@officexapp/vidfarm-devcli 0.21.32 → 0.21.34

package/dist/src/cli.js

@@ -736,6 +736,14 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
                             ("did my edit look right") without a full render
     --at 0,2.5,7              Timestamps (default: midpoint of each scene clip, cap 8)
     --out <dir>               Output dir (default <dir>/stills)
+    --sheet                   ALSO tile them into one contact sheet PNG — the
+                              whole-video review pass. Read it as ONE image:
+                              scene-by-scene building drifts (uneven margins,
+                              3 type sizes, a wandering accent colour, N equal
+                              beats, a jarring join) and only a side-by-side
+                              sheet shows it
+    --sheet-out <file>        Sheet path (default <out>/contact-sheet.png)
+    --sheet-width <px>        Per-tile width in the sheet (default 320)
   doctor                    Health-check the local toolchain: node,       (local)
                             ffmpeg, hyperframes engines, Chrome, API key
                             (whoami), provider keys, agent CLI, poisoned
@@ -2387,9 +2395,10 @@ Rules:
 - When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
 - 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. 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). None of that 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).
+- 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 regime 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.
 - 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 QA_REGIME.md — \`vidfarm regime init short-form --out ./QA_REGIME.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo), then EDIT it with them. It is their own written quality standard, and it exists because nobody watches variant #37 as carefully as #1. \`vidfarm qa .\` picks up ./QA_REGIME.md automatically; \`--regime <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. When a batch teaches you something, write it back into the regime.
 - DEDUPLICATE BEFORE YOU PUBLISH — AND ASK FIRST. Social platforms fingerprint every upload, so the same render posted twice (a second account, another platform, a re-post next month) gets the later copy suppressed as duplicate/reused content. BEFORE you render for publication, and before any bulk run, ASK the director: "do you want deduplicated copies for posting, and how many?" Ask THEN, not after — dedupe is a post-render ffmpeg pass, so the correct order is RENDER ONCE → DEDUPE N, and deciding late means paying for a second render. Run it on the EXPORTED file: \`vidfarm dedupe ./final.mp4\` (one copy) or \`vidfarm dedupe ./final.mp4 --variants N --seed <slug> --out-dir ./posts\` (N copies, one per account/slot). Free, offline, no wallet — it never re-renders the composition. The default \`standard\` preset is skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk; invisible to a viewer, and each variant differs from the original AND from its siblings. Post each variant to a DIFFERENT account — two accounts posting the same variant defeats the point. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and the CLI says so; pass \`--rotate 0\` when framing matters more. Cloud twin: \`POST /api/v1/primitives/media/dedupe\`.
 - QA EVERY VIDEO BEFORE YOU RENDER: run \`vidfarm qa .\` in this directory. It's free, instant, and local — a blocklist for the slop above plus the first frame, the font regime, and the safe zone, with a concrete fix per finding. It's feedback, not a gate (exits 0 even on findings, never runs automatically) and a blocklist, not an allowlist, so stylized or hand-made work passes untouched. Fix what's real, ignore what's a deliberate style call. \`--json\` for scripted batches.
@@ -10264,20 +10273,32 @@ async function runStillsCommand(argv) {
         options: {
             at: { type: "string" },
             out: { type: "string" },
+            sheet: { type: "boolean", default: false },
+            "sheet-out": { type: "string" },
+            "sheet-width": { type: "string" },
             json: { type: "boolean", default: false }
         }
     });
     const target = parsed.positionals[0];
     if (!target)
-        throw new Error("stills requires a composition path: `vidfarm stills <dir-or-composition.html> [--at 0,2.5,7] [--out <dir>]`.");
+        throw new Error("stills requires a composition path: `vidfarm stills <dir-or-composition.html> [--at 0,2.5,7] [--sheet] [--out <dir>]`.");
     const htmlPath = resolveCompositionHtmlPath(target);
     const json = Boolean(parsed.values.json);
     const at = parsed.values.at
         ? String(parsed.values.at).split(",").map((value) => parseTimeToSeconds(value.trim())).filter((value) => Number.isFinite(value))
         : undefined;
+    const sheetWidthRaw = parsed.values["sheet-width"] ? Number.parseInt(String(parsed.values["sheet-width"]), 10) : undefined;
     if (!json)
         console.log(`${DIM}Rendering stills in-process (free, local Chrome capture)…${RESET}`);
-    const result = await renderCompositionStills({ htmlPath, at, outDir: parsed.values.out, quiet: json });
+    const result = await renderCompositionStills({
+        htmlPath,
+        at,
+        outDir: parsed.values.out,
+        quiet: json,
+        sheet: Boolean(parsed.values.sheet),
+        sheetPath: parsed.values["sheet-out"],
+        ...(Number.isFinite(sheetWidthRaw) ? { sheetTileWidth: sheetWidthRaw } : {})
+    });
     if (json) {
         printJson(result);
         return;
@@ -10286,6 +10307,10 @@ async function runStillsCommand(argv) {
         console.log(`  ${GREEN}${still.path}${RESET} ${DIM}(requested ${still.requested_sec}s → captured ${still.captured_sec}s)${RESET}`);
     }
     console.log(`${DIM}${result.stills.length} still(s) at ${result.grid_fps}fps grid accuracy — open them to verify the edit before rendering.${RESET}`);
+    if (result.sheet) {
+        console.log(`  ${GREEN}${result.sheet}${RESET} ${DIM}(contact sheet)${RESET}`);
+        console.log(`${DIM}READ the contact sheet as ONE image — that is how you catch what per-scene checks miss: uneven margins, a wandering type scale or accent colour, N identically-long beats, a jarring join, dead space under top-anchored content. Fix drift by defining the system, not by patching the one odd scene.${RESET}`);
+    }
 }
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so

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

@@ -103,6 +103,38 @@ function radiusPx(style) {
     const num = Number((raw.match(/(-?[\d.]+)px/) ?? [])[1] ?? 0);
     return Number.isFinite(num) ? num : 0;
 }
+/** Walk self + ancestors up to the composition root. */
+function selfAndAncestors(node) {
+    const chain = [];
+    let cursor = node;
+    while (cursor && typeof cursor.getAttribute === "function") {
+        chain.push(cursor);
+        if (cursor.getAttribute("data-composition-id") != null)
+            break;
+        cursor = cursor.parentNode;
+    }
+    return chain;
+}
+/**
+ * Is this node part of an animated caption run? The active-word highlight IS a
+ * pill, and it is the one legitimate pill in a video — it tracks the spoken
+ * word instead of sitting there like a badge.
+ */
+function isAnimatedCaptionPart(node) {
+    return selfAndAncestors(node).some((n) => n.getAttribute("data-caption-animation") != null || n.getAttribute("data-cap-word") != null);
+}
+// Native platform artifacts that legitimately use rounded, filled bubbles:
+// iMessage/DM threads, TikTok comment cards, fake chat UI. These are social
+// furniture, not web furniture, so the badge rule must never fire on them.
+const MOCK_UI_HINT = /(imessage|messenger|whatsapp|bubble|chat|sms|dm-|comment|reply|tweet|notification|caption-pill)/i;
+function isMockSocialUi(node) {
+    return selfAndAncestors(node).some((n) => {
+        if (n.getAttribute("data-vf-mock-ui") != null)
+            return true;
+        const hay = `${n.getAttribute("class") ?? ""} ${n.getAttribute("data-label") ?? ""} ${n.getAttribute("data-slug") ?? ""} ${n.getAttribute("id") ?? ""}`;
+        return MOCK_UI_HINT.test(hay);
+    });
+}
 function primaryFamily(raw) {
     return String(raw).split(",")[0].replace(/['"]/g, "").trim().toLowerCase();
 }
@@ -264,6 +296,42 @@ export function qaCompositionHtml(html) {
             fix: "Say each benefit as its OWN timed caption line on the footage, one at a time, in the font regime. One idea per beat reads far better than a chip strip."
         });
     }
+    // ── Rule: standalone badge pill ────────────────────────────────────────────
+    // The lonely capsule: ONE rounded, padded, filled tag holding a static stat or
+    // label — "10 hrs / week", "STEP 2", "EP.01", "+40%". badge-chip-row needs two
+    // siblings and cta-button needs action copy, so a single stat pill used to slip
+    // through both — and it is the most common surviving web tell in practice.
+    // Two signals: a capsule shape (radius well past a caption band) AND a fill.
+    // Excluded on purpose: active-word caption highlights (they MOVE with the
+    // spoken word — the one legitimate pill) and mock social UI, which is native.
+    for (const node of all) {
+        const text = textOf(node);
+        if (!text || text.length > 45)
+            continue;
+        const style = styleString(node);
+        const radius = radiusPx(style);
+        const filled = /background(?:-color|-image)?\s*:/.test(style) && !/background[^;]*:\s*(none|transparent)/.test(style);
+        // A caption band tops out around 8px; 20px+ on a text-sized box is a capsule.
+        if (!filled || radius < 20)
+            continue;
+        // Padding is what turns a hugging band into a tag. Either axis counts.
+        const padded = hasDecl(style, "padding") || hasDecl(style, "padding-left") || hasDecl(style, "padding-inline") ||
+            hasDecl(style, "padding-top") || hasDecl(style, "padding-block");
+        if (!padded)
+            continue;
+        if (isAnimatedCaptionPart(node) || isMockSocialUi(node))
+            continue;
+        // A capsule wrapping several elements is a card — card-panel's job, not ours.
+        if (Array.from(node.children ?? []).filter((c) => textOf(c)).length >= 2)
+            continue;
+        push({
+            rule: "static-pill",
+            severity: "error",
+            message: `Badge pill ("${text.slice(0, 30)}") — a filled ${radius >= 9999 ? "fully-rounded" : `${Math.round(radius)}px`} capsule with padding around static text. One is still a badge.`,
+            where: label(node, "pill"),
+            fix: "Drop the capsule and set the words themselves: bigger, heavier, ALL-CAPS, or an accent color — or circle/underline them. The only legitimate pill tracks the spoken word (set_captions spotlight/karaoke). Mock social UI is exempt: mark it data-vf-mock-ui."
+        });
+    }
     // ── Rule: card / panel / glassmorphism ─────────────────────────────────────
     // A rounded box with a border, shadow, or frosted blur, holding more than one
     // piece of content. A tight caption BAND is legal (small radius, one run) —

package/dist/src/devcli/stills.js

@@ -17,10 +17,12 @@
 // to 2/1fps for long timelines) instead of the composition's native 30fps.
 // Requested timestamps are snapped to that grid; the actually-captured time
 // is reported next to each written PNG.
+import { spawn } from "node:child_process";
 import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseHTML } from "linkedom";
+import { resolveFfmpeg } from "../services/clip-curation/ffmpeg.js";
 import { inspectComposition } from "./composition-edit.js";
 const MAX_DEFAULT_STILLS = 8;
 const MAX_GRID_FRAMES = 600;
@@ -143,6 +145,62 @@ function stageCompositionProject(htmlPath, stagedHtml) {
     }
     return projectDir;
 }
+/**
+ * Choose a near-square tile grid for N frames, biased to a wider-than-tall
+ * sheet (frames are usually portrait, so extra columns read better than extra
+ * rows on a screen).
+ */
+export function pickTileGrid(count) {
+    const cols = Math.max(1, Math.ceil(Math.sqrt(count)));
+    return { cols, rows: Math.max(1, Math.ceil(count / cols)) };
+}
+/**
+ * Tile the rendered stills into ONE contact sheet.
+ *
+ * This exists because reviewing a video frame-by-frame does not surface the
+ * defects that actually ship. Sequence-level drift — margins that shift scene
+ * to scene, three headline sizes, a wandering accent colour, N identical beat
+ * lengths, a jarring join — is only visible when the frames sit side by side,
+ * and an agent reading one tiled image sees it immediately while N separate
+ * image reads bury it. See the vidfarm skill's references/reviewing-renders.md.
+ *
+ * Frames are copied to sequential names first: globbing the output dir would
+ * pick up stills left over from a previous run at different timestamps.
+ */
+async function writeContactSheet(stills, outPath, tileWidth) {
+    const ffmpeg = await resolveFfmpeg();
+    const stageDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-sheet-"));
+    try {
+        stills.forEach((still, index) => {
+            copyFileSync(still.path, path.join(stageDir, `f${String(index + 1).padStart(4, "0")}.png`));
+        });
+        const { cols, rows } = pickTileGrid(stills.length);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        const args = [
+            "-hide_banner", "-v", "error", "-y",
+            "-i", path.join(stageDir, "f%04d.png"),
+            "-vf", `scale=${tileWidth}:-2,tile=${cols}x${rows}:margin=8:padding=8:color=0x999999`,
+            "-frames:v", "1",
+            outPath
+        ];
+        await new Promise((resolve, reject) => {
+            const child = spawn(ffmpeg, args, { stdio: ["ignore", "ignore", "pipe"] });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+            child.on("error", reject);
+            child.on("close", (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`ffmpeg tile failed (exit ${code})${stderr.trim() ? `: ${stderr.trim()}` : ""}`));
+            });
+        });
+        return outPath;
+    }
+    finally {
+        rmSync(stageDir, { recursive: true, force: true });
+    }
+}
 export async function renderCompositionStills(input) {
     const html = readFileSync(input.htmlPath, "utf8");
     if (!html.includes("data-composition-id=")) {
@@ -230,13 +288,19 @@ export async function renderCompositionStills(input) {
             copyFileSync(path.join(framesDir, frameFiles[frameIndex]), dest);
             stills.push({ requested_sec: Number(t.toFixed(3)), captured_sec: capturedSec, path: dest });
         }
+        let sheet;
+        if (input.sheet && stills.length > 0) {
+            const sheetPath = path.resolve(input.sheetPath ?? path.join(outDir, "contact-sheet.png"));
+            sheet = await writeContactSheet(stills, sheetPath, Math.max(80, Math.round(input.sheetTileWidth ?? 320)));
+        }
         return {
             ok: true,
             composition: input.htmlPath,
             out_dir: outDir,
             grid_fps: gridFps,
             duration_seconds: durationSeconds,
-            stills
+            stills,
+            ...(sheet ? { sheet } : {})
         };
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.32",
+  "version": "0.21.34",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {