flowfig 0.1.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
@@ -80,6 +95,8 @@ Then ask your agent: "draw a diagram of how login works in this repo".
 - [Three forms](#three-forms)
 - [The spec](#the-spec)
 - [Check a figure](#check-a-figure)
+- [Verify in CI](#verify-in-ci)
+- [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
 - [Use with your coding agent](#use-with-your-coding-agent)
@@ -172,6 +189,8 @@ Each SVG from the CLI carries its own spec. These commands made the rail-only fi
 npx flowfig --spec docs/checkout.svg > checkout.json   # print the spec in the SVG
 # edit checkout.json: set "props.rail" to "only"
 npx flowfig checkout.json docs/checkout-rail-only.svg
+npx flowfig verify docs/checkout.svg                    # check that each source still exists
+npx flowfig diff old.svg docs/checkout.svg              # list what changed in the spec
 ```
 
 ## The spec
@@ -181,14 +200,15 @@ full reference, run `npx flowfig docs`.
 
 ### Boxes
 
-| Field   | Meaning                                                           | Default     |
-| ------- | ----------------------------------------------------------------- | ----------- |
-| `id`    | The name that edges and steps use. It must be unique.             | required    |
-| `label` | The title in the box.                                             | required    |
-| `sub`   | A smaller line under the label.                                   | none        |
-| `shape` | `"box"`, `"decision"` (a diamond) or `"store"` (a data cylinder). | `"box"`     |
-| `lines` | The least number of text lines that a content card keeps.         | none        |
-| `width` | The width in px. This value replaces the width that layout picks. | from layout |
+| Field    | Meaning                                                                   | Default     |
+| -------- | ------------------------------------------------------------------------- | ----------- |
+| `id`     | The name that edges and steps use. It must be unique.                     | required    |
+| `label`  | The title in the box.                                                     | required    |
+| `sub`    | A smaller line under the label.                                           | none        |
+| `shape`  | `"box"`, `"decision"` (a diamond) or `"store"` (a data cylinder).         | `"box"`     |
+| `source` | The code this draws: `path` or `path#symbol`. `flowfig verify` checks it. | none        |
+| `lines`  | The least number of text lines that a content card keeps.                 | none        |
+| `width`  | The width in px. This value replaces the width that layout picks.         | from layout |
 
 ### Groups
 
@@ -205,14 +225,15 @@ full reference, run `npx flowfig docs`.
 
 ### Edges
 
-| Field    | Meaning                                                                 | Default    |
-| -------- | ----------------------------------------------------------------------- | ---------- |
-| `from`   | The id of the box or group where the edge starts.                       | required   |
-| `to`     | The id of the box or group where the edge ends.                         | required   |
-| `id`     | The name that beats use.                                                | `from->to` |
-| `label`  | The text on the edge.                                                   | none       |
-| `around` | `"above"` or `"below"` routes the edge over or under the boxes between. | none       |
-| `quiet`  | `true` draws the edge only while a step uses it.                        | `false`    |
+| Field    | Meaning                                                                        | Default    |
+| -------- | ------------------------------------------------------------------------------ | ---------- |
+| `from`   | The id of the box or group where the edge starts.                              | required   |
+| `to`     | The id of the box or group where the edge ends.                                | required   |
+| `id`     | The name that beats use.                                                       | `from->to` |
+| `label`  | The text on the edge.                                                          | none       |
+| `around` | `"above"` or `"below"` routes the edge over or under the boxes between.        | none       |
+| `quiet`  | `true` draws the edge only while a step uses it.                               | `false`    |
+| `source` | The code this edge draws: `path` or `path#symbol`. `flowfig verify` checks it. | none       |
 
 ### Steps
 
@@ -229,13 +250,13 @@ Each step is one story. The player shows one tab for each step. With no steps, t
 
 A beat is an edge id, an array of edge ids that run at the same time, or an object:
 
-| Field   | Meaning                                                                            | Default        |
-| ------- | ---------------------------------------------------------------------------------- | -------------- |
-| `edges` | One hop or an array of hops. A hop is an edge id or `{ edge, back, data, async }`. | none (a pause) |
-| `say`   | The line of narration for the beat.                                                | none           |
-| `show`  | `{ boxId: content }` fills the content card of a box until the step ends.          | none           |
-| `light` | The ids of the boxes to highlight for this beat only.                              | none           |
-| `ms`    | The length of the beat in ms.                                                      | `speed` (900)  |
+| Field   | Meaning                                                                                    | Default        |
+| ------- | ------------------------------------------------------------------------------------------ | -------------- |
+| `edges` | One hop or an array of hops. A hop is an edge id or `{ edge, back, data, async, source }`. | none (a pause) |
+| `say`   | The line of narration for the beat.                                                        | none           |
+| `show`  | `{ boxId: content }` fills the content card of a box until the step ends.                  | none           |
+| `light` | The ids of the boxes to highlight for this beat only.                                      | none           |
+| `ms`    | The length of the beat in ms.                                                              | `speed` (900)  |
 
 In a hop, `back: true` runs the packet from `to` to `from`. `data` is a small card on the packet. `async: true` marks a message
 that does not wait for an answer.
@@ -294,6 +315,45 @@ A render runs the same check first. If the check finds an error, the render writ
 In React, `<Flow check />` runs the same rules on the layout that the browser drew. The player prints each fault with
 `console.warn`.
 
+## Verify in CI
+
+A box, an edge or a hop can name the code it draws: `"source": "src/auth/login.ts#verifyPassword"`. `npx flowfig verify docs/login.svg`
+fails when the file or the symbol is gone. The action runs `verify` on every figure in a pull request. It comments the old and
+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
+  pull-requests: write
+steps:
+  - uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 22
+  - uses: iamalvisng/flowfig@v0.2.0
+    with:
+      figures: 'docs/**/*.svg' # default **/*.svg
+```
+
+## MCP server
+
+`npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.
+`render` writes the SVG file and returns the check lines and the path, so no SVG text goes through the model.
+
+`npx flowfig init` registers the server for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), GitHub Copilot
+(`.vscode/mcp.json`), Gemini CLI (`.gemini/settings.json`) and Kiro (`.kiro/settings/mcp.json`). It merges one entry into
+the file and keeps every other server. `--no-mcp` skips this step. If you formatted the file with other spacing, the first
+run rewrites it once. For any other client, add:
+
+```json
+{ "mcpServers": { "flowfig": { "command": "npx", "args": ["flowfig", "mcp"] } } }
+```
+
 ## Use in React
 
 ```tsx
@@ -348,6 +408,8 @@ writeFileSync('first.svg', toSvg(spec));
 - `check(spec, options)` returns the findings. It also takes `width` and `minText`.
 - `render(spec, options)` returns `{ svg, scene }`. The scene is the layout that the check reads. Its shape can change.
 
+`flowfig/verify` is for Node only. It exports `verify`, `links`, `owners` and `parseSource`, the same checks as `flowfig verify`.
+
 `toSvg` does not put the spec in the SVG. Only the CLI adds the spec, which `--spec` reads back.
 
 ## Use with your coding agent
@@ -378,8 +440,9 @@ On a terminal, `init` shows a picker. The picker selects the agents that the rep
 | `--agents <ids>` | Write for these agents, for example `--agents claude,cursor`. |
 | `--all-agents`   | Write for all 7 agents.                                       |
 | `-y`, `--yes`    | Write for the agents that the repo uses, with no picker.      |
-| `--global`       | Write only the Claude Code skill, to your home directory.     |
+| `--global`       | Write the Claude skill and the MCP entry to your home folder. |
 | `--dry-run`      | Print what `init` would write, and write nothing.             |
+| `--no-mcp`       | Do not register the MCP server.                               |
 | `--list-agents`  | Print the agent ids.                                          |
 
 With no terminal and no `-y`, `--agents` or `--all-agents`, `init` prints the agent ids and exits with code 2.

package/dist/check.js

@@ -1,7 +1,8 @@
 // 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 });
 const warn = (rule, ids, message) => ({ rule, severity: 'warning', ids, message });
 const groupIds = (g) => [...(g.id ? [g.id] : []), ...g.children.flatMap((c) => (isGroup(c) ? groupIds(c) : []))];
@@ -43,6 +44,10 @@ export function checkSpec(fig) {
         if (e.quiet && !used.has(edges[i]))
             out.push(err('hidden-edge', [edges[i]], `edge "${edges[i]}" is quiet and no beat uses it, so the figure never shows it`));
     });
+    // A link with a bad form never verifies, so say so here, where the spec is checked.
+    for (const [who, source] of owners(fig))
+        if (source != null && !parseSource(source))
+            out.push(warn('bad-source', [], `${who}: source "${source}" is not path or path#symbol`));
     return out;
 }
 /** A point on the cubic Bézier at `t`. */
@@ -73,7 +78,7 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
     const labeled = scene.edges.filter((e) => e.label);
     labeled.forEach((e, i) => {
         for (const f of labeled.slice(i + 1))
-            if (overlap(e.label, f.label, 1))
+            if ((e.step == null || f.step == null || e.step === f.step) && overlap(e.label, f.label, 1))
                 out.push(err('label-overlap', [e.id, f.id], `the labels of edges "${e.id}" and "${f.id}" overlap`));
         for (const b of scene.boxes)
             if (overlap(e.label, b.rect, 1))
@@ -123,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 = [];
@@ -137,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]);
@@ -149,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

@@ -15,8 +15,12 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   flowfig figure.ts out.svg            # a module whose default export is a spec
  *   flowfig --spec out.svg               # print back the spec the SVG carries
  *   flowfig check <input> [--json]       # list the faults; the input can also be an SVG this wrote
+ *   flowfig verify <input>... [--root dir]   # check that the code each figure links to still exists
+ *   flowfig diff <old> <new> [--json|--md]   # list the spec changes between two figures
  *   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.
@@ -27,11 +31,23 @@ 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 { counts } from './model.js';
-import { check, toSvg } from './svg.js';
-const SPEC_OPEN = '<metadata id="figure-spec"><![CDATA[';
-const SPEC_CLOSE = ']]></metadata>';
+import { serve } from './mcp.js';
+import { diff, formatDiff } from './diff.js';
+import { loadSpec, reportLines, sortFindings, specOf, svgWithSpec } from './load.js';
+import { check } from './svg.js';
+import { links, verify } from './verify.js';
+const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg]   render a figure; a spec on stdin with -
+       flowfig check <-|spec.json|figure.ts|figure.svg>   list the faults; the input can be an SVG this wrote
+       flowfig --spec figure.svg                          print the spec the SVG carries
+       flowfig verify <input>... [--root <dir>] [--json] [--strict]   check the code links of one or more figures
+       flowfig diff <old> <new> [--json|--md]   list the spec changes between two figures
+       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) {
     console.error(message);
@@ -49,22 +65,98 @@ const value = (name) => {
     const n = Number(args.splice(i, 2)[1] || NaN);
     return n > 0 && Number.isFinite(n) ? n : usage(`${name} needs a positive number`);
 };
-function specOf(svg, name) {
-    const at = svg.indexOf(SPEC_OPEN);
-    if (at === -1)
-        usage(`${name}: no figure spec inside this SVG`);
-    return svg.slice(at + SPEC_OPEN.length, svg.indexOf(SPEC_CLOSE, at));
+if (!args[0] || ['help', '--help', '-h'].includes(args[0])) {
+    if (args[0])
+        console.log(USAGE);
+    else
+        usage(USAGE);
+    process.exit(0);
 }
 if (args[0] === 'docs') {
     process.stdout.write(GUIDE);
     process.exit(0);
 }
+if (args[0] === 'mcp') {
+    await serve(process.stdin, process.stdout);
+    // A pipe write is asynchronous: wait until the queued response lines are out before the exit.
+    await new Promise((done) => process.stdout.write('', () => done(undefined)));
+    process.exit(0);
+}
 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');
-    console.log(specOf(readFileSync(args[1], 'utf8'), args[1]));
+    let svg = '';
+    try {
+        svg = readFileSync(args[1], 'utf8');
+    }
+    catch (e) {
+        usage(`${args[1]}: ${e.message}`);
+    }
+    try {
+        console.log(specOf(svg, args[1]));
+    }
+    catch (e) {
+        usage(e.message);
+    }
+    process.exit(0);
+}
+/** A spec from stdin, a JSON file, an SVG this wrote, or a module. Exit 2 with a message on any failure. */
+async function load(input) {
+    try {
+        if (input.endsWith('.json') || input.endsWith('.svg'))
+            return loadSpec(input);
+        if (input === '-')
+            return loadSpec(JSON.parse(readFileSync(0, 'utf8')), input);
+        return loadSpec((await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(input)).href))).default, input);
+    }
+    catch (e) {
+        const m = e.message;
+        return usage(m.startsWith(`${input}: `) ? m : `${input}: ${m}`);
+    }
+}
+if (args[0] === 'verify') {
+    args.shift();
+    const json = flag('--json'), strict = flag('--strict');
+    const at = args.indexOf('--root');
+    const root = at === -1 ? process.cwd() : (args.splice(at, 2)[1] ?? usage('--root needs a folder'));
+    const unknown = args.find((a) => a.startsWith('-') && a !== '-');
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    if (!args.length)
+        usage('verify needs at least one figure');
+    const findings = [];
+    const all = [];
+    for (const input of args) {
+        const props = await load(input);
+        const found = sortFindings([...check(props), ...verify(props, { root })], strict).map((f) => ({ ...f, figure: input }));
+        findings.push(...found);
+        all.push(...links(props).map((l) => ({ ...l, figure: input })));
+    }
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    if (json)
+        console.log(JSON.stringify({ findings, links: all }, null, 2));
+    else {
+        const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
+        for (const f of findings)
+            console.log(`${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.figure}: ${f.message}`);
+        console.log(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
+    }
+    process.exit(errors ? 1 : 0);
+}
+if (args[0] === 'diff') {
+    args.shift();
+    const json = flag('--json'), md = flag('--md');
+    const unknown = args.find((a) => a.startsWith('-') && a !== '-');
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    if (args.length !== 2)
+        usage('diff needs two figures: flowfig diff <old> <new> [--json|--md]');
+    const changes = diff(await load(args[0]), await load(args[1]));
+    console.log(json ? JSON.stringify(changes, null, 2) : formatDiff(changes, md ? 'md' : 'text'));
     process.exit(0);
 }
 const command = args[0] === 'check' ? args.shift() : 'render';
@@ -75,44 +167,17 @@ if (unknown)
     usage(`unknown flag ${unknown}`);
 const [input, out] = args;
 if (!input)
-    usage('usage: flowfig <-|spec.json|figure.ts> [out.svg]  |  flowfig check <-|spec.json|figure.ts|figure.svg> [--json]  |  flowfig docs  |  flowfig init [dir]');
-let loaded;
-try {
-    loaded =
-        input === '-'
-            ? JSON.parse(readFileSync(0, 'utf8'))
-            : input.endsWith('.json')
-                ? JSON.parse(readFileSync(input, 'utf8'))
-                : input.endsWith('.svg')
-                    ? JSON.parse(specOf(readFileSync(input, 'utf8'), input))
-                    : (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(input)).href))).default;
-}
-catch (e) {
-    usage(`${input}: ${e.message}`);
-}
-const props = loaded?.props ?? loaded;
-if (!props?.layout)
-    usage(`${input}: no figure props (expected { props: { layout, edges, steps } })`);
-if (!Array.isArray(props.edges))
-    usage(`${input}: edges must be an array (use [] for none)`);
-if (props.steps?.some((s) => !Array.isArray(s?.flow)))
-    usage(`${input}: each step needs a flow array`);
-const findings = skip
-    ? []
-    : check(props, opts)
-        .map((f) => (strict ? { ...f, severity: 'error' } : f))
-        .sort((a, b) => (a.severity === b.severity ? a.rule.localeCompare(b.rule) : a.severity === 'error' ? -1 : 1));
+    usage(USAGE);
+const props = await load(input);
+const findings = skip ? [] : sortFindings(check(props, opts), strict);
 const errors = findings.filter((f) => f.severity === 'error').length;
