flowfig 0.2.0 → 0.4.0

package/dist/cli.js

@@ -20,23 +20,35 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *   flowfig docs                         # print the full guide (Markdown)
  *   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
@@ -44,6 +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] [--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) {
@@ -81,6 +96,10 @@ if (args[0] === 'mcp') {
 }
 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');
@@ -154,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)
@@ -189,3 +355,12 @@ const dest = out ?? (input === '-' ? 'figure.svg' : input.replace(/\.[^./\\]+$/,
 const withSpec = svgWithSpec(props);
 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

@@ -23,7 +23,7 @@ function compare(kind, before, after, fieldsOf) {
     return out;
 }
 const messages = (fig) => new Map((fig.steps ?? [])
-    .flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}`)))
+    .flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => `${str(s.label)}: ${h.edge}${h.back ? ' back' : ''}${h.data != null ? ` "${str(h.data)}"` : ''}${h.tone ? ` [${h.tone}]` : ''}`)))
     .map((id) => [id, id]));
 export function diff(before, after) {
     const boxes = (f) => {
@@ -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', '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.d.ts

@@ -0,0 +1,12 @@
+/** A file name from the question: lower case, letters and digits, joined by -, at most 60 characters. */
+export declare function slug(question: string): string;
+/** The claude argv after the binary. The system prompt carries the agent text, the output path and the folder rule. */
+export declare function agentArgs(o: {
+    question: string;
+    out: string;
+    cwd: string;
+    maxTurns: number;
+    model?: string;
+}): string[];
+/** Run `flowfig draw`. Prints, and returns the exit code. */
+export declare function runDraw(argv: string[]): Promise<number>;

package/dist/draw.js

@@ -0,0 +1,195 @@
+// `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';
+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] [--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
+        .toLowerCase()
+        .match(/[a-z0-9]+/g)
+        ?.join('-')
+        .slice(0, 60)
+        .replace(/-$/, '');
+    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}.`;
+    const args = [
+        '-p',
+        o.question,
+        '--output-format',
+        'json',
+        '--max-turns',
+        String(o.maxTurns),
+        '--permission-mode',
+        'acceptEdits',
+        '--allowedTools',
+        ALLOWED,
+        '--disallowedTools',
+        DISALLOWED,
+        '--append-system-prompt',
+        system,
+    ];
+    if (o.model)
+        args.push('--model', o.model);
+    return args;
+}
+class Bad extends Error {
+}
+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;
+    const value = (n) => {
+        const i = args.indexOf(n);
+        if (i === -1)
+            return undefined;
+        const v = args.splice(i, 2)[1];
+        if (v === undefined)
+            throw new Bad(`${n} needs a value`);
+        return v;
+    };
+    let json, open, outArg, model, turns;
+    try {
+        json = flag('--json');
+        open = flag('--open');
+        outArg = value('--out');
+        model = value('--model');
+        turns = value('--max-turns');
+    }
+    catch (e) {
+        if (e instanceof Bad)
+            return fail(`draw: ${e.message}\n${USAGE}`, 2);
+        throw e;
+    }
+    const maxTurns = turns === undefined ? 40 : Number(turns);
+    if (!Number.isInteger(maxTurns) || maxTurns < 1)
+        return fail(`draw: --max-turns needs a positive whole number\n${USAGE}`, 2);
+    const bad = args.find((a) => a.startsWith('-'));
+    if (bad)
+        return fail(`draw: unknown flag ${bad}\n${USAGE}`, 2);
+    const question = args.join(' ').trim();
+    if (!question)
+        return fail(`draw needs a question\n${USAGE}`, 2);
+    if (process.platform === 'win32')
+        return fail('draw does not run on Windows yet', 2);
+    const bin = process.env.FLOWFIG_CLAUDE_BIN || 'claude';
+    const version = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+    if (version.error || version.status !== 0)
+        return fail('draw needs Claude Code: npm i -g @anthropic-ai/claude-code', 2);
+    const cwd = process.cwd();
+    const out = outArg ?? `${slug(question)}.svg`;
+    if (!out.endsWith('.svg'))
+        return fail(`draw: --out needs a .svg path\n${USAGE}`, 2);
+    const full = resolve(cwd, out);
+    try {
+        mkdirSync(dirname(full), { recursive: true });
+    }
+    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.
+    const mtime = () => (existsSync(full) ? statSync(full).mtimeMs : undefined);
+    const before = mtime();
+    const run = spawnSync(bin, agentArgs({ question, out, cwd, maxTurns, model }), {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'inherit'],
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    // The JSON is the last line that starts with {: a warning line may come before it.
+    const line = (run.stdout ?? '')
+        .split('\n')
+        .reverse()
+        .find((l) => l.startsWith('{'));
+    let reply = '', cost = null, session = null, stopped, denials = [];
+    try {
+        const parsed = JSON.parse(line ?? '');
+        reply = String(parsed.result ?? '');
+        cost = typeof parsed.total_cost_usd === 'number' ? parsed.total_cost_usd : null;
+        session = typeof parsed.session_id === 'string' ? parsed.session_id : null;
+        if (parsed.is_error === true)
+            stopped = String(parsed.subtype ?? '?');
+        if (Array.isArray(parsed.permission_denials))
+            denials = parsed.permission_denials;
+    }
+    catch {
+        process.stderr.write(run.stdout ?? '');
+        const message = `claude failed (exit ${run.status ?? 'null'})`;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        return fail(`draw: ${message}`, 1);
+    }
+    const stop = () => {
+        if (stopped !== undefined)
+            console.error(`draw: claude stopped (${stopped})`);
+    };
+    const after = mtime();
+    if (after === undefined || after === before) {
+        const message = `the agent wrote no figure at ${out}`;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        else
+            console.log(reply);
+        for (const d of denials)
+            console.error(`denied: ${d.tool_name ?? '?'} ${d.tool_input?.command ?? d.tool_input?.file_path ?? ''}`.trimEnd());
+        stop();
+        return fail(`draw: ${message}`, 1);
+    }
+    let props;
+    try {
+        props = loadSpec(full);
+    }
+    catch (e) {
+        stop();
+        const message = e.message;
+        if (json)
+            console.log(JSON.stringify({ out, reply, cost, session, findings: [], error: message }, null, 2));
+        return fail(`draw: ${message}`, 1);
+    }
+    const findings = sortFindings([...check(props), ...verify(props, { root: cwd })], true);
+    const errors = findings.length > 0;
+    if (!errors && stopped === undefined)
+        rmSync(specPath(full), { force: true });
+    if (json)
+        console.log(JSON.stringify({ out, reply, cost, session, findings }, null, 2));
+    else {
+        for (const l of reportLines(props, findings))
+            console.log(l);
+        console.log('');
+        console.log(reply);
+        console.log(`agent: claude, $${cost === null ? '?' : cost.toFixed(4)}, session ${session ?? '?'}`);
+    }
+    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]);
+            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,6 +4,7 @@ export type Rect = {
     w: number;
     h: number;
 };
+export type Side = 'l' | 'r' | 't' | 'b';
 export type Pt = {
     x: number;
     y: number;
@@ -20,5 +21,7 @@ export declare function route(edges: {
     from: string;
     to: string;
     around?: Around;
-}[], rects: Record<string, Rect>, tips?: Set<string>): Routed[];
+    sides?: [Side, Side];
+    elbow?: boolean;
+}[], rects: Record<string, Rect>, tips?: Set<string>, avoid?: Rect[]): Routed[];
 export {};

package/dist/geometry.js

@@ -4,25 +4,29 @@ const cy = (r) => r.y + r.h / 2;
 // 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()) {
+export function route(edges, rects, tips = new Set(), avoid = []) {
     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.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.
@@ -65,6 +69,29 @@ export function route(edges, rects, tips = new Set()) {
     };
     return picks.map((p) => {
         const s = anchor.get(p.id + ':s'), e = anchor.get(p.id + ':e');
+        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;

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>;