figdown 0.1.0-rc.1

package/SHOWCASE.md

@@ -0,0 +1,421 @@
+# FigDown capability showcase — one source, two readers
+
+A FigDown figure is a single `.fd` text: a human opens the rendered SVG and
+*sees* it; an agent opens the same text and *reads* it — answering questions
+about widths, bit positions, message order, and decision logic without a
+pixel. These six classic networking figures each demonstrate one advantage as
+an agent skill: the agent writes the `.fd` (not brittle ASCII art), the human
+gets a clean SVG, and a second agent reads the text back to answer questions
+that would otherwise need OCR. The sixth — the complete TCP state machine —
+is the stress test: every state and every labelled transition of RFC 9293
+Figure 5 on one canvas.
+
+Each entry: the rendered SVG, the full `.fd`, one line on what the human sees,
+and questions an agent answers **from the text alone**. Every colour and
+dash is carried by a `class` whose label states its *meaning*; no meaning rides
+on geometry (`tools/r25-check.js --strict`) or presentation.
+
+Two of these figures — the TCP handshake and ARP resolution — are deliberately
+**mixed documents**: a scene block *and* a `table` block in one `.fd`, composed
+in document order (spec §8). This is the project's ruled answer for content the
+scene genre cannot yet carry first-class (per-endpoint lifeline state; a local
+cache transition): a second typed block carries it machine-readably, rather than
+letting it ride on geometry or absence.
+
+---
+
+## 1. TCP header — bit-exact machine-readable layout (`bitfield`)
+
+![TCP header](examples/showcase/tcp-header.svg)
+
+```figdown
+figdown 0.1 bitfield
+title TCP Header
+
+bitfield tcp "TCP Header (RFC 9293)" unit=32 numbering=msb0
+
+field "Source Port" 16
+field "Destination Port" 16
+field "Sequence Number" 32
+field "Acknowledgment Number" 32
+field "Data Offset" 4 note="header length in 32-bit words; min 5 (=20 bytes), max 15 (=60 bytes)"
+field Reserved 4 note="must be zero"
+field CWR 1
+field ECE 1
+field URG 1
+field ACK 1
+field PSH 1
+field RST 1
+field SYN 1 color=#fee2e2
+field FIN 1 color=#fee2e2
+field Window 16 note="receive window size in bytes (subject to window scaling option)"
+field Checksum 16
+field "Urgent Pointer" 16
+field Options 32 optional note="present iff Data Offset > 5; padded to a 32-bit boundary"
+field Data * note="variable-length payload; length from the IP datagram, not the TCP header"
+```
+
+**Human sees:** the RFC-style header — a 32-bit ruler, every field to width,
+the eight flags as individual bit cells, Options dashed (optional).
+
+**An agent answers from the text alone:**
+
+- *Q: Which bits carry the window size?* A: bits 112–127 — the sum of preceding
+  widths (96 for rows 1–3, then Data Offset 4 + Reserved 4 + eight 1-bit flags)
+  places `Window` next. Derived from field order/width, not the drawing.
+- *Q: Is SYN one bit or a byte?* A: one bit (`field SYN 1`); each of the eight
+  flags is a distinct, individually addressable 1-bit field.
+- *Q: When are Options present; what is the minimum header length?* A: present
+  iff Data Offset > 5 (`optional` + note); minimum header = 5 × 32-bit words =
+  20 bytes (Data Offset note).
+
+---
+
+## 2. TCP three-way handshake — labelled directed exchange (`topology`)
+
+![TCP handshake](examples/showcase/tcp-handshake.svg)
+
+```figdown
+figdown 0.1 topology
+title TCP Three-Way Handshake
+
+class setup "Connection-setup segment — carries SYN and/or ACK control flags" color=#2563eb
+class data  "Segment that also carries application data (piggybacked on the ACK)" color=#16a34a
+
+node client "Client (active open)"
+node server "Server (passive open, LISTEN)"
+
+flow right
+
+edge client -[1: SYN  seq=x]-> server class=setup
+edge server -[2: SYN,ACK  seq=y ack=x+1]-> client class=setup
+edge client -[3: ACK  ack=y+1  (+ data)]-> server class=data
+
+table state "Endpoint state after each segment (RFC 9293 §3.3.2 state names)"
+| Segment            | Client state          | Server state              |
+|--------------------|-----------------------|---------------------------|
+| start              | CLOSED                | LISTEN                    |
+| 1: SYN →           | SYN-SENT              | SYN-RECEIVED on receipt   |
+| 2: SYN,ACK ←       | ESTABLISHED on receipt| SYN-RECEIVED              |
+| 3: ACK →           | ESTABLISHED           | ESTABLISHED on receipt    |
+```
+
+This is a **mixed document**: a `topology` scene *and* a `table` in one `.fd`,
+composed in document order (spec §8). The canonical RFC 9293 figure carries the
+per-endpoint state on the lifelines; the topology genre has no lifeline-state
+construct, so the companion table carries those states machine-readably —
+composition is the ruled interim until the sequence genre lands.
+
+**Human sees:** two endpoints and three numbered segments — SYN out, SYN-ACK
+back, ACK (with piggybacked data) out — with a state table below tracking each
+endpoint's TCP state segment by segment.
+
+**An agent answers from the text alone:**
+
+- *Q: Which flags are set in segment 2?* A: SYN and ACK — from label `2: SYN,ACK`.
+- *Q: Which segment carries data, in which direction?* A: segment 3,
+  client → server — the only `data`-classed edge; its operator gives direction.
+- *Q: What ack number does the client send last?* A: `ack=y+1`, acknowledging
+  the server's SYN — from the segment-3 label.
+- *Q: What state is the server in after receiving segment 1?* A: SYN-RECEIVED —
+  row 2 of the state table (`1: SYN →`, Server state). Answerable only because
+  the companion table carries the RFC 9293 lifeline states.
+
+> **Honest limit (stated in the source):** message *order* rides on the 1/2/3
+> label ordinals, not a first-class construct — R37 does not treat numbering as
+> semantics. The v0.2 sequence genre (OQ-S18) closes this; see
+> [EXPRESSING.md](EXPRESSING.md), "strict message ordering".
+
+---
+
+## 3. L2 switch forwarding decision — protocol logic, readable (`flowchart`)
+
+![L2 forwarding logic](examples/showcase/l2-forwarding-logic.svg)
+
+```figdown
+figdown 0.1 flowchart
+title L2 Switch Forwarding Decision
+
+class forward "Forward — send the frame out the single learned egress port" color=#16a34a
+class flood   "Flood — send out every port in the VLAN except the ingress port" color=#2563eb
+class filter  "Filter — discard; destination is out the same port it arrived on" color=#dc2626
+
+boundary wire "from ingress port"
+
+node learn  "Learn source MAC:\nupdate MAC table\n(SA -> ingress port)"
+node lookup "Look up destination MAC\nin MAC table"
+node hit    "Entry found?"                                 shape=diamond
+node same   "Egress port ==\ningress port?"                shape=diamond
+node fwd    "Forward out\nlearned port"                    shape=rounded class=forward
+node fld    "Flood to all ports\nin VLAN except ingress"   shape=rounded class=flood
+node flt    "Filter (drop):\nsame-port destination"        shape=rounded class=filter
+
+flow down
+
+edge wire   -> learn
+edge learn  -> lookup
+edge lookup -> hit
+edge hit  -[no]->  fld
+edge hit  -[yes]-> same
+edge same -[yes]-> flt
+edge same -[no]->  fwd
+```
+
+**Human sees:** a frame from the ingress port → source-MAC learning →
+destination lookup → two decisions branching into three colour-coded outcomes.
+
+**An agent answers from the text alone:**
+
+- *Q: When does the switch flood?* A: on a lookup miss — `hit -[no]-> fld`, and
+  `fld` is the `flood` outcome (unknown-unicast and broadcast both take it).
+- *Q: A hit whose destination is behind the ingress port?* A: filtered
+  (dropped) — `same -[yes]-> flt`, class `filter`.
+- *Q: Does learning happen before or after lookup?* A: before — the chain is
+  `wire -> learn -> lookup`.
+
+Closed-world: the three `class`-marked terminals are the *only* outcomes; there
+is no unstated fourth path.
+
+---
+
+## 4. Ethernet II frame — byte order carried by syntax (`table`)
+
+![Ethernet frame](examples/showcase/ethernet-frame.svg)
+
+```figdown
+figdown 0.1 table
+title Ethernet II Frame — Untagged vs 802.1Q Tagged
+
+class tag "802.1Q VLAN tag (4 bytes), inserted after Source MAC; absent in an untagged frame" color=#dbeafe
+
+table eth "Ethernet II frame — column order = wire order (byte counts in the second header tier)"
+| Variant  | Destination MAC | Source MAC | 802.1Q Tag  | EtherType | Payload         | FCS       |
+| (frame)  | (6 bytes)       | (6 bytes)  | (4 bytes)   | (2 bytes) | (46-1500 bytes) | (4 bytes) |
+|----------|-----------------|------------|-------------|-----------|-----------------|-----------|
+| Untagged | DA              | SA         | (none)      | Type      | Data            | CRC-32    |
+| Tagged   | DA              | SA         | TPID 0x8100 + PCP/DEI/VID | Type | Data       | CRC-32    |
+colw 90 auto auto auto auto auto auto
+cell 1,4 class=tag
+cell 2,4 class=tag
+```
+
+**Human sees:** the frame in wire order left-to-right, two variants (untagged /
+802.1Q-tagged), the tag column highlighted at its insertion point.
+
+**An agent answers from the text alone:**
+
+- *Q: What field follows Source MAC on a tagged frame?* A: the 802.1Q Tag
+  (column 4, `class=tag`) — column order is wire order.
+- *Q: How many bytes does the tag add?* A: 4 (header tier `(4 bytes)` + class
+  label).
+- *Q: Untagged vs tagged?* A: the tag column is `(none)` vs
+  `TPID 0x8100 + PCP/DEI/VID` — absent, not zeroed (class label).
+
+The OQ-S24 sanctioned pattern: a byte-unit packet is a single-row `table`, so
+byte order lives in cell order (strip test survives), not a bit ruler.
+
+**One fact this figure cannot draw:** the FCS (CRC-32) is computed over
+Destination MAC through Payload inclusive — a coverage span across a
+*contiguous run of columns*. FigDown has no construct to annotate such a span
+(curly-brace grouping over a contiguous cell range is **OQ-S16**, v0.2), so the
+fact is stated in the `.fd` source comment and here in prose, never on geometry.
+
+---
+
+## 5. ARP resolution — boundary + class discipline (`topology`)
+
+![ARP resolution](examples/showcase/arp-resolution.svg)
+
+```figdown
+figdown 0.1 topology
+title ARP Resolution
+
+class bcast "Broadcast — delivered to every host on the LAN (dst MAC ff:ff:ff:ff:ff:ff)" color=#dc2626 style=dashed
+class ucast "Unicast — delivered only to the requester (dst MAC = A's MAC)" color=#16a34a
+
+node a "Host A\nwants MAC for B's IP"
+node b "Host B\nowns the target IP"
+
+boundary lan "rest of the LAN\n(hosts C, D, ...)"
+
+flow right
+
+edge a -[1: who-has B?  (broadcast)]-> b class=bcast
+edge a -[1: heard, ignored]-> lan class=bcast
+edge b -[2: B is at aa:bb:cc:...  A caches it]-> a class=ucast
+
+table cache "Host A's ARP cache — before and after the exchange"
+| Moment             | Entry                                   |
+|--------------------|-----------------------------------------|
+| before the exchange| (no entry for B's IP)                   |
+| after segment 2    | B's IP → aa:bb:cc:... , learned from the reply |
+```
+
+This too is a **mixed document** (scene + table in one `.fd`, document order):
+the cache *transition* is the figure's actual outcome, but it is a local state
+change on A rather than a message, so the companion table carries the
+before/after cache state machine-readably.
+
+**Human sees:** A broadcasts who-has (reaching B; the rest of the LAN hears it
+and ignores it), B replies by unicast and A caches the binding — broadcast
+dashed-red, unicast green, "rest of the LAN" an open boundary — with a cache
+table below showing the before/after state. The cache update is a local action
+on A, not a message, so it rides on the reply label, the cache table, and this
+prose rather than on an edge of its own.
+
+**An agent answers from the text alone:**
+
+- *Q: Broadcast or unicast request, and how do you know?* A: broadcast — the
+  request edges are `class=bcast` ("delivered to every host … dst MAC ff:…ff").
+  The dashed red is only presentation; the meaning is the class label.
+- *Q: Who receives the reply, and what does A do with it?* A: only Host A —
+  reply edge `class=ucast`, directed `b -> a`; the label states A caches the
+  IP → MAC binding on receipt.
+- *Q: Is "rest of the LAN" a participating host?* A: no — a `boundary`, stating
+  only that the broadcast crosses the figure's edge.
+- *Q: What does A's cache hold before the exchange?* A: nothing — row 1 of the
+  cache table (`before the exchange` → `(no entry for B's IP)`). Answerable only
+  because the companion table carries the before-state explicitly.
+
+> **Honest limit:** step order (1/2) rides on label ordinals, pending the v0.2
+> sequence genre (OQ-S18).
+
+---
+
+## 6. TCP connection state machine — every state, every transition (`flowchart`)
+
+![TCP state machine](examples/showcase/tcp-state-machine.svg)
+
+```figdown
+figdown 0.1 flowchart
+title TCP Connection State Machine (RFC 9293, Figure 5)
+
+class states  "A node IS a TCP state (RFC 9293 §3.3.2); the two CLOSED nodes are one state — no node-identity construct yet (OQ-S26)" color=#eef2ff
+class setup   "Connection-setup transition — opening the connection (OPEN, SYN exchange, first ACK)" color=#2563eb
+class client  "Active-close path (typically the client) — calls CLOSE first: FIN-WAIT-1 → FIN-WAIT-2 / CLOSING → TIME-WAIT → CLOSED" color=#dc2626
+class server  "Passive-close path (typically the server) — receives the peer's FIN first: CLOSE-WAIT → LAST-ACK → CLOSED" color=#16a34a
+class rare    "Rare / simultaneous transition — simultaneous open or close, or a reset/abort (RST, close from a half-open state)" color=#9333ea style=dashed
+
+node closed "CLOSED"        shape=rounded class=states
+node listen "LISTEN"        shape=rounded class=states
+node synsent "SYN-SENT"     shape=rounded class=states
+node synrcvd "SYN-RECEIVED" shape=rounded class=states
+node estab  "ESTABLISHED"   shape=rounded class=states
+node fw1    "FIN-WAIT-1"    shape=rounded class=states
+node fw2    "FIN-WAIT-2"    shape=rounded class=states
+node closing "CLOSING"      shape=rounded class=states
+node closewait "CLOSE-WAIT" shape=rounded class=states
+node lastack "LAST-ACK"     shape=rounded class=states
+node timewait "TIME-WAIT"   shape=rounded class=states
+node closed2 "CLOSED"       shape=rounded class=states
+
+flow down
+
+edge closed -[passive OPEN / create TCB]-> listen class=setup
+edge closed -[active OPEN / create TCB, snd SYN]-> synsent class=setup
+edge listen -[SEND / snd SYN]-> synsent class=setup
+edge listen -[rcv SYN / snd SYN,ACK]-> synrcvd class=setup
+edge synsent -[rcv SYN / snd SYN,ACK]-> synrcvd class=rare
+edge synsent -[rcv SYN,ACK / snd ACK]-> estab class=setup
+edge synrcvd -[rcv ACK of SYN / x]-> estab class=setup
+
+edge listen -[CLOSE / delete TCB]-> closed class=rare
+edge synsent -[CLOSE / delete TCB]-> closed class=rare
+edge synrcvd -[rcv RST (note 1) / x]-> listen class=rare
+
+edge synrcvd -[CLOSE / snd FIN]-> fw1 class=client
+edge estab -[CLOSE / snd FIN]-> fw1 class=client
+edge fw1 -[rcv ACK of FIN / x]-> fw2 class=client
+edge fw1 -[rcv FIN / snd ACK]-> closing class=client
+edge fw1 -[rcv FIN,ACK / snd ACK]-> timewait class=rare
+edge fw2 -[rcv FIN / snd ACK]-> timewait class=client
+edge closing -[rcv ACK of FIN / x]-> timewait class=client
+edge timewait -[Timeout=2MSL / delete TCB]-> closed2 class=client
+
+edge estab -[rcv FIN / snd ACK]-> closewait class=server
+edge closewait -[CLOSE / snd FIN]-> lastack class=server
+edge lastack -[rcv ACK of FIN / x]-> closed2 class=server
+
+render
+pin closed    at=394,20
+pin listen    at=394,150
+pin synrcvd   at=152,280
+pin synsent   at=607,280
+pin estab     at=376,410
+pin fw1       at=159,540
+pin closewait at=600,540
+pin fw2       at=159,670
+pin closing   at=311,670
+pin lastack   at=607,670
+pin timewait  at=304,800
+pin closed2   at=614,800
+route closed -> synsent via=790,38;790,298
+route listen -> closed via=300,105
+route synsent -> closed via=640,120
+```
+
+The `pin`/`route` block reproduces the canonical Figure 5 arrangement so a
+reader who knows the RFC diagram recognises it — but it is **presentation
+only** (`r25-check --strict` passes): strip every line after `render` and all
+11 states, all 21 transitions and their `event / action` labels survive on the
+`node`/`edge`/`class` lines. All meaning is in the edges; the pins are layout.
+
+**Human sees:** the whole RFC 9293 state diagram — CLOSED at top, the SYN pair
+flanking, ESTABLISHED centred, the active-close column falling left and the
+passive-close column right — four colour-coded transition families (blue setup,
+red active-close, green passive-close, purple rare/simultaneous dashed), every
+arrow carrying its `event / action`.
+
+**An agent answers from the text alone:**
+
+- *Q: What event takes ESTABLISHED to CLOSE-WAIT, and what does the endpoint
+  send?* A: `rcv FIN / snd ACK` — one edge label
+  (`edge estab -[rcv FIN / snd ACK]-> closewait`).
+- *Q: From FIN-WAIT-1, how many ways lead to TIME-WAIT and under what
+  conditions?* A: two. Directly, `rcv FIN,ACK / snd ACK` (the RFC Note-2
+  transition, `fw1 -> timewait`); and via FIN-WAIT-2, `rcv ACK of FIN / x` then
+  `rcv FIN / snd ACK` (`fw1 -> fw2 -> timewait`). A third path runs via CLOSING
+  (`rcv FIN / snd ACK` then `rcv ACK of FIN / x`). All read off the edges.
+- *Q: How long does TIME-WAIT last and what happens after?* A: `Timeout=2MSL`,
+  then `delete TCB` → CLOSED (`timewait -[Timeout=2MSL / delete TCB]-> closed2`).
+- *Q: Which transitions belong to the typical server (passive-close) path?*
+  A: the three `class=server` edges — `ESTABLISHED → CLOSE-WAIT`,
+  `CLOSE-WAIT → LAST-ACK`, `LAST-ACK → CLOSED` — enumerated by querying the
+  class, whose label spells the path out.
+
+> **Honest limit (stated in the source):** a node *is* a state is not yet a
+> machine-declarable fact — FigDown has no state genre (the R49 §6 candidate),
+> so "this node is a protocol state" rides on the `states` class label, interim.
+> And CLOSED is drawn **twice** (top origin, bottom terminus) because FigDown
+> has no node-identity/alias construct (**OQ-S26**): the two `closed`/`closed2`
+> nodes are declared one state only by the shared class label, not machine-
+> readably. Everything else — all 11 states, all 21 labelled transitions
+> including the one the canonical figure omits in its own Note 2 — the edges
+> carry in full.
+
+---
+
+## The honest limits, in one paragraph
+
+Two figures depend on a convention the language does not yet make first-class:
+**message/step ordering** in the handshake and ARP is carried by numbering edge
+labels `1:`/`2:`/`3:`, which R37 treats as naming, not semantics — the v0.2
+sequence genre (OQ-S18) will fix it, and the sources say so. Relatedly, the RFC
+9293 handshake carries **per-endpoint lifeline state** (LISTEN, SYN-SENT, …)
+that the topology genre has no construct for; the companion state table carries
+it as composition (a ruled interim, again pending the sequence genre, OQ-S18).
+The Ethernet frame uses the **OQ-S24** byte-unit workaround (single-row `table`,
+not `bitfield`) so byte order rides on cell order, and one of its facts — the
+FCS **coverage span** over a contiguous run of columns (DA through Payload) —
+has no annotation construct yet (**OQ-S16**), so it rides on a source comment
+and prose. The TCP state machine meets two more: **state-ness is not first-class**
+— a node *is* a state carries as the `states` class label until the state genre
+lands (the R49 §6 candidate) — and CLOSED is drawn **twice** because FigDown has
+no **node-identity/alias** construct (**OQ-S26**) to declare two nodes the same
+entity; the shared class label asserts it instead. Every state and every labelled
+transition still rides on an edge, so those two are the *only* facts the figure
+cannot carry that the canonical drawing implies. All are documented in
+[EXPRESSING.md](EXPRESSING.md)'s "Known limits".
+That a figure format states its own limits — and that a reading agent recovers
+exactly what the text declares and nothing the geometry merely implies — is the
+claim these figures make.