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/module-ui.ts

@@ -0,0 +1,133 @@
+import type { ModuleUiHostContext } from "./host-context.js";
+
+export type Awaitable<Value> = Value | PromiseLike<Value>;
+
+/**
+ * Released by a host when the module UI should be torn down. A module that acquires anything during
+ * `mount` — a framework root, a subscription, a timer, an event listener — must return one of these
+ * and release that work here, exactly as a backend module releases resources in its `stop` hook
+ * (ADR 0006). Returning nothing declares that the mount acquired nothing to release.
+ */
+export type ModuleUiUnmount = () => Awaitable<void>;
+
+/**
+ * What a module's compiled `entrypoints.ui` artifact default-exports (ADR 0021, ADR 0022).
+ *
+ * `id` and `version` are build-artifact identity markers, mirroring `ModuleRuntimeDefinition`
+ * exactly (ADR 0006): they let a host prove the UI bundle it imported was built from the module it
+ * thinks it is, and catch a stale artifact. They do not duplicate anything else from the manifest.
+ *
+ * `mount` is intentionally the whole behavioral contract. The host supplies a container element and
+ * the host context; what happens inside is the module's business. React is the supported way to
+ * write that (ADR 0022), but React appears nowhere in this type — the contract is a mount function,
+ * so a module's internal framework choice, and a host's, can each change without renegotiating the
+ * platform boundary.
+ */
+export interface ModuleUiDefinition {
+  readonly id: string;
+  readonly version: string;
+  readonly mount: (
+    container: Element,
+    context: ModuleUiHostContext,
+  ) => Awaitable<ModuleUiUnmount | void>;
+}
+
+export type ModuleUiContractErrorCode =
+  | "MODULE_UI_EXPORT_MISSING"
+  | "MODULE_UI_DEFINITION_INVALID"
+  | "MODULE_UI_IDENTITY_MISMATCH";
+
+const errorMessages: Readonly<Record<ModuleUiContractErrorCode, string>> = Object.freeze({
+  MODULE_UI_EXPORT_MISSING:
+    "A module UI entrypoint must have a default export produced by defineModuleUi.",
+  MODULE_UI_DEFINITION_INVALID:
+    "A module UI definition must declare a non-empty id and version and a mount function, and nothing else.",
+  MODULE_UI_IDENTITY_MISMATCH:
+    "The module UI artifact's id and version do not match the module it was loaded for.",
+});
+
+/**
+ * Carries a stable code and a fixed message, never the offending value, the artifact URL, a
+ * filesystem path, or a caught cause — matching the sanitization rule every other Ekklesia error
+ * boundary follows.
+ */
+export class ModuleUiContractError extends Error {
+  readonly code: ModuleUiContractErrorCode;
+
+  constructor(code: ModuleUiContractErrorCode) {
+    super(errorMessages[code]);
+    this.name = "ModuleUiContractError";
+    this.code = code;
+    this.stack = `${this.name}: ${this.message}`;
+    Object.freeze(this);
+  }
+}
+
+const definitionKeys = new Set(["id", "mount", "version"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Structural check only. The identity a definition claims is verified against the manifest by
+ * {@link parseModuleUiExport}, so this never needs a copy of Core's module-id or semantic-version
+ * grammar — there is exactly one place each of those is defined, and it is not here.
+ */
+export function isModuleUiDefinition(value: unknown): value is ModuleUiDefinition {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (Object.keys(value).some((key) => !definitionKeys.has(key))) {
+    return false;
+  }
+  return (
+    isNonEmptyString(value.id) &&
+    isNonEmptyString(value.version) &&
+    typeof value.mount === "function"
+  );
+}
+
+export function parseModuleUiDefinition(value: unknown): ModuleUiDefinition {
+  if (!isModuleUiDefinition(value)) {
+    throw new ModuleUiContractError("MODULE_UI_DEFINITION_INVALID");
+  }
+  return Object.freeze({
+    id: value.id,
+    mount: value.mount,
+    version: value.version,
+  });
+}
+
+/** The identity a host already knows from the module's validated manifest. */
+export interface ModuleUiIdentity {
+  readonly id: string;
+  readonly version: string;
+}
+
+/**
+ * The one entry point a host uses after importing a module's UI artifact.
+ *
+ * Deliberately does **not** import anything itself. Each host performs its own dynamic import — a
+ * browser host from a served URL, a test host from a file URL — and passes the resulting module
+ * namespace here. That keeps this package free of any loader, bundler, or URL assumption, and keeps
+ * Core out of the business of evaluating browser code entirely: module discovery still only
+ * resolves and validates the `entrypoints.ui` path and never executes it (ADR 0021).
+ */
+export function parseModuleUiExport(
+  namespace: unknown,
+  expected: ModuleUiIdentity,
+): ModuleUiDefinition {
+  if (!isRecord(namespace) || !("default" in namespace)) {
+    throw new ModuleUiContractError("MODULE_UI_EXPORT_MISSING");
+  }
+  const definition = parseModuleUiDefinition(namespace.default);
+  if (definition.id !== expected.id || definition.version !== expected.version) {
+    throw new ModuleUiContractError("MODULE_UI_IDENTITY_MISMATCH");
+  }
+  return definition;
+}