flowfig 0.8.4 → 0.10.0

package/dist/atlas.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
+import { coverageLines, coverageReport } from './coverage.js';
+import { loadSpec, specOf } from './load.js';
+import { altText, nodes, str } from './model.js';
+import { openFile } from './open.js';
+import { esc, pageHtml } from './page.js';
+import { toSvg } from './svg.js';
+const USAGE = 'usage: flowfig atlas [--figures <glob>] [--root <dir>] [--out <dir>] [--open]';
+const CSS = `body { font: 16px/1.5 system-ui, sans-serif; margin: 0 auto; max-width: 960px; padding: 16px }
+table { border-collapse: collapse; width: 100% }
+td, th { text-align: left; padding: 6px 10px; border-bottom: 1px solid color-mix(in srgb, CanvasText 20%, transparent) }
+strong[data-state] { padding: 1px 8px; border-radius: 4px; border: 1px solid currentColor; font-size: 14px }
+strong[data-state="ok"] { color: light-dark(#116329, #7ee787) }
+strong[data-state="stale"] { color: light-dark(#8a5a00, #e3b341) }
+strong[data-state="fail"] { color: light-dark(#b42318, #ff7b72) }
+strong[data-state="none"] { color: GrayText }`;
+const badge = (f) => `<strong data-state="${f.state}">${f.state}</strong>`;
+const pageOf = (figure) => {
+    const page = figure.replace(/\.svg$/, '.html');
+    return page === 'index.html' ? 'index.figure.html' : page;
+};
+const MARK = '<meta name="generator" content="flowfig atlas">';
+const url = (path) => path.split('/').map(encodeURIComponent).join('/');
+const hrefTo = (from, to) => url(posix.relative(posix.dirname(from), to));
+export function atlasFiles({ root = process.cwd(), figures } = {}) {
+    const report = coverageReport({ root, figures });
+    const rows = report.figures.sort((a, b) => a.figure.localeCompare(b.figure));
+    if (!rows.length)
+        return new Map();
+    const specs = new Map();
+    for (const { figure } of rows) {
+        try {
+            specs.set(figure, loadSpec(JSON.parse(specOf(readFileSync(resolve(root, figure), 'utf8'), figure)), figure));
+        }
+        catch { }
+    }
+    const files = new Map();
+    const shell = (title, body) => `<!doctype html>\n<meta charset="utf-8">\n${MARK}\n<meta name="viewport" content="width=device-width, initial-scale=1">\n<title>${esc(title)}</title>\n<style>\n:root { color-scheme: light dark }\n${CSS}\n</style>\n${body}\n`;
+    for (const f of rows) {
+        const spec = specs.get(f.figure);
+        if (!spec)
+            continue;
+        const page = pageOf(f.figure);
+        const targets = nodes(spec.layout).flatMap((n) => {
+            const to = typeof n.detail === 'string' ? posix.normalize(n.detail) : '';
+            return to && specs.has(to) ? [{ n, to }] : [];
+        });
+        const hrefs = new Map(targets.map(({ n, to }) => [n.id, hrefTo(page, pageOf(to))]));
+        const svg = toSvg(spec, { links: Object.fromEntries(hrefs) });
+        const details = nodes(spec.layout)
+            .filter((n) => typeof n.detail === 'string')
+            .map((n) => {
+            const name = esc(str(n.label) || n.id);
+            const href = hrefs.get(n.id);
+            return `<li>${name}: ${href == null ? `${esc(n.detail)} (not in the atlas)` : `<a href="${esc(href)}">${esc(n.detail)}</a>`}</li>`;
+        });
+        const { title, desc } = altText(spec);
+        const before = `<style>\n${CSS}\n</style>\n<main>\n<p><a href="${esc(hrefTo(page, 'index.html'))}">All figures</a></p>\n` +
+            `<h1>${esc(f.figure)}</h1>\n<p>${badge(f)} ${esc(f.detail)}</p>\n`;
+        const after = (details.length ? `\n<h2>Details</h2>\n<ul>\n${details.join('\n')}\n</ul>` : '') +
+            `\n<details><summary>Transcript</summary><pre style="white-space: pre-wrap">${esc(desc)}</pre></details>\n</main>`;
+        files.set(page, pageHtml(svg, `${title} (${f.figure})`, before, after, `${MARK}\n`));
+    }
+    const body = rows
+        .map((f) => {
+        const spec = specs.get(f.figure);
+        const name = spec ? `<a href="${esc(url(pageOf(f.figure)))}">${esc(f.figure)}</a>` : esc(f.figure);
+        return `<tr><td>${name}</td><td>${badge(f)}</td><td>${esc(f.detail)}</td><td>${spec ? esc(altText(spec).title) : ''}</td></tr>`;
+    })
+        .join('\n');
+    files.set('index.html', shell('Figures', `<main>\n<h1>Figures</h1>\n<p>${esc(coverageLines(report).at(-1))}</p>\n<table>\n<tr><th>Figure</th><th>Health</th><th>Detail</th><th>Title</th></tr>\n${body}\n</table>\n</main>`));
+    files.set('.nojekyll', '');
+    return files;
+}
+export async function runAtlas(argv) {
+    const fail = (message, code) => (console.error(message), code);
+    const args = [...argv];
+    const open = args.includes('--open');
+    if (open)
+        args.splice(args.indexOf('--open'), 1);
+    const opts = {};
+    for (const name of ['--figures', '--root', '--out']) {
+        const at = args.indexOf(name);
+        if (at === -1)
+            continue;
+        const value = args.splice(at, 2)[1];
+        if (!value || value.startsWith('-'))
+            return fail(`${name} needs a value`, 2);
+        opts[name] = value;
+    }
+    if (args.length)
+        return fail(args[0].startsWith('-') ? `unknown flag ${args[0]}` : USAGE, 2);
+    const root = resolve(opts['--root'] ?? '.');
+    if (!existsSync(root))
+        return fail(`${root}: the folder does not exist`, 2);
+    const files = atlasFiles({ root, figures: opts['--figures'] });
+    if (!files.size)
+        return fail('no figure SVG matches', 1);
+    const out = resolve(opts['--out'] ?? 'atlas');
+    const mine = [...files.keys()].filter((p) => p !== '.nojekyll');
+    const foreign = mine.find((p) => existsSync(join(out, p)) && !readFileSync(join(out, p), 'utf8').includes(MARK));
+    if (foreign)
+        return fail(`${join(out, foreign)}: the file exists and flowfig atlas did not write it; nothing was written`, 2);
+    for (const [path, text] of files) {
+        if (!text && existsSync(join(out, path)))
+            continue;
+        mkdirSync(dirname(join(out, path)), { recursive: true });
+        writeFileSync(join(out, path), text);
+    }
+    const index = join(out, 'index.html');
+    console.log(`${index} — ${files.size - 2} figure page${files.size === 3 ? '' : 's'}`);
+    if (open) {
+        try {
+            await openFile(index);
+        }
+        catch (e) {
+            return fail(`open: ${e.message}`, 1);
+        }
+    }
+    return 0;
+}

