@diagrammo/dgmo 0.95.0 → 0.96.0

package/docs/language-reference.md

@@ -98,7 +98,7 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 - **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
   <!-- TITLE end -->
   <!-- CATEGORIZE start -->
-- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>` in the header — after the tag group and before the first element, because a type such as c4 refuses it after content — then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). **Bracket, block, body, event-line, family, sketch and whiteboard** take the tag group but no `active-tag` line — declare the group and stop there; on event-line, family and sketch the line would be drawn as an element. **Class, flowchart, wireframe, raci, cycle, pyramid, ring, sankey, tech-radar, venn, version-control, wordcloud, arc, bar, clock, countdown, funnel, function, goal, heatmap, line, pie, polar-area, quadrant, radar, scatter and slope** take no tag group at all — skip this rule for them. Most report the lines; cycle, pyramid, ring, sankey, venn, version-control and wordcloud read them as content, and flowchart and tech-radar drop them without a word. Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have _fewer_ values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>` in the header — after the tag group and before the first element, because a type such as c4 refuses it after content — then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). **Bracket, block, body, event-line, family and whiteboard** take the tag group but no `active-tag` line — declare the group and stop there; on event-line and family the line would be drawn as an element. **Class, flowchart, wireframe, raci, cycle, pyramid, ring, sankey, tech-radar, venn, version-control, wordcloud, arc, bar, clock, countdown, funnel, function, goal, heatmap, line, pie, polar-area, quadrant, radar, scatter and slope** take no tag group at all — skip this rule for them. Most report the lines; cycle, pyramid, ring, sankey, venn, version-control and wordcloud read them as content, and flowchart and tech-radar drop them without a word. Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have _fewer_ values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
 <!-- CATEGORIZE end -->
 - **Keep labels short.** A few words per node. Move detail into notes or metadata, never a full sentence inside a label.
 - **Let the defaults show.** Don't add `no-*` opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color.
@@ -141,7 +141,6 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 | `ring`            | concentric rings of nested categories                                                                                                                         |
 | `treemap`         | nested rectangles sized by value (budgets, disk usage, portfolios)                                                                                            |
 | `block`           | author-controlled grid of nested, collapsible blocks (system / architecture layouts)                                                                          |
-| `sketch`          | GUI-first free-placement canvas: uniform shapes on a snap grid, arrows, tags (markup is app-generated)                                                        |
 | `whiteboard`      | free-form infinite canvas: shapes, sticky notes, free arrows, text, images and freehand ink at pixel positions (canvas-drawn; AI writes all but ink)          |
 | `goal`            | single progress-toward-a-target value (`now` vs `target`) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas                                |
 | `countdown`       | live "N days until X" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type                    |
@@ -215,7 +214,7 @@ tag GroupName as <alias>
 - Must appear before diagram content
 - Bare shorthand is not an alias (TD-18): `tag Priority p` declares a group _named_ "Priority p" — no alias registers, so `p:` assignments silently miss. The parser warns on this shape (spaced name, no alias, alias-shaped trailing word), suggesting `tag Priority as p` or a quoted name
 
-**Diagram types that support tags**: the tag model is near-universal across the structural types — sequence, infra, org, c4, er, kanban, gantt, sitemap, timeline, boxes-and-lines, state (§5.7), pert, swimlane, mindmap, journey-map, event-line, treemap, map, block, sketch, bracket, family and whiteboard all accept `tag <Group> as <alias>` blocks (a whiteboard's names its colours — §24Ea). Check the per-type Options section for the exact directive set; if a type draws a tag legend, it takes tags. **Flowchart, wireframe, raci and class take no tags** — a `tag` block or `active-tag` on any of them is ignored with a warning, because what an element looks like is fixed by what it is (a flowchart's shape, a wireframe's state keywords, a class's trailing colour word) or by the roles (raci).
+**Diagram types that support tags**: the tag model is near-universal across the structural types — sequence, infra, org, c4, er, kanban, gantt, sitemap, timeline, boxes-and-lines, state (§5.7), pert, swimlane, mindmap, journey-map, event-line, treemap, map, block, bracket, family and whiteboard all accept `tag <Group> as <alias>` blocks (a whiteboard's names its colours — §24Ea). Check the per-type Options section for the exact directive set; if a type draws a tag legend, it takes tags. **Flowchart, wireframe, raci and class take no tags** — a `tag` block or `active-tag` on any of them is ignored with a warning, because what an element looks like is fixed by what it is (a flowchart's shape, a wireframe's state keywords, a class's trailing colour word) or by the roles (raci).
 
 ### 1.4 Same-Line Metadata
 
