flowfig 0.3.0 → 0.5.0

package/README.md

@@ -16,17 +16,30 @@
 
 </div>
 
-An agent with the flowfig instructions made faithful, checked diagrams more often than the same agent without them:
+## Use it
 
-| Criterion                                           | Agent without flowfig instructions | Agent with flowfig instructions                |
-| --------------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
-| Diagram faithful to the code (no invented part)     | 7 of 8                             | 8 of 8                                         |
-| Right diagram form for the task                     | 5 of 7                             | 7 of 7                                         |
-| Passes `flowfig check --strict`                     | 5 of 7                             | 6 of 6                                         |
-| Right action (draws, declines or splits)            | 6 of 8                             | 7 of 8                                         |
-| Held-out tasks (not used to write the instructions) | –                                  | 2 of 4 pass all 6 criteria; 2 of 4 pass 4 of 6 |
+Set up your repo:
 
-[How we measured](#how-we-measured).
+```bash
+npx flowfig init
+```
+
+Then start a new agent session. In Claude Code, run:
+
+```
+/figure how does login work
+```
+
+With any agent, ask in plain words:
+
+```
+draw a diagram of how login works in this repo
+use flowfig to draw the checkout flow as a sequence
+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.
 
 ## One command
 
@@ -41,18 +54,7 @@ checks the figure itself with `check --strict` and `verify`, and removes the spe
 `draw` exits 1 and shows the tool calls that the permission rules denied. `draw` prints the result, the reply of the agent
 and the cost of the run. `draw` needs Claude Code on the machine and a login. `draw` does not run on Windows yet.
 `--out` sets the path (it must end in `.svg`), `--model` sets the model, `--max-turns` sets the turn cap (default 40) and
-`--json` prints `{ out, reply, cost, session, findings }` for scripts.
-
-## Quick start
-
-```bash
-npx flowfig init
-```
-
-Then ask your agent: "draw a diagram of how login works in this repo".
-
-`init` writes the flowfig instructions for the agents that your repo uses. The agent reads the code, writes a spec, runs
-`flowfig check`, fixes the faults, and renders the SVG.
+`--json` prints `{ out, reply, cost, session, findings }` for scripts. `--open` opens the figure in the default browser after the check.
 
 ## The problem
 
@@ -95,13 +97,14 @@ Then ask your agent: "draw a diagram of how login works in this repo".
 - [Three forms](#three-forms)
 - [The spec](#the-spec)
 - [Check a figure](#check-a-figure)
+- [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)
 - [Use with your coding agent](#use-with-your-coding-agent)
 - [What flowfig does not draw](#what-flowfig-does-not-draw)
-- [How we measured](#how-we-measured)
 - [License](#license)
 - [Development](#development)
 
@@ -298,6 +301,7 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | `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.          |
 
@@ -305,7 +309,7 @@ The last line gives the counts of the parts of the figure. Compare the counts wi
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
 | `--strict`        | Every warning becomes an error.                                                                            |
 | `--json`          | Print the findings as a JSON array, for scripts. Each finding has `rule`, `severity`, `ids` and `message`. |
-| `--width <px>`    | The page width for `small-text`. Default: 830.                                                             |
+| `--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.                                                   |
 
 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.
@@ -315,6 +319,31 @@ A render runs the same check first. If the check finds an error, the render writ
 In React, `<Flow check />` runs the same rules on the layout that the browser drew. The player prints each fault with
 `console.warn`.
 
+## Open and share a figure
+
+`flowfig open` shows a figure in your default browser. On macOS, an `.svg` file often opens in a text editor or in Xcode. Thus
+`open` writes an HTML page that holds the SVG, and opens that page.
+
+```bash
+npx flowfig open docs/checkout.svg
+npx flowfig open docs/checkout.svg --html checkout.html    # also write the page to checkout.html
+npx flowfig docs/checkout.json docs/checkout.svg --open    # render, then open
+```
+
+`flowfig gif` writes an animated GIF of the whole loop. A GIF plays in Slack, Notion, X and slide decks, where an SVG
+animation does not play.
+
+```bash
+npx flowfig gif docs/checkout.svg                 # writes docs/checkout.gif
+npx flowfig gif docs/checkout.svg --step 2        # only step 2: writes docs/checkout-step2.gif
+npx flowfig gif docs/checkout.svg --dark --mp4    # the dark theme, and also docs/checkout.mp4
+```
+
+`gif` needs Chrome, Edge, Chromium or Brave in the standard install path. Set `CHROME_PATH` to use another browser program.
+`--fps` sets the frames per second (1 to 50, default 20). `--scale` sets the pixel scale (default 2). `--mp4` needs `ffmpeg`
+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.
+
 ## 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`
@@ -340,6 +369,21 @@ steps:
       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.
@@ -455,24 +499,9 @@ of the file. A second run also replaces a whole file that `init` wrote. If a who
 
 ## What flowfig does not draw
 
-flowfig draws parts, the messages between the parts, and their order. flowfig does not draw class diagrams, ER diagrams, Gantt
-charts, timelines with dates, charts of numbers or mind maps. Use Mermaid or a chart library for those.
-
-## How we measured
-
-We ran an evaluation before this release: 47 coding-agent runs, with Claude Sonnet as the agent. The runs covered 12 tasks in 5
-test repos: a TypeScript login API, a Python ETL pipeline, an order state machine, a 20-service platform and a mixed CLI repo.
-The agent ran without the flowfig instructions and with them. An Opus grader scored each run against an answer key.
-
-4 tasks were held out: they shaped no instruction. On the held-out tasks, 2 of 4 runs passed all 6 criteria. The other 2 passed
-4 of 6: one drew an edge from the wrong box, and one reply stated a runtime effect wrongly.
-
-A first draft of the instructions scored worse than no instructions: 5 of 8 faithful. We rewrote the instructions from the
-failures and tested them again. The "with" column comes from the version that we tested on all 8 tasks. The shipped instructions
-add two refinements: the scope of a repo with many flows, and each edge taken from the caller in the code. 9 more runs tested
-the two refinements on the tasks that still failed.
-
-The evaluation also found 3 faults in flowfig itself. We fixed all 3 before this release.
+flowfig draws parts, the messages between the parts, and their order. flowfig draws a roadmap or a timeline with dates (`timeline: true`),
+and converts a Mermaid `gantt` to it. flowfig does not draw class diagrams, ER diagrams, charts of numbers or mind maps. Use Mermaid
+or a chart library for those.
 
 ## License
 

package/dist/browser.d.ts

@@ -0,0 +1,33 @@
+export type Found = {
+    path: string | null;
+    checked: string[];
+};
+/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+export declare function findBrowser(o: {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    exists: (p: string) => boolean;
+}): Found;
+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>;
+}>;
+export type Capture = {
+    pngs: Buffer[];
+    width: number;
+    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;
+    scale: number;
+    fps: number;
+    dark: boolean;
+}): Promise<Capture>;

