flowfig 0.10.0 → 0.12.0

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)
@@ -209,7 +337,7 @@ const overlap = (a, b, pad) => a.x + pad < b.x + b.w - pad && b.x + pad < a.x +
 const px = (n) => Math.round(n * 10) / 10;
 // Measured corner touches go 3.5 px deep; real crossings go 24 px or more.
 const TOUCH = 6;
-export function checkScene(scene, { width = 830, minText = 10 } = {}) {
+export function checkScene(scene, { width = 830, minText = 10, auto } = {}) {
     const out = [];
     for (const b of scene.boxes)
         for (const t of b.texts) {
@@ -223,7 +351,7 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
         const pts = path(e);
         for (const b of scene.boxes)
             if (b.id !== e.from && b.id !== e.to && pts.some((p) => inside(p, b.rect, TOUCH)))
-                out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}": move a box, or set "auto": true on the root layout`));
+                out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}": move a box${auto ? '' : ', or set "auto": true on the root layout'}`));
     }
     for (const e of scene.edges) {
         const pts = path(e);
@@ -231,7 +359,7 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
         const ratio = drawn / Math.max(1, Math.hypot(pts.at(-1).x - pts[0].x, pts.at(-1).y - pts[0].y));
         // The README figures have a good edge at ratio 1.77 and 425 px.
         if (ratio >= 1.6 && drawn >= 600)
-            out.push(warn('long-edge', [e.id], `edge "${e.id}" is ${px(ratio)} times the straight distance between its ends: put its ends in one row or column, route it with around, or set "auto": true on the root layout`));
+            out.push(warn('long-edge', [e.id], `edge "${e.id}" is ${px(ratio)} times the straight distance between its ends: put its ends in one row or column${auto ? ', or route it with around' : ', route it with around, or set "auto": true on the root layout'}`));
     }
     const pills = scene.edges.filter((e) => e.pts && e.label);
     const under = new Set();
@@ -376,12 +504,19 @@ 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',
         ids: [id],
         message: `edge "${id}" ends at a lane that no block on its side shows; the edge uses the nearest block`,
     }));
-    return [...checkSpec(fig), ...checkScene(scene, opts), ...lost, ...checkTheme({ ...fig.theme, ...opts.theme })];
+    return [
+        ...checkSpec(fig),
+        ...(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 }),
+    ];
 }

package/dist/cli.js

@@ -13,6 +13,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { captureFrames, findBrowser, launch } from './browser.js';
+import { keyFrames, sheetGrid, sheetSvg } from './frames.js';
 import { delays, encodeGif } from './gif.js';
 import { GUIDE, TOPICS } from './guide.js';
 import { runDraw } from './draw.js';
@@ -20,14 +21,15 @@ import { runInit } from './init.js';
 import { serve } from './mcp.js';
 import { runAtlas } from './atlas.js';
 import { runFromMermaid } from './mermaid.js';
-import { openedLine, openSvg, runOpen } from './open.js';
+import { openedLine, openFile, openSvg, runOpen } from './open.js';
 import { pageHtml } from './page.js';
 import { decodePng } from './png.js';
 import { diff, formatDiff, mergeFigures } from './diff.js';
 import { loadSpec, reportLines, sortFindings, specOf, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render, toSvg } from './svg.js';
 import { checkRendered } from './check.js';
-import { coverageLine, links, parseSource, unsureLines, verifyReport } from './verify.js';
+import { coverageLine, levelLines, links, parseSource, unsureLines, verifyReport } from './verify.js';
+import { VERSION } from './version.js';
 import { trace, traceLines } from './trace.js';
 import { coverageLines, coverageReport } from './coverage.js';
 const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   render a figure; a spec on stdin with -
@@ -45,11 +47,72 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   rende
        flowfig open <figure.svg> [--html <path>]          show the figure in the default browser
        flowfig from-mermaid <file.mmd|file.md|-> [--out <dir>]   convert Mermaid diagrams to specs
        flowfig gif <figure.svg> [out.gif] [--step <n>] [--dark] [--fps <n>] [--scale <n>] [--mp4]   write an animated GIF
-flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only), --no-verify (render only)`;
+       flowfig frames <figure.svg> [out.png] [--step <n>] [--dark] [--fps <n>] [--every <ms>] [--scale <n>] [--open]   write one PNG sheet of the key frames
+flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only), --no-verify (render only), --scene <id> (render one level), --script (add the script that opens a box on a click)
+flowfig --version, -v                               print the version`;
 function usage(message) {
     console.error(message);
     process.exit(2);
 }
+async function withBrowser(name, work) {
+    const found = findBrowser({ platform: process.platform, env: process.env, exists: existsSync });
+    if (!found.path)
+        usage([`${name} needs Chrome, Edge, Chromium or Brave. Checked:`, ...found.checked, 'Set CHROME_PATH to the browser program.'].join('\n'));
+    const temp = mkdtempSync(join(tmpdir(), `flowfig-${name}-`));
+    let launching;
+    let cleaning;
+    const cleanup = () => (cleaning ??= (async () => {
+        await (await launching?.catch(() => undefined))?.close();
+        try {
+            // Windows can hold a file lock briefly after the exit, so retry.
+            rmSync(temp, { recursive: true, force: true, maxRetries: 10 });
+        }
+        catch (e) {
+            console.error(`warning: could not remove ${temp}: ${e.message}`);
+        }
+    })());
+    let stopped = 0;
+    const yieldLoop = () => new Promise((done) => setImmediate(done));
+    // A write comes right after this check, so a signal must run its handler first.
+    const run = {
+        written: [],
+        proceed: async () => {
+            await yieldLoop();
+            if (stopped)
+                throw new Error('stopped');
+        },
+    };
+    // Keep the handlers: a second signal must not end the process mid-cleanup.
+    const onSignal = (signal) => {
+        if (stopped)
+            return;
+        stopped = signal === 'SIGINT' ? 130 : 143;
+        void (run.onStop?.() ?? Promise.resolve())
+            .then(() => run.written.forEach((f) => rmSync(f, { force: true })))
+            .then(cleanup)
+            .finally(() => process.exit(stopped));
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    let code = 0;
+    try {
+        launching = launch(found.path, join(temp, 'profile'));
+        await work((await launching).cdp, run);
+    }
+    catch (e) {
+        if (!stopped)
+            console.error(`${name}: ${e.message}`);
+        code = 1;
+    }
+    finally {
+        await cleanup();
+    }
+    // A late signal runs its handler in this await, before the exit.
+    await yieldLoop();
+    if (stopped)
+        run.written.forEach((f) => rmSync(f, { force: true }));
+    process.exit(stopped || code);
+}
 const args = process.argv.slice(2);
 const flag = (name) => {
     const i = args.indexOf(name);
@@ -73,6 +136,10 @@ if (!args[0] || ['help', '--help', '-h'].includes(args[0])) {
         usage(USAGE);
     process.exit(0);
 }
+if (['--version', '-v'].includes(args[0])) {
+    console.log(VERSION);
+    process.exit(0);
+}
 if (args[0] === 'docs') {
     const topic = args[1];
     if (topic && !Object.hasOwn(TOPICS, topic))
@@ -154,10 +221,12 @@ if (args[0] === 'verify') {
     else {
         const n = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
         for (const f of findings)
-            console.log(`${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.figure}: ${f.message}`);
+            console.log(`${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.figure}: ${f.scene ? `[${f.scene}] ` : ''}${f.message}`);
         console.log(`${n(errors, 'error')}, ${n(findings.length - errors, 'warning')}`);
         for (const c of coverage) {
             console.log(coverageLine(c.figure, c));
+            for (const l of levelLines(c))
+                console.log(l);
             for (const l of unsureLines(c))
                 console.log(l);
         }
@@ -266,56 +335,20 @@ if (args[0] === 'gif') {
         usage(`${path}: no width and height on the <svg> element`);
     if (!existsSync(dirname(resolve(out))))
         usage(`${out}: the folder does not exist`);
-    const found = findBrowser({ platform: process.platform, env: process.env, exists: existsSync });
-    if (!found.path)
-        usage(['gif needs Chrome, Edge, Chromium or Brave. Checked:', ...found.checked, 'Set CHROME_PATH to the browser program.'].join('\n'));
     const line = (file, frames, bytes) => `${file} — ${frames} frame${frames === 1 ? '' : 's'}, ${(frames / fps).toFixed(1)} s, ${(bytes / 1048576).toFixed(1)} MB`;
-    const temp = mkdtempSync(join(tmpdir(), 'flowfig-gif-'));
-    let launching;
-    let cleaning;
-    const cleanup = () => (cleaning ??= (async () => {
-        await (await launching?.catch(() => undefined))?.close();
-        try {
-            // Windows can hold a file lock briefly after the exit, so retry.
-            rmSync(temp, { recursive: true, force: true, maxRetries: 10 });
-        }
-        catch (e) {
-            console.error(`warning: could not remove ${temp}: ${e.message}`);
-        }
-    })());
-    const written = [];
-    let ffmpeg, ffmpegDone = Promise.resolve(), stopped = 0;
-    const yieldLoop = () => new Promise((done) => setImmediate(done));
-    // Keep the handlers: a second signal must not end the process mid-cleanup.
-    const onSignal = (signal) => {
-        if (stopped)
-            return;
-        stopped = signal === 'SIGINT' ? 130 : 143;
-        ffmpeg?.kill('SIGKILL');
-        void ffmpegDone
-            .then(() => written.forEach((f) => rmSync(f, { force: true })))
-            .then(cleanup)
-            .finally(() => process.exit(stopped));
-    };
-    process.on('SIGINT', onSignal);
-    process.on('SIGTERM', onSignal);
-    // A write comes right after this check, so a signal must run its handler first.
-    const proceed = async () => {
-        await yieldLoop();
-        if (stopped)
-            throw new Error('stopped');
-    };
-    let code = 0;
-    try {
-        launching = launch(found.path, join(temp, 'profile'));
-        const browser = await launching;
+    await withBrowser('gif', async (cdp, run) => {
+        let ffmpeg, ffmpegDone = Promise.resolve();
+        run.onStop = () => {
+            ffmpeg?.kill('SIGKILL');
+            return ffmpegDone;
+        };
         const viewport = { width: Math.ceil(Number(size[1])), height: Math.ceil(Number(size[2])) };
-        const { pngs } = await captureFrames(browser.cdp, pageHtml(svg, basename(path)), { ...viewport, scale, fps, dark });
+        const { pngs } = await captureFrames(cdp, pageHtml(svg, basename(path)), { ...viewport, scale, fps, dark });
         const wait = delays(pngs.length, fps);
         // The GIF keeps the PNG bytes: a decoded 2400 x 1600 frame is 15 MB.
         const gif = await encodeGif(pngs.map((png, i) => ({ load: () => decodePng(png), delay: wait[i], same: i > 0 && png.equals(pngs[i - 1]) })));
-        await proceed();
-        written.push(out);
+        await run.proceed();
+        run.written.push(out);
         writeFileSync(out, gif);
         console.log(line(out, pngs.length, gif.length));
         if (gif.length > 10485760)
@@ -326,8 +359,8 @@ if (args[0] === 'gif') {
             if (spawnSync(ffmpegBin, ['-version']).error)
                 console.error('gif: no ffmpeg on the PATH, so no MP4. The GIF is written.');
             else {
-                await proceed();
-                written.push(mp4Path);
+                await run.proceed();
+                run.written.push(mp4Path);
                 // yuv420p needs an even width and height, so the pad filter adds a pixel.
                 ffmpeg = spawn(ffmpegBin, [
                     '-y',
@@ -358,7 +391,7 @@ if (args[0] === 'gif') {
                     ffmpeg.once('error', () => done(-1));
                     ffmpeg.once('close', done);
                 }));
-                await proceed();
+                await run.proceed();
                 if (status !== 0) {
                     rmSync(mp4Path, { force: true });
                     throw new Error(`ffmpeg failed: ${stderr.trim()}`);
@@ -366,26 +399,93 @@ if (args[0] === 'gif') {
                 console.log(line(mp4Path, pngs.length, statSync(mp4Path).size));
             }
         }
-    }
-    catch (e) {
-        if (!stopped)
-            console.error(`gif: ${e.message}`);
-        code = 1;
-    }
-    finally {
-        await cleanup();
-    }
-    // A late signal runs its handler in this await, before the exit.
-    await yieldLoop();
-    if (stopped)
-        written.forEach((f) => rmSync(f, { force: true }));
-    process.exit(stopped || code);
+    });
+}
+if (args[0] === 'frames') {
+    args.shift();
+    const dark = flag('--dark'), opening = flag('--open');
+    const fps = value('--fps') ?? 20, scale = value('--scale') ?? 1, step = value('--step'), every = value('--every');
+    if (!Number.isInteger(fps) || fps > 50)
+        usage('--fps needs a whole number from 1 to 50');
+    const unknown = args.find((a) => a.startsWith('-'));
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    const [path, outArg] = args;
+    if (!path)
+        usage('usage: flowfig frames <figure.svg> [out.png] [--step <n>] [--dark] [--fps <n>] [--every <ms>] [--scale <n>] [--open]');
+    if (!path.endsWith('.svg'))
+        usage(`${path}: expected a .svg path`);
+    const props = (() => {
+        try {
+            return loadSpec(path);
+        }
+        catch (e) {
+            return usage(e.message);
+        }
+    })();
+    const count = props.steps?.length ?? 0;
+    if (!count)
+        usage(`${path}: frames needs a figure with steps; this figure has 0`);
+    if (step !== undefined && (!Number.isInteger(step) || step > count))
+        usage(`--step needs a whole number from 1 to ${count}`);
+    const fig = step === undefined ? props : { ...props, steps: [props.steps[step - 1]] };
+    const svg = step === undefined ? readFileSync(path, 'utf8') : toSvg(fig);
+    const { tiles, frames } = keyFrames(fig, { fps, every, step });
+    if (tiles.length > 64)
+        usage(`${path}: ${tiles.length} tiles; the sheet holds 64 or fewer. Use --step <n> or a larger --every <ms>.`);
+    const out = outArg ?? path.replace(/\.svg$/, step === undefined ? '-frames.png' : `-step${step}-frames.png`);
+    const size = /<svg\b[^>]*?\swidth="([\d.]+)"[^>]*?\sheight="([\d.]+)"/.exec(svg);
+    if (!size)
+        usage(`${path}: no width and height on the <svg> element`);
+    if (!existsSync(dirname(resolve(out))))
+        usage(`${out}: the folder does not exist`);
+    const [w, h] = [Number(size[1]), Number(size[2])];
+    const grid = sheetGrid(tiles.length, w, h, scale);
+    const loopMs = Math.round((frames * 1000) / fps);
+    await withBrowser('frames', async (cdp, run) => {
+        // A fractional device scale draws paused opacity animations two ways on alternate frames.
+        const shot = await captureFrames(cdp, pageHtml(svg, basename(path), '', '', '<style>svg { width: 100% }</style>'), {
+            width: grid.tile,
+            height: grid.tileH,
+            scale: 1,
+            fps,
+            dark,
+            frames: tiles.map((t) => t.frame),
+        });
+        if (Math.abs(Math.round((shot.loopMs * fps) / 1000) - frames) > 1)
+            throw new Error(`${path}: the SVG loop is ${Math.round(shot.loopMs)} ms but its spec gives ${loopMs} ms. Render the figure again.`);
+        const header = `${basename(path)} · ${tiles.length} tiles of ${frames} frames at ${fps} fps · loop ${loopMs} ms`;
+        const sheet = await captureFrames(cdp, pageHtml(sheetSvg(tiles, shot.pngs, grid, { header, fps, dark, scale }), basename(out)), {
+            width: grid.width,
+            height: grid.height,
+            scale: 1,
+            fps,
+            dark,
+        });
+        const png = sheet.pngs[0];
+        await run.proceed();
+        run.written.push(out);
+        writeFileSync(out, png);
+        const rows = tiles.map((t) => [
+            `#${t.frame}`,
+            `${Math.round((t.frame * 1000) / fps)} ms`,
+            `step ${t.step}${t.beat ? ` beat ${t.beat}` : ''}`,
+            t.kinds.join('+'),
+        ]);
+        const widths = [0, 1, 2, 3].map((c) => Math.max(...rows.map((r) => r[c].length)));
+        tiles.forEach((t, i) => console.log([...rows[i].map((v, c) => v.padEnd(widths[c])), t.text].join(' ') + (t.say ? `  "${t.say}"` : '')));
+        console.log(`${out} — ${tiles.length} tiles of ${frames} frames at ${fps} fps, ${grid.cols} x ${grid.rows} grid, ${grid.width} x ${grid.height} px, ${(png.length / 1048576).toFixed(1)} MB`);
+        if (grid.warning)
+            console.error(grid.warning);
+        if (opening)
+            await openFile(out);
+    });
 }
 const command = args[0] === 'check' ? args.shift() : 'render';
 const json = flag('--json'), strict = flag('--strict'), skip = flag('--no-check'), skipVerify = flag('--no-verify'), open = flag('--open');
 if (command === 'check' && open)
     usage('--open works with a render, not with check');
-const opts = { width: value('--width'), minText: value('--min-text') };
+const opts = { width: value('--width'), minText: value('--min-text'), scene: option('--scene'), script: flag('--script') };
 const unknown = args.find((a) => a.startsWith('-') && a !== '-');
 if (unknown)
     usage(`unknown flag ${unknown}`);
@@ -393,8 +493,18 @@ const [input, out] = args;
 if (!input)
     usage(USAGE);
 const props = await load(input);
-const rendered = skip ? undefined : render(props, opts);
-const findings = rendered ? sortFindings(checkRendered(props, opts, rendered.scene), strict) : [];
+const drawn = () => {
+    try {
+        return render(props, opts);
+    }
+    catch (e) {
+        if (!e.message.endsWith('has no level to open'))
+            throw e;
+        return usage(e.message);
+    }
+};
+const rendered = skip ? undefined : drawn();
+const findings = rendered ? sortFindings(checkRendered(props, opts, rendered.scene, rendered.levels), strict) : [];
 const errors = findings.filter((f) => f.severity === 'error').length;
 const report = (print, tty, extra = []) => {
     const paint = (s) => tty && !process.env.NO_COLOR ? s.replace(/^(error {3}|warning )/, (w) => `\x1b[${w[0] === 'e' ? 31 : 33}m${w}\x1b[0m`) : s;
@@ -412,7 +522,7 @@ const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/,
 report(console.error, process.stderr.isTTY, errors ? [] : [...summaryLines(props), ...(skipVerify ? [] : verifyLines(props, dest))]);
 if (errors)
     process.exit(1);
-const withSpec = svgWithSpec(props, opts, rendered?.svg);
+const withSpec = svgWithSpec(props, opts, (rendered ?? drawn()).svg);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);
 if (open) {

package/dist/diff.d.ts

@@ -4,6 +4,8 @@ export type Change = {
     op: 'added' | 'removed' | 'changed';
     id: string;
     detail?: string;
+    /** The path line of the level, for a change inside a box. */
+    path?: string;
 };
 export declare function diff(before: FlowProps, after: FlowProps): Change[];
 export declare function formatDiff(changes: Change[], as: 'text' | 'md'): string;