@open-take/compositor 0.1.2 → 0.2.0

package/dist/index.js

@@ -9,6 +9,16 @@ import { fileURLToPath } from "node:url";
 import { renderVideo } from "@open-take/revideo-renderer";
 
 //#region src/types.ts
+const DEFAULT_CAMERA = {
+	enabled: true,
+	fillFrac: .6,
+	maxScale: 2.4,
+	minHoldMs: 1200,
+	minZoomScale: 1.25,
+	coalesceWindowMs: 900,
+	travelThreshold: .18,
+	pullOutCoverage: .55
+};
 /** True when motion blur is configured to actually do something (so the OFF
 *  path stays byte-identical to the pre-motion-blur renderer). */
 function motionBlurActive(mb) {
@@ -44,14 +54,8 @@ const DEFAULT_CURSOR = {
 	arcMax: 24,
 	rippleMs: 450,
 	holdMs: 1100,
-	zoomOutMs: 800,
-	zoomInMs: 760,
-	zoomEase: [
-		.3,
-		0,
-		.2,
-		1
-	],
+	zoomOutMs: 1340,
+	zoomInMs: 730,
 	dragLagMs: 190,
 	travelEase: [
 		.3,
@@ -86,20 +90,23 @@ const MOTION = {
 	calm: {
 		travelWidthsPerSec: .28,
 		holdMs: 1500,
-		zoomInMs: 950,
-		zoomOutMs: 950
+		zoomInMs: 900,
+		zoomOutMs: 1650,
+		zoomEase: void 0
 	},
 	natural: {
 		travelWidthsPerSec: .35,
 		holdMs: 1100,
-		zoomInMs: 760,
-		zoomOutMs: 800
+		zoomInMs: 730,
+		zoomOutMs: 1340,
+		zoomEase: void 0
 	},
 	brisk: {
 		travelWidthsPerSec: .45,
 		holdMs: 750,
-		zoomInMs: 560,
-		zoomOutMs: 600
+		zoomInMs: 550,
+		zoomOutMs: 1e3,
+		zoomEase: void 0
 	}
 };
 function motionName(cursor) {
@@ -286,11 +293,11 @@ __export(math_exports, {
 	gradientEndpoints: () => gradientEndpoints,
 	isDragging: () => isDragging,
 	keyvalN: () => keyvalN,
-	keyvalP: () => keyvalP,
-	panEasing: () => panEasing,
+	keyvalR: () => keyvalR,
 	restStageScale: () => restStageScale,
 	smoother: () => smoother,
 	springEase: () => springEase,
+	stageCamera: () => stageCamera,
 	stageEasing: () => stageEasing
 });
 function smoother(t) {
@@ -323,23 +330,22 @@ function cubicBezier(x1, y1, x2, y2) {
 function springEase(bounce) {
 	const zeta = Math.max(.4, Math.min(1, 1 - bounce));
 	const Ts = -Math.log(.001) / zeta;
-	return (p) => {
-		if (p <= 0) return 0;
-		if (p >= 1) return 1;
-		const t = p * Ts;
+	const step = (t) => {
 		if (zeta >= 1) return 1 - Math.exp(-t) * (1 + t);
 		const wd = Math.sqrt(1 - zeta * zeta);
 		return 1 - Math.exp(-zeta * t) * (Math.cos(wd * t) + zeta / wd * Math.sin(wd * t));
 	};
+	const end = step(Ts);
+	return (p) => {
+		if (p <= 0) return 0;
+		if (p >= 1) return 1;
+		return step(p * Ts) / end;
+	};
 }
 function stageEasing(cursor) {
 	if (cursor.zoomSpring != null) return springEase(cursor.zoomSpring);
 	if (cursor.zoomEase) return cubicBezier(...cursor.zoomEase);
-	return smoother;
-}
-function panEasing(cursor) {
-	if (cursor.zoomEase) return cubicBezier(...cursor.zoomEase);
-	return smoother;
+	return springEase(0);
 }
 function gradientEndpoints(angleDeg, oW, oH) {
 	if (angleDeg == null) return {
@@ -361,32 +367,13 @@ function gradientEndpoints(angleDeg, oW, oH) {
 		y1: cy + dy * L / 2
 	};
 }
-function keyvalN(t, kfs, ease = smoother, easeDown) {
+function keyvalN(t, kfs, ease = smoother) {
 	if (t <= kfs[0][0]) return kfs[0][1];
 	if (t >= kfs[kfs.length - 1][0]) return kfs[kfs.length - 1][1];
 	for (let i = 0; i < kfs.length - 1; i++) {
 		const [t0, v0] = kfs[i];
 		const [t1, v1] = kfs[i + 1];
-		if (t0 <= t && t <= t1) {
-			const e = easeDown && v1 < v0 ? easeDown : ease;
-			return v0 + (v1 - v0) * e((t - t0) / (t1 - t0));
-		}
-	}
-	return kfs[kfs.length - 1][1];
-}
-function keyvalP(t, kfs, ease = smoother) {
-	if (t <= kfs[0][0]) return kfs[0][1];
-	if (t >= kfs[kfs.length - 1][0]) return kfs[kfs.length - 1][1];
-	for (let i = 0; i < kfs.length - 1; i++) {
-		const [t0, v0] = kfs[i];
-		const [t1, v1] = kfs[i + 1];
-		if (t0 <= t && t <= t1) {
-			const p = ease((t - t0) / (t1 - t0));
-			return {
-				x: v0.x + (v1.x - v0.x) * p,
-				y: v0.y + (v1.y - v0.y) * p
-			};
-		}
+		if (t0 <= t && t <= t1) return v0 + (v1 - v0) * ease((t - t0) / (t1 - t0));
 	}
 	return kfs[kfs.length - 1][1];
 }
@@ -425,6 +412,30 @@ function clampCenter(center, scale, videoW, videoH, outW, outH) {
 		y: cy
 	};
 }
+/** Interpolate the rect track: centre AND size move under the SAME eased
+*  parameter. This is the whole trick (verified
+*  by frame-tracking a reference export: its pan curve overlays its viewport-WIDTH
+*  curve exactly, not its scale curve): lerping the rect keeps every corner on
+*  a straight line, so the screen-space path of the zoom target is strictly
+*  monotone toward frame centre — no wrong-way "bounce" for ANY scale pair,
+*  which scale+centre lerp can't guarantee (it hooks when scale > 2×rest). */
+function keyvalR(t, kfs, ease) {
+	if (t <= kfs[0][0]) return kfs[0][1];
+	if (t >= kfs[kfs.length - 1][0]) return kfs[kfs.length - 1][1];
+	for (let i = 0; i < kfs.length - 1; i++) {
+		const [t0, v0] = kfs[i];
+		const [t1, v1] = kfs[i + 1];
+		if (t0 <= t && t <= t1) {
+			const p = ease((t - t0) / (t1 - t0));
+			return {
+				cx: v0.cx + (v1.cx - v0.cx) * p,
+				cy: v0.cy + (v1.cy - v0.cy) * p,
+				w: Math.max(v0.w + (v1.w - v0.w) * p, Math.min(v0.w, v1.w) * .5)
+			};
+		}
+	}
+	return kfs[kfs.length - 1][1];
+}
 function buildStageKeyframes(comp) {
 	const { videoWidth: vW, videoHeight: vH } = comp.source;
 	const { width: oW, height: oH } = comp.output;
@@ -434,7 +445,16 @@ function buildStageKeyframes(comp) {
 		y: vH / 2
 	};
 	const HOLD = comp.cursor.holdMs / 1e3;
-	const ZOUT = comp.cursor.zoomOutMs / 1e3;
+	const ZOUT_MS = comp.cursor.zoomOutMs;
+	const rectFor = (center, scale) => {
+		const c = clampCenter(center, scale, vW, vH, oW, oH);
+		return {
+			cx: c.x,
+			cy: c.y,
+			w: oW / scale
+		};
+	};
+	const restR = rectFor(restC, rest);
 	const anchors = [];
 	for (const e of comp.events) {
 		const base = {
@@ -454,95 +474,86 @@ function buildStageKeyframes(comp) {
 			glide: e.zoom.glide
 		});
 	}
-	const zf = [{
-		t: 0,
-		s: rest
-	}];
-	const cf = [{
+	const targets = anchors.map((e) => rectFor(e.center, e.scale));
+	const ZIN_MS = comp.cursor.zoomInMs;
+	const rampStartS = anchors.map((e, i) => {
+		const from = i > 0 ? targets[i - 1] : restR;
+		const pullOut = targets[i].w > from.w + 1e-6;
+		const isDefaultInAt = Math.abs(e.inAtMs - Math.max(0, e.tMs - ZIN_MS)) < 1;
+		if (!pullOut || !isDefaultInAt) return e.inAtMs / 1e3;
+		const desired = e.tMs - ZOUT_MS;
+		const prevEndMs = i > 0 ? anchors[i - 1].tMs + anchors[i - 1].durationMs : 0;
+		const start = desired >= prevEndMs ? desired : Math.min(prevEndMs, e.tMs - Math.min(ZOUT_MS, ZIN_MS));
+		return Math.max(start, 0) / 1e3;
+	});
+	const rf = [{
 		t: 0,
-		c: restC
+		r: restR
 	}];
-	const push = (t, s, c) => {
-		zf.push({
-			t: Math.max(t, zf[zf.length - 1].t + .001),
-			s
-		});
-		cf.push({
-			t: Math.max(t, cf[cf.length - 1].t + .001),
-			c
+	const push = (t, r) => {
+		rf.push({
+			t: Math.max(t, rf[rf.length - 1].t + .001),
+			r
 		});
 	};
-	const pushC = (t, c) => {
-		cf.push({
-			t: Math.max(t, cf[cf.length - 1].t + .001),
-			c
-		});
-	};
-	const ze = panEasing(comp.cursor);
-	const invEase = (target) => {
-		let lo = 0;
-		let hi = 1;
-		for (let i = 0; i < 30; i++) {
-			const m = (lo + hi) / 2;
-			if (ze(m) < target) lo = m;
-			else hi = m;
-		}
-		return (lo + hi) / 2;
-	};
-	const fillThreshold = Math.max(oW / vW, oH / vH);
-	let cur = {
-		s: rest,
-		c: restC
-	};
+	let cur = restR;
 	anchors.forEach((e, i) => {
-		const rampStart = e.inAtMs / 1e3;
 		const clickT = e.tMs / 1e3;
 		const actionEnd = (e.tMs + e.durationMs) / 1e3;
 		const next = anchors[i + 1];
-		const holdEndT = next ? next.inAtMs / 1e3 : actionEnd + HOLD;
-		let holdC = e.center;
+		const holdEndT = next ? rampStartS[i + 1] : actionEnd + HOLD;
+		push(rampStartS[i], cur);
+		push(clickT, targets[i]);
+		cur = targets[i];
+		let holdR = cur;
 		if (e.glide && (e.glide.x !== 0 || e.glide.y !== 0)) {
 			const holdDur = Math.max(0, holdEndT - clickT);
-			holdC = {
+			holdR = rectFor({
 				x: e.center.x + e.glide.x * holdDur,
 				y: e.center.y + e.glide.y * holdDur
-			};
-		}
-		push(rampStart, cur.s, cur.c);
-		if (cur.s > fillThreshold && e.scale < fillThreshold && fillThreshold > rest && clickT > rampStart && Math.hypot(e.center.x - cur.c.x, e.center.y - cur.c.y) > 1) {
-			const uCross = invEase((fillThreshold - cur.s) / (e.scale - cur.s));
-			pushC(rampStart + uCross * (clickT - rampStart), e.center);
+			}, e.scale);
 		}
-		push(clickT, e.scale, e.center);
-		cur = {
-			s: e.scale,
-			c: holdC
-		};
-		if (next) push(holdEndT, cur.s, cur.c);
-		else {
-			const holdEnd = holdEndT;
-			push(holdEnd, cur.s, cur.c);
-			const offset = Math.hypot(cur.c.x - restC.x, cur.c.y - restC.y) > 1;
-			if (offset && cur.s > fillThreshold && fillThreshold > rest) {
-				const uCross = invEase((fillThreshold - cur.s) / (rest - cur.s));
-				pushC(holdEnd + uCross * ZOUT, restC);
-			}
-			push(holdEnd + ZOUT, rest, restC);
-			cur = {
-				s: rest,
-				c: restC
-			};
+		push(holdEndT, holdR);
+		cur = holdR;
+		if (!next) {
+			push(holdEndT + ZOUT_MS / 1e3, restR);
+			cur = restR;
 		}
 	});
-	const lastT = Math.max(zf[zf.length - 1].t, cf[cf.length - 1].t);
+	const lastT = rf[rf.length - 1].t;
 	const T = Math.max(comp.durationMs / 1e3, lastT) + .3;
-	push(T, rest, restC);
+	push(T, restR);
 	return {
-		z: zf.map((f) => [f.t, f.s]),
-		c: cf.map((f) => [f.t, f.c]),
+		r: rf.map((f) => [f.t, f.r]),
 		T
 	};
 }
+/** The one camera evaluator — scene.tsx (render) and the editor preview both
+*  consume THIS, so preview and export can never drift. */
+function stageCamera(comp) {
+	const stage = buildStageKeyframes(comp);
+	const ease = stageEasing(comp.cursor);
+	const oW = comp.output.width;
+	const rest = restStageScale(comp.source.videoWidth, comp.source.videoHeight, oW, comp.output.height, comp.framing.insetFrac);
+	const at = (t) => {
+		const r = keyvalR(t, stage.r, ease);
+		return {
+			scale: oW / r.w,
+			center: {
+				x: r.cx,
+				y: r.cy
+			}
+		};
+	};
+	let peakScale = stage.r.reduce((m, [, r]) => Math.max(m, oW / r.w), rest);
+	for (let i = 0; i <= 720; i++) peakScale = Math.max(peakScale, at(i / 720 * stage.T).scale);
+	return {
+		T: stage.T,
+		rest,
+		peakScale,
+		at
+	};
+}
 function buildLegs(comp) {
 	const legs = [];
 	let cur = comp.start;
@@ -550,8 +561,8 @@ function buildLegs(comp) {
 	const speedPxPerMs = (travelWidthsPerSec || 0) * comp.source.videoWidth / 1e3;
 	const travelDur = (a, b) => {
 		if (speedPxPerMs <= 0) return travelMs / 1e3;
-		const dist = Math.hypot(b.x - a.x, b.y - a.y);
-		return Math.min(travelMaxMs, Math.max(travelMinMs, dist / speedPxPerMs)) / 1e3;
+		const dist$1 = Math.hypot(b.x - a.x, b.y - a.y);
+		return Math.min(travelMaxMs, Math.max(travelMinMs, dist$1 / speedPxPerMs)) / 1e3;
 	};
 	for (const e of comp.events) {
 		if (e.kind === "scroll" || e.kind === "press") continue;
@@ -635,6 +646,200 @@ function isDragging(t, legs) {
 	return legs.some((lg) => lg.drag === true && lg.t0 <= t && t <= lg.t1);
 }
 
+//#endregion
+//#region src/camera.ts
+const centerOf = (b) => ({
+	x: b.x + b.w / 2,
+	y: b.y + b.h / 2
+});
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+const union = (a, b) => {
+	const x = Math.min(a.x, b.x);
+	const y = Math.min(a.y, b.y);
+	return {
+		x,
+		y,
+		w: Math.max(a.x + a.w, b.x + b.w) - x,
+		h: Math.max(a.y + a.h, b.y + b.h) - y
+	};
+};
+function growDown(box, video) {
+	const grownH = Math.max(box.h, Math.min(video.h * .42, box.w * .55));
+	const h = Math.min(grownH, video.h - box.y);
+	return {
+		x: box.x,
+		y: box.y,
+		w: box.w,
+		h
+	};
+}
+/** The region a beat is "about" — what the camera should frame. Prefers the
+*  captured effect region; else shapes one from the element bbox by kind. */
+function roiForBeat(b, video) {
+	if (b.effectBox) return b.effectBox;
+	if (!b.box) return void 0;
+	if (b.kind === "type") return growDown(b.box, video);
+	return b.box;
+}
+function clusterLabel(beats, idx) {
+	const raw = beats[idx[0]]?.label ?? "";
+	const cleaned = raw.replace(/\s+/g, " ").trim().slice(0, 18);
+	return cleaned || "region";
+}
+/**
+* Decide framing for every beat. `endMs` is when the last frame can hold until
+* (for the min-hold check on the final segment). `rest` is the stage scale at
+* full view.
+*/
+function directCamera(beats, video, out, cam, rest, endMs) {
+	const restC = {
+		x: video.w / 2,
+		y: video.h / 2
+	};
+	const fit = (roi) => bboxFitScale(roi, out.w, out.h, cam.fillFrac, cam.maxScale, rest);
+	const nodes = beats.map((b, i) => {
+		const roi = roiForBeat(b, video);
+		const scale = roi ? fit(roi) : rest;
+		const gapBreak = i > 0 && b.tMs - (beats[i - 1].tMs + beats[i - 1].durationMs) > cam.coalesceWindowMs;
+		if (b.intent === "never") return {
+			roi,
+			scale,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: "plan: zoom=never → full view"
+		};
+		if (b.intent === "always") return {
+			roi,
+			scale,
+			forceFull: false,
+			forcePunch: true,
+			boundary: true,
+			reason: roi ? `plan: zoom=always → ${scale.toFixed(2)}× (framing from ROI)` : "plan: zoom=always but no bbox to frame → full view"
+		};
+		if (b.kind === "scroll") return {
+			roi: void 0,
+			scale: rest,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: "scroll — full view (content pans)"
+		};
+		if (b.kind === "press" && b.keys && /(^|\+)esc(ape)?$/i.test(b.keys.trim())) return {
+			roi: void 0,
+			scale: rest,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: "Escape (dismissal) — full view"
+		};
+		if (b.changeCoverage != null && b.changeCoverage >= cam.pullOutCoverage) return {
+			roi,
+			scale,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: `changeCoverage ${b.changeCoverage.toFixed(2)} ≥ ${cam.pullOutCoverage} (global repaint) → full view`
+		};
+		if (i === 0) return {
+			roi,
+			scale,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: "opening beat — full view (orienting)"
+		};
+		if (!roi) return {
+			roi,
+			scale,
+			forceFull: true,
+			forcePunch: false,
+			boundary: true,
+			reason: "no bbox to frame → full view"
+		};
+		if (scale < cam.minZoomScale) return {
+			roi,
+			scale,
+			forceFull: true,
+			forcePunch: false,
+			boundary: gapBreak,
+			reason: `ROI fills the frame already (fit ${scale.toFixed(2)}× < ${cam.minZoomScale}×) — full view`
+		};
+		return {
+			roi,
+			scale,
+			forceFull: false,
+			forcePunch: false,
+			boundary: gapBreak,
+			reason: `punch ${scale.toFixed(2)}× (ROI-fit)`
+		};
+	});
+	const segs = [];
+	for (let i = 0; i < nodes.length; i++) {
+		const n = nodes[i];
+		if (n.forceFull) {
+			segs.push({
+				idx: [i],
+				kind: "rest",
+				scale: rest,
+				center: restC
+			});
+			continue;
+		}
+		const last = segs[segs.length - 1];
+		const lastLastIdx = last ? last.idx[last.idx.length - 1] : -1;
+		const canExtend = !!last && last.kind === "punch" && !!last.roi && !n.forcePunch && !nodes[lastLastIdx].forcePunch && !n.boundary && !!n.roi && dist(centerOf(n.roi), centerOf(last.roi)) < cam.travelThreshold * video.w && fit(union(last.roi, n.roi)) >= cam.minZoomScale;
+		if (canExtend && last && last.roi && n.roi) {
+			const roi = union(last.roi, n.roi);
+			last.idx.push(i);
+			last.roi = roi;
+			last.scale = fit(roi);
+			last.center = centerOf(roi);
+		} else segs.push({
+			idx: [i],
+			kind: "punch",
+			roi: n.roi,
+			scale: n.scale,
+			center: n.roi ? centerOf(n.roi) : restC
+		});
+	}
+	segs.forEach((s, si) => {
+		if (s.kind !== "punch") return;
+		const firstT = beats[s.idx[0]].tMs;
+		const next = segs[si + 1];
+		const heldUntil = next ? beats[next.idx[0]].tMs : endMs;
+		if (heldUntil - firstT < cam.minHoldMs) {
+			s.kind = "rest";
+			s.scale = rest;
+			s.center = restC;
+			s.dropped = true;
+		}
+	});
+	const framings = new Array(beats.length);
+	for (const s of segs) {
+		if (s.kind === "rest") {
+			for (const i of s.idx) framings[i] = {
+				enabled: false,
+				scale: rest,
+				center: restC,
+				reason: s.dropped ? `punch dropped — held < ${cam.minHoldMs}ms (would flinch) → full view` : nodes[i].reason
+			};
+			continue;
+		}
+		const N = s.idx.length;
+		const tag = N > 1 ? `cluster[${clusterLabel(beats, s.idx)}]` : null;
+		s.idx.forEach((i, k) => {
+			framings[i] = {
+				enabled: true,
+				scale: s.scale,
+				center: s.center,
+				reason: tag ? `${tag} ${k + 1}/${N} · hold shared framing (union of ${N}) → ${s.scale.toFixed(2)}×` : nodes[i].reason
+			};
+		});
+	}
+	return framings;
+}
+
 //#endregion
 //#region src/plan.ts
 function planComposition(log, opts = {}) {
@@ -642,10 +847,6 @@ function planComposition(log, opts = {}) {
 	const oW = opts.output?.width ?? vW;
 	const oH = opts.output?.height ?? vH;
 	const fps = opts.output?.fps ?? 30;
-	const fillFrac = opts.fillFrac ?? .55;
-	const maxScale = opts.maxScale ?? 1.5;
-	const zoomRatio = opts.zoomRatio ?? 1.3;
-	const zoomFirst = opts.zoomFirst ?? false;
 	const framing = {
 		...DEFAULT_FRAMING,
 		...opts.framing
@@ -654,6 +855,10 @@ function planComposition(log, opts = {}) {
 		...DEFAULT_CURSOR,
 		...opts.cursor
 	};
+	const camera = {
+		...DEFAULT_CAMERA,
+		...opts.camera
+	};
 	const sx = vW / log.viewport.w;
 	const sy = vH / log.viewport.h;
 	const mapPt = (p) => ({
@@ -677,13 +882,12 @@ function planComposition(log, opts = {}) {
 			h: Math.max(...ys) - y
 		};
 	};
-	const events = log.events.map((c, i) => {
+	const scaffolds = log.events.map((c) => {
 		const kind = c.kind ?? "click";
 		const point = mapPt({
 			x: c.x,
 			y: c.y
 		});
-		const isFirst = i === 0;
 		const intent = c.zoom ?? "auto";
 		const durationMs$1 = "durationMs" in c ? c.durationMs : 0;
 		const to = kind === "drag" ? mapPt(c.to) : void 0;
@@ -694,53 +898,26 @@ function planComposition(log, opts = {}) {
 		const path = rawPath?.map(mapPt);
 		const ease = kind === "drag" ? c.ease : void 0;
 		const bbox = kind === "drag" && path ? pathBBox(path) : c.box ? mapBox(c.box) : void 0;
-		let enabled = false;
-		let scale = rest;
-		let reason;
-		const center = bbox ? {
-			x: bbox.x + bbox.w / 2,
-			y: bbox.y + bbox.h / 2
-		} : point;
-		const fit = bbox ? bboxFitScale(bbox, oW, oH, fillFrac, maxScale, rest) : maxScale;
-		if (kind === "scroll") {
-			enabled = false;
-			reason = "scroll — full view (content pans, no zoom)";
-		} else if (intent === "never") {
-			enabled = false;
-			reason = "plan: zoom=never (global/navigation payoff — keep full view)";
-		} else if (intent === "always") {
-			enabled = true;
-			scale = fit;
-			reason = `plan: zoom=always → ${fit.toFixed(2)}x (capped ${maxScale}x)`;
-		} else if (!bbox) reason = "no bbox in event log — cannot bbox-fit, so no zoom (avoids framing dead space)";
-		else {
-			scale = fit;
-			const meaningful = fit > rest * zoomRatio;
-			const region = kind === "drag" ? "drag path" : "element";
-			if (isFirst && !zoomFirst) {
-				enabled = false;
-				reason = `first/orienting action — skipped by default (fit ${fit.toFixed(2)}x available)`;
-			} else if (!meaningful) {
-				enabled = false;
-				reason = `${region} fills the frame already (fit ${fit.toFixed(2)}x ≈ rest ${rest.toFixed(2)}x) — gentle/no zoom`;
-			} else {
-				enabled = true;
-				reason = `bbox-fit ${fit.toFixed(2)}x (capped ${maxScale}x), ${region} framed with ${Math.round(fillFrac * 100)}% fill`;
-			}
-		}
-		return {
+		const effectBox = c.effectBox ? mapBox(c.effectBox) : void 0;
+		const label = c.sel ?? c.note;
+		const beat = {
+			kind,
+			tMs: c.tMs,
+			durationMs: durationMs$1,
+			box: bbox,
+			effectBox,
+			changeCoverage: c.changeCoverage,
+			point,
+			intent,
+			label,
+			...kind === "press" ? { keys: c.keys } : {}
+		};
+		const ev = {
 			kind,
 			tMs: c.tMs,
 			point,
 			bbox,
-			label: c.sel ?? c.note,
-			zoom: {
-				enabled,
-				scale,
-				center,
-				inAtMs: Math.max(0, c.tMs - cursor.zoomInMs),
-				reason
-			},
+			label,
 			...durationMs$1 ? { durationMs: durationMs$1 } : {},
 			...kind === "type" ? { text: c.text } : {},
 			...kind === "press" ? { keys: c.keys } : {},
@@ -748,13 +925,40 @@ function planComposition(log, opts = {}) {
 			...path ? { path } : {},
 			...ease ? { ease } : {}
 		};
+		return {
+			beat,
+			ev
+		};
+	});
+	const beats = scaffolds.map((s) => s.beat);
+	const last = log.events.length ? log.events[log.events.length - 1] : void 0;
+	const lastEnd = last ? last.tMs + ("durationMs" in last ? last.durationMs : 0) : 0;
+	const endMs = Math.max(log.tEndMs ?? 0, lastEnd + cursor.holdMs);
+	const framings = camera.enabled ? directCamera(beats, {
+		w: vW,
+		h: vH
+	}, {
+		w: oW,
+		h: oH
+	}, camera, rest, endMs) : beats.map((b) => manualFraming(b, rest));
+	const events = scaffolds.map((s, i) => {
+		const f = framings[i];
+		const zoom = {
+			enabled: f.enabled,
+			scale: f.scale,
+			center: f.center,
+			inAtMs: Math.max(0, s.beat.tMs - cursor.zoomInMs),
+			reason: f.reason
+		};
+		return {
+			...s.ev,
+			zoom
+		};
 	});
 	const start = log.start ? mapPt(log.start) : {
 		x: vW * .25,
 		y: vH * .9
 	};
-	const last = log.events.length ? log.events[log.events.length - 1] : void 0;
-	const lastEnd = last ? last.tMs + ("durationMs" in last ? last.durationMs : 0) : 0;
 	const durationMs = Math.max(log.tEndMs ?? 0, lastEnd + cursor.holdMs + cursor.zoomOutMs + 400);
 	return {
 		output: {
@@ -776,6 +980,23 @@ function planComposition(log, opts = {}) {
 		durationMs
 	};
 }
+function manualFraming(b, rest) {
+	if (b.intent === "always" && b.box) return {
+		enabled: true,
+		scale: rest,
+		center: {
+			x: b.box.x + b.box.w / 2,
+			y: b.box.y + b.box.h / 2
+		},
+		reason: "camera off · plan: zoom=always (raise scale by hand)"
+	};
+	return {
+		enabled: false,
+		scale: rest,
+		center: b.point,
+		reason: "camera off · full view (no explicit zoom)"
+	};
+}
 
 //#endregion
 //#region src/validate.ts
@@ -841,6 +1062,11 @@ function validateComposition(comp, opts = {}) {
 			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");
 		}
 	}
+	const spring = comp.cursor.zoomSpring;
+	if (spring != null) {
+		if (!(spring >= 0 && spring < .6)) err("cursor.zoomSpring", `zoomSpring ${spring} outside [0, 0.6)`, "0 = critically damped (the default feel); keep bounce ≤ 0.3");
+		else if (spring > .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");
+	}
 	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`);
 	if (opts.captureLog) {
@@ -1069,5 +1295,5 @@ async function renderTakeExclusive(opts) {
 }
 
 //#endregion
-export { DEFAULT_CURSOR, DEFAULT_FRAMING, DEFAULT_MOTION_BLUR, FINISH, LOOKS, MOTION, ZOOM_LEVELS, finishName, formatIssues, lookName, math_exports as math, motionBlurActive, motionName, planComposition, renderTake, resolveFfmpeg, resolveFfprobe, validateComposition, zoomLevelName };
+export { DEFAULT_CAMERA, DEFAULT_CURSOR, DEFAULT_FRAMING, DEFAULT_MOTION_BLUR, FINISH, LOOKS, MOTION, ZOOM_LEVELS, directCamera, finishName, formatIssues, lookName, math_exports as math, motionBlurActive, motionName, planComposition, renderTake, resolveFfmpeg, resolveFfprobe, validateComposition, zoomLevelName };
 //# sourceMappingURL=index.js.map