@officexapp/vidfarm-devcli 0.21.35 → 0.21.37

package/dist/src/cli.js

@@ -23,7 +23,8 @@ import { extractCompositionFacts, formatQaReport, formatWatchTheVideoNotice, qaC
 import { HARNESS_FILENAME, discoverHarness, formatHarnessReport, isLegacyHarnessFilename, listBuiltinHarnesses, loadAndEvaluateHarness, mergeHarnessIntoReport, parseHarness, resolveHarnessPath } from "./devcli/harness.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeLocalDedupe, DEDUPE_PRESETS, DEDUPE_DEFAULT_PRESET, isDedupePresetName } from "./devcli/dedupe-local.js";
-import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, analyzeKeyedArt, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
+import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, connectivitySafeArtInstruction, analyzeKeyedArt, measureOpaqueShare, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
+import { smartKeyPlate, planZonedSheet, zonedSheetInstruction } from "./devcli/plate-key.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -321,6 +322,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --media-type <k>        Force image|video instead of auto-detecting
     --tolerance <0..1>      Key radius (default 0.3); --softness <0..1> edge feather (0.1)
     --no-despill            Skip edge color-fringe suppression
+    --smart                 IMAGE only: key by border-connected fill instead of by
+                            color alone, so plate-colored detail inside the subject
+                            and hollow/outline art survive (what cutout and
+                            sticker-pack do by default). Local only
     --output-format <f>     Image only: png|webp
     --gif                   Write a TRANSPARENT GIF instead (animated for a clip)
                             — local only, 1-bit alpha, for GIF-only sticker surfaces
@@ -373,21 +378,25 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             default: --generate moves the plate off any hue the subject
                             mentions; an existing file's plate is read from its corners.
                             --no-auto-key forces plain green.
+    --key-mode smart|flat   smart (default): flood-fill the plate in from the frame
+                            edge, so plate-colored detail inside the subject and
+                            hollow/outline art survive and the edge is feathered +
+                            de-spilled per pixel. flat: the plain ffmpeg chromakey
     --pad <px>              Keep N px of transparent breathing room around the cutout
     --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
     --no-trim               Key only; don't shrink to the bounding box
     --output-format png|webp   Cutout format (default png)
     --keep-plate <file>     Also save the pre-key generated plate (with --generate)
     --out <file>            Write the cutout here (default <source>.cutout.png)
-  sticker-pack [sheet|url]  Make a whole STICKER PACK from ONE greenscreen sheet:
-                            key the flat plate once, auto-find each item in the
-                            alpha channel, and cut every one into its own snug
+  sticker-pack [sheet|url]  Make a whole STICKER PACK from ONE sheet: key the
+                            plate(s) once, auto-find each item in the alpha
+                            channel, and cut every one into its own snug
                             transparent file (+ stickers.json). One image job for
                             the set = one art style, ~1/N the cost of N cutouts.
                             Items may be any size, from an icon to a full-frame
-                            landscape. Prompts for key-safe art (solid fills, no
-                            outline-only/hollow shapes, nothing in a near-plate
-                            shade) and flags any item that came out hollow.
+                            landscape. Keys by CONNECTIVITY, so plate-colored
+                            detail inside an item and hollow/outline shapes
+                            survive, and edges come out feathered + de-spilled.
                             Local, free, ffmpeg-only. Image-only.
                             (aliases: stickers, sticker-sheet)
     --generate "<theme>"    AI-generate the sheet first (ONE billed image job for
@@ -399,6 +408,30 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             art can't collide with (green art → magenta plate, etc.);
                             splitting an existing sheet detects the plate from its
                             corners. --no-auto-key forces plain green. (--flat too)
+    --sheet-mode <m>        auto (default) | zoned | flat. ZONED asks the model for a
+                            grid of color PANELS — one item per panel, each panel's
+                            plate picked against that item — so a green frog and a
+                            pink flower can share a sheet, item art can use ANY
+                            palette, and names are pinned to panels instead of guessed
+                            from reading order. auto = zoned when generating 2+ named
+                            items. FLAT is the classic one-color sheet: use it for a
+                            weaker image model that can't follow a color-block grid
+                            (if a model ignores the grid, keying detects that and
+                            falls back to a flat plate on its own)
+    --zones auto|off|RxC    How to read panels off a sheet at key time (default auto:
+                            recover the grid from the sheet's own edges, else one
+                            plate). Pass RxC for a sheet you know the layout of
+    --zone-cols <n>         Force the panel grid's column count when planning a
+                            zoned generation
+    --key-mode smart|flat   smart (default): flood-fill the plate inward from the
+                            sheet edge, so only background that REACHES the edge is
+                            deleted. flat: the plain ffmpeg chromakey (deletes the key
+                            color wherever it appears) — the simple fallback, and the
+                            way to match a cloud render exactly
+    --refine                Re-cut every item with the local ONNX matting model
+                            (free, ~1-2s each) instead of the chroma cut — the path
+                            for painterly, soft-edged, furry or glassy art. Falls
+                            back to the keyed cut per item when the matte looks wrong
     --dry-run               Just list the detected crop boxes; write nothing
     --gap <pct>             Merge islands closer than this % of the sheet's short
                             side into ONE item (default 1.2) — raise it to rejoin a
@@ -2437,7 +2470,7 @@ Rules:
 - For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
 - If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
 - NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use an imported family (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
-- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; never a DM funnel, "follow for part two", or ragebait. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
+- STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; a keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed, but never "follow for part two", ragebait, or an earnings/health claim traded for the reply. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
 - THE FIRST FRAME IS THE THUMBNAIL. Frame 0 is one frame of ~30 in the first second, but every feed card, share link, and paused player freezes on it — more people see that frame than watch the video. It must never be black, empty, mid-fade, or mid-animation: a real visual at start:0 (\`vidfarm retime . --layer <key> --start 0\`), the hook words already on screen at t=0, and NO entrance transition on the FIRST clip (\`vidfarm transitions set . --layer <key> --in none\`; junction transitions between later clips are fine). Look at the actual pixels before you render: \`vidfarm stills . --at 0\`.
 - REVIEW THE WHOLE VIDEO AS ONE OBJECT — AND NEVER JUDGE IT BY ONE FRAME. Assume your own finished video has a defect you cannot see: across a 32-video batch, EVERY first-pass video had a real defect its own author had already reported as "verified, looks good". The cause is structural — you build scene by scene, each scene correct while it is the whole world, so every scene passes alone and the video fails as a SEQUENCE: margins shift between beats, headline sizes drift, the accent color wanders, one asset is flat vector and the next is photographic, every beat is the same length, a join lands like a slap. Nobody watches a scene; they watch the sequence. So before you call anything done, tile ~12 stills into ONE contact sheet and READ IT AS AN IMAGE — one command: \`vidfarm stills . --sheet\` (add \`--at 0,2,4,…\` to pick timestamps; writes stills/contact-sheet.png). Check: visual balance (no dead band under top-anchored content), consistent spacing/margins, ONE type scale, ONE accent color, ONE illustration style, deliberate pacing rather than N identical beats, nothing jarring at the joins, no frame where two elements compete for the eye — and the summary question, does it look like one person made it in one sitting? Fix drift by defining the SYSTEM (type scale, margin, palette, default beat) and applying it to every scene, not by patching the one scene that stood out. The defects that actually ship, in observed frequency order: large flat dead regions · a placeholder empty state that reads as a failed render · two contradictory numbers in one frame · a CTA still building at the last frame (settle it >=2s before the end) · two headlines superimposed at a scene handoff (exit at nextIn-0.18, duration 0.24, ease power2.out) · type colliding with a busy background exactly as it is spoken. If a frame looks empty, sample 0.2s apart to see whether it RESTS there — a transient wipe frame is fine, >0.5s is a hole. AND ALWAYS COMPARE TWO FRAMES FROM DIFFERENT SCENES: a frozen render (an overlay/watermark pass missing \`-loop 1\`, or assets outside the composition root so the timeline never runs) makes every frame identical while duration, frame count and audio hash all still pass, and frame 0 looks perfect. Verify audio by MEASUREMENT, never "it sounds fine" (you cannot hear it): ~12-15 dB speech-over-bed separation across the actual word spans, peak <0 dBFS. Never \`adelay\` the VO — whisper word timings and every caption built from them are relative to the raw vo.wav; use apad+atrim. Report what you MEASURED separately from what you JUDGED. Full method: the vidfarm skill's references/reviewing-renders.md.
 - THE HARNESS IS A FIRST-CLASS ARTIFACT — KNOW THE THREE PHRASINGS. A HARNESS.md is the reusable AI harness for ONE format or template: what makes it special, written down so an agent reproduces it without the director in the room. "Create me a harness" → \`vidfarm harness init short-form --out ./HARNESS.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. "Update the harness for this format" → open the file and write the new rule in WITH ITS REASON on the same line. "Give me the harness for this template_id" → they mean the DECOMPOSITION: \`vidfarm harness derive <forkId>\` distils this fork's viral/visual/structural/audio/build DNA into an editable HARNESS.md, keyed the same way the decompose JSON is (\`## Viral DNA\` → \`viral_dna\`, …); \`vidfarm harness show <ref> --dna visual\` prints one strand. \`vidfarm qa .\` picks up ./HARNESS.md automatically; \`--harness <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. ONE-TIME OR BULK? Ask before you build: if the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE — pin this fork as the base, vary exactly ONE thing per variant, and install a harness, because nobody watches variant #37 as carefully as #1. When a batch teaches you something, write it back into the harness — the compositions are disposable, the harness compounds. (Formerly QA_REGIME.md; \`vidfarm regime …\` still works as an alias. NOTE: the \`.harness/\` directory beside this file is machine-generated context regenerated on every pull — never hand-edit it. HARNESS.md is the one you own.)
@@ -5198,6 +5231,12 @@ async function runRemoveGreenscreenCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            // IMAGE-only upgrade: key by border-connected fill instead of by color
+            // alone, so plate-colored detail inside the subject and hollow/outline art
+            // survive (`vidfarm cutout` / `sticker-pack` use this by default). Video
+            // stays on the ffmpeg filter chain — per-frame fills in JS would be slow
+            // and would break cloud parity.
+            smart: { type: "boolean", default: false },
             "output-format": { type: "string" },
             // Animated transparent GIF (local only) — the "sticker for GIF-only
             // surfaces" output. GIF alpha is 1-bit, so it's a hand-off format, not a
@@ -5364,9 +5403,38 @@ async function runLocalGreenscreen(ctx, values, sourceArg, presetRaw) {
         const keyTargetPath = gifWork
             ? path.join(gifWork, mediaType === "video" ? "keyed.webm" : "keyed.png")
             : outPath;
-        if (!ctx.json)
-            console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with ffmpeg (free)…${RESET}`);
-        let result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: keyTargetPath, keyColor, tolerance, softness, despill });
+        const wantSmart = Boolean(values.smart);
+        if (wantSmart && mediaType === "video") {
+            throw new Error("--smart is image-only (it flood-fills the plate per frame). For a clip, key it without --smart, or cut the subject out with `vidfarm remove-background <video>` (ONNX matting, color-blind).");
+        }
+        let result;
+        if (wantSmart) {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            const smart = await smartKeyPlate({
+                sourcePath,
+                outputPath: /\.(png|webp)$/i.test(keyTargetPath) ? keyTargetPath : `${keyTargetPath.replace(/\.[^.]+$/, "")}.png`,
+                keyColor: keyColor ?? "#00FF00",
+                singlePlate: true,
+                tolerance: values.tolerance !== undefined ? Number(values.tolerance) : undefined,
+                softness: values.softness !== undefined ? Number(values.softness) : undefined,
+                despill
+            });
+            result = {
+                outputPath: smart.outputPath,
+                format: (/\.webp$/i.test(smart.outputPath) ? "webp" : "png"),
+                alpha: true,
+                webmAlpha: false
+            };
+            if (!ctx.json && smart.stats.protected_px) {
+                console.log(`${DIM}Kept ${smart.stats.protected_px.toLocaleString()} plate-colored pixel(s) INSIDE the subject that a flat key would have deleted.${RESET}`);
+            }
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out ${presetRaw ?? keyColor ?? "green"} background locally with ffmpeg (free)…${RESET}`);
+            result = await removeGreenscreenLocal({ sourcePath, mediaType, outputPath: keyTargetPath, keyColor, tolerance, softness, despill });
+        }
         if (gifWork) {
             try {
                 if (!ctx.json)
@@ -5776,7 +5844,7 @@ async function runLocalDedupe(ctx, input) {
 // "Cutout graphics for explainers" recipe for placement + zoom/grow/shake/move).
 /** Build a chroma-plate instruction so an AI-generated graphic keys cleanly.
  *  Matches the color to the chosen key so the keyer has a flat edge to cut. */
-function cutoutPlateInstruction(keyColorHex) {
+function cutoutPlateInstruction(keyColorHex, keyMode = "smart") {
     const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
         : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
@@ -5785,9 +5853,10 @@ function cutoutPlateInstruction(keyColorHex) {
         `like a green-screen plate. ` +
         `Center the subject with generous empty margin on all sides, no drop shadow or reflection cast on the ` +
         `background, crisp clean edges, sticker/cutout style, single subject, no text. ` +
-        // The plate color is only half the battle — art drawn as a hollow outline
-        // (or in a near-plate shade) gets its middle keyed away too.
-        keySafeArtInstruction(keyColorHex));
+        // Which art rules apply depends on the keyer: a flat chromakey deletes the
+        // key color wherever it appears (so hollow art loses its middle), while the
+        // smart keyer only deletes background that reaches the frame edge.
+        (keyMode === "smart" ? connectivitySafeArtInstruction(keyColorHex) : keySafeArtInstruction(keyColorHex)));
 }
 async function runCutoutCommand(argv) {
     const parsed = parseArgs({
@@ -5809,6 +5878,7 @@ async function runCutoutCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            "key-mode": { type: "string" }, // smart (default) | flat
             // Trim knobs.
             "no-trim": { type: "boolean", default: false },
             pad: { type: "string" },
@@ -5836,6 +5906,15 @@ async function runCutoutCommand(argv) {
     const despill = !parsed.values["no-despill"];
     const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
     const outExt = outputFormat === "webp" ? "webp" : "png";
+    // `smart` keys by border-connected fill, so plate-colored details inside the
+    // subject and hollow/outline art survive, and the edge is feathered + de-spilled
+    // per pixel. `flat` is the plain ffmpeg chromakey, kept as the simple fallback
+    // (and the way to match a cloud render exactly).
+    const keyModeRaw = (parsed.values["key-mode"] ?? "smart").trim().toLowerCase();
+    if (!["smart", "flat"].includes(keyModeRaw)) {
+        throw new Error(`Unknown --key-mode "${keyModeRaw}". Use smart (default) or flat (the plain ffmpeg chromakey).`);
+    }
+    const keyMode = keyModeRaw;
     const generatePrompt = parsed.values.generate?.trim();
     const sourceArg = parsed.values.source ?? parsed.positionals[0];
     if (!generatePrompt && !sourceArg) {
@@ -5876,7 +5955,7 @@ async function runCutoutCommand(argv) {
                     "and hands the PNG back; `vidfarm cutout <file>` then keys + trims it for $0"
             });
             const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
-            const fullPrompt = `${generatePrompt}. ${cutoutPlateInstruction(keyColor)}`;
+            const fullPrompt = `${generatePrompt}. ${cutoutPlateInstruction(keyColor, keyMode)}`;
             const payload = { prompt: fullPrompt };
             payload.aspect_ratio = parsed.values["aspect-ratio"] ?? "1:1";
             if (parsed.values.provider)
@@ -5940,9 +6019,28 @@ async function runCutoutCommand(argv) {
             }
         }
         const keyedPath = path.join(work, "keyed.png");
-        if (!ctx.json)
-            console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg (free)…${RESET}`);
-        await removeGreenscreenLocal({ sourcePath, mediaType: "image", outputPath: keyedPath, keyColor, tolerance, softness, despill });
+        let cutoutKey = null;
+        if (keyMode === "flat") {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with ffmpeg chromakey (--key-mode flat, free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath, mediaType: "image", outputPath: keyedPath, keyColor, tolerance, softness, despill });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} background locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            cutoutKey = await smartKeyPlate({
+                sourcePath,
+                outputPath: keyedPath,
+                keyColor,
+                singlePlate: true,
+                tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                despill
+            });
+            if (!ctx.json && cutoutKey.stats.protected_px) {
+                console.log(`${DIM}Kept ${cutoutKey.stats.protected_px.toLocaleString()} ${keyColor}-colored pixel(s) INSIDE the subject that a flat key would have deleted.${RESET}`);
+            }
+        }
         // ---- 3. Trim to the tight cutout bounding box ---------------------------
         const outPath = parsed.values.out
             ? path.resolve(process.cwd(), String(parsed.values.out))
