flowfig 0.3.0 → 0.5.0

package/dist/cli.js

@@ -21,24 +21,34 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   flowfig mcp                          # serve check, render, verify, diff and docs over MCP (stdio)
  *   flowfig init [dir]                   # write flowfig instructions for the coding agents of a repo
  *   flowfig draw "<question>" [--out out.svg]   # ask Claude Code for a figure, then check it
+ *   flowfig open figure.svg              # show the figure in the default browser
+ *   flowfig gif figure.svg [out.gif]     # write an animated GIF of the figure (needs Chrome, Edge, Chromium or Brave)
  *
  * A render checks first and writes nothing on an error (--no-check skips that). --strict makes warnings errors; --width and
  * --min-text set the page width and the smallest text the reader should get.
+ * --open opens the rendered SVG in the default browser (render and draw).
  *
  * Every rendered SVG carries its own spec in <metadata>, so a figure is editable later without anyone having to keep the JSON.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { captureFrames, findBrowser, launch } from './browser.js';
+import { delays, encodeGif } from './gif.js';
 import { GUIDE } from './guide.js';
 import { runDraw } from './draw.js';
 import { runInit } from './init.js';
 import { serve } from './mcp.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 { loadSpec, reportLines, sortFindings, specOf, svgWithSpec } from './load.js';
-import { check } from './svg.js';
+import { check, toSvg } from './svg.js';
 import { links, verify } from './verify.js';
-const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg]   render a figure; a spec on stdin with -
+const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg] [--open]   render a figure; a spec on stdin with -
        flowfig check <-|spec.json|figure.ts|figure.svg>   list the faults; the input can be an SVG this wrote
        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
