cozyclay 3.1.0 → 3.1.2

package/src/bus-tasks.js

@@ -8,7 +8,7 @@
 // next command on a target the user changed answers STALE_TARGET once. Ctrl+Z stops at a running task's entry.
 // A single agent turn (agent.turn.*) is untouched: tasks and a turn never run together.
 import { StudioProtocolError, validateReceipt } from './studio-agent-protocol.js';
-import { commandKeys, keyOfId, scopeConflict, isScopeKey } from './bus-task-scopes.js';
+import { commandKeys, keyOfId, scopeConflict, isScopeKey, layerOf, expandScope, keysOverlap } from './bus-task-scopes.js';
 
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 const VERBS = ['begin', 'requestScope', 'mark', 'rollback', 'finish', 'cancel', 'undo'];
@@ -17,7 +17,11 @@ const listOf = keys => [...keys].slice(0, 6).join(', ') + (keys.length > 6 ? ` a
 
 export function createBusTasks({ ports, emit }) {
 	const open = new Map(), finished = new Map(), entryTask = new Map();
+	// A character layer has its own token (its fields only), so another task's edit of her other layers never makes it
+	// stale; an editor without layer reads falls back to the whole character's.
 	const tokenOf = key => {
+		const of = layerOf(key);
+		if (of?.layer) return ports.readLayer?.(key) ?? ports.readTarget?.(of.id) ?? 'absent';
 		const [kind, id] = key.split(/:(.*)/s);
 		if (id !== undefined) return ports.readTarget?.(id) ?? 'absent';
 		const state = ports.read();
@@ -32,14 +36,16 @@ export function createBusTasks({ ports, emit }) {
 		if (!ports.restoreTargets) fail('CAPABILITY_MISSING', 'This editor cannot restore task targets.');
 		const { historyEntryId = null } = ports.restoreTargets(values) ?? {};
 		if (historyEntryId) entryTask.set(historyEntryId, task.taskId);
-		task.restored = [...new Set(values.map(({ key }) => key.includes(':') ? key.slice(key.indexOf(':') + 1) : ports.read().host.sceneId))];
+		task.restored = [...new Set(values.map(({ key }) => layerOf(key)?.id ?? (key.includes(':') ? key.slice(key.indexOf(':') + 1) : ports.read().host.sceneId)))];
 		for (const { key } of values) task.tokens.set(key, tokenOf(key));
 		emit?.({ type: `task.${action}`, taskId: task.taskId, keys: values.map(v => v.key) });
 		return historyEntryId;
 	}
-	function grant(task, keys) {
-		const bad = keys.find(key => !isScopeKey(key));
-		if (bad !== undefined) fail('INVALID_ARGUMENT', `"${bad}" is not a scope key: object:<id>, character:<id>, shot:<id>, stage, timeline or scene.`);
+	// A plain character:<id> is held as its four layers: the commands name layers, and each layer keeps its own token.
+	function grant(task, scope) {
+		const bad = scope.find(key => !isScopeKey(key));
+		if (bad !== undefined) fail('INVALID_ARGUMENT', `"${bad}" is not a scope key: object:<id>, character:<id> (or one layer: character:<id>:placement, :take, :ik, :props), shot:<id>, stage, timeline or scene.`);
+		const keys = expandScope(scope);
 		const conflict = scopeConflict(task.taskId, keys, open);
 		if (conflict) fail('SCOPE_BUSY', `${conflict}; wait for it, or ask for what is free.`);
 		for (const key of keys) if (!task.keys.has(key)) { task.keys.add(key); task.tokens.set(key, tokenOf(key)); }
@@ -121,7 +127,7 @@ export function createBusTasks({ ports, emit }) {
 			if (!task && !open.size) return null;
 			const keys = entry?.id ? commandKeys(entry.id, args, before, entry) : [];
 			// The user's own edit is never refused; a running task whose scope it touches hears of it (the panel's card).
-			if (!task && request.origin === 'ui') { for (const other of open.values()) { const mine = keys.filter(key => other.keys.has(key)); if (mine.length) emit?.({ type: 'task.userEdit', taskId: other.taskId, keys: mine }); } return null; }
+			if (!task && request.origin === 'ui') { for (const other of open.values()) { const mine = keys.filter(key => [...other.keys].some(held => keysOverlap(key, held))); if (mine.length) emit?.({ type: 'task.userEdit', taskId: other.taskId, keys: mine }); } return null; }
 			if (!task) {
 				const held = keys.find(key => scopeConflict(null, [key], open));
 				if (held) fail('SCOPE_BUSY', `${scopeConflict(null, [held], open)}; this command waits for that task.`);
@@ -135,18 +141,25 @@ export function createBusTasks({ ports, emit }) {
 				fail('STALE_TARGET', `${listOf(moved)} changed outside this task (the user, or an undo) since it last looked; read it again, then retry.`);
 			}
 			for (const key of keys) if (!task.pre.has(key)) task.pre.set(key, snapshot(key));
-			return { task, keys, values: keys.map(snapshot), mark: task.mark };
+			return { task, keys, values: keys.map(snapshot), mark: task.mark, fence: new Map(keys.map(key => [key, tokenOf(key)])) };
 		},
+		/**
+		 * A task's job fences on its own keys, not the whole target: another task placing the character while this one
+		 * compiles her take is not a change under the compile. moved(point) names what changed since admit or rebase(point).
+		 */
+		moved: point => [...point.fence].filter(([key, token]) => tokenOf(key) !== token).map(([key]) => key),
+		rebase(point) { for (const key of point.fence.keys()) point.fence.set(key, tokenOf(key)); },
 		/** Files a task's receipt: ids it created join its scope, it may be undone newest first, readers hear of it. */
 		record(point, recorded) {
 			if (!point || !recorded?.ok) return recorded;
 			const { task } = point, state = ports.read(), warnings = [];
 			let grew = false;
+			// A character the task holds one layer of is its own: the command was admitted on that layer.
 			for (const id of recorded.affectedIds ?? []) {
 				const key = keyOfId(id, state);
-				if (!key || task.keys.has(key)) continue;
-				if (scopeConflict(task.taskId, [key], open)) warnings.push({ code: 'SCOPE_DENIED', message: `${key} changed outside the task's scope.` });
-				else { task.keys.add(key); grew = true; if (!point.keys.includes(key)) { task.pre.set(key, { key, value: undefined }); point.values.push({ key, value: undefined }); } }
+				if (!key || [...task.keys].some(held => keysOverlap(key, held))) continue;
+				if (scopeConflict(task.taskId, [key], open)) { warnings.push({ code: 'SCOPE_DENIED', message: `${key} changed outside the task's scope.` }); continue; }
+				for (const made of expandScope([key])) { task.keys.add(made); grew = true; if (!point.keys.includes(made)) { task.pre.set(made, { key: made, value: undefined }); point.values.push({ key: made, value: undefined }); } }
 			}
 			if (grew) emit?.({ type: 'task.scope', taskId: task.taskId, scope: [...task.keys] });
 			for (const key of task.keys) task.tokens.set(key, tokenOf(key));

