cozyclay 3.2.0 → 3.2.1

package/src/update/update-client.js

@@ -2,12 +2,21 @@
 // (bin/update-routes.mjs) read and driven from the page. Pure apart from the
 // injected fetch, timers, storage and window, so test/verify-update-client.mjs
 // drives it under Node. A page without window.__COZYCLAY_RUNTIME__ (the hosted
-// site, Vite dev) makes no request at all.
+// site, Vite dev) makes no request at all. Tabs share a dismiss, an install
+// start and a phase change at once (U2): over a BroadcastChannel, or through a
+// storage event where there is none. A hint only makes a tab fetch now; the
+// launcher's answer stays the only phase a tab shows. Restart now (U2b, #960)
+// hands the launcher to the new version and waits for it to answer.
 export const UPDATE_URL = "/__cozyclay/update";
+export const RESTART_URL = "/__cozyclay/update/restart";
+export const RESTART_WAIT_MS = 30_000;
+export const RESTART_POLL_MS = 1000;
 export const DISMISS_KEY = "cozyclay:update-dismissed";
 export const POLL_MS = 6 * 60 * 60 * 1000;
 export const VISIBLE_STALE_MS = 60 * 60 * 1000;
 export const UPDATING_POLL_MS = 2000;
+export const CHANNEL_NAME = "cozyclay:update";
+export const HINT_KEY = "cozyclay:update-hint";
 
 const VERSION = /^\d+\.\d+\.\d+$/;
 const KINDS = new Set(["global", "npx", "clone"]);
@@ -42,16 +51,17 @@ export function normalizeUpdateInfo(body) {
 		phase,
 		errorClass: phase === "failed" ? (ERROR_CLASSES.has(body.errorClass) ? body.errorClass : "other") : null,
 		durationMs: Number.isFinite(body.durationMs) && body.durationMs >= 0 ? body.durationMs : null,
+		installed: version(body.installed),
 		// Opened in a new tab, so only the project's own release page is accepted.
 		notesUrl: latest && body.notesUrl === `${NOTES_PREFIX}${latest}` ? body.notesUrl : null,
 		command: kind === "npx" ? NPX_COMMAND : GLOBAL_COMMAND,
 	};
 }
 
