feat(mermaid): add @tldraw/mermaid package for diagram-to-shape conversion (tldraw#8194)

In order to let users paste Mermaid diagram syntax and have it converted
into native tldraw shapes, this PR introduces the `@tldraw/mermaid`
package and integrates it into the dotcom app.
Closes tldraw#4353

### How it works

The system has three layers: **detection**, **parsing + layout
extraction**, and **blueprint rendering**.

**Detection (dotcom integration).** When text is pasted on dotcom,
`SneakyMermaidHandler` registers an external text content handler on the
editor. Before pulling in the heavy mermaid library, it runs a
lightweight regex-based check (`simpleMermaidStringTest`) that strips
YAML frontmatter, `%%{...}%%` directives, and `%%` comments, then tests
whether the cleaned text starts with a known diagram keyword. This keeps
the mermaid library out of the main bundle — it's only `import()`-ed
when a paste actually looks like a diagram. If the text doesn't match,
it falls through to `defaultHandleExternalTextContent`. If the diagram
type is unsupported (e.g. pie charts), the handler falls back to SVG
import via `putExternalContent({ type: 'svg-text' })` and shows a toast.

**Parsing + layout extraction (`createMermaidDiagram`).** This is the
main entry point. It initializes mermaid with inflated font sizes to
compensate for tldraw's hand-drawn font being wider, parses and
validates the syntax, renders to an offscreen DOM element for layout
extraction via `getBBox()`, then extracts the diagram's semantic data
(vertices, edges, actors, states, etc.) and dispatches to the
appropriate diagram-specific converter.

**Diagram-specific converters.** Each converter combines the semantic
data (from mermaid's DB) with layout data (from the rendered SVG) to
produce a `DiagramMermaidBlueprint`:

- *Flowcharts* — Node positions/dimensions from SVG `.node` elements,
cluster bounds from `.cluster` elements, edge waypoints from
`path[data-points]` attributes. Maps mermaid shape types to tldraw geo
types. Builds subgraph hierarchy as frames with `parentId`. Computes
arrow bend from waypoint geometry. Parses `classDef` CSS colors and maps
to nearest tldraw palette color via Euclidean RGB distance.
- *Sequence diagrams* — Actor layouts from SVG rect elements with fixed
spacing. Creates top/bottom actor shapes, vertical lifelines, signal
arrows with precise bindings, note shapes, and fragment frames for
loop/alt/opt/par/critical blocks.
- *State diagrams* — Recursively flattens the state hierarchy. Creates
frames for compound states, handles special types (start, end,
fork/join, choice). Reuses the same SVG node/edge parsing strategy as
flowcharts.
**Blueprint rendering (`renderBlueprint`).** The blueprint is a
diagram-type-agnostic intermediate representation with `nodes`, `edges`,
`lines`, and `groups`. The renderer centers the diagram at the paste
point, creates shapes in parent-first order with proper coordinate
transforms, creates arrows with bindings (precise anchored, self-loop,
and standard center-to-center), groups shapes, and applies a final
position correction pass.

### Change type

- [x] `feature`
- [x] `api`

### Test plan

1. Paste a flowchart mermaid diagram (e.g. `graph TD; A-->B; B-->C;`)
into tldraw.com — shapes should appear
2. Paste a sequence diagram — shapes with lifelines and arrows should
appear
3. Paste a state diagram — shapes with transitions should appear
4. Paste an unsupported diagram type (e.g. pie chart) — should fall back
to SVG with a warning toast
5. Paste normal text — should behave as before (no mermaid handling)

- [x] Unit tests

### API changes

- Added `createMermaidDiagram(editor, text, options?)` — main entry
point to parse and render a Mermaid diagram
- Added `renderBlueprint(editor, blueprint, opts?)` — renders a
`DiagramMermaidBlueprint` into tldraw shapes
- Added `MermaidDiagramError` — error class for parse/unsupported
diagram errors
- Added types: `DiagramMermaidBlueprint`, `MermaidBlueprintGeoNode`,
`MermaidBlueprintEdge`, `MermaidBlueprintLineNode`,
`BlueprintRenderingOptions`, `MermaidDiagramOptions`

### Release notes

- Add Mermaid diagram support: paste Mermaid syntax to create native
tldraw shapes (flowcharts, sequence diagrams, state diagrams)

### Code changes

| Section         | LOC change    |
| --------------- | ------------- |
| Core code       | +2661 / -0    |
| Tests           | +964 / -0     |
| Automated files | +176 / -0     |
| Documentation   | +1246 / -0    |
| Apps            | +99 / -0      |
| Config/tooling  | +1252 / -43   |

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new diagram parsing/rendering subsystem and hooks it into
editor paste handling, which could impact editor stability/perf and
external-content security surface (SVG/text parsing). Scope is large but
mostly additive behind lightweight detection and fallback behavior.
> 
> **Overview**
> Adds Mermaid-to-tldraw conversion support via a new `@tldraw/mermaid`
package that parses Mermaid text, extracts layout from rendered SVG, and
renders a diagram-agnostic “blueprint” into native tldraw shapes
(nodes/lines/arrows/groups) for supported diagram types.
> 
> Integrates this into dotcom editors (`LocalEditor` and `TlaEditor`)
with a `SneakyMermaidHandler` that detects Mermaid-ish pasted text
without bundling Mermaid eagerly, lazily `import()`s the converter on
demand, and falls back to importing SVG + showing a warning toast for
unsupported diagram types.
> 
> Updates app deps/tsconfig references, adds i18n strings for the new
warning toast, and introduces an examples use-case showcasing
large-scale Mermaid rendering.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
6d3b07f. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Guillaume <guillaume@tldraw.com>

Author: kaneel

apps/dotcom/client/package.json

@@ -36,6 +36,7 @@
 		"@sentry/react": "^7.120.3",
 		"@tldraw/assets": "workspace:*",
 		"@tldraw/dotcom-shared": "workspace:*",
+		"@tldraw/mermaid": "workspace:*",
 		"@tldraw/sync": "workspace:*",
 		"@tldraw/sync-core": "workspace:*",
 		"@tldraw/utils": "workspace:*",

apps/dotcom/client/public/tla/locales-compiled/en.json

@@ -213,6 +213,12 @@
       "value": "Accept all"
     }
   ],
