@mrkt_frwd/reel 0.1.0

package/src/critic.mjs

@@ -0,0 +1,271 @@
+/**
+ * Frame critic — judge a recording from what it actually shows.
+ *
+ * The plan for this phase said "point design-eval's still-image rubric at the sampled
+ * frames". Reading that rubric closely, most of it does not transfer: its axes are
+ * `subjectFirst`, `framing`, `geometryCredibility` and `materials`, which are
+ * product-photography measures. A frame of someone filling in a form has no subject on a
+ * background and no material response, so those axes would score noise and the noise
+ * would carry a calibrated-looking number. What does transfer is the *shape* of that
+ * rubric — measured axes, blockers separated from warnings, a skip status that
+ * renormalises rather than scoring a default — and `imageStats`, whose raw luminance and
+ * occupancy measures are subject-agnostic.
+ *
+ * So the axes here are about what a recording can get wrong, and every one is measured
+ * from frames rather than asserted about the script:
+ *
+ *   deadFrames      a shot rendered nothing — blank, or a uniform wash
+ *   frozenMotion    consecutive frames identical while the shot claims movement. This is
+ *                   the one that catches a WebGL scene that never animated, which is
+ *                   exactly the failure a screenshot review cannot see.
+ *   continuity      a jump inside a shot, where the picture changes so much between two
+ *                   frames that the eye reads a cut rather than a move
+ *   pacing          a shot too short for anyone to read what it shows
+ *   ending          the clip lands mid-motion instead of on a held final state
+ *
+ * No model call. Everything here runs from pixels and the capture timeline, so it works
+ * in an environment with no egress and gives the same answer twice.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { frameGrids, gridDelta, gridSpread } from './frame-grid.mjs';
+
+/** Below this luminance spread a frame carries no legible content. */
+const DEAD_STD_LUM = 3.0;
+/** Mean absolute difference under this reads as an identical frame. */
+const FROZEN_DELTA = 0.6;
+/** Above this, consecutive frames *might* read as a cut rather than a move. */
+const JUMP_DELTA = 34;
+/** ...but only if the change also stands this many times clear of its neighbours. */
+const JUMP_ISOLATION = 3.5;
+/** Changes this close to either end of a shot belong to the cut, not to the shot. */
+const BOUNDARY_SEC = 0.4;
+/** A shot shorter than this cannot be read, whatever it contains. */
+const MIN_SHOT_SEC = 1.2;
+/** The tail that should be settled so a loop ends well. */
+const ENDING_WINDOW_SEC = 0.6;
+
+const clamp = (n, lo = 0, hi = 100) => Math.max(lo, Math.min(hi, n));
+const axis = (score, status, notes, evidence = {}) => ({
+  score: Math.round(clamp(score)),
+  status,
+  notes,
+  evidence,
+});
+
+/**
+ * @param {object} opts
+ * @param {string[]} opts.frames analysis frames, in order
+ * @param {number} opts.fps rate the analysis frames were extracted at
+ * @param {{id:string,intent:string,startSec:number,endSec:number}[]} opts.timeline
+ * @param {number} opts.durationSec
+ */
+export function critique({ frames, fps, timeline = [], durationSec }) {
+  const axes = {};
+  const blockers = [];
+  const findings = [];
+
+  if (!frames || frames.length < 2) {
+    return {
+      axes: { deadFrames: axis(0, 'fail', 'No frames to judge') },
+      blockers: ['NO_FRAMES'],
+      findings: [],
+      score: 0,
+      pass: false,
+    };
+  }
+
+  const { ok, grids, error } = frameGrids(frames);
+
+  // Without a pixel backend every measure below is null and the axes would fall back to
+  // constants — a score that measured nothing. Refuse rather than reassure.
+  if (!ok || grids.some((g) => !g)) {
+    return {
+      axes: {},
+      blockers: ['MEASUREMENT_UNAVAILABLE'],
+      findings: [{
+        kind: 'measurement',
+        detail: error || 'One or more frames could not be read',
+      }],
+      score: null,
+      pass: false,
+    };
+  }
+
+  const stats = frames.map((file, i) => ({
+    file, i, t: i / fps, grid: grids[i], spread: gridSpread(grids[i]),
+  }));
+
+  const shotAt = (t) => timeline.find((s) => t >= s.startSec && t < s.endSec) || null;
+
+  // ── dead frames ────────────────────────────────────────────────────────────
+  const dead = stats.filter((f) => (f.spread ?? 0) < DEAD_STD_LUM);
+  for (const f of dead) {
+    findings.push({
+      kind: 'dead-frame',
+      atSec: Number(f.t.toFixed(2)),
+      shot: shotAt(f.t)?.id ?? null,
+      detail: `frame carries almost no contrast (spread ${(f.spread ?? 0).toFixed(1)}) — nothing is legible here`,
+    });
+  }
+  axes.deadFrames = dead.length
+    ? axis(100 - (dead.length / stats.length) * 300, 'fail', `${dead.length} blank or near-blank frame(s)`, { count: dead.length })
+    : axis(100, 'pass', 'every frame carries content');
+  if (dead.length / stats.length > 0.1) blockers.push('DEAD_FRAMES');
+
+  // ── frozen motion ──────────────────────────────────────────────────────────
+  // Judged per shot, and only against shots that claim movement. A `hold` is supposed to
+  // be still, so flagging stillness everywhere would bury the one case that matters.
+  const deltas = [];
+  for (let i = 1; i < stats.length; i++) {
+    deltas.push({ t: stats[i].t, d: gridDelta(stats[i - 1].grid, stats[i].grid), shot: shotAt(stats[i].t) });
+  }
+
+  const movingShots = new Map();
+  for (const d of deltas) {
+    if (!d.shot) continue;
+    const entry = movingShots.get(d.shot.id) || { shot: d.shot, deltas: [] };
+    entry.deltas.push(d.d ?? 0);
+    movingShots.set(d.shot.id, entry);
+  }
+
+  let frozen = 0;
+  for (const { shot, deltas: ds } of movingShots.values()) {
+    const moved = ds.filter((d) => d > FROZEN_DELTA).length;
+    const share = ds.length ? moved / ds.length : 0;
+    // A shot whose frames never change at all, for more than a second, is not a beat —
+    // it is something that failed to render or failed to animate.
+    if (share < 0.05 && shot.endSec - shot.startSec > 1.5) {
+      frozen++;
+      findings.push({
+        kind: 'frozen-shot',
+        atSec: Number(shot.startSec.toFixed(2)),
+        shot: shot.id,
+        detail: `nothing moves for ${(shot.endSec - shot.startSec).toFixed(1)}s — intent was "${shot.intent}"`,
+      });
+    }
+  }
+  axes.frozenMotion = frozen
+    ? axis(100 - frozen * 45, 'fail', `${frozen} shot(s) render a still picture`, { count: frozen })
+    : axis(100, 'pass', 'every shot shows movement');
+  if (frozen) blockers.push('FROZEN_SHOT');
+
+  // ── continuity ─────────────────────────────────────────────────────────────
+  // A jump at a shot boundary is a cut and is intended; a jump inside one is not.
+  //
+  // Absolute change is the wrong test on its own, and the first version of this got it
+  // wrong: scrolling the landing page across the boundary between its dark hero and the
+  // cream section below produces enormous frame-to-frame deltas, and every one was
+  // reported as a cut. That is a fast scroll doing exactly what it was asked to do.
+  //
+  // What distinguishes a discontinuity is that it is *isolated*: one large change sitting
+  // among small ones. Sustained motion makes its neighbours large too. So a delta is only
+  // a jump if it also stands well clear of the local median around it.
+  const localMedian = (i, radius = 3) => {
+    const near = [];
+    for (let j = Math.max(0, i - radius); j <= Math.min(deltas.length - 1, i + radius); j++) {
+      if (j !== i && deltas[j].d != null) near.push(deltas[j].d);
+    }
+    if (!near.length) return null;
+    near.sort((a, b) => a - b);
+    return near[Math.floor(near.length / 2)];
+  };
+
+  const jumps = deltas.filter((d, i) => {
+    if (d.d == null || d.d < JUMP_DELTA) return false;
+    if (!d.shot) return false;
+    // Both ends of a shot are legitimate cuts. Guarding only the start still reported the
+    // navigation into the next shot, because the analysis strip is coarser than the
+    // boundary and one delta straddles it — the change belongs to the goto, not to the
+    // shot it happens to be filed under.
+    if (d.t - d.shot.startSec <= BOUNDARY_SEC) return false;
+    if (d.shot.endSec - d.t <= BOUNDARY_SEC) return false;
+    const med = localMedian(i);
+    // No neighbours to compare against — do not guess.
+    if (med == null) return false;
+    return d.d > Math.max(JUMP_DELTA, med * JUMP_ISOLATION);
+  });
+  for (const j of jumps) {
+    findings.push({
+      kind: 'jump-cut',
+      atSec: Number(j.t.toFixed(2)),
+      shot: j.shot.id,
+      detail: `picture changes abruptly mid-shot (delta ${j.d.toFixed(0)}) — reads as a cut, not a move`,
+    });
+  }
+  axes.continuity = jumps.length
+    ? axis(100 - jumps.length * 12, 'warn', `${jumps.length} abrupt change(s) inside a shot`, { count: jumps.length })
+    : axis(100, 'pass', 'motion is continuous within every shot');
+
+  // ── pacing ─────────────────────────────────────────────────────────────────
+  const rushed = timeline.filter((s) => s.endSec - s.startSec < MIN_SHOT_SEC);
+  for (const s of rushed) {
+    findings.push({
+      kind: 'rushed-shot',
+      atSec: Number(s.startSec.toFixed(2)),
+      shot: s.id,
+      detail: `${(s.endSec - s.startSec).toFixed(2)}s is too short to read — under the ${MIN_SHOT_SEC}s floor`,
+    });
+  }
+  axes.pacing = timeline.length
+    ? (rushed.length
+        ? axis(100 - (rushed.length / timeline.length) * 100, 'warn', `${rushed.length} shot(s) too short to read`, { count: rushed.length })
+        : axis(100, 'pass', 'every shot holds long enough to read'))
+    : axis(50, 'skip', 'no timeline supplied');
+
+  // ── ending ─────────────────────────────────────────────────────────────────
+  // The craft rule in the recorder skill: land on a strong final state so a loop ends
+  // well. Measured as stillness across the tail.
+  const tail = deltas.filter((d) => d.t > (durationSec ?? stats[stats.length - 1].t) - ENDING_WINDOW_SEC);
+  const tailMoving = tail.filter((d) => (d.d ?? 0) > JUMP_DELTA / 3).length;
+  if (tail.length && tailMoving / tail.length > 0.5) {
+    findings.push({
+      kind: 'unsettled-ending',
+      atSec: Number((durationSec ?? 0).toFixed(2)),
+      shot: timeline[timeline.length - 1]?.id ?? null,
+      detail: 'the clip ends mid-motion — a loop will cut on a moving frame',
+    });
+  }
+  axes.ending = tail.length
+    ? (tailMoving / tail.length > 0.5
+        ? axis(45, 'warn', 'ends mid-motion rather than on a held state')
+        : axis(100, 'pass', 'settles before the end'))
+    : axis(50, 'skip', 'clip too short to judge its ending');
+
+  const score = weighted(axes);
+  return {
+    axes,
+    blockers,
+    findings: findings.sort((a, b) => a.atSec - b.atSec),
+    score,
+    pass: blockers.length === 0 && score != null && score >= 70,
+  };
+}
+
+export const CRITIC_WEIGHTS = {
+  deadFrames: 0.3,
+  frozenMotion: 0.3,
+  continuity: 0.15,
+  pacing: 0.15,
+  ending: 0.1,
+};
+
+/** Skipped axes renormalise rather than scoring a default — the design-eval convention. */
+function weighted(axes) {
+  let sum = 0;
+  let wsum = 0;
+  for (const [k, w] of Object.entries(CRITIC_WEIGHTS)) {
+    if (axes[k] && axes[k].status !== 'skip') {
+      sum += axes[k].score * w;
+      wsum += w;
+    }
+  }
+  return wsum ? Math.round(sum / wsum) : null;
+}
+
+export function writeCritique(dir, result, meta = {}) {
+  const file = path.join(dir, 'critique.json');
+  fs.writeFileSync(file, JSON.stringify({ ...meta, ...result }, null, 2));
+  return file;
+}

