@amg555/frameforge-mcp 2.3.2 → 2.3.3

package/src/harness/lib/encode.mjs

@@ -0,0 +1,89 @@
+/**
+ * encode.mjs — FFmpeg Argv Builders & Final Master Video Encoder
+ *
+ * Enforces broadcast-standard BT.709 color metadata, explicit -t duration (avoiding
+ * the -shortest 0% CPU hang trap), and accurate multi-track audio muxing.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawnSync, spawn } from 'child_process';
+
+/**
+ * Build FFmpeg argv for encoding a directory of image frames into an MP4.
+ */
+export function buildFramesEncodeArgs({
+  framesPattern,
+  duration,
+  fps = 30,
+  crf = 17,
+  preset = 'slow',
+  audioPath = null,
+  outPath,
+}) {
+  const args = [
+    '-y',
+    '-framerate', String(fps),
+    '-pattern_type', 'sequence',
+    '-i', framesPattern,
+  ];
+
+  if (audioPath && fs.existsSync(audioPath)) {
+    args.push(
+      '-i', audioPath,
+      '-c:a', 'aac',
+      '-b:a', '192k',
+      '-ar', '48000',
+      '-ac', '2',
+      '-map', '0:v:0',
+      '-map', '1:a:0'
+    );
+  } else {
+    args.push('-an');
+  }
+
+  args.push(
+    '-c:v', 'libx264',
+    '-preset', preset,
+    '-crf', String(crf),
+    '-profile:v', 'high',
+    '-level', '4.1',
+    '-pix_fmt', 'yuv420p',
+    // BT.709 Color Space Tags (Prevents player color shift)
+    '-color_range', 'tv',
+    '-colorspace', 'bt709',
+    '-color_primaries', 'bt709',
+    '-color_trc', 'bt709',
+    '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709',
+    '-movflags', '+faststart',
+    // Explicit duration prevents -shortest hang trap
+    '-t', String(duration),
+    outPath
+  );
+
+  return args;
+}
+
+/**
+ * Execute FFmpeg encode from frame sequence to MP4 master.
+ */
+export async function encodeFramesToMp4(opts) {
+  const args = buildFramesEncodeArgs(opts);
+  const res = spawnSync('ffmpeg', args, {
+    maxBuffer: 1024 * 1024 * 64,
+    encoding: 'utf8',
+  });
+
+  if (res.status !== 0) {
+    throw new Error(`FFmpeg master encode failed:\n${res.stderr || res.stdout}`);
+  }
+
+  const stat = fs.statSync(opts.outPath);
+  return {
+    outPath: opts.outPath,
+    sizeBytes: stat.size,
+    duration: opts.duration,
+    fps: opts.fps,
+  };
+}
+

package/src/harness/lib/jobs.mjs