package/src/command-bus.js

@@ -173,12 +173,13 @@ export function createCommandBus({ registry, ports }) {
       affectedIds: [...tx.affectedIds], delta: [], checks: { coverage: 'wire-transaction' }, warnings: toastWarnings(tx.toasts),
       undo: tx.historyEntryId ? { historyEntryId: tx.historyEntryId, entries: 1, canUndoDirect: true } : null });
   }
+  // a refusal may list every problem of the request at once (a motion spec: up to 12 lines), so it keeps 2000 characters
   function refusal(request, before, error, mutated) {
     const changed = mutated ?? (ports.read().revision !== before.revision);
     return validateReceipt({ ok: false, commandId: request.commandId, host: before.host,
       code: refusalCode(error), phase: changed ? 'commit' : 'admission', affectedIds: [], expectedTargets: [], currentTargets: [],
       mutated: changed, preserved: { authoredState: changed ? 'changed' : 'unchanged' }, recovery: { action: 'inspect', retryAllowed: false },
-      message: [...String(error.message || error)].slice(0, 500).join('') });
+      message: [...String(error.message || error)].slice(0, 2000).join('') });
   }
   /** Findings first, toasts after; past the schema's twelve, say how many were left out. */
   const receiptWarnings = (findings = [], toasts = [], omitted = 0, limit = 12) => {
@@ -283,17 +284,19 @@ export function createCommandBus({ registry, ports }) {
       const rebase = () => {
         const current = ports.read();
         token = targetId ? ports.readTarget?.(targetId) : null;
-        domainRevision = domain ? current.domainRevisions?.[domain] : null;
+        domainRevision = domain ? current.domainRevisions?.[domain] : null; if (scoped?.keys.length) tasks.rebase(scoped);
       };
       const nestedIds = new Set();
-      const context = { origin: request.origin, signal: controller.signal, taskId: request.taskId ?? null,
+      // callId: the agent's tool call (a script's nested commands share it), for motion.compile's stop rule (repair-watch.js)
+      const context = { origin: request.origin, signal: controller.signal, taskId: request.taskId ?? null, turnId: request.turnId ?? null, callId: typeof request.callId === 'string' ? request.callId : null,
         check() {
           controller.signal.throwIfAborted();
           const current = ports.read();
           // Name the fence that tripped: the three share one code, and a bare "something changed" leaves the user and the agent guessing.
           if (!same(current.host, before.host)) fail('STALE_TARGET', 'The open document or scene changed while the job was running.');
           if (domain && !task && current.domainRevisions?.[domain] !== domainRevision) fail('STALE_TARGET', `The ${domain} data changed while the job was running (revision ${domainRevision} to ${current.domainRevisions?.[domain]}); an edit landed between the request and its result.`);
-          if (targetId && ports.readTarget?.(targetId) !== token) fail('STALE_TARGET', `${targetId} changed while the job was running.`);
+          // Inside a task the fence is the task's own keys (bus-tasks.js moved): another task's layer of the target is not a change under it.
+          const moved = scoped?.keys.length ? tasks.moved(scoped) : targetId && ports.readTarget?.(targetId) !== token ? [targetId] : []; if (moved.length) fail('STALE_TARGET', `${moved.join(', ')} changed while the job was running.`);
         },
         commit(apply) {
           context.check();

package/src/commands/ai.js

@@ -26,6 +26,6 @@ export function register(registry, ports) {
 			const shot = result.shot && { id: result.shot.id, name: result.shot.name, range: { startFrame: result.shot.startFrame, endFrameExclusive: result.shot.endFrame + 1 } };
 			const referenceFrames = (result.frame ? 1 : 0) + (result.frameB ? 1 : 0);
 			return { affectedIds: [], output: { prompt: result.prompt, mode: result.mode, modelLabel: result.modelLabel ?? null, shot, aspectRatio: result.aspectRatio, cameraMode: result.camera?.mode ?? null, referenceFrames },
-				summary: `Prepared the ${result.mode} prompt${result.modelLabel ? ` for ${result.modelLabel}` : ""} for ${shot ? `${shot.name} [${shot.range.startFrame}, ${shot.range.endFrameExclusive})` : "the current camera"}; the Studio's result panel shows it with ${referenceFrames} reference frame${referenceFrames === 1 ? "" : "s"} for the user to copy and download.` };
+				summary: `Prepared the ${result.mode} prompt${result.modelLabel ? ` for ${result.modelLabel}` : ""} for ${shot ? `${shot.name} [${shot.range.startFrame}, ${shot.range.endFrameExclusive})` : "the current camera"}; the Studio's result panel shows it with ${referenceFrames} reference frame${referenceFrames === 1 ? "" : "s"} for the user to copy and export.` };
 		} });
 }

package/src/commands/elements.js

@@ -111,9 +111,10 @@ export function elementPatchArgs(kind, args) {
   });
   return collection ? ops.length === 1 ? ops[0] : { ops } : ops.reduce((patch, op) => mergeElementSet(patch, op.set), {});
 }
