flowfig 0.5.0 → 0.7.0

package/README.md

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

package/dist/browser.d.ts

@@ -2,7 +2,7 @@ export type Found = {
     path: string | null;
     checked: string[];
 };
-/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+/** The first capture browser that exists. `CHROME_PATH` wins. */
 export declare function findBrowser(o: {
     platform: NodeJS.Platform;
     env: Record<string, string | undefined>;
@@ -12,7 +12,6 @@ export type Cdp = {
     send(method: string, params?: object, sessionId?: string, timeoutMs?: number): Promise<any>;
     once(event: string, sessionId?: string, timeoutMs?: number): Promise<any>;
 };
-/** Start the capture browser in headless mode with a CDP pipe. `close` stops it and never throws. */
 export declare function launch(path: string, profile: string, timeoutMs?: number): Promise<{
     cdp: Cdp;
     close: () => Promise<void>;
@@ -23,7 +22,6 @@ export type Capture = {
     height: number;
     loopMs: number;
 };
-/** Set the page, pause the animations and take one PNG per frame time. */
 export declare function captureFrames(cdp: Cdp, html: string, o: {
     width: number;
     height: number;