cozyclay 1.2.0 → 1.5.0

package/src/scenes.js

@@ -2,21 +2,47 @@
 // A Scene is the set; shotDocument and stage are sealed department envelopes.
 // This module stores and copies those envelopes but never opens or validates them.
 
-export const SCENES_VERSION = 2;
-export const SCENES_STORAGE_KEY = "cozyclay.scenes.v2";
-export const SCENES_QUARANTINE_KEY = "cozyclay.scenes.v2.quarantine";
-export const PREVIOUS_SCENES_STORAGE_KEY = "cozyclay.scenes.v1";
+import { DEFAULT_SENSOR_FORMAT, SENSOR_FORMATS } from "./shot.js";
+import { normalizeStableItems } from "./stable-items.js";
+
+export const SCENES_VERSION = 4;
+export const SCENES_STORAGE_KEY = "cozyclay.scenes.v4";
+export const SCENES_QUARANTINE_KEY = "cozyclay.scenes.v4.quarantine";
+export const PREVIOUS_SCENES_STORAGE_KEY = "cozyclay.scenes.v3";
+export const V2_SCENES_STORAGE_KEY = "cozyclay.scenes.v2";
+export const V1_SCENES_STORAGE_KEY = "cozyclay.scenes.v1";
 export const LEGACY_SCENE_STORAGE_KEY = "cozyclay.scene.v1";
+/** Newest-first fallback chain: a user arriving from any older build still
+ * finds their scenes, and the reader migrates whatever body it lands on. */
+export const LEGACY_SCENES_STORAGE_KEYS = Object.freeze([
+	PREVIOUS_SCENES_STORAGE_KEY,
+	V2_SCENES_STORAGE_KEY,
+	V1_SCENES_STORAGE_KEY,
+]);
+
+/** v3 and older authored every frame number on ARDY's 20 fps clock; v4 reads
+ * them on the 24 fps production clock. The numbers are MULTIPLIED, never
+ * reinterpreted: a waypoint at frame 40 meant 2.0 s and must still mean 2.0 s,
+ * which is frame 48 — reinterpreting it would silently speed the scene up. */
+export const LEGACY_FRAME_FPS = 20;
+export const TIMELINE_FRAME_FPS = 24;
+export const toTimelineFrame = (frame) =>
+	Math.round((frame * TIMELINE_FRAME_FPS) / LEGACY_FRAME_FPS);
+
+/** Rigged character models shipped in public/models. The id is both the FBX
+ * file stem and the wire `source.rig` value sent to ARDY. */
+export const CHARACTER_MODEL_IDS = Object.freeze(["y-bot-tpose", "x-bot-tpose"]);
+export const DEFAULT_CHARACTER_MODEL = "y-bot-tpose";
+export const DEFAULT_SUBJECT_ONE = "a young woman in a tan coat";
+export const DEFAULT_SUBJECT_TWO = "a man in a dark coat";
 
 export const DEFAULT_SCENE_STAGE = Object.freeze({
-	charA: Object.freeze({ x: 0, z: 0, rot: 0 }),
-	charB: Object.freeze({ x: 1.15, z: 0.1, rot: -14 }),
-	showB: false,
-	poseA: null,
-	poseB: null,
+	characters: Object.freeze([
+		Object.freeze({ id: "char-a", model: DEFAULT_CHARACTER_MODEL, x: 0, z: 0, rot: 0, hidden: false, pose: null, subject: DEFAULT_SUBJECT_ONE }),
+	]),
 	hasCharSheet: false,
-	subject: "a young woman in a tan coat",
-	subject2: "a man in a dark coat",
+	shotAspect: "16:9",
+	sensorId: DEFAULT_SENSOR_FORMAT,
 });
 
 let sceneSequence = 1;
@@ -49,17 +75,191 @@ function cloneValue(value, copies = new WeakMap()) {
 	return copy;
 }
 