-// Unasked, an optional structured value (a glow, a light) is listed only where
-// the item has one, so every plain object's receipt stays as short as before.
-const listed = (element, item, paths) => paths ? paths.includes(element.path) : element.type !== 'object' || readElement(item, element.path) != null;
+// Unasked, an optional structured value (a glow, a light) or a `sparse` field (a
+// surface preset) is listed only where the item has one, so every plain
+// object's receipt stays as short as before.
+const listed = (element, item, paths) => paths ? paths.includes(element.path) : (element.type !== 'object' && !element.sparse) || readElement(item, element.path) != null;
 export function elementReadback(kind, item, paths, document) {
   return patchElements(projectionKind(kind)).filter(element => listed(element, item, paths)).map(element => {
     const path = element.path;

package/src/commands/export.js

@@ -15,6 +15,6 @@ export function register(registry, ports) {
 			const result = await ports.exportShotVideo({ shotId: shotId ?? null, ...(scope ? { scope } : {}) }, context);
 			if (!result?.fileName) fail("TARGET_NOT_READY", "The video export did not finish; the editor's export panel shows why and offers Retry.");
 			return { affectedIds: shot ? [shot.id] : [], output: { fileName: result.fileName, frameCount: result.frameCount },
-				summary: `Recorded ${scope === "timeline" ? "the whole timeline" : shot ? shotLabel(shot) : "the shot"} to ${result.fileName} (${result.frameCount} frames); the browser was asked to download it.` };
+				summary: `Recorded ${scope === "timeline" ? "the whole timeline" : shot ? shotLabel(shot) : "the shot"} to ${result.fileName} (${result.frameCount} frames); it was handed to the configured export folder or the browser download.` };
 		} });
 }

