@open-take/compositor 0.1.2 → 0.2.0

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
@@ -228,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/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(