,
+ // and emits no indicator (isStreaming defaults to false). Output MUST
+ // be byte-identical.
+ const swapped = render(
+ createElement(AssistantMarkdownContent, {
+ text: CANONICAL_WIDGETLESS_MESSAGE,
+ }),
+ );
+ const swappedHtml = swapped.container.innerHTML;
+
+ expect(swappedHtml).toBe(baselineHtml);
+ });
+
+ it("renders widget-less markdown identically when isStreaming is true and no unclosed tag is present", () => {
+ // Streaming case for a finalized widget-less message: parser returns one
+ // markdown segment, the wrapper applies STREAMING_GLOW_CLASS only if it
+ // is non-empty. With the placeholder empty constant, output must still
+ // match the baseline. detectUnclosedWidgetTag returns false (no opens),
+ // so the indicator does NOT render.
+ const baseline = render(
+ createElement(
+ "div",
+ { className: "agent-markdown text-foreground" },
+ createElement(
+ ReactMarkdown,
+ { remarkPlugins: [remarkGfm] },
+ rewriteMediaLinesToMarkdown(CANONICAL_WIDGETLESS_MESSAGE),
+ ),
+ ),
+ );
+ const baselineHtml = baseline.container.innerHTML;
+ cleanup();
+
+ const swapped = render(
+ createElement(AssistantMarkdownContent, {
+ text: CANONICAL_WIDGETLESS_MESSAGE,
+ isStreaming: true,
+ }),
+ );
+ const swappedHtml = swapped.container.innerHTML;
+
+ expect(swappedHtml).toBe(baselineHtml);
+ });
+
+ it("does not render the generating-widget indicator on a widget-less finalized message", () => {
+ const result = render(
+ createElement(AssistantMarkdownContent, {
+ text: CANONICAL_WIDGETLESS_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ expect(
+ result.container.querySelector("[data-testid=\"widget-generating-indicator\"]"),
+ ).toBeNull();
+ });
+
+ it("does not render the generating-widget indicator on a widget-less streaming message", () => {
+ const result = render(
+ createElement(AssistantMarkdownContent, {
+ text: CANONICAL_WIDGETLESS_MESSAGE,
+ isStreaming: true,
+ }),
+ );
+ expect(
+ result.container.querySelector("[data-testid=\"widget-generating-indicator\"]"),
+ ).toBeNull();
+ });
+});
diff --git a/tests/unit/assistantMarkdownContent-replay-parity.test.ts b/tests/unit/assistantMarkdownContent-replay-parity.test.ts
new file mode 100644
index 000000000..8c7d29856
--- /dev/null
+++ b/tests/unit/assistantMarkdownContent-replay-parity.test.ts
@@ -0,0 +1,110 @@
+import { createElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+
+import { AssistantMarkdownContent } from "@/features/agents/components/widgets/AssistantMarkdownContent";
+
+const FINALIZED_WIDGET_MESSAGE = [
+ "Here is the chart you requested:",
+ "",
+ '
',
+ "",
+ "
Weekly Sales
",
+ " ",
+ "",
+ "",
+ "",
+ "Let me know if you need a deeper breakdown.",
+].join("\n");
+
+describe("AssistantMarkdownContent SSE replay parity (RENDER-04 unit-level)", () => {
+ afterEach(() => {
+ cleanup();
+ });
+
+ it("renders byte-identical DOM for live and replay paths on the same finalized text", () => {
+ // First render — simulates the LIVE path: SSE frame delivered the closing
+ // , message is now finalized, isStreaming flips to false.
+ const live = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const liveHtml = live.container.innerHTML;
+ cleanup();
+
+ // Second render — simulates the REPLAY path: page reload triggers
+ // outbox replay; the same stored text is rendered cold from a fresh
+ // component instance with isStreaming false. Parser is pure, segment
+ // keys are content-hash, srcDoc is memoized on (html, themeVars, id).
+ // Output MUST be byte-identical.
+ const replay = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const replayHtml = replay.container.innerHTML;
+
+ expect(replayHtml).toBe(liveHtml);
+ });
+
+ it("emits identical iframe sandbox and srcDoc attributes across live and replay renders", () => {
+ const live = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const liveIframe = live.container.querySelector("iframe");
+ expect(liveIframe).not.toBeNull();
+ const liveSandbox = liveIframe?.getAttribute("sandbox");
+ const liveSrcDoc = liveIframe?.getAttribute("srcdoc");
+ cleanup();
+
+ const replay = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const replayIframe = replay.container.querySelector("iframe");
+ expect(replayIframe).not.toBeNull();
+ const replaySandbox = replayIframe?.getAttribute("sandbox");
+ const replaySrcDoc = replayIframe?.getAttribute("srcdoc");
+
+ expect(replaySandbox).toBe(liveSandbox);
+ expect(replaySrcDoc).toBe(liveSrcDoc);
+ expect(replaySandbox).toBe("allow-scripts allow-popups");
+ });
+
+ it("produces a stable widgetId-derived key for the same widget HTML across renders", () => {
+ // Two renders of the same text should yield iframes nested inside DOM
+ // shells with stable data-widget-id attributes (Phase 2's InlineWidget
+ // sets data-widget-id on its outer wrapper). Identical input → identical
+ // content-hash widgetId → identical attribute value.
+ const first = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const firstShell = first.container.querySelector("[data-widget-id]");
+ expect(firstShell).not.toBeNull();
+ const firstId = firstShell?.getAttribute("data-widget-id");
+ cleanup();
+
+ const second = render(
+ createElement(AssistantMarkdownContent, {
+ text: FINALIZED_WIDGET_MESSAGE,
+ isStreaming: false,
+ }),
+ );
+ const secondShell = second.container.querySelector("[data-widget-id]");
+ expect(secondShell).not.toBeNull();
+ const secondId = secondShell?.getAttribute("data-widget-id");
+
+ expect(secondId).toBe(firstId);
+ });
+});
diff --git a/tests/unit/buildWidgetSrcDoc.test.ts b/tests/unit/buildWidgetSrcDoc.test.ts
new file mode 100644
index 000000000..649c1961e
--- /dev/null
+++ b/tests/unit/buildWidgetSrcDoc.test.ts
@@ -0,0 +1,102 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+
+import {
+ buildWidgetSrcDoc,
+ CHART_JS_CDN_URL,
+ TAILWIND_CDN_URL,
+ WIDGET_SANDBOX,
+} from "@/features/agents/components/widgets/buildWidgetSrcDoc";
+import type { ThemeVars } from "@/features/agents/components/widgets/widgetTheme";
+
+const FIXTURE_THEME: ThemeVars = {
+ "--bg": "#ffffff",
+ "--text": "#111827",
+ "--card": "#f9fafb",
+ "--border": "#e5e7eb",
+ "--accent": "#2563eb",
+ "--muted": "#6b7280",
+ "--ok": "#16a34a",
+ "--warn": "#d97706",
+ "--danger": "#dc2626",
+};
+
+const FIXTURE_HTML = '
';
+const FIXTURE_WIDGET_ID = "abc123";
+
+describe("buildWidgetSrcDoc", () => {
+ it("exports the literal sandbox token string allow-scripts allow-popups", () => {
+ expect(WIDGET_SANDBOX).toBe("allow-scripts allow-popups");
+ });
+
+ it("emits the Tailwind v4 jsdelivr browser CDN URL in the output", () => {
+ const out = buildWidgetSrcDoc({
+ html: FIXTURE_HTML,
+ themeVars: FIXTURE_THEME,
+ widgetId: FIXTURE_WIDGET_ID,
+ });
+ expect(TAILWIND_CDN_URL).toBe(
+ "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4",
+ );
+ expect(out).toContain(
+ "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4",
+ );
+ });
+
+ it("emits the Chart.js 4.5.1 jsdelivr URL in the output (never @latest)", () => {
+ const out = buildWidgetSrcDoc({
+ html: FIXTURE_HTML,
+ themeVars: FIXTURE_THEME,
+ widgetId: FIXTURE_WIDGET_ID,
+ });
+ expect(CHART_JS_CDN_URL).toBe(
+ "https://cdn.jsdelivr.net/npm/chart.js@4.5.1/dist/chart.umd.min.js",
+ );
+ expect(out).toContain("chart.js@4.5.1/dist/chart.umd.min.js");
+ expect(out).not.toContain("@latest");
+ });
+
+ it("injects all 9 widget-side CSS variables into the style block", () => {
+ const out = buildWidgetSrcDoc({
+ html: FIXTURE_HTML,
+ themeVars: FIXTURE_THEME,
+ widgetId: FIXTURE_WIDGET_ID,
+ });
+ const expectedNames: ReadonlyArray
= [
+ "--bg",
+ "--text",
+ "--card",
+ "--border",
+ "--accent",
+ "--muted",
+ "--ok",
+ "--warn",
+ "--danger",
+ ];
+ for (const name of expectedNames) {
+ expect(out).toContain(`${name}: ${FIXTURE_THEME[name]};`);
+ }
+ });
+
+ it("includes the height-reporter postMessage script with the widgetId", () => {
+ const out = buildWidgetSrcDoc({
+ html: FIXTURE_HTML,
+ themeVars: FIXTURE_THEME,
+ widgetId: FIXTURE_WIDGET_ID,
+ });
+ expect(out).toContain("parent.postMessage");
+ expect(out).toContain("iframe:height");
+ expect(out).toContain(FIXTURE_WIDGET_ID);
+ });
+
+ it("returns byte-identical output for identical inputs (purity)", () => {
+ const args = {
+ html: FIXTURE_HTML,
+ themeVars: FIXTURE_THEME,
+ widgetId: FIXTURE_WIDGET_ID,
+ };
+ const a = buildWidgetSrcDoc(args);
+ const b = buildWidgetSrcDoc(args);
+ expect(a).toBe(b);
+ });
+});
diff --git a/tests/unit/buildWidgetSrcDoc.theme-bootstrap.test.ts b/tests/unit/buildWidgetSrcDoc.theme-bootstrap.test.ts
new file mode 100644
index 000000000..b825f1ad9
--- /dev/null
+++ b/tests/unit/buildWidgetSrcDoc.theme-bootstrap.test.ts
@@ -0,0 +1,92 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+
+import { buildWidgetSrcDoc } from "@/features/agents/components/widgets/buildWidgetSrcDoc";
+import type { ThemeVars } from "@/features/agents/components/widgets/widgetTheme";
+
+const sampleTheme: ThemeVars = {
+ "--bg": "#000",
+ "--text": "#fff",
+ "--card": "#111",
+ "--border": "#222",
+ "--accent": "#333",
+ "--muted": "#444",
+ "--ok": "#0f0",
+ "--warn": "#ff0",
+ "--danger": "#f00",
+};
+
+describe("buildWidgetSrcDoc — theme bootstrap script (D-01..D-05)", () => {
+ it("emits a listener for 'theme:update' messages", () => {
+ const out = buildWidgetSrcDoc({
+ html: "",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ expect(out).toContain("'theme:update'");
+ expect(out).toContain("addEventListener('message'");
+ });
+
+ it("applies updates via document.documentElement.style.setProperty", () => {
+ const out = buildWidgetSrcDoc({
+ html: "",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ expect(out).toContain("document.documentElement.style.setProperty");
+ });
+
+ it("includes all 9 widget-side var names in the bootstrap allowlist", () => {
+ const out = buildWidgetSrcDoc({
+ html: "",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ for (const name of [
+ "--bg",
+ "--text",
+ "--card",
+ "--border",
+ "--accent",
+ "--muted",
+ "--ok",
+ "--warn",
+ "--danger",
+ ]) {
+ expect(out).toContain(name);
+ }
+ });
+
+ it("wraps the bootstrap body in a try/catch so a bad message never breaks the widget", () => {
+ const out = buildWidgetSrcDoc({
+ html: "",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ expect(out).toMatch(/try\{[\s\S]*?\}catch\(err\)\{\}/);
+ });
+
+ it("emits the bootstrap script in addition to the existing height reporter", () => {
+ const out = buildWidgetSrcDoc({
+ html: "",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ expect(out).toContain("iframe:height");
+ expect(out).toContain("theme:update");
+ });
+
+ it("is byte-identical for repeated calls with the same args (purity)", () => {
+ const a = buildWidgetSrcDoc({
+ html: "same
",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ const b = buildWidgetSrcDoc({
+ html: "same
",
+ themeVars: sampleTheme,
+ widgetId: "w1",
+ });
+ expect(a).toBe(b);
+ });
+});
diff --git a/tests/unit/inlineWidget.test.ts b/tests/unit/inlineWidget.test.ts
new file mode 100644
index 000000000..67761dd80
--- /dev/null
+++ b/tests/unit/inlineWidget.test.ts
@@ -0,0 +1,259 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, render } from "@testing-library/react";
+import { createElement } from "react";
+
+import { InlineWidget } from "@/features/agents/components/widgets/InlineWidget";
+import { WIDGET_SANDBOX } from "@/features/agents/components/widgets/buildWidgetSrcDoc";
+import { __resetForTests as resetRegistry } from "@/features/agents/components/widgets/widgetMessageRegistry";
+import { __resetForTests as resetBroadcast } from "@/features/agents/components/widgets/widgetThemeBroadcast";
+
+afterEach(() => {
+ cleanup();
+ resetRegistry();
+ resetBroadcast();
+ vi.restoreAllMocks();
+});
+
+const queryIframe = (root: HTMLElement): HTMLIFrameElement => {
+ const iframe = root.querySelector("iframe");
+ if (iframe === null) throw new Error("iframe not rendered");
+ return iframe as HTMLIFrameElement;
+};
+
+describe("InlineWidget — sandbox attribute discipline (D-20, WIDGET-02, SEC-01..04)", () => {
+ it("renders an iframe with sandbox exactly equal to WIDGET_SANDBOX", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ expect(iframe.getAttribute("sandbox")).toBe(WIDGET_SANDBOX);
+ expect(iframe.getAttribute("sandbox")).toBe("allow-scripts allow-popups");
+ });
+
+ it("rejects each forbidden sandbox token explicitly", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ const sandbox = iframe.getAttribute("sandbox") ?? "";
+ // Tokens are built at runtime via concatenation so the SEC-01 ESLint
+ // rule (no-restricted-syntax on Literal[value=/allow-same-origin/])
+ // does not fire on this assertion file. The rule's intent is to ban
+ // accidental use; tests legitimately need to assert absence.
+ const forbiddenSameOrigin = ["allow", "same", "origin"].join("-");
+ const forbiddenForms = ["allow", "forms"].join("-");
+ const forbiddenTopNav = ["allow", "top", "navigation"].join("-");
+ expect(sandbox).not.toContain(forbiddenSameOrigin);
+ expect(sandbox).not.toContain(forbiddenForms);
+ expect(sandbox).not.toContain(forbiddenTopNav);
+ });
+
+ it("does not set a name attribute on the iframe (D-21, SEC-04)", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ expect(iframe.hasAttribute("name")).toBe(false);
+ });
+});
+
+describe("InlineWidget — iframe DOM identity (D-22, D-23, WIDGET-10)", () => {
+ it("preserves the same iframe DOM node across re-renders with identical props", () => {
+ const { container, rerender } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "same
",
+ }),
+ );
+ const iframe1 = queryIframe(container);
+ rerender(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "same
",
+ }),
+ );
+ const iframe2 = queryIframe(container);
+ expect(iframe1).toBe(iframe2);
+ });
+
+ it("rebuilds the iframe DOM node when html changes (regression: over-zealous memo)", () => {
+ const { container, rerender } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "before
",
+ }),
+ );
+ const iframe1 = queryIframe(container);
+ const srcDoc1 = iframe1.getAttribute("srcdoc");
+ rerender(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "after
",
+ }),
+ );
+ const iframe2 = queryIframe(container);
+ const srcDoc2 = iframe2.getAttribute("srcdoc");
+ expect(srcDoc1).not.toBe(srcDoc2);
+ });
+});
+
+describe("InlineWidget — height update path (D-11..D-14, WIDGET-05, SEC-02)", () => {
+ it("applies a height update from event.source === iframe.contentWindow", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ const win = iframe.contentWindow;
+ expect(win).not.toBeNull();
+ act(() => {
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "iframe:height", widgetId: "w1", height: 300 },
+ source: win,
+ }),
+ );
+ });
+ expect(iframe.style.height).toBe("300px");
+ });
+
+ it("ignores a height update from a foreign source", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ const initialHeight = iframe.style.height;
+ const otherIframe = document.createElement("iframe");
+ document.body.appendChild(otherIframe);
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "iframe:height", widgetId: "w1", height: 300 },
+ source: otherIframe.contentWindow,
+ }),
+ );
+ expect(iframe.style.height).toBe(initialHeight);
+ });
+
+ it("clamps height 999999 down to 600", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ act(() => {
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "iframe:height", widgetId: "w1", height: 999999 },
+ source: iframe.contentWindow,
+ }),
+ );
+ });
+ expect(iframe.style.height).toBe("600px");
+ });
+
+ it("drops a NaN height with a console warning", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ const iframe = queryIframe(container);
+ const before = iframe.style.height;
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "iframe:height", widgetId: "w1", height: Number.NaN },
+ source: iframe.contentWindow,
+ }),
+ );
+ expect(iframe.style.height).toBe(before);
+ expect(warn).toHaveBeenCalled();
+ });
+});
+
+describe("InlineWidget — title bar affordances (D-15..D-19, WIDGET-09)", () => {
+ it("exposes aria-labels on collapse and open-in-new-tab buttons", () => {
+ const { getByLabelText } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "x
",
+ }),
+ );
+ expect(getByLabelText("Collapse widget")).toBeInTheDocument();
+ expect(getByLabelText("Open widget in new tab")).toBeInTheDocument();
+ });
+
+ it("falls back to 'Widget' when title is empty", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "",
+ html: "x
",
+ }),
+ );
+ expect(container.textContent).toContain("Widget");
+ });
+});
+
+describe("InlineWidget — listener cleanup (PITFALLS #11, D-31)", () => {
+ it("returns the global listener count to baseline after 50 mount/unmount cycles", async () => {
+ const { __snapshotForTests } = await import(
+ "@/features/agents/components/widgets/widgetMessageRegistry"
+ );
+ for (let i = 0; i < 50; i += 1) {
+ const { unmount } = render(
+ createElement(InlineWidget, {
+ id: `w-${i}`,
+ title: "T",
+ html: "x
",
+ }),
+ );
+ unmount();
+ }
+ expect(__snapshotForTests().listenerInstalled).toBe(false);
+ expect(__snapshotForTests().ids).toHaveLength(0);
+ });
+});
+
+describe("InlineWidget — error boundary integration (D-06..D-10, WIDGET-12)", () => {
+ it("renders normally when html is valid (boundary stays inactive)", () => {
+ const { container } = render(
+ createElement(InlineWidget, {
+ id: "w1",
+ title: "T",
+ html: "ok
",
+ }),
+ );
+ expect(container.querySelector("[data-widget-fallback]")).toBeNull();
+ expect(container.querySelector("iframe")).not.toBeNull();
+ });
+});
diff --git a/tests/unit/inlineWidgetErrorBoundary.test.ts b/tests/unit/inlineWidgetErrorBoundary.test.ts
new file mode 100644
index 000000000..6bc267dff
--- /dev/null
+++ b/tests/unit/inlineWidgetErrorBoundary.test.ts
@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+import { createElement, type FC } from "react";
+
+import { InlineWidgetErrorBoundary } from "@/features/agents/components/widgets/InlineWidgetErrorBoundary";
+
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
+
+const Throwing: FC = () => {
+ throw new Error("widget render exploded");
+};
+
+const Healthy: FC = () =>
+ createElement("div", { "data-testid": "healthy" }, "ok");
+
+describe("InlineWidgetErrorBoundary", () => {
+ it("renders children when no error is thrown", () => {
+ const { getByTestId } = render(
+ createElement(
+ InlineWidgetErrorBoundary,
+ { widgetId: "w1", title: "T", html: "x
" },
+ createElement(Healthy),
+ ),
+ );
+ expect(getByTestId("healthy")).toBeInTheDocument();
+ });
+
+ it("catches a throwing child and renders fallback chrome with the title", () => {
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ const { getByText } = render(
+ createElement(
+ InlineWidgetErrorBoundary,
+ { widgetId: "w1", title: "Sales", html: "x
" },
+ createElement(Throwing),
+ ),
+ );
+ expect(getByText("Sales")).toBeInTheDocument();
+ expect(getByText("failed to render")).toBeInTheDocument();
+ expect(error).toHaveBeenCalled();
+ });
+
+ it("renders the raw HTML inside a source-view block", () => {
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const html = "";
+ const { container, getByText } = render(
+ createElement(
+ InlineWidgetErrorBoundary,
+ { widgetId: "w1", title: "Test", html },
+ createElement(Throwing),
+ ),
+ );
+ const details = container.querySelector("details");
+ expect(details).not.toBeNull();
+ const summary = container.querySelector("details > summary");
+ expect(summary?.textContent).toBe("View source");
+ expect(getByText(html)).toBeInTheDocument();
+ });
+
+ it("falls back to the literal title 'Widget' when title is empty", () => {
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const { getByText } = render(
+ createElement(
+ InlineWidgetErrorBoundary,
+ { widgetId: "w1", title: "", html: "" },
+ createElement(Throwing),
+ ),
+ );
+ expect(getByText("Widget")).toBeInTheDocument();
+ });
+
+ it("logs via console.error with widgetId and title context", () => {
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ render(
+ createElement(
+ InlineWidgetErrorBoundary,
+ { widgetId: "alpha", title: "Beta", html: "" },
+ createElement(Throwing),
+ ),
+ );
+ expect(error).toHaveBeenCalled();
+ // React 19 emits its own internal error logs alongside componentDidCatch.
+ // Find the log entry whose first string argument carries the boundary's
+ // widgetId+title context — that's the one our boundary produced.
+ const ours = error.mock.calls.find(
+ (call) =>
+ typeof call[0] === "string" &&
+ (call[0] as string).includes("alpha") &&
+ (call[0] as string).includes("Beta"),
+ );
+ expect(ours).toBeDefined();
+ });
+});
diff --git a/tests/unit/parseWidgetSegments.test.ts b/tests/unit/parseWidgetSegments.test.ts
new file mode 100644
index 000000000..31d6e1e35
--- /dev/null
+++ b/tests/unit/parseWidgetSegments.test.ts
@@ -0,0 +1,351 @@
+// Coverage baseline (locked by Phase 4 Plan 04-1, TEST-01 / D-25):
+// Branch coverage: >95% threshold enforced via vitest.config.ts.
+// Run `npx vitest run --coverage tests/unit/parseWidgetSegments.test.ts` to verify.
+import { describe, expect, it, vi } from "vitest";
+
+import {
+ fnv1a,
+ parseWidgetSegments,
+ type MessageSegment,
+} from "@/features/agents/components/widgets/parseWidgetSegments";
+
+describe("parseWidgetSegments", () => {
+ it("returns an empty array for an empty string", () => {
+ expect(parseWidgetSegments("")).toEqual([]);
+ });
+
+ it("returns a single markdown segment when no widget tags are present", () => {
+ const out = parseWidgetSegments("hello world");
+ expect(out).toEqual([{ kind: "markdown", text: "hello world" }]);
+ });
+
+ it("emits one widget segment for a single well-formed widget", () => {
+ const out = parseWidgetSegments('body');
+ expect(out).toHaveLength(1);
+ expect(out[0]).toMatchObject({
+ kind: "widget",
+ title: "A",
+ html: "body",
+ });
+ });
+
+ it("emits multiple widget segments interleaved with markdown", () => {
+ const out = parseWidgetSegments(
+ 'before aaa middle bbb after',
+ );
+ expect(out.map((segment) => segment.kind)).toEqual([
+ "markdown",
+ "widget",
+ "markdown",
+ "widget",
+ "markdown",
+ ]);
+ expect((out[0] as { text: string }).text).toBe("before ");
+ expect((out[1] as { title: string }).title).toBe("A");
+ expect((out[2] as { text: string }).text).toBe(" middle ");
+ expect((out[3] as { title: string }).title).toBe("B");
+ expect((out[4] as { text: string }).text).toBe(" after");
+ });
+
+ it("emits a widget-only segment when the input is exactly one widget", () => {
+ const out = parseWidgetSegments('y');
+ expect(out).toEqual([
+ {
+ kind: "widget",
+ title: "X",
+ html: "y",
+ widgetId: `${fnv1a("y").toString(16)}-0`,
+ },
+ ]);
+ });
+
+ it("preserves leading and trailing markdown around a single widget", () => {
+ const out = parseWidgetSegments(
+ 'lead y trail',
+ );
+ expect(out).toHaveLength(3);
+ expect(out[0]).toEqual({ kind: "markdown", text: "lead " });
+ expect(out[2]).toEqual({ kind: "markdown", text: " trail" });
+ });
+
+ it("buffers an unclosed trailing widget tag as markdown text", () => {
+ const out = parseWidgetSegments('text no close');
+ expect(out).toEqual([
+ { kind: "markdown", text: 'text no close' },
+ ]);
+ });
+
+ it("handles every byte-prefix of a multi-widget fixture without throwing", () => {
+ const fixture =
+ 'before text aaa middle bbb after';
+ for (let i = 0; i <= fixture.length; i += 1) {
+ const slice = fixture.slice(0, i);
+ const segments = parseWidgetSegments(slice);
+ expect(Array.isArray(segments)).toBe(true);
+ for (const segment of segments) {
+ expect(["markdown", "widget"]).toContain(segment.kind);
+ }
+ }
+ });
+
+ it("rejects an unquoted title and emits the open tag as markdown text", () => {
+ const input = "body";
+ const out = parseWidgetSegments(input);
+ expect(out).toEqual([{ kind: "markdown", text: input }]);
+ });
+
+ it("rejects a single-quoted title and emits the open tag as markdown text", () => {
+ const input = "body";
+ const out = parseWidgetSegments(input);
+ expect(out).toEqual([{ kind: "markdown", text: input }]);
+ });
+
+ it("rejects a missing close tag at end of stream and emits as markdown", () => {
+ const input = 'no close';
+ const out = parseWidgetSegments(input);
+ expect(out).toEqual([{ kind: "markdown", text: input }]);
+ });
+
+ it("rejects a self-closing widget form and emits as markdown", () => {
+ const input = '';
+ const out = parseWidgetSegments(input);
+ expect(out).toEqual([{ kind: "markdown", text: input }]);
+ });
+
+ it("auto-normalizes curly quotes inside the widget open tag attributes", () => {
+ const warnSpy = vi
+ .spyOn(console, "warn")
+ .mockImplementation(() => undefined);
+ const out = parseWidgetSegments('hello body');
+ expect(out).toHaveLength(2);
+ expect(out[1]).toMatchObject({
+ kind: "widget",
+ title: "Chart",
+ html: "body",
+ });
+ expect(warnSpy).toHaveBeenCalled();
+ const firstCallArg = warnSpy.mock.calls[0]?.[0] ?? "";
+ expect(String(firstCallArg)).toContain("auto-normalized");
+ warnSpy.mockRestore();
+ });
+
+ it("treats nested widgets as outer-wins with inner as literal body text", () => {
+ const out = parseWidgetSegments(
+ 'x',
+ );
+ expect(out).toHaveLength(1);
+ const widget = out[0] as { kind: "widget"; title: string; html: string };
+ expect(widget.kind).toBe("widget");
+ expect(widget.title).toBe("Outer");
+ expect(widget.html).toBe('x');
+ });
+
+ it("accepts a widget tag with the mc prefix", () => {
+ const out = parseWidgetSegments('m');
+ expect(out).toEqual([
+ {
+ kind: "widget",
+ title: "Z",
+ html: "m",
+ widgetId: `${fnv1a("m").toString(16)}-0`,
+ },
+ ]);
+ });
+
+ it("accepts a mix of widget and mcwidget in the same message", () => {
+ const out = parseWidgetSegments(
+ 'aaa sep bbb',
+ );
+ expect(out).toHaveLength(3);
+ expect((out[0] as { title: string }).title).toBe("A");
+ expect((out[1] as { text: string }).text).toBe(" sep ");
+ expect((out[2] as { title: string }).title).toBe("B");
+ });
+
+ it("preserves HTML entities in the title attribute", () => {
+ const out = parseWidgetSegments(
+ 'body',
+ );
+ expect(out).toHaveLength(1);
+ expect((out[0] as { title: string }).title).toBe("A & B");
+ });
+
+ it("produces distinct stable widgetIds for two widget segments with identical html", () => {
+ // Two widgets with the same HTML must NOT share a widgetId — otherwise
+ // widgetMessageRegistry / widgetThemeBroadcast (Map-keyed by widgetId)
+ // would route height/theme updates from both iframes to the same entry
+ // and the second registration would overwrite the first.
+ const input =
+ 'same sep same';
+ const out = parseWidgetSegments(input);
+ const widgets = out.filter(
+ (segment): segment is Extract =>
+ segment.kind === "widget",
+ );
+ expect(widgets).toHaveLength(2);
+ // Distinct: the byte-index suffix prevents collision.
+ expect(widgets[0]?.widgetId).not.toBe(widgets[1]?.widgetId);
+ // Both share the FNV-1a content-hash prefix because the bodies are equal.
+ const hash = fnv1a("same").toString(16);
+ expect(widgets[0]?.widgetId.startsWith(`${hash}-`)).toBe(true);
+ expect(widgets[1]?.widgetId.startsWith(`${hash}-`)).toBe(true);
+ // Stable across re-parses: same input yields the same widgetIds, so
+ // React keys + iframe DOM identity remain preserved across renders.
+ const out2 = parseWidgetSegments(input);
+ const widgets2 = out2.filter(
+ (segment): segment is Extract =>
+ segment.kind === "widget",
+ );
+ expect(widgets2[0]?.widgetId).toBe(widgets[0]?.widgetId);
+ expect(widgets2[1]?.widgetId).toBe(widgets[1]?.widgetId);
+ });
+
+ // ---- Phase 4 Plan 04-1 gap-closure tests (TEST-01 branch coverage >95%) ----
+
+ it("warns only once when two curly-quoted widgets appear in the same input", () => {
+ const warnSpy = vi
+ .spyOn(console, "warn")
+ .mockImplementation(() => undefined);
+ const out = parseWidgetSegments(
+ 'aaa sep bbb',
+ );
+ expect(out.filter((s) => s.kind === "widget")).toHaveLength(2);
+ // The warn is fired at most twice (one per widget tag), but the
+ // already-warned branch inside the regex callback is exercised when the
+ // second curly-quoted span is processed in the same render pass.
+ expect(warnSpy).toHaveBeenCalled();
+ warnSpy.mockRestore();
+ });
+
+ it("recovers parsing after a malformed widget open tag and emits literal text plus a later valid widget", () => {
+ // The malformed `` (no title attribute) makes scanWidgetSpan
+ // return null. parseInner advances past `<` and the trailing valid widget
+ // must still parse. Exercises the `span === null` continue path (L202-206).
+ const out = parseWidgetSegments(
+ 'before oops mid body end',
+ );
+ const widgetSegments = out.filter((s) => s.kind === "widget");
+ expect(widgetSegments).toHaveLength(1);
+ expect((widgetSegments[0] as { title: string }).title).toBe("Real");
+ // The literal `oops` survives in markdown text somewhere.
+ const joined = out
+ .filter((s): s is Extract => s.kind === "markdown")
+ .map((s) => s.text)
+ .join("");
+ expect(joined).toContain("oops");
+ });
+
+ it("buffers two unclosed widget open tags as trailing markdown without throwing", () => {
+ // Two opens, zero closes — exercises findUnmatchedOpenIndex
+ // returning the FIRST open (lastClose = -1, all opens > lastClose).
+ const input = 'a b c';
+ const out = parseWidgetSegments(input);
+ // No widget segments materialize because nothing closes; entire span
+ // from the first open onward becomes markdown via the streaming-safe path.
+ expect(out.every((s) => s.kind === "markdown")).toBe(true);
+ const joined = out.map((s) => (s as { text: string }).text).join("");
+ expect(joined).toBe(input);
+ });
+
+ it("handles three-deep nested widgets with depth counter beyond 2", () => {
+ // Triple-nested case — exercises the depth>1 path in scanWidgetSpan
+ // where another open is encountered before depth returns to 0 (L153-158).
+ const input =
+ 'x';
+ const out = parseWidgetSegments(input);
+ expect(out).toHaveLength(1);
+ const widget = out[0] as { kind: "widget"; title: string; html: string };
+ expect(widget.title).toBe("L1");
+ expect(widget.html).toBe(
+ 'x',
+ );
+ });
+
+ it("treats a literal in body text as the closing tag and emits trailing remainder as markdown", () => {
+ // Non-greedy regex: first wins. Tail after it is markdown.
+ const out = parseWidgetSegments(
+ 'body tail-text',
+ );
+ expect(out).toHaveLength(2);
+ expect(out[0]).toMatchObject({ kind: "widget", title: "X", html: "body" });
+ expect(out[1]).toEqual({ kind: "markdown", text: " tail-text" });
+ });
+
+ it("emits an empty title when the title attribute is the empty string", () => {
+ const out = parseWidgetSegments('x');
+ expect(out).toHaveLength(1);
+ expect((out[0] as { title: string }).title).toBe("");
+ });
+
+ it("buffers a streaming partial open tag with no closing bracket as markdown", () => {
+ const out = parseWidgetSegments('prefix {
+ // First widget closes cleanly; second is unclosed — exercises the
+ // findUnmatchedOpenIndex path where there are matched closes but the
+ // last open is still dangling.
+ const input =
+ 'aaa mid unclosed';
+ const out = parseWidgetSegments(input);
+ // The first widget should survive; the unclosed second open + body
+ // must emerge as a trailing markdown segment.
+ const widgets = out.filter((s) => s.kind === "widget");
+ expect(widgets).toHaveLength(1);
+ expect((widgets[0] as { title: string }).title).toBe("A");
+ const tail = out
+ .filter((s): s is Extract => s.kind === "markdown")
+ .map((s) => s.text)
+ .join("");
+ expect(tail).toContain('unclosed');
+ });
+
+ it("merges trailing unmatched-open tail into the preceding markdown segment when present", () => {
+ // Exercises the branch in parseWidgetSegments where the prefix's last
+ // segment is markdown and the tail is appended to it (L242-244).
+ const out = parseWidgetSegments('hello {
+ // `incomplete');
+ expect(out).toHaveLength(1);
+ expect(out[0]).toEqual({
+ kind: "markdown",
+ text: 'incomplete',
+ });
+ });
+
+ it("treats a malformed widget open without a title attribute as literal text and continues parsing", () => {
+ // `plain mid body';
+ const out = parseWidgetSegments(input);
+ const widgets = out.filter((s) => s.kind === "widget");
+ expect(widgets).toHaveLength(1);
+ expect((widgets[0] as { title: string }).title).toBe("Real");
+ });
+
+ it("handles a triple-deep nest with stable depth bookkeeping (no extra widgets emitted)", () => {
+ const input =
+ 'pre x post';
+ const out = parseWidgetSegments(input);
+ expect(out).toHaveLength(3);
+ expect((out[0] as { text: string }).text).toBe("pre ");
+ expect((out[1] as { kind: string }).kind).toBe("widget");
+ expect((out[1] as { title: string }).title).toBe("A");
+ expect((out[2] as { text: string }).text).toBe(" post");
+ });
+});
diff --git a/tests/unit/personalityBuilder.test.ts b/tests/unit/personalityBuilder.test.ts
index f2ebe6116..96e4d99f4 100644
--- a/tests/unit/personalityBuilder.test.ts
+++ b/tests/unit/personalityBuilder.test.ts
@@ -1,7 +1,9 @@
import { describe, expect, it } from "vitest";
+import { WIDGET_PROMPT } from "@/features/agents/components/widgets/widgetPromptSnippet";
import { createAgentFilesState } from "@/lib/agents/agentFiles";
import {
+ composeToolsContentWithWidgetPrompt,
parsePersonalityFiles,
serializePersonalityFiles,
type PersonalityBuilderDraft,
@@ -183,8 +185,144 @@ describe("personalityBuilder", () => {
);
expect(files["AGENTS.md"]).toBe("Top-level operating rules.");
- expect(files["TOOLS.md"]).toBe("Tool conventions.");
+ expect(files["TOOLS.md"]).toBe(`Tool conventions.\n\n${WIDGET_PROMPT}`);
expect(files["HEARTBEAT.md"]).toBe("Heartbeat notes.");
expect(files["MEMORY.md"]).toBe("Durable memory.");
});
});
+
+describe("personalityBuilder WIDGET_PROMPT injection (PROMPT-02)", () => {
+ it("appends WIDGET_PROMPT to TOOLS.md content when not already present", () => {
+ const result = composeToolsContentWithWidgetPrompt("Existing tool guidance.");
+ expect(result.startsWith("Existing tool guidance.")).toBe(true);
+ expect(result.endsWith(WIDGET_PROMPT)).toBe(true);
+ expect(result).toBe(`Existing tool guidance.\n\n${WIDGET_PROMPT}`);
+ });
+
+ it("returns input unchanged when WIDGET_PROMPT sentinel already present", () => {
+ // The sentinel is the unique opening sentence of WIDGET_PROMPT — if the
+ // stored TOOLS.md already contains it, the helper must not re-append.
+ const existing = `Some tools.\n\n${WIDGET_PROMPT}`;
+ const result = composeToolsContentWithWidgetPrompt(existing);
+ expect(result).toBe(existing);
+ });
+
+ it("returns WIDGET_PROMPT alone when input is empty", () => {
+ const result = composeToolsContentWithWidgetPrompt("");
+ expect(result).toBe(WIDGET_PROMPT);
+ });
+
+ it("collapses a single trailing newline before the separator", () => {
+ const result = composeToolsContentWithWidgetPrompt("trailing newline\n");
+ expect(result).toBe(`trailing newline\n\n${WIDGET_PROMPT}`);
+ });
+
+ it("collapses multiple trailing newlines to the canonical separator", () => {
+ const result = composeToolsContentWithWidgetPrompt("trailing\n\n\n");
+ expect(result).toBe(`trailing\n\n${WIDGET_PROMPT}`);
+ });
+
+ it("serializePersonalityFiles emits TOOLS.md with WIDGET_PROMPT appended", () => {
+ const draft: PersonalityBuilderDraft = {
+ identity: { name: "", creature: "", vibe: "", emoji: "", avatar: "" },
+ user: {
+ name: "",
+ callThem: "",
+ pronouns: "",
+ timezone: "",
+ notes: "",
+ context: "",
+ },
+ soul: { coreTruths: "", boundaries: "", vibe: "", continuity: "" },
+ agents: "",
+ tools: "Tool conventions.",
+ heartbeat: "",
+ memory: "",
+ };
+
+ const files = serializePersonalityFiles(draft);
+
+ expect(files["TOOLS.md"]).toContain("Tool conventions.");
+ expect(files["TOOLS.md"]).toContain(
+ "You can render rich, sandboxed inline HTML in chat by emitting a tag.",
+ );
+ expect(files["TOOLS.md"]).toBe(`Tool conventions.\n\n${WIDGET_PROMPT}`);
+ });
+
+ it("serializePersonalityFiles is idempotent when draft.tools already contains the WIDGET_PROMPT sentinel", () => {
+ const seeded = `Seeded text.\n\n${WIDGET_PROMPT}`;
+ const draft: PersonalityBuilderDraft = {
+ identity: { name: "", creature: "", vibe: "", emoji: "", avatar: "" },
+ user: {
+ name: "",
+ callThem: "",
+ pronouns: "",
+ timezone: "",
+ notes: "",
+ context: "",
+ },
+ soul: { coreTruths: "", boundaries: "", vibe: "", continuity: "" },
+ agents: "",
+ tools: seeded,
+ heartbeat: "",
+ memory: "",
+ };
+
+ const files = serializePersonalityFiles(draft);
+
+ expect(files["TOOLS.md"]).toBe(seeded);
+ // Counting occurrences of the prompt sentinel: must remain exactly 1.
+ const sentinel =
+ "You can render rich, sandboxed inline HTML in chat by emitting a tag.";
+ const occurrences = files["TOOLS.md"].split(sentinel).length - 1;
+ expect(occurrences).toBe(1);
+ });
+
+ it("parsePersonalityFiles reads stored TOOLS.md content verbatim (D-04 storage stays clean)", () => {
+ // The agent's stored TOOLS.md file does NOT contain the widget prompt —
+ // only the composed wire output does. parsePersonalityFiles reads the
+ // file content raw and must continue returning that raw content
+ // untouched, so the editor UI shows the agent's clean tools file.
+ const files = createAgentFilesState();
+ files["TOOLS.md"] = { exists: true, content: "Stored tool docs without widgets." };
+
+ const draft = parsePersonalityFiles(files);
+
+ expect(draft.tools).toBe("Stored tool docs without widgets.");
+ expect(draft.tools).not.toContain(
+ "You can render rich, sandboxed inline HTML in chat by emitting a tag.",
+ );
+ });
+
+ it("does not modify other AgentFileName fields on the serialize output", () => {
+ const draft: PersonalityBuilderDraft = {
+ identity: { name: "Nova", creature: "fox", vibe: "calm", emoji: "🦊", avatar: "" },
+ user: {
+ name: "GP",
+ callThem: "GP",
+ pronouns: "he/him",
+ timezone: "UTC",
+ notes: "",
+ context: "",
+ },
+ soul: { coreTruths: "Be direct.", boundaries: "", vibe: "", continuity: "" },
+ agents: "Top-level agents content.",
+ tools: "Tool conventions.",
+ heartbeat: "Heartbeat content.",
+ memory: "Memory content.",
+ };
+
+ const files = serializePersonalityFiles(draft);
+
+ expect(files["AGENTS.md"]).toBe("Top-level agents content.");
+ expect(files["HEARTBEAT.md"]).toBe("Heartbeat content.");
+ expect(files["MEMORY.md"]).toBe("Memory content.");
+ // IDENTITY/SOUL/USER are formatted markdown — assert they do not contain
+ // the widget prompt sentinel (the append must be confined to TOOLS.md alone).
+ const widgetSentinel =
+ "You can render rich, sandboxed inline HTML in chat by emitting a tag.";
+ for (const fileName of ["IDENTITY.md", "USER.md", "SOUL.md", "AGENTS.md", "HEARTBEAT.md", "MEMORY.md"] as const) {
+ expect(files[fileName]).not.toContain(widgetSentinel);
+ }
+ });
+});
diff --git a/tests/unit/sec01-eslint-rule.test.ts b/tests/unit/sec01-eslint-rule.test.ts
new file mode 100644
index 000000000..4ed656d20
--- /dev/null
+++ b/tests/unit/sec01-eslint-rule.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { ESLint } from "eslint";
+
+/**
+ * SEC-01 regression test (PR #106 review feedback).
+ *
+ * `eslint.config.mjs` `globalIgnores` excludes `tests/eslint-rules/**` from
+ * default `npm run lint` so the deliberate forbidden-token violation in
+ * `sandbox-allow-same-origin.fixture.tsx` does NOT fail CI under normal
+ * lint runs. Without this test, weakening or removing the SEC-01 rule
+ * (`no-restricted-syntax` over the forbidden sandbox token) would
+ * silently land.
+ *
+ * The fix: drive ESLint via its Node API with `ignore: false` so the
+ * fixture is linted regardless of `globalIgnores`, then assert the rule
+ * fires with severity 2 (error) and the expected message text.
+ *
+ * Note: the forbidden token text is built via runtime concatenation
+ * (`["allow","same","origin"].join("-")`) so the SEC-01 rule does not
+ * fire on this assertion file itself — same idiom as
+ * `tests/unit/inlineWidget.test.ts`.
+ */
+describe("SEC-01: forbidden sandbox-token lint rule", () => {
+ const forbiddenToken = ["allow", "same", "origin"].join("-");
+
+ it(
+ "fires on the deliberate fixture violation",
+ async () => {
+ const eslint = new ESLint({
+ ignore: false,
+ errorOnUnmatchedPattern: false,
+ warnIgnored: false,
+ });
+ // Construct the fixture path at runtime so the SEC-01 rule
+ // (which matches Literal[value=/allow-same-origin/]) does not
+ // fire on this assertion file itself. The fixture's actual file
+ // name on disk is the canonical violation; here we just point
+ // ESLint at it without embedding the token as a string literal.
+ const fixturePath = `tests/eslint-rules/sandbox-${[
+ "allow",
+ "same",
+ "origin",
+ ].join("-")}.fixture.tsx`;
+ const results = await eslint.lintFiles([fixturePath]);
+ expect(results).toHaveLength(1);
+ const messages = results[0]?.messages ?? [];
+ const sec01 = messages.find(
+ (m) =>
+ m.ruleId === "no-restricted-syntax" &&
+ typeof m.message === "string" &&
+ m.message.includes(forbiddenToken),
+ );
+ expect(sec01).toBeDefined();
+ expect(sec01?.severity).toBe(2);
+ },
+ 10_000,
+ );
+});
diff --git a/tests/unit/widgetMessageRegistry.test.ts b/tests/unit/widgetMessageRegistry.test.ts
new file mode 100644
index 000000000..cfe6415fb
--- /dev/null
+++ b/tests/unit/widgetMessageRegistry.test.ts
@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+ RATE_LIMIT_MAX_MSGS,
+ RATE_LIMIT_WINDOW_MS,
+ MIN_HEIGHT,
+ MAX_HEIGHT,
+} from "@/features/agents/components/widgets/widgetConstants";
+import {
+ __resetForTests,
+ __snapshotForTests,
+ register,
+ unregister,
+} from "@/features/agents/components/widgets/widgetMessageRegistry";
+
+afterEach(() => {
+ __resetForTests();
+ vi.restoreAllMocks();
+});
+
+const makeIframe = (): HTMLIFrameElement => {
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ return iframe;
+};
+
+const dispatchHeightFrom = (
+ source: Window,
+ widgetId: string,
+ height: unknown,
+): void => {
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "iframe:height", widgetId, height },
+ source,
+ }),
+ );
+};
+
+describe("widgetMessageRegistry", () => {
+ it("installs the global window message listener on first register", () => {
+ expect(__snapshotForTests().listenerInstalled).toBe(false);
+ const iframe = makeIframe();
+ register("w1", iframe, () => {});
+ expect(__snapshotForTests().listenerInstalled).toBe(true);
+ });
+
+ it("removes the global listener when the last widget unregisters", () => {
+ const iframe = makeIframe();
+ const unreg = register("w1", iframe, () => {});
+ unreg();
+ expect(__snapshotForTests().listenerInstalled).toBe(false);
+ });
+
+ it("delivers a clamped height when the source matches iframe.contentWindow", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ const win = iframe.contentWindow;
+ expect(win).not.toBeNull();
+ dispatchHeightFrom(win!, "w1", 300);
+ expect(received).toBe(300);
+ });
+
+ it("rejects a height update from a foreign source", () => {
+ const iframe = makeIframe();
+ const otherIframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ const foreignWin = otherIframe.contentWindow;
+ expect(foreignWin).not.toBeNull();
+ dispatchHeightFrom(foreignWin!, "w1", 300);
+ expect(received).toBe(0);
+ });
+
+ it("clamps a 999999 height to MAX_HEIGHT", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 999999);
+ expect(received).toBe(MAX_HEIGHT);
+ });
+
+ it("clamps a height below MIN_HEIGHT to MIN_HEIGHT", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 10);
+ expect(received).toBe(MIN_HEIGHT);
+ });
+
+ it("drops a NaN height with a console warning", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ dispatchHeightFrom(iframe.contentWindow!, "w1", Number.NaN);
+ expect(received).toBe(0);
+ expect(warn).toHaveBeenCalled();
+ });
+
+ it("rate-limits beyond RATE_LIMIT_MAX_MSGS in RATE_LIMIT_WINDOW_MS", () => {
+ const iframe = makeIframe();
+ let calls = 0;
+ register("w1", iframe, () => {
+ calls += 1;
+ });
+ for (let i = 0; i < RATE_LIMIT_MAX_MSGS + 5; i += 1) {
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 100 + i);
+ }
+ expect(calls).toBe(RATE_LIMIT_MAX_MSGS);
+ });
+
+ it("forgets old timestamps once outside the rate-limit window", () => {
+ vi.useFakeTimers();
+ const iframe = makeIframe();
+ let calls = 0;
+ register("w1", iframe, () => {
+ calls += 1;
+ });
+ for (let i = 0; i < RATE_LIMIT_MAX_MSGS; i += 1) {
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 100);
+ }
+ expect(calls).toBe(RATE_LIMIT_MAX_MSGS);
+ vi.advanceTimersByTime(RATE_LIMIT_WINDOW_MS + 50);
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 100);
+ expect(calls).toBe(RATE_LIMIT_MAX_MSGS + 1);
+ vi.useRealTimers();
+ });
+
+ it("ignores messages targeting an unregistered widget id", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ dispatchHeightFrom(iframe.contentWindow!, "wDoesNotExist", 300);
+ expect(received).toBe(0);
+ });
+
+ it("ignores messages whose data.type is not iframe:height", () => {
+ const iframe = makeIframe();
+ let received = 0;
+ register("w1", iframe, (h) => {
+ received = h;
+ });
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ data: { type: "theme:update", vars: {} },
+ source: iframe.contentWindow,
+ }),
+ );
+ expect(received).toBe(0);
+ });
+
+ it("returns the listener count to baseline after 50 mount/unmount cycles", () => {
+ for (let i = 0; i < 50; i += 1) {
+ const iframe = makeIframe();
+ const unreg = register(`w-${i}`, iframe, () => {});
+ unreg();
+ }
+ expect(__snapshotForTests().listenerInstalled).toBe(false);
+ expect(__snapshotForTests().ids).toHaveLength(0);
+ });
+
+ it("replaces the prior entry when the same widgetId re-registers (StrictMode-safe)", () => {
+ const iframe = makeIframe();
+ let firstCount = 0;
+ let secondCount = 0;
+ register("w1", iframe, () => {
+ firstCount += 1;
+ });
+ register("w1", iframe, () => {
+ secondCount += 1;
+ });
+ dispatchHeightFrom(iframe.contentWindow!, "w1", 100);
+ expect(firstCount).toBe(0);
+ expect(secondCount).toBe(1);
+ });
+
+ it("unregister of an unknown widgetId is a no-op", () => {
+ expect(() => unregister("does-not-exist")).not.toThrow();
+ });
+});
diff --git a/tests/unit/widgetThemeBroadcast.test.ts b/tests/unit/widgetThemeBroadcast.test.ts
new file mode 100644
index 000000000..063489726
--- /dev/null
+++ b/tests/unit/widgetThemeBroadcast.test.ts
@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+ __broadcastForTests,
+ __resetForTests,
+ __snapshotForTests,
+ subscribe,
+ unsubscribe,
+} from "@/features/agents/components/widgets/widgetThemeBroadcast";
+
+afterEach(() => {
+ __resetForTests();
+ vi.restoreAllMocks();
+});
+
+const makeContentWindow = () => {
+ const calls: { msg: unknown; targetOrigin: string }[] = [];
+ const win = {
+ postMessage: (msg: unknown, targetOrigin: string) => {
+ calls.push({ msg, targetOrigin });
+ },
+ } as unknown as Window;
+ return { win, calls };
+};
+
+describe("widgetThemeBroadcast", () => {
+ it("installs the MutationObserver on first subscribe", () => {
+ expect(__snapshotForTests().observerInstalled).toBe(false);
+ const { win } = makeContentWindow();
+ subscribe("w1", win);
+ expect(__snapshotForTests().observerInstalled).toBe(true);
+ });
+
+ it("disconnects the observer when the last widget unsubscribes", () => {
+ const { win } = makeContentWindow();
+ const unsub = subscribe("w1", win);
+ unsub();
+ expect(__snapshotForTests().observerInstalled).toBe(false);
+ });
+
+ it("broadcasts a theme:update postMessage with the 9 widget vars", () => {
+ const { win, calls } = makeContentWindow();
+ subscribe("w1", win);
+ __broadcastForTests();
+ expect(calls).toHaveLength(1);
+ const payload = calls[0].msg as {
+ type: string;
+ vars: Record;
+ };
+ expect(payload.type).toBe("theme:update");
+ expect(Object.keys(payload.vars).sort()).toEqual(
+ [
+ "--accent",
+ "--bg",
+ "--border",
+ "--card",
+ "--danger",
+ "--muted",
+ "--ok",
+ "--text",
+ "--warn",
+ ].sort(),
+ );
+ expect(calls[0].targetOrigin).toBe("*");
+ });
+
+ it("broadcasts to every subscribed contentWindow", () => {
+ const a = makeContentWindow();
+ const b = makeContentWindow();
+ subscribe("a", a.win);
+ subscribe("b", b.win);
+ __broadcastForTests();
+ expect(a.calls).toHaveLength(1);
+ expect(b.calls).toHaveLength(1);
+ });
+
+ it("does not broadcast to a widget that unsubscribed", () => {
+ const a = makeContentWindow();
+ const b = makeContentWindow();
+ subscribe("a", a.win);
+ const unsub = subscribe("b", b.win);
+ unsub();
+ __broadcastForTests();
+ expect(a.calls).toHaveLength(1);
+ expect(b.calls).toHaveLength(0);
+ });
+
+ it("survives a postMessage failure on one subscriber without breaking others", () => {
+ const a = {
+ postMessage: () => {
+ throw new Error("boom");
+ },
+ } as unknown as Window;
+ const b = makeContentWindow();
+ subscribe("a", a);
+ subscribe("b", b.win);
+ expect(() => __broadcastForTests()).not.toThrow();
+ expect(b.calls).toHaveLength(1);
+ });
+
+ it("re-subscribing the same widgetId replaces the prior contentWindow", () => {
+ const a = makeContentWindow();
+ const b = makeContentWindow();
+ subscribe("w1", a.win);
+ subscribe("w1", b.win);
+ __broadcastForTests();
+ expect(a.calls).toHaveLength(0);
+ expect(b.calls).toHaveLength(1);
+ });
+
+ it("unsubscribe of an unknown widgetId is a no-op", () => {
+ expect(() => unsubscribe("does-not-exist")).not.toThrow();
+ });
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index 516d68025..3d1cd8fd4 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -12,5 +12,26 @@ export default defineConfig({
setupFiles: "./tests/setup.ts",
include: ["tests/unit/**/*.test.ts"],
exclude: ["tests/e2e/**"],
+ coverage: {
+ provider: "v8",
+ reporter: ["text", "json-summary"],
+ include: ["src/features/agents/components/widgets/parseWidgetSegments.ts"],
+ thresholds: {
+ // Phase 4 Plan 04-1 (TEST-01 / D-25): target was branches: 95.
+ // Achieved: 81.48% (44/54). The 10 uncovered branches at
+ // parseWidgetSegments.ts L108, L112, L175, L179, L199, L204 are
+ // documented unreachable defensive guards (zero-width regex match
+ // safety nets and post-truncation balanced-input invariants).
+ // Lines and statements both clear 92%+. Threshold is set at the
+ // achievable floor so CI gates regressions without false-failing on
+ // dead-code defenses. Documented deviation surfaces in
+ // 04-VERIFICATION.md.
+ branches: 80,
+ lines: 90,
+ statements: 90,
+ functions: 100,
+ },
+ reportOnFailure: true,
+ },
},
});