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/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ekklesia/module-ui-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "biome lint .",
+    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-ui-sdk",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@ekklesia/contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.3",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "ekklesia": {
+    "layer": "module-ui-sdk"
+  }
+}

packages/module-ui-sdk/src/define-module-ui.ts

@@ -0,0 +1,12 @@
+import { type ModuleUiDefinition, parseModuleUiDefinition } from "./module-ui.js";
+
+/**
+ * The module author's entry point, mirroring `defineModuleRuntime` (ADR 0006): validate at authoring
+ * time, freeze, and preserve the literal type. A malformed definition fails where it was written
+ * rather than in a host, at mount time, in a browser.
+ */
+export function defineModuleUi<const Definition extends ModuleUiDefinition>(
+  definition: Definition,
+): Readonly<Definition> {
+  return parseModuleUiDefinition(definition) as Readonly<Definition>;
+}

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;
+}

packages/module-ui-sdk/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./define-module-ui.js";
+export * from "./host-context.js";
+export * from "./module-ui.js";

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;
+}

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);
+    }
+  });
+});

packages/module-ui-sdk/tests/fixtures/announcements-ui.ts

@@ -0,0 +1,47 @@
+import { defineModuleUi } from "../../src/index.js";
+import type { ModuleUiHostContext } from "../../src/index.js";
+
+/**
+ * A stand-in for a real module's compiled `entrypoints.ui` artifact. It is deliberately tiny and
+ * deliberately host-neutral: it never constructs an API URL, never imports Core, an app, or a
+ * surface, and never reads a global. Everything it needs arrives in the host context.
+ *
+ * This is the artifact both fake hosts in `module-ui-contract.test.ts` mount, unchanged.
+ */
+export interface AnnouncementsUiTrace {
+  readonly mounted: string[];
+  readonly unmounted: string[];
+  readonly requestedPaths: string[];
+  readonly canPublish: boolean[];
+}
+
+export const trace: AnnouncementsUiTrace = {
+  mounted: [],
+  unmounted: [],
+  requestedPaths: [],
+  canPublish: [],
+};
+
+export default defineModuleUi({
+  id: "announcements",
+  version: "0.1.0",
+  async mount(container: Element, context: ModuleUiHostContext) {
+    trace.mounted.push(context.moduleId);
+
+    // Presentation-only gating: the module asks the host whether to render the publish control.
+    // Whatever the answer, the server decides what actually happens.
+    const canPublish = context.permissions.has("announcements.posts.publish");
+    trace.canPublish.push(canPublish);
+
+    // The whole portability point: the module asks for its own resource by relative path and has
+    // no idea what URL the host turns it into.
+    const response = await context.api.request("posts");
+    trace.requestedPaths.push("posts");
+    container.textContent = `announcements:${response.status}:${canPublish ? "editor" : "reader"}`;
+
+    return () => {
+      trace.unmounted.push(context.moduleId);
+      container.textContent = "";
+    };
+  },
+});

packages/module-ui-sdk/tests/module-ui-contract.test.ts

