cozyclay 1.0.0 → 1.2.0

package/src/ardy/waypoints.js

@@ -1,4 +1,5 @@
 const cleanZero = (value) => (Object.is(value, -0) || Math.abs(value) < 1e-9 ? 0 : value);
+import { isKo } from "../locale.js";
 
 /**
  * ARDY root constraints live in the actor's clip-local coordinates. CozyClay's
@@ -273,7 +274,7 @@ export function judgeNextWaypoint(last, candidate, fps, prev = null) {
 	if (gap < PATH_LIMITS.minPinGapFrames) {
 		return {
 			ok: false,
-			error: `pins need at least ${PATH_LIMITS.minPinGapFrames} frames between them (${(PATH_LIMITS.minPinGapFrames / fps).toFixed(1)} s) — scrub past frame ${last.frame + PATH_LIMITS.minPinGapFrames}`,
+			error: isKo ? `핀 사이에는 최소 ${PATH_LIMITS.minPinGapFrames}프레임(${(PATH_LIMITS.minPinGapFrames / fps).toFixed(1)}초)이 필요해요 — ${last.frame + PATH_LIMITS.minPinGapFrames}프레임 이후로 이동해 주세요` : `pins need at least ${PATH_LIMITS.minPinGapFrames} frames between them (${(PATH_LIMITS.minPinGapFrames / fps).toFixed(1)} s) — scrub past frame ${last.frame + PATH_LIMITS.minPinGapFrames}`,
 			warnings: [],
 		};
 	}
@@ -285,7 +286,7 @@ export function judgeNextWaypoint(last, candidate, fps, prev = null) {
 		const neededFrames = Math.ceil((dist / PATH_LIMITS.speedMaxMps) * fps);
 		return {
 			ok: false,
-			error: `${speed.toFixed(1)} m/s is faster than anyone moves (max ${PATH_LIMITS.speedMaxMps}) — pin frame ${last.frame + neededFrames} or later, or click closer`,
+			error: isKo ? `${speed.toFixed(1)} m/s는 사람이 움직이기엔 너무 빨라요(최대 ${PATH_LIMITS.speedMaxMps}) — ${last.frame + neededFrames}프레임 이후에 핀을 찍거나 더 가까운 곳을 눌러 주세요` : `${speed.toFixed(1)} m/s is faster than anyone moves (max ${PATH_LIMITS.speedMaxMps}) — pin frame ${last.frame + neededFrames} or later, or click closer`,
 			warnings: [],
 		};
 	}
@@ -294,7 +295,7 @@ export function judgeNextWaypoint(last, candidate, fps, prev = null) {
 		const neededDist = (PATH_LIMITS.speedMinMps * dt).toFixed(1);
 		return {
 			ok: false,
-			error: `${speed.toFixed(2)} m/s is below a sustainable walk (min ${PATH_LIMITS.speedMinMps}) — pin frame ~${walkFrame} instead, or click at least ${neededDist} m away`,
+			error: isKo ? `${speed.toFixed(2)} m/s는 자연스럽게 걷기엔 너무 느려요(최소 ${PATH_LIMITS.speedMinMps}) — 대신 약 ${walkFrame}프레임에 핀을 찍거나 최소 ${neededDist} m 이상 떨어진 곳을 눌러 주세요` : `${speed.toFixed(2)} m/s is below a sustainable walk (min ${PATH_LIMITS.speedMinMps}) — pin frame ~${walkFrame} instead, or click at least ${neededDist} m away`,
 			warnings: [],
 		};
 	}
@@ -305,7 +306,7 @@ export function judgeNextWaypoint(last, candidate, fps, prev = null) {
 			const prevSpeed = prevDist / ((last.frame - prev.frame) / fps);
 			const ratio = Math.max(speed, prevSpeed) / Math.max(Math.min(speed, prevSpeed), 1e-6);
 			if (ratio > PATH_LIMITS.speedRatioWarn) {
-				warnings.push(`${ratio.toFixed(1)}x speed change from the previous leg — expect a visible gait shift`);
+				warnings.push(isKo ? `이전 구간보다 속도가 ${ratio.toFixed(1)}배 달라요 — 걸음 변화가 눈에 보일 수 있어요` : `${ratio.toFixed(1)}x speed change from the previous leg — expect a visible gait shift`);
 			}
 			const before = Math.atan2(last.x - prev.x, last.z - prev.z);
 			const after = Math.atan2(candidate.x - last.x, candidate.z - last.z);
@@ -313,7 +314,7 @@ export function judgeNextWaypoint(last, candidate, fps, prev = null) {
 			if (turn > Math.PI) turn = 2 * Math.PI - turn;
 			const turnRate = (turn * 180) / Math.PI / dt;
 			if (turnRate > PATH_LIMITS.turnRateWarnDegPerS) {
-				warnings.push(`${Math.round((turn * 180) / Math.PI)}° turn in ${dt.toFixed(1)} s is sharper than a walking arc — give it more frames or distance`);
+				warnings.push(isKo ? `${dt.toFixed(1)}초 동안 ${Math.round((turn * 180) / Math.PI)}° 회전은 걷는 동선치고 너무 급해요 — 프레임이나 거리를 더 주세요` : `${Math.round((turn * 180) / Math.PI)}° turn in ${dt.toFixed(1)} s is sharper than a walking arc — give it more frames or distance`);
 			}
 		}
 	}
@@ -331,21 +332,25 @@ export function judgeAuthoredPath(rootPath, fps, clipFrames, { chained = false }
 	const ordered = [...rootPath].sort((a, b) => a.frame - b.frame);
 	for (let i = 1; i < ordered.length; i += 1) {
 		const verdict = judgeNextWaypoint(ordered[i - 1], ordered[i], fps, i >= 2 ? ordered[i - 2] : null);
-		if (!verdict.ok) errors.push(`leg ${i} (frame ${ordered[i - 1].frame}->${ordered[i].frame}): ${verdict.error}`);
-		else for (const warning of verdict.warnings) warnings.push(`leg ${i}: ${warning}`);
+		if (!verdict.ok) errors.push(isKo ? `구간 ${i} (${ordered[i - 1].frame}->${ordered[i].frame}프레임): ${verdict.error}` : `leg ${i} (frame ${ordered[i - 1].frame}->${ordered[i].frame}): ${verdict.error}`);
+		else for (const warning of verdict.warnings) warnings.push(isKo ? `구간 ${i}: ${warning}` : `leg ${i}: ${warning}`);
 	}
 	// The trained window binds ONE model call. A chained rollout (a prompt
 	// schedule) makes a call per block, so the whole clip may exceed it —
 	// each block is capped separately by the bridge and the box generator.
 	if (!chained && clipFrames / fps > PATH_LIMITS.clipMaxS) {
 		errors.push(
-			`a root path generates the whole clip in one model call, and ARDY's trained window is ${PATH_LIMITS.clipMaxS} s — shorten the clip to ${PATH_LIMITS.clipMaxS} s, or split the prompt into blocks so the path rides a chained rollout`,
+			isKo
+				? `이동 경로는 전체 클립을 한 번의 모델 호출로 만들어요. ARDY가 학습한 길이는 ${PATH_LIMITS.clipMaxS}초까지예요 — 클립을 ${PATH_LIMITS.clipMaxS}초로 줄이거나 프롬프트를 블록으로 나눠 이어 만들기를 사용해 주세요`
+				: `a root path generates the whole clip in one model call, and ARDY's trained window is ${PATH_LIMITS.clipMaxS} s — shorten the clip to ${PATH_LIMITS.clipMaxS} s, or split the prompt into blocks so the path rides a chained rollout`,
 		);
 	}
 	const tail = (clipFrames - 1 - (ordered[ordered.length - 1]?.frame ?? 0)) / fps;
 	if (ordered.length > 1 && tail > PATH_LIMITS.tailMaxS) {
 		warnings.push(
-			`${tail.toFixed(1)} s of clip remain after the last pin — the unconstrained tail continues whatever the path ends in`,
+			isKo
+				? `마지막 핀 뒤에 클립이 ${tail.toFixed(1)}초 남아 있어요 — 제약이 없는 끝부분은 경로가 끝난 상태를 그대로 이어가요`
+				: `${tail.toFixed(1)} s of clip remain after the last pin — the unconstrained tail continues whatever the path ends in`,
 		);
 	}
 	return { errors, warnings };

package/src/camera-block.js

@@ -0,0 +1,60 @@
+// Pure Camera Block model. A shot owns one complete camera instruction, like
+// the camera card clipped to a single strip of film.
+
+export const CAMERA_MODES = Object.freeze(["keys", "follow", "rail"]);
+
+export const CAMERA_FOLLOW_DEFAULTS = Object.freeze({
+	distance: 3,
+	height: 1.6,
+	response: 0.7,
+	lead: 0.25,
+	railStartMode: "head",
+	maxDollySpeed: 4,
+	pitchOffsetDeg: 0,
+});
+
+function cloneRail(points) {
+	return Array.isArray(points) ? points.map((point) => ({ x: point.x, z: point.z })) : null;
+}
+
+function cloneRailFollow(value) {
+	if (!value || typeof value !== "object") return null;
+	if (value.mode === "off") return { mode: "off" };
+	if (value.mode === "range") return {
+		mode: "range",
+		startFrame: value.startFrame,
+		endFrame: value.endFrame,
+	};
+	return null;
+}
+
+/** Build a complete block from a partial or stored camera value. */
+export function createCameraBlock(input = {}) {
+	const value = input && typeof input === "object" ? input : {};
+	return {
+		mode: CAMERA_MODES.includes(value.mode) ? value.mode : "keys",
+		followCam: { ...CAMERA_FOLLOW_DEFAULTS, ...(value.followCam ?? {}) },
+		cameraRail: cloneRail(value.cameraRail),
+		railFollow: cloneRailFollow(value.railFollow),
+	};
+}
+
+/** Camera Blocks must never share nested settings across shots. */
+export function cloneCameraBlock(camera) {
+	return createCameraBlock(camera);
+}
+
+/** Immutable nested update used by both the sidebar and timeline inspector. */
+export function updateCameraBlock(camera, patch = {}) {
+	const current = createCameraBlock(camera);
+	const change = patch && typeof patch === "object" ? patch : {};
+	return createCameraBlock({
+		...current,
+		...change,
+		followCam: change.followCam
+			? { ...current.followCam, ...change.followCam }
+			: current.followCam,
+		cameraRail: Object.hasOwn(change, "cameraRail") ? change.cameraRail : current.cameraRail,
+		railFollow: Object.hasOwn(change, "railFollow") ? change.railFollow : current.railFollow,
+	});
+}

