@mrkt_frwd/reel 0.1.0

package/src/edit.mjs

@@ -0,0 +1,303 @@
+/**
+ * Edit decision lists — deriving a short cut from a recorded master.
+ *
+ * A social clip is not a different recording, it is a different *reading* of one. Cutting
+ * from the master rather than re-recording keeps the two consistent, costs seconds instead
+ * of minutes, and means the 30-second version cannot drift from the two-minute version it
+ * claims to summarise.
+ *
+ * Segments address the master by shot id, resolved against the timeline in `capture.json`,
+ * so an edit survives the script being re-timed: shots move, the edit still points at the
+ * right material. Explicit `from`/`to` seconds are available where a shot needs trimming
+ * inside itself.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { validateMotion } from './motion.mjs';
+
+export const ASPECTS = {
+  '16:9': { w: 1920, h: 1080 },
+  '9:16': { w: 1080, h: 1920 },
+  '1:1': { w: 1080, h: 1080 },
+};
+
+/**
+ * Transitions, named for what a director would call them and mapped to the ffmpeg filter
+ * that implements each.
+ *
+ * A transition belongs to the segment it moves *into* — "dissolve into the WebGL shot" —
+ * which is how an edit reads aloud and why segment 0 cannot carry one: there is nothing
+ * to come from. `cut` is the absence of a transition and stays the default, because a
+ * demo that dissolves between every shot reads as a screensaver.
+ *
+ * Every transition costs runtime. Two shots joined by a 0.5s dissolve occupy 0.5s less
+ * than their sum, since the tail of one plays over the head of the next — which is why
+ * `resolve` subtracts them rather than reporting a total the file will not match.
+ */
+export const TRANSITIONS = {
+  cut: null,
+  fade: 'fade',
+  // A director saying "dissolve" means a crossfade. ffmpeg's filter of that name is a
+  // *grain* dissolve — pixels swapped at random, which on a dark UI reads as static over
+  // the shot. Found by extracting a frame from the middle of one rather than by reading
+  // the docs. So `dissolve` maps to the smooth blend people mean, and the grainy one is
+  // available under a name that describes it.
+  dissolve: 'fade',
+  grain: 'dissolve',
+  fadeblack: 'fadeblack',
+  fadewhite: 'fadewhite',
+  wipeleft: 'wipeleft',
+  wiperight: 'wiperight',
+  slideleft: 'slideleft',
+  slideright: 'slideright',
+  slideup: 'slideup',
+  slidedown: 'slidedown',
+  smoothleft: 'smoothleft',
+  smoothright: 'smoothright',
+  circleopen: 'circleopen',
+  circleclose: 'circleclose',
+};
+
+const DEFAULT_TRANSITION_SEC = 0.4;
+
+/**
+ * `"transition": "dissolve"` or `{ "type": "dissolve", "durationSec": 0.6 }`.
+ * Both forms appear in real edit files; the shorthand is what gets written by hand.
+ */
+export function normalizeTransition(value) {
+  if (value == null) return { type: 'cut', durationSec: 0 };
+  if (typeof value === 'string') {
+    return { type: value, durationSec: value === 'cut' ? 0 : DEFAULT_TRANSITION_SEC };
+  }
+  if (typeof value !== 'object') return null;
+  const type = value.type ?? 'cut';
+  return {
+    type,
+    durationSec: type === 'cut' ? 0 : Number(value.durationSec ?? DEFAULT_TRANSITION_SEC),
+  };
+}
+
+/**
+ * Static validation. Returns a list of problems, empty when the edit is well formed.
+ * Timeline-dependent checks live in `resolve`, which needs the capture to compare against.
+ */
+export function validateEdit(edit) {
+  const errors = [];
+  if (!edit || typeof edit !== 'object') return ['edit is not an object'];
+  if (!edit.name || !/^[a-z0-9][a-z0-9-]*$/.test(edit.name)) {
+    errors.push('name must be a lowercase slug — it becomes the output filename');
+  }
+  if (!edit.source) errors.push('missing source — the recording this cuts from');
+  if (edit.aspect && !ASPECTS[edit.aspect]) {
+    errors.push(`unknown aspect "${edit.aspect}" — one of ${Object.keys(ASPECTS).join(', ')}`);
+  }
+  if (!Array.isArray(edit.segments) || edit.segments.length === 0) {
+    errors.push('edit has no segments');
+    return errors;
+  }
+  edit.segments.forEach((seg, i) => {
+    const at = `segment ${i}`;
+    if (!seg || typeof seg !== 'object') return errors.push(`${at}: not an object`);
+    if (!seg.shot && seg.from == null) errors.push(`${at}: needs a shot id or an explicit from`);
+    if (seg.from != null && seg.to != null && seg.to <= seg.from) {
+      errors.push(`${at}: to (${seg.to}) is not after from (${seg.from})`);
+    }
+    if (seg.speed != null && (seg.speed < 0.25 || seg.speed > 4)) {
+      errors.push(`${at}: speed ${seg.speed} is outside 0.25-4`);
+    }
+    if (seg.focusX != null && (seg.focusX < 0 || seg.focusX > 1)) {
+      errors.push(`${at}: focusX ${seg.focusX} is outside 0-1`);
+    }
+    if (seg.caption != null && typeof seg.caption !== 'string') {
+      errors.push(`${at}: caption must be a string`);
+    }
+    if (seg.fit != null && !['cover', 'contain'].includes(seg.fit)) {
+      errors.push(`${at}: fit "${seg.fit}" — use "cover" (crop to fill) or "contain" (letterbox)`);
+    }
+
+    const tr = normalizeTransition(seg.transition);
+    if (tr === null) {
+      errors.push(`${at}: transition must be a name or { type, durationSec }`);
+    } else if (!(tr.type in TRANSITIONS)) {
+      errors.push(`${at}: unknown transition "${tr.type}" — one of ${Object.keys(TRANSITIONS).join(', ')}`);
+    } else if (tr.type !== 'cut') {
+      if (i === 0) {
+        errors.push(`${at}: the first segment cannot have a transition — there is nothing to come from`);
+      }
+      if (!(tr.durationSec > 0) || tr.durationSec > 3) {
+        errors.push(`${at}: transition durationSec ${tr.durationSec} is outside 0-3`);
+      }
+    }
+
+    if (seg.captionAt != null && seg.captionAt < 0) {
+      errors.push(`${at}: captionAt ${seg.captionAt} is before the segment starts`);
+    }
+    if (seg.captionForSec != null && !(seg.captionForSec > 0)) {
+      errors.push(`${at}: captionForSec must be positive`);
+    }
+    if (seg.captionFadeSec != null && (seg.captionFadeSec < 0 || seg.captionFadeSec > 2)) {
+      errors.push(`${at}: captionFadeSec ${seg.captionFadeSec} is outside 0-2`);
+    }
+    if (seg.motion != null) {
+      if (!seg.caption && !seg.kicker) {
+        errors.push(`${at}: motion needs a caption or kicker to animate`);
+      }
+      errors.push(...validateMotion(seg.motion, `${at} motion`));
+    }
+  });
+
+  // Audio is a whole-cut property: one bed under the piece, not a track per segment. Per
+  // segment audio would need mixing rules nobody has asked for, and a music bed that
+  // restarts at every cut is the sound of an edit fighting itself.
+  if (edit.audio != null) {
+    const a = edit.audio;
+    if (typeof a !== 'object') {
+      errors.push('audio must be an object — { file, gainDb, fadeInSec, fadeOutSec }');
+    } else {
+      if (!a.file || typeof a.file !== 'string') errors.push('audio.file is required');
+      if (a.gainDb != null && (a.gainDb < -60 || a.gainDb > 12)) {
+        errors.push(`audio.gainDb ${a.gainDb} is outside -60 to 12`);
+      }
+      for (const key of ['fadeInSec', 'fadeOutSec']) {
+        if (a[key] != null && (a[key] < 0 || a[key] > 10)) {
+          errors.push(`audio.${key} ${a[key]} is outside 0-10`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Turn segments into absolute in/out points against a capture.
+ *
+ * The failure this exists to catch is an edit that still names a shot the script has since
+ * renamed or removed. Nothing about that is visible in the edit file, and ffmpeg would
+ * happily cut from second zero — producing a plausible clip of the wrong material.
+ *
+ * @param {object} edit
+ * @param {object} capture parsed capture.json
+ */
+export function resolve(edit, capture) {
+  const problems = [];
+  const timeline = capture.timeline || [];
+  const byId = new Map(timeline.map((s) => [s.id, s]));
+  const duration = capture.durationSec ?? (timeline.length ? timeline[timeline.length - 1].endSec : 0);
+  const segments = [];
+
+  edit.segments.forEach((seg, i) => {
+    const at = `segment ${i}${seg.shot ? ` (${seg.shot})` : ''}`;
+    let start;
+    let end;
+
+    if (seg.shot) {
+      const shot = byId.get(seg.shot);
+      if (!shot) {
+        problems.push(`${at}: no shot "${seg.shot}" in ${capture.name} — it has ${[...byId.keys()].join(', ')}`);
+        return;
+      }
+      // from/to alongside a shot are offsets *within* it, which is how a director thinks
+      // about trimming: "the last two seconds of the orbit", not "second 19.6 of the file".
+      start = shot.startSec + (seg.from ?? 0);
+      end = seg.to != null ? shot.startSec + seg.to : shot.endSec;
+      if (end > shot.endSec + 1e-6) {
+        problems.push(`${at}: to ${seg.to}s runs past the shot, which is ${(shot.endSec - shot.startSec).toFixed(2)}s long`);
+        return;
+      }
+    } else {
+      start = seg.from;
+      end = seg.to ?? duration;
+    }
+
+    if (start < 0 || end > duration + 1e-6) {
+      problems.push(`${at}: ${start.toFixed(2)}-${end.toFixed(2)}s falls outside the ${duration.toFixed(2)}s master`);
+      return;
+    }
+    if (end - start < 0.25) {
+      problems.push(`${at}: ${(end - start).toFixed(2)}s is too short to register`);
+      return;
+    }
+
+    const speed = seg.speed ?? 1;
+    const transition = normalizeTransition(seg.transition) ?? { type: 'cut', durationSec: 0 };
+    segments.push({
+      index: i,
+      transition,
+      shot: seg.shot ?? null,
+      start,
+      end,
+      speed,
+      // Per segment, falling back to the edit default. One focus for a whole cut is wrong
+      // as soon as two shots put their subject in different places: cropping the studio
+      // tour to 9:16 with a single value framed the 3D stage correctly and sliced the left
+      // column off the brief form.
+      focusX: seg.focusX ?? edit.focusX ?? 0.5,
+      sourceSec: end - start,
+      outSec: (end - start) / speed,
+      fit: seg.fit ?? edit.fit ?? 'cover',
+      caption: seg.caption ?? null,
+      kicker: seg.kicker ?? null,
+      captionAt: seg.captionAt ?? 0,
+      captionForSec: seg.captionForSec ?? null,
+      captionFadeSec: seg.captionFadeSec ?? edit.captionFadeSec ?? 0,
+      motion: seg.motion ?? null,
+    });
+  });
+
+  // A transition overlaps its two segments, so the piece is shorter than the sum of its
+  // parts by exactly the transition durations. Getting this wrong is not cosmetic: the CLI
+  // compares the encoded duration against this number to catch a segment silently dropped
+  // by a mislabelled filtergraph, and an total that ignores overlap would fail every edit
+  // that dissolves.
+  let overlapSec = 0;
+  segments.forEach((s, i) => {
+    if (i === 0 || s.transition.type === 'cut') return;
+    // A transition cannot be longer than either shot it joins — ffmpeg produces a valid
+    // file with the tail of the shorter one missing, which is a silent content change.
+    const shorter = Math.min(s.outSec, segments[i - 1].outSec);
+    if (s.transition.durationSec >= shorter) {
+      problems.push(
+        `segment ${s.index}${s.shot ? ` (${s.shot})` : ''}: a ${s.transition.durationSec}s `
+        + `${s.transition.type} does not fit between shots of ${segments[i - 1].outSec.toFixed(2)}s `
+        + `and ${s.outSec.toFixed(2)}s — it would consume one of them whole`
+      );
+      return;
+    }
+    overlapSec += s.transition.durationSec;
+  });
+
+  const totalSec = segments.reduce((a, s) => a + s.outSec, 0) - overlapSec;
+  return { segments, problems, totalSec, overlapSec, sourceDurationSec: duration };
+}
+
+/**
+ * Advice on a duration budget. Reported rather than enforced: silently speeding a cut up
+ * to hit a number changes the pacing the director chose, and pacing is the whole point of
+ * the format.
+ */
+export function budgetReport(totalSec, budgetSec) {
+  if (!budgetSec) return null;
+  const over = totalSec - budgetSec;
+  if (over <= 0.05) return { ok: true, totalSec, budgetSec };
+  const speed = totalSec / budgetSec;
+  return {
+    ok: false,
+    totalSec,
+    budgetSec,
+    overSec: over,
+    suggestedSpeed: Number(speed.toFixed(2)),
+    hint: `trim ${over.toFixed(1)}s, or set "speed": ${speed.toFixed(2)} across the segments`,
+  };
+}
+
+export function loadCapture(root, sourceName) {
+  const file = path.join(root, 'recordings', sourceName, 'capture.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `no capture for "${sourceName}" — run \`npm run record -- recordings/${sourceName}/script.json\` first`
+    );
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}

package/src/frame-grid.mjs

@@ -0,0 +1,80 @@
+/**
+ * Downsampled luminance grids for frame comparison.
+ *
+ * The critic first compared frames by their luminance *aggregates* — mean, spread,
+ * occupancy — which `imageStats` already provides. That is unusably weak for video: a
+ * pure translation leaves every aggregate unchanged, so a scrolling repeated pattern, or
+ * a 3D object rotating under constant light, measured as perfectly still. The critic
+ * would then report a moving shot as frozen, which is the exact failure it exists to
+ * catch, inverted.
+ *
+ * Comparing a small luminance grid instead sees position. 16x16 is enough to register a
+ * scroll or an orbit and coarse enough to ignore compression noise, which a pixel-exact
+ * comparison would report as constant motion.
+ *
+ * Every frame is read in a single Python call. Per-frame spawning cost more than the
+ * decode for a strip of any length.
+ */
+import { spawnSync } from 'child_process';
+
+export const GRID = 16;
+
+const PY = `
+import sys, json
+from PIL import Image
+paths = json.loads(sys.stdin.read())
+out = []
+for p in paths:
+    try:
+        im = Image.open(p).convert('L').resize((${GRID}, ${GRID}), Image.BILINEAR)
+        out.append(list(im.getdata()))
+    except Exception:
+        out.append(None)
+print(json.dumps(out))
+`;
+
+/**
+ * @param {string[]} files
+ * @returns {{ ok: boolean, grids: (number[]|null)[], error?: string }}
+ */
+export function frameGrids(files) {
+  if (!files.length) return { ok: true, grids: [] };
+
+  for (const bin of ['python3', 'python']) {
+    const res = spawnSync(bin, ['-c', PY], {
+      input: JSON.stringify(files),
+      encoding: 'utf8',
+      maxBuffer: 256 * 1024 * 1024,
+    });
+    if (res.error || res.status !== 0) continue;
+    try {
+      const grids = JSON.parse(res.stdout);
+      if (Array.isArray(grids) && grids.length === files.length) return { ok: true, grids };
+    } catch {
+      // fall through to the next interpreter
+    }
+  }
+
+  // No backend means no measurement. Saying so is the only honest option — an unmeasured
+  // critique that reports a score is worse than one that refuses.
+  return {
+    ok: false,
+    grids: files.map(() => null),
+    error: 'No pixel backend for frame comparison — python3 with Pillow is required',
+  };
+}
+
+/** Mean absolute luminance difference between two grids, 0-255. */
+export function gridDelta(a, b) {
+  if (!a || !b || a.length !== b.length) return null;
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += Math.abs(a[i] - b[i]);
+  return sum / a.length;
+}
+
+/** Luminance spread within one grid — near zero means a flat, illegible frame. */
+export function gridSpread(g) {
+  if (!g || !g.length) return null;
+  const mean = g.reduce((a, b) => a + b, 0) / g.length;
+  return Math.sqrt(g.reduce((a, v) => a + (v - mean) ** 2, 0) / g.length);
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+/**
+ * Reel — a browser, driven from a script, recorded.
+ *
+ * The script is data, not code: validate it before spending four minutes on a
+ * capture, resolve every selector in a dry run, and record with a fixed clock
+ * so the frames do not depend on how long a frame cost to draw.
+ */
+export { validate, selectorsFor, dryRun, parseViewport } from './schema.mjs';
+export { ACTION_TYPES, ACTIONS, resetJitter } from './actions.mjs';
+export { resolveExecutable, launch, record } from './runner.mjs';
+export {
+  encodeMaster, encodeVertical, encodeGif,
+  sampleFrames, extractFrames, cutEdit, buildEditGraph, probeDuration,
+} from './assemble.mjs';
+export {
+  ASPECTS, TRANSITIONS, normalizeTransition,
+  validateEdit, resolve as resolveEdit, budgetReport, loadCapture,
+} from './edit.mjs';
+export { critique, writeCritique, CRITIC_WEIGHTS } from './critic.mjs';

package/src/motion.mjs

@@ -0,0 +1,229 @@
+/**
+ * Motion graphics — animated type, rendered a frame at a time in Chromium.
+ *
+ * Captions burned in as a single still can fade and can be scheduled, and that is the
+ * ceiling: the plate is the same image for every frame it appears in. Type that moves —
+ * a line rising into place, a rule drawing itself under a kicker, words arriving one after
+ * another — is what separates a demo from a screen recording with subtitles, and it is the
+ * one thing a still overlay can never do.
+ *
+ * ffmpeg cannot help here. Its text filter is absent from the bundled build (see
+ * caption.mjs), and even with it, keyframed type would mean expressing a design in filter
+ * expressions. So the same machine that renders the captions renders the animation: a page
+ * in Chromium, in the studio's own typefaces, screenshotted once per frame onto a
+ * transparent background. The result is an image sequence ffmpeg overlays like any other.
+ *
+ * The animation is evaluated in Node and applied as inline styles per frame — deliberately
+ * not CSS animations or WAAPI. A CSS animation advances on the browser's own clock, so the
+ * frame you screenshot is whatever the compositor had reached when the call returned, and
+ * two runs of the same edit would differ. Computing the state for frame `i` makes the
+ * sequence a pure function of the spec: byte-identical across runs and machines, which is
+ * the property the deterministic capture mode exists to protect.
+ */
+import fs from 'fs';
+import path from 'path';
+
+/** Presets, named for what they do to the eye rather than for the property they animate. */
+export const MOTION_PRESETS = {
+  /** Rises into place from below, fading in. The workhorse for a lower third. */
+  rise: { dy: 0.045, blur: 0, stagger: 0.10 },
+  /** Straight fade, no movement — for a caption that must not pull focus. */
+  fade: { dy: 0, blur: 0, stagger: 0.06 },
+  /** Drops in from above, for a title that lands on a beat. */
+  fall: { dy: -0.045, blur: 0, stagger: 0.10 },
+  /** Rises and resolves out of blur, like a rack focus onto the words. */
+  focus: { dy: 0.02, blur: 10, stagger: 0.12 },
+};
+
+export const EXITS = ['fade', 'rise', 'fall', 'hold'];
+
+/** easeOutCubic — fast arrival, soft landing. */
+const easeOut = (t) => 1 - Math.pow(1 - t, 3);
+/** easeInCubic, for exits, so a departure accelerates away. */
+const easeIn = (t) => t * t * t;
+
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+
+/**
+ * State of one animated line at time `t`, in seconds from the start of the overlay.
+ *
+ * Exported and pure so the curve can be asserted without a browser. Every value it
+ * returns is a style the renderer applies verbatim.
+ *
+ * @param {object} opts
+ * @param {number} opts.t seconds since the overlay began
+ * @param {number} opts.index which line this is, for stagger
+ * @param {number} opts.durationSec how long the overlay is on screen in total
+ * @param {string} opts.preset key of MOTION_PRESETS
+ * @param {string} opts.exit one of EXITS
+ * @param {number} [opts.enterSec] how long the entrance takes
+ * @param {number} [opts.exitSec] how long the exit takes
+ */
+export function lineStateAt({ t, index, durationSec, preset = 'rise', exit = 'fade', enterSec = 0.55, exitSec = 0.4 }) {
+  const p = MOTION_PRESETS[preset] || MOTION_PRESETS.rise;
+  const delay = index * p.stagger;
+
+  // Entrance
+  const enterT = clamp01((t - delay) / Math.max(0.001, enterSec));
+  const inProgress = easeOut(enterT);
+
+  // Exit. `hold` means the overlay never leaves under its own steam — the segment ending
+  // is what removes it, which is what a title card on the final shot wants.
+  let outProgress = 0;
+  if (exit !== 'hold' && exitSec > 0) {
+    const exitStart = durationSec - exitSec;
+    outProgress = easeIn(clamp01((t - exitStart) / Math.max(0.001, exitSec)));
+  }
+
+  const opacity = clamp01(inProgress * (1 - outProgress));
+
+  // Offsets are fractions of frame height, so one spec reads the same at 1080p and in 9:16.
+  let offset = p.dy * (1 - inProgress);
+  if (exit === 'rise') offset -= p.dy * outProgress;
+  if (exit === 'fall') offset += p.dy * outProgress;
+
+  const blur = p.blur * (1 - inProgress);
+
+  return { opacity, offsetY: offset, blurPx: blur };
+}
+
+/**
+ * Validate a motion spec. Returns problems; empty means well formed.
+ */
+export function validateMotion(motion, at = 'motion') {
+  const errors = [];
+  if (motion == null) return errors;
+  if (typeof motion !== 'object') return [`${at}: must be an object`];
+
+  if (motion.preset != null && !(motion.preset in MOTION_PRESETS)) {
+    errors.push(`${at}: unknown preset "${motion.preset}" — one of ${Object.keys(MOTION_PRESETS).join(', ')}`);
+  }
+  if (motion.exit != null && !EXITS.includes(motion.exit)) {
+    errors.push(`${at}: unknown exit "${motion.exit}" — one of ${EXITS.join(', ')}`);
+  }
+  for (const key of ['enterSec', 'exitSec']) {
+    if (motion[key] != null && (motion[key] < 0 || motion[key] > 4)) {
+      errors.push(`${at}: ${key} ${motion[key]} is outside 0-4`);
+    }
+  }
+  // An entrance and an exit that together outlast the overlay means the line never
+  // reaches full opacity — it fades up straight into fading down, which reads as a flicker
+  // rather than as a title.
+  if (motion.durationSec != null) {
+    const enter = motion.enterSec ?? 0.55;
+    const exitSec = motion.exit === 'hold' ? 0 : (motion.exitSec ?? 0.4);
+    if (enter + exitSec > motion.durationSec) {
+      errors.push(
+        `${at}: enter (${enter}s) + exit (${exitSec}s) exceeds the ${motion.durationSec}s it is on screen — `
+        + 'the type would never settle'
+      );
+    }
+  }
+  return errors;
+}
+
+function overlayHtml({ lines, width, height, aspect, tokensCss }) {
+  const inset = aspect === '9:16'
+    ? { bottom: 0.16, side: 0.08, maxWidth: 0.86 }
+    : aspect === '1:1'
+      ? { bottom: 0.11, side: 0.07, maxWidth: 0.8 }
+      : { bottom: 0.09, side: 0.06, maxWidth: 0.62 };
+  const base = Math.round(height * (aspect === '9:16' ? 0.030 : 0.038));
+
+  const rows = lines.map((l, i) => `
+  <div class="line ${l.kind}" data-i="${i}">${escapeHtml(l.text)}</div>`).join('');
+
+  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}
+.line{will-change:transform,opacity,filter}
+.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;
+  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-wrap:balance;
+  text-shadow:0 3px 18px rgba(0,0,0,.9),0 1px 4px rgba(0,0,0,.95);
+}
+</style></head><body>
+<div class="wrap">${rows}</div>
+<script>
+  // Applied from outside, once per frame. No CSS animation and no requestAnimationFrame:
+  // the renderer decides what frame this is, so the page must not have a clock of its own.
+  window.__apply = (states) => {
+    const els = document.querySelectorAll('.line');
+    states.forEach((s, i) => {
+      const el = els[i];
+      if (!el) return;
+      el.style.opacity = String(s.opacity);
+      el.style.transform = 'translateY(' + (s.offsetY * ${height}) + 'px)';
+      el.style.filter = s.blurPx > 0.01 ? 'blur(' + s.blurPx.toFixed(2) + 'px)' : 'none';
+    });
+  };
+</script>
+</body></html>`;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+  ));
+}
+
+/**
+ * Render an animated overlay to a numbered PNG sequence.
+ *
+ * @returns {Promise<{dir:string, count:number, fps:number}>}
+ */
+export async function renderMotionSequence(spec, { chromium, launch, dir, width, height, aspect, fps, root }) {
+  const lines = [];
+  if (spec.kicker) lines.push({ kind: 'kicker', text: spec.kicker });
+  if (spec.text) lines.push({ kind: 'text', text: spec.text });
+  if (!lines.length) return { dir, count: 0, fps };
+
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+
+  let tokensCss = '';
+  const tokensPath = path.join(root, 'assets', 'lib', 'tokens.css');
+  if (fs.existsSync(tokensPath)) tokensCss = fs.readFileSync(tokensPath, 'utf8');
+
+  const durationSec = spec.durationSec;
+  const frames = Math.max(1, Math.round(durationSec * fps));
+
+  const browser = await launch(chromium);
+  let count = 0;
+  try {
+    const page = await browser.newPage({ viewport: { width, height } });
+    await page.setContent(overlayHtml({ lines, width, height, aspect, tokensCss }), { waitUntil: 'load' });
+    await page.evaluate(() => document.fonts?.ready).catch(() => {});
+
+    for (let i = 0; i < frames; i++) {
+      const t = i / fps;
+      const states = lines.map((_, index) => lineStateAt({
+        t,
+        index,
+        durationSec,
+        preset: spec.preset,
+        exit: spec.exit,
+        enterSec: spec.enterSec,
+        exitSec: spec.exitSec,
+      }));
+      await page.evaluate((s) => window.__apply(s), states);
+      await page.screenshot({
+        path: path.join(dir, `m-${String(i + 1).padStart(5, '0')}.png`),
+        omitBackground: true,
+      });
+      count++;
+    }
+  } finally {
+    await browser.close().catch(() => {});
+  }
+
+  return { dir, count, fps };
+}