agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/engine/node/chrome.mjs

@@ -0,0 +1,349 @@
+// Headless Chrome over the DevTools pipe transport (fd 3/4, NUL-delimited JSON), so no control
+// port ever listens. Re-expresses the driver mechanism of mexicat/pdoom-video app/scripts/render.ts
+// (MIT, see ../NOTICE) without a driver package. Launch walks the MO-A-51 flag ladder and a rung
+// only counts when a real page gets a WebGL2 context; the page is served from disk through CDP
+// Fetch interception, so nothing listens for it either.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { CHROME_ALWAYS, CHROME_RUNGS, EXIT, UNKNOWN_RENDERER } from "../core/constants.mjs";
+import { which } from "./host.mjs";
+
+export class BlockedError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const CANDIDATES = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    path.join(homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+  ],
+  linux: ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+/** Resolve Chrome: $CHROME_PATH, then the platform's usual locations. Returns null when absent. */
+export function findChrome(env = process.env) {
+  if (env.CHROME_PATH) return existsSync(env.CHROME_PATH) ? env.CHROME_PATH : null;
+  for (const candidate of CANDIDATES[process.platform] ?? []) {
+    if (path.isAbsolute(candidate)) {
+      if (existsSync(candidate)) return candidate;
+    } else {
+      const found = which(candidate);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function chromeVersion(chrome) {
+  const probe = spawnSync(chrome, ["--version"], { encoding: "utf8", timeout: 15000 });
+  return probe.status === 0 ? probe.stdout.trim() : `unknown (${(probe.stderr || probe.error?.message || "").trim().split(/\r?\n/u)[0]})`;
+}
+
+/**
+ * The stage path's flag set (director brief 6d): the software rung (SwiftShader) by default, or the
+ * platform's GPU rung for a 3D film (WebGL on the GPU; page raster stays on the CPU either way), the compositor and animation flags that keep a captured frame a function of the page's state,
+ * sRGB at scale 1, the window at the format's size, no background networking, and a resolver rule
+ * that leaves only the synthetic stage origin resolvable.
+ */
+export function stageFlags({ width, height, rung = "software" }) {
+  const base = rung === "gpu" ? CHROME_RUNGS[process.platform]?.[0]?.filter((f) => f !== "--enable-gpu-rasterization") : CHROME_RUNGS.software;
+  if (!base) throw new Error(`no GPU rung on ${process.platform}`);
+  return [
+    ...base, "--disable-gpu-rasterization", "--disable-partial-raster",
+    "--run-all-compositor-stages-before-draw", "--disable-checker-imaging", "--disable-new-content-rendering-timeout",
+    "--disable-threaded-animation", "--disable-threaded-scrolling", "--disable-image-animation-resync", "--disable-lcd-text",
+    "--force-color-profile=srgb", "--hide-scrollbars", "--mute-audio", "--force-device-scale-factor=1", `--window-size=${width},${height}`,
+    "--disable-background-networking", "--disable-component-update", "--disable-sync", "--no-pings", "--metrics-recording-only",
+    "--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE lit.stage",
+    ...CHROME_ALWAYS,
+  ];
+}
+
+/** The ladder for this platform: GPU rung(s) first, SwiftShader last (MO-A-51). */
+export function flagLadder({ softwareOnly = false } = {}) {
+  const gpu = CHROME_RUNGS[process.platform] ?? [];
+  const rungs = softwareOnly ? [CHROME_RUNGS.software] : [...gpu, CHROME_RUNGS.software];
+  return rungs.map((rung) => [...rung, ...CHROME_ALWAYS]);
+}
+
+// Messages arrive as raw bytes: each chunk is scanned once for the NUL terminator and kept as a
+// Buffer until its message is complete, so a large screenshot never rescans what came before and a
+// multi-byte character split across two chunks is decoded whole.
+export class Pipe {
+  constructor(child) {
+    this.child = child;
+    this.id = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.parts = [];
+    this.closed = false;
+    child.stdio[4].on("data", (chunk) => this.receive(chunk));
+    child.stdio[4].on("error", () => {});
+    child.stdio[3].on("error", () => {});
+    child.on("exit", () => {
+      this.closed = true;
+      for (const { reject } of this.pending.values()) reject(new Error("Chrome exited"));
+      this.pending.clear();
+    });
+  }
+  receive(chunk) {
+    let start = 0;
+    for (;;) {
+      const end = chunk.indexOf(0, start);
+      if (end < 0) {
+        if (start < chunk.length) this.parts.push(chunk.subarray(start));
+        return;
+      }
+      this.parts.push(chunk.subarray(start, end));
+      start = end + 1;
+      const message = JSON.parse(Buffer.concat(this.parts).toString("utf8"));
+      this.parts = [];
+      if (message.id !== undefined && this.pending.has(message.id)) {
+        const { resolve, reject } = this.pending.get(message.id);
+        this.pending.delete(message.id);
+        if (message.error) reject(new Error(`${message.error.message}${message.error.data ? `: ${message.error.data}` : ""}`));
+        else resolve(message.result);
+      } else if (message.method) {
+        for (const fn of this.listeners.get(message.method) ?? []) fn(message.params, message.sessionId);
+      }
+    }
+  }
+  send(method, params = {}, sessionId) {
+    if (this.closed) return Promise.reject(new Error("Chrome pipe closed"));
+    const id = ++this.id;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.child.stdio[3].write(`${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`);
+    });
+  }
+  on(method, fn) {
+    if (!this.listeners.has(method)) this.listeners.set(method, []);
+    this.listeners.get(method).push(fn);
+  }
+}
+
+const withTimeout = (promise, ms, message) => Promise.race([
+  promise,
+  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref()),
+]);
+
+const CONTENT_TYPES = { ".html": "text/html", ".mjs": "text/javascript", ".js": "text/javascript", ".json": "application/json", ".ttf": "font/ttf", ".otf": "font/otf", ".svg": "image/svg+xml" };
+
+// A loopback origin: the page may then open its WebSocket to 127.0.0.1 without tripping Chrome's
+// private-network rules. Every request to it is fulfilled by Fetch interception, so nothing is
+// ever sent to a real localhost server.
+export const APP_ORIGIN = "http://localhost";
+
+/**
+ * One headless Chrome with one page. `routes(pathname)` returns a file path or { body, type } for a
+ * request under APP_ORIGIN, or null for 404.
+ */
+/**
+ * The full argument list for one headless launch. `--use-mock-keychain` and `--password-store=basic`
+ * keep Chrome away from the OS keychain: with a fresh profile (or an isolated HOME) it would
+ * otherwise look for its safe-storage item and macOS would put a keychain dialog on screen.
+ */
+export function launchArgs(profileDir, flags) {
+  return [
+    "--headless", `--user-data-dir=${profileDir}`, "--remote-debugging-pipe", "--no-first-run", "--no-default-browser-check",
+    "--use-mock-keychain", "--password-store=basic",
+    "--disable-extensions", "--hide-scrollbars", "--mute-audio", ...flags, "about:blank",
+  ];
+}
+
+// Chrome is tied to this process on POSIX: a shell becomes the leader of a new process group,
+// starts a watcher that leaves the group's descriptors and signals alone, and then execs Chrome,
+// so Chrome keeps the shell's PID. The watcher polls this process and Chrome; once either is gone
+// it sends TERM, then KILL, to the whole group. A launcher killed mid-run, even by SIGKILL, so
+// never leaves Chrome or its helpers alive under PID 1.
+const TETHER = [
+  'parent=$1; group=$$; shift',
+  '( trap "" TERM INT HUP',
+  '  while kill -0 "$parent" 2>/dev/null && kill -0 "$group" 2>/dev/null; do sleep 0.1; done',
+  '  kill -TERM -"$group" 2>/dev/null; sleep 0.2; kill -KILL -"$group" 2>/dev/null',
+  ') </dev/null >/dev/null 2>&1 3>&- 4>&- &',
+  'exec "$@"',
+].join("\n");
+
+/** `spawn` for Chrome: tethered in its own process group on POSIX, a plain child on Windows. */
+function spawnTethered(chrome, args, options) {
+  if (process.platform === "win32") return spawn(chrome, args, options);
+  return spawn("/bin/sh", ["-c", TETHER, "litclaude-chrome", String(process.pid), chrome, ...args], { ...options, detached: true });
+}
+
+export class ChromeSession {
+  static async launch({ chrome, flags, profileDir, routes, timeoutMs = 30000 }) {
+    mkdirSync(profileDir, { recursive: true });
+    const args = launchArgs(profileDir, flags);
+    let child;
+    try {
+      child = spawnTethered(chrome, args, { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"] });
+    } catch (error) {
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch: ${error.message}`);
+    }
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    const spawnError = new Promise((_, reject) => child.on("error", (error) => reject(error)));
+    const session = new ChromeSession(child, profileDir, routes, flags);
+    try {
+      await withTimeout(Promise.race([session.pipe.send("Browser.getVersion"), spawnError]), timeoutMs, "Chrome did not answer on the DevTools pipe");
+    } catch (error) {
+      session.kill();
+      const first = stderr.split("\n").map((l) => l.trim()).find(Boolean) ?? error.message;
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch headless: ${first}`);
+    }
+    session.stderr = () => stderr;
+    return session;
+  }
+
+  constructor(child, profileDir, routes, flags) {
+    this.child = child;
+    this.profileDir = profileDir;
+    this.routes = routes;
+    this.flags = flags;
+    this.pipe = new Pipe(child);
+    this.logs = [];
+  }
+
+  async openPage() {
+    const { targetId } = await this.pipe.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await this.pipe.send("Target.attachToTarget", { targetId, flatten: true });
+    this.sessionId = sessionId;
+    this.pipe.on("Runtime.exceptionThrown", (p) => this.logs.push(`[exception] ${p.exceptionDetails?.exception?.description ?? p.exceptionDetails?.text}`));
+    this.pipe.on("Runtime.consoleAPICalled", (p) => {
+      if (p.type === "error" || p.type === "warning") this.logs.push(`[${p.type}] ${p.args.map((a) => a.value ?? a.description).join(" ")}`);
+    });
+    this.pipe.on("Fetch.requestPaused", (p, sid) => this.serve(p, sid));
+    // Chrome gates a page's connections to 127.0.0.1 behind a loopback-network permission; grant
+    // it for the app origin only (older builds do not know the name, which is fine).
+    await this.pipe.send("Browser.grantPermissions", { permissions: ["loopbackNetwork"], origin: APP_ORIGIN }).catch(() => {});
+    await this.send("Runtime.enable");
+    await this.send("Fetch.enable", { patterns: [{ urlPattern: `${APP_ORIGIN}/*`, requestStage: "Request" }] });
+    await this.send("Emulation.setDeviceMetricsOverride", { width: 1920, height: 1080, deviceScaleFactor: 1, mobile: false });
+  }
+
+  async serve(params, sid) {
+    const url = new URL(params.request.url);
+    let resolved = null;
+    try {
+      resolved = this.routes(decodeURIComponent(url.pathname));
+    } catch {
+      resolved = null;
+    }
+    try {
+      if (!resolved) {
+        await this.pipe.send("Fetch.fulfillRequest", { requestId: params.requestId, responseCode: 404, body: "" }, sid);
+        return;
+      }
+      const body = typeof resolved === "string" ? readFileSync(resolved) : Buffer.from(resolved.body);
+      const type = typeof resolved === "string" ? CONTENT_TYPES[path.extname(resolved)] ?? "application/octet-stream" : resolved.type;
+      await this.pipe.send("Fetch.fulfillRequest", {
+        requestId: params.requestId, responseCode: 200,
+        responseHeaders: [{ name: "Content-Type", value: type }, { name: "Cache-Control", value: "no-store" }],
+        body: body.toString("base64"),
+      }, sid);
+    } catch (error) {
+      this.logs.push(`[serve] ${url.pathname}: ${error.message}`);
+    }
+  }
+
+  send(method, params = {}) {
+    return this.pipe.send(method, params, this.sessionId);
+  }
+
+  /** Evaluate an expression in the page; resolves promises and returns the JSON value. */
+  async evaluate(expression, { timeoutMs = 600000 } = {}) {
+    const result = await withTimeout(this.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }), timeoutMs, `page evaluation timed out: ${expression.slice(0, 80)}`);
+    if (result.exceptionDetails) throw new Error(`page error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+    return result.result.value;
+  }
+
+  /** WebGL2 in a blank page: { webgl2, renderer } (MO-A-51 rung check). */
+  async probeWebgl2() {
+    return this.evaluate(`(() => {
+      const gl = document.createElement('canvas').getContext('webgl2');
+      if (!gl) return { webgl2: false, renderer: null };
+      const ext = gl.getExtension('WEBGL_debug_renderer_info');
+      return { webgl2: true, renderer: ext ? String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)) : ${JSON.stringify(UNKNOWN_RENDERER)} };
+    })()`);
+  }
+
+  async navigate(url) {
+    await this.send("Page.enable");
+    await this.send("Page.navigate", { url });
+  }
+
+  kill() {
+    try {
+      if (process.platform === "win32") this.child.kill("SIGKILL");
+      else process.kill(-this.child.pid, "SIGKILL");
+    } catch {
+      // already gone
+    }
+  }
+
+  async close() {
+    try {
+      await withTimeout(this.pipe.send("Browser.close"), 5000, "close timed out");
+    } catch {
+      this.kill();
+    }
+    const exited = (ms) => new Promise((resolve) => {
+      if (this.child.exitCode !== null || this.child.signalCode) resolve();
+      else this.child.once("exit", resolve);
+      setTimeout(resolve, ms).unref();
+    });
+    await exited(5000);
+    // A browser that acknowledged Browser.close but is still alive would keep this process open.
+    if (this.child.exitCode === null && !this.child.signalCode) {
+      this.kill();
+      await exited(2000);
+    }
+    rmSync(this.profileDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Walk the ladder: launch, check WebGL2 in a real page, keep the first rung that has it. Throws
+ * BlockedError 10 when Chrome itself cannot run, 11 when Chrome runs on every rung but no WebGL2.
+ */
+export async function launchWithLadder({ chrome, profileRoot, routes, softwareOnly = false, log = () => {} }) {
+  if (!chrome) throw new BlockedError(EXIT.BLOCKED_NO_CHROME, "BLOCKED_NO_CHROME: Chrome/Chromium not found (set CHROME_PATH or install Google Chrome)");
+  const failures = [];
+  let index = 0;
+  for (const flags of flagLadder({ softwareOnly })) {
+    const profileDir = path.join(profileRoot, `c${process.pid % 100000}-${index++}`);
+    let session;
+    try {
+      session = await ChromeSession.launch({ chrome, flags, profileDir, routes });
+    } catch (error) {
+      rmSync(profileDir, { recursive: true, force: true });
+      if (error instanceof BlockedError) throw error;
+      throw new BlockedError(EXIT.BLOCKED_NO_CHROME, `BLOCKED_NO_CHROME: ${error.message}`);
+    }
+    try {
+      await session.openPage();
+      const probe = await session.probeWebgl2();
+      if (probe.webgl2) {
+        log(`chrome rung ok: ${flags.join(" ")} -> ${probe.renderer}`);
+        return { session, flags, renderer: probe.renderer };
+      }
+      failures.push(`${flags[0]}: getContext('webgl2') returned null`);
+    } catch (error) {
+      failures.push(`${flags[0]}: ${error.message}`);
+    }
+    await session.close();
+  }
+  throw new BlockedError(EXIT.BLOCKED_NO_WEBGL2, `BLOCKED_NO_WEBGL2: Chrome ran but no rung produced a WebGL2 context (${failures.join("; ")})`);
+}

package/skills/agentvfx/engine/node/encode.mjs

@@ -0,0 +1,110 @@
+// agentvfx (agentvfx licence, see LICENSE). Adapted from lit-typographic-motion 1.0.45 engine/node/encode.mjs.
+// ffmpeg is always the last stage and always a separately installed host binary: the master is one
+// pinned encode (BT.709 matrix and tags, tv range, CRF 16, tune grain). The preview walks the encoder
+// ladder (ffmpeg libwebp_anim, then img2webp, then GIF) over PNG frames the renderer wrote.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { ENCODE_ARGS, PREVIEW } from "../core/constants.mjs";
+import { which } from "./host.mjs";
+import { ffmpegMetadataArgs } from "../core/mark.mjs";
+
+export { which };
+
+export const findFfmpeg = (env = process.env) => (env.FFMPEG_PATH && existsSync(env.FFMPEG_PATH) ? env.FFMPEG_PATH : which("ffmpeg", env));
+export const findFfprobe = (env = process.env) => (env.FFPROBE_PATH && existsSync(env.FFPROBE_PATH) ? env.FFPROBE_PATH : which("ffprobe", env));
+export const findImg2webp = (env = process.env) => which("img2webp", env);
+
+export function ffmpegVersion(ffmpeg) {
+  const probe = spawnSync(ffmpeg, ["-version"], { encoding: "utf8" });
+  return probe.status === 0 ? probe.stdout.split(/\r?\n/u)[0].trim() : null;
+}
+
+/** The preview-encoder rungs available on this host, in ladder order. */
+export function previewRungs(ffmpeg, env = process.env) {
+  const rungs = [];
+  if (ffmpeg) {
+    const list = spawnSync(ffmpeg, ["-hide_banner", "-encoders"], { encoding: "utf8" }).stdout ?? "";
+    if (/\blibwebp_anim\b/u.test(list)) rungs.push("libwebp_anim");
+  }
+  if (findImg2webp(env)) rungs.push("img2webp");
+  if (ffmpeg) rungs.push("gif");
+  return rungs;
+}
+
+/** Start the master encode; returns { write(bytes), finish() }. Writes respect stdin backpressure. */
+export function startMaster({ ffmpeg, width, height, fps, out, audio = null, comment = null }) {
+  const args = ["-y", "-hide_banner", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${width}x${height}`, "-r", String(fps), "-i", "pipe:0"];
+  if (audio) args.push("-i", audio);
+  args.push(...ENCODE_ARGS);
+  // The track is prepared to the film's exact sample count, so nothing is cut to the shorter stream.
+  if (audio) args.push("-map", "0:v:0", "-map", "1:a:0", "-c:a", "aac", "-b:a", "256k");
+  args.push(...ffmpegMetadataArgs({ comment }), out);
+  const child = spawn(ffmpeg, args, { stdio: ["pipe", "ignore", "pipe"] });
+  let stderr = "";
+  child.stderr.on("data", (d) => { stderr += d.toString(); });
+  let exitCode = null;
+  const exited = new Promise((resolve) => child.on("close", (code) => { exitCode = code ?? -1; resolve(code); }));
+  child.stdin.on("error", () => {});
+  const dead = () => new Error(`ffmpeg exited (${exitCode}) during the encode: ${stderr.trim() || "no message"}`);
+  return {
+    args,
+    // A write never waits on 'drain' alone: if ffmpeg dies mid-encode the write rejects instead of hanging.
+    async write(bytes) {
+      if (exitCode !== null) throw dead();
+      if (!child.stdin.write(bytes)) {
+        await Promise.race([new Promise((resolve) => child.stdin.once("drain", resolve)), exited]);
+        if (exitCode !== null) throw dead();
+      }
+    },
+    async finish() {
+      child.stdin.end();
+      const code = await exited;
+      return { code, stderr: stderr.trim() };
+    },
+  };
+}
+
+function run(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return { code: r.status, stderr: (r.stderr || r.error?.message || "").trim() };
+}
+
+/** Encode one preview rung from numbered PNGs (00000.png ...) with one encoder. */
+export function encodePreview({ encoder, ffmpeg, img2webp, dir, fps, out }) {
+  const frames = readdirSync(dir).filter((f) => /^\d{5}\.png$/u.test(f)).sort();
+  if (encoder === "libwebp_anim") {
+    return run(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "%05d.png"), "-c:v", "libwebp_anim", "-lossless", "0", "-q:v", String(PREVIEW.webpQuality), "-loop", "0", out]);
+  }
+  if (encoder === "img2webp") {
+    const args = ["-loop", "0", "-lossy", "-q", String(PREVIEW.webpQuality), "-m", "4"];
+    let elapsed = 0;
+    frames.forEach((f, i) => {
+      const next = Math.round(((i + 1) * 1000) / fps);
+      args.push("-d", String(next - elapsed), path.join(dir, f));
+      elapsed = next;
+    });
+    args.push("-o", out);
+    return run(img2webp, args);
+  }
+  return run(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", "-framerate", String(fps), "-i", path.join(dir, "%05d.png"),
+    "-vf", "split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=4", "-loop", "0", out]);
+}
+
+/** ffprobe the first video stream. Returns null when ffprobe is missing or fails. */
+export function probeVideo(file, env = process.env) {
+  const ffprobe = findFfprobe(env);
+  if (!ffprobe || !existsSync(file)) return null;
+  const r = spawnSync(ffprobe, ["-v", "error", "-select_streams", "v:0", "-count_frames", "-show_entries",
+    "stream=width,height,r_frame_rate,pix_fmt,color_space,color_range,color_transfer,color_primaries,nb_read_frames,codec_name:format=duration,size",
+    "-of", "json", file], { encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const j = JSON.parse(r.stdout);
+  const s = j.streams?.[0] ?? {};
+  const [num, den] = String(s.r_frame_rate ?? "0/1").split("/").map(Number);
+  return {
+    codec: s.codec_name, width: s.width, height: s.height, fps: den ? num / den : 0, pixFmt: s.pix_fmt, colorSpace: s.color_space,
+    colorRange: s.color_range, colorTransfer: s.color_transfer, colorPrimaries: s.color_primaries, frames: Number(s.nb_read_frames ?? 0),
+    duration: Number(j.format?.duration ?? 0), bytes: statSync(file).size,
+  };
+}

package/skills/agentvfx/engine/node/eye.mjs

@@ -0,0 +1,77 @@
+// agentvfx (agentvfx licence, see LICENSE). The eye: every render leaves stills the model must open before reporting.
+// stills/sheet.png (12 evenly spaced frames, 4x3), stills/strip-<k>.png (7 consecutive frames centred
+// on each hit, cut or onset, or on 25/50/75 % when there are none; at most 6 strips) and
+// stills/poster.png (full size, 40 % in). Frames are downscaled as they arrive, so memory stays small.
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { areaDownscale } from "./analysis.mjs";
+import { encodePng, rgbaToRgb } from "./png.mjs";
+
+const GAP = 8;
+const BG = [18, 18, 18];
+const MAX_STRIPS = 6;
+
+/** Which frames the eye needs: { sheet: [f], strips: [{ centre, frames: [f] }], poster: f }. */
+export function eyePlan(frameCount, events = []) {
+  const sheet = [...new Set(Array.from({ length: 12 }, (_, i) => Math.round((i * (frameCount - 1)) / 11)))];
+  const centres = (events.length ? events : [0.25, 0.5, 0.75].map((p) => Math.round(p * (frameCount - 1)))).slice(0, MAX_STRIPS);
+  const strips = centres.map((c) => ({ centre: c, frames: Array.from({ length: 7 }, (_, i) => Math.min(frameCount - 1, Math.max(0, c - 3 + i))) }));
+  return { sheet, strips, poster: Math.round(0.4 * (frameCount - 1)) };
+}
+
+function compose(thumbs, cols, tw, th) {
+  const rows = Math.ceil(thumbs.length / cols);
+  const W = cols * tw + (cols + 1) * GAP;
+  const H = rows * th + (rows + 1) * GAP;
+  const out = Buffer.alloc(W * H * 4);
+  for (let i = 0; i < W * H; i++) out.set([...BG, 255], i * 4);
+  thumbs.forEach((t, i) => {
+    const ox = GAP + (i % cols) * (tw + GAP);
+    const oy = GAP + Math.floor(i / cols) * (th + GAP);
+    for (let y = 0; y < th; y++) t.copy(out, ((oy + y) * W + ox) * 4, y * tw * 4, (y + 1) * tw * 4);
+  });
+  return { rgba: out, width: W, height: H };
+}
+
+const png = (img) => encodePng(rgbaToRgb(img.rgba, img.width, img.height), img.width, img.height, 3, { level: 6 });
+
+/** Collects the frames it needs during the render; write(outDir) saves the PNGs and returns their paths. */
+export function createEye({ width, height, frameCount, events }) {
+  const plan = eyePlan(frameCount, events);
+  const sheetW = 480;
+  const sheetH = Math.max(2, Math.round((sheetW * height) / width));
+  const stripW = 320;
+  const stripH = Math.max(2, Math.round((stripW * height) / width));
+  const sheetSet = new Set(plan.sheet);
+  const stripSet = new Set(plan.strips.flatMap((s) => s.frames));
+  const sheetThumbs = new Map();
+  const stripThumbs = new Map();
+  let poster = null;
+  return {
+    plan,
+    wants: (f) => sheetSet.has(f) || stripSet.has(f) || f === plan.poster,
+    push(f, rgba) {
+      if (sheetSet.has(f)) sheetThumbs.set(f, areaDownscale(rgba, width, height, sheetW, sheetH));
+      if (stripSet.has(f)) stripThumbs.set(f, areaDownscale(rgba, width, height, stripW, stripH));
+      if (f === plan.poster) poster = Buffer.from(rgba);
+    },
+    write(outDir) {
+      const dir = path.join(outDir, "stills");
+      mkdirSync(dir, { recursive: true });
+      const files = {};
+      const sheet = compose(plan.sheet.map((f) => sheetThumbs.get(f)), 4, sheetW, sheetH);
+      files.sheet = path.join(dir, "sheet.png");
+      writeFileSync(files.sheet, png(sheet));
+      files.strips = plan.strips.map((s, k) => {
+        const file = path.join(dir, `strip-${k}.png`);
+        writeFileSync(file, png(compose(s.frames.map((f) => stripThumbs.get(f)), 7, stripW, stripH)));
+        return { file, centre: s.centre, frames: s.frames };
+      });
+      if (poster) {
+        files.poster = path.join(dir, "poster.png");
+        writeFileSync(files.poster, png({ rgba: poster, width, height }));
+      }
+      return files;
+    },
+  };
+}

package/skills/agentvfx/engine/node/footage.mjs

@@ -0,0 +1,129 @@
+// agentvfx (agentvfx licence, see LICENSE). Footage ingest: probe a clip, decode the requested window with ffmpeg at a
+// constant frame rate, scale so the long edge is 1920 (even sizes), convert to RGBA with the clip's
+// colour matrix (BT.709 when untagged), and hand frames to the renderer strictly in order. A request
+// for frame 0 after later frames restarts the decoder (the determinism replay). The window's audio is
+// extracted to a 48 kHz stereo WAV for analysis and muxing.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { EXIT } from "../core/constants.mjs";
+import { BlockedError } from "./chrome.mjs";
+import { findFfmpeg, findFfprobe } from "./encode.mjs";
+
+const even = (n) => Math.max(2, 2 * Math.round(n / 2));
+
+/** ffprobe a clip: { width, height, duration, fps, colorSpace, hasAudio }. */
+export function probeClip(file) {
+  const ffprobe = findFfprobe();
+  const r = spawnSync(ffprobe, ["-v", "error", "-show_entries", "stream=codec_type,width,height,r_frame_rate,color_space:format=duration", "-of", "json", file], { encoding: "utf8" });
+  if (r.status !== 0) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: ffprobe could not read ${file}: ${r.stderr.trim()}`);
+  const j = JSON.parse(r.stdout);
+  const v = j.streams.find((s) => s.codec_type === "video");
+  if (!v) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: ${file} has no video stream`);
+  const [num, den] = String(v.r_frame_rate ?? "0/1").split("/").map(Number);
+  return { width: v.width, height: v.height, duration: Number(j.format?.duration ?? 0), fps: den ? num / den : 0, colorSpace: v.color_space ?? null, hasAudio: j.streams.some((s) => s.codec_type === "audio") };
+}
+
+/** Output size: keep the aspect, long edge `longEdge`, even dimensions. */
+export function fitSize(width, height, longEdge = 1920) {
+  return width >= height ? { width: even(longEdge), height: even((longEdge * height) / width) } : { width: even((longEdge * width) / height), height: even(longEdge) };
+}
+
+/**
+ * Open a footage source for a render window. Returns { width, height, frames, info, frame(f), close() }.
+ * Throws BLOCKED_ASSET_MISSING naming `input.video` when the file is missing or too short.
+ */
+export function openFootage(file, { fps, startSec = 0, durationSec, longEdge = 1920 }) {
+  if (!file || !existsSync(file)) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: input.video not found: ${file}`);
+  const info = probeClip(file);
+  if (info.duration && info.duration + 0.05 < startSec + durationSec) {
+    throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: input.video ${file} is ${info.duration.toFixed(2)} s; the window ${startSec}-${startSec + durationSec} s does not fit`);
+  }
+  const { width, height } = fitSize(info.width, info.height, longEdge);
+  const frames = Math.round(durationSec * fps);
+  const matrix = info.colorSpace && info.colorSpace !== "unknown" ? "auto" : "bt709";
+  const ffmpeg = findFfmpeg();
+  const frameBytes = width * height * 4;
+  let proc = null;
+  let next = 0;
+  let chunks = [];
+  let have = 0;
+  let waiters = [];
+  let ended = false;
+  let stderr = "";
+
+  const start = () => {
+    stop();
+    next = 0;
+    chunks = [];
+    have = 0;
+    ended = false;
+    stderr = "";
+    const vf = `fps=${fps}:round=near,scale=${width}:${height}:flags=lanczos:in_color_matrix=${matrix}:in_range=auto,format=rgba`;
+    proc = spawn(ffmpeg, ["-v", "error", "-ss", String(startSec), "-i", file, "-t", String(durationSec), "-an", "-vf", vf, "-frames:v", String(frames), "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1"], { stdio: ["ignore", "pipe", "pipe"] });
+    proc.stderr.on("data", (d) => { stderr += d.toString(); });
+    proc.stdout.on("data", (d) => {
+      chunks.push(d);
+      have += d.length;
+      if (have >= frameBytes * 4) proc.stdout.pause();
+      flush();
+    });
+    proc.stdout.on("end", () => { ended = true; flush(); });
+  };
+  const take = () => {
+    const all = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks);
+    const frame = Buffer.from(all.subarray(0, frameBytes));
+    const rest = all.subarray(frameBytes);
+    chunks = rest.length ? [rest] : [];
+    have = rest.length;
+    if (proc && have < frameBytes * 4) proc.stdout.resume();
+    return frame;
+  };
+  const flush = () => {
+    while (waiters.length && (have >= frameBytes || ended)) {
+      const w = waiters.shift();
+      if (have >= frameBytes) w.resolve(take());
+      else w.reject(new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: input.video ${file} ended early (${stderr.trim()})`));
+    }
+  };
+  const stop = () => {
+    if (proc && proc.exitCode === null) proc.kill("SIGKILL");
+    proc = null;
+  };
+
+  return {
+    width, height, frames, info, matrix,
+    frame(f) {
+      if (f === 0 || !proc) start();
+      if (f !== next) return Promise.reject(new Error(`footage frames must be read in order (asked ${f}, next ${next})`));
+      next += 1;
+      return new Promise((resolve, reject) => {
+        waiters.push({ resolve, reject });
+        flush();
+      });
+    },
+    close: stop,
+  };
+}
+
+/** Extract an audio window to a 48 kHz stereo WAV in a temp dir; null when the file has no audio. */
+export function extractAudio(file, { startSec = 0, durationSec }) {
+  const info = probeClip(file);
+  if (!info.hasAudio) return null;
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-audio-"));
+  const out = path.join(dir, "window.wav");
+  const r = spawnSync(findFfmpeg(), ["-v", "error", "-y", "-ss", String(startSec), "-i", file, "-t", String(durationSec), "-vn", "-ac", "2", "-ar", "48000", "-c:a", "pcm_s16le", out], { encoding: "utf8" });
+  if (r.status !== 0) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: could not extract audio from ${file}: ${r.stderr.trim()}`);
+  return { file: out, dir };
+}
+
+/** Audio-only file (input.audio) window to WAV. */
+export function extractAudioFile(file, { startSec = 0, durationSec }) {
+  if (!existsSync(file)) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: input.audio not found: ${file}`);
+  const dir = mkdtempSync(path.join(tmpdir(), "agentvfx-audio-"));
+  const out = path.join(dir, "window.wav");
+  const r = spawnSync(findFfmpeg(), ["-v", "error", "-y", "-ss", String(startSec), "-i", file, "-t", String(durationSec), "-vn", "-ac", "2", "-ar", "48000", "-c:a", "pcm_s16le", out], { encoding: "utf8" });
+  if (r.status !== 0) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: could not decode input.audio ${file}: ${r.stderr.trim()}`);
+  return { file: out, dir };
+}