@mrkt_frwd/reel 0.1.0

package/src/runner.mjs

@@ -0,0 +1,205 @@
+/**
+ * Recording runner — owns the browser for the length of a story.
+ *
+ * The context is created once and reused across every shot, which is the whole reason a
+ * multi-page narrative works: cookies, localStorage, sessionStorage and any in-page state
+ * survive navigation, so shot 4 can show an account page that shot 2 signed into. A
+ * recorder that opens a fresh page per shot can only ever produce disconnected clips.
+ *
+ * Launch flags are inherited from `tools/runtime-audit.mjs`, which is the configuration
+ * already proven to render this repo's WebGL templates headlessly under SwiftShader.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { ACTIONS, resetJitter } from './actions.mjs';
+import { CURSOR_INIT, POLISH_INIT } from './cursor.mjs';
+import { CLOCK_INIT } from './clock.mjs';
+import { ScreencastRecorder, writeManifest } from './capture.mjs';
+import { RealtimeDriver, DeterministicDriver } from './timeline.mjs';
+import { startServer } from './server.mjs';
+
+const LAUNCH_ARGS = [
+  '--use-gl=angle',
+  '--use-angle=swiftshader',
+  '--no-sandbox',
+  '--ignore-gpu-blocklist',
+  '--force-color-profile=srgb',
+  // Screencast quality: without this Chromium throttles the compositor when the window
+  // is not focused, which in headless means always.
+  '--disable-backgrounding-occluded-windows',
+  '--disable-renderer-backgrounding',
+  '--disable-background-timer-throttling',
+  '--hide-scrollbars',
+];
+
+/**
+ * Playwright's bundled browser revision and the one baked into a container image drift
+ * apart, and the resulting error names a path that was never going to exist. Prefer an
+ * explicit binary when one is present.
+ */
+export function resolveExecutable() {
+  if (process.env.CHROMIUM_PATH) return process.env.CHROMIUM_PATH;
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH || '/opt/pw-browsers';
+  if (!fs.existsSync(root)) return undefined;
+  const candidates = fs
+    .readdirSync(root)
+    .filter((d) => d.startsWith('chromium-'))
+    .sort()
+    .reverse()
+    .map((d) => path.join(root, d, 'chrome-linux', 'chrome'));
+  return candidates.find((c) => fs.existsSync(c));
+}
+
+export async function launch(chromium, { headless = true } = {}) {
+  const executablePath = resolveExecutable();
+  return chromium.launch({ headless, args: LAUNCH_ARGS, ...(executablePath ? { executablePath } : {}) });
+}
+
+/**
+ * Run a script end to end.
+ *
+ * @param {object} script parsed script.json
+ * @param {object} opts
+ * @param {import('playwright-core').BrowserType} opts.chromium
+ * @param {string} opts.outDir where frames and video land
+ * @param {string} [opts.baseUrl] skip the local server and record a deployed origin
+ * @param {string} [opts.root] document root for the local server
+ * @param {(msg: string) => void} [opts.log]
+ */
+export async function record(script, opts) {
+  const log = opts.log || (() => {});
+  const viewport = script.viewport || { width: 1440, height: 900 };
+  const framesDir = path.join(opts.outDir, 'frames');
+
+  let server = null;
+  let baseUrl = opts.baseUrl;
+  if (!baseUrl) {
+    server = await startServer(opts.root || process.cwd());
+    baseUrl = server.base;
+    log(`serving ${opts.root || process.cwd()} at ${baseUrl}`);
+  }
+
+  const browser = await launch(opts.chromium);
+  const context = await browser.newContext({
+    viewport,
+    deviceScaleFactor: script.deviceScaleFactor || 1,
+    reducedMotion: 'no-preference',
+    colorScheme: script.colorScheme || 'dark',
+  });
+
+  // Before any page script runs, on every navigation. The clock goes first: a Three.js
+  // app that captured performance.now at module scope would otherwise keep the real one.
+  const deterministic = (script.capture || opts.capture) === 'deterministic';
+  if (deterministic) await context.addInitScript(CLOCK_INIT);
+  await context.addInitScript(POLISH_INIT);
+  await context.addInitScript(CURSOR_INIT);
+
+  const page = await context.newPage();
+  const consoleErrors = [];
+  page.on('console', (m) => { if (m.type() === 'error') consoleErrors.push(m.text().slice(0, 200)); });
+  page.on('pageerror', (e) => consoleErrors.push(`pageerror: ${e.message.slice(0, 200)}`));
+
+  /**
+   * Assets that did not arrive, named.
+   *
+   * The console reports these as "Failed to load resource: 404" with no URL, which is
+   * unactionable — two sessions logged six of them and chased none, because there was
+   * nothing to chase. Recording the URL turns a number into a defect.
+   *
+   * A font matters more than the count suggests: a page whose typeface never arrived
+   * renders in its fallback stack and looks entirely plausible doing it, frame by frame.
+   * The studio recorded its whole tour in Georgia that way. So fonts and stylesheets are
+   * flagged separately from an image nobody will miss.
+   */
+  const assetErrors = [];
+  const noteAsset = (url, detail) => {
+    if (assetErrors.length > 60) return;
+    const kind = /\.(woff2?|ttf|otf)(\?|$)/i.test(url) ? 'font'
+      : /\.css(\?|$)|fonts\.googleapis/i.test(url) ? 'stylesheet'
+        : 'asset';
+    assetErrors.push({ kind, url: url.slice(0, 300), detail });
+  };
+  page.on('response', (r) => { if (r.status() >= 400) noteAsset(r.url(), String(r.status())); });
+  page.on('requestfailed', (r) => noteAsset(r.url(), r.failure()?.errorText || 'request failed'));
+
+  fs.rmSync(framesDir, { recursive: true, force: true });
+  const fps = script.fps || 30;
+
+  const driver = deterministic
+    ? new DeterministicDriver(page, {
+        fps,
+        dir: framesDir,
+        quality: script.quality ?? 90,
+        format: script.frameFormat || 'jpeg',
+      })
+    : new RealtimeDriver(page, { fps });
+
+  // Realtime observes what the compositor paints; deterministic captures each frame it
+  // has just computed, so only the former needs a screencast attached.
+  const recorder = deterministic
+    ? null
+    : new ScreencastRecorder(page, { dir: framesDir, quality: script.quality ?? 80 });
+
+  // Same script, same keystroke cadence — see resetJitter in actions.mjs.
+  resetJitter();
+
+  const ctx = { page, context, baseUrl, log, driver };
+  const timeline = [];
+  let stats = null;
+
+  try {
+    // The first goto happens before capture starts so the initial paint and font swap
+    // are not the opening frames of the video.
+    const first = script.shots[0]?.actions?.[0];
+    if (first?.type === 'goto') {
+      await ACTIONS.goto(ctx, first);
+      await page.waitForTimeout(script.settleMs ?? 600);
+    }
+
+    if (recorder) await recorder.start();
+    else driver.startCapture();
+    const t0 = Date.now();
+
+    const elapsed = () => (deterministic ? driver.virtualMs / 1000 : (Date.now() - t0) / 1000);
+
+    for (const shot of script.shots) {
+      const shotStart = elapsed();
+      log(`  shot ${shot.id} — ${shot.intent}`);
+      for (const [i, action] of shot.actions.entries()) {
+        if (shot === script.shots[0] && i === 0 && first?.type === 'goto') continue;
+        const fn = ACTIONS[action.type];
+        if (!fn) throw new Error(`unknown action "${action.type}" in shot ${shot.id}`);
+        await fn(ctx, action);
+      }
+      timeline.push({
+        id: shot.id,
+        intent: shot.intent,
+        startSec: Number(shotStart.toFixed(3)),
+        endSec: Number(elapsed().toFixed(3)),
+      });
+    }
+  } finally {
+    if (recorder) {
+      stats = await recorder.stop();
+    } else {
+      driver.stopCapture();
+      stats = driver.summary();
+    }
+    await context.close().catch(() => {});
+    await browser.close().catch(() => {});
+    if (server) await server.close();
+  }
+
+  const frames = recorder ? recorder.frames : driver.frames;
+  return {
+    stats,
+    timeline,
+    consoleErrors,
+    assetErrors,
+    framesDir,
+    viewport,
+    deterministic,
+    writeManifest: (file) => writeManifest(frames, file),
+  };
+}

