@open-take/compositor 0.1.1 → 0.2.0

package/src/render.ts

@@ -3,25 +3,42 @@
 //
 // Runs revideo headless (vite + chromium + ffmpeg). The renderer resolves
 // everything relative to process.cwd(), and injects `projectFile` verbatim
-// as an import specifier — so we chdir to the package root and use the
-// vite-root-absolute "/src/scene/project.ts" (a bare specifier hangs the
-// renderer forever; see spike-revideo/VERDICT.md).
+// as an import specifier — so the render runs from a directory laid out like
+// the package (src/ + public/) with the vite-root-absolute
+// "/src/scene/project.ts" (a bare specifier hangs the renderer forever; see
+// spike-revideo/VERDICT.md).
+//
+// That directory is a per-render SCRATCH COPY in the tmp dir, never the
+// installed package: a render used to write capture.mp4, .composition.json and
+// out-render/ into node_modules, which breaks read-only installs outright and
+// lets two renders read each other's composition. See prepareScratch.
 
 import { spawn } from "node:child_process";
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import {
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  symlink,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { renderVideo } from "@revideo/renderer";
-import { resolveFfmpeg } from "./ffmpeg";
+import { renderVideo } from "@open-take/revideo-renderer";
+import { repairBundledMediaPermissions, resolveFfmpeg } from "./ffmpeg";
 import { type PlanOpts, planComposition } from "./plan";
 import { type CaptureLog, type TakeComposition, motionBlurActive } from "./types";
 import { type CompositionIssue, formatIssues, validateComposition } from "./validate";
 
 // dist/index.js -> package root
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const PUBLIC_MP4 = resolve(PKG_ROOT, "public/capture.mp4");
-const COMP_JSON = resolve(PKG_ROOT, "src/scene/.composition.json");
-const RENDER_OUT = "out-render"; // relative to cwd (= PKG_ROOT at render time)
+const RENDER_OUT = "out-render"; // relative to cwd (= the scratch dir at render time)
 
 export type RenderTakeOpts = {
   /** input capture video (webm or mp4) */
@@ -35,10 +52,9 @@ export type RenderTakeOpts = {
   planOpts?: PlanOpts;
   logProgress?: boolean;
   /** Chrome binary for the headless render. Pass the same Chrome-for-Testing
-   *  the capture path uses so a single browser serves both stages (no second
-   *  download). revideo forwards this to puppeteer.launch's executablePath;
-   *  if unset, revideo's bundled puppeteer resolves its own. */
-  chromePath?: string;
+   *  the capture path uses so a single browser serves both stages. The
+   *  higher-level runtime resolves and supplies this to puppeteer-core. */
+  chromePath: string;
   /** the capture log, for cross-checking that an edited composition didn't
    *  drift an action's capture-locked tMs (see validateComposition). Optional —
    *  the structural checks run regardless. */
@@ -66,7 +82,9 @@ function run(cmd: string, args: string[]): Promise<void> {
   return new Promise((res, rej) => {
     const c = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
     let err = "";
-    c.stderr.on("data", (d) => (err += d));
+    c.stderr.on("data", (d) => {
+      err += d;
+    });
     c.on("error", rej);
     c.on("close", (code) => (code === 0 ? res() : rej(new Error(`${cmd} exited ${code}: ${err}`))));
   });
@@ -134,9 +152,113 @@ async function motionBlurMp4(
   ]);
 }
 
+// --- per-render scratch dir --------------------------------------------------
+
+/** The nearest node_modules above the installed package. Symlinked into the
+ *  scratch dir so the copied scene can still resolve `@revideo/*` — pnpm keeps
+ *  a node_modules beside the package, npm/yarn hoist it to the project root, so
+ *  walk up rather than assume either. */
+function hostNodeModules(): string | null {
+  let dir = PKG_ROOT;
+  for (;;) {
+    const candidate = join(dir, "node_modules");
+    if (existsSync(candidate)) return candidate;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/** The whole dependency tree in one directory, for vite's fs.allow. Vite serves
+ *  realpaths, and pnpm's are under `<root>/node_modules/.pnpm/…`, so the first
+ *  `node_modules` segment of a resolved dependency covers every layout. */
+function depsRoot(): string | null {
+  try {
+    const real = realpathSync(createRequire(import.meta.url).resolve("@revideo/core"));
+    const parts = real.split(sep);
+    const i = parts.indexOf("node_modules");
+    return i === -1 ? null : parts.slice(0, i + 1).join(sep);
+  } catch {
+    return null;
+  }
+}
+
+/** Copy a tree WITHOUT inheriting its permission bits. `fs.cp` preserves mode,
+ *  so copying out of a read-only install yields a read-only copy we then can't
+ *  write the composition into. Re-creating each file gives us the umask
+ *  default instead. The scene tree is a handful of small source files. */
+async function copyWritable(from: string, to: string): Promise<void> {
+  await mkdir(to, { recursive: true });
+  for (const e of await readdir(from, { withFileTypes: true })) {
+    const src = join(from, e.name);
+    const dst = join(to, e.name);
+    if (e.isDirectory()) await copyWritable(src, dst);
+    else if (e.isFile()) await writeFile(dst, await readFile(src));
+  }
+}
+
+async function cleanupScratch(dir: string): Promise<void> {
+  // Drop the node_modules LINK first and by name: recursive deletion around a
+  // link to the real dependency tree deserves an explicit safety boundary.
+  await unlink(join(dir, "node_modules")).catch(() => {});
+  if (!process.env.OPEN_TAKE_KEEP_SCRATCH) {
+    await rm(dir, { recursive: true, force: true });
+  } else {
+    process.stderr.write(`render scratch kept: ${dir}\n`);
+  }
+}
+
+/** Build the throwaway directory this render runs in: the package's `src/`
+ *  (the scene and everything it imports), this render's composition, the
+ *  normalised capture as vite's public asset, and a node_modules link. */
+async function prepareScratch(composition: TakeComposition, videoPath: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "open-take-render-"));
+  try {
+    await copyWritable(join(PKG_ROOT, "src"), join(dir, "src"));
+    await writeFile(
+      join(dir, "src", "scene", ".composition.json"),
+      JSON.stringify(composition, null, 2),
+    );
+    const nm = hostNodeModules();
+    if (!nm) throw new Error("render: could not locate node_modules for the scene's imports");
+    // "junction" is the Windows directory link that doesn't need admin rights;
+    // ignored on POSIX.
+    await symlink(nm, join(dir, "node_modules"), "junction");
+    // fps follows the composition: the render grid must match the source, or a
+    // hi-fps capture is decimated before the scene ever sees it.
+    await toMp4(videoPath, join(dir, "public", "capture.mp4"), composition.output.fps);
+    return dir;
+  } catch (error) {
+    await cleanupScratch(dir);
+    throw error;
+  }
+}
+
+// process.chdir is process-global, so two renders in one process cannot run
+// concurrently no matter how isolated their directories are — the scratch dirs
+// remove the shared STATE, this removes the interleaving. (True parallelism
+// needs the renderer off cwd, or one child process per render.)
+let renderQueue: Promise<unknown> = Promise.resolve();
+
 export async function renderTake(
   opts: RenderTakeOpts,
 ): Promise<{ mp4Path: string; compositionPath: string }> {
+  const run = renderQueue.then(
+    () => renderTakeExclusive(opts),
+    () => renderTakeExclusive(opts),
+  );
+  renderQueue = run.catch(() => {});
+  return run;
+}
+
+async function renderTakeExclusive(
+  opts: RenderTakeOpts,
+): Promise<{ mp4Path: string; compositionPath: string }> {
+  if (!opts.chromePath) {
+    throw new Error(
+      "renderTake: `chromePath` is required; use @open-take/runtime to resolve managed Chrome automatically",
+    );
+  }
   const composition: TakeComposition =
     opts.composition ??
     planComposition(
@@ -164,74 +286,86 @@ export async function renderTake(
       );
   }
 
-  // 1. serve the capture as /capture.mp4 (vite public dir under PKG_ROOT)
-  await toMp4(opts.videoPath, PUBLIC_MP4, composition.output.fps);
-
-  // 2. hand the composition to the scene (static import, rewritten per render)
-  await mkdir(dirname(COMP_JSON), { recursive: true });
-  await writeFile(COMP_JSON, JSON.stringify(composition, null, 2));
+  // Revideo spawns its bundled ffprobe directly. Repair installer permissions
+  // here so published consumers are protected even though they do not run the
+  // monorepo root's postinstall script.
+  await repairBundledMediaPermissions();
 
-  // 3. render headless, with cwd pinned to the package root.
-  // revideo's @revideo/telemetry phones home to PostHog by default; this is an
-  // all-local tool, so default it OFF (an explicit user-set value still wins).
-  if (process.env.DISABLE_TELEMETRY === undefined) process.env.DISABLE_TELEMETRY = "true";
-  const prevCwd = process.cwd();
-  process.chdir(PKG_ROOT);
-  let produced: string;
+  // 1. lay out this render's own directory (scene + composition + capture)
+  const scratch = await prepareScratch(composition, opts.videoPath);
+  const deps = depsRoot();
   try {
-    produced = await renderVideo({
-      projectFile: "/src/scene/project.ts",
-      settings: {
-        outFile: "take.mp4",
-        outDir: RENDER_OUT,
-        workers: 1,
-        ...(opts.rangeSec ? { projectSettings: { range: opts.rangeSec } } : {}),
-        logProgress: opts.logProgress ?? false,
-        ...(opts.onProgress
-          ? { progressCallback: (_worker: number, progress: number) => opts.onProgress!(progress) }
-          : {}),
-        // Reuse the capture-managed Chrome-for-Testing when given (one browser
-        // for both stages); else let revideo's puppeteer resolve its own.
-        puppeteer: {
-          // --password-store/--use-mock-keychain: never touch the OS keychain, so
-          // macOS doesn't pop a "Chrome wants to use Chromium Safe Storage" prompt
-          // mid-render (matches the capture launch in runtime/cdp.ts).
-          args: [
-            "--no-sandbox",
-            "--disable-setuid-sandbox",
-            "--password-store=basic",
-            "--use-mock-keychain",
-          ],
-          ...(opts.chromePath ? { executablePath: opts.chromePath } : {}),
+    // 2. render headless, with cwd pinned to the scratch dir.
+    // revideo's @revideo/telemetry phones home to PostHog by default; this is an
+    // all-local tool, so default it OFF (an explicit user-set value still wins).
+    if (process.env.DISABLE_TELEMETRY === undefined) process.env.DISABLE_TELEMETRY = "true";
+    const prevCwd = process.cwd();
+    process.chdir(scratch);
+    let produced: string;
+    try {
+      produced = await renderVideo({
+        projectFile: "/src/scene/project.ts",
+        settings: {
+          outFile: "take.mp4",
+          outDir: RENDER_OUT,
+          workers: 1,
+          ...(opts.rangeSec ? { projectSettings: { range: opts.rangeSec } } : {}),
+          logProgress: opts.logProgress ?? false,
+          ...(opts.onProgress
+            ? {
+                progressCallback: (_worker: number, progress: number) => opts.onProgress!(progress),
+              }
+            : {}),
+          // vite's dev server refuses to serve outside its root, and its root is
+          // now a tmp dir — so allow the dependency tree the scene imports
+          // through the node_modules link (vite resolves it to the realpath).
+          viteConfig: {
+            server: { fs: { allow: [scratch, ...(deps ? [deps] : [])] } },
+          },
+          // Reuse the capture-managed Chrome-for-Testing for both stages.
+          puppeteer: {
+            // --password-store/--use-mock-keychain: never touch the OS keychain, so
+            // macOS doesn't pop a "Chrome wants to use Chromium Safe Storage" prompt
+            // mid-render (matches the capture launch in runtime/cdp.ts).
+            args: [
+              "--no-sandbox",
+              "--disable-setuid-sandbox",
+              "--password-store=basic",
+              "--use-mock-keychain",
+            ],
+            executablePath: opts.chromePath,
+          },
         },
-      },
-    });
-  } finally {
-    process.chdir(prevCwd);
-  }
+      });
+    } finally {
+      process.chdir(prevCwd);
+    }
 
-  // 4. deliver mp4 (motion-blur down from fps·samples if configured) + the
-  //    editable composition. OFF ⇒ a plain copy (byte-identical to before).
-  await mkdir(dirname(resolve(opts.outPath)), { recursive: true });
-  const producedAbs = resolve(PKG_ROOT, produced);
-  if (motionBlurActive(composition.motionBlur)) {
-    await motionBlurMp4(
-      producedAbs,
-      resolve(opts.outPath),
-      composition.output.fps,
-      composition.motionBlur.samples,
-      composition.motionBlur.shutter,
-    );
-  } else {
-    await copyFile(producedAbs, resolve(opts.outPath));
-  }
-  const compositionPath = resolve(opts.outPath).replace(/\.mp4$/i, "") + ".composition.json";
-  if (opts.writeCompositionSibling !== false) {
-    // strip the render-time review decoration — the editable artifact is the
-    // clean composition, never the badged/watermarked variant of it.
-    const { review: _review, ...persisted } = composition;
-    await writeFile(compositionPath, JSON.stringify(persisted, null, 2));
-  }
+    // 3. deliver mp4 (motion-blur down from fps·samples if configured) + the
+    //    editable composition. OFF ⇒ a plain copy (byte-identical to before).
+    await mkdir(dirname(resolve(opts.outPath)), { recursive: true });
+    const producedAbs = resolve(scratch, produced);
+    if (motionBlurActive(composition.motionBlur)) {
+      await motionBlurMp4(
+        producedAbs,
+        resolve(opts.outPath),
+        composition.output.fps,
+        composition.motionBlur.samples,
+        composition.motionBlur.shutter,
+      );
+    } else {
+      await copyFile(producedAbs, resolve(opts.outPath));
+    }
+    const compositionPath = resolve(opts.outPath).replace(/\.mp4$/i, "") + ".composition.json";
+    if (opts.writeCompositionSibling !== false) {
+      // strip the render-time review decoration — the editable artifact is the
+      // clean composition, never the badged/watermarked variant of it.
+      const { review: _review, ...persisted } = composition;
+      await writeFile(compositionPath, JSON.stringify(persisted, null, 2));
+    }
 
-  return { mp4Path: resolve(opts.outPath), compositionPath };
+    return { mp4Path: resolve(opts.outPath), compositionPath };
+  } finally {
+    await cleanupScratch(scratch);
+  }
 }

package/src/scene/scene.tsx

@@ -4,17 +4,11 @@
 import { makeScene2D, Rect, Video, Line, Circle, Node, Gradient, Txt } from "@revideo/2d";
 import { createSignal, tween, linear } from "@revideo/core";
 import {
-  buildStageKeyframes,
+  stageCamera,
   buildLegs,
   cursorPos,
   isDragging,
-  keyvalN,
-  keyvalP,
-  clampCenter,
-  stageEasing,
-  panEasing,
   gradientEndpoints,
-  restStageScale,
   smoother,
 } from "../math";
 import comp from "./.composition.json";
@@ -23,9 +17,9 @@ const vW = comp.source.videoWidth,
   vH = comp.source.videoHeight;
 const oW = comp.output.width,
   oH = comp.output.height;
-const stage = buildStageKeyframes(comp);
+const cam = stageCamera(comp);
 const legs = buildLegs(comp);
-const rest = restStageScale(vW, vH, oW, oH, comp.framing.insetFrac);
+const rest = cam.rest;
 
 // video-px -> stage-local coords (stage local origin = video centre)
 const lx = (px) => px - vW / 2;
@@ -46,12 +40,10 @@ const CURSOR = [
 export default makeScene2D("take", function* (view) {
   const t = createSignal(0);
 
-  // zoom/pan stage easing (scale + center in unison): spring → bezier → smoother
-  const scaleEase = stageEasing(comp.cursor); // zoom-IN: spring allowed
-  const panEase = panEasing(comp.cursor); // zoom-OUT scale + centre: smooth bezier
-  // spring in / bezier out (smooth settle); Math.max(rest,…) is a floor. Mirrors derive.ts.
-  const scaleAt = () => Math.max(rest, keyvalN(t(), stage.z, scaleEase, panEase));
-  const centerAt = () => clampCenter(keyvalP(t(), stage.c, panEase), scaleAt(), vW, vH, oW, oH);
+  // The camera: ONE eased viewport rect (centre + size in lockstep, targets
+  // pre-clamped at build) — see math.ts stageCamera. Mirrors the editor preview.
+  const scaleAt = () => cam.at(t()).scale;
+  const centerAt = () => cam.at(t()).center;
 
   // Composition camera: ONE camera zooms the WHOLE
   // composition (backdrop + the inset framed screen) together. At rest the
@@ -123,7 +115,7 @@ export default makeScene2D("take", function* (view) {
           spatial click point, so they get no ripple) */}
         {comp.events
           .filter((e) => e.kind !== "scroll" && e.kind !== "press")
-          .map((e) => {
+          .map((e, index) => {
             const ms = comp.cursor.rippleMs / 1000;
             const prog = () => {
               const dt = t() - e.tMs / 1000;
@@ -131,6 +123,7 @@ export default makeScene2D("take", function* (view) {
             };
             return (
               <Circle
+                key={`${e.kind}-${e.tMs}-${index}`}
                 position={[lx(e.point.x), ly(e.point.y)]}
                 size={() => {
                   const p = prog();
@@ -227,5 +220,5 @@ export default makeScene2D("take", function* (view) {
     if (review.label) view.add(pill(review.label, 1, true));
   }
 
-  yield* tween(stage.T, (v) => t(v * stage.T), linear);
+  yield* tween(cam.T, (v) => t(v * cam.T), linear);
 });

package/src/scene/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  // The scene is NOT compiled by tsc (the package tsconfig excludes src/scene);
+  // it is compiled by revideo's vite at render time. But vite's dependency
+  // scanner still reads the nearest tsconfig to learn the JSX settings, and the
+  // repo base sets `jsx: react-jsx` with no import source (for apps/editor,
+  // which really is React). Without this override the scanner tries to resolve
+  // `react/jsx-dev-runtime` from scene.tsx, fails, and skips dependency
+  // pre-bundling with a scary warning on every render. The scene's JSX is
+  // revideo's, not React's.
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@revideo/2d/lib"
+  }
+}

package/src/types.ts

@@ -25,8 +25,22 @@ export type CaptureEventBase = {
   /** selector / note, kept for editability */
   sel?: string;
   note?: string;
-  /** selective-zoom intent from the plan (default auto = heuristic) */
+  /** selective-zoom intent from the plan. Absent/"auto" ⇒ the camera director
+   *  decides from the ground-truth log; "always"/"never" hard-override it (and
+   *  cut the beat out of any cluster — an override is a segment boundary). */
   zoom?: ZoomIntent;
+  /** CAPTURE-DERIVED (frame-diff / mutation pass — the `effectBox` seam): the
+   *  region that actually CHANGED after the action, viewport CSS px. The
+   *  director frames THIS over `box` when present — a `type`'s result region, or
+   *  a payoff that lands somewhere other than where you clicked. Absent ⇒ the
+   *  director shapes an ROI from `box`/kind instead. */
+  effectBox?: BBox;
+  /** CAPTURE-DERIVED (same pass): fraction of the frame that changed after the
+   *  action, 0..1. ≥ camera.pullOutCoverage ⇒ the action repainted most of the
+   *  frame (nav / global restyle) ⇒ pull out to full view. Absent ⇒ the pull-out
+   *  branch is skipped (the director can't tell nav from popover on bbox alone —
+   *  it says so in the beat's `reason`). */
+  changeCoverage?: number;
 };
 
 /** A click (or a type's focus-click): an instantaneous action at a point. */
@@ -187,23 +201,27 @@ export type CursorConfig = {
   rippleMs: number;
   /** ms to hold a zoom after the action settles, before zooming back out */
   holdMs: number;
-  /** ms for the zoom-OUT ramp (back to rest) */
+  /** ms for a zoom-OUT / pull-out ramp (to rest OR to any wider framing).
+   *  Measured on a reference export: the pull-out is ~1.8× slower than the
+   *  punch-in (their zoom-out spring ω≈5.2 rad/s ⇒ ~1340ms of critically-damped
+   *  settle) — a slow, soft release reads premium; a fast one reads like a
+   *  flinch. */
   zoomOutMs: number;
   /** ms for the zoom-IN ramp (into a target). Decoupled from travelMs so the
-   *  zoom can be slower/gentler than the cursor (a cinematic ~1s zoom). */
+   *  zoom can be slower/gentler than the cursor. Measured reference punch-in spring
+   *  ω≈9.4 rad/s ⇒ ~730ms. */
   zoomInMs: number;
-  /** Easing for the zoom/pan stage ramps (scale + center together), as
-   *  cubic-bezier control points. Absent ⇒ symmetric smootherstep — whose broad
-   *  near-constant-velocity middle reads a bit linear, esp. on the zoom-OUT
-   *  settle. A decel-biased curve gives a softer landing into rest. */
+  /** Optional cubic-bezier easing for the camera-rect ramps (centre + size in
+   *  lockstep — see math.ts stageCamera). Absent ⇒ the default critically-
+   *  damped spring (the measured reference curve). Set this only to force a
+   *  bezier feel; `zoomSpring` wins over it when both are set. */
   zoomEase?: [number, number, number, number];
-  /** Spring easing for the zoom/pan stage ramps, as a `bounce` amount ∈ [0,~0.6):
-   *  0 = critically damped (a soft physical ease-out), higher = more overshoot/
-   *  snap (the "silky" settle a premium screen-recorder has; ~0.06 for zoom). When
-   *  set, this WINS over `zoomEase` (see math.ts stageEasing). Absent ⇒ use
-   *  `zoomEase`/smootherstep. The segment duration stays zoomInMs/zoomOutMs;
-   *  bounce only shapes the curve. NB: large bounce can undershoot rest on the
-   *  zoom-OUT (momentary backdrop dead-space) — keep it small for zoom. */
+  /** Spring easing for the camera-rect ramps, as a `bounce` amount ∈ [0,~0.6):
+   *  0 = critically damped (the measured reference zoom curve — also the
+   *  default when neither zoomSpring nor zoomEase is set), higher = more
+   *  overshoot/snap. The segment duration stays zoomInMs/zoomOutMs; bounce only
+   *  shapes the curve. Bounce > 0 overshoots the RECT (a touch past the target
+   *  frame, then settle) — keep it small. */
   zoomSpring?: number;
   /** ms to delay the synthetic cursor along a DRAG stroke, compensating for the
    *  capture pipeline latency: the captured ink appears ~this long after the pen
@@ -253,6 +271,53 @@ export type ReviewDecor = {
   label?: string;
 };
 
+/** The auto-camera director's tuning. ON by default (a plan that specifies no
+ *  zoom must still come out with sensible framing — the whole point). The
+ *  numbers are the FEEL knobs; judge them by eye on a rendered clip, not on
+ *  paper. `enabled: false` is the clean escape hatch: the director doesn't run
+ *  and ONLY explicit `zoom: "always"/"never"` produce zoom (auto/absent hold
+ *  full view). There is no legacy per-event heuristic to fall back to. */
+export type CameraConfig = {
+  enabled: boolean;
+  /** an ROI fills this fraction of the frame when framed (bigger ⇒ tighter). */
+  fillFrac: number;
+  /** hard ceiling on scale. NOT the main lever — ROI SIZE drives the actual
+   *  scale (a big type-ROI lands medium, a tiny icon lands tight); this just
+   *  stops a pinpoint ROI zooming past legibility. */
+  maxScale: number;
+  /** a punch that can't stay on screen this long is dropped to full view (a
+   *  sub-second punch reads as a flinch). Enforced AFTER hard breaks — the hold
+   *  extends into the gap before the next break, never merges across one. */
+  minHoldMs: number;
+  /** a scale below this isn't worth a distinct frame: a single beat that fits
+   *  under it holds full view, and a coalesced cluster whose UNION falls under
+   *  it splits instead (the two are "different regions" → chain/pull, not hold). */
+  minZoomScale: number;
+  /** gap between two actions greater than this ⇒ they cannot share a frame. */
+  coalesceWindowMs: number;
+  /** two ROIs whose centres are closer than this (fraction of video width) MAY
+   *  coalesce into one shared, held frame — the "cluster" (a thumbnail rail, a
+   *  toolbar). Farther apart ⇒ a re-frame (progressive/deeper), not a hold. */
+  travelThreshold: number;
+  /** changeCoverage ≥ this ⇒ the action repainted most of the frame (nav /
+   *  global) ⇒ pull out to full view. The nav-vs-popover divider — the one knob
+   *  to tune by eye on real captures (frame-diff pass populates the input). */
+  pullOutCoverage: number;
+};
+
+// Defaults tuned as a STARTING point — every number here is meant to be judged
+// on a rendered clip and A/B'd one at a time, not signed off on paper.
+export const DEFAULT_CAMERA: CameraConfig = {
+  enabled: true,
+  fillFrac: 0.6,
+  maxScale: 2.4,
+  minHoldMs: 1200,
+  minZoomScale: 1.25,
+  coalesceWindowMs: 900,
+  travelThreshold: 0.18,
+  pullOutCoverage: 0.55,
+};
+
 export type TakeComposition = {
   output: { width: number; height: number; fps: number };
   source: {
@@ -321,15 +386,13 @@ export const DEFAULT_CURSOR: CursorConfig = {
   arcMax: 24,
   rippleMs: 450,
   holdMs: 1100,
-  // Gentle, cinematic zoom (a ~1s ramp reads as premium); our
-  // old 600ms tied-to-travel zoom felt snappy/mechanical by comparison.
-  zoomOutMs: 800,
-  zoomInMs: 760,
-  // Zoom/pan stage easing. Same decel-biased curve as the cursor — symmetric
-  // smootherstep (the fallback) has a broad near-constant-velocity middle that
-  // reads a touch linear, especially as the zoom-OUT settles back to rest; this
-  // gives a soft landing into rest. Applied to scale + center together.
-  zoomEase: [0.3, 0.0, 0.2, 1.0],
+  // Camera ramp durations, measured off a reference export by frame-
+  // tracking (see math.ts springEase): punch-in spring ω≈9.4 rad/s ≈ 730ms,
+  // pull-out ω≈5.2 ≈ 1340ms. The slow soft release is half the premium feel.
+  // No zoomEase/zoomSpring set ⇒ stageEasing falls to springEase(0), the
+  // critically-damped spring that IS the measured SS curve over these windows.
+  zoomOutMs: 1340,
+  zoomInMs: 730,
   // The captured ink trails the pen by the screencast/encode pipeline latency τ;
   // delay the cursor by τ so its tip rides the ink front. Set to τ EXACTLY and
   // the cursor locks to the ink at ALL stroke speeds (both are the same time-

package/src/validate.ts

@@ -187,6 +187,24 @@ export function validateComposition(
     }
   }
 
+  // camera-rect spring: bounce shapes the ONE ease driving centre+size, so an
+  // out-of-range value corrupts every camera move (see math.ts springEase).
+  const spring = comp.cursor.zoomSpring;
+  if (spring != null) {
+    if (!(spring >= 0 && spring < 0.6))
+      err(
+        "cursor.zoomSpring",
+        `zoomSpring ${spring} outside [0, 0.6)`,
+        "0 = critically damped (the default feel); keep bounce ≤ 0.3",
+      );
+    else if (spring > 0.3)
+      warn(
+        "cursor.zoomSpring",
+        `zoomSpring ${spring} is a lot of bounce — the rect overshoot can flash backdrop at edge-flush targets and over-zoom tight punches`,
+        "keep ≤ 0.3 (the editor slider's max) unless the flash is wanted",
+      );
+  }
+
   // tail: the composition must outlast the last action (+ a little settle)
   if (comp.durationMs < lastEnd)
     err(