cozyclay 2.0.0 → 2.1.0

package/src/project.js

@@ -16,8 +16,17 @@
 
 import { SCENES_VERSION } from "./scenes.js";
 import { ASSET_MAX_SOURCE_BYTES, assetIdForBytes, isAssetId, isImageAssetId, isMeshAssetId, meshIdForBytes, normalizeAsset, referencedAssetIds } from "./scene-assets.js";
+import { ko } from "./locale.js";
 
-export const PROJECT_VERSION = 4;
+export const PROJECT_VERSION = 5;
+// A project is authored either as a storyboard (stills) or as animation
+// (clips). v5 records the choice on the envelope; v2-v4 files are animation.
+export const PREVIS_MODES = Object.freeze(["storyboard", "animation"]);
+export const DEFAULT_PREVIS_MODE = "animation";
+
+export function normalizePrevisMode(value) {
+	return PREVIS_MODES.includes(value) ? value : DEFAULT_PREVIS_MODE;
+}
 export const PROJECT_EXTENSION = ".cclayproject";
 export const WORKFLOW_VERSION = 1;
 export const WORKFLOW_STORAGE_KEY = "cozyclay.workflow.v1";
@@ -32,8 +41,6 @@ export const PROJECT_MAX_RESOURCE_BYTES = 256 * 1024 * 1024;
 // A motion id is the SHA-256 of the raw NPZ bytes (see motion-resources.js).
 const MOTION_ID_PATTERN = /^[0-9a-f]{64}$/i;
 
