@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/sprite-compiler.js

@@ -0,0 +1,1745 @@
+import { requireValue } from "./required.js";
+// Host-independent compiler for the pixel-sprite/0.1 notation.
+//
+// A document declares a palette, optional parts and stamps, cels and
+// animations. A cel is a canvas built by ordered layers in whole-pixel
+// coordinates. Literal `pixels` rows can state any indexed image exactly; the
+// other operations are shorthands that compile to the same pixels. A cel can
+// start from another cel or from a 3D render supplied by the caller through
+// `options.renderBase`, so this module performs no IO and stays
+// host-independent. Every pixel records the part that owns it.
+export const SPRITE_FORMAT = "pixel-sprite/0.1";
+export const SPRITE_LIMITS = Object.freeze({
+    dimension: 1024,
+    cels: 4096,
+    layers: 512,
+    expandedOperations: 8192,
+    pixels: 16777216,
+    sceneDimension: 2048,
+    stamps: 256,
+    colors: 4096,
+    specks: 4096,
+});
+/** Reserved colour reference: paint transparent. */
+export const CLEAR = "clear";
+/** Predefined key in `pixels` rows and stamps: leave the pixel unchanged. */
+export const SKIP_KEY = ".";
+const NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const HEX = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/;
+const CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right", "center"];
+const DIRS = { "upper-left": [-1, -1], "upper-right": [1, -1], "lower-left": [-1, 1], "lower-right": [1, 1] };
+const DOC_FIELDS = [
+    "format",
+    "id",
+    "asset",
+    "palette",
+    "parts",
+    "stamps",
+    "recipes",
+    "views",
+    "cels",
+    "animations",
+    "notes",
+];
+const CEL_FIELDS = ["size", "pivot", "base", "flip", "view", "exempt", "layers", "notes"];
+/** Guide parts smaller than this many pixels are not required in a view. */
+export const GUIDE_MIN_AREA = 3;
+/** Bounding-box overlap below which an authored part is reported as drifting from its guide. */
+export const GUIDE_MIN_IOU = 0.35;
+const LAYER_FIELDS = {
+    pixels: ["at", "part", "onPart"],
+    rect: ["fill", "round", "part"],
+    ellipse: ["fill", "part"],
+    line: ["color", "part"],
+    stamp: ["at", "flip", "part", "onPart"],
+    outline: ["parts", "side", "corners", "against"],
+    bevel: ["parts", "width", "dir", "through", "keep"],
+    speck: ["parts", "count", "seed", "inset"],
+    mirror: ["parts"],
+    recolor: ["parts"],
+    repaint: ["parts", "keep"],
+    move: ["parts"],
+    silhouette: ["fill", "part"],
+    shade: ["parts", "guides"],
+    recipe: [],
+    use: ["at", "flip", "part"],
+};
+const OPS = Object.keys(LAYER_FIELDS);
+// ---------- diagnostics ----------
+/** Escapes a document key for use as a JSON Pointer segment. */
+export const ptr = (key) => String(key).replace(/~/g, "~0").replace(/\//g, "~1");
+function diag(list, severity, code, path, message, extra = {}) {
+    list.push({ severity, code, path, message, ...extra });
+}
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isInt = (v) => Number.isInteger(v);
+const isPoint = (v) => Array.isArray(v) && v.length === 2 && v.every(Number.isSafeInteger);
+// ---------- colour ----------
+export function parseHex(hex) {
+    if (typeof hex !== "string")
+        return null;
+    const m = HEX.exec(hex);
+    if (!m)
+        return null;
+    const n = parseInt(requireValue(m[1]), 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255, m[2] ? parseInt(m[2], 16) : 255];
+}
+export function toHex([r, g, b, a]) {
+    const h = (v) => v.toString(16).padStart(2, "0");
+    return `#${h(r)}${h(g)}${h(b)}${a === 255 ? "" : h(a)}`;
+}
+const srgbToLinear = (c) => {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+export function rgbToOklab([r, g, b]) {
+    const lr = srgbToLinear(r), lg = srgbToLinear(g), lb = srgbToLinear(b);
+    const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    return [
+        0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    ];
+}
+/** Resolves palette declarations into a reference resolver. */
+function buildPalette(palette, d) {
+    const colors = new Map();
+    const ramps = new Map();
+    const keys = new Map([[SKIP_KEY, null]]);
+    let keyWidth = 1;
+    const empty = {
+        resolve: (_ref) => null,
+        keys,
+        keyWidth,
+        all: [],
+        locked: false,
+        ramps,
+        colors,
+    };
+    if (palette === undefined)
+        palette = {};
+    if (!isObj(palette)) {
+        diag(d, "error", "SPRITE_PALETTE", "/palette", "palette must be an object");
+        return empty;
+    }
+    for (const k of Object.keys(palette))
+        if (!["colors", "ramps", "keys", "keyWidth", "lock"].includes(k))
+            diag(d, "error", "SPRITE_UNKNOWN_FIELD", `/palette/${ptr(k)}`, `unknown palette field ${k}`);
+    if (palette.keyWidth !== undefined) {
+        if (![1, 2, 3].includes(palette.keyWidth))
+            diag(d, "error", "SPRITE_KEY_WIDTH", "/palette/keyWidth", "keyWidth must be 1, 2 or 3");
+        else
+            keyWidth = palette.keyWidth;
+    }
+    for (const key of ["colors", "ramps", "keys"])
+        if (palette[key] !== undefined && !isObj(palette[key]))
+            diag(d, "error", "SPRITE_PALETTE", `/palette/${key}`, `${key} must be an object`);
+    for (const [name, hex] of Object.entries(isObj(palette.colors) ? palette.colors : {})) {
+        const c = typeof hex === "string" ? parseHex(hex) : null;
+        if (!NAME.test(name) || name === CLEAR)
+            diag(d, "error", "SPRITE_NAME", `/palette/colors/${ptr(name)}`, `invalid colour name ${name}`);
+        else if (!c)
+            diag(d, "error", "SPRITE_COLOR", `/palette/colors/${ptr(name)}`, "expected #rrggbb or #rrggbbaa", {
+                received: hex,
+            });
+        else
+            colors.set(name, c);
+    }
+    for (const [name, steps] of Object.entries(isObj(palette.ramps) ? palette.ramps : {})) {
+        if (!NAME.test(name) || colors.has(name) || name === CLEAR) {
+            diag(d, "error", "SPRITE_NAME", `/palette/ramps/${ptr(name)}`, `invalid or duplicate ramp name ${name}`);
+            continue;
+        }
+        if (!Array.isArray(steps) || !steps.length) {
+            diag(d, "error", "SPRITE_RAMP", `/palette/ramps/${ptr(name)}`, "a ramp is a non-empty array of colours");
+            continue;
+        }
+        const parsed = steps.map((hex, i) => {
+            const c = typeof hex === "string" ? parseHex(hex) : null;
+            if (!c)
+                diag(d, "error", "SPRITE_COLOR", `/palette/ramps/${ptr(name)}/${i}`, "expected #rrggbb or #rrggbbaa", {
+                    received: hex,
+                });
+            return c;
+        });
+        ramps.set(name, parsed);
+    }
+    const locked = palette.lock === true;
+    if (palette.lock !== undefined && typeof palette.lock !== "boolean")
+        diag(d, "error", "SPRITE_PALETTE", "/palette/lock", "lock must be true or false");
+    const resolve = (ref) => {
+        if (ref === null)
+            return null;
+        if (ref === CLEAR)
+            return CLEAR;
+        if (typeof ref !== "string")
+            return null;
+        if (ref.startsWith("#"))
+            return locked ? null : (parseHex(ref) ?? null);
+        if (colors.has(ref))
+            return colors.get(ref) ?? null;
+        const dot = ref.lastIndexOf(".");
+        if (dot > 0) {
+            const ramp = ramps.get(ref.slice(0, dot));
+            const i = Number(ref.slice(dot + 1));
+            if (ref.slice(dot + 1).length > 0 && ramp && isInt(i) && i >= 0 && i < ramp.length)
+                return ramp[i] ?? null;
+        }
+        return null;
+    };
+    for (const [key, ref] of Object.entries(isObj(palette.keys) ? palette.keys : {})) {
+        if (key.length !== keyWidth || key === SKIP_KEY.repeat(keyWidth) || /["\\\s]/.test(key)) {
+            diag(d, "error", "SPRITE_KEY", `/palette/keys/${ptr(key)}`, `keys must be ${keyWidth} printable characters`);
+            continue;
+        }
+        const c = resolve(ref);
+        if (c === null)
+            diag(d, "error", locked && typeof ref === "string" && ref.startsWith("#")
+                ? "SPRITE_PALETTE_LOCKED"
+                : "SPRITE_COLOR_REF", `/palette/keys/${ptr(key)}`, locked && typeof ref === "string" && ref.startsWith("#")
+                ? "the palette is locked: refer to a named colour or ramp step"
+                : `unknown colour reference ${JSON.stringify(ref)}`);
+        else
+            keys.set(key, c);
+    }
+    if (keyWidth > 1)
+        keys.set(SKIP_KEY.repeat(keyWidth), null);
+    const all = [...colors.values(), ...[...ramps.values()].flat()].filter((c) => c !== null);
+    const colourCount = new Set([...all, ...keys.values()].filter(Array.isArray).map((c) => toHex(c))).size;
+    if (colourCount > SPRITE_LIMITS.colors)
+        diag(d, "error", "SPRITE_BUDGET", "/palette", `more than ${SPRITE_LIMITS.colors} colours`);
+    return { resolve, keys, keyWidth, all, locked, ramps, colors };
+}
+// ---------- canvas ----------
+export class SpriteCanvas {
+    width;
+    height;
+    rgba;
+    owners;
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+        this.rgba = new Uint8Array(width * height * 4);
+        this.owners = new Int32Array(width * height).fill(-1);
+    }
+    clone() {
+        const c = new SpriteCanvas(this.width, this.height);
+        c.rgba.set(this.rgba);
+        c.owners.set(this.owners);
+        return c;
+    }
+    inside(x, y) {
+        return x >= 0 && y >= 0 && x < this.width && y < this.height;
+    }
+    opaque(x, y) {
+        return this.inside(x, y) && (this.rgba[(y * this.width + x) * 4 + 3] ?? 0) > 0;
+    }
+    owner(x, y) {
+        return this.inside(x, y) ? (this.owners[y * this.width + x] ?? -1) : -1;
+    }
+    color(x, y) {
+        const i = (y * this.width + x) * 4;
+        return [this.rgba[i] ?? 0, this.rgba[i + 1] ?? 0, this.rgba[i + 2] ?? 0, this.rgba[i + 3] ?? 0];
+    }
+    /** Paints one pixel; CLEAR erases it. Returns false when outside the canvas. */
+    set(x, y, c, owner) {
+        if (!this.inside(x, y))
+            return false;
+        const p = y * this.width + x;
+        if (c === CLEAR) {
+            this.rgba.fill(0, p * 4, p * 4 + 4);
+            this.owners[p] = -1;
+            return true;
+        }
+        this.rgba.set(c, p * 4);
+        if (c[3] === 0) {
+            this.rgba.fill(0, p * 4, p * 4 + 4);
+            this.owners[p] = -1;
+        }
+        else if (owner != null)
+            this.owners[p] = owner;
+        return true;
+    }
+    flip(axis) {
+        const out = new SpriteCanvas(this.width, this.height);
+        for (let y = 0; y < this.height; y++)
+            for (let x = 0; x < this.width; x++) {
+                const sx = axis.includes("x") ? this.width - 1 - x : x;
+                const sy = axis.includes("y") ? this.height - 1 - y : y;
+                const s = sy * this.width + sx, t = y * this.width + x;
+                out.rgba.set(this.rgba.subarray(s * 4, s * 4 + 4), t * 4);
+                out.owners[t] = this.owners[s] ?? -1;
+            }
+        return out;
+    }
+}
+/** Deterministic 32-bit PRNG (mulberry32). */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Integer points of a Bresenham segment, inclusive. */
+export function bresenham([x0, y0], [x1, y1]) {
+    if (![x0, y0, x1, y1].every(Number.isSafeInteger))
+        return [];
+    const pts = [];
+    const dx = Math.abs(x1 - x0), sx = x0 < x1 ? 1 : -1, dy = -Math.abs(y1 - y0), sy = y0 < y1 ? 1 : -1;
+    let err = dx + dy, x = x0, y = y0;
+    for (;;) {
+        pts.push([x, y]);
+        if (x === x1 && y === y1)
+            break;
+        const e2 = 2 * err;
+        if (e2 >= dy) {
+            err += dy;
+            x += sx;
+        }
+        if (e2 <= dx) {
+            err += dx;
+            y += sy;
+        }
+    }
+    return pts;
+}
+// Clip in the major-axis step domain, preserving Bresenham's original phase.
+// BigInt keeps the rounding exact even when safe endpoints span an unsafe delta.
+function clippedLine(a, b, width, height) {
+    const ax = BigInt(a[0]), ay = BigInt(a[1]);
+    const bx = BigInt(b[0]), by = BigInt(b[1]);
+    const abs = (n) => (n < 0n ? -n : n);
+    const dx = abs(bx - ax), dy = abs(by - ay);
+    const sx = ax < bx ? 1n : -1n, sy = ay < by ? 1n : -1n;
+    const horizontal = dx >= dy;
+    const major = horizontal ? dx : dy, minor = horizontal ? dy : dx;
+    const start = horizontal ? ax : ay, sign = horizontal ? sx : sy;
+    const end = BigInt((horizontal ? width : height) - 1);
+    const low = sign > 0n ? -start : start - end;
+    const high = sign > 0n ? end - start : start;
+    const first = low > 0n ? low : 0n, last = high < major ? high : major;
+    const points = [];
+    for (let k = first; k <= last; k++) {
+        const offset = major === 0n ? 0n : (k * minor + major / 2n) / major;
+        const x = Number(ax + sx * (horizontal ? k : offset));
+        const y = Number(ay + sy * (horizontal ? offset : k));
+        if (x >= 0 && x < width && y >= 0 && y < height)
+            points.push([x, y]);
+    }
+    return points;
+}
+// ---------- compiler ----------
+/**
+ * Compiles a pixel-sprite/0.1 document.
+ * `SPRITE_GUIDE_HIDDEN_REF` is an error for referencing an occluded guide part;
+ * `SPRITE_GUIDE_HIDDEN` warns about an authored drawing of such a part.
+ * Every user key in diagnostic paths is JSON Pointer escaped. Expanded recipes
+ * retain their calling path: /cels/<cel>/layers/<i>/recipe(<name>)/<j>.
+ * Resolver failures always emit an error, even if they also carry warnings.
+ */
+export function compileSprite(doc, options = {}) {
+    const d = [];
+    /** Resolved part anchors, in order: { path, part, point }. */
+    const anchors = [];
+    /** Per cel with a view: how each authored part compares with its layout guide. */
+    const guideReport = [];
+    const guides = new Map();
+    const result = {
+        ok: false,
+        diagnostics: d,
+        parts: [],
+        cels: new Map(),
+        animations: new Map(),
+        anchors,
+        guides,
+        guideReport,
+    };
+    if (!isObj(doc)) {
+        diag(d, "error", "SPRITE_STRUCTURE", "", "document must be an object");
+        return result;
+    }
+    if (doc.format !== SPRITE_FORMAT)
+        diag(d, "error", "SPRITE_FORMAT", "/format", `expected ${SPRITE_FORMAT}`, { received: doc.format });
+    for (const k of Object.keys(doc))
+        if (!DOC_FIELDS.includes(k))
+            diag(d, "error", "SPRITE_UNKNOWN_FIELD", `/${ptr(k)}`, `unknown field ${k}`);
+    for (const key of ["id", "asset"])
+        if (doc[key] !== undefined && typeof doc[key] !== "string")
+            diag(d, "error", "SPRITE_STRUCTURE", `/${key}`, `${key} must be a string`);
+    const pal = buildPalette(doc.palette, d);
+    // Parts: declared names are enforced; render bases add their own part names.
+    const parts = [];
+    const partIndex = new Map();
+    const declared = doc.parts === undefined ? null : new Set();
+    const addPart = (name) => {
+        if (!partIndex.has(name)) {
+            partIndex.set(name, parts.length);
+            parts.push(name);
+        }
+        return requireValue(partIndex.get(name));
+    };
+    if (doc.parts !== undefined) {
+        const names = Array.isArray(doc.parts) ? doc.parts : isObj(doc.parts) ? Object.keys(doc.parts) : null;
+        if (!names)
+            diag(d, "error", "SPRITE_PARTS", "/parts", "parts must be an array or object of names");
+        for (const n of names ?? []) {
+            if (typeof n !== "string" || !NAME.test(n.replace(/\//g, "_")))
+                diag(d, "error", "SPRITE_NAME", "/parts", `invalid part name ${JSON.stringify(n)}`);
+            else {
+                declared?.add(n);
+                addPart(n);
+            }
+        }
+    }
+    // Part contracts: { ramps, colors } list the only colours a part may use.
+    const contracts = new Map();
+    if (isObj(doc.parts))
+        for (const [name, spec] of Object.entries(doc.parts)) {
+            if (!isObj(spec)) {
+                diag(d, "error", "SPRITE_PARTS", `/parts/${ptr(name)}`, "a part declaration is an object");
+                continue;
+            }
+            for (const k of Object.keys(spec))
+                if (!["ramps", "colors", "notes"].includes(k))
+                    diag(d, "error", "SPRITE_UNKNOWN_FIELD", `/parts/${ptr(name)}/${ptr(k)}`, `unknown part field ${k}`);
+            if (spec.ramps === undefined && spec.colors === undefined)
+                continue;
+            const allowed = new Set();
+            for (const key of ["ramps", "colors"]) {
+                if (spec[key] !== undefined && !Array.isArray(spec[key]))
+                    diag(d, "error", "SPRITE_PARTS", `/parts/${ptr(name)}/${key}`, `${key} must be an array`);
+            }
+            for (const [i, r] of (Array.isArray(spec.ramps) ? spec.ramps : []).entries()) {
+                const steps = pal.ramps.get(r);
+                if (!steps)
+                    diag(d, "error", "SPRITE_COLOR_REF", `/parts/${ptr(name)}/ramps/${i}`, `unknown ramp ${JSON.stringify(r)}`);
+                else
+                    for (const c of steps)
+                        if (c)
+                            allowed.add(toHex(c));
+            }
+            for (const [i, ref] of (Array.isArray(spec.colors) ? spec.colors : []).entries()) {
+                const c = pal.resolve(ref);
+                if (!Array.isArray(c))
+                    diag(d, "error", "SPRITE_COLOR_REF", `/parts/${ptr(name)}/colors/${i}`, `unknown colour ${JSON.stringify(ref)}`);
+                else
+                    allowed.add(toHex(c));
+            }
+            contracts.set(name, allowed);
+        }
+    const paletteHex = new Set(pal.all.map((c) => toHex(c)));
+    // Final-pixel checks: part contracts, and the palette lock.
+    const checkColours = (canvas, path) => {
+        const bad = new Map();
+        let off = 0;
+        for (let q = 0; q < canvas.owners.length; q++) {
+            if (!(canvas.rgba[q * 4 + 3] ?? 0))
+                continue;
+            const hex = toHex([
+                requireValue(canvas.rgba[q * 4]),
+                requireValue(canvas.rgba[q * 4 + 1]),
+                requireValue(canvas.rgba[q * 4 + 2]),
+                requireValue(canvas.rgba[q * 4 + 3]),
+            ]);
+            if (pal.locked && !paletteHex.has(hex))
+                off++;
+            const name = parts[canvas.owners[q] ?? -1];
+            const allowed = name === undefined ? null : contracts.get(name);
+            if (allowed && !allowed.has(hex))
+                bad.set(name, (bad.get(name) ?? 0) + 1);
+        }
+        for (const [name, n] of bad)
+            diag(d, "warning", "SPRITE_PART_COLOUR", path, `${n} pixel(s) of ${name} use colours outside its ramps`, {
+                part: name,
+                received: n,
+            });
+        if (off)
+            diag(d, "error", "SPRITE_OFF_PALETTE", path, `${off} pixel(s) use colours outside the locked palette`, {
+                received: off,
+            });
+    };
+    const partOf = (name, path) => {
+        if (name === undefined)
+            return null;
+        if (typeof name !== "string") {
+            diag(d, "error", "SPRITE_PART", path, "part must be a string");
+            return null;
+        }
+        if (declared && !declared.has(name) && !partIndex.has(name)) {
+            diag(d, "error", "SPRITE_UNKNOWN_PART", path, `unknown part ${name}`, { part: name });
+            return null;
+        }
+        return addPart(name);
+    };
+    const partList = (names, path) => {
+        if (names === undefined)
+            return null;
+        if (!Array.isArray(names) || !names.length) {
+            diag(d, "error", "SPRITE_PARTS", path, "parts must be a non-empty array");
+            return null;
+        }
+        return new Set(names.map((n, i) => partOf(n, `${path}/${i}`)).filter((i) => i !== null));
+    };
+    const color = (ref, path) => {
+        const c = pal.resolve(ref);
+        if (c === null && pal.locked && typeof ref === "string" && ref.startsWith("#"))
+            diag(d, "error", "SPRITE_PALETTE_LOCKED", path, "the palette is locked: refer to a named colour or ramp step");
+        else if (c === null)
+            diag(d, "error", "SPRITE_COLOR_REF", path, `unknown colour reference ${JSON.stringify(ref)}`);
+        return c ?? null;
+    };
+    // Rows of keys (pixels layers and stamps) become a sparse grid.
+    const parseRows = (rows, path) => {
+        if (!Array.isArray(rows) || !rows.length || rows.some((r) => typeof r !== "string")) {
+            diag(d, "error", "SPRITE_ROWS", path, "rows must be a non-empty array of strings");
+            return null;
+        }
+        const w = (rows[0] ?? "").length;
+        if (w === 0 || w % pal.keyWidth) {
+            diag(d, "error", "SPRITE_ROW_LENGTH", `${path}/0`, `row length must be a positive multiple of ${pal.keyWidth}`);
+            return null;
+        }
+        const cols = w / pal.keyWidth;
+        const grid = [];
+        let bad = false;
+        rows.forEach((row, y) => {
+            if (row.length !== w) {
+                diag(d, "error", "SPRITE_ROW_LENGTH", `${path}/${y}`, `row ${y} has ${row.length} characters, expected ${w}`, {
+                    received: row.length,
+                    expected: w,
+                });
+                bad = true;
+                return;
+            }
+            for (let x = 0; x < cols; x++) {
+                const key = row.slice(x * pal.keyWidth, (x + 1) * pal.keyWidth);
+                if (!pal.keys.has(key)) {
+                    diag(d, "error", "SPRITE_UNKNOWN_KEY", `${path}/${y}`, `unknown key ${JSON.stringify(key)} at column ${x}`, {
+                        received: key,
+                    });
+                    bad = true;
+                    continue;
+                }
+                const c = pal.keys.get(key);
+                if (c !== null)
+                    grid.push([x, y, c]);
+            }
+        });
+        return bad ? null : { cols, rows: rows.length, grid };
+    };
+    const stamps = new Map();
+    if (doc.stamps !== undefined) {
+        if (!isObj(doc.stamps) || Object.keys(doc.stamps).length > SPRITE_LIMITS.stamps)
+            diag(d, "error", "SPRITE_STAMPS", "/stamps", `stamps must be an object of at most ${SPRITE_LIMITS.stamps}`);
+        else
+            for (const [name, s] of Object.entries(doc.stamps)) {
+                if (!NAME.test(name) || !isObj(s) || Object.keys(s).some((k) => k !== "pixels")) {
+                    diag(d, "error", "SPRITE_STAMPS", `/stamps/${ptr(name)}`, "a stamp is { pixels: [rows] }");
+                    continue;
+                }
+                const g = parseRows(s.pixels, `/stamps/${ptr(name)}/pixels`);
+                if (g)
+                    stamps.set(name, g);
+            }
+    }
+    if (!isObj(doc.cels) || !Object.keys(doc.cels).length) {
+        diag(d, "error", "SPRITE_CELS", "/cels", "cels must be a non-empty object");
+        return result;
+    }
+    const celSpecs = doc.cels;
+    const celIds = Object.keys(celSpecs);
+    if (celIds.length > SPRITE_LIMITS.cels) {
+        diag(d, "error", "SPRITE_BUDGET", "/cels", `more than ${SPRITE_LIMITS.cels} cels`);
+        return result;
+    }
+    let allocatedPixels = 0;
+    const allocationLimit = Symbol("sprite pixel budget");
+    const reservePixels = (width, height, path) => {
+        if (allocatedPixels + width * height > SPRITE_LIMITS.pixels) {
+            diag(d, "error", "SPRITE_BUDGET", path, `more than ${SPRITE_LIMITS.pixels} allocated canvas pixels`);
+            throw allocationLimit;
+        }
+        allocatedPixels += width * height;
+    };
+    const allocate = (width, height, path) => {
+        reservePixels(width, height, path);
+        return new SpriteCanvas(width, height);
+    };
+    // Views: each names a projection of the linked 3D asset. The caller's
+    // `guide` resolver turns it into a layout guide (canvas size and, per part,
+    // a bounding box, visible area, depth rank and mask) shared by every cel
+    // drawn in that view.
+    // Diagnostics from a resolver (for example the /pixel renderer) become errors
+    // whose paths point into this document.
+    const foreign = (x, prefix) => ({
+        ...x,
+        severity: x.severity ?? "error",
+        path: x.path?.startsWith(prefix) ? x.path : `${prefix}${x.path ?? ""}`,
+    });
+    const views = isObj(doc.views) ? doc.views : {};
+    if (doc.views !== undefined && !isObj(doc.views))
+        diag(d, "error", "SPRITE_VIEWS", "/views", "views must be an object of view specifications");
+    const guideOf = (view, path) => {
+        if (guides.has(view))
+            return guides.get(view) ?? null;
+        if (!Object.hasOwn(views, view) || !isObj(views[view])) {
+            diag(d, "error", "SPRITE_UNKNOWN_VIEW", path, `unknown view ${view}`);
+            guides.set(view, null);
+            return null;
+        }
+        if (!options.guide) {
+            diag(d, "error", "SPRITE_GUIDE_UNAVAILABLE", path, "no guide resolver was supplied");
+            guides.set(view, null);
+            return null;
+        }
+        try {
+            const g = options.guide(views[view], `/views/${ptr(view)}`);
+            validateGuide(g);
+            guides.set(view, g);
+            return g;
+        }
+        catch (e) {
+            for (const x of resolverErrors(e, "SPRITE_GUIDE"))
+                d.push(foreign(x, `/views/${ptr(view)}`));
+            guides.set(view, null);
+            return null;
+        }
+    };
+    let currentGuide = null;
+    /**
+     * The guide part `name`, or null with a diagnostic. With `skipHidden`, a part
+     * the guide reports as hidden or cut in this view returns null silently: mask
+     * operations (`silhouette`, `shade`) have nothing to paint there, and one
+     * recipe can then list every part for every view.
+     */
+    const guidePart = (name, path, skipHidden = false) => {
+        if (!currentGuide) {
+            diag(d, "error", "SPRITE_GUIDE_UNAVAILABLE", path, "this cel has no view, so guide references are unavailable");
+            return null;
+        }
+        const g = Object.hasOwn(currentGuide.parts, name) ? currentGuide.parts[name] : null;
+        if (!g) {
+            const hidden = currentGuide.hidden?.includes(name);
+            if (hidden && skipHidden)
+                return null;
+            diag(d, "error", hidden ? "SPRITE_GUIDE_HIDDEN_REF" : "SPRITE_GUIDE_UNKNOWN_PART", path, hidden ? `part ${name} is hidden in this view` : `the guide has no part ${name}`, { part: name });
+            return null;
+        }
+        return g;
+    };
+    const recipes = isObj(doc.recipes) ? doc.recipes : {};
+    if (doc.recipes !== undefined && !isObj(doc.recipes))
+        diag(d, "error", "SPRITE_RECIPES", "/recipes", "recipes must be an object of layer lists");
+    for (const [name, list] of Object.entries(recipes))
+        if (!NAME.test(name) || !Array.isArray(list))
+            diag(d, "error", "SPRITE_RECIPES", `/recipes/${ptr(name)}`, "a recipe is a named array of layers");
+    const recipeStack = [];
+    let operations = 0;
+    const pending = new Set();
+    const failed = new Set();
+    const compileCel = (id) => {
+        if (result.cels.has(id))
+            return result.cels.get(id) ?? null;
+        const path = `/cels/${ptr(id)}`;
+        if (pending.has(id)) {
+            diag(d, "error", "SPRITE_BASE_CYCLE", path, `cel ${id} inherits from itself`);
+            return null;
+        }
+        if (failed.has(id))
+            return null;
+        const spec = celSpecs[id];
+        failed.add(id);
+        if (!isObj(spec)) {
+            diag(d, "error", "SPRITE_CEL", path, "a cel must be an object");
+            return null;
+        }
+        if (pending.size >= 256) {
+            diag(d, "error", "SPRITE_DEPTH", path, "cels nest more than 256 levels through use");
+            return null;
+        }
+        pending.add(id);
+        for (const k of Object.keys(spec))
+            if (!CEL_FIELDS.includes(k))
+                diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${path}/${ptr(k)}`, `unknown cel field ${k}`);
+        if (spec.exempt !== undefined &&
+            (!Array.isArray(spec.exempt) || spec.exempt.some((n) => typeof n !== "string")))
+            diag(d, "error", "SPRITE_EXEMPT", `${path}/exempt`, "exempt is a list of part names");
+        let canvas = null;
+        let pivot = null;
+        let view = null;
+        if (typeof spec.base === "string") {
+            if (!Object.hasOwn(celSpecs, spec.base))
+                diag(d, "error", "SPRITE_UNKNOWN_CEL", `${path}/base`, `unknown base cel ${spec.base}`);
+            else {
+                const base = compileCel(spec.base);
+                if (base) {
+                    canvas = allocate(base.canvas.width, base.canvas.height, path);
+                    canvas.rgba.set(base.canvas.rgba);
+                    canvas.owners.set(base.canvas.owners);
+                    pivot = base.pivot;
+                    view = base.view;
+                }
+            }
+        }
+        else if (isObj(spec.base) && isObj(spec.base.render)) {
+            for (const k of Object.keys(spec.base))
+                if (k !== "render")
+                    diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${path}/base/${ptr(k)}`, `unknown base field ${k}`);
+            if (!options.renderBase)
+                diag(d, "error", "SPRITE_RENDER_UNAVAILABLE", `${path}/base`, "no renderBase resolver was supplied");
+            else {
+                try {
+                    const r = options.renderBase(spec.base.render, `${path}/base/render`);
+                    validateRender(r);
+                    canvas = allocate(r.width, r.height, path);
+                    canvas.rgba.set(r.rgba);
+                    const map = r.names.map((n) => addPart(n));
+                    r.owners.forEach((o, i) => (requireValue(canvas).owners[i] = o >= 0 ? (map[o] ?? -1) : -1));
+                    if (spec.base.render.snap === true)
+                        snapToPalette(canvas, pal.all);
+                }
+                catch (e) {
+                    if (e === allocationLimit)
+                        throw e;
+                    for (const x of resolverErrors(e, "SPRITE_RENDER"))
+                        d.push(foreign(x, `${path}/base/render`));
+                }
+            }
+        }
+        else if (spec.base !== undefined)
+            diag(d, "error", "SPRITE_BASE", `${path}/base`, "base must be a cel id or { render: {...} }");
+        if (spec.size !== undefined) {
+            const ok = Array.isArray(spec.size) &&
+                spec.size.length === 2 &&
+                spec.size.every((v) => isInt(v) && v >= 1 && v <= SPRITE_LIMITS.dimension);
+            if (!ok)
+                diag(d, "error", "SPRITE_SIZE", `${path}/size`, `size must be [w, h] within 1..${SPRITE_LIMITS.dimension}`);
+            else if (canvas && (canvas.width !== spec.size[0] || canvas.height !== spec.size[1]))
+                diag(d, "error", "SPRITE_SIZE", `${path}/size`, "size differs from the base cel", {
+                    received: spec.size,
+                    expected: [canvas.width, canvas.height],
+                });
+            else if (!canvas)
+                canvas = allocate(spec.size[0], spec.size[1], path);
+        }
+        if (spec.view !== undefined) {
+            if (typeof spec.view !== "string")
+                diag(d, "error", "SPRITE_VIEW", `${path}/view`, "view must be a view name");
+            else
+                view = spec.view;
+        }
+        const guide = view === null ? null : guideOf(view, `${path}/view`);
+        if (guide) {
+            if (!canvas)
+                canvas = allocate(guide.width, guide.height, path);
+            else if (canvas.width !== guide.width || canvas.height !== guide.height)
+                diag(d, "error", "SPRITE_SIZE", path, `the cel size differs from the ${view} guide`, {
+                    received: [canvas.width, canvas.height],
+                    expected: [guide.width, guide.height],
+                });
+        }
+        if (!canvas) {
+            if (spec.base === undefined && spec.size === undefined && view === null)
+                diag(d, "error", "SPRITE_SIZE", path, "a cel needs a size, a base or a view");
+            pending.delete(id);
+            return null;
+        }
+        if (spec.flip !== undefined) {
+            if (!["x", "y", "xy"].includes(spec.flip))
+                diag(d, "error", "SPRITE_FLIP", `${path}/flip`, 'flip must be "x", "y" or "xy"');
+            else {
+                reservePixels(canvas.width, canvas.height, path);
+                canvas = canvas.flip(spec.flip);
+                if (spec.view === undefined)
+                    view = null;
+                if (pivot && spec.flip.includes("x"))
+                    pivot = [canvas.width - 1 - pivot[0], pivot[1]];
+                if (pivot && spec.flip.includes("y"))
+                    pivot = [pivot[0], canvas.height - 1 - pivot[1]];
+            }
+        }
+        if (spec.pivot !== undefined) {
+            if (!isPoint(spec.pivot))
+                diag(d, "error", "SPRITE_PIVOT", `${path}/pivot`, "pivot must be [x, y] integers");
+            else
+                pivot = spec.pivot;
+        }
+        pivot ??= [Math.floor(canvas.width / 2), canvas.height - 1];
+        const layers = spec.layers === undefined ? [] : spec.layers;
+        if (!Array.isArray(layers) || layers.length > SPRITE_LIMITS.layers)
+            diag(d, "error", "SPRITE_LAYERS", `${path}/layers`, `layers must be an array of at most ${SPRITE_LIMITS.layers}`);
+        else {
+            const previous = currentGuide;
+            currentGuide = view === null ? null : guideOf(view, `${path}/view`);
+            const previousOperations = operations;
+            operations = 0;
+            for (const [i, layer] of layers.entries()) {
+                applyLayer(canvas, layer, `${path}/layers/${i}`);
+                if (operations > SPRITE_LIMITS.expandedOperations)
+                    break;
+            }
+            operations = previousOperations;
+            if (currentGuide)
+                checkGuide(canvas, currentGuide, id, path, spec.exempt);
+            currentGuide = previous;
+        }
+        if (contracts.size || pal.locked)
+            checkColours(canvas, path);
+        pending.delete(id);
+        const cel = { id, canvas, pivot, view };
+        failed.delete(id);
+        result.cels.set(id, cel);
+        return cel;
+    };
+    // Resolves `at` as [x, y] or { part, corner, offset } against the current canvas.
+    const resolveAt = (canvas, at, path) => {
+        if (at === undefined)
+            return { point: [0, 0], anchor: null };
+        if (isPoint(at))
+            return { point: at, anchor: null };
+        if (isObj(at) && typeof at.guide === "string") {
+            const extra = Object.keys(at).filter((k) => !["guide", "corner", "offset"].includes(k));
+            if (extra.length)
+                diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${path}/${ptr(extra[0])}`, "unknown anchor field");
+            const corner = at.corner ?? "top-left";
+            const off = at.offset ?? [0, 0];
+            if (!CORNERS.includes(corner) || !isPoint(off)) {
+                diag(d, "error", "SPRITE_ANCHOR", path, `corner is one of ${CORNERS.join(", ")}; offset is [dx, dy]`);
+                return null;
+            }
+            const g = guidePart(at.guide, `${path}/guide`);
+            if (!g)
+                return null;
+            const [x, y, w, h] = g.bbox;
+            const corners = {
+                "top-left": [x, y],
+                "top-right": [x + w - 1, y],
+                "bottom-left": [x, y + h - 1],
+                "bottom-right": [x + w - 1, y + h - 1],
+                center: [x + Math.floor((w - 1) / 2), y + Math.floor((h - 1) / 2)],
+            };
+            const base = requireValue(corners[corner]);
+            const point = [base[0] + off[0], base[1] + off[1]];
+            anchors.push({ path, guide: at.guide, point });
+            return { point, anchor: partIndex.get(at.guide) };
+        }
+        if (isObj(at) && typeof at.part === "string") {
+            const extra = Object.keys(at).filter((k) => !["part", "corner", "offset"].includes(k));
+            if (extra.length)
+                diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${path}/${ptr(extra[0])}`, "unknown anchor field");
+            const corner = at.corner ?? "top-left";
+            if (!CORNERS.includes(corner)) {
+                diag(d, "error", "SPRITE_ANCHOR", `${path}/corner`, `corner must be one of ${CORNERS.join(", ")}`);
+                return null;
+            }
+            const off = at.offset ?? [0, 0];
+            if (!isPoint(off)) {
+                diag(d, "error", "SPRITE_ANCHOR", `${path}/offset`, "offset must be [dx, dy] integers");
+                return null;
+            }
+            const p = partOf(at.part, `${path}/part`);
+            if (p === null)
+                return null;
+            let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+            for (let y = 0; y < canvas.height; y++)
+                for (let x = 0; x < canvas.width; x++)
+                    if (canvas.owner(x, y) === p && canvas.opaque(x, y)) {
+                        x0 = Math.min(x0, x);
+                        y0 = Math.min(y0, y);
+                        x1 = Math.max(x1, x);
+                        y1 = Math.max(y1, y);
+                    }
+            if (x0 === Infinity) {
+                diag(d, "error", "SPRITE_ANCHOR_MISSING", `${path}/part`, `part ${at.part} has no pixels to anchor to`, {
+                    part: at.part,
+                });
+                return null;
+            }
+            const corners = {
+                "top-left": [x0, y0],
+                "top-right": [x1, y0],
+                "bottom-left": [x0, y1],
+                "bottom-right": [x1, y1],
+                center: [Math.floor((x0 + x1) / 2), Math.floor((y0 + y1) / 2)],
+            };
+            const base = requireValue(corners[corner]);
+            const point = [base[0] + off[0], base[1] + off[1]];
+            anchors.push({ path, part: at.part, point });
+            return { point, anchor: p };
+        }
+        diag(d, "error", "SPRITE_AT", path, "at must be [x, y] or { part, corner, offset }");
+        return null;
+    };
+    // Paints a list of [x, y, colour], reporting out-of-bounds and off-part pixels.
+    const paint = (canvas, pts, owner, path, onPart) => {
+        let outside = 0, offPart = 0;
+        for (const [x, y, c] of pts) {
+            if (onPart != null && !(canvas.owner(x, y) === onPart && canvas.opaque(x, y)))
+                offPart++;
+            if (!canvas.set(x, y, c, owner))
+                outside++;
+        }
+        if (outside)
+            diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `${outside} pixel(s) fall outside the ${canvas.width}x${canvas.height} canvas`, {
+                received: outside,
+            });
+        if (offPart)
+            diag(d, "warning", "SPRITE_PATCH_OFF_PART", path, `${offPart} pixel(s) land outside the anchor part`, {
+                received: offPart,
+            });
+    };
+    // Colours listed in `keep` are protected: never painted, and outside the region.
+    const keepColours = (refs, path) => {
+        if (refs === undefined)
+            return () => false;
+        if (!Array.isArray(refs) || !refs.length) {
+            diag(d, "error", "SPRITE_KEEP", path, "keep must be a non-empty array of colours");
+            return () => false;
+        }
+        const cs = refs
+            .map((r, i) => color(r, `${path}/${i}`))
+            .filter((c) => Array.isArray(c));
+        return (canvas, x, y) => {
+            const c = canvas.color(x, y);
+            return cs.some((k) => k.every((v, i) => v === c[i]));
+        };
+    };
+    const regionSets = (canvas, set) => {
+        // Pixel indices by owner, restricted to `set` when given.
+        const by = new Map();
+        for (let p = 0; p < canvas.owners.length; p++) {
+            if ((canvas.rgba[p * 4 + 3] ?? 0) === 0)
+                continue;
+            const o = canvas.owners[p] ?? -1;
+            if (set && !set.has(o))
+                continue;
+            if (!by.has(o))
+                by.set(o, []);
+            by.get(o).push(p);
+        }
+        return by;
+    };
+    // Compares each authored part with the view's layout guide. Exaggeration is
+    // allowed; only parts that drift far from their projected box, guide parts
+    // left out, and parts drawn although hidden in this view are reported.
+    function checkGuide(canvas, guide, celId, path, exempt) {
+        const skip = new Set(Array.isArray(exempt) ? exempt : []);
+        const boxes = new Map();
+        for (let p = 0; p < canvas.owners.length; p++) {
+            if (!(canvas.rgba[p * 4 + 3] ?? 0))
+                continue;
+            const name = parts[canvas.owners[p] ?? -1];
+            if (name === undefined)
+                continue;
+            const x = p % canvas.width, y = Math.floor(p / canvas.width);
+            const b = boxes.get(name) ?? { x0: x, y0: y, x1: x, y1: y, area: 0 };
+            b.x0 = Math.min(b.x0, x);
+            b.y0 = Math.min(b.y0, y);
+            b.x1 = Math.max(b.x1, x);
+            b.y1 = Math.max(b.y1, y);
+            b.area++;
+            boxes.set(name, b);
+        }
+        const iou = (a, [gx, gy, gw, gh]) => {
+            const ix = Math.max(0, Math.min(a.x1 + 1, gx + gw) - Math.max(a.x0, gx));
+            const iy = Math.max(0, Math.min(a.y1 + 1, gy + gh) - Math.max(a.y0, gy));
+            const inter = ix * iy;
+            return inter / ((a.x1 - a.x0 + 1) * (a.y1 - a.y0 + 1) + gw * gh - inter);
+        };
+        const rows = [];
+        for (const [name, b] of boxes) {
+            if (skip.has(name))
+                continue;
+            const g = Object.hasOwn(guide.parts, name) ? guide.parts[name] : null;
+            const authored = [b.x0, b.y0, b.x1 - b.x0 + 1, b.y1 - b.y0 + 1];
+            if (!g) {
+                if (guide.hidden?.includes(name))
+                    diag(d, "warning", "SPRITE_GUIDE_HIDDEN", path, `part ${name} is drawn but hidden in this view`, {
+                        part: name,
+                    });
+                continue;
+            }
+            // An outside outline adds one pixel around a part (and is owned by it), so the
+            // guide box grown by one pixel counts too; otherwise thin parts always "drift".
+            const [gx, gy, gw, gh] = g.bbox;
+            const overlap = Math.max(iou(b, g.bbox), iou(b, [gx - 1, gy - 1, gw + 2, gh + 2]));
+            rows.push({
+                cel: celId,
+                part: name,
+                guide: g.bbox,
+                authored,
+                overlap,
+                guideArea: g.area,
+                area: b.area,
+            });
+            if (g.area >= GUIDE_MIN_AREA && overlap < GUIDE_MIN_IOU)
+                diag(d, "warning", "SPRITE_GUIDE_DRIFT", path, `part ${name} drifts from its guide box`, {
+                    part: name,
+                    received: authored,
+                    expected: g.bbox,
+                });
+        }
+        for (const [name, g] of Object.entries(guide.parts)) {
+            if (g.instance || g.area < GUIDE_MIN_AREA || skip.has(name))
+                continue;
+            const drawn = [...boxes.keys()].some((n) => n === name || n.startsWith(`${name}/`));
+            if (!drawn) {
+                rows.push({
+                    cel: celId,
+                    part: name,
+                    guide: g.bbox,
+                    authored: null,
+                    overlap: 0,
+                    guideArea: g.area,
+                    area: 0,
+                });
+                diag(d, "warning", "SPRITE_GUIDE_MISSING", path, `guide part ${name} (${g.area} px) is not drawn`, {
+                    part: name,
+                });
+            }
+        }
+        guideReport.push(...rows);
+    }
+    function applyLayer(canvas, layer, path) {
+        if (++operations > SPRITE_LIMITS.expandedOperations) {
+            if (operations === SPRITE_LIMITS.expandedOperations + 1)
+                diag(d, "error", "SPRITE_BUDGET", path, `more than ${SPRITE_LIMITS.expandedOperations} expanded operations per cel`);
+            return;
+        }
+        if (!isObj(layer)) {
+            diag(d, "error", "SPRITE_LAYER", path, "a layer must be an object");
+            return;
+        }
+        const ops = OPS.filter((k) => k in layer);
+        if (ops.length !== 1) {
+            diag(d, "error", "SPRITE_LAYER_OP", path, `a layer needs exactly one of ${OPS.join(", ")}`, {
+                received: ops,
+            });
+            return;
+        }
+        const op = requireValue(ops[0]);
+        for (const k of Object.keys(layer))
+            if (k !== op && !requireValue(LAYER_FIELDS[op]).includes(k))
+                diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${path}/${ptr(k)}`, `unknown field ${k} for ${op}`);
+        if (layer.onPart !== undefined && typeof layer.onPart !== "boolean" && typeof layer.onPart !== "string")
+            diag(d, "error", "SPRITE_LAYER", `${path}/onPart`, "onPart must be a boolean or part name");
+        if (layer.corners !== undefined && typeof layer.corners !== "boolean")
+            diag(d, "error", "SPRITE_OUTLINE", `${path}/corners`, "corners must be boolean");
+        const owner = partOf(layer.part, `${path}/part`);
+        const W = canvas.width, H = canvas.height;
+        switch (op) {
+            case "pixels":
+            case "stamp": {
+                if (op === "stamp" && typeof layer.stamp !== "string") {
+                    diag(d, "error", "SPRITE_UNKNOWN_STAMP", `${path}/stamp`, "stamp must be a string");
+                    return;
+                }
+                const g = op === "pixels"
+                    ? parseRows(layer.pixels, `${path}/pixels`)
+                    : (stamps.get(layer.stamp) ??
+                        (diag(d, "error", "SPRITE_UNKNOWN_STAMP", `${path}/stamp`, `unknown stamp ${layer.stamp}`),
+                            null));
+                if (!g)
+                    return;
+                const flip = layer.flip === undefined ? "" : layer.flip;
+                if (!["", "x", "y", "xy"].includes(flip)) {
+                    diag(d, "error", "SPRITE_FLIP", `${path}/flip`, 'flip must be "x", "y" or "xy"');
+                    return;
+                }
+                if (Array.isArray(layer.at) && layer.at.length === 0) {
+                    diag(d, "error", "SPRITE_AT", `${path}/at`, "at must be a point or a non-empty list of points");
+                    return;
+                }
+                const ats = op === "stamp" && Array.isArray(layer.at) && layer.at.every(isPoint) ? layer.at : [layer.at];
+                const namedOnPart = typeof layer.onPart === "string" ? partOf(layer.onPart, `${path}/onPart`) : null;
+                for (const at of ats) {
+                    const r = resolveAt(canvas, at, `${path}/at`);
+                    if (!r)
+                        continue;
+                    // onPart: true checks the anchor part (or the layer's part); a name checks that part.
+                    const onPart = layer.onPart === true
+                        ? (r.anchor ?? owner)
+                        : typeof layer.onPart === "string"
+                            ? namedOnPart
+                            : null;
+                    const pts = g.grid.map(([x, y, c]) => [
+                        r.point[0] + (flip.includes("x") ? g.cols - 1 - x : x),
+                        r.point[1] + (flip.includes("y") ? g.rows - 1 - y : y),
+                        c,
+                    ]);
+                    paint(canvas, pts, owner, path, onPart);
+                }
+                return;
+            }
+            case "rect":
+            case "ellipse": {
+                let b = layer[op];
+                if (isObj(b) && typeof b.guide === "string") {
+                    const grow = b.grow === undefined ? 0 : b.grow;
+                    const extra = Object.keys(b).filter((k) => !["guide", "grow"].includes(k));
+                    if (extra.length || !Number.isSafeInteger(grow)) {
+                        diag(d, "error", "SPRITE_SHAPE", `${path}/${op}`, "guide bounds are { guide, grow? } with integer grow");
+                        return;
+                    }
+                    const g = guidePart(b.guide, `${path}/${op}/guide`);
+                    if (!g)
+                        return;
+                    const [gx, gy, gw, gh] = g.bbox;
+                    b = [gx - grow, gy - grow, gw + 2 * grow, gh + 2 * grow];
+                }
+                if (!(Array.isArray(b) && b.length === 4 && b.every(Number.isSafeInteger) && b[2] > 0 && b[3] > 0)) {
+                    diag(d, "error", "SPRITE_SHAPE", `${path}/${op}`, `${op} must be [x, y, w, h] with positive size`);
+                    return;
+                }
+                const c = color(layer.fill, `${path}/fill`);
+                if (c === null)
+                    return;
+                const [x, y, w, h] = b;
+                const pts = [];
+                const round = layer.round === undefined ? 0 : layer.round;
+                if (op === "rect" && ![0, 1].includes(round)) {
+                    diag(d, "error", "SPRITE_SHAPE", `${path}/round`, "round is 0 or 1");
+                    return;
+                }
+                for (let j = Math.max(0, -y); j < Math.min(h, H - y); j++)
+                    for (let i = Math.max(0, -x); i < Math.min(w, W - x); i++) {
+                        if (op === "rect" && round === 1 && (i === 0 || i === w - 1) && (j === 0 || j === h - 1))
+                            continue;
+                        if (op === "ellipse") {
+                            const u = (i + 0.5 - w / 2) / (w / 2), v = (j + 0.5 - h / 2) / (h / 2);
+                            if (u * u + v * v > 1)
+                                continue;
+                        }
+                        pts.push([x + i, y + j, c]);
+                    }
+                paint(canvas, pts, owner, path);
+                if (op === "rect") {
+                    const corners = round === 1 ? Math.min(2, w) * Math.min(2, h) : 0;
+                    const count = w * h - corners - pts.length;
+                    if (count > 0)
+                        diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `${count} pixel(s) fall outside the ${W}x${H} canvas`, { received: count });
+                }
+                else {
+                    // The widest row and tallest column bound the actual ellipse pixels.
+                    const extent = (span, cross) => {
+                        const v = cross % 2 === 0 ? 1 / cross : 0;
+                        return Math.ceil((span / 2) * (1 - Math.sqrt(1 - v * v)) - 0.5);
+                    };
+                    const ix = extent(w, h), iy = extent(h, w);
+                    const outside = x + ix < 0 || x + w - 1 - ix >= W || y + iy < 0 || y + h - 1 - iy >= H;
+                    if (outside)
+                        diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `ellipse pixels fall outside the ${W}x${H} canvas`);
+                }
+                return;
+            }
+            case "line": {
+                const ptsIn = layer.line;
+                if (!Array.isArray(ptsIn) || ptsIn.length < 2 || !ptsIn.every(isPoint)) {
+                    diag(d, "error", "SPRITE_SHAPE", `${path}/line`, "line must be at least two [x, y] points");
+                    return;
+                }
+                const c = color(layer.color, `${path}/color`);
+                if (c === null)
+                    return;
+                const seen = new Set();
+                const pts = [];
+                for (let i = 1; i < ptsIn.length; i++)
+                    for (const [x, y] of clippedLine(requireValue(ptsIn[i - 1]), requireValue(ptsIn[i]), W, H)) {
+                        const k = `${x},${y}`;
+                        if (!seen.has(k)) {
+                            seen.add(k);
+                            pts.push([x, y, c]);
+                        }
+                    }
+                paint(canvas, pts, owner, path);
+                if (ptsIn.some(([x, y]) => !canvas.inside(x, y)))
+                    diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `line pixels fall outside the ${W}x${H} canvas`);
+                return;
+            }
+            case "outline": {
+                const c = color(layer.outline, `${path}/outline`);
+                if (c === null)
+                    return;
+                const set = partList(layer.parts, `${path}/parts`);
+                const side = layer.side === undefined ? "outside" : layer.side;
+                const against = layer.against === undefined ? "empty" : layer.against;
+                if (!["outside", "inside"].includes(side)) {
+                    diag(d, "error", "SPRITE_OUTLINE", `${path}/side`, "side is outside or inside");
+                    return;
+                }
+                if (!["empty", "any"].includes(against)) {
+                    diag(d, "error", "SPRITE_OUTLINE", `${path}/against`, "against is empty or any");
+                    return;
+                }
+                const nb = layer.corners === true
+                    ? [
+                        [-1, 0],
+                        [1, 0],
+                        [0, -1],
+                        [0, 1],
+                        [-1, -1],
+                        [1, -1],
+                        [-1, 1],
+                        [1, 1],
+                    ]
+                    : [
+                        [-1, 0],
+                        [1, 0],
+                        [0, -1],
+                        [0, 1],
+                    ];
+                const inT = (x, y) => canvas.opaque(x, y) && (!set || set.has(canvas.owner(x, y)));
+                const pts = [];
+                for (let y = 0; y < H; y++)
+                    for (let x = 0; x < W; x++) {
+                        if (side === "outside") {
+                            if (inT(x, y))
+                                continue;
+                            if (against === "empty" && canvas.opaque(x, y))
+                                continue;
+                            const n = nb.find(([dx, dy]) => inT(x + dx, y + dy));
+                            if (n)
+                                pts.push([x, y, canvas.owner(x + n[0], y + n[1])]);
+                        }
+                        else {
+                            if (!inT(x, y))
+                                continue;
+                            const edge = nb.some(([dx, dy]) => against === "empty"
+                                ? !canvas.opaque(x + dx, y + dy)
+                                : !canvas.opaque(x + dx, y + dy) || canvas.owner(x + dx, y + dy) !== canvas.owner(x, y));
+                            if (edge)
+                                pts.push([x, y, canvas.owner(x, y)]);
+                        }
+                    }
+                for (const [x, y, o] of pts)
+                    canvas.set(x, y, c, o);
+                return;
+            }
+            case "bevel": {
+                const b = layer.bevel;
+                if (!isObj(b) ||
+                    Object.keys(b).some((k) => !["light", "shadow"].includes(k)) ||
+                    !Object.keys(b).length) {
+                    diag(d, "error", "SPRITE_BEVEL", `${path}/bevel`, "bevel is { light?, shadow? }");
+                    return;
+                }
+                const light = b.light === undefined ? null : color(b.light, `${path}/bevel/light`);
+                const shadow = b.shadow === undefined ? null : color(b.shadow, `${path}/bevel/shadow`);
+                if ((b.light !== undefined && light === null) || (b.shadow !== undefined && shadow === null))
+                    return;
+                const width = layer.width === undefined ? 1 : layer.width;
+                if (!isInt(width) || width < 1 || width > 8) {
+                    diag(d, "error", "SPRITE_BEVEL", `${path}/width`, "width is 1..8");
+                    return;
+                }
+                const dirName = layer.dir ?? "upper-left";
+                const dir = Object.hasOwn(DIRS, dirName) ? DIRS[dirName] : null;
+                if (!dir) {
+                    diag(d, "error", "SPRITE_BEVEL", `${path}/dir`, `dir is one of ${Object.keys(DIRS).join(", ")}`);
+                    return;
+                }
+                const set = partList(layer.parts, `${path}/parts`);
+                // Parts listed in `through` count as the same surface for edge tests
+                // (an occluding nozzle does not create an edge), but are not painted.
+                const through = partList(layer.through, `${path}/through`) ?? new Set();
+                const kept = keepColours(layer.keep, `${path}/keep`);
+                const same = (x, y, o) => canvas.opaque(x, y) &&
+                    !kept(canvas, x, y) &&
+                    (canvas.owner(x, y) === o || through.has(canvas.owner(x, y)));
+                const out = [];
+                for (const [o, pix] of regionSets(canvas, set)) {
+                    if (through.has(o))
+                        continue;
+                    for (const p of pix) {
+                        const x = p % W, y = (p / W) | 0;
+                        if (kept(canvas, x, y))
+                            continue;
+                        // The nearest edge toward the light is lit, the nearest away from it
+                        // is shaded; vertical edges decide before horizontal ones.
+                        let side = null;
+                        for (const [ax, ay] of [
+                            [0, dir[1]],
+                            [dir[0], 0],
+                        ]) {
+                            for (let k = 1; k <= width && side === null; k++) {
+                                if (!same(x + ax * k, y + ay * k, o))
+                                    side = "light";
+                                else if (!same(x - ax * k, y - ay * k, o))
+                                    side = "shadow";
+                            }
+                            if (side !== null)
+                                break;
+                        }
+                        const tone = side === "light" ? light : side === "shadow" ? shadow : null;
+                        if (tone)
+                            out.push([x, y, tone]);
+                    }
+                }
+                for (const [x, y, c] of out)
+                    canvas.set(x, y, c);
+                return;
+            }
+            case "speck": {
+                const c = color(layer.speck, `${path}/speck`);
+                if (c === null)
+                    return;
+                const count = layer.count ?? 1, seed = layer.seed ?? 1, inset = layer.inset ?? 1;
+                if (!isInt(count) ||
+                    count < 1 ||
+                    count > SPRITE_LIMITS.specks ||
+                    !isInt(seed) ||
+                    !isInt(inset) ||
+                    inset < 0) {
+                    diag(d, "error", "SPRITE_SPECK", path, `count is 1..${SPRITE_LIMITS.specks}; seed and inset are integers`);
+                    return;
+                }
+                const set = partList(layer.parts, `${path}/parts`);
+                const cand = [];
+                for (const [o, pix] of regionSets(canvas, set))
+                    for (const p of pix) {
+                        const x = p % W, y = (p / W) | 0;
+                        if (inset > Math.min(x, y, W - 1 - x, H - 1 - y))
+                            continue;
+                        let ok = true;
+                        for (let dy = -inset; dy <= inset && ok; dy++)
+                            for (let dx = -inset; dx <= inset && ok; dx++)
+                                if (!(canvas.opaque(x + dx, y + dy) && canvas.owner(x + dx, y + dy) === o))
+                                    ok = false;
+                        if (ok)
+                            cand.push(p);
+                    }
+                cand.sort((a, b) => a - b);
+                const rnd = mulberry32(seed);
+                for (let i = cand.length - 1; i > 0; i--) {
+                    const j = Math.floor(rnd() * (i + 1));
+                    [cand[i], cand[j]] = [cand[j], cand[i]];
+                }
+                const picked = new Set();
+                for (const p of cand) {
+                    if (picked.size >= count)
+                        break;
+                    const x = p % W, y = (p / W) | 0;
+                    let near = false;
+                    for (let dy = -1; dy <= 1 && !near; dy++)
+                        for (let dx = -1; dx <= 1 && !near; dx++) {
+                            const nx = x + dx, ny = y + dy;
+                            if (nx >= 0 && ny >= 0 && nx < W && ny < H && picked.has(ny * W + nx))
+                                near = true;
+                        }
+                    if (!near)
+                        picked.add(p);
+                }
+                if (picked.size < count)
+                    diag(d, "warning", "SPRITE_SPECK_SHORT", path, `placed ${picked.size} of ${count} specks`, {
+                        received: picked.size,
+                        expected: count,
+                    });
+                for (const p of picked)
+                    canvas.set(p % W, (p / W) | 0, c);
+                return;
+            }
+            case "mirror": {
+                if (!["x", "y"].includes(layer.mirror)) {
+                    diag(d, "error", "SPRITE_MIRROR", `${path}/mirror`, 'mirror is "x" (left onto right) or "y" (top onto bottom)');
+                    return;
+                }
+                const set = partList(layer.parts, `${path}/parts`);
+                reservePixels(W, H, path);
+                const src = canvas.clone();
+                const sel = (x, y) => !set || (src.opaque(x, y) && set.has(src.owner(x, y)));
+                for (let y = 0; y < H; y++)
+                    for (let x = 0; x < W; x++) {
+                        const right = layer.mirror === "x" ? x >= W - Math.floor(W / 2) : y >= H - Math.floor(H / 2);
+                        if (!right)
+                            continue;
+                        const sx = layer.mirror === "x" ? W - 1 - x : x, sy = layer.mirror === "y" ? H - 1 - y : y;
+                        if (set && src.opaque(x, y) && set.has(src.owner(x, y)))
+                            canvas.set(x, y, CLEAR);
+                        if (sel(sx, sy)) {
+                            const c = src.color(sx, sy);
+                            canvas.set(x, y, c[3] ? c : CLEAR, src.owner(sx, sy));
+                        }
+                    }
+                return;
+            }
+            case "recolor": {
+                const map = layer.recolor;
+                if (!isObj(map) || !Object.keys(map).length) {
+                    diag(d, "error", "SPRITE_RECOLOR", `${path}/recolor`, "recolor is { fromColour: toColour }");
+                    return;
+                }
+                const pairs = Object.entries(map).map(([from, to]) => [
+                    color(from, `${path}/recolor/${ptr(from)}`),
+                    color(to, `${path}/recolor/${ptr(from)}`),
+                ]);
+                if (pairs.some(([a, b]) => a === null || b === null))
+                    return;
+                const set = partList(layer.parts, `${path}/parts`);
+                for (const [, pix] of regionSets(canvas, set))
+                    for (const p of pix) {
+                        const x = p % W, y = (p / W) | 0;
+                        const c = canvas.color(x, y);
+                        const hit = pairs.find(([a]) => a != null && a !== CLEAR && a.every((v, i) => v === c[i]));
+                        if (hit)
+                            canvas.set(x, y, requireValue(hit[1]));
+                    }
+                return;
+            }
+            case "repaint": {
+                const c = color(layer.repaint, `${path}/repaint`);
+                if (c === null)
+                    return;
+                const set = partList(layer.parts, `${path}/parts`);
+                if (!set) {
+                    diag(d, "error", "SPRITE_PARTS", `${path}/parts`, "repaint needs parts");
+                    return;
+                }
+                const kept = keepColours(layer.keep, `${path}/keep`);
+                for (const [, pix] of regionSets(canvas, set))
+                    for (const p of pix)
+                        if (!kept(canvas, p % W, (p / W) | 0))
+                            canvas.set(p % W, (p / W) | 0, c);
+                return;
+            }
+            case "silhouette": {
+                const names = typeof layer.silhouette === "string" ? [layer.silhouette] : layer.silhouette;
+                if (!Array.isArray(names) ||
+                    (layer.parts !== undefined && !names.length) ||
+                    names.some((n) => typeof n !== "string")) {
+                    diag(d, "error", "SPRITE_SILHOUETTE", `${path}/silhouette`, "silhouette is a guide part name or a list");
+                    return;
+                }
+                const c = color(layer.fill, `${path}/fill`);
+                if (c === null)
+                    return;
+                names.forEach((n, i) => {
+                    const g = guidePart(n, `${path}/silhouette${typeof layer.silhouette === "string" ? "" : `/${i}`}`, true);
+                    if (!g)
+                        return;
+                    const o = owner ?? partOf(n, `${path}/silhouette`);
+                    for (const q of g.mask)
+                        canvas.set(q % W, Math.floor(q / W), c, o);
+                });
+                return;
+            }
+            case "shade": {
+                // Repaints guide part masks with the tone the guide's light gives each
+                // pixel: role 1 deep, 2 shadow, 3 mid, 4 light become ramp steps 0–3
+                // (clamped to the ramp). Role 0 (the guide's outline) is left as it is.
+                const spec = layer.shade;
+                if (layer.guides !== undefined &&
+                    (!isObj(layer.guides) || Object.values(layer.guides).some((n) => typeof n !== "string"))) {
+                    diag(d, "error", "SPRITE_SHADE", `${path}/guides`, "guides maps authored parts to guide names");
+                    return;
+                }
+                if (isObj(spec) && Object.values(spec).some((r) => typeof r !== "string" || !r.length)) {
+                    diag(d, "error", "SPRITE_SHADE", `${path}/shade`, "shade map values must be non-empty ramp names");
+                    return;
+                }
+                const guideName = (n) => isObj(layer.guides) && Object.hasOwn(layer.guides, n) ? layer.guides[n] : n;
+                if (!currentGuide) {
+                    diag(d, "error", "SPRITE_GUIDE_UNAVAILABLE", `${path}/shade`, "shade needs a cel drawn in a view");
+                    return;
+                }
+                const guide = currentGuide;
+                const roles = guide.roles;
+                if (!roles) {
+                    diag(d, "error", "SPRITE_SHADE", `${path}/shade`, "the guide has no tone roles");
+                    return;
+                }
+                const declaredRamp = (n) => isObj(doc.parts) && Object.hasOwn(doc.parts, n) && isObj(doc.parts[n])
+                    ? (doc.parts[n].ramps?.[0] ?? null)
+                    : null;
+                let pairs;
+                if (typeof spec === "string" || spec === true) {
+                    let names = layer.parts;
+                    if (names === undefined && spec === true)
+                        names = Object.keys(isObj(doc.parts) ? doc.parts : {}).filter((n) => declaredRamp(n) !== null && Object.hasOwn(guide.parts, guideName(n)));
+                    if (!Array.isArray(names) ||
+                        (layer.parts !== undefined && !names.length) ||
+                        names.some((n) => typeof n !== "string")) {
+                        diag(d, "error", "SPRITE_SHADE", `${path}/parts`, "shade needs parts: a list of guide part names");
+                        return;
+                    }
+                    pairs = names.map((n) => [
+                        n,
+                        spec === true ? declaredRamp(n) : spec,
+                    ]);
+                }
+                else if (isObj(spec) && Object.keys(spec).length) {
+                    // `parts` beside a { part: ramp } map limits it to those parts.
+                    const listed = layer.parts;
+                    if (listed !== undefined &&
+                        (!Array.isArray(listed) || !listed.length || listed.some((n) => typeof n !== "string"))) {
+                        diag(d, "error", "SPRITE_SHADE", `${path}/parts`, "parts is a list of guide part names");
+                        return;
+                    }
+                    const only = Array.isArray(listed) ? listed : null;
+                    pairs = Object.entries(spec).filter(([n]) => !only || only.includes(n));
+                }
+                else {
+                    diag(d, "error", "SPRITE_SHADE", `${path}/shade`, "shade is a ramp name, { part: ramp } or true");
+                    return;
+                }
+                for (const [n, rampName] of pairs) {
+                    const ramp = typeof rampName === "string" ? (pal.ramps.get(rampName) ?? null) : null;
+                    if (!ramp) {
+                        diag(d, "error", "SPRITE_COLOR_REF", `${path}/shade`, `part ${n} has no ramp ${typeof rampName === "string" ? rampName : "(none declared)"}`, { part: n });
+                        continue;
+                    }
+                    const g = guidePart(guideName(n), `${path}/shade`, true);
+                    if (!g)
+                        continue;
+                    const o = partOf(n, `${path}/shade`);
+                    for (const q of g.mask) {
+                        const role = roles[q] ?? -1;
+                        if (role < 1)
+                            continue;
+                        const c = ramp[Math.min(role - 1, ramp.length - 1)];
+                        if (c)
+                            canvas.set(q % W, Math.floor(q / W), c, o);
+                    }
+                }
+                return;
+            }
+            case "use": {
+                // Draws another cel as a component: its pixels and their owners, at an offset.
+                if (typeof layer.use !== "string" || !Object.hasOwn(celSpecs, layer.use)) {
+                    diag(d, "error", "SPRITE_UNKNOWN_CEL", `${path}/use`, `unknown cel ${JSON.stringify(layer.use)}`);
+                    return;
+                }
+                const src = compileCel(layer.use);
+                if (!src)
+                    return;
+                const flip = layer.flip === undefined ? "" : layer.flip;
+                if (!["", "x", "y", "xy"].includes(flip)) {
+                    diag(d, "error", "SPRITE_FLIP", `${path}/flip`, 'flip must be "x", "y" or "xy"');
+                    return;
+                }
+                const r = resolveAt(canvas, layer.at, `${path}/at`);
+                if (!r)
+                    return;
+                const sc = src.canvas;
+                let outside = 0;
+                for (let y = 0; y < sc.height; y++)
+                    for (let x = 0; x < sc.width; x++) {
+                        if (!sc.opaque(x, y))
+                            continue;
+                        const tx = r.point[0] + (flip.includes("x") ? sc.width - 1 - x : x);
+                        const ty = r.point[1] + (flip.includes("y") ? sc.height - 1 - y : y);
+                        if (!canvas.set(tx, ty, sc.color(x, y), owner ?? sc.owner(x, y)))
+                            outside++;
+                    }
+                if (outside)
+                    diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `${outside} pixel(s) of ${layer.use} fall outside the canvas`, {
+                        received: outside,
+                    });
+                return;
+            }
+            case "recipe": {
+                const name = layer.recipe;
+                const list = typeof name === "string" && Object.hasOwn(recipes, name) ? recipes[name] : null;
+                if (!Array.isArray(list)) {
+                    diag(d, "error", "SPRITE_UNKNOWN_RECIPE", `${path}/recipe`, `unknown recipe ${JSON.stringify(name)}`);
+                    return;
+                }
+                if (recipeStack.includes(name) || recipeStack.length >= 8) {
+                    diag(d, "error", "SPRITE_RECIPE_CYCLE", `${path}/recipe`, `recipe ${name} expands into itself or nests too deeply`);
+                    return;
+                }
+                recipeStack.push(name);
+                for (const [i, l] of list.entries()) {
+                    applyLayer(canvas, l, `${path}/recipe(${ptr(name)})/${i}`);
+                    if (operations > SPRITE_LIMITS.expandedOperations)
+                        break;
+                }
+                recipeStack.pop();
+                return;
+            }
+            case "move": {
+                const m = layer.move;
+                if (!isPoint(m)) {
+                    diag(d, "error", "SPRITE_MOVE", `${path}/move`, "move is [dx, dy] integers");
+                    return;
+                }
+                const set = partList(layer.parts, `${path}/parts`);
+                if (!set) {
+                    diag(d, "error", "SPRITE_PARTS", `${path}/parts`, "move needs parts");
+                    return;
+                }
+                const moved = [];
+                for (const [o, pix] of regionSets(canvas, set))
+                    for (const p of pix)
+                        moved.push([p % W, (p / W) | 0, canvas.color(p % W, (p / W) | 0), o]);
+                for (const [x, y] of moved)
+                    canvas.set(x, y, CLEAR);
+                let outside = 0;
+                for (const [x, y, c, o] of moved)
+                    if (!canvas.set(x + m[0], y + m[1], c, o))
+                        outside++;
+                if (outside)
+                    diag(d, "error", "SPRITE_OUT_OF_BOUNDS", path, `${outside} moved pixel(s) fall outside the canvas`, {
+                        received: outside,
+                    });
+                return;
+            }
+        }
+    }
+    // Compile bases before the cels that inherit from them, so long chains do
+    // not recurse and the result does not depend on key order.
+    const depth = new Map();
+    const depthOf = (start) => {
+        const chain = [];
+        const seen = new Set();
+        let id = start;
+        while (typeof id === "string" && Object.hasOwn(celSpecs, id) && !depth.has(id) && !seen.has(id)) {
+            seen.add(id);
+            chain.push(id);
+            id = isObj(celSpecs[id]) ? celSpecs[id].base : null;
+        }
+        let base = typeof id === "string" && depth.has(id) ? depth.get(id) : 0;
+        for (let i = chain.length - 1; i >= 0; i--)
+            depth.set(chain[i], ++base);
+        return depth.get(start) ?? 0;
+    };
+    const order = celIds.map((id, i) => [depthOf(id), i, id]).sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    try {
+        for (const [, , id] of order)
+            compileCel(id);
+    }
+    catch (e) {
+        if (e !== allocationLimit)
+            throw e;
+    }
+    if (doc.animations !== undefined) {
+        if (!isObj(doc.animations))
+            diag(d, "error", "SPRITE_ANIMATIONS", "/animations", "animations must be an object");
+        else
+            for (const [name, a] of Object.entries(doc.animations)) {
+                const p = `/animations/${ptr(name)}`;
+                if (!isObj(a) || !Array.isArray(a.cels) || !a.cels.length) {
+                    diag(d, "error", "SPRITE_ANIMATION", p, "an animation is { cels: [...], ms, loop? }");
+                    continue;
+                }
+                for (const k of Object.keys(a))
+                    if (!["cels", "ms", "loop"].includes(k))
+                        diag(d, "error", "SPRITE_UNKNOWN_FIELD", `${p}/${ptr(k)}`, `unknown field ${k}`);
+                a.cels.forEach((c, i) => {
+                    if (typeof c !== "string" || !Object.hasOwn(celSpecs, c))
+                        diag(d, "error", "SPRITE_UNKNOWN_CEL", `${p}/cels/${i}`, `unknown cel ${JSON.stringify(c)}`);
+                });
+                const ms = Array.isArray(a.ms) ? a.ms : a.cels.map(() => a.ms ?? 100);
+                if (ms.length !== a.cels.length || !ms.every((v) => isInt(v) && v > 0))
+                    diag(d, "error", "SPRITE_ANIMATION", `${p}/ms`, "ms is a positive integer or one per cel");
+                const sizes = new Set(a.cels
+                    .map((c) => result.cels.get(c))
+                    .filter((c) => c !== undefined)
+                    .map((c) => `${c.canvas.width}x${c.canvas.height}`));
+                if (sizes.size > 1)
+                    diag(d, "error", "SPRITE_ANIMATION", `${p}/cels`, "animation cels differ in size");
+                if (a.loop !== undefined && typeof a.loop !== "boolean")
+                    diag(d, "error", "SPRITE_ANIMATION", `${p}/loop`, "loop must be boolean");
+                result.animations.set(name, { cels: a.cels, ms, loop: a.loop !== false });
+            }
+    }
+    result.parts = parts;
+    result.ok = !d.some((x) => x.severity === "error");
+    return result;
+}
+/** Maps every opaque pixel to the nearest palette colour in OKLab. */
+export function snapToPalette(canvas, colors) {
+    if (!colors.length)
+        return;
+    const labs = colors.map((c) => [c, rgbToOklab(c)]);
+    const memo = new Map();
+    for (let p = 0; p < canvas.owners.length; p++) {
+        const a = canvas.rgba[p * 4 + 3] ?? 0;
+        if (!a)
+            continue;
+        const key = `${canvas.rgba[p * 4]},${canvas.rgba[p * 4 + 1]},${canvas.rgba[p * 4 + 2]}`;
+        let best = memo.get(key);
+        if (!best) {
+            const lab = rgbToOklab([
+                canvas.rgba[p * 4] ?? 0,
+                canvas.rgba[p * 4 + 1] ?? 0,
+                canvas.rgba[p * 4 + 2] ?? 0,
+            ]);
+            let bd = Infinity;
+            for (const [c, l] of labs) {
+                const dd = (l[0] - lab[0]) ** 2 + (l[1] - lab[1]) ** 2 + (l[2] - lab[2]) ** 2;
+                if (dd < bd) {
+                    bd = dd;
+                    best = c;
+                }
+            }
+            memo.set(key, best);
+        }
+        canvas.rgba.set([best[0], best[1], best[2], a], p * 4);
+    }
+}
+/** Part under a pixel of a compiled cel, or null. */
+export function pickSprite(result, celId, x, y) {
+    if (!Number.isInteger(x) || !Number.isInteger(y))
+        return null;
+    const cel = result.cels.get(celId);
+    if (!cel || !cel.canvas.opaque(x, y))
+        return null;
+    return result.parts[cel.canvas.owner(x, y)] ?? null;
+}
+function invalidResolver(message) {
+    throw new Error(message);
+}
+function validSize(value) {
+    return [value.width, value.height].every((n) => Number.isInteger(n) && n >= 1 && n <= SPRITE_LIMITS.dimension);
+}
+function validateRender(r) {
+    if (!r || !validSize(r))
+        invalidResolver("render dimensions must be integers within 1..1024");
+    if (!(r.rgba instanceof Uint8Array) ||
+        r.rgba.length !== r.width * r.height * 4 ||
+        !(r.owners instanceof Int32Array) ||
+        r.owners.length !== r.width * r.height ||
+        !Array.isArray(r.names) ||
+        r.names.some((n) => typeof n !== "string") ||
+        r.owners.some((o) => o < -1 || o >= r.names.length))
+        invalidResolver("invalid render rgba, owners or names");
+}
+function validateGuide(g) {
+    if (!g || !validSize(g))
+        invalidResolver("guide dimensions must be integers within 1..1024");
+    if (!isObj(g.parts) ||
+        (g.owners !== undefined &&
+            (!(g.owners instanceof Int32Array) || g.owners.length !== g.width * g.height)) ||
+        (g.depth !== undefined && g.depth.length !== g.width * g.height) ||
+        (g.roles !== undefined && (!(g.roles instanceof Int8Array) || g.roles.length !== g.width * g.height)) ||
+        (g.hidden !== undefined && (!Array.isArray(g.hidden) || g.hidden.some((n) => typeof n !== "string"))))
+        invalidResolver("invalid guide parts, owners, depth, roles or hidden");
+    for (const part of Object.values(g.parts)) {
+        if (!isObj(part) ||
+            !Array.isArray(part.bbox) ||
+            part.bbox.length !== 4 ||
+            !part.bbox.every(Number.isFinite) ||
+            part.bbox[2] <= 0 ||
+            part.bbox[3] <= 0 ||
+            !Number.isFinite(part.area) ||
+            part.area < 0 ||
+            !Array.isArray(part.mask) ||
+            part.mask.some((q) => !Number.isInteger(q) || q < 0 || q >= g.width * g.height))
+            invalidResolver("invalid guide part bbox, area or mask");
+    }
+}
+function resolverErrors(error, code) {
+    const value = isObj(error) ? error : {};
+    const diagnostics = Array.isArray(value.diagnostics)
+        ? value.diagnostics.filter(isObj)
+        : [];
+    if (!diagnostics.some((d) => d.severity !== "warning"))
+        diagnostics.push({ severity: "error", code, message: String(value.message ?? error) });
+    return diagnostics;
+}