package/src/schema.mjs

@@ -0,0 +1,157 @@
+/**
+ * Script validation and the dry run.
+ *
+ * This is the handoff gate between the director agent (who writes `script.json`) and the
+ * interaction developer (who makes it actually run). The failure this exists to catch is
+ * the one this repo keeps finding in other guises: a reference that *looks* wired and is
+ * not. A selector that matches nothing does not throw at author time — it throws four
+ * minutes into a capture, after the browser has been driven halfway through a story.
+ *
+ * `validate` is static and free. `dryRun` opens the pages and asserts every selector the
+ * script names actually resolves, without recording anything.
+ */
+import { ACTION_TYPES } from './actions.mjs';
+
+const REQUIRED_BY_TYPE = {
+  goto: ['url'],
+  waitFor: [],
+  hold: [],
+  moveTo: ['x', 'y'],
+  hover: ['selector'],
+  click: ['selector'],
+  type: ['selector', 'text'],
+  press: ['key'],
+  scroll: ['to'],
+  drag: [],
+  eval: ['fn'],
+  inject: [],
+  route: ['url'],
+  setViewport: ['width', 'height'],
+  cursor: [],
+};
+
+/**
+ * @param {object} script parsed script.json
+ * @returns {string[]} problems, empty when the script is well formed
+ */
+export function validate(script) {
+  const errors = [];
+  if (!script || typeof script !== 'object') return ['script is not an object'];
+  if (!script.name || !/^[a-z0-9][a-z0-9-]*$/.test(script.name)) {
+    errors.push('name must be a lowercase slug — it becomes the output directory');
+  }
+  if (!Array.isArray(script.shots) || script.shots.length === 0) {
+    errors.push('script has no shots');
+    return errors;
+  }
+  if (script.fps != null && (script.fps < 1 || script.fps > 60)) {
+    errors.push(`fps ${script.fps} is outside 1-60`);
+  }
+
+  const ids = new Set();
+  script.shots.forEach((shot, si) => {
+    const where = `shot ${si}${shot.id ? ` (${shot.id})` : ''}`;
+    if (!shot.id) errors.push(`${where}: missing id`);
+    else if (ids.has(shot.id)) errors.push(`${where}: duplicate id`);
+    ids.add(shot.id);
+    // The intent line is what the critic judges the frames against. Without it a
+    // critique can only be about taste.
+    if (!shot.intent) errors.push(`${where}: missing intent — the critic has nothing to judge against`);
+    if (!Array.isArray(shot.actions) || shot.actions.length === 0) {
+      errors.push(`${where}: no actions`);
+      return;
+    }
+    shot.actions.forEach((a, ai) => {
+      const at = `${where} action ${ai}`;
+      if (!a || !a.type) return errors.push(`${at}: missing type`);
+      if (!ACTION_TYPES.includes(a.type)) {
+        return errors.push(`${at}: unknown action "${a.type}" — known: ${ACTION_TYPES.join(', ')}`);
+      }
+      for (const key of REQUIRED_BY_TYPE[a.type] || []) {
+        if (a[key] === undefined) errors.push(`${at}: "${a.type}" requires "${key}"`);
+      }
+      if (a.type === 'drag' && !a.selector && (a.x === undefined || a.y === undefined)) {
+        errors.push(`${at}: drag needs a selector or an x/y start point`);
+      }
+    });
+  });
+
+  // A story that never navigates is a screenshot with extra steps.
+  const hasGoto = script.shots.some((s) => (s.actions || []).some((a) => a.type === 'goto'));
+  if (!hasGoto) errors.push('no shot navigates anywhere — every script needs at least one goto');
+
+  return errors;
+}
+
+/** Selectors a shot depends on, in the order the script will need them. */
+export function selectorsFor(shot) {
+  return (shot.actions || [])
+    .filter((a) => a.selector && a.type !== 'waitFor')
+    .map((a) => ({ selector: a.selector, type: a.type }));
+}
+
+/**
+ * Walk the script for real, resolving every selector, without capturing. Navigations and
+ * waits run; interactions do not. Returns the list of unresolved references.
+ *
+ * @returns {Promise<{ selector: string, shot: string, type: string }[]>}
+ */
+export async function dryRun(script, { page, baseUrl }) {
+  const missing = [];
+  for (const shot of script.shots) {
+    for (const a of shot.actions) {
+      if (a.type === 'goto') {
+        const url = /^https?:/i.test(a.url) ? a.url : baseUrl + (a.url.startsWith('/') ? a.url : `/${a.url}`);
+        await page.goto(url, { waitUntil: 'load', timeout: a.timeout || 30000 });
+        continue;
+      }
+      if (a.type === 'waitFor' && a.selector) {
+        await page.locator(a.selector).first()
+          .waitFor({ state: a.state || 'visible', timeout: a.timeout || 15000 })
+          .catch(() => missing.push({ selector: a.selector, shot: shot.id, type: 'waitFor' }));
+        continue;
+      }
+      if (a.type === 'setViewport') {
+        await page.setViewportSize({ width: a.width, height: a.height });
+        continue;
+      }
+      if (!a.selector) continue;
+      const count = await page.locator(a.selector).count().catch(() => 0);
+      if (count === 0) missing.push({ selector: a.selector, shot: shot.id, type: a.type });
+    }
+  }
+  return missing;
+}
+
+/**
+ * `--viewport WIDTHxHEIGHT[@SCALE]` → the take's viewport, scale factor and variant name.
+ *
+ * Separated from the CLI so the parsing and the naming can be asserted without launching
+ * a browser. Returns `{ error }` rather than throwing, because the caller reports it and
+ * exits with a usage code.
+ */
+export function parseViewport(value) {
+  const m = /^(\d{2,4})x(\d{2,4})(?:@(\d(?:\.\d)?))?$/.exec(String(value ?? '').trim());
+  if (!m) return { error: `--viewport wants WIDTHxHEIGHT[@SCALE], e.g. 540x960@2 — got "${value}"` };
+
+  const width = Number(m[1]);
+  const height = Number(m[2]);
+  const scale = m[3] ? Number(m[3]) : 1;
+  if (scale < 1 || scale > 3) return { error: `scale ${scale} is outside 1-3` };
+
+  const ratio = width / height;
+  const suffix =
+    Math.abs(ratio - 9 / 16) < 0.02 ? 'vertical'
+      : Math.abs(ratio - 1) < 0.02 ? 'square'
+        : Math.abs(ratio - 16 / 9) < 0.02 ? 'wide'
+          : `${width}x${height}`;
+
+  // A responsive layout switches on CSS width, not on output pixels. 1080 CSS px is still
+  // a desktop: the first vertical take recorded that way kept its two-column layout and
+  // left the bottom third of the frame empty — worse than the crop it was meant to
+  // replace. Flagged rather than corrected, because a wide vertical take is legitimate
+  // when the subject is a 3D stage that does not reflow at all.
+  const desktopBreakpoint = width >= 900 && ratio < 1;
+
+  return { width, height, scale, suffix, desktopBreakpoint, outWidth: width * scale, outHeight: height * scale };
+}

