@zuilib/text-editor 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog — @zuilib/text-editor
 
+## 0.5.0
+
+**Diagram builder rewrite.** The drawing canvas, its payload format and the
+authoring story for LLMs were rebuilt.
+
+- **Format v2 (breaking)**: ` ```drawing ` payloads are now
+  `{"version":2,"canvasHeight":<px>,"canvasWidth"?:<px>,"width"?:"content","shapes":[...]}`.
+  No migration from version 1 and no legacy spellings: anything that is
+  not a version 2 payload renders as an empty canvas.
+  `canvasWidth` is optional: when set the drawing scales to fit narrower
+  layouts (SVG viewBox), when absent the canvas is fluid. `triangle` and
+  `pentagon` are removed. `DRAWING_DATA_JSON_SCHEMA` and
+  `DRAWING_FORMAT.md` rewritten for v2
+- **Shapes**: boxes `rect`, `ellipse`, `diamond`, `note` (sticky note with
+  a folded corner, default fill `#ffec99`), `cylinder` (database), `cloud`,
+  `queue` (horizontal cylinder), `actor` (stick figure with a name under
+  it, `text` slot only); connectors `arrow`, `line`; free `text`. Palette
+  gains purple (`#7048e8` / `#d0bfff`)
+- **Bindings** are objects: `{ id, fixedPoint?: [fx, fy], mode?: "orbit" |
+  "inside" }`. `fixedPoint` is a ratio in the box's bounding box; omitted,
+  the endpoint auto-aims from the box center at the other end. `orbit`
+  (default) projects the endpoint onto the outline with a 6px gap,
+  `inside` pins it exactly. The `side: "top" | "right" | "bottom" |
+  "left"` shorthand exists only in the ` ```diagram ` skeleton
+- **Router**: `routing: "elbow"` is auto-routed. It leaves the box
+  perpendicular to the attach side, avoids every box on the canvas and
+  minimises bends. `elbow` (0 to 1) remains as an override of the middle
+  segment when the path is a simple three-segment Z; `waypoints` still
+  take precedence
+- **Editor UX**: multi-select (shift-click, marquee on empty canvas; move,
+  delete and recolor together), redesigned toolbar with a "more shapes"
+  popover, contextual property bar, smoother drag and selection visuals,
+  **Copy as Mermaid** button
+- **` ```diagram ` skeleton**: a fenced block with a coordinate-free JSON
+  skeleton (`boxes`, `connectors`, `texts`, `direction`, palette `color`
+  names) that the editor auto-lays out and expands into a ` ```drawing `
+  block on import (one-way). New exports `expandSkeleton`,
+  `parseDrawingSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`, `DIAGRAM`
+  transformer, types `DrawingSkeleton`, `SkeletonBox`, `SkeletonConnector`
+- **Mermaid export**: `drawingToMermaid(data, { direction? })` returns a
+  `flowchart` with one node per box (shape-specific node syntax), edges for
+  connectors bound at both ends (labels as `|text|`), `style` lines for
+  coloured boxes and free text as `%% note:` comments
+- Internal: the drawing code moved from `src/components/` into
+  `src/drawing/` (`types.ts`, `schema.ts`, `geometry.ts`, `mermaid.ts`,
+  `shapes/`, `canvas/`); shape geometry is data-driven so the router,
+  bindings, skeleton expansion and exporters run without a DOM
+
 ## 0.4.0
 
 - **Table density**, Slab-style: the floating table toolbar (caret in a

package/DRAWING_FORMAT.md

@@ -1,43 +1,59 @@
-# The `drawing` block format
+# The `drawing` and `diagram` block formats
 
 `@zuilib/text-editor` documents are plain markdown. Diagrams are embedded as
-a fenced code block with the language `drawing`, containing a single JSON
-object:
+fenced code blocks containing a single JSON object. Two languages exist:
+
+- ```` ```diagram ```` holds a **skeleton**: boxes, connectors and colors, no
+  coordinates. The editor lays it out and expands it into a full drawing on
+  import. **Generators should emit this one.** See
+  [Prefer the ```diagram skeleton](#prefer-the-diagram-skeleton).
+- ```` ```drawing ```` holds the **concrete format** (version 2): every shape
+  with its position, size and style. This is what the editor stores once a
+  drawing has been edited.
 
 ````md
 ```drawing
-{"version":1,"height":320,"shapes":[ ... ]}
+{"version":2,"canvasHeight":320,"shapes":[ ... ]}
 ```
 ````
 
-This document is the authoritative spec of that JSON payload. It is written
-so it can be handed to a program or an LLM that needs to **generate or edit
-drawings**. A machine-readable JSON Schema of the same rules is exported
-from the package as `DRAWING_DATA_JSON_SCHEMA`.
+This document is the authoritative spec of both payloads. It is written so
+it can be handed to a program or an LLM that needs to **generate or edit
+drawings**. Machine-readable JSON Schemas of the same rules are exported
+from the package as `DRAWING_DATA_JSON_SCHEMA` (concrete) and
+`DRAWING_SKELETON_JSON_SCHEMA` (skeleton).
 
 Malformed payloads never crash the editor: anything that fails validation
 degrades to an empty canvas (invalid shapes are dropped individually).
 
+Exactly one concrete format is supported: version 2, as written by the
+editor. Payloads with any other `version` (or none) render as an empty
+canvas. Convenience spellings such as `side` exist only in the ```diagram
+skeleton, which is a separate block type.
+
 ## Coordinate system
 
 - Origin `(0,0)` is the canvas's top-left; x grows right, y grows down.
 - Units are CSS pixels.
-- The canvas is as wide as the editor by default (`width` omitted or
-  `"full"`). Keep shapes within roughly x ∈ [0, 700] to be safe on typical
-  layouts.
-- `"width":"content"` instead sizes the canvas to fit the rightmost shape
-  (plus a margin, never narrower than 240px), left-aligned with the text —
-  use it for small diagrams that shouldn't stretch across the page.
-- `height` is the canvas height in pixels (minimum 80; 300–400 is typical).
+- `canvasHeight` is the canvas height in pixels (minimum 80; 300 to 400 is
+  typical).
+- `canvasWidth` is optional. When set, the drawing is scaled down to fit
+  narrower layouts (SVG viewBox), so coordinates can assume that width.
+  When omitted the canvas is fluid and as wide as the editor; keep shapes
+  within roughly x in [0, 700] to be safe on typical layouts.
+- `"width":"content"` sizes the block to fit the rightmost shape (plus a
+  margin), left-aligned with the text. Use it for small diagrams that
+  should not stretch across the page. Default `"full"`, omit it.
 
 ## Top-level object
 
-| Field     | Type      | Notes                                   |
-|-----------|-----------|-----------------------------------------|
-| `version` | `1`       | Literal `1`                             |
-| `height`  | `number`  | Canvas height in px                     |
-| `width`   | `"full"` \| `"content"` | Optional; default `"full"`. `"content"` fits the shapes' extent |
-| `shapes`  | `Shape[]` | Render order: later shapes draw on top  |
+| Field          | Type      | Notes                                                        |
+|----------------|-----------|--------------------------------------------------------------|
+| `version`      | `2`       | Literal `2`                                                  |
+| `canvasHeight` | `number`  | Canvas height in px (min 80)                                 |
+| `canvasWidth`  | `number`  | Optional logical width in px (min 120); scales to fit when set |
+| `width`        | `"full"` \| `"content"` | Optional; default `"full"`. `"content"` fits the shapes' extent |
+| `shapes`       | `Shape[]` | Render order: later shapes draw on top                       |
 
 ## Shape object
 
@@ -46,17 +62,33 @@ All shapes share these required fields:
 | Field         | Type     | Meaning                                                            |
 |---------------|----------|--------------------------------------------------------------------|
 | `id`          | `string` | Unique within the drawing; bindings reference it                   |
-| `type`        | `string` | `rect` \| `ellipse` \| `triangle` \| `pentagon` \| `arrow` \| `line` \| `text` |
+| `type`        | `string` | One of the types below                                             |
 | `x`, `y`      | `number` | Boxes/text: top-left of the bounding box. Connectors: start point. |
 | `w`, `h`      | `number` | Boxes/text: size (non-negative). Connectors: delta to the end point (`end = (x+w, y+h)`; may be negative). |
 | `stroke`      | `string` | CSS color of the outline and of all text on the shape              |
 | `fill`        | `string` | CSS color of the interior; `"transparent"` for none                |
 | `strokeWidth` | `number` | Use `2`                                                            |
 
-### Boxes (`rect`, `ellipse`, `triangle`, `pentagon`) — "cards"
+### Shape types
+
+| Type       | Kind      | Default size | Notes                                                        |
+|------------|-----------|--------------|--------------------------------------------------------------|
+| `rect`     | box       | 160 x 90     | Rectangle; the general-purpose card                          |
+| `ellipse`  | box       | 160 x 90     | Ellipse inscribed in the bounding box                        |
+| `diamond`  | box       | 170 x 100    | Decision; text area is the inner half                        |
+| `note`     | box       | 160 x 110    | Sticky note with a folded bottom-right corner; default fill `#ffec99` |
+| `cylinder` | box       | 140 x 110    | Database; text sits below the top ellipse                    |
+| `cloud`    | box       | 180 x 110    | Cloud; outline is an ellipse for binding purposes            |
+| `queue`    | box       | 180 x 80     | Horizontal cylinder (queue, stream, pipe)                    |
+| `actor`    | box       | 90 x 120     | Stick figure; `text` only, rendered as a name under the figure |
+| `arrow`    | connector |              | Head at the end; `bidirectional` for both ends               |
+| `line`     | connector |              | No arrowhead                                                 |
+| `text`     | free text |              | Floating annotation                                          |
+
+### Boxes ("cards")
 
 Boxes are card-like: they can carry up to three text slots that render
-inside the shape and move/resize/wrap with it:
+inside the shape and move, resize and wrap with it:
 
 | Field    | Renders as                                    |
 |----------|-----------------------------------------------|
@@ -64,12 +96,14 @@ inside the shape and move/resize/wrap with it:
 | `text`   | Main content, centered                        |
 | `footer` | Small dim line at the bottom                  |
 
-Text wraps automatically to the box width; `\n` forces a line break.
-Triangles are apex-up isoceles; pentagons are apex-up, inscribed in the
-bounding box. Prefer these slots over floating `text` shapes — slot text is
-attached to the card.
+Text wraps automatically to the box's text area; `\n` forces a line break.
+The text area is smaller than the bounding box for non-rectangular shapes
+(diamond, ellipse, cloud, cylinder), so give those a little more room.
+`actor` has only the `text` slot: it is drawn under the figure and may be
+wider than the box; `label` and `footer` are dropped. Prefer slots over
+floating `text` shapes; slot text is attached to the card.
 
-### `text` — free-floating annotation
+### `text`: free-floating annotation
 
 `text` holds the content. `w`/`h` are advisory (the editor recomputes them
 from the content); position is the top-left of the first line. Use only for
@@ -85,70 +119,210 @@ Geometry: from `(x, y)` to `(x+w, y+h)`. `arrow` has a head at the end;
 |-----------------|------------|-------------------------------------------------------------------------|
 | `text`          | `string`   | Label rendered at the path midpoint on a small backing plate            |
 | `bidirectional` | `boolean`  | Arrows only: heads on both ends                                         |
-| `startBinding`  | `string`   | id of the box the start attaches to                                     |
-| `endBinding`    | `string`   | id of the box the end attaches to                                       |
-| `routing`       | `"elbow"`  | Orthogonal auto-routing with up to two right-angle bends                |
-| `elbow`         | `number`   | 0–1: middle-segment position along the span (default 0.5)               |
-| `waypoints`     | `Point[]`  | Explicit intermediate path points (`{x,y}`), ordered start→end          |
-
-**Bindings.** When `startBinding`/`endBinding` name a box id, the editor
-re-anchors that endpoint onto the box's border (aimed at the other end, with
-a small gap) and keeps it attached as the box moves. Generated endpoints
-therefore only need to be approximately right — place them near the intended
-boxes and the resolver snaps them. Don't bind both ends of one connector to
-the same box. Bindings to ids that don't exist are silently dropped.
-
-**Routing.** Omit `routing` for a straight (possibly diagonal) connector.
-`"elbow"` renders an orthogonal path: it runs along the dominant axis, turns
-through a perpendicular middle segment (positioned by `elbow`), and turns
-again. If `waypoints` is non-empty it defines the path (`start → waypoints…
-→ end`) and `routing`/`elbow` are ignored. Waypoints are absolute canvas
+| `startBinding`  | `Binding`  | Box the start attaches to (see below)                                   |
+| `endBinding`    | `Binding`  | Box the end attaches to                                                 |
+| `routing`       | `"elbow"`  | Right-angled auto-routed path                                           |
+| `elbow`         | `number`   | 0 to 1: override of the middle segment, only for a simple three-segment Z |
+| `waypoints`     | `Point[]`  | Explicit intermediate path points (`{x,y}`), ordered start to end       |
+
+## Bindings
+
+A binding attaches a connector endpoint to a box and keeps it attached as
+the box moves:
+
+```json
+{ "id": "<box id>", "fixedPoint": [fx, fy], "mode": "orbit" }
+```
+
+| Field        | Type                     | Meaning                                                                 |
+|--------------|--------------------------|-------------------------------------------------------------------------|
+| `id`         | `string`                 | Required. Id of a box shape (bindings to unknown or non-box ids are dropped) |
+| `fixedPoint` | `[number, number]`       | Optional. Attach point as a ratio of the box's bounding box: `[0,0]` top-left, `[1,1]` bottom-right, `[0.5,0]` top edge midpoint. Values are clamped to 0 to 1 |
+| `mode`       | `"orbit"` \| `"inside"`  | Optional, default `"orbit"`                                             |
+
+- **Omit `fixedPoint`** when you do not care where the connector attaches:
+  the endpoint auto-aims from the box center at the other end of the
+  connector, so the line always meets the outline on the facing side.
+- **Set `fixedPoint` to an edge midpoint** when the attach edge matters (a
+  decision's "yes" leaves at the bottom `[0.5,1]`, "no" at the right
+  `[1,0.5]`). In the ```diagram skeleton the same thing is spelled
+  `"side":"bottom"`.
+- `mode: "orbit"` (default) projects the endpoint onto the box outline with
+  a 6px gap. `mode: "inside"` pins the endpoint exactly on the fixed point
+  (useful for lines that end inside a shape).
+
+Bound endpoints are re-anchored by the editor, so the connector's own
+`x`/`y`/`w`/`h` only need to be approximately right: place them near the
+intended boxes and the resolver snaps them. Don't bind both ends of one
+connector to the same box.
+
+## Routing
+
+Omit `routing` for a straight (possibly diagonal) connector.
+
+`"routing":"elbow"` renders an auto-routed orthogonal path: it leaves the
+box perpendicular to the attach side, avoids every box on the canvas, and
+uses as few bends as possible. `elbow` (0 to 1) is an optional override of
+the middle segment's position along the span; it is applied only when the
+routed path is a simple three-segment Z, and ignored otherwise.
+
+If `waypoints` is non-empty it defines the path (`start, waypoints..., end`)
+and `routing`/`elbow` are ignored. Waypoints are absolute canvas
 coordinates; align consecutive points on x or y to get right angles.
 
 ## Recommended colors
 
-Any CSS color works; the editor's palette (dark-mode safe — the canvas
+Any CSS color works; the editor's palette (dark-mode safe, the canvas
 inverts colors Excalidraw-style in dark themes):
 
-- Strokes: `#1e1e1e` (default), `#e03131` red, `#2f9e44` green, `#1971c2` blue, `#f08c00` orange
-- Fills: `transparent`, `#ffc9c9`, `#b2f2bb`, `#a5d8ff`, `#ffec99`
+| Name   | Stroke    | Fill          |
+|--------|-----------|---------------|
+| gray   | `#1e1e1e` | `transparent` |
+| red    | `#e03131` | `#ffc9c9`     |
+| green  | `#2f9e44` | `#b2f2bb`     |
+| blue   | `#1971c2` | `#a5d8ff`     |
+| orange | `#f08c00` | `#ffec99`     |
+| purple | `#7048e8` | `#d0bfff`     |
+
+Pair a colored stroke with its pastel fill. `note` defaults to the yellow
+fill `#ffec99`.
+
+## Prefer the ```diagram skeleton
+
+A fenced block with language `diagram` holds a skeleton: what the boxes are
+and how they connect. The editor expands it into a full ```drawing block
+on import (auto layout, default sizes, palette colors). The expansion is
+one-way: once opened, the document stores the concrete ```drawing block.
+
+```
+{
+  "direction"?: "right" | "down",          // auto-layout flow, default right
+  "canvasWidth"?: n, "canvasHeight"?: n, "width"?: "content",
+  "boxes": [ { "id", "type"?: <box type, default rect>, "label"?, "text"?, "footer"?,
+               "x"?, "y"?,            // omitted: auto layout by connector rank
+               "w"?, "h"?,            // omitted: sized to fit the text
+               "color"?: "gray"|"red"|"green"|"blue"|"orange"|"purple",  // stroke + pastel fill
+               "stroke"?, "fill"? } ],
+  "connectors"?: [ { "id"?, "type"?: "arrow"|"line", "from": "<id>" | {"id","side"?}, "to": same,
+                     "text"?, "bidirectional"?, "routing"?: "elbow"|"straight", "color"?, "stroke"? } ],
+  "texts"?: [ { "x", "y", "text", "color"? } ]
+}
+```
+
+Rules:
+
+- `boxes` is required; every box needs a unique `id`. `type` is any box
+  type from the table above (default `rect`).
+- `from`/`to` are box ids, or `{"id","side"}` to pick the attach edge.
+- `color` picks a palette pair (stroke plus pastel fill) from the table
+  above. `stroke`/`fill` override it with explicit CSS colors. On
+  connectors only the stroke applies.
 
