agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/engine/node/frame-worker.mjs

@@ -0,0 +1,39 @@
+// agentvfx (agentvfx licence, see LICENSE). Adapted from lit-typographic-motion 1.0.45 engine/node/frame-worker.mjs.
+// One frame-analysis worker: decode a captured PNG to RGBA and analyse it off the capture thread
+// (the SHA-256 of the decoded RGBA, the flash-audit cells on the frame's own grid, the 0.5th and
+// 99.5th percentile luminance, the busy-cell share). The capture loop steps the next frame while a
+// pool of these decodes. Imported outside a worker (the import test), it does nothing.
+import { parentPort } from "node:worker_threads";
+import { analyzeFrame, busyShare } from "./analysis.mjs";
+import { decodePng } from "./png.mjs";
+
+parentPort?.on("message", ({ id, png, width, height }) => {
+  try {
+    const image = decodePng(Buffer.from(png));
+    if (image.width !== width || image.height !== height) {
+      parentPort.postMessage({ id, error: `captured ${image.width}x${image.height}, expected ${width}x${height}` });
+      return;
+    }
+    const rgba = image.channels === 4 ? image.pixels : toRgba(image.pixels, image.channels);
+    // A stage frame is opaque: analyzeFrame's alpha-as-ink count is meaningless here and is dropped.
+    const { cells, luminanceP995, luminanceP005, rgbaSha256 } = analyzeFrame(rgba, width, height);
+    const busy = busyShare(rgba, width, height);
+    const buffer = rgba.buffer.slice(rgba.byteOffset, rgba.byteOffset + rgba.byteLength);
+    parentPort.postMessage({ id, rgba: buffer, cells, luminanceP995, luminanceP005, rgbaSha256, busy }, [buffer, cells.R.buffer, cells.G.buffer, cells.B.buffer]);
+  } catch (error) {
+    parentPort.postMessage({ id, error: error.message });
+  }
+});
+
+function toRgba(pixels, channels) {
+  const n = pixels.length / channels;
+  const out = Buffer.alloc(n * 4);
+  for (let i = 0; i < n; i++) {
+    const s = i * channels;
+    out[i * 4] = pixels[s];
+    out[i * 4 + 1] = pixels[channels >= 3 ? s + 1 : s];
+    out[i * 4 + 2] = pixels[channels >= 3 ? s + 2 : s];
+    out[i * 4 + 3] = 255;
+  }
+  return out;
+}

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