@@ -0,0 +1,135 @@
+/**
+ * jobs.mjs — Resumable, Atomic Frame Queue & Worker Pool
+ *
+ * Implements atomic writes (.tmp + renameSync) and corruption checks (<1000 bytes)
+ * so interrupted renders can resume without re-rendering valid frames or trusting truncated ones.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { openPageWithVirtualClock, captureFrame } from './capture.mjs';
+
+/**
+ * Render a frame range across a pool of parallel Playwright pages.
+ *
+ * @param {object} opts
+ * @param {object} opts.browser         Playwright Browser instance
+ * @param {string} opts.htmlPath        Path to index.html or studio.html
+ * @param {string} opts.framesDir       Directory where frame files land
+ * @param {number} opts.first           First frame index (0-based)
+ * @param {number} opts.last            Last frame index (inclusive)
+ * @param {number} opts.fps             Frames per second
+ * @param {number} [opts.workers=4]     Number of parallel worker pages
+ * @param {number} [opts.width=1920]    Frame width
+ * @param {number} [opts.height=1080]   Frame height
+ * @param {string} [opts.format='jpg']  'jpg' or 'png'
+ * @param {number} [opts.quality=0.94]  JPEG quality
+ * @param {function} [opts.onProgress]  (done, total, frameIndex) => void
+ * @returns {Promise<{ total: number, rendered: number, skipped: number, frames: string[] }>}
+ */
+export async function renderFrameJobs({
+  browser,
+  htmlPath,
+  framesDir,
+  first = 0,
+  last,
+  fps = 30,
+  workers = 4,
+  width = 1920,
+  height = 1080,
+  format = 'jpg',
+  quality = 0.94,
+  onProgress = null,
+}) {
+  fs.mkdirSync(framesDir, { recursive: true });
+
+  const ext = format === 'png' ? 'png' : 'jpg';
+  const mimeType = format === 'png' ? 'image/png' : 'image/jpeg';
+
+  const todo = [];
+  let skipped = 0;
+
+  for (let i = first; i <= last; i++) {
+    const filename = `f${String(i).padStart(6, '0')}.${ext}`;
+    const targetFile = path.join(framesDir, filename);
+
+    let existsAndValid = false;
+    try {
+      if (fs.existsSync(targetFile)) {
+        const stat = fs.statSync(targetFile);
+        if (stat.size >= 1000) {
+          existsAndValid = true;
+        }
+      }
+    } catch (_) {}
+
+    if (existsAndValid) {
+      skipped++;
+    } else {
+      todo.push(i);
+    }
+  }
+
+  const totalFrames = last - first + 1;
+  if (todo.length === 0) {
+    return {
+      total: totalFrames,
+      rendered: 0,
+      skipped,
+      frames: fs.readdirSync(framesDir).filter(f => f.startsWith('f') && f.endsWith(`.${ext}`)).map(f => path.join(framesDir, f)),
+    };
+  }
+
+  const workerCount = Math.min(workers, todo.length);
+  const pages = await Promise.all(
+    Array.from({ length: workerCount }, () =>
+      openPageWithVirtualClock(browser, htmlPath, { width, height })
+    )
+  );
+
+  let nextIdx = 0;
+  let doneCount = skipped;
+
+  await Promise.all(
+    pages.map(async (page) => {
+      while (true) {
+        let frameIdx;
+        if (nextIdx < todo.length) {
+          frameIdx = todo[nextIdx++];
+        } else {
+          break;
+        }
+
+        const t = frameIdx / fps;
+        const filename = `f${String(frameIdx).padStart(6, '0')}.${ext}`;
+        const targetFile = path.join(framesDir, filename);
+        const tmpFile = `${targetFile}.tmp`;
+
+        const buf = await captureFrame(page, t, { type: mimeType, quality });
+
+        // Atomic write: write to temp file then rename
+        fs.writeFileSync(tmpFile, buf);
+        fs.renameSync(tmpFile, targetFile);
+
+        doneCount++;
+        if (onProgress) {
+          onProgress(doneCount, totalFrames, frameIdx);
+        }
+      }
+      await page.close();
+    })
+  );
+
+  const allFrames = fs.readdirSync(framesDir)
+    .filter(f => f.startsWith('f') && f.endsWith(`.${ext}`))
+    .sort()
+    .map(f => path.join(framesDir, f));
+
+  return {
+    total: totalFrames,
+    rendered: todo.length,
+    skipped,
+    frames: allFrames,
+  };
+}
+

package/src/harness/lib/pixels.mjs

