@elabs-ai/components-editor 4.0.0

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

@@ -0,0 +1,257 @@
+import { cleanup, render, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MarkdownPreview } from "./markdown-preview";
+import type { CitationData } from "../markdown-academic/citations";
+
+afterEach(cleanup);
+
+/*
+ * The academic layer (footnotes / math / citations / TOC) — none of these nest a
+ * MarkdownPreview, so they share one file. They each render a single Streamdown.
+ */
+
+describe("MarkdownPreview — footnotes", () => {
+  const DOC = `A claim.[^1] Repeated.[^1] Another.[^big]\n\n[^1]: First note with [a link](https://x.com).\n[^big]: Second note.`;
+
+  it("renders refs whose anchors resolve to the definitions (no broken ids)", async () => {
+    const { container } = render(<MarkdownPreview footnotes>{DOC}</MarkdownPreview>);
+    await waitFor(() => expect(container.querySelector("[data-footnote-ref]")).toBeInTheDocument());
+
+    const firstRef = container.querySelector('a[id="fnref-1"]') as HTMLAnchorElement;
+    expect(firstRef).toBeInTheDocument();
+    expect(firstRef.getAttribute("href")).toBe("#fn-1");
+    // The ref target exists.
+    expect(container.querySelector('li[id="fn-1"]')).toBeInTheDocument();
+    // In-page anchors must NOT open a new tab.
+    expect(firstRef).not.toHaveAttribute("target");
+  });
+
+  it("gives a repeated reference a unique id but the same number", async () => {
+    const { container } = render(<MarkdownPreview footnotes>{DOC}</MarkdownPreview>);
+    await waitFor(() => expect(container.querySelector('a[id="fnref-1-2"]')).toBeInTheDocument());
+    const second = container.querySelector('a[id="fnref-1-2"]') as HTMLAnchorElement;
+    expect(second.getAttribute("href")).toBe("#fn-1");
+    expect(second.textContent).toBe("1");
+  });
+
+  it("renders a labelled footnote section with a working back-reference", async () => {
+    const { container } = render(<MarkdownPreview footnotes>{DOC}</MarkdownPreview>);
+    await waitFor(() =>
+      expect(screen.getByRole("region", { name: "Footnotes" })).toBeInTheDocument(),
+    );
+    const backref = container.querySelector('a[data-footnote-backref][href="#fnref-1"]');
+    expect(backref).toBeInTheDocument();
+    // The footnote is cited twice → one back-ref per mention (GFM behavior).
+    expect(
+      container.querySelector('a[data-footnote-backref][href="#fnref-1-2"]'),
+    ).toBeInTheDocument();
+    // The definition's link survived sanitization.
+    expect(screen.getByRole("link", { name: "a link" })).toHaveAttribute("href", "https://x.com/");
+  });
+
+  // Regression guard for #317: a link inside a running block of text must carry a
+  // non-color cue (a resting `underline`) or axe's `link-in-text-block` fires. The
+  // footnote marker is one of the sites that regressed to color-only (`no-underline`
+  // at rest, `hover:underline` only).
+  it("keeps a resting underline on the footnote marker (#317 — link-in-text-block)", async () => {
+    const { container } = render(<MarkdownPreview footnotes>{DOC}</MarkdownPreview>);
+    await waitFor(() => expect(container.querySelector("[data-footnote-ref]")).toBeInTheDocument());
+    const ref = container.querySelector("[data-footnote-ref]") as HTMLAnchorElement;
+    expect(ref.className).toMatch(/(?:^|\s)underline(?:\s|$)/);
+    expect(ref.className).not.toMatch(/(?:^|\s)no-underline(?:\s|$)/);
+  });
+});
+
+describe("MarkdownPreview — math (KaTeX)", () => {
+  it("renders inline math with MathML for assistive tech", async () => {
+    const { container } = render(
+      <MarkdownPreview math>{`Mass-energy: $E = mc^2$.`}</MarkdownPreview>,
+    );
+    await waitFor(() => expect(container.querySelector('[role="math"]')).toBeInTheDocument());
+    // KaTeX emits MathML (read by AT) + an aria-hidden visual layer.
+    const mathml = container.querySelector(".katex-mathml");
+    expect(mathml).toBeInTheDocument();
+    expect(mathml?.textContent).toContain("E = mc^2"); // the TeX annotation, for AT
+    expect(container.querySelector('.katex-html[aria-hidden="true"]')).toBeInTheDocument();
+    // A raw-TeX fallback name for AT that can't process MathML.
+    expect(container.querySelector('[role="math"]')).toHaveAttribute("aria-label", "E = mc^2");
+  });
+
+  it("renders block math ($$ on its own lines)", async () => {
+    const { container } = render(
+      <MarkdownPreview
+        math
+      >{`Result:\n\n$$\n\\int_0^1 x\\,dx = \\frac{1}{2}\n$$`}</MarkdownPreview>,
+    );
+    await waitFor(() => expect(container.querySelector('div[role="math"]')).toBeInTheDocument());
+    expect(container.querySelector('div[role="math"] .katex')).toBeInTheDocument();
+  });
+
+  it("does not parse $…$ when math is off", async () => {
+    const { container } = render(<MarkdownPreview>{`Price is $5 and $10.`}</MarkdownPreview>);
+    await waitFor(() => expect(screen.getByTestId("markdown-preview")).toBeInTheDocument());
+    expect(container.querySelector('[role="math"]')).toBeNull();
+  });
+
+  it("degrades a malformed expression to a contained fallback (no crash)", async () => {
+    render(<MarkdownPreview math>{`Bad: $\\frac{1}{$`}</MarkdownPreview>);
+    // Either a KaTeX error node or our code fallback — the page still renders.
+    await waitFor(() => expect(screen.getByTestId("markdown-preview")).toBeInTheDocument());
+  });
+});
+
+describe("MarkdownPreview — citations + bibliography", () => {
+  const DB: Record<string, CitationData> = {
+    smith2020: { author: "Smith", year: 2020, title: "On Things", url: "https://ex.com/s" },
+    jones2019: { author: "Jones", year: 2019, title: "More Things", doi: "10.1/x" },
+  };
+  const resolveCitation = (k: string) => DB[k] ?? null;
+
+  it("numbers inline cites and the bibliography consistently", async () => {
+    const { container } = render(
+      <MarkdownPreview resolveCitation={resolveCitation}>
+        {`See [@smith2020] and [@jones2019].\n\n::bibliography`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("region", { name: "References" })).toBeInTheDocument(),
+    );
+    // Inline cite 1 → smith, links to its bib entry id.
+    const cite = container.querySelector('a[href="#ref-smith2020"]') as HTMLAnchorElement;
+    expect(cite.textContent).toBe("1");
+    // The bare "1" carries a real accessible name (the title isn't announced by AT).
+    expect(cite.getAttribute("aria-label")).toMatch(/^Citation: /);
+    // Bibliography entry id matches the inline href.
+    expect(container.querySelector('li[id="ref-smith2020"]')).toBeInTheDocument();
+    expect(container.querySelector('li[id="ref-jones2019"]')).toBeInTheDocument();
+  });
+
+  it("renders a locator and multiple keys in one bracket", async () => {
+    const { container } = render(
+      <MarkdownPreview resolveCitation={resolveCitation}>
+        {`Per [@jones2019, p. 5; @smith2020].`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(container.querySelector('a[href="#ref-jones2019"]')).toBeInTheDocument(),
+    );
+    expect(container.querySelector('a[href="#ref-jones2019"]')?.textContent).toBe("1, p. 5");
+    expect(container.querySelector('a[href="#ref-smith2020"]')?.textContent).toBe("2");
+  });
+
+  it("renders the author-year style", async () => {
+    const { container } = render(
+      <MarkdownPreview resolveCitation={resolveCitation} citationStyle="author-year">
+        {`See [@smith2020].`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(container.querySelector('a[href="#ref-smith2020"]')).toBeInTheDocument(),
+    );
+    expect(container.querySelector('a[href="#ref-smith2020"]')?.textContent).toBe("Smith 2020");
+  });
+
+  it("keeps an unresolved citation as a graceful literal", async () => {
+    render(
+      <MarkdownPreview
+        resolveCitation={resolveCitation}
+      >{`Unknown [@ghost1999].`}</MarkdownPreview>,
+    );
+    await waitFor(() => expect(screen.getByText("[@ghost1999]")).toBeInTheDocument());
+  });
+
+  it("does not parse [@key] when no resolver is supplied", async () => {
+    render(<MarkdownPreview>{`Text [@smith2020] here.`}</MarkdownPreview>);
+    await waitFor(() => expect(screen.getByText(/\[@smith2020\]/)).toBeInTheDocument());
+  });
+
+  // Regression guard for #317: the inline citation ref and the bibliography's
+  // external DOI/URL link both live inside a running block of body text, so axe's
+  // `link-in-text-block` requires a non-color cue (a resting `underline`) — color
+  // alone (`text-primary` + `hover:underline`) is not enough.
+  it("keeps a resting underline on the inline cite and bibliography links (#317 — link-in-text-block)", async () => {
+    // (see also the `-text` rung guard below — #317 had two halves and the
+    // underline only closed the 1.4.1 one.)
+    const { container } = render(
+      <MarkdownPreview resolveCitation={resolveCitation}>
+        {`See [@smith2020] and [@jones2019].\n\n::bibliography`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("region", { name: "References" })).toBeInTheDocument(),
+    );
+    const inlineCite = container.querySelector('a[href="#ref-smith2020"]') as HTMLAnchorElement;
+    expect(inlineCite.className).toMatch(/(?:^|\s)underline(?:\s|$)/);
+    expect(inlineCite.className).not.toMatch(/(?:^|\s)no-underline(?:\s|$)/);
+
+    // jones2019 has a `doi` (no `url`) → renders the bibliography's external link.
+    const bibLink = container.querySelector(
+      'li[id="ref-jones2019"] a[href^="https://doi.org/"]',
+    ) as HTMLAnchorElement;
+    expect(bibLink).toBeInTheDocument();
+    expect(bibLink.className).toMatch(/(?:^|\s)underline(?:\s|$)/);
+    expect(bibLink.className).not.toMatch(/(?:^|\s)no-underline(?:\s|$)/);
+  });
+
+  // Regression guard for the OTHER half of #317 — `color-contrast`. Both links
+  // used the `--primary` FILL rung as body text, which measured 4.29-4.31:1 in
+  // light (sub-AA for normal text). #399 minted `--primary-text`, gated
+  // ≥4.5:1 on every content surface in every theme by
+  // `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 () => {
+    const { container } = render(
+      <MarkdownPreview resolveCitation={resolveCitation}>
+        {`See [@smith2020] and [@jones2019].\n\n::bibliography`}
+      </MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("region", { name: "References" })).toBeInTheDocument(),
+    );
+
+    const inlineCite = container.querySelector('a[href="#ref-smith2020"]') as HTMLAnchorElement;
+    expect(inlineCite.className.split(/\s+/)).toContain("text-primary-text");
+    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+/)).not.toContain("text-primary");
+  });
+});
+
+describe("MarkdownPreview — generated TOC", () => {
+  it("renders a nav whose links resolve to heading ids", async () => {
+    const { container } = render(
+      <MarkdownPreview toc>{`::toc\n\n# Intro\n\nbody\n\n## Details`}</MarkdownPreview>,
+    );
+    const nav = await screen.findByRole("navigation", { name: "Contents" });
+    const links = within(nav).getAllByRole("link");
+    expect(links.map((l) => l.getAttribute("href"))).toEqual(["#intro", "#details"]);
+    expect(container.querySelector('h1[id="intro"]')).toBeInTheDocument();
+    expect(container.querySelector('h2[id="details"]')).toBeInTheDocument();
+  });
+
+  it("does not stamp heading ids when toc is off", async () => {
+    const { container } = render(<MarkdownPreview>{`# Intro`}</MarkdownPreview>);
+    await waitFor(() => expect(screen.getByRole("heading", { name: "Intro" })).toBeInTheDocument());
+    expect(container.querySelector("h1")?.getAttribute("id")).toBeNull();
+  });
+
+  // Regression guard for #317: TOC entries share the same color-only-link pattern
+  // (kept consistent with citations/footnotes even though axe didn't flag this site
+  // in the original scan).
+  it("keeps a resting underline on TOC entries (#317 — link-in-text-block)", async () => {
+    render(<MarkdownPreview toc>{`::toc\n\n# Intro\n\nbody\n\n## Details`}</MarkdownPreview>);
+    const nav = await screen.findByRole("navigation", { name: "Contents" });
+    const links = within(nav).getAllByRole("link");
+    expect(links.length).toBeGreaterThan(0);
+    for (const link of links) {
+      expect(link.className).toMatch(/(?:^|\s)underline(?:\s|$)/);
+      expect(link.className).not.toMatch(/(?:^|\s)no-underline(?:\s|$)/);
+    }
+  });
+});

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