@@ -0,0 +1,31 @@
+// Host lookups that differ on Windows. `where` ends each line with \r\n, so a plain split("\n")
+// keeps the \r and the path is never found. npm on Windows is npm.cmd, and since the
+// CVE-2024-27980 fix (Node 18.20.2, 20.12.2, 21.7.3 and every 22+) Node refuses to spawn a .cmd
+// without a shell (spawnSync EINVAL). When npm itself started us, npm_execpath names its npm-cli.js
+// and this Node runs it with no shell at all; otherwise the .cmd goes through cmd.exe with every
+// argument quoted, and an argument cmd.exe could still reinterpret inside quotes is refused.
+import { spawnSync } from "node:child_process";
+
+/** The first match for `name` on PATH, or null. */
+export function which(name, env = process.env, { platform = process.platform, spawn = spawnSync } = {}) {
+  const probe = spawn(platform === "win32" ? "where" : "which", [name], { encoding: "utf8", env });
+  if (probe.status !== 0) return null;
+  return String(probe.stdout ?? "").split(/\r?\n/u).map((line) => line.trim()).find(Boolean) ?? null;
+}
+
+const CMD_SAFE = /^[\w@.,:=+/\\-]+$/u;
+const CMD_UNSAFE = /["%\r\n]/u;
+
+export const quoteForCmd = (arg) => {
+  const text = String(arg);
+  if (CMD_UNSAFE.test(text)) throw new Error(`refusing to pass ${JSON.stringify(text)} through cmd.exe`);
+  // Trailing backslashes are doubled so the closing quote still ends the argument for node.
+  return CMD_SAFE.test(text) ? text : `"${text.replace(/(\\+)$/u, "$1$1")}"`;
+};
+
+/** { command, args, shell } for spawn/spawnSync. */
+export function npmInvocation(args, { platform = process.platform, env = process.env, execPath = process.execPath } = {}) {
+  if (platform !== "win32") return { command: "npm", args, shell: false };
+  if (/npm-cli\.c?js$/iu.test(env.npm_execpath ?? "")) return { command: execPath, args: [env.npm_execpath, ...args], shell: false };
+  return { command: "npm.cmd", args: args.map(quoteForCmd), shell: true };
+}

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

@@ -0,0 +1,181 @@
+// agentvfx (agentvfx licence, see LICENSE). One render job, end to end: resolve the score's footage and audio, analyse
+// the audio, render the master (stage mode: full intensity, never tamed), keep the eye's stills, run
+// the flash audit as a report, write SAFETY.txt and the MP4 comment when limits are exceeded, and, only
+// when asked (safety.mode "broadcast-safe" or safeVariant), render a substituted broadcast-safe file.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { EXIT } from "../core/constants.mjs";
+import { BlockedError } from "./chrome.mjs";
+import { createFlashAuditor } from "../core/flash.mjs";
+import { CREDIT_TEXT, creditText } from "../core/mark.mjs";
+import { buildSchedule } from "../core/schedule.mjs";
+import { findFfmpeg } from "./encode.mjs";
+import { createEye } from "./eye.mjs";
+import { extractAudio, extractAudioFile, openFootage } from "./footage.mjs";
+import { renderScore } from "./render.mjs";
+
+export const FLASH_COMMENT = "contains intense flashing";
+const SAFE = { maxPerSecond: 3, minGapMs: 334 };
+
+async function loadAudio() {
+  return import("./audio.mjs");
+}
+
+/** Broadcast-safe hits: keep flashing hits at most 3 per 1 s with leading edges >= 334 ms apart; substitute the rest. */
+export function safeScore(score, lib, features) {
+  const fps = score.fps;
+  const sched = buildSchedule({ ...score, cuts: [], bindings: [] }, lib, { features });
+  const starts = (score.hits ?? []).map((h, i) => ({ i, h, start: sched.frames.findIndex((fr) => fr.layers.some((l) => l.key === `h${i}`)) }));
+  const flashing = (id) => ["possible", "strobe"].includes(lib.get(id)?.fx.X_AGENTVFX.flash);
+  const kept = [];
+  const substitutions = [];
+  const hits = [];
+  for (const { i, h, start } of starts.sort((a, b) => a.start - b.start || a.i - b.i)) {
+    if (!flashing(h.template)) {
+      hits.push(h);
+      continue;
+    }
+    const gapOk = kept.every((k) => Math.abs(start - k) * 1000 / fps >= SAFE.minGapMs);
+    const windowOk = kept.filter((k) => start - k < fps).length < SAFE.maxPerSecond;
+    const sub = lib.get(h.template).fx.X_AGENTVFX.safeSubstitute;
+    if (start >= 0 && gapOk && windowOk) {
+      kept.push(start);
+      // A kept hit is one flash, not a burst: a params-only substitute (e.g. pulses: 1) still applies.
+      hits.push(sub?.params && !sub.template ? { ...h, params: { ...(h.params ?? {}), ...sub.params } } : h);
+      continue;
+    }
+    if (sub) {
+      // A hit swaps to the substitute template (a motion or isoluminant hit); without one, the
+      // substitute params tame the same template.
+      const replaced = sub.template
+        ? { ...h, template: sub.template, preset: undefined, params: undefined }
+        : { ...h, params: { ...(h.params ?? {}), ...(sub.params ?? {}) } };
+      hits.push(replaced);
+      substitutions.push({ hit: i, frame: start, from: h.template, to: replaced.template, params: sub.params ?? {} });
+    } else substitutions.push({ hit: i, frame: start, from: h.template, to: null, dropped: true });
+  }
+  const tame = (layer) => {
+    const ref = typeof layer === "string" ? { template: layer } : layer;
+    const sub = lib.get(ref.template)?.fx.X_AGENTVFX.flash === "strobe" ? lib.get(ref.template).fx.X_AGENTVFX.safeSubstitute : null;
+    return sub ? { ...ref, params: { ...(ref.params ?? {}), ...(sub.params ?? {}) } } : layer;
+  };
+  const base = tame({ template: score.template, preset: score.preset, params: score.params });
+  return {
+    score: { ...score, params: base.params, stack: score.stack?.map(tame), cuts: score.cuts?.map((c) => ({ ...c, layers: c.layers.map(tame) })), hits: hits.length ? hits : undefined },
+    substitutions,
+  };
+}
+
+function remuxComment(file, comment) {
+  const tmp = `${file}.tmp.mp4`;
+  const r = spawnSync(findFfmpeg(), ["-v", "error", "-y", "-i", file, "-map", "0", "-c", "copy", "-metadata", `comment=${comment}`, "-movflags", "+faststart", tmp], { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`could not tag ${file}: ${r.stderr}`);
+  renameSync(tmp, file);
+}
+
+function safetyText(flash, film) {
+  return [
+    "SAFETY NOTICE: this clip contains intense flashing.",
+    "",
+    `File: ${path.basename(film)}`,
+    `Worst 1 s window: ${flash.worstWindow?.transitions ?? "?"} transitions from ${flash.worstWindow?.startSec ?? "?"} s`,
+    `Max flashes per second: ${flash.flashesPerSecondMax}`,
+    `Red flashes: ${flash.redFlashes}`,
+    `Extended flashing (4-6 transitions/s for 4 s): ${flash.extendedFlashing}`,
+    "",
+    "Limits exceeded: WCAG 2.2 SC 2.3.1 general flash / ITU-R BT.1702-3 (more than 3 flashes in any 1 s,",
+    "or any saturated-red flash). This file was rendered at full intensity for stage use (stage mode).",
+    "For broadcast or web posting, render with \"safety\": { \"safeVariant\": true } to also get film.safe.mp4.",
+    "",
+  ].join("\n");
+}
+
+async function pass({ score, lib, outDir, film, footageFile, audioWav, features, width, height, replay, events }) {
+  const longEdge = width && height ? Math.max(width, height) : 1920;
+  const footage = footageFile ? openFootage(footageFile, { fps: score.fps, startSec: score.input?.startSec ?? 0, durationSec: score.durationSec, longEdge }) : null;
+  const w = width ?? footage?.width ?? 1920;
+  const h = height ?? footage?.height ?? 1080;
+  const sched = buildSchedule(score, lib, { features });
+  const eventsAll = sched.events.length ? sched.events : (features?.meta?.onsets ?? []).filter((f) => f < sched.frameCount);
+  const eye = createEye({ width: w, height: h, frameCount: sched.frameCount, events: events ?? eventsAll });
+  const auditor = createFlashAuditor({ fps: score.fps, width: w, height: h });
+  try {
+    const report = await renderScore(score, lib, {
+      outDir, width: w, height: h, features, footage, audioFile: audioWav, replay,
+      onFrame: (f, a) => {
+        auditor.push({ width: w, height: h, data: a.rgba });
+        if (eye.wants(f)) eye.push(f, a.rgba);
+      },
+    });
+    if (film !== report.film) renameSync(report.film, film);
+    return { report: { ...report, film }, flash: auditor.finish(), eye, footage: footage ? { width: footage.width, height: footage.height, matrix: footage.matrix, transport: "cdp-fetch-interception" } : null };
+  } finally {
+    footage?.close();
+  }
+}
+
+/**
+ * Run a validated score. Writes film.mp4, stills/, gate-report.json, features.json (with audio),
+ * CREDIT.txt (the attribution line), SAFETY.txt (stage mode, limits exceeded), film.safe.mp4 (safe variant) or withheld/ (safe file failed).
+ */
+export async function runJob(score, lib, { outDir, width, height, replay = true, cwd = process.cwd() }) {
+  mkdirSync(outDir, { recursive: true });
+  const footageFile = score.input?.video ? path.resolve(cwd, score.input.video) : null;
+  if (footageFile && !existsSync(footageFile)) throw new BlockedError(EXIT.BLOCKED_ASSET_MISSING, `BLOCKED_ASSET_MISSING: input.video not found: ${footageFile}`);
+  const window = { startSec: score.input?.startSec ?? 0, durationSec: score.durationSec };
+  const tmpDirs = [];
+  try {
+    let audio = null;
+    if (score.input?.audio) audio = extractAudioFile(path.resolve(cwd, score.input.audio), window);
+    else if (footageFile) audio = extractAudio(footageFile, window);
+    if (audio) tmpDirs.push(audio.dir);
+    let features = null;
+    if (audio) {
+      const { analyzeAudio, writeFeatures } = await loadAudio();
+      features = await analyzeAudio(audio.file, { fps: score.fps });
+      await writeFeatures(features, path.join(outDir, "features.json"));
+    }
+    const stageMode = score.safety.mode === "stage";
+    const gate = { ok: true, score, safetyMode: score.safety.mode };
+    const master = await pass({ score: stageMode ? score : safeScore(score, lib, features).score, lib, outDir, film: path.join(outDir, "film.mp4"), footageFile, audioWav: audio?.file ?? null, features, width, height, replay });
+    gate.render = master.report;
+    gate.flash = master.flash;
+    gate.footage = master.footage;
+    gate.stills = master.eye.write(outDir);
+    gate.determinism = master.report.determinism;
+    if (master.report.determinism.pass === false) gate.ok = false;
+    if (stageMode && master.flash.exceeds) {
+      writeFileSync(path.join(outDir, "SAFETY.txt"), safetyText(master.flash, master.report.film));
+      remuxComment(master.report.film, FLASH_COMMENT);
+      gate.safetyNotice = { file: path.join(outDir, "SAFETY.txt"), mp4Comment: FLASH_COMMENT };
+    }
+    if (!stageMode && master.flash.exceeds) {
+      const held = path.join(outDir, "withheld");
+      mkdirSync(held, { recursive: true });
+      renameSync(master.report.film, path.join(held, "film.mp4"));
+      gate.ok = false;
+      gate.withheld = path.join(held, "film.mp4");
+    }
+    if (!stageMode) gate.substitutions = safeScore(score, lib, features).substitutions;
+    if (stageMode && score.safety.safeVariant) {
+      const safe = safeScore(score, lib, features);
+      const safeDir = path.join(outDir, ".safe");
+      const res = await pass({ score: safe.score, lib, outDir: safeDir, film: path.join(outDir, "film.safe.mp4"), footageFile, audioWav: audio?.file ?? null, features, width, height, replay: false, events: master.eye.plan.strips.map((s) => s.centre) });
+      rmSync(safeDir, { recursive: true, force: true });
+      gate.safeVariant = { film: res.report.film, flash: res.flash, substitutions: safe.substitutions };
+      if (res.flash.exceeds) {
+        const held = path.join(outDir, "withheld");
+        mkdirSync(held, { recursive: true });
+        renameSync(res.report.film, path.join(held, "film.safe.mp4"));
+        gate.safeVariant.withheld = path.join(held, "film.safe.mp4");
+      }
+    }
+    writeFileSync(path.join(outDir, "CREDIT.txt"), creditText());
+    gate.credit = { text: CREDIT_TEXT, file: path.join(outDir, "CREDIT.txt") };
+    writeFileSync(path.join(outDir, "gate-report.json"), `${JSON.stringify(gate, null, 2)}\n`);
+    return gate;
+  } finally {
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,112 @@
+// Minimal PNG encode/decode with node:zlib, so stills, masks, sheets and preview frames never need
+// an image dependency. Encodes 8-bit grayscale, RGB and RGBA; decodes non-interlaced 8-bit PNGs.
+import { deflateSync, inflateSync } from "node:zlib";
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffers) {
+  let c = 0xffffffff;
+  for (const buf of buffers) for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const name = Buffer.from(type, "ascii");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32([name, data]));
+  return Buffer.concat([len, name, data, crc]);
+}
+
+const COLOR_TYPE = { 1: 0, 3: 2, 4: 6 };
+
+/** Encode `channels` (1 gray, 3 RGB, 4 RGBA) 8-bit pixels, rows top to bottom. */
+export function encodePng(pixels, width, height, channels = 4, { level = 6 } = {}) {
+  const stride = width * channels;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 1; // filter: Sub
+    const row = y * stride;
+    const out = y * (stride + 1) + 1;
+    for (let x = 0; x < stride; x++) raw[out + x] = (pixels[row + x] - (x >= channels ? pixels[row + x - channels] : 0)) & 0xff;
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = COLOR_TYPE[channels];
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw, { level })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/** RGBA -> RGB (drops alpha). */
+export function rgbaToRgb(rgba, width, height) {
+  const out = Buffer.alloc(width * height * 3);
+  for (let i = 0, j = 0; i < rgba.length; i += 4, j += 3) {
+    out[j] = rgba[i]; out[j + 1] = rgba[i + 1]; out[j + 2] = rgba[i + 2];
+  }
+  return out;
+}
+
+/** Decode an 8-bit non-interlaced PNG to { width, height, channels, pixels }. */
+export function decodePng(buf) {
+  if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error("not a PNG");
+  let off = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 0;
+  const idat = [];
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString("ascii", off + 4, off + 8);
+    const data = buf.subarray(off + 8, off + 8 + len);
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      if (data[8] !== 8 || data[12] !== 0) throw new Error("only 8-bit non-interlaced PNG is supported");
+      channels = { 0: 1, 2: 3, 6: 4 }[data[9]];
+      if (!channels) throw new Error(`unsupported PNG colour type ${data[9]}`);
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    off += 12 + len;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const pixels = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const src = y * (stride + 1) + 1;
+    const dst = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? pixels[dst + x - channels] : 0;
+      const b = y > 0 ? pixels[dst - stride + x] : 0;
+      const c = x >= channels && y > 0 ? pixels[dst - stride + x - channels] : 0;
+      let v = raw[src + x];
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a);
+        const pb = Math.abs(p - b);
+        const pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      pixels[dst + x] = v & 0xff;
+    }
+  }
+  return { width, height, channels, pixels };
+}

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

