cozyclay 3.0.1 → 3.0.3

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.0.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"bedf955b7367c9d4e883baa9c0b6fd14a205f6d39a3bf447f628488cd2893564\"}","signature":"+2TEXB+bXFUPN34/ls1YvimKkHfSdSCs0IiIyjIhsHqvz3j+XcKkEkqx1zjXn8MQlybgStGOS290YH40Nw1hBQ=="}
+{"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-yfZaJkWc.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/analytics-BWCqdgWA.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-DNO8kv_N.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-D78eiKTa.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-BWCqdgWA.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-U3kS2rvK.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.1",
+  "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/agent-turn-mark.js

@@ -23,8 +23,41 @@ export function markAgentTurn(id, turn) {
   const { mark } = turn;
   if (!mark) throw new StudioProtocolError('STALE_TARGET', 'The agent turn has no mark to roll back to.');
   turn.mark = null;
+  turn.edits = (turn.edits ?? []).filter(edit => edit.mark !== mark);
   // No session at the mark: everything the turn authored came after it.
   turn.session?.rollback(mark.point ?? undefined);
   turn.affectedIds = mark.affectedIds;
   return { txId: turn.txId, affectedIds: [...mark.since], toasts: [] };
 }
+
+// The turn's own edits, newest last: each keeps the savepoint before it, so undo_edit on the
+// newest one's receipt rolls back to there and the turn stays open (9240db36 was refused twice).
+/** Where the turn stands before a command runs: the savepoint, the ids so far, the open mark. */
+export const turnEditPoint = turn => turn && { point: turn.session?.savepoint() ?? null, affectedIds: new Set(turn.affectedIds), since: turn.mark && new Set(turn.mark.since), mark: turn.mark };
+
+/** Files an authored receipt of the turn with the point before it; answers the receipt. */
+export function recordTurnEdit(turn, at, recorded) {
+  if (turn && at && recorded?.ok && recorded.authored) (turn.edits ??= []).push({ ...at, receiptId: recorded.receiptId, ids: recorded.affectedIds });
+  return recorded;
+}
+
+/**
+ * edit.undo from inside the owning turn once it has authored. A receipt of the turn's newest edit
+ * rolls back to the point before it and answers the receipt (before: the bus's read at admission;
+ * read: a read after); anything else is refused with what the agent can do instead.
+ */
+export function undoTurnEdit(turn, args, request, before, read) {
+  const edits = turn.edits ?? [], at = edits.findIndex(edit => edit.receiptId === args.receiptId);
+  if (at < 0) throw new StudioProtocolError('TARGET_BUSY', `Finish the agent turn before traversing history or opening another transaction. Inside the turn, undo_edit with the receiptId of this message's newest edit reverts it${edits.length ? ` (now ${edits.at(-1).receiptId})` : ''}; an earlier message's edit is undone after this one ends.`);
+  const edit = edits[at];
+  if (at < edits.length - 1) throw new StudioProtocolError('UNDO_CONFLICT', `Later edits of this message come after it; undo them first, newest first: ${edits.slice(at + 1).reverse().map(later => later.receiptId).join(', ')}.`);
+  turn.session.rollback(edit.point ?? undefined);
+  edits.pop();
+  turn.affectedIds = edit.affectedIds;
+  // Nothing came after a mark this edit predates, so the mark moves to now: a script's rollback still finds it.
+  if (turn.mark && edit.mark !== turn.mark) turn.mark = { point: turn.session.savepoint(), affectedIds: new Set(turn.affectedIds), since: new Set() };
+  else if (turn.mark) turn.mark.since = edit.since;
+  return { ok: true, status: 'completed', kind: 'transaction', action: 'edit.undo', txId: turn.txId, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+    summary: `Undid ${edit.receiptId} inside this message.`, authored: false, revision: { before: before.revision, after: read().revision }, affectedIds: edit.ids, delta: [],
+    checks: { coverage: 'agent-turn-savepoint' }, undo: null, warnings: [], output: { undoneReceiptId: edit.receiptId } };
+}

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 } from './agent-turn-mark.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);
       }
@@ -102,12 +75,12 @@ export function createCommandBus({ registry, ports }) {
       finally { agentTurn = null; }
       return transactionReceipt(id, turn, request, turn.before);
     }
-    // Every Studio turn opens a turn transaction (#715), so "undo the last thing" arrives
-    // inside one. Until the turn has authored anything (no session yet) history traversal
-    // is safe: the undo lands as its own entry and a later edit still groups into the turn.
-    // After the first authored edit the turn owns the frontier and traversal waits (#735).
-    const traversal = id === 'edit.undo' || id === 'edit.redo';
-    if (agentTurn && !id.startsWith('job.') && !(traversal && !agentTurn.session)) fail('TARGET_BUSY', 'Finish the agent turn before traversing history or opening another transaction.');
+    // 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', 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);
       const previous = args.receiptId ? ports.receipt(args.receiptId) : historyReceipts.get(historyEntryId)
@@ -243,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
@@ -294,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;
@@ -318,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) {
@@ -358,13 +332,13 @@ export function createCommandBus({ registry, ports }) {
         const deadline = new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true }));
         return Promise.race([value, deadline]);
       };
-      const value = entry.kind === 'mutation' ? recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
+      const point = turnEditPoint(turn), value = entry.kind === 'mutation' ? recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
       const finish = ({ result, historyEntryId }) => mapResult(result, output => {
         clearTimer();
         releaseToasts?.(); releaseToasts = null;
-        const refused = toastRefusal();
+        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 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;
@@ -406,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);