cozyclay 2.0.2 → 2.1.0

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."

package/src/commands/objects.js

@@ -3,7 +3,11 @@ import { studioActionDeclaration } from "../studio-actions.js";
 import { characterOf, fail } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
 import './elements/object.js';
-import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, normalizeSceneObject } from '../scene-objects.js';
+import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, normalizeSceneObject, groupUnderNewEmpty, objectPatchFields, createSculptObject, SCULPT_KIND } from '../scene-objects.js';
+import { expandSculptParts, normalizeSculptRecipe, patchSculptRecipe } from '../sculpt-recipe.js';
+import { rankingRow, scoreSculptAgainstReference } from '../sculpt-compare.js';
+import { browserSculptImages, shrinkRgba } from './sculpt-images.js';
+import { clampWarning } from '../receipt-findings.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
@@ -14,15 +18,24 @@ const placement = input({ x: number, y: number, z: number, rot: number }, []);
 const setInput = elementSetSchema('object');
 const scale = setInput.properties.set.properties.scale;
 setInput.properties.set.properties.scale = { oneOf: [number, scale] };
+const PATCH_HINTS = { scale: 'use scaleX, scaleY, scaleZ', rotY: 'use rot for yaw', yaw: 'use rot for yaw', rotation: 'use rot, rotX, rotZ', position: 'use x, y, z', parent: 'use object.group or object.set parent', parentId: 'use object.group or object.set parent' };
 const mutation = (id, label, input) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'objects', input });
 const semantic = [
 	mutation('object.set', 'Set object fields', setInput),
-	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id }, ['kind'])),
+	mutation('object.add', 'Add object', input({ kind: { type: 'string' }, placement, name: { type: 'string' }, parent: id, first: { type: 'boolean' } }, ['kind'])),
+	// A clay prop from a recipe of soft parts (docs/sculpt-from-image.md). With `id` it re-sculpts that
+	// sculpt in place (one undo); without, it creates one. The recipe is checked by sculpt-recipe.js.
+	{ ...mutation('object.sculpt', 'Sculpt a clay prop from a recipe', input({ recipe: { type: 'object', properties: {}, additionalProperties: true }, edits: { type: 'array', minItems: 1, maxItems: 48, items: { type: 'object', properties: {}, additionalProperties: true } }, id, name: { type: 'string', maxLength: 240 }, placement, parent: id }, [])),
+		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape: blob|box|cylinder|torus|frame, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, roundness, taper, border }] }. Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
 	mutation('object.remove', 'Remove objects', input({ ids })),
 	mutation('object.rename', 'Rename object', input({ id, name: { type: 'string', maxLength: 240 } })),
 	mutation('object.group', 'Group objects', input({ parent: id, children: ids })),
 	mutation('object.ungroup', 'Ungroup objects', input({ children: ids })),
-	mutation('object.update', 'Update object', input({ id, patch: { type: 'object', properties: {}, additionalProperties: true } }, [])),
+	// The Outliner's "Group under new Empty": the Empty and the reparent are one write, so one undo.
+	{ ...mutation('object.groupUnderEmpty', 'Group object under a new Empty', input({ id })), exposure: 'ui-only' },
+	{ ...mutation('object.update', 'Update object', input({ id, patch: { type: 'object', properties: {}, additionalProperties: true } }, [])), agentHidden: true },
+	// agentHidden: object.update silently ignores unknown keys, so the agent's action index and inspect_studio leave it out
+	// and the prompt points at object.set / arrange_objects; MCP, the CLI and the UI keep it.
 	mutation('objects.arrange', 'Arrange objects', STUDIO_TOOL_SCHEMAS.arrange_objects),
 ];
 const batch = { id: 'objects.batch', label: 'Batch objects', description: 'Apply legacy object operations in one retained entry.', kind: 'job', domain: 'objects',
@@ -37,8 +50,18 @@ const assetImport = { ...studioActionDeclaration('asset.import'), kind: 'job', d
 		input({ assetId: id, placement, placeAs: assetProperties.placeAs }, ['assetId', 'placeAs']),
 		input({ fileToken: id, placeAs: { type: 'string', enum: ['mesh', 'cutout'] } }, ['fileToken', 'placeAs']),
 	] } };
