cozyclay 1.10.0 → 2.0.2

package/src/commands/motion.js

@@ -0,0 +1,231 @@
+// Motion and IK commands share one per-character authored-intent owner.
+import { STUDIO_IK_CHAIN_TRACKS, studioActionDeclaration } from "../studio-actions.js";
+import { fail, characterOf } from "./shared.js";
+import { elementSetSchema, registerElementSet } from './elements.js';
+import './elements/motion.js';
+import './elements/character.js';
+import { generationArgs } from '../motion/generation.js';
+import { applyRootDrop, normalizeRootDrop } from '../ardy/root-drop.js';
+import { characterScaleFor } from '../ardy/npz.js';
+import { I2V_MOTION_DURATIONS } from '../i2v-motion-client.js';
+import { createMotionEdit, trimMotionEdit, splitMotionEdit, setMotionSegmentSpeed, removeMotionSegment } from '../ardy/motion-edit.js';
+const id = { type: 'string', minLength: 1 }, frame = { type: 'integer', minimum: 0 };
+const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const drop = { oneOf: [{ type: 'null' }, input({ from_s: { type: 'number', minimum: 0 }, to_s: { type: 'number', exclusiveMinimum: 0 }, meters: { type: 'number', exclusiveMinimum: 0, maximum: 30 } })] };
+const mutation = (id, label, properties, required) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'motion', input: input(properties, required) });
+const setInput = elementSetSchema('motion');
+// A collection transaction has no single native character target. Normalize
+// that scope explicitly so begin/update carry the same target sentinel.
+for (const variant of setInput.oneOf) variant.properties.characterId = { type: 'null', default: null };
+const vector3 = { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3 };
+const rangePin = input({ id: { ...id, maxLength: 64 }, track: { type: 'string', enum: ['leftHand', 'rightHand', 'leftFoot', 'rightFoot'] },
+	startFrame: frame, endFrame: frame, blend: { type: 'integer', minimum: 1, maximum: 240 }, reach: { type: 'string', enum: ['limb', 'body'] },
+	target: { oneOf: [input({ space: { const: 'world' }, position: vector3 }), input({ space: { const: 'object' }, objectId: id, local: vector3 })] },
+}, ['id', 'track', 'startFrame', 'endFrame', 'blend', 'target']);
+const rangePins = [
+	mutation('motion.rangePin.apply', 'Apply range pin', { characterId: id, pin: rangePin, replaceExisting: { type: 'boolean', default: false } }, ['characterId', 'pin']),
+	mutation('motion.rangePin.remove', 'Remove range pin', { characterId: id, pinId: id }),
+];
+const platformFit = [
+	{ id: 'motion.platformFit.run', label: 'Fit motion to platforms', description: 'Analyse scene platforms and prepare or apply an IK correction.', kind: 'job', domain: 'motion', timeoutMs: 300000, input: input({ characterId: id, preview: { type: 'boolean', default: false } }, ['characterId']) },
+	{ id: 'motion.platformFit.remove', label: 'Remove platform fit', description: 'Apply or remove the reviewed platform-fit correction.', kind: 'job', domain: 'motion', timeoutMs: 300000, input: input({ characterId: id, apply: { type: 'boolean', default: false } }, ['characterId']) },
+];
+const edits = [
+	{ ...mutation('motion.set', 'Set take fields', {}), input: setInput },
+	mutation('motion.trim', 'Trim motion', { characterId: id, start: frame, end: frame }),
+	mutation('motion.resetTrim', 'Restore full take', { characterId: id }),
+	mutation('motion.cut', 'Cut motion segment', { characterId: id, frame }),
+	mutation('motion.setSegmentSpeed', 'Set segment speed', { characterId: id, id, speed: { type: 'number', minimum: 0.05, maximum: 8 } }),
+	mutation('motion.removeSegment', 'Remove motion segment', { characterId: id, id }),
+	mutation('motion.fixCollisions', 'Fix body collisions', { characterId: id, scope: { type: 'string', enum: ['frame', 'clip'], default: 'frame' } }, ['characterId']),
+];
+const generate = { id: 'motion.generate', label: 'Generate motion', description: 'Generate the named character through the editor pipeline, following its prompt blocks, root path, pose pins and take lineage.',
+	kind: 'job', domain: 'motion', generation: 'motion', background: true, timeoutMs: 1000,
+	input: input({ characterId: id, drop, blocks: elementSetSchema('character').properties.set.properties.layer.properties.promptClips,
+		durationSeconds: { type: 'number', minimum: 1, maximum: 1200 }, seed: { type: 'integer', minimum: 0, maximum: 2147483647 } }, ['characterId']) };
+const prepared = { ...mutation('motion.applyPrepared', 'Apply prepared motion edit', { characterId: id, token: id }), exposure: 'ui-only' };
+const loads = [
+	{ id: 'motion.replace', label: 'Replace take', input: input({ characterId: id, url: id, prompt: { type: 'string', default: '' },
+		blocks: { type: 'array', maxItems: 120, items: input({ startFrame: frame, endFrame: { ...frame, minimum: 1 }, prompt: { type: 'string' } }) },
+		drop,
+	}, ['characterId', 'url']) },
+	{ id: 'motion.loadVersion', label: 'Restore take version', input: input({ characterId: id, motionUrl: id }) },
+].map(entry => ({ ...entry, description: entry.label, kind: 'job', domain: 'motion' }));
+const tools = [
+	mutation('motion.applyPhysics', 'Apply reviewed physics', { characterId: id }),
+	mutation('motion.editTrail', 'Edit motion trail', { characterId: id, track: { type: 'string', enum: ['hips', 'leftFoot', 'rightFoot', 'leftHand', 'rightHand', 'head'], default: 'hips' }, grabFrame: frame, radiusFrames: { ...frame, minimum: 1 }, delta: input({ x: { type: 'number' }, y: { type: 'number' }, z: { type: 'number' } }) }, ['characterId', 'grabFrame', 'radiusFrames', 'delta']),
+	mutation('ik.applyPose', 'Key full-body pose', { characterId: id, frame, pose: { type: 'object', properties: { bones: { type: 'object', properties: {}, required: [], additionalProperties: true }, rootY: { type: 'number' } }, required: ['bones'], additionalProperties: true } }),
+];
+const physics = { id: 'motion.autoPhysics', label: 'Review motion physics', description: 'Analyse real rig motion and optionally apply one retained correction.', kind: 'job', domain: 'motion',
+	input: input({ characterId: id, apply: { type: 'boolean', default: true }, strength: { type: 'number', minimum: 0, maximum: 1, default: 1 },
+		protectedFrames: { type: 'array', items: frame, default: [] }, overrides: { type: 'array', default: [], items: input({
+			site: { type: 'string', enum: ['leftFoot', 'rightFoot', 'leftHand', 'rightHand', 'leftKnee', 'rightKnee'] }, start: frame, end: frame,
+			mode: { type: 'string', enum: ['plant', 'free'] },
+		}) },
+	}, ['characterId']) };
+// These only queue the existing editor producers. Their eventual take
+// publication is owned above; generation-pipeline unification remains #444.
+const queued = ['motion.commitLineEdit', 'motion.regenerateTrail'].map(id => ({ id, label: id === 'motion.commitLineEdit' ? 'Commit line edit' : 'Regenerate trail edit',
+	description: 'Queue the current editor draft through the existing generation producer.', kind: 'transient', exposure: 'ui-only', input: input({ characterId: { type: 'string' } }) }));
+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.',
+	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 })) } }, []) };
+export const declarations = Object.freeze([videoDraft, generate, ...queued, prepared, ...loads, physics, ...tools, ...rangePins, ...platformFit, ...edits, ...legacyIk, ...ik, clear, ...["motion.generateAllBlocks", "motion.generateFromVideo"].map(studioActionDeclaration)]);
+
+export function register(registry, ports) {
+	const owner = () => ports.storeDomain('motion');
+	const mounted = () => Boolean(ports.storeDomain?.('motion')) || 'The motion owner is not mounted.';
+	const take = characterId => { characterOf(ports, characterId); return owner().motionFor(characterId) ?? fail('TARGET_NOT_READY', 'Load a take for this character first.'); };
+	registry.register({ ...videoDraft, available: mounted, run(args) {
+		owner().setVideoDraft(args);
+		return { affectedIds: [], summary: videoDraft.label };
+	} });
+	registry.registerToolAlias('generate_motion', generate.id, generationArgs);
+	registry.register({ ...generate, available: mounted, target: args => args.characterId, async run(args, context) {
+		characterOf(ports, args.characterId);
+		if (owner().isGenerating()) fail('TARGET_BUSY', 'A motion generation is already running.');
+		if (args.drop && !normalizeRootDrop(args.drop)) fail('INVALID_ARGUMENT', 'Invalid drop.');
+		if (args.blocks) context.run('character.setPromptBlocks', { characterId: args.characterId, blocks: args.blocks });
+		const generationContext = !args.drop ? context : { ...context, commit: apply => context.commit(() => {
+			const result = apply(), take = owner().motionFor(args.characterId), layer = owner().layer(args.characterId);
+			owner().replace(args.characterId, applyRootDrop(take, args.drop, { worldScale: characterScaleFor(take) }), {
+				recipe: layer.takeRecipe, versions: layer.takeVersions, ikKeys: layer.ikKeys,
+			});
+			owner().writeLayer(args.characterId, { committedIkEdits: layer.committedIkEdits });
+			return result;
+		}) };
+		await owner().generate(args, generationContext);
+		return { affectedIds: [args.characterId], summary: 'Generated motion.' };
+	} });
+	for (const declaration of queued) registry.register({ ...declaration, available: mounted, run({ characterId }) {
+		characterOf(ports, characterId);
+		if (ports.state().activeCharacterId !== characterId) fail('TARGET_NOT_READY', 'Select the character that owns this editor draft.');
+		if (declaration.id === 'motion.commitLineEdit') owner().requestLineEdit(); else owner().requestTrailRegeneration();
+		return { affectedIds: [], summary: declaration.label };
+	} });
+	registry.register({ ...prepared, available: mounted, run({ characterId, token }) {
+		characterOf(ports, characterId); const result = owner().applyPrepared(token);
+		return { affectedIds: result?.affectedIds ?? [characterId], summary: prepared.label };
+	} });
+	for (const declaration of loads) registry.register({ ...declaration, available: mounted, target: args => args.characterId, async run(args, context) {
+		characterOf(ports, args.characterId); await owner().loadRemote(args, context);
+		return { affectedIds: [args.characterId], summary: declaration.label };
+	} });
+	registry.register({ ...physics, available: mounted, target: args => args.characterId, async run(args, context) {
+		characterOf(ports, args.characterId);
+		return { affectedIds: [args.characterId], summary: physics.label, output: await owner().autoPhysics(args.characterId, args, context) };
+	} });
+	for (const declaration of tools) registry.register({ ...declaration, available: mounted, run(args) {
+		characterOf(ports, args.characterId);
+		if (declaration.id === 'motion.applyPhysics') owner().applyPhysics(args.characterId);
+		else if (declaration.id === 'motion.editTrail') owner().editTrail(args.characterId, args);
+		else {
+			if (args.frame >= ports.state().frameCount) fail('INVALID_RANGE', 'IK frame is outside the timeline.');
+			for (const angles of Object.values(args.pose.bones)) if (!Array.isArray(angles) || angles.length !== 3 || !angles.every(Number.isFinite)) fail('INVALID_ARGUMENT', 'Pose bones require three finite rotation angles.');
+			owner().keyPose(args.characterId, args.frame, args.pose);
+		}
+		return { affectedIds: [args.characterId], summary: declaration.label };
+	} });
+	for (const declaration of rangePins) registry.register({ ...declaration, available: mounted, run(args) {
+		characterOf(ports, args.characterId);
+		const output = declaration.id === 'motion.rangePin.apply'
+			? owner().bakeRangePin(args.characterId, args.pin, args.replaceExisting)
+			: owner().removePin(args.characterId, args.pinId);
+		return { affectedIds: [args.characterId], summary: declaration.label, ...(output ? { output } : {}) };
+	} });
+	registry.register({ ...platformFit[0], available: mounted, target: args => args.characterId, async run(args, context) {
+		characterOf(ports, args.characterId);
+		const output = await owner().platformFitRun(args.characterId, context, { preview: args.preview === true });
+		return { affectedIds: [args.characterId], summary: platformFit[0].label, output };
+	} });
+	registry.register({ ...platformFit[1], available: mounted, target: args => args.characterId, run(args, context) {
+		characterOf(ports, args.characterId);
+		const output = owner().platformFitRemove(args.characterId, context, { apply: args.apply === true });
+		return { affectedIds: [args.characterId], summary: platformFit[1].label, ...(output ? { output } : {}) };
+	} });
+	registerElementSet({ register(entry) { registry.register({ ...entry, available: mounted, run(args) {
+		for (const op of args.ops ?? [args]) take(op.id);
+		return entry.run(args);
+	} }); } }, ports, edits[0]);
+	for (const declaration of edits.slice(1)) registry.register({ ...declaration, available: mounted, run(args) {
+		const { characterId } = args; characterOf(ports, characterId);
+		if (declaration.id === 'motion.fixCollisions') owner().fix(characterId, args.scope);
+		else {
+			const current = take(characterId), full = owner().fullMotionFor(characterId);
+			let segments = current.editSegments;
+			if (declaration.id === 'motion.trim') {
+				if (args.start > args.end || args.end >= current.frames) fail('INVALID_RANGE', 'Trim range is outside the take.');
+				segments = trimMotionEdit(segments, args.start, args.end);
+			} else if (declaration.id === 'motion.resetTrim') segments = createMotionEdit(full.frames);
+			else if (declaration.id === 'motion.cut') segments = splitMotionEdit(segments, args.frame);
+			else if (declaration.id === 'motion.setSegmentSpeed') segments = setMotionSegmentSpeed(segments, args.id, args.speed);
+			else { if (segments.length <= 1) fail('INVALID_ARGUMENT', 'Use motion.clear to remove the final segment.'); segments = removeMotionSegment(segments, args.id); }
+			if (segments !== current.editSegments) owner().editSegments(characterId, segments);
+		}
+		return { affectedIds: [characterId], summary: declaration.label };
+	} });
+	for (const [index, declaration] of [...legacyIk, ...ik].entries()) registry.register({ ...declaration,
+		available: state => state.characters.length > 0 || 'There are no characters in this scene.', run(args) {
+			const character = characterOf(ports, args.characterId), kind = index % 3;
+			if (kind === 0) {
+				const { frame, tracks } = args, names = Object.keys(tracks);
+				if (frame >= ports.state().frameCount) fail('INVALID_RANGE', 'IK frame is outside the timeline.');
+				if (!names.length) fail('INVALID_ARGUMENT', 'Name at least one track.');
+				for (const track of names) {
+					const key = tracks[track], chain = STUDIO_IK_CHAIN_TRACKS.includes(track), bones = chain ? 3 : 1;
+					if (!key.q && !key.p) fail('INVALID_ARGUMENT', `tracks.${track} needs q or p.`);
+					if (key.chainP && !chain) fail('INVALID_ARGUMENT', `tracks.${track}.chainP is for chain tracks only.`);
+					for (const field of ['q', 'baseQ', 'chainP']) if (key[field] && key[field].length !== bones) fail('INVALID_ARGUMENT', `tracks.${track}.${field} needs ${bones} entries.`);
+					if ([...(key.q ?? []), ...(key.baseQ ?? [])].some(q => Math.hypot(q.x, q.y, q.z, q.w) < 1e-6)) fail('INVALID_ARGUMENT', `tracks.${track} has a zero-length quaternion.`);
+				}
+				ports.setCharacterIkKey(args.characterId, frame, tracks);
+			} else if (kind === 1) ports.removeCharacterIkKey(args.characterId, args.frame);
+			else ports.clearCharacterIkKeys(args.characterId);
+			return { affectedIds: [character.id], summary: declaration.label };
+		} });
+	registry.register({ ...clear, available: () => Boolean(ports.storeDomain?.('motion')) || typeof ports.clearMotionNative === 'function' || 'The motion owner is not mounted.',
+		run({ characterId }) {
+			if (ports.storeDomain?.('motion')) { characterOf(ports, characterId); owner().clear(characterId); }
+			else {
+				if (ports.state().activeCharacterId !== characterId) fail('TARGET_NOT_READY', 'Select this character before clearing its take.');
+				ports.clearMotionNative();
+			}
+			return { affectedIds: [characterId], summary: 'Cleared motion.' };
+		} });
+	registry.register({ ...studioActionDeclaration("motion.generateAllBlocks"), target: () => ports.state().activeCharacterId,
+		available: state => state.generating ? "A motion generation is already running."
+			: !state.motionReady ? "The motion backend is not ready."
+				: state.promptBlockCount === 0 ? "The active character has no prompt block with text; write them with patch_elements character.promptBlocks." : true,
+		run: (_args, context) => {
+			const { activeCharacterId, promptBlockCount } = ports.state();
+			const shown = ports.runAllPromptBlocks(context) ?? [];
+			if (shown?.then) return shown.then(() => ({ affectedIds: activeCharacterId ? [activeCharacterId] : [], summary: `Generated motion from ${promptBlockCount} prompt blocks.` }));
+			// The generation queues synchronously or not at all; when it does not,
+			// the editor's last toast names the refusal (rig not loaded, a root
+			// waypoint outside the clip, an over-long block, a line-edit draft).
+			if (!ports.state().generating) fail("TARGET_NOT_READY", shown.length ? `Generation not started: ${shown.at(-1)}` : "The editor did not start the generation; check the active character's rig and prompt blocks.");
+			return { affectedIds: activeCharacterId ? [activeCharacterId] : [], summary: `Started generating the active character's motion from ${promptBlockCount} prompt block${promptBlockCount === 1 ? "" : "s"}.` };
+		} });
+	// AI-video motion: the agent panel's Generate motion (generateI2vMotion
+	// "act"), awaited to its clip. The AI motion card shows every failure it meets, so
+	// a refusal is silent in the UI and tells the model the reason in English.
+	registry.register({ ...studioActionDeclaration("motion.generateFromVideo"), domain: "motion", target: () => ports.state().activeCharacterId,
+		available: ({ i2vMotion }) => !i2vMotion.enabled ? "AI video motion (Fal) is not enabled for this account."
+			: !["idle", "done", "error", "failed"].includes(i2vMotion.status) ? "An AI video motion generation is already running; wait for it to finish."
+				: i2vMotion.dailyRemaining === 0 ? "The account's daily AI video generations are used up." : true,
+		run: async ({ instruction }, context) => {
+			const outcome = await ports.generateI2vMotion("act", instruction, context);
+			if (outcome.failed) fail("TARGET_NOT_READY", outcome.failed);
+			const { job, footage, dailyRemaining } = outcome;
+			if (!job.video?.url) fail("TARGET_NOT_READY", "The AI video model finished without returning a video.");
+			return { affectedIds: [], output: { videoUrl: job.video.url, resolution: job.resolution ?? null, durationSeconds: job.resultDuration ?? job.duration ?? null,
+				ingested: Boolean(footage), frames: footage?.frames ?? null, fps: footage?.fps ?? null, dailyRemaining },
+			summary: footage
+				? `The AI video (${job.resolution}, ${footage.frames} frames at ${footage.fps} fps) is ingested as Video capture footage and the timeline now spans it; its motion becomes a take once GVHMR extraction runs in the Video capture panel.`
+				: `The AI video is ready at ${job.video.url}, but ingesting it as footage failed; the Video capture panel shows why.` };
+		} });
+}

