@elabs-ai/components-editor 4.0.0 → 4.2.0

package/src/markdown-outline/document-outline.stories.tsx

@@ -60,7 +60,7 @@ function ItemActionsDemo() {
             aria-label={`Pin section “${item.text}”`}
             aria-pressed={pinned === item.id}
             onClick={() => setPinned((p) => (p === item.id ? null : item.id))}
-            className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-ring"
           >
             <Pin className="size-3" aria-hidden="true" />
           </button>

package/src/markdown-outline/document-outline.tsx

@@ -6,6 +6,7 @@
  * `useMarkdownOutline`, drive `activeId` from your scroll observer, and handle
  * `onSelect` (e.g. scroll the matching `data-sourcepos` block into view).
  */
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { forwardRef, useMemo, type HTMLAttributes, type ReactNode } from "react";
 
@@ -31,11 +32,12 @@ export interface DocumentOutlineProps extends Omit<HTMLAttributes<HTMLElement>,
 
 export const DocumentOutline = forwardRef<HTMLElement, DocumentOutlineProps>(
   function DocumentOutline({ items, activeId, onSelect, itemActions, className, ...props }, ref) {
+    const { t } = useLocale();
     const minLevel = items.reduce<number>((min, it) => Math.min(min, it.level), 6);
     return (
       <nav
         ref={ref}
-        aria-label="Document outline"
+        aria-label={t("editor.documentOutline.label")}
         className={cn("text-body", className)}
         {...props}
       >
@@ -55,7 +57,7 @@ export const DocumentOutline = forwardRef<HTMLElement, DocumentOutlineProps>(
                   className={cn(
                     "-ms-px block w-full truncate border-s-2 py-1 pe-2 text-start text-caption",
                     "transition-colors duration-fast ease-standard motion-reduce:transition-none",
-                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+                    "focus-ring-inset",
                     item.id === activeId
                       ? "border-s-primary font-medium text-foreground"
                       : "border-s-transparent text-muted-foreground hover:border-s-border-strong hover:text-foreground",
@@ -75,7 +77,9 @@ export const DocumentOutline = forwardRef<HTMLElement, DocumentOutlineProps>(
           })}
         </ul>
         {items.length === 0 ? (
-          <p className="px-2 py-1 text-caption text-muted-foreground">No headings yet.</p>
+          <p className="px-2 py-1 text-caption text-muted-foreground">
+            {t("editor.documentOutline.empty")}
+          </p>
         ) : null}
       </nav>
     );

package/src/markdown-preview/markdown-preview-academic.test.tsx

@@ -201,7 +201,7 @@ describe("MarkdownPreview — citations + bibliography", () => {
   // `packages/tokens/src/themes-contrast.test.ts`; this row is the CLASS-NAME
   // lock that keeps these two call sites pointed at it. It is not a contrast
   // proof on its own — the token test is.
-  it("uses the on-surface text rung (text-primary-text), not the --primary fill (#317/#399 — color-contrast)", async () => {
+  it("uses the link ink (text-link → --primary-text), not the --primary fill (#317/#399 — color-contrast)", async () => {
     const { container } = render(
       <MarkdownPreview resolveCitation={resolveCitation}>
         {`See [@smith2020] and [@jones2019].\n\n::bibliography`}
@@ -212,13 +212,13 @@ describe("MarkdownPreview — citations + bibliography", () => {
     );
 
     const inlineCite = container.querySelector('a[href="#ref-smith2020"]') as HTMLAnchorElement;
-    expect(inlineCite.className.split(/\s+/)).toContain("text-primary-text");
+    expect(inlineCite.className.split(/\s+/)).toContain("text-link");
     expect(inlineCite.className.split(/\s+/)).not.toContain("text-primary");
 
     const bibLink = container.querySelector(
       'li[id="ref-jones2019"] a[href^="https://doi.org/"]',
     ) as HTMLAnchorElement;
-    expect(bibLink.className.split(/\s+/)).toContain("text-primary-text");
+    expect(bibLink.className.split(/\s+/)).toContain("text-link");
     expect(bibLink.className.split(/\s+/)).not.toContain("text-primary");
   });
 });

package/src/markdown-preview/markdown-preview-transclusion.test.tsx

@@ -11,7 +11,7 @@ afterEach(cleanup);
  * nested mount is perturbed by prior Streamdown renders (an env-only gremlin — the
  * feature renders correctly in the browser and in isolation). So transclusion gets
  * its OWN file with the resolved (nested-render) case asserted FIRST in a clean
- * module context. Six-theme pixel sweep still owed.
+ * module context. Cross-theme pixel sweep still owed.
  */
 describe("MarkdownPreview — transclusion (resolveTransclusion)", () => {
   it("embeds resolved markdown in a labelled figure", async () => {

package/src/markdown-preview/markdown-preview.stories.tsx

@@ -12,11 +12,33 @@ const meta = {
     docs: {
       description: {
         component:
+          "The EDITOR preview pane, which understands the brand `:::` directives. " +
+          "Pick a markdown renderer by where the markdown is going to be READ: a " +
+          "read-only document in a chat or a side rail → `AI/MarkdownView`; the preview " +
+          "pane of the markdown editor → `Editor/MarkdownPreview`; a file the app did " +
+          "not write → the markdown adapter behind `Viewer/FileViewer`; streaming into " +
+          "a message as the model writes it → `MessageResponse` on `AI/Message`. See " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs)." +
+          "\n\n" +
           "Renders markdown to REAL @brand components (Streamdown + a branded components " +
           "map): `#` → Heading, link → Link, table → Table, `---` → Separator, and the brand " +
           "directives `:::card` / `:::callout` / `::metric` / `:::timeline` → Card / Alert / " +
           "MetricBlock / Timeline. Uses the SAME shared remark pipeline as the Milkdown editor. " +
-          "Unknown directives render an explicit error block instead of disappearing.",
+          "Unknown directives render an explicit error block instead of disappearing.\n\n" +
+          "Its map is NOT a superset or a subset of `MarkdownView`'s — it is a different " +
+          "job. Every standard element here is wrapped to attach `data-sourcepos` (the " +
+          "seam the editor scroll-sync, the ghost-diff wash and the search wash all read), " +
+          "and a heading additionally carries a TOC slug id, a heading-action slot and " +
+          "hover-reveal anchor chrome. It has no `baseHeadingLevel`; it does have " +
+          "wikilinks, transclusion, `resolveUrl` and mermaid fences.\n\n" +
+          "All three map their element tree onto the same `Prose*` primitives owned " +
+          "by `@elabs-ai/components-ui` (`@elabs-ai/components-editor` re-exports them " +
+          "under short names). The element MAPS stay per-surface on purpose — " +
+          "`@elabs-ai/components-ai`, `@elabs-ai/components-editor` and " +
+          "`@elabs-ai/components-viewer` are leaves that may not import one another, and " +
+          "`streamdown` deliberately never moves down into `@elabs-ai/components-ui`, or " +
+          "every consumer of every foundation component would carry it. One prose source, " +
+          "several renderers.",
       },
     },
   },
@@ -88,7 +110,7 @@ export const HeadingActions: Story = {
         type="button"
         aria-label={`Pin section “${h.text}”`}
         aria-pressed={h.text === "Timeline"}
-        className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        className="rounded-sm p-0.5 text-muted-foreground hover:text-foreground focus-ring"
       >
         <Pin className="size-3.5" aria-hidden="true" />
       </button>

package/src/markdown-preview/markdown-preview.test.tsx

@@ -1,5 +1,5 @@
 import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
 
 import { MarkdownPreview } from "./markdown-preview";
 
@@ -249,16 +249,33 @@ describe("MarkdownPreview — code fences (highlight + chip + copy)", () => {
 });
 
 describe("MarkdownPreview — mermaid fences (#L1)", () => {
+  // #64 — under a full, parallel, uncached monorepo run this describe block's
+  // FIRST `import("mermaid")` (fired inside MermaidDiagram's effect,
+  // mermaid-diagram.tsx) is a large, cold module-graph evaluation
+  // (d3/dagre/cytoscape/khroma/katex) that can lose the race against Vitest's
+  // 5000ms default test timeout — not because the spec is wrong, but because it
+  // shares the event loop with every other worker on a CPU-starved host. Warm
+  // the module graph here, OUTSIDE any timed assertion, so the two specs below
+  // only ever pay a warm re-import. `mermaid` stays a dynamic import in
+  // mermaid-diagram.tsx (`pnpm heavy-deps:check` requires it) — this does not
+  // change that, it just pays the cold cost once, up front, off the clock.
+  beforeAll(async () => {
+    await import("mermaid");
+  });
+
+  // Explicit, generous timeouts as the second, independent half of the fix —
+  // belt-and-suspenders alongside the warm-up above, in case the warm-up itself
+  // lands inside a contended window. See #64.
   it("routes ```mermaid fences to the MermaidDiagram component", async () => {
     render(<MarkdownPreview>{"```mermaid\ngraph TD; A-->B\n```"}</MarkdownPreview>);
     await waitFor(() => expect(screen.getByTestId("mermaid-diagram")).toBeInTheDocument());
-  });
+  }, 15_000);
 
   it("keeps non-mermaid fences as plain pre blocks", async () => {
     const { container } = render(<MarkdownPreview>{"```ts\nconst x = 1;\n```"}</MarkdownPreview>);
     await waitFor(() => expect(container.querySelector("pre")).toBeInTheDocument());
     expect(container.querySelector('[data-testid="mermaid-diagram"]')).toBeNull();
-  });
+  }, 15_000);
 });
 
 describe("MarkdownPreview — colon false-positives (#workbench live finding)", () => {

package/src/markdown-toolbar/markdown-toolbar.stories.tsx

@@ -18,6 +18,9 @@ const meta = {
     docs: {
       description: {
         component:
+          "The markdown SOURCE-pane toolbar; the general-purpose roving control strip is " +
+          "`Layout/Toolbar` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "Formatting chrome for the markdown SOURCE pane, composed from @elabs-ai/components-ui. " +
           "The Insert menu is driven by the slash-command registry, so source mode " +
           "reaches the same brand blocks as the WYSIWYG `/` menu.",

package/src/markdown-toolbar/markdown-toolbar.tsx

@@ -19,6 +19,7 @@ import {
   TooltipContent,
   TooltipProvider,
   TooltipTrigger,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import {
@@ -65,18 +66,31 @@ export interface MarkdownToolbarProps extends HTMLAttributes<HTMLDivElement> {
 /** A command that actually carries a source-mode snippet. */
 type InsertableCommand = SlashCommand & { snippet: string };
 
-const DIRECTIVE_SNIPPETS: { label: string; snippet: string }[] = [
-  { label: "Card", snippet: `:::card{title="Title"}\nContent\n:::` },
-  { label: "Callout", snippet: `:::callout{type="info" title="Note"}\nMessage\n:::` },
-  { label: "Metric", snippet: `::metric{label="Label" value="0" description="detail"}` },
+// The `title=`/`label=` values below are example CONTENT dropped into the user's
+// document (the same seeds `brand-slash-commands.ts` uses), not UI chrome — left
+// as literal English placeholder text the author overwrites.
+const DIRECTIVE_SNIPPETS: { labelKey: string; snippet: string }[] = [
   {
-    label: "Timeline",
-    snippet: `:::timeline\n- (done) Step one\n- (active) Step two\n- (pending) Step three\n:::`,
+    labelKey: "editor.markdownToolbar.directiveCard",
+    snippet: `:::card{title="Title"}\nContent\n:::`, // i18n-exempt: example document content
+  },
+  {
+    labelKey: "editor.markdownToolbar.directiveCallout",
+    snippet: `:::callout{type="info" title="Note"}\nMessage\n:::`, // i18n-exempt: example document content
+  },
+  {
+    labelKey: "editor.markdownToolbar.directiveMetric",
+    snippet: `::metric{label="Label" value="0" description="detail"}`, // i18n-exempt: example document content
+  },
+  {
+    labelKey: "editor.markdownToolbar.directiveTimeline",
+    snippet: `:::timeline\n- (done) Step one\n- (active) Step two\n- (pending) Step three\n:::`, // i18n-exempt: example document content
   },
 ];
 
 export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
   function MarkdownToolbar({ editor, actions, insertCommands, className, ...props }, ref) {
+    const { t } = useLocale();
     const disabled = !editor;
     const run = (fn: (e: MonacoCodeEditor) => void) => () => {
       if (editor) fn(editor);
@@ -121,7 +135,7 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
         <div
           ref={ref}
           role="toolbar"
-          aria-label="Markdown formatting"
+          aria-label={t("editor.markdownToolbar.label")}
           className={cn(
             "flex h-10 shrink-0 items-center gap-0.5 border-b border-border bg-surface px-2",
             className,
@@ -129,21 +143,25 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
           {...props}
         >
           <IconButton
-            label="Bold"
+            label={t("editor.markdownToolbar.bold")}
             icon={<Bold className="size-4" />}
             onClick={run((e) => wrapSelection(e, "**"))}
           />
           <IconButton
-            label="Italic"
+            label={t("editor.markdownToolbar.italic")}
             icon={<Italic className="size-4" />}
             onClick={run((e) => wrapSelection(e, "*"))}
           />
           <IconButton
-            label="Inline code"
+            label={t("editor.markdownToolbar.inlineCode")}
             icon={<Code2 className="size-4" />}
             onClick={run((e) => wrapSelection(e, "`"))}
           />
-          <IconButton label="Link" icon={<Link2 className="size-4" />} onClick={run(insertLink)} />
+          <IconButton
+            label={t("editor.markdownToolbar.link")}
+            icon={<Link2 className="size-4" />}
+            onClick={run(insertLink)}
+          />
 
           <Separator orientation="vertical" className="mx-1 h-5" />
 
@@ -157,14 +175,14 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
                     size="sm"
                     disabled={disabled}
                     className="gap-1"
-                    aria-label="Heading level"
+                    aria-label={t("editor.markdownToolbar.headingLevel")}
                   >
                     <Heading className="size-4" />
                     <ChevronDown className="size-3" />
                   </Button>
                 </DropdownMenuTrigger>
               </TooltipTrigger>
-              <TooltipContent>Heading</TooltipContent>
+              <TooltipContent>{t("editor.markdownToolbar.heading")}</TooltipContent>
             </Tooltip>
             <DropdownMenuContent align="start">
               {([1, 2, 3] as const).map((level) => (
@@ -172,29 +190,29 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
                   key={level}
                   onSelect={run((e) => toggleLinePrefix(e, `${"#".repeat(level)} `))}
                 >
-                  Heading {level}
+                  {t("editor.markdownToolbar.headingLevelItem", { level })}
                 </DropdownMenuItem>
               ))}
             </DropdownMenuContent>
           </DropdownMenu>
 
           <IconButton
-            label="Quote"
+            label={t("editor.markdownToolbar.quote")}
             icon={<Quote className="size-4" />}
             onClick={run((e) => toggleLinePrefix(e, "> "))}
           />
           <IconButton
-            label="Bullet list"
+            label={t("editor.markdownToolbar.bulletList")}
             icon={<List className="size-4" />}
             onClick={run((e) => toggleLinePrefix(e, "- "))}
           />
           <IconButton
-            label="Numbered list"
+            label={t("editor.markdownToolbar.numberedList")}
             icon={<ListOrdered className="size-4" />}
             onClick={run((e) => toggleLinePrefix(e, "1. "))}
           />
           <IconButton
-            label="Divider"
+            label={t("editor.markdownToolbar.divider")}
             icon={<Minus className="size-4" />}
             onClick={run(insertHorizontalRule)}
           />
@@ -211,14 +229,14 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
                     size="sm"
                     disabled={disabled}
                     className="gap-1"
-                    aria-label="Insert block"
+                    aria-label={t("editor.markdownToolbar.insertBlock")}
                   >
                     <SquarePlus className="size-4" />
-                    <span className="text-xs">Insert</span>
+                    <span className="text-xs">{t("editor.markdownToolbar.insert")}</span>
                   </Button>
                 </DropdownMenuTrigger>
               </TooltipTrigger>
-              <TooltipContent>Insert brand block</TooltipContent>
+              <TooltipContent>{t("editor.markdownToolbar.insertBrandBlock")}</TooltipContent>
             </Tooltip>
             <DropdownMenuContent align="start">
               {insertGroups && insertGroups.length > 0
@@ -244,12 +262,12 @@ export const MarkdownToolbar = forwardRef<HTMLDivElement, MarkdownToolbarProps>(
                       ))}
                     </Fragment>
                   ))
-                : DIRECTIVE_SNIPPETS.map(({ label, snippet }) => (
+                : DIRECTIVE_SNIPPETS.map(({ labelKey, snippet }) => (
                     <DropdownMenuItem
-                      key={label}
+                      key={labelKey}
                       onSelect={run((e) => insertDirective(e, snippet))}
                     >
-                      {label}
+                      {t(labelKey)}
                     </DropdownMenuItem>
                   ))}
             </DropdownMenuContent>

package/src/markdown-workspace/markdown-workspace.test.tsx

@@ -3,6 +3,10 @@ import { createRef } from "react";
 import { afterEach, expect, test, vi } from "vitest";
 
 import type { SlashCommand } from "../markdown-editor/slash";
+import {
+  hasPendingMilkdownTeardown,
+  waitForPendingMilkdownTeardown,
+} from "../markdown-editor/milkdown-react/use-get-editor";
 
 // ---------------------------------------------------------------------------
 // Monaco mock — extended with revealLine / revealLineInCenter / getLineCount
@@ -25,8 +29,19 @@ vi.mock("monaco-editor", () => ({
       onDidBlurEditorText: vi.fn(() => ({ dispose: vi.fn() })),
       getValue: vi.fn(() => ""),
       setValue: vi.fn(),
+      // The controlled-value sync effect diffs against the MODEL's value (not
+      // the editor's) and applies the result via `executeEdits`. Every model
+      // this mock hands out shares the same value the editor's `getValue`
+      // reports (`""`), so a no-op sync never fires.
+      executeEdits: vi.fn(),
       getSelection: vi.fn(() => null),
-      getModel: vi.fn(() => ({ dispose: vi.fn(), getLineCount })),
+      getModel: vi.fn(() => ({
+        dispose: vi.fn(),
+        getLineCount,
+        getValue: vi.fn(() => ""),
+        getPositionAt: vi.fn((offset: number) => ({ lineNumber: 1, column: offset })),
+      })),
+      setModel: vi.fn(),
       updateOptions: vi.fn(),
       dispose: vi.fn(),
       getDomNode: vi.fn(() => null),
@@ -40,7 +55,11 @@ vi.mock("monaco-editor", () => ({
       addAction,
       focus: vi.fn(),
     })),
-    createModel: vi.fn(() => ({ dispose: vi.fn() })),
+    createModel: vi.fn(() => ({
+      dispose: vi.fn(),
+      getValue: vi.fn(() => ""),
+      getPositionAt: vi.fn((offset: number) => ({ lineNumber: 1, column: offset })),
+    })),
     setModelLanguage: vi.fn(),
     defineTheme: vi.fn(),
     setTheme: vi.fn(),
@@ -77,14 +96,25 @@ vi.mock("monaco-editor", () => ({
     KeyZ: 56,
   },
   Uri: { parse: (s: string) => ({ toString: () => s }) },
-  Range: class {},
+  Range: class {
+    static fromPositions(start: unknown, end: unknown) {
+      return { start, end };
+    }
+  },
   Selection: class {},
 }));
 
 import { MarkdownWorkspace, type MarkdownWorkspaceHandle } from "./markdown-workspace";
 
-afterEach(() => {
+// #65 — `cleanup()` unmounts synchronously but Milkdown's own `editor.destroy()`
+// is async (`@milkdown/ctx` schedules an internal cleanup timer inside it), so
+// returning here without waiting let that timer fire after Vitest recycled this
+// file's jsdom environment: `ReferenceError: removeEventListener is not defined`.
+// Await every pending Milkdown teardown (tracked in `use-get-editor.ts`) before
+// the next test's `vi.clearAllMocks()` / setup runs.
+afterEach(async () => {
   cleanup();
+  await waitForPendingMilkdownTeardown();
   vi.clearAllMocks();
 });
 
@@ -98,6 +128,25 @@ test("renders the mode switcher and the WYSIWYG editor", async () => {
   await waitFor(() => expect(screen.getByText("Hello")).toBeInTheDocument());
 });
 
+// #65 — regression lock for the awaitable Milkdown-destroy handle itself. Proves
+// (a) unmounting a Milkdown-backed surface registers a real pending teardown
+// (not a no-op — a reverted fix would leave nothing tracked and fail the first
+// assertion), and (b) awaiting the exposed handle actually drains it rather than
+// resolving early. Five mount/unmount cycles back to back so a leak in the
+// tracking Set itself (an entry that never gets removed) would also fail.
+test("#65 awaits Milkdown teardown on unmount via the exposed handle", async () => {
+  for (let i = 0; i < 5; i += 1) {
+    const { unmount } = render(<MarkdownWorkspace defaultMode="wysiwyg" defaultValue="# Hello" />);
+    await waitFor(() => expect(screen.getByText("Hello")).toBeInTheDocument());
+
+    unmount();
+    expect(hasPendingMilkdownTeardown()).toBe(true);
+
+    await waitForPendingMilkdownTeardown();
+    expect(hasPendingMilkdownTeardown()).toBe(false);
+  }
+});
+
 // #270 — focusWriting opt-out
 test("focusWriting={false} hides the Focus toggle in wysiwyg mode", () => {
   render(<MarkdownWorkspace defaultMode="wysiwyg" focusWriting={false} />);

package/src/markdown-workspace/markdown-workspace.tsx

@@ -22,6 +22,7 @@ import {
   TooltipContent,
   TooltipProvider,
   TooltipTrigger,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { Columns2, Eye, Focus, SquareCode } from "lucide-react";
@@ -219,6 +220,7 @@ export const MarkdownWorkspace = forwardRef<MarkdownWorkspaceHandle, MarkdownWor
     },
     ref,
   ) {
+    const { t } = useLocale();
     // The source/split Insert menu defaults to the SAME commands as the WYSIWYG
     // slash menu, so both surfaces insert the same blocks (A4).
     const slashCommandList =
@@ -704,13 +706,14 @@ export const MarkdownWorkspace = forwardRef<MarkdownWorkspaceHandle, MarkdownWor
                       size="sm"
                       pressed={focusWritingOn}
                       onPressedChange={setFocusWritingOn}
-                      aria-label="Focus writing"
+                      aria-label={t("editor.markdownWorkspace.focusWriting")}
                       className="h-6 gap-1.5 px-2 text-caption"
                     >
-                      <Focus className="size-3.5" aria-hidden="true" /> Focus
+                      <Focus className="size-3.5" aria-hidden="true" />{" "}
+                      {t("editor.markdownWorkspace.focus")}
                     </Toggle>
                   </TooltipTrigger>
-                  <TooltipContent>Typewriter scrolling · inactive paragraphs dim</TooltipContent>
+                  <TooltipContent>{t("editor.markdownWorkspace.focusWritingHint")}</TooltipContent>
                 </Tooltip>
               </TooltipProvider>
             ) : null}

package/src/mermaid-diagram/mermaid-diagram-fixes.test.tsx

@@ -0,0 +1,130 @@
+/**
+ * Locks the three review fixes to MermaidDiagram:
+ *
+ * 1. Concurrent renders are serialized through `withMermaidLock` so two
+ *    instances (or two overlapping theme changes) never interleave
+ *    `mermaid.initialize()` (one shared module-level config) with a
+ *    different instance's `mermaid.render()`.
+ * 2. The render effect debounces on `chart`, so a rapidly-changing
+ *    (streaming) source only triggers one real `mermaid.render()` call for
+ *    the final value, not one per intermediate change.
+ * 3. `downloadSvg()` defers `URL.revokeObjectURL` past the click (Safari).
+ *
+ * Isolated from `mermaid-diagram.test.tsx` because these tests need fake
+ * timers and finer control over when each `mermaid.render()` call resolves,
+ * which would otherwise fight that file's real-timer `waitFor` calls.
+ */
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const callOrder: string[] = [];
+let resolveFirstRender: (() => void) | undefined;
+
+const initializeMock = vi.fn(() => {
+  callOrder.push("initialize");
+});
+
+let renderStarts = 0;
+let holdFirstRender = false;
+const renderMock = vi.fn(async (id: string, chart: string) => {
+  renderStarts += 1;
+  const isFirst = holdFirstRender && renderStarts === 1;
+  callOrder.push("render-start");
+  if (isFirst) {
+    await new Promise<void>((resolve) => {
+      resolveFirstRender = resolve;
+    });
+  }
+  callOrder.push("render-end");
+  return { svg: `<svg data-id="${id}" data-chart="${chart}"></svg>` };
+});
+
+vi.mock("mermaid", () => ({
+  default: { initialize: initializeMock, render: renderMock },
+}));
+
+import { MermaidDiagram } from "./mermaid-diagram";
+
+beforeEach(() => {
+  callOrder.length = 0;
+  renderStarts = 0;
+  holdFirstRender = false;
+  resolveFirstRender = undefined;
+  renderMock.mockClear();
+  initializeMock.mockClear();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe("MermaidDiagram — serializes concurrent renders across instances (review finding)", () => {
+  it("never starts a second instance's initialize before the first instance's render settles", async () => {
+    holdFirstRender = true;
+    vi.useFakeTimers();
+    render(<MermaidDiagram chart={"graph TD; A-->B"} />);
+    render(<MermaidDiagram chart={"graph TD; C-->D"} />);
+
+    // Fire both debounce timers; only the FIRST queued render should have
+    // started — the second instance's `initialize` must wait for it.
+    await act(() => vi.advanceTimersByTimeAsync(300));
+    expect(callOrder).toEqual(["initialize", "render-start"]);
+
+    // Let the first render settle; the queue should now release the second.
+    resolveFirstRender?.();
+    await act(() => vi.advanceTimersByTimeAsync(0));
+    await act(() => vi.advanceTimersByTimeAsync(0));
+
+    expect(callOrder).toEqual([
+      "initialize",
+      "render-start",
+      "render-end",
+      "initialize",
+      "render-start",
+      "render-end",
+    ]);
+  });
+});
+
+describe("MermaidDiagram — debounces re-rendering while the source is changing (review finding)", () => {
+  it("only renders once, for the final chart value, across rapid successive changes", async () => {
+    vi.useFakeTimers();
+    const { rerender } = render(<MermaidDiagram chart={"graph TD; A-->B"} />);
+    rerender(<MermaidDiagram chart={"graph TD; A-->C"} />);
+    rerender(<MermaidDiagram chart={"graph TD; A-->D"} />);
+
+    // Just under the debounce window: nothing has rendered yet.
+    await act(() => vi.advanceTimersByTimeAsync(299));
+    expect(renderMock).not.toHaveBeenCalled();
+
+    // Past the window: exactly one render, for the last value only.
+    await act(() => vi.advanceTimersByTimeAsync(50));
+    expect(renderMock).toHaveBeenCalledTimes(1);
+    expect(renderMock).toHaveBeenCalledWith(expect.any(String), "graph TD; A-->D");
+  });
+});
+
+describe("MermaidDiagram — defers revoking the download object URL (review finding)", () => {
+  it("does not call URL.revokeObjectURL synchronously after the download click", async () => {
+    render(<MermaidDiagram chart={"graph TD; A-->B"} label="Flow" />);
+    await waitFor(() =>
+      expect(screen.getByRole("button", { name: "Download diagram as SVG" })).toBeInTheDocument(),
+    );
+
+    vi.useFakeTimers();
+    global.URL.createObjectURL = vi.fn(() => "blob:mock");
+    const revokeSpy = vi.fn();
+    global.URL.revokeObjectURL = revokeSpy;
+    const clickSpy = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+
+    fireEvent.click(screen.getByRole("button", { name: "Download diagram as SVG" }));
+
+    // Not revoked synchronously — the click handler must have returned first.
+    expect(revokeSpy).not.toHaveBeenCalled();
+    act(() => vi.runAllTimers());
+    expect(revokeSpy).toHaveBeenCalledWith("blob:mock");
+
+    clickSpy.mockRestore();
+  });
+});

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

@@ -7,9 +7,10 @@ const renderMock = vi.fn(async (_id: string, chart: string) => {
     svg: `<svg data-chart="ok"><g class="node"><rect></rect><text>Microsoft Graph API</text></g><g class="node"><rect></rect><text>Worker</text></g></svg>`,
   };
 });
+const initializeMock = vi.fn();
 
 vi.mock("mermaid", () => ({
-  default: { initialize: vi.fn(), render: renderMock },
+  default: { initialize: initializeMock, render: renderMock },
 }));
 
 import { MermaidDiagram } from "./mermaid-diagram";