figdown 0.1.0-rc.1

package/examples/showcase/tcp-state-machine.svg

@@ -0,0 +1,140 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 843 984" width="843" height="984" font-family="system-ui,sans-serif"><defs><marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#555"/></marker><pattern id="hatch" width="6" height="6" patternUnits="userSpaceOnUse" patternTransform="rotate(45)"><line x1="0" y1="0" x2="0" y2="6" stroke="#bbb" stroke-width="2"/></pattern></defs><g transform="translate(18,6)"><line data-edge="68" x1="429.6" y1="76" x2="429.6" y2="170" stroke="#2563eb" stroke-width="1.6"/><path data-edge="69" d="M465.2 58 L780 58 Q790 58 790 68 L790 308 Q790 318 780 318 L692.6 318" fill="none" stroke="#2563eb" stroke-width="1.6"/><line data-edge="70" x1="460.08923076923077" y1="206" x2="619.3107692307692" y2="300" stroke="#2563eb" stroke-width="1.6"/><line data-edge="71" x1="400.8612326629738" y1="209.014657885179" x2="241.49507881681996" y2="303.01465788517896" stroke="#2563eb" stroke-width="1.6"/><line data-edge="72" x1="607" y1="318" x2="266.4" y2="318" stroke="#9333ea" stroke-width="1.6" stroke-dasharray="6 4"/><line data-edge="73" x1="619.3107692307692" y1="336" x2="460.08923076923077" y2="430" stroke="#2563eb" stroke-width="1.6"/><line data-edge="74" x1="239.71692307692308" y1="336" x2="399.08307692307693" y2="430" stroke="#2563eb" stroke-width="1.6"/><path data-edge="77" d="M394 170.694 L308.994 129.372 Q300 125 308.883 120.408 L394.782 76" fill="none" stroke="#9333ea" stroke-width="1.6" stroke-dasharray="6 4"/><path data-edge="78" d="M648.809 300 L640.55 149.985 Q640 140 630.683 136.369 L465.2 71.875" fill="none" stroke="#9333ea" stroke-width="1.6" stroke-dasharray="6 4"/><line data-edge="79" x1="237.9387673370262" y1="296.98534211482104" x2="397.30492118318006" y2="202.985342114821" stroke="#9333ea" stroke-width="1.6" stroke-dasharray="6 4"/><line data-edge="82" x1="209.18615384615384" y1="336" x2="209.01384615384615" y2="560" stroke="#dc2626" stroke-width="1.6"/><line data-edge="83" x1="399.05538461538464" y1="466" x2="239.54461538461538" y2="560" stroke="#dc2626" stroke-width="1.6"/><line data-edge="84" x1="209" y1="596" x2="209" y2="690" stroke="#dc2626" stroke-width="1.6"/><line data-edge="85" x1="228.55076923076922" y1="596" x2="330.64923076923077" y2="690" stroke="#dc2626" stroke-width="1.6"/><line data-edge="86" x1="218.78923076923076" y1="596" x2="340.6107692307692" y2="820" stroke="#9333ea" stroke-width="1.6" stroke-dasharray="6 4"/><line data-edge="87" x1="228.57846153846154" y1="726" x2="330.82153846153847" y2="820" stroke="#dc2626" stroke-width="1.6"/><line data-edge="88" x1="350.2276923076923" y1="726" x2="350.3723076923077" y2="820" stroke="#dc2626" stroke-width="1.6"/><line data-edge="89" x1="396.79999999999995" y1="838" x2="614" y2="838" stroke="#dc2626" stroke-width="1.6"/><line data-edge="92" x1="460.1169230769231" y1="466" x2="619.483076923077" y2="560" stroke="#16a34a" stroke-width="1.6"/><line data-edge="93" x1="649.9723076923077" y1="596" x2="649.8276923076922" y2="690" stroke="#16a34a" stroke-width="1.6"/><line data-edge="94" x1="649.7723076923077" y1="726" x2="649.6276923076923" y2="820" stroke="#16a34a" stroke-width="1.6"/><g data-node="closed" data-x="394" data-y="40" style="cursor:move"><rect x="394" y="40" width="71.2" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="429.6" y="62.55" font-size="13" text-anchor="middle" fill="#1d1d1b">CLOSED</text></g><g data-node="listen" data-x="394" data-y="170" style="cursor:move"><rect x="394" y="170" width="71.2" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="429.6" y="192.55" font-size="13" text-anchor="middle" fill="#1d1d1b">LISTEN</text></g><g data-node="synsent" data-x="607" data-y="300" style="cursor:move"><rect x="607" y="300" width="85.6" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="649.8" y="322.55" font-size="13" text-anchor="middle" fill="#1d1d1b">SYN-SENT</text></g><g data-node="synrcvd" data-x="152" data-y="300" style="cursor:move"><rect x="152" y="300" width="114.4" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="209.2" y="322.55" font-size="13" text-anchor="middle" fill="#1d1d1b">SYN-RECEIVED</text></g><g data-node="estab" data-x="376" data-y="430" style="cursor:move"><rect x="376" y="430" width="107.2" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="429.6" y="452.55" font-size="13" text-anchor="middle" fill="#1d1d1b">ESTABLISHED</text></g><g data-node="fw1" data-x="159" data-y="560" style="cursor:move"><rect x="159" y="560" width="100" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="209" y="582.55" font-size="13" text-anchor="middle" fill="#1d1d1b">FIN-WAIT-1</text></g><g data-node="fw2" data-x="159" data-y="690" style="cursor:move"><rect x="159" y="690" width="100" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="209" y="712.55" font-size="13" text-anchor="middle" fill="#1d1d1b">FIN-WAIT-2</text></g><g data-node="closing" data-x="311" data-y="690" style="cursor:move"><rect x="311" y="690" width="78.4" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="350.2" y="712.55" font-size="13" text-anchor="middle" fill="#1d1d1b">CLOSING</text></g><g data-node="closewait" data-x="600" data-y="560" style="cursor:move"><rect x="600" y="560" width="100" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="650" y="582.55" font-size="13" text-anchor="middle" fill="#1d1d1b">CLOSE-WAIT</text></g><g data-node="lastack" data-x="607" data-y="690" style="cursor:move"><rect x="607" y="690" width="85.6" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="649.8" y="712.55" font-size="13" text-anchor="middle" fill="#1d1d1b">LAST-ACK</text></g><g data-node="timewait" data-x="304" data-y="820" style="cursor:move"><rect x="304" y="820" width="92.8" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="350.4" y="842.55" font-size="13" text-anchor="middle" fill="#1d1d1b">TIME-WAIT</text></g><g data-node="closed2" data-x="614" data-y="820" style="cursor:move"><rect x="614" y="820" width="71.2" height="36" rx="14" fill="#eef2ff" stroke="#8a8880" stroke-width="1.8"/><text x="649.6" y="842.55" font-size="13" text-anchor="middle" fill="#1d1d1b">CLOSED</text></g><text x="435.6" y="137.57999999999998" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">passive OPEN / create TCB</text><text x="435.6" y="137.57999999999998" font-size="11" text-anchor="start" fill="#2563eb">passive OPEN / create TCB</text><path d="M429.6 170 L424 159.92 L435.20000000000005 159.92 z" fill="#2563eb" stroke="none"/><text x="627.6" y="52.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">active OPEN / create TCB, snd SYN</text><text x="627.6" y="52.25" font-size="11" text-anchor="middle" fill="#2563eb">active OPEN / create TCB, snd SYN</text><path d="M692.5999999999999 318 L702.68 312.4 L702.68 323.6 z" fill="#2563eb" stroke="none"/><text x="539.7" y="247.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">SEND / snd SYN</text><text x="539.7" y="247.25" font-size="11" text-anchor="middle" fill="#2563eb">SEND / snd SYN</text><path d="M619.3107692307692 300 L607.783624515843 299.6977836517479 L613.4775557147959 290.05314019013707 z" fill="#2563eb" stroke="none"/><text x="321.17815573989685" y="250.26465788517896" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv SYN / snd SYN,ACK</text><text x="321.17815573989685" y="250.26465788517896" font-size="11" text-anchor="middle" fill="#2563eb">rcv SYN / snd SYN,ACK</text><path d="M241.49507881681996 303.01465788517896 L247.33224434230044 293.0701167379896 L253.02234270997042 302.71702197056237 z" fill="#2563eb" stroke="none"/><text x="436.7" y="312.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv SYN / snd SYN,ACK</text><text x="436.7" y="312.25" font-size="11" text-anchor="middle" fill="#9333ea">rcv SYN / snd SYN,ACK</text><path d="M266.4 318 L276.47999999999996 312.4 L276.47999999999996 323.6 z" fill="#9333ea" stroke="none"/><text x="539.7" y="377.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv SYN,ACK / snd ACK</text><text x="539.7" y="377.25" font-size="11" text-anchor="middle" fill="#2563eb">rcv SYN,ACK / snd ACK</text><path d="M460.08923076923077 430 L465.9224442852041 420.05314019013707 L471.6163754841569 429.6977836517479 z" fill="#2563eb" stroke="none"/><text x="319.4" y="377.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv ACK of SYN / x</text><text x="319.4" y="377.25" font-size="11" text-anchor="middle" fill="#2563eb">rcv ACK of SYN / x</text><path d="M399.08307692307693 430 L387.55581302992647 429.7023640853834 L393.24591139759644 420.05545885281066 z" fill="#2563eb" stroke="none"/><text x="336.01719402985077" y="100.63" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">CLOSE / delete TCB</text><text x="336.01719402985077" y="100.63" font-size="11" text-anchor="middle" fill="#9333ea">CLOSE / delete TCB</text><path d="M394.7820895522388 76 L388.3996077783373 85.60366213513446 L383.25615963242194 75.65454452751315 z" fill="#9333ea" stroke="none"/><text x="552.6" y="100.18726235741445" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">CLOSE / delete TCB</text><text x="552.6" y="100.18726235741445" font-size="11" text-anchor="middle" fill="#9333ea">CLOSE / delete TCB</text><path d="M465.20000000000005 71.8745247148289 L476.6254519472023 70.31713979061396 L472.5583957756856 80.75261074777387 z" fill="#9333ea" stroke="none"/><text x="336.7457827216416" y="232.955342114821" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv RST (note 1) / x</text><text x="336.7457827216416" y="232.955342114821" font-size="11" text-anchor="middle" fill="#9333ea">rcv RST (note 1) / x</text><path d="M397.30492118318006 202.985342114821 L391.46775565769957 212.92988326201035 L385.7776572900296 203.2829780294376 z" fill="#9333ea" stroke="none"/><text x="215.1" y="451.3" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">CLOSE / snd FIN</text><text x="215.1" y="451.3" font-size="11" text-anchor="start" fill="#dc2626">CLOSE / snd FIN</text><path d="M209.01384615384615 560 L203.42160165450994 549.915695291214 L214.62159834090195 549.9243106732804 z" fill="#dc2626" stroke="none"/><text x="319.3" y="507.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">CLOSE / snd FIN</text><text x="319.3" y="507.25" font-size="11" text-anchor="middle" fill="#dc2626">CLOSE / snd FIN</text><path d="M239.54461538461538 560 L245.38572668223014 550.0577759626491 L251.0719964792192 559.7069384027706 z" fill="#dc2626" stroke="none"/><text x="86" y="646.3000000000001" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv ACK of FIN / x</text><text x="86" y="646.3000000000001" font-size="11" text-anchor="start" fill="#dc2626">rcv ACK of FIN / x</text><path d="M209 690 L203.4 679.92 L214.6 679.92 z" fill="#dc2626" stroke="none"/><text x="279.6" y="637.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv FIN / snd ACK</text><text x="279.6" y="637.25" font-size="11" text-anchor="middle" fill="#dc2626">rcv FIN / snd ACK</text><path d="M330.64923076923077 690 L319.4405255167678 687.2923577482596 L327.02659217035057 679.0527222752913 z" fill="#dc2626" stroke="none"/><text x="300.3185846153846" y="738.1800000000001" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv FIN,ACK / snd ACK</text><text x="300.3185846153846" y="738.1800000000001" font-size="11" text-anchor="start" fill="#9333ea">rcv FIN,ACK / snd ACK</text><path d="M340.6107692307692 820 L330.875382512483 813.820303774018 L340.7144579488292 808.469360440559 z" fill="#9333ea" stroke="none"/><text x="279.7" y="767.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv FIN / snd ACK</text><text x="279.7" y="767.25" font-size="11" text-anchor="middle" fill="#dc2626">rcv FIN / snd ACK</text><path d="M330.82153846153847 820 L319.61092639723944 817.3002635047485 L327.19118005561285 809.0552799101793 z" fill="#dc2626" stroke="none"/><text x="356.29999999999995" y="776.3000000000001" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv ACK of FIN / x</text><text x="356.29999999999995" y="776.3000000000001" font-size="11" text-anchor="start" fill="#dc2626">rcv ACK of FIN / x</text><path d="M350.3723076923077 820 L344.75680664555944 809.9286273033927 L355.9567933911451 809.9113965545532 z" fill="#dc2626" stroke="none"/><text x="505.4" y="832.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">Timeout=2MSL / delete TCB</text><text x="505.4" y="832.25" font-size="11" text-anchor="middle" fill="#dc2626">Timeout=2MSL / delete TCB</text><path d="M614 838 L603.92 843.6 L603.92 832.4 z" fill="#dc2626" stroke="none"/><text x="539.8000000000001" y="507.25" font-size="11" text-anchor="middle" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv FIN / snd ACK</text><text x="539.8000000000001" y="507.25" font-size="11" text-anchor="middle" fill="#16a34a">rcv FIN / snd ACK</text><path d="M619.483076923077 560 L607.9558130299265 559.7023640853835 L613.6459113975964 550.0554588528106 z" fill="#16a34a" stroke="none"/><text x="655.9" y="646.3000000000001" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">CLOSE / snd FIN</text><text x="655.9" y="646.3000000000001" font-size="11" text-anchor="start" fill="#16a34a">CLOSE / snd FIN</text><path d="M649.8276923076922 690 L644.2432066088548 679.9113965545532 L655.4431933544405 679.9286273033927 z" fill="#16a34a" stroke="none"/><text x="655.7" y="776.3000000000001" font-size="11" text-anchor="start" fill="#fff" stroke="#fff" stroke-width="3" stroke-linejoin="round">rcv ACK of FIN / x</text><text x="655.7" y="776.3000000000001" font-size="11" text-anchor="start" fill="#16a34a">rcv ACK of FIN / x</text><path d="M649.6276923076923 820 L644.0432066088549 809.9113965545532 L655.2431933544406 809.9286273033927 z" fill="#16a34a" stroke="none"/><rect x="0" y="877" width="16" height="11" fill="#eef2ff" stroke="#555"/><text x="21" y="886.5" font-size="11" fill="#1d1d1b">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)</text><rect x="0" y="897" width="16" height="11" fill="#2563eb" stroke="#555"/><text x="21" y="906.5" font-size="11" fill="#1d1d1b">Connection-setup transition — opening the connection (OPEN, SYN exchange, first ACK)</text><rect x="0" y="917" width="16" height="11" fill="#dc2626" stroke="#555"/><text x="21" y="926.5" font-size="11" fill="#1d1d1b">Active-close path (typically the client) — calls CLOSE first: FIN-WAIT-1 → FIN-WAIT-2 / CLOSING → TIME-WAIT → CLOSED</text><rect x="0" y="937" width="16" height="11" fill="#16a34a" stroke="#555"/><text x="21" y="946.5" font-size="11" fill="#1d1d1b">Passive-close path (typically the server) — receives the peer's FIN first: CLOSE-WAIT → LAST-ACK → CLOSED</text><rect x="0" y="957" width="16" height="11" fill="#9333ea" stroke="#555" stroke-dasharray="6 4"/><text x="21" y="966.5" font-size="11" fill="#1d1d1b">Rare / simultaneous transition — simultaneous open or close, or a reset/abort (RST, close from a half-open state)</text></g><metadata id="figdown-source" data-sha256="459b9e5cc2a557ccb672ce2b25d576fd8aa07c8384f2ad347a0c2534a2373f54"><![CDATA[
+figdown 0.1 flowchart
+title TCP Connection State Machine (RFC 9293, Figure 5)
+
+# ── What this figure is ─────────────────────────────────────────────
+# The complete TCP connection state machine from RFC 9293 §3.3.2,
+# Figure 5: all 11 states and every state transition, each labelled
+# "event / action" exactly as the RFC writes it. `x` is the RFC's own
+# notation for "no action". This is the hardest showcase figure — it
+# answers the maintainer question "can FigDown fully express the TCP
+# state machine with its transitions and conditions?" — and the answer
+# it gives is: yes, every state and every labelled transition rides on
+# an edge, so a reading agent recovers the whole machine from the text.
+#
+# HONEST LIMIT — state-ness is not yet first-class. FigDown has no
+# "state" genre in which a node IS a state as a machine-declarable fact
+# (that genre is the R49 §6 candidate; OQ tracks it). Here each state is
+# a `shape=rounded` node and the fact "this node is a protocol state" is
+# carried by the `states` class label, not by the genre. Interim, ruled.
+#
+# HONEST LIMIT — the CLOSED identity (OQ-S26). The canonical RFC figure
+# draws CLOSED TWICE — top (origin) and bottom (the terminus TIME-WAIT
+# and LAST-ACK return to) — and so do we, because routing every terminal
+# edge back to a single top node produced long lines that struck the
+# setup-abort labels around CLOSED and made the figure unreadable. But
+# FigDown CANNOT declare two nodes to be the SAME entity: there is no
+# node-identity / alias construct (OQ-S26). So `closed` and `closed2`
+# are two nodes that a human reads as one state only because the shared
+# `states` class label SAYS "the two CLOSED nodes are one state."
+# A reading agent sees two ids; the identity is asserted
+# in the label, not machine-declarable. This is the single fact this
+# figure cannot carry that the canonical drawing implies by reusing the
+# name — documented, not hidden.
+#
+# HONEST LIMIT — RFC Note 2. The canonical Figure 5 OMITS the
+# FIN-WAIT-1 → TIME-WAIT transition and says so in its Note 2 (it occurs
+# when a FIN arrives that also ACKs our FIN). We DRAW it (edge fw1→tw),
+# so this figure is strictly MORE complete than the canonical drawing
+# while carrying the same semantics the RFC prose states. Note 1 (rcv
+# RST → LISTEN applies only to a passively-opened SYN-RECEIVED) rides on
+# that edge's label.
+
+# ── Semantic classes — the meaning behind every stroke ──────────────
+# A reading agent queries these to group transitions by role; the
+# colour/dash is only presentation (R37), the meaning is the label.
+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
+
+# ── The 11 states (CLOSED drawn twice; see OQ-S26 note above) ────────
+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
+
+# ── Opening the connection (setup) ──────────────────────────────────
+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
+
+# ── Aborting a half-open connection (rare / reset) ──────────────────
+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
+
+# ── Active close — the endpoint that calls CLOSE first ──────────────
+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
+
+# ── Passive close — the endpoint that receives the peer's FIN ───────
+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
+# ── Presentation only (R25) ─────────────────────────────────────────
+# The strip test holds: delete every line below and the machine is
+# unchanged — all 11 states, all 21 transitions and their event/action
+# labels live in the `node`/`edge`/`class` lines above (closed2 is not
+# an orphan: it is the target of two terminal edges).
+#
+# The grid reproduces the CANONICAL Figure 5 composition, mirrored about
+# one central vertical axis (x≈430, the shared centre of CLOSED, LISTEN
+# and ESTABLISHED) with a uniform 130 px row rhythm:
+#   row0 CLOSED · row1 LISTEN · row2 SYN-RECEIVED | SYN-SENT (mirrored
+#   at ±220) · row3 ESTABLISHED · row4 FIN-WAIT-1 | CLOSE-WAIT (same
+#   ±220 mirror) · row5 FIN-WAIT-2, CLOSING, LAST-ACK · row6 TIME-WAIT,
+#   CLOSED (terminus, under LAST-ACK as the RFC draws it).
+# Column discipline: CLOSED→LISTEN, SYN-RECEIVED→FIN-WAIT-1→FIN-WAIT-2,
+# CLOSING→TIME-WAIT, CLOSE-WAIT→LAST-ACK→CLOSED run dead vertical; the
+# simultaneous-open edge SYN-SENT→SYN-RECEIVED runs dead horizontal
+# between the mirrored pair. All meaning is in the edges; this is
+# layout, not knowledge.
+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
+
+# ── Edge routing — the three long transitions, deliberately calm ────
+# active OPEN (closed→synsent) hugs the right margin with two elbows,
+# outside the row-2 band; the two aborts back to the top CLOSED bow out
+# on the outer left (LISTEN's close) and outer right (SYN-SENT's close)
+# so they cross nothing. Every other edge is straight: the FIN-WAIT-1 →
+# TIME-WAIT diagonal threads the gap between FIN-WAIT-2 and CLOSING,
+# and TIME-WAIT → CLOSED is a plain same-row horizontal.
+route closed -> synsent via=790,38;790,298
+route listen -> closed via=300,105
+route synsent -> closed via=640,120
+
+]]></metadata></svg>

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "figdown",
+  "version": "0.1.0-rc.1",
+  "description": "Figures as text — one source, two readers: a closed, deterministic figure language for Markdown, readable by AI agents and humans alike",
+  "license": "MIT",
+  "author": "FigDown <hello@figdown.org>",
+  "homepage": "https://figdown.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FigDown/figdown.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FigDown/figdown/issues"
+  },
+  "keywords": [
+    "figdown",
+    "diagram",
+    "figure",
+    "markdown",
+    "svg",
+    "diagrams-as-code",
+    "ai-agent",
+    "deterministic"
+  ],
+  "type": "commonjs",
+  "main": "dist/figdown.js",
+  "module": "dist/figdown.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/figdown.mjs",
+      "require": "./dist/figdown.js"
+    }
+  },
+  "bin": {
+    "figdown-svg": "skill/figdown/build-svg.js"
+  },
+  "files": [
+    "dist/figdown.js",
+    "dist/figdown.mjs",
+    "skill/figdown/figdown.html",
+    "skill/figdown/build-svg.js",
+    "SHOWCASE.md",
+    "EXPRESSING.md",
+    "LAYOUT-GUIDE.md",
+    "examples/evpn-fabric.svg",
+    "examples/showcase/*.svg"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/figdown/build-svg.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// FigDown Stage-0 sidecar generator (R14): X.fd -> X.svg
+// Deterministic: same source -> same SVG, bit-level. The artifact embeds
+// its own source and a SHA-256 of it (spec draft section 7).
+// The engine is never forked: parser+renderer are extracted from the editor
+// single file at build time (the "regenerate, don't fork" rule).
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// The engine file is looked up in order: $FIGDOWN_HTML, a co-located
+// copy (the agent-skill bundle layout), then ../editor/figdown.html (the
+// repository layout).
+const ENGINE = [
+  process.env.FIGDOWN_HTML,
+  path.join(__dirname, 'figdown.html'),
+  path.join(__dirname, '..', 'editor', 'figdown.html'),
+].filter(Boolean).find(p => fs.existsSync(p));
+
+function loadEngine() {
+  if (!ENGINE) throw new Error('figdown.html not found (set FIGDOWN_HTML or keep it next to this script)');
+  const h = fs.readFileSync(ENGINE, 'utf8');
+  const start = h.indexOf('const SHAPES');
+  const end = h.indexOf('// 3. UI');
+  if (start < 0 || end < 0) throw new Error('cannot locate engine in ' + ENGINE);
+  const factory = new Function(h.slice(start, end) + '\nreturn {parse, render};');
+  return factory();
+}
+
+function buildOne(engine, fdPath) {
+  const src = fs.readFileSync(fdPath, 'utf8');
+  const { doc, errs } = engine.parse(src);
+  if (errs.length) {
+    console.error(fdPath + ':');
+    for (const e of errs) console.error('  ' + e);
+    return false;
+  }
+  const svg = engine.render(doc, RENDER_OPTS).svg;
+  const hash = crypto.createHash('sha256').update(src, 'utf8').digest('hex');
+  // render options are recorded in the artifact so a third-party rebuild
+  // (same source + same recorded options) stays bit-identical
+  const optAttr = RENDER_OPTS.title === true ? ' data-render-options="with-title"' : '';
+  const meta = '<metadata id="figdown-source" data-sha256="' + hash + '"' + optAttr + '><![CDATA[\n'
+    + src.replace(/]]>/g, ']]]]><![CDATA[>') + '\n]]></metadata>';
+  const artifact = svg.replace(/<\/svg>$/, meta + '</svg>');
+  const out = fdPath.replace(/\.fd$/, '') + '.svg';
+  fs.writeFileSync(out, artifact);
+  console.log('OK  ' + out);
+  return true;
+}
+
+const argv = process.argv.slice(2);
+const RENDER_OPTS = {};
+const args = argv.filter(a => {
+  if (a === '--with-title') { RENDER_OPTS.title = true; return false; }
+  if (a === '--no-title') { return false; }  // the default since 0.1-dev.12 (kept for compat)
+  return true;
+});
+if (!args.length) {
+  console.error('usage: node tools/build-svg.js [--with-title] <file.fd | dir> ...');
+  process.exit(2);
+}
+const engine = loadEngine();
+let fail = false;
+for (const a of args) {
+  const st = fs.statSync(a);
+  const files = st.isDirectory()
+    ? fs.readdirSync(a).filter(f => f.endsWith('.fd')).sort().map(f => path.join(a, f))
+    : [a];
+  for (const f of files) if (!buildOne(engine, f)) fail = true;
+}
+process.exit(fail ? 1 : 0);