+// Read-only: a job that never commits, so its receipt is `completed` with the score as output,
+// authored false and no undo. The scoring is MCP compare_sculpt's (sculpt-compare.js).
+const openObject = { type: 'object', properties: {}, additionalProperties: true };
+const sculptCompare = { id: 'sculpt.compare', label: 'Compare a sculpt with its reference', kind: 'job', timeoutMs: 60000,
+	description: 'Score a sculpt\'s silhouette against a reference image without changing anything: IoU, width-to-height delta, missing area by height band (top, middle, bottom), parts that stick out, and a reference | overlay sheet (grey both, red missing, blue extra) as sheetDataUrl. reference is { assetId } of a project image or { dataUrl }. yaw is the reference camera azimuth in degrees (0 in front, positive toward the subject\'s own left); omitted tries -45..45 and keeps the best. candidates (up to 12 { label, edits }) are scored from the same view and ranked against the current sculpt; none is applied. Apply the winner with object.sculpt { id, edits }.',
+	input: input({ id, reference: { oneOf: [input({ assetId: id }), input({ dataUrl: { type: 'string', pattern: '^data:image/(png|jpeg|webp|gif);base64,', maxLength: 6000000 } })] },
+		yaw: { type: 'number', minimum: -180, maximum: 180 }, elevation: { type: 'number', minimum: -60, maximum: 60 },
+		candidates: { type: 'array', minItems: 1, maxItems: 12, items: input({ label: { type: 'string', maxLength: 60 }, edits: { type: 'array', minItems: 1, maxItems: 48, items: openObject } }) } }, ['id', 'reference']) };
+// A receipt is at most 8 KiB, so the sheet is shrunk until the whole output fits this.
+const SCULPT_COMPARE_OUTPUT_BYTES = 6500;
 const matte = { id: 'object.matte', label: 'Apply object matte', description: 'Prepare derived assets, then publish one fenced object edit.', kind: 'job', domain: 'objects', exposure: 'ui-only', input: input({ objectId: id }) };
