ekklesiaandClaude Opus 5
07835b7b56
ADR 0023 refused stylesheet imports for a good reason: esbuild would emit a
`.css` sidecar beside the artifact, nothing would declare it, no host would
fetch it, and it would work in a local test and silently do nothing in a real
host. Inline style objects were the whole story. They cannot express
`:hover`, `:focus-visible`, `:disabled`, `@media`, or `@keyframes` — so an
accessible focus treatment was not expressible, and the shared elements added
in the previous commit are built from real CSS for exactly that reason.
Compile the stylesheet into the artifact instead of beside it. A module
imports plain `.css`; the canonical builder resolves local `@import`s through
a nested bundle and turns each file into its compiled text, which the author
declares as `defineModuleUi({ styles })`. One declared file still contains
everything: nothing extra to publish, nothing to fetch, and no way for CSS to
become an asset nobody serves. The build additionally fails if a CSS output
ever appears beside an artifact, so a future loader change cannot bring the
sidecar back. Two rules are enforced with their own codes: a module stylesheet
may reference `--ekklesia-*` and never declare one, and every `@import` must
resolve locally or the artifact would fetch styles at run time. Plain `.css`
only; other dialects are a toolchain decision needing their own ADR.
Then make the isolation real. The generic loader mounts every browser artifact
— primary, display, and later a contributed renderer — inside an open Shadow
DOM root it creates, installs the artifact's stylesheet there, and hands the
artifact an element inside it. Shadow DOM is the one mechanism a browser
actually enforces; a class prefix or a "scope your selectors" instruction is a
convention one mistake defeats, and the failure mode is a module silently
restyling the Dashboard. It applies unconditionally, including to artifacts
with no stylesheet, because a conditional boundary is one a module can fall
out of by editing a source file. Both wrappers are `display: contents` through
base rules installed before the artifact's own, so layout is unchanged and a
full-viewport display can still override `:host`. Unmount removes the whole
root in a `finally`, so a cleanup that throws cannot leave styles behind, and
remounting cannot accumulate a second copy.
This is a correctness boundary for styles and is not described as a sandbox:
the root is `open` precisely because module code is trusted, same-realm code
that could reach `document` anyway.
An artifact's DOM is no longer a direct child of the host's element, so the
mount ABI is versioned explicitly. `defineModuleUi` stamps
`MODULE_UI_ABI_VERSION` so it can never drift from the SDK the artifact
compiled against, and a version-1 artifact fails with its own code — "rebuild
your module", not a typo hunt. No dual acceptance, matching every manifest
cutover here. Migration is one `pnpm build`.
`pnpm boundaries` allows `.css` only under `src/ui/` and `src/display/`: a
stylesheet anywhere else in a module is the undeclared sidecar again, just
relocated.
Co-Authored-By: Claude Opus 5 <[email protected]>
78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# Contributing
|
|
|
|
Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency
|
|
boundaries described in [repository-boundaries.md](docs/architecture/repository-boundaries.md).
|
|
|
|
Before opening a change, run:
|
|
|
|
```bash
|
|
pnpm verify
|
|
```
|
|
|
|
Migration-runner changes and changes to identity/authentication or the API's session transport also
|
|
require the disposable live PostgreSQL suite:
|
|
|
|
```bash
|
|
pnpm test:migrations:integration
|
|
```
|
|
|
|
See the [testing guide](docs/development/testing.md) for the distinction between unit and live
|
|
evidence and for credential-safe troubleshooting.
|
|
|
|
When adding or changing a module manifest, also run `pnpm modules:validate` directly for focused,
|
|
path-aware discovery errors. It is included in `pnpm verify`.
|
|
|
|
If Docker is available, also validate the development infrastructure:
|
|
|
|
```bash
|
|
pnpm infrastructure:config
|
|
```
|
|
|
|
## Package rules
|
|
|
|
- Use strict TypeScript for production packages.
|
|
- Expose supported entry points through package `exports`; do not import another package's
|
|
private source paths.
|
|
- Use `workspace:` ranges for internal package dependencies.
|
|
- Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may
|
|
contain `.tsx` and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`, and may author
|
|
plain `.css` inside a browser-artifact source root (ADR 0040). Every other UI framework, `.jsx`,
|
|
other stylesheet dialects, and other presentation formats remain rejected by `pnpm boundaries`. Primary and display sources live at the exact `src/ui/index.tsx` and
|
|
`src/display/index.tsx` conventions; one `pnpm build` invocation atomically compiles every role
|
|
the v6 manifest declares via `@ekklesia/module-ui-build` (ADR 0023/0033). Module authors write no
|
|
bundler configuration. A module's stylesheets are compiled into its declared artifact as text and
|
|
installed by the host into that artifact's own Shadow DOM root, so module styles cannot leak into
|
|
the Dashboard or another module (ADR 0040). Both roles use the same UI SDK context with no
|
|
presentation-mode flag, and the same versioned mount ABI.
|
|
- A module may also consume exactly two shared design packages — `@ekklesia/design-tokens` and
|
|
`@ekklesia/ui` (ADR 0039) — so two modules' screens look like one product. That is a named
|
|
allowlist: every other shared role (`api-client`, `auth-client`, `surface-sdk`, `module-ui-host`)
|
|
stays rejected inside a module. Reference registered semantic tokens; never define an
|
|
`--ekklesia-*` custom property of your own.
|
|
- Module UI reaches its host only through `@ekklesia/module-ui-sdk` — never
|
|
`@ekklesia/module-ui-host`, which is the host-side loader — and asks the host for its own
|
|
API by relative path — never by constructing `/api/v1/modules/<id>/...`, which is Ekklesia's
|
|
private deployment detail and would break standalone hosting.
|
|
- The containing application shell, navigation, global theme, and platform policy belong to Core and
|
|
the host application, never to a module. Ekklesia's own shell is `surfaces/shell`; it discovers
|
|
primary module UIs through `GET /api/v1/dashboard/navigation`, resolves a dedicated display
|
|
through `GET /api/v1/module-displays/<module-id>`, mounts both with
|
|
`@ekklesia/module-ui-host`, and statically imports no module (ADR 0026/0033).
|
|
- Dedicated displays are module-owned renderers mounted by a separate full-viewport surface at
|
|
`/display/<module-id>`, never Dashboard UI with hidden chrome. Its page and descriptor require the
|
|
module-owned, non-public permission declared by `entrypoints.display`; artifact bytes remain
|
|
anonymous trusted code. Public/device identity, display inventory, and variants are deferred.
|
|
- Dashboard groups are presentation configuration, never module structure. Do not add a parent
|
|
module, child module, owning module, or group-derived dependency: real module relationships are
|
|
the dependency contract's job alone, and grouping must never influence discovery, dependency
|
|
ordering, startup, or authorization (ADR 0027). A module declares its display name
|
|
(`manifest.name`); the Dashboard owns where it appears.
|
|
- A surface is browser code. It may depend on browser-safe shared roles only — never
|
|
`@ekklesia/contracts` or `@ekklesia/module-sdk`, whose type graphs pull Node's globals into the
|
|
browser — and it reaches the server over HTTP.
|
|
- Add or update tests when changing a contract or architectural rule.
|
|
- Record major architectural changes in an ADR rather than burying them in an implementation.
|
|
|
|
Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually
|
|
maintained feature-module registry; discovery starts from validated `ekklesia.module.json` files.
|