@officexapp/vidfarm-devcli 0.21.29 → 0.21.31

package/dist/src/cli.js

@@ -22,7 +22,7 @@ import { renderCompositionStills } from "./devcli/stills.js";
 import { extractCompositionFacts, formatQaReport, qaCompositionHtml } from "./devcli/qa-check.js";
 import { discoverRegime, formatRegimeReport, listBuiltinRegimes, loadAndEvaluateRegime, mergeRegimeIntoReport, parseRegime, resolveRegimePath } from "./devcli/qa-regime.js";
 import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
-import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor } from "./devcli/sticker-pack.js";
+import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, analyzeKeyedArt, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -351,7 +351,10 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             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. Local, free, ffmpeg-only. Image-only.
+                            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.
+                            Local, free, ffmpeg-only. Image-only.
                             (aliases: stickers, sticker-sheet)
     --generate "<theme>"    AI-generate the sheet first (ONE billed image job for
                             the WHOLE pack) on a spaced grid over a chroma plate
@@ -808,6 +811,19 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     --content-type <a,b>    With --search: filter the /raws branch by shot-KIND tag
                             (talking_head,b_roll,product_shot,screen_recording,demo,
                             reaction,interview,establishing,lifestyle,text_graphic)
+  recycle <source>          PAID. RECYCLE a Reddit or X/Twitter source into reusable JSON —
+                            "tweet to tiktok" / "reddit to tiktok". Accepts a Reddit thread URL
+                            (post + comments), a subreddit (r/name or URL -> its threads), an X
+                            thread URL (tweet + replies), or an X profile (@handle or URL -> their
+                            posts). Returns items[] with text, author + avatar, stats, permalinks
+                            and every image/video media URL - unranked and unsummarized, so YOU
+                            pick what to remix. Brokered through the reddit-lead-gen / x-lead-gen
+                            OfficeX apps, billed on the credits they consume.
+                            Flags: --max-records N (spend ceiling, default 100) --cursor <token>
+                            --query <text> --filter hot|new|top --mode <mode> --network <net>
+                            --no-comments --no-profile --out ./recycled.json --no-wait
+                            Aliases: recycle-social, tweet-to-video, reddit-to-video
+                            -> POST /api/v1/primitives/social/recycle
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
   annotate-file <id|name>   Set metadata notes on one My Files entry     → PATCH /api/v1/user/me/attachments/:id