@@ -46,7 +56,9 @@ const USAGE = `usage: flowfig <-|spec.json|figure.ts> [out.svg]   render a figur
        flowfig docs                                       print the guide (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 draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json]   ask Claude Code for a figure, then check it
+       flowfig draw "<question>" [--out <path>] [--model <alias>] [--max-turns <n>] [--json] [--open]   ask Claude Code for a figure, then check it
+       flowfig open <figure.svg> [--html <path>]          show the figure in the default browser
+       flowfig gif <figure.svg> [out.gif] [--step <n>] [--dark] [--fps <n>] [--scale <n>] [--mp4]   write an animated GIF
 flags for render and check: --strict (warnings are errors), --json, --width <px>, --min-text <px>, --no-check (render only)`;
 /** Bad use, not a bad figure: exit 2 with a message, not a stack trace. A declaration, so TypeScript narrows after a call. */
 function usage(message) {
@@ -86,6 +98,8 @@ 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] === 'open')
+    process.exit(await runOpen(args.slice(1)));
 if (args[0] === '--spec') {
     if (!args[1])
         usage('--spec needs the path of an SVG');
@@ -159,8 +173,155 @@ if (args[0] === 'diff') {
     console.log(json ? JSON.stringify(changes, null, 2) : formatDiff(changes, md ? 'md' : 'text'));
     process.exit(0);
 }
+if (args[0] === 'gif') {
+    args.shift();
+    const dark = flag('--dark'), mp4 = flag('--mp4');
+    const fps = value('--fps') ?? 20, scale = value('--scale') ?? 2, step = value('--step');
+    if (!Number.isInteger(fps) || fps > 50)
+        usage('--fps needs a whole number from 1 to 50');
+    const unknown = args.find((a) => a.startsWith('-'));
+    if (unknown)
+        usage(`unknown flag ${unknown}`);
+    const [path, outArg] = args;
+    if (!path)
+        usage('usage: flowfig gif <figure.svg> [out.gif] [--step <n>] [--dark] [--fps <n>] [--scale <n>] [--mp4]');
+    if (!path.endsWith('.svg'))
+        usage(`${path}: expected a .svg path`);
+    let svg = '';
+    try {
+        svg = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        usage(`${path}: ${e.message}`);
+    }
+    if (step !== undefined) {
+        // One step only: render the spec again with that step, so the loop holds that step alone.
+        const props = (() => {
+            try {
+                return loadSpec(path);
+            }
+            catch (e) {
+                return usage(e.message);
+            }
+        })();
+        const count = props.steps?.length ?? 0;
+        if (!count)
+            usage(`${path}: --step needs a figure with steps; this figure has 0`);
+        if (!Number.isInteger(step) || step > count)
+            usage(`--step needs a whole number from 1 to ${count}`);
+        svg = toSvg({ ...props, steps: [props.steps[step - 1]] });
+    }
+    const out = outArg ?? path.replace(/\.svg$/, step === undefined ? '.gif' : `-step${step}.gif`);
+    const size = /<svg\b[^>]*?\swidth="([\d.]+)"[^>]*?\sheight="([\d.]+)"/.exec(svg);
+    if (!size)
+        usage(`${path}: no width and height on the <svg> element`);
+    if (!existsSync(dirname(resolve(out))))
+        usage(`${out}: the folder does not exist`);
+    const found = findBrowser({ platform: process.platform, env: process.env, exists: existsSync });
+    if (!found.path)
+        usage(['gif needs Chrome, Edge, Chromium or Brave. Checked:', ...found.checked, 'Set CHROME_PATH to the browser program.'].join('\n'));
+    const line = (file, frames, bytes) => `${file} — ${frames} frame${frames === 1 ? '' : 's'}, ${(frames / fps).toFixed(1)} s, ${(bytes / 1048576).toFixed(1)} MB`;
+    const temp = mkdtempSync(join(tmpdir(), 'flowfig-gif-'));
+    // A Ctrl-C can come while the browser starts, so cleanup waits for the start before it stops the browser.
+    let launching;
+    let cleaning;
+    const cleanup = () => (cleaning ??= (async () => {
+        await (await launching?.catch(() => undefined))?.close();
+        try {
+            // The retries cover Windows, where the browser can hold a file lock for a short time after the exit.
+            rmSync(temp, { recursive: true, force: true, maxRetries: 3 });
+        }
+        catch (e) {
+            console.error(`warning: could not remove ${temp}: ${e.message}`);
+        }
+    })());
+    // The output files of this run: a stop removes them, so no partial file stays.
+    const written = [];
+    let ffmpeg, ffmpegDone = Promise.resolve(), stopped = 0;
+    const yieldLoop = () => new Promise((done) => setImmediate(done));
+    // The handlers stay for the whole run: a second signal during the cleanup must not end the process before the cleanup ends.
+    const onSignal = (signal) => {
+        if (stopped)
+            return;
+        stopped = signal === 'SIGINT' ? 130 : 143;
+        ffmpeg?.kill('SIGKILL');
+        void ffmpegDone
+            .then(() => written.forEach((f) => rmSync(f, { force: true })))
+            .then(cleanup)
+            .finally(() => process.exit(stopped));
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    // The encode and the ffmpeg run give the event loop a turn, so a signal handler can run. A write comes straight after this check.
+    const proceed = async () => {
+        await yieldLoop();
+        if (stopped)
+            throw new Error('stopped');
+    };
+    let code = 0;
+    try {
+        launching = launch(found.path, join(temp, 'profile'));
+        const browser = await launching;
+        const viewport = { width: Math.ceil(Number(size[1])), height: Math.ceil(Number(size[2])) };
+        const { pngs } = await captureFrames(browser.cdp, pageHtml(svg, basename(path)), { ...viewport, scale, fps, dark });
+        const wait = delays(pngs.length, fps);
+        // The GIF keeps the PNG bytes, not the pixels: a decoded 2400 x 1600 frame is 15 MB.
+        const gif = await encodeGif(pngs.map((png, i) => ({ load: () => decodePng(png), delay: wait[i], same: i > 0 && png.equals(pngs[i - 1]) })));
+        await proceed();
+        written.push(out);
+        writeFileSync(out, gif);
+        console.log(line(out, pngs.length, gif.length));
+        if (gif.length > 10485760)
+            console.error(`warning: ${out} is ${(gif.length / 1048576).toFixed(1)} MB, over 10 MB. Try --step <n>, a lower --fps or a lower --scale.`);
+        if (mp4) {
+            const mp4Path = out.replace(/(\.gif)?$/, '.mp4');
+            // FLOWFIG_FFMPEG replaces the PATH lookup, so a test can hide ffmpeg and keep the full PATH.
+            const ffmpegBin = process.env.FLOWFIG_FFMPEG ?? 'ffmpeg';
+            if (spawnSync(ffmpegBin, ['-version']).error)
+                console.error('gif: no ffmpeg on the PATH, so no MP4. The GIF is written.');
+            else {
+                await proceed();
+                written.push(mp4Path);
+                // yuv420p needs an even width and height, so the pad filter adds a pixel where needed.
+                ffmpeg = spawn(ffmpegBin, [
+                    ...['-y', '-loglevel', 'error', '-f', 'image2pipe', '-framerate', String(fps), '-c:v', 'png', '-i', '-'],
+                    ...['-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', mp4Path],
+                ]);
+                let stderr = '';
+                ffmpeg.stderr.on('data', (d) => (stderr += d));
+                ffmpeg.stdin.on('error', () => { }); // ffmpeg can exit before it reads all the input; the exit code reports that
+                ffmpeg.stdin.end(Buffer.concat(pngs));
+                const status = await (ffmpegDone = new Promise((done) => {
+                    ffmpeg.once('error', () => done(-1));
+                    ffmpeg.once('close', done);
+                }));
+                await proceed();
+                if (status !== 0) {
+                    rmSync(mp4Path, { force: true });
+                    throw new Error(`ffmpeg failed: ${stderr.trim()}`);
+                }
+                console.log(line(mp4Path, pngs.length, statSync(mp4Path).size));
+            }
+        }
+    }
+    catch (e) {
+        if (!stopped)
+            console.error(`gif: ${e.message}`);
+        code = 1;
+    }
+    finally {
+        await cleanup();
+    }
+    // A signal that came in the last turn runs its handler here, before the exit.
+    await yieldLoop();
+    if (stopped)
+        written.forEach((f) => rmSync(f, { force: true }));
+    process.exit(stopped || code);
+}
 const command = args[0] === 'check' ? args.shift() : 'render';
-const json = flag('--json'), strict = flag('--strict'), skip = flag('--no-check');
+const json = flag('--json'), strict = flag('--strict'), skip = flag('--no-check'), open = flag('--open');
+if (command === 'check' && open)
+    usage('--open works with a render, not with check');
 const opts = { width: value('--width'), minText: value('--min-text') };
 const unknown = args.find((a) => a.startsWith('-') && a !== '-');
 if (unknown)
@@ -191,6 +352,15 @@ if (errors)
     process.exit(1);
 const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/, '') + '.svg');
 // The spec rides along in <metadata>: an SVG is then its own source, and no JSON has to be kept.