package/dist/browser.js

@@ -0,0 +1,201 @@
+// The capture browser of `flowfig gif`: find it, start it in headless mode, and talk CDP to it over a pipe. Node only.
+import { spawn } from 'node:child_process';
+import { win32 } from 'node:path';
+const MAC = ['Google Chrome', 'Microsoft Edge', 'Chromium', 'Brave Browser'].map((n) => `/Applications/${n}.app/Contents/MacOS/${n}`);
+const LINUX = [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+    '/usr/bin/microsoft-edge',
+    '/usr/bin/brave-browser',
+    '/opt/google/chrome/chrome',
+];
+const WINDOWS = [
+    'Google\\Chrome\\Application\\chrome.exe',
+    'Microsoft\\Edge\\Application\\msedge.exe',
+    'BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+    'Chromium\\Application\\chrome.exe',
+];
+/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+export function findBrowser(o) {
+    const { env } = o;
+    const paths = env.CHROME_PATH
+        ? [env.CHROME_PATH]
+        : o.platform === 'darwin'
+            ? MAC
+            : o.platform === 'win32'
+                ? [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA].flatMap((dir) => dir ? WINDOWS.map((p) => win32.join(dir, p)) : [])
+                : LINUX;
+    const checked = [];
+    for (const p of paths) {
+        checked.push(p);
+        if (o.exists(p))
+            return { path: p, checked };
+    }
+    return { path: null, checked };
+}
+/** Start the capture browser in headless mode with a CDP pipe. `close` stops it and never throws. */
+export function launch(path, profile, timeoutMs = 30_000) {
+    const args = [
+        '--headless=new',
+        '--remote-debugging-pipe',
+        `--user-data-dir=${profile}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--hide-scrollbars',
+        '--mute-audio',
+        // The GPU raster gave a different pixel run to run on a rounded corner, and a bigger GIF.
+        '--disable-gpu',
+        // A transform animation (the timeline playhead) runs on the compositor thread, so a seek can draw a stale x under load.
+        '--disable-threaded-animation',
+    ];
+    // Chrome refuses to start as root without it, for example in a Docker container.
+    if (process.getuid?.() === 0)
+        args.push('--no-sandbox');
+    const child = spawn(path, [...args, 'about:blank'], {
+        stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+        // Its own process group, so close can stop the helpers too. Not on Windows: there it opens a console window.
+        detached: process.platform !== 'win32',
+    });
+    // The browser reads commands on fd 3 and writes replies on fd 4. A NUL byte ends each message.
+    const out = child.stdio[3], input = child.stdio[4];
+    out.on('error', () => { }); // a write after the exit fails; the exit handler below rejects the commands
+    let tail = '', dead = null, nextId = 1;
+    child.stderr.on('data', (d) => (tail = (tail + d.toString()).slice(-2048)));
+    const pending = new Map();
+    const events = [];
+    const stop = (e) => {
+        dead ??= e;
+        for (const w of [...pending.values(), ...events.splice(0)])
+            w.reject(dead);
+        pending.clear();
+    };
+    // The browser starts helper processes in its process group. A helper can outlive the browser and keep a pipe open.
+    const killGroup = () => {
+        try {
+            if (process.platform === 'win32')
+                child.kill('SIGKILL');
+            else if (child.pid)
+                process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            // the group is already gone
+        }
+    };
+    const closed = new Promise((done) => {
+        const end = (e) => (stop(e), done());
+        const stopped = (code) => new Error(`the browser stopped (exit ${code}): ${tail.trim()}`);
+        child.once('error', end);
+        child.once('exit', (code) => {
+            out.destroy(); // the write end of fd 3 does not close by itself, and 'close' waits for it
+            killGroup();
+            setTimeout(() => end(stopped(code)), 1000).unref(); // in case a pipe stays open after the group kill
+        });
+        child.once('close', (code) => end(stopped(code)));
+    });
+    let parts = [];
+    input.on('data', (chunk) => {
+        let start = 0;
+        for (let end = chunk.indexOf(0); end !== -1; start = end + 1, end = chunk.indexOf(0, start)) {
+            parts.push(chunk.subarray(start, end));
+            const msg = JSON.parse(Buffer.concat(parts).toString('utf8'));
+            parts = [];
+            if (msg.id !== undefined) {
+                const w = pending.get(msg.id);
+                pending.delete(msg.id);
+                if (msg.error)
+                    w?.reject(new Error(`${w.method}: ${msg.error.message}`));
+                else
+                    w?.resolve(msg.result);
+            }
+            else {
+                const i = events.findIndex((w) => w.event === msg.method && w.sessionId === msg.sessionId);
+                if (i !== -1)
+                    events.splice(i, 1)[0].resolve(msg.params);
+            }
+        }
+        if (start < chunk.length)
+            parts.push(chunk.subarray(start));
+    });
+    /** A promise that rejects after the timeout; `add` registers the waiter, `drop` removes it. */
+    const timed = (label, add, drop, ms = timeoutMs) => new Promise((resolve, reject) => {
+        if (dead)
+            return reject(dead);
+        const timer = setTimeout(() => {
+            drop();
+            reject(new Error(`${label}: no reply in ${ms / 1000} s`));
+        }, ms);
+        add({ resolve: (v) => (clearTimeout(timer), resolve(v)), reject: (e) => (clearTimeout(timer), reject(e)) });
+    });
+    const cdp = {
+        send: (method, params = {}, sessionId, ms) => {
+            const id = nextId++;
+            return timed(method, (w) => {
+                pending.set(id, { ...w, method });
+                out.write(JSON.stringify({ id, method, params, sessionId }) + '\0');
+            }, () => pending.delete(id), ms);
+        },
+        once: (event, sessionId, ms) => {
+            let me;
+            return timed(event, (w) => events.push((me = { ...w, event, sessionId })), () => events.splice(events.indexOf(me), 1), ms);
+        },
+    };
+    // No Browser.close: the profile is a temp folder with nothing to keep, and Chrome takes about 10 s to exit after it.
+    const close = async () => {
+        killGroup();
+        await closed;
+    };
+    return cdp.send('Browser.getVersion').then(() => ({ cdp, close }), async (e) => {
+        await close();
+        throw e;
+    });
+}
+/** Set the page, pause the animations and take one PNG per frame time. */
+export async function captureFrames(cdp, html, o) {
+    const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    const send = (method, params) => cdp.send(method, params, sessionId);
+    const run = async (expression) => {
+        const r = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+        if (r.exceptionDetails)
+            throw new Error(`Runtime.evaluate: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`);
+        return r.result.value;
+    };
+    await send('Emulation.setDeviceMetricsOverride', { width: o.width, height: o.height, deviceScaleFactor: o.scale, mobile: false });
+    // The figure picks its theme with a media query, so the run sets the query and leaves the SVG as it is.
+    await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: o.dark ? 'dark' : 'light' }] });
+    // The page goes in as content, not as a file: a snap browser has a private /tmp and cannot read the temp folder.
+    const { frameTree } = await send('Page.getFrameTree');
+    await send('Page.setDocumentContent', { frameId: frameTree.frame.id, html });
+    // CSS animations are in getAnimations(). The packet moves with SMIL, which only the <svg> element controls.
+    const info = await run(`(async () => {
+    await document.fonts.ready;
+    const svg = document.querySelector('svg');
+    const css = document.getAnimations();
+    for (const a of css) a.pause();
+    svg.pauseAnimations();
+    let loop = 0;
+    for (const a of css) loop = Math.max(loop, Number(a.effect.getTiming().duration) || 0);
+    for (const m of svg.querySelectorAll('animate, animateMotion, animateTransform, set'))
+      try { loop = Math.max(loop, m.getSimpleDuration() * 1000); } catch {}
+    const r = svg.getBoundingClientRect();
+    return { loop, x: r.x, y: r.y, width: r.width, height: r.height };
+  })()`);
+    const n = Math.max(1, Math.round((info.loop * o.fps) / 1000));
+    const clip = { x: info.x, y: info.y, width: info.width, height: info.height, scale: 1 };
+    const pngs = [];
+    for (let i = 0; i < n; i++) {
+        const t = (i * 1000) / o.fps;
+        await run(`(() => {
+      for (const a of document.getAnimations()) a.currentTime = ${t};
+      document.querySelector('svg').setCurrentTime(${t / 1000});
+      // two frames: one frame can fire before the browser draws the new time under load
+      return new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+    })()`);
+        const { data } = await send('Page.captureScreenshot', { format: 'png', clip });
+        pngs.push(Buffer.from(data, 'base64'));
+    }
+    return { pngs, width: Math.round(info.width * o.scale), height: Math.round(info.height * o.scale), loopMs: info.loop };
+}

package/dist/check.js

@@ -1,6 +1,7 @@
 // The rules behind `flowfig check`. They never draw and never measure: a renderer gives a Scene, and these read it. So one rule set
 // covers the SVG (estimated text) and the React player (measured text), and any later view that gives a scene.
-import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, nodes, str, toBeat, } from './model.js';
+import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
+import { crosses } from './geometry.js';
 import { textWidth } from './text.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
@@ -34,9 +35,9 @@ export function checkSpec(fig) {
             for (const h of b.hops)
                 if (!knownEdges.has(h.edge))
                     out.push(err('unknown-id', [h.edge], `${where} moves along edge "${h.edge}", which does not exist`));
-            for (const id of [...Object.keys(b.show ?? {}), ...(b.light ?? [])])
+            for (const id of [...Object.keys(b.show ?? {}), ...(b.light ?? []), ...(b.focus ?? [])])
                 if (!known.has(id))
-                    out.push(err('unknown-id', [id], `${where}: show or light names box "${id}", which does not exist`));
+                    out.push(err('unknown-id', [id], `${where}: show, light or focus names box "${id}", which does not exist`));
         }
     });
     const used = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => h.edge))));
@@ -48,6 +49,61 @@ export function checkSpec(fig) {
     for (const [who, source] of owners(fig))
         if (source != null && !parseSource(source))
             out.push(warn('bad-source', [], `${who}: source "${source}" is not path or path#symbol`));
+    const marks = nodes(fig.layout).map((n) => n.mark);
+    const starts = marks.filter((m) => m === 'start').length;
+    const ends = marks.filter((m) => m === 'end').length;
+    if (starts > 1 || (starts && !ends))
+        out.push(warn('mark-count', [], `a lifecycle has one start and at least one end: ${starts} start, ${ends} end`));
+    if (fig.timeline && fig.lanes)
+        out.push(warn('timeline-and-lanes', [], 'the figure sets timeline and lanes; the renderers draw the timeline and ignore lanes'));
+    if (fig.timeline) {
+        if (!isLanesLayout(fig.layout))
+            out.push(err('lanes-need-column', [], 'a timeline uses the lanes layout: a column group of labeled groups, one per track, with boxes only inside'));
+        for (const n of nodes(fig.layout)) {
+            if (n.from == null)
+                out.push(err('timeline-need-from', [n.id], `box "${n.id}" has no from date, and a timeline needs one`));
+            const [f, t] = [n.from == null ? null : dayOf(n.from), n.to == null ? null : dayOf(n.to)];
+            for (const [name, v, d] of [
+                ['from', n.from, f],
+                ['to', n.to, t],
+            ])
+                if (v != null && d == null)
+                    out.push(err('bad-date', [n.id], `box "${n.id}": ${name} "${v}" is not a real YYYY-MM-DD date`));
+            if (f != null && t != null && t < f)
+                out.push(err('bad-date', [n.id], `box "${n.id}": to ${n.to} is before from ${n.from}`));
+        }
+        // A dependent item starts after its source ends. A milestone ends the day it starts.
+        const span = new Map(nodes(fig.layout).map((n) => [n.id, [n.from && dayOf(n.from), (n.to && dayOf(n.to)) ?? (n.from && dayOf(n.from))]]));
+        for (const e of fig.edges) {
+            const start = span.get(e.to)?.[0];
+            const end = span.get(e.from)?.[1];
+            if (start != null && end != null && start <= end)
+                out.push(warn('timeline-dependency-order', [e.from, e.to], `"${e.to}" does not start after "${e.from}" ends`));
+        }
+        if (fig.today != null && dayOf(fig.today) == null)
+            out.push(err('bad-date', [], `today "${fig.today}" is not a real YYYY-MM-DD date`));
+    }
+    else if (fig.lanes) {
+        const top = fig.layout;
+        if (!isLanesLayout(top))
+            out.push(err('lanes-need-column', [], 'lanes need a column group of labeled groups, one per lane, with boxes only inside'));
+        else {
+            const cols = laneColumns(fig);
+            for (const lane of top.children) {
+                const at = new Map();
+                for (const n of lane.children) {
+                    const c = cols.get(n.id);
+                    const other = at.get(c);
+                    if (other != null)
+                        out.push(warn('lane-column-taken', [other, n.id], `boxes "${other}" and "${n.id}" share column ${c} in lane "${str(lane.label)}"`));
+                    at.set(c, n.id);
+                }
+            }
+        }
+    }
+    for (const n of nodes(fig.layout))
+        if (n.at != null && !validAt(n.at))
+            out.push(err('bad-at', [n.id], `box "${n.id}": at ${n.at} is not an integer of 0 or more`));
     return out;
 }
 /** A point on the cubic Bézier at `t`. */
@@ -56,6 +112,7 @@ const at = ([p0, p1, p2, p3], t) => {
     const [a, b, c, d] = [u * u * u, 3 * u * u * t, 3 * u * t * t, t * t * t];
     return { x: a * p0.x + b * p1.x + c * p2.x + d * p3.x, y: a * p0.y + b * p1.y + c * p2.y + d * p3.y };
 };
+const lerp = (p, q, t) => ({ x: p.x + (q.x - p.x) * t, y: p.y + (q.y - p.y) * t });
 // The margins keep a touch from counting: an edge leaves along a border, and pills sit edge to edge.
 const inside = (p, r, pad) => p.x > r.x + pad && p.x < r.x + r.w - pad && p.y > r.y + pad && p.y < r.y + r.h - pad;
 const overlap = (a, b, pad) => a.x + pad < b.x + b.w - pad && b.x + pad < a.x + a.w - pad && a.y + pad < b.y + b.h - pad && b.y + pad < a.y + a.h - pad;
@@ -70,11 +127,54 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 out.push(err('text-overflow', [b.id], `box "${b.id}": "${t.text}" needs ${Math.ceil(need)} px, has ${Math.floor(t.room)} px`));
         }
     for (const e of scene.edges) {
-        const pts = Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+        if (e.behind)
+            continue;
+        const pts = e.pts
+            ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
+            : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
         for (const b of scene.boxes)
             if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, 2)))
                 out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}"`));
     }