@@ -0,0 +1,137 @@
+/**
+ * pixels.mjs — Frame Content & Color Inspector
+ *
+ * For inspecting visual content when the model cannot view image media directly.
+ * Catches blank frames, blown flashes, and quadrant-confined content.
+ */
+
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+
+/**
+ * Analyze an RGB24 buffer.
+ * @param {Buffer|Uint8Array} buf   RGB raw bytes (length = width * height * 3)
+ * @param {number} width
+ * @param {number} height
+ * @returns {{
+ *   meanColor: [number, number, number],
+ *   brightPixelShare: number,
+ *   bbox: [number, number, number, number]|null,
+ *   isBlank: boolean,
+ *   isBlown: boolean,
+ *   isCornerConfined: boolean,
+ *   flags: string[]
+ * }}
+ */
+export function analyzeRgbBuffer(buf, width, height) {
+  const totalPixels = width * height;
+  if (!buf || buf.length < totalPixels * 3) {
+    throw new Error(`Buffer size ${buf?.length} too small for ${width}x${height} RGB24`);
+  }
+
+  let rSum = 0;
+  let gSum = 0;
+  let bSum = 0;
+  let brightCount = 0;
+
+  let minX = width;
+  let minY = height;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let i = 0; i < totalPixels; i++) {
+    const idx = i * 3;
+    const r = buf[idx];
+    const g = buf[idx + 1];
+    const b = buf[idx + 2];
+
+    rSum += r;
+    gSum += g;
+    bSum += b;
+
+    // Perceived luminance (ITU-R BT.709)
+    const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+    if (lum > 200) {
+      brightCount++;
+    }
+
+    if (lum > 30) {
+      const x = i % width;
+      const y = Math.floor(i / width);
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+    }
+  }
+
+  const meanR = Math.round(rSum / totalPixels);
+  const meanG = Math.round(gSum / totalPixels);
+  const meanB = Math.round(bSum / totalPixels);
+  const brightPixelShare = brightCount / totalPixels;
+
+  const hasContent = maxX >= 0 && maxY >= 0;
+  const bbox = hasContent ? [minX, minY, maxX, maxY] : null;
+
+  const meanLum = 0.2126 * meanR + 0.7152 * meanG + 0.0722 * meanB;
+  const isBlank = !hasContent || (meanLum < 5 && brightPixelShare < 0.001);
+  const isBlown = brightPixelShare > 0.92;
+
+  let isCornerConfined = false;
+  if (hasContent && !isBlank && !isBlown) {
+    const halfW = width * 0.55;
+    const halfH = height * 0.55;
+    const inTopLeft     = maxX < halfW && maxY < halfH;
+    const inTopRight    = minX > width - halfW && maxY < halfH;
+    const inBottomLeft  = maxX < halfW && minY > height - halfH;
+    const inBottomRight = minX > width - halfW && minY > height - halfH;
+    isCornerConfined = inTopLeft || inTopRight || inBottomLeft || inBottomRight;
+  }
+
+  const flags = [];
+  if (isBlank) flags.push('blank_frame');
+  if (isBlown) flags.push('blown_frame');
+  if (isCornerConfined) flags.push('corner_confined');
+
+  return {
+    meanColor: [meanR, meanG, meanB],
+    brightPixelShare: parseFloat(brightPixelShare.toFixed(4)),
+    bbox,
+    isBlank,
+    isBlown,
+    isCornerConfined,
+    flags,
+  };
+}
+
+/**
+ * Analyze an image file on disk using FFmpeg rawvideo pipe.
+ * @param {string} filePath
+ * @param {number} [width=1920]
+ * @param {number} [height=1080]
+ */
+export function analyzeImageFile(filePath, width = 1920, height = 1080) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const res = spawnSync('ffmpeg', [
+    '-v', 'error',
+    '-i', filePath,
+    '-s', `${width}x${height}`,
+    '-f', 'rawvideo',
+    '-pix_fmt', 'rgb24',
+    '-'
+  ], {
+    maxBuffer: width * height * 3 + 1024,
+    encoding: 'buffer'
+  });
+
+  if (res.status !== 0 || !res.stdout) {
+    throw new Error(`FFmpeg pixel extraction failed: ${res.stderr?.toString() || 'Unknown error'}`);
+  }
+
+  return analyzeRgbBuffer(res.stdout, width, height);
+}
+

package/src/harness/lib/sheets.mjs

