@officexapp/vidfarm-devcli 0.21.28 → 0.21.30

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

@@ -0,0 +1,162 @@
+// Interactive-mode HAND-OFF briefs — the copy-paste packets an agent gives the
+// human when the pair (cost mode × interaction mode) says "a human step here
+// beats spending, and beats going without".
+//
+// Two hand-offs cover almost every real case:
+//
+//   1. IMAGES (`buildImageHandoff`) — the agent writes the prompt, the user runs
+//      it in a FREE frontier web generator (meta.ai / ChatGPT / Gemini / a
+//      Hugging Face Space) and drops the file back. Defaults to a STICKER PACK:
+//      one prompt → one greenscreen sheet holding every graphic → `vidfarm
+//      sticker-pack` splits it into many transparent stickers locally. One round
+//      trip for a whole cast is both the cheapest thing for the user's time and
+//      the most token-efficient thing for the agent.
+//
+//   2. RAW CLIPS (`buildRawsHandoff`) — the agent hands over search keywords and
+//      where to search, the user downloads a few clips with a free online
+//      downloader and points the agent at the folder. This is the LAST rung of
+//      the sourcing ladder: an agent should first try its own browser control,
+//      then vidfarm's cloud scan, and only ask the human when neither is
+//      available (fully-local, keyless devcli) or when human taste matters.
+//
+// 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";
+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) {
+    if (count <= 1)
+        return "1x1";
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    return `${cols}x${rows}`;
+}
+/**
+ * Build the free-image-generation hand-off. Sticker-pack shaped by default: ONE
+ * image containing every item on a flat chroma plate, generously spaced, which
+ * `vidfarm sticker-pack` then splits into individually-trimmed transparent
+ * stickers. The spacing/no-touching instruction is load-bearing — items that
+ * touch on the sheet segment as a single sticker.
+ */
+export function buildImageHandoff(input) {
+    // Plate choice matters MORE here than anywhere else: the user is about to
+    // spend their own effort generating this sheet, and a green plate under green
+    // art means the stickers come back with holes. Pick the plate off the subject
+    // unless the caller pinned one.
+    const picked = pickPlateColor([input.theme, input.items.join(" "), input.style ?? ""].join(" "));
+    const keyColor = (input.keyColor ?? picked.keyColor).toUpperCase();
+    const keyColorNote = input.keyColor
+        ? null
+        : picked.moved
+            ? `Plate moved off green to ${picked.preset} (${picked.keyColor}) — ${picked.reason}. A green plate would key holes through green artwork.`
+            : picked.reason;
+    const style = input.style?.trim() || DEFAULT_STYLE;
+    const items = input.items.map((s) => s.trim()).filter(Boolean);
+    const pack = input.pack ?? items.length > 1;
+    const outDir = input.outDir ?? "./stickers";
+    const grid = input.grid ?? gridFor(items.length || 6);
+    const prompt = pack
+        ? [
+            `A sticker sheet of ${items.length || "several"} separate objects — ${style} — on a solid pure ${keyColor} background`,
+            `(flat, evenly lit, no gradient, no shadow, no text, no labels, no frames or dividing lines).`,
+            `Theme: ${input.theme}.`,
+            items.length
+                ? `Arranged in a ${grid} grid with generous even spacing: ${items.map((it, i) => `(${i + 1}) ${it}`).join(", ")}.`
+                : `Arranged in a ${grid} grid with generous even spacing.`,
+            `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.`,
+            `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.`,
+            `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.",
+            "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}\`.`
+        ]
+        : [
+            "Open a FREE image generator you're already signed into (list below).",
+            "Paste the prompt below and generate.",
+            "Download the image (PNG preferred) and tell me the file path.",
+            "I'll key the background out and trim it to a snug transparent sticker locally for $0: `vidfarm cutout <file>`."
+        ];
+    const keyFlag = keyColor === "#00FF00" ? "" : ` --key-color "${keyColor}"`;
+    const followUp = pack
+        ? `vidfarm sticker-pack <downloaded-sheet.png>${items.length ? ` --items "${items.join(",")}"` : ""}${keyFlag} --out-dir ${outDir}`
+        : `vidfarm cutout <downloaded.png>${keyFlag}`;
+    return {
+        prompt,
+        steps,
+        followUp,
+        keyColor,
+        keyColorNote,
+        tools: [
+            "https://meta.ai (free, generous)",
+            "ChatGPT free tier (image generation included)",
+            "Google Gemini free tier",
+            "a free image Space on https://huggingface.co/spaces (search \"flux\" or \"sdxl\")"
+        ]
+    };
+}
+/**
+ * Build the manual raw-clip sourcing hand-off. Deliberately does NOT name one
+ * downloader site: those rot, get blocked, and vary by region — so the brief
+ * hands over a SEARCH for a downloader instead, which stays correct forever.
+ */
+export function buildRawsHandoff(input) {
+    const keywords = input.keywords.map((k) => k.trim()).filter(Boolean);
+    if (!keywords.length)
+        throw new Error("A raws hand-off needs at least one search keyword.");
+    const platforms = (input.platforms?.length ? input.platforms : ["tiktok", "youtube"]).map((p) => p.trim().toLowerCase());
+    const count = input.count ?? Math.max(3, keywords.length * 2);
+    const outDir = input.outDir ?? "./downloads";
+    const searchLines = keywords.map((k) => `  • "${k}"`).join("\n");
+    const prompt = [
+        `Search these keywords on ${platforms.join(" / ")} and download ${count} clips you like:`,
+        searchLines,
+        "",
+        `To download: search Google for a downloader — https://google.com/search?q=${encodeURIComponent(`${platforms[0]} video downloader`)} — and use whichever one works today.`
+    ].join("\n");
+    return {
+        prompt,
+        steps: [
+            `Search ${platforms.join(" and ")} for the keywords below.`,
+            input.purpose
+                ? `Pick ${count} clips that fit: ${input.purpose}. Favor clean, well-lit footage with no burned-in captions or watermarks over the subject.`
+                : `Pick ${count} clips with clean, well-lit footage and no burned-in captions or watermarks over the subject.`,
+            `Download them with any free online downloader (google "${platforms[0]} video downloader" — the working one changes often) into ${outDir}.`,
+            `Tell me the folder and I'll import each one into your raws library: \`vidfarm clipper ${outDir}/<file>.mp4\` (whole clip), or \`vidfarm raws scan ${outDir}/<file>.mp4\` to mine short clips out of a long one.`
+        ],
+        followUp: `vidfarm clipper ${outDir}/<file>.mp4   # per download; or: vidfarm raws scan ${outDir}/<file>.mp4`,
+        tools: [
+            `https://google.com/search?q=${encodeURIComponent(`${platforms[0]} video downloader`)}`,
+            ...platforms.map((p) => `https://google.com/search?q=${encodeURIComponent(`${p} ${keywords[0]}`)}`)
+        ]
+    };
+}
+/** Render a brief as the block of text an agent shows the user verbatim. */
+export function formatHandoff(title, brief, opts = {}) {
+    const lines = [];
+    lines.push(title);
+    lines.push("");
+    brief.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+    lines.push(`${opts.promptLabel ?? "─── copy from here ───"}`);
+    lines.push(brief.prompt);
+    lines.push("──────────────────────");
+    lines.push("");
+    lines.push("Free tools:");
+    brief.tools.forEach((t) => lines.push(`  • ${t}`));
+    lines.push("");
+    lines.push(`When the file(s) come back: ${brief.followUp}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=handoff.js.map

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/interaction-mode.js

@@ -0,0 +1,154 @@
+// Interaction mode — is the human IN THE LOOP, or is the agent running solo?
+//
+// This is a SECOND, INDEPENDENT axis from cost mode (cost-mode.ts). Cost mode
+// answers "how much money may I spend?"; interaction mode answers "how much of
+// the user's own time and hands may I use?". Every cost mode can run either
+// way — interactive minimize, autonomous rich-ai, interactive pure-videogen —
+// and the pair is what actually determines the plan.
+//
+//   - interactive : the user is willing to do some manual work in exchange for
+//                   better output. The agent hands them copy-paste briefs at
+//                   fixed checkpoints — an image prompt to run in a free web
+//                   generator, a keyword list to source raw clips with — and
+//                   waits for the files to come back. Quality goes UP, because
+//                   the frontier web models (free tiers) beat what an API-key
+//                   budget usually buys, and a human eye picks better clips than
+//                   any keyword scan. In `minimize` this is the difference
+//                   between "no custom art at all" and "a full sticker pack for
+//                   $0", so ALWAYS offer it there.
+//   - autonomous  : the agent finishes end-to-end with zero user steps. It
+//                   spends (within cost mode) or does without. Faster and
+//                   hands-off; typically a quality floor below interactive.
+//
+// Like cost mode, this is a durable preference the human picks ONCE (`vidfarm
+// mode <interactive|autonomous>`) and every relevant command respects. Unset
+// means "nobody has asked yet" — the agent should ask before it either spends
+// money or silently downgrades quality.
+//
+// Backend-free (Node built-ins only) so it ships in the public cloud-only CLI.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveDevcliHome } from "./auth-store.js";
+export const INTERACTION_MODES = ["interactive", "autonomous"];
+/** What we assume when nothing is set. Autonomous is the safe assumption for a
+ *  running pipeline (never block on a human who isn't there), but `isSet:false`
+ *  is the signal for an agent to ASK — interactive usually wins on quality. */
+export const DEFAULT_INTERACTION_MODE = "autonomous";
+function interactionModeFilePath(home) {
+    return path.join(resolveDevcliHome(home), "interaction-mode.json");
+}
+/** Normalize loose spellings ("manual", "hands-on", "auto", "solo"). */
+export function normalizeInteractionMode(raw) {
+    const v = (raw ?? "").trim().toLowerCase().replace(/[\s_]+/g, "-");
+    if (!v)
+        return null;
+    if (["interactive", "manual", "hands-on", "handson", "collab", "collaborative", "human", "human-in-the-loop", "hitl", "assisted", "guided", "with-me"].includes(v)) {
+        return "interactive";
+    }
+    if (["autonomous", "auto", "automatic", "solo", "hands-off", "handsoff", "unattended", "headless", "agentic", "full-auto"].includes(v)) {
+        return "autonomous";
+    }
+    return null;
+}
+export function readStoredInteractionMode(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(interactionModeFilePath(home), "utf8"));
+        const mode = normalizeInteractionMode(parsed?.mode);
+        if (mode)
+            return { mode, note: parsed.note ?? null, savedAt: String(parsed.savedAt ?? "") };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the interaction mode. Returns the file path written. */
+export function writeStoredInteractionMode(mode, savedAt, note, home) {
+    const dir = resolveDevcliHome(home);
+    mkdirSync(dir, { recursive: true });
+    const file = interactionModeFilePath(home);
+    const payload = { mode, note: note ?? null, savedAt };
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return file;
+}
+export function clearStoredInteractionMode(home) {
+    const file = interactionModeFilePath(home);
+    if (!existsSync(file))
+        return false;
+    rmSync(file, { force: true });
+    return true;
+}
+/**
+ * Resolve the effective interaction mode. Precedence:
+ *   --interaction-mode/--interactive/--autonomous → VIDFARM_INTERACTION_MODE →
+ *   stored preference → default (autonomous, isSet:false).
+ */
+export function resolveInteractionMode(values) {
+    if (values.interactive && !values.autonomous)
+        return { mode: "interactive", isSet: true, source: "flag" };
+    if (values.autonomous && !values.interactive)
+        return { mode: "autonomous", isSet: true, source: "flag" };
+    const flag = normalizeInteractionMode(values["interaction-mode"]);
+    if (flag)
+        return { mode: flag, isSet: true, source: "flag" };
+    const env = normalizeInteractionMode(process.env.VIDFARM_INTERACTION_MODE);
+    if (env)
+        return { mode: env, isSet: true, source: "env" };
+    const stored = readStoredInteractionMode(values.home);
+    if (stored)
+        return { mode: stored.mode, isSet: true, source: "stored" };
+    return { mode: DEFAULT_INTERACTION_MODE, isSet: false, source: "default" };
+}
+export const INTERACTION_MODE_BLURB = {
+    interactive: "Interactive — you're in the loop, and the video gets better for it. At fixed checkpoints the agent " +
+        "hands you a copy-paste brief instead of spending: an IMAGE PROMPT to run in a free web generator " +
+        "(meta.ai / ChatGPT / Gemini / a Hugging Face Space) and drop the PNG back, or a KEYWORD LIST to " +
+        "search TikTok/YouTube and download raw clips with a free online downloader. Frontier web models on " +
+        "their free tiers usually beat what an API budget buys, and a human eye picks better clips than any " +
+        "keyword scan — so quality goes UP, especially in cost mode `minimize` where the alternative is no " +
+        "custom art at all. Manual image work defaults to STICKER PACKS: one prompt → one greenscreen sheet " +
+        "→ `vidfarm sticker-pack` splits it into many transparent stickers.",
+    autonomous: "Autonomous — the agent finishes end-to-end with zero steps from you. No prompts to paste, no files " +
+        "to fetch: it sources clips itself (browser control, the free public raws catalog, cloud scan) and " +
+        "generates art within the cost mode's budget, or does without. Fastest and fully hands-off; the " +
+        "quality ceiling is usually a notch below interactive, and in `minimize` it means custom art simply " +
+        "doesn't happen."
+};
+/** One short human line summarizing the active interaction mode. */
+export function interactionModeSummaryLine(resolved) {
+    const setNote = resolved.isSet ? `set via ${resolved.source}` : "NOT set — assuming autonomous";
+    return `interaction mode: ${resolved.mode} (${setNote})`;
+}
+/** The "explain it simply" block an agent should relay to the user. */
+export function interactionModeExplainer() {
+    return [
+        "Do you want to be in the loop, or should the agent finish on its own?",
+        "  • interactive — you do a little manual work, the video comes out better. At checkpoints you get",
+        "                  a copy-paste IMAGE PROMPT for a free web generator (and drop the PNG back), or a",
+        "                  KEYWORD LIST to hand-source raw clips. Manual images default to sticker packs.",
+        "  • autonomous  — zero steps from you: the agent sources and generates everything itself, within",
+        "                  the cost mode's budget (or goes without).",
+        "This is INDEPENDENT of cost mode — any cost mode can run either way:",
+        "  minimize + interactive   → $0 videos WITH custom art and hand-picked footage (the sweet spot).",
+        "  minimize + autonomous    → $0 videos from stock + existing raws only; no custom art.",
+        "  hybrid/rich-ai + interactive → paid generation for the hard shots, your hands on the hero art.",
+        "  rich-ai/pure-videogen + autonomous → fully hands-off, budget does the work.",
+        "Quality usually goes UP in interactive mode — most of all in `minimize`, where the free frontier",
+        "web models replace an AI budget you're not spending.",
+        "Set it: vidfarm mode <interactive|autonomous>   (cost is separate: vidfarm cost-mode <…>)"
+    ].join("\n");
+}
+/**
+ * The line an agent should print (and act on) when it is about to do something
+ * that interactive mode would do better — generate art, or source raw clips.
+ * Returns null when the mode is set and the agent should just proceed.
+ */
+export function interactiveOfferLine(input) {
+    if (input.interaction.isSet)
+        return null;
+    return (`[mode] No interaction preference set — about to ${input.about} autonomously. ` +
+        "Ask the user whether they'd rather work INTERACTIVELY (they paste a prompt into a free image " +
+        "generator / hand-source clips — usually better output, and the only way to get custom art in " +
+        "`minimize`) and save it: vidfarm mode <interactive|autonomous>.");
+}
+//# sourceMappingURL=interaction-mode.js.map

package/dist/src/devcli/qa-check.js

@@ -5,6 +5,10 @@
 // capsules, benefit chip rows, and frosted cards floating over footage — the
 // single loudest tell that a video was machine-made.
 //
+// It also judges ONE frame on its own terms: t=0. That frame is the poster every
+// feed and share sheet freezes on, so a black open or a fade-up from black is a
+// real defect even though it's a single frame of ~30 in the first second.
+//
 // DESIGN CONTRACT (read before adding a rule):
 //   * BLOCKLIST, never allowlist. We name specific, well-known web-furniture
 //     patterns. Anything we haven't named is legal. A composition that does
@@ -50,6 +54,27 @@ const SLOP_CLASS_PREFIXES = [
 const ACTION_COPY = /\b(sign\s?up|get\s?started|learn\s?more|book\s+a\s+(call|demo)|start\s+(your\s+)?free\s+trial|free\s+trial|try\s+(it\s+)?free|click\s+here|subscribe\s+now|shop\s+now|order\s+now|contact\s+us|join\s+now|download\s+now|register\s+now|read\s+more|see\s+plans|view\s+pricing)\b/i;
 // The stock trust-badge phrases that show up in benefit chip rows.
 const BENEFIT_COPY = /(no\s+credit\s+card|money[-\s]?back|cancel\s+any\s?time|24\/7|free\s+shipping|verified|guarantee|no\s+commitment|risk[-\s]?free)/i;
+// Entrance transitions that leave frame 0 as a flat solid — the worst possible
+// thumbnail, because the frame carries no information at all.
+const BLANKING_INTROS = ["fade-black", "fade-white", "flash", "smoke"];
+function numAttrOf(node, name) {
+    const raw = node?.getAttribute?.(name);
+    const value = Number.parseFloat(String(raw ?? ""));
+    return Number.isFinite(value) ? value : NaN;
+}
+/** Does this clip paint pixels? Mirrors gapsFromClips in composition-edit.ts. */
+function isVisualClip(node) {
+    const kind = String(node?.getAttribute?.("data-layer-kind") ?? "").toLowerCase();
+    return node?.getAttribute?.("data-vf-timeline-proxy") === "video" || ["video", "image", "html", "shape"].includes(kind);
+}
+/** Is the clip on screen at t (seconds)? Layers with no duration are ignored. */
+function coversTime(node, t) {
+    const start = numAttrOf(node, "data-start");
+    const duration = numAttrOf(node, "data-duration");
+    if (!Number.isFinite(start) || !Number.isFinite(duration) || duration <= 0)
+        return false;
+    return start <= t + 0.001 && start + duration > t + 0.001;
+}
 function textOf(node) {
     return String(node?.textContent ?? "").replace(/\s+/g, " ").trim();
 }
@@ -390,6 +415,62 @@ export function qaCompositionHtml(html) {
             }
         }
     }
+    // ── Rule: the first frame IS the thumbnail ─────────────────────────────────
+    // Frame 0 is one frame of ~30 in the first second, but every feed, share
+    // sheet, and player poster freezes on it — so it is seen by everyone who
+    // scrolls past and never presses play. A black open, a fade-up from black, or
+    // an empty frame waiting for the hook line throws away the only frame that
+    // has to sell the video. Judged at t=0 exactly, since that is the frame the
+    // poster is grabbed from.
+    const visualClips = layers.filter(isVisualClip);
+    const openingVisuals = visualClips.filter((node) => coversTime(node, 0));
+    if (visualClips.length && !openingVisuals.length) {
+        const earliest = visualClips
+            .map((node) => numAttrOf(node, "data-start"))
+            .filter((value) => Number.isFinite(value))
+            .sort((a, b) => a - b)[0];
+        push({
+            rule: "thumbnail-blank-open",
+            severity: "error",
+            message: Number.isFinite(earliest)
+                ? `Nothing is on screen at t=0 — the first visual starts at ${earliest.toFixed(2)}s, so the thumbnail is a black frame.`
+                : "Nothing is on screen at t=0 — the thumbnail is a black frame.",
+            where: "timeline t=0",
+            fix: "Pull the opening clip back to start:0 (`vidfarm retime <dir> --layer <key> --start 0`), or place a deliberate hook frame there. The first frame is the poster every scroller judges the video by."
+        });
+    }
+    for (const node of openingVisuals) {
+        const intro = String(node.getAttribute?.("data-transition") ?? "").trim().toLowerCase();
+        if (!intro || intro === "none")
+            continue;
+        const blanking = BLANKING_INTROS.includes(intro);
+        push({
+            rule: "thumbnail-fade-in",
+            severity: blanking ? "error" : "warn",
+            message: blanking
+                ? `The opening clip has a "${intro}" entrance — frame 0 is a flat ${intro === "fade-white" ? "white" : intro === "flash" ? "blown-out" : "black"} frame, so that becomes the thumbnail.`
+                : `The opening clip has a "${intro}" entrance — frame 0 is caught mid-animation (offset, blurred, or scaled), which is what the thumbnail freezes on.`,
+            where: label(node, "opening clip"),
+            fix: `Drop the entrance on the FIRST clip — it's an intro, not a junction (\`vidfarm transitions set <dir> --layer <key> --in none\`). Junction transitions between later clips are unaffected. If you truly want to open from black, add a held hook frame before it so the poster still shows something.`
+        });
+    }
+    // The strongest thumbnails carry the hook in words. Only a nudge: opening on a
+    // clean face or product shot is a legitimate call.
+    if (textLayers.length && !textLayers.some((node) => coversTime(node, 0))) {
+        const earliest = textLayers
+            .map((node) => numAttrOf(node, "data-start"))
+            .filter((value) => Number.isFinite(value))
+            .sort((a, b) => a - b)[0];
+        push({
+            rule: "thumbnail-no-hook-text",
+            severity: "warn",
+            message: Number.isFinite(earliest)
+                ? `No on-screen text at t=0 (the first text lands at ${earliest.toFixed(2)}s) — the thumbnail carries no hook words.`
+                : "No on-screen text at t=0 — the thumbnail carries no hook words.",
+            where: "timeline t=0",
+            fix: "Start the hook line at 0 so the poster frame states the promise. Ignore this if the video deliberately opens on a clean face/product shot."
+        });
+    }
     const errors = findings.filter((f) => f.severity === "error");
     const warnings = findings.filter((f) => f.severity === "warn");
     return {
@@ -404,6 +485,98 @@ export function qaCompositionHtml(html) {
         }
     };
 }
