flowfig 0.5.0 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 <h1><img src="docs/logo.svg" alt="flowfig" height="80"/></h1>
 
-### Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf and Kiro draw the diagram from your code. flowfig checks it before it goes in your README.
+### Your coding agent draws the diagram from your code. flowfig checks it, and CI fails when the linked code is gone.
 
 <p>
   <a href="https://www.npmjs.com/package/flowfig"><img src="https://img.shields.io/npm/v/flowfig?style=for-the-badge&logo=npm&logoColor=white&label=npm" alt="npm version"/></a>
@@ -16,6 +16,58 @@
 
 </div>
 
+## The problem
+
+A diagram in a repo drifts from the code. Someone renames a function, and the diagram still shows the old name. No
+check fails, so no one sees the drift.
+
+flowfig links each part of a diagram to the code that it draws. `flowfig verify` fails when a linked file or symbol is
+gone. Run `verify` in CI, and a stale diagram fails the pull request.
+
+## Fail CI when the diagram drifts
+
+A box, an edge or a message can name the code that it draws:
+
+```json
+{ "id": "verify", "label": "verifyPassword", "source": "src/auth/login.ts#verifyPassword" }
+```
+
+Rename `verifyPassword` to `checkPassword`. Then `verify` fails with exit code 1:
+
+```console
+$ npx flowfig verify login.svg
+error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not found
+1 error, 0 warnings
+```
+
+`verify` checks that each linked file exists and that the symbol name still occurs in it. A link to a Markdown file can
+name a heading, so a process diagram can follow its SOP document.
+
+The GitHub Action runs `verify` on every figure in a pull request. For each SVG that the PR changes, it comments the old
+image, the new image and the spec changes. It also names each figure whose linked code the PR changes.
+
+```yaml
+# .github/workflows/figures.yml
+name: figures
+on: pull_request
+jobs:
+  figures:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # the Action reads the old figure from the base commit
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: iamalvisng/flowfig@v0.6.0
+        with:
+          figures: 'docs/**/*.svg' # default **/*.svg
+```
+
 ## Use it
 
 Set up your repo:
@@ -41,49 +93,79 @@ draw the refund process with a lane for each team
 The agent writes an SVG and ends its reply with `npx flowfig open <path>`. Run that command to see the animation in your
 browser.
 
+`init` sets up 7 agents: Claude Code, Cursor, GitHub Copilot, Codex and other `AGENTS.md` agents, Gemini CLI, Windsurf
+and Kiro.
+
 ## One command
 
 ```bash
 npx flowfig draw "how does login work"
 ```
 
-`draw` runs Claude Code on the repo. It gives Claude Code the flowfig guide, `npx flowfig` and the tools Read, Glob and Grep.
-The permission mode is `acceptEdits`, so Claude Code can write files. `draw` disallows the tools Edit, MultiEdit and
-NotebookEdit. Claude Code writes the spec `how-does-login-work.json`, then renders `how-does-login-work.svg`. Then `draw`
-checks the figure itself with `check --strict` and `verify`, and removes the spec file. If the agent writes no new figure,
-`draw` exits 1 and shows the tool calls that the permission rules denied. `draw` prints the result, the reply of the agent
-and the cost of the run. `draw` needs Claude Code on the machine and a login. `draw` does not run on Windows yet.
-`--out` sets the path (it must end in `.svg`), `--model` sets the model, `--max-turns` sets the turn cap (default 40) and
-`--json` prints `{ out, reply, cost, session, findings }` for scripts. `--open` opens the figure in the default browser after the check.
+`draw` runs Claude Code on the repo with the flowfig guide. It gives Claude Code the tools Read, Glob and Grep, and
+`npx flowfig`. `draw` disallows the tools Edit, MultiEdit and NotebookEdit. Claude Code writes the figure. Then `draw`
+checks the figure with `check --strict` and `verify`. `draw` prints the result, the reply of the agent and the cost of
+the run.
 
-## The problem
+`draw` needs Claude Code on the machine and a login. `draw` does not run on Windows yet. `--out` sets the path,
+`--model` sets the model, `--max-turns` sets the turn cap (default 40), `--json` prints the result for scripts, and
+`--open` opens the figure.
+
+## How it works
+
+1. **The agent writes JSON, not pictures.** The agent reads the code and writes a spec of the parts, the calls and their
+   order. flowfig does the layout.
+2. **flowfig checks the spec.** `flowfig check` has 22 rules. It finds ids that point nowhere, text wider than its box,
+   edges through boxes, overlapping labels and low contrast. A render runs the same check and writes nothing on an error.
+   The agent reads the faults and fixes the spec.
+3. **The output is one animated SVG with no script.** The SVG plays in a GitHub README, PR or issue. It follows the light
+   or dark mode of the reader. The SVG carries its spec, so `npx flowfig --spec figure.svg` prints it back.
+
+## Forms
+
+The map (the default) shows the parts and the messages between them:
+
+![A request that misses the cache, then hits the cache](docs/cached-request.svg)
 
