flowfig 0.9.0 → 0.10.0

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)

package/dist/cli.js

@@ -18,10 +18,12 @@ import { GUIDE, TOPICS } from './guide.js';
 import { runDraw } from './draw.js';
 import { runInit } from './init.js';
 import { serve } from './mcp.js';
+import { runAtlas } from './atlas.js';
+import { runFromMermaid } from './mermaid.js';
 import { openedLine, openSvg, runOpen } from './open.js';
 import { pageHtml } from './page.js';
 import { decodePng } from './png.js';
-import { diff, formatDiff } from './diff.js';
+import { diff, formatDiff, mergeFigures } from './diff.js';
 import { loadSpec, reportLines, sortFindings, specOf, summaryLines, svgWithSpec, verifyLines } from './load.js';
 import { check, render, toSvg } from './svg.js';
 import { checkRendered } from './check.js';
@@ -32,14 +34,16 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   rende
        flowfig check <-|spec.json|figure.ts|figure.svg>   list the faults; the input can be an SVG this wrote
        flowfig --spec figure.svg                          print the spec the SVG carries
        flowfig verify <input>... [--root <dir>] [--json] [--strict]   check the code links of one or more figures
-       flowfig diff <old> <new> [--json|--md]   list the spec changes between two figures
+       flowfig diff <old> <new> [--json|--md] [--svg <out.svg>]   list the spec changes between two figures, or draw them in one SVG
        flowfig trace <file#symbol> [--depth <n>] [--max <n>] [--root <dir>] [--json]   list the calls under a symbol, each one checked
        flowfig coverage [--figures <glob>] [--entries <glob>] [--root <dir>] [--strict] [--json]   list failing and stale figures, and code with no figure
        flowfig docs [topic]                               print the guide, or one topic (Markdown)
        flowfig mcp                                        serve check, render, verify, diff and docs over MCP (stdio)
-       flowfig init [dir] [--agents <ids>] [-y] [--global] [--dry-run] [--no-mcp]   write flowfig instructions for the coding agents of a repo
+       flowfig init [dir] [--agents <ids> | --all-agents | --list-agents] [-y] [--global] [--dry-run] [--no-mcp]   write flowfig instructions for the coding agents of a repo
        flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json] [--open]   ask Claude Code for a figure, then check it
+       flowfig atlas [--figures <glob>] [--root <dir>] [--out <dir>] [--open]   write one linked web page for each figure, and an index
        flowfig open <figure.svg> [--html <path>]          show the figure in the default browser