-async function request(fetchImpl, init, win) {
+async function request(fetchImpl, init, win, url = UPDATE_URL) {
 	if (!hasLauncherRuntime(win) || typeof fetchImpl !== "function") return null;
 	try {
-		const response = await fetchImpl(UPDATE_URL, { cache: "no-store", credentials: "same-origin", ...init });
+		const response = await fetchImpl(url, { cache: "no-store", credentials: "same-origin", ...init });
 		if (!response?.ok) return null;
 		return normalizeUpdateInfo(await response.json());
 	} catch {
@@ -65,6 +75,16 @@ export const fetchUpdateInfo = (fetchImpl = globalThis.fetch?.bind(globalThis),
 /** POST: ask the launcher to install `latest`. The 202 body, or null (403/409/network). No body is sent. */
 export const startUpdate = (fetchImpl = globalThis.fetch?.bind(globalThis), win = globalThis.window) => request(fetchImpl, { method: "POST" }, win);
 
+/** POST: hand the launcher to the installed version. The 202 body, or null (403/409/network). No body is sent. */
+export const requestRestart = (fetchImpl = globalThis.fetch?.bind(globalThis), win = globalThis.window) => request(fetchImpl, { method: "POST" }, win, RESTART_URL);
+
+/** After the new launcher answers: reload only a saved project. True when it reloaded. */
+export function reloadAfterRestart({ dirty, reload }) {
+	if (dirty) return false;
+	reload();
+	return true;
+}
+
 /** patch | minor | major: how far `current` is behind `latest`. */
 export function behindOf(current, latest) {
 	const [a, b] = [current, latest].map((value) => (version(value) ?? "0.0.0").split(".").map(Number));
@@ -83,16 +103,24 @@ export function updateBlocked({ agentRunning = false, exportStatus = null, recSt
 
 const HIDDEN = Object.freeze({ view: "hidden", actions: [] });
 
-/** The chip and dialog view for one poll result and the local dismiss state ({ dismissed }). */
+const RESTART_ACTIONS = { restarting: [], restarted: ["reload"], restart_timeout: ["copy_command"] };
+
+/**
+ * The chip and dialog view for one poll result and the local state: { dismissed }, and { restart }
+ * (restarting | restarted | restart_timeout) once Restart now ran here or in another tab.
+ */
 export function nextUpdateState(info, local = {}) {
 	if (!info || !info.enabled) return HIDDEN;
 	const base = {
 		current: info.current, latest: info.latest, kind: info.kind, notesUrl: info.notesUrl,
 		command: info.command, canSelfUpdate: info.canSelfUpdate, errorClass: null,
 	};
+	if (RESTART_ACTIONS[local.restart]) return { ...base, latest: local.target ?? info.latest, view: local.restart, command: RESTART_COMMAND, actions: RESTART_ACTIONS[local.restart] };
 	const oneClick = info.kind === "global" && info.canSelfUpdate;
-	if (info.phase === "updating") return { ...base, view: "updating", actions: [] };
-	if (info.phase === "restart_needed") return { ...base, view: "restart_needed", command: RESTART_COMMAND, actions: ["copy_command"] };
+	// "Installing X" and "Updated to X" name the version npm installs, which the registry may have passed since.
+	const installed = info.installed ?? info.latest;
+	if (info.phase === "updating") return { ...base, latest: installed, view: "updating", actions: [] };
+	if (info.phase === "restart_needed") return { ...base, latest: installed, view: "restart_needed", command: RESTART_COMMAND, actions: ["restart", "copy_command"] };
 	if (info.phase === "failed") {
 		return { ...base, view: "failed", errorClass: info.errorClass ?? "other", command: GLOBAL_COMMAND,
 			actions: oneClick ? ["retry", "copy_command"] : ["copy_command"] };
@@ -115,6 +143,13 @@ export function writeDismissed(latest, storage = safeStorage()) {
 	try { storage.setItem(DISMISS_KEY, latest); return true; } catch { return false; }
 }
 
+const HINTS = new Set(["dismiss", "install", "phase", "restart"]);
+
+// A missing or throwing BroadcastChannel is null: hints then travel as a storage event.
+function openUpdateChannel() {
+	try { return typeof globalThis.BroadcastChannel === "function" ? new globalThis.BroadcastChannel(CHANNEL_NAME) : null; } catch { return null; }
+}
+
 const defaultTimers = {
 	set: (fn, ms) => setTimeout(fn, ms),
 	clear: (timer) => clearTimeout(timer),
@@ -131,40 +166,97 @@ const defaultTimers = {
  * The poll loop: once after the first frame and idle, every 6 h, on a visible
  * tab whose last check is over 1 h old, every 2 s while installing. `onState`
  * gets { state, info } after every change. Returns { dismiss, update, stop }.
+ * `channel` is a BroadcastChannel-shaped object (default: one is opened when
+ * the browser has it); null sends the other tabs' hints through `storage`.
+ * restart() and a restart hint poll every 1 s, failures included, until the
+ * launcher's `current` is the installed version, for up to 30 s.
  */
 export function createUpdatePoller({
 	fetchImpl = globalThis.fetch?.bind(globalThis), onState = () => {}, timers = defaultTimers,
-	storage = safeStorage(), win = globalThis.window, doc = globalThis.document,
+	storage = safeStorage(), win = globalThis.window, doc = globalThis.document, channel: injected,
 } = {}) {
-	const noop = { dismiss() {}, update: async () => null, stop() {} };
+	const noop = { dismiss() {}, update: async () => null, restart: async () => null, stop() {} };
 	if (!hasLauncherRuntime(win)) return noop;
-	let info = null, timer = null, stopped = false, inflight = null, lastCheck = -Infinity;
-	let dismissed = readDismissed(storage);
-	const emit = () => { if (!stopped) onState({ state: nextUpdateState(info, { dismissed }), info }); };
+	const channel = injected === undefined ? openUpdateChannel() : injected;
+	let info = null, timer = null, stopped = false, inflight = null, lastCheck = -Infinity, hints = 0;
+	let dismissed = readDismissed(storage), restart = null, target = null, following = null;
+	const emit = () => { if (!stopped) onState({ state: nextUpdateState(info, { dismissed, restart, target }), info }); };
 	const schedule = () => {
 		if (stopped) return;
 		if (timer !== null) timers.clear(timer);
 		timer = timers.set(check, info?.phase === "updating" ? UPDATING_POLL_MS : POLL_MS);
 	};
-	const apply = (next) => { if (next) { info = next; emit(); } };
-	function check() {
+	// Tell the other tabs; a lost hint only costs them the wait for their next poll.
+	const hint = (type, latest = null) => {
+		try {
+			if (channel) channel.postMessage({ type, latest });
+			else if (type !== "dismiss") storage?.setItem(HINT_KEY, `${type}:${timers.now()}:${(hints += 1)}:${version(latest) ?? ""}`);
+		} catch { /* best effort */ }
+	};
+	// Emitted first, so this tab's update:finished claim is in storage before any other tab re-polls.
+	// A change a hint led to is not hinted again: the other tabs had the same hint.
+	const apply = (next, cause = "phase") => {
+		if (!next) return;
+		const changed = info !== null && info.phase !== next.phase;
+		info = next;
+		emit();
+		if (cause === "install" || (changed && cause === "phase")) hint(cause);
+	};
+	function check(cause = "phase") {
 		if (stopped) return Promise.resolve(info);
 		if (inflight) return inflight;
 		// An early check (a visible tab) replaces the pending poll; the schedule never doubles.
 		if (timer !== null) { timers.clear(timer); timer = null; }
 		lastCheck = timers.now();
 		inflight = fetchUpdateInfo(fetchImpl, win);
-		return inflight.then((next) => { inflight = null; apply(next); schedule(); return info; });
+		return inflight.then((next) => { inflight = null; apply(next, cause); schedule(); return info; });
 	}
 	const onVisible = () => {
 		if (doc?.visibilityState === "visible" && timers.now() - lastCheck > VISIBLE_STALE_MS) void check();
 	};
+	// A fetch already in flight may predate the hint, so one more follows it.
+	const refresh = () => (inflight ? inflight.then(() => check("hinted")) : check("hinted"));
+	// The old launcher stops answering for a moment, so a failed fetch is only another try.
+	const followRestart = (to) => {
+		if (following || !to) return following ?? Promise.resolve(null);
+		restart = "restarting";
+		target = to;
+		emit();
+		const deadline = timers.now() + RESTART_WAIT_MS;
+		following = (async () => {
+			for (;;) {
+				await new Promise((done) => timers.set(done, RESTART_POLL_MS));
+				if (stopped) return null;
+				const next = await fetchUpdateInfo(fetchImpl, win);
+				if (next?.current === to) { info = next; restart = "restarted"; break; }
+				if (timers.now() >= deadline) { restart = "restart_timeout"; break; }
+			}
+			emit();
+			return restart === "restarted" ? "ok" : "timeout";
+		})();
+		return following;
+	};
+	// The version the launcher installed, not the registry's latest: a newer release may appear while it waits.
+	const restartTarget = (latest) => version(latest) ?? (info?.phase === "restart_needed" ? info.installed ?? info.latest : null);
+	const onHint = (type, latest = null) => {
+		if (stopped || !HINTS.has(type)) return;
+		if (type === "restart") return void followRestart(restartTarget(latest));
+		if (type !== "dismiss") return void refresh();
+		dismissed = readDismissed(storage) ?? version(latest) ?? dismissed;
+		emit();
+	};
+	const onMessage = (event) => onHint(event?.data?.type, event?.data?.latest);
 	const onStorage = (event) => {
+		if (event?.key === HINT_KEY) { const [type, , , latest] = String(event.newValue ?? "").split(":"); return onHint(type, latest || null); }
 		if (event?.key !== DISMISS_KEY && event?.key !== null) return;
 		dismissed = readDismissed(storage);
 		emit();
 	};
-	try { doc?.addEventListener?.("visibilitychange", onVisible); win?.addEventListener?.("storage", onStorage); } catch { /* no listeners: the 6 h poll still runs */ }
+	try {
+		doc?.addEventListener?.("visibilitychange", onVisible);
+		win?.addEventListener?.("storage", onStorage);
+		channel?.addEventListener?.("message", onMessage);
+	} catch { /* no listeners: the 6 h poll still runs */ }
 	timers.afterFirstFrame(() => { if (!stopped) void check(); });
 	return {
 		dismiss(latest) {
@@ -172,17 +264,31 @@ export function createUpdatePoller({
 			writeDismissed(latest, storage);
 			dismissed = latest;
 			emit();
+			hint("dismiss", latest);
 		},
 		async update() {
 			const next = await startUpdate(fetchImpl, win);
-			apply(next);
+			apply(next, "install");
 			schedule();
 			return next;
 		},
+		// Resolves to the outcome (ok | timeout), or null when the launcher refused.
+		async restart() {
+			const to = restartTarget(null);
+			if (!to || following) return following;
+			if (!(await requestRestart(fetchImpl, win))) return null;
+			hint("restart", to);
+			return followRestart(to);
+		},
 		stop() {
 			stopped = true;
 			if (timer !== null) timers.clear(timer);
-			try { doc?.removeEventListener?.("visibilitychange", onVisible); win?.removeEventListener?.("storage", onStorage); } catch { /* best effort */ }
+			try {
+				doc?.removeEventListener?.("visibilitychange", onVisible);
+				win?.removeEventListener?.("storage", onStorage);
+				channel?.removeEventListener?.("message", onMessage);
+				channel?.close?.();
+			} catch { /* best effort */ }
 		},
 	};
 }

package/src/update/update-telemetry.js

@@ -1,4 +1,5 @@
-// update:notice_shown, update:clicked and update:finished (the U1 update notice).
+// update:notice_shown, update:clicked, update:finished (the U1 update notice) and
+// update:restarted (Restart now, #960).
 // Only closed values leave: the install kind, how far behind (patch/minor/major),
 // the button, the outcome, the npm error class and a duration bucket. Never a
 // version string, a path, a command or npm's output. All three are passive
@@ -10,7 +11,8 @@ import { bucketLong } from "../analytics-strict.js";
 const CLICKS_PER_SESSION = 10;
 const FINISHED_PER_SESSION = 3;
 const NOTICE_KINDS = new Set(["global", "npx"]);
-const CLICK_ACTIONS = new Set(["update_now", "copy_command", "later", "dismiss", "release_notes"]);
+const CLICK_ACTIONS = new Set(["update_now", "copy_command", "later", "dismiss", "release_notes", "restart"]);
+const RESTART_OUTCOMES = new Set(["ok", "timeout"]);
 // The install this browser already reported, shared by the tabs of one profile:
 // several tabs (and several polls) see the same terminal phase, the event leaves once.
 const REPORTED_KEY = "cozyclay:update-reported";
@@ -31,7 +33,7 @@ export function noteNoticeShown(state) {
 	}
 }
 
-/** A notice button: update_now (also Try again), copy_command, later, dismiss or release_notes. */
+/** A notice button: update_now (also Try again), copy_command, later, dismiss, release_notes or restart. */
 export function noteUpdateClicked(action, kind) {
 	try {
 		if (!CLICK_ACTIONS.has(action) || !NOTICE_KINDS.has(kind)) return;
@@ -41,6 +43,16 @@ export function noteUpdateClicked(action, kind) {
 	}
 }
 
+/** Restart now ended in the tab that pressed it: the new launcher answered (ok) or 30 s passed (timeout). Once per session. */
+export function noteUpdateRestarted(outcome) {
+	try {
+		if (!RESTART_OUTCOMES.has(outcome)) return;
+		if (admit("update:restarted", 1)) send("update:restarted", { outcome });
+	} catch {
+		// Telemetry must never affect the restart.
+	}
+}
+
 function claim(key) {
 	if (reportedHere.has(key)) return false;
 	reportedHere.add(key);

package/src/use-sculpt-mode.js

@@ -1,11 +1,15 @@
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, 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 { blueprintErrorMessage, blueprintRequest, blueprintViewImages } from "./sculpt-blueprint.js";
+import { browserSculptImages } from "./commands/sculpt-images.js";
+import { agentSessionReady, chatgptSignedIn, createCommandTap, sculptModelChoice, sculptTargetFromSelection, storeSculptModel } from "./sculpt-mode.js";
 import { SCULPT_KIND } from "./scene-objects.js";
+import { overlayOwnsEscape, sculptPartTree } from "./sculpt-pick.js";
+import { GIZMO_HOTKEYS } from "./stage-startup-defaults.js";
+import { ko } from "./locale.js";
 
-export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId }) {
+export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectId, appContext }) {
 	// 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.
@@ -17,6 +21,8 @@ export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectI
 	const [sculptRun, setSculptRun] = useState(null);
 	const sculptRunRef = useRef(null);
 	const [sculptAgentStatus, setSculptAgentStatus] = useState("unknown");
+	// Whether the sidecar holds a ChatGPT token: the blueprint's image model needs one (#970).
+	const [sculptChatgpt, setSculptChatgpt] = useState(false);
 	// 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 });
@@ -47,8 +53,8 @@ export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectI
 		let live = true;
 		const read = () => {
 			sculptTransport.status().then(
-				(status) => { if (live) setSculptAgentStatus(agentSessionReady(status) ? "ready" : "signed-out"); },
-				() => { if (live) setSculptAgentStatus("signed-out"); },
+				(status) => { if (live) { setSculptAgentStatus(agentSessionReady(status) ? "ready" : "signed-out"); setSculptChatgpt(chatgptSignedIn(status)); } },
+				() => { if (live) { setSculptAgentStatus("signed-out"); setSculptChatgpt(false); } },
 			);
 			// The Agent panel's catalogue: a key added or removed elsewhere changes what can run.
 			sculptTransport.models().then(
@@ -65,6 +71,50 @@ export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectI
 		window.addEventListener("focus", read);
 		return () => { live = false; window.removeEventListener("focus", read); };
 	}, [sculptMode, sculptTransport]);
+	// Part picking (#740 S7): one part of the target, chosen on the turntable or
+	// in the panel's tree. A new target or leaving the mode drops it; Esc drops
+	// it before Esc reaches the scene selection, unless an open menu or dialog takes that Esc.
+	const [sculptPart, setSculptPart] = useState(null);
+	useEffect(() => { setSculptPart(null); }, [sculptMode, sculptTargetId]);
+	// The part gizmo (#740 S8): its tool, and the last refusal or notice it shows under the tree.
+	const [partTool, setPartTool] = useState("move");
+	const [partNotice, setPartNotice] = useState(null);
+	useEffect(() => { setPartNotice(null); }, [sculptPart?.partId, sculptPart?.mirrored, sculptTargetId]);
+	useEffect(() => {
+		if (!sculptMode || !sculptPart) return undefined;
+		const onKey = (event) => {
+			if (event.target?.closest?.("input, textarea, select, [contenteditable='true']")) return;
+			// Delete with a part picked would take the whole sculpt: refused, Esc first.
+			if (event.key === "Delete" || event.key === "Backspace") {
+				event.stopPropagation();
+				event.preventDefault();
+				setPartNotice(ko("Delete removes the whole sculpt. Press Esc to deselect the part first.", "Delete는 조형물 전체를 지워요. 먼저 Esc로 부품 선택을 해제하세요.", "Delete 会删除整个雕塑。请先按 Esc 取消部件选择。"));
+				return;
+			}
+			if (event.key !== "Escape" || overlayOwnsEscape()) return;
+			event.stopPropagation();
+			setSculptPart(null);
+		};
+		window.addEventListener("keydown", onKey, true);
+		return () => window.removeEventListener("keydown", onKey, true);
+	}, [sculptMode, sculptPart]);
+	const sculptRecipe = sculptTarget?.recipe;
+	const sculptTree = useMemo(() => sculptPartTree(sculptRecipe), [sculptRecipe]);
+	// A recipe edit that removed the part leaves nothing selected.
+	const selectedPart = sculptPart && sculptTree.some((row) => row.id === sculptPart.partId) ? sculptPart : null;
+	// W/E/R: the selected part's move, rotate and scale; with no part, the turntable views.
+	const onKey = (code) => (selectedPart ? setPartTool(GIZMO_HOTKEYS[code]) : requestSculptView({ KeyW: "front", KeyE: "side", KeyR: "back" }[code]));
+	const tools = [["W", "move", ko("Move part", "부품 이동", "移动部件")], ["E", "rotate", ko("Rotate part", "부품 회전", "旋转部件")], ["R", "scale", ko("Scale part (Shift: uniform)", "부품 크기 (Shift: 균등)", "缩放部件（Shift：等比）")]]
+		.map(([key, id, name]) => ({ key, id, name, active: partTool === id, pick: () => setPartTool(id) }));
+	// One drag, one write: the command refuses what cannot be drawn and its reason is shown.
+	const commit = (edit) => {
+		if (!edit || !sculptTarget || !appContext) return false;
+		let receipt;
+		try { receipt = appContext.bus.run("object.sculpt", { id: sculptTarget.id, edits: [edit] }, { origin: "ui" }); } catch (error) { receipt = { ok: false, message: error?.message }; }
+		setPartNotice(receipt?.ok === false ? `${ko("Edit refused", "편집 거부", "编辑被拒绝")}: ${receipt.message ?? ""}` : null);
+		return receipt?.ok !== false;
+	};
+	const sculptParts = { tree: sculptTree, selected: selectedPart, onSelect: setSculptPart, tool: partTool, tools, onKey, commit, notice: partNotice };
 	// 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);
@@ -78,7 +128,11 @@ export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectI
 		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 } }));
+			// Cut into views (#970): side and back go to Start next to the reference; a view whose mask fails is dropped with a notice.
+			let cropped;
+			try { cropped = await blueprintViewImages(result.dataUrl, browserSculptImages); } catch (error) { cropped = { views: [], notices: [`The sheet could not be cut into views: ${error?.message || error}`] }; }
+			if (blueprintAbortRef.current !== controller) return;
+			setSculptBlueprint((current) => ({ ...current, state: "ready", sheet: { dataUrl: result.dataUrl, width: result.width, height: result.height, ms: Date.now() - startedAt, views: cropped.views, notices: cropped.notices } }));
 		} catch (error) {
 			if (blueprintAbortRef.current !== controller) return;
 			const cancelled = controller.signal.aborted;
@@ -91,5 +145,5 @@ export function useSculptMode({ workflowMode, sceneObjects, selectedSceneObjectI
 		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 };
+	return { sculptMode, sculptCamRef, sculptView, sculptReference, setSculptReference, sculptRun, setSculptRun, sculptRunRef, sculptAgentStatus, sculptChatgpt, sculptModels, sculptModelPick, chooseSculptModel, sculptTransport, sculptTap, sculptTarget, setSculptTargetId, requestSculptView, sculptBlueprint, setSculptBlueprint, generateSculptBlueprint, cancelSculptBlueprint, sculptParts };
 }

package/src/workflow/agent-failure-codes.js

@@ -1,7 +1,8 @@
 // The closed `agent:turn_failed.failure_code` vocabulary, browser side. The
 // sidecar keeps an identical table in bin/agent/agent-failure-codes.mjs (it
 // cannot import src/); test/verify-agent-execution.mjs holds both to the same
-// answers. Only the structured code and HTTP status are read, never a message.
+// answers. Only the error's name, structured code and HTTP status are read,
+// never a message.
 //
 //   key_refused         the model provider rejected the credentials (provider
 //                       401/403, structured or message-only: runner `unauthorized`)
@@ -14,9 +15,15 @@
 //                       LIVE_HUB_UNAVAILABLE: no connected editor)
 //   busy                a turn is already running, or the target is busy
 //   invalid_request     the sidecar rejected the request (400, INVALID_*, other 4xx)
-//   upstream            provider outage, overload, 5xx, network or unclassified
-//   aborted / tool_failed / unknown  are assigned by the turn, not by this table
-export const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "unknown",
+//   upstream            provider trouble: HTTP 5xx, or the runner's `overloaded`,
+//                       `upstream`, `truncated` (and the provider's `server_error`)
+//   network             the request never got an HTTP answer: a fetch TypeError
+//                       (offline, refused, DNS) or a socket code (ECONNRESET,
+//                       ENOTFOUND, ...), on the error or its `cause`
+//   unknown             anything else, including an error whose fields throw
+//   aborted / tool_failed  are assigned by the turn, not by this table
+// Rows before the network/unknown split carry `upstream` for all three.
+export const AGENT_FAILURE_CODES = new Set(["aborted", "auth", "rate_limited", "tool_failed", "upstream", "network", "unknown",
 	"key_refused", "stale_scene", "capability_missing", "busy", "invalid_request"]);
 
 const BY_CODE = {
@@ -24,24 +31,36 @@ const BY_CODE = {
 	STALE_SCENE: "stale_scene", STALE_TARGET: "stale_scene", STALE_ENVIRONMENT: "stale_scene",
 	CAPABILITY_MISSING: "capability_missing", LIVE_HUB_UNAVAILABLE: "capability_missing",
 	busy: "busy", TARGET_BUSY: "busy", SCOPE_BUSY: "busy", TARGET_NOT_READY: "busy",
+	// A sidecar frame whose code is already this table's fallback answer passes through.
+	network: "network", unknown: "unknown",
 };
+// The runner's provider codes read as upstream, after the status: a 4xx beside one is the request's fault.
+const PROVIDER_CODES = new Set(["overloaded", "upstream", "truncated", "server_error"]);
+const NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ECONNABORTED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT", "EPIPE",
+	"ENETUNREACH", "ENETDOWN", "EHOSTUNREACH", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
+const codeOf = (value) => (typeof value?.code === "string" ? value.code : "");
 
-/** `{ code, status }` -> failure code. Foreign getters fall back to upstream. */
+/** `{ name, code, status }` -> failure code. Foreign getters read as unknown. */
 export function transportFailureCode(error) {
 	try {
-		const code = typeof error?.code === "string" ? error.code : "";
+		const code = codeOf(error);
 		const status = error?.status;
 		if (Object.hasOwn(BY_CODE, code)) return BY_CODE[code];
 		if (code.startsWith("INVALID_")) return "invalid_request";
 		if (status === 401 || status === 403) return "auth";
 		if (status === 429) return "rate_limited";
-		return Number.isInteger(status) && status >= 400 && status < 500 ? "invalid_request" : "upstream";
-	} catch { return "upstream"; }
+		if (Number.isInteger(status) && status >= 400 && status < 500) return "invalid_request";
+		if (Number.isInteger(status) && status >= 500 && status < 600) return "upstream";
+		if (PROVIDER_CODES.has(code)) return "upstream";
+		if (Number.isInteger(status)) return "unknown";
+		if (NETWORK_CODES.has(code) || NETWORK_CODES.has(codeOf(error?.cause)) || error?.name === "TypeError") return "network";
+		return "unknown";
+	} catch { return "unknown"; }
 }
 
 /** A refused turn: the sidecar's `{ error: { code } }` body plus the HTTP status. */
 export async function refusalFailureCode(response) {
 	let code;
 	try { const body = await response.clone().json(); code = typeof body?.error?.code === "string" ? body.error.code : undefined; } catch { /* status alone */ }
-	try { return transportFailureCode({ code, status: response?.status }); } catch { return "upstream"; }
+	try { return transportFailureCode({ code, status: response?.status }); } catch { return "unknown"; }
 }

package/src/workflow/agent-turn-telemetry.js

@@ -142,7 +142,7 @@ export function startAgentTurn({ surface, capture, now, correlationId = null })
 	return {
 		turnId,
 		cancel: () => finish("cancelled", "aborted"),
-		fail: (code) => finish("failed", AGENT_FAILURE_CODES.has(code) ? code : "upstream"),
+		fail: (code) => finish("failed", AGENT_FAILURE_CODES.has(code) ? code : "unknown"),
 		/** A tool.start / tool.done frame the panel sees (after replay dedupe). */
 		tool(event) {
 			if (!terminal) advisory(() => tally.note(event), null);

package/src/workflow/task-board.js

@@ -1,4 +1,4 @@
-// The Studio task board in the agent panel (parallel tasks, P3). Task mode is a per-browser switch (the panel's Tasks
+// The Studio task board in the agent panel (parallel tasks, P3). Task mode is a per-browser switch, on by default (the panel's Tasks
 // toggle) or the server's COZYCLAY_STUDIO_TASKS flag: the chat then talks to the main agent (POST /agent/main), which
 // answers at once and dispatches tasks; this board shows them. Pure parts here (the reducer, labels, the switch's
 // storage); the network side is createTaskBoardClient; the view is TaskBoard.jsx.
@@ -13,7 +13,7 @@ import { parseSseChunk } from "./agent-client.js";
 
 const TASKS_KEY = "cozyclay.agent.tasks";
 export function readStoredTaskMode(storage = globalThis.localStorage) {
-	try { return storage?.getItem(TASKS_KEY) === "on"; } catch { return false; }
+	try { return storage?.getItem(TASKS_KEY) !== "off"; } catch { return true; } // on unless the author turned it off
 }
 export function storeTaskMode(enabled, storage = globalThis.localStorage) {
 	try { storage?.setItem(TASKS_KEY, enabled ? "on" : "off"); } catch { /* storage may be unavailable */ }

package/tools/dev/page-shell.py

@@ -12,7 +12,7 @@ ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 PAGES_DIR = os.path.join(os.path.dirname(__file__), "pages")
 
 NAV = """        <nav>
-          <a href="/#try">Try it</a>
+          <a href="/app/">Try it</a>
           <a href="/greybox-to-video/">Greybox to video</a>
           <a href="/previs-software/">Previs software</a>
           <a href="/ai-camera-control/">Camera control</a>

package/tools/dev/pages/greybox-to-video.html

@@ -72,6 +72,25 @@
         </div>
       </section>
 
+      <section>
+        <h2>What the models actually accept</h2>
+        <p>
+          Seedance 2.5's product page names this input: "Provides advanced capabilities such as white-model control
+          and green-screen editing, combined with professional camera movement and performance blocking." Its showcase
+          prompt directs the model to "Use the white-model reference video as the sole guide for camera movement,
+          pacing, framing, subject motion, and blocking." That white-model reference video is a plain RGB blockout
+          clip, which is exactly what the keyframe pack exports. MiniMax H3 reference-to-video, the Wan 3.0 hosted
+          <code>reference_video</code>, LTX Desktop's "3D Render to Photoreal" ("keeping the exact composition, camera
+          move and layout of the input") and fal render-to-real all consume the same clip.
+        </p>
+        <p>
+          The caveat is Kling Motion Control: "Avoid cuts, camera movement, etc.; otherwise, the video may be
+          trimmed." So send it a single character, one continuous take.
+        </p>
+        <p class="note">None of the top hosted APIs (Seedance, Kling, Veo 3.1, Runway Act-Two, MiniMax)
+        documents a depth or pose control-video input.</p>
+      </section>
+
       <section>
         <h2>The block-then-generate loop</h2>
         <ol>
@@ -107,11 +126,11 @@
         <h2>Do it in the browser</h2>
         <p>
           CozyClay is open source previs that runs in a Chromium tab. It exists for exactly this loop: block,
-          camera, export, generate. The <a href="/#try">playground on the home page</a> runs the studio in the page, and
+          camera, export, generate. The <a href="/app/">browser studio</a> runs it in a tab, and
           <code>npx cozyclay</code> runs it on your machine.
         </p>
         <div class="cta">
-          <a class="btn primary" href="/#try">Try it in your browser</a>
+          <a class="btn primary" href="/app/">Try it in your browser</a>
           <a class="btn ghost" href="https://github.com/NomaDamas/CozyClay">View on GitHub</a>
         </div>
       </section>

package/tools/dev/pages/previs-software.html

@@ -64,8 +64,8 @@
         <p>
           The honest split is time, not money. Blender can do everything on this page and will take an
           afternoon to learn just the camera. CozyClay does one thing (block, camera, cut, export) and expects
-          you to be productive in the first ten minutes; the <a href="/#try">playground on the home page</a>
-          runs it in the page.
+          you to be productive in the first ten minutes; the <a href="/app/">browser studio</a>
+          runs it in a tab.
         </p>
       </section>
 
@@ -115,7 +115,7 @@
           <li><strong>Everything, given time:</strong> Blender.</li>
         </ul>
         <div class="cta">
-          <a class="btn primary" href="/#try">Try CozyClay in your browser</a>
+          <a class="btn primary" href="/app/">Try CozyClay in your browser</a>
           <a class="btn ghost" href="https://github.com/NomaDamas/CozyClay">Source on GitHub</a>
         </div>
       </section>