@@ -285,7 +284,7 @@ Two narrow exceptions accept same-line-metadata-only color: **cycle edges** (no
 - Indented content below belongs to the group
 - **A tag value on the group line colors the group's own frame**, and cascades
   to its children: `[Backend] s: Red`. Supported on boxes-and-lines, infra, c4,
-  state, pert, kanban, gantt, sequence, org, block and sketch. Two rules: a
+  state, pert, kanban, gantt, sequence, org and block. Two rules: a
   group never picks up the tag group's first-value default (an untagged group
   stays neutral grey), and a value the tag group does not recognize leaves it
   neutral rather than painting a fallback shade.
@@ -431,6 +430,25 @@ A block must have every key, hex only, text readable on its fills, and a name th
 
 **Who wins**, highest first: an explicit choice where the diagram is shown (a fence `palette=` attribute, `--palette` on the command line), then the file's palette, then the site's or app's own setting, then Slate. `theme` is retired — the mode word on the palette line does its job.
 
+### 1.11 Line Breaks in Description and Note Bodies
+
+A line break in the source is **not** a line break in the drawing. Consecutive body lines join into one paragraph and re-wrap to fit the card, so you can break prose wherever is comfortable in the editor. Two things keep a break:
+
+- **A blank line** starts a new paragraph, with a gap above it.
+- **A trailing `\`** breaks the line without starting a new paragraph (markdown's hard break).
+
+A `- ` line always starts its own bullet. A plain line straight after a bullet continues that bullet; a blank line returns to prose.
+
+```
+2026-09-28 67.10.0 deployed
+  *9:00 AM* \
+  Existing refresh code already deletes opted-out cards.
+```
+
+Without the `\`, the time and the sentence join into one line: `9:00 AM Existing refresh code…`.
+
+This applies to event-line descriptions, pyramid, ring and cycle descriptions, boxes-and-lines descriptions, and multi-line note bodies (sequence, flowchart, state, class, ER, journey-map, countdown).
+
 ---
 
 ## 2. Universal Name Handling
@@ -753,6 +771,7 @@ Content formatting:
 - Inline markdown: `**bold**`, `*italic*`, `` `code` ``
 - Links: `[text](url)` and bare URLs (auto-truncated in display)
 - The note ends where the indentation does — there is **no `end` terminator** (a bare `end` line is rejected).
+- Body lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 ### 2.6 Structural Blocks
 
@@ -772,6 +791,7 @@ parallel label
 ```
 
 - `parallel` requires a label
+- `else` is bare. A second condition is `else if <condition>`; `else <label>` is an error (`'else' does not take a label`)
 - Blocks nest via indentation
 - **No `end`/terminator keyword** — a block closes by dedenting (like multi-line notes). `end` and `activate`/`deactivate` are not dgmo syntax (a bare `end` line is rejected); activation is controlled by the `activations` option (§2.7), not per-message keywords.
 - **Tags apply to participants, not messages** — there is no per-message tag/color. Color a participant by category with `<Participant> <tagAlias>: <Value>` after declaring a `tag <Name> as <alias>` group (§1.3). Message text is just the arrow label.
@@ -783,6 +803,27 @@ parallel label
 - `collapse-notes` / `no-collapse-notes`
 - `active-tag GroupName`
 
+Options go in the header. Put every option line — `active-tag` included — after the `tag` groups and before the first participant declaration, `[Group]`, divider or message. An option after any of those is an error (`Options like 'active-tag Zone' must appear before the first message or declaration`).
+
+```dgmo
+sequence Checkout
+tag Zone as z
+  Internal blue
+  External orange
+active-tag Zone
+
+Shop is a service z: Internal
+Bank is a service z: External
+
+Shop -charge-> Bank
+  if approved
+    Bank -receipt-> Shop
+  else if declined
+    Bank -decline code-> Shop
+  else
+    Bank -timeout-> Shop
+```
+
 ---
 
 ## 4. Infrastructure Diagrams
@@ -955,7 +996,7 @@ API Gateway
 
 <!-- TIPS start -->
 
