cozyclay 2.0.0 → 2.1.0

package/src/camera-tutorial.jsx

@@ -11,7 +11,7 @@ import { ko } from "./locale.js";
 // to them directly.
 //
 //   cozyclay:nav               fly / walk / dolly / orbit  (src/controls.jsx)
-//   cozyclay:playground-signal shot / rail                 (src/App.jsx)
+//   shotCount / railReady      shot / rail                 (authored state)
 //   previewing prop            play                        (lookThroughShot)
 //
 // Nothing here drives the studio. A step is done when the operator has done
@@ -69,16 +69,16 @@ export const CAMERA_TUTORIAL_STEPS = [
 		label: ko("Shot", "샷"),
 		// The control lives in another region than the card, so the card says
 		// which way to look before it says what to do.
-		where: ko("↓ Timeline, Shots lane", "↓ 타임라인 샷 레인"),
+		where: ko("↓ Timeline, Camera Cuts", "↓ 타임라인 Camera Cuts"),
 		how: () => ko(
-			<>In the timeline's Shots lane click <b>+ Add shot</b>. That is your cut.</>,
-			<>타임라인의 샷 레인에서 <b>+ 샷 추가</b>를 누르세요. 그게 컷입니다.</>,
+			<>In the timeline's Camera Cuts lane click <b>+ Add shot</b>. That is your cut.</>,
+			<>타임라인의 Camera Cuts 레인에서 <b>+ 샷 추가</b>를 누르세요. 그게 컷입니다.</>,
 		),
 	},
 	{
 		kind: "rail",
 		label: ko("Rail", "레일"),
-		where: ko("↓ Timeline, Shots lane", "↓ 타임라인 샷 레인"),
+		where: ko("↓ Timeline, Camera Cuts", "↓ 타임라인 Camera Cuts"),
 		how: () => ko(
 			<>Select the shot, click <b>Draw rail</b> in the camera bar, and drag a line across the top view. That line is the dolly move.</>,
 			<>샷을 선택하고 카메라 바의 <b>레일 그리기</b>를 누른 뒤, 탑뷰에 선을 그으세요. 그 선이 돌리 이동입니다.</>,
@@ -87,10 +87,10 @@ export const CAMERA_TUTORIAL_STEPS = [
 	{
 		kind: "play",
 		label: ko("Play", "재생"),
-		where: ko("→ Viewport", "→ 뷰포트"),
+		where: ko("↘ Shot Camera monitor", "↘ Shot Camera 모니터"),
 		how: () => ko(
 			<>Click <b>Look through</b> in the Shot monitor to fly the shot camera; <b>▶</b> rides the rail, <kbd>Esc</kbd> returns to the free camera.</>,
-			<>뷰포트의 <b>샷 시점</b>을 눌러 샷 카메라를 조종하세요. <b>▶</b>는 레일을 타고, <kbd>Esc</kbd>로 자유 카메라로 돌아옵니다.</>,
+			<>Shot Camera 모니터의 <b>샷 시점</b>을 눌러 샷 카메라를 조종하세요. <b>▶</b>는 레일을 타고, <kbd>Esc</kbd>로 자유 카메라로 돌아옵니다.</>,
 		),
 	},
 ];
@@ -98,8 +98,6 @@ export const CAMERA_TUTORIAL_STEPS = [
 const NAV_KINDS = new Set(["fly", "walk", "dolly", "orbit"]);
 const SIGNAL_KINDS = new Set(["shot", "rail"]);
 
-/* ------------------------------------------------------------- beacons --- */
-
 // Where each of the last three steps actually happens (#211). The card names
 // the gesture; these pin a numbered circle and a caption onto the control
 // itself, so "click + Add shot" stops being a treasure hunt across two panes.
@@ -119,10 +117,13 @@ export const TUTORIAL_BEACONS = {
 			label: () => ko("1. Select the shot", "1. 샷을 선택"),
 		},
 		{ role: "draw-rail", selector: ".tl-rail-draw", label: () => ko("2. Draw rail, then drag across the top view", "2. 레일 그리기 후 탑뷰에 선 긋기") },
-		{ role: "top-view", selector: ".vp-inset", requires: ".tl-rail-draw", label: () => ko("Drag a line here", "여기에 선을 그으세요") },
+		// The Top-View becomes an active drawing surface after the tool is armed.
+		{ role: "top-view", selector: ".vp-inset", requires: '[data-rail-draw="1"]', label: () => ko("Drag a line here", "여기에 선을 그으세요") },
 	],
 	play: [
-		{ role: "look-through", selector: ".vp-look-through", label: () => ko("Click to fly the shot camera", "클릭해 샷 카메라를 조종") },
+		// The glass shell keeps the same action in the bottom dock while the
+		// compact viewport card owns it in the classic shell.
+		{ role: "look-through", selector: ".dock-shot-look, .vp-look-through", label: () => ko("Click to fly the shot camera", "클릭해 샷 카메라를 조종") },
 	],
 };
 
@@ -217,7 +218,7 @@ export function TutorialBeacon({ kind, step, role, selector, label, requires = n
 			if (pane) resize.observe(pane);
 		}
 		const mutations = new MutationObserver(schedule);
-		mutations.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["class", "style"] });
+		mutations.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["class", "style", "data-rail-draw"] });
 		return () => {
 			if (frame) cancelAnimationFrame(frame);
 			window.removeEventListener("resize", schedule);
@@ -246,8 +247,6 @@ export function TutorialBeacon({ kind, step, role, selector, label, requires = n
 	);
 }
 
-/* -------------------------------------------------------- gesture cues --- */
-
 // Steps 1–4 have no control to point at: the gesture IS the interface. The cue
 // draws the mouse and the keys the step wants, animated the way the hand is
 // supposed to move, and sits centre-bottom of the viewport where the eye
@@ -327,11 +326,18 @@ export function GestureCue({ kind, walked, leaving = false, onLeft }) {
  * Top-View inset, and never takes the pointer except on its own close button
  * — every step is completed by working the studio underneath it.
  */
-export function CameraTutorial({ previewing = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
+export function CameraTutorial({ previsMode, previewing = false, shotCount = 0, railReady = false, analytics, onStepChange, onClose, onComplete, handoff = null, shotId = null, onOpenExport, onContinue }) {
 	const [done, setDone] = useState(() => new Set());
 	const [walked, setWalked] = useState(() => new Set());
 	const [cue, setCue] = useState(null);
 	const completionReported = useRef(false);
+	const effectiveDone = useMemo(() => {
+		const next = new Set(done);
+		if (shotCount > 0) next.add("shot");
+		if (railReady) next.add("rail");
+		if (previewing && next.has("rail")) next.add("play");
+		return next;
+	}, [done, previewing, railReady, shotCount]);
 
 	useEffect(() => {
 		const complete = (kind) => setDone((current) => (current.has(kind) ? current : new Set(current).add(kind)));
@@ -362,6 +368,16 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 		};
 	}, []);
 
+	// Studio-native completion comes from the authored state. The old playground
+	// signal was never emitted by the Studio shell, so a real Shot or rail could
+	// leave the tutorial stuck on its previous step.
+	useEffect(() => {
+		if (shotCount > 0) setDone((current) => (current.has("shot") ? current : new Set(current).add("shot")));
+	}, [shotCount]);
+	useEffect(() => {
+		if (railReady) setDone((current) => (current.has("rail") ? current : new Set(current).add("rail")));
+	}, [railReady]);
+
 	// The player is the last step, and only once there is a rail to ride:
 	// look-through before the dolly exists shows a still frame, which teaches
 	// nothing about the move. Analytics v1 observes this existing look-through
@@ -369,12 +385,12 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 	useEffect(() => {
 		if (!previewing) return;
 		setDone((current) => (!current.has("rail") || current.has("play") ? current : new Set(current).add("play")));
-	}, [previewing]);
+	}, [previewing, railReady]);
 
-	const current = useMemo(() => CAMERA_TUTORIAL_STEPS.find((step) => !done.has(step.kind)) ?? null, [done]);
+	const current = useMemo(() => CAMERA_TUTORIAL_STEPS.find((step) => !effectiveDone.has(step.kind)) ?? null, [effectiveDone]);
 	const complete = current === null;
 	const currentKind = current?.kind ?? null;
-	const showHandoff = !!shotId && (handoff?.canShow(done) ?? false);
+	const showHandoff = !!shotId && (handoff?.canShow(effectiveDone) ?? false);
 	useEffect(() => {
 		if (!complete || completionReported.current) return;
 		completionReported.current = true;
@@ -384,8 +400,8 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 	// Observe committed progression, outside state updaters (which StrictMode
 	// may replay). The attempt belongs to App and survives effect cleanup/resume.
 	useEffect(() => {
-		analytics?.observe(done, currentKind);
-	}, [analytics, done, currentKind]);
+		analytics?.observe(effectiveDone, currentKind);
+	}, [analytics, effectiveDone, currentKind]);
 
 	// The step the operator is on is the studio's business too: App puts it on
 	// the .app root as data-tutorial-step, and styles.css spotlights whichever
@@ -409,6 +425,9 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 		});
 	}, [currentKind]);
 