package/src/cursor.mjs

@@ -0,0 +1,118 @@
+/**
+ * Synthetic cursor overlay.
+ *
+ * Playwright's mouse is real as far as the page is concerned, but the OS pointer is not
+ * part of what the compositor paints — so a screencast of a click shows the effect and
+ * never the cause. For a SaaS-style walkthrough that is fatal: the viewer sees fields
+ * filling themselves. This draws a pointer that the recording can see, plus a ripple on
+ * click so the moment of interaction reads at speed.
+ *
+ * Installed with `addInitScript`, so it survives every navigation in a multi-page story
+ * without the script needing to re-inject it per page.
+ *
+ * The overlay is `pointer-events:none` and sits above everything, so it cannot alter what
+ * it is documenting. It is also marked `data-recording-chrome`, which the frame critic
+ * uses to tell studio UI apart from recorder furniture.
+ */
+
+export const CURSOR_INIT = `(() => {
+  if (window.__rec) return;
+  const SIZE = 22;
+  let el = null, ripple = null;
+
+  function ensure() {
+    if (el && document.body.contains(el)) return;
+    el = document.createElement('div');
+    el.setAttribute('data-recording-chrome', 'cursor');
+    el.style.cssText = [
+      'position:fixed','left:0','top:0','width:' + SIZE + 'px','height:' + SIZE + 'px',
+      'pointer-events:none','z-index:2147483647','will-change:transform',
+      'transform:translate3d(-100px,-100px,0)','opacity:0','transition:opacity .18s ease',
+    ].join(';');
+    el.innerHTML =
+      '<svg width="' + SIZE + '" height="' + SIZE + '" viewBox="0 0 22 22" fill="none">' +
+      '<path d="M4 2.5 L4 17 L8 13.4 L10.6 19 L13.4 17.7 L10.8 12.3 L16 12 Z" ' +
+      'fill="#ffffff" stroke="rgba(0,0,0,.55)" stroke-width="1.1" stroke-linejoin="round"/></svg>';
+
+    ripple = document.createElement('div');
+    ripple.setAttribute('data-recording-chrome', 'ripple');
+    ripple.style.cssText = [
+      'position:fixed','left:0','top:0','width:34px','height:34px','margin:-17px 0 0 -17px',
+      'border-radius:50%','pointer-events:none','z-index:2147483646','opacity:0',
+      'border:2px solid rgba(255,255,255,.85)','will-change:transform,opacity',
+    ].join(';');
+
+    document.body.appendChild(el);
+    document.body.appendChild(ripple);
+  }
+
+  window.__rec = {
+    /** Place the pointer. Called once per animation step, so no CSS transition on transform. */
+    cursor(x, y) {
+      ensure();
+      el.style.opacity = '1';
+      el.style.transform = 'translate3d(' + x + 'px,' + y + 'px,0)';
+      window.__rec._x = x; window.__rec._y = y;
+    },
+    hide() { if (el) el.style.opacity = '0'; },
+    /** A one-shot ring at the current point. Deliberately short — it must not trail. */
+    ripple(x, y) {
+      ensure();
+      const px = x == null ? window.__rec._x : x;
+      const py = y == null ? window.__rec._y : y;
+      ripple.style.transition = 'none';
+      ripple.style.transform = 'translate3d(' + px + 'px,' + py + 'px,0) scale(.35)';
+      ripple.style.opacity = '.9';
+      requestAnimationFrame(() => {
+        ripple.style.transition = 'transform .42s cubic-bezier(.2,.7,.3,1), opacity .42s ease';
+        ripple.style.transform = 'translate3d(' + px + 'px,' + py + 'px,0) scale(1.25)';
+        ripple.style.opacity = '0';
+      });
+    },
+    _x: 0, _y: 0,
+  };
+
+  // The drawn cursor follows the real pointer by listening, rather than being positioned
+  // by the driver on every step. Each driver-side call is an IPC round trip, and doing
+  // one per animation frame was costing more time than the frame itself — it held capture
+  // to about 20fps during motion. Listening keeps the two in sync by construction.
+  addEventListener('pointermove', (e) => {
+    if (e.isTrusted === false && !e.__rec) return;
+    window.__rec.cursor(e.clientX, e.clientY);
+  }, { capture: true, passive: true });
+
+  /** Eased scroll driven entirely in-page, so the driver waits instead of stepping. */
+  window.__rec.scrollTo = (target, ms) => new Promise((resolve) => {
+    const from = window.scrollY;
+    const delta = target - from;
+    if (!ms || Math.abs(delta) < 1) { window.scrollTo(0, target); return resolve(); }
+    const t0 = performance.now();
+    const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+    (function step(now) {
+      const t = Math.min(1, (now - t0) / ms);
+      window.scrollTo(0, from + delta * ease(t));
+      if (t < 1) requestAnimationFrame(step);
+      else resolve();
+    })(t0);
+  });
+
+  if (document.body) ensure();
+  else document.addEventListener('DOMContentLoaded', ensure, { once: true });
+})();`;
+
+/**
+ * Hides native carets and scrollbars, which read as artefacts in a finished clip, and
+ * neutralises smooth-scroll so the recorder owns scroll timing rather than the page.
+ */
+export const POLISH_INIT = `(() => {
+  const style = document.createElement('style');
+  style.setAttribute('data-recording-chrome', 'polish');
+  style.textContent = [
+    'html{scroll-behavior:auto !important}',
+    '::-webkit-scrollbar{width:0 !important;height:0 !important}',
+    'html{scrollbar-width:none !important}',
+  ].join('');
+  const add = () => document.documentElement.appendChild(style);
+  if (document.documentElement) add();
+  else document.addEventListener('DOMContentLoaded', add, { once: true });
+})();`;

