cozyclay 2.0.2 → 2.1.1

package/src/workflow/agent-client.js

@@ -13,7 +13,7 @@
 //   POST /oauth/logout  -> { ok }
 //   POST /agent/turn    -> SSE, lines of `data: {json}`
 //   POST /agent/stop    -> { ok }
-//   GET  /agent/models  -> { providers: [{ id, label, signedIn, models }], models: [flat] }
+//   GET  /agent/models  -> { providers: [{ id, label, signedIn, models }], models: [flat], roles: { byMain } }
 //   POST /agent/turn/<turnId>/steer -> { ok, queued } while that turn streams
 //
 // Studio hosts add the frozen task-1 contracts on the same routes:
@@ -21,14 +21,16 @@
 //   GET  /agent/turn/<turnId>/events?after=N -> replay after a dropped stream
 //   POST /agent/stop                        -> { surface, sessionId, turnId, jobId? }
 //   POST /agent/jobs/<jobId>/accept          -> explicit "Apply with warnings"
+//   GET  /agent/turn/<turnId>/supervisor     -> 200 supervisor note | 204 none (#728)
 
 import { bucketMs, track } from "../analytics.js";
 import { appendAttachments, ATTACHMENT_MAX_COUNT } from "./attachment-image.js";
 import { ko } from "../locale.js";
 import { AGENT_TOOL_CATEGORIES, EXECUTION_TELEMETRY_VALUES } from "../execution-telemetry.js";
 import { STUDIO_VARIANTS, validateReceipt } from "../studio-agent-protocol.js";
+import { requestAgentImage, sidecarRequest, sidecarUrl } from "../agent-image-client.js";
 
-export const AGENT_PANEL_WIDTH_KEY = "cozyclay.workflow.agentPanel.width";
+const AGENT_PANEL_WIDTH_KEY = "cozyclay.workflow.agentPanel.width";
 export const AGENT_PANEL_WIDTH_DEFAULT = 360;
 export const AGENT_PANEL_WIDTH_MIN = 300;
 export const AGENT_PANEL_WIDTH_MAX = 560;