package/dist/auto.d.ts

@@ -0,0 +1,3 @@
+import { type FigEdge, type FlowProps } from './model.ts';
+export declare const rowBreaks: WeakSet<FigEdge>;
+export declare function autoLayout(spec: FlowProps): FlowProps;

package/dist/auto.js

@@ -0,0 +1,302 @@
+import { edgeId, fitCap, idsIn, isGroup, isRows, itemWidth, nodes, toBeat, NODE_MAX_W, } from './model.js';
+const PAGE = 830, PAD = 24, SWEEPS = 8, TALL = 2.5, 
+// A 20-box chain measures 105 px for each rank.
+RANK_H = 105, MIN_TEXT = 10;
+const flat = (it) => (isGroup(it) && it.label == null && it.id == null ? it.children.flatMap(flat) : [it]);
+function seenOrder(fig) {
+    const at = new Map();
+    const byId = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    for (const s of fig.steps ?? [])
+        for (const b of s.flow)
+            for (const h of toBeat(b).hops) {
+                const e = byId.get(h.edge);
+                if (e)
+                    for (const id of h.back ? [e.to, e.from] : [e.from, e.to])
+                        if (!at.has(id))
+                            at.set(id, at.size);
+            }
+    for (const n of nodes(fig.layout))
+        if (!at.has(n.id))
+            at.set(n.id, at.size);
+    return at;
+}
+function level(items, dir, ctx) {
+    const n = items.length;
+    const unit = new Map();
+    items.forEach((it, k) => idsIn(it).forEach((id) => unit.set(id, k)));
+    const first = items.map((it) => Math.min(...idsIn(it).map((id) => ctx.at.get(id) ?? Infinity)));
+    const pairs = ctx.edges.flatMap((e) => {
+        const a = unit.get(e.from), b = unit.get(e.to);
+        return a == null || b == null || a === b ? [] : [[a, b, e]];
+    });
+    const keys = [...items.keys()].sort((p, q) => first[p] - first[q]);
+    const state = Array.from({ length: n }, () => 0);
+    const back = new Set();
+    const dfs = (u) => {
+        state[u] = 1;
+        const out = [...pairs.keys()].filter((i) => pairs[i][0] === u).sort((i, j) => first[pairs[i][1]] - first[pairs[j][1]]);
+        for (const i of out) {
+            const v = pairs[i][1];
+            if (state[v] === 1)
+                back.add(i);
+            else if (state[v] === 0)
+                dfs(v);
+        }
+        state[u] = 2;
+    };
+    for (const k of keys)
+        if (!state[k])
+            dfs(k);
+    const dag = pairs.map(([a, b], i) => (back.has(i) ? [b, a] : [a, b]));
+    const rank = Array.from({ length: n }, () => 0);
+    for (let pass = 0; pass < n; pass++)
+        for (const [a, b] of dag)
+            rank[b] = Math.max(rank[b], rank[a] + 1);
+    const ranks = Math.max(0, ...rank) + 1;
+    const layers = Array.from({ length: ranks }, () => []);
+    const layerOf = [...rank];
+    for (const k of keys)
+        layers[rank[k]].push(k);
+    const links = [];
+    const via = dag.map(() => []);
+    for (const [i, [a, b]] of dag.entries()) {
+        let prev = a;
+        for (let r = rank[a] + 1; r < rank[b]; r++) {
+            const v = layerOf.length;
+            layerOf.push(r);
+            layers[r].push(v);
+            via[i].push(v);
+            links.push([prev, v]);
+            prev = v;
+        }
+        links.push([prev, b]);
+    }
+    const pos = [];
+    const index = () => layers.forEach((l) => l.forEach((x, i) => (pos[x] = i)));
+    const crossings = () => {
+        index();
+        let c = 0;
+        for (let i = 0; i < links.length; i++)
+            for (let j = i + 1; j < links.length; j++) {
+                const [a, b] = links[i], [p, q] = links[j];
+                if (layerOf[a] === layerOf[p] && (pos[a] - pos[p]) * (pos[b] - pos[q]) < 0)
+                    c++;
+            }
+        return c;
+    };
+    let best = layers.map((l) => [...l]);
+    let fewest = crossings();
+    for (let it = 0; it < SWEEPS; it++) {
+        const down = it % 2 === 0;
+        const order = [...layers.keys()].slice(1).map((r) => (down ? r : ranks - 1 - r));
+        for (const r of order) {
+            index();
+            const bary = (x) => {
+                const ns = links.filter(([a, b]) => (down ? b : a) === x).map(([a, b]) => pos[down ? a : b]);
+                return ns.length ? ns.reduce((s, v) => s + v, 0) / ns.length : pos[x];
+            };
+            const w = new Map(layers[r].map((x) => [x, bary(x)]));
+            layers[r].sort((x, y) => w.get(x) - w.get(y));
+        }
+        const c = crossings();
+        if (c < fewest)
+            [fewest, best] = [c, layers.map((l) => [...l])];
+    }
+    const cross = dir === 'row' ? 'column' : 'row';
+    const built = items.map((it) => (isGroup(it) ? { ...it, direction: dir, children: level(it.children.flatMap(flat), dir, ctx) } : it));
+    const beside = new Map();
+    const unitOf = (k) => {
+        const leaf = beside.get(k);
+        if (leaf == null)
+            return built[k];
+        const real = best.find((l) => l.includes(k)).filter((x) => x < n);
+        const pair = [built[k], built[leaf]];
+        return { direction: 'row', children: real.indexOf(k) < (real.length - 1) / 2 ? pair.reverse() : pair };
+    };
+    const rankRow = (l) => {
+        const real = l.filter((x) => x < n);
+        return real.length === 1 ? unitOf(real[0]) : { direction: cross, children: real.map(unitOf) };
+    };
+    if (dir === 'column') {
+        const fits = (l) => itemWidth(rankRow(l), ctx.carded, ctx.edges, NODE_MAX_W) <= PAGE - 2 * PAD;
+        for (const l of best) {
+            const leaves = l
+                .filter((k) => k < n && !dag.some(([a]) => a === k) && dag.filter(([, b]) => b === k).length === 1)
+                .sort((p, q) => first[q] - first[p]);
+            for (const k of leaves) {
+                if (fits(l))
+                    break;
+                const src = dag.find(([, b]) => b === k)[0];
+                if (beside.has(src))
+                    continue;
+                const home = best.find((m) => m.includes(src));
+                const i = l.indexOf(k);
+                l.splice(i, 1);
+                beside.set(src, k);
+                if (!fits(home)) {
+                    beside.delete(src);
+                    l.splice(i, 0, k);
+                }
+            }
+        }
+    }
+    const outer = (vs, side) => vs.every((v) => {
+        const l = best[layerOf[v]];
+        const k = l.indexOf(v);
+        return (side > 0 ? l.slice(k + 1) : l.slice(0, k)).every((x) => x >= n);
+    });
+    const hints = () => via.map((vs, i) => {
+        const [a, b] = dag[i];
+        const stacked = [a, b].every((k) => best[rank[k]].filter((x) => x < n).length === 1);
+        return !back.has(i) && (!vs.length || stacked) ? 0 : outer([a, ...vs, b], 1) ? 1 : outer([a, ...vs, b], -1) ? -1 : 0;
+    });
+    const turn = (o, u, w) => Math.sign((u[0] - o[0]) * (w[1] - o[1]) - (u[1] - o[1]) * (w[0] - o[0]));
+    const drawn = (ws) => {
+        const at = [];
+        best.forEach((l, r) => l.filter((x) => x < n).forEach((x, i, real) => (at[x] = [r, i - (real.length - 1) / 2])));
+        let c = 0;
+        for (let i = 0; i < dag.length; i++)
+            for (let j = i + 1; j < dag.length; j++) {
+                const [a, b] = dag[i], [p, q] = dag[j];
+                if (a === p || a === q || b === p || b === q || ![a, b, p, q].every((x) => at[x]))
+                    continue;
+                if (ws[i] || ws[j])
+                    c += +(ws[i] === ws[j] && rank[a] < rank[q] && rank[p] < rank[b]);
+                else
+                    c += +(turn(at[a], at[b], at[p]) * turn(at[a], at[b], at[q]) < 0 && turn(at[p], at[q], at[a]) * turn(at[p], at[q], at[b]) < 0);
+            }
+        return c;
+    };
+    let ways = hints();
+    for (const i of ways.keys())
+        for (const j of ways.keys()) {
+            const wi = ways[i];
+            const [ai, bi] = dag[i], [aj, bj] = dag[j];
+            if (j <= i || !wi || wi !== ways[j] || rank[ai] >= rank[bj] || rank[aj] >= rank[bi])
+                continue;
+            for (const k of via[i].length <= via[j].length ? [i, j] : [j, i]) {
+                const units = [dag[k][0], ...via[k], dag[k][1]];
+                if (units.some((v) => !best[layerOf[v]].includes(v)))
+                    continue;
+                const kept = best.map((l) => [...l]);
+                const was = drawn(ways);
+                for (const v of units) {
+                    const l = best[layerOf[v]];
+                    l.splice(l.indexOf(v), 1);
+                    if (wi > 0)
+                        l.unshift(v);
+                    else
+                        l.push(v);
+                }
+                const now = hints();
+                if (now[k] === -wi && now[i + j - k] === wi && drawn(now) < was) {
+                    ways = now;
+                    break;
+                }
+                best = kept;
+            }
+        }
+    ways.forEach((way, i) => {
+        if (way)
+            pairs[i][2].around = dir === 'column' ? (way > 0 ? 'right' : 'left') : way > 0 ? 'below' : 'above';
+    });
+    const kept = best.filter((l) => l.some((x) => x < n));
+    const rows = kept.map(rankRow);
+    if (dir === 'row' || kept.length * RANK_H <= TALL * PAGE)
+        return rows;
+    const out = [];
+    let run = [];
+    const lines = (per) => {
+        const k = Math.ceil(run.length / per), q = Math.ceil(run.length / k);
+        return Array.from({ length: k }, (_, i) => ({ direction: 'row', children: run.slice(i * q, (i + 1) * q) }));
+    };
+    const flush = () => {
+        const folded = run.length < 4 ? undefined : [4, 3].map(lines).find((ls) => ls.every((l) => itemWidth(l, ctx.carded, ctx.edges) <= PAGE - 2 * PAD));
+        out.push(...(folded ?? run));
+        run = [];
+    };
+    rows.forEach((r, i) => {
+        if (kept[i].length === 1 && !isGroup(r))
+            run.push(r);
+        else {
+            flush();
+            out.push(r);
+        }
+    });
+    flush();
+    return out;
+}
+const pruned = (g) => ({
+    ...g,
+    children: g.children.map((c) => (isGroup(c) ? pruned(c) : c)).filter((c) => !isGroup(c) || c.children.length),
+});
+const titled = (it) => isGroup(it) && (it.label != null || it.children.some(titled));
+function smallFont(f, carded) {
+    const shown = (f.steps ?? []).flatMap((s) => s.flow.flatMap((b) => Object.values(toBeat(b).show ?? {})));
+    if (shown.some((c) => isRows(c) && c.some((r) => r.mono)))
+        return 10.5;
+    if (carded.size || f.edges.some((e) => e.label != null) || titled(f.layout))
+        return 11;
+    if ((f.steps ?? []).some((s) => s.flow.some((b) => toBeat(b).hops.some((h) => h.data != null))))
+        return 11.5;
+    if (nodes(f.layout).some((n) => n.sub != null))
+        return 12;
+    return f.steps?.length ? 13.5 : 14;
+}
+export const rowBreaks = new WeakSet();
+function fold(f, carded) {
+    const room = (PAGE * smallFont(f, carded)) / MIN_TEXT - 2 * PAD;
+    if (f.rail || itemWidth(f.layout, carded, f.edges, fitCap(f, PAGE)) <= room)
+        return f;
+    const ranks = f.layout.children;
+    const n = ranks.length;
+    const unit = new Map(ranks.flatMap((r, k) => idsIn(r).map((id) => [id, k])));
+    const ends = f.edges.filter((e) => unit.has(e.from) && unit.has(e.to)).map((e) => [unit.get(e.from), unit.get(e.to)]);
+    const across = (c) => ends.filter(([a, b]) => a < c !== b < c).length;
+    const last = Math.min(n - 1, ...f.edges.filter((e) => e.around).flatMap((e) => [e.from, e.to].map((id) => unit.get(id) ?? n)));
+    const better = (p, q) => p[0] - q[0] || p[1] - q[1] || p[2] - q[2];
+    const plans = [{ cost: [0, 0, 0], from: -1 }];
+    for (let j = 1; j <= n; j++)
+        for (let i = j - 1; i >= 0; i--) {
+            const w = itemWidth({ direction: 'row', children: ranks.slice(i, j) }, carded, f.edges);
+            if (w > room)
+                break;
+            const prev = plans[i];
+            if (!prev || (j === n && i > last))
+                continue;
+            const cost = [prev.cost[0] + 1, prev.cost[1] + (i ? across(i) : 0), Math.max(prev.cost[2], w)];
+            if (!plans[j] || better(cost, plans[j].cost) < 0)
+                plans[j] = { cost, from: i };
+        }
+    if (!plans[n] || plans[n].cost[0] < 2)
+        return f;
+    const cuts = [];
+    for (let j = n; j > 0; j = plans[j].from)
+        cuts.unshift(plans[j].from);
+    const rows = cuts.map((c, k) => ranks.slice(c, cuts[k + 1] ?? n));
+    for (const e of f.edges)
+        if (cuts.some((c) => c && unit.get(e.from) < c && unit.get(e.to) >= c))
+            rowBreaks.add(e);
+    const children = rows.map((rs) => (rs.length === 1 ? rs[0] : { direction: 'row', children: rs }));
+    return { ...f, layout: { direction: 'column', children } };
+}
+export function autoLayout(spec) {
+    if (spec.lanes || spec.timeline)
+        return spec;
+    const fig = { ...spec, layout: pruned(spec.layout) };
+    if (!fig.layout.auto)
+        return fig;
+    const carded = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => Object.keys(toBeat(b).show ?? {}))));
+    const at = seenOrder(fig);
+    const items = fig.layout.children.flatMap(flat);
+    const make = (direction) => {
+        const edges = fig.edges.map((e) => ({ ...e, around: undefined }));
+        return { ...fig, edges, layout: { direction, children: level(items, direction, { edges, at, carded }) } };
+    };
+    if (fig.layout.direction === 'row')
+        return fold(make('row'), carded);
+    if (fig.layout.direction)
+        return make(fig.layout.direction);
+    const lr = make('row');
+    return itemWidth(lr.layout, carded, lr.edges, fitCap(lr, PAGE)) + 2 * PAD <= PAGE ? lr : make('column');
+}

