@multiplatform.one/markdown 7.7.0 → 7.7.1

package/src/icons/Icons.stories.tsx

@@ -0,0 +1,145 @@
+/**
+ * Markdown icons — the four hand-drawn SVGs the package ships and exports
+ * from its barrel: the copy affordance on MDXCodeBlock (Clipboard → Check),
+ * CheckCircle, and the heading anchor's Link.
+ *
+ * They are raw @tamagui/react-native-svg paths, not catalog icons, so they
+ * cannot consume `$colorN` token strings in a stroke attribute. useIconColor
+ * resolves the token to a concrete value first (SB-M-1206); pass a raw token
+ * and it still paints, which is what the ThemeTokens story shows.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, XStack, YStack } from "tamagui";
+import { CheckCircleIcon, CheckIcon, ClipboardIcon, LinkIcon } from "./index";
+
+const meta: Meta = {
+  title: "Markdown/Icons",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "ClipboardIcon, CheckIcon, CheckCircleIcon and LinkIcon. Size is a number in px (Clipboard/Check/CheckCircle default 16, Link defaults 12); color takes a concrete CSS color or a $theme token, which useIconColor resolves before it reaches the SVG stroke.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const icons = [
+  { name: "ClipboardIcon", Icon: ClipboardIcon },
+  { name: "CheckIcon", Icon: CheckIcon },
+  { name: "CheckCircleIcon", Icon: CheckCircleIcon },
+  { name: "LinkIcon", Icon: LinkIcon },
+] as const;
+
+export const Main: Story = {
+  args: { size: 24, color: "$color12" },
+  argTypes: {
+    size: { control: { type: "range", min: 8, max: 64, step: 2 } },
+    color: {
+      control: "select",
+      options: ["$color12", "$color10", "$blue10", "$green10", "$red10", "#ff8800"],
+    },
+  },
+  render: (args: any) => (
+    <XStack gap="$6" padding="$4" alignItems="flex-start">
+      {icons.map(({ name, Icon }) => (
+        <YStack key={name} gap="$2" alignItems="center">
+          <Icon size={args.size} color={args.color} />
+          <Paragraph size="$1" color="$color10">
+            {name}
+          </Paragraph>
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};
+
+/** The size ladder each icon is actually used at, plus the extremes. */
+export const SizeLadder: Story = {
+  render: () => (
+    <YStack gap="$4" padding="$4">
+      {icons.map(({ name, Icon }) => (
+        <XStack key={name} gap="$4" alignItems="center">
+          <Paragraph size="$2" width={140}>
+            {name}
+          </Paragraph>
+          {[8, 12, 16, 24, 48].map((size) => (
+            <Icon key={`${name}-${size}`} size={size} />
+          ))}
+        </XStack>
+      ))}
+    </YStack>
+  ),
+};
+
+/**
+ * SB-M-1206: a `$colorN` string cannot go straight into a stroke attribute.
+ * Every icon here is given a raw token, so a regression in useIconColor shows
+ * up as invisible strokes rather than a subtle mis-tint.
+ */
+export const ThemeTokens: Story = {
+  render: () => (
+    <YStack gap="$4" padding="$4">
+      {["$color12", "$color10", "$blue10", "$green10", "$red10"].map((token) => (
+        <XStack key={token} gap="$4" alignItems="center">
+          <Paragraph size="$2" width={100} color="$color10">
+            {token}
+          </Paragraph>
+          {icons.map(({ name, Icon }) => (
+            <Icon key={`${token}-${name}`} size={24} color={token} />
+          ))}
+        </XStack>
+      ))}
+    </YStack>
+  ),
+};
+
+/**
+ * In situ: Clipboard and Check are the two faces of the copy button on
+ * MDXCodeBlock, and Link is the anchor that appears beside a heading.
+ */
+export const InSitu: Story = {
+  render: () => (
+    <YStack gap="$4" padding="$4" maxWidth={520}>
+      <XStack gap="$3" alignItems="center">
+        <ClipboardIcon size={16} color="$color11" />
+        <Paragraph size="$3">Copy — idle</Paragraph>
+      </XStack>
+      <XStack gap="$3" alignItems="center">
+        <CheckIcon size={16} color="$green10" />
+        <Paragraph size="$3">Copy — copied</Paragraph>
+      </XStack>
+      <XStack gap="$3" alignItems="center">
+        <CheckCircleIcon size={16} color="$green10" />
+        <Paragraph size="$3">A completed item</Paragraph>
+      </XStack>
+      <XStack gap="$2" alignItems="center">
+        <Paragraph size="$6" fontWeight="700">
+          A heading
+        </Paragraph>
+        <LinkIcon size={12} color="$color10" />
+      </XStack>
+    </YStack>
+  ),
+};
+
+/** A custom strokeWidth is CheckIcon's only extra knob. */
+export const CheckStrokeWidth: Story = {
+  render: () => (
+    <XStack gap="$5" padding="$4" alignItems="center">
+      {[1, 1.5, 2.5, 4].map((strokeWidth) => (
+        <YStack key={strokeWidth} gap="$2" alignItems="center">
+          <CheckIcon size={32} strokeWidth={strokeWidth} />
+          <Paragraph size="$1" color="$color10">
+            {String(strokeWidth)}
+          </Paragraph>
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};

package/src/icons/icons.spec.tsx

@@ -0,0 +1,98 @@
+/**
+ * Markdown icons spec (MPO-195). The four SVGs are exported from the package
+ * barrel and had no colocated spec. What matters here is the thing that has
+ * already broken once: a `$colorN` string cannot reach a raw SVG stroke
+ * attribute, so useIconColor must resolve it to a concrete value first
+ * (SB-M-1206). An unresolved token paints nothing and no test caught it.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { CheckCircleIcon, CheckIcon, ClipboardIcon, LinkIcon } from "./index";
+
+const icons = [
+  { name: "ClipboardIcon", Icon: ClipboardIcon, defaultSize: "16" },
+  { name: "CheckIcon", Icon: CheckIcon, defaultSize: "16" },
+  { name: "CheckCircleIcon", Icon: CheckCircleIcon, defaultSize: "16" },
+  { name: "LinkIcon", Icon: LinkIcon, defaultSize: "12" },
+] as const;
+
+function strokes(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll("[stroke]")).map(
+    (el) => el.getAttribute("stroke") ?? "",
+  );
+}
+
+describe("markdown icons", () => {
+  for (const { name, Icon, defaultSize } of icons) {
+    it(`${name} renders an svg at its documented default size`, () => {
+      const { container } = renderWithProviders(<Icon />);
+      const svg = container.querySelector("svg");
+      expect(svg, name).toBeTruthy();
+      expect(svg!.getAttribute("width")).toBe(defaultSize);
+      expect(svg!.getAttribute("height")).toBe(defaultSize);
+      expect(svg!.getAttribute("viewBox")).toBe("0 0 24 24");
+    });
+
+    it(`${name} honours an explicit size`, () => {
+      const { container } = renderWithProviders(<Icon size={40} />);
+      const svg = container.querySelector("svg")!;
+      expect(svg.getAttribute("width")).toBe("40");
+      expect(svg.getAttribute("height")).toBe("40");
+    });
+
+    it(`${name} resolves a $token colour before it reaches the stroke (SB-M-1206)`, () => {
+      const { container } = renderWithProviders(<Icon color="$color10" />);
+      const painted = strokes(container);
+      expect(painted.length, name).toBeGreaterThan(0);
+      for (const stroke of painted) {
+        expect(stroke, name).not.toMatch(/^\$/);
+        expect(stroke, name).not.toBe("");
+      }
+    });
+
+    it(`${name} passes a concrete colour straight through`, () => {
+      const { container } = renderWithProviders(<Icon color="#ff8800" />);
+      for (const stroke of strokes(container)) expect(stroke).toBe("#ff8800");
+    });
+
+    it(`${name} paints a concrete stroke with no colour prop at all`, () => {
+      const { container } = renderWithProviders(<Icon />);
+      const painted = strokes(container);
+      expect(painted.length, name).toBeGreaterThan(0);
+      for (const stroke of painted) expect(stroke).not.toMatch(/^\$/);
+    });
+  }
+
+  it("an unknown $token degrades to a concrete colour rather than an empty stroke", () => {
+    const { container } = renderWithProviders(<CheckIcon color="$notARealToken" />);
+    for (const stroke of strokes(container)) {
+      expect(stroke).not.toMatch(/^\$/);
+      expect(stroke).not.toBe("");
+    }
+  });
+
+  it("CheckIcon takes a custom strokeWidth", () => {
+    const { container } = renderWithProviders(<CheckIcon strokeWidth={4} />);
+    expect(container.querySelector("path")!.getAttribute("stroke-width")).toBe("4");
+  });
+
+  it("CheckIcon defaults strokeWidth to 2.5, the other icons to 2", () => {
+    const check = renderWithProviders(<CheckIcon />);
+    expect(check.container.querySelector("path")!.getAttribute("stroke-width")).toBe("2.5");
+    const clipboard = renderWithProviders(<ClipboardIcon />);
+    expect(clipboard.container.querySelector("rect")!.getAttribute("stroke-width")).toBe("2");
+  });
+
+  it("ClipboardIcon and CheckCircleIcon draw their distinguishing shapes", () => {
+    const clipboard = renderWithProviders(<ClipboardIcon />);
+    expect(clipboard.container.querySelector("rect")).toBeTruthy();
+    const checkCircle = renderWithProviders(<CheckCircleIcon />);
+    expect(checkCircle.container.querySelector("circle")).toBeTruthy();
+  });
+
+  it("LinkIcon draws both halves of the broken chain", () => {
+    const { container } = renderWithProviders(<LinkIcon />);
+    expect(container.querySelectorAll("path")).toHaveLength(2);
+  });
+});

package/src/mermaid/MermaidBlock.spec.tsx

@@ -61,10 +61,41 @@ describe("MermaidBlock", () => {
   });
 });
 
+/**
+ * The native tier is its own module, not a branch of the web one (MPO-195).
+ * It never touches the engine, so it has no loading state, no error state and
+ * no diagram host — every input is source, shown as source.
+ */
 describe("MermaidBlock native fallback", () => {
   it("renders the source as a mermaid CodeBlock, never a diagram host", () => {
     const { container } = renderWithProviders(<NativeMermaidBlock>{FLOWCHART}</NativeMermaidBlock>);
     expect(container.querySelector('[data-mermaid-diagram="true"]')).toBeNull();
     expect(container.textContent).toContain("graph TD");
   });
+
+  it("never calls the engine or the mount helper", () => {
+    renderMermaidDiagram.mockClear();
+    mountDiagramSvg.mockClear();
+    renderWithProviders(<NativeMermaidBlock>{FLOWCHART}</NativeMermaidBlock>);
+    expect(renderMermaidDiagram).not.toHaveBeenCalled();
+    expect(mountDiagramSvg).not.toHaveBeenCalled();
+  });
+
+  it("shows invalid source verbatim with no error alert", () => {
+    const { container } = renderWithProviders(
+      <NativeMermaidBlock>{"graph TD\n A--"}</NativeMermaidBlock>,
+    );
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+    expect(container.textContent).toContain("graph TD");
+  });
+
+  it("renders a code block for empty source instead of nothing", () => {
+    const { container } = renderWithProviders(<NativeMermaidBlock>{""}</NativeMermaidBlock>);
+    expect(container.querySelector('[data-mermaid-diagram="true"]')).toBeNull();
+    expect(container.firstElementChild).toBeTruthy();
+  });
+
+  it("is a different component from the web block", () => {
+    expect(NativeMermaidBlock).not.toBe(MermaidBlock);
+  });
 });

package/src/mermaid/MermaidBlockNative.stories.tsx

@@ -0,0 +1,80 @@
+/**
+ * MermaidBlock.native — the NATIVE fallback, rendered here on web so the
+ * fallback itself is inspectable.
+ *
+ * Markdown/Mermaid's NativeFallbackNote story described this file in prose
+ * and then rendered the web block instead, so nobody had ever looked at what
+ * native actually paints. The native tier has no DOM, mermaid needs one, so
+ * the fallback renders the diagram SOURCE as a mermaid-tagged CodeBlock.
+ * Importing the `.native` module explicitly is what makes that visible —
+ * the web resolver would otherwise hand back MermaidBlock.tsx.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, YStack } from "tamagui";
+import { MermaidBlock as NativeMermaidBlock } from "./MermaidBlock.native";
+
+const FLOWCHART = `graph TD
+  A[Scan] --> B[Preview]
+  B --> C[Commit]`;
+
+const SEQUENCE = `sequenceDiagram
+  Client->>Server: parse
+  Server-->>Client: mdast`;
+
+const meta: Meta<typeof NativeMermaidBlock> = {
+  title: "Markdown/Mermaid Native",
+  component: NativeMermaidBlock,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The native tier of MermaidBlock. No DOM means no mermaid engine, so the diagram source renders as a mermaid CodeBlock instead of an SVG. Same props as the web block, no diagram host and no error state — invalid source is just source.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof NativeMermaidBlock>;
+
+export const Main: Story = {
+  args: { children: FLOWCHART },
+};
+
+/** A second grammar: the fallback never parses, so any source is fine. */
+export const Sequence: Story = {
+  args: { children: SEQUENCE },
+};
+
+/**
+ * The web block shows a parse error above the source for invalid input.
+ * Native has no parser, so the same input is shown verbatim with no alert.
+ */
+export const InvalidSourceIsJustSource: Story = {
+  args: { children: "graph TD\n A--" },
+};
+
+/** Side by side with what the fallback is standing in for. */
+export const AgainstTheWebPath: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={700} padding="$4">
+      <Paragraph size="$2" color="$color10">
+        This is MermaidBlock.native.tsx, the tier iOS and Android resolve. The web tier of the same
+        component renders a live SVG for this source; see Markdown/Mermaid.
+      </Paragraph>
+      <NativeMermaidBlock>{FLOWCHART}</NativeMermaidBlock>
+    </YStack>
+  ),
+};
+
+/** Empty and single-line sources still paint a code block, never nothing. */
+export const Edge: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={700} padding="$4">
+      <NativeMermaidBlock>{""}</NativeMermaidBlock>
+      <NativeMermaidBlock>{"graph LR; A-->B"}</NativeMermaidBlock>
+    </YStack>
+  ),
+};

