cozyclay 3.0.2 → 3.0.3

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.2\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"7232c78719451c250c0be94e5f375e56c3c05984e94882724c50048b900c6c71\"}","signature":"+LLNPJc5HYZikPGbfrI57GjEjarn3TRJiaHrrsn4z1CuRMN958copspe2aRT+Y3j5wBo1vH0gYI2UsYn2J6sBA=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.3\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"b8a07fdd5d546c0314c6099680d3569a89a01e59bd3a442fb2360f1acec56330\"}","signature":"uZinWHO8tjMSZNdv8SjUSnLeHER+UvdGPW6ay++FCJiXOt8eIKjw0bYpN4HJpoNQG6/i9RBBeKMdrPBepn76Ag=="}

package/dist/index.html

@@ -301,9 +301,9 @@
         .btn, a.card, .seg button, .tutorial-steps li { transition: none; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/landing-mq5bnqFE.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/analytics-DbKG0NgD.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-CrGZ3n_O.js">
+    <script type="module" crossorigin src="/assets/landing-DYg87MDY.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/analytics-BibyE5ar.js">
+    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-Qx7SKl38.js">
   </head>
   <body>
     <header class="site">

package/dist/workflow/index.html

@@ -8,11 +8,11 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-dUhurYUc.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-BSA22Ofr.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-DbKG0NgD.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-BibyE5ar.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-7J-w5oNh.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-DBYQBR0T.js">
     <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-_S8NQl5B.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",

package/src/bus-task-scopes.js

@@ -0,0 +1,69 @@
+// The document targets a command writes, known before it runs, for tasks that edit one scene at once (parallel Studio
+// tasks, P1). A key names one target: object:<id> (a group carries its subtree), character:<id> (its placement, its
+// take, its IK), shot:<id> (its camera, rail and keys), or one of the singletons stage (light, environment, lens),
+// timeline (frame count, shot order and ranges) and scene (documents, the cast library, a replace of a whole kind).
+// timeline and scene are exclusive: no other task runs beside them. A command that only creates (object.add, a kit,
+// character.add) needs no key: what it makes joins its task. A command this table does not know writes scene, so a
+// new command is safe until it is named here.
+const EXCLUSIVE_KEYS = new Set(['timeline', 'scene']);
+const KEY = /^(?:(?:object|character|shot):[A-Za-z0-9][A-Za-z0-9._:-]*|stage|timeline|scene)$/;
+export const isScopeKey = key => typeof key === 'string' && key.length <= 140 && KEY.test(key);
+
+const SCENE = ['cast.replace', 'cast.setCustomPoses', 'cast.showExtras', 'cast.removePose', 'objects.replace', 'shot.replace', 'ai.prepareShot'];
+const TIMELINE = ['shot.create', 'shot.createStill', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.reorder', 'shot.setRange', 'shot.setTimeline'];
+const CREATE = ['object.add', 'object.createKit', 'asset.import', 'character.add'];
+const CHARACTER = /^(character\.|characters?\b|cast\.(savePose|setLayer)$|ik\.|motion\.)/;
+
+/** object:<id> and every object under it. */
+function objectKeys(ids, state) {
+	const rows = state?.objects ?? [], out = new Set();
+	const visit = id => { if (!id || out.has(`object:${id}`)) return; out.add(`object:${id}`); for (const row of rows) if (row.parent === id) visit(row.id); };
+	for (const id of ids) visit(id);
+	return [...out];
+}
+const arrangeKeys = (ops, state) => ops.flatMap(op => op.op === 'create' ? [] : op.op === 'group' ? objectKeys([op.parentId, ...op.childIds], state)
+	: op.op === 'ungroup' ? objectKeys(op.childIds, state) : objectKeys([op.id], state));
+
+/**
+ * The keys command `id` with validated `args` writes against state `state` (the bus's read), or [] when it writes
+ * none (a read, a view change, a pure creation). `entry` is its registry entry (kind, readOnly).
+ */
+export function commandKeys(id, args = {}, state = {}, entry = {}) {
+	if (entry.kind === 'document' || /^(scene|project)\./.test(id) || id === 'load_scenes' || SCENE.includes(id)) return ['scene'];
+	if (entry.readOnly || entry.kind === 'transient' || /^(view|timeline)\./.test(id) || ['motion.qa', 'motion.sample', 'motion.describe', 'motion.report', 'sculpt.compare', 'export.shotVideo'].includes(id)) return [];
+	if (CREATE.includes(id)) return [];
+	if (id === 'objects.batch') return [...new Set(args.ops.flatMap(op => commandKeys(op.name, op.args, state)))];
+	if (id === 'objects.arrange') return [...new Set(arrangeKeys(args.ops, state))];
+	if (id === 'characters.arrange') return args.ops.flatMap(op => op.op === 'create' ? [] : [`character:${op.characterId}`]);
+	if (id.startsWith('stage.') || id === 'shot.setLens') return ['stage'];
+	if (TIMELINE.includes(id)) return ['timeline'];
+	if (id.startsWith('shot.')) {
+		const shot = args.shotId ?? args.id ?? state.selectedShotId;
+		return shot ? [`shot:${shot}`] : ['timeline'];
+	}
+	if (id === 'object.group') return objectKeys([args.parent, ...args.children], state);
+	if (id === 'object.ungroup') return objectKeys(args.children, state);
+	if (id === 'object.remove') return objectKeys(args.ids, state);
+	if (id === 'object.attach' || id === 'motion.keyObject') return [`character:${args.characterId}`, ...objectKeys([args.objectId], state)];
+	if (id.startsWith('object.')) return objectKeys([args.id ?? args.objectId], state);
+	if (CHARACTER.test(id) && (args.characterId ?? args.id)) return [`character:${args.characterId ?? args.id}`];
+	return ['scene'];
+}
+
+/** The key an id a receipt names resolves to in state, or null (the scene's own id, a removed target). */
+export function keyOfId(id, state = {}) {
+	if ((state.objects ?? []).some(row => row.id === id)) return `object:${id}`;
+	if ((state.characters ?? []).some(row => row.id === id)) return `character:${id}`;
+	if ((state.shots ?? []).some(row => row.id === id)) return `shot:${id}`;
+	return null;
+}
+
+/** Why `keys` cannot join task `taskId` beside the other open tasks, or null. */
+export function scopeConflict(taskId, keys, tasks) {
+	for (const other of tasks.values()) {
+		if (other.taskId === taskId) continue;
+		const held = keys.find(key => other.keys.has(key) || EXCLUSIVE_KEYS.has(key) || [...other.keys].some(k => EXCLUSIVE_KEYS.has(k)));
+		if (held) return `${held} is held by task ${other.taskId}${other.title ? ` (${other.title})` : ''}`;
+	}
+	return null;
+}

package/src/bus-task-targets.js

@@ -0,0 +1,48 @@
+// What a task's scope keys are in the editor's document stores, for the bus's tasks (bus-tasks.js): a snapshot of a
+// key is its rows (an object's row; a character's cast row and motion layer; a shot's row) or, for stage and timeline,
+// the whole slices; restoring puts every row back where it stood (or removes a row the task created) in one composed
+// entry, so undo, history and saves see an ordinary edit. scene is not restorable: documents have no undo.
+import { StudioProtocolError } from './studio-agent-protocol.js';
+
+const ROWS = { object: [['objects', null]], character: [['cast', 'characters'], ['motion', null]], shot: [['shot', 'shots']] };
+const WHOLE = { stage: ['stage'], timeline: ['shot', 'motion'] };
+const split = key => { const at = key.indexOf(':'); return at < 0 ? [key] : [key.slice(0, at), key.slice(at + 1)]; };
+
+function put(slice, part) {
+	if ('whole' in part) return part.whole;
+	const rows = (part.path ? slice[part.path] : slice).filter(row => row.id !== part.id);
+	if (part.row) rows.splice(Math.min(part.index, rows.length), 0, part.row);
+	return part.path ? { ...slice, [part.path]: rows } : rows;
+}
+
+/** snapshotTarget(key) and restoreTargets([{ key, value }]) over the app's store domains (ports.storeDomain, ports.beginAction). */
+export function taskTargetPorts(ports) {
+	const store = domain => ports.storeDomain?.(domain)?.documentStore;
+	const rowParts = (kind, id, read) => ROWS[kind].filter(([domain]) => store(domain)).map(([domain, path]) => {
+		const slice = store(domain).read(domain), rows = (path ? slice?.[path] : slice) ?? [];
+		const index = read ? rows.findIndex(row => row.id === id) : -1;
+		return { domain, path, id, index, row: index < 0 ? undefined : rows[index] };
+	});
+	return {
+		snapshotTarget(key) {
+			const [kind, id] = split(key);
+			if (WHOLE[kind]) return WHOLE[kind].filter(store).map(domain => ({ domain, whole: store(domain).read(domain) }));
+			return ROWS[kind] ? rowParts(kind, id, true) : null;
+		},
+		restoreTargets(values) {
+			const parts = values.flatMap(({ key, value }) => {
+				if (value === null) throw new StudioProtocolError('CAPABILITY_MISSING', `${key} cannot be restored: a document change has no undo.`);
+				const [kind, id] = split(key);
+				return value ?? rowParts(kind, id, false);
+			});
+			const domains = [...new Set(parts.map(part => part.domain))];
+			if (!domains.length) return { historyEntryId: null };
+			const session = ports.beginAction(domains[0], null);
+			try {
+				for (const domain of domains.slice(1)) session.touch(domain);
+				session.run(() => { for (const part of parts) store(part.domain).write(part.domain, slice => put(slice, part)); });
+				return session.commit();
+			} catch (error) { session.cancel(); throw error; }
+		},
+	};
+}

package/src/bus-tasks.js

@@ -0,0 +1,175 @@
+// Tasks: several agents editing one scene at once (parallel Studio tasks, P1; plan in docs). A task holds a scope of
+// keys (bus-task-scopes.js) instead of the whole-scene turn lock: its commands write only inside it, each command
+// commits as its own short entry (the per-command write lock is the document's own composition), and admission reads
+// the scope's target tokens, not the scene revision, so another task's edit elsewhere never makes it stale. Before a
+// key's first write the task keeps its pre-image (ports.snapshotTarget); cancel and undo-task put the pre-images back
+// as one new entry (ports.restoreTargets), which touches no other task's keys. A mark and rollback (a script's start)
+// and undo_edit of the task's newest edit restore the same way. The user's own edits are never refused: the task's
+// 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';
+
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+const VERBS = ['begin', 'requestScope', 'mark', 'rollback', 'finish', 'cancel', 'undo'];
+const FINISHED_KEPT = 32;
+const listOf = keys => [...keys].slice(0, 6).join(', ') + (keys.length > 6 ? ` and ${keys.length - 6} more` : '');
+
+export function createBusTasks({ ports, emit }) {
+	const open = new Map(), finished = new Map(), entryTask = new Map();
+	const tokenOf = key => {
+		const [kind, id] = key.split(/:(.*)/s);
+		if (id !== undefined) return ports.readTarget?.(id) ?? 'absent';
+		const state = ports.read();
+		return kind === 'scene' ? `r${state.revision}` : `${kind}:${state.domainRevisions?.[kind === 'timeline' ? 'shot' : kind] ?? 0}`;
+	};
+	const snapshot = key => ({ key, value: ports.snapshotTarget ? ports.snapshotTarget(key) : fail('CAPABILITY_MISSING', 'This editor cannot snapshot task targets.') });
+	// A scene key has no restorable value (documents have no undo): it is left as it is and said so.
+	function restore(task, values, action) {
+		task.skipped = values.filter(v => v.value === null).map(v => v.key);
+		values = values.filter(v => v.value !== null);
+		if (!values.length) return null;
+		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))];
+		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.`);
+		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)); }
+	}
+	function receipt(id, task, request, before, { historyEntryId = null, affectedIds = [], output, warnings = [] } = {}) {
+		const after = ports.read();
+		if (task.skipped?.length) warnings = [...warnings, { code: 'SCOPE_NOT_RESTORED', message: `Left as they are (a document change has no undo): ${listOf(task.skipped)}.` }];
+		task.skipped = null;
+		return validateReceipt({ ok: true, status: 'completed', kind: 'transaction', commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+			action: id, txId: task.taskId, authored: Boolean(historyEntryId), revision: { before: before.revision, after: after.revision },
+			affectedIds: historyEntryId && !affectedIds.length ? task.restored : affectedIds, delta: [],
+			checks: { coverage: 'task-scope' }, warnings, undo: historyEntryId ? { historyEntryId, entries: 1, canUndoDirect: false } : null,
+			output: { scope: [...task.keys], ...output } });
+	}
+	const ownerOf = (request, taskId) => { if (request.origin !== 'agent' || request.taskId !== taskId) fail('CAPABILITY_MISSING', 'Only the owning task can control it.'); };
+	return {
+		get size() { return open.size; },
+		controls: (object, identifier) => Object.fromEntries(VERBS.map(verb => [`task.${verb}`,
+			verb === 'begin' || verb === 'requestScope'
+				? { ...object({ taskId: identifier, scope: { type: 'array', items: { type: 'string' }, maxItems: 64 } }), properties: { taskId: identifier, scope: { type: 'array', items: { type: 'string' }, maxItems: 64 }, reads: { type: 'array', items: { type: 'string' }, maxItems: 64 }, title: { type: 'string', maxLength: 120 } } }
+				: object({ taskId: identifier })])),
+		/** The open task a request names (null without one); a request naming a closed task is refused. */
+		of(request, id) {
+			if (!request.taskId) return null;
+			const task = open.get(request.taskId);
+			if (!task && !id.startsWith('task.')) fail('STALE_TARGET', `Task ${request.taskId} is not open.`);
+			return task ?? null;
+		},
+		/** task.* controls. `busy` says why no task may begin (an agent turn or a command transaction is open). */
+		control(id, args, request, before, busy) {
+			if (id === 'task.undo') {
+				const task = finished.get(args.taskId) ?? fail('UNDO_EXPIRED', `Task ${args.taskId} is not a finished task this editor still holds.`);
+				const moved = [...task.final].filter(([key, token]) => tokenOf(key) !== token).map(([key]) => key);
+				if (moved.length) fail('UNDO_CONFLICT', `Changed since the task finished: ${listOf(moved)}; undo those first or edit by hand.`);
+				const historyEntryId = restore(task, [...task.pre.values()], 'undone');
+				finished.delete(args.taskId);
+				return receipt(id, task, request, before, { historyEntryId, affectedIds: task.affectedIds });
+			}
+			ownerOf(request, args.taskId);
+			if (id === 'task.begin') {
+				if (busy) fail('TARGET_BUSY', busy);
+				if (open.has(args.taskId) || finished.has(args.taskId)) fail('INVALID_ARGUMENT', `Task ${args.taskId} already exists.`);
+				const task = { taskId: args.taskId, title: args.title ?? '', keys: new Set(), reads: new Set(args.reads ?? []), tokens: new Map(), pre: new Map(), edits: [], notices: [], affectedIds: [] };
+				grant(task, args.scope);
+				open.set(task.taskId, task);
+				emit?.({ type: 'task.begun', taskId: task.taskId, scope: [...task.keys] });
+				return receipt(id, task, request, before);
+			}
+			const task = open.get(args.taskId) ?? fail('STALE_TARGET', `Task ${args.taskId} is not open.`);
+			if (id === 'task.requestScope') { grant(task, args.scope); return receipt(id, task, request, before); }
+			if (id === 'task.mark') { task.mark = { values: [...task.keys].map(snapshot), keys: new Set(task.keys) }; return receipt(id, task, request, before); }
+			if (id === 'task.rollback') {
+				const mark = task.mark ?? fail('STALE_TARGET', 'The task has no mark to roll back to.');
+				task.mark = null;
+				const after = [...task.keys].filter(key => !mark.keys.has(key)).map(key => task.pre.get(key) ?? snapshot(key));
+				const historyEntryId = restore(task, [...mark.values, ...after], 'rolledBack');
+				task.edits = task.edits.filter(edit => edit.mark !== mark);
+				return receipt(id, task, request, before, { historyEntryId });
+			}
+			open.delete(task.taskId);
+			if (id === 'task.cancel') {
+				const historyEntryId = restore(task, [...task.pre.values()], 'cancelled');
+				return receipt(id, task, request, before, { historyEntryId, affectedIds: task.affectedIds });
+			}
+			task.final = new Map([...task.pre.keys()].map(key => [key, tokenOf(key)]));
+			finished.set(task.taskId, task);
+			while (finished.size > FINISHED_KEPT) finished.delete(finished.keys().next().value);
+			emit?.({ type: 'task.finished', taskId: task.taskId });
+			return receipt(id, task, request, before, { affectedIds: task.affectedIds, output: { edits: task.edits.length } });
+		},
+		/**
+		 * Admits a command: a task writes only inside its scope, on targets nobody else changed since it last looked; a
+		 * wire caller outside any task may not write a running task's keys; the UI always may. Answers the point a
+		 * task's edit restores to (undo_edit of it), after keeping each key's first pre-image.
+		 */
+		admit(task, entry, args, request, before) {
+			if (!task && (request.origin === 'ui' || !open.size)) return null;
+			const keys = entry?.id ? commandKeys(entry.id, args, before, entry) : [];
+			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.`);
+				return null;
+			}
+			const outside = keys.filter(key => !task.keys.has(key));
+			if (outside.length) fail('SCOPE_DENIED', `Outside this task's scope: ${listOf(outside)}. Ask for it with task.requestScope, or leave it to the task that holds it.`);
+			const moved = keys.filter(key => task.tokens.has(key) && tokenOf(key) !== task.tokens.get(key));
+			if (moved.length) {
+				for (const key of moved) task.tokens.set(key, tokenOf(key));
+				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 };
+		},
+		/** 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 = [];
+			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); if (!point.keys.includes(key)) { task.pre.set(key, { key, value: undefined }); point.values.push({ key, value: undefined }); } }
+			}
+			for (const key of task.keys) task.tokens.set(key, tokenOf(key));
+			if (recorded.authored) {
+				task.edits.push({ receiptId: recorded.receiptId, values: point.values, keys: point.keys, mark: point.mark });
+				task.affectedIds = [...new Set([...task.affectedIds, ...recorded.affectedIds])];
+				if (recorded.undo?.historyEntryId) entryTask.set(recorded.undo.historyEntryId, task.taskId);
+				for (const other of open.values()) for (const key of point.keys) if (other !== task && other.reads.has(key)) {
+					other.notices.push({ code: 'DEPENDENCY_CHANGED', message: `${key}, which this task reads, was changed by task ${task.taskId}.` });
+					emit?.({ type: 'task.dependencyChanged', taskId: other.taskId, key, by: task.taskId });
+				}
+			}
+			const heard = task.notices.splice(0);
+			return heard.length || warnings.length ? { ...recorded, warnings: [...recorded.warnings, ...warnings, ...heard].slice(0, 12) } : recorded;
+		},
+		/** History traversal: undo_edit of a task's newest edit inside it; the UI's undo stops at a running task's entry. */
+		traversal(id, args, request, before, frontier) {
+			const task = request.taskId ? open.get(request.taskId) : null;
+			if (task && id === 'edit.undo') {
+				const at = task.edits.findIndex(edit => edit.receiptId === args.receiptId);
+				if (at < 0) fail('TARGET_BUSY', `Inside a task, undo_edit takes the receiptId of the task's own newest edit${task.edits.length ? ` (now ${task.edits.at(-1).receiptId})` : ''}.`);
+				if (at < task.edits.length - 1) fail('UNDO_CONFLICT', `Later edits of this task come after it; undo them first, newest first: ${task.edits.slice(at + 1).reverse().map(edit => edit.receiptId).join(', ')}.`);
+				const edit = task.edits.pop(), historyEntryId = restore(task, edit.values, 'editUndone');
+				return receipt(id, task, request, before, { historyEntryId, output: { undoneReceiptId: edit.receiptId } });
+			}
+			const owner = open.get(entryTask.get(frontier));
+			if (!task && owner) fail('TARGET_BUSY', `The last edit belongs to running task ${owner.taskId}${owner.title ? ` (${owner.title})` : ''}; cancel or undo it from that task.`);
+			return null;
+		},
+		dispose() { open.clear(); finished.clear(); entryTask.clear(); },
+	};
+}

