cozyclay 2.0.2 → 2.1.1

package/src/App.jsx

@@ -6,6 +6,7 @@ import { useScenes } from "./domains/scenes.js";
 import { useStage } from "./domains/stage.js";
 import StudioShell from "./shell/StudioShell.jsx";
 import ViewportToolbar from "./shell/ViewportToolbar.jsx";
+import CompositionGuideButton from "./shell/CompositionGuideButton.jsx";
 import { StudioShellContext } from "./shell/studio-shell-context.js";
 
 import {
@@ -48,18 +49,35 @@ import { createLiveControl, loadLiveWorkspaceId, mintLiveWorkspaceId } from "./l
 import { createFirstEditTracker, semanticEditKind } from "./semantic-edit.js";
 
 import AgentPanel from "./workflow/AgentPanel.jsx";
+import SculptPanel from "./panels/SculptPanel.jsx";
+import { createAgentPort, createSculptRun } from "./sculpt-run.js";
+import { SculptTurntable } from "./sculpt-stage.jsx";
+import { measureReferenceOutline } from "./sculpt-compare.js";
+import { BLUEPRINT_LAYOUT, buildBlueprintPrompt } from "./sculpt-blueprint.js";
+import { browserSculptImages } from "./commands/sculpt-images.js";
+import { sculptAgentClient, sculptModelLabel } from "./sculpt-mode.js";
+import { useSculptMode } from "./use-sculpt-mode.js";
+import { useFirstSuccessPrompt } from "./use-first-success-prompt.js";
+import { useCameraTutorial } from "./use-camera-tutorial.js";
+import { useEmbedBridge } from "./use-embed-bridge.js";
+import { useAssetShelf } from "./use-asset-shelf.js";
+import { useI2vCaptureModal } from "./use-i2v-capture-modal.js";
 import { StudioProtocolError } from "./studio-agent-protocol.js";
 import { elementByPath } from "./studio-elements.js";
 import {
 	resolveStudioToast,
 } from "./studio-actions.js";
 import { createStudioAppActions } from "./commands/index.js";
+import { STORYBOARD_MOTION_REFUSAL } from "./commands/view.js";
 
 import { createStudioAppBinding } from "./studio-app-binding.js";
 import { AppContext, createAppContext } from "./app-context.js";
 import { clone as cloneSkeleton } from "three/examples/jsm/utils/SkeletonUtils.js";
 
 import { PlanBoard } from "./planview.jsx";
+import { drawPlanDiagram } from "./plan-diagram.js";
+import { placementAt } from "./root-path.js";
+import { proxyYaw } from "./proxy-figure.jsx";
 import { autoColorHex, loadAutoColor } from "./auto-color.js";
 import { DualRender, fitAspect, GIZMO_LAYER } from "./dualview.jsx";
 import { GridFloor } from "./grid-floor.jsx";
@@ -114,10 +132,9 @@ import {
 	RAIL_SCHEDULE_RANGE,
 	resolveRailSchedule,
 } from "./camera-rail-schedule.js";
-import { SetProps } from "./props.jsx";
+import { ObjectCarrier, SetProps } from "./props.jsx";
 import {
 	CUTOUT_KIND,
-	MESH_KIND,
 	isEffectivelyHidden,
 	objectSize,
 	sceneObjectIdFromHierarchy,
@@ -147,10 +164,10 @@ import {
 } from "./matte.js";
 import { createMatteEditor } from "./matte-editor.js";
 import {
-	SCENES_STORAGE_KEY,
 	SCENES_VERSION,
 	activeSceneIndex,
 	createSceneStage,
+	isProxyFigure,
 	normalizeReferenceImage,
 } from "./scenes.js";
 import {
@@ -184,16 +201,19 @@ import { demoSeedGate, hasLineEditCapability, motionReadiness } from "./motion-r
 import { PWA_UPDATE_EVENT } from "./pwa.js";
 import {
 	createObjectPath,
+	insertPathMark,
 	objectTransformAt,
 	pathMetrics,
 	strokeToPathPoints,
-	MAX_PATH_POINTS,
 } from "./object-path.js";
+import { carriedPointAt, sceneObjectsAt } from "./object-travel.js";
+import { routeOwnerFor } from "./route-owner.js";
 import {
 	analyticsActive,
 	exportFailureCode,
 	recordSemanticEdit,
 	recordUseCase,
+	sculptRunTelemetry,
 	shouldAskUseCase,
 	startExportAttempt,
 	track,
@@ -201,13 +221,13 @@ import {
 	trackFeature,
 } from "./analytics.js";
 import { ko, isKo } from "./locale.js";
-import {
-	isPlaygroundEmbed,
-} from "./playground.js";
+import { characterCapabilities, kindRefusal, proxyFigureBounds } from "./character-kind.js";
 import { STARTER_SCENES } from "./starter-scenes.js";
 import { PART_COLOURS } from "./part-colours.js";
 import {
 	DEFAULT_POSE,
+	applyHipsOffset,
+	applyPose,
 } from "./poses.js";
 import {
 	IkHandles,
@@ -256,15 +276,13 @@ import { exportOffscreenVideo } from "./offscreen-export.js";
 import { parseRigNodeId } from "./hierarchy-model.js";
 import { timelineContentExtent } from "./timeline-extent.js";
 import {
-	GUIDE_LABELS,
 	guideGeometry,
-	nextGuideMode,
 	readStoredGuideMode,
 	writeStoredGuideMode,
 } from "./shot-guides.js";
 import { shotCaptureMeta } from "./shot-meta.js";
 import { buildShotPrompt } from "./shot-prompt.js";
-import { keyframePackEntries, keyframePackName } from "./keyframe-pack.js";
+import { buildKeyframePack, keyframePackEntries, keyframePackName, slugifyTitle } from "./keyframe-pack.js";
 import { buildZip } from "./zip-store.js";
 import { composeStoryboard } from "./storyboard.js";
 import { DEPTH_RANGE_M, depthRangeFromFrames, passFileName, renderPass } from "./render-passes.js";
@@ -272,12 +290,12 @@ import { DEPTH_RANGE_M, depthRangeFromFrames, passFileName, renderPass } from ".
 import { motionApiOrigin, I2V_MOTION_SHOT_ASPECT } from "./i2v-motion-client.js";
 import { serializeOtio } from "./otio.js";
 import "./shell/mode.css";
+import { readPoseFadeOpacity, withPoseFadeLifted, writePoseFadeOpacity } from "./pose-fade.js";
 import {
 	shotAtFrame,
 	shotIndexAtFrame,
 } from "./cuts.js";
 import {
-	ASSET_DELETE_UNDO_MS,
 	BRIDGE_RECHECK_MS,
 	CameraGlide,
 	CameraRailScenePreview,
@@ -437,11 +455,14 @@ function koSubjectParticle(word) {
  * A missing rig, a member with no clip and a layer with no keys are all
  * no-ops rather than errors: characters without a take keep their pose.
  */
-function poseMemberAtFrame(rig, clip, ikState, frame, blendFrames = 0) {
+function poseMemberAtFrame(rig, clip, ikState, frame, blendFrames = 0, pose = null) {
 	if (!rig) return;
 	if (clip) {
 		const sampled = sampleAt({ frameCount: clip.frames, motion: clip }, null, frame);
 		applyMotionFrame(rig, clip, sampled.motionFrame);
+	} else if (pose) {
+		applyPose(rig, pose);
+		applyHipsOffset(rig, pose.rootY ?? 0);
 	}
 	if (ikState && ikState.keys.size > 0 && ikState.chains && ikState.rig === rig) {
 		ikEvaluate(ikState.chains, ikState, frame, ikState.fkJoints, clip ? blendFrames : 0);
@@ -483,56 +504,12 @@ export default function App() {
 		getBus: () => studioBindingRef.current.bus,
 		notify: (...args) => setToast(...args),
 	}));
-	const embedMode = ["scene", "playview"].includes(new URLSearchParams(globalThis.location?.search || "").get("embed"));
-	// The landing page's try-it iframe: full studio interaction on a preset
-	// scene with the project chrome hidden and saving off (see playground.js).
-	const playgroundMode = isPlaygroundEmbed(globalThis.location?.search);
-	const [playgroundHint, setPlaygroundHint] = useState(null);
-	const playgroundExportRef = useRef(null);
-	// The camera tutorial (#206): the landing page's seven steps, run against
-	// the real studio instead of the playground iframe. It opens from
-	// /app/?tutorial=camera or from Settings ▾, and it is not offered inside an
-	// embed.
-
-	// Both doors go through startCameraTutorial (#209), which puts the studio in
-	// the state the landing page teaches these steps in — the city-block starter
-	// scene with the walk take on its character — so Shot / Rail / Play always
-	// have something to frame. That function is declared with the project
-	// actions further down; the listeners here reach it through a ref so they
-	// always call the current render's closure (the confirm reads projectDirty).
-	const [cameraTutorialEntry] = useState(() => {
-		const params = new URLSearchParams(globalThis.location?.search || "");
-		const query = params.get("tutorial") === "camera";
-		let firstRun = false;
-		try {
-			firstRun = !query && !params.get("scene") && !cameraTutorialSuppressed()
-				&& !loadProjectSession()?.name && !globalThis.localStorage?.getItem(SCENES_STORAGE_KEY);
-		} catch { firstRun = false; }
-		return !embedMode && !playgroundMode && !cameraTutorialSuppressed() && (query ? "query" : firstRun ? "first-run" : null);
-	});
-	const cameraTutorialQuery = Boolean(cameraTutorialEntry);
-	const [cameraTutorial, setCameraTutorial] = useState(false);
-	const cameraTutorialAnalytics = useRef(null);
-	const [cameraTutorialAttempt, setCameraTutorialAttempt] = useState(0);
-	const [cameraTutorialHandoff, setCameraTutorialHandoff] = useState(null);
-	const cameraTutorialCompletedRef = useRef(false);
-	const exportMenuTriggerRef = useRef(null);
-	const exportShotIdRef = useRef(null);
-	// The step the tutorial is on, published on the .app root so styles.css can
-	// spotlight the one control that step needs (#211).
-	const [cameraTutorialStep, setCameraTutorialStep] = useState(null);
-	const startCameraTutorialRef = useRef(null);
-	const cameraTutorialStarted = useRef(false);
-	// A tutorial restart never reloads the starter over the user's edits.
-	const tutorialStarterRef = useRef(false);
-	const tutorialLoadingRef = useRef(false);
-	const tutorialProjectEpochRef = useRef(0);
-	const tutorialSeedEpochRef = useRef(null);
-	// Armed once the starter is applied, consumed by the seed effect next to the
-	// hosted-demo seed as soon as the new character's rig exists.
-	const [tutorialSeedPending, setTutorialSeedPending] = useState(false);
+	const { embedMode, playgroundMode, playgroundHint, setPlaygroundHint, playgroundExportRef } = useEmbedBridge();
+	const { cameraTutorialEntry, cameraTutorialQuery, cameraTutorial, setCameraTutorial, cameraTutorialAnalytics, cameraTutorialAttempt, setCameraTutorialAttempt, cameraTutorialHandoff, setCameraTutorialHandoff, cameraTutorialCompletedRef, exportMenuTriggerRef, exportShotIdRef, cameraTutorialStep, setCameraTutorialStep, startCameraTutorialRef, cameraTutorialStarted, tutorialStarterRef, tutorialLoadingRef, tutorialProjectEpochRef, tutorialSeedEpochRef, tutorialSeedPending, setTutorialSeedPending } = useCameraTutorial({ embedMode, playgroundMode });
 	useEffect(() => {
 		if (!cameraTutorialQuery || cameraTutorialStarted.current) return;
+		// Storyboard projects never auto-open the seven-step camera tutorial.
+		if (scenesDomain.previsMode === "storyboard") return;
 		cameraTutorialStarted.current = true;
 		void startCameraTutorialRef.current?.({ source: cameraTutorialEntry });
 	}, [cameraTutorialQuery, cameraTutorialEntry]);
@@ -547,6 +524,7 @@ export default function App() {
 				setCameraTutorialHandoff(null);
 				return;
 			}
+			if (scenesDomain.previsMode === "storyboard") return;
 			void startCameraTutorialRef.current?.({ source: event.detail?.source ?? "settings" });
 		};
 		window.addEventListener("cozyclay:camera-tutorial", onTutorial);
@@ -795,6 +773,23 @@ export default function App() {
 	// bridge read this global, and the render path is still PlayView's.
 	globalThis.playMode = preview;
 	const playMode = preview;
+	// #441 moved shot authoring into commands and dropped the Shot and Rail
+	// signals the landing checklist waits for. Read them from the authored state,
+	// as the studio tutorial does (#586): a shot added here, and a rail drawn.
+	// Declared before the play signal: a drawn rail starts playback in the same
+	// commit, and the checklist expects Rail before Play.
+	const playgroundShotCount = useRef(null);
+	useEffect(() => {
+		if (!playgroundMode) return;
+		if (playgroundShotCount.current !== null && shots.length > playgroundShotCount.current) {
+			window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: "shot" }, "*");
+		}
+		playgroundShotCount.current = shots.length;
+	}, [playgroundMode, shots.length]);
+	const playgroundRailReady = playgroundMode && shots.some((shot) => Array.isArray(shot.camera?.cameraRail) && shot.camera.cameraRail.length >= 2);
+	useEffect(() => {
+		if (playgroundRailReady) window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: "rail" }, "*");
+	}, [playgroundRailReady]);
 	// Preview is the player for the finished motion: entering starts playback,
 	// leaving pauses it. The editor view stays the manipulation surface.
 	const [tlPlaying, setTlPlaying] = useState(false);
@@ -1177,7 +1172,7 @@ export default function App() {
 		setPromptBlocksReveal, revealPromptBlocks, waypointMode, setWaypointMode, waypoints, setWaypoints,
 		activeWaypointId, setActiveWaypointId, pendingWaypointFrame, setPendingWaypointFrame, promptClips,
 		setPromptClips, editPromptClips, selectedPromptId, setSelectedPromptId, photoPoseState, photoPoseError,
-		setPhotoPoseError, allPoses, selectablePoses, posingIndex, posingChar, posedRig, setPosed, rootStart,
+		setPhotoPoseError, allPoses, selectablePoses, posingIndex, posingChar, posedRig, setPosed, rootStart, commitPosedPose,
 		queueRootWaypointFrame, castMemberOf, addCharacterWaypoint, moveCharacterWaypoint,
 		removeCharacterWaypoint, clearCharacterWaypoints, addFloorWaypoint, moveWaypoint, removeWaypoint,
 		toggleWaypointMode, openStudio, closeStudio, saveCurrentPose, savePose, posePhotoFile, removePose,
@@ -1190,9 +1185,14 @@ export default function App() {
 	// not the one its closure captured.
 	appContext.publishCharacters(characters);
 
-	const [i2vMotionEnabled, setI2vMotionEnabled] = useState(false);
-	const [i2vMotionMode, setI2vMotionMode] = useState("interpolate");
-	const [i2vMotionCameraUnlocked, setI2vMotionCameraUnlocked] = useState(false);
+	const {
+		i2vMotionEnabled,
+		setI2vMotionEnabled,
+		i2vMotionMode,
+		setI2vMotionMode,
+		i2vMotionCameraUnlocked,
+		setI2vMotionCameraUnlocked,
+	} = useI2vCaptureModal();
 
 	useEffect(() => {
 		let cancelled = false;
@@ -1369,7 +1369,8 @@ export default function App() {
 		bodyContact, setBodyContact, IK_CORRECTION_BLEND_FRAMES, autoPhysicsRunning, setAutoPhysicsRunning,
 		physicsPreview, setPhysicsPreview, physicsShow, physicsProgress, physicsOptions, setPhysicsOptions,
 		ikTick, setIkTick, committedIkEdits, setCommittedIkEdits, trailFalloffS, setTrailFalloffS, showTrails,
-		setShowTrails, ikEditTool, setIkEditTool, trailEdit, trailFalloffFrames, focusIkHandle, snapshotIkKeys,
+		setShowTrails, ikEditTool, setIkEditTool, trailEdit, trailTrackFocus, selectTrailTrack, clearTrailTrackFocus, trailFalloffFrames, focusIkHandle, snapshotIkKeys,
+		pendingIkEdit, applyPendingIkEdit, cancelPendingIkEdit,
 		rangePins, rangePinResiduals, rangePinSelection, setRangePinSelection, rangePinPartPick, setRangePinPartPick, rangePinPreview, previewRangePinDraft, applyRangePinDraft, deleteRangePin,
 		setCharacterIkKey, removeCharacterIkKey, clearCharacterIkKeys, bridge, setBridge, bridgeChecking,
 		motionSetupReveal, motionSetupKind, setArdyPrompt, setArdyDuration, ardySeed, preserveStrength,
@@ -1399,14 +1400,24 @@ export default function App() {
 	// Keep the underlying selection model intact, but use this small workflow
 	// state to surface only the tools that belong to the current job.
 	const [workflowMode, setWorkflowMode] = useState("scene");
+	const [poseObjectOpacity, setPoseObjectOpacityState] = useState(readPoseFadeOpacity);
+	const setPoseObjectOpacity = (value) => { setPoseObjectOpacityState(value); writePoseFadeOpacity(value); };
 	// Pose mode IS IK editing (#521): with no rig to solve there is nothing to
 	// pose, so the mode refuses with the reason instead of opening empty.
-	const poseRefusal = ikChains ? null : ko("Load a character to pose it — Pose mode edits its rig with IK", "캐릭터를 불러와야 포즈를 잡을 수 있어요 — 포즈 모드는 IK로 리그를 편집합니다");
+	// A capsule figure has no rig at all, so it gets its own reason rather than
+	// the "load a character" one, which would read as a loading problem.
+	const activeCapabilities = characterCapabilities(activeChar);
+	const poseRefusal = !activeCapabilities.pose ? kindRefusal("pose", isKo) : ikChains ? null : ko("Load a character to pose it — Pose mode edits its rig with IK", "캐릭터를 불러와야 포즈를 잡을 수 있어요 — 포즈 모드는 IK로 리그를 편집합니다");
 	function selectWorkflowMode(next) {
 		if (next === "pose" && poseRefusal) {
 			setToast(poseRefusal);
 			return;
 		}
+		// A storyboard is stills: there is no Motion department to open.
+		if (next === "motion" && storyboardProject) {
+			setToast(ko(STORYBOARD_MOTION_REFUSAL.en, STORYBOARD_MOTION_REFUSAL.ko));
+			return;
+		}
 		setWorkflowMode(next);
 		// Picking a department leaves the chrome-free player. Shot-look is
 		// camera work, so it only yields when the operator leaves Camera.
@@ -1425,7 +1436,8 @@ export default function App() {
 		// Pose lands on the active character's rig: its Rig Control panel holds
 		// the IK tools that W/E/R switch between.
 		else if (next === "pose") setSelectedHierarchyId(`${rowIdForCharIndex(activeCharIndex)}.rig`);
-		else setSelectedHierarchyId("shot");
+		// Sculpt keeps the selection: a selected sculpt is the one it opens on.
+		else if (next !== "sculpt") setSelectedHierarchyId("shot");
 	}
 	// Every door into the mode (tab, 1-4 keys, view.setMode on the bus) moves
 	// IK with it through the motion domain's own entry/exit path...
@@ -1435,7 +1447,7 @@ export default function App() {
 	// ...and whatever else ends IK (a take starting playback, the rig going
 	// away) hands the operator back to Motion instead of a dead Pose mode.
 	useEffect(() => {
-		if (!ikMode && workflowMode === "pose") setWorkflowMode("motion");
+		if (!ikMode && workflowMode === "pose") setWorkflowMode(storyboardProject ? "scene" : "motion");
 	}, [ikMode]);
 
 	const toggleHierarchyHidden = (hierarchyId) => {
@@ -1496,10 +1508,75 @@ export default function App() {
 		matteShrink, setMatteShrink, matteFeather, setMatteFeather, matteMode, setMatteMode, matteStats,
 		setMatteStats, matteBusy, gizmoMode, setGizmoMode, snapEnabled, setSnapEnabled, addSceneObject,
 		importCutout, importCutouts, spawnCutoutAt, persistMeshAsset, importMesh, importMeshes, spawnMeshAt,
-		applyMatte, duplicateSelectedSceneObject, frameSelection, renameSceneObject, sceneObjectWorldMatrix,
+		applyMatte, duplicateSelectedSceneObject, frameSelection, groupObjectUnderNewEmpty, renameRequest, renameSceneObject, sceneObjectWorldMatrix,
 		attachTargetForRow, attachTargetLabel, attachSceneObject,
 	} = objectsDomain;
 
+	const { sculptMode, sculptCamRef, sculptView, sculptReference, setSculptReference, sculptRun, setSculptRun, sculptRunRef, sculptAgentStatus, sculptModels, sculptModelPick, chooseSculptModel, sculptTransport, sculptTap, sculptTarget, setSculptTargetId, requestSculptView, sculptBlueprint, setSculptBlueprint, generateSculptBlueprint, cancelSculptBlueprint } = useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId });
+	async function chooseSculptReference(file) {
+		try {
+			// A new reference makes the old sheet a drawing of something else.
+			cancelSculptBlueprint();
+			setSculptBlueprint((current) => ({ ...current, state: "idle", sheet: null, error: null }));
+			setSculptReference(await objectsDomain.storeSculptReference(file));
+		} catch (error) {
+			setToast(ko(`Could not read that image: ${error.message}`, `이미지를 읽지 못했어요: ${error.message}`));
+		}
+	}
+	function startSculptRun() {
+		if (!sculptReference) return;
+		sculptRunRef.current?.cancel();
+		const run = createSculptRun({
+			bus: { subscribe: (listener) => sculptTap.subscribe(listener, studioBindingRef.current?.bus) },
+			agent: createAgentPort(sculptAgentClient(sculptTransport, () => buildStudioAgentContext())),
+			reference: sculptReference,
+			sculptId: sculptTarget?.id ?? null,
+			score: (args) => appContext.bus.run("sculpt.compare", args, { origin: "ui" }),
+			measure: async (reference) => measureReferenceOutline(await browserSculptImages.decode(reference)),
+			model: sculptModelPick.model || undefined,
+			effort: sculptModelPick.effort || undefined,
+			modelLabel: sculptModelLabel(sculptModels, sculptModelPick.model) || undefined,
+		});
+		sculptRunRef.current = run;
+		let shownId = sculptTarget?.id ?? null;
+		const hadTarget = Boolean(sculptTarget);
+		let reported = false;
+		run.subscribe((state) => {
+			// Before the current-run gate: a run replaced by a new Start still ends (cancelled) once.
+			const telemetry = reported ? null : sculptRunTelemetry(state, { hadTarget });
+			if (telemetry) { reported = true; track("sculpt_run", telemetry); }
+			// A finished run's bus listener outlives it; only the current run speaks.
+			if (sculptRunRef.current !== run) return;
+			setSculptRun(state);
+			if (state.sculptId && state.sculptId !== shownId) {
+				shownId = state.sculptId;
+				setSculptTargetId(state.sculptId);
+				setSelectedHierarchyId(`object:${state.sculptId}`);
+			}
+		});
+		setSculptRun(run.getState());
+		void run.start();
+	}
+	/** Place in scene: on the ground in front of the scene camera, selected,
+	 * back on Stage. The move is one object.update, so one undo. */
+	function placeSculptInScene() {
+		if (!sculptTarget) return;
+		try {
+			selectWorkflowMode("scene");
+			objectsDomain.placeSculptInScene(sculptTarget.id);
+		} catch (error) {
+			if (!(error instanceof StudioProtocolError)) throw error;
+			setToast(error.uiMessage ?? error.message);
+		}
+	}
+
+	// The record whose route the studio shows for the selection: the selected
+	// record itself, or the routed record inside the group it stands for (a car
+	// Empty over its Chassis). Selection stays on the group; only the route's
+	// source moves. With no route anywhere a new stroke lands on the selection.
+	const routeOwner = useMemo(() => routeOwnerFor(sceneObjects, selectedSceneObjectId), [sceneObjects, selectedSceneObjectId]);
+	const pathTarget = routeOwner ?? selectedSceneObject;
+
 	// An undo offer is an offer, not a banner: without a window it sits on the
 	// screen for the rest of the session. Long enough to notice and reach, then
 	// gone — the deletion is still reversible through Undo history afterwards.
@@ -1566,7 +1643,7 @@ export default function App() {
 		get objectsDomain() { return objectsDomain; },
 	}));
 	const {
-		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName, projectDirty,
+		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName, previsMode, projectDirty,
 		setProjectDirty, projectSaveState, setProjectSaveState, projectMenuOpen, setProjectMenuOpen,
 		projectBrowserOpen, setProjectBrowserOpen, projectNameDialog, setProjectNameDialog, projectStartupOpen,
 		setProjectStartupOpen, projectManifest, setProjectManifest, saveBlockedReasons, setSaveBlockedReasons,
@@ -1577,6 +1654,18 @@ export default function App() {
 		renameSceneDocumentFromUi, deleteSceneDocumentFromUi, switchSceneDocument, addSceneDocument,
 		duplicateSceneDocument, renameSceneDocument, deleteSceneDocument,
 	} = scenesDomain;
+	// A sculpt run belongs to Sculpt mode and the scene it started in: leaving
+	// either cancels it, so no paid turn runs unseen and nothing reselects.
+	useEffect(() => {
+		if (!sculptMode) sculptRunRef.current?.cancel();
+	}, [sculptMode]);
+	useEffect(() => () => sculptRunRef.current?.cancel(), [activeSceneId]);
+	// A storyboard project has no Motion department: a project opened while
+	// Motion was up lands on Stage instead.
+	const storyboardProject = scenesDomain.previsMode === "storyboard";
+	useEffect(() => {
+		if (storyboardProject && workflowMode === "motion") setWorkflowMode("scene");
+	}, [storyboardProject, workflowMode]);
 
 	const saveBlockedRef = useRef(startup.saveBlocked);
 	const dirtyRef = useRef(false);
@@ -1638,6 +1727,8 @@ export default function App() {
 	// the gesture is "paste into the studio", not "paste into this box".
 	useEffect(() => {
 		const onPaste = (event) => {
+			// The Agent composer takes a picture pasted anywhere on it first.
+			if (event.defaultPrevented) return;
 			const target = event.target;
 			// Never steal a paste aimed at somewhere text goes.
 			if (target instanceof HTMLElement) {
@@ -1819,12 +1910,20 @@ export default function App() {
 			}
 			// 1-4 pick the workflow mode; pose is refused (with its reason) when
 			// there is no rig to solve. The embedded player has no modes to pick.
-			const modeKey = { Digit1: "scene", Digit2: "pose", Digit3: "camera", Digit4: "motion" }[event.code];
+			const modeKey = { Digit1: "scene", Digit2: "pose", Digit3: "camera", Digit4: "motion", Digit5: "sculpt" }[event.code];
 			if (modeKey && !embedMode && !event.ctrlKey && !event.metaKey && !event.altKey) {
+				// A storyboard has no key 4: it does nothing, not even a refusal.
+				if (modeKey === "motion" && storyboardProject) return;
 				event.preventDefault();
 				if (modeKey !== workflowMode) selectWorkflowMode(modeKey);
 				return;
 			}
+			// Sculpt mode's W/E/R swing the turntable to front, side and back.
+			if (workflowMode === "sculpt" && GIZMO_HOTKEYS[event.code]) {
+				event.preventDefault();
+				requestSculptView({ KeyW: "front", KeyE: "side", KeyR: "back" }[event.code]);
+				return;
+			}
 			// Pose mode's W/E/R are the IK tools, gated like their Rig Control
 			// buttons: the trail tool needs visible trails, the range pin a take.
 			if (workflowMode === "pose" && GIZMO_HOTKEYS[event.code]) {
@@ -1912,7 +2011,7 @@ export default function App() {
 	// selection would point the gizmo at a stale dot.
 	useEffect(() => {
 		setPathPointIndex(null);
-	}, [selectedSceneObjectId]);
+	}, [selectedSceneObjectId, routeOwner?.id]);
 
 	useEffect(() => {
 		if (!inspectorActionsOpen) return undefined;
@@ -1942,6 +2041,13 @@ export default function App() {
 	// Object travel-path drawing: the same Top-View stroke gesture as the rail,
 	// aimed at the selected object instead of the shot camera.
 	const [pathDraw, setPathDraw] = useState(false);
+	// Root-path (waypoint) authoring and Top-View path drawing are motion
+	// tooling; a storyboard never leaves either switched on.
+	useEffect(() => {
+		if (!storyboardProject) return;
+		if (waypointMode) setWaypointMode(false);
+		if (pathDraw) setPathDraw(false);
+	}, [storyboardProject, waypointMode, pathDraw]);
 	const [pathPointIndex, setPathPointIndex] = useState(null);
 	const pathDragTokenRef = useRef(null);
 	const planPathTokenRef = useRef(null);
@@ -1975,6 +2081,16 @@ export default function App() {
 		if (typeof toast.uiMessage === "string" && toast.uiMessage) for (const sink of toastSinkRef.current) sink(toast);
 		showToast(toast.uiMessage);
 	}, []);
+	// The dots on a route are found by double-clicking the line, a gesture
+	// nothing hints at: say it once, the first time a route is selected.
+	const routeHintShownRef = useRef(false);
+	// The route shown may belong to a routed record inside the selected group.
+	const selectedRouteId = routeOwner?.path ? routeOwner.id : null;
+	useEffect(() => {
+		if (!selectedRouteId || routeHintShownRef.current) return;
+		routeHintShownRef.current = true;
+		setToast(ko("Double-click the line to add a dot", "선을 더블클릭하면 점이 추가돼요"));
+	}, [selectedRouteId, setToast]);
 	// The PWA's "a newer studio is waiting" registration, once one arrives.
 	const [pwaUpdate, setPwaUpdate] = useState(null);
 	useEffect(() => {
@@ -1993,58 +2109,7 @@ export default function App() {
 	const takeRecipeRef = useRef(null);
 
 	const [bottomTab, setBottomTab] = useState("timeline");
-	// The imported-pictures region of the Assets shelf. null = the scan has
-	// never resolved (the pane shows skeletons, NEVER the empty message); an
-	// array = the SOURCE ids to show, mattes and cut renders already filtered
-	// out (asset-shelf.js). Scans run only while the shelf is visible, and
-	// re-run when a cutout's lineage changes — not on every transform tick, so
-	// a gizmo drag never hammers IndexedDB.
-	const [shelfImageIds, setShelfImageIds] = useState(null);
-	const [shelfMeshIds, setShelfMeshIds] = useState(null);
-	const [manageAssetStorage, setManageAssetStorage] = useState(false);
-	// A separate scan preserves the source-only placement shelf while the
-	// manager exposes every unreachable stored record, including matte and cut
-	// derivatives orphaned with a deleted card.
-	const [unusedAssetIds, setUnusedAssetIds] = useState(null);
-	const [usedAssetIds, setUsedAssetIds] = useState(null);
-	const [usageCounts, setUsageCounts] = useState(new Map());
-	const assetShelfScanTokenRef = useRef(0);
-	const legacyDerivedIdsRef = useRef(new Set());
-	// This is deliberately session-only. Each entry is a complete IndexedDB
-	// record, so Undo can put it back byte-for-byte until the page is reloaded.
-	const [assetTrash, setAssetTrash] = useState([]);
-	// Same rule as the object deletion offer: the toast is a window, not a
-	// banner. Only the OFFER expires — the trashed record itself is the restore
-	// data, so it is deliberately kept for the session and never timed out.
-	const [assetUndoOffered, setAssetUndoOffered] = useState(false);
-	useEffect(() => {
-		if (!assetUndoOffered) return undefined;
-		const timer = setTimeout(() => setAssetUndoOffered(false), ASSET_DELETE_UNDO_MS);
-		return () => clearTimeout(timer);
-	}, [assetUndoOffered]);
-	const [deletingAssetId, setDeletingAssetId] = useState(null);
-	const cutoutLineage = useMemo(
-		() => JSON.stringify(sceneObjects.flatMap((object) => (object.renderer === CUTOUT_KIND ? [[object.assetId, object.sourceAssetId, object.matteAssetId]] : []))),
-		[sceneObjects],
-	);
-	const meshLineage = useMemo(
-		() => JSON.stringify(sceneObjects.flatMap((object) => (object.renderer === MESH_KIND ? [object.assetId] : []))),
-		[sceneObjects],
-	);
-	const projectCutoutLineage = useMemo(() => {
-		const allScenes = scenes.map((scene) => (scene.id === activeSceneId ? { ...scene, objects: sceneObjects } : scene));
-		return JSON.stringify(
-			allScenes.flatMap((scene) =>
-				(Array.isArray(scene.objects) ? scene.objects : []).flatMap((object) =>
-					object.renderer === CUTOUT_KIND ? [[object.assetId, object.sourceAssetId, object.matteAssetId]] : [],
-				),
-			),
-		);
-	}, [scenes, activeSceneId, sceneObjects]);
-	const projectAssetGraphSignature = useMemo(() => {
-		const allScenes = scenes.map((scene) => (scene.id === activeSceneId ? { ...scene, objects: sceneObjects } : scene));
-		return assetGraphSignature(allScenes);
-	}, [scenes, activeSceneId, sceneObjects]);
+	const { shelfImageIds, setShelfImageIds, shelfMeshIds, setShelfMeshIds, manageAssetStorage, setManageAssetStorage, unusedAssetIds, setUnusedAssetIds, usedAssetIds, setUsedAssetIds, usageCounts, setUsageCounts, assetShelfScanTokenRef, legacyDerivedIdsRef, assetTrash, setAssetTrash, assetUndoOffered, setAssetUndoOffered, deletingAssetId, setDeletingAssetId, cutoutLineage, meshLineage, projectCutoutLineage, projectAssetGraphSignature } = useAssetShelf({ scenes, activeSceneId, sceneObjects });
 	useEffect(() => {
 		const { scenes: latestScenes, activeSceneId: latestActiveSceneId, sceneObjects: latestObjects } = projectStateRef.current;
 		const allScenes = latestScenes.map((scene) => (scene.id === latestActiveSceneId ? { ...scene, objects: latestObjects } : scene));
@@ -2217,15 +2282,21 @@ export default function App() {
 	// the export overwrites it per captured frame and restores nothing, which
 	// is correct — the next render puts it back.
 	propFrameRef.current = tlFrame;
-	const animatedSceneObjects = useMemo(() => {
-		if (!sceneObjects.some((object) => object.path)) return sceneObjects;
-		const take = { frameCount: tlFrameCount, fps: tlFps };
-		return sceneObjects.map((object) => {
-			const at = objectTransformAt(object, tlFrame, take);
-			if (!at) return object;
-			return { ...object, x: at.x, y: at.y, z: at.z, rot: at.rot ?? object.rot };
-		});
-	}, [sceneObjects, tlFrame, tlFrameCount, tlFps]);
+	// Routed records and everything grouped under them (object-travel.js).
+	const animatedSceneObjects = useMemo(
+		() => sceneObjectsAt(sceneObjects, tlFrame, { frameCount: tlFrameCount, fps: tlFps }),
+		[sceneObjects, tlFrame, tlFrameCount, tlFps],
+	);
+
+	// The selection as it is DRAWN at this frame, for the transform gizmo to sit
+	// on: a routed record, the group under one, and the Empty that rides its
+	// routed descendant all stand away from their authored numbers while the
+	// playhead is off frame 0. Drags still read the authored records (the gizmo
+	// is handed those separately), so they stay delta-based on authored numbers.
+	const gizmoSceneObject = useMemo(
+		() => (selectedSceneObject ? animatedSceneObjects.find((object) => object.id === selectedSceneObject.id) ?? selectedSceneObject : null),
+		[selectedSceneObject, animatedSceneObjects],
+	);
 
 	// Auto color: Blender's viewport "Random" mode. A DISPLAY-ONLY marker rides
 	// each non-cutout object into the renderers; the authored `color`, the scene
@@ -2257,6 +2328,14 @@ export default function App() {
 	// r3f frame loop — so it asks the set for one placement pass itself, right
 	// after it has written that frame's bones.
 	const propSyncRef = useRef(null);
+	// Characters grouped under a scene object ride it inside an ObjectCarrier.
+	// The carriers read the AUTHORED records by id, and register a placement
+	// pass the recorder runs before the props' (a prop carried on a riding
+	// character's hand needs the carrier placed first).
+	const carrierRegistryRef = useRef(new Set());
+	const sceneObjectLookupRef = useRef(null);
+	sceneObjectLookupRef.current = useMemo(() => new Map(sceneObjects.map((object) => [object.id, object])), [sceneObjects]);
+	const syncCarriers = () => { for (const place of carrierRegistryRef.current) place(); };
 	// Where a prop actually IS, read off its live group: the one authority on
 	// the transform currently on screen, and so the only honest starting point
 	// for a no-jump conversion.
@@ -2265,9 +2344,30 @@ export default function App() {
 	/**
 	 * Hierarchy row drag policy (the panel holds none). An object row dropped on
 	 * another object GROUPS; on a character or one of its bone rows it ATTACHES;
-	 * on Props it comes back to the world. Anything else is not a drop.
+	 * on Props it comes back to the world. A character row dropped on an object
+	 * row is GROUPED under it and rides its travel; dropped on the scene root it
+	 * stands in the world again. Anything else is not a drop.
 	 */
-	const hierarchyReparent = { canDrop: objectsDomain.canReparentSceneObject, onDrop: objectsDomain.reparentSceneObject };
+	function characterGroupMove(sourceRowId, targetRowId) {
+		const characterId = charIdFromHierarchyId(sourceRowId);
+		const entry = characterId ? characters.find((item) => item.id === characterId) : null;
+		if (!entry) return null;
+		if (targetRowId === "shot") return (entry.parent ?? null) !== null ? { characterId, parent: null } : null;
+		const objectId = sceneObjectIdFromHierarchy(String(targetRowId ?? ""));
+		const object = objectId ? sceneObjects.find((item) => item.id === objectId) : null;
+		if (!object || object.attach || entry.parent === objectId) return null;
+		return { characterId, parent: objectId };
+	}
+	const hierarchyReparent = {
+		canDrop: (source, target) => (charIdFromHierarchyId(source)
+			? characterGroupMove(source, target) !== null
+			: objectsDomain.canReparentSceneObject(source, target)),
+		onDrop: (source, target) => {
+			if (!charIdFromHierarchyId(source)) return objectsDomain.reparentSceneObject(source, target);
+			const move = characterGroupMove(source, target);
+			if (move) runStudioAction("character.update", { characterId: move.characterId, patch: { parent: move.parent } });
+		},
+	};
 
 	useEffect(() => {
 		setCraneSelectedIndex(null);
@@ -2453,10 +2553,20 @@ export default function App() {
 	appContext.publishScenes(scenes);
 	activeSceneIdRef.current = activeSceneId;
 	shotDocumentRef.current = createShotAuthoringDocument({ shots, waypoints, frameCount: tlFrameCount });
+	// The motion layers: their IK edits (Pose mode, IK keys, range pins) ride
+	// into the saved stage below with each character, and a change to them is
+	// a reason to autosave.
+	const motionLayers = appContext.storeDomain("motion")?.read() ?? null;
+	const ikEditsOf = (id) => {
+		const row = motionLayers?.find((layer) => layer.id === id);
+		if (!row || (!row.ikKeys?.length && !row.ikPins?.length)) return null;
+		return { keys: row.ikKeys, pins: row.ikPins ?? [], pinResiduals: row.ikPinResiduals ?? [] };
+	};
+	// sessionMotion is stripped: generated clips are session-only and far too
+	// heavy for the stage envelope; paths, prompt blocks and IK edits persist.
+	const stageCharacters = characters.map(({ sessionMotion, ...entry }) => ({ ...entry, ikEdits: ikEditsOf(entry.id) }));
 	actorStageRef.current = {
-		// sessionMotion is stripped: generated clips are session-only and far
-		// too heavy for the stage envelope; paths and prompt blocks persist.
-		characters: characters.map(({ sessionMotion, ...entry }) => entry),
+		characters: stageCharacters,
 		hasCharSheet,
 		environmentImage,
 		shotAspect: shotAspectKey,
@@ -2470,8 +2580,7 @@ export default function App() {
 		hasEnvSheet,
 	};
 
-	const [firstSuccessGuideOpen, setFirstSuccessGuideOpen] = useState(false);
-	const [useCaseAskOpen, setUseCaseAskOpen] = useState(false);
+	const { firstSuccessGuideOpen, setFirstSuccessGuideOpen, useCaseAskOpen, setUseCaseAskOpen } = useFirstSuccessPrompt();
 
 	// Dismissal mirrors the inspector-actions menu: only listen while open,
 	// ignore presses inside the wrap (the trigger's own click keeps toggling),
@@ -2804,6 +2913,8 @@ export default function App() {
 		activeShotId: activeShot?.id ?? null,
 		captureCurrentFraming,
 		captureFramingPng,
+		// The Top View pull (verify_result visual "plan", capture_plan_png).
+		capturePlanPng,
 		captureShotMeta,
 		// The identity / environment reference pictures a capture carries (#167).
 		captureShotReferences,
@@ -2839,6 +2950,7 @@ export default function App() {
 					aspectRatio: live.filmback.aspectRatio,
 				},
 				stage: live.stage,
+				previsMode: scenesDomain.metadata().previsMode,
 				timeline: live.timeline,
 				activeCharacterId: live.activeCharacterId,
 				characters: castDomain.read(),
@@ -2874,10 +2986,7 @@ export default function App() {
 		// not capture_frame's 640x360 preview, which stays exactly as it is.
 			capture_framing_png: (args = {}) => {
 				const live = appContext.live.state;
-				const requested = args?.output;
-				const output = Number.isFinite(requested?.width) && Number.isFinite(requested?.height)
-					? { width: Math.round(requested.width), height: Math.round(requested.height) }
-					: SHOT_ASPECT_PRESETS[live.stage.shotAspect] ?? SHOT_ASPECT_PRESETS["16:9"];
+				const output = requestedCaptureOutput(args) ?? SHOT_ASPECT_PRESETS[live.stage.shotAspect] ?? SHOT_ASPECT_PRESETS["16:9"];
 				const dataUrl = live.captureFramingPng(live.captureCurrentFraming(), output);
 				if (!dataUrl) throw new Error("The shot renderer is not ready");
 				return {
@@ -2894,6 +3003,9 @@ export default function App() {
 					references: live.captureShotReferences(),
 				};
 			},
+			// The Top View as the agent's plan picture: a 2D diagram of the cast,
+			// footprints and every shot camera drawn from state (src/plan-diagram.js).
+			capture_plan_png: (args = {}) => appContext.live.state.capturePlanPng(requestedCaptureOutput(args) ?? undefined),
 	};
 
 	useEffect(() => {
@@ -2904,7 +3016,8 @@ export default function App() {
 		const timer = setTimeout(() => {
 			if (!liveControlRef.current) {
 				liveControlRef.current = createLiveControl({
-					handlers: { ...liveQueries, ...studioBindingRef.current.handlers },
+					// Tapped so a sculpt run hears the agent's object.sculpt / sculpt.compare.
+					handlers: sculptTap.wrap({ ...liveQueries, ...studioBindingRef.current.handlers }),
 					workspaceId: liveWorkspaceIdRef.current,
 					meta: {
 						project: projectName ?? "Untitled",
@@ -2965,7 +3078,7 @@ export default function App() {
 		dirtyRef.current = true;
 		const timer = setTimeout(flushScenes, 400);
 		return () => clearTimeout(timer);
-	}, [sceneObjects, shots, waypoints, tlFrameCount, charA, charB, showB, poseA, poseB, hasCharSheet, environmentImage, environment, style, hasEnvSheet, subject, subject2, shotAspectKey, sensorId, keyLight, scenes, activeSceneId]);
+	}, [sceneObjects, shots, waypoints, tlFrameCount, charA, charB, showB, poseA, poseB, hasCharSheet, environmentImage, environment, style, hasEnvSheet, subject, subject2, shotAspectKey, sensorId, keyLight, scenes, activeSceneId, motionLayers]);
 	useEffect(() => {
 		const onPageHide = () => flushScenes();
 		const onVisibility = () => {
@@ -3028,25 +3141,33 @@ export default function App() {
 	// props did not change must not re-render its subtree.
 	const characterViews = useMemo(() => characters.flatMap((entry, index) => {
 		if (entry.hidden) return [];
+		const pickId = index === 0 ? "A" : index === 1 ? "B" : entry.id;
 		// Each cast member is driven by ITS OWN clip: the active one reads
 		// the editing buffer, the others their stored session motion.
 		const clip = entry.id === activeChar.id ? motion : entry.sessionMotion;
+		const placement = placementAt(entry, tlFrame, {
+			shotAt: frame => shotAtFrame(shots, frame),
+			takeRoot: clip ? sampleAt({ frameCount: clip.frames, motion: clip }, null, tlFrame).subject : null,
+		});
 		return [{
 			id: entry.id,
-			url: characterModelUrl(entry.model),
-			position: [entry.x, entry.y ?? 0, entry.z],
-			rot: entry.rot,
+			model: entry.model,
+			...(isProxyFigure(entry) ? {} : { url: characterModelUrl(entry.model) }),
+			position: [placement.x, entry.y ?? 0, placement.z],
+			rot: placement.rot,
 			tint: entry.tint ?? defaultCharacterTint(entry, index),
 			partColoursEnabled,
 			partColoursMode,
-			pose: clip ? null : (entry.pose ?? DEFAULT_POSE),
+			pose: clip ? null : (placement.pose ?? DEFAULT_POSE),
+			posture: placement.posture,
 			// The stature the entry's take was extracted at. It rides with the
 			// clip, never separately — see Character for why.
 			scale: entry.scale ?? 1,
-			onRig: reportRig(entry.id),
-			pickId: index === 0 ? "A" : index === 1 ? "B" : entry.id,
+			...(isProxyFigure(entry) ? {} : { onRig: reportRig(entry.id) }),
+			pickId,
+			parent: entry.parent ?? null,
 		}];
-	}), [characters, activeChar.id, motion, partColoursEnabled, partColoursMode]);
+	}), [characters, activeChar.id, motion, shots, tlFrame, partColoursEnabled, partColoursMode]);
 	// Where the selection gizmo stands: same driving rules as the render,
 	// for the active (selected) cast member only. Gated on the HIERARCHY
 	// selection, not the sticky active layer — the layer stays on the last
@@ -3057,8 +3178,10 @@ export default function App() {
 		if (!charIdFromHierarchyId(selectedHierarchyId)) return null;
 		const entry = characters.find((item) => item.id === activeChar.id);
 		if (!entry || entry.hidden) return null;
-		return { position: [entry.x, entry.y ?? 0, entry.z] };
-	}, [characters, activeChar.id, motion, selectedHierarchyId]);
+		const hasTake = activeChar.id === activeCharacterId ? Boolean(motion) : Boolean(activeChar.sessionMotion);
+		const placement = hasTake ? entry : placementAt(entry, tlFrame, { shotAt: frame => shotAtFrame(shots, frame) });
+		return { position: [placement.x, entry.y ?? 0, placement.z], rot: placement.rot };
+	}, [characters, activeChar.id, motion, shots, tlFrame, selectedHierarchyId]);
 	// The cast rides the SAME gizmo as scene objects — one movement grammar
 	// for everything on stage. The proxy hands ObjectGizmo the object shape
 	// it expects; `height` puts the pivot at the hips like a prop's centre.
@@ -3072,7 +3195,7 @@ export default function App() {
 			z: gizmoView.position[2],
 			height: 1.15,
 			footprint: { width: 0.6, depth: 0.6 },
-			rotY: entry?.rot ?? 0,
+			rotY: gizmoView.rot ?? entry?.rot ?? 0,
 			scaleX: entry?.scale ?? 1,
 			scaleY: entry?.scale ?? 1,
 			scaleZ: entry?.scale ?? 1,
@@ -3235,7 +3358,7 @@ export default function App() {
 			ikStates: new Map([...ikStatesRef.current].map(([id, state]) => [id, copyIk(state)])),
 			rigStates: Object.values(rigs).filter(Boolean).map(snapshotExportRig),
 		};
-		return Object.freeze({ kind, format: kind === "frame" ? "png" : kind === "keyframe_pack" ? "zip" : "mp4",
+		return Object.freeze({ kind, format: kind === "frame" || kind === "contact_sheet" ? "png" : kind === "keyframe_pack" || kind === "panel_pack" ? "zip" : "mp4",
 			context, run, external, download, handedOff: new Set() });
 	}
 
@@ -3335,16 +3458,23 @@ export default function App() {
 		propFrameRef.current = frame;
 		const context = recRef.current?.request.context;
 		for (const entry of context?.characters ?? characters) {
+			if (isProxyFigure(entry)) continue;
 			const activeId = context?.activeId ?? activeChar.id;
 			const clip = entry.id === activeId ? (context ? context.motion : motion) : entry.sessionMotion;
 			const state = context
 				? (entry.id === activeId ? context.ikState : context.ikStates.get(entry.id))
 				: (entry.id === activeChar.id ? ikStateRef.current : ikStatesRef.current.get(entry.id));
-			poseMemberAtFrame(rigs[entry.id], clip, state, frame, IK_CORRECTION_BLEND_FRAMES);
+			const placement = placementAt(entry, frame, {
+				shotAt: at => shotAtFrame(context?.shots ?? shots, at),
+				takeRoot: clip ? sampleAt({ frameCount: clip.frames, motion: clip }, null, frame).subject : null,
+			});
+			poseMemberAtFrame(rigs[entry.id], clip, state, frame, IK_CORRECTION_BLEND_FRAMES, placement.pose ?? null);
 		}
 		// The bones for this frame are now written, so a carried prop can take
 		// its place on them. gl.render() never runs the r3f frame loop, so this
 		// pass is the recorder's stand-in for the useFrame the preview gets.
+		// Riding characters move with their object first, then the props.
+		syncCarriers();
 		propSyncRef.current?.();
 		const sampled = sampleAt(context?.playbackScene ?? playbackScene, shotAtFrame(context?.shots ?? shots, frame), frame);
 		const framing = sampled.camera ?? context?.framing;
@@ -3384,18 +3514,43 @@ export default function App() {
 		const cameraSnapshot = { position: cam.position.clone(), quaternion: cam.quaternion.clone(),
 			rotationOrder: cam.rotation.order, fov: cam.fov, yaw: look.current.yaw, pitch: look.current.pitch };
 		const rigSnapshots = Object.values(rigs).filter(Boolean).map(snapshotExportRig);
+		const proxySnapshots = [];
+		const context = recRef.current?.request.context;
+		const cast = context?.characters ?? characters;
+		const scene = (recRef.current?.capture ?? captureRef.current)?.scene;
+		const pickIdByCharacter = new Map(characterViews.map(view => [view.id, view.pickId]));
+		if (typeof scene?.traverse === "function") scene.traverse(node => {
+			const index = cast.findIndex(entry => isProxyFigure(entry) && node.userData.characterPick === pickIdByCharacter.get(entry.id));
+			if (index < 0) return;
+			proxySnapshots.push({ node, entry: cast[index], position: node.position.clone(), quaternion: node.quaternion.clone() });
+		});
 		const propFrame = propFrameRef.current;
 		try {
 			// Character stature lives on the rig and placement/yaw on its parent,
 			// not in playback bones. Retry temporarily restores both, plus the
 			// original held pose, then puts the CURRENT editor transforms back.
 			for (const snapshot of recRef.current?.request.context?.rigStates ?? []) restoreExportRig(snapshot);
+			for (const { node, entry } of proxySnapshots) {
+				const clip = entry.id === (context?.activeId ?? activeChar.id) ? (context ? context.motion : motion) : entry.sessionMotion;
+				const placement = placementAt(entry, frame, {
+					shotAt: at => shotAtFrame(context?.shots ?? shots, at),
+					takeRoot: clip ? sampleAt({ frameCount: clip.frames, motion: clip }, null, frame).subject : null,
+				});
+				node.position.set(placement.x, entry.y ?? 0, placement.z);
+				node.rotation.y = proxyYaw(placement.rot, placement.posture);
+				node.updateMatrixWorld(true);
+			}
 			const plate = applyExportFrame(frame);
 			return render ? render() : plate;
 		} catch (error) {
 			throw Object.assign(new Error(error?.message || String(error), { cause: error }), { exportFailureCode: exportFailureCode(error, "render_failed") });
 		} finally {
 			for (const snapshot of rigSnapshots) restoreExportRig(snapshot);
+			for (const { node, position, quaternion } of proxySnapshots) {
+				node.position.copy(position);
+				node.quaternion.copy(quaternion);
+				node.updateMatrixWorld(true);
+			}
 			cam.position.copy(cameraSnapshot.position);
 			cam.rotation.order = cameraSnapshot.rotationOrder;
 			cam.quaternion.copy(cameraSnapshot.quaternion);
@@ -3404,6 +3559,7 @@ export default function App() {
 			look.current.yaw = cameraSnapshot.yaw;
 			look.current.pitch = cameraSnapshot.pitch;
 			propFrameRef.current = propFrame;
+			syncCarriers();
 			propSyncRef.current?.();
 		}
 	}
@@ -3762,6 +3918,13 @@ export default function App() {
 		return output;
 	}
 
+	// One storyboard panel as a picture: the shot's first frame through the
+	// offscreen capture rig, as a PNG data URL (null while the renderer has no
+	// frame). The contact sheet and the Board dock tab share it.
+	function capturePanelThumbnail(entry) {
+		return captureShotFramePng(entry.startFrame);
+	}
+
 	/** Contact sheet of the whole cut: one thumbnail and prompt per shot. */
 	async function exportStoryboard() {
 		try {
@@ -3769,7 +3932,7 @@ export default function App() {
 			setToast(ko("Composing the storyboard…", "스토리보드 구성 중…"));
 			const cells = [];
 			for (const [index, entry] of shots.entries()) {
-				const dataUrl = captureShotFramePng(entry.startFrame);
+				const dataUrl = capturePanelThumbnail(entry);
 				const meta = packMetaForShot(entry, index);
 				cells.push({
 					title: storyboardLine(`${index + 1}. ${entry.name}`),
@@ -3789,18 +3952,7 @@ export default function App() {
 				// the fit, so the frame is scaled to height) and a caption block wide
 				// enough for the 90 characters the composer draws at this size.
 				cell: { width: 480, height: 300 },
-				createCanvas: (width, height) => {
-					const element = document.createElement("canvas");
-					element.width = width;
-					element.height = height;
-					const ctx = element.getContext("2d");
-					// The sheet is a deliverable, so it uses the studio's own type
-					// stack rather than the canvas default (10px sans-serif).
-					ctx.font = STORYBOARD_FONT;
-					ctx.textAlign = "left";
-					ctx.textBaseline = "top";
-					return element;
-				},
+				createCanvas: storyboardCanvas,
 			});
 			saveDownload(canvas.toDataURL("image/png"), "cozyclay-storyboard.png");
 			setToast(isKo ? `스토리보드 저장됨 · ${cells.length}샷` : `Storyboard saved · ${cells.length} shots`);
@@ -3810,6 +3962,162 @@ export default function App() {
 		}
 	}
 
+	function storyboardCanvas(width, height) {
+		const element = document.createElement("canvas");
+		element.width = width;
+		element.height = height;
+		const ctx = element.getContext("2d");
+		// The sheet is a deliverable, so it uses the studio's own type
+		// stack rather than the canvas default (10px sans-serif).
+		ctx.font = STORYBOARD_FONT;
+		ctx.textAlign = "left";
+		ctx.textBaseline = "top";
+		return element;
+	}
+
+	/* ===================== storyboard exports (#644) =======================
+	 * A storyboard project's panels are its stills, in still order. Each
+	 * export runs as one export job (status panel, cancel, retry, analytics
+	 * export_kind contact_sheet | panel_pack | animatic) and draws its frames
+	 * through withExportFrame, so per-panel cast overrides and proxy paths
+	 * land exactly as the preview shows them.
+	 */
+
+	function storyboardPanels(list = shots) {
+		return list.filter((entry) => entry.kind === "still").sort((a, b) => a.startFrame - b.startFrame);
+	}
+
+	const noPanelsMessage = () => ko("Add a panel first — storyboard exports describe panels", "패널을 먼저 추가하세요 — 스토리보드 내보내기는 패널을 담습니다");
+
+	// The panel's stylized picture as PNG bytes, or null when it has none (or
+	// its asset is gone from this browser).
+	async function panelStylizedPng(entry) {
+		if (!entry.stylizedAssetId) return null;
+		const record = await assetRecord(entry.stylizedAssetId);
+		if (!record) {
+			console.warn(`[cozyclay] stylized panel ${entry.stylizedAssetId} is missing; exporting the greybox only`);
+			return null;
+		}
+		const bytes = new Uint8Array(record.bytes);
+		if (record.type === "image/png") return bytes;
+		const bitmap = await createImageBitmap(new Blob([bytes], { type: record.type }));
+		try {
+			const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+			canvas.getContext("2d").drawImage(bitmap, 0, 0);
+			return new Uint8Array(await (await canvas.convertToBlob({ type: "image/png" })).arrayBuffer());
+		} finally {
+			bitmap.close();
+		}
+	}
+
+	async function loadPngBytes(bytes) {
+		const url = URL.createObjectURL(new Blob([bytes], { type: "image/png" }));
+		try { return await loadImage(url); }
+		finally { URL.revokeObjectURL(url); }
+	}
+
+	const panelFolder = (order) => `panel-${String(order + 1).padStart(2, "0")}`;
+
+	/** Contact sheet of the storyboard: the stylized picture with the greybox
+	 * inset when a panel has one, and the panel caption under it. */
+	async function exportContactSheet() {
+		if (recRef.current) return null;
+		if (!storyboardPanels().length) { setToast(noPanelsMessage()); return null; }
+		return executeExportRequest(exportRequest("contact_sheet", async (job) => {
+			const all = job.request.context.shots;
+			const panels = storyboardPanels(all);
+			updateExportStatus(job, "preparing", { stage: "frames", cancellable: true });
+			const cells = [];
+			for (const [order, entry] of panels.entries()) {
+				const dataUrl = captureShotFramePng(entry.startFrame);
+				if (!dataUrl) throw Object.assign(new Error(ko("The shot renderer is not ready", "샷 렌더러가 아직 준비되지 않았어요")), { exportFailureCode: "render_failed" });
+				const stylized = await panelStylizedPng(entry);
+				const meta = packMetaForShot(entry, all.indexOf(entry));
+				cells.push({
+					title: storyboardLine(`${order + 1}. ${entry.name}`),
+					durationSeconds: Number(((entry.endFrame - entry.startFrame + 1) / tlFps).toFixed(2)),
+					prompt: storyboardCaption(buildShotPrompt(meta, { target: "image" })),
+					caption: storyboardLine((entry.caption ?? "").trim()),
+					image: await loadImage(dataUrl),
+					stylized: stylized ? await loadPngBytes(stylized) : null,
+				});
+				await exportBoundary(job);
+			}
+			const canvas = composeStoryboard({ shots: cells, columns: Math.min(3, cells.length), cell: { width: 480, height: 300 }, createCanvas: storyboardCanvas });
+			job.controller.signal.throwIfAborted();
+			saveDownload(canvas.toDataURL("image/png"), "cozyclay-storyboard.png");
+			setToast(isKo ? `콘택트 시트 다운로드 요청 · 패널 ${cells.length}개` : `Download requested: contact sheet · ${cells.length} panels`);
+			return { fileName: "cozyclay-storyboard.png", panelCount: cells.length };
+		}));
+	}
+
+	// One panel's pack: the greybox as first.png, the stylized picture when
+	// there is one, the still's camera and hold, and the image prompt plus caption.
+	async function panelPackArgs(entry, order, all) {
+		const firstUrl = captureShotFramePng(entry.startFrame);
+		if (!firstUrl) throw Object.assign(new Error(ko("The shot renderer is not ready", "샷 렌더러가 아직 준비되지 않았어요")), { exportFailureCode: "render_failed" });
+		const meta = packMetaForShot(entry, all.indexOf(entry));
+		const caption = (entry.caption ?? "").trim();
+		return {
+			shot: { title: entry.name, index: order + 1, startFrame: entry.startFrame, endFrame: entry.endFrame, kind: "still" },
+			fps: tlFps,
+			firstFramePng: dataUrlToBytes(firstUrl),
+			lastFramePng: null,
+			clip: null,
+			stylizedPng: await panelStylizedPng(entry),
+			camera: { ...meta, framing: { start: shotFramingAtFrame(entry, entry.startFrame) } },
+			prompt: buildShotPrompt(meta, { target: "image" }) + (caption ? `\nCAPTION: ${caption}` : ""),
+			folder: panelFolder(order),
+		};
+	}
+
+	/** Panel pack (zip) for one panel — the given one, else the selected one,
+	 * else the one under the playhead, else the first — or, with `every`, one
+	 * zip holding a panel-NN/ folder per panel. */
+	async function exportPanelPacks(every = false, shotId = null) {
+		if (recRef.current) return null;
+		const panels = storyboardPanels();
+		if (!panels.length) { setToast(noPanelsMessage()); return null; }
+		const target = shotId ? panels.find((entry) => entry.id === shotId)
+			: panels.find((entry) => entry.id === activeShot?.id)
+			?? panels.find((entry) => tlFrame >= entry.startFrame && tlFrame <= entry.endFrame) ?? panels[0];
+		if (!target) return null;
+		return executeExportRequest(exportRequest("panel_pack", async (job) => {
+			const all = job.request.context.shots;
+			const contextPanels = storyboardPanels(all);
+			const targets = every ? contextPanels : contextPanels.filter((entry) => entry.id === target.id);
+			updateExportStatus(job, "preparing", { stage: "frames", cancellable: true });
+			const packs = [];
+			for (const [step, entry] of targets.entries()) {
+				job.label = ko(`Panel ${step + 1} of ${targets.length}`, `패널 ${step + 1} / ${targets.length}`);
+				packs.push(await panelPackArgs(entry, contextPanels.indexOf(entry), all));
+				await exportBoundary(job);
+			}
+			updateExportStatus(job, "finalizing", { stage: "archive", cancellable: true });
+			await exportBoundary(job);
+			const entries = packs.flatMap((args) => keyframePackEntries(args));
+			const bytes = every ? buildZip(entries) : buildKeyframePack(packs[0]);
+			const name = every ? "cozyclay-panels.zip" : `cozyclay-${packs[0].folder}-${slugifyTitle(target.name)}.zip`;
+			await exportBoundary(job);
+			const url = URL.createObjectURL(new Blob([bytes], { type: "application/zip" }));
+			try { saveDownload(url, name); }
+			finally { setTimeout(() => URL.revokeObjectURL(url), 10_000); }
+			setToast(isKo ? `${name} 다운로드 요청 · 파일 ${entries.length}개` : `Download requested: ${name} · ${entries.length} files`);
+			return { fileName: name, entries: entries.map((entry) => entry.name) };
+		}));
+	}
+
+	/** Animatic (mp4): every panel held for its hold, from frame 0 to the last
+	 * still's end, at the production fps. */
+	async function exportAnimatic() {
+		if (recRef.current) return null;
+		const panels = storyboardPanels();
+		if (!panels.length) { setToast(noPanelsMessage()); return null; }
+		const endFrame = panels.at(-1).endFrame;
+		return executeExportRequest(exportRequest("animatic",
+			(job) => runShotExport({ startFrame: 0, endFrame, fileName: "cozyclay-animatic.mp4" }, job)));
+	}
+
 	function captureCurrentFraming() {
 		const cam = shotCamRef.current;
 		const pos = cam ? cam.position : cameraPos;
@@ -3910,11 +4218,11 @@ export default function App() {
 		generate: (kind) => void generateI2vMotion(kind),
 		enableShaded: () => runStudioAction("view.setPartColours", { mode: "shaded" }),
 	};
-	const viewLooksActive = gridView || autoColor || partColoursEnabled;
+	const viewLooksActive = gridView || autoColor || partColoursEnabled || guideMode !== "off";
 	const rigSelection = parseRigNodeId(selectedHierarchyId);
 	const isRigSelection = rigSelection !== null;
 	const inspectorHasContent = isSceneSelection || isCameraSelection || isCharacterSelection || isRigSelection
-		|| selectedHierarchyId === "environment" || selectedHierarchyId === "props" || selectedHierarchyId === "light" || Boolean(selectedSceneObject);
+		|| selectedHierarchyId === "environment" || selectedHierarchyId === "props" || selectedHierarchyId === "light" || Boolean(selectedSceneObject) || sculptMode;
 
 	useEffect(() => () => {
 		if (multiModelObjectUrlRef.current) URL.revokeObjectURL(multiModelObjectUrlRef.current);
@@ -4005,7 +4313,7 @@ export default function App() {
 	useEffect(() => {
 		// The ACTIVE member's clip only: its own corrections are applied by the
 		// evaluate effect below, after its editing state settles.
-		poseMemberAtFrame(rigs[activeChar.id], motion, null, tlFrame);
+		if (activeCapabilities.rig) poseMemberAtFrame(rigs[activeChar.id], motion, null, tlFrame);
 		poseOtherCastMembers(tlFrame);
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [characters, activeChar.id, motion, rigs, tlFrame, ikTick]);
@@ -4022,7 +4330,7 @@ export default function App() {
 	// character's rig (re)loads. A rig missing any bone resolves to null and
 	// IK mode stays unavailable.
 	useEffect(() => {
-		const resolved = resolveIkRig(activeRig);
+		const resolved = activeCapabilities.ik ? resolveIkRig(activeRig) : null;
 		const chains = resolved ? resolved.chains : null;
 		setIkChains(chains);
 		setIkFkJoints(resolved ? resolved.fkJoints : null);
@@ -4032,7 +4340,7 @@ export default function App() {
 		ikStateRef.current.fkJoints = resolved ? resolved.fkJoints : null;
 		ikStateRef.current.rig = chains ? activeRig : null;
 		if (!chains) leaveIkMode();
-	}, [activeRig]);
+	}, [activeRig, activeCapabilities.ik]);
 
 	// Whether the collision capsules can be built for this rig at all. Bone
 	// lookups only — no mesh measurement — so it is cheap enough to hang off
@@ -4041,7 +4349,7 @@ export default function App() {
 	// a SEPARATE question from `ikChains`: the two collision buttons disable
 	// on it rather than offering a click whose only possible answer is "not
 	// supported".
-	const collisionCleanupSupported = useMemo(() => supportsCollisionCleanup(activeRig), [activeRig]);
+	const collisionCleanupSupported = useMemo(() => activeCapabilities.physics && supportsCollisionCleanup(activeRig), [activeRig, activeCapabilities.physics]);
 
 	//
 
@@ -4078,11 +4386,12 @@ export default function App() {
 		// Preview changes may re-run this effect without a playhead change.
 		// Always re-establish the motion base before adding a correction.
 		if (motion) poseMemberAtFrame(activeRig, motion, null, tlFrame);
-		const layer = physicsPreview && physicsShow ? physicsPreview.candidate : ikStateRef.current;
+		const layer = pendingIkEdit?.characterId === activeChar.id ? pendingIkEdit.candidate
+			: physicsPreview && physicsShow ? physicsPreview.candidate : ikStateRef.current;
 		if (ikMode || layer.keys.size > 0) {
 			ikEvaluate(ikChains, layer, tlFrame, ikFkJoints, motion ? IK_CORRECTION_BLEND_FRAMES : 0);
 		}
-	}, [ikMode, ikChains, activeRig, motion, posing, tlFrame, ikTick, ikFkJoints, physicsPreview, physicsShow]);
+	}, [ikMode, ikChains, activeRig, motion, posing, tlFrame, ikTick, ikFkJoints, physicsPreview, physicsShow, pendingIkEdit, activeChar.id]);
 
 	// Re-seat the handles on the keyed pose when the FRAME changes with IK
 	// on — scrubbing to frame 39 shows that frame's interpolated pose AND
@@ -4103,6 +4412,7 @@ export default function App() {
 	// (tools/ardy/visual-qa.mjs). Harmless in normal use.
 	useEffect(() => {
 	window.__cozyclay = {
+			runStudioAction,
 			runArdy: (options) => appContext.live.state.runArdy(options),
 			rigA: activeRig, motion, tlFrame, frameCount: tlFrameCount, playing: tlPlaying, ikMode, ikChains, ikFocus, contactRadii: ikChains?.values().next().value?.contactRadii ?? null, ik: ikStateRef.current,
 			rangePins, rangePinResiduals,
@@ -4209,22 +4519,33 @@ export default function App() {
 			insetPane: insetPaneRef.current,
 			mainPane: mainPaneRef.current,
 			// the selected prop's route, so QA can aim a gesture at the line
-			objectPath: selectedSceneObject?.path ?? null,
+			objectPath: routeOwner?.path ?? null,
+			objectPathOwnerId: routeOwner?.id ?? null,
 			pathPointIndex,
-			pathHandlesEnabled: !preview && !lookThroughShot && !ikMode && !posing && !!selectedSceneObject?.path,
+			pathHandlesEnabled: !preview && !lookThroughShot && !ikMode && !posing && !!routeOwner?.path,
 			addSceneObject: (kind, placement = {}) => addSceneObject(kind, placement),
 			scrub: (frame) => setTlFrame(Math.max(0, Math.min(tlFrameCount - 1, Math.round(frame)))),
 			pause: () => setTlPlaying(false),
 			// Motion-trail QA surface: read the current trail policy and drive the
 			// same drag -> preview -> pending-edit path headless checks cannot reach
 			// through synthetic pointers reliably.
-			trail: { falloffFrames: trailFalloffFrames, falloffS: trailFalloffS, edit: trailEdit, tool: ikEditTool, visible: showTrails },
+			trail: { falloffFrames: trailFalloffFrames, falloffS: trailFalloffS, edit: trailEdit, tool: ikEditTool, visible: showTrails, activeTrackId: trailTrackFocus, visibleTracks: trailTrackFocus ? [trailTrackFocus] : null },
 			trailPoints: (jointName = "Hips") => jointTrailPoints(motion, jointName, { baseY: activeChar.y ?? 0, scale: activeChar.scale ?? 1 }),
 			trailEditApply: (grabFrame, delta) => {
-				onTrailDragStart({ grabFrame });
+				onTrailDragStart({ track: "hips", grabFrame });
 				onTrailDragPreview({ track: "hips", grabFrame, delta });
 				onTrailDragEnd({ track: "hips", grabFrame, delta });
 			},
+			// QA-only IK drag seam: resolves the same production solve/end path as
+			// the viewport manipulator, with a deterministic world-space offset.
+			ikPreviewApply: (track = "leftHand", offset = { x: 0.02, y: 0, z: 0 }) => {
+				const chain = ikChains?.get(track), bone = chain?.bones?.[2];
+				if (!bone) return false;
+				const target = bone.getWorldPosition(new THREE.Vector3()).add(new THREE.Vector3(offset.x ?? 0, offset.y ?? 0, offset.z ?? 0));
+				ikSolve("chain", track, target);
+				ikDragEnd();
+				return true;
+			},
 			trailRegenerate: runTrailRegeneration,
 			// Fix-collisions QA surface: live penetration readout for headless
 			// checks; the fix itself runs through the buttons / runFixCollisions.
@@ -4271,7 +4592,7 @@ export default function App() {
 		// close over them: a stale closure would report the set as it was two
 		// edits ago — and, after an undo that removes a subject, would keep
 		// reporting the ghost's capsules.
-	}, [activeRig, motion, tlFrame, tlFrameCount, ikMode, ikChains, ikFocus, ikTick, charA, rangePins, rangePinResiduals, committedIkEdits, waypoints, lookThroughShot, selectedSceneObject, sceneObjects, rigs, characters, pathPointIndex, preview, posing, playMode, pathDraw, trailEdit, trailFalloffFrames, trailFalloffS, ikEditTool, showTrails, physicsPreview, physicsShow, physicsOptions, autoPhysicsRunning, platformFitRunning, platformFitLast, platformFitApplied]);
+	}, [activeRig, motion, tlFrame, tlFrameCount, ikMode, ikChains, ikFocus, ikTick, charA, rangePins, rangePinResiduals, committedIkEdits, waypoints, lookThroughShot, selectedSceneObject, sceneObjects, rigs, characters, pathPointIndex, preview, posing, playMode, pathDraw, trailEdit, trailTrackFocus, pendingIkEdit, trailFalloffFrames, trailFalloffS, ikEditTool, showTrails, physicsPreview, physicsShow, physicsOptions, autoPhysicsRunning, platformFitRunning, platformFitLast, platformFitApplied]);
 	// QA hook (plan §6.5): exposes history depth and the present === objects
 	// invariant so the browser suite can assert undo entry counts directly.
 	// Reads live store state at call time; re-registered after every render.
@@ -4320,19 +4641,37 @@ export default function App() {
 		fovDeg,
 		filmback,
 	}), [tlFrameCount, tlFps, charA, motion, fovDeg, filmback]);
-	const motionPos = useMemo(() => (
-		motion ? sampleAt(playbackSceneBase, null, tlFrame).subject : null
-	), [motion, playbackSceneBase, tlFrame]);
+	// The camera's subject grouped under a routed object (#655) stands where
+	// that object carries it: its played root through the object's carry,
+	// frame by frame — the same carry the renderer gives the body. Null when it
+	// rides nothing, so every reader below keeps the plain played root.
+	const subjectCarry = useMemo(() => {
+		if (!charA.parent) return null;
+		const objects = new Map(sceneObjects.map((object) => [object.id, object]));
+		const take = { frameCount: tlFrameCount, fps: tlFps };
+		return (point, frame) => {
+			if (!point) return point;
+			const at = carriedPointAt(objects, charA.parent, { x: point.x, y: charA.y ?? 0, z: point.z }, frame, take);
+			return { x: at.x, z: at.z };
+		};
+	}, [charA.parent, charA.y, sceneObjects, tlFrameCount, tlFps]);
+	const motionPos = useMemo(() => {
+		if (!motion && !subjectCarry) return null;
+		const subject = sampleAt(playbackSceneBase, null, tlFrame).subject;
+		return subjectCarry ? subjectCarry(subject, tlFrame) : subject;
+	}, [motion, subjectCarry, playbackSceneBase, tlFrame]);
 
 	// The subject's full per-frame scene trajectory — what the follow camera
-	// is derived from. Without a loaded motion the subject stands still and
-	// the follow camera simply composes a static frame.
+	// is derived from. Without a loaded motion, and riding nothing, the subject
+	// stands still and the follow camera simply composes a static frame.
 	const subjectTrack = useMemo(() => {
 		if (!shots.some((shot) => shot.camera?.mode === "follow" || shot.camera?.mode === "rail")) return null;
 		const frames = Math.max(tlFrameCount, 1);
-		return Array.from({ length: frames }, (_, frame) =>
-			sampleAt(playbackSceneBase, null, frame).subject);
-	}, [shots, playbackSceneBase, tlFrameCount]);
+		return Array.from({ length: frames }, (_, frame) => {
+			const subject = sampleAt(playbackSceneBase, null, frame).subject;
+			return subjectCarry ? subjectCarry(subject, frame) : subject;
+		});
+	}, [shots, playbackSceneBase, tlFrameCount, subjectCarry]);
 
 	// The dense rail (spline through the drawn control points) — shared by
 	// the follow controller and the Top-View display.
@@ -4443,7 +4782,7 @@ export default function App() {
 				? { label: ko("ROOT PATH", "루트 경로"), kind: "root" }
 				: null;
 
-	function bufferToPng(buffer, output = shotOutput) {
+	function bufferToPng(buffer, output = shotOutput, decorate = null) {
 		const canvas = document.createElement("canvas");
 		if (output === shotOutput) {
 			canvas.width = shotOutput.width;
@@ -4463,6 +4802,7 @@ export default function App() {
 			);
 		}
 		ctx.putImageData(image, 0, 0);
+		decorate?.(ctx);
 		return canvas.toDataURL("image/png");
 	}
 
@@ -4476,6 +4816,12 @@ export default function App() {
 		cam.rotation.order = "YXZ";
 		cam.rotation.set(framing.pitch, framing.yaw, 0);
 		cam.fov = framing.fovDeg;
+		const prevAspect = cam.aspect;
+		const offset = framing.viewOffset;
+		if (offset) {
+			cam.aspect = offset.fullWidth / offset.fullHeight;
+			cam.setViewOffset(offset.fullWidth, offset.fullHeight, offset.x, offset.y, offset.width, offset.height);
+		}
 		cam.updateProjectionMatrix();
 		const needsOwnTarget = output.width !== shotOutput.width || output.height !== shotOutput.height;
 		const capture = needsOwnTarget && typeof captureRef.current.createExportCapture === "function"
@@ -4491,10 +4837,85 @@ export default function App() {
 			look.current.yaw = prev.yaw;
 			look.current.pitch = prev.pitch;
 			cam.fov = prev.fov;
+			if (offset) {
+				cam.clearViewOffset();
+				cam.aspect = prevAspect;
+			}
 			cam.updateProjectionMatrix();
 		}
 	}
 
+	/** A live capture command's requested `output` size, or null to use its default. */
+	function requestedCaptureOutput(args) {
+		const requested = args?.output;
+		return Number.isFinite(requested?.width) && Number.isFinite(requested?.height)
+			? { width: Math.round(requested.width), height: Math.round(requested.height) }
+			: null;
+	}
+
+	/** The Top View as a PNG: a 2D data diagram drawn from editor state by
+	    src/plan-diagram.js (grid, footprints, cast, every shot camera, the current
+	    shot's action line and blocked sight lines). No render is involved. */
+	function capturePlanPng(output = { width: 1280, height: 720 }) {
+		const live = appContext.live.state, s = readStudioState();
+		const canvas = document.createElement("canvas");
+		canvas.width = output.width;
+		canvas.height = output.height;
+		drawPlanDiagram(canvas.getContext("2d"), { frame: s.view.frame, frameCount: s.frameCount, objects: s.objects, characters: s.characters, shotDocument: { shots: s.shots }, camera: s.camera },
+			{ width: output.width, height: output.height, ports: { bounds: studioBounds }, currentShotId: live.activeShotId, aspect: shotOutput.width / shotOutput.height });
+		return { dataUrl: canvas.toDataURL("image/png"), width: output.width, height: output.height, frame: live.timeline.currentFrame, shotId: live.activeShotId };
+	}
+
+	/** The canvas runs under the floating panels, so "what I see" is only the uncovered middle.
+	    Returns the largest centred `aspect` rectangle inside that region as a camera view offset. */
+	function visibleViewOffset(aspect) {
+		const canvas = document.querySelector(".viewport canvas");
+		if (!canvas) return null;
+		const box = canvas.getBoundingClientRect();
+		const edge = (selector, side) => {
+			const rect = document.querySelector(selector)?.getBoundingClientRect();
+			return rect && rect.width > 0 && rect.height > 0 ? rect[side] : null;
+		};
+		const left = Math.max(box.left, edge(".studio-left-column", "right") ?? box.left);
+		const right = Math.min(box.right, edge(".studio-right-column", "left") ?? box.right);
+		const top = Math.max(box.top, edge(".topbar", "bottom") ?? box.top);
+		const bottom = Math.min(box.bottom, edge(".studio-dock-slot", "top") ?? box.bottom);
+		if (right - left < 50 || bottom - top < 50) return null;
+		const width = Math.min(right - left, (bottom - top) * aspect);
+		const height = width / aspect;
+		return {
+			fullWidth: box.width, fullHeight: box.height,
+			x: (left + right) / 2 - width / 2 - box.left, y: (top + bottom) / 2 - height / 2 - box.top,
+			width, height,
+		};
+	}
+
+	/** Pose mode's image generation: the shot camera's view of the pose as it stands, at the
+	    delivery size, plus the scene's identity/environment references. The pose-mode object
+	    fade is lifted for this draw only (props are re-synced right after, so a demand frame loop keeps it), and editor
+	    overlays such as motion trails are hidden around it. */
+	function capturePoseImage(source = "view") {
+		const viewCam = source === "view" ? poserCamRef.current : null;
+		let framing = captureCurrentFraming();
+		if (viewCam) {
+			const dir = viewCam.getWorldDirection(new THREE.Vector3());
+			const pos = viewCam.getWorldPosition(new THREE.Vector3());
+			framing = captureFraming({ pos, yaw: Math.atan2(-dir.x, -dir.z), pitch: Math.asin(THREE.MathUtils.clamp(dir.y, -1, 1)), fovDeg: viewCam.fov });
+			framing.viewOffset = visibleViewOffset(shotOutput.width / shotOutput.height);
+		}
+		const scene = captureRef.current?.scene;
+		const overlays = [];
+		scene?.traverse((node) => {
+			if (node.userData.editorOverlay && node.visible) { node.visible = false; overlays.push(node); }
+		});
+		try {
+			const dataUrl = withPoseFadeLifted(propSyncRef.current, () => captureFramingPng(framing, shotOutput));
+			return dataUrl ? { dataUrl, references: captureShotReferences() } : null;
+		} finally {
+			for (const node of overlays) node.visible = true;
+		}
+	}
+
 	function copyPrompt(prompt) {
 		const write = navigator.clipboard?.writeText(prompt);
 		if (!write) return;
@@ -6428,13 +6849,32 @@ export default function App() {
 			preserveAuthoredMotion: Boolean(c.layer?.waypoints?.length) }]));
 		return { host: { workspaceId: liveWorkspaceIdRef.current, documentEpoch: studioDocumentEpochRef.current,
 				sceneId: activeSceneIdRef.current, sceneEpoch: studioSceneEpochRef.current }, workspaceHandle: liveWorkspaceHandleRef.current,
-			sceneName: live.scenes.find(s => s.id === activeSceneIdRef.current)?.name ?? "Untitled Scene", aspect: live.stage.shotAspect, stage: live.stage,
+			sceneName: live.scenes.find(s => s.id === activeSceneIdRef.current)?.name ?? "Untitled Scene", previsMode: scenesDomain.previsMode, aspect: live.stage.shotAspect, stage: live.stage,
 			objects: storeRef.current.objects, characters: list, targets, shots: live.shots, frameCount: live.timeline.frameCount,
 			selection: live.studioSelection, activeCharacterId: live.activeCharacterId, selectedShotId: live.studioShotId,
 			view: live.studioView, camera: live.studioCamera ?? readStudioCamera(), filmback: live.filmback, manual: manualCameraOverrideRef.current,
 			bridgeReady: Boolean(bridge?.ok), busy: storeRef.current.present() !== storeRef.current.objects || Boolean(studioGestureRef.current ||
 				ikBodyDragRef.current || lineDragRef.current || lineDrawRef.current || linePinDragRef.current || live.studioPhysicsRunning || recRef.current) };
 	}
+	function sampleStudioStateAt(frame, current = readStudioState()) {
+		const shot = shotAtFrame(current.shots ?? current.shotDocument?.shots ?? [], frame);
+		const sampledPlayback = sampleAt(playbackScene, shot, frame);
+		const sampledSubject = sampledPlayback.subject;
+		const primaryId = current.activeCharacterId ?? current.characters[0]?.id;
+		const characters = sampledSubject && primaryId
+			? current.characters.map(character => character.id === primaryId ? { ...character, x: sampledSubject.x, z: sampledSubject.z } : character)
+			: current.characters;
+		const sampled = sampledPlayback.camera;
+		if (!sampled) return { ...current, frame, characters, view: { ...current.view, frame } };
+		const position = { x: sampled.pos.x, y: sampled.pos.y, z: sampled.pos.z };
+		const direction = forwardFrom(sampled.yaw, sampled.pitch);
+		return { ...current, frame, characters, view: { ...current.view, frame }, camera: {
+			position,
+			lookAt: { x: position.x + direction.x, y: position.y + direction.y, z: position.z + direction.z },
+			focalMm: fovToFocalMm(sampled.fovDeg * Math.PI / 180, current.filmback.sensorId, current.filmback.aspectRatio),
+			sensorId: current.filmback.sensorId,
+		} };
+	}
 
 	/** The authored stage envelope (key light, environment, filmback) published
 	 * as one body: the live read model first, so the next synchronous read sees
@@ -6502,6 +6942,14 @@ export default function App() {
 		const raw = readStudioState();
 		const original = raw.characters.find(c => c.id === entity.id) ?? raw.characters.find(c => c.model === entity.model);
 		const target = original && raw.targets.get(original.id);
+		if (isProxyFigure(original)) {
+			const clip = target?.motion;
+			const placement = placementAt(original, frame, {
+				shotAt: at => shotAtFrame(raw.shots, at),
+				takeRoot: clip ? sampleAt({ frameCount: clip.frames, motion: clip }, null, frame).subject : null,
+			});
+			return proxyFigureBounds(original, placement);
+		}
 		if (!target?.rig) throw new StudioProtocolError("TARGET_NOT_READY", "Character bounds require its loaded rig.");
 		const rig = cloneSkeleton(target.rig), parent = new THREE.Group();
 		const originals = [], copies = [];
@@ -6530,13 +6978,15 @@ export default function App() {
 			for (const skeleton of skeletons) skeleton.dispose(); parent.remove(rig);
 		}
 	}
-	function operateStudio({ selection, view, shotId }) {
+	function operateStudio({ selection, view, shotId, modeSet = true }) {
 		const { frame } = view;
 		appContext.patchLive({ studioSelection: selection, studioView: view, studioShotId: shotId });
 		appContext.patchTimeline({ currentFrame: frame }); tlFrameRef.current = frame;
 		if (selection && ["character", "rig"].includes(selection.kind)) { appContext.patchLive({ activeCharacterId: selection.id }); setActiveCharacterId(selection.id); }
 		setSelectedHierarchyId(selection ? selection.kind === "object" ? `object:${selection.id}` : ["character", "rig"].includes(selection.kind) ? `character:${selection.id}` : selection.kind === "camera" ? "camera" : "shot" : "");
-		setTlFrame(frame); setWorkflowMode(view.mode); setLookThroughShot(view.lookThrough); setGridView(view.grid); setAutoColor(view.autoColor); setTlPlaying(view.playing);
+		// Sculpt is UI-only and publishes as Stage (below): a view write that
+		// names no mode keeps the editor in it.
+		setTlFrame(frame); setWorkflowMode((current) => (current === "sculpt" && !modeSet && view.mode === "scene" ? current : view.mode)); setLookThroughShot(view.lookThrough); setGridView(view.grid); setAutoColor(view.autoColor); setTlPlaying(view.playing);
 	}
 	const studioGestureRef = useRef(false);
 	// The Studio turn authors the scene through its own families and never
@@ -6555,13 +7005,16 @@ export default function App() {
 			selectedStudioChar ? { kind: "character", id: selectedStudioChar, hierarchyId: selectedHierarchyId } : selectedHierarchyId === "camera" ? { kind: "camera", id: "camera" } : { kind: "scene", id: activeSceneId },
 		studioShotId: activeShot?.id ?? null,
 		studioPhysicsRunning: autoPhysicsRunning,
-		studioView: { mode: workflowMode, frame: tlFrame, playing: tlPlaying, lookThrough: lookThroughShot, grid: gridView, autoColor },
+		// The agent's mode vocabulary is four (studio-agent-protocol.js): the
+		// sculpt turntable is the Stage's scene seen in isolation.
+		studioView: { mode: sculptMode ? "scene" : workflowMode, frame: tlFrame, playing: tlPlaying, lookThrough: lookThroughShot, grid: gridView, autoColor },
 	});
 	appContext.updatePorts({
 		read: readStudioState, revision: sceneRevisionRef, bounds: studioBounds, commit: commitStudioDraft,
 		operate: operateStudio, undo: () => stepStudioHistory(false), redo: () => stepStudioHistory(true),
+		sampleStateAt: sampleStudioStateAt,
 		history: redo => appContext.historyEntry(redo), finishHistoryGesture: finishStudioHistoryGesture,
-		stepHistory: stepStudioHistory, capture: () => liveQueries.capture_framing_png({}),
+		stepHistory: stepStudioHistory, capture: () => liveQueries.capture_framing_png({}), capturePlan: () => liveQueries.capture_plan_png({}),
 		// One shot frame as raw read-back pixels (rows bottom-up), from the export
 		// path captureShotFramePng uses; an export in flight renders at its output.
 		renderFrameBuffer: frame => {
@@ -6605,7 +7058,7 @@ export default function App() {
 			scenes: appContext.live.scenes.map(({ id, name }) => ({ id, name })), activeSceneId: activeSceneIdRef.current,
 			// What a save needs: a name, a file this session, and (to pick or
 			// re-grant a file) the user's click still active.
-			project: { name: projectName, hasFile: Boolean(projectHandleRef.current), fileAccess: hasFileSystemAccess(),
+			project: { name: projectName, previsMode, hasFile: Boolean(projectHandleRef.current), fileAccess: hasFileSystemAccess(),
 				gesture: globalThis.navigator?.userActivation?.isActive === true },
 			// What generate() reads for the Send-to-AI package, as this render has it.
 			aiShot: { mode, imageModel },
@@ -6670,25 +7123,68 @@ export default function App() {
 					? ko("Unsaved changes", "저장되지 않은 변경사항")
 					: ko("Saved", "저장됨");
 
+	// Sculpt mode's panel heads the Details column (DetailsSlot mounts it).
+	const sculptPanel = sculptMode && !embedMode ? (
+		<SculptPanel
+			run={sculptRun}
+			reference={sculptReference}
+			onReference={(file) => void chooseSculptReference(file)}
+			onStart={startSculptRun}
+			onCancel={() => sculptRunRef.current?.cancel()}
+			onPlaceInScene={placeSculptInScene}
+			canStart={Boolean(sculptReference) && sculptAgentStatus === "ready" && Boolean(liveWorkspaceHandle) && Boolean(sculptModelPick.model)}
+			blueprint={{
+				...sculptBlueprint,
+				prompt: buildBlueprintPrompt({ pose: sculptBlueprint.pose, notes: sculptBlueprint.notes }),
+				layout: BLUEPRINT_LAYOUT,
+				// The image model is ChatGPT-only (the sidecar refuses others with a reason).
+				refusal: sculptAgentStatus === "signed-out" ? ko("Sign in with ChatGPT in the Agent panel to generate a blueprint.", "도면을 생성하려면 에이전트 패널에서 ChatGPT로 로그인하세요.") : null,
+				onPose: (pose) => setSculptBlueprint((current) => ({ ...current, pose })),
+				onNotes: (notes) => setSculptBlueprint((current) => ({ ...current, notes })),
+				onGenerate: () => void generateSculptBlueprint(),
+				onCancel: cancelSculptBlueprint,
+			}}
+			modelPicker={{
+				...sculptModels,
+				model: sculptModelPick.model,
+				effort: sculptModelPick.effort,
+				// A new model starts at its own default effort.
+				onModel: (model) => chooseSculptModel({ model, effort: null }),
+				onEffort: (effort) => chooseSculptModel({ effort }),
+			}}
+			startRefusal={sculptAgentStatus === "signed-out"
+				? ko("Sign in to the Agent (⌘B) to sculpt from an image.", "이미지로 조형하려면 에이전트(⌘B)에 로그인하세요.")
+				: sculptAgentStatus === "ready" && !liveWorkspaceHandle
+					? ko("The live editor is disconnected — reconnect to sculpt.", "라이브 편집기가 연결되지 않았어요 — 연결 후 조형하세요.")
+					: sculptAgentStatus === "ready" && sculptModels.state === "failed"
+						? ko("No model is available — add a provider key in the Agent panel.", "사용할 모델이 없어요 — 에이전트 패널에서 제공자 키를 추가하세요.")
+						: null}
+			sculptName={sculptTarget?.name ?? null}
+		/>
+	) : null;
 	// The single shell snapshot keeps subsequent region work out of App.
 	const shellContext = {
-		projectMenuOpen, setProjectMenuOpen, projectDirty, projectName, projectStartupOpen,
+		sculptPanel,
+		projectMenuOpen, setProjectMenuOpen, projectDirty, projectName, previsMode, projectStartupOpen,
 		requestNewProject, setProjectStartupOpen, setProjectBrowserOpen, runStudioAction, saveProject,
 		projectManifest, projectSaveState, recState, exportMenuTriggerRef, exportMenuOpen,
 		exportShotIdRef, setExportMenuAnchor, setExportMenuOpen, exportPhaseLabel,
 		exportMenuAnchor, resultOpen, exportFeedback, shots, exportKeyframePacks,
 		hasCameraKeys, motion, exportRenderPasses, exportDepthVideo, exportStoryboard,
+		exportContactSheet, exportPanelPacks, exportAnimatic,
+		capturePanelThumbnail, packMetaForShot, previsMode: scenesDomain.previsMode, sceneRevision: sceneRevisionRef.current,
 		downloadOtioCutList, projectStatus, liveWorkspaceHandle, selectedHierarchyId, selectHierarchy,
 		aimEditorAtKeyLight, characters, showB, ikFrames, ikMode,
 		rowIdForCharIndex, activeCharIndex, waypoints, sceneObjects, scenes,
 		activeSceneId, selectSceneDocument, createSceneDocumentFromUi, duplicateSceneDocumentFromUi, renameSceneDocumentFromUi,
-		deleteSceneDocumentFromUi, addSceneObject, renameSceneObject, deleteSceneObject, frameSelection,
+		deleteSceneDocumentFromUi, addSceneObject, renameSceneObject, deleteSceneObject, frameSelection, groupObjectUnderNewEmpty, renameRequest,
 		toggleHierarchyHidden, propsDrop, hierarchyReparent, agentTouchedRows, workflowMode,
-		selectWorkflowMode, gizmoMode, setGizmoMode, snapEnabled, setSnapEnabled,
+		selectWorkflowMode, gizmoMode, setGizmoMode, snapEnabled, setSnapEnabled, sculptView, requestSculptView,
 		preset, applyPreset, cameraPresetId, i2vMotionCameraLocked, shotAspectKey,
 		fovDeg, shotsDomain, shot, setNonce, workspaceLayout,
 		viewMenuTriggerRef, viewMenuOpen, setViewMenuAnchor, setViewMenuOpen, viewLooksActive,
 		viewMenuAnchor, gridView, setGridView, autoColor, setAutoColor,
+		guideMode,
 		isCharacterSelection, partColoursChoice, embedMode, agentCollapsed, sceneSaveError,
 		studioAgentError, studioAgentMode, setStudioAgentMode, AgentPanel, setAgentCollapsed,
 		buildStudioAgentContext, highlightAgentTargets, generateI2vMotionFromUi, selectedSceneObject, rigSelection,
@@ -6712,12 +7208,13 @@ export default function App() {
 		linePreviewError, generationBusy, bridgeChecking, lineReadinessState, runLineEdit,
 		openMotionSetup, recheckMotionHealth, resetLineCurve, exitLineEditMode, readinessState,
 		ardyRunning, cancelArdy, ardyStatus, ardyOutcome, addPromptClip,
-		tlFrame, isRigSelection, ikChains, ikFocus, footSnap,
+		tlFrame, isRigSelection, ikChains, ikFocus, footSnap, poseObjectOpacity, setPoseObjectOpacity, capturePoseImage,
 		collisionCleanupSupported, runFixCollisions, runFixCollisionsRange, autoPhysicsRunning, physicsProgress,
 		physicsPreview, physicsShow, physicsOptions, platformFitRunning, platformFitProgress,
 		platformFitLast, platformFitApplied, changePhysicsOptions, runAutoPhysics, showPhysicsPreview,
 		applyPhysicsPreview, cancelPhysicsPreview, ikEditTool, setIkEditTool, showTrails,
-		setShowTrails, trailFalloffS, setTrailFalloffS, trailEdit, runTrailRegeneration,
+		setShowTrails, trailFalloffS, setTrailFalloffS, trailEdit, trailTrackFocus, selectTrailTrack, clearTrailTrackFocus, runTrailRegeneration,
+		pendingIkEdit, applyPendingIkEdit, cancelPendingIkEdit,
 		trailReadinessState, rangePins, rangePinResiduals, rangePinSelection, rangePinPartPick,
 		rangePinPreview, setRangePinSelection, setRangePinPartPick, previewRangePinDraft, applyRangePinDraft,
 		deleteRangePin, hasEnvSheet, environment, style, environmentImage,
@@ -6739,10 +7236,11 @@ export default function App() {
 		addActiveCranePoint, deleteSelectedCranePoint, setCraneSelectedIndex, tlFps, ghostLayers,
 		pathSpeed, tlPlaying, pendingWaypointFrame, stateBadge, applyMotionTrim,
 		resetMotionTrim, cutMotionAtPlayhead, changeMotionSegmentSpeed, removeMotionSegmentById, bodyContact,
-		activeShotIdx, railDraw, pathDraw, setPathDraw, setRailDraw,
-		setWorkspaceLayout, timingTokenRef, railCurve, ikAddKeyframe, ikDeleteKeyframe,
+		activeShotIdx, railDraw, pathDraw, pathTarget, setPathDraw, setRailDraw,
+		setWorkspaceLayout, timingTokenRef, railCurve, ikAddKeyframe, ikDeleteKeyframe, pathPointIndex, setPathPointIndex,
 		setBodyContact, setFootSnap, advanceFrame, stepFrame, cameraPreviewEndRef,
-		manualCameraOverrideRef, setTlPlaying, toggleWaypointMode, setWaypointMode, selectActiveCharacterInHierarchy,
+		manualCameraOverrideRef, setTlPlaying, setWaypointMode, selectActiveCharacterInHierarchy,
+		toggleWaypointMode: storyboardProject ? undefined : toggleWaypointMode,
 		setActiveWaypointId, setPendingWaypointFrame, removeWaypoint, queueRootWaypointFrame, revealPromptBlocks,
 		resizePromptClip, movePromptClip, removePromptClip, setSelectedHierarchyId, addCameraKeyframe,
 		moveCameraKeyframe, removeCameraKeyframe, syncActiveCameraFraming, activeCamera, activeShotDuration,
@@ -6764,7 +7262,7 @@ export default function App() {
 	return (
 		<AppContext.Provider value={appContext}>
 		<StudioShellContext.Provider value={shellContext}>
-		<StudioShell className={"app" + (renderActive ? "" : " render-idle")} style={workspaceStyle} data-workflow-mode={workflowMode} data-embed-mode={embedMode ? "playview" : playgroundMode ? "playground" : undefined} data-playground-hint={playgroundMode ? playgroundHint ?? undefined : undefined} data-tutorial-step={cameraTutorial ? cameraTutorialStep ?? undefined : undefined} data-rail-draw={railDraw ? 1 : undefined} data-shot-look={lookThroughShot && !embedMode ? 1 : undefined} data-plan-draw={railDraw || pathDraw || waypointMode ? 1 : undefined}
+		<StudioShell className={"app" + (renderActive ? "" : " render-idle")} style={workspaceStyle} data-workflow-mode={workflowMode} data-previs-mode={scenesDomain.previsMode} data-embed-mode={embedMode ? "playview" : playgroundMode ? "playground" : undefined} data-playground-hint={playgroundMode ? playgroundHint ?? undefined : undefined} data-tutorial-step={cameraTutorial ? cameraTutorialStep ?? undefined : undefined} data-rail-draw={railDraw ? 1 : undefined} data-shot-look={lookThroughShot && !embedMode ? 1 : undefined} data-plan-draw={railDraw || pathDraw || waypointMode ? 1 : undefined}
 			viewport={
 				<div className="viewport" data-drop={viewportDrop.over ? "over" : undefined} {...viewportDrop.handlers}
 					onWheel={(event) => {
@@ -6775,6 +7273,13 @@ export default function App() {
 						}
 					}}>
 				<ViewportToolbar />
+				{(embedMode || playgroundMode) && <CompositionGuideButton guideMode={guideMode} onCycle={(mode) => runStudioAction("view.setGuideMode", { mode })} />}
+				{sculptMode && !sculptTarget && (
+					<div className="vp-sculpt-hint" role="status" data-testid="sculpt-empty">
+						<strong>{ko("New sculpt", "새 조형물")}</strong>
+						<span>{ko("Add a reference image in the Sculpt panel and press Start — or select a sculpt and press 5.", "조형 패널에 참조 이미지를 넣고 시작을 누르세요 — 또는 조형물을 선택하고 5를 누르세요.")}</span>
+					</div>
+				)}
 
 					{/* Sits under the mode tabs and left of the Top-View inset, over the
 					    stage it is teaching. The overlay itself never takes the pointer
@@ -6784,6 +7289,7 @@ export default function App() {
 							key={cameraTutorialAttempt}
 							analytics={cameraTutorialAnalytics.current}
 							previewing={lookThroughShot}
+							previsMode={scenesDomain.previsMode}
 							shotCount={shots.length}
 							railReady={shots.some((shot) => Array.isArray(shot.camera?.cameraRail) && shot.camera.cameraRail.length >= 2)}
 							onStepChange={setCameraTutorialStep}
@@ -6850,7 +7356,7 @@ export default function App() {
 							<KeyLightPuck
 								keyLight={keyLight}
 								selected={keyLightSelected}
-								visible={!preview && !lookThroughShot}
+								visible={!preview && !lookThroughShot && !sculptMode}
 								paneRef={mainPaneRef}
 								camRef={editorCamRef}
 								onSelect={() => selectHierarchy("light")}
@@ -6862,12 +7368,14 @@ export default function App() {
 							{gridView ? <GridFloor layer={GIZMO_LAYER} /> : <Room light={uiTheme === "light"} />}
 							<SetProps
 								objects={stageSceneObjects}
+								authoredObjects={sceneObjects}
 								selectedId={selectedSceneObjectId}
 								frameRef={propFrameRef}
 								take={{ frameCount: tlFrameCount, fps: tlFps }}
 								attachFrameRef={attachFrameRef}
 								syncRef={propSyncRef}
 								worldRef={propWorldRef}
+								fadeOpacity={workflowMode === "pose" ? poseObjectOpacity : null}
 							/>
 
 							<PerspectiveCamera
@@ -6883,7 +7391,7 @@ export default function App() {
 							    operator's own view of the set. */}
 							<PerspectiveCamera
 								ref={editorCamRef}
-								makeDefault={!ikMode && !lookThroughShot}
+								makeDefault={!ikMode && !lookThroughShot && !sculptMode}
 								fov={55}
 								near={0.1}
 								far={100}
@@ -6908,21 +7416,47 @@ export default function App() {
 								position={[0, 24, 0]}
 								rotation={[-Math.PI / 2, 0, 0]}
 							/>
+							{/* Sculpt mode's own orbit camera and turntable; it owns the main
+							    pane (DualRender's editor slot) while the shot preview keeps
+							    drawing the whole scene. Unmounting restores normal rendering. */}
+							{sculptMode && (
+								<SculptTurntable
+									camRef={sculptCamRef}
+									objects={sceneObjects}
+									target={sculptTarget}
+									size={sculptTarget ? objectSize(sculptTarget) : null}
+									view={sculptView}
+									light={uiTheme === "light"}
+									busy={["measure", "draft", "score", "refine"].includes(sculptRun?.stage)}
+									changedParts={sculptRun?.changedParts ?? null}
+								/>
+							)}
 
 							{characterViews.map((view) => (
-								<Character
+								// Always wrapped, grouped or not: giving or taking a parent
+								// must not remount the rig the playback effects hold.
+								<ObjectCarrier
 									key={`${view.id}:${rigMountEpoch}`}
-									url={view.url}
-									position={view.position}
-									rot={view.rot}
-									tint={view.tint}
-									partColoursEnabled={view.partColoursEnabled}
-									partColoursMode={view.partColoursMode}
-									pose={view.pose}
-									scale={view.scale}
-									onRig={view.onRig}
-									pickId={view.pickId}
-								/>
+									objectId={view.parent}
+									objectsRef={sceneObjectLookupRef}
+									frameRef={propFrameRef}
+									take={{ frameCount: tlFrameCount, fps: tlFps }}
+									registryRef={carrierRegistryRef}
+								>
+									<Character
+										url={view.url}
+										{...{ model: view.model, posture: view.posture }}
+										position={view.position}
+										rot={view.rot}
+										tint={view.tint}
+										partColoursEnabled={view.partColoursEnabled}
+										partColoursMode={view.partColoursMode}
+										pose={view.pose}
+										scale={view.scale}
+										onRig={view.onRig}
+										pickId={view.pickId}
+									/>
+								</ObjectCarrier>
 							))}
 
 							{/* Selection marker: XYZ tripod + ring on the picked cast
@@ -6935,7 +7469,7 @@ export default function App() {
 									objects={characterGizmoObject ? [characterGizmoObject] : []}
 									mode={gizmoMode}
 									snap={snapEnabled}
-									enabled={!planIsMain && !posing && !ikMode && !playMode && !!characterGizmoObject}
+									enabled={!planIsMain && !posing && !ikMode && !playMode && !sculptMode && !!characterGizmoObject}
 									paneRef={mainPaneRef}
 									camRef={lookThroughShot ? shotCamRef : editorCamRef}
 									shotAspect={lookThroughShot ? shotOutput.aspect : null}
@@ -6994,6 +7528,7 @@ export default function App() {
 								// editorial camera keys resume when the block returns to Keys mode.
 								following={!followCamActive && hasCameraKeys && (preview || (moveFollow && !ikMode && !waypointMode && !posing))}
 								followFrame={tlFrame}
+								frameRef={propFrameRef}
 								fps={tlFps}
 								keys={cameraKeys}
 								shots={shots}
@@ -7006,6 +7541,7 @@ export default function App() {
 							<FollowCamRig
 								enabled={followCamActive && !movePlaying}
 								frame={tlFrame}
+								frameRef={propFrameRef}
 								scene={playbackScene}
 								shot={activeShot}
 								camRef={shotCamRef}
@@ -7017,7 +7553,7 @@ export default function App() {
 							    pointerdowns that hit a handle, so empty-space drags orbit
 							    and the wheel dollies without wrecking the framing. */}
 							<FlyControls
-								enabled={!posing && !playMode}
+								enabled={!posing && !playMode && !sculptMode}
 								cameraLocked={lookThroughShot && i2vMotionCameraLocked}
 								camRef={ikMode ? poserCamRef : lookThroughShot ? shotCamRef : editorCamRef}
 								look={ikMode ? poserLook : lookThroughShot ? look : editorLook}
@@ -7039,6 +7575,7 @@ export default function App() {
 									markSemanticEdit("pose", before, after);
 									setPoseTick((n) => n + 1);
 								}}
+								onCommit={commitPosedPose}
 							/>
 							<IkHandles
 								chains={ikChains}
@@ -7069,6 +7606,7 @@ export default function App() {
 								look={look}
 								fovDeg={fovDeg}
 								characters={characters}
+								characterPlacements={characterViews}
 								onMoveCharacter={moveCharacter}
 								onCameraGestureStart={beginCameraFramingGesture}
 								pathStart={activeChar}
@@ -7092,33 +7630,30 @@ export default function App() {
 								cameraRailPoints={railCurve ? railCurve.points : null}
 								railDraw={railDraw}
 								pathDraw={pathDraw}
-								objectPathPoints={selectedSceneObject?.path?.points ?? null}
+								objectPath={routeOwner?.path ?? null}
 								objectPathSelectedIndex={pathPointIndex}
 								onObjectPathPointSelect={setPathPointIndex}
-								onObjectPathPointMove={(index, floor) => {
-									const path = selectedSceneObject?.path;
+								onObjectPathChange={(patch) => {
+									const path = routeOwner?.path;
 									if (!path) return;
-									// The board edits the floor route only; a point's height is
-									// the scene's business, so y rides through untouched.
-									const points = path.points.map((point, i) => (i === index ? { ...point, x: floor.x, z: floor.z } : point));
-									changeSceneObject(selectedSceneObject.id, { path: { ...path, points } }, planPathTokenRef.current);
+									// Inside the gesture's own transaction (planPathTokenRef), like
+									// the 3D view. The board bends the floor route only; a point's
+									// height is the scene's business, so y rides through untouched.
+									changeSceneObject(routeOwner.id, { path: { ...path, ...patch } }, planPathTokenRef.current);
 								}}
-								onObjectPathPointInsert={(index, t) => {
-									const path = selectedSceneObject?.path;
-									if (!path || path.points.length >= MAX_PATH_POINTS) return;
-									const a = path.points[index];
-									const b = path.points[index + 1];
-									const inserted = {
-										x: a.x + (b.x - a.x) * t,
-										y: (a.y ?? 0) + ((b.y ?? 0) - (a.y ?? 0)) * t,
-										z: a.z + (b.z - a.z) * t,
-									};
-									const points = [...path.points.slice(0, index + 1), inserted, ...path.points.slice(index + 1)];
+								onObjectPathMarkInsert={(t) => {
+									const path = routeOwner?.path;
+									if (!path) return;
+									// The new dot is born with the lean the route already has there,
+									// and it goes to the record that owns the route (the selected
+									// group may only contain it).
+									const added = insertPathMark(path, t);
+									if (!added) return;
 									const token = beginSceneTransaction({ owner: "object-path", cancel: () => {} });
-									changeSceneObject(selectedSceneObject.id, { path: { ...path, points } }, token);
+									changeSceneObject(routeOwner.id, { path: { ...path, marks: added.marks } }, token);
 									endSceneTransaction(token, { commit: true });
-									setPathPointIndex(index + 1);
-									setToast(ko("Point added — drag it here, or lift it in the scene", "점을 추가했어요 — 여기서 끌거나 씬에서 높이를 올리세요"));
+									setPathPointIndex(added.index);
+									setToast(ko("Dot added — drag it to bend the route", "점을 추가했어요 — 끌어서 경로를 휘세요"));
 								}}
 								onObjectPathGestureStart={() => {
 									planPathTokenRef.current = beginSceneTransaction({ owner: "object-path", cancel: () => { planPathTokenRef.current = null; } });
@@ -7131,16 +7666,22 @@ export default function App() {
 								keyLight={keyLight}
 								onRailStroke={shotsDomain.drawCameraRail}
 								onPathStroke={(stroke) => {
-									if (!selectedSceneObject) return;
-									// Few points on purpose: the stroke sets the shape, the
-									// operator adds the handles they actually want by
-									// double-clicking the line. Height comes later, from
+									if (!pathTarget) return;
+									// The stroke keeps its shape, as the camera rail's does; the
+									// operator adds the dots they want to hold by double-clicking
+									// the line. The route starts at the height
+									// the object stands at, so a raised body (a chassis on its
+									// wheels, a prop on a table) travels where it is instead of
+									// dropping to the floor; changing height comes later, from
 									// dragging a point in the scene.
-									const points = strokeToPathPoints(stroke, simplifyStroke);
+									const height = pathTarget.attach ? 0 : pathTarget.y ?? 0;
+									const points = strokeToPathPoints(stroke, simplifyStroke).map((point) => ({ ...point, y: height }));
 									if (points.length < 2) return;
 									const token = beginSceneTransaction({ owner: "object-path", cancel: () => {} });
-									changeSceneObject(selectedSceneObject.id, { path: { ...(selectedSceneObject.path ?? {}), points } }, token);
+									// A new stroke is a new shape: marks belong to the old one.
+									changeSceneObject(pathTarget.id, { path: { ...(pathTarget.path ?? {}), points, marks: [] } }, token);
 									endSceneTransaction(token, { commit: true });
+									setPathPointIndex(null);
 									setPathDraw(false);
 									const metrics = pathMetrics(createObjectPath({ points }));
 									setToast(isKo
@@ -7153,11 +7694,11 @@ export default function App() {
 							    the plan owns the big pane (the pucks are the handles there)
 							    and while posing/IK owns the pointer. */}
 							<ObjectGizmo
-								object={cameraGizmoObject ?? lightGizmoObject ?? (selectedSceneObject && !isEffectivelyHidden(selectedSceneObject, sceneObjects, characters) ? selectedSceneObject : null)}
+								object={cameraGizmoObject ?? lightGizmoObject ?? (selectedSceneObject && !isEffectivelyHidden(selectedSceneObject, sceneObjects, characters) ? gizmoSceneObject : null)}
 								objects={sceneObjects}
 								mode={lightGizmoObject ? "move" : cameraGizmoObject ? (gizmoMode === "scale" ? "move" : gizmoMode) : gizmoMode}
 								snap={snapEnabled}
-								enabled={!planIsMain && !posing && !ikMode && !playMode}
+								enabled={!planIsMain && !posing && !ikMode && !playMode && !sculptMode}
 								paneRef={mainPaneRef}
 								camRef={lookThroughShot ? shotCamRef : editorCamRef}
 								shotAspect={lookThroughShot ? shotOutput.aspect : null}
@@ -7187,15 +7728,19 @@ export default function App() {
 								/>
 							)}
 							<ObjectPathHandles
-								path={selectedSceneObject?.path ?? null}
+								path={routeOwner?.path ?? null}
 								selectedIndex={pathPointIndex}
-								enabled={!preview && !lookThroughShot && !ikMode && !posing && !!selectedSceneObject?.path}
+								mode={gizmoMode}
+								enabled={!preview && !lookThroughShot && !ikMode && !posing && !!routeOwner?.path}
 								paneRef={mainPaneRef}
 								camRef={editorCamRef}
 								onSelect={setPathPointIndex}
-								onChangePoints={(points) => {
-									if (!selectedSceneObject) return;
-									changeSceneObject(selectedSceneObject.id, { path: points === null ? null : { ...selectedSceneObject.path, points } });
+								onChangePath={(patch) => {
+									if (!routeOwner) return;
+									// Inside the drag's own transaction, like the Top-View mark
+									// move: a plain update while the transaction is open is
+									// refused, so the dot never moved in the 3D view.
+									changeSceneObject(routeOwner.id, { path: patch === null ? null : { ...routeOwner.path, ...patch } }, pathDragTokenRef.current);
 								}}
 								onDragStart={() => {
 									pathDragTokenRef.current = beginSceneTransaction({ owner: "object-path", cancel: () => {} });
@@ -7246,6 +7791,7 @@ export default function App() {
 									baseY={activeChar.y ?? 0}
 									charScale={activeChar.scale ?? 1}
 									ikFocus={ikFocus}
+									activeTrackId={trailTrackFocus}
 									falloffFrames={trailFalloffFrames}
 									playheadFrame={tlFrame}
 									pendingEdit={trailEdit}
@@ -7264,10 +7810,11 @@ export default function App() {
 								shotCamRef={shotCamRef}
 								planCamRef={planCamRef}
 								poserCamRef={poserCamRef}
-								editorCamRef={editorCamRef}
-								// The studio hides the facing marks on screen; embeds show the
-								// scene as exported.
-								editorLook={!embedMode && !playgroundMode}
+								editorCamRef={sculptMode ? sculptCamRef : editorCamRef}
+								// The studio and the landing playground hide the facing marks on
+								// screen; the Workflow embed shows the scene as exported. Captures
+								// render outside this loop and keep them everywhere.
+								editorLook={!embedMode}
 								ikMode={ikMode}
 								planIsMain={planIsMain}
 								// Preview IS PlayView's render path: DualRender tests this branch
@@ -7276,7 +7823,7 @@ export default function App() {
 								// shot camera in the editing draw instead.
 								playMode={preview}
 								lookThrough={lookThroughShot}
-								insetCollapsed={workspaceLayout.insetCollapsed || workflowMode === "motion" || workflowMode === "pose"}
+								insetCollapsed={workspaceLayout.insetCollapsed || workflowMode === "motion" || workflowMode === "pose" || workflowMode === "sculpt"}
 								planZoom={workspaceLayout.planZoom}
 								shotAspect={shotOutput.aspect}
 							/>
@@ -7381,18 +7928,6 @@ export default function App() {
 							<span className="vp-inset-tag vp-shot-preview-tag">
 								<span className="vp-rec-dot" aria-hidden="true" />
 								{ko("Shot", "샷")}
-								<button
-									type="button"
-									className={"vp-guide-cycle" + (guideMode === "off" ? "" : " on")}
-									aria-label={ko("Cycle composition guides", "구도 가이드 전환")}
-									title={ko(GUIDE_LABELS[guideMode].en, GUIDE_LABELS[guideMode].ko) + ko(" · click to cycle", " · 클릭으로 전환")}
-									onClick={() => runStudioAction("view.setGuideMode", { mode: nextGuideMode(guideMode) })}
-								>
-									<svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
-										<path d="M3 3h18v18H3z" />
-										<path d="M9 3v18M15 3v18M3 9h18M3 15h18" />
-									</svg>
-								</button>
 								<button
 									type="button"
 									className="vp-look-through"
@@ -7475,9 +8010,9 @@ export default function App() {
 						setProjectBrowserOpen(false);
 						void openStarterScene(id, "starter", name);
 					}}
-					onNew={() => {
+					onNew={(name, options) => {
 						setProjectBrowserOpen(false);
-						requestNewProject();
+						requestNewProject(false, options);
 					}}
 					onClose={() => {
 						setProjectBrowserOpen(false);
@@ -7495,7 +8030,7 @@ export default function App() {
 					else newProject(name);
 				}}
 			/>
-			<FirstSuccessGuide open={firstSuccessGuideOpen} onDismiss={() => setFirstSuccessGuideOpen(false)} />
+			<FirstSuccessGuide open={firstSuccessGuideOpen} previsMode={scenesDomain.previsMode} onDismiss={() => setFirstSuccessGuideOpen(false)} />
 			<UseCaseQuestion
 				open={useCaseAskOpen}
 				isKo={isKo}