-Pair a colored stroke with its pastel fill (`#1971c2` + `#a5d8ff`, etc.).
+- Auto layout: boxes are ranked along `direction` by the longest path from
+  the sources (cycles are broken). Ranks are 90px apart, boxes within a
+  rank 40px apart, starting at (32,32). Boxes with explicit `x`/`y` keep
+  them. Boxes without `w`/`h` are sized to fit their text. `canvasHeight`
+  is computed when omitted.
+- `texts` are free annotations and need explicit coordinates.
 
-## Examples
+A three-box flow:
+
+````md
+```diagram
+{"boxes":[
+  {"id":"web","label":"CLIENT","text":"Web App","footer":"React","color":"blue"},
+  {"id":"api","label":"SERVICE","text":"API","footer":"Kotlin","color":"green"},
+  {"id":"db","type":"cylinder","text":"Postgres"}
+],"connectors":[
+  {"from":"web","to":"api","text":"REST"},
+  {"from":"api","to":"db"}
+]}
+```
+````
+
+A decision with attach sides and elbow routing, flowing down:
+
+````md
+```diagram
+{"direction":"down","boxes":[
+  {"id":"user","type":"actor","text":"User"},
+  {"id":"check","type":"diamond","text":"Valid?"},
+  {"id":"save","text":"Save","color":"green"},
+  {"id":"err","type":"note","text":"Show error","color":"red"}
+],"connectors":[
+  {"from":"user","to":"check"},
+  {"from":{"id":"check","side":"bottom"},"to":"save","text":"yes","routing":"elbow"},
+  {"from":{"id":"check","side":"right"},"to":{"id":"err","side":"left"},"text":"no","routing":"elbow"}
+]}
+```
+````
+
+Programmatic use: `parseDrawingSkeleton(json)` parses a skeleton,
+`expandSkeleton(skeleton)` returns `DrawingData`, and
+`DRAWING_SKELETON_JSON_SCHEMA` is the JSON Schema. Types: `DrawingSkeleton`,
+`SkeletonBox`, `SkeletonConnector`.
+
+## Concrete examples
 
 Two bound cards with a labeled arrow:
 
 ````md
 ```drawing
-{"version":1,"height":260,"shapes":[
+{"version":2,"canvasHeight":260,"shapes":[
   {"id":"web","type":"rect","x":40,"y":70,"w":170,"h":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App","footer":"React"},
   {"id":"api","type":"rect","x":330,"y":70,"w":170,"h":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API","footer":"Kotlin"},
-  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":"web","endBinding":"api","text":"REST"}
+  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"web"},"endBinding":{"id":"api"},"text":"REST"}
 ]}
 ```
 ````
 