package/src/command-bus.js

@@ -1,40 +1,11 @@
 // The Studio command runner. The registry owns declarations/implementations;
 // the editor ports own native state/history, and the existing journal owns
 // idempotency. Synchronous UI actions stay synchronous (including user gestures).
-import { HISTORY_LIMIT } from './history.js';
 import { StudioProtocolError, StudioSchemas, validateStudioSchema, validateReceipt, validateStudioIdentity, refusalCode } from './studio-agent-protocol.js';
 import { agentTurnControls, markAgentTurn, turnEditPoint, recordTurnEdit, undoTurnEdit } from './agent-turn-mark.js';
+import { createBusTasks } from './bus-tasks.js';
 
-// A batching/retention adapter over the existing object history owner. The
-// native store still owns every snapshot and transition; this tracks only the
-// retained pre-image identities needed by receipts.
-export function withCommandHistory(store) {
-  let past = [], future = [], group = null;
-  const adapter = Object.create(store);
-  const pushed = before => { if (before !== store.present()) { past.push(before); past = past.slice(-HISTORY_LIMIT); future = []; } };
-  adapter.hasHistoryState = state => state === store.present() || past.includes(state) || future.includes(state);
-  adapter.settle = (...args) => { const before = store.present(); store.settle(...args); pushed(before); };
-  adapter.applyAtomic = fn => {
-    if (group) { if (!group.running) fail('TARGET_BUSY', 'A command transaction owns the object history.'); return store.applyIn(group.token, fn); }
-    adapter.settle(); const before = store.present(); store.applyAtomic(fn); pushed(before);
-  };
-  adapter.begin = (...args) => { adapter.settle(); return store.begin(...args); };
-  adapter.end = (token, options) => { const before = store.present(), ended = store.end(token, options); if (options.commit) pushed(before); return ended; };
-  adapter.undo = () => { adapter.settle(); const before = store.present(), restored = store.undo(); if (restored !== null) { past.pop(); future.unshift(before); } return restored; };
-  adapter.redo = () => { const before = store.present(), restored = store.redo(); if (restored !== null) { past.push(before); future.shift(); } return restored; };
-  adapter.beginCommand = () => {
-    if (group) fail('TARGET_BUSY', 'An object command is already in progress.');
-    adapter.settle(); const before = store.present();
-    const current = { running: 0, token: store.begin('command-bus', () => { current.closed = true; group = null; }) }; group = current;
-    const check = () => { if (current.closed) fail('STALE_TARGET', 'Native object transaction was retired.'); };
-    return {
-      run(fn) { check(); current.running++; try { const result = fn(); if (result?.then) return result.finally(() => { current.running--; }); current.running--; return result; } catch (error) { current.running--; throw error; } },
-      commit() { check(); current.closed = true; group = null; store.end(current.token, { commit: true }); pushed(before); return before !== store.present(); },
-      cancel() { if (current.closed) return false; current.closed = true; group = null; return store.end(current.token, { commit: false }); },
-    };
-  };
-  return adapter;
-}
+export { withCommandHistory } from './command-history.js';
 
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -47,6 +18,7 @@ export function createCommandBus({ registry, ports }) {
   const pending = new Map(), transactions = new Map(), jobs = new Map(), listeners = new Set();
   const confirmations = new Map(), historyReceipts = new Map();
   let agentTurn = null;
+  const tasks = createBusTasks({ ports, emit: event => emit(event) });
   function exposure(entry, args, request) {
     if (request.origin === 'ui') return;
     if (entry.exposure === 'ui-only') fail('CAPABILITY_MISSING', entry.uiOnlyHint ?? 'This command is available only from the Studio UI.');
@@ -63,7 +35,7 @@ export function createCommandBus({ registry, ports }) {
   const object = properties => ({ type: 'object', properties, required: Object.keys(properties), additionalProperties: false });
   const argsSchema = { type: 'object', properties: {}, required: [], additionalProperties: true };
   const controls = {
-    ...agentTurnControls(object, identifier),
+    ...agentTurnControls(object, identifier), ...tasks.controls(object, identifier),
     'run.begin': object({ id: identifier, args: argsSchema }),
     'run.update': object({ txId: identifier, args: argsSchema }),
     'run.commit': object({ txId: identifier }),
@@ -84,10 +56,11 @@ export function createCommandBus({ registry, ports }) {
     tx.timer = (ports.setTimeout ?? setTimeout)(() => cancelTransaction(tx, true), ports.transactionIdleMs ?? 30_000);
   }
   function control(id, args, request, before) {
+    if (id.startsWith('task.')) return tasks.control(id, args, request, before, agentTurn ? 'Finish the agent turn first.' : transactions.size ? 'Finish the open command transaction first.' : null);
     if (id.startsWith('agent.turn.')) {
       if (request.origin !== 'agent' || request.turnId !== args.turnId) fail('CAPABILITY_MISSING', 'Only the owning agent turn can control this transaction.');
       if (id === 'agent.turn.begin') {
-        if (agentTurn || transactions.size) fail('TARGET_BUSY', 'Finish the open transaction first.');
+        if (agentTurn || transactions.size || tasks.size) fail('TARGET_BUSY', 'Finish the open transaction first.');
         agentTurn = { txId: args.turnId, before, affectedIds: new Set(), toasts: [], session: null };
         return transactionReceipt(id, agentTurn, request, before);
       }
@@ -105,7 +78,8 @@ export function createCommandBus({ registry, ports }) {
     // Every Studio turn opens a turn transaction (#715), so "undo the last thing" arrives inside one. Until the
     // turn has authored (no session yet) history traversal is safe: the undo lands as its own entry (#735).
     // After that the turn owns the frontier: its own agent may undo its newest edit (agent-turn-mark.js).
-    const traversal = id === 'edit.undo' || id === 'edit.redo';
+    const traversal = id === 'edit.undo' || id === 'edit.redo', scoped = traversal && tasks.traversal(id, args, request, before, id === 'edit.undo' ? ports.history?.(false) : null);
+    if (scoped) return scoped;
     if (agentTurn && !id.startsWith('job.') && !(traversal && !agentTurn.session)) { if (id === 'edit.undo' && request.turnId === agentTurn.txId) return validateReceipt(undoTurnEdit(agentTurn, args, request, before, () => ports.read())); fail('TARGET_BUSY', 'Finish the agent turn before traversing history or opening another transaction.'); }
     if (traversal) {
       const redo = id === 'edit.redo', historyEntryId = ports.history?.(redo);
@@ -242,7 +216,7 @@ export function createCommandBus({ registry, ports }) {
     if (agentTurn && !same(agentTurn.before.host, before.host)) {
       agentTurn.session?.cancel({ restore: false }); agentTurn = null;
     }
-    const turn = request.origin === 'agent' && request.turnId === agentTurn?.txId ? agentTurn : null;
+    const turn = request.origin === 'agent' && request.turnId === agentTurn?.txId ? agentTurn : null, task = tasks.of(request, id);
     const recordAction = (domain, invoke, targetId, nested = false) => {
       if (!turn) return ports.recordAction(domain, invoke, targetId, nested);
       // Enrol each owner in the existing composed session. Do not commit (or
@@ -293,13 +267,14 @@ export function createCommandBus({ registry, ports }) {
         // can advance the revision while their wire request is in transit.
         // Document identity and the job's own publication fence still apply.
         // A readOnly action (declared data, e.g. motion.qa) only measures: no revision or gesture fence, the host check above still holds.
-        if (!entry?.readOnly && !['job.await', 'job.cancel', 'agent.turn.mark', 'agent.turn.rollback', 'agent.turn.finish', 'agent.turn.cancel'].includes(id) && request.expectedRevision !== before.revision) fail('STALE_SCENE', 'Authored state changed; obtain fresh intent.');
+        if (!task && !id.startsWith('task.') && !entry?.readOnly && !['job.await', 'job.cancel', 'agent.turn.mark', 'agent.turn.rollback', 'agent.turn.finish', 'agent.turn.cancel'].includes(id) && request.expectedRevision !== before.revision) fail('STALE_SCENE', 'Authored state changed; obtain fresh intent.');
         if (!entry?.readOnly && before.busy && !turn && !transactions.has(validated.txId) && !id.startsWith('job.')) fail('TARGET_BUSY', 'Finish the current editor gesture first.');
       }
       if (controls[id]) return mapResult(control(id, validated, request, before), remember, rejected);
       if (transactions.size) fail('TARGET_BUSY', 'Finish or cancel the open command transaction first.');
       if (turn && entry.kind === 'document') fail('TARGET_BUSY', 'Finish the agent turn before changing documents.');
       exposure(entry, validated, request);
+      const scoped = tasks.admit(task, entry, validated, request, before);
       releaseToasts = ports.captureToasts?.(toast => toasts.push(typeof toast === 'string' ? { message: toast } : toast));
       const domain = entry.domain ?? entry.undoDomain;
       const targetId = entry.target?.(validated, before) ?? validated.characterId ?? validated.shotId ?? validated.objectId;
@@ -317,7 +292,7 @@ export function createCommandBus({ registry, ports }) {
           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 && 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 (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.`);
         },
         commit(apply) {
@@ -363,7 +338,7 @@ export function createCommandBus({ registry, ports }) {
         releaseToasts?.(); releaseToasts = null;
         const refused = output?.output === undefined ? toastRefusal() : null; // a job that answered was not refused by a toast that showed meanwhile
         if (refused) throw refused;
-        return recordTurnEdit(turn, point, remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts, turn)));
+        return tasks.record(scoped, recordTurnEdit(turn, point, remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts, turn))));
       });
       const finished = value?.then ? value.then(finish) : finish(value);
       const answer = finished?.then ? finished.catch(rejected) : finished;
@@ -405,5 +380,5 @@ export function createCommandBus({ registry, ports }) {
     // Trusted UI adapter only: wire callers can consume, never mint a token.
     confirm(id, args = {}) { const prepared = registry.prepare(id, args), token = crypto.randomUUID(); confirmations.set(token, { id, args: prepared.args, host: ports.read().host, expires: (ports.now ?? Date.now)() + 300_000 }); return token; },
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
-    dispose() { agentTurn?.session?.cancel(); agentTurn = null; for (const tx of transactions.values()) cancelTransaction(tx); for (const job of jobs.values()) if (!job.outcome) job.controller.abort(new StudioProtocolError('CANCELLED', 'Studio closed.')); listeners.clear(); } };
+    dispose() { agentTurn?.session?.cancel(); agentTurn = null; tasks.dispose(); for (const tx of transactions.values()) cancelTransaction(tx); for (const job of jobs.values()) if (!job.outcome) job.controller.abort(new StudioProtocolError('CANCELLED', 'Studio closed.')); listeners.clear(); } };
 }

package/src/command-history.js

@@ -0,0 +1,36 @@
+// The object history adapter the command bus uses (moved out of command-bus.js unchanged).
+import { HISTORY_LIMIT } from './history.js';
+import { StudioProtocolError } from './studio-agent-protocol.js';
+
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+
+// A batching/retention adapter over the existing object history owner. The
+// native store still owns every snapshot and transition; this tracks only the
+// retained pre-image identities needed by receipts.
+export function withCommandHistory(store) {
+  let past = [], future = [], group = null;
+  const adapter = Object.create(store);
+  const pushed = before => { if (before !== store.present()) { past.push(before); past = past.slice(-HISTORY_LIMIT); future = []; } };
+  adapter.hasHistoryState = state => state === store.present() || past.includes(state) || future.includes(state);
+  adapter.settle = (...args) => { const before = store.present(); store.settle(...args); pushed(before); };
+  adapter.applyAtomic = fn => {
+    if (group) { if (!group.running) fail('TARGET_BUSY', 'A command transaction owns the object history.'); return store.applyIn(group.token, fn); }
+    adapter.settle(); const before = store.present(); store.applyAtomic(fn); pushed(before);
+  };
+  adapter.begin = (...args) => { adapter.settle(); return store.begin(...args); };
+  adapter.end = (token, options) => { const before = store.present(), ended = store.end(token, options); if (options.commit) pushed(before); return ended; };
+  adapter.undo = () => { adapter.settle(); const before = store.present(), restored = store.undo(); if (restored !== null) { past.pop(); future.unshift(before); } return restored; };
+  adapter.redo = () => { const before = store.present(), restored = store.redo(); if (restored !== null) { past.push(before); future.shift(); } return restored; };
+  adapter.beginCommand = () => {
+    if (group) fail('TARGET_BUSY', 'An object command is already in progress.');
+    adapter.settle(); const before = store.present();
+    const current = { running: 0, token: store.begin('command-bus', () => { current.closed = true; group = null; }) }; group = current;
+    const check = () => { if (current.closed) fail('STALE_TARGET', 'Native object transaction was retired.'); };
+    return {
+      run(fn) { check(); current.running++; try { const result = fn(); if (result?.then) return result.finally(() => { current.running--; }); current.running--; return result; } catch (error) { current.running--; throw error; } },
+      commit() { check(); current.closed = true; group = null; store.end(current.token, { commit: true }); pushed(before); return before !== store.present(); },
+      cancel() { if (current.closed) return false; current.closed = true; group = null; return store.end(current.token, { commit: false }); },
+    };
+  };
+  return adapter;
+}

package/src/commands/cast.js

@@ -2,7 +2,7 @@
 // name their character explicitly, so they run the same way whichever
 // character is active and whatever mode the editor is in.
 import { studioActionDeclaration } from "../studio-actions.js";
-import { characterOf, fail, changedIds } from "./shared.js";
+import { characterOf, fail, changedIds, checkPoseBones } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/character.js';
 import { createCharacterEntry, CHARACTER_KIND_IDS, POSTURES, PROXY_FIGURE_MODEL, isProxyFigure } from '../scenes.js';
@@ -43,7 +43,13 @@ export function register(registry, ports) {
 	const owner = () => ports.storeDomain('cast');
 	const mounted = () => Boolean(ports.storeDomain?.('cast')) || 'The cast document owner is not mounted.';
 	const character = characterId => owner().read().find(row => row.id === characterId) ?? fail('STALE_TARGET', `Character ${characterId} is not in this scene.`);
-	const pose = value => typeof value === 'string' ? owner().poses().find(row => row.id === value) ?? fail('STALE_TARGET', `Pose ${value} is not in the library.`) : value;
+	// Every pose path names only POSE_BONES joints: a pose sent whole, one chosen from the library by id,
+	// and every library entry written (#773).
+	const pose = value => {
+		const resolved = typeof value === 'string' ? owner().poses().find(row => row.id === value) ?? fail('STALE_TARGET', `Pose ${value} is not in the library.`) : value;
+		checkPoseBones(resolved?.bones);
+		return resolved;
+	};
 	const patch = (characterId, update) => { character(characterId); owner().update(characterId, update); };
 	// A character groups under a scene object that stands in the world. An
 	// object a character carries is refused: it rides a bone, not a route.
@@ -69,8 +75,9 @@ export function register(registry, ports) {
 		'character.setPose': ({ characterId, pose: value, clearMotion }) => { character(characterId); owner().applyPose(characterId, pose(value), clearMotion); },
 		
 		'cast.replace': ({ characters }) => owner().write(characters),
-		'cast.setCustomPoses': ({ poses }) => owner().writeState(before => ({ ...before, customPoses: poses })),
+		'cast.setCustomPoses': ({ poses }) => { for (const entry of poses) checkPoseBones(entry?.bones); owner().writeState(before => ({ ...before, customPoses: poses })); },
 		'cast.savePose': ({ pose, characterId, clearMotion }) => {
+			checkPoseBones(pose?.bones);
 			if (characterId) character(characterId);
 			owner().writeState(before => ({ ...before, customPoses: [...before.customPoses.filter(entry => entry.id !== pose.id), pose] }));
 			if (characterId) owner().applyPose(characterId, pose, clearMotion);

package/src/commands/motion.js

@@ -1,6 +1,6 @@
 // Motion and IK commands share one per-character authored-intent owner.
 import { STUDIO_IK_CHAIN_TRACKS, studioActionDeclaration } from "../studio-actions.js";
-import { fail, characterOf } from "./shared.js";
+import { fail, characterOf, checkPoseBones } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import { registerTiming, timingDeclarations } from './motion-timing.js';
 import './elements/motion.js';
@@ -41,6 +41,7 @@ export function register(registry, ports) {
 	for (const declaration of tools) registry.register({ ...declaration, available: mounted, run(args) {
 		characterOf(ports, args.characterId);
 		if (args.frame >= ports.state().frameCount) fail('INVALID_RANGE', 'IK frame is outside the timeline.');
+		checkPoseBones(args.pose.bones);
 		for (const angles of Object.values(args.pose.bones)) if (!Array.isArray(angles) || angles.length !== 3 || !angles.every(Number.isFinite)) fail('INVALID_ARGUMENT', 'Pose bones require three finite rotation angles.');
 		owner().keyPose(args.characterId, args.frame, args.pose);
 		return { affectedIds: [args.characterId], summary: declaration.label };

package/src/commands/motion3.js

@@ -48,7 +48,7 @@ const declarations = Object.freeze([
 		input: input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id,
 			topics: list({ oneOf: [{ type: "string", enum: DESCRIBE_TOPICS }, input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id }, ["topic"])] }, 8) }, []) },
 	{ id: "motion.report", label: "Read motion report", kind: "job", domain: "motion", timeoutMs: 10000, readOnly: true, description: HELP.report,
-		input: input({ specId, part: { type: "string", enum: ["groups", "timeline", "probes"], default: "groups" }, from: { type: "integer", minimum: 0, default: 0 } }, ["specId"]) },
+		input: input({ specId, characterId: id, part: { type: "string", enum: ["groups", "timeline", "probes"], default: "groups" }, from: { type: "integer", minimum: 0, default: 0 } }, []) },
 	{ id: "motion.keyObject", label: "Key held object", kind: "job", domain: "motion", timeoutMs: 120000, description: HELP.keyObject,
 		input: input({ characterId: id, objectId: id, frame: { type: "integer", minimum: 0 }, pos: numbers(3), rot: numbers(4), aim: numbers(3), roll: { type: "number" },
 			angle: { type: "number" }, remove: { type: "boolean", default: false } }, ["characterId", "objectId", "frame"]) },
@@ -198,9 +198,15 @@ export function register(registry, ports) {
 		}
 		return { affectedIds: [], summary: `Described ${topic}${name ? ` ${name}` : ""}.`, output: asArgument(() => describe(topic, name)) };
 	} });
-	registry.register({ ...declarations[4], available: always, run({ specId: wanted, part = "groups", from = 0 }) {
-		const page = reportPage(store.parts(wanted) ?? unknownSpec("specId", wanted, "compile it again"), wanted, part, from);
-		return { affectedIds: [], summary: `${page.items.length} ${part} from ${from}.`, output: page };
+	// a characterId reads the installed take's report (session 2ad2760a asked for it that way and was refused): the stored
+	// one when this session compiled that spec, else the take's QA run now
+	registry.register({ ...declarations[4], available: always, run({ specId: wanted, characterId, part = "groups", from = 0 }) {
+		const answer = (parts, id) => { const page = reportPage(parts, id, part, from); return { affectedIds: [], summary: `${page.items.length} ${part} from ${from}.`, output: page }; };
+		if (wanted) return answer(store.parts(wanted) ?? unknownSpec("specId", wanted, "compile it again"), wanted);
+		if (!characterId) fail("INVALID_ARGUMENT", "motion.report needs specId (from a motion.compile or motion.qa answer) or characterId (its installed take).");
+		const take = installed(characterId), id = specIdOf(take.spec), kept = store.parts(id);
+		if (kept) return answer(kept, id);
+		return after(compile(characterOf(ports, characterId), take.spec), r => { const out = report(r, {}); return answer(store.parts(out.specId), out.specId); });
 	} });
 	// motion.keyObject (C14): one key of a held object (or a hinge angle) in the installed take's spec, compiled
 	// and installed whatever QA says (a user edit), as one undo entry

package/src/commands/shared.js

@@ -2,9 +2,18 @@
 // object: its members are read at call time, so a run always reaches the
 // latest handlers and `ports.state()` the synchronously published document.
 import { StudioProtocolError } from "../studio-agent-protocol.js";
+import { POSE_BONES } from "../poses.js";
 
 export const fail = (code, message) => { throw new StudioProtocolError(code, message); };
 
+// A pose bone outside POSE_BONES is dropped by applyPose, so the pose falls back to the
+// rest (T) pose for that joint. Refuse it and name the joints a pose can set (#773).
+const POSE_BONE_IDS = POSE_BONES.map(entry => entry.id);
+export function checkPoseBones(bones) {
+	const unknown = Object.keys(bones ?? {}).filter(name => !POSE_BONE_IDS.includes(name));
+	if (unknown.length) fail("INVALID_ARGUMENT", `Unknown pose bone ${unknown.join(", ")}. Use one of: ${POSE_BONE_IDS.join(", ")}.`);
+}
+
 /** Ids of the rows added, changed or removed between two renders of a list. */
 export const changedIds = (before, after) => [...new Set([
 	...after.filter(row => !before.includes(row)).map(row => row.id),