+const finiteOr = (value, fallback) => (Number.isFinite(value) ? value : fallback);
+
+/** Stature band for a cast member. Wider than ardy/npz.js's mocap band
+ * (0.6-1.5, a sanity clamp on ESTIMATED statures): the gizmo's scale handles
+ * are a deliberate artistic ask, and a previs giant or child is legitimate. */
+export const CHARACTER_SCALE_MIN = 0.2;
+export const CHARACTER_SCALE_MAX = 3;
+const clampScale = (value) => (Number.isFinite(value) && value > 0
+	? Math.max(CHARACTER_SCALE_MIN, Math.min(CHARACTER_SCALE_MAX, value))
+	: 1);
+
+/** Where an extra extraction take's performer stands: the filmed offset from
+ * person 0, rotated into the ACTIVE character's facing. Pure geometry, so the
+ * placement can be proven without a renderer. */
+export function takeAnchor(active, offsetX, offsetZ) {
+	const rad = (finiteOr(active?.rot, 0) * Math.PI) / 180;
+	const dx = finiteOr(offsetX, 0);
+	const dz = finiteOr(offsetZ, 0);
+	return {
+		x: finiteOr(active?.x, 0) + dx * Math.cos(rad) + dz * Math.sin(rad),
+		z: finiteOr(active?.z, 0) - dx * Math.sin(rad) + dz * Math.cos(rad),
+	};
+}
+
+/** One character entry in the stage envelope. `source` may be a v3 entry, a
+ * partial (spawn dialog), or null — every field falls back to a sane default
+ * and every object is freshly owned by the caller. */
+export function createCharacterEntry(source = null, index = 0) {
+	const s = plainObject(source) ? source : {};
+	return {
+		id: typeof s.id === "string" && s.id ? s.id : `char-${index + 1}`,
+		model: CHARACTER_MODEL_IDS.includes(s.model) ? s.model : DEFAULT_CHARACTER_MODEL,
+		x: finiteOr(s.x, 0),
+		// Lift floors at the deck; there is deliberately no ceiling, so every
+		// writer (inspector field, viewport gizmo, load path) shares max(0, y).
+		y: Math.max(0, finiteOr(s.y, 0)),
+		z: finiteOr(s.z, 0),
+		rot: finiteOr(s.rot, 0),
+		hidden: s.hidden === true,
+		// User-picked body tint; null means "model default" (y-bot clay, x-bot
+		// whiter clay) so the entry survives future default tweaks.
+		tint: typeof s.tint === "string" && /^#[0-9a-fA-F]{6}$/.test(s.tint) ? s.tint : null,
+		pose: plainObject(s.pose) ? cloneValue(s.pose) : null,
+		// Stature multiplier: 1 is the canonical body, an extracted take carries
+		// the FILMED person's leg ratio. It persists with the entry because the
+		// take's root travel was authored against it — see the render path.
+		scale: clampScale(s.scale),
+		subject: typeof s.subject === "string" ? s.subject : index === 0 ? DEFAULT_SUBJECT_ONE : DEFAULT_SUBJECT_TWO,
+		// The character's animation layer: its own root path and prompt-block
+		// schedule. The generated clip itself is heavy, so only a lightweight
+		// reference (bridge URL + generation params) is persisted — enough to
+		// re-fetch and decode it on the next session.
+		layer: normalizeLayer(s.layer),
+		motionRef: normalizeMotionRef(s.motionRef),
+	};
+}
+
+function normalizeMotionRef(ref) {
+	if (!plainObject(ref) || typeof ref.url !== "string" || !ref.url) return null;
+	return {
+		url: ref.url,
+		prompt: typeof ref.prompt === "string" ? ref.prompt : "",
+		rotationDeg: Number.isFinite(ref.rotationDeg) ? ref.rotationDeg : 0,
+		anchorX: Number.isFinite(ref.anchorX) ? ref.anchorX : 0,
+		anchorZ: Number.isFinite(ref.anchorZ) ? ref.anchorZ : 0,
+	};
+}
+
+function normalizeLayer(layer) {
+	const source = plainObject(layer) ? layer : {};
+	return {
+		waypoints: normalizeStableItems(cloneValue(source.waypoints), "waypoint"),
+		promptClips: normalizeStableItems(cloneValue(source.promptClips), "prompt-clip"),
+	};
+}
+
+function normalizeStageLayers(stage) {
+	const source = plainObject(stage) ? stage : {};
+	const ids = new Set();
+	return {
+		...source,
+		characters: Array.isArray(source.characters)
+			? source.characters.map((character) => ({
+				...character,
+				layer: {
+					waypoints: normalizeStableItems(cloneValue(character.layer?.waypoints), "waypoint", ids),
+					promptClips: normalizeStableItems(cloneValue(character.layer?.promptClips), "prompt-clip", ids),
+				},
+			}))
+			: source.characters,
+	};
+}
+
+export function createCharacterLayer() {
+	return { waypoints: [], promptClips: [] };
+}
+
+/** Retime one animation layer from the 20 fps authoring clock onto the 24 fps
+ * production clock. Frame numbers only: positions, headings and prompt text
+ * are untouched. The mapping is strictly increasing, so ascending order and
+ * the gaps between prompt blocks survive it — the guards below re-establish
+ * both anyway, because a hand-edited body may never have had them. Prompt
+ * ranges are half-open [start, end), matching movePromptClipFrames: touching
+ * blocks are legal, overlapping ones are not. */
+function migrateLayerFrames(layer) {
+	if (!plainObject(layer)) return layer;
+	const next = { ...cloneValue(layer) };
+	if (Array.isArray(layer.waypoints)) {
+		const byFrame = new Map();
+		for (const waypoint of layer.waypoints) {
+			if (!plainObject(waypoint) || !Number.isFinite(waypoint.frame)) continue;
+			const frame = Math.max(0, toTimelineFrame(Math.round(waypoint.frame)));
+			byFrame.set(frame, { ...cloneValue(waypoint), frame });
+		}
+		next.waypoints = [...byFrame.values()].sort((a, b) => a.frame - b.frame);
+	}
+	if (Array.isArray(layer.promptClips)) {
+		const ordered = layer.promptClips
+			.filter((clip) => plainObject(clip) && Number.isFinite(clip.startFrame) && Number.isFinite(clip.endFrame))
+			.sort((a, b) => a.startFrame - b.startFrame);
+		const clips = [];
+		let floor = 0;
+		for (const clip of ordered) {
+			const startFrame = Math.max(floor, toTimelineFrame(Math.round(clip.startFrame)));
+			const endFrame = Math.max(startFrame, toTimelineFrame(Math.round(clip.endFrame)));
+			clips.push({ ...cloneValue(clip), startFrame, endFrame });
+			floor = endFrame;
+		}
+		next.promptClips = clips;
+	}
+	return next;
+}
+
+/** v3 → v4 for one stage envelope: every frame-bearing number in every cast
+ * member's layer moves onto the production clock. Exported because a project
+ * FILE carries its own scene document and needs the same migration. */
+export function migrateStageFrames(stage) {
+	if (!plainObject(stage) || !Array.isArray(stage.characters)) return stage;
+	return {
+		...stage,
+		characters: stage.characters.map((entry) => (plainObject(entry) && plainObject(entry.layer)
+			? { ...entry, layer: migrateLayerFrames(entry.layer) }
+			: entry)),
+	};
+}
+
+/** Stage envelopes before v3 stored a fixed cast (charA/charB/showB/poseA/
+ * poseB/subject/subject2). Fold that cast into the characters list so the
+ * rest of the app only ever sees one shape. */
+function migrateLegacyCast(source) {
+	const cast = [createCharacterEntry({ ...plainObject(source.charA) ? source.charA : {}, id: "char-a", pose: source.poseA ?? null, subject: source.subject ?? DEFAULT_SUBJECT_ONE }, 0)];
+	if (source.showB === true) {
+		cast.push(createCharacterEntry({ ...plainObject(source.charB) ? source.charB : {}, id: "char-b", pose: source.poseB ?? null, subject: source.subject2 ?? DEFAULT_SUBJECT_TWO }, 1));
+	}
+	return cast;
+}
+
+const STAGE_ENVELOPE_KEYS = new Set([
+	"characters", "hasCharSheet", "shotAspect", "sensorId",
+	"charA", "charB", "showB", "poseA", "poseB", "subject", "subject2",
+]);
+
 export function createSceneStage(stage = null) {
 	const source = plainObject(stage) ? stage : {};
+	const characters = Array.isArray(source.characters) && source.characters.length
+		? source.characters.map((entry, index) => createCharacterEntry(entry, index))
+		: migrateLegacyCast(source);
+	// Unknown extra keys (shotAspect was one, once) ride along so the envelope
+	// stays sealed-but-lossless; legacy cast keys are deliberately dropped.
+	const extras = {};
+	for (const [key, value] of Object.entries(source)) {
+		if (!STAGE_ENVELOPE_KEYS.has(key)) extras[key] = cloneValue(value);
+	}
 	return {
-		...cloneValue(DEFAULT_SCENE_STAGE),
-		...cloneValue(source),
-		charA: { ...cloneValue(DEFAULT_SCENE_STAGE.charA), ...cloneValue(plainObject(source.charA) ? source.charA : {}) },
-		charB: { ...cloneValue(DEFAULT_SCENE_STAGE.charB), ...cloneValue(plainObject(source.charB) ? source.charB : {}) },
-		showB: source.showB === true,
+		...extras,
+		characters,
 		hasCharSheet: source.hasCharSheet === true,
-		subject: typeof source.subject === "string" ? source.subject : DEFAULT_SCENE_STAGE.subject,
-		subject2: typeof source.subject2 === "string" ? source.subject2 : DEFAULT_SCENE_STAGE.subject2,
+		shotAspect: ["16:9", "2.39:1", "9:16", "1:1", "4:3"].includes(source.shotAspect)
+			? source.shotAspect
+			: DEFAULT_SCENE_STAGE.shotAspect,
+		// `sensorFormat` was this field's name for one unreleased day; read it so
+		// a stage saved in that window still loads with its camera intact.
+		sensorId: Object.hasOwn(SENSOR_FORMATS, source.sensorId ?? source.sensorFormat)
+			? (source.sensorId ?? source.sensorFormat)
+			: DEFAULT_SCENE_STAGE.sensorId,
 	};
 }
 