package/src/camera-follow.js

@@ -29,6 +29,21 @@ function springStep(pos, vel, target, omega, dt) {
 	return [pos + nextVel * dt, nextVel];
 }
 
+/** scalar spring whose speed limit is applied before position integration */
+function cappedSpringStep(pos, vel, target, omega, dt, maxSpeed) {
+	const acc = omega * omega * (target - pos) - 2 * omega * vel;
+	const cap = Math.max(0, Number.isFinite(maxSpeed) ? maxSpeed : 0);
+	const nextVel = Math.max(-cap, Math.min(vel + acc * dt, cap));
+	return [pos + nextVel * dt, nextVel];
+}
+
+const PITCH_LIMIT = (85 * Math.PI) / 180;
+
+function offsetPitch(pitch, offsetDeg) {
+	const safeOffset = Math.max(-30, Math.min(Number.isFinite(offsetDeg) ? offsetDeg : 0, 30));
+	return Math.max(-PITCH_LIMIT, Math.min(pitch + (safeOffset * Math.PI) / 180, PITCH_LIMIT));
+}
+
 function aimAngles(position, target) {
 	const dx = target.x - position.x;
 	const dy = target.y - position.y;
@@ -39,6 +54,25 @@ function aimAngles(position, target) {
 	};
 }
 
