@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/pixel.js

@@ -0,0 +1,942 @@
+import { linear } from "./compat.js";
+export const PIXEL_PROFILE_FORMAT = "pixel-profile/0.1";
+export const PIXEL_IMAGE_FORMAT = "pixel-image/0.1";
+/** Upper bound on logical width or height. */
+export const PIXEL_MAX_DIMENSION = 2048;
+/** Upper bound on supersamples (width * height * samples^2) per render. */
+export const PIXEL_MAX_SUBSAMPLES = 16_777_216;
+const steps = (outline, deep, shadow, light) => [
+    { dL: outline, hueShift: -26, chroma: 0.9, minChroma: 0.02 },
+    { dL: deep, hueShift: -18, chroma: 1.12, minChroma: 0.015 },
+    { dL: shadow, hueShift: -10, chroma: 1.08, minChroma: 0.01 },
+    { dL: 0, hueShift: 0, chroma: 1, minChroma: 0 },
+    { dL: light, hueShift: 8, chroma: 0.9, minChroma: 0 },
+];
+const base = {
+    format: PIXEL_PROFILE_FORMAT,
+    coolHue: 275,
+    warmHue: 85,
+    light: { right: -0.25, up: 0.6, back: 0.75 },
+    topBias: 0.15,
+    bands: [0.72, 0.25, -0.2],
+    outlineColor: "#1f1b24",
+    depthGap: 0.015,
+    frontVotes: 0.5,
+    sliverThinness: 0.4,
+    accentArea: 10,
+    featureWeight: 8,
+    orphanCleanup: true,
+};
+/**
+ * Built-in profiles, after a survey of itch.io environment packs (see
+ * docs/pixel-art.md). Experimental; none has owner visual acceptance.
+ */
+export const PIXEL_PROFILES = Object.freeze({
+    /** Dioramas and rooms: coloured 1 px outlines, occlusion lines, four tones, 32 colours. */
+    scene: Object.freeze({
+        ...base,
+        name: "scene",
+        outline: "coloured",
+        innerLines: true,
+        steps: steps(-0.36, -0.21, -0.1, 0.085),
+        tones: 4,
+        paletteCap: 32,
+        patternMinPixels: 4,
+    }),
+    /** Denser towns and interiors: gentler chroma, four tones, 64 colours, finer patterns. */
+    fantasy: Object.freeze({
+        ...base,
+        name: "fantasy",
+        outline: "coloured",
+        innerLines: true,
+        steps: steps(-0.32, -0.18, -0.09, 0.075).map((step) => ({
+            ...step,
+            chroma: 1 + (step.chroma - 1) * 0.5,
+        })),
+        tones: 4,
+        paletteCap: 64,
+        patternMinPixels: 3,
+    }),
+    /** Readable shapes: three tones with strong value separation and one dark line colour. */
+    arcade: Object.freeze({
+        ...base,
+        name: "arcade",
+        outline: "dark",
+        innerLines: true,
+        steps: steps(-0.4, -0.2, -0.16, 0.11),
+        tones: 3,
+        paletteCap: 32,
+        patternMinPixels: 4,
+    }),
+});
+/** Profile, camera and density bundles for the built-in profiles. */
+export const PIXEL_PRESETS = Object.freeze({
+    scene: Object.freeze({ profile: PIXEL_PROFILES.scene, camera: "dimetric", pixelsPerMetre: 32 }),
+    fantasy: Object.freeze({ profile: PIXEL_PROFILES.fantasy, camera: "topDown", pixelsPerMetre: 48 }),
+    arcade: Object.freeze({ profile: PIXEL_PROFILES.arcade, camera: "dimetric", pixelsPerMetre: 32 }),
+});
+const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const normalize = (a) => {
+    const l = Math.hypot(a[0], a[1], a[2]) || 1;
+    return [a[0] / l, a[1] / l, a[2] / l];
+};
+/** Orthographic camera looking from `yaw` (about +Y, from +Z toward +X) and `pitch` above the horizon. */
+export function pixelCamera(yawDegrees, pitchDegrees, name = `yaw${yawDegrees}-pitch${pitchDegrees}`) {
+    if (!Number.isFinite(yawDegrees) || !Number.isFinite(pitchDegrees) || Math.abs(pitchDegrees) >= 90)
+        throw new RangeError("Camera yaw must be finite and pitch strictly between -90 and 90 degrees");
+    const yaw = (yawDegrees * Math.PI) / 180, pitch = (pitchDegrees * Math.PI) / 180;
+    const back = [Math.sin(yaw) * Math.cos(pitch), Math.sin(pitch), Math.cos(yaw) * Math.cos(pitch)];
+    const right = normalize(cross([0, 1, 0], back));
+    return { name, right, up: cross(back, right), back };
+}
+/**
+ * Camera presets. The dimetric presets use a 30 degree pitch at a diagonal
+ * yaw, which projects the ground axes to exact 2:1 pixel slopes.
+ */
+export const PIXEL_CAMERAS = Object.freeze({
+    /** Gallery-facing 2:1 view: the side the library thumbnails show (yaw 135). */
+    dimetric: pixelCamera(135, 30, "dimetric"),
+    dimetricRight: pixelCamera(225, 30, "dimetricRight"),
+    dimetricOpposite: pixelCamera(315, 30, "dimetricOpposite"),
+    dimetricLeft: pixelCamera(45, 30, "dimetricLeft"),
+    /** Front elevation (looking along +Z) with a slight downward tilt, for side-view scenes. */
+    front: pixelCamera(180, 8, "front"),
+    /** Top-down three-quarter view (45 degree elevation) showing tops and front faces. */
+    topDown: pixelCamera(180, 45, "topDown"),
+});
+/**
+ * Rest-pose instances of a compiled asset (instances hidden in rest states are
+ * omitted). `tint` (#rrggbb) multiplies tintable materials, as in meshForAsset.
+ */
+export function pixelInstances(asset, tint = null) {
+    if (tint !== null && !isHex(tint))
+        throw new RangeError("Tint must be #rrggbb");
+    const factor = tint ? [1, 3, 5].map((i) => linear(parseInt(tint.slice(i, i + 2), 16))) : null;
+    return asset.instances.map((i) => {
+        const tinted = factor && asset.materials[i.material]?.tintable;
+        const mesh = tinted
+            ? { ...i.mesh, colors: i.mesh.colors.map((v, n) => v * (factor[n % 3] ?? 1)) }
+            : i.mesh;
+        return { id: i.id, part: i.part, material: i.material, mesh, restPositions: null };
+    });
+}
+/**
+ * Places compiled assets in one scene. Each placement rotates about +Y and
+ * translates its rest meshes; IDs become `<placement>/<instance>` and patterns
+ * stay in each asset's own frame.
+ */
+export function composePixelScene(placements) {
+    const ids = new Set();
+    const out = [];
+    for (const p of placements) {
+        if (ids.has(p.id))
+            throw new RangeError(`Duplicate placement ID ${p.id}`);
+        ids.add(p.id);
+        if (!p.position.every(Number.isFinite) || !Number.isFinite(p.yawDegrees ?? 0))
+            throw new RangeError(`Placement ${p.id} needs a finite position and yaw`);
+        const a = ((p.yawDegrees ?? 0) * Math.PI) / 180, c = Math.cos(a), s = Math.sin(a);
+        for (const inst of pixelInstances(p.asset, p.tint ?? null)) {
+            const src = inst.mesh, positions = new Array(src.positions.length), normals = new Array(src.normals.length);
+            for (let v = 0; v < src.positions.length; v += 3) {
+                const x = src.positions[v] ?? 0, y = src.positions[v + 1] ?? 0, z = src.positions[v + 2] ?? 0;
+                positions[v] = c * x + s * z + p.position[0];
+                positions[v + 1] = y + p.position[1];
+                positions[v + 2] = -s * x + c * z + p.position[2];
+                const nx = src.normals[v] ?? 0, ny = src.normals[v + 1] ?? 0, nz = src.normals[v + 2] ?? 0;
+                normals[v] = c * nx + s * nz;
+                normals[v + 1] = ny;
+                normals[v + 2] = -s * nx + c * nz;
+            }
+            out.push({
+                id: `${p.id}/${inst.id}`,
+                part: inst.part,
+                material: inst.material,
+                mesh: { ...src, positions, normals },
+                restPositions: src.positions,
+            });
+        }
+    }
+    return out;
+}
+const axisIndex = (a) => (a === "x" ? 0 : a === "y" ? 1 : 2);
+const frac = (v) => v - Math.floor(v);
+/**
+ * Smallest undrawn gap of a pattern, in metres. Line-like parts (stripes,
+ * grid lines, mortar) are widened to at least one pixel when drawn, so the
+ * gap between them is what must survive on the grid.
+ */
+function patternGap(p) {
+    switch (p.type) {
+        case "stripes":
+            return (1 - p.width) * p.period;
+        case "checker":
+            return p.period;
+        case "grid":
+            return (1 - p.width) * p.period;
+        case "bricks":
+            return Math.min(p.course, p.length) - p.mortar;
+    }
+}
+/**
+ * Whether a point in the asset's own frame lies on the drawn part of a
+ * pattern. `lineWidth` is the minimum line width in metres (0 for none). The
+ * same function can drive an ordinary 3D renderer as a solid texture.
+ */
+export function samplePixelPattern(p, point, lineWidth = 0) {
+    return patternHit(p, point, lineWidth);
+}
+function patternHit(p, q, lineFloor) {
+    switch (p.type) {
+        case "stripes":
+            return frac(q[axisIndex(p.axis)] / p.period) < Math.max(p.width * p.period, lineFloor) / p.period;
+        case "checker":
+            return ((Math.floor(q[0] / p.period) + Math.floor(q[1] / p.period) + Math.floor(q[2] / p.period)) % 2 !== 0);
+        case "grid": {
+            const w = Math.max(p.width * p.period, lineFloor) / p.period;
+            return p.axes.some((a) => frac(q[axisIndex(a)] / p.period) < w);
+        }
+        case "bricks": {
+            const row = Math.floor(q[1] / p.course), along = q[axisIndex(p.axis)] + (row % 2 !== 0 ? p.length / 2 : 0), across = q[p.axis === "x" ? 2 : 0] + (row % 2 !== 0 ? p.length / 2 : 0), mortar = Math.max(p.mortar, lineFloor);
+            return (frac(q[1] / p.course) * p.course < mortar ||
+                frac(along / p.length) * p.length < mortar ||
+                frac(across / p.length) * p.length < mortar);
+        }
+    }
+}
+export class PixelArtError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(diagnostics.map((d) => `${d.code} ${d.path}: ${d.message}`).join("\n"));
+        this.diagnostics = diagnostics;
+        this.name = "PixelArtError";
+    }
+}
+const isHex = (v) => typeof v === "string" && /^#[0-9a-fA-F]{6}$/.test(v);
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+/** Structural validation of render options. Errors only; render warnings are returned with the image. */
+export function validatePixelOptions(options) {
+    const d = [];
+    const fail = (code, path, message) => d.push({ code, path, message });
+    const ppm = options.pixelsPerMetre ?? 32;
+    if (!finite(ppm) || ppm <= 0 || ppm > 512)
+        fail("PIXEL_DENSITY", "/pixelsPerMetre", "Expected a density in (0, 512]");
+    const samples = options.samples ?? 4;
+    if (!Number.isInteger(samples) || samples < 1 || samples > 4)
+        fail("PIXEL_SAMPLES", "/samples", "Expected an integer from 1 to 4");
+    const margin = options.margin ?? 4;
+    if (!Number.isInteger(margin) || margin < 0 || margin > 256)
+        fail("PIXEL_MARGIN", "/margin", "Expected an integer from 0 to 256");
+    if (options.frame) {
+        const f = options.frame;
+        if (!f.center.every(finite))
+            fail("PIXEL_FRAME", "/frame/center", "Expected a finite point");
+        for (const k of ["width", "height"])
+            if (!Number.isInteger(f[k]) || f[k] < 1 || f[k] > PIXEL_MAX_DIMENSION)
+                fail("PIXEL_FRAME", `/frame/${k}`, `Expected an integer from 1 to ${PIXEL_MAX_DIMENSION}`);
+    }
+    if (options.camera) {
+        const { right, up, back } = options.camera;
+        const unit = (v) => v.every(finite) && Math.abs(Math.hypot(v[0], v[1], v[2]) - 1) < 1e-6;
+        if (!unit(right) ||
+            !unit(up) ||
+            !unit(back) ||
+            Math.abs(dot(right, up)) > 1e-6 ||
+            Math.abs(dot(right, back)) > 1e-6 ||
+            Math.abs(dot(up, back)) > 1e-6)
+            fail("PIXEL_CAMERA", "/camera", "Camera basis must be finite and orthonormal");
+    }
+    if (options.background !== undefined && options.background !== null && !isHex(options.background))
+        fail("PIXEL_COLOR", "/background", "Expected #rrggbb or null");
+    const profile = options.profile;
+    if (profile) {
+        if (profile.format !== PIXEL_PROFILE_FORMAT)
+            fail("PIXEL_PROFILE", "/profile/format", `Expected ${PIXEL_PROFILE_FORMAT}`);
+        if (profile.steps.length !== 5)
+            fail("PIXEL_PROFILE", "/profile/steps", "Expected five ramp steps");
+        const b = profile.bands;
+        if (!(b[0] > b[1] && b[1] > b[2]))
+            fail("PIXEL_PROFILE", "/profile/bands", "Band thresholds must descend");
+        if (!["coloured", "dark", "none"].includes(profile.outline))
+            fail("PIXEL_PROFILE", "/profile/outline", "Unknown outline mode");
+        if (!isHex(profile.outlineColor))
+            fail("PIXEL_COLOR", "/profile/outlineColor", "Expected #rrggbb");
+        if (profile.tones !== 3 && profile.tones !== 4)
+            fail("PIXEL_PROFILE", "/profile/tones", "Expected 3 or 4");
+        if (profile.paletteCap !== null &&
+            (!Number.isInteger(profile.paletteCap) || profile.paletteCap < 4 || profile.paletteCap > 256))
+            fail("PIXEL_PROFILE", "/profile/paletteCap", "Expected null or an integer from 4 to 256");
+    }
+    (options.surfaces ?? []).forEach((s, i) => {
+        const path = `/surfaces/${i}`;
+        if (!isHex(s.color))
+            fail("PIXEL_COLOR", `${path}/color`, "Expected #rrggbb");
+        if (typeof s.material !== "string" || !s.material)
+            fail("PIXEL_PATTERN", `${path}/material`, "Expected a material name");
+        const p = s.pattern;
+        const positive = (v, name) => {
+            if (!finite(v) || v <= 0 || v > 100)
+                fail("PIXEL_PATTERN", `${path}/pattern/${name}`, "Expected a positive length up to 100 m");
+        };
+        const share = (v, name) => {
+            if (!finite(v) || v <= 0 || v >= 1)
+                fail("PIXEL_PATTERN", `${path}/pattern/${name}`, "Expected a share strictly between 0 and 1");
+        };
+        if (p.type === "stripes") {
+            positive(p.period, "period");
+            share(p.width, "width");
+            if (!["x", "y", "z"].includes(p.axis))
+                fail("PIXEL_PATTERN", `${path}/pattern/axis`, "Expected x, y or z");
+        }
+        else if (p.type === "checker")
+            positive(p.period, "period");
+        else if (p.type === "grid") {
+            positive(p.period, "period");
+            share(p.width, "width");
+            if (!p.axes.length || p.axes.some((a) => !["x", "y", "z"].includes(a)))
+                fail("PIXEL_PATTERN", `${path}/pattern/axes`, "Expected one or more of x, y, z");
+        }
+        else if (p.type === "bricks") {
+            positive(p.course, "course");
+            positive(p.length, "length");
+            positive(p.mortar, "mortar");
+            if (finite(p.mortar) && (p.mortar >= p.course || p.mortar >= p.length))
+                fail("PIXEL_PATTERN", `${path}/pattern/mortar`, "Mortar must be thinner than courses and bricks");
+            if (!["x", "z"].includes(p.axis))
+                fail("PIXEL_PATTERN", `${path}/pattern/axis`, "Expected x or z");
+        }
+        else
+            fail("PIXEL_PATTERN", `${path}/pattern/type`, "Unknown pattern type");
+    });
+    return d;
+}
+// ---------- colour ----------
+const toSrgb = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+/** Linear sRGB to OKLab (Ottosson 2020). */
+export function linearToOklab(rgb) {
+    const [r, g, b] = rgb;
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    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,
+    ];
+}
+/** OKLab to linear sRGB. */
+export function oklabToLinear(lab) {
+    const [L, a, b] = lab;
+    const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    return [
+        4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    ];
+}
+function oklchToSrgb8(L, C, h) {
+    for (let c = C;; c *= 0.95) {
+        const rad = (h * Math.PI) / 180;
+        const lin = oklabToLinear([L, c * Math.cos(rad), c * Math.sin(rad)]);
+        if (lin.every((v) => v >= -1e-7 && v <= 1 + 1e-7) || c < 1e-4) {
+            const [r, g, b] = lin.map((v) => Math.round(255 * toSrgb(Math.min(1, Math.max(0, v)))));
+            return [r ?? 0, g ?? 0, b ?? 0];
+        }
+    }
+}
+const hexToLinear = (hex) => [
+    toLinear(parseInt(hex.slice(1, 3), 16) / 255),
+    toLinear(parseInt(hex.slice(3, 5), 16) / 255),
+    toLinear(parseInt(hex.slice(5, 7), 16) / 255),
+];
+const toHex = (c) => "#" + c.map((v) => v.toString(16).padStart(2, "0")).join("");
+const towards = (h, target, amount) => {
+    const d = ((target - h + 540) % 360) - 180;
+    return (h + Math.sign(d) * Math.min(Math.abs(d), amount) + 360) % 360;
+};
+/** Ramp step indices. */
+export const PIXEL_RAMP = Object.freeze({ outline: 0, deep: 1, shadow: 2, mid: 3, light: 4 });
+/** Five-step hue-shifted ramp (#rrggbb) for a linear-sRGB colour. */
+export function pixelRamp(linearRgb, profile = PIXEL_PROFILES.scene) {
+    return rampRgb(linearRgb, profile).map(toHex);
+}
+function rampRgb(linearRgb, profile) {
+    const [L0, a, b] = linearToOklab(linearRgb);
+    const C0 = Math.hypot(a, b);
+    const h0 = C0 < 1e-6 ? profile.coolHue : ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360;
+    return profile.steps.map(({ dL, hueShift, chroma, minChroma }) => {
+        const h = hueShift === 0 ? h0 : towards(h0, hueShift < 0 ? profile.coolHue : profile.warmHue, Math.abs(hueShift));
+        return oklchToSrgb8(Math.min(0.97, Math.max(0.1, L0 + dL)), Math.max(C0 * chroma, minChroma), h);
+    });
+}
+/** Instance and part under a pixel, or null for background and out-of-range coordinates. */
+export function pickPixel(image, x, y) {
+    if (!Number.isInteger(x) || !Number.isInteger(y) || x < 0 || y < 0 || x >= image.width || y >= image.height)
+        return null;
+    const o = image.owners[y * image.width + x] ?? -1;
+    const inst = o >= 0 ? image.instances[o] : null;
+    return inst ? { id: inst.id, part: inst.part } : null;
+}
+// ---------- rendering ----------
+const N4 = [
+    [-1, 0],
+    [1, 0],
+    [0, -1],
+    [0, 1],
+];
+const isAsset = (s) => !Array.isArray(s);
+/** Renders an asset or a composed scene to pixel art. Throws PixelArtError on invalid options or empty input. */
+export function renderPixelArt(source, options = {}) {
+    const errors = validatePixelOptions(options);
+    const instances = isAsset(source) ? pixelInstances(source) : source;
+    if (!instances.length || instances.every((i) => !i.mesh.indices.length))
+        errors.push({ code: "PIXEL_EMPTY", path: "", message: "Nothing to render" });
+    for (const [n, inst] of instances.entries()) {
+        const m = inst.mesh;
+        if (m.positions.length % 3 ||
+            m.normals.length !== m.positions.length ||
+            m.colors.length !== m.positions.length ||
+            m.indices.length % 3 ||
+            m.indices.some((i) => !Number.isInteger(i) || i < 0 || i >= m.positions.length / 3) ||
+            !m.positions.every(Number.isFinite) ||
+            (inst.restPositions && inst.restPositions.length !== m.positions.length))
+            errors.push({ code: "PIXEL_MESH", path: `/instances/${n}`, message: `Invalid mesh for ${inst.id}` });
+    }
+    if (errors.length)
+        throw new PixelArtError(errors);
+    const profile = options.profile ?? PIXEL_PROFILES.scene, camera = options.camera ?? requireCamera("dimetric"), ppm = options.pixelsPerMetre ?? 32, s = options.samples ?? 4, margin = options.margin ?? 4, features = new Set(options.features ?? []), warnings = [];
+    // Surfaces whose smallest feature is below the grid are suppressed, not drawn broken.
+    const surfaces = (options.surfaces ?? []).filter((surface, i) => {
+        const px = patternGap(surface.pattern) * ppm;
+        if (px >= profile.patternMinPixels)
+            return true;
+        warnings.push({
+            code: "PIXEL_PATTERN_BELOW_GRID",
+            path: `/surfaces/${i}`,
+            message: `Pattern gap is ${px.toFixed(2)} px at ${ppm} px/m; minimum is ${profile.patternMinPixels} px`,
+        });
+        return false;
+    });
+    const surfaceOf = instances.map((inst) => surfaces.findIndex((x) => x.material === inst.material &&
+        (x.scope === undefined || x.scope === null || inst.id.startsWith(`${x.scope}/`))));
+    // Projection and canvas.
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    for (const { mesh } of instances)
+        for (let v = 0; v < mesh.positions.length; v += 3) {
+            const p = [mesh.positions[v] ?? 0, mesh.positions[v + 1] ?? 0, mesh.positions[v + 2] ?? 0];
+            const x = dot(p, camera.right), y = dot(p, camera.up);
+            minX = Math.min(minX, x);
+            maxX = Math.max(maxX, x);
+            minY = Math.min(minY, y);
+            maxY = Math.max(maxY, y);
+        }
+    let width, height, originX, originY;
+    if (options.frame) {
+        width = options.frame.width;
+        height = options.frame.height;
+        originX = dot(options.frame.center, camera.right) - width / 2 / ppm;
+        originY = dot(options.frame.center, camera.up) + height / 2 / ppm;
+    }
+    else {
+        width = Math.ceil((maxX - minX) * ppm) + 2 * margin;
+        height = Math.ceil((maxY - minY) * ppm) + 2 * margin;
+        // Centre the content; snap the origin to whole pixels so equal inputs align.
+        originX = minX - Math.floor((width - (maxX - minX) * ppm) / 2) / ppm;
+        originY = maxY + Math.floor((height - (maxY - minY) * ppm) / 2) / ppm;
+    }
+    if (width > PIXEL_MAX_DIMENSION ||
+        height > PIXEL_MAX_DIMENSION ||
+        width * height * s * s > PIXEL_MAX_SUBSAMPLES)
+        throw new PixelArtError([
+            {
+                code: "PIXEL_BUDGET",
+                path: "/pixelsPerMetre",
+                message: `Canvas ${width}x${height} at ${s}x${s} samples exceeds the render budget`,
+            },
+        ]);
+    // Pass 1: supersampled owner, depth, normal and pattern buffers.
+    const W = width * s, H = height * s, k = ppm * s, lineFloor = 1 / ppm;
+    const owner = new Int32Array(W * H).fill(-1), depth = new Float64Array(W * H).fill(-Infinity), normal = new Float32Array(W * H * 3), pattern = new Uint8Array(W * H);
+    for (const [id, inst] of instances.entries()) {
+        const m = inst.mesh, rest = inst.restPositions ?? m.positions, n = m.positions.length / 3, surface = surfaces[surfaceOf[id] ?? -1] ?? null;
+        const sx = new Float64Array(n), sy = new Float64Array(n), sz = new Float64Array(n);
+        for (let v = 0; v < n; v++) {
+            const p = [m.positions[3 * v] ?? 0, m.positions[3 * v + 1] ?? 0, m.positions[3 * v + 2] ?? 0];
+            sx[v] = (dot(p, camera.right) - originX) * k;
+            sy[v] = (originY - dot(p, camera.up)) * k;
+            sz[v] = dot(p, camera.back);
+        }
+        for (let t = 0; t < m.indices.length; t += 3) {
+            const a = m.indices[t] ?? 0, b = m.indices[t + 1] ?? 0, c = m.indices[t + 2] ?? 0;
+            const ax = sx[a] ?? 0, ay = sy[a] ?? 0, bx = sx[b] ?? 0, by = sy[b] ?? 0, cx = sx[c] ?? 0, cy = sy[c] ?? 0;
+            const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+            if (Math.abs(area) < 1e-12)
+                continue;
+            const x0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), x1 = Math.min(W - 1, Math.ceil(Math.max(ax, bx, cx)));
+            const y0 = Math.max(0, Math.floor(Math.min(ay, by, cy))), y1 = Math.min(H - 1, Math.ceil(Math.max(ay, by, cy)));
+            for (let y = y0; y <= y1; y++)
+                for (let x = x0; x <= x1; x++) {
+                    const px = x + 0.5, py = y + 0.5;
+                    const wa = ((bx - px) * (cy - py) - (by - py) * (cx - px)) / area;
+                    const wb = ((cx - px) * (ay - py) - (cy - py) * (ax - px)) / area;
+                    const wc = 1 - wa - wb;
+                    if (wa < -1e-9 || wb < -1e-9 || wc < -1e-9)
+                        continue;
+                    const d = wa * (sz[a] ?? 0) + wb * (sz[b] ?? 0) + wc * (sz[c] ?? 0), at = y * W + x;
+                    if (d <= (depth[at] ?? -Infinity))
+                        continue;
+                    depth[at] = d;
+                    owner[at] = id;
+                    for (let j = 0; j < 3; j++)
+                        normal[3 * at + j] =
+                            wa * (m.normals[3 * a + j] ?? 0) +
+                                wb * (m.normals[3 * b + j] ?? 0) +
+                                wc * (m.normals[3 * c + j] ?? 0);
+                    if (surface) {
+                        const r = (j) => wa * (rest[3 * a + j] ?? 0) + wb * (rest[3 * b + j] ?? 0) + wc * (rest[3 * c + j] ?? 0);
+                        const q = [r(0), r(1), r(2)];
+                        pattern[at] = patternHit(surface.pattern, q, lineFloor) ? 1 : 0;
+                    }
+                    else
+                        pattern[at] = 0;
+                }
+        }
+    }
+    // Pass 2: one owner per pixel; declared features win at >= 1/8 coverage.
+    const size = width * height, pxOwner = new Int32Array(size).fill(-1), minFeature = Math.ceil((s * s) / 8), count = new Map();
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            count.clear();
+            let background = 0;
+            for (let j = 0; j < s; j++)
+                for (let i = 0; i < s; i++) {
+                    const o = owner[(y * s + j) * W + x * s + i] ?? -1;
+                    if (o < 0)
+                        background++;
+                    else
+                        count.set(o, (count.get(o) ?? 0) + 1);
+                }
+            let best = -1, score = 0;
+            for (const [o, n] of [...count].sort((p, q) => p[0] - q[0])) {
+                const feature = features.has(instances[o]?.part ?? "");
+                const sc = feature && n >= minFeature ? n * profile.featureWeight : n;
+                if (sc > score) {
+                    score = sc;
+                    best = o;
+                }
+            }
+            if (best >= 0 && background <= score)
+                pxOwner[y * width + x] = best;
+        }
+    // Pass 3: faces (owner subsamples grouped by rounded normal); drop slivers; majority face per pixel.
+    const faceKey = (q) => Math.round((normal[3 * q] ?? 0) * 10) * 441 +
+        Math.round((normal[3 * q + 1] ?? 0) * 10) * 21 +
+        Math.round((normal[3 * q + 2] ?? 0) * 10);
+    const cellFaces = (x, y, o) => {
+        const faces = new Map();
+        for (let j = 0; j < s; j++)
+            for (let i = 0; i < s; i++) {
+                const q = (y * s + j) * W + x * s + i;
+                if (owner[q] !== o)
+                    continue;
+                const key = faceKey(q);
+                let f = faces.get(key);
+                if (!f) {
+                    f = { n: 0, nx: 0, ny: 0, nz: 0, hits: 0, flat: true, first: q };
+                    faces.set(key, f);
+                }
+                f.n++;
+                f.nx += normal[3 * q] ?? 0;
+                f.ny += normal[3 * q + 1] ?? 0;
+                f.nz += normal[3 * q + 2] ?? 0;
+                f.hits += pattern[q] ?? 0;
+                for (let c = 0; c < 3; c++)
+                    if (Math.abs((normal[3 * q + c] ?? 0) - (normal[3 * f.first + c] ?? 0)) > 1e-5)
+                        f.flat = false;
+            }
+        return [...faces].sort((p, q) => p[0] - q[0]);
+    };
+    // A face is flat only if every subsample in every pixel shares the first
+    // subsample's normal; comparing within one pixel is not enough, because a
+    // curved surface can leave a single sample of a normal bin per pixel.
+    const faceStats = new Map();
+    const sameNormal = (a, b) => Math.abs((normal[3 * a] ?? 0) - (normal[3 * b] ?? 0)) <= 1e-5 &&
+        Math.abs((normal[3 * a + 1] ?? 0) - (normal[3 * b + 1] ?? 0)) <= 1e-5 &&
+        Math.abs((normal[3 * a + 2] ?? 0) - (normal[3 * b + 2] ?? 0)) <= 1e-5;
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const o = pxOwner[y * width + x] ?? -1;
+            if (o < 0)
+                continue;
+            for (const [key, f] of cellFaces(x, y, o)) {
+                const id = `${o}|${key}`, st = faceStats.get(id) ?? { samples: 0, touched: 0, flat: true, ref: f.first };
+                st.samples += f.n;
+                st.touched++;
+                st.flat &&= f.flat && sameNormal(st.ref, f.first);
+                faceStats.set(id, st);
+            }
+        }
+    // Only flat faces can be slivers; curved surfaces are split into normal bins artificially.
+    const sliver = new Set();
+    for (const [id, st] of faceStats)
+        if (st.flat && st.touched >= 3 && st.samples / (s * s) / st.touched < profile.sliverThinness)
+            sliver.add(id);
+    const pxNormal = new Float64Array(size * 3), pxPattern = new Uint8Array(size);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const at = y * width + x, o = pxOwner[at] ?? -1;
+            if (o < 0)
+                continue;
+            const faces = cellFaces(x, y, o);
+            const eligible = faces.filter(([key]) => !sliver.has(`${o}|${key}`));
+            let chosen = null;
+            for (const [, f] of eligible.length ? eligible : faces)
+                if (!chosen || f.n > chosen.n)
+                    chosen = f;
+            if (!chosen)
+                continue;
+            const len = Math.hypot(chosen.nx, chosen.ny, chosen.nz) || 1;
+            pxNormal[3 * at] = chosen.nx / len;
+            pxNormal[3 * at + 1] = chosen.ny / len;
+            pxNormal[3 * at + 2] = chosen.nz / len;
+            pxPattern[at] = 2 * chosen.hits >= chosen.n ? 1 : 0;
+        }
+    // Pass 4: which part is in front of which, decided once per pair from subsample votes.
+    const front = new Set();
+    if (profile.innerLines) {
+        const votes = new Map();
+        const sameFace = (a, b) => (normal[3 * a] ?? 0) * (normal[3 * b] ?? 0) +
+            (normal[3 * a + 1] ?? 0) * (normal[3 * b + 1] ?? 0) +
+            (normal[3 * a + 2] ?? 0) * (normal[3 * b + 2] ?? 0) >
+            0.9;
+        const extrapolate = (a, c) => owner[c] === owner[a] && sameFace(a, c)
+            ? (depth[a] ?? 0) + ((depth[a] ?? 0) - (depth[c] ?? 0)) * 0.5
+            : (depth[a] ?? 0);
+        const tally = (a, b, aPrev, bNext) => {
+            const oa = owner[a] ?? -1, ob = owner[b] ?? -1;
+            if (oa < 0 || ob < 0 || oa === ob)
+                return;
+            const da = extrapolate(a, aPrev), db = extrapolate(b, bNext);
+            const lo = Math.min(oa, ob), key = `${lo},${Math.max(oa, ob)}`, v = votes.get(key) ?? { total: 0, ab: 0, ba: 0 };
+            v.total++;
+            // ab: the lower-indexed owner is in front.
+            const lowDepth = oa === lo ? da : db, highDepth = oa === lo ? db : da;
+            if (lowDepth - highDepth > profile.depthGap)
+                v.ab++;
+            else if (highDepth - lowDepth > profile.depthGap)
+                v.ba++;
+            votes.set(key, v);
+        };
+        for (let y = 0; y < H; y++)
+            for (let x = 0; x < W; x++) {
+                const a = y * W + x;
+                if (x + 1 < W)
+                    tally(a, a + 1, x > 0 ? a - 1 : a, x + 2 < W ? a + 2 : a + 1);
+                if (y + 1 < H)
+                    tally(a, a + W, y > 0 ? a - W : a, y + 2 < H ? a + 2 * W : a + W);
+            }
+        for (const [key, v] of votes) {
+            const [lo, hi] = key.split(",");
+            if (v.ab >= profile.frontVotes * v.total)
+                front.add(`${lo},${hi}`);
+            else if (v.ba >= profile.frontVotes * v.total)
+                front.add(`${hi},${lo}`);
+        }
+    }
+    // Pass 5: bands, lines, cleanup and colour.
+    const ramps = new Map();
+    const rampFor = (linear) => {
+        const key = linear.join(",");
+        let r = ramps.get(key);
+        if (!r) {
+            r = rampRgb(linear, profile);
+            ramps.set(key, r);
+        }
+        return r;
+    };
+    const baseOf = instances.map((inst) => [
+        inst.mesh.colors[0] ?? 0,
+        inst.mesh.colors[1] ?? 0,
+        inst.mesh.colors[2] ?? 0,
+    ]);
+    const patternLinear = surfaces.map((x) => hexToLinear(x.color));
+    const declaredSurfaces = options.surfaces ?? [];
+    const area = new Map();
+    for (const o of pxOwner)
+        if (o >= 0)
+            area.set(o, (area.get(o) ?? 0) + 1);
+    const lightAxis = (i) => profile.light.right * camera.right[i] +
+        profile.light.up * camera.up[i] +
+        profile.light.back * camera.back[i];
+    const L = normalize([lightAxis(0), lightAxis(1), lightAxis(2)]);
+    const band = new Int8Array(size).fill(-1);
+    for (let at = 0; at < size; at++) {
+        if ((pxOwner[at] ?? -1) < 0)
+            continue;
+        const n = [pxNormal[3 * at] ?? 0, pxNormal[3 * at + 1] ?? 0, pxNormal[3 * at + 2] ?? 0];
+        const v = dot(n, L) + profile.topBias * n[1];
+        band[at] =
+            v >= profile.bands[0]
+                ? 4
+                : v >= profile.bands[1]
+                    ? 3
+                    : v >= profile.bands[2] || profile.tones === 3
+                        ? 2
+                        : 1;
+    }
+    // Out-of-canvas neighbours are skipped: a crop edge is not a silhouette.
+    const neighbours = (at, visit) => {
+        const x = at % width, y = (at - x) / width;
+        for (const [dx, dy] of N4) {
+            const qx = x + dx, qy = y + dy;
+            if (qx >= 0 && qy >= 0 && qx < width && qy < height)
+                visit(qy * width + qx);
+        }
+    };
+    // 0 fill, 1 outline, 2 inner line, 3 accent.
+    const kind = new Int8Array(size).fill(-1);
+    for (let at = 0; at < size; at++) {
+        const o = pxOwner[at] ?? -1;
+        if (o < 0)
+            continue;
+        if ((area.get(o) ?? 0) <= profile.accentArea || features.has(instances[o]?.part ?? "")) {
+            kind[at] = 3;
+            continue;
+        }
+        let exterior = false, inner = false;
+        neighbours(at, (q) => {
+            const b = pxOwner[q] ?? -1;
+            if (b < 0)
+                exterior = true;
+            else if (b !== o && front.has(`${o},${b}`))
+                inner = true;
+        });
+        kind[at] = exterior && profile.outline !== "none" ? 1 : inner ? 2 : 0;
+    }
+    const cleaned = band.slice();
+    let orphansCleaned = 0;
+    if (profile.orphanCleanup)
+        for (let at = 0; at < size; at++) {
+            if (kind[at] !== 0)
+                continue;
+            let n = 0, agreed = -1, uniform = true;
+            neighbours(at, (q) => {
+                if (pxOwner[q] !== pxOwner[at] || kind[q] !== 0 || pxPattern[q] !== pxPattern[at])
+                    return;
+                n++;
+                if (agreed < 0)
+                    agreed = band[q] ?? -1;
+                else if (band[q] !== agreed)
+                    uniform = false;
+            });
+            if (n >= 2 && uniform && agreed !== band[at]) {
+                cleaned[at] = agreed;
+                orphansCleaned++;
+            }
+        }
+    const outlineRgb = [
+        parseInt(profile.outlineColor.slice(1, 3), 16),
+        parseInt(profile.outlineColor.slice(3, 5), 16),
+        parseInt(profile.outlineColor.slice(5, 7), 16),
+    ];
+    const background = options.background ?? null;
+    const bg = background
+        ? [
+            parseInt(background.slice(1, 3), 16),
+            parseInt(background.slice(3, 5), 16),
+            parseInt(background.slice(5, 7), 16),
+        ]
+        : null;
+    const rgba = new Uint8Array(size * 4), roles = new Int8Array(size).fill(-1);
+    const stats = {
+        outline: 0,
+        inner: 0,
+        accent: 0,
+        fill: 0,
+        pattern: 0,
+        orphansCleaned,
+        sliverFaces: sliver.size,
+        frontPairs: front.size,
+    };
+    // Scene palette from every input colour (not visible pixels), so all views agree.
+    const candidates = new Map();
+    // Typical use of each ramp step: mid tones cover most pixels, outlines the fewest.
+    const stepUse = [0.15, 0.4, 0.7, 1, 0.7];
+    const addRamp = (ramp, weight) => {
+        ramp.forEach((c, step) => {
+            const key = toHex(c), w = weight * (ramp.length === stepUse.length ? (stepUse[step] ?? 1) : 1), e = candidates.get(key);
+            if (e)
+                e.weight += w;
+            else
+                candidates.set(key, { rgb: c, weight: w });
+        });
+    };
+    // Weight by surface area, so a large ground keeps its colours against many small parts.
+    let totalArea = 0;
+    for (const [o, inst] of instances.entries()) {
+        const m = inst.mesh;
+        let area = 0;
+        for (let t = 0; t < m.indices.length; t += 3) {
+            const [a, b, c] = [m.indices[t] ?? 0, m.indices[t + 1] ?? 0, m.indices[t + 2] ?? 0];
+            const p = (v) => [
+                m.positions[3 * v] ?? 0,
+                m.positions[3 * v + 1] ?? 0,
+                m.positions[3 * v + 2] ?? 0,
+            ];
+            const [pa, pb, pc] = [p(a), p(b), p(c)];
+            const n = cross([pb[0] - pa[0], pb[1] - pa[1], pb[2] - pa[2]], [pc[0] - pa[0], pc[1] - pa[1], pc[2] - pa[2]]);
+            area += Math.hypot(n[0], n[1], n[2]) / 2;
+        }
+        totalArea += area;
+        // Every declared surface counts, including ones suppressed at this density,
+        // so the palette does not depend on pixels per metre or framing.
+        const declared = declaredSurfaces.findIndex((x) => x.material === inst.material &&
+            (x.scope === undefined || x.scope === null || inst.id.startsWith(`${x.scope}/`)));
+        addRamp(rampFor(baseOf[o] ?? [0, 0, 0]), declared >= 0 ? area / 2 : area);
+        if (declared >= 0)
+            addRamp(rampFor(hexToLinear(declaredSurfaces[declared]?.color ?? "#000000")), area / 2);
+    }
+    if (profile.outline === "dark")
+        addRamp([outlineRgb], totalArea);
+    const mapped = profile.paletteCap === null ? null : capPalette(candidates, profile.paletteCap);
+    const palette = new Set();
+    for (let at = 0; at < size; at++) {
+        const o = pxOwner[at] ?? -1;
+        if (o < 0) {
+            if (bg)
+                rgba.set([...bg, 255], 4 * at);
+            continue;
+        }
+        const own = rampFor(baseOf[o] ?? [0, 0, 0]);
+        const patterned = pxPattern[at] === 1 && (surfaceOf[o] ?? -1) >= 0;
+        const fillRamp = patterned ? rampFor(patternLinear[surfaceOf[o] ?? 0] ?? [0, 0, 0]) : own;
+        let role, color;
+        const k2 = kind[at];
+        if (k2 === 3) {
+            role = Math.min(4, Math.max(3, (band[at] ?? 3) + 1));
+            color = fillRamp[role] ?? [0, 0, 0];
+            stats.accent++;
+        }
+        else if (k2 === 1) {
+            role = 0;
+            color = profile.outline === "dark" ? outlineRgb : (own[0] ?? [0, 0, 0]);
+            stats.outline++;
+        }
+        else if (k2 === 2) {
+            role = 1;
+            color = own[1] ?? [0, 0, 0];
+            stats.inner++;
+        }
+        else {
+            role = cleaned[at] ?? 3;
+            color = fillRamp[role] ?? [0, 0, 0];
+            if (patterned)
+                stats.pattern++;
+            else
+                stats.fill++;
+        }
+        roles[at] = role;
+        if (mapped)
+            color = mapped.get(toHex(color)) ?? color;
+        rgba.set([...color, 255], 4 * at);
+        palette.add(toHex(color));
+    }
+    // Per-pixel depth of the final owner (any covering sample if cleanup reassigned the pixel).
+    const pxDepth = new Float32Array(width * height).fill(NaN);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const o = pxOwner[y * width + x] ?? -1;
+            if (o < 0)
+                continue;
+            let own = -Infinity, any = -Infinity;
+            for (let j = 0; j < s; j++)
+                for (let i = 0; i < s; i++) {
+                    const q = (y * s + j) * W + x * s + i, d = depth[q] ?? -Infinity;
+                    if (d > any)
+                        any = d;
+                    if (owner[q] === o && d > own)
+                        own = d;
+                }
+            const d = own > -Infinity ? own : any;
+            if (d > -Infinity)
+                pxDepth[y * width + x] = d;
+        }
+    return {
+        format: PIXEL_IMAGE_FORMAT,
+        width,
+        height,
+        pixelsPerMetre: ppm,
+        camera: camera.name,
+        profile: profile.name,
+        rgba,
+        owners: pxOwner,
+        roles,
+        depth: pxDepth,
+        instances: instances.map((i) => ({ id: i.id, part: i.part, material: i.material })),
+        palette: [...palette].sort(),
+        stats,
+        warnings,
+    };
+}
+/**
+ * Deterministic palette reduction by weighted maximin selection: start from
+ * the heaviest colour (area times typical step use), then repeatedly add the
+ * candidate with the largest distance to every chosen colour times
+ * (weight / heaviest)^0.25, in OKLab with hue and chroma weighted double.
+ * Chosen colours are real ramp colours, and distinctive hues (a blue roof, a
+ * red sign) survive; every candidate maps to its nearest chosen colour.
+ */
+function capPalette(candidates, cap) {
+    const keys = [...candidates.keys()].sort();
+    const out = new Map();
+    if (keys.length <= cap)
+        return out;
+    const items = keys.map((k) => {
+        const e = candidates.get(k) ?? { rgb: [0, 0, 0], weight: 0 };
+        const lab = linearToOklab([toLinear(e.rgb[0] / 255), toLinear(e.rgb[1] / 255), toLinear(e.rgb[2] / 255)]);
+        return { key: k, rgb: e.rgb, weight: e.weight, lab };
+    });
+    const d2 = (a, b) => (a[0] - b[0]) ** 2 + 4 * (a[1] - b[1]) ** 2 + 4 * (a[2] - b[2]) ** 2;
+    let first = 0;
+    items.forEach((item, i) => {
+        if (item.weight > (items[first]?.weight ?? 0))
+            first = i;
+    });
+    const chosen = [first];
+    const nearest = items.map((item) => d2(item.lab, items[first]?.lab ?? item.lab));
+    const heaviest = items[first]?.weight || 1;
+    const score = (i) => (nearest[i] ?? 0) * ((items[i]?.weight ?? 0) / heaviest) ** 0.25;
+    while (chosen.length < cap) {
+        let far = 0;
+        nearest.forEach((_, i) => {
+            if (score(i) > score(far))
+                far = i;
+        });
+        if (score(far) === 0)
+            break;
+        chosen.push(far);
+        const c = items[far]?.lab ?? [0, 0, 0];
+        items.forEach((item, i) => (nearest[i] = Math.min(nearest[i] ?? Infinity, d2(item.lab, c))));
+    }
+    for (const item of items) {
+        let best = chosen[0] ?? 0;
+        for (const c of chosen)
+            if (d2(item.lab, items[c]?.lab ?? item.lab) < d2(item.lab, items[best]?.lab ?? item.lab))
+                best = c;
+        out.set(item.key, items[best]?.rgb ?? item.rgb);
+    }
+    return out;
+}
+function requireCamera(name) {
+    const c = PIXEL_CAMERAS[name];
+    if (!c)
+        throw new Error(`Missing camera preset ${name}`);
+    return c;
+}