@@ -125,7 +127,7 @@ export const SUGGESTION_CHIPS = [
 /** Previs asks, in the Studio's own words: short enough to read at a glance in
  * the Inspector column, and every one of them is something the Studio families
  * can actually do. */
-export const STUDIO_SUGGESTION_CHIPS = [
+const STUDIO_SUGGESTION_CHIPS = [
 	ko("Block a two-shot", "\uD22C\uC0F7 \uBE14\uB85C\uD0B9"),
 	ko("Frame the selected character", "\uC120\uD0DD\uD55C \uCE90\uB9AD\uD130 \uAD6C\uB3C4 \uC7A1\uAE30"),
 	ko("Light the set warmer", "\uC138\uD2B8 \uC870\uBA85 \uB354 \uB530\uB73B\uD558\uAC8C"),
@@ -263,6 +265,27 @@ export function storeModel(key, storage = globalThis.localStorage) {
 	}
 }
 
+/** The supervisor switch (#728): on unless the author turned it off. It rides
+ * on every Studio turn as `supervisor: false` so the sidecar skips the review
+ * for that turn; the sidecar's own COZYCLAY_SUPERVISOR=off still wins. */
+const AGENT_SUPERVISOR_KEY = "cozyclay.agent.supervisor";
+
+export function readStoredSupervisor(storage = globalThis.localStorage) {
+	try {
+		return storage?.getItem(AGENT_SUPERVISOR_KEY) !== "off";
+	} catch {
+		return true;
+	}
+}
+
+export function storeSupervisor(enabled, storage = globalThis.localStorage) {
+	try {
+		storage?.setItem(AGENT_SUPERVISOR_KEY, enabled ? "on" : "off");
+	} catch {
+		// Private-mode storage denial must never break the toggle.
+	}
+}
+
 /** The model to open with: the remembered key when it is still advertised,
  * otherwise the first model the sidecar listed. */
 export function preferredModel(models, stored = readStoredModel()) {
@@ -293,6 +316,20 @@ export function nextSelectedModel(providers, models, current) {
 	return preferredModel(models.filter((entry) => modelIsSelectable(providers, entry.id)));
 }
 
+/** The roles the sidecar derived for one main model (#717): `{ helper, vision,
+ * advisor, fallback }`, each a `provider/id` key. Read-only here — nothing the
+ * panel sends depends on it — so a malformed entry is simply not shown. */
+export function selectedModelRoles(byMain, key) {
+	const entry = byMain && typeof byMain === "object" && typeof key === "string" ? byMain[key] : null;
+	return entry && ["helper", "vision", "advisor"].every((role) => typeof entry[role] === "string" && entry[role]) ? entry : null;
+}
+
+/** A `provider/id` key without its provider, for a line that has no room for it. */
+export function shortModelId(key) {
+	const value = String(key ?? "");
+	return value.slice(value.indexOf("/") + 1);
+}
+
 /** "resets in 42m" / "resets in 1h 05m" for the account strip and the paused
  * card countdown. Returns null when there is nothing to count down to. */
 export function formatResetIn(resetAt, now = Date.now()) {
@@ -340,6 +377,28 @@ export const STEER_ERROR_COPY = {
 	NO_ACTIVE_TURN: "That turn already ended — send it as a new message.",
 };
 
+/** Codes a Studio refusal carries: a turn that met one is reviewed by the
+ * supervisor even when it authored nothing (#728). */
+const SUPERVISOR_REFUSAL = /^(TARGET_NOT_READY|CAPABILITY_MISSING|CONFIRMATION_REQUIRED):/;
+
+/** The next prompt a supervisor note suggests: its blocker and concern issues,
+ * or null when it raised none. A note with validated fixes (#743) asks for
+ * exactly those run_action calls, in order, in one script; the blockers and
+ * concerns without a fix follow under their own header. */
+export function supervisorFollowUp(note) {
+	const all = Array.isArray(note?.issues) ? note.issues : [];
+	const fixes = (Array.isArray(note?.fixes) ? note.fixes : []).filter((fix) => typeof fix?.action === "string" && fix.args && typeof fix.args === "object");
+	const fixed = new Set(fixes.map((fix) => fix.issueIndex));
+	const issues = all.filter((issue, index) => (issue?.severity === "blocker" || issue?.severity === "concern") && !fixed.has(index));
+	const line = (issue) => `- [${issue.severity}] ${issue.text}${issue.evidence ? ` (${issue.evidence})` : ""}`;
+	if (!fixes.length) return issues.length ? [ko("Supervisor review — please address:", "감독 검토 — 다음을 고쳐 주세요:"), ...issues.map(line)].join("\n") : null;
+	return [
+		ko("Supervisor review — apply these fixes exactly, in order, in ONE script call, then verify_result; do not re-derive them:", "감독 검토 — 아래 수정을 유추 없이 순서대로 script 1회로 실행하고 verify_result로 확인해 주세요:"),
+		...fixes.map((fix) => `- [${fix.severity}] ${all[fix.issueIndex]?.text ?? ""} -> run_action ${JSON.stringify({ action: fix.action, args: fix.args })}`),
+		...(issues.length ? [ko("Also check:", "추가 확인:"), ...issues.map(line)] : []),
+	].join("\n");
+}
+
 export const ERROR_COPY = {
 	auth: "Your session expired. Sign in again to continue.",
 	entitlement: "This account cannot generate images.",
@@ -348,8 +407,6 @@ export const ERROR_COPY = {
 	overloaded: "The model service is overloaded right now. Try again in a moment.",
 };
 
-// --- activity line ---------------------------------------------------------
-//
 // Silence is the failure mode this replaces: a live turn says what it is doing
 // and a finished turn says how it ended, in the same line, so "nothing on
 // screen" can never mean "nobody knows".
@@ -445,14 +502,6 @@ export function parseSseChunk(buffer) {
 	return { events, tail };
 }
 
-// --- real transport (loopback sidecar) ------------------------------------
-
-const SIDECAR_ORIGIN = "";
-
-function sidecarUrl(path) {
-	return `${SIDECAR_ORIGIN}${path}`;
-}
-
 const validTelemetryId = (value) => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
 const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown"]);
 const exactKeys = (value, keys) => value && typeof value === "object" && !Array.isArray(value)
@@ -574,7 +623,7 @@ const RESUME_ATTEMPTS = 3;
  * — it only needs the variable's NAME, so an env-backed provider can say which
  * variable is already holding one instead of offering an input that would be
  * ignored. */
-export const PROVIDER_ENV_VARS = {
+const PROVIDER_ENV_VARS = {
 	anthropic: ["ANTHROPIC_API_KEY"],
 	openai: ["OPENAI_API_KEY"],
 	google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
@@ -590,26 +639,7 @@ export function providerEnvLabel(id) {
 
 export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalThis), surface, capture = track, now = () => performance.now() } = {}) {
 	const activeTurns = new Map();
-	const request = async (path, init) => {
-		const response = await fetchImpl(sidecarUrl(path), {
-			headers: { "content-type": "application/json" },
-			...init,
-		});
-		if (!response.ok) {
-			let detail = null;
-			try { detail = await response.clone().json(); } catch { /* preserve the status when the server did not send JSON */ }
-			const message = typeof detail?.error === "string" ? detail.error : detail?.error?.message;
-			const error = new Error(message || `${path} responded ${response.status}`);
-			// Keep machine-readable verification evidence alongside the human message.
-			// The Workflow node can show why an H3 take was rejected without exposing
-			// or retaining the rejected video itself.
-			error.status = response.status;
-			if (detail?.error && typeof detail.error === "object") Object.assign(error, detail.error);
-			if (detail?.preservation && typeof detail.preservation === "object") error.preservation = detail.preservation;
-			throw error;
-		}
-		return response.json();
-	};
+	const request = (path, init) => sidecarRequest(fetchImpl, path, init);
 	return {
 		mock: false,
 		async status() {
@@ -635,6 +665,10 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 			const providers = Array.isArray(result?.providers)
 				? result.providers.filter((provider) => provider?.id && Array.isArray(provider.models))
 				: [];
+			// The derived model roles (#717) ride along untouched; a sidecar without
+			// them simply leaves the roles line hidden.
+			const byMain = result?.roles?.byMain;
+			if (byMain && typeof byMain === "object" && !Array.isArray(byMain)) return { providers, models, roles: { byMain } };
 			return { providers, models };
 		},
 		/** Steering a turn that is STILL streaming. The id is the one this browser
@@ -682,8 +716,8 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 		// `references` are the scene's identity / environment slots (#167): extra
 		// attached pictures with a role, passed through untouched so the sidecar
 		// decides how they are described to the model.
-		async image({ prompt, imageDataUrl, referenceDataUrl, references, quality = "auto" }, signal) {
-			return request("/agent/image", { method: "POST", body: JSON.stringify({ prompt, imageDataUrl, ...(referenceDataUrl ? { referenceDataUrl } : {}), ...(Array.isArray(references) && references.length ? { references } : {}), quality }), signal });
+		async image(payload, signal) {
+			return requestAgentImage(payload, { fetchImpl, signal });
 		},
 		async video(payload, signal) {
 			return request("/agent/video", { method: "POST", body: JSON.stringify(payload), signal });
@@ -691,9 +725,18 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 		async videoProviders() {
 			return request("/agent/video/providers");
 		},
+		/** The supervisor note for a finished Studio turn (#728): one long-poll
+		 * the sidecar holds while the review runs. A 200 is the note; a 204, a
+		 * failure or anything unreadable is no note. */
+		async supervisor(turnId, signal) {
+			const response = await fetchImpl(sidecarUrl(`/agent/turn/${encodeURIComponent(turnId)}/supervisor`), { headers: { accept: "application/json" }, credentials: "same-origin", signal });
+			if (response?.status !== 200) return null;
+			const note = await response.json();
+			return note?.type === "supervisor" && ["reviewed", "unavailable"].includes(note.verdict) ? note : null;
+		},
 		/** Streams sidecar events to `onEvent`. Resolves when the turn ends. */
 		async turn(turnRequest, onEvent, signal) {
-			const { sessionId, text, attachFrame, model, effort, attachments } = turnRequest;
+			const { sessionId, text, attachFrame, model, effort, attachments, supervisor } = turnRequest;
 			const attached = Array.isArray(attachments) && attachments.length ? { attachments } : {};
 			const studio = turnRequest.surface === "studio";
 			const turnId = studio ? turnRequest.turnId : null;
@@ -748,7 +791,7 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 			const body = studio
 				? JSON.stringify({
 					surface: "studio", sessionId, turnId, text, context: turnRequest.context,
-					...(model ? { model } : {}), ...(effort ? { effort } : {}), ...(attachFrame === undefined ? {} : { attachFrame: Boolean(attachFrame) }), ...attached,
+					...(model ? { model } : {}), ...(effort ? { effort } : {}), ...(attachFrame === undefined ? {} : { attachFrame: Boolean(attachFrame) }), ...(supervisor === false ? { supervisor: false } : {}), ...attached,
 				})
 				: JSON.stringify({ sessionId, text, attachFrame, model, ...(effort ? { effort } : {}), ...attached, ...(telemetry.turnId ? { turn_id: telemetry.turnId } : {}) });
 			try {
@@ -798,8 +841,7 @@ export function createHttpTransport({ fetchImpl = globalThis.fetch?.bind(globalT
 	};
 }
 
-// --- mock transport (QA) ---------------------------------------------------
-
+// --- mock transport (QA) ---
 /** ?agent=mock turns the panel onto a scripted transport so every state in the
  * issue can be reached and screenshotted before the sidecar exists. */
 export function mockConfigFromSearch(search = globalThis.location?.search || "") {
@@ -902,7 +944,7 @@ const MOCK_PROVIDER_MODELS = {
 const MOCK_LIVE_ONLY_CODEX_MODEL = { id: "gpt-6-live-preview", label: "gpt-6 live preview", efforts: ["none", "low", "medium", "high"], defaultEffort: "high" };
 /** The shortest key the scripted sidecar will store, so QA can drive the
  * refusal path (PUT → 400) without a real provider. */
-export const MOCK_PROVIDER_KEY_MIN = 8;
+const MOCK_PROVIDER_KEY_MIN = 8;
 /** How many times the scripted sidecar answered /oauth/status. The panel reads
  * the session once per credential write and never on a timer (#379), and this
  * is how browser QA proves it without reaching inside the component. */
@@ -1107,8 +1149,6 @@ export function createAgentTransport(options = {}) {
 	return config ? createMockTransport({ surface: options.surface, ...config }) : createHttpTransport(options);
 }
 
-// --- chat store (framework-free) -------------------------------------------
-//
 // One conversation: session identity, transcript, motion jobs, receipts and
 // acknowledged image actions. It lives here rather than inside the component so
 // the dock, an embedded Studio host and the test runner drive the SAME state
@@ -1119,7 +1159,7 @@ export function createAgentTransport(options = {}) {
  * already committed belongs to its receipt, not here; anything short of an
  * explicit not-applied answer stays unknown, because the alternative is telling
  * an author the scene is clean when nobody checked. */
-export function stopOutcome(result) {
+function stopOutcome(result) {
 	const outcome = result?.outcome;
 	if (outcome?.status === "already_applied") return null;
 	if (outcome && outcome.mutated === false) return { status: "not_applied", code: outcome.code ?? "CANCELLED", mutated: false };
@@ -1171,6 +1211,9 @@ export function createAgentChatStore({
 	// turnId, or the hex id the dock's transport mints. It is what the steer
 	// route is keyed by, and only the transport can tell us which it is.
 	let wireTurnId = null;
+	// Supervisor note requests still waiting on the sidecar; a cleared or
+	// replaced conversation abandons them.
+	const supervisorRequests = new Set();
 	let state = {
 		sessionId: newId(),
 		turnId: null,
@@ -1262,8 +1305,29 @@ export function createAgentChatStore({
 		try { onReceipt?.(receipt); } catch { /* host presentation is advisory */ }
 	}
 
+	// One request per reviewable Studio turn, after its stream ended: the note
+	// joins the transcript whenever it arrives, and nothing waits for it.
+	function requestSupervisorNote(turnId) {
+		if (typeof transport.supervisor !== "function") return;
+		const request = new AbortController();
+		supervisorRequests.add(request);
+		Promise.resolve()
+			.then(() => transport.supervisor(turnId, request.signal))
+			.then((note) => {
+				if (!note || request.signal.aborted) return;
+				setItems((items) => [...items, { ...note, kind: "supervisor", id: `supervisor:${turnId}` }]);
+			})
+			.catch(() => { /* a missing note is no note */ })
+			.finally(() => supervisorRequests.delete(request));
+	}
+	const abandonSupervisorNotes = () => { for (const request of supervisorRequests) request.abort(); supervisorRequests.clear(); };
+
 	function applyEvent(event) {
 		if (activeTurn && ["text.delta", "tool.start", "tool.done", "image", "job.state", "job.progress", "receipt", "error"].includes(event?.type)) activeTurn.produced = true;
+		// The supervisor's own trigger, read from the same frames: an authored
+		// result or a refusal makes the turn reviewable.
+		if (activeTurn && ((event?.type === "tool.done" && (event.ok ? event.result?.authored === true : SUPERVISOR_REFUSAL.test(String(event.error ?? ""))))
+			|| (event?.type === "receipt" && event.receipt?.authored === true))) activeTurn.reviewable = true;
 		if (event?.type === "text.delta") {
 			setItems((items) => {
 				const last = items[items.length - 1];
@@ -1341,6 +1405,7 @@ export function createAgentChatStore({
 	}
 
 	const resetSession = () => {
+		abandonSupervisorNotes();
 		seenReceipts.clear();
 		settledActions.clear();
 		// Clearing the transcript also retires the server session: a cleared chat
@@ -1348,6 +1413,7 @@ export function createAgentChatStore({
 		set({ sessionId: newId(), turnId: null, items: [], pendingAttachments: [], rateLimit: null, lastPrompt: "", turnStartedAt: null, lastTurn: null });
 	};
 	const restore = (transcript, sessionId = state.sessionId) => {
+		abandonSupervisorNotes();
 		seenReceipts.clear();
 		settledActions.clear();
 		const restoredReceiptIds = new Set();
@@ -1404,7 +1470,7 @@ export function createAgentChatStore({
 				return;
 			}
 			const startedAt = clock();
-			const turn = { produced: false, failure: null };
+			const turn = { produced: false, failure: null, reviewable: false };
 			activeTurn = turn;
 			// What the author attached to THIS message: an explicit list wins, the
 			// composer's pending pictures otherwise. Either way the composer is
@@ -1435,6 +1501,7 @@ export function createAgentChatStore({
 					attachFrame: Boolean(options.attachFrame),
 					model: options.model,
 					effort: options.effort ?? undefined,
+					...(options.supervisor === false ? { supervisor: false } : {}),
 				}, applyEvent, signal);
 			} catch (error) {
 				if (!signal.aborted) applyEvent({ type: "error", code: "upstream", message: String(error?.message || error) });
@@ -1460,6 +1527,7 @@ export function createAgentChatStore({
 							failure: turn.failure,
 						},
 					});
+					if (studio && turn.reviewable && options.supervisor !== false && !signal.aborted) requestSupervisorNote(turnId);
 				}
 			}
 		},

package/src/workflow/agent-panel.css

@@ -744,6 +744,16 @@
 
 .agent-receipt-summary { line-height: 1.5; word-break: break-word; }
 
+/* The supervisor note (#728) reads quieter than the turn it reviews. */
+.agent-supervisor-card { display: flex; flex-direction: column; gap: var(--agent-space-2); padding: var(--agent-space-3) var(--agent-space-4); border-style: dashed; background: var(--agent-bg-sunken); color: var(--agent-text-muted); font-size: var(--agent-font-md); }
+.agent-supervisor-head { display: flex; align-items: center; gap: var(--agent-space-2); }
+.agent-supervisor-toggle { margin-left: auto; }
+.agent-supervisor-summary { margin: 0; line-height: 1.5; word-break: break-word; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 3; overflow: hidden; }
+.agent-supervisor-card[data-open="true"] .agent-supervisor-summary { display: block; }
+.agent-supervisor-badge.blocker { border-color: var(--agent-alert-edge); background: var(--agent-alert-bg); color: var(--agent-alert); }
+.agent-supervisor-fix { display: block; margin-top: var(--agent-space-1); font: var(--agent-font-sm) ui-monospace, monospace; white-space: pre-wrap; word-break: break-all; color: var(--agent-text-dim); }
+.agent-supervisor-badge.note { border-color: var(--agent-border-strong); background: transparent; color: var(--agent-text-dim); }
+
 .agent-failure-card { border-color: #6d3a52; background: #2a1c26; }
 .agent-failure-code {
 	color: var(--agent-alert);
@@ -1097,6 +1107,16 @@
 
 .agent-model-select option:disabled { color: var(--agent-text-dim); }
 
+/* The selected model's derived roles (#717): one muted, read-only line. */
+.agent-model-roles {
+	margin: var(--agent-space-1) 0 0;
+	overflow: hidden;
+	white-space: nowrap;
+	text-overflow: ellipsis;
+	color: var(--agent-text-dim);
+	font-size: var(--agent-font-sm);
+}
+
 .agent-composer-picks { margin-bottom: var(--agent-space-2); }
 .agent-effort-select { flex: 0 0 auto; width: auto; max-width: 42%; }
 .agent-composer-spacer { flex: 1; }
@@ -1171,3 +1191,18 @@
 	.agent-resize { display: none; }
 }
 }
+
+/* The supervisor switch beside the model picks (#728). */
+.agent-supervisor-toggle {
+	flex: 0 0 auto;
+	font: inherit;
+	font-size: 12px;
+	padding: 4px 8px;
+	border-radius: 6px;
+	border: 1px solid var(--agent-border, #444);
+	background: transparent;
+	color: var(--agent-text-dim, #999);
+	cursor: pointer;
+}
+.agent-supervisor-toggle.is-on { color: var(--agent-text, #ddd); border-color: var(--agent-border-focus, #6a9); }
+.agent-supervisor-toggle:focus-visible { outline: 2px solid var(--agent-border-focus, #6a9); outline-offset: 1px; }

package/src/workflow/attachment-image.js

@@ -17,7 +17,7 @@ export const ATTACHMENT_MAX_BYTES = 4 * 1024 * 1024;
 export const ATTACHMENT_JPEG_QUALITY = 0.85;
 /** The turn envelope accepts exactly these three, so the composer refuses the
  * rest here rather than letting the sidecar reject a turn the author sent. */
-export const ATTACHMENT_TYPES = Object.freeze(["image/png", "image/jpeg", "image/webp"]);
+const ATTACHMENT_TYPES = Object.freeze(["image/png", "image/jpeg", "image/webp"]);
 export const ATTACHMENT_LIMIT_NOTICE = "Up to 4 images per message";
 export const ATTACHMENT_TYPE_NOTICE = "Attach a PNG, JPEG or WebP image";
 export const ATTACHMENT_FAILED_NOTICE = "That image could not be attached";

package/src/workflow/canvas-commands.js

@@ -49,10 +49,10 @@ export function createCanvasCommands({ store, makeNode, nodeSchemas }) {
 	const handlers = {
 		get_graph: () => { const graph = clone(current()); return { ...graph, nodes: graph.nodes.map((node) => ({ id: node.id, type: node.type, model: node.data?.model || null, data: node.data, position: node.position })), outputs: Object.fromEntries(graph.nodes.map((node) => [node.id, node.data?.outputs || []])) }; },
 		add_node: ({ type, model, data = {}, position } = {}) => { const next = mutate((graph) => {
-			if (typeof type !== "string" || !type || !["text", "image", "video", "audio", "api", "video-combiner", "scene", "upload", "concat", "motion-input", "shot-prompt"].includes(type)) throw new Error("Unknown node type");
+			if (!["text", "image", "video", "audio", "api", "video-combiner", "scene", "upload", "concat", "motion-input", "shot-prompt"].includes(type)) throw new Error("Unknown node type");
 			if (position && (!Number.isFinite(position.x) || !Number.isFinite(position.y))) throw new Error("position must contain finite x and y");
 			const id = `${type}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
-			const modelValue = typeof model === "string" ? model : model;
+			const modelValue = model;
 			const node = makeNode(type, id, position || nextFreePosition(graph), modelValue || null, nodeSchemas);
 			if (modelValue && typeof modelValue === "string") {
 				const models = nodeSchemas?.categories?.[schemaCategoryForType(type)]?.models || {};
@@ -71,5 +71,5 @@ export function createCanvasCommands({ store, makeNode, nodeSchemas }) {
 		undo: () => { const previous = history.pop(); if (!previous) return { undone: false }; publish(previous); return { undone: true, graph: clone(previous) }; },
 		history,
 	};
-	return { ...handlers, handlers, undo: handlers.undo, history };
+	return { ...handlers, handlers };
 }

package/src/workflow/cozy-scene-node.js

@@ -8,14 +8,14 @@
  */
 
 export const COZY_SCENE_NODE_TYPE = "cozyclay-scene";
-export const COZY_SCENE_NODE_VERSION = 1;
+const COZY_SCENE_NODE_VERSION = 1;
 
 export const COZY_SCENE_INPUTS = Object.freeze([
 	{ id: "asset", label: "Asset", kind: "asset" },
 	{ id: "motion", label: "Motion", kind: "motion", legacy: true },
 ]);
 
-export const COZY_SCENE_CHARACTER_HANDLE_PREFIX = "character:";
+const COZY_SCENE_CHARACTER_HANDLE_PREFIX = "character:";
 
 /** Return the stable Scene target handle for a cast member. */
 export function sceneCharacterHandle(characterId) {
@@ -46,7 +46,6 @@ export function sceneInputSpecs(characters = [], { includeLegacyMotion = true }
 	return specs;
 }
 
-/** Build the Scene input state represented by ReactFlow edges. */
 /** Restrict Scene inputs to values the Scene can actually consume. */
 export function sceneConnectionAllowed(source, targetHandle, sourceData = {}) {
 	const type = typeof source === "string" ? source : source?.type;
@@ -56,6 +55,7 @@ export function sceneConnectionAllowed(source, targetHandle, sourceData = {}) {
 	return false;
 }
 
+/** Build the Scene input state represented by ReactFlow edges. */
 export function sceneInputsFromEdges(edges, sceneNodeId) {
 	const assetInputs = [];
 	const motionInputs = [];

package/src/workflow/local-workflow.js

@@ -16,13 +16,13 @@ export function executeLocalWorkflowGraph(graph, { runId = `local-${Date.now()}`
 	const updates = new Map();
 	const order = [];
 	while (remaining.size) {
-		const ready = [...remaining].filter((id) => (incoming.get(id) || []).every((edge) => !remaining.has(edge.source)));
+		const ready = [...remaining].filter((id) => incoming.get(id).every((edge) => !remaining.has(edge.source)));
 		const batch = ready.length ? ready : [...remaining];
 		for (const id of batch) { remaining.delete(id); order.push(id); }
 	}
 	for (const id of order) {
 		const node = nodeById.get(id);
-		const inputs = (incoming.get(id) || []).map((edge) => values.get(edge.source)).filter((value) => value !== undefined);
+		const inputs = incoming.get(id).map((edge) => values.get(edge.source)).filter((value) => value !== undefined);
 		const output = localNodeOutput(node, inputs);
 		values.set(id, output);
 		const run = { id: runId, status: "complete", result: { outputs: [{ value: output }] } };

package/src/workflow/motion-input.js

@@ -1,7 +1,7 @@
 import { SCENES_STORAGE_KEY, readSceneDocument } from "../scenes.js";
 
-export const MOTION_INPUT_NODE_TYPE = "motion-input";
-export const MOTION_INPUT_NODE_VERSION = 1;
+const MOTION_INPUT_NODE_TYPE = "motion-input";
+const MOTION_INPUT_NODE_VERSION = 1;
 
 function text(value, fallback = "") {
 	return typeof value === "string" ? value : fallback;
@@ -69,7 +69,7 @@ export function characterMotionPatch(characterId, input = {}) {
 	return {
 		characterId: data.characterId || null,
 		motionRef: {
-			...(data.motionRef && typeof data.motionRef === "object" ? clone(data.motionRef) : {}),
+			...(data.motionRef ? clone(data.motionRef) : {}),
 			url: data.url || data.objectUrl || null,
 			fileName: data.fileName || null,
 			mimeType: data.mimeType,

package/src/workflow/node-schema.js

@@ -38,7 +38,7 @@ export function schemaModelEntries(nodeSchemas, category) {
 	return Object.entries(models).map(([id, model]) => ({ ...model, id, name: model.name || id.replace(/-/g, " ") }));
 }
 
-export function schemaForModel(nodeSchemas, category, modelId) {
+function schemaForModel(nodeSchemas, category, modelId) {
 	const model = nodeSchemas?.categories?.[category]?.models?.[modelId];
 	const input = model?.input_schema || {};
 	return input?.schemas?.input_data || input;

package/src/workflow/scene-asset-sync.js

@@ -34,13 +34,6 @@ function objectHasAsset(object, assetId) {
 	return [object.assetId, object.sourceAssetId, object.matteAssetId].includes(assetId);
 }
 
-/** Return the document's active scene without exposing a mutable reference. */
-export function activeSceneRecord(document) {
-	const scenes = Array.isArray(document?.scenes) ? document.scenes : [];
-	const index = activeSceneIndex(scenes, document?.activeSceneId);
-	return index < 0 ? null : scenes[index] ?? null;
-}
-
 /**
  * Add an imported image as a cutout in the active scene.
  *
@@ -116,7 +109,7 @@ export function readStoredSceneDocument(storage = globalThis.localStorage) {
 }
 
 /** Persist a scene envelope and notify both local and remote Studio tabs. */
-export function publishSceneDocument(document, {
+function publishSceneDocument(document, {
 	storage = globalThis.localStorage,
 	target = globalThis,
 } = {}) {
@@ -204,7 +197,7 @@ export function subscribeToScenePlayback(onCommand, {
 }
 
 /** Import bytes through the canonical asset pipeline and warm the texture cache. */
-export async function importWorkflowImage(file, {
+async function importWorkflowImage(file, {
 	importer = importImageFile,
 	remember = rememberAsset,
 	importOptions,

package/src/workflow/shot-prompt-node.js

@@ -3,7 +3,7 @@
 // the unit test share one definition of what a Shot Prompt node produces.
 import { buildShotPrompt } from "../shot-prompt.js";
 
-export const SHOT_PROMPT_TARGETS = Object.freeze(["image", "video"]);
+const SHOT_PROMPT_TARGETS = Object.freeze(["image", "video"]);
 
 /** Defaults a fresh Shot Prompt node starts with. */
 export function shotPromptNodeData() {

package/src/workflow/video-contract.js

@@ -1,6 +1,6 @@
 // Fal H3 Max Turbo I2V schema: https://fal.ai/models/minimax/h3-max-turbo/image-to-video/api
 export const DEFAULT_FAL_VIDEO_MODEL = "minimax/h3-max-turbo/image-to-video";
-export const COMFY_VIDEO_ASPECTS = Object.freeze(["16:9", "9:16", "1:1", "21:9", "12:7"]);
+const COMFY_VIDEO_ASPECTS = Object.freeze(["16:9", "9:16", "1:1", "21:9", "12:7"]);
 
 export function falVideoContract(model = DEFAULT_FAL_VIDEO_MODEL) {
 	if (model === DEFAULT_FAL_VIDEO_MODEL) return { name: "H3 Max Turbo", aspectFromImage: true, cameraLocked: true, aspects: [], minDuration: 5, maxDuration: 15, integerDuration: true, defaultDuration: 5, resolution: ["480P", "768P", "1080P"], defaultResolution: "480P" };

package/src/workflow/workflow-resources.js

@@ -52,8 +52,6 @@ export function outputKind(value) {
 	return value.trim() ? "other" : null;
 }
 
-/* ------------------------------------------------------------- paths ---- */
-
 function outputPaths(data) {
 	const paths = [["resultUrl"], ["videoUrl"], ["lastOutput", "renderUrl"], ["lastOutput", "sceneUrl"], ["fileUrl"]];
 	if (Array.isArray(data.versions)) data.versions.forEach((_, index) => paths.push(["versions", index, "dataUrl"]));
@@ -106,8 +104,6 @@ async function mapOutputs(graph, visit) {
 	return { ...graph, nodes };
 }
 
-/* -------------------------------------------------------------- refs ---- */
-
 /**
  * Every output slot that holds something, with where it lives and what it is.
  * `field` reads like a path (`versions[2].dataUrl`) so a manifest row can point
@@ -126,8 +122,6 @@ export function workflowOutputRefs(graph) {
 	return refs;
 }
 
-/* ----------------------------------------------------------- data URLs -- */
-
 function bytesToBase64(bytes) {
 	let binary = "";
 	for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
@@ -196,8 +190,6 @@ export function imageDimensions(bytes) {
 	return null;
 }
 
-/* --------------------------------------------------------- intern/resolve */
-
 /**
  * Save path. Every `data:image/*` output becomes `{ assetRef }` and the bytes
  * come back once per distinct picture as an asset record in the shape the