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/tests/browser-safety.test.ts

@@ -0,0 +1,65 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const sourceDirectory = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+
+async function sourceFiles(): Promise<string[]> {
+  const entries = await readdir(sourceDirectory);
+  return entries.filter((entry) => entry.endsWith(".ts")).sort();
+}
+
+/**
+ * This package is bundled into a browser. `@ekklesia/module-sdk` re-exports all of
+ * `@ekklesia/contracts`, which pulls Zod, Drizzle, and semver behind one barrel export, so a single
+ * value import from a backend package here would drag that whole graph into every module UI bundle
+ * (ADR 0022). The dependency on `@ekklesia/contracts` is deliberately type-only and must stay that
+ * way; `import type` is erased at build time, a plain `import` is not.
+ */
+describe("module UI SDK stays browser-safe", () => {
+  it("imports nothing from another workspace package at runtime", async () => {
+    for (const file of await sourceFiles()) {
+      const source = await readFile(path.join(sourceDirectory, file), "utf8");
+      const workspaceImports = [
+        ...source.matchAll(/^import\s+(.*?)\s+from\s+"(@ekklesia\/[^"]+)"/gmu),
+      ];
+
+      for (const [, clause, specifier] of workspaceImports) {
+        expect(
+          clause?.startsWith("type "),
+          `${file} imports ${specifier} at runtime; it must be a type-only import`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("declares no runtime dependency other than the type-only contracts package", async () => {
+    const manifestPath = path.join(sourceDirectory, "..", "package.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
+      dependencies?: Record<string, string>;
+    };
+
+    expect(Object.keys(manifest.dependencies ?? {})).toEqual(["@ekklesia/contracts"]);
+  });
+
+  it("does not depend on a UI framework, so the contract stays framework-neutral", async () => {
+    const manifestPath = path.join(sourceDirectory, "..", "package.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      peerDependencies?: Record<string, string>;
+    };
+    const declared = [
+      ...Object.keys(manifest.dependencies ?? {}),
+      ...Object.keys(manifest.devDependencies ?? {}),
+      ...Object.keys(manifest.peerDependencies ?? {}),
+    ];
+
+    // React is the supported way to *author* module UI. It is deliberately absent from the host
+    // contract, so a host never has to match a module's rendering library.
+    for (const framework of ["react", "react-dom", "vue", "svelte", "preact"]) {
+      expect(declared).not.toContain(framework);
+    }
+  });
+});