cozyclay 3.0.2 → 3.1.0

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;
@@ -311,13 +286,13 @@ export function createCommandBus({ registry, ports }) {
         domainRevision = domain ? current.domainRevisions?.[domain] : null;
       };
       const nestedIds = new Set();
-      const context = { origin: request.origin, signal: controller.signal,
+      const context = { origin: request.origin, signal: controller.signal, taskId: request.taskId ?? null,
         check() {
           controller.signal.throwIfAborted();
           const current = ports.read();
           // Name the fence that tripped: the three share one code, and a bare "something changed" leaves the user and the agent guessing.
           if (!same(current.host, before.host)) fail('STALE_TARGET', 'The open document or scene changed while the job was running.');
-          if (domain && 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-compile.js

@@ -1,12 +1,16 @@
-// Where a motion compile runs. In the browser: one module Web Worker (motion3/compile-worker.js), started
-// on the first compile and reused, jobs answered in arrival order, so a compile costs the worker's time
-// and never blocks the viewport (the main thread runs the compiler ~4x slower and freezes while it does).
-// Where there is no Worker (Node, tests) or the worker fails: the same job on the calling thread,
-// synchronously, so `registry.run("motion.compile", ...)` there still answers at once. The answer is the
-// same either way (compile-job.js runs the same code on the same plain inputs).
+// Where a motion compile runs. In the browser: a pool of module Web Workers (motion3/compile-worker.js), at most
+// POOL of them, each started on first need and reused; a job takes an idle worker or waits in arrival order, so a
+// compile costs a worker's time and never blocks the viewport (the main thread runs the compiler ~4x slower and freezes
+// while it does). Two workers let two Studio tasks compile at once (parallel tasks, case 10) without a third
+// starving the editor's cores; the rest wait, and the panel shows which task's compile is waiting (compileActivity).
+// Where there is no Worker (Node, tests) or a worker fails: the same job on the calling thread, synchronously, so
+// `registry.run("motion.compile", ...)` there still answers at once. The answer is the same either way (compile-job.js
+// runs the same code on the same plain inputs), whichever worker runs it.
 import { runCompileJob } from "../motion3/compile-job.js";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
 
+const POOL = 2;
+
 /** A job error (or a worker's serialized one) as the Studio's protocol error when it carries a code. */
 function rethrow(error) {
 	if (error?.code && !(error instanceof StudioProtocolError)) throw new StudioProtocolError(error.code, error.message);
@@ -21,43 +25,63 @@ function browserWorker() {
 	return new Worker(new URL("../motion3/compile-worker.js", import.meta.url), { type: "module", name: "motion-compile" });
 }
 
+// What the editor's compiles are doing, for the panel: { running: [meta], waiting: [meta] } (meta: { taskId, characterId }).
+const watchers = new Set();
+let activity = { running: [], waiting: [] };
+const publish = next => { activity = next; for (const watcher of watchers) watcher(activity); };
+export const compileActivity = () => activity;
+export function watchCompileActivity(watcher) { watchers.add(watcher); return () => watchers.delete(watcher); }
+
 /**
- * createCompileRunner({ spawn }) -> { run(job) -> answer | Promise<answer>, takeWarning() -> string | null }
+ * createCompileRunner({ spawn, size }) -> { run(job, meta?) -> answer | Promise<answer>, takeWarning() -> string | null }
  * spawn() -> a Worker-like object (postMessage, onmessage, onerror, terminate) or null for the calling thread.
  */
-export function createCompileRunner({ spawn = browserWorker } = {}) {
-	let worker, dead = false, warning = null, next = 0;
-	const pending = new Map();
-	/** The worker failed (would not start, or crashed): every job from now on, and those in flight, run here. */
+export function createCompileRunner({ spawn = browserWorker, size = POOL } = {}) {
+	let dead = false, warning = null, next = 0;
+	const slots = [], queue = [];
+	const report = () => publish({ running: slots.filter(slot => slot.job).map(slot => slot.job.meta), waiting: queue.map(item => item.meta) });
+	/** A worker failed (would not start, or crashed): every job from now on, and those in flight or waiting, run here. */
 	const fallBack = reason => {
 		dead = true;
-		worker?.terminate?.();
-		worker = null;
 		warning ??= `The motion compile worker stopped (${reason}); compiling on the main thread, which is slower and blocks the editor while it runs.`;
-		for (const [id, { job, resolve, reject }] of pending) { pending.delete(id); try { resolve(local(job)); } catch (error) { reject(error); } }
+		const orphans = [...slots.flatMap(slot => (slot.job ? [slot.job] : [])), ...queue.splice(0)];
+		for (const slot of slots.splice(0)) slot.worker?.terminate?.();
+		for (const { job, resolve, reject } of orphans) { try { resolve(local(job)); } catch (error) { reject(error); } }
+		report();
 	};
-	const started = () => {
-		if (worker || dead) return worker;
+	/** One more worker in the pool: its slot, or null when none can start (dead: every job runs here from now on). */
+	const grow = () => {
+		let worker;
 		try { worker = spawn(); } catch (error) { fallBack(error?.message ?? String(error)); return null; }
 		if (!worker) { dead = true; return null; }
+		const slot = { worker, job: null };
 		worker.onmessage = ({ data: { id, value, error } }) => {
-			const job = pending.get(id);
-			if (!job) return;
-			pending.delete(id);
+			const job = slot.job;
+			if (!job || job.id !== id) return;
+			slot.job = null;
 			if (error) { try { rethrow(error); } catch (thrown) { job.reject(thrown); } } else job.resolve(value);
+			pump();
 		};
 		worker.onerror = event => { event?.preventDefault?.(); fallBack(event?.message || "worker error"); };
 		worker.onmessageerror = () => fallBack("an answer could not be read");
-		return worker;
+		slots.push(slot);
+		return slot;
+	};
+	const pump = () => {
+		while (!dead && queue.length) {
+			const slot = slots.find(candidate => !candidate.job) ?? (slots.length < size ? grow() : null);
+			if (!slot) break;
+			slot.job = queue.shift();
+			try { slot.worker.postMessage({ id: slot.job.id, job: slot.job.job }); } catch (error) { fallBack(error?.message ?? String(error)); return; }
+		}
+		if (dead) for (const item of queue.splice(0)) { try { item.resolve(local(item.job)); } catch (error) { item.reject(error); } }
+		report();
 	};
 	return {
-		run(job) {
-			if (!started()) return local(job);
-			return new Promise((resolve, reject) => {
-				const id = ++next;
-				pending.set(id, { job, resolve, reject });
-				try { worker.postMessage({ id, job }); } catch (error) { fallBack(error?.message ?? String(error)); }
-			});
+		run(job, meta = {}) {
+			// No worker can start here (Node, tests): answer on this thread at once, as before.
+			if (dead || (!slots.length && !grow())) return local(job);
+			return new Promise((resolve, reject) => { queue.push({ id: ++next, job, meta, resolve, reject }); pump(); });
 		},
 		/** The fallback note, once (a receipt warning), or null. */
 		takeWarning() { const note = warning; if (note) warning = ""; return note || null; },

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"]) },
@@ -105,10 +105,10 @@ export function register(registry, ports) {
 	 * spec on the character's rig and the current scene (compile-job.js) -> { stored (the spec a take keeps and its specId
 	 * names), qa, ..., take when bake is given }, at once or as a promise. opts: probes, checks, lenient, repair.
 	 */
-	const compile = (character, spec, opts = {}, bake) => {
+	const compile = (character, spec, opts = {}, bake, taskId = null) => {
 		rigOf(character);
 		const placed = bake && { position: [character.x ?? 0, character.y ?? 0, character.z ?? 0], yaw: character.rot ?? 0, ...bake };
-		return runner.run({ model: character.model, scene: sceneFor(character), spec, ...opts, ...(placed ? { bake: placed } : {}) });
+		return runner.run({ model: character.model, scene: sceneFor(character), spec, ...opts, ...(placed ? { bake: placed } : {}) }, { taskId, characterId: character.id });
 	};
 	/** The whole output, kept in the store (motion.report, delta) and cut to the receipt budget (report.js). */
 	const report = (r, head, extra = {}) => {
@@ -145,7 +145,7 @@ export function register(registry, ports) {
 		const installedSpec = () => { const take = owner().motionFor(characterId); return take?.spec && specIdOf(take.spec) === base ? structuredClone(take.spec) : null; };
 		const patched = [], source = spec ?? asArgument(() => applyPatch(store.get(base) ?? installedSpec() ?? unknownSpec("base", base), patch ?? [], patched));
 		// the take is always baked: the user watches every draft, installed or not
-		return after(compile(character, source, { probes, repair }, {}), r => {
+		return after(compile(character, source, { probes, repair }, {}, context?.taskId), r => {
 			const { qa, take } = r, notes = [...patched, ...(r.notes ?? [])];
 			// ifClean: install only a clean final result (qa.ok includes the goals; after repair when asked)
 			const wanted = install === "ifClean" ? qa.ok : install;
@@ -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/project.js

@@ -12,7 +12,7 @@ const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
 const exportAsAnimation = studioActionDeclaration("project.exportAsAnimation");
 const opening = document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token });
 const fresh = document("project.new", "Start a new project", { name, previsMode: { type: "string", enum: [...PREVIS_MODES] } });
-const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] }, name });
+const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "launch"] }, name });
 const restore = { ...document("project.restore", "Restore the remembered project", { handleToken: token }), exposure: "ui-only" };
 const browse = { id: "project.browse", label: "Browse projects", description: "Show the project browser.", kind: "transient", exposure: "ui-only", input: input() };
 export const declarations = Object.freeze([rename, save, saveAs, exportAsAnimation, opening, fresh, starter, restore, browse]);

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),

package/src/commands/shot.js

@@ -1,6 +1,6 @@
 // One semantic entry point for timeline, camera controls and agent framing.
 import { createCameraBlock, updateCameraBlock, removeCameraRail } from '../camera-block.js';
-import { addShotAtFrame, createShot, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
+import { addShotAtFrame, appendShotGrowingTake, createShot, cutAtFrame, duplicateShot, removeShot, reorderShot, resizeShot, renameShot, moveCameraKey, removeCameraKey } from '../cuts.js';
 import { reflowStillShots, stillFrameCount, STILL_FRAME_COUNT_MAX, STILL_HOLD_DEFAULT } from '../shot-authoring.js';
 import { ko } from '../locale.js';
 import { track } from '../analytics.js';
@@ -17,6 +17,7 @@ import './elements/shot.js';
 import { changedIds, fail, shotLabel } from './shared.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
+const TAKE_FRAME_MAX = 28800;
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const number = { type: 'number' };
 const frame = { type: 'integer', minimum: 0 };
@@ -30,7 +31,7 @@ const extra = [
   mutation('shot.moveKey', 'Move camera key', input({ shotId: id, keyId: id, frame })),
   mutation('shot.removeKey', 'Remove camera key', input({ shotId: id, keyId: id })),
   mutation('shot.clearKeys', 'Clear camera keys', input({ shotId: id })),
-  mutation('shot.setTimeline', 'Set shot timeline', input({ frameCount: { type: 'integer', minimum: 24, maximum: 28800 } })),
+  mutation('shot.setTimeline', 'Set shot timeline', input({ frameCount: { type: 'integer', minimum: 24, maximum: TAKE_FRAME_MAX } })),
   mutation('shot.setLens', 'Set camera lens', input({ fovDeg: { ...number, minimum: 14, maximum: 90 } })),
   mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] },
     'Frame a shot on one character (the frame_shot tool): framing.intent { size, level, view, side, focalMm } or framing.exact { position, lookAt, focalMm }. Without keyAtFrame a shot that holds one framing is reframed whole: a held shot. keyAtFrame adds a camera key there; every key eases in and out, so the camera slows to a stop at each one: key a pan or zoom from one spot with two keys (its start and end), lay a moving camera as a rail (shot.setCameraRail) and cut to a new shot for a new view. On a rail shot it puts the shot back on keys. Answers checks { derivedSize, screenFraction, clipped, behindCamera, occluded, cameraSide } for the subject at that frame.'),
@@ -84,6 +85,17 @@ export function register(registry, ports) {
     const created = written.find(shot => shot.id === still.id), { selection, view } = ports.readView();
     ports.publishView({ selection, view: { ...view, frame: created.startFrame }, shotId: created.id });
   }
+  // A clip shot goes in the free time at (or after) the playhead; with none left the take grows at its end,
+  // in the same write so one undo takes both back, and the playhead lands in the new shot.
+  function createClip() {
+    const current = owner().read(), { frameCount } = owner().state(), framing = owner().capture();
+    const placed = addShotAtFrame(current, ports.state().frame, frameCount, framing);
+    if (placed !== current) return owner().write(placed);
+    const grown = appendShotGrowingTake(current, frameCount, framing, TAKE_FRAME_MAX) ?? fail('INVALID_ARGUMENT', `The take is at its longest (${TAKE_FRAME_MAX} frames); shorten or remove a shot first.`);
+    owner().writeState(before => ({ ...before, ...grown }));
+    const added = grown.shots.find(shot => !current.some(row => row.id === shot.id)), { selection, view } = ports.readView();
+    if (added) ports.publishView({ selection, view: { ...view, frame: added.startFrame }, shotId: added.id });
+  }
   function duplicate(shotId) {
     const source = shotOf(shotId), copied = { kind: source.kind, caption: source.caption, cast: structuredClone(source.cast), stylizedAssetId: source.stylizedAssetId };
     if (source.kind !== 'still') {
@@ -130,7 +142,7 @@ export function register(registry, ports) {
   // aimHeight moves a cast aim off the chest to a world height (a whole body, a face).
   const aimOf = (aim, aimHeight) => (aim?.ids && aimHeight !== undefined ? { ids: aim.ids, height: aimHeight } : aim);
   const methods = {
-    'shot.create': () => storyboard() ? createStill() : owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
+    'shot.create': () => storyboard() ? createStill() : createClip(),
     'shot.createStill': args => createStill(args),
     'shot.setCaption': ({ shotId, caption }) => patchShot(shotId, shot => ({ ...shot, caption })),
     'shot.setCastOverride': ({ shotId, characterId, override }) => owner().setCastOverride(shotId, characterId, override),
@@ -188,7 +200,7 @@ export function register(registry, ports) {
   const hasShots = state => state.shots.length > 0 || 'There are no shots yet; add one with shot.create.';
   const availability = {
     'shot.createStill': () => true,
-    'shot.create': state => storyboard() || addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || `There is no free room for a new shot at the playhead (frame ${state.frame}); move it with operate_studio { frame } or shorten a shot.`,
+    'shot.create': state => storyboard() || addShotAtFrame(state.shots, state.frame, state.frameCount, null) !== state.shots || appendShotGrowingTake(state.shots, state.frameCount, null, TAKE_FRAME_MAX) !== null || `The take is at its longest (${TAKE_FRAME_MAX} frames); shorten or remove a shot first.`,
     'shot.split': state => state.shots.some(shot => state.frame > shot.startFrame && state.frame <= shot.endFrame) || `The playhead (frame ${state.frame}) is not inside a shot after its first frame; move it with operate_studio { frame }.`,
     'shot.clearCameraRail': state => state.shots.some(shot => createCameraBlock(shot.camera).cameraRail) || 'No shot has a camera rail; lay one with shot.setCameraRail.',
   };

package/src/controls.jsx

@@ -53,14 +53,6 @@ export function aimAt(position, target) {
  * `getPivot()` is optional and returns a world point to orbit; without one,
  * Alt-drag orbits a point straight ahead of the lens.
  */
-/** Coarse navigation signal for onboarding surfaces (the landing-page
- * tutorial listens through the playground bridge). Fires once per gesture
- * start, not per frame. */
-function announceNav(kind, key = null) {
-	if (typeof window === "undefined") return;
-	window.dispatchEvent(new CustomEvent("cozyclay:nav", { detail: { kind, key } }));
-}
-
 export function FlyControls({ enabled, cameraLocked = false, camRef, look, getPivot, onFlyStateChange, onCameraChange }) {
 	const { gl, invalidate } = useThree();
 	const keys = useRef(new Set());
@@ -136,7 +128,6 @@ export function FlyControls({ enabled, cameraLocked = false, camRef, look, getPi
 			if (gesture.current?.kind !== "fly") return;
 			const key = KEY_BY_CODE[e.code];
 			if (key) {
-				if (!keys.current.has(key) && key !== "shift") announceNav("walk", key);
 				keys.current.add(key);
 				e.preventDefault();
 			}
@@ -220,7 +211,6 @@ export function FlyControls({ enabled, cameraLocked = false, camRef, look, getPi
 			lockAttempts = 0;
 			if (e.pointerType !== "touch" && e.pointerType !== "pen") requestNavLock();
 			if (kind === "fly") flyStateRef.current?.(true);
-			announceNav(kind);
 			scheduleInvalidate();
 		};
 
@@ -309,7 +299,6 @@ export function FlyControls({ enabled, cameraLocked = false, camRef, look, getPi
 				return;
 			}
 			cam.position.addScaledVector(forwardFrom(look.current.yaw, look.current.pitch), -e.deltaY * DOLLY_STEP);
-			announceNav("dolly");
 			cameraChangeRef.current?.();
 		};
 

package/src/cuts.js

@@ -127,6 +127,17 @@ export function addShotAtFrame(shots, frame, frameCount, currentFraming, duratio
 	return [...list, createShot(`Shot ${list.length + 1}`, target, endFrame, keys)].sort((a, b) => a.startFrame - b.startFrame);
 }
 
+/** Add Shot when the take has no free time left: the take grows by one default
+ * shot at its end and the new shot fills that, so the button never silently does
+ * nothing. Existing shots are untouched. Null past maxFrameCount. */
+export function appendShotGrowingTake(shots, frameCount, currentFraming, maxFrameCount) {
+	const list = Array.isArray(shots) ? shots : [];
+	const startFrame = Math.max(frameNumber(frameCount, 1), ...list.map((shot) => shot.endFrame + 1));
+	const grownCount = startFrame + DEFAULT_SHOT_FRAMES;
+	if (grownCount > maxFrameCount) return null;
+	return { shots: addShotAtFrame(list, startFrame, grownCount, currentFraming), frameCount: grownCount };
+}
+
 export function resizeShot(shots, shotId, edge, rawFrame, frameCount) {
 	const shot = shotById(shots, shotId);
 	if (edge !== "start" && edge !== "end") return shots;

package/src/domains/cast.js

@@ -546,7 +546,7 @@ export function useCast(appContext) {
 		return current.length;
 	}
 
-	/** ARDY-demo style authoring: each empty-floor press in the Shot view drops
+	/** Click-to-place authoring: each empty-floor press in the Shot view drops
 	    the next waypoint where it was clicked; the frame gap comes from walking
 	    distance. The bird's-eye board selects and drags existing waypoints. */
 	function addFloorWaypoint(point) {
@@ -715,7 +715,8 @@ export function useCast(appContext) {
 	}
 	function undoScene() {
 		const receipt = appContext.bus.run('edit.undo');
-		if (receipt.status === 'noop') appContext.notify(ko("Nothing to undo", "실행 취소할 작업이 없어요"));
+		// A refusal says why: the last edit belongs to a running task (parallel tasks), which its own card undoes.
+		if (receipt.status === 'noop' || receipt.ok === false) appContext.notify(receipt.ok === false ? ko(receipt.message ?? "Undo was refused", `실행 취소 불가: ${receipt.message ?? ""}`) : ko("Nothing to undo", "실행 취소할 작업이 없어요"));
 		return receipt;
 	}
 	function redoScene() {

package/src/domains/motion.js

@@ -29,8 +29,8 @@ import {
 } from "../motion/ik.js";
 import * as THREE from "three";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
-
 import { applyTakeFrame } from "../motion3/playback.js";
+import { advancePlayback, installPlaybackApplier } from "./playback.js";
 import { isKo, ko } from "../locale.js";
 import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
@@ -625,15 +625,7 @@ export function useMotion(appContext) {
 
 
 	function advanceFrame(steps = 1) {
-		const count = Math.max(1, Math.floor(steps));
-		const previewEnd = appContext.shared.cameraPreviewEndRef.current;
-		if (previewEnd != null && appContext.shared.tlFrameRef.current + count >= previewEnd) {
-			appContext.shared.cameraPreviewEndRef.current = null;
-			appContext.shared.setTlFrame(previewEnd);
-			appContext.shared.setTlPlaying(false);
-			return;
-		}
-		appContext.shared.setTlFrame((f) => (f + count) % appContext.shared.frameCountRef.current);
+		advancePlayback(appContext.shared, steps);
 	}
 
 	function stepFrame(delta) {
@@ -677,6 +669,7 @@ export function useMotion(appContext) {
 			appContext.shared.poseMemberAtFrame(appContext.shared.rigs[entry.id], entry.sessionMotion, appContext.shared.ikStatesRef.current.get(entry.id), frame, IK_CORRECTION_BLEND_FRAMES);
 		}
 	};
+	installPlaybackApplier(appContext, motion, poseOtherCastMembers, ikEvaluate, IK_CORRECTION_BLEND_FRAMES);
 
 	function toggleIkMode() {
 		const next = !ikMode;