@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/sprite-scene.js

@@ -0,0 +1,664 @@
+import { PIXEL_CAMERAS, PIXEL_PROFILES, composePixelScene, linearToOklab, pixelCamera, pixelRamp, renderPixelArt, } from "./pixel.js";
+import { compileAsset } from "./compiler.js";
+import { posedAsset, spriteGuideResolver, spriteRenderResolver } from "./sprite-guide.js";
+import { compileSprite, SPRITE_LIMITS } from "./sprite-compiler.js";
+import { requireValue } from "./required.js";
+const PRESETS = {
+    dimetric: [135, 30],
+    dimetricRight: [225, 30],
+    dimetricOpposite: [315, 30],
+    dimetricLeft: [45, 30],
+    front: [180, 8],
+    topDown: [180, 45],
+};
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+function checkFrameSize(width, height) {
+    if (![width, height].every((n) => Number.isSafeInteger(n) && n > 0 && n <= SPRITE_LIMITS.sceneDimension))
+        throw new Error(`scene frame dimensions must be integers within 1..${SPRITE_LIMITS.sceneDimension}`);
+}
+// Object member order has no meaning in a JSON scene contract; array order does.
+function structurallyEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) || Array.isArray(b))
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((v, i) => structurallyEqual(v, b[i])));
+    const left = a, right = b;
+    return (Object.keys(left).length === Object.keys(right).length &&
+        Object.keys(left).every((key) => Object.hasOwn(right, key) && structurallyEqual(left[key], right[key])));
+}
+/** Prepare a scene using caller-owned asset JSON; performs no IO. */
+export function prepareSpriteScene(scene, resolve) {
+    if (scene.format !== "pixel-sprite-scene/0.1")
+        throw new Error("expected pixel-sprite-scene/0.1");
+    const assets = new Map();
+    const ids = new Set();
+    for (const p of scene.placements) {
+        if (ids.has(p.id))
+            throw new Error(`duplicate placement ${p.id}`);
+        ids.add(p.id);
+        if (assets.has(p.asset))
+            continue;
+        const meta = Object.hasOwn(scene.assets, p.asset) ? scene.assets[p.asset] : null;
+        if (!meta)
+            throw new Error(`placement ${p.id}: asset ${p.asset} is not declared in assets`);
+        const { spec, motion = null } = resolve(p.asset);
+        assets.set(p.asset, {
+            ref: p.asset,
+            spec,
+            compiled: compileAsset(spec),
+            motion,
+            sprite: meta.sprite,
+            states: meta.states ?? {},
+        });
+    }
+    const placements = scene.placements.map((p) => ({ ...p, yaw: p.yaw ?? 0, tint: p.tint ?? null }));
+    return { scene, assets, placements };
+}
+const anglesOf = (view) => typeof view.camera === "string" ? requireValue(PRESETS[view.camera]) : [view.camera.yaw, view.camera.pitch];
+export const cameraOf = (camera) => typeof camera === "string" ? requireValue(PIXEL_CAMERAS[camera]) : pixelCamera(camera.yaw, camera.pitch);
+/** Name of the asset view for a scene view and state ("dimetric", "dimetric-open"). */
+export const assetViewName = (view, state = "idle") => state === "idle" ? view : `${view}-${state}`;
+/** Cel id a placement shows in a scene view and state. */
+export const celIdFor = (view, state = "idle") => `${view}/${state}/0`;
+/**
+ * The asset-local view a placement needs: a placement with yaw ψ seen by a
+ * camera of yaw φ is its asset seen from yaw φ − ψ at the same pitch.
+ */
+export function placementView(loaded, placement, view, state = "idle") {
+    const v = requireValue(loaded.scene.views[view]);
+    const [yaw, pitch] = anglesOf(requireValue(v));
+    const local = (((yaw - placement.yaw) % 360) + 360) % 360;
+    const out = {
+        camera: placement.yaw === 0 && typeof v.camera === "string" ? v.camera : { yaw: local, pitch },
+        pixelsPerMetre: loaded.scene.pixelsPerMetre,
+    };
+    const hide = (v.hide ?? [])
+        .filter((h) => h.startsWith(`${placement.id}/`))
+        .map((h) => h.slice(placement.id.length + 1));
+    if (hide.length)
+        out.hide = hide;
+    if (state !== "idle") {
+        const pose = requireValue(loaded.assets.get(placement.asset)).states[state];
+        if (!pose)
+            throw new Error(`asset ${placement.asset} has no state ${state}`);
+        out.pose = pose;
+    }
+    return out;
+}
+/** The states an asset offers, idle first. */
+export const statesOf = (loaded, ref) => [
+    "idle",
+    ...Object.keys(requireValue(loaded.assets.get(ref)).states),
+];
+/** The `views` object an asset's sprite document must declare, and the cels it must contain. */
+export function assetViews(loaded, ref) {
+    const views = Object.create(null);
+    const cels = [];
+    for (const p of loaded.placements.filter((q) => q.asset === ref))
+        for (const view of Object.keys(loaded.scene.views))
+            for (const state of statesOf(loaded, ref)) {
+                const name = assetViewName(view, state);
+                const v = placementView(loaded, p, view, state);
+                if (views[name] && !structurallyEqual(views[name], v))
+                    throw new Error(`placements of ${ref} need different ${name} views; give them separate documents`);
+                if (!views[name])
+                    cels.push(celIdFor(view, state));
+                views[name] = v;
+            }
+    return { views, cels };
+}
+const cutBy = (hide) => (inst) => hide.some((h) => {
+    const slash = h.indexOf("/");
+    return inst.id.startsWith(`${h.slice(0, slash)}/`) && inst.part === h.slice(slash + 1);
+});
+/** Scene instances for a view (cutaways applied), optionally only some placements, with states. */
+export function sceneInstances(loaded, view, { only = null, states = {} } = {}) {
+    const placements = loaded.placements
+        .filter((p) => !only || only.includes(p.id))
+        .map((p) => {
+        const a = requireValue(loaded.assets.get(p.asset));
+        const state = states[p.id] ?? "idle";
+        const asset = state === "idle" ? a.compiled : posedAsset(a.compiled, a.motion, a.states[state]);
+        return { id: p.id, asset, position: p.position, yawDegrees: p.yaw, tint: p.tint };
+    });
+    const cut = cutBy(requireValue(loaded.scene.views[view]).hide ?? []);
+    return composePixelScene(placements).filter((inst) => !cut(inst));
+}
+/**
+ * The scene's pixel grid in a view: canvas size and the world position of its
+ * top-left corner along camera right and up, fitted to every placement at rest.
+ */
+export function sceneFrame(loaded, view, margin = 6) {
+    const camera = cameraOf(requireValue(loaded.scene.views[view]).camera);
+    const ppm = loaded.scene.pixelsPerMetre;
+    if (!Number.isFinite(ppm) || ppm <= 0 || !Number.isSafeInteger(margin) || margin < 0)
+        throw new Error("scene frame needs positive finite pixelsPerMetre and a non-negative safe integer margin");
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    for (const { mesh } of sceneInstances(loaded, view))
+        for (let v = 0; v < mesh.positions.length; v += 3) {
+            const p = [mesh.positions[v], mesh.positions[v + 1], mesh.positions[v + 2]];
+            minX = Math.min(minX, dot(p, camera.right));
+            maxX = Math.max(maxX, dot(p, camera.right));
+            minY = Math.min(minY, dot(p, camera.up));
+            maxY = Math.max(maxY, dot(p, camera.up));
+        }
+    if (minX === Infinity)
+        throw new Error(`scene view ${view} has an empty projection`);
+    const width = Math.ceil((maxX - minX) * ppm) + 2 * margin;
+    const height = Math.ceil((maxY - minY) * ppm) + 2 * margin;
+    checkFrameSize(width, height);
+    const originX = minX - Math.floor((width - (maxX - minX) * ppm) / 2) / ppm;
+    const originY = maxY + Math.floor((height - (maxY - minY) * ppm) / 2) / ppm;
+    const cx = originX + width / 2 / ppm, cy = originY - height / 2 / ppm;
+    const center = [0, 1, 2].map((i) => requireValue(camera.right[i]) * cx + requireValue(camera.up[i]) * cy);
+    return { camera, ppm, width, height, originX, originY, frame: { center, width, height } };
+}
+/** 3D reference render (arcade profile) of the scene, or of some placements, on the scene grid. */
+export function sceneRender(loaded, view, { only = null, states = {}, background = null, } = {}) {
+    const f = sceneFrame(loaded, view);
+    return renderPixelArt(sceneInstances(loaded, view, { only, states }), {
+        camera: f.camera,
+        pixelsPerMetre: f.ppm,
+        frame: f.frame,
+        profile: PIXEL_PROFILES.arcade,
+        background,
+    });
+}
+/** Screen offset (pixels, unrounded) of a placement's asset-local origin on the scene grid. */
+export function placementOffset(loaded, placement, view) {
+    const f = sceneFrame(loaded, view);
+    return {
+        x: (dot(placement.position, f.camera.right) - f.originX) * f.ppm,
+        y: (f.originY - dot(placement.position, f.camera.up)) * f.ppm,
+        depth: dot(placement.position, f.camera.back),
+    };
+}
+// ---------- shared palette ----------
+const srgbToLinear = (v) => ((v /= 255) <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+const linearOf = (hex) => [1, 3, 5].map((i) => srgbToLinear(parseInt(hex.slice(i, i + 2), 16)));
+const labDistance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+/** Materials closer than this in OKLab share one ramp. */
+export const MERGE_DISTANCE = 0.015;
+/**
+ * One locked palette for the whole scene: four tones (deep, shadow, mid,
+ * light) per material colour as placed (tints applied), from the /pixel arcade
+ * ramp, with near-identical materials merged, plus the shared outline `line`.
+ * Returns the palette, and per asset the ramp of each material.
+ */
+export function scenePalette(loaded) {
+    const entries = []; // { ref, material, name, linear, lab }
+    const tintOf = new Map();
+    for (const p of loaded.placements) {
+        const prev = tintOf.get(p.asset);
+        if (prev !== undefined && prev !== p.tint)
+            throw new Error(`placements of ${p.asset} use different tints; one sprite document cannot serve both`);
+        tintOf.set(p.asset, p.tint);
+    }
+    for (const [ref, a] of loaded.assets) {
+        const tint = tintOf.get(ref);
+        for (const [material, m] of Object.entries(a.compiled.materials)) {
+            let lin = linearOf(m.color);
+            if (m.tintable && tint)
+                lin = lin.map((v, i) => v * requireValue(linearOf(tint)[i]));
+            entries.push({ ref, material, linear: lin, lab: linearToOklab(lin) });
+        }
+    }
+    const clusters = [];
+    for (const e of entries) {
+        const c = clusters.find((k) => labDistance(k.lab, e.lab) < MERGE_DISTANCE);
+        if (c)
+            c.members.push(e);
+        else
+            clusters.push({ lab: e.lab, linear: e.linear, members: [e] });
+    }
+    const ramps = Object.create(null);
+    const byAsset = Object.create(null);
+    const taken = new Map();
+    for (const c of clusters) {
+        const base = colourName(c.lab);
+        let name = base;
+        for (let k = 2; taken.has(name); k++)
+            name = `${base}-${k}`;
+        taken.set(name, c);
+        ramps[name] = pixelRamp(c.linear, PIXEL_PROFILES.arcade).slice(1);
+        for (const m of c.members)
+            (byAsset[m.ref] ??= {})[m.material] = name;
+    }
+    return {
+        palette: { lock: true, colors: { line: loaded.scene.outline }, ramps },
+        materials: byAsset,
+    };
+}
+/**
+ * A short descriptive name for a colour from its OKLab value ("pale-teal",
+ * "dark-red", "cream", "charcoal"), so ramps read as what they look like.
+ */
+export function colourName([L, a, b]) {
+    const C = Math.hypot(a, b);
+    const h = ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360;
+    if (C < 0.025)
+        return L > 0.9 ? "white" : L > 0.75 ? "light-grey" : L > 0.45 ? "grey" : "charcoal";
+    if (h >= 40 && h < 105 && C < 0.1)
+        return L > 0.85 ? "cream" : L > 0.68 ? "sand" : L > 0.5 ? "tan" : L > 0.38 ? "brown" : "dark-brown";
+    const hue = h < 15 || h >= 345
+        ? "pink"
+        : h < 40
+            ? "red"
+            : h < 75
+                ? "orange"
+                : h < 110
+                    ? "yellow"
+                    : h < 150
+                        ? "olive"
+                        : h < 175
+                            ? "green"
+                            : h < 215
+                                ? "teal"
+                                : h < 270
+                                    ? "blue"
+                                    : h < 310
+                                        ? "purple"
+                                        : "magenta";
+    return L > 0.85 ? `pale-${hue}` : L < 0.5 ? `dark-${hue}` : hue;
+}
+/** The palette subset an asset's document uses: its materials' ramps and the outline. */
+export function assetPalette(shared, ref) {
+    const names = [...new Set(Object.values(requireValue(shared.materials[ref])))].sort();
+    return {
+        lock: true,
+        colors: { ...shared.palette.colors },
+        ramps: Object.fromEntries(names.map((n) => [n, requireValue(shared.palette.ramps[n])])),
+    };
+}
+/** Per part of an asset: its material and the scene ramp that material uses. */
+export function partRamps(loaded, shared, ref) {
+    const spec = requireValue(loaded.assets.get(ref)).spec;
+    return Object.fromEntries(Object.entries(spec.parts ?? {}).map(([part, def]) => [
+        part,
+        { material: def.material, ramp: requireValue(shared.materials[ref])[def.material] ?? null },
+    ]));
+}
+/** Compiles one asset's document with the kitchen resolvers and checks it against the scene's contract. */
+export function compileAssetSprite(loaded, shared, ref, input) {
+    const doc = input;
+    const result = compileSprite(doc, {
+        renderBase: spriteRenderResolver(requireValue(loaded.assets.get(ref)).compiled),
+        guide: spriteGuideResolver(requireValue(loaded.assets.get(ref)).compiled, {
+            motion: requireValue(loaded.assets.get(ref)).motion,
+        }),
+    });
+    const problems = [];
+    if (doc.asset !== ref)
+        problems.push(`asset must be ${ref}`);
+    const { views, cels } = assetViews(loaded, ref);
+    for (const [name, v] of Object.entries(views))
+        if (!structurallyEqual(doc.views?.[name], v))
+            problems.push(`views.${name} must be ${JSON.stringify(v)}`);
+    const requiredViews = new Map(Object.keys(loaded.scene.views).flatMap((view) => statesOf(loaded, ref).map((state) => [celIdFor(view, state), assetViewName(view, state)])));
+    for (const id of cels) {
+        const cel = result.cels.get(id);
+        if (!cel) {
+            problems.push(`missing cel ${id}`);
+            continue;
+        }
+        const name = requireValue(requiredViews.get(id));
+        const guide = result.guides.get(name);
+        if (cel.view !== name)
+            problems.push(`cel ${id} must be drawn in view ${name}`);
+        if (!guide)
+            problems.push(`cel ${id} needs a resolved ${name} guide`);
+        else if (cel.canvas.width !== guide.width || cel.canvas.height !== guide.height)
+            problems.push(`cel ${id} size must match the ${name} guide`);
+    }
+    const want = assetPalette(shared, ref);
+    const pal = doc.palette ?? {};
+    if (pal.lock !== true)
+        problems.push("palette.lock must be true");
+    if (!structurallyEqual(pal.colors, want.colors))
+        problems.push(`palette.colors must be ${JSON.stringify(want.colors)}`);
+    for (const [name, ramp] of Object.entries(pal.ramps ?? {}))
+        if (!structurallyEqual(shared.palette.ramps[name], ramp))
+            problems.push(`palette.ramps.${name} is not the scene ramp of that name`);
+    return { result, problems, cels };
+}
+/** Share of two placements' 3D overlap that must disagree before their draw order is reported as wrong. */
+export const ORDER_SHARE = 0.25;
+/** Depth toward the camera of a placement's bounds centre (posed bounds for a state). */
+function centreDepth(loaded, p, camera, state) {
+    const a0 = requireValue(loaded.assets.get(p.asset));
+    const b = state === "idle" ? a0.compiled.bounds : posedAsset(a0.compiled, a0.motion, a0.states[state]).bounds;
+    const a = (p.yaw * Math.PI) / 180, c = Math.cos(a), s = Math.sin(a);
+    const m = [0, 1, 2].map((i) => (requireValue(b.min[i]) + requireValue(b.max[i])) / 2);
+    const centre = [
+        c * m[0] + s * m[2] + p.position[0],
+        m[1] + p.position[1],
+        -s * m[0] + c * m[2] + p.position[2],
+    ];
+    return dot(centre, camera.back);
+}
+/** Back-to-front order: "back" placements (the room) first, then by bounds-centre depth. */
+export function drawOrder(loaded, view, states = {}) {
+    const f = sceneFrame(loaded, view);
+    const key = new Map(loaded.placements.map((p) => [p.id, centreDepth(loaded, p, f.camera, states[p.id] ?? "idle")]));
+    return [...loaded.placements].sort((p, q) => Number(q.order === "back") - Number(p.order === "back") ||
+        requireValue(key.get(p.id)) - requireValue(key.get(q.id)) ||
+        (p.id < q.id ? -1 : 1));
+}
+/**
+ * The layers of one view: per placement, its cel for the state in `states`
+ * (or, with `allStates`, one layer for idle and each state the placement
+ * offers in its `states` list), placed
+ * by its guide's origin, with a 3D depth per pixel. `depth: "parts"` (default)
+ * takes the depth of the guide's projected surface under each pixel (plus the
+ * placement's translation), else the mean depth of the part that owns it, else
+ * the nearest among its neighbours (outlines, details drawn beyond the
+ * projection), else the placement's centre. `depth: "placements"` gives every
+ * pixel the placement's centre depth. Placements without a compiled sprite are
+ * skipped and listed. The result can be composed many times, with different
+ * states, by `composeSpriteLayers` (for example in a browser).
+ */
+export function spriteSceneLayers(loaded, view, sprites, { states = {}, depth = "parts", allStates = false } = {}) {
+    const f = sceneFrame(loaded, view);
+    const layers = [];
+    const skipped = [];
+    for (const p of loaded.placements) {
+        const s = sprites.get(p.asset);
+        let selectedAvailable = false;
+        // With allStates: idle plus the states this placement offers (its `states` list; none without one).
+        const offered = statesOf(loaded, p.asset);
+        const wanted = allStates
+            ? ["idle", ...(p.states ?? []).filter((st) => offered.includes(st))]
+            : [states[p.id] ?? "idle"];
+        for (const state of wanted) {
+            const cel = s?.cels.get(celIdFor(view, state));
+            const guide = s?.guides.get(state === "idle" ? view : `${view}-${state}`);
+            if (!s || !cel || !guide)
+                continue;
+            if (state === (states[p.id] ?? "idle"))
+                selectedAvailable = true;
+            const o = placementOffset(loaded, p, view);
+            // o is the placement's origin on the scene grid; the guide origin is the
+            // cel's top-left in the asset's own frame (metres along camera right/up).
+            const x0 = Math.round(o.x + requireValue(guide.originX) * f.ppm);
+            const y0 = Math.round(o.y - requireValue(guide.originY) * f.ppm);
+            const c = cel.canvas;
+            const n = c.width * c.height;
+            const z = new Float64Array(n).fill(NaN);
+            const back = p.order === "back";
+            const fallback = centreDepth(loaded, p, f.camera, state);
+            for (let i = 0; i < n; i++) {
+                if (!c.rgba[i * 4 + 3])
+                    continue;
+                if (back || depth !== "parts") {
+                    z[i] = back ? -Infinity : fallback;
+                    continue;
+                }
+                // The 3D surface under this pixel decides; where the drawing goes beyond
+                // the projection, the part's mean depth; otherwise the neighbours'.
+                const gd = requireValue(guide.depth && c.width === guide.width && c.height === guide.height ? guide.depth[i] : NaN);
+                if (Number.isFinite(gd)) {
+                    z[i] = gd + o.depth;
+                    continue;
+                }
+                const name = s.parts[c.owners[i] ?? -1];
+                const g = name
+                    ? Object.hasOwn(guide.parts, name)
+                        ? guide.parts[name]
+                        : guide.parts[name.split("/")[0] ?? ""]
+                    : null;
+                if (g && Number.isFinite(g.z))
+                    z[i] = requireValue(g.z) + o.depth;
+            }
+            for (let pass = 0; pass < 3; pass++) {
+                const next = Float64Array.from(z);
+                for (let i = 0; i < n; i++) {
+                    if (!c.rgba[i * 4 + 3] || !Number.isNaN(z[i]))
+                        continue;
+                    const x = i % c.width, y = (i / c.width) | 0;
+                    let best = NaN;
+                    for (const [dx, dy] of [
+                        [-1, 0],
+                        [1, 0],
+                        [0, -1],
+                        [0, 1],
+                    ]) {
+                        const X = x + dx, Y = y + dy;
+                        if (X < 0 || Y < 0 || X >= c.width || Y >= c.height)
+                            continue;
+                        const v = requireValue(z[Y * c.width + X]);
+                        if (!Number.isNaN(v) && !(v <= best))
+                            best = v;
+                    }
+                    next[i] = best;
+                }
+                z.set(next);
+            }
+            for (let i = 0; i < n; i++)
+                if (c.rgba[i * 4 + 3] && Number.isNaN(z[i]))
+                    z[i] = fallback;
+            layers.push({
+                id: p.id,
+                asset: p.asset,
+                state,
+                cel: cel.id,
+                at: [x0, y0],
+                width: c.width,
+                height: c.height,
+                rgba: c.rgba,
+                owners: c.owners,
+                parts: s.parts,
+                depth: z,
+                back,
+                order: fallback,
+            });
+        }
+        if (!selectedAvailable)
+            skipped.push(p.id);
+    }
+    return { view, width: f.width, height: f.height, layers, skipped };
+}
+/**
+ * Composes layers (from `spriteSceneLayers`) with a depth buffer: per
+ * placement the layer for its state in `states` (default "idle"), drawn
+ * "back" placements first, then by the order key and id, keeping the nearest
+ * pixel (later layers win ties). Host independent and cheap enough to run on
+ * every toggle in a browser.
+ */
+export function composeSpriteLayers(built, { states = {}, background = null } = {}) {
+    const W = built.width, H = built.height;
+    checkFrameSize(W, H);
+    const rgba = new Uint8Array(W * H * 4);
+    if (background) {
+        const [r, g, b] = [1, 3, 5].map((i) => parseInt(background.slice(i, i + 2), 16));
+        for (let i = 0; i < W * H; i++)
+            rgba.set([requireValue(r), requireValue(g), requireValue(b), 255], i * 4);
+    }
+    const owner = new Int32Array(W * H).fill(-1); // index into `placed`
+    const part = new Array(W * H).fill(null);
+    const zbuf = new Float64Array(W * H).fill(-Infinity);
+    const placed = [];
+    const chosen = built.layers
+        .filter((l) => l.state === (states[l.id] ?? "idle"))
+        .sort((p, q) => Number(q.back) - Number(p.back) || p.order - q.order || (p.id < q.id ? -1 : 1));
+    const drawn = new Set(chosen.map((l) => l.id));
+    const skipped = [
+        ...built.skipped.filter((id) => !drawn.has(id)),
+        ...[...new Set(built.layers.map((l) => l.id))].filter((id) => !drawn.has(id) && !built.skipped.includes(id)),
+    ];
+    for (const l of chosen) {
+        const index = placed.length;
+        const mask = [];
+        const [x0, y0] = l.at;
+        for (let y = 0; y < l.height; y++)
+            for (let x = 0; x < l.width; x++) {
+                const i = y * l.width + x;
+                const a = l.rgba[i * 4 + 3];
+                if (!a)
+                    continue;
+                const X = x0 + x, Y = y0 + y;
+                if (X < 0 || Y < 0 || X >= W || Y >= H)
+                    continue;
+                const q = Y * W + X;
+                mask.push(q);
+                const zi = requireValue(l.depth[i]);
+                if (zi < requireValue(zbuf[q]))
+                    continue;
+                zbuf[q] = zi;
+                const src = i * 4;
+                if (a === 255)
+                    rgba.set(l.rgba.subarray(src, src + 4), q * 4);
+                else {
+                    const sourceAlpha = a / 255;
+                    const destinationAlpha = requireValue(rgba[q * 4 + 3]) / 255;
+                    const remaining = destinationAlpha * (1 - sourceAlpha);
+                    const alpha = sourceAlpha + remaining;
+                    for (let k = 0; k < 3; k++)
+                        rgba[q * 4 + k] = Math.round((requireValue(l.rgba[src + k]) * sourceAlpha + requireValue(rgba[q * 4 + k]) * remaining) /
+                            alpha);
+                    rgba[q * 4 + 3] = Math.round(alpha * 255);
+                }
+                owner[q] = index;
+                part[q] = l.parts[l.owners[i] ?? -1] ?? null;
+            }
+        placed.push({
+            id: l.id,
+            asset: l.asset,
+            state: l.state,
+            cel: l.cel,
+            at: [x0, y0],
+            size: [l.width, l.height],
+            mask,
+        });
+    }
+    return { view: built.view, width: W, height: H, rgba, owner, part, placed, skipped };
+}
+/**
+ * Composes one view. `sprites` maps an asset ref to its compiled result;
+ * `states` maps a placement id to a state ("open"). Equivalent to
+ * `composeSpriteLayers(spriteSceneLayers(...))`: pixels sort by the 3D depth
+ * under them, so a non-convex object such as an open door sorts pixel by
+ * pixel; "back" placements are always behind; `depth: "placements"` is plain
+ * back-to-front drawing by bounds centre.
+ */
+export function composeSpriteScene(loaded, view, sprites, { states = {}, background = null, depth = "parts" } = {}) {
+    return composeSpriteLayers(spriteSceneLayers(loaded, view, sprites, { states, depth }), {
+        states,
+        background,
+    });
+}
+/** Placement and part under a scene pixel, or null. */
+export function pickScene(composed, x, y) {
+    if (!Number.isInteger(x) ||
+        !Number.isInteger(y) ||
+        x < 0 ||
+        y < 0 ||
+        x >= composed.width ||
+        y >= composed.height)
+        return null;
+    const q = y * composed.width + x;
+    const i = requireValue(composed.owner[q]);
+    return i < 0 ? null : { placement: requireValue(composed.placed[i]).id, part: composed.part[q] ?? null };
+}
+function maskOf(owners, pred) {
+    const m = new Set();
+    for (let q = 0; q < owners.length; q++)
+        if (requireValue(owners[q]) >= 0 && pred(requireValue(owners[q])))
+            m.add(q);
+    return m;
+}
+/**
+ * Footprint report: per placed sprite, overlap with the placement's own
+ * (unoccluded) 3D mask, the integer shift within ±3 px that maximises it, and
+ * draw-order disagreements with the 3D scene render.
+ */
+export function spriteSceneFootprint(loaded, composed, { states = {} } = {}) {
+    const { view, width: W } = composed;
+    const full = sceneRender(loaded, view, { states });
+    const placementOfInstance = full.instances.map((i) => i.id.split("/")[0]);
+    const rows = [];
+    const masks3 = new Map();
+    for (const [index, pl] of composed.placed.entries()) {
+        const alone = sceneRender(loaded, view, { only: [pl.id], states });
+        const m3 = maskOf(alone.owners, () => true);
+        masks3.set(pl.id, m3);
+        const ms = new Set(pl.mask);
+        const iouAt = (dx, dy) => {
+            let inter = 0;
+            for (const q of ms) {
+                const x = (q % W) - dx, y = Math.floor(q / W) - dy;
+                if (m3.has(y * W + x))
+                    inter++;
+            }
+            return inter / (ms.size + m3.size - inter || 1);
+        };
+        const iou = iouAt(0, 0);
+        let best = { dx: 0, dy: 0, iou };
+        for (let dy = -3; dy <= 3; dy++)
+            for (let dx = -3; dx <= 3; dx++) {
+                const v = iouAt(dx, dy);
+                if (v > best.iou + 1e-9)
+                    best = { dx, dy, iou: v };
+            }
+        // A shift counts only if it improves the overlap noticeably.
+        const shift = best.iou - iou > 0.02 ? [best.dx, best.dy] : [0, 0];
+        rows.push({
+            placement: pl.id,
+            asset: pl.asset,
+            state: pl.state,
+            spritePixels: ms.size,
+            modelPixels: m3.size,
+            iou: +iou.toFixed(3),
+            bestShift: shift,
+            bestIou: +best.iou.toFixed(3),
+            misaligned: Math.max(Math.abs(requireValue(shift[0])), Math.abs(requireValue(shift[1]))) > 1,
+            index,
+        });
+    }
+    // Draw order: where both placements are present in 3D (inside both of their
+    // own masks) and both sprites are drawn, the sprite on top must be the one
+    // the 3D render shows in front. Outlines and exaggeration outside a
+    // placement's own mask are not order errors.
+    const spriteMasks = new Map(composed.placed.map((p) => [p.id, new Set(p.mask)]));
+    const pairs = new Map();
+    for (let q = 0; q < composed.owner.length; q++) {
+        const top = requireValue(composed.owner[q]);
+        const o3 = requireValue(full.owners[q]);
+        if (top < 0 || o3 < 0)
+            continue;
+        const front3 = placementOfInstance[o3];
+        const topId = requireValue(composed.placed[top]).id;
+        if (front3 === topId)
+            continue;
+        if (!masks3.get(topId)?.has(q) || !masks3.get(front3)?.has(q))
+            continue;
+        if (!spriteMasks.get(requireValue(front3))?.has(q))
+            continue;
+        const key = `${front3} over ${topId}`;
+        pairs.set(key, (pairs.get(key) ?? 0) + 1);
+    }
+    // A pair is reported with the share of its 3D overlap that disagrees; small
+    // shares are edge pixels whose majority owner changes with the background.
+    const order = [...pairs.entries()]
+        .map(([pair, pixels]) => {
+        const [front, top] = pair.split(" over ");
+        const a = masks3.get(front), b = masks3.get(top);
+        let both = 0;
+        for (const q of b)
+            if (a.has(q))
+                both++;
+        return { pair, pixels, share: +(pixels / (both || 1)).toFixed(3) };
+    })
+        .filter((p) => p.pixels >= 4)
+        .sort((a, b) => b.pixels - a.pixels);
+    return {
+        view,
+        placements: rows,
+        orderDisagreements: order,
+        wrongOrder: order.filter((p) => p.share > ORDER_SHARE && p.pixels >= 8),
+    };
+}