cozyclay 1.0.0

package/src/camera-follow.js

@@ -0,0 +1,366 @@
+/**
+ * Follow camera: a real crew in three pieces of math.
+ *
+ * A tracking shot on set is three jobs — the RAIL constrains where the camera
+ * may be, the DOLLY GRIP pushes along it to hold distance to the subject, and
+ * the OPERATOR pans to keep the framing. Keyframe interpolation can't play
+ * that scene: between keys it never looks at what the subject actually does,
+ * which is exactly why corners feel wrong. Here the camera is DERIVED from
+ * the subject's per-frame trajectory instead.
+ *
+ * Everything is integrated offline over the whole clip at a fixed dt, so
+ * scrubbing, playing backwards, PlayView and Record all see the same
+ * deterministic track — no wall-clock springs, no simulation state to
+ * desync. Same trajectory + same params = the same track, always.
+ *
+ * Conventions match camera-move.js / controls.jsx: Y-up metres, YXZ look
+ * angles with yaw = atan2(-dx, -dz).
+ */
+
+/** critically damped response: reaches ~98% of a step in `response` seconds */
+function omegaFor(response) {
+	return 4.6 / Math.max(response, 0.05);
+}
+
+/** one semi-implicit Euler step of a critically damped spring (scalar) */
+function springStep(pos, vel, target, omega, dt) {
+	const acc = omega * omega * (target - pos) - 2 * omega * vel;
+	const nextVel = vel + acc * dt;
+	return [pos + nextVel * dt, nextVel];
+}
+
+function aimAngles(position, target) {
+	const dx = target.x - position.x;
+	const dy = target.y - position.y;
+	const dz = target.z - position.z;
+	return {
+		yaw: Math.atan2(-dx, -dz),
+		pitch: Math.atan2(dy, Math.max(Math.hypot(dx, dz), 1e-6)),
+	};
+}
+
+export const FOLLOW_DEFAULTS = {
+	/** metres the grip tries to hold between camera and subject */
+	distance: 3,
+	/** camera height in metres (a rail is 2D; height is the operator's) */
+	height: 1.6,
+	/** dolly response in seconds — larger = heavier, lazier camera */
+	response: 0.7,
+	/** operator aim response; a head pans faster than a dolly moves */
+	aimResponse: 0.35,
+	/** seconds of subject velocity the operator leads the frame by */
+	lead: 0.25,
+	/** where on the body the operator holds frame (chest, metres) */
+	aimHeight: 1.35,
+	/** hard cap on camera translation (m/s) — a crew has legs, not thrusters */
+	maxSpeed: 2.8,
+	/** EMA weight for the BEHIND direction; slow on purpose, so a corner
+	 * sweeps the trailing position gradually and the camera cuts the corner
+	 * the way a steadicam op does instead of whipping around the subject.
+	 * Tuned with maxSpeed against a 90° corner walk: together they hold the
+	 * worst pan under ~60°/s (3°/frame @20), a brisk but human pan. */
+	dirBlend: 0.05,
+};
+
+/**
+ * Subject travel directions, one unit XZ vector per frame. Velocity is
+ * EMA-smoothed so a foot-plant wobble doesn't wag the whole camera, and the
+ * last real direction is held through stops — a grip doesn't forget which
+ * way the actor was walking just because they paused.
+ */
+export function travelDirections(subject, fps, initialDir = null, blend = 0.25) {
+	const dirs = [];
+	let dir = initialDir && Math.hypot(initialDir.x, initialDir.z) > 1e-6
+		? normalize(initialDir)
+		: null;
+	let vx = 0;
+	let vz = 0;
+	for (let f = 0; f < subject.length; f += 1) {
+		if (f > 0) {
+			vx += ((subject[f].x - subject[f - 1].x) * fps - vx) * blend;
+			vz += ((subject[f].z - subject[f - 1].z) * fps - vz) * blend;
+		}
+		if (Math.hypot(vx, vz) > 0.15) dir = normalize({ x: vx, z: vz });
+		if (!dir) {
+			// nothing has moved yet: probe the first future step so the camera
+			// starts behind the walk instead of snapping when it begins
+			for (let probe = f + 1; probe < subject.length; probe += 1) {
+				const dx = subject[probe].x - subject[f].x;
+				const dz = subject[probe].z - subject[f].z;
+				if (Math.hypot(dx, dz) > 0.05) {
+					dir = normalize({ x: dx, z: dz });
+					break;
+				}
+			}
+			if (!dir) dir = { x: 0, z: 1 };
+		}
+		dirs.push(dir);
+	}
+	return dirs;
+}
+
+function normalize(v) {
+	const len = Math.max(Math.hypot(v.x, v.z), 1e-9);
+	return { x: v.x / len, z: v.z / len };
+}
+
+/** smoothed subject velocities (m/s), the operator's lead signal */
+function smoothedVelocities(subject, fps) {
+	const out = [];
+	let vx = 0;
+	let vz = 0;
+	const blend = 0.25;
+	for (let f = 0; f < subject.length; f += 1) {
+		if (f > 0) {
+			vx += ((subject[f].x - subject[f - 1].x) * fps - vx) * blend;
+			vz += ((subject[f].z - subject[f - 1].z) * fps - vz) * blend;
+		}
+		out.push({ x: vx, z: vz });
+	}
+	return out;
+}
+
+/**
+ * Free follow (no rail): steadicam behind the subject. The position target
+ * sits `distance` metres behind the smoothed travel direction; the camera
+ * spring-chases it, the aim spring-chases a lead point. Returns one
+ * {pos, yaw, pitch} per subject frame.
+ */
+export function buildFollowTrack(subject, fps, params = {}) {
+	const p = { ...FOLLOW_DEFAULTS, ...params };
+	if (!subject || subject.length === 0) return [];
+	const dt = 1 / Math.max(fps, 1);
+	const dirs = travelDirections(subject, fps, p.initialDir ?? null, p.dirBlend);
+	const vels = smoothedVelocities(subject, fps);
+	const omega = omegaFor(p.response);
+	const aimOmega = omegaFor(p.aimResponse);
+	// a critically damped spring trails a moving target by 2v/ω at steady
+	// state; feeding the subject's velocity forward cancels that lag, so the
+	// held distance is the REQUESTED distance, not distance-plus-lag
+	const lagComp = 2 / omega;
+
+	// start settled on the frame-0 target: a shot opens composed, not sliding
+	let px = subject[0].x - dirs[0].x * p.distance;
+	let pz = subject[0].z - dirs[0].z * p.distance;
+	let py = p.height;
+	let vx = 0, vz = 0, vy = 0;
+	let ax = subject[0].x;
+	let az = subject[0].z;
+	let avx = 0, avz = 0;
+
+	const track = [];
+	for (let f = 0; f < subject.length; f += 1) {
+		if (f > 0) {
+			const tx = subject[f].x - dirs[f].x * p.distance + vels[f].x * lagComp;
+			const tz = subject[f].z - dirs[f].z * p.distance + vels[f].z * lagComp;
+			// planar spring integrated by hand so the SPEED cap binds the
+			// velocity vector, not each axis separately
+			vx += (omega * omega * (tx - px) - 2 * omega * vx) * dt;
+			vz += (omega * omega * (tz - pz) - 2 * omega * vz) * dt;
+			const speed = Math.hypot(vx, vz);
+			if (speed > p.maxSpeed) {
+				vx *= p.maxSpeed / speed;
+				vz *= p.maxSpeed / speed;
+			}
+			px += vx * dt;
+			pz += vz * dt;
+			[py, vy] = springStep(py, vy, p.height, omega, dt);
+			const aimTx = subject[f].x + vels[f].x * p.lead;
+			const aimTz = subject[f].z + vels[f].z * p.lead;
+			[ax, avx] = springStep(ax, avx, aimTx, aimOmega, dt);
+			[az, avz] = springStep(az, avz, aimTz, aimOmega, dt);
+		}
+		const pos = { x: px, y: py, z: pz };
+		const { yaw, pitch } = aimAngles(pos, { x: ax, y: p.aimHeight, z: az });
+		track.push({ pos, yaw, pitch });
+	}
+	return track;
+}
+
+/* ------------------------------------------------------------ the rail --- */
+
+/**
+ * Ramer–Douglas–Peucker: an authored stroke is hundreds of jittery pointer
+ * samples; the rail wants the handful of points that carry its shape.
+ */
+export function simplifyStroke(points, epsilon = 0.12) {
+	if (!points || points.length <= 2) return points ? [...points] : [];
+	const keep = new Array(points.length).fill(false);
+	keep[0] = keep[points.length - 1] = true;
+	const stack = [[0, points.length - 1]];
+	while (stack.length) {
+		const [a, b] = stack.pop();
+		const pa = points[a];
+		const pb = points[b];
+		const abx = pb.x - pa.x;
+		const abz = pb.z - pa.z;
+		const abLen = Math.max(Math.hypot(abx, abz), 1e-9);
+		let worst = 0;
+		let worstIdx = -1;
+		for (let i = a + 1; i < b; i += 1) {
+			const d = Math.abs((points[i].x - pa.x) * abz - (points[i].z - pa.z) * abx) / abLen;
+			if (d > worst) {
+				worst = d;
+				worstIdx = i;
+			}
+		}
+		if (worst > epsilon && worstIdx > 0) {
+			keep[worstIdx] = true;
+			stack.push([a, worstIdx], [worstIdx, b]);
+		}
+	}
+	return points.filter((_, i) => keep[i]);
+}
+
+/**
+ * Centripetal Catmull–Rom through the simplified control points, sampled at
+ * ~`spacing` metres. Returns { points, cumLen, length } — a dense polyline
+ * with cumulative arc length, the coordinate system the grip pushes in.
+ */
+export function buildRail(controlPoints, { spacing = 0.05 } = {}) {
+	const cps = (controlPoints ?? []).filter(
+		(p, i, arr) => i === 0 || Math.hypot(p.x - arr[i - 1].x, p.z - arr[i - 1].z) > 1e-6,
+	);
+	if (cps.length < 2) return null;
+	const pts = [cps[0]];
+	const alpha = 0.5; // centripetal: no loops or overshoot at tight corners
+	for (let i = 0; i < cps.length - 1; i += 1) {
+		const p0 = cps[Math.max(i - 1, 0)];
+		const p1 = cps[i];
+		const p2 = cps[i + 1];
+		const p3 = cps[Math.min(i + 2, cps.length - 1)];
+		const segLen = Math.hypot(p2.x - p1.x, p2.z - p1.z);
+		const steps = Math.max(2, Math.ceil(segLen / spacing));
+		const t0 = 0;
+		const t1 = t0 + Math.hypot(p1.x - p0.x, p1.z - p0.z) ** alpha || t0 + 1e-6;
+		const t2 = t1 + segLen ** alpha;
+		const t3 = t2 + Math.hypot(p3.x - p2.x, p3.z - p2.z) ** alpha || t2 + 1e-6;
+		for (let s = 1; s <= steps; s += 1) {
+			const t = t1 + ((t2 - t1) * s) / steps;
+			pts.push(catmullRomPoint(p0, p1, p2, p3, t0, t1, t2, t3, t));
+		}
+	}
+	const cumLen = [0];
+	for (let i = 1; i < pts.length; i += 1) {
+		cumLen.push(cumLen[i - 1] + Math.hypot(pts[i].x - pts[i - 1].x, pts[i].z - pts[i - 1].z));
+	}
+	return { points: pts, cumLen, length: cumLen[cumLen.length - 1] };
+}
+
+function catmullRomPoint(p0, p1, p2, p3, t0, t1, t2, t3, t) {
+	const lerp2 = (a, b, ta, tb) => {
+		const w = tb - ta < 1e-9 ? 0 : (t - ta) / (tb - ta);
+		return { x: a.x + (b.x - a.x) * w, z: a.z + (b.z - a.z) * w };
+	};
+	const a1 = lerp2(p0, p1, t0, t1);
+	const a2 = lerp2(p1, p2, t1, t2);
+	const a3 = lerp2(p2, p3, t2, t3);
+	const b1 = lerp2(a1, a2, t0, t2);
+	const b2 = lerp2(a2, a3, t1, t3);
+	return lerp2(b1, b2, t1, t2);
+}
+
+/** point on the rail at arc position s (clamped) */
+export function railPoint(rail, s) {
+	const { points, cumLen, length } = rail;
+	const target = Math.max(0, Math.min(s, length));
+	let lo = 0;
+	let hi = cumLen.length - 1;
+	while (hi - lo > 1) {
+		const mid = (lo + hi) >> 1;
+		if (cumLen[mid] <= target) lo = mid;
+		else hi = mid;
+	}
+	const span = cumLen[hi] - cumLen[lo];
+	const w = span < 1e-9 ? 0 : (target - cumLen[lo]) / span;
+	return {
+		x: points[lo].x + (points[hi].x - points[lo].x) * w,
+		z: points[lo].z + (points[hi].z - points[lo].z) * w,
+	};
+}
+
+/** arc position of the sample nearest the given point, searched globally */
+function nearestS(rail, point) {
+	let best = 0;
+	let bestD = Infinity;
+	for (let i = 0; i < rail.points.length; i += 1) {
+		const d = Math.hypot(rail.points[i].x - point.x, rail.points[i].z - point.z);
+		if (d < bestD) {
+			bestD = d;
+			best = rail.cumLen[i];
+		}
+	}
+	return best;
+}
+
+/**
+ * Rail follow: the camera lives ON the drawn rail; each frame the grip finds
+ * the nearby arc position whose distance to the subject is closest to
+ * `distance` and spring-pushes toward it (speed-capped — a dolly has mass).
+ * The operator aims exactly as in the free follow. Local search only: the
+ * dolly never teleports across the stage to a globally better spot.
+ */
+export function buildRailFollowTrack(subject, fps, rail, params = {}) {
+	const p = { ...FOLLOW_DEFAULTS, maxDollySpeed: 4, searchWindow: 2.5, backtrackPenalty: 1.0, ...params };
+	if (!subject || subject.length === 0 || !rail || rail.length < 1e-6) return [];
+	const dt = 1 / Math.max(fps, 1);
+	const vels = smoothedVelocities(subject, fps);
+	const omega = omegaFor(p.response);
+	const aimOmega = omegaFor(p.aimResponse);
+	const step = Math.max(rail.length / Math.max(rail.points.length - 1, 1), 1e-3);
+
+	const distanceErrorAt = (s, subj) => {
+		const rp = railPoint(rail, s);
+		return Math.abs(Math.hypot(rp.x - subj.x, rp.z - subj.z) - p.distance);
+	};
+	// Retreat is taxed: when the subject closes in, a real grip concedes
+	// distance rather than sprinting the dolly backwards — the backwards
+	// whip-pan looks far worse on screen than a temporarily short distance.
+	const bestSNear = (s0, subj, window, penalty) => {
+		let best = s0;
+		let bestErr = distanceErrorAt(s0, subj);
+		for (let ds = step; ds <= window; ds += step) {
+			for (const cand of [s0 + ds, s0 - ds]) {
+				if (cand < 0 || cand > rail.length) continue;
+				const err = distanceErrorAt(cand, subj) + penalty * Math.max(0, s0 - cand);
+				if (err < bestErr - 1e-9) {
+					bestErr = err;
+					best = cand;
+				}
+			}
+		}
+		return best;
+	};
+
+	// open settled: the whole rail is searched once (no penalty — there is
+	// no established mark yet) for the best opening position
+	let s = bestSNear(nearestS(rail, subject[0]), subject[0], rail.length, 0);
+	let sVel = 0;
+	let py = p.height;
+	let vy = 0;
+	let ax = subject[0].x;
+	let az = subject[0].z;
+	let avx = 0, avz = 0;
+
+	const track = [];
+	for (let f = 0; f < subject.length; f += 1) {
+		if (f > 0) {
+			const sTarget = bestSNear(s, subject[f], p.searchWindow, p.backtrackPenalty);
+			[s, sVel] = springStep(s, sVel, sTarget, omega, dt);
+			const cap = p.maxDollySpeed;
+			if (sVel > cap) sVel = cap;
+			if (sVel < -cap) sVel = -cap;
+			s = Math.max(0, Math.min(s, rail.length));
+			[py, vy] = springStep(py, vy, p.height, omega, dt);
+			const aimTx = subject[f].x + vels[f].x * p.lead;
+			const aimTz = subject[f].z + vels[f].z * p.lead;
+			[ax, avx] = springStep(ax, avx, aimTx, aimOmega, dt);
+			[az, avz] = springStep(az, avz, aimTz, aimOmega, dt);
+		}
+		const rp = railPoint(rail, s);
+		const pos = { x: rp.x, y: py, z: rp.z };
+		const { yaw, pitch } = aimAngles(pos, { x: ax, y: p.aimHeight, z: az });
+		track.push({ pos, yaw, pitch, s });
+	}
+	return track;
+}

