cozyclay 2.0.0 → 2.0.2

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"2.0.0\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"2df2a5c5568a32133c5f4efc43abbd1ecb7bd07d89538eb6860a24afe12a98c5\"}","signature":"stRY9RUg5dAQVwVhfhYrieP1HpXK+ahX3U5g8qFMzsQYw2ZFEF+iXRblkvYNjk5MS2g43qKAEMN9F8K0MP3vAA=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"2.0.2\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"6b21f4b8112041967b14ed57d28da217b04fae78e0adeb9dd0da143622814822\"}","signature":"72GMEbX6c47ZRDJrLMi7FipjXz9cKt/piGTYyzGUXpUtNNPx3WCkP6GWJp4PoXZdVoaB9mOrEA71YGN9TEktAA=="}

package/dist/sitemap.xml

@@ -6,19 +6,19 @@
   </url>
   <url>
     <loc>https://cozyclay.org/greybox-to-video/</loc>
-    <lastmod>2026-10-01</lastmod>
+    <lastmod>2026-09-14</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/previs-software/</loc>
-    <lastmod>2026-10-01</lastmod>
+    <lastmod>2026-09-10</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/seedance-camera-control/</loc>
-    <lastmod>2026-10-01</lastmod>
+    <lastmod>2026-09-10</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/ai-camera-control/</loc>
-    <lastmod>2026-10-01</lastmod>
+    <lastmod>2026-09-10</lastmod>
   </url>
   <url>
     <loc>https://cozyclay.org/privacy/</loc>

package/dist/workflow/index.html

@@ -8,10 +8,10 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-dNPGY9xz.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-B5XZwVfe.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
     <link rel="modulepreload" crossorigin href="/assets/analytics-MVZOEW8O.js">
-    <link rel="modulepreload" crossorigin href="/assets/shot-prompt-Yrt99wZx.js">
+    <link rel="modulepreload" crossorigin href="/assets/shot-prompt-hN0j_O-p.js">
     <link rel="stylesheet" crossorigin href="/assets/shot-prompt-CbqWcWYi.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",

package/src/App.jsx

