flowfig 0.6.0 → 0.7.0

package/README.md

@@ -63,7 +63,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.6.0
+      - uses: iamalvisng/flowfig@v0.7.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -450,7 +450,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.6.0
+      - uses: iamalvisng/flowfig@v0.7.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```

package/dist/browser.d.ts

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

package/dist/browser.js

@@ -1,5 +1,5 @@
-// 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, spawnSync } from 'node:child_process';
+import * as os from 'node:os';
 import { win32 } from 'node:path';
 const MAC = ['Google Chrome', 'Microsoft Edge', 'Chromium', 'Brave Browser'].map((n) => `/Applications/${n}.app/Contents/MacOS/${n}`);
 const LINUX = [
@@ -18,7 +18,7 @@ const WINDOWS = [
     'BraveSoftware\\Brave-Browser\\Application\\brave.exe',
     'Chromium\\Application\\chrome.exe',
 ];
-/** The first capture browser that exists. `CHROME_PATH` wins. Pure apart from `exists`. */
+/** The first capture browser that exists. `CHROME_PATH` wins. */
 export function findBrowser(o) {
     const { env } = o;
     const paths = env.CHROME_PATH
@@ -36,7 +36,6 @@ export function findBrowser(o) {
     }
     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',
@@ -46,22 +45,22 @@ export function launch(path, profile, timeoutMs = 30_000) {
         '--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.
+        // GPU raster gave different pixels run to run on rounded corners.
         '--disable-gpu',
-        // A transform animation (the timeline playhead) runs on the compositor thread, so a seek can draw a stale x under load.
+        // A seek can draw a stale transform x under load on the compositor thread.
         '--disable-threaded-animation',
     ];
-    // Chrome refuses to start as root without it, for example in a Docker container.
+    // Chrome refuses to start as root without it, for example in Docker.
     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.
+        // Not on Windows: a process group there 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.
+    // The browser reads fd 3 and writes 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
+    out.on('error', () => { });
     let tail = '', dead = null, nextId = 1;
     child.stderr.on('data', (d) => (tail = (tail + d.toString()).slice(-2048)));
     const pending = new Map();
@@ -72,10 +71,10 @@ export function launch(path, profile, timeoutMs = 30_000) {
             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.
+    // A helper can outlive the browser and keep a pipe open.
     const killGroup = () => {
         try {
-            // Windows has no process group: taskkill /T stops the helpers of the browser too.
+            // Windows has no process group: taskkill /T stops the helpers.
             if (process.platform === 'win32') {
                 if (child.pid)
                     spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
@@ -84,18 +83,16 @@ export function launch(path, profile, timeoutMs = 30_000) {
             else if (child.pid)
                 process.kill(-child.pid, 'SIGKILL');
         }
-        catch {
-            // the group is already gone
-        }
+        catch { }
     };
     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
+            out.destroy(); // The write end of fd 3 does not close by itself.
             killGroup();
-            setTimeout(() => end(stopped(code)), 1000).unref(); // in case a pipe stays open after the group kill
+            setTimeout(() => end(stopped(code)), 1000).unref(); // A pipe can stay open after the group kill.
         });
         child.once('close', (code) => end(stopped(code)));
     });
@@ -123,7 +120,6 @@ export function launch(path, profile, timeoutMs = 30_000) {
         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);
@@ -146,7 +142,7 @@ export function launch(path, profile, timeoutMs = 30_000) {
             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.
+    // Chrome takes about 10 s to exit after Browser.close.
     const close = async () => {
         killGroup();
         await closed;
@@ -156,50 +152,62 @@ export function launch(path, profile, timeoutMs = 30_000) {
         throw e;
     });
 }
-/** Set the page, pause the animations and take one PNG per frame time. */
+// Measured: 4 tabs halve the capture time; 8 tabs gain 15% more.
+const MAX_TABS = 4;
+const MIN_FRAMES_PER_TAB = 8;
 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;
+    const open = async () => {
+        const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank', newWindow: true });
+        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 });
+        await send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-color-scheme', value: o.dark ? 'dark' : 'light' }] });
+        // 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 });
+        // 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 };
+    })()`);
+        return { send, run, info };
     };
