feat: mount discovered module UI in a minimal Ekklesia browser host

Phase 6C pass 2. Every link in the module UI chain existed except the one
that closes it: a module could be authored, built, validated, published at a
browser URL, and loaded by a generic loader — and nothing in Ekklesia did any
of it. There was no browser application at all.

Two pieces were missing. A browser could not discover what to mount, and it
must not work that out for itself.

GET /api/v1/module-ui is the inventory: per publishable module, its id and
version, the server-produced artifact URL, the server-produced root of the
module's own API, and the subset of that module's declared permissions the
caller holds. Five fields, each because building a ModuleUiHostContext needs
it — no filesystem paths, and no name/icon/folder/order, because navigation
metadata is a design that does not exist yet. Its module set is the ADR 0025
publication registry rather than a rescan, so the inventory and the artifact
route cannot disagree. It requires a new Core permission, core.modules.ui.read
(baseline authenticated), because it is precisely the enumeration the anonymous
artifact route deliberately withholds.

Both URLs are server-produced. moduleUiArtifactUrl already existed;
moduleApiBaseUrl is now exported and moduleRoutePath builds on it, so each URL
shape has exactly one author. Without it the shell would hardcode
/api/v1/modules/<id> — the prefix ADR 0022 forbids a module UI from spelling,
reappearing in the host instead.

surfaces/shell (@ekklesia/shell) is the repository's first surface: a small
React application built to static files by its own esbuild script. It resolves
the principal, fetches the inventory, builds the host context entirely from
server-derived data, and hands the artifact URL to @ekklesia/module-ui-host.
One frame per selection — keyed by module identity — defeats the stale-load
race; the host owns the container, the loading state, and every failure, so a
broken module costs its own panel rather than the shell.

