@open-take/compositor 0.1.0

package/src/types.ts

@@ -0,0 +1,349 @@
+// The editable take composition — the source of truth. The agent (or a
+// human) edits THIS, and the revideo scene renders it deterministically.
+// All spatial fields are in VIDEO-pixel space (capture coords mapped
+// through viewport→video scaling), so the scene works in one coordinate
+// system.
+
+export type Pt = { x: number; y: number };
+export type BBox = { x: number; y: number; w: number; h: number };
+
+// --- capture input (the ground-truth event log) -----------------------
+
+/** Editorial zoom intent for an action (set by the planner/agent). */
+export type ZoomIntent = "auto" | "never" | "always";
+
+/** Fields common to every captured action. `x,y` is the anchor / start
+ *  point (cursor target), viewport CSS px. */
+export type CaptureEventBase = {
+  /** anchor point (click target / field / drag start), viewport CSS px */
+  x: number;
+  y: number;
+  /** element bounding box, viewport CSS px — the ground-truth edge */
+  box?: BBox;
+  /** ms from recording start (when the cursor arrives / action begins) */
+  tMs: number;
+  /** selector / note, kept for editability */
+  sel?: string;
+  note?: string;
+  /** selective-zoom intent from the plan (default auto = heuristic) */
+  zoom?: ZoomIntent;
+};
+
+/** A click (or a type's focus-click): an instantaneous action at a point. */
+export type CaptureClick = CaptureEventBase & { kind?: "click" };
+
+/** Typing into a focused field: the cursor parks and the zoom holds for
+ *  `durationMs` while the text appears in the recording. */
+export type CaptureType = CaptureEventBase & {
+  kind: "type";
+  /** what was typed (editability) */
+  text: string;
+  /** ms the typing occupies on screen (ground-truth wall time) */
+  durationMs: number;
+};
+
+/** A drag: a path from the anchor (`x,y`) to `to`, optionally via `path`,
+ *  with the button held for `durationMs`. */
+export type CaptureDrag = CaptureEventBase & {
+  kind: "drag";
+  /** drag end point, viewport CSS px */
+  to: { x: number; y: number };
+  /** full polyline incl. ends, viewport CSS px (freehand strokes) */
+  path?: { x: number; y: number }[];
+  /** ms the drag occupies on screen (ground-truth wall time) */
+  durationMs: number;
+  /** how the stroke was paced and BAKED into the ink: "smooth" (accel-in /
+   *  decel-out — a natural hand-draw) or "linear" (constant speed). The
+   *  compositor cursor must replay the SAME easing to stay locked to the ink.
+   *  Absent ⇒ linear (legacy captures). */
+  ease?: "linear" | "smooth";
+};
+
+/** A scroll: the content pans for `durationMs`. The cursor holds (no travel),
+ *  full-view (no zoom). `dy` is the signed pixels scrolled (editability). */
+export type CaptureScroll = CaptureEventBase & {
+  kind: "scroll";
+  /** signed pixels scrolled (positive = down) */
+  dy: number;
+  /** ms the scroll occupies on screen (ground-truth wall time) */
+  durationMs: number;
+};
+
+/** A hover: the cursor travels to `x,y` and dwells for `durationMs` so a
+ *  tooltip / menu / hover-state reveals. Like a click that doesn't click. */
+export type CaptureHover = CaptureEventBase & {
+  kind: "hover";
+  /** ms the dwell occupies on screen (ground-truth wall time) */
+  durationMs: number;
+};
+
+/** A key press / shortcut: keyboard-driven, so the cursor holds (no travel).
+ *  Holds for `durationMs` while the effect plays out; if a reveal element was
+ *  located, `box` carries its bbox so the zoom can frame it. */
+export type CapturePress = CaptureEventBase & {
+  kind: "press";
+  /** the chord pressed, e.g. "Enter" / "Meta+k" (editability) */
+  keys: string;
+  /** ms the hold occupies on screen (ground-truth wall time) */
+  durationMs: number;
+};
+
+export type CaptureEvent =
+  | CaptureClick
+  | CaptureType
+  | CaptureDrag
+  | CaptureScroll
+  | CaptureHover
+  | CapturePress;
+
+export type CaptureLog = {
+  video: { width: number; height: number; fps?: number | string; durationS?: number };
+  viewport: { w: number; h: number };
+  start?: { x: number; y: number };
+  /** the ordered ground-truth actions (click / type / drag) */
+  events: CaptureEvent[];
+  tEndMs?: number;
+};
+
+// --- the composition (editable) ----------------------------------------
+
+export type ZoomDecision = {
+  /** selective: not every action zooms. Edit this to tune/remove. */
+  enabled: boolean;
+  /** absolute stage scale to reach (bbox-fit, capped) */
+  scale: number;
+  /** video-px point to frame (bbox center), pre-clamp */
+  center: Pt;
+  /** when the zoom-in begins (ms) */
+  inAtMs: number;
+  /** Optional "glide": a slow camera drift WHILE the zoom is held, as a velocity
+   *  in video-px per second {x,y}. The held centre pans from `center` by
+   *  `glide · holdSeconds` across the hold window (then the next beat ramps from
+   *  there / it zooms out from there). Adds life vs a dead-static hold (Screen
+   *  Studio's glide). Absent/0 ⇒ a still hold. Clamped to the video at read time,
+   *  so a drift just stops at the edge. Keep it gentle (tens of px/s). */
+  glide?: Pt;
+  /** why this decision (for the human/agent reading the composition) */
+  reason: string;
+};
+
+export type CompEvent = {
+  kind: "click" | "type" | "drag" | "scroll" | "hover" | "press";
+  tMs: number;
+  /** anchor point (click / focus / drag start / hover) in video-px. For a
+   *  scroll/press the cursor does not move; this is its resting point. */
+  point: Pt;
+  /** element bbox in video-px (if known) */
+  bbox?: BBox;
+  label?: string;
+  zoom: ZoomDecision;
+  /** how long the action plays out after `tMs` (type/drag/scroll/hover/press);
+   *  0 for a click. The cursor parks and the zoom holds for this long. */
+  durationMs?: number;
+  /** typed text (kind=type), for editability */
+  text?: string;
+  /** chord pressed (kind=press), for editability */
+  keys?: string;
+  /** drag end point, video-px (kind=drag) */
+  to?: Pt;
+  /** drag polyline incl. ends, video-px (kind=drag) — the cursor path */
+  path?: Pt[];
+  /** drag stroke easing baked into the ink (kind=drag): "smooth" or "linear".
+   *  The cursor replays it so it stays locked to the ink. Absent ⇒ linear. */
+  ease?: "linear" | "smooth";
+};
+
+export type FramingConfig = {
+  /** video occupies this fraction of the frame at rest (inset for the backdrop) */
+  insetFrac: number;
+  cornerRadius: number;
+  shadow: { color: string; blur: number; offset: Pt };
+  /** backdrop behind the framed video. `type` defaults to "gradient" (from→to);
+   *  "solid" fills `from` only. `angle` (deg, CSS-like: 0 = upward) rotates the
+   *  gradient; absent ⇒ the legacy top-left→bottom-right diagonal (pixel-identical). */
+  background: { from: string; to: string; type?: "gradient" | "solid"; angle?: number };
+};
+
+export type CursorConfig = {
+  /** Fallback travel duration (ms) when `travelWidthsPerSec` is unset/0. A FIXED
+   *  duration makes cursor speed scale with distance (short=slow, long=fast),
+   *  which reads inconsistent; prefer the distance-aware speed below. */
+  travelMs: number;
+  /** Distance-aware travel speed, as a fraction of the source video WIDTH per
+   *  second (resolution-independent). A travel leg's duration is
+   *  `clamp(distance / (widthsPerSec·videoWidth), travelMinMs, travelMaxMs)`, so
+   *  the cursor holds a roughly CONSTANT on-screen speed regardless of distance —
+   *  the premium-recorder feel (measured ~0.30 widths/s on the reference). Set 0
+   *  to fall back to the fixed `travelMs`. */
+  travelWidthsPerSec: number;
+  /** Floor for a distance-aware travel (ms) so short hops aren't an instant snap. */
+  travelMinMs: number;
+  /** Ceiling for a distance-aware travel (ms) so a full-width jump stays a glide,
+   *  not a multi-second crawl. */
+  travelMaxMs: number;
+  scale: number;
+  arcFrac: number;
+  arcMax: number;
+  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) */
+  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). */
+  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. */
+  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. */
+  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
+   *  actually moved, so without the delay the (exact-time) cursor leads the ink.
+   *  Tune so the cursor tip sits on the ink front mid-stroke. */
+  dragLagMs: number;
+  /** easing for a travel move, as cubic-bezier control points [x1,y1,x2,y2].
+   *  Default is a symmetric ease-in-out — measured from a reference recording, whose
+   *  cursor accelerates and decelerates evenly (a slow start, fast middle, soft
+   *  landing). Drag strokes ignore this (they ease the stroke in lockstep with
+   *  the captured ink — see math.ts). */
+  travelEase: [number, number, number, number];
+};
+
+/** Camera motion blur (temporal supersampling — what a real shutter does). The
+ *  renderer samples the composition camera at `samples` sub-times within each
+ *  output frame and averages them, so a fast zoom/pan/cursor smears in the
+ *  motion direction (a camera/shutter motion blur). It smears the
+ *  backdrop-reveal on a zoom-OUT into a soft gradient instead of a hard
+ *  single-frame pop. The captured video's frames repeat across sub-samples, so
+ *  the recording's own content is NOT blurred — only the camera move + cursor. */
+export type MotionBlurConfig = {
+  /** sub-frames sampled per output frame. 1 ⇒ OFF (no supersampling, no cost). */
+  samples: number;
+  /** fraction of the frame interval the shutter is open (0..1). Blur strength;
+   *  0 ⇒ OFF. ~0.5 = a 180° shutter, 1 = 360°. */
+  shutter: number;
+};
+
+/** One caption window on a review copy: the pill reads `text` from `fromMs`
+ *  (inclusive) to `toMs` (exclusive) on the composition timeline. */
+export type ReviewBadge = { fromMs: number; toMs: number; text: string };
+
+/** Render-time decoration for review copies and A/B variant reels: burned-in
+ *  beat badges, a REVIEW watermark, and a per-variant corner label. Drawn by the
+ *  scene in SCREEN space (fixed, outside the composition camera) so the text is
+ *  legible at any zoom. This is a render input only — it is never written into
+ *  the editable `*.composition.json` artifact (render strips it) and the
+ *  validator ignores it. Text renders in the headless Chrome, so any script
+ *  (incl. CJK) works without ffmpeg font filters. */
+export type ReviewDecor = {
+  /** top-right watermark, e.g. "REVIEW" — marks a copy as not-for-posting */
+  watermark?: string;
+  /** bottom-left caption pill, swapping per timeline window */
+  badges?: ReviewBadge[];
+  /** constant bottom-left variant label for A/B reels, e.g. "B · tight ×1.8" */
+  label?: string;
+};
+
+export type TakeComposition = {
+  output: { width: number; height: number; fps: number };
+  source: {
+    videoUrl: string;
+    videoWidth: number;
+    videoHeight: number;
+    viewport: { w: number; h: number };
+  };
+  framing: FramingConfig;
+  cursor: CursorConfig;
+  /** camera motion blur; absent ⇒ off (renders exactly as before). */
+  motionBlur?: MotionBlurConfig;
+  /** cursor start, video-px */
+  start: Pt;
+  events: CompEvent[];
+  durationMs: number;
+  /** render-time review decoration (badges/watermark/label); never persisted */
+  review?: ReviewDecor;
+};
+
+/** True when motion blur is configured to actually do something (so the OFF
+ *  path stays byte-identical to the pre-motion-blur renderer). */
+export function motionBlurActive(mb: MotionBlurConfig | undefined): mb is MotionBlurConfig {
+  return !!mb && mb.samples > 1 && mb.shutter > 0;
+}
+
+export const DEFAULT_FRAMING: FramingConfig = {
+  insetFrac: 0.92,
+  cornerRadius: 28,
+  shadow: { color: "rgba(0,0,0,0.55)", blur: 60, offset: { x: 0, y: 28 } },
+  background: { from: "#1e1b3a", to: "#0a0e1c" },
+};
+
+// Camera motion blur, ON by default — it smooths the zoom
+// motion and softens the zoom-OUT backdrop reveal (the model-C hitch). 6
+// sub-frames is a good smoothness/speed balance; ~0.7 shutter is a strong-ish
+// blur without ghosting. EXPORT render cost scales with `samples` (renders at
+// fps·samples then averages), so `samples` is the quality⇄speed knob — drop it
+// to render faster, raise (≤~12) for silkier fast pans.
+export const DEFAULT_MOTION_BLUR: MotionBlurConfig = {
+  samples: 6,
+  shutter: 0.7,
+};
+
+export const DEFAULT_CURSOR: CursorConfig = {
+  travelMs: 560,
+  // Distance-aware cursor speed — the dominant "silky" lever. A fixed duration
+  // makes velocity scale with distance (short=slow, long=fast); holding a roughly
+  // constant on-screen speed reads consistent/premium. ~0.35 widths/s with the
+  // big-move cap (travelMaxMs 850) was tuned by eye to a notch slower than a
+  // premium reference recording (svgl.mp4) on this app's long toolbar→canvas
+  // moves. Tune up for snappier, down for slower/grander.
+  // NOTE on the cap (subtle): travel ENDS at the action's instant, so a LONGER
+  // duration starts EARLIER, not later. With the front-loaded ease (below) a
+  // longer move therefore reaches the target SOONER — i.e. raising travelMaxMs
+  // can read as *faster*. Judge speed by how fast the cursor SWEEPS, not by when
+  // it arrives; lower the cap for a more deliberate sweep.
+  travelWidthsPerSec: 0.35,
+  travelMinMs: 300,
+  travelMaxMs: 850,
+  scale: 2.0,
+  // Near-straight glide. The reference cursor barely bows (measured: a
+  // full-width move deviated <2% off the straight line), so the arc is small —
+  // just enough to avoid a robotic ruler-straight path, not a visible curve.
+  arcFrac: 0.05,
+  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],
+  // 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-
+  // delay of the same path), which is what makes a SMOOTH (eased) drag work —
+  // its fast mid-section amplifies any τ mismatch into a visible lead. Measured
+  // τ≈190ms on this pipeline (swept dragLagMs, picked where the tip sits on the
+  // ink front mid-stroke); the old 110ms left even linear strokes ~40px ahead.
+  // Re-tune if a different machine's encode latency differs.
+  dragLagMs: 190,
+  // Soft launch + soft landing (gentle accel from rest, peak ~t0.24, decelerate
+  // into the target). Chosen over a symmetric ease-in-out (which felt less silky)
+  // and over a pure ease-out [.33,1,.68,1] (instant-max launch + a 46%-of-duration
+  // creep tail that makes the speed knob lie — see travelMaxMs). This keeps the
+  // soft landing (the silk) while trimming the tail to 38% and removing the abrupt
+  // launch. Tune toward [0.42,0,0.58,1] for a more uniform sweep.
+  travelEase: [0.3, 0.0, 0.2, 1.0],
+};