package/src/mermaid/MountDiagramSvg.stories.tsx

@@ -0,0 +1,133 @@
+/**
+ * mountDiagramSvg — the sanitizing mount step between the mermaid engine and
+ * the page. MermaidBlock hands it an SVG string; it parses that string INERT
+ * (a detached document, so nothing executes during parsing), strips
+ * executable elements and event handlers, and imports only the <svg> into the
+ * live document.
+ *
+ * The helper is exported from the `@multiplatform.one/markdown/mermaid`
+ * subpath, so callers that render diagrams themselves reach it directly.
+ * These stories mount real strings into real containers, including a hostile
+ * one, and show what survived.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useEffect, useRef, useState } from "react";
+import { Paragraph, View, YStack } from "tamagui";
+import { mountDiagramSvg } from "./mountDiagramSvg";
+
+const meta: Meta = {
+  title: "Markdown/Mermaid Mount",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "mountDiagramSvg(container, svg) parses an SVG string inert, drops script/iframe/object/embed nodes, on* handlers and javascript: hrefs, then imports the <svg> into the container. Returns false and leaves the container untouched when the string holds no <svg> at all.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+/** Mounts `svg` on mount and reports what mountDiagramSvg returned. */
+function MountSpecimen({ label, svg }: { label: string; svg: string }) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const [result, setResult] = useState<{ mounted: boolean; html: string } | null>(null);
+
+  useEffect(() => {
+    if (!hostRef.current) return;
+    const mounted = mountDiagramSvg(hostRef.current, svg);
+    setResult({ mounted, html: hostRef.current.innerHTML });
+  }, [svg]);
+
+  return (
+    <YStack gap="$2">
+      <Paragraph fontWeight="600">{label}</Paragraph>
+      <View
+        borderWidth={1}
+        borderColor="$borderColor"
+        borderRadius="$4"
+        padding="$3"
+        backgroundColor="$color2"
+      >
+        <div ref={hostRef} data-mount-host="true" />
+      </View>
+      <Paragraph size="$1" color="$color10">
+        {result ? `returned ${result.mounted}` : "mounting…"}
+      </Paragraph>
+      <Paragraph size="$1" color="$color10" fontFamily="$mono">
+        {result ? result.html || "(container left empty)" : ""}
+      </Paragraph>
+    </YStack>
+  );
+}
+
+const plainDiagram = `<svg xmlns="http://www.w3.org/2000/svg" width="220" height="90" viewBox="0 0 220 90">
+  <rect x="4" y="4" width="92" height="42" rx="6" fill="none" stroke="#7c8ea0" stroke-width="2"/>
+  <text x="50" y="30" text-anchor="middle" fill="#7c8ea0" font-size="14">Parse</text>
+  <rect x="124" y="44" width="92" height="42" rx="6" fill="none" stroke="#7c8ea0" stroke-width="2"/>
+  <text x="170" y="70" text-anchor="middle" fill="#7c8ea0" font-size="14">Render</text>
+  <path d="M96 25 L170 25 L170 44" fill="none" stroke="#7c8ea0" stroke-width="2"/>
+</svg>`;
+
+const hostileDiagram = `<svg xmlns="http://www.w3.org/2000/svg" width="220" height="60" viewBox="0 0 220 60">
+  <script>window.__mermaidPwned = true;</script>
+  <rect x="4" y="4" width="212" height="52" rx="6" fill="none" stroke="#7c8ea0" stroke-width="2" onload="window.__mermaidPwned = true"/>
+  <a href="javascript:alert(1)"><text x="110" y="34" text-anchor="middle" fill="#7c8ea0" font-size="14">survives, defanged</text></a>
+  <iframe src="https://example.com"></iframe>
+</svg>`;
+
+const foreignObjectDiagram = `<svg xmlns="http://www.w3.org/2000/svg" width="220" height="60">
+  <foreignObject x="0" y="0" width="220" height="60">
+    <div>an html label, not well-formed XML
+  </foreignObject>
+</svg>`;
+
+export const Main: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4">
+      <MountSpecimen label="A well-formed diagram mounts as real SVG nodes" svg={plainDiagram} />
+    </YStack>
+  ),
+};
+
+/**
+ * Defense in depth on top of mermaid's own DOMPurify pass: the script, the
+ * iframe, the `onload` and the `javascript:` href are all gone, and the
+ * drawing that carried them still paints.
+ */
+export const HostileMarkupIsStripped: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4">
+      <MountSpecimen
+        label="script / iframe / onload / javascript: href removed, drawing kept"
+        svg={hostileDiagram}
+      />
+    </YStack>
+  ),
+};
+
+/**
+ * XML parse first, lenient HTML parse as the fallback — mermaid emits html
+ * labels inside foreignObject that are not well-formed XML.
+ */
+export const MalformedFallsBackToHtmlParsing: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4">
+      <MountSpecimen label="Unclosed html label inside foreignObject" svg={foreignObjectDiagram} />
+    </YStack>
+  ),
+};
+
+/** No <svg> anywhere: returns false, container untouched. */
+export const NoSvgReturnsFalse: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4" gap="$5">
+      <MountSpecimen label="Plain text" svg="not markup at all" />
+      <MountSpecimen label="Empty string" svg="" />
+    </YStack>
+  ),
+};