package/dist/browser.js

@@ -36,6 +36,8 @@ export function findBrowser(o) {
     }
     return { path: null, checked };
 }
+// Measured: 2 parallel starts on a loaded 4-CPU Linux runner took over 30 s.
+const START_MS = 120_000;
 export function launch(path, profile, timeoutMs = 30_000) {
     const args = [
         '--headless=new',
@@ -147,7 +149,7 @@ export function launch(path, profile, timeoutMs = 30_000) {
         killGroup();
         await closed;
     };
-    return cdp.send('Browser.getVersion').then(() => ({ cdp, close }), async (e) => {
+    return cdp.send('Browser.getVersion', {}, undefined, START_MS).then(() => ({ cdp, close }), async (e) => {
         await close();
         throw e;
     });

package/dist/check.js

@@ -1,6 +1,6 @@
 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, hit as curveHit } from './geometry.js';
+import { crosses, samples } from './geometry.js';
 import { textWidth } from './text.js';
 import { owners, parseSource } from './source.js';
 const err = (rule, ids, message) => ({ rule, severity: 'error', ids, message });
@@ -75,10 +75,22 @@ export function checkSpec(fig) {
     twice('edges', edges);
     const known = new Set([...boxIds, ...groups]);
     const knownEdges = new Set(edges);
+    const empty = new Set();
+    const walk = (g) => {
+        for (const c of g.children)
+            if (isGroup(c)) {
+                if (c.id != null && !nodes(c).length)
+                    empty.add(c.id);
+                walk(c);
+            }
+    };
+    walk(fig.layout);
     fig.edges.forEach((e, i) => {
         for (const end of [e.from, e.to])
             if (!known.has(end))
                 out.push(err('unknown-id', [edges[i], end], `edge "${edges[i]}" names box "${end}", which does not exist`));
+            else if (empty.has(end))
+                out.push(err('unknown-id', [edges[i], end], `edge "${edges[i]}" ends at group "${end}", which has no boxes`));
     });
     (fig.steps ?? []).forEach((s, si) => {
         const where = `step ${si + 1} ("${str(s.label)}")`;
@@ -96,6 +108,17 @@ export function checkSpec(fig) {
                     out.push(err('unknown-id', [id], `${where}: show, light or focus names box "${id}", which does not exist`));
         }
     });
+    const form = fig.timeline ? 'timeline' : fig.lanes ? 'lanes' : null;
+    if (fig.layout.auto && form)
+        out.push(warn('auto-ignored', [], `the figure sets ${form}; ${form === 'lanes' ? 'lanes place the boxes and ignore' : 'the timeline places the boxes and ignores'} layout.auto`));
+    if (fig.layout.auto && !form)
+        fig.edges.forEach((e, i) => {
+            if (e.around)
+                out.push(warn('auto-ignored', [edges[i]], `auto routes edge "${edges[i]}"; remove around`));
+        });
+    const nestedAuto = (g) => g.children.some((c) => isGroup(c) && (c.auto || nestedAuto(c)));
+    if (nestedAuto(fig.layout))
+        out.push(warn('auto-ignored', [], 'auto works on the root layout only'));
     const used = new Set((fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => h.edge))));
     fig.edges.forEach((e, i) => {
         if (e.quiet && !used.has(edges[i]))
@@ -107,6 +130,9 @@ export function checkSpec(fig) {
         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`));
     }
+    for (const n of nodes(fig.layout))
+        if (n.detail != null && !(typeof n.detail === 'string' && n.detail.endsWith('.svg') && !/^([\\/]|[A-Za-z]+:)/.test(n.detail)))
+            out.push(warn('bad-detail', [n.id], `box "${n.id}": detail ${JSON.stringify(n.detail)} is not a relative path to an .svg file`));
     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;
@@ -130,7 +156,10 @@ 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}`));
         }
-        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))]]));
+        const span = new Map(nodes(fig.layout).map((n) => {
+            const f = n.from == null ? null : dayOf(n.from);
+            return [n.id, [f, n.to ? dayOf(n.to) : f == null ? null : f - 1]];
+        }));
         for (const e of fig.edges) {
             const start = span.get(e.to)?.[0];
             const end = span.get(e.from)?.[1];
@@ -164,16 +193,22 @@ export function checkSpec(fig) {
     out.push(...plainText(fig));
     return out;
 }
-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 });
+const path = (e) => {
+    const line = e.elbow ?? e.pts;
+    if (!line)
+        return samples(e.curve);
+    return line.slice(1).flatMap((q, k) => {
+        const n = Math.max(16, Math.ceil(Math.hypot(q.x - line[k].x, q.y - line[k].y) / 4));
+        return Array.from({ length: n + 1 }, (_, i) => lerp(line[k], q, i / n));
+    });
+};
 // 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;