-- A diagram in a repo drifts from the code. No one sees the drift.
-- An agent that you ask for a diagram invents parts that the code does not have.
-- A static picture cannot show the order of the calls or their payloads.
-
-## What flowfig does
-
-- **One command sets up 7 agents.** `npx flowfig init` writes instructions for Claude Code, Cursor, GitHub Copilot, Codex and
-  others through `AGENTS.md`, Gemini CLI, Windsurf and Kiro.
-- **The agent writes JSON, not pictures.** The agent reads the code and writes a JSON spec of the parts, the calls and their
-  order. flowfig does the layout.
-- **`flowfig check` finds the faults a machine can read.** It finds ids that point nowhere, text wider than its box, edges
-  through boxes, overlapping labels, hidden edges, text too small at the README width, and low contrast. The agent reads the
-  faults and fixes the spec.
-- **The output is one animated SVG with no script.** The SVG plays in a GitHub README, PR or issue. It follows the light or dark
-  mode of the reader.
-- **Every SVG carries its own spec.** `npx flowfig --spec figure.svg` prints the spec. Any agent can read a diagram back, change
-  it, and render it again.
-- **Three forms and a React player.** The forms are the map, the map with a lifeline rail for sequences, and the rail alone. The
-  React player adds tabs, pause and hover. The package has zero runtime dependencies. Only the React player needs React.
+The map and the rail (`rail: true`) adds one row for each message, with its payload:
+
+![An order checkout: the map of the parts, and a rail of the messages under it](docs/checkout.svg)
+
+The rail only (`rail: "only"`) shows the order of the messages without the map:
+
+![The checkout messages as a rail, without the map](docs/checkout-rail-only.svg)
+
+Swimlanes (`lanes: true`) give each role a lane and put the steps left to right in time order:
+
+![The refund process across Customer, Support and Finance](docs/refund-process.svg)
+
+A long swimlane process wraps into blocks at the page width. An edge between two blocks becomes two labeled stubs:
+
+![A returns process in blocks of lanes, with labeled stubs between the blocks](docs/returns-process.svg)
+
+The timeline (`timeline: true`) draws a roadmap with one track per team, dated bars, milestones and a today line:
+
+![A Q4 roadmap with three tracks, milestones and a today line](docs/roadmap.svg)
+
+A state lifecycle marks the first state with `mark: "start"` and each final state with `mark: "end"`:
+
+![An order status lifecycle with a start dot and two end rings](docs/order-status.svg)
+
+## Open and share
+
+`npx flowfig open figure.svg` shows the figure in your default browser.
+
+`npx flowfig gif figure.svg` writes an animated GIF for Slack, Notion, X and slides, where SVG animation does not play.
+
+The options are in [Open and share a figure](#open-and-share-a-figure).
 
 ## flowfig, Mermaid and a hand-drawn image
 
 |                                | flowfig                           | Mermaid                              | Hand-drawn image |
 | ------------------------------ | --------------------------------- | ------------------------------------ | ---------------- |
 | Made by an agent from the code | Yes, with the `init` instructions | Yes, as Mermaid text                 | No               |
-| Checked for faults             | Yes, 11 rules in `flowfig check`  | Syntax errors only                   | No               |
+| Linked to the code             | Yes, `verify` fails in CI         | No                                   | No               |
+| Checked for faults             | Yes, 22 rules in `flowfig check`  | Syntax errors only                   | No               |
 | Animated                       | Yes, one packet per message       | No                                   | No               |
 | Shows payloads and order       | Yes, on the map and the rail      | Order and text in a sequence diagram | No               |
 | Plays in a GitHub README       | Yes, as an SVG                    | Yes, GitHub renders it               | Yes, as an image |
@@ -94,12 +176,11 @@ and the cost of the run. `draw` needs Claude Code on the machine and a login. `d
 
 - [Install](#install)
 - [Your first figure](#your-first-figure)
-- [Three forms](#three-forms)
+- [Read and change a figure](#read-and-change-a-figure)
 - [The spec](#the-spec)
 - [Check a figure](#check-a-figure)
 - [Open and share a figure](#open-and-share-a-figure)
 - [Verify in CI](#verify-in-ci)
-- [For teams](#for-teams)
 - [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
@@ -163,28 +244,7 @@ The command writes `first.svg`:
 The SVG has no script and fetches no font. GitHub shows the SVG in a README, a PR or an issue. The SVG follows the light or dark
 color scheme of the reader.
 
-## Three forms
-
-| Form          | Spec           | Use it when                                                             |
-| ------------- | -------------- | ----------------------------------------------------------------------- |
-| The map       | (default)      | The reader must see where each part runs and which parts talk.          |
-| Map and rail  | `rail: true`   | The reader must see the parts, and also the order and payload of calls. |
-| The rail only | `rail: "only"` | The order of the messages is the point, and the map adds nothing to it. |
-
-The map:
-
-![A request that misses the cache, then hits the cache](docs/cached-request.svg)
-
-The map with the rail:
-
-![An order checkout: the map of the parts, and a rail of the messages under it](docs/checkout.svg)
-
-The rail draws one row for each message, with its payload.
-Hops in one beat share a parallel band. An `async` hop has a dashed arrow and an `async` tag.
-
-The rail only, from the same checkout spec:
-
-![The checkout messages as a rail, without the map](docs/checkout-rail-only.svg)
+## Read and change a figure
 
 Each SVG from the CLI carries its own spec. These commands made the rail-only figure from `docs/checkout.svg`:
 
@@ -203,15 +263,19 @@ full reference, run `npx flowfig docs`.
 
 ### Boxes
 
-| Field    | Meaning                                                                   | Default     |
-| -------- | ------------------------------------------------------------------------- | ----------- |
-| `id`     | The name that edges and steps use. It must be unique.                     | required    |
-| `label`  | The title in the box.                                                     | required    |
-| `sub`    | A smaller line under the label.                                           | none        |
-| `shape`  | `"box"`, `"decision"` (a diamond) or `"store"` (a data cylinder).         | `"box"`     |
-| `source` | The code this draws: `path` or `path#symbol`. `flowfig verify` checks it. | none        |
-| `lines`  | The least number of text lines that a content card keeps.                 | none        |
-| `width`  | The width in px. This value replaces the width that layout picks.         | from layout |
+| Field    | Meaning                                                                                                   | Default                             |
+| -------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `id`     | The name that edges and steps use. It must be unique.                                                     | required                            |
+| `label`  | The title in the box.                                                                                     | required                            |
+| `sub`    | A smaller line under the label.                                                                           | none                                |
+| `shape`  | `"box"`, `"decision"` (a diamond) or `"store"` (a data cylinder).                                         | `"box"`                             |
+| `source` | The code this draws: `path` or `path#symbol`. `flowfig verify` checks it.                                 | none                                |
+| `lines`  | The least number of text lines that a content card keeps.                                                 | none                                |
+| `width`  | The width in px. This value replaces the width that layout picks.                                         | from layout                         |
+| `at`     | In a `lanes` figure: the time column of the box, from 0.                                                  | the order of first use in the steps |
+| `from`   | In a `timeline` figure: the start date of the item, as YYYY-MM-DD. A box with only `from` is a milestone. | none                                |
+| `to`     | In a `timeline` figure: the last day of the item, as YYYY-MM-DD.                                          | none                                |
+| `mark`   | `"start"` draws a dot before the box. `"end"` draws a ring after the box. Use it on a state lifecycle.    | none                                |
 
 ### Groups
 
@@ -262,20 +326,24 @@ A beat is an edge id, an array of edge ids that run at the same time, or an obje
 | `ms`    | The length of the beat in ms.                                                              | `speed` (900)  |
 
 In a hop, `back: true` runs the packet from `to` to `from`. `data` is a small card on the packet. `async: true` marks a message
-that does not wait for an answer.
+that does not wait for an answer. On the rail, an `async` hop has a dashed arrow and an `async` tag. The hops of one beat
+share a parallel band on the rail.
 
 Content is an array of rows, or a React node in the player. A row is `{ text, tag, tone, meta, mark, mono }`. Only `text` is
 required. The tones are `blue` (the default), `purple`, `green`, `orange` and `gray`.
 
 ### Figure options
 
-| Field      | Meaning                                                                   | Default  |
-| ---------- | ------------------------------------------------------------------------- | -------- |
-| `rail`     | `true` draws the rail under the map. `"only"` draws the rail alone.       | `false`  |
-| `speed`    | The time in ms for a packet to cross one edge.                            | 900      |
-| `theme`    | `{ accent, fg, muted, bg, surface, border, font }`. Each key is optional. | built-in |
-| `autoplay` | Start to play when the figure mounts. Only the React player reads it.     | `true`   |
-| `check`    | Run the check rules in the browser. Only the React player reads it.       | `false`  |
+| Field      | Meaning                                                                              | Default  |
+| ---------- | ------------------------------------------------------------------------------------ | -------- |
+| `rail`     | `true` draws the rail under the map. `"only"` draws the rail alone.                  | `false`  |
+| `lanes`    | `true` draws swimlanes: a `column` group of labeled groups, one lane per role.       | off      |
+| `timeline` | `true` draws a timeline: one labeled group per track, with the boxes at their dates. | off      |
+| `today`    | In a `timeline` figure: the date of the today line, as YYYY-MM-DD.                   | none     |
+| `speed`    | The time in ms for a packet to cross one edge.                                       | 900      |
+| `theme`    | `{ accent, fg, muted, bg, surface, border, font }`. Each key is optional.            | built-in |
+| `autoplay` | Start to play when the figure mounts. Only the React player reads it.                | `true`   |
+| `check`    | Run the check rules in the browser. Only the React player reads it.                  | `false`  |
 
 ## Check a figure
 
@@ -290,20 +358,32 @@ figure: 5 boxes, 3 groups, 4 edges, 2 steps, 6 messages
 
 The last line gives the counts of the parts of the figure. Compare the counts with the parts that you planned.
 
-| Rule                | Severity | What it finds                                                                |
-| ------------------- | -------- | ---------------------------------------------------------------------------- |
-| `unknown-id`        | error    | An edge, step or beat names a box or edge that does not exist.               |
-| `duplicate-id`      | error    | Two boxes, groups or edges have the same id.                                 |
-| `hidden-edge`       | error    | A `quiet` edge that no beat uses, so the figure never shows it.              |
-| `text-overflow`     | error    | Text that needs more width than its box has.                                 |
-| `edge-crosses-box`  | error    | An edge that goes through a box that is not one of its ends.                 |
-| `label-overlap`     | error    | Two edge labels overlap, or an edge label covers a box.                      |
-| `low-contrast`      | error    | A text and background pair below 4.5:1, in the light, dark or custom theme.  |
-| `empty-step`        | warning  | A step with no beats.                                                        |
-| `small-text`        | warning  | At the page width, the smallest text is below the minimum size.              |
-| `lane-end-block`    | warning  | In wrapped lanes, an edge ends at a lane that no block on its side shows.    |
-| `font-estimated`    | warning  | `theme.font` is set. The SVG check estimates text width for the system font. |
-| `color-not-checked` | warning  | A color that the check cannot read, so its contrast is not checked.          |
+`flowfig check` has 22 rules: 11 errors and 11 warnings.
+
+| Rule                        | Severity | What it finds                                                                                       |
+| --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `unknown-id`                | error    | An edge, step or beat names a box, group or edge that does not exist.                               |
+| `duplicate-id`              | error    | Two boxes, two groups or two edges have the same id.                                                |
+| `hidden-edge`               | error    | A `quiet` edge that no beat uses, so the figure never shows it.                                     |
+| `text-overflow`             | error    | Text that needs more width than its box has.                                                        |
+| `edge-crosses-box`          | error    | An edge that goes through a box that is not one of its ends.                                        |
+| `label-overlap`             | error    | Two edge labels overlap, or a label covers a box or an edge, or a stub label crosses a lane border. |
+| `low-contrast`              | error    | A text and background pair below 4.5:1, in the light, dark or custom theme, or on a tone tint.      |
+| `lanes-need-column`         | error    | The layout of a `lanes` or `timeline` figure is not a column group of labeled groups.               |
+| `bad-at`                    | error    | An `at` value that is not an integer of 0 or more.                                                  |
+| `timeline-need-from`        | error    | A box in a timeline has no `from` date.                                                             |
+| `bad-date`                  | error    | A `from`, `to` or `today` value is not a real YYYY-MM-DD date, or a `to` is before its `from`.      |
+| `empty-step`                | warning  | A step with no beats.                                                                               |
+| `small-text`                | warning  | At the page width, the smallest text is below the minimum size.                                     |
+| `bad-source`                | warning  | A `source` that is not `path` or `path#symbol`.                                                     |
+| `mark-count`                | warning  | A lifecycle has more than one `start` mark, or a `start` mark and no `end` mark.                    |
+| `lane-column-taken`         | warning  | Two boxes in one lane share a time column.                                                          |
+| `lane-end-block`            | warning  | In wrapped lanes, an edge ends at a lane that no block on its side shows.                           |
+| `stub-crosses-edge`         | warning  | In wrapped lanes, a stub line crosses another edge.                                                 |
+| `timeline-dependency-order` | warning  | In a timeline, an item does not start after the item that it depends on ends.                       |
+| `timeline-and-lanes`        | warning  | The figure sets `timeline` and `lanes`. The renderers draw the timeline and ignore `lanes`.         |
+| `font-estimated`            | warning  | `theme.font` is set. The SVG check estimates text width for the system font.                        |
+| `color-not-checked`         | warning  | A color that the check cannot read, so its contrast is not checked.                                 |
 
 | Option            | Effect                                                                                                     |
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -351,39 +431,30 @@ fails when the file or the symbol is gone. The action runs `verify` on every fig
 the new image for each SVG the PR changes, with the spec changes as a list, and it names each figure whose linked code the PR
 changes.
 
-A process figure for a team links its boxes to the SOP document, not to code: `"source": "docs/sop/refunds.md#step-3-approve-the-refund"`. The symbol is the heading as a GitHub anchor. If the heading is gone, `verify` fails.
+A process figure for a team links its boxes to the SOP document, not to code: `"source": "docs/sop/refunds.md#step-3-approve-or-reject"`. The symbol is the heading as a GitHub anchor. If the heading is gone, `verify` fails.
 
 ```yaml
-permissions:
-  contents: read
-  pull-requests: write
-steps:
-  - uses: actions/checkout@v4
-    with:
-      fetch-depth: 0
-  - uses: actions/setup-node@v4
-    with:
-      node-version: 22
-  - uses: iamalvisng/flowfig@v0.2.0
-    with:
-      figures: 'docs/**/*.svg' # default **/*.svg
+# .github/workflows/figures.yml
+name: figures
+on: pull_request
+jobs:
+  figures:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # the Action reads the old figure from the base commit
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: iamalvisng/flowfig@v0.6.0
+        with:
+          figures: 'docs/**/*.svg' # default **/*.svg
 ```
 
-A state lifecycle marks the first state with `mark: "start"` and each final state with `mark: "end"`.
-
-![An order status lifecycle with a start dot and two end rings](docs/order-status.svg)
-
-## For teams
-
-A process is a diagram too. `lanes: true` draws one lane per role and the steps left to right in time order. Each step
-links to a heading in the SOP, so `verify` fails when the SOP changes under the diagram.
-
-![The refund process across Customer, Support and Finance](docs/refund-process.svg)
-
-A plan is a figure too. `timeline: true` draws one track per team, with each item as a bar from its `from` date to its `to` date. A milestone has only `from`, and `today` draws the line for now.
-
-![A Q4 roadmap with three tracks, milestones and a today line](docs/roadmap.svg)
-
 ## MCP server
 
 `npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.

package/dist/browser.js

@@ -1,5 +1,5 @@
 // The capture browser of `flowfig gif`: find it, start it in headless mode, and talk CDP to it over a pipe. Node only.
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { win32 } from 'node:path';
 const MAC = ['Google Chrome', 'Microsoft Edge', 'Chromium', 'Brave Browser'].map((n) => `/Applications/${n}.app/Contents/MacOS/${n}`);
 const LINUX = [
@@ -75,8 +75,12 @@ export function launch(path, profile, timeoutMs = 30_000) {
     // The browser starts helper processes in its process group. A helper can outlive the browser and keep a pipe open.
     const killGroup = () => {
         try {
-            if (process.platform === 'win32')
+            // Windows has no process group: taskkill /T stops the helpers of the browser too.
+            if (process.platform === 'win32') {
+                if (child.pid)
+                    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
                 child.kill('SIGKILL');
+            }
             else if (child.pid)
                 process.kill(-child.pid, 'SIGKILL');
         }

package/dist/check.js

@@ -127,10 +127,11 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 out.push(err('text-overflow', [b.id], `box "${b.id}": "${t.text}" needs ${Math.ceil(need)} px, has ${Math.floor(t.room)} px`));
         }
     for (const e of scene.edges) {
-        if (e.behind)
+        if (e.behind && !e.elbow)
             continue;
-        const pts = e.pts
-            ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
+        const line = e.elbow ?? e.pts;
+        const pts = line
+            ? line.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(line[k], q, i / 16)))
             : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
         for (const b of scene.boxes)
             if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, 2)))
@@ -167,13 +168,15 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 out.push(warn('stub-crosses-edge', [f.id, e.id], `the stub of edge "${f.id}" crosses edge "${e.id}"`));
             }
         }
-    // A stub pill sits inside the band of its box: a pill across a band border reads as part of two lanes.
-    for (const f of pills)
+    // A stub pill or an edge label sits inside one band: a pill across a band border reads as part of two lanes.
+    for (const f of scene.edges.filter((e) => e.label))
         for (const l of scene.lanes ?? []) {
             const [p, r] = [f.label, l.rect];
             const inside = p.x >= r.x && p.x + p.w <= r.x + r.w && p.y >= r.y && p.y + p.h <= r.y + r.h;
             if (!inside && overlap(p, r, 0))
-                out.push(err('label-overlap', [f.id], `the pill of edge "${f.id}" crosses the border of lane "${l.id}"`));
+                out.push(err('label-overlap', [f.id], f.pts
+                    ? `the pill of edge "${f.id}" crosses the border of lane "${l.id}"`
+                    : `the label of edge "${f.id}" crosses the border of lane "${l.id}"`));
         }
     const labeled = scene.edges.filter((e) => e.label);
     labeled.forEach((e, i) => {

package/dist/cli.js

@@ -229,7 +229,7 @@ if (args[0] === 'gif') {
         await (await launching?.catch(() => undefined))?.close();
         try {
             // The retries cover Windows, where the browser can hold a file lock for a short time after the exit.
-            rmSync(temp, { recursive: true, force: true, maxRetries: 3 });
+            rmSync(temp, { recursive: true, force: true, maxRetries: 10 });
         }
         catch (e) {
             console.error(`warning: could not remove ${temp}: ${e.message}`);

package/dist/geometry.d.ts

@@ -18,12 +18,18 @@ export type Stub = {
     short?: true;
     tight: [boolean, boolean];
 };
+/** `elbow` holds the corners of an elbow path, so `check` can test its straight runs. */
 export type Routed = {
     id: string;
     d: string;
     mid: Pt;
     curve: [Pt, Pt, Pt, Pt];
     stub?: Stub;
+    elbow?: Pt[];
+};
+/** A rect that a route keeps clear of. `box` marks a box: an elbow's horizontal runs keep clear of a box, not of a label. */
+export type Avoid = Rect & {
+    box?: boolean;
 };
 type Around = 'above' | 'below';
 export declare function route(edges: {
@@ -36,8 +42,12 @@ export declare function route(edges: {
     stub?: number[];
     bands?: [Rect | undefined, Rect | undefined];
     labelW?: number;
-}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Rect[], // what an elbow's vertical run and a stub pill must not cross (the timeline's outside labels; the boxes and gutters of lanes)
-area?: Rect): Routed[];
+}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Avoid[], // what an elbow's vertical run and a stub pill must not cross (the timeline's outside labels; the boxes and gutters of lanes)
+area?: Rect, // where a stub pill may sit: the lanes right of the gutter
+lanes?: {
+    bands: Rect[];
+    boxes: Rect[];
+}): Routed[];
 /** True if the segment a-b crosses the segment c-d. The ends of a-b are trimmed by 1.5 px, so a touch at a box side does not count. */
 export declare function crosses(a: Pt, b: Pt, c: Pt, d: Pt): boolean;
 export {};

package/dist/geometry.js

@@ -1,4 +1,6 @@
 import { STUB } from './model.js';
+/** The least gap between a label pill and a lane border. */
+const LABEL_CLEAR = 4;
 const cx = (r) => r.x + r.w / 2;
 const cy = (r) => r.y + r.h / 2;
 /** A point on the cubic Bézier at `t`, as `check` samples an edge. */
@@ -18,7 +20,8 @@ const bezier = ([p0, p1, p2, p3], t) => {
 // `labelW` is the width of an edge's label pill: a stub pill keeps clear of it.
 // `stub` (wrapped lanes: the source pill width, the target pill width, and the width of a shorter source pill) draws a short stub from the source to a pill, and from a second pill into the target.
 export function route(edges, rects, tips = new Set(), avoid = [], // what an elbow's vertical run and a stub pill must not cross (the timeline's outside labels; the boxes and gutters of lanes)
-area) {
+area, // where a stub pill may sit: the lanes right of the gutter
+lanes) {
     const picks = [];
     for (const e of edges) {
         const a = rects[e.from], b = rects[e.to];
@@ -143,6 +146,22 @@ area) {
                     }
                 return out.sort((m, q) => m[3] - q[3]).map(([r, a, b]) => [r, a, b]);
             };
+            // A diamond with no room beside its point: the stub leaves the side point straight down or up, to a pill that spans its x.
+            const along = (w, box, from, dir, band) => {
+                if (!tips.has(dir > 0 ? p.from : p.to))
+                    return [];
+                const out = [];
+                for (const y of rows(box, from.y + 12, band))
+                    for (let x = from.x - w + 8; x <= from.x - 8; x += 8) {
+                        const down = y >= from.y + 12;
+                        if (!down && y + 18 > from.y - 12)
+                            continue;
+                        const r = { x, y, w, h: 18 };
+                        const [a, b] = [from, { x: from.x, y: down ? y : y + 18 }];
+                        out.push([r, ...(dir > 0 ? [a, b] : [b, a]), Math.abs(y + 9 - from.y) + Math.abs(x + w / 2 - from.x)]);
+                    }
+                return out.sort((m, q) => m[3] - q[3]).map(([r, a, b]) => [r, a, b]);
+            };
             const outs = (w) => [
                 ...beside(w, p.a, s, 1, sb),
                 [
@@ -155,6 +174,7 @@ area) {
                     { x: cx(p.a), y: p.a.y },
                     { x: cx(p.a), y: p.a.y - STUB },
                 ],
+                ...along(w, p.a, s, 1, sb),
             ];
             const ins = [
                 ...beside(iw, p.b, e, -1, tb),
@@ -168,6 +188,7 @@ area) {
                     { x: cx(p.b), y: p.b.y + p.b.h + STUB },
                     { x: cx(p.b), y: p.b.y + p.b.h },
                 ],
+                ...along(iw, p.b, e, -1, tb),
             ];
             const seg = (a, b) => Array.from({ length: 9 }, (_, i) => ({ x: a.x + ((b.x - a.x) * i) / 8, y: a.y + ((b.y - a.y) * i) / 8 }));
             // A stub must not run through a box other than its own, nor through a pill or a label, nor cross an edge path.
@@ -206,27 +227,79 @@ area) {
             };
         }
         if (p.elbow) {
-            // The vertical run sits at the midpoint x. Under 16 px of gap, it detours: out 8 px past the start, back to 8 px
-            // before the end, then forward into the target. A gap of 0 px or less takes the same detour.
-            // Over 16 px, it tries the midpoint, then 8 px before the end, then 8 px after the start, and takes the first that clears `avoid`.
-            const y0 = Math.min(s.y, e.y), y1 = Math.max(s.y, e.y);
-            const clear = (x) => !avoid.some((r) => x > r.x - 2 && x < r.x + r.w + 2 && y1 > r.y && y0 < r.y + r.h);
-            const mx = e.x - s.x >= 16 ? ([(s.x + e.x) / 2, e.x - 8, s.x + 8].find(clear) ?? (s.x + e.x) / 2) : s.x + 8;
-            const c1 = { x: mx, y: s.y }, c2 = { x: mx, y: e.y };
+            // Under 16 px of gap, the elbow detours: out 8 px past the start, back to 8 px before the end, then forward into the target.
+            // A gap of 0 px or less takes the same detour.
             if (e.x - s.x < 16 && s.y === e.y) {
                 // One row: a straight line, since a detour would only double back.
-                return { id: p.id, d: `M ${s.x} ${s.y} H ${e.x}`, mid: { x: (s.x + e.x) / 2, y: s.y }, curve: [s, s, e, e] };
+                return { id: p.id, d: `M ${s.x} ${s.y} H ${e.x}`, mid: { x: (s.x + e.x) / 2, y: s.y }, curve: [s, s, e, e], elbow: [s, e] };
             }
             if (e.x - s.x < 16) {
-                const ex = e.x - 8, my = (s.y + e.y) / 2;
+                const mx = s.x + 8, ex = e.x - 8, my = (s.y + e.y) / 2;
                 return {
                     id: p.id,
                     d: `M ${s.x} ${s.y} H ${mx} V ${my} H ${ex} V ${e.y} H ${e.x}`,
                     mid: { x: (mx + ex) / 2, y: my },
                     curve: [s, { x: mx, y: my }, { x: ex, y: my }, e],
+                    elbow: [s, { x: mx, y: s.y }, { x: mx, y: my }, { x: ex, y: my }, { x: ex, y: e.y }, e],
                 };
             }
-            return { id: p.id, d: `M ${s.x} ${s.y} H ${mx} V ${e.y} H ${e.x}`, mid: { x: mx, y: (s.y + e.y) / 2 }, curve: [s, c1, c2, e] };
+            // Over 16 px, the vertical run tries the midpoint, 8 px before the end, 8 px after the start, then any x in the gap.
+            // A vertical run keeps clear of every label and box; a horizontal run keeps clear of every box but the two ends.
+            const own = (r) => [p.a, p.b].some((q) => q.x === r.x && q.y === r.y && q.w === r.w && q.h === r.h);
+            const all = avoid.filter((r) => !own(r));
+            const boxes = all.filter((r) => r.box);
+            // `m` is the margin: 2 px in the gap, 8 px on a detour, so a detour does not run along a box side.
+            const vClear = (x, ya, yb, m = 2) => !all.some((r) => x > r.x - m && x < r.x + r.w + m && Math.max(ya, yb) > r.y && Math.min(ya, yb) < r.y + r.h);
+            const hClear = (y, xa, xb, list = boxes, m = 2) => !list.some((r) => y > r.y - m && y < r.y + r.h + m && Math.max(xa, xb) > r.x && Math.min(xa, xb) < r.x + r.w);
+            const mid = (s.x + e.x) / 2;
+            const gap = Array.from({ length: Math.floor((e.x - s.x - 16) / 4) + 1 }, (_, i) => s.x + 8 + i * 4).sort((u, w) => Math.abs(u - mid) - Math.abs(w - mid));
+            const mx = [mid, e.x - 8, s.x + 8, ...gap].find((x) => vClear(x, s.y, e.y) && hClear(s.y, s.x, x) && hClear(e.y, x, e.x));
+            if (mx == null && boxes.length) {
+                // No x in the gap is clear: the elbow goes around. It runs right past the boxes in its way, along a clear row, back to
+                // a clear x at or before 8 px before the target, then down or up and forward into the target. The shortest clear
+                // detour wins; ties take the row nearest the middle.
+                const right = Math.max(...boxes.map((r) => r.x + r.w)) + 12;
+                const left = Math.min(...boxes.map((r) => r.x));
+                const [top, bottom] = [Math.min(...boxes.map((r) => r.y)) - 12, Math.max(...boxes.map((r) => r.y + r.h)) + 12];
+                let best;
+                // ponytail: a grid search in 4 px steps, about 10^5 tries for a figure the size of the roadmap.
+                for (let x = s.x + 8; x <= right; x += 4) {
+                    if (!hClear(s.y, s.x, x))
+                        continue;
+                    for (let ex = e.x - 8; ex >= left; ex -= 4) {
+                        if (!hClear(e.y, ex, e.x))
+                            continue;
+                        for (let y = top; y <= bottom; y += 4) {
+                            const len = x - s.x + Math.abs(y - s.y) + Math.abs(x - ex) + Math.abs(e.y - y) + e.x - ex;
+                            const off = Math.abs(y - (s.y + e.y) / 2);
+                            if (best && (len > best.len || (len === best.len && off >= best.off)))
+                                continue;
+                            if (vClear(x, s.y, y, 8) && hClear(y, x, ex, all, 8) && vClear(ex, y, e.y))
+                                best = { len, off, x, y, ex };
+                        }
+                    }
+                }
+                if (best) {
+                    const { x, y, ex } = best;
+                    return {
+                        id: p.id,
+                        d: `M ${s.x} ${s.y} H ${x} V ${y} H ${ex} V ${e.y} H ${e.x}`,
+                        mid: { x: (x + ex) / 2, y },
+                        curve: [s, { x, y }, { x: ex, y }, e],
+                        elbow: [s, { x, y: s.y }, { x, y }, { x: ex, y }, { x: ex, y: e.y }, e],
+                    };
+                }
+            }
+            // If no path is clear, the midpoint stays and `check` reports the crossing.
+            const x = mx ?? mid;
+            const c1 = { x, y: s.y }, c2 = { x, y: e.y };
+            return {
+                id: p.id,
+                d: `M ${s.x} ${s.y} H ${x} V ${e.y} H ${e.x}`,
+                mid: { x, y: (s.y + e.y) / 2 },
+                curve: [s, c1, c2, e],
+                elbow: [s, c1, c2, e],
+            };
         }
         if (p.around) {
             // ponytail: arcs 50px past the two ends' boxes; a taller box in between can still be crossed.
@@ -246,6 +319,8 @@ area) {
             continue;
         const r = one(p);
         done.set(p, r);
+        if (p.labelW && lanes)
+            r.mid = labelInBand(r, p.labelW, lanes, pills);
         if (p.labelW)
             pills.push({ x: r.mid.x - p.labelW / 2, y: r.mid.y - 9, w: p.labelW, h: 18 });
         track(Array.from({ length: 33 }, (_, i) => bezier(r.curve, i / 32)));
@@ -255,6 +330,32 @@ area) {
             done.set(p, one(p));
     return picks.map((p) => done.get(p));
 }
+/** The point of the path nearest its middle where a label pill of width `w` sits inside one band, LABEL_CLEAR from the border, clear of the boxes
+ * and the earlier pills. If a short run leaves no such point, the pill keeps the x of a path point and moves up or down into the nearest
+ * band, still on the path. If that fails too, the middle. Both renderers route through this, so they place the label alike. */
+function labelInBand(r, w, { bands, boxes }, pills) {
+    const hit = (a, b, m) => a.x < b.x + b.w + m && b.x < a.x + a.w + m && a.y < b.y + b.h + m && b.y < a.y + a.h + m;
+    const ts = Array.from({ length: 65 }, (_, i) => i / 64).sort((a, b) => Math.abs(a - 0.5) - Math.abs(b - 0.5));
+    const path = ts.map((t) => bezier(r.curve, t));
+    const clear = (pill) => !boxes.some((b) => hit(pill, b, 1)) && !pills.some((b) => hit(pill, b, 1));
+    const room = (x, b) => x - w / 2 >= b.x + LABEL_CLEAR && x + w / 2 <= b.x + b.w - LABEL_CLEAR;
+    for (const q of path) {
+        const pill = { x: q.x - w / 2, y: q.y - 9, w, h: 18 };
+        const fits = bands.some((b) => room(q.x, b) && pill.y >= b.y + LABEL_CLEAR && pill.y + 18 <= b.y + b.h - LABEL_CLEAR);
+        if (fits && clear(pill))
+            return q;
+    }
+    for (const q of path)
+        for (const b of bands) {
+            if (!room(q.x, b) || b.h < 18 + LABEL_CLEAR * 2)
+                continue;
+            const y = Math.min(Math.max(q.y, b.y + LABEL_CLEAR + 9), b.y + b.h - LABEL_CLEAR - 9);
+            const pill = { x: q.x - w / 2, y: y - 9, w, h: 18 };
+            if (clear(pill) && path.some((o) => o.x >= pill.x && o.x <= pill.x + w && o.y >= pill.y && o.y <= pill.y + 18))
+                return { x: q.x, y };
+        }
+    return r.mid;
+}
 /** True if the segment a-b crosses the segment c-d. The ends of a-b are trimmed by 1.5 px, so a touch at a box side does not count. */
 export function crosses(a, b, c, d) {
     const len = Math.hypot(b.x - a.x, b.y - a.y);

package/dist/guide.d.ts

@@ -1,5 +1,5 @@
 /** The full guide, as Markdown. `flowfig docs` prints it. */
-export declare const GUIDE = "# flowfig guide\n\nflowfig draws animated flow figures. A figure has boxes, the edges between the boxes, and steps. In each step, a packet moves along\nthe edges. The output is one animated SVG with no script. The SVG plays in a GitHub README, in PR and issue comments, and in blog\nposts. A figure is about 5 to 50 kB.\n\nYou write a JSON spec. You never write SVG by hand. The command `npx flowfig` checks the spec and renders it.\n\n## What flowfig draws\n\nA spec has three forms.\n\n- The map (the default). The map shows the boxes and the edges. A packet moves along an edge in each beat.\n- The map with a rail (`\"rail\": true`). The rail is a lifeline diagram under the map. It has one row for each message.\n- The rail alone (`\"rail\": \"only\"`). Use it when the reader needs only the order of the messages, for example when the map is already in the same document.\n\nUse the rail for a sequence of messages: a request lifecycle, an API call chain, or a Mermaid `sequenceDiagram`. Put each message on\nan edge. Put each phase in a step. Put messages that run at the same time in one beat. Mark a message that does not wait for an\nanswer with `\"async\": true`: every send to a queue or a topic, every emitted event, and every call the caller does not await.\n\n## Scope: what flowfig draws and what it does not\n\nflowfig draws how something works: parts, the messages between them, and the order of the messages.\n\n| The user asks for                          | Draw                                                                                       |\n| ------------------------------------------ | ------------------------------------------------------------------------------------------ |\n| An architecture, a data flow, a pipeline   | The map. Group parts by service, network or trust boundary. `store` for data at rest.       |\n| A request lifecycle, a call chain          | The map with `\"rail\": true`. One message per hop, with its real payload in `data`.          |\n| A sequence diagram only                    | `\"rail\": \"only\"`.                                                                           |\n| A state lifecycle, a state machine         | One box per state, one edge per transition, labeled with its event. One step per path. Mark the first state with `mark: \"start\"` and each final state with `mark: \"end\"`. |\n| A flowchart with branches                  | `shape: \"decision\"` for each branch. One step per path.                                     |\n| A roadmap or a timeline | `timeline: true`. One labeled group per track, in a `column` group. Items with `from` and `to` (dates), a milestone with `from` only, an edge for a dependency, `today` for the line. A dependent item starts after its source ends. |\n| A process across roles (a ticket, an order, a refund) | `lanes: true`. One labeled group per role, in a `column` group. Put each step in the lane of the role that does it. Link each step with `source` to the SOP heading. If the steps do not fit the width, flowfig wraps the time columns into blocks and links the blocks with labeled stubs, so keep the whole process in one figure. Give the outcomes of one decision the same `at`. |\n\nflowfig draws a roadmap or a timeline with dates (`timeline: true`), and converts a Mermaid `gantt` to it. flowfig does not\ndraw class or ER diagrams (fields, types, cardinality), charts of numbers or mind maps. If the user asks for one of these, say that\nflowfig does not draw it, suggest Mermaid (`classDiagram`, `erDiagram`), and draw nothing with flowfig.\n\n## Workflow\n\n### 1. Pick the scope\n\nIf the code has more than one flow, name each flow in the reply. Then draw one flow, or draw one structure view and call it a\nstructure view. If the user asks for the whole system, draw one top view with groups, or a set of figures that together cover\nevery part. Keep each figure to 12 boxes or fewer.\n\n### 2. Write the fact list\n\nBefore the spec, write a list of the facts that the figure must show. Take each fact from the code and from its wiring: config\nfiles, compose files, route tables and queue bindings (or from the pasted Mermaid). Give each fact its `file:line`:\n\n- every part (service, function, store, queue, external system);\n- every call, in order, written as `caller \u2192 callee: payload (file:line of the call)`. The edge in the spec goes from that caller\n  to that callee;\n- every call that does not wait for an answer (fire and forget, a queue, a webhook, a callback), and every consumer of each queue\n  or topic;\n- every branch and every error path (a rejected input, a retry, a dead-letter path);\n- every end state;\n- for a process document (an SOP): every deadline, every message to a person (an email, a notice), every choice that a person\n  makes, and every wait for a reply. Put each one in a box `sub`, a step `say` or a `data` card. A small fact still counts.\n\nIf the code does not show a fact, leave the fact out. Do not guess a part, a name or an order.\n\n### 3. Write the spec\n\nEach fact becomes a box, an edge, a beat, a `data` card or a `show` row. Use the real names from the code as labels, and\nreal example data from the code or its tests. Keep each fact that you leave out, with the reason, for the reply.\nGive each box and edge that draws code a `source`, from the fact list: `\"src/auth/login.ts#verifyPassword\"`. A store or an outside part may have none.\nA box that draws a step from a document links to that document: `\"docs/sop/refunds.md#step-3-approve-the-refund\"`, the heading as a GitHub anchor. `verify` checks it the same way.\n\nMermaid mapping:\n\n| Mermaid                                  | flowfig                                                            |\n| ---------------------------------------- | ------------------------------------------------------------------ |\n| `participant`                            | a box                                                              |\n| `A->>B: text`                            | an edge from A to B, and a hop with `data: \"text\"`                 |\n| `B-->>A: text` (a reply)                 | a hop on the same edge with `back: true`                           |\n| `A-)B: text` (async)                     | a hop with `async: true`                                           |\n| `par ... and ... end`                    | the hops of all branches in one beat                               |\n| `alt` / `opt`                            | one step per path                                                  |\n| `stateDiagram` states and transitions    | boxes, and edges labeled with the event                            |\n\n### 4. Render, then fix\n\n```bash\nnpx flowfig - out.svg <<'SPEC'\n{ \"props\": { \"layout\": ..., \"edges\": [...], \"steps\": [...] } }\nSPEC\n```\n\nThe quoted `<<'SPEC'` heredoc passes the JSON with no change. The command checks the spec first. If the check finds an error, the\ncommand writes no SVG and lists the faults. Fix each fault and render again.\n\n- Fix a layout fault by changing the layout first: put parts in rows or columns, route an edge `around`, or change a gap.\n  Never remove a fact from the fact list to pass the check. If you must remove one, name it in the reply.\n- If `small-text` appears, the figure is too wide. Put the parts in two rows, move a detail from `label` to `sub`, or split\n  the figure. Use more steps in one figure before you make a second figure. Keep the real name from the code in the label:\n  `ReportsController` stays `ReportsController`, not `Controller`. Do not change `--width` to pass the check: the\n  reader sees the figure at the real page width.\n- Fix every other warning, or tell the user why it stays.\n- Do not use `--no-check` to hide a fault.\n\n### 5. Read the figure back\n\nRun `npx flowfig --spec out.svg`. Compare the spec with the fact list. Check that each edge goes from the caller to the callee\nthat its fact names. Add each fact that is missing, fix each wrong edge, and render again.\n\nRun `npx flowfig verify out.svg` from the repo root. Fix each `missing-file` or `missing-symbol`.\n\n### 6. Look at the SVG\n\nThe check estimates the text width, so it cannot see everything. If you can open a browser, open the SVG and take a\nscreenshot. Wait a few seconds and take a second screenshot to see a later beat. If you cannot open a browser, write \"not\nlooked at\" in the reply. Never report a look that you did not do. A browser tool can block `file://` URLs. If it does, serve the folder\nwith `python3 -m http.server`.\n\n### 7. Write the reply\n\nThe reply has these parts, in this order:\n\n1. the path of each SVG;\n2. what each figure shows: the parts and the steps. Copy the counts from the `figure:` line of the check output. Copy every name\n   from the read-back spec. Never count from memory;\n3. the scope: the flow you drew, why, and the other flows that exist;\n4. what the figure leaves out, and why;\n5. the two check lines that the render printed, `0 errors, 0 warnings` and `figure: ...`, copied as printed, and whether\n   you looked at the SVG;\n6. one line `npx flowfig open <path>` for each SVG, at the end of the reply. Do not run that command yourself.\n\nTo change an SVG later, print its spec with `--spec`, change the spec, and render again.\n\n## Spec reference\n\n`props` has these fields.\n\n| Field      | Type                    | Meaning                                                                                        |\n| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------- |\n| `layout`   | group                   | The boxes and how they line up. Required.                                                      |\n| `edges`    | edge[]                  | The arrows between the boxes. Required.                                                        |\n| `steps`    | step[]                  | The stories the figure tells. With no steps, the figure is a still map.                        |\n| `lanes`    | `true`                | Draw the layout as swimlanes: a `column` group of labeled groups, one per role. The boxes run left to right in step order. |\n| `timeline` | `true`               | Draw the layout as a timeline: one labeled group per track, with the boxes placed by their `from` and `to` dates. |\n| `today`    | `YYYY-MM-DD`          | In a `timeline` figure: the date where the today line stops. Default: the last date of the items. |\n| `rail`     | `true` or `\"only\"`      | Draw the steps as a lifeline rail under the map. `\"only\"` draws the rail without the map.      |\n| `speed`    | number                  | Milliseconds a packet takes to cross one edge. Default: 900.                                   |\n| `theme`    | object                  | Colors: `accent`, `fg`, `muted`, `bg`, `surface`, `border`, `font`. Each color you omit keeps its built-in value. |\n\n### layout\n\nThe layout is a tree. A group has `children` and these optional fields.\n\n- `id`: a name that an edge can use to reach the group as a whole.\n- `label`: the title on the frame. Only a group with a `label` gets a frame.\n- `direction`: `\"row\"` (the default) or `\"column\"`.\n- `gap`: the space between children in px. Default: 28 for a column. For a row, the gap fits the widest edge label between two children (at least 56).\n- `align`: `\"start\"`, `\"center\"` or `\"end\"`. This sets where the children line up across the direction.\n\nEvery other item is a box.\n\n| Box field | Meaning                                                                                                   |\n| --------- | --------------------------------------------------------------------------------------------------------- |\n| `id`      | Required. The name that edges and steps use. It must be unique in the figure.                             |\n| `label`   | Required. The title in the box.                                                                           |\n| `sub`     | A smaller line under the label.                                                                           |\n| `shape`   | `\"box\"` (default), `\"decision\"` (a diamond) or `\"store\"` (a database cylinder for data at rest).          |\n| `at`      | In a `lanes` figure: the time column of the box, 0 first. Default: the order in which the steps first reach the box. |\n| `from`    | In a `timeline` figure: the start of the item, or the date of a milestone, as YYYY-MM-DD. |\n| `to`      | In a `timeline` figure: the last day of the item, as YYYY-MM-DD. Without it the box is a milestone. |\n| `width`   | Width in px. This overrides the width that the layout picks.                                              |\n| `source`  | The code this draws: `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it.  |\n| `lines`   | The least number of text lines that a content card keeps. The card still grows to fit its content.        |\n| `tone`    | The state color of the box: a 1 px border and a light tint. Use `blue`, `purple`, `green`, `orange`, `red` or `gray`.                  |\n| `mark`    | `\"start\"` or `\"end\"` | A lifecycle mark: a filled dot before a start state, a ringed dot after an end state. |\n\n### edges\n\nAn edge has these fields.\n\n- `id`: the name that steps use. Default: `from->to`.\n- `from` and `to`: the `id` of a box or a group.\n- `label`: text on the edge, drawn as a small pill.\n- `around`: `\"above\"` or `\"below\"`. This routes the edge over or under the boxes in between (loops, skip-ahead edges).\n- `quiet`: if `true`, the SVG draws the edge only while a step uses it.\n- `source`: the code this edge draws, as `path` or `path#symbol`. `flowfig verify` checks it.\n\n### steps\n\nA step has `label` and `flow`. It can also have `caption` (the line under the figure while no beat has a `say`) and `nodes` (ids of\nboxes to highlight for the whole step).\n\n`flow` is a list of beats. A beat is one of these:\n\n- an edge id (a string);\n- an array of edge ids, which run at the same time;\n- an object `{ edges?, say?, show?, light?, ms? }`. A beat with no `edges` is a pause.\n\nThe beat fields:\n\n- `edges`: an edge id, a hop object, or an array of these. A hop object is `{ edge, back?, data?, tone?, async?, source? }`.\n  - `back: true` runs the packet from the `to` box to the `from` box.\n  - `data` is a small card that moves with the packet.\n  - `async: true` marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag.\n  - `tone`: the color of this hop for its beat. The packet, the data card, the edge, the label pill and the arrival box take the color. The trail after the beat stays the accent.\n    - `green`: a success or a cache hit. `orange`: a warning, a miss or a retry. `red`: an error or a rejected input.\n    - `gray`: idle or skipped. `purple`: async or background. `blue`: the default row color.\n    - If the hop has no `tone`, the arrival box uses its box `tone`, then the accent. A hop `tone` wins over a box `tone`.\n- `say`: the caption for the beat.\n- `show`: `{ boxId: [row, ...] }`. This fills the content card of each named box. The card keeps the rows until the step ends.\n- `light`: ids of boxes to highlight for this beat.\n- `ms`: how long the beat lasts. Default: the time one packet needs to cross an edge.\n\nA row of a content card is `{ tag?, tone?, text, meta?, mark?, mono? }`.\n\n- `tag`: a short colored label at the start of the line.\n- `tone`: the color of the tag: `blue` (default), `purple`, `green`, `orange`, `red` or `gray`.\n- `text`: the main text.\n- `meta`: muted text after the main text.\n- `mark`: a mark at the right end of the line, such as a check or \"new\".\n- `mono`: if `true`, the text uses a monospace font.\n\n## Content rules\n\n- Give every box a stable `id`.\n- Use `shape: \"store\"` for data at rest (a database, a cache, a file, a queue). Use a plain box for a part that does work. Use `shape: \"decision\"` for a branch.\n- Keep one clear main path, left to right. Put side parts in a `column` group.\n- Use `quiet: true` on a long edge that crosses the picture. A quiet edge needs a beat that uses it, or the check reports\n  `hidden-edge`.\n- In a rail, draw an error reply as a hop back on the same edge, with the error in `data` (`{ \"edge\": \"login\", \"back\": true,\n  \"data\": \"401 CREDENTIALS_INVALID\" }`). A call that stays inside one part (a hash check, a guard) is not a message: put it in\n  `say` or in a `show` row of that part.\n- Keep an SVG to one or two steps. The SVG plays every step in a loop, with no controls.\n- Use the React player, `<Flow {...props} />` from `flowfig`, for a page that needs tabs, pause or hover.\n\n## Example\n\n```json\n{\n  \"props\": {\n    \"layout\": {\n      \"children\": [\n        { \"id\": \"client\", \"label\": \"Browser\" },\n        { \"id\": \"api\", \"label\": \"API Server\" },\n        { \"id\": \"db\", \"label\": \"Database\", \"shape\": \"store\" }\n      ]\n    },\n    \"edges\": [\n      { \"id\": \"req\", \"from\": \"client\", \"to\": \"api\", \"label\": \"GET /users/42\" },\n      { \"id\": \"q\", \"from\": \"api\", \"to\": \"db\", \"label\": \"SELECT\" }\n    ],\n    \"steps\": [\n      {\n        \"label\": \"read\",\n        \"flow\": [\n          { \"edges\": { \"edge\": \"req\", \"data\": \"GET /users/42\" }, \"say\": \"The browser asks for user 42.\" },\n          { \"edges\": \"q\", \"show\": { \"db\": [{ \"tag\": \"row\", \"tone\": \"gray\", \"text\": \"Ada Lovelace\" }] }, \"say\": \"The API server reads the row.\" },\n          { \"edges\": { \"edge\": \"req\", \"back\": true, \"data\": \"200 OK\" }, \"say\": \"The API server sends the user.\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Commands\n\n```bash\nnpx flowfig - out.svg < spec.json      # render a spec from stdin\nnpx flowfig spec.json out.svg          # render a spec file\nnpx flowfig figure.ts out.svg          # render a module whose default export is a spec\nnpx flowfig check <input> [--json]     # list the faults. The input can also be an SVG that flowfig wrote.\nnpx flowfig verify <input>...          # check that the code each source names still exists\nnpx flowfig diff <old> <new>           # list what changed in the spec between two figures\nnpx flowfig --spec out.svg             # print the spec that an SVG carries\nnpx flowfig open out.svg               # show the figure in the default browser\nnpx flowfig gif out.svg [out.gif]      # write an animated GIF (needs Chrome, Edge, Chromium or Brave)\nnpx flowfig docs                       # print this guide\nnpx flowfig init                       # write these instructions for the coding agents of a repo\n```\n\nA render checks first and writes nothing on an error. `--strict` makes warnings errors. `--width` sets the page width.\n`--min-text` sets the smallest text that the reader should get. `--no-check` skips the check.\n";
+export declare const GUIDE = "# flowfig guide\n\nflowfig draws animated flow figures. A figure has boxes, the edges between the boxes, and steps. In each step, a packet moves along\nthe edges. The output is one animated SVG with no script. The SVG plays in a GitHub README, in PR and issue comments, and in blog\nposts. A figure is about 5 to 50 kB.\n\nYou write a JSON spec. You never write SVG by hand. The command `npx flowfig` checks the spec and renders it.\n\n## What flowfig draws\n\nA spec has three forms.\n\n- The map (the default). The map shows the boxes and the edges. A packet moves along an edge in each beat.\n- The map with a rail (`\"rail\": true`). The rail is a lifeline diagram under the map. It has one row for each message.\n- The rail alone (`\"rail\": \"only\"`). Use it when the reader needs only the order of the messages, for example when the map is already in the same document.\n\nUse the rail for a sequence of messages: a request lifecycle, an API call chain, or a Mermaid `sequenceDiagram`. Put each message on\nan edge. Put each phase in a step. Put messages that run at the same time in one beat. Mark a message that does not wait for an\nanswer with `\"async\": true`: every send to a queue or a topic, every emitted event, and every call the caller does not await.\n\n## Scope: what flowfig draws and what it does not\n\nflowfig draws how something works: parts, the messages between them, and the order of the messages.\n\n| The user asks for                          | Draw                                                                                       |\n| ------------------------------------------ | ------------------------------------------------------------------------------------------ |\n| An architecture, a data flow, a pipeline   | The map. Group parts by service, network or trust boundary. `store` for data at rest.       |\n| A request lifecycle, a call chain          | The map with `\"rail\": true`. One message per hop, with its real payload in `data`.          |\n| A sequence diagram only                    | `\"rail\": \"only\"`.                                                                           |\n| A state lifecycle, a state machine         | One box per state, one edge per transition, labeled with its event. One step per path. Mark the first state with `mark: \"start\"` and each final state with `mark: \"end\"`. |\n| A flowchart with branches                  | `shape: \"decision\"` for each branch. One step per path.                                     |\n| A roadmap or a timeline | `timeline: true`. One labeled group per track, in a `column` group. Items with `from` and `to` (dates), a milestone with `from` only, an edge for a dependency, `today` for the line. A dependent item starts after its source ends. |\n| A process across roles (a ticket, an order, a refund) | `lanes: true`. One labeled group per role, in a `column` group. Put each step in the lane of the role that does it. Link each step with `source` to the SOP heading. If the steps do not fit the width, flowfig wraps the time columns into blocks and links the blocks with labeled stubs, so keep the whole process in one figure. Give the outcomes of one decision the same `at`. |\n\nflowfig draws a roadmap or a timeline with dates (`timeline: true`), and converts a Mermaid `gantt` to it. flowfig does not\ndraw class or ER diagrams (fields, types, cardinality), charts of numbers or mind maps. If the user asks for one of these, say that\nflowfig does not draw it, suggest Mermaid (`classDiagram`, `erDiagram`), and draw nothing with flowfig.\n\n## Workflow\n\n### 1. Pick the scope\n\nIf the code has more than one flow, name each flow in the reply. Then draw one flow, or draw one structure view and call it a\nstructure view. If the user asks for the whole system, draw one top view with groups, or a set of figures that together cover\nevery part. Keep each figure to 12 boxes or fewer.\n\n### 2. Write the fact list\n\nBefore the spec, write a list of the facts that the figure must show. Take each fact from the code and from its wiring: config\nfiles, compose files, route tables and queue bindings (or from the pasted Mermaid). Give each fact its `file:line`:\n\n- every part (service, function, store, queue, external system);\n- every call, in order, written as `caller \u2192 callee: payload (file:line of the call)`. The edge in the spec goes from that caller\n  to that callee;\n- every call that does not wait for an answer (fire and forget, a queue, a webhook, a callback), and every consumer of each queue\n  or topic;\n- every branch and every error path (a rejected input, a retry, a dead-letter path);\n- every end state;\n- for a process document (an SOP): every deadline, every message to a person (an email, a notice), every choice that a person\n  makes, and every wait for a reply. Put each one in a box `sub`, a step `say` or a `data` card. A small fact still counts.\n  Draw each path to its end: after a rejection, also draw the next step that the document gives. Give each path its own step.\n\nIf the code does not show a fact, leave the fact out. Do not guess a part, a name or an order.\n\n### 3. Write the spec\n\nEach fact becomes a box, an edge, a beat, a `data` card or a `show` row. Use the real names from the code as labels, and\nreal example data from the code or its tests. Keep each fact that you leave out, with the reason, for the reply.\nGive each box and edge that draws code a `source`, from the fact list: `\"src/auth/login.ts#verifyPassword\"`. A store or an outside part may have none.\nA box that draws a step from a document links to that document: `\"docs/sop/refunds.md#step-3-approve-the-refund\"`, the heading as a GitHub anchor. `verify` checks it the same way.\n\nMermaid mapping:\n\n| Mermaid                                  | flowfig                                                            |\n| ---------------------------------------- | ------------------------------------------------------------------ |\n| `participant`                            | a box                                                              |\n| `A->>B: text`                            | an edge from A to B, and a hop with `data: \"text\"`                 |\n| `B-->>A: text` (a reply)                 | a hop on the same edge with `back: true`                           |\n| `A-)B: text` (async)                     | a hop with `async: true`                                           |\n| `par ... and ... end`                    | the hops of all branches in one beat                               |\n| `alt` / `opt`                            | one step per path                                                  |\n| `stateDiagram` states and transitions    | boxes, and edges labeled with the event                            |\n\nA pasted design wins over the async rule: keep each arrow as the Mermaid draws it. `A->>B` stays a plain hop, also for a\nsend to a queue. Mark a hop async only for `-)`. If you think the design is wrong, say so in the reply.\n\n### 4. Render, then fix\n\n```bash\nnpx flowfig - out.svg <<'SPEC'\n{ \"props\": { \"layout\": ..., \"edges\": [...], \"steps\": [...] } }\nSPEC\n```\n\nThe quoted `<<'SPEC'` heredoc passes the JSON with no change. The command checks the spec first. If the check finds an error, the\ncommand writes no SVG and lists the faults. Fix each fault and render again.\n\n- Fix a layout fault by changing the layout first: put parts in rows or columns, route an edge `around`, or change a gap.\n  Never remove a fact from the fact list to pass the check. If you must remove one, name it in the reply.\n- If `small-text` appears, the figure is too wide. Put the parts in two rows, move a detail from `label` to `sub`, or split\n  the figure. Use more steps in one figure before you make a second figure. Keep the real name from the code in the label:\n  `ReportsController` stays `ReportsController`, not `Controller`. Do not change `--width` to pass the check: the\n  reader sees the figure at the real page width.\n- If `text-overflow` appears, a text is wider than its box. Give the box a larger `width`, move a detail from `label` to\n  `sub`, or put the detail in the step `say`. Never cut a fact, a number or a unit to make a text fit: \"within 30 days of\n  delivery\" does not become \"within 30 days\". If you must shorten a text, keep every fact and name the change in the reply.\n- Fix every other warning, or tell the user why it stays.\n- Do not use `--no-check` to hide a fault.\n\n### 5. Read the figure back\n\nRun `npx flowfig --spec out.svg`. Compare the spec with the fact list. Check that each edge goes from the caller to the callee\nthat its fact names. Add each fact that is missing, fix each wrong edge, and render again.\n\nRun `npx flowfig verify out.svg` from the repo root. Fix each `missing-file` or `missing-symbol`.\n\n### 6. Look at the SVG\n\nThe check estimates the text width, so it cannot see everything. If you can open a browser, open the SVG and take a\nscreenshot. Wait a few seconds and take a second screenshot to see a later beat. If you cannot open a browser, write \"not\nlooked at\" in the reply. Never report a look that you did not do. A browser tool can block `file://` URLs. If it does, serve the folder\nwith `python3 -m http.server`.\n\n### 7. Write the reply\n\nThe reply has these parts, in this order:\n\n1. the path of each SVG;\n2. what each figure shows: the parts and the steps. Copy the counts from the `figure:` line of the check output. Copy every name\n   from the read-back spec. Never count from memory;\n3. the scope: the flow you drew, why, and the other flows that exist;\n4. what the figure leaves out, and why;\n5. the two check lines that the render printed, `0 errors, 0 warnings` and `figure: ...`, copied as printed, and whether\n   you looked at the SVG;\n6. one line `npx flowfig open <path>` for each SVG, at the end of the reply. Do not run that command yourself.\n\nTo change an SVG later, print its spec with `--spec`, change the spec, and render again.\n\n## Spec reference\n\n`props` has these fields.\n\n| Field      | Type                    | Meaning                                                                                        |\n| ---------- | ----------------------- | ---------------------------------------------------------------------------------------------- |\n| `layout`   | group                   | The boxes and how they line up. Required.                                                      |\n| `edges`    | edge[]                  | The arrows between the boxes. Required.                                                        |\n| `steps`    | step[]                  | The stories the figure tells. With no steps, the figure is a still map.                        |\n| `lanes`    | `true`                | Draw the layout as swimlanes: a `column` group of labeled groups, one per role. The boxes run left to right in step order. |\n| `timeline` | `true`               | Draw the layout as a timeline: one labeled group per track, with the boxes placed by their `from` and `to` dates. |\n| `today`    | `YYYY-MM-DD`          | In a `timeline` figure: the date where the today line stops. Default: the last date of the items. |\n| `rail`     | `true` or `\"only\"`      | Draw the steps as a lifeline rail under the map. `\"only\"` draws the rail without the map.      |\n| `speed`    | number                  | Milliseconds a packet takes to cross one edge. Default: 900.                                   |\n| `theme`    | object                  | Colors: `accent`, `fg`, `muted`, `bg`, `surface`, `border`, `font`. Each color you omit keeps its built-in value. |\n\n### layout\n\nThe layout is a tree. A group has `children` and these optional fields.\n\n- `id`: a name that an edge can use to reach the group as a whole.\n- `label`: the title on the frame. Only a group with a `label` gets a frame.\n- `direction`: `\"row\"` (the default) or `\"column\"`.\n- `gap`: the space between children in px. Default: 28 for a column. For a row, the gap fits the widest edge label between two children (at least 56).\n- `align`: `\"start\"`, `\"center\"` or `\"end\"`. This sets where the children line up across the direction.\n\nEvery other item is a box.\n\n| Box field | Meaning                                                                                                   |\n| --------- | --------------------------------------------------------------------------------------------------------- |\n| `id`      | Required. The name that edges and steps use. It must be unique in the figure.                             |\n| `label`   | Required. The title in the box.                                                                           |\n| `sub`     | A smaller line under the label.                                                                           |\n| `shape`   | `\"box\"` (default), `\"decision\"` (a diamond) or `\"store\"` (a database cylinder for data at rest).          |\n| `at`      | In a `lanes` figure: the time column of the box, 0 first. Default: the order in which the steps first reach the box. |\n| `from`    | In a `timeline` figure: the start of the item, or the date of a milestone, as YYYY-MM-DD. |\n| `to`      | In a `timeline` figure: the last day of the item, as YYYY-MM-DD. Without it the box is a milestone. |\n| `width`   | Width in px. This overrides the width that the layout picks.                                              |\n| `source`  | The code this draws: `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it.  |\n| `lines`   | The least number of text lines that a content card keeps. The card still grows to fit its content.        |\n| `tone`    | The state color of the box: a 1 px border and a light tint. Use `blue`, `purple`, `green`, `orange`, `red` or `gray`.                  |\n| `mark`    | `\"start\"` or `\"end\"` | A lifecycle mark: a filled dot before a start state, a ringed dot after an end state. |\n\n### edges\n\nAn edge has these fields.\n\n- `id`: the name that steps use. Default: `from->to`.\n- `from` and `to`: the `id` of a box or a group.\n- `label`: text on the edge, drawn as a small pill.\n- `around`: `\"above\"` or `\"below\"`. This routes the edge over or under the boxes in between (loops, skip-ahead edges).\n- `quiet`: if `true`, the SVG draws the edge only while a step uses it.\n- `source`: the code this edge draws, as `path` or `path#symbol`. `flowfig verify` checks it.\n\n### steps\n\nA step has `label` and `flow`. It can also have `caption` (the line under the figure while no beat has a `say`) and `nodes` (ids of\nboxes to highlight for the whole step).\n\n`flow` is a list of beats. A beat is one of these:\n\n- an edge id (a string);\n- an array of edge ids, which run at the same time;\n- an object `{ edges?, say?, show?, light?, ms? }`. A beat with no `edges` is a pause.\n\nThe beat fields:\n\n- `edges`: an edge id, a hop object, or an array of these. A hop object is `{ edge, back?, data?, tone?, async?, source? }`.\n  - `back: true` runs the packet from the `to` box to the `from` box.\n  - `data` is a small card that moves with the packet.\n  - `async: true` marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag.\n  - `tone`: the color of this hop for its beat. The packet, the data card, the edge, the label pill and the arrival box take the color. The trail after the beat stays the accent.\n    - `green`: a success or a cache hit. `orange`: a warning, a miss or a retry. `red`: an error or a rejected input.\n    - `gray`: idle or skipped. `purple`: async or background. `blue`: the default row color.\n    - If the hop has no `tone`, the arrival box uses its box `tone`, then the accent. A hop `tone` wins over a box `tone`.\n- `say`: the caption for the beat.\n- `show`: `{ boxId: [row, ...] }`. This fills the content card of each named box. The card keeps the rows until the step ends.\n- `light`: ids of boxes to highlight for this beat.\n- `ms`: how long the beat lasts. Default: the time one packet needs to cross an edge.\n\nA row of a content card is `{ tag?, tone?, text, meta?, mark?, mono? }`.\n\n- `tag`: a short colored label at the start of the line.\n- `tone`: the color of the tag: `blue` (default), `purple`, `green`, `orange`, `red` or `gray`.\n- `text`: the main text.\n- `meta`: muted text after the main text.\n- `mark`: a mark at the right end of the line, such as a check or \"new\".\n- `mono`: if `true`, the text uses a monospace font.\n\n## Content rules\n\n- Give every box a stable `id`.\n- Use `shape: \"store\"` for data at rest (a database, a cache, a file, a queue). Use a plain box for a part that does work. Use `shape: \"decision\"` for a branch.\n- Keep one clear main path, left to right. Put side parts in a `column` group.\n- Use `quiet: true` on a long edge that crosses the picture. A quiet edge needs a beat that uses it, or the check reports\n  `hidden-edge`.\n- In a rail, draw an error reply as a hop back on the same edge, with the error in `data` (`{ \"edge\": \"login\", \"back\": true,\n  \"data\": \"401 CREDENTIALS_INVALID\" }`). A call that stays inside one part (a hash check, a guard) is not a message: put it in\n  `say` or in a `show` row of that part.\n- Keep an SVG to one or two steps. The SVG plays every step in a loop, with no controls.\n- Use the React player, `<Flow {...props} />` from `flowfig`, for a page that needs tabs, pause or hover.\n\n## Example\n\n```json\n{\n  \"props\": {\n    \"layout\": {\n      \"children\": [\n        { \"id\": \"client\", \"label\": \"Browser\" },\n        { \"id\": \"api\", \"label\": \"API Server\" },\n        { \"id\": \"db\", \"label\": \"Database\", \"shape\": \"store\" }\n      ]\n    },\n    \"edges\": [\n      { \"id\": \"req\", \"from\": \"client\", \"to\": \"api\", \"label\": \"GET /users/42\" },\n      { \"id\": \"q\", \"from\": \"api\", \"to\": \"db\", \"label\": \"SELECT\" }\n    ],\n    \"steps\": [\n      {\n        \"label\": \"read\",\n        \"flow\": [\n          { \"edges\": { \"edge\": \"req\", \"data\": \"GET /users/42\" }, \"say\": \"The browser asks for user 42.\" },\n          { \"edges\": \"q\", \"show\": { \"db\": [{ \"tag\": \"row\", \"tone\": \"gray\", \"text\": \"Ada Lovelace\" }] }, \"say\": \"The API server reads the row.\" },\n          { \"edges\": { \"edge\": \"req\", \"back\": true, \"data\": \"200 OK\" }, \"say\": \"The API server sends the user.\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## Commands\n\n```bash\nnpx flowfig - out.svg < spec.json      # render a spec from stdin\nnpx flowfig spec.json out.svg          # render a spec file\nnpx flowfig figure.ts out.svg          # render a module whose default export is a spec\nnpx flowfig check <input> [--json]     # list the faults. The input can also be an SVG that flowfig wrote.\nnpx flowfig verify <input>...          # check that the code each source names still exists\nnpx flowfig diff <old> <new>           # list what changed in the spec between two figures\nnpx flowfig --spec out.svg             # print the spec that an SVG carries\nnpx flowfig open out.svg               # show the figure in the default browser\nnpx flowfig gif out.svg [out.gif]      # write an animated GIF (needs Chrome, Edge, Chromium or Brave)\nnpx flowfig docs                       # print this guide\nnpx flowfig init                       # write these instructions for the coding agents of a repo\n```\n\nA render checks first and writes nothing on an error. `--strict` makes warnings errors. `--width` sets the page width.\n`--min-text` sets the smallest text that the reader should get. `--no-check` skips the check.\n";
 /** The short instruction text that `flowfig init` writes for each coding agent. */
 export declare const AGENT_TEXT = "# Diagrams with flowfig\n\nIf the user names no other tool, use flowfig for every diagram, figure, flowchart or picture of how something works. Do not answer with a Mermaid block or ASCII art. Use it for an architecture, a data flow or pipeline, a request lifecycle,\na call sequence, a state lifecycle, or a flowchart. flowfig also converts a pasted Mermaid flowchart, `stateDiagram` or\n`sequenceDiagram`.\n\nflowfig draws a roadmap or a timeline with dates (`timeline: true`), and converts a Mermaid `gantt` to it. flowfig does not\ndraw class or ER diagrams or charts of numbers. For those, tell the user so, suggest Mermaid (`classDiagram`, `erDiagram`),\nand draw nothing with flowfig.\n\n1. Run `npx flowfig docs` and read it. If the command fails, stop: tell the user that flowfig is not available, give them\n   `npm install --save-dev flowfig`, and draw nothing with another tool.\n2. Pick the scope. If the code has more than one flow, name each flow in the reply, then draw one flow, or draw one structure\n   view and call it a structure view. If the user asks for the whole system, draw one top view with groups, or a set of figures\n   that together cover every part. Keep each figure to 12 boxes or fewer. For a process that several roles do, use\n   `lanes: true`, one labeled group per role. For a plan or a roadmap, read the dates from the document and use `timeline: true`.\n3. Write a fact list from the code and from its wiring (config, compose, route and queue files). Write each call as\n   `caller \u2192 callee: payload (file:line of the call)`, in order. Include each async call and every consumer of a queue, each\n   branch and error path, and each end state. Leave out what the code does not show.\n4. Write the spec from the fact list, with the real names and data. Render it with `npx flowfig - out.svg <<'SPEC'` and the\n   JSON in the heredoc. Fix every fault by changing the layout first (rows, `around`, the gap). Never remove a fact to pass\n   the check; if you must remove one, name it in the reply. If `small-text` appears, use two rows or split the figure; keep\n   the real names; do not change `--width`. Give each box and edge that draws code a `source` (`file#symbol`) from the fact list.\n   Mark every send to a queue or a topic, every emitted event, and every call the caller does not await with `async: true`.\n5. Run `npx flowfig --spec out.svg` and compare it with the fact list: each edge must go from the caller to the callee that the\n   fact names. Fix each gap. Then run `npx flowfig verify out.svg` from the repo root and fix each fault.\n6. If you can open a browser, look at the SVG at two moments of the loop. If you cannot, write \"not looked at\" in the reply.\n   Never report a look that you did not do.\n7. Reply with: the SVG path; what it shows, with the counts copied from the `figure:` line and the names copied from the read-back spec; what it leaves out and why;\n   the two lines the render printed, `0 errors, 0 warnings` and `figure: ...`, copied as printed.\n   End the reply with one line `npx flowfig open <path>` for each SVG. Do not run that command yourself.\n";
 /** The description of the Claude skill: the words that make the agent load it. */

package/dist/guide.js

@@ -60,6 +60,7 @@ files, compose files, route tables and queue bindings (or from the pasted Mermai
 - every end state;
 - for a process document (an SOP): every deadline, every message to a person (an email, a notice), every choice that a person
   makes, and every wait for a reply. Put each one in a box \`sub\`, a step \`say\` or a \`data\` card. A small fact still counts.
+  Draw each path to its end: after a rejection, also draw the next step that the document gives. Give each path its own step.
 
 If the code does not show a fact, leave the fact out. Do not guess a part, a name or an order.
 
@@ -82,6 +83,9 @@ Mermaid mapping:
 | \`alt\` / \`opt\`                            | one step per path                                                  |
 | \`stateDiagram\` states and transitions    | boxes, and edges labeled with the event                            |
 
+A pasted design wins over the async rule: keep each arrow as the Mermaid draws it. \`A->>B\` stays a plain hop, also for a
+send to a queue. Mark a hop async only for \`-)\`. If you think the design is wrong, say so in the reply.
+
 ### 4. Render, then fix
 
 \`\`\`bash
@@ -99,6 +103,9 @@ command writes no SVG and lists the faults. Fix each fault and render again.
   the figure. Use more steps in one figure before you make a second figure. Keep the real name from the code in the label:
   \`ReportsController\` stays \`ReportsController\`, not \`Controller\`. Do not change \`--width\` to pass the check: the
   reader sees the figure at the real page width.
+- If \`text-overflow\` appears, a text is wider than its box. Give the box a larger \`width\`, move a detail from \`label\` to
+  \`sub\`, or put the detail in the step \`say\`. Never cut a fact, a number or a unit to make a text fit: "within 30 days of
+  delivery" does not become "within 30 days". If you must shorten a text, keep every fact and name the change in the reply.
 - Fix every other warning, or tell the user why it stays.
 - Do not use \`--no-check\` to hide a fault.
 

package/dist/index.js

@@ -5,7 +5,7 @@ import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.js';
 import { textWidth } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, EDGE_OFF, EDGE_ON, LIGHT, TONES, ON_ACCENT, toneFill, toneTint, decisions, edgeId, groupGap, isGroup, isRows, lanePlan as planLanes, laneEnd, laneBlock, STUB_ROOM, labelPillW, str, LANE_BLOCK_GAP, LANE_PAD, LANE_ROW_GAP, isLanesLayout, nodes, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, diamondLines, diamondRoom, tightCopies, nodeWidth, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
@@ -72,6 +72,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
     const bar = useRef(null); // the active tab's progress line
     const [beat, setBeat] = useState(0);
     const [holding, setHolding] = useState(false); // the step hold: a timeline's today line rests at today
+    const [returning, setReturning] = useState(false); // the end of the last hold: the playhead moves back to the loop start
+    const firstLabel = useRef(''); // the playhead date of the first mount, which shows at once; '' before the first render
     const paths = useRef({});
     const [routed, setRouted] = useState([]);
     // Lane copies that grow because a stub there had no place clear of every edge path (see `tightCopies`).
@@ -177,6 +179,11 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                 const r = n.getBoundingClientRect();
                 avoid.push({ x: (r.left - base.left) / k, y: (r.top - base.top) / k, w: r.width / k, h: r.height / k });
             });
+            // A timeline elbow keeps clear of the bars and milestones it does not connect, as in the SVG.
+            if (tl)
+                for (const n of nodes(layout))
+                    if (rects[n.id])
+                        avoid.push({ ...rects[n.id], box: true });
             // Wrapped lanes: an edge between two blocks is two stubs with pills, clear of the boxes and the lane labels.
             const stubs = lanePlan?.stubs ?? new Map();
             if (stubs.size) {
@@ -225,8 +232,8 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     stub: stubs.get(ids[i]).map(labelPillW),
                     bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)],
                 }),
-                ...(stubs.size && e.label != null && { labelW: labelPillW(str(e.label)) }),
-            })), rects, tips, avoid, pillArea);
+                ...((stubs.size || lanePlan) && e.label != null && { labelW: labelPillW(str(e.label)) }),
+            })), rects, tips, avoid, pillArea, lanePlan ? { bands: Object.values(laneBands), boxes: nodes(layout).flatMap((n) => (rects[n.id] ? [rects[n.id]] : [])) } : undefined);
             setRouted(next);
             if (lanePlan) {
                 const more = [...tightCopies(layout.children, lanePlan.ends, edges, next)].filter((k) => !lanePlan.tall.has(k) && !extraTall.has(k));
@@ -378,6 +385,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
             if (i !== shownBeat)
                 setBeat((shownBeat = i));
             setHolding(t >= ends.at(-1));
+            setReturning(active === steps.length - 1 && t >= total - 400 * BASE_RATE);
             const start = i ? ends[i - 1] : 0;
             const f = Math.min(1, (t - start) / speed); // the packet crosses in `speed`; the hold gives the rest
             const eased = f < 0.5 ? 2 * f * f : 1 - (-2 * f + 2) ** 2 / 2;
@@ -515,11 +523,52 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
         if (timelineFig && item === layout) {
             const lanesList = layout.children;
             // The playhead follows the latest dated focus in the step, and rests at the last date before one and in the hold.
-            const focused = holding || still ? undefined : playheadItem(timelineFig.items, beats, beat);
+            // In the last 400 ms of the loop it moves back to the loop start, so the next loop starts in place, as in the SVG.
+            const focused = still
+                ? undefined
+                : returning
+                    ? loopStartItem(timelineFig.items, steps)
+                    : holding
+                        ? undefined
+                        : playheadItem(timelineFig.items, beats, beat);
             const home = timelineFig.last ?? 0;
             const at = focused ? focused.x + (focused.milestone ? focused.w / 2 : 0) : home;
             const dateText = focused ? focused.date : timelineFig.lastDate;
             const rowsPx = timelineFig.rows.map((r) => r * TL_BAR_H + (r - 1) * TL_ROW_GAP + LANE_PAD * 2);
+            // The today line and the playhead line sit behind the bars (before them, at the bars' z-index); their labels sit on top.
+            // The playhead label waits for the line, except on the first mount, where the line starts in place.
+            if (firstLabel.current === '')
+                firstLabel.current = dateText;
+            else if (firstLabel.current !== dateText)
+                firstLabel.current = null;
+            const marks = (front) => timelineFig.last != null && (_jsxs("div", { style: { gridColumn: '2 / 4', gridRow: '1 / -1', position: 'relative', zIndex: front ? 2 : 1, pointerEvents: 'none' }, children: [timelineFig.today != null && (_jsx("div", { "data-fig-today": front ? undefined : '', style: { position: 'absolute', left: timelineFig.today, top: 12, bottom: 0, width: 0 }, children: front ? (_jsx("span", { style: {
+                                position: 'absolute',
+                                right: 3,
+                                top: -1,
+                                fontSize: 11,
+                                lineHeight: '11px',
+                                fontWeight: 600,
+                                color: v('accent'),
+                            }, children: "today" })) : (_jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, borderLeft: `1px dashed ${v('accent')}`, opacity: 0.6 } })) })), _jsx("div", { "data-fig-playhead": front ? undefined : '', style: {
+                            position: 'absolute',
+                            left: 0,
+                            top: 12,
+                            bottom: 0,
+                            width: front ? 0 : 1.5,
+                            background: front ? undefined : v('accent'),
+                            transform: `translateX(${at}px)`,
+                            transition: still ? 'none' : 'transform .4s linear',
+                        }, children: front && (_jsx("span", { style: {
+                                position: 'absolute',
+                                left: 3,
+                                top: dateLabelRaised(at, timelineFig.today, textWidth(dateText, 11), textWidth('today', 11)) ? -13 : -1,
+                                fontSize: 11,
+                                lineHeight: '11px',
+                                fontWeight: 600,
+                                whiteSpace: 'nowrap',
+                                color: v('accent'),
+                                animation: still || firstLabel.current === dateText ? undefined : 'flowfig-label .4s step-end',
+                            }, children: dateText }, dateText)) })] }));
             return (_jsxs("div", { style: {
                     display: 'grid',
                     gridTemplateColumns: `max-content minmax(${TL_AXIS_W}px, 1fr) 18px`,
@@ -527,7 +576,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                     gridTemplateRows: `${TL_AXIS_H - LANE_ROW_GAP}px ${rowsPx.map((h) => h + 'px').join(' ')}`,
                     rowGap: LANE_ROW_GAP,
                     position: 'relative',
-                }, children: [_jsxs("div", { "data-fig-axis": "", style: { gridColumn: '2 / 4', gridRow: 1, position: 'relative', height: TL_AXIS_H, alignSelf: 'start' }, children: [_jsx("div", { style: { position: 'absolute', left: 0, right: 0, top: TL_AXIS_H - 1, height: 1, background: v('border') } }), timelineFig.ticks.map((k) => (_jsxs(Fragment, { children: [_jsx("div", { style: { position: 'absolute', left: k.x, top: TL_AXIS_H - 5, width: 1, height: 4, background: v('border') } }), _jsx("div", { style: { position: 'absolute', left: k.x + 3, top: 0, fontSize: 11, lineHeight: '13px', color: v('muted') }, children: k.label })] }, k.x)))] }), lanesList.map((lane, li) => {
+                }, children: [marks(false), _jsxs("div", { "data-fig-axis": "", style: { gridColumn: '2 / 4', gridRow: 1, position: 'relative', height: TL_AXIS_H, alignSelf: 'start' }, children: [_jsx("div", { style: { position: 'absolute', left: 0, right: 0, top: TL_AXIS_H - 1, height: 1, background: v('border') } }), timelineFig.ticks.map((k) => (_jsxs(Fragment, { children: [_jsx("div", { style: { position: 'absolute', left: k.x, top: TL_AXIS_H - 5, width: 1, height: 4, background: v('border') } }), _jsx("div", { style: { position: 'absolute', left: k.x + 3, top: 0, fontSize: 11, lineHeight: '13px', color: v('muted') }, children: k.label })] }, k.x)))] }), lanesList.map((lane, li) => {
                         const lit = lane.id != null && litNodes.has(lane.id);
                         return (_jsxs(Fragment, { children: [_jsx("div", { "data-fig": lane.id, "data-fig-lane": "", style: {
                                         gridColumn: '1 / -1',
@@ -552,34 +601,7 @@ export function Flow({ layout, edges, steps: stepsIn = NONE, theme, speed = 900,
                                     }, children: lane.label }), _jsx("div", { ref: li === 0 ? area : undefined, style: { gridColumn: 2, gridRow: li + 2, position: 'relative', zIndex: 1 }, children: timelineFig.items
                                         .filter((it) => it.track === li)
                                         .map((it) => renderBar(lane.children.find((k) => k.id === it.id), it)) })] }, lane.id ?? String(lane.label)));
-                    }), timelineFig.last != null && (_jsxs("div", { style: { gridColumn: '2 / 4', gridRow: '1 / -1', position: 'relative', zIndex: 2, pointerEvents: 'none' }, children: [timelineFig.today != null && (_jsxs("div", { "data-fig-today": "", style: { position: 'absolute', left: timelineFig.today, top: 12, bottom: 0, width: 0 }, children: [_jsx("div", { style: { position: 'absolute', top: 0, bottom: 0, borderLeft: `1px dashed ${v('accent')}`, opacity: 0.6 } }), _jsx("span", { style: {
-                                            position: 'absolute',
-                                            right: 3,
-                                            top: -1,
-                                            fontSize: 11,
-                                            lineHeight: '11px',
-                                            fontWeight: 600,
-                                            color: v('accent'),
-                                        }, children: "today" })] })), _jsx("div", { "data-fig-playhead": "", style: {
-                                    position: 'absolute',
-                                    left: 0,
-                                    top: 12,
-                                    bottom: 0,
-                                    width: 1.5,
-                                    background: v('accent'),
-                                    transform: `translateX(${at}px)`,
-                                    transition: still ? 'none' : 'transform .4s linear',
-                                }, children: _jsx("span", { style: {
-                                        position: 'absolute',
-                                        left: 3,
-                                        top: dateLabelRaised(at, timelineFig.today, textWidth(dateText, 11), textWidth('today', 11)) ? -13 : -1,
-                                        fontSize: 11,
-                                        lineHeight: '11px',
-                                        fontWeight: 600,
-                                        whiteSpace: 'nowrap',
-                                        color: v('accent'),
-                                        animation: still ? undefined : 'flowfig-label .4s step-end',
-                                    }, children: dateText }, dateText) })] }))] }));
+                    }), marks(true)] }));
         }
         if (lanes && item === layout && isLanesLayout(layout)) {
             const { cols, starts, gaps, lead, blocks, gutter, tall } = lanePlan;

package/dist/init.js

@@ -1,7 +1,7 @@
 // `flowfig init`: write flowfig instructions for the coding agents of a repo. Pure functions where possible, so the tests need no TTY.
 import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 import { AGENT_TEXT, SKILL_DESCRIPTION } from './guide.js';
 import { runPicker } from './picker.js';
@@ -136,7 +136,10 @@ export function registerMcp(a, old) {
 /** `✓ ` before a finished write. */
 const mark = (status) => (/^(created|updated|unchanged)$/.test(status) ? '✓ ' : '');
 /** The path to show: relative to the repo folder, or `~` for the home folder. */
-const shown = (path, base, global) => (global ? `~/${relative(base, path)}` : relative(base, path));
+const shown = (path, base, global) => {
+    const rel = relative(base, path).split(sep).join('/'); // the output uses / on every system
+    return global ? `~/${rel}` : rel;
+};
 const HINT = 'run with -y or --agents <ids>';
 /** Run `flowfig init`. Returns the exit code. */
 export async function runInit(argv) {

package/dist/model.d.ts

@@ -218,6 +218,12 @@ export declare const playheadItem: <T extends {
 }>(items: T[], beats: {
     focus?: string[];
 }[], i: number) => T | undefined;
+/** The item the playhead rests on when the loop starts: the playhead item of the first beat of the first step. */
+export declare const loopStartItem: <T extends {
+    id: string;
+}>(items: T[], steps: {
+    flow: FigStep['flow'];
+}[]) => T | undefined;
 /** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
 export declare const outsideLabelRect: (bar: {
     x: number;

package/dist/model.js

@@ -62,6 +62,8 @@ export const playheadItem = (items, beats, i) => {
     }
     return undefined;
 };
+/** The item the playhead rests on when the loop starts: the playhead item of the first beat of the first step. */
+export const loopStartItem = (items, steps) => playheadItem(items, (steps[0]?.flow ?? []).slice(0, 1).map(toBeat), 0);
 /** The box of a timeline label that sits beside its bar, in the bar's coordinates. */
 export const outsideLabelRect = (bar, label) => ({
     x: bar.x + bar.w + 6,

package/dist/scene.d.ts

@@ -24,6 +24,8 @@ export type SceneEdge = {
     label?: Rect;
     step?: number;
     behind?: true;
+    /** The corners of a timeline elbow. `check` tests a `behind` edge against the boxes only when it has them. */
+    elbow?: Pt[];
 };
 /** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
 /** `lanes` are the lane bands of a swimlanes figure, one per lane and block, named by the lane label. A stub pill stays inside one. */

package/dist/svg.js

@@ -12,7 +12,7 @@ import { textWidth, wrap } from './text.js';
 import { checkScene, checkSpec, checkTheme } from './check.js';
 export { parseSource, links } from './source.js';
 export { diff, formatDiff } from './diff.js';
-import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, lanePlan, STUB_ROOM, laneBlock, laneEnd, tightCopies, nodeWidth, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, dateLabelRaised, labelSpan, outsideLabelRect, } from './model.js';
+import { ASYNC_TAG_W, BASE_RATE, CARD_LINE, CARD_PAD, CARD_WIDTH, DARK, EDGE_OFF, EDGE_ON, LIGHT, TONES, toneFill, toneTint, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, LANE_PAD, LANE_ROW_GAP, LANE_BLOCK_GAP, FRAME_SIDE, laneGutter as gutterOf, lanePlan, STUB_ROOM, laneBlock, laneEnd, tightCopies, nodeWidth, diamondLines, diamondRoom, isLanesLayout, timelineBeats, timelineLayout, TL_AXIS_H, TL_AXIS_W, TL_BAR_H, TL_ROW_GAP, toBeat, beatMs, STEP_HOLD_MS, playheadItem, loopStartItem, dateLabelRaised, labelSpan, outsideLabelRect, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const LINE = CARD_LINE, CARD_SIDE = 8, ROW_GAP = 4;
 const LABEL_LINE = 18, SUB_LINE = 15;
@@ -253,12 +253,16 @@ export function render(fig, opts = {}) {
             around: e.around ?? (plan?.around.has(ids[i]) ? 'below' : undefined),
             ...(tl && { sides: ['r', 'l'], elbow: true }),
             ...(stubs.has(ids[i]) && { stub: stubs.get(ids[i]).map(labelPillW), bands: [bandOf(ids[i], e.from, 0), bandOf(ids[i], e.to, 1)] }),
-            ...(stubs.size && e.label != null && { labelW: labelPillW(str(e.label)) }),
+            ...((stubs.size || lanes) && e.label != null && { labelW: labelPillW(str(e.label)) }),
         })), rects, tips, stubs.size
             ? placed.flatMap((p) => (!isGroup(p.item) ? [p] : p.lane ? [{ x: p.x, y: p.y, w: gutter, h: p.h }] : []))
-            : placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))), 
+            : [
+                ...placed.filter((p) => p.tl && !p.tl.labelInside).map((p) => outsideLabelRect(p, str(p.item.label))),
+                // A timeline elbow keeps clear of the bars and milestones it does not connect.
+                ...placed.filter((p) => p.tl).map((p) => ({ x: p.x, y: p.y, w: p.w, h: p.h, box: true })),
+            ], 
         // A stub pill stays in the lanes, right of the gutter.
-        stubs.size ? { x: placed[0].x + gutter, y: placed[0].y, w: placed[0].w - gutter, h: placed[0].h } : undefined);
+        stubs.size ? { x: placed[0].x + gutter, y: placed[0].y, w: placed[0].w - gutter, h: placed[0].h } : undefined, lanes ? { bands: placed.filter((p) => p.lane), boxes: placed.filter((p) => !isGroup(p.item)) } : undefined);
     };
     let routed = go();
     for (let pass = 0; plan && pass < 3; pass++) {
@@ -618,8 +622,8 @@ export function render(fig, opts = {}) {
             `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n4(t0)};${n4(t1)};1" keyPoints="${h.back ? '1;1;0;0' : '0;0;1;1'}" calcMode="linear">` +
             `<mpath href="#p-${esc(h.edge)}" xlink:href="#p-${esc(h.edge)}"/></animateMotion></g>`);
     });
