@open-take/compositor 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,11 +1,24 @@
 import { __export } from "./chunk-Cl8Af3a2.js";
 import { spawn, spawnSync } from "node:child_process";
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+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 { 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) {
@@ -41,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,
@@ -83,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) {
@@ -224,6 +234,23 @@ async function installerPath(pkg) {
 		return null;
 	}
 }
+/** Some pnpm installs leave the platform packages' media binaries without an
+*  executable bit. Repair the resolved target at the point of use as well as
+*  in the repo postinstall: published consumers do not run this monorepo's
+*  root lifecycle script. Windows does not use POSIX execute bits. */
+async function ensureExecutable(path) {
+	if (!path || process.platform === "win32") return;
+	try {
+		const info = await stat(path);
+		if ((info.mode & 73) === 0) await chmod(path, info.mode | 73);
+	} catch {}
+}
+/** Revideo resolves its own bundled ffprobe rather than calling
+*  resolveFfprobe(), so repair both installer targets before invoking it. */
+async function repairBundledMediaPermissions() {
+	const paths = await Promise.all([installerPath("@ffmpeg-installer/ffmpeg"), installerPath("@ffprobe-installer/ffprobe")]);
+	await Promise.all(paths.map(ensureExecutable));
+}
 async function resolveFfmpeg() {
 	if (cachedFfmpeg) return cachedFfmpeg;
 	if (runsOk("ffmpeg")) {
@@ -231,6 +258,7 @@ async function resolveFfmpeg() {
 		return cachedFfmpeg;
 	}
 	const p = await installerPath("@ffmpeg-installer/ffmpeg");
+	await ensureExecutable(p);
 	if (p && runsOk(p)) {
 		cachedFfmpeg = p;
 		return p;
@@ -244,6 +272,7 @@ async function resolveFfprobe() {
 		return cachedFfprobe;
 	}
 	const p = await installerPath("@ffprobe-installer/ffprobe");
+	await ensureExecutable(p);
 	if (p && runsOk(p)) {
 		cachedFfprobe = p;
 		return p;
@@ -264,16 +293,16 @@ __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) {
-	t = Math.max(0, Math.min(1, t));
-	return t * t * t * (t * (t * 6 - 15) + 10);
+	const clamped = Math.max(0, Math.min(1, t));
+	return clamped * clamped * clamped * (clamped * (clamped * 6 - 15) + 10);
 }
 function cubicBezier(x1, y1, x2, y2) {
 	const bx = (s) => {
@@ -301,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 {
@@ -339,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];
 }
@@ -403,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;
@@ -412,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 = {
@@ -432,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
+	const push = (t, r) => {
+		rf.push({
+			t: Math.max(t, rf[rf.length - 1].t + .001),
+			r
 		});
-		cf.push({
-			t: Math.max(t, cf[cf.length - 1].t + .001),
-			c
-		});
-	};
-	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;
@@ -528,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;
@@ -613,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 = {}) {
@@ -620,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
@@ -632,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) => ({
@@ -655,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;
@@ -672,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 } : {},
@@ -726,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: {
@@ -754,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
@@ -819,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) {
@@ -843,8 +1091,6 @@ function formatIssues(issues) {
 //#endregion
 //#region src/render.ts
 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";
 function run(cmd, args) {
 	return new Promise((res, rej) => {
@@ -854,7 +1100,9 @@ function run(cmd, args) {
 			"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}`)));
 	});
@@ -911,7 +1159,80 @@ async function motionBlurMp4(inMp4, outMp4, baseFps, samples, shutter) {
 		outMp4
 	]);
 }
+/** 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() {
+	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() {
+	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, to) {
+	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) {
+	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, videoPath) {
+	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");
+		await symlink(nm, join(dir, "node_modules"), "junction");
+		await toMp4(videoPath, join(dir, "public", "capture.mp4"), composition.output.fps);
+		return dir;
+	} catch (error) {
+		await cleanupScratch(dir);
+		throw error;
+	}
+}
+let renderQueue = Promise.resolve();
 async function renderTake(opts) {
+	const run$1 = renderQueue.then(() => renderTakeExclusive(opts), () => renderTakeExclusive(opts));
+	renderQueue = run$1.catch(() => {});
+	return run$1;
+}
+async function renderTakeExclusive(opts) {
+	if (!opts.chromePath) throw new Error("renderTake: `chromePath` is required; use @open-take/runtime to resolve managed Chrome automatically");
 	const composition = opts.composition ?? planComposition(opts.log ?? (() => {
 		throw new Error("renderTake: provide `log` or `composition`");
 	})(), opts.planOpts);
@@ -922,52 +1243,57 @@ async function renderTake(opts) {
 		if (opts.logProgress && warns.length) process.stderr.write(`composition warnings:\n${formatIssues(warns)}\n`);
 		if (errors.length) throw new Error(`composition has ${errors.length} error(s) — refusing to render:\n${formatIssues(errors)}`);
 	}
-	await toMp4(opts.videoPath, PUBLIC_MP4, composition.output.fps);
-	await mkdir(dirname(COMP_JSON), { recursive: true });
-	await writeFile(COMP_JSON, JSON.stringify(composition, null, 2));
-	if (process.env.DISABLE_TELEMETRY === void 0) process.env.DISABLE_TELEMETRY = "true";
-	const prevCwd = process.cwd();
-	process.chdir(PKG_ROOT);
-	let produced;
+	await repairBundledMediaPermissions();
+	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, progress) => opts.onProgress(progress) } : {},
-				puppeteer: {
-					args: [
-						"--no-sandbox",
-						"--disable-setuid-sandbox",
-						"--password-store=basic",
-						"--use-mock-keychain"
-					],
-					...opts.chromePath ? { executablePath: opts.chromePath } : {}
+		if (process.env.DISABLE_TELEMETRY === void 0) process.env.DISABLE_TELEMETRY = "true";
+		const prevCwd = process.cwd();
+		process.chdir(scratch);
+		let produced;
+		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, progress) => opts.onProgress(progress) } : {},
+					viteConfig: { server: { fs: { allow: [scratch, ...deps ? [deps] : []] } } },
+					puppeteer: {
+						args: [
+							"--no-sandbox",
+							"--disable-setuid-sandbox",
+							"--password-store=basic",
+							"--use-mock-keychain"
+						],
+						executablePath: opts.chromePath
+					}
 				}
-			}
-		});
+			});
+		} finally {
+			process.chdir(prevCwd);
+		}
+		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) {
+			const { review: _review,...persisted } = composition;
+			await writeFile(compositionPath, JSON.stringify(persisted, null, 2));
+		}
+		return {
+			mp4Path: resolve(opts.outPath),
+			compositionPath
+		};
 	} finally {
-		process.chdir(prevCwd);
-	}
-	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) {
-		const { review: _review,...persisted } = composition;
-		await writeFile(compositionPath, JSON.stringify(persisted, null, 2));
+		await cleanupScratch(scratch);
 	}
-	return {
-		mp4Path: resolve(opts.outPath),
-		compositionPath
-	};
 }
 
 //#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