@@ -0,0 +1,71 @@
+/**
+ * Locks the user-reported gap: a ```calc fence used as an iteration cell template
+ * must RESOLVE into a CalcBlock (not show as raw text) — in BOTH the matrix/pivot
+ * and the stacked layouts. MarkdownPreview threads the calc `evaluate` into each
+ * cell's nested preview, so calc objects compute per cell. The builder dialog's
+ * live preview renders through this same path.
+ *
+ * Nested previews are jsdom-sensitive (Streamdown), so this lives in its own file
+ * with generous waits — per the markdown-preview-iteration suite convention.
+ */
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MarkdownPreview } from "./markdown-preview";
+import { evaluateEmbedded } from "../markdown-iteration/iteration-builder";
+import type { EvaluateCalc } from "../calc-block";
+
+afterEach(cleanup);
+
+// A minimal calc engine: each non-empty line resolves to 42. Proves a calc cell
+// RESOLVES into a CalcBlock inside an iteration — the library renders, the app
+// computes (no math engine bundled).
+const evaluateCalc: EvaluateCalc = (source) => ({
+  results: source
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((_, i) => ({
+      line: i + 1,
+      tokens: [],
+      value: { kind: "number" as const, raw: 42, display: "42" },
+    })),
+});
+
+const calcCount = (root: HTMLElement) => root.querySelectorAll('[data-testid="calc-block"]').length;
+
+describe("calc objects resolve inside iteration cells (every layout)", () => {
+  it("pivot/matrix: every cell's calc fence renders a CalcBlock", async () => {
+    const md = [
+      `:::pivot{rows="Q1, Q2" cols="N, S" layout="matrix"}`,
+      "```calc",
+      "items = {{row}} + {{col}}",
+      "total = items",
+      "```",
+      ":::",
+    ].join("\n");
+    const { container } = render(
+      <MarkdownPreview evaluateIteration={evaluateEmbedded} evaluate={evaluateCalc}>
+        {md}
+      </MarkdownPreview>,
+    );
+    // 2 rows × 2 cols = 4 resolved calc blocks.
+    await waitFor(() => expect(calcCount(container)).toBe(4), { timeout: 8000 });
+  });
+
+  it("iterate/stacked: every item's calc fence renders a CalcBlock", async () => {
+    const md = [
+      `:::iterate{as="item" values="A, B, C" layout="stacked"}`,
+      "```calc",
+      "x = {{item.name}}",
+      "```",
+      ":::",
+    ].join("\n");
+    const { container } = render(
+      <MarkdownPreview evaluateIteration={evaluateEmbedded} evaluate={evaluateCalc}>
+        {md}
+      </MarkdownPreview>,
+    );
+    // 3 values = 3 resolved calc blocks (stacked).
+    await waitFor(() => expect(calcCount(container)).toBe(3), { timeout: 8000 });
+  });
+});

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