+	// Storyboard projects never show the camera tutorial (its steps are shot/rail/play).
+	if (previsMode === "storyboard") return null;
+
 	return (
 	<>
 		<aside
@@ -425,10 +444,10 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 						key={step.kind}
 						data-testid="camera-tutorial-step"
 						data-kind={step.kind}
-						data-done={done.has(step.kind) ? 1 : 0}
+						data-done={effectiveDone.has(step.kind) ? 1 : 0}
 						data-current={step === current ? 1 : 0}
 					>
-						<i aria-hidden="true">{done.has(step.kind) ? "✓" : index + 1}</i>
+						<i aria-hidden="true">{effectiveDone.has(step.kind) ? "✓" : index + 1}</i>
 						{step.label}
 					</li>
 				))}
@@ -490,8 +509,8 @@ export function CameraTutorial({ previewing = false, analytics, onStepChange, on
 				role={beacon.role}
 				selector={beacon.selector}
 				label={beacon.label}
-				requires={beacon.requires ?? null}
-				absent={beacon.absent ?? null}
+				requires={beacon.requires}
+				absent={beacon.absent}
 			/>
 		))}
 	</>

package/src/character-kind.js

@@ -0,0 +1,79 @@
+// What a cast member can do depends on its kind. A rigged character has a
+// skeleton every motion, IK and physics tool writes to; a capsule figure
+// (PROXY_FIGURE_MODEL) is a placement-only stand-in with no bones at all, so
+// those tools refuse it by name instead of failing on a missing rig.
+import { isProxyFigure } from "./scenes.js";
+import { isKo } from "./locale.js";
+import { StudioProtocolError } from "./studio-agent-protocol.js";
+
+export const CHARACTER_CAPABILITIES = Object.freeze(["rig", "ik", "pose", "motion", "mocap", "physics", "trails", "lineEdit"]);
+const PROXY_BODY_RADIUS = 0.22;
+const PROXY_BODY_HEIGHT = 1.45;
+const PROXY_HEAD_RADIUS = 0.12;
+
+/** Return a capsule figure's rendered world-space bounds without a rig. */
+export function proxyFigureBounds(character, placement = character) {
+	const posture = character?.posture === "sit" || character?.posture === "lie" ? character.posture : "stand";
+	const bodyHeight = posture === "sit" ? PROXY_BODY_HEIGHT * 0.6 : PROXY_BODY_HEIGHT;
+	const stature = Number.isFinite(placement?.scale) ? placement.scale : Number.isFinite(character?.scale) ? character.scale : 1;
+	const x = Number.isFinite(placement?.x) ? placement.x : character?.x ?? 0;
+	const y = Number.isFinite(placement?.y) ? placement.y : character?.y ?? 0;
+	const z = Number.isFinite(placement?.z) ? placement.z : character?.z ?? 0;
+	const yaw = ((Number.isFinite(placement?.rot) ? placement.rot : character?.rot ?? 0) + (posture === "lie" ? 180 : 0)) * Math.PI / 180;
+	const [minCorner, maxCorner] = posture === "lie"
+		? [[-PROXY_BODY_RADIUS, PROXY_BODY_RADIUS - PROXY_HEAD_RADIUS, -(bodyHeight + 0.25)],
+			[PROXY_BODY_RADIUS, PROXY_BODY_RADIUS + PROXY_HEAD_RADIUS, 0]]
+		: [[-PROXY_BODY_RADIUS, 0, -PROXY_BODY_RADIUS], [PROXY_BODY_RADIUS, bodyHeight + 0.25, PROXY_BODY_RADIUS]];
+	const min = { x: Infinity, y: Infinity, z: Infinity }, max = { x: -Infinity, y: -Infinity, z: -Infinity };
+	for (const lx of [minCorner[0], maxCorner[0]]) for (const ly of [minCorner[1], maxCorner[1]]) for (const lz of [minCorner[2], maxCorner[2]]) {
+		const sx = lx * stature, sy = ly * stature, sz = lz * stature;
+		const wx = x + sx * Math.cos(yaw) + sz * Math.sin(yaw);
+		const wz = z - sx * Math.sin(yaw) + sz * Math.cos(yaw);
+		min.x = Math.min(min.x, wx); max.x = Math.max(max.x, wx);
+		min.y = Math.min(min.y, y + sy); max.y = Math.max(max.y, y + sy);
+		min.z = Math.min(min.z, wz); max.z = Math.max(max.z, wz);
+	}
+	return { min, max };
+}
+
+/** `{ rig, ik, pose, motion, mocap, physics, trails, lineEdit }` - all false
+ * for a capsule figure, all true for a rigged character. */
+export function characterCapabilities(character) {
+	const rigged = !isProxyFigure(character);
+	return Object.freeze(Object.fromEntries(CHARACTER_CAPABILITIES.map((name) => [name, rigged])));
+}
+
+// The noun each refusal names. A feature id not listed here is used verbatim.
+const FEATURE_LABELS = {
+	rig: ["the rig", "리그"],
+	ik: ["IK", "IK"],
+	pose: ["Pose mode", "포즈 모드"],
+	motion: ["Motion generation", "모션 생성"],
+	mocap: ["Motion capture", "모션 캡처"],
+	photoPose: ["Photo pose", "사진 포즈"],
+	physics: ["Physics", "물리 보정"],
+	collision: ["Collision cleanup", "충돌 정리"],
+	trails: ["Motion trails", "궤적선"],
+	lineEdit: ["Line edit", "라인 편집"],
+	take: ["Loading a take", "테이크 불러오기"],
+};
+
+// A character's kind (rig or capsule figure) is fixed at creation; character.update refuses a kind change.
+export const KIND_FIXED_REFUSAL = Object.freeze({
+	en: "A character's kind is chosen when it is created; add a new character instead.",
+	ko: "캐릭터 종류는 만들 때 정합니다. 새 캐릭터를 추가하세요.",
+});
+
+export function kindRefusal(feature, ko = false) {
+	const label = FEATURE_LABELS[feature]?.[ko ? 1 : 0] ?? feature;
+	return ko
+		? `캡슐 인물은 리그가 없어요 - ${label}는 리그 캐릭터에서만 됩니다.`
+		: `Capsule figures have no rig - ${label} works on rigged characters only.`;
+}
+
+/** Throw TARGET_NOT_READY when `character` is a capsule figure. The protocol
+ * message is English (the agent reads it); `uiMessage` is the locale's. */
+export function refuseRigOnly(character, feature) {
+	if (!isProxyFigure(character)) return;
+	throw Object.assign(new StudioProtocolError("TARGET_NOT_READY", kindRefusal(feature, false)), { uiMessage: kindRefusal(feature, isKo) });
+}