package/src/camera-move.js

@@ -0,0 +1,286 @@
+// Pure math + string assembly. No three.js, no React.
+// A camera move is two framings and a duration — nothing else. The authoring
+// model is "compose the shot twice": the director frames A, frames B, and this
+// module interpolates like a dolly grip instead of a graphics library. It also
+// names the move from the geometry, so the prompt claims "push-in" only when
+// the camera actually pushes in.
+
+import { FRAMING_PIVOT_Y, SUBJECT_HEIGHT_M, deriveShot, focalMmToFov, fovToFocalMm } from "./shot.js";
+
+/* ------------------------------------------------------------ framing --- */
+
+/**
+ * Snapshot the shot camera as a plain framing record.
+ * yaw/pitch follow the YXZ free-look convention in controls.jsx.
+ * @param {{pos:{x:number,y:number,z:number}, yaw:number, pitch:number, fovDeg:number}} state
+ */
+export function captureFraming({ pos, yaw, pitch, fovDeg }) {
+	return { pos: { x: pos.x, y: pos.y, z: pos.z }, yaw, pitch, fovDeg };
+}
+
+// yaw/pitch -> unit forward vector. Mirrors forwardFrom() in controls.jsx,
+// re-stated here so this module stays importable without three.js.
+function forward(yaw, pitch) {
+	const cp = Math.cos(pitch);
+	return { x: -Math.sin(yaw) * cp, y: Math.sin(pitch), z: -Math.cos(yaw) * cp };
+}
+
+// position + target -> the yaw/pitch that looks at the target. Mirrors aimAt().
+function aimAngles(position, target) {
+	const dx = target.x - position.x;
+	const dy = target.y - position.y;
+	const dz = target.z - position.z;
+	return {
+		yaw: Math.atan2(-dx, -dz),
+		pitch: Math.atan2(dy, Math.max(Math.hypot(dx, dz), 1e-6)),
+	};
+}
+
+const TWO_PI = Math.PI * 2;
+
+/** signed shortest angular distance a -> b, in (-PI, PI] */
+export function shortestArc(a, b) {
+	let delta = (b - a) % TWO_PI;
+	if (delta > Math.PI) delta -= TWO_PI;
+	if (delta <= -Math.PI) delta += TWO_PI;
+	return delta;
+}
+
+const clamp01 = (t) => Math.max(0, Math.min(1, t));
+const lerp = (a, b, t) => a + (b - a) * t;
+
+/** the classic film ease: slow out of A, slow into B */
+export function easeInOut(t) {
+	return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
+}
+
+/**
+ * Decompose a framing into subject-centred move coordinates: horizontal
+ * distance, azimuth around the subject, lens height, and the world point the
+ * lens is aimed at (sampled at the subject's range, so an interpolated orbit
+ * keeps looking where the framing did instead of at empty air).
+ */
+function decompose(framing, anchor) {
+	const dx = framing.pos.x - anchor.x;
+	const dz = framing.pos.z - anchor.z;
+	const r = Math.max(Math.hypot(dx, dz), 1e-6);
+	// pos = anchor + r * (sin az, cos az): the same convention ShotRig presets use
+	const azimuth = Math.atan2(dx, dz);
+	const range = Math.max(Math.hypot(r, framing.pos.y - FRAMING_PIVOT_Y), 1e-6);
+	const dir = forward(framing.yaw, framing.pitch);
+	const aim = {
+		x: framing.pos.x + dir.x * range,
+		y: framing.pos.y + dir.y * range,
+		z: framing.pos.z + dir.z * range,
+	};
+	return { r, azimuth, height: framing.pos.y, aim, focalMm: fovToFocalMm((framing.fovDeg * Math.PI) / 180) };
+}
+
+/**
+ * The heart of the tool. Interpolating raw positions drives an orbit through
+ * the chord — straight at the subject's face — so the blend runs in
+ * subject-centred coordinates instead: distance, azimuth, and height each
+ * ease independently, and azimuth takes the short way around. The lens
+ * interpolates in focal millimetres, which is the space a zoom ring moves in.
+ *
+ * @param {object} a          start framing (captureFraming record)
+ * @param {object} b          end framing
+ * @param {{x:number,z:number}} anchor   subject ground position
+ * @param {number} t          0..1 along the move
+ * @param {(t:number)=>number} ease
+ * @returns a framing record for time t; t=0 and t=1 reproduce A and B exactly
+ */
+export function interpolateFraming(a, b, anchor, t, ease = easeInOut) {
+	const k = ease(clamp01(t));
+	const A = decompose(a, anchor);
+	const B = decompose(b, anchor);
+	const r = lerp(A.r, B.r, k);
+	const azimuth = A.azimuth + shortestArc(A.azimuth, B.azimuth) * k;
+	const height = lerp(A.height, B.height, k);
+	const pos = {
+		x: anchor.x + r * Math.sin(azimuth),
+		y: height,
+		z: anchor.z + r * Math.cos(azimuth),
+	};
+	const aim = {
+		x: lerp(A.aim.x, B.aim.x, k),
+		y: lerp(A.aim.y, B.aim.y, k),
+		z: lerp(A.aim.z, B.aim.z, k),
+	};
+	const { yaw, pitch } = aimAngles(pos, aim);
+	const focalMm = lerp(A.focalMm, B.focalMm, k);
+	return { pos, yaw, pitch, fovDeg: (focalMmToFov(focalMm) * 180) / Math.PI };
+}
+
+/* ----------------------------------------------------------- naming ---- */
+
+const DEG = 180 / Math.PI;
+
+// Below these deltas the camera is, cinematically speaking, not doing that.
+const STILL_POS_M = 0.12;
+const STILL_ANGLE_DEG = 6;
+const DOLLY_M = 0.3;
+const CRANE_M = 0.4;
+const ORBIT_DEG = 20;
+const ZOOM_MM = 10;
+const VERTIGO_MM = 8;
+const VERTIGO_SIZE_DRIFT = 0.15; // dolly-zoom = distance changes, subject size does not
+
+/**
+ * Name the move from the geometry. The CAMERA_MOVES list in shot.js is what a
+ * user *claims*; this is what the two framings *prove*. The phrase slots into
+ * composePrompt's "Camera move: ${...}." sentence.
+ *
+ * @param {object} a  start framing
+ * @param {object} b  end framing
+ * @param {{x:number,z:number,rot:number}} subject
+ * @param {{durationS?:number, height?:number}} [opts]
+ */
+export function classifyMove(a, b, subject, { durationS = 3, height = SUBJECT_HEIGHT_M } = {}) {
+	const anchor = { x: subject.x, z: subject.z };
+	const A = decompose(a, anchor);
+	const B = decompose(b, anchor);
+	const shotA = deriveShot(a.pos, subject, (a.fovDeg * Math.PI) / 180, height);
+	const shotB = deriveShot(b.pos, subject, (b.fovDeg * Math.PI) / 180, height);
+
+	const dr = B.r - A.r;
+	const dAzDeg = shortestArc(A.azimuth, B.azimuth) * DEG;
+	const dh = B.height - A.height;
+	const dFocal = B.focalMm - A.focalMm;
+	const dYawDeg = shortestArc(a.yaw, b.yaw) * DEG;
+	const dPitchDeg = (b.pitch - a.pitch) * DEG;
+	const posDelta = Math.hypot(b.pos.x - a.pos.x, b.pos.y - a.pos.y, b.pos.z - a.pos.z);
+	const sizeDrift = Math.abs(shotB.screenFraction - shotA.screenFraction) / Math.max(shotA.screenFraction, 1e-6);
+
+	// tempo comes from how far the lens physically travels per second
+	const travel = Math.hypot(Math.abs(dr), (Math.abs(dAzDeg) / DEG) * ((A.r + B.r) / 2), dh);
+	const speed = travel / Math.max(durationS, 0.1);
+	const tempo = travel < STILL_POS_M ? "" : speed < 0.35 ? "slow " : speed > 1.4 ? "fast " : "";
+
+	const still = posDelta < STILL_POS_M;
+	const sizes = `from a ${shotA.sizeLabel} to a ${shotB.sizeLabel}`;
+	let id;
+	let label;
+	let phrase;
+
+	if (still && Math.abs(dYawDeg) < STILL_ANGLE_DEG && Math.abs(dPitchDeg) < STILL_ANGLE_DEG && Math.abs(dFocal) < ZOOM_MM) {
+		id = "static";
+		label = "Static / locked-off";
+		phrase = "static, locked-off shot";
+	} else if (still && Math.abs(dFocal) >= ZOOM_MM) {
+		id = dFocal > 0 ? "zoom-in" : "zoom-out";
+		label = dFocal > 0 ? "Zoom in" : "Zoom out";
+		phrase = `a ${tempo}zoom ${dFocal > 0 ? "in, tightening" : "out, widening"} ${sizes}`;
+	} else if (still) {
+		// the tripod stays put; only the head moves
+		if (Math.abs(dYawDeg) >= Math.abs(dPitchDeg)) {
+			const side = dYawDeg > 0 ? "left" : "right"; // +yaw turns a YXZ camera left
+			id = `pan-${side}`;
+			label = `Pan ${side}`;
+			phrase = `a ${tempo}pan to the ${side}`;
+		} else {
+			const way = dPitchDeg > 0 ? "up" : "down";
+			id = `tilt-${way}`;
+			label = `Tilt ${way}`;
+			phrase = `a ${tempo}tilt ${way}`;
+		}
+	} else if (
+		Math.abs(dr) >= DOLLY_M &&
+		Math.abs(dFocal) >= VERTIGO_MM &&
+		Math.sign(dFocal) === Math.sign(dr) &&
+		sizeDrift <= VERTIGO_SIZE_DRIFT
+	) {
+		id = "dolly-zoom";
+		label = "Dolly-zoom (vertigo)";
+		phrase = `a dolly-zoom (vertigo effect), the camera ${dr < 0 ? "pushing in" : "pulling back"} while the lens compensates to hold the subject's size, the background ${dr < 0 ? "stretching away" : "compressing in"}`;
+	} else if (Math.abs(dAzDeg) >= ORBIT_DEG) {
+		id = "orbit";
+		label = "Orbit / arc";
+		const radial = dr <= -DOLLY_M ? ", closing in as it circles" : dr >= DOLLY_M ? ", drifting wider as it circles" : "";
+		phrase = `a ${tempo}orbit around the subject, arcing ${Math.round(Math.abs(dAzDeg))} degrees${radial}`;
+	} else if (Math.abs(dh) >= CRANE_M && Math.abs(dh) >= Math.abs(dr) * 0.8) {
+		const way = dh > 0 ? "up" : "down";
+		id = `crane-${way}`;
+		label = `Crane ${way}`;
+		phrase = `a ${tempo}crane ${way}, the camera ${dh > 0 ? "rising" : "sinking"} from ${shotA.levelLabel} to ${shotB.levelLabel}`;
+	} else if (dr <= -DOLLY_M) {
+		id = "push-in";
+		label = "Push-in (dolly in)";
+		const crane = Math.abs(dh) >= CRANE_M ? `, craning ${dh > 0 ? "up" : "down"} as it moves` : "";
+		phrase = `a ${tempo}push-in (dolly in) ${sizes}${crane}`;
+	} else if (dr >= DOLLY_M) {
+		id = "pull-out";
+		label = "Pull-out (dolly out)";
+		const crane = Math.abs(dh) >= CRANE_M ? `, craning ${dh > 0 ? "up" : "down"} as it moves` : "";
+		phrase = `a ${tempo}pull-out (dolly out) ${sizes}${crane}`;
+	} else {
+		id = "tracking";
+		label = "Tracking / follow";
+		phrase = `a ${tempo}tracking move`;
+	}
+
+	return {
+		id,
+		label,
+		phrase,
+		tempo: tempo.trim(),
+		from: shotA,
+		to: shotB,
+		deltas: { dr, dAzDeg, dh, dFocal, dYawDeg, dPitchDeg, posDelta, sizeDrift },
+	};
+}
+
+/** the burned-in move slate, e.g. "MEDIUM SHOT 35MM → CLOSE-UP 85MM · PUSH-IN (DOLLY IN)" */
+export function moveSlate(move) {
+	const end = [
+		`${move.from.sizeLabel} ${move.from.focalMm}mm`,
+		`${move.to.sizeLabel} ${move.to.focalMm}mm`,
+	].map((part) => part.toUpperCase());
+	return `${end[0]} → ${end[1]} · ${move.label.toUpperCase()}`;
+}
+
+/* ------------------------------------------------- multi-key sequences --- */
+
+/**
+ * Sample an N-key camera move at a frame. Keys are sorted frame-unique
+ * records `{ frame, framing }`. Before the first key and after the last the
+ * framing holds; inside a segment it interpolates exactly like A→B.
+ * @param {Array<{frame:number, framing:object}>} keys  sorted by frame
+ * @param {{x:number,z:number}} anchor  subject ground position
+ * @param {number} frame
+ * @returns a framing record, or null when there are no keys
+ */
+export function cameraMoveAt(keys, anchor, frame) {
+	if (!keys.length) return null;
+	const first = keys[0];
+	const last = keys[keys.length - 1];
+	if (frame <= first.frame) return first.framing;
+	if (frame >= last.frame) return last.framing;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const a = keys[i];
+		const b = keys[i + 1];
+		if (frame <= b.frame) {
+			return interpolateFraming(a.framing, b.framing, anchor, (frame - a.frame) / (b.frame - a.frame));
+		}
+	}
+	return last.framing;
+}
+
+/** Chained slate for a classified segment list, e.g.
+ * "MEDIUM SHOT 35MM · PUSH-IN (DOLLY IN) → CLOSE-UP 85MM · ORBIT / ARC → WIDE 24MM".
+ * One segment renders identically to moveSlate. */
+export function moveSequenceSlate(segments) {
+	if (!segments.length) return "";
+	if (segments.length === 1) return moveSlate(segments[0]);
+	const parts = [`${segments[0].from.sizeLabel} ${segments[0].from.focalMm}mm`.toUpperCase()];
+	for (const seg of segments) {
+		parts.push(`${seg.label.toUpperCase()} → ${`${seg.to.sizeLabel} ${seg.to.focalMm}mm`.toUpperCase()}`);
+	}
+	return parts.join(" · ");
+}
+
+/** Generation phrase for a classified segment list: each segment's proven
+ * phrase, chained in time order. */
+export function moveSequencePhrase(segments) {
+	return segments.map((seg) => seg.phrase).join(", then ");
+}