@@ -0,0 +1,58 @@
+/**
+ * Locks the fence-collision fix: a nested CONTAINER directive (`:::card`) inside an
+ * `:::iterate` / `:::pivot` cell must render as the REAL component AND keep the
+ * content AFTER it, instead of being truncated. Before the fix the builder
+ * serialized a 3-colon `:::iterate`, so the nested `:::card`'s closing `:::` closed
+ * the OUTER block early — the card rendered as plain text and everything after it
+ * (incl. `{{tokens}}`) was dropped. `serializeIterationDirective` now escalates the
+ * outer fence past any nested fence (`outerDirectiveFence`).
+ *
+ * Nested previews are jsdom-sensitive (Streamdown), so this lives in its OWN file
+ * with generous waits — per the markdown-preview-iteration suite convention.
+ */
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MarkdownPreview } from "./markdown-preview";
+import {
+  evaluateEmbedded,
+  serializeIterationDirective,
+} from "../markdown-iteration/iteration-builder";
+
+afterEach(cleanup);
+
+// Cards compose the `bg-card` surface — count them to prove the directive rendered
+// as a real <Card>, not as truncated plain text.
+const cardCount = (root: HTMLElement) => root.querySelectorAll(".bg-card").length;
+
+describe("nested directive inside an iteration cell (fence-collision fix)", () => {
+  it("iterate: a :::card with trailing content renders a real Card AND the trailing text, per item", async () => {
+    const md = serializeIterationDirective({
+      kind: "iterate",
+      as: "item",
+      layout: "stacked",
+      values: ["Ada", "Bo"],
+      template: [
+        `:::card{title="{{item.name}}"}`,
+        `body for {{item.name}}`,
+        `:::`,
+        ``,
+        `tail {{item.name}}`,
+      ].join("\n"),
+    });
+    // The serializer escalates the outer fence past the nested `:::card` (3 colons).
+    expect(md.startsWith("::::iterate")).toBe(true);
+
+    const { container } = render(
+      <MarkdownPreview evaluateIteration={evaluateEmbedded}>{md}</MarkdownPreview>,
+    );
+
+    // One real Card per item (2) — was 0 before the fix (rendered as plain text).
+    await waitFor(() => expect(cardCount(container)).toBe(2), { timeout: 8000 });
+    expect(container.textContent).toContain("body for Ada");
+    expect(container.textContent).toContain("body for Bo");
+    // The content AFTER the nested card survives — it was dropped before the fix.
+    expect(container.textContent).toContain("tail Ada");
+    expect(container.textContent).toContain("tail Bo");
+  });
+});

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

