cozyclay 2.0.2 → 2.1.1

package/src/planview.jsx

@@ -4,9 +4,12 @@ import { Line, Text } from "@react-three/drei";
 import * as THREE from "three";
 import { aimAt } from "./controls.jsx";
 import { PLAN_LAYER } from "./dualview.jsx";
-import { objectSize } from "./scene-objects.js";
+import { EMPTY_MARKER_SIZE, isEmptyObject, objectSize } from "./scene-objects.js";
 import { displayObjectLabel } from "./object-catalog.jsx";
 import { ko } from "./locale.js";
+import { isProxyFigure } from "./scenes.js";
+import { prepareRailBend } from "./camera-follow.js";
+import { MARK_GAP, MAX_PATH_MARKS, MAX_PATH_POINTS, nearestPathFraction, pathCurve, pathMarkFractions, pathPointAtFraction } from "./object-path.js";
 
 const ROOM_LIMIT = 240; // stay on the open stage (matches scene-objects' clamp)
 const ACTOR_LIMIT = 4; // matches the Subject sliders' range
@@ -186,7 +189,33 @@ function CastRing({ color }) {
 	);
 }
 
+/** An Empty on the board: no footprint, just a small cross and a ring where
+ * its origin stands, so a group node can be found, selected and dragged like
+ * any other row of the plan. */
+function EmptyPlanMarker({ object, selected, dragging, turning }) {
+	const half = EMPTY_MARKER_SIZE / 2;
+	const color = selected ? SELECTED_COLOR : PROP_LABEL_COLOR;
+	const rotation = (object.rot * Math.PI) / 180;
+	const cross = useMemo(() => [[[-half, 0.04, 0], [half, 0.04, 0]], [[0, 0.04, -half], [0, 0.04, half]]], [half]);
+	return (
+		<group position={[object.x, 0, object.z]} rotation={[0, rotation, 0]}>
+			{cross.map((points, index) => (
+				<Line key={index} points={points} color={color} lineWidth={selected ? 2 : 1.5} transparent opacity={selected ? 1 : 0.85} depthWrite={false} depthTest={false} renderOrder={12} />
+			))}
+			<mesh position={[0, 0.036, 0]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={11}>
+				<ringGeometry args={[half * 0.8, half * 0.95, 24]} />
+				<meshBasicMaterial color={color} transparent opacity={selected ? 0.9 : 0.6} depthWrite={false} depthTest={false} />
+			</mesh>
+			<group position={[0, 0, half + 0.35]} rotation={[0, -rotation, 0]}>
+				<PlanLabel text={displayObjectLabel(object.name).slice(0, 8)} color={color} offset={0} muted={!selected} />
+			</group>
+			{selected && <Puck color={SELECTED_COLOR} showBody={false} handleDist={half + 0.65} dragging={dragging} turning={turning} />}
+		</group>
+	);
+}
+
 function SceneObjectFootprint({ object, selected, dragging, turning }) {
+	if (isEmptyObject(object)) return <EmptyPlanMarker object={object} selected={selected} dragging={dragging} turning={turning} />;
 	const { width, height, depth } = objectSize(object);
 	const objectLabel = displayObjectLabel(object.name).slice(0, 8);
 	const handleDist = depth / 2 + 0.65;
@@ -303,11 +332,6 @@ function SubjectMovementGuide({ track }) {
 	);
 }
 
-/**
- * The drawn camera rail (and the live stroke while drawing): a flat violet
- * line on the deck. Display only — authoring happens through the pointer
- * handlers, exactly like the pucks.
- */
 /**
  * A scene object's travel path on the plan board. The camera's rail owns
  * RAIL_COLOR; a prop's route gets its own green so the two never read as the
@@ -315,54 +339,41 @@ function SubjectMovementGuide({ track }) {
  */
 const OBJECT_PATH_COLOR = "#6fcf97";
 const OBJECT_PATH_SELECTED_COLOR = "#ffb454";
+const OBJECT_PATH_LIT_COLOR = "#d4f7e2";
 // How near the floor pointer must be to grab a route point, in metres.
 const PATH_POINT_GRAB = 0.34;
-function ObjectPathLine({ points, selectedIndex = null }) {
-	if (!points || points.length < 2) return null;
-	const first = points[0];
-	const last = points[points.length - 1];
+function ObjectPathLine({ path, selectedIndex = null, hoverIndex = null, lit = false }) {
+	const curve = useMemo(() => (path?.points?.length > 1 ? pathCurve(path) : null), [path]);
+	const marks = useMemo(() => (path ? pathMarkFractions(path).map((t) => pathPointAtFraction(path, t)) : []), [path]);
+	if (!curve || curve.points.length < 2) return null;
 	return (
 		<group>
-			<Line
-				points={points.map((point) => [point.x, 0.028, point.z])}
-				color={OBJECT_PATH_COLOR}
-				lineWidth={3}
-				transparent
-				opacity={0.92}
-				depthWrite={false}
-				depthTest={false}
-				renderOrder={9}
-			/>
-			{/* Every point is a handle here, not just the ends: the route is
-			    drawn on this board, so it should also be editable on it. */}
-			{points.map((point, index) => (
+			{/* The camera rail's own line: the curve the object travels, with the
+			    same start disc, START label, heading arrow and end ring. Only the
+			    colour is the prop's. */}
+			<CameraRailLine points={curve.points} color={lit ? OBJECT_PATH_LIT_COLOR : OBJECT_PATH_COLOR} />
+			{/* The marks, like the rail's crane dots: the ends plus any added by
+			    double-clicking the line. These are what the board lets you grab. */}
+			{marks.map((point, index) => point && (
 				<mesh
 					key={index}
-					position={[point.x, 0.036, point.z]}
+					position={[point.x, 0.042, point.z]}
 					rotation={[-Math.PI / 2, 0, 0]}
-					renderOrder={10}
+					renderOrder={12}
 				>
-					<circleGeometry args={[index === selectedIndex ? 0.13 : 0.1, 14]} />
+					<circleGeometry args={[index === selectedIndex ? 0.13 : index === hoverIndex ? 0.12 : 0.1, 14]} />
 					<meshBasicMaterial
-						color={index === selectedIndex ? OBJECT_PATH_SELECTED_COLOR : OBJECT_PATH_COLOR}
+						color={index === selectedIndex ? OBJECT_PATH_SELECTED_COLOR : index === hoverIndex ? "#d4f7e2" : "#2f8f5b"}
 						depthWrite={false}
 						depthTest={false}
 					/>
 				</mesh>
 			))}
-			<mesh position={[first.x, 0.038, first.z]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={11}>
-				<circleGeometry args={[0.16, 18]} />
-				<meshBasicMaterial color={OBJECT_PATH_COLOR} depthWrite={false} depthTest={false} />
-			</mesh>
-			<mesh position={[last.x, 0.038, last.z]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={11}>
-				<ringGeometry args={[0.13, 0.19, 18]} />
-				<meshBasicMaterial color={OBJECT_PATH_COLOR} depthWrite={false} depthTest={false} />
-			</mesh>
 		</group>
 	);
 }
 
-function CameraRailLine({ points, live = false }) {
+function CameraRailLine({ points, live = false, color = RAIL_COLOR }) {
 	const directionGeometry = useMemo(() => {
 		if (live || !points || points.length < 2) return null;
 		const head = points[0];
@@ -394,22 +405,22 @@ function CameraRailLine({ points, live = false }) {
 	const last = points[points.length - 1];
 	return (
 		<group>
-			<Line points={points.map((point) => [point.x, 0.03, point.z])} color={RAIL_COLOR} lineWidth={live ? 2.5 : 3.5} transparent opacity={live ? 0.72 : 0.96} depthWrite={false} depthTest={false} renderOrder={9} />
+			<Line points={points.map((point) => [point.x, 0.03, point.z])} color={color} lineWidth={live ? 2.5 : 3.5} transparent opacity={live ? 0.72 : 0.96} depthWrite={false} depthTest={false} renderOrder={9} />
 			{!live && (
 				<>
 					<mesh position={[first.x, 0.04, first.z]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={11}>
 						<circleGeometry args={[0.22, 20]} />
-						<meshBasicMaterial color={RAIL_COLOR} depthWrite={false} depthTest={false} />
+						<meshBasicMaterial color={color} depthWrite={false} depthTest={false} />
 					</mesh>
 					<mesh position={[first.x, 0.039, first.z]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={10}>
 						<ringGeometry args={[0.27, 0.32, 20]} />
-						<meshBasicMaterial color={RAIL_COLOR} transparent opacity={0.72} depthWrite={false} depthTest={false} />
+						<meshBasicMaterial color={color} transparent opacity={0.72} depthWrite={false} depthTest={false} />
 					</mesh>
 					<Text
 						position={[first.x, 0.05, first.z + 0.48]}
 						rotation={[-Math.PI / 2, 0, 0]}
 						fontSize={0.24}
-						color={RAIL_COLOR}
+						color={color}
 						anchorX="center"
 						anchorY="middle"
 						outlineWidth={0.035}
@@ -422,12 +433,12 @@ function CameraRailLine({ points, live = false }) {
 					</Text>
 					{directionGeometry && (
 						<mesh geometry={directionGeometry} renderOrder={11}>
-							<meshBasicMaterial color={RAIL_COLOR} depthWrite={false} depthTest={false} side={THREE.DoubleSide} />
+							<meshBasicMaterial color={color} depthWrite={false} depthTest={false} side={THREE.DoubleSide} />
 						</mesh>
 					)}
 					<mesh position={[last.x, 0.04, last.z]} rotation={[-Math.PI / 2, 0, 0]} renderOrder={10}>
 						<ringGeometry args={[0.1, 0.15, 16]} />
-						<meshBasicMaterial color={RAIL_COLOR} depthWrite={false} depthTest={false} />
+						<meshBasicMaterial color={color} depthWrite={false} depthTest={false} />
 					</mesh>
 				</>
 			)}
@@ -490,10 +501,18 @@ function WaypointPath({ waypoints, start, activeWaypointId }) {
  * reports moves that still hit it, so a fast drag off the edge silently strands
  * the puck.
  */
-export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, characters = [], onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, pathStart = null, waypoints, activeWaypointId, onSelectWaypoint, onMoveWaypoint, onSelectEntity, sceneObjects = [], selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, cameraRailPoints = null, railDraw = false, onRailStroke, pathDraw = false, onPathStroke, objectPathPoints = null, objectPathSelectedIndex = null, onObjectPathPointSelect, onObjectPathPointMove, onObjectPathPointInsert, onObjectPathGestureStart, onObjectPathGestureEnd, subjectTrack = null, onCameraChange, keyLight = null, minimal = false }) {
+export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, characters = [], characterPlacements = [], onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, pathStart = null, waypoints, activeWaypointId, onSelectWaypoint, onMoveWaypoint, onSelectEntity, sceneObjects = [], selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, cameraRailPoints = null, railDraw = false, onRailStroke, pathDraw = false, onPathStroke, objectPath = null, objectPathSelectedIndex = null, onObjectPathPointSelect, onObjectPathChange, onObjectPathMarkInsert, onObjectPathGestureStart, onObjectPathGestureEnd, subjectTrack = null, onCameraChange, keyLight = null, minimal = false }) {
+	characters = characters.map(entry => {
+		const placement = isProxyFigure(entry) && characterPlacements.find(view => view.id === entry.id);
+		return placement ? { ...entry, x: placement.position[0], z: placement.position[2], rot: placement.rot } : entry;
+	});
 	const [drag, setDrag] = useState(null); // { id, mode }
 	// live stroke while the rail is being drawn; world XZ, display only
 	const [railStroke, setRailStroke] = useState(null);
+	// the route mark under the pointer, for the hover highlight
+	const [hoverMark, setHoverMark] = useState(null);
+	// The pointer is on the route where a double-click would still drop a dot.
+	const [hoverLine, setHoverLine] = useState(false);
 	const rootRef = useRef();
 	const camPos = useRef();
 	const camRot = useRef();
@@ -520,8 +539,8 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 	// clears dragRef, so a dep that changes while dragging (charA.x does, on the
 	// very first move) would kill the drag after one frame. Read live values
 	// through a ref and keep the effect's deps stable.
-	const latest = useRef({ objectPathPoints, objectPathSelectedIndex, onObjectPathPointSelect, onObjectPathPointMove, onObjectPathPointInsert, onObjectPathGestureStart, onObjectPathGestureEnd, characters, waypoints, onSelectWaypoint, onMoveWaypoint, onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, onSelectEntity, sceneObjects, selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, railDraw, onRailStroke, pathDraw, onPathStroke, onCameraChange });
-	latest.current = { objectPathPoints, objectPathSelectedIndex, onObjectPathPointSelect, onObjectPathPointMove, onObjectPathPointInsert, onObjectPathGestureStart, onObjectPathGestureEnd, characters, waypoints, onSelectWaypoint, onMoveWaypoint, onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, onSelectEntity, sceneObjects, selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, railDraw, onRailStroke, pathDraw, onPathStroke, onCameraChange };
+	const latest = useRef({ objectPath, objectPathSelectedIndex, onObjectPathPointSelect, onObjectPathChange, onObjectPathMarkInsert, onObjectPathGestureStart, onObjectPathGestureEnd, characters, waypoints, onSelectWaypoint, onMoveWaypoint, onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, onSelectEntity, sceneObjects, selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, railDraw, onRailStroke, pathDraw, onPathStroke, onCameraChange });
+	latest.current = { objectPath, objectPathSelectedIndex, onObjectPathPointSelect, onObjectPathChange, onObjectPathMarkInsert, onObjectPathGestureStart, onObjectPathGestureEnd, characters, waypoints, onSelectWaypoint, onMoveWaypoint, onMoveCharacter, onCharacterGestureStart, onWaypointGestureStart, onCameraGestureStart, onSelectEntity, sceneObjects, selectedSceneObjectId, onMoveSceneObject, onObjectMoveStart, onObjectMoveEnd, railDraw, onRailStroke, pathDraw, onPathStroke, onCameraChange };
 
 	const targets = () => {
 		const cast = latest.current.characters;
@@ -539,7 +558,9 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			});
 		});
 		for (const object of latest.current.sceneObjects) {
-			const { width, depth } = objectSize(object);
+			// An Empty has no footprint; it is picked by its marker's size.
+			const size = isEmptyObject(object) ? { width: EMPTY_MARKER_SIZE, depth: EMPTY_MARKER_SIZE } : objectSize(object);
+			const { width, depth } = size;
 			out.push({
 				id: `object:${object.id}`,
 				objectId: object.id,
@@ -612,13 +633,15 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			// "the puck doesn't move". Pick the NEAREST target instead.
 			// A route's own points outrank pucks: they are smaller, they sit on
 			// top of the deck, and a press near one is always meant for it.
-			const pathPoints = latest.current.objectPathPoints;
-			if (pathPoints && pathPoints.length >= 2) {
+			const route = latest.current.objectPath;
+			if (route && route.points?.length >= 2) {
 				let nearest = null;
-				for (let i = 0; i < pathPoints.length; i += 1) {
-					const d = (p.x - pathPoints[i].x) ** 2 + (p.z - pathPoints[i].z) ** 2;
+				pathMarkFractions(route).forEach((t, i) => {
+					const at = pathPointAtFraction(route, t);
+					if (!at) return;
+					const d = (p.x - at.x) ** 2 + (p.z - at.z) ** 2;
 					if (d < PATH_POINT_GRAB * PATH_POINT_GRAB && (!nearest || d < nearest.d)) nearest = { d, index: i };
-				}
+				});
 				if (nearest) return { id: `path:${nearest.index}`, mode: "pathPoint", origin: { pathIndex: nearest.index } };
 			}
 			const list = targets();
@@ -637,8 +660,6 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 
 		const onDown = (event) => {
 			if (event.button !== 0) return;
-			// Rail drawing owns the pointer: a stroke starts anywhere on the
-			// deck, so puck picking would fight every stroke that crosses one.
 			// Rail drawing and object-path drawing share one stroke gesture:
 			// a stroke starts anywhere on the deck, so puck picking would
 			// fight every stroke that crosses one.
@@ -670,8 +691,17 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			// instantly (plan §6.4). Camera, character and waypoint grips
 			// write separate state and must never open a scene transaction.
 			if (grip.mode === "pathPoint") {
-				// One undo entry per point drag, like every other plan gesture.
+				// One undo entry per mark drag, like every other plan gesture.
 				latest.current.onObjectPathGestureStart?.();
+				// The bend this drag applies (the camera rail's own preparation):
+				// the route's points around the mark follow, fading out by the
+				// neighbouring marks.
+				const route = latest.current.objectPath;
+				const fractions = pathMarkFractions(route);
+				const base = pathPointAtFraction(route, fractions[grip.origin.pathIndex]);
+				const bend = base && prepareRailBend(route.points, base, fractions.map((t) => ({ t })), grip.origin.pathIndex, { maxControls: MAX_PATH_POINTS });
+				dragRef.current.bend = bend;
+				dragRef.current.pressed = { x: p.x, z: p.z };
 			} else if (grip.origin.objectId) {
 				dragRef.current.token = latest.current.onObjectMoveStart?.({
 					owner: "plan",
@@ -702,11 +732,27 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			}
 			const p = toFloor(event);
 			const grip = p && pick(p);
-			host.style.cursor = !grip
-				? "default"
-				: grip.mode === "turn"
-					? "ew-resize"
-					: "grab";
+			const markIndex = grip?.mode === "pathPoint" ? grip.origin.pathIndex : null;
+			setHoverMark((current) => (current === markIndex ? current : markIndex));
+			// The route answers too: it brightens and the cursor says "copy" while a
+			// double-click here would still add a dot.
+			let addable = false;
+			const route = latest.current.objectPath;
+			if (!grip && p && route && route.points?.length >= 2) {
+				const fractions = pathMarkFractions(route);
+				if (fractions.length < MAX_PATH_MARKS) {
+					const best = nearestPathFraction(route, (point) => ({ x: point.x, y: point.z }), p.x, p.z);
+					addable = !!best && best.d <= PATH_POINT_GRAB && !fractions.some((entry) => Math.abs(entry - best.t) < MARK_GAP + 0.01);
+				}
+			}
+			setHoverLine((current) => (current === addable ? current : addable));
+			host.style.cursor = addable
+				? "copy"
+				: !grip
+					? "default"
+					: grip.mode === "turn"
+						? "ew-resize"
+						: "grab";
 		};
 
 		const onMove = (event) => {
@@ -726,10 +772,18 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			}
 
 			if (grip.mode === "pathPoint") {
-				latest.current.onObjectPathPointMove?.(grip.origin.pathIndex, {
-					x: snap(p.x, ROOM_LIMIT),
-					z: snap(p.z, ROOM_LIMIT),
+				if (!grip.bend) return;
+				// Floor only: a point's height is the scene's business, so y rides
+				// through untouched. The pull is snapped like every board move.
+				const dx = Math.round((p.x - grip.pressed.x) / 0.05) * 0.05;
+				const dz = Math.round((p.z - grip.pressed.z) / 0.05) * 0.05;
+				const moved = grip.bend.startControls.map((entry, i) => {
+					const weight = grip.bend.weights[i];
+					return weight > 0
+						? { ...entry, x: THREE.MathUtils.clamp(entry.x + dx * weight, -ROOM_LIMIT, ROOM_LIMIT), z: THREE.MathUtils.clamp(entry.z + dz * weight, -ROOM_LIMIT, ROOM_LIMIT) }
+						: entry;
 				});
+				latest.current.onObjectPathChange?.({ points: moved });
 				return;
 			}
 
@@ -831,27 +885,20 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 		// 3D scene uses, offered here because this is the board the route was
 		// drawn on, so this is where a hand goes looking for it.
 		const onDouble = (event) => {
-			const points = latest.current.objectPathPoints;
-			if (!points || points.length < 2) return;
+			const route = latest.current.objectPath;
+			if (!route || route.points?.length < 2) return;
 			if (latest.current.railDraw || latest.current.pathDraw) return;
 			const p = toFloor(event);
 			if (!p) return;
-			let best = null;
-			for (let i = 0; i < points.length - 1; i += 1) {
-				const a = points[i];
-				const b = points[i + 1];
-				const dx = b.x - a.x;
-				const dz = b.z - a.z;
-				const lenSq = dx * dx + dz * dz;
-				const t = lenSq < 1e-9 ? 0 : Math.min(1, Math.max(0, ((p.x - a.x) * dx + (p.z - a.z) * dz) / lenSq));
-				const d = Math.hypot(a.x + dx * t - p.x, a.z + dz * t - p.z);
-				if (!best || d < best.d) best = { d, index: i, t };
-			}
-			// Near the line, and not on top of a point that is already there.
-			if (!best || best.d > PATH_POINT_GRAB || best.t < 0.04 || best.t > 0.96) return;
+			const fractions = pathMarkFractions(route);
+			if (fractions.length >= MAX_PATH_MARKS) return;
+			const best = nearestPathFraction(route, (point) => ({ x: point.x, y: point.z }), p.x, p.z);
+			// Near the line, and not on top of a mark that is already there.
+			if (!best || best.d > PATH_POINT_GRAB) return;
+			if (fractions.some((entry) => Math.abs(entry - best.t) < MARK_GAP + 0.01)) return;
 			event.preventDefault();
 			event.stopPropagation();
-			latest.current.onObjectPathPointInsert?.(best.index, best.t);
+			latest.current.onObjectPathMarkInsert?.(best.t);
 		};
 
 		const onEscape = (event) => {
@@ -901,7 +948,7 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 				const puckId = listIndex === 0 ? "a" : listIndex === 1 ? "b" : `char:${entry.id}`;
 				const color = listIndex === 0 ? SUBJECT_ONE_COLOR : SUBJECT_TWO_COLOR;
 				return (
-					<group key={entry.id} position={[entry.x, 0, entry.z]}>
+					<group key={entry.id} position={[entry.x, 0, entry.z]} userData={{ characterPuck: entry.id }}>
 						<PlanLabel text={ko(`S${listIndex + 1}`, `인물 ${listIndex + 1}`)} color={color} offset={-(CAST_RING_OUTER + 0.3)} />
 						<CastRing color={color} />
 						<group rotation={[0, (entry.rot * Math.PI) / 180, 0]}>
@@ -931,7 +978,7 @@ export function PlanBoard({ hostRef, planCamRef, shotCamRef, look, fovDeg, chara
 			{railStroke && railStroke.length > 1 && <CameraRailLine points={railStroke} live />}
 			{/* The selected object's travel path, drawn in its own colour so a
 			    prop's route never reads as the camera's rail. */}
-			{!minimal && objectPathPoints && objectPathPoints.length > 1 && <ObjectPathLine points={objectPathPoints} selectedIndex={objectPathSelectedIndex} />}
+			{!minimal && objectPath && objectPath.points?.length > 1 && <ObjectPathLine path={objectPath} selectedIndex={objectPathSelectedIndex} hoverIndex={hoverMark} lit={hoverLine} />}
 			{/* The sun on the floor plan: a gold disc + a stem toward the stage
 			    centre, so blocking can read where the light comes from without
 			    switching to the 3D scene. Not draggable here — the 3D puck owns

package/src/playground.js

@@ -5,10 +5,10 @@
 // playground must never overwrite scenes they authored in the real studio.
 
 import { readProjectDocument } from "./project.js";
-import { SCENES_VERSION, migrateStageFrames } from "./scenes.js";
+import { migrateScenesDocument as migrateToCurrentScenes } from "./scenes.js";
 import { resolveSceneParam } from "./starter-scenes.js";
 
-export const PLAYGROUND_EMBED = "playground";
+const PLAYGROUND_EMBED = "playground";
 const PLAYGROUND_GLOBAL = "__cozyclayPlayground";
 
 export function isPlaygroundEmbed(search) {
@@ -42,9 +42,7 @@ export async function fetchPlaygroundProject(url) {
 		const result = readProjectDocument(await response.text());
 		if (!result.ok) return null;
 		const source = result.project.scenesDocument;
-		const document = Number.isInteger(source.version) && source.version < SCENES_VERSION
-			? { ...source, version: SCENES_VERSION, scenes: source.scenes.map((scene) => ({ ...scene, stage: migrateStageFrames(scene.stage) })) }
-			: source;
+		const document = migrateToCurrentScenes(source);
 		return { name: result.project.name, document };
 	} catch {
 		return null;

package/src/pose-fade.js

@@ -0,0 +1,77 @@
+export const POSE_FADE_DEFAULT = 0.2;
+export const POSE_FADE_STORAGE_KEY = "cozyclay.poseObjectOpacity";
+
+export function readPoseFadeOpacity(storage = globalThis.localStorage) {
+	const value = Number(storage?.getItem?.(POSE_FADE_STORAGE_KEY));
+	return storage?.getItem?.(POSE_FADE_STORAGE_KEY) == null || !Number.isFinite(value)
+		? POSE_FADE_DEFAULT
+		: Math.min(1, Math.max(0, value));
+}
+
+export function writePoseFadeOpacity(value, storage = globalThis.localStorage) {
+	try { storage?.setItem?.(POSE_FADE_STORAGE_KEY, String(value)); } catch { return; }
+}
+
+// Keyed by material: a material shared by several meshes is recorded once, so the restore is exact.
+const originals = new WeakMap();
+const noRaycast = () => {};
+
+function materialsOf(mesh) {
+	return Array.isArray(mesh.material) ? mesh.material : mesh.material ? [mesh.material] : [];
+}
+
+// Image captures in Pose mode want the set as authored: the working fade is lifted while this is set.
+let fadeSuspended = false;
+function suspendPoseFade(suspended) {
+	fadeSuspended = suspended;
+}
+
+/** Runs `draw` with the working fade lifted. `sync` re-applies the fade to every prop; it runs
+    again afterwards because a demand frame loop may not render another frame on its own. */
+export function withPoseFadeLifted(sync, draw) {
+	suspendPoseFade(true);
+	sync?.();
+	try {
+		return draw();
+	} finally {
+		suspendPoseFade(false);
+		sync?.();
+	}
+}
+
+/** `fade` is Pose mode's working fade (null = off; a faded prop also stops catching clicks);
+    `own` is the object's authored opacity (1 = solid). */
+export function applyPoseFade(root, fade, own = 1) {
+	const workingFade = fadeSuspended || fade == null || fade >= 1 ? 1 : fade;
+	const opacity = workingFade * own;
+	const faded = opacity < 1;
+	const unpickable = workingFade < 1;
+	root.traverse((node) => {
+		if (!node.isMesh) return;
+		for (const material of materialsOf(node)) {
+			if (faded) {
+				if (!originals.has(material)) {
+					originals.set(material, { transparent: material.transparent, opacity: material.opacity, depthWrite: material.depthWrite });
+				}
+				const target = originals.get(material).opacity * opacity;
+				if (material.opacity !== target || !material.transparent || material.depthWrite) {
+					material.transparent = true;
+					material.opacity = target;
+					material.depthWrite = false;
+					material.needsUpdate = true;
+				}
+			} else if (originals.has(material)) {
+				Object.assign(material, originals.get(material));
+				originals.delete(material);
+				material.needsUpdate = true;
+			}
+		}
+		if (unpickable && node.raycast !== noRaycast) {
+			node.userData.poseFadeRaycast = node.raycast;
+			node.raycast = noRaycast;
+		} else if (!unpickable && node.raycast === noRaycast) {
+			node.raycast = node.userData.poseFadeRaycast;
+			delete node.userData.poseFadeRaycast;
+		}
+	});
+}

package/src/pose-gizmo.css

@@ -0,0 +1,23 @@
+.pose-rotation-readout {
+	transform: translate(10px, -100%);
+	display: grid;
+	gap: 3px;
+	padding: 5px 8px;
+	border-radius: 7px;
+	background: rgba(22, 22, 26, 0.72);
+	backdrop-filter: blur(6px);
+	box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.08), 0 4px 14px rgba(0, 0, 0, 0.18);
+	color: rgba(255, 255, 255, 0.86);
+	font: 500 11px/1.25 ui-sans-serif, system-ui, -apple-system, sans-serif;
+	font-variant-numeric: tabular-nums;
+	white-space: nowrap;
+	user-select: none;
+}
+.pose-rotation-axes { display: flex; gap: 9px; }
+.pose-rotation-axes span { display: inline-flex; gap: 3px; opacity: 0.72; }
+.pose-rotation-axes span.active { opacity: 1; }
+.pose-rotation-readout i { font-style: normal; font-weight: 600; }
+.pose-rotation-readout [data-axis="x"] i, .pose-rotation-delta[data-axis="x"] span { color: #ff6b5e; }
+.pose-rotation-readout [data-axis="y"] i, .pose-rotation-delta[data-axis="y"] span { color: #7ee07a; }
+.pose-rotation-readout [data-axis="z"] i, .pose-rotation-delta[data-axis="z"] span { color: #5c9dff; }
+.pose-rotation-delta { display: flex; gap: 4px; font-size: 13px; font-weight: 600; color: #fff; }

package/src/pose-gizmo.js

@@ -0,0 +1,96 @@
+import * as THREE from "three";
+
+// Left side runs cool (blue arm, teal leg), right side warm (red arm, magenta leg); the pelvis is
+// its own amber so the body's root reads apart from the spine above it.
+export const HANDLE_COLORS = Object.freeze({
+	pelvis: "#ffb21e",
+	torso: "#2fd66b",
+	head: "#a37bff",
+	leftArm: "#3d8bff",
+	leftLeg: "#14c8e6",
+	rightArm: "#ff4d6a",
+	rightLeg: "#e44dff",
+});
+export const ROTATION_AXES = Object.freeze([
+	{ axis: "x", dir: new THREE.Vector3(1, 0, 0), color: "#ff6b5e" },
+	{ axis: "y", dir: new THREE.Vector3(0, 1, 0), color: "#7ee07a" },
+	{ axis: "z", dir: new THREE.Vector3(0, 0, 1), color: "#5c9dff" },
+]);
+
+const RING_BACK_OPACITY = 0.22;
+
+// Fades the half of a ring that faces away from the camera (relative to the ring's centre), the way
+// DCC rotate gizmos do, so the three rings stop crossing over the bone like a cage.
+export function backFaceFade(material) {
+	material.onBeforeCompile = (shader) => {
+		shader.uniforms.ringBackOpacity = { value: RING_BACK_OPACITY };
+		shader.vertexShader = shader.vertexShader
+			.replace("#include <common>", "#include <common>\nvarying float vRingFront;")
+			.replace("#include <project_vertex>", `#include <project_vertex>
+				vec4 ringCentre = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+				vRingFront = smoothstep(-0.02, 0.02, mvPosition.z - ringCentre.z);`);
+		shader.fragmentShader = shader.fragmentShader
+			.replace("#include <common>", "#include <common>\nvarying float vRingFront;\nuniform float ringBackOpacity;")
+			.replace("#include <opaque_fragment>", "#include <opaque_fragment>\ngl_FragColor.a *= mix(ringBackOpacity, 1.0, vRingFront);");
+	};
+	material.customProgramCacheKey = () => "pose-ring-backfade";
+	return material;
+}
+
+function handlePart(id = "") {
+	const match = /^(left|right)(.*)$/.exec(String(id));
+	if (match) return `${match[1]}${/knee|foot|leg|toe|hip/i.test(match[2]) ? "Leg" : "Arm"}`;
+	if (id === "hips") return "pelvis";
+	return id === "head" ? "head" : "torso";
+}
+
+export function handleColor(id) {
+	return HANDLE_COLORS[handlePart(id)];
+}
+
+const v0 = new THREE.Vector3();
+const v1 = new THREE.Vector3();
+const cross = new THREE.Vector3();
+
+/** Signed angle (radians) that turns `start` into `current` about `axis`, both measured from `origin`. */
+export function ringAngle(axis, origin, start, current) {
+	v0.subVectors(start, origin);
+	v1.subVectors(current, origin);
+	if (v0.lengthSq() < 1e-12 || v1.lengthSq() < 1e-12) return 0;
+	cross.crossVectors(v0, v1);
+	return Math.atan2(cross.dot(axis), v0.dot(v1));
+}
+
+const relative = new THREE.Quaternion();
+const euler = new THREE.Euler();
+
+/**
+ * Rotation away from the bind pose in the parent frame (the frame the rings turn in), as XYZ Euler
+ * degrees rounded to 0.1. The pose system applies a correction as `delta · bind`, so the delta is
+ * recovered as `current · bind⁻¹`.
+ */
+export function rotationFromBindDeg(bindQuat, quat) {
+	relative.copy(bindQuat ?? relative.identity()).invert().premultiply(quat);
+	euler.setFromQuaternion(relative, "XYZ");
+	const round = (rad) => Math.round(THREE.MathUtils.radToDeg(rad) * 10) / 10 || 0;
+	return { x: round(euler.x), y: round(euler.y), z: round(euler.z) };
+}
+
+export function rotationReadout(deg, drag = null) {
+	const axes = ["x", "y", "z"].map((axis) => ({ axis, value: `${Math.round(deg[axis])}°`, active: drag?.axis === axis }));
+	if (!drag) return { delta: null, axes };
+	const value = THREE.MathUtils.radToDeg(drag.angle);
+	return { delta: { axis: drag.axis, value: `${value >= 0 ? "+" : "−"}${Math.abs(value).toFixed(1)}°` }, axes };
+}
+
+const bindCache = new WeakMap();
+
+export function bindQuaternionOf(bone) {
+	if (bindCache.has(bone)) return bindCache.get(bone);
+	let node = bone;
+	while (node && !node.userData?.poseBind) node = node.parent;
+	const saved = node?.userData.poseBind.get(bone);
+	const quat = saved ? new THREE.Quaternion(saved.x, saved.y, saved.z, saved.w) : null;
+	bindCache.set(bone, quat);
+	return quat;
+}