+// 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 } = {}) {
     const out = [];
     for (const b of scene.boxes)
@@ -185,29 +220,31 @@ export function checkScene(scene, { width = 830, minText = 10 } = {}) {
     for (const e of scene.edges) {
         if (e.behind && !e.elbow)
             continue;
-        const line = e.elbow ?? e.pts;
-        const pts = line?.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(line[k], q, i / 16)));
+        const pts = path(e);
         for (const b of scene.boxes)
-            if (b.id !== e.from && b.id !== e.to && (pts ? pts.some((p) => inside(p, b.rect, 2)) : curveHit(e.curve, [b.rect], -2).length))
-                out.push(err('edge-crosses-box', [e.id, b.id], `edge "${e.id}" passes through box "${b.id}"`));
+            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`));
+    }
+    for (const e of scene.edges) {
+        const pts = path(e);
+        const drawn = pts.slice(1).reduce((s, q, k) => s + Math.hypot(q.x - pts[k].x, q.y - pts[k].y), 0);
+        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`));
     }
     const pills = scene.edges.filter((e) => e.pts && e.label);
     const under = new Set();
     for (const e of scene.edges) {
         if (e.behind)
             continue;
-        const pts = e.pts
-            ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
-            : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
+        const pts = path(e);
         for (const f of pills)
             if (f.id !== e.id && !under.has(e.id + ' ' + f.id) && pts.some((p) => inside(p, f.label, 2))) {
                 under.add(e.id + ' ' + f.id);
                 out.push(err('label-overlap', [e.id, f.id], `edge "${e.id}" passes under the pill of edge "${f.id}"`));
             }
     }
-    const path = (e) => e.pts
-        ? e.pts.slice(1).flatMap((q, k) => Array.from({ length: 17 }, (_, i) => lerp(e.pts[k], q, i / 16)))
-        : Array.from({ length: 33 }, (_, i) => at(e.curve, i / 32));
     const stubs = scene.edges.filter((e) => e.pts && e.pts.length > 1);
     const hit = new Set();
     for (const f of stubs)