demobite 1.7.1 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demobite",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobite": "launcher/index.mjs"

package/scripts/trim.mjs

@@ -152,12 +152,16 @@ const dur = execFileSync(FFPROBE(), [
   "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", clean,
 ]).toString().trim();
 const duration = parseFloat(dur);
-// LAW (founder): a Bite is capped at 90 seconds by product concept. A take
-// that cuts longer than that must not proceed to staging — the story needs a
-// SPLIT, not a trim. Fail loudly here, before any upload machinery runs.
-if (duration > 90) {
+// LAW (founder 2026-10-10: 3 minutes, was 90 s since 2026-08-09): a Bite is
+// capped at 180 seconds by product concept — a LIMIT, not a target; the
+// sweet spot stays 30 to 45 s. A take that cuts longer than that must not
+// proceed to staging — the story needs a SPLIT, not a trim. Fail loudly here,
+// before any upload machinery runs. The server refuses the same number
+// (MAX_BITE_SECONDS; GET /api/recorder/limits answers it).
+const MAX_BITE_SECONDS = 180;
+if (duration > MAX_BITE_SECONDS) {
   console.error(
-    `HARD CAP: this take cuts to ${duration.toFixed(1)}s — a Bite is limited to 90 seconds. ` +
+    `HARD CAP: this take cuts to ${duration.toFixed(1)}s — a Bite is limited to 3 minutes. ` +
     "Do not upload. Split the scenario into multiple Bites and refilm."
   );
   process.exit(1);

package/skill/SKILL.md

@@ -144,9 +144,10 @@ Holding shots to cover estimated lines is what produced a 60 second take with th
 **Budgets, hold yourself to them:**
 
 - **30 to 45 seconds total (35 to 45 when the story crosses pages).** Over 45 is a rewrite, not a trim; under 30 with two pages is rushing, see the linger law below.
-- **90 seconds is a HARD CAP, by product concept, and it is a limit, not a
-  target.** A Bite over 90 seconds does not exist. Budget the beats BEFORE
-  filming: if the human's scenario cannot honestly fit inside 90 seconds, do
+- **3 minutes (180 s) is a HARD CAP, by product concept, and it is a limit,
+  not a target** (founder 2026-10-10; it was 90 s before). A Bite over 3
+  minutes does not exist. Budget the beats BEFORE filming: if the human's
+  scenario cannot honestly fit inside 3 minutes, do
   not film-and-trim and do not compress it into uselessness — tell them up
   front and ask them to SPLIT it into multiple Bites, one story per Bite.
   State the estimated duration in every storyboard presentation.
@@ -363,7 +364,7 @@ Laws for a re-take:
 
 ## Batch of briefs (GitHub PR → demos)
 
-The human pastes a bundle of approved briefs into the chat: a header (batchId, workspaceId, the target URL, the 90 second rule) and one block per brief (briefId, revision, contentHash, title, audience, outcome, flowIntent). Up to five briefs. The pasted text is a copy; the server holds the truth.
+The human pastes a bundle of approved briefs into the chat: a header (batchId, workspaceId, the target URL, the 3-minute rule) and one block per brief (briefId, revision, contentHash, title, audience, outcome, flowIntent). Up to five briefs. The pasted text is a copy; the server holds the truth.
 
 ```bash
 node scripts/briefs.mjs list <batchId> [--paste bundle.txt]        # the approved briefs; warns when the paste drifted

package/skill/scripts/briefs.mjs

@@ -96,7 +96,7 @@ function printBatch(data) {
   const { batch, briefs } = data;
   const src = batch?.source ? `${batch.source.repo}#${batch.source.prNumber}` : "";
   console.log(`Batch ${batch?.id ?? "?"}  ${src}  target ${batch?.target?.url ?? "?"}${batch?.target?.environment ? ` (${batch.target.environment})` : ""}`);
-  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most 90 seconds. One storyboard approval per brief.`);
+  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most 180 seconds (3 minutes). One storyboard approval per brief.`);
   for (const b of briefs) {
     const att = b.attempt ? ` · attempt ${b.attempt.ref} (${b.attempt.state})` : "";
     console.log(`\n  ${b.briefId}  r${b.revision}  ${b.status}${att}\n  ${b.title}\n  audience: ${b.audience}\n  outcome: ${b.outcome}${b.estimatedDurationSec ? `\n  about ${b.estimatedDurationSec}s` : ""}`);
@@ -138,7 +138,7 @@ function printRadar(data, slug) {
   // A radar batch has no target address: the agent films where the code
   // already runs (the Record stage says so); print the target only when set.
   console.log(`Batch ${batch?.id ?? "?"}${batch?.target?.url ? `  target ${batch.target.url}${batch.target.environment ? ` (${batch.target.environment})` : ""}` : ""}`);
-  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most ${batch?.rules?.maxSeconds ?? 90} seconds, in this order:\n`);
+  console.log(`${briefs.length} brief${briefs.length === 1 ? "" : "s"}, each at most ${batch?.rules?.maxSeconds ?? 180} seconds, in this order:\n`);
   const questions = [];
   order.forEach((b, i) => {
     const pos = String(i + 1).padStart(2, " ");
@@ -178,7 +178,7 @@ function writeRadarBundle(slug, data) {
  * The limits are the server's (a refine that breaks one answers 400
  * invalid_refine): title ≤ 80, audience ≤ 60, outcome ≤ 200, flowIntent 2..8
  * lines ≤ 120 each, prerequisites/exclusions ≤ 6 lines ≤ 160 each,
- * estimatedDurationSec 15..90. They are checked here first, with the field
+ * estimatedDurationSec 15..180 (3 minutes, founder 2026-10-10). They are checked here first, with the field
  * named, so the agent trims before posting instead of reading a 400. */
 const CONTENT_LIMITS = { title: 80, audience: 60, outcome: 200 };
 const LIST_LIMITS = { flowIntent: { min: 2, max: 8, line: 120 }, prerequisites: { min: 0, max: 6, line: 160 }, exclusions: { min: 0, max: 6, line: 160 } };
@@ -206,7 +206,7 @@ function refineProblems(c) {
     v.forEach((line, i) => { if (typeof line !== "string" || !line.trim()) out.push(`${k}[${i}]: an empty line`); else if (line.trim().length > lim.line) out.push(`${k}[${i}]: ${line.trim().length} characters, the limit is ${lim.line}`); });
   }
   const d = c.estimatedDurationSec;
-  if (!Number.isInteger(d) || d < 15 || d > 90) out.push(`estimatedDurationSec: ${JSON.stringify(d)}, must be a whole number of seconds 15..90`);
+  if (!Number.isInteger(d) || d < 15 || d > 180) out.push(`estimatedDurationSec: ${JSON.stringify(d)}, must be a whole number of seconds 15..90`);
   return out;
 }
 

package/skill/scripts/camera.mjs

@@ -0,0 +1,350 @@
+// The camera, locally. Every rule the DemoBites cloud uses to turn a take's
+// measured shots into zooms, in one readable file (ported from
+// planCameraPath in the app's recorder-ingest.ts and the export runtime's
+// keyframes.ts / videoMath.ts). Change a constant, re-run finish.mjs, see it.
+//
+// Input: manifest.demobites.json (times in clean.mp4 seconds, pixels in the
+// 1920x1080 take). Output: planShots() -> [{start,end,cx,cy,factor,wide}],
+// and cameraAt(t) -> {cx, cy, factor} for any frame.
+
+export const FRAME_W = 1920;
+export const FRAME_H = 1080;
+
+// ── How tight a zoom is ──────────────────────────────────────────────────
+// The subject (the button, the field, the chart) should fill this share of
+// the zoomed frame. Tiny targets hit the max; big ones fall to the min.
+export const ZOOM_MIN_FACTOR = 1.25;
+export const ZOOM_MAX_FACTOR = 3.0;
+export const SUBJECT_FILL_W = 0.6;
+export const SUBJECT_FILL_H = 0.75;
+// A box the storyboard drew by hand is the zoom itself, with a little air.
+export const AUTHORED_FILL_W = 0.92;
+export const AUTHORED_FILL_H = 0.9;
+export const AUTHORED_MIN_FACTOR = 1.05;
+
+// ── When a zoom is allowed ───────────────────────────────────────────────
+export const ZOOM_MIN_START = 0.5;   // never zoom on the very first frames
+export const ZOOM_END_BUFFER = 0.8;  // the video always ends wide
+export const ZOOM_MIN_LENGTH = 0.9;  // shorter than this is a flicker, dropped
+export const SHOT_OVERLAP_SECONDS = 0.5; // chained shots travel, never pull out
+
+// ── The regime ladder (founder laws, 2026-08-09) ─────────────────────────
+// Motion is the cost, tightness is the budget, the union rectangle judges.
+// 1. MERGE: one steady framing that holds two neighbours beats two zooms,
+//    if it gives up less than MERGE_TOLERANCE of tightness.
+// 2. PAN: neighbours near each other keep their tightness and the camera
+//    travels WITH the cursor's glide.
+// 3. TROMBONE: far apart and both tight: arc out through exactly the union
+//    framing (never wider) during the glide, then tighten on arrival.
+export const MERGE_TOLERANCE = 0.75;
+export const MERGE_FLOOR = 1.35;
+export const MERGE_MAX_GAP_SECONDS = 4;
+export const PAN_MAX_TRAVEL = 0.85;
+export const TROMBONE_ANTICIPATION = 0.25;
+export const TROMBONE_SETTLE_LEAD = 0.15;
+
+// ── The invariant: the cursor is inside the frame on every frame ─────────
+export const INVARIANT_SLACK_PX = 16;
+export const INVARIANT_WIDEN_STEP = 1.15;
+export const INVARIANT_MAX_PASSES = 4;
+
+// ── Motion ───────────────────────────────────────────────────────────────
+// Transition length grows with how far the camera moves: 0.5 s for a nudge,
+// 1.2 s for a full pull-out from max zoom. Every move eases with the
+// material curve bezier(0.4, 0, 0.2, 1).
+export function transitionSeconds(from, to) {
+  const scaleMag = Math.abs(to.factor - from.factor) / 2;
+  const dx = (remX(to) - remX(from)) / 960;
+  const dy = (remY(to) - remY(from)) / 540;
+  const posMag = Math.sqrt(dx * dx + dy * dy) / 1.414;
+  return 0.5 + Math.min(Math.max(scaleMag, posMag) * 0.5, 0.7);
+}
+// The runtime moves a translate, not a centre: (960 - cx) * factor.
+const remX = (c) => (FRAME_W / 2 - c.cx) * c.factor;
+const remY = (c) => (FRAME_H / 2 - c.cy) * c.factor;
+
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const round2 = (v) => Math.round(v * 100) / 100;
+
+export function factorForSubject(w, h) {
+  const raw = Math.min((SUBJECT_FILL_W * FRAME_W) / Math.max(24, w), (SUBJECT_FILL_H * FRAME_H) / Math.max(18, h));
+  return round2(clamp(raw, ZOOM_MIN_FACTOR, ZOOM_MAX_FACTOR));
+}
+export function factorForAuthored(w, h) {
+  const raw = Math.min((AUTHORED_FILL_W * FRAME_W) / Math.max(24, w), (AUTHORED_FILL_H * FRAME_H) / Math.max(18, h));
+  return round2(clamp(raw, AUTHORED_MIN_FACTOR, ZOOM_MAX_FACTOR));
+}
+function transitionFactor(w, h) {
+  const raw = Math.min((SUBJECT_FILL_W * FRAME_W) / Math.max(24, w), (SUBJECT_FILL_H * FRAME_H) / Math.max(18, h));
+  return round2(clamp(raw, 1.01, ZOOM_MAX_FACTOR));
+}
+// The zoomed viewport never leaves the take: no dead space at an edge.
+export function clampPin(cx, cy, factor) {
+  const hw = FRAME_W / (2 * factor), hh = FRAME_H / (2 * factor);
+  return { x: clamp(cx, hw, FRAME_W - hw), y: clamp(cy, hh, FRAME_H - hh) };
+}
+function unionRect(a, b) {
+  const x1 = Math.min(a.sx, b.sx), y1 = Math.min(a.sy, b.sy);
+  const x2 = Math.max(a.sx + a.sw, b.sx + b.sw), y2 = Math.max(a.sy + a.sh, b.sy + b.sh);
+  return { x: x1, y: y1, w: x2 - x1, h: y2 - y1 };
+}
+function reframe(shot, subj, factor) {
+  shot.sx = subj.x; shot.sy = subj.y; shot.sw = subj.w; shot.sh = subj.h;
+  shot.factor = factor;
+  const pin = clampPin(subj.x + subj.w / 2, subj.y + subj.h / 2, factor);
+  shot.cx = pin.x; shot.cy = pin.y;
+}
+// CUT LAW: a navigation cut is a hard camera boundary.
+function crosses(a, b, cuts) { return cuts.some((c) => a < c.end && b > c.start); }
+
+export function planShots(manifest, duration, log = () => {}) {
+  const lastEnd = duration - ZOOM_END_BUFFER;
+  if (lastEnd <= ZOOM_MIN_START) return [];
+  const cuts = (manifest.cuts ?? [])
+    .map((c) => ({ start: Number(c.t_start), end: Number(c.t_end) }))
+    .filter((c) => c.end > c.start);
+
+  let planned = [];
+  for (const s of manifest.camera ?? []) {
+    const [t0, t1, x, y, w, h] = [s.t_start, s.t_end, s.x, s.y, s.w, s.h].map(Number);
+    if (![t0, t1, x, y, w, h].every(Number.isFinite) || w <= 0 || h <= 0 || t1 <= t0) continue;
+    const g = s.glide;
+    const glide = g && g.t_end > g.t_start && g.t_end - g.t_start <= 5 && Math.abs(g.t_end - t0) <= 1.5 ? { t_start: g.t_start, t_end: g.t_end } : undefined;
+    if (s.wide) {
+      // WIDE (founder 2026-09-27): a landing is 1.0, whatever box was measured.
+      const start = Math.max(0, t0), end = Math.min(t1, duration);
+      if (end - start < ZOOM_MIN_LENGTH * 0.6) continue;
+      planned.push({ start, end, cx: FRAME_W / 2, cy: FRAME_H / 2, factor: 1, sx: 0, sy: 0, sw: FRAME_W, sh: FRAME_H, tight: 1, n: s.n, wide: true, label: s.label });
+      continue;
+    }
+    const factor = s.authored ? factorForAuthored(w, h) : factorForSubject(w, h);
+    const pin = clampPin(x + w / 2, y + h / 2, factor);
+    const start = Math.max(ZOOM_MIN_START, t0), end = Math.min(t1, lastEnd);
+    if (end - start < ZOOM_MIN_LENGTH) continue;
+    planned.push({ start, end, cx: pin.x, cy: pin.y, factor, sx: x, sy: y, sw: w, sh: h, tight: factor, n: s.n, revealed: s.revealed === true, glide, authored: s.authored === true, label: s.label });
+  }
+  planned.sort((a, b) => a.start - b.start);
+  if (!planned.length) return [];
+
+  // Two wides in a row are one wide.
+  planned = planned.reduce((out, s) => {
+    const last = out[out.length - 1];
+    if (last?.wide && s.wide && s.start - last.end <= 1.5 && !crosses(last.start, Math.max(last.end, s.end), cuts)) { last.end = Math.max(last.end, s.end); return out; }
+    out.push(s); return out;
+  }, []);
+
+  if (planned.some((s) => s.glide)) {
+    // "The button plus what the button did": a revealed shot keeps its control in frame.
+    for (const s of planned) {
+      if (!s.revealed || s.n == null || s.authored || s.wide) continue;
+      const control = planned.find((c) => c.n === s.n && !c.revealed && !c.wide);
+      if (!control) continue;
+      const u = unionRect(s, control);
+      reframe(s, u, factorForSubject(u.w, u.h));
+    }
+    // 1. MERGE
+    const merged = [];
+    for (const s of planned) {
+      const last = merged[merged.length - 1];
+      if (last && !last.authored && !s.authored && !last.wide && !s.wide && s.start - last.end <= MERGE_MAX_GAP_SECONDS && !crosses(last.start, Math.max(last.end, s.end), cuts)) {
+        const u = unionRect(last, s);
+        const uf = factorForSubject(u.w, u.h);
+        const tight = Math.max(last.tight, s.tight);
+        if (uf >= tight - MERGE_TOLERANCE && uf >= MERGE_FLOOR) {
+          reframe(last, u, uf); last.end = Math.max(last.end, s.end); last.tight = tight;
+          last.label = `${last.label} + ${s.label}`;
+          continue;
+        }
+      }
+      merged.push(s);
+    }
+    // 2/3. PAN or TROMBONE
+    const out = [merged[0]];
+    for (let i = 1; i < merged.length; i++) {
+      const A = out[out.length - 1], B = merged[i];
+      if (B.start - A.start < ZOOM_MIN_LENGTH || crosses(A.start, B.start, cuts) || A.wide || B.wide) { out.push(B); continue; }
+      const departure = B.glide ? B.glide.t_start : B.start - 1.2;
+      const arrival = B.glide ? B.glide.t_end : B.start + 0.3;
+      const maxF = Math.max(A.factor, B.factor);
+      if (Math.abs(A.cx - B.cx) <= (PAN_MAX_TRAVEL * FRAME_W) / maxF && Math.abs(A.cy - B.cy) <= (PAN_MAX_TRAVEL * FRAME_H) / maxF) {
+        B.start = Math.max(A.start + ZOOM_MIN_LENGTH, Math.min(B.start, departure - TROMBONE_SETTLE_LEAD));
+        A.end = Math.min(lastEnd, Math.max(A.end, arrival + TROMBONE_SETTLE_LEAD));
+        B.how = "pan"; out.push(B); continue;
+      }
+      const u = unionRect(A, B);
+      const uf = transitionFactor(u.w, u.h);
+      if (uf < maxF - 0.1) {
+        const uStart = Math.max(A.start + ZOOM_MIN_LENGTH, departure - TROMBONE_ANTICIPATION);
+        const uEnd = Math.min(lastEnd, Math.max(arrival + TROMBONE_SETTLE_LEAD, uStart + ZOOM_MIN_LENGTH));
+        if (uStart < B.start - 0.15 && uEnd - uStart >= ZOOM_MIN_LENGTH * 0.6) {
+          const U = { start: uStart, end: uEnd, cx: 0, cy: 0, factor: uf, sx: u.x, sy: u.y, sw: u.w, sh: u.h, tight: uf, label: `${A.label} to ${B.label}`, how: "trombone" };
+          reframe(U, u, uf); out.push(U);
+        }
+      }
+      out.push(B);
+    }
+    planned = out.sort((a, b) => a.start - b.start);
+
+    // Scroll means breathe out: the camera is wide while the page slides.
+    for (const st of manifest.steps ?? []) {
+      if (st.action !== "scroll" || !(st.t_end > st.t_start)) continue;
+      const w = { start: Math.max(0, st.t_start - 0.3), end: Math.min(lastEnd, Math.min(st.t_end, st.t_start + 2.8) + 0.3) };
+      if (w.end - w.start < 0.5) continue;
+      for (const s of planned) {
+        if (s.factor <= 1.3) continue;
+        if (s.start < w.start && s.end > w.start) s.end = w.start;
+        if (s.start >= w.start && s.start < w.end) s.start = Math.min(w.end, lastEnd - ZOOM_MIN_LENGTH);
+      }
+      planned.push({ start: w.start, end: w.end, cx: 960, cy: 540, factor: 1.01, sx: 0, sy: 0, sw: FRAME_W, sh: FRAME_H, tight: 1.01, label: "scroll, wide" });
+    }
+    planned = planned.filter((s) => s.end - s.start >= ZOOM_MIN_LENGTH * 0.6).sort((a, b) => a.start - b.start);
+  }
+
+  // Continuity: each shot overlaps its successor so the camera travels
+  // instead of pulling out between them. A wide is a boundary.
+  for (let i = 0; i < planned.length - 1; i++) {
+    const cur = planned[i], next = planned[i + 1];
+    if (next.start < cur.start + ZOOM_MIN_LENGTH) next.start = cur.start + ZOOM_MIN_LENGTH;
+    if (next.end < next.start + ZOOM_MIN_LENGTH) next.end = Math.min(next.start + ZOOM_MIN_LENGTH, lastEnd);
+    if (next.wide) {
+      if (cur.end < next.start && next.start - cur.end <= 1.0) cur.end = next.start;
+      cur.end = Math.min(cur.end, next.start, lastEnd);
+      continue;
+    }
+    if (cur.wide) { cur.end = Math.min(cur.end, next.start); continue; }
+    if (crosses(cur.start, next.start, cuts)) { continue; }
+    cur.end = Math.min(Math.max(cur.end, next.start + SHOT_OVERLAP_SECONDS), lastEnd, next.end);
+  }
+  let final = planned.filter((s) => s.end - s.start >= ZOOM_MIN_LENGTH * 0.6);
+
+  // THE INVARIANT: simulate the camera against the real cursor track; any
+  // moment the cursor would leave the frame widens the shot there.
+  const track = (manifest.interactions?.mouseEvents ?? []).filter((e) => [e.x, e.y, e.time].every(Number.isFinite));
+  if (track.length > 1) {
+    const zooms = () => final.filter((s) => !s.wide);
+    const violations = (slack) => {
+      const cam = buildTimeline(zooms(), duration);
+      return track.filter((e) => {
+        const c = cam(e.time);
+        if (c.factor <= 1.001) return false;
+        return Math.abs(e.x - c.cx) > FRAME_W / (2 * c.factor) - slack || Math.abs(e.y - c.cy) > FRAME_H / (2 * c.factor) - slack;
+      }).map((e) => e.time);
+    };
+    let v = violations(INVARIANT_SLACK_PX);
+    const initial = v.length;
+    for (let pass = 0; pass < INVARIANT_MAX_PASSES && v.length; pass++) {
+      const widened = new Set();
+      for (const t of v) for (const s of zooms()) {
+        if (s.start <= t && t <= s.end && !widened.has(s) && s.factor > 1.01) {
+          widened.add(s);
+          reframe(s, { x: s.sx, y: s.sy, w: s.sw, h: s.sh }, Math.max(1.01, s.factor / INVARIANT_WIDEN_STEP));
+        }
+      }
+      if (!widened.size) break;
+      v = violations(INVARIANT_SLACK_PX);
+    }
+    log(`camera invariant: ${initial} near-edge samples -> ${v.length} after widening; ${violations(0).length} true cursor losses`);
+  }
+  return final;
+}
+
+// ── From shots to a camera at every frame (the export runtime's keyframes) ──
+// Each zoom: travel from wherever the camera is to the shot over
+// transitionSeconds; hold; then either hand over to the next shot (overlap)
+// or pull back to 1.0 so the pull-out FINISHES at the shot's end.
+export function buildTimeline(shots, duration) {
+  const zooms = shots.filter((s) => !s.wide).sort((a, b) => a.start - b.start);
+  const base = { cx: FRAME_W / 2, cy: FRAME_H / 2, factor: 1 };
+  const kf = [{ t: 0, ...base }];
+  let cur = base;
+  for (let i = 0; i < zooms.length; i++) {
+    const z = zooms[i];
+    const target = { cx: z.cx, cy: z.cy, factor: z.factor };
+    const tin = transitionSeconds(cur, target);
+    const tout = transitionSeconds(target, base);
+    const next = zooms[i + 1];
+    kf.push({ t: z.start, ...cur });
+    kf.push({ t: z.start + tin, ...target });
+    cur = target;
+    if (next && next.start < z.end) {
+      if (next.start > z.start + tin) kf.push({ t: next.start, ...target });
+    } else {
+      kf.push({ t: Math.max(z.start + tin, z.end - tout), ...target });
+      kf.push({ t: Math.max(z.start + tin + 0.01, z.end), ...base });
+      cur = base;
+    }
+  }
+  kf.push({ t: Math.max(duration, kf[kf.length - 1].t + 0.01), ...cur });
+  // Keyframes must be strictly increasing in time.
+  const clean = kf.reduce((out, k) => { if (!out.length || k.t > out[out.length - 1].t) out.push(k); else out[out.length - 1] = k; return out; }, []);
+  return (t) => {
+    if (t <= clean[0].t) return { ...clean[0] };
+    for (let i = 1; i < clean.length; i++) {
+      const a = clean[i - 1], b = clean[i];
+      if (t <= b.t) {
+        const p = ease((t - a.t) / (b.t - a.t));
+        // Interpolate the translate and the scale, like the runtime does.
+        const f = a.factor + (b.factor - a.factor) * p;
+        const rx = remX(a) + (remX(b) - remX(a)) * p;
+        const ry = remY(a) + (remY(b) - remY(a)) * p;
+        return { factor: f, cx: FRAME_W / 2 - rx / f, cy: FRAME_H / 2 - ry / f };
+      }
+    }
+    return { ...clean[clean.length - 1] };
+  };
+}
+
+// ── SPRING motion (measured off a competitor's output, 2026-09-29) ─────────
+// Critically damped: full speed the moment it starts, a long soft landing,
+// never overshoots. Halfway in 0.2 s, settled in ~0.8 s, whatever the
+// distance. A new target mid-flight keeps the velocity, so chained moves
+// (zoom → pan → zoom) flow instead of stopping and restarting.
+export const SPRING = { stiffness: 100, damping: 20, mass: 1 };
+// The spring cannot "finish at" a time, so a pull-out is released this much
+// before the shot ends (94% of the way out by then).
+export const SPRING_RELEASE_LEAD = 0.45;
+
+export function buildSpringTimeline(shots, duration, spring = SPRING) {
+  const zooms = shots.filter((s) => !s.wide).sort((a, b) => a.start - b.start);
+  const base = { cx: FRAME_W / 2, cy: FRAME_H / 2, factor: 1 };
+  // Where the camera WANTS to be at time t (a step function).
+  const segs = zooms.map((z, i) => {
+    const next = zooms[i + 1];
+    const release = next && next.start < z.end ? next.start : Math.max(z.start + 0.3, z.end - SPRING_RELEASE_LEAD);
+    return { from: z.start, to: release, target: { cx: z.cx, cy: z.cy, factor: z.factor } };
+  });
+  const targetAt = (t) => { let tg = base; for (const s of segs) if (s.from <= t && t < s.to) tg = s.target; return tg; };
+  // Spring the runtime's own variables (translate + scale) so a settled
+  // camera is exactly the planned shot and the path never shows dead space.
+  const HZ = 600, dt = 1 / HZ, n = Math.ceil((duration + 1) * HZ);
+  const { stiffness: k, damping: c, mass: m } = spring;
+  const st = { rx: 0, ry: 0, f: 1, vx: 0, vy: 0, vf: 0 };
+  const samples = new Float64Array(n * 3);
+  for (let i = 0; i < n; i++) {
+    const tg = targetAt(i * dt);
+    const tx = remX(tg), ty = remY(tg), tf = tg.factor;
+    st.vx += ((-k * (st.rx - tx) - c * st.vx) / m) * dt; st.rx += st.vx * dt;
+    st.vy += ((-k * (st.ry - ty) - c * st.vy) / m) * dt; st.ry += st.vy * dt;
+    st.vf += ((-k * (st.f - tf) - c * st.vf) / m) * dt; st.f += st.vf * dt;
+    samples[i * 3] = st.rx; samples[i * 3 + 1] = st.ry; samples[i * 3 + 2] = st.f;
+  }
+  return (t) => {
+    const x = clamp(t * HZ, 0, n - 1.001), i = Math.floor(x), p = x - i;
+    const g = (o) => samples[i * 3 + o] + (samples[(i + 1) * 3 + o] - samples[i * 3 + o]) * p;
+    const f = Math.max(1, g(2));
+    return { factor: f, cx: FRAME_W / 2 - g(0) / f, cy: FRAME_H / 2 - g(1) / f };
+  };
+}
+
+// cubic-bezier(0.4, 0, 0.2, 1), solved for x by Newton iterations.
+function ease(x) {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const x1 = 0.4, y1 = 0, x2 = 0.2, y2 = 1;
+  const bx = (t) => 3 * (1 - t) * (1 - t) * t * x1 + 3 * (1 - t) * t * t * x2 + t * t * t;
+  const by = (t) => 3 * (1 - t) * (1 - t) * t * y1 + 3 * (1 - t) * t * t * y2 + t * t * t;
+  const dbx = (t) => 3 * (1 - t) * (1 - t) * x1 + 6 * (1 - t) * t * (x2 - x1) + 3 * t * t * (1 - x2);
+  let t = x;
+  for (let i = 0; i < 8; i++) { const d = dbx(t); if (Math.abs(d) < 1e-6) break; t = clamp(t - (bx(t) - x) / d, 0, 1); }
+  return by(t);
+}

package/skill/scripts/cursors.mjs

@@ -0,0 +1,7 @@
+// Cursor glyphs, the same SVGs the DemoBites studio draws (public/cursors),
+// with the studio hotspots and native sizes. Generated; edit the app copies.
+export const CURSORS = {
+  arrow: { w: 12, h: 19, hotspot: { x: 1, y: 1 }, svg: "<svg width=\"12\" height=\"19\" viewBox=\"0 0 12 19\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><g clip-path=\"url(#clip0_1_69)\"><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M0 16.015V0L11.591 11.619H4.81L4.399 11.743L0 16.015Z\" fill=\"white\"/><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M9.08449 16.6893L5.47949 18.2243L0.797485 7.1353L4.48349 5.5823L9.08449 16.6893Z\" fill=\"white\"/><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M7.75101 16.0086L5.90701 16.7826L2.80701 9.4086L4.64801 8.6336L7.75101 16.0086Z\" fill=\"black\"/><path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M1 2.4071V13.5951L3.969 10.7291L4.397 10.5901H9.165L1 2.4071Z\" fill=\"black\"/></g><defs><clipPath id=\"clip0_1_69\"><rect width=\"12\" height=\"19\" fill=\"white\"/></clipPath></defs></svg>" },
+  pointingHand: { w: 16, h: 17, hotspot: { x: 5, y: 0 }, svg: "<svg width=\"16\" height=\"17\" viewBox=\"0 0 16 17\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"> <g clip-path=\"url(#clip0_1_131)\"> <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M3.3315 12.3799C3.0475 12.0209 2.7025 11.2869 2.0885 10.3959C1.7405 9.8919 0.877496 8.9429 0.620496 8.4609C0.397496 8.0349 0.421496 7.8439 0.474496 7.4909C0.568496 6.8629 1.2125 6.3739 1.8995 6.4399C2.4185 6.4889 2.8585 6.8319 3.2545 7.1559C3.4935 7.3509 3.7875 7.7299 3.9645 7.9439C4.1275 8.1399 4.1675 8.2209 4.3415 8.4529C4.5715 8.7599 4.6435 8.9119 4.5555 8.5739C4.4845 8.0779 4.3685 7.2309 4.2005 6.4819C4.0725 5.9139 4.0415 5.8249 3.9195 5.3889C3.7905 4.9249 3.7245 4.5999 3.6035 4.1079C3.5195 3.7599 3.3685 3.0489 3.3275 2.6489C3.2705 2.1019 3.2405 1.2099 3.5915 0.799903C3.8665 0.478903 4.4975 0.381903 4.8885 0.579903C5.4005 0.838903 5.6915 1.5829 5.8245 1.8799C6.0635 2.4139 6.2115 3.0309 6.3405 3.8409C6.5045 4.8719 6.8065 6.3029 6.8165 6.6039C6.8405 6.2349 6.7485 5.4579 6.8125 5.1039C6.8705 4.7829 7.1405 4.4099 7.4785 4.3089C7.7645 4.2239 8.0995 4.1929 8.3945 4.2539C8.7075 4.3179 9.03749 4.5419 9.16049 4.7529C9.5225 5.3769 9.5295 6.6519 9.5445 6.5839C9.6305 6.2079 9.61549 5.3549 9.8285 4.9999C9.9685 4.7659 10.3255 4.5549 10.5155 4.5209C10.8095 4.4689 11.1705 4.4529 11.4795 4.5129C11.7285 4.5619 12.0655 4.8579 12.1565 4.9999C12.3745 5.3439 12.4985 6.3169 12.5355 6.6579C12.5505 6.7989 12.6095 6.2659 12.8285 5.9219C13.2345 5.2829 14.6715 5.1589 14.7265 6.5609C14.7515 7.2149 14.7465 7.1849 14.7465 7.6249C14.7465 8.1419 14.7345 8.4529 14.7065 8.8269C14.6755 9.2269 14.5895 10.1309 14.4645 10.5689C14.3785 10.8699 14.0935 11.5469 13.8125 11.9529C13.8125 11.9529 12.7385 13.2029 12.6215 13.7659C12.5035 14.3279 12.5425 14.3319 12.5195 14.7309C12.4965 15.1289 12.6405 15.6529 12.6405 15.6529C12.6405 15.6529 11.8385 15.7569 11.4065 15.6879C11.0155 15.6249 10.5315 14.8469 10.4065 14.6089C10.2345 14.2809 9.86749 14.3439 9.72449 14.5859C9.49949 14.9689 9.0155 15.6559 8.6735 15.6989C8.0055 15.7829 6.6195 15.7299 5.5345 15.7189C5.5345 15.7189 5.7195 14.7079 5.3075 14.3609C5.0025 14.1019 4.4775 13.5769 4.1635 13.3009L3.3315 12.3799Z\" fill=\"white\"/> <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M3.3315 12.3799C3.0475 12.0209 2.7025 11.2869 2.0885 10.3959C1.7405 9.8919 0.877496 8.9429 0.620496 8.4609C0.397496 8.0349 0.421496 7.8439 0.474496 7.4909C0.568496 6.8629 1.2125 6.3739 1.8995 6.4399C2.4185 6.4889 2.8585 6.8319 3.2545 7.1559C3.4935 7.3509 3.7875 7.7299 3.9645 7.9439C4.1275 8.1399 4.1675 8.2209 4.3415 8.4529C4.5715 8.7599 4.6435 8.9119 4.5555 8.5739C4.4845 8.0779 4.3685 7.2309 4.2005 6.4819C4.0725 5.9139 4.0415 5.8249 3.9195 5.3889C3.7905 4.9249 3.7245 4.5999 3.6035 4.1079C3.5195 3.7599 3.3685 3.0489 3.3275 2.6489C3.2705 2.1019 3.2405 1.2099 3.5915 0.799903C3.8665 0.478903 4.4975 0.381903 4.8885 0.579903C5.4005 0.838903 5.6915 1.5829 5.8245 1.8799C6.0635 2.4139 6.2115 3.0309 6.3405 3.8409C6.5045 4.8719 6.8065 6.3029 6.8165 6.6039C6.8405 6.2349 6.7485 5.4579 6.8125 5.1039C6.8705 4.7829 7.1405 4.4099 7.4785 4.3089C7.7645 4.2239 8.0995 4.1929 8.3945 4.2539C8.7075 4.3179 9.03749 4.5419 9.16049 4.7529C9.52249 5.3769 9.5295 6.6519 9.5445 6.5839C9.6305 6.2079 9.6155 5.3549 9.8285 4.9999C9.9685 4.7659 10.3255 4.5549 10.5155 4.5209C10.8095 4.4689 11.1705 4.4529 11.4795 4.5129C11.7285 4.5619 12.0655 4.8579 12.1565 4.9999C12.3745 5.3439 12.4985 6.3169 12.5355 6.6579C12.5505 6.7989 12.6095 6.2659 12.8285 5.9219C13.2345 5.2829 14.6715 5.1589 14.7265 6.5609C14.7515 7.2149 14.7465 7.1849 14.7465 7.6249C14.7465 8.1419 14.7345 8.4529 14.7065 8.8269C14.6755 9.2269 14.5895 10.1309 14.4645 10.5689C14.3785 10.8699 14.0935 11.5469 13.8125 11.9529C13.8125 11.9529 12.7385 13.2029 12.6215 13.7659C12.5035 14.3279 12.5425 14.3319 12.5195 14.7309C12.4965 15.1289 12.6405 15.6529 12.6405 15.6529C12.6405 15.6529 11.8385 15.7569 11.4065 15.6879C11.0155 15.6249 10.5315 14.8469 10.4065 14.6089C10.2345 14.2809 9.86749 14.3439 9.72449 14.5859C9.49949 14.9689 9.0155 15.6559 8.6735 15.6989C8.0055 15.7829 6.6195 15.7299 5.5345 15.7189C5.5345 15.7189 5.7195 14.7079 5.3075 14.3609C5.0025 14.1019 4.4775 13.5769 4.1635 13.3009L3.3315 12.3799Z\" stroke=\"black\" stroke-width=\"0.75\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/> <path d=\"M11.5664 12.7344V9.27541\" stroke=\"black\" stroke-width=\"0.75\" stroke-linecap=\"round\"/> <path d=\"M9.55079 12.7461L9.53479 9.2731\" stroke=\"black\" stroke-width=\"0.75\" stroke-linecap=\"round\"/> <path d=\"M7.55469 9.3047L7.57569 12.7307\" stroke=\"black\" stroke-width=\"0.75\" stroke-linecap=\"round\"/> </g> <defs> <clipPath id=\"clip0_1_131\"> <rect width=\"16\" height=\"17\" fill=\"white\"/> </clipPath> </defs> </svg>" },
+  iBeam: { w: 10, h: 16, hotspot: { x: 4, y: 8 }, svg: "<svg width=\"9\" height=\"16\" viewBox=\"0 0 9 16\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"> <g clip-path=\"url(#clip0_1_90)\"> <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M4.01398 2V13.993H4.99998V2H4.01398Z\" fill=\"black\"/> <path fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M3 8V8.984H6V8H3Z\" fill=\"black\"/> <path d=\"M5 2.5C5.19256 2.04209 5.84981 1.33692 6.27645 1.10339C6.68002 0.880845 7.09513 0.691271 7.49178 0.591448C7.97723 0.467813 9 0.505362 9 0.505362\" stroke=\"black\"/> <path d=\"M4 2.5C3.82142 2.01964 3.08491 1.28308 2.75693 1.08271C2.36475 0.844812 1.92938 0.691096 1.52787 0.591364C1.03531 0.467843 0 0.505357 0 0.505357\" stroke=\"black\"/> <path d=\"M5 13.5C5.19256 13.9579 5.84981 14.6631 6.27645 14.8966C6.68002 15.1192 7.09513 15.3087 7.49178 15.4086C7.97723 15.5322 9 15.4946 9 15.4946\" stroke=\"black\"/> <path d=\"M4 13.5C3.82142 13.9804 3.08491 14.7169 2.75693 14.9173C2.36475 15.1552 1.92938 15.3089 1.52787 15.4086C1.03531 15.5322 0 15.4946 0 15.4946\" stroke=\"black\"/> </g> <defs> <clipPath id=\"clip0_1_90\"> <rect width=\"9\" height=\"16\" fill=\"white\"/> </clipPath> </defs> </svg>" },
+};

package/skill/scripts/finish.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+// finish.mjs — the LOCAL ending. A filmed take becomes a finished demo
+// recording on this machine, with no DemoBites account:
+//
+//   1. voice   — each narration line is spoken with YOUR ElevenLabs key,
+//                measured, and placed at its beat (never on top of the last line)
+//   2. camera  — the take's measured shots become zooms, by the rules in
+//                camera.mjs (the same laws the DemoBites cloud uses)
+//   3. cursor  — drawn from the recorded track, crisp at any zoom, with the
+//                press the studio uses
+//   4. frame   — the take sits centre stage on a background, rounded corners,
+//                a soft shadow, 16:9
+//
+// Usage: node finish.mjs <takeDir> [--out=<file.mp4>] [--no-voice]
+//                                  [--voice=<elevenlabs voice id>]
+//                                  [--background=midnight|mist|<#hex>]
+// Reads  <takeDir>/clean.mp4 + <takeDir>/manifest.demobites.json
+// Writes <takeDir>/local/{camera.json,voice.json,narration.wav,demo.mp4}
+// Key:   ELEVENLABS_API_KEY, or the file .recorder/elevenlabs.key. The key
+//        only ever travels to the ElevenLabs API.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn, execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { ffmpeg as ffmpegPath, ffprobe as ffprobePath, requireMediaTools } from "./media-tools.mjs";
+import { planShots, buildTimeline, buildSpringTimeline, FRAME_W, FRAME_H } from "./camera.mjs";
+import { CURSORS } from "./cursors.mjs";
+
+const args = process.argv.slice(2);
+const dir = args.find((a) => !a.startsWith("--"));
+const opt = (k, d) => { const a = args.find((x) => x.startsWith(`--${k}=`)); return a ? a.slice(k.length + 3) : d; };
+const has = (k) => args.includes(`--${k}`);
+if (!dir) { console.error("Usage: node finish.mjs <takeDir> [--out=file.mp4] [--no-voice] [--voice=id] [--background=midnight|mist|#hex]"); process.exit(2); }
+requireMediaTools();
+const FFMPEG = ffmpegPath(), FFPROBE = ffprobePath();
+
+const sharp = await (async () => {
+  try { return (await import("sharp")).default; } catch {}
+  try { return createRequire(path.join(process.env.SHARP_FROM || process.cwd(), "noop.js"))("sharp"); } catch {}
+  console.error("finish.mjs needs sharp (npm i sharp)."); process.exit(1);
+})();
+
+const cleanPath = path.join(dir, "clean.mp4");
+const manPath = path.join(dir, "manifest.demobites.json");
+for (const p of [cleanPath, manPath]) if (!fs.existsSync(p)) { console.error(`${p} not found — film and trim the take first.`); process.exit(1); }
+const man = JSON.parse(fs.readFileSync(manPath, "utf8"));
+const outDir = path.join(dir, "local");
+fs.mkdirSync(outDir, { recursive: true });
+const probe = (f) => parseFloat(execFileSync(FFPROBE, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", f]).toString());
+const videoDur = probe(cleanPath);
+const FPS = 30;
+const T0 = Date.now();
+const say = (s) => console.log(s);
+
+// ── 1. Voice ────────────────────────────────────────────────────────────
+const LINE_GAP = 0.25;       // silence between two lines, at least
+const OPENING_BEAT = 0.3;    // the first line never fires on frame one
+const lines = (man.steps ?? [])
+  .filter((s) => s.narration?.text)
+  .map((s, i) => ({ n: s.n, text: s.narration.text.trim(), anchor: Number(s.narration.t ?? s.t_start ?? 0) + (i === 0 ? OPENING_BEAT : 0), stepEnd: Number(s.t_end ?? 0) }));
+let voiceOn = !has("no-voice") && lines.length > 0;
+let KEY = process.env.ELEVENLABS_API_KEY || "";
+if (!KEY) { try { KEY = fs.readFileSync(path.resolve(".recorder", "elevenlabs.key"), "utf8").trim(); } catch {} }
+if (voiceOn && !KEY) { say("No ElevenLabs key (ELEVENLABS_API_KEY or .recorder/elevenlabs.key) — finishing silent, captions still written."); voiceOn = false; }
+let cfg = {};
+try { cfg = JSON.parse(fs.readFileSync(path.resolve(".recorder", "config.json"), "utf8")); } catch {}
+const VOICE = opt("voice", cfg.tts?.voice_id || "Xb7hH8MSUJpSbSDYk0k2"); // Alice (premade)
+const MODEL = cfg.tts?.model_id || "eleven_multilingual_v2";
+
+if (voiceOn) {
+  const cache = path.join(outDir, "voice");
+  fs.mkdirSync(cache, { recursive: true });
+  let chars = 0;
+  for (const l of lines) {
+    const id = crypto.createHash("sha1").update(`${VOICE}|${MODEL}|${l.text}`).digest("hex").slice(0, 16);
+    l.file = path.join(cache, `${id}.mp3`);
+    if (!fs.existsSync(l.file)) {
+      const res = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${VOICE}?output_format=mp3_44100_128`, {
+        method: "POST",
+        headers: { "xi-api-key": KEY, "Content-Type": "application/json" },
+        body: JSON.stringify({ text: l.text, model_id: MODEL, voice_settings: { stability: 0.5, similarity_boost: 0.75 } }),
+      });
+      if (!res.ok) { console.error(`ElevenLabs refused line ${l.n}: ${res.status} ${(await res.text()).slice(0, 200)}`); process.exit(1); }
+      fs.writeFileSync(l.file, Buffer.from(await res.arrayBuffer()));
+      chars += l.text.length;
+    }
+    l.dur = probe(l.file);
+  }
+  // Placement: at its beat, or right after the previous line — never on top.
+  let prevEnd = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    l.at = Math.max(l.anchor, prevEnd + (i ? LINE_GAP : 0));
+    l.end = l.at + l.dur;
+    prevEnd = l.end;
+    const next = lines[i + 1];
+    l.late = Math.max(0, l.at - l.anchor);
+    l.overrun = next ? Math.max(0, l.end + LINE_GAP - next.anchor) : 0;
+  }
+  say(`voice: ${lines.length} lines, ${chars} new characters sent to ElevenLabs (voice ${VOICE})`);
+  for (const l of lines) say(`  ${l.at.toFixed(2).padStart(6)}s  ${l.dur.toFixed(2)}s${l.late > 0.05 ? `  (+${l.late.toFixed(2)}s late)` : ""}${l.overrun > 0.05 ? `  ⚠ runs ${l.overrun.toFixed(2)}s into the next beat` : ""}  "${l.text}"`);
+  fs.writeFileSync(path.join(outDir, "voice.json"), JSON.stringify({ voice: VOICE, model: MODEL, lines }, null, 2));
+}
+// The video ends a breath after the last word — hold the last frame if needed.
+const lastWord = voiceOn ? Math.max(...lines.map((l) => l.end)) : 0;
+const outDur = Math.max(videoDur, lastWord + 0.8);
+const hold = Math.max(0, outDur - videoDur);
+
+// Captions beside the video, always (the silent version needs them most).
+{
+  const ts = (s) => { const ms = Math.round(s * 1000); const h = Math.floor(ms / 3600000), m = Math.floor(ms / 60000) % 60, sec = Math.floor(ms / 1000) % 60; return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(sec).padStart(2, "0")},${String(ms % 1000).padStart(3, "0")}`; };
+  const srt = lines.map((l, i) => { const a = l.at ?? l.anchor; const b = l.end ?? Math.min(outDur, a + Math.max(1.5, l.text.split(/\s+/).length / 2.6)); return `${i + 1}\n${ts(a)} --> ${ts(b)}\n${l.text}\n`; }).join("\n");
+  fs.writeFileSync(path.join(outDir, "captions.srt"), srt);
+}
+
+// ── 2. Camera ───────────────────────────────────────────────────────────
+const shots = planShots(man, videoDur, (m) => say(m));
+// --motion=spring (critically damped, velocity carries across chained moves)
+// or --motion=bezier (the DemoBites runtime today). --blur adds camera motion
+// blur: while the camera moves, each frame averages several sub-frame
+// cameras across the shutter, like a real camera's exposure.
+const MOTION = opt("motion", cfg.look?.motion || "bezier");
+const BLUR = has("blur") || cfg.look?.motionBlur === true;
+const SHUTTER = Number(opt("shutter", "0.5")); // in frames: 0.5 = a 180° shutter, like film
+const camAt = MOTION === "spring" ? buildSpringTimeline(shots, outDur) : buildTimeline(shots, outDur);
+fs.writeFileSync(path.join(outDir, "camera.json"), JSON.stringify(shots.map(({ start, end, cx, cy, factor, wide, how, label }) => ({ start: +start.toFixed(2), end: +end.toFixed(2), factor, cx: Math.round(cx), cy: Math.round(cy), wide: !!wide, how: how ?? (wide ? "wide" : "zoom"), label })), null, 2));
+say(`camera: ${shots.filter((s) => !s.wide).length} zooms, ${shots.filter((s) => s.wide).length} wide holds · motion ${MOTION}${BLUR ? ` + motion blur (shutter ${SHUTTER} frame)` : ""}`);
+for (const s of shots) say(`  ${s.start.toFixed(2).padStart(6)}–${s.end.toFixed(2).padEnd(6)} ${s.wide ? "wide " : `${s.factor.toFixed(2)}x`}  ${s.how ? `[${s.how}] ` : ""}${s.label ?? ""}`);
+
+// ── 3. Cursor ───────────────────────────────────────────────────────────
+const CURSOR_H = 0.02 * FRAME_W;   // studio "medium": 2% of the frame width
+// The studio grows the glyph with the zoom (it lives inside the zoomed
+// layer). Locally we let it grow, but not past this: at 3x a full-size hand
+// covers the button it is pressing.
+const CURSOR_MAX_GROWTH = 1.6;
+const PRESS_SCALE = 0.88, PRESS_IN = 0.3, PRESS_WINDOW = 0.4;
+const GAP_HOLD = 0.25, GAP_MOVE = 0.18; // cursor gap law: hold through a hole, then a 0.18 s move
+const events = (man.interactions?.mouseEvents ?? []).filter((e) => [e.x, e.y, e.time].every(Number.isFinite)).sort((a, b) => a.time - b.time);
+const clicks = events.filter((e) => e.type === "click");
+function cursorAt(t) {
+  if (!events.length) return null;
+  if (t <= events[0].time) return { x: events[0].x, y: events[0].y, kind: CURSORS[events[0].cursor] ? events[0].cursor : "arrow", press: 1 };
+  let i = events.length - 1;
+  for (let lo = 0, hi = events.length - 1; lo <= hi;) { const mid = (lo + hi) >> 1; if (events[mid].time <= t) { i = mid; lo = mid + 1; } else hi = mid - 1; }
+  const a = events[i], b = events[i + 1];
+  let x = a.x, y = a.y;
+  if (b) {
+    const gap = b.time - a.time;
+    const from = gap > GAP_HOLD ? b.time - GAP_MOVE : a.time;
+    const p = Math.min(1, Math.max(0, (t - from) / Math.max(1e-6, b.time - from)));
+    x = a.x + (b.x - a.x) * p; y = a.y + (b.y - a.y) * p;
+  }
+  const kind = CURSORS[a.cursor] ? a.cursor : "arrow";
+  let press = 1;
+  const c = [...clicks].reverse().find((k) => k.time <= t);
+  if (c && kind === "pointingHand") {
+    const f = (t - c.time) / PRESS_WINDOW;
+    if (c.press === "down") press = f < PRESS_IN ? 1 - (1 - PRESS_SCALE) * (f / PRESS_IN) : PRESS_SCALE;
+    else if (f < 1) press = f < PRESS_IN ? 1 - (1 - PRESS_SCALE) * (f / PRESS_IN) : 1 - (1 - PRESS_SCALE) * (1 - (f - PRESS_IN) / (1 - PRESS_IN));
+  }
+  return { x, y, kind, press };
+}
+const glyphCache = new Map();
+async function glyph(kind, h) {
+  const key = `${kind}@${Math.round(h * 2)}`;
+  if (glyphCache.has(key)) return glyphCache.get(key);
+  const g = CURSORS[kind];
+  const scale = h / g.h;
+  const W = Math.max(1, Math.round(g.w * scale)), H = Math.max(1, Math.round(g.h * scale));
+  const buf = await sharp(Buffer.from(g.svg), { density: Math.max(72, 72 * scale * 1.5) }).resize(W, H).ensureAlpha().raw().toBuffer();
+  const out = { buf, W, H, hx: g.hotspot.x * scale, hy: g.hotspot.y * scale };
+  glyphCache.set(key, out);
+  return out;
+}
+
+// ── 4. Frame: background, shadow, rounded mask ──────────────────────────
+// The take sits in a browser window: a bar on top (DemoBites geometry:
+// bar = 0.075 x content height, traffic lights 0.2 x bar, gap 8/14 of a dot,
+// left offset 40/1920 of the width), content below at its true 16:9.
+const CONTENT_W = 1600, CONTENT_H = 900;
+const showBar = !has("no-bar") && cfg.look?.browserBar !== false;
+const BAR_H = showBar ? Math.round(0.075 * CONTENT_H) : 0;
+const WIN_W = CONTENT_W, WIN_H = CONTENT_H + BAR_H, WIN_X = (FRAME_W - WIN_W) / 2, WIN_Y = Math.round((FRAME_H - WIN_H) / 2), RADIUS = 24;
+const pageUrl = (() => { try { const m = JSON.parse(fs.readFileSync(path.join(dir, "manifest.json"), "utf8")); const u = new URL(m.url); return (u.host + u.pathname).replace(/\/$/, ""); } catch { return ""; } })();
+const barUrl = opt("url", cfg.look?.url ?? pageUrl);
+const bgName = opt("background", cfg.look?.background || "midnight");
+const BACKGROUNDS = {
+  midnight: `<linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#10151c"/><stop offset="1" stop-color="#1d2b33"/></linearGradient><radialGradient id="r" cx="0.18" cy="0.12" r="0.7"><stop offset="0" stop-color="#17b0b8" stop-opacity="0.22"/><stop offset="1" stop-color="#17b0b8" stop-opacity="0"/></radialGradient>`,
+  mist: `<linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#eef1f3"/><stop offset="1" stop-color="#d9dfe3"/></linearGradient><radialGradient id="r" cx="0.2" cy="0.1" r="0.8"><stop offset="0" stop-color="#17b0b8" stop-opacity="0.16"/><stop offset="1" stop-color="#17b0b8" stop-opacity="0"/></radialGradient>`,
+};
+const bgSvg = /^#?[0-9a-f]{6}$/i.test(bgName)
+  ? `<svg xmlns="http://www.w3.org/2000/svg" width="${FRAME_W}" height="${FRAME_H}"><rect width="100%" height="100%" fill="#${bgName.replace("#", "")}"/></svg>`
+  : `<svg xmlns="http://www.w3.org/2000/svg" width="${FRAME_W}" height="${FRAME_H}"><defs>${BACKGROUNDS[bgName] ?? BACKGROUNDS.midnight}</defs><rect width="100%" height="100%" fill="url(#g)"/><rect width="100%" height="100%" fill="url(#r)"/></svg>`;
+const bgHex = (bgSvg.match(/stop-color="#([0-9a-f]{6})"/i) || bgSvg.match(/fill="#([0-9a-f]{6})"/i) || [, "10151c"])[1];
+const light = parseInt(bgHex.slice(0, 2), 16) * 0.299 + parseInt(bgHex.slice(2, 4), 16) * 0.587 + parseInt(bgHex.slice(4, 6), 16) * 0.114 > 128;
+const shadowSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${FRAME_W}" height="${FRAME_H}"><defs><filter id="s" x="-20%" y="-20%" width="140%" height="140%"><feGaussianBlur stdDeviation="${light ? 26 : 34}"/></filter></defs><rect x="${WIN_X}" y="${WIN_Y + (light ? 14 : 18)}" width="${WIN_W}" height="${WIN_H}" rx="${RADIUS}" fill="#000" fill-opacity="${light ? 0.22 : 0.55}" filter="url(#s)"/></svg>`;
+const maskSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${WIN_W}" height="${WIN_H}"><rect width="100%" height="100%" fill="#000"/><rect width="100%" height="100%" rx="${RADIUS}" fill="#fff"/></svg>`;
+const dot = 0.2 * BAR_H, gapDot = dot * 8 / 14, dotX = WIN_W * 40 / 1920 + dot / 2;
+const esc = (t) => String(t).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const pillW = Math.min(WIN_W * 0.42, Math.max(260, barUrl.length * 11 + 60));
+const barSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${WIN_W}" height="${BAR_H}"><rect width="100%" height="100%" fill="#eceef1"/><rect y="${BAR_H - 1}" width="100%" height="1" fill="#d7dbe0"/>` +
+  ["#ff5f57", "#febc2e", "#28c840"].map((c, i) => `<circle cx="${dotX + i * (dot + gapDot)}" cy="${BAR_H / 2}" r="${dot / 2}" fill="${c}"/>`).join("") +
+  (barUrl ? `<rect x="${(WIN_W - pillW) / 2}" y="${BAR_H * 0.22}" width="${pillW}" height="${BAR_H * 0.56}" rx="${BAR_H * 0.28}" fill="#ffffff"/><text x="${WIN_W / 2}" y="${BAR_H / 2 + 7}" font-family="-apple-system, Helvetica Neue, Arial, sans-serif" font-size="20" fill="#5b6470" text-anchor="middle">${esc(barUrl)}</text>` : "") + `</svg>`;
+const bgPng = path.join(outDir, "background.png"), shadowPng = path.join(outDir, "shadow.png"), maskPng = path.join(outDir, "mask.png"), barPng = path.join(outDir, "bar.png");
+await sharp(Buffer.from(bgSvg)).png().toFile(bgPng);
+await sharp(Buffer.from(shadowSvg)).png().toFile(shadowPng);
+await sharp(Buffer.from(maskSvg)).png().toFile(maskPng);
+if (showBar) await sharp(Buffer.from(barSvg)).png().toFile(barPng);
+
+// ── Narration track ─────────────────────────────────────────────────────
+const wavPath = path.join(outDir, "narration.wav");
+if (voiceOn) {
+  const ins = lines.flatMap((l) => ["-i", l.file]);
+  const chains = lines.map((l, i) => { const ms = Math.round(l.at * 1000); return `[${i}:a]aresample=48000,adelay=${ms}|${ms}[a${i}]`; }).join(";");
+  const mix = `${lines.map((_, i) => `[a${i}]`).join("")}amix=inputs=${lines.length}:normalize=0,apad=whole_dur=${outDur.toFixed(3)},loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000[aout]`;
+  execFileSync(FFMPEG, ["-y", "-loglevel", "error", ...ins, "-filter_complex", `${chains};${mix}`, "-map", "[aout]", "-t", outDur.toFixed(3), "-ac", "2", wavPath]);
+} else {
+  execFileSync(FFMPEG, ["-y", "-loglevel", "error", "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo", "-t", outDur.toFixed(3), wavPath]);
+}
+
+// ── Render: decode → camera + cursor per frame → frame + encode ─────────
+const outPath = path.resolve(opt("out", path.join(outDir, "demo.mp4")));
+const FRAME_BYTES = FRAME_W * FRAME_H * 3;
+const totalFrames = Math.round(outDur * FPS);
+const dec = spawn(FFMPEG, ["-loglevel", "error", "-i", cleanPath, "-vf", `fps=${FPS}${hold > 0 ? `,tpad=stop_mode=clone:stop_duration=${hold.toFixed(3)}` : ""}`, "-f", "rawvideo", "-pix_fmt", "rgb24", "pipe:1"], { stdio: ["ignore", "pipe", "inherit"] });
+const enc = spawn(FFMPEG, [
+  "-y", "-loglevel", "error",
+  "-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${FRAME_W}x${FRAME_H}`, "-r", String(FPS), "-i", "pipe:0",
+  "-loop", "1", "-framerate", String(FPS), "-i", bgPng,
+  "-i", shadowPng,
+  "-i", maskPng,
+  "-i", wavPath,
+  ...(showBar ? ["-loop", "1", "-framerate", String(FPS), "-i", barPng] : []),
+  "-filter_complex",
+  (showBar
+    ? `[0:v]format=rgb24,scale=${CONTENT_W}:${CONTENT_H}:flags=lanczos,format=rgba[c];[5:v]format=rgba[bar];[bar][c]vstack=inputs=2:shortest=1[v]`
+    : `[0:v]format=rgb24,scale=${CONTENT_W}:${CONTENT_H}:flags=lanczos,format=rgba[v]`) +
+  `;[3:v]format=gray[m];[v][m]alphamerge[va];[1:v][2:v]overlay=0:0[b1];[b1][va]overlay=${WIN_X}:${WIN_Y}:shortest=1,format=yuv420p[out]`,
+  "-map", "[out]", "-map", "4:a",
+  "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-r", String(FPS),
+  "-c:a", "aac", "-b:a", "160k", "-t", outDur.toFixed(3), "-movflags", "+faststart",
+  outPath,
+], { stdio: ["pipe", "inherit", "inherit"] });
+
+const viewport = (cam) => {
+  const f = cam.factor, vw = FRAME_W / f, vh = FRAME_H / f;
+  return { f, vw, vh, vx: Math.min(FRAME_W - vw, Math.max(0, cam.cx - vw / 2)), vy: Math.min(FRAME_H - vh, Math.max(0, cam.cy - vh / 2)) };
+};
+// The take seen through one camera position, as raw RGB at output size
+// (or at half size: fast sub-frames are blurred anyway).
+async function shoot(raw, v, half = false) {
+  if (v.f <= 1.001 && !half) return raw;
+  // Sub-pixel camera: cut a whole-pixel region around the viewport, scale
+  // it, then trim to the exact viewport at output resolution.
+  const { f, vx, vy, vw, vh } = v;
+  const ex = Math.floor(vx), ey = Math.floor(vy);
+  const ew = Math.min(FRAME_W - ex, Math.ceil(vx + vw) - ex + 1), eh = Math.min(FRAME_H - ey, Math.ceil(vy + vh) - ey + 1);
+  const q = half ? 0.5 : 1, OW = FRAME_W * q, OH = FRAME_H * q, fq = f * q;
+  const rw = Math.max(OW, Math.round(ew * fq)), rh = Math.max(OH, Math.round(eh * fq));
+  const ox = Math.min(rw - OW, Math.round((vx - ex) * fq)), oy = Math.min(rh - OH, Math.round((vy - ey) * fq));
+  return sharp(raw, { raw: { width: FRAME_W, height: FRAME_H, channels: 3 } })
+    .extract({ left: ex, top: ey, width: ew, height: eh }).resize(rw, rh, { kernel: half ? "cubic" : "lanczos3" })
+    .extract({ left: Math.max(0, ox), top: Math.max(0, oy), width: OW, height: OH }).raw().toBuffer();
+}
+// How far (output px) the picture slides between two camera positions:
+// the worst of the two viewport corners.
+function slide(a, b) {
+  let worst = 0;
+  for (const [px, py] of [[a.vx, a.vy], [a.vx + a.vw, a.vy + a.vh]]) {
+    const ax = (px - a.vx) * a.f, ay = (py - a.vy) * a.f, bx = (px - b.vx) * b.f, by = (py - b.vy) * b.f;
+    worst = Math.max(worst, Math.hypot(ax - bx, ay - by));
+  }
+  return worst;
+}
+let blurredFrames = 0;
+async function renderFrame(raw, n) {
+  const t = n / FPS;
+  const v = viewport(camAt(t));
+  let frame;
+  const half = (SHUTTER / FPS) / 2;
+  const a = BLUR ? viewport(camAt(t - half)) : v, b = BLUR ? viewport(camAt(t + half)) : v;
+  const travel = BLUR ? slide(a, b) : 0;
+  if (travel < 1.5) {
+    frame = await shoot(raw, v);
+  } else {
+    // One sub-frame every ~2 px of travel (no visible copies), 64 at most,
+    // averaged. Past 12 px of smear the sub-frames are shot at half size and
+    // the average is scaled back up: the blur is wider than what that loses.
+    const k = Math.min(64, Math.max(3, Math.ceil(travel / 2)));
+    const small = travel > 12;
+    const W = small ? FRAME_W / 2 : FRAME_W, H = small ? FRAME_H / 2 : FRAME_H;
+    const acc = new Uint16Array(W * H * 3);
+    for (let i = 0; i < k; i++) {
+      const sub = await shoot(raw, viewport(camAt(t - half + (2 * half * i) / (k - 1))), small);
+      for (let j = 0; j < acc.length; j++) acc[j] += sub[j];
+    }
+    const avg = Buffer.alloc(acc.length);
+    for (let j = 0; j < acc.length; j++) avg[j] = (acc[j] + (k >> 1)) / k;
+    frame = small ? await sharp(avg, { raw: { width: W, height: H, channels: 3 } }).resize(FRAME_W, FRAME_H, { kernel: "lanczos3" }).raw().toBuffer() : avg;
+    blurredFrames++;
+  }
+  const { f, vx, vy } = v;
+  const img = sharp(frame, { raw: { width: FRAME_W, height: FRAME_H, channels: 3 } });
+  const cur = cursorAt(t);
+  const layers = [];
+  if (cur) {
+    const g = await glyph(cur.kind, CURSOR_H * Math.min(f, CURSOR_MAX_GROWTH) * cur.press);
+    const left = Math.round((cur.x - vx) * f - g.hx), top = Math.round((cur.y - vy) * f - g.hy);
+    // Clip the glyph to the frame (a cursor at the edge is partly outside).
+    const cl = Math.max(0, -left), ct = Math.max(0, -top);
+    const cw = Math.min(g.W, FRAME_W - left) - cl, ch = Math.min(g.H, FRAME_H - top) - ct;
+    if (cw > 0 && ch > 0) {
+      const part = cl || ct || cw !== g.W || ch !== g.H
+        ? await sharp(g.buf, { raw: { width: g.W, height: g.H, channels: 4 } }).extract({ left: cl, top: ct, width: cw, height: ch }).raw().toBuffer()
+        : g.buf;
+      layers.push({ input: part, raw: { width: cw, height: ch, channels: 4 }, left: left + cl, top: top + ct });
+    }
+  }
+  return img.composite(layers).ensureAlpha().raw().toBuffer();
+}
+
+const IN_FLIGHT = 6;
+let chunks = [], have = 0, n = 0, written = 0;
+const queue = new Map();
+let flushing = Promise.resolve();
+const writeInOrder = async () => {
+  while (queue.has(written)) {
+    const buf = await queue.get(written);
+    queue.delete(written);
+    if (!enc.stdin.write(buf)) await new Promise((r) => enc.stdin.once("drain", r));
+    written++;
+    if (written % 150 === 0) process.stdout.write(`  rendered ${(written / FPS).toFixed(0)}s / ${outDur.toFixed(0)}s\n`);
+  }
+  if (queue.size < IN_FLIGHT) dec.stdout.resume();
+};
+dec.stdout.on("data", (chunk) => {
+  chunks.push(chunk); have += chunk.length;
+  while (have >= FRAME_BYTES) {
+    // One copy per frame: join exactly FRAME_BYTES, keep the remainder.
+    const all = Buffer.concat(chunks, have);
+    const frame = all.subarray(0, FRAME_BYTES);
+    const rest = all.subarray(FRAME_BYTES);
+    chunks = rest.length ? [rest] : []; have = rest.length;
+    if (n < totalFrames) queue.set(n, renderFrame(frame, n));
+    n++;
+  }
+  if (queue.size >= IN_FLIGHT) dec.stdout.pause();
+  flushing = flushing.then(writeInOrder);
+});
+await new Promise((res, rej) => { dec.on("close", (c) => (c === 0 ? res() : rej(new Error(`decoder exited ${c}`)))); });
+await flushing.then(writeInOrder);
+enc.stdin.end();
+await new Promise((res, rej) => enc.on("close", (c) => (c === 0 ? res() : rej(new Error(`encoder exited ${c}`)))));
+say(`✓ ${outPath}  (${probe(outPath).toFixed(1)}s, ${written} frames${BLUR ? `, ${blurredFrames} motion-blurred` : ""}, rendered in ${((Date.now() - T0) / 1000).toFixed(0)}s)`);