@rig-c/parts 0.0.0-stage → 1.5.4

package/skills/rig-parts/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: rig-parts
+description: Turn one anime character painting and its See-through layer decomposition into a verified 2D character rig (Spine 4.3 skeleton data) — measured parts, weighted meshes, bone chains and a looping idle — with rig-parts, which gates everything through rig-c before it is written. Use for a request to rig or animate a single character painting, to run or read rig-parts layers, sheet, assemble, propose, rig, check, loop or build, or to write or fix a rig-parts config.json. Not for cutting art into parts by hand, for authoring a rig from loose PNGs (that is the rigc skill), for lip-sync or swapping a part's image, or for running See-through itself.
+license: MIT
+compatibility: Requires Bun 1.2 or later. The tool is the npm package @rig-c/parts (npm i -D @rig-c/parts, or bun add -d @rig-c/parts), whose command is rig-parts; rig-c is installed with it. See-through is run separately.
+---
+
+# rig-parts — a painting to a Spine rig, for agents
+
+rig-parts merges See-through's two layer runs over one painting into rig-space
+parts, authors a rig spec and a motion spec over them, and hands those to
+rig-c, which compiles, gates, packs and renders. You cannot see the painting,
+the layers or the rig. The printed lines, `docs/AUTHORING.md` and the files each
+stage writes are the whole interface.
+
+## Non-negotiables
+
+- **rig-c's gate is never bypassed.** rig-parts writes no Spine data
+  itself; `rig` writes only after rigc's `build` gate is green, and `build`'s
+  artifact is what rigc wrote. There is no flag that skips it, and none may be added.
+  `check.json`'s `rigc_entry` names which gate ran: rigc's own validator in an
+  install, the spine-core round trip where the runtime is installed beside rigc.
+- **No value is invented.** A missing config field is a refusal naming it. Take a
+  value from the command that proposes it (`propose --head-box`,
+  `assemble --propose-plan`, `propose`) or decide it yourself — never guess one
+  because the tool refused.
+- **The refusal is the instruction.** `FAIL  RULE: object — detail` names the object,
+  the value found and the value required; AUTHORING §6 maps every rule to the field
+  or input that has to change.
+- **Green is not "looks right".** `check` measures the gates, the seam, the loop and
+  six judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`,
+  `TIP_OVER_ROOT`, `STILL_REGIONS_DARK` — its face half in the head's own frame —
+  and `TEXTURE_STRETCH`) (AUTHORING §7). A judgement line that says
+  SKIP was not verified: report it as such, with its reason, never as passed.
+  No line judges a bang over the face or the eyes: `STILL_REGIONS_DARK`'s
+  `crossing` reports how deep each one swings, and only an eye can say whether
+  that reads right.
+- **What a scene asks is declared, not assumed.** When the request says what the
+  motion must do — a hand on a cup, a sleeve taking half an arm's turn, a joint
+  inside a range, a fringe that must not part from the face — write it into a `spine-parts-requirements/1` file and pass
+  `check --requirements <file>` (or `build --requirements`); every bar in it is the
+  requester's, never yours to invent (AUTHORING §7, *Declared requirements*). Each
+  line is PASS, FAIL or NOT MEASURABLE; a NOT MEASURABLE is not green, and a kind the
+  file does not declare was not measured — say so, never "passed".
+- **A hole in the layers is invisible to every bar.** Painting that no part holds is
+  missing from the setup pose and from the flat stack alike, so the seam passes over
+  it. `assemble` lists it (`uncovered hole N: <px> px at x,y wxh (between …)`) and
+  paints it red in `recomposite_error_rig.png`; `check` copies it into `check.json` as
+  `RECOMPOSITE_HOLES`, a REPORTED line with no bar. Read it; never report it as a
+  pass.
+
+## The loop
+
+1. `rig-parts inputs --source <painting> --config config.json --out <dir>` writes
+   `st_input_full.png`, the painting on a white square. The config needs only `key`,
+   `seethrough` and `assemble.rig_scale` at this point. Run See-through on it — any
+   route; the optional `comfy seethrough` adapter only talks to a ComfyUI box.
+2. `rig-parts layers <full run>` — read the table. A `WARN  PLAN_LAYER_…` line names
+   a layer See-through invented (a translucent haze, or one out of proportion);
+   the plan step leaves it out and says so in its `notes`.
+3. `rig-parts propose --head-box --full <full run> --canvas <W>x<H>` → put
+   `head_box` in the config, run `inputs` again (it now also writes
+   `st_input_head.png`, the crop at that box), and run See-through on the crop.
+4. `rig-parts assemble --propose-plan …` → `config.assemble.plan` and
+   `extend_below_crop`.
+5. `rig-parts assemble … --out work` — read the `uncovered hole` lines and look at
+   `work/render/recomposite_error_rig.png`; a large red hole between two parts is a
+   gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
+   not in the rig. Then `rig-parts propose --parts work/rig
+   --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `motion`
+   from `proposal.json` into the config. `assemble` needs the plan and none of
+   those four; do not stub them to get past it (AUTHORING §4 says what each step
+   requires). If an `uncovered hole` stays large with the plan right — a piece
+   of the figure neither run holds, red in `recomposite_error_rig.png` — add an
+   `assemble.patches` entry (a rig-pixel box, `alpha: "silhouette"`, drawn
+   `"back"` and reaching under its neighbours, its bone in `regions`) and assemble
+   again; never add a part to `rig/` or `parts/` by hand (AUTHORING §5).
+   One layer holding two things that must move apart (a scarf end inside
+   `topwear`, both arms in one `handwear`): add an `assemble.cuts` entry — a
+   polygon in rig pixels read off `work/rig/parts/<part>.png` plus its
+   `parts.json` `x`, `y`, a new name, a `draw`, an `overlap` (the band the part
+   keeps under the piece's edge; 1 px closed the seam on scarf) — and give the piece its own
+   `meshes` entry; the `cut:` line gives the split. At overlap 0 a cut through
+   opaque art leaves a seam `check` reads (AUTHORING §5).
+   A seated or reclining figure: add `--keypoints <file>` (body-18 joints in
+   painting px, each observed, occluded or missing; AUTHORING §3, *A posed
+   figure*) so the neck, hip, chest and sleeves follow the pose and LINT reads
+   the joints, not screen y. Never write a joint you did not get from an
+   estimator or the painting: say `missing` and let the rule stand in.
+6. Correct against `render/landmarks.png` and `note:` lines; a
+   `coverage … not checked` line is a bone no check read (the line says why),
+   and `basis.json` beside the proposal says what each bone rests on — check
+   the `ratio` bones and any with a `fallback` first. `propose …
+   --from-config config.json` (with the same `--keypoints`) until it prints no
+   `LINT` line. `rig-parts compare
+   --left work/proposal.json --right config.json` lists what the correction changed,
+   bone by bone — origin, parent, tip, length, direction (AUTHORING §4).
+   A constraint the motion needs (an ik reaching a scene target, physics on a
+   link) goes in `config.constraints`, in rig-c's own rig-spec shape: the
+   loader resolves the bones it names and nothing else, and rigc's gate refuses
+   the rest in its words. A scene target is a single bone under `root`. A two-bone
+   ik over links the idle keys needs `--idle-keys direct` on `rig` or `build`
+   (rigc refuses the pair the link's control splits, and the line names the flag
+   on the command that ran; AUTHORING §3).
+7. `rig-parts build --config … --source … --full … --head … --out out --loop`
+   (add `--idle-keys direct` when step 6 said so).
+   It stops at the first stage that refuses, printing that stage's lines under
+   `[assemble]`, `[rig]` or `[check]`. Fix what the FAIL line names and build again.
+8. Read `out/check/check.json` — the six judgement lines the same way as the seam
+   and the loop: a FAIL names the field to change (AUTHORING §6);
+   `TEXTURE_STRETCH` names the worst mesh triangle (slot, triangle, vertices, edge,
+   frame), so quote it even on a PASS. Quote
+   `RECOMPOSITE_HOLES` (uncovered px, hole count, the largest hole's box) in the
+   report whatever `PASS` says. The artifact is the three paths the build prints
+   last: `check/build/skeleton.json`, `skeleton.atlas` and the packed page. Report
+   them with the pack line and the check figures verbatim.
+
+Several characters in one rig: build each one green on its own, then
+`rig-parts compose --scene scene.json --out scene` (spec `spine-parts-scene/1`:
+the canvas, each character's `build` and `offset`, an optional plate with its
+`provenance`, and the `order` of the characters' slots, back to front). You write
+the order and the offsets; nothing infers them, nothing scales a character, and
+nothing detects or separates people. Report the plate's provenance as you declared
+it and the order as `scene.json` records it (AUTHORING §7, *Composing several
+characters*).
+
+`--seam silhouette` repairs more of the seam on white garments than the default
+`near-white` (the demo: 10,340 → 8,644 recomposite error pixels); the default is
+the reference implementation's rule. `--project visible` lets thin visible parts
+(lashes, brows, irises) take the painting's pixels, which the default `core` rule
+erodes away. Name both rules you used in your report, and quote the assemble
+`pixels:` line: its occluded share is hidden art, its "visible but not projected"
+share is synthesis where the painting was there to be taken.
+
+## What this will not do
+
+- Run See-through or generate the painting itself. The optional `comfy seethrough`
+  and `comfy paint` commands drive a ComfyUI box you name; nothing else here reaches
+  a GPU or the network.
+- Give a layer two depths: a layer in front of another in one place and behind it in
+  another is right in the still and wrong in motion.
+- Propose, key or judge any animation but the looping `idle`, or lip-sync: every slot
+  holds one attachment, so nothing swaps a part's image. Expressions and a jiggle are
+  yours to build on top (below).
+- Write animated WebP: `loop` writes GIF and APNG.
+- Know what the art does not tag: a swinging element painted inside another layer,
+  hair of an unfamiliar shape, whether an accessory swings. Those are yours to add.
+- Promise a success rate. Three public characters and eight private ones check green;
+  that is all that has been measured.
+
+## Where to read next
+
+[docs/AUTHORING.md](https://github.com/rig-c/parts/blob/main/docs/AUTHORING.md)
+first — every config field, the command order, what to read after each stage, every
+refusal. It is in the installed package at `node_modules/@rig-c/parts/docs/AUTHORING.md`,
+the copy that matches the version you run. Two recipes there cover what this package
+leaves to you:
+
+- An expression or any other named animation: AUTHORING §3, *Recipe: expressions and other
+  named animations* (`motion.animations_from`; built and gated with the rig, not measured).
+- A jiggle (a bust, the hips): AUTHORING §3, *Recipe: a soft region driven by physics* (a
+  config-only bone, a `contour` region on it, a `physics` constraint; `examples/sample`
+  carries one, and its slow idle barely moves it).
+
+A `RIG_RIGC_GREEN` or `CHECK_RIGC_GREEN`
+line quotes rig-c's own assertion; rig-c's guide for those is
+`node_modules/rig-c/docs/AUTHORING.md`, and its `rigc` skill covers the compiler.

package/src/apng.ts

@@ -0,0 +1,381 @@
+/**
+ * Animated PNG (APNG) encoder — `acTL` / `fcTL` / `fdAT` over 8-bit RGBA
+ * frames, the form GitHub renders in a README.
+ *
+ * Pure: bytes in, bytes out, no clock, no file system. The only thing it leans
+ * on is `node:zlib` for DEFLATE, which is also all rig-c's own PNG codec
+ * (`rig-c/tools/plate.ts`) leans on; the chunk framing and CRC are that
+ * codec's `pngChunk`, so there is one PNG chunk writer in the dependency tree,
+ * not two.
+ *
+ * What the encoder does, all of it lossless:
+ *
+ * - **Frame 0 is the default image.** Its `fcTL` precedes the `IDAT`, so a
+ *   decoder that knows nothing of APNG shows frame 0 — which is what the
+ *   selftest reads back through rig-c's `decodePng`.
+ * - **Consecutive identical frames are merged** into one frame whose delay is
+ *   their sum; the timing is kept exactly, because an APNG delay is a fraction
+ *   (`delay_num / delay_den`) and the fps is its denominator.
+ * - **Every later frame is cropped to the box of pixels that changed** from the
+ *   frame before (`dispose_op` NONE). When every pixel of that box is opaque in
+ *   both frames, unchanged pixels are written fully transparent and the frame
+ *   is blended OVER the previous one — transparent zeros compress far better
+ *   than repeated colour, and OVER of an opaque pixel is exact replacement.
+ *   Where any pixel in the box is translucent the frame is blended SOURCE
+ *   instead, since OVER would mix it with what is under it.
+ * - **Each scanline takes the PNG filter with the smallest sum of absolute
+ *   values** (libpng's heuristic), then zlib level 9.
+ *
+ * {@link encodeIndexedApng} is the second writer here: colour type 3, one
+ * shared palette, lossy by that palette and reporting its error. It is the
+ * small file; this one stays the exactness record.
+ *
+ * ⚠️ Animated WebP is out of scope: it needs a VP8 (lossy) or VP8L (lossless)
+ * bitstream encoder, and none ships here.
+ */
+import { deflateSync } from 'node:zlib';
+import { PNG_SIGNATURE, pngChunk } from 'rig-c/tools/plate.ts';
+import { histogram, mapToPalette, medianCut, type PaletteError, paletteError, type Rgba } from './palette.ts';
+import type { Raster } from './raster/types.ts';
+
+export interface AnimFrame {
+  image: Raster;
+  /** How many ticks of `1/fps` this frame is shown for. */
+  ticks: number;
+}
+
+export interface ApngStats {
+  /** Frames written into the file, after merging identical neighbours. */
+  frames: number;
+  /** Frames blended OVER with their unchanged pixels cleared, of `frames - 1` later frames. */
+  overFrames: number;
+  bytes: number;
+}
+
+export class EncodeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EncodeError';
+  }
+}
+
+function u32(n: number): Uint8Array {
+  return new Uint8Array([(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255]);
+}
+
+function u16(n: number): Uint8Array {
+  return new Uint8Array([(n >>> 8) & 255, n & 255]);
+}
+
+function concat(parts: readonly Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((s, p) => s + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+/**
+ * Filtered, deflated scanlines — an IDAT / fdAT payload. `rows` is `height`
+ * scanlines of `stride` bytes each, `bpp` bytes per pixel for the filters'
+ * left neighbour (1 for any indexed depth, as the PNG spec rounds it up).
+ * `adaptive` picks each scanline's filter by the smallest sum of absolute
+ * values (libpng's heuristic); otherwise every scanline is filter 0 (None).
+ */
+export function deflateScanlines(stride: number, height: number, bpp: number, rows: Uint8Array, adaptive: boolean): Uint8Array {
+  const raw = new Uint8Array((stride + 1) * height);
+  const trial = new Uint8Array(stride);
+  const best = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const row = rows.subarray(y * stride, (y + 1) * stride);
+    if (!adaptive) {
+      raw.set(row, y * (stride + 1) + 1);
+      continue;
+    }
+    const up = y > 0 ? rows.subarray((y - 1) * stride, y * stride) : null;
+    let bestType = 0;
+    let bestScore = Infinity;
+    for (let type = 0; type < 5; type++) {
+      let score = 0;
+      for (let i = 0; i < stride; i++) {
+        const a = i >= bpp ? row[i - bpp] : 0;
+        const b = up !== null ? up[i] : 0;
+        const c = i >= bpp && up !== null ? up[i - bpp] : 0;
+        const pred = type === 0 ? 0 : type === 1 ? a : type === 2 ? b : type === 3 ? (a + b) >>> 1 : paeth(a, b, c);
+        const v = (row[i] - pred) & 255;
+        trial[i] = v;
+        score += v < 128 ? v : 256 - v;
+      }
+      if (score < bestScore) {
+        bestScore = score;
+        bestType = type;
+        best.set(trial);
+      }
+    }
+    raw[y * (stride + 1)] = bestType;
+    raw.set(best, y * (stride + 1) + 1);
+  }
+  return new Uint8Array(deflateSync(raw, { level: 9 }));
+}
+
+/** Filtered, deflated scanlines of an RGBA window — the lossless APNG's IDAT / fdAT payload. */
+export function deflateRgba(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  return deflateScanlines(width * 4, height, 4, rgba, true);
+}
+
+function sameFrame(a: Raster, b: Raster): boolean {
+  if (a.data.length !== b.data.length) return false;
+  for (let i = 0; i < a.data.length; i++) if (a.data[i] !== b.data[i]) return false;
+  return true;
+}
+
+/** Merge runs of identical neighbours into one frame of their summed ticks. */
+export function mergeRuns(frames: readonly AnimFrame[]): AnimFrame[] {
+  const out: AnimFrame[] = [];
+  for (const f of frames) {
+    const last = out[out.length - 1];
+    if (last !== undefined && sameFrame(last.image, f.image)) out[out.length - 1] = { image: last.image, ticks: last.ticks + f.ticks };
+    else out.push({ image: f.image, ticks: f.ticks });
+  }
+  return out;
+}
+
+/** The box of pixels that differ between two same-size frames, or null when none does. */
+export function changedBox(prev: Raster, cur: Raster): { x: number; y: number; w: number; h: number } | null {
+  let x0 = cur.width;
+  let y0 = cur.height;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0; y < cur.height; y++) {
+    for (let x = 0; x < cur.width; x++) {
+      const i = (y * cur.width + x) * 4;
+      if (prev.data[i] !== cur.data[i] || prev.data[i + 1] !== cur.data[i + 1] || prev.data[i + 2] !== cur.data[i + 2] || prev.data[i + 3] !== cur.data[i + 3]) {
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
+    }
+  }
+  return x1 < 0 ? null : { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 };
+}
+
+export function checkFrames(frames: readonly AnimFrame[], fps: number): void {
+  if (frames.length === 0) throw new EncodeError('no frames to encode; at least one is required');
+  if (!Number.isInteger(fps) || fps < 1 || fps > 65535) throw new EncodeError(`fps ${fps}; an integer from 1 to 65535 is required`);
+  const { width, height } = frames[0].image;
+  if (width < 1 || height < 1) throw new EncodeError(`frame 0 is ${width}x${height}; a frame needs pixels`);
+  frames.forEach((f, i) => {
+    if (f.image.width !== width || f.image.height !== height) {
+      throw new EncodeError(`frame ${i} is ${f.image.width}x${f.image.height}; every frame must be frame 0's ${width}x${height}`);
+    }
+    if (!Number.isInteger(f.ticks) || f.ticks < 1) throw new EncodeError(`frame ${i} is shown for ${f.ticks} tick(s); a positive integer is required`);
+  });
+}
+
+/**
+ * Encode frames as an APNG that loops forever, each frame shown for
+ * `ticks / fps` seconds.
+ */
+export function encodeApng(input: readonly AnimFrame[], fps: number): { bytes: Uint8Array; stats: ApngStats } {
+  checkFrames(input, fps);
+  const frames = mergeRuns(input);
+  const { width, height } = frames[0].image;
+  let seq = 0;
+  let overFrames = 0;
+  const chunks: Uint8Array[] = [PNG_SIGNATURE];
+  chunks.push(pngChunk('IHDR', concat([u32(width), u32(height), new Uint8Array([8, 6, 0, 0, 0])])));
+  chunks.push(pngChunk('acTL', concat([u32(frames.length), u32(0)])));
+  const fctl = (x: number, y: number, w: number, h: number, ticks: number, blend: number): Uint8Array =>
+    pngChunk('fcTL', concat([u32(seq++), u32(w), u32(h), u32(x), u32(y), u16(ticks), u16(fps), new Uint8Array([0, blend])]));
+  frames.forEach((f, i) => {
+    if (i === 0) {
+      chunks.push(fctl(0, 0, width, height, f.ticks, 0));
+      chunks.push(pngChunk('IDAT', deflateRgba(width, height, new Uint8Array(f.image.data.buffer, f.image.data.byteOffset, f.image.data.byteLength))));
+      return;
+    }
+    const prev = frames[i - 1].image;
+    // mergeRuns guarantees a difference; the box is never null here.
+    const box = changedBox(prev, f.image) ?? { x: 0, y: 0, w: 1, h: 1 };
+    const win = new Uint8Array(box.w * box.h * 4);
+    let opaque = true;
+    for (let y = 0; y < box.h; y++) {
+      for (let x = 0; x < box.w; x++) {
+        const s = ((box.y + y) * width + box.x + x) * 4;
+        if (prev.data[s + 3] !== 255 || f.image.data[s + 3] !== 255) opaque = false;
+        win.set(f.image.data.subarray(s, s + 4), (y * box.w + x) * 4);
+      }
+    }
+    if (opaque) {
+      overFrames++;
+      for (let y = 0; y < box.h; y++) {
+        for (let x = 0; x < box.w; x++) {
+          const s = ((box.y + y) * width + box.x + x) * 4;
+          const same = prev.data[s] === f.image.data[s] && prev.data[s + 1] === f.image.data[s + 1] && prev.data[s + 2] === f.image.data[s + 2];
+          if (same) win.fill(0, (y * box.w + x) * 4, (y * box.w + x) * 4 + 4);
+        }
+      }
+    }
+    chunks.push(fctl(box.x, box.y, box.w, box.h, f.ticks, opaque ? 1 : 0));
+    chunks.push(pngChunk('fdAT', concat([u32(seq++), deflateRgba(box.w, box.h, win)])));
+  });
+  chunks.push(pngChunk('IEND', new Uint8Array(0)));
+  const bytes = concat(chunks);
+  return { bytes, stats: { frames: frames.length, overFrames, bytes: bytes.length } };
+}
+
+/** The quantised colours of an indexed APNG, before the reserved transparent entry. */
+export const INDEXED_COLOURS = 255;
+
+export interface IndexedOptions {
+  /** Floyd–Steinberg error diffusion before matching (`src/palette.ts`). */
+  dither: boolean;
+  /** Per-scanline adaptive filters instead of filter 0 on every scanline. */
+  adaptiveFilter: boolean;
+}
+
+/** What `loop` ships: no dithering, filter 0 — the smaller file at the smaller error on both examples (see the PR measuring it). */
+export const INDEXED_DEFAULTS: IndexedOptions = { dither: false, adaptiveFilter: false };
+
+export interface IndexedApngStats extends ApngStats {
+  /** PLTE entries, the transparent one included; at most 256. */
+  entries: number;
+  /** Distinct RGBA colours across every input frame. */
+  distinct: number;
+  /** Bits per index: 1, 2, 4 or 8, the fewest the palette fits in. */
+  bitDepth: number;
+  /** Palette error against the input frames, over every frame. */
+  all: PaletteError;
+}
+
+function packIndices(ix: Uint8Array, w: number, h: number, depth: number): { rows: Uint8Array; stride: number } {
+  const stride = Math.ceil((w * depth) / 8);
+  if (depth === 8) return { rows: ix, stride };
+  const rows = new Uint8Array(stride * h);
+  const perByte = 8 / depth;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const shift = 8 - depth * ((x % perByte) + 1);
+      rows[y * stride + Math.floor(x / perByte)] |= ix[y * w + x] << shift;
+    }
+  }
+  return { rows, stride };
+}
+
+/**
+ * Encode frames as an indexed (colour type 3) APNG that loops forever — the
+ * README-sized animation, with its palette error measured and returned.
+ *
+ * - **One palette for every frame**: entry 0 is reserved fully transparent
+ *   (`tRNS` alpha 0), entries 1..255 are `src/palette.ts`'s median cut of the
+ *   union of every frame's RGBA pixels, alpha graded per entry when the frames
+ *   have translucent pixels. `tRNS` is written only as far as the last entry
+ *   whose alpha is not 255.
+ * - **Bit depth** is the fewest bits the entries fit in (1, 2, 4 or 8).
+ * - **Frames are differenced in index space**, as the GIF is: neighbours that
+ *   quantise to the same indices merge, and every later frame is cropped to the
+ *   box of indices that changed. When every changed index in the box is an
+ *   opaque entry, unchanged pixels are written as entry 0 and the frame is
+ *   blended OVER (exact: OVER of an opaque pixel replaces, of alpha 0 keeps);
+ *   otherwise the box is written whole and blended SOURCE.
+ * - zlib level 9; the filter is {@link IndexedOptions.adaptiveFilter}.
+ */
+export function encodeIndexedApng(input: readonly AnimFrame[], fps: number, opts: IndexedOptions = INDEXED_DEFAULTS): { bytes: Uint8Array; stats: IndexedApngStats } {
+  checkFrames(input, fps);
+  const images = input.map((f) => f.image);
+  const colours = histogram(images);
+  const cut = medianCut(colours, INDEXED_COLOURS);
+  const mapped = mapToPalette(images, cut, opts.dither);
+  const all = paletteError(images, mapped, cut);
+  const palette: Rgba[] = [[0, 0, 0, 0], ...cut];
+  const { width, height } = images[0];
+  const runs: Array<{ ix: Uint8Array; ticks: number }> = [];
+  mapped.forEach((m, i) => {
+    const ix = new Uint8Array(m.length);
+    for (let p = 0; p < m.length; p++) ix[p] = m[p] + 1;
+    const last = runs[runs.length - 1];
+    if (last !== undefined && last.ix.every((v, p) => v === ix[p])) last.ticks += input[i].ticks;
+    else runs.push({ ix, ticks: input[i].ticks });
+  });
+  const depth = palette.length <= 2 ? 1 : palette.length <= 4 ? 2 : palette.length <= 16 ? 4 : 8;
+  let lastTranslucent = 0;
+  palette.forEach((c, i) => {
+    if (c[3] !== 255) lastTranslucent = i;
+  });
+
+  let seq = 0;
+  let overFrames = 0;
+  const chunks: Uint8Array[] = [PNG_SIGNATURE];
+  chunks.push(pngChunk('IHDR', concat([u32(width), u32(height), new Uint8Array([depth, 3, 0, 0, 0])])));
+  chunks.push(pngChunk('acTL', concat([u32(runs.length), u32(0)])));
+  chunks.push(pngChunk('PLTE', new Uint8Array(palette.flatMap((c) => [c[0], c[1], c[2]]))));
+  chunks.push(pngChunk('tRNS', new Uint8Array(palette.slice(0, lastTranslucent + 1).map((c) => c[3]))));
+  const fctl = (x: number, y: number, w: number, h: number, ticks: number, blend: number): Uint8Array =>
+    pngChunk('fcTL', concat([u32(seq++), u32(w), u32(h), u32(x), u32(y), u16(ticks), u16(fps), new Uint8Array([0, blend])]));
+  const payload = (ix: Uint8Array, w: number, h: number): Uint8Array => {
+    const { rows, stride } = packIndices(ix, w, h, depth);
+    return deflateScanlines(stride, h, 1, rows, opts.adaptiveFilter);
+  };
+  runs.forEach((run, i) => {
+    if (i === 0) {
+      chunks.push(fctl(0, 0, width, height, run.ticks, 0));
+      chunks.push(pngChunk('IDAT', payload(run.ix, width, height)));
+      return;
+    }
+    const prev = runs[i - 1].ix;
+    let x0 = width;
+    let y0 = height;
+    let x1 = -1;
+    let y1 = -1;
+    let opaque = true;
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const p = y * width + x;
+        if (prev[p] === run.ix[p]) continue;
+        if (palette[run.ix[p]][3] !== 255) opaque = false;
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
+    }
+    // Merged runs differ, so the box is never empty here.
+    const w = x1 - x0 + 1;
+    const h = y1 - y0 + 1;
+    const win = new Uint8Array(w * h);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const p = (y0 + y) * width + x0 + x;
+        win[y * w + x] = opaque && prev[p] === run.ix[p] ? 0 : run.ix[p];
+      }
+    }
+    if (opaque) overFrames++;
+    chunks.push(fctl(x0, y0, w, h, run.ticks, opaque ? 1 : 0));
+    chunks.push(pngChunk('fdAT', concat([u32(seq++), payload(win, w, h)])));
+  });
+  chunks.push(pngChunk('IEND', new Uint8Array(0)));
+  const bytes = concat(chunks);
+  return { bytes, stats: { frames: runs.length, overFrames, bytes: bytes.length, entries: palette.length, distinct: colours.length, bitDepth: depth, all } };
+}
+
+/** The chunk types of a PNG file, in order — what the selftest reads the structure back with. */
+export function chunkTypes(bytes: Uint8Array): string[] {
+  const out: string[] = [];
+  let at = 8;
+  while (at + 8 <= bytes.length) {
+    const len = ((bytes[at] << 24) | (bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+    out.push(String.fromCharCode(bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]));
+    at += 12 + len;
+  }
+  return out;
+}