-An elbow arrow and a hand-routed multi-bend line:
+An elbow arrow with attach sides, a database, and a hand-routed multi-bend
+line:
 
 ````md
 ```drawing
-{"version":1,"height":300,"shapes":[
+{"version":2,"canvasHeight":300,"canvasWidth":640,"shapes":[
   {"id":"a","type":"rect","x":40,"y":40,"w":150,"h":80,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"text":"A"},
-  {"id":"b","type":"ellipse","x":420,"y":180,"w":150,"h":80,"stroke":"#e03131","fill":"#ffc9c9","strokeWidth":2,"text":"B"},
-  {"id":"e1","type":"arrow","x":196,"y":80,"w":224,"h":140,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":"a","endBinding":"b","routing":"elbow"},
-  {"id":"e2","type":"line","x":115,"y":126,"w":380,"h":54,"stroke":"#1971c2","fill":"transparent","strokeWidth":2,"startBinding":"a","endBinding":"b","waypoints":[{"x":115,"y":260},{"x":495,"y":260}]}
+  {"id":"b","type":"cylinder","x":420,"y":180,"w":140,"h":110,"stroke":"#7048e8","fill":"#d0bfff","strokeWidth":2,"text":"B"},
+  {"id":"e1","type":"arrow","x":190,"y":80,"w":300,"h":100,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"a","fixedPoint":[1,0.5]},"endBinding":{"id":"b","fixedPoint":[0.5,0]},"routing":"elbow"},
+  {"id":"e2","type":"line","x":115,"y":126,"w":375,"h":54,"stroke":"#1971c2","fill":"transparent","strokeWidth":2,"startBinding":{"id":"a"},"endBinding":{"id":"b"},"waypoints":[{"x":115,"y":260},{"x":490,"y":260}]}
 ]}
 ```
 ````
 
