@mrkt_frwd/reel 0.1.0

package/src/cli.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * Recording CLI.
+ *
+ *   npm run record       -- recordings/<name>/script.json
+ *   npm run record:dry   -- recordings/<name>/script.json
+ *   npm run record:exact -- recordings/<name>/script.json
+ *   npm run record       -- <script> --live https://joeasare.com --formats mp4,gif,vertical
+ *
+ * Two capture modes:
+ *
+ *   realtime      Frames arrive as the compositor paints them, carrying real timestamps,
+ *                 and are resampled to a constant rate at assembly. Fast to run, but the
+ *                 result is bound to machine speed — measured 20-23fps for DOM pages and
+ *                 about 10fps for Three.js under SwiftShader.
+ *
+ *   deterministic Page time is replaced by a virtual clock the recorder advances one frame
+ *                 at a time, screenshotting each. Slow to run and completely indifferent to
+ *                 how slow: a frame costing 900ms of real work is still 1/fps of video, and
+ *                 two runs of one script produce the same frames.
+ */
+import fs from 'fs';
+import path from 'path';
+import { chromium } from 'playwright-core';
+
+import { record, launch } from './runner.mjs';
+import { validate, dryRun, parseViewport } from './schema.mjs';
+import { encodeMaster, encodeVertical, encodeGif, sampleFrames, extractFrames, probeDuration } from './assemble.mjs';
+import { critique, writeCritique } from './critic.mjs';
+import { startServer } from './server.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback = null) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+const has = (name) => argv.includes(`--${name}`);
+
+const scriptPath = argv.find((a) => !a.startsWith('--') && a.endsWith('.json'));
+if (!scriptPath) {
+  console.error('usage: npm run record -- <path/to/script.json> [--dry-run] [--deterministic] [--live <origin>] [--formats mp4,gif,vertical] [--keep-frames] [--gate]');
+  process.exit(2);
+}
+if (!fs.existsSync(scriptPath)) {
+  console.error(`no such script: ${scriptPath}`);
+  process.exit(2);
+}
+
+const script = JSON.parse(fs.readFileSync(scriptPath, 'utf8'));
+const root = process.cwd();
+
+console.log(`\n  RECORD  ${script.name}\n  ────────────────────────────────────`);
+
+// ── gate: the script has to be well formed before a browser is worth opening ──
+const errors = validate(script);
+if (errors.length) {
+  console.error(`\n  ✗ ${errors.length} problem(s) in ${scriptPath}\n`);
+  for (const e of errors) console.error(`      ${e}`);
+  console.error('');
+  process.exit(1);
+}
+console.log('  ✓ script is well formed');
+
+/**
+ * A vertical take is a *recording* at a vertical viewport, not a crop of a landscape one.
+ *
+ * Cropping a 1440x900 master to 9:16 keeps 35% of its width, so a two-column layout loses
+ * a column and the framing argument moves to picking which third to sacrifice. These
+ * templates are responsive, so the answer is to give the page a vertical window and let it
+ * reflow. The crop path stays for deriving a quick short from an existing master, but it
+ * is the fallback now, not the method.
+ *
+ *   npm run record -- <script> --viewport 540x960@2
+ *
+ * CSS pixels at a scale factor, and the two are not interchangeable: a layout switches on
+ * CSS width, so 1080x1920 is still a desktop and the page keeps its two-column form. The
+ * form above is a phone's CSS width rendered at 2x, which reflows *and* delivers a
+ * 1080x1920 frame.
+ *
+ * The take lands in its own directory, because it is a different recording of the same
+ * story: a different capture, a different timeline, its own critique. Sharing a directory
+ * would mean the second take silently overwriting the first's capture.json, and every edit
+ * pointing at that source would change meaning without being touched.
+ */
+const viewportFlag = flag('viewport');
+let outputName = script.name;
+if (viewportFlag) {
+  const v = parseViewport(viewportFlag);
+  if (v.error) {
+    console.error(`\n  ✗ ${v.error}\n`);
+    process.exit(2);
+  }
+  script.viewport = { width: v.width, height: v.height };
+  script.deviceScaleFactor = v.scale;
+  outputName = `${script.name}-${v.suffix}`;
+  console.log(
+    `  ✓ recording at ${v.width}x${v.height} CSS px @${v.scale}x → ${v.outWidth}x${v.outHeight} `
+    + `→ recordings/${outputName}`
+  );
+
+  // The distinction that decides whether a vertical take is worth anything. A responsive
+  // layout switches on *CSS* width, and 1080 CSS px is still a desktop: recording the
+  // brief form at 1080x1920 kept the two-column desktop layout and left the lower third
+  // of the frame empty — a worse result than the crop it was meant to replace. Recording
+  // at a phone's CSS width and scaling up gets the mobile layout at full resolution.
+  // Found by looking at a sample frame, which is the only way this is ever visible.
+  if (v.desktopBreakpoint) {
+    console.warn(`  ! ${v.width} CSS px wide is a desktop breakpoint — the page will not reflow to its mobile layout.`);
+    console.warn(`      For a phone layout at the same pixel size: --viewport ${v.width / 2}x${v.height / 2}@2`);
+  }
+}
+
+const outDir = path.join(root, 'recordings', outputName);
+const liveOrigin = flag('live');
+
+// ── dry run: every selector resolves, nothing is captured ─────────────────────
+if (has('dry-run')) {
+  let server = null;
+  let baseUrl = liveOrigin;
+  if (!baseUrl) {
+    server = await startServer(root);
+    baseUrl = server.base;
+  }
+  const browser = await launch(chromium);
+  const page = await browser.newPage({ viewport: script.viewport || { width: 1440, height: 900 } });
+  try {
+    const missing = await dryRun(script, { page, baseUrl });
+    if (missing.length) {
+      console.error(`\n  ✗ ${missing.length} selector(s) resolve to nothing\n`);
+      for (const m of missing) console.error(`      shot ${m.shot} · ${m.type} · ${m.selector}`);
+      console.error('');
+      process.exit(1);
+    }
+    console.log('  ✓ every selector resolves');
+    console.log('\n  OK dry run — nothing was recorded\n');
+  } finally {
+    await browser.close().catch(() => {});
+    if (server) await server.close();
+  }
+  process.exit(0);
+}
+
+// ── capture ───────────────────────────────────────────────────────────────────
+const result = await record(script, {
+  chromium,
+  outDir,
+  root,
+  baseUrl: liveOrigin,
+  capture: has('deterministic') ? 'deterministic' : undefined,
+  log: (m) => console.log(`  ${m}`),
+});
+
+const { stats, timeline, consoleErrors, assetErrors, framesDir, deterministic } = result;
+
+// A missing font is not a missing image. The page still renders, every frame looks
+// plausible, and the take is quietly in the wrong typeface — which is exactly how the
+// studio tour got recorded in Georgia. Say it before the encode, not after.
+const missingFonts = (assetErrors || []).filter((a) => a.kind === 'font' || a.kind === 'stylesheet');
+if (missingFonts.length) {
+  console.warn(`\n  ! ${missingFonts.length} font/stylesheet request(s) failed — this take is in fallback type:`);
+  for (const a of [...new Map(missingFonts.map((a) => [a.url, a])).values()].slice(0, 5)) {
+    console.warn(`      ${a.detail}  ${a.url}`);
+  }
+  console.warn('      The frames will look fine. They will not be the studio\'s typefaces.\n');
+}
+const fpsTarget = script.fps || 30;
+if (deterministic) {
+  console.log(
+    `  ✓ captured ${stats.count} frames · ${stats.durationSec.toFixed(1)}s · `
+    + `exactly ${fpsTarget} fps (${stats.realMsPerFrame}ms of real work per frame)`
+  );
+} else {
+  console.log(
+    `  ✓ captured ${stats.count} frames · ${stats.durationSec.toFixed(1)}s · `
+    + `${stats.motionFps.toFixed(1)} fps while moving (${stats.heldFrames} held)`
+  );
+}
+if (stats.dropped) console.warn(`  ! ${stats.dropped} frame(s) failed to write`);
+
+// The screencast delivers what the compositor paints, and headless Chromium paces that
+// well below 30fps here — measured 20-23fps during motion on this container, with no
+// launch flag that lifts it. Encoding to a higher constant rate then duplicates frames
+// unevenly, which reads as judder. Say so rather than shipping a number that implies
+// smoothness the capture never had.
+if (!deterministic && stats.motionFps > 0 && stats.motionFps < fpsTarget * 0.8) {
+  console.warn(
+    `  ! captured ${stats.motionFps.toFixed(1)} fps during motion but encoding at ${fpsTarget} — `
+    + `frames will be duplicated. Set "fps": ${Math.max(20, Math.round(stats.motionFps / 2) * 2)}, `
+    + 'or re-run with --deterministic for exact frame timing.'
+  );
+}
+if (stats.count < 2) {
+  console.error('\n  ✗ nothing was captured — the page never painted\n');
+  process.exit(1);
+}
+
+// ── assemble ──────────────────────────────────────────────────────────────────
+const fps = script.fps || 30;
+const formats = (flag('formats') || (script.output?.formats || ['mp4']).join(',')).split(',').map((s) => s.trim());
+const manifest = result.writeManifest(path.join(framesDir, 'frames.txt'));
+const master = path.join(outDir, 'out', `${outputName}.mp4`);
+
+encodeMaster({ manifest, out: master, fps, crf: script.output?.crf ?? 18 });
+console.log(`  ✓ ${path.relative(root, master)}  (${(fs.statSync(master).size / 1e6).toFixed(1)} MB)`);
+
+if (formats.includes('vertical')) {
+  const { width, height } = result.viewport;
+  if (width / height <= 9 / 16 + 0.02) {
+    // Already vertical. Cropping it to 9:16 is a re-encode that changes nothing, and
+    // shipping both leaves two files where one is a slightly worse copy of the other.
+    console.log('  · skipping the vertical derivative — this take is already vertical');
+  } else {
+    const vertical = path.join(outDir, 'out', `${outputName}-vertical.mp4`);
+    encodeVertical({ input: master, out: vertical, focusX: script.output?.focusX ?? 0.5, fps });
+    console.log(`  ✓ ${path.relative(root, vertical)}`);
+    // Say what it costs, at the moment it is paid. A derived vertical from a landscape
+    // take throws most of the frame away; recording the story at a vertical viewport
+    // keeps all of it, because these pages are responsive.
+    const kept = ((height * 9 / 16) / width * 100).toFixed(0);
+    console.log(`      keeps ${kept}% of the width — re-run with --viewport 1080x1920 for a native vertical take`);
+  }
+}
+if (formats.includes('gif')) {
+  const gif = path.join(outDir, 'out', `${outputName}.gif`);
+  encodeGif({ input: master, out: gif, width: script.output?.gifWidth ?? 720 });
+  console.log(`  ✓ ${path.relative(root, gif)}  (${(fs.statSync(gif).size / 1e6).toFixed(1)} MB)`);
+}
+
+// A few stills for a human to glance at; the critic reads a denser strip below.
+const samples = sampleFrames({
+  input: master,
+  dir: path.join(outDir, 'samples'),
+  count: script.sampleCount ?? 6,
+  duration: stats.durationSec,
+});
+console.log(`  ✓ ${samples.length} sample frame(s) for critique`);
+
+// ── critique ──────────────────────────────────────────────────────────────────
+// Judged from the encoded master, so the verdict is about what a viewer will see rather
+// than about an intermediate nobody watches.
+const ANALYSIS_FPS = 4;
+const analysisDir = path.join(outDir, '.analysis');
+let verdict = null;
+try {
+  const analysisFrames = extractFrames({ input: master, dir: analysisDir, fps: ANALYSIS_FPS });
+  verdict = critique({
+    frames: analysisFrames,
+    fps: ANALYSIS_FPS,
+    timeline,
+    durationSec: probeDuration(master),
+  });
+  writeCritique(outDir, verdict, { name: outputName, judgedAt: new Date().toISOString() });
+
+  if (verdict.blockers?.includes('MEASUREMENT_UNAVAILABLE')) {
+    // Not a bad recording — an unjudged one. Printing it as a failure next to a video
+    // that encoded fine reads as though the take were broken.
+    console.warn('  ! critique skipped — no pixel backend to compare frames with');
+    console.warn('      python3 -m pip install --user pillow numpy');
+    console.warn('      (macOS may need --break-system-packages, or use a venv)');
+  } else if (verdict.blockers?.length) {
+    console.error(`  ✗ critique: ${verdict.blockers.join(', ')}`);
+  } else {
+    console.log(`  ✓ critique ${verdict.score}/100 — ${verdict.findings.length} finding(s)`);
+  }
+  for (const f of verdict.findings.slice(0, 6)) {
+    if (f.atSec == null) {
+      // Not every finding is anchored to a moment — a measurement problem is about the
+      // whole run. Formatting one as `undefineds - ` was pure noise.
+      console.log(`      ${f.kind}: ${f.detail}`);
+      continue;
+    }
+    console.log(`      ${String(f.atSec).padStart(6)}s  ${f.shot || '-'}  ${f.kind}: ${f.detail}`);
+  }
+} catch (e) {
+  console.warn(`  ! critique unavailable: ${e.message}`);
+} finally {
+  fs.rmSync(analysisDir, { recursive: true, force: true });
+}
+
+fs.writeFileSync(
+  path.join(outDir, 'capture.json'),
+  JSON.stringify({
+    name: outputName,
+    recordedAt: new Date().toISOString(),
+    viewport: result.viewport,
+    fps,
+    frames: stats.count,
+    capture: deterministic ? 'deterministic' : 'realtime',
+    capturedFps: Number(stats.fps.toFixed(2)),
+    capturedMotionFps: Number(stats.motionFps.toFixed(2)),
+    ...(deterministic ? { realMsPerFrame: stats.realMsPerFrame } : {}),
+    durationSec: probeDuration(master),
+    timeline,
+    consoleErrors,
+    assetErrors,
+    outputs: { master: path.relative(root, master), samples: samples.map((s) => path.relative(root, s)) },
+    critique: verdict ? { score: verdict.score, pass: verdict.pass, findings: verdict.findings.length } : null,
+  }, null, 2)
+);
+
+if (consoleErrors.length) {
+  console.warn(`\n  ! ${consoleErrors.length} console error(s) during capture:`);
+  for (const e of [...new Set(consoleErrors)].slice(0, 5)) console.warn(`      ${e}`);
+}
+
+if (!has('keep-frames')) {
+  fs.rmSync(framesDir, { recursive: true, force: true });
+}
+
+console.log(`\n  OK ${path.relative(root, path.join(outDir, 'capture.json'))}\n`);
+
+// --gate makes the critique decide the exit code, for a loop that should stop on a bad
+// take rather than quietly producing one.
+if (has('gate') && verdict && !verdict.pass) {
+  console.error(`  ✗ critique did not pass (${verdict.score ?? 'unscored'}/100)\n`);
+  process.exit(1);
+}
+process.exit(0);

