@stigmer/react 3.1.3 → 3.1.5

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

package/src/internal/markdown-components.tsx

@@ -1,10 +1,12 @@
-import type { ComponentProps, JSX } from "react";
+import { isValidElement, type ComponentProps, type JSX, type ReactNode } from "react";
 import type { Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { cn } from "@stigmer/theme";
 import { highlightToReact } from "./code-highlight.js";
+import { MermaidDiagram } from "./MermaidDiagram.js";
 
 const LANGUAGE_CLASS_PREFIX = "language-";
+const MERMAID_LANGUAGE_CLASS = "language-mermaid";
 
 type MdProps<T extends keyof JSX.IntrinsicElements> = ComponentProps<T>;
 
@@ -119,6 +121,30 @@ export function extractLeadingH1(markdown: string): {
   return { title: match[1], body: trimmed.slice(match[0].length) };
 }
 
+/**
+ * Returns the mermaid source when a `pre` element's children are a single
+ * fenced code block explicitly tagged `mermaid`, or `null` otherwise.
+ *
+ * Both renderers (Streamdown for chat, react-markdown for artifacts/skills)
+ * hand `pre` exactly one `<code>` child whose `className` carries the fence's
+ * info string as `language-*` and whose children are the raw source text.
+ * Anything that deviates from that shape — a different language, a missing
+ * tag, non-string children — is not a mermaid fence and keeps the ordinary
+ * code-block rendering. Only the explicit `mermaid` tag qualifies:
+ * inspecting fence bodies to guess diagram intent is the kind of fuzzy
+ * heuristic this codebase avoids.
+ */
+function extractMermaidSource(children: ReactNode): string | null {
+  if (!isValidElement(children)) return null;
+  const { className, children: code } = children.props as {
+    className?: unknown;
+    children?: unknown;
+  };
+  if (typeof className !== "string") return null;
+  if (!className.split(/\s+/).includes(MERMAID_LANGUAGE_CLASS)) return null;
+  return typeof code === "string" ? code : null;
+}
+
 /**
  * Styled react-markdown component overrides for SDK markdown surfaces.
  *
@@ -208,6 +234,15 @@ export const MARKDOWN_COMPONENTS: Components = {
   },
 
   pre({ children, ...props }: MdProps<"pre">) {
+    // A ```mermaid fence renders as a diagram, not a code block. The check
+    // lives here (not in the `code` override) because the diagram must
+    // replace the <pre> wrapper too — a block-level diagram container inside
+    // <pre> is invalid HTML and would inherit code-block chrome.
+    const mermaidSource = extractMermaidSource(children);
+    if (mermaidSource !== null) {
+      return <MermaidDiagram chart={mermaidSource} />;
+    }
+
     return (
       <pre
         className="mb-3 last:mb-0 overflow-x-auto rounded-md bg-muted p-3"

package/src/internal/mermaid-loader.ts

@@ -0,0 +1,44 @@
+/**
+ * Lazy loader for the `mermaid` library, isolated in its own module — the
+ * same seam pattern as `workflow/layout/elk-layout-engine.ts` — so
+ * {@link file://./MermaidDiagram.tsx} stays a pure presentation component and
+ * tests can mock the load outcome (resolve, reject) without touching module
+ * registries.
+ *
+ * `mermaid` is an optional peer dependency (DD-013): it is large, so it must
+ * never sit on the synchronous bundle path, and a host that has not installed
+ * it must degrade gracefully (the caller falls back to a code block).
+ */
+
+/**
+ * The mermaid API surface the SDK consumes, typed from the package itself so
+ * it stays in lockstep with the installed version.
+ */
+export type MermaidModule = typeof import("mermaid").default;
+
+/**
+ * Holds the in-flight import promise so concurrent diagrams share one load.
+ * A failed import clears the cache: rejections are often transient (a
+ * chunk-load hiccup mid-deploy), and caching one would break every diagram
+ * for the rest of the session.
+ */
+let mermaidImport: Promise<MermaidModule> | null = null;
+
+/**
+ * Dynamically imports `mermaid`, sharing one in-flight import across callers.
+ *
+ * @returns The mermaid default export.
+ * @throws If `mermaid` cannot be imported (not installed, or the async chunk
+ *   failed to load). Callers treat this as "diagrams unavailable" and render
+ *   the fenced source as a plain code block.
+ */
+export function loadMermaid(): Promise<MermaidModule> {
+  mermaidImport ??= import("mermaid").then(
+    (module) => module.default,
+    (error: unknown) => {
+      mermaidImport = null;
+      throw error;
+    },
+  );
+  return mermaidImport;
+}

package/src/internal/mermaid-theme-css.ts

@@ -0,0 +1,178 @@
+/**
+ * Token-driven `themeCSS` for Mermaid diagram interiors.
+ *
+ * Mermaid's built-in `default`/`dark` themes color a diagram's SVG interior
+ * with a fixed palette that ignores the host's `--stgm-*` preset (Corporate,
+ * Fintech, ...). The obvious fix — feeding resolved tokens into Mermaid's
+ * `themeVariables` — is blocked: our tokens are authored in `oklch()`, and
+ * Mermaid's color engine (`khroma`) parses only hex/rgb/hsl/keyword, so it
+ * throws or NaNs on `oklch(...)`. (Mermaid also gates every `themeVariables`
+ * value through the allowlist `^[\d "#%(),.;A-Za-z]+$`, which excludes `-` and
+ * would blank any `var(--...)`.)
+ *
+ * Instead we hand Mermaid this CSS via `initialize({ themeCSS })`. Mermaid
+ * injects it into the diagram's own `<style>` block, scoped under the render
+ * id (`#stgm-mermaid-N`), *after* the theme palette it computes. Because every
+ * selector in that block is id-prefixed, our rules and the palette's rules sit
+ * at equal specificity, so ours win by source order — and `!important` makes
+ * that bulletproof against the few palette rules that are themselves important
+ * or inlined. Crucially, `themeCSS` never passes through khroma, so the
+ * `oklch()`-backed `var(--stgm-*)` references flow straight to the browser,
+ * which resolves them against the `.stgm` scope the SVG lives in. That is why
+ * interiors track the active preset *and* color mode live, with no JS color
+ * reading and no re-render on theme change.
+ *
+ * `initialize({ theme })` still selects the built-in `default`/`dark` theme as
+ * the base, so any element or diagram type we do not target here degrades to
+ * Mermaid's stock palette — never a blank or mis-colored diagram.
+ *
+ * Palette intent (subtle surfaces + brand accents — legibility over brand
+ * saturation): node/actor bodies sit on a muted surface with quiet
+ * token-colored borders and edges; labels use the standard foreground; the
+ * brand `--stgm-primary` is reserved for structural headers (subgraph/cluster
+ * titles, sequence loop/section titles, the sequence-number badge).
+ *
+ * Coverage is the two families agents emit overwhelmingly — flowchart and
+ * sequence — plus the shared marker/edge-label chrome. Both label render paths
+ * are handled: SVG `text`/`tspan` (via `fill`) and HTML labels inside
+ * `foreignObject` (via `color`).
+ */
+export const MERMAID_THEME_CSS = `
+  /* Shared: edge arrowheads / markers */
+  .marker {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .marker.cross {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Flowchart: node bodies */
+  .node rect,
+  .node circle,
+  .node ellipse,
+  .node polygon,
+  .node path {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .node .neo-node {
+    stroke: var(--stgm-border) !important;
+  }
+  .node .katex path {
+    fill: var(--stgm-foreground) !important;
+    stroke: var(--stgm-foreground) !important;
+  }
+
+  /* Flowchart: node labels (SVG text and HTML spans) */
+  .label {
+    color: var(--stgm-foreground) !important;
+  }
+  .label text,
+  .label span {
+    fill: var(--stgm-foreground) !important;
+    color: var(--stgm-foreground) !important;
+  }
+
+  /* Flowchart: edges */
+  .edgePath .path,
+  .flowchart-link {
+    stroke: var(--stgm-border) !important;
+  }
+  .arrowheadPath,
+  .root .anchor path {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Flowchart: edge labels sit on the diagram surface for legibility */
+  .edgeLabel,
+  .edgeLabel p,
+  .edgeLabel rect,
+  .labelBkg {
+    background-color: var(--stgm-card) !important;
+    fill: var(--stgm-card) !important;
+  }
+
+  /* Flowchart: subgraph clusters — muted surface, brand-accent title */
+  .cluster rect {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .cluster-label text,
+  .cluster text {
+    fill: var(--stgm-primary) !important;
+  }
+  .cluster-label span,
+  .cluster span {
+    color: var(--stgm-primary) !important;
+  }
+
+  /* Sequence: actors and lifelines */
+  .actor {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  text.actor > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .actor-line {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Sequence: messages */
+  .messageLine0,
+  .messageLine1 {
+    stroke: var(--stgm-border) !important;
+  }
+  [id$="-arrowhead"] path,
+  [id$="-crosshead"] path {
+    fill: var(--stgm-border) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .messageText {
+    fill: var(--stgm-foreground) !important;
+  }
+
+  /* Sequence: number badge — brand accent with its paired foreground */
+  [id$="-sequencenumber"] {
+    fill: var(--stgm-primary) !important;
+  }
+  .sequenceNumber {
+    fill: var(--stgm-primary-foreground) !important;
+  }
+
+  /* Sequence: alt/opt/loop boxes and labels */
+  .labelBox {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .labelText,
+  .labelText > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .loopText,
+  .loopText > tspan,
+  .sectionTitle,
+  .sectionTitle > tspan {
+    fill: var(--stgm-primary) !important;
+  }
+  .loopLine {
+    stroke: var(--stgm-border) !important;
+  }
+
+  /* Sequence: notes and activations */
+  .note {
+    fill: var(--stgm-muted-subtle) !important;
+    stroke: var(--stgm-border) !important;
+  }
+  .noteText,
+  .noteText > tspan {
+    fill: var(--stgm-foreground) !important;
+  }
+  .activation0,
+  .activation1 {
+    fill: var(--stgm-muted) !important;
+    stroke: var(--stgm-border) !important;
+  }
+`;

package/src/internal/slug.ts

@@ -7,23 +7,27 @@
  *
  * Rules (applied in order):
  * 1. Convert to lowercase
- * 2. Replace spaces with hyphens
+ * 2. Replace spaces and dots (namespace separators) with hyphens
  * 3. Strip everything except `a-z`, `0-9`, and `-`
  * 4. Collapse consecutive hyphens into one
  * 5. Trim leading / trailing hyphens
  *
+ * Dots are treated as namespace separators (e.g. `platform.sara` → `platform-sara`),
+ * matching the backend generators, so namespace-scoped names stay readable.
+ *
  * @example
  * ```ts
- * generateSlug("My Cool Agent")  // "my-cool-agent"
- * generateSlug("Acme Corp!")     // "acme-corp"
- * generateSlug("  --hello-- ")   // "hello"
- * generateSlug("")               // ""
+ * generateSlug("My Cool Agent")             // "my-cool-agent"
+ * generateSlug("Acme Corp!")                // "acme-corp"
+ * generateSlug("  --hello-- ")              // "hello"
+ * generateSlug("platform.planton-arch")     // "platform-planton-arch"
+ * generateSlug("")                          // ""
  * ```
  */
 export function generateSlug(name: string): string {
   return name
     .toLowerCase()
-    .replace(/ /g, "-")
+    .replace(/[ .]/g, "-")
     .replace(/[^a-z0-9-]/g, "")
     .replace(/-{2,}/g, "-")
     .replace(/^-+|-+$/g, "");