-/** The findings for a person: one line each, colored only on a terminal. A render prints them to stderr, next to its own output. */
+/** The findings for a person: one line each, colored only on a terminal, then the counts. A render prints them to stderr, next to
+ * its own output. A clean render still prints `0 errors, 0 warnings`: the agent copies that line into its reply. */
 const report = (print, tty) => {
-    const paint = (s, code) => (tty && !process.env.NO_COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
-    for (const f of findings)
-        print(`${paint(f.severity.padEnd(8), f.severity === 'error' ? 31 : 33)} ${f.rule.padEnd(18)} ${f.message}`);
-    const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
-    if (findings.length || print === console.log)
-        print(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
-    const c = counts(props);
-    print(`figure: ${n(c.boxes, 'box').replace('boxs', 'boxes')}, ${n(c.groups, 'group')}, ${n(c.edges, 'edge')}, ${n(c.steps, 'step')}, ${n(c.messages, 'message')}`);
+    // The severity field is 8 characters wide, so the painted field keeps the same width.
+    const paint = (s) => tty && !process.env.NO_COLOR ? s.replace(/^(error {3}|warning )/, (w) => `\x1b[${w[0] === 'e' ? 31 : 33}m${w}\x1b[0m`) : s;
+    for (const line of reportLines(props, findings, !skip))
+        print(paint(line));
 };
 if (command === 'check') {
     if (json)
@@ -126,8 +191,6 @@ if (errors)
     process.exit(1);
 const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
 // The spec rides along in <metadata>: an SVG is then its own source, and no JSON has to be kept.
-// `]]>` would close the CDATA early; it cannot appear in JSON-encoded text, but be sure.
-const spec = JSON.stringify({ props }).replaceAll(']]>', ']]\\u003e');
-const withSpec = toSvg(props).replace(/(<svg[^>]*>\n?)/, (tag) => `${tag}${SPEC_OPEN}${spec}${SPEC_CLOSE}\n`);
+const withSpec = svgWithSpec(props);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);

package/dist/diff.d.ts

@@ -0,0 +1,9 @@
+import { type FlowProps } from './model.ts';
+export type Change = {
+    kind: 'box' | 'edge' | 'step' | 'message' | 'rail';
+    op: 'added' | 'removed' | 'changed';
+    id: string;
+    detail?: string;
+};
+export declare function diff(before: FlowProps, after: FlowProps): Change[];
+export declare function formatDiff(changes: Change[], as: 'text' | 'md'): string;

package/dist/diff.js

@@ -0,0 +1,59 @@
+// The spec diff: what a PR changed in a figure, by id. The SVG geometry follows from the spec, so the spec is the diff.
+import { edgeId, isGroup, str, toBeat } from './model.js';
+const show = (v) => (v == null ? '(none)' : `"${str(v)}"`);
+/** The fields that changed, as `name "old" -> "new"` parts; empty when equal. */
+const fields = (a, b, names) => names.filter((k) => str(a[k]) !== str(b[k])).map((k) => `${String(k)} ${show(a[k])} -> ${show(b[k])}`);
+/** Compare two maps by key. The order is stable: changed first, then removed, then added. */
+function compare(kind, before, after, fieldsOf) {
+    const out = [];
+    for (const [id, a] of before) {
+        const b = after.get(id);
+        if (!b)
+            continue;
+        const d = fieldsOf(a, b);
+        if (d.length)
+            out.push({ kind, op: 'changed', id, detail: d.join('; ') });
+    }
+    for (const id of before.keys())
+        if (!after.has(id))
+            out.push({ kind, op: 'removed', id });
+    for (const id of after.keys())
+        if (!before.has(id))
+            out.push({ kind, op: 'added', id });
+    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)}"` : ''}${h.tone ? ` [${h.tone}]` : ''}`)))
+    .map((id) => [id, id]));
+export function diff(before, after) {
+    const boxes = (f) => {
+        const m = new Map();
+        // The group is its label, else its id; the top level has none.
+        const walk = (g, parent) => g.children.forEach((c) => (isGroup(c) ? walk(c, c.label != null ? str(c.label) : c.id) : m.set(c.id, { ...c, group: parent })));
+        walk(f.layout);
+        return m;
+    };
+    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', '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), () => []),
+    ];
+    // The rail is a boolean or 'only', so str() would hide it.
+    if ((before.rail ?? false) !== (after.rail ?? false))
+        out.push({ kind: 'rail', op: 'changed', id: 'rail', detail: `${before.rail ?? '(none)'} -> ${after.rail ?? '(none)'}` });
+    return out;
+}
+export function formatDiff(changes, as) {
+    if (!changes.length)
+        return as === 'md' ? '- no change in the spec' : 'no change in the spec';
+    return changes
+        .map((c) => {
+        const id = as === 'md' ? `\`${c.id}\`` : c.id;
+        const line = `${c.kind} ${c.op}: ${id}${c.detail ? ` (${c.detail})` : ''}`;
+        return as === 'md' ? `- ${line}` : line;
+    })
+        .join('\n');
+}

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>;