-/* ---------------------------- workflow graph --------------------------- */
-
 function plainRecord(value) {
 	if (!value || typeof value !== "object") return false;
 	const prototype = Object.getPrototypeOf(value);
@@ -132,11 +139,14 @@ export function normalizeWorkflowGraph(value) {
 	return { version: WORKFLOW_VERSION, nodes, edges };
 }
 
-/** Read the browser-local workflow draft used by the standalone canvas. */
-export function loadWorkflowGraph(storage = globalThis.localStorage) {
+/** Read the browser-local workflow draft used by the standalone canvas.
+ * A corrupt draft reads as an empty graph unless `strict`, which rethrows the
+ * parse error so a caller about to write can refuse to overwrite it. */
+export function loadWorkflowGraph(storage = globalThis.localStorage, { strict = false } = {}) {
 	try {
 		return normalizeWorkflowGraph(JSON.parse(storage?.getItem(WORKFLOW_STORAGE_KEY) || "null"));
-	} catch {
+	} catch (error) {
+		if (strict) throw error;
 		return createWorkflowGraph();
 	}
 }
@@ -155,8 +165,6 @@ export function storeWorkflowGraph(graph, storage = globalThis.localStorage) {
 	return normalized;
 }
 
-/* ------------------------------- envelope ------------------------------- */
-
 function asArrayBuffer(bytes) {
 	if (bytes instanceof ArrayBuffer) return bytes;
 	if (ArrayBuffer.isView(bytes)) return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
@@ -362,13 +370,13 @@ function readEmbeddedMotions(value, report) {
 }
 
 /**
- * Build the v4 envelope. Images are embedded when a scene or workflow
+ * Build the v5 envelope. Images are embedded when a scene or workflow
  * assetRef references them; motions are embedded as given (deduped by
  * motionId, first record wins) because the caller already knows which ones
  * the project uses. Throws `resources-too-large` when one motion or the whole
  * manifest exceeds its budget.
  */
-export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, assets, motions, savedAt, workflow }) {
+export function createProjectDocument({ scenesDocument, workspaceLayout, customPoses, name, previsMode, assets, motions, savedAt, workflow }) {
 	const assetRecords = new Map();
 	for (const record of Array.isArray(assets) ? assets : []) {
 		const asset = embeddedAsset(record);
@@ -404,6 +412,7 @@ export function createProjectDocument({ scenesDocument, workspaceLayout, customP
 		kind: "project",
 		version: PROJECT_VERSION,
 		name: typeof name === "string" && name.trim() ? name.trim() : "Untitled",
+		previsMode: normalizePrevisMode(previsMode),
 		...(Number.isFinite(savedAt) && savedAt > 0 ? { savedAt } : {}),
 		scenes: scenesDocument,
 		workspace: workspaceLayout ?? null,
@@ -413,12 +422,43 @@ export function createProjectDocument({ scenesDocument, workspaceLayout, customP
 	};
 }
 
+/** Convert a normalized storyboard project into a fresh animation envelope.
+ * The source remains untouched: still shot records are copied with their
+ * ranges, camera keys, captions, cast overrides and stylized asset references.
+ */
+export function buildAnimationProjectFromStoryboard(project) {
+	const scenesDocument = structuredClone(project?.scenesDocument ?? { version: SCENES_VERSION, activeSceneId: null, scenes: [] });
+	scenesDocument.scenes = (scenesDocument.scenes ?? []).map((scene) => ({
+		...scene,
+		shotDocument: scene.shotDocument && typeof scene.shotDocument === "object"
+			? {
+				...scene.shotDocument,
+				shots: Array.isArray(scene.shotDocument.shots)
+					? scene.shotDocument.shots.map((shot) => ({ ...shot, ...(shot.kind === "still" ? { kind: "clip" } : {}) }))
+					: scene.shotDocument.shots,
+			}
+			: scene.shotDocument,
+	}));
+	return createProjectDocument({
+		scenesDocument,
+		workspaceLayout: structuredClone(project?.workspaceLayout ?? null),
+		customPoses: structuredClone(project?.customPoses ?? []),
+		name: `${project?.name || "Untitled"} - ${ko("Animation", "애니메이션")}`,
+		previsMode: "animation",
+		assets: project?.assets ?? [],
+		motions: project?.motions ?? [],
+		workflow: structuredClone(project?.workflow ?? createWorkflowGraph()),
+		savedAt: Date.now(),
+	});
+}
+
 /**
  * Parse + validate a project file. Returns { ok, reason?, warnings?,
  * problems?, project? }. Invalid embedded records are skipped, each one
  * reported as a warning string and a `{ kind, id, code, message }` problem.
  * v2/v3 files carry images at the top-level `assets`; v4 moves everything
- * under `resources`. Older files are read as-is, never rewritten.
+ * under `resources`; v5 adds the top-level `previsMode` (absent or unknown
+ * reads as the default). Older files are read as-is, never rewritten.
  */
 export function readProjectDocument(raw) {
 	let parsed;
@@ -452,6 +492,7 @@ export function readProjectDocument(raw) {
 		problems,
 		project: {
 			name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : "Untitled",
+			previsMode: normalizePrevisMode(parsed.previsMode),
 			savedAt: Number.isFinite(parsed.savedAt) && parsed.savedAt > 0 ? parsed.savedAt : null,
 			scenesDocument: { version: scenes.version, activeSceneId: scenes.activeSceneId ?? null, scenes: scenes.scenes },
 			workspaceLayout: parsed.workspace && typeof parsed.workspace === "object" ? parsed.workspace : null,
@@ -465,8 +506,6 @@ export function readProjectDocument(raw) {
 	};
 }
 
-/* ------------------------- file system access --------------------------- */
-
 export function hasFileSystemAccess() {
 	return typeof window !== "undefined" && typeof window.showSaveFilePicker === "function" && typeof window.showOpenFilePicker === "function";
 }
@@ -502,8 +541,6 @@ export async function readProjectFile(handle) {
 	return { name: file.name.replace(/\.cclayproject$|\.json$/i, ""), text: await file.text(), savedAt: file.lastModified };
 }
 
-/* --------------------------- fallback (no FS API) ------------------------ */
-
 export function downloadProjectFallback(serialized, name) {
 	const blob = new Blob([serialized], { type: "application/json" });
 	const url = URL.createObjectURL(blob);
@@ -529,8 +566,6 @@ export function openProjectFallback() {
 	});
 }
 
-/* ------------------------------- IDB handle ------------------------------ */
-
 function openIdb() {
 	return new Promise((resolve, reject) => {
 		const request = indexedDB.open(IDB_NAME, 1);
@@ -605,27 +640,23 @@ export function loadProjectSession(storage = globalThis.localStorage) {
 		const value = JSON.parse(storage?.getItem(PROJECT_SESSION_KEY) || "null");
 		if (!value || typeof value !== "object") return null;
 		const name = typeof value.name === "string" ? value.name.trim() : "";
-		return name ? { name, updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
+		return name ? { name, previsMode: normalizePrevisMode(value.previsMode), updatedAt: Number.isFinite(value.updatedAt) ? value.updatedAt : 0 } : null;
 	} catch {
 		return null;
 	}
 }
 
-export function storeProjectSession(name, storage = globalThis.localStorage) {
+export function storeProjectSession(name, previsMode = DEFAULT_PREVIS_MODE, storage = globalThis.localStorage) {
 	const normalized = typeof name === "string" ? name.trim() : "";
 	if (!normalized) return false;
 	try {
-		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, updatedAt: Date.now() }));
+		storage?.setItem(PROJECT_SESSION_KEY, JSON.stringify({ name: normalized, previsMode: normalizePrevisMode(previsMode), updatedAt: Date.now() }));
 		return true;
 	} catch {
 		return false;
 	}
 }
 
-export function clearProjectSession(storage = globalThis.localStorage) {
-	try { storage?.removeItem(PROJECT_SESSION_KEY); } catch { /* private mode */ }
-}
-
 async function idbSet(key, value) {
 	try {
 		const db = await openIdb();

package/src/props.jsx

@@ -12,12 +12,16 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useFrame } from "@react-three/fiber";
 import { objectTransformAt } from "./object-path.js";
+import { sceneObjectCarryMatrixAt, sceneObjectTravelMatrixAt, travelPose } from "./object-travel.js";
 import * as THREE from "three";
 import { GIZMO_LAYER } from "./dualview.jsx";
-import { CUTOUT_KIND, MESH_KIND } from "./scene-objects.js";
+import { CUTOUT_KIND, MESH_KIND, EMPTY_KIND, EMPTY_MARKER_SIZE, SCULPT_KIND } from "./scene-objects.js";
+import { buildSculptGroup, disposeSculptGroup } from "./sculpt-geometry.js";
 import { subscribeToAssetTexture } from "./scene-asset-cache.js";
 import { subscribeToMeshScene } from "./scene-mesh-cache.js";
 import { cloneMeshGraph } from "./mesh-graph-clone.js";
+import { applyPoseFade } from "./pose-fade.js";
+import { coplanarDepthRanks } from "./coplanar-depth.js";
 
 const CLAY_CAR = "#d98770";
 const CLAY_CAR_TOP = "#e49a84";
@@ -56,27 +60,22 @@ export function Car({ position = [0, 0, 0], rotY = 0, color = CLAY_CAR, topColor
 		: { color: topColor, roughness: 0.5, metalness: 0.2 };
 	return (
 		<group position={position} rotation={[0, rotY, 0]}>
-			{/* lower body */}
 			<mesh position={[0, 0.62, 0]}>
 				<boxGeometry args={[1.78, 0.62, 4.45]} />
 				<meshStandardMaterial {...bodyMaterial} />
 			</mesh>
-			{/* cabin: centred over the wheelbase, not stacked on the tail */}
 			<mesh position={[0, 1.12, -0.15]}>
 				<boxGeometry args={[1.58, 0.5, 2.2]} />
 				<meshStandardMaterial {...topMaterial} />
 			</mesh>
-			{/* greenhouse glass band */}
 			<mesh position={[0, 1.14, -0.15]}>
 				<boxGeometry args={[1.62, 0.3, 1.9]} />
 				<meshStandardMaterial color={CLAY_GLASS} roughness={0.15} metalness={0.6} />
 			</mesh>
-			{/* windshield slope */}
 			<mesh position={[0, 1.05, 0.95]} rotation={[0.5, 0, 0]}>
 				<boxGeometry args={[1.56, 0.42, 0.08]} />
 				<meshStandardMaterial color={CLAY_GLASS} roughness={0.15} metalness={0.6} />
 			</mesh>
-			{/* rear glass slope */}
 			<mesh position={[0, 1.05, -1.25]} rotation={[-0.55, 0, 0]}>
 				<boxGeometry args={[1.56, 0.42, 0.08]} />
 				<meshStandardMaterial color={CLAY_GLASS} roughness={0.15} metalness={0.6} />
@@ -98,7 +97,6 @@ export function SmallPlane({ position = [0, 0, 0], rotY = 0, autoColor = undefin
 		autoColor ? autoFlat(autoColor) : { color, roughness, metalness };
 	return (
 		<group position={position} rotation={[0, rotY, 0]}>
-			{/* fuselage and tapered nose */}
 			<mesh position={[0, 0.76, 0]} rotation={[Math.PI / 2, 0, 0]}>
 				<cylinderGeometry args={[0.23, 0.31, 2.75, 16]} />
 				<meshStandardMaterial {...mat(CLAY_PLANE, 0.58, 0.18)} />
@@ -108,7 +106,6 @@ export function SmallPlane({ position = [0, 0, 0], rotY = 0, autoColor = undefin
 				<meshStandardMaterial {...mat(CLAY_PLANE_TRIM, 0.52, 0.2)} />
 			</mesh>
 
-			{/* main wing and tail plane */}
 			<mesh position={[0, 0.73, 0.15]}>
 				<boxGeometry args={[3.4, 0.09, 0.58]} />
 				<meshStandardMaterial {...mat(CLAY_PLANE, 0.62, 0.14)} />
@@ -122,13 +119,11 @@ export function SmallPlane({ position = [0, 0, 0], rotY = 0, autoColor = undefin
 				<meshStandardMaterial {...mat(CLAY_PLANE, 0.62, 0.12)} />
 			</mesh>
 
-			{/* cockpit canopy */}
 			<mesh position={[0, 1.02, 0.42]} scale={[0.62, 0.46, 0.9]}>
 				<sphereGeometry args={[0.42, 16, 10, 0, Math.PI * 2, 0, Math.PI / 2]} />
 				<meshStandardMaterial color={CLAY_GLASS} roughness={0.16} metalness={0.55} />
 			</mesh>
 
-			{/* propeller hub and blades */}
 			<group position={[0, 0.76, 1.86]}>
 				<mesh rotation={[Math.PI / 2, 0, 0]}>
 					<cylinderGeometry args={[0.11, 0.11, 0.2, 12]} />
@@ -140,7 +135,6 @@ export function SmallPlane({ position = [0, 0, 0], rotY = 0, autoColor = undefin
 				</mesh>
 			</group>
 
-			{/* simple landing gear */}
 			{[-0.55, 0.55].map((x) => (
 				<group key={x} position={[x, 0.2, 0.15]}>
 					<mesh position={[0, 0.24, 0]} rotation={[0, 0, x < 0 ? -0.35 : 0.35]}>
@@ -210,12 +204,20 @@ function autoFlat(hex) {
 	return { color: hex, roughness: 1, metalness: 0, emissive: hex, emissiveIntensity: 0.4 };
 }
 
-function Primitive({ kind, color, autoColor }) {
+// Parts of an assembly can share a plane with an earlier part (hood top and
+// grille top). The depth test can't order them and the winner flips as the
+// camera moves, so a ranked part is pulled toward the camera by `rank` steps
+// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
+function depthRankProps(rank) {
+	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
+}
+
+function Primitive({ kind, color, autoColor, depthRank = 0 }) {
 	const side = kind === "plane" ? THREE.DoubleSide : THREE.FrontSide;
 	const material = autoColor ? (
-		<meshStandardMaterial {...autoFlat(autoColor)} side={side} />
+		<meshStandardMaterial {...autoFlat(autoColor)} side={side} {...depthRankProps(depthRank)} />
 	) : (
-		<meshStandardMaterial color={color} roughness={0.82} side={side} />
+		<meshStandardMaterial color={color} roughness={0.82} side={side} {...depthRankProps(depthRank)} />
 	);
 	if (kind === "sphere") {
 		return (
@@ -311,8 +313,8 @@ function disposeOwnedMaterials(root) {
  *
  * Skinned graphs go through `cloneMeshGraph` so a Mixamo-as-statue keeps
  * its bind pose. Clay replaces materials on THIS clone only, so a second
- * instance of the same file can keep the textures from the disk. Auto-color
- * also clones: the cached graph is shared, and a viewport tint must not leak.
+ * instance of the same file can keep the textures from the disk. Every clone
+ * owns its materials, so auto-color tints and opacity fades never leak.
  */
 function instantiateMesh(source, object) {
 	const root = cloneMeshGraph(source);
@@ -338,18 +340,16 @@ function instantiateMesh(source, object) {
 		node.receiveShadow = true;
 		if (clay) {
 			const make = () => new THREE.MeshStandardMaterial({ color: clayColor, roughness: 0.9, metalness: 0 });
+			for (const material of Array.isArray(node.material) ? node.material : [node.material]) material?.dispose?.();
 			node.material = Array.isArray(node.material) ? node.material.map(() => make()) : make();
 			node.userData.clayOwned = true;
 			return;
 		}
 		if (!object.autoColor || !node.material) return;
-		const tint = (material) => {
-			const next = material.clone();
-			if (next.color) next.color.set(object.autoColor);
-			return next;
-		};
-		node.material = Array.isArray(node.material) ? node.material.map(tint) : tint(node.material);
-		node.userData.instanceOwned = true;
+		// cloneMeshGraph already gave this instance its own materials.
+		for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+			if (material.color) material.color.set(object.autoColor);
+		}
 	});
 	return root;
 }
@@ -420,21 +420,92 @@ function Cutout({ object }) {
 	);
 }
 
+/**
+ * A sculpt: the clay parts its recipe describes, rebuilt only when the recipe
+ * or the look changes. Each part keeps its own clay colour; auto-colour paints
+ * the whole sculpt flat like any other prop, because it is one object.
+ */
+function Sculpt({ object, depthRank = 0 }) {
+	const { recipe, autoColor } = object;
+	const group = useMemo(
+		() => buildSculptGroup(recipe, {
+			materialFor: (part) => new THREE.MeshStandardMaterial({
+				...(autoColor ? autoFlat(autoColor) : { color: part.color, roughness: 0.82, metalness: 0 }),
+				...depthRankProps(depthRank),
+			}),
+		}),
+		[recipe, autoColor, depthRank],
+	);
+	useEffect(() => () => disposeSculptGroup(group), [group]);
+	return <primitive object={group} />;
+}
+
 const PRIMITIVE_KINDS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "plane"]);
 
-function SceneObjectContent({ object }) {
+// X red, Y green, Z blue: the DCC convention, so a turned Empty reads its own
+// orientation off the marker.
+const EMPTY_AXES = [
+	{ to: [1, 0, 0], color: "#e5594f" },
+	{ to: [0, 1, 0], color: "#5fb95f" },
+	{ to: [0, 0, 1], color: "#4f86e5" },
+];
+
+/**
+ * An Empty's viewport presence: a three-axis cross and a pick volume, and
+ * nothing else. It is editor furniture, so every node sits on GIZMO_LAYER —
+ * the layer the shot camera, the preview card, PlayView, the ink prepass and
+ * the recorder all drop — and it casts no shadow because it has no mesh to
+ * cast one. The pick volume is invisible (never drawn) but still raycasts; the
+ * object picker finds it by `userData.emptyPick` on the gizmo-layer pass.
+ */
+function EmptyMarker() {
+	const half = EMPTY_MARKER_SIZE / 2;
+	const axes = useMemo(() => {
+		const positions = [];
+		const colors = [];
+		const color = new THREE.Color();
+		for (const axis of EMPTY_AXES) {
+			positions.push(-axis.to[0] * half, -axis.to[1] * half, -axis.to[2] * half, axis.to[0] * half, axis.to[1] * half, axis.to[2] * half);
+			color.set(axis.color);
+			colors.push(color.r, color.g, color.b, color.r, color.g, color.b);
+		}
+		const geometry = new THREE.BufferGeometry();
+		geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+		geometry.setAttribute("color", new THREE.Float32BufferAttribute(colors, 3));
+		return geometry;
+	}, [half]);
+	useEffect(() => () => axes.dispose(), [axes]);
+	const onLayer = (node) => {
+		if (node) node.layers.set(GIZMO_LAYER);
+	};
+	return (
+		<group userData={{ emptyMarker: true }}>
+			<lineSegments ref={onLayer} geometry={axes} renderOrder={997} frustumCulled={false}>
+				<lineBasicMaterial vertexColors depthTest={false} depthWrite={false} transparent opacity={0.95} />
+			</lineSegments>
+			<mesh ref={onLayer} visible={false} userData={{ emptyPick: true }}>
+				<sphereGeometry args={[half * 1.25, 12, 8]} />
+				<meshBasicMaterial />
+			</mesh>
+		</group>
+	);
+}
+
+function SceneObjectContent({ object, depthRank = 0 }) {
 	// `autoColor` is the viewport-only display color the auto-color mode stamps
 	// onto the DISPLAYED object (App's displaySceneObjects); the authored
 	// `color` is untouched underneath. Cutouts stay out: tinting a photo
 	// standee destroys the one thing it is for. Imported meshes take the same
 	// override as a cube — file materials are cloned and tinted per instance.
 	const { renderer, color, autoColor } = object;
+	if (renderer === EMPTY_KIND) return <EmptyMarker />;
 	if (renderer === CUTOUT_KIND) return <Cutout object={object} />;
 	if (renderer === MESH_KIND) return <ImportedMesh object={object} />;
+	if (renderer === SCULPT_KIND) return <Sculpt object={object} depthRank={depthRank} />;
 	if (renderer === "car") return <Car color={autoColor ?? color} autoColor={autoColor} />;
 	if (renderer === "small-plane") return <SmallPlane autoColor={autoColor} />;
 	if (renderer === "chair") return <Chair autoColor={autoColor} />;
-	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} color={color} autoColor={autoColor} />;
+	if (PRIMITIVE_KINDS.has(renderer)) return <Primitive kind={renderer} color={color} autoColor={autoColor} depthRank={depthRank} />;
 	return null;
 }
 
@@ -444,9 +515,12 @@ function SceneObjectContent({ object }) {
  * object instead of a selection.
  */
 function SelectionBox({ object }) {
-	const height = Math.max(object.height ?? 1, 0.08);
-	const width = object.footprint?.width ?? 1;
-	const depth = object.footprint?.depth ?? 1;
+	// An Empty has no extent, so its cage is the marker's own cube, centred on
+	// the origin (a prop's cage stands on it).
+	const empty = object.renderer === EMPTY_KIND;
+	const height = empty ? EMPTY_MARKER_SIZE : Math.max(object.height ?? 1, 0.08);
+	const width = empty ? EMPTY_MARKER_SIZE : object.footprint?.width ?? 1;
+	const depth = empty ? EMPTY_MARKER_SIZE : object.footprint?.depth ?? 1;
 	const edges = useMemo(
 		() => new THREE.EdgesGeometry(new THREE.BoxGeometry(width * 1.04, height * 1.04, depth * 1.04)),
 		[width, height, depth],
@@ -463,7 +537,7 @@ function SelectionBox({ object }) {
 				if (mesh) mesh.layers.set(GIZMO_LAYER);
 			}}
 			geometry={edges}
-			position={[0, height / 2, 0]}
+			position={[0, empty ? 0 : height / 2, 0]}
 			renderOrder={998}
 		>
 			<lineBasicMaterial color="#e7b557" transparent opacity={0.95} depthTest={false} depthWrite={false} />
@@ -482,7 +556,7 @@ const placeLocal = new THREE.Matrix4();
 const placeWorld = new THREE.Matrix4();
 const placeFrame = new THREE.Matrix4();
 
-function SceneObject({ object, selected, frameRef = null, take = null, attachFrameRef = null, registryRef = null }) {
+function SceneObject({ object, selected, frameRef = null, take = null, attachFrameRef = null, registryRef = null, travelLookupRef = null, fadeOpacity = null, depthRank = 0 }) {
 	const groupRef = useRef(null);
 	const attach = object.attach ?? null;
 	// An object on a travel path — or one CARRIED by a character — is placed
@@ -496,17 +570,27 @@ function SceneObject({ object, selected, frameRef = null, take = null, attachFra
 		const group = groupRef.current;
 		if (!group) return;
 		const frame = frameRef?.current ?? 0;
-		if (attach || object.path) {
+		// A record under a routed parent travels with it (object-travel.js), and
+		// so does a routed record itself: one answer from the authored records.
+		const travelled = frameRef && !attach && travelLookupRef?.current
+			? sceneObjectTravelMatrixAt(travelLookupRef.current, object.id, frame, take ?? {}, placeWorld)
+			: null;
+		if (travelled) {
+			travelled.decompose(group.position, group.quaternion, group.scale);
+		} else if (attach || object.path) {
 			// The authored numbers first. While attached they are the prop's LOCAL
 			// transform in the attach frame; otherwise they are already world.
 			placePos.set(object.x, object.y ?? 0, object.z);
-			placeEuler.set((object.rotX ?? 0) * DEG, object.rot * DEG, (object.rotZ ?? 0) * DEG);
+			placeEuler.set((object.rotX ?? 0) * DEG, object.rot * DEG, (object.rotZ ?? 0) * DEG, "XYZ");
 			placeScale.set(object.scaleX ?? 1, object.scaleY ?? 1, object.scaleZ ?? 1);
 			if (frameRef && object.path) {
 				const at = objectTransformAt(object, frame, take ?? {});
 				if (at) {
 					placePos.set(at.x, at.y, at.z);
-					if (at.rot !== null) placeEuler.y = at.rot * DEG;
+					// The same pose object-travel gives a routed record: yaw, then
+					// the body's own pitch, then its roll (+ the route's lean).
+					const pose = travelPose(object, at);
+					placeEuler.set(pose.rotX * DEG, pose.rot * DEG, pose.rotZ * DEG, "YXZ");
 				}
 			}
 			// A missing rig (the character left the cast, or its model has not
@@ -530,8 +614,9 @@ function SceneObject({ object, selected, frameRef = null, take = null, attachFra
 		// the store only knows the authored one — and while attached the authored
 		// one is not even in world space. Harmless in normal use.
 		if (typeof window !== "undefined") {
-			(window.__cclayPropWorld ??= {})[object.id] = { x: group.position.x, y: group.position.y, z: group.position.z, frame };
+			(window.__cclayPropWorld ??= {})[object.id] = { x: group.position.x, y: group.position.y, z: group.position.z, quat: { x: group.quaternion.x, y: group.quaternion.y, z: group.quaternion.z, w: group.quaternion.w }, frame };
 		}
+		applyPoseFade(group, fadeOpacity, object.opacity ?? 1);
 	};
 	useFrame(place);
 	// Two things the App needs to reach imperatively, registered per prop: a
@@ -570,7 +655,7 @@ function SceneObject({ object, selected, frameRef = null, take = null, attachFra
 			// the viewport picker walks up from a hit mesh to find this id
 			userData={{ sceneObjectId: object.id }}
 		>
-			<SceneObjectContent object={object} />
+			<SceneObjectContent object={object} depthRank={depthRank} />
 			{selected && <SelectionBox object={object} />}
 		</group>
 	);
@@ -584,8 +669,16 @@ function SceneObject({ object, selected, frameRef = null, take = null, attachFra
  * loop and would otherwise record props one frame stale; `worldRef` with a
  * "where is this prop" lookup, so a reparent converts from the transform on
  * screen instead of from a second computation of it. */
-export function SetProps({ objects = [], selectedId = null, frameRef = null, take = null, attachFrameRef = null, syncRef = null, worldRef = null }) {
+export function SetProps({ objects = [], authoredObjects = null, selectedId = null, frameRef = null, take = null, attachFrameRef = null, syncRef = null, worldRef = null, fadeOpacity = null }) {
 	const registryRef = useRef(null);
+	// The authored records by id: a child's travel is its routed parent's
+	// route against the parent's AUTHORED pose, which the display copies in
+	// `objects` no longer carry once they have been animated.
+	const travelLookupRef = useRef(null);
+	travelLookupRef.current = useMemo(() => (authoredObjects ? new Map(authoredObjects.map((object) => [object.id, object])) : null), [authoredObjects]);
+	// Coplanar-face ranks come from the AUTHORED records: a routed group moves
+	// rigidly, so what shares a plane at rest shares it on every frame.
+	const depthRanks = useMemo(() => coplanarDepthRanks(authoredObjects ?? objects), [authoredObjects, objects]);
 	if (!registryRef.current) registryRef.current = new Map();
 	if (syncRef) syncRef.current = () => { for (const entry of registryRef.current.values()) entry.place(); };
 	if (worldRef) worldRef.current = (id, out) => registryRef.current.get(id)?.world(out) ?? null;
@@ -600,8 +693,56 @@ export function SetProps({ objects = [], selectedId = null, frameRef = null, tak
 					take={take}
 					attachFrameRef={attachFrameRef}
 					registryRef={registryRef}
+					travelLookupRef={travelLookupRef}
+					fadeOpacity={fadeOpacity}
+					depthRank={depthRanks.get(object.id) ?? 0}
 				/>
 			))}
 		</group>
 	);
 }
+
+const carryMatrix = new THREE.Matrix4();
+
+/**
+ * A group that rides a scene object's travel: whatever is inside it (a
+ * character grouped under a car) is moved and turned with the object's route,
+ * on top of its own transform and animation. Placed imperatively from the
+ * frame ref for the same reason a routed prop is — the offscreen export
+ * advances frames without a re-render — and registered in `registryRef` so the
+ * recorder can place every carrier before it renders a frame.
+ *
+ * `objectsRef.current` holds the AUTHORED records by id; with no object, or an
+ * object that does not travel, the group stays at identity.
+ */
+export function ObjectCarrier({ objectId = null, objectsRef, frameRef = null, take = null, registryRef = null, children }) {
+	const groupRef = useRef(null);
+	const place = () => {
+		const group = groupRef.current;
+		if (!group) return;
+		const carried = objectId && objectsRef?.current
+			? sceneObjectCarryMatrixAt(objectsRef.current, objectId, frameRef?.current ?? 0, take ?? {}, carryMatrix)
+			: null;
+		if (carried) carried.decompose(group.position, group.quaternion, group.scale);
+		else {
+			group.position.set(0, 0, 0);
+			group.quaternion.identity();
+			group.scale.set(1, 1, 1);
+		}
+	};
+	// Ahead of every priority-0 placement: a prop held by a rider reads its
+	// bone's world matrix through this group, so the carry must land first or
+	// the prop trails the hand by one frame. Mount order alone does not hold
+	// (SetProps mounts before the cast; a rig remount moves to the back).
+	useFrame(place, -1);
+	const placeRef = useRef(place);
+	placeRef.current = place;
+	useEffect(() => {
+		if (!registryRef) return undefined;
+		const registry = registryRef.current;
+		const entry = () => placeRef.current();
+		registry.add(entry);
+		return () => { registry.delete(entry); };
+	}, [registryRef]);
+	return <group ref={groupRef}>{children}</group>;
+}

package/src/proxy-figure.jsx

@@ -0,0 +1,69 @@
+import { memo, useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { defaultCharacterTint } from "./app-stage.jsx";
+
+const BODY_RADIUS = 0.22;
+const BODY_HEIGHT = 1.45;
+const HEAD_RADIUS = 0.12;
+
+export function proxyYaw(rot, posture = "stand") {
+	return (rot * Math.PI) / 180 + (posture === "lie" ? Math.PI : 0);
+}
+
+export const ProxyFigure = memo(function ProxyFigure({
+	position,
+	rot,
+	tint,
+	scale = 1,
+	posture = "stand",
+	pickId,
+	selected,
+}) {
+	const bodyHeight = posture === "sit" ? BODY_HEIGHT * 0.6 : BODY_HEIGHT;
+	const headY = bodyHeight + 0.13;
+	const model = useMemo(() => {
+		const bodyMaterial = new THREE.MeshStandardMaterial({
+			color: tint ?? defaultCharacterTint({ model: "proxy-figure" }, 0),
+			roughness: 0.66,
+			metalness: 0,
+			envMapIntensity: 0.35,
+		});
+		const group = new THREE.Group();
+		const body = new THREE.Mesh(new THREE.CapsuleGeometry(BODY_RADIUS, bodyHeight - BODY_RADIUS * 2, 12, 20), bodyMaterial);
+		body.position.y = bodyHeight / 2;
+		body.castShadow = true;
+		body.receiveShadow = true;
+		body.frustumCulled = false;
+		group.add(body);
+		const head = new THREE.Mesh(new THREE.SphereGeometry(HEAD_RADIUS, 16, 12), bodyMaterial);
+		head.position.y = headY;
+		head.castShadow = true;
+		head.receiveShadow = true;
+		head.frustumCulled = false;
+		group.add(head);
+		return group;
+	}, [bodyHeight, headY, tint]);
+	useEffect(() => () => {
+		const materials = new Set();
+		model.traverse(node => {
+			if (!node.isMesh) return;
+			node.geometry.dispose();
+			materials.add(node.material);
+		});
+		for (const material of materials) material.dispose();
+	}, [model]);
+
+	return (
+		<group
+			position={position}
+			rotation={[0, proxyYaw(rot, posture), 0]}
+			scale={scale}
+			userData={pickId ? { characterPick: pickId, selected: !!selected } : undefined}
+		>
+			<group position={posture === "lie" ? [0, BODY_RADIUS, 0] : [0, 0, 0]} rotation={posture === "lie" ? [-Math.PI / 2, 0, 0] : [0, 0, 0]}>
+				<primitive object={model} />
+			</group>
+		</group>
+	);
+});
+

package/src/range-pin-panel.jsx

@@ -341,4 +341,3 @@ export function RangePinPanel({
 	);
 }
 
-export { PARTS as RANGE_PIN_PARTS, partFor as rangePinPartFor, freshDraft as createRangePinDraft };