feat: add display kiosk host

surfaces/shell/tests/display-app.test.tsx

@@ -0,0 +1,710 @@
+import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
+import { act, Component, type ReactElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostApp } from "../src/browser/HostApp.js";
+import { DisplayApp } from "../src/display/DisplayApp.js";
+import type {
+  EkklesiaHostConfig,
+  HostEventSourceFactory,
+  HostEventSourceOptions,
+} from "../src/host-protocol.js";
+
+declare global {
+  // eslint-disable-next-line no-var
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+const apiBaseUrl = "https://ekklesia.example.test";
+
+let container: HTMLDivElement;
+let root: Root;
+let consoleError: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+  consoleError.mockRestore();
+});
+
+function descriptorPayload(id = "announcements", version = "1.2.0") {
+  return {
+    module: {
+      api: { baseUrl: `/api/v1/modules/${id}` },
+      display: { url: `/api/v1/module-ui/${id}/${version}/display` },
+      id,
+      permissions: [`${id}.slideshow.view`],
+      realtime: { baseUrl: `/api/v1/module-realtime/${id}` },
+      version,
+    },
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "content-type": "application/json" },
+    status,
+  });
+}
+
+interface PlatformOptions {
+  readonly descriptorStatus?: number;
+  readonly principal?: unknown;
+}
+
+function platform(options: PlatformOptions = {}) {
+  const calls: Array<{ readonly init: RequestInit | undefined; readonly url: string }> = [];
+  const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ init, url });
+    if (url.endsWith("/api/v1/principal")) {
+      return json(options.principal ?? { kind: "authenticated", userId: "user-1" });
+    }
+    if (url.endsWith("/api/v1/module-displays/announcements")) {
+      return json(descriptorPayload(), options.descriptorStatus ?? 200);
+    }
+    if (url.endsWith("/api/v1/modules/announcements/slides")) {
+      return json([{ id: "slide-1" }]);
+    }
+    return json({ code: "NOT_FOUND" }, 404);
+  }) as unknown as typeof globalThis.fetch;
+  return { calls, fetch };
+}
+
+class FakeEventSource {
+  readonly CLOSED = 2 as const;
+  readonly CONNECTING = 0 as const;
+  readonly OPEN = 1 as const;
+  readonly listeners = new Map<string, Set<EventListener>>();
+  closeCalls = 0;
+  readyState: number = this.CONNECTING;
+
+  addEventListener(type: string, listener: EventListener): void {
+    const listeners = this.listeners.get(type) ?? new Set<EventListener>();
+    listeners.add(listener);
+    this.listeners.set(type, listeners);
+  }
+
+  removeEventListener(type: string, listener: EventListener): void {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  close(): void {
+    this.closeCalls += 1;
+    this.readyState = this.CLOSED;
+  }
+
+  emit(type: string, data?: string): void {
+    if (type === "open") {
+      this.readyState = this.OPEN;
+    }
+    const event = Object.freeze({ data, type }) as unknown as Event;
+    for (const listener of this.listeners.get(type) ?? []) {
+      listener(event);
+    }
+  }
+}
+
+function eventSources() {
+  const calls: Array<{
+    readonly options: HostEventSourceOptions;
+    readonly source: FakeEventSource;
+    readonly url: string;
+  }> = [];
+  const factory = ((url: string, options: HostEventSourceOptions): EventSource => {
+    const source = new FakeEventSource();
+    calls.push({ options, source, url });
+    return source as unknown as EventSource;
+  }) as HostEventSourceFactory;
+  return { calls, factory };
+}
+
+function artifact(
+  id = "announcements",
+  version = "1.2.0",
+  options: {
+    readonly cleanup?: () => void;
+    readonly mount?: (container: Element, context: ModuleUiHostContext) => undefined | (() => void);
+  } = {},
+) {
+  return {
+    default: {
+      id,
+      mount(element: Element, context: ModuleUiHostContext) {
+        if (options.mount) {
+          return options.mount(element, context);
+        }
+        element.textContent = `${context.moduleId}:display`;
+        return () => {
+          options.cleanup?.();
+          element.replaceChildren();
+        };
+      },
+      version,
+    },
+  };
+}
+
+async function render(
+  config: EkklesiaHostConfig,
+  importModule?: (url: string) => Promise<unknown>,
+  moduleId = "announcements",
+): Promise<void> {
+  await act(async () => {
+    root.render(
+      <DisplayApp
+        config={config}
+        {...(importModule ? { importModule } : {})}
+        moduleId={moduleId}
+      />,
+    );
+  });
+}
+
+function query(testId: string): HTMLElement | null {
+  return container.querySelector(`[data-testid="${testId}"]`);
+}
+
+function moduleUrl(source: string): string {
+  return `data:text/javascript;base64,${Buffer.from(source, "utf8").toString("base64")}`;
+}
+
+describe("display host — full-viewport boundary", () => {
+  it("mounts only the display artifact with no Dashboard chrome", async () => {
+    const server = platform();
+    const imported: string[] = [];
+    await render({ apiBaseUrl, fetch: server.fetch }, async (url) => {
+      imported.push(url);
+      return artifact();
+    });
+
+    expect(imported).toEqual([`${apiBaseUrl}/api/v1/module-ui/announcements/1.2.0/display`]);
+    expect(query("display-module-container")?.textContent).toBe("announcements:display");
+    expect(container.querySelector("header")).toBeNull();
+    expect(container.querySelector("nav")).toBeNull();
+    expect(container.querySelector("aside")).toBeNull();
+    expect(container.textContent).not.toContain("Ekklesia");
+    expect(query("display-host")?.style.height).toBe("100%");
+    expect(query("display-host")?.style.minHeight).toBe("100dvh");
+  });
+
+  it("constructs the same browser-safe API, principal, permission, and realtime context", async () => {
+    const server = platform();
+    const live = eventSources();
+    let seenContext: ModuleUiHostContext | undefined;
+    await render({ apiBaseUrl, eventSourceFactory: live.factory, fetch: server.fetch }, async () =>
+      artifact("announcements", "1.2.0", {
+        mount(element, context) {
+          seenContext = context;
+          void context.api.request("slides");
+          const subscription = context.realtime.subscribe("state", {});
+          element.textContent = context.permissions.has("announcements.slideshow.view")
+            ? "permitted"
+            : "denied";
+          return () => subscription.close();
+        },
+      }),
+    );
+
+    expect(Object.keys(seenContext ?? {}).sort()).toEqual([
+      "api",
+      "moduleId",
+      "permissions",
+      "principal",
+      "realtime",
+    ]);
+    expect(seenContext?.principal).toEqual({ kind: "authenticated", userId: "user-1" });
+    expect(query("display-module-container")?.textContent).toBe("permitted");
+    expect(
+      server.calls.some((call) => call.url.endsWith("/api/v1/modules/announcements/slides")),
+    ).toBe(true);
+    expect(live.calls[0]).toMatchObject({
+      options: { withCredentials: true },
+      url: `${apiBaseUrl}/api/v1/module-realtime/announcements/state`,
+    });
+  });
+
+  it("uses a genuine dynamic import and renders an Announcements snapshot with its direct object URL unchanged", async () => {
+    const server = platform();
+    const live = eventSources();
+    const requestedArtifacts: string[] = [];
+    const source = `
+      export default {
+        id: "announcements",
+        version: "1.2.0",
+        mount(container, context) {
+          const image = document.createElement("img");
+          image.setAttribute("data-testid", "announcement-slide");
+          container.append(image);
+          const subscription = context.realtime.subscribe("state", {
+            onSnapshot(state) {
+              image.src = state.mode === "on" ? state.slides[state.currentSlide].url : "";
+            },
+            onUpdate(state) {
+              image.src = state.mode === "on" ? state.slides[state.currentSlide].url : "";
+            },
+          });
+          return () => { subscription.close(); container.replaceChildren(); };
+        },
+      };
+    `;
+
+    await render(
+      { apiBaseUrl, eventSourceFactory: live.factory, fetch: server.fetch },
+      async (url) => {
+        requestedArtifacts.push(url);
+        return import(moduleUrl(source));
+      },
+    );
+
+    const deliveryUrl =
+      "https://objects.example.test/ekklesia-announcements-assets/slides%2Fwelcome.jpg?X-Amz-Signature=opaque";
+    await act(async () => {
+      live.calls[0]?.source.emit("open");
+      live.calls[0]?.source.emit(
+        "snapshot",
+        JSON.stringify({
+          payload: {
+            currentSlide: 0,
+            mode: "on",
+            slideSeconds: 7,
+            slides: [{ url: deliveryUrl }],
+          },
+          sequence: 1,
+        }),
+      );
+    });
+
+    expect(requestedArtifacts).toEqual([
+      `${apiBaseUrl}/api/v1/module-ui/announcements/1.2.0/display`,
+    ]);
+    expect(container.querySelector('[data-testid="announcement-slide"]')?.getAttribute("src")).toBe(
+      deliveryUrl,
+    );
+    expect(container.innerHTML).not.toContain("socket.io");
+    expect(container.innerHTML).not.toContain("mqtt");
+  });
+
+  it("keeps one Announcements-shaped module's management and slideshow roots distinct", async () => {
+    const live = eventSources();
+    const requestedArtifacts: string[] = [];
+    const fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/v1/principal")) {
+        return json({ kind: "authenticated", userId: "user-1" });
+      }
+      if (url.endsWith("/api/v1/dashboard/navigation")) {
+        return json({
+          groups: [],
+          ungrouped: [
+            {
+              module: {
+                api: { baseUrl: "/api/v1/modules/announcements" },
+                id: "announcements",
+                permissions: ["announcements.slideshow.view"],
+                realtime: { baseUrl: "/api/v1/module-realtime/announcements" },
+                ui: { url: "/api/v1/module-ui/announcements/1.2.0" },
+                version: "1.2.0",
+              },
+              name: "Announcements",
+            },
+          ],
+        });
+      }
+      if (url.endsWith("/api/v1/module-displays/announcements")) {
+        return json(descriptorPayload());
+      }
+      return json({ code: "NOT_FOUND" }, 404);
+    }) as unknown as typeof globalThis.fetch;
+    const config = { apiBaseUrl, eventSourceFactory: live.factory, fetch };
+    const importer = async (url: string): Promise<unknown> => {
+      requestedArtifacts.push(url);
+      if (!url.endsWith("/display")) {
+        return artifact("announcements", "1.2.0", {
+          mount(element) {
+            element.textContent = "announcement management";
+            return () => element.replaceChildren();
+          },
+        });
+      }
+      return artifact("announcements", "1.2.0", {
+        mount(element, context) {
+          const image = document.createElement("img");
+          image.dataset.testid = "both-role-slide";
+          element.append(image);
+          const subscription = context.realtime.subscribe<{
+            readonly currentSlide: number;
+            readonly mode: "off" | "on";
+            readonly slides: readonly { readonly url: string }[];
+          }>("state", {
+            onSnapshot(state) {
+              image.src = state.mode === "on" ? (state.slides[state.currentSlide]?.url ?? "") : "";
+            },
+          });
+          return () => {
+            subscription.close();
+            element.replaceChildren();
+          };
+        },
+      });
+    };
+
+    await act(async () => root.render(<HostApp config={config} importModule={importer} />));
+    expect(container.textContent).toContain("announcement management");
+    expect(container.querySelector("nav")).not.toBeNull();
+    expect(requestedArtifacts).toEqual([`${apiBaseUrl}/api/v1/module-ui/announcements/1.2.0`]);
+
+    await act(async () => root.unmount());
+    root = createRoot(container);
+    await act(async () =>
+      root.render(<DisplayApp config={config} importModule={importer} moduleId="announcements" />),
+    );
+    const deliveryUrl =
+      "https://objects.example.test/module-assets/slide.jpg?X-Amz-Signature=opaque";
+    await act(async () => {
+      live.calls[0]?.source.emit("open");
+      live.calls[0]?.source.emit(
+        "snapshot",
+        JSON.stringify({
+          payload: { currentSlide: 0, mode: "on", slides: [{ url: deliveryUrl }] },
+          sequence: 1,
+        }),
+      );
+    });
+
+    expect(requestedArtifacts).toEqual([
+      `${apiBaseUrl}/api/v1/module-ui/announcements/1.2.0`,
+      `${apiBaseUrl}/api/v1/module-ui/announcements/1.2.0/display`,
+    ]);
+    expect(container.querySelector('[data-testid="both-role-slide"]')?.getAttribute("src")).toBe(
+      deliveryUrl,
+    );
+    expect(container.querySelector("nav")).toBeNull();
+    expect(container.querySelector("header")).toBeNull();
+    expect(JSON.stringify(requestedArtifacts)).not.toMatch(/socket\.io|mqtt|10\.|localhost/u);
+  });
+});
+
+describe("display host — authentication and controlled failures", () => {
+  it("mounts nothing and never requests a descriptor for an anonymous browser", async () => {
+    const server = platform({ principal: { kind: "anonymous" } });
+    const importer = vi.fn(async () => artifact());
+
+    await render({ apiBaseUrl, fetch: server.fetch }, importer);
+
+    expect(query("display-host-signed-out")).not.toBeNull();
+    expect(importer).not.toHaveBeenCalled();
+    expect(server.calls.map((call) => call.url)).toEqual([`${apiBaseUrl}/api/v1/principal`]);
+  });
+
+  it("does not import protected display code when the descriptor is denied or unavailable", async () => {
+    for (const status of [403, 404]) {
+      const server = platform({ descriptorStatus: status });
+      const importer = vi.fn(async () => artifact());
+      await render({ apiBaseUrl, fetch: server.fetch }, importer);
+
+      expect(query("display-host-unavailable"), String(status)).not.toBeNull();
+      expect(importer, String(status)).not.toHaveBeenCalled();
+    }
+  });
+
+  it("clears partial mount DOM, renders no caught detail, and retries in a fresh container", async () => {
+    const server = platform();
+    let attempts = 0;
+    const containers: Element[] = [];
+    const importer = vi.fn(async () => {
+      attempts += 1;
+      return artifact("announcements", "1.2.0", {
+        mount(element) {
+          containers.push(element);
+          if (attempts === 1) {
+            element.textContent = "secret at /srv/modules/announcements";
+            throw new Error("mount exploded with token=secret");
+          }
+          element.textContent = "recovered";
+          return () => element.replaceChildren();
+        },
+      });
+    });
+
+    await render({ apiBaseUrl, fetch: server.fetch }, importer);
+
+    expect(query("display-error")).not.toBeNull();
+    expect(container.textContent).not.toContain("/srv/");
+    expect(container.textContent).not.toContain("secret");
+    await act(async () => query("display-retry")?.click());
+
+    expect(query("display-error")).toBeNull();
+    expect(query("display-module-container")?.textContent).toBe("recovered");
+    expect(containers).toHaveLength(2);
+    expect(containers[0]).not.toBe(containers[1]);
+    expect(containers[0]?.isConnected).toBe(false);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[ekklesia] display UI failure module=announcements code=MODULE_UI_MOUNT_FAILED",
+    );
+  });
+
+  it.each([
+    "error",
+    "unhandledrejection",
+  ] as const)("turns a post-mount page %s into one sanitized failure with manual retry", async (eventType) => {
+    const server = platform();
+    const cleanups: Element[] = [];
+    const mountedInto: Element[] = [];
+    const importer = vi.fn(async () =>
+      artifact("announcements", "1.2.0", {
+        mount(element) {
+          mountedInto.push(element);
+          element.textContent = "private render at /srv/modules/announcements";
+          return () => {
+            cleanups.push(element);
+            element.replaceChildren();
+          };
+        },
+      }),
+    );
+
+    await render({ apiBaseUrl, fetch: server.fetch }, importer);
+    expect(query("display-module-container")?.textContent).toContain("/srv/modules");
+    consoleError.mockClear();
+
+    await act(async () => {
+      const event =
+        eventType === "error"
+          ? new ErrorEvent("error", {
+              error: new Error("token=secret-render-error"),
+              message: "token=secret-render-error",
+            })
+          : new Event("unhandledrejection");
+      window.dispatchEvent(event);
+      // A second signal from the same failed render must not run cleanup or transition twice.
+      window.dispatchEvent(new Event(eventType));
+    });
+
+    expect(query("display-error")).not.toBeNull();
+    expect(query("display-module-container")?.textContent).toBe("");
+    expect(container.textContent).toBe("This display could not be loaded.Retry");
+    expect(container.textContent).not.toMatch(/secret|\/srv\//u);
+    expect(importer).toHaveBeenCalledTimes(1);
+    expect(cleanups).toEqual([mountedInto[0]]);
+    expect(consoleError).toHaveBeenCalledTimes(1);
+    expect(consoleError).toHaveBeenCalledWith(
+      `[ekklesia] display UI failure module=announcements code=${
+        eventType === "error" ? "DISPLAY_UI_RUNTIME_ERROR" : "DISPLAY_UI_UNHANDLED_REJECTION"
+      }`,
+    );
+
+    await act(async () => query("display-retry")?.click());
+
+    expect(importer).toHaveBeenCalledTimes(2);
+    expect(query("display-error")).toBeNull();
+    expect(query("display-module-container")?.textContent).toContain("/srv/modules");
+    expect(mountedInto[0]?.isConnected).toBe(false);
+    expect(mountedInto[1]?.isConnected).toBe(true);
+  });
+
+  it("catches a React render failure reported after the artifact mount has returned", async () => {
+    const server = platform();
+    const cleanup = vi.fn();
+    await render({ apiBaseUrl, fetch: server.fetch }, async () =>
+      artifact("announcements", "1.2.0", {
+        mount(element) {
+          const moduleRoot = createRoot(element);
+          class ReportRenderFailure extends Component<{ readonly children: ReactNode }> {
+            override componentDidCatch(error: unknown): void {
+              // React's browser default reports an uncaught render through the page's global error
+              // facility. This test boundary makes that report deterministic under happy-dom,
+              // whose test runner otherwise intercepts the global exception first.
+              window.dispatchEvent(
+                new ErrorEvent("error", {
+                  cancelable: true,
+                  error,
+                  message: error instanceof Error ? error.message : "display render failure",
+                }),
+              );
+            }
+
+            override render(): ReactNode {
+              return this.props.children;
+            }
+          }
+          const BrokenDisplay = (): ReactElement => {
+            throw new Error("late component secret at /srv/modules/announcements");
+          };
+          moduleRoot.render(
+            <ReportRenderFailure>
+              <BrokenDisplay />
+            </ReportRenderFailure>,
+          );
+          return () => {
+            cleanup();
+            moduleRoot.unmount();
+          };
+        },
+      }),
+    );
+
+    await act(async () => undefined);
+
+    expect(query("display-error")).not.toBeNull();
+    expect(container.textContent).toBe("This display could not be loaded.Retry");
+    expect(container.textContent).not.toMatch(/secret|\/srv\//u);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not treat a module media/resource error as a crashed display runtime", async () => {
+    const server = platform();
+    const cleanup = vi.fn();
+    await render({ apiBaseUrl, fetch: server.fetch }, async () =>
+      artifact("announcements", "1.2.0", {
+        mount(element) {
+          const image = document.createElement("img");
+          image.dataset.testid = "display-media";
+          element.append(image);
+          return () => cleanup();
+        },
+      }),
+    );
+
+    await act(async () => {
+      container.querySelector('[data-testid="display-media"]')?.dispatchEvent(
+        new ErrorEvent("error", {
+          bubbles: true,
+          cancelable: true,
+          message: "a signed media URL expired",
+        }),
+      );
+    });
+
+    expect(query("display-error")).toBeNull();
+    expect(query("display-media")).not.toBeNull();
+    expect(cleanup).not.toHaveBeenCalled();
+  });
+
+  it("removes the page failure listeners when a display attempt is torn down", async () => {
+    const server = platform();
+    const cleanup = vi.fn();
+    await render({ apiBaseUrl, fetch: server.fetch }, async () =>
+      artifact("announcements", "1.2.0", { cleanup }),
+    );
+
+    await act(async () => root.render(null));
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    consoleError.mockClear();
+
+    window.dispatchEvent(new ErrorEvent("error", { message: "after teardown" }));
+    window.dispatchEvent(new Event("unhandledrejection"));
+
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(consoleError).not.toHaveBeenCalled();
+  });
+});
+
+describe("display host — independent instances and stale work", () => {
+  it("mounts and unmounts two browser instances independently", async () => {
+    const server = platform();
+    const cleanups: string[] = [];
+    const importer = async () =>
+      artifact("announcements", "1.2.0", {
+        cleanup: () => cleanups.push("cleanup"),
+      });
+    const config = { apiBaseUrl, fetch: server.fetch };
+
+    await act(async () => {
+      root.render(
+        <>
+          <DisplayApp
+            config={config}
+            importModule={importer}
+            key="first"
+            moduleId="announcements"
+          />
+          <DisplayApp
+            config={config}
+            importModule={importer}
+            key="second"
+            moduleId="announcements"
+          />
+        </>,
+      );
+    });
+    expect(container.querySelectorAll('[data-testid="display-module-container"]')).toHaveLength(2);
+
+    await act(async () => {
+      root.render(
+        <DisplayApp
+          config={config}
+          importModule={importer}
+          key="second"
+          moduleId="announcements"
+        />,
+      );
+    });
+
+    expect(cleanups).toHaveLength(1);
+    expect(container.querySelectorAll('[data-testid="display-module-container"]')).toHaveLength(1);
+    expect(query("display-module-container")?.textContent).toBe("announcements:display");
+  });
+
+  it("discards a late import into its detached container without disturbing the newer route", async () => {
+    let releaseAnnouncements: (() => void) | undefined;
+    const pendingAnnouncements = new Promise<void>((resolve) => {
+      releaseAnnouncements = resolve;
+    });
+    const mountedInto: Element[] = [];
+    const staleUnmounts: Element[] = [];
+    const fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/v1/principal")) {
+        return json({ kind: "authenticated", userId: "user-1" });
+      }
+      if (url.endsWith("/api/v1/module-displays/calendar")) {
+        return json(descriptorPayload("calendar", "2.0.0"));
+      }
+      return json(descriptorPayload());
+    }) as unknown as typeof globalThis.fetch;
+    const config = { apiBaseUrl, fetch };
+    const importer = async (url: string): Promise<unknown> => {
+      const isCalendar = url.includes("/calendar/");
+      if (!isCalendar) {
+        await pendingAnnouncements;
+      }
+      return artifact(isCalendar ? "calendar" : "announcements", isCalendar ? "2.0.0" : "1.2.0", {
+        mount(element) {
+          mountedInto.push(element);
+          element.textContent = isCalendar ? "calendar-live" : "announcements-stale";
+          return () => {
+            if (!isCalendar) {
+              staleUnmounts.push(element);
+            }
+            element.replaceChildren();
+          };
+        },
+      });
+    };
+
+    await render(config, importer);
+    await render(config, importer, "calendar");
+    expect(query("display-module-container")?.textContent).toBe("calendar-live");
+    const liveContainer = query("display-module-container");
+
+    await act(async () => {
+      releaseAnnouncements?.();
+      await pendingAnnouncements;
+    });
+
+    expect(query("display-module-container")).toBe(liveContainer);
+    expect(liveContainer?.textContent).toBe("calendar-live");
+    const staleContainer = mountedInto.find((element) => element !== liveContainer);
+    expect(staleContainer?.isConnected).toBe(false);
+    expect(staleUnmounts).toEqual([staleContainer]);
+  });
+});