@@ -5968,12 +6066,18 @@ async function runCutoutCommand(argv) {
         // left as bare plate) or a near-plate fill comes back as a rim around a
         // see-through hole — invisible until it composites over a real background.
         const art = await analyzeKeyedArt(trim.outputPath);
-        const hollowNote = art?.hollow
-            ? `${art.hole_pct}% of this cutout is transparent HOLES inside the art. If it's meant to be a ring/frame/donut, ignore this. ` +
-                `Otherwise the key ate the fill: the art was drawn as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. ` +
-                `Fix it in the PROMPT — ask for "a closed, solidly filled shape, no outline-only or hollow art, nothing in ${keyColor} or any near-shade of it, ` +
-                `fully opaque, no translucency or glow" — and re-generate. (--tolerance lower can rescue a near-shade fill; nothing rescues an empty one.)`
-            : null;
+        const hollowNote = !art?.hollow
+            ? null
+            : keyMode === "smart"
+                // The smart keyer can't reach an enclosed interior, so a hole is almost
+                // always drawn that way — or the fill is OPEN to the background.
+                ? `${art.hole_pct}% of this cutout is transparent HOLES inside the art. The smart keyer can't delete an enclosed interior, so this is ` +
+                    `most likely real (a ring, frame, donut, or separate pieces with background between them). If it looks wrong, the shape's fill is open ` +
+                    `to the background through a gap in its outline — ask the prompt for a closed, solidly filled shape.`
+                : `${art.hole_pct}% of this cutout is transparent HOLES inside the art. If it's meant to be a ring/frame/donut, ignore this. ` +
+                    `Otherwise the flat key ate the fill: the art was drawn as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. ` +
+                    `Re-run without --key-mode flat (the smart keyer keeps enclosed interiors), or fix it in the PROMPT — "a closed, solidly filled shape, ` +
+                    `nothing in ${keyColor} or any near-shade of it, fully opaque".`;
         if (ctx.json) {
             printJson({
                 ok: true,
@@ -5988,6 +6092,9 @@ async function runCutoutCommand(argv) {
                 area_reduced_pct: shrinkPct,
                 bytes: safeSize(trim.outputPath),
                 key_color: keyColor,
+                key_mode: keyMode,
+                keyed_pct: cutoutKey?.stats.keyed_pct ?? null,
+                protected_px: cutoutKey?.stats.protected_px ?? null,
                 hole_pct: art?.hole_pct ?? null,
                 hollow: art?.hollow ?? false,
                 hollow_note: hollowNote
@@ -6207,7 +6314,7 @@ function slugifyStickerName(raw) {
  *  in the parts that make segmentation work: a spread-out grid and, above all,
  *  visible plate-colored GAPS between items (touching items merge into one
  *  island and come out as a single sticker). */
-function stickerSheetInstruction(keyColorHex, count, items) {
+function stickerSheetInstruction(keyColorHex, count, items, keyMode = "smart") {
     const named = /^#?00ff00$/i.test(keyColorHex) ? "pure chroma-key green"
         : /^#?0047bb$/i.test(keyColorHex) ? "solid chroma-key blue"
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
@@ -6221,7 +6328,10 @@ function stickerSheetInstruction(keyColorHex, count, items) {
         `nothing touching, overlapping, or connected. Keep a wide ${keyColorHex} margin around the edges of the sheet too. ` +
         `No drop shadows, no reflections, no text, no labels, ` +
         `no frames or dividing lines between items. One consistent art style across all items, crisp clean edges, sticker/cutout style. ` +
-        keySafeArtInstruction(keyColorHex));
+        // The art rules depend on which keyer will cut this sheet: the smart keyer
+        // only deletes background that reaches the sheet's edge, so it can allow
+        // hollow shapes and plate-colored detail that a flat chromakey cannot.
+        (keyMode === "smart" ? connectivitySafeArtInstruction(keyColorHex) : keySafeArtInstruction(keyColorHex)));
 }
 async function runStickerPackCommand(argv) {
     const parsed = parseArgs({
@@ -6246,6 +6356,12 @@ async function runStickerPackCommand(argv) {
             tolerance: { type: "string" },
             softness: { type: "string" },
             "no-despill": { type: "boolean", default: false },
+            // How the plate is removed, and how the sheet is laid out.
+            "key-mode": { type: "string" }, // smart (default) | flat
+            "sheet-mode": { type: "string" }, // auto (default) | zoned | flat
+            zones: { type: "string" }, // auto (default) | off | RxC
+            "zone-cols": { type: "string" },
+            refine: { type: "boolean", default: false },
             // Segmentation knobs.
             "min-area": { type: "string" },
             gap: { type: "string" },
@@ -6290,13 +6406,71 @@ async function runStickerPackCommand(argv) {
     if (!generatePrompt && !sourceArg) {
         throw new Error("sticker-pack needs a sheet: `vidfarm sticker-pack <sheet.png|url>` to cut up a greenscreen sheet you already have, or `vidfarm sticker-pack --generate \"cozy farm props\" --items \"barn,tractor,hay bale,sun\"` to AI-generate one first (ONE image job for the whole set).");
     }
+    // ---- How to key, and how to lay the sheet out -----------------------------
+    // KEY MODE. `smart` (default) keys by CONNECTIVITY: it flood-fills the plate
+    // inward from the sheet's edge, so only background that reaches the edge is
+    // deleted. Plate-colored art interiors and hollow/outline shapes survive, and
+    // edges come out feathered and de-spilled per pixel. `flat` is the original
+    // ffmpeg chromakey — every pixel that looks like the key color goes, wherever
+    // it is. Kept as a first-class fallback: it is the cloud path's exact filter
+    // chain, so it's the way to reproduce a cloud render bit-for-bit.
+    const keyModeRaw = (parsed.values["key-mode"] ?? "smart").trim().toLowerCase();
+    if (!["smart", "flat"].includes(keyModeRaw)) {
+        throw new Error(`Unknown --key-mode "${keyModeRaw}". Use smart (default — connectivity fill, keeps plate-colored art) or flat (the plain ffmpeg chromakey).`);
+    }
+    const keyMode = keyModeRaw;
+    // SHEET MODE. `zoned` puts every item on its OWN colored panel, so each item's
+    // plate is chosen against that item — a green frog on magenta beside a pink
+    // flower on green. `flat` is the classic ONE-color sheet. `auto` (default)
+    // zones a named multi-item generation and stays flat otherwise, because a
+    // weaker image model may not honor a color-block grid; if the model ignores it
+    // anyway, keying falls back to a flat plate automatically (see below).
+    const sheetModeRaw = (parsed.values["sheet-mode"] ?? "auto").trim().toLowerCase();
+    if (!["auto", "zoned", "flat"].includes(sheetModeRaw)) {
+        throw new Error(`Unknown --sheet-mode "${sheetModeRaw}". Use auto (default), zoned (one plate color per item — needs a model that follows a color-block grid), or flat (one plate color for the whole sheet).`);
+    }
+    if (sheetModeRaw === "zoned" && keyMode === "flat") {
+        throw new Error("--sheet-mode zoned needs the smart keyer (a flat chromakey can only remove one color per sheet). Drop --key-mode flat, or use --sheet-mode flat.");
+    }
+    if (sheetModeRaw === "zoned" && !generatePrompt) {
+        throw new Error("--sheet-mode zoned only applies when GENERATING a sheet (it plans the panel colors). For a zoned sheet you already have, pass --zones auto (the default) or --zones RxC.");
+    }
+    const wantZonedSheet = generatePrompt
+        ? sheetModeRaw === "zoned" || (sheetModeRaw === "auto" && keyMode === "smart" && itemNames.length >= 2 && !explicitKeyColor)
+        : false;
+    // ZONES: how to READ panels back off a sheet at key time. Independent of
+    // sheet-mode, because a zoned sheet can also arrive from a web generator.
+    const zonesRaw = (parsed.values.zones ?? "auto").trim().toLowerCase();
+    let declaredGrid = null;
+    if (!["auto", "off", "none"].includes(zonesRaw)) {
+        const m = /^(\d+)\s*[x×]\s*(\d+)$/.exec(zonesRaw);
+        if (!m)
+            throw new Error(`Unknown --zones "${zonesRaw}". Use auto (default — read the panels off the sheet), off (one plate for the whole sheet), or a grid like 3x2 (rows x columns).`);
+        declaredGrid = { rows: Number(m[1]), cols: Number(m[2]) };
+    }
+    const zonesOff = ["off", "none"].includes(zonesRaw);
+    const refine = Boolean(parsed.values.refine);
     // PLATE CHOICE. A chroma key removes exactly one color, so a plate the art
     // also uses keys holes through the art — a pack of leaves/frogs/money on GREEN
     // is the classic own-goal. When generating and the caller didn't pin a color,
     // read the subject and move the plate off any hue it mentions.
     let plateNote = null;
     let plateAuto = false;
-    if (generatePrompt && !explicitKeyColor && !parsed.values["no-auto-key"]) {
+    let zonePlan = null;
+    if (wantZonedSheet) {
+        // ZONED: no single plate to pick — every panel gets its own, chosen against
+        // the item that sits on it.
+        zonePlan = planZonedSheet(itemNames, itemNames.length, pickPlateColor, {
+            theme: generatePrompt,
+            cols: parsed.values["zone-cols"] !== undefined ? Math.max(1, Math.round(Number(parsed.values["zone-cols"]))) : undefined
+        });
+        plateAuto = true;
+        plateNote =
+            `Zoned sheet: ${zonePlan.rows}×${zonePlan.cols} panels, one plate color per item ` +
+                `(${zonePlan.cells.map((c) => `${c.name ?? `item ${c.index}`} on ${c.keyColor}`).join(", ")}). ` +
+                `Each item's art can use ANY color — including the colors of the other panels.`;
+    }
+    else if (generatePrompt && !explicitKeyColor && !parsed.values["no-auto-key"]) {
         const picked = pickPlateColor([generatePrompt, itemNames.join(" ")].join(" "));
         keyColor = picked.keyColor;
         plateAuto = true;
@@ -6331,7 +6505,9 @@ async function runStickerPackCommand(argv) {
                     "back; this command then splits it for $0"
             });
             const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
-            const fullPrompt = `${generatePrompt}. ${stickerSheetInstruction(keyColor, count, itemNames)}`;
+            const fullPrompt = zonePlan
+                ? `${generatePrompt}. ${zonedSheetInstruction(zonePlan, { theme: generatePrompt })}`
+                : `${generatePrompt}. ${stickerSheetInstruction(keyColor, count, itemNames, keyMode)}`;
             const payload = { prompt: fullPrompt };
             // A sheet wants room to spread items out — square by default, not portrait.
             payload.aspect_ratio = parsed.values["aspect-ratio"] ?? "1:1";
@@ -6344,8 +6520,11 @@ async function runStickerPackCommand(argv) {
             const tracer = parsed.values.tracer ?? `devcli-stickerpack-${Date.now().toString(36)}`;
             if (!ctx.json && plateNote)
                 console.log(`${YELLOW}Plate:${RESET} ${DIM}${plateNote}${RESET}`);
-            if (!ctx.json)
-                console.log(`${DIM}Generating ONE ${keyColor} plate holding ${count} items…${RESET}`);
+            if (!ctx.json) {
+                console.log(zonePlan
+                    ? `${DIM}Generating ONE color-block sheet — ${zonePlan.rows}×${zonePlan.cols} panels, ${count} items, a different plate under each…${RESET}`
+                    : `${DIM}Generating ONE ${keyColor} plate holding ${count} items…${RESET}`);
+            }
             const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/images/generate", auth: ctx.auth, body: { tracer, payload } });
             assertApiOk(submit, "sticker-pack generate");
             const jobId = submit.json?.job_id;
@@ -6385,12 +6564,12 @@ async function runStickerPackCommand(argv) {
                 await downloadUrlToFile(sourceUrl, sheetPath);
             }
         }
-        // ---- 2. Key the flat plate ONCE → a transparent sheet ---------------------
+        // ---- 2. Key the plate(s) ONCE → a transparent sheet ------------------------
         // For a sheet we did NOT generate, read the plate off the image instead of
         // assuming green: the four corners of a sticker sheet are always plate, so
         // a user can hand back a red/purple/blue sheet from a web generator and the
         // cut still works without them knowing what a chroma key is.
-        if (!explicitKeyColor && !generatePrompt && !parsed.values["no-auto-key"]) {
+        if (!explicitKeyColor && !generatePrompt && !parsed.values["no-auto-key"] && (keyMode === "flat" || zonesOff)) {
             const detected = await detectPlateColor(sheetPath);
             if (detected && detected.hex.toUpperCase() !== keyColor.toUpperCase()) {
                 keyColor = detected.hex;
@@ -6404,9 +6583,83 @@ async function runStickerPackCommand(argv) {
                 console.log(`${YELLOW}Plate:${RESET} ${DIM}${plateNote}${RESET}`);
         }
         const keyedSheet = path.join(work, "keyed-sheet.png");
-        if (!ctx.json)
-            console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} plate locally with ffmpeg (free)…${RESET}`);
-        await removeGreenscreenLocal({ sourcePath: sheetPath, mediaType: "image", outputPath: keyedSheet, keyColor, tolerance, softness, despill });
+        let smart = null;
+        let zonesUsed = [];
+        let keyNote = null;
+        if (keyMode === "flat") {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the ${presetRaw ?? keyColor} plate locally with ffmpeg chromakey (--key-mode flat, free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath: sheetPath, mediaType: "image", outputPath: keyedSheet, keyColor, tolerance, softness, despill });
+        }
+        else {
+            // SMART. Zones come from (a) the grid we asked the model for, (b) a grid the
+            // caller declared, (c) the sheet's own edges, or (d) one plate for the whole
+            // sheet. Panels are keyed independently, each with its own color read back
+            // off that panel's corners.
+            const grid = declaredGrid ?? (zonePlan && !zonesOff ? { rows: zonePlan.rows, cols: zonePlan.cols } : null);
+            if (!ctx.json) {
+                console.log(grid || !zonesOff
+                    ? `${DIM}Keying locally with the smart keyer (border-connected fill${grid ? `, ${grid.rows}×${grid.cols} panels` : ", auto zones"}, free)…${RESET}`
+                    : `${DIM}Keying the ${keyColor} plate locally with the smart keyer (border-connected fill, free)…${RESET}`);
+            }
+            smart = await smartKeyPlate({
+                sourcePath: sheetPath,
+                outputPath: keyedSheet,
+                keyColor: zonesOff || explicitKeyColor ? keyColor : undefined,
+                singlePlate: zonesOff,
+                grid: grid ?? undefined,
+                tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                despill
+            });
+            // AUTOMATIC FALLBACK TO A FLAT PLATE. A weaker image model may ignore the
+            // color-block grid and paint one background anyway (or paint a busy one).
+            // Then some "panel" has almost nothing to key, and its item would come out
+            // welded to a colored rectangle. Detect that and re-key the sheet as a
+            // single plate, read off its corners — the simple method, still free.
+            // Two ways a panel says "this sheet isn't the grid I asked for":
+            //   • it keyed almost NOTHING (25%) — the color read at its corners isn't a
+            //     plate, so the panel is really part of one big background or of the art;
+            //   • it keyed EVERYTHING — the item filled the panel corner to corner, so
+            //     the item's own color was read as the plate and the item was deleted.
+            // The second only counts for a panel we expected to hold an item: a trailing
+            // panel of a grid wider than the item list is legitimately all plate.
+            const expectedItems = zonePlan ? zonePlan.cells.length : itemNames.length;
+            const weakZone = smart.stats.perZone.find((z) => z.keyed_pct < 25 || (z.keyed_pct > 99.5 && expectedItems > 0 && z.zone <= expectedItems));
+            if (smart.stats.zones.length > 1 && weakZone) {
+                const detected = await detectPlateColor(sheetPath);
+                keyColor = detected?.hex ?? keyColor;
+                plateAuto = Boolean(detected);
+                keyNote =
+                    `Panel ${weakZone.zone} (${weakZone.hex}) keyed ${weakZone.keyed_pct}% of itself — ` +
+                        `${weakZone.keyed_pct < 25 ? "there's no plate there" : "its item filled the panel corner to corner, so the item's own color read as the plate"}, ` +
+                        `i.e. the sheet isn't really a color-block grid, ` +
+                        `so it was re-keyed as ONE ${keyColor} plate${detected ? " (read off the sheet's corners)" : ""}. ` +
+                        `That's the simple path and it works; for zoned sheets the image model has to follow a color-block grid ` +
+                        `(try a stronger model, or pass --sheet-mode flat to skip zoning entirely).`;
+                smart = await smartKeyPlate({
+                    sourcePath: sheetPath,
+                    outputPath: keyedSheet,
+                    keyColor,
+                    singlePlate: true,
+                    tolerance: parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : undefined,
+                    softness: parsed.values.softness !== undefined ? Number(parsed.values.softness) : undefined,
+                    despill
+                });
+                zonePlan = null; // panel→name mapping is meaningless once we fall back
+                if (!ctx.json)
+                    console.log(`${YELLOW}Zones:${RESET} ${DIM}${keyNote}${RESET}`);
+            }
+            zonesUsed = smart.stats.zones;
+            if (zonesUsed.length === 1)
+                keyColor = zonesUsed[0].hex;
+            if (!ctx.json) {
+                const zoneWord = zonesUsed.length > 1 ? `${zonesUsed.length} panels (${zonesUsed.map((z) => z.hex).join(", ")})` : `one ${keyColor} plate`;
+                console.log(`${DIM}Keyed ${smart.stats.keyed_pct}% of the sheet — ${zoneWord}` +
+                    (smart.stats.protected_px ? `, kept ${smart.stats.protected_px.toLocaleString()} plate-colored pixel(s) INSIDE the art that a flat key would have punched out` : "") +
+                    `.${RESET}`);
+            }
+        }
         if (parsed.values["keep-sheet"]) {
             const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-sheet"]));
             mkdirSync(path.dirname(keepPath), { recursive: true });
@@ -6428,6 +6681,43 @@ async function runStickerPackCommand(argv) {
         if (!seg.components.length) {
             throw new Error("No items found in the sheet. Either the plate didn't key (check --preset/--key-color, raise --tolerance) or every item was filtered as speckle (lower --min-area).");
         }
+        // ---- 3a. Names, by PANEL when the sheet is zoned -------------------------
+        // On a flat sheet, names can only be matched to items in reading order, which
+        // goes off-by-one the moment two items merge or one splits. A zoned sheet
+        // makes it exact: panel N holds the item we asked for in panel N, so an item's
+        // name comes from whichever panel its box sits in.
+        const zoneIndexOf = (c) => {
+            if (zonesUsed.length < 2)
+                return -1;
+            const cx = c.x + c.width / 2;
+            const cy = c.y + c.height / 2;
+            return zonesUsed.findIndex((z) => cx >= z.x && cx < z.x + z.width && cy >= z.y && cy < z.y + z.height);
+        };
+        const nameOf = (c) => {
+            if (zonePlan) {
+                const zi = zoneIndexOf(c);
+                if (zi >= 0)
+                    return zonePlan.cells.find((cell) => cell.index === zi + 1)?.name ?? null;
+            }
+            return itemNames[c.index - 1] ?? null;
+        };
+        // A panel that yielded NO sticker is worth saying out loud: either it was
+        // empty (a grid wider than the item list — fine) or its item was keyed away
+        // with the panel. The pack is still usable, so this warns rather than fails.
+        let emptyPanelNote = null;
+        if (zonesUsed.length > 1) {
+            const empty = zonesUsed
+                .map((_, i) => i + 1)
+                .filter((panel) => !seg.components.some((c) => zoneIndexOf(c) === panel - 1));
+            if (empty.length) {
+                emptyPanelNote =
+                    `Panel(s) ${empty.join(", ")} produced no sticker. If those panels were meant to be empty, ignore this — otherwise the item ` +
+                        `there touched its panel's edges (so its own color read as the plate and it keyed away). Re-run with --zones off, or ` +
+                        `--key-color <hex> to pin the plate.`;
+                if (!ctx.json)
+                    console.log(`${YELLOW}Panels:${RESET} ${DIM}${emptyPanelNote}${RESET}`);
+            }
+        }
         // ---- 3b. Hollow-sticker check -------------------------------------------
         // The other half of "did the key work": items that came back as a rim around
         // a transparent hole, because the art was drawn as an outline (interior left
@@ -6437,14 +6727,24 @@ async function runStickerPackCommand(argv) {
         // which is why this warns and never blocks.
         let hollowNote = null;
         if (seg.hollow.length) {
-            const named = seg.hollow.map((i) => `${String(i).padStart(2, "0")}${itemNames[i - 1] ? ` (${itemNames[i - 1]})` : ""} — ${seg.components.find((c) => c.index === i)?.hole_pct}% see-through`);
-            hollowNote =
-                `${seg.hollow.length} of ${seg.components.length} sticker(s) came out mostly hollow: ${named.join(", ")}. ` +
-                    `If those are meant to be rings/frames/donuts, ignore this. Otherwise the key ate their FILL: the art was drawn ` +
-                    `as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. Fix it in the PROMPT, not the keyer — ` +
-                    `ask for "closed, solidly filled shapes, no outline-only or hollow objects, nothing on the art in ${keyColor} or any ` +
-                    `near-shade of it, fully opaque, no translucency or glow" — then re-generate the sheet. ` +
-                    `(Lowering --tolerance can rescue a near-shade fill from an existing sheet, but not a genuinely empty one.)`;
+            const named = seg.hollow.map((i) => {
+                const c = seg.components.find((comp) => comp.index === i);
+                const label = c ? nameOf(c) : null;
+                return `${String(i).padStart(2, "0")}${label ? ` (${label})` : ""} — ${c?.hole_pct}% see-through`;
+            });
+            hollowNote = keyMode === "smart"
+                // Under the smart keyer an ENCLOSED interior can't be keyed away, so a
+                // hole here is either genuinely drawn art (a ring, a frame) or a gap that
+                // the plate really did reach through — not the old "the key ate the fill".
+                ? `${seg.hollow.length} of ${seg.components.length} sticker(s) have large transparent areas inside them: ${named.join(", ")}. ` +
+                    `With the smart keyer a shape's ENCLOSED interior can't be keyed away, so this is most likely real: a ring, frame, donut, ` +
+                    `or an item drawn as separate pieces with plate showing between them. If it looks wrong, the art's fill is probably OPEN ` +
+                    `to the background (a gap in the outline lets the fill reach the sheet edge) — ask the prompt for closed, solidly filled shapes.`
+                : `${seg.hollow.length} of ${seg.components.length} sticker(s) came out mostly hollow: ${named.join(", ")}. ` +
+                    `If those are meant to be rings/frames/donuts, ignore this. Otherwise the flat key ate their FILL: the art was drawn ` +
+                    `as an outline with a bare ${keyColor} interior, or filled in a near-${keyColor} shade. Either re-run without ` +
+                    `--key-mode flat (the smart keyer keeps enclosed interiors), or fix it in the PROMPT — ` +
+                    `"closed, solidly filled shapes, nothing on the art in ${keyColor} or any near-shade of it, fully opaque".`;
             if (!ctx.json)
                 console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
         }
@@ -6452,13 +6752,24 @@ async function runStickerPackCommand(argv) {
             // Report the boxes without writing stickers — for eyeballing segmentation
             // before spending disk, and for hand-fixing a merged item with `mask --crop`.
             if (ctx.json) {
-                printJson({ ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`, found: seg.components.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, hollow: seg.hollow, hollow_note: hollowNote, items: seg.components });
+                printJson({
+                    ok: true, target: "local", dry_run: true, sheet: `${seg.sourceWidth}x${seg.sourceHeight}`,
+                    found: seg.components.length, skipped_specks: seg.rejected, key_mode: keyMode,
+                    key_color: keyColor, key_color_auto: plateAuto,
+                    zones: zonesUsed.map((z, i) => ({ panel: i + 1, x: z.x, y: z.y, width: z.width, height: z.height, plate: z.hex, keyed_pct: smart?.stats.perZone[i]?.keyed_pct ?? null })),
+                    protected_px: smart?.stats.protected_px ?? null,
+                    hollow: seg.hollow, hollow_note: hollowNote,
+                    items: seg.components.map((c) => ({ ...c, name: nameOf(c), panel: zoneIndexOf(c) >= 0 ? zoneIndexOf(c) + 1 : null }))
+                });
             }
             else {
                 console.log(`${GREEN}Found ${seg.components.length} item${seg.components.length === 1 ? "" : "s"}${RESET} ${DIM}on the ${seg.sourceWidth}×${seg.sourceHeight} sheet${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""} (dry run — nothing written):${RESET}`);
                 for (const c of seg.components) {
                     const hollowFlag = c.hole_pct >= HOLE_WARN_PCT ? `  ${YELLOW}⚠ ${c.hole_pct}% hollow${RESET}` : "";
-                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${RESET}${hollowFlag}`);
+                    const zi = zoneIndexOf(c);
+                    const where = zi >= 0 ? `  panel ${zi + 1} (${zonesUsed[zi].hex})` : "";
+                    const label = nameOf(c);
+                    console.log(`  ${DIM}${String(c.index).padStart(2, "0")}  crop ${c.x},${c.y},${c.width},${c.height}  (${c.width}×${c.height}, ${c.area_pct}% of sheet)${where}${label ? `  ${label}` : ""}${RESET}${hollowFlag}`);
                 }
                 console.log(`${DIM}Merged two items into one box? Raise the gap between them in the prompt, lower --gap, or grab that one by hand: vidfarm mask <sheet> --crop x,y,w,h --flat "${keyColor}".${RESET}`);
             }
@@ -6469,11 +6780,56 @@ async function runStickerPackCommand(argv) {
         const padPx = parsed.values.pad !== undefined ? Number(parsed.values.pad) : 0;
         const gifAlpha = parsed.values["gif-alpha"] !== undefined ? Number(parsed.values["gif-alpha"]) : undefined;
         const written = [];
+        if (refine && !ctx.json) {
+            console.log(`${DIM}Refining each item with the local ONNX matting model (free, a second or two each) — this is the path for painterly/soft-edged art…${RESET}`);
+        }
         for (const c of seg.components) {
-            const label = itemNames[c.index - 1] ? slugifyStickerName(itemNames[c.index - 1]) : "";
+            const itemName = nameOf(c);
+            const label = itemName ? slugifyStickerName(itemName) : "";
             const stem = `${prefix}-${String(c.index).padStart(2, "0")}${label ? `-${label}` : ""}`;
             const regionPath = path.join(work, `${stem}.region.png`);
-            await cropImageRegion({ sourcePath: keyedSheet, outputPath: regionPath, x: c.x, y: c.y, width: c.width, height: c.height });
+            let refined = false;
+            if (refine) {
+                // REFINE. The keyer decides WHERE each item is; matting decides what its
+                // alpha should be. Cropping the item out of the ORIGINAL (un-keyed) sheet
+                // and running the ONNX matte on it is color-blind, so it handles the art a
+                // chroma key can't: soft/painterly edges, fur, glows, glass, drop shadows,
+                // and an item whose own silhouette is the plate color. A little margin
+                // gives the model context to separate against.
+                const margin = Math.round(Math.max(c.width, c.height) * 0.08);
+                const rawRegion = path.join(work, `${stem}.raw.png`);
+                await cropImageRegion({
+                    sourcePath: sheetPath,
+                    outputPath: rawRegion,
+                    x: Math.max(0, c.x - margin),
+                    y: Math.max(0, c.y - margin),
+                    width: c.width + margin * 2,
+                    height: c.height + margin * 2
+                });
+                const matted = path.join(work, `${stem}.matte.png`);
+                const run = await runHyperframesCommand("remove-background", [rawRegion, "-o", matted], { stdio: "capture" });
+                // Trust the matte only if it looks like a cut-out. The model is trained on
+                // photographic subjects, so on flat vector art it can return an EMPTY
+                // matte (blank sticker) or an untouched one (plate still attached) — both
+                // of which write a file and exit 0. The keyed cut is the safer answer then.
+                const opaqueShare = run.code === 0 && existsSync(matted) ? await measureOpaqueShare(matted) : null;
+                const usable = opaqueShare !== null && opaqueShare >= 5 && opaqueShare <= 95;
+                if (usable) {
+                    copyFileSync(matted, regionPath);
+                    refined = true;
+                }
+                else if (!ctx.json) {
+                    const why = run.code !== 0
+                        ? (run.stderr.trim().split("\n").pop() ?? "the matting engine failed")
+                        : opaqueShare === null
+                            ? "the matte had no alpha"
+                            : `the matte came back ${opaqueShare < 5 ? "empty" : "fully opaque"} (${opaqueShare}% opaque) — the model didn't see a subject in this art`;
+                    console.log(`  ${YELLOW}↳${RESET} ${DIM}item ${c.index}: kept the keyed cut instead of the matte — ${why}.${RESET}`);
+                }
+            }
+            if (!refined) {
+                await cropImageRegion({ sourcePath: keyedSheet, outputPath: regionPath, x: c.x, y: c.y, width: c.width, height: c.height });
+            }
             // Trim to the item's TRUE box: segmentation works on a downscaled alpha, so
             // the crop carries a pixel or two of slack — this is what makes the sticker's
             // pixel size equal the subject, the property placement/scaling relies on.
@@ -6484,13 +6840,17 @@ async function runStickerPackCommand(argv) {
                 finalPath = path.join(outDir, `${stem}.gif`);
                 await encodeTransparentGif(trim.outputPath, finalPath, { alphaThreshold: gifAlpha });
             }
+            const zi = zoneIndexOf(c);
             written.push({
                 index: c.index,
-                name: itemNames[c.index - 1] ?? null,
+                name: itemName,
                 file: finalPath,
                 width: trim.width,
                 height: trim.height,
                 sheet_crop: { x: c.x, y: c.y, width: c.width, height: c.height },
+                panel: zi >= 0 ? zi + 1 : null,
+                plate: zi >= 0 ? zonesUsed[zi].hex : keyColor,
+                refined,
                 area_pct: c.area_pct,
                 holes: c.holes,
                 hole_pct: c.hole_pct,
@@ -6505,10 +6865,22 @@ async function runStickerPackCommand(argv) {
         // A manifest so the next step (place/keyframes, or an agent picking props by
         // name) doesn't have to re-derive what's in the pack.
         const manifestPath = path.join(outDir, "stickers.json");
+        const keyReport = {
+            key_mode: keyMode,
+            sheet_mode: zonesUsed.length > 1 ? "zoned" : "flat",
+            zones: zonesUsed.map((z, i) => ({ panel: i + 1, x: z.x, y: z.y, width: z.width, height: z.height, plate: z.hex, keyed_pct: smart?.stats.perZone[i]?.keyed_pct ?? null })),
+            keyed_pct: smart?.stats.keyed_pct ?? null,
+            protected_px: smart?.stats.protected_px ?? null,
+            protected_pct: smart?.stats.protected_pct ?? null,
+            key_note: keyNote,
+            empty_panel_note: emptyPanelNote,
+            refined: refine
+        };
         writeFileSync(manifestPath, `${JSON.stringify({
             generated_from: generatePrompt ? "generate" : sourceArg,
             key_color: keyColor,
             key_color_auto: plateAuto,
+            ...keyReport,
             hollow: seg.hollow,
             hollow_note: hollowNote,
             sheet_width: seg.sourceWidth,
@@ -6518,12 +6890,14 @@ async function runStickerPackCommand(argv) {
             stickers: written
         }, null, 2)}\n`);
         if (ctx.json) {
-            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, hollow: seg.hollow, hollow_note: hollowNote, stickers: written });
+            printJson({ ok: true, target: "local", out_dir: outDir, manifest: manifestPath, count: written.length, skipped_specks: seg.rejected, key_color: keyColor, key_color_auto: plateAuto, key_color_note: plateNote, ...keyReport, hollow: seg.hollow, hollow_note: hollowNote, stickers: written });
         }
         else {
             console.log(`${GREEN}Sticker pack ready:${RESET} ${written.length} transparent sticker${written.length === 1 ? "" : "s"} in ${outDir} ${DIM}(manifest: stickers.json${seg.rejected ? `, ${seg.rejected} speck(s) skipped` : ""})${RESET}`);
-            if (itemNames.length && itemNames.length !== written.length) {
-                console.log(`${YELLOW}Note:${RESET} ${DIM}you named ${itemNames.length} item(s) but ${written.length} were cut, so names may be off-by-one. Re-run with --dry-run to inspect the boxes; two touching items segment as ONE (lower --gap or ask the generator for wider spacing), and one item split in two segments as TWO (raise --gap).${RESET}`);
+            // Names are only guessed by reading order on a FLAT sheet; a zoned sheet
+            // pins each name to its panel, so the off-by-one caveat doesn't apply.
+            if (itemNames.length && itemNames.length !== written.length && !zonePlan) {
+                console.log(`${YELLOW}Note:${RESET} ${DIM}you named ${itemNames.length} item(s) but ${written.length} were cut, so names may be off-by-one. Re-run with --dry-run to inspect the boxes; two touching items segment as ONE (lower --gap or ask the generator for wider spacing), and one item split in two segments as TWO (raise --gap). A zoned sheet (--sheet-mode zoned) names items by PANEL instead of by order, which can't drift.${RESET}`);
             }
             console.log(`${DIM}Place one: vidfarm place <dir> --src "${written[0]?.file}" --kind image. Animate it (pop-in/float/shake/drift) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe.${RESET}`);
         }
@@ -8861,6 +9235,7 @@ async function runHandoffCommand(argv) {
             "out-dir": { type: "string" },
             grid: { type: "string" },
             single: { type: "boolean", default: false },
+            zoned: { type: "boolean", default: false },
             // raws
             keywords: { type: "string" },
             platforms: { type: "string" },
@@ -8883,7 +9258,8 @@ async function runHandoffCommand(argv) {
             keyColor: parsed.values["key-color"],
             outDir: parsed.values["out-dir"],
             grid: parsed.values.grid,
-            pack: parsed.values.single ? false : undefined
+            pack: parsed.values.single ? false : undefined,
+            zoned: Boolean(parsed.values.zoned)
         });
         if (json)
             return printJson({ ok: true, kind: "image", pack: !parsed.values.single, ...brief });