@@ -0,0 +1,161 @@
+// agentvfx (agentvfx licence, see LICENSE). The host side of a render: open the render page in headless Chrome (GPU
+// rung), prepare the templates, step every frame in order, capture, analyse in a worker pool, pipe
+// RGBA to ffmpeg, then replay sampled frames in a fresh browser from frame 0 and compare bytes
+// (determinism; exit 18 semantics after lit-typographic-motion's stage replay).
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { EXIT } from "../core/constants.mjs";
+import { resolvePalette } from "../core/palettes.mjs";
+import { buildSchedule } from "../core/schedule.mjs";
+import { BlockedError } from "./chrome.mjs";
+import { findFfmpeg, startMaster } from "./encode.mjs";
+import { FramePool, StageBrowser, analyzeChecked } from "./stage-capture.mjs";
+import { seedToUnit } from "../web/prelude.mjs";
+import { CREDIT_OVERLAY } from "../core/mark.mjs";
+
+const PAGE = "lit/engine/render.html";
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+
+/** Passes of one template as the page needs them: [{ file, target, persistent }]. */
+export function templatePasses(tpl) {
+  const passes = tpl.fx.PASSES;
+  if (!Array.isArray(passes) || passes.length === 0) return [{ file: "main.frag", target: null, persistent: false }];
+  return passes.map((p, i) => ({ file: i === passes.length - 1 ? "main.frag" : `pass${i}.frag`, target: i === passes.length - 1 ? null : p.TARGET ?? null, persistent: Boolean(p.PERSISTENT) }));
+}
+
+/** Frames the determinism replay samples: first, last and evenly spaced, `n` in all. */
+export function sampleFrames(frameCount, n = 8) {
+  if (frameCount <= n) return Array.from({ length: frameCount }, (_, i) => i);
+  return [...new Set(Array.from({ length: n }, (_, i) => Math.round((i * (frameCount - 1)) / (n - 1))))];
+}
+
+/** The first differing 64x64 block between two RGBA frames, or null. */
+export function firstDifference(a, b, width, height, block = 64) {
+  for (let by = 0; by < height; by += block) {
+    for (let bx = 0; bx < width; bx += block) {
+      for (let y = by; y < Math.min(by + block, height); y++) {
+        for (let x = bx; x < Math.min(bx + block, width); x++) {
+          const o = (y * width + x) * 4;
+          if (a[o] !== b[o] || a[o + 1] !== b[o + 1] || a[o + 2] !== b[o + 2]) return { x: bx, y: by, size: block };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function pagePrepare({ schedule, lib, width, height, seed, palette, probeNondeterminism, credit = null }) {
+  const templates = {};
+  for (const id of schedule.templatesUsed) {
+    const tpl = lib.get(id);
+    templates[id] = { rel: tpl.rel, inputs: tpl.fx.INPUTS ?? [], passes: templatePasses(tpl), text: tpl.fx.X_AGENTVFX.text ?? null };
+  }
+  return { width, height, fps: schedule.fps, seed01: seedToUnit(seed), palette, templates, probeNondeterminism, credit };
+}
+
+function audioFor(features, f) {
+  const fr = features?.frames?.[f];
+  if (!fr) return null;
+  const { xy, ...rest } = fr;
+  return rest;
+}
+
+async function openRenderer({ prepare, width, height, seed, outDir, log, tag }) {
+  const profileDir = mkdtempSync(path.join(tmpdir(), `agentvfx-${tag}-`));
+  const browser = await StageBrowser.open({ stageDir: outDir, page: PAGE, prepare, width, height, seed, profileDir, rung: "gpu", log });
+  if (!browser.prepared?.ok) {
+    await browser.close();
+    throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: render page failed to prepare: ${browser.prepared?.error ?? "no answer"}`);
+  }
+  return browser;
+}
+
+async function stepFrame(browser, f, schedule, features, footage) {
+  if (footage) {
+    const frame = await footage.frame(f);
+    const route = `/lit/frame/${f}.rgba`;
+    browser.dynamic = (p) => (p === route ? { body: frame, type: "application/octet-stream" } : null);
+    await browser.evaluate(`window.__litFootageFetch(${JSON.stringify(route)}, ${footage.width}, ${footage.height})`);
+    browser.dynamic = null;
+  }
+  const plan = { layers: schedule.frames[f].layers.map(({ key, template, params, t, labels, textStyle }) => ({ key, template, params, t, labels, textStyle })), audio: audioFor(features, f), footage: Boolean(footage) };
+  try {
+    await browser.evaluate(`window.__litStep(${f}, ${JSON.stringify(plan)})`);
+  } catch (error) {
+    throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: frame ${f}: ${error.message}`);
+  }
+}
+
+/**
+ * Render a validated score. Options: outDir, width/height (default 1920x1080), features (audio
+ * analysis), footage ({ width, height, frame(f) -> Promise<Buffer RGBA> }), audioFile (muxed),
+ * replay (default true), probeNondeterminism (test hook), onFrame(f, analysed) for stills/flash.
+ * Returns the render report; writes outDir/film.mp4.
+ */
+export async function renderScore(score, lib, opts) {
+  const { outDir, features = null, footage = null, audioFile = null, replay = true, probeNondeterminism = false, onFrame = null, comment = null, log = () => {} } = opts;
+  const width = opts.width ?? footage?.width ?? 1920;
+  const height = opts.height ?? footage?.height ?? 1080;
+  mkdirSync(outDir, { recursive: true });
+  const ffmpeg = findFfmpeg();
+  if (!ffmpeg) throw new BlockedError(EXIT.BLOCKED_NO_FFMPEG_FOR_VIDEO, "BLOCKED_NO_FFMPEG_FOR_VIDEO: ffmpeg not found");
+  const schedule = buildSchedule(score, lib, { features });
+  const palette = resolvePalette(score.palette ?? "rainbow").map((c) => c.map(srgbToLinear));
+  const prepare = pagePrepare({ schedule, lib, width, height, seed: score.seed, palette, probeNondeterminism, credit: score.credit?.overlay === false ? null : CREDIT_OVERLAY });
+  const samples = sampleFrames(schedule.frameCount);
+  const kept = new Map();
+  const shas = [];
+  const film = path.join(outDir, "film.mp4");
+  const pool = new FramePool();
+  let browser = null;
+  let master = null;
+  const t0 = Date.now();
+  try {
+    browser = await openRenderer({ prepare, width, height, seed: score.seed, outDir, log, tag: "master" });
+    const renderer = browser.prepared.renderer;
+    master = startMaster({ ffmpeg, width, height, fps: schedule.fps, out: film, audio: audioFile, comment });
+    let pending = Promise.resolve();
+    for (let f = 0; f < schedule.frameCount; f++) {
+      await stepFrame(browser, f, schedule, features, footage);
+      const png = await browser.capture();
+      const analysed = analyzeChecked(pool, png, width, height);
+      const prev = pending;
+      pending = (async () => {
+        const a = await analysed;
+        await prev;
+        shas[f] = a.rgbaSha256;
+        if (samples.includes(f)) kept.set(f, a.rgba);
+        if (onFrame) await onFrame(f, a);
+        await master.write(a.rgba);
+      })();
+    }
+    await pending;
+    const enc = await master.finish();
+    master = null;
+    if (enc.code !== 0) throw new Error(`ffmpeg failed (${enc.code}): ${enc.stderr}`);
+    await browser.close();
+    browser = null;
+    const report = { renderer, width, height, fps: schedule.fps, frames: schedule.frameCount, durationSec: schedule.frameCount / schedule.fps, renderMs: Date.now() - t0, events: schedule.events, film };
+    if (!replay) return { ...report, determinism: { checked: false } };
+    browser = await openRenderer({ prepare, width, height, seed: score.seed, outDir, log, tag: "replay" });
+    const last = samples[samples.length - 1];
+    for (let f = 0; f <= last; f++) {
+      await stepFrame(browser, f, schedule, features, footage);
+      if (!samples.includes(f)) continue;
+      const a = await analyzeChecked(pool, await browser.capture(), width, height);
+      if (a.rgbaSha256 !== shas[f]) {
+        return { ...report, determinism: { checked: true, pass: false, sampled: samples, frame: f, firstDifference: firstDifference(kept.get(f), a.rgba, width, height) } };
+      }
+    }
+    return { ...report, determinism: { checked: true, pass: true, sampled: samples } };
+  } finally {
+    if (master) await master.finish().catch(() => {});
+    if (browser) await browser.close().catch(() => {});
+    await pool.close();
+  }
+}
+
+export function cleanDir(dir) {
+  rmSync(dir, { recursive: true, force: true });
+}