@@ -1179,6 +1195,13 @@ async function main() {
         case "download-audio":
             await runDownloadPostAudioCommand(rest);
             return;
+        // "tweet to tiktok" / "reddit to tiktok": decompose a social source to JSON.
+        case "recycle-social":
+        case "tweet-to-video":
+        case "reddit-to-video":
+        case "recycle":
+            await runRecycleCommand(rest);
+            return;
         case "files":
             await runFilesCommand(rest);
             return;
@@ -5303,9 +5326,12 @@ function cutoutPlateInstruction(keyColorHex) {
             : /^#?ff00ff$/i.test(keyColorHex) ? "solid magenta"
                 : `a solid flat ${keyColorHex}`;
     return (`Isolated subject on a completely flat, evenly-lit ${named} (${keyColorHex}) background — ` +
-        `like a green-screen plate. The subject must contain NONE of that background color anywhere on it. ` +
+        `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.`);
+        `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));
 }
 async function runCutoutCommand(argv) {
     const parsed = parseArgs({
@@ -5482,6 +5508,16 @@ async function runCutoutCommand(argv) {
         const shrinkPct = trim.origWidth && trim.origHeight && trim.width && trim.height
             ? Math.round((1 - (trim.width * trim.height) / (trim.origWidth * trim.origHeight)) * 100)
             : null;
+        // Did the key eat the ART as well as the plate? Outline-only art (interior
+        // 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;
         if (ctx.json) {
             printJson({
                 ok: true,
@@ -5495,13 +5531,18 @@ async function runCutoutCommand(argv) {
                 trimmed: trim.trimmed,
                 area_reduced_pct: shrinkPct,
                 bytes: safeSize(trim.outputPath),
-                key_color: keyColor
+                key_color: keyColor,
+                hole_pct: art?.hole_pct ?? null,
+                hollow: art?.hollow ?? false,
+                hollow_note: hollowNote
             });
         }
         else {
             console.log(`${GREEN}Cutout ready:${RESET} ${trim.outputPath} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(trim.outputPath))}${trim.trimmed && shrinkPct !== null ? `, −${shrinkPct}% area` : ""})${RESET}`);
             if (!trim.trimmed && !noTrim)
                 console.log(`${YELLOW}Note:${RESET} ${DIM}no transparent margin to trim — the subject already reached the edges, or the plate keyed to fully transparent (check --preset/--key-color).${RESET}`);
+            if (hollowNote)
+                console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
             console.log(`${DIM}Drop it on a composition: vidfarm place <dir> --src "${trim.outputPath}" --kind image [--ken-burns zoom-in]. Animate it (zoom/grow/shake/move) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe.${RESET}`);
         }
     }
@@ -5722,8 +5763,9 @@ function stickerSheetInstruction(keyColorHex, count, items) {
         `${named} (${keyColorHex}) background. ${list} ` +
         `CRITICAL: every item must be fully separated from the others by a clear margin of plain ${keyColorHex} background — ` +
         `nothing touching, overlapping, or connected. Keep a wide ${keyColorHex} margin around the edges of the sheet too. ` +
-        `No item may contain that background color anywhere on it. 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.`);
+        `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));
 }
 async function runStickerPackCommand(argv) {
     const parsed = parseArgs({
@@ -5930,16 +5972,37 @@ 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).");
         }
+        // ---- 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
+        // as bare plate) or filled in a near-plate shade. It looks fine on the sheet
+        // and only shows up once the sticker composites over a real background — so
+        // say it here, loudly, with the fix. A ring/donut/frame reads the same way,
+        // 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.)`;
+            if (!ctx.json)
+                console.log(`${YELLOW}Hollow:${RESET} ${DIM}${hollowNote}${RESET}`);
+        }
         if (parsed.values["dry-run"]) {
             // 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, 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_color: keyColor, key_color_auto: plateAuto, hollow: seg.hollow, hollow_note: hollowNote, items: seg.components });
             }
             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) {
-                    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}`);
+                    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}`);
                 }
                 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}`);
             }
@@ -5973,10 +6036,14 @@ async function runStickerPackCommand(argv) {
                 height: trim.height,
                 sheet_crop: { x: c.x, y: c.y, width: c.width, height: c.height },
                 area_pct: c.area_pct,
+                holes: c.holes,
+                hole_pct: c.hole_pct,
+                hollow: c.hole_pct >= HOLE_WARN_PCT,
                 bytes: safeSize(finalPath)
             });
             if (!ctx.json) {
-                console.log(`  ${GREEN}✓${RESET} ${path.relative(process.cwd(), finalPath)} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(finalPath))})${RESET}`);
+                const hollowFlag = c.hole_pct >= HOLE_WARN_PCT ? ` ${YELLOW}⚠ ${c.hole_pct}% hollow${RESET}` : "";
+                console.log(`  ${GREEN}✓${RESET} ${path.relative(process.cwd(), finalPath)} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(finalPath))})${RESET}${hollowFlag}`);
             }
         }
         // A manifest so the next step (place/keyframes, or an agent picking props by
@@ -5986,6 +6053,8 @@ async function runStickerPackCommand(argv) {
             generated_from: generatePrompt ? "generate" : sourceArg,
             key_color: keyColor,
             key_color_auto: plateAuto,
+            hollow: seg.hollow,
+            hollow_note: hollowNote,
             sheet_width: seg.sourceWidth,
             sheet_height: seg.sourceHeight,
             format: wantGif ? "gif" : stillExt,
@@ -5993,7 +6062,7 @@ 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, 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, 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}`);
@@ -8254,6 +8323,118 @@ async function runDownloadPostCommand(argv) {
     const final = await pollPrimitiveJob(ctx, jobId);
     emitPrimitiveJobResult(ctx, final, "download-post");
 }