-**Styling tips:** write every connection as `Source -> Target` (or a single-line chain like `(Start) -> [Collect info] -> <Eligible?>`); write each connection on its own line. Every decision `<Question?>` MUST have at least two outgoing branches — usually `-yes->`/`-no->`, but use specific labels when the choices are not binary (e.g. `-retirement->`, `-disability->`, `-survivor->`); a decision with only one branch is invalid. Begin at exactly one start terminal `(Start)` and make every path terminate at a terminal node (`(Approved)`, `(Denied)`, `(End)`). Every node MUST connect to the rest of the graph: if a node cannot be traced from the start forward to a terminal, it is invalid — remove it, never leave it floating. Flowcharts have NO tag groups, node metadata, or manual node colors — do NOT write `tag … as …`, a `s: value` suffix, or a trailing color word; node colors are assigned automatically by shape (start terminal green, end terminals red, processes blue, decisions yellow). Just pick the right shape and let color follow. Label every decision edge so branches read unambiguously; keep each node to a short action phrase and phrase every decision as a question.
+**Styling tips:** write every connection as `Source -> Target` (or a single-line chain like `(Start) -> [Collect info] -> <Eligible?>`); write each connection on its own line. Every decision `<Question?>` MUST have at least two outgoing branches — usually `-yes->`/`-no->`, but use specific labels when the choices are not binary (e.g. `-retirement->`, `-disability->`, `-survivor->`); a decision with only one branch is invalid. Begin at exactly one start terminal `(Start)` and make every path terminate at a terminal node (`(Approved)`, `(Denied)`, `(End)`). Nothing points back at the start node: no arrow may end at `(Start)`, so a loop returns to a step after it (`-retry-> [Collect info]`), never to the start. Every node MUST connect to the rest of the graph: if a node cannot be traced from the start forward to a terminal, it is invalid — remove it, never leave it floating. Flowcharts have NO tag groups, node metadata, or manual node colors — do NOT write `tag … as …`, a `s: value` suffix, or a trailing color word; node colors are assigned automatically by shape (start terminal green, end terminals red, processes blue, decisions yellow). Just pick the right shape and let color follow. Label every decision edge so branches read unambiguously; keep each node to a short action phrase and phrase every decision as a question.
 
 <!-- TIPS end -->
 
@@ -1020,13 +1061,16 @@ Bracket syntax only.
 
 ### 4.7 Notes (Nodes)
 