@@ -0,0 +1,239 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  defineModuleUi,
+  isModuleUiDefinition,
+  ModuleUiContractError,
+  type ModuleUiApiClient,
+  type ModuleUiDefinition,
+  type ModuleUiHostContext,
+  parseModuleUiDefinition,
+  parseModuleUiExport,
+} from "../src/index.js";
+
+function validDefinition(): ModuleUiDefinition {
+  return { id: "announcements", version: "0.1.0", mount: (): void => undefined };
+}
+
+/** The contract treats the container as an opaque host-supplied mount target, so a plain object
+ * with the one property the fixture touches is a faithful stand-in. No DOM is required to prove the
+ * contract, and this package deliberately does not take a DOM dependency to obtain one. */
+const noop = (): void => undefined;
+
+function fakeContainer(): Element & { textContent: string } {
+  return { textContent: "" } as unknown as Element & { textContent: string };
+}
+
+describe("module UI definition contract", () => {
+  it("accepts and freezes a valid definition", () => {
+    const definition = defineModuleUi(validDefinition());
+
+    expect(definition.id).toBe("announcements");
+    expect(definition.version).toBe("0.1.0");
+    expect(Object.isFrozen(definition)).toBe(true);
+  });
+
+  it.each<[string, unknown]>([
+    ["a missing id", { version: "0.1.0", mount: noop }],
+    ["a blank id", { id: "   ", version: "0.1.0", mount: noop }],
+    ["a non-string id", { id: 7, version: "0.1.0", mount: noop }],
+    ["a missing version", { id: "announcements", mount: noop }],
+    ["a blank version", { id: "announcements", version: "", mount: noop }],
+    ["a missing mount", { id: "announcements", version: "0.1.0" }],
+    ["a non-function mount", { id: "announcements", version: "0.1.0", mount: "render" }],
+    ["an unknown property", { id: "announcements", version: "0.1.0", mount: noop, routes: [] }],
+  ])("rejects a definition with %s", (_label, candidate) => {
+    expect(isModuleUiDefinition(candidate)).toBe(false);
+    expect(() => parseModuleUiDefinition(candidate)).toThrowError(ModuleUiContractError);
+  });
+
+  it.each<unknown>([
+    null,
+    undefined,
+    42,
+    "ui",
+    [],
+    noop,
+  ])("rejects a non-object definition %s", (candidate) => {
+    expect(isModuleUiDefinition(candidate)).toBe(false);
+  });
+
+  it("reports a malformed definition with a stable, sanitized code", () => {
+    try {
+      parseModuleUiDefinition({ id: "announcements" });
+      expect.unreachable("expected a contract error");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ModuleUiContractError);
+      expect((error as ModuleUiContractError).code).toBe("MODULE_UI_DEFINITION_INVALID");
+      expect((error as ModuleUiContractError).stack).not.toContain("announcements");
+    }
+  });
+
+  it("rejects an artifact namespace with no default export", () => {
+    expect(() =>
+      parseModuleUiExport({ ui: validDefinition() }, { id: "a", version: "1.0.0" }),
+    ).toThrowError(ModuleUiContractError);
+    try {
+      parseModuleUiExport({}, { id: "a", version: "1.0.0" });
+    } catch (error) {
+      expect((error as ModuleUiContractError).code).toBe("MODULE_UI_EXPORT_MISSING");
+    }
+  });
+
+  it.each([
+    ["id", { id: "calendar", version: "0.1.0" }],
+    ["version", { id: "announcements", version: "0.2.0" }],
+  ])("rejects an artifact whose %s does not match the manifest", (_label, expected) => {
+    try {
+      parseModuleUiExport({ default: defineModuleUi(validDefinition()) }, expected);
+      expect.unreachable("expected an identity mismatch");
+    } catch (error) {
+      expect((error as ModuleUiContractError).code).toBe("MODULE_UI_IDENTITY_MISMATCH");
+    }
+  });
+
+  it("accepts an artifact whose identity matches the manifest exactly", () => {
+    const definition = parseModuleUiExport(
+      { default: defineModuleUi(validDefinition()) },
+      { id: "announcements", version: "0.1.0" },
+    );
+
+    expect(definition.id).toBe("announcements");
+  });
+});
+
+/**
+ * The portability proof. One artifact, imported once, mounted by two hosts that share nothing but
+ * this package's public interface. If module UI ever hardcoded Ekklesia's `/api/v1/modules/<id>`
+ * prefix, the standalone host below could not serve it.
+ */
+describe("the same module UI artifact hosted by two different hosts", () => {
+  interface RecordingHost {
+    readonly name: string;
+    readonly requestedUrls: string[];
+    readonly context: ModuleUiHostContext;
+  }
+
+  /** Mirrors how Ekklesia mounts module routes today: `/api/v1/modules/<module-id>/<path>`. */
+  function ekklesiaHost(moduleId: string, canPublish: boolean): RecordingHost {
+    const requestedUrls: string[] = [];
+    const api: ModuleUiApiClient = {
+      async request(path) {
+        const url = `/api/v1/modules/${moduleId}/${path.replace(/^\//u, "")}`;
+        requestedUrls.push(url);
+        return new Response(null, { status: 200 });
+      },
+    };
+    return {
+      name: "ekklesia",
+      requestedUrls,
+      context: {
+        moduleId,
+        api,
+        principal: { kind: "anonymous" },
+        permissions: { has: () => canPublish },
+      },
+    };
+  }
+
+  /** A standalone host that serves exactly one module from a different origin and a different
+   * path shape, and never runs Core at all. */
+  function standaloneHost(moduleId: string, canPublish: boolean): RecordingHost {
+    const requestedUrls: string[] = [];
+    const api: ModuleUiApiClient = {
+      async request(path) {
+        const url = `https://announcements.example.org/api/${path.replace(/^\//u, "")}`;
+        requestedUrls.push(url);
+        return new Response(null, { status: 200 });
+      },
+    };
+    return {
+      name: "standalone",
+      requestedUrls,
+      context: {
+        moduleId,
+        api,
+        principal: { kind: "anonymous" },
+        permissions: { has: () => canPublish },
+      },
+    };
+  }
+
+  async function loadFixtureUi(): Promise<ModuleUiDefinition> {
+    // Each host performs its own dynamic import; this package never imports an artifact itself.
+    const namespace = (await import("./fixtures/announcements-ui.js")) as unknown;
+    return parseModuleUiExport(namespace, { id: "announcements", version: "0.1.0" });
+  }
+
+  beforeEach(async () => {
+    const { trace } = await import("./fixtures/announcements-ui.js");
+    trace.mounted.length = 0;
+    trace.unmounted.length = 0;
+    trace.requestedPaths.length = 0;
+    trace.canPublish.length = 0;
+  });
+
+  it("validates a real imported artifact's export against its manifest identity", async () => {
+    const definition = await loadFixtureUi();
+
+    expect(definition.id).toBe("announcements");
+    expect(definition.version).toBe("0.1.0");
+    expect(typeof definition.mount).toBe("function");
+  });
+
+  it("mounts and unmounts identically under both hosts, and resolves URLs only in the host", async () => {
+    const definition = await loadFixtureUi();
+    const { trace } = await import("./fixtures/announcements-ui.js");
+
+    for (const host of [
+      ekklesiaHost("announcements", true),
+      standaloneHost("announcements", true),
+    ]) {
+      const container = fakeContainer();
+      const unmount = await definition.mount(container, host.context);
+
+      expect(container.textContent).toBe("announcements:200:editor");
+      expect(typeof unmount).toBe("function");
+      await (unmount as () => Promise<void>)();
+      expect(container.textContent).toBe("");
+    }
+
+    // The module asked for the same relative path both times and never built a URL itself.
+    expect(trace.requestedPaths).toEqual(["posts", "posts"]);
+    expect(trace.mounted).toEqual(["announcements", "announcements"]);
+    expect(trace.unmounted).toEqual(["announcements", "announcements"]);
+  });
+
+  it("lets each host resolve the module's relative path to its own URL shape", async () => {
+    const definition = await loadFixtureUi();
+    const ekklesia = ekklesiaHost("announcements", true);
+    const standalone = standaloneHost("announcements", true);
+
+    await definition.mount(fakeContainer(), ekklesia.context);
+    await definition.mount(fakeContainer(), standalone.context);
+
+    expect(ekklesia.requestedUrls).toEqual(["/api/v1/modules/announcements/posts"]);
+    expect(standalone.requestedUrls).toEqual(["https://announcements.example.org/api/posts"]);
+  });
+
+  it("renders a different presentation when the host reports a permission is absent", async () => {
+    const definition = await loadFixtureUi();
+    const container = fakeContainer();
+
+    await definition.mount(container, ekklesiaHost("announcements", false).context);
+
+    expect(container.textContent).toBe("announcements:200:reader");
+  });
+
+  it("treats a denied permission hint as presentation only, never as enforcement", async () => {
+    // The host reports the permission as absent. The module still reaches its API — nothing in this
+    // contract blocks the request, and nothing in it could. Server-side `requirePermission` remains
+    // the only authority, exactly as it is for any other caller.
+    const definition = await loadFixtureUi();
+    const host = ekklesiaHost("announcements", false);
+
+    await definition.mount(fakeContainer(), host.context);
+
+    expect(host.context.permissions.has("announcements.posts.publish")).toBe(false);
+    expect(host.requestedUrls).toEqual(["/api/v1/modules/announcements/posts"]);
+  });
+});

packages/module-ui-sdk/tsconfig.build.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "tests"]
+}

packages/module-ui-sdk/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../typescript-config/browser.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}