+    // A stub pill (the label of an edge with `pts`) must not sit on another edge's path.
+    const pills = scene.edges.filter((e) => e.pts && e.label);
+    const under = new Set();
+    for (const e of scene.edges) {
+        if (e.behind)
+            continue;
+        const pts = e.pts
+            ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
+            : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+        for (const f of pills)
+            if (f.id !== e.id && !under.has(e.id + ' ' + f.id) && pts.some((p) => inside(p, f.label, 2))) {
+                under.add(e.id + ' ' + f.id);
+                out.push(err('label-overlap', [e.id, f.id], `edge "${e.id}" passes under the pill of edge "${f.id}"`));
+            }
+    }
+    // A stub line (a segment of an edge with `pts`) must not cross the path of another edge.
+    const path = (e) => e.pts
+        ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
+        : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+    const stubs = scene.edges.filter((e) => e.pts && e.pts.length > 1);
+    const hit = new Set();
+    for (const f of stubs)
+        for (const e of scene.edges) {
+            if (e.behind || e === f || (e.id === f.id && e.pts) || hit.has(f.id + ' ' + e.id))
+                continue;
+            const p = path(e);
+            if (f.pts.slice(1).some((a, k) => p.slice(1).some((b, i) => crosses(f.pts[k], a, p[i], b)))) {
+                hit.add(f.id + ' ' + e.id);
+                out.push(warn('stub-crosses-edge', [f.id, e.id], `the stub of edge "${f.id}" crosses edge "${e.id}"`));
+            }
+        }
+    // A stub pill sits inside the band of its box: a pill across a band border reads as part of two lanes.
+    for (const f of pills)
+        for (const l of scene.lanes ?? []) {
+            const [p, r] = [f.label, l.rect];
+            const inside = p.x >= r.x && p.x + p.w <= r.x + r.w && p.y >= r.y && p.y + p.h <= r.y + r.h;
+            if (!inside && overlap(p, r, 0))
+                out.push(err('label-overlap', [f.id], `the pill of edge "${f.id}" crosses the border of lane "${l.id}"`));
+        }
     const labeled = scene.edges.filter((e) => e.label);
     labeled.forEach((e, i) => {
         for (const f of labeled.slice(i + 1))