feat: define the module UI authoring model and host contract #16
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Zayin/Ekklesia#16
Reference in New Issue
Block a user
ADR 0021 established that a module may own UI and added a statically
validated, never-executed
entrypoints.uipath, but deliberately leftfive questions open: what the artifact exports, what a host provides,
how one artifact runs under both Ekklesia and a standalone host, what
the browser-side trust model is, and how module UI avoids being welded
to a Dashboard that does not exist. This answers them.
React and TypeScript are the supported module UI authoring model. The
repository already leaned this way:
packages/typescript-configships abrowser.jsonpreset and areact-native.jsonpreset with"jsx": "react-jsx", and ADR 0002 names browser and React Nativeconfigurations. One framework is supported; every other stays rejected.
React is deliberately not part of the contract. A module's compiled
artifact default-exports
defineModuleUi({ id, version, mount }), andmount(container, context)takes a DOM element and returns an unmountfunction.
idandversionare build-artifact identity markers a hostverifies against the manifest, mirroring
defineModuleRuntimeexactly.A host needs an element and a context, never a matching rendering
library, so a module's framework, a host's framework, and the platform
boundary between them stay independent.
The contract lives in a new
@ekklesia/module-ui-sdkrather than in@ekklesia/module-sdk, for a concrete reason: that package re-exportsall of
@ekklesia/contracts, so routing module UI through it would dragZod, Drizzle, and semver into every browser bundle. The new package has
no runtime dependencies, and its one dependency on contracts is
type-only — the emitted
host-context.jsisexport {};, and a testpins that so it cannot regress.
The host context is four members:
moduleId,api,principal, andpermissions. Navigation, theme, module configuration, organizationcontext, and diagnostics are deliberately absent; each needs a design
that does not exist. Module UI reaches its backend through
api.request(path)with a path relative to its own API root and neverconstructs
/api/v1/modules/<id>/..., which is Ekklesia's privatedeployment detail — a module that builds that URL is silently unhostable
anywhere else. One fixture artifact is mounted under two hosts with
different origins and URL shapes to prove it.
Client-side permission hints are presentation only, and both the docs
and a test say so plainly: a denied hint does not stop the module from
calling its API, because server-side
requirePermissionis the onlyauthority. Module UI is trusted code in the host's own browser realm —
no iframe, no sandbox — which matches the backend model rather than
overstating it, since a module's server half already holds the API's
database authority.
The boundary guard is narrowed precisely, not removed:
.tsx,react,and
react-domare un-denied and modules may depend on the newmodule-ui-sdkrole..jsx,.css, every other framework,react-router-dom,react-native, and@vitejs/plugin-reactstaydenied, layer rules are untouched, and an unsupported framework aliased
behind an allowed name (
"react": "npm:vue@3") is resolved and rejectedby its real target. Fixtures prove each case, including that module UI
source still cannot import Core.
Core, apps/api, and the manifest contract are untouched. Discovery still
validates the
entrypoints.uipath and never evaluates it; hostsperform their own dynamic import and validate the result with
parseModuleUiExport. No Dashboard shell, UI runtime, navigation,grouping, standalone host, build or styling pipeline, installer,
hot-loading, or feature module is added.
Co-Authored-By: Claude Opus 5 [email protected]
ADR 0021 established that a module may own UI and added a statically validated, never-executed `entrypoints.ui` path, but deliberately left five questions open: what the artifact exports, what a host provides, how one artifact runs under both Ekklesia and a standalone host, what the browser-side trust model is, and how module UI avoids being welded to a Dashboard that does not exist. This answers them. React and TypeScript are the supported module UI authoring model. The repository already leaned this way: `packages/typescript-config` ships a `browser.json` preset and a `react-native.json` preset with `"jsx": "react-jsx"`, and ADR 0002 names browser and React Native configurations. One framework is supported; every other stays rejected. React is deliberately not part of the contract. A module's compiled artifact default-exports `defineModuleUi({ id, version, mount })`, and `mount(container, context)` takes a DOM element and returns an unmount function. `id` and `version` are build-artifact identity markers a host verifies against the manifest, mirroring `defineModuleRuntime` exactly. A host needs an element and a context, never a matching rendering library, so a module's framework, a host's framework, and the platform boundary between them stay independent. The contract lives in a new `@ekklesia/module-ui-sdk` rather than in `@ekklesia/module-sdk`, for a concrete reason: that package re-exports all of `@ekklesia/contracts`, so routing module UI through it would drag Zod, Drizzle, and semver into every browser bundle. The new package has no runtime dependencies, and its one dependency on contracts is type-only — the emitted `host-context.js` is `export {};`, and a test pins that so it cannot regress. The host context is four members: `moduleId`, `api`, `principal`, and `permissions`. Navigation, theme, module configuration, organization context, and diagnostics are deliberately absent; each needs a design that does not exist. Module UI reaches its backend through `api.request(path)` with a path relative to its own API root and never constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private deployment detail — a module that builds that URL is silently unhostable anywhere else. One fixture artifact is mounted under two hosts with different origins and URL shapes to prove it. Client-side permission hints are presentation only, and both the docs and a test say so plainly: a denied hint does not stop the module from calling its API, because server-side `requirePermission` is the only authority. Module UI is trusted code in the host's own browser realm — no iframe, no sandbox — which matches the backend model rather than overstating it, since a module's server half already holds the API's database authority. The boundary guard is narrowed precisely, not removed: `.tsx`, `react`, and `react-dom` are un-denied and modules may depend on the new `module-ui-sdk` role. `.jsx`, `.css`, every other framework, `react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay denied, layer rules are untouched, and an unsupported framework aliased behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected by its real target. Fixtures prove each case, including that module UI source still cannot import Core. Core, apps/api, and the manifest contract are untouched. Discovery still validates the `entrypoints.ui` path and never evaluates it; hosts perform their own dynamic import and validate the result with `parseModuleUiExport`. No Dashboard shell, UI runtime, navigation, grouping, standalone host, build or styling pipeline, installer, hot-loading, or feature module is added. Co-Authored-By: Claude Opus 5 <[email protected]>