flowfig 0.6.0 → 0.8.0

package/README.md

@@ -22,7 +22,7 @@ A diagram in a repo drifts from the code. Someone renames a function, and the di
 check fails, so no one sees the drift.
 
 flowfig links each part of a diagram to the code that it draws. `flowfig verify` fails when a linked file or symbol is
-gone. Run `verify` in CI, and a stale diagram fails the pull request.
+gone, and warns when the code does not make an edge. Run `verify` in CI, and a stale diagram fails the pull request.
 
 ## Fail CI when the diagram drifts
 
@@ -36,12 +36,14 @@ Rename `verifyPassword` to `checkPassword`. Then `verify` fails with exit code 1
 
 ```console
 $ npx flowfig verify login.svg
-error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not found
+error    missing-symbol     login.svg: box "verify" -> src/auth/login.ts#verifyPassword: symbol not defined
 1 error, 0 warnings
+login.svg: 0 of 1 boxes defined
 ```
 
-`verify` checks that each linked file exists and that the symbol name still occurs in it. A link to a Markdown file can
-name a heading, so a process diagram can follow its SOP document.
+`verify` checks that each linked file exists and that it defines the symbol. It also checks each edge against the code
+(see [Verify in CI](#verify-in-ci)). A link to a Markdown file can name a heading, so a process diagram can follow its SOP
+document.
 
 The GitHub Action runs `verify` on every figure in a pull request. For each SVG that the PR changes, it comments the old
 image, the new image and the spec changes. It also names each figure whose linked code the PR changes.
@@ -63,7 +65,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.6.0
+      - uses: iamalvisng/flowfig@v0.8.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -252,7 +254,7 @@ Each SVG from the CLI carries its own spec. These commands made the rail-only fi
 npx flowfig --spec docs/checkout.svg > checkout.json   # print the spec in the SVG
 # edit checkout.json: set "props.rail" to "only"
 npx flowfig checkout.json docs/checkout-rail-only.svg
-npx flowfig verify docs/checkout.svg                    # check that each source still exists
+npx flowfig verify docs/checkout.svg                    # check each source and each edge against the code
 npx flowfig diff old.svg docs/checkout.svg              # list what changed in the spec
 ```
 
@@ -431,6 +433,23 @@ fails when the file or the symbol is gone. The action runs `verify` on every fig
 the new image for each SVG the PR changes, with the spec changes as a list, and it names each figure whose linked code the PR
 changes.
 
+`verify` prints one count line for each figure, and gives each edge one result:
+
+```console
+docs/login.svg: 7 of 7 boxes defined; edges: 9 found, 0 not found, 1 unsure, 1 not checked
+```
+
+- found: the caller code calls or references the callee through an import, the same file or a typed receiver.
+- not found: the caller code does not. `verify` warns, and `--strict` makes it an error.
+- unsure: `verify` cannot decide, for example when a receiver has no declared type. `verify` lists it with the reason. It never fails CI.
+- not checked: the edge has no `source`, or the language is not supported.
+
+A method source is `path#Owner.name`. An edge `source` names the function that makes the call.
+
+`via` on an edge names the route, queue, topic, table, file or key that both sides use. For a `via` edge, found means that the caller code and the callee file both use that token. It does not prove that a handler serves it.
+
+Edge checks support TypeScript/JavaScript, Python, Go, Java, C# and Rust. Other files keep the name check for boxes.
+
 A process figure for a team links its boxes to the SOP document, not to code: `"source": "docs/sop/refunds.md#step-3-approve-or-reject"`. The symbol is the heading as a GitHub anchor. If the heading is gone, `verify` fails.
 
 ```yaml
@@ -450,7 +469,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - uses: iamalvisng/flowfig@v0.6.0
+      - uses: iamalvisng/flowfig@v0.8.0
         with:
           figures: 'docs/**/*.svg' # default **/*.svg
 ```
@@ -523,7 +542,8 @@ writeFileSync('first.svg', toSvg(spec));
 - `check(spec, options)` returns the findings. It also takes `width` and `minText`.
 - `render(spec, options)` returns `{ svg, scene }`. The scene is the layout that the check reads. Its shape can change.
 
-`flowfig/verify` is for Node only. It exports `verify`, `links`, `owners` and `parseSource`, the same checks as `flowfig verify`.
+`flowfig/verify` is for Node only. It exports `verify`, `verifyReport` (the findings and the counts), `links`, `owners` and `parseSource`, the same checks
+as `flowfig verify`.
 
 `toSvg` does not put the spec in the SVG. Only the CLI adds the spec, which `--spec` reads back.
 

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,10 +44,12 @@ 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))
+    for (const [who, source, via] of owners(fig)) {
         if (source != null && !parseSource(source))
             out.push(warn('bad-source', [], `${who}: source "${source}" is not path or path#symbol`));
+        if (via != null && (typeof via !== 'string' || !/^\S+$/.test(via)))
+            out.push(warn('bad-source', [], `${who}: via ${JSON.stringify(via)} is not a string of one word`));
+    }
     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;
@@ -72,7 +73,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 +106,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 +135,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 +149,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 +164,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 +187,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 +228,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 +260,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 +274,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 })];
+}