@@ -0,0 +1,164 @@
+/**
+ * sheets.mjs — Visual Review Artifact Compositor
+ *
+ * Generates contact sheets, motion strips, full-res crops, and 4-keyframe storyboards
+ * for human/agent review before full encode.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { captureFrame } from './capture.mjs';
+
+function pad6(n) {
+  return String(n).padStart(6, '0');
+}
+
+/**
+ * Render contact sheet of given timestamps.
+ */
+export async function renderSheet({
+  page,
+  times,
+  cols = 6,
+  thumbWidth = 320,
+  aspectRatio = 16 / 9,
+  outPath,
+}) {
+  const thumbHeight = Math.round(thumbWidth / aspectRatio);
+  const rows = Math.ceil(times.length / cols);
+
+  const tmpDir = path.join(path.dirname(outPath), `_sheet_tmp_${Date.now()}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  for (let i = 0; i < times.length; i++) {
+    const buf = await captureFrame(page, times[i]);
+    fs.writeFileSync(path.join(tmpDir, `f_${pad6(i)}.png`), buf);
+  }
+
+  const res = spawnSync('ffmpeg', [
+    '-y',
+    '-i', path.join(tmpDir, 'f_%06d.png'),
+    '-vf', `scale=${thumbWidth}:${thumbHeight},tile=${cols}x${rows}`,
+    '-q:v', '3',
+    outPath,
+  ]);
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  if (res.status !== 0) {
+    throw new Error(`Sheet generation failed: ${res.stderr?.toString()}`);
+  }
+
+  return outPath;
+}
+
+/**
+ * Render motion strip: every frame across a time range [start, end].
+ */
+export async function renderStrip({
+  page,
+  start,
+  end,
+  fps = 30,
+  thumbWidth = 320,
+  aspectRatio = 16 / 9,
+  outPath,
+}) {
+  const thumbHeight = Math.round(thumbWidth / aspectRatio);
+  const startF = Math.round(start * fps);
+  const endF = Math.round(end * fps);
+  const count = Math.max(1, endF - startF + 1);
+
+  const tmpDir = path.join(path.dirname(outPath), `_strip_tmp_${Date.now()}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  for (let i = 0; i < count; i++) {
+    const t = (startF + i) / fps;
+    const buf = await captureFrame(page, t);
+    fs.writeFileSync(path.join(tmpDir, `f_${pad6(i)}.png`), buf);
+  }
+
+  const res = spawnSync('ffmpeg', [
+    '-y',
+    '-i', path.join(tmpDir, 'f_%06d.png'),
+    '-vf', `scale=${thumbWidth}:${thumbHeight},tile=${count}x1`,
+    '-q:v', '3',
+    outPath,
+  ]);
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  if (res.status !== 0) {
+    throw new Error(`Strip generation failed: ${res.stderr?.toString()}`);
+  }
+
+  return outPath;
+}
+
+/**
+ * Render full-res crop region or ratio framing at time t.
+ */
+export async function renderCrop({
+  page,
+  time,
+  crop = null, // [x, y, w, h] or ratio string '9:16'
+  outPath,
+}) {
+  const buf = await captureFrame(page, time);
+  const rawPath = `${outPath}.raw.png`;
+  fs.writeFileSync(rawPath, buf);
+
+  let vfFilter;
+  if (Array.isArray(crop) && crop.length === 4) {
+    const [x, y, w, h] = crop;
+    vfFilter = `crop=${w}:${h}:${x}:${y}`;
+  } else if (crop === '9:16') {
+    vfFilter = 'crop=ih*9/16:ih:(iw-ow)/2:0';
+  } else {
+    vfFilter = 'null';
+  }
+
+  const res = spawnSync('ffmpeg', [
+    '-y',
+    '-i', rawPath,
+    '-vf', vfFilter,
+    outPath,
+  ]);
+
+  try { fs.unlinkSync(rawPath); } catch (_) {}
+
+  if (res.status !== 0) {
+    throw new Error(`Crop generation failed: ${res.stderr?.toString()}`);
+  }
+
+  return outPath;
+}
+
+/**
+ * Render standard 4-keyframe storyboard (0%, 33%, 66%, 100%) in 2x2 grid.
+ */
+export async function renderStoryboard({
+  page,
+  duration,
+  thumbWidth = 480,
+  aspectRatio = 16 / 9,
+  outPath,
+}) {
+  const times = [
+    0,
+    parseFloat((duration * 0.33).toFixed(2)),
+    parseFloat((duration * 0.66).toFixed(2)),
+    Math.max(0, parseFloat((duration - 0.05).toFixed(2))),
+  ];
+
+  return renderSheet({
+    page,
+    times,
+    cols: 2,
+    thumbWidth,
+    aspectRatio,
+    outPath,
+  });
+}
+

package/src/harness/lib/verify-purity.mjs

@@ -0,0 +1,119 @@
+/**
+ * verify-purity.mjs — 3-Point History Leak & Purity Verification Gate
+ *
+ * Enforces the core invariant: Every frame must be a pure function of t.
+ * Tests 3 points per timestamp:
+ *   1. Hash at t (a)
+ *   2. Immediate repeat at t (b)
+ *   3. Wander off to (t + duration/2) % duration
+ *   4. Cold jump back to t (c)
+ * Condition: a === b && a === c.
+ *
+ * If a !== b, frame varies on repeated calls (unseeded randomness / unconstrained timers).
+ * If a !== c, history leaked into the draw path (retained state, incremental physics).
+ */
+
+import { createHash } from 'crypto';
+import { openPageWithVirtualClock, captureFrame } from './capture.mjs';
+
+/**
+ * Verify frame purity across a set of sampled timestamps.
+ *
+ * @param {object} opts
+ * @param {object} opts.browser    Playwright browser instance
+ * @param {string} opts.htmlPath   Path to HTML file
+ * @param {number} [opts.duration] Scene duration (seconds, default reads window.DURATION)
+ * @param {number[]} [opts.times]  Specific times to test (defaults to 9 sampled points)
+ * @param {number} [opts.width=640]  Test render width (lower resolution is faster for hash comparison)
+ * @param {number} [opts.height=360] Test render height
+ * @returns {Promise<{
+ *   passed: boolean,
+ *   timesTested: number,
+ *   results: Array<{ time: number, a: string, b: string, c: string, ok: boolean, failure?: string }>,
+ *   framesSha256?: string
+ * }>}
+ */
+export async function verifyScenePurity({
+  browser,
+  htmlPath,
+  duration = null,
+  times = null,
+  width = null,
+  height = null,
+}) {
+  // Initial page probe for dimensions
+  const probe = await openPageWithVirtualClock(browser, htmlPath, { width: 1080, height: 1080 });
+  const dims = await probe.evaluate(() => {
+    const c = document.querySelector('canvas');
+    return {
+      w: c?.width || window.REEL?.width || 1080,
+      h: c?.height || window.REEL?.height || 1080,
+      dur: window.DURATION || window.REEL?.duration || 2.0,
+    };
+  });
+  await probe.close();
+
+  const resolvedWidth = width || dims.w;
+  const resolvedHeight = height || dims.h;
+  const resolvedDuration = duration || dims.dur;
+
+  const page = await openPageWithVirtualClock(browser, htmlPath, {
+    width: resolvedWidth,
+    height: resolvedHeight,
+  });
+
+  const sampleTimes = times || [
+    0.05 * resolvedDuration,
+    0.15 * resolvedDuration,
+    0.28 * resolvedDuration,
+    0.40 * resolvedDuration,
+    0.50 * resolvedDuration,
+    0.62 * resolvedDuration,
+    0.75 * resolvedDuration,
+    0.88 * resolvedDuration,
+    0.95 * resolvedDuration,
+  ].map(t => parseFloat(t.toFixed(3)));
+
+  async function getFrameHash(t) {
+    const buf = await captureFrame(page, t, { type: 'image/png' });
+    return createHash('sha256').update(buf).digest('hex').slice(0, 16);
+  }
+
+  const results = [];
+  let allPassed = true;
+  const hashDigest = createHash('sha256');
+
+  for (const t of sampleTimes) {
+    // 1. Initial render at t
+    const a = await getFrameHash(t);
+
+    // 2. Immediate repeat at t
+    const b = await getFrameHash(t);
+
+    // 3. Wander off to opposite half of timeline
+    const wanderTime = parseFloat(((t + resolvedDuration / 2) % resolvedDuration).toFixed(3));
+    await getFrameHash(wanderTime);
+
+    // 4. Cold jump back to t
+    const c = await getFrameHash(t);
+
+    const ok = (a === b && a === c);
+    if (!ok) allPassed = false;
+
+    let failure = null;
+    if (a !== b) failure = 'Non-deterministic: repeat call at same t gave different frame';
+    else if (a !== c) failure = 'History leak: frame changed after rendering other timestamps';
+
+    results.push({ time: t, a, b, c, ok, failure });
+    hashDigest.update(a);
+  }
+
+  await page.close();
+
+  return {
+    passed: allPassed,
+    timesTested: sampleTimes.length,
+    results,
+    framesSha256: hashDigest.digest('hex').slice(0, 16),
+  };
+}

package/src/harness/test/fixtures/broken-scene.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>body { margin: 0; background: #0c1116; }</style>
+</head>
+<body>
+<canvas id="frame" width="1080" height="1080"></canvas>
+<script>
+window.DURATION = 2;
+const ctx = document.querySelector("#frame").getContext("2d");
+let historyAccumulator = 0;
+
+// Broken: relies on rAF loop and unseeded Math.random + accumulated state
+window.seek = async (t) => {
+  historyAccumulator += Math.random() * 50; // History leak & randomness!
+  ctx.fillStyle = "#0c1116";
+  ctx.fillRect(0, 0, 1080, 1080);
+  ctx.fillStyle = "#ff5555";
+  ctx.beginPath();
+  ctx.arc(120 + 400 * t + historyAccumulator, 540, 80, 0, 2 * Math.PI);
+  ctx.fill();
+};
+</script>
+</body>
+</html>
+

package/src/harness/test/fixtures/reference-scene.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>body { margin: 0; background: #0c1116; overflow: hidden; }</style>
+</head>
+<body>
+<canvas id="frame" width="1080" height="1080"></canvas>
+<script>
+window.DURATION = 2;
+const ctx = document.querySelector("#frame").getContext("2d");
+window.seek = async (t) => {
+  ctx.fillStyle = "#0c1116";
+  ctx.fillRect(0, 0, 1080, 1080);
+  ctx.fillStyle = "#5be2a1";
+  ctx.beginPath();
+  ctx.arc(120 + 400 * t, 540, 80, 0, 2 * Math.PI);
+  ctx.fill();
+};
+</script>
+</body>
+</html>
+