cozyclay 2.0.2 → 2.1.1

package/src/styles.css

@@ -847,6 +847,9 @@ select {
 	display: none;
 }
 .app[data-embed-mode="playground"] .tl-view-tools { display: none !important; }
+/* The v2 Sequencer styles sit outside the legacy layer, so the lane rule above
+   needs !important to keep only the Shots lane. */
+.app[data-embed-mode="playground"] .tl-track:not(.shots) { display: none !important; }
 /* Title bar keeps nothing but the pane's own name: the drawn dolly plays
    full-screen through the shot camera's look-through button, and Esc is the
    way back to flying. */
@@ -855,6 +858,8 @@ select {
 /* The plan inset only matters while a rail is being drawn into it. */
 .app[data-embed-mode="playground"]:not([data-rail-draw="1"]) .vp-inset.plan { display: none !important; }
 .app[data-embed-mode="playground"][data-rail-draw="1"] .vp-inset.plan { width: 44% !important; height: 62% !important; }
+/* The shot monitor would sit over the map's corner while the rail is drawn. */
+.app[data-embed-mode="playground"][data-rail-draw="1"] .vp-shot-preview { display: none !important; }
 .app[data-embed-mode="playground"] .bottom-window,
 .app[data-embed-mode="playground"] .bottom-timeline {
 	flex: 0 0 auto;
@@ -865,7 +870,7 @@ select {
 .app[data-embed-mode="playground"] .timeline.empty-shots { height: auto !important; min-height: 0 !important; max-height: none; }
 .app[data-embed-mode="playground"] .tl-body { flex: 0 0 auto; overflow: hidden; }
 .app[data-embed-mode="playground"] .tl-body { min-height: 0 !important; height: auto !important; }
-.app[data-embed-mode="playground"] .tl-surface { height: auto !important; min-height: 0; grid-template-rows: auto auto !important; }
+.app[data-embed-mode="playground"] .tl-surface { height: auto !important; min-height: 0 !important; grid-template-rows: auto auto !important; }
 /* The Shots lane keeps its full-studio height so the block's hover actions
    (Duplicate / Delete) sit in a strip above the clickable body instead of
    covering it. */
@@ -875,7 +880,8 @@ select {
 /* The shot monitor is the pane the tutorial points at: keep it small. */
 .app[data-embed-mode="playground"] .vp-shot-preview { width: 22% !important; height: auto !important; aspect-ratio: 16 / 9; right: 12px; bottom: 12px; }
 .app[data-embed-mode="playground"] .vp-shot-preview-tag { font-size: 12px; }
-.app[data-embed-mode="playground"] .vp-look-through { width: 24px; height: 24px; }
+/* The look-through button carries its label now; keep it on one line. */
+.app[data-embed-mode="playground"] .vp-look-through { height: 24px; padding: 0 8px; white-space: nowrap; }
 .app[data-embed-mode="playground"] .vp-look-through svg { width: 15px; height: 15px; }
 /* Tutorial hints: the landing page names the control the current step needs. */
 .app[data-playground-hint="look"] .vp-look-through,
@@ -3032,6 +3038,28 @@ input[type=range]::-moz-range-thumb {
 	color: #eafff3;
 }
 
+/* The selected dot's lean: two small scrub fields, the word as their badge. */
+.objmo-lean {
+	display: inline-flex;
+	align-items: stretch;
+	gap: 6px;
+}
+
+.objmo-lean .number-field {
+	flex: none;
+	width: 104px;
+}
+
+.objmo-lean .number-field .axis {
+	width: auto;
+	padding: 0 6px;
+	font-size: 10px;
+}
+
+.number-field.disabled { opacity: .45; }
+.number-field.disabled .axis,
+.number-field.disabled input { cursor: not-allowed; }
+
 .tl-path-hint {
 	margin-left: auto;
 	color: #7fae95;
@@ -3136,9 +3164,22 @@ input[type=range]::-moz-range-thumb {
 	vector-effect: non-scaling-stroke;
 }
 
-.sg-cut-diamond { fill: #ffb454; }
+/* The pin head lives outside the SVG: the graph's 1×1 viewBox is stretched to
+   the lane, so anything drawn inside it is as wide as the lane is long. */
+.sg-cut-pin {
+	position: absolute;
+	top: 3px;
+	width: 9px;
+	height: 9px;
+	padding: 0;
+	border: 0;
+	border-radius: 2px;
+	background: #ffb454;
+	transform: translateX(-50%) rotate(45deg);
+	cursor: pointer;
+}
 
-.sg-pin.selected .sg-cut-diamond { fill: #ffd08a; }
+.sg-cut-pin.selected { background: #ffd08a; box-shadow: 0 0 0 2px rgba(255, 208, 138, .35); }
 .sg-pin.selected .sg-cut { stroke-width: 2; stroke-dasharray: none; }
 
 .sg-cut-pick {
@@ -3334,7 +3375,9 @@ input[type=range]::-moz-range-thumb {
 .sg-shot .sg-line { stroke: #b9a1e8; }
 .sg-shot .sg-axis, .sg-shot .sg-average { stroke: rgba(185, 161, 232, .4); }
 .sg-shot .sg-readout { background: #4a3d6e; }
-.sg-shot .sg-scale-top, .sg-shot .sg-scale-avg, .sg-shot .sg-scale-zero { color: #7d6a9e; }
+/* The box's own width is its clock and it has no room for an axis: a dozen
+   pixels tall, three marks would sit on top of one another. */
+.sg-bare .sg-scale-top, .sg-bare .sg-scale-avg, .sg-bare .sg-scale-zero { display: none; }
 
 
 
@@ -3390,10 +3433,13 @@ input[type=range]::-moz-range-thumb {
 	pointer-events: none;
 }
 
+/* One axis, one edge: all three scale marks sit on the left. */
 .sg-scale-top,
-.sg-scale-avg {
+.sg-scale-avg,
+.sg-scale-zero {
 	position: absolute;
 	left: 4px;
+	right: auto;
 	color: #7fae95;
 	font-size: 8px;
 	pointer-events: none;
@@ -5992,6 +6038,12 @@ input[type=range]::-moz-range-thumb {
 	border-radius: 3px;
 }
 
+/* an Empty has no colour: a dashed, hollow swatch reads as "nothing to draw" */
+.add-object-swatch.empty {
+	background: transparent !important;
+	border-style: dashed;
+}
+
 /* inspector cards clip their overflow, so the menu opens inline there */
 .card .add-object {
 	display: block;
@@ -6803,10 +6855,9 @@ input[type=range]::-moz-range-thumb {
 
 /* Keep the timeline focused on the selected workflow.  Pose-correction and
    take-generation controls are useful while authoring motion, but they are
-   noise during blocking and camera work.  The controls stay mounted so the
-   mode switch is lossless; only their always-on chrome is hidden. */
+   noise during blocking and camera work.  The motion clear action stays
+   visible in Stage so a loaded take is always reversible. */
 .app[data-workflow-mode="scene"] .tl-pose-tools,
-.app[data-workflow-mode="scene"] .tl-motion-tools,
 .app[data-workflow-mode="scene"] .take-bar,
 .app[data-workflow-mode="camera"] .tl-pose-tools,
 .app[data-workflow-mode="camera"] .tl-motion-tools,
@@ -10217,4 +10268,36 @@ input[type=range] {
 	margin: 8px 0 0;
 	color: var(--muted);
 }
+
+/* Sculpt mode (#739): the turntable owns the main pane and the shot preview
+   shows the scene, so the Top-View inset has nothing to add. */
+.app[data-workflow-mode="sculpt"] .vp-inset { display: none !important; }
+
+/* The empty turntable says what the mode is waiting for, under the mode pill
+   (the dock floats over the pane's foot). Overlay chrome, like the viewport
+   pills: it never takes the pointer from the orbit. */
+.vp-sculpt-hint {
+	position: absolute;
+	left: 50%;
+	top: calc(2 * var(--sp-2, 12px) + var(--h-control, 28px));
+	z-index: 7;
+	display: grid;
+	gap: var(--sp-1, 4px);
+	max-width: min(420px, calc(100% - 2 * var(--sp-3, 16px)));
+	padding: var(--sp-2, 8px) var(--sp-3, 16px);
+	border-radius: var(--r-2, 6px);
+	background: var(--overlay);
+	color: var(--text-2);
+	font-size: 11px;
+	line-height: 1.45;
+	text-align: center;
+	transform: translateX(-50%);
+	pointer-events: none;
+}
+
+.vp-sculpt-hint strong {
+	color: var(--text-1);
+	font-size: 12px;
+	font-weight: 600;
+}
 }

package/src/ui-scrub.js

@@ -28,7 +28,7 @@ export const SCRUB_THRESHOLD_PX = 4;
 
 /** Shift buys a quarter-speed pass for fine detail; Alt keeps its old 0.1x. */
 export const FINE_SCRUB_FACTOR = 0.25;
-export const EXTRA_FINE_SCRUB_FACTOR = 0.1;
+const EXTRA_FINE_SCRUB_FACTOR = 0.1;
 
 /**
  * The meaningful span a full drag sweeps when the field does not name one.
@@ -39,8 +39,8 @@ export const SCRUB_RANGE_STEPS = 100;
 
 /** The span one full `SCRUB_TRAVEL_PX` drag covers for a field. */
 export function scrubRangeFor({ scrubRange, step } = {}) {
-	if (typeof scrubRange === "number" && Number.isFinite(scrubRange) && scrubRange > 0) return scrubRange;
-	const size = typeof step === "number" && Number.isFinite(step) && step > 0 ? step : 1;
+	if (Number.isFinite(scrubRange) && scrubRange > 0) return scrubRange;
+	const size = Number.isFinite(step) && step > 0 ? step : 1;
 	return size * SCRUB_RANGE_STEPS;
 }
 
@@ -95,7 +95,7 @@ export function createScrubGesture({ x, value, step, precision, scrubRange }) {
  * 1.7000000000000002 in the input.
  */
 export function snapScrubValue(value, { step, precision = 2 } = {}) {
-	const size = typeof step === "number" && Number.isFinite(step) && step > 0 ? step : 0;
+	const size = Number.isFinite(step) && step > 0 ? step : 0;
 	const snapped = size > 0 ? Math.round(value / size) * size : value;
 	const digits = Number.isFinite(precision) ? Math.max(0, Math.min(15, Math.round(precision))) : 2;
 	return Number(snapped.toFixed(digits));

package/src/ui.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { createScrubGesture } from "./ui-scrub.js";
+import { isImeComposing } from "./ime.js";
 
 // Custom dropdown, structurally matched to the reference (`.dropdown`,
 // `dd-caret`, `dropdown-menu`, `dropdown-item`, `dd-check`) with the keyboard
@@ -279,7 +280,7 @@ export function Field({ label, children }) {
 		</div>
 	);
 }
-export function NumberField({ label, value, step, precision = 2, scrubRange, onChange, onScrubStart, onScrubEnd, title }) {
+export function NumberField({ label, value, step, precision = 2, scrubRange, onChange, onScrubStart, onScrubEnd, title, disabled = false }) {
 	const [focused, setFocused] = useState(false);
 	const [draft, setDraft] = useState(null);
 	// The draft must be readable synchronously: blur() fires the commit
@@ -335,7 +336,7 @@ export function NumberField({ label, value, step, precision = 2, scrubRange, onC
 	};
 
 	const onKeyDown = (e) => {
-		if (e.key === "Enter") {
+		if (e.key === "Enter" && !isImeComposing(e)) {
 			e.preventDefault();
 			commitDraft();
 			// Keep focus and select the committed value so the next keystroke
@@ -357,7 +358,7 @@ export function NumberField({ label, value, step, precision = 2, scrubRange, onC
 	// alone was a 15 px hotspot nobody found). Sensitivity is a fixed-travel
 	// rate (src/ui-scrub.js), not pixels * step, so every field feels the same.
 	const onFieldPointerDown = (e) => {
-		if (e.button !== 0) return;
+		if (e.button !== 0 || disabled) return;
 		// A press inside an already-focused input is text editing (caret
 		// placement, drag-select), not a scrub — leave it alone.
 		if (focused && e.target === inputRef.current) return;
@@ -460,7 +461,7 @@ export function NumberField({ label, value, step, precision = 2, scrubRange, onC
 
 	return (
 		<span
-			className={`number-field v2-details-number-field${focused ? " editing" : ""}`}
+			className={`number-field v2-details-number-field${focused ? " editing" : ""}${disabled ? " disabled" : ""}`}
 			title={title}
 			onPointerDown={onFieldPointerDown}
 			onPointerUp={endFieldDrag}
@@ -472,6 +473,7 @@ export function NumberField({ label, value, step, precision = 2, scrubRange, onC
 				type="text"
 				inputMode="decimal"
 				value={display}
+				disabled={disabled}
 				onFocus={onFocus}
 				onBlur={onBlur}
 				onChange={(e) => setDraftValue(e.target.value)}

package/src/use-asset-shelf.js

@@ -0,0 +1,60 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ASSET_DELETE_UNDO_MS } from "./app-stage.jsx";
+import { CUTOUT_KIND, MESH_KIND } from "./scene-objects.js";
+import { assetGraphSignature } from "./scene-assets.js";
+
+export function useAssetShelf({ scenes, activeSceneId, sceneObjects }) {
+	// The imported-pictures region of the Assets shelf. null = the scan has
+	// never resolved (the pane shows skeletons, NEVER the empty message); an
+	// array = the SOURCE ids to show, mattes and cut renders already filtered
+	// out (asset-shelf.js). Scans run only while the shelf is visible, and
+	// re-run when a cutout's lineage changes — not on every transform tick, so
+	// a gizmo drag never hammers IndexedDB.
+	const [shelfImageIds, setShelfImageIds] = useState(null);
+	const [shelfMeshIds, setShelfMeshIds] = useState(null);
+	const [manageAssetStorage, setManageAssetStorage] = useState(false);
+	// A separate scan preserves the source-only placement shelf while the
+	// manager exposes every unreachable stored record, including matte and cut
+	// derivatives orphaned with a deleted card.
+	const [unusedAssetIds, setUnusedAssetIds] = useState(null);
+	const [usedAssetIds, setUsedAssetIds] = useState(null);
+	const [usageCounts, setUsageCounts] = useState(new Map());
+	const assetShelfScanTokenRef = useRef(0);
+	const legacyDerivedIdsRef = useRef(new Set());
+	// This is deliberately session-only. Each entry is a complete IndexedDB
+	// record, so Undo can put it back byte-for-byte until the page is reloaded.
+	const [assetTrash, setAssetTrash] = useState([]);
+	// Same rule as the object deletion offer: the toast is a window, not a
+	// banner. Only the OFFER expires — the trashed record itself is the restore
+	// data, so it is deliberately kept for the session and never timed out.
+	const [assetUndoOffered, setAssetUndoOffered] = useState(false);
+	useEffect(() => {
+		if (!assetUndoOffered) return undefined;
+		const timer = setTimeout(() => setAssetUndoOffered(false), ASSET_DELETE_UNDO_MS);
+		return () => clearTimeout(timer);
+	}, [assetUndoOffered]);
+	const [deletingAssetId, setDeletingAssetId] = useState(null);
+	const cutoutLineage = useMemo(
+		() => JSON.stringify(sceneObjects.flatMap((object) => (object.renderer === CUTOUT_KIND ? [[object.assetId, object.sourceAssetId, object.matteAssetId]] : []))),
+		[sceneObjects],
+	);
+	const meshLineage = useMemo(
+		() => JSON.stringify(sceneObjects.flatMap((object) => (object.renderer === MESH_KIND ? [object.assetId] : []))),
+		[sceneObjects],
+	);
+	const projectCutoutLineage = useMemo(() => {
+		const allScenes = scenes.map((scene) => (scene.id === activeSceneId ? { ...scene, objects: sceneObjects } : scene));
+		return JSON.stringify(
+			allScenes.flatMap((scene) =>
+				(Array.isArray(scene.objects) ? scene.objects : []).flatMap((object) =>
+					object.renderer === CUTOUT_KIND ? [[object.assetId, object.sourceAssetId, object.matteAssetId]] : [],
+				),
+			),
+		);
+	}, [scenes, activeSceneId, sceneObjects]);
+	const projectAssetGraphSignature = useMemo(() => {
+		const allScenes = scenes.map((scene) => (scene.id === activeSceneId ? { ...scene, objects: sceneObjects } : scene));
+		return assetGraphSignature(allScenes);
+	}, [scenes, activeSceneId, sceneObjects]);
+	return { shelfImageIds, setShelfImageIds, shelfMeshIds, setShelfMeshIds, manageAssetStorage, setManageAssetStorage, unusedAssetIds, setUnusedAssetIds, usedAssetIds, setUsedAssetIds, usageCounts, setUsageCounts, assetShelfScanTokenRef, legacyDerivedIdsRef, assetTrash, setAssetTrash, assetUndoOffered, setAssetUndoOffered, deletingAssetId, setDeletingAssetId, cutoutLineage, meshLineage, projectCutoutLineage, projectAssetGraphSignature };
+}

package/src/use-camera-tutorial.js

@@ -0,0 +1,50 @@
+import { useRef, useState } from "react";
+import { cameraTutorialSuppressed } from "./first-shot-handoff.js";
+import { loadProjectSession } from "./project.js";
+import { SCENES_STORAGE_KEY } from "./scenes.js";
+
+export function useCameraTutorial({ embedMode, playgroundMode }) {
+	// The camera tutorial (#206): the landing page's seven steps, run against
+	// the real studio instead of the playground iframe. It opens from
+	// /app/?tutorial=camera or from Settings ▾, and it is not offered inside an
+	// embed.
+
+	// Both doors go through startCameraTutorial (#209), which puts the studio in
+	// the state the landing page teaches these steps in — the city-block starter
+	// scene with the walk take on its character — so Shot / Rail / Play always
+	// have something to frame. That function is declared with the project
+	// actions further down; the listeners here reach it through a ref so they
+	// always call the current render's closure (the confirm reads projectDirty).
+	const [cameraTutorialEntry] = useState(() => {
+		const params = new URLSearchParams(globalThis.location?.search || "");
+		const query = params.get("tutorial") === "camera";
+		let firstRun = false;
+		try {
+			firstRun = !query && !params.get("scene") && !cameraTutorialSuppressed()
+				&& !loadProjectSession()?.name && !globalThis.localStorage?.getItem(SCENES_STORAGE_KEY);
+		} catch { firstRun = false; }
+		return !embedMode && !playgroundMode && !cameraTutorialSuppressed() && (query ? "query" : firstRun ? "first-run" : null);
+	});
+	const cameraTutorialQuery = Boolean(cameraTutorialEntry);
+	const [cameraTutorial, setCameraTutorial] = useState(false);
+	const cameraTutorialAnalytics = useRef(null);
+	const [cameraTutorialAttempt, setCameraTutorialAttempt] = useState(0);
+	const [cameraTutorialHandoff, setCameraTutorialHandoff] = useState(null);
+	const cameraTutorialCompletedRef = useRef(false);
+	const exportMenuTriggerRef = useRef(null);
+	const exportShotIdRef = useRef(null);
+	// The step the tutorial is on, published on the .app root so styles.css can
+	// spotlight the one control that step needs (#211).
+	const [cameraTutorialStep, setCameraTutorialStep] = useState(null);
+	const startCameraTutorialRef = useRef(null);
+	const cameraTutorialStarted = useRef(false);
+	// A tutorial restart never reloads the starter over the user's edits.
+	const tutorialStarterRef = useRef(false);
+	const tutorialLoadingRef = useRef(false);
+	const tutorialProjectEpochRef = useRef(0);
+	const tutorialSeedEpochRef = useRef(null);
+	// Armed once the starter is applied, consumed by the seed effect next to the
+	// hosted-demo seed as soon as the new character's rig exists.
+	const [tutorialSeedPending, setTutorialSeedPending] = useState(false);
+	return { cameraTutorialEntry, cameraTutorialQuery, cameraTutorial, setCameraTutorial, cameraTutorialAnalytics, cameraTutorialAttempt, setCameraTutorialAttempt, cameraTutorialHandoff, setCameraTutorialHandoff, cameraTutorialCompletedRef, exportMenuTriggerRef, exportShotIdRef, cameraTutorialStep, setCameraTutorialStep, startCameraTutorialRef, cameraTutorialStarted, tutorialStarterRef, tutorialLoadingRef, tutorialProjectEpochRef, tutorialSeedEpochRef, tutorialSeedPending, setTutorialSeedPending };
+}

package/src/use-embed-bridge.js

@@ -0,0 +1,12 @@
+import { useRef, useState } from "react";
+import { isPlaygroundEmbed } from "./playground.js";
+
+export function useEmbedBridge() {
+	const embedMode = ["scene", "playview"].includes(new URLSearchParams(globalThis.location?.search || "").get("embed"));
+	// The landing page's try-it iframe: full studio interaction on a preset
+	// scene with the project chrome hidden and saving off (see playground.js).
+	const playgroundMode = isPlaygroundEmbed(globalThis.location?.search);
+	const [playgroundHint, setPlaygroundHint] = useState(null);
+	const playgroundExportRef = useRef(null);
+	return { embedMode, playgroundMode, playgroundHint, setPlaygroundHint, playgroundExportRef };
+}

package/src/use-first-success-prompt.js

@@ -0,0 +1,7 @@
+import { useState } from "react";
+
+export function useFirstSuccessPrompt() {
+	const [firstSuccessGuideOpen, setFirstSuccessGuideOpen] = useState(false);
+	const [useCaseAskOpen, setUseCaseAskOpen] = useState(false);
+	return { firstSuccessGuideOpen, setFirstSuccessGuideOpen, useCaseAskOpen, setUseCaseAskOpen };
+}

package/src/use-i2v-capture-modal.js

@@ -0,0 +1,15 @@
+import { useState } from "react";
+
+export function useI2vCaptureModal() {
+	const [i2vMotionEnabled, setI2vMotionEnabled] = useState(false);
+	const [i2vMotionMode, setI2vMotionMode] = useState("interpolate");
+	const [i2vMotionCameraUnlocked, setI2vMotionCameraUnlocked] = useState(false);
+	return {
+		i2vMotionEnabled,
+		setI2vMotionEnabled,
+		i2vMotionMode,
+		setI2vMotionMode,
+		i2vMotionCameraUnlocked,
+		setI2vMotionCameraUnlocked,
+	};
+}

package/src/use-sculpt-mode.js

@@ -0,0 +1,95 @@
+import { useEffect, useRef, useState } from "react";
+import { createAgentTransport } from "./workflow/agent-client.js";
+import { requestAgentImage, stylizeErrorMessage } from "./agent-image-client.js";
+import { blueprintErrorMessage, blueprintRequest } from "./sculpt-blueprint.js";
+import { agentSessionReady, createCommandTap, sculptModelChoice, sculptTargetFromSelection, storeSculptModel } from "./sculpt-mode.js";
+import { SCULPT_KIND } from "./scene-objects.js";
+
+export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId }) {
+	// Sculpt mode (#739): one sculpt on an isolated turntable, the Sculpt panel
+	// and its agent run. The target is the sculpt selected on entry, or a new one
+	// the first run creates; picking another sculpt while here retargets.
+	const sculptMode = workflowMode === "sculpt";
+	const sculptCamRef = useRef(null);
+	const [sculptTargetId, setSculptTargetId] = useState(null);
+	const [sculptView, setSculptView] = useState({ view: "front", nonce: 0 });
+	const [sculptReference, setSculptReference] = useState(null);
+	const [sculptRun, setSculptRun] = useState(null);
+	const sculptRunRef = useRef(null);
+	const [sculptAgentStatus, setSculptAgentStatus] = useState("unknown");
+	// The model Sculpt runs on (its own pick, remembered apart from the chat model) and the list it comes from.
+	const [sculptModels, setSculptModels] = useState({ state: "loading", providers: [], models: [] });
+	const [sculptModelPick, setSculptModelPick] = useState({ model: "", effort: null });
+	const chooseSculptModel = (next) => setSculptModelPick((current) => {
+		const choice = { ...current, ...next };
+		storeSculptModel(choice);
+		return choice;
+	});
+	const [sculptTransport] = useState(() => createAgentTransport({ surface: "studio" }));
+	const [sculptTap] = useState(createCommandTap);
+	const sculptTarget = sceneObjects.find((object) => object.id === sculptTargetId && object.renderer === SCULPT_KIND) ?? null;
+	const requestSculptView = (view) => setSculptView((current) => ({ view, nonce: current.nonce + 1 }));
+	useEffect(() => {
+		if (!sculptMode) return;
+		setSculptTargetId(sculptTargetFromSelection(sceneObjects, selectedSceneObjectId));
+		requestSculptView("front");
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [sculptMode]);
+	useEffect(() => {
+		const selected = sculptMode ? sculptTargetFromSelection(sceneObjects, selectedSceneObjectId) : null;
+		if (selected) setSculptTargetId(selected);
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [selectedSceneObjectId]);
+	// Start needs the Agent panel's readiness rule (signed in, or a provider
+	// key in the sidecar); a sign-in finished in another window lands on focus.
+	useEffect(() => {
+		if (!sculptMode) return undefined;
+		let live = true;
+		const read = () => {
+			sculptTransport.status().then(
+				(status) => { if (live) setSculptAgentStatus(agentSessionReady(status) ? "ready" : "signed-out"); },
+				() => { if (live) setSculptAgentStatus("signed-out"); },
+			);
+			// The Agent panel's catalogue: a key added or removed elsewhere changes what can run.
+			sculptTransport.models().then(
+				(advertised) => {
+					if (!live) return;
+					const list = Array.isArray(advertised?.models) ? advertised.models : [];
+					setSculptModels({ state: list.length ? "ready" : "failed", providers: advertised?.providers ?? [], models: list });
+					setSculptModelPick((current) => sculptModelChoice(advertised, current));
+				},
+				() => { if (live) setSculptModels((current) => ({ ...current, state: current.models.length ? current.state : "failed" })); },
+			);
+		};
+		read();
+		window.addEventListener("focus", read);
+		return () => { live = false; window.removeEventListener("focus", read); };
+	}, [sculptMode, sculptTransport]);
+	// The blueprint step: the reference turned into a four-view model sheet by one image request.
+	const [sculptBlueprint, setSculptBlueprint] = useState({ state: "idle", pose: "keep", notes: "", sheet: null, error: null, startedAt: null });
+	const blueprintAbortRef = useRef(null);
+	async function generateSculptBlueprint() {
+		if (!sculptReference) return;
+		blueprintAbortRef.current?.abort();
+		const controller = new AbortController();
+		blueprintAbortRef.current = controller;
+		const startedAt = Date.now();
+		setSculptBlueprint((current) => ({ ...current, state: "generating", error: null, startedAt }));
+		try {
+			const result = await requestAgentImage(blueprintRequest({ reference: sculptReference, pose: sculptBlueprint.pose, notes: sculptBlueprint.notes }), { signal: controller.signal });
+			if (blueprintAbortRef.current !== controller) return;
+			setSculptBlueprint((current) => ({ ...current, state: "ready", sheet: { dataUrl: result.dataUrl, width: result.width, height: result.height, ms: Date.now() - startedAt } }));
+		} catch (error) {
+			if (blueprintAbortRef.current !== controller) return;
+			const cancelled = controller.signal.aborted;
+			setSculptBlueprint((current) => ({ ...current, state: current.sheet ? "ready" : "idle", error: cancelled ? null : blueprintErrorMessage(error, stylizeErrorMessage(error).replace(/^Stylize failed — |^스타일화 실패 — /, "")) }));
+		}
+	}
+	function cancelSculptBlueprint() {
+		const controller = blueprintAbortRef.current;
+		blueprintAbortRef.current = null;
+		controller?.abort();
+		setSculptBlueprint((current) => ({ ...current, state: current.sheet ? "ready" : "idle" }));
+	}
+	return { sculptMode, sculptCamRef, sculptView, sculptReference, setSculptReference, sculptRun, setSculptRun, sculptRunRef, sculptAgentStatus, sculptModels, sculptModelPick, chooseSculptModel, sculptTransport, sculptTap, sculptTarget, setSculptTargetId, requestSculptView, sculptBlueprint, setSculptBlueprint, generateSculptBlueprint, cancelSculptBlueprint };
+}