@elabs-ai/components-editor 4.1.0 → 5.0.0

package/src/markdown-iteration/iteration-builder-dialog.tsx

@@ -28,6 +28,7 @@ import {
   TagInput,
   ToggleGroup,
   ToggleGroupItem,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { useEffect, useId, useMemo, useState, type ReactNode } from "react";
 
@@ -79,6 +80,7 @@ export function IterationBuilderDialog({
   evaluate,
   interpolate,
 }: IterationBuilderDialogProps) {
+  const { t } = useLocale();
   const kind = value?.kind ?? kindProp;
   const isPivot = kind === "pivot";
   const ids = useId();
@@ -130,19 +132,26 @@ export function IterationBuilderDialog({
     onOpenChange(false);
   };
 
-  const noun = isPivot ? "pivot" : "iteration";
+  const noun = isPivot
+    ? t("editor.iterationBuilder.pivotNoun")
+    : t("editor.iterationBuilder.iterationNoun");
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="flex max-h-[88vh] w-[min(56rem,94vw)] max-w-none flex-col">
         <DialogHeader>
           <DialogTitle>
-            {value ? "Edit" : "Insert"} {noun}
+            {t(
+              value ? "editor.iterationBuilder.editTitle" : "editor.iterationBuilder.insertTitle",
+              {
+                noun,
+              },
+            )}
           </DialogTitle>
           <DialogDescription>
             {isPivot
-              ? "Pick the row and column values, then write the per-cell template. The matrix below fills in live."
-              : "Add the list values, then write the per-row template. The result below fills in live."}
+              ? t("editor.iterationBuilder.pivotDescription")
+              : t("editor.iterationBuilder.iterationDescription")}
           </DialogDescription>
         </DialogHeader>
 
@@ -151,47 +160,53 @@ export function IterationBuilderDialog({
           <div className="flex min-w-0 flex-col gap-4">
             {!isPivot ? (
               <div className="flex flex-col gap-1.5">
-                <Label htmlFor={`${ids}-as`}>Bind name</Label>
+                <Label htmlFor={`${ids}-as`}>{t("editor.iterationBuilder.bindName")}</Label>
                 <Input
                   id={`${ids}-as`}
                   value={asName}
                   spellCheck={false}
                   autoComplete="off"
-                  placeholder="item"
+                  placeholder={t("editor.iterationBuilder.bindNamePlaceholder")}
                   onChange={(e) => setAsName(e.target.value)}
                 />
                 <p className="text-meta text-muted-foreground">
-                  Use <code>{`{{${asName.trim() || "item"}.name}}`}</code> in the template.
+                  {t("editor.iterationBuilder.bindNameHintPrefix")}
+                  <code>{`{{${asName.trim() || "item"}.name}}`}</code>
+                  {t("editor.iterationBuilder.bindNameHintSuffix")}
                 </p>
               </div>
             ) : null}
 
             <div className="flex flex-col gap-1.5">
-              <Label htmlFor={`${ids}-values`}>{isPivot ? "Row values" : "Values"}</Label>
+              <Label htmlFor={`${ids}-values`}>
+                {isPivot
+                  ? t("editor.iterationBuilder.rowValues")
+                  : t("editor.iterationBuilder.values")}
+              </Label>
               <TagInput
                 id={`${ids}-values`}
                 value={values}
                 onValueChange={setValues}
                 delimiter={[",", "\n"]}
-                placeholder="Type a value, press Enter…"
+                placeholder={t("editor.iterationBuilder.valuePlaceholder")}
               />
             </div>
 
             {isPivot ? (
               <div className="flex flex-col gap-1.5">
-                <Label htmlFor={`${ids}-cols`}>Column values</Label>
+                <Label htmlFor={`${ids}-cols`}>{t("editor.iterationBuilder.columnValues")}</Label>
                 <TagInput
                   id={`${ids}-cols`}
                   value={cols}
                   onValueChange={setCols}
                   delimiter={[",", "\n"]}
-                  placeholder="Type a value, press Enter…"
+                  placeholder={t("editor.iterationBuilder.valuePlaceholder")}
                 />
               </div>
             ) : null}
 
             <div className="flex flex-col gap-1.5">
-              <Label id={`${ids}-layout`}>Layout</Label>
+              <Label id={`${ids}-layout`}>{t("editor.iterationBuilder.layout")}</Label>
               <ToggleGroup
                 type="single"
                 variant="segmented"
@@ -216,23 +231,27 @@ export function IterationBuilderDialog({
           {/* Right column — the per-cell TEMPLATE + the live populated preview. */}
           <div className="flex min-h-0 min-w-0 flex-col gap-4">
             <div className="flex min-h-0 flex-col gap-1.5">
-              <Label>Per-{isPivot ? "cell" : "row"} template</Label>
+              <Label>
+                {isPivot
+                  ? t("editor.iterationBuilder.perCellTemplate")
+                  : t("editor.iterationBuilder.perRowTemplate")}
+              </Label>
               <div className="h-44 min-h-0 overflow-hidden rounded-md border border-border">
                 <MarkdownWorkspace
                   value={template}
                   onChange={setTemplate}
                   defaultMode="source"
                   className="h-full"
-                  aria-label="Per-cell template"
+                  aria-label={t("editor.iterationBuilder.perCellTemplate")}
                 />
               </div>
             </div>
 
             <div className="flex min-h-0 flex-col gap-1.5">
-              <Label>Live preview</Label>
+              <Label>{t("editor.iterationBuilder.livePreview")}</Label>
               <div
                 role="region"
-                aria-label="Live preview"
+                aria-label={t("editor.iterationBuilder.livePreview")}
                 className="min-h-0 flex-1 overflow-auto rounded-md border border-border bg-card p-3"
               >
                 <MarkdownPreview
@@ -249,9 +268,11 @@ export function IterationBuilderDialog({
 
         <DialogFooter>
           <Button variant="ghost" onClick={() => onOpenChange(false)}>
-            Cancel
+            {t("editor.iterationBuilder.cancel")}
+          </Button>
+          <Button onClick={save}>
+            {value ? t("editor.iterationBuilder.save") : t("editor.iterationBuilder.insert")}
           </Button>
-          <Button onClick={save}>{value ? "Save" : "Insert"}</Button>
         </DialogFooter>
       </DialogContent>
     </Dialog>

package/src/markdown-iteration/template-dialog.tsx

@@ -18,6 +18,7 @@ import {
   DialogFooter,
   DialogHeader,
   DialogTitle,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { useEffect, useState, type ReactNode } from "react";
 
@@ -47,6 +48,7 @@ export function IterationTemplateDialog({
   kind = "iterate",
   mode = "split",
 }: IterationTemplateDialogProps) {
+  const { t } = useLocale();
   const [draft, setDraft] = useState(template);
 
   // Re-seed the draft whenever the dialog (re)opens against a new template.
@@ -63,12 +65,28 @@ export function IterationTemplateDialog({
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="flex max-h-[85vh] w-[min(48rem,92vw)] max-w-none flex-col">
+      <DialogContent
+        className="flex max-h-[85vh] w-[min(48rem,92vw)] max-w-none flex-col"
+        // Radix autofocuses the first tabbable element — the toolbar's Bold button —
+        // and its Tooltip opens on focus, so the dialog opened with a stray tooltip.
+        // Focus the dialog itself instead; Tab still reaches the toolbar first.
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          (event.currentTarget as HTMLElement | null)?.focus();
+        }}
+      >
         <DialogHeader>
-          <DialogTitle>Edit {kind === "pivot" ? "pivot" : "iteration"} template</DialogTitle>
+          <DialogTitle>
+            {kind === "pivot"
+              ? t("editor.templateDialog.editPivotTitle")
+              : t("editor.templateDialog.editIterationTitle")}
+          </DialogTitle>
           <DialogDescription>
-            The per-{unit} template. Use <code>{"{{token}}"}</code> placeholders (e.g.{" "}
-            <code>{"{{item.name}}"}</code>) — each is filled per {unit} when the block renders.
+            {t("editor.templateDialog.descriptionPrefix", { unit })}
+            <code>{"{{token}}"}</code>
+            {t("editor.templateDialog.descriptionMiddle")}
+            <code>{"{{item.name}}"}</code>
+            {t("editor.templateDialog.descriptionSuffix", { unit })}
           </DialogDescription>
         </DialogHeader>
         <div className="min-h-0 flex-1">
@@ -77,14 +95,14 @@ export function IterationTemplateDialog({
             onChange={setDraft}
             defaultMode={mode}
             className="h-full"
-            aria-label="Iteration template editor"
+            aria-label={t("editor.templateDialog.editorLabel")}
           />
         </div>
         <DialogFooter>
           <Button variant="ghost" onClick={() => onOpenChange(false)}>
-            Cancel
+            {t("editor.templateDialog.cancel")}
           </Button>
-          <Button onClick={save}>Save template</Button>
+          <Button onClick={save}>{t("editor.templateDialog.saveTemplate")}</Button>
         </DialogFooter>
       </DialogContent>
     </Dialog>

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}
       >
@@ -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-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

@@ -29,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),
@@ -44,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(),
@@ -81,7 +96,11 @@ 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 {},
 }));
 

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