+function aspectLabel(width, height) {
+    if (!width || !height)
+        return null;
+    const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+    const divisor = gcd(width, height) || 1;
+    return `${width / divisor}:${height / divisor}`;
+}
+/**
+ * Derive the facts a QA_REGIME.md can assert against. Pure, tolerant of
+ * malformed input (returns empty facts rather than throwing) — same contract as
+ * qaCompositionHtml, because a regime run must never break a render either.
+ */
+export function extractCompositionFacts(html) {
+    const empty = {
+        duration_sec: null,
+        canvas: { width: null, height: null, aspect: null },
+        visual_clips: [],
+        text_runs: [],
+        card_runs: [],
+        audio_layers: 0,
+        caption_layers: 0,
+        first_frame_visual: false,
+        first_frame_text: null,
+        first_text_at_sec: null,
+        max_simultaneous_text: 0,
+        off_regime_fonts: [],
+        all_text: ""
+    };
+    let root = null;
+    try {
+        const { document } = parseHTML(html);
+        root = document.querySelector("[data-composition-id]") ?? document.body;
+    }
+    catch {
+        return empty;
+    }
+    if (!root)
+        return empty;
+    const layers = Array.from(root.querySelectorAll("[data-start]"));
+    const width = Number(root.getAttribute?.("data-width") ?? 0) || null;
+    const height = Number(root.getAttribute?.("data-height") ?? 0) || null;
+    const duration = Number.parseFloat(String(root.getAttribute?.("data-duration") ?? ""));
+    const visualClips = layers.filter(isVisualClip).map((node) => ({
+        key: String(node.getAttribute?.("data-hf-id") || node.getAttribute?.("id") || ""),
+        kind: String(node.getAttribute?.("data-layer-kind") ?? "video").toLowerCase(),
+        start: numAttrOf(node, "data-start") || 0,
+        duration: numAttrOf(node, "data-duration") || 0
+    }));
+    const textRuns = [];
+    for (const node of Array.from(root.querySelectorAll('[data-layer-kind="caption"], [data-layer-kind="text"]'))) {
+        const text = textOf(node);
+        if (!text)
+            continue;
+        const style = styleString(node);
+        const cssFamily = (style.match(/(?:^|;)\s*font-family\s*:\s*([^;]+)/) ?? [])[1] ?? "";
+        const family = primaryFamily(String(node.getAttribute?.("data-font-family") ?? "") || cssFamily);
+        textRuns.push({
+            key: String(node.getAttribute?.("data-hf-id") || node.getAttribute?.("id") || ""),
+            kind: String(node.getAttribute?.("data-layer-kind") ?? "text").toLowerCase(),
+            text,
+            start: numAttrOf(node, "data-start") || 0,
+            duration: numAttrOf(node, "data-duration") || 0,
+            font: family || null
+        });
+    }
+    // Max text runs sharing the screen — swept at every run's start, which is the
+    // only instant the count can rise.
+    let maxSimultaneous = 0;
+    for (const probe of textRuns) {
+        const at = probe.start;
+        const overlapping = textRuns.filter((run) => run.start <= at + 0.001 && run.start + run.duration > at + 0.001).length;
+        if (overlapping > maxSimultaneous)
+            maxSimultaneous = overlapping;
+    }
+    const openingText = textRuns.filter((run) => run.start <= 0.001 && run.start + run.duration > 0.001);
+    const sortedStarts = textRuns.map((run) => run.start).sort((a, b) => a - b);
+    return {
+        duration_sec: Number.isFinite(duration) ? duration : null,
+        canvas: { width, height, aspect: aspectLabel(width, height) },
+        visual_clips: visualClips,
+        text_runs: textRuns,
+        card_runs: textRuns.filter((run) => run.kind === "text"),
+        audio_layers: layers.filter((node) => String(node.getAttribute?.("data-layer-kind") ?? "").toLowerCase() === "audio").length,
+        caption_layers: textRuns.filter((run) => run.kind === "caption").length,
+        first_frame_visual: visualClips.some((clip) => clip.start <= 0.001 && clip.start + clip.duration > 0.001),
+        first_frame_text: openingText.length ? openingText.map((run) => run.text).join(" ").trim() : null,
+        first_text_at_sec: sortedStarts.length ? sortedStarts[0] : null,
+        max_simultaneous_text: maxSimultaneous,
+        off_regime_fonts: [...new Set(textRuns.map((run) => run.font).filter((font) => Boolean(font) && !FONT_REGIME.includes(font)))],
+        all_text: textRuns.map((run) => run.text).join(" \n ")
+    };
+}
 /** Human-readable report body (no trailing summary line — the CLI adds that). */
 export function formatQaReport(report, colors) {
     const { red, yellow, dim, reset } = colors;