edododraw 0.1.0 → 0.1.2

package/dist-lib/llms-full.txt

@@ -0,0 +1,1782 @@
+# EDodoDraw — complete documentation (v0.1.1)
+
+> A 100% code/syntax-to-diagram engine with the Excalidraw hand-drawn aesthetic, magic-move camera, scriptable + real-time annotations, animated arrows, and first-class Mermaid import.
+>
+> This ONE file is the full, LLM-consumable documentation for EDodoDraw. It
+> concatenates every guide and every runnable example, generated verbatim
+> from the source repo — nothing is summarised or omitted.
+
+- Live site (rendered docs + live demos): https://vivmagarwal.github.io/edododraw/
+- npm package: https://www.npmjs.com/package/edododraw  (`npm i edododraw`)
+- Source repo: https://github.com/vivmagarwal/edododraw
+
+What EDodoDraw is: a 100% code/syntax-to-diagram engine with the Excalidraw
+hand-drawn look, a magic-move camera, scriptable + real-time annotations,
+animated arrows, and first-class Mermaid import. You write `.edd` source; it
+renders a diagram. Use it via the DSL (see "Language reference") and/or embed
+it in an app via the `EdodoDraw` facade (see "Embed in your app").
+
+## Contents
+
+1. Language reference
+2. Camera & timeline
+3. Annotations
+4. Import & export
+5. Embed in your app
+6. Extend & make plugins
+7. Architecture
+8. Development standards
+9. Runnable examples (.edd)
+
+==============================================================================
+
+# ═══ Language reference  (docs/DSL_LANGUAGE_GUIDE.md) ═══
+
+# EDodoDraw Language Guide (`.edd`)
+
+The complete reference for **EDodoDraw code** — the text syntax that compiles 100% to a diagram. Written to be equally readable by humans and generatable by LLMs.
+
+> Implementation: `src/engine/dsl/` (lexer → parser → compiler). This guide documents what the compiler **actually accepts today**. Runnable examples live in `examples/`.
+
+---
+
+## 1. Mental model
+
+A program has two halves:
+
+1. **Structure** — declared once inside `scene { … }`: nodes, edges, groups, styles, layout. Mermaid-friendly (arrow glyphs, `id[Label]` sugar, `:::class`) with clean `{ key: value }` attribute blocks for styling.
+2. **Choreography** (optional) — a `timeline { … }` of ordered `beat`s. Each beat is a keyframe of **camera** (fit/focus/zoom/pan), **annotate** (highlight/underline/point-at/…), and **reveal** (show/hide). The engine "magic-moves" between beats.
+
+Minimal program:
+
+```edd
+scene {
+  a[Start] --> b[Do work] --> c{OK?}
+  c -->|yes| d(Done)
+  c -->|no|  a
+}
+```
+
+Everything else is optional layering on top.
+
+---
+
+## 2. Top-level statements
+
+| Statement | Purpose |
+|---|---|
+| `edd 1.0` | Optional version marker (first line). |
+| `meta { title: "…", background: "#…" }` | Diagram metadata. |
+| `theme name { tokens { $x: #hex, … } }` | Named theme + reusable `$tokens`. |
+| `style .name { … }` / `style .name extends .other { … }` | Reusable style class. |
+| `defaults { node { … } edge { … } }` | Defaults applied to every node/edge. |
+| `scene [name] { … }` | Structure. Multiple `scene` blocks merge. |
+| `annotate ["label"] { … }` | Always-on annotations (outside the timeline). |
+| `timeline [name] { … }` | Choreography (beats). |
+| `overrides { id at (x, y) [size (w, h)] … }` | Pinned positions/sizes (usually machine-written by direct editing — see §11). |
+| `mermaid """ … """` | Import a raw Mermaid diagram (see IMPORT_AND_EXPORT_GUIDE.md). |
+
+Comments: `// line`, `%% line` (Mermaid-style), `/* block */` (nestable).
+
+---
+
+## 3. Nodes — three equivalent forms
+
+```edd
+// 1. Mermaid sugar (shape from the bracket kind)
+db[(Postgres)]          // cylinder
+q{{Load Balancer}}      // hexagon
+ok([Success])           // pill / stadium
+
+// 2. Keyword form (explicit shape keyword first) — best for LLMs
+cylinder db "Postgres"
+hexagon  lb "Load Balancer"
+
+// 3. Explicit form
+node db "Postgres" as cylinder
+```
+
+### Shape sugar table
+
+| Sugar | Shape | Sugar | Shape |
+|---|---|---|---|
+| `[x]` | rectangle | `[(x)]` | cylinder |
+| `(x)` | round-rectangle | `((x))` | circle |
+| `([x])` | pill / stadium | `{x}` | diamond |
+| `[[x]]` | rectangle | `{{x}}` | hexagon |
+| `[/x/]` | parallelogram | `[/x\]` | trapezoid |
+
+### Full shape keyword list
+
+`rect` · `round-rect` · `ellipse` · `circle` · `diamond` (`decision`) · `triangle` · `hexagon` · `parallelogram` · `trapezoid` · `cylinder` (`db`) · `cloud` · `document` · `note` · `actor` · `pill` (`stadium`) · `text` · `star`
+
+Unknown shape names resolve through the **shape plugin registry** (`registerShape`) — see DEVELOPMENT_STANDARDS.md.
+
+### Node attributes
+
+```edd
+rect api "API Service" {
+  fill: green            // palette name or #hex → soft bg + matching stroke
+  stroke: #1971c2
+  fillStyle: hachure     // hachure | cross-hatch | solid | zigzag | dots | none
+  strokeWidth: bold      // thin | medium | bold | thick | <number>
+  strokeStyle: dashed    // solid | dashed | dotted
+  roughness: artist      // architect(0) | artist(1) | cartoonist(2) | <number>
+  roundness: 16          // corner radius (px)
+  font: hand             // hand | normal | code
+  fontSize: 22
+  opacity: 0.9           // 0..1 or 0..100
+  at: (1180, 40)         // absolute world position
+  pin: true              // exclude from auto-layout (pinned)
+  size: (180, 80)        // explicit width,height
+  tags: [edge, critical] // selectable via .edge / .critical
+}
+```
+
+Apply style classes with `:::` — `rect api "API" :::card :::critical`.
+
+### Named colors
+
+Stroke palette: `black gray red pink grape violet blue cyan teal green lime yellow orange brown white`.
+`fill: green` yields the pleasant Excalidraw soft-green box with a matching darker-green outline. `transparent`/`none` → no fill.
+
+---
+
+## 4. Edges
+
+```edd
+a --> b                      // arrow
+a --> b "label"              // trailing label
+a -->|mid label| b           // Mermaid mid-label
+a -> b -> c                  // chain → two edges
+a -> b & c                   // fan-out → a→b and a→c
+a@(1,0.5) -> b.north         // anchored endpoints (see §7)
+edge e1: a --> b "named"     // give the edge an id
+```
+
+### Glyph table
+
+| Glyph | Line | End arrowhead | Notes |
+|---|---|---|---|
+| `--` `---` | solid | none | plain connector |
+| `->` `-->` | solid | arrow | canonical |
+| `<-` `<--` | solid | arrow at start | reversed |
+| `<->` `<-->` | solid | arrows both | bidirectional |
+| `-.->` | dashed | arrow | async |
+| `..>` | dotted | arrow | dependency |
+| `==>` | solid (thick) | arrow | emphasis |
+| `~>` | solid (curved) | arrow | **animated `flow` by default** |
+| `--o` `-o` | solid | circle | association |
+| `--x` `-x` | solid | bar | termination |
+
+### Edge attributes
+
+```edd
+a -> b {
+  color: #1971c2
+  strokeWidth: bold
+  strokeStyle: dashed
+  startArrow: dot          // none arrow triangle bar dot circle diamond crow …
+  endArrow: triangle
+  curve: curved            // straight | curved | orthogonal | elbow | bezier | arc
+  animate: dash-march      // see §5
+}
+```
+
+Parallel edges between the same pair automatically fan out so they never overlap.
+
+---
+
+## 5. Animated arrows
+
+Set `animate: <kind>` on any edge. EDodoDraw ships far more than Excalidraw:
+
+| Kind | Effect |
+|---|---|
+| `flow` | dashes flow along the path |
+| `dash-march` | marching ants |
+| `draw-on` | the line draws itself in (loops) |
+| `comet` | bright head with a fading trail + glow |
+| `gradient-flow` | animated multi-color gradient stroke |
+| `electric` | fast jittered dashes |
+| `pulse` | opacity/width pulse |
+
+`glow`→comet, `caravan`→dash-march, `wiggle`→flow are accepted aliases. Speed: `animate: flow { speed: 1.4 }`.
+
+---
+
+## 6. Layout
+
+```edd
+scene {
+  layout dag { direction: down, gap: 64, rankGap: 110 }
+  …
+}
+```
+
+| Kind | Behavior |
+|---|---|
+| `dag` / `tree` / `flow` | layered graph via dagre (respects `direction`) |
+| `grid` | row-major grid |
+| `radial` | hub + ring (`center: id`) |
+| `manual` / `free` | use each node's `at:` position |
+
+`direction`: `down`(TB) · `up`(BT) · `right`(LR) · `left`(RL). Nodes with `pin: true` (or `at:` set) are excluded from auto-layout and kept fixed. Groups are clustered so their members stay together.
+
+---
+
+## 7. Connection anchors (richer than Excalidraw's 4)
+
+Attach an edge endpoint to a specific point on a node with `.anchor` or `@(u,v)`:
+
+- Compass: `.n .s .e .w .ne .nw .se .sw .c` (aliases `.top .bottom .left .right .center`).
+- Side fraction: `.top:0.3` (30% along the top edge), also `.right:0.75`, `.bottom:0.5`, `.left:0.2`.
+- Normalized: `@(0.5, 1.0)` — u,v in 0..1 of the node box.
+- Angle: `.angle:45` — degrees from the center (0 = east, clockwise).
+
+```edd
+gw.s      -> api.n            // bottom of gw → top of api
+api@(1, 0.5) -> db.top:0.3    // right-middle of api → 30% along db's top edge
+```
+
+Omit the anchor for automatic border attachment aimed at the other endpoint.
+
+---
+
+## 8. Groups
+
+```edd
+scene {
+  group services "Application Services" {
+    round-rect auth "Auth"
+    round-rect api  "API"
+  }
+}
+```
+
+Draws a labelled dashed frame around its members. A group is addressable as one target (e.g. `camera focus services`, `spotlight services`).
+
+---
+
+## 9. Annotations
+
+Annotate elements in an always-on `annotate { … }` block or inside a timeline beat.
+
+| Command | Example |
+|---|---|
+| `highlight` | `highlight cdn { color: yellow }` |
+| `underline` | `underline api { color: #2563eb, style: wavy }` |
+| `strike` | `strike legacy { color: red }` |
+| `box` (over a set) | `box [gateway, api, db] "critical path" { color: red }` |
+| `circle-mark` | `circle-mark queue "retry here"` |
+| `point-at` | `point-at gateway "single entry" { from: ne, color: #2563eb }` |
+| `callout` | `callout db "source of truth" { placement: bottom }` |
+| `spotlight` | `spotlight services { dim: 0.72 }` |
+| `note-marker` | `note-marker db "1"` |
+
+`from` / `placement` take a cardinal (`n s e w ne …`). Annotations anchor to their target and track the camera. See ANNOTATIONS_GUIDE.md for the real-time editor and round-trip.
+
+---
+
+## 10. Timeline (magic-move presentation)
+
+```edd
+timeline story {
+  beat overview "The whole system" {
+    camera fit-all over 800ms
+    reveal { show all with fade-in }
+    narrate: "End-to-end request path."
+  }
+
+  beat data "Where state lives" {
+    camera focus [db, cache, queue] zoom 1.7 ease ease-in-out
+    annotate {
+      callout db "primary of record" { placement: right }
+      spotlight [db, cache, queue] { dim: 0.7 }
+    }
+    narrate: "All writes funnel through Postgres."
+    hold: 2s
+  }
+}
+```
+
+### Camera operations (inline or block form)
+
+| Op | Inline | Block |
+|---|---|---|
+| Frame all | `camera fit-all` | `camera { }` |
+| Focus target(s) | `camera focus [a,b] zoom 1.6` | `camera { focus: [a,b], zoom: 1.6 }` |
+| Absolute zoom | `camera zoom 1.3` | `camera { zoom: 1.3 }` |
+| Pan | `camera pan (x, y)` | `camera { pan: (x,y) }` |
+| Reset | `camera reset` | — |
+
+Shared modifiers: `zoom N` · `over <ms|s>` · `ease <easing>` · `pad N`.
+Easings: `linear ease ease-in ease-out ease-in-out back-out anticipate spring` — plus `magic` (an alias for the tuned spring). `spring(…)` is accepted and animates with the tuned spring; `cubic-bezier(…)` is accepted syntax but currently falls back to the default `ease-in-out` (parameters for both are reserved for a future release).
+
+### Reveal / hide
+
+`reveal { show all }`, `reveal { hide legacy }`, `reveal { show .critical with pop }`. Visibility is **sticky** across beats until changed. Beat annotations are cleared at the start of each beat (unless in the always-on `annotate` block).
+
+### Beat properties
+
+`narrate: "caption"` (speaker note shown under the diagram), `hold: 2s` (dwell before auto-advance during Play).
+
+---
+
+## 11. Overrides — where direct edits live
+
+The layout engine positions nodes automatically. When you **drag, resize, add, rename, restyle, or delete elements directly on the canvas** (in the playground, or via the editor API — see INTEGRATION_GUIDE.md), those changes are written straight back into the source so the code stays the single source of truth. Geometry lands in an `overrides { … }` block:
+
+```edd
+scene {
+  layout dag { direction: down }
+  rect a "A"
+  rect b "B"
+  a --> b
+}
+
+overrides {
+  a at (120, 40)             // pin a node's top-left corner (world units)
+  b at (120, 220) size (160, 90)   // …and optionally its width/height
+}
+```
+
+- Each entry is `id at (x, y)` with an optional `size (w, h)`. Coordinates are the node's top-left in world units; `id` may be any node — declared, auto-created from an edge, or Mermaid-imported.
+- A pinned node keeps its coordinates; the layout still routes edges and places any *un-pinned* nodes around it.
+- The block is **machine-managed**: dragging a node rewrites its entry, and the engine freezes the other nodes' current positions into the block at the same time so the layout doesn't reshuffle under you. You can hand-edit or delete entries freely — remove the whole block to hand control back to auto-layout.
+- Restyle/rename/add/delete edits patch the node's declaration and edges in place (e.g. a fill swatch upserts `{ fill: green }`); only position/size use `overrides`.
+
+---
+
+## 12. Diagnostics
+
+The compiler recovers from errors and reports many at once, each with `line:col`, a stable code (`E-EDGE-NOOP`, `E-STMT`, `W-UNKNOWN-KEY`, …), and a hint. A bad statement never blanks the diagram — valid statements still render.
+
+---
+
+## 13. LLM authoring tips
+
+- Prefer the **keyword node form** (`cylinder db "…"`) and the **block form** for camera/annotations — they're unambiguous.
+- One statement per line. Attributes are `{ key: value, … }` (commas or newlines both separate).
+- Declare structure once in `scene`; reference ids everywhere else. Forward references are fine.
+- Colors: use palette names (`green`, `blue`) for the Excalidraw look, or `#hex`.
+- To animate a connector, add `animate: flow` (or use the `~>` glyph).
+- To present, add a `timeline` of `beat`s with `camera focus …` — that's the differentiator.
+
+See `examples/*.edd` for complete, runnable programs.
+
+==============================================================================
+
+# ═══ Camera & timeline  (docs/CAMERA_AND_TIMELINE_GUIDE.md) ═══
+
+# Camera & Timeline Guide
+
+How EDodoDraw does "magic-move" — smooth, scriptable camera moves and step-by-step presentations.
+
+## Architecture
+
+The camera is a `{ cx, cy, zoom }` transform (world point centered in the viewport). It is applied as the SVG `transform` on the world `<g>`:
+
+```
+translate(vw/2, vh/2) · scale(zoom) · translate(-cx, -cy)
+```
+
+- **Math** — `src/engine/camera/fit.ts` (`cameraForBBox`: frame any bbox with padding).
+- **Easing** — `src/engine/camera/easing.ts` (`linear ease ease-in ease-out ease-in-out back-out anticipate spring`; `spring` is a tuned overshoot for magic-move).
+- **Controller** — `src/engine/camera/controller.ts` drives interruptible, retargetable rAF tweens. Position eases linearly; **zoom interpolates in log space** so fast/slow zooms feel natural. Duration auto-scales with travel distance + zoom ratio when not specified.
+
+```ts
+const controller = new CameraController(renderer);
+await controller.fitAll(scene, { padding: 80 });
+await controller.focus(scene, ["db", "cache"], { zoom: 1.7, easing: "spring" });
+controller.zoomBy(1.2, screenPoint);   // wheel zoom around cursor
+controller.panByScreen(dx, dy);         // drag pan
+```
+
+Mid-flight `animateTo` retargets smoothly from the current interpolated state — no snap.
+
+## Interaction (built into the canvas)
+
+- **Wheel** → zoom around the cursor.
+- **Drag** → pan.
+- Any user gesture pauses the timeline player.
+
+## Timeline player
+
+`src/engine/timeline/player.ts` plays `scene.steps` (compiled from a `timeline { beat … }` block — see [DSL_LANGUAGE_GUIDE §10](DSL_LANGUAGE_GUIDE.md)). Each beat diffs against the running state:
+
+| Channel | Rule |
+|---|---|
+| Camera | **Sticky** — a beat with no `camera` keeps the current one. |
+| Visibility (`show`/`hide`) | **Sticky** until changed. |
+| Annotations | **Beat-scoped** — replaced each beat (always-on `annotate` block persists underneath). |
+
+API: `player.load(scene)`, `play()`, `pause()`, `next()`, `prev()`, `restart()`, `goto(i)`. It emits `PlayerState { index, total, caption, stepName, playing }` for the UI. Auto-advance uses each beat's `hold:` (default 3.2s).
+
+```edd
+timeline story {
+  beat overview "All"  { camera fit-all over 800ms; narrate: "the system" }
+  beat focus  "Detail" { camera focus [db, queue] zoom 1.7 ease spring; hold: 2s
+                         annotate { spotlight [db, queue] { dim: 0.7 } } }
+}
+```
+
+In the app, the bottom **player bar** shows Fit / Restart / Prev / Play / Next, the step indicator, and the caption. `⤢ Fit` reframes the whole diagram at any time.
+
+==============================================================================
+
+# ═══ Annotations  (docs/ANNOTATIONS_GUIDE.md) ═══
+
+# Annotations Guide
+
+Annotations are the layer of **highlights, underlines, arrows, callouts, spotlights** on top of a diagram — authored in code **or** drawn live, unified under one model (`Annotation` in `src/engine/scene/types.ts`).
+
+## One model, two sources
+
+- **Scripted** — from a top-level `annotate { … }` block (always-on) or inside a timeline `beat` (beat-scoped). Compiled into `scene.annotations` / `step.annotations`.
+- **Live** — drawn interactively by the user. Kept by `LiveAnnotationController` in a separate `live` layer.
+
+Both are the same `Annotation` record and both render through `AnnotationLayer` (`src/engine/annotate/layer.ts`), which draws hand-drawn (rough.js) marks in **world space** so they track the camera and their anchored element.
+
+### Anchoring
+
+`Annotation.target` is a ref to a node/edge/group id (tracks that element), a set (`options.members`), or an absolute world point. When the camera moves or layout changes, the annotation follows because it lives in the transformed world layer and re-resolves its target bbox on render.
+
+## Kinds
+
+`highlight` (marker) · `underline` (solid/double/wavy) · `strike` · `box` (over a set, labelled) · `circle-mark` · `point-at` (hand-drawn pointer + label) · `callout` (leader + bubble) · `spotlight` (dims everything but the target via an SVG mask) · `note-marker` · `connector` (free arrow) · `sticky` (note). See the table in [DSL_LANGUAGE_GUIDE §9](DSL_LANGUAGE_GUIDE.md).
+
+## Real-time editing
+
+The floating toolbar (left of the canvas) selects a tool; `LiveAnnotationController` (`src/engine/annotate/interact.ts`) handles pointer events:
+
+| Tool | Gesture | Result |
+|---|---|---|
+| Select | click a mark → select; drag → move; Delete → remove | edit existing |
+| Highlight / Underline / Box / Circle | click an element | anchored annotation, spring reveal |
+| Arrow | drag; endpoints snap to elements | `point-at` / free connector |
+| Text | click | sticky note (inline text input) |
+
+Undo/redo (`⌘Z` / `⇧⌘Z`) is a snapshot stack. All interaction is smooth and reversible; nothing mutates the source until you commit.
+
+## Round-trip: commit to code
+
+The **⤓ code** button serializes live annotations back into an `annotate "live" { … }` block and appends it to the editor, then clears the live layer — so what you drew becomes part of the program and re-renders as scripted:
+
+```edd
+annotate "live" {
+  highlight idea { color: yellow }
+  underline vibe { color: #1971c2 }
+  circle-mark edit { color: #e8590c }
+  point-at hello { from: s, color: #1971c2 }
+}
+```
+
+Element-anchored annotations serialize exactly; free-form marks (a floating arrow with no element under either end) are emitted as a comment noting they aren't representable by id. See `LiveAnnotationController.commitToCode` and `tests/annotations.test.ts` for the round-trip contract.
+
+## Animated arrows
+
+The connector animations (`flow`, `dash-march`, `draw-on`, `comet`, `gradient-flow`, `electric`, `pulse`) are a CSS overlay path over the hand-drawn stroke — see `animationOverlay` in `src/engine/render/edges.ts` and the keyframes in `src/engine/render/theme.css.ts`. Set on any edge with `animate:` or the `~>` glyph.
+
+==============================================================================
+
+# ═══ Import & export  (docs/IMPORT_AND_EXPORT_GUIDE.md) ═══
+
+# Import & Export Guide
+
+## Mermaid import
+
+EDodoDraw imports raw Mermaid and re-renders it in the hand-drawn style, **preserving node ids** so you can choreograph and annotate the result.
+
+```edd
+mermaid """
+flowchart LR
+  app[App Servers] --> otel[OTel Collector]
+  otel --> prom[Prometheus]
+  prom --> grafana[Grafana]
+"""
+
+timeline walkthrough {
+  beat collect "Collection" {
+    camera focus [app, otel] zoom 1.7        // references the mermaid ids
+    annotate { point-at otel "single ingestion point" { from: s } }
+  }
+}
+```
+
+### How it works
+
+`src/engine/import/mermaid.ts` wraps `@excalidraw/mermaid-to-excalidraw`. Mermaid rendering needs the browser, so import is **async and app-side**:
+
+1. `extractMermaidBlocks(source)` pulls the `mermaid """ … """` bodies (pure string fn — unit-testable).
+2. `convertMermaid(body)` runs the Mermaid → Excalidraw-skeleton converter and maps each element to Scene IR: vertices → pinned nodes (mermaid id preserved), arrows → edges bound by `start.id`/`end.id`.
+3. `injectMermaid(scene, fragment)` merges the fragment into the compiled scene, so `id:::class` re-tags and timeline/annotate references resolve against the imported nodes.
+
+Supported: flowcharts (and other mermaid graph types the converter emits as elements). The synchronous DSL compiler stays DOM-free; only the app awaits conversion.
+
+## Export
+
+Toolbar (top-right): **SVG · PNG · JSON · Copy**. Implemented in `src/engine/export.ts`.
+
+| Format | Notes |
+|---|---|
+| **SVG** | Standalone, framed to the content bbox (independent of the current camera). The hand-drawn font is **embedded as base64**, so the file renders correctly anywhere. |
+| **PNG** | The SVG rasterized to a 2× canvas. |
+| **JSON** | The full `Scene` IR — round-trippable, inspectable. |
+| **Copy** | The `.edd` source to the clipboard. |
+
+```ts
+await downloadSVG(renderer, scene);
+await downloadPNG(renderer, scene);
+downloadJSON(scene);
+```
+
+Screen-space overlays (player bar, selection outlines, hidden elements) are stripped from exports; the background is the scene/theme background.
+
+==============================================================================
+
+# ═══ Embed in your app  (docs/INTEGRATION_GUIDE.md) ═══
+
+# Integrating EDodoDraw
+
+How to embed the `edododraw` engine in your own app — vanilla JS, any framework,
+React, or a server. Everything here is checked against the published API in
+`src/lib/` and `src/engine/`.
+
+> Want to _extend_ the engine (new shapes, animations, layouts)? See
+> [EXTENDING_GUIDE.md](EXTENDING_GUIDE.md). For the diagram source language, see
+> [DSL_LANGUAGE_GUIDE.md](DSL_LANGUAGE_GUIDE.md).
+
+---
+
+## 1. Install
+
+```bash
+npm i edododraw
+```
+
+- **Runtime dependencies install automatically:** `roughjs` (hand-drawn strokes)
+  and `@dagrejs/dagre` (auto-layout).
+- **Mermaid import** (`@excalidraw/mermaid-to-excalidraw`) ships as an
+  _optionalDependency_: it's installed by default, but install won't fail if it's
+  unavailable, and it's **lazy-loaded** only when a `mermaid` block is actually
+  rendered. See [§6](#6-mermaid-note).
+- **React is optional.** It's a _peer_ dependency needed only for the
+  `edododraw/react` entry. For the core `edododraw` entry you don't need React at
+  all.
+
+The package is **ESM-only** (`"type": "module"`, `exports` expose `import` only)
+and targets **Node ≥ 18**. Two entry points:
+
+| Import | What you get |
+|---|---|
+| `edododraw` | The core: `EdodoDraw` facade + the whole engine (`compileEdd`, `SvgRenderer`, `registerShape`, Scene IR types, …). |
+| `edododraw/react` | `EdodoDrawView` React component (thin wrapper over the facade). |
+
+---
+
+## 2. Quick start (vanilla / any framework)
+
+Give the engine a sized container element and hand it EDodoDraw source. The
+`EdodoDraw` facade mounts an `<svg>`, compiles + renders, and exposes camera,
+timeline, live annotations, and export behind one object.
+
+```html
+<!doctype html>
+<div id="diagram" style="width: 100%; height: 500px;"></div>
+<script type="module">
+  import { EdodoDraw } from "edododraw";
+
+  const el = document.getElementById("diagram");
+  const edd = new EdodoDraw(el, { interactive: true });
+
+  await edd.render(`
+    scene {
+      a[Client] --> b[API] --> c[(Database)]
+    }
+    timeline {
+      beat intro "Overview" { camera fit-all, reveal { show a } }
+      beat call  "Trace the call" { camera focus b zoom 1.4, reveal { show b, c } }
+    }
+  `);
+
+  edd.play();   // drives the timeline (magic-move). No-op if the source has no timeline.
+</script>
+```
+
+The **container must have a height** — the facade sets `position` and
+`overflow: hidden` for you but never a size, and `autoFit` needs a measurable
+viewport. A `0px`-tall div renders nothing.
+
+`render()` is async (a `mermaid` block may need the lazy runtime) and safe to call
+on every keystroke — stale runs are discarded. It resolves to
+`{ scene, diagnostics }`.
+
+---
+
+## 3. `EdodoDraw` API reference
+
+```ts
+import { EdodoDraw } from "edododraw";
+new EdodoDraw(container: HTMLElement, options?: EdodoDrawOptions)
+```
+
+### Options (`EdodoDrawOptions`)
+
+| Option | Type | Default | Effect |
+|---|---|---|---|
+| `interactive` | `boolean` | `true` | Enable pan (drag), zoom (wheel), and live-annotation pointer/keyboard handling. Set `false` for a static embed. |
+| `grid` | `boolean` | `true` | Draw a dotted grid that pans/zooms with the camera (a CSS background on the container). |
+| `autoFit` | `boolean` | `true` | Fit the whole diagram into view after each `render()`. |
+| `padding` | `number` | `80` | Screen-px padding used when fitting. |
+
+### Render / scene
+
+| Method | Signature | Notes |
+|---|---|---|
+| `render` | `(source: string) => Promise<RenderResult>` | Compile + render. `RenderResult = { scene: Scene; diagnostics: Diagnostic[] }`. |
+| `getScene` | `() => Scene` | The current rendered scene (Scene IR). |
+| `getSource` | `() => string` | The last source string passed to `render`. |
+
+### Camera
+
+| Method | Signature | Notes |
+|---|---|---|
+| `fit` | `(animate?: boolean) => void` | Fit the whole diagram (default `animate = true`). |
+| `focus` | `(ids: string[], opts?: { zoom?: number; padding?: number }) => Promise<void>` | Animate to frame the given node/group/edge ids. |
+| `zoomBy` | `(factor: number) => void` | Multiply zoom around the viewport centre (e.g. `1.2` in, `0.8` out). |
+| `reset` | `() => void` | Animate back to fit-all. |
+| `camera` | `get camera(): CameraController` | The underlying controller for advanced moves (`animateTo`, `panByScreen`, …). |
+
+### Timeline (magic-move presentation)
+
+Only meaningful when the source contains a `timeline { … }` — otherwise these
+no-op. State changes emit via `on("state", …)`.
+
+| Method | Signature | Notes |
+|---|---|---|
+| `play` | `() => void` | Auto-advance through beats. No-op if the scene has no steps. |
+| `pause` | `() => void` | Stop auto-advance. |
+| `next` / `prev` | `() => void` | Step forward / back one beat. |
+| `goto` | `(i: number) => void` | Jump to beat index `i` (0-based). |
+| `restart` | `() => void` | Go to the first beat. |
+| `timeline` | `get timeline(): TimelinePlayer` | The underlying player (`hasTimeline`, current index, …). |
+
+### Tools — direct editing & annotation
+
+`setTool` selects the active pointer tool and switches the engine between its two
+interactive **modes**. All of this requires `interactive: true`.
+
+| Method | Signature | Notes |
+|---|---|---|
+| `setTool` | `(tool: string) => void` | **Edit tools** (mode `edit`): `"select"`, `"hand"`, `"rect"`, `"ellipse"`, `"diamond"`, `"text"`, `"arrow"`. **Annotate tools** (mode `annotate`): `"highlight"`, `"underline"`, `"mark-box"`, `"mark-circle"`, `"point"`, `"note"`. |
+
+**Direct editing (canvas → code).** In `edit` mode, pointer gestures manipulate the
+diagram and every change is patched back into the source (emitted as the `"edit"`
+event — see below), keeping the code the single source of truth:
+
+- **select / move** — click a node to select (8-handle box); drag to move.
+- **resize** — drag a handle. Move/resize write an `overrides { … }` block (see DSL_LANGUAGE_GUIDE §11).
+- **rename** — double-click a node, type, `Enter`.
+- **add** — pick `rect`/`ellipse`/`diamond`/`text` and drag on empty canvas; `arrow` drags between two nodes to connect them.
+- **delete** — `Delete`/`Backspace` on the selection.
+
+| Method | Signature | Notes |
+|---|---|---|
+| `applyStyle` | `(id, { fill?, stroke?, shape? }) => void` | Upsert style attrs on a node's declaration (e.g. `{ fill: green }`). |
+| `renameSelected` | `() => void` | Open the rename field for the current selection. |
+| `deleteSelected` | `() => void` | Delete the selection (node decl + its edges + its override). |
+| `fitNext` | `() => void` | Fit the whole diagram on the next render (e.g. after loading a new document). |
+| `editor` | `get editor(): EditController` | The underlying edit controller (`clearSelection`, `getTool`, …). |
+
+### Live annotations
+
+| Method | Signature | Notes |
+|---|---|---|
+| `undo` / `redo` | `() => void` | Undo/redo live annotation edits. |
+| `clearAnnotations` | `() => void` | Remove all live annotations. |
+| `annotationsToCode` | `() => string` | Serialize live annotations back to an `annotate { … }` DSL block. |
+| `annotator` | `get annotator(): LiveAnnotationController` | The underlying controller. |
+
+### Export
+
+| Method | Signature | Notes |
+|---|---|---|
+| `toSVG` | `() => Promise<string>` | Standalone SVG string with the hand-drawn font **embedded** (renders offline). |
+| `toPNG` | `() => Promise<Blob>` | Rasterised PNG (2× by default). |
+| `toJSON` | `() => Scene` | The Scene IR (the same object `getScene` returns). |
+| `downloadSVG` / `downloadPNG` | `() => Promise<void>` | Trigger a browser download. |
+| `downloadJSON` | `() => void` | Download the Scene IR as JSON. |
+
+### Lifecycle
+
+| Method | Signature | Notes |
+|---|---|---|
+| `resize` | `() => void` | Re-measure the container and re-apply the camera. Called automatically on container resize when `interactive: true` (via `ResizeObserver`); call it yourself otherwise. |
+| `destroy` | `() => void` | Remove listeners, the SVG, and the timeline; clears event subscribers. Always call on teardown. |
+
+### Events — `on(event, cb): () => void`
+
+`on` returns an **unsubscribe** function. Six events:
+
+| Event | Payload | Fires when |
+|---|---|---|
+| `"render"` | `RenderResult` `{ scene, diagnostics }` | After each successful `render()`. |
+| `"diagnostics"` | `Diagnostic[]` | After each `render()`, with compile diagnostics. |
+| `"state"` | `PlayerState` `{ index, total, caption, playing, stepName }` | Timeline position/playing changes. |
+| `"live"` | `LiveState` `{ tool, count, canUndo, canRedo, selected }` | Live-annotation tool/selection/undo state changes. |
+| `"edit"` | `source: string` | A direct-manipulation edit patched the source. Re-render with this new source (and mirror it into your code editor). |
+| `"editstate"` | `EditState` `{ tool, selected }` | Edit-mode tool or node selection changes (drive a property panel / toolbar highlight). |
+
+A `Diagnostic` has `{ severity: "error"|"warning"|"info", code, message, line, col,
+start, end, expected?, found?, hint? }` (see `src/engine/dsl/diagnostics.ts`).
+
+```ts
+const off = edd.on("diagnostics", (diags) => {
+  const errors = diags.filter((d) => d.severity === "error");
+  if (errors.length) console.warn(errors.map((d) => `${d.code}: ${d.message}`).join("\n"));
+});
+// later: off();  // unsubscribe
+edd.on("state", (s) => console.log(`beat ${s.index + 1}/${s.total} — ${s.stepName}`));
+
+// Direct-edit round-trip: the diagram is editable, and edits flow back to code.
+let source = "scene { rect a \"A\"\n a --> b }";
+edd.on("edit", (next) => {
+  source = next;              // keep your source of truth in sync…
+  void edd.render(next);      // …and re-render (also mirror `next` into your code editor)
+});
+edd.setTool("select");        // enable move/resize/rename/delete on the canvas
+```
+
+---
+
+## 4. React
+
+`edododraw/react` exports `EdodoDrawView`, a thin wrapper that owns an `EdodoDraw`
+instance for the lifetime of the component.
+
+```tsx
+import { EdodoDrawView } from "edododraw/react";
+import type { EdodoDraw } from "edododraw/react";
+
+export function Diagram() {
+  return (
+    <div style={{ height: 500 }}>
+      <EdodoDrawView
+        source={`scene { a[Hello] --> b[World] }`}
+        interactive
+        grid={false}
+        style={{ borderRadius: 8 }}
+        onReady={(edd: EdodoDraw) => edd.on("state", (s) => console.log(s.stepName))}
+        onDiagnostics={(diags) => console.log(diags)}
+        onState={(state) => console.log(state.index)}
+      />
+    </div>
+  );
+}
+```
+
+### Props (`EdodoDrawViewProps`)
+
+`EdodoDrawViewProps` extends `EdodoDrawOptions` (so `interactive`, `grid`,
+`autoFit`, `padding` are all valid props), plus:
+
+| Prop | Type | Notes |
+|---|---|---|
+| `source` | `string` (required) | EDodoDraw source. Re-renders whenever it changes. |
+| `className` | `string` | On the host `<div>`. |
+| `style` | `CSSProperties` | Merged onto the host (which defaults to `width/height: 100%`). |
+| `onReady` | `(edd: EdodoDraw) => void` | Called **once** after mount with the imperative instance — use it to subscribe to events or grab a ref for camera/export. |
+| `onDiagnostics` | `(diags: Diagnostic[]) => void` | Wired to the `"diagnostics"` event. |
+| `onState` | `(state: PlayerState) => void` | Wired to the `"state"` event. |
+
+The host `<div>` fills its parent (`width/height: 100%`), so wrap it in a **sized**
+element. Note the `EdodoDrawOptions` props (`interactive`, `grid`, …) are read
+**once at mount**; only `source` is reactive. To change options at runtime, remount
+(e.g. via a React `key`).
+
+---
+
+## 5. Low-level engine usage (SSR / Node-safe)
+
+The DSL compiler is **synchronous and DOM-free**, so you can compile and validate a
+diagram anywhere — Node, an edge function, a build step — without a browser:
+
+```ts
+import { compileEdd } from "edododraw";
+
+const { scene, diagnostics, report } = compileEdd(`scene { a -> b -> c }`);
+// scene       : the Scene IR (nodes/edges/steps/…), JSON-serializable
+// diagnostics : a DiagnosticBag — diagnostics.items is Diagnostic[], .hasErrors, .errors
+// report      : string[] — human-readable, source-annotated diagnostic blocks
+
+if (diagnostics.hasErrors) throw new Error(report.join("\n\n"));
+```
+
+> `compileEdd` returns `diagnostics` as a **`DiagnosticBag`** (use `.items`,
+> `.hasErrors`, `.errors`). This differs from the facade's `render()`, whose
+> `diagnostics` is already a flat `Diagnostic[]`.
+
+The full engine is re-exported from `edododraw` for building your own rendering
+pipeline instead of using the `EdodoDraw` facade:
+
+```ts
+import {
+  compileEdd, applyLayout,
+  SvgRenderer, CameraController, TimelinePlayer,
+  AnnotationLayer, LiveAnnotationController,
+  cameraForBBox, sceneBBox,
+  exportSVGString, exportPNGBlob,
+  registerShape, ensureEngineStyles,
+} from "edododraw";
+```
+
+For example, a minimal custom composition (browser): compile → new `SvgRenderer`
+→ `renderer.render(scene)` → drive a `CameraController` yourself. The `EdodoDraw`
+facade in `src/lib/EdodoDraw.ts` is the reference for how these compose.
+
+---
+
+## 6. Mermaid note
+
+You can embed raw Mermaid inside EDodoDraw source:
+
+```edd
+scene {
+  mermaid """
+  flowchart LR
+    A[Start] --> B{Choice}
+    B -->|yes| C[Do it]
+  """
+}
+```
+
+- The Mermaid engine (`@excalidraw/mermaid-to-excalidraw`) is an **optional
+  dependency, lazy-loaded** via dynamic `import()` on the **first** `mermaid` block
+  rendered — so apps that never use Mermaid don't pay for it (it's heavy).
+- The facade's `render()` extracts `mermaid """ … """` blocks, converts each, and
+  injects the resulting nodes/edges into the scene.
+- **If the package isn't installed**, the lazy import fails; the facade catches it
+  and reports a diagnostic (code `M-PARSE`) for that block. The rest of the diagram
+  still renders — `import { EdodoDraw } from "edododraw"` stays fully functional.
+  Install it explicitly if you need Mermaid: `npm i @excalidraw/mermaid-to-excalidraw`.
+- Mermaid conversion runs in the **browser only** (it renders to a hidden SVG). The
+  pure `compileEdd` path stays synchronous and ignores Mermaid runtime.
+
+Helpers `convertMermaid`, `extractMermaidBlocks`, and `injectMermaid` are also
+exported from `edododraw` if you want to drive the import yourself. See
+[IMPORT_AND_EXPORT_GUIDE.md](IMPORT_AND_EXPORT_GUIDE.md).
+
+---
+
+## 7. SSR / bundler notes
+
+- **The facade needs a DOM.** `new EdodoDraw(el)` and its methods use browser globals
+  — `document`, `window`, `getComputedStyle`, `ResizeObserver`, `requestAnimationFrame`
+  / `cancelAnimationFrame` (camera animation), and `XMLSerializer` (SVG export).
+  Construct and use it in the browser only. In React, create it inside `useEffect`
+  (which is exactly what `EdodoDrawView` does), never during render or on the server.
+- **`compileEdd` is DOM-free.** Use it for server-side validation, computing a scene
+  ahead of time, or CI checks — no browser or jsdom required.
+- **Fonts are self-contained.** The hand-drawn font (Excalifont/Virgil) is embedded
+  as a base64 `@font-face` in the engine's injected CSS and in every exported SVG —
+  **no external font file or CDN is needed**. The live canvas injects this CSS once
+  per document via `ensureEngineStyles()` (the facade calls it automatically on
+  mount). The UI/code fonts (Nunito, Cascadia) are best-effort from `/fonts` with
+  system fallbacks and only matter inside the playground app.
+- **ESM only.** There is no CommonJS build; use `import` (or dynamic `import()`),
+  not `require`. Any modern bundler (Vite, webpack 5, esbuild, Rollup, Next.js)
+  resolves the `edododraw` / `edododraw/react` subpath exports directly.
+- **Tree-shaking + built-in shapes.** Built-in plugin shapes (e.g. `star`) are
+  registered from the renderer on `mount()` (via `registerBuiltinShapes()`), so they
+  survive a tree-shaking library build and are always available once you render.
+  `package.json` also lists the `builtins` files under `sideEffects` for the eager
+  registration path. Your own `registerShape(...)` calls run whenever their module is
+  imported — import that module before you render.
+
+---
+
+## 8. Troubleshooting
+
+| Symptom | Likely cause & fix |
+|---|---|
+| Blank canvas, nothing renders | Container has no height. Give it an explicit size (`height: 500px`); the facade sets position/overflow but never a size. |
+| `document is not defined` / crash on the server | The facade needs a DOM. Only construct `EdodoDraw` in the browser; use `compileEdd` for SSR/Node. |
+| `edd.play()` does nothing | The source has no `timeline { … }` — the player no-ops without steps. Add beats, or drive the camera directly with `focus`/`fit`. |
+| Mermaid block shows an `M-PARSE` diagnostic | `@excalidraw/mermaid-to-excalidraw` isn't installed. Run `npm i @excalidraw/mermaid-to-excalidraw`. |
+| Wheel/scroll is hijacked by the diagram | `interactive: true` binds wheel-zoom with `preventDefault`. Use `interactive: false` for a static embed. |
+| React: changing `interactive`/`grid` prop has no effect | Options are read once at mount; only `source` is reactive. Remount (e.g. change the component `key`). |
+| Live-annotation tools do nothing | Live tools require `interactive: true`. |
+| Camera/timeline "jumps" instead of animating | You called an immediate variant (`fit(false)`), or `autoFit` refit after a `render()`. Use `focus(...)`/`fit(true)` for animated moves. |
+| Old instance leaks / duplicate SVGs after re-mount | Call `edd.destroy()` on teardown (the React wrapper does this for you). |
+
+---
+
+See also: [ARCHITECTURE.md](ARCHITECTURE.md) ·
+[DSL_LANGUAGE_GUIDE.md](DSL_LANGUAGE_GUIDE.md) ·
+[CAMERA_AND_TIMELINE_GUIDE.md](CAMERA_AND_TIMELINE_GUIDE.md) ·
+[ANNOTATIONS_GUIDE.md](ANNOTATIONS_GUIDE.md) ·
+[IMPORT_AND_EXPORT_GUIDE.md](IMPORT_AND_EXPORT_GUIDE.md) ·
+[EXTENDING_GUIDE.md](EXTENDING_GUIDE.md)
+
+==============================================================================
+
+# ═══ Extend & make plugins  (docs/EXTENDING_GUIDE.md) ═══
+
+# Extending EDodoDraw
+
+How to add new capabilities to the engine: custom **shapes**, **animated arrows**,
+**annotation kinds**, **layouts**, and **DSL constructs**. This guide is for people
+working _inside_ the repository (or forking it) — every example is copy-paste
+accurate against the current source.
+
+> New to the codebase? Read [ARCHITECTURE.md](ARCHITECTURE.md) first, then
+> [DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md). To _embed_ EDodoDraw in an
+> app (rather than extend it), see [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md).
+
+---
+
+## 1. The extension philosophy
+
+EDodoDraw is designed to be extended without rewriting the core. Two ideas make
+that possible:
+
+- **The Scene IR is the contract.** Every producer (the DSL compiler, the Mermaid
+  importer, a programmatic caller) emits a `Scene`; the renderer and controllers
+  only consume a `Scene`. See `src/engine/scene/types.ts`. If your extension can be
+  expressed as data on the `Scene`, everything downstream already works.
+- **Open unions + registries.** The presentation-level enums are _open_ string
+  unions: `ShapeKind`, `ArrowheadKind`, `ArrowAnimationKind`, `AnnotationKind`,
+  and `LayoutKind` all end in `| (string & {})` (except `LayoutKind`, whose
+  dispatch has a grid fallback). That means the parser and compiler already accept
+  names they've never seen — an unknown value flows through the pipeline untouched
+  and is _resolved at the last moment_ by a renderer switch or a registry lookup.
+
+The practical consequence: **most extensions need no grammar change.** You add a
+name and teach one switch (or one registry) how to draw it.
+
+There are two flavours of extension:
+
+| Flavour | Mechanism | Needs a repo edit? | Example |
+|---|---|---|---|
+| **Registry** (runtime) | `registerShape(name, fn)` | No — callable from any app | Custom shapes |
+| **Switch** (compile-time) | add a `case` to a `switch` | Yes — you edit engine source | Animations, annotations, layouts |
+
+Shapes are the only fully-runtime seam today; the rest are small, well-isolated
+`switch` additions.
+
+---
+
+## 2. Add a custom shape
+
+Shapes resolve through a **plugin registry** (`src/engine/plugins/registry.ts`).
+You register a function under a name; the renderer calls it whenever a node's
+`shape` matches. No grammar change is needed — `mapShape()` in
+`src/engine/dsl/lower.ts` returns any unknown shape name as-is, and
+`renderShapeBody()` (`src/engine/render/shapes.ts`) falls back to the registry in
+its `default:` case:
+
+```ts
+// src/engine/render/shapes.ts (default branch of renderShapeBody)
+default: {
+  const plugin = getShapePlugin(shape);
+  if (plugin) return plugin(rc, rect, style);
+  // unknown shape -> rounded rectangle so nothing silently disappears
+}
+```
+
+### The plugin contract
+
+```ts
+export type ShapePluginFn = (rc: RoughSVG, rect: ShapeRect, style: NodeStyle) => SVGGElement;
+```
+
+- **`rc`** — a rough.js SVG generator (`ReturnType<typeof rough.svg>`). Use
+  `rc.polygon`, `rc.path`, `rc.ellipse`, `rc.rectangle`, `rc.circle`, `rc.line`,
+  `rc.linearPath`, `rc.curve` — each returns an `SVGGElement` (or `SVGPathElement`)
+  you append.
+- **`rect`** — the node box as **top-left `x`/`y` plus `w`/`h`** (`ShapeRect`), in
+  world coordinates. There is no separate transform: draw directly at these
+  absolute coordinates. The centre is `(rect.x + rect.w/2, rect.y + rect.h/2)`.
+- **`style`** — the node's resolved `NodeStyle` (stroke, fill, `fillStyle`,
+  `strokeWidth`, `roughness`, `seed`, `fontSize`, …).
+- **Return** a single `<g>` (`SVGGElement`). **Do not draw the label** — the
+  renderer overlays text itself after calling you.
+
+`nodeRoughOptions(style, filled)` (exported from `src/engine/render/shapes.ts`)
+maps a `NodeStyle` onto rough.js `Options` (stroke/fill/roughness/seed, dashes,
+hachure gap). Pass `filled = true` for closed bodies so the node's fill and
+`fillStyle` are honoured; `false` for stroke-only accents. Using it keeps the
+deterministic `seed` (so re-renders don't re-jitter) and the hand-drawn look
+consistent with the built-ins.
+
+### Worked example — a "gauge" shape (add to the builtins)
+
+The canonical place to register in-repo shapes is
+`src/engine/plugins/builtins.ts` (the `star` example already lives there). Add your
+shape inside the exported `registerBuiltinShapes()` function — the renderer calls it
+on `mount()` (and it is called eagerly on import), so built-ins survive a
+tree-shaking library build and are always available once you render. Add:
+
+```ts
+// src/engine/plugins/builtins.ts — add this call INSIDE registerBuiltinShapes()
+// (so it survives the tree-shaking library build, like the star above).
+// `nodeRoughOptions` and `registerShape` are already imported in that file.
+
+// A half-circle gauge with a needle — great for "health"/"load" nodes.
+registerShape("gauge", (rc, rect, style) => {
+  const g = document.createElementNS("http://www.w3.org/2000/svg", "g") as SVGGElement;
+  const cx = rect.x + rect.w / 2;
+  const cy = rect.y + rect.h * 0.72;           // dial sits low in the box
+  const r = Math.min(rect.w, rect.h * 1.4) / 2;
+
+  // The dial arc (semicircle), stroke-only.
+  const arc = `M${cx - r},${cy} A${r},${r} 0 0 1 ${cx + r},${cy}`;
+  g.appendChild(rc.path(arc, nodeRoughOptions(style, false)));
+
+  // Filled body under the arc so fill/fillStyle read through.
+  const body = `M${cx - r},${cy} A${r},${r} 0 0 1 ${cx + r},${cy} Z`;
+  g.appendChild(rc.path(body, nodeRoughOptions(style, true)));
+
+  // The needle, pointing ~70% of the way across the dial.
+  const angle = Math.PI - Math.PI * 0.7;
+  g.appendChild(rc.line(cx, cy, cx + Math.cos(angle) * r * 0.9, cy - Math.sin(angle) * r * 0.9, {
+    stroke: style.stroke,
+    strokeWidth: style.strokeWidth + 0.6,
+    roughness: Math.min(style.roughness, 1),
+    seed: style.seed,
+  }));
+  return g;
+});
+```
+
+### Using it from the DSL
+
+No grammar change — three equivalent ways to reach a registered shape:
+
+```edd
+scene {
+  g1[CPU] { shape: gauge }     // via the `shape:` attribute
+  node g2 "Memory" as gauge    // via the explicit `as <name>` form
+}
+```
+
+Both compile to a node whose `shape` is `"gauge"`, which the renderer resolves via
+`getShapePlugin("gauge")`. (Verified: `g[Gauge] { shape: gauge }` compiles to a
+node with `shape === "gauge"`, and `node x as gauge` likewise.)
+
+To also expose a **short keyword** (so `gauge g1 "CPU"` works as a shape-led node),
+add the word to two internal tables:
+
+1. `SHAPE_KEYWORDS` in `src/engine/dsl/tokens.ts` — so the parser treats
+   `gauge <id>` as a keyword-led node (see `parseKeywordNode` in `parser.ts`).
+2. `SHAPE_MAP` in `src/engine/dsl/lower.ts` — map `gauge: "gauge"` (only needed if
+   the surface word differs from the registered name; identical names pass through
+   `mapShape` unchanged).
+
+### Registering from _outside_ the repo (runtime)
+
+`registerShape` is part of the public package export, so an embedding app can add a
+shape at runtime with no fork:
+
+```ts
+import { registerShape, EdodoDraw } from "edododraw";
+
+// nodeRoughOptions is engine-internal (not re-exported), so build rough options
+// inline from the NodeStyle you're handed:
+registerShape("gauge", (rc, rect, style) => {
+  const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  const opts = {
+    stroke: style.stroke,
+    strokeWidth: style.strokeWidth,
+    roughness: style.roughness,
+    seed: style.seed,
+    fill: style.fill ?? undefined,
+    fillStyle: style.fillStyle,
+  };
+  const cx = rect.x + rect.w / 2, cy = rect.y + rect.h / 2, r = Math.min(rect.w, rect.h) / 2;
+  g.appendChild(rc.circle(cx, cy, r * 2, opts));
+  return g;
+});
+
+const edd = new EdodoDraw(document.getElementById("app")!);
+await edd.render(`scene { s[Sensor] { shape: gauge } }`);
+```
+
+Register **before** you call `render()` so the plugin is present when the scene
+paints.
+
+---
+
+## 3. Add an animated arrow
+
+An edge draws a hand-drawn base stroke, arrowheads, and (optionally) a clean
+**overlay `<path>`** that carries a CSS animation along the exact same centerline.
+Adding a new animation kind is **exactly three edits** plus (optionally) widening
+the type union. We'll add a kind called `surge` (a fast, short dash sweep).
+
+**Edit 1 — the overlay case** in `animationOverlay()`
+(`src/engine/render/edges.ts`). This configures the SVG path for the new kind; the
+element already has class `edd-anim edd-anim-surge`, and `--edd-len` / `--edd-speed`
+CSS variables are set for you:
+
+```ts
+// src/engine/render/edges.ts — inside animationOverlay's switch (kind)
+case "surge": {
+  p.setAttribute("stroke", stroke);
+  p.setAttribute("stroke-width", String(sw * 1.5));
+  p.setAttribute("stroke-linecap", "round");
+  p.setAttribute("stroke-dasharray", "4 14");
+  style.animationDuration = `${0.7 / speed}s`;
+  break;
+}
+```
+
+**Edit 2 — the keyframe + class** in `src/engine/render/theme.css.ts` (the `CSS`
+string). The class name must be `edd-anim-<kind>` to match the attribute the
+overlay sets:
+
+```css
+@keyframes edd-surge {
+  to { stroke-dashoffset: -18; }
+}
+.edd-anim-surge {
+  animation-name: edd-surge;
+  animation-timing-function: ease-in;
+  animation-iteration-count: infinite;
+}
+```
+
+`.edd-anim-surge` is already covered by the blanket `.edd-anim` selector in the
+`prefers-reduced-motion` block at the end of the CSS, so motion-sensitive users
+are handled automatically — no extra edit needed there.
+
+**Edit 3 — accept the name in the compiler.** In `mapAnimation()`
+(`src/engine/dsl/lower.ts`), add `surge` to the `known` set so the DSL keeps it
+instead of falling back to `flow`:
+
+```ts
+const known = new Set([
+  "none", "flow", "dash-march", "draw-on", "pulse", "comet",
+  "gradient-flow", "electric", "glow", "caravan", "wiggle",
+  "surge",  // <-- new
+]);
+```
+
+**Optional — widen the type.** Add `| "surge"` to the `ArrowAnimationKind` union in
+`src/engine/scene/types.ts`. The union is open (`| (string & {})`), so this is only
+for editor autocomplete and exhaustiveness, not correctness.
+
+### Using it
+
+```edd
+scene {
+  a[Client] ~> b[Server] { animate: surge }
+  a -> b { animation: surge { speed: 1.6 } }
+}
+```
+
+Both `animate:` and `animation:` are accepted (see `buildEdgeStyle` in
+`compile.ts`); the `{ speed: N }` styled form sets `animationSpeed`, which your
+`animationDuration` divides by. The `~>` glyph is a convenient default that already
+sets `animation: flow` + curved routing — override with the trailing block.
+
+---
+
+## 4. Add an annotation kind
+
+Annotations (scripted _and_ live) are `Annotation` records rendered by
+`AnnotationLayer.draw()` (`src/engine/annotate/layer.ts`). The `kind` field is an
+open union, so adding one is a single `case` plus a private draw method. We'll add
+`cross` (a big hand-drawn X over an element — distinct from `strike`, which is one
+horizontal line).
+
+**Edit 1 — the `draw` switch** in `AnnotationLayer` (`layer.ts`). `box` is the
+target's world bounding box (already resolved for you from `an.target`):
+
+```ts
+// src/engine/annotate/layer.ts — inside draw()'s switch (an.kind)
+case "cross":
+  if (box) this.drawCross(g, box, an);
+  break;
+```
+
+**Edit 2 — the draw method** (same file), using rough.js with a stable `seed` so it
+doesn't re-jitter:
+
+```ts
+private drawCross(g: SVGGElement, box: BBox, an: Annotation): void {
+  const color = an.color || "#e03131";
+  const opts = { stroke: color, strokeWidth: 3, roughness: 1.6, seed: 33 };
+  g.appendChild(this.rc.line(box.minX, box.minY, box.maxX, box.maxY, opts));
+  g.appendChild(this.rc.line(box.minX, box.maxY, box.maxX, box.minY, opts));
+  if (an.text) this.label(g, an.text, { x: box.minX, y: box.minY - 8 }, color, "start");
+}
+```
+
+That's enough to use it from a scripted `annotate { … }` block — `parseAnnotationCmd`
+reads any leading ident as the `kind`, so no parser change is required:
+
+```edd
+scene { a[Deprecated] }
+annotate {
+  cross a { color: red }
+}
+```
+
+> Note: to use a **bare** annotation command inside a `timeline` beat or a
+> `stagger { … }` block (e.g. `beat { cross a }`), also add `"cross"` to the
+> `ANNOT_KINDS` set at the bottom of `src/engine/dsl/parser.ts` — that set gates
+> which idents are recognised as annotation verbs in beat context. Top-level
+> `annotate { … }` blocks don't consult it.
+
+### Optional — a live tool
+
+To let users draw it interactively, teach `LiveAnnotationController`
+(`src/engine/annotate/interact.ts`):
+
+1. **Widen the `Tool` union:** `export type Tool = "select" | … | "cross";`
+2. **Add a default** to the `DEFAULTS` map — the element-anchored tool path in
+   `pointerDown()` reads it (click an element → annotation created):
+   ```ts
+   const DEFAULTS = {
+     // …existing…
+     cross: { kind: "cross", color: "#e03131", options: {} },
+   };
+   ```
+3. **(Optional) commit-to-code:** add a `case "cross"` to `serialize()` so
+   `annotationsToCode()` round-trips it back to DSL.
+4. **Add a toolbar button** in the playground: `src/app/App.tsx`, the `TOOLS`
+   array — `{ tool: "cross", icon: "✕", label: "Cross out element" }`.
+
+The live layer already handles selection, undo/redo, and camera tracking generically,
+so those come for free.
+
+---
+
+## 5. Add a layout
+
+Auto-layout assigns world positions to non-pinned nodes based on
+`scene.meta.layout` (a `LayoutKind`). See `src/engine/layout/index.ts`. Adding a
+mode is three edits; we'll add `column` (a single vertical stack).
+
+**Edit 1 — the algorithm.** New file `src/engine/layout/column.ts`, mutating each
+node's top-left `x`/`y` in place (mirror the shape of `grid.ts`/`radial.ts`):
+
+```ts
+// src/engine/layout/column.ts
+import type { SceneNode } from "../scene/types.js";
+
+/** Stack nodes in one centred vertical column, top to bottom. */
+export function layoutColumn(nodes: SceneNode[], gap: number): void {
+  let y = 0;
+  for (const n of nodes) {
+    n.x = -n.w / 2;   // centre each node on x = 0
+    n.y = y;
+    y += n.h + gap;
+  }
+}
+```
+
+**Edit 2 — the dispatch** in `runLayout()` (`layout/index.ts`). Any unknown kind
+already falls back to grid, so this just makes `column` explicit:
+
+```ts
+import { layoutColumn } from "./column.js";
+// …
+switch (kind) {
+  // …existing cases…
+  case "column":
+    layoutColumn(movable, gridGap(scene));
+    return;
+}
+```
+
+**Edit 3 — the type + DSL mapping.**
+
+- Add `"column"` to the `LayoutKind` union in `src/engine/scene/types.ts`.
+- Map the DSL keyword in `resolveLayoutKind()` (`src/engine/dsl/compile.ts`) — this
+  is where `layout <word>` is translated to a `LayoutKind`:
+  ```ts
+  const map: Record<string, LayoutKind> = {
+    dag: "dag", tree: "dag", flow: "dag", force: "dag",
+    grid: "grid", radial: "radial", free: "manual", manual: "manual",
+    column: "column",  // <-- new
+  };
+  ```
+
+### How a layout is chosen
+
+`resolveLayoutKind()` runs at compile time: an explicit `layout <kind>` maps through
+the table above; with no `layout` statement, the compiler defaults to `"dag"` when
+any node is unpinned, else `"manual"`. `applyLayout(scene)` then reads
+`scene.meta.layout` and dispatches. Cross-cutting rules that come for free:
+`pinned` nodes are never moved, the function never throws (falls back to grid), and
+the final result is normalised so the bounding box starts near `(40, 40)`.
+
+### Using it
+
+```edd
+scene {
+  layout column
+  a[One] --> b[Two] --> c[Three]
+}
+```
+
+---
+
+## 6. Add a DSL construct
+
+The DSL is a hand-written recursive-descent parser (`src/engine/dsl/parser.ts`)
+lowered to Scene IR by the compiler (`src/engine/dsl/compile.ts`). Grammar changes
+touch three files — know where each concern lives:
+
+| File | Responsibility | Where to hook in |
+|---|---|---|
+| `dsl/ast.ts` | AST node types | Add your statement's interface + to the relevant union (`TopStmt`, `SceneStmt`, `BeatItem`, …). |
+| `dsl/parser.ts` | tokens → AST | Add a keyword case to `parseTop()` (top level) or `parseSceneStmt()` (inside `scene { }`); write a `parseX()` that returns your AST node. |
+| `dsl/compile.ts` | AST → Scene IR | Handle your node in `compileProgram`'s top-level loop or in `walk()` (scene statements), writing onto the `Scene`. |
+| `dsl/lower.ts` | enum/glyph → IR value tables | Add any surface-word → IR-value mapping here (e.g. new shape/animation/routing names). |
+
+Concretely:
+
+- **A new node/edge attribute** (e.g. `blur: 4`) is the smallest change: no parser
+  edit at all. Attributes are parsed generically by `parseAttrEntry`, so you only add
+  a `case "blur":` to `buildNodeStyle` (or `buildEdgeStyle`) in `compile.ts` and a
+  field to `NodeStyle`/`EdgeStyle` in `scene/types.ts` (then honour it in the
+  renderer). This is the recommended path for most "new knob" requests.
+- **A new top-level keyword** (e.g. `legend { … }`): add `case "legend": return
+  this.parseLegend();` to `parseTop()`, define `parseLegend()` (use
+  `parseAttrBlock()` / `skipBlock()` helpers), add the AST type, and consume it in
+  `compileProgram`'s statement loop. Note `parseTop` already _tolerates_ unknown
+  top-level keywords like `plugin`/`define` by skipping their block — a good template
+  for "parse but ignore for now."
+- **A new scene-level statement** (e.g. `ruler …`): add a `case` to
+  `parseSceneStmt()`'s keyword switch and handle it in `walk()`.
+
+Keep the parser **permissive and recoverable**: report problems via
+`this.error(code, msg, token, …)` (which pushes a `Diagnostic`) and call
+`recoverStmt()` / `skipBlock()` rather than throwing. The compiler accumulates
+`Diagnostic`s and always returns a best-effort `Scene` — see
+[DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md) ("Diagnostics, not
+exceptions").
+
+For the full user-facing grammar, see
+[DSL_LANGUAGE_GUIDE.md](DSL_LANGUAGE_GUIDE.md).
+
+---
+
+## 7. Testing your extension
+
+Follow the two-stage rule from [DEVELOPMENT_STANDARDS.md](DEVELOPMENT_STANDARDS.md).
+
+**Stage 1 — code-level (fast, Node/jsdom).** The compiler is synchronous and
+DOM-free, so most extensions are unit-testable without a browser. Add a spec under
+`tests/` (vitest) and run:
+
+```bash
+npm test          # vitest run
+npm run typecheck  # tsc -b --noEmit
+```
+
+A shape/animation/annotation test typically compiles a snippet and asserts on the
+resulting `Scene`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { compileEdd } from "../src/engine/dsl/index.js";
+
+describe("gauge shape", () => {
+  it("passes an unknown shape name through unchanged", () => {
+    const { scene } = compileEdd(`scene { g[CPU] { shape: gauge } }`);
+    expect(scene.nodes[0].shape).toBe("gauge");
+  });
+});
+
+describe("surge animation", () => {
+  it("keeps a registered animation kind", () => {
+    const { scene } = compileEdd(`scene { a -> b { animate: surge } }`);
+    expect(scene.edges[0].style.animation).toBe("surge");
+  });
+});
+```
+
+Existing suites to mirror: `tests/parser.test.ts`, `tests/lowering.test.ts`,
+`tests/layout.test.ts`, `tests/annotations.test.ts`.
+
+**Stage 2 — end-user visual check.** A green unit test does not prove the
+hand-drawn render is correct. Run the app and drive it with `playwright-cli`, then
+**read the screenshots**:
+
+```bash
+npm run dev                 # dev server (see DEVELOPMENT_STANDARDS.md)
+scripts/qa/smoke.sh         # loads every example, screenshots, fails on console errors
+```
+
+Add an example that exercises your extension (an `.edd` file wired into the
+playground's example list) so the smoke test covers it, and confirm no
+per-element render warnings appear in the console — the renderer wraps each
+node/edge so one bad element can't blank the diagram, but it _will_ log a warning
+you should catch.
+
+==============================================================================
+
+# ═══ Architecture  (docs/ARCHITECTURE.md) ═══
+
+# EDodoDraw Architecture
+
+EDodoDraw is a **100% code-to-diagram engine** with the Excalidraw hand-drawn aesthetic, a magic-move camera, and scriptable + real-time annotations. It is built from the ground up (no Excalidraw runtime) on three reused primitives: **rough.js** (hand-drawn strokes), **dagre** (auto-layout), and **@excalidraw/mermaid-to-excalidraw** (Mermaid import). The hand-drawn font is the OFL-licensed **Virgil/Excalifont**.
+
+## The pipeline
+
+```mermaid
+flowchart LR
+  src["EDodoDraw code (.edd)"] --> lex[Lexer]
+  lex --> parse[Parser → AST]
+  parse --> compile[Compiler]
+  compile --> scene["Scene IR"]
+  merm["mermaid ' … '"] -. import .-> scene
+  scene --> layout["Layout (dagre/grid/radial)"]
+  layout --> render["SVG Renderer (rough.js)"]
+  render --> cam[Camera controller]
+  render --> anno[Annotation layer]
+  render --> tl[Timeline player]
+```
+
+Everything flows through the **Scene IR** (`src/engine/scene/types.ts`) — a flat, serializable model of nodes, edges, groups, annotations, and timeline steps. The DSL, the Mermaid importer, and any programmatic caller all produce a `Scene`; the renderer and controllers only consume one. This is the single contract that keeps the system decoupled.
+
+## Modules
+
+| Area | Path | Responsibility | Guide |
+|---|---|---|---|
+| Scene IR | `src/engine/scene/` | Types, palette, factories, anchors, queries | — |
+| DSL | `src/engine/dsl/` | `lexer → parser → ast → compile` + diagnostics | [DSL_LANGUAGE_GUIDE](DSL_LANGUAGE_GUIDE.md) |
+| Layout | `src/engine/layout/` | dagre/grid/radial → node positions | — |
+| Renderer | `src/engine/render/` | SVG + rough.js, shapes, edges, arrowheads, fonts | — |
+| Camera | `src/engine/camera/` | fit math, easing, animated controller | [CAMERA_AND_TIMELINE_GUIDE](CAMERA_AND_TIMELINE_GUIDE.md) |
+| Timeline | `src/engine/timeline/` | beat player (magic-move) | [CAMERA_AND_TIMELINE_GUIDE](CAMERA_AND_TIMELINE_GUIDE.md) |
+| Annotations | `src/engine/annotate/` | render layer + live interactive editor | [ANNOTATIONS_GUIDE](ANNOTATIONS_GUIDE.md) |
+| Import/Export | `src/engine/import/`, `src/engine/export.ts` | Mermaid in; SVG/PNG/JSON out | [IMPORT_AND_EXPORT_GUIDE](IMPORT_AND_EXPORT_GUIDE.md) |
+| Plugins | `src/engine/plugins/` | shape registry (extension seam) | [DEVELOPMENT_STANDARDS](DEVELOPMENT_STANDARDS.md) |
+| App | `src/app/` | React playground: editor, canvas, toolbar, player | [DEVELOPMENT_STANDARDS](DEVELOPMENT_STANDARDS.md) |
+
+`src/engine/index.ts` is the public barrel; the app imports only from `@engine/*`.
+
+## Key decisions
+
+- **SVG, not Canvas.** The world layer is one `<g>` whose `transform` attribute is the camera. This makes the magic-move camera a single attribute update per frame, GPU-friendly, and lets annotations/animated arrows be DOM elements with CSS animations. Trade-off: not ideal for tens of thousands of elements — fine for diagrams.
+- **Imperative renderer outside React.** `SvgRenderer` owns the SVG DOM directly (like Excalidraw owns its canvas). React only mounts the container and drives high-level state. Full re-render on scene change; camera/animation mutate transforms only.
+- **Deterministic hand-drawn strokes.** Every element gets a stable rough.js `seed` (hash of its id) so re-rendering never re-jitters strokes.
+- **Open unions + registries.** `ShapeKind`, `ArrowAnimationKind`, and `AnnotationKind` are open string unions; unknown values resolve through registries (`src/engine/plugins/`). New shapes/animations need no grammar or core change.
+- **Sync compiler, async Mermaid.** The DSL compiler is synchronous and DOM-free (unit-testable in Node). Mermaid rendering needs the browser, so the app awaits `convertMermaid` and injects the fragment — the compiler itself stays pure.
+
+## Rendering layers (bottom → top)
+
+`bg (screen)` · `grid` · `groups` · `edges` · `nodes` · `annotations` (scripted) · `live` (interactive) — the last two sit in the camera-transformed world layer so annotations track the diagram. See `src/engine/render/svgRenderer.ts`.
+
+## Testing
+
+- Unit tests (vitest, jsdom): `tests/` — lexer, parser, compiler, lowering, layout, camera math, anchors, annotations round-trip. Run `npm test`.
+- Visual smoke: `scripts/qa/smoke.sh` drives every example with `playwright-cli` and fails on console errors. Two-stage testing per `docs`-referenced FE guide: code-level first, end-user browser interaction last.
+
+==============================================================================
+
+# ═══ Development standards  (docs/DEVELOPMENT_STANDARDS.md) ═══
+
+# Development Standards
+
+## Setup
+
+```bash
+npm install
+npm run dev        # http://localhost:5273
+npm test           # vitest
+npm run typecheck  # tsc -b --noEmit
+npm run build      # tsc + vite build → dist/
+```
+
+Node ≥ 18 (matches `engines`). The `reference/` directory (Excalidraw + mermaid-to-excalidraw clones, studied during design) is gitignored and excluded from Vite (`vite.config.ts → optimizeDeps.entries` + `server.watch.ignored`).
+
+## Project structure
+
+```
+src/
+  engine/            framework-agnostic engine (no React)
+    scene/           Scene IR: types, palette, defaults, anchors, query
+    dsl/             lexer, tokens, ast, parser, lower, compile, diagnostics
+    layout/          dagre / grid / radial → node positions
+    render/          svgRenderer, shapes, edges, theme.css, fonts
+    camera/          fit math, easing, controller
+    timeline/        beat player
+    annotate/        layer (render) + interact (live editor)
+    import/          mermaid adapter
+    plugins/         registry + builtins
+    export.ts        SVG / PNG / JSON
+    index.ts         public barrel (import from "@engine/…")
+  app/               React playground (App, CanvasView, examples)
+examples/            *.edd sample programs (imported ?raw)
+docs/                this documentation
+tests/               vitest suites
+scripts/qa/          playwright-cli smoke test
+public/fonts/        OFL hand-drawn fonts (Virgil, Excalifont)
+```
+
+The engine is pure TypeScript with no React dependency; the app is a thin shell over it. Import engine code via the `@engine/*` alias with `.js` extensions (bundler resolution maps to `.ts`).
+
+## Conventions
+
+- **Scene IR is the contract.** Anything that produces diagrams emits a `Scene`; anything that draws consumes one. Don't reach around it.
+- **Deterministic seeds.** Element factories (`makeNode`/`makeEdge`) assign a rough.js seed from the id hash. Preserve that when adding element kinds.
+- **Never throw in the lexer/renderer per-element.** The lexer is permissive; the renderer wraps each node/edge so one bad element can't blank the diagram.
+- **Diagnostics, not exceptions.** The compiler accumulates `Diagnostic`s and recovers at statement/block boundaries.
+
+## Extending the engine
+
+### Add a shape
+
+Register a renderer — no grammar change needed (the DSL already accepts any shape name):
+
+```ts
+import { registerShape } from "@engine/index.js";
+import { nodeRoughOptions } from "@engine/render/shapes.js";
+
+registerShape("hexstar", (rc, rect, style) => {
+  const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  g.appendChild(rc.polygon(myPoints(rect), nodeRoughOptions(style, true)));
+  return g;
+});
+```
+
+Then `shape: hexstar` (or a keyword mapped in `src/engine/dsl/lower.ts → SHAPE_MAP`) works. See `src/engine/plugins/builtins.ts` for the built-in `star`.
+
+### Add an animated arrow
+
+Add a `case` in `animationOverlay` (`src/engine/render/edges.ts`) and a keyframe in `src/engine/render/theme.css.ts`, then list it in `mapAnimation` (`src/engine/dsl/lower.ts`).
+
+### Add an annotation kind
+
+Add a `case` in `AnnotationLayer.draw` (`src/engine/annotate/layer.ts`) and, for live editing, a tool in `LiveAnnotationController` (`src/engine/annotate/interact.ts`) + the toolbar in `src/app/App.tsx`.
+
+### Add a DSL construct
+
+Grammar-level changes live in `src/engine/dsl/parser.ts` (recursive descent, keyword-dispatched) and are lowered to Scene IR in `src/engine/dsl/compile.ts`. Add tests in `tests/parser.test.ts`.
+
+## Testing standard
+
+Two stages (mandatory for anything user-facing):
+
+1. **Code-level** — `npm test` (vitest) + `npm run typecheck`.
+2. **End-user** — drive the running app with `playwright-cli` (`scripts/qa/smoke.sh`), screenshot every state, and **read every screenshot**. A route returning the right JSON does not prove the hand-drawn render is correct.
+
+==============================================================================
+
+# ▸ Runnable examples (examples/*.edd)
+
+Each is a complete EDodoDraw program. Paste any into the playground
+(https://vivmagarwal.github.io/edododraw/#/playground) or compile it with `compileEdd(source)`.
+
+## examples/animated-arrows.edd
+
+```edd
+edd 1.0
+meta { title: "Animated Arrow Gallery" }
+
+// EDodoDraw ships far more animated connectors than Excalidraw.
+scene {
+  layout dag { direction: right, gap: 120 }
+
+  circle a "A" { fill: blue }
+  circle b "B" { fill: green }
+
+  a -> b "flow"          { animate: flow }
+  a -> b "dash-march"    { animate: dash-march }
+  a -> b "draw-on"       { animate: draw-on }
+  a -> b "comet"         { animate: comet, color: red }
+  a -> b "gradient-flow" { animate: gradient-flow }
+  a -> b "electric"      { animate: electric, color: violet }
+  a -> b "pulse"         { animate: pulse }
+}
+```
+
+## examples/architecture.edd
+
+```edd
+edd 1.0
+meta { title: "WebShop Reference Architecture" }
+
+theme light {
+  tokens { $accent: #2563eb, $muted: #9ca3af, $danger: #e03131 }
+}
+
+style .card     { shape: round-rect, fill: blue }
+style .critical { stroke: $danger, strokeWidth: bold }
+
+defaults {
+  edge { endArrow: arrow }
+}
+
+scene {
+  use theme light
+  layout dag { direction: down, gap: 64, rankGap: 110 }
+
+  actor  client "User"
+  cloud  cdn    "CDN / Edge"       { fill: cyan }
+  hexagon gw    "API Gateway"      { fill: violet, strokeWidth: bold }
+
+  group services "Application Services" {
+    round-rect auth   "Auth Service"  :::card
+    round-rect api    "API Service"   :::card :::critical
+    subroutine worker "Async Worker"
+  }
+
+  group data "Data Layer" {
+    cylinder      db    "Postgres"       { fill: teal }
+    cylinder      cache "Redis"          { fill: red }
+    parallelogram queue "Message Queue"  { fill: orange }
+  }
+
+  note legacy "Legacy Billing\n(deprecate)" { at: (760, 40), pin: true, strokeStyle: dashed }
+
+  // Arrowhead + animation variety
+  client  -> cdn    "https"
+  cdn     ==> gw    "cache miss"   { color: $accent }
+  gw      -> auth   "authZ"        { startArrow: dot }
+  gw      -> api    "REST"         { animate: dash-march }
+  api     ~> worker "enqueue"      { animate: flow }
+  api     -> db     "write"        { endArrow: triangle, animate: draw-on }
+  api     -.-> cache "read-through"
+  worker  -> queue  "publish"      { animate: comet, color: $accent }
+  queue   -> db     "persist"
+  api     -x legacy "deprecated"   { color: $muted, strokeStyle: dashed }
+}
+
+annotate "persistent" {
+  callout db "source of truth" { placement: bottom }
+}
+
+timeline story {
+  beat overview "The whole system" {
+    camera fit-all over 800ms
+    reveal { show all with fade-in }
+    narrate: "End-to-end request path."
+  }
+
+  beat ingress "Traffic enters at the edge" {
+    camera focus [client, cdn, gw] zoom 1.5 ease spring
+    annotate {
+      point-at gw "single entry point" { from: ne, color: $accent }
+      highlight cdn { color: yellow }
+    }
+  }
+
+  beat services "Inside the app tier" {
+    camera focus services zoom 1.6
+    annotate {
+      spotlight services { dim: 0.72 }
+      underline api "the hot path" { color: $accent }
+    }
+    narrate: "Auth fronts the API; the worker drains async jobs."
+  }
+
+  beat data "Where state lives" {
+    camera focus data zoom 1.7 ease ease-in-out
+    annotate {
+      callout db "primary of record" { placement: right }
+      circle-mark queue "retry here"
+    }
+    narrate: "All writes funnel through Postgres; Redis is read-through."
+    hold: 2s
+  }
+}
+```
+
+## examples/flowchart.edd
+
+```edd
+edd 1.0
+meta { title: "Signup Flow" }
+
+scene {
+  layout dag { direction: down, gap: 60 }
+
+  start([Start])
+  form[Signup Form]
+  valid{Valid?}
+  ok(Create Account):::good
+  err(Show Errors):::bad
+
+  start --> form
+  form  --> valid
+  valid -->|yes| ok
+  valid -->|no|  err
+  err   --> form
+}
+
+style .good { stroke: green, fill: green }
+style .bad  { stroke: red,   fill: red }
+```
+
+## examples/mermaid-import.edd
+
+```edd
+edd 1.0
+meta { title: "Imported from Mermaid" }
+
+// Paste raw Mermaid — EDodoDraw imports it, keeps the node ids,
+// and lets you choreograph a walkthrough on top.
+mermaid """
+flowchart LR
+  app[App Servers] --> otel[OTel Collector]
+  otel --> prom[Prometheus]
+  otel --> loki[Loki]
+  prom --> grafana[Grafana]
+  loki --> grafana
+  prom --> alertmgr[Alertmanager]
+"""
+
+timeline walkthrough {
+  beat all "Pipeline overview" {
+    camera fit-all over 700ms
+    narrate: "Telemetry flows left to right into Grafana."
+  }
+  beat collect "Collection" {
+    camera focus [app, otel] zoom 1.7
+    annotate {
+      highlight otel { color: yellow }
+      point-at otel "single ingestion point" { from: s }
+    }
+  }
+  beat visualize "Dashboards & alerts" {
+    camera focus [grafana, alertmgr] zoom 1.6
+    annotate {
+      circle-mark grafana "the pane of glass"
+      callout alertmgr "pages on-call" { placement: top }
+    }
+  }
+}
+```
+
+## examples/welcome.edd
+
+```edd
+edd 1.0
+meta { title: "Welcome to EDodoDraw" }
+
+// Everything you see is generated from THIS code.
+// Edit anything on the left and the diagram updates live.
+
+scene {
+  layout dag { direction: down, gap: 72 }
+
+  ellipse     hello "Hello 👋"                 { fill: yellow }
+  rect        idea  "Diagrams as CODE"         { fill: blue }
+  round-rect  vibe  "…with the Excalidraw vibe" { fill: green }
+  diamond     edit  "Try editing me!"          { fill: violet }
+
+  hello --> idea   "type"
+  idea  --> vibe   "render"
+  vibe  --> edit   "enjoy"
+  edit  ~> hello   "loop"        // ~>  == a flowing animated arrow
+}
+```
+