flowfig 0.11.0 → 0.12.0

package/README.md

@@ -65,7 +65,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.11.0
+      - uses: iamalvisng/flowfig@v0.12.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
           # coverage: true # also fail the job if a figure is stale
@@ -120,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 26 rules. It finds ids that point nowhere, text wider than its box,
+2. **flowfig checks the spec.** `flowfig check` has 29 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
@@ -128,6 +128,8 @@ the run.
 
 ## Forms
 
+To explain a flow one moment at a time in a web page, see [Explain a flow in a web page](#explain-a-flow-in-a-web-page).
+
 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)
@@ -156,12 +158,16 @@ A state lifecycle marks the first state with `mark: "start"` and each final stat
 
 ![An order status lifecycle with a start dot and two end rings](docs/order-status.svg)
 
+A box with inside parts opens to show them, down to 3 levels. See [Inside a box](#inside-a-box).
+
 ## 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.
 
+`npx flowfig frames figure.svg` writes one PNG sheet of the key frames, so a coding agent can read the motion in one image.
+
 The options are in [Open and share a figure](#open-and-share-a-figure).
 
 ## flowfig, Mermaid and a hand-drawn image
@@ -170,7 +176,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, 26 rules in `flowfig check`  | Syntax errors only                   | No               |
+| Checked for faults             | Yes, 29 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 |
@@ -193,6 +199,7 @@ The options are in [Open and share a figure](#open-and-share-a-figure).
 - [MCP server](#mcp-server)
 - [Use in React](#use-in-react)
 - [Use from Node](#use-from-node)
+- [Explain a flow in a web page](#explain-a-flow-in-a-web-page)
 - [Use with your coding agent](#use-with-your-coding-agent)
 - [What flowfig does not draw](#what-flowfig-does-not-draw)
 - [License](#license)
@@ -291,6 +298,8 @@ full reference, run `npx flowfig docs`.
 | `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"`                             |
+| `check`  | The question on the gate in the guide world. The labels of the edges out of the box are the answers.      | the label, for a `decision` box     |
+| `done`   | The state after the box, such as "Oil in stock". The ending tags of the guide world show it.              | the label                           |
 | `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                                |
@@ -299,6 +308,7 @@ full reference, run `npx flowfig docs`.
 | `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                                |
+| `look`   | One of the 12 pictures that the guide world draws for this box.                                           | none                                |
 
 ### Groups
 
@@ -313,6 +323,7 @@ full reference, run `npx flowfig docs`.
 | `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                                                 |
+| `look`      | One of the 12 pictures that the guide world draws for this group.                                        | none                                                |
 
 ### Automatic layout
 
@@ -344,28 +355,64 @@ A group with a `label` or an `id` stays together as one frame. flowfig removes a
 and `align`. flowfig ignores `around` on the edges. A `direction` on the root forces `"row"` or `"column"`. `lanes` and
 `timeline` figures ignore `auto`.
 
+### Inside a box
+
+A box can hold its inside parts, down to 3 levels. Put the parts in `inside`, with the same fields as a figure:
+`layout`, `edges` and `steps`. An inside edge can start or end at an outer neighbor of the box. The open box shows that
+neighbor as a port.
+
+```json
+{
+  "id": "orders",
+  "label": "Orders",
+  "source": "src/orders.ts#createOrder",
+  "inside": {
+    "layout": {
+      "auto": true,
+      "children": [
+        { "id": "validate", "label": "Check the cart", "source": "src/orders.ts#validateCart" },
+        { "id": "save", "label": "Save the order", "source": "src/orders.ts#insertOrder" }
+      ]
+    },
+    "edges": [
+      { "from": "gateway", "to": "validate" },
+      { "from": "validate", "to": "save" },
+      { "from": "save", "to": "payments" }
+    ]
+  }
+}
+```
+
+The SVG plays a tour: it opens each box in turn and plays one step inside it. A README image shows that tour. Add
+`--script` to open a box with a click when the SVG is in a browser tab. `--scene orders` renders one level as a plain
+figure. The React player opens a box on a click. `check` and `verify` run on each level.
+
+![Flow figure: Browser, Gateway, Cart, Orders, Payments, Mail. Steps: Place an order, Add to cart.](docs/inside-shop.svg)
+
 ### 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"`, `"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       |
+| 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`    |
+| `carries` | What moves on the edge in the guide world: `"data"`, or `{ thing, form, count, from }` for a physical thing. `form` is `box`, `barrel` or `notes`. `count` is 1 to 4. `from` is the id of the box or group where the thing starts. | `"data"`   |
+| `source`  | The code this edge draws: `path` or `path#symbol`. `flowfig verify` checks it.                                                                                                                                                     | none       |
 
 ### 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     |
+| 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                            |
+| `outcome` | One sentence, 15 words or fewer, about how the story ends. The guide shows it at the end of the story. | "Ends at: <the last box label>" |
+| `nodes`   | The ids of the boxes to highlight for the whole step.                                                  | none                            |
 
 ### Beats
 
@@ -377,6 +424,7 @@ A beat is an edge id, an array of edge ids that run at the same time, or an obje
 | `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           |
+| `note`  | The reason for the beat, in one line. The guide form shows it under the `say` line.        | 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
@@ -415,11 +463,11 @@ 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 26 rules: 11 errors and 15 warnings.
+`flowfig check` has 29 rules: 11 errors and 18 warnings.
 
 | Rule                        | Severity | What it finds                                                                                                              |
 | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `unknown-id`                | error    | An edge, step or beat names a box, group or edge that does not exist.                                                      |
+| `unknown-id`                | error    | An edge, step or beat names a box, group or edge that does not exist, or `carries.from` names no box and no group.         |
 | `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.                                                                               |
@@ -430,6 +478,8 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | `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`.                             |
+| `bad-carries`               | warning  | An edge `carries` has an empty `thing`, a `form` that is not `box`, `barrel` or `notes`, or a `count` that is not 1 to 4.  |
+| `thing-no-road`             | warning  | A thing edge starts and ends at the same actor, or one end has no actor.                                                   |
 | `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`.                                                                            |
@@ -444,6 +494,7 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | `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.                                                 |
+| `unknown-look`              | warning  | A box or a group has a `look` that is not one of the 12 pictures.                                                          |
 | `auto-ignored`              | warning  | `auto` with `lanes` or `timeline`, `auto` on a nested group, or `around` on an edge with `auto`.                           |
 
 | Option            | Effect                                                                                                     |
@@ -452,6 +503,8 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | `--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` and for the lanes wrap. Default: 830.                                      |
 | `--min-text <px>` | The smallest text size the reader must get. Default: 10.                                                   |
+| `--scene <id>`    | A render only: draw the level inside the box with this id, as a plain figure.                              |
+| `--script`        | A render only: add the script that opens a box with a click.                                               |
 
 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.
 
@@ -485,6 +538,16 @@ npx flowfig gif docs/checkout.svg --dark --mp4    # the dark theme, and also doc
 on the PATH. If a GIF is over 10 MB, `gif` prints a warning. Use `--step`, a lower `--fps` or a lower `--scale` to make the
 file smaller.
 
+`flowfig frames` writes one PNG contact sheet: the key frames of the loop, each with the frame number, the time, the step,
+the beat and the boxes. It also prints one line per tile. The frame numbers match `flowfig gif` with the same `--fps`
+and `--step`.
+
+```bash
+npx flowfig frames docs/checkout.svg               # writes docs/checkout-frames.png
+npx flowfig frames docs/checkout.svg --step 2      # only step 2: writes docs/checkout-step2-frames.png
+npx flowfig frames docs/checkout.svg --every 500   # one frame each 500 ms, in place of the key frames
+```
+
 ## Verify in CI
 
 A box, an edge or a hop can name the code it draws: `"source": "src/auth/login.ts#verifyPassword"`. `npx flowfig verify docs/login.svg`
@@ -530,7 +593,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.11.0
+      - uses: iamalvisng/flowfig@v0.12.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -894,6 +957,70 @@ as `flowfig verify`.
 
 `toSvg` does not put the spec in the SVG. Only the CLI adds the spec, which `--spec` reads back.
 
+## Explain a flow in a web page
+
+`flowfig/element` is a web component. It shows one flow to a reader who does not know the code. Load the script and add the tag:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/flowfig/dist/element.js"></script>
+<flowfig-explain src="oil.json" form="guide"></flowfig-explain>
+<flowfig-explain src="after.json" before="before.json" form="change">
+  <p slot="verdict">A failed ledger write now runs again by itself.</p>
+</flowfig-explain>
+```
+
+![The guide form as a small world: the last moment of a refused pickup, with the check gate at the server](docs/explain-guide.png)
+
+The element has three forms:
+
+- `diagram` shows the figure that `toSvg` draws, with the step tabs of the player.
+- `guide` shows one moment at a time. The actors are the cast. The cast comes from the lanes. Else it comes from the labeled top-level groups.
+  Else it comes from the boxes that the steps visit. A store box adds the actor "Records" at the end. When the cast comes from the boxes, the cast holds at most 6 actors, and "Records" takes one of the 6 places. In a figure
+  without lanes, a decision box is not an actor.
+- `change` shows the older and the newer spec side by side, with the differences marked. Below the diagrams, an outcome row
+  compares Before and After: red for an end box with the tone `red` or `gray`, green for the tone `green`. A step that only one
+  side has plays on that side only.
+
+For a good guide, give each role a lane or a labeled group. Give each beat a `say`. Use `note` for the reason and `look` for the picture.
+
+The guide form shows a figure as a small isometric world when an edge `carries` a thing, or when an actor has the look
+`person`, `shop` or `truck`. Each actor stands in a building along a road. A thing moves by road or by hand. Data flies as an arc
+through the air. A check is a gate at the door of its owner. Each story ends on an outcome frame, with the `outcome` sentence and
+one tag for each actor. On a phone, the road runs down the screen as a stacked street. Other figures show the diagram in the guide.
+The world loads from `element-world.js` next to `element.js`, with a shared chunk (`element-looks.js`). A CDN script tag loads
+them from the same folder. The world art stays light in a dark theme.
+
+| Attribute | Values                                                             | Default                                       |
+| --------- | ------------------------------------------------------------------ | --------------------------------------------- |
+| `src`     | The URL of a spec JSON file, or of an SVG that flowfig wrote.      | required, unless the `spec` property is set   |
+| `form`    | `diagram`, `guide` or `change`.                                    | `guide` if the spec has steps, else `diagram` |
+| `step`    | A step label to start on.                                          | the first step                                |
+| `before`  | The URL of the older spec.                                         | required for `change`                         |
+| `theme`   | `auto`, `light` or `dark`.                                         | `auto`                                        |
+| `code`    | Present: each moment shows its `source` and `via` values.          | absent                                        |
+| `forms`   | The forms that the reader can switch between, separated by spaces. | all forms that the input allows               |
+
+The `theme` key of the spec colors the SVG in the diagram and change forms. It applies only when the `theme` attribute is `auto`. The element keeps a color only if it is plain color syntax. Else it uses the default color.
+
+- Properties: `spec` and `beforeSpec` (objects, instead of the URLs), and `moment` (the index; read and write).
+- Methods: `next()`, `back()`, `play()`, `pause()` and `show(stepLabel)`.
+- Events: `flowfig-moment` (`detail: { step, moment, total }`) and `flowfig-form` (`detail: { form }`).
+- Slots: `verdict` (the change form; it shows above the diagrams), `title` and `caption`. Without a `verdict`, the change form shows a plain list of what changed. The raw diff is behind "Show all changes".
+- Keys: the element takes focus. The arrow keys move between moments (or between steps in the diagram form). Space plays and pauses. The keys 1 to 9 pick a step.
+
+The element has a shadow root. The CSS of the host page does not reach inside it. To change the look, set the `--flowfig-*` tokens
+on the element: `--flowfig-bg`, `--flowfig-surface`, `--flowfig-border`, `--flowfig-ink`, `--flowfig-muted`, `--flowfig-accent`,
+`--flowfig-on-accent`, `--flowfig-good`, `--flowfig-bad`, `--flowfig-play`, `--flowfig-font`. Only these tokens change the look.
+
+```css
+flowfig-explain {
+  --flowfig-accent: #7c3aed;
+  --flowfig-font: Georgia, serif;
+}
+```
+
+The element is `element.js` and the files `element-world.js` and `element-looks.js` next to it. The core loads under 45 kB gzip, and the world loads on demand. There is no React. In a bundler, write `import 'flowfig/element'`.
+
 ## 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

package/dist/atlas.js

@@ -2,7 +2,7 @@ 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 { altText, nodes, scenes, str } from './model.js';
 import { openFile } from './open.js';
 import { esc, pageHtml } from './page.js';
 import { toSvg } from './svg.js';
@@ -47,7 +47,11 @@ export function atlasFiles({ root = process.cwd(), figures } = {}) {
             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 owners = new Set(scenes(spec).flatMap((s) => (s.path.length === 1 ? s.path : [])));
+        const svg = toSvg(spec, {
+            links: Object.fromEntries([...hrefs].filter(([id]) => !owners.has(id))),
+            ...(owners.size && { script: true }),
+        });
         const details = nodes(spec.layout)
             .filter((n) => typeof n.detail === 'string')
             .map((n) => {

package/dist/browser.d.ts

@@ -28,4 +28,5 @@ export declare function captureFrames(cdp: Cdp, html: string, o: {
     scale: number;
     fps: number;
     dark: boolean;
+    frames?: number[];
 }): Promise<Capture>;

package/dist/browser.js

@@ -51,6 +51,8 @@ export function launch(path, profile, timeoutMs = 30_000) {
         '--disable-gpu',
         // A seek can draw a stale transform x under load on the compositor thread.
         '--disable-threaded-animation',
+        // A partial raster of a reused tile depends on the frames before it.
+        '--disable-partial-raster',
     ];
     // Chrome refuses to start as root without it, for example in Docker.
     if (process.getuid?.() === 0)
@@ -176,6 +178,8 @@ export async function captureFrames(cdp, html, o) {
         // The packet moves with SMIL, which only the <svg> element controls.
         const info = await run(`(async () => {
       await document.fonts.ready;
+      // A data URI image decodes after the page parse, so wait for each one.
+      await Promise.all([...document.querySelectorAll('image')].map((i) => i.decode().catch(() => {})));
       const svg = document.querySelector('svg');
       const css = document.getAnimations();
       for (const a of css) a.pause();
@@ -192,15 +196,16 @@ export async function captureFrames(cdp, html, o) {
     const first = await open();
     const { info } = first;
     const n = Math.max(1, Math.round((info.loop * o.fps) / 1000));
+    const want = o.frames ?? Array.from({ length: n }, (_, i) => i);
     const clip = { x: info.x, y: info.y, width: info.width, height: info.height, scale: 1 };
     // availableParallelism arrived in Node 18.14; the package supports Node 18.0.
     const cores = os.availableParallelism?.() ?? os.cpus().length;
-    const count = Math.max(1, Math.min(MAX_TABS, cores, Math.floor(n / MIN_FRAMES_PER_TAB)));
+    const count = Math.max(1, Math.min(MAX_TABS, cores, Math.floor(want.length / MIN_FRAMES_PER_TAB)));
     const tabs = [first, ...(await Promise.all(Array.from({ length: count - 1 }, open)))];
-    const pngs = Array.from({ length: n });
+    const pngs = Array.from({ length: want.length });
     await Promise.all(tabs.map(async ({ send, run }, k) => {
-        for (let i = k; i < n; i += count) {
-            const t = (i * 1000) / o.fps;
+        for (let i = k; i < want.length; i += count) {
+            const t = (want[i] * 1000) / o.fps;
             await run(`(() => {
           for (const a of document.getAnimations()) a.currentTime = ${t};
           document.querySelector('svg').setCurrentTime(${t / 1000});

package/dist/check.d.ts

@@ -1,6 +1,6 @@
 import { type FigTheme, type FlowProps, type LanePlan } from './model.ts';
 import type { Finding, Scene } from './scene.ts';
-import type { SvgOptions } from './svg.ts';
+import type { Level, SvgOptions } from './svg.ts';
 /** Faults in the spec: dangling ids, duplicate ids, empty steps. The renderers skip them silently. */
 export declare function checkSpec(fig: FlowProps): Finding[];
 export type CheckOptions = {
@@ -14,4 +14,4 @@ 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[];
 export declare function planFor(fig: FlowProps, opts: SvgOptions): LanePlan | null;
-export declare function checkRendered(fig: FlowProps, opts: SvgOptions & CheckOptions, scene: Scene): Finding[];
+export declare function checkRendered(fig: FlowProps, opts: SvgOptions & CheckOptions, scene: Scene, levels?: Level[]): Finding[];

package/dist/check.js

@@ -1,7 +1,8 @@
-import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, lanePlan, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
+import { DARK, LIGHT, LOOKS, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, lanePlan, validAt, laneColumns, nodes, scenes, str, toBeat, MAX_LEVEL, } from './model.js';
 import { layoutRail } from './rail.js';
 import { crosses, samples } from './geometry.js';
 import { textWidth } from './text.js';
+import { cast } from './explain.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
 const warn = (rule, ids, message) => ({ rule, severity: 'warning', ids, message });
@@ -42,6 +43,8 @@ function plainText(fig) {
     for (const n of nodes(fig.layout)) {
         check(`box "${n.id}"`, 'label', n.label, { source: n.source, command: true });
         check(`box "${n.id}"`, 'sub', n.sub);
+        check(`box "${n.id}"`, 'check', n.check);
+        check(`box "${n.id}"`, 'done', n.done);
     }
     const groupLabels = (g) => {
         if (g.label != null)
@@ -51,11 +54,16 @@ function plainText(fig) {
                 groupLabels(c);
     };
     groupLabels(fig.layout);
-    fig.edges.forEach((e) => check(`edge "${edgeId(e)}"`, 'label', e.label, { source: e.source, command: true }));
+    fig.edges.forEach((e) => {
+        check(`edge "${edgeId(e)}"`, 'label', e.label, { source: e.source, command: true });
+        if (e.carries && typeof e.carries === 'object')
+            check(`edge "${edgeId(e)}"`, 'carries.thing', e.carries.thing);
+    });
     for (const s of fig.steps ?? []) {
         const name = str(s.label);
         check(`step "${name}"`, 'label', s.label);
         check(`step "${name}"`, 'caption', s.caption, { words: true });
+        check(`step "${name}"`, 'outcome', s.outcome, { words: true });
         s.flow.map(toBeat).forEach((b, i) => {
             check(`step "${name}"`, `say ${i + 1}`, b.say, { words: true });
             b.hops.forEach((h) => check(`step "${name}"`, `data ${i + 1}`, h.data, { code: false }));
@@ -65,6 +73,94 @@ function plainText(fig) {
 }
 /** Faults in the spec: dangling ids, duplicate ids, empty steps. The renderers skip them silently. */
 export function checkSpec(fig) {
+    const own = specRules(fig);
+    if (!nodes(fig.layout).some((n) => n.inside))
+        return own;
+    return [...own, ...insideRules(fig)];
+}
+function insideRules(fig) {
+    const out = [];
+    const form = fig.timeline
+        ? 'timeline; a timeline does not'
+        : fig.lanes
+            ? 'lanes; lanes do not'
+            : fig.rail === 'only'
+                ? 'rail: "only"; a rail-only figure does not'
+                : null;
+    if (form) {
+        for (const n of nodes(fig.layout))
+            if (n.inside)
+                out.push(warn('parts-ignored', [n.id], `the figure sets ${form} open boxes, so the renderers ignore inside on "${n.id}"`));
+        return out;
+    }
+    let total = 0;
+    const limits = (g, level) => {
+        for (const n of nodes(g)) {
+            if (!n.inside)
+                continue;
+            if (level === MAX_LEVEL) {
+                out.push(err('part-limit', [n.id], `box "${n.id}" is at level ${MAX_LEVEL}, so its parts are at level ${MAX_LEVEL + 1}; the limit is ${MAX_LEVEL} levels`));
+                continue;
+            }
+            const count = nodes(n.inside.layout).length;
+            total += count;
+            if (!count)
+                out.push(err('part-limit', [n.id], `box "${n.id}": inside has no parts`));
+            else if (count > 16)
+                out.push(err('part-limit', [n.id], `box "${n.id}" has ${count} parts; the limit is 16`));
+            limits(n.inside.layout, level + 1);
+        }
+    };
+    limits(fig.layout, 1);
+    if (total > 60)
+        out.push(err('part-limit', [], `the figure has ${total} parts; the limit is 60`));
+    const all = scenes(fig);
+    const seen = { boxes: new Map(), groups: new Map(), edges: new Map() };
+    const partsOf = (s) => {
+        const ports = new Set(s.ports.map((p) => p.id));
+        return nodes(s.props.layout).filter((n) => !ports.has(n.id));
+    };
+    for (const s of all) {
+        const add = (m, ids) => ids.forEach((id) => m.set(id, (m.get(id) ?? new Map()).set(s.path.join('>'), s.line || 'the root')));
+        add(seen.boxes, partsOf(s).map((n) => n.id));
+        add(seen.groups, groupIds(s.props.layout));
+        add(seen.edges, s.props.edges.map(edgeId));
+    }
+    for (const [kind, m] of Object.entries(seen))
+        for (const [id, lines] of m)
+            if (lines.size > 1)
+                out.push(err('duplicate-id', [id], `two ${kind} have the id "${id}": ${[...lines.values()].join(' and ')}`));
+    const byKey = new Map(all.map((s) => [s.path.join('>'), s]));
+    for (const s of all.slice(1)) {
+        const parent = byKey.get(s.path.slice(0, -1).join('>'));
+        const owner = s.path.at(-1);
+        const found = specRules(s.props).filter((f) => f.rule !== 'bad-source');
+        const parts = new Set(partsOf(s).map((n) => n.id));
+        for (const n of partsOf(s))
+            if (n.source == null)
+                found.push(warn('part-no-source', [n.id], `part "${n.id}" has no source`));
+        const outerIn = parent.props.edges.filter((e) => e.to === owner);
+        const outerOut = parent.props.edges.filter((e) => e.from === owner);
+        for (const e of s.props.edges) {
+            const id = edgeId(e);
+            if (!parts.has(e.from) && !parts.has(e.to))
+                found.push(err('part-edge-mismatch', [id], `edge "${id}" has no part at either end`));
+            else if (!parts.has(e.from) && !outerIn.some((o) => o.from === e.from))
+                found.push(err('part-edge-mismatch', [id, e.from], `edge "${id}" comes in from "${e.from}", but no edge goes from "${e.from}" to "${owner}"`));
+            else if (!parts.has(e.to) && !outerOut.some((o) => o.to === e.to))
+                found.push(err('part-edge-mismatch', [id, e.to], `edge "${id}" goes out to "${e.to}", but no edge goes from "${owner}" to "${e.to}"`));
+        }
+        for (const o of outerIn)
+            if (!s.props.edges.some((e) => e.from === o.from))
+                found.push(warn('part-edge-mismatch', [edgeId(o)], `edge "${edgeId(o)}" comes in, but no edge inside "${owner}" starts at "${o.from}"; the open view cannot show where the flow comes in`));
+        for (const o of outerOut)
+            if (!s.props.edges.some((e) => e.to === o.to))
+                found.push(warn('part-edge-mismatch', [edgeId(o)], `edge "${edgeId(o)}" goes out, but no edge inside "${owner}" ends at "${o.to}"; the open view cannot show where the flow goes out`));
+        out.push(...found.map((f) => ({ ...f, scene: s.line })));
+    }
+    return out;
+}
+function specRules(fig) {
     const out = [];
     const boxIds = nodes(fig.layout).map((n) => n.id);
     const groups = groupIds(fig.layout);
@@ -76,13 +172,21 @@ export function checkSpec(fig) {
     const known = new Set([...boxIds, ...groups]);
     const knownEdges = new Set(edges);
     const empty = new Set();
+    const firstBox = new Map();
     const walk = (g) => {
-        for (const c of g.children)
+        for (const c of g.children) {
+            if (c.look != null && !LOOKS.includes(c.look)) {
+                const who = isGroup(c) ? `group "${c.id ?? str(c.label)}"` : `box "${c.id}"`;
+                out.push(warn('unknown-look', isGroup(c) ? (c.id == null ? [] : [c.id]) : [c.id], `${who} has look "${c.look}"; use one of: ${LOOKS.join(', ')}`));
+            }
             if (isGroup(c)) {
                 if (c.id != null && !nodes(c).length)
                     empty.add(c.id);
+                if (c.id != null && nodes(c).length)
+                    firstBox.set(c.id, nodes(c)[0].id);
                 walk(c);
             }
+        }
     };
     walk(fig.layout);
     fig.edges.forEach((e, i) => {
@@ -92,6 +196,30 @@ export function checkSpec(fig) {
             else if (empty.has(end))
                 out.push(err('unknown-id', [edges[i], end], `edge "${edges[i]}" ends at group "${end}", which has no boxes`));
     });
+    const actorOf = new Map(cast(fig).flatMap((a) => a.boxes.map((b) => [b, a.name])));
+    fig.edges.forEach((e, i) => {
+        const c = e.carries;
+        if (!c || typeof c !== 'object')
+            return;
+        const id = edges[i];
+        const thing = str(c.thing).trim();
+        if (c.count != null && !(Number.isInteger(c.count) && c.count >= 1 && c.count <= 4))
+            out.push(warn('bad-carries', [id], `edge "${id}" has carries.count ${c.count}; use 1 to 4`));
+        if (!thing)
+            out.push(warn('bad-carries', [id], `edge "${id}" has an empty carries.thing; name the thing in plain words`));
+        if (c.form != null && !['box', 'barrel', 'notes'].includes(c.form))
+            out.push(warn('bad-carries', [id], `edge "${id}" has carries.form "${c.form}"; use box, barrel or notes`));
+        if (c.from != null && !known.has(c.from)) {
+            out.push(err('unknown-id', [id, c.from], `edge "${id}" has carries.from "${c.from}", which names no box and no group`));
+            return;
+        }
+        const start = c.from == null ? e.from : (firstBox.get(c.from) ?? c.from);
+        const [a, b] = [actorOf.get(start), actorOf.get(e.to)];
+        if (a == null || b == null)
+            out.push(warn('thing-no-road', [id], `edge "${id}" carries "${thing}", but box "${a == null ? start : e.to}" has no actor; put it in a lane or a labeled group`));
+        else if (a === b)
+            out.push(warn('thing-no-road', [id], `edge "${id}" carries "${thing}", but both ends are at actor "${a}"; set carries.from to the box where the thing starts`));
+    });
     (fig.steps ?? []).forEach((s, si) => {
         const where = `step ${si + 1} ("${str(s.label)}")`;
         if (!s.flow.length)
@@ -376,7 +504,7 @@ export function planFor(fig, opts) {
     const floor = fig.rail ? (layoutRail(fig, 560)?.width ?? 0) : 0;
     return lanePlan(fig, { width: opts.width, minText: opts.minText, padding: opts.padding ?? 24, floor });
 }
-export function checkRendered(fig, opts, scene) {
+export function checkRendered(fig, opts, scene, levels) {
     const lost = (planFor(fig, opts)?.lost ?? []).map((id) => ({
         rule: 'lane-end-block',
         severity: 'warning',
@@ -385,7 +513,9 @@ export function checkRendered(fig, opts, scene) {
     }));
     return [
         ...checkSpec(fig),
-        ...checkScene(scene, { ...opts, auto: opts.auto ?? fig.layout.auto }),
+        ...(levels
+            ? levels.flatMap((l, i) => checkScene({ ...l.scene, width: Math.max(...levels.map((x) => x.scene.width)) }, { ...opts, auto: opts.auto ?? l.props.layout.auto }).map((f) => (i ? { ...f, scene: l.line } : f)))
+            : checkScene(scene, { ...opts, auto: opts.auto ?? fig.layout.auto })),
         ...lost,
         ...checkTheme({ ...fig.theme, ...opts.theme }),
     ];