flowfig 0.2.0 → 0.3.0

package/README.md

@@ -28,6 +28,21 @@ An agent with the flowfig instructions made faithful, checked diagrams more ofte
 
 [How we measured](#how-we-measured).
 
+## 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.
+
 ## Quick start
 
 ```bash
@@ -307,6 +322,8 @@ 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.
+
 ```yaml
 permissions:
   contents: read

package/dist/check.js

@@ -1,6 +1,6 @@
 // The rules behind `flowfig check`. They never draw and never measure: a renderer gives a Scene, and these read it. So one rule set
 // covers the SVG (estimated text) and the React player (measured text), and any later view that gives a scene.
-import { DARK, LIGHT, ON_ACCENT, edgeId, isGroup, nodes, str, toBeat } from './model.js';
+import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, nodes, str, toBeat, } from './model.js';
 import { textWidth } from './text.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
@@ -128,7 +128,16 @@ const PAIRS = [
     ['muted', 'bg'],
     ['fg', 'surface'],
     ['text', 'accent'],
+    ['fg', 'tint'],
+    ['muted', 'tint'],
 ];
+/** A color mixed over a base at pct %, per channel like the CSS color-mix. The default is the active-box tint: 10 % accent over the surface. */
+function tintOf(t, color = t.accent, base = t.surface, pct = 10) {
+    const [a, s] = [rgb(color), rgb(base)];
+    if (!a || !s)
+        return base; // an unreadable color is reported by its own pairs
+    return `rgb(${a.map((v, i) => (pct / 100) * v + (1 - pct / 100) * s[i]).join(',')})`;
+}
 /** Text the reader cannot read: each text and background pair, in light, dark and any custom theme, needs 4.5:1 (WCAG AA). */
 export function checkTheme(theme = {}) {
     const out = [];
@@ -142,7 +151,8 @@ export function checkTheme(theme = {}) {
     if (custom)
         sets.push(['custom', { ...LIGHT, ...Object.fromEntries(Object.entries(theme).filter(([, v]) => v != null)) }]);
     const unread = new Set();
-    for (const [name, t] of sets)
+    for (const [name, base] of sets) {
+        const t = { ...base, tint: tintOf(base) };
         for (const [fg, bg] of PAIRS) {
             const a = fg === 'text' ? ON_ACCENT : t[fg];
             const r = contrast(a, t[bg]);
@@ -154,6 +164,17 @@ export function checkTheme(theme = {}) {
             else if (r < 4.5)
                 out.push(err('low-contrast', [], `${name} theme: ${fg} on ${bg} has contrast ${r}:1 (minimum 4.5:1)`));
         }
+        // A toned box shows fg and muted text on its tone tint: 8 % over bg (off, trail) and 10 % over surface (active).
+        for (const [tname, tone] of Object.entries(TONES)) {
+            for (const bg of [tintOf(t, tone, t.bg, 8), tintOf(t, tone, t.surface, 10)]) {
+                for (const fg of ['fg', 'muted']) {
+                    const r = contrast(t[fg], bg);
+                    if (r != null && r < 4.5)
+                        out.push(err('low-contrast', [], `${name} theme: ${fg} on the ${tname} box tint has contrast ${r}:1 (minimum 4.5:1)`));
+                }
+            }
+        }
+    }
     for (const c of unread)
         out.push(warn('color-not-checked', [], `cannot read the color "${c}", so its contrast is not checked`));
     return out;

package/dist/cli.js

@@ -20,6 +20,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   flowfig docs                         # print the full guide (Markdown)
  *   flowfig mcp                          # serve check, render, verify, diff and docs over MCP (stdio)
  *   flowfig init [dir]                   # write flowfig instructions for the coding agents of a repo
+ *   flowfig draw "<question>" [--out out.svg]   # ask Claude Code for a figure, then check it
  *
  * A render checks first and writes nothing on an error (--no-check skips that). --strict makes warnings errors; --width and
  * --min-text set the page width and the smallest text the reader should get.
@@ -30,6 +31,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { GUIDE } from './guide.js';
+import { runDraw } from './draw.js';
 import { runInit } from './init.js';
 import { serve } from './mcp.js';
 import { diff, formatDiff } from './diff.js';
@@ -44,6 +46,7 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg]   render a figur
        flowfig docs                                       print the guide (Markdown)
        flowfig mcp                                        serve check, render, verify, diff and docs over MCP (stdio)
        flowfig init [dir] [--agents <ids>] [-y] [--global] [--dry-run] [--no-mcp]   write flowfig instructions for the coding agents of a repo
+       flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json]   ask Claude Code for a figure, then check it
 flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only)`;
 /** Bad use, not a bad figure: exit 2 with a message, not a stack trace. A declaration, so TypeScript narrows after a call. */
 function usage(message) {
@@ -81,6 +84,8 @@ if (args[0] === 'mcp') {
 }
 if (args[0] === 'init')
     process.exit(await runInit(args.slice(1)));
+if (args[0] === 'draw')
+    process.exit(await runDraw(args.slice(1)));
 if (args[0] === '--spec') {
     if (!args[1])
         usage('--spec needs the path of an SVG');

package/dist/diff.js

@@ -23,7 +23,7 @@ function compare(kind, before, after, fieldsOf) {
     return out;
 }
 const messages = (fig) => new Map((fig.steps ?? [])
-    .flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}`)))
+    .flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}${h.tone ? ` [${h.tone}]` : ''}`)))
     .map((id) => [id, id]));
 export function diff(before, after) {
     const boxes = (f) => {
@@ -36,7 +36,7 @@ export function diff(before, after) {
     const edges = (f) => new Map(f.edges.map((e) => [edgeId(e), e]));
     const steps = (f) => new Map((f.steps ?? []).map((s) => [str(s.label), s]));
     const out = [
-        ...compare('box', boxes(before), boxes(after), (a, b) => fields(a, b, ['label', 'sub', 'shape', 'source', 'group'])),
+        ...compare('box', boxes(before), boxes(after), (a, b) => fields(a, b, ['label', 'sub', 'shape', 'tone', 'source', 'group'])),
         ...compare('edge', edges(before), edges(after), (a, b) => fields(a, b, ['from', 'to', 'label', 'source'])),
         ...compare('step', steps(before), steps(after), () => []),
         ...compare('message', messages(before), messages(after), () => []),

package/dist/draw.d.ts

@@ -0,0 +1,12 @@
+/** A file name from the question: lower case, letters and digits, joined by -, at most 60 characters. */
+export declare function slug(question: string): string;
+/** The claude argv after the binary. The system prompt carries the agent text, the output path and the folder rule. */
+export declare function agentArgs(o: {
+    question: string;
+    out: string;
+    cwd: string;
+    maxTurns: number;
+    model?: string;
+}): string[];
+/** Run `flowfig draw`. Prints, and returns the exit code. */
+export declare function runDraw(argv: string[]): Promise<number>;

package/dist/draw.js

@@ -0,0 +1,178 @@
+// `flowfig draw`: one command to the first figure. Claude Code reads the repo and renders; draw checks the result itself.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { AGENT_TEXT } from './guide.js';
+import { loadSpec, reportLines, sortFindings } from './load.js';
+import { check } from './svg.js';
+import { verify } from './verify.js';
+const ALLOWED = 'Read,Glob,Grep,Bash(npx flowfig *)';
+const DISALLOWED = 'Edit,MultiEdit,NotebookEdit';
+const USAGE = 'usage: flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json]';
+/** A file name from the question: lower case, letters and digits, joined by -, at most 60 characters. */
+export function slug(question) {
+    const s = question
+        .toLowerCase()
+        .match(/[a-z0-9]+/g)
+        ?.join('-')
+        .slice(0, 60)
+        .replace(/-$/, '');
+    return s || 'figure';
+}
+const specPath = (out) => out.replace(/\.svg$/, '.json');
+/** The claude argv after the binary. The system prompt carries the agent text, the output path and the folder rule. */
+export function agentArgs(o) {
+    const spec = specPath(o.out);
+    const system = `${AGENT_TEXT.trimEnd()}\n\nWrite the spec to ${spec} with the Write tool. Then run exactly \`npx flowfig ${spec} ${o.out}\` as one command, alone on its line: no heredoc, no \`;\`, no \`&&\`, no pipe (the permission rule matches one plain command only). Then run \`npx flowfig verify ${o.out}\` the same way. Run every command from this folder, ${o.cwd}.`;
+    const args = [
+        '-p',
+        o.question,
+        '--output-format',
+        'json',
+        '--max-turns',
+        String(o.maxTurns),
+        '--permission-mode',
+        'acceptEdits',
+        '--allowedTools',
+        ALLOWED,
+        '--disallowedTools',
+        DISALLOWED,
+        '--append-system-prompt',
+        system,
+    ];
+    if (o.model)
+        args.push('--model', o.model);
+    return args;
+}
+class Bad extends Error {
+}
+const fail = (message, code) => {
+    console.error(message);
+    return code;
+};
+/** Run `flowfig draw`. Prints, and returns the exit code. */
+export async function runDraw(argv) {
+    const args = [...argv];
+    const flag = (n) => args.includes(n) && args.splice(args.indexOf(n), 1).length > 0;
+    const value = (n) => {
+        const i = args.indexOf(n);
+        if (i === -1)
+            return undefined;
+        const v = args.splice(i, 2)[1];
+        if (v === undefined)
+            throw new Bad(`${n} needs a value`);
+        return v;
+    };
+    let json, outArg, model, turns;
+    try {
+        json = flag('--json');
+        outArg = value('--out');
+        model = value('--model');
+        turns = value('--max-turns');
+    }
+    catch (e) {
+        if (e instanceof Bad)
+            return fail(`draw: ${e.message}\n${USAGE}`, 2);
+        throw e;
+    }
+    const maxTurns = turns === undefined ? 40 : Number(turns);
+    if (!Number.isInteger(maxTurns) || maxTurns < 1)
+        return fail(`draw: --max-turns needs a positive whole number\n${USAGE}`, 2);
+    const bad = args.find((a) => a.startsWith('-'));
+    if (bad)
+        return fail(`draw: unknown flag ${bad}\n${USAGE}`, 2);
+    const question = args.join(' ').trim();
+    if (!question)
+        return fail(`draw needs a question\n${USAGE}`, 2);
+    if (process.platform === 'win32')
+        return fail('draw does not run on Windows yet', 2);
+    const bin = process.env.FLOWFIG_CLAUDE_BIN || 'claude';
+    const version = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+    if (version.error || version.status !== 0)
+        return fail('draw needs Claude Code: npm i -g @anthropic-ai/claude-code', 2);
+    const cwd = process.cwd();
+    const out = outArg ?? `${slug(question)}.svg`;
+    if (!out.endsWith('.svg'))
+        return fail(`draw: --out needs a .svg path\n${USAGE}`, 2);
+    const full = resolve(cwd, out);
+    try {
+        mkdirSync(dirname(full), { recursive: true });
+    }
+    catch (e) {
+        return fail(`draw: ${e.message}`, 2);
+    }
+    // A figure from an earlier run must not pass as this run's work: compare the mtime.
+    const mtime = () => (existsSync(full) ? statSync(full).mtimeMs : undefined);
+    const before = mtime();
+    const run = spawnSync(bin, agentArgs({ question, out, cwd, maxTurns, model }), {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'inherit'],
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    // The JSON is the last line that starts with {: a warning line may come before it.
+    const line = (run.stdout ?? '')
+        .split('\n')
+        .reverse()
+        .find((l) => l.startsWith('{'));
+    let reply = '', cost = null, session = null, stopped, denials = [];
+    try {
+        const parsed = JSON.parse(line ?? '');
+        reply = String(parsed.result ?? '');
+        cost = typeof parsed.total_cost_usd === 'number' ? parsed.total_cost_usd : null;
+        session = typeof parsed.session_id === 'string' ? parsed.session_id : null;
+        if (parsed.is_error === true)
+            stopped = String(parsed.subtype ?? '?');
+        if (Array.isArray(parsed.permission_denials))
+            denials = parsed.permission_denials;
+    }
+    catch {
+        process.stderr.write(run.stdout ?? '');
+        const message = `claude failed (exit ${run.status ?? 'null'})`;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        return fail(`draw: ${message}`, 1);
+    }
+    const stop = () => {
+        if (stopped !== undefined)
+            console.error(`draw: claude stopped (${stopped})`);
+    };
+    const after = mtime();
+    if (after === undefined || after === before) {
+        const message = `the agent wrote no figure at ${out}`;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        else
+            console.log(reply);
+        for (const d of denials)
+            console.error(`denied: ${d.tool_name ?? '?'} ${d.tool_input?.command ?? d.tool_input?.file_path ?? ''}`.trimEnd());
+        stop();
+        return fail(`draw: ${message}`, 1);
+    }
+    let props;
+    try {
+        props = loadSpec(full);
+    }
+    catch (e) {
+        stop();
+        const message = e.message;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        return fail(`draw: ${message}`, 1);
+    }
+    const findings = sortFindings([...check(props), ...verify(props, { root: cwd })], true);
+    const errors = findings.length > 0;
+    if (!errors && stopped === undefined)
+        rmSync(specPath(full), { force: true });
+    if (json)
+        console.log(JSON.stringify({ out, reply, cost, session, findings }, null, 2));
+    else {
+        for (const l of reportLines(props, findings))
+            console.log(l);
+        console.log('');
+        console.log(reply);
+        console.log(`agent: claude, $${cost === null ? '?' : cost.toFixed(4)}, session ${session ?? '?'}`);
+    }
+    stop();
+    return errors || stopped !== undefined ? 1 : 0;
+}

package/dist/guide.d.ts

@@ -1,6 +1,6 @@
 /** 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`.\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 each end state, for example with `sub: \"end state\"`. |\n| A flowchart with branches                  | `shape: \"decision\"` for each branch. One step per path.                                     |\n\nflowfig does not draw class or ER diagrams (fields, types, cardinality), Gantt charts, timelines with dates, charts of numbers,\nor mind maps. If the user asks for one of these, say that flowfig does not draw it, suggest Mermaid (`classDiagram`,\n`erDiagram`, `gantt`), 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\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.\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.\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| `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| `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\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?, 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- `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` 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 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 each end state, for example with `sub: \"end state\"`. |\n| A flowchart with branches                  | `shape: \"decision\"` for each branch. One step per path.                                     |\n\nflowfig does not draw class or ER diagrams (fields, types, cardinality), Gantt charts, timelines with dates, charts of numbers,\nor mind maps. If the user asks for one of these, say that flowfig does not draw it, suggest Mermaid (`classDiagram`,\n`erDiagram`, `gantt`), 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\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.\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| `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| `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\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 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\nUse flowfig when the user wants a diagram of how something works: 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 does not draw class or ER diagrams, Gantt charts or charts of numbers. For those, tell the user so, suggest Mermaid\n(`classDiagram`, `erDiagram`, `gantt`), and 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.\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.\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";
+export declare const AGENT_TEXT = "# Diagrams with flowfig\n\nUse flowfig when the user wants a diagram of how something works: 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 does not draw class or ER diagrams, Gantt charts or charts of numbers. For those, tell the user so, suggest Mermaid\n(`classDiagram`, `erDiagram`, `gantt`), and 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.\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";
 /** The description of the Claude skill: the words that make the agent load it. */
 export declare const SKILL_DESCRIPTION = "Use when the user asks for a diagram, figure or animation of how code or a system works: an architecture, a data flow, a pipeline, a request lifecycle, a call sequence, a state lifecycle or a flowchart; when the user pastes a Mermaid flowchart, stateDiagram or sequenceDiagram to convert; or when the user asks for a class, ER or Gantt diagram.";

package/dist/guide.js

@@ -18,7 +18,7 @@ A spec has three forms.
 
 Use the rail for a sequence of messages: a request lifecycle, an API call chain, or a Mermaid \`sequenceDiagram\`. Put each message on
 an 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
-answer with \`"async": true\`.
+answer with \`"async": true\`: every send to a queue or a topic, every emitted event, and every call the caller does not await.
 
 ## Scope: what flowfig draws and what it does not
 
@@ -64,6 +64,7 @@ If the code does not show a fact, leave the fact out. Do not guess a part, a nam
 Each 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
 real example data from the code or its tests. Keep each fact that you leave out, with the reason, for the reply.
 Give 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.
+A 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.
 
 Mermaid mapping:
 
@@ -159,6 +160,7 @@ Every other item is a box.
 | \`width\`   | Width in px. This overrides the width that the layout picks.                                              |
 | \`source\`  | The code this draws: \`path\` or \`path#symbol\`, relative to the repo root. \`flowfig verify\` checks it.  |
 | \`lines\`   | The least number of text lines that a content card keeps. The card still grows to fit its content.        |
+| \`tone\`    | The state color of the box: a 1 px border and a light tint. Use \`blue\`, \`purple\`, \`green\`, \`orange\`, \`red\` or \`gray\`.                  |
 
 ### edges
 
@@ -184,10 +186,14 @@ boxes to highlight for the whole step).
 
 The beat fields:
 
-- \`edges\`: an edge id, a hop object, or an array of these. A hop object is \`{ edge, back?, data?, async?, source? }\`.
+- \`edges\`: an edge id, a hop object, or an array of these. A hop object is \`{ edge, back?, data?, tone?, async?, source? }\`.
   - \`back: true\` runs the packet from the \`to\` box to the \`from\` box.
   - \`data\` is a small card that moves with the packet.
   - \`async: true\` marks a message that does not wait for an answer. The rail draws it dashed, with an \`async\` tag.
+  - \`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.
+    - \`green\`: a success or a cache hit. \`orange\`: a warning, a miss or a retry. \`red\`: an error or a rejected input.
+    - \`gray\`: idle or skipped. \`purple\`: async or background. \`blue\`: the default row color.
+    - If the hop has no \`tone\`, the arrival box uses its box \`tone\`, then the accent. A hop \`tone\` wins over a box \`tone\`.
 - \`say\`: the caption for the beat.
 - \`show\`: \`{ boxId: [row, ...] }\`. This fills the content card of each named box. The card keeps the rows until the step ends.
 - \`light\`: ids of boxes to highlight for this beat.
@@ -196,7 +202,7 @@ The beat fields:
 A row of a content card is \`{ tag?, tone?, text, meta?, mark?, mono? }\`.
 
 - \`tag\`: a short colored label at the start of the line.
-- \`tone\`: the color of the tag: \`blue\` (default), \`purple\`, \`green\`, \`orange\` or \`gray\`.
+- \`tone\`: the color of the tag: \`blue\` (default), \`purple\`, \`green\`, \`orange\`, \`red\` or \`gray\`.
 - \`text\`: the main text.
 - \`meta\`: muted text after the main text.
 - \`mark\`: a mark at the right end of the line, such as a check or "new".
@@ -284,6 +290,7 @@ flowfig does not draw class or ER diagrams, Gantt charts or charts of numbers. F
    JSON in the heredoc. Fix every fault by changing the layout first (rows, \`around\`, the gap). Never remove a fact to pass
    the check; if you must remove one, name it in the reply. If \`small-text\` appears, use two rows or split the figure; keep
    the real names; do not change \`--width\`. Give each box and edge that draws code a \`source\` (\`file#symbol\`) from the fact list.
+   Mark every send to a queue or a topic, every emitted event, and every call the caller does not await with \`async: true\`.
 5. 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
    fact names. Fix each gap. Then run \`npx flowfig verify out.svg\` from the repo root and fix each fault.
 6. 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.

package/dist/index.js

@@ -4,12 +4,15 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 import { route } from './geometry.js';
 import { foldedLabel, groupBox, layoutRail, railState, RAIL } from './rail.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, decisions, edgeId, groupGap, isGroup, isRows, nodes, toBeat, } 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, nodes, toBeat, beatMs, STEP_HOLD_MS, } from './model.js';
 export { LIGHT, DARK } from './model.js';
 const DEFAULTS = { ...LIGHT, font: 'inherit' };
 const v = (k) => `var(--fig-${k}, ${DEFAULTS[k]})`;
 const MONO = 'var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular, Menlo, monospace)';
-const glow = `0 0 0 3px color-mix(in srgb, ${v('accent')} 18%, transparent)`;
+const ACTIVE = 'flowfig-active'; // the box a packet has just reached
+// The active box reads --ff-hop (the tone of the hop that arrived), then --ff-box (the tone of the box), then the accent.
+const hue = `var(--ff-hop, var(--ff-box, ${v('accent')}))`;
+const glow = `0 0 0 3px color-mix(in srgb, ${hue} 18%, transparent)`;
 const cardBody = (c) => {
     if (c == null)
         return '—';
@@ -228,12 +231,12 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
     }, [check, routed, layout, edges, steps, ids, theme, rail, noMap]);
     // Play the step's beats: each moves its packets (and their data cards) along its edges, then the next step starts.
     useEffect(() => {
-        const gs = dots.current, cs = chips.current;
+        const gs = dots.current, cs = chips.current, edgeOf = Object.fromEntries(edges.map((e, i) => [ids[i], e]));
         if (clock.current.beats !== beats) {
             // A rail click can open another step at a later beat; start the clock at that beat, not at 0.
             const j = jump.current ?? 0;
             jump.current = null;
-            clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + (b.ms ?? speed), 0) };
+            clock.current = { beats, elapsed: beats.slice(0, j).reduce((t, b) => t + beatMs(b, speed), 0) };
             setBeat(j);
         }
         if (!beats.length || (!noMap && !routed.length))
@@ -243,8 +246,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                 bar.current.style.transform = 'none';
             return void setBeat(beats.length - 1);
         }
-        const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + (b.ms ?? speed)], []);
-        const total = ends.at(-1) + speed * 1.5; // hold on the last beat before moving on
+        const ends = beats.reduce((acc, b) => [...acc, (acc.at(-1) ?? 0) + beatMs(b, speed)], []);
+        const total = ends.at(-1) + STEP_HOLD_MS; // The figure holds on the last beat before the next step.
         let raf = 0, last = performance.now(), shownBeat = -1;
         const tick = (now) => {
             if (playingRef.current)
@@ -263,7 +266,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
             if (i !== shownBeat)
                 setBeat((shownBeat = i));
             const start = i ? ends[i - 1] : 0;
-            const f = Math.min(1, (t - start) / ((beats[i].ms ?? speed) * 0.8)); // arrive a little early, rest at the end
+            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;
             const hops = t < ends.at(-1) ? beats[i].hops : [];
             gs.forEach((g, j) => {
@@ -277,20 +280,51 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     return;
                 }
                 const pt = p.getPointAtLength((hops[j].back ? 1 - eased : eased) * p.getTotalLength());
+                const tone = hops[j].tone && TONES[hops[j].tone];
                 if (g) {
                     g.setAttribute('transform', `translate(${pt.x} ${pt.y})`);
                     g.style.opacity = '1';
+                    g.style.color = tone ?? v('accent');
                 }
                 if (c) {
+                    c.style.background = tone ? toneFill(tone) : v('accent');
                     c.style.transform = `translate(${pt.x}px, ${pt.y}px) translate(-50%, calc(-100% - 12px))`;
                     c.style.opacity = hops[j].data == null ? '0' : '1';
                 }
             });
+            // A box is active from the packet arrival to the end of the step hold. The tick toggles the class and skips React.
+            const arrived = new Map();
+            if (f >= 1)
+                for (const h of beats[i].hops) {
+                    const to = h.back ? edgeOf[h.edge]?.from : edgeOf[h.edge]?.to;
+                    arrived.set(to, arrived.get(to) ?? (h.tone && TONES[h.tone]));
+                }
+            root.current?.querySelectorAll('[data-fig]').forEach((n) => {
+                const on = arrived.has(n.dataset.fig ?? '');
+                if (on) {
+                    const tone = arrived.get(n.dataset.fig);
+                    if (tone)
+                        n.style.setProperty('--ff-hop', tone);
+                    else
+                        n.style.removeProperty('--ff-hop');
+                }
+                if (on === n.classList.contains(ACTIVE))
+                    return;
+                if (!on)
+                    return void n.classList.remove(ACTIVE); // the transition fades the box
+                // The box turns active at once: no transition while the class arrives.
+                const keep = n.style.transition;
+                n.style.transition = 'none';
+                n.classList.add(ACTIVE);
+                void n.offsetWidth;
+                n.style.transition = keep;
+            });
             raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
         return () => {
             cancelAnimationFrame(raf);
+            root.current?.querySelectorAll(`.${ACTIVE}`).forEach((n) => n.classList.remove(ACTIVE));
             gs.forEach((g) => g && (g.style.opacity = '0'));
             cs.forEach((c) => c && (c.style.opacity = '0'));
         };
@@ -309,10 +343,15 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         if (litEdges.has(ids[i]))
             litNodes.add(e.from).add(e.to);
     });
+    // A toned hop colors its edge for its own beat only; the trail after it is the accent.
+    const hopTone = (edge) => {
+        const t = cur?.hops.find((h) => h.edge === edge && h.tone)?.tone;
+        return t && TONES[t];
+    };
     const goTo = (step, b) => {
         setPlaying(true);
         if (step === active) {
-            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + (x.ms ?? speed), 0);
+            clock.current.elapsed = beats.slice(0, b).reduce((t, x) => t + beatMs(x, speed), 0);
             setBeat(b);
         }
         else {
@@ -360,7 +399,8 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
         const diamond = item.shape === 'decision';
         const store = item.shape === 'store';
         const card = carded.has(item.id);
-        return (_jsxs("div", { "data-fig": item.id, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
+        const bt = item.tone && TONES[item.tone];
+        return (_jsxs("div", { "data-fig": item.id, "data-diamond": diamond || undefined, onMouseEnter: () => setHover(item.id), onMouseLeave: () => setHover(null), style: {
                 position: 'relative',
                 isolation: 'isolate',
                 minWidth: 100,
@@ -371,17 +411,20 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                 display: 'flex',
                 flexDirection: 'column',
                 justifyContent: 'center',
-                padding: diamond ? '22px 34px' : `${store ? 24 : 10}px ${card ? 10 : 16}px 10px`,
+                padding: diamond
+                    ? '22px 34px'
+                    : `calc(${store ? 24 : 10}px - var(--ff-b, 0px)) calc(${card ? 10 : 16}px - var(--ff-b, 0px)) calc(10px - var(--ff-b, 0px))`,
                 textAlign: 'center',
-                background: diamond ? undefined : v('bg'),
+                background: diamond ? undefined : bt ? toneTint(bt, v('bg')) : v('bg'),
                 color: v('fg'),
-                border: diamond ? undefined : `1px solid ${lit ? v('accent') : v('border')}`,
-                boxShadow: diamond ? undefined : lit ? glow : '0 1px 2px rgba(0,0,0,.06)',
+                border: diamond ? undefined : `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
+                ...(bt && { '--ff-box': bt }),
+                boxShadow: diamond ? undefined : '0 1px 2px rgba(0,0,0,.06)',
                 opacity: focus && !lit ? 0.7 : 1,
                 borderRadius: store ? '50% / 12px' : 10,
                 fontSize: 14,
                 fontWeight: 500,
-                transition: 'border-color .25s, box-shadow .25s, opacity .25s',
+                transition: 'border-color .4s, background .4s, box-shadow .4s, border-width .4s, padding .4s, opacity .25s',
                 cursor: 'default',
             }, children: [diamond && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", style: {
                         position: 'absolute',
@@ -390,7 +433,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: '100%',
                         overflow: 'visible',
                         zIndex: -1,
-                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: v('bg'), stroke: lit ? v('accent') : v('border'), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .25s' } }) })), store && (_jsx("div", { style: {
+                    }, children: _jsx("polygon", { points: "50,0 100,50 50,100 0,50", fill: bt ? toneTint(bt, v('bg')) : v('bg'), stroke: bt ?? (lit ? v('accent') : v('border')), strokeWidth: lit ? 1.6 : 1, vectorEffect: "non-scaling-stroke", style: { transition: 'stroke .4s, fill .4s, stroke-width .4s' } }) })), store && (_jsx("div", { style: {
                         position: 'absolute',
                         top: -1,
                         left: -1,
@@ -398,7 +441,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                         height: 24,
                         boxSizing: 'border-box',
                         borderRadius: '50%',
-                        border: `1px solid ${lit ? v('accent') : v('border')}`,
+                        border: `1px solid ${bt ?? (lit ? v('accent') : v('border'))}`,
                         transition: 'border-color .25s',
                     } })), _jsx("div", { children: item.label }), item.sub != null && _jsx("div", { style: { fontSize: 12, fontWeight: 400, color: v('muted'), marginTop: 2 }, children: item.sub }), card && (_jsxs("div", { style: {
                         marginTop: 8,
@@ -452,7 +495,10 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                     zIndex: 3,
                     width: 28,
                     height: 28,
-                }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@keyframes flowfig-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
+                }, children: _jsx(Icon, { d: full ? 'M4 4l8 8M12 4l-8 8' : 'M9 3h4v4M7 13H3V9M13 3L9 7M3 13l4-4' }) }), _jsx("style", { children: '@keyframes flowfig-in{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}' +
+                    // The active box has a 2 px border, a tint and a glow. The padding shrinks by 1 px. The box size stays the same, so the edges keep their route.
+                    `.${ACTIVE}:not([data-diamond]){--ff-b:1px;border-width:2px!important;background:color-mix(in srgb, ${hue} 10%, ${v('surface')})!important;box-shadow:${glow}!important;border-color:${hue}!important}` +
+                    `.${ACTIVE} polygon{fill:color-mix(in srgb, ${hue} 10%, ${v('surface')});stroke:${hue};stroke-width:2px}` }), !noMap && (_jsx(_Fragment, { children: _jsx("div", { style: {
                         margin: full ? '-48px -24px 0' : '-20px -16px 0',
                         padding: full ? '48px 24px 24px' : '24px 16px',
                         borderRadius: full ? 0 : '16px 16px 0 0',
@@ -479,15 +525,16 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                         height: '100%',
                                         overflow: 'visible',
                                         pointerEvents: 'none',
-                                    }, children: [_jsx("defs", { children: ['off', 'on'].map((k) => (_jsx("marker", { id: `fig-arrow-${k}`, viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: k === 'on' ? v('accent') : v('muted') }) }, k))) }), routed.map((r) => {
+                                    }, children: [_jsx("defs", { children: ['off', 'on'].map((k) => (_jsx("marker", { id: `fig-arrow-${k}`, viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: "context-stroke" }) }, k))) }), routed.map((r) => {
                                             const on = litEdges.has(r.id);
+                                            const tone = hopTone(r.id);
                                             const hidden = !on && edges[ids.indexOf(r.id)].quiet;
                                             return (_jsx("path", { ref: (p) => {
                                                     paths.current[r.id] = p;
-                                                }, d: r.d, fill: "none", stroke: on ? v('accent') : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s' } }, r.id));
+                                                }, d: r.d, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeOpacity: hidden ? 0 : focus && !on ? 0.35 : 1, markerEnd: hidden ? undefined : `url(#fig-arrow-${on ? 'on' : 'off'})`, style: { transition: 'stroke .25s, stroke-opacity .25s' } }, r.id));
                                         }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsxs("g", { ref: (g) => {
                                                 dots.current[j] = g;
-                                            }, style: { opacity: 0 }, children: [_jsx("circle", { r: 10, fill: v('accent'), opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: v('accent') })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
+                                            }, style: { opacity: 0, color: v('accent') }, children: [_jsx("circle", { r: 10, fill: "currentColor", opacity: 0.2 }), _jsx("circle", { r: 4.5, fill: "currentColor" })] }, j)))] }), Array.from({ length: Math.max(1, ...beats.map((b) => b.hops.length)) }, (_, j) => (_jsx("div", { ref: (c) => {
                                         chips.current[j] = c;
                                     }, style: {
                                         position: 'absolute',
@@ -511,6 +558,7 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                     if (e.label == null)
                                         return null;
                                     const on = litEdges.has(r.id);
+                                    const tone = hopTone(r.id);
                                     return (_jsx("div", { "data-fig-label": r.id, style: {
                                             position: 'absolute',
                                             left: r.mid.x,
@@ -522,9 +570,9 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                             borderRadius: 999,
                                             whiteSpace: 'nowrap',
                                             pointerEvents: 'none',
-                                            background: on ? v('accent') : v('bg'),
+                                            background: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'),
                                             color: on ? ON_ACCENT : v('muted'),
-                                            border: `1px solid ${on ? v('accent') : v('border')}`,
+                                            border: `1px solid ${on ? (tone ?? v('accent')) : v('border')}`,
                                             opacity: !on && e.quiet ? 0 : focus && !on ? 0.6 : 1,
                                             fontFamily: MONO,
                                             transition: 'background .25s, color .25s, opacity .25s',
@@ -565,14 +613,15 @@ export function Flow({ layout, edges, steps = [], theme, speed = 900, autoplay =
                                 (hover != null && [rail.columns[row.from].id, rail.columns[row.to].id].includes(hover));
                             const [x1, x2] = [rail.columns[row.from].x, rail.columns[row.to].x];
                             const ly = y + RAIL.row / 2;
+                            const tone = state === 'now' && row.tone ? TONES[row.tone] : undefined;
                             const g = row.group != null ? rail.groups[row.group] : null;
-                            return (_jsxs("g", { "data-rail-row": row.n, "data-state": state, opacity: state === 'next' && !on ? 0.45 : 1, style: { cursor: 'pointer' }, onClick: () => goTo(row.step, row.beat), onMouseEnter: () => setHoverEdge(row.edge), onMouseLeave: () => setHoverEdge(null), children: [g && g.rows[0] === i && (_jsx("rect", { x: groupBox(rail, g).x, y: y + groupBox(rail, g).y, width: groupBox(rail, g).w, height: groupBox(rail, g).h, rx: 6, fill: `color-mix(in srgb, ${v('accent')} 8%, ${v('bg')})`, stroke: v('accent'), strokeDasharray: "3 3" })), _jsx("path", { d: `M ${x1} ${ly} H ${x2}`, fill: "none", stroke: on ? v('accent') : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
+                            return (_jsxs("g", { "data-rail-row": row.n, "data-state": state, opacity: state === 'next' && !on ? 0.45 : 1, style: { cursor: 'pointer' }, onClick: () => goTo(row.step, row.beat), onMouseEnter: () => setHoverEdge(row.edge), onMouseLeave: () => setHoverEdge(null), children: [g && g.rows[0] === i && (_jsx("rect", { x: groupBox(rail, g).x, y: y + groupBox(rail, g).y, width: groupBox(rail, g).w, height: groupBox(rail, g).h, rx: 6, fill: `color-mix(in srgb, ${v('accent')} 8%, ${v('bg')})`, stroke: v('accent'), strokeDasharray: "3 3" })), _jsx("path", { d: `M ${x1} ${ly} H ${x2}`, fill: "none", stroke: on ? (tone ?? v('accent')) : v('muted'), strokeWidth: on ? EDGE_ON : EDGE_OFF, strokeDasharray: row.async ? '4 3' : undefined, markerEnd: "url(#flowfig-rail-arrow)" }), row.async &&
                                         (() => {
                                             const tagW = ASYNC_TAG_W;
                                             // The tag sits on the tail side of the pill, so it never hides the arrowhead.
                                             const tx = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;
                                             return (_jsxs(_Fragment, { children: [_jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: v('bg') }), _jsx("rect", { x: tx, y: ly - 6, width: tagW, height: 12, rx: 4, fill: TONES.gray, fillOpacity: 0.15 }), _jsx("text", { x: tx + tagW / 2, y: ly + 3, fill: TONES.gray, fontSize: 9, fontWeight: 600, letterSpacing: ".03em", textAnchor: "middle", "data-fig-tag": true, children: "ASYNC" })] }));
-                                        })(), row.pill && (_jsxs("g", { "data-fig-label": `rail:${row.n}`, children: [_jsx("rect", { x: row.pill.x, y: ly - 9, width: row.pill.w, height: 18, rx: 9, fill: on ? v('accent') : v('bg'), stroke: on ? v('accent') : v('border') }), _jsx("text", { x: row.pill.x + row.pill.w / 2, y: ly + 4, fill: on ? ON_ACCENT : v('muted'), fontSize: 11, fontFamily: MONO, textAnchor: "middle", children: row.text })] }))] }, `m${i}`));
+                                        })(), row.pill && (_jsxs("g", { "data-fig-label": `rail:${row.n}`, children: [_jsx("rect", { x: row.pill.x, y: ly - 9, width: row.pill.w, height: 18, rx: 9, fill: on ? (tone ? toneFill(tone) : v('accent')) : v('bg'), stroke: on ? (tone ?? v('accent')) : v('border') }), _jsx("text", { x: row.pill.x + row.pill.w / 2, y: ly + 4, fill: on ? ON_ACCENT : v('muted'), fontSize: 11, fontFamily: MONO, textAnchor: "middle", children: row.text })] }))] }, `m${i}`));
                         });
                     })(), _jsx("defs", { children: _jsx("marker", { id: "flowfig-rail-arrow", viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 1 L 9 5 L 0 9 z", fill: v('muted') }) }) })] })), steps.length > 0 && (_jsxs("figcaption", { style: { marginTop: 14, textAlign: 'center' }, children: [_jsxs("div", { style: { display: 'flex', gap: 10, justifyContent: 'center', alignItems: 'center' }, children: [_jsx("button", { type: "button", "aria-label": playing ? 'Pause' : 'Play', title: playing ? 'Pause' : 'Play', style: iconBtn, onClick: () => setPlaying((p) => !p), children: _jsx(Icon, { d: playing ? 'M5.5 4v8M10.5 4v8' : 'M5 3.5v9l7.5-4.5z', fill: !playing }) }), _jsx("div", { role: "tablist", style: {
                                     display: 'inline-flex',

package/dist/model.d.ts

@@ -13,6 +13,8 @@ export type FigNode = {
     lines?: number;
     /** Width in px. Overrides the width the layout picks. */
     width?: number;
+    /** A permanent state color for the box, such as a failing part. It gives a 1 px border and a light tint. An arrival with no hop tone uses it too. */
+    tone?: FigTone;
     /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
     source?: string;
 };
@@ -56,6 +58,8 @@ export type FigHop = string | {
     back?: boolean;
     /** A small card that rides along with the packet. */
     data?: ReactNode;
+    /** Colors the packet, its data card, the edge and the box it arrives at, for this beat. The trail after the beat stays the accent. Default: the accent. */
+    tone?: FigTone;
     /** Marks a message that does not wait for an answer. The rail draws it dashed, with an `async` tag. Default: `false`. */
     async?: boolean;
     /** The code this draws, `path` or `path#symbol`, relative to the repo root. `flowfig verify` checks it. */
@@ -71,7 +75,7 @@ export type FigBeat = {
     show?: Record<string, FigContent>;
     /** Ids of boxes to highlight for this beat, without a packet or a content card. */
     light?: string[];
-    /** How long the beat lasts in ms. Default: the time one packet needs to cross an edge (`speed`). */
+    /** How long the beat lasts in ms. The packet crosses in `speed`; the rest is a hold. An explicit `ms` wins as written. Default: `speed` plus the time to read `say`. */
     ms?: number;
 };
 /** One line of a content card. */
@@ -89,8 +93,8 @@ export type FigRow = {
     /** Draws the text in a monospace font. Default: `false`. */
     mono?: boolean;
 };
-/** The color of a row tag. Each tone is a fixed color. */
-export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'gray';
+/** The color of a row tag, a hop or a box. Each tone is a fixed color. */
+export type FigTone = 'blue' | 'purple' | 'green' | 'orange' | 'red' | 'gray';
 /** What a content card shows: rows, or anything React can render. */
 export type FigContent = FigRow[] | ReactNode;
 /** One story the figure can tell. The player shows one tab for each step. */
@@ -137,6 +141,7 @@ export type Beat = Omit<FigBeat, 'edges'> & {
         edge: string;
         back: boolean;
         data?: ReactNode;
+        tone?: FigTone;
         async?: boolean;
         source?: string;
     }[];
@@ -155,6 +160,10 @@ export declare const BASE_RATE = 1.25;
 export declare const CARD_LINE = 15, CARD_PAD = 6;
 /** The fixed color of each row tone. */
 export declare const TONES: Record<FigTone, string>;
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export declare const toneFill: (c: string) => string;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export declare const toneTint: (c: string, bg: string, pct?: number) => string;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export declare const labelPillW: (label: string) => number;
 /** The width of the `async` tag in px. */
@@ -182,6 +191,12 @@ export declare const DARK: {
 export declare const ON_ACCENT = "#ffffff";
 /** Only text survives outside React: a React element has no string form. */
 export declare const str: (n: unknown) => string;
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export declare const readMs: (say: unknown) => number;
+/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
+export declare const beatMs: (b: Beat, speed: number) => number;
+/** The hold at the end of each step, before the next step starts. */
+export declare const STEP_HOLD_MS = 2000;
 export declare const nodes: (g: FigGroup) => FigNode[];
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */
 export declare const counts: (p: FlowProps) => {

package/dist/model.js

@@ -25,8 +25,13 @@ export const TONES = {
     purple: '#8b5cf6',
     green: '#10b981',
     orange: '#f59e0b',
+    red: '#ef4444',
     gray: '#8b949e',
 };
+/** A tone as a fill under white text: darker, so the text keeps its contrast. */
+export const toneFill = (c) => `color-mix(in srgb, ${c} 64%, #000)`;
+/** The light tint of a tone over a background: the fill of a toned box. */
+export const toneTint = (c, bg, pct = 8) => `color-mix(in srgb, ${c} ${pct}%, ${bg})`;
 /** The width of an edge-label pill in px: the label text plus its padding. The rail uses it for a payload, so both look the same. */
 export const labelPillW = (label) => textWidth(label, 11, true) + 14;
 /** The width of the `async` tag in px. */
@@ -41,6 +46,15 @@ export const DARK = { accent: '#1f78c8', fg: '#e3e3e3', muted: '#9aa0a6', bg: '#
 export const ON_ACCENT = '#ffffff';
 /** Only text survives outside React: a React element has no string form. */
 export const str = (n) => (typeof n === 'string' || typeof n === 'number' ? String(n) : '');
+/** The time a reader needs for a caption line: 400 ms plus 240 ms per word. The result is 0 for no text. */
+export const readMs = (say) => {
+    const w = str(say).split(/\s+/).filter(Boolean).length;
+    return w ? 400 + 240 * w : 0;
+};
+/** How long a beat lasts. An explicit `ms` wins as written. Else the beat lasts `speed` plus the time to read `say`. */
+export const beatMs = (b, speed) => b.ms ?? speed + readMs(b.say);
+/** The hold at the end of each step, before the next step starts. */
+export const STEP_HOLD_MS = 2000;
 export const nodes = (g) => g.children.flatMap((c) => (isGroup(c) ? nodes(c) : [c]));
 const labeledGroups = (g) => (g.label ? 1 : 0) + g.children.reduce((n, c) => n + (isGroup(c) ? labeledGroups(c) : 0), 0);
 /** The part counts of a spec, for the line that `flowfig check` prints. An agent copies the line into its reply. */

package/dist/rail.d.ts

@@ -1,5 +1,5 @@
 import type { Rect } from './geometry.ts';
-import { type FlowProps } from './model.ts';
+import { type FigTone, type FlowProps } from './model.ts';
 export declare const RAIL: {
     readonly gap: 24;
     readonly band: 20;
@@ -45,6 +45,7 @@ export type RailRow = {
     to: number;
     text: string;
     async: boolean;
+    tone?: FigTone;
     pill?: {
         x: number;
         w: number;

package/dist/rail.js

@@ -43,6 +43,7 @@ export function layoutRail(fig, mapWidth) {
         back: h.back,
         text: str(h.data) || str(edges.get(h.edge).label),
         async: h.async === true,
+        tone: h.tone,
     }))));
     const msgs = perStep.flat(2);
     if (!msgs.length)
@@ -127,7 +128,20 @@ export function layoutRail(fig, mapWidth) {
                 const pill = m.text ? { x: mid - labelPillW(m.text) / 2, w: labelPillW(m.text) } : undefined;
                 if (group != null)
                     groups[group].rows.push(rows.length);
-                rows.push({ kind: 'message', step: si, beat: m.beat, n: ++n, edge: m.edge, from, to, text: m.text, async: m.async, pill, group });
+                rows.push({
+                    kind: 'message',
+                    step: si,
+                    beat: m.beat,
+                    n: ++n,
+                    edge: m.edge,
+                    from,
+                    to,
+                    text: m.text,
+                    async: m.async,
+                    tone: m.tone,
+                    pill,
+                    group,
+                });
             }
         }
     });

package/dist/source.d.ts

@@ -4,6 +4,8 @@ export declare function parseSource(s: string): {
     path: string;
     symbol?: string;
 } | null;
+/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
+export declare const headingSlug: (text: string) => string;
 export type Link = {
     owner: string;
     source: string;

package/dist/source.js

@@ -7,6 +7,11 @@ export function parseSource(s) {
         return null;
     return m[2] ? { path: m[1], symbol: m[2] } : { path: m[1] };
 }
+/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
+export const headingSlug = (text) => text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N} -]/gu, '')
+    .replace(/ /g, '-');
 /** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
 export function owners(fig) {
     return [

package/dist/svg.js

@@ -12,18 +12,20 @@ import { textWidth } 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, labelPillW, ON_ACCENT, str, edgeId, groupGap, isGroup, isRows, toBeat, } 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, toBeat, beatMs, STEP_HOLD_MS, } 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, NODE_MIN_W = 100, NODE_MAX_W = 190;
 const FRAME_TOP = 37, FRAME_SIDE = 18, FRAME_BOTTOM = 18;
-// The card-on fills are fixed colors that approximate the player's 8% accent tint, so the SVG needs no color-mix.
-const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn};`;
+// The card-on fills are fixed colors that approximate the player's 8% accent tint. The active tint is the player's color-mix.
+const vars = (t, cardOn) => `--accent:${t.accent}; --fg:${t.fg}; --muted:${t.muted}; --bg:${t.bg}; --surface:${t.surface}; --border:${t.border}; --card-on:${cardOn}; --tint:color-mix(in srgb, var(--accent) 10%, var(--surface));`;
 /** What a card actually holds: rows, or its text. Only text survives outside React. */
 const content = (c) => (isRows(c) ? c : str(c));
 const esc = (s) => s.replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c]);
 const n2 = (v) => Math.round(v * 10) / 10;
-const pct = (v) => n2(v * 100) + '%';
+// Keyframe times are fractions of a loop that can last a minute: one decimal would round a 0.7 s hop away, and the packet would jump.
+const n4 = (v) => Math.round(v * 10000) / 10000;
+const pct = (v) => Math.round(v * 10000) / 100 + '%';
 /** Break a string into lines that fit `width`, keeping the newlines it already has. */
 function wrap(s, width, fontSize, mono = false) {
     const out = [];
@@ -191,17 +193,31 @@ export function render(fig, opts = {}) {
     // The timeline: every beat of every step, in order, with the player's hold at the end of each step.
     const segs = [];
     const hops = [];
+    const edgeOf = Object.fromEntries(fig.edges.map((e, i) => [ids[i], e]));
     let t = 0;
     beats.forEach((stepBeats, si) => {
         stepBeats.forEach((b, bi) => {
-            const dur = (b.ms ?? fig.speed ?? 900) / 1000 / BASE_RATE;
             const last = bi === stepBeats.length - 1;
+            const dur = beatMs(b, opts.speed ?? fig.speed ?? 900) / 1000 / BASE_RATE;
+            const hold = last ? STEP_HOLD_MS / 1000 / BASE_RATE : 0;
             b.hops.forEach((h, lane) => {
                 if (byId[h.edge])
-                    hops.push({ si, bi, lane, edge: h.edge, back: h.back, data: h.data, t0: t, t1: t + dur });
+                    hops.push({
+                        si,
+                        bi,
+                        lane,
+                        edge: h.edge,
+                        dest: h.back ? edgeOf[h.edge].from : edgeOf[h.edge].to,
+                        back: h.back,
+                        data: h.data,
+                        tone: h.tone && TONES[h.tone],
+                        t0: t,
+                        t1: t + speed,
+                        tEnd: t + dur,
+                    });
             });
-            segs.push({ t0: t, t1: t + dur + (last ? speed * 1.5 : 0), si, bi });
-            t += dur + (last ? speed * 1.5 : 0);
+            segs.push({ t0: t, t1: t + dur + hold, si, bi });
+            t += dur + hold;
         });
     });
     const total = t || 1;
@@ -242,8 +258,8 @@ export function render(fig, opts = {}) {
         return list ? ` class="${list}"` : '';
     };
     /** Like `anim`, for a property that takes a different value in each segment (a row that moves as phases fold). */
-    const frames = (values, prefix) => {
-        if (!segs.length || values.every((v) => v === values[0]))
+    const frames = (values, prefix, base = values[0]) => {
+        if (!segs.length || values.every((v) => v === base))
             return '';
         const key = prefix + values.join('|');
         if (!seen.has(key)) {
@@ -254,6 +270,59 @@ export function render(fig, opts = {}) {
         }
         return seen.get(key);
     };
+    /**
+     * The look of one box over the loop: off, trail (visited) or active (the packet arrived, until the segment ends).
+     * A segment ends at the beat end, or after the step hold for the last beat.
+     * Each frame holds one look. The gap before the frame that follows an active frame gives the FADE.
+     * FADE is in timeline seconds, which are wall seconds.
+     */
+    const FADE = 0.4;
+    // A box tone is a permanent state: a 1 px border and a light tint in the off and trail looks. The active look uses the hop tone, else the box tone.
+    const looks = (look, boxTone, hopTone) => {
+        const tint = boxTone ? toneTint(boxTone, 'var(--bg)') : 'var(--bg)';
+        if (look === 'off')
+            return [tint, boxTone ?? 'var(--border)', 1, 'drop-shadow(0 0 0 transparent)'];
+        if (look === 'trail')
+            return [tint, boxTone ?? 'var(--accent)', 1, 'drop-shadow(0 0 0 transparent)'];
+        const c = hopTone ?? boxTone;
+        return c
+            ? [toneTint(c, 'var(--surface)', 10), c, 2, `drop-shadow(0 0 4px ${c})`]
+            : ['var(--tint)', 'var(--accent)', 2, 'drop-shadow(0 0 4px var(--accent))'];
+    };
+    const boxAnim = (id, shape, boxTone) => {
+        const pieces = [];
+        segs.forEach((s, i) => {
+            if (!litNodes[i].has(id))
+                return void pieces.push({ a: s.t0, b: s.t1, look: 'off' });
+            const here = hops.filter((h) => h.dest === id && h.si === s.si && h.bi === s.bi);
+            const arrive = Math.min(...here.map((h) => h.t1), s.t1);
+            if (arrive > s.t0)
+                pieces.push({ a: s.t0, b: arrive, look: 'trail' });
+            if (arrive < s.t1)
+                pieces.push({ a: arrive, b: s.t1, look: 'active', hop: here.find((h) => h.tone)?.tone });
+        });
+        if (!pieces.length || pieces.every((q) => q.look === 'off'))
+            return '';
+        // The last frame is active: the fade ends at 100 %, so the loop wraps with no jump.
+        const end = pieces.at(-1);
+        if (end.look === 'active') {
+            end.b -= FADE;
+            pieces.push({ a: end.b, b: end.b + FADE, look: pieces[0].look, hop: pieces[0].hop, ramp: FADE - 0.0002 * total });
+        }
+        const kf = pieces.map((q, k) => {
+            const ramp = q.ramp ?? (q.look !== 'active' && pieces[k - 1]?.look === 'active' ? Math.min(FADE, (q.b - q.a) / 2) : 0);
+            const [fill, stroke, width, filter] = looks(q.look, boxTone, q.hop);
+            const css = `${shape ? `fill: ${fill}; ` : ''}stroke: ${stroke}; stroke-width: ${width}${shape ? `; filter: ${filter}` : ''}`;
+            return `${pct((q.a + ramp) / total)},${pct(q.b / total - 0.0001)} { ${css} }`;
+        });
+        const key = (shape ? 'B' : 'R') + kf.join(' ');
+        if (!seen.has(key)) {
+            const name = `a${seen.size}`;
+            seen.set(key, name);
+            css.push(`@keyframes ${name} { ${kf.join(' ')} }\n.${name} { animation: ${name} ${n2(total)}s infinite linear; }`);
+        }
+        return seen.get(key);
+    };
     const boxes = placed.map((p) => {
         const { item } = p;
         if (isGroup(item)) {
@@ -264,18 +333,21 @@ export function render(fig, opts = {}) {
                 cls(anim(on, 'stroke: var(--accent)', 'stroke: var(--border)', 'n')) +
                 `/><text x="${n2(p.x + FRAME_SIDE)}" y="${n2(p.y + 20)}" class="frame">${esc(str(item.label).toUpperCase())}</text>`);
         }
-        const on = segs.map((_, i) => litNodes[i].has(item.id));
-        const stroke = cls(anim(on, 'stroke: var(--accent)', 'stroke: var(--border)', 'n'));
+        const bt = item.tone && TONES[item.tone];
+        const stroke = cls(boxAnim(item.id, true, bt));
+        const rim = item.shape === 'store' ? cls(boxAnim(item.id, false, bt)) : '';
+        const fill0 = bt ? toneTint(bt, 'var(--bg)') : 'var(--bg)';
+        const stroke0 = bt ?? 'var(--border)';
         const cx = p.x + p.w / 2;
         const contents = cards.get(item.id);
         const cardTop = p.y + p.h - 10 - (contents ? cardH.get(item.id) : 0);
         const labelY = item.shape === 'store' ? p.y + 24 + 13 : contents ? p.y + 10 + 13 : p.y + p.h / 2 + (item.sub ? -2 : 5);
         const shape = item.shape === 'decision'
-            ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(p.y + p.h / 2)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(p.y + p.h / 2)}" fill="var(--bg)" stroke="var(--border)"${stroke}/>`
+            ? `<polygon points="${n2(cx)},${n2(p.y)} ${n2(p.x + p.w)},${n2(p.y + p.h / 2)} ${n2(cx)},${n2(p.y + p.h)} ${n2(p.x)},${n2(p.y + p.h / 2)}" fill="${fill0}" stroke="${stroke0}"${stroke}/>`
             : item.shape === 'store'
-                ? `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(p.w)} 0 v ${n2(p.h - 24)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(-p.w)} 0 z" fill="var(--bg)" stroke="var(--border)"${stroke}/>` +
-                    `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 0 ${n2(p.w)} 0" fill="none" stroke="var(--border)"${stroke}/>`
-                : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="var(--bg)" stroke="var(--border)"${stroke}/>`;
+                ? `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(p.w)} 0 v ${n2(p.h - 24)} a ${n2(p.w / 2)} 12 0 0 1 ${n2(-p.w)} 0 z" fill="${fill0}" stroke="${stroke0}"${stroke}/>` +
+                    `<path d="M${n2(p.x)} ${n2(p.y + 12)} a ${n2(p.w / 2)} 12 0 0 0 ${n2(p.w)} 0" fill="none" stroke="${stroke0}"${rim}/>`
+                : `<rect x="${n2(p.x)}" y="${n2(p.y)}" width="${n2(p.w)}" height="${n2(p.h)}" rx="10" fill="${fill0}" stroke="${stroke0}"${stroke}/>`;
         const label = `<text x="${n2(cx)}" y="${n2(labelY)}" class="label">${esc(str(item.label))}</text>`;
         const sub = item.sub ? `<text x="${n2(cx)}" y="${n2(labelY + SUB_LINE)}" class="sub">${esc(str(item.sub))}</text>` : '';
         return shape + label + sub + (contents ? card(p, cardTop, contents) : '');
@@ -340,7 +412,15 @@ export function render(fig, opts = {}) {
         const on = segs.map((_, i) => litEdges[i].has(r.id));
         const hidden = e.quiet && !on.every(Boolean);
         const shown = hidden ? cls(anim(on, 'opacity: 1', 'opacity: 0', 'q')) : '';
-        const lit = cls(anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, `stroke: var(--muted); stroke-width: ${EDGE_OFF}`, 'e'));
+        // A toned hop colors its edge for its own beat only; the trail after it is the accent.
+        const tone = segs.map(({ si, bi }) => (beats[si][bi].hops.find((h) => h.edge === r.id && h.tone)?.tone ?? undefined));
+        const col = tone.map((x) => (x ? TONES[x] : 'var(--accent)'));
+        const off = `stroke: var(--muted); stroke-width: ${EDGE_OFF}`;
+        // With no tone the map and the rail share one keyframe (same key); a toned edge needs its own values.
+        const toned = tone.some(Boolean);
+        const lit = cls(toned
+            ? frames(on.map((x, i) => (x ? `stroke: ${col[i]}; stroke-width: ${EDGE_ON}` : off)), 'e', off)
+            : anim(on, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, off, 'e'));
         const path = `<path id="p-${esc(r.id)}" d="${r.d}" fill="none" stroke="var(--muted)" stroke-width="${EDGE_OFF}" marker-end="url(#arrow)"${lit}/>`;
         // A quiet edge is only drawn while a step uses it, so wrap the whole thing rather than the stroke.
         const label = e.label == null
@@ -350,17 +430,19 @@ export function render(fig, opts = {}) {
                 labelRects[r.id] = { x: r.mid.x - lw / 2, y: r.mid.y - 9, w: lw, h: 18 };
                 fonts.push(11);
                 return (`<rect x="${n2(r.mid.x - lw / 2)}" y="${n2(r.mid.y - 9)}" width="${n2(lw)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"` +
-                    cls(anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
+                    cls(toned
+                        ? frames(on.map((x, i) => x ? `fill: ${tone[i] ? toneFill(col[i]) : col[i]}; stroke: ${col[i]}` : 'fill: var(--bg); stroke: var(--border)'), 'l', 'fill: var(--bg); stroke: var(--border)')
+                        : anim(on, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l')) +
                     `/><text x="${n2(r.mid.x)}" y="${n2(r.mid.y + 4)}"${cls('edgelabel', anim(on, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(str(e.label))}</text>`);
             })();
         return hidden ? `<g opacity="0"${shown}>${path}${label}</g>` : path + label;
     });
-    // A packet per hop: it waits offstage, crosses its edge during its beat, then leaves. Any `data`
+    // A packet per hop: it waits offstage, crosses its edge in `speed`, rests at the end of the edge to the end of its beat, then leaves. Any `data`
     // rides above it in a chip, which is how the figure says what is moving.
     const packets = hops.map((h, i) => {
-        const t0 = h.t0 / total, t1 = h.t1 / total;
+        const t0 = h.t0 / total, t1 = h.t1 / total, tEnd = h.tEnd / total;
         const name = `p${i}`;
-        css.push(`@keyframes ${name} { 0%,${pct(t0)} { opacity: 0 } ${pct(t0 + 0.0001)},${pct(t1 - 0.0001)} { opacity: 1 } ${pct(t1)},100% { opacity: 0 } }\n` +
+        css.push(`@keyframes ${name} { 0%,${pct(t0)} { opacity: 0 } ${pct(t0 + 0.0001)},${pct(tEnd - 0.0001)} { opacity: 1 } ${pct(tEnd)},100% { opacity: 0 } }\n` +
             `.${name} { animation: ${name} ${n2(total)}s infinite step-end; }`);
         const chip = (() => {
             const label = str(h.data);
@@ -370,11 +452,11 @@ export function render(fig, opts = {}) {
             const lines = wrap(label, 210, 11.5);
             const w = Math.max(...lines.map((l) => textWidth(l, 11.5))) + 18;
             const boxH = lines.length * 15 + 8;
-            return (`<rect x="${n2(-w / 2)}" y="${n2(-boxH - 12)}" width="${n2(w)}" height="${n2(boxH)}" rx="8" fill="var(--accent)"/>` +
+            return (`<rect x="${n2(-w / 2)}" y="${n2(-boxH - 12)}" width="${n2(w)}" height="${n2(boxH)}" rx="8" fill="${h.tone ? toneFill(h.tone) : 'var(--accent)'}"/>` +
                 lines.map((l, li) => `<text x="0" y="${n2(-boxH - 12 + 15 * li + 15)}" class="chip">${esc(l)}</text>`).join(''));
         })();
-        return (`<g${cls(name)} opacity="0"><circle r="10" fill="var(--accent)" opacity="0.2"/><circle r="4.5" fill="var(--accent)"/>${chip}` +
-            `<animateMotion dur="${n2(total)}s" repeatCount="indefinite" keyTimes="0;${n2(t0)};${n2(t1)};1" keyPoints="${h.back ? '1;1;0;0' : '0;0;1;1'}" calcMode="linear">` +
+        return (`<g${cls(name)} opacity="0"><circle r="10" fill="${h.tone ?? 'var(--accent)'}" opacity="0.2"/><circle r="4.5" fill="${h.tone ?? 'var(--accent)'}"/>${chip}` +
+            `<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>`);
     });
     const bounds = placed[0];
@@ -463,7 +545,8 @@ export function render(fig, opts = {}) {
                 const next = segs.map((s) => s.si < row.step || (s.si === row.step && s.bi < row.beat));
                 const [x1, x2] = [rail.columns[row.from].x, rail.columns[row.to].x];
                 const ly = y + RAIL.row / 2;
-                const lit = anim(now, `stroke: var(--accent); stroke-width: ${EDGE_ON}`, `stroke: var(--muted); stroke-width: ${EDGE_OFF}`, 'e');
+                const col = row.tone ? TONES[row.tone] : 'var(--accent)';
+                const lit = anim(now, `stroke: ${col}; stroke-width: ${EDGE_ON}`, `stroke: var(--muted); stroke-width: ${EDGE_OFF}`, row.tone ? 'e' + col : 'e');
                 const tagW = ASYNC_TAG_W;
                 // The tag sits on the tail side of the pill, so it never hides the arrowhead.
                 const tagX = !row.pill ? (x1 + x2) / 2 - tagW / 2 : x2 > x1 ? row.pill.x - tagW - 4 : row.pill.x + row.pill.w + 4;
@@ -473,7 +556,7 @@ export function render(fig, opts = {}) {
                         `<text x="${n2(tagX + tagW / 2)}" y="${n2(ly + 3)}" class="tag" fill="${TONES.gray}">ASYNC</text>`
                     : '';
                 const pill = row.pill
-                    ? `<rect x="${n2(row.pill.x)}" y="${n2(ly - 9)}" width="${n2(row.pill.w)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"${cls(anim(now, 'fill: var(--accent); stroke: var(--accent)', 'fill: var(--bg); stroke: var(--border)', 'l'))}/>` +
+                    ? `<rect x="${n2(row.pill.x)}" y="${n2(ly - 9)}" width="${n2(row.pill.w)}" height="18" rx="9" fill="var(--bg)" stroke="var(--border)"${cls(anim(now, `fill: ${row.tone ? toneFill(col) : col}; stroke: ${col}`, 'fill: var(--bg); stroke: var(--border)', row.tone ? 'l' + col : 'l'))}/>` +
                         `<text x="${n2(row.pill.x + row.pill.w / 2)}" y="${n2(ly + 4)}"${cls('edgelabel', anim(now, `fill: ${ON_ACCENT}`, 'fill: var(--muted)', 'x'))}>${esc(row.text)}</text>`
                     : '';
                 parts.push(`<g${cls('railrow', moveRow(i))}><g${cls(anim(next, 'opacity: .45', 'opacity: 1', 'r'))}>` +
@@ -507,7 +590,7 @@ svg { ${vars(t0, '#eef5fd')} }
 .end { text-anchor: end; }
 ${css.join('\n')}
 </style>
-<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="var(--muted)"/></marker></defs>
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 9 5 L 0 9 z" fill="context-stroke"/></marker></defs>
 <rect width="100%" height="100%" fill="var(--bg)"/>
 ${only
         ? ''

package/dist/verify.d.ts

@@ -1,6 +1,6 @@
 import type { FlowProps } from './model.ts';
 import type { Finding } from './scene.ts';
-export { parseSource, owners, links, type Link } from './source.ts';
+export { parseSource, headingSlug, owners, links, type Link } from './source.ts';
 /** The links against the files under `root`. A path outside the root is a missing file: the figure names the repo, not the disk. */
 export declare function verify(fig: FlowProps, { root }?: {
     root?: string;

package/dist/verify.js

@@ -1,8 +1,8 @@
 // `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 { links } from './source.js';
-export { parseSource, owners, links } from './source.js';
+import { headingSlug, links } from './source.js';
+export { parseSource, headingSlug, owners, links } from './source.js';
 const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 /** The file text, or null for a missing path, a folder or an unreadable file. */
 function read(full) {
@@ -13,6 +13,11 @@ function read(full) {
         return null;
     }
 }
+/** True if a heading line of the Markdown text has this slug. */
+const hasHeading = (text, slug) => text.split('\n').some((line) => {
+    const m = /^#{1,6}\s+(.*?)\s*#*\s*$/.exec(line);
+    return m != null && headingSlug(m[1]) === slug;
+});
 /** The links against the files under `root`. A path outside the root is a missing file: the figure names the repo, not the disk. */
 export function verify(fig, { root = process.cwd() } = {}) {
     const out = [];
@@ -29,7 +34,9 @@ export function verify(fig, { root = process.cwd() } = {}) {
         const text = files.get(full);
         if (text == null)
             out.push({ rule: 'missing-file', severity: 'error', ids: [], message: `${l.owner} -> ${l.source}: file not found` });
-        else if (l.symbol && !new RegExp(`(^|[^\\w$])${escape(l.symbol)}(?![\\w$])`).test(text))
+        else if (l.symbol &&
+            !new RegExp(`(^|[^\\w$])${escape(l.symbol)}(?![\\w$])`).test(text) &&
+            !(/\.(md|markdown)$/i.test(l.path) && hasHeading(text, l.symbol)))
             out.push({ rule: 'missing-symbol', severity: 'error', ids: [], message: `${l.owner} -> ${l.source}: symbol not found` });
     }
     return out;

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.2.0";
+export declare const VERSION = "0.3.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.2.0';
+export const VERSION = '0.3.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowfig",
-  "version": "0.2.0",
+  "version": "0.3.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": {