@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/sprite-decompile.js

@@ -0,0 +1,786 @@
+import { requireValue } from "./required.js";
+// Lossless decompiler: existing pixel art (RGBA frames) to a structured
+// pixel-sprite/0.1 document a model can read and edit. It finds the outline
+// colour, groups colours into ramps (by hue and by which colours touch),
+// splits the sprite into parts (connected regions of one ramp), fits exact
+// shapes, explains shading with bevels where that saves pixels, and encodes
+// animation frames as a shift plus per-part changes. Whatever the operations
+// do not explain stays as literal pixels, so the result always compiles back
+// to the input exactly; `decompile` verifies that before returning.
+import { SPRITE_FORMAT, compileSprite, rgbToOklab, toHex } from "./sprite-compiler.js";
+const N4 = [
+    [0, -1],
+    [-1, 0],
+    [1, 0],
+    [0, 1],
+];
+// Printable ASCII without '"', '\' and '.', most readable first.
+const KEYS = [
+    ..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#$%&'()*+,-/:;<=>?@[]^_`{|}~!",
+];
+const hexAt = (rgba, p) => toHex([
+    requireValue(rgba[p * 4]),
+    requireValue(rgba[p * 4 + 1]),
+    requireValue(rgba[p * 4 + 2]),
+    requireValue(rgba[p * 4 + 3]),
+]);
+const lch = (hex) => {
+    const n = parseInt(hex.slice(1, 7), 16);
+    const [L, a, b] = rgbToOklab([(n >> 16) & 255, (n >> 8) & 255, n & 255]);
+    return { L, C: Math.hypot(a, b), h: ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360 };
+};
+const hueGap = (a, b) => Math.min(Math.abs(a - b), 360 - Math.abs(a - b));
+function hueName({ L, C, h }) {
+    if (C < 0.035)
+        return L > 0.85 ? "white" : L < 0.3 ? "black" : "gray";
+    if (h >= 20 && h < 75 && L < 0.62)
+        return "brown";
+    const names = [
+        [40, "red"],
+        [75, "orange"],
+        [115, "yellow"],
+        [170, "green"],
+        [220, "teal"],
+        [285, "blue"],
+        [325, "purple"],
+        [360, "pink"],
+    ];
+    return (names.find(([limit]) => h < limit) ?? [0, "red"])[1];
+}
+/** Colour statistics, outline colour and ramps for a set of frames. */
+function analysePalette(frames) {
+    const count = new Map();
+    const silhouette = new Map();
+    const touch = new Map();
+    let silhouetteTotal = 0;
+    for (const f of frames) {
+        const { width: W, height: H, rgba } = f;
+        const op = (x, y) => x >= 0 && y >= 0 && x < W && y < H && requireValue(rgba[(y * W + x) * 4 + 3]) > 0;
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++) {
+                if (!op(x, y))
+                    continue;
+                const c = hexAt(rgba, y * W + x);
+                count.set(c, (count.get(c) ?? 0) + 1);
+                if (N4.some(([dx, dy]) => !op(x + dx, y + dy))) {
+                    silhouette.set(c, (silhouette.get(c) ?? 0) + 1);
+                    silhouetteTotal++;
+                }
+                for (const [dx, dy] of [
+                    [1, 0],
+                    [0, 1],
+                ])
+                    if (op(x + dx, y + dy)) {
+                        const n = hexAt(rgba, (y + dy) * W + x + dx);
+                        if (n !== c) {
+                            const k = c < n ? `${c}|${n}` : `${n}|${c}`;
+                            touch.set(k, (touch.get(k) ?? 0) + 1);
+                        }
+                    }
+            }
+    }
+    const colours = [...count.keys()].sort();
+    const info = new Map(colours.map((c) => [c, lch(c)]));
+    // Outline: the colour covering most of the silhouette, if it is one of the two darkest.
+    let outline = null;
+    const bySil = [...silhouette.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+    const darkest = [...colours]
+        .sort((a, b) => requireValue(info.get(a)).L - requireValue(info.get(b)).L)
+        .slice(0, 2);
+    if (bySil.length &&
+        requireValue(bySil[0])[1] >= 0.5 * silhouetteTotal &&
+        darkest.includes(requireValue(bySil[0])[0]))
+        outline = requireValue(bySil[0])[0];
+    // Ramps: union colours that touch often and have compatible hue and chroma.
+    const parent = new Map(colours.map((c) => [c, c]));
+    const find = (c) => parent.get(c) === c ? c : (parent.set(c, find(requireValue(parent.get(c)))), requireValue(parent.get(c)));
+    const pairs = [...touch.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+    for (const [k, n] of pairs) {
+        const [a0, b0] = k.split("|");
+        const a = requireValue(a0), b = requireValue(b0);
+        if (a === outline || b === outline)
+            continue;
+        const A = requireValue(info.get(a)), B = requireValue(info.get(b));
+        const small = Math.min(requireValue(count.get(requireValue(a))), requireValue(count.get(requireValue(b))));
+        if (n < Math.max(2, 0.05 * small))
+            continue;
+        const neutral = A.C < 0.035 && B.C < 0.035;
+        const compatible = neutral
+            ? Math.abs(A.L - B.L) < 0.45
+            : Math.min(A.C, B.C) >= 0.02 && hueGap(A.h, B.h) < 38 && Math.abs(A.L - B.L) < 0.5;
+        if (compatible)
+            parent.set(find(requireValue(a)), find(requireValue(b)));
+    }
+    const groups = new Map();
+    for (const c of colours) {
+        if (c === outline)
+            continue;
+        const r = find(c);
+        if (!groups.has(r))
+            groups.set(r, []);
+        requireValue(groups.get(r)).push(c);
+    }
+    const ramps = [];
+    const used = new Map();
+    for (const members of [...groups.values()].sort((a, b) => b.reduce((s, c) => s + requireValue(count.get(c)), 0) -
+        a.reduce((s, c) => s + requireValue(count.get(c)), 0))) {
+        members.sort((a, b) => requireValue(info.get(a)).L - requireValue(info.get(b)).L);
+        const mode = [...members].sort((a, b) => requireValue(count.get(b)) - requireValue(count.get(a)))[0];
+        const base = hueName(requireValue(info.get(requireValue(mode))));
+        const k = (used.get(base) ?? 0) + 1;
+        used.set(base, k);
+        ramps.push({ name: k === 1 ? base : `${base}${k}`, colours: members });
+    }
+    const rampOf = new Map();
+    for (const r of ramps)
+        r.colours.forEach((c, i) => rampOf.set(c, { ramp: r.name, step: i }));
+    return { count, outline, ramps, rampOf, info };
+}
+/** Pixel set predicted by the compiler's ellipse rule on a bounding box. */
+function ellipseSet(x, y, w, h) {
+    const s = new Set();
+    for (let j = 0; j < h; j++)
+        for (let i = 0; i < w; i++) {
+            const u = (i + 0.5 - w / 2) / (w / 2), v = (j + 0.5 - h / 2) / (h / 2);
+            if (u * u + v * v <= 1)
+                s.add(`${x + i},${y + j}`);
+        }
+    return s;
+}
+/** Splits one frame into parts: 4-connected regions of one ramp; tiny enclosed regions become details of their neighbour. */
+function regions(frame, pal) {
+    const { width: W, height: H, rgba } = frame;
+    const label = new Int32Array(W * H).fill(-1);
+    const list = [];
+    for (let p = 0; p < W * H; p++) {
+        if (!rgba[p * 4 + 3] || requireValue(label[p]) >= 0)
+            continue;
+        const c = hexAt(rgba, p);
+        if (c === pal.outline)
+            continue;
+        const ramp = requireValue(pal.rampOf.get(c)).ramp;
+        const idx = list.length;
+        const pix = [];
+        const stack = [p];
+        label[p] = idx;
+        while (stack.length) {
+            const q = requireValue(stack.pop());
+            pix.push(requireValue(q));
+            const x = q % W, y = Math.floor(q / W);
+            for (const [dx, dy] of N4) {
+                const nx = x + dx, ny = y + dy, n = ny * W + nx;
+                if (nx < 0 || ny < 0 || nx >= W || ny >= H || requireValue(label[n]) >= 0 || !rgba[n * 4 + 3])
+                    continue;
+                const nc = hexAt(rgba, n);
+                if (nc === pal.outline || requireValue(pal.rampOf.get(nc)).ramp !== ramp)
+                    continue;
+                label[n] = idx;
+                stack.push(n);
+            }
+        }
+        list.push({ ramp, pix, absorbed: false });
+    }
+    // Absorb regions of at most two pixels that touch exactly one other region (and nothing else but outline).
+    for (const [i, r] of list.entries()) {
+        if (r.pix.length > 2)
+            continue;
+        const touching = new Set();
+        let open = false;
+        for (const q of r.pix) {
+            const x = q % W, y = Math.floor(q / W);
+            for (const [dx, dy] of N4) {
+                const nx = x + dx, ny = y + dy, n = ny * W + nx;
+                if (nx < 0 || ny < 0 || nx >= W || ny >= H || !rgba[n * 4 + 3])
+                    open = true;
+                else if (requireValue(label[n]) >= 0 && label[n] !== i)
+                    touching.add(requireValue(label[n]));
+            }
+        }
+        if (!open && touching.size === 1) {
+            const host = requireValue([...touching][0]);
+            if (requireValue(list[host]).pix.length > 2) {
+                for (const q of r.pix)
+                    label[q] = host;
+                requireValue(list[host]).pix.push(...r.pix);
+                r.absorbed = true;
+            }
+        }
+    }
+    let kept = splitBySeeds(frame, list.filter((r) => !r.absorbed));
+    // Very busy images (sheets, previews): one part per ramp keeps the document within budget.
+    if (kept.length > MAX_REGIONS) {
+        const byRamp = new Map();
+        for (const r of kept) {
+            if (!byRamp.has(r.ramp))
+                byRamp.set(r.ramp, { ramp: r.ramp, pix: [], absorbed: false });
+            for (const q of r.pix)
+                requireValue(byRamp.get(r.ramp)).pix.push(q);
+        }
+        kept = [...byRamp.values()];
+    }
+    return { label, list: kept, all: list };
+}
+/** Above this many regions, regions merge per ramp. */
+const MAX_REGIONS = 150;
+/** Frame-0 layers allowed before falling back to literal rows (the compiler accepts 512). */
+const LAYER_BUDGET = 480;
+/**
+ * Splits a ramp region where two or more thick single-colour areas each cover
+ * a substantial share of it (a light frame around a darker panel, say). Other
+ * pixels join the nearest area by breadth-first distance inside the region.
+ * One-pixel lines such as highlights never start a split.
+ */
+function splitBySeeds(frame, list) {
+    const { width: W, rgba } = frame;
+    const out = [];
+    for (const r of list) {
+        const set = new Set(r.pix);
+        const seen = new Set();
+        const seeds = [];
+        for (const p of r.pix) {
+            if (seen.has(p))
+                continue;
+            const c = hexAt(rgba, p);
+            const comp = [];
+            const stack = [p];
+            seen.add(p);
+            while (stack.length) {
+                const q = requireValue(stack.pop());
+                comp.push(q);
+                for (const [dx, dy] of N4) {
+                    const x = (q % W) + dx, n = q + dy * W + dx;
+                    if (x < 0 || x >= W || !set.has(n) || seen.has(n) || hexAt(rgba, n) !== c)
+                        continue;
+                    seen.add(n);
+                    stack.push(n);
+                }
+            }
+            // Thick: at least two pixels across in both directions, and filled
+            // (area of at least twice the longer side), so one-pixel lines never qualify.
+            let bx0 = Infinity, by0 = Infinity, bx1 = -Infinity, by1 = -Infinity;
+            for (const q of comp) {
+                bx0 = Math.min(bx0, q % W);
+                bx1 = Math.max(bx1, q % W);
+                by0 = Math.min(by0, Math.floor(q / W));
+                by1 = Math.max(by1, Math.floor(q / W));
+            }
+            const bw = bx1 - bx0 + 1, bh = by1 - by0 + 1;
+            const thick = Math.min(bw, bh) >= 2 && comp.length >= 2 * Math.max(bw, bh);
+            if (thick && comp.length >= Math.max(12, 0.15 * r.pix.length))
+                seeds.push(comp);
+        }
+        const colours = new Set(seeds.map((c) => hexAt(rgba, requireValue(c[0]))));
+        if (seeds.length < 2 || colours.size < 2) {
+            out.push(r);
+            continue;
+        }
+        const owner = new Map();
+        let frontier = [];
+        seeds.forEach((c, i) => c.forEach((q) => (owner.set(q, i), frontier.push(q))));
+        while (frontier.length) {
+            const next = [];
+            for (const q of frontier)
+                for (const [dx, dy] of N4) {
+                    const x = (q % W) + dx, n = q + dy * W + dx;
+                    if (x < 0 || x >= W || !set.has(n) || owner.has(n))
+                        continue;
+                    owner.set(n, requireValue(owner.get(q)));
+                    next.push(n);
+                }
+            frontier = next;
+        }
+        const parts = seeds.map(() => []);
+        for (const p of r.pix)
+            requireValue(parts[owner.get(p) ?? 0]).push(p);
+        for (const pix of parts)
+            if (pix.length)
+                out.push({ ramp: r.ramp, pix, absorbed: false });
+    }
+    return out;
+}
+/** Best bevel for a region: the variant that leaves the fewest residual pixels, or null if none helps. */
+function bestBevel(frame, set, mode, rampColours, W) {
+    const { rgba } = frame;
+    const H = frame.height;
+    const inSet = (x, y) => x >= 0 && y >= 0 && x < W && y < H && set.has(y * W + x);
+    const modeIdx = rampColours.indexOf(mode);
+    const lighter = rampColours.slice(modeIdx + 1);
+    const darker = rampColours.slice(0, modeIdx);
+    const base = [...set].filter((p) => hexAt(rgba, p) !== mode).length;
+    let best = { residual: base, variant: null };
+    for (const [dir, [dx, dy]] of [
+        ["upper-left", [-1, -1]],
+        ["upper-right", [1, -1]],
+    ])
+        for (const light of [null, ...lighter])
+            for (const shadow of [null, ...darker]) {
+                if (!light && !shadow)
+                    continue;
+                let residual = 0;
+                for (const p of set) {
+                    const x = p % W, y = Math.floor(p / W);
+                    let side = null;
+                    if (!inSet(x, y + dy))
+                        side = "light";
+                    else if (!inSet(x, y - dy))
+                        side = "shadow";
+                    else if (!inSet(x + dx, y))
+                        side = "light";
+                    else if (!inSet(x - dx, y))
+                        side = "shadow";
+                    const tone = side === "light" ? light : side === "shadow" ? shadow : null;
+                    if ((tone ?? mode) !== hexAt(rgba, p))
+                        residual++;
+                }
+                if (residual < best.residual)
+                    best = { residual, variant: { dir, light, shadow } };
+            }
+    return best.variant ? { residual: best.residual, variant: best.variant } : null;
+}
+/** Rows of keys for a sparse set of pixels: [x0, y0, rows]. */
+function patchRows(points, keyOf, skip) {
+    let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+    for (const [x, y] of points) {
+        x0 = Math.min(x0, x);
+        y0 = Math.min(y0, y);
+        x1 = Math.max(x1, x);
+        y1 = Math.max(y1, y);
+    }
+    const grid = Array.from({ length: y1 - y0 + 1 }, () => Array(x1 - x0 + 1).fill(skip));
+    for (const [x, y, c] of points)
+        requireValue(grid[y - y0])[x - x0] = keyOf(c);
+    return { at: [x0, y0], rows: grid.map((r) => r.join("")) };
+}
+/**
+ * Decompiles frames of equal size. Returns { doc, summary, verified }. The
+ * document reproduces every frame exactly; `verified` is the compile check.
+ */
+export function decompileSprite(input, { id = "decompiled", animation = null, ms = 100 } = {}) {
+    if (!Array.isArray(input) || !input.length)
+        throw new RangeError("decompileSprite requires non-empty frames");
+    const first = requireValue(input[0]);
+    for (const f of input) {
+        if (!f ||
+            !Number.isInteger(f.width) ||
+            !Number.isInteger(f.height) ||
+            f.width < 1 ||
+            f.height < 1 ||
+            f.width > 1024 ||
+            f.height > 1024 ||
+            f.width !== first.width ||
+            f.height !== first.height ||
+            !(f.rgba instanceof Uint8Array) ||
+            f.rgba.length !== f.width * f.height * 4)
+            throw new RangeError("decompileSprite frames must have equal sizes within 1..1024 and complete RGBA data");
+    }
+    // The contract is exact for normalised RGBA: fully transparent pixels are 0,0,0,0.
+    let normalisedTransparent = 0;
+    const frames = input.map((f) => {
+        const rgba = new Uint8Array(f.rgba);
+        for (let i = 3; i < rgba.length; i += 4)
+            if (rgba[i] === 0 && (rgba[i - 1] || rgba[i - 2] || rgba[i - 3])) {
+                rgba.fill(0, i - 3, i + 1);
+                normalisedTransparent++;
+            }
+        return { width: f.width, height: f.height, rgba };
+    });
+    const W = requireValue(frames[0]).width, H = requireValue(frames[0]).height;
+    const pal = analysePalette(frames);
+    // Keys: ramp colours first (mnemonic where possible), then the outline, then "clear".
+    const keyOf = new Map();
+    const needed = pal.ramps.reduce((n, r) => n + r.colours.length, 0) + (pal.outline ? 1 : 0) + 1;
+    const keyWidth = needed <= KEYS.length ? 1 : 2;
+    const pool = keyWidth === 1 ? KEYS : KEYS.flatMap((a) => KEYS.map((b) => a + b));
+    const skip = ".".repeat(keyWidth);
+    const taken = new Set([skip]);
+    const take = (preferred) => {
+        const wanted = keyWidth === 1 ? [preferred, preferred?.toUpperCase()] : [];
+        const k = requireValue([...wanted, ...pool].find((c) => c && !taken.has(c)), "sprite has too many colours");
+        taken.add(k);
+        return k;
+    };
+    const refOf = new Map();
+    if (pal.outline) {
+        keyOf.set(pal.outline, take("o"));
+        refOf.set(pal.outline, "line");
+    }
+    for (const r of pal.ramps)
+        r.colours.forEach((c, i) => {
+            keyOf.set(c, take(r.name[0]));
+            refOf.set(c, `${r.name}.${i}`);
+        });
+    const clearKey = take("_");
+    const keys = Object.fromEntries([...keyOf.entries()].map(([c, k]) => [k, refOf.get(c)]));
+    keys[clearKey] = "clear";
+    const key = (c) => (c === "clear" ? clearKey : requireValue(keyOf.get(c)));
+    const palette = {
+        ...(keyWidth > 1 ? { keyWidth } : {}),
+        ...(pal.outline ? { colors: { line: pal.outline } } : {}),
+        ramps: Object.fromEntries(pal.ramps.map((r) => [r.name, r.colours])),
+        keys,
+    };
+    const summary = {
+        size: [W, H],
+        frames: frames.length,
+        outline: pal.outline,
+        ramps: [],
+        parts: [],
+        frameChanges: [],
+        normalisedTransparent,
+        fallback: null,
+    };
+    for (const r of pal.ramps)
+        summary.ramps.push({
+            name: r.name,
+            steps: r.colours.map((c) => ({ colour: c, pixels: requireValue(pal.count.get(c)) })),
+        });
+    // ---- frame 0: structured layers ----
+    const f0 = requireValue(frames[0]);
+    const reg = regions(requireValue(f0), pal);
+    const nameCount = new Map();
+    for (const r of reg.list)
+        nameCount.set(r.ramp, (nameCount.get(r.ramp) ?? 0) + 1);
+    const seen = new Map();
+    const ordered = [...reg.list].sort((a, b) => b.pix.length - a.pix.length || requireValue(a.pix[0]) - requireValue(b.pix[0]));
+    for (const r of ordered) {
+        const k = (seen.get(r.ramp) ?? 0) + 1;
+        seen.set(r.ramp, k);
+        r.name = nameCount.get(r.ramp) === 1 ? r.ramp : `${r.ramp}-${k}`;
+    }
+    const base = [], shading = [], fixes = [];
+    const predicted = new Map(); // pixel -> colour the structured layers produce
+    for (const r of ordered) {
+        const set = new Set(r.pix);
+        const colours = r.pix.map((p) => hexAt(f0.rgba, p));
+        const tally = new Map();
+        for (const c of colours)
+            tally.set(c, (tally.get(c) ?? 0) + 1);
+        const mode = requireValue([...tally.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0])[0];
+        const rampColours = requireValue(pal.ramps.find((x) => x.name === requireValue(pal.rampOf.get(mode)).ramp)).colours;
+        let x0 = W, y0 = H, x1 = -1, y1 = -1;
+        for (const p of r.pix) {
+            x0 = Math.min(x0, p % W);
+            y0 = Math.min(y0, Math.floor(p / W));
+            x1 = Math.max(x1, p % W);
+            y1 = Math.max(y1, Math.floor(p / W));
+        }
+        const bw = x1 - x0 + 1, bh = y1 - y0 + 1;
+        const keyset = new Set(r.pix.map((p) => `${p % W},${Math.floor(p / W)}`));
+        const sameSet = (s) => s.size === keyset.size && [...s].every((k) => keyset.has(k));
+        let shape = "mask";
+        const rectSet = (round) => {
+            const s = new Set();
+            for (let j = 0; j < bh; j++)
+                for (let i = 0; i < bw; i++)
+                    if (!(round && (i === 0 || i === bw - 1) && (j === 0 || j === bh - 1)))
+                        s.add(`${x0 + i},${y0 + j}`);
+            return s;
+        };
+        const fill = requireValue(refOf.get(mode));
+        if (sameSet(rectSet(false))) {
+            shape = "rect";
+            base.push({ part: r.name, rect: [x0, y0, bw, bh], fill });
+        }
+        else if (bw >= 3 && bh >= 3 && sameSet(rectSet(true))) {
+            shape = "rounded rect";
+            base.push({ part: r.name, rect: [x0, y0, bw, bh], fill, round: 1 });
+        }
+        else if (bw >= 3 && bh >= 3 && sameSet(ellipseSet(x0, y0, bw, bh))) {
+            shape = "ellipse";
+            base.push({ part: r.name, ellipse: [x0, y0, bw, bh], fill });
+        }
+        else {
+            const pr = patchRows(r.pix.map((p) => [p % W, Math.floor(p / W), mode]), key, skip);
+            base.push({ part: r.name, at: pr.at, pixels: pr.rows });
+        }
+        for (const p of r.pix)
+            predicted.set(p, mode);
+        const bev = rampColours.length > 1 ? bestBevel(f0, set, mode, rampColours, W) : null;
+        if (bev) {
+            const v = bev.variant;
+            const layer = { bevel: {}, parts: [r.name] };
+            if (v.light)
+                layer.bevel.light = refOf.get(v.light);
+            if (v.shadow)
+                layer.bevel.shadow = refOf.get(v.shadow);
+            if (v.dir !== "upper-left")
+                layer.dir = v.dir;
+            shading.push(layer);
+            // Recompute what the bevel paints.
+            const inSet = (x, y) => x >= 0 && y >= 0 && x < W && y < H && set.has(y * W + x);
+            const [dx, dy] = v.dir === "upper-left" ? [-1, -1] : [1, -1];
+            for (const p of r.pix) {
+                const x = p % W, y = Math.floor(p / W);
+                let side = null;
+                if (!inSet(x, y + dy))
+                    side = "light";
+                else if (!inSet(x, y - dy))
+                    side = "shadow";
+                else if (!inSet(x + dx, y))
+                    side = "light";
+                else if (!inSet(x - dx, y))
+                    side = "shadow";
+                const tone = side === "light" ? v.light : side === "shadow" ? v.shadow : null;
+                if (tone)
+                    predicted.set(p, tone);
+            }
+        }
+        const residual = r.pix.filter((p) => predicted.get(p) !== hexAt(f0.rgba, p));
+        if (residual.length) {
+            const pr = patchRows(residual.map((p) => [p % W, Math.floor(p / W), hexAt(f0.rgba, p)]), key, skip);
+            fixes.push({ part: r.name, at: pr.at, pixels: pr.rows });
+        }
+        summary.parts.push({
+            part: requireValue(r.name),
+            ramp: r.ramp,
+            bbox: [x0, y0, bw, bh],
+            pixels: r.pix.length,
+            shape,
+            fill,
+            bevel: bev
+                ? {
+                    dir: bev.variant.dir,
+                    light: bev.variant.light ? (refOf.get(bev.variant.light) ?? null) : null,
+                    shadow: bev.variant.shadow ? (refOf.get(bev.variant.shadow) ?? null) : null,
+                }
+                : null,
+            residualPixels: residual.length,
+        });
+    }
+    // Outline: an outside 4-neighbour outline of the filled regions, corrected by a patch.
+    const outlineLayers = [];
+    let outlineStats = null;
+    if (pal.outline) {
+        const filled = (x, y) => x >= 0 && y >= 0 && x < W && y < H && predicted.has(y * W + x);
+        const ring = new Set();
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++)
+                if (!filled(x, y) && N4.some(([dx, dy]) => filled(x + dx, y + dy)))
+                    ring.add(y * W + x);
+        const actual = new Set();
+        for (let p = 0; p < W * H; p++)
+            if (f0.rgba[p * 4 + 3] && hexAt(f0.rgba, p) === pal.outline)
+                actual.add(p);
+        const missing = [...actual].filter((p) => !ring.has(p));
+        const extra = [...ring].filter((p) => !actual.has(p) && !predicted.has(p));
+        const useOp = actual.size && missing.length + extra.length < actual.size;
+        if (useOp) {
+            outlineLayers.push({ outline: "line" });
+            for (const p of ring)
+                if (!predicted.has(p))
+                    predicted.set(p, pal.outline);
+            if (extra.length) {
+                const pr = patchRows(extra.map((p) => [p % W, Math.floor(p / W), "clear"]), key, skip);
+                outlineLayers.push({ at: pr.at, pixels: pr.rows });
+                for (const p of extra)
+                    predicted.delete(p);
+            }
+            if (missing.length) {
+                const pr = patchRows(missing.map((p) => [p % W, Math.floor(p / W), requireValue(pal.outline)]), key, skip);
+                outlineLayers.push({ part: "line", at: pr.at, pixels: pr.rows });
+                for (const p of missing)
+                    predicted.set(p, pal.outline);
+            }
+        }
+        else if (actual.size) {
+            const pr = patchRows([...actual].map((p) => [p % W, Math.floor(p / W), requireValue(pal.outline)]), key, skip);
+            outlineLayers.push({ part: "line", at: pr.at, pixels: pr.rows });
+            for (const p of actual)
+                predicted.set(p, pal.outline);
+        }
+        outlineStats = {
+            pixels: actual.size,
+            operation: Boolean(useOp),
+            added: missing.length,
+            removed: extra.length,
+        };
+    }
+    summary.outlineStats = outlineStats;
+    const celName = (i) => (animation ? `${animation}/${i}` : `frame/${i}`);
+    let layers0 = [...base, ...shading, ...outlineLayers, ...fixes];
+    // Too many layers for the compiler's budget: state frame 0 as literal rows in one part.
+    if (layers0.length > LAYER_BUDGET) {
+        const pts = [];
+        for (let p = 0; p < W * H; p++)
+            if (f0.rgba[p * 4 + 3])
+                pts.push([p % W, Math.floor(p / W), hexAt(f0.rgba, p)]);
+        const pr = patchRows(pts, key, skip);
+        summary.fallback = `literal: ${layers0.length} structured layers exceed ${LAYER_BUDGET}`;
+        layers0 = [{ part: "pixels", at: pr.at, pixels: pr.rows }];
+        summary.parts = [
+            {
+                part: "pixels",
+                ramp: null,
+                bbox: [pr.at[0], pr.at[1], requireValue(pr.rows[0]).length / skip.length, pr.rows.length],
+                pixels: pts.length,
+                shape: "literal",
+                fill: null,
+                bevel: null,
+                residualPixels: 0,
+            },
+        ];
+        if (summary.outlineStats)
+            summary.outlineStats = { ...summary.outlineStats, operation: false, added: 0, removed: 0 };
+    }
+    const cels = { [celName(0)]: { size: [W, H], layers: layers0 } };
+    // ---- later frames: best whole-frame shift plus per-part changes ----
+    const doc = {
+        format: SPRITE_FORMAT,
+        id,
+        palette,
+        cels,
+    };
+    let compiled = compileSprite(doc);
+    let prev = requireValue(compiled.cels.get(celName(0)));
+    for (let i = 1; i < frames.length; i++) {
+        const f = requireValue(frames[i]), a = requireValue(frames[i - 1]);
+        const px = (img, x, y) => x < 0 || y < 0 || x >= W || y >= H ? null : img.rgba.subarray((y * W + x) * 4, (y * W + x) * 4 + 4);
+        let best = { n: Infinity, dx: 0, dy: 0 };
+        for (let dy = -3; dy <= 3; dy++)
+            for (let dx = -3; dx <= 3; dx++) {
+                let n = 0;
+                for (let y = 0; y < H; y++)
+                    for (let x = 0; x < W; x++) {
+                        const s = px(a, x - dx, y - dy), t = requireValue(px(f, x, y));
+                        const sa = s ? s[3] : 0;
+                        if (sa !== t[3] || (sa && (s?.[0] !== t[0] || s?.[1] !== t[1] || s?.[2] !== t[2])))
+                            n++;
+                    }
+                // Prefer no shift on ties, then the smallest shift.
+                const cost = n * 100 + Math.abs(dx) + Math.abs(dy);
+                if (cost < best.n)
+                    best = { n: cost, dx, dy };
+            }
+        const layers = [];
+        // A shift is only worth a layer if it explains pixels and stays on the canvas.
+        let shifted = false;
+        if ((best.dx || best.dy) && prev) {
+            const names = [...new Set([...prev.canvas.owners].filter((o) => o >= 0))];
+            let fits = true;
+            for (let p = 0; p < W * H; p++)
+                if (prev.canvas.rgba[p * 4 + 3] && requireValue(prev.canvas.owners[p]) >= 0) {
+                    const x = (p % W) + best.dx, y = Math.floor(p / W) + best.dy;
+                    if (x < 0 || y < 0 || x >= W || y >= H)
+                        fits = false;
+                }
+            const unowned = [...prev.canvas.owners].some((o, p) => o < 0 && requireValue(prev).canvas.rgba[p * 4 + 3]);
+            if (fits && names.length && !unowned) {
+                layers.push({ move: [best.dx, best.dy], parts: names.map((o) => compiled.parts[o]) });
+                shifted = true;
+            }
+        }
+        // Pixels still differing after the shift, grouped by the part that now owns the neighbourhood.
+        const tmp = { ...doc, cels: { ...doc.cels, __probe: { base: celName(i - 1), layers } } };
+        const probe = compileSprite(tmp);
+        const after = requireValue(probe.cels.get("__probe")).canvas;
+        const partsList = probe.parts;
+        const groups = new Map();
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++) {
+                const p = y * W + x;
+                const t = f.rgba.subarray(p * 4, p * 4 + 4);
+                const s = after.rgba.subarray(p * 4, p * 4 + 4);
+                if (t[0] === s[0] && t[1] === s[1] && t[2] === s[2] && t[3] === s[3])
+                    continue;
+                let part = "";
+                if (t[3]) {
+                    part = "detail";
+                    const own = requireValue(after.owners[p]);
+                    if (own >= 0 && after.rgba[p * 4 + 3])
+                        part = requireValue(partsList[own]);
+                    else {
+                        for (const [dx, dy] of N4) {
+                            const nx = x + dx, ny = y + dy;
+                            if (nx < 0 || ny < 0 || nx >= W || ny >= H)
+                                continue;
+                            const o = requireValue(after.owners[ny * W + nx]);
+                            if (o >= 0 && after.rgba[(ny * W + nx) * 4 + 3]) {
+                                part = requireValue(partsList[o]);
+                                break;
+                            }
+                        }
+                    }
+                }
+                const c = t[3] ? hexAt(f.rgba, p) : "clear";
+                if (!groups.has(part))
+                    groups.set(part, []);
+                requireValue(groups.get(part)).push([x, y, c]);
+            }
+        for (const [part, pts] of [...groups.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+            const pr = patchRows(pts, key, skip);
+            layers.push({ ...(part ? { part } : {}), at: pr.at, pixels: pr.rows });
+        }
+        cels[celName(i)] = layers.length ? { base: celName(i - 1), layers } : { base: celName(i - 1) };
+        summary.frameChanges.push({
+            frame: i,
+            shift: shifted ? [best.dx, best.dy] : [0, 0],
+            changedPixels: [...groups.values()].reduce((s, g) => s + g.length, 0),
+            partsChanged: [...groups.keys()].filter(Boolean),
+        });
+        compiled = compileSprite(doc);
+        prev = requireValue(compiled.cels.get(celName(i)));
+    }
+    if (animation)
+        doc.animations = { [animation]: { cels: frames.map((_, i) => celName(i)), ms } };
+    // Symmetry of frame 0 about its best vertical axis (share of opaque pixels whose mirror matches).
+    let sym = { axis: null, share: 0 };
+    for (let twice = 0; twice <= 2 * W - 2; twice++) {
+        let match = 0, total = 0;
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++) {
+                const p = y * W + x;
+                if (!f0.rgba[p * 4 + 3])
+                    continue;
+                total++;
+                const mx = twice - x;
+                if (mx < 0 || mx >= W)
+                    continue;
+                const q = y * W + mx;
+                if (f0.rgba[q * 4 + 3] && hexAt(f0.rgba, q) === hexAt(f0.rgba, p))
+                    match++;
+            }
+        if (total && match / total > sym.share)
+            sym = { axis: twice / 2, share: match / total };
+    }
+    summary.symmetry = sym;
+    // Verify.
+    const check = compileSprite(doc);
+    let verified = check.ok;
+    frames.forEach((f, i) => {
+        const c = check.cels.get(celName(i));
+        if (!c || c.canvas.rgba.some((v, j) => v !== f.rgba[j]))
+            verified = false;
+    });
+    return { doc, summary, verified, diagnostics: check.diagnostics };
+}
+/** Markdown description of a decompiled sprite for a model to read. */
+export function describeSprite(summary, doc) {
+    const lines = [];
+    lines.push(`# ${doc.id ?? "sprite"}`, "");
+    lines.push(`Canvas ${summary.size[0]}×${summary.size[1]}, ${summary.frames} frame(s). Coordinates are [x, y] from the top-left; boxes are [x, y, w, h].`, "");
+    if (summary.outline) {
+        const o = requireValue(summary.outlineStats);
+        lines.push(`Outline colour \`line\` = ${summary.outline} (${o.pixels} px). ${o.operation ? `Drawn by one \`outline\` operation, then ${o.added} px added and ${o.removed} px removed by patches.` : "Not a plain outside outline; kept as literal pixels in part `line`."}`, "");
+    }
+    else
+        lines.push("No outline colour detected.", "");
+    lines.push("## Ramps (darkest step first)", "");
+    for (const r of summary.ramps)
+        lines.push(`- \`${r.name}\`: ${r.steps.map((s, i) => `${r.name}.${i} ${s.colour} (${s.pixels} px)`).join(", ")}`);
+    lines.push("", "## Parts (frame 0, largest first)", "");
+    lines.push("| part | box | px | shape | fill | shading | literal fixes |", "| --- | --- | ---: | --- | --- | --- | ---: |");
+    for (const p of summary.parts)
+        lines.push(`| \`${p.part}\` | ${JSON.stringify(p.bbox)} | ${p.pixels} | ${p.shape} | ${p.fill ?? "–"} | ${p.bevel ? `bevel ${p.bevel.dir}: light ${p.bevel.light ?? "–"}, shadow ${p.bevel.shadow ?? "–"}` : "flat"} | ${p.residualPixels} |`);
+    lines.push("");
+    const s = summary.symmetry ?? { axis: null, share: 0 };
+    if (s.axis !== null)
+        lines.push(`Mirror symmetry: ${(s.share * 100).toFixed(0)}% of opaque pixels match their mirror about x = ${s.axis}.`, "");
+    if (summary.frameChanges.length) {
+        lines.push("## Frames", "");
+        for (const f of summary.frameChanges)
+            lines.push(`- frame ${f.frame}: shift ${JSON.stringify(f.shift)}, ${f.changedPixels} px changed${f.partsChanged.length ? ` (${f.partsChanged.join(", ")})` : ""}`);
+        lines.push("");
+    }
+    lines.push("Part names are generic (ramp name and size order). Rename them to what they depict before editing.");
+    return `${lines.join("\n")}\n`;
+}