@@ -147,6 +147,7 @@ import {
 } from "./matte.js";
 import { createMatteEditor } from "./matte-editor.js";
 import {
+	SCENES_STORAGE_KEY,
 	SCENES_VERSION,
 	activeSceneIndex,
 	createSceneStage,
@@ -154,6 +155,7 @@ import {
 } from "./scenes.js";
 import {
 	hasFileSystemAccess,
+	loadProjectSession,
 	loadStoredProjectHandle,
 	queryHandlePermission,
 	requestHandlePermission,
@@ -498,9 +500,17 @@ export default function App() {
 	// 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 [cameraTutorialQuery] = useState(() => !embedMode && !playgroundMode
-		&& new URLSearchParams(globalThis.location?.search || "").get("tutorial") === "camera"
-		&& !cameraTutorialSuppressed());
+	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);
@@ -524,8 +534,8 @@ export default function App() {
 	useEffect(() => {
 		if (!cameraTutorialQuery || cameraTutorialStarted.current) return;
 		cameraTutorialStarted.current = true;
-		void startCameraTutorialRef.current?.({ source: "query" });
-	}, [cameraTutorialQuery]);
+		void startCameraTutorialRef.current?.({ source: cameraTutorialEntry });
+	}, [cameraTutorialQuery, cameraTutorialEntry]);
 	useEffect(() => {
 		const onTutorial = (event) => {
 			if (event.detail?.open === false) {
@@ -3024,8 +3034,8 @@ export default function App() {
 		return [{
 			id: entry.id,
 			url: characterModelUrl(entry.model),
-			position: clip ? [clip.anchorX, entry.y ?? 0, clip.anchorZ] : [entry.x, entry.y ?? 0, entry.z],
-			rot: clip ? clip.rotationDeg : entry.rot,
+			position: [entry.x, entry.y ?? 0, entry.z],
+			rot: entry.rot,
 			tint: entry.tint ?? defaultCharacterTint(entry, index),
 			partColoursEnabled,
 			partColoursMode,
@@ -3047,8 +3057,7 @@ export default function App() {
 		if (!charIdFromHierarchyId(selectedHierarchyId)) return null;
 		const entry = characters.find((item) => item.id === activeChar.id);
 		if (!entry || entry.hidden) return null;
-		const clip = motion;
-		return { position: clip ? [clip.anchorX, entry.y ?? 0, clip.anchorZ] : [entry.x, entry.y ?? 0, entry.z] };
+		return { position: [entry.x, entry.y ?? 0, entry.z] };
 	}, [characters, activeChar.id, motion, selectedHierarchyId]);
 	// The cast rides the SAME gizmo as scene objects — one movement grammar
 	// for everything on stage. The proxy hands ObjectGizmo the object shape
@@ -3950,6 +3959,11 @@ export default function App() {
 			});
 			return;
 		}
+		// The seed dresses a visitor's first, unnamed stage and the starter set a
+		// `?scene=` launch always re-opens ("one character mid-walk"). A named
+		// project is the author's document: reloading it must never put the demo
+		// walk back on a character they deliberately left without a take.
+		if (loadProjectSession()?.name && !new URLSearchParams(window.location.search).get("scene")) { demoSeeded.current = true; return; }
 		if (!demoSeed.seed) return;
 		demoSeeded.current = true;
 		// Loaded, not played: the clip walks the subject out of the default
@@ -6770,6 +6784,8 @@ export default function App() {
 							key={cameraTutorialAttempt}
 							analytics={cameraTutorialAnalytics.current}
 							previewing={lookThroughShot}
+							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()}
@@ -7455,9 +7471,9 @@ export default function App() {
 						openProject();
 					}}
 					starters={STARTER_SCENES}
-					onStarter={(id) => {
+					onStarter={(id, name) => {
 						setProjectBrowserOpen(false);
-						void openStarterScene(id);
+						void openStarterScene(id, "starter", name);
 					}}
 					onNew={() => {
 						setProjectBrowserOpen(false);

package/src/ardy/timeline.css

@@ -855,10 +855,25 @@
 	background: var(--select-tint, rgba(232, 163, 61, .14));
 }
 
+/* The bar hangs above the block's top-left corner instead of inside it: a
+   short cut (40 frames ~ 38px) is narrower than Split + Duplicate + Delete,
+   and an in-block bar would sit on the shot's name, turning a click on the
+   name into Delete. Hover is kept because the bar is still a child. */
 .v2-sequencer .tl-shot-actions {
+	top: auto;
+	bottom: calc(100% + 2px);
+	left: 0;
+	right: auto;
 	background: var(--overlay, rgba(12, 12, 13, .78));
 }
 
+/* The block clips its own box (overflow hidden) so the hanging bar only exists
+   while it is wanted; the label clips its own text, so nothing else escapes. */
+.v2-sequencer .tl-shot-block:hover,
+.v2-sequencer .tl-shot-block:focus-within {
+	overflow: visible;
+}
+
 .v2-sequencer .tl-shot-actions button {
 	height: var(--h-row, 24px);
 	border-radius: var(--r-1, 4px);

package/src/ardy/timeline.jsx

@@ -1809,7 +1809,10 @@ export default function Timeline({
 									type="button"
 									className="tl-seq-action rail"
 									data-testid="sequencer-draw-rail"
-									title={ko("Draw or redraw the selected camera rail", "선택한 카메라 레일을 그리거나 다시 그립니다")}
+									// The rail belongs to a shot: with none selected the toggle used to
+									// do nothing at all, so say why instead.
+									disabled={cameraBlockIdx == null}
+									title={cameraBlockIdx == null ? ko("Add or select a shot first — the rail belongs to a shot", "먼저 샷을 추가하거나 선택하세요 — 레일은 샷에 속합니다") : ko("Draw or redraw the selected camera rail", "선택한 카메라 레일을 그리거나 다시 그립니다")}
 									onClick={() => handlers.current.onCameraRailDrawToggle?.()}
 								>
 									{ko("Draw rail", "레일 그리기")}

package/src/ardy/waypoints.js

@@ -1,6 +1,6 @@
 const cleanZero = (value) => (Object.is(value, -0) || Math.abs(value) < 1e-9 ? 0 : value);
 import { isKo } from "../locale.js";
-import { TIMELINE_FRAME_FPS } from "../scenes.js";
+import { TIMELINE_FRAME_FPS } from "../timeline-fps.js";
 
 const DEFAULT_WAYPOINT_SPACING_FRAMES = Math.round(0.4 * TIMELINE_FRAME_FPS);
 

package/src/camera-tutorial.jsx

@@ -11,7 +11,7 @@ import { ko } from "./locale.js";
 // to them directly.
 //
 //   cozyclay:nav               fly / walk / dolly / orbit  (src/controls.jsx)
-//   cozyclay:playground-signal shot / rail                 (src/App.jsx)
+//   shotCount / railReady      shot / rail                 (authored state)
 //   previewing prop            play                        (lookThroughShot)
 //
 // Nothing here drives the studio. A step is done when the operator has done
@@ -69,16 +69,16 @@ export const CAMERA_TUTORIAL_STEPS = [
 		label: ko("Shot", "샷"),
 		// The control lives in another region than the card, so the card says
 		// which way to look before it says what to do.
-		where: ko("↓ Timeline, Shots lane", "↓ 타임라인 샷 레인"),
+		where: ko("↓ Timeline, Camera Cuts", "↓ 타임라인 Camera Cuts"),
 		how: () => ko(
-			<>In the timeline's Shots lane click <b>+ Add shot</b>. That is your cut.</>,
-			<>타임라인의 샷 레인에서 <b>+ 샷 추가</b>를 누르세요. 그게 컷입니다.</>,
+			<>In the timeline's Camera Cuts lane click <b>+ Add shot</b>. That is your cut.</>,
+			<>타임라인의 Camera Cuts 레인에서 <b>+ 샷 추가</b>를 누르세요. 그게 컷입니다.</>,
 		),
 	},
 	{
 		kind: "rail",
 		label: ko("Rail", "레일"),
-		where: ko("↓ Timeline, Shots lane", "↓ 타임라인 샷 레인"),
+		where: ko("↓ Timeline, Camera Cuts", "↓ 타임라인 Camera Cuts"),
 		how: () => ko(
 			<>Select the shot, click <b>Draw rail</b> in the camera bar, and drag a line across the top view. That line is the dolly move.</>,
 			<>샷을 선택하고 카메라 바의 <b>레일 그리기</b>를 누른 뒤, 탑뷰에 선을 그으세요. 그 선이 돌리 이동입니다.</>,
@@ -87,10 +87,10 @@ export const CAMERA_TUTORIAL_STEPS = [
 	{
 		kind: "play",
 		label: ko("Play", "재생"),
-		where: ko("→ Viewport", "→ 뷰포트"),
+		where: ko("↘ Shot Camera monitor", "↘ Shot Camera 모니터"),
 		how: () => ko(
 			<>Click <b>Look through</b> in the Shot monitor to fly the shot camera; <b>▶</b> rides the rail, <kbd>Esc</kbd> returns to the free camera.</>,
-			<>뷰포트의 <b>샷 시점</b>을 눌러 샷 카메라를 조종하세요. <b>▶</b>는 레일을 타고, <kbd>Esc</kbd>로 자유 카메라로 돌아옵니다.</>,
+			<>Shot Camera 모니터의 <b>샷 시점</b>을 눌러 샷 카메라를 조종하세요. <b>▶</b>는 레일을 타고, <kbd>Esc</kbd>로 자유 카메라로 돌아옵니다.</>,
 		),
 	},
 ];
@@ -119,10 +119,13 @@ export const TUTORIAL_BEACONS = {
 			label: () => ko("1. Select the shot", "1. 샷을 선택"),
 		},
 		{ role: "draw-rail", selector: ".tl-rail-draw", label: () => ko("2. Draw rail, then drag across the top view", "2. 레일 그리기 후 탑뷰에 선 긋기") },
-		{ role: "top-view", selector: ".vp-inset", requires: ".tl-rail-draw", label: () => ko("Drag a line here", "여기에 선을 그으세요") },
+		// The Top-View becomes an active drawing surface after the tool is armed.
+		{ role: "top-view", selector: ".vp-inset", requires: '[data-rail-draw="1"]', label: () => ko("Drag a line here", "여기에 선을 그으세요") },
 	],
 	play: [
-		{ role: "look-through", selector: ".vp-look-through", label: () => ko("Click to fly the shot camera", "클릭해 샷 카메라를 조종") },
+		// The glass shell keeps the same action in the bottom dock while the
+		// compact viewport card owns it in the classic shell.
+		{ role: "look-through", selector: ".dock-shot-look, .vp-look-through", label: () => ko("Click to fly the shot camera", "클릭해 샷 카메라를 조종") },
 	],
 };
 
@@ -217,7 +220,7 @@ export function TutorialBeacon({ kind, step, role, selector, label, requires = n
 			if (pane) resize.observe(pane);
 		}
 		const mutations = new MutationObserver(schedule);
-		mutations.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["class", "style"] });
+		mutations.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["class", "style", "data-rail-draw"] });
 		return () => {
 			if (frame) cancelAnimationFrame(frame);
 			window.removeEventListener("resize", schedule);
@@ -327,11 +330,18 @@ export function GestureCue({ kind, walked, leaving = false, onLeft }) {
  * Top-View inset, and never takes the pointer except on its own close button
  * — every step is completed by working the studio underneath it.
  */
-export function CameraTutorial({ previewing = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
+export function CameraTutorial({ previewing = false, shotCount = 0, railReady = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
 	const [done, setDone] = useState(() => new Set());
 	const [walked, setWalked] = useState(() => new Set());
 	const [cue, setCue] = useState(null);
 	const completionReported = useRef(false);
+	const effectiveDone = useMemo(() => {
+		const next = new Set(done);
+		if (shotCount > 0) next.add("shot");
+		if (railReady) next.add("rail");
+		if (previewing && next.has("rail")) next.add("play");
+		return next;
+	}, [done, previewing, railReady, shotCount]);
 
 	useEffect(() => {
 		const complete = (kind) => setDone((current) => (current.has(kind) ? current : new Set(current).add(kind)));
@@ -362,6 +372,16 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 		};
 	}, []);
 
+	// Studio-native completion comes from the authored state. The old playground
+	// signal was never emitted by the Studio shell, so a real Shot or rail could
+	// leave the tutorial stuck on its previous step.
+	useEffect(() => {
+		if (shotCount > 0) setDone((current) => (current.has("shot") ? current : new Set(current).add("shot")));
+	}, [shotCount]);
+	useEffect(() => {
+		if (railReady) setDone((current) => (current.has("rail") ? current : new Set(current).add("rail")));
+	}, [railReady]);
+
 	// The player is the last step, and only once there is a rail to ride:
 	// look-through before the dolly exists shows a still frame, which teaches
 	// nothing about the move. Analytics v1 observes this existing look-through
@@ -369,12 +389,12 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 	useEffect(() => {
 		if (!previewing) return;
 		setDone((current) => (!current.has("rail") || current.has("play") ? current : new Set(current).add("play")));
-	}, [previewing]);
+	}, [previewing, railReady]);
 
-	const current = useMemo(() => CAMERA_TUTORIAL_STEPS.find((step) => !done.has(step.kind)) ?? null, [done]);
+	const current = useMemo(() => CAMERA_TUTORIAL_STEPS.find((step) => !effectiveDone.has(step.kind)) ?? null, [effectiveDone]);
 	const complete = current === null;
 	const currentKind = current?.kind ?? null;
-	const showHandoff = !!shotId && (handoff?.canShow(done) ?? false);
+	const showHandoff = !!shotId && (handoff?.canShow(effectiveDone) ?? false);
 	useEffect(() => {
 		if (!complete || completionReported.current) return;
 		completionReported.current = true;
@@ -384,8 +404,8 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 	// Observe committed progression, outside state updaters (which StrictMode
 	// may replay). The attempt belongs to App and survives effect cleanup/resume.
 	useEffect(() => {
-		analytics?.observe(done, currentKind);
-	}, [analytics, done, currentKind]);
+		analytics?.observe(effectiveDone, currentKind);
+	}, [analytics, effectiveDone, currentKind]);
 
 	// The step the operator is on is the studio's business too: App puts it on
 	// the .app root as data-tutorial-step, and styles.css spotlights whichever
@@ -425,10 +445,10 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 						key={step.kind}
 						data-testid="camera-tutorial-step"
 						data-kind={step.kind}
-						data-done={done.has(step.kind) ? 1 : 0}
+						data-done={effectiveDone.has(step.kind) ? 1 : 0}
 						data-current={step === current ? 1 : 0}
 					>
-						<i aria-hidden="true">{done.has(step.kind) ? "✓" : index + 1}</i>
+						<i aria-hidden="true">{effectiveDone.has(step.kind) ? "✓" : index + 1}</i>
 						{step.label}
 					</li>
 				))}

package/src/commands/project.js

@@ -10,7 +10,7 @@ const save = { ...studioActionDeclaration("project.save"), input: input({ name }
 const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
 const opening = document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token });
 const fresh = document("project.new", "Start a new project", { name });
-const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] } });
+const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] }, name });
 const restore = { ...document("project.restore", "Restore the remembered project", { handleToken: token }), exposure: "ui-only" };
 const browse = { id: "project.browse", label: "Browse projects", description: "Show the project browser.", kind: "transient", exposure: "ui-only", input: input() };
 export const declarations = Object.freeze([rename, save, saveAs, opening, fresh, starter, restore, browse]);