@@ -0,0 +1,187 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+
+import { MarkdownPreview } from "./markdown-preview";
+import type { IterationData, IterationSpec } from "../markdown-iteration";
+
+const meta = {
+  title: "Editor/MarkdownPreview/Iteration",
+  component: MarkdownPreview,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "`:::iterate` / `:::pivot` repeat a per-cell markdown TEMPLATE (the directive body) " +
+          "over consumer-resolved data. `evaluateIteration(spec)` returns the data (the app owns " +
+          "the source); `interpolate(template, ctx)` fills each cell (a minimal `{{path}}` default " +
+          "is provided). Layouts: `stacked` (vertical), `grid` + `matrix` (a `@elabs-ai/components-ui` Table). " +
+          "Cells render through a nested, depth-capped `MarkdownPreview`.",
+      },
+    },
+  },
+} satisfies Meta<typeof MarkdownPreview>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/* A small in-app data source (would be a query / binding in a real app). */
+const TEAM = [
+  { name: "Ada Lovelace", role: "Engineering", commits: 128 },
+  { name: "Grace Hopper", role: "Compilers", commits: 211 },
+  { name: "Alan Turing", role: "Theory", commits: 97 },
+];
+
+const REVENUE: Record<string, Record<string, number>> = {
+  Q1: { EU: 120, US: 240 },
+  Q2: { EU: 150, US: 265 },
+};
+
+const evaluateIteration = (spec: IterationSpec): IterationData | null => {
+  if (spec.kind === "pivot") {
+    const rowHeaders = Object.keys(REVENUE);
+    const colHeaders = ["EU", "US"];
+    return {
+      rowHeaders,
+      colHeaders,
+      cells: rowHeaders.flatMap((r) =>
+        colHeaders.map((c) => ({ row: r, col: c, context: { amount: REVENUE[r]?.[c] ?? 0 } })),
+      ),
+    };
+  }
+  return {
+    columns: ["Member"],
+    cells: TEAM.map((m) => ({ context: m, key: m.name })),
+  };
+};
+
+export const Stacked: Story = {
+  args: {
+    evaluateIteration,
+    children: `# Team
+
+:::iterate{as="m" layout="stacked"}
+:::card{title="{{m.name}}"}
+**{{m.role}}** · {{m.commits}} commits
+:::
+:::`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByText("Ada Lovelace", {}, { timeout: 8000 })).toBeVisible();
+    await expect(canvas.getByText("Grace Hopper")).toBeVisible();
+  },
+};
+
+export const Grid: Story = {
+  args: {
+    evaluateIteration,
+    children: `# Team grid
+
+:::iterate{as="m" layout="grid"}
+**{{m.name}}** — {{m.role}}
+:::`,
+  },
+};
+
+export const Bento: Story = {
+  args: {
+    evaluateIteration,
+    children: `# Team bento
+
+:::iterate{as="m" layout="bento"}
+**{{m.name}}**
+
+{{m.role}}
+:::`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByText("Ada Lovelace", {}, { timeout: 8000 })).toBeVisible();
+    await expect(canvas.getByText("Alan Turing")).toBeVisible();
+  },
+};
+
+/**
+ * A nested `:::card` (with content AFTER it) inside an `:::iterate` cell. Authored
+ * with a FOUR-colon outer fence (`::::iterate … ::::`) so the inner `:::card`'s
+ * close can't terminate the outer block — the card renders as a real component and
+ * the trailing line survives. The guided builder emits this fence automatically.
+ */
+export const NestedCard: Story = {
+  name: "Nested :::card (+ trailing)",
+  args: {
+    evaluateIteration,
+    children: `::::iterate{as="m" layout="stacked"}
+:::card{title="{{m.name}}"}
+**{{m.role}}** · {{m.commits}} commits
+:::
+
+Reviewed {{m.name}}.
+::::`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByText("Ada Lovelace", {}, { timeout: 8000 })).toBeVisible();
+    // The trailing line after the nested card survives (the fence-collision fix).
+    await expect(canvas.getByText("Reviewed Ada Lovelace.")).toBeVisible();
+    await expect(canvas.getByText("Reviewed Grace Hopper.")).toBeVisible();
+  },
+};
+
+export const Pivot: Story = {
+  name: "Pivot (matrix)",
+  args: {
+    evaluateIteration,
+    children: `# Revenue by quarter × region
+
+:::pivot
+**\${{amount}}**M
+:::`,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      await canvas.findByRole("columnheader", { name: "EU" }, { timeout: 8000 }),
+    ).toBeVisible();
+    await expect(canvas.getByRole("rowheader", { name: "Q1" })).toBeVisible();
+  },
+};
+
+/**
+ * Nested iteration: an outer per-member repeat whose template contains an inner
+ * `:::iterate` over that member's data. The outer pass leaves the inner tokens
+ * literal; the inner pass (one level deeper, depth-capped) resolves them.
+ */
+export const Nested: Story = {
+  args: {
+    evaluateIteration: (spec: IterationSpec): IterationData | null => {
+      if (spec.source === "skills") {
+        const skills = (spec.attributes.of ?? "").split(",").filter(Boolean);
+        return { cells: skills.map((s) => ({ context: { skill: s.trim() }, key: s })) };
+      }
+      return {
+        cells: [
+          { context: { name: "Ada", of: "Math, Engines, Notes" }, key: "Ada" },
+          { context: { name: "Grace", of: "Compilers, Teaching" }, key: "Grace" },
+        ],
+      };
+    },
+    children: `:::iterate{as="person"}
+### {{person.name}}
+
+:::iterate{source="skills" of="{{person.of}}"}
+- {{skill}}
+:::
+:::`,
+  },
+};
+
+export const EmptyState: Story = {
+  name: "Empty (no data)",
+  args: {
+    evaluateIteration: () => ({ cells: [] }),
+    children: `:::iterate{as="m"}\n{{m.name}}\n:::`,
+  },
+};

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

