flowfig 0.9.0 → 0.11.0

package/README.md

@@ -65,11 +65,14 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.9.0
+      - uses: iamalvisng/flowfig@v0.11.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
+          # coverage: true # also fail the job if a figure is stale
 ```
 
+Set `coverage: true` to run `flowfig coverage --strict` after the comment. The job then fails if a figure is stale or fails verify.
+
 ## Use it
 
 Set up your repo:
@@ -117,7 +120,7 @@ the run.
 
 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 23 rules. It finds ids that point nowhere, text wider than its box,
+2. **flowfig checks the spec.** `flowfig check` has 26 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
@@ -167,7 +170,7 @@ The options are in [Open and share a figure](#open-and-share-a-figure).
 | ------------------------------ | --------------------------------- | ------------------------------------ | ---------------- |
 | Made by an agent from the code | Yes, with the `init` instructions | Yes, as Mermaid text                 | No               |
 | Linked to the code             | Yes, `verify` fails in CI         | No                                   | No               |
-| Checked for faults             | Yes, 23 rules in `flowfig check`  | Syntax errors only                   | No               |
+| Checked for faults             | Yes, 26 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 |
@@ -185,6 +188,8 @@ The options are in [Open and share a figure](#open-and-share-a-figure).
 - [Verify in CI](#verify-in-ci)
 - [Trace the calls of a function](#trace-the-calls-of-a-function)
 - [Find stale figures](#find-stale-figures)
+- [One page for all figures](#one-page-for-all-figures)
+- [Convert Mermaid](#convert-mermaid)
 - [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
@@ -242,7 +247,8 @@ figure: 3 boxes, 0 groups, 2 edges, 1 step, 4 messages
 browser -> api: GET /user
 api -> db: read the user
 step "Load a user": 4 hops
-first.svg — 9.7 kB
+alt: Flow figure: Browser, API, Database. Steps: Load a user.
+first.svg — 10.1 kB
 ```
 
 The render prints the check result, the counts, one line per edge and one line per step. Read these lines to check the figure
@@ -266,8 +272,12 @@ npx flowfig --spec docs/checkout.svg > checkout.json   # print the spec in the S
 npx flowfig checkout.json docs/checkout-rail-only.svg
 npx flowfig verify docs/checkout.svg                    # check each source and each edge against the code
 npx flowfig diff old.svg docs/checkout.svg              # list what changed in the spec
+npx flowfig diff old.svg docs/checkout.svg --svg diff.svg   # draw the change in one figure
 ```
 
+The diff SVG is a still figure. Green marks an added box or edge, red and dashed marks a removed one, and orange marks a changed one.
+The diff SVG has no spec. The Action and `coverage` skip it. `verify` and `--spec` report that it has no spec.
+
 ## 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
@@ -282,6 +292,7 @@ full reference, run `npx flowfig docs`.
 | `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                                |
+| `detail` | A more detailed figure: the SVG path from the repo root. `flowfig atlas` links the box to 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 |
@@ -301,18 +312,49 @@ full reference, run `npx flowfig docs`.
 | `direction` | `"row"` puts the children side by side. `"column"` stacks them.                                          | `"row"`                                             |
 | `gap`       | The smallest space between the children in px. It grows to fit the labels of edges that cross the group. | column: 28; row: fits the widest label, at least 56 |
 | `align`     | `"start"`, `"center"` or `"end"`, across the direction.                                                  | `"center"` (a column stretches)                     |
