cozyclay 1.2.0 → 1.3.0

package/src/ardy/timeline.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { frameFromClientX, promptMoveStartFrame, shotBlockGeometry } from "./timeline-coordinates.js";
+import { frameFromClientX, motionTrimRange, promptMoveStartFrame, shotBlockGeometry } from "./timeline-coordinates.js";
 import { promptResizeFrame } from "./timeline-resize.js";
 import { ko, isKo } from "../locale.js";
 
@@ -18,8 +18,8 @@ import { ko, isKo } from "../locale.js";
  * and PlayView ride the keys segment by segment.
  */
 
-const DEFAULT_FRAME_COUNT = 300; // 15 s @ 20 fps, the ARDY Core cadence
-const DEFAULT_FPS = 20;
+const DEFAULT_FRAME_COUNT = 360; // 15 s @ 24 fps, the production clock the app timeline runs on
+const DEFAULT_FPS = 24;
 // Trackpad/wheel zoom over the FRAME ruler: the gesture changes only the
 // horizontal visual scale of the time surface — never frameCount, fps,
 // duration, waypoints or the generation request.
@@ -168,15 +168,24 @@ export default function Timeline({
 	fps = DEFAULT_FPS,
 	playbackSpeed = 1,
 	playing,
+	// Which cast member's animation layer these tracks edit ("S2", …).
+	trackOwner = null,
+	// Read-only previews of the OTHER cast members' layers: their prompt
+	// blocks and root pins render dimmed with an owner chip, so the whole
+	// cast's schedule is visible while only the active layer is editable.
+	ghostLayers = [], // [{ owner, promptClips: [], waypointFrames: [] }]
 	waypointMode,
 	waypointFrames = [],
-	pathSpeed = null,
+	pathSpeed = null, // { min, max, warn } in m/s, shown on the 2D Root label
 	badge,
 	promptClips = [],
 	selectedPromptId,
 	pendingWaypointFrame = null,
 	ikMode = false,
 	ikDisabled = false, // a loaded motion owns the rig
+	// The ACTIVE cast member's loaded take, drawn as a passive strip on the
+	// Full-Body lane. Frames are already on the timeline's 24 fps clock.
+	motion = null, // { frames, label } | null
 	ikFrames = [], // sorted full-body key frames
 	footSnap = true, // feet stay planted while the body moves
 	shots = [],
@@ -224,6 +233,8 @@ export default function Timeline({
 	onShotCut,
 	onShotSplit,
 	onShotMove,
+	onMotionTrim,
+	onMotionTrimReset,
 }) {
 	const [expanded, setExpanded] = useState(true);
 	const [zoom, setZoom] = useState(ZOOM_DEFAULT);
@@ -244,7 +255,7 @@ export default function Timeline({
 	// The window key/interval handlers register once; the latest callbacks
 	// are read through a ref so they never go stale mid-playback.
 	const handlers = useRef({});
-	handlers.current = { onScrub, onAdvance, onStep, onPlayToggle, onWaypointToggle, onMarkerSelect, onMarkerRemove, onRootKeyframeAdd, onPromptAdd, onPromptSelect, onPromptChange, onPromptResize, onPromptMove, onPromptRemove, onIkToggle, onIkKeyframeAdd, onIkKeyframeRemove, onFootSnapToggle, onCameraMoveSelect, onCameraKeyframeAdd, onCameraKeyframeMove, onCameraKeyframeRemove, onCameraBlockSelect, onCameraBlockChange, onCameraPreview, onCameraRailDrawToggle, onRailSelect, onRailMove, onRailRangeChange, onRailRemove, onShotSelect, onShotBoundaryMove, onShotRename, onShotRemove, onShotDuplicate, onShotCut, onShotSplit, onShotMove };
+	handlers.current = { onScrub, onAdvance, onStep, onPlayToggle, onWaypointToggle, onMarkerSelect, onMarkerRemove, onRootKeyframeAdd, onPromptAdd, onPromptSelect, onPromptChange, onPromptResize, onPromptMove, onPromptRemove, onIkToggle, onIkKeyframeAdd, onIkKeyframeRemove, onFootSnapToggle, onCameraMoveSelect, onCameraKeyframeAdd, onCameraKeyframeMove, onCameraKeyframeRemove, onCameraBlockSelect, onCameraBlockChange, onCameraPreview, onCameraRailDrawToggle, onRailSelect, onRailMove, onRailRangeChange, onRailRemove, onShotSelect, onShotBoundaryMove, onShotRename, onShotRemove, onShotDuplicate, onShotCut, onShotSplit, onShotMove, onMotionTrim, onMotionTrimReset };
 
 	// Trackpad/wheel zoom over the FRAME ruler lane only. React registers
 	// onWheel as passive, so a synthetic onWheel could never preventDefault —
@@ -484,6 +495,47 @@ export default function Timeline({
 		e.currentTarget.releasePointerCapture?.(e.pointerId);
 	}
 
+	// Motion trim: frame-accurate drag of the loaded take's in/out point on
+	// the Full-Body strip. No block snapping — a cut lands on the exact frame
+	// the hand releases. The preview lives here; the CUT itself is App's.
+	const motionTrimRef = useRef(null);
+	const [trimPreview, setTrimPreview] = useState(null);
+
+	function beginMotionTrim(e, edge) {
+		if (e.button !== 0 || !motion) return;
+		e.preventDefault();
+		e.stopPropagation();
+		e.currentTarget.setPointerCapture?.(e.pointerId);
+		const rect = e.currentTarget.closest(".tl-lane")?.getBoundingClientRect();
+		if (!rect || rect.width < 2) return;
+		const max = Math.min(motion.frames, displayFrameCount) - 1;
+		// The preview always restarts from the FULL take: App composes the cut
+		// as trimOffset + start, so an end-only drag must still report start 0.
+		motionTrimRef.current = { edge, rect, max, displayFrameCount, preview: { start: 0, end: max } };
+		setTrimPreview({ start: 0, end: max });
+	}
+
+	function moveMotionTrim(e) {
+		const active = motionTrimRef.current;
+		if (!active) return;
+		// Same pixel→frame transform as every other lane, off the pointer-down
+		// geometry, so the handle stays under the cursor at any zoom.
+		const frame = Math.min(active.max, frameFromClientX(e.clientX, active.rect.left, active.rect.width, active.displayFrameCount, frameCount));
+		const next = motionTrimRange(active.edge, frame, active.preview, active.max);
+		active.preview = next;
+		setTrimPreview(next);
+	}
+
+	function endMotionTrim(e) {
+		const active = motionTrimRef.current;
+		motionTrimRef.current = null;
+		e.currentTarget.releasePointerCapture?.(e.pointerId);
+		setTrimPreview(null);
+		if (active && (active.preview.start > 0 || active.preview.end < active.max)) {
+			handlers.current.onMotionTrim?.(active.preview.start, active.preview.end);
+		}
+	}
+
 	// Camera key dots re-time by dragging, like prompt clips move: the frame
 	// delta comes from the pointer-down geometry so a growing timeline cannot
 	// feed back into the next pointermove.
@@ -917,6 +969,17 @@ export default function Timeline({
 							<div className={"tl-track" + (name === "Prompts" ? " prompts" : "") + (name === IK_LANE ? " ik" : "") + (name === SHOTS_LANE ? " shots" : "")} key={name}>
 								<span className="tl-track-label">
 									{TRACK_LABELS_KO[name]}
+									{trackOwner && (name === "Prompts" || name === "2D Root") && <em className="tl-track-owner">{trackOwner}</em>}
+									{name === "2D Root" && pathSpeed && (
+										<em
+											className={"tl-path-speed" + (pathSpeed.warn ? " warn" : "")}
+											title={isKo ? `핀 구간 속도 ${pathSpeed.min.toFixed(1)}~${pathSpeed.max.toFixed(1)} m/s — 자연 보행은 0.8~1.2 m/s` : `Leg speeds ${pathSpeed.min.toFixed(1)}–${pathSpeed.max.toFixed(1)} m/s — natural gait is 0.8–1.2 m/s`}
+										>
+											{pathSpeed.min === pathSpeed.max
+												? `${pathSpeed.min.toFixed(1)} m/s`
+												: `${pathSpeed.min.toFixed(1)}–${pathSpeed.max.toFixed(1)} m/s`}
+										</em>
+									)}
 									{name === "Prompts" && <button className="tl-track-add" type="button" title={ko("Add 2 second prompt clip", "2초 프롬프트 클립 추가")} onClick={() => handlers.current.onPromptAdd?.(frame)}>+</button>}
 									{name === SHOTS_LANE && (
 										<button
@@ -1079,6 +1142,16 @@ export default function Timeline({
 											</div>
 										);
 									})}
+									{name === "Prompts" && ghostLayers.map((layer) => layer.promptClips.map((clip) => (
+										<div
+											key={`${layer.owner}:${clip.id}`}
+											className="tl-chip ghost"
+											style={{ "--tl-f-start": clipPct(clip.startFrame), "--tl-f-end": clipPct(clip.endFrame) }}
+											title={`${layer.owner} · ${clip.text}`}
+										>
+											<span className="tl-chip-ghost-label">{layer.owner} · {clip.text || "…"}</span>
+										</div>
+									)))}
 									{name === "Prompts" && promptClips.map((clip) => {
 										const duration = ((clip.endFrame - clip.startFrame) / Math.max(1, fps)).toFixed(1);
 										return (
@@ -1089,6 +1162,44 @@ export default function Timeline({
 											</div>
 										);
 									})}
+									{name === IK_LANE && motion && (
+										<div
+											className={"tl-motion-clip" + (trimPreview ? " trimming" : "")}
+											style={{
+												"--tl-f-start": clipPct(trimPreview ? trimPreview.start : 0),
+												"--tl-f-end": clipPct(trimPreview ? trimPreview.end + 1 : Math.min(motion.frames, displayFrameCount)),
+											}}
+											title={isKo
+												? `불러온 테이크 — ${motion.frames}프레임. 양끝 핸들로 잘라내고, 핸들 우클릭으로 전체 길이 복원`
+												: `Loaded take — ${motion.frames} frames. Drag the end handles to cut; right-click a handle to restore the full take`}
+										>
+											<button
+												className="tl-motion-clip-handle start"
+												type="button"
+												aria-label={ko("Trim take start", "테이크 시작점 자르기")}
+												onPointerDown={(e) => beginMotionTrim(e, "start")}
+												onPointerMove={moveMotionTrim}
+												onPointerUp={endMotionTrim}
+												onPointerCancel={endMotionTrim}
+												onContextMenu={(e) => { e.preventDefault(); handlers.current.onMotionTrimReset?.(); }}
+											/>
+											<span className="tl-motion-clip-label">
+												{trimPreview
+													? `${trimPreview.start}–${trimPreview.end} (${trimPreview.end - trimPreview.start + 1}f)`
+													: motion.label}
+											</span>
+											<button
+												className="tl-motion-clip-handle end"
+												type="button"
+												aria-label={ko("Trim take end", "테이크 끝점 자르기")}
+												onPointerDown={(e) => beginMotionTrim(e, "end")}
+												onPointerMove={moveMotionTrim}
+												onPointerUp={endMotionTrim}
+												onPointerCancel={endMotionTrim}
+												onContextMenu={(e) => { e.preventDefault(); handlers.current.onMotionTrimReset?.(); }}
+											/>
+										</div>
+									)}
 									{name === IK_LANE &&
 										ikFrames.map((f) => (
 											<span
@@ -1108,6 +1219,14 @@ export default function Timeline({
 												}}
 											/>
 										))}
+									{name === "2D Root" && ghostLayers.map((layer) => layer.waypointFrames.map((f) => (
+										<span
+											key={`${layer.owner}:${f}`}
+											className="tl-marker wp ghost"
+											style={{ "--tl-f": framePct(f, displayFrameCount) }}
+											title={`${layer.owner} · frame ${f}`}
+										/>
+									)))}
 									{name === "2D Root" &&
 										[...waypointFrames, ...(pendingWaypointFrame == null || waypointFrames.includes(pendingWaypointFrame) ? [] : [pendingWaypointFrame])].map((f) => (
 											<span

package/src/ardy/to-cskel27.js

@@ -3,11 +3,12 @@
  * reads (local_rot_mats 27x3x3, posed_joints 27x3; the generator then runs its
  * own FK, consulting only posed_joints[0] as the root).
  *
- * The 19 joints CozyClay authors map through each bone's armature-space rest
- * rotation Rb (cskel27-rest.json): L = Rb @ basis @ Rb^T. The other 8 joints
- * get identity, i.e. "at ARDY rest" — CozyClay does not author them and must
- * not invent them; `filled_identity` says which joints that happened for and
- * why, so callers can report it rather than guess.
+ * The 19 joints CozyClay authors map through each Mixamo bone's armature-space
+ * rest rotation Rb (cskel27-rest.json): L = Rb @ basis @ Rb^T. ARDY has four
+ * torso segments where Mixamo has three, so Mixamo Spine/Spine1 target ARDY
+ * Spine1/Spine2, matching playback's map. The remaining joints get identity;
+ * `filled_identity` records them and `rotation_constraint_indices` identifies
+ * the rotations that are genuinely authored.
  *
  * Proportions are never hardcoded: bone offsets come from the reference frame
  * of the same base clip the pose will constrain (mirroring
@@ -16,7 +17,11 @@
  * correct by construction.
  */
 
-import { COZYCLAY_BONES, CSKEL27_JOINTS } from "./cskel27.js";
+import {
+	COZYCLAY_BONES,
+	COZYCLAY_TO_CSKEL27,
+	CSKEL27_JOINTS,
+} from "./cskel27.js";
 import { CSKEL27_NEUTRAL } from "./cskel27-neutral.js";
 import {
 	basisQuaternionToLocalRotation,
@@ -36,6 +41,13 @@ const IDENTITY = [
 	[0, 0, 1],
 ];
 
+const SOURCE_BY_TARGET = new Map(
+	COZYCLAY_BONES.map((source) => [
+		CSKEL27_JOINTS[COZYCLAY_TO_CSKEL27[source]],
+		source,
+	])
+);
+
 const CANONICAL_ROOT_Y = -Math.min(...CSKEL27_NEUTRAL.map((joint) => joint[1]));
 
 /** Floor-aligned CoreSkeleton27 reference used when no clip reference is
@@ -160,23 +172,28 @@ export function poseToCskel27({ pose, rest, reference }) {
 		restByJoint.set(entry.name, entry.rest);
 	}
 
-	const authored = new Set(COZYCLAY_BONES);
 	const local_rot_mats = new Array(CSKEL27_JOINTS.length);
 	const filled_identity = [];
+	const rotation_constraint_indices = [];
 	for (let index = 0; index < CSKEL27_JOINTS.length; index += 1) {
 		const name = CSKEL27_JOINTS[index];
-		const rb = restByJoint.get(name);
-		if (authored.has(name) && rb !== null && rb !== undefined) {
+		const sourceName = SOURCE_BY_TARGET.get(name);
+		const rb = sourceName ? restByJoint.get(sourceName) : null;
+		if (sourceName && rb !== null && rb !== undefined) {
 			// L = Rb @ basis @ Rb^T; basisQuaternionToLocalRotation is the
 			// quatToMat + basisToLocal composition from convert.js.
-			local_rot_mats[index] = basisQuaternionToLocalRotation(pose.bones[name], rb);
+			local_rot_mats[index] = basisQuaternionToLocalRotation(
+				pose.bones[sourceName],
+				rb
+			);
+			rotation_constraint_indices.push(index);
 		} else {
 			// Fresh identity per joint so callers can never alias a shared
 			// constant by mutating one row.
 			local_rot_mats[index] = IDENTITY.map((row) => row.slice());
 			filled_identity.push({
 				joint: name,
-				reason: authored.has(name) ? "no rest rotation" : "not authored",
+				reason: sourceName ? "no rest rotation" : "not authored",
 			});
 		}
 	}
@@ -201,5 +218,10 @@ export function poseToCskel27({ pose, rest, reference }) {
 	const canonicalRoot = canonicalCskel27Reference().posed_joints[0];
 	const posed_joints = forwardKinematics(local_rot_mats, offsets, pose.root ?? canonicalRoot);
 
-	return { local_rot_mats, posed_joints, filled_identity };
+	return {
+		local_rot_mats,
+		posed_joints,
+		filled_identity,
+		rotation_constraint_indices,
+	};
 }

package/src/ardy/trim.js

@@ -0,0 +1,33 @@
+// trim.js — cut a loaded take to a frame range. The slice is a NEW motion
+// object in the exact npz-decoded shape; the caller keeps the original, so
+// trimming is non-destructive and re-trimming always cuts from the full
+// take. Frame 0 of the slice becomes the playback anchor: applyMotionFrame
+// re-anchors X/Z on the anchor frame, so a mid-clip cut plays at the
+// character's placement instead of teleporting to the original frame 0.
+// The spread carries every non-array field with the slice — `personScale`
+// included: a cut is the same performer, and a take that lost its stature
+// mid-edit would replay the remaining frames at the wrong stride length.
+
+import { CSKEL27_JOINTS } from "./cskel27.js";
+
+export function sliceMotion(motion, startFrame, endFrame) {
+	if (!motion || !Number.isInteger(motion.frames) || motion.frames < 1) {
+		throw new Error("sliceMotion: motion.frames must be a positive integer");
+	}
+	if (!Number.isInteger(startFrame) || !Number.isInteger(endFrame)) {
+		throw new Error("sliceMotion: startFrame and endFrame must be integers");
+	}
+	if (startFrame < 0 || endFrame >= motion.frames || startFrame > endFrame) {
+		throw new Error(`sliceMotion: range ${startFrame}..${endFrame} is outside 0..${motion.frames - 1}`);
+	}
+	const joints = CSKEL27_JOINTS.length;
+	const frames = endFrame - startFrame + 1;
+	return {
+		...motion,
+		frames,
+		rotMats: motion.rotMats.slice(startFrame * joints * 9, (endFrame + 1) * joints * 9),
+		rootPos: motion.rootPos.slice(startFrame * 3, (endFrame + 1) * 3),
+		posedJoints: motion.posedJoints.slice(startFrame * joints * 3, (endFrame + 1) * joints * 3),
+		anchorFrame: 0,
+	};
+}

package/src/asset-pane.jsx

@@ -0,0 +1,36 @@
+import { ko } from "./locale.js";
+import { CHARACTER_MODEL_IDS } from "./scenes.js";
+
+/** Casting assets offered in the bottom Assets tab. `id` doubles as the FBX
+ * file stem and the ARDY wire rig name (see scenes.js). */
+export const CHARACTER_ASSETS = CHARACTER_MODEL_IDS.map((id) => ({
+	id,
+	label: id === "y-bot-tpose" ? "Y Bot" : "X Bot",
+}));
+
+/** Bottom-window asset shelf: character cards the operator drags into the
+ * shot pane to spawn. The drag itself is owned by App (ghost overlay +
+ * ground raycast on drop); the pane only reports the grab. */
+export default function AssetPane({ onAssetGrab }) {
+	return (
+		<div className="assets-grid">
+			{CHARACTER_ASSETS.map((asset) => (
+				<button
+					type="button"
+					className="asset-card"
+					key={asset.id}
+					title={ko(`Drag ${asset.label} into the scene`, `${asset.label}을(를) 씬에 드래그하세요`)}
+					onPointerDown={(event) => {
+						if (event.button !== 0) return;
+						event.preventDefault();
+						onAssetGrab?.(asset, event);
+					}}
+				>
+					<span className="asset-card-swatch" data-model={asset.id} aria-hidden="true" />
+					<span className="asset-card-label">{asset.label}</span>
+					<span className="asset-card-kind">{ko("Character", "인물")}</span>
+				</button>
+			))}
+		</div>
+	);
+}

package/src/dualview.jsx

@@ -53,9 +53,15 @@ const EDGE_FRAGMENT = `
 	}
 
 	void main() {
+		float centerZ = linearDepth(texture2D(tDepth, vUv).x);
+		// Keep the stroke kernel stable, but soften its opacity past the 3 m
+		// reference distance. A minimum 42% opacity keeps distant silhouettes
+		// readable without letting ink become the only visible part of the body.
+		float distanceFade = orthographic > 0.5
+			? 1.0
+			: mix(0.42, 1.0, clamp(3.0 / max(centerZ, 0.001), 0.0, 1.0));
 		vec2 x = vec2(texel.x * 0.8, 0.0);
 		vec2 y = vec2(0.0, texel.y * 0.8);
-		float centerZ = linearDepth(texture2D(tDepth, vUv).x);
 		float nearestZ = min(
 			min(linearDepth(texture2D(tDepth, vUv - x).x), linearDepth(texture2D(tDepth, vUv + x).x)),
 			min(linearDepth(texture2D(tDepth, vUv - y).x), linearDepth(texture2D(tDepth, vUv + y).x))
@@ -88,7 +94,7 @@ const EDGE_FRAGMENT = `
 		float depthLine = smoothstep(0.055, 0.16, depthEdge);
 		float normalLine = smoothstep(0.7, 1.7, normalEdge);
 		float edge = max(depthLine * foregroundOwner, normalLine * 0.68);
-		gl_FragColor = vec4(edgeColor, edge * 0.76);
+		gl_FragColor = vec4(edgeColor, edge * 0.76 * distanceFade);
 	}
 `;
 
@@ -103,7 +109,7 @@ export function fitAspect(rect, aspect) {
 	return { x: rect.x + (rect.w - w) / 2, y: rect.y + (rect.h - h) / 2, w, h };
 }
 
-export function DualRender({ stageRef, mainRef, insetRef, shotCamRef, planCamRef, poserCamRef, ikMode = false, planIsMain, playMode = false, insetCollapsed = false, planZoom = 1 }) {
+export function DualRender({ stageRef, mainRef, insetRef, shotCamRef, planCamRef, poserCamRef, ikMode = false, planIsMain, playMode = false, insetCollapsed = false, planZoom = 1, shotAspect = SHOT_ASPECT }) {
 	const invalidate = useThree((state) => state.invalidate);
 	// Demand mode draws nothing by itself: the first frame can land before the
 	// layout settles (the inset reads 0x0), and async scene content commits
@@ -253,7 +259,7 @@ export function DualRender({ stageRef, mainRef, insetRef, shotCamRef, planCamRef
 		};
 
 		gl.autoClear = true;
-		shotCam.aspect = SHOT_ASPECT;
+		shotCam.aspect = shotAspect;
 		shotCam.updateProjectionMatrix();
 		// An orthographic plan keeps every puck the same size and the floor
 		// undistorted; a perspective one skews the pucks near the edges and reads
@@ -279,7 +285,7 @@ export function DualRender({ stageRef, mainRef, insetRef, shotCamRef, planCamRef
 			// GIZMO_LAYER and is dropped for this draw, mask restored after.
 			const playMask = shotCam.layers.mask;
 			shotCam.layers.disable(GIZMO_LAYER);
-			draw(shotCam, mainRect, fitAspect(mainRect, SHOT_ASPECT));
+			draw(shotCam, mainRect, fitAspect(mainRect, shotAspect));
 			shotCam.layers.mask = playMask;
 		} else if (ikMode && poserCam) {
 			// IK mode: the main pane is the poser working view (free navigation,
@@ -288,12 +294,12 @@ export function DualRender({ stageRef, mainRef, insetRef, shotCamRef, planCamRef
 			poserCam.aspect = mainRect.w / mainRect.h;
 			poserCam.updateProjectionMatrix();
 			draw(poserCam, mainRect);
-			if (!insetCollapsed) draw(shotCam, insetRect, fitAspect(insetRect, SHOT_ASPECT));
+			if (!insetCollapsed) draw(shotCam, insetRect, fitAspect(insetRect, shotAspect));
 		} else if (planIsMain) {
 			draw(planCam, planPane, null, false);
-			if (!insetCollapsed) draw(shotCam, shotPane, fitAspect(shotPane, SHOT_ASPECT));
+			if (!insetCollapsed) draw(shotCam, shotPane, fitAspect(shotPane, shotAspect));
 		} else {
-			draw(shotCam, shotPane, fitAspect(shotPane, SHOT_ASPECT));
+			draw(shotCam, shotPane, fitAspect(shotPane, shotAspect));
 			if (!insetCollapsed) draw(planCam, planPane, null, false);
 		}
 

package/src/hierarchy-model.js

@@ -27,12 +27,56 @@ export const HIERARCHY_NODES = [
 								label: "Rig",
 								kind: "rig",
 								children: [
-									{ id: "rig.hips", label: "Root / Hips", kind: "bone" },
-									{ id: "rig.spine", label: "Spine", kind: "bone" },
-									{ id: "rig.leftArm", label: "Left Arm", kind: "bone" },
-									{ id: "rig.rightArm", label: "Right Arm", kind: "bone" },
-									{ id: "rig.leftLeg", label: "Left Leg", kind: "bone" },
-									{ id: "rig.rightLeg", label: "Right Leg", kind: "bone" },
+									{
+										id: "rig.torso",
+										label: "Torso",
+										kind: "rig",
+										children: [
+											{ id: "rig.hips", label: "Root / Hips", kind: "bone" },
+											{ id: "rig.spine", label: "Spine", kind: "bone" },
+											{ id: "rig.chest", label: "Chest", kind: "bone" },
+											{ id: "rig.neck", label: "Neck", kind: "bone" },
+											{ id: "rig.head", label: "Head", kind: "bone" },
+										],
+									},
+									{
+										id: "rig.leftArm",
+										label: "Left Arm",
+										kind: "rig",
+										children: [
+											{ id: "rig.leftShoulder", label: "Left Shoulder", kind: "bone" },
+											{ id: "rig.leftElbow", label: "Left Elbow", kind: "bone" },
+											{ id: "rig.leftHand", label: "Left Hand", kind: "bone" },
+										],
+									},
+									{
+										id: "rig.rightArm",
+										label: "Right Arm",
+										kind: "rig",
+										children: [
+											{ id: "rig.rightShoulder", label: "Right Shoulder", kind: "bone" },
+											{ id: "rig.rightElbow", label: "Right Elbow", kind: "bone" },
+											{ id: "rig.rightHand", label: "Right Hand", kind: "bone" },
+										],
+									},
+									{
+										id: "rig.leftLeg",
+										label: "Left Leg",
+										kind: "rig",
+										children: [
+											{ id: "rig.leftKnee", label: "Left Knee", kind: "bone" },
+											{ id: "rig.leftFoot", label: "Left Foot", kind: "bone" },
+										],
+									},
+									{
+										id: "rig.rightLeg",
+										label: "Right Leg",
+										kind: "rig",
+										children: [
+											{ id: "rig.rightKnee", label: "Right Knee", kind: "bone" },
+											{ id: "rig.rightFoot", label: "Right Foot", kind: "bone" },
+										],
+									},
 								],
 							},
 						],
@@ -51,19 +95,57 @@ export const HIERARCHY_NODES = [
 	},
 ];
 
-export function buildHierarchyNodes(sceneObjects = []) {
+export function buildHierarchyNodes(sceneObjects = [], characters = null) {
 	const clone = (node) => {
 		const next = { ...node };
 		if (node.id === "props") {
-			next.children = sceneObjects.map((object) => ({
-				id: `object:${object.id}`,
-				label: object.name,
-				kind: "object",
-			}));
+			// Grouped props nest under their parent, so a rocket built from ten
+			// primitives reads as one thing in the tree instead of ten siblings.
+			const childrenOf = (parentId) =>
+				sceneObjects
+					.filter((object) => (object.parent ?? null) === parentId)
+					.map((object) => {
+						const row = { id: `object:${object.id}`, label: object.name, kind: "object" };
+						const nested = childrenOf(object.id);
+						if (nested.length) row.children = nested;
+						return row;
+					});
+			// An object whose parent is missing still has to appear somewhere, so
+			// anything unreachable from the top level is shown at the top level.
+			const ids = new Set(sceneObjects.map((object) => object.id));
+			const rooted = sceneObjects.filter(
+				(object) => (object.parent ?? null) === null || !ids.has(object.parent),
+			);
+			next.children = rooted.map((object) => {
+				const row = { id: `object:${object.id}`, label: object.name, kind: "object" };
+				const nested = childrenOf(object.id);
+				if (nested.length) row.children = nested;
+				return row;
+			});
 		} else if (node.children) {
 			next.children = node.children.map(clone);
 		}
 		return next;
 	};
-	return HIERARCHY_NODES.map(clone);
+	const nodes = HIERARCHY_NODES.map(clone);
+	// The cast is list-driven: one row per visible character. The first two
+	// keep the legacy row ids (characterA/characterB) that selection, IK and
+	// the inspector already route to; extras carry their character id.
+	if (Array.isArray(characters)) {
+		const group = nodes[0]?.children?.find((node) => node.id === "characters");
+		if (group) {
+			const rigChildren = group.children.find((node) => node.id === "characterA")?.children;
+			// Row ids follow the entry's LIST index so they match the viewport
+			// pickId (A/B/charId) stamped by the Character renderer in App.jsx.
+			group.children = characters.flatMap((entry, listIndex) => entry.hidden ? [] : [{
+				id: listIndex === 0 ? "characterA" : listIndex === 1 ? "characterB" : `character:${entry.id}`,
+				label: `Character ${listIndex + 1}`,
+				kind: "character",
+				// Only the primary carries the rig subtree: IK and viewport pose
+				// handles are scoped to it this phase.
+				...(listIndex === 0 && rigChildren ? { children: rigChildren } : {}),
+			}]);
+		}
+	}
+	return nodes;
 }