+async function runRecycleCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            "max-records": { type: "string" },
+            cursor: { type: "string" },
+            query: { type: "string" },
+            filter: { type: "string" },
+            sort: { type: "string" },
+            mode: { type: "string" },
+            network: { type: "string" },
+            "no-comments": { type: "boolean", default: false },
+            "no-profile": { type: "boolean", default: false },
+            out: { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const source = parsed.positionals[0];
+    if (!source) {
+        throw new Error("recycle requires a Reddit or X/Twitter source — a thread URL, a subreddit (r/name), a profile URL, or @handle.");
+    }
+    const maxRecords = parsed.values["max-records"] ? Number(parsed.values["max-records"]) : undefined;
+    if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1 || maxRecords > 1000)) {
+        throw new Error("recycle --max-records must be an integer between 1 and 1000.");
+    }
+    const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "recycle a Reddit/X source into JSON (paid plan — brokered via the OfficeX lead-gen apps)",
+        estimate: maxRecords && maxRecords > 100
+            ? "several cents (max-records drives upstream pagination)"
+            : "~$0.002-$0.02 per pull",
+        freeAlternative: "open the thread in a browser and copy the text you want by hand"
+    });
+    // A bare handle/subreddit is ambiguous without a network; a URL is not.
+    const looksLikeUrl = /^https?:\/\//i.test(source) || source.includes(".com/");
+    const payload = looksLikeUrl ? { source_url: source } : { handle: source };
+    if (!looksLikeUrl && parsed.values.network)
+        payload.network = String(parsed.values.network);
+    if (parsed.values.mode)
+        payload.mode = String(parsed.values.mode);
+    if (maxRecords !== undefined)
+        payload.max_records = maxRecords;
+    if (parsed.values.cursor)
+        payload.cursor = String(parsed.values.cursor);
+    if (parsed.values.query)
+        payload.query = String(parsed.values.query);
+    if (parsed.values.filter)
+        payload.filter = String(parsed.values.filter);
+    if (parsed.values.sort)
+        payload.sort = String(parsed.values.sort);
+    if (parsed.values["no-comments"])
+        payload.include_comments = false;
+    if (parsed.values["no-profile"])
+        payload.include_profile = false;
+    const tracer = String(parsed.values.tracer ?? `devcli-recycle-${Date.now().toString(36)}`);
+    const submit = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/primitives/social/recycle",
+        auth: ctx.auth,
+        body: { tracer, payload }
+    });
+    assertApiOk(submit, "recycle");
+    const jobId = submit.json?.job_id;
+    if (!jobId || parsed.values["no-wait"]) {
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json) {
+        console.log(`${DIM}Recycling ${source} (${jobId})… the upstream lead-gen job is polled server-side.${RESET}`);
+    }
+    const final = await pollPrimitiveJob(ctx, jobId);
+    // --out writes the FULL normalized payload to disk; the job result inlines
+    // only a prefix when the item list is large.
+    const outPath = parsed.values.out ? String(parsed.values.out) : null;
+    if (outPath) {
+        const result = (final?.result ?? {});
+        const recycledUrl = result.recycled?.url
+            ?? result.primary_file_url;
+        if (typeof recycledUrl === "string" && recycledUrl) {
+            const res = await fetch(recycledUrl);
+            if (res.ok) {
+                mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+                writeFileSync(path.resolve(outPath), await res.text());
+                if (!ctx.json)
+                    console.log(`${DIM}Wrote full recycled JSON → ${outPath}${RESET}`);
+            }
+            else if (!ctx.json) {
+                console.warn(`[vidfarm] could not fetch recycled.json (${res.status}) — the job result still has it.`);
+            }
+        }
+    }
+    if (!ctx.json) {
+        const result = (final?.result ?? {});
+        const counts = (result.counts ?? {});
+        console.log(`${DIM}mode=${String(result.mode ?? "?")} items=${String(counts.items ?? "?")} `
+            + `(posts=${String(counts.posts ?? "?")} comments=${String(counts.comments ?? "?")}) `
+            + `media=${String(counts.media ?? "?")} credits=${String(counts.credits_charged ?? "?")}${RESET}`);
+        for (const job of result.upstreamJobs ?? []) {
+            if (typeof job.view_url === "string" && job.view_url) {
+                console.log(`${DIM}  browse ${String(job.endpoint)} in a spreadsheet: ${job.view_url}${RESET}`);
+            }
+        }
+        if (result.nextCursor) {
+            console.log(`${DIM}  more available — re-run with --cursor ${String(result.nextCursor).slice(0, 24)}…${RESET}`);
+        }
+    }
+    emitPrimitiveJobResult(ctx, final, "recycle");
+}
 async function runDownloadPostAudioCommand(argv) {
     const parsed = parseArgs({
         args: argv,

package/dist/src/devcli/doctor.js

@@ -15,6 +15,7 @@ import { parseArgs } from "node:util";
 import { detectLocalAgent } from "../services/clip-curation/index.js";
 import { hasFfmpeg, resolveFfmpeg, resolveFfprobe } from "../services/clip-curation/ffmpeg.js";
 import { resolveHyperframesCli } from "./hyperframes-cli.js";
+import { applyVidfarmStudioBrand } from "./studio-brand.js";
 import { resolveSkillsRoot } from "./skills.js";
 import { readStoredAuth } from "./auth-store.js";
 import { scanLocalServers, reapProcesses } from "./process-scan.js";
@@ -138,6 +139,18 @@ export async function runDoctorCommand(argv) {
     add("hyperframes", hyperframesCli ? "ok" : "warn", hyperframesCli
         ? `${hyperframesCli} (Vidfarm's whitelabel render/animation engine — reach it via \`vidfarm hf …\`)`
         : "not installed — Vidfarm's render/animation engine (open-source whitelabel). Install for native local render/tts/stt/matting: `npm i -g hyperframes` (else falls back to slow `npx -y hyperframes`)");
+    // 3b. Whitelabel the LOCAL studio shell (the `hyperframes preview` editor UI),
+    // which otherwise renders the upstream "HeyGen · HyperFrames" header logo and
+    // tab title. `doctor` REPAIRS it rather than just reporting: the patch is
+    // idempotent and a fresh `npm install` restores the pristine shell.
+    if (hyperframesCli) {
+        const brand = applyVidfarmStudioBrand();
+        add("studio branding", brand === "unavailable" ? "warn" : "ok", brand === "patched"
+            ? "local studio shell re-branded as VidFarm (upstream logo/title replaced)"
+            : brand === "already-branded"
+                ? "local studio shell already whitelabeled as VidFarm"
+                : "could not patch the local studio shell — `hyperframes preview` will show upstream branding (cosmetic only)");
+    }
     // 4. Chrome for the in-process render (stills / serve local render).
     const chrome = detectChromeForRender();
     add("chrome", chrome.found ? "ok" : "warn", chrome.found ? chrome.detail : `${chrome.detail} — local render/stills will try to download one on first run`);

package/dist/src/devcli/handoff.js

@@ -22,7 +22,7 @@
 // Both builders return plain text meant to be shown verbatim to the user, plus a
 // structured form for `--json` so an agent can render it its own way. No network,
 // no backend imports — this module is pure string assembly.
-import { pickPlateColor } from "./sticker-pack.js";
+import { pickPlateColor, keySafeArtInstruction } from "./sticker-pack.js";
 const DEFAULT_STYLE = "simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows, no text";
 /** Pick a sensible grid for N items (roughly square, wider than tall). */
 function gridFor(count) {
@@ -67,18 +67,22 @@ export function buildImageHandoff(input) {
             `CRITICAL: every object must be fully separated from the others by a clear margin of plain ${keyColor} background —`,
             `nothing touching, overlapping or connected, and nothing touching the image edge.`,
             `One consistent art style, line weight and palette across all objects. Front-facing, centered in its own cell.`,
+            // Load-bearing: the user is about to spend their own time on this sheet,
+            // and hollow/outline-only art comes back as rims around holes.
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ")
         : [
             `${input.theme} — ${style} — isolated on a solid pure ${keyColor} background`,
             `(flat, evenly lit, no gradient, no shadow cast on the background, no text).`,
             `Center the subject with generous empty margin on all sides, crisp clean edges, single subject.`,
+            keySafeArtInstruction(keyColor),
             `Square image, high resolution.`
         ].join(" ");
     const steps = pack
         ? [
             "Open a FREE image generator you're already signed into (list below).",
-            "Paste the prompt below and generate. If any two objects come out touching, re-generate asking for wider spacing — touching objects get cut out as one sticker.",
+            "Paste the prompt below and generate. Two checks before you send it back: (a) if any two objects are touching, re-generate asking for wider spacing — touching objects get cut out as ONE sticker; (b) if any object is a hollow outline with the background showing through its middle, re-generate asking for solid fills — that interior gets deleted with the background and the sticker ends up as a rim around a hole.",
             "Download the image (PNG preferred) and tell me the file path — or drop it in this project folder.",
             `I'll split it into individual transparent stickers locally for $0: \`vidfarm sticker-pack <sheet> --out-dir ${outDir}\`.`
         ]

package/dist/src/devcli/hyperframes-cli.js

@@ -49,6 +49,18 @@ export async function runHyperframesCommand(subcommand, args, opts = {}) {
             "Local engines and vidfarm BYOK keys are the only auth.");
     }
     const cli = resolveHyperframesCli();
+    // The local studio SPA shell ships upstream branding (a "HeyGen · HyperFrames"
+    // header logo and a "HyperFrames Studio" tab title) that `hyperframes preview`
+    // serves straight off disk — the one Vidfarm surface the web editor's own
+    // rebrand never reaches. Whitelabel the shell on EVERY hyperframes spawn, not
+    // just preview: the patch is a cheap idempotent file check, and doing it here
+    // means a director who later runs `hyperframes preview` by hand still gets the
+    // VidFarm studio. Best-effort — branding never fails a render.
+    try {
+        const { applyVidfarmStudioBrand } = await import("./studio-brand.js");
+        applyVidfarmStudioBrand();
+    }
+    catch { /* cosmetic only */ }
     // Fresh empty config dir per invocation — guarantees no ~/.heygen credential
     // (or any other persisted account state) leaks into the child process.
     const emptyConfigDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-hf-noauth-"));

package/dist/src/devcli/sticker-pack.js

@@ -132,6 +132,42 @@ export async function detectPlateColor(sourcePath, opts = {}) {
     const hex = `#${avg.map((v) => v.toString(16).padStart(2, "0")).join("").toUpperCase()}`;
     return { hex, rgb: avg };
 }
+// ── Key-safe ART instruction ─────────────────────────────────────────────────
+// Picking a plate the art doesn't use (above) is only HALF of surviving a chroma
+// key. The other half is what the art is made of, and it's the failure we see in
+// the wild: an image model hears "sticker on a green plate" and draws OUTLINE
+// art — a colored stroke with the shape's interior left as bare background. On
+// screen that looks fine. After the key, the interior is gone, and the sticker
+// composites as a rim floating around a see-through hole.
+//
+// The same failure arrives three other ways: a fill that's a near-shade of the
+// plate (keyed by tolerance, not by exact match), a translucent/glassy material
+// that lets the plate through, and a soft glow/drop-shadow that fades INTO the
+// plate at the edges.
+//
+// All four are prompt-preventable, so every generation path that mints art
+// destined for a key (cutout, sticker-pack, the hand-off brief the user pastes
+// into a free web tool) appends this clause. Detection after the fact is the net
+// (`detectEnclosedHoles` below) — this is the mechanism.
+/**
+ * The "your art has to survive the key" clause, worded for an image model.
+ * Append to any prompt whose output will be chroma-keyed on `keyColorHex`.
+ */
+export function keySafeArtInstruction(keyColorHex) {
+    const hex = keyColorHex.toUpperCase();
+    return (`KEY-SAFE ARTWORK (the ${hex} background gets deleted, so anything ${hex} on the art is deleted too): ` +
+        `every object must be a CLOSED, SOLIDLY FILLED shape — outlines and strokes must enclose an opaque fill of a ` +
+        `different color. NO outline-only / hollow / line-art objects, and never leave a shape's interior as bare ` +
+        `background. No part of any object — fill, outline, highlight, gradient, glow, shading or detail — may be ${hex} ` +
+        `or any near-shade, tint or tone of ${hex}. No transparent, translucent, glassy, glowing, misty or ghosted ` +
+        `materials; every pixel of every object is fully opaque. No soft glows, blurs or drop shadows fading into the ` +
+        `background. Keep the whole palette in strong contrast to ${hex}. The background must be visible ONLY around the ` +
+        `outside of the objects, never showing through inside them.`);
+}
+/** At/above this `hole_pct` a sticker is worth warning about: past ~a fifth of
+ *  its own box, "the key ate the fill" is far more likely than "the artist drew
+ *  a ring". Tuned to stay quiet on letter counters, handles and small gaps. */
+export const HOLE_WARN_PCT = 20;
 /** Read a still's alpha plane as raw 8-bit luma at a given size (bundle-safe:
  *  ffmpeg's `alphaextract` writes alpha as luma; rawvideo skips any decoding on
  *  our side). Returns exactly width*height bytes. */
@@ -199,6 +235,93 @@ function dilate(mask, w, h, radius) {
     }
     return out;
 }
+/**
+ * Find transparent islands that are fully SURROUNDED by opaque art — the exact
+ * signature of the "hollow sticker" bug: art drawn as an outline (or filled in a
+ * near-plate shade) has its middle deleted by the key, and composites as a rim
+ * around a see-through hole.
+ *
+ * Mechanically it's the complement of a background flood-fill: every transparent
+ * pixel reachable from the mask's border is the plate doing its job; every
+ * transparent pixel that is NOT reachable is a hole punched inside something.
+ * 4-connected on purpose — an 8-connected fill leaks through a 1px diagonal
+ * seam in antialiased line art and would under-report every real hole.
+ *
+ * Note this cannot distinguish a bug from a deliberate ring/donut/picture-frame,
+ * so callers WARN on the result, never reject it.
+ */
+export function detectEnclosedHoles(mask, w, h, opts = {}) {
+    const reachable = new Uint8Array(w * h);
+    const queue = new Int32Array(w * h);
+    let head = 0;
+    let tail = 0;
+    const push = (p) => {
+        if (!mask[p] && !reachable[p]) {
+            reachable[p] = 1;
+            queue[tail++] = p;
+        }
+    };
+    for (let x = 0; x < w; x++) {
+        push(x);
+        push((h - 1) * w + x);
+    }
+    for (let y = 0; y < h; y++) {
+        push(y * w);
+        push(y * w + (w - 1));
+    }
+    while (head < tail) {
+        const p = queue[head++];
+        const py = (p / w) | 0;
+        const px = p - py * w;
+        if (px > 0)
+            push(p - 1);
+        if (px < w - 1)
+            push(p + 1);
+        if (py > 0)
+            push(p - w);
+        if (py < h - 1)
+            push(p + w);
+    }
+    // Anything transparent and unreached is enclosed — group it into islands.
+    const minAreaPx = Math.max(1, Math.round(opts.minAreaPx ?? 4));
+    const seen = new Uint8Array(w * h);
+    const holes = [];
+    const stack = new Int32Array(w * h);
+    for (let start = 0; start < mask.length; start++) {
+        if (mask[start] || reachable[start] || seen[start])
+            continue;
+        let top = 0;
+        stack[top++] = start;
+        seen[start] = 1;
+        const hole = { minX: w, minY: h, maxX: -1, maxY: -1, area: 0 };
+        while (top > 0) {
+            const p = stack[--top];
+            const py = (p / w) | 0;
+            const px = p - py * w;
+            hole.area++;
+            if (px < hole.minX)
+                hole.minX = px;
+            if (px > hole.maxX)
+                hole.maxX = px;
+            if (py < hole.minY)
+                hole.minY = py;
+            if (py > hole.maxY)
+                hole.maxY = py;
+            const neighbors = [px > 0 ? p - 1 : -1, px < w - 1 ? p + 1 : -1, py > 0 ? p - w : -1, py < h - 1 ? p + w : -1];
+            for (const q of neighbors) {
+                if (q < 0 || mask[q] || reachable[q] || seen[q])
+                    continue;
+                seen[q] = 1;
+                stack[top++] = q;
+            }
+        }
+        // Sub-threshold islands are antialiasing dropouts and despill speckle, not
+        // a missing fill — a real hollow interior is orders of magnitude bigger.
+        if (hole.area >= minAreaPx)
+            holes.push(hole);
+    }
+    return holes;
+}
 /**
  * Find every item on a keyed plate by segmenting its alpha channel into
  * connected islands of opaque pixels — the automatic replacement for measuring
@@ -312,22 +435,93 @@ export async function segmentAlphaComponents(input) {
     // ---- Map sample-space boxes back to source pixels --------------------------
     // One sample pixel of slack on each side covers the downscale's rounding, so a
     // subject's outermost antialiased edge never gets clipped off.
+    // ---- Attribute enclosed holes to the item that surrounds them --------------
+    // A hole lives strictly inside the art that encloses it, so its center falls
+    // in that item's box. Boxes can nest (a small icon inside a big backdrop), so
+    // the SMALLEST containing box wins — the nearest enclosing art is the owner.
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = new Array(ordered.length).fill(0);
+    const holeCount = new Array(ordered.length).fill(0);
+    for (const hole of holes) {
+        const cx = (hole.minX + hole.maxX) / 2;
+        const cy = (hole.minY + hole.maxY) / 2;
+        let owner = -1;
+        let ownerArea = Infinity;
+        for (let i = 0; i < ordered.length; i++) {
+            const b = ordered[i];
+            if (cx < b.minX || cx > b.maxX || cy < b.minY || cy > b.maxY)
+                continue;
+            const boxArea = (b.maxX - b.minX + 1) * (b.maxY - b.minY + 1);
+            if (boxArea < ownerArea) {
+                owner = i;
+                ownerArea = boxArea;
+            }
+        }
+        if (owner >= 0) {
+            holeArea[owner] += hole.area;
+            holeCount[owner]++;
+        }
+    }
     const inv = 1 / scale;
     const components = ordered.map((b, i) => {
         const x0 = Math.max(0, Math.floor((b.minX - 1) * inv));
         const y0 = Math.max(0, Math.floor((b.minY - 1) * inv));
         const x1 = Math.min(dims.width, Math.ceil((b.maxX + 2) * inv));
         const y1 = Math.min(dims.height, Math.ceil((b.maxY + 2) * inv));
+        // Measured against the item's own silhouette (fill + holes), not the plate:
+        // "a fifth of THIS sticker is missing" is the question that matters.
+        const silhouette = b.area + holeArea[i];
         return {
             index: i + 1,
             x: x0,
             y: y0,
             width: Math.max(1, x1 - x0),
             height: Math.max(1, y1 - y0),
-            area_pct: Math.round((b.area / total) * 1000) / 10
+            area_pct: Math.round((b.area / total) * 1000) / 10,
+            holes: holeCount[i],
+            hole_pct: silhouette > 0 ? Math.round((holeArea[i] / silhouette) * 1000) / 10 : 0
         };
     });
-    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected };
+    const hollow = components.filter((c) => c.hole_pct >= HOLE_WARN_PCT).map((c) => c.index);
+    return { components, sourceWidth: dims.width, sourceHeight: dims.height, sampleWidth: sw, sampleHeight: sh, rejected, hollow };
+}
+/**
+ * The single-subject version of the hollow-sticker check: does THIS keyed still
+ * have transparency punched through the middle of its art? Used by `cutout`,
+ * which has one subject and so needs no segmentation — just the same
+ * background-flood-fill complement over the whole alpha plane.
+ */
+export async function analyzeKeyedArt(sourcePath) {
+    if (!existsSync(sourcePath))
+        return null;
+    const dims = await probeImageDimensions(sourcePath);
+    if (!dims)
+        return null;
+    const longSide = Math.max(dims.width, dims.height);
+    const scale = longSide > 640 ? 640 / longSide : 1;
+    const sw = Math.max(1, Math.round(dims.width * scale));
+    const sh = Math.max(1, Math.round(dims.height * scale));
+    let alpha;
+    try {
+        alpha = await readAlphaPlane(sourcePath, sw, sh);
+    }
+    catch {
+        return null; // no alpha channel to read → nothing to say
+    }
+    const mask = new Uint8Array(sw * sh);
+    let opaque = 0;
+    for (let i = 0; i < mask.length; i++)
+        if (alpha[i] > 8) {
+            mask[i] = 1;
+            opaque++;
+        }
+    if (!opaque)
+        return null;
+    const total = sw * sh;
+    const holes = detectEnclosedHoles(mask, sw, sh, { minAreaPx: Math.max(6, Math.round(total * 0.00005)) });
+    const holeArea = holes.reduce((sum, h) => sum + h.area, 0);
+    const hole_pct = Math.round((holeArea / (opaque + holeArea)) * 1000) / 10;
+    return { holes: holes.length, hole_pct, hollow: hole_pct >= HOLE_WARN_PCT };
 }
 /**
  * Re-encode a transparent still as a transparent GIF — the format a lot of