-const withSpec = svgWithSpec(props);
+const withSpec = svgWithSpec(props, opts);
 writeFileSync(dest, withSpec);
 console.log(`${dest} — ${(withSpec.length / 1024).toFixed(1)} kB`);
+if (open) {
+    try {
+        console.log(openedLine((await openSvg(dest))[0]));
+    }
+    catch (e) {
+        console.error(`open: ${e.message}`);
+        process.exit(1);
+    }
+}

package/dist/diff.js

@@ -36,7 +36,7 @@ export function diff(before, after) {
     const edges = (f) => new Map(f.edges.map((e) => [edgeId(e), e]));
     const steps = (f) => new Map((f.steps ?? []).map((s) => [str(s.label), s]));
     const out = [
-        ...compare('box', boxes(before), boxes(after), (a, b) => fields(a, b, ['label', 'sub', 'shape', 'tone', 'source', 'group'])),
+        ...compare('box', boxes(before), boxes(after), (a, b) => fields(a, b, ['label', 'sub', 'shape', 'tone', 'mark', 'from', 'to', 'source', 'group'])),
         ...compare('edge', edges(before), edges(after), (a, b) => fields(a, b, ['from', 'to', 'label', 'source'])),
         ...compare('step', steps(before), steps(after), () => []),
         ...compare('message', messages(before), messages(after), () => []),

package/dist/draw.js

@@ -4,11 +4,12 @@ import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { AGENT_TEXT } from './guide.js';
 import { loadSpec, reportLines, sortFindings } from './load.js';
+import { openedLine, openSvg } from './open.js';
 import { check } from './svg.js';
 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]';
+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. */
 export function slug(question) {
     const s = question
@@ -63,9 +64,10 @@ export async function runDraw(argv) {
             throw new Bad(`${n} needs a value`);
         return v;
     };
-    let json, outArg, model, turns;
+    let json, open, outArg, model, turns;
     try {
         json = flag('--json');
+        open = flag('--open');
         outArg = value('--out');
         model = value('--model');
         turns = value('--max-turns');
@@ -174,5 +176,20 @@ export async function runDraw(argv) {
         console.log(`agent: claude, $${cost === null ? '?' : cost.toFixed(4)}, session ${session ?? '?'}`);
     }
     stop();
-    return errors || stopped !== undefined ? 1 : 0;
+    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]);
+            if (json)
+                console.error(line);
+            else
+                console.log(line);
+        }
+        catch (e) {
+            console.error(`open: ${e.message}`);
+            code = 1;
+        }
+    }
+    return code;
 }

