flowfig 0.3.0 → 0.4.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)
@@ -194,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

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

package/dist/gif.js

@@ -0,0 +1,245 @@
+/** The delay of each of `count` frames in cs. The sum is round(count * 100 / fps). */
+export function delays(count, fps) {
+    // Each delay is a whole cs: the rounding error moves between frames and does not add up.
+    return Array.from({ length: count }, (_, i) => Math.round(((i + 1) * 100) / fps) - Math.round((i * 100) / fps));
+}
+// A color bin: 5 bits per channel, 32768 bins.
+const binOf = (rgb) => ((rgb >> 9) & 0x7c00) | ((rgb >> 6) & 0x3e0) | ((rgb >> 3) & 0x1f);
+const channel = (bin, c) => (bin >> (10 - 5 * c)) & 31;
+/** Median cut: split the box with the widest channel range at its weighted median, until 256 boxes or one bin per box. */
+function medianCut(bins, counts) {
+    const boxes = [bins];
+    while (boxes.length < 256) {
+        let pick = -1, widest = 0, axis = 0;
+        boxes.forEach((box, i) => {
+            for (let c = 0; c < 3; c++) {
+                let lo = 31, hi = 0;
+                for (const b of box) {
+                    const v = channel(b, c);
+                    if (v < lo)
+                        lo = v;
+                    if (v > hi)
+                        hi = v;
+                }
+                if (hi - lo > widest)
+                    [widest, pick, axis] = [hi - lo, i, c];
+            }
+        });
+        if (pick === -1)
+            break;
+        const box = boxes[pick].sort((a, b) => channel(a, axis) - channel(b, axis));
+        const half = box.reduce((s, b) => s + counts[b], 0) / 2;
+        let at = 1, seen = counts[box[0]];
+        while (at < box.length - 1 && seen + counts[box[at]] <= half)
+            seen += counts[box[at++]];
+        boxes.splice(pick, 1, box.slice(0, at), box.slice(at));
+    }
+    return boxes;
+}
+/** The palette: the exact colors if there are 256 or fewer, else median cut over the bins. No dither. */
+function palette(exact, counts, sums) {
+    const colors = new Uint8Array(768);
+    if (exact) {
+        for (const [rgb, k] of exact)
+            colors.set([rgb >> 16, (rgb >> 8) & 255, rgb & 255], k * 3);
+        return { colors, index: (rgb) => exact.get(rgb) };
+    }
+    const bins = [];
+    for (let b = 0; b < 32768; b++)
+        if (counts[b])
+            bins.push(b);
+    const boxes = medianCut(bins, counts);
+    boxes.forEach((box, k) => {
+        let n = 0, r = 0, g = 0, b = 0;
+        for (const x of box) {
+            n += counts[x];
+            r += sums[x * 3];
+            g += sums[x * 3 + 1];
+            b += sums[x * 3 + 2];
+        }
+        colors.set([Math.round(r / n), Math.round(g / n), Math.round(b / n)], k * 3);
+    });
+    // Each bin maps to the palette color nearest to the mean color of the bin.
+    const table = new Uint8Array(32768);
+    for (const x of bins) {
+        const r = sums[x * 3] / counts[x], g = sums[x * 3 + 1] / counts[x], b = sums[x * 3 + 2] / counts[x];
+        let best = 0, dist = Infinity;
+        for (let k = 0; k < boxes.length; k++) {
+            const d = (colors[k * 3] - r) ** 2 + (colors[k * 3 + 1] - g) ** 2 + (colors[k * 3 + 2] - b) ** 2;
+            if (d < dist)
+                [dist, best] = [d, k];
+        }
+        table[x] = best;
+    }
+    return { colors, index: (rgb) => table[binOf(rgb)] };
+}
+/** GIF LZW: minimum code size 8, a clear code first, codes up to 12 bits, data in sub-blocks of 255 bytes or fewer. */
+function lzw(px, width, rect, byte) {
+    const [x0, y0, x1, y1] = rect;
+    const CLEAR = 256, END = 257;
+    const block = new Uint8Array(255);
+    const dict = new Map();
+    let blen = 0, acc = 0, bits = 0, size = 9, next = 258, prefix = -1;
+    const flush = () => {
+        byte(blen);
+        for (let i = 0; i < blen; i++)
+            byte(block[i]);
+        blen = 0;
+    };
+    const emit = (code) => {
+        acc |= code << bits;
+        for (bits += size; bits >= 8; bits -= 8, acc >>>= 8) {
+            block[blen++] = acc & 255;
+            if (blen === 255)
+                flush();
+        }
+    };
+    byte(8);
+    emit(CLEAR);
+    for (let y = y0; y <= y1; y++)
+        for (let x = x0; x <= x1; x++) {
+            const k = px[y * width + x];
+            if (prefix < 0) {
+                prefix = k;
+                continue;
+            }
+            const code = dict.get((prefix << 8) | k);
+            if (code !== undefined) {
+                prefix = code;
+                continue;
+            }
+            emit(prefix);
+            if (next === 4096) {
+                emit(CLEAR);
+                dict.clear();
+                [next, size] = [258, 9];
+            }
+            else {
+                // The decoder runs one code behind: grow the size when the new code no longer fits.
+                if (next >= 1 << size)
+                    size++;
+                dict.set((prefix << 8) | k, next++);
+            }
+            prefix = k;
+        }
+    emit(prefix);
+    emit(END);
+    if (bits > 0) {
+        block[blen++] = acc & 255;
+        if (blen === 255)
+            flush();
+    }
+    if (blen)
+        flush();
+    byte(0);
+}
+/** An animated GIF that loops forever. All frames have the size of the first frame. */
+// It yields to the event loop between frames, so a signal handler can run while the encode goes on.
+export async function encodeGif(frames) {
+    if (!frames.length)
+        throw new Error('a GIF needs at least one frame');
+    // Pass 1: count the colors of all frames.
+    const counts = new Uint32Array(32768), sums = new Float64Array(32768 * 3);
+    let exact = new Map(), width = 0, height = 0;
+    for (let f = 0; f < frames.length; f++) {
+        if (frames[f].same && f > 0)
+            continue;
+        // A run of equal frames counts once, with the weight of the run.
+        let weight = 1;
+        while (f + weight < frames.length && frames[f + weight].same)
+            weight++;
+        await new Promise(setImmediate);
+        const { width: w, height: h, data } = frames[f].load();
+        if (f === 0)
+            [width, height] = [w, h];
+        else if (w !== width || h !== height)
+            throw new Error(`frame ${f + 1} is ${w} x ${h}; the first frame is ${width} x ${height}`);
+        let last = -1, bin = 0;
+        for (let i = 0; i < data.length; i += 4) {
+            const rgb = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];
+            if (rgb !== last) {
+                last = rgb;
+                bin = binOf(rgb);
+                if (exact && !exact.has(rgb))
+                    exact = exact.size < 256 ? exact.set(rgb, exact.size) : null;
+            }
+            counts[bin] += weight;
+            sums[bin * 3] += data[i] * weight;
+            sums[bin * 3 + 1] += data[i + 1] * weight;
+            sums[bin * 3 + 2] += data[i + 2] * weight;
+        }
+    }
+    const { colors, index } = palette(exact, counts, sums);
+    let buf = new Uint8Array(1 << 20), len = 0;
+    const byte = (v) => {
+        if (len === buf.length) {
+            const grown = new Uint8Array(buf.length * 2);
+            grown.set(buf);
+            buf = grown;
+        }
+        buf[len++] = v;
+    };
+    const word = (v) => {
+        byte(v & 255);
+        byte(v >> 8);
+    };
+    const bytes = (...vs) => vs.forEach(byte);
+    const text = (s) => {
+        for (const c of s)
+            byte(c.charCodeAt(0));
+    };
+    text('GIF89a');
+    word(width);
+    word(height);
+    bytes(0xf7, 0, 0); // a global color table of 256 colors; background color 0; no aspect ratio
+    colors.forEach(byte);
+    bytes(0x21, 0xff, 11);
+    text('NETSCAPE2.0');
+    bytes(3, 1, 0, 0, 0); // loop count 0: loop forever
+    // Pass 2: each frame as palette indices. A later frame sends only the rectangle that changed.
+    let prev = null;
+    for (const frame of frames) {
+        await new Promise(setImmediate);
+        let cur = prev;
+        if (!(frame.same && prev)) {
+            const { data } = frame.load();
+            cur = new Uint8Array(width * height);
+            let last = -1, k = 0;
+            for (let p = 0, i = 0; p < cur.length; p++, i += 4) {
+                const rgb = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];
+                if (rgb !== last)
+                    [last, k] = [rgb, index(rgb)];
+                cur[p] = k;
+            }
+        }
+        let rect = [0, 0, width - 1, height - 1];
+        if (cur === prev)
+            rect = [0, 0, -1, -1];
+        else if (prev) {
+            rect = [width, height, -1, -1];
+            for (let y = 0, p = 0; y < height; y++)
+                for (let x = 0; x < width; x++, p++)
+                    if (cur[p] !== prev[p]) {
+                        if (x < rect[0])
+                            rect[0] = x;
+                        if (x > rect[2])
+                            rect[2] = x;
+                        if (y < rect[1])
+                            rect[1] = y;
+                        rect[3] = y;
+                    }
+        }
+        // No change: a 1 x 1 frame that paints the old color keeps the frame and its delay.
+        if (rect[2] < 0)
+            rect = [0, 0, 0, 0];
+        bytes(0x21, 0xf9, 4, 1 << 2); // disposal method 1: the next frame draws over this frame
+        word(frame.delay);
+        bytes(0, 0, 0x2c);
+        [rect[0], rect[1], rect[2] - rect[0] + 1, rect[3] - rect[1] + 1].forEach(word);
+        byte(0);
+        lzw(cur, width, rect, byte);
+        prev = cur;
+    }
+    byte(0x3b);
+    return buf.slice(0, len);
+}