+| `auto`      | On the root layout: `true` makes flowfig place the boxes. See [Automatic layout](#automatic-layout).     | off                                                 |
+
+### Automatic layout
+
+Set `"auto": true` on the root layout and list the boxes. flowfig places them in ranks, in the direction of the edges.
+Use it when you do not want to plan rows and columns, or when `check` reports an edge through a box.
+
+```json
+{
+  "layout": {
+    "auto": true,
+    "children": [
+      { "id": "api", "label": "API" },
+      { "id": "queue", "label": "Queue", "shape": "store" },
+      { "label": "Workers", "children": [{ "id": "w", "label": "Worker" }] }
+    ]
+  },
+  "edges": [
+    { "from": "api", "to": "queue", "label": "enqueue" },
+    { "from": "queue", "to": "w", "label": "pull" }
+  ]
+}
+```
+
+Render the spec with `npx flowfig spec.json docs/auto-layout.svg`. This figure has 9 boxes, 1 frame, 1 decision, 1 store and 2 steps:
+
+![Flow figure: Shopper, Web shop, In stock?, Order, Payment, Shipping, Orders, Email, Back order. Steps: Item in stock, Item sold out.](docs/auto-layout.svg)
+
+A group with a `label` or an `id` stays together as one frame. flowfig removes a group with neither, with its `direction`, `gap`
+and `align`. flowfig ignores `around` on the edges. A `direction` on the root forces `"row"` or `"column"`. `lanes` and
+`timeline` figures ignore `auto`.
 
 ### 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`    |
-| `source` | The code this edge draws: `path` or `path#symbol`. `flowfig verify` checks it. | none       |
+| 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"`, `"below"`, `"left"` or `"right"` routes the edge around the boxes between, on that side. | 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
 
@@ -357,6 +399,9 @@ required. The tones are `blue` (the default), `purple`, `green`, `orange` and `g
 | `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`  |
 
+A figure is as wide as its boxes need, and at least 320 px. The step captions wrap at the figure
+width, so a narrow figure fits a phone screen at full size. A rail-only figure is at least 560 px.
+
 ## 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
@@ -370,33 +415,36 @@ 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.
 
-`flowfig check` has 23 rules: 11 errors and 12 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.                                 |
-| `plain-text`                | warning  | Text with a code name, a filler word, or a `say` or caption over 20 words.                          |
+`flowfig check` has 26 rules: 11 errors and 15 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`.                                                                            |
+| `bad-detail`                | warning  | A `detail` that is not a relative path that ends in `.svg`.                                                                |
+| `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.                                                                        |
+| `long-edge`                 | warning  | An edge at least 600 px long that is 1.6 times or more the straight distance between its ends.                             |
+| `timeline-dependency-order` | warning  | In a timeline, an item does not start after the item that it depends on ends. An item may start on the day of a milestone. |
+| `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.                                                        |
+| `plain-text`                | warning  | Text with a code name, a filler word, or a `say` or caption over 20 words.                                                 |
+| `auto-ignored`              | warning  | `auto` with `lanes` or `timeline`, `auto` on a nested group, or `around` on an edge with `auto`.                           |
 
 | Option            | Effect                                                                                                     |
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -455,6 +503,8 @@ docs/login.svg: 7 of 7 boxes defined; edges: 9 found, 0 not found, 1 unsure, 1 n
 - unsure: `verify` cannot decide, for example when a receiver has no declared type. `verify` lists it with the reason. It never fails CI.
 - not checked: the edge has no `source`, or the language is not supported.
 
+`verify` also checks `detail`. If the file is missing or has no figure spec, `verify` warns with `missing-detail`. `--strict` makes it an error.
+
 A method source is `path#Owner.name`. An edge `source` names the function that makes the call.
 
 `via` on an edge names the route, queue, topic, table, file or key that both sides use. For a `via` edge, found means that the caller code and the callee file both use that token. It does not prove that a handler serves it.
@@ -480,7 +530,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.9.0
+      - uses: iamalvisng/flowfig@v0.11.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -491,25 +541,44 @@ jobs:
 before it writes a figure. Then the agent reads only the lines that the trace names. Each edge passes the same check as
 `verify`.
 
+`src/login.ts`:
+
+```ts
+import { verifyPassword } from './password.ts';
+import { findUser } from './users.ts';
+
+export function login(name: string, password: string) {
+  const user = findUser(name);
+  return verifyPassword(user, password);
+}
+```
+
+`src/password.ts`:
+
+```ts
+export function verifyPassword(user: { hash: string }, password: string) {
+  return user.hash === password.split('').reverse().join('');
+}
+```
+
+`src/users.ts`:
+
+```ts
+export function findUser(name: string) {
+  return { name, hash: 'drowssap' };
+}
+```
+
 ```console
-$ npx flowfig trace src/verify.ts#verify
-src/verify.ts#verify -> src/verify.ts#verifyReport          src/verify.ts:104
-src/verify.ts#verifyReport -> src/verify.ts#emptyCoverage   src/verify.ts:48
-src/verify.ts#verifyReport -> src/source.ts#links           src/verify.ts:49
-src/verify.ts#verifyReport -> src/code.ts#outside           src/verify.ts:58
-src/verify.ts#verifyReport -> src/code.ts#codeFile          src/verify.ts:65
-src/verify.ts#verifyReport -> src/code.ts#isDefined         src/verify.ts:67
-src/verify.ts#verifyReport -> src/verify.ts#escape          src/verify.ts:69
-src/verify.ts#verifyReport -> src/verify.ts#hasHeading      src/verify.ts:70
-src/verify.ts#verifyReport -> src/model.ts#nodes            src/verify.ts:79
-src/verify.ts#verifyReport -> src/edges.ts#edgeResult       src/verify.ts:81
-src/verify.ts#verifyReport -> src/model.ts#edgeId           src/verify.ts:91
-src/verify.ts#verifyReport -> src/model.ts#toBeat           src/verify.ts:95
-stop    depth 2: 11 symbols not followed
-summary: 13 symbols, 12 found, 0 unsure, 0 open, 4 calls outside the repo, 0.1 s
-```
-
-- An edge line gives the caller, the callee, and the file and line of the call.
+$ npx flowfig trace src/login.ts#login
+src/login.ts#login
+  5  src/users.ts#findUser
+  6  src/password.ts#verifyPassword
+summary: 3 symbols, 2 found, 0 unsure, 0 open, 1 call outside the repo, 0.0 s
+```
+
+- A header line gives a caller as `file#symbol`. Each call line under it gives the line of the call, then the callee.
+  The call is in the file of the caller. A callee in the same file shows only its symbol.
 - `unsure`: trace cannot name the target. An example is a call of a parameter.
 - `open`: the target is a name in a string, for example a route table entry. Read that line yourself.
 - `stop`: the trace reached `--depth` or `--max`. The line gives the number of functions that it did not follow.
@@ -560,6 +629,8 @@ prints one line that says so.
 
 A figure covers a code file if one of its links names that file. With `--entries`, `coverage` lists each matched code
 file that no figure covers. With no `--entries`, it prints one count line for each top folder.
+`coverage` does not count test files as code: `*.test.*`, `*.spec.*`, `__tests__/`, `test_*.py`, `*_test.py`, `*_test.go`,
+`*Test.java`, `*Tests.java`, `*Test.cs`, `*Tests.cs`, and files under `tests/` or `src/test/`. An entry that `--entries` names in full still counts.
 
 | Option             | Meaning                                                       | Default            |
 | ------------------ | ------------------------------------------------------------- | ------------------ |
@@ -571,6 +642,180 @@ file that no figure covers. With no `--entries`, it prints one count line for ea
 
 `coverage` skips `node_modules`, `dist` and each folder with a name that starts with a dot.
 
+## One page for all figures
+
+`flowfig atlas` writes one web page for each figure, and an index page. A box can link to a more detailed figure with
+`detail`. The path starts at the repo root, as `source` does.
+
+`docs/system.svg`:
+
+```json
+{
+  "layout": {
+    "children": [
+      { "id": "up", "label": "Whole system", "detail": "docs/flows/orders.svg" },
+      { "id": "db", "label": "Orders table" }
+    ]
+  },
+  "edges": []
+}
+```
+
+`docs/flows/orders.svg`:
+
+```json
+{
+  "layout": {
+    "children": [
+      { "id": "web", "label": "Web app" },
+      { "id": "orders", "label": "Order service", "detail": "docs/system.svg" }
+    ]
+  },
+  "edges": []
+}
+```
+
+`docs/system.svg` links down to the order flow. `docs/flows/orders.svg` links back up.
+
+```console
+$ npx flowfig atlas
+/path/to/repo/atlas/index.html — 2 figure pages
+```
+
+The command prints the full path of `index.html`.
+
+| Option             | Meaning                                                       | Default            |
+| ------------------ | ------------------------------------------------------------- | ------------------ |
+| `--figures <glob>` | The SVG files to read. Only an SVG with a figure spec counts. | `**/*.svg`         |
+| `--root <dir>`     | The repo root. `detail` paths start here.                     | the current folder |
+| `--out <dir>`      | The folder to write.                                          | `atlas`            |
+| `--open`           | Open `index.html` in the default browser.                     | off                |
+
+The command writes `index.html`, one `.html` page for each figure, and an empty `.nojekyll` file. It deletes nothing. If a file of the same name exists and the atlas did not write it, the command writes nothing and exits with 2.
+All links are relative, so the pages work from a file, a sub-path or any file host. The exit code is 0 when the site is
+written, whatever the health of the figures. It is 1 when no figure matches, and 2 for a bad flag.
+
+The index lists each figure with its health from `coverage`: `ok`, `stale`, `fail` or `none`. A figure with a bad spec
+has no page. Its row shows `fail` and the error.
+
+Each figure page has these parts, in this order:
+
+1. A link "All figures".
+2. The figure path and its health.
+3. The figure.
+4. A "Details" list with one link for each box that has `detail`.
+5. The transcript of the figure.
+
+A link works in these places:
+
+- In the README, an SVG is an image, so a box has no link. The README render does not change.
+- On an atlas page, a click on a box opens the page of its `detail` figure. The mouse is the only way to use this link.
+- The "Details" list has the same links with names. Use it with the keyboard and a screen reader.
+- If the target figure is not in the atlas, the box has no link. The list row says "not in the atlas".
+
+The atlas draws each spec with the installed flowfig and the default options. A page can differ from the committed SVG
+if you drew that SVG with `--width` or `--min-text`. A figure that you remove keeps its old page in `--out`.
+
+To publish the pages on GitHub Pages, run `npx flowfig atlas --out docs/atlas` and commit the result. Then set Pages to
+"Deploy from a branch" with the folder `/docs`.
+
+## Convert Mermaid
+
+`flowfig from-mermaid` turns a Mermaid flowchart, sequence diagram, state diagram or `gantt` into a flowfig spec. The converter uses no model.
+Then `check` and `verify` can test the figure.
+
+```console
+$ cat login.mmd
+sequenceDiagram
+    participant W as Web app
+    W->>A: POST /login
+    A-->>W: 200 session cookie
+    A-)Q: user.logged_in
+$ npx flowfig from-mermaid login.mmd > login.json
+$ npx flowfig login.json login.svg
+```
+
+The input is a `.mmd` file with one diagram, or a Markdown file. In a Markdown file, each fenced block with the language
+`mermaid` is one diagram. `-` reads one diagram from stdin. With one diagram, the command prints the spec. With
+`--out <dir>`, the command writes one JSON file for each diagram, such as `docs-1.json` and `docs-2.json`.
+
+The command exits 1 if a diagram has a line that the converter does not read. It prints `<file>:<line>: <reason>` for each
+line, and writes no spec for that diagram. The command never guesses.
+
+This flowchart has a decision, a subgraph and a store:
+
+```mermaid
+flowchart TD
+    A([Visitor]) --> B[Sign-up form]
+    B --> C{Email valid?}
+    C -->|no| X[Show error]
+    C -->|yes| D
+    subgraph auth [Account service]
+        D[Create account] --> E[Hash password]
+    end
+    E --> F[(Users)]
+    E --> G[Welcome email]
+```
+
+`npx flowfig from-mermaid signup.mmd > signup.json` converts it. `npx flowfig signup.json docs/from-mermaid.svg` renders it:
+
+![Flow figure: Visitor, Sign-up form, Email valid?, Show error, Create account, Hash password, Users, Welcome email.](docs/from-mermaid.svg)
+
+A flowchart (`flowchart` or `graph`) becomes a still map with automatic layout:
+
+- Nodes: `A`, `A[text]`, `A(text)`, `A([text])`, `A((text))`, `A{text}` (a decision) and `A[(text)]` (a store). The text can
+  have quotes. `<br>` becomes a space. `#quot;`, `#amp;`, `#lt;`, `#gt;`, `#apos;`, `#nbsp;` and `#NN;` (a decimal code)
+  become their characters.
+- Links: `-->`, `-.->`, `==>`, with a label as `-->|text|` or `-- text -->`. Chains (`A --> B --> C`) and `&`
+  (`A & B --> C`) are read.
+- `subgraph id`, `subgraph id [title]`, `subgraph id["title"]` or `subgraph title` ... `end` becomes a group with a frame. A subgraph with no
+  node is dropped.
+- `classDef`, `class`, `style`, `linkStyle`, `click`, `direction`, `:::class` and `%%` comments are ignored.
+- In all four diagram types, `accTitle:`, `accDescr:` and `accDescr { ... }` are ignored.
+
+A sequence diagram becomes a rail (`rail: "only"`):
+
+- Each `participant` or `actor` is a box. A participant that first shows in a message is a box too.
+- Each pair of participants gets one edge. Each message is one hop on that edge, with its text in `data`.
+- A message in the other direction of the edge is a hop with `back: true`. `-)` gives `async: true`.
+- With no `alt`, the figure has one step with all the messages.
+- Each `alt` or `else` branch becomes one step. The step has the messages before the `alt`, the messages of that branch, and
+  the messages after the `end`. The step label is the branch condition.
+- `loop`, `opt`, `par`, `and` and `rect` lines are ignored. Their messages stay in order in each step.
+- `activate`, `deactivate`, `+` and `-`, `Note` and `autonumber` are ignored.
+
+A state diagram (`stateDiagram` or `stateDiagram-v2`) becomes a still map with automatic layout:
+
+- Each state is a box. `state "Long name" as A` sets the label. `A : text` puts the text under the label, as Mermaid does.
+- `A --> B` and `A --> B : text` become an edge with a label.
+- `[*] --> A` at the top level gives A `mark: "start"`. `A --> [*]` at the top level gives A `mark: "end"`.
+- `state A { ... }` becomes a group with a frame. A `[*]` in it gives no edge and no mark.
+- `state A <<choice>>` becomes a decision. Its label is its id.
+- `direction`, `classDef`, `class`, `%%` comments, `note` and `hide empty description` are ignored.
+
+A `gantt` becomes a timeline (`timeline: true`):
+
+- Each `section` is a track. Each task is a box in its track. A task with no id gets the id `task-1`, `task-2` and so on.
+- A task can have a start date or `after <id>`, and an end date or a duration in days (`10d`) or weeks (`2w`).
+  A task with only a duration starts when the task above it ends.
+- Mermaid reads an end date as the start of that day. So the box `to` is the day before the end date.
+- `after a b` starts the task when the last of `a` and `b` ends. Each id gives an edge to the task.
+- `milestone` with `0d` gives a box with only `from`. `crit` gives `tone: "red"`. `done` and `active` are ignored.
+- `title`, `axisFormat`, `tickInterval`, `todayMarker`, `weekday` and `click` are ignored. The today line uses the flowfig default.
+
+Limits:
+
+- `RL` reads as `LR`, and `BT` reads as `TB`. The automatic layout sets the order of the boxes.
+- `-.->` and `==>` give a plain edge. flowfig has no dotted or thick edge.
+- A link with no arrow (`---`, `-.-`, `===`) is an error. Use `-->` to give it a direction.
+- Other node shapes, Markdown strings, `<-->`, `--o`, `--x`, `-x` and a message to the same participant are errors.
+- A second `alt` and an `alt` inside an `alt` are errors.
+- In a state diagram, `<<fork>>`, `<<join>>`, a concurrent region (`--`), `:::class` and a transition to the same state
+  are errors. A `[*]` on a composite state, a description on a composite state and a label on a `[*]` transition are errors too.
+- A state with a start and an end transition is an error, because a box has one mark.
+- In a `gantt`, a `dateFormat` other than `YYYY-MM-DD`, `excludes`, `weekend`, `inclusiveEndDates`, `until`, a duration in
+  hours and a milestone with a duration are errors. These change the dates, and the converter never guesses a date.
+
 ## MCP server
 
 `npx flowfig mcp` serves the tools `docs`, `check`, `render`, `verify` and `diff` over stdio, for an agent with no shell.
@@ -600,12 +845,15 @@ 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.
+- The step tabs take the Left, Right, Home and End keys.
 - 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.
 - A hover on a box, an edge or a rail row with a `source` shows the `source`. The SVG shows it as a tooltip too.
 
 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.
+auto start. `check` runs the check rules. If a figure is wider than its container, the player changes the figure to fit.
+In a box under 600 px, the player keeps reader text at 11 px or more. If the map does not fit, the player draws the map as a column.
+In a box of 600 px or more, the player folds the map only when text would fall under 9 px.
+A lanes map or a timeline map stops at that size and scrolls sideways in its pane. 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`:
 

package/dist/atlas.d.ts

@@ -0,0 +1,6 @@
+export type AtlasOptions = {
+    root?: string;
+    figures?: string;
+};
+export declare function atlasFiles({ root, figures }?: AtlasOptions): Map<string, string>;
+export declare function runAtlas(argv: string[]): Promise<number>;

package/dist/atlas.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
+import { coverageLines, coverageReport } from './coverage.js';
+import { loadSpec, specOf } from './load.js';
+import { altText, nodes, str } from './model.js';
+import { openFile } from './open.js';
+import { esc, pageHtml } from './page.js';
+import { toSvg } from './svg.js';
+const USAGE = 'usage: flowfig atlas [--figures <glob>] [--root <dir>] [--out <dir>] [--open]';
+const CSS = `body { font: 16px/1.5 system-ui, sans-serif; margin: 0 auto; max-width: 960px; padding: 16px }
+table { border-collapse: collapse; width: 100% }
+td, th { text-align: left; padding: 6px 10px; border-bottom: 1px solid color-mix(in srgb, CanvasText 20%, transparent) }
+strong[data-state] { padding: 1px 8px; border-radius: 4px; border: 1px solid currentColor; font-size: 14px }
+strong[data-state="ok"] { color: light-dark(#116329, #7ee787) }
+strong[data-state="stale"] { color: light-dark(#8a5a00, #e3b341) }
+strong[data-state="fail"] { color: light-dark(#b42318, #ff7b72) }
+strong[data-state="none"] { color: GrayText }`;
+const badge = (f) => `<strong data-state="${f.state}">${f.state}</strong>`;
+const pageOf = (figure) => {
+    const page = figure.replace(/\.svg$/, '.html');
+    return page === 'index.html' ? 'index.figure.html' : page;
+};
+const MARK = '<meta name="generator" content="flowfig atlas">';
+const url = (path) => path.split('/').map(encodeURIComponent).join('/');
+const hrefTo = (from, to) => url(posix.relative(posix.dirname(from), to));
+export function atlasFiles({ root = process.cwd(), figures } = {}) {
+    const report = coverageReport({ root, figures });
+    const rows = report.figures.sort((a, b) => a.figure.localeCompare(b.figure));
+    if (!rows.length)
+        return new Map();
+    const specs = new Map();
+    for (const { figure } of rows) {
+        try {
+            specs.set(figure, loadSpec(JSON.parse(specOf(readFileSync(resolve(root, figure), 'utf8'), figure)), figure));
+        }
+        catch { }
+    }
+    const files = new Map();
+    const shell = (title, body) => `<!doctype html>\n<meta charset="utf-8">\n${MARK}\n<meta name="viewport" content="width=device-width, initial-scale=1">\n<title>${esc(title)}</title>\n<style>\n:root { color-scheme: light dark }\n${CSS}\n</style>\n${body}\n`;
+    for (const f of rows) {
+        const spec = specs.get(f.figure);
+        if (!spec)
+            continue;
+        const page = pageOf(f.figure);
+        const targets = nodes(spec.layout).flatMap((n) => {
+            const to = typeof n.detail === 'string' ? posix.normalize(n.detail) : '';
+            return to && specs.has(to) ? [{ n, to }] : [];
+        });
+        const hrefs = new Map(targets.map(({ n, to }) => [n.id, hrefTo(page, pageOf(to))]));
+        const svg = toSvg(spec, { links: Object.fromEntries(hrefs) });
+        const details = nodes(spec.layout)
+            .filter((n) => typeof n.detail === 'string')
+            .map((n) => {
+            const name = esc(str(n.label) || n.id);
+            const href = hrefs.get(n.id);
+            return `<li>${name}: ${href == null ? `${esc(n.detail)} (not in the atlas)` : `<a href="${esc(href)}">${esc(n.detail)}</a>`}</li>`;
+        });
+        const { title, desc } = altText(spec);
+        const before = `<style>\n${CSS}\n</style>\n<main>\n<p><a href="${esc(hrefTo(page, 'index.html'))}">All figures</a></p>\n` +
+            `<h1>${esc(f.figure)}</h1>\n<p>${badge(f)} ${esc(f.detail)}</p>\n`;
+        const after = (details.length ? `\n<h2>Details</h2>\n<ul>\n${details.join('\n')}\n</ul>` : '') +
+            `\n<details><summary>Transcript</summary><pre style="white-space: pre-wrap">${esc(desc)}</pre></details>\n</main>`;
+        files.set(page, pageHtml(svg, `${title} (${f.figure})`, before, after, `${MARK}\n`));
+    }
+    const body = rows
+        .map((f) => {
+        const spec = specs.get(f.figure);
+        const name = spec ? `<a href="${esc(url(pageOf(f.figure)))}">${esc(f.figure)}</a>` : esc(f.figure);
+        return `<tr><td>${name}</td><td>${badge(f)}</td><td>${esc(f.detail)}</td><td>${spec ? esc(altText(spec).title) : ''}</td></tr>`;
+    })
+        .join('\n');
+    files.set('index.html', shell('Figures', `<main>\n<h1>Figures</h1>\n<p>${esc(coverageLines(report).at(-1))}</p>\n<table>\n<tr><th>Figure</th><th>Health</th><th>Detail</th><th>Title</th></tr>\n${body}\n</table>\n</main>`));
+    files.set('.nojekyll', '');
+    return files;
+}
+export async function runAtlas(argv) {
+    const fail = (message, code) => (console.error(message), code);
+    const args = [...argv];
+    const open = args.includes('--open');
+    if (open)
+        args.splice(args.indexOf('--open'), 1);
+    const opts = {};
+    for (const name of ['--figures', '--root', '--out']) {
+        const at = args.indexOf(name);
+        if (at === -1)
+            continue;
+        const value = args.splice(at, 2)[1];
+        if (!value || value.startsWith('-'))
+            return fail(`${name} needs a value`, 2);
+        opts[name] = value;
+    }
+    if (args.length)
+        return fail(args[0].startsWith('-') ? `unknown flag ${args[0]}` : USAGE, 2);
+    const root = resolve(opts['--root'] ?? '.');
+    if (!existsSync(root))
+        return fail(`${root}: the folder does not exist`, 2);
+    const files = atlasFiles({ root, figures: opts['--figures'] });
+    if (!files.size)
+        return fail('no figure SVG matches', 1);
+    const out = resolve(opts['--out'] ?? 'atlas');
+    const mine = [...files.keys()].filter((p) => p !== '.nojekyll');
+    const foreign = mine.find((p) => existsSync(join(out, p)) && !readFileSync(join(out, p), 'utf8').includes(MARK));
+    if (foreign)
+        return fail(`${join(out, foreign)}: the file exists and flowfig atlas did not write it; nothing was written`, 2);
+    for (const [path, text] of files) {
+        if (!text && existsSync(join(out, path)))
+            continue;
+        mkdirSync(dirname(join(out, path)), { recursive: true });
+        writeFileSync(join(out, path), text);
+    }
+    const index = join(out, 'index.html');
+    console.log(`${index} — ${files.size - 2} figure page${files.size === 3 ? '' : 's'}`);
+    if (open) {
+        try {
+            await openFile(index);
+        }
+        catch (e) {
+            return fail(`open: ${e.message}`, 1);
+        }
+    }
+    return 0;
+}

package/dist/auto.d.ts

@@ -0,0 +1,3 @@
+import { type FigEdge, type FlowProps } from './model.ts';
+export declare const rowBreaks: WeakSet<FigEdge>;
+export declare function autoLayout(spec: FlowProps): FlowProps;