package/dist/geometry.d.ts

@@ -4,15 +4,26 @@ export type Rect = {
     w: number;
     h: number;
 };
+export type Side = 'l' | 'r' | 't' | 'b';
 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. */
+export type Stub = {
+    parts: [string, string];
+    pills: [Rect, Rect];
+    pts: [Pt[], Pt[]];
+    short?: true;
+    tight: [boolean, boolean];
+};
 export type Routed = {
     id: string;
     d: string;
     mid: Pt;
     curve: [Pt, Pt, Pt, Pt];
+    stub?: Stub;
 };
 type Around = 'above' | 'below';
 export declare function route(edges: {
@@ -20,5 +31,13 @@ export declare function route(edges: {
     from: string;
     to: string;
     around?: Around;
-}[], rects: Record<string, Rect>, tips?: Set<string>): Routed[];
+    sides?: [Side, Side];
+    elbow?: boolean;
+    stub?: number[];
+    bands?: [Rect | undefined, Rect | undefined];
+    labelW?: number;
+}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Rect[], // 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): 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. */
+export declare function crosses(a: Pt, b: Pt, c: Pt, d: Pt): boolean;
 export {};

package/dist/geometry.js

@@ -1,28 +1,45 @@
+import { STUB } from './model.js';
 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.
-export function route(edges, rects, tips = new Set()) {
+// `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) {
     const picks = [];
     for (const e of edges) {
         const a = rects[e.from], b = rects[e.to];
         if (!a || !b)
             continue;
         const stacked = a.x < b.x + b.w && b.x < a.x + a.w;
-        const [sa, sb] = e.around
-            ? e.around === 'above'
-                ? ['t', 't']
-                : ['b', 'b']
-            : stacked
-                ? a.y < b.y
-                    ? ['b', 't']
-                    : ['t', 'b']
-                : a.x < b.x
-                    ? ['r', 'l']
-                    : ['l', 'r'];
+        const [sa, sb] = e.sides
+            ? e.sides
+            : e.stub
+                ? ['r', 'l']
+                : e.around
+                    ? e.around === 'above'
+                        ? ['t', 't']
+                        : ['b', 'b']
+                    : stacked
+                        ? a.y < b.y
+                            ? ['b', 't']
+                            : ['t', 'b']
+                        : a.x < b.x
+                            ? ['r', 'l']
+                            : ['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.
@@ -63,8 +80,154 @@ export function route(edges, rects, tips = new Set()) {
         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 };
     };
-    return picks.map((p) => {
+    // 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);
+        pts.slice(1).forEach((q, i) => runs.push([pts[i], q]));
+    };
+    const inBand = (r, b) => !b || (r.x >= b.x + 4 && r.x + r.w <= b.x + b.w - 4 && r.y >= b.y + 4 && r.y + r.h <= b.y + b.h - 4);
+    const clear = (r, band) => inBand(r, band) &&
+        (!area || (r.x >= area.x && r.x + r.w <= area.x + area.w && r.y >= area.y && r.y + r.h <= area.y + area.h)) &&
+        ![...avoid, ...pills].some((q) => r.x < q.x + q.w + 2 && q.x < r.x + r.w + 2 && r.y < q.y + q.h + 2 && q.y < r.y + r.h + 2) &&
+        !paths.some((q) => 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 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) => {
+                const ys = band
+                    ? Array.from({ length: Math.max(0, Math.floor((band.h - 26) / 4)) + 1 }, (_, i) => band.y + 4 + i * 4)
+                    : [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] = [
+                        { x, y: under ? box.y + box.h : box.y },
+                        { x, y: under ? r.y : r.y + r.h },
+                    ];
+                }
+                return dir > 0 ? [r, a, b] : [r, b, a];
+            };
+            const 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)]);
+                    }
+                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),
+                [
+                    { 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 },
+                ],
+                [
+                    { 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 },
+                ],
+            ];
+            const ins = [
+                ...beside(iw, p.b, e, -1, tb),
+                [
+                    { 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 },
+                ],
+                [
+                    { 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 },
+                ],
+            ];
+            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 cut = hit?.[1] === 1;
+            const [po, o1, o2] = hit?.[0] ?? outs(ow)[0];
+            pills.push(po);
+            track(seg(o1, o2));
+            const hit2 = first(p.b, tb, [ins]);
+            const [pi, i1, i2] = hit2?.[0] ?? ins[0];
+            pills.push(pi);
+            track(seg(i1, i2));
+            const line = (a, b) => `M ${a.x} ${a.y} L ${b.x} ${b.y}`;
+            const parts = [line(o1, o2), line(i1, i2)];
+            return {
+                id: p.id,
+                d: parts.join(' '),
+                mid: { x: po.x + po.w / 2, y: po.y + 9 },
+                curve: [o1, o1, i2, i2],
+                stub: {
+                    parts,
+                    pills: [po, pi],
+                    pts: [
+                        [o1, o2],
+                        [i1, i2],
+                    ],
+                    tight: [hit?.[2] !== false, hit2?.[2] !== false],
+                    ...(cut && { short: true }),
+                },
+            };
+        }
+        if (p.elbow) {
+            // The vertical run sits at the midpoint x. Under 16 px of gap, it 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.
+            // Over 16 px, it tries the midpoint, then 8 px before the end, then 8 px after the start, and takes the first that clears `avoid`.
+            const y0 = Math.min(s.y, e.y), y1 = Math.max(s.y, e.y);
+            const clear = (x) => !avoid.some((r) => x > r.x - 2 && x < r.x + r.w + 2 && y1 > r.y && y0 < r.y + r.h);
+            const mx = e.x - s.x >= 16 ? ([(s.x + e.x) / 2, e.x - 8, s.x + 8].find(clear) ?? (s.x + e.x) / 2) : s.x + 8;
+            const c1 = { x: mx, y: s.y }, c2 = { x: mx, y: e.y };
+            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] };
+            }
+            if (e.x - s.x < 16) {
+                const ex = e.x - 8, my = (s.y + e.y) / 2;
+                return {
+                    id: p.id,
+                    d: `M ${s.x} ${s.y} H ${mx} V ${my} H ${ex} V ${e.y} H ${e.x}`,
+                    mid: { x: (mx + ex) / 2, y: my },
+                    curve: [s, { x: mx, y: my }, { x: ex, y: my }, e],
+                };
+            }
+            return { id: p.id, d: `M ${s.x} ${s.y} H ${mx} V ${e.y} H ${e.x}`, mid: { x: mx, y: (s.y + e.y) / 2 }, curve: [s, c1, c2, e] };
+        }
         if (p.around) {
             // ponytail: arcs 50px past the two ends' boxes; a taller box in between can still 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;
@@ -76,5 +239,32 @@ export function route(edges, rects, tips = new Set()) {
         const c1 = horiz ? { x: s.x + sign * k, y: s.y } : { x: s.x, y: s.y + sign * k };
         const c2 = horiz ? { x: e.x - sign * k, y: e.y } : { x: e.x, y: e.y - sign * k };
         return drawn(p.id, [s, c1, c2, e], { x: (s.x + e.x) / 2, y: (s.y + e.y) / 2 });
-    });
+    };
+    const done = new Map();
+    for (const p of picks) {
+        if (p.stub)
+            continue;
+        const r = one(p);
+        done.set(p, r);
+        if (p.labelW)
+            pills.push({ x: r.mid.x - p.labelW / 2, y: r.mid.y - 9, w: p.labelW, h: 18 });
+        track(Array.from({ length: 33 }, (_, i) => bezier(r.curve, i / 32)));
+    }
+    for (const p of picks)
+        if (p.stub)
+            done.set(p, one(p));
+    return picks.map((p) => done.get(p));
+}
+/** 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. */
+export function crosses(a, b, c, d) {
+    const len = Math.hypot(b.x - a.x, b.y - a.y);
+    if (len < 4)
+        return false;
+    const t = 1.5 / len;
+    const [p, q] = [
+        { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t },
+        { x: b.x - (b.x - a.x) * t, y: b.y - (b.y - a.y) * t },
+    ];
+    const side = (o, u, v) => Math.sign((u.x - o.x) * (v.y - o.y) - (u.y - o.y) * (v.x - o.x));
+    return side(p, q, c) * side(p, q, d) < 0 && side(c, d, p) * side(c, d, q) < 0;
 }

package/dist/gif.d.ts

@@ -0,0 +1,12 @@
+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`. */
+export type GifFrame = {
+    load: () => Image;
+    delay: number;
+    same?: boolean;
+};
+/** The delay of each of `count` frames in cs. The sum is round(count * 100 / fps). */
+export declare function delays(count: number, fps: number): number[];
+/** An animated GIF that loops forever. All frames have the size of the first frame. */
+export declare function encodeGif(frames: GifFrame[]): Promise<Uint8Array>;