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-sdk/tests/module-ui-contract.test.ts

@@ -2,23 +2,32 @@ import { beforeEach, describe, expect, it } from "vitest";
 import {
   defineModuleUi,
   isModuleUiDefinition,
+  MODULE_UI_ABI_VERSION,
   ModuleUiContractError,
   type ModuleUiApiClient,
   type ModuleUiDefinition,
+  type ModuleUiDefinitionInput,
   type ModuleUiHostContext,
   type ModuleUiRealtimeClient,
   parseModuleUiDefinition,
   parseModuleUiExport,
 } from "../src/index.js";
 
-function validDefinition(): ModuleUiDefinition {
+function definitionInput(): ModuleUiDefinitionInput {
   return { id: "announcements", version: "0.1.0", mount: (): void => undefined };
 }
 
+/** What a compiled artifact actually default-exports: the author's declaration plus the ABI marker
+ * `defineModuleUi` stamps on it (ADR 0040). */
+function validDefinition(): ModuleUiDefinition {
+  return { abi: MODULE_UI_ABI_VERSION, ...definitionInput() };
+}
+
 /** 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;
+const abi = MODULE_UI_ABI_VERSION;
 
 const noopRealtime: ModuleUiRealtimeClient = Object.freeze({
   subscribe: () => Object.freeze({ close: noop }),
@@ -29,23 +38,66 @@ function fakeContainer(): Element & { textContent: string } {
 }
 
 describe("module UI definition contract", () => {
-  it("accepts and freezes a valid definition", () => {
-    const definition = defineModuleUi(validDefinition());
+  it("accepts, stamps the ABI on, and freezes a valid definition", () => {
+    const definition = defineModuleUi(definitionInput());
 
     expect(definition.id).toBe("announcements");
     expect(definition.version).toBe("0.1.0");
+    // Stamped by the SDK the artifact compiled against, never written by the author, so it can
+    // never drift from the contract the artifact was actually built for.
+    expect(definition.abi).toBe(MODULE_UI_ABI_VERSION);
+    expect(definition.styles).toBeUndefined();
     expect(Object.isFrozen(definition)).toBe(true);
   });
 
+  it("carries a declared stylesheet through as the artifact's own compiled CSS text", () => {
+    const definition = defineModuleUi({ ...definitionInput(), styles: ".a{color:red}" });
+
+    expect(definition.styles).toBe(".a{color:red}");
+  });
+
+  it("rejects an artifact built against a different mount ABI, with its own code", () => {
+    // The whole point of the marker: a version-1 artifact is reported as "rebuild your module",
+    // not as a malformed definition a developer would hunt for a typo in.
+    const versionOne = { id: "announcements", version: "0.1.0", mount: noop };
+
+    expect(isModuleUiDefinition(versionOne)).toBe(false);
+    try {
+      parseModuleUiDefinition(versionOne);
+      expect.unreachable("expected a contract error");
+    } catch (error) {
+      expect((error as ModuleUiContractError).code).toBe("MODULE_UI_ABI_UNSUPPORTED");
+    }
+    expect(() =>
+      parseModuleUiDefinition({ ...versionOne, abi: MODULE_UI_ABI_VERSION + 1 }),
+    ).toThrowError(expect.objectContaining({ code: "MODULE_UI_ABI_UNSUPPORTED" }));
+  });
+
   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: [] }],
+    ["a blank stylesheet", "   "],
+    ["a non-string stylesheet", 7],
+    ["an array of stylesheets", [".a{}"]],
+  ])("rejects %s", (_label, styles) => {
+    const candidate = { ...validDefinition(), styles };
+
+    expect(isModuleUiDefinition(candidate)).toBe(false);
+    expect(() => parseModuleUiDefinition(candidate)).toThrowError(
+      expect.objectContaining({ code: "MODULE_UI_STYLES_INVALID" }),
+    );
+  });
+
+  it.each<[string, unknown]>([
+    ["a missing id", { abi, version: "0.1.0", mount: noop }],
+    ["a blank id", { abi, id: "   ", version: "0.1.0", mount: noop }],
+    ["a non-string id", { abi, id: 7, version: "0.1.0", mount: noop }],
+    ["a missing version", { abi, id: "announcements", mount: noop }],
+    ["a blank version", { abi, id: "announcements", version: "", mount: noop }],
+    ["a missing mount", { abi, id: "announcements", version: "0.1.0" }],
+    ["a non-function mount", { abi, id: "announcements", version: "0.1.0", mount: "render" }],
+    [
+      "an unknown property",
+      { abi, 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);
@@ -64,7 +116,7 @@ describe("module UI definition contract", () => {
 
   it("reports a malformed definition with a stable, sanitized code", () => {
     try {
-      parseModuleUiDefinition({ id: "announcements" });
+      parseModuleUiDefinition({ abi, id: "announcements" });
       expect.unreachable("expected a contract error");
     } catch (error) {
       expect(error).toBeInstanceOf(ModuleUiContractError);