package/src/command-bus.js

@@ -45,9 +45,10 @@ export const isBusRunActive = () => activeRunDepth > 0;
 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;
   function exposure(entry, args, request) {
     if (request.origin === 'ui') return;
-    if (entry.exposure === 'ui-only') fail('CAPABILITY_MISSING', 'This command is available only from the Studio UI.');
+    if (entry.exposure === 'ui-only') fail('CAPABILITY_MISSING', entry.uiOnlyHint ?? 'This command is available only from the Studio UI.');
     if (entry.id === 'load_scenes') {
       const ids = scenes => [...new Set(scenes.map(scene => scene.id))].sort();
       if (same(ids(args.document.scenes), ids(registry.state().scenes))) return;
@@ -61,6 +62,9 @@ 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 = {
+    'agent.turn.begin': object({ turnId: identifier }),
+    'agent.turn.finish': object({ turnId: identifier }),
+    'agent.turn.cancel': object({ turnId: identifier }),
     'run.begin': object({ id: identifier, args: argsSchema }),
     'run.update': object({ txId: identifier, args: argsSchema }),
     'run.commit': object({ txId: identifier }),
@@ -81,7 +85,29 @@ 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 === 'edit.undo' || id === 'edit.redo') {
+    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.');
+        agentTurn = { txId: args.turnId, before, affectedIds: new Set(), toasts: [], session: null };
+        return transactionReceipt(id, agentTurn, request, before);
+      }
+      if (agentTurn?.txId !== args.turnId) fail('STALE_TARGET', 'The agent turn is no longer open.');
+      const turn = agentTurn;
+      // A rolled-back turn restores every owner it touched and leaves no entry.
+      if (id === 'agent.turn.cancel') { agentTurn = null; turn.session?.cancel(); return transactionReceipt(id, turn, request, before); }
+      try { turn.historyEntryId = turn.session?.commit().historyEntryId; }
+      catch (error) { turn.session?.cancel(); throw error; }
+      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.');
+    if (traversal) {
       const redo = id === 'edit.redo', historyEntryId = ports.history?.(redo);
       const previous = args.receiptId ? ports.receipt(args.receiptId) : historyReceipts.get(historyEntryId)
         ?? (historyEntryId ? { receiptId: historyEntryId, host: before.host, affectedIds: [before.host.sceneId],
@@ -180,23 +206,51 @@ export function createCommandBus({ registry, ports }) {
       mutated: changed, preserved: { authoredState: changed ? 'changed' : 'unchanged' }, recovery: { action: 'inspect', retryAllowed: false },
       message: [...String(error.message || error)].slice(0, 500).join('') });
   }
-  function receipt(entry, request, before, result, historyEntryId, toasts = []) {
+  /** Findings first, toasts after; past the schema's twelve, say how many were left out. */
+  const receiptWarnings = (findings = [], toasts = [], omitted = 0, limit = 12) => {
+    const all = [...(omitted ? [{ code: 'READBACK_TRUNCATED', count: omitted, message: `Readback lists 8 of ${8 + omitted} affected ids; inspect_studio scope entities with ids for the rest.` }] : []), ...findings, ...toastWarnings(toasts)];
+    return all.length <= limit ? all : [...all.slice(0, limit - 1), { code: 'WARNINGS_TRUNCATED', count: all.length - limit + 1, message: `${all.length - limit + 1} more warnings omitted.` }];
+  };
+  function receipt(entry, request, before, result, historyEntryId, toasts = [], turn = null) {
     const after = ports.read(), changed = after.revision !== before.revision;
-    if (entry.kind === 'mutation' && changed && !historyEntryId) fail('UNCERTAIN_APPLY', `${entry.id} changed the scene without one undoable entry.`);
-    const completed = entry.kind === 'job' || entry.kind === 'document' || (entry.kind === 'mutation' && changed && after.revision > before.revision + 1);
+    // A turn's transaction is the undo entry only for a command that changed the scene: a read-only
+    // job inside an agent turn (sculpt.compare) has nothing to undo.
+    const retainedHistoryEntryId = historyEntryId ?? (changed ? turn?.txId : null) ?? null;
+    if (entry.kind === 'mutation' && changed && !historyEntryId && !turn) fail('UNCERTAIN_APPLY', `${entry.id} changed the scene without one undoable entry.`);
+    const completed = entry.kind === 'job' || entry.kind === 'document' || (entry.kind === 'mutation' && changed && (turn || after.revision > before.revision + 1));
     const ids = completed || changed ? result.affectedIds : entry.kind === 'transient' ? [before.host.sceneId] : [];
-    return validateReceipt({ ok: true, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
+    if (turn && changed) for (const id of ids) turn.affectedIds.add(id);
+    const build = level => validateReceipt({ ok: true, commandId: request.commandId, receiptId: crypto.randomUUID(), host: before.host,
       action: entry.id, summary: result.summary, status: completed ? 'completed' : entry.kind === 'transient' ? 'transient' : changed ? 'applied' : 'noop',
       authored: changed, ...(completed ? { kind: entry.kind, ...(result.output === undefined ? {} : { output: result.output }), ...(same(before.host, after.host) ? {} : { nextHost: after.host }) } : entry.kind === 'transient' ? { view: { before: before.viewRevision ?? 0, after: after.viewRevision ?? 0 } } : { mutated: changed }),
       revision: { before: before.revision, after: after.revision }, affectedIds: ids,
-      delta: ids.slice(0, 8).map(id => ({ id, after: ports.readback?.(id, after) ?? { removed: true } })),
-      checks: { coverage: `studio-action:${entry.id}` }, warnings: toastWarnings(toasts),
-      undo: historyEntryId ? { historyEntryId, entries: 1, canUndoDirect: true } : null, ...(ids.length > 8 ? { detailCursor: request.commandId } : {}) });
+      delta: ids.slice(0, 8).map(id => ({ id, after: ports.readback?.(id, after, level > 0) ?? { removed: true } })),
+      // The command's own measurements (an arrangement's overlap evidence) ride beside the coverage tag.
+      checks: { coverage: `studio-action:${entry.id}`, ...result.checks }, warnings: receiptWarnings(result.warnings, toasts, Math.max(0, ids.length - 8), level > 1 ? 4 : 12),
+      undo: retainedHistoryEntryId ? { historyEntryId: retainedHistoryEntryId, entries: 1, canUndoDirect: !turn } : null, ...(ids.length > 8 ? { detailCursor: request.commandId } : {}) });
+    // Full readback and warnings are richer than the 8 KiB receipt always allows; shed the extras
+    // (box and children, then all but the first warnings) rather than fail an edit that was applied.
+    for (let level = 0; ; level++) {
+      try { return build(level); }
+      catch (error) { if (level >= 2 || error?.code !== 'INVALID_RECEIPT' || !/8 KiB/.test(error.message)) throw error; }
+    }
   }
   function executeRun(id, args = {}, options = {}) {
     const request = { origin: 'ui', commandId: crypto.randomUUID(), ...options };
     if (request.origin === 'ui' && (id === 'edit.undo' || id === 'edit.redo')) ports.finishHistoryGesture?.();
     const before = ports.read(), journal = ports.journal();
+    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 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
+      // cancel the parent on a tool refusal) at an individual command boundary.
+      turn.session ??= ports.beginAction(domain, targetId);
+      const result = turn.session.run(() => ports.beginAction(domain, targetId).run(invoke));
+      return { result, historyEntryId: null };
+    };
     let begun = false, releaseToasts, timer, foregroundTimer, job, applied = false, committedHistoryId;
     const controller = new AbortController();
     const clearTimer = () => {
@@ -228,6 +282,7 @@ export function createCommandBus({ registry, ports }) {
     };
     try {
       if (request.origin !== 'ui' && !same(validateStudioIdentity(request.host), before.host)) fail('STALE_SCENE', 'The live document changed.');
+      if (request.turnId && !turn && id !== 'agent.turn.begin') fail('STALE_TARGET', 'The agent turn is no longer open.');
       const signature = JSON.stringify({ id, args, ...request });
       if (!journal.begin(request.commandId, signature)) return journal.get(request.commandId) ?? pending.get(request.commandId) ?? refusal(request, before, new StudioProtocolError('UNCERTAIN_APPLY', 'Command is still executing.'));
       begun = true;
@@ -237,11 +292,12 @@ export function createCommandBus({ registry, ports }) {
         // Job controls observe/cancel an admitted identity; completion itself
         // can advance the revision while their wire request is in transit.
         // Document identity and the job's own publication fence still apply.
-        if (!['job.await', 'job.cancel'].includes(id) && request.expectedRevision !== before.revision) fail('STALE_SCENE', 'Authored state changed; obtain fresh intent.');
-        if (before.busy && !transactions.has(validated.txId) && !id.startsWith('job.')) fail('TARGET_BUSY', 'Finish the current editor gesture first.');
+        if (!['job.await', 'job.cancel', 'agent.turn.finish', 'agent.turn.cancel'].includes(id) && request.expectedRevision !== before.revision) fail('STALE_SCENE', 'Authored state changed; obtain fresh intent.');
+        if (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);
       releaseToasts = ports.captureToasts?.(toast => toasts.push(typeof toast === 'string' ? { message: toast } : toast));
       const domain = entry.domain ?? entry.undoDomain;
@@ -258,12 +314,15 @@ export function createCommandBus({ registry, ports }) {
         check() {
           controller.signal.throwIfAborted();
           const current = ports.read();
-          if (!same(current.host, before.host) || (domain && current.domainRevisions?.[domain] !== domainRevision) || (targetId && ports.readTarget?.(targetId) !== token)) fail('STALE_TARGET', 'The target or its authored domain changed while the job was running.');
+          // 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 (targetId && ports.readTarget?.(targetId) !== token) fail('STALE_TARGET', `${targetId} changed while the job was running.`);
         },
         commit(apply) {
           context.check();
           if (!domain) fail('INVALID_ARGUMENT', 'A committing job must declare its domain.');
-          const recorded = ports.recordAction(domain, apply, targetId ?? null);
+          const recorded = recordAction(domain, apply, targetId ?? null);
           if (recorded?.then) fail('INVALID_ARGUMENT', 'Job publication must be synchronous; prepare before commit.');
           committedHistoryId = recorded.historyEntryId; applied ||= Boolean(committedHistoryId);
           if (job) rebase();
@@ -273,7 +332,7 @@ export function createCommandBus({ registry, ports }) {
           if (job) context.check(); else controller.signal.throwIfAborted();
           const nested = registry.prepare(nestedId, nestedArgs); exposure(nested.entry, nested.args, request);
           const invoke = () => registry.invoke(nested.entry, nested.args, context);
-          const value = nested.entry.kind === 'mutation' ? ports.recordAction(nested.entry.undoDomain, invoke, nested.args.characterId ?? null, true) : { result: invoke() };
+          const value = nested.entry.kind === 'mutation' ? recordAction(nested.entry.undoDomain, invoke, nested.args.characterId ?? null, true) : { result: invoke() };
           // Only the synchronous owned step may advance the fence. Never absorb
           // an external edit while an asynchronous nested step is suspended;
           // its later publication must itself use context.run/commit.
@@ -297,13 +356,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' ? ports.recordAction(entry.undoDomain, invoke, validated.characterId ?? null) : { result: invoke(), historyEntryId: null };
+      const 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();
         if (refused) throw refused;
-        return remember(receipt(entry, request, before, { ...output, affectedIds: [...new Set([...output.affectedIds, ...nestedIds])] }, historyEntryId ?? committedHistoryId, toasts));
+        return 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;
@@ -345,5 +404,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() { 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; 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/commands/cast.js

@@ -5,7 +5,9 @@ import { studioActionDeclaration } from "../studio-actions.js";
 import { characterOf, fail, changedIds } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/character.js';
-import { createCharacterEntry } from '../scenes.js';
+import { createCharacterEntry, CHARACTER_KIND_IDS, POSTURES, PROXY_FIGURE_MODEL, isProxyFigure } from '../scenes.js';
+import { KIND_FIXED_REFUSAL } from '../character-kind.js';
+import { track } from '../analytics.js';
 import { DEFAULT_POSE } from '../poses.js';
 import { createStableItemId, updateStableItem, removeStableItem } from '../stable-items.js';
 import { movePromptClipFrames } from '../ardy/prompt-clips.js';
@@ -14,13 +16,18 @@ import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js'
 const id = StudioSchemas.TargetGuard.properties.targetId;
 const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
 const record = { type: 'object', properties: {}, additionalProperties: true };
+// A capsule figure is cast by model id; its posture is the one body choice it
+// has. A patched posture outside POSTURES normalizes to "stand" (createCharacterEntry).
+const newCharacter = { ...record, properties: { model: { type: 'string', enum: [...CHARACTER_KIND_IDS] }, posture: { type: 'string', enum: [...POSTURES] } }, required: [] };
+const characterPatch = { ...record, properties: { posture: { type: 'string', description: `One of ${POSTURES.join(', ')}; anything else stands.` } }, required: [] };
 const mutation = (id, label, schema, exposure = 'open') => ({ id, label, description: label, kind: 'mutation', undoDomain: 'cast', input: schema, exposure });
 const blocks = elementSetSchema('character').properties.set.properties.layer.properties.promptClips;
 const semantic = [
 	mutation('character.set', 'Set character fields', elementSetSchema('character')),
-	mutation('character.add', 'Add character', input({ character: record })),
+	mutation('character.add', 'Add character', input({ character: newCharacter })),
 	mutation('character.remove', 'Remove character', input({ characterId: id })),
-	mutation('character.update', 'Update character', input({ characterId: id, patch: record })),
+	mutation('character.update', 'Update character', input({ characterId: id, patch: characterPatch })),
+	studioActionDeclaration('character.move'),
 	mutation('character.setPose', 'Set character pose', input({ characterId: id, pose: { oneOf: [id, record, { type: 'null' }] }, clearMotion: { type: 'boolean' } }, ['characterId', 'pose'])),
 	mutation('character.setPromptBlocks', 'Set prompt blocks', input({ characterId: id, blocks })),
 	mutation('characters.arrange', 'Arrange characters', STUDIO_TOOL_SCHEMAS.arrange_characters),
@@ -41,7 +48,14 @@ export function register(registry, ports) {
 	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;
-	const patch = (characterId, update) => { character(characterId); owner().write(rows => rows.map(row => row.id === characterId ? { ...row, ...update } : row)); };
+	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.
+	const groupParent = value => {
+		if (value === null || value === undefined) return;
+		const object = ports.state().objects.find(row => row.id === value) ?? fail('STALE_TARGET', `Object ${value} is not in this scene.`);
+		if (object.attach) fail('INVALID_ARGUMENT', 'A character cannot be grouped under an object that a character carries.');
+	};
 	function promptEdit(command, args) {
 		const before = character(args.characterId), clips = before.layer.promptClips;
 		let next;
@@ -72,7 +86,13 @@ export function register(registry, ports) {
 			owner().write(rows => [...rows, row]);
 		},
 		'character.remove': ({ characterId }) => { character(characterId); if (owner().read().length <= 1) fail('INVALID_ARGUMENT', 'Cannot remove the final character.'); owner().write(rows => rows.filter(row => row.id !== characterId)); },
-		'character.update': ({ characterId, patch: value }) => patch(characterId, value),
+		'character.update': ({ characterId, patch: value }) => {
+			// Rig <-> capsule figure is a different kind of cast member; rig-to-rig model swaps stay.
+			if (Object.hasOwn(value, 'model') && (value.model === PROXY_FIGURE_MODEL) !== isProxyFigure(character(characterId))) fail('INVALID_ARGUMENT', KIND_FIXED_REFUSAL.en);
+			if (Object.hasOwn(value, 'parent')) groupParent(value.parent);
+			patch(characterId, value);
+		},
+		'character.move': ({ characterId, ...value }) => patch(characterId, value),
 		'character.setPose': ({ characterId, pose: value, clearMotion }) => { character(characterId); owner().applyPose(characterId, pose(value), clearMotion); },
 		'character.setPromptBlocks': ({ characterId, blocks }) => {
 			const entry = character(characterId); patch(characterId, { layer: { ...entry.layer, promptClips: blocks } });
@@ -96,6 +116,7 @@ export function register(registry, ports) {
 		registry.register({ ...entry, available: mounted, run(args) {
 			// A pose id selects a complete library entry, not a deep bone patch.
 			const ops = args.ops ?? [args];
+			for (const op of ops) if (Object.hasOwn(op.set, 'parent')) groupParent(op.set.parent);
 			const poses = ops.filter(op => Object.hasOwn(op.set, 'pose')).map(op => ({ id: op.id, value: pose(op.set.pose) }));
 			const fields = ops.map(({ id, set: { pose: _pose, ...set } }) => ({ id, set }));
 			const result = entry.run(args.ops ? { ops: fields } : fields[0]);
@@ -103,10 +124,13 @@ export function register(registry, ports) {
 			return result;
 		} });
 	} }, ports, semantic[0]);
-	for (const declaration of semantic.slice(1)) registry.register({ ...declaration, available: mounted, run(args) {
-		if (declaration.id === 'characters.arrange') { const plan = owner().arrange(args); return { affectedIds: plan.affectedIds, summary: 'Arranged characters.' }; }
+	for (const declaration of semantic.slice(1)) registry.register({ ...declaration, available: mounted, run(args, context) {
+		if (declaration.id === 'characters.arrange') { const plan = owner().arrange(args); return { affectedIds: plan.affectedIds, summary: 'Arranged characters.', checks: plan.checks, warnings: plan.warnings }; }
 		const before = owner().read();
 		if (declaration.id.endsWith('PromptBlock')) promptEdit(declaration.id, args); else methods[declaration.id](args);
+		// The Assets tile and the MCP live path report themselves; this is the agent and
+		// any other non-UI bus caller adding a capsule figure.
+		if (declaration.id === 'character.add' && context?.origin && context.origin !== 'ui' && isProxyFigure(owner().read().find(row => !before.some(prior => prior.id === row.id)))) track('cast:proxy_added', { surface: 'agent' });
 		const changed = changedIds(before, owner().read());
 		return { affectedIds: changed.length ? changed : [args.characterId ?? ports.state().activeSceneId], summary: declaration.label };
 	} });

package/src/commands/elements/object.js

@@ -14,7 +14,7 @@ const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('object.')).m
   return { ...element, ...(components[field] ? { documentPath: components[field] } : {}),
     ...(field === 'remove' ? { readback: item => ({ flag: item === undefined }) } : {}) };
 });
-export function normalizeObjectSet(record) {
+function normalizeObjectSet(record) {
   const item = normalizeSceneObject(record);
   // The owning collection consumes this lifecycle intent before persistence.
   return record.remove === true ? { ...item, remove: true } : item;

package/src/commands/elements/shot.js

@@ -2,7 +2,7 @@ import { createShotAuthoringDocument } from '../../shot-authoring.js';
 import { STUDIO_ELEMENTS } from '../../studio-elements.js';
 import { registerElementKind } from '../elements.js';
 
-export function normalizeShot(record) {
+function normalizeShot(record) {
   return createShotAuthoringDocument({ shots: [record], frameCount: Math.max(24, record.endFrame + 1) }).shots[0];
 }
 registerElementKind('shot', { collection: true, documentKey: 'shots',

package/src/commands/elements.js

@@ -58,7 +58,7 @@ export function readElement(document, path) {
     ? Object.fromEntries(Object.entries(element.documentPath).map(([component, stored]) => [component, atPath(document, stored)]))
     : atPath(document, setPath(element));
 }
-export function mergeElementSet(document = {}, patch) {
+function mergeElementSet(document = {}, patch) {
   document = document ?? {};
   const next = { ...document };
   for (const [key, value] of Object.entries(patch)) next[key] = value && typeof value === 'object' && !Array.isArray(value)

package/src/commands/export.js

@@ -10,11 +10,11 @@ export function register(registry, ports) {
 	registry.register({ ...studioActionDeclaration("export.shotVideo"),
 		available: state => state.exporting ? "An export is already running; wait for it to finish."
 			: state.canExportVideo || "There is nothing to record yet: add a shot (shot.create), camera keys or a motion take first.",
-		run: async ({ shotId }, context) => {
+		run: async ({ shotId, scope }, context) => {
 			const shot = shotId ? shotOf(ports, shotId) : null;
-			const result = await ports.exportShotVideo({ shotId: shotId ?? null }, context);
+			const result = await ports.exportShotVideo({ shotId: shotId ?? null, ...(scope ? { scope } : {}) }, context);
 			if (!result?.fileName) fail("TARGET_NOT_READY", "The video export did not finish; the editor's export panel shows why and offers Retry.");
 			return { affectedIds: shot ? [shot.id] : [], output: { fileName: result.fileName, frameCount: result.frameCount },
-				summary: `Recorded ${shot ? shotLabel(shot) : "the shot"} to ${result.fileName} (${result.frameCount} frames); the browser was asked to download it.` };
+				summary: `Recorded ${scope === "timeline" ? "the whole timeline" : shot ? shotLabel(shot) : "the shot"} to ${result.fileName} (${result.frameCount} frames); the browser was asked to download it.` };
 		} });
 }

package/src/commands/motion.js

@@ -70,7 +70,7 @@ const queued = ['motion.commitLineEdit', 'motion.regenerateTrail'].map(id => ({
 const legacyIk = ['character.setIkKey', 'character.removeIkKey', 'character.clearIkKeys'].map(studioActionDeclaration);
 const ik = legacyIk.map((entry, index) => ({ ...entry, id: ['ik.setKey', 'ik.removeKey', 'ik.clearKeys'][index] }));
 
-const clear = { id: 'motion.clear', label: 'Clear motion', description: 'Clear the active take, its corrections and take-owned cast fields.',
+const clear = { id: 'motion.clear', label: 'Clear motion', description: 'Clear the active take, its corrections, prompt blocks and take-owned cast fields.',
 	kind: 'mutation', undoDomain: 'motion', input: { type: 'object', properties: { characterId: { type: 'string' } }, required: ['characterId'], additionalProperties: false } };
 const videoDraft = { id: 'motion.setVideoDraft', label: 'Set video motion draft', description: 'Set the uncommitted AI-video form without changing the project or its history.', kind: 'transient',
 	input: input({ instruction: { oneOf: [{ const: '' }, { type: 'string', maxLength: 3700 }] }, promptOverride: { oneOf: [{ const: '' }, { type: 'string', maxLength: 3700 }] }, duration: { oneOf: I2V_MOTION_DURATIONS.map(value => ({ const: value })) } }, []) };
@@ -194,7 +194,7 @@ export function register(registry, ports) {
 				if (ports.state().activeCharacterId !== characterId) fail('TARGET_NOT_READY', 'Select this character before clearing its take.');
 				ports.clearMotionNative();
 			}
-			return { affectedIds: [characterId], summary: 'Cleared motion.' };
+			return { affectedIds: [characterId], summary: 'Cleared motion and prompt blocks.' };
 		} });
 	registry.register({ ...studioActionDeclaration("motion.generateAllBlocks"), target: () => ports.state().activeCharacterId,
 		available: state => state.generating ? "A motion generation is already running."