` inside the paragraph: the text after the colon
+ disappeared and React threw a hydration error. Unknown text directives now go
+ back to literal text, in both `
` and the per-page Markdown output.
+
## [0.5.0] — 2026-08-30
### Added
diff --git a/README.md b/README.md
index b8f7d2d..73c7035 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,7 @@ To embed the engine in an existing Next.js app or build a custom theme from scra
| **AI ask-box** | BYO model (Anthropic, OpenAI, or Google) and API key. Answers are grounded in your actual content with cited sources. |
| **`/llms.txt` out of the box** | The [llms.txt](https://llmstxt.org) convention — a curated index and full-corpus export for LLMs and agentic tools. |
| **Full-text search** | [Pagefind](https://pagefind.app/) indexes your built HTML at deploy time. Fast, client-side, no server required. |
+| **Diagrams** | ` ```mermaid ` fences become zoomable, pannable diagrams themed to your site — with a fullscreen view, minimap, and SVG download. Mermaid only loads on pages that have one. |
| **Blog & changelog** | Drop files in `content/blog/` or `content/changelog/` — routes and nav links appear automatically. |
| **Own your deployment** | A normal Next.js app. Ship to Vercel, AWS Amplify, a container, or a subpath on an existing site. |
| **Genuinely open** | MIT licensed. No telemetry, no required account, no lock-in. |
diff --git a/examples/inkform-docs/content/docs/docs.json b/examples/inkform-docs/content/docs/docs.json
index a6999e7..96b0ec8 100644
--- a/examples/inkform-docs/content/docs/docs.json
+++ b/examples/inkform-docs/content/docs/docs.json
@@ -35,6 +35,7 @@
{ "title": "Add a Blog to an Existing Site", "slug": "guides/blog-in-existing-site", "file": "guides/blog-in-existing-site.mdx", "icon": "layers" },
{ "title": "Changelog", "slug": "guides/changelog", "file": "guides/changelog.mdx", "icon": "map" },
{ "title": "Widgets", "slug": "guides/widgets", "file": "guides/widgets.mdx", "icon": "blocks" },
+ { "title": "Diagrams", "slug": "guides/diagrams", "file": "guides/diagrams.mdx", "icon": "image" },
{ "title": "Comments, Reactions & Subscribe Forms", "slug": "guides/interactive", "file": "guides/interactive.mdx", "icon": "heart" },
{ "title": "Claude Code Skill", "slug": "guides/claude-code-skill", "file": "guides/claude-code-skill.mdx", "icon": "sparkles" }
]
diff --git a/examples/inkform-docs/content/docs/guides/diagrams.mdx b/examples/inkform-docs/content/docs/guides/diagrams.mdx
new file mode 100644
index 0000000..015a09e
--- /dev/null
+++ b/examples/inkform-docs/content/docs/guides/diagrams.mdx
@@ -0,0 +1,182 @@
+---
+title: Diagrams
+description: Mermaid diagrams in any MDX page — written as a fenced code block, rendered as a zoomable, pannable figure.
+---
+
+# Diagrams
+
+Write a fenced code block with the language set to `mermaid` and it renders as a diagram:
+
+````md
+```mermaid
+flowchart LR
+ Draft --> Review --> Publish
+```
+````
+
+```mermaid title="The smallest useful diagram"
+flowchart LR
+ Draft --> Review --> Publish
+```
+
+Hover a diagram (or tab to it) for the toolbar: zoom, copy the source, download an SVG, or open it fullscreen. In fullscreen there's a minimap for finding your way around large graphs.
+
+## Setup
+
+Diagrams are opt-in, because `mermaid` is a large install and plenty of docs sites never draw one. The scaffolded templates already have it on. For an existing site:
+
+```bash
+npm i mermaid
+```
+
+```ts
+// mdx-components.tsx
+import { mdxComponents } from '@inkform/framework/components';
+import { Mermaid } from '@inkform/framework/mermaid';
+
+export const siteMdxComponents = mdxComponents({ Mermaid });
+```
+
+Without that registration, `mermaid` fences still build — they render as a plain block of source, so nothing breaks while you decide.
+
+Readers only download mermaid on pages that have a diagram, and only when one is about to scroll into view. Pages without diagrams ship none of it.
+
+## Captions
+
+Put `title="…"` (or `caption="…"`) after the language. It shows under the diagram, names the fullscreen view and the downloaded file, and is what screen readers announce.
+
+````md
+```mermaid title="Request lifecycle"
+sequenceDiagram
+ ...
+```
+````
+
+```mermaid title="Request lifecycle"
+sequenceDiagram
+ participant B as Browser
+ participant E as Edge
+ participant A as App
+ participant D as Database
+ B->>E: GET /docs/quickstart
+ E->>E: Cache lookup
+ alt cache hit
+ E-->>B: 200 (cached HTML)
+ else cache miss
+ E->>A: Render page
+ A->>D: Load content
+ D-->>A: MDX source
+ A-->>E: HTML
+ E-->>B: 200
+ end
+```
+
+The JSX form works too, if you're building the source in an expression:
+
+```mdx
+ B`} />
+```
+
+## Moving around
+
+| Where | Zoom | Pan |
+| --- | --- | --- |
+| In the page | Ctrl /⌘ + scroll, trackpad pinch, double-click, or `+` / `-` | Drag once zoomed in, or arrow keys |
+| Fullscreen | Scroll, pinch, double-click | Drag, arrow keys, or click the minimap |
+| Touch | Pinch | One finger once zoomed in |
+
+A plain scroll over an inline diagram scrolls the page, not the diagram, so long posts don't trap the reader. `0` resets to fit.
+
+## Theming
+
+Diagrams take their colors from the site's `--fw-*` tokens, so they match whichever theme you run, and they redraw when the reader switches between light and dark. Styles written in the diagram itself (`style A fill:#111,color:#fff`) still win.
+
+## Big graphs
+
+Large diagrams are where the viewer earns its keep. Open this one fullscreen and use the minimap:
+
+```mermaid title="Content pipeline, end to end"
+flowchart TD
+ subgraph Authoring
+ A1[Write MDX] --> A2[Preview locally]
+ A2 --> A3{Looks right?}
+ A3 -- no --> A1
+ A3 -- yes --> A4[Open PR]
+ end
+ subgraph Review
+ A4 --> R1[CI: typecheck + tests]
+ R1 --> R2[CI: link check]
+ R2 --> R3[Preview deploy]
+ R3 --> R4{Approved?}
+ R4 -- changes --> A1
+ end
+ subgraph Build
+ R4 -- merge --> B1[Load content]
+ B1 --> B2[Parse frontmatter]
+ B2 --> B3[Compile MDX]
+ B3 --> B4[Highlight code]
+ B3 --> B5[Collect headings]
+ B5 --> B6[Build TOC]
+ B1 --> B7[Parse OpenAPI]
+ B7 --> B8[Operation pages]
+ B4 --> B9[Static HTML]
+ B6 --> B9
+ B8 --> B9
+ end
+ subgraph Ship
+ B9 --> S1[Pagefind index]
+ B9 --> S2[llms.txt]
+ B9 --> S3[Per-page .md]
+ S1 --> S4[Deploy]
+ S2 --> S4
+ S3 --> S4
+ S4 --> S5((Live))
+ end
+```
+
+## Other diagram types
+
+Anything Mermaid supports renders — state machines, ER diagrams, Gantt charts, mindmaps, and more.
+
+```mermaid title="Subscription states"
+stateDiagram-v2
+ [*] --> Trial
+ Trial --> Active: pays
+ Trial --> Expired: 14 days
+ Active --> PastDue: card fails
+ PastDue --> Active: retry succeeds
+ PastDue --> Canceled: 3 failures
+ Active --> Canceled: cancels
+ Canceled --> [*]
+```
+
+```mermaid title="What a docs site needs"
+mindmap
+ root((Docs site))
+ Content
+ Guides
+ API reference
+ Changelog
+ Discovery
+ Search
+ llms.txt
+ Per-page Markdown
+ Trust
+ Versioning
+ Examples that run
+```
+
+```mermaid title="Where the time goes"
+pie
+ "Writing" : 45
+ "Review" : 25
+ "Diagrams" : 20
+ "Deploy" : 10
+```
+
+## Writing diagrams with AI
+
+Mermaid is plain text, and it's the diagram format language models write most reliably — ask for "a Mermaid flowchart of …" and paste the result into a fence. The source stays in your MDX, so it diffs, reviews, and renders on GitHub too. The per-page Markdown (any URL + `.md`) and `llms.txt` output keep the fence as-is, so agents reading your docs see the diagram source rather than an image.
+
+If the source has a syntax error, the page shows mermaid's error message next to the source instead of an empty box.
diff --git a/examples/inkform-docs/content/docs/reference/framework-api.mdx b/examples/inkform-docs/content/docs/reference/framework-api.mdx
index 6b2c819..f593f67 100644
--- a/examples/inkform-docs/content/docs/reference/framework-api.mdx
+++ b/examples/inkform-docs/content/docs/reference/framework-api.mdx
@@ -66,7 +66,8 @@ Types: `OpenApiModel`, `ApiOperation`, `ApiParam`, `ApiBody`, `ApiResponse`,
| Export | Notes |
| --- | --- |
-| `Mdx({ source, components? })` | Async server component. Renders an MDX string with GFM, `:::callout` directives, Shiki-highlighted code, heading slugs, and all built-in blocks. Self-wraps output in `.fw-prose`. |
+| `Mdx({ source, components? })` | Async server component. Renders an MDX string with GFM, `:::callout` directives, Shiki-highlighted code, ` ```mermaid ` fences as ``, heading slugs, and all built-in blocks. Self-wraps output in `.fw-prose`. |
+| `remarkMermaid` | The remark plugin behind the fence → `` conversion, for hosts running their own MDX pipeline. |
## `@inkform/framework/docs-shell`
@@ -86,10 +87,20 @@ The built-in MDX block library — `Note`, `Tip`, `Info`, `Warning`, `Danger`,
`Check` (callout variants), `Card`, `CardGroup`, `Columns`, `Steps`/`Step`,
`Tabs`/`Tab`, `CodeGroup`, `Accordion`/`AccordionGroup`, `ParamField`,
`ResponseField`, `Expandable`, `Frame`, `Tooltip`, `Embed`, `Hero`,
-`AuthorBio`, `RelatedPosts`, `NewsletterCTA`, and `ApiLink`. Also exports
+`AuthorBio`, `RelatedPosts`, `NewsletterCTA`, `ApiLink`, and `Mermaid` (the static
+source-block fallback — see `./mermaid` below). Also exports
`mdxComponents(customWidgets)` — merges your `widgets/index.ts` registry with
every built-in block into the map ``).
+- **Mermaid diagrams** — ` ```mermaid ` fences render as zoomable, pannable
+ figures with a fullscreen view and minimap (`./mermaid`, opt-in: `npm i mermaid`).
- **A `docs.json` content model** — Mintlify-style tabs → groups → pages, with
anchors, navbar links, nested pages, and versioning hints. Pure, no IO.
- **OpenAPI → API Reference** — parse a JSON/YAML spec into a normalized model,
@@ -77,7 +79,8 @@ Content lives under `content/{docs,blog,changelog}` (override the root with
| `./content` | filesystem loaders: `loadDocsConfig`, `loadDocPage`, `loadBlogPosts`, `loadOpenApiSpec`, `extractHeadings` |
| `./nav` | `DocsConfig`, `docTabs`, `listDocPages`, `docNeighbours` |
| `./openapi` | `parseOpenApi`, `normalizeOperations`, `operationNavGroups`, `curlExample`, `sampleFromSchema` |
-| `./mdx` | `` |
+| `./mdx` | ``, `remarkMermaid` |
+| `./mermaid` | `` — interactive diagram viewer (needs the optional `mermaid` peer) |
| `./components` | the MDX component kit + `mdxComponents()` |
| `./docs-shell` | ``, ``, ``, ``, `` — also mounts the Pagefind highlight effect, see below |
| `./api-reference` | ``, `` |
diff --git a/packages/framework/package.json b/packages/framework/package.json
index 75160b0..9a51d37 100644
--- a/packages/framework/package.json
+++ b/packages/framework/package.json
@@ -1,6 +1,6 @@
{
"name": "@inkform/framework",
- "version": "0.5.0",
+ "version": "0.6.0",
"description": "Standalone Next.js + MDX framework for documentation, API reference (OpenAPI), blog, and changelog sites. The rendering engine behind the inkform docs themes — usable on its own.",
"license": "MIT",
"author": "Charan",
@@ -27,7 +27,8 @@
"api-reference",
"changelog",
"blog",
- "static-site"
+ "static-site",
+ "mermaid"
],
"main": "./src/index.ts",
"exports": {
@@ -45,6 +46,7 @@
"./ai": "./src/ai/index.ts",
"./llms-txt": "./src/llms-txt.ts",
"./mdx": "./src/mdx.tsx",
+ "./mermaid": "./src/mermaid/index.tsx",
"./markdown": "./src/markdown.ts",
"./components": "./src/components.tsx",
"./docs-shell": "./src/docs-shell.tsx",
@@ -76,13 +78,20 @@
"peerDependencies": {
"next": ">=16",
"react": ">=19",
- "react-dom": ">=19"
+ "react-dom": ">=19",
+ "mermaid": ">=11"
+ },
+ "peerDependenciesMeta": {
+ "mermaid": {
+ "optional": true
+ }
},
"dependencies": {
"@ai-sdk/anthropic": "^4.0.16",
"@ai-sdk/google": "^4.0.18",
"@ai-sdk/openai": "^4.0.16",
"@modelcontextprotocol/sdk": "^1.29.0",
+ "@panzoom/panzoom": "^4.6.2",
"@scalar/json-magic": "^0.12.19",
"@scalar/openapi-parser": "^0.28.10",
"@scalar/openapi-types": "^0.9.3",
@@ -102,6 +111,7 @@
},
"devDependencies": {
"@types/react": "^19",
+ "mermaid": "^12.0.0",
"tsx": "^4.23.1",
"typescript": "^5",
"vitest": "^3.2.4"
diff --git a/packages/framework/src/components.tsx b/packages/framework/src/components.tsx
index 785321e..94138ef 100644
--- a/packages/framework/src/components.tsx
+++ b/packages/framework/src/components.tsx
@@ -330,6 +330,32 @@ export function Frame({ caption, children }: FrameProps) {
);
}
+/* ---------------------------------------------------------------------------
+ * Mermaid (static fallback)
+ * -------------------------------------------------------------------------*/
+
+export interface MermaidSourceProps {
+ chart?: string;
+ caption?: string;
+}
+
+/**
+ * What ```mermaid fences render as by default: the diagram source as a plain
+ * block. The interactive renderer is opt-in so sites that never draw diagrams
+ * don't install mermaid — register it with
+ * `mdxComponents({ Mermaid })` from `@inkform/framework/mermaid`.
+ */
+export function MermaidSource({ chart = '', caption }: MermaidSourceProps) {
+ return (
+
+
+ {chart.trim()}
+
+ {caption && {caption} }
+
+ );
+}
+
/* ---------------------------------------------------------------------------
* Tooltip
* -------------------------------------------------------------------------*/
@@ -528,6 +554,7 @@ const BUILTINS: Record>> = {
// Misc
Expandable: Expandable as React.ComponentType>,
Frame: Frame as React.ComponentType>,
+ Mermaid: MermaidSource as React.ComponentType>,
Tooltip: Tooltip as unknown as React.ComponentType>,
// Media / embeds
Embed: Embed as React.ComponentType>,
diff --git a/packages/framework/src/glyphs.tsx b/packages/framework/src/glyphs.tsx
index b441438..cefa047 100644
--- a/packages/framework/src/glyphs.tsx
+++ b/packages/framework/src/glyphs.tsx
@@ -1,8 +1,8 @@
import * as React from 'react';
/**
- * Shared dependency-free stroke glyphs used by the AI-tool menu and page
- * actions (copy / check / external-link / text icons). Single-color
+ * Shared dependency-free stroke glyphs used by the AI-tool menu, page
+ * actions, and the Mermaid diagram toolbar. Single-color
* `currentColor` strokes, sized to match the menu's 15px icon slots.
*/
@@ -49,3 +49,63 @@ export function TextGlyph() {
);
}
+
+export function PlusGlyph() {
+ return (
+
+
+ );
+}
+
+export function MinusGlyph() {
+ return (
+
+
+ );
+}
+
+/** Four inward corners — "fit to view". */
+export function FitGlyph() {
+ return (
+
+
+ );
+}
+
+/** Four outward corners — "expand to fullscreen". */
+export function ExpandGlyph() {
+ return (
+
+
+ );
+}
+
+export function DownloadGlyph() {
+ return (
+
+
+ );
+}
+
+export function CloseGlyph() {
+ return (
+
+
+ );
+}
diff --git a/packages/framework/src/markdown.test.ts b/packages/framework/src/markdown.test.ts
index 069de26..79de8ee 100644
--- a/packages/framework/src/markdown.test.ts
+++ b/packages/framework/src/markdown.test.ts
@@ -7,6 +7,11 @@ const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..
const POKEAPI_CONTENT_ROOT = path.join(REPO_ROOT, 'examples', 'pokeapi-docs', 'content');
describe('processMarkdown', () => {
+ it('keeps inline colons that remark-directive would read as text directives', () => {
+ const md = processMarkdown('Google studied teams ([re:Work](https://example.com)).\n');
+ expect(md).toContain('[re:Work](https://example.com)');
+ });
+
it('strips imports/exports but keeps the body', () => {
const md = processMarkdown(
`import { Playground } from '@/widgets';
diff --git a/packages/framework/src/markdown.ts b/packages/framework/src/markdown.ts
index e2b3fa2..d4c5dd1 100644
--- a/packages/framework/src/markdown.ts
+++ b/packages/framework/src/markdown.ts
@@ -107,7 +107,8 @@ const mdxTextHandler = mdxJsxHandlers.mdxJsxTextElement!;
* toMarkdown handlers:
* - drop `mdxjsEsm` (imports/exports are machinery, not content)
* - `:::callout` directives → blockquote
- * - leaf/text directives → their children (or drop when empty)
+ * - leaf directives → their children (or drop when empty); inline `:name`
+ * text directives → back to the literal text
*/
function remarkPlainMarkdown() {
return (tree: Root) => {
@@ -128,8 +129,15 @@ function remarkPlainMarkdown() {
delete directive.attributes;
return;
}
- case 'leafDirective':
case 'textDirective': {
+ // Inline `:word` is almost always prose ("re:Work"), not a directive:
+ // put the colon and name back rather than dropping them.
+ const name = (n as { name?: string }).name ?? '';
+ const restored = [{ type: 'text', value: `:${name}` } as Node, ...((n.children ?? []) as Node[])];
+ (parent.children as Node[]).splice(index, 1, ...restored);
+ return;
+ }
+ case 'leafDirective': {
const children = (n.children ?? []) as Node[];
// Replace the directive node with its children (or drop it). Spliced
// in place so `visit`'s index stays valid for the remaining siblings.
diff --git a/packages/framework/src/mdx.tsx b/packages/framework/src/mdx.tsx
index a17978d..a4fd003 100644
--- a/packages/framework/src/mdx.tsx
+++ b/packages/framework/src/mdx.tsx
@@ -4,30 +4,11 @@ import remarkGfm from 'remark-gfm';
import remarkDirective from 'remark-directive';
import rehypePrettyCode from 'rehype-pretty-code';
import rehypeSlug from 'rehype-slug';
-import { visit } from 'unist-util-visit';
import { mdxComponents } from './components';
+import { remarkCallouts } from './remark-directives';
+import { remarkMermaid } from './remark-mermaid';
-const CALLOUT_NAMES = new Set(['info', 'warning', 'error', 'success', 'note', 'tip']);
-
-type DirectiveNode = {
- type: string;
- name?: string;
- data?: { hName?: string; hProperties?: Record };
-};
-
-/** Map `:::info … :::` (remark-directive) onto the component. */
-function remarkCallouts() {
- return (tree: Parameters[0]) => {
- visit(tree, (node) => {
- const n = node as DirectiveNode;
- if ((n.type === 'containerDirective' || n.type === 'leafDirective') && n.name && CALLOUT_NAMES.has(n.name)) {
- n.data ??= {};
- n.data.hName = 'Callout';
- n.data.hProperties = { type: n.name };
- }
- });
- };
-}
+export { remarkMermaid } from './remark-mermaid';
const prettyCodeOptions = {
theme: { light: 'github-light', dark: 'github-dark' },
@@ -42,7 +23,8 @@ type MdxProps = {
/**
* Renders an MDX string (the body the editor commits) to React. Supports GFM,
- * `:::callout` directives, fenced code with Shiki highlighting, rehype-slug for
+ * `:::callout` directives, fenced code with Shiki highlighting, ```mermaid
+ * fences as diagrams, rehype-slug for
* heading IDs (matching extractHeadings slugs → TOC anchor links), and all
* built-in components. Unknown components render a visible fallback (never crash
* the build).
@@ -60,7 +42,7 @@ export async function Mdx({ source, components }: MdxProps) {
// the v6 RCE guard (`blockDangerousJS: true`, the secure default) in place.
blockJS: false,
mdxOptions: {
- remarkPlugins: [remarkGfm, remarkDirective, remarkCallouts],
+ remarkPlugins: [remarkGfm, remarkDirective, remarkCallouts, remarkMermaid],
// eslint-disable-next-line @typescript-eslint/no-explicit-any
rehypePlugins: [rehypeSlug, [rehypePrettyCode as any, prettyCodeOptions]],
},
diff --git a/packages/framework/src/mermaid/index.tsx b/packages/framework/src/mermaid/index.tsx
new file mode 100644
index 0000000..62c2782
--- /dev/null
+++ b/packages/framework/src/mermaid/index.tsx
@@ -0,0 +1,339 @@
+'use client';
+
+/**
+ * @inkform/framework/mermaid — the interactive diagram renderer.
+ *
+ * Opt-in: needs the `mermaid` package installed alongside the framework
+ * (`npm i mermaid`), then register it so ```mermaid fences use it instead of
+ * the built-in static source block:
+ *
+ * import { mdxComponents } from '@inkform/framework/components';
+ * import { Mermaid } from '@inkform/framework/mermaid';
+ * export const siteMdxComponents = mdxComponents({ Mermaid });
+ *
+ * Readers only pay for mermaid on pages that have a diagram, and only once
+ * the diagram is about to scroll into view — it's a dynamic import.
+ */
+
+import * as React from 'react';
+import { copyText } from '../clipboard';
+import { CheckGlyph, CloseGlyph, CopyGlyph, DownloadGlyph, ExpandGlyph, FitGlyph, MinusGlyph, PlusGlyph } from '../glyphs';
+import { renderDiagram, themeConfig } from './render';
+import type { ViewerApi } from './viewer';
+
+// The pan/zoom viewer (and @panzoom/panzoom) is its own chunk too, so a site
+// that registers everywhere adds almost nothing to pages without
+// a diagram.
+const loadViewer = () => import('./viewer');
+const DiagramViewer = React.lazy(() => loadViewer().then((m) => ({ default: m.DiagramViewer })));
+
+export interface MermaidProps {
+ /** Mermaid source. ```mermaid fences are passed in as this prop. */
+ chart?: string;
+ /** Shown under the diagram and used as its accessible name. */
+ caption?: string;
+}
+
+/* ---------------------------------------------------------------------------
+ * Hooks
+ * -------------------------------------------------------------------------*/
+
+function subscribeTheme(onChange: () => void) {
+ const mo = new MutationObserver(onChange);
+ mo.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'data-theme'] });
+ return () => mo.disconnect();
+}
+
+const isDark = () => {
+ const html = document.documentElement;
+ return html.classList.contains('dark') || html.dataset.theme === 'dark';
+};
+
+/** Tracks the `html.dark` class (or `data-theme="dark"`) the theme toggle sets. */
+function useDarkMode() {
+ return React.useSyncExternalStore(subscribeTheme, isDark, () => false);
+}
+
+/** True once `ref` comes within ~one screen of the viewport. Never flips back. */
+function useNearViewport(ref: React.RefObject) {
+ const [near, setNear] = React.useState(false);
+ React.useEffect(() => {
+ const el = ref.current;
+ if (!el || near) return;
+ if (typeof IntersectionObserver === 'undefined') {
+ setNear(true);
+ return;
+ }
+ const io = new IntersectionObserver(
+ (entries) => {
+ if (entries.some((e) => e.isIntersecting)) {
+ setNear(true);
+ io.disconnect();
+ }
+ },
+ { rootMargin: '600px 0px' },
+ );
+ io.observe(el);
+ return () => io.disconnect();
+ }, [ref, near]);
+ return near;
+}
+
+/* ---------------------------------------------------------------------------
+ * Helpers
+ * -------------------------------------------------------------------------*/
+
+let renderCount = 0;
+
+function errorMessage(err: unknown): string {
+ const raw = err instanceof Error ? err.message : String(err);
+ return raw.replace(/^Error:\s*/, '').trim() || 'Unknown error';
+}
+
+function slugify(text: string | undefined): string {
+ const slug = (text ?? '')
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-|-$/g, '');
+ return slug || 'diagram';
+}
+
+/** Standalone SVG file: natural size, page background baked in. */
+function downloadSvg(svg: string, name: string, background: string) {
+ const doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
+ const root = doc.documentElement;
+ const vb = root.getAttribute('viewBox')?.split(/[\s,]+/).map(Number);
+ if (vb?.length === 4) {
+ root.setAttribute('width', String(vb[2]));
+ root.setAttribute('height', String(vb[3]));
+ }
+ root.removeAttribute('style');
+ root.setAttribute('style', `background-color: ${background}`);
+ const xml = `\n${new XMLSerializer().serializeToString(root)}`;
+ const url = URL.createObjectURL(new Blob([xml], { type: 'image/svg+xml' }));
+ const a = document.createElement('a');
+ a.href = url;
+ a.download = `${name}.svg`;
+ a.click();
+ setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/* ---------------------------------------------------------------------------
+ * Toolbar
+ * -------------------------------------------------------------------------*/
+
+interface ToolbarProps {
+ scale: number;
+ api: React.RefObject;
+ copied: boolean;
+ onCopy: () => void;
+ onDownload: () => void;
+ onExpand?: () => void;
+ onClose?: () => void;
+}
+
+function ToolButton({ label, onClick, children }: { label: string; onClick: () => void; children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+
+function Toolbar({ scale, api, copied, onCopy, onDownload, onExpand, onClose }: ToolbarProps) {
+ return (
+
+
api.current?.zoomOut()}>
+
+
api.current?.reset()}
+ >
+ {Math.round(scale * 100)}%
+
+
api.current?.zoomIn()}>
+
+ {onClose && (
+
api.current?.reset()}>
+
+ )}
+
+
+ {copied ?
+
+
+ {onExpand && (
+
+
+ )}
+ {onClose && (
+ <>
+
+
+
+
+ )}
+
(null);
+ const dialogRef = React.useRef(null);
+ const inlineApi = React.useRef(null);
+ const fullApi = React.useRef(null);
+ const near = useNearViewport(figureRef);
+ const dark = useDarkMode();
+ const [rendered, setRendered] = React.useState(null);
+ const [scale, setScale] = React.useState(1);
+ const [fullScale, setFullScale] = React.useState(1);
+ const [open, setOpen] = React.useState(false);
+ const [copied, setCopied] = React.useState(false);
+
+ React.useEffect(() => {
+ const el = figureRef.current;
+ if (!near || !source || !el) return;
+ let cancelled = false;
+ // A fresh id per render: mermaid removes any existing element with the id
+ // it's given, which would yank the diagram on screen during a re-theme.
+ const id = `fw-mermaid-${++renderCount}`;
+ void loadViewer();
+ renderDiagram(id, source, themeConfig(el, dark))
+ .then(({ svg }) => !cancelled && setRendered({ svg, id }))
+ .catch((err) => !cancelled && setRendered({ error: errorMessage(err) }));
+ return () => {
+ cancelled = true;
+ };
+ }, [near, source, dark]);
+
+ React.useEffect(() => {
+ const dialog = dialogRef.current;
+ if (!open || !dialog) return;
+ dialog.showModal();
+ const html = document.documentElement;
+ const prev = html.style.overflow;
+ html.style.overflow = 'hidden';
+ return () => {
+ html.style.overflow = prev;
+ };
+ }, [open]);
+
+ const onCopy = async () => {
+ if (await copyText(source)) {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1500);
+ }
+ };
+
+ const svg = rendered && 'svg' in rendered ? rendered : null;
+ const onDownload = () => {
+ if (!svg || !figureRef.current) return;
+ const bg = getComputedStyle(figureRef.current).getPropertyValue('--fw-bg').trim() || 'transparent';
+ downloadSvg(svg.svg, slugify(caption), bg);
+ };
+
+ // The fullscreen copy lives in the same document, so its ids (markers,
+ // scoped