@mrkt_frwd/reel 0.1.0

package/src/assemble.mjs

@@ -0,0 +1,362 @@
+/**
+ * Frames to deliverable video.
+ *
+ * Encodes the master at a constant frame rate from the irregular capture, then derives
+ * the formats the reference briefs call for: a landscape MP4 for product demos, a 9:16
+ * crop for social, and a GIF for the landing hover-preview that `index.html` and
+ * `shells/registry.json` already swap in when a `preview` field is set.
+ *
+ * `yuv420p` and the even-dimension scale filter are not decoration: without them Safari
+ * and most social uploaders refuse the file or re-encode it badly, and an odd pixel
+ * dimension makes libx264 fail outright.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+// The director's-name → filter-name map lives with the edit vocabulary. Imported rather
+// than restated: two copies of a mapping table drift, and the drift is invisible until an
+// edit names a transition one file knows about and the other does not.
+import { TRANSITIONS } from './edit.mjs';
+
+const require = createRequire(import.meta.url);
+
+function ffmpegBin() {
+  if (process.env.FFMPEG) return process.env.FFMPEG;
+  try {
+    return require('ffmpeg-static');
+  } catch {
+    return 'ffmpeg';
+  }
+}
+
+function run(args, label) {
+  const bin = ffmpegBin();
+  const res = spawnSync(bin, ['-hide_banner', '-loglevel', 'error', '-y', ...args], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) throw new Error(`${label}: could not run ffmpeg (${res.error.message})`);
+  if (res.status !== 0) throw new Error(`${label}: ${(res.stderr || '').slice(-600)}`);
+}
+
+const EVEN = 'scale=trunc(iw/2)*2:trunc(ih/2)*2';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.manifest ffmpeg concat file written by the recorder
+ * @param {string} opts.out master MP4 path
+ * @param {number} [opts.fps] constant output rate
+ * @param {number} [opts.crf] 18 is a master; 23 is a web deliverable
+ */
+export function encodeMaster({ manifest, out, fps = 30, crf = 18 }) {
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  run([
+    '-f', 'concat', '-safe', '0', '-i', manifest,
+    '-vsync', 'cfr', '-r', String(fps),
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', String(crf),
+    '-pix_fmt', 'yuv420p', '-movflags', '+faststart',
+    '-vf', EVEN,
+    out,
+  ], 'encode master');
+  return out;
+}
+
+/**
+ * 9:16 for social. Crops to the centre of interest rather than letterboxing, because a
+ * letterboxed product demo reads as an afterthought in a vertical feed. `focusX` is a
+ * 0-1 fraction — a left-hand form or a right-hand 3D stage is rarely centred.
+ */
+export function encodeVertical({ input, out, focusX = 0.5, fps = 30, crf = 20 }) {
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const x = `(iw-ow)*${Math.max(0, Math.min(1, focusX)).toFixed(3)}`;
+  run([
+    '-i', input,
+    '-vf', `crop=ih*9/16:ih:${x}:0,scale=1080:1920:flags=lanczos,${EVEN}`,
+    '-r', String(fps),
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', String(crf),
+    '-pix_fmt', 'yuv420p', '-movflags', '+faststart',
+    out,
+  ], 'encode vertical');
+  return out;
+}
+
+/** Two-pass palette GIF. A single-pass GIF of a dark UI bands badly. */
+export function encodeGif({ input, out, width = 720, fps = 15 }) {
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const palette = path.join(path.dirname(out), '.palette.png');
+  const filters = `fps=${fps},scale=${width}:-1:flags=lanczos`;
+  run(['-i', input, '-vf', `${filters},palettegen=stats_mode=diff`, palette], 'gif palette');
+  run([
+    '-i', input, '-i', palette,
+    '-lavfi', `${filters}[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=3`,
+    out,
+  ], 'gif encode');
+  fs.rmSync(palette, { force: true });
+  return out;
+}
+
+/**
+ * A handful of stills spread across the runtime, for a human to glance at.
+ *
+ * Not what the critic reads — see `extractFrames`, which pulls a dense strip. These are
+ * for the reviewer who wants to see four or five moments without opening the video.
+ */
+export function sampleFrames({ input, dir, count = 6, duration }) {
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Spread the samples across the whole runtime. The obvious `thumbnail,fps=1/1` with a
+  // frame cap does not do this — it takes the first N seconds and stops, so every sample
+  // of a ninety-second tour came from the opening shot and the later shots were never
+  // looked at. A critique built on that is worse than none, because it reads as coverage.
+  const seconds = duration || probeDuration(input) || count;
+  const rate = count / Math.max(seconds, 0.001);
+
+  run([
+    '-i', input,
+    '-vf', `fps=${rate.toFixed(6)},scale=1280:-1`,
+    '-frames:v', String(count),
+    path.join(dir, 'sample-%02d.png'),
+  ], 'sample frames');
+
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith('sample-'))
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+/**
+ * Dense frames for the critic, extracted from the finished master.
+ *
+ * Taken from the encoded video rather than the capture frames on purpose: the critic
+ * should judge what a viewer will actually see, after resampling and compression, not an
+ * intermediate nobody watches. Four per second is enough to catch a frozen shot or a jump
+ * without making the analysis cost more than the recording.
+ */
+export function extractFrames({ input, dir, fps = 4 }) {
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  run([
+    '-i', input,
+    '-vf', `fps=${fps},scale=480:-1:flags=bilinear`,
+    path.join(dir, 'a-%05d.png'),
+  ], 'extract analysis frames');
+  return fs.readdirSync(dir).filter((f) => f.startsWith('a-')).sort().map((f) => path.join(dir, f));
+}
+
+/**
+ * Cut an edit from a master: trim each segment, retime it, burn its caption in, crop to
+ * the target aspect, and concatenate.
+ *
+ * Done as one filtergraph rather than encoding each segment to a file and concatenating.
+ * Two reasons: a re-encode per segment costs quality at every cut, and the concat demuxer
+ * needs every input to share codec parameters — which a per-segment crop or speed change
+ * quietly breaks, producing a file that plays only the first segment in some players.
+ *
+ * @param {object} opts
+ * @param {string} opts.input master MP4
+ * @param {string} opts.out
+ * @param {{start:number,end:number,speed:number,captionPng?:string}[]} opts.segments
+ * @param {{w:number,h:number}} opts.size target frame
+ * @param {number} [opts.focusX] 0-1, where the crop sits when narrowing the frame
+ */
+export function cutEdit({
+  input, out, segments, size, focusX = 0.5, fps = 30, crf = 19,
+  background = '#0b0e12', audio = null,
+}) {
+  const bg = background;
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+
+  const { filter, videoLabel, audioLabel, inputs } = buildEditGraph({
+    input, segments, size, focusX, fps, background: bg, audio,
+  });
+
+  run([
+    ...inputs,
+    '-filter_complex', filter,
+    '-map', videoLabel,
+    ...(audioLabel ? ['-map', audioLabel, '-c:a', 'aac', '-b:a', '160k'] : []),
+    '-c:v', 'libx264', '-preset', 'slow', '-crf', String(crf),
+    '-pix_fmt', 'yuv420p', '-movflags', '+faststart',
+    '-r', String(fps),
+    out,
+  ], 'cut edit');
+
+  return out;
+}
+
+/**
+ * Build the filtergraph for an edit, separately from running it.
+ *
+ * Split out so the graph can be asserted without a video file or an ffmpeg process. The
+ * failure this guards against is a mislabelled chain that still encodes — ffmpeg produces
+ * a perfectly valid file with a segment missing, and the only other way to notice is to
+ * compare the output duration against what the edit asked for, after the render.
+ *
+ * @returns {{ filter: string, videoLabel: string, audioLabel: string|null, inputs: string[] }}
+ */
+export function buildEditGraph({ input, segments, size, focusX = 0.5, fps = 30, background = '#0b0e12', audio = null }) {
+  const bg = background;
+  const inputs = ['-i', input];
+  const captionIdx = new Map();
+  let nextInput = 1;
+
+  for (const seg of segments) {
+    // An animated overlay is a numbered PNG sequence with alpha, fed in at the edit's
+    // frame rate. It takes precedence over the still: a segment declaring motion has
+    // already had its caption rendered as frames, and compositing both would double the
+    // type.
+    if (seg.motionSeq?.count > 0) {
+      inputs.push(
+        '-framerate', String(seg.motionSeq.fps),
+        '-i', path.join(seg.motionSeq.dir, 'm-%05d.png')
+      );
+      captionIdx.set(seg, nextInput++);
+      continue;
+    }
+    if (!seg.captionPng) continue;
+    // Looped rather than dropped in as a single frame: a still has no timeline, so it can
+    // neither fade nor be scheduled. Giving it the segment's duration turns the caption
+    // into a clip, which is what makes captionAt / captionForSec / captionFadeSec mean
+    // anything at all.
+    inputs.push('-loop', '1', '-framerate', String(fps), '-t', seg.outSec.toFixed(4), '-i', seg.captionPng);
+    captionIdx.set(seg, nextInput++);
+  }
+
+  const audioIdx = audio?.file ? nextInput++ : null;
+  if (audioIdx != null) {
+    // A short music bed under a longer cut ends in silence unless it repeats.
+    if (audio.loop) inputs.push('-stream_loop', '-1');
+    inputs.push('-i', audio.file);
+  }
+
+  const parts = [];
+  const labels = [];
+
+  segments.forEach((seg, i) => {
+    const v = `v${i}`;
+    const fx = Math.max(0, Math.min(1, seg.focusX ?? focusX));
+    const x = `(iw-ow)*${fx.toFixed(3)}`;
+    // Crop to the target ratio *before* scaling so the framing decision is made on the
+    // source pixels, then scale once.
+    const chain = [
+      `trim=start=${seg.start.toFixed(4)}:end=${seg.end.toFixed(4)}`,
+      'setpts=PTS-STARTPTS',
+      ...(seg.speed && seg.speed !== 1 ? [`setpts=PTS/${seg.speed}`] : []),
+      ...(seg.fit === "contain"
+        // Letterbox instead of cropping. A 1440x900 master narrowed to 9:16 keeps only 35%
+        // of its width, which frames a centred 3D stage well and slices the left column off
+        // a two-column form. Where the layout *is* the subject, showing all of it on a
+        // studio-coloured ground beats showing a third of it edge to edge.
+        ? [`scale=${size.w}:${size.h}:force_original_aspect_ratio=decrease:flags=lanczos`,
+           `pad=${size.w}:${size.h}:(ow-iw)/2:(oh-ih)/2:color=${bg}`]
+        : [`crop=min(iw\\,ih*${size.w}/${size.h}):min(ih\\,iw*${size.h}/${size.w}):${x}:(ih-oh)/2`,
+           `scale=${size.w}:${size.h}:flags=lanczos`]),
+      'setsar=1',
+      `fps=${fps}`,
+    ].join(',');
+    parts.push(`[0:v]${chain}[${v}]`);
+
+    if (captionIdx.has(seg) && seg.motionSeq?.count > 0) {
+      // The sequence carries its own fades and timing, so it is scaled and composited as
+      // it is — gating or fading it here would fight the animation that was rendered.
+      const ci = captionIdx.get(seg);
+      const at = Math.max(0, seg.captionAt ?? 0);
+      parts.push(`[${ci}:v]scale=${size.w}:${size.h},setsar=1,format=rgba[c${i}]`);
+      const shift = at > 0 ? `:enable='gte(t,${at.toFixed(3)})'` : '';
+      parts.push(`[${v}][c${i}]overlay=0:0:format=auto:eof_action=pass${shift}[o${i}]`);
+      labels.push(`[o${i}]`);
+    } else if (captionIdx.has(seg)) {
+      const ci = captionIdx.get(seg);
+      const at = Math.max(0, seg.captionAt ?? 0);
+      const until = seg.captionForSec != null
+        ? Math.min(at + seg.captionForSec, seg.outSec)
+        : seg.outSec;
+      const fade = Math.min(seg.captionFadeSec ?? 0, (until - at) / 2);
+
+      const capChain = [`scale=${size.w}:${size.h}`, 'setsar=1'];
+      if (fade > 0) {
+        // Alpha fades, not colour fades: a caption on a transparent plate faded to black
+        // becomes a black rectangle over the shot.
+        capChain.push('format=rgba');
+        capChain.push(`fade=t=in:st=${at.toFixed(3)}:d=${fade.toFixed(3)}:alpha=1`);
+        capChain.push(`fade=t=out:st=${(until - fade).toFixed(3)}:d=${fade.toFixed(3)}:alpha=1`);
+      }
+      parts.push(`[${ci}:v]${capChain.join(',')}[c${i}]`);
+
+      // `enable` gates the overlay; the fades soften its edges. Both are needed — enable
+      // alone pops, fade alone leaves the plate composited (and costing quality) for the
+      // whole segment even at zero alpha.
+      const windowed = at > 0 || seg.captionForSec != null;
+      const enable = windowed ? `:enable='between(t,${at.toFixed(3)},${until.toFixed(3)})'` : '';
+      parts.push(`[${v}][c${i}]overlay=0:0:format=auto${enable}[o${i}]`);
+      labels.push(`[o${i}]`);
+    } else {
+      labels.push(`[${v}]`);
+    }
+  });
+
+  // Fold the segments together left to right rather than concatenating in one go, because
+  // a transition is pairwise: xfade takes exactly two streams and overlaps them. Folding
+  // lets cuts and transitions mix freely in one edit — concat where the edit says cut,
+  // xfade where it names a transition — which a single concat node cannot express.
+  let cursor = labels[0];
+  let accSec = segments[0]?.outSec ?? 0;
+
+  for (let i = 1; i < segments.length; i++) {
+    const seg = segments[i];
+    const tr = seg.transition ?? { type: 'cut', durationSec: 0 };
+    const next = `x${i}`;
+
+    if (tr.type !== 'cut' && tr.durationSec > 0) {
+      // offset is measured on the *first* input's timeline, so it is where the outgoing
+      // stream should start dissolving: its full length so far, less the overlap.
+      const offset = Math.max(0, accSec - tr.durationSec);
+      parts.push(
+        `${cursor}${labels[i]}xfade=transition=${TRANSITIONS[tr.type] || tr.type}`
+        + `:duration=${tr.durationSec.toFixed(3)}:offset=${offset.toFixed(4)}[${next}]`
+      );
+      accSec = accSec + seg.outSec - tr.durationSec;
+    } else {
+      parts.push(`${cursor}${labels[i]}concat=n=2:v=1:a=0[${next}]`);
+      accSec += seg.outSec;
+    }
+    cursor = `[${next}]`;
+  }
+
+  parts.push(`${cursor}null[outv]`);
+
+  let audioLabel = null;
+  if (audioIdx != null) {
+    const total = accSec;
+    const gain = audio.gainDb ?? -18;
+    const fadeIn = audio.fadeInSec ?? 0.5;
+    const fadeOut = Math.min(audio.fadeOutSec ?? 1, total);
+    const chain = [
+      `atrim=start=0:end=${total.toFixed(4)}`,
+      'asetpts=PTS-STARTPTS',
+      // Default well under the voice of the piece. A bed that competes with the subject is
+      // the most common way a good demo is made unwatchable.
+      `volume=${gain}dB`,
+      ...(fadeIn > 0 ? [`afade=t=in:st=0:d=${fadeIn.toFixed(3)}`] : []),
+      ...(fadeOut > 0 ? [`afade=t=out:st=${Math.max(0, total - fadeOut).toFixed(3)}:d=${fadeOut.toFixed(3)}`] : []),
+      // Guarantees a full-length track even when the bed is short and not set to loop,
+      // so the muxer never truncates the video to the audio.
+      `apad=whole_dur=${total.toFixed(4)}`,
+    ];
+    parts.push(`[${audioIdx}:a]${chain.join(',')}[outa]`);
+    audioLabel = '[outa]';
+  }
+
+  return { filter: parts.join(';'), videoLabel: '[outv]', audioLabel, inputs };
+}
+
+
+export function probeDuration(file) {
+  const bin = ffmpegBin();
+  const res = spawnSync(bin, ['-hide_banner', '-i', file], { encoding: 'utf8' });
+  const m = (res.stderr || '').match(/Duration:\s*(\d+):(\d+):([\d.]+)/);
+  if (!m) return null;
+  return Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]);
+}

