@stigmer/react 3.1.3 → 3.1.5

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/VirtualizedThread.tsx

@@ -15,6 +15,7 @@ import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 import {
   ThreadItemRenderer,
   threadContentColumnClass,
+  type MessageThreadSlots,
   type ThreadItem,
   type ThreadContentColumn,
 } from "../execution/MessageThread.js";
@@ -55,6 +56,7 @@ export interface VirtualizedThreadProps {
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
+  readonly slots?: MessageThreadSlots;
 }
 
 // ---------------------------------------------------------------------------
@@ -124,6 +126,7 @@ export function VirtualizedThread({
   onRetrySend,
   onRetryExecution,
   onEditMessage,
+  slots,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -161,8 +164,9 @@ export function VirtualizedThread({
       onRetrySend,
       onRetryExecution,
       onEditMessage,
+      slots,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage, slots],
   );
 
   return (

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();
+  });
+});