package/src/commands/motion3.js

@@ -22,6 +22,7 @@ import { qaSay } from "../qa-label.js";
 import { carryEdit } from "../motion3/edit-carry.js";
 import { normalizeCompileArgs } from "../motion3/lenient.js";
 import { createCompileRunner } from "./motion3-compile.js";
+import { createRepairWatch } from "../motion3/repair-watch.js";
 import { peopleOf } from "../motion3/people.js";
 
 const TIMELINE_FPS = 24;
@@ -84,6 +85,8 @@ function asArgument(run) {
 
 export function register(registry, ports) {
 	const store = createSpecStore();
+	// the stop rule: output.stuck when more compiles stopped paying (repair-watch.js)
+	const watch = createRepairWatch();
 	const owner = () => ports.storeDomain("motion");
 	const mounted = () => Boolean(ports.storeDomain?.("motion")) || "The motion owner is not mounted.";
 	const always = () => true;
@@ -105,10 +108,21 @@ export function register(registry, ports) {
 	 * spec on the character's rig and the current scene (compile-job.js) -> { stored (the spec a take keeps and its specId
 	 * names), qa, ..., take when bake is given }, at once or as a promise. opts: probes, checks, lenient, repair.
 	 */
-	const compile = (character, spec, opts = {}, bake, taskId = null) => {
+	const compile = (character, spec, opts = {}, bake, taskId = null, scene = sceneFor(character)) => {
 		rigOf(character);
 		const placed = bake && { position: [character.x ?? 0, character.y ?? 0, character.z ?? 0], yaw: character.rot ?? 0, ...bake };
-		return runner.run({ model: character.model, scene: sceneFor(character), spec, ...opts, ...(placed ? { bake: placed } : {}) }, { taskId, characterId: character.id });
+		return runner.run({ model: character.model, scene, spec, ...opts, ...(placed ? { bake: placed } : {}) }, { taskId, characterId: character.id });
+	};
+	// where a take was baked: the body's place and a hash of the scene's bodies (a take kept for the stop rule fits only
+	// there): 0.14 ms for 860 bodies, where their JSON took 0.9 ms and 295 KB a key
+	const placeKey = (character, scene) => {
+		let h = 2166136261;
+		const mix = v => { h = Math.imul(h ^ Math.round(v * 1e4), 16777619); };
+		for (const [id, o] of Object.entries(scene.objects ?? {})) {
+			for (let i = 0; i < id.length; i++) mix(id.charCodeAt(i) / 1e4);
+			for (const list of [o.pos, o.half, ...o.R]) for (let i = 0; i < list.length; i++) mix(list[i]);
+		}
+		return `${character.model} ${[character.x ?? 0, character.y ?? 0, character.z ?? 0, character.rot ?? 0].join(" ")} ${(h >>> 0).toString(36)}`;
 	};
 	/** The whole output, kept in the store (motion.report, delta) and cut to the receipt budget (report.js). */
 	const report = (r, head, extra = {}) => {
@@ -144,8 +158,9 @@ export function register(registry, ports) {
 		// a base the store forgot (a reload) may still be the installed take's spec: a document read names it by specId
 		const installedSpec = () => { const take = owner().motionFor(characterId); return take?.spec && specIdOf(take.spec) === base ? structuredClone(take.spec) : null; };
 		const patched = [], source = spec ?? asArgument(() => applyPatch(store.get(base) ?? installedSpec() ?? unknownSpec("base", base), patch ?? [], patched));
+		const scene = sceneFor(character), at = placeKey(character, scene);
 		// the take is always baked: the user watches every draft, installed or not
-		return after(compile(character, source, { probes, repair }, {}, context?.taskId), r => {
+		return after(compile(character, source, { probes, repair }, {}, context?.taskId, scene), r => {
 			const { qa, take } = r, notes = [...patched, ...(r.notes ?? [])];
 			// ifClean: install only a clean final result (qa.ok includes the goals; after repair when asked)
 			const wanted = install === "ifClean" ? qa.ok : install;
@@ -158,11 +173,16 @@ export function register(registry, ports) {
 				if (installs) timing = put(character, take, context);
 			}
 			const delta = base === undefined ? {} : { delta: deltaOf(store.parts(base)?.groups ?? [], qa.groups, base) };
-			const how = kept ? "; already installed, unchanged" : install === "ifClean" ? (installs ? "; installed" : "; not installed") : "";
-			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: wanted, ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
+			// the stop rule (repair-watch.js): a note, and the best take so far put on when the note would leave the take empty or worse
+			const own = specIdOf(r.stored), carried = owner().motionFor(characterId)?.spec, current = carried ? specIdOf(carried) : null;
+			const { say: stuck, install: best } = watch.note({ characterId, turnId: context?.turnId, callId: context?.callId, specId: own, base, qa, at, take, installed: Boolean(installs || kept), current });
+			if (best) timing = put(character, best.take, context) ?? timing;
+			const self = best?.specId === own, how = kept ? "; already installed, unchanged" : self ? "; installed as the best take so far"
+				: best ? `; not installed; the best take so far, ${best.specId}, installed` : install === "ifClean" ? (installs ? "; installed" : "; not installed") : "";
+			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: Boolean(wanted) || self, ...(stuck ? { stuck } : {}), ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
 			// agent-progress.js: viewport ghost, timeline beats, agent panel
-			publishDraft(characterId, { take, installed: installs || kept, specId: output.specId, label: r.label, qa, timeline: r.timeline });
-			return { affectedIds: installs ? [characterId] : [], summary: `Compiled ${r.frameCount} frames; QA ${qaSay(qa)}${how}${adjustedSay(notes)}.`, output, ...workerWarning() };
+			publishDraft(characterId, { take, installed: installs || kept || self, specId: output.specId, label: r.label, qa, timeline: r.timeline });
+			return { affectedIds: installs || best ? [characterId] : [], summary: `Compiled ${r.frameCount} frames; QA ${qaSay(qa)}${how}${adjustedSay(notes)}.`, output, ...workerWarning() };
 		});
 	} });
 	registry.register({ ...declarations[1], available: mounted, run({ characterId, checks }) {

package/src/commands/objects.js

@@ -28,7 +28,7 @@ const semantic = [
 	// A clay prop from a recipe of soft parts (docs/sculpt-from-image.md). With `id` it re-sculpts that
 	// sculpt in place (one undo); without, it creates one. The recipe is checked by sculpt-recipe.js.
 	{ ...mutation('object.sculpt', 'Sculpt a clay prop from a recipe', input({ recipe: { type: 'object', properties: {}, additionalProperties: true }, edits: { type: 'array', minItems: 1, maxItems: 48, items: { type: 'object', properties: {}, additionalProperties: true } }, id, name: { type: 'string', maxLength: 240 }, placement, parent: id }, [])),
-		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape: blob|box|cylinder|torus|frame, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, roundness, taper, border }] }. Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
+		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, ...shape fields, material, finish, detail, gradient, op }] }. Shapes: blob {roundness, taper} soft forms; box {roundness}; cylinder {taper}; torus; frame {border} rims; lathe {profile [[r 0..1, y 0..1]...], smooth} turned objects (pot, vase, bottle, bowl, lampshade); tube {path [[x,y,z] each -0.5..0.5 of size], thickness m, taper, closed} ropes, vines, cables, handles, bike frames; extrude {outline [[x,y] -0.5..0.5], holes, roundness} flat cut shapes (sign, leaf, gable, star); loft {sections [{ y 0..1, points [[x,z]] } | { y, w, d, x?, z?, roundness? }], smooth} cross-sections that change (hull, car body, shoe, loaf); convex {points | seed, facetCount, facets} rocks, boulders, gems; scatter {item blade|tuft|flower|leaf|pebble|twig, count <= 4000, spread ground|shell, seed} thousands of small items as ONE part (grass, flower beds, gravel, leaf crowns). Any part: material clay|wood|straw|stone|brick|concrete|metal|glass|ceramic|plastic|rubber|fabric|paper|foliage (real texture and shine; color tints it; never fake glass with opacity or thatch with stripes) and finish matte|satin|gloss; detail {amount 0..1, scale, seed} lumpy surface (clouds, bushes, rocks, hay); gradient {color, axis, from, to} two-tone blend; op subtract|intersect turns the part into a cutter of its parent (windows, doors, arches; hollow a lathe with a smaller lathe of the same profile). Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
 	mutation('object.remove', 'Remove objects', input({ ids })),
 	mutation('object.rename', 'Rename object', input({ id, name: { type: 'string', maxLength: 240 } })),
 	mutation('object.group', 'Group objects', input({ parent: id, children: ids })),

package/src/export-workspace.js

@@ -0,0 +1,244 @@
+// Optional export folder. When the browser grants a directory, download-type
+// exports are written there; every failure path falls back to the browser's
+// normal download so an export is never lost.
+
+const DB_NAME = "cozyclay-export-workspace";
+const DB_VERSION = 1;
+const STORE = "handles";
+const FOLDER_KEY = "folder";
+const MAX_NAME = 180;
+let writeQueue = Promise.resolve();
+
+function splitExtension(name) {
+	const dot = name.lastIndexOf(".");
+	return dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+}
+
+/** A file name that cannot leave the chosen directory or break the file system. */
+function safeNameCharacter(character) {
+	const code = character.codePointAt(0);
+	if (code < 0x20 || code === 0x7f || '<>:"/\\|?*'.includes(character)) return "-";
+	return character;
+}
+
+export function sanitizeExportName(name) {
+	const leaf = String(name ?? "").split(/[\\/]/).pop() ?? "";
+	const cleaned = [...leaf]
+		.map(safeNameCharacter)
+		.join("")
+		.replace(/^[.\s]+/, "")
+		.replace(/[.\s]+$/, "")
+		.trim();
+	if (!cleaned) return "cozyclay-export";
+	if (cleaned.length <= MAX_NAME) return cleaned;
+	const [base, extension] = splitExtension(cleaned);
+	return `${base.slice(0, Math.max(1, MAX_NAME - extension.length))}${extension}`;
+}
+
+/** Browser download naming: shot.zip, shot (1).zip, shot (2).zip, ... */
+export function collisionName(name, index) {
+	const [base, extension] = splitExtension(String(name));
+	return `${base} (${index})${extension}`;
+}
+
+async function fileHandleForWrite(directory, name) {
+	const safe = sanitizeExportName(name);
+	for (let index = 0; index < 10_000; index += 1) {
+		const candidate = index === 0 ? safe : collisionName(safe, index);
+		try {
+			await directory.getFileHandle(candidate);
+		} catch (error) {
+			if (error?.name === "NotFoundError") {
+				return { handle: await directory.getFileHandle(candidate, { create: true }), name: candidate };
+			}
+			// A folder with the export's name is a collision, not a reason to fail.
+			if (error?.name === "TypeMismatchError") continue;
+			throw error;
+		}
+	}
+	throw new Error("No free export file name.");
+}
+
+async function writeBlobNow(directory, blob, name) {
+	const target = await fileHandleForWrite(directory, name);
+	let writable = null;
+	try {
+		writable = await target.handle.createWritable();
+		await writable.write(blob);
+		await writable.close();
+		return { name: target.name, bytes: blob.size };
+	} catch (error) {
+		try { await writable?.abort(); } catch { /* the stream may already be closed */ }
+		try { await directory.removeEntry(target.name); } catch { /* best-effort cleanup */ }
+		throw error;
+	}
+}
+
+/** Write one export without overwriting an existing file. Writes are serialized
+ * so two overlapping exports cannot both claim the same free name. */
+export function writeBlobToDirectory(directory, blob, name) {
+	const run = () => writeBlobNow(directory, blob, name);
+	const result = writeQueue.then(run, run);
+	writeQueue = result.then(() => undefined, () => undefined);
+	return result;
+}
+
+function clickDownload(source, name) {
+	if (typeof document === "undefined") throw new Error("A browser download is unavailable here.");
+		if (typeof source === "string" && !/^(?:blob:|data:|https?:\/\/|\/)/i.test(source)) {
+		throw new Error("Unsupported export source.");
+	}
+	const anchor = document.createElement("a");
+	let url = null;
+	if (typeof source === "string") {
+		anchor.href = source;
+	} else {
+		url = URL.createObjectURL(source);
+		anchor.href = url;
+	}
+	anchor.download = sanitizeExportName(name);
+	document.body.appendChild(anchor);
+	anchor.click();
+	anchor.remove();
+	if (url) setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}
+
+async function toBlob(source) {
+	if (source instanceof Blob) return source;
+	if (typeof source === "string") {
+		const response = await fetch(source);
+		if (!response.ok) throw new Error(`Export source could not be read: ${response.status}`);
+		return response.blob();
+	}
+	throw new TypeError("An export must be a Blob or a URL.");
+}
+
+function openDb() {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(DB_NAME, DB_VERSION);
+		request.onupgradeneeded = () => request.result.createObjectStore(STORE);
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+		request.onblocked = () => reject(new Error("Export folder storage is blocked."));
+	});
+}
+
+async function storedHandle() {
+	try {
+		const db = await openDb();
+		try {
+			return await new Promise((resolve, reject) => {
+				const request = db.transaction(STORE, "readonly").objectStore(STORE).get(FOLDER_KEY);
+				request.onsuccess = () => resolve(request.result ?? null);
+				request.onerror = () => reject(request.error);
+			});
+		} finally {
+			db.close();
+		}
+	} catch {
+		return null;
+	}
+}
+
+async function storeHandle(handle) {
+	const db = await openDb();
+	try {
+		await new Promise((resolve, reject) => {
+			const transaction = db.transaction(STORE, "readwrite");
+			transaction.objectStore(STORE).put(handle, FOLDER_KEY);
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+		});
+	} finally {
+		db.close();
+	}
+}
+
+async function permissionOf(handle) {
+	if (!handle) return "denied";
+	if (typeof handle.queryPermission !== "function") return "granted";
+	try {
+		return await handle.queryPermission({ mode: "readwrite" });
+	} catch {
+		return "denied";
+	}
+}
+
+export function canChooseExportWorkspace() {
+	return typeof window !== "undefined" && typeof window.showDirectoryPicker === "function";
+}
+
+/** Ask for the folder; the picker grants read/write for this session. */
+export async function chooseExportWorkspace() {
+	if (!canChooseExportWorkspace()) throw new Error("This browser cannot choose an export folder.");
+	const handle = await window.showDirectoryPicker({ id: "cozyclay-export-folder", mode: "readwrite" });
+	await storeHandle(handle);
+	return handle;
+}
+
+/** The remembered folder and its current permission, if any. */
+export async function loadExportWorkspace() {
+	const handle = await storedHandle();
+	if (!handle) return null;
+	return { handle, permission: await permissionOf(handle) };
+}
+
+export async function requestExportWorkspacePermission(handle) {
+	if (await permissionOf(handle) === "granted") return "granted";
+	if (typeof handle?.requestPermission !== "function") return "granted";
+	try {
+		return await handle.requestPermission({ mode: "readwrite" });
+	} catch {
+		return "denied";
+	}
+}
+
+export async function clearExportWorkspace() {
+	let db = null;
+	try {
+		db = await openDb();
+		await new Promise((resolve, reject) => {
+			const transaction = db.transaction(STORE, "readwrite");
+			transaction.objectStore(STORE).delete(FOLDER_KEY);
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+		});
+		return true;
+	} catch {
+		return false;
+	} finally {
+		db?.close();
+	}
+}
+
+/** Save an export to the chosen folder, or hand it to the browser on any miss. */
+export async function saveExport(source, name, options = {}) {
+	const injectedDirectory = Object.prototype.hasOwnProperty.call(options, "directory");
+	const download = options.download ?? clickDownload;
+	if (!injectedDirectory && !canChooseExportWorkspace()) {
+		download(source, name);
+		return { method: "download", name: sanitizeExportName(name), reason: "unsupported" };
+	}
+	let directory = options.directory ?? null;
+	let permission = injectedDirectory ? (options.permission ?? "granted") : "denied";
+	if (!injectedDirectory) {
+		const workspace = await loadExportWorkspace();
+		directory = workspace?.handle ?? null;
+		permission = workspace?.permission ?? "denied";
+	}
+	if (!directory) {
+		download(source, name);
+		return { method: "download", name: sanitizeExportName(name), reason: "no-workspace" };
+	}
+	if (permission !== "granted") {
+		download(source, name);
+		return { method: "download", name: sanitizeExportName(name), reason: "workspace-permission" };
+	}
+	try {
+		const written = await writeBlobToDirectory(directory, await toBlob(source), name);
+		return { method: "workspace", ...written, folderName: directory.name ?? "Export folder" };
+	} catch (error) {
+		download(source, name);
+		return { method: "download", name: sanitizeExportName(name), reason: "workspace-write-failed", error };
+	}
+}