package/src/caption.mjs

@@ -0,0 +1,115 @@
+/**
+ * Caption rendering, in the browser.
+ *
+ * The obvious route is ffmpeg's `drawtext`. It is not available: the bundled
+ * `ffmpeg-static` build reports `--enable-libfreetype` but ships no `drawtext` filter, so
+ * the only text path is libass — which renders in whatever face fontconfig happens to find
+ * on the machine. A caption that is Helvetica on one laptop and DejaVu in CI is not a
+ * caption, it is a defect that only shows up in the deliverable.
+ *
+ * So captions are rendered by Chromium, which the recorder already launches, using the
+ * studio's own `tokens.css`. That buys the real typeface, real kerning, and text that
+ * matches the pages being recorded — with no font vendored into the repo and no new
+ * dependency. Each caption becomes a transparent PNG that ffmpeg overlays.
+ */
+import fs from 'fs';
+import path from 'path';
+
+/** Safe-area insets as a fraction of the frame, per aspect. Vertical needs more bottom
+ *  room because feed UI sits there. */
+const INSET = {
+  '16:9': { bottom: 0.09, side: 0.06, maxWidth: 0.62 },
+  '9:16': { bottom: 0.16, side: 0.08, maxWidth: 0.86 },
+  '1:1': { bottom: 0.11, side: 0.07, maxWidth: 0.8 },
+};
+
+function captionHtml({ text, kicker, width, height, aspect, tokensCss }) {
+  const inset = INSET[aspect] || INSET['16:9'];
+  // Scale type to the frame rather than fixing px, so one caption spec reads correctly at
+  // 1920x1080 and at 1080x1920.
+  const base = Math.round(height * (aspect === '9:16' ? 0.030 : 0.038));
+
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+${tokensCss}
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:${width}px;height:${height}px;background:transparent;overflow:hidden}
+.wrap{
+  position:absolute;
+  left:${Math.round(width * inset.side)}px;
+  bottom:${Math.round(height * inset.bottom)}px;
+  max-width:${Math.round(width * inset.maxWidth)}px;
+}
+.kicker{
+  font-family:var(--font-mono,ui-monospace,Menlo,monospace);
+  font-size:${Math.round(base * 0.42)}px;
+  letter-spacing:.22em;
+  text-transform:uppercase;
+  color:var(--brand-accent,#c9852f);
+  margin-bottom:${Math.round(base * 0.42)}px;
+  /* A shadow rather than a plate: the caption must not hide the product behind it. */
+  text-shadow:0 2px 12px rgba(0,0,0,.85), 0 1px 3px rgba(0,0,0,.95);
+}
+.text{
+  font-family:var(--font-display,Georgia,serif);
+  font-weight:400;
+  font-size:${base}px;
+  line-height:1.15;
+  color:#fff;
+  text-shadow:0 3px 18px rgba(0,0,0,.9), 0 1px 4px rgba(0,0,0,.95);
+  text-wrap:balance;
+}
+</style></head><body>
+<div class="wrap">
+  ${kicker ? `<div class="kicker">${escapeHtml(kicker)}</div>` : ''}
+  <div class="text">${escapeHtml(text)}</div>
+</div>
+</body></html>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+/**
+ * Render each caption to a transparent PNG.
+ *
+ * One browser for the whole set — launching per caption costs more than the rendering.
+ *
+ * @param {{text:string,kicker?:string,key:string}[]} captions
+ * @param {object} opts
+ * @returns {Promise<Map<string,string>>} caption key to PNG path
+ */
+export async function renderCaptions(captions, { chromium, launch, dir, width, height, aspect, root }) {
+  const out = new Map();
+  if (!captions.length) return out;
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Inline the studio tokens so the caption carries the same palette and typefaces as the
+  // pages it sits over.
+  let tokensCss = '';
+  const tokensPath = path.join(root, 'assets', 'lib', 'tokens.css');
+  if (fs.existsSync(tokensPath)) tokensCss = fs.readFileSync(tokensPath, 'utf8');
+
+  const browser = await launch(chromium);
+  try {
+    const page = await browser.newPage({ viewport: { width, height } });
+    for (const cap of captions) {
+      const file = path.join(dir, `${cap.key}.png`);
+      await page.setContent(
+        captionHtml({ text: cap.text, kicker: cap.kicker, width, height, aspect, tokensCss }),
+        { waitUntil: 'load' }
+      );
+      await page.evaluate(() => document.fonts?.ready).catch(() => {});
+      // omitBackground is what makes the PNG transparent, so the overlay carries only the
+      // text rather than a black rectangle over the footage.
+      await page.screenshot({ path: file, omitBackground: true });
+      out.set(cap.key, file);
+    }
+  } finally {
+    await browser.close().catch(() => {});
+  }
+  return out;
+}

package/src/capture.mjs

@@ -0,0 +1,143 @@
+/**
+ * Frame capture over the DevTools screencast.
+ *
+ * Why not `page.screenshot()` in a loop: a screenshot round-trip costs 50-100ms, which
+ * caps you near 12fps and stutters. Why not Playwright's built-in `recordVideo`: it is
+ * WebM only, gives no control over quality, and its timing is opaque when you want to
+ * re-cut the result.
+ *
+ * `Page.startScreencast` pushes a frame whenever the compositor paints one, each carrying
+ * a real timestamp. That is the important part: frames arrive *irregularly* — a heavy
+ * Three.js scene under SwiftShader may deliver 8fps for a second and 40fps the next — so
+ * the recording keeps every frame's true timestamp and lets ffmpeg resample to a constant
+ * rate at assembly. Treating irregular frames as if they were evenly spaced is what makes
+ * naive screen captures of WebGL look like they are speeding up and slowing down.
+ *
+ * The compositor output includes WebGL and canvas, so 3D content is captured as painted
+ * rather than needing any per-canvas hook.
+ *
+ * A frame that takes 900ms to paint still occupies 900ms of the timeline here. Removing
+ * that dependency on machine speed is the deterministic-clock work, not this.
+ */
+import fs from 'fs';
+import path from 'path';
+
+export class ScreencastRecorder {
+  /**
+   * @param {import('playwright-core').Page} page
+   * @param {{ dir: string, quality?: number, maxWidth?: number, maxHeight?: number }} opts
+   */
+  constructor(page, opts) {
+    this.page = page;
+    this.dir = opts.dir;
+    this.quality = opts.quality ?? 80;
+    this.maxWidth = opts.maxWidth;
+    this.maxHeight = opts.maxHeight;
+    this.frames = [];
+    this.session = null;
+    this.running = false;
+    this.dropped = 0;
+  }
+
+  async start() {
+    fs.mkdirSync(this.dir, { recursive: true });
+    this.session = await this.page.context().newCDPSession(this.page);
+
+    this.session.on('Page.screencastFrame', async (frame) => {
+      // Acknowledge first and always: Chromium sends no further frames until the current
+      // one is acked, so a throw between here and the ack silently ends the recording.
+      const ack = this.session
+        .send('Page.screencastFrameAck', { sessionId: frame.sessionId })
+        .catch(() => {});
+
+      if (this.running) {
+        const index = this.frames.length;
+        const file = path.join(this.dir, `f${String(index).padStart(6, '0')}.jpg`);
+        try {
+          fs.writeFileSync(file, Buffer.from(frame.data, 'base64'));
+          this.frames.push({ file, t: frame.metadata.timestamp });
+        } catch {
+          this.dropped++;
+        }
+      }
+      await ack;
+    });
+
+    this.running = true;
+    await this.session.send('Page.startScreencast', {
+      format: 'jpeg',
+      quality: this.quality,
+      everyNthFrame: 1,
+      ...(this.maxWidth ? { maxWidth: this.maxWidth } : {}),
+      ...(this.maxHeight ? { maxHeight: this.maxHeight } : {}),
+    });
+  }
+
+  async stop() {
+    this.running = false;
+    if (!this.session) return this.summary();
+    await this.session.send('Page.stopScreencast').catch(() => {});
+    await this.session.detach().catch(() => {});
+    this.session = null;
+    return this.summary();
+  }
+
+  summary() {
+    const times = this.frames.map((f) => f.t).filter((t) => typeof t === 'number');
+    const duration = times.length > 1 ? times[times.length - 1] - times[0] : 0;
+
+    // Average frame rate over the whole take is not the number that matters, and reading
+    // it as if it were understates the capture badly: a deliberate two-second hold on a
+    // static page paints nothing, contributes no frames, and drags the mean down. What
+    // decides whether motion looks smooth is the rate *while something is moving*, so
+    // gaps longer than a fifth of a second are treated as held frames and excluded.
+    const gaps = [];
+    for (let i = 1; i < times.length; i++) gaps.push(times[i] - times[i - 1]);
+    const moving = gaps.filter((g) => g < 0.2);
+    const movingTime = moving.reduce((a, b) => a + b, 0);
+
+    return {
+      count: this.frames.length,
+      dropped: this.dropped,
+      durationSec: duration,
+      fps: duration > 0 ? this.frames.length / duration : 0,
+      motionFps: movingTime > 0 ? moving.length / movingTime : 0,
+      heldFrames: gaps.length - moving.length,
+    };
+  }
+
+  /**
+   * ffmpeg concat manifest carrying each frame's real on-screen duration. Assembly
+   * resamples this to a constant rate, which is what turns irregular capture into
+   * even playback.
+   */
+  writeManifest(file) {
+    return writeManifest(this.frames, file);
+  }
+}
+
+/**
+ * ffmpeg concat manifest carrying each frame's on-screen duration.
+ *
+ * Shared by both capture modes on purpose. Under realtime capture the durations vary,
+ * because the compositor paints when it can, and the encode resamples them to a constant
+ * rate. Under deterministic capture they are all identical and the resample is a no-op —
+ * which is the entire point of that mode.
+ *
+ * @param {{ file: string, t: number }[]} frames
+ * @param {string} file manifest path
+ */
+export function writeManifest(frames, file) {
+  if (!frames || frames.length < 2) throw new Error('nothing captured — no frames to assemble');
+  const lines = [];
+  for (let i = 0; i < frames.length; i++) {
+    const next = frames[i + 1];
+    lines.push(`file '${path.basename(frames[i].file)}'`);
+    const dur = next ? Math.max(0.001, next.t - frames[i].t) : 0.04;
+    lines.push(`duration ${dur.toFixed(6)}`);
+  }
+  // The concat demuxer ignores the final duration unless the last file is repeated.
+  lines.push(`file '${path.basename(frames[frames.length - 1].file)}'`);
+  fs.writeFileSync(file, lines.join('\n'));
+  return file;
+}