The shell statically imports no module, and both levels are checked: no source
import may name a module, and the emitted bundle must contain exactly one
dynamic import (the loader's) with no module id, no /api/v1/modules, no eval,
and no blob URL. Permission hints come from Core's own evaluator and stay
presentation-only — the end-to-end test has a UI holding no grant call its API
anyway and still receive 403.

Surfaces may now depend only on browser-safe shared roles; @ekklesia/contracts
is deliberately excluded, since its barrel pulls Drizzle's types and Node's
globals into the browser — the hole ADR 0024 closed one layer down.

Not the Dashboard: no navigation, grouping, icons, ordering, design system, or
routing. The selector is a list of module ids.

Co-Authored-By: Claude Opus 5 <[email protected]>

surfaces/shell/src/browser/HostApp.tsx

@@ -0,0 +1,175 @@
+import type { ModuleUiImporter } from "@ekklesia/module-ui-host";
+import { type ReactElement, useEffect, useState } from "react";
+import {
+  bootstrapHost,
+  type EkklesiaHostConfig,
+  type HostBootstrap,
+  HostProtocolError,
+} from "../host-protocol.js";
+import { ModuleUiFrame } from "./ModuleUiFrame.js";
+
+type BootstrapState =
+  | { readonly status: "loading" }
+  | { readonly status: "ready"; readonly bootstrap: HostBootstrap }
+  | { readonly status: "signed-out" }
+  | { readonly status: "failed" };
+
+export interface HostAppProps {
+  /** Must be a stable reference: bootstrap re-runs whenever it changes, so a fresh object literal
+   * built during render would re-fetch forever. The browser entry point builds it once at module
+   * scope. */
+  readonly config: EkklesiaHostConfig;
+  /** Test-only seam, forwarded to {@link ModuleUiFrame}. Production composition leaves it unset. */
+  readonly importModule?: ModuleUiImporter;
+}
+
+const shellStyles = {
+  aside: { borderRight: "1px solid #e7e5e4", minWidth: "12rem", padding: "1rem" },
+  header: {
+    borderBottom: "1px solid #e7e5e4",
+    fontWeight: 600,
+    gridColumn: "1 / -1",
+    padding: "0.75rem 1rem",
+  },
+  layout: {
+    color: "#1c1917",
+    display: "grid",
+    fontFamily: "system-ui, sans-serif",
+    gridTemplateColumns: "auto 1fr",
+    minHeight: "100vh",
+  },
+  main: { padding: "1rem" },
+  message: { color: "#57534e", padding: "1rem" },
+} as const;
+
+function moduleKey(id: string, version: string): string {
+  return `${id}@${version}`;
+}
+
+/**
+ * The minimal Ekklesia browser shell: sign-in awareness, a module list, and one mount target.
+ *
+ * **This is not the Dashboard.** There is no navigation model, no grouping or folders, no icons, no
+ * ordering, no home screen, no design system, and no routing — a selected-module state is the whole
+ * of it, and the selector renders module ids because the inventory deliberately carries no display
+ * metadata yet (ADR 0021 keeps that an administrator's presentation configuration, not a module
+ * declaration). What this proves is the architecture underneath: that a module discovered on the
+ * server, published as an artifact, and described by the inventory can be mounted here without the
+ * shell knowing anything about it in advance.
+ *
+ * Nothing about any specific module appears in this file, or anywhere in this package. There is no
+ * import of a module, no module id, no registry, no allowlist, and no fallback bundle. Every module
+ * the shell can mount arrives at run time from the inventory the server returned.
+ */
+export function HostApp(props: HostAppProps): ReactElement {
+  const [state, setState] = useState<BootstrapState>({ status: "loading" });
+  const [selectedKey, setSelectedKey] = useState<string | undefined>(undefined);
+  const { config, importModule } = props;
+
+  useEffect(() => {
+    const abort = new AbortController();
+    setState({ status: "loading" });
+    void bootstrapHost(config, abort.signal)
+      .then((bootstrap) => {
+        if (abort.signal.aborted) {
+          return;
+        }
+        setState(
+          bootstrap.principal.kind === "anonymous"
+            ? { status: "signed-out" }
+            : { bootstrap, status: "ready" },
+        );
+        setSelectedKey(
+          bootstrap.modules[0]
+            ? moduleKey(bootstrap.modules[0].id, bootstrap.modules[0].version)
+            : undefined,
+        );
+      })
+      .catch((error: unknown) => {
+        if (abort.signal.aborted) {
+          return;
+        }
+        console.error("[ekklesia] host bootstrap failed", error);
+        setState(
+          error instanceof HostProtocolError && error.code === "HOST_UNAUTHENTICATED"
+            ? { status: "signed-out" }
+            : { status: "failed" },
+        );
+      });
+    return () => abort.abort();
+  }, [config]);
+
+  if (state.status === "loading") {
+    return <p style={shellStyles.message}>Loading Ekklesia…</p>;
+  }
+  if (state.status === "signed-out") {
+    return (
+      <p data-testid="host-signed-out" style={shellStyles.message}>
+        Sign in to Ekklesia to use the module host.
+      </p>
+    );
+  }
+  if (state.status === "failed") {
+    return (
+      <p data-testid="host-error" style={shellStyles.message}>
+        Ekklesia could not be reached. Refresh to try again.
+      </p>
+    );
+  }
+
+  const { bootstrap } = state;
+  const selected = bootstrap.modules.find(
+    (module) => moduleKey(module.id, module.version) === selectedKey,
+  );
+
+  return (
+    <div style={shellStyles.layout}>
+      <header style={shellStyles.header}>Ekklesia</header>
+      <aside style={shellStyles.aside}>
+        {bootstrap.modules.length === 0 ? (
+          <p data-testid="host-empty" style={{ color: "#57534e", margin: 0 }}>
+            No installed module provides a user interface.
+          </p>
+        ) : (
+          <nav style={{ display: "grid", gap: "0.25rem" }}>
+            {bootstrap.modules.map((module) => {
+              const key = moduleKey(module.id, module.version);
+              return (
+                <button
+                  data-testid={`select-${module.id}`}
+                  key={key}
+                  onClick={() => setSelectedKey(key)}
+                  style={{
+                    background: key === selectedKey ? "#e7e5e4" : "transparent",
+                    border: "none",
+                    cursor: "pointer",
+                    font: "inherit",
+                    padding: "0.375rem 0.5rem",
+                    textAlign: "left",
+                  }}
+                  type="button"
+                >
+                  {module.id}
+                </button>
+              );
+            })}
+          </nav>
+        )}
+      </aside>
+      <main style={shellStyles.main}>
+        {selected ? (
+          // Keyed by module identity, so switching selection discards this frame — and its container
+          // element — entirely rather than reusing one across two modules. See `ModuleUiFrame` for
+          // why that is what makes a slow, stale load harmless.
+          <ModuleUiFrame
+            config={config}
+            descriptor={selected}
+            {...(importModule ? { importModule } : {})}
+            key={moduleKey(selected.id, selected.version)}
+            principal={bootstrap.principal}
+          />
+        ) : undefined}
+      </main>
+    </div>
+  );
+}

surfaces/shell/src/browser/ModuleUiFrame.tsx

@@ -0,0 +1,115 @@
+import { loadModuleUi, type ModuleUiImporter } from "@ekklesia/module-ui-host";
+import type { ModuleUiPrincipal } from "@ekklesia/module-ui-sdk";
+import { type ReactElement, useEffect, useRef, useState } from "react";
+import type { EkklesiaHostConfig, HostModuleUiDescriptor } from "../host-protocol.js";
+import { createModuleUiContext, moduleUiSourceUrl } from "../module-context.js";
+
+type FrameStatus = "loading" | "ready" | "failed";
+
+export interface ModuleUiFrameProps {
+  readonly config: EkklesiaHostConfig;
+  readonly descriptor: HostModuleUiDescriptor;
+  readonly principal: ModuleUiPrincipal;
+  /** Test-only seam, forwarded to the generic loader so a test can hold an import pending and prove
+   * the stale-load rule. Production composition leaves it unset and the loader's own
+   * `(url) => import(url)` runs. */
+  readonly importModule?: ModuleUiImporter;
+}
+
+/**
+ * Mounts exactly one module UI into a container this component owns, and tears it down again.
+ *
+ * ## Host-owned container, module-owned contents
+ *
+ * The `<div>` below belongs to the shell. The module fills it and must return an unmount that
+ * empties it; it never receives the shell's header, the module list, the page root, or the document.
+ * The loading and error states are rendered as siblings, so a module can never own the shell's
+ * pre-mount or failure state — which is the point of the host owning them.
+ *
+ * ## One frame per selection, which is what defeats the stale-load race
+ *
+ * The parent renders this with a `key` of the module's identity, so selecting a different module
+ * unmounts this component entirely and creates a fresh one with a **fresh container element**. A
+ * slow import that resolves after the selection changed therefore mounts into a node that is already
+ * detached from the document and is immediately unmounted by this component's own cleanup — it can
+ * never render over, or into, the newer selection's container. The `cancelled` flag makes that
+ * explicit rather than incidental: a load that finishes after cleanup ran is torn down at once and
+ * never reaches `setStatus`, so it also cannot resurrect a stale status on a component React has
+ * already discarded.
+ *
+ * ## Failure is the host's to render
+ *
+ * Every way this can fail — the artifact will not fetch, the bundle is not a module, its declared
+ * identity does not match the manifest, or `mount` throws — is caught here and turned into a fixed,
+ * host-owned message. Nothing from the caught error reaches the DOM: not a URL, not a path, not a
+ * stack. The error object goes to the browser console, which is where a developer's diagnostics
+ * belong and where ADR 0024 intends the loader's `cause` to be read. The rest of the shell keeps
+ * rendering, so a broken module costs its own panel and nothing else.
+ */
+export function ModuleUiFrame(props: ModuleUiFrameProps): ReactElement {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [status, setStatus] = useState<FrameStatus>("loading");
+  const { config, descriptor, importModule, principal } = props;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+    let cancelled = false;
+    let mounted: Awaited<ReturnType<typeof loadModuleUi>> | undefined;
+    setStatus("loading");
+
+    void (async () => {
+      try {
+        const instance = await loadModuleUi({
+          container,
+          context: createModuleUiContext({ config, descriptor, principal }),
+          ...(importModule ? { importModule } : {}),
+          source: {
+            moduleId: descriptor.id,
+            url: moduleUiSourceUrl(config, descriptor),
+            version: descriptor.version,
+          },
+        });
+        if (cancelled) {
+          // Selection already moved on. Release it immediately rather than leaving a module running
+          // in a detached container with no handle to stop it.
+          await instance.unmount().catch(() => undefined);
+          return;
+        }
+        mounted = instance;
+        setStatus("ready");
+      } catch (error) {
+        console.error("[ekklesia] a module UI failed to load", error);
+        if (!cancelled) {
+          setStatus("failed");
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      // Idempotent by contract (ADR 0024), and a throwing cleanup is swallowed here: teardown is
+      // already in progress, and a module that fails to clean up must not take the shell with it.
+      void mounted?.unmount().catch(() => undefined);
+    };
+  }, [config, descriptor, importModule, principal]);
+
+  return (
+    <section aria-live="polite" style={{ display: "grid", gap: "0.75rem" }}>
+      {status === "loading" ? (
+        <p data-testid="module-loading" style={{ color: "#57534e", margin: 0 }}>
+          Loading module…
+        </p>
+      ) : undefined}
+      {status === "failed" ? (
+        <p data-testid="module-error" style={{ color: "#9f1239", margin: 0 }}>
+          This module’s interface could not be loaded. Try another module, or ask an administrator
+          to check the installation.
+        </p>
+      ) : undefined}
+      <div data-testid="module-container" ref={containerRef} />
+    </section>
+  );
+}

surfaces/shell/src/browser/main.tsx

@@ -0,0 +1,31 @@
+import { createRoot } from "react-dom/client";
+import type { EkklesiaHostConfig } from "../host-protocol.js";
+import { HostApp } from "./HostApp.js";
+
+/**
+ * Replaced at build time by `scripts/build-browser.mjs` with a JSON string literal: the API origin
+ * when `EKKLESIA_API_BASE_URL` was set for the build, and `""` otherwise. Declared rather than read
+ * from `process.env`, because a browser has no `process` and the substitution must be visible here
+ * instead of hidden in bundler configuration.
+ */
+declare const __EKKLESIA_API_BASE_URL__: string;
+
+/**
+ * The one place the shell touches a browser global.
+ *
+ * An empty build-time value means the API is served from the same origin as this page, which is the
+ * expected production shape; a non-empty one is the split-origin development shape the platform's
+ * trusted-origin configuration already supports (`EKKLESIA_IDENTITY_TRUSTED_ORIGINS` must list this
+ * page's origin for the session cookie to travel). Everything downstream receives the resolved
+ * origin as a plain argument, so no other file in this package reads `window`.
+ */
+const config: EkklesiaHostConfig = {
+  apiBaseUrl: __EKKLESIA_API_BASE_URL__ || window.location.origin,
+};
+
+const container = document.getElementById("ekklesia-host");
+if (!container) {
+  throw new Error("The Ekklesia shell requires a #ekklesia-host element.");
+}
+
+createRoot(container).render(<HostApp config={config} />);

surfaces/shell/src/host-protocol.ts

@@ -0,0 +1,247 @@
+import type { ModuleUiPrincipal } from "@ekklesia/module-ui-sdk";
+
+/**
+ * How this shell reaches the Ekklesia API.
+ *
+ * `apiBaseUrl` is an absolute **origin** (`https://ekklesia.example.test`, `http://127.0.0.1:3000`)
+ * rather than something read from a global. The browser entry point supplies it — from a build-time
+ * value when the shell and the API are served from different origins in development, and from
+ * `window.location.origin` otherwise — so every function below is a pure function of its arguments
+ * and can be exercised without a DOM, a `window`, or a page. Nothing here reads a global.
+ */
+export interface EkklesiaHostConfig {
+  readonly apiBaseUrl: string;
+  /** Injected so tests can drive the real protocol against a real in-process app without a socket.
+   * Production composition leaves this unset and the platform `fetch` is used. */
+  readonly fetch?: typeof fetch;
+}
+
+/** Root-relative platform paths. The shell never builds a module UI artifact URL or a module API
+ * URL — the server produces both and hands them over in the inventory — so these two are the only
+ * URLs it knows, and they are the two that describe the platform itself rather than any module. */
+const PRINCIPAL_PATH = "/api/v1/principal";
+const MODULE_UI_INVENTORY_PATH = "/api/v1/module-ui";
+
+export type HostProtocolErrorCode =
+  /** The caller is not signed in, or lacks `core.modules.ui.read`. */
+  | "HOST_UNAUTHENTICATED"
+  /** The API answered, but not with something this shell understands. */
+  | "HOST_RESPONSE_INVALID"
+  /** The API could not be reached, or failed. */
+  | "HOST_REQUEST_FAILED"
+  /** A module UI asked for something outside its own API root. */
+  | "MODULE_API_PATH_INVALID";
+
+const errorMessages: Readonly<Record<HostProtocolErrorCode, string>> = Object.freeze({
+  HOST_REQUEST_FAILED: "Ekklesia could not be reached.",
+  HOST_RESPONSE_INVALID: "Ekklesia returned a response this host does not understand.",
+  HOST_UNAUTHENTICATED: "You need to sign in to Ekklesia to use this page.",
+  MODULE_API_PATH_INVALID: "A module asked for a path outside its own API.",
+});
+
+/**
+ * Carries a stable code and a fixed, user-safe message — never a URL, a response body, a server
+ * path, or a caught cause — matching every other Ekklesia error boundary. The originating error is
+ * attached as `cause` for browser-console diagnostics and is never rendered.
+ */
+export class HostProtocolError extends Error {
+  readonly code: HostProtocolErrorCode;
+
+  constructor(code: HostProtocolErrorCode, options?: { readonly cause?: unknown }) {
+    super(errorMessages[code], options);
+    this.name = "HostProtocolError";
+    this.code = code;
+    this.stack = `${this.name}: ${this.message}`;
+  }
+}
+
+/**
+ * One module UI this host may mount, exactly as the server described it.
+ *
+ * This mirrors the server's `HostModuleUiDescriptor` (`apps/api/src/module-ui-inventory.ts`) rather
+ * than importing it: a surface may not depend on an app, and the type on either side of an HTTP
+ * boundary should be validated on arrival rather than assumed. `parseHostModuleUiInventory` below is
+ * that validation, and the end-to-end test feeds a real server response through it so the two
+ * declarations are proven to agree instead of merely looking similar.
+ */
+export interface HostModuleUiDescriptor {
+  readonly id: string;
+  readonly version: string;
+  /** Server-produced. The shell resolves it against `apiBaseUrl` and hands it to the generic loader
+   * unchanged; it never constructs, parses, or pattern-matches this URL. */
+  readonly uiUrl: string;
+  /** Server-produced root of this module's own HTTP API. */
+  readonly apiBaseUrl: string;
+  /** Granted ids only, already evaluated server-side. Presentation hints, never authority. */
+  readonly permissions: readonly string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function nestedString(value: unknown, key: string): string | undefined {
+  return isRecord(value) ? nonEmptyString(value[key]) : undefined;
+}
+
+/**
+ * Both URLs in a descriptor must be **root-relative** paths, exactly as the server produces them.
+ *
+ * Enforced rather than assumed. The shell resolves each against the configured API origin, so an
+ * absolute or protocol-relative value arriving here would silently redirect a module's script import
+ * or its API calls to another origin. This does not defend against a compromised server — one could
+ * serve anything at the real URL — but it does pin the wire contract, so a proxy rewrite, a
+ * misconfiguration, or a future server-side bug fails loudly here instead of quietly changing where
+ * browser code is fetched from.
+ */
+function rootRelativePath(value: unknown, key: string): string | undefined {
+  const candidate = nestedString(value, key);
+  if (candidate === undefined || !candidate.startsWith("/") || candidate.startsWith("//")) {
+    return undefined;
+  }
+  return candidate;
+}
+
+/**
+ * Strict, total validation of the inventory document. Anything unexpected — a missing field, a
+ * non-array `modules`, a permission entry that is not a string — fails the whole parse rather than
+ * yielding a half-built descriptor, because a descriptor with a missing URL would surface much later
+ * as an inexplicable mount failure.
+ */
+export function parseHostModuleUiInventory(payload: unknown): readonly HostModuleUiDescriptor[] {
+  const modules = isRecord(payload) ? payload.modules : undefined;
+  if (!Array.isArray(modules)) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  return Object.freeze(
+    modules.map((entry): HostModuleUiDescriptor => {
+      const id = nestedString(entry, "id");
+      const version = nestedString(entry, "version");
+      const uiUrl = isRecord(entry) ? rootRelativePath(entry.ui, "url") : undefined;
+      const apiBaseUrl = isRecord(entry) ? rootRelativePath(entry.api, "baseUrl") : undefined;
+      const permissions = isRecord(entry) ? entry.permissions : undefined;
+      if (
+        id === undefined ||
+        version === undefined ||
+        uiUrl === undefined ||
+        apiBaseUrl === undefined ||
+        !Array.isArray(permissions) ||
+        permissions.some((permission) => typeof permission !== "string")
+      ) {
+        throw new HostProtocolError("HOST_RESPONSE_INVALID");
+      }
+      return Object.freeze({
+        apiBaseUrl,
+        id,
+        permissions: Object.freeze([...(permissions as string[])]),
+        uiUrl,
+        version,
+      });
+    }),
+  );
+}
+
+/** `/api/v1/principal`'s two documented shapes, narrowed to the browser-owned `ModuleUiPrincipal`
+ * the UI SDK defines. Nothing else the endpoint might ever return is carried into module UI. */
+export function parseHostPrincipal(payload: unknown): ModuleUiPrincipal {
+  if (!isRecord(payload)) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  if (payload.kind === "anonymous") {
+    return { kind: "anonymous" };
+  }
+  const userId = nonEmptyString(payload.userId);
+  if (payload.kind === "authenticated" && userId !== undefined) {
+    return { kind: "authenticated", userId };
+  }
+  throw new HostProtocolError("HOST_RESPONSE_INVALID");
+}
+
+/** Resolves a root-relative platform path against the configured API origin. The one place the
+ * shell turns a server-produced path into an absolute URL. */
+export function resolveApiUrl(config: EkklesiaHostConfig, rootRelativePath: string): string {
+  return new URL(rootRelativePath, config.apiBaseUrl).href;
+}
+
+/**
+ * Every request this shell makes to Ekklesia carries credentials.
+ *
+ * Same-origin that is simply the session cookie. Split-origin — the development shape the platform's
+ * trusted-origin configuration already supports — it is what makes the cookie travel at all, and it
+ * works only because the API reflects an exact trusted origin with
+ * `Access-Control-Allow-Credentials: true` and never a wildcard. This does not weaken that policy;
+ * it is the client half of it.
+ */
+async function requestPlatformJson(
+  config: EkklesiaHostConfig,
+  rootRelativePath: string,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const performRequest = config.fetch ?? fetch;
+  let response: Response;
+  try {
+    response = await performRequest(resolveApiUrl(config, rootRelativePath), {
+      credentials: "include",
+      headers: { accept: "application/json" },
+      ...(signal ? { signal } : {}),
+    });
+  } catch (error) {
+    throw new HostProtocolError("HOST_REQUEST_FAILED", { cause: error });
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new HostProtocolError("HOST_UNAUTHENTICATED");
+  }
+  if (!response.ok) {
+    throw new HostProtocolError("HOST_REQUEST_FAILED");
+  }
+  try {
+    return (await response.json()) as unknown;
+  } catch (error) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID", { cause: error });
+  }
+}
+
+/** Who is viewing. Anonymous is a normal answer, not a failure: the shell renders a sign-in prompt
+ * rather than an error, and never asks for the inventory it would be refused. */
+export async function loadHostPrincipal(
+  config: EkklesiaHostConfig,
+  signal?: AbortSignal,
+): Promise<ModuleUiPrincipal> {
+  return parseHostPrincipal(await requestPlatformJson(config, PRINCIPAL_PATH, signal));
+}
+
+/** Which module UIs this viewer may mount, where to fetch each, and what they may do inside it. */
+export async function loadModuleUiInventory(
+  config: EkklesiaHostConfig,
+  signal?: AbortSignal,
+): Promise<readonly HostModuleUiDescriptor[]> {
+  return parseHostModuleUiInventory(
+    await requestPlatformJson(config, MODULE_UI_INVENTORY_PATH, signal),
+  );
+}
+
+export interface HostBootstrap {
+  readonly principal: ModuleUiPrincipal;
+  readonly modules: readonly HostModuleUiDescriptor[];
+}
+
+/**
+ * The shell's whole startup sequence, in one explicit function: resolve who is viewing, then ask
+ * what they may mount. Sequential rather than parallel on purpose — an anonymous viewer is told to
+ * sign in and the inventory is never requested, so the shell does not depend on a `403` to discover
+ * something `/api/v1/principal` already said plainly.
+ */
+export async function bootstrapHost(
+  config: EkklesiaHostConfig,
+  signal?: AbortSignal,
+): Promise<HostBootstrap> {
+  const principal = await loadHostPrincipal(config, signal);
+  if (principal.kind === "anonymous") {
+    return { modules: Object.freeze([]), principal };
+  }
+  return { modules: await loadModuleUiInventory(config, signal), principal };
+}

surfaces/shell/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * The framework-free half of the Ekklesia shell: how it talks to the platform and how it builds a
+ * module UI host context. Deliberately the only public surface of this package.
+ *
+ * The React shell itself (`src/browser/`) is not exported. It is an application, bundled straight to
+ * a browser artifact by this package's own build; exporting components would invite another package
+ * to depend on Ekklesia's shell internals, which is exactly the coupling the surface boundary
+ * exists to prevent. What *is* exported is the protocol — validated wire parsing, context
+ * construction, module API resolution — so the end-to-end test can drive the real host code against
+ * a real server instead of a reimplementation of it.
+ */
+export {
+  bootstrapHost,
+  type EkklesiaHostConfig,
+  type HostBootstrap,
+  type HostModuleUiDescriptor,
+  HostProtocolError,
+  type HostProtocolErrorCode,
+  loadHostPrincipal,
+  loadModuleUiInventory,
+  parseHostModuleUiInventory,
+  parseHostPrincipal,
+  resolveApiUrl,
+} from "./host-protocol.js";
+export {
+  type CreateModuleUiContextOptions,
+  createModuleUiContext,
+  moduleUiSourceUrl,
+} from "./module-context.js";

surfaces/shell/src/module-context.ts

@@ -0,0 +1,104 @@
+import type {
+  ModuleUiApiClient,
+  ModuleUiHostContext,
+  ModuleUiPrincipal,
+} from "@ekklesia/module-ui-sdk";
+import {
+  type EkklesiaHostConfig,
+  type HostModuleUiDescriptor,
+  HostProtocolError,
+  resolveApiUrl,
+} from "./host-protocol.js";
+
+const ABSOLUTE_URL_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/u;
+
+/**
+ * Turns the relative path a module UI asks for into the real Ekklesia URL, and refuses anything
+ * that is not the module's own API.
+ *
+ * `context.api.request("records")` becomes `<origin>/api/v1/modules/<module-id>/records`. The
+ * `/api/v1/modules/<module-id>` half is **not** written here: it arrives from the server in the
+ * inventory descriptor (`apiBaseUrl`), so Ekklesia's module mount prefix is spelled in exactly one
+ * place in the whole repository (`moduleApiBaseUrl`, `apps/api/src/module-http-routes.ts`). The
+ * browser is a consumer of that URL, never a second author of it.
+ *
+ * Containment is enforced with the URL parser rather than string inspection, because the parser is
+ * what a real `fetch` would use: `"../calendar/records"` normalizes to another module's API, and a
+ * check that only looked at the input string would miss it. Anything that resolves outside this
+ * module's own root — a traversal, a protocol-relative `//host`, an absolute URL, an encoded
+ * separator — is refused with `MODULE_API_PATH_INVALID`.
+ *
+ * This is a portability boundary, not a security one. Module UI is trusted same-realm code (ADR
+ * 0022) and could call `fetch` directly; refusing here is what keeps a module honest about
+ * addressing only its own backend, so the same artifact still runs under a standalone host. Server
+ * authorization is unaffected either way: every module route stays behind `requirePermission`.
+ */
+function createModuleApiClient(
+  config: EkklesiaHostConfig,
+  descriptor: HostModuleUiDescriptor,
+): ModuleUiApiClient {
+  const performRequest = config.fetch ?? fetch;
+  const moduleRoot = new URL(resolveApiUrl(config, descriptor.apiBaseUrl));
+
+  return Object.freeze({
+    async request(path: string, init?: RequestInit): Promise<Response> {
+      if (ABSOLUTE_URL_PATTERN.test(path) || path.startsWith("//")) {
+        throw new HostProtocolError("MODULE_API_PATH_INVALID");
+      }
+      const relative = path.replace(/^\/+/u, "");
+      const target = new URL(
+        relative === "" ? moduleRoot.pathname : `${moduleRoot.pathname}/${relative}`,
+        moduleRoot,
+      );
+      const contained =
+        target.origin === moduleRoot.origin &&
+        (target.pathname === moduleRoot.pathname ||
+          target.pathname.startsWith(`${moduleRoot.pathname}/`));
+      if (!contained) {
+        throw new HostProtocolError("MODULE_API_PATH_INVALID");
+      }
+      // The module's own `init` is forwarded whole — method, headers, body, signal — and only
+      // `credentials` is imposed, because session handling is the host's job and a module UI never
+      // sees or supplies a token (ADR 0022). A module cannot opt out of it.
+      return performRequest(target.href, { ...init, credentials: "include" });
+    },
+  });
+}
+
+export interface CreateModuleUiContextOptions {
+  readonly config: EkklesiaHostConfig;
+  readonly descriptor: HostModuleUiDescriptor;
+  readonly principal: ModuleUiPrincipal;
+}
+
+/**
+ * Builds the `ModuleUiHostContext` (ADR 0022) Ekklesia hands a module UI at mount time.
+ *
+ * All four members come from server-derived data: the module id and API root from the inventory
+ * descriptor, the principal from `/api/v1/principal`, and the permission hints from the server's own
+ * evaluation of that module's declared permissions against that principal. Nothing is guessed,
+ * defaulted to `true`, or inferred from a client-side role name.
+ *
+ * The permission set is the module's own and only the module's own. A module UI cannot use this to
+ * discover what the viewer may do elsewhere in the platform, and `has` returning `true` is a
+ * statement about what the server said a moment ago — a hint for hiding a control, never a
+ * substitute for the server check that actually decides.
+ */
+export function createModuleUiContext(options: CreateModuleUiContextOptions): ModuleUiHostContext {
+  const granted = new Set(options.descriptor.permissions);
+  return Object.freeze({
+    api: createModuleApiClient(options.config, options.descriptor),
+    moduleId: options.descriptor.id,
+    permissions: Object.freeze({ has: (permissionId: string) => granted.has(permissionId) }),
+    principal: options.principal,
+  });
+}
+
+/** The absolute URL the generic loader should import this module's artifact from — the descriptor's
+ * server-produced path resolved against the configured API origin, and nothing more. */
+export function moduleUiSourceUrl(
+  config: EkklesiaHostConfig,
+  descriptor: HostModuleUiDescriptor,
+): string {
+  return resolveApiUrl(config, descriptor.uiUrl);
+}