+       flowfig from-mermaid <file.mmd|file.md|-> [--out <dir>]   convert Mermaid diagrams to specs
        flowfig gif <figure.svg> [out.gif] [--step <n>] [--dark] [--fps <n>] [--scale <n>] [--mp4]   write an animated GIF
 flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only), --no-verify (render only)`;
 function usage(message) {
@@ -86,8 +90,12 @@ if (args[0] === 'init')
     process.exit(await runInit(args.slice(1)));
 if (args[0] === 'draw')
     process.exit(await runDraw(args.slice(1)));
+if (args[0] === 'atlas')
+    process.exit(await runAtlas(args.slice(1)));
 if (args[0] === 'open')
     process.exit(await runOpen(args.slice(1)));
+if (args[0] === 'from-mermaid')
+    process.exit(runFromMermaid(args.slice(1)));
 if (args[0] === '--spec') {
     if (!args[1])
         usage('--spec needs the path of an SVG');
@@ -197,12 +205,21 @@ if (args[0] === 'coverage') {
 if (args[0] === 'diff') {
     args.shift();
     const json = flag('--json'), md = flag('--md');
+    const svgOut = option('--svg');
     const unknown = args.find((a) => a.startsWith('-') && a !== '-');
     if (unknown)
         usage(`unknown flag ${unknown}`);
     if (args.length !== 2)
-        usage('diff needs two figures: flowfig diff <old> <new> [--json|--md]');
-    const changes = diff(await load(args[0]), await load(args[1]));
+        usage('diff needs two figures: flowfig diff <old> <new> [--json|--md] [--svg <out.svg>]');
+    const [before, after] = [await load(args[0]), await load(args[1])];
+    const changes = diff(before, after);
+    if (svgOut) {
+        const { figure, marks } = mergeFigures(before, after);
+        const { svg, scene } = render(figure, { marks });
+        for (const f of sortFindings(checkRendered(figure, {}, scene), false))
+            console.error(`${f.severity.padEnd(8)} ${f.rule.padEnd(18)} ${f.message}`);
+        writeFileSync(svgOut, svg);
+    }
     console.log(json ? JSON.stringify(changes, null, 2) : formatDiff(changes, md ? 'md' : 'text'));
     process.exit(0);
 }

package/dist/coverage.js

@@ -3,12 +3,12 @@ import { readFileSync } from 'node:fs';
 import { posix, resolve } from 'node:path';
 import { langOf, readFile } from './code.js';
 import { loadSpec, specOf } from './load.js';
-import { links, verifyReport } from './verify.js';
-const MARK = '<metadata id="figure-spec">';
+import { detailFindings, links, SPEC_MARK, verifyReport } from './verify.js';
 const globRe = (glob) => new RegExp(`^${glob
     .replace(/^\.\//, '')
     .replace(/[.+^${}()|[\]\\]/g, '\\$&')
     .replace(/\*\*\/|\*\*|\*|\?/g, (t) => (t === '**/' ? '(?:.*/)?' : t === '**' ? '.*' : t === '*' ? '[^/]*' : '[^/]'))}$`);
+const isTest = (p) => /(^|\/)(__tests__|tests|src\/test)\//.test(p) || /\.(test|spec)\.[^/]+$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$|Tests?\.(java|cs)$/.test(p);
 const day = (t) => (t === Infinity ? 'now' : new Date(t * 1000).toISOString().slice(0, 10));
 const count = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
 function gitTimes(root) {
@@ -42,7 +42,7 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
     const out = [];
     for (const figure of all.filter((p) => p.endsWith('.svg') && want.test(p))) {
         const text = readFileSync(resolve(root, figure), 'utf8');
-        if (!text.includes(MARK))
+        if (!text.includes(SPEC_MARK))
             continue;
         let fig;
         try {
@@ -54,8 +54,10 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
         }
         const paths = [...new Set(links(fig).map((l) => posix.normalize(l.path)))];
         paths.forEach((p) => covered.add(p));
+        const lost = detailFindings(fig, root).length;
+        const lostText = lost ? `; ${lost} missing-detail` : '';
         if (!paths.length) {
-            out.push({ figure, state: 'none', detail: 'no source links' });
+            out.push({ figure, state: 'none', detail: `no source links${lostText}` });
             continue;
         }
         const { findings, coverage } = verifyReport(fig, { root, cache });
@@ -72,13 +74,14 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
         const newer = time && paths.find((p) => time(p) > mine);
         out.push(newer
             ? { figure, state: 'stale', detail: `${newer} changed ${day(time(newer))}, figure ${day(mine)}` }
-            : { figure, state: 'ok', detail: `${coverage.boxesDefined} of ${coverage.boxes} boxes defined` });
+            : { figure, state: 'ok', detail: `${coverage.boxesDefined} of ${coverage.boxes} boxes defined${lostText}` });
     }
-    const code = all.filter((p) => langOf(p) != null);
+    const code = all.filter((p) => langOf(p) != null && !isTest(p));
     const report = { figures: out, git: time != null };
     if (entries) {
         const re = globRe(entries);
-        const matched = code.filter((p) => re.test(p));
+        const named = entries.replace(/^\.\//, '');
+        const matched = all.filter((p) => langOf(p) != null && re.test(p) && (p === named || !isTest(p)));
         report.entries = { glob: entries, total: matched.length, uncovered: matched.filter((p) => !covered.has(p)) };
     }
     else {

package/dist/diff.d.ts

@@ -7,3 +7,13 @@ export type Change = {
 };
 export declare function diff(before: FlowProps, after: FlowProps): Change[];
 export declare function formatDiff(changes: Change[], as: 'text' | 'md'): string;
+export type DiffMark = 'added' | 'removed' | 'changed';
+export type DiffMarks = {
+    boxes: Record<string, DiffMark>;
+    edges: Record<string, DiffMark>;
+    steps: number;
+};
+export declare function mergeFigures(before: FlowProps, after: FlowProps): {
+    figure: FlowProps;
+    marks: DiffMarks;
+};