feat: give module UI real stylesheets, and every artifact its own root

ADR 0023 refused stylesheet imports for a good reason: esbuild would emit a
`.css` sidecar beside the artifact, nothing would declare it, no host would
fetch it, and it would work in a local test and silently do nothing in a real
host. Inline style objects were the whole story. They cannot express
`:hover`, `:focus-visible`, `:disabled`, `@media`, or `@keyframes` — so an
accessible focus treatment was not expressible, and the shared elements added
in the previous commit are built from real CSS for exactly that reason.

Compile the stylesheet into the artifact instead of beside it. A module
imports plain `.css`; the canonical builder resolves local `@import`s through
a nested bundle and turns each file into its compiled text, which the author
declares as `defineModuleUi({ styles })`. One declared file still contains
everything: nothing extra to publish, nothing to fetch, and no way for CSS to
become an asset nobody serves. The build additionally fails if a CSS output
ever appears beside an artifact, so a future loader change cannot bring the
sidecar back. Two rules are enforced with their own codes: a module stylesheet
may reference `--ekklesia-*` and never declare one, and every `@import` must
resolve locally or the artifact would fetch styles at run time. Plain `.css`
only; other dialects are a toolchain decision needing their own ADR.

Then make the isolation real. The generic loader mounts every browser artifact
— primary, display, and later a contributed renderer — inside an open Shadow
DOM root it creates, installs the artifact's stylesheet there, and hands the
artifact an element inside it. Shadow DOM is the one mechanism a browser
actually enforces; a class prefix or a "scope your selectors" instruction is a
convention one mistake defeats, and the failure mode is a module silently
restyling the Dashboard. It applies unconditionally, including to artifacts
with no stylesheet, because a conditional boundary is one a module can fall
out of by editing a source file. Both wrappers are `display: contents` through
base rules installed before the artifact's own, so layout is unchanged and a
full-viewport display can still override `:host`. Unmount removes the whole
root in a `finally`, so a cleanup that throws cannot leave styles behind, and
remounting cannot accumulate a second copy.

This is a correctness boundary for styles and is not described as a sandbox:
the root is `open` precisely because module code is trusted, same-realm code
that could reach `document` anyway.

An artifact's DOM is no longer a direct child of the host's element, so the
mount ABI is versioned explicitly. `defineModuleUi` stamps
`MODULE_UI_ABI_VERSION` so it can never drift from the SDK the artifact
compiled against, and a version-1 artifact fails with its own code — "rebuild
your module", not a typo hunt. No dual acceptance, matching every manifest
cutover here. Migration is one `pnpm build`.

`pnpm boundaries` allows `.css` only under `src/ui/` and `src/display/`: a
stylesheet anywhere else in a module is the undeclared sidecar again, just
relocated.

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

packages/module-ui-host/tests/fixtures/artifact-module/module-styles.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css" {
+  const stylesheet: string;
+  export default stylesheet;
+}

packages/module-ui-host/tests/fixtures/artifact-module/src/ui/index.tsx

@@ -1,15 +1,19 @@
 import { defineModuleUi } from "@ekklesia/module-ui-sdk";