package/src/mermaid/RenderMermaidDiagram.stories.tsx

@@ -0,0 +1,158 @@
+/**
+ * renderMermaidDiagram — the canonical lazy mermaid engine (LC-16), driven
+ * directly rather than through MermaidBlock.
+ *
+ * MermaidBlock hides the whole contract behind one component, so nothing
+ * showed what the helper actually returns. It is exported from the
+ * dependency-free `@multiplatform.one/markdown/mermaid` subpath precisely so
+ * other surfaces can call it themselves — the rich-text editor's live
+ * code-block preview does. These stories render the result of that call: the
+ * `{ ok, svg }` / `{ ok, error }` union, the scheme-driven re-initialise, and
+ * the fontFamily option, with the SVG mounted through mountDiagramSvg so the
+ * engine's real output is on screen.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useEffect, useRef, useState } from "react";
+import { Paragraph, View, XStack, YStack } from "tamagui";
+import { mountDiagramSvg } from "./mountDiagramSvg";
+import { renderMermaidDiagram, type MermaidRenderResult } from "./renderMermaidDiagram";
+
+const meta: Meta = {
+  title: "Markdown/Mermaid Engine",
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "renderMermaidDiagram(code, { scheme, fontFamily }) dynamically imports the mermaid engine on first call, parses before rendering so a syntax error never leaves mermaid's error-bomb SVG behind, and resolves to { ok: true, svg } or { ok: false, error }. The engine is global, so it re-initialises only when scheme or fontFamily changes.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const FLOWCHART = `graph TD
+  A[Fence] --> B[renderMermaidDiagram]
+  B --> C[mountDiagramSvg]
+  C --> D[Painted]`;
+
+const INVALID = "graph TD\n A--";
+
+/** Calls the engine once and shows the union it resolved to. */
+function EngineSpecimen({
+  label,
+  code,
+  scheme,
+  fontFamily,
+}: {
+  label: string;
+  code: string;
+  scheme?: "light" | "dark";
+  fontFamily?: string;
+}) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const [result, setResult] = useState<MermaidRenderResult | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setResult(null);
+    renderMermaidDiagram(code, { scheme, fontFamily }).then((next) => {
+      if (cancelled) return;
+      setResult(next);
+      if (next.ok && hostRef.current) mountDiagramSvg(hostRef.current, next.svg);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [code, scheme, fontFamily]);
+
+  return (
+    <YStack gap="$2" flex={1}>
+      <Paragraph fontWeight="600">{label}</Paragraph>
+      <View
+        borderWidth={1}
+        borderColor="$borderColor"
+        borderRadius="$4"
+        padding="$3"
+        backgroundColor="$color2"
+        minHeight={80}
+      >
+        <div ref={hostRef} />
+      </View>
+      <Paragraph size="$1" color={result && !result.ok ? "$red11" : "$color10"} role="status">
+        {result === null
+          ? "awaiting the lazy engine…"
+          : result.ok
+            ? `ok: true · ${result.svg.length} chars of svg`
+            : `ok: false · ${result.error}`}
+      </Paragraph>
+    </YStack>
+  );
+}
+
+export const Main: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4">
+      <EngineSpecimen label="A flowchart through the engine" code={FLOWCHART} />
+    </YStack>
+  ),
+};
+
+/**
+ * Mermaid's config is global, so the helper re-initialises when the scheme
+ * changes. Both specimens render from the same source; only the theme differs.
+ */
+export const SchemeSwitch: Story = {
+  render: () => (
+    <XStack gap="$4" padding="$4" maxWidth={900}>
+      <EngineSpecimen label="scheme: light" code={FLOWCHART} scheme="light" />
+      <EngineSpecimen label="scheme: dark" code={FLOWCHART} scheme="dark" />
+    </XStack>
+  ),
+};
+
+/**
+ * Axiom 6: parse() runs before render(), so invalid source resolves to
+ * { ok: false, error } carrying mermaid's own message, and nothing is
+ * mounted. The box stays empty on purpose — the caller shows the error.
+ */
+export const InvalidSource: Story = {
+  render: () => (
+    <YStack maxWidth={700} padding="$4">
+      <EngineSpecimen label="Invalid source returns the parse message" code={INVALID} />
+    </YStack>
+  ),
+};
+
+/** fontFamily is forwarded into mermaid's theme config, and re-inits like scheme. */
+export const FontFamily: Story = {
+  render: () => (
+    <XStack gap="$4" padding="$4" maxWidth={900}>
+      <EngineSpecimen label="engine default font" code={FLOWCHART} />
+      <EngineSpecimen
+        label='fontFamily: "Courier New, monospace"'
+        code={FLOWCHART}
+        fontFamily="Courier New, monospace"
+      />
+    </XStack>
+  ),
+};
+
+/** Other grammars go through the same call; only the source changes. */
+export const OtherGrammars: Story = {
+  render: () => (
+    <YStack gap="$5" padding="$4" maxWidth={700}>
+      <EngineSpecimen
+        label="sequenceDiagram"
+        code={"sequenceDiagram\n  Client->>Engine: render\n  Engine-->>Client: svg"}
+      />
+      <EngineSpecimen
+        label="pie"
+        code={'pie title Coverage\n  "Storied" : 27\n  "Unstoried" : 24'}
+      />
+    </YStack>
+  ),
+};