agentvfx 0.0.0-stage → 0.3.4

package/skills/agentvfx/engine/node/stage-capture.mjs

@@ -0,0 +1,187 @@
+// agentvfx (agentvfx licence, see LICENSE). Adapted from lit-typographic-motion 1.0.45 engine/node/stage-capture.mjs.
+// One stage browser: headless Chrome on the GPU rung, the render page served by Fetch interception on
+// http://lit.stage, the frozen-clock init script injected before any page script, and a step/capture
+// pair the renderer calls frame by frame. The master and the determinism replay each open their own
+// StageBrowser; none of them ever seeks.
+import { readFileSync } from "node:fs";
+import { cpus } from "node:os";
+import { Worker } from "node:worker_threads";
+import { EXIT } from "../core/constants.mjs";
+import { BlockedError, ChromeSession, findChrome, stageFlags } from "./chrome.mjs";
+import { INIT_FILE, STAGE_ORIGIN, stageRouter } from "./stage-serve.mjs";
+
+const withTimeout = (promise, ms, message) => Promise.race([
+  promise,
+  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref()),
+]);
+
+export class StageBrowser {
+  static async open({ stageDir, page = "index.html", prepare = {}, width, height, seed, profileDir, rung = "gpu", env = process.env, log = () => {} }) {
+    const chrome = findChrome(env);
+    if (!chrome) throw new BlockedError(EXIT.BLOCKED_NO_CHROME, "BLOCKED_NO_CHROME: Chrome/Chromium not found (set CHROME_PATH or install Google Chrome)");
+    const flags = stageFlags({ width, height, rung });
+    const session = await ChromeSession.launch({ chrome, flags, profileDir, routes: () => null });
+    const browser = new StageBrowser(session, { stageDir, width, height, flags, rung, log });
+    try {
+      await browser.#attach(seed);
+      await browser.#load(page, prepare);
+    } catch (error) {
+      await browser.close();
+      throw error;
+    }
+    return browser;
+  }
+
+  constructor(session, { stageDir, width, height, flags, rung, log }) {
+    this.session = session;
+    this.rung = rung;
+    this.width = width;
+    this.height = height;
+    this.flags = flags;
+    this.log = log;
+    this.router = stageRouter({ stageDir });
+    this.served = [];
+    this.dynamic = null; // (pathname) => { body: Buffer, type } | null, for per-frame footage
+
+  }
+
+  send(method, params = {}) {
+    return this.session.pipe.send(method, params, this.sessionId);
+  }
+
+  async evaluate(expression, { timeoutMs = 120000 } = {}) {
+    const result = await withTimeout(this.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }), timeoutMs, `stage page evaluation timed out: ${expression.slice(0, 60)}`);
+    if (result.exceptionDetails) throw new Error(`stage page error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+    return result.result.value;
+  }
+
+  async #attach(seed) {
+    const pipe = this.session.pipe;
+    const { targetId } = await pipe.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await pipe.send("Target.attachToTarget", { targetId, flatten: true });
+    this.sessionId = sessionId;
+    pipe.on("Fetch.requestPaused", (p, sid) => {
+      if (sid === sessionId) this.#serve(p);
+    });
+    await this.send("Page.enable");
+    await this.send("Runtime.enable");
+    await this.send("Emulation.setDeviceMetricsOverride", { width: this.width, height: this.height, deviceScaleFactor: 1, mobile: false });
+    await this.send("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] });
+    const init = readFileSync(INIT_FILE, "utf8").replaceAll("__LIT_SEED__", String(seed >>> 0));
+    await this.send("Page.addScriptToEvaluateOnNewDocument", { source: init });
+  }
+
+  async #serve(params) {
+    const url = params.request.url;
+    const dyn = this.dynamic ? this.dynamic(new URL(url).pathname) : null;
+    if (dyn) {
+      await this.send("Fetch.fulfillRequest", {
+        requestId: params.requestId, responseCode: 200,
+        responseHeaders: [{ name: "Content-Type", value: dyn.type }, { name: "Cache-Control", value: "no-store" }],
+        body: dyn.body.toString("base64"),
+      }).catch((error) => this.log(`stage serve ${url}: ${error.message}`));
+      return;
+    }
+    const answer = this.router.route(url);
+    try {
+      if (answer.kind === "blocked") {
+        await this.send("Fetch.failRequest", { requestId: params.requestId, errorReason: "BlockedByClient" });
+        return;
+      }
+      if (answer.kind === "missing") {
+        await this.send("Fetch.fulfillRequest", { requestId: params.requestId, responseCode: 404, body: "" });
+        return;
+      }
+      const body = answer.kind === "file" ? readFileSync(answer.file) : Buffer.from(answer.body);
+      this.served.push(new URL(url).pathname);
+      await this.send("Fetch.fulfillRequest", {
+        requestId: params.requestId, responseCode: 200,
+        responseHeaders: [{ name: "Content-Type", value: answer.type }, { name: "Cache-Control", value: "no-store" }],
+        body: body.toString("base64"),
+      });
+    } catch (error) {
+      this.log(`stage serve ${url}: ${error.message}`);
+    }
+  }
+
+  async #load(page, prepare) {
+    await this.send("Page.navigate", { url: `${STAGE_ORIGIN}/${page}` });
+    const deadline = Date.now() + 60000;
+    for (;;) {
+      const ready = await this.evaluate("document.readyState").catch(() => "loading");
+      if (ready === "complete") break;
+      if (Date.now() > deadline) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR: the stage page did not finish loading within 60 s");
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    this.prepared = await this.evaluate(`window.__litPrepare ? window.__litPrepare(${JSON.stringify(prepare)}) : null`);
+    this.state = await this.evaluate("window.__litStageState ? window.__litStageState() : null");
+  }
+
+  /** Step to frame f (steps 1-7 of the per-frame algorithm run in the page). */
+  step(f, fps, { paint = true } = {}) {
+    return this.evaluate(`window.__litStep(${f}, ${fps}, { paint: ${paint} })`);
+  }
+
+  /** Step 8: capture the viewport; the decoded size is checked by the caller. */
+  async capture() {
+    const shot = await this.send("Page.captureScreenshot", {
+      format: "png", optimizeForSpeed: true, captureBeyondViewport: false, fromSurface: true,
+      clip: { x: 0, y: 0, width: this.width, height: this.height, scale: 1 },
+    });
+    return Buffer.from(shot.data, "base64");
+  }
+
+  pageState() {
+    return this.evaluate("window.__litStageState()");
+  }
+
+  async close() {
+    await this.session.close();
+  }
+}
+
+/** A small pool of frame-analysis workers; results come back in submission order. */
+export class FramePool {
+  constructor(size = Math.max(2, Math.min(6, cpus().length - 2))) {
+    this.workers = Array.from({ length: size }, () => new Worker(new URL("./frame-worker.mjs", import.meta.url)));
+    this.next = 0;
+    this.id = 0;
+    this.waiting = new Map();
+    for (const w of this.workers) {
+      w.on("message", (msg) => {
+        const done = this.waiting.get(msg.id);
+        this.waiting.delete(msg.id);
+        if (msg.error) done.reject(new Error(msg.error));
+        else done.resolve({ ...msg, rgba: Buffer.from(msg.rgba) });
+      });
+      w.on("error", (error) => {
+        for (const p of this.waiting.values()) p.reject(error);
+        this.waiting.clear();
+      });
+    }
+  }
+
+  analyze(png, width, height) {
+    const id = ++this.id;
+    const worker = this.workers[this.next++ % this.workers.length];
+    const copy = png.buffer.slice(png.byteOffset, png.byteOffset + png.byteLength);
+    return new Promise((resolve, reject) => {
+      this.waiting.set(id, { resolve, reject });
+      worker.postMessage({ id, png: copy, width, height }, [copy]);
+    });
+  }
+
+  async close() {
+    await Promise.all(this.workers.map((w) => w.terminate()));
+  }
+}
+
+/** Analyse one capture; a decoded size that is not the format's is exit 17. */
+export async function analyzeChecked(pool, png, width, height) {
+  try {
+    return await pool.analyze(png, width, height);
+  } catch (error) {
+    if (/^captured \d+x\d+/u.test(error.message)) throw new BlockedError(EXIT.STAGE_CONTRACT_ERROR, `STAGE_CONTRACT_ERROR: ${error.message}`);
+    throw error;
+  }
+}

package/skills/agentvfx/engine/node/stage-serve.mjs

@@ -0,0 +1,72 @@
+// agentvfx (agentvfx licence, see LICENSE). Adapted from lit-typographic-motion 1.0.45 engine/node/stage-serve.mjs.
+// Serving without a listening socket: every request the render page makes is paused by CDP Fetch
+// interception and either fulfilled from disk on the synthetic origin http://lit.stage, or failed
+// with BlockedByClient and recorded. Routes: /lit/engine/* (engine/web), /lit/templates/* (the
+// template library) and everything else from the stage dir. Real paths must stay inside their root.
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const STAGE_ORIGIN = "http://lit.stage";
+export const WEB_DIR = fileURLToPath(new URL("../web/", import.meta.url));
+export const TEMPLATES_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
+export const INIT_FILE = fileURLToPath(new URL("../web/init.js", import.meta.url));
+
+export const CONTENT_TYPES = Object.freeze({
+  ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".webp": "image/webp", ".json": "application/json", ".frag": "text/plain; charset=utf-8", ".vert": "text/plain; charset=utf-8",
+  ".glsl": "text/plain; charset=utf-8",
+});
+
+const inside = (root, target) => target === root || target.startsWith(`${root}${path.sep}`);
+
+function resolveUnder(rootDir, rel) {
+  if (rel.includes("\\") || rel.split("/").includes("..")) return { reason: "path traversal" };
+  let root;
+  let real;
+  try {
+    root = realpathSync(rootDir);
+    real = realpathSync(path.join(rootDir, rel));
+  } catch {
+    return { reason: "not found" };
+  }
+  if (!inside(root, real)) return { reason: "resolves outside its root" };
+  const type = CONTENT_TYPES[path.extname(real).toLowerCase()];
+  if (!type || !statSync(real).isFile()) return { reason: "not a servable file" };
+  return { file: real, type };
+}
+
+/**
+ * The request router for one render run. Returns { kind: "file", file, type } | { kind: "blocked" } |
+ * { kind: "missing" }, and records every refusal and miss.
+ */
+export function stageRouter({ stageDir, webDir = WEB_DIR, templatesDir = TEMPLATES_DIR }) {
+  const refused = [];
+  const missing = [];
+  const route = (url) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      refused.push({ url, reason: "unparsable URL" });
+      return { kind: "blocked" };
+    }
+    if (parsed.origin !== STAGE_ORIGIN) {
+      refused.push({ url, reason: "outside the stage origin" });
+      return { kind: "blocked" };
+    }
+    const pathname = decodeURIComponent(parsed.pathname);
+    if (pathname === "/favicon.ico") return { kind: "missing" };
+    let hit;
+    if (pathname.startsWith("/lit/engine/")) hit = resolveUnder(webDir, pathname.slice("/lit/engine/".length));
+    else if (pathname.startsWith("/lit/templates/")) hit = resolveUnder(templatesDir, pathname.slice("/lit/templates/".length));
+    else hit = resolveUnder(stageDir, pathname === "/" ? "index.html" : pathname.replace(/^\/+/u, ""));
+    if (!hit.file) {
+      missing.push({ url, reason: hit.reason });
+      return { kind: "missing" };
+    }
+    return { kind: "file", file: hit.file, type: hit.type };
+  };
+  return { route, refused, missing };
+}

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

@@ -0,0 +1,100 @@
+// The stills set both renderers write, the thing the look rounds are about: one full-size still per
+// beat midpoint, one transition strip per cut (the frames 6 before, at and 6 after the cut, side by
+// side at half size), a 12-frame contact sheet, and `stills/index.json` listing every file with its
+// frames and SHA-256. The index's own SHA-256 is the "stills manifest" a look round is stamped with.
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { areaDownscale } from "./analysis.mjs";
+import { encodePng, rgbaToRgb } from "./png.mjs";
+
+export const STILLS_DIR = "stills";
+export const INDEX_FILE = "index.json";
+export const STRIP_OFFSETS = Object.freeze([-6, 0, 6]);
+export const SHEET_FRAMES = 12;
+const GAP = 12;
+const GROUND = 30;
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const clampFrame = (f, count) => Math.max(0, Math.min(count - 1, f));
+
+/**
+ * Which frames the stills set needs. `beats` are { t0, t1 } in seconds; `cuts` are cut frames.
+ * Returns { beats: [frame], strips: [[f-6, f, f+6]], sheet: [12 frames], poster, reduced, all: Set }.
+ */
+export function stillsPlan({ beats, fps, frameCount, cuts, posterBeat = null }) {
+  const mids = beats.map((b) => clampFrame(Math.round(((b.t0 + b.t1) / 2) * fps), frameCount));
+  const strips = cuts.map((c) => STRIP_OFFSETS.map((o) => clampFrame(c + o, frameCount)));
+  const sheet = Array.from({ length: SHEET_FRAMES }, (_, k) => Math.round((k * (frameCount - 1)) / (SHEET_FRAMES - 1)));
+  const pick = Number.isInteger(posterBeat) && posterBeat >= 0 && posterBeat < mids.length ? posterBeat : Math.floor(mids.length / 2);
+  const all = new Set([...mids, ...strips.flat(), ...sheet]);
+  return { beats: mids, strips, sheet, poster: mids[pick], reduced: mids[mids.length - 1], all };
+}
+
+/** Cut frames of a stage film: every beat boundary after the first, inside the film. */
+export const beatCuts = (beats, fps, frameCount) => beats.slice(1).map((b) => Math.round(b.t0 * fps)).filter((c) => c > 0 && c < frameCount);
+
+function tile(target, W, rgba, w, h, ox, oy) {
+  for (let y = 0; y < h; y++) {
+    const src = y * w * 4;
+    const dst = ((oy + y) * W + ox) * 3;
+    for (let x = 0; x < w; x++) {
+      target[dst + x * 3] = rgba[src + x * 4];
+      target[dst + x * 3 + 1] = rgba[src + x * 4 + 1];
+      target[dst + x * 3 + 2] = rgba[src + x * 4 + 2];
+    }
+  }
+}
+
+/** Compose frames into one RGB PNG: `cols` per row, each scaled to tw x th. */
+export function composeGrid(frames, width, height, { cols, tw, th }) {
+  const rows = Math.ceil(frames.length / cols);
+  const W = cols * tw + (cols + 1) * GAP;
+  const H = rows * th + (rows + 1) * GAP;
+  const out = Buffer.alloc(W * H * 3, GROUND);
+  frames.forEach((rgba, i) => {
+    const small = areaDownscale(rgba, width, height, tw, th);
+    tile(out, W, small, tw, th, GAP + (i % cols) * (tw + GAP), GAP + Math.floor(i / cols) * (th + GAP));
+  });
+  return encodePng(out, W, H, 3, { level: 6 });
+}
+
+export const stripPng = (frames, width, height) => composeGrid(frames, width, height, { cols: 3, tw: Math.round(width / 2), th: Math.round(height / 2) });
+export function sheetPng(frames, width, height) {
+  const landscape = width >= height;
+  return composeGrid(frames, width, height, landscape ? { cols: 4, tw: 480, th: 270 } : { cols: 6, tw: 270, th: 480 });
+}
+export const stillPng = (rgba, width, height) => encodePng(rgbaToRgb(rgba, width, height), width, height, 3, { level: 6 });
+
+/**
+ * Write the stills set from a map frame -> RGBA. Returns { index, sha256, files }. The index lists
+ * paths relative to the output directory; `poster` (full renders) is the delivered poster.png.
+ */
+export function writeStills({ out, plan, frames, width, height, fps, frameCount, round, stillsOnly, path: renderPath, posterFile = null }) {
+  const dir = path.join(out, STILLS_DIR);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const entries = [];
+  const put = (name, bytes, extra) => {
+    writeFileSync(path.join(dir, name), bytes);
+    entries.push({ file: `${STILLS_DIR}/${name}`, sha256: sha256(bytes), ...extra });
+  };
+  plan.beats.forEach((f, i) => put(`beat-${String(i + 1).padStart(2, "0")}.png`, stillPng(frames.get(f), width, height), { kind: "beat", beat: i, frames: [f] }));
+  plan.strips.forEach((fs, i) => put(`strip-${String(i + 1).padStart(2, "0")}.png`, stripPng(fs.map((f) => frames.get(f)), width, height), { kind: "strip", cut: i, frames: fs }));
+  put("sheet.png", sheetPng(plan.sheet.map((f) => frames.get(f)), width, height), { kind: "sheet", frames: plan.sheet });
+  if (posterFile) entries.push({ file: path.relative(out, posterFile), sha256: sha256(readFileSync(posterFile)), kind: "poster", frames: [plan.poster] });
+  const index = { schema: "litclaude.motion-stills/v1", path: renderPath, round, stillsOnly, width, height, fps, frameCount, files: entries };
+  const bytes = Buffer.from(`${JSON.stringify(index, null, 2)}\n`);
+  writeFileSync(path.join(dir, INDEX_FILE), bytes);
+  return { index, sha256: sha256(bytes), files: entries.map((e) => e.file) };
+}
+
+/** Read the latest stills index and its SHA-256 (null when absent). */
+export function readStills(out) {
+  try {
+    const bytes = readFileSync(path.join(out, STILLS_DIR, INDEX_FILE));
+    return { index: JSON.parse(bytes.toString("utf8")), sha256: sha256(bytes) };
+  } catch {
+    return null;
+  }
+}

package/skills/agentvfx/engine/node/ws-server.mjs

@@ -0,0 +1,132 @@
+// Frame egress (MO-A-02 option 1): a minimal RFC 6455 WebSocket server on 127.0.0.1 with an
+// OS-assigned port. The page sends each frame's metadata as a text message and its RGBA bytes as a
+// binary message; the server acks every binary frame so the page never runs more than a few frames
+// ahead. No dependency: the handshake and framing below are the whole protocol this needs.
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+export function startFrameServer({ onText, onBinary, host = "127.0.0.1", listen = null } = {}) {
+  return new Promise((resolve, reject) => {
+    const server = createServer((_, res) => {
+      res.writeHead(426);
+      res.end("websocket only");
+    });
+    let socket = null;
+    server.on("upgrade", (req, sock) => {
+      const key = req.headers["sec-websocket-key"];
+      if (!key || socket) {
+        sock.destroy();
+        return;
+      }
+      const accept = createHash("sha1").update(key + GUID).digest("base64");
+      sock.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+      sock.setNoDelay(true);
+      socket = sock;
+      // Chunks are kept in a list and joined once per frame: re-concatenating on every TCP chunk
+      // would copy an 8 MB frame over a hundred times.
+      let chunks = [];
+      let total = 0;
+      let need = 2;
+      let fragments = [];
+      let fragmentOp = 0;
+      const take = () => {
+        const joined = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, total);
+        chunks = [joined];
+        return joined;
+      };
+      sock.on("data", (chunk) => {
+        chunks.push(chunk);
+        total += chunk.length;
+        while (total >= need) {
+          const buffer = take();
+          const op = buffer[0] & 0x0f;
+          const fin = (buffer[0] & 0x80) !== 0;
+          const masked = (buffer[1] & 0x80) !== 0;
+          let len = buffer[1] & 0x7f;
+          let off = 2;
+          if (len === 126) {
+            if (buffer.length < 4) { need = 4; return; }
+            len = buffer.readUInt16BE(2);
+            off = 4;
+          } else if (len === 127) {
+            if (buffer.length < 10) { need = 10; return; }
+            len = Number(buffer.readBigUInt64BE(2));
+            off = 10;
+          }
+          const maskOff = off;
+          if (masked) off += 4;
+          if (buffer.length < off + len) { need = off + len; return; }
+          const payload = Buffer.from(buffer.subarray(off, off + len));
+          if (masked) {
+            const mask = buffer.subarray(maskOff, maskOff + 4);
+            for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+          }
+          const rest = buffer.subarray(off + len);
+          chunks = rest.length ? [rest] : [];
+          total = rest.length;
+          need = 2;
+          if (op === 0x8) {
+            sock.end();
+            return;
+          }
+          if (op === 0x9) {
+            sendFrame(sock, 0xa, payload);
+            continue;
+          }
+          if (op === 0x1 || op === 0x2) {
+            fragmentOp = op;
+            fragments = [payload];
+          } else if (op === 0x0) fragments.push(payload);
+          else continue;
+          if (!fin) continue;
+          const message = fragments.length === 1 ? fragments[0] : Buffer.concat(fragments);
+          fragments = [];
+          if (fragmentOp === 0x1) onText?.(message.toString("utf8"));
+          else onBinary?.(message);
+        }
+      });
+      sock.on("error", () => {});
+    });
+    server.on("error", reject);
+    const doListen = listen ?? ((srv, cb) => srv.listen(0, host, cb));
+    try {
+      doListen(server, () => {
+        const { port } = server.address();
+        resolve({
+          url: `ws://${host}:${port}/`,
+          ack(text) {
+            if (socket) sendFrame(socket, 0x1, Buffer.from(text));
+          },
+          close() {
+            return new Promise((done) => {
+              socket?.destroy();
+              server.close(() => done());
+            });
+          },
+        });
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+function sendFrame(sock, op, payload) {
+  const len = payload.length;
+  let header;
+  if (len < 126) header = Buffer.from([0x80 | op, len]);
+  else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | op;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | op;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  sock.write(Buffer.concat([header, payload]));
+}