surfaces/shell/tests/display-assets.test.ts

@@ -0,0 +1,48 @@
+// @vitest-environment node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { displayHostAssetUrls } from "../src/display-assets.js";
+
+const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+describe("display host asset locator", () => {
+  it("exports only frozen immutable href strings for the two exact built files", () => {
+    expect(Object.isFrozen(displayHostAssetUrls)).toBe(true);
+    expect(displayHostAssetUrls).toEqual({
+      html: new URL("dist/browser/display/index.html", `file://${packageDirectory}/`).href,
+      script: new URL("dist/browser/display/app.js", `file://${packageDirectory}/`).href,
+    });
+    expect(typeof displayHostAssetUrls.html).toBe("string");
+    expect(typeof displayHostAssetUrls.script).toBe("string");
+  });
+
+  it("publishes the locator through a narrow package subpath, not the shell root barrel", async () => {
+    const manifest = JSON.parse(
+      await readFile(path.join(packageDirectory, "package.json"), "utf8"),
+    ) as { exports?: Record<string, unknown> };
+    expect(manifest.exports?.["./display-assets"]).toEqual({
+      import: "./dist/display-assets.js",
+      types: "./dist/display-assets.d.ts",
+    });
+
+    const rootSource = await readFile(path.join(packageDirectory, "src/index.ts"), "utf8");
+    expect(rootSource).not.toContain("displayHostAssetUrls");
+    expect(rootSource).not.toContain("display-assets");
+  });
+
+  it("uses a fixed root script asset and only structural full-viewport page styles", async () => {
+    const html = await readFile(path.join(packageDirectory, "display.html"), "utf8");
+
+    expect(html).toContain('id="ekklesia-display"');
+    expect(html).toContain('src="/assets/ekklesia-display/app.js"');
+    expect(html).toContain('name="viewport"');
+    expect(html).toContain("height: 100%");
+    expect(html).toContain("margin: 0");
+    expect(html).not.toContain("<nav");
+    expect(html).not.toContain("<header");
+    expect(html).not.toContain("<aside");
+    expect(html).not.toContain("fullscreen");
+  });
+});

