@officexapp/vidfarm-devcli 0.21.35 → 0.21.37

package/dist/src/devcli/plate-key.js

@@ -0,0 +1,698 @@
+// Connectivity-aware plate keying ("smart key") + MULTI-ZONE plates.
+//
+// ── The limitation this removes ───────────────────────────────────────────────
+// A flat chroma key (`chromakey` in ffmpeg, `removeGreenscreenLocal`) deletes
+// every pixel that *looks like* the key color, wherever it is. That single rule
+// is what has been forcing sticker art to stay simple and flat:
+//
+//   • nothing on the art may be the plate color → no green leaves on a green
+//     sheet, no magenta candy on a magenta sheet;
+//   • outline / line-art shapes come back as a rim around a see-through hole,
+//     because their interior was left as bare plate;
+//   • one plate color per SHEET means the whole pack shares one banned hue, so
+//     the more items a sheet holds, the more of the palette is off-limits.
+//
+// None of that is inherent to keying — it's an artifact of treating "matches the
+// key color" as "is background". The background of a sticker sheet has a much
+// stronger, purely geometric definition: it is the plate region that REACHES THE
+// EDGE OF THE SHEET. A green pixel in the middle of a mascot's eye does not, so
+// it isn't background, so it must survive.
+//
+// So this module keys by CONNECTIVITY, not by color alone:
+//   1. score every pixel's distance to its plate color (chroma-only for
+//      chromatic plates, so lighting/gradient on the plate still keys);
+//   2. flood-fill inward from the sheet border through plate-ish pixels;
+//   3. only what the fill REACHES becomes transparent, with a soft ramp across
+//      the loose band at the boundary;
+//   4. unpremultiply the plate out of every partial-alpha pixel (exact math,
+//      per-pixel) instead of running a global `despill` that discolors the art.
+//
+// The direct consequences: plate-colored art interiors survive, hollow/outline
+// art keeps its interior, soft edges and glows feather out to semi-transparency
+// instead of leaving a hard halo, and the art may use ANY color as long as it
+// doesn't bleed into the plate at its own silhouette.
+//
+// ── And then: one plate color per STICKER, not per sheet ──────────────────────
+// The remaining constraint is the silhouette edge: an item whose OUTER edge is
+// the plate color still dissolves into it. That's fixed by dropping the "one
+// plate per sheet" assumption — a sheet is laid out as a grid of colored PANELS,
+// each item on its own panel, each panel a plate color chosen against that
+// item's own colors. A green frog sits on magenta while the pink flower next to
+// it sits on green. `detectPlateZones` recovers that grid from the sheet itself
+// (the panel colors change along the sheet's own edges), so a zoned sheet from a
+// free web generator works the same as one we planned.
+//
+// Bundle-safe: ffmpeg (raw pixel in, raw pixel out) + typed arrays. No backend
+// import, no network, no native dependency.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolveFfmpeg } from "../services/clip-curation/ffmpeg.js";
+import { probeImageDimensions } from "./greenscreen-local.js";
+export function parseHexColor(value) {
+    const hex = /^#?([0-9a-f]{6})$/i.exec(value.trim());
+    if (!hex) {
+        const named = {
+            green: [0, 255, 0], lime: [0, 255, 0], blue: [0, 71, 187], magenta: [255, 0, 255],
+            white: [255, 255, 255], black: [0, 0, 0], red: [255, 0, 0], cyan: [0, 255, 255], yellow: [255, 255, 0]
+        };
+        const hit = named[value.trim().toLowerCase()];
+        if (hit)
+            return hit;
+        throw new Error(`Can't read "${value}" as a color — use a hex like #00FF00.`);
+    }
+    const n = parseInt(hex[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+export function hexOf(rgb) {
+    return `#${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+}
+/** True when a color has enough hue to be keyed on CHROMA alone. Grey/white/
+ *  black plates carry no chroma, so they have to be matched on full RGB. */
+export function isChromatic(rgb) {
+    return Math.max(...rgb) - Math.min(...rgb) >= 40;
+}
+/** Normalized chromaticity (r, g) — the color's ratio, with intensity divided
+ *  out. This is what makes the match brightness-invariant: #00FF00 and a shaded
+ *  #008C00 land on the same point, so an unevenly-lit plate still keys. (ffmpeg's
+ *  chromakey compares raw Cb/Cr instead, which is why IT struggles with a dark
+ *  or vignetted greenscreen.) */
+function chromaticity(r, g, b) {
+    const sum = r + g + b;
+    if (sum <= 0)
+        return [1 / 3, 1 / 3];
+    return [r / sum, g / sum];
+}
+/**
+ * Distance from a pixel to the plate color, normalized so ~0 is an exact match
+ * and 1 is "nothing like it".
+ *
+ * Chromatic plates are matched on CHROMATICITY only, so plate brightness,
+ * gradients, vignetting and the art's own bounce light don't matter. Achromatic
+ * plates (white/black/grey) have no chromaticity to compare — every grey sits at
+ * the same point — so they fall back to full RGB distance, which is also why they
+ * need a much tighter tolerance.
+ */
+export function plateDistance(r, g, b, plate, chromaticPlate) {
+    if (chromaticPlate) {
+        // Very dark pixels have unstable chromaticity (a rounding error swings the
+        // ratio), so never let near-black masquerade as a lit plate.
+        if (r + g + b < 24 && plate[0] + plate[1] + plate[2] >= 60)
+            return 1;
+        const [pr, pg] = chromaticity(plate[0], plate[1], plate[2]);
+        const [cr, cg] = chromaticity(r, g, b);
+        return Math.min(1, Math.sqrt((cr - pr) * (cr - pr) + (cg - pg) * (cg - pg)) / 0.9);
+    }
+    const dr = r - plate[0];
+    const dg = g - plate[1];
+    const db = b - plate[2];
+    return Math.sqrt(dr * dr + dg * dg + db * db) / 441.673;
+}
+/**
+ * Estimate how opaque a boundary pixel really is (its alpha "coverage"), by
+ * unmixing the plate out of it rather than by how far its color drifted.
+ *
+ * A boundary pixel is `C = α·art + (1-α)·plate`, with `art` unknown. Two bounds
+ * fall straight out of `0 ≤ art ≤ 255`:
+ *
+ *   • plate's BRIGHT channels: the plate can only ADD to such a channel, so
+ *     `C_c ≥ (1-α)·plate_c` ⟹ `α ≥ 1 - C_c/plate_c`. The tightest (smallest) of
+ *     those readings is the best estimate of coverage — on green, a 90 %-plate
+ *     pixel reads 0.10 and a 50/50 blend reads 0.42.
+ *   • plate's DARK channels give a lower bound the art alone must account for:
+ *     `C_d = α·art_d ≤ α·255` ⟹ `α ≥ C_d/255`. This is the guard that stops the
+ *     estimate eroding real art — white art on green reads α ≥ 1 and stays solid.
+ *
+ * The distance ramp is kept as a third, coarse upper reading so a pixel that
+ * isn't plate-like at all (black art on green) can never be dragged transparent.
+ */
+export function coverage(rgb, offset, plate, dist, inner, outer) {
+    const c = [rgb[offset], rgb[offset + 1], rgb[offset + 2]];
+    // Coarse ramp on plate distance.
+    let upper = Math.max(0, Math.min(1, (dist - inner) / Math.max(1e-6, outer - inner)));
+    // Tightest bright-channel reading.
+    for (let i = 0; i < 3; i++) {
+        if (plate[i] < 32)
+            continue;
+        upper = Math.min(upper, Math.max(0, 1 - c[i] / plate[i]));
+    }
+    // Dark-channel floor: whatever the plate can't explain must be art.
+    let floor = 0;
+    for (let i = 0; i < 3; i++) {
+        if (plate[i] >= 32)
+            continue;
+        floor = Math.max(floor, c[i] / 255);
+    }
+    return Math.max(0, Math.min(1, Math.max(upper, floor)));
+}
+/**
+ * Turn an observed boundary color back into the ART color for a given coverage:
+ * `C = α·art + (1-α)·plate` ⟹ `art = (C - (1-α)·plate)/α`. PNG/WebP store
+ * straight (unassociated) alpha, so writing the art color with alpha α makes the
+ * composite exact — no plate fringe.
+ *
+ * Strictly better than ffmpeg's global `despill`, which rebalances EVERY pixel
+ * and so discolors plate-hued art in the interior; this only ever touches pixels
+ * that are actually part-plate.
+ */
+function unpremultiplyPlate(rgba, offset, plate, alpha) {
+    if (alpha <= 0 || alpha >= 1)
+        return;
+    for (let c = 0; c < 3; c++) {
+        const v = (rgba[offset + c] - (1 - alpha) * plate[c]) / alpha;
+        rgba[offset + c] = Math.max(0, Math.min(255, Math.round(v)));
+    }
+}
+// Defaults for THIS keyer. Deliberately separate from GREENSCREEN_PRESETS: those
+// numbers are `chromakey`'s similarity/blend, on a different metric. The band is
+// generous on purpose — inside a border-connected fill a wide band only buys
+// softer edges (and feathers glows), it can no longer eat the art's interior.
+export const SMART_KEY_DEFAULTS = {
+    chromatic: { tolerance: 0.16, softness: 0.2 },
+    achromatic: { tolerance: 0.055, softness: 0.08 }
+};
+export function defaultsForPlate(plate) {
+    return isChromatic(plate) ? { ...SMART_KEY_DEFAULTS.chromatic } : { ...SMART_KEY_DEFAULTS.achromatic };
+}
+/** A zone that covers a whole sheet — the "plain single-plate sheet" case. */
+export function singleZone(width, height, hex) {
+    return { x: 0, y: 0, width, height, hex: hex.toUpperCase(), rgb: parseHexColor(hex) };
+}
+/**
+ * Recover a panel grid from the sheet itself.
+ *
+ * A zoned sheet advertises its own layout along its edges: walk the top edge and
+ * the panel colors change at every column boundary; walk the left edge and they
+ * change at every row boundary. So segment both edges into runs of flat color
+ * and take the boundaries. Two guards keep art from faking a boundary:
+ *
+ *   • a run must be at least `minRunPct` of the edge, and
+ *   • a boundary must appear on BOTH opposite edges (top AND bottom for columns,
+ *     left AND right for rows) — art can touch one edge at a given offset, but
+ *     almost never both at the same offset.
+ *
+ * Returns a single full-sheet zone when the sheet is a plain one-color plate
+ * (the common case), or null when the edges are too busy to read at all.
+ */
+export function detectZoneGrid(rgb, w, h, opts = {}) {
+    const tol = opts.tolerance ?? 26;
+    const minRunPct = opts.minRunPct ?? 8;
+    const band = Math.max(1, Math.round(Math.min(w, h) * 0.01));
+    const at = (x, y) => {
+        const i = (y * w + x) * 3;
+        return [rgb[i], rgb[i + 1], rgb[i + 2]];
+    };
+    /** Mean color of a small patch, so JPEG noise doesn't split a run. */
+    const patch = (x, y, sw, sh) => {
+        let r = 0, g = 0, b = 0, n = 0;
+        for (let yy = Math.max(0, y); yy < Math.min(h, y + sh); yy++) {
+            for (let xx = Math.max(0, x); xx < Math.min(w, x + sw); xx++) {
+                const c = at(xx, yy);
+                r += c[0];
+                g += c[1];
+                b += c[2];
+                n++;
+            }
+        }
+        return n ? [r / n, g / n, b / n] : [0, 0, 0];
+    };
+    const near = (a, b) => Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]), Math.abs(a[2] - b[2])) <= tol;
+    /** Split one edge into runs of flat color; returns the run start offsets. */
+    const runsAlong = (axis, offset) => {
+        const span = axis === "x" ? w : h;
+        const minRun = Math.max(2, Math.round((minRunPct / 100) * span));
+        const step = Math.max(1, Math.round(span / 256)); // ~256 samples is plenty
+        // Sample ONE pixel across the axis being walked (averaging only across the
+        // other axis): a patch that straddles a panel seam averages the two panel
+        // colors and reads as a third "run".
+        const sample = (p) => (axis === "x" ? patch(p, offset, 1, band) : patch(offset, p, band, 1));
+        const starts = [0];
+        let runColor = sample(0);
+        let runStart = 0;
+        for (let p = step; p < span; p += step) {
+            const c = sample(p);
+            if (near(c, runColor))
+                continue;
+            // A change only counts once the PREVIOUS run was long enough to be a panel;
+            // otherwise it's art brushing the edge and we stay in the current run.
+            if (p - runStart >= minRun) {
+                starts.push(p);
+                runStart = p;
+                // Re-read the new run's color a little past the seam, clear of any
+                // antialiasing on the boundary itself.
+                runColor = sample(Math.min(span - 1, p + Math.max(1, band)));
+            }
+        }
+        // Drop a trailing sliver (art at the far edge, or a 1px border artifact).
+        while (starts.length > 1 && span - starts[starts.length - 1] < minRun)
+            starts.pop();
+        return starts;
+    };
+    /** Keep only boundaries that BOTH opposite edges agree on. */
+    const agree = (a, b, span) => {
+        const slack = Math.max(4, Math.round(span * 0.04));
+        const out = [0];
+        for (const v of a.slice(1)) {
+            const match = b.slice(1).find((u) => Math.abs(u - v) <= slack);
+            if (match !== undefined)
+                out.push(Math.round((v + match) / 2));
+        }
+        return out;
+    };
+    const inset = band;
+    const colStarts = agree(runsAlong("x", inset), runsAlong("x", h - 1 - inset), w);
+    const rowStarts = agree(runsAlong("y", inset), runsAlong("y", w - 1 - inset), h);
+    const zones = [];
+    for (let ri = 0; ri < rowStarts.length; ri++) {
+        const y0 = rowStarts[ri];
+        const y1 = ri + 1 < rowStarts.length ? rowStarts[ri + 1] : h;
+        for (let ci = 0; ci < colStarts.length; ci++) {
+            const x0 = colStarts[ci];
+            const x1 = ci + 1 < colStarts.length ? colStarts[ci + 1] : w;
+            const zw = x1 - x0;
+            const zh = y1 - y0;
+            if (zw < 8 || zh < 8)
+                return null;
+            // Read the panel's plate color from ITS OWN four corners — the art lives in
+            // the middle, so corners are plate. The median of the four survives one
+            // corner being clipped by a wide item.
+            const p = Math.max(2, Math.round(Math.min(zw, zh) * 0.02));
+            const s = Math.max(3, Math.round(Math.min(zw, zh) * 0.03));
+            const corners = [
+                patch(x0 + p, y0 + p, s, s),
+                patch(x1 - p - s, y0 + p, s, s),
+                patch(x0 + p, y1 - p - s, s, s),
+                patch(x1 - p - s, y1 - p - s, s, s)
+            ];
+            const median = [0, 1, 2].map((ch) => {
+                const vals = corners.map((c) => c[ch]).sort((a, b) => a - b);
+                return (vals[1] + vals[2]) / 2;
+            });
+            // At least three corners must look like that median, or this panel has no
+            // readable plate and guessing one would key holes through the art.
+            const votes = corners.filter((c) => near(c, median)).length;
+            if (votes < 3)
+                return null;
+            zones.push({ x: x0, y: y0, width: zw, height: zh, hex: hexOf(median), rgb: [Math.round(median[0]), Math.round(median[1]), Math.round(median[2])] });
+        }
+    }
+    return zones.length ? zones : null;
+}
+/**
+ * Compute a straight (unassociated) RGBA image from a sheet's RGB pixels by
+ * flood-filling the plate inward from each zone's border.
+ *
+ * PURE: takes and returns typed arrays, so the whole decision surface is
+ * testable without ffmpeg. `rgb` is w*h*3 bytes; the returned `rgba` is w*h*4.
+ */
+export function keyPlateFromPixels(rgb, w, h, zones, opts = {}) {
+    const despill = opts.despill ?? true;
+    const rgba = new Uint8Array(w * h * 4);
+    // Start fully opaque: anything the fill never reaches IS art, by definition.
+    for (let i = 0, j = 0; i < w * h; i++, j += 3) {
+        rgba[i * 4] = rgb[j];
+        rgba[i * 4 + 1] = rgb[j + 1];
+        rgba[i * 4 + 2] = rgb[j + 2];
+        rgba[i * 4 + 3] = 255;
+    }
+    const perZone = [];
+    let keyedTotal = 0;
+    let protectedTotal = 0;
+    let plateColoredTotal = 0;
+    let featheredTotal = 0;
+    const queue = new Int32Array(w * h);
+    zones.forEach((zone, zi) => {
+        const { x: zx, y: zy, width: zw, height: zh } = zone;
+        const chromatic = isChromatic(zone.rgb);
+        const base = defaultsForPlate(zone.rgb);
+        const inner = Math.min(0.95, Math.max(0.001, opts.tolerance ?? base.tolerance));
+        const bandWidth = Math.min(0.95, Math.max(0, opts.softness ?? base.softness));
+        const outer = Math.min(1, inner + bandWidth);
+        // Per-pixel plate distance for this panel only. `loose` is the mask the fill
+        // may travel through; `tight` marks definite plate.
+        const dist = new Float32Array(zw * zh);
+        const loose = new Uint8Array(zw * zh);
+        for (let y = 0; y < zh; y++) {
+            for (let x = 0; x < zw; x++) {
+                const src = ((zy + y) * w + (zx + x)) * 3;
+                const d = plateDistance(rgb[src], rgb[src + 1], rgb[src + 2], zone.rgb, chromatic);
+                const p = y * zw + x;
+                dist[p] = d;
+                if (d <= outer)
+                    loose[p] = 1;
+                if (d <= inner)
+                    plateColoredTotal++;
+            }
+        }
+        // Flood inward from the panel's own perimeter, 4-connected (an 8-connected
+        // fill squeezes through 1px diagonal seams in antialiased line art and eats
+        // interiors it has no business reaching).
+        const reached = new Uint8Array(zw * zh);
+        let head = 0;
+        let tail = 0;
+        const push = (p) => {
+            if (loose[p] && !reached[p]) {
+                reached[p] = 1;
+                queue[tail++] = p;
+            }
+        };
+        for (let x = 0; x < zw; x++) {
+            push(x);
+            push((zh - 1) * zw + x);
+        }
+        for (let y = 0; y < zh; y++) {
+            push(y * zw);
+            push(y * zw + (zw - 1));
+        }
+        while (head < tail) {
+            const p = queue[head++];
+            const py = (p / zw) | 0;
+            const px = p - py * zw;
+            if (px > 0)
+                push(p - 1);
+            if (px < zw - 1)
+                push(p + 1);
+            if (py > 0)
+                push(p - zw);
+            if (py < zh - 1)
+                push(p + zw);
+        }
+        // Write alpha: 0 inside the reached plate, an estimated coverage across the
+        // boundary, and full opacity everywhere the fill never got to.
+        const cleared = new Uint8Array(zw * zh); // fully-keyed, for the edge shell below
+        let keyedHere = 0;
+        for (let y = 0; y < zh; y++) {
+            for (let x = 0; x < zw; x++) {
+                const p = y * zw + x;
+                const out = ((zy + y) * w + (zx + x)) * 4;
+                if (!reached[p]) {
+                    // Plate-colored but unreachable = art interior we just saved.
+                    if (dist[p] <= inner)
+                        protectedTotal++;
+                    continue;
+                }
+                if (dist[p] <= inner) {
+                    rgba[out + 3] = 0;
+                    cleared[p] = 1;
+                    keyedHere++;
+                    continue;
+                }
+                const a = coverage(rgb, ((zy + y) * w + (zx + x)) * 3, zone.rgb, dist[p], inner, outer);
+                rgba[out + 3] = Math.round(a * 255);
+                if (a < 1)
+                    featheredTotal++;
+                keyedHere += 1 - a;
+                if (despill)
+                    unpremultiplyPlate(rgba, out, zone.rgb, a);
+            }
+        }
+        // EDGE SHELL. Antialiasing leaves a one-pixel ring of art/plate blend whose
+        // color has already drifted past `outer` — too far to be called plate, but
+        // still carrying the plate's tint. Colour distance can't catch it; geometry
+        // can: any opaque pixel touching the cleared region is on the silhouette, so
+        // estimate its coverage the same way. This is what removes the green fringe
+        // that a flat key leaves behind (and it can't erode the art, because a pixel
+        // with nothing of the plate in it estimates as fully opaque).
+        for (let y = 0; y < zh; y++) {
+            for (let x = 0; x < zw; x++) {
+                const p = y * zw + x;
+                const out = ((zy + y) * w + (zx + x)) * 4;
+                if (rgba[out + 3] !== 255)
+                    continue;
+                const touching = (x > 0 && cleared[p - 1]) || (x < zw - 1 && cleared[p + 1]) ||
+                    (y > 0 && cleared[p - zw]) || (y < zh - 1 && cleared[p + zw]);
+                if (!touching)
+                    continue;
+                const a = coverage(rgb, ((zy + y) * w + (zx + x)) * 3, zone.rgb, dist[p], inner, outer);
+                if (a >= 1)
+                    continue;
+                rgba[out + 3] = Math.round(a * 255);
+                featheredTotal++;
+                keyedHere += 1 - a;
+                if (despill)
+                    unpremultiplyPlate(rgba, out, zone.rgb, a);
+            }
+        }
+        keyedTotal += keyedHere;
+        perZone.push({ zone: zi + 1, hex: zone.hex, keyed_pct: Math.round((keyedHere / (zw * zh)) * 1000) / 10 });
+    });
+    return {
+        rgba,
+        stats: {
+            zones,
+            perZone,
+            keyed_pct: Math.round((keyedTotal / (w * h)) * 1000) / 10,
+            protected_px: protectedTotal,
+            protected_pct: plateColoredTotal > 0 ? Math.round((protectedTotal / plateColoredTotal) * 1000) / 10 : 0,
+            feathered_px: featheredTotal
+        }
+    };
+}
+// ── ffmpeg I/O ───────────────────────────────────────────────────────────────
+/** Read a still as raw RGB24 at its native size (or a given size). */
+export async function readRgbPlane(sourcePath, size) {
+    if (!existsSync(sourcePath))
+        throw new Error(`No such source file: ${sourcePath}`);
+    const dims = size ?? (await probeImageDimensions(sourcePath));
+    if (!dims)
+        throw new Error(`Couldn't read image dimensions for ${sourcePath}.`);
+    const ffmpeg = await resolveFfmpeg();
+    const scale = size ? [`scale=${dims.width}:${dims.height}:flags=area`] : [];
+    const args = [
+        "-hide_banner", "-v", "error",
+        "-i", sourcePath,
+        "-frames:v", "1",
+        ...(scale.length ? ["-vf", scale.join(",")] : []),
+        "-f", "rawvideo", "-pix_fmt", "rgb24",
+        "-"
+    ];
+    const need = dims.width * dims.height * 3;
+    const buf = await new Promise((resolve, reject) => {
+        const child = spawn(ffmpeg, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const chunks = [];
+        let stderr = "";
+        child.stdout.on("data", (d) => chunks.push(d));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const out = Buffer.concat(chunks);
+            if (code !== 0 || out.length < need) {
+                reject(new Error(`Couldn't read ${sourcePath} as pixels (ffmpeg exit ${code})${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-2).join(" ")}` : ""}.`));
+            }
+            else
+                resolve(out);
+        });
+    });
+    return { rgb: new Uint8Array(buf.buffer, buf.byteOffset, need), width: dims.width, height: dims.height };
+}
+/** Write raw RGBA out as a transparent PNG/WebP. */
+export async function writeRgbaStill(rgba, width, height, outputPath) {
+    const ffmpeg = await resolveFfmpeg();
+    const isWebp = /\.webp$/i.test(outputPath);
+    const args = [
+        "-hide_banner", "-v", "error", "-y",
+        "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${width}x${height}`, "-i", "-",
+        "-frames:v", "1",
+        ...(isWebp ? ["-c:v", "libwebp", "-lossless", "1", "-pix_fmt", "rgba"] : ["-c:v", "png", "-pix_fmt", "rgba"]),
+        outputPath
+    ];
+    await new Promise((resolve, reject) => {
+        const child = spawn(ffmpeg, args, { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code !== 0 || !existsSync(outputPath)) {
+                reject(new Error(`Writing the keyed still failed (ffmpeg exit ${code})${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-2).join(" ")}` : ""}.`));
+            }
+            else
+                resolve();
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(Buffer.from(rgba.buffer, rgba.byteOffset, rgba.length));
+    });
+}
+/**
+ * Zones for a declared R×C grid: split the sheet into equal panels and read each
+ * panel's plate color from its own corners. Used when WE generated the sheet, so
+ * the layout is known and only the colors need reading back (image models drift
+ * the hue; the corners tell the truth).
+ */
+export function zonesFromGrid(rgb, w, h, rows, cols) {
+    const zones = [];
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            const x0 = Math.round((c * w) / cols);
+            const x1 = Math.round(((c + 1) * w) / cols);
+            const y0 = Math.round((r * h) / rows);
+            const y1 = Math.round(((r + 1) * h) / rows);
+            const zw = x1 - x0;
+            const zh = y1 - y0;
+            const inset = Math.max(2, Math.round(Math.min(zw, zh) * 0.02));
+            const s = Math.max(3, Math.round(Math.min(zw, zh) * 0.03));
+            const corners = [
+                [x0 + inset, y0 + inset],
+                [x1 - inset - s, y0 + inset],
+                [x0 + inset, y1 - inset - s],
+                [x1 - inset - s, y1 - inset - s]
+            ].map(([px, py]) => {
+                let sr = 0, sg = 0, sb = 0, n = 0;
+                for (let yy = py; yy < Math.min(h, py + s); yy++) {
+                    for (let xx = px; xx < Math.min(w, px + s); xx++) {
+                        const i = (yy * w + xx) * 3;
+                        sr += rgb[i];
+                        sg += rgb[i + 1];
+                        sb += rgb[i + 2];
+                        n++;
+                    }
+                }
+                return n ? [sr / n, sg / n, sb / n] : [0, 0, 0];
+            });
+            const median = [0, 1, 2].map((ch) => {
+                const vals = corners.map((cc) => cc[ch]).sort((a, b) => a - b);
+                return Math.round((vals[1] + vals[2]) / 2);
+            });
+            zones.push({ x: x0, y: y0, width: zw, height: zh, hex: hexOf(median), rgb: median });
+        }
+    }
+    return zones;
+}
+/** Detect a sheet's panel layout (or its single plate color) from the file. */
+export async function detectPlateZones(sourcePath) {
+    // Detection is a layout question — run it on a downscale for speed, then map
+    // the boundaries back up to source pixels.
+    const dims = await probeImageDimensions(sourcePath);
+    if (!dims)
+        return null;
+    const longSide = Math.max(dims.width, dims.height);
+    const scale = longSide > 720 ? 720 / longSide : 1;
+    const sw = Math.max(8, Math.round(dims.width * scale));
+    const sh = Math.max(8, Math.round(dims.height * scale));
+    const { rgb } = await readRgbPlane(sourcePath, { width: sw, height: sh });
+    const small = detectZoneGrid(rgb, sw, sh);
+    if (!small)
+        return null;
+    const kx = dims.width / sw;
+    const ky = dims.height / sh;
+    return small.map((z) => {
+        const x0 = Math.round(z.x * kx);
+        const y0 = Math.round(z.y * ky);
+        const x1 = Math.min(dims.width, Math.round((z.x + z.width) * kx));
+        const y1 = Math.min(dims.height, Math.round((z.y + z.height) * ky));
+        return { ...z, x: x0, y: y0, width: Math.max(1, x1 - x0), height: Math.max(1, y1 - y0) };
+    });
+}
+/**
+ * Key a still's plate(s) out by connectivity and write a transparent PNG/WebP.
+ * This is the drop-in upgrade for `removeGreenscreenLocal` on images.
+ */
+export async function smartKeyPlate(input) {
+    const { rgb, width, height } = await readRgbPlane(input.sourcePath);
+    let zones;
+    let zoneSource;
+    if (input.zones?.length) {
+        zones = input.zones;
+        zoneSource = "declared";
+    }
+    else if (input.grid && (input.grid.rows > 1 || input.grid.cols > 1)) {
+        zones = zonesFromGrid(rgb, width, height, input.grid.rows, input.grid.cols);
+        zoneSource = "grid";
+    }
+    else if (input.singlePlate || input.keyColor) {
+        zones = [singleZone(width, height, input.keyColor ?? "#00FF00")];
+        zoneSource = "single";
+    }
+    else {
+        const detected = detectZoneGrid(rgb, width, height);
+        if (detected && detected.length > 1) {
+            zones = detected;
+            zoneSource = "detected";
+        }
+        else {
+            zones = [detected?.[0] ?? singleZone(width, height, "#00FF00")];
+            zoneSource = detected ? "detected" : "single";
+        }
+    }
+    const { rgba, stats } = keyPlateFromPixels(rgb, width, height, zones, input);
+    await writeRgbaStill(rgba, width, height, input.outputPath);
+    return { outputPath: input.outputPath, width, height, stats, zoneSource };
+}
+/**
+ * Lay a pack out as a grid of colored panels and pick each panel's plate color
+ * AGAINST THE ITEM THAT SITS ON IT — the whole point of zoning. Adjacent panels
+ * are also kept different, both so the grid is readable from the sheet's edges
+ * and so an item that overruns its panel doesn't dissolve into its neighbour.
+ *
+ * `pick` is injected (it's `pickPlateColor` from sticker-pack.ts) to keep this
+ * module free of the plate-vocabulary table.
+ */
+export function planZonedSheet(items, count, pick, opts = {}) {
+    const n = Math.max(1, items.length || count);
+    const cols = Math.max(1, opts.cols ?? Math.ceil(Math.sqrt(n)));
+    const rows = Math.ceil(n / cols);
+    const cells = [];
+    for (let i = 0; i < n; i++) {
+        const row = Math.floor(i / cols);
+        const col = i % cols;
+        const name = items[i] ?? null;
+        // The item's OWN description drives its plate. With no name, the theme does.
+        const first = pick([name ?? "", opts.theme ?? ""].join(" ").trim() || "generic");
+        let chosen = first;
+        // Nudge off any neighbour that already claimed this color (left and above).
+        const taken = new Set([cells.find((c) => c.row === row && c.col === col - 1), cells.find((c) => c.row === row - 1 && c.col === col)]
+            .filter(Boolean)
+            .map((c) => c.keyColor));
+        if (taken.has(chosen.keyColor)) {
+            const alt = pick(`${name ?? ""} ${opts.theme ?? ""} ${[...taken].map((hex) => hex).join(" ")}`);
+            // pick() only understands words, so fall back to a deterministic rotation
+            // through the alternates when it hands back the same color.
+            chosen = alt.keyColor !== chosen.keyColor ? alt : rotatePlate(chosen, taken);
+        }
+        cells.push({ index: i + 1, name, preset: chosen.preset, keyColor: chosen.keyColor.toUpperCase(), row, col });
+    }
+    return { rows, cols, cells };
+}
+/** Deterministic fallback rotation when the word-based picker can't move. */
+function rotatePlate(current, taken) {
+    const ring = [
+        { preset: "green", keyColor: "#00FF00" },
+        { preset: "magenta", keyColor: "#FF00FF" },
+        { preset: "blue", keyColor: "#0047BB" },
+        { preset: "orange", keyColor: "#FF7A00" },
+        { preset: "cyan", keyColor: "#00E5FF" }
+    ];
+    const start = Math.max(0, ring.findIndex((r) => r.keyColor === current.keyColor.toUpperCase()));
+    for (let step = 1; step <= ring.length; step++) {
+        const cand = ring[(start + step) % ring.length];
+        if (!taken.has(cand.keyColor))
+            return cand;
+    }
+    return current;
+}
+/**
+ * The generation prompt for a ZONED sheet. Everything a flat sheet's prompt has
+ * to forbid because one color is banned everywhere, this can allow: the art may
+ * use any palette (its panel color is chosen against it), and it may be hollow,
+ * outlined or line-art, because a border-connected fill can't reach a shape's
+ * interior. What's left is the two things geometry can't fix — the item must not
+ * touch its panel's plate color at its own edge, and it must stay inside its
+ * panel.
+ */
+export function zonedSheetInstruction(plan, opts = {}) {
+    const panels = plan.cells
+        .map((c) => `panel ${c.index} (row ${c.row + 1}, column ${c.col + 1}): solid ${c.keyColor} background, containing ONLY ${c.name ?? `item ${c.index}`}`)
+        .join("; ");
+    return (`LAYOUT — a color-block sticker sheet, NOT one background: divide the square canvas into an exact ${plan.rows}×${plan.cols} grid ` +
+        `of equal rectangular panels (${plan.cells.length} panels used), edge to edge, with NO gaps, borders, outlines, gutters or dividing lines ` +
+        `between them — each panel is defined purely by its own flat background color. Each panel holds exactly ONE object, ` +
+        `drawn once, centered, at a comfortable size with a clear margin of that panel's own background color on all four sides. ` +
+        `Nothing crosses a panel edge; nothing spans two panels. Panels, in order: ${panels}. ` +
+        `Every panel background must be one completely flat, evenly-lit, uniform fill of the EXACT color named — no gradient, ` +
+        `no texture, no vignette, no shading. ` +
+        `ART — the objects themselves are free: any palette, any style, flat or shaded or painterly, filled or outlined, ` +
+        `as long as (a) the object's OUTER EDGE is clearly a different color from its OWN panel's background, with crisp, ` +
+        `non-blurry edges, and (b) the object casts no drop shadow, glow, reflection or blur onto the panel background. ` +
+        `An object may absolutely use the color of a DIFFERENT panel. No text, no labels, no watermarks, no frames. ` +
+        `One consistent art style across all panels.` +
+        (opts.theme ? ` Overall theme: ${opts.theme}.` : ""));
+}
+//# sourceMappingURL=plate-key.js.map