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

tests/boundaries.test.ts

@@ -47,6 +47,8 @@ describe("repository dependency boundaries", () => {
     ["package-cycle", "no-circular-package-dependencies"],
     ["module-has-ui", "modules-do-not-own-ui"],
     ["module-ui-framework", "modules-do-not-own-ui"],
+    ["module-ui-aliased-framework", "modules-do-not-own-ui"],
+    ["module-ui-imports-core", "modules-use-public-platform-contracts"],
     ["module-imports-ui-package", "modules-use-public-platform-contracts"],
     ["cross-package-relative", "workspace-imports-use-public-exports"],
     ["cycle", "no-circular-source-dependencies"],
@@ -55,18 +57,72 @@ describe("repository dependency boundaries", () => {
     expect(result.violations.map((violation) => violation.rule)).toContain(expectedRule);
   });
 
-  it("rejects component, stylesheet, and case-insensitive view files inside a module", async () => {
+  it("rejects stylesheet and case-insensitive view files inside a module, but not TSX", async () => {
     const result = await checkBoundaries(path.join(fixtures, "module-has-ui"));
-    expect(
-      result.violations.filter((violation) => violation.rule === "modules-do-not-own-ui"),
-    ).toHaveLength(3);
+    const uiViolations = result.violations.filter(
+      (violation) => violation.rule === "modules-do-not-own-ui",
+    );
+
+    expect(uiViolations).toHaveLength(2);
+    expect(uiViolations.map((violation) => violation.from)).toEqual(
+      expect.arrayContaining([
+        "modules/calendar/src/calendar.css",
+        "modules/calendar/src/view.ASTRO",
+      ]),
+    );
+    // React is the supported module UI authoring model (ADR 0022), so a module's own `.tsx` is
+    // legitimate source and must no longer be reported.
+    expect(uiViolations.map((violation) => violation.from)).not.toContain(
+      "modules/calendar/src/calendar.tsx",
+    );
   });
 
-  it("rejects UI framework dependencies, imports, and view formats inside a module", async () => {
+  it("rejects unsupported UI frameworks, their imports, and view formats inside a module", async () => {
     const result = await checkBoundaries(path.join(fixtures, "module-ui-framework"));
-    expect(
-      result.violations.filter((violation) => violation.rule === "modules-do-not-own-ui"),
-    ).toHaveLength(4);
+    const uiViolations = result.violations.filter(
+      (violation) => violation.rule === "modules-do-not-own-ui",
+    );
+
+    expect(uiViolations).toHaveLength(3);
+    expect(uiViolations.map((violation) => violation.message)).toEqual(
+      expect.arrayContaining([
+        "Module package depends on UI framework preact.",
+        "Module source imports UI framework preact.",
+      ]),
+    );
+    // The fixture also aliases `compat` to react, which is now the supported framework and is
+    // therefore no longer a violation.
+    expect(uiViolations.map((violation) => violation.message).join(" ")).not.toContain("compat");
+  });
+
+  it("still rejects module UI source that reaches into Core internals", async () => {
+    // Allowing `.tsx` inside a module changed which *formats* a module may contain. It did not
+    // change which layers a module may import: module UI is subject to the identical layer rules
+    // as module backend source.
+    const result = await checkBoundaries(path.join(fixtures, "module-ui-imports-core"));
+
+    expect(result.violations).toEqual([
+      {
+        from: "modules/announcements/src/ui/editor.tsx",
+        message: "module code may not import core code directly.",
+        rule: "modules-use-public-platform-contracts",
+        to: "core/src/index.ts",
+      },
+    ]);
+  });
+
+  it("accepts a module that owns React UI through the public module UI SDK", async () => {
+    const result = await checkBoundaries(path.join(fixtures, "module-owns-react-ui"));
+
+    expect(result.violations).toEqual([]);
+  });
+
+  it("rejects an unsupported framework aliased behind the supported one", async () => {
+    const result = await checkBoundaries(path.join(fixtures, "module-ui-aliased-framework"));
+
+    expect(result.violations.map((violation) => violation.message)).toEqual([
+      "Module package depends on UI framework vue aliased as react.",
+    ]);
   });
 
   it("requires workspace: ranges in every dependency field", async () => {

tests/fixtures/boundaries/module-owns-react-ui/modules/announcements/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@ekklesia/module-announcements",
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {
+    "@ekklesia/module-ui-sdk": "workspace:*",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "module"
+  }
+}

tests/fixtures/boundaries/module-owns-react-ui/modules/announcements/src/index.ts

@@ -0,0 +1 @@
+export const moduleId = "announcements";

tests/fixtures/boundaries/module-owns-react-ui/modules/announcements/src/ui/editor.tsx

@@ -0,0 +1,12 @@
+import { defineModuleUi } from "@ekklesia/module-ui-sdk";
+import { createRoot } from "react-dom/client";
+
+export default defineModuleUi({
+  id: "announcements",
+  version: "0.0.0",
+  mount(container, context) {
+    const root = createRoot(container);
+    root.render(context.moduleId);
+    return () => root.unmount();
+  },
+});

tests/fixtures/boundaries/module-owns-react-ui/packages/module-ui-sdk/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@ekklesia/module-ui-sdk",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "module-ui-sdk"
+  }
+}

tests/fixtures/boundaries/module-owns-react-ui/packages/module-ui-sdk/src/index.ts

@@ -0,0 +1,3 @@
+export function defineModuleUi<Definition>(definition: Definition): Definition {
+  return definition;
+}

tests/fixtures/boundaries/module-ui-aliased-framework/modules/calendar/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@ekklesia/module-calendar",
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {
+    "react": "npm:[email protected]"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "module"
+  }
+}

tests/fixtures/boundaries/module-ui-aliased-framework/modules/calendar/src/index.ts

@@ -0,0 +1 @@
+export const moduleId = "calendar";

tests/fixtures/boundaries/module-ui-imports-core/core/src/index.ts

@@ -0,0 +1 @@
+export const corePool = "core-internal-pool";

tests/fixtures/boundaries/module-ui-imports-core/modules/announcements/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@ekklesia/module-announcements",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "ekklesia": {
+    "layer": "module"
+  }
+}

tests/fixtures/boundaries/module-ui-imports-core/modules/announcements/src/index.ts

@@ -0,0 +1 @@
+export const moduleId = "announcements";

tests/fixtures/boundaries/module-ui-imports-core/modules/announcements/src/ui/editor.tsx

@@ -0,0 +1,3 @@
+import { corePool } from "../../../../core/src/index.js";
+
+export const leakedCoreInternal = corePool;