@stigmer/react 3.1.3 → 3.1.4

package/src/internal/MermaidDiagram.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useIsCodeFenceIncomplete } from "streamdown";
+import { useColorMode } from "../color-mode.js";
+import { loadMermaid } from "./mermaid-loader.js";
+import { MERMAID_THEME_CSS } from "./mermaid-theme-css.js";
+
+/**
+ * `mermaid.render` requires a DOM id for its scratch element. Ids must be
+ * unique per render call — theme switches and streaming updates can overlap
+ * renders within one component — so a module counter is the simplest
+ * collision-free source.
+ */
+let renderSequence = 0;
+
+/** Props for {@link MermaidDiagram}. */
+export interface MermaidDiagramProps {
+  /** The raw Mermaid source from the fenced code block. */
+  readonly chart: string;
+}
+
+type RenderState =
+  | { readonly status: "pending" }
+  | { readonly status: "rendered"; readonly svg: string }
+  | { readonly status: "failed"; readonly message: string };
+
+/**
+ * Renders a fenced ```mermaid block as an inline SVG diagram.
+ *
+ * Mounted by the shared `pre` override in
+ * {@link file://./markdown-components.tsx} whenever a fenced block carries the
+ * explicit `mermaid` info string — which means every SDK markdown surface
+ * (chat via Streamdown, artifacts/skills via react-markdown) renders diagrams
+ * identically. Detection is deliberately limited to the explicit language tag;
+ * guessing diagram intent from fence bodies (e.g. a bare fence starting with
+ * `flowchart`) is the kind of fuzzy heuristic this codebase avoids.
+ *
+ * Every failure mode degrades to the exact code block the fence rendered as
+ * before this component existed:
+ *
+ * - **Streaming** — while the fence is still open (`useIsCodeFenceIncomplete`,
+ *   a safe no-op under react-markdown where the context defaults to `false`),
+ *   the source renders as a code block; the diagram appears once the fence
+ *   closes. No half-parsed error flashing mid-stream.
+ * - **Library unavailable** — `mermaid` is an optional peer dependency; if the
+ *   dynamic import fails the source stays a code block.
+ * - **Parse error** — invalid diagram source falls back to the code block plus
+ *   a screen-reader-announced note, so the agent's output is never hidden.
+ *
+ * Security: agent output is untrusted and this SDK renders inside host
+ * applications, so mermaid runs with `securityLevel: "strict"` (sanitized
+ * labels, no `click` interactivity) — deliberately stricter than the
+ * docs-site renderer, which only ever shows first-party content.
+ *
+ * Theming: the container chrome is fully `--stgm-*` token-driven, and so is
+ * the SVG interior. The built-in `default`/`dark` theme (selected via
+ * {@link useColorMode}) is the base; on top of it we inject
+ * {@link MERMAID_THEME_CSS}, a token-driven stylesheet whose `var(--stgm-*)`
+ * references the browser resolves against the `.stgm` scope. Interiors
+ * therefore track the active preset *and* color mode live — no color is read
+ * in JS, and a preset switch needs no re-render. Feeding tokens through
+ * mermaid's `themeVariables` is not possible: they are authored in `oklch()`,
+ * which mermaid's color engine (khroma) cannot parse. Any element or diagram
+ * type the CSS does not target falls back to the built-in theme, so a diagram
+ * is never blank or mis-colored.
+ */
+export function MermaidDiagram({ chart }: MermaidDiagramProps) {
+  const isIncomplete = useIsCodeFenceIncomplete();
+  const colorMode = useColorMode();
+  const [state, setState] = useState<RenderState>({ status: "pending" });
+
+  // Markdown parsers hand the fence body over with its trailing newline;
+  // mermaid treats leading/trailing blank lines as part of the diagram.
+  const source = chart.trim();
+
+  useEffect(() => {
+    if (isIncomplete || source.length === 0) return;
+
+    let cancelled = false;
+
+    void (async () => {
+      const renderId = `stgm-mermaid-${++renderSequence}`;
+      try {
+        const mermaid = await loadMermaid();
+        // initialize() mutates a global singleton, so it runs before every
+        // render call — all diagrams under one provider share a color mode,
+        // and re-initializing keeps a theme switch from bleeding stale config
+        // into the next render.
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "strict",
+          theme: colorMode === "dark" ? "dark" : "default",
+          themeCSS: MERMAID_THEME_CSS,
+          fontFamily: "inherit",
+        });
+        const { svg } = await mermaid.render(renderId, source);
+        if (!cancelled) setState({ status: "rendered", svg });
+      } catch (error: unknown) {
+        // Mermaid has historically leaked its scratch element into the
+        // document on parse failure; removing it defensively costs nothing.
+        document.getElementById(renderId)?.remove();
+        if (!cancelled) {
+          setState({
+            status: "failed",
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // A previously rendered diagram stays visible while a re-render (theme
+    // switch) is in flight — swapping to a blank pending state would flash.
+  }, [source, colorMode, isIncomplete]);
+
+  if (state.status === "rendered") {
+    return (
+      <div
+        role="img"
+        aria-label="Mermaid diagram"
+        className="mb-3 last:mb-0 flex justify-center overflow-x-auto rounded-md border border-border bg-card p-3 [&_svg]:max-w-full"
+        dangerouslySetInnerHTML={{ __html: state.svg }}
+      />
+    );
+  }
+
+  return (
+    <MermaidSourceFallback
+      chart={chart}
+      failureMessage={state.status === "failed" ? state.message : null}
+    />
+  );
+}
+
+/**
+ * The pre-diagram presentation of a mermaid fence: the same styled code block
+ * the shared `pre`/`code` overrides in `markdown-components.tsx` would have
+ * produced (classes mirrored from there — importing them would create a
+ * module cycle, since that file mounts this component). Shown while the fence
+ * streams, while mermaid loads, and permanently when rendering fails.
+ */
+function MermaidSourceFallback({
+  chart,
+  failureMessage,
+}: {
+  chart: string;
+  failureMessage: string | null;
+}) {
+  return (
+    <div className="mb-3 last:mb-0">
+      <pre className="overflow-x-auto rounded-md bg-muted p-3">
+        <code className="font-mono text-xs text-foreground">{chart}</code>
+      </pre>
+      {failureMessage !== null && (
+        <p role="status" className="mt-1 text-xs text-muted-foreground">
+          Mermaid diagram failed to render; showing source. ({failureMessage})
+        </p>
+      )}
+    </div>
+  );
+}

package/src/internal/__tests__/a11y/mermaid-theme.a11y.test.tsx

@@ -0,0 +1,122 @@
+// Browser-mode regression guard (runs under vitest.a11y.config.ts in real
+// Chromium) for token-driven Mermaid interior theming.
+//
+// This is not an axe audit — it lives here because the claim can only be
+// verified against real layout + a real CSS engine: that Mermaid's injected
+// `themeCSS` (authored with `var(--stgm-*)`) survives `securityLevel: "strict"`
+// (mermaid's `sanitizeCss` + DOMPurify) and is resolved by the browser cascade
+// against the `.stgm` scope. Source analysis already proves survivability; this
+// test locks it against future mermaid/DOMPurify upgrades and proves, end to
+// end, that interiors track the active color mode and preset live — with no
+// component re-render (we mutate the scope in the DOM, never React state).
+
+import "../../../../dist/styles.css";
+import "@stigmer/theme/presets/fintech.css";
+
+import { describe, it, afterEach, expect } from "vitest";
+import { render, cleanup, waitFor } from "@testing-library/react";
+import { ColorModeContext, type ResolvedColorMode } from "../../../color-mode.js";
+import { MermaidDiagram } from "../../MermaidDiagram.js";
+
+const CHART = "flowchart LR\n  A[Hello] --> B[World]";
+
+const NODE_SHAPE_SELECTOR =
+  "svg .node rect, svg .node polygon, svg .node circle, svg .node ellipse, svg .node path";
+
+interface Mounted {
+  readonly container: HTMLElement;
+  /** The painted node shape whose `fill` our `themeCSS` drives from a token. */
+  readonly nodeShape: SVGElement;
+  /** Probe resolving `var(--stgm-muted)` (node fill) in the same scope. */
+  readonly mutedProbe: HTMLElement;
+  /** Probe resolving `var(--stgm-primary)` in the same scope. */
+  readonly primaryProbe: HTMLElement;
+}
+
+/**
+ * Render a diagram inside a `.stgm` scope carrying `scopeClass` (e.g. a preset)
+ * and `mode`, alongside two probe spans that resolve the same tokens. Resolves
+ * once the SVG interior has painted.
+ */
+async function mount(
+  scopeClass: string,
+  mode: ResolvedColorMode,
+): Promise<Mounted> {
+  const container = document.createElement("div");
+  container.className = `stgm ${scopeClass}`.trim();
+  container.setAttribute("data-stgm-color-mode", mode);
+  document.body.appendChild(container);
+
+  render(
+    <ColorModeContext.Provider value={mode}>
+      <span data-probe="muted" style={{ color: "var(--stgm-muted)" }} />
+      <span data-probe="primary" style={{ color: "var(--stgm-primary)" }} />
+      <MermaidDiagram chart={CHART} />
+    </ColorModeContext.Provider>,
+    { container },
+  );
+
+  await waitFor(() => {
+    const shape = container.querySelector(NODE_SHAPE_SELECTOR);
+    if (!shape) throw new Error("diagram node not rendered yet");
+  });
+
+  return {
+    container,
+    nodeShape: container.querySelector(NODE_SHAPE_SELECTOR) as SVGElement,
+    mutedProbe: container.querySelector('[data-probe="muted"]') as HTMLElement,
+    primaryProbe: container.querySelector('[data-probe="primary"]') as HTMLElement,
+  };
+}
+
+afterEach(() => {
+  cleanup();
+  document.querySelectorAll(".stgm").forEach((node) => node.remove());
+});
+
+describe("Mermaid interior theming — token-driven, cascade-resolved", () => {
+  it("paints node interiors from --stgm-* tokens, not mermaid's stock palette", async () => {
+    const { nodeShape, mutedProbe } = await mount("", "light");
+    // If our themeCSS lost the specificity/order battle, the fill would be
+    // mermaid's default (#ECECFF-ish) and this exact-match would fail.
+    expect(getComputedStyle(nodeShape).fill).toBe(
+      getComputedStyle(mutedProbe).color,
+    );
+  });
+
+  it("tracks a color-mode switch live, with no re-render", async () => {
+    const { container, nodeShape, mutedProbe } = await mount("", "light");
+    const fillLight = getComputedStyle(nodeShape).fill;
+    expect(fillLight).toBe(getComputedStyle(mutedProbe).color);
+
+    // Flip the scope attribute directly — no React update. Pure cascade.
+    container.setAttribute("data-stgm-color-mode", "dark");
+
+    const fillDark = getComputedStyle(nodeShape).fill;
+    expect(fillDark).toBe(getComputedStyle(mutedProbe).color);
+    expect(fillDark).not.toBe(fillLight);
+  });
+
+  it("tracks the active preset", async () => {
+    const { nodeShape, mutedProbe, primaryProbe } = await mount(
+      "stgm-theme-fintech",
+      "light",
+    );
+    // The diagram is painted from the ACTIVE preset's resolved token.
+    expect(getComputedStyle(nodeShape).fill).toBe(
+      getComputedStyle(mutedProbe).color,
+    );
+
+    // Guard against a false pass where the preset CSS never loaded: fintech's
+    // primary (indigo) must differ from the default palette's primary (teal).
+    const defaultScope = document.createElement("div");
+    defaultScope.className = "stgm";
+    defaultScope.setAttribute("data-stgm-color-mode", "light");
+    defaultScope.innerHTML = '<span style="color: var(--stgm-primary)"></span>';
+    document.body.appendChild(defaultScope);
+
+    expect(getComputedStyle(primaryProbe).color).not.toBe(
+      getComputedStyle(defaultScope.firstElementChild as HTMLElement).color,
+    );
+  });
+});

package/src/internal/__tests__/markdown-components.test.tsx

@@ -1,12 +1,23 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { render, cleanup } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
+import Markdown from "react-markdown";
 import {
   MARKDOWN_COMPONENTS,
+  REMARK_PLUGINS,
   extractLeadingH1,
   unwrapEnclosingMarkdownFence,
 } from "../markdown-components";
 
+// Stub the diagram component: these tests verify the DISPATCH seam (which
+// fences route to the diagram vs the code block), not mermaid rendering —
+// that contract is covered by mermaid-diagram.test.tsx.
+vi.mock("../MermaidDiagram", () => ({
+  MermaidDiagram: ({ chart }: { chart: string }) => (
+    <div data-testid="mermaid-diagram">{chart}</div>
+  ),
+}));
+
 afterEach(cleanup);
 
 /** The shared `code` override, typed for direct rendering in tests. */
@@ -15,6 +26,11 @@ const CodeComponent = MARKDOWN_COMPONENTS.code as ComponentType<{
   children?: ReactNode;
 }>;
 
+/** The shared `pre` override, typed for direct rendering in tests. */
+const PreComponent = MARKDOWN_COMPONENTS.pre as ComponentType<{
+  children?: ReactNode;
+}>;
+
 describe("unwrapEnclosingMarkdownFence", () => {
   describe("unwraps a whole-message markdown fence", () => {
     it.each([
@@ -185,3 +201,79 @@ describe("MARKDOWN_COMPONENTS.code (shared highlight seam)", () => {
     expect(code!.textContent).toBe("inlineToken");
   });
 });
+
+describe("MARKDOWN_COMPONENTS.pre (mermaid dispatch seam)", () => {
+  const CHART = "flowchart LR\n  A --> B";
+
+  it("routes an explicit ```mermaid fence to the diagram, dropping the <pre> wrapper", () => {
+    const { container } = render(
+      <PreComponent>
+        <code className="language-mermaid">{CHART}</code>
+      </PreComponent>,
+    );
+
+    const diagram = container.querySelector('[data-testid="mermaid-diagram"]');
+    expect(diagram).not.toBeNull();
+    expect(diagram!.textContent).toBe(CHART);
+    // The diagram replaces the <pre> entirely — a block container inside
+    // <pre> would be invalid HTML and inherit code-block chrome.
+    expect(container.querySelector("pre")).toBeNull();
+  });
+
+  it("matches language-mermaid among multiple classes", () => {
+    const { container } = render(
+      <PreComponent>
+        <code className="language-mermaid extra-class">{CHART}</code>
+      </PreComponent>,
+    );
+
+    expect(
+      container.querySelector('[data-testid="mermaid-diagram"]'),
+    ).not.toBeNull();
+  });
+
+  it.each([
+    [
+      "a different language",
+      <code key="go" className="language-go">{"func main() {}"}</code>,
+    ],
+    [
+      "a language merely PREFIXED with mermaid",
+      <code key="pfx" className="language-mermaidjs">{CHART}</code>,
+    ],
+    ["an untagged fence", <code key="bare">{CHART}</code>],
+    [
+      "non-string code children",
+      <code key="node" className="language-mermaid">
+        <span>{CHART}</span>
+      </code>,
+    ],
+    ["plain-text children (no code element)", CHART],
+  ])("keeps the ordinary <pre> code block for %s", (_label, children) => {
+    const { container } = render(<PreComponent>{children}</PreComponent>);
+
+    expect(container.querySelector('[data-testid="mermaid-diagram"]')).toBeNull();
+    const pre = container.querySelector("pre");
+    expect(pre).not.toBeNull();
+    expect(pre!.className).toContain("bg-muted");
+  });
+
+  it("dispatches through real react-markdown (the artifact/skill surface path)", () => {
+    // Renders an actual document instead of synthetic elements, proving the
+    // element shape react-markdown hands to `pre` matches what the seam
+    // detects. The Streamdown (chat) path has the equivalent end-to-end
+    // coverage in message-entry.test.tsx.
+    const doc = `Before\n\n\`\`\`mermaid\n${CHART}\n\`\`\`\n\n\`\`\`go\nfunc main() {}\n\`\`\``;
+    const { container } = render(
+      <Markdown remarkPlugins={REMARK_PLUGINS} components={MARKDOWN_COMPONENTS}>
+        {doc}
+      </Markdown>,
+    );
+
+    const diagram = container.querySelector('[data-testid="mermaid-diagram"]');
+    expect(diagram).not.toBeNull();
+    expect(diagram!.textContent).toContain("flowchart LR");
+    // The sibling go fence still renders as an ordinary highlighted block.
+    expect(container.querySelector("pre code.language-go")).not.toBeNull();
+  });
+});

package/src/internal/__tests__/mermaid-diagram.test.tsx

@@ -0,0 +1,282 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup, waitFor, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { MermaidDiagram } from "../MermaidDiagram";
+import { loadMermaid, type MermaidModule } from "../mermaid-loader";
+import { MERMAID_THEME_CSS } from "../mermaid-theme-css";
+import { ColorModeContext, type ResolvedColorMode } from "../../color-mode";
+
+// The loader is the component's only side-effectful dependency; mocking it
+// (not the `mermaid` package) exercises the real degradation contract:
+// a rejected load must look exactly like "library not installed".
+vi.mock("../mermaid-loader", () => ({
+  loadMermaid: vi.fn(),
+}));
+
+// Partial-mock streamdown so tests can drive the incomplete-fence signal
+// without spinning up a full Streamdown render.
+vi.mock("streamdown", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("streamdown")>()),
+  useIsCodeFenceIncomplete: vi.fn(() => false),
+}));
+
+const { useIsCodeFenceIncomplete } = await import("streamdown");
+
+const loadMermaidMock = vi.mocked(loadMermaid);
+const incompleteFenceMock = vi.mocked(useIsCodeFenceIncomplete);
+
+/** Builds a mermaid module stub whose render resolves with the given SVG. */
+function stubMermaid(svg = "<svg><g>diagram</g></svg>") {
+  const mermaid = {
+    initialize: vi.fn(),
+    render: vi.fn().mockResolvedValue({ svg }),
+  };
+  loadMermaidMock.mockResolvedValue(mermaid as unknown as MermaidModule);
+  return mermaid;
+}
+
+function renderDiagram(
+  chart: string,
+  { colorMode = "light" as ResolvedColorMode } = {},
+) {
+  return render(
+    <ColorModeContext.Provider value={colorMode}>
+      <MermaidDiagram chart={chart} />
+    </ColorModeContext.Provider>,
+  );
+}
+
+function queryDiagram(container: HTMLElement) {
+  return container.querySelector('[role="img"][aria-label="Mermaid diagram"]');
+}
+
+beforeEach(() => {
+  loadMermaidMock.mockReset();
+  incompleteFenceMock.mockReset();
+  incompleteFenceMock.mockReturnValue(false);
+});
+
+afterEach(cleanup);
+
+const CHART = "flowchart LR\n  A --> B";
+
+describe("MermaidDiagram — successful render", () => {
+  it("renders the SVG in an accessible container", async () => {
+    stubMermaid("<svg data-diagram><g>ok</g></svg>");
+    const { container } = renderDiagram(CHART);
+
+    await waitFor(() => expect(queryDiagram(container)).not.toBeNull());
+    expect(queryDiagram(container)!.querySelector("svg[data-diagram]")).not.toBeNull();
+    // The source fallback is gone once the diagram is up.
+    expect(container.querySelector("pre")).toBeNull();
+  });
+
+  it("shows the source as a code block while the render is pending", () => {
+    // A load that never settles = the loading window.
+    loadMermaidMock.mockReturnValue(new Promise(() => {}));
+    const { container } = renderDiagram(CHART);
+
+    const code = container.querySelector("pre code");
+    expect(code).not.toBeNull();
+    expect(code!.textContent).toBe(CHART);
+    expect(queryDiagram(container)).toBeNull();
+  });
+
+  it("trims the trailing newline the fence body carries before rendering", async () => {
+    const mermaid = stubMermaid();
+    renderDiagram("flowchart LR\n  A --> B\n");
+
+    await waitFor(() => expect(mermaid.render).toHaveBeenCalled());
+    expect(mermaid.render).toHaveBeenCalledWith(
+      expect.any(String),
+      "flowchart LR\n  A --> B",
+    );
+  });
+});
+
+describe("MermaidDiagram — security and theming configuration", () => {
+  it("configures mermaid with securityLevel strict (agent output is untrusted)", async () => {
+    const mermaid = stubMermaid();
+    renderDiagram(CHART);
+
+    await waitFor(() => expect(mermaid.initialize).toHaveBeenCalled());
+    expect(mermaid.initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ securityLevel: "strict", startOnLoad: false }),
+    );
+  });
+
+  it("injects the token-driven themeCSS so interiors track --stgm-* tokens", async () => {
+    const mermaid = stubMermaid();
+    renderDiagram(CHART);
+
+    await waitFor(() => expect(mermaid.initialize).toHaveBeenCalled());
+    // The interior palette rides on themeCSS (var(--stgm-*)), layered over the
+    // built-in default/dark base theme. The browser-mode a11y suite verifies
+    // the CSS actually resolves; here we lock the wiring itself.
+    expect(mermaid.initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ themeCSS: MERMAID_THEME_CSS }),
+    );
+  });
+
+  it.each([
+    ["light", "default"],
+    ["dark", "dark"],
+  ] as const)("selects the %s theme for %s color mode", async (mode, theme) => {
+    const mermaid = stubMermaid();
+    renderDiagram(CHART, { colorMode: mode });
+
+    await waitFor(() => expect(mermaid.initialize).toHaveBeenCalled());
+    expect(mermaid.initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ theme }),
+    );
+  });
+
+  it("re-renders the diagram when the color mode changes", async () => {
+    const mermaid = stubMermaid();
+    const { container, rerender } = render(
+      <ColorModeContext.Provider value="light">
+        <MermaidDiagram chart={CHART} />
+      </ColorModeContext.Provider>,
+    );
+    await waitFor(() => expect(queryDiagram(container)).not.toBeNull());
+
+    rerender(
+      <ColorModeContext.Provider value="dark">
+        <MermaidDiagram chart={CHART} />
+      </ColorModeContext.Provider>,
+    );
+
+    await waitFor(() => expect(mermaid.render).toHaveBeenCalledTimes(2));
+    expect(mermaid.initialize).toHaveBeenLastCalledWith(
+      expect.objectContaining({ theme: "dark" }),
+    );
+  });
+});
+
+describe("MermaidDiagram — failure degrades to the code block", () => {
+  it("falls back with an announced note when the diagram source is invalid", async () => {
+    loadMermaidMock.mockResolvedValue({
+      initialize: vi.fn(),
+      render: vi.fn().mockRejectedValue(new Error("Parse error on line 2")),
+    } as unknown as MermaidModule);
+    const { container } = renderDiagram("flowchart LR\n  A --> ");
+
+    await waitFor(() =>
+      expect(container.querySelector('[role="status"]')).not.toBeNull(),
+    );
+    expect(container.querySelector("pre code")!.textContent).toContain(
+      "A -->",
+    );
+    expect(container.querySelector('[role="status"]')!.textContent).toContain(
+      "Parse error on line 2",
+    );
+    expect(queryDiagram(container)).toBeNull();
+  });
+
+  it("falls back when the mermaid library cannot be loaded (optional peer absent)", async () => {
+    loadMermaidMock.mockRejectedValue(
+      new Error("Cannot find module 'mermaid'"),
+    );
+    const { container } = renderDiagram(CHART);
+
+    await waitFor(() =>
+      expect(container.querySelector('[role="status"]')).not.toBeNull(),
+    );
+    expect(container.querySelector("pre code")!.textContent).toBe(CHART);
+    expect(queryDiagram(container)).toBeNull();
+  });
+
+  it("does not attempt to render an empty fence", () => {
+    stubMermaid();
+    const { container } = renderDiagram("   \n  ");
+
+    expect(loadMermaidMock).not.toHaveBeenCalled();
+    expect(queryDiagram(container)).toBeNull();
+  });
+});
+
+describe("MermaidDiagram — streaming deferral", () => {
+  it("defers rendering while the fence is still streaming", () => {
+    stubMermaid();
+    incompleteFenceMock.mockReturnValue(true);
+    const { container } = renderDiagram(CHART);
+
+    expect(loadMermaidMock).not.toHaveBeenCalled();
+    const code = container.querySelector("pre code");
+    expect(code).not.toBeNull();
+    expect(code!.textContent).toBe(CHART);
+  });
+
+  it("renders the diagram once the fence closes", async () => {
+    stubMermaid();
+    incompleteFenceMock.mockReturnValue(true);
+    const { container, rerender } = renderDiagram(CHART);
+    expect(queryDiagram(container)).toBeNull();
+
+    incompleteFenceMock.mockReturnValue(false);
+    rerender(
+      <ColorModeContext.Provider value="light">
+        <MermaidDiagram chart={CHART} />
+      </ColorModeContext.Provider>,
+    );
+
+    await waitFor(() => expect(queryDiagram(container)).not.toBeNull());
+  });
+});
+
+describe("MermaidDiagram — stale-render races", () => {
+  it("discards a render that resolves after the chart has changed", async () => {
+    const initialize = vi.fn();
+    let resolveFirst!: (result: { svg: string }) => void;
+    const renderMock = vi
+      .fn()
+      .mockImplementationOnce(
+        () => new Promise((resolve) => (resolveFirst = resolve)),
+      )
+      .mockResolvedValue({ svg: "<svg data-chart='second'></svg>" });
+    loadMermaidMock.mockResolvedValue({
+      initialize,
+      render: renderMock,
+    } as unknown as MermaidModule);
+
+    const { container, rerender } = renderDiagram("flowchart LR\n  A --> B");
+    await waitFor(() => expect(renderMock).toHaveBeenCalledTimes(1));
+
+    rerender(
+      <ColorModeContext.Provider value="light">
+        <MermaidDiagram chart={"flowchart LR\n  C --> D"} />
+      </ColorModeContext.Provider>,
+    );
+    await waitFor(() =>
+      expect(
+        container.querySelector("svg[data-chart='second']"),
+      ).not.toBeNull(),
+    );
+
+    // The first (now stale) render settles late — it must not clobber the
+    // second chart's SVG.
+    act(() => resolveFirst({ svg: "<svg data-chart='first'></svg>" }));
+    expect(container.querySelector("svg[data-chart='first']")).toBeNull();
+    expect(container.querySelector("svg[data-chart='second']")).not.toBeNull();
+  });
+
+  it("ignores a render that settles after unmount", async () => {
+    let resolveRender!: (result: { svg: string }) => void;
+    loadMermaidMock.mockResolvedValue({
+      initialize: vi.fn(),
+      render: vi.fn().mockReturnValue(
+        new Promise((resolve) => (resolveRender = resolve)),
+      ),
+    } as unknown as MermaidModule);
+
+    const { unmount } = renderDiagram(CHART);
+    await waitFor(() => expect(loadMermaidMock).toHaveBeenCalled());
+    unmount();
+
+    // Settling after unmount must not warn or throw (React state update on
+    // an unmounted component).
+    expect(() =>
+      act(() => resolveRender({ svg: "<svg></svg>" })),
+    ).not.toThrow();
+  });
+});