@@ -0,0 +1,90 @@
+import { cleanup, render, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MarkdownPreview } from "./markdown-preview";
+import type { IterationData, IterationSpec } from "../markdown-iteration";
+
+afterEach(cleanup);
+
+/*
+ * `:::iterate` cells mount a NESTED MarkdownPreview (interpolated template →
+ * Streamdown). That nested render is jsdom-sensitive (it is perturbed by other
+ * Streamdown renders in the same file), so — per the suite convention — these
+ * live in their OWN file with the HEAVIEST (nested-iteration) case FIRST.
+ */
+
+const PEOPLE = [
+  { name: "Ada", role: "Engineering" },
+  { name: "Bo", role: "Design" },
+];
+
+function evaluateIteration(spec: IterationSpec): IterationData | null {
+  if (spec.kind === "pivot") {
+    return {
+      rowHeaders: ["Q1", "Q2"],
+      colHeaders: ["EU", "US"],
+      cells: ["Q1", "Q2"].flatMap((r) =>
+        ["EU", "US"].map((c) => ({ row: r, col: c, context: { cell: `${r}-${c}` } })),
+      ),
+    };
+  }
+  // The nested case: each person owns a sub-list of projects.
+  if (spec.source === "projects") {
+    const projects = (spec.attributes.of ?? "").split(",").filter(Boolean);
+    return { cells: projects.map((p) => ({ context: { project: p.trim() }, key: p })) };
+  }
+  return { cells: PEOPLE.map((p) => ({ context: p, key: p.name })) };
+}
+
+describe("MarkdownPreview — iteration (nested render, heaviest first)", () => {
+  it("renders a nested :::iterate inside an iterated cell (depth-capped, no loop)", async () => {
+    const md = `:::iterate{as="person"}
+### {{person.name}}
+
+:::iterate{source="projects" of="Alpha, Beta"}
+- {{project}}
+:::
+:::`;
+    render(<MarkdownPreview evaluateIteration={evaluateIteration}>{md}</MarkdownPreview>);
+    await waitFor(() => expect(screen.getByText("Ada")).toBeInTheDocument(), { timeout: 8000 });
+    // Inner iteration rendered the per-person project list — once per person (2),
+    // proving the outer pass left `{{project}}` literal for the inner pass.
+    expect(screen.getAllByText("Alpha")).toHaveLength(2);
+    expect(screen.getAllByText("Beta")).toHaveLength(2);
+  });
+});
+
+describe("MarkdownPreview — iteration layouts", () => {
+  it("stacked: repeats the interpolated template per item", async () => {
+    const md = `:::iterate{as="p" layout="stacked"}\n**{{p.name}}** — {{p.role}}\n:::`;
+    const { container } = render(
+      <MarkdownPreview evaluateIteration={evaluateIteration}>{md}</MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(container.querySelector('[data-iteration="iterate"]')).toBeInTheDocument(),
+    );
+    const group = container.querySelector('[data-iteration-layout="stacked"]')!;
+    expect(group.textContent).toContain("Ada");
+    expect(group.textContent).toContain("Engineering");
+  });
+
+  it("pivot: builds a matrix table with row + column headers", async () => {
+    const md = `:::pivot\nCell {{cell}}\n:::`;
+    const { container } = render(
+      <MarkdownPreview evaluateIteration={evaluateIteration}>{md}</MarkdownPreview>,
+    );
+    await waitFor(() =>
+      expect(container.querySelector('[data-iteration="pivot"]')).toBeInTheDocument(),
+    );
+    const table = container.querySelector("table")!;
+    expect(within(table).getByRole("columnheader", { name: "EU" })).toBeInTheDocument();
+    expect(within(table).getByRole("rowheader", { name: "Q1" })).toBeInTheDocument();
+    expect(table.textContent).toContain("Q1-US");
+  });
+
+  it("does not parse :::iterate when no evaluateIteration is supplied", async () => {
+    // Unknown container directive → the explicit unknown-block error, not a crash.
+    render(<MarkdownPreview>{`:::iterate{as="p"}\n{{p.name}}\n:::`}</MarkdownPreview>);
+    await waitFor(() => expect(screen.getByText(/Unknown block/i)).toBeInTheDocument());
+  });
+});