package/src/validate.ts

@@ -0,0 +1,245 @@
+// validateComposition: a NON-MUTATING structural check on an edited
+// composition. The refine loop is "edit the JSON, re-render" — so the agent
+// (or a human) hand-edits `*.composition.json`, and this gives a
+// millisecond, field-specific verdict BEFORE paying for a render. It never
+// changes the composition; it only reports.
+//
+// Severity:
+//   "error" — the render would be wrong/broken (or silently mis-framed).
+//             renderTake refuses to render until these are fixed.
+//   "warn"  — suspect, but may be intentional. Rendered as-is.
+//
+// The single most important check is the capture-lock (see CAPTURE-LOCKED
+// below): an action beat's `tMs` is bound to the recording — the video frame
+// at time t shows the page AS IT WAS at capture-time t — so re-rendering with
+// a moved `tMs` desyncs the overlay from the on-screen action. Retiming an
+// action needs a re-capture, not a JSON edit. Pass the capture log to enforce
+// this; without it the check is skipped (we can't know the ground truth).
+
+import { restStageScale } from "./math";
+import type { CaptureLog, TakeComposition } from "./types";
+
+export type CompositionIssue = {
+  severity: "error" | "warn";
+  /** dotted/indexed field path, e.g. "events[3].zoom.scale" */
+  path: string;
+  message: string;
+  /** a concrete suggested correction the agent can apply */
+  fix?: string;
+};
+
+export type ValidateOpts = {
+  /** soft ceiling on zoom scale — above it the pixels visibly soften (warn).
+   *  Default 2.5 (the planner caps auto-zoom at 1.5; manual edits get headroom). */
+  maxScale?: number;
+  /** the ground-truth capture log. When given, action `tMs` is checked against
+   *  it (capture-lock). Omit to skip that check. */
+  captureLog?: CaptureLog;
+};
+
+const reqField: Record<string, string> = {
+  type: "text",
+  press: "keys",
+  drag: "to",
+};
+
+export function validateComposition(
+  comp: TakeComposition,
+  opts: ValidateOpts = {},
+): CompositionIssue[] {
+  const issues: CompositionIssue[] = [];
+  const err = (path: string, message: string, fix?: string) =>
+    issues.push({ severity: "error", path, message, fix });
+  const warn = (path: string, message: string, fix?: string) =>
+    issues.push({ severity: "warn", path, message, fix });
+
+  const maxScale = opts.maxScale ?? 2.5;
+
+  // --- output / source sanity ---
+  const { width: oW, height: oH, fps } = comp.output;
+  if (!(oW > 0 && oH > 0))
+    err("output", `non-positive output size ${oW}x${oH}`, "set positive width/height");
+  if (!(fps > 0)) err("output.fps", `fps must be > 0 (got ${fps})`, "set output.fps to 30 or 60");
+  const { videoWidth: vW, videoHeight: vH } = comp.source;
+  if (!(vW > 0 && vH > 0)) err("source", `non-positive source video size ${vW}x${vH}`);
+
+  const rest = restStageScale(vW, vH, oW, oH, comp.framing.insetFrac);
+
+  // --- motion blur (render cost scales with samples: frames = fps × samples) ---
+  const mb = comp.motionBlur;
+  if (mb) {
+    if (!Number.isInteger(mb.samples) || mb.samples < 1 || mb.samples > 16)
+      err(
+        "motionBlur.samples",
+        `samples must be an integer 1-16 (got ${mb.samples})`,
+        "6 is the balanced default; 1 turns blur off",
+      );
+    else if (mb.samples > 9)
+      warn(
+        "motionBlur.samples",
+        `samples ${mb.samples} renders ${mb.samples}× the frames for little extra smoothness`,
+        "9 is the practical ceiling",
+      );
+    if (!(mb.shutter >= 0 && mb.shutter <= 1))
+      err(
+        "motionBlur.shutter",
+        `shutter must be 0..1 (got ${mb.shutter})`,
+        "0.7 is the default; 0 turns blur off",
+      );
+  }
+
+  // --- duration / ordering ---
+  const events = comp.events ?? [];
+  let lastEnd = 0;
+  let prevT = -1;
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i]!;
+    const p = `events[${i}]`;
+    const dur = e.durationMs ?? 0;
+    const endMs = e.tMs + dur;
+    lastEnd = Math.max(lastEnd, endMs);
+
+    // ordering: events must stay in temporal order (the video is temporal)
+    if (e.tMs < prevT) {
+      err(
+        `${p}.tMs`,
+        `tMs ${e.tMs} is before the previous beat (${prevT}) — events out of order`,
+        "events follow the recording; reordering needs a re-capture, not a swap here",
+      );
+    }
+    prevT = e.tMs;
+
+    if (e.tMs < 0) err(`${p}.tMs`, `negative tMs ${e.tMs}`);
+    if (e.tMs > comp.durationMs)
+      err(
+        `${p}.tMs`,
+        `tMs ${e.tMs} exceeds composition durationMs ${comp.durationMs}`,
+        "raise durationMs or remove the beat",
+      );
+
+    // kind-specific required fields (editability invariants)
+    const need = reqField[e.kind];
+    if (need && (e as Record<string, unknown>)[need] == null)
+      err(
+        `${p}.${need}`,
+        `${e.kind} beat is missing "${need}"`,
+        `restore ${need} from the capture`,
+      );
+
+    // --- zoom decision ---
+    const z = e.zoom;
+    if (!z) {
+      err(
+        `${p}.zoom`,
+        "missing zoom decision",
+        "every beat needs a zoom { enabled, scale, center, inAtMs }",
+      );
+      continue;
+    }
+    // inAtMs must precede the action (the zoom-in ramps in before the beat lands)
+    if (z.inAtMs < 0) err(`${p}.zoom.inAtMs`, `negative inAtMs ${z.inAtMs}`, "clamp to 0");
+    if (z.inAtMs > e.tMs)
+      err(
+        `${p}.zoom.inAtMs`,
+        `inAtMs ${z.inAtMs} is AFTER the action at tMs ${e.tMs} — the zoom would arrive late`,
+        `set inAtMs = tMs − cursor.zoomInMs (= ${Math.max(0, e.tMs - comp.cursor.zoomInMs)})`,
+      );
+
+    if (z.enabled) {
+      // scale must zoom IN (≥ rest). Below rest shows MORE than the framed
+      // video → backdrop dead-space; that's never what an enabled zoom wants.
+      if (z.scale < rest - 1e-6)
+        err(
+          `${p}.zoom.scale`,
+          `scale ${z.scale.toFixed(3)} is below rest ${rest.toFixed(3)} — that zooms OUT past the frame (dead space)`,
+          `raise to ≥ ${rest.toFixed(2)}, or set zoom.enabled=false for a full-view beat`,
+        );
+      else if (z.scale <= rest + 1e-6)
+        warn(
+          `${p}.zoom.scale`,
+          `scale ${z.scale.toFixed(3)} ≈ rest — zoom is enabled but does nothing visible`,
+          "raise scale to actually zoom, or set enabled=false",
+        );
+      if (z.scale > maxScale)
+        warn(
+          `${p}.zoom.scale`,
+          `scale ${z.scale.toFixed(2)} exceeds the soft cap ${maxScale} — pixels will soften`,
+          `clamp toward ${maxScale.toFixed(1)} unless the detail truly needs it`,
+        );
+      // center inside the video (clampCenter will pull it in, but an off-video
+      // center usually means a stale/hand-miscomputed value)
+      if (z.center.x < 0 || z.center.x > vW || z.center.y < 0 || z.center.y > vH)
+        warn(
+          `${p}.zoom.center`,
+          `center (${z.center.x.toFixed(0)},${z.center.y.toFixed(0)}) is outside the video ${vW}x${vH}`,
+          e.bbox
+            ? "use the bbox center: { x: bbox.x+bbox.w/2, y: bbox.y+bbox.h/2 }"
+            : "point at the on-screen target (video-px)",
+        );
+      // enabling zoom on a no-bbox beat means an invented center/scale — fine,
+      // but flag it so the refine loop knows it's not bbox-derived.
+      if (!e.bbox)
+        warn(
+          `${p}.zoom`,
+          "zoom enabled on a beat with no bbox — center/scale are hand-set, not bbox-fit",
+          "double-check the center frames the intended region",
+        );
+    }
+  }
+
+  // tail: the composition must outlast the last action (+ a little settle)
+  if (comp.durationMs < lastEnd)
+    err(
+      "durationMs",
+      `durationMs ${comp.durationMs} ends before the last action (${lastEnd})`,
+      `raise to ≥ ${Math.round(lastEnd + comp.cursor.holdMs + comp.cursor.zoomOutMs)}`,
+    );
+  else if (comp.durationMs < lastEnd + comp.cursor.zoomOutMs)
+    warn(
+      "durationMs",
+      `only ${comp.durationMs - lastEnd}ms after the last action — the final zoom-out may be cut`,
+      `allow ≥ ${comp.cursor.zoomOutMs}ms (cursor.zoomOutMs) of tail`,
+    );
+
+  // --- CAPTURE-LOCKED: action tMs must match the recording ---
+  // The video is temporal: a beat's tMs is WHEN it is visible in the capture.
+  // A render-only edit cannot move that, so a drifted tMs would fire the
+  // overlay off the on-screen action. (Cinematic timing — inAtMs, holdMs,
+  // zoom ramps, the intro travel and the tail — IS freely editable; only the
+  // action anchor tMs is locked.)
+  if (opts.captureLog) {
+    const log = opts.captureLog;
+    if (log.events.length !== events.length)
+      warn(
+        "events",
+        `composition has ${events.length} beats but the capture log has ${log.events.length} — added/removed actions need a re-capture`,
+        "re-capture to change the choreography; edit only renders the existing recording",
+      );
+    const n = Math.min(log.events.length, events.length);
+    for (let i = 0; i < n; i++) {
+      const lt = log.events[i]!.tMs;
+      const ct = events[i]!.tMs;
+      if (Math.abs(lt - ct) > 1)
+        err(
+          `events[${i}].tMs`,
+          `tMs ${ct} drifted from the captured ${lt} — an action's tMs is capture-locked (the video shows it at ${lt}ms)`,
+          `restore tMs to ${lt}; to retime the action itself, re-capture`,
+        );
+    }
+  }
+
+  return issues;
+}
+
+/** Format issues for a human/agent log. Errors first. */
+export function formatIssues(issues: CompositionIssue[]): string {
+  if (!issues.length) return "composition OK (0 issues)";
+  const order = (s: string) => (s === "error" ? 0 : 1);
+  return issues
+    .slice()
+    .sort((a, b) => order(a.severity) - order(b.severity))
+    .map(
+      (i) => `  [${i.severity}] ${i.path}: ${i.message}${i.fix ? `\n          fix: ${i.fix}` : ""}`,
+    )
+    .join("\n");
+}