cozyclay 3.0.2 → 3.1.0

package/src/App.jsx

@@ -42,7 +42,6 @@ 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 { StudioProtocolError } from "./studio-agent-protocol.js";
@@ -120,9 +119,6 @@ import {
 import ProjectBrowser, { ProjectNameDialog } from "./project-browser.jsx";
 import FirstSuccessGuide from "./first-success-guide.jsx";
 import UseCaseQuestion from "./use-case-question.jsx";
-import { CameraTutorial } from "./camera-tutorial.jsx";
-import { createTutorialAnalytics } from "./tutorial-analytics.js";
-import { cameraTutorialSuppressed, createFirstShotHandoff, rememberCameraTutorialTerminal } from "./first-shot-handoff.js";
 import ObjectGizmo from "./object-gizmo.jsx";
 import { useHeldObjectEdit } from "./held-object-edit.jsx";
 
@@ -141,7 +137,7 @@ import {
 	pathMetrics,
 	strokeToPathPoints,
 } from "./object-path.js";
-import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { tutorialWalkSpec } from "./tutorial-walk.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx";
+import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx";
 import { routeOwnerFor } from "./route-owner.js";
 import {
 	analyticsActive,
@@ -157,7 +153,7 @@ import {
 } from "./analytics.js";
 import { ko, isKo } from "./locale.js";
 import { characterCapabilities, kindRefusal, proxyFigureBounds } from "./character-kind.js";
-import { STARTER_SCENES } from "./starter-scenes.js";
+import { STARTER_SCENES, resolveSceneParam } from "./starter-scenes.js";
 import { PART_COLOURS } from "./part-colours.js";
 import {
 	DEFAULT_POSE,
@@ -217,11 +213,14 @@ import {
 	shotAtFrame,
 	shotIndexAtFrame,
 } from "./cuts.js";
+import { playbackFrame } from "./motion/playback-frame-store.js";
+import { usePlaybackSubjectPosition } from "./motion/playback-subject.js";
+import { characterGizmoObject as buildCharacterGizmoObject, characterGizmoView, followCameraActive, playbackSceneWithTrack, updateShotMetrics } from "./stage-gizmo.js";
 import {
 	CameraGlide,
 	CameraRailScenePreview,
 	CaptureRig,
-	Character,
+	PlaybackCharacter,
 	ContextLossGuard,
 	CraneHandles,
 	DEFAULT_CAMERA_POSITION,
@@ -381,35 +380,9 @@ export default function App() {
 		getBus: () => studioBindingRef.current.bus,
 		notify: (...args) => setToast(...args),
 	}));
-	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]);
-	useEffect(() => {
-		const onTutorial = (event) => {
-			if (event.detail?.open === false) {
-				setCameraTutorial(false);
-				cameraTutorialAnalytics.current?.dismiss();
-				rememberCameraTutorialTerminal(cameraTutorialCompletedRef.current ? "completed" : "dismissed");
-				tutorialProjectEpochRef.current += 1;
-				setTutorialSeedPending(false);
-				setCameraTutorialHandoff(null);
-				return;
-			}
-			if (scenesDomain.previsMode === "storyboard") return;
-			void startCameraTutorialRef.current?.({ source: event.detail?.source ?? "settings" });
-		};
-		window.addEventListener("cozyclay:camera-tutorial", onTutorial);
-		return () => window.removeEventListener("cozyclay:camera-tutorial", onTutorial);
-	}, []);
-	useEffect(() => {
-		if (cameraTutorial) trackFeature("camera_tutorial");
-	}, [cameraTutorial]);
+	const { embedMode, playgroundMode } = useEmbedBridge();
+	const exportMenuTriggerRef = useRef(null);
+	const exportShotIdRef = useRef(null);
 	useEffect(() => {
 		if (!embedMode) return undefined;
 		// The Workflow page's Scene node embeds the studio as its preview, so the
@@ -472,7 +445,7 @@ export default function App() {
 	if (!firstEditRef.current) {
 		const firstEdit = createFirstEditTracker(track);
 		// Observe the existing semantic boundary once, even after its telemetry
-		// gate is satisfied. The tutorial/semantic hook itself stays unchanged.
+		// gate is satisfied. The semantic hook itself stays unchanged.
 		firstEditRef.current = (surface, domain, before, after) => {
 			if (before !== after) sceneRevisionRef.current += 1;
 			studioBindingRef.current?.invalidate(domain, before, after);
@@ -493,8 +466,6 @@ export default function App() {
 	// One semantic hook for authored UI and programmatic mutations. Passive
 	// setters intentionally bypass it (navigation, load, seed, restore, history).
 	const markSemanticEdit = (domain, before, after) => {
-		tutorialProjectEpochRef.current += 1;
-		if (tutorialSeedEpochRef.current !== null) setTutorialSeedPending(false);
 		return firstEditRef.current(playgroundMode ? "playground" : "craft", domain, before, after);
 	};
 	const craftActionTrackedRef = useRef(false);
@@ -506,31 +477,11 @@ export default function App() {
 		track(playgroundMode ? "playground:first_action" : "craft:first_action", { action_kind: actionKind });
 	};
 	useEffect(() => {
-		if (!playgroundMode) return undefined;
+		if (!playgroundMode) return;
 		track("playground:opened");
 		// The landing page keeps a loading veil over the iframe until the
 		// studio has actually mounted; a bare `load` fires far too early.
 		window.parent?.postMessage({ type: "cozyclay:playground-ready" }, "*");
-		// Camera gestures feed the landing page's tutorial checklist, and the
-		// checklist points back at one control (the shot look-through) by hint.
-		const onNav = (event) => window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: event.detail?.kind, key: event.detail?.key ?? null }, "*");
-		const onSignal = (event) => window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: event.detail?.kind }, "*");
-		window.addEventListener("cozyclay:playground-signal", onSignal);
-		const onHint = (event) => {
-			if (event.source !== window.parent || event.origin !== window.location.origin) return;
-			if (event.data?.type === "cozyclay:playground-hint") setPlaygroundHint(typeof event.data.kind === "string" ? event.data.kind : null);
-			if (event.data?.type === "cozyclay:playground-export") {
-				// The visitor keeps what they made: the landing page turns this
-				// into a .cclayproject download they can open after npx cozyclay.
-				playgroundExportRef.current?.("City Block").then(
-					(serialized) => window.parent?.postMessage({ type: "cozyclay:playground-export-result", serialized }, "*"),
-					(error) => window.parent?.postMessage({ type: "cozyclay:playground-export-result", error: String(error?.message ?? error) }, "*"),
-				);
-			}
-		};
-		window.addEventListener("cozyclay:nav", onNav);
-		window.addEventListener("message", onHint);
-		return () => { window.removeEventListener("cozyclay:nav", onNav); window.removeEventListener("cozyclay:playground-signal", onSignal); window.removeEventListener("message", onHint); };
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, []);
 	const [startup] = useState(loadSceneStartup);
@@ -649,26 +600,11 @@ 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);
+	// Playback ticks stay outside React; stopping commits the live frame back to
+	// the edit-time state so exports and agent reads see the stopped frame.
 	useEffect(() => {
 		if (playgroundMode && tlPlaying) window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: "play" }, "*");
 	}, [playgroundMode, tlPlaying]);