+import styles from "./styles.css";
 
 /**
  * A real module UI compiled by the canonical pipeline. It imports the public SDK so the built
  * artifact proves the whole loop closes: SDK source -> esbuild bundle -> browser URL -> host loader.
  *
  * React is deliberately absent — the module template already proves the React path end to end, and
- * omitting it keeps this artifact small enough to serve as a `data:` URL.
+ * omitting it keeps this artifact small enough to serve as a `data:` URL. It does import a local
+ * stylesheet, so the built artifact also proves the CSS half of that loop: `.css` source -> compiled
+ * text inside the declared artifact -> installed in the isolated root at mount (ADR 0040).
  */
 export default defineModuleUi({
   id: "example",
   version: "0.1.0",
+  styles,
   async mount(container, context) {
     const response = await context.api.request("records");
     const label = context.principal.kind === "authenticated" ? context.principal.userId : "guest";

packages/module-ui-host/tests/fixtures/artifact-module/src/ui/styles.css

@@ -0,0 +1,5 @@
+/* Compiled into the artifact by the canonical builder and installed into its isolated root by the
+ * loader (ADR 0040). It references a global token and declares none of its own. */
+.artifact-label {
+  color: var(--ekklesia-text-primary);
+}

packages/module-ui-host/tests/load-module-ui.test.ts

@@ -1,7 +1,18 @@
 // @vitest-environment happy-dom
-import { ModuleUiContractError, type ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
+import {
+  MODULE_UI_ABI_VERSION,
+  ModuleUiContractError,
+  type ModuleUiHostContext,
+} from "@ekklesia/module-ui-sdk";
 import { describe, expect, it } from "vitest";
-import { loadModuleUi, ModuleUiHostError, type ModuleUiImporter } from "../src/index.js";
+import {
+  loadModuleUi,
+  MODULE_UI_ISOLATION_ATTRIBUTE,
+  MODULE_UI_ISOLATION_ROOT_ATTRIBUTE,
+  MODULE_UI_ISOLATION_STYLE_ATTRIBUTE,
+  ModuleUiHostError,
+  type ModuleUiImporter,
+} from "../src/index.js";
 
 /**
  * A browser-loadable URL for a module built from source text.
@@ -15,10 +26,14 @@ function moduleUrl(source: string): string {
   return `data:text/javascript;base64,${Buffer.from(source, "utf8").toString("base64")}`;
 }
 
-const validArtifact = (options: { id?: string; version?: string; cleanup?: boolean } = {}) => `
+const validArtifact = (
+  options: { id?: string; version?: string; cleanup?: boolean; styles?: string } = {},
+) => `
 export default {
+  abi: ${MODULE_UI_ABI_VERSION},
   id: ${JSON.stringify(options.id ?? "announcements")},
   version: ${JSON.stringify(options.version ?? "1.2.0")},
+  ${options.styles === undefined ? "" : `styles: ${JSON.stringify(options.styles)},`}
   mount(container, context) {
     globalThis.__mounts ??= [];
     globalThis.__mounts.push({ moduleId: context.moduleId, container });
@@ -54,6 +69,20 @@ function container(): Element {
   return element;
 }
 
+/**
+ * What the artifact actually rendered, reached the way a host's own diagnostics would: through the
+ * open shadow root the loader created. The host's container itself holds only the loader's one
+ * wrapper element, which is exactly the isolation ADR 0040 introduced.
+ */
+function artifactRoot(element: Element): Element | null {
+  const shadowHost = element.querySelector(`[${MODULE_UI_ISOLATION_ATTRIBUTE}]`);
+  return shadowHost?.shadowRoot?.querySelector(`[${MODULE_UI_ISOLATION_ROOT_ATTRIBUTE}]`) ?? null;
+}
+
+function artifactText(element: Element): string {
+  return artifactRoot(element)?.textContent ?? "";
+}
+
 const source = { moduleId: "announcements", version: "1.2.0" };
 
 describe("generic module UI host loader", () => {
@@ -70,10 +99,99 @@ describe("generic module UI host loader", () => {
     expect(mounted.moduleId).toBe("announcements");
     expect(mounted.version).toBe("1.2.0");
     expect(mounted.mounted).toBe(true);
-    expect(element.textContent).toBe("mounted:announcements");
+    expect(artifactText(element)).toBe("mounted:announcements");
   });
 
-  it("passes the host's own container and context straight through", async () => {
+  it("mounts the artifact into an isolated root rather than the host's own container", async () => {
+    const element = container();
+
+    const mounted = await loadModuleUi({
+      source: { ...source, url: moduleUrl(validArtifact()) },
+      container: element,
+      context: hostContext([]),
+    });
+
+    // The host's container gained exactly one child: the loader's shadow host.
+    expect(element.children).toHaveLength(1);
+    const shadowHost = element.firstElementChild as Element;
+    expect(shadowHost.hasAttribute(MODULE_UI_ISOLATION_ATTRIBUTE)).toBe(true);
+    expect(shadowHost.shadowRoot).toBe(mounted.shadowRoot);
+    // Open, deliberately: this is a correctness boundary for styles, not a sandbox — an installed
+    // module is trusted code in the host's own realm and could reach `document` regardless.
+    expect(mounted.shadowRoot.mode).toBe("open");
+    // The artifact's DOM is not reachable from the host's own document tree.
+    expect(element.textContent).toBe("");
+  });
+
+  it("installs a declared stylesheet inside the isolated root, exactly once", async () => {
+    const element = container();
+
+    const mounted = await loadModuleUi({
+      source: { ...source, url: moduleUrl(validArtifact({ styles: ".posts{color:red}" })) },
+      container: element,
+      context: hostContext([]),
+    });
+
+    const styles = mounted.shadowRoot.querySelectorAll(
+      `style[${MODULE_UI_ISOLATION_STYLE_ATTRIBUTE}]`,
+    );
+    expect(styles).toHaveLength(1);
+    expect(styles[0]?.textContent).toContain(".posts{color:red}");
+    // The host document never receives the artifact's rules.
+    expect(document.head.querySelector(`style[${MODULE_UI_ISOLATION_STYLE_ATTRIBUTE}]`)).toBeNull();
+  });
+
+  it("installs the host's base rules before the artifact's own, so an artifact can override them", async () => {
+    const element = container();
+
+    const mounted = await loadModuleUi({
+      source: { ...source, url: moduleUrl(validArtifact({ styles: ":host{display:block}" })) },
+      container: element,
+      context: hostContext([]),
+    });
+
+    const stylesheet =
+      mounted.shadowRoot.querySelector(`style[${MODULE_UI_ISOLATION_STYLE_ATTRIBUTE}]`)
+        ?.textContent ?? "";
+    expect(stylesheet.indexOf(":host{display:contents}")).toBeLessThan(
+      stylesheet.indexOf(":host{display:block}"),
+    );
+  });
+
+  it("still mounts an artifact that declares no stylesheet", async () => {
+    const element = container();
+
+    const mounted = await loadModuleUi({
+      source: { ...source, url: moduleUrl(validArtifact()) },
+      container: element,
+      context: hostContext([]),
+    });
+
+    expect(artifactText(element)).toBe("mounted:announcements");
+    expect(
+      mounted.shadowRoot.querySelectorAll(`style[${MODULE_UI_ISOLATION_STYLE_ATTRIBUTE}]`),
+    ).toHaveLength(1);
+  });
+
+  it("never accumulates styles across repeated mounts of the same container", async () => {
+    const element = container();
+    const url = moduleUrl(validArtifact({ styles: ".posts{color:red}" }));
+
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const mounted = await loadModuleUi({
+        source: { ...source, url },
+        container: element,
+        context: hostContext([]),
+      });
+      expect(
+        mounted.shadowRoot.querySelectorAll(`style[${MODULE_UI_ISOLATION_STYLE_ATTRIBUTE}]`),
+      ).toHaveLength(1);
+      await mounted.unmount();
+      expect(element.children).toHaveLength(0);
+    }
+  });
+
+  it("passes the isolated mount target and the host's context straight through", async () => {
     const element = container();
     const requested: string[] = [];
     const context = hostContext(requested);
@@ -86,7 +204,9 @@ describe("generic module UI host loader", () => {
 
     const mounts = (globalThis as { __mounts?: { moduleId: string; container: Element }[] })
       .__mounts;
-    expect(mounts?.at(-1)?.container).toBe(element);
+    // The artifact receives the loader's isolated root, never the host's own element.
+    expect(mounts?.at(-1)?.container).toBe(artifactRoot(element));
+    expect(mounts?.at(-1)?.container).not.toBe(element);
     expect(mounts?.at(-1)?.moduleId).toBe("announcements");
   });
 
@@ -104,7 +224,7 @@ describe("generic module UI host loader", () => {
     expect(requested.join(" ")).not.toContain("/api/v1/modules");
   });
 
-  it("runs the module's cleanup on unmount without touching the host container", async () => {
+  it("runs the module's cleanup and removes the isolated root without touching the host container", async () => {
     const element = container();
     const parent = element.parentElement;
 
@@ -116,7 +236,8 @@ describe("generic module UI host loader", () => {
     await mounted.unmount();
 
     expect(mounted.mounted).toBe(false);
-    expect(element.textContent).toBe("");
+    // The artifact's root, and with it its styles, are gone.
+    expect(element.children).toHaveLength(0);
     // The host owns the container; unmounting a module never removes it.
     expect(element.parentElement).toBe(parent);
     expect(document.body.contains(element)).toBe(true);
@@ -151,13 +272,15 @@ describe("generic module UI host loader", () => {
 
     await expect(mounted.unmount()).resolves.toBeUndefined();
     expect(mounted.mounted).toBe(false);
+    expect(element.children).toHaveLength(0);
   });
 
   it("marks an instance unmounted even when its cleanup throws, so it never re-runs", async () => {
     const element = container();
     const artifact = `
       export default {
-        id: "announcements", version: "1.2.0",
+        abi: ${MODULE_UI_ABI_VERSION}, id: "announcements", version: "1.2.0",
+        styles: ".x{color:red}",
         mount() { return () => { globalThis.__cleanupCalls = (globalThis.__cleanupCalls ?? 0) + 1; throw new Error("cleanup exploded"); }; },
       };`;
 
@@ -169,6 +292,8 @@ describe("generic module UI host loader", () => {
 
     await expect(mounted.unmount()).rejects.toThrow("cleanup exploded");
     expect(mounted.mounted).toBe(false);
+    // A module that fails to clean up must not leave its stylesheet installed in the page.
+    expect(element.children).toHaveLength(0);
     await expect(mounted.unmount()).resolves.toBeUndefined();
     expect((globalThis as { __cleanupCalls?: number }).__cleanupCalls).toBe(1);
   });
@@ -189,16 +314,17 @@ describe("generic module UI host loader", () => {
       context: hostContext([]),
     });
 
-    expect(first.textContent).toBe("mounted:announcements");
-    expect(second.textContent).toBe("mounted:announcements");
+    expect(artifactText(first)).toBe("mounted:announcements");
+    expect(artifactText(second)).toBe("mounted:announcements");
+    expect(a.shadowRoot).not.toBe(b.shadowRoot);
 
     await a.unmount();
 
     // Each handle owns its own cleanup state; unmounting one leaves the other alone.
     expect(a.mounted).toBe(false);
     expect(b.mounted).toBe(true);
-    expect(first.textContent).toBe("");
-    expect(second.textContent).toBe("mounted:announcements");
+    expect(first.children).toHaveLength(0);
+    expect(artifactText(second)).toBe("mounted:announcements");
   });
 
   describe("rejects an artifact before mounting it", () => {
@@ -209,7 +335,7 @@ describe("generic module UI host loader", () => {
       await expect(
         loadModuleUi({ source: { ...source, url }, container: element, context: hostContext([]) }),
       ).rejects.toMatchObject({ code: "MODULE_UI_IDENTITY_MISMATCH" });
-      expect(element.textContent).toBe("");
+      expect(element.children).toHaveLength(0);
     });
 
     it("when the version does not match the manifest", async () => {
@@ -219,7 +345,19 @@ describe("generic module UI host loader", () => {
       await expect(
         loadModuleUi({ source: { ...source, url }, container: element, context: hostContext([]) }),
       ).rejects.toMatchObject({ code: "MODULE_UI_IDENTITY_MISMATCH" });
-      expect(element.textContent).toBe("");
+      expect(element.children).toHaveLength(0);
+    });
+
+    it("when it was built against the previous mount ABI", async () => {
+      const element = container();
+      const url = moduleUrl(
+        'export default { id: "announcements", version: "1.2.0", mount() {} };',
+      );
+
+      await expect(
+        loadModuleUi({ source: { ...source, url }, container: element, context: hostContext([]) }),
+      ).rejects.toMatchObject({ code: "MODULE_UI_ABI_UNSUPPORTED" });
+      expect(element.children).toHaveLength(0);
     });
 
     it("when there is no default export", async () => {
@@ -233,7 +371,9 @@ describe("generic module UI host loader", () => {
 
     it("when the default export is not a module UI definition", async () => {
       const element = container();
-      const url = moduleUrl('export default { id: "announcements", version: "1.2.0" };');
+      const url = moduleUrl(
+        `export default { abi: ${MODULE_UI_ABI_VERSION}, id: "announcements", version: "1.2.0" };`,
+      );
 
       const failure = loadModuleUi({
         source: { ...source, url },
@@ -263,11 +403,12 @@ describe("generic module UI host loader", () => {
     }
   });
 
-  it("reports a throwing mount as a mount failure and registers no cleanup", async () => {
+  it("reports a throwing mount as a mount failure, registers no cleanup, and removes the root", async () => {
     const element = container();
     const url = moduleUrl(`
       export default {
-        id: "announcements", version: "1.2.0",
+        abi: ${MODULE_UI_ABI_VERSION}, id: "announcements", version: "1.2.0",
+        styles: ".x{color:red}",
         mount(container) { container.textContent = "partial"; throw new Error("mount exploded"); },
       };`);
 
@@ -284,9 +425,38 @@ describe("generic module UI host loader", () => {
       expect((error as ModuleUiHostError).message).not.toContain("exploded");
       expect((error as { cause?: Error }).cause?.message).toBe("mount exploded");
     }
-    // No handle exists, so nothing can claim the module is mounted. The container is left exactly
-    // as the module left it: the host owns it and decides what a failed mount looks like.
-    expect(element.textContent).toBe("partial");
+    // No handle exists, so nothing can claim the module is mounted — and a failed mount leaves
+    // neither partial DOM nor an installed stylesheet behind in the host's container.
+    expect(element.children).toHaveLength(0);
+  });
+
+  it("reports an environment with no Shadow DOM as an isolation failure, never as an unisolated mount", async () => {
+    const element = container();
+    const detached = {
+      ownerDocument: document,
+      appendChild: element.appendChild.bind(element),
+    } as unknown as Element;
+    // A container whose created element cannot take a shadow root: the loader must refuse rather
+    // than fall back to mounting the artifact — and its styles — straight into the host's page.
+    const noShadow = new Proxy(detached, {
+      get(target, property, receiver) {
+        if (property === "ownerDocument") {
+          return {
+            createElement: () => ({ setAttribute: () => undefined }),
+          };
+        }
+        return Reflect.get(target, property, receiver);
+      },
+    });
+
+    await expect(
+      loadModuleUi({
+        source: { ...source, url: moduleUrl(validArtifact()) },
+        container: noShadow,
+        context: hostContext([]),
+      }),
+    ).rejects.toMatchObject({ code: "MODULE_UI_ISOLATION_UNAVAILABLE" });
+    expect(element.children).toHaveLength(0);
   });
 
   it("accepts a host-supplied importer for bundlers that need their own escape hatch", async () => {
@@ -294,7 +464,14 @@ describe("generic module UI host loader", () => {
     const seen: string[] = [];
     const importModule: ModuleUiImporter = async (url) => {
       seen.push(url);
-      return { default: { id: "announcements", version: "1.2.0", mount: () => undefined } };
+      return {
+        default: {
+          abi: MODULE_UI_ABI_VERSION,
+          id: "announcements",
+          version: "1.2.0",
+          mount: () => undefined,
+        },
+      };
     };
 
     const mounted = await loadModuleUi({

packages/module-ui-host/tests/real-artifact.test.ts

@@ -5,7 +5,20 @@ import { fileURLToPath } from "node:url";
 import { buildModuleUi } from "@ekklesia/module-ui-build";
 import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
 import { beforeAll, describe, expect, it } from "vitest";
-import { loadModuleUi } from "../src/index.js";
+import {
+  loadModuleUi,
+  MODULE_UI_ISOLATION_ATTRIBUTE,
+  MODULE_UI_ISOLATION_ROOT_ATTRIBUTE,
+} from "../src/index.js";
+
+/** What the artifact rendered, reached through the open shadow root the loader created (ADR 0040). */
+function artifactText(container: Element): string {
+  const shadowHost = container.querySelector(`[${MODULE_UI_ISOLATION_ATTRIBUTE}]`);
+  return (
+    shadowHost?.shadowRoot?.querySelector(`[${MODULE_UI_ISOLATION_ROOT_ATTRIBUTE}]`)?.textContent ??
+    ""
+  );
+}
 
 const fixtureDirectory = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -80,12 +93,32 @@ describe("loading a real compiled artifact", () => {
       context: ekklesiaContext(requested),
     });
 
-    expect(container.textContent).toBe("example:200:user-123");
+    expect(artifactText(container)).toBe("example:200:user-123");
     await mounted.unmount();
-    expect(container.textContent).toBe("");
+    expect(container.children).toHaveLength(0);
     expect(mounted.mounted).toBe(false);
   });
 
+  it("compiles the fixture's stylesheet into the artifact and installs it in the isolated root", async () => {
+    const container = document.createElement("div");
+
+    // No sidecar: the whole stylesheet travels inside the one declared JavaScript artifact.
+    expect(artifactSource).toContain(".artifact-label");
+
+    const mounted = await loadModuleUi({
+      source: { moduleId: "example", version: "0.1.0", url: artifactUrl },
+      container,
+      context: ekklesiaContext([]),
+    });
+
+    const stylesheet = mounted.shadowRoot.querySelector("style")?.textContent ?? "";
+    expect(stylesheet).toContain(".artifact-label");
+    expect(stylesheet).toContain("var(--ekklesia-text-primary)");
+    expect(document.head.textContent ?? "").not.toContain(".artifact-label");
+
+    await mounted.unmount();
+  });
+
   it("still rejects the real artifact when the host expects a different version", async () => {
     await expect(
       loadModuleUi({
@@ -118,8 +151,8 @@ describe("loading a real compiled artifact", () => {
     // the module asked for "records" both times and resolved nothing itself.
     expect(ekklesiaRequests).toEqual(["/api/v1/modules/example/records"]);
     expect(standaloneRequests).toEqual(["https://example.test/api/records"]);
-    expect(ekklesiaContainer.textContent).toBe("example:200:user-123");
-    expect(standaloneContainer.textContent).toBe("example:200:guest");
+    expect(artifactText(ekklesiaContainer)).toBe("example:200:user-123");
+    expect(artifactText(standaloneContainer)).toBe("example:200:guest");
 
     await inEkklesia.unmount();
     await inStandalone.unmount();