+  "3e2ae04ff0": [
+    {
+      "type": 0,
+      "value": "Unsupported Mermaid diagram"
+    }
+  ],
   "42e53c47c1": [
     {
       "type": 0,
@@ -297,6 +303,12 @@
       "value": "Are you sure you want to delete this group? This action cannot be undone."
     }
   ],
+  "5097d89907": [
+    {
+      "type": 0,
+      "value": "Unsupported diagram, will generate SVG instead"
+    }
+  ],
   "50db1b7e1e": [
     {
       "type": 0,

apps/dotcom/client/public/tla/locales/en.json

@@ -104,6 +104,9 @@
   "3d0238bf16": {
     "translation": "Accept all"
   },
+  "3e2ae04ff0": {
+    "translation": "Unsupported Mermaid diagram"
+  },
   "42e53c47c1": {
     "translation": "Contact the owner to request access."
   },
@@ -146,6 +149,9 @@
   "4e6fbf032b": {
     "translation": "Are you sure you want to delete this group? This action cannot be undone."
   },
+  "5097d89907": {
+    "translation": "Unsupported diagram, will generate SVG instead"
+  },
   "50db1b7e1e": {
     "translation": "Unable to unpublish the file."
   },

apps/dotcom/client/src/components/LocalEditor.tsx

@@ -8,6 +8,7 @@ import { useHandleUiEvents } from '../utils/analytics'
 import { assetUrls } from '../utils/assetUrls'
 import { createAssetFromUrl } from '../utils/createAssetFromUrl'
 import { getScratchPersistenceKey } from '../utils/scratch-persistence-key'
+import { SneakyMermaidHandler } from './SneakyMermaidHandler/SneakyMermaidHandler'
 import { SneakyOnDropOverride } from './SneakyOnDropOverride'
 import { ThemeUpdater } from './ThemeUpdater/ThemeUpdater'
 
@@ -51,6 +52,7 @@ export function LocalEditor({
 			>
 				<SneakyOnDropOverride isMultiplayer={false} />
 				<SneakyToolSwitcher />
+				<SneakyMermaidHandler />
 				<ThemeUpdater />
 				{children}
 			</Tldraw>

apps/dotcom/client/src/components/SneakyMermaidHandler/SneakyMermaidHandler.tsx

@@ -0,0 +1,61 @@
+import { useEffect } from 'react'
+import { defaultHandleExternalTextContent, useEditor, useToasts } from 'tldraw'
+import { defineMessages, useMsg } from '../../tla/utils/i18n'
+import { simpleMermaidStringTest } from './simpleMermaidStringTest'
+
+const messages = defineMessages({
+	unsupportedTitle: { defaultMessage: 'Unsupported Mermaid diagram' },
+	unsupportedDescription: { defaultMessage: 'Unsupported diagram, will generate SVG instead' },
+})
+
+export function SneakyMermaidHandler() {
+	const editor = useEditor()
+	const { addToast } = useToasts()
+	const unsupportedTitle = useMsg(messages.unsupportedTitle)
+	const unsupportedDescription = useMsg(messages.unsupportedDescription)
+
+	useEffect(() => {
+		editor.registerExternalContentHandler('text', async (content) => {
+			if (!simpleMermaidStringTest(content.text)) {
+				await defaultHandleExternalTextContent(editor, content)
+				return
+			}
+			const { createMermaidDiagram } = await import('@tldraw/mermaid')
+			const shapesBefore = new Set(editor.getCurrentPageShapeIds())
+
+			const selectNewShapes = () => {
+				const newShapeIds = [...editor.getCurrentPageShapeIds()].filter(
+					(id) => !shapesBefore.has(id)
+				)
+				if (newShapeIds.length) {
+					editor.setSelectedShapes(newShapeIds)
+				}
+			}
+
+			try {
+				const onUnsupportedDiagram = async (svgString: string) => {
+					await editor.putExternalContent({
+						type: 'svg-text',
+						text: svgString,
+						point: content.point,
+						sources: content.sources,
+					})
+					addToast({
+						id: 'unsupported-mermaid-diagram',
+						title: unsupportedTitle,
+						description: unsupportedDescription,
+						severity: 'warning',
+					})
+				}
+
+				await createMermaidDiagram(editor, content.text, { onUnsupportedDiagram })
+				selectNewShapes()
+			} catch (e) {
+				console.error(e)
+				await defaultHandleExternalTextContent(editor, content)
+			}
+		})
+	}, [editor, addToast, unsupportedTitle, unsupportedDescription])
+
+	return null
+}

apps/dotcom/client/src/components/SneakyMermaidHandler/simpleMermaidStringTest.test.ts

@@ -0,0 +1,109 @@
+import { simpleMermaidStringTest } from './simpleMermaidStringTest'
+
+describe('simpleMermaidStringTest', () => {
+	describe('bare keywords', () => {
+		const keywords = [
+			['flowchart', 'flowchart TD\n  A --> B'],
+			['graph', 'graph LR\n  A --> B'],
+			['sequenceDiagram', 'sequenceDiagram\n  Alice->>Bob: Hi'],
+			['stateDiagram', 'stateDiagram-v2\n  [*] --> Idle'],
+			['classDiagram', 'classDiagram\n  class Animal'],
+			['erDiagram', 'erDiagram\n  CUSTOMER ||--o{ ORDER : places'],
+			['journey', 'journey\n  title My day'],
+			['gantt', 'gantt\n  title A Gantt\n  dateFormat YYYY-MM-DD'],
+			['pie', 'pie\n  "Dogs" : 386'],
+			['gitGraph', 'gitGraph\n  commit'],
+			['mindmap', 'mindmap\n  root((Central))'],
+			['timeline', 'timeline\n  title History'],
+			['sankey', 'sankey-beta'],
+			['xychart', 'xychart-beta'],
+			['block', 'block-beta'],
+			['quadrantChart', 'quadrantChart'],
+			['requirement', 'requirement test_req'],
+			['C4Context', 'C4Context\n  Person(user, "User")'],
+			['C4Container', 'C4Container'],
+			['C4Component', 'C4Component'],
+			['C4Dynamic', 'C4Dynamic'],
+			['C4Deployment', 'C4Deployment'],
+			['packet', 'packet-beta'],
+			['kanban', 'kanban'],
+			['architecture', 'architecture-beta'],
+			['treemap', 'treemap-beta'],
+			['radar', 'radar-beta'],
+			['info', 'info'],
+		] as const
+
+		for (const [keyword, input] of keywords) {
+			it(`detects "${keyword}"`, () => {
+				expect(simpleMermaidStringTest(input)).toBe(true)
+			})
+		}
+	})
+
+	describe('with boilerplate stripped', () => {
+		it('detects keyword after YAML frontmatter', () => {
+			const text = '---\ntitle: test\n---\nflowchart TD\n  A --> B'
+			expect(simpleMermaidStringTest(text)).toBe(true)
+		})
+
+		it('detects keyword after %%{init}%% directive', () => {
+			const text = '%%{init: {"theme":"dark"}}%%\nsequenceDiagram\n  Alice->>Bob: Hi'
+			expect(simpleMermaidStringTest(text)).toBe(true)
+		})
+
+		it('detects keyword after %% line comments', () => {
+			const text = '%% this is a comment\nflowchart LR\n  A --> B'
+			expect(simpleMermaidStringTest(text)).toBe(true)
+		})
+
+		it('detects keyword after frontmatter + directive + comment combined', () => {
+			const text = [
+				'---',
+				'title: combo',
+				'---',
+				'%%{init: {"theme":"forest"}}%%',
+				'%% a comment',
+				'stateDiagram-v2',
+				'  [*] --> Idle',
+			].join('\n')
+			expect(simpleMermaidStringTest(text)).toBe(true)
+		})
+
+		it('detects keyword with leading whitespace', () => {
+			expect(simpleMermaidStringTest('   flowchart TD\n  A --> B')).toBe(true)
+			expect(simpleMermaidStringTest('\t\tgantt\n  title Plan')).toBe(true)
+		})
+	})
+
+	describe('negative cases', () => {
+		it('rejects plain English text', () => {
+			expect(simpleMermaidStringTest('Hello world')).toBe(false)
+		})
+
+		it('rejects text that merely mentions a keyword', () => {
+			expect(simpleMermaidStringTest('Let me think about flowcharts')).toBe(false)
+			expect(simpleMermaidStringTest('My flowchart TD\n  A --> B')).toBe(false)
+		})
+
+		it('rejects empty string', () => {
+			expect(simpleMermaidStringTest('')).toBe(false)
+		})
+
+		it('rejects whitespace-only string', () => {
+			expect(simpleMermaidStringTest('   \n\t\n  ')).toBe(false)
+		})
+
+		it('rejects JSON containing a keyword', () => {
+			expect(simpleMermaidStringTest('{"type": "flowchart", "nodes": []}')).toBe(false)
+		})
+
+		it('rejects HTML containing a keyword', () => {
+			expect(simpleMermaidStringTest('<div class="flowchart">content</div>')).toBe(false)
+		})
+
+		it('rejects a markdown code block wrapping mermaid', () => {
+			const text = '```mermaid\nflowchart TD\n  A --> B\n```'
+			expect(simpleMermaidStringTest(text)).toBe(false)
+		})
+	})
+})

apps/dotcom/client/src/components/SneakyMermaidHandler/simpleMermaidStringTest.ts

@@ -0,0 +1,32 @@
+/**
+ * Lightweight mermaid detection replicating mermaid's own detectType preprocessing
+ * (from mermaid v11.12.2 src/diagram-api/detectType.ts and src/diagram-api/regexes.ts).
+ *
+ * https://github.com/mermaid-js/mermaid/blob/277c4967f97405e9bb172c0a2f67f462a672b162/packages/mermaid/src/diagram-api/detectType.ts
+ * https://github.com/mermaid-js/mermaid/blob/277c4967f97405e9bb172c0a2f67f462a672b162/packages/mermaid/src/diagram-api/regexes.ts
+ *
+ * Strips YAML frontmatter, %%{...}%% directives, and %% comments, then tests for
+ * a known diagram keyword at the start of the cleaned text.
+ *
+ * This file intentionally has zero imports so it can be loaded statically without
+ * pulling in the heavy mermaid library.
+ */
+const FRONTMATTER_REGEX = /^-{3}\s*[\n\r]([\s\S]*?)[\n\r]-{3}\s*[\n\r]+/
+const DIAGRAM_KEYWORD_REGEX =
+	/^\s*(flowchart|graph|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie|gitGraph|mindmap|timeline|sankey|xychart|block|quadrantChart|requirement|C4Context|C4Container|C4Component|C4Dynamic|C4Deployment|packet|kanban|architecture|treemap|radar|info)/
+
+/**
+ * Strip mermaid boilerplate (frontmatter, directives, comments) so only the
+ * diagram body remains. The two global regexes are created as fresh literals
+ * each call to avoid the stateful-lastIndex footgun of module-level /g regexes.
+ */
+function stripMermaidBoilerplate(text: string): string {
+	return text
+		.replace(FRONTMATTER_REGEX, '')
+		.replace(/%{2}{\s*(?:(\w+)\s*:|(\w+))\s*(?:(\w+)|((?:(?!}%{2}).|\r?\n)*))?\s*(?:}%{2})?/gi, '')
+		.replace(/\s*%%.*\n/gm, '\n')
+}
+
+export function simpleMermaidStringTest(text: string): boolean {
+	return DIAGRAM_KEYWORD_REGEX.test(stripMermaidBoilerplate(text))
+}

apps/dotcom/client/src/tla/components/TlaEditor/TlaEditor.tsx

@@ -23,6 +23,7 @@ import {
 } from 'tldraw'
 import { ThemeUpdater } from '../../../components/ThemeUpdater/ThemeUpdater'
 
+import { SneakyMermaidHandler } from '../../../components/SneakyMermaidHandler/SneakyMermaidHandler'
 import { useOpenUrlAndTrack } from '../../../hooks/useOpenUrlAndTrack'
 import { useRoomLoadTracking } from '../../../hooks/useRoomLoadTracking'
 import { trackEvent, useHandleUiEvents } from '../../../utils/analytics'
@@ -261,6 +262,7 @@ function TlaEditorInner({ fileSlug, deepLinks }: TlaEditorProps) {
 				<ThemeUpdater />
 				<SneakyDarkModeSync />
 				<SneakyToolSwitcher />
+				<SneakyMermaidHandler />
 				{app && <SneakyTldrawFileDropHandler />}
 				<SneakyLargeFileHander />
 				<SneakyDebugModeToast />

apps/dotcom/client/tsconfig.json

@@ -24,6 +24,7 @@
 	"references": [
 		{ "path": "../../../packages/assets" },
 		{ "path": "../../../packages/dotcom-shared" },
+		{ "path": "../../../packages/mermaid" },
 		{ "path": "../../../packages/sync" },
 		{ "path": "../../../packages/sync-core" },
 		{ "path": "../../../packages/tldraw" },

apps/examples/package.json

@@ -49,6 +49,7 @@
 		"@tldraw/assets": "workspace:*",
 		"@tldraw/dotcom-shared": "workspace:*",
 		"@tldraw/driver": "workspace:*",
+		"@tldraw/mermaid": "workspace:*",
 		"@tldraw/state": "workspace:*",
 		"@tldraw/sync": "workspace:*",
 		"ag-grid-community": "^32.3.3",
@@ -58,6 +59,7 @@
 		"d3-geo": "^3.1.1",
 		"lazyrepo": "0.0.0-alpha.27",
 		"lodash": "^4.17.21",
+		"mermaid": "11.12.2",
 		"pdf-lib": "^1.17.1",
 		"pdfjs-dist": "^4.10.38",
 		"radix-ui": "^1.4.2",