cozyclay 2.0.0 → 2.1.0

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 };
+}

package/src/workflow/AgentPanel.jsx

@@ -8,6 +8,9 @@ import {
 	attachmentFromFile,
 	transferCarriesFiles,
 } from "./attachment-image.js";
+import { isImeComposing } from "../ime.js";
+import { useStudioShell } from "../shell/studio-shell-context.js";
+import { ko } from "../locale.js";
 import {
 	AGENT_PANEL_OVERLAY_BREAKPOINT,
 	AGENT_PANEL_RAIL_WIDTH,
@@ -34,9 +37,14 @@ import {
 	formatElapsed,
 	formatResetIn,
 	readStoredPanelWidth,
+	readStoredSupervisor,
 	storeModel,
 	storePanelWidth,
+	storeSupervisor,
 	STUDIO_SESSION_STORAGE_KEY,
+	selectedModelRoles,
+	shortModelId,
+	supervisorFollowUp,
 } from "./agent-client.js";
 import "./agent-panel.css";
 
@@ -122,6 +130,18 @@ function PausedCard({ resetAt, onRetry, onSwitchModel }) {
 	</div>;
 }
 
+// The lineup the sidecar derived for the selected model (#717), read-only:
+// what a turn may lean on beside it. Vision is named only when it is not the
+// selected model itself.
+function ModelRolesLine({ model, roles }) {
+	if (!roles) return null;
+	const parts = [[ko("helper", "보조"), roles.helper], [ko("advisor", "자문"), roles.advisor]];
+	if (roles.vision !== model) parts.push([ko("vision", "비전"), roles.vision]);
+	return <p className="agent-model-roles" data-agent-model-roles="true">
+		{parts.map(([label, key]) => `${label} · ${shortModelId(key)}`).join(" · ")}
+	</p>;
+}
+
 // A generation is a server-owned job. The card shows the state the runtime
 // reported, the phase it named and only a progress value it actually sent.
 function JobCard({ job, onStop, onAccept }) {
@@ -182,6 +202,47 @@ function ReceiptCard({ item }) {
 	</div>;
 }
 
+const SUPERVISOR_SEVERITY_COPY = { blocker: ko("blocker", "차단"), concern: ko("concern", "우려"), note: ko("note", "참고") };
+const SUPERVISOR_STATUS_COPY = { done: ko("done", "완료"), partial: ko("partial", "일부"), refused: ko("refused", "거부됨"), missing: ko("missing", "누락") };
+
+// The supervisor's note on a finished Studio turn (#728): muted, collapsed to
+// its summary and counts, and never acted on by itself. Its one action puts
+// the blockers and concerns into the composer as the author's next turn.
+function SupervisorCard({ note, onSend, defaultOpen = false }) {
+	const [open, setOpen] = useState(defaultOpen);
+	if (note.verdict !== "reviewed") return <div className="agent-card agent-supervisor-card" data-supervisor-verdict="unavailable">
+		<p className="agent-supervisor-summary">{ko("Supervisor review unavailable", "감독 검토를 할 수 없었어요")}{note.reason ? ` — ${note.reason}` : ""}</p>
+	</div>;
+	const followUp = supervisorFollowUp(note);
+	// Validated run_action drafts (#743), shown under the issue each one fixes.
+	const fixes = Array.isArray(note.fixes) ? note.fixes : [];
+	return <div className="agent-card agent-supervisor-card" data-supervisor-verdict="reviewed" data-open={open ? "true" : "false"}>
+		<div className="agent-supervisor-head">
+			<span className="agent-job-label">{ko("Supervisor", "감독")}</span>
+			{["blocker", "concern", "note"].filter((severity) => note.counts?.[severity] > 0).map((severity) => <span key={severity} className={`agent-job-badge agent-supervisor-badge ${severity}`} data-severity={severity}>{note.counts[severity]} {SUPERVISOR_SEVERITY_COPY[severity]}</span>)}
+			<button type="button" className="agent-ghost-button agent-supervisor-toggle" aria-expanded={open} onClick={() => setOpen((value) => !value)}>{open ? ko("Less", "접기") : ko("Details", "자세히")}</button>
+		</div>
+		<p className="agent-supervisor-summary">{note.summary}</p>
+		{open && note.items?.length > 0 && <ul className="agent-receipt-notes agent-supervisor-items">
+			{note.items.map((item, index) => <li key={index} data-status={item.status}>{SUPERVISOR_STATUS_COPY[item.status] ?? item.status} · {item.text}{item.evidence ? ` — ${item.evidence}` : ""}</li>)}
+		</ul>}
+		{open && note.issues?.length > 0 && <ul className="agent-receipt-notes agent-supervisor-issues">
+			{note.issues.map((issue, index) => {
+				const fix = fixes.find((entry) => entry.issueIndex === index);
+				return <li key={index} data-severity={issue.severity}>{SUPERVISOR_SEVERITY_COPY[issue.severity] ?? issue.severity} · {issue.text}{issue.evidence ? ` — ${issue.evidence}` : ""}
+					{fix && <code className="agent-supervisor-fix" data-fix-action={fix.action}>{`run_action ${JSON.stringify({ action: fix.action, args: fix.args })}`}</code>}
+				</li>;
+			})}
+		</ul>}
+		{followUp && <div className="agent-job-actions">
+			<button type="button" className="agent-ghost-button agent-supervisor-send" onClick={() => onSend(followUp)}
+				title={note.autofix?.eligible ? ko("Autofix is on: the blocker fixes would be applied as written", "자동 수정 켜짐: 차단 수정안을 적힌 그대로 적용합니다") : undefined}>
+				{fixes.length ? ko("Apply fixes as next prompt", "수정안 다음 턴으로 보내기") : ko("Send as next prompt", "다음 턴으로 보내기")}
+			</button>
+		</div>}
+	</div>;
+}
+
 const RECOVERY_COPY = {
 	none: "No recovery is available for this command.",
 	inspect: "Ask the agent to inspect the target before trying again.",
@@ -286,6 +347,11 @@ export default function AgentPanel({
 	const transport = useMemo(() => injectedTransport || createAgentTransport({ surface }), [injectedTransport, surface]);
 	const mockState = transport.mock ? transport.state : null;
 
+	// Inside the studio the title names the project's previs mode (#650).
+	const previsMode = useStudioShell()?.previsMode;
+	const titleMode = surface === "studio" && previsMode
+		? (previsMode === "storyboard" ? ko("Storyboard", "스토리보드") : ko("Animation", "애니메이션"))
+		: null;
 	const [collapsed, setCollapsed] = useState(defaultCollapsed);
 	// Only the dock owns a width; an embedded host sizes the panel itself and
 	// never reads the dock's stored key.
@@ -302,6 +368,8 @@ export default function AgentPanel({
 	const [modelProviders, setModelProviders] = useState([]);
 	const [model, setModel] = useState("");
 	const [modelsState, setModelsState] = useState("loading");
+	// The roles derived per main model (#717); shown, never sent or stored.
+	const [modelRoles, setModelRoles] = useState(null);
 	// null = the model's backend default; picking a model resets it.
 	const [effort, setEffort] = useState(null);
 	const efforts = useMemo(() => effortOptions(models.find((entry) => entry.id === model)), [models, model]);
@@ -309,6 +377,10 @@ export default function AgentPanel({
 	// remembered so a reload does not quietly move the next turn to another
 	// provider's model.
 	const chooseModel = useCallback((id) => { setModel(id); setEffort(null); storeModel(id); }, []);
+	// The supervisor switch (#728): a preference like the model pick. Off skips
+	// the post-turn review for every turn sent from this panel.
+	const [supervisorOn, setSupervisorOn] = useState(() => readStoredSupervisor());
+	const toggleSupervisor = useCallback(() => setSupervisorOn((current) => { storeSupervisor(!current); return !current; }), []);
 	// One place takes `{ providers, models }` from the sidecar: the grouped list
 	// the dropdown draws, the flat key-addressed list every lookup uses, and the
 	// model to open with. Returns false when nothing was advertised.
@@ -318,6 +390,7 @@ export default function AgentPanel({
 		const providers = Array.isArray(advertised?.providers) ? advertised.providers : [];
 		setModelProviders(providers);
 		setModels(list);
+		setModelRoles(advertised?.roles?.byMain ?? null);
 		// A saved or removed key arrives through this same path, so a selection the
 		// panel opened with is dropped here the moment its provider cannot run it.
 		setModel((current) => nextSelectedModel(providers, list, current));
@@ -345,6 +418,7 @@ export default function AgentPanel({
 	const [restoreReady, setRestoreReady] = useState(surface !== "studio");
 
 	const composerRef = useRef(null);
+	const focusPendingRef = useRef(false);
 	const transcriptRef = useRef(null);
 
 	// The host's context builder and image-action handler are read through refs
@@ -382,10 +456,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);
@@ -399,7 +475,6 @@ export default function AgentPanel({
 		try { globalThis.localStorage?.setItem(STUDIO_SESSION_STORAGE_KEY, chat.sessionId); } catch { /* storage may be unavailable */ }
 	}, [chat.sessionId, restoreReady, surface]);
 
-	// --- activity line -----------------------------------------------------
 	// One line that always states what the panel is doing, ticking while a turn
 	// is live and holding the turn's outcome for a few seconds after it ends.
 	const [activityNow, setActivityNow] = useState(() => Date.now());
@@ -414,7 +489,6 @@ export default function AgentPanel({
 		return () => clearInterval(timer);
 	}, [activity.ticking]);
 
-	// --- session bootstrap -------------------------------------------------
 	// Two ways in (#379): the ChatGPT sign-in, or a provider key the sidecar
 	// already holds. `providersConfigured` counts the second, so a session that
 	// never signed in to ChatGPT still gets a composer instead of a sign-in wall
@@ -518,7 +592,6 @@ export default function AgentPanel({
 		store.send("Give me a wide two-shot of this scene", { attachFrame: false, model });
 	}, [authState, items.length, mockState, model, store]);
 
-	// --- layout ------------------------------------------------------------
 	useEffect(() => {
 		if (embedded) return;
 		const onResize = () => setOverlay((globalThis.innerWidth || 1440) < AGENT_PANEL_OVERLAY_BREAKPOINT);
@@ -555,7 +628,10 @@ export default function AgentPanel({
 	// Focus moves to the composer whenever the panel opens. The composer only
 	// mounts once the session resolves, so authState is a dependency too:
 	// otherwise this fires against a composer that does not exist yet. A hidden
-	// embedded panel never pulls focus out of the host's own surface.
+	// embedded panel never pulls focus out of the host's own surface. An
+	// embedded panel never collapses itself (its host hides it), so shown means
+	// open there: without that the Studio composer opened unfocused and the
+	// next Cmd+V landed on the stage.
 	useEffect(() => {
 		if (hidden) {
 			// Chrome blurs a hidden focused field only on its next lifecycle step;
@@ -563,8 +639,12 @@ export default function AgentPanel({
 			if (composerRef.current && composerRef.current === document.activeElement) composerRef.current.blur();
 			return;
 		}
-		if (!collapsed) composerRef.current?.focus();
-	}, [authState, collapsed, hidden]);
+		if (!(embedded || !collapsed)) return;
+		composerRef.current?.focus();
+		// A composer still waiting on the model list is disabled and refuses
+		// focus; the open is remembered so it lands once the composer enables.
+		focusPendingRef.current = document.activeElement !== composerRef.current;
+	}, [authState, collapsed, embedded, hidden]);
 
 	useEffect(() => {
 		const node = transcriptRef.current;
@@ -595,12 +675,13 @@ export default function AgentPanel({
 		});
 	}, []);
 
-	// --- pasted and dropped pictures ---------------------------------------
 	// A screenshot is the fastest thing an author can show the agent, so the
 	// composer takes one from the clipboard or the desktop. Only a transfer that
 	// actually carries a picture is intercepted: a text paste still lands in the
 	// caret, which is the whole reason the studio's document handler steps aside
-	// for a textarea in the first place.
+	// for a textarea in the first place. The paste is taken on the composer
+	// block, not the textarea, so the Send and model buttons a click just left
+	// focus on do not hand the picture to the stage.
 	const attachFiles = useCallback(async (files) => {
 		const prepared = [];
 		let failed = 0;
@@ -610,7 +691,6 @@ export default function AgentPanel({
 		const rejected = prepared.length ? store.addAttachments(prepared).rejected : 0;
 		setAttachNotice(rejected ? ATTACHMENT_LIMIT_NOTICE : failed ? ATTACHMENT_FAILED_NOTICE : null);
 	}, [store]);
-	/** Whether this transfer belongs to the composer. */
 	const takeTransfer = useCallback((transfer) => {
 		const { images, unsupported } = attachmentFilesFromTransfer(transfer);
 		if (!images.length) {
@@ -641,12 +721,11 @@ export default function AgentPanel({
 		if (takeTransfer(event.dataTransfer)) event.preventDefault();
 	}, [takeTransfer]);
 
-	// --- turn --------------------------------------------------------------
 	const runTurn = useCallback((text) => {
 		setAttachNotice(null);
 		setSteerNotice("");
-		return store.send(text, { attachFrame, model, effort: effort ?? undefined });
-	}, [attachFrame, effort, model, store]);
+		return store.send(text, { attachFrame, model, effort: effort ?? undefined, supervisor: supervisorOn });
+	}, [attachFrame, effort, model, store, supervisorOn]);
 	const stopTurn = useCallback(() => store.stop(), [store]);
 	// Steering the turn that is already running: the composer's text joins THAT
 	// turn instead of starting a second one. A refusal (the turn ended while the
@@ -715,7 +794,6 @@ export default function AgentPanel({
 		}
 	}, [store, transport]);
 
-	// --- provider keys -----------------------------------------------------
 	// The section is read when it opens; every write goes back through the
 	// refresh above, because a key changes the session, not just a row.
 	const toggleProviderKeys = useCallback(() => {
@@ -759,7 +837,7 @@ export default function AgentPanel({
 			stopTurn();
 			return;
 		}
-		if (event.key === "Enter" && !event.shiftKey) {
+		if (event.key === "Enter" && !isImeComposing(event) && !event.shiftKey) {
 			event.preventDefault();
 			// Enter does what the button under it says: Send, or Steer while a turn
 			// on a steerable surface is still running.
@@ -782,6 +860,13 @@ export default function AgentPanel({
 	// can send to: the composer stays shut instead of submitting a turn the
 	// provider would refuse.
 	const composerDisabled = panelState === "rate-limited" || !model || !modelIsSelectable(modelProviders, model);
+	useEffect(() => {
+		if (hidden) focusPendingRef.current = false;
+		if (hidden || composerDisabled || !focusPendingRef.current) return;
+		focusPendingRef.current = false;
+		// Only claim focus nobody else has taken in the meantime.
+		if (!document.activeElement || document.activeElement === document.body) composerRef.current?.focus();
+	}, [composerDisabled, hidden]);
 
 	if (collapsed && !embedded) {
 		return <aside className="agent-panel collapsed" data-agent-state={panelState} data-agent-collapsed="true" aria-label="Agent panel, collapsed">
@@ -819,7 +904,7 @@ export default function AgentPanel({
 
 		<header className="agent-header">
 			<StatusDot tone={statusTone} title={panelState} />
-			<h2 className="agent-title">Agent</h2>
+			<h2 className="agent-title" data-previs-mode={titleMode ? previsMode : undefined}>{titleMode ? `Agent · ${titleMode}` : "Agent"}</h2>
 			<span className="agent-header-spacer" />
 			<button type="button" className="agent-icon-button agent-new" aria-label="New conversation" title="New conversation" onClick={newSession}><FiPlus size={14} aria-hidden="true" /></button>
 			{presentation.history && <span className="agent-history-wrap">
@@ -904,6 +989,7 @@ export default function AgentPanel({
 				if (item.kind === "job") return <div className="agent-row" key={item.id}><JobCard job={item} onStop={stopTurn} onAccept={(job) => store.acceptJob(job.jobId)} /></div>;
 				if (item.kind === "receipt") return <div className="agent-row" key={item.id}><ReceiptCard item={item} /></div>;
 				if (item.kind === "failure") return <div className="agent-row" key={item.id}><FailureCard failure={item.failure} onRetry={() => runTurn(chat.lastPrompt)} /></div>;
+				if (item.kind === "supervisor") return <div className="agent-row" key={item.id}><SupervisorCard note={item} onSend={(text) => { store.setDraft(text); runTurn(text); }} /></div>;
 				return <div className="agent-row" key={item.id}><ImageResultCard image={item} onUse={(image) => store.applyImage(image.id)} onUndo={(image) => store.undoImage(image.id)} onRegenerate={() => runTurn(chat.lastPrompt)} onOpen={setLightbox} /></div>;
 			})}
 
@@ -923,6 +1009,7 @@ export default function AgentPanel({
 			onDragOver={composerDisabled ? undefined : onComposerDragOver}
 			onDragLeave={composerDisabled ? undefined : onComposerDragLeave}
 			onDrop={composerDisabled ? undefined : onComposerDrop}
+			onPaste={composerDisabled ? undefined : onComposerPaste}
 		>
 			{pendingAttachments.length > 0 && <ul className="agent-attachments" aria-label="Attached images">
 				{pendingAttachments.map((attachment) => <li key={attachment.id} className="agent-attachment">
@@ -931,8 +1018,6 @@ export default function AgentPanel({
 				</li>)}
 			</ul>}
 			{attachNotice && <p className="agent-attachment-notice" role="status">{attachNotice}</p>}
-			{/* One field: the message, and under it on the same surface the
-			    frame toggle, the model and effort picks, and Send. */}
 			<div className="agent-field">
 				<textarea
 					ref={composerRef}
@@ -943,7 +1028,6 @@ export default function AgentPanel({
 					disabled={composerDisabled}
 					onChange={(event) => store.setDraft(event.target.value)}
 					onKeyDown={onComposerKeyDown}
-					onPaste={onComposerPaste}
 					onDragOver={onComposerDragOver}
 					onDrop={onComposerDrop}
 				/>
@@ -972,6 +1056,11 @@ export default function AgentPanel({
 							{efforts.map((value, index) => <option key={value} value={value} title={index === 0 ? "Default for this model" : undefined}>{value}</option>)}
 						</select>
 					)}
+					{surface === "studio" && (
+						<button type="button" className={`agent-supervisor-toggle${supervisorOn ? " is-on" : ""}`} role="switch" aria-checked={supervisorOn} aria-label={ko("Supervisor review", "감독 검토")} title={ko(supervisorOn ? "Supervisor review is on: a note arrives after each editing turn" : "Supervisor review is off", supervisorOn ? "감독 검토 켜짐: 편집 턴이 끝나면 메모가 옵니다" : "감독 검토 꺼짐")} onClick={toggleSupervisor}>
+							{ko("Supervisor", "감독")} {supervisorOn ? "ON" : "OFF"}
+						</button>
+					)}
 					<span className="agent-composer-spacer" aria-hidden="true" />
 					{surface === "studio" && i2vActionRef.current && <button
 						type="button"
@@ -993,6 +1082,7 @@ export default function AgentPanel({
 						</>
 						: <button type="button" className="agent-send" aria-label="Send" title="Send (Enter)" disabled={composerDisabled || !draft.trim()} onClick={() => runTurn(draft)}><FiArrowUp size={14} aria-hidden="true" /></button>}
 				</div>
+				<ModelRolesLine model={model} roles={selectedModelRoles(modelRoles, model)} />
 			</div>
 		</div>}
 		{/* The hint exists to warn about image spend; a surface that cannot

package/src/workflow/WorkflowBuilder.jsx

@@ -14,7 +14,7 @@ import { Toaster, toast } from "react-hot-toast";
 import { loadWorkflowGraph, normalizeWorkflowGraph, storeWorkflowGraph, WORKFLOW_STORAGE_KEY } from "../project.js";
 import AgentPanel from "./AgentPanel.jsx";
 import CozySceneNode from "./CozySceneNode.jsx";
-import { applyCozyScenePatch, normalizeCozySceneData, sceneConnectionAllowed, toCozySceneRunRequest } from "./cozy-scene-node.js";
+import { applyCozyScenePatch, normalizeCozySceneData, sceneConnectionAllowed } from "./cozy-scene-node.js";
 import { activeSceneCharacters, characterHandleId, characterIdFromHandle, normalizeMotionInputData, motionInputOutput } from "./motion-input.js";
 import { DEFAULT_NODE_SCHEMAS, defaultFormValues, schemaCategoryForType, schemaModelEntries, schemaProperties } from "./node-schema.js";
 import { executeLocalWorkflowGraph } from "./local-workflow.js";