-    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 first = await open();
+    const { info } = first;
     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'));
-    }
+    // 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 tabs = [first, ...(await Promise.all(Array.from({ length: count - 1 }, open)))];
+    const pngs = Array.from({ length: n });
+    await Promise.all(tabs.map(async ({ send, run }, k) => {
+        for (let i = k; i < n; i += count) {
+            const t = (i * 1000) / o.fps;
+            await run(`(() => {
+          for (const a of document.getAnimations()) a.currentTime = ${t};
+          document.querySelector('svg').setCurrentTime(${t / 1000});
+          // 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[i] = 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.d.ts

@@ -1,14 +1,16 @@
-import { type FigTheme, type FlowProps } from './model.ts';
+import { type FigTheme, type FlowProps, type LanePlan } from './model.ts';
 import type { Finding, Scene } from './scene.ts';
-/** Ids that point nowhere, ids used twice, steps with nothing in them. The renderers skip these without a word. */
+import type { 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 = {
     width?: number;
     minText?: number;
 };
-/** Layout faults in what a renderer drew, and text that the target width shrinks below `minText`. */
 export declare function checkScene(scene: Scene, { width, minText }?: CheckOptions): Finding[];
 /** The WCAG contrast ratio of two colors, rounded to 2 places; null if either cannot be read. */
 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[];

package/dist/check.js

@@ -1,13 +1,12 @@
-// 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, dayOf, isLanesLayout, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
+import { DARK, LIGHT, ON_ACCENT, TONES, edgeId, isGroup, dayOf, isLanesLayout, lanePlan, validAt, laneColumns, nodes, str, toBeat, } from './model.js';
+import { layoutRail } from './rail.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 });
 const warn = (rule, ids, message) => ({ rule, severity: 'warning', ids, message });
 const groupIds = (g) => [...(g.id ? [g.id] : []), ...g.children.flatMap((c) => (isGroup(c) ? groupIds(c) : []))];
-/** Ids that point nowhere, ids used twice, steps with nothing in them. The renderers skip these without a word. */
+/** Faults in the spec: dangling ids, duplicate ids, empty steps. The renderers skip them silently. */
 export function checkSpec(fig) {
     const out = [];
     const boxIds = nodes(fig.layout).map((n) => n.id);
@@ -45,7 +44,6 @@ export function checkSpec(fig) {
         if (e.quiet && !used.has(edges[i]))
             out.push(err('hidden-edge', [edges[i]], `edge "${edges[i]}" is quiet and no beat uses it, so the figure never shows it`));
     });
-    // A link with a bad form never verifies, so say so here, where the spec is checked.
     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`));
@@ -72,7 +70,6 @@ export function checkSpec(fig) {
             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];
@@ -106,18 +103,16 @@ export function checkSpec(fig) {
             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`. */
 const at = ([p0, p1, p2, p3], t) => {
     const u = 1 - 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.
+// Margins stop edges along a border and pills edge to edge from counting as touches.
 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;
 const px = (n) => Math.round(n * 10) / 10;
-/** Layout faults in what a renderer drew, and text that the target width shrinks below `minText`. */
 export function checkScene(scene, { width = 830, minText = 10 } = {}) {
     const out = [];
     for (const b of scene.boxes)
@@ -137,7 +132,6 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
             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) {
@@ -152,7 +146,6 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 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));
@@ -168,7 +161,6 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
                 out.push(warn('stub-crosses-edge', [f.id, e.id], `the stub of edge "${f.id}" crosses edge "${e.id}"`));
             }
         }
-    // A stub pill or an edge label sits inside one band: a pill across a band border reads as part of two lanes.
     for (const f of scene.edges.filter((e) => e.label))
         for (const l of scene.lanes ?? []) {
             const [p, r] = [f.label, l.rect];
@@ -192,7 +184,6 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
         out.push(warn('small-text', [], `at ${width} px the smallest text is ${px(shown)} px (minimum ${minText} px)`));
     return out;
 }
-/** Red, green and blue from a hex, rgb() or hsl() color; null for a CSS variable or a named color. */
 function rgb(color) {
     const s = color.trim().toLowerCase();
     let m = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
@@ -234,11 +225,10 @@ const PAIRS = [
     ['fg', 'tint'],
     ['muted', 'tint'],
 ];
-/** A color mixed over a base at pct %, per channel like the CSS color-mix. The default is the active-box tint: 10 % accent over the surface. */
 function tintOf(t, color = t.accent, base = t.surface, pct = 10) {
     const [a, s] = [rgb(color), rgb(base)];
     if (!a || !s)
-        return base; // an unreadable color is reported by its own pairs
+        return base;
     return `rgb(${a.map((v, i) => (pct / 100) * v + (1 - pct / 100) * s[i]).join(',')})`;
 }
 /** Text the reader cannot read: each text and background pair, in light, dark and any custom theme, needs 4.5:1 (WCAG AA). */
@@ -267,7 +257,6 @@ export function checkTheme(theme = {}) {
             else if (r < 4.5)
                 out.push(err('low-contrast', [], `${name} theme: ${fg} on ${bg} has contrast ${r}:1 (minimum 4.5:1)`));
         }
-        // A toned box shows fg and muted text on its tone tint: 8 % over bg (off, trail) and 10 % over surface (active).
         for (const [tname, tone] of Object.entries(TONES)) {
             for (const bg of [tintOf(t, tone, t.bg, 8), tintOf(t, tone, t.surface, 10)]) {
                 for (const fg of ['fg', 'muted']) {
@@ -282,3 +271,18 @@ export function checkTheme(theme = {}) {
         out.push(warn('color-not-checked', [], `cannot read the color "${c}", so its contrast is not checked`));
     return out;
 }
+export function planFor(fig, opts) {
+    if (fig.timeline || !fig.lanes || !isLanesLayout(fig.layout))
+        return null;
+    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) {
+    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 })];
+}

package/dist/cli.js

@@ -7,29 +7,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-/**
- * Render a figure as one animated SVG — for a README, a PR, an issue, a blog post — and check it first.
- *
- *   flowfig - out.svg < spec.json        # a spec on stdin: nothing is left on disk
- *   flowfig spec.json out.svg            # a spec file
- *   flowfig figure.ts out.svg            # a module whose default export is a spec
- *   flowfig --spec out.svg               # print back the spec the SVG carries
- *   flowfig check <input> [--json]       # list the faults; the input can also be an SVG this wrote
- *   flowfig verify <input>... [--root dir]   # check that the code each figure links to still exists
- *   flowfig diff <old> <new> [--json|--md]   # list the spec changes between two figures
- *   flowfig docs                         # print the full guide (Markdown)
- *   flowfig mcp                          # serve check, render, verify, diff and docs over MCP (stdio)
- *   flowfig init [dir]                   # write flowfig instructions for the coding agents of a repo
- *   flowfig draw "<question>" [--out out.svg]   # ask Claude Code for a figure, then check it
- *   flowfig open figure.svg              # show the figure in the default browser
- *   flowfig gif figure.svg [out.gif]     # write an animated GIF of the figure (needs Chrome, Edge, Chromium or Brave)
- *
- * A render checks first and writes nothing on an error (--no-check skips that). --strict makes warnings errors; --width and
- * --min-text set the page width and the smallest text the reader should get.
- * --open opens the rendered SVG in the default browser (render and draw).
- *
- * Every rendered SVG carries its own spec in <metadata>, so a figure is editable later without anyone having to keep the JSON.
- */
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -46,7 +23,8 @@ import { pageHtml } from './page.js';
 import { decodePng } from './png.js';
 import { diff, formatDiff } from './diff.js';
 import { loadSpec, reportLines, sortFindings, specOf, svgWithSpec } from './load.js';
-import { check, toSvg } from './svg.js';
+import { check, render, toSvg } from './svg.js';
+import { checkRendered } from './check.js';
 import { links, verify } from './verify.js';
 const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   render a figure; a spec on stdin with -
        flowfig check <-|spec.json|figure.ts|figure.svg>   list the faults; the input can be an SVG this wrote
@@ -60,7 +38,6 @@ 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 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)`;
-/** Bad use, not a bad figure: exit 2 with a message, not a stack trace. A declaration, so TypeScript narrows after a call. */
 function usage(message) {
     console.error(message);
     process.exit(2);
@@ -90,7 +67,7 @@ if (args[0] === 'docs') {
 }
 if (args[0] === 'mcp') {
     await serve(process.stdin, process.stdout);
-    // A pipe write is asynchronous: wait until the queued response lines are out before the exit.
+    // A pipe write is asynchronous: wait for the queued lines before the exit.
     await new Promise((done) => process.stdout.write('', () => done(undefined)));
     process.exit(0);
 }
@@ -118,7 +95,6 @@ if (args[0] === '--spec') {
     }
     process.exit(0);
 }
-/** A spec from stdin, a JSON file, an SVG this wrote, or a module. Exit 2 with a message on any failure. */
 async function load(input) {
     try {
         if (input.endsWith('.json') || input.endsWith('.svg'))
@@ -195,7 +171,6 @@ if (args[0] === 'gif') {
         usage(`${path}: ${e.message}`);
     }
     if (step !== undefined) {
-        // One step only: render the spec again with that step, so the loop holds that step alone.
         const props = (() => {
             try {
                 return loadSpec(path);
@@ -222,24 +197,22 @@ if (args[0] === 'gif') {
         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-'));
-    // A Ctrl-C can come while the browser starts, so cleanup waits for the start before it stops the browser.
     let launching;
     let cleaning;
     const cleanup = () => (cleaning ??= (async () => {
         await (await launching?.catch(() => undefined))?.close();
         try {
-            // The retries cover Windows, where the browser can hold a file lock for a short time after the exit.
+            // 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}`);
         }
     })());
-    // The output files of this run: a stop removes them, so no partial file stays.
     const written = [];
     let ffmpeg, ffmpegDone = Promise.resolve(), stopped = 0;
     const yieldLoop = () => new Promise((done) => setImmediate(done));
-    // The handlers stay for the whole run: a second signal during the cleanup must not end the process before the cleanup ends.
+    // Keep the handlers: a second signal must not end the process mid-cleanup.
     const onSignal = (signal) => {
         if (stopped)
             return;
@@ -252,7 +225,7 @@ if (args[0] === 'gif') {
     };
     process.on('SIGINT', onSignal);
     process.on('SIGTERM', onSignal);
-    // The encode and the ffmpeg run give the event loop a turn, so a signal handler can run. A write comes straight after this check.
+    // A write comes right after this check, so a signal must run its handler first.
     const proceed = async () => {
         await yieldLoop();
         if (stopped)
@@ -265,7 +238,7 @@ if (args[0] === 'gif') {
         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 wait = delays(pngs.length, fps);
-        // The GIF keeps the PNG bytes, not the pixels: a decoded 2400 x 1600 frame is 15 MB.
+        // 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);
@@ -275,21 +248,37 @@ if (args[0] === 'gif') {
             console.error(`warning: ${out} is ${(gif.length / 1048576).toFixed(1)} MB, over 10 MB. Try --step <n>, a lower --fps or a lower --scale.`);
         if (mp4) {
             const mp4Path = out.replace(/(\.gif)?$/, '.mp4');
-            // FLOWFIG_FFMPEG replaces the PATH lookup, so a test can hide ffmpeg and keep the full PATH.
             const ffmpegBin = process.env.FLOWFIG_FFMPEG ?? 'ffmpeg';
             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);
-                // yuv420p needs an even width and height, so the pad filter adds a pixel where needed.
+                // yuv420p needs an even width and height, so the pad filter adds a pixel.
                 ffmpeg = spawn(ffmpegBin, [
-                    ...['-y', '-loglevel', 'error', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-'],
-                    ...['-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', mp4Path],
+                    '-y',
+                    '-loglevel',
+                    'error',
+                    '-f',
+                    'image2pipe',
+                    '-framerate',
+                    String(fps),
+                    '-c:v',
+                    'png',
+                    '-i',
+                    '-',
+                    '-vf',
+                    'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+                    '-c:v',
+                    'libx264',
+                    '-pix_fmt',
+                    'yuv420p',
+                    mp4Path,
                 ]);
                 let stderr = '';
                 ffmpeg.stderr.on('data', (d) => (stderr += d));
-                ffmpeg.stdin.on('error', () => { }); // ffmpeg can exit before it reads all the input; the exit code reports that
+                // ffmpeg can exit early; the exit code reports that.
+                ffmpeg.stdin.on('error', () => { });
                 ffmpeg.stdin.end(Buffer.concat(pngs));
                 const status = await (ffmpegDone = new Promise((done) => {
                     ffmpeg.once('error', () => done(-1));
@@ -312,7 +301,7 @@ if (args[0] === 'gif') {
     finally {
         await cleanup();
     }
-    // A signal that came in the last turn runs its handler here, before the exit.
+    // A late signal runs its handler in this await, before the exit.
     await yieldLoop();
     if (stopped)
         written.forEach((f) => rmSync(f, { force: true }));
@@ -330,12 +319,10 @@ const [input, out] = args;
 if (!input)
     usage(USAGE);
 const props = await load(input);
-const findings = skip ? [] : sortFindings(check(props, opts), strict);
+const rendered = skip ? undefined : render(props, opts);
+const findings = rendered ? sortFindings(checkRendered(props, opts, rendered.scene), strict) : [];
 const errors = findings.filter((f) => f.severity === 'error').length;
-/** The findings for a person: one line each, colored only on a terminal, then the counts. A render prints them to stderr, next to
- * its own output. A clean render still prints `0 errors, 0 warnings`: the agent copies that line into its reply. */
 const report = (print, tty) => {
-    // The severity field is 8 characters wide, so the painted field keeps the same width.
     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;
     for (const line of reportLines(props, findings, !skip))
         print(paint(line));
@@ -351,8 +338,7 @@ report(console.error, process.stderr.isTTY);
 if (errors)
     process.exit(1);
 const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
-// The spec rides along in <metadata>: an SVG is then its own source, and no JSON has to be kept.
-const withSpec = svgWithSpec(props, opts);
+const withSpec = svgWithSpec(props, opts, rendered?.svg);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);
 if (open) {

package/dist/diff.js

@@ -1,9 +1,6 @@
-// The spec diff: what a PR changed in a figure, by id. The SVG geometry follows from the spec, so the spec is the diff.
 import { edgeId, isGroup, str, toBeat } from './model.js';
 const show = (v) => (v == null ? '(none)' : `"${str(v)}"`);
-/** The fields that changed, as `name "old" -> "new"` parts; empty when equal. */
 const fields = (a, b, names) => names.filter((k) => str(a[k]) !== str(b[k])).map((k) => `${String(k)} ${show(a[k])} -> ${show(b[k])}`);
-/** Compare two maps by key. The order is stable: changed first, then removed, then added. */
 function compare(kind, before, after, fieldsOf) {
     const out = [];
     for (const [id, a] of before) {
@@ -28,7 +25,6 @@ const messages = (fig) => new Map((fig.steps ?? [])
 export function diff(before, after) {
     const boxes = (f) => {
         const m = new Map();
-        // The group is its label, else its id; the top level has none.
         const walk = (g, parent) => g.children.forEach((c) => (isGroup(c) ? walk(c, c.label != null ? str(c.label) : c.id) : m.set(c.id, { ...c, group: parent })));
         walk(f.layout);
         return m;

package/dist/draw.d.ts

@@ -1,6 +1,5 @@
-/** A file name from the question: lower case, letters and digits, joined by -, at most 60 characters. */
+/** A file name from the question: at most 60 characters. */
 export declare function slug(question: string): string;
-/** The claude argv after the binary. The system prompt carries the agent text, the output path and the folder rule. */
 export declare function agentArgs(o: {
     question: string;
     out: string;
@@ -8,5 +7,4 @@ export declare function agentArgs(o: {
     maxTurns: number;
     model?: string;
 }): string[];
-/** Run `flowfig draw`. Prints, and returns the exit code. */
 export declare function runDraw(argv: string[]): Promise<number>;