+## Mermaid export
+
+The canvas has a **Copy as Mermaid** button. Programmatically,
+`drawingToMermaid(data, { direction?: 'LR' | 'TD' })` returns a
+`flowchart`:
+
+- one node per box, in shape order: `rect` and `note` `["…"]`, `ellipse`
+  `(["…"])`, `diamond` `{"…"}`, `cylinder` `[("…")]`, `cloud` and `actor`
+  `(("…"))`, `queue` `[["…"]]`; node text joins `label`, `text` and
+  `footer`
+- one edge per connector bound at both ends: `-->`, `<-->` (bidirectional),
+  `---` (line); connector `text` becomes `|text|`. Unbound connectors are
+  dropped
+- a `style` line for every box with a non-default stroke or fill
+- free `text` shapes as `%% note:` comments
+
+When `direction` is omitted it is `LR` if most edges run horizontally,
+otherwise `TD`.
+
 ## Generation checklist
 
-1. One JSON object, single ```drawing fence, no comments or trailing commas.
-2. Every `id` unique; every binding references an existing box id.
-3. Boxes ≥ 120×70 when they carry text slots; leave ~60px between cards for
+1. Prefer a ```diagram skeleton. Fall back to ```drawing only when you edit
+   an existing concrete payload or need exact positions.
+2. One JSON object per fence, no comments or trailing commas.
+3. Every `id` unique; every binding references an existing box id.
+4. Concrete boxes: at least 120 x 70 when they carry text slots (use the
+   default sizes from the table); leave about 60px between cards for
    connectors and labels.
-4. Box text goes in `label`/`text`/`footer` — not in floating `text` shapes.
-5. Connectors between cards should bind both ends; approximate endpoints are
-   fine (the editor snaps them to borders).
-6. `height` large enough to contain every shape plus ~20px margin.
+5. Box text goes in `label`/`text`/`footer`, not in floating `text` shapes.
+   `actor` only has `text`.
+6. Connectors between cards bind both ends as objects (`{"id":"web"}`).
+   Add an edge-midpoint `fixedPoint` when the attach edge matters; omit it
+   otherwise.
+7. Use `"routing":"elbow"` for flowcharts; leave `elbow` and `waypoints`
+   out unless you need to override the router.
+8. `canvasHeight` large enough to contain every shape plus ~20px margin.

package/README.md

@@ -15,9 +15,12 @@ document outline, and collapsible sections.
   inline formatting), styled like Claude artifacts
 - **Table settings**: full/content width and row density per table;
   diagrams switch between full and content width too — Slab-style
-- **Diagrams**: a drawing canvas embedded in the document — cards with
-  attached text slots, bound arrows that follow their cards, elbow and
-  multi-waypoint routing, labels, color palettes, dark mode
+- **Diagrams**: a drawing canvas embedded in the document. Eight box
+  shapes (rectangle, ellipse, diamond, note, database, cloud, queue, actor)
+  with attached text slots, bound arrows that follow their boxes and attach
+  to a chosen side, auto-routed elbows that avoid other boxes, multi-select,
+  color palettes, dark mode, Mermaid export. LLMs author diagrams as a
+  coordinate-free ` ```diagram ` skeleton that the editor lays out
 - **Outline**: optional table-of-contents sidebar with click-to-scroll and
   current-section highlight
 - **Section folding**: collapse everything under a heading, view-layer only