@@ -139,23 +339,26 @@ export function createSceneDocument() {
 	return { version: SCENES_VERSION, activeSceneId: scene.id, scenes: [scene] };
 }
 
-function repairScene(record, existing, fallbackNumber, fallbackStage) {
+function repairScene(record, existing, fallbackNumber, fallbackStage, legacyClock = false) {
 	if (!plainObject(record) || typeof record.id !== "string" || !record.id || !Array.isArray(record.objects)) return null;
 	if (existing.some((scene) => scene.id === record.id)) return null;
+	const stage = normalizeStageLayers(createSceneStage(cloneValue(plainObject(record.stage) ? record.stage : fallbackStage)));
 	return {
 		id: record.id,
 		name: uniqueName(typeof record.name === "string" ? record.name : `SCENE ${String(fallbackNumber).padStart(2, "0")}`, existing),
 		objects: record.objects.filter(plainObject).map((object) => cloneValue(object)),
+		// The shot document is a sealed envelope with its OWN version, and it
+		// migrates its own frames when its reader opens it.
 		shotDocument: cloneValue(record.shotDocument ?? null),
-		stage: cloneValue(plainObject(record.stage) ? record.stage : fallbackStage),
+		stage: legacyClock ? migrateStageFrames(stage) : stage,
 	};
 }
 
-function repairDocument(payload, fallbackStage = DEFAULT_SCENE_STAGE) {
+function repairDocument(payload, fallbackStage = DEFAULT_SCENE_STAGE, legacyClock = false) {
 	const scenes = [];
 	let dropped = 0;
 	for (const record of payload.scenes) {
-		const scene = repairScene(record, scenes, scenes.length + 1, fallbackStage);
+		const scene = repairScene(record, scenes, scenes.length + 1, fallbackStage, legacyClock);
 		if (scene) scenes.push(scene);
 		else dropped += 1;
 	}
@@ -197,7 +400,11 @@ export function readSceneDocument(raw, legacyRaw = null) {
 		return { status: "corrupt", document: createSceneDocument(), dropped: 0, quarantineRaw: raw };
 	}
 	const migrating = payload.version < SCENES_VERSION;
-	const repaired = repairDocument(payload, createSceneStage(payload.stage));
+	// Anything below v4 was authored while the timeline ran at 20 fps. The
+	// fallback stage (a v1 global cast) rides the same conversion, applied
+	// once, inside repairScene — whichever stage that scene ends up with.
+	const legacyClock = payload.version < 4;
+	const repaired = repairDocument(payload, createSceneStage(payload.stage), legacyClock);
 	return { status: migrating ? "migrated" : "valid", ...repaired };
 }
 
@@ -208,9 +415,11 @@ export function serializeSceneDocument(document) {
 /** Storage adapter: quarantine corrupt bytes, persist successful migration,
  * and never write over a future document. The legacy key remains as a backup. */
 export function loadSceneDocumentFromStorage(storage) {
-	const currentRaw = storage.getItem(SCENES_STORAGE_KEY);
-	const previousRaw = currentRaw ? null : storage.getItem(PREVIOUS_SCENES_STORAGE_KEY);
-	const raw = currentRaw || previousRaw;
+	let raw = storage.getItem(SCENES_STORAGE_KEY);
+	for (const key of LEGACY_SCENES_STORAGE_KEYS) {
+		if (raw) break;
+		raw = storage.getItem(key);
+	}
 	const legacyRaw = raw ? null : storage.getItem(LEGACY_SCENE_STORAGE_KEY);
 	const result = readSceneDocument(raw, legacyRaw);
 	if (result.status === "corrupt" && result.quarantineRaw !== undefined) {

package/src/shot-authoring.js

@@ -5,32 +5,72 @@
  */
 
 import { createShot } from "./cuts.js";
+import { normalizeStableItems } from "./stable-items.js";
 
-export const SHOT_AUTHORING_VERSION = 3;
-export const SHOT_AUTHORING_KEY = "cozyclay.shot-authoring.v3";
+export const SHOT_AUTHORING_VERSION = 4;
+export const SHOT_AUTHORING_KEY = "cozyclay.shot-authoring.v4";
 // The single-key alias points at the newest legacy body for older callers.
 // New readers should walk the list so a user can still arrive directly from v1.
-export const SHOT_AUTHORING_LEGACY_KEY = "cozyclay.shot-authoring.v2";
+export const SHOT_AUTHORING_LEGACY_KEY = "cozyclay.shot-authoring.v3";
 export const SHOT_AUTHORING_LEGACY_KEYS = Object.freeze([
 	SHOT_AUTHORING_LEGACY_KEY,
+	"cozyclay.shot-authoring.v2",
 	"cozyclay.shot-authoring.v1",
 ]);
-export const SHOT_AUTHORING_QUARANTINE_KEY = "cozyclay.shot-authoring.v3.quarantine";
+export const SHOT_AUTHORING_QUARANTINE_KEY = "cozyclay.shot-authoring.v4.quarantine";
 
-/** clip length sanity bounds, frames @ 20 fps: 1 s .. 20 min */
-const FRAME_COUNT_MIN = 20;
-const FRAME_COUNT_MAX = 24000;
-const DEFAULT_FRAME_COUNT = 120;
+/** clip length sanity bounds, frames @ 24 fps: 1 s .. 20 min */
+const FRAME_COUNT_MIN = 24;
+const FRAME_COUNT_MAX = 28800;
+const DEFAULT_FRAME_COUNT = 144;
 const RAIL_MAX_POINTS = 512;
 const finite = Number.isFinite;
 
+/** v3 and older bodies counted frames on ARDY's 20 fps clock; v4 counts them
+ * on the 24 fps production clock. Every frame-bearing number is multiplied so
+ * a saved roll keeps its DURATION: a 300-frame clip was 15 s and stays 15 s as
+ * 360 frames. Reinterpreting instead would silently shorten it to 12.5 s. */
+const LEGACY_FRAME_FPS = 20;
+const TIMELINE_FRAME_FPS = 24;
+const toTimelineFrame = (frame) => Math.round((frame * TIMELINE_FRAME_FPS) / LEGACY_FRAME_FPS);
+const rescaleFrame = (value) => (finite(value) ? toTimelineFrame(value) : value);
+const rescaleKeys = (entries) => (Array.isArray(entries)
+	? entries.map((key) => (key && typeof key === "object" ? { ...key, frame: rescaleFrame(key.frame) } : key))
+	: entries);
+const rescaleRailFollow = (value) => (value && typeof value === "object" && !Array.isArray(value)
+	? { ...value, startFrame: rescaleFrame(value.startFrame), endFrame: rescaleFrame(value.endFrame) }
+	: value);
+
+/** Retime a whole parsed body before the ordinary repair runs, so the version
+ * migrations below only ever see production-clock numbers. Rail geometry,
+ * follow gains and framings carry no frames and are passed through. */
+function rescaleShotAuthoringFrames(parsed) {
+	const next = { ...parsed, frameCount: rescaleFrame(parsed.frameCount) };
+	if (Array.isArray(parsed.cameraKeys)) next.cameraKeys = rescaleKeys(parsed.cameraKeys);
+	if (Array.isArray(parsed.waypoints)) next.waypoints = rescaleKeys(parsed.waypoints);
+	if (parsed.railFollow !== undefined) next.railFollow = rescaleRailFollow(parsed.railFollow);
+	if (Array.isArray(parsed.shots)) {
+		next.shots = parsed.shots.map((shot) => {
+			if (!shot || typeof shot !== "object") return shot;
+			const moved = { ...shot, startFrame: rescaleFrame(shot.startFrame), endFrame: rescaleFrame(shot.endFrame) };
+			if (Array.isArray(shot.cameraKeys)) moved.cameraKeys = rescaleKeys(shot.cameraKeys);
+			if (shot.camera && typeof shot.camera === "object" && !Array.isArray(shot.camera)) {
+				moved.camera = { ...shot.camera, railFollow: rescaleRailFollow(shot.camera.railFollow) };
+			}
+			return moved;
+		});
+	}
+	return next;
+}
+
 const FOLLOW_BOUNDS = {
 	distance: [0.5, 15],
-	height: [0.2, 6],
+	height: [0.2, Number.POSITIVE_INFINITY],
 	response: [0.1, 3],
 	lead: [0, 1],
 	maxDollySpeed: [0.2, 8],
-	pitchOffsetDeg: [-30, 30],
+	pitchOffsetDeg: [-170, 170],
+	orbitOffsetDeg: [-180, 180],
 };
 const FOLLOW_DEFAULTS = {
 	distance: 3,
@@ -40,6 +80,7 @@ const FOLLOW_DEFAULTS = {
 	railStartMode: "head",
 	maxDollySpeed: 4,
 	pitchOffsetDeg: 0,
+	orbitOffsetDeg: 0,
 };
 const CAMERA_MODES = new Set(["keys", "follow", "rail"]);
 
@@ -55,12 +96,13 @@ function repairFrameCount(value) {
 	return finite(value) ? Math.max(FRAME_COUNT_MIN, Math.min(FRAME_COUNT_MAX, Math.round(value))) : null;
 }
 
-function repairKeys(entries, minFrame, maxFrame) {
+function repairKeys(entries, minFrame, maxFrame, ids = new Set()) {
 	const byFrame = new Map();
-	for (const key of Array.isArray(entries) ? entries : []) {
-		if (!key || !finite(key.frame) || !validFraming(key.framing)) continue;
+	for (const key of normalizeStableItems(entries, "camera-key", ids)) {
+		if (!finite(key.frame) || !validFraming(key.framing)) continue;
 		const frame = Math.max(minFrame, Math.min(maxFrame, Math.round(key.frame)));
 		byFrame.set(frame, {
+			id: key.id,
 			frame,
 			framing: {
 				pos: { x: key.framing.pos.x, y: key.framing.pos.y, z: key.framing.pos.z },
@@ -73,7 +115,7 @@ function repairKeys(entries, minFrame, maxFrame) {
 	return [...byFrame.values()].sort((a, b) => a.frame - b.frame);
 }
 
-function repairShots(entries, frameCount, inheritedCamera = null) {
+function repairShots(entries, frameCount, inheritedCamera = null, ids = new Set()) {
 	const candidates = [];
 	for (const entry of Array.isArray(entries) ? entries : []) {
 		if (!entry || typeof entry !== "object" || !finite(entry.startFrame)) continue;
@@ -85,34 +127,35 @@ function repairShots(entries, frameCount, inheritedCamera = null) {
 
 	// One boundary per frame. The later stored entry wins, just like re-keying.
 	const byStart = new Map(candidates.map((candidate) => [candidate.startFrame, candidate.entry]));
-	const ordered = [...byStart.entries()].sort((a, b) => a[0] - b[0]);
-	const seenIds = new Set();
-	return ordered.map(([startFrame, entry], index) => {
-		const nextStart = ordered[index + 1]?.[0] ?? frameCount;
+	const ordered = normalizeStableItems(
+		[...byStart.entries()].sort((a, b) => a[0] - b[0]).map(([startFrame, entry]) => ({ ...entry, startFrame })),
+		"shot",
+		ids,
+	);
+	return ordered.map((entry, index) => {
+		const startFrame = entry.startFrame;
+		const nextStart = ordered[index + 1]?.startFrame ?? frameCount;
 		// Pre-overlay v3 bodies had no endFrame and were gapless by definition.
 		// Infer their old boundary exactly; new bodies persist an explicit end.
 		const storedEnd = finite(entry.endFrame) ? Math.round(entry.endFrame) : nextStart - 1;
 		const endFrame = Math.max(startFrame, Math.min(frameCount - 1, nextStart - 1, storedEnd));
-		const fallback = createShot(`Shot ${index + 1}`, startFrame, endFrame);
-		const storedId = typeof entry.id === "string" && entry.id.trim() && !seenIds.has(entry.id) ? entry.id : fallback.id;
-		seenIds.add(storedId);
 		return {
-			id: storedId,
+			id: entry.id,
 			name: typeof entry.name === "string" && entry.name.trim() ? entry.name.trim() : `Shot ${index + 1}`,
 			startFrame,
 			endFrame,
-			cameraKeys: repairKeys(entry.cameraKeys, startFrame, endFrame),
+			cameraKeys: repairKeys(entry.cameraKeys, startFrame, endFrame, ids),
 			camera: repairCamera(inheritedCamera ?? entry.camera),
 		};
 	});
 }
 
-function repairWaypoints(entries) {
+function repairWaypoints(entries, ids = new Set()) {
 	const byFrame = new Map();
-	for (const waypoint of Array.isArray(entries) ? entries : []) {
-		if (!waypoint || !finite(waypoint.frame) || waypoint.frame < 0 || !finite(waypoint.x) || !finite(waypoint.z)) continue;
+	for (const waypoint of normalizeStableItems(entries, "waypoint", ids)) {
+		if (!finite(waypoint.frame) || waypoint.frame < 0 || !finite(waypoint.x) || !finite(waypoint.z)) continue;
 		const frame = Math.round(waypoint.frame);
-		byFrame.set(frame, { frame, x: waypoint.x, z: waypoint.z, heading: finite(waypoint.heading) ? waypoint.heading : null });
+		byFrame.set(frame, { id: waypoint.id, frame, x: waypoint.x, z: waypoint.z, heading: finite(waypoint.heading) ? waypoint.heading : null });
 	}
 	return [...byFrame.values()].sort((a, b) => a.frame - b.frame);
 }
@@ -143,6 +186,27 @@ function repairRailFollow(value) {
 	return startFrame <= endFrame ? { mode: "range", startFrame, endFrame } : null;
 }
 
+/** The crane axis rides the rail's arc; mirrors camera-block.js's normalization. */
+function repairCraneHeight(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = Array.isArray(value.points)
+		? value.points
+		: finite(value.start) && finite(value.end)
+			? [{ t: 0, height: value.start }, { t: 1, height: value.end }]
+			: null;
+	if (!raw) return null;
+	const cleaned = raw
+		.filter((point) => point && finite(point.t) && finite(point.height))
+		.map((point) => ({ t: Math.max(0, Math.min(1, point.t)), height: Math.max(0.1, point.height) }))
+		.sort((a, b) => a.t - b.t)
+		.filter((point, i, arr) => i === arr.length - 1 || arr[i + 1].t - point.t > 1e-6)
+		.slice(0, 8);
+	if (cleaned.length < 2) return null;
+	cleaned[0] = { ...cleaned[0], t: 0 };
+	cleaned[cleaned.length - 1] = { ...cleaned[cleaned.length - 1], t: 1 };
+	return { points: cleaned };
+}
+
 function repairCamera(value) {
 	const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
 	const cameraRail = repairRail(source.cameraRail);
@@ -150,7 +214,14 @@ function repairCamera(value) {
 	// A rail block without a usable two-point rail behaves like ordinary
 	// follow, never like a mysteriously enabled but motionless dolly.
 	if (mode === "rail" && !cameraRail) mode = "follow";
-	return { mode, followCam: repairFollowCam(source.followCam), cameraRail, railFollow: repairRailFollow(source.railFollow) };
+	return {
+		mode,
+		followCam: repairFollowCam(source.followCam),
+		cameraRail,
+		railFollow: repairRailFollow(source.railFollow),
+		// A crane cannot outlive the rail it rides.
+		craneHeight: cameraRail ? repairCraneHeight(source.craneHeight) : null,
+	};
 }
 
 function migratedCamera(followCam, cameraRail, railFollow = null) {
@@ -164,10 +235,10 @@ function migratedCamera(followCam, cameraRail, railFollow = null) {
 	});
 }
 
-function repairShared(parsed, frameCount) {
+function repairShared(parsed, frameCount, ids) {
 	return {
 		frameCount,
-		waypoints: repairWaypoints(parsed.waypoints),
+		waypoints: repairWaypoints(parsed.waypoints, ids),
 	};
 }
 
@@ -178,45 +249,53 @@ function repairShared(parsed, frameCount) {
 export function createShotAuthoringDocument({ shots = [], waypoints = [], frameCount = null } = {}) {
 	const repairedFrameCount = repairFrameCount(frameCount);
 	const effectiveFrameCount = repairedFrameCount ?? DEFAULT_FRAME_COUNT;
+	const ids = new Set();
 	return {
 		version: SHOT_AUTHORING_VERSION,
 		frameCount: repairedFrameCount,
-		shots: repairShots(shots, effectiveFrameCount),
-		waypoints: repairWaypoints(waypoints),
+		waypoints: repairWaypoints(waypoints, ids),
+		shots: repairShots(shots, effectiveFrameCount, null, ids),
 	};
 }
 
 /** Pure object reader; storage adapters decide how bytes become this object. */
-export function readShotAuthoringDocument(parsed) {
-	if (parsed === undefined) return { status: "absent", state: null };
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { status: "corrupt", state: null };
-	const version = parsed.version === undefined ? 1 : parsed.version;
+export function readShotAuthoringDocument(raw) {
+	if (raw === undefined) return { status: "absent", state: null };
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { status: "corrupt", state: null };
+	const version = raw.version === undefined ? 1 : raw.version;
 	if (!Number.isInteger(version) || version < 1) return { status: "corrupt", state: null };
 	if (version > SHOT_AUTHORING_VERSION) return { status: "future", state: null };
 
+	// One conversion at the door: everything below reads one clock.
+	const parsed = version < 4 ? rescaleShotAuthoringFrames(raw) : raw;
 	const frameCount = repairFrameCount(parsed.frameCount);
 	const effectiveFrameCount = frameCount ?? DEFAULT_FRAME_COUNT;
 	if (version === 1) {
-		const keys = repairKeys(parsed.cameraKeys, 0, effectiveFrameCount - 1);
+		const ids = new Set();
+		const keys = repairKeys(parsed.cameraKeys, 0, effectiveFrameCount - 1, ids);
 		const camera = migratedCamera(parsed.followCam, parsed.cameraRail, parsed.railFollow);
 		// v1 was one whole-timeline camera roll even when it had no keys.
 		const shots = [createShot("Shot 1", 0, effectiveFrameCount - 1, keys, repairCamera(camera))];
 		return {
 			status: "migrated",
-			state: { ...repairShared(parsed, frameCount), shots },
+			state: { ...repairShared(parsed, frameCount, ids), shots },
 		};
 	}
 	if (!Array.isArray(parsed.shots)) return { status: "corrupt", state: null };
 	if (version === 2) {
+		const ids = new Set();
 		const camera = migratedCamera(parsed.followCam, parsed.cameraRail, parsed.railFollow);
 		return {
 			status: "migrated",
-			state: { ...repairShared(parsed, frameCount), shots: repairShots(parsed.shots, effectiveFrameCount, camera) },
+			state: { ...repairShared(parsed, frameCount, ids), shots: repairShots(parsed.shots, effectiveFrameCount, camera, ids) },
 		};
 	}
+	const ids = new Set();
 	return {
-		status: "valid",
-		state: { ...repairShared(parsed, frameCount), shots: repairShots(parsed.shots, effectiveFrameCount) },
+		// A v3 body is structurally current but was authored on the old clock;
+		// it is rewritten, so it reports as migrated, not valid.
+		status: version < SHOT_AUTHORING_VERSION ? "migrated" : "valid",
+		state: { ...repairShared(parsed, frameCount, ids), shots: repairShots(parsed.shots, effectiveFrameCount, null, ids) },
 	};
 }