@officexapp/vidfarm-devcli 0.21.55 → 0.21.57

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/devcli/update-check.js

@@ -0,0 +1,340 @@
+// `vidfarm update-check` — is this install current?
+//
+// Vidfarm ships as TWO moving parts that are versioned TOGETHER: the `vidfarm`
+// agent skill (the workflows on disk) and the `vidfarm-devcli` (the command).
+// Updating one but not the other is the most common cause of "this command
+// doesn't exist" and "the skill says to do X but it fails" — the skill documents
+// routes and flags the installed CLI may not have yet. So this checks both and
+// reports them as one answer.
+//
+// It is built to be run by an AI AGENT on a cadence, not by a human on a whim:
+//   - `--quiet` prints ONE line (or nothing at all when current), so it can sit
+//     at the top of a session without burning context.
+//   - `--if-stale` is a no-op unless the last check is older than the interval,
+//     so "check at least once every 24 hours" costs one cheap call a day rather
+//     than one per command.
+//   - `--skip` records the user's "not now" so the agent stops asking. A prompt
+//     that cannot be dismissed gets ignored, and then the real one is ignored too.
+//
+// BACKEND-FREE: Node built-ins plus one unauthenticated fetch of the public npm
+// registry and one of vidfarm.cc/skill.md. No key, no account, no wallet.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveDevcliHome } from "./auth-store.js";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+const PACKAGE_NAME = "@officexapp/vidfarm-devcli";
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const DEFAULT_HOST = "https://vidfarm.cc";
+/** "at least once every 24 hours" — the cadence SKILL.md asks agents to keep. */
+export const DEFAULT_STALE_HOURS = 24;
+/** Never let a version probe hold up the real work. */
+const FETCH_TIMEOUT_MS = 6000;
+// ── semver ───────────────────────────────────────────────────────────────────
+/**
+ * Compare two semvers numerically. A STRING compare is the trap here: "0.9.0"
+ * sorts above "0.21.55", which would report a current install as ahead of the
+ * registry and silently suppress every update prompt.
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => v.trim().replace(/^v/, "").split("-")[0].split(".").map((part) => {
+        const n = Number(part);
+        return Number.isFinite(n) ? n : 0;
+    });
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** Which part moved: a major bump is the one that can break a documented flow. */
+export function bumpKind(from, to) {
+    const parse = (v) => v.trim().replace(/^v/, "").split("-")[0].split(".").map((p) => Number(p) || 0);
+    const [aMajor = 0, aMinor = 0, aPatch = 0] = parse(from);
+    const [bMajor = 0, bMinor = 0, bPatch = 0] = parse(to);
+    if (bMajor !== aMajor)
+        return "major";
+    if (bMinor !== aMinor)
+        return "minor";
+    if (bPatch !== aPatch)
+        return "patch";
+    return "none";
+}
+// ── what is installed ────────────────────────────────────────────────────────
+/** Walk up from this module to the package root and read its version. */
+export function installedDevcliVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.version && (pkg.name === PACKAGE_NAME || pkg.name === "vidfarm-devcli" || i > 0)) {
+                    return String(pkg.version);
+                }
+            }
+            catch {
+                // keep walking — a malformed package.json higher up is not fatal
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * `version:` out of a SKILL.md front-matter block. Deliberately tiny — the same
+ * stance as the harness front-matter reader: a pack that needs a YAML parser to
+ * state its own version has stopped being legible to the human maintaining it.
+ */
+export function readSkillVersion(markdown) {
+    const front = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const body = front ? front[1] : markdown.slice(0, 2000);
+    const found = body.match(/^\s*(?:skill_version|version)\s*:\s*["']?v?([0-9]+(?:\.[0-9]+)*)["']?\s*$/m);
+    return found ? found[1] : null;
+}
+/** The vidfarm skill pack installed on this machine, if there is one. */
+export function installedSkillPath() {
+    const roots = [process.cwd(), path.dirname(fileURLToPath(import.meta.url))];
+    for (const root of roots) {
+        let dir = root;
+        for (let i = 0; i < 6; i += 1) {
+            for (const rel of [
+                path.join(".agents", "skills", "vidfarm", "SKILL.md"),
+                path.join(".claude", "skills", "vidfarm", "SKILL.md")
+            ]) {
+                const candidate = path.join(dir, rel);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+// ── what is published ────────────────────────────────────────────────────────
+async function fetchText(url, headers = {}) {
+    try {
+        const response = await fetch(url, {
+            headers: { accept: "*/*", ...headers },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!response.ok)
+            return null;
+        return await response.text();
+    }
+    catch {
+        // Offline is a normal state for this CLI — the whole local half works with
+        // no network. A failed probe must never look like "you are out of date".
+        return null;
+    }
+}
+async function latestDevcliVersion() {
+    const text = await fetchText(REGISTRY_URL, { accept: "application/json" });
+    if (!text)
+        return null;
+    try {
+        const body = JSON.parse(text);
+        return body.version ? String(body.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function latestSkillVersion(host) {
+    const text = await fetchText(`${host.replace(/\/+$/, "")}/SKILL.md`);
+    return text ? readSkillVersion(text) : null;
+}
+function statePath(home) {
+    return path.join(resolveDevcliHome(home), "update-check.json");
+}
+export function readUpdateState(home) {
+    try {
+        return JSON.parse(readFileSync(statePath(home), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeUpdateState(next, home) {
+    const file = statePath(home);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(next, null, 2), "utf8");
+}
+/** Hours since the last check, or null if it has never run. */
+export function hoursSinceLastCheck(state, now = Date.now()) {
+    if (!state.lastCheckedAt)
+        return null;
+    const then = Date.parse(state.lastCheckedAt);
+    if (!Number.isFinite(then))
+        return null;
+    return (now - then) / 3_600_000;
+}
+export async function runUpdateCheck(options = {}) {
+    const host = options.host || process.env.VIDFARM_HOST || DEFAULT_HOST;
+    const now = options.now ?? Date.now();
+    const state = readUpdateState(options.home);
+    const devcliInstalled = installedDevcliVersion();
+    const skillPath = installedSkillPath();
+    const skillInstalled = skillPath ? readSkillVersion(readFileSync(skillPath, "utf8")) : null;
+    const [devcliLatest, skillLatest] = await Promise.all([latestDevcliVersion(), latestSkillVersion(host)]);
+    const offline = devcliLatest === null && skillLatest === null;
+    const devcliBehind = Boolean(devcliInstalled && devcliLatest && compareSemver(devcliInstalled, devcliLatest) < 0);
+    const skillBehind = Boolean(skillInstalled && skillLatest && compareSemver(skillInstalled, skillLatest) < 0);
+    // The version the user would be moving TO — a skip is recorded against it, so
+    // a NEWER release always asks again rather than staying silent forever.
+    const target = devcliLatest && skillLatest
+        ? (compareSemver(devcliLatest, skillLatest) >= 0 ? devcliLatest : skillLatest)
+        : (devcliLatest ?? skillLatest ?? "");
+    const skipped = Boolean(state.skippedVersion && target && compareSemver(target, state.skippedVersion) <= 0);
+    const report = {
+        devcli: {
+            installed: devcliInstalled,
+            latest: devcliLatest,
+            behind: devcliBehind,
+            bump: devcliInstalled && devcliLatest ? bumpKind(devcliInstalled, devcliLatest) : "none"
+        },
+        skill: { installed: skillInstalled, latest: skillLatest, behind: skillBehind, path: skillPath },
+        update_available: (devcliBehind || skillBehind) && !skipped,
+        suppressed: (devcliBehind || skillBehind) && skipped,
+        skipped,
+        checked_at: new Date(now).toISOString(),
+        hours_since_last_check: hoursSinceLastCheck(state, now),
+        offline
+    };
+    // Only a check that actually reached the network resets the clock. Stamping it
+    // while offline would suppress the next 24 hours of checks on no information.
+    if (!offline)
+        writeUpdateState({ ...state, lastCheckedAt: report.checked_at }, options.home);
+    return report;
+}
+// ── the command ──────────────────────────────────────────────────────────────
+export const UPDATE_CHECK_HELP = `vidfarm update-check — is this install current?
+
+  update-check                 Check both halves (skill + devcli) and print the verdict
+    --if-stale [--hours 24]    No-op unless the last check is older than N hours.
+                               THIS is the one to put in an agent's session opener.
+    --quiet                    One line, and NOTHING at all when already current
+    --json                     Structured: {devcli, skill, update_available, ...}
+    --skip                     Record "not now" for the current latest version.
+                               A NEWER release asks again; this one stays quiet.
+    --unskip                   Clear that, and ask again from now on
+    --host <url>               Where to read the published SKILL.md (default vidfarm.cc)
+
+  The skill and the devcli are versioned TOGETHER. Updating one without the other
+  is the most common cause of "that command doesn't exist" and "the skill says to
+  do X but it fails". Update both: https://vidfarm.cc/update.md`;
+export async function runUpdateCheckCommand(argv) {
+    const { parseArgs } = await import("node:util");
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+            quiet: { type: "boolean" },
+            "if-stale": { type: "boolean" },
+            hours: { type: "string" },
+            skip: { type: "boolean" },
+            unskip: { type: "boolean" },
+            host: { type: "string" },
+            help: { type: "boolean" }
+        }
+    });
+    const values = parsed.values;
+    if (values.help) {
+        console.log(UPDATE_CHECK_HELP);
+        return;
+    }
+    if (values.unskip) {
+        const state = readUpdateState();
+        delete state.skippedVersion;
+        delete state.skippedAt;
+        writeUpdateState(state);
+        console.log(`${GREEN}✓${RESET} Update prompts re-enabled.`);
+        return;
+    }
+    // `--if-stale` is what makes a 24-hour cadence cheap: the agent can call this
+    // at the top of every session and it costs one network round-trip a day.
+    if (values["if-stale"]) {
+        const hours = Number(values.hours ?? DEFAULT_STALE_HOURS);
+        const since = hoursSinceLastCheck(readUpdateState());
+        if (since !== null && since < (Number.isFinite(hours) ? hours : DEFAULT_STALE_HOURS)) {
+            if (values.json)
+                console.log(JSON.stringify({ checked: false, hours_since_last_check: since }, null, 2));
+            else if (!values.quiet)
+                console.log(`${DIM}Checked ${since.toFixed(1)}h ago — skipping (next check after ${hours}h).${RESET}`);
+            return;
+        }
+    }
+    const report = await runUpdateCheck({ host: values.host });
+    if (values.skip) {
+        const target = report.devcli.latest ?? report.skill.latest;
+        if (target) {
+            writeUpdateState({ ...readUpdateState(), skippedVersion: target, skippedAt: new Date().toISOString() });
+            console.log(`${GREEN}✓${RESET} Skipped ${BOLD}${target}${RESET}. A newer release will ask again — ${DIM}vidfarm update-check --unskip${RESET} to undo.`);
+        }
+        else {
+            console.log(`${DIM}Nothing to skip — could not read the published versions.${RESET}`);
+        }
+        return;
+    }
+    if (values.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (report.offline) {
+        if (!values.quiet)
+            console.log(`${DIM}Could not reach the registry or ${values.host ?? DEFAULT_HOST} — skipping the version check. Everything local still works.${RESET}`);
+        return;
+    }
+    if (!report.update_available) {
+        if (values.quiet)
+            return; // silence is the point of --quiet when current
+        const parts = [
+            `devcli ${report.devcli.installed ?? "?"}`,
+            `skill ${report.skill.installed ?? "not installed"}`
+        ];
+        console.log(`${GREEN}✓${RESET} Vidfarm is current ${DIM}(${parts.join(" · ")})${RESET}`);
+        if (report.suppressed)
+            console.log(`  ${DIM}An update is available but you skipped it: vidfarm update-check --unskip${RESET}`);
+        return;
+    }
+    const lines = [];
+    if (report.devcli.behind)
+        lines.push(`  devcli  ${BOLD}${report.devcli.installed}${RESET} → ${BOLD}${GREEN}${report.devcli.latest}${RESET} ${DIM}(${report.devcli.bump})${RESET}`);
+    if (report.skill.behind)
+        lines.push(`  skill   ${BOLD}${report.skill.installed}${RESET} → ${BOLD}${GREEN}${report.skill.latest}${RESET}`);
+    if (report.skill.installed === null && report.skill.latest) {
+        lines.push(`  skill   ${DIM}not installed${RESET} → ${BOLD}${GREEN}${report.skill.latest}${RESET} ${DIM}(vidfarm skills add vidfarm)${RESET}`);
+    }
+    if (values.quiet) {
+        console.log(`${YELLOW}Vidfarm update available${RESET}${DIM} — ${report.devcli.behind ? `devcli ${report.devcli.installed}→${report.devcli.latest}` : ""}${report.devcli.behind && report.skill.behind ? ", " : ""}${report.skill.behind ? `skill ${report.skill.installed}→${report.skill.latest}` : ""} · vidfarm update-check for detail, --skip to dismiss${RESET}`);
+        return;
+    }
+    console.log(`${YELLOW}⟳ A Vidfarm update is available.${RESET}`);
+    for (const line of lines)
+        console.log(line);
+    console.log("");
+    if (report.devcli.bump === "major") {
+        console.log(`${YELLOW}This is a MAJOR bump${RESET}${DIM} — read the breaking-change notes before you assume an old workflow still applies.${RESET}`);
+    }
+    console.log(`${DIM}Update BOTH halves together — they are versioned together, and updating one alone is the${RESET}`);
+    console.log(`${DIM}usual cause of "that command doesn't exist". The runbook: ${RESET}https://vidfarm.cc/update.md`);
+    console.log("");
+    console.log(`  ${BOLD}npm i -g ${PACKAGE_NAME}@latest${RESET}  ${DIM}&&${RESET}  ${BOLD}vidfarm skills add vidfarm${RESET}`);
+    console.log("");
+    console.log(`${DIM}Not now? ${RESET}vidfarm update-check --skip${DIM} — this version stays quiet, a newer one asks again.${RESET}`);
+}
+//# sourceMappingURL=update-check.js.map

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