-export const declarations = Object.freeze([...semantic, replace, batch, ...['object.attach', 'object.detach', 'object.duplicate'].map(studioActionDeclaration), matte, assetImport]);
+export const declarations = Object.freeze([...semantic, replace, batch, ...['object.attach', 'object.detach', 'object.duplicate'].map(studioActionDeclaration), matte, sculptCompare, assetImport]);
 
 export function register(registry, ports) {
 	const objectOf = objectId => ports.state().objects.find(object => object.id === objectId)
@@ -53,10 +76,43 @@ export function register(registry, ports) {
 			const object = createSceneObject(args.kind, before, args.placement);
 			if (!object) fail('INVALID_ARGUMENT', `Unknown object kind: ${args.kind}`);
 			const placed = updateSceneObject([object], object.id, { ...(args.placement ?? {}), ...(args.name === undefined ? {} : { name: args.name }) })[0];
-			const next = [...before, placed];
+			// `first`: the Outliner lists Props in record order, so a UI-made object
+			// goes to the top where it is seen, not below a long expanded group.
+			const next = args.first ? [placed, ...before] : [...before, placed];
 			owned().write(args.parent === undefined ? next : setSceneObjectParent(next, placed.id, args.parent));
 			return result(before, 'Added object.');
 		},
+		'object.sculpt': args => {
+			const before = owned().read();
+			if ((args.recipe === undefined) === (args.edits === undefined)) fail('INVALID_ARGUMENT', 'Give exactly one of recipe (whole) or edits (part by part).');
+			if (args.edits !== undefined && args.id === undefined) fail('INVALID_ARGUMENT', 'edits patch an existing sculpt: give its id.');
+			let refused, changedParts = null;
+			if (args.edits !== undefined) {
+				const target = objectOf(args.id);
+				if (target.renderer !== SCULPT_KIND) fail('INVALID_ARGUMENT', `${args.id} is a ${target.renderer}, not a sculpt.`);
+				refused = patchSculptRecipe(target.recipe, args.edits);
+				changedParts = refused.changed;
+			} else refused = normalizeSculptRecipe(args.recipe);
+			if (!refused.ok) fail('INVALID_ARGUMENT', `Recipe refused at ${refused.error}`);
+			const patch = { ...(args.placement ?? {}), ...(args.name === undefined ? {} : { name: args.name }) };
+			let objectId = args.id;
+			if (objectId !== undefined) {
+				const target = objectOf(objectId);
+				if (target.renderer !== SCULPT_KIND) fail('INVALID_ARGUMENT', `${objectId} is a ${target.renderer}, not a sculpt; omit id to create a new sculpt.`);
+				owned().write(updateSceneObject(before, objectId, { ...patch, recipe: refused.recipe }));
+			} else {
+				if (args.parent !== undefined) objectOf(args.parent);
+				const made = createSculptObject({ recipe: refused.recipe, name: args.name }, before, args.placement);
+				objectId = made.object.id;
+				const next = [...before, updateSceneObject([made.object], objectId, patch)[0]];
+				owned().write(args.parent === undefined ? next : setSceneObjectParent(next, objectId, args.parent));
+			}
+			const sculpted = owned().read().find(row => row.id === objectId);
+			const parts = expandSculptParts(sculpted.recipe).length;
+			const size = `${sculpted.footprint.width} × ${sculpted.footprint.depth} m, ${sculpted.height} m tall`;
+			return { affectedIds: [objectId, ...result(before, '').affectedIds.filter(row => row !== objectId)],
+				summary: `${args.id === undefined ? 'Sculpted' : changedParts ? `Patched ${changedParts.join(', ')} on` : 'Re-sculpted'} ${sculpted.name} (${objectId}): ${parts} parts, ${size}.` };
+		},
 		'object.remove': ({ ids }) => {
 			const before = owned().read(); ids.forEach(objectOf);
 			owned().write(ids.reduce((rows, id) => removeSceneObject(rows, id), before));
@@ -67,10 +123,16 @@ export function register(registry, ports) {
 			owned().write(updateSceneObject(before, id, { name }));
 			return result(before, 'Renamed object.');
 		},
-		'object.update': ({ id, patch }) => {
-			objectOf(id); const before = owned().read();
-			owned().write(updateSceneObject(before, id, patch));
-			return result(before, 'Updated object.');
+		'object.update': ({ id, patch }, context) => {
+			const target = objectOf(id), before = owned().read();
+			// Wire callers get an error for a key nothing reads; the UI's own patches stay lenient.
+			const unknown = Object.keys(patch ?? {}).filter(key => !objectPatchFields(target).includes(key));
+			if (unknown.length && context?.origin && context.origin !== 'ui') fail('INVALID_ARGUMENT', `object.update cannot set ${unknown.join(', ')}${unknown.some(key => PATCH_HINTS[key]) ? ` (${unknown.filter(key => PATCH_HINTS[key]).map(key => `${key}: ${PATCH_HINTS[key]}`).join('; ')})` : ''}. Supported fields: ${objectPatchFields(target).join(', ')}.`);
+			const next = updateSceneObject(before, id, patch);
+			owned().write(next);
+			const kept = next.find(row => row.id === id);
+			const warning = clampWarning(id, Object.fromEntries(['x', 'y', 'z', 'scaleX', 'scaleY', 'scaleZ'].filter(key => Object.hasOwn(patch ?? {}, key)).map(key => [key, Number(patch[key])])), kept);
+			return { ...result(before, 'Updated object.'), ...(warning ? { warnings: [warning] } : {}) };
 		},
 		'object.group': ({ parent, children }) => {
 			objectOf(parent); children.forEach(objectOf);
@@ -84,9 +146,17 @@ export function register(registry, ports) {
 			owned().write(children.reduce((rows, id) => setSceneObjectParent(rows, id, null), before));
 			return result(before, 'Ungrouped objects.');
 		},
+		'object.groupUnderEmpty': ({ id }) => {
+			const object = objectOf(id); const before = owned().read();
+			if (object.attach) fail('CAPABILITY_MISSING', 'Detach the object from its character before grouping it.');
+			const grouped = groupUnderNewEmpty(before, id);
+			if (!grouped) fail('INVALID_ARGUMENT', 'Cannot group this object.');
+			owned().write(grouped.objects);
+			return { affectedIds: [grouped.emptyId, id], summary: 'Grouped the object under a new Empty.' };
+		},
 		'objects.arrange': args => {
 			const plan = owned().arrange(args);
-			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.' };
+			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.', checks: plan.checks, warnings: plan.warnings };
 		},
 	};
 	// Scalar scale is a convenience at the command boundary; the registry still
@@ -157,6 +227,31 @@ export function register(registry, ports) {
 		await owned().applyMatte(objectId, context);
 		return { affectedIds: [objectId], summary: 'Applied the object matte.' };
 	} });
+	registry.register({ ...sculptCompare, available, run: async ({ id: objectId, reference, yaw, elevation = 0, candidates }, context) => {
+		const target = objectOf(objectId);
+		if (target.renderer !== SCULPT_KIND || !target.recipe) fail('INVALID_ARGUMENT', `${objectId} is a ${target.renderer}, not a sculpt.`);
+		const images = ports.sculptImages ?? browserSculptImages;
+		let image, scored;
+		try { image = await images.decode(reference); }
+		catch (error) { fail('INVALID_ARGUMENT', `Could not read the reference image: ${error?.message || error}`); }
+		context?.signal?.throwIfAborted();
+		try { scored = scoreSculptAgainstReference(target.recipe, image, { yaw, elevation, candidates }); }
+		catch (error) { fail('INVALID_ARGUMENT', error?.message || String(error)); }
+		const { result, ranked, refused } = scored;
+		const output = { id: objectId, ...result.report };
+		if (ranked) Object.assign(output, { ranking: [...ranked.map(row => rankingRow(row, result)), ...refused.map(({ label, error }) => ({ label, refused: error }))],
+			sheetLabel: ranked[0].label, note: `Nothing was applied. Apply the winner with object.sculpt { id: "${objectId}", edits }.` });
+		const sheet = (ranked ? ranked[0].result : result).sheet;
+		const room = SCULPT_COMPARE_OUTPUT_BYTES - JSON.stringify(output).length;
+		// The full-size sheet is always tried, however narrow; shrinking stops at 64 px.
+		for (let factor = 1; factor === 1 || sheet.width / factor >= 64; factor *= 2) {
+			const dataUrl = await images.encodePng(factor === 1 ? sheet : shrinkRgba(sheet, factor));
+			if (dataUrl.length + 40 <= room) { Object.assign(output, { sheetDataUrl: dataUrl, ...(factor > 1 ? { sheetScale: 1 / factor } : {}) }); break; }
+		}
+		if (!output.sheetDataUrl) output.sheetOmitted = 'The overlay sheet does not fit in a receipt at a readable size; read missingByBand and extraByPart.';
+		const lead = ranked ? `best ${ranked[0].label} at IoU ${ranked[0].result.report.iou} (current ${result.report.iou}), ${candidates.length} candidates scored, none applied` : `IoU ${result.report.iou}`;
+		return { affectedIds: [], output, summary: `Compared ${target.name || objectId} with the reference at yaw ${result.report.view.yaw}: ${lead}.` };
+	} });
 	registry.register({ ...assetImport, available: () => true,
 		run: async (args, context) => {
 			const { source, ...options } = args;