package/src/clock.mjs

@@ -0,0 +1,131 @@
+/**
+ * Deterministic clock.
+ *
+ * Phase 1 captured whatever the compositor happened to paint, which tied the result to
+ * machine speed: 20-23fps for DOM pages and about 10fps for Three.js under SwiftShader.
+ * This replaces the page's sense of time entirely. The recorder advances a virtual clock
+ * by exactly one frame, runs the callbacks that became due, screenshots, and repeats — so
+ * a frame that takes 900ms of real work still becomes 1/24s of video, and two runs of the
+ * same script produce the same frames.
+ *
+ * Why a JavaScript shim rather than CDP `Emulation.setVirtualTimePolicy`: virtual time
+ * freezes the whole renderer, so any page awaiting a real network response hangs until
+ * the policy is nursed through pending fetches. A shim only replaces the *timing* APIs.
+ * Network, decoding and layout continue on real time, so a page that fetches during a
+ * recording simply works, and a `setTimeout` poll waiting on that fetch still fires
+ * because the recorder keeps advancing.
+ *
+ * Installed with `addInitScript`, before any page script runs — a Three.js app that
+ * captured `performance.now` at module scope would otherwise keep the real one.
+ *
+ * ── What this cannot virtualise ──────────────────────────────────────────────────
+ *   · `<video>` and `<audio>` playback, which run on the media clock. Recorded live.
+ *   · CSS transitions and animations are *sampled*, not stepped: they are paused and
+ *     their currentTime is set from the virtual clock each frame. That is exact for
+ *     time-based animations and wrong for anything driven by transitionend timing.
+ *   · Code reading `new Date()` rather than `Date.now()` — the constructor is left
+ *     alone deliberately, since replacing it breaks date maths in ways that are far
+ *     harder to see than a slightly wrong wall clock.
+ *   · Worker and iframe timers, which have their own global scopes.
+ */
+
+export const CLOCK_INIT = `(() => {
+  if (window.__clock) return;
+
+  const realNow = performance.now.bind(performance);
+  const realDateNow = Date.now.bind(Date);
+  const origin = realDateNow();
+
+  let now = 0;
+  let seq = 0;
+  const rafs = new Map();
+  const timers = new Map();
+
+  // Anything already scheduled by the time we install is left to the real clock; nothing
+  // should be, because this runs before page scripts.
+  const realSetTimeout = window.setTimeout.bind(window);
+
+  window.__clock = {
+    installed: true,
+    get now() { return now; },
+    /** Frames the recorder has asked for; exposed for diagnostics. */
+    ticks: 0,
+
+    /**
+     * Advance virtual time by dt milliseconds and run everything that became due.
+     * Timers fire in due order, then animation callbacks receive the new timestamp,
+     * matching the order a real frame would use.
+     */
+    tick(dt) {
+      now += dt;
+      this.ticks++;
+
+      // Timers can schedule timers. Bound the drain so a setTimeout(fn, 0) loop cannot
+      // spin forever inside a single frame — it yields to the next frame instead.
+      for (let guard = 0; guard < 1000; guard++) {
+        let earliest = null;
+        for (const t of timers.values()) {
+          if (t.due <= now && (!earliest || t.due < earliest.due || (t.due === earliest.due && t.id < earliest.id))) {
+            earliest = t;
+          }
+        }
+        if (!earliest) break;
+        if (earliest.interval == null) timers.delete(earliest.id);
+        else earliest.due = now + Math.max(1, earliest.interval);
+        try { earliest.fn(...(earliest.args || [])); } catch (e) { /* page's problem, not ours */ }
+      }
+
+      // rAF callbacks registered during this flush belong to the *next* frame, which is
+      // how the real one behaves — otherwise a self-rescheduling render loop would run
+      // unbounded inside one tick.
+      const due = [...rafs.entries()];
+      rafs.clear();
+      for (const [, cb] of due) {
+        try { cb(now); } catch (e) { /* ditto */ }
+      }
+
+      // CSS animations and transitions are sampled rather than stepped.
+      if (document.getAnimations) {
+        for (const anim of document.getAnimations()) {
+          try {
+            if (anim.playState === 'running') anim.pause();
+            anim.currentTime = now;
+          } catch (e) { /* not all animations accept a seek */ }
+        }
+      }
+    },
+
+    /** True once the page has asked for at least one frame — tells us a render loop exists. */
+    get pending() { return rafs.size; },
+    get timerCount() { return timers.size; },
+  };
+
+  performance.now = () => now;
+  Date.now = () => origin + now;
+
+  window.requestAnimationFrame = (cb) => { const id = ++seq; rafs.set(id, cb); return id; };
+  window.cancelAnimationFrame = (id) => { rafs.delete(id); };
+
+  window.setTimeout = (fn, delay, ...args) => {
+    if (typeof fn !== 'function') return realSetTimeout(fn, delay);
+    const id = ++seq;
+    timers.set(id, { id, fn, args, due: now + Math.max(0, delay || 0), interval: null });
+    return id;
+  };
+  window.setInterval = (fn, delay, ...args) => {
+    if (typeof fn !== 'function') return 0;
+    const id = ++seq;
+    const every = Math.max(1, delay || 1);
+    timers.set(id, { id, fn, args, due: now + every, interval: every });
+    return id;
+  };
+  window.clearTimeout = (id) => { timers.delete(id); };
+  window.clearInterval = (id) => { timers.delete(id); };
+
+  // Kept so the recorder can measure how much real work a frame cost, which is the only
+  // honest way to report that a scene is heavy once the output no longer shows it.
+  window.__clock.realNow = realNow;
+})();`;
+
+/** Milliseconds of virtual time per frame at a given rate. */
+export const frameMs = (fps) => 1000 / fps;