surfaces/shell/tests/display-host-protocol.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  bootstrapDisplayHost,
+  loadModuleDisplay,
+  moduleDisplayDescriptorPath,
+  parseDisplayRoute,
+  parseHostModuleDisplay,
+} from "../src/host-protocol.js";
+
+const apiBaseUrl = "https://ekklesia.example.test";
+
+function displayPayload(overrides: Record<string, unknown> = {}): {
+  readonly module: Record<string, unknown>;
+} {
+  return {
+    module: {
+      api: { baseUrl: "/api/v1/modules/announcements" },
+      display: { url: "/api/v1/module-ui/announcements/1.2.0/display" },
+      id: "announcements",
+      permissions: ["announcements.slideshow.view"],
+      realtime: { baseUrl: "/api/v1/module-realtime/announcements" },
+      version: "1.2.0",
+      ...overrides,
+    },
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "content-type": "application/json" },
+    status,
+  });
+}
+
+describe("display host protocol — strict descriptor", () => {
+  it("parses the exact display role into the generic mount descriptor", () => {
+    const parsed = parseHostModuleDisplay(displayPayload());
+
+    expect(parsed).toEqual({
+      module: {
+        apiBaseUrl: "/api/v1/modules/announcements",
+        id: "announcements",
+        permissions: ["announcements.slideshow.view"],
+        realtimeBaseUrl: "/api/v1/module-realtime/announcements",
+        uiUrl: "/api/v1/module-ui/announcements/1.2.0/display",
+        version: "1.2.0",
+      },
+    });
+    expect(Object.isFrozen(parsed)).toBe(true);
+    expect(Object.isFrozen(parsed.module)).toBe(true);
+    expect(Object.isFrozen(parsed.module.permissions)).toBe(true);
+  });
+
+  it("rejects malformed identities, shapes, permissions, and any non-root-relative URL", () => {
+    const invalid: unknown[] = [
+      {},
+      { ...displayPayload(), extra: true },
+      displayPayload({ id: "Announcements" }),
+      displayPayload({ id: "announcements/other" }),
+      displayPayload({ id: "a".repeat(65) }),
+      displayPayload({ version: "v1.2.0" }),
+      displayPayload({ version: "01.2.0" }),
+      displayPayload({ permissions: "announcements.slideshow.view" }),
+      displayPayload({ permissions: [""] }),
+      displayPayload({
+        permissions: ["announcements.slideshow.view", "announcements.slideshow.view"],
+      }),
+      displayPayload({ api: { baseUrl: "https://evil.example.test/api" } }),
+      displayPayload({ display: { url: "//evil.example.test/display.js" } }),
+      displayPayload({ display: { url: "/display.js?token=secret" } }),
+      displayPayload({ display: { url: "/api/%2e%2e/grants" } }),
+      displayPayload({ display: { url: "/api/%2Fgrants" } }),
+      displayPayload({ display: { url: "/api//display.js" } }),
+      displayPayload({ realtime: { baseUrl: "/\\evil.example.test/live" } }),
+      displayPayload({ display: { url: "/display.js", extra: true } }),
+    ];
+
+    for (const payload of invalid) {
+      expect(() => parseHostModuleDisplay(payload), JSON.stringify(payload)).toThrowError(
+        expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }),
+      );
+    }
+  });
+
+  it("does not accept a Dashboard artifact in place of a display artifact", () => {
+    const module = (displayPayload() as { module: Record<string, unknown> }).module;
+    const { display: _display, ...withoutDisplay } = module;
+
+    expect(() =>
+      parseHostModuleDisplay({
+        module: {
+          ...withoutDisplay,
+          ui: { url: "/api/v1/module-ui/announcements/1.2.0" },
+        },
+      }),
+    ).toThrowError(expect.objectContaining({ code: "HOST_RESPONSE_INVALID" }));
+  });
+});
+
+describe("display host protocol — outer route", () => {
+  it("accepts one exact stable version-independent module route", () => {
+    expect(parseDisplayRoute("/display/announcements")).toBe("announcements");
+    expect(moduleDisplayDescriptorPath("announcements")).toBe(
+      "/api/v1/module-displays/announcements",
+    );
+  });
+
+  it("rejects extra segments, trailing slashes, malformed escapes, and path escapes", () => {
+    for (const pathname of [
+      "/display",
+      "/display/",
+      "/display/announcements/",
+      "/display/announcements/settings",
+      "/display/%2fapi",
+      "/display/..",
+      "/display/%",
+      "/modules/announcements/display",
+    ]) {
+      expect(() => parseDisplayRoute(pathname), pathname).toThrowError(
+        expect.objectContaining({ code: "DISPLAY_ROUTE_INVALID" }),
+      );
+    }
+  });
+});
+
+describe("display host protocol — authenticated bootstrap", () => {
+  it("loads principal first, then the exact descriptor, with host-owned credentials", async () => {
+    const calls: Array<{ init: RequestInit | undefined; url: string }> = [];
+    const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      calls.push({ init, url });
+      return url.endsWith("/api/v1/principal")
+        ? json({ kind: "authenticated", userId: "user-1" })
+        : json(displayPayload());
+    }) as unknown as typeof globalThis.fetch;
+
+    const bootstrap = await bootstrapDisplayHost({ apiBaseUrl, fetch }, "announcements");
+
+    expect(bootstrap.status).toBe("ready");
+    expect(calls.map((call) => call.url)).toEqual([
+      `${apiBaseUrl}/api/v1/principal`,
+      `${apiBaseUrl}/api/v1/module-displays/announcements`,
+    ]);
+    expect(calls.every((call) => call.init?.credentials === "include")).toBe(true);
+  });
+
+  it("does not probe a display descriptor for an anonymous principal", async () => {
+    const fetch = vi.fn(async () =>
+      json({ kind: "anonymous" }),
+    ) as unknown as typeof globalThis.fetch;
+
+    const bootstrap = await bootstrapDisplayHost({ apiBaseUrl, fetch }, "announcements");
+
+    expect(bootstrap).toEqual({ principal: { kind: "anonymous" }, status: "signed-out" });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("distinguishes denied, unavailable, unauthenticated, and infrastructure failures safely", async () => {
+    for (const [status, code] of [
+      [401, "HOST_UNAUTHENTICATED"],
+      [403, "DISPLAY_ACCESS_DENIED"],
+      [404, "DISPLAY_NOT_AVAILABLE"],
+      [503, "HOST_REQUEST_FAILED"],
+    ] as const) {
+      const fetch = vi.fn(async () =>
+        json({ detail: "/srv/modules/announcements secret-token" }, status),
+      ) as unknown as typeof globalThis.fetch;
+      const error = await loadModuleDisplay({ apiBaseUrl, fetch }, "announcements").catch(
+        (caught: unknown) => caught,
+      );
+
+      expect(error).toMatchObject({ code });
+      expect((error as Error).message).not.toContain("/srv/");
+      expect((error as Error).message).not.toContain("secret-token");
+    }
+  });
+
+  it("rejects a stale or misrouted descriptor whose identity differs from the requested display", async () => {
+    const fetch = vi.fn(async () =>
+      json(displayPayload({ id: "calendar" })),
+    ) as unknown as typeof globalThis.fetch;
+
+    await expect(loadModuleDisplay({ apiBaseUrl, fetch }, "announcements")).rejects.toMatchObject({
+      code: "HOST_RESPONSE_INVALID",
+    });
+  });
+});