package/src/server.mjs

@@ -0,0 +1,109 @@
+/**
+ * Static file server for recordings.
+ *
+ * Deliberately separate from the one inside `tools/runtime-audit.mjs`, which is not
+ * importable — that file has no exports and runs its audit on import. Unifying the two
+ * means editing the file CI depends on most, so it is a change of its own rather than a
+ * passenger on this one. Recording also needs behaviour the audit does not: it serves a
+ * chosen document root and honours `cleanUrls` the way `vercel.json` declares it, so a
+ * script can say `/library` and get `library.html` exactly as production would.
+ */
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.webp': 'image/webp',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.glb': 'model/gltf-binary',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.map': 'application/json',
+};
+
+/**
+ * Commerce endpoints answer with a signed-out stub. A recording of the editor should
+ * show the real gated state rather than a network error, and no recording should ever
+ * depend on live Stripe.
+ */
+function mockApi(pathname, res) {
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  if (/\/api\/me$/.test(pathname)) {
+    res.writeHead(200);
+    res.end(JSON.stringify({ authenticated: false, pro: false, plan: null, templates: {}, mock: true }));
+    return true;
+  }
+  if (/\/api\/export-allowed$/.test(pathname)) {
+    res.writeHead(200);
+    res.end(JSON.stringify({ allowed: false, reason: 'signin', mock: true }));
+    return true;
+  }
+  if (pathname.startsWith('/api/')) {
+    res.writeHead(200);
+    res.end(JSON.stringify({ ok: true, mock: true }));
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} root document root
+ * @returns {Promise<{ base: string, close: () => Promise<void> }>}
+ */
+export async function startServer(root) {
+  const server = http.createServer((req, res) => {
+    let pathname;
+    try {
+      pathname = decodeURIComponent(new URL(req.url, 'http://127.0.0.1').pathname);
+    } catch {
+      res.writeHead(400);
+      return res.end('bad request');
+    }
+
+    if (mockApi(pathname, res)) return;
+
+    let file = path.join(root, pathname);
+    // cleanUrls: /library resolves to library.html, matching vercel.json.
+    if (!path.extname(file)) {
+      if (fs.existsSync(`${file}.html`)) file = `${file}.html`;
+      else if (fs.existsSync(path.join(file, 'index.html'))) file = path.join(file, 'index.html');
+    }
+    if (pathname === '/') file = path.join(root, 'index.html');
+
+    // Never serve outside the document root, whatever the request path claims.
+    const resolved = path.resolve(file);
+    if (!resolved.startsWith(path.resolve(root))) {
+      res.writeHead(403);
+      return res.end('forbidden');
+    }
+    if (!fs.existsSync(resolved) || fs.statSync(resolved).isDirectory()) {
+      res.writeHead(404);
+      return res.end('not found');
+    }
+
+    res.setHeader('Content-Type', MIME[path.extname(resolved)] || 'application/octet-stream');
+    res.setHeader('Cache-Control', 'no-store');
+    res.writeHead(200);
+    res.end(fs.readFileSync(resolved));
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+
+  return {
+    base: `http://127.0.0.1:${port}`,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}

package/src/timeline.mjs

@@ -0,0 +1,120 @@
+/**
+ * The two ways time can pass during a recording.
+ *
+ * Actions do not know which they are running under. They ask the driver to wait, or to
+ * animate a value over a duration, and the driver decides whether that means sleeping and
+ * hoping the compositor keeps up, or advancing a virtual clock one frame at a time and
+ * taking a screenshot per frame. Keeping that decision in one place is what let phase 2
+ * land without rewriting the verb vocabulary.
+ *
+ *   realtime      — phase 1. Fast to run, output bound to machine speed.
+ *   deterministic — phase 2. Slow to run, output independent of machine speed and
+ *                   identical across runs.
+ */
+import fs from 'fs';
+import path from 'path';
+
+const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+
+/** Wall-clock pacing. Frames are whatever the screencast delivers alongside. */
+export class RealtimeDriver {
+  constructor(page, { fps = 30 } = {}) {
+    this.page = page;
+    this.frameMs = 1000 / fps;
+    this.deterministic = false;
+  }
+
+  async wait(ms) {
+    if (ms > 0) await this.page.waitForTimeout(ms);
+  }
+
+  /**
+   * Run `onStep(t)` across `ms`, where t is eased 0..1. Sleeps only the remainder of each
+   * step, so the animation takes the duration it says regardless of driver round trips —
+   * a fixed sleep per step made every move overrun.
+   */
+  async animate(ms, onStep) {
+    const steps = Math.max(1, Math.round(ms / this.frameMs));
+    const t0 = Date.now();
+    for (let i = 1; i <= steps; i++) {
+      await onStep(ease(i / steps), i / steps);
+      const behind = t0 + (i / steps) * ms - Date.now();
+      if (behind > 0) await this.page.waitForTimeout(behind);
+    }
+  }
+}
+
+/**
+ * Virtual pacing. Every frame is exactly `frameMs` of page time, whatever it cost to
+ * produce, and every frame is captured explicitly rather than observed.
+ */
+export class DeterministicDriver {
+  constructor(page, { fps = 30, dir, quality = 90, format = 'jpeg' } = {}) {
+    this.page = page;
+    this.fps = fps;
+    this.frameMs = 1000 / fps;
+    this.dir = dir;
+    this.quality = quality;
+    this.format = format;
+    this.deterministic = true;
+    this.frames = [];
+    this.capturing = false;
+    this.virtualMs = 0;
+    this.realMsInFrames = 0;
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  startCapture() { this.capturing = true; }
+  stopCapture() { this.capturing = false; }
+
+  /** Advance one frame of page time, then record what it painted. */
+  async tick() {
+    const realStart = Date.now();
+    await this.page.evaluate((dt) => window.__clock && window.__clock.tick(dt), this.frameMs);
+    this.virtualMs += this.frameMs;
+
+    if (this.capturing) {
+      const index = this.frames.length;
+      const ext = this.format === 'png' ? 'png' : 'jpg';
+      const file = path.join(this.dir, `f${String(index).padStart(6, '0')}.${ext}`);
+      // A screenshot forces a paint, which is what makes the frame we just computed
+      // actually exist. This is also the slow part, and deliberately so — wall-clock cost
+      // stops mattering once the output no longer depends on it.
+      const buf = await this.page.screenshot(
+        this.format === 'png' ? { type: 'png' } : { type: 'jpeg', quality: this.quality }
+      );
+      fs.writeFileSync(file, buf);
+      this.frames.push({ file, t: this.virtualMs / 1000 });
+    }
+    this.realMsInFrames += Date.now() - realStart;
+  }
+
+  async wait(ms) {
+    const frames = Math.max(0, Math.round(ms / this.frameMs));
+    for (let i = 0; i < frames; i++) await this.tick();
+  }
+
+  async animate(ms, onStep) {
+    const steps = Math.max(1, Math.round(ms / this.frameMs));
+    for (let i = 1; i <= steps; i++) {
+      await onStep(ease(i / steps), i / steps);
+      await this.tick();
+    }
+  }
+
+  summary() {
+    return {
+      count: this.frames.length,
+      dropped: 0,
+      durationSec: this.frames.length / this.fps,
+      fps: this.fps,
+      motionFps: this.fps,
+      heldFrames: 0,
+      deterministic: true,
+      // How long the machine actually took per frame. Once output is decoupled from
+      // speed this is the only place heaviness is still visible, and it is worth
+      // surfacing rather than hiding — it is what says a scene is expensive.
+      realMsPerFrame: this.frames.length ? Number((this.realMsInFrames / this.frames.length).toFixed(1)) : 0,
+    };
+  }
+}