-    // The timeline axis under the boxes, the fixed today marker and the moving playhead over them.
-    let axisSvg = '', todaySvg = '';
+    // The timeline axis, the fixed today marker and the moving playhead. Their lines sit behind the bars, their labels on top.
+    let axisSvg = '', lineSvg = '', todaySvg = '';
     if (tl) {
         const top = placed[0];
         const x0 = top.x + gutterOf(fig.layout.children);
@@ -635,19 +639,21 @@ export function render(fig, opts = {}) {
         // The today marker is fixed at the figure's `today`.
         if (tl.today != null) {
             const tx = x0 + tl.today;
-            todaySvg =
-                `<path d="M ${n2(tx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-opacity="0.6" stroke-width="1" stroke-dasharray="3 3"/>` +
-                    `<text x="${n2(tx - 3)}" y="${n2(top.y + 22)}" text-anchor="end" class="today">today</text>`;
+            lineSvg = `<path d="M ${n2(tx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-opacity="0.6" stroke-width="1" stroke-dasharray="3 3"/>`;
+            todaySvg = `<text x="${n2(tx - 3)}" y="${n2(top.y + 22)}" text-anchor="end" class="today">today</text>`;
         }
-        // The playhead moves to the start of each beat's item, then to the last date in the step hold.
+        // The playhead moves to the start of each beat's item, then to the last date in the step hold. The loop starts with
+        // the playhead at the first beat's item, so the first frame shows the first beat; the last hold moves it back there.
         if (tl.last != null && segs.length) {
             const home = tl.last;
             const startOf = new Map(tl.items.map((i) => [i.id, i.x + (i.milestone ? i.w / 2 : 0)]));
             const dateOf = new Map(tl.items.map((i) => [i.id, i.date]));
             const hold = STEP_HOLD_MS / 1000 / BASE_RATE;
-            const pts = [[0, home]];
+            const first = loopStartItem(tl.items, steps);
+            const start = first ? startOf.get(first.id) : home;
+            const pts = [[0, start]];
             const dates = []; // the label date in each time span
-            let at = home;
+            let at = start;
             segs.forEach((s, i) => {
                 const item = playheadItem(tl.items, beats[s.si], s.bi);
                 const to = item ? startOf.get(item.id) : home;
@@ -655,15 +661,20 @@ export function render(fig, opts = {}) {
                 const last = i === segs.length - 1 || segs[i + 1].si !== s.si;
                 const end = last ? s.t1 - hold : s.t1; // the step hold starts here
                 pts.push([s.t0, at], [Math.min(s.t0 + RAMP, end), to], [end, to]);
-                const [la, lb] = labelSpan(s.t0, end, RAMP);
+                // The label waits for the line, except at the loop start, where the line is already in place.
+                const [la, lb] = i === 0 && to === start ? [s.t0, end] : labelSpan(s.t0, end, RAMP);
                 if (la < lb)
                     dates.push({ a: la, b: lb, d: date, x: to });
                 at = to;
                 if (last) {
-                    pts.push([Math.min(end + RAMP, s.t1), home], [s.t1, home]);
-                    const [ha, hb] = labelSpan(end, s.t1, RAMP);
+                    // The last hold of the loop ends with the move back to the loop start.
+                    const back = i === segs.length - 1 ? Math.max(end + RAMP, s.t1 - RAMP) : s.t1;
+                    pts.push([Math.min(end + RAMP, s.t1), home], [back, home]);
+                    const [ha, hb] = labelSpan(end, back, RAMP);
                     if (ha < hb)
                         dates.push({ a: ha, b: hb, d: tl.lastDate, x: home });
+                    if (back < s.t1)
+                        pts.push([s.t1, start]);
                     at = home;
                 }
             });
@@ -688,7 +699,8 @@ export function render(fig, opts = {}) {
                 const raised = dateLabelRaised(dates.find((x) => x.d === d).x, tl.today, textWidth(d, 11), textWidth('today', 11));
                 return `<text x="${n2(lx + 3)}" y="${n2(top.y + (raised ? 10 : 22))}" opacity="0"${cls('today', seen.get(key))}>${esc(d)}</text>`;
             });
-            todaySvg += `<g${cls(name)}><path d="M ${n2(lx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-width="1.5"/>${labels.join('')}</g>`;
+            lineSvg += `<g${cls(name)}><path d="M ${n2(lx)} ${n2(top.y + 12)} V ${bottom}" stroke="var(--accent)" stroke-width="1.5"/></g>`;
+            todaySvg += `<g${cls(name)}>${labels.join('')}</g>`;
         }
     }
     const bounds = placed[0];
@@ -831,7 +843,7 @@ ${only
         ? ''
         : `<g transform="translate(${n2(shift)} ${arcs ? 44 : 0})">
 ${axisSvg}
-${tl ? boxes.filter((b, i) => b && isGroup(placed[i].item)).join('\n') : ''}
+${tl ? boxes.filter((b, i) => b && isGroup(placed[i].item)).join('\n') : ''}${lineSvg && `\n${lineSvg}`}
 ${tl ? edgeSvg.join('\n') : ''}
 ${boxes.filter((b, i) => b && !(tl && isGroup(placed[i].item))).join('\n')}
 ${tl ? '' : edgeSvg.join('\n')}
@@ -854,7 +866,17 @@ ${said.join('\n')}
                 // A cross-block edge is two scene edges: each stub with its pill.
                 if (r.stub)
                     return r.stub.pts.map((pts, k) => ({ id: r.id, from: e.from, to: e.to, curve: r.curve, pts, label: r.stub.pills[k] }));
-                return [{ id: r.id, from: e.from, to: e.to, curve: r.curve, label: labelRects[r.id], ...(tl && { behind: true }) }];
+                // A timeline edge is drawn behind, but `check` still tests its elbow against the boxes it does not connect.
+                return [
+                    {
+                        id: r.id,
+                        from: e.from,
+                        to: e.to,
+                        curve: r.curve,
+                        label: labelRects[r.id],
+                        ...(tl && { behind: true, elbow: r.elbow }),
+                    },
+                ];
             }),
             // Each rail payload is a label too, in its own open-phase position, so label-overlap covers the rail.
             ...(rail?.rows ?? []).flatMap((row, i) => {
@@ -878,7 +900,7 @@ ${said.join('\n')}
             }),
         ],
         minFont: Math.min(...fonts),
-        ...(stubs.size && {
+        ...(lanes && {
             lanes: placed.filter((p) => p.lane).map((p) => ({ id: str(p.item.label), rect: { x: p.x, y: p.y, w: p.w, h: p.h } })),
         }),
     };

package/dist/verify.js

@@ -1,6 +1,6 @@
 // `flowfig verify`: checks that the code a link names is still there. The link parsing lives in source.ts, which has no Node import.
 import { readFileSync, statSync } from 'node:fs';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { headingSlug, links } from './source.js';
 export { parseSource, headingSlug, owners, links } from './source.js';
 const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -28,7 +28,7 @@ export function verify(fig, { root = process.cwd() } = {}) {
     for (const l of all) {
         const full = resolve(root, l.path);
         const rel = relative(root, full);
-        const outside = isAbsolute(l.path) || rel === '..' || rel.startsWith('../');
+        const outside = isAbsolute(l.path) || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
         if (!files.has(full))
             files.set(full, outside ? null : read(full));
         const text = files.get(full);

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The package version, for the MCP `serverInfo`. The release list bumps it with package.json. */
-export const VERSION = '0.5.0';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Your coding agent draws animated diagrams from your code, and flowfig checks them. One animated SVG for a GitHub README, PR or issue, and a React player. Set up Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf and Kiro with npx flowfig init.",
   "license": "MIT",
   "repository": {