figdown 0.1.0-rc.1

package/EXPRESSING.md

@@ -0,0 +1,119 @@
+# Expressing intent in FigDown — author index
+
+> **Non-normative index.** Spec is normative: [spec/syntax-draft.md](spec/syntax-draft.md).
+> Full authoring workflow: [AUTHORING.md](AUTHORING.md) (pick a template first, then come back here).
+> Layout hints: [LAYOUT-GUIDE.md](LAYOUT-GUIDE.md).
+> Build and validate: `node tools/build-svg.js X.fd` — errors are `Line N: message`.
+>
+> 繁體中文版：[EXPRESSING.zh-tw.md](EXPRESSING.zh-tw.md)
+
+Purpose: one-line lookup — "I need to show X → use Y." One row per intent. Notes column = a caveat or scope limit, not a tutorial.
+
+---
+
+## Structure & composition
+
+| I need to show… | Use | Notes |
+|---|---|---|
+| containment — node belongs inside a box | `group g "Label"` + `node n "…" in=g` | one level of nesting only (spec §2.2); for deeper, represent the inner group as a proxy node |
+| set membership / category (color + legend) | `class c "meaning" color=… style=…` + `class=c` on members | legend derives automatically; bare `color=` carries no named meaning |
+| one class used on both nodes and edges | same `class c "meaning" color=…` on each | `color=` **fills** a node box but **strokes** an edge line; `stroke=` outlines a node and is **ignored** on an edge; `style=` applies to both. Pick `color=` when the class must read on edges |
+| hierarchy / tree | directed `edge` chain; `flow down` to orient | the edges carry the tree; group is for spatial containment, not hierarchy |
+| adjacency without a link | `in=` on the same `group`, no `edge` between them | the shared frame communicates co-location |
+| cross-cutting category spanning groups | `class` + `class=` on elements in different groups | one class can mark nodes, edges, and fields across the whole document |
+| system boundary / inside vs outside | `boundary ext "label"` + edges to/from it; internal nodes in a `group` | `boundary` is never drawn as a shape — the edge ends open |
+| ownership zones / domain coloring | `class zone "Owner" color=…` on a `group` or its members | assign to the group itself to color the frame |
+| conditional or optional element (standby link, optional component) | `class cond "Condition text" style=dashed` + `class=cond` on the element | `style=dashed` alone states nothing (R57); write the condition in the class label |
+| one-level nesting limit | `in=` on `node`; `group … in=…` is a line error | for two levels: add a proxy `node` representing the inner group |
+| layer stack or spatial arrangement where order is knowledge | `edge` chain + `flow down`, or single-row `table`; state the order in prose | no spatial-arrangement construct yet — see Known limits OQ-S25 |
+| slot map / position in a spatial grid | state positions in label text + `pin` in render zone | `pin` is geometry only — use a `table` for anything a reader must count or address |
+
+---
+
+## Flow & behaviour
+
+| I need to show… | Use | Notes |
+|---|---|---|
+| ordered steps | directed `edge` chain; order = edge direction | `flow right` or `flow down` sets reading axis |
+| decision + branches | `node q "…" shape=diamond` + `edge q -[yes]-> …` / `edge q -[no]-> …` | `shape=diamond` is geometry only (D7); declare a `class` if the decision role carries meaning (OQ-S18) |
+| loop / retry | directed cycle back to an earlier node; condition in the mid-label | a back-edge crossing is expected and correct |
+| error paths | `class err "Error path" style=dashed` + `class=err` on error edges | separate semantic category from the happy path |
+| state machine / lifecycle | nodes as states + labelled directed edges as transitions | no sequence genre yet; order meaning rides on labels |
+| pipeline stages | `node` per stage + `boundary` at the mouths + `flow right` + `rank` | `boundary` marks where data enters/leaves the figure |
+| event → action | `edge src -[event]-> tgt` | mid-label is the trigger; head-label can name the action |
+| precedence / partial order | a DAG of directed edges | absence of an edge means no stated constraint |
+| fan-out / fan-in | edges from/to a common node | AND-vs-XOR join discipline: declare a `class` (OQ-S18 — no first-class gateway yet) |
+| message exchange between parties | nodes as parties + labelled directed edges; ordinal labels for ordering | strict ordering: number labels consistently (OQ-S18) — see Known limits |
+| a label too wide for its diamond / ellipse / cylinder | nothing — shapes size themselves from their **inscribed** area | do not add `size`; see the note below |
+
+> **Delete `size` lines added to make a shape fit its text.** Non-rectangular
+> shapes were once sized by their bounding box, so authors added `size` to stop
+> `diamond` and `ellipse` labels overflowing. That is fixed. `size` is rigid and
+> must be re-tuned whenever a label changes, so removing it is a maintenance
+> win. Verified on production documents and reproducible here: strip every
+> `size` line from this repo's examples that carry them and
+> `node tools/shape-check.js --strict` still reports zero containment failures.
+> The drawing is *not* byte-identical — the canvas shifts — but it stays
+> geometrically correct. Layout-motivated `size` ([LAYOUT-GUIDE.md](LAYOUT-GUIDE.md) rung 3) is a separate question.
+
+---
+
+## Data & format
+
+| I need to show… | Use | Notes |
+|---|---|---|
+| bit-level register / header | `bitfield id "label" [unit=32] [numbering=lsb0\|msb0]` + `field name width` | default `lsb0` (hardware style); use `msb0` for IETF RFC convention |
+| byte-level frame with no bit ruler | single-row `table`, cell order = wire order | `bitfield` adds a bit ruler — use `table` when bits are not the unit |
+| struct / record layout | `table` with `Offset \| Field \| Type \| Width \| Notes` columns | cell order is authoritative; `colw` for presentation only |
+| memory map as lookup | `table` with address ranges + `cell r,c color=` for highlights | |
+| lookup / translation table | `table` + `cell r,c color=` for highlights | |
+| mapping between two node sets | `edge` + `class` naming the relation | the class label is the relation name; edges draw the pairs |
+| pointer chains between nodes | directed `edge` chain | can't target a table cell — see Known limits OQ-S17 |
+| optional / variable-length fields | `field name width optional` or `field name *` in a `bitfield` | `optional` flag triggers reader branching (R48); `*` fills row remainder |
+| endianness / dual ruler convention | two `bitfield` blocks with different `numbering=` | `lsb0` and `msb0` produce different rulers from the same fields |
+| mode-dependent field meaning | separate labelled `bitfield` blocks + `note=` per field | no first-class variant yet — see Known limits OQ-S9 |
+| nested encapsulation / multi-tier header | `table` with `||` colspan spans in header rows | `^^` for rowspan; cell order = wire order |
+
+---
+
+## Quantity, time & relation
+
+| I need to show… | Use | Notes |
+|---|---|---|
+| proportion of a whole / fill level | `fill N%  in=g color=…` on a `group` or `node` | label the node with the current value; `fill` is the band |
+| threshold / watermark | `line "label" in=g at=N%` | `line` requires `in=` to a `group` (not a bare node) |
+| quantity comparison | `table` with numeric columns | `▁▃▅▇` Unicode blocks as sparklines in cells (OQ-S12) |
+| signal values over time | `wave id "label"` + `signal name chars` (one char = one tick) | lane alphabet: `0 1 p n x = . 0-9` |
+| event ordering without exact times | directed edges with ordinal mid-labels (`-[1: SYN]->`) | number labels consistently; no sequence genre yet |
+| visual code / legend | `class` — legend derives automatically from declaration order | each `class` line gives swatch + meaning text |
+| annotation explaining why | `node note "…" style=dashed` + dashed edge to the target | no first-class callout yet — see Known limits OQ-S14 |
+| cross-references within a scene | `edge` + `class` naming the relation | can't reference a table cell or bitfield field — see Known limits OQ-S17 / OQ-S20 |
+| units | state them in the label or column header | no machine-readable unit type; interim: text in the label |
+| trends / rates | `table` with a values column; `▁▃▅▇` for sparklines | charts are out of scope (D11/R46) — keep the raster + prose |
+
+---
+
+## Known limits (v0.1)
+
+Each entry: what cannot be expressed today · OQ reference · sanctioned interim workaround.
+
+- **same entity in two views** — no way to assert two nodes are the same participant; OQ pending; interim: shared `class` + a note stating the identity.
+- **strict message ordering** — order carried only by label numbering convention; sequence genre candidate (v0.2, OQ-S18); interim: number labels consistently (e.g. `1: SYN`, `2: SYN-ACK`).
+- **first-class callout / annotation** — a callout is structurally a node; OQ-S14; interim: `node note "…" style=dashed` + dashed `edge`.
+- **cell anchors** — an `edge` cannot target a `table` cell or `bitfield` field; OQ-S17; interim: whole-table relation + cell name in the edge label.
+- **cross-block references** — no locator from one typed block to another; OQ-S20; interim: prose note or a linking `edge` between the host nodes.
+- **byte-unit packet construct** — `bitfield` adds an unwanted bit ruler; OQ-S24; interim: single-row `table`.
+- **meaningful arrangement** (layer stacks, floorplans, proportional memory maps) — no declared-arrangement construct; OQ-S25/R57; interim: state the arrangement meaning in prose + read the render zone.
+- **wave timing parameters** (setup/hold spans) — no named span between signal events; OQ-S23; interim: keep the original raster + prose.
+- **mode-dependent field variants** — same bit range, different decode per mode; OQ-S9; interim: separate labelled `bitfield` blocks + `note=`.
+- **multiplicity / machine-readable units** — no count or unit type; pending corpus frequency; interim: state them in label text.
+- **decision/gateway role vocabulary** (AND vs XOR) — `shape=diamond` is geometry only; OQ-S18; interim: declare a `class` naming the join discipline.
+- **conditional presence in scene elements** — `optional` is a `bitfield`-only flag; `node a "A" optional` is a line error; v0.2 candidate; interim: `class cond "condition text" style=dashed` + `class=cond`.
+- **mutually exclusive `bitfield` interpretations — a correctness trap, not a cosmetic one.** `wrap` is presentation-only and never reorders or skips bits, so alternative decodings of the *same* bits stacked with `wrap` are read by a machine as one long contiguous sequence: an 18-bit register drawn as eight alternative encodings computes as 144 bits. There is no union/case construct and nothing warns. Open question: what a variant/discriminator construct should look like (adjacent to OQ-S9). Interim: **one `bitfield` block per alternative**, each labelled with the discriminator value that selects it (`bitfield ctl_a "Control — mode=0 (18 bits)" unit=18`).
+- **aside / non-participating annotation** — no node kind that comments on a figure without joining its graph; a free `node` parses but reads as a participant. Open question: whether an aside is a node kind or a document-level construct. Interim: prose beside the figure, or `node note "…" style=dashed` + a dashed `edge` (which does join the graph).
+- **repeated-subgraph template** — no way to declare a sub-structure once and instantiate it *n* times. Open question: whether templating belongs in the language at all or in the generator above it. Interim: write each instance out.
+- **two-level group nesting** — `group … in=…` is a line error; nesting is one level in v0.1. Open question: whether deeper nesting needs new syntax or only a renderer change. Interim: a proxy `node` for the inner group.
+- **mux / selector shape** — `shape=` is a closed geometric set (`box|rounded|circle|ellipse|cloud|diamond|cylinder`); `shape=mux` is a line error. Open question: whether the mux trapezoid is geometry (admissible under D7) or a domain noun (excluded). Interim: `shape=diamond` or a box, with the selector role in the label or a `class`.
+- **blank / idle lane character in `wave`** — the lane alphabet is closed and has no "no activity" tick (`_` and `z` are line errors). Authors reach for `x`, which draws as an unknown-value hatch — a different claim. Open question: whether idle is a lane value or a `gap`-like marker. Interim: `x` plus a `labels=` entry or note saying it means idle.
+- **charts / plots** — deliberately out of scope (D11/R46); keep the raster and describe in prose or a `table`.
+- **closed-world readings** (anything not drawn is denied) — absence leaves no trace in the syntax; no tool can catch this. When a figure's meaning depends on what is NOT drawn, declare the closed-world reading explicitly and state every prohibition in a table row or note (R59 addendum).