package/src/commands/objects.js

@@ -0,0 +1,174 @@
+// Scene object commands: attachment, duplication and asset import.
+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 { 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 ids = { type: 'array', items: id, minItems: 1, maxItems: 100 };
+const number = { type: 'number' };
+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 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.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 } }, [])),
+	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',
+	input: input({ ops: { type: 'array', maxItems: 100, items: input({ name: { type: 'string' }, args: { type: 'object', properties: {}, additionalProperties: true } }) }, atomic: { type: 'boolean' }, stopOnError: { type: 'boolean' }, label: { type: 'string' } }, ['ops']) };
+const replace = { ...mutation('objects.replace', 'Replace authored objects', input({ objects: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } } })), exposure: 'ui-only' };
+const changedIds = (before, after) => [...new Set([...before, ...after].map(row => row.id))].filter(id => JSON.stringify(before.find(row => row.id === id)) !== JSON.stringify(after.find(row => row.id === id)));
+const assetProperties = { ...studioActionDeclaration('asset.import').input.properties, placement,
+	...Object.fromEntries(['x', 'y', 'z', 'rot', 'height'].map(key => [key, number])), clay: { type: 'boolean' }, mimeType: { type: 'string' } };
+const assetImport = { ...studioActionDeclaration('asset.import'), kind: 'job', domain: 'objects',
+	input: { ...input({ ...assetProperties, assetId: id, fileToken: id }, ['placeAs']), oneOf: [
+		input(assetProperties, ['source', 'name', 'placeAs']),
+		input({ assetId: id, placement, placeAs: assetProperties.placeAs }, ['assetId', 'placeAs']),
+		input({ fileToken: id, placeAs: { type: 'string', enum: ['mesh', 'cutout'] } }, ['fileToken', 'placeAs']),
+	] } };
+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 function register(registry, ports) {
+	const objectOf = objectId => ports.state().objects.find(object => object.id === objectId)
+		?? fail("STALE_TARGET", `Object ${objectId} is not in this scene.`);
+	const owned = () => ports.storeDomain('objects');
+	const available = () => Boolean(ports.storeDomain?.('objects')) || 'The objects document owner is not mounted.';
+	const result = (before, summary) => ({ affectedIds: changedIds(before, owned().read()), summary });
+	const methods = {
+		'object.add': args => {
+			const before = owned().read();
+			if (args.parent !== undefined) objectOf(args.parent);
+			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];
+			owned().write(args.parent === undefined ? next : setSceneObjectParent(next, placed.id, args.parent));
+			return result(before, 'Added object.');
+		},
+		'object.remove': ({ ids }) => {
+			const before = owned().read(); ids.forEach(objectOf);
+			owned().write(ids.reduce((rows, id) => removeSceneObject(rows, id), before));
+			return result(before, 'Removed objects.');
+		},
+		'object.rename': ({ id, name }) => {
+			objectOf(id); const before = owned().read();
+			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.group': ({ parent, children }) => {
+			objectOf(parent); children.forEach(objectOf);
+			const before = owned().read();
+			if (children.some(id => id === parent || descendantsOf(before, id).some(row => row.id === parent))) fail('INVALID_ARGUMENT', 'Grouping would create a cycle.');
+			owned().group(parent, children);
+			return result(before, 'Grouped objects.');
+		},
+		'object.ungroup': ({ children }) => {
+			children.forEach(objectOf); const before = owned().read();
+			owned().write(children.reduce((rows, id) => setSceneObjectParent(rows, id, null), before));
+			return result(before, 'Ungrouped objects.');
+		},
+		'objects.arrange': args => {
+			const plan = owned().arrange(args);
+			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.' };
+		},
+	};
+	// Scalar scale is a convenience at the command boundary; the registry still
+	// owns all field mapping, normalization, publication and patch aliases.
+	registerElementSet({ register(entry) {
+		const expand = op => typeof op.set.scale === 'number' ? { ...op, set: { ...op.set, scale: { x: op.set.scale, y: op.set.scale, z: op.set.scale } } } : op;
+		registry.register({ ...entry, available, run: args => {
+			const ops = (args.ops ?? [args]).map(expand);
+			let draft = owned().read();
+			for (const { id, set } of ops) if (Object.hasOwn(set, 'parent')) {
+				const object = objectOf(id), parent = set.parent;
+				if (parent !== null) objectOf(parent);
+				if (parent === id || descendantsOf(draft, id).some(row => row.id === parent)) fail('INVALID_ARGUMENT', 'Grouping would create a cycle.');
+				if (object.attach) fail('CAPABILITY_MISSING', 'Use object.group to preserve an attached object world transform.');
+				draft = setSceneObjectParent(draft, id, parent);
+			}
+			return entry.run(args.ops ? { ops } : ops[0]);
+		} });
+	} }, ports, semantic[0]);
+	for (const declaration of semantic.slice(1)) registry.register({ ...declaration, available, run: methods[declaration.id] });
+	// Native adapters stay usable until their owner is mounted. In the editor,
+	// domains mount before registry construction, so this is always the bus alias.
+	if (ports.storeDomain?.('objects')) registry.registerToolAlias('arrange_objects', 'objects.arrange');
+	registry.register({ ...replace, available, run: ({ objects }) => {
+		const next = objects.map(normalizeSceneObject);
+		if (next.some(row => !row) || new Set(next.map(row => row.id)).size !== next.length) fail('INVALID_ARGUMENT', 'Objects require valid records and unique ids.');
+		const before = owned().read(); owned().write(next);
+		return result(before, 'Replaced authored objects.');
+	} });
+	registry.register({ ...batch, available, run: (args, context) => {
+		const before = owned().read();
+		const output = context.commit(() => owned().batch(args));
+		return { ...result(before, 'Applied object batch.'), output };
+	} });
+	registry.register({ ...studioActionDeclaration("object.attach"),
+		available: state => state.objects.length === 0 ? "There are no scene objects to attach."
+			: state.characters.length === 0 ? "There are no characters to attach an object to." : true,
+		run: ({ objectId, characterId, bone }) => {
+			const object = objectOf(objectId), character = characterOf(ports, characterId), before = ports.state().objects;
+			ports.attachSceneObject(objectId, { characterId, bone: bone ?? null });
+			const frameName = `${character.subject || character.id}'s ${bone ?? "root"}`;
+			return { affectedIds: [objectId], summary: ports.state().objects === before
+				? `${object.name || objectId} already rides ${frameName}; nothing changed.`
+				: `Attached ${object.name || objectId} to ${frameName}, keeping its place on screen.` };
+		} });
+	registry.register({ ...studioActionDeclaration("object.detach"),
+		available: state => state.objects.some(object => object.attach || object.parent) || "No scene object is attached to a character or grouped.",
+		run: ({ objectId }) => {
+			const object = objectOf(objectId);
+			if (!object.attach && !object.parent) fail("TARGET_NOT_READY", `${object.name || objectId} is not attached to a character or in a group.`);
+			ports.attachSceneObject(objectId, null);
+			return { affectedIds: [objectId], summary: `Put ${object.name || objectId} back in the world where it is now.` };
+		} });
+	registry.register({ ...studioActionDeclaration("object.duplicate"),
+		available: state => state.objects.length > 0 || "There are no scene objects to duplicate.",
+		run: ({ objectId }) => {
+			const state = ports.state(), id = objectId ?? state.selectedObjectId;
+			if (!id) fail("TARGET_NOT_READY", "Name objectId or select an object first.");
+			const source = state.objects.find(object => object.id === id) ?? fail("STALE_TARGET", `Object ${id} is not in this scene.`);
+			ports.duplicateSelectedSceneObject(id);
+			const after = ports.state().objects, affectedIds = changedIds(state.objects, after);
+			const copy = after.find(object => affectedIds.includes(object.id));
+			return { affectedIds, summary: copy ? `Duplicated ${source.name || source.id} as ${copy.name || copy.id}.` : "Duplicate object: nothing changed." };
+		} });
+	// The live import_asset path (validate, store the bytes, ONE atomic store
+	// entry), fed a data URL; an http(s) source is fetched into one first.
+	registry.register({ ...matte, available, run: async ({ objectId }, context) => {
+		await owned().applyMatte(objectId, context);
+		return { affectedIds: [objectId], summary: 'Applied the object matte.' };
+	} });
+	registry.register({ ...assetImport, available: () => true,
+		run: async (args, context) => {
+			const { source, ...options } = args;
+			const { name, placeAs } = options;
+			let dataUrl = source;
+			if (source && !source.startsWith("data:")) {
+				try { dataUrl = await ports.fetchImportSource(source); }
+				catch (error) { fail("TARGET_NOT_READY", `Could not fetch the source (${error?.message || error}); its server must allow cross-origin reads.`); }
+			}
+			let imported;
+			try { imported = await (ports.storeDomain?.('objects')?.importAsset ?? ports.importAsset)({ ...options, dataUrl }, context); }
+			catch (error) { fail(error.code ?? "INVALID_ARGUMENT", `Not imported: ${error?.message || error}`); }
+			return { affectedIds: [imported.objectId], output: imported, summary: `Imported ${name ?? imported.objectId} as a ${placeAs} (object ${imported.objectId}, asset ${imported.assetId}).` };
+		} });
+}