package/src/domains/scenes.js

@@ -435,7 +435,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 +449,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;
@@ -537,6 +538,8 @@ export function useScenes(appContext) {
 		setProjectNameDialog(null);
 		const fresh = createSceneDocument(ko("SCENE 01", "씬 01"));
 		storeWorkflowGraph(createWorkflowGraph());
+		appContext.shared.projectMotionsRef.current = new Map();
+		appContext.shared.motionFullRef.current.clear();
 		domain.replaceDocument(fresh.scenes, fresh.activeSceneId, name);
 		persistScenes(fresh.scenes, fresh.activeSceneId);
 		openScene(fresh.scenes[0], fresh.scenes);
@@ -763,6 +766,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");
@@ -782,7 +788,7 @@ export function useScenes(appContext) {
 		};
 		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.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; }
@@ -807,7 +813,7 @@ export function useScenes(appContext) {
 		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,
+		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/motion/generation.js

@@ -1,7 +1,7 @@
 // Pure request construction. The caller supplies one rolled seed and sampled
 // poses; no rig, store, random source, notification or network is touched here.
 import { StudioProtocolError, compileStudioBeats } from '../studio-agent-protocol.js';
-import { TIMELINE_FRAME_FPS as FPS } from '../scenes.js';
+import { TIMELINE_FRAME_FPS as FPS } from '../timeline-fps.js';
 import { judgeAuthoredPath, alignArdyPath } from '../ardy/waypoints.js';
 import { planPosePin, PIN_BLOCKED } from '../ardy/pose-pin.js';
 import { blocksFromRequest, replayPayload, replayTruncated } from '../take-recipe.js';

package/src/project-browser.jsx

@@ -190,6 +190,10 @@ export default function ProjectBrowser({ currentName, onOpen, onOpenFile, onNew,
 		event.preventDefault();
 		const projectName = name.trim();
 		if (!projectName) return;
+		if (selectedTemplate?.starterId) {
+			onStarter?.(selectedTemplate.starterId, projectName);
+			return;
+		}
 		pendingProjectName = projectName;
 		onNew(projectName);
 	};

package/src/scenes.js

@@ -8,6 +8,9 @@ import { normalizeMotionCalibration } from "./ardy/motion-calibration.js";
 import { normalizeTrailEdits } from "./motion-trail.js";
 import { elementByPath } from "./studio-elements.js";
 import { wrapAngle } from "./scene-objects.js";
+// The timeline clock lives in timeline-fps.js (three-free, so the agent
+// sidecar can import it); re-exported here for every scene-side caller.
+import { LEGACY_FRAME_FPS, TIMELINE_FRAME_FPS, toTimelineFrame } from "./timeline-fps.js";
 
 const CHARACTER_POSITION_LIMITS = elementByPath("character.position");
 const CHARACTER_ROTATION_LIMITS = elementByPath("character.rot");
@@ -29,14 +32,7 @@ export const LEGACY_SCENES_STORAGE_KEYS = Object.freeze([
 	V1_SCENES_STORAGE_KEY,
 ]);
 
-/** v3 and older authored every frame number on ARDY's 20 fps clock; v4 reads
- * them on the 24 fps production clock. The numbers are MULTIPLIED, never
- * reinterpreted: a waypoint at frame 40 meant 2.0 s and must still mean 2.0 s,
- * which is frame 48 — reinterpreting it would silently speed the scene up. */
-export const LEGACY_FRAME_FPS = 20;
-export const TIMELINE_FRAME_FPS = 24;
-export const toTimelineFrame = (frame) =>
-	Math.round((frame * TIMELINE_FRAME_FPS) / LEGACY_FRAME_FPS);
+export { LEGACY_FRAME_FPS, TIMELINE_FRAME_FPS, toTimelineFrame };
 
 /** Rigged character models shipped in public/models. The id is both the FBX
  * file stem and the wire `source.rig` value sent to ARDY. */

package/src/styles.css

@@ -899,7 +899,8 @@ select {
 .app[data-tutorial-step="shot"] .tl-track.shots .tl-track-add,
 .app[data-tutorial-step="rail"] .tl-track.shots .tl-shot-block:not(.selected),
 .app[data-tutorial-step="rail"] .tl-rail-draw,
-.app[data-tutorial-step="play"] .vp-look-through {
+.app[data-tutorial-step="play"] .vp-look-through,
+.app[data-tutorial-step="play"] .dock-shot-look {
 	animation: tutorial-spotlight 1.5s var(--ease) infinite;
 	box-shadow: 0 0 0 3px var(--accent);
 }
@@ -9427,6 +9428,23 @@ input[type=range] {
 	width: clamp(220px, calc(50% - 92px), 360px);
 }
 
+/* The floating shell covers the full-bleed viewport with panels. Keep the
+   instructions inside its open stage, clear of the tool rail and dock. */
+.app[data-shell="glass"]:not([data-embed-mode]) .camera-tutorial {
+	top: calc(var(--shell-view-top, 52px) + 12px);
+	left: calc(var(--shell-center-left) + 64px);
+	width: min(430px, calc(100% - var(--shell-center-left) - var(--shell-center-right) - 128px));
+}
+.app[data-shell="glass"][data-tutorial-step="rail"] .camera-tutorial,
+.app[data-shell="glass"] .camera-tutorial[data-previewing="1"] {
+	top: auto;
+	bottom: calc(var(--shell-center-bottom) + 12px);
+}
+.app[data-shell="glass"]:not([data-embed-mode]) .tutorial-cue {
+	left: calc((var(--shell-center-left) + 100% - var(--shell-center-right)) / 2);
+	bottom: calc(var(--shell-center-bottom) + 18px);
+}
+
 .camera-tutorial-steps {
 	display: flex;
 	flex-wrap: wrap;

package/src/theme.js

@@ -2,7 +2,7 @@
 // shell, its regions and body-level popovers all read the same token set.
 export const THEMES = ["dark", "light"];
 export const THEME_KEY = "cozyclay.theme.v1";
-export const DEFAULT_THEME = "dark";
+export const DEFAULT_THEME = "light";
 
 import { useEffect, useState } from "react";
 

package/src/timeline-fps.js

@@ -0,0 +1,13 @@
+// The timeline clock, on its own so the agent sidecar (bin/agent) can read it
+// without importing scenes.js, whose scene-object and motion-trail imports pull
+// in `three` — a devDependency the npm package does not ship
+// (test/verify-package-agent-imports.mjs).
+
+/** v3 and older authored every frame number on ARDY's 20 fps clock; v4 reads
+ * them on the 24 fps production clock. The numbers are MULTIPLIED, never
+ * reinterpreted: a waypoint at frame 40 meant 2.0 s and must still mean 2.0 s,
+ * which is frame 48 — reinterpreting it would silently speed the scene up. */
+export const LEGACY_FRAME_FPS = 20;
+export const TIMELINE_FRAME_FPS = 24;
+export const toTimelineFrame = (frame) =>
+	Math.round((frame * TIMELINE_FRAME_FPS) / LEGACY_FRAME_FPS);

package/src/workflow/AgentPanel.jsx

@@ -382,10 +382,12 @@ export default function AgentPanel({
 				const payload = await transport.loadSession(stored);
 				if (!Array.isArray(payload?.transcript)) throw new Error("missing transcript");
 				if (!cancelled) store.restore(payload.transcript, payload.sessionId || stored);
-			} catch {
+			} catch (error) {
 				if (!cancelled) {
 					store.newSession();
-					setRestoreNotice("Previous conversation could not be restored");
+					// A session id with no record behind it (the pane opened, nothing
+					// was ever sent) is nothing to restore, not a failure.
+					if (error?.status !== 404) setRestoreNotice("Previous conversation could not be restored");
 				}
 			} finally {
 				if (!cancelled) setRestoreReady(true);

package/tools/run-tests.mjs

@@ -108,6 +108,7 @@ const NODE_FILES = [
 	"test/verify-agent-host.mjs",
 	"test/verify-agent-routes.mjs",
 	"test/verify-agent-live-runtime.mjs",
+	"test/verify-package-agent-imports.mjs",
 	"test/verify-agent-runner-errors.mjs",
 	"test/verify-agent-steer.mjs",
 	"test/verify-pi-tools.mjs",
@@ -292,6 +293,7 @@ const BROWSER_FILES = [
 	"test/verify-object-gizmo.mjs",
 	"test/verify-offscreen-export-browser.mjs",
 	"test/verify-project-menu-browser.mjs",
+	"test/verify-project-session-reset.mjs",
 	"test/verify-settings-menu-browser.mjs",
 	"test/verify-static-shot-export-browser.mjs",
 	"test/qa-agent-view-toggle-browser.mjs",