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