cozyclay 2.0.0 → 2.1.0

package/src/domains/objects.js

@@ -20,9 +20,15 @@ import {
 	duplicateCutoutOptions,
 	MESH_KIND,
 	duplicateMeshOptions,
+	createSculptObject,
+	duplicateSculptOptions,
+	SCULPT_KIND,
 	objectSize,
 	setSceneObjectAttach,
 	setSceneObjectParent,
+	rigidMotionBetween,
+	carryPointByMotion,
+	tidyAngle,
 } from "../scene-objects.js";
 
 import { ko, isKo } from "../locale.js";
@@ -41,6 +47,7 @@ import { importMeshFile, compressedGlbReason, meshBoundsFromAsset, fitMeshBounds
 import { cutOutBackground, maskAsset } from "../matte.js";
 import { parseRigNodeId } from "../hierarchy-model.js";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
+import { assetDataUrl, sculptPlacement } from "../sculpt-mode.js";
 
 // A stable owner across scene loads. App's remaining native history readers use
 // the small store facade below; authored writes are owned by the document store.
@@ -55,12 +62,50 @@ export function createObjectsDomain(appContext, initial) {
 	};
 	const read = () => documentStore.read("objects");
 	function write(update) {
-		return documentStore.write("objects", before => {
+		let moved = null;
+		const result = documentStore.write("objects", before => {
 			let next = typeof update === "function" ? update(before) : update;
 			for (const row of next.filter(row => row.remove === true)) next = removeSceneObject(next, row.id);
 			if (JSON.stringify(next) === JSON.stringify(before)) return before;
+			moved = { before, next };
 			return next;
 		});
+		if (moved) carryGroupedCharacters(moved.before, moved.next);
+		return result;
+	}
+	/** Characters grouped under an object ride it while authoring too: whatever
+	 * motion an object took in this write (its own move or turn, or carried with
+	 * its group), the characters under it take the same. A pure move shifts
+	 * them by the same translation. A turn orbits them about the object's pivot
+	 * (position by the object's Δ, like any carried child) and adds the yaw
+	 * part of Δ to their facing — a character has only a yaw, so the pitch or
+	 * roll of its parent moves where it stands and never tips it over.
+	 * Joined to the open action, so one undo puts back the object and the
+	 * riders together. */
+	function carryGroupedCharacters(before, next) {
+		const cast = appContext.storeDomain("cast");
+		if (!cast) return;
+		const was = new Map(before.map(row => [row.id, row]));
+		const shifts = new Map();
+		const turns = new Map();
+		for (const row of next) {
+			const prior = was.get(row.id);
+			if (!prior || row.attach || prior.attach) continue;
+			const turn = rigidMotionBetween(prior, row);
+			if (turn) { turns.set(row.id, turn); continue; }
+			const shift = { x: row.x - prior.x, y: (row.y ?? 0) - (prior.y ?? 0), z: row.z - prior.z };
+			if (shift.x || shift.y || shift.z) shifts.set(row.id, shift);
+		}
+		if (!(shifts.size || turns.size) || !cast.read().some(entry => shifts.has(entry.parent) || turns.has(entry.parent))) return;
+		appContext.recordAction("cast", () => cast.write(rows => rows.map(entry => {
+			const turn = turns.get(entry.parent);
+			if (turn) {
+				const at = carryPointByMotion({ x: entry.x, y: entry.y ?? 0, z: entry.z }, turn);
+				return { ...entry, x: at.x, y: Math.max(0, at.y), z: at.z, rot: tidyAngle((entry.rot ?? 0) + turn.yaw) };
+			}
+			const shift = shifts.get(entry.parent);
+			return shift ? { ...entry, x: entry.x + shift.x, y: Math.max(0, (entry.y ?? 0) + shift.y), z: entry.z + shift.z } : entry;
+		})), null, true);
 	}
 	const publish = () => { if (appContext.live.state) appContext.patchLive({ objects: read() }); };
 	const unsubscribe = documentStore.subscribe(publish);
@@ -242,6 +287,10 @@ export function useObjects(appContext) {
 
 	const [gizmoMode, setGizmoMode] = useState("move");
 
+	// An Empty is nothing but its name: the moment one is made, its Outliner
+	// row opens for naming (a nonce, so a second Empty re-opens it).
+	const [renameRequest, setRenameRequest] = useState(null);
+
 	// Snap is a preference, not a law: with it on the gizmo blocks on the plan
 	// board's grid, and Ctrl/Cmd during a drag gives a free one. Off, it is the
 	// other way round. (docs/unity-reference.md §9.5)
@@ -255,10 +304,11 @@ export function useObjects(appContext) {
 		const placement = at ?? (camera
 			? placementInFront({ x: camera.position.x, z: camera.position.z }, paneYaw)
 			: {});
-		const receipt = run("object.add", { kind, placement });
+		const receipt = run("object.add", { kind, placement, first: true });
 		const object = domain.read().find(row => row.id === receipt.affectedIds[0]);
 		appContext.shared.markCraftAction("object");
 		appContext.shared.setSelectedHierarchyId(`object:${object.id}`);
+		if (object.renderer === "empty") setRenameRequest({ id: `object:${object.id}`, nonce: Date.now() });
 		// Deliberate divergence from Unity's rename-on-create: creating an object
 		// here is followed by placing it, and dropping focus into a text field
 		// swallows the very next W/E/R. Renaming stays on F2/Return and the row's
@@ -385,6 +435,25 @@ export function useObjects(appContext) {
 		}
 	}
 
+	/** Sculpt mode's Place in scene (#739): the sculpt stands on the ground in
+	 * front of the scene camera, where + Add puts a new object, and ends up
+	 * selected. One object.update, so one undo. */
+	function placeSculptInScene(id) {
+		const camera = (appContext.shared.lookThroughShot ? appContext.shared.shotCamRef : appContext.shared.editorCamRef).current;
+		const yaw = (appContext.shared.lookThroughShot ? appContext.shared.look : appContext.shared.editorLook).current.yaw;
+		const receipt = run("object.update", { id, patch: camera ? sculptPlacement(camera.position, yaw) : { y: 0 } });
+		appContext.shared.setSelectedHierarchyId(`object:${id}`);
+		return receipt;
+	}
+
+	/** A sculpt reference goes into the asset store like a cutout's picture;
+	 * the run reads it back as a data URL of the stored bytes. */
+	async function storeSculptReference(file) {
+		const prepared = await importImageFile(file);
+		const stored = await rememberAsset(prepared);
+		return { dataUrl: assetDataUrl(prepared), name: prepared.name || file.name || "reference", assetId: stored.id };
+	}
+
 	function placementInFrontOfShot() {
 		const camera = (appContext.shared.lookThroughShot ? appContext.shared.shotCamRef : appContext.shared.editorCamRef).current;
 		return camera
@@ -528,7 +597,9 @@ export function useObjects(appContext) {
 			? createCutoutObject(duplicateCutoutOptions(object), objects, placement)
 			: object.renderer === MESH_KIND
 				? createMeshObject(duplicateMeshOptions(object), objects, placement)
-				: createSceneObject(object.renderer, objects, placement);
+				: object.renderer === SCULPT_KIND
+					? createSculptObject(duplicateSculptOptions(object), objects, placement).object
+					: createSceneObject(object.renderer, objects, placement);
 		if (!copy) return;
 		// Unity drops the duplicate exactly on top of the original; for blocking,
 		// one grid step to the side means you can see that it worked.
@@ -548,6 +619,25 @@ export function useObjects(appContext) {
 		);
 	}
 
+	/** Outliner "Group under new Empty": the object's parent node, made on the
+	 * spot. One command, one write, so one undo takes back the Empty and the
+	 * reparent together. Selection follows the Empty, the new handle. */
+	function groupObjectUnderNewEmpty(id = selectedSceneObjectId) {
+		if (!id) return null;
+		try {
+			const receipt = run("object.groupUnderEmpty", { id });
+			const emptyId = receipt.affectedIds[0];
+			appContext.shared.setSelectedHierarchyId(`object:${emptyId}`);
+			setRenameRequest({ id: `object:${emptyId}`, nonce: Date.now() });
+			setGizmoMode("move");
+			appContext.notify(ko("Grouped under a new Empty", "빈 오브젝트로 묶었어요"));
+			return emptyId;
+		} catch (error) {
+			appContext.notify(error?.message || ko("Could not group this object", "이 오브젝트는 묶을 수 없어요"));
+			return null;
+		}
+	}
+
 	/** In-place rename commit from the hierarchy (F2 / Return / rename on
 	 * create). The row label lives in the tree; the object name is shared
 	 * state, so this is just the inspector's rename through another door. */
@@ -878,7 +968,9 @@ export function useObjects(appContext) {
 		// Grouping keeps its own rules (self, cycles, unknown ids) — asking the
 		// store is the only way to stay honest about them.
 		if (targetObjectId) return setSceneObjectParent(sceneObjects, id, targetObjectId) !== sceneObjects;
-		if (targetRowId === "props") return (object.attach ?? null) !== null || (object.parent ?? null) !== null;
+		// Props takes an object out of its group (or off a character) and lists
+		// it first, so the drop always shows; a top-level object moves up too.
+		if (targetRowId === "props") return (object.attach ?? null) !== null || (object.parent ?? null) !== null || sceneObjects[0]?.id !== id;
 		const attach = attachTargetForRow(targetRowId);
 		if (!attach) return false;
 		const current = object.attach ?? null;
@@ -894,6 +986,14 @@ export function useObjects(appContext) {
 		// group comes back to world numbers on the way, exactly as the Props
 		// row would put it back.
 		if (targetObjectId) return run("object.group", { parent: targetObjectId, children: [id] });
+		const object = sceneObjects.find((entry) => entry.id === id);
+		if (targetRowId === "props" && !object?.attach) {
+			// Out of its group and to the top of Props in one write (one undo):
+			// records are world-space, so clearing the parent moves nothing.
+			const rows = setSceneObjectParent(domain.read(), id, null);
+			const moved = rows.find((entry) => entry.id === id);
+			return run("objects.replace", { objects: [moved, ...rows.filter((entry) => entry.id !== id)] });
+		}
 		const attach = targetRowId === "props" ? null : attachTargetForRow(targetRowId);
 		appContext.shared.runStudioAction(attach ? "object.attach" : "object.detach", attach
 			? { objectId: id, characterId: attach.characterId, ...(attach.bone ? { bone: attach.bone } : {}) }
@@ -926,7 +1026,8 @@ export function useObjects(appContext) {
 		matteBrush, setMatteBrush, 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,
+		spawnMeshAt, applyMatte, duplicateSelectedSceneObject, frameSelection, groupObjectUnderNewEmpty, renameRequest, renameSceneObject,
 		sceneObjectWorldMatrix, attachTargetForRow, attachTargetLabel, attachSceneObject,
+		placeSculptInScene, storeSculptReference,
 	};
 }

package/src/domains/scenes.js

@@ -7,7 +7,7 @@ import {
 	readSceneDocument,
 	serializeSceneDocument,
 	SCENES_VERSION,
-	migrateStageFrames,
+	migrateScenesDocument as migrateToCurrentScenes,
 	activeSceneIndex,
 	createSceneDocument,
 	createSceneStage,
@@ -37,6 +37,9 @@ import {
 	requestHandlePermission,
 	createWorkflowGraph,
 	clearStoredProjectHandle,
+	DEFAULT_PREVIS_MODE,
+	normalizePrevisMode,
+	buildAnimationProjectFromStoryboard,
 } from "../project.js";
 import { playgroundSceneUrl, fetchSceneProject } from "../playground.js";
 import { openAssetDb, referencedAssetIds, getAsset, putAsset } from "../scene-assets.js";
@@ -45,7 +48,7 @@ import { encodeMotionResource } from "../motion-resources.js";
 import { openMotionDb, putMotion, sweepMotions } from "../motion-store.js";
 import { resourceManifest } from "../project-resources.js";
 import { isKo, ko } from "../locale.js";
-import { track, bucketCount, bucketProjectAge } from "../analytics.js";
+import { track, bucketCount, bucketProjectAge, startExportAttempt } from "../analytics.js";
 import { mergeProjectCustomPoses } from "../project-poses.js";
 import { DEFAULT_WORKSPACE_LAYOUT, DEFAULT_DURATION_S, TIMELINE_FPS } from "../app-stage.jsx";
 import { saveCustomPoses } from "../poses.js";
@@ -55,9 +58,11 @@ import { createIkState } from "../ardy/ik.js";
 
 // The scene list and project identity share one history. Dirty is derived from
 // the saved checkpoint, not an authored edit, and has its own non-history slice.
-export function createScenesDomain(appContext, initial, name) {
+// previsMode is project identity too: it is set only by a document boundary
+// (blank creation, starter/file open, session restore), never by an edit.
+function createScenesDomain(appContext, initial, name, previsMode = DEFAULT_PREVIS_MODE) {
 	const ordered = rows => rows.map((scene, order) => ({ ...scene, order }));
-	let native = createDocumentStore({ owned: { scenes: ordered(initial.scenes), project: { name, activeSceneId: initial.activeSceneId } } });
+	let native = createDocumentStore({ owned: { scenes: ordered(initial.scenes), project: { name, activeSceneId: initial.activeSceneId, previsMode: normalizePrevisMode(previsMode) } } });
 	const listeners = new Set();
 	const notify = () => { for (const listener of listeners) listener(); };
 	let release = native.subscribe(notify);
@@ -93,7 +98,7 @@ export function createScenesDomain(appContext, initial, name) {
 		appContext.publishScenes(read());
 		appContext.shared.activeSceneIdRef.current = metadata().activeSceneId;
 		if (appContext.live.state) appContext.patchLive({ scenes: read(), activeSceneId: metadata().activeSceneId });
-		storeProjectSession(metadata().name);
+		storeProjectSession(metadata().name, metadata().previsMode);
 		domain.persist?.();
 		domain.refreshDirty?.();
 	};
@@ -117,9 +122,9 @@ export function createScenesDomain(appContext, initial, name) {
 		},
 		// Session cache/file loads are explicit non-authored boundaries. They
 		// retire scene history, just as opening a scene retired native history.
-		replaceDocument(scenes, activeSceneId, name = metadata().name) {
+		replaceDocument(scenes, activeSceneId, name = metadata().name, previsMode = metadata().previsMode) {
 			release(); native.dispose();
-			native = createDocumentStore({ owned: { scenes: ordered(scenes), project: { name, activeSceneId } } });
+			native = createDocumentStore({ owned: { scenes: ordered(scenes), project: { name, activeSceneId, previsMode: normalizePrevisMode(previsMode) } } });
 			release = native.subscribe(notify); notify();
 		},
 		setDirty(value) {
@@ -135,9 +140,13 @@ export function createScenesDomain(appContext, initial, name) {
 }
 
 export function useScenes(appContext) {
-	const [domain] = useState(() => appContext.storeDomain("scenes") ?? createScenesDomain(appContext, appContext.shared.startup.document, loadProjectSession()?.name ?? null));
+	const [domain] = useState(() => {
+		if (appContext.storeDomain("scenes")) return appContext.storeDomain("scenes");
+		const session = loadProjectSession();
+		return createScenesDomain(appContext, appContext.shared.startup.document, session?.name ?? null, session?.previsMode);
+	});
 	const scenes = useDocumentDomain(domain.documentStore, "scenes");
-	const { activeSceneId, name: projectName } = useDocumentDomain(domain.documentStore, "project");
+	const { activeSceneId, name: projectName, previsMode } = useDocumentDomain(domain.documentStore, "project");
 	const projectDirty = useDocumentDomain(domain.dirtyStore, "projectDirty");
 	const runtimeValues = useRef(new Map());
 	async function runProject(id, args = {}) {
@@ -185,8 +194,7 @@ export function useScenes(appContext) {
 		}
 	}
 
-	/* ============================ project files ============================
-	 * Game-engine workflow: the authoring state (scenes + cast + layers,
+	/* Game-engine workflow: the authoring state (scenes + cast + layers,
 	 * workspace layout, custom poses) round-trips through a real
 	 * `.cclayproject` file. localStorage stays as the always-on session
 	 * cache; the file is the portable, user-owned document. */
@@ -222,6 +230,7 @@ export function useScenes(appContext) {
 			customPoses: appContext.shared.projectStateRef.current.customPoses,
 			workflow: loadWorkflowGraph(),
 			name,
+			previsMode: domain.metadata().previsMode,
 		};
 	}
 
@@ -296,7 +305,7 @@ export function useScenes(appContext) {
 		appContext.shared.projectSnapshotRef.current = snapshot;
 		if (domain.metadata().name === previousName) domain.nameSaved(name);
 		refreshProjectDirty();
-		storeProjectSession(domain.metadata().name);
+		storeProjectSession(domain.metadata().name, domain.metadata().previsMode);
 	}
 
 	function projectProblemsNotice(problems) {
@@ -391,6 +400,40 @@ export function useScenes(appContext) {
 		}
 	}
 
+	async function exportAsAnimationProject(context) {
+		if (domain.metadata().previsMode !== "storyboard") return { saved: false, failure: "not-storyboard" };
+		const attempt = startExportAttempt({ export_kind: "animation_project", format: "cclayproject", surface: "studio" });
+		try {
+			const source = readProjectDocument(await collectProjectSerialized(domain.metadata().name ?? "Untitled"));
+			context.check();
+			if (!source.ok) throw new Error(`Could not read the storyboard project: ${source.reason}`);
+			const animation = buildAnimationProjectFromStoryboard(source.project);
+			const serialized = JSON.stringify(animation, null, 2);
+			let downloaded = false;
+			if (hasFileSystemAccess()) {
+				const handle = await pickProjectFileForSave(animation.name);
+				context.check();
+				await writeProjectFile(handle, serialized);
+				await rememberRecentProject(handle, animation.name);
+			} else {
+				downloadProjectFallback(serialized, animation.name);
+				downloaded = true;
+			}
+			attempt.succeed();
+			return {
+				saved: true,
+				name: animation.name,
+				fileName: `${animation.name}${PROJECT_EXTENSION}`,
+				downloaded,
+			};
+		} catch (error) {
+			attempt.fail(error, error?.name === "AbortError" ? "aborted" : "unknown");
+			if (error?.name === "AbortError") return { saved: false, cancelled: true };
+			appContext.notify(ko("Could not export the animation project", "애니메이션 프로젝트를 내보내지 못했어요"));
+			return { saved: false, failure: error?.code ?? error?.name ?? "error" };
+		}
+	}
+
 	function applyProject(project, authorized = false) {
 		if (!authorized) return runWithValue("project.open", "projectToken", project);
 		const checked = readSceneDocument(JSON.stringify(project.scenesDocument));
@@ -408,11 +451,10 @@ export function useScenes(appContext) {
 		// A project FILE carries its own scene document and never passes the
 		// storage reader, so the 20 fps → 24 fps clock migration is applied here
 		// too — otherwise an older .cozyclay would open a sixth too fast.
-		const doc = Number.isInteger(source.version) && source.version < SCENES_VERSION
-			? { ...source, version: SCENES_VERSION, scenes: source.scenes.map((scene) => ({ ...scene, stage: migrateStageFrames(scene.stage) })) }
-			: source;
+		const doc = migrateToCurrentScenes(source);
 		const mergedCustomPoses = mergeProjectCustomPoses(appContext.shared.customPoses, project.customPoses);
-		domain.replaceDocument(doc.scenes, doc.activeSceneId, project.name);
+		const projectPrevisMode = normalizePrevisMode(project.previsMode);
+		domain.replaceDocument(doc.scenes, doc.activeSceneId, project.name, projectPrevisMode);
 		if (project.workspaceLayout) appContext.shared.setWorkspaceLayout({ ...DEFAULT_WORKSPACE_LAYOUT, ...project.workspaceLayout });
 		appContext.bus.run('cast.setCustomPoses', { poses: mergedCustomPoses });
 		const resolvedWorkflow = resolveWorkflowOutputs(normalizeWorkflowGraph(project.workflow), new Map((project.assets ?? []).map((asset) => [asset.id, asset])));
@@ -423,7 +465,7 @@ export function useScenes(appContext) {
 		appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(project.name);
 		domain.pendingCheckpoint = { clock: appContext.undoClock, name: project.name };
 		domain.setDirty(false);
-		storeProjectSession(project.name);
+		storeProjectSession(project.name, projectPrevisMode);
 		setProjectStartupOpen(false);
 		// Whatever document this is, it is no longer the scene the tutorial opened
 		// for itself; startCameraTutorial re-arms the flag after its own open.
@@ -435,7 +477,8 @@ export function useScenes(appContext) {
 	/** Open a bundled starter scene as a fresh, saveable project. Used by the
 	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`), which is
 	 * how the landing-page tutorial hands people into the local studio. */
-	async function openStarterScene(id, source = "starter", context = null) {
+	async function openStarterScene(id, source = "starter", context = null, name = null) {
+		if (source === "starter" && domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return false;
 		const before = source === "tutorial" ? collectProjectSnapshot("Tutorial") : null;
 		const epoch = appContext.shared.tutorialProjectEpochRef.current;
 		const url = playgroundSceneUrl(`?scene=${encodeURIComponent(id)}`);
@@ -448,7 +491,7 @@ export function useScenes(appContext) {
 			return false;
 		}
 		context?.check();
-		applyProject({ ...project, savedAt: null }, true);
+		applyProject({ ...project, name: name?.trim() || project.name, savedAt: null }, true);
 		appContext.shared.projectHandleRef.current = null;
 		track("scene:loaded", { scene_source: source });
 		return true;
@@ -524,27 +567,36 @@ export function useScenes(appContext) {
 		}
 	}
 
-	function requestNewProject(authorized = false) {
-		if (!authorized) return runProject("project.new");
+	function requestNewProject(authorized = false, { previsMode } = {}) {
+		if (!authorized) return runProject("project.new", previsMode === undefined ? undefined : { previsMode });
 		if (domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return;
-		setProjectNameDialog({ kind: "new", initialName: projectName ?? "My Project" });
+		// The mode chosen on the start screen rides on the name dialog until its
+		// submit commits the project.
+		setProjectNameDialog({ kind: "new", initialName: projectName ?? "My Project", ...(previsMode === undefined ? {} : { previsMode }) });
 	}
 
-	function newProject(name, authorized = false) {
-		if (!authorized) return runProject("project.new", typeof name === "string" ? { name } : {});
-		if (typeof name !== "string") return requestNewProject(true);
+	function newProject(name, authorized = false, { previsMode } = {}) {
+		if (!authorized) {
+			if (previsMode === undefined && projectNameDialog?.kind === "new") previsMode = projectNameDialog.previsMode;
+			return runProject("project.new", { ...(typeof name === "string" ? { name } : {}), ...(previsMode === undefined ? {} : { previsMode }) });
+		}
+		if (typeof name !== "string") return requestNewProject(true, { previsMode });
 		name = name.trim() || "My Project";
+		previsMode = normalizePrevisMode(previsMode);
 		setProjectNameDialog(null);
 		const fresh = createSceneDocument(ko("SCENE 01", "씬 01"));
 		storeWorkflowGraph(createWorkflowGraph());
-		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name);
+		appContext.shared.projectMotionsRef.current = new Map();
+		appContext.shared.motionFullRef.current.clear();
+		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name, previsMode);
 		persistScenes(fresh.scenes, fresh.activeSceneId);
 		openScene(fresh.scenes[0], fresh.scenes);
 		appContext.shared.projectHandleRef.current = null;
 		clearStoredProjectHandle();
 		appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(name);
 		domain.setDirty(false);
-		storeProjectSession(name);
+		storeProjectSession(name, previsMode);
+		track("scene:created", { scene_source: "new_project", previs_mode: previsMode });
 		setProjectStartupOpen(false);
 		appContext.shared.setFirstSuccessGuideOpen(true);
 		domain.pendingCheckpoint = { clock: appContext.undoClock, name };
@@ -658,7 +710,7 @@ export function useScenes(appContext) {
 		const target = nextScenes[nextScenes.length - 1];
 		persistScenes(nextScenes, target.id);
 		openScene(target, nextScenes);
-		track("scene:created", { scene_source: "ui" });
+		track("scene:created", { scene_source: "ui", previs_mode: domain.metadata().previsMode });
 	}
 
 	function duplicateSceneDocument(sceneId) {
@@ -763,6 +815,9 @@ export function useScenes(appContext) {
 			domain.pendingCheckpoint = null;
 			if (checkpoint.clock === appContext.undoClock && checkpoint.name === name) appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(name);
 		}
+		if (name !== null && !appContext.shared.projectSnapshotRef.current) {
+			appContext.shared.projectSnapshotRef.current = collectProjectSnapshot(name);
+		}
 		const dirty = name !== null && collectProjectSnapshot(name) !== appContext.shared.projectSnapshotRef.current;
 		domain.setDirty(dirty);
 		setProjectSaveState((current) => current === "saving" ? current : dirty ? "dirty" : "saved");
@@ -772,6 +827,7 @@ export function useScenes(appContext) {
 	domain.fileState = () => ({ name: domain.metadata().name, hasFile: Boolean(appContext.shared.projectHandleRef.current),
 		fileAccess: hasFileSystemAccess(), gesture: globalThis.navigator?.userActivation?.isActive === true });
 	domain.save = (args, context) => saveProject(args.saveAs, args.name ?? null, context);
+	domain.exportAsAnimationProject = context => exportAsAnimationProject(context);
 	domain.loadScenes = args => loadLiveScenes(args, true);
 	domain.projectAction = async (id, args, context) => {
 		const runtime = key => {
@@ -781,8 +837,8 @@ export function useScenes(appContext) {
 			return value;
 		};
 		if (id === "project.browse") { setProjectStartupOpen(false); setProjectBrowserOpen(true); return; }
-		if (id === "project.new") return newProject(args.name, true);
-		if (id === "project.openStarter") return openStarterScene(args.id, args.source, context);
+		if (id === "project.new") return newProject(args.name, true, { previsMode: args.previsMode });
+		if (id === "project.openStarter") return openStarterScene(args.id, args.source, context, args.name);
 		if (id === "project.restore") return restoreStoredProject({ handle: runtime("handleToken") }, context);
 		if (args.handleToken) return openProjectByHandle(runtime("handleToken"), context);
 		if (args.projectToken) { applyProject(runtime("projectToken"), true); return true; }
@@ -801,13 +857,14 @@ export function useScenes(appContext) {
 	domain.refreshDirty = () => refreshProjectDirty(false);
 	return {
 		...domain, applyExternalScene, loadLiveScenes, refreshProjectDirty,
-		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName,
+		scenes, activeSceneId, sceneSaveError, snapshotActiveScene, persistScenes, projectName, previsMode,
 		projectDirty, setProjectDirty: domain.setDirty, projectSaveState, setProjectSaveState, projectMenuOpen,
 		setProjectMenuOpen, projectBrowserOpen, setProjectBrowserOpen, projectNameDialog, setProjectNameDialog,
 		projectStartupOpen, setProjectStartupOpen, projectManifest, setProjectManifest, saveBlockedReasons,
 		setSaveBlockedReasons, workflowRevision, setWorkflowRevision, collectProjectSnapshot,
 		collectProjectSerialized, projectProblemsNotice, rehydrateProjectAssets, saveProject, applyProject,
-		openStarterScene: async (id, source = "starter") => (await runProject("project.openStarter", { id, source })).output?.opened === true,
+		exportAsAnimationProject,
+		openStarterScene: async (id, source = "starter", name = null) => (await runProject("project.openStarter", { id, source, ...(name ? { name } : {}) })).output?.opened === true,
 		openProject, openProjectByHandle, requestNewProject, newProject, restoreOffer,
 		setRestoreOffer, restoreStoredProject, flushScenes, openScene, selectSceneDocument,
 		createSceneDocumentFromUi, duplicateSceneDocumentFromUi, renameSceneDocumentFromUi,

package/src/domains/shots.js

@@ -30,7 +30,7 @@ function normalizeState(value) {
 
 // The stable handle survives scene loads. Camera pose belongs to the same
 // history entry as the shot it frames; only the persisted shots are projected.
-export function createShotsDomain(appContext, initial = {}) {
+function createShotsDomain(appContext, initial = {}) {
   const initialState = value => normalizeState({ shots: [], frameCount: DEFAULT_DURATION_S * TIMELINE_FPS,
     cameraMove: CAMERA_MOVES[1], fovDeg: PRESETS.medium.fov, camera: null, manual: false, ...value });
   let native = createDocumentStore({ owned: { shot: initialState(initial) } });
@@ -140,6 +140,25 @@ export function createShotsDomain(appContext, initial = {}) {
     const before = state(), filmback = appContext.live.state.filmback;
     writeState({ ...before, fovDeg, camera: before.camera && { ...before.camera, focalMm: fovToFocalMm(fovDeg * Math.PI / 180, filmback.sensorId, filmback.aspectRatio) } });
   }
+  function setCastOverride(shotId, characterId, override) {
+    if (!read().some(shot => shot.id === shotId)) throw new StudioProtocolError('STALE_TARGET', `Shot ${shotId} is not in this scene.`);
+    if (!appContext.live.characters.some(entry => entry.id === characterId)) throw new StudioProtocolError('STALE_TARGET', `Character ${characterId} is not in this scene.`);
+    if (override !== null && (!override || !Number.isFinite(override.x) || !Number.isFinite(override.z) || !Number.isFinite(override.rot)
+      || (override.posture !== undefined && !['stand', 'sit', 'lie'].includes(override.posture))
+      || (override.pose !== undefined && (!override.pose || typeof override.pose !== 'object' || Array.isArray(override.pose))))) {
+      throw new StudioProtocolError('INVALID_ARGUMENT', 'Cast override requires finite x, z and rot and valid posture/pose fields.');
+    }
+    return writeState(before => ({
+      ...before,
+      shots: before.shots.map(shot => {
+        if (shot.id !== shotId) return shot;
+        const cast = { ...shot.cast };
+        if (override === null) delete cast[characterId];
+        else cast[characterId] = structuredClone(override);
+        return { ...shot, cast };
+      }),
+    }));
+  }
   function placeCamera(args) {
     const before = appContext.ports.read().camera ?? state().camera;
     const position = { ...before.position, ...Object.fromEntries(['x', 'y', 'z'].filter(key => args[key] !== undefined).map(key => [key, args[key]])) };
@@ -181,7 +200,7 @@ export function createShotsDomain(appContext, initial = {}) {
     }
     return run('run.update', { txId: gesture.txId, args });
   }
-  const domain = { documentStore, state, read, write, writeState, beginAction, run, edit, beginGesture, finishGesture,
+  const domain = { documentStore, state, read, write, writeState, setCastOverride, beginAction, run, edit, beginGesture, finishGesture,
     bindRender(context) { appContext = context; },
     capture: () => appContext.shared.captureCurrentFraming(), frame, captureCamera, placeCamera, setLens, renderCamera,
     canUndo: id => documentStore.canUndo(id), stepHistory: redo => { finishGesture(); return Boolean((redo ? documentStore.redo : documentStore.undo)()); },
@@ -345,7 +364,9 @@ export function useShots(appContext) {
       const travel = Math.ceil(curve.length / speed * tlFps) + Math.round(tlFps * 0.5);
       const endFrame = Math.min(tlFrameCount - 1, activeShot.startFrame + Math.max(travel, activeShot.endFrame - activeShot.startFrame));
       setTimelineShotRange(activeShot.id, activeShot.startFrame, endFrame);
-      appContext.shared.enterPreview(); setTlFrame(activeShot.startFrame);
+      // The landing tutorial's last step is pressing ▶ (#602): open the player
+      // on the shot camera, but leave playback to the visitor.
+      appContext.shared.enterPreview(); appContext.shared.setTlPlaying(false); setTlFrame(activeShot.startFrame);
       appContext.notify(isKo ? '레일 완성 — 샷 카메라 시점으로 전환했습니다. ▶ 로 재생, Esc 로 복귀' : 'Rail drawn — you are looking through the shot camera. Press ▶ to ride it; Esc goes back to flying.'); return;
     }
     appContext.notify(isKo ? `카메라 레일 완성 — ${curve ? curve.length.toFixed(1) : '?'} m, 제어점 ${simplified.length}개` : `Camera rail drawn — ${curve ? curve.length.toFixed(1) : '?'} m, ${simplified.length} control points`);
@@ -371,18 +392,23 @@ export function useShots(appContext) {
     setTlFrameCount(span); if (extent > 0) setTlFrame(frame => Math.min(frame, span - 1));
   }
   function finishCameraMove(finalFov) { setMovePlaying(false); setFovDeg(Math.round(finalFov * 10) / 10); }
-  async function exportShotVideo({ download = true, shotId = null } = {}, commandContext = null) {
+  // scope "timeline" records every frame of the timeline, shot boxes and all;
+  // "shot" records one shot (shotId, or the one under the playhead). Without a
+  // scope the old rule stands: a named shot, or the playhead's shot when there
+  // is no motion, else the whole record.
+  async function exportShotVideo({ download = true, shotId = null, scope = null } = {}, commandContext = null) {
     if (appContext.shared.recRef.current) return null;
     const atPlayhead = shotIndexAtFrame(shots, tlFrame);
     const target = shotId ? shots.find(entry => entry.id === shotId) : shots[atPlayhead >= 0 ? atPlayhead : 0] ?? null;
     if (shotId && !target) return null;
     let exportShots = shots;
-    if (target && target.cameraKeys.length === 0 && !shotId) {
+    if (target && target.cameraKeys.length === 0 && !shotId && scope !== 'timeline') {
       appContext.bus.run('shot.addKey', { shotId: target.id, frame: target.startFrame });
       exportShots = appContext.storeDomain('shot').read();
     }
-    const range = target && (shotId || !appContext.shared.motion) ? { startFrame: target.startFrame, endFrame: target.endFrame }
-      : { startFrame: 0, endFrame: Math.max(0, appContext.shared.currentRecordFrameCount() - 1) };
+    const oneShot = scope === 'shot' ? Boolean(target) : scope === 'timeline' ? false : Boolean(target && (shotId || !appContext.shared.motion));
+    const range = oneShot ? { startFrame: target.startFrame, endFrame: target.endFrame }
+      : { startFrame: 0, endFrame: Math.max(0, appContext.shared.currentRecordFrameCount() - 1, ...(scope === 'timeline' ? shots.map(entry => entry.endFrame) : [])) };
     return appContext.shared.executeExportRequest(appContext.shared.exportRequest('video', async job => {
       const abort = () => job.controller.abort(commandContext.signal.reason);
       commandContext?.signal.addEventListener('abort', abort, { once: true });

package/src/error-boundary.jsx

@@ -31,7 +31,7 @@ export default class ErrorBoundary extends Component {
 			<div className="crash-screen" role="alert">
 				<h1>{ko("The studio hit a render error", "스튜디오에 렌더링 오류가 발생했어요")}</h1>
 				<p>{ko("Scenes autosave as you work, so reloading resumes from the last saved state.", "작업 중 장면은 자동 저장되므로, 새로고침하면 마지막 저장 상태에서 이어집니다.")}</p>
-				<pre className="crash-detail">{String((this.state.error && this.state.error.message) || this.state.error)}</pre>
+				<pre className="crash-detail">{String(this.state.error.message || this.state.error)}</pre>
 				<button type="button" onClick={() => window.location.reload()}>
 					{ko("Reload the studio", "스튜디오 새로고침")}
 				</button>

package/src/execution-telemetry.js

@@ -1,5 +1,5 @@
 import { bucketMs, track, EXECUTION_TELEMETRY_VALUES } from "./analytics.js";
-export { AGENT_TOOL_CATEGORIES, MCP_TOOL_CATEGORIES, EXECUTION_TELEMETRY_EVENTS, EXECUTION_TELEMETRY_PROPERTY_KEYS, EXECUTION_TELEMETRY_VALUES } from "./analytics.js";
+export { AGENT_TOOL_CATEGORIES, EXECUTION_TELEMETRY_EVENTS, EXECUTION_TELEMETRY_PROPERTY_KEYS, EXECUTION_TELEMETRY_VALUES } from "./analytics.js";
 const WORKFLOW_FAILURE_CODES = new Set(["aborted", "capture_failed", "generation_failed", "unknown"]);
 const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown"]);
 function secureId() {
@@ -31,7 +31,7 @@ function readNow(now) {
 	}
 }
 
-export function executionFailureCode(error, channel, fallbackCode = "unknown") {
+function executionFailureCode(error, channel, fallbackCode = "unknown") {
 	const allowed = channel === "agent" ? AGENT_FAILURE_CODES : WORKFLOW_FAILURE_CODES;
 	try {
 		if (error?.name === "AbortError") return "aborted";
@@ -48,8 +48,8 @@ export function mcpToolCategory(name) {
 	if (name === "set_camera" || name === "frame_shot" || name === "mark_camera_move" || name === "describe_camera_move") return "camera";
 	if (name === "set_prompt_blocks") return "prompt_authoring";
 	if (name === "save_project" || name === "open_project") return "project_io";
-	if (name === "describe_scene" || name === "describe_shot" || name === "render_prompt" || name === "live_status") return "read";
-	if (name === "add_character" || name === "place_character" || name === "remove_character" || name === "focus_character" || name === "place_object" || name === "import_mesh" || name === "group_objects" || name === "update_object" || name === "remove_object" || name === "apply_batch" || name === "add_scene" || name === "switch_scene") return "scene_write";
+	if (name === "describe_scene" || name === "describe_shot" || name === "render_prompt" || name === "live_status" || name === "compare_sculpt") return "read";
+	if (name === "add_character" || name === "place_character" || name === "remove_character" || name === "focus_character" || name === "place_object" || name === "import_mesh" || name === "sculpt_object" || name === "group_objects" || name === "update_object" || name === "remove_object" || name === "apply_batch" || name === "add_scene" || name === "switch_scene") return "scene_write";
 	return "other";
 }
 
@@ -61,7 +61,7 @@ export function startWorkflowExecution(metadata, { capture = track, now = () =>
 	const emit = (event, props) => {
 		if (runId) safeCapture(capture, event, props);
 	};
-	if (runId) emit("workflow:run_requested", {
+	emit("workflow:run_requested", {
 		surface: "workflow",
 		...(EXECUTION_TELEMETRY_VALUES.node_count_bucket.has(metadata.node_count_bucket) ? { node_count_bucket: metadata.node_count_bucket } : {}),
 		run_id: runId,

package/src/facing-marks.js

@@ -30,7 +30,7 @@ import * as THREE from "three";
  * these cannot split segmentation. The COCO nose keypoint is the one the
  * estimator keys facing on; the wedge centres the face below the eyes.
  */
-export const EYE_SEPARATION = 6;
+const EYE_SEPARATION = 6;
 
 export function facingMarkSpecs() {
 	const eye = (x) => ({
@@ -73,3 +73,16 @@ export function addFacingMarks(clone) {
 		head.add(mesh);
 	}
 }
+
+export function proxyFacingMark(material = null) {
+	const mesh = new THREE.Mesh(
+		new THREE.ConeGeometry(0.055, 0.16, 4),
+		material ?? new THREE.MeshStandardMaterial({ color: "#1C1C1C", roughness: 0.7, metalness: 0 }),
+	);
+	mesh.position.set(0, -0.015, 0.115);
+	mesh.rotation.set(Math.PI / 2, Math.PI / 4, 0);
+	mesh.castShadow = true;
+	mesh.frustumCulled = false;
+	mesh.userData.facingMark = true;
+	return mesh;
+}