package/src/commands/project.js

@@ -0,0 +1,53 @@
+import { studioActionDeclaration } from "../studio-actions.js";
+import { fail } from "./shared.js";
+
+const input = (properties = {}, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+const name = { type: "string", minLength: 1, maxLength: 240 };
+const token = { type: "string", minLength: 1, maxLength: 240 };
+const document = (id, label, properties = {}) => ({ id, label, description: label, kind: "document", exposure: "confirm", input: input(properties) });
+const rename = { id: "project.rename", label: "Rename project", description: "Rename the project in one retained undo entry.", kind: "mutation", undoDomain: "scenes", input: input({ name }, ["name"]) };
+const save = { ...studioActionDeclaration("project.save"), input: input({ name }) };
+const saveAs = { ...save, id: "project.saveAs", label: "Save project as" };
+const opening = document("project.open", "Open a project file", { serialized: { type: "string", maxLength: 400_000_000 }, handleToken: token, projectToken: token });
+const fresh = document("project.new", "Start a new project", { name });
+const starter = document("project.openStarter", "Open a starter project", { id: token, source: { type: "string", enum: ["starter", "tutorial", "launch"] }, name });
+const restore = { ...document("project.restore", "Restore the remembered project", { handleToken: token }), exposure: "ui-only" };
+const browse = { id: "project.browse", label: "Browse projects", description: "Show the project browser.", kind: "transient", exposure: "ui-only", input: input() };
+export const declarations = Object.freeze([rename, save, saveAs, opening, fresh, starter, restore, browse]);
+
+export function register(registry, ports) {
+	const owner = () => ports.storeDomain?.("scenes");
+	const available = () => Boolean(owner()) || "The project document owner is not mounted.";
+	registry.register({ ...rename, available, run: ({ name }) => {
+		if (!name.trim()) fail("INVALID_ARGUMENT", "A project name cannot be blank.");
+		owner().renameProject(name);
+		return { affectedIds: [owner().metadata().activeSceneId], summary: "Renamed project." };
+	} });
+	for (const declaration of [save, saveAs]) registry.register({ ...declaration, available: () => true,
+		requiresConfirmation: state => {
+			const project = owner()?.fileState() ?? state.project;
+			return project.hasFile || project.fileAccess;
+		},
+		run: async (args, context) => {
+			const project = owner()?.fileState() ?? ports.state().project;
+			const as = declaration.id === "project.saveAs";
+			if (context.origin !== "ui" && !project.gesture && project.name !== null && project.fileAccess) {
+				if (as || !project.hasFile) fail("TARGET_NOT_READY", "Only the user's click can open the file picker. Ask them to press Save Project.");
+				if (!(await ports.projectFileGranted())) fail("TARGET_NOT_READY", "The browser needs the user's click to re-grant access to the project file.");
+			}
+			const saved = owner() ? await owner().save({ ...args, saveAs: as }, context) : await ports.saveProject(as);
+			if (saved?.naming) fail("TARGET_NOT_READY", "Not saved: the project has no name yet. The Save dialog is open for the user.");
+			if (saved?.cancelled) fail("TARGET_NOT_READY", "Not saved: the user closed the file picker.");
+			if (!saved?.saved) fail("TARGET_NOT_READY", saved?.failure === "missing-resources" ? "Not saved: some project assets or motions are missing."
+				: saved?.failure === "resources-too-large" ? "Not saved: the project's resources are too large." : "Not saved: writing the project file failed.");
+			return { affectedIds: [], output: { fileName: saved.fileName }, summary: saved.downloaded
+				? `This browser has no file access, so the project ${saved.name} was downloaded as ${saved.fileName}.`
+				: `Saved the project ${saved.name} to ${saved.fileName}.` };
+		} });
+	for (const declaration of [opening, fresh, starter, restore, browse]) registry.register({ ...declaration,
+		available, run: async (args, context) => {
+			const result = await owner().projectAction(declaration.id, args, context);
+			if (result === false) fail("TARGET_NOT_READY", "The project was not opened; check the project dialog.");
+			return { affectedIds: [owner().metadata().activeSceneId], output: { opened: result === true }, summary: `${declaration.label}.` };
+		} });
+}

package/src/commands/scene.js

@@ -0,0 +1,81 @@
+// Scene commands: the scene pill's and the Hierarchy scene menu's own
+// handlers. When the open scene moves, the action answers once React has
+// rendered the new room, so the next command reads that scene's state.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { fail } from "./shared.js";
+import { elementSetSchema, registerElementSet } from "./elements.js";
+import "./elements/scene.js";
+
+const mutation = (id, label, input) => ({ id, label, description: label, kind: "mutation", undoDomain: "scenes", input });
+const set = mutation("scene.set", "Set scene name or order", elementSetSchema("scene"));
+const reorder = mutation("scene.reorder", "Reorder a scene", { type: "object", properties: {
+	sceneId: studioActionDeclaration("scene.rename").input.properties.sceneId, order: { type: "number" },
+}, required: ["sceneId", "order"], additionalProperties: false });
+const load = { id: "load_scenes", label: "Load scene document", description: "Load scenes through the non-authored boundary; changed scene ids require confirmation.", kind: "document", exposure: "confirm",
+	input: { type: "object", properties: { document: { type: "object", properties: {
+		version: { type: "integer" }, activeSceneId: { type: "string" }, scenes: { type: "array", minItems: 1, items: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: true } },
+	}, required: ["version", "activeSceneId", "scenes"], additionalProperties: false } }, required: ["document"], additionalProperties: false } };
+export const declarations = Object.freeze([load, set, reorder,
+	...["scene.create", "scene.duplicate", "scene.rename", "scene.delete", "scene.switch"].map(id => {
+		const declaration = studioActionDeclaration(id);
+		return id === "scene.rename" ? { ...declaration, kind: "mutation", undoDomain: "scenes", description: "Rename a scene in one retained undo entry." } : declaration;
+	}),
+]);
+
+export function register(registry, ports) {
+	const available = () => Boolean(ports.storeDomain?.("scenes")) || "The project document owner is not mounted.";
+	registry.register({ ...load, available, run: args => {
+		const output = ports.storeDomain("scenes").loadScenes(args);
+		return { affectedIds: [output.activeSceneId], output, summary: "Loaded scene document." };
+	} });
+	registerElementSet(registry, ports, set);
+	registry.register({ ...reorder, available, run: ({ sceneId, order }) => {
+		const owner = ports.storeDomain("scenes");
+		if (!owner.read().some(row => row.id === sceneId)) fail("STALE_TARGET", `Scene ${sceneId} is not in this project.`);
+		owner.write(owner.read().map(row => row.id === sceneId ? { ...row, order } : row));
+		return { affectedIds: [sceneId], summary: "Reordered scene." };
+	} });
+	const sceneOf = sceneId => ports.state().scenes.find(scene => scene.id === sceneId) ?? fail("STALE_TARGET", `Scene ${sceneId} is not in this project.`);
+	const sceneName = scene => `${scene.name} (${scene.id})`;
+	const sceneAction = (id, available, run) => registry.register({ ...studioActionDeclaration(id), available,
+		run: args => {
+			const before = ports.state(), describe = run(args, before), after = ports.state();
+			const moved = after.activeSceneId !== before.activeSceneId, opened = after.scenes.find(scene => scene.id === after.activeSceneId);
+			const affectedIds = [...new Set([
+				...after.scenes.filter(scene => !before.scenes.some(row => row.id === scene.id && row.name === scene.name)).map(scene => scene.id),
+				...before.scenes.filter(scene => !after.scenes.some(row => row.id === scene.id)).map(scene => scene.id),
+				...(moved ? [after.activeSceneId] : []),
+			])];
+			const result = { affectedIds, summary: describe(after, opened, moved) };
+			return moved ? ports.afterRender().then(() => result) : result;
+		} });
+	const manyScenes = state => state.scenes.length > 1;
+	sceneAction("scene.create", () => true, () => {
+		ports.addSceneDocument();
+		return (after, opened) => `Created and opened scene ${sceneName(opened)}.`;
+	});
+	sceneAction("scene.duplicate", () => true, ({ sceneId }) => {
+		const source = sceneOf(sceneId);
+		ports.duplicateSceneDocument(sceneId);
+		return (after, opened) => `Duplicated ${sceneName(source)} as ${sceneName(opened)} and opened the copy.`;
+	});
+	sceneAction("scene.rename", () => true, ({ sceneId, name }) => {
+		const source = sceneOf(sceneId);
+		ports.renameSceneDocument(sceneId, name);
+		return after => {
+			const renamed = after.scenes.find(scene => scene.id === sceneId);
+			return renamed.name === source.name ? `${sceneName(source)} already has that name; nothing changed.` : `Renamed scene ${sceneId} from ${source.name} to ${renamed.name}.`;
+		};
+	});
+	sceneAction("scene.delete", state => manyScenes(state) || "The project's last scene cannot be deleted.", ({ sceneId }) => {
+		const source = sceneOf(sceneId);
+		ports.deleteSceneDocument(sceneId);
+		return (after, opened, moved) => `Deleted scene ${sceneName(source)}${moved ? `; opened ${sceneName(opened)}` : ""}.`;
+	});
+	sceneAction("scene.switch", state => manyScenes(state) || "This project has one scene; add one with scene.create.", ({ sceneId }, before) => {
+		const target = sceneOf(sceneId);
+		if (sceneId === before.activeSceneId) return () => `${sceneName(target)} is already open; nothing changed.`;
+		ports.switchSceneDocument(sceneId);
+		return () => `Opened scene ${sceneName(target)}.`;
+	});
+}

package/src/commands/shared.js

@@ -0,0 +1,19 @@
+// Helpers the command modules share. `ports` is the editor's one generic port
+// object: its members are read at call time, so a run always reaches the
+// latest handlers and `ports.state()` the synchronously published document.
+import { StudioProtocolError } from "../studio-agent-protocol.js";
+
+export const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+
+/** Ids of the rows added, changed or removed between two renders of a list. */
+export const changedIds = (before, after) => [...new Set([
+	...after.filter(row => !before.includes(row)).map(row => row.id),
+	...before.filter(row => !after.some(next => next.id === row.id)).map(row => row.id),
+])];
+
+export const shotLabel = shot => `${shot.name} [${shot.startFrame}, ${shot.endFrame + 1})`;
+
+export const shotOf = (ports, shotId) => ports.state().shots.find(shot => shot.id === shotId) ?? fail("STALE_TARGET", `Shot ${shotId} is not in this scene.`);
+
+export const characterOf = (ports, characterId) => ports.state().characters.find(entry => entry.id === characterId)
+	?? fail("STALE_TARGET", `Character ${characterId} is not in this scene.`);