+const clamp = (value, min, max) => Math.max(min, Math.min(value, max));
+const rounded = (value, places) => Number(value.toFixed(places));
+
+/**
+ * Turn the operator's current viewport framing into the three physical Follow
+ * settings. These are observations, not knobs: moving the camera is the input.
+ * Pitch is stored as an offset from the rig's automatic chest aim so replaying
+ * the Follow track reproduces the angle the operator composed by hand.
+ */
+export function followFramingFromCamera(position, pitch, subject, aimHeight = FOLLOW_DEFAULTS.aimHeight) {
+	const planarDistance = Math.hypot(position.x - subject.x, position.z - subject.z);
+	const automaticPitch = aimAngles(position, { x: subject.x, y: aimHeight, z: subject.z }).pitch;
+	return {
+		distance: rounded(clamp(planarDistance, 0.5, 15), 2),
+		height: rounded(clamp(position.y, 0.2, 6), 2),
+		pitchOffsetDeg: rounded(clamp(((pitch - automaticPitch) * 180) / Math.PI, -30, 30), 1),
+	};
+}
+
 export const FOLLOW_DEFAULTS = {
 	/** metres the grip tries to hold between camera and subject */
 	distance: 3,
@@ -52,8 +86,14 @@ export const FOLLOW_DEFAULTS = {
 	lead: 0.25,
 	/** where on the body the operator holds frame (chest, metres) */
 	aimHeight: 1.35,
+	/** vertical tilt added after automatic aiming, in degrees */
+	pitchOffsetDeg: 0,
 	/** hard cap on camera translation (m/s) — a crew has legs, not thrusters */
 	maxSpeed: 2.8,
+	/** where a rail dolly opens: the authored head or legacy auto placement */
+	railStartMode: "head",
+	/** hard cap on rail-dolly travel in metres per second */
+	maxDollySpeed: 4,
 	/** 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.
@@ -172,7 +212,7 @@ export function buildFollowTrack(subject, fps, params = {}) {
 		}
 		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 });
+		track.push({ pos, yaw, pitch: offsetPitch(pitch, p.pitchOffsetDeg) });
 	}
 	return track;
 }
@@ -301,7 +341,7 @@ function nearestS(rail, point) {
  * 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 };
+	const p = { ...FOLLOW_DEFAULTS, 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);
@@ -332,9 +372,11 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 		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);
+	// Head mode honours the authored start mark exactly. Nearest preserves the
+	// legacy auto-placement option by searching the whole rail once.
+	let s = p.railStartMode === "nearest"
+		? bestSNear(nearestS(rail, subject[0]), subject[0], rail.length, 0)
+		: 0;
 	let sVel = 0;
 	let py = p.height;
 	let vy = 0;
@@ -346,10 +388,7 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 	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, sVel] = cappedSpringStep(s, sVel, sTarget, omega, dt, p.maxDollySpeed);
 			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;
@@ -360,7 +399,7 @@ export function buildRailFollowTrack(subject, fps, rail, params = {}) {
 		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 });
+		track.push({ pos, yaw, pitch: offsetPitch(pitch, p.pitchOffsetDeg), s });
 	}
 	return track;
 }

package/src/camera-rail-schedule.js

@@ -0,0 +1,176 @@
+/**
+ * Rail Follow time clip — pure schedule math.
+ *
+ * The spatial rail (cameraRail) says WHERE the dolly may go; the Rail Follow
+ * clip says WHEN. A shot has at most one clip, drawn as a thin ribbon on the
+ * Camera lane, and its schedule lives in the persisted `railFollow` field:
+ *
+ *   null                        legacy-derived — the clip is the whole timeline
+ *                               until the first edit; the serializer omits the
+ *                               field entirely so old payloads stay untouched
+ *   {mode:"range",startFrame,endFrame}  authored range, both ends inclusive
+ *   {mode:"off"}                explicit removal — never resurrects on reload
+ *
+ * Every function here is pure: storage values in, plain answers out, no
+ * state, no React. The camera-owner decision is a separate pure step so the
+ * timeline can render the clip (ribbon, progress, handles) even while the
+ * follow cam is off.
+ */
+
+/** minimum inclusive clip length: 10 frames @ 20 fps = 0.5 s */
+export const RAIL_FOLLOW_MIN_FRAMES = 10;
+
+/** resolved schedule kinds — what the clip looks like right now */
+export const RAIL_SCHEDULE_NONE = "none"; // no usable rail geometry at all
+export const RAIL_SCHEDULE_TOO_SHORT = "too-short"; // timeline can't hold a 10-frame clip
+export const RAIL_SCHEDULE_OFF = "off"; // explicitly removed, must not resurrect
+export const RAIL_SCHEDULE_RANGE = "range"; // authored range, inclusive both ends
+export const RAIL_SCHEDULE_LEGACY = "legacy"; // pre-railFollow payload: whole timeline
+
+/** camera owners at a frame — MoveRig and FollowCamRig must never both win */
+export const RAIL_OWNER_NONE = "none";
+export const RAIL_OWNER_RAIL = "rail";
+export const RAIL_OWNER_KEYS = "keys";
+
+const finite = Number.isFinite;
+
+/** the persisted rail is usable when it holds at least two finite points */
+export function isRailUsable(cameraRail) {
+	return (
+		Array.isArray(cameraRail) &&
+		cameraRail.length >= 2 &&
+		cameraRail.every((point) => !!point && finite(point.x) && finite(point.z))
+	);
+}
+
+/**
+ * Fit a range into a timeline: clamp both ends into [0, frameCount-1] and
+ * enforce the 10-inclusive-frame minimum by extending (never by shrinking a
+ * longer clip). Returns null when the range is structurally invalid or the
+ * timeline is too short to hold the minimum clip. Never grows a range beyond
+ * what was stored, so re-clamping after a timeline grows back is a no-op.
+ */
+function fitRange(startFrame, endFrame, frameCount) {
+	if (!finite(startFrame) || !finite(endFrame) || !finite(frameCount)) return null;
+	const last = Math.floor(frameCount) - 1;
+	if (last < 0) return null;
+	let start = Math.max(0, Math.min(Math.round(startFrame), last));
+	let end = Math.max(0, Math.min(Math.round(endFrame), last));
+	if (start > end) return null;
+	const minSpan = RAIL_FOLLOW_MIN_FRAMES - 1;
+	if (end - start < minSpan) {
+		if (frameCount < RAIL_FOLLOW_MIN_FRAMES) return null;
+		end = Math.min(last, start + minSpan);
+		start = Math.max(0, end - minSpan);
+	}
+	return { startFrame: start, endFrame: end };
+}
+
+/** the default clip range for a freshly drawn rail: the whole timeline */
+export function defaultRailRange(frameCount) {
+	if (!finite(frameCount) || frameCount < RAIL_FOLLOW_MIN_FRAMES) return null;
+	return { startFrame: 0, endFrame: Math.floor(frameCount) - 1 };
+}
+
+/**
+ * Shrink-safe clamp for persisting an authored range when the timeline
+ * changes: clamp once, store the result, and later growth cannot resurrect
+ * the old (now out-of-bounds) range because this never expands it.
+ */
+export function clampRailRange(range, frameCount) {
+	if (!range || typeof range !== "object") return null;
+	return fitRange(range.startFrame, range.endFrame, frameCount);
+}
+
+/**
+ * Move a clip by `delta` frames, preserving its length. The whole span stays
+ * inside [0, frameCount-1]. Returns null when the range is not a valid
+ * min-10 clip or cannot fit in the timeline.
+ */
+export function moveRailRange(range, delta, frameCount) {
+	if (!range || typeof range !== "object" || !finite(delta) || !finite(frameCount)) return null;
+	const start = Math.round(range.startFrame);
+	const end = Math.round(range.endFrame);
+	const length = end - start + 1;
+	if (start > end || length < RAIL_FOLLOW_MIN_FRAMES || length > frameCount) return null;
+	const last = Math.floor(frameCount) - 1;
+	if (last < 0) return null;
+	const maxStart = last - (length - 1);
+	const shifted = start + Math.round(delta);
+	const newStart = Math.max(0, Math.min(shifted, maxStart));
+	return { startFrame: newStart, endFrame: newStart + length - 1 };
+}
+
+/**
+ * Resize a clip by moving one edge to `frame`. The result keeps the other
+ * edge fixed, stays inside the timeline, and is never shorter than the
+ * 10-inclusive-frame minimum. Returns null when no valid range can keep the
+ * fixed edge (the timeline is too short at that side) or the inputs are
+ * structurally invalid.
+ */
+export function resizeRailRange(range, edge, frame, frameCount) {
+	if (!range || typeof range !== "object" || (edge !== "start" && edge !== "end")) return null;
+	if (!finite(frame) || !finite(frameCount)) return null;
+	const last = Math.floor(frameCount) - 1;
+	if (last < 0) return null;
+	const start = Math.max(0, Math.min(Math.round(range.startFrame), last));
+	const end = Math.max(0, Math.min(Math.round(range.endFrame), last));
+	if (start > end) return null;
+	const target = Math.max(0, Math.min(Math.round(frame), last));
+	const minSpan = RAIL_FOLLOW_MIN_FRAMES - 1;
+	if (edge === "end") {
+		const minEnd = start + minSpan;
+		if (minEnd > last) return null;
+		return { startFrame: start, endFrame: Math.max(minEnd, Math.min(target, last)) };
+	}
+	const maxStart = end - minSpan;
+	if (maxStart < 0) return null;
+	return { startFrame: Math.min(maxStart, Math.max(target, 0)), endFrame: end };
+}
+
+/**
+ * Resolve the persisted schedule into what the clip looks like right now.
+ * Order matters: no rail beats everything (there is nothing to schedule),
+ * then a timeline too short to hold a clip hides it, then the stored modes
+ * apply. Corrupt ranges fold to "off" — never invent a clip the data does
+ * not support.
+ */
+export function resolveRailSchedule({ railFollow, cameraRail, frameCount }) {
+	if (!isRailUsable(cameraRail)) return { kind: RAIL_SCHEDULE_NONE };
+	if (!finite(frameCount) || frameCount < RAIL_FOLLOW_MIN_FRAMES) return { kind: RAIL_SCHEDULE_TOO_SHORT };
+	const last = Math.floor(frameCount) - 1;
+	if (!railFollow) return { kind: RAIL_SCHEDULE_LEGACY, startFrame: 0, endFrame: last };
+	if (railFollow.mode === RAIL_SCHEDULE_OFF) return { kind: RAIL_SCHEDULE_OFF };
+	if (railFollow.mode === RAIL_SCHEDULE_RANGE) {
+		const fitted = fitRange(railFollow.startFrame, railFollow.endFrame, frameCount);
+		if (fitted) return { kind: RAIL_SCHEDULE_RANGE, ...fitted };
+		return { kind: RAIL_SCHEDULE_OFF };
+	}
+	return { kind: RAIL_SCHEDULE_OFF };
+}
+
+/** is `frame` inside the clip? Both ends are inclusive. */
+export function activeAt(schedule, frame) {
+	if (!schedule || !finite(frame)) return false;
+	if (schedule.kind !== RAIL_SCHEDULE_RANGE && schedule.kind !== RAIL_SCHEDULE_LEGACY) return false;
+	return frame >= schedule.startFrame && frame <= schedule.endFrame;
+}
+
+/**
+ * Which camera owns `frame`? Kept deliberately separate from
+ * resolveRailSchedule so the caller passes explicit rail usability (the
+ * built geometry, not just the stored points) and the resolved schedule.
+ *
+ *   follow off            -> none (keys/free hold as before)
+ *   no usable geometry    -> none (free follow owns the whole clip)
+ *   off / too-short / none-> none
+ *   inside the clip       -> rail
+ *   outside the clip      -> keys (the caller's existing no-keys fallback
+ *                             to free/hold applies as before)
+ */
+export function railCameraOwner({ followEnabled, railUsable, schedule, frame }) {
+	if (followEnabled !== true || !railUsable) return RAIL_OWNER_NONE;
+	if (activeAt(schedule, frame)) return RAIL_OWNER_RAIL;
+	if (schedule && (schedule.kind === RAIL_SCHEDULE_RANGE || schedule.kind === RAIL_SCHEDULE_LEGACY)) return RAIL_OWNER_KEYS;
+	return RAIL_OWNER_NONE;
+}

package/src/controls.jsx

@@ -49,13 +49,15 @@ export function aimAt(position, target) {
  * `getPivot()` is optional and returns a world point to orbit; without one,
  * Alt-drag orbits a point straight ahead of the lens.
  */
-export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange }) {
+export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange, onCameraChange }) {
 	const { gl } = useThree();
 	const keys = useRef(new Set());
 	const gesture = useRef(null); // { kind: "fly" | "pan" | "orbit", pointerId, x, y, ... }
 	const speedScale = useRef(1);
 	const flyStateRef = useRef(onFlyStateChange);
 	flyStateRef.current = onFlyStateChange;
+	const cameraChangeRef = useRef(onCameraChange);
+	cameraChangeRef.current = onCameraChange;
 	const pivotRef = useRef(getPivot);
 	pivotRef.current = getPivot;
 
@@ -102,6 +104,7 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 			// the fly speed set with the wheel persists between flights, as it does in Unity
 			element.style.cursor = "";
 			flyStateRef.current?.(false);
+			if (active.changed) cameraChangeRef.current?.();
 		};
 
 		const onPointerDown = (e) => {
@@ -116,7 +119,7 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 			e.stopPropagation();
 			const cam = camRef.current;
 			const pivot = kind === "orbit" && cam ? resolvePivot(cam) : null;
-			gesture.current = { kind, pointerId: e.pointerId, x: e.clientX, y: e.clientY, pivot };
+			gesture.current = { kind, pointerId: e.pointerId, x: e.clientX, y: e.clientY, pivot, changed: false };
 			element.setPointerCapture(e.pointerId);
 			element.focus();
 			element.style.cursor = kind === "fly" ? "crosshair" : kind === "pan" ? "grabbing" : "move";
@@ -145,6 +148,8 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 				look.current.yaw -= dx * LOOK_SENS;
 				look.current.pitch -= dy * LOOK_SENS;
 				look.current.pitch = THREE.MathUtils.clamp(look.current.pitch, -PITCH_LIMIT, PITCH_LIMIT);
+				active.changed = active.changed || dx !== 0 || dy !== 0;
+				if (dx !== 0 || dy !== 0) cameraChangeRef.current?.();
 				return;
 			}
 			if (active.kind === "pan") {
@@ -156,6 +161,8 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 				cam.position.addScaledVector(right, -dx * PAN_SENS * distance);
 				cam.position.addScaledVector(up, dy * PAN_SENS * distance);
 				cam.position.y = Math.max(cam.position.y, 0.12);
+				active.changed = active.changed || dx !== 0 || dy !== 0;
+				if (dx !== 0 || dy !== 0) cameraChangeRef.current?.();
 				return;
 			}
 			// orbit: swing the camera around the pivot, then re-aim at it so the
@@ -172,6 +179,8 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 			const angles = aimAt(cam.position, pivot);
 			look.current.yaw = angles.yaw;
 			look.current.pitch = angles.pitch;
+			active.changed = active.changed || dx !== 0 || dy !== 0;
+			if (dx !== 0 || dy !== 0) cameraChangeRef.current?.();
 		};
 
 		const onWheel = (e) => {
@@ -184,6 +193,7 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 				return;
 			}
 			cam.position.addScaledVector(forwardFrom(look.current.yaw, look.current.pitch), -e.deltaY * DOLLY_STEP);
+			cameraChangeRef.current?.();
 		};
 
 		// A right-drag is navigation, so the browser menu must not interrupt it.
@@ -239,6 +249,10 @@ export function FlyControls({ enabled, camRef, look, getPivot, onFlyStateChange
 		if (keys.current.has("e")) cam.position.y += crane;
 		if (keys.current.has("q")) cam.position.y -= crane;
 		cam.position.y = Math.max(cam.position.y, 0.12);
+		if (gesture.current) {
+			gesture.current.changed = true;
+			cameraChangeRef.current?.();
+		}
 	});
 
 	return null;