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

docs/module-development/README.md

@@ -190,33 +190,118 @@ and be compiled ESM JavaScript ending in `.js` or `.mjs`. A `./src/ui/index.ts`
 discovery — the platform never imports source TypeScript, and a UI artifact is a build output like
 any other.
 
+### What the artifact must export
+
+The artifact default-exports one definition, built with `defineModuleUi` from
+`@ekklesia/module-ui-sdk` (ADR 0022):
+
+```tsx
+import { defineModuleUi } from "@ekklesia/module-ui-sdk";
+import { createRoot } from "react-dom/client";
+import { Editor } from "./editor.js";
+
+export default defineModuleUi({
+  id: "announcements",
+  version: "0.1.0",
+  mount(container, context) {
+    const root = createRoot(container);
+    root.render(<Editor context={context} />);
+    return () => root.unmount();
+  },
+});
+```
+
+`id` and `version` are build-artifact identity markers and must match your manifest, exactly like the
+ones in `defineModuleRuntime`. A host verifies both against the manifest it already validated, so a
+stale UI bundle is caught rather than mounted.
+
+`mount` receives a container element and the host context, and returns an unmount function or
+nothing. If your mount acquires anything — a React root, a subscription, a timer, an event listener —
+return an unmount and release it there, the same discipline your `stop` hook follows.
+
+React is the supported way to write module UI. It is deliberately **not** part of the contract: the
+platform hands you an element and a context, so your framework choice and the host's stay
+independent.
+
+### What the host gives you
+
+`mount` receives exactly four members, and nothing else is available:
+
+| Member | What it is |
+| --- | --- |
+| `moduleId` | Your module's id, so you never re-derive it from a URL |
+| `api` | `request(path, init)` against **your own** module API — see below |
+| `principal` | Who is viewing (`anonymous` or `authenticated`), for presentation |
+| `permissions` | `has(permissionId)` — a presentation hint, never a security check |
+
+Navigation, host theme and design tokens, module configuration, organization context, and
+diagnostics reporting are **not** in the contract yet. They need designs that do not exist, and a
+speculative field frozen into a public contract is harder to remove than to add.
+
+### Never build your own API URL
+
+Ask the host for a path relative to your own module's API root:
+
+```ts
+const response = await context.api.request("posts");
+```
+
+Do **not** write `/api/v1/modules/announcements/posts`. That prefix is Ekklesia's private deployment
+detail. A standalone host serving only your module may expose the same routes at `/api`, at a
+different origin, or behind a proxy — and a module that builds the URL itself silently stops being
+hostable anywhere but Ekklesia. The host resolves the path and owns credentials, base URL, and
+platform headers; your UI never sees a session token.
+
+`request` returns a `Response`, the same Fetch vocabulary your backend routes already speak.
+
+### Client-side permission checks are UX, not security
+
+`context.permissions.has("announcements.posts.publish")` tells you what the host believes, so you can
+hide an action or disable a control. **It is not a security boundary.** Server-side authorization is
+the only authority: your routes are enforced by Core's `requirePermission` middleware regardless of
+what any browser decided. Checking `has()` and then calling your API is still fully authorized
+server-side; skipping the check is still denied. The point is that a user does not see a button that
+would fail.
+
+### Your UI is trusted code in the host's page
+
+Module UI runs in the same browser JavaScript realm as the host shell. There is no iframe, no
+sandbox, and no capability confinement — your UI can reach the host page and any global the browser
+exposes. This matches the backend model: installing a module already means running its code in the
+API process. Write module UI as trusted first-party code, because that is what it is. See
+[Security model and deployment trust boundaries](../development/security.md).
+
+### What you may and may not use today
+
+`pnpm boundaries` still enforces `modules-do-not-own-ui`, narrowed precisely (ADR 0022):
+
+| Allowed in a module | Still rejected |
+| --- | --- |
+| `.tsx` source | `.jsx` (strict TypeScript only), `.css`, `.vue`, `.svelte`, `.astro`, `.mdx`, `.svg`, `.html` |
+| `react`, `react-dom` | Every other framework, plus `react-router-dom` (routing is the host's), `react-native`, `@vitejs/plugin-react` |
+| `@ekklesia/module-ui-sdk` | `@ekklesia/ui` and other shared UI-role packages |
+
+Layer rules are unchanged: module UI source may not import Core, an app, a surface, a builder, or
+another module. An unsupported framework aliased behind an allowed name — `"react": "npm:vue@3"` —
+is resolved and rejected by its real target.
+
+> **Not yet buildable end to end.** The pipeline that compiles a module's `.tsx` into the compiled
+> `entrypoints.ui` artifact is not designed: `browser.json` uses `"jsx": "preserve"`, which needs a
+> bundler, and `@vitejs/plugin-react` is still denied. Module styling is unresolved for the same
+> reason, which is why `.css` stays rejected. No host mounts a module UI yet either. The contract
+> above is stable and tested; shipping a module UI is not yet possible end to end.
+
 ### What this does and does not do today
 
 Discovery parses the manifest as inert JSON, resolves the `ui` path, validates it, and records it on
-the discovered module. That is all. **Nothing in this repository imports, evaluates, mounts, or
-renders a UI entrypoint** — a UI artifact that throws on evaluation still discovers successfully,
-because it is never evaluated. The field follows the same established pattern as `entrypoints.jobs`,
-which has been declared and validated since ADR 0006 with no runtime consumer.
-
-Declaring `ui` therefore has no observable runtime effect yet. It exists so the host shell, the UI
-runtime, and a future standalone host have a fixed, tested contract to build against.
-
-### The authoring constraint you will hit
-
-`pnpm boundaries` enforces `modules-do-not-own-ui`, which rejects UI *source* extensions (`.tsx`,
-`.vue`, `.svelte`, `.css`, `.svg`, and others) and UI *framework dependencies* (React, Vue, Svelte,
-Tailwind, and others) inside a module package. **That rule is still enforced.** ADR 0021 changed the
-architectural direction — a module may own UI — but the authoring model for module UI, including
-which parts of that deny list are relaxed and what replaces them, is a later Phase 6 decision that
-has not been made.
-
-In practice this means a module can declare `entrypoints.ui` today only for a framework-neutral
-compiled artifact authored in plain `.ts`. Do not add a UI framework dependency to a module package
-expecting it to pass; it will not, and that is deliberate rather than an oversight.
+the discovered module. That is all. **Nothing in Core imports, evaluates, mounts, or renders a UI
+entrypoint** — a UI artifact that throws on evaluation still discovers successfully, because it is
+never evaluated. Hosts perform their own dynamic import and then validate the result with
+`parseModuleUiExport`; Core never loads browser code.
 
 ### What a module UI will never own
 
-Whatever authoring model is chosen, a module UI consumes platform policy and never redefines it.
+A module UI consumes platform policy and never redefines it.
 Authentication and session establishment, authorization enforcement, organization/platform context,
 the containing application shell, top-level routing and mount boundaries, the platform navigation
 container, the global theme and design-token contract, platform error boundaries, and