@@ -684,9 +620,6 @@ export default function App() {
 	// The Workflow page embeds this Studio as the Scene node's preview; that
 	// preview must show what the node captures on Run: the shot camera's view.
 	const [lookThroughShot, setLookThroughShot] = useState(embedMode);
-	useEffect(() => {
-		if (playgroundMode && lookThroughShot) window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: "shot" }, "*");
-	}, [playgroundMode, lookThroughShot]);
 	useEffect(() => {
 		if (!lookThroughShot || embedMode) return undefined;
 		const onKey = (event) => {
@@ -1135,7 +1068,8 @@ export default function App() {
 		get motionFullRef() { return motionFullRef; },
 		get poseMemberAtFrame() { return poseMemberAtFrame; },
 		get posedRig() { return posedRig; },
-		get poserCamRef() { return poserCamRef; },
+		// Pose mode enters from the view the author is looking through (motion.js toggleIkMode).
+		get poserCamRef() { return poserCamRef; }, get editorCamRef() { return editorCamRef; }, get editorLook() { return editorLook; },
 		get poserLook() { return poserLook; },
 		get posing() { return posing; },
 		get posingChar() { return posingChar; },
@@ -1163,9 +1097,9 @@ export default function App() {
 		get tlFrame() { return tlFrame; },
 		get tlFrameCount() { return tlFrameCount; },
 		get tlFrameRef() { return tlFrameRef; },
+		get propFrameRef() { return propFrameRef; },
 		
 		
-		get tutorialProjectEpochRef() { return tutorialProjectEpochRef; },
 		get waitForRig() { return waitForRig; },
 		get waypointMode() { return waypointMode; },
 		get waypoints() { return waypoints; },
@@ -1392,7 +1326,6 @@ export default function App() {
 	const scenesDomain = useScenes(appContext.forRender({
 		get activeSceneIdRef() { return activeSceneIdRef; },
 		get actorStageRef() { return actorStageRef; },
-		get cameraTutorialQuery() { return cameraTutorialQuery; },
 		get customPoses() { return customPoses; },
 		get dirtyRef() { return dirtyRef; },
 		get exportShotIdRef() { return exportShotIdRef; },
@@ -1414,8 +1347,6 @@ export default function App() {
 		get saveFailureToastRef() { return saveFailureToastRef; },
 		get setActiveCharacterId() { return setActiveCharacterId; },
 		get setActiveWaypointId() { return setActiveWaypointId; },
-		get setCameraTutorial() { return setCameraTutorial; },
-		get setCameraTutorialHandoff() { return setCameraTutorialHandoff; },
 		get setFirstSuccessGuideOpen() { return setFirstSuccessGuideOpen; },
 		get setHasCharSheet() { return setHasCharSheet; },
 		get setMovePlaying() { return setMovePlaying; },
@@ -1428,7 +1359,6 @@ export default function App() {
 		get setShots() { return setShots; },
 		get setTlFrame() { return setTlFrame; },
 		get setTlFrameCount() { return setTlFrameCount; },
-		get setTutorialSeedPending() { return setTutorialSeedPending; },
 		get setWaypoints() { return setWaypoints; },
 		get setWorkspaceLayout() { return setWorkspaceLayout; },
 		get shotDocumentRef() { return shotDocumentRef; },
@@ -1439,9 +1369,6 @@ export default function App() {
 		get studioDocumentEpochRef() { return studioDocumentEpochRef; },
 		get studioHistoryRef() { return studioHistoryRef; },
 		get studioSceneEpochRef() { return studioSceneEpochRef; },
-		get tutorialProjectEpochRef() { return tutorialProjectEpochRef; },
-		get tutorialSeedEpochRef() { return tutorialSeedEpochRef; },
-		get tutorialStarterRef() { return tutorialStarterRef; },
 		get castDomain() { return castDomain; },
 		get objectsDomain() { return objectsDomain; },
 	}));
@@ -1821,11 +1748,6 @@ export default function App() {
 	const [mode, setMode] = useState("image");
 	const [imageModel, setImageModel] = useState("gpt_image_2");
 
-	useEffect(() => {
-		if (playgroundMode && movePlaying) window.parent?.postMessage({ type: "cozyclay:playground-nav", kind: "play" }, "*");
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [playgroundMode, movePlaying]);
-
 	// 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);
@@ -1843,9 +1765,9 @@ export default function App() {
 	// The frame props follow. Live playback keeps it at the playhead; the
 	// offscreen export drives it per captured frame without re-rendering.
 	const propFrameRef = useRef(0);
-
 	const [cameraPos, setCameraPos] = useState(DEFAULT_CAMERA_POSITION);
 	const [subjectVisible, setSubjectVisible] = useState(true);
+	const subjectVisibleRef = useRef(true);
 	const mcpCaptureRef = useRef(null);
 	const liveControlRef = useRef(null);
 	const [liveWorkspaceHandle, setLiveWorkspaceHandle] = useState(null);
@@ -2058,7 +1980,11 @@ export default function App() {
 	}
 
 
-	const renderActive = useRenderActivity(tlPlaying || movePlaying);
+	const renderActive = useRenderActivity(tlPlaying || movePlaying, { playing: tlPlaying, commit: shotsDomain.commitPlaybackFrame, onStop: () => {
+		const position = shotCameraPosRef.current;
+		if (position) setCameraPos(position);
+		setSubjectVisible(subjectVisibleRef.current);
+	} });
 	 // the clip length on the production clock
 
 	// Keep the imperative frame in step with the playhead for live playback;
@@ -2348,96 +2274,18 @@ export default function App() {
 		};
 	}, []);
 
-	const tutorialInitialSnapshotRef = useRef(null);
-	if (tutorialInitialSnapshotRef.current === null) tutorialInitialSnapshotRef.current = collectProjectSnapshot("Tutorial");
-
-	playgroundExportRef.current = collectProjectSerialized;
-
-	function closeCameraTutorial(reason = null) {
-		const terminal = reason ?? (cameraTutorialCompletedRef.current ? "completed" : "dismissed");
-		rememberCameraTutorialTerminal(terminal);
-		tutorialProjectEpochRef.current += 1;
-		setTutorialSeedPending(false);
-		cameraTutorialHandoff?.dismiss();
-		setCameraTutorialHandoff(null);
-		cameraTutorialAnalytics.current?.dismiss();
-		cameraTutorialAnalytics.current = null;
-		cameraTutorialCompletedRef.current = false;
-		setCameraTutorial(false);
-		setCameraTutorialStep(null);
-	}
-
-	function openExportMenuForShot(shotId) {
-		const target = shots.find((entry) => entry.id === shotId);
-		if (!target) return;
-		exportShotIdRef.current = target.id;
-		const trigger = exportMenuTriggerRef.current;
-		if (trigger) {
-			const box = trigger.getBoundingClientRect();
-			const menuWidth = Math.min(340, window.innerWidth - 16);
-			setExportMenuAnchor({
-				top: box.bottom + 6,
-				right: Math.min(Math.max(8, window.innerWidth - box.right), Math.max(8, window.innerWidth - menuWidth - 8)),
-			});
-		}
-		setExportMenuOpen(true);
-		cameraTutorialHandoff?.dismiss();
-		setCameraTutorialHandoff(null);
-	}
-
-	/** The camera tutorial's single entry (#209), for both /app/?tutorial=camera
-	 * and the Settings ▾ item.
-	 *
-	 * The seven steps teach Shot / Rail / Play, which need a set and somebody
-	 * moving through it. On cozyclay.org they get both for free: the landing
-	 * playground opens the city-block starter and the hosted-demo seed below
-	 * loads the walk take because a statically served build has no motion
-	 * bridge. A local session HAS a bridge, so that seed is skipped and the
-	 * tutorial used to open on whatever was loaded — usually an empty room.
-	 * This puts the studio in the landing page's state explicitly. */
-	async function startCameraTutorial({ source = "settings" } = {}) {
-		if (embedMode || playgroundMode || tutorialLoadingRef.current) return;
-		// QA hook, same spirit as window.__cozyclayRenders: which door the tutorial
-		// came in by, so a headless run can prove both of them land here.
-		window.__cozyclayTutorialSource = source;
-		// Only a pristine, newly created document receives the sample. An
-		// existing project (even unnamed), or a restart, keeps all current work.
-		const seed = !tutorialStarterRef.current && startupCreatedScene && projectName === null
-			&& !projectDirty && !cameraTutorialSuppressed()
-			&& tutorialInitialSnapshotRef.current === collectProjectSnapshot("Tutorial");
-		if (seed) {
-			tutorialLoadingRef.current = true;
-			try {
-				const opened = await openStarterScene("city-block", "tutorial");
-				if (opened) {
-					tutorialStarterRef.current = true;
-					tutorialSeedEpochRef.current = tutorialProjectEpochRef.current;
-					setTutorialSeedPending(true);
-					exitPreview();
-					setTlFrame(0);
-				}
-			} finally {
-				tutorialLoadingRef.current = false;
-			}
-		}
-		setProjectStartupOpen(false);
-		setFirstSuccessGuideOpen(false);
-		setCameraTutorialHandoff(createFirstShotHandoff());
-		// Explicit start, including while already open, resets the existing
-		// done/walked component state. Passive renders never create an attempt.
-		cameraTutorialAnalytics.current = createTutorialAnalytics({ surface: "studio", startSource: source });
-		setCameraTutorialAttempt((attempt) => attempt + 1);
-		setCameraTutorial(true);
-		cameraTutorialCompletedRef.current = false;
-	}
-	startCameraTutorialRef.current = startCameraTutorial;
-
 	const starterOpened = useRef(false);
 	useEffect(() => {
 		if (starterOpened.current || playgroundMode) return;
 		const requested = new URLSearchParams(globalThis.location?.search || "").get("scene");
 		if (!requested) return;
 		starterOpened.current = true;
+		// An id this build does not ship (a removed starter, a typo) is ignored:
+		// the studio opens as it would without ?scene=.
+		if (!resolveSceneParam(requested)) {
+			console.warn(`cozyclay: ?scene=${requested} is not a starter scene in this build; ignored.`);
+			return;
+		}
 		void openStarterScene(requested, "launch");
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, []);
@@ -2731,6 +2579,8 @@ export default function App() {
 		});
 		return [{
 			id: entry.id,
+			entry,
+			clip,
 			model: entry.model,
 			...(isProxyFigure(entry) ? {} : { url: characterModelUrl(entry.model) }),
 			position: [placement.x, entry.y ?? 0, placement.z],
@@ -2754,33 +2604,14 @@ export default function App() {
 	// character so the motion tab keeps working, but a move gizmo hanging in
 	// the viewport while the camera or a prop is selected reads as a stray
 	// widget.
-	const gizmoView = useMemo(() => {
-		if (!charIdFromHierarchyId(selectedHierarchyId)) return null;
-		const entry = characters.find((item) => item.id === activeChar.id);
-		if (!entry || entry.hidden) return null;
-		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]);
+	const gizmoView = characterGizmoView({
+		selected: Boolean(charIdFromHierarchyId(selectedHierarchyId)), characters, activeCharacterId,
+		activeCharacter: activeChar, motion, shots, activeId: activeChar.id, frame: tlFrame,
+	});
 	// 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.
-	const characterGizmoObject = useMemo(() => {
-		if (!gizmoView) return null;
-		const entry = characters.find((item) => item.id === activeChar.id);
-		return {
-			id: "__character__",
-			x: gizmoView.position[0],
-			y: gizmoView.position[1],
-			z: gizmoView.position[2],
-			height: 1.15,
-			footprint: { width: 0.6, depth: 0.6 },
-			rotY: gizmoView.rot ?? entry?.rot ?? 0,
-			scaleX: entry?.scale ?? 1,
-			scaleY: entry?.scale ?? 1,
-			scaleZ: entry?.scale ?? 1,
-		};
-	}, [gizmoView, characters, activeChar.id]);
+	const characterGizmoObject = buildCharacterGizmoObject(gizmoView, characters.find((item) => item.id === activeChar.id));
 
 	/* --------------------- per-character layer buffers ---------------------
 	 * waypoints / motion above are the EDITING BUFFER of the
@@ -3263,16 +3094,6 @@ export default function App() {
 		);
 	}
 
-	// Observe the existing export UI boundary, independently of telemetry.
-	// The first transition covers ordinary menu exports and fast failures too;
-	// progress updates do not write storage on every encoded frame.
-	const hasExportAttempt = exportStatus !== null;
-	useEffect(() => {
-		if (!hasExportAttempt) return;
-		rememberCameraTutorialTerminal("export_started");
-		setCameraTutorialHandoff(null);
-	}, [hasExportAttempt]);
-
 	function downloadOtioCutList() {
 		if (!shots.length) {
 			setToast(ko("Add at least one Shot before exporting OTIO", "OTIO를 내보내려면 샷을 하나 이상 추가하세요"));
@@ -3772,22 +3593,6 @@ export default function App() {
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, []);
 
-	// The camera tutorial's seed (#209). startCameraTutorial arms
-	// tutorialSeedPending once the starter scene is applied, and a compiled walk
-	// (take v3) goes on as soon as that scene's character has a parsed rig: a
-	// state condition, not a timer. The compile runs in the worker; an edit that lands
-	// before it answers makes the job's fence refuse the install (set dressing, no error).
-	useEffect(() => {
-		if (!tutorialSeedPending || !activeRig) return;
-		const seedEpoch = tutorialSeedEpochRef.current;
-		tutorialSeedEpochRef.current = null;
-		setTutorialSeedPending(false);
-		if (seedEpoch === null || seedEpoch !== tutorialProjectEpochRef.current) return;
-		const spec = tutorialWalkSpec(activeChar); // the take is set dressing, never an error to act on
-		if (spec && runStudioAction("motion.compile", { characterId: activeChar.id, spec })) { setTlFrame(0); setTlPlaying(false); }
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [tutorialSeedPending, activeRig]);
-
 	// Drive every cast member from ITS OWN clip on the shared playhead. The
 	// active character's buffer motion and the stored session motions of the
 	// others all advance together; characters without a clip keep their pose.
@@ -3868,7 +3673,7 @@ export default function App() {
 	// (test/motion3/qa-motion3-*-browser.mjs). Harmless in normal use.
 	useEffect(() => {
 	window.__cozyclay = {
-			runStudioAction, setFrame: setTlFrame,
+			runStudioAction, setFrame: setTlFrame, setPlaying: setTlPlaying,
 			rigA: activeRig, motion, tlFrame, frameCount: tlFrameCount, playing: tlPlaying, ikMode, ikChains, ikFocus, contactRadii: ikChains?.values().next().value?.contactRadii ?? null, ik: ikStateRef.current,
 			rangePins, rangePinResiduals,
 			rangePinApplySpec: motionDomain.rangePinApplySpec,
@@ -4050,11 +3855,7 @@ export default function App() {
 			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]);
+	const motionPos = usePlaybackSubjectPosition({ motion, subjectCarry, scene: playbackSceneBase, frame: tlFrame });
 
 	// The subject's full per-frame scene trajectory — what the follow camera
 	// is derived from. Without a loaded motion, and riding nothing, the subject
@@ -4075,11 +3876,7 @@ export default function App() {
 	// A rail shot with an aim holds its cast (or a world point) instead of the subject.
 	const followTrack = useShotCameraTracks({ shots, subjectTrack, subjectId: charA.id, fps: tlFps, yawDeg: charA.rot, filmback, characters, objects: sceneObjects, frameCount: tlFrameCount, activeId: activeChar.id, motion });
 
-	const playbackScene = useMemo(() => ({
-		...playbackSceneBase,
-		subjectTrack,
-		cameraTrack: followTrack,
-	}), [playbackSceneBase, subjectTrack, followTrack]);
+	const playbackScene = useMemo(() => playbackSceneWithTrack(playbackSceneBase, subjectTrack, followTrack), [playbackSceneBase, subjectTrack, followTrack]);
 
 	// Browser acceptance seam: it invokes the exact production exporter but
 	// suppresses the download, returning only serializable evidence.
@@ -4120,8 +3917,7 @@ export default function App() {
 
 	// The follow camera owns the shot camera in the same situations key
 	// following would: never while an authoring mode holds the viewport.
-	const followCamActive =
-		activeCamera.mode !== "keys" && !!followTrack?.[tlFrame] && (preview || (!ikMode && !waypointMode && !posing));
+	const followCamActive = followCameraActive(activeCamera.mode, followTrack, tlPlaying ? playbackFrame() : tlFrame, preview, ikMode, waypointMode, posing);
 
 	// Implied locomotion speed per authored segment, on the timeline clock
 	// (m/s is physical, so the judge always uses tlFps). Shown in the
@@ -4824,7 +4620,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-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}
+		<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-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) => {
@@ -4843,26 +4639,6 @@ export default function App() {
 					</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
-					    (styles.css) — every step is completed in the studio underneath. */}
-					{cameraTutorial && !embedMode && (
-						<CameraTutorial
-							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}
-							onComplete={() => { cameraTutorialCompletedRef.current = true; cameraTutorialHandoff?.complete(); }}
-							onClose={() => closeCameraTutorial()}
-							handoff={cameraTutorialHandoff}
-							shotId={activeShot?.id ?? null}
-							onOpenExport={openExportMenuForShot}
-							onContinue={() => closeCameraTutorial()}
-						/>
-					)}
 					<div className="stage" id="stage" ref={stageRef} data-render-loop={renderActive ? "always" : "demand"}>
 						{/* Shadows were off, so every castShadow in props.jsx was inert and
 						    nothing on the open stage ever touched the floor. A contact
@@ -4998,7 +4774,10 @@ export default function App() {
 									take={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }}
 									registryRef={carrierRegistryRef}
 								>
-									<Character
+									<PlaybackCharacter
+										entry={view.entry}
+										clip={view.clip}
+										shots={shots}
 										url={view.url}
 										{...{ model: view.model, posture: view.posture }}
 										position={view.position}
@@ -5055,19 +4834,10 @@ export default function App() {
 								charA={charA}
 								charB={charB}
 								showB={showB}
-								probeX={motionPos ? motionPos.x : charA.x}
-								probeZ={motionPos ? motionPos.z : charA.z}
+								probe={{ scene: playbackSceneBase, frameRef: propFrameRef, carry: subjectCarry }}
 								camRef={shotCamRef}
 								look={look}
-								onMetrics={(p, visible) => {
-									shotCameraPosRef.current = { x: p.x, y: p.y, z: p.z };
-									setCameraPos((prev) =>
-										Math.abs(prev.x - p.x) + Math.abs(prev.y - p.y) + Math.abs(prev.z - p.z) > 1e-4
-											? { x: p.x, y: p.y, z: p.z }
-											: prev,
-									);
-									setSubjectVisible((prev) => (prev === visible ? prev : visible));
-								}}
+								onMetrics={(p, visible) => updateShotMetrics({ position: p, visible, playing: tlPlaying, setCameraPos, setSubjectVisible, cameraRef: shotCameraPosRef, visibleRef: subjectVisibleRef })}
 							/>
 							<MoveRig
 								playing={movePlaying}
@@ -5148,11 +4918,10 @@ export default function App() {
 								target={rangePinPreview?.target}
 								enabled={ikMode && ikEditTool === "pin" && Boolean(rangePinPreview?.target)}
 							/>
-							{/* The tutorial's top view is the landing playground's: camera, cast
-							    and the rail only, so the line the Rail step asks for is drawn on
-							    a clean floor instead of over 34 footprints. */}
+							{/* The landing playground's top view: camera, cast and the rail
+							    only, so a rail is drawn on a clean floor. */}
 							<PlanBoard
-								minimal={playgroundMode || cameraTutorial}
+								minimal={playgroundMode}
 								hostRef={planHostRef}
 								planCamRef={planCamRef}
 								shotCamRef={shotCamRef}
@@ -5447,7 +5216,7 @@ export default function App() {
 
 						<div
 							ref={shotPreviewRef}
-							hidden={playMode || ikMode || lookThroughShot || workflowMode === "motion"}
+							hidden={playMode || lookThroughShot}
 							className="vp-pane vp-shot-preview"
 							style={{ "--shot-aspect": shotOutput.aspect }}
 						>