@@ -217,29 +220,79 @@ table containing the selection, `null` outside tables), `canUndo`,
 ## Diagrams (drawing canvas)
 
 The toolbar's insert-drawing button embeds a canvas; the drawing persists
-in the markdown as a ` ```drawing ` fenced JSON block, fully specified in
-**[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
+in the markdown as a ` ```drawing ` fenced JSON block (format version 2),
+fully specified in **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
 
-- **Shapes**: rectangle, ellipse, triangle, pentagon, arrow, line, text —
-  with stroke/fill palettes. Draw by picking a tool and dragging.
+- **Shapes**: rectangle, ellipse, diamond, note (sticky note), database
+  (cylinder), cloud, queue, actor (stick figure), arrow, line, text. The
+  toolbar shows the common tools and a "more shapes" popover for the rest.
+  Draw by picking a tool and dragging.
 - **Cards**: every box carries three text slots that move, resize, and wrap
-  with it — a bold **label** on top, **content** in the center, a dim
-  **footer** at the bottom. Click a selected box (or double-click its
-  top/middle/bottom strip, or press Enter) to edit a slot.
+  with it: a bold **label** on top, **content** in the center, a dim
+  **footer** at the bottom (actor has only the name under the figure).
+  Click a selected box (or double-click its top/middle/bottom strip, or
+  press Enter) to edit a slot.
 - **Bound connectors**: an arrow drawn from one card to another attaches to
