feat: define the module UI authoring model and host contract

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]>

packages/module-ui-sdk/src/host-context.ts

@@ -0,0 +1,75 @@
+import type { EkklesiaPrincipal } from "@ekklesia/contracts";
+
+/**
+ * Everything a host hands a module's UI, and the complete list of what module UI may assume exists.
+ *
+ * This is deliberately the smallest set that proves the architecture rather than everything a real
+ * screen will eventually want. Navigation, host theme and design tokens, module configuration,
+ * organization/platform context, and diagnostics reporting are **not** here yet: each needs a design
+ * that does not exist, and a speculative field frozen into a public contract is harder to remove
+ * than to add. See ADR 0022.
+ *
+ * Nothing in this object is an Ekklesia implementation. Every member is satisfiable by a standalone
+ * host that never runs Core, which is what makes one module UI hostable by both.
+ */
+export interface ModuleUiHostContext {
+  /** The module this UI belongs to, as the host knows it. Supplied so a module never has to hardcode
+   * or re-derive its own identity from a URL. */
+  readonly moduleId: string;
+  /** The only supported way for module UI to reach its own backend. See {@link ModuleUiApiClient}. */
+  readonly api: ModuleUiApiClient;
+  /** Who is viewing, for presentation decisions only. Reuses Core's own principal type so a host and
+   * a module UI cannot disagree about its shape. */
+  readonly principal: EkklesiaPrincipal;
+  /** Presentation-only permission hints. See {@link ModuleUiPermissions}. */
+  readonly permissions: ModuleUiPermissions;
+}
+
+/**
+ * A module UI's access to its own module's HTTP API, addressed **relative to the module's own API
+ * root** — never as an absolute path.
+ *
+ * This is the single most important portability rule in this contract. Ekklesia mounts module routes
+ * under `/api/v1/modules/<module-id>` (`apps/api/src/module-http-routes.ts`), but that prefix is
+ * Ekklesia's private deployment detail. A standalone host serving one module may expose the same
+ * routes at `/api`, at a different origin entirely, or through a proxy. A module UI that builds
+ * `/api/v1/modules/announcements/posts` itself is silently welded to Ekklesia and can never be
+ * hosted anywhere else.
+ *
+ * So the module asks for `posts`, and the host resolves it. `Request`/`Response` are the same Fetch
+ * vocabulary a module's backend routes already speak (ADR 0015), so one module speaks one HTTP
+ * shape on both sides of the wire.
+ *
+ * A host is responsible for credentials, base URL, and any platform headers. A module UI neither
+ * supplies nor sees a session token.
+ */
+export interface ModuleUiApiClient {
+  /**
+   * @param path A path relative to this module's own API root, with or without a leading `/`.
+   *   Must not be an absolute URL: a host is free to reject one rather than silently allowing a
+   *   module UI to address something other than its own backend.
+   */
+  request(path: string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Presentation-only permission hints.
+ *
+ * **This is not a security boundary and must never be used as one.** A module UI may use it to hide
+ * an action, disable a control, or choose which empty state to render. Server-side authorization
+ * remains the only authority: every module route is enforced by Core's `requirePermission`
+ * middleware against the composed platform permission registry (ADR 0013/0014), and that
+ * enforcement is unchanged by, and unaware of, anything a browser believes.
+ *
+ * A module UI that "checks" a permission here and then calls its API is still fully authorized
+ * server-side. A module UI that skips the check and calls anyway is still denied server-side. The
+ * value of this interface is that the user does not see a button that would fail.
+ *
+ * `permissionId` is a plain `string`, deliberately, and not the branded `PermissionId` Core uses:
+ * branding would require a module UI to run Zod parsing in the browser to produce a value for a
+ * call that decides nothing security-relevant. The branded type remains the server-side type.
+ */
+export interface ModuleUiPermissions {
+  /** Whether the host believes the current principal holds this permission. A hint, not a grant. */
+  has(permissionId: string): boolean;
+}