surfaces/shell/tests/modularity.test.ts

@@ -170,3 +170,53 @@ describe("the shell builds no module knowledge into its bundle", () => {
     expect(bundle).not.toContain("createObjectURL");
   });
 });
+
+describe("the display host is a separate generic browser bundle", () => {
+  let bundle: string;
+
+  beforeAll(async () => {
+    const result = await build({
+      absWorkingDir: packageDirectory,
+      bundle: true,
+      define: {
+        __EKKLESIA_API_BASE_URL__: '""',
+        "process.env.NODE_ENV": '"production"',
+      },
+      entryPoints: [path.join(sourceDirectory, "display", "main.tsx")],
+      format: "esm",
+      jsx: "automatic",
+      logLevel: "silent",
+      minify: false,
+      platform: "browser",
+      target: "es2022",
+      write: false,
+    });
+    bundle = result.outputFiles.map((file) => file.text).join("\n");
+  }, 60_000);
+
+  it("contains the generic loader's one dynamic import and no statically known module", () => {
+    expect([...bundle.matchAll(/\bimport\s*\(/gu)]).toHaveLength(1);
+    expect(bundle).toContain("(url) => import(url)");
+    expect(bundle).not.toContain("ekklesia.module.json");
+    expect(bundle).not.toContain("/api/v1/modules");
+    for (const moduleId of ["announcements", "calendar", "livestream", "signage"]) {
+      expect(bundle.toLowerCase()).not.toContain(moduleId);
+    }
+  });
+
+  it("knows only its host route resources, with no Dashboard application or transport coupling", () => {
+    expect(bundle).toContain('"/api/v1/principal"');
+    expect(bundle).toContain('"/api/v1/module-displays"');
+    expect(bundle).not.toContain('"/api/v1/dashboard/navigation"');
+    expect(bundle).not.toContain("Loading Ekklesia");
+    expect(bundle).not.toContain("Sign in to Ekklesia");
+    expect(bundle.toLowerCase()).not.toContain("socket.io");
+    expect(bundle.toLowerCase()).not.toContain("mqtt");
+  });
+
+  it("uses neither eval nor a blob URL to load display code", () => {
+    expect(bundle).not.toContain("new Function(");
+    expect(bundle).not.toMatch(/\beval\s*\(/u);
+    expect(bundle).not.toContain("createObjectURL");
+  });
+});