package/LAYOUT-GUIDE.md

@@ -0,0 +1,367 @@
+# Layout Guide — arranging FigDown figures for human readers
+
+> **Non-normative recommendation.** Nothing here is required. A `.fd` with zero
+> layout lines is fully conforming (spec §3: auto-layout is the default). This
+> guide teaches how to **think** about arranging a figure for human readers
+> using the render zone. All layout calls are maintainer recommendations, not
+> mandates.
+>
+> Lessons come from field observation of a downstream authoring pass.
+>
+> 繁體中文版：[LAYOUT-GUIDE.zh-tw.md](LAYOUT-GUIDE.zh-tw.md)
+
+## 1. The two-zone mindset
+
+FigDown has two zones (spec §3, R43): the **semantic zone** (before `render`)
+holds nodes, edges, groups, and classes — the complete knowledge of what the
+figure means. The **rendering zone** (after `render`) holds only `pin`, `size`,
+`routing`, and `route` — instructions for how that knowledge lands on a canvas.
+
+Key invariant (R25, R37): stripping every `pin`/`size`/`routing`/`route` line
+must leave a document that still parses, renders under auto-layout, and
+expresses the identical structure and relationships. No knowledge lives in the
+render zone. If removing a `pin` changes what an AI reader can learn, the
+position was encoding meaning that should live in text instead.
+
+Auto-layout is a **default**, not a promise. When the original figure's spatial
+arrangement carries reading order — left-to-right pipeline stages, top-down
+layer stack — reproduce that orientation in the render zone so human readers
+follow the same path.
+
+Note: `flow` and `rank` are **semantic** directives (R43); they go before
+`render`. Only `pin`, `size`, `routing`, and `route` are legal after `render`.
+
+## 2. The escalation ladder
+
+Try each rung, rebuild (`node tools/build-svg.js X.fd`), and **stop as soon
+as the figure reads clearly.** The lowest rung that works is the right choice.
+
+| Rung | Directive | When |
+|------|-----------|------|
+| 0 | *(nothing)* | Small graphs or figures where spatial order carries no meaning |
+| 1 | `flow right\|down\|left\|up` | Direction of the figure — one line before `render` |
+| 2 | `rank a b c` | Pull parallel peers onto one row/column; before `render` |
+| 3 | `pin … at=x,y` / `size … w= h=` | Topology/spatial where placement IS the message |
+| 4 | `routing orthogonal` / `route … via=` | Edge geometry last; dense buses or trunk lines |
+
+**Rung 1 is where authoring should begin.** A scene document should almost
+always carry a `flow` line. It costs one line and gives the layout engine the
+single most useful piece of intent it can receive. "Write nothing" (rung 0)
+is reasonable only for a figure small enough that direction is obvious — or
+for a figure where spatial order carries no meaning at all. Field evidence
+confirms this is already the norm: in the first independent production corpus,
+all 20 scene documents declare `flow` explicitly (15 `flow down`, 5
+`flow right`); not one relies on the template default.
+
+**What the direction expresses.** `flow down` reads as a portrait figure whose
+sequence runs top-to-bottom — the common shape for decision and process
+figures. `flow right` reads as a landscape figure whose sequence runs
+left-to-right — the common shape for pipelines and layered architectures. The
+direction is a reading-order statement to the human, not only a layout knob:
+pick the one that matches how the figure should be read, not merely how it
+should be arranged. `flow` only declares the visual reading axis for
+relationships that already exist; it does not create semantic precedence,
+sequence, or connectivity — process order still comes from `edge` declarations
+and typed-block declaration order. Honest limit: for a mesh or a hub topology with no
+dominant sequence, `flow` sets the primary layering axis but does not by
+itself determine the overall aspect. That gap — controlling aspect and
+wrapping on figures with no dominant sequence — is tracked in the engine
+backlog (long-chain wrapping / aspect control, item 10) and there is no
+aspect keyword today.
+
+Higher rungs cost future edit effort (every `pin` is a promise; §5).
+
+## 3. Patterns by figure family
+
+Each sketch is minimal and verified against `build-svg.js`. Keywords used:
+`flow`, `rank`, `pin`, `routing`, `route` — all from spec §3.
+
+### Sequential pipeline — `flow` + `rank`
+
+```figdown
+figdown 0.1 block
+title Packet Pipeline
+node rx  "RX"
+node par "Parser"
+node pol "Policy"
+node tx  "TX"
+edge rx -> par
+edge par -> pol
+edge pol -> tx
+flow right
+rank rx par pol tx
+```
+
+Wrap long chains: one `rank` per stage row, let auto-layout stack the rows.
+
+### Decision flowchart — main path on one axis
+
+```figdown
+figdown 0.1 flowchart
+node start "Start"  shape=rounded
+node check "Header valid?" shape=diamond
+node proc  "Process"
+node drop  "Drop"   shape=rounded
+node done  "Done"   shape=rounded
+edge start -> check
+edge check -[yes]-> proc
+edge check -[no]->  drop
+edge proc  -> done
+flow down
+rank start check proc done
+```
+
+`rank` the mainline; side-exit branches fall perpendicular under auto-layout.
+
+### Hierarchy / layers — one `rank` per layer
+
+```figdown
+figdown 0.1 block
+group app   "Application"
+group net   "Network"
+group link  "Link"
+node  http  "HTTP"  in=app
+node  tcp   "TCP"   in=app
+node  ip    "IP"    in=net
+node  eth   "Ethernet" in=link
+edge http -> tcp
+edge tcp  -> ip
+edge ip   -> eth
+flow down
+rank http tcp
+```
+
+Layer labels go in `group` names or node labels, not only in vertical position.
+
+### Topology / spatial — pin the anchors
+
+```figdown
+figdown 0.1 topology
+node hub  "Core"
+node a    "ToR-A"
+node b    "ToR-B"
+node c    "ToR-C"
+edge hub -> a
+edge hub -> b
+edge hub -> c
+render
+pin hub at=300,200
+pin a   at=150,80
+pin b   at=450,80
+pin c   at=300,360
+```
+
+Pin hub, corners, or geography-defining nodes; let auto-layout fill the rest.
+
+### Dense buses — `routing orthogonal` + `route`
+
+```figdown
+figdown 0.1 block
+node cpu "CPU"
+node mem "DRAM"
+node dma "DMA"
+node bus "Bus"
+edge cpu -> bus
+edge mem -> bus
+edge dma -> bus
+flow down
+render
+routing orthogonal
+route cpu -> bus via=200,100;200,200
+```
+
+## 4. Two-level pins (groups as layout modules)
+
+Spec §3 (D6): a **pinned group** anchors its local origin in canvas px; a
+**pinned member** is group-local. Moving a group is one edit (`pin g at=…`)
+and never disturbs another group. Use groups as layout modules for figures
+with independent spatial regions.
+
+```figdown
+group ingress "Ingress Pipeline"
+node  rx  "RX"    in=ingress
+node  par "Parse" in=ingress
+group egress  "Egress Pipeline"
+node  sch "Sched" in=egress
+node  tx  "TX"    in=egress
+render
+pin ingress at=50,100
+pin rx      at=0,0
+pin par     at=120,0
+pin egress  at=50,250
+pin sch     at=0,0
+pin tx      at=120,0
+```
+
+## 5. The iteration loop for agents
+
+```
+author semantics
+  → build:  node tools/build-svg.js X.fd
+  → judge:  eyeball + node tools/layout-lint.js X.svg  (6 metrics; --max-score gate)
+  → if not clear: add ONE rung (§2) and repeat
+  → stop when it reads well
+```
+
+Before committing layout lines: `node tools/r25-check.js X.fd` — flags nodes whose only relationship to the rest of the figure is geometric (R25 strip test).
+
+**Over-pinning warning (R8).** Every `pin` is a promise future edits must
+keep. Pin only the elements whose position IS the message (the hub of a star,
+the corners of a geographic map). Auto-layout keeps improving; engine-backlog
+items will lift rung-0 quality without manual pins needing updates.
+
+## 6. When not to fight the layout
+
+If semantics are complete and the figure is legible, ship it. Visual difference
+from the original is not semantic loss (R37): the figure states the same
+relationships regardless of where the hub sits on the canvas. Reserve layout
+effort for figures where **arrangement carries meaning** — where a reader
+draws a different conclusion from a different arrangement.
+
+A back-edge crossing in a retry loop (e.g. a `no` branch looping back to an
+earlier step) is structural: no rung of the escalation ladder removes it, and
+the crossing count is the same with or without `flow down`. That is a
+legitimate stopping point — the graph encodes a cycle; the lint score reflects
+it correctly.
+
+## 7. Before / after: the same semantics, different render zones
+
+The first two entries are pairs, byte-identical in the semantic zone. The third is the counter-case: no pair, because the fix was not in the render zone at all. Score = `cross×2 + thru×3 + novlp×3 + lblcol×2 + coinc×2`.
+
+**Lint scores are a smoke alarm, not a judge.** The srl-evpn-irb pair below shows lint getting *worse* (ink/e 111→117) while the figure becomes dramatically more readable — because the metrics do not measure group containment, overlap, or reading order. Always look at the render; the ladder ends when a human can read it. One variant of that example scored better on lint but had lost its column alignment — and the alignment was the peer signal; only looking at the render caught it.
+
+### Leaf-spine fabric — `+flow down +rank sp1 sp2 +rank lf1 lf2 lf3`
+
+Eight-node VXLAN/EVPN topology. Auto-layout scatters spines and leaves; three semantic directives align them into clear tiers. Lint score is the same; edge length halves (144→77 ink/e).
+
+| variant | cross | ink/e | score |
+|---------|-------|-------|-------|
+| auto    | 3 | 144 | 6 |
+| `+flow +rank` | 3 | 77 | 6 |
+
+[auto .fd](examples/layout-compare/evpn-fabric-auto.fd) · [auto .svg](examples/layout-compare/evpn-fabric-auto.svg) · [tuned .fd](examples/layout-compare/evpn-fabric-tuned.fd) · [tuned .svg](examples/layout-compare/evpn-fabric-tuned.svg)
+
+### srl-evpn-irb — two-level pins + groups (20 layout lines)
+
+Sixteen-node EVPN-VXLAN IRB figure with three leaf groups. Auto-layout lets group boxes overlap each other and member nodes escape their frames, producing a tall chaotic column (561×907 px). The tuned version pins each group as a layout module (spec §3 D6: a pinned group anchors its local origin in canvas px; members are group-local), giving three clean leaf boxes under the fabric cloud (1228×608 px). Aspect ratio flips from portrait to landscape. Lint ink/e gets *worse* (111→117) while the figure becomes unambiguous — the metrics do not measure group containment or overlap.
+
+| variant | cross | novlp | ink/e | score |
+|---------|-------|-------|-------|-------|
+| auto    | 0 | 1 | 111 | 3 |
+| `+pin` ×20 | 0 | 1 | 117 | 3 |
+
+[auto .fd](examples/layout-compare/srl-evpn-irb-auto.fd) · [auto .svg](examples/layout-compare/srl-evpn-irb-auto.svg) · [tuned .fd](examples/layout-compare/srl-evpn-irb-tuned.fd) · [tuned .svg](examples/layout-compare/srl-evpn-irb-tuned.svg)
+
+### vxlan-encap — when layout tuning is the wrong fix (0 layout lines)
+
+This one used to be listed here as a third before/after pair, and that was the
+mistake. The packet-header figure was authored as fifteen free `node`s; auto-layout
+stacked them into a 415×1704 px vertical column, so 19 `pin` lines were added to
+lay the fields out left to right in byte order (896×736 px). The render looked
+right — and the document was broken, because **the byte order existed only in the
+`pin` x-coordinates**. Nothing in the semantic zone said that Outer MAC precedes
+Outer IP precedes UDP precedes VXLAN, or where the original L2 frame was inserted.
+The pins were not describing an arrangement; they were the only copy of the
+meaning (R37: meaning must never live in geometry).
+
+The fix was not a better rung on the ladder — it was **a different construct**. Each
+frame is now a single-row `table` whose cell order *is* the on-the-wire order, with
+a header-tier span for the nested original frame and `class` marks carrying the
+field roles ([vxlan-encap.fd](examples/vxlan-encap.fd)). The document now needs
+**zero** `pin`/`size`/`flow`/`rank` lines and renders at 1036×650 px.
+
+**The diagnostic — run the R25 strip test before you tune.** Delete every
+`flow`/`rank`/`pin`/`size`/`routing`/`route` line and the bare `render`, then re-read
+what is left. If a fact you thought the figure stated is now unrecoverable — order,
+adjacency, containment, grouping — you have a semantics bug, and adding layout lines
+only hides it. Fix the construct: ordered sequences belong in `table`, `bitfield`, or
+explicit `edge` chains; containment belongs in `group` or a header span; categories
+belong in `class`. Reach for the ladder in §2 only once the stripped document already
+says everything the figure says.
+
+### Failure mode 4 — the render implies a relation the .fd never states
+
+The first three modes park meaning where a reader may ignore it (geometry, presentation,
+absence). This one is the mirror image: the `.fd` is correct but the picture asserts
+something extra to a human. Worked case from a private-VLAN example in this repo: the
+promiscuous port was drawn left with edges fanning out, so it read as upstream parent.
+In a private VLAN it is a peer port; the fix was symmetry — four equal-size peer frames,
+promiscuous port centred, router as `boundary` (the only genuinely external thing).
+
+R37 protects the agent, who reads syntax; the human reads geometry. A layout that
+implies false structure misleads exactly the reader the render exists for. No tool
+catches this — the author must look. Peers should look like peers: equal size and
+shared alignment carry peerhood without any syntax.
+
+**Fidelity checklist** (§5 loop asks "is it readable?"; these ask "is it honest?"):
+
+1. **Did I leave anything out?** Is any meaning riding on coordinates, on a stroke or
+   colour with no class, or on an edge I did not draw? (`tools/r25-check.js` catches
+   the first; the other two need your eyes.)
+2. **Did I add anything?** Does the arrangement imply a hierarchy, direction, sequence,
+   or grouping the semantic zone never states? Left-to-right and top-to-bottom both read
+   as precedence — check that you meant it.
+3. **Do the edges land where I meant?** An edge piercing a container frame reads as
+   targeting the container; a label crossed by a stroke reads as belonging to it.
+
+## 8. Cautions from a production corpus
+
+A five-way review rendered and inspected all 78 documents of a production
+corpus; below is what authors had to discover by trial and error, most-hit
+first. Expressing-side findings are in [EXPRESSING.md](EXPRESSING.md).
+
+**Group captions must be short.** Group rect and canvas are sized from member
+geometry only, so a caption wider than its members is clipped off the *canvas*
+— not merely outside the box, outside the image. Measured: two 35px members, a
+caption needing 368px, canvas 78px wide, caption cut mid-word. Until the
+renderer accounts for caption width, keep a caption no wider than its widest
+member row and put the detail in prose. Most-worked-around defect in the corpus.
+
+**Pick the direction for the figure's shape** (extends §2). A short linear
+pipeline — four to six stages, one terminal branch — reads better as
+`flow right` (measured 672×156 px) than as the tall narrow column `flow down`
+gives it (241×396 px). Reverse failure: a very wide multi-line outcome node
+pushes the canvas past a usable aspect ratio; wrap the label with `\n`
+(860×173 → 284×205 px) or move the detail into a companion `table`.
+
+**Long back-edges and bypasses need help.** An edge that skips several ranks
+detours to the canvas margin and picks up a waypoint per rank crossed — in a
+six-stage chain one `s1 -> s6` bypass becomes a ten-point polyline out at the
+margin; on large figures it reads as a many-bend staircase. Add a waypoint:
+
+```figdown
+node s1 "Stage 1"
+node s6 "Stage 6"
+edge s1 -[fast path]-> s6
+flow down
+render
+route s1 -> s6 via=200,240
+```
+
+Three points instead of ten. The `route` reference names endpoints and operator
+only, never the mid-label. If a bypass needs several waypoints, reconsider the
+structure instead.
+
+**Dense fan-in and fan-out.** Past about five edges between one node and one
+rank, the bundle renders as parallel runs with stacked labels (seven terminal
+targets measured 1079×156 px). Two options today: an explicit relay node, or a
+class that mutes the bundle so it recedes — `class discard "Discard reasons"
+color=#b8b6b0 style=dashed` on the terminal-bound edges, used to good effect by
+a corpus author. On an edge `color=` is what strokes the line (EXPRESSING.md).
+
+**Use `rank` for a lateral bypass, not for the mainline.** Under `flow down` a
+`rank` shares a *row*, so ranking the main chain flattens the figure sideways.
+`rank hit punt` lifts a decision's side exit onto the decision's own row and
+leaves the mainline vertical.
+
+**Two independent sub-diagrams side by side** — the `group` + `pin` pattern of
+§4. Two state machines, each a group pinned in canvas px with group-local
+members, render as two clean columns in one figure (verified in the corpus).
+Without it authors split into two figures unnecessarily.
+
+**When a figure is too big.** Around twenty nodes with a high crossing count a
+single figure stops being readable — guidance, not a rule. Split it and join
+the halves with `boundary` endpoints naming each other: `boundary cont
+"continues in Figure 2"` / `boundary cont "continued from Figure 1"`. A
+boundary states only that the edge crosses the figure's edge, so neither half
+implies a missing participant.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The FigDown Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.