-Attach an annotation to a node with `note <NodeId> text` (quote the id
-for multi-word labels). The note renders as a folded-corner box beside
-the node, expanded at rest.
+Attach an annotation to a node with `note NodeLabel text` (quote the
+label when it has more than one word). A note names the node by its
+label, without the shape's brackets: the decision `<Email exists?>` takes
+`note "Email exists?" …`, never `note <Email exists?> …`. The note renders
+as a folded-corner box beside the node, expanded at rest.
 
 ```
 note Validate checks the payload schema
 note "Read Map" the map is half-burned
+note "Email exists?" checks the users table
 ```
 
 Indent lines below the heading for a multi-line body (bullets + inline
@@ -2740,7 +2784,7 @@ tag Genre as g
 - **Date** — optional, ISO only (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `+HH:MM` / `+HH:MM:SS`, plus `YYYY BCE`/`BC`/`CE`/`AD`), formatted for reading as the card subtitle (`2008-09-02` → `Sep 2, 2008`). No `date:` key; no `M/D/YYYY`.
 - **`TBD` (future events)** — write the literal `TBD` (case-insensitive) in the date slot for a **not-yet-scheduled** event: `TBD Console Port  t: Engine`. Its caption reads `TBD` and it draws a **hollow dot + faded leader** (a faded shelf edge in `no-box`) so it reads as pending. To scale, its position is **inferred from its source-order dated neighbors**: a `TBD` followed by a dated event is interpolated into that gap; a **trailing** `TBD` (nothing dated after it) parks past the last real date and the spine **trails off dashed** — the open horizon. `TBD`s never trip the bad-date / out-of-order warnings.
 - **Tag** — trailing same-line metadata (`g: Pop`), like timeline; colors the dot, leader, and card.
-- **Description** — bare indented body lines (like `pyramid`/`ring`); `- ` makes a bullet; inline markdown (`**bold**`, `*italic*`, `` `code` ``) supported.
+- **Description** — bare indented body lines (like `pyramid`/`ring`); `- ` makes a bullet; inline markdown (`**bold**`, `*italic*`, `` `code` ``) supported. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 #### Eras
 
@@ -3327,7 +3371,7 @@ Act red
 
 ### Descriptions
 
-Indented lines under a node become the description. Inline markdown is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`), and `- item` renders as `• item`.
+Indented lines under a node become the description. Inline markdown is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`), and `- item` renders as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 ```
 Observe
@@ -3610,7 +3654,7 @@ Physiological orange
 
 ### Descriptions
 
-Indented lines under a layer are description text. Markdown inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) is supported. Bullets written as `- item` render as `• item`.
+Indented lines under a layer are description text. Markdown inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) is supported. Bullets written as `- item` render as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 ### Directives
 
@@ -3679,7 +3723,7 @@ The Open Sea cyan
 
 ### Descriptions
 
-Indented lines under a layer are description text. Markdown inline formatting is supported. Bullets written as `- item` render as `• item`. Descriptions appear in a stacked side list with colored accent bars.
+Indented lines under a layer are description text. Markdown inline formatting is supported. Bullets written as `- item` render as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11). Descriptions appear in a stacked side list with colored accent bars.
 
 ### Directives
 
@@ -3903,86 +3947,6 @@ In the desktop app a block diagram is interactive: click a container header to c
 
 ---
 
-## 24E. Sketch Diagrams
-
-<!-- TYPE:sketch -->
-
-**Beta — expect rough edges and syntax changes.**
-
-<!-- TIPS start -->
-
-**Styling tips:** Sketch is a GUI-authored format — the desktop and web canvas editors generate this markup, so hand-writing it is the exception. If you generate it anyway: keep it SMALL (sketches read best under ~15 shapes), and either omit `at:` everywhere (shapes flow into rows) or use integer half-slot coordinates with shapes **at least 3 half-slots apart** on one axis (a footprint spans 2 half-units and the mandatory gap adds 1 more, so each shape claims a 3×3 block; 2 apart overlaps). A `[Box]` may hold another `[Box]`, to **depth 2** — a third level is refused and its shapes join the box above it. Alias any shape an edge references (`as con`). Never write `size:`, `shape:`, colors, or fonts — every shape is the same plain card. In sketch, `~` dashed means secondary emphasis, NOT async. Categorize with a tag group — kind-of-thing is meaning, and meaning lives in tags. Reach for `sketch` when the drawing itself is the content; reach for `boxes-and-lines` when topology should auto-lay-out.
-
-<!-- TIPS end -->
-
-A **GUI-first constrained canvas**: uniformly-sized shapes placed freely on a snap grid, arrows between them, meaning through tags. The renderer owns all styling — authors own placement, connection, naming, and tags. Every shape has ONE universal footprint (no resizing); text always fits (shrink → smart-wrap → `…`). Pick `sketch` when the spatial arrangement is yours to decide; pick `boxes-and-lines` when topology should auto-lay-out.
-
-### Declaration
-
-```
-sketch [Title]
-```
-
-### Example
-
-```
-sketch Plunder Pipeline
-
-tag Crew
-  Deck
-  Hold
-
-Spyglass Feed at: 0 0, crew: Deck
-  -sightings-> con
-Captain's Console as con at: 2 0, crew: Deck
-  -orders-> bq
-Divvy Service as dvy at: 4 0, crew: Hold
-
-[Below Decks] at: 2 2, crew: Hold
-  Booty Queue as bq at: 0 0
-    ~haul~> dvy
-  Ship Ledger as ledger at: 2 0
-
-[Armory] as armory at: 0 2, collapsed
-  Powder Store at: 0 0
-```
-
-### Shapes
-
-One top-level line = one shape — a **bare name** plus same-line `key: value` metadata. Every shape is the same plain card — there are no shape kinds, and a `shape:` clause is an error (`E_SKETCH_SHAPE_UNSUPPORTED`); the shape still draws, without it. Duplicate labels are legal **when aliased** (`Cache as c1` / `Cache as c2`); unaliased duplicates merge (standard dgmo semantics).
-
-### Coordinates — `at: C R`
-
-Integer **half-slot steps** (a slot = one footprint + the mandatory gap), origin-normalized; box children are relative to the box origin. `at:` is **optional** — un-positioned shapes flow-place in rows below existing content. Hand-authored overlap auto-resolves with a warning; nothing renders broken.
-
-### Lines
-
-Indented under the source shape, targeting an alias (or an unambiguous bare label). Six forms: `-label->` one head · `<-label->` both heads · `-label-` no heads, plus `~` dashed twins. Unlabeled headless lines are `--` / `~~`. No left-pointing arrows — write `B -> A`, never `A <- B`. A tag on the edge tail (`crew: Hold`) colors the line. Both ends must attach.
-
-### Boxes
-
-`[Brackets]` = a **box** (labeled group frame) — the only bracket meaning in sketch. Label mandatory; one level only (no nested boxes); taggable (frame tints, cascades to children, individual overrides); bare `collapsed` folds it to a card with the collapse-bar and edges re-target the card. Interactive fold/unfold in the app; static export renders the authored state.
-
-### Node Metadata
-
-| Key         | Type           | Default                 | Description                                              |
-| ----------- | -------------- | ----------------------- | -------------------------------------------------------- |
-| `at`        | `C R` integers | flow-placed             | Half-slot position (origin-normalized)                   |
-| `collapsed` | flag           | —                       | Box only — start folded (collapse-bar)                   |
-| `<tag>`     | declared value | untagged (neutral gray) | Tag value (cascades from box; edge tails color the line) |
-
-### Directives
-
-| Directive   | Effect               |
-| ----------- | -------------------- |
-| `no-legend` | Hide the tag legend. |
-
-### Interactivity vs export
-
-In the desktop and web app a sketch opens in the **canvas editor** (the code pane hides behind a toggle); boxes fold/unfold interactively. Static SVG / PNG export renders the authored state — the same interactive-vs-export split the map, treemap, and block charts use.
-
----
-
 ## 24Ea. Whiteboard Diagrams
 
 <!-- TYPE:whiteboard -->
@@ -3991,11 +3955,11 @@ In the desktop and web app a sketch opens in the **canvas editor** (the code pan
 
 <!-- TIPS start -->
 
-**Styling tips:** Whiteboard is a canvas-first format: people draw on it, and pen strokes (`ink` lines) only ever come from drawing — never write an `ink` line. Generate the readable parts only: `rectangle`, `ellipse`, `database`, `queue` with a label, `at: X Y` (top-left, integer pixels) and `size: W H`; `arrow` with `from: X Y, to: X Y` and an optional label, or `line` the same way for a connection with no head; add `style: dashed` to an arrow or line for a tentative or optional link; `heads: both` for a two-way arrow; `bend: 40` (px, sign picks the side) to curve a link around something in its way; `text` at a point; `note` with `at: X Y` for a sticky-note comment or open question (a 160 × 99 yellow card by default; `size:` and `color:` are optional). A shape label or a note wraps to its width on its own, so never break a sentence by hand to fit; for separate lines (a heading, a list), drop the inline label and indent each line two spaces under the element line. Leave ~40px between shapes and keep boards small (under ~15 elements). Colours are palette names (red, green, blue, teal, purple, orange, yellow, cyan, gray); leave colour off for the default ink. An arrow or line end placed inside a shape or note attaches to it and is drawn to its border, so point ends at shape centres. `no-notes` hides every note when the board is shown. Reach for `whiteboard` for a loose drawing someone will scribble over; reach for `sketch` for tagged shapes on a grid, and `boxes-and-lines` when topology should auto-lay-out.
+**Styling tips:** Whiteboard is a canvas-first format: people draw on it, and pen strokes (`ink` lines) only ever come from drawing — never write an `ink` line. Generate the readable parts only: `rectangle`, `ellipse`, `database`, `queue`, `file` (a page with a wavy bottom, for a document or file) with a label, `at: X Y` (top-left, integer pixels) and `size: W H`; `arrow` with `from: X Y, to: X Y` and an optional label, or `line` the same way for a connection with no head; add `style: dashed` to an arrow or line for a tentative or optional link; `heads: both` for a two-way arrow; `bend: 40` (px, sign picks the side) to curve a link around something in its way; `text` at a point; `note` with `at: X Y` for a sticky-note comment or open question (a 160 × 99 yellow card by default; `size:` and `color:` are optional). A shape label or a note wraps to its width on its own, so never break a sentence by hand to fit; for separate lines (a heading, a list), drop the inline label and indent each line two spaces under the element line. Leave ~40px between shapes and keep boards small (under ~15 elements). Colours are palette names (red, green, blue, teal, purple, orange, yellow, cyan, gray); leave colour off for the default ink. An arrow or line end placed inside a shape or note attaches to it and is drawn to its border, so point ends at shape centres. `no-notes` hides every note when the board is shown. Reach for `whiteboard` for a loose drawing someone will scribble over; reach for `boxes-and-lines` when topology should auto-lay-out.
 
 <!-- TIPS end -->
 
-A **free-form whiteboard** on an infinite canvas: rectangles, ellipses, databases, queues, sticky notes, free arrows and lines, text, pasted images and freehand ink, each at absolute pixel positions. Shapes are clean vector outlines; only ink looks hand-made. The export is cropped to the drawing plus a margin. Elements draw in kind bands, bottom to top: images; shapes, sticky notes, arrows and lines (`rectangle`, `ellipse`, `database`, `queue`, `note`, `arrow`, `line`); text; ink. A band always draws above the one before it. Inside a band, file order decides: a later line draws on top, so shapes, notes and arrows stack either way — except that an arrow or line always draws just above the latest shape or note it is attached to. No syntax sets the band.
+A **free-form whiteboard** on an infinite canvas: rectangles, ellipses, databases, queues, files, sticky notes, free arrows and lines, text, pasted images and freehand ink, each at absolute pixel positions. Shapes are clean vector outlines; only ink looks hand-made. The export is cropped to the drawing plus a margin. Elements draw in kind bands, bottom to top: images; shapes, sticky notes, arrows and lines (`rectangle`, `ellipse`, `database`, `queue`, `file`, `note`, `arrow`, `line`); text; ink. A band always draws above the one before it. Inside a band, file order decides: a later line draws on top, so shapes, notes and arrows stack either way — except that an arrow or line always draws just above the latest shape or note it is attached to. No syntax sets the band.
 
 ### Declaration
 
@@ -4805,16 +4769,16 @@ API description: Main gateway
 
 Some constructs _look_ universal but are scoped to specific chart types. Don't transplant them across charts.
 
-| Construct                                     | Scope                                                                                                                                     |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Bare `collapsed` trailing flag (§1.8)         | sequence, infra, gantt, kanban, mindmap, pert, state, c4, event-line (eras), block, sketch, wireframe. Legacy: `collapsed: true` metadata |
-| Same-line / indented metadata on declarations | all chart types except flowchart, state, data charts (§1.4)                                                                               |
-| Trailing-keyword flag list                    | wireframe only (§19)                                                                                                                      |
-| `progress: <N>` key                           | gantt only (§13)                                                                                                                          |
-| `score: <N>` + `emotion: <Word>` keys         | journey-map only (§22)                                                                                                                    |
-| `description: <text>` shorthand for layers    | pyramid, ring (§23, §24)                                                                                                                  |
-| `milestone` keyword                           | **removed** — use `<name> 0` (§13A)                                                                                                       |
-| `\|` operator as metadata delimiter           | **removed** (§1.4). Surviving uses: wireframe `{A \| B}` braces, in-arrow `A -file\|name-> B`, quoted `"Order \| Items"`                  |
+| Construct                                     | Scope                                                                                                                             |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Bare `collapsed` trailing flag (§1.8)         | sequence, infra, gantt, kanban, mindmap, pert, state, c4, event-line (eras), block, wireframe. Legacy: `collapsed: true` metadata |
+| Same-line / indented metadata on declarations | all chart types except flowchart, state, data charts (§1.4)                                                                       |
+| Trailing-keyword flag list                    | wireframe only (§19)                                                                                                              |
+| `progress: <N>` key                           | gantt only (§13)                                                                                                                  |
+| `score: <N>` + `emotion: <Word>` keys         | journey-map only (§22)                                                                                                            |
+| `description: <text>` shorthand for layers    | pyramid, ring (§23, §24)                                                                                                          |
+| `milestone` keyword                           | **removed** — use `<name> 0` (§13A)                                                                                               |
+| `\|` operator as metadata delimiter           | **removed** (§1.4). Surviving uses: wireframe `{A \| B}` braces, in-arrow `A -file\|name-> B`, quoted `"Order \| Items"`          |
 
 ### 26.4 Quoted Names + Aliases — Pick One
 

package/gallery/fixtures/whiteboard.dgmo

@@ -9,6 +9,7 @@ rectangle Magic link at: 60 250, size: 180 70, color: green
 arrow emails a code from: 150 95, to: 150 285, color: green
 database Users at: 420 160, size: 140 100, color: purple, fill: solid
 queue Email jobs at: 300 380, size: 200 64, color: orange
+file Audit log at: 60 400, size: 140 80, color: gray
 arrow from: 150 285, to: 400 412, color: orange, bend: 50
 text keep it to ONE screen at: 62 184
 text 2FA here?? at: 560 -4, color: red

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "author": "Diagrammo LLC",