cozyclay 1.2.0 → 1.3.0

package/src/scenes.js

@@ -2,21 +2,43 @@
 // 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";
+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",
 });
 
 let sceneSequence = 1;
@@ -49,17 +71,167 @@ 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),
+		y: 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: Array.isArray(source.waypoints) ? cloneValue(source.waypoints) : [],
+		promptClips: Array.isArray(source.promptClips) ? cloneValue(source.promptClips) : [],
+	};
+}
+
+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",
+	"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", "9:16", "1:1", "4:3"].includes(source.shotAspect)
+			? source.shotAspect
+			: DEFAULT_SCENE_STAGE.shotAspect,
 	};
 }
 
@@ -139,23 +311,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 = 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 +372,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 +387,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

@@ -6,24 +6,62 @@
 
 import { createShot } from "./cuts.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],
@@ -187,13 +225,15 @@ export function createShotAuthoringDocument({ shots = [], waypoints = [], frameC
 }
 
 /** 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) {
@@ -215,7 +255,9 @@ export function readShotAuthoringDocument(parsed) {
 		};
 	}
 	return {
-		status: "valid",
+		// 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), shots: repairShots(parsed.shots, effectiveFrameCount) },
 	};
 }