feat: build module UI into its declared browser artifact

ADR 0022 defined what a module UI is and selected React and TypeScript
as the authoring model, but closed by recording that it was not buildable
end to end: `browser.json` preserves JSX, bundler plugins are denied, and
nothing turned a module's `.tsx` into the artifact its manifest declares.
This closes exactly that gap.

esbuild produces the artifact. It was already the right answer before it
was chosen: this workspace resolves esbuild 0.28.1 through Vite/Vitest
today and `pnpm-workspace.yaml` already carries `allowBuilds: esbuild`,
so the pinned dependency adds no second copy and no new trust decision.
It is also the smallest tool that covers TSX, ESM, browser platform,
bundling, source maps, and a define-time constant with no plugin
ecosystem. Vite library mode would drag in `@vitejs/plugin-react`, which
the module boundary denies on purpose; `tsc` alone cannot bundle, so its
output would carry bare `react/jsx-runtime` imports no browser resolves.

React is bundled, not externalized. That follows from ADR 0022 rather
than from convenience: `mount()` was made the ABI precisely so React
would not be part of the host contract, and externalizing it would
reverse that through the build system — every host would have to supply
a compatible React, and a standalone host might not use React at all.
The cost is real and accepted: duplicate runtimes and a ~570 KB
unminified artifact. Sharing one runtime later is a build optimization
that cannot change the contract, because the contract is a mount
function.

Output is browser ESM at `es2022`, unminified so an operator can review
what they install, with `process.env.NODE_ENV` substituted — React reads
it at module scope and would otherwise touch a Node global that does not
exist in a browser. The output path is read from the module's own
manifest rather than a build convention, so declared and produced
artifacts cannot drift, and it is validated with the same
`packageRelativePathSchema` discovery enforces, so a build can never
write where discovery would later reject.

`@ekklesia/module-ui-build` owns every option; modules own none. It uses
the existing `tooling` role that modules could already depend on, so this
pass required no boundary relaxation at all. Its `bin` points at a
committed launcher rather than compiled output because pnpm links bins
during install, before Turborepo builds anything — a bin targeting
`dist/cli.js` fails to link on a fresh clone and breaks every module's UI
build in CI. A module with no `entrypoints.ui` is not an error; the CLI
reports nothing to build and exits zero, so one script serves both kinds
of module.

Styling is React inline style objects. A stylesheet import fails the
build rather than emitting a sidecar `.css` that no manifest declares and
no host loads — an undeclared asset would appear to work in tests and
silently do nothing in a real host.

`templates/module` is the canonical example and now ships optional UI.
Its tests build the artifact from source, validate it with
`parseModuleUiExport`, mount it into a real DOM, assert the rendered
output, and unmount it; the artifact is rebuilt per run so the proof can
never pass against stale output, and `dist/` stays gitignored. Because
verify runs both `pnpm test` and `pnpm build`, a UI that cannot be
produced fails CI through two independent paths.

One correction worth stating plainly: the UI TypeScript project declares
`"types": []`, and a UI file referencing `process` does fail in
isolation, but TypeScript still pulls Node globals in transitively — a
file importing `@ekklesia/module-ui-sdk` reaches `@ekklesia/contracts`
and through its Zod and Drizzle types `process.env` typechecks again.
The docs and ADR describe this as the convention it is rather than the
guard it is not.

Core is untouched. Building is an authoring step; discovery still only
validates the artifact a module shipped and never executes or produces
one.

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

templates/module/src/ui/ExampleApp.tsx

@@ -0,0 +1,53 @@
+import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
+import { type ReactElement, useEffect, useState } from "react";
+
+/**
+ * The template's example screen. It is deliberately tiny, and deliberately host-neutral: it reads
+ * everything it needs from the host context and hardcodes no URL, no origin, and no global.
+ */
+export function ExampleApp({ context }: { readonly context: ModuleUiHostContext }): ReactElement {
+  const [recordCount, setRecordCount] = useState<number | undefined>(undefined);
+
+  // Presentation-only gating. The server decides what actually happens; this only decides what the
+  // viewer is offered. See docs/development/security.md.
+  const canRead = context.permissions.has("example.records.read");
+
+  useEffect(() => {
+    if (!canRead) {
+      return;
+    }
+    let cancelled = false;
+    // Relative to this module's own API root. Never `/api/v1/modules/example/records`: that prefix
+    // is Ekklesia's private deployment detail, and building it here would make this artifact
+    // unhostable by a standalone host (ADR 0022).
+    void context.api
+      .request("records")
+      .then((response) => (response.ok ? response.json() : []))
+      .then((records: unknown) => {
+        if (!cancelled) {
+          setRecordCount(Array.isArray(records) ? records.length : 0);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setRecordCount(0);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [canRead, context.api]);
+
+  if (!canRead) {
+    return <p style={{ margin: 0 }}>You do not have access to example records.</p>;
+  }
+
+  return (
+    <section style={{ display: "grid", gap: "0.5rem" }}>
+      <h1 style={{ margin: 0 }}>Example module UI</h1>
+      <p style={{ margin: 0 }} data-testid="record-count">
+        {recordCount === undefined ? "Loading records…" : `${recordCount} record(s)`}
+      </p>
+    </section>
+  );
+}

templates/module/src/ui/index.tsx

@@ -0,0 +1,21 @@
+import { defineModuleUi } from "@ekklesia/module-ui-sdk";
+import { createRoot } from "react-dom/client";
+import { ExampleApp } from "./ExampleApp.js";
+
+/**
+ * The module's compiled UI entrypoint. `pnpm build` bundles this file, and everything it imports,
+ * into the single browser artifact this module's manifest declares as `entrypoints.ui`.
+ *
+ * `id` and `version` must match the manifest: a host verifies both before mounting, so a stale
+ * artifact is caught rather than rendered.
+ */
+export default defineModuleUi({
+  id: "example",
+  version: "0.1.0",
+  mount(container, context) {
+    const root = createRoot(container);
+    root.render(<ExampleApp context={context} />);
+    // React owns a root here, so the mount must return an unmount that releases it.
+    return () => root.unmount();
+  },
+});