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]>
Ekklesia module template
This is the smallest supported Ekklesia module product. It proves the static manifest,
compiled runtime and schema entrypoints, capability registration, a module-owned Drizzle table, a
generated module-owned migration, logical storage-bucket declarations, and one permissioned HTTP
route (GET /records, declared in register) that reads that table through
context.services.database — the platform-provided ModuleDatabase facade, never a
module-constructed Drizzle instance or a raw pg client. Migration execution and storage
provisioning are intentionally not included.
It also ships two independently optional React roles: a primary/management UI at src/ui/index.tsx
and a full-viewport display at src/display/index.tsx. One invocation of pnpm build compiles each
declared role to the exact artifact in entrypoints.ui and entrypoints.display.artifact
(ADR 0023). Both default-export
the same role-neutral defineModuleUi({ id, version, mount }) ABI and receive the same
ModuleUiHostContext; there is deliberately no mode flag. The manifest entrypoint and the host route
choose the role.
Either role can be omitted independently. To remove only the display example, delete src/display/
and entrypoints.display (and remove example.display.view if nothing else uses it). To keep the
module backend-only, also delete src/ui/, tsconfig.ui.json, tsconfig.ui-test.json,
tests/module-ui.test.ts, the ui entrypoint, and the React/module-UI dependencies. The builder
succeeds with an empty artifact list when neither role is declared.
tests/module-ui.test.ts builds both artifacts from source, validates them with
parseModuleUiExport, mounts each into a real DOM, and unmounts it. Ekklesia mounts the primary UI
inside its Dashboard shell and serves the display without Dashboard chrome at the stable
/display/example page. See
Declaring UI entrypoints.
To create a module inside this repository:
- Copy this directory to
modules/<module-id>. - Rename the package in
package.jsonand removeprivatewhen it is ready for publication. - Update the ID, name, version, namespaces, compatibility ranges, and bucket requests in
ekklesia.module.json. - Keep the manifest capability versions and dependency ranges aligned with the contracts the module actually implements and consumes.
- Replace
src/server/index.tswith backend behavior only. ItsdefineModuleRuntimeID and version must match the manifest; do not duplicate the rest of the manifest in TypeScript. Declare HTTP routes only inregister, against a permission the manifest already declares;start,stop, and every route handler — neverregister— receivecontext.services.database, a typedModuleDatabaseview over the platform's one PostgreSQL pool. - Replace the pure Drizzle declarations in
src/schema/tables.tsand keep its table prefix aligned with the module ID. Keep thedefineModuleSchemaownership wrapper insrc/schema/index.tsaligned too, and never import another module's schema. - Update
drizzle.config.ts, generate forward migrations withpnpm migration:generate --name=lowercase_namefrom the module directory, and review the SQL. Keep each generated tag indrizzle/meta/_ekklesia.json, classify it asnoneorapproval-required, and change that file'smoduleIdwhen renaming the template. - Run
pnpm install,pnpm build,pnpm modules:validate,pnpm migrations:validate, andpnpm verifyfrom the repository root. The declared production entrypoint is the compileddist/server/index.js, not source TypeScript; the schema entrypoint is likewise compiled todist/schema/index.js.
The module owns its feature screens and display renderer. Do not add platform navigation, the
containing shell, global theme, authentication screens, or top-level routing; those belong to
surfaces and Core. A module UI asks its host for relative API paths and realtime state, and never
hardcodes Ekklesia routes. The display permission is enforced by the host before it serves the page
or descriptor; context.permissions remains a presentation-only hint.
Keep imports side-effect-free, register capabilities in register, acquire resources in start,
and release them in stop. Never construct a Drizzle instance, read DATABASE_URL, or reach for a
raw pg client — context.services.database is the only supported way to query this module's own
tables, and it is never available during register.
The migration directory uses the pinned stable Drizzle Kit 0.31.10 PostgreSQL journal and
snapshot format. Migrations are forward-only and may modify only this module's objects. Offline
validation treats SQL as opaque bytes, calculates SHA-256 from the exact contents, and never opens a
database or executes SQL. Destructive declarations are review metadata, not automatic SQL
classification or approval.