flowfig 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Vectorize AI, Inc.
+Copyright (c) 2026 Alvis Ng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,428 @@
+<div align="center">
+
+<h1><img src="docs/logo.svg" alt="flowfig" height="80"/></h1>
+
+### Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf and Kiro draw the diagram from your code. flowfig checks it before it goes in your README.
+
+<p>
+  <a href="https://www.npmjs.com/package/flowfig"><img src="https://img.shields.io/npm/v/flowfig?style=for-the-badge&logo=npm&logoColor=white&label=npm" alt="npm version"/></a>
+  <a href="https://github.com/iamalvisng/flowfig/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/iamalvisng/flowfig/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI" alt="CI status"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-20C997?style=for-the-badge" alt="License: MIT"/></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-5FA04E?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node 18 or later"/>
+  <img src="https://img.shields.io/badge/dependencies-0-0074D9?style=for-the-badge" alt="Zero runtime dependencies"/>
+</p>
+
+<img src="docs/hero.svg" alt="You ask your coding agent for a diagram. The agent reads the code and writes a spec. flowfig check sends a fault back, the agent fixes the spec, and the SVG goes in the README." width="100%"/>
+
+</div>
+
+An agent with the flowfig instructions made faithful, checked diagrams more often than the same agent without them:
+
+| Criterion                                           | Agent without flowfig instructions | Agent with flowfig instructions                |
+| --------------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
+| Diagram faithful to the code (no invented part)     | 7 of 8                             | 8 of 8                                         |
+| Right diagram form for the task                     | 5 of 7                             | 7 of 7                                         |
+| Passes `flowfig check --strict`                     | 5 of 7                             | 6 of 6                                         |
+| Right action (draws, declines or splits)            | 6 of 8                             | 7 of 8                                         |
+| Held-out tasks (not used to write the instructions) | –                                  | 2 of 4 pass all 6 criteria; 2 of 4 pass 4 of 6 |
+
+[How we measured](#how-we-measured).
+
+## Quick start
+
+```bash
+npx flowfig init
+```
+
+Then ask your agent: "draw a diagram of how login works in this repo".
+
+`init` writes the flowfig instructions for the agents that your repo uses. The agent reads the code, writes a spec, runs
+`flowfig check`, fixes the faults, and renders the SVG.
+
+## The problem
+
+- A diagram in a repo drifts from the code. No one sees the drift.
+- An agent that you ask for a diagram invents parts that the code does not have.
+- A static picture cannot show the order of the calls or their payloads.
+
+## What flowfig does
+
+- **One command sets up 7 agents.** `npx flowfig init` writes instructions for Claude Code, Cursor, GitHub Copilot, Codex and
+  others through `AGENTS.md`, Gemini CLI, Windsurf and Kiro.
+- **The agent writes JSON, not pictures.** The agent reads the code and writes a JSON spec of the parts, the calls and their
+  order. flowfig does the layout.
+- **`flowfig check` finds the faults a machine can read.** It finds ids that point nowhere, text wider than its box, edges
+  through boxes, overlapping labels, hidden edges, text too small at the README width, and low contrast. The agent reads the
+  faults and fixes the spec.
+- **The output is one animated SVG with no script.** The SVG plays in a GitHub README, PR or issue. It follows the light or dark
+  mode of the reader.
+- **Every SVG carries its own spec.** `npx flowfig --spec figure.svg` prints the spec. Any agent can read a diagram back, change
+  it, and render it again.
+- **Three forms and a React player.** The forms are the map, the map with a lifeline rail for sequences, and the rail alone. The
+  React player adds tabs, pause and hover. The package has zero runtime dependencies. Only the React player needs React.
+
+## flowfig, Mermaid and a hand-drawn image
+
+|                                | flowfig                           | Mermaid                              | Hand-drawn image |
+| ------------------------------ | --------------------------------- | ------------------------------------ | ---------------- |
+| Made by an agent from the code | Yes, with the `init` instructions | Yes, as Mermaid text                 | No               |
+| Checked for faults             | Yes, 11 rules in `flowfig check`  | Syntax errors only                   | No               |
+| Animated                       | Yes, one packet per message       | No                                   | No               |
+| Shows payloads and order       | Yes, on the map and the rail      | Order and text in a sequence diagram | No               |
+| Plays in a GitHub README       | Yes, as an SVG                    | Yes, GitHub renders it               | Yes, as an image |
+| Readable back as source        | Yes, with `--spec`                | Yes, the source is text              | No               |
+| Class and ER diagrams          | No                                | Yes. Mermaid wins this row.          | Yes              |
+
+## Contents
+
+- [Install](#install)
+- [Your first figure](#your-first-figure)
+- [Three forms](#three-forms)
+- [The spec](#the-spec)
+- [Check a figure](#check-a-figure)
+- [Use in React](#use-in-react)
+- [Use from Node](#use-from-node)
+- [Use with your coding agent](#use-with-your-coding-agent)
+- [What flowfig does not draw](#what-flowfig-does-not-draw)
+- [How we measured](#how-we-measured)
+- [License](#license)
+- [Development](#development)
+
+## Install
+
+```bash
+npm i flowfig
+```
+
+React (>=18) is a peer dependency. Only the React player needs React. The CLI and `flowfig/svg` do not need React. flowfig needs
+Node 18 or later.
+
+## Your first figure
+
+Save this spec as `first.json`. The spec has 3 boxes, 2 edges and 1 step.
+
+```json
+{
+  "layout": {
+    "children": [
+      { "id": "browser", "label": "Browser" },
+      { "id": "api", "label": "API" },
+      { "id": "db", "label": "Database", "shape": "store" }
+    ]
+  },
+  "edges": [
+    { "from": "browser", "to": "api", "label": "GET /user" },
+    { "from": "api", "to": "db", "label": "SELECT" }
+  ],
+  "steps": [
+    {
+      "label": "Load a user",
+      "flow": [
+        { "edges": "browser->api", "say": "The browser asks the API for the user." },
+        { "edges": "api->db", "say": "The API reads the row." },
+        { "edges": { "edge": "api->db", "back": true }, "say": "The row comes back." },
+        { "edges": { "edge": "browser->api", "back": true }, "say": "The API sends the user as JSON." }
+      ]
+    }
+  ]
+}
+```
+
+Render the spec:
+
+```console
+$ npx flowfig first.json
+figure: 3 boxes, 0 groups, 2 edges, 1 step, 4 messages
+first.svg — 8.8 kB
+```
+
+The command writes `first.svg`:
+
+![A browser loads a user through an API from a database](docs/first.svg)
+
+The SVG has no script and fetches no font. GitHub shows the SVG in a README, a PR or an issue. The SVG follows the light or dark
+color scheme of the reader.
+
+## Three forms
+
+| Form          | Spec           | Use it when                                                             |
+| ------------- | -------------- | ----------------------------------------------------------------------- |
+| The map       | (default)      | The reader must see where each part runs and which parts talk.          |
+| Map and rail  | `rail: true`   | The reader must see the parts, and also the order and payload of calls. |
+| The rail only | `rail: "only"` | The order of the messages is the point, and the map adds nothing to it. |
+
+The map:
+
+![A request that misses the cache, then hits the cache](docs/cached-request.svg)
+
+The map with the rail:
+
+![An order checkout: the map of the parts, and a rail of the messages under it](docs/checkout.svg)
+
+The rail draws one row for each message, with its payload.
+Hops in one beat share a parallel band. An `async` hop has a dashed arrow and an `async` tag.
+
+The rail only, from the same checkout spec:
+
+![The checkout messages as a rail, without the map](docs/checkout-rail-only.svg)
+
+Each SVG from the CLI carries its own spec. These commands made the rail-only figure from `docs/checkout.svg`:
+
+```bash
+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
+```
+
+## The spec
+
+A spec has a `layout`, `edges`, and optional `steps`. The full types have doc comments, so your editor shows each field. For the
+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 |
+
+### Groups
+
+`layout` is a group. A group holds boxes and other groups.
+
+| Field       | Meaning                                                         | Default                                             |
+| ----------- | --------------------------------------------------------------- | --------------------------------------------------- |
+| `children`  | The boxes and groups in the group, in order.                    | required                                            |
+| `id`        | The name that an edge can use to reach the whole group.         | none                                                |
+| `label`     | The title of the frame. Only a group with a label has a frame.  | none                                                |
+| `direction` | `"row"` puts the children side by side. `"column"` stacks them. | `"row"`                                             |
+| `gap`       | The space between the children in px.                           | column: 28; row: fits the widest label, at least 56 |
+| `align`     | `"start"`, `"center"` or `"end"`, across the direction.         | `"center"` (a column stretches)                     |
+
+### 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`    |
+
+### Steps
+
+Each step is one story. The player shows one tab for each step. With no steps, the figure is a still map.
+
+| Field     | Meaning                                               | Default  |
+| --------- | ----------------------------------------------------- | -------- |
+| `label`   | The tab title.                                        | required |
+| `flow`    | The beats, in play order.                             | required |
+| `caption` | The line under the figure while no beat has a `say`.  | none     |
+| `nodes`   | The ids of the boxes to highlight for the whole step. | none     |
+
+### Beats
+
+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)  |
+
+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.
+
+Content is an array of rows, or a React node in the player. A row is `{ text, tag, tone, meta, mark, mono }`. Only `text` is
+required. The tones are `blue` (the default), `purple`, `green`, `orange` and `gray`.
+
+### Figure options
+
+| Field      | Meaning                                                                   | Default  |
+| ---------- | ------------------------------------------------------------------------- | -------- |
+| `rail`     | `true` draws the rail under the map. `"only"` draws the rail alone.       | `false`  |
+| `speed`    | The time in ms for a packet to cross one edge.                            | 900      |
+| `theme`    | `{ accent, fg, muted, bg, surface, border, font }`. Each key is optional. | built-in |
+| `autoplay` | Start to play when the figure mounts. Only the React player reads it.     | `true`   |
+| `check`    | Run the check rules in the browser. Only the React player reads it.       | `false`  |
+
+## Check a figure
+
+`flowfig check` reads a spec and lists the faults. The input is `-` (stdin), a `.json` file, a `.ts` module or an SVG from the
+CLI. A `.ts` module needs a Node version that strips types, such as Node 22.18 or later.
+
+```console
+$ npx flowfig check docs/checkout.svg
+0 errors, 0 warnings
+figure: 5 boxes, 3 groups, 4 edges, 2 steps, 6 messages
+```
+
+The last line gives the counts of the parts of the figure. Compare the counts with the parts that you planned.
+
+| Rule                | Severity | What it finds                                                                |
+| ------------------- | -------- | ---------------------------------------------------------------------------- |
+| `unknown-id`        | error    | An edge, step or beat names a box or edge that does not exist.               |
+| `duplicate-id`      | error    | Two boxes, groups or edges have the same id.                                 |
+| `hidden-edge`       | error    | A `quiet` edge that no beat uses, so the figure never shows it.              |
+| `text-overflow`     | error    | Text that needs more width than its box has.                                 |
+| `edge-crosses-box`  | error    | An edge that goes through a box that is not one of its ends.                 |
+| `label-overlap`     | error    | Two edge labels overlap, or an edge label covers a box.                      |
+| `low-contrast`      | error    | A text and background pair below 4.5:1, in the light, dark or custom theme.  |
+| `empty-step`        | warning  | A step with no beats.                                                        |
+| `small-text`        | warning  | At the page width, the smallest text is below the minimum size.              |
+| `font-estimated`    | warning  | `theme.font` is set. The SVG check estimates text width for the system font. |
+| `color-not-checked` | warning  | A color that the check cannot read, so its contrast is not checked.          |
+
+| Option            | Effect                                                                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `--strict`        | Every warning becomes an error.                                                                            |
+| `--json`          | Print the findings as a JSON array, for scripts. Each finding has `rule`, `severity`, `ids` and `message`. |
+| `--width <px>`    | The page width for `small-text`. Default: 830.                                                             |
+| `--min-text <px>` | The smallest text size the reader must get. Default: 10.                                                   |
+
+The exit code is 0 with no errors, 1 with one or more errors, and 2 for bad use, such as a missing input, an unknown flag, or a `--width` value that is not a number.
+
+A render runs the same check first. If the check finds an error, the render writes nothing. `--no-check` skips the check.
+
+In React, `<Flow check />` runs the same rules on the layout that the browser drew. The player prints each fault with
+`console.warn`.
+
+## Use in React
+
+```tsx
+import { Flow, type FlowProps } from 'flowfig';
+import spec from './first.json';
+
+export const LoadUser = () => <Flow {...(spec as FlowProps)} />;
+```
+
+The player has these controls:
+
+- One tab for each step, with a progress line. A click on a tab starts that step.
+- A pause button, and a speed button that changes between 1× and 2×.
+- A full screen button. Esc closes full screen.
+- A hover on a box highlights its edges. With the rail, a click on a row starts that message, and a hover highlights its edge.
+
+The player props are the spec fields. `theme` sets the colors, `speed` sets the packet time, and `autoplay={false}` stops the
+auto start. `check` runs the check rules. If a figure is wider than its container, the player shrinks the figure to half size at
+most, then scrolls. If the reader asks for reduced motion, the player shows the last beat and does not move packets.
+
+The player has no dark theme of its own. For dark mode, set the `--fig-*` CSS variables on `.flowfig`:
+
+```css
+@media (prefers-color-scheme: dark) {
+  .flowfig {
+    --fig-accent: #1f78c8;
+    --fig-fg: #e3e3e3;
+    --fig-muted: #9aa0a6;
+    --fig-bg: #1b1b1d;
+    --fig-surface: #242526;
+    --fig-border: #3a3b3c;
+  }
+}
+```
+
+These are the built-in dark colors. `flowfig` exports them as `DARK`, and the light colors as `LIGHT`.
+
+## Use from Node
+
+`flowfig/svg` needs no React and no browser.
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs';
+import { check, toSvg } from 'flowfig/svg';
+
+const spec = JSON.parse(readFileSync('first.json', 'utf8'));
+for (const f of check(spec)) console.log(f.severity, f.rule, f.message);
+writeFileSync('first.svg', toSvg(spec));
+```
+
+- `toSvg(spec, options)` returns the SVG string. The options are `speed`, `padding` (default 24) and `theme`.
+- `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.
+
+`toSvg` does not put the spec in the SVG. Only the CLI adds the spec, which `--spec` reads back.
+
+## Use with your coding agent
+
+`npx flowfig init` writes flowfig instructions for the coding agents of a repo. The instructions tell the agent how to write a
+spec, check the spec, and render the SVG.
+
+```bash
+npx flowfig init            # the current directory
+npx flowfig init path/to/repo
+```
+
+On a terminal, `init` shows a picker. The picker selects the agents that the repo already uses. If it finds none, it selects
+`AGENTS.md`. Type the numbers to toggle agents, press Enter to write, or type `q` to quit.
+
+| Id         | Agent          | File                              | How                                  |
+| ---------- | -------------- | --------------------------------- | ------------------------------------ |
+| `claude`   | Claude Code    | `.claude/skills/figure/SKILL.md`  | whole file (a skill)                 |
+| `agents`   | AGENTS.md      | `AGENTS.md`                       | section (for Codex, Amp, Jules, ...) |
+| `cursor`   | Cursor         | `.cursor/rules/flowfig.mdc`       | whole file                           |
+| `copilot`  | GitHub Copilot | `.github/copilot-instructions.md` | section                              |
+| `gemini`   | Gemini CLI     | `GEMINI.md`                       | section                              |
+| `windsurf` | Windsurf       | `.windsurf/rules/flowfig.md`      | whole file                           |
+| `kiro`     | Kiro           | `.kiro/steering/flowfig.md`       | whole file                           |
+
+| Flag             | Effect                                                        |
+| ---------------- | ------------------------------------------------------------- |
+| `--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.     |
+| `--dry-run`      | Print what `init` would write, and write nothing.             |
+| `--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.
+
+A section sits between `<!-- flowfig:start -->` and `<!-- flowfig:end -->`. A second run replaces that section and keeps the rest
+of the file. A second run also replaces a whole file that `init` wrote. If a whole file exists and did not come from `init`,
+`init` skips the file. `init` also skips a section file that has a start marker and no end marker.
+
+`npx flowfig docs` prints the full guide as Markdown.
+
+## What flowfig does not draw
+
+flowfig draws parts, the messages between the parts, and their order. flowfig does not draw class diagrams, ER diagrams, Gantt
+charts, timelines with dates, charts of numbers or mind maps. Use Mermaid or a chart library for those.
+
+## How we measured
+
+We ran an evaluation before this release: 47 coding-agent runs, with Claude Sonnet as the agent. The runs covered 12 tasks in 5
+test repos: a TypeScript login API, a Python ETL pipeline, an order state machine, a 20-service platform and a mixed CLI repo.
+The agent ran without the flowfig instructions and with them. An Opus grader scored each run against an answer key.
+
+4 tasks were held out: they shaped no instruction. On the held-out tasks, 2 of 4 runs passed all 6 criteria. The other 2 passed
+4 of 6: one drew an edge from the wrong box, and one reply stated a runtime effect wrongly.
+
+A first draft of the instructions scored worse than no instructions: 5 of 8 faithful. We rewrote the instructions from the
+failures and tested them again. The "with" column comes from the version that we tested on all 8 tasks. The shipped instructions
+add two refinements: the scope of a repo with many flows, and each edge taken from the caller in the code. 9 more runs tested
+the two refinements on the tasks that still failed.
+
+The evaluation also found 3 faults in flowfig itself. We fixed all 3 before this release.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development
+
+```bash
+npm install
+npm run dev            # the gallery: each file in figures/ is one figure
+npm test               # build, then run the unit tests
+npm run typecheck
+npm run format:check
+```
+
+A change to the layout, the routing or the SVG output needs a unit test in `src/*.test.ts`.

package/dist/check.d.ts

@@ -0,0 +1,14 @@
+import { type FigTheme, type FlowProps } from './model.ts';
+import type { Finding, Scene } from './scene.ts';
+/** Ids that point nowhere, ids used twice, steps with nothing in them. The renderers skip these without a word. */
+export declare function checkSpec(fig: FlowProps): Finding[];
+export type CheckOptions = {
+    width?: number;
+    minText?: number;
+};
+/** Layout faults in what a renderer drew, and text that the target width shrinks below `minText`. */
+export declare function checkScene(scene: Scene, { width, minText }?: CheckOptions): Finding[];
+/** The WCAG contrast ratio of two colors, rounded to 2 places; null if either cannot be read. */
+export declare function contrast(a: string, b: string): number | null;
+/** Text the reader cannot read: each text and background pair, in light, dark and any custom theme, needs 4.5:1 (WCAG AA). */
+export declare function checkTheme(theme?: FigTheme): Finding[];

package/dist/check.js

@@ -0,0 +1,155 @@
+// 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 { textWidth } from './text.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) : []))];
+/** Ids that point nowhere, ids used twice, steps with nothing in them. The renderers skip these without a word. */
+export function checkSpec(fig) {
+    const out = [];
+    const boxIds = nodes(fig.layout).map((n) => n.id);
+    const groups = groupIds(fig.layout);
+    const edges = fig.edges.map(edgeId);
+    const twice = (kind, list) => new Set(list.filter((id, i) => list.indexOf(id) !== i)).forEach((id) => out.push(err('duplicate-id', [id], `two ${kind} have the id "${id}"`)));
+    twice('boxes', boxIds);
+    twice('groups', groups);
+    twice('edges', edges);
+    const known = new Set([...boxIds, ...groups]);
+    const knownEdges = new Set(edges);
+    fig.edges.forEach((e, i) => {
+        for (const end of [e.from, e.to])
+            if (!known.has(end))
+                out.push(err('unknown-id', [edges[i], end], `edge "${edges[i]}" names box "${end}", which does not exist`));
+    });
+    (fig.steps ?? []).forEach((s, si) => {
+        const where = `step ${si + 1} ("${str(s.label)}")`;
+        if (!s.flow.length)
+            out.push(warn('empty-step', [], `${where} has no beats`));
+        for (const id of s.nodes ?? [])
+            if (!known.has(id))
+                out.push(err('unknown-id', [id], `${where}: nodes names box "${id}", which does not exist`));
+        for (const b of s.flow.map(toBeat)) {
+            for (const h of b.hops)
+                if (!knownEdges.has(h.edge))
+                    out.push(err('unknown-id', [h.edge], `${where} moves along edge "${h.edge}", which does not exist`));
+            for (const id of [...Object.keys(b.show ?? {}), ...(b.light ?? [])])
+                if (!known.has(id))
+                    out.push(err('unknown-id', [id], `${where}: show or light names box "${id}", which does not exist`));
+        }
+    });
+    const used = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => h.edge))));
+    fig.edges.forEach((e, i) => {
+        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`));
+    });
+    return out;
+}
+/** A point on the cubic Bézier at `t`. */
+const at = ([p0, p1, p2, p3], t) => {
+    const u = 1 - t;
+    const [a, b, c, d] = [u * u * u, 3 * u * u * t, 3 * u * t * t, t * t * t];
+    return { x: a * p0.x + b * p1.x + c * p2.x + d * p3.x, y: a * p0.y + b * p1.y + c * p2.y + d * p3.y };
+};
+// The margins keep a touch from counting: an edge leaves along a border, and pills sit edge to edge.
+const inside = (p, r, pad) => p.x > r.x + pad && p.x < r.x + r.w - pad && p.y > r.y + pad && p.y < r.y + r.h - pad;
+const overlap = (a, b, pad) => a.x + pad < b.x + b.w - pad && b.x + pad < a.x + a.w - pad && a.y + pad < b.y + b.h - pad && b.y + pad < a.y + a.h - pad;
+const px = (n) => Math.round(n * 10) / 10;
+/** Layout faults in what a renderer drew, and text that the target width shrinks below `minText`. */
+export function checkScene(scene, { width = 830, minText = 10 } = {}) {
+    const out = [];
+    for (const b of scene.boxes)
+        for (const t of b.texts) {
+            const need = t.need ?? textWidth(t.text, t.fontSize, t.mono);
+            if (need > t.room + 0.5)
+                out.push(err('text-overflow', [b.id], `box "${b.id}": "${t.text}" needs ${Math.ceil(need)} px, has ${Math.floor(t.room)} px`));
+        }
+    for (const e of scene.edges) {
+        const pts = Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+        for (const b of scene.boxes)
+            if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, 2)))
+                out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}"`));
+    }
+    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))
+                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))
+                out.push(err('label-overlap', [e.id, b.id], `the label of edge "${e.id}" covers box "${b.id}"`));
+    });
+    const shown = scene.minFont * Math.min(1, width / scene.width);
+    if (shown < minText)
+        out.push(warn('small-text', [], `at ${width} px the smallest text is ${px(shown)} px (minimum ${minText} px)`));
+    return out;
+}
+/** Red, green and blue from a hex, rgb() or hsl() color; null for a CSS variable or a named color. */
+function rgb(color) {
+    const s = color.trim().toLowerCase();
+    let m = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
+    if (m) {
+        const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+        return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    }
+    m = s.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/);
+    if (m)
+        return [+m[1], +m[2], +m[3]];
+    m = s.match(/^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/);
+    if (m) {
+        const [h, sat, l] = [+m[1] / 360, +m[2] / 100, +m[3] / 100];
+        const f = (n) => {
+            const k = (n + h * 12) % 12;
+            return 255 * (l - sat * Math.min(l, 1 - l) * Math.max(-1, Math.min(k - 3, 9 - k, 1)));
+        };
+        return [f(0), f(8), f(4)];
+    }
+    return null;
+}
+const lum = (c) => c
+    .map((v) => v / 255)
+    .map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+    .reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0);
+/** The WCAG contrast ratio of two colors, rounded to 2 places; null if either cannot be read. */
+export function contrast(a, b) {
+    const [x, y] = [rgb(a), rgb(b)];
+    if (!x || !y)
+        return null;
+    const [hi, lo] = [lum(x), lum(y)].sort((p, q) => q - p);
+    return Math.round(((hi + 0.05) / (lo + 0.05)) * 100) / 100;
+}
+const PAIRS = [
+    ['fg', 'bg'],
+    ['muted', 'bg'],
+    ['fg', 'surface'],
+    ['text', 'accent'],
+];
+/** 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 = [];
+    if (theme.font && theme.font !== 'inherit')
+        out.push(warn('font-estimated', [], `theme.font is "${theme.font}"; the SVG check estimates text width for the system font`));
+    const custom = Object.keys(theme).some((k) => k !== 'font');
+    const sets = [
+        ['light', LIGHT],
+        ['dark', DARK],
+    ];
+    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 [fg, bg] of PAIRS) {
+            const a = fg === 'text' ? ON_ACCENT : t[fg];
+            const r = contrast(a, t[bg]);
+            if (r == null) {
+                for (const c of [a, t[bg]])
+                    if (!rgb(c))
+                        unread.add(c);
+            }
+            else if (r < 4.5)
+                out.push(err('low-contrast', [], `${name} theme: ${fg} on ${bg} 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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};