-  both — moving a card moves its arrows, endpoints anchored to the border.
-  Drag an endpoint off/onto a card to detach/re-attach.
-- **Routing**: straight (diagonal) by default; toggle **elbow** for right
-  angles, or drag the dashed "+" handles on a selected connector to add any
-  number of **waypoints** (they snap to neighbors' axes for clean 90°
-  bends). One-way / two-way arrowhead toggle; midpoint **labels**.
+  both; moving a card moves its arrows, endpoints anchored to the outline.
+  An endpoint either auto-aims at the other end or sticks to a fixed point
+  on the box (a side, or a ratio inside the box). Drag an endpoint off/onto
+  a card to detach/re-attach.
+- **Routing**: straight (diagonal) by default; toggle **elbow** for an
+  auto-routed right-angled path that leaves the box perpendicular to its
+  attach side and avoids the other boxes, or drag the dashed "+" handles on
+  a selected connector to add any number of **waypoints** (they snap to
+  neighbors' axes for clean 90° bends). One-way / two-way arrowhead toggle;
+  midpoint **labels**.
+- **Multi-select**: shift-click, or drag a marquee on empty canvas, then
+  move, delete, or recolor the selection together. A contextual property
+  bar shows the options for whatever is selected.
+- **Copy as Mermaid**: a canvas button copies the drawing as a Mermaid
+  `flowchart` (also available as `drawingToMermaid(data)`).
 - **Canvas**: resizable height, dot grid, white surface that inverts
-  Excalidraw-style in dark mode (`.dark` ancestor class).
+  Excalidraw-style in dark mode (`.dark` ancestor class). An optional
+  `canvasWidth` scales the drawing to fit narrower layouts.
 - **Width**: the toggle at the right end of the canvas toolbar switches
   between **full width** (spans the editor) and **content width** (the
   canvas fits the rightmost shape and grows as shapes move). Stored as
   `"width":"content"` in the payload; omitted when full.
 
+A stored drawing looks like this:
+
+````md
+```drawing
+{"version":2,"canvasHeight":260,"shapes":[
+  {"id":"web","type":"rect","x":40,"y":70,"w":170,"h":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App"},
+  {"id":"api","type":"rect","x":330,"y":70,"w":170,"h":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API"},
+  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"web"},"endBinding":{"id":"api"},"text":"REST"}
+]}
+```
+````
+
+### The ` ```diagram ` skeleton
+
+Generators (LLMs, scripts) do not need coordinates. A ` ```diagram ` block
+holds a skeleton: boxes, connectors, colors. On import the editor lays it
+out along `direction` (`right` by default, or `down`), sizes boxes to their
+text, and stores the result as a normal ` ```drawing ` block (one-way
+expansion).
+
+````md
+```diagram
+{"boxes":[
+  {"id":"web","label":"CLIENT","text":"Web App","color":"blue"},
+  {"id":"api","label":"SERVICE","text":"API","color":"green"},
+  {"id":"db","type":"cylinder","text":"Postgres"}
+],"connectors":[
+  {"from":"web","to":"api","text":"REST"},
+  {"from":"api","to":"db","routing":"elbow"}
+]}
+```
+````
+
+The full skeleton spec (attach sides, explicit positions, free texts) is
+in [DRAWING_FORMAT.md](./DRAWING_FORMAT.md). Programmatic access:
+`parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`.
+
 ## Outline & section folding
 
 `outline` docks a collapsible table-of-contents sidebar: live heading list
@@ -256,14 +309,19 @@ remount; a folded section auto-expands if the cursor enters it.
 Documents are plain markdown, so LLMs can generate them — including
 diagrams:
 
-- **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)** is the authoritative
-  ` ```drawing ` payload spec, written to be pasted into a prompt (ships in
-  the npm package next to this README).
-- `DRAWING_DATA_JSON_SCHEMA` (exported) is the same contract as JSON Schema
-  — use it to validate generated payloads or as a structured-output/tool
-  schema.
-- `parseDrawingData(json)` is the editor's own lenient parser (invalid
-  shapes drop out; never throws); `serializeDrawingData` is its inverse.
+- Emit ` ```diagram ` skeleton blocks: no coordinates, the editor lays them
+  out. Use ` ```drawing ` (format v2) only to edit an existing concrete
+  payload.
+- **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)** is the authoritative spec of
+  both payloads, written to be pasted into a prompt (ships in the npm
+  package next to this README).
+- `DRAWING_SKELETON_JSON_SCHEMA` and `DRAWING_DATA_JSON_SCHEMA` (exported)
+  are the same contracts as JSON Schema: use them to validate generated
+  payloads or as structured-output/tool schemas.
+- `parseDrawingSkeleton(json)` / `expandSkeleton(skeleton)` turn a skeleton
+  into `DrawingData`. `parseDrawingData(json)` is the editor's own lenient
+  parser (invalid shapes drop out; never throws); `serializeDrawingData` is
+  its inverse. `drawingToMermaid(data)` exports a Mermaid `flowchart`.
 - A ready-made Claude Code skill lives in the monorepo at
   `.claude/skills/text-editor-documents/` — copy it into consuming repos so
   agents there know the dialect.
@@ -280,11 +338,14 @@ diagrams:
 | `BlockWidth`, `TableDensity`, `TableSettings`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
 | `$getTableSettings`, `$setTableSettings`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
 | `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` |
-| `DRAWING`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformer |
+| `DRAWING`, `DIAGRAM`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformers (` ```drawing ` and ` ```diagram `) |
 | `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |
 | `DrawingData`, `DrawingShape`, `DrawingShapeType` | Drawing payload types |
 | `parseDrawingData`, `serializeDrawingData` | Drawing payload (de)serialization |
 | `DRAWING_DATA_JSON_SCHEMA` | JSON Schema of the drawing payload |