package/src/edit-cli.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Edit CLI — cut a short piece from a recorded master.
+ *
+ *   npm run record:edit -- recordings/studio-tour/social.edit.json
+ *   npm run record:edit -- <edit.json> --check      # resolve and report, encode nothing
+ *
+ * The master is the source of truth. A social cut is a reading of it, not a second
+ * recording, so the two cannot drift apart.
+ */
+import fs from 'fs';
+import path from 'path';
+import { chromium } from 'playwright-core';
+
+import { launch } from './runner.mjs';
+import { validateEdit, resolve, budgetReport, loadCapture, ASPECTS } from './edit.mjs';
+import { renderCaptions } from './caption.mjs';
+import { renderMotionSequence } from './motion.mjs';
+import { cutEdit, probeDuration } from './assemble.mjs';
+
+const argv = process.argv.slice(2);
+const has = (name) => argv.includes(`--${name}`);
+const editPath = argv.find((a) => !a.startsWith('--') && a.endsWith('.json'));
+
+if (!editPath || !fs.existsSync(editPath)) {
+  console.error('usage: npm run record:edit -- <path/to/edit.json> [--check]');
+  process.exit(2);
+}
+
+const root = process.cwd();
+const edit = JSON.parse(fs.readFileSync(editPath, 'utf8'));
+
+console.log(`\n  EDIT  ${edit.name}\n  ────────────────────────────────────`);
+
+const errors = validateEdit(edit);
+if (errors.length) {
+  console.error(`\n  ✗ ${errors.length} problem(s) in ${editPath}\n`);
+  for (const e of errors) console.error(`      ${e}`);
+  console.error('');
+  process.exit(1);
+}
+
+let capture;
+try {
+  capture = loadCapture(root, edit.source);
+} catch (e) {
+  console.error(`\n  ✗ ${e.message}\n`);
+  process.exit(1);
+}
+
+const { segments, problems, totalSec, overlapSec, sourceDurationSec } = resolve(edit, capture);
+if (problems.length) {
+  console.error(`\n  ✗ ${problems.length} segment(s) do not resolve against ${edit.source}\n`);
+  for (const p of problems) console.error(`      ${p}`);
+  console.error('');
+  process.exit(1);
+}
+
+console.log(`  ✓ ${segments.length} segment(s) resolve against ${edit.source} (${sourceDurationSec.toFixed(1)}s master)`);
+for (const s of segments) {
+  const speed = s.speed !== 1 ? ` @${s.speed}x` : '';
+  const cap = s.caption ? `  "${s.caption.slice(0, 42)}${s.caption.length > 42 ? '…' : ''}"` : '';
+  // The transition sits on its own line between the two shots it joins, which is where it
+  // happens. Inline, it read as a property of the segment and pushed the columns out of
+  // alignment for every other row.
+  if (s.transition && s.transition.type !== 'cut') {
+    console.log(`         ⌄ ${s.transition.type} ${s.transition.durationSec}s`);
+  }
+  console.log(`      ${(s.shot || 'abs').padEnd(9)} ${s.start.toFixed(2)}-${s.end.toFixed(2)}s → ${s.outSec.toFixed(2)}s${speed}${cap}`);
+}
+console.log(
+  `  ✓ ${totalSec.toFixed(1)}s total`
+  + (overlapSec > 0 ? ` (${overlapSec.toFixed(1)}s absorbed by transitions)` : '')
+);
+
+// Narrowing a landscape master to a vertical frame is lossy in a way that no focusX can
+// rescue, and the loss is invisible until the render is watched. Report it in the units
+// that matter — how much of the frame survives — and name the alternative, which is to
+// record the story at that viewport instead. These pages are responsive; a vertical take
+// reflows and keeps the whole design in frame.
+const shot = ASPECTS[edit.aspect || '16:9'];
+const src = capture.viewport;
+if (src?.width && shot) {
+  const srcRatio = src.width / src.height;
+  const outRatio = shot.w / shot.h;
+  if (outRatio < srcRatio - 0.02 && segments.some((s) => s.fit !== 'contain')) {
+    const kept = ((src.height * outRatio) / src.width) * 100;
+    const level = kept < 60 ? '!' : '·';
+    console.log(
+      `  ${level} cropping ${src.width}x${src.height} to ${edit.aspect} keeps ${kept.toFixed(0)}% of the width`
+    );
+    if (kept < 60) {
+      console.log(`      a native take keeps all of it: npm run record -- recordings/${edit.source}/script.json --viewport ${shot.w}x${shot.h}`);
+      console.log(`      then point this edit at "source": "${edit.source}-vertical"`);
+    }
+  }
+}
+
+const budget = budgetReport(totalSec, edit.budgetSec);
+if (budget && !budget.ok) {
+  // Reported, not enforced. Silently retiming to hit a number changes the pacing the
+  // director chose, and pacing is the whole point of a short format.
+  console.warn(`  ! ${budget.totalSec.toFixed(1)}s is over the ${budget.budgetSec}s budget — ${budget.hint}`);
+}
+
+// An audio bed is named in the edit but lives on disk, so it is checked here rather than
+// in validation. Failing at the graph stage would mean discovering it after the captions
+// have been rendered in a browser.
+let audio = null;
+if (edit.audio?.file) {
+  const file = path.isAbsolute(edit.audio.file) ? edit.audio.file : path.join(root, edit.audio.file);
+  if (!fs.existsSync(file)) {
+    console.error(`\n  ✗ audio.file not found: ${edit.audio.file}\n`);
+    process.exit(1);
+  }
+  audio = { ...edit.audio, file };
+  const bed = path.basename(file);
+  console.log(`  ✓ audio bed ${bed} at ${audio.gainDb ?? -18}dB${audio.loop ? ', looped' : ''}`);
+}
+
+if (has('check')) {
+  console.log('\n  OK check — nothing was encoded\n');
+  process.exit(0);
+}
+
+const aspect = edit.aspect || '16:9';
+const size = ASPECTS[aspect];
+const fps = edit.fps || capture.fps || 30;
+const outDir = path.join(root, 'recordings', edit.source, 'out');
+const master = path.join(root, capture.outputs?.master || path.join('recordings', edit.source, 'out', `${edit.source}.mp4`));
+
+if (!fs.existsSync(master)) {
+  console.error(`\n  ✗ master not found at ${path.relative(root, master)} — re-run the recording\n`);
+  process.exit(1);
+}
+
+// ── captions ──────────────────────────────────────────────────────────────────
+const capDir = path.join(root, 'recordings', edit.source, '.captions');
+const captions = segments
+  .filter((s) => s.caption)
+  .map((s) => ({ key: `cap-${s.index}`, text: s.caption, kicker: s.kicker }));
+
+// ── motion overlays ───────────────────────────────────────────────────────────
+// Rendered before the stills, because a segment that animates does not want one. Each is
+// a PNG sequence at the edit's frame rate, produced by stepping the animation in Node and
+// screenshotting Chromium once per frame — the same determinism the capture mode relies on.
+const motionDir = path.join(root, 'recordings', edit.source, '.motion');
+fs.rmSync(motionDir, { recursive: true, force: true });
+let motionFrames = 0;
+for (const s of segments) {
+  if (!s.motion) continue;
+  const spec = {
+    text: s.caption,
+    kicker: s.kicker,
+    durationSec: s.captionForSec != null ? Math.min(s.captionForSec, s.outSec) : s.outSec,
+    ...s.motion,
+  };
+  const seq = await renderMotionSequence(spec, {
+    chromium, launch, dir: path.join(motionDir, `seg-${s.index}`),
+    width: size.w, height: size.h, aspect, fps, root,
+  });
+  s.motionSeq = seq;
+  motionFrames += seq.count;
+}
+if (motionFrames) {
+  console.log(`  ✓ ${motionFrames} animated overlay frame(s) across ${segments.filter((s) => s.motion).length} segment(s)`);
+}
+
+const stillCaptions = captions.filter((c) => !segments.find((s) => `cap-${s.index}` === c.key)?.motion);
+
+let rendered = new Map();
+if (stillCaptions.length) {
+  rendered = await renderCaptions(stillCaptions, {
+    chromium, launch, dir: capDir, width: size.w, height: size.h, aspect, root,
+  });
+  console.log(`  ✓ ${rendered.size} still caption(s) rendered in the studio typeface`);
+}
+for (const s of segments) {
+  if (s.caption && !s.motion) s.captionPng = rendered.get(`cap-${s.index}`);
+}
+
+// ── cut ───────────────────────────────────────────────────────────────────────
+const out = path.join(outDir, `${edit.name}.mp4`);
+try {
+  cutEdit({
+    input: master,
+    out,
+    segments,
+    size,
+    focusX: edit.focusX ?? 0.5,
+    fps,
+    crf: edit.crf ?? 19,
+    audio,
+  });
+} finally {
+  fs.rmSync(capDir, { recursive: true, force: true });
+  fs.rmSync(motionDir, { recursive: true, force: true });
+}
+
+const actual = probeDuration(out);
+console.log(`  ✓ ${path.relative(root, out)}  ${size.w}x${size.h}  ${actual ? actual.toFixed(1) + 's' : ''}  (${(fs.statSync(out).size / 1e6).toFixed(1)} MB)`);
+
+// The filtergraph is long and one wrong label silently drops a segment, so the result is
+// checked against what the edit asked for rather than assumed.
+if (actual && Math.abs(actual - totalSec) > 0.5) {
+  console.error(`\n  ✗ output is ${actual.toFixed(2)}s but the edit asks for ${totalSec.toFixed(2)}s — a segment did not make it\n`);
+  process.exit(1);
+}
+
+console.log('\n  OK\n');
+process.exit(0);