package/src/keyframe-pack.js

@@ -55,10 +55,14 @@ function readmeText({ shot, fps, hasLast, hasClip, ext, hasStylized }) {
 	lines.push(
 		"- camera.json: camera reference. The recorded camera move, fps, and",
 		"  frame range to reproduce the framing over time.",
-		"- blocking-depth.mp4: shot-wide normalised depth video; lighter pixels are closer.",
 		"- prompt.txt: the text prompt describing the intended action.",
 	);
 	if (hasStylized) lines.push("- stylized.png: the stylized picture of this panel; first.png is its greybox.");
+	lines.push(
+		"",
+		"Not in this pack: the shot-wide depth video (blocking-depth.mp4) is a",
+		"separate export - use Depth (mp4) in the export menu.",
+	);
 	return lines.join("\n") + "\n";
 }
 

package/src/live-control.js

@@ -11,8 +11,11 @@ const MOTION_TELEMETRY_EVENTS = new Set([
 const LIVE_TELEMETRY_EVENTS = new Set([...MOTION_TELEMETRY_EVENTS, ...EXECUTION_TELEMETRY_EVENTS.filter((event) => event.startsWith("mcp:"))]);
 
 const LIVE_CONTROL_PORT = import.meta.env?.VITE_COZYCLAY_LIVE_PORT ?? "5184";
-export const liveControlUrl = (port = LIVE_CONTROL_PORT) => `ws://127.0.0.1:${port}/live`;
-const LIVE_CONTROL_URL = liveControlUrl();
+// The npm launcher serves a prebuilt bundle, so the build-time port above is
+// fixed; it injects the hub port it actually started as __COZYCLAY_LIVE_PORT__
+// (#862). A valid runtime value wins over the build-time default.
+export const resolveLiveControlPort = (runtime = globalThis.__COZYCLAY_LIVE_PORT__) => (/^[1-9]\d{0,4}$/.test(String(runtime)) && Number(runtime) < 65536 ? String(runtime) : LIVE_CONTROL_PORT);
+export const liveControlUrl = (port = resolveLiveControlPort()) => `ws://127.0.0.1:${port}/live`;
 // Reconnect schedule: 1 s doubling to a 15 s cap with +-25 % jitter, so a hub
 // that comes back does not take every editor's retry in the same millisecond.
 const LIVE_RECONNECT_BASE_MS = 1_000;
@@ -147,10 +150,8 @@ export async function dispatchLiveFrame(data, handlers = {}) {
 	}
 }
 
-/**
- * Open the editor's one-way client connection. Failures are intentionally
- * silent: a studio remains a fully local editor when the MCP server is absent.
- */
+// Open the editor's one-way client connection. Failures are intentionally
+// silent: a studio remains a fully local editor when the MCP server is absent.
 export function createLiveControl({
 	handlers = {},
 	onWorkspace = () => {},
@@ -164,7 +165,7 @@ export function createLiveControl({
 	// Optional identity for the hub's live_status listing (scene/project names).
 	meta = null,
 	WebSocketImpl = globalThis.WebSocket,
-	url = LIVE_CONTROL_URL,
+	url = liveControlUrl(),
 	timers = defaultTimers,
 	random = Math.random,
 	// Aliased on purpose: an unqualified call to a binding named `listen` reads
@@ -377,6 +378,12 @@ export function createLiveControl({
 		setHandlers(nextHandlers) {
 			currentHandlers = nextHandlers && typeof nextHandlers === "object" ? nextHandlers : {};
 		},
+		// Opening another project renames the tab; the next hello carries the new
+		// label and an open socket tells the hub now, so status stays truthful.
+		setMeta(nextMeta) {
+			meta = nextMeta && typeof nextMeta === "object" ? nextMeta : null;
+			if (meta) send({ type: "meta", meta });
+		},
 		close() {
 			stopped = true;
 			clearRetry();