flowfig 0.6.0 → 0.7.0

package/dist/draw.js

@@ -1,4 +1,3 @@
-// `flowfig draw`: one command to the first figure. Claude Code reads the repo and renders; draw checks the result itself.
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
@@ -10,7 +9,7 @@ import { verify } from './verify.js';
 const ALLOWED = 'Read,Glob,Grep,Bash(npx flowfig *)';
 const DISALLOWED = 'Edit,MultiEdit,NotebookEdit';
 const USAGE = 'usage: flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json] [--open]';
-/** 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 function slug(question) {
     const s = question
         .toLowerCase()
@@ -21,7 +20,6 @@ export function slug(question) {
     return s || 'figure';
 }
 const specPath = (out) => out.replace(/\.svg$/, '.json');
-/** The claude argv after the binary. The system prompt carries the agent text, the output path and the folder rule. */
 export function agentArgs(o) {
     const spec = specPath(o.out);
     const system = `${AGENT_TEXT.trimEnd()}\n\nWrite the spec to ${spec} with the Write tool. Then run exactly \`npx flowfig ${spec} ${o.out}\` as one command, alone on its line: no heredoc, no \`;\`, no \`&&\`, no pipe (the permission rule matches one plain command only). Then run \`npx flowfig verify ${o.out}\` the same way. Run every command from this folder, ${o.cwd}.`;
@@ -51,7 +49,6 @@ const fail = (message, code) => {
     console.error(message);
     return code;
 };
-/** Run `flowfig draw`. Prints, and returns the exit code. */
 export async function runDraw(argv) {
     const args = [...argv];
     const flag = (n) => args.includes(n) && args.splice(args.indexOf(n), 1).length > 0;
@@ -103,7 +100,7 @@ export async function runDraw(argv) {
     catch (e) {
         return fail(`draw: ${e.message}`, 2);
     }
-    // A figure from an earlier run must not pass as this run's work: compare the mtime.
+    // Compare the mtime: a figure from an earlier run must not pass.
     const mtime = () => (existsSync(full) ? statSync(full).mtimeMs : undefined);
     const before = mtime();
     const run = spawnSync(bin, agentArgs({ question, out, cwd, maxTurns, model }), {
@@ -112,7 +109,7 @@ export async function runDraw(argv) {
         stdio: ['ignore', 'pipe', 'inherit'],
         maxBuffer: 64 * 1024 * 1024,
     });
-    // The JSON is the last line that starts with {: a warning line may come before it.
+    // The JSON is the last line that starts with {; a warning can come before.
     const line = (run.stdout ?? '')
         .split('\n')
         .reverse()
@@ -177,7 +174,6 @@ export async function runDraw(argv) {
     }
     stop();
     let code = errors || stopped !== undefined ? 1 : 0;
-    // The SVG is on disk also with findings, so the user can look at it.
     if (open) {
         try {
             const line = openedLine((await openSvg(full))[0]);

package/dist/geometry.d.ts

@@ -9,8 +9,7 @@ export type Pt = {
     x: number;
     y: number;
 };
-/** A cross-block edge of wrapped lanes: the two drawn stubs, their pills, and their points for `check`. `d` then holds both stubs,
- * so a packet runs the source stub and jumps to the target stub. */
+/** A cross-lane edge as two stubs, their pills and their points. */
 export type Stub = {
     parts: [string, string];
     pills: [Rect, Rect];
@@ -18,7 +17,7 @@ export type Stub = {
     short?: true;
     tight: [boolean, boolean];
 };
-/** `elbow` holds the corners of an elbow path, so `check` can test its straight runs. */
+/** `elbow` holds the corners of an elbow path for `check`. */
 export type Routed = {
     id: string;
     d: string;
@@ -27,11 +26,12 @@ export type Routed = {
     stub?: Stub;
     elbow?: Pt[];
 };
-/** A rect that a route keeps clear of. `box` marks a box: an elbow's horizontal runs keep clear of a box, not of a label. */
+/** A rect that a route keeps clear of. `box` marks a box. */
 export type Avoid = Rect & {
     box?: boolean;
 };
 type Around = 'above' | 'below';
+/** Routes edges between measured boxes as curved SVG paths. `elbow` draws right-angle paths; `stub` splits a cross-lane edge in two. */
 export declare function route(edges: {
     id: string;
     from: string;
@@ -42,12 +42,10 @@ export declare function route(edges: {
     stub?: number[];
     bands?: [Rect | undefined, Rect | undefined];
     labelW?: number;
-}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Avoid[], // what an elbow's vertical run and a stub pill must not cross (the timeline's outside labels; the boxes and gutters of lanes)
-area?: Rect, // where a stub pill may sit: the lanes right of the gutter
-lanes?: {
+}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Avoid[], area?: Rect, lanes?: {
     bands: Rect[];
     boxes: Rect[];
 }): Routed[];
-/** True if the segment a-b crosses the segment c-d. The ends of a-b are trimmed by 1.5 px, so a touch at a box side does not count. */
+/** True if segment a-b crosses c-d. The ends of a-b are trimmed by 1.5 px. */
 export declare function crosses(a: Pt, b: Pt, c: Pt, d: Pt): boolean;
 export {};

package/dist/geometry.js

@@ -1,27 +1,14 @@
 import { STUB } from './model.js';
-/** The least gap between a label pill and a lane border. */
 const LABEL_CLEAR = 4;
 const cx = (r) => r.x + r.w / 2;
 const cy = (r) => r.y + r.h / 2;
-/** A point on the cubic Bézier at `t`, as `check` samples an edge. */
 const bezier = ([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 };
 };
-// Turns edges between measured boxes into curved SVG paths.
-// Boxes stacked on top of each other connect bottom->top, otherwise side->side.
-// Several edges leaving the same side of a box are spread out so they don't overlap,
-// except on `tips` boxes (diamonds), where they all meet at the point.
-// `elbow` draws a right-angle path, from a right end to a left end: its four curve points are the corners.
-// `sides` fixes the two sides an edge uses (a timeline uses right to left).
-// `around` makes an edge leave and enter from the top or bottom, arcing over whatever sits between.
-// `bands` (with `stub`) are the lane bands of the source and of the target: each pill stays inside its band, 4 px clear of the border.
-// `labelW` is the width of an edge's label pill: a stub pill keeps clear of it.
-// `stub` (wrapped lanes: the source pill width, the target pill width, and the width of a shorter source pill) draws a short stub from the source to a pill, and from a second pill into the target.
-export function route(edges, rects, tips = new Set(), avoid = [], // what an elbow's vertical run and a stub pill must not cross (the timeline's outside labels; the boxes and gutters of lanes)
-area, // where a stub pill may sit: the lanes right of the gutter
-lanes) {
+/** Routes edges between measured boxes as curved SVG paths. `elbow` draws right-angle paths; `stub` splits a cross-lane edge in two. */
+export function route(edges, rects, tips = new Set(), avoid = [], area, lanes) {
     const picks = [];
     for (const e of edges) {
         const a = rects[e.from], b = rects[e.to];
@@ -45,7 +32,6 @@ lanes) {
                             : ['l', 'r'];
         picks.push({ ...e, a, b, sa, sb });
     }
-    // For every (box, side), list the edge ends that sit there, sorted by where the other end is.
     const ends = new Map();
     for (const pick of picks) {
         for (const start of [true, false]) {
@@ -64,7 +50,7 @@ lanes) {
             const r = x.start ? x.pick.b : x.pick.a;
             return horiz ? cx(r) : cy(r);
         };
-        list.sort((p, q) => other(p) - other(q)); // stable: ties keep declaration order
+        list.sort((p, q) => other(p) - other(q));
         list.forEach((x, i) => {
             const r = x.start ? x.pick.a : x.pick.b;
             const f = tip ? 0.5 : (i + 1) / (list.length + 1);
@@ -78,16 +64,12 @@ lanes) {
             anchor.set(x.pick.id + (x.start ? ':s' : ':e'), pt);
         });
     }
-    // The four points travel with the path string: `flowfig check` samples the curve, and nothing has to parse `d`.
     const drawn = (id, curve, mid) => {
         const [s, c1, c2, e] = curve;
         return { id, d: `M ${s.x} ${s.y} C ${c1.x} ${c1.y}, ${c2.x} ${c2.y}, ${e.x} ${e.y}`, mid, curve };
     };
-    // Stub pills are placed after the other edges. Each pill keeps clear of `avoid`, of the edge labels, of the pills and stubs
-    // before it, and of every edge path (sampled as `check` samples it).
     const pills = [];
     const paths = [];
-    // The same samples as segments: a stub line must not cross one.
     const runs = [];
     const track = (pts) => {
         paths.push(...pts);
@@ -101,11 +83,6 @@ lanes) {
     const one = (p) => {
         const s = anchor.get(p.id + ':s'), e = anchor.get(p.id + ':e');
         if (p.stub) {
-            // The source pill goes right of the source and the target pill left of the target, at the nearest clear place: it slides
-            // away from the box in 8 px steps, and up or down inside the band in 4 px steps. The stub then runs on a slant. The last
-            // places are below and above the box. A place is clear if the pill and its stub keep clear of everything, and the pill stays
-            // inside its band. If no place is clear, the source pill tries its shorter text. If no place is clear then, the first place
-            // stays and `check` reports it.
             const [ow, iw, sw] = p.stub;
             const [sb, tb] = p.bands ?? [];
             const rows = (box, y0, band) => {
@@ -114,14 +91,11 @@ lanes) {
                     : [box.y + box.h + 2, box.y - 20];
                 return [y0, ...ys.filter((y) => y !== y0)];
             };
-            // A place and its stub. Beside the box, the stub runs from the box side to the near end of the pill. Under or over the box,
-            // it runs straight down or up between the box and the pill. `dir` is 1 for the source (box to pill), -1 for the target.
             const place = (box, from, dir, r, side, tip) => {
                 let a, b;
                 if (side)
                     [a, b] = [from, { x: dir > 0 ? r.x : r.x + r.w, y: r.y + 9 }];
                 else {
-                    // A diamond has its point at the middle: the stub meets the point.
                     const x = tip ? cx(box) : Math.min(Math.max(r.x + r.w / 2, box.x + 8, r.x + 8), box.x + box.w - 8, r.x + r.w - 8);
                     const under = r.y >= box.y + box.h;
                     [a, b] = [
@@ -131,22 +105,49 @@ lanes) {
                 }
                 return dir > 0 ? [r, a, b] : [r, b, a];
             };
-            const beside = (w, box, from, dir, band) => {
+            function* beside(w, box, from, dir, band) {
                 const tip = tips.has(dir > 0 ? p.from : p.to);
-                const out = [];
-                for (let dx = STUB - 8 * Math.ceil((box.w + w) / 8); dx <= STUB + 240; dx += 8)
-                    for (const y of rows(box, from.y - 9, band)) {
-                        // Closer than STUB to the box side, a pill sits under or over the box, with room for the stub.
-                        const x = dir > 0 ? from.x + dx : from.x - dx - w;
-                        if (dx < STUB && !(y >= box.y + box.h + STUB / 2 || y + 18 <= box.y - STUB / 2))
-                            continue;
-                        if (dx < STUB && tip && !(x + 8 <= cx(box) && cx(box) <= x + w - 8))
-                            continue;
-                        out.push([...place(box, from, dir, { x, y, w, h: 18 }, dx >= STUB, tip), Math.abs(dx - STUB) + Math.abs(y + 9 - from.y)]);
+                const ys = rows(box, from.y - 9, band)
+                    .map((y, i) => ({ y, d: Math.abs(y + 9 - from.y), i }))
+                    .sort((m, q) => m.d - q.d || m.i - q.i);
+                const heap = [];
+                for (let dx = STUB - 8 * Math.ceil((box.w + w) / 8); dx <= STUB + 240; dx += 8) {
+                    const x = dir > 0 ? from.x + dx : from.x - dx - w;
+                    if (dx < STUB && tip && !(x + 8 <= cx(box) && cx(box) <= x + w - 8))
+                        continue;
+                    if (ys.length)
+                        heap.push({ dx, x, k: 0, key: Math.abs(dx - STUB) + ys[0].d, i: heap.length });
+                }
+                // Equal keys must keep the dx order, then the row order, or a pill moves.
+                const less = (m, q) => m.key < q.key || (m.key === q.key && m.i < q.i);
+                heap.sort((m, q) => m.key - q.key || m.i - q.i);
+                while (heap.length) {
+                    const h = heap[0];
+                    const { y } = ys[h.k++];
+                    if (h.k < ys.length)
+                        h.key = Math.abs(h.dx - STUB) + ys[h.k].d;
+                    else {
+                        const last = heap.pop();
+                        if (heap.length)
+                            heap[0] = last;
                     }
-                return out.sort((m, q) => m[3] - q[3]).map(([r, a, b]) => [r, a, b]);
-            };
-            // A diamond with no room beside its point: the stub leaves the side point straight down or up, to a pill that spans its x.
+                    for (let i = 0;;) {
+                        const l = 2 * i + 1;
+                        let m = i;
+                        if (l < heap.length && less(heap[l], heap[m]))
+                            m = l;
+                        if (l + 1 < heap.length && less(heap[l + 1], heap[m]))
+                            m = l + 1;
+                        if (m === i)
+                            break;
+                        [heap[i], heap[m]] = [heap[m], heap[i]];
+                        i = m;
+                    }
+                    if (h.dx < STUB && !(y >= box.y + box.h + STUB / 2 || y + 18 <= box.y - STUB / 2))
+                        continue;
+                    yield place(box, from, dir, { x: h.x, y, w, h: 18 }, h.dx >= STUB, tip);
+                }
+            }
             const along = (w, box, from, dir, band) => {
                 if (!tips.has(dir > 0 ? p.from : p.to))
                     return [];
@@ -162,49 +163,54 @@ lanes) {
                     }
                 return out.sort((m, q) => m[3] - q[3]).map(([r, a, b]) => [r, a, b]);
             };
-            const outs = (w) => [
-                ...beside(w, p.a, s, 1, sb),
-                [
+            function* outs(w) {
+                yield* beside(w, p.a, s, 1, sb);
+                yield [
                     { x: cx(p.a) - w / 2, y: p.a.y + p.a.h + STUB, w, h: 18 },
                     { x: cx(p.a), y: p.a.y + p.a.h },
                     { x: cx(p.a), y: p.a.y + p.a.h + STUB },
-                ],
-                [
+                ];
+                yield [
                     { x: cx(p.a) - w / 2, y: p.a.y - STUB - 18, w, h: 18 },
                     { x: cx(p.a), y: p.a.y },
                     { x: cx(p.a), y: p.a.y - STUB },
-                ],
-                ...along(w, p.a, s, 1, sb),
-            ];
-            const ins = [
-                ...beside(iw, p.b, e, -1, tb),
-                [
+                ];
+                yield* along(w, p.a, s, 1, sb);
+            }
+            function* ins() {
+                yield* beside(iw, p.b, e, -1, tb);
+                yield [
                     { x: cx(p.b) - iw / 2, y: p.b.y - STUB - 18, w: iw, h: 18 },
                     { x: cx(p.b), y: p.b.y - STUB },
                     { x: cx(p.b), y: p.b.y },
-                ],
-                [
+                ];
+                yield [
                     { x: cx(p.b) - iw / 2, y: p.b.y + p.b.h + STUB, w: iw, h: 18 },
                     { x: cx(p.b), y: p.b.y + p.b.h + STUB },
                     { x: cx(p.b), y: p.b.y + p.b.h },
-                ],
-                ...along(iw, p.b, e, -1, tb),
-            ];
+                ];
+                yield* along(iw, p.b, e, -1, tb);
+            }
             const seg = (a, b) => Array.from({ length: 9 }, (_, i) => ({ x: a.x + ((b.x - a.x) * i) / 8, y: a.y + ((b.y - a.y) * i) / 8 }));
-            // A stub must not run through a box other than its own, nor through a pill or a label, nor cross an edge path.
             const free = (a, b, own) => seg(a, b).every((q) => ![...avoid, ...pills].some((r) => r !== own && q.x > r.x + 2 && q.x < r.x + r.w - 2 && q.y > r.y + 2 && q.y < r.y + r.h - 2));
             const whole = (a, b) => !runs.some(([c, d]) => crosses(a, b, c, d));
             const fits = (own, band, strict) => ([r, a, b]) => clear(r, band) && free(a, b, own) && (!strict || whole(a, b));
-            // The first place whose stub crosses no edge path. If none, the first place that clears everything else: in a dense
-            // figure no place may avoid every edge, and `check` then warns about the crossing.
-            const first = (own, band, lists) => [true, false].flatMap((strict) => lists.map((l, i) => [l.find(fits(own, band, strict)), i, !strict])).find(([x]) => x);
-            const hit = first(p.a, sb, [outs(ow), ...(sw == null ? [] : [outs(sw)])]);
+            const first = (own, band, lists) => {
+                for (const strict of [true, false]) {
+                    const ok = fits(own, band, strict);
+                    for (const [i, list] of lists.entries())
+                        for (const c of list())
+                            if (ok(c))
+                                return [c, i, !strict];
+                }
+            };
+            const hit = first(p.a, sb, [() => outs(ow), ...(sw == null ? [] : [() => outs(sw)])]);
             const cut = hit?.[1] === 1;
-            const [po, o1, o2] = hit?.[0] ?? outs(ow)[0];
+            const [po, o1, o2] = hit?.[0] ?? outs(ow).next().value;
             pills.push(po);
             track(seg(o1, o2));
             const hit2 = first(p.b, tb, [ins]);
-            const [pi, i1, i2] = hit2?.[0] ?? ins[0];
+            const [pi, i1, i2] = hit2?.[0] ?? ins().next().value;
             pills.push(pi);
             track(seg(i1, i2));
             const line = (a, b) => `M ${a.x} ${a.y} L ${b.x} ${b.y}`;
@@ -227,10 +233,7 @@ lanes) {
             };
         }
         if (p.elbow) {
-            // Under 16 px of gap, the elbow detours: out 8 px past the start, back to 8 px before the end, then forward into the target.
-            // A gap of 0 px or less takes the same detour.
             if (e.x - s.x < 16 && s.y === e.y) {
-                // One row: a straight line, since a detour would only double back.
                 return { id: p.id, d: `M ${s.x} ${s.y} H ${e.x}`, mid: { x: (s.x + e.x) / 2, y: s.y }, curve: [s, s, e, e], elbow: [s, e] };
             }
             if (e.x - s.x < 16) {
@@ -243,26 +246,20 @@ lanes) {
                     elbow: [s, { x: mx, y: s.y }, { x: mx, y: my }, { x: ex, y: my }, { x: ex, y: e.y }, e],
                 };
             }
-            // Over 16 px, the vertical run tries the midpoint, 8 px before the end, 8 px after the start, then any x in the gap.
-            // A vertical run keeps clear of every label and box; a horizontal run keeps clear of every box but the two ends.
             const own = (r) => [p.a, p.b].some((q) => q.x === r.x && q.y === r.y && q.w === r.w && q.h === r.h);
             const all = avoid.filter((r) => !own(r));
             const boxes = all.filter((r) => r.box);
-            // `m` is the margin: 2 px in the gap, 8 px on a detour, so a detour does not run along a box side.
             const vClear = (x, ya, yb, m = 2) => !all.some((r) => x > r.x - m && x < r.x + r.w + m && Math.max(ya, yb) > r.y && Math.min(ya, yb) < r.y + r.h);
             const hClear = (y, xa, xb, list = boxes, m = 2) => !list.some((r) => y > r.y - m && y < r.y + r.h + m && Math.max(xa, xb) > r.x && Math.min(xa, xb) < r.x + r.w);
             const mid = (s.x + e.x) / 2;
             const gap = Array.from({ length: Math.floor((e.x - s.x - 16) / 4) + 1 }, (_, i) => s.x + 8 + i * 4).sort((u, w) => Math.abs(u - mid) - Math.abs(w - mid));
             const mx = [mid, e.x - 8, s.x + 8, ...gap].find((x) => vClear(x, s.y, e.y) && hClear(s.y, s.x, x) && hClear(e.y, x, e.x));
             if (mx == null && boxes.length) {
-                // No x in the gap is clear: the elbow goes around. It runs right past the boxes in its way, along a clear row, back to
-                // a clear x at or before 8 px before the target, then down or up and forward into the target. The shortest clear
-                // detour wins; ties take the row nearest the middle.
                 const right = Math.max(...boxes.map((r) => r.x + r.w)) + 12;
                 const left = Math.min(...boxes.map((r) => r.x));
                 const [top, bottom] = [Math.min(...boxes.map((r) => r.y)) - 12, Math.max(...boxes.map((r) => r.y + r.h)) + 12];
                 let best;
-                // ponytail: a grid search in 4 px steps, about 10^5 tries for a figure the size of the roadmap.
+                // ponytail: grid search in 4 px steps, about 10^5 tries on the roadmap.
                 for (let x = s.x + 8; x <= right; x += 4) {
                     if (!hClear(s.y, s.x, x))
                         continue;
@@ -290,7 +287,6 @@ lanes) {
                     };
                 }
             }
-            // If no path is clear, the midpoint stays and `check` reports the crossing.
             const x = mx ?? mid;
             const c1 = { x, y: s.y }, c2 = { x, y: e.y };
             return {
@@ -302,7 +298,7 @@ lanes) {
             };
         }
         if (p.around) {
-            // ponytail: arcs 50px past the two ends' boxes; a taller box in between can still be crossed.
+            // ponytail: arcs 50 px past the box ends; a taller box between can be crossed.
             const y = p.around === 'above' ? Math.min(p.a.y, p.b.y) - 50 : Math.max(p.a.y + p.a.h, p.b.y + p.b.h) + 50;
             return drawn(p.id, [s, { x: s.x, y }, { x: e.x, y }, e], { x: (s.x + e.x) / 2, y: (s.y + 6 * y + e.y) / 8 });
         }
@@ -330,9 +326,6 @@ lanes) {
             done.set(p, one(p));
     return picks.map((p) => done.get(p));
 }
-/** The point of the path nearest its middle where a label pill of width `w` sits inside one band, LABEL_CLEAR from the border, clear of the boxes
- * and the earlier pills. If a short run leaves no such point, the pill keeps the x of a path point and moves up or down into the nearest
- * band, still on the path. If that fails too, the middle. Both renderers route through this, so they place the label alike. */
 function labelInBand(r, w, { bands, boxes }, pills) {
     const hit = (a, b, m) => a.x < b.x + b.w + m && b.x < a.x + a.w + m && a.y < b.y + b.h + m && b.y < a.y + a.h + m;
     const ts = Array.from({ length: 65 }, (_, i) => i / 64).sort((a, b) => Math.abs(a - 0.5) - Math.abs(b - 0.5));
@@ -356,7 +349,7 @@ function labelInBand(r, w, { bands, boxes }, pills) {
         }
     return r.mid;
 }
-/** True if the segment a-b crosses the segment c-d. The ends of a-b are trimmed by 1.5 px, so a touch at a box side does not count. */
+/** True if segment a-b crosses c-d. The ends of a-b are trimmed by 1.5 px. */
 export function crosses(a, b, c, d) {
     const len = Math.hypot(b.x - a.x, b.y - a.y);
     if (len < 4)

package/dist/gif.d.ts

@@ -1,6 +1,5 @@
 import type { Image } from './png.ts';
-/** One frame: `load` returns the pixels (called twice per frame); `delay` is in centiseconds.
- * `same` says the pixels equal the frame before: the encoder then never calls `load`. */
+/** One frame. `load` returns the pixels, `delay` is in cs, `same` skips `load`. */
 export type GifFrame = {
     load: () => Image;
     delay: number;