+| `DrawingSkeleton`, `SkeletonBox`, `SkeletonConnector` | Skeleton types |
+| `parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA` | Skeleton parsing, expansion to `DrawingData`, JSON Schema |
+| `drawingToMermaid` | Mermaid `flowchart` export |
 
 ## Form integration
 
@@ -305,13 +366,15 @@ ZUI convention: a `dark` class on `<html>`.
 - Source: `src/EditorRoot.tsx` (composer + plugins), `src/EditorContent.tsx`,
   `src/MarkdownEditor.tsx` (default composition), `src/useMarkdownEditor.ts`,
   `src/components/Toolbar.tsx`; plugins in `src/plugins/`; drawing
-  canvas in `src/components/`; custom nodes in `src/nodes/`;
+  canvas in `src/drawing/`; custom nodes in `src/nodes/`;
   transformers in `src/transformers/`
 - Markdown import/export via `@lexical/markdown` transformers; order
-  matters: `FRONTMATTER` and `DRAWING` claim their blocks before `CODE`,
-  `CHECK_LIST` before `UNORDERED_LIST`
-- Drawing geometry (bindings resolver, elbow/waypoint paths, wrapping) is
-  pure and lives in `src/components/drawingGeometry.ts`
+  matters: `FRONTMATTER`, `DRAWING` and `DIAGRAM` claim their blocks before
+  `CODE`, `CHECK_LIST` before `UNORDERED_LIST`
+- `src/drawing/` keeps the format (`types.ts`, `schema.ts`), shape
+  definitions (`shapes/`), pure geometry (`geometry.ts`), the Mermaid
+  exporter (`mermaid.ts`) and the React canvas (`canvas/`) apart, so the
+  router, bindings and skeleton expansion run without a DOM
 - Tests: `pnpm test` runs a headless-Lexical markdown round-trip suite
   (`tests/roundtrip.mjs`)