@officexapp/vidfarm-devcli 0.21.56 → 0.21.58

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

@@ -29,6 +29,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseHTML } from "linkedom";
 import { compositionDeclaresFont } from "./composition-edit.js";
+import { ENGINE_GLOBALS_FIX, findEngineOwnedGlobalAssignments, usesTimelineLibraryWithoutRegistry } from "../lib/engine-globals.js";
 // ── Revision governor ────────────────────────────────────────────────────────
 //
 // `vidfarm qa` is feedback, not a gate — which is exactly what makes it a loop
@@ -120,7 +121,7 @@ export function watchTheVideoDirective(dir = "<dir>", renderPath) {
             `Look at the WHOLE thing: \`vidfarm stills ${dir} --sheet\` — then actually OPEN ${dir}/stills/contact-sheet.png and read it as an image. Reading the filenames is not looking at the video.`,
             "Judge it as one sequence, not scene by scene: one type scale, steady margins, one palette, deliberate pacing, clean joins, no dead bands.",
             "Judge every caption AGAINST ITS PICTURE: is the line sitting in the emptiest part of that frame, or on top of the subject? Is it small enough not to run edge-to-edge? Does it even need its plate? qa cannot see pixels — you can.",
-            "Compare frames from two DIFFERENT scenes — a frozen render passes duration, frame-count and audio-hash checks and still ships a still image.",
+            `Prove it MOVES, don't assume it: \`vidfarm motion-check ${video}\` — a frozen render passes duration, frame-count and audio-hash checks and still ships a still image. Then compare frames from two DIFFERENT scenes by eye.`,
             "Time it against your own thumb: name the seconds you would cut. Any beat you can delete without losing the payoff IS fluff — cut it and ripple the hole closed. Assume your first cut is 30–50% too long, and say out loud which beat you cut, or why nothing could go.",
             `Measure the audio instead of vibing it: \`ffmpeg -i ${video} -af volumedetect -f null -\` (peak < 0 dBFS, speech ~12–15 dB over the bed).`,
             "Report what you MEASURED separately from what you JUDGED, and say plainly if you did not watch it."
@@ -341,6 +342,31 @@ export function qaCompositionHtml(html) {
     const textLayers = Array.from(root.querySelectorAll('[data-layer-kind="caption"], [data-layer-kind="text"]')).filter((node) => textOf(node).length > 0);
     const canvasW = Number(root.getAttribute?.("data-width") ?? 0) || null;
     const canvasH = Number(root.getAttribute?.("data-height") ?? 0) || null;
+    // ── Rule: engine-owned globals ─────────────────────────────────────────────
+    // Not a slop rule — a correctness one, and the only defect in this file that
+    // ships a technically-perfect MP4 containing a still image. A weaker model
+    // invents `window.__player = { seek }` as its own per-frame API; that kills
+    // the capture bridge, the render exits 0, and nothing downstream notices.
+    // Duplicated from `vidfarm lint` on purpose: an agent that runs only one of
+    // the two must still be caught. See lib/engine-globals.ts.
+    for (const hit of findEngineOwnedGlobalAssignments(html)) {
+        push({
+            rule: "engine-owned-global",
+            severity: "error",
+            message: `window.${hit.global} is assigned on line ${hit.line} — the engine owns that global. The render will succeed and NOTHING WILL MOVE.`,
+            where: hit.snippet || `line ${hit.line}`,
+            fix: ENGINE_GLOBALS_FIX
+        });
+    }
+    if (usesTimelineLibraryWithoutRegistry(html)) {
+        push({
+            rule: "missing-timeline-registry",
+            severity: "warn",
+            message: "A GSAP/anime timeline is built but never registered on window.__timelines — the engine has nothing to seek.",
+            where: "<script>",
+            fix: 'Register it: window.__timelines = window.__timelines || {}; window.__timelines["<data-composition-id>"] = tl; — the key must equal the root\'s data-composition-id exactly.'
+        });
+    }
     // ── Rule: clickable elements ────────────────────────────────────────────────
     // Nothing in a video is clickable. A <button>, a link, or a form control in a
     // composition is web instinct leaking through, full stop.

package/dist/src/lib/engine-globals.js

@@ -0,0 +1,138 @@
+// Engine-owned browser globals — the ones a composition must never assign.
+//
+// WHY THIS FILE EXISTS (bug report, 2026-08-25):
+// The HyperFrames runtime installs `window.__player` and the capture harness
+// then builds the real seek bridge (`window.__hf`) ON TOP of that object. A
+// composition that assigns `window.__player = { seek }` — an agent inventing
+// its own per-frame API, which is exactly what a weaker model does when it is
+// told "the page must expose window.__hf = { duration, seek }" — permanently
+// destroys the bridge. The render does NOT fail: the harness accepts the
+// forged `__hf` as proof the runtime is up, stalls 45s on
+// `sub_timeline_readiness_timeout`, downgrades it to a warning, and writes a
+// well-formed MP4 with the correct duration, frame count and audio in which
+// NOTHING MOVES. Exit code 0. Four paid marketplace deliverables shipped that
+// way before anyone noticed.
+//
+// The failure is undiagnosable at render time, so it has to be caught at
+// AUTHORING time. This detector is the shared source of truth for:
+//   - `vidfarm lint`            (services/composition-lint.ts — error)
+//   - `vidfarm qa`              (devcli/qa-check.ts — error)
+//   - `vidfarm render --target local` preflight (devcli/local-render.ts — refuses to render)
+//   - the /editor chat's replace_composition_html preflight (via composition-lint)
+//
+// Zero dependencies on purpose: it runs inside the editor-chat Lambda too.
+/**
+ * Globals the HyperFrames runtime + capture harness own. Assigning any of them
+ * from composition code is never correct.
+ *
+ * `__timelines` is deliberately ABSENT — `window.__timelines = window.__timelines || {}`
+ * is the documented, required registration idiom, and flagging it would train
+ * authors away from the one thing they must do.
+ */
+export const ENGINE_OWNED_GLOBALS = [
+    "__player",
+    "__playerReady",
+    "__hf",
+    "__renderReady",
+    "__hyperframes"
+];
+/** The one sentence every message about this should end with. */
+export const ENGINE_GLOBALS_FIX = 'Delete the assignment. The engine installs window.__player / window.__hf itself and drives the composition by SEEKING a paused timeline you register: ' +
+    'window.__timelines = window.__timelines || {}; window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true }); ' +
+    'For imperative per-frame drawing, register a paused driver timeline with an onUpdate callback instead of inventing a seek API.';
+const NAMES = ENGINE_OWNED_GLOBALS.join("|");
+// window.__player = …   window["__player"] = …   globalThis.__hf = …   self.__hf = …
+// The `=(?!=)` tail keeps `window.__player === x` and `!==` out.
+const ASSIGN_RE = new RegExp(String.raw `\b(?:window|globalThis|self)\s*(?:\.\s*(${NAMES})\b|\[\s*["'](${NAMES})["']\s*\])\s*(?:\|\||&&)?\s*=(?!=)`, "g");
+// Object.defineProperty(window, "__player", …) — the same destruction, spelled politely.
+const DEFINE_RE = new RegExp(String.raw `defineProperty\s*\(\s*(?:window|globalThis|self)\s*,\s*["'](${NAMES})["']`, "g");
+/** Extract `<script>` bodies with their offset in the source document. */
+function scriptBodies(html) {
+    const out = [];
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi;
+    let match;
+    while ((match = re.exec(html)) !== null) {
+        out.push({ body: match[1], offset: match.index + match[0].indexOf(match[1]) });
+    }
+    return out;
+}
+function lineOf(html, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < html.length; i += 1)
+        if (html.charCodeAt(i) === 10)
+            line += 1;
+    return line;
+}
+/**
+ * A window of source AROUND the match, not the whole line. Compositions are
+ * routinely minified onto one line, where "the line" is the entire document and
+ * tells the author nothing.
+ */
+function snippetAround(html, index) {
+    const lineStart = html.lastIndexOf("\n", index) + 1;
+    const lineEndRaw = html.indexOf("\n", index);
+    const lineEnd = lineEndRaw === -1 ? html.length : lineEndRaw;
+    const from = Math.max(lineStart, index - 24);
+    const to = Math.min(lineEnd, index + 116);
+    return `${from > lineStart ? "…" : ""}${html.slice(from, to).trim()}${to < lineEnd ? "…" : ""}`;
+}
+/**
+ * Find every assignment to an engine-owned global inside the composition's
+ * inline `<script>` blocks. Only script bodies are scanned, so prose or a
+ * caption that happens to contain the words is never flagged.
+ *
+ * One hit per (global, line) — a loop that reassigns the same thing twice on
+ * one line is one defect, not two.
+ */
+export function findEngineOwnedGlobalAssignments(html) {
+    if (typeof html !== "string" || !html.includes("__"))
+        return [];
+    const hits = [];
+    const seen = new Set();
+    const record = (name, absoluteIndex) => {
+        const line = lineOf(html, absoluteIndex);
+        const key = `${name}:${line}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        hits.push({ global: name, line, snippet: snippetAround(html, absoluteIndex) });
+    };
+    for (const { body, offset } of scriptBodies(html)) {
+        for (const re of [ASSIGN_RE, DEFINE_RE]) {
+            re.lastIndex = 0;
+            let match;
+            while ((match = re.exec(body)) !== null) {
+                const name = match[1] ?? match[2];
+                if (name)
+                    record(name, offset + match.index);
+            }
+        }
+    }
+    return hits.sort((a, b) => a.line - b.line || a.global.localeCompare(b.global));
+}
+/** Human-readable one-liner for a set of hits. */
+export function describeEngineGlobalHits(hits) {
+    const names = [...new Set(hits.map((h) => `window.${h.global}`))].join(", ");
+    const where = hits.map((h) => `line ${h.line}`).slice(0, 4).join(", ");
+    return `Composition assigns engine-owned global(s) ${names} (${where}). ` +
+        "This silently destroys the HyperFrames capture bridge: the render still exits 0 and writes a correct-length MP4 in which NOTHING MOVES. " +
+        ENGINE_GLOBALS_FIX;
+}
+/**
+ * A composition that builds a GSAP/anime timeline but never registers it on
+ * `window.__timelines` renders static for a different reason — the engine has
+ * nothing to seek. Cheap companion check; warning-level, because a sub-
+ * composition may legitimately be registered from a sibling file.
+ */
+export function usesTimelineLibraryWithoutRegistry(html) {
+    if (typeof html !== "string")
+        return false;
+    const bodies = scriptBodies(html).map((s) => s.body).join("\n");
+    if (!bodies)
+        return false;
+    const buildsTimeline = /\bgsap\s*\.\s*timeline\s*\(|\banime\s*\.\s*timeline\s*\(|\bnew\s+TimelineMax\b/.test(bodies);
+    if (!buildsTimeline)
+        return false;
+    return !/\b__timelines\b/.test(bodies);
+}
+//# sourceMappingURL=engine-globals.js.map

package/dist/src/lib/frozen-render.js

@@ -0,0 +1,130 @@
+// Frozen-render detection — "the MP4 is correct in every measurable way and
+// nothing in it moves".
+//
+// WHY THIS FILE EXISTS: whole classes of render bug produce a video where every
+// frame is identical while duration, frame count, file size and audio all come
+// out exactly right, and the renderer exits 0. Three known causes, all silent:
+//   1. the composition assigned an engine-owned global (window.__player /
+//      window.__hf), which destroys the capture bridge — see lib/engine-globals.ts;
+//   2. a watermark/overlay pass over a single-frame PNG without `-loop 1`,
+//      which collapses the whole video onto one frame;
+//   3. assets (or the animation library) outside the composition root, so the
+//      timeline never starts — frame 0 still renders fine, because frame 0 IS
+//      the static DOM.
+// Frame 0 looks perfect in all three, so every single-frame check passes and a
+// still image ships as a video.
+//
+// METHOD — one ffmpeg pass, no temp files:
+//   fps=4 → scale → tblend=difference (each sample minus the previous one)
+//         → blackframe, which reports `pblack:<percent of near-black pixels>`
+// A frame pair with real motion leaves bright pixels in the difference, so
+// pblack drops well below 100. A frozen video leaves pblack at exactly 100 for
+// every pair — encoder noise on a static source sits at 54–66 dB PSNR, far
+// under the blackness threshold, so it does not register as motion.
+// Measured on a real render: animating → pblack 87–100 (min 87); frozen →
+// pblack 100 on every pair. The separation is not marginal.
+import { spawn } from "node:child_process";
+import { resolveFfmpeg } from "../services/clip-curation/ffmpeg.js";
+const PBLACK_RE = /pblack:(\d+(?:\.\d+)?)/g;
+function runFfmpeg(bin, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        child.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? 1, stderr });
+        });
+    });
+}
+/**
+ * Decide whether a rendered video actually animates. Never throws: an
+ * unavailable ffmpeg comes back as `{ ok: true, skipped: true }` so a missing
+ * toolchain can never fail a render that is probably fine.
+ */
+export async function checkRenderMotion(videoPath, opts = {}) {
+    const fpsGrid = opts.fpsGrid ?? 4;
+    const width = opts.width ?? 192;
+    const staticPblack = opts.staticPblack ?? 99.9;
+    const base = {
+        ok: true,
+        frozen: false,
+        skipped: true,
+        video: videoPath,
+        compared_pairs: 0,
+        moving_pairs: 0,
+        min_pblack: 100,
+        motion_score: 0,
+        fps_grid: fpsGrid,
+        reason: "not run"
+    };
+    let bin;
+    try {
+        bin = await resolveFfmpeg();
+    }
+    catch {
+        return { ...base, reason: "ffmpeg unavailable — motion not verified." };
+    }
+    const filter = `fps=${fpsGrid},scale=${width}:-2,tblend=all_mode=difference,blackframe=amount=0:threshold=24`;
+    let stderr;
+    try {
+        ({ stderr } = await runFfmpeg(bin, ["-v", "info", "-nostdin", "-i", videoPath, "-an", "-vf", filter, "-f", "null", "-"], opts.timeoutMs ?? 120_000));
+    }
+    catch {
+        return { ...base, reason: "ffmpeg could not be launched — motion not verified." };
+    }
+    const values = [];
+    let match;
+    PBLACK_RE.lastIndex = 0;
+    while ((match = PBLACK_RE.exec(stderr)) !== null)
+        values.push(Number(match[1]));
+    if (values.length === 0) {
+        return { ...base, reason: "ffmpeg reported no comparable frames — motion not verified." };
+    }
+    const minPblack = Math.min(...values);
+    const movingPairs = values.filter((v) => v < staticPblack).length;
+    const frozen = movingPairs === 0;
+    return {
+        ok: !frozen,
+        frozen,
+        skipped: false,
+        video: videoPath,
+        compared_pairs: values.length,
+        moving_pairs: movingPairs,
+        min_pblack: minPblack,
+        motion_score: Number((100 - minPblack).toFixed(3)),
+        fps_grid: fpsGrid,
+        reason: frozen
+            ? `All ${values.length} sampled frame pairs are identical — this video never moves.`
+            : `${movingPairs}/${values.length} sampled frame pairs differ (max change ${(100 - minPblack).toFixed(1)}%).`
+    };
+}
+/** Terminal block for a frozen result. Returns "" when the video is fine. */
+export function formatFrozenRenderFailure(result, colors) {
+    if (!result.frozen)
+        return "";
+    const { red, bold, dim, reset } = colors;
+    return [
+        "",
+        `${red}${bold}■ FROZEN RENDER — the MP4 is a still image.${reset}`,
+        `  ${dim}${result.compared_pairs} frame pairs sampled at ${result.fps_grid}fps; not one of them differed.${reset}`,
+        `  ${dim}Duration, frame count and audio are all correct, which is why nothing else caught this.${reset}`,
+        "",
+        `  ${bold}Usual causes, in order:${reset}`,
+        `  ${dim}1.${reset} The composition assigns an engine-owned global. ${dim}window.__player / window.__hf belong to the engine; assigning either kills frame capture. Run ${reset}vidfarm lint <dir>${dim}.${reset}`,
+        `  ${dim}2.${reset} No paused timeline is registered. ${dim}window.__timelines["<data-composition-id>"] = gsap.timeline({ paused: true }) — the key must equal the root's data-composition-id exactly.${reset}`,
+        `  ${dim}3.${reset} The animation library or an asset sits outside the composition root. ${dim}Only <style>/<script> INSIDE the root element execute.${reset}`,
+        `  ${dim}4.${reset} A watermark/overlay pass over a single-frame PNG without ${reset}-loop 1${dim}.${reset}`,
+        "",
+        `  ${dim}Re-check after fixing: ${reset}vidfarm motion-check ${result.video}${dim}. Ship a deliberately static card with ${reset}--allow-static${dim}.${reset}`,
+        ""
+    ].join("\n");
+}
+//# sourceMappingURL=frozen-render.js.map

package/dist/src/services/composition-lint.js

@@ -5,6 +5,7 @@
 // composition vocabulary (data-vf-* proxies, transition holds, caption spans).
 import { parseHTML } from "linkedom";
 import { CAPTION_ANIMATIONS, KEN_BURNS_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS } from "../hyperframes/composition.js";
+import { ENGINE_GLOBALS_FIX, findEngineOwnedGlobalAssignments, usesTimelineLibraryWithoutRegistry } from "../lib/engine-globals.js";
 const OVERLAP_EPSILON = 0.011;
 function parseNumberAttr(value) {
     if (typeof value !== "string" || !value.trim()) {
@@ -175,6 +176,21 @@ export function lintCompositionHtml(html) {
             }
         }
     }
+    // ── Engine-owned globals ────────────────────────────────────────────────────
+    // The highest-value check in this file. A composition that assigns
+    // window.__player (or window.__hf) still renders, still exits 0, and still
+    // writes a correct-length MP4 — in which nothing moves. Nothing downstream
+    // catches it, so it has to be an ERROR here. See lib/engine-globals.ts.
+    for (const hit of findEngineOwnedGlobalAssignments(trimmed)) {
+        push("error", "engine_owned_global_assigned", `Line ${hit.line} assigns window.${hit.global} — the HyperFrames engine owns that global. ` +
+            "Assigning it destroys the frame-capture bridge: the render still succeeds and writes a video in which NOTHING MOVES. " +
+            ENGINE_GLOBALS_FIX, hit.snippet);
+    }
+    if (usesTimelineLibraryWithoutRegistry(trimmed)) {
+        push("warning", "missing_timeline_registry", 'Composition builds a GSAP/anime timeline but never registers one on window.__timelines. ' +
+            'The engine drives motion by SEEKING a registered paused timeline — without it the render is a still image. ' +
+            'Add: window.__timelines = window.__timelines || {}; window.__timelines["<data-composition-id>"] = tl;');
+    }
     const scripts = document.querySelectorAll("script");
     if (scripts.length > 0) {
         push("warning", "scripts_stripped_on_save", `Composition contains ${scripts.length} <script> tag(s). Scripts survive local serve/disk renders, but every cloud/web editor save strips them (stored-XSS defense) — script-driven animation will be lost there. Prefer the declarative preset vocabulary (data-kenburns, data-transition, data-caption-animation) for compositions that round-trip through the web editor.`);