cozyclay 1.10.0 → 2.0.2

package/src/commands/cast.js

@@ -0,0 +1,140 @@
+// Cast commands: a named character's root waypoints and IK key layer. They
+// name their character explicitly, so they run the same way whichever
+// character is active and whatever mode the editor is in.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { characterOf, fail, changedIds } from "./shared.js";
+import { elementSetSchema, registerElementSet } from './elements.js';
+import './elements/character.js';
+import { createCharacterEntry } from '../scenes.js';
+import { DEFAULT_POSE } from '../poses.js';
+import { createStableItemId, updateStableItem, removeStableItem } from '../stable-items.js';
+import { movePromptClipFrames } from '../ardy/prompt-clips.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 record = { type: 'object', properties: {}, additionalProperties: true };
+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.remove', 'Remove character', input({ characterId: id })),
+	mutation('character.update', 'Update character', input({ characterId: id, patch: record })),
+	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),
+	mutation('cast.replace', 'Replace cast', input({ characters: { type: 'array', items: record, minItems: 1 } }), 'ui-only'),
+	mutation('cast.setCustomPoses', 'Set pose library', input({ poses: { type: 'array', items: record } }), 'ui-only'),
+	mutation('cast.savePose', 'Save pose', input({ pose: record, characterId: id, clearMotion: { type: 'boolean' } }, ['pose']), 'ui-only'),
+	mutation('cast.removePose', 'Remove saved pose', input({ id }), 'ui-only'),
+	mutation('cast.showExtras', 'Show extra subjects', input({ show: { type: 'boolean' } }), 'ui-only'),
+	mutation('cast.setLayer', 'Set character layer', input({ characterId: id, layer: record }), 'ui-only'),
+	...['add', 'move', 'resize', 'change', 'remove'].map(verb => mutation(`character.${verb}PromptBlock`, `${verb} prompt block`,
+		input({ characterId: id, id, frame: { type: 'number' }, edge: { type: 'string', enum: ['start', 'end'] }, text: { type: 'string', maxLength: 2000 } },
+			verb === 'add' ? ['characterId', 'frame'] : verb === 'remove' ? ['characterId', 'id'] : verb === 'change' ? ['characterId', 'id', 'text'] : verb === 'resize' ? ['characterId', 'id', 'edge', 'frame'] : ['characterId', 'id', 'frame']), 'ui-only')),
+];
+export const declarations = Object.freeze([...semantic, ...["character.addWaypoint", "character.moveWaypoint", "character.removeWaypoint", "character.clearWaypoints"].map(studioActionDeclaration)]);
+
+export function register(registry, ports) {
+	const owner = () => ports.storeDomain('cast');
+	const mounted = () => Boolean(ports.storeDomain?.('cast')) || 'The cast document owner is not mounted.';
+	const character = characterId => owner().read().find(row => row.id === characterId) ?? fail('STALE_TARGET', `Character ${characterId} is not in this scene.`);
+	const pose = value => typeof value === 'string' ? owner().poses().find(row => row.id === value) ?? fail('STALE_TARGET', `Pose ${value} is not in the library.`) : value;
+	const patch = (characterId, update) => { character(characterId); owner().write(rows => rows.map(row => row.id === characterId ? { ...row, ...update } : row)); };
+	function promptEdit(command, args) {
+		const before = character(args.characterId), clips = before.layer.promptClips;
+		let next;
+		if (command === 'character.addPromptBlock') {
+			const snapped = Math.max(0, Math.round(args.frame / 48) * 48);
+			const blocked = clips.some(clip => snapped < clip.endFrame && snapped + 48 > clip.startFrame);
+			const startFrame = blocked ? Math.max(snapped, ...clips.map(clip => clip.endFrame)) : snapped;
+			next = [...clips, { id: createStableItemId('prompt-clip'), startFrame, endFrame: startFrame + 48, text: '' }];
+		} else if (command === 'character.removePromptBlock') next = removeStableItem(clips, args.id, 'promptClips');
+		else if (command === 'character.changePromptBlock') next = updateStableItem(clips, args.id, clip => ({ ...clip, text: args.text }), 'promptClips');
+		else if (command === 'character.movePromptBlock') next = movePromptClipFrames(clips, args.id, args.frame, 48);
+		else {
+			next = updateStableItem(clips, args.id, clip => {
+				const snapped = Math.max(0, Math.round(args.frame / 48) * 48);
+				return args.edge === 'start' ? { ...clip, startFrame: Math.min(Math.max(snapped, clip.endFrame - 120), clip.endFrame - 48) }
+					: { ...clip, endFrame: Math.min(Math.max(clip.startFrame + 48, snapped), clip.startFrame + 120) };
+			}, 'promptClips');
+			const resized = next.find(clip => clip.id === args.id);
+			if (next.some(clip => clip.id !== args.id && resized.startFrame < clip.endFrame && resized.endFrame > clip.startFrame)) return;
+		}
+		patch(args.characterId, { layer: { ...before.layer, promptClips: next } });
+		owner().extendTimeline(next.reduce((end, clip) => Math.max(end, clip.endFrame), 24));
+	}
+	const methods = {
+		'character.add': ({ character: value }) => {
+			const row = createCharacterEntry({ ...value, id: value.id ?? createStableItemId('character') }, owner().read().length);
+			if (owner().read().some(entry => entry.id === row.id)) fail('INVALID_ARGUMENT', 'Character id already exists.');
+			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.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 } });
+		},
+		'cast.replace': ({ characters }) => owner().write(characters),
+		'cast.setCustomPoses': ({ poses }) => owner().writeState(before => ({ ...before, customPoses: poses })),
+		'cast.savePose': ({ pose, characterId, clearMotion }) => {
+			if (characterId) character(characterId);
+			owner().writeState(before => ({ ...before, customPoses: [...before.customPoses.filter(entry => entry.id !== pose.id), pose] }));
+			if (characterId) owner().applyPose(characterId, pose, clearMotion);
+		},
+		'cast.removePose': ({ id }) => owner().writeState(before => ({
+			characters: before.characters.map(entry => entry.pose?.id === id ? { ...entry, pose: DEFAULT_POSE } : entry),
+			customPoses: before.customPoses.filter(entry => entry.id !== id),
+		})),
+
+		'cast.showExtras': ({ show }) => owner().showExtras(show),
+		'cast.setLayer': ({ characterId, layer }) => patch(characterId, { layer: { ...character(characterId).layer, ...layer } }),
+	};
+	registerElementSet({ register(entry) {
+		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];
+			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]);
+			for (const selected of poses) owner().applyPose(selected.id, selected.value, false);
+			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.' }; }
+		const before = owner().read();
+		if (declaration.id.endsWith('PromptBlock')) promptEdit(declaration.id, args); else methods[declaration.id](args);
+		const changed = changedIds(before, owner().read());
+		return { affectedIds: changed.length ? changed : [args.characterId ?? ports.state().activeSceneId], summary: declaration.label };
+	} });
+	if (ports.storeDomain?.('cast')) registry.registerToolAlias('arrange_characters', 'characters.arrange');
+	const castAction = (id, run) => registry.register({ ...studioActionDeclaration(id),
+		available: state => state.characters.length > 0 || "There are no characters in this scene; add one with arrange_characters.",
+		run: args => {
+			const character = characterOf(ports, args.characterId);
+			return { affectedIds: [character.id], summary: run(args, character.subject || character.id) };
+		} });
+	const pin = waypoint => `frame ${waypoint.frame} (x ${waypoint.x}, z ${waypoint.z})`;
+	const warned = warnings => warnings.length ? `; warning: ${warnings[0]}` : "";
+	castAction("character.addWaypoint", ({ characterId, position, frame }, name) => {
+		const { waypoint, index, warnings } = ports.addCharacterWaypoint(characterId, position, frame ?? null);
+		ports.setWaypointMode(true);
+		return `Added ${name}'s root waypoint ${index + 1} at ${pin(waypoint)}${warned(warnings)}.`;
+	});
+	castAction("character.moveWaypoint", ({ characterId, frame, position }, name) => {
+		const { waypoint, warnings } = ports.moveCharacterWaypoint(characterId, frame, position);
+		ports.setWaypointMode(true);
+		return `Moved ${name}'s root waypoint to ${pin(waypoint)}${warned(warnings)}.`;
+	});
+	castAction("character.removeWaypoint", ({ characterId, frame }, name) => {
+		ports.removeCharacterWaypoint(characterId, frame);
+		return `Removed ${name}'s root waypoint at frame ${frame}.`;
+	});
+	castAction("character.clearWaypoints", ({ characterId }, name) => {
+		const count = ports.clearCharacterWaypoints(characterId);
+		return count ? `Cleared ${name}'s root path (${count} waypoint${count === 1 ? "" : "s"}).` : `${name} has no root waypoints; nothing changed.`;
+	});
+}

package/src/commands/elements/character.js

@@ -0,0 +1,13 @@
+import { createCharacterEntry } from '../../scenes.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('character.')).map(row => {
+  const { min, max, gizmo, ...element } = row;
+  if (row.path === 'character.position') return { ...element, documentPath: { x: 'x', y: 'y', z: 'z' } };
+  if (row.path === 'character.promptBlocks') return { ...element, documentPath: 'layer.promptClips' };
+  if (row.path === 'character.pose') return { ...element, readback: item => ({ text: item?.pose?.id ?? null }) };
+  return element;
+});
+registerElementKind('character', { collection: true, documentKey: 'characters', elements, normalize: createCharacterEntry });
+registerElementKind('poseLibrary', { collection: true, documentKey: 'customPoses', elements: [], normalize: value => value });

package/src/commands/elements/motion.js

@@ -0,0 +1,14 @@
+import { registerElementKind } from '../elements.js';
+import { wrapAngle } from '../../scene-objects.js';
+
+const elements = [
+  ...['anchorX', 'anchorZ', 'rotationDeg'].map(field => ({ path: `motion.take.${field}`, type: 'number' })),
+  { path: 'motion.take.prompt', type: 'string' },
+  { path: 'motion.ikKeys', type: 'array', readOnly: true },
+  { path: 'motion.takeRecipe', type: 'object', readOnly: true },
+  { path: 'motion.takeVersions', type: 'array', readOnly: true },
+];
+registerElementKind('motion', { collection: true, elements, normalize: row => ({ ...row, take: row.take && { ...row.take,
+  anchorX: Math.max(-240, Math.min(240, row.take.anchorX ?? 0)), anchorZ: Math.max(-240, Math.min(240, row.take.anchorZ ?? 0)),
+  rotationDeg: wrapAngle(row.take.rotationDeg ?? 0),
+} }) });

package/src/commands/elements/object.js

@@ -0,0 +1,22 @@
+import { normalizeSceneObject } from '../../scene-objects.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const components = {
+  position: { x: 'x', y: 'y', z: 'z' },
+  rotation: { x: 'rotX', y: 'rot', z: 'rotZ' },
+  scale: { x: 'scaleX', y: 'scaleY', z: 'scaleZ' },
+};
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('object.')).map(row => {
+  // Wire validation checks finite numbers; persistence owns the transform clamps.
+  const { min, max, ...element } = row;
+  const field = row.path.slice(7);
+  return { ...element, ...(components[field] ? { documentPath: components[field] } : {}),
+    ...(field === 'remove' ? { readback: item => ({ flag: item === undefined }) } : {}) };
+});
+export function normalizeObjectSet(record) {
+  const item = normalizeSceneObject(record);
+  // The owning collection consumes this lifecycle intent before persistence.
+  return record.remove === true ? { ...item, remove: true } : item;
+}
+registerElementKind('object', { collection: true, documentKey: 'objects', elements, normalize: normalizeObjectSet });

package/src/commands/elements/scene.js

@@ -0,0 +1,16 @@
+import { registerElementKind } from '../elements.js';
+
+// Array position is the authoritative order. The owner refreshes this persisted
+// field after every move, so generic set/read and the project file agree.
+registerElementKind('scene', {
+  collection: true, documentKey: 'scenes',
+  elements: [
+    { path: 'scene.name', type: 'string' },
+    { path: 'scene.order', type: 'number' },
+  ],
+  normalize: scene => ({ ...scene, name: scene.name.trim(), order: Math.max(0, Math.round(scene.order)) }),
+});
+registerElementKind('project', {
+  elements: [{ path: 'project.name', type: 'string' }],
+  normalize: project => project,
+});

package/src/commands/elements/shot.js

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

package/src/commands/elements/stage.js

@@ -0,0 +1,11 @@
+import { createSceneStage } from '../../scenes.js';
+import { STUDIO_ELEMENTS } from '../../studio-elements.js';
+import { registerElementKind } from '../elements.js';
+
+const elements = STUDIO_ELEMENTS.filter(row => row.path.startsWith('stage.'));
+export const STAGE_FIELDS = [...new Set(elements.map(element => (element.documentPath ?? element.path.slice(6)).split('.')[0]))];
+export function normalizeStage(source) {
+  const normalized = createSceneStage(source);
+  return Object.fromEntries(STAGE_FIELDS.map(key => [key, normalized[key]]));
+}
+registerElementKind('stage', { elements, normalize: normalizeStage });

package/src/commands/elements.js

@@ -0,0 +1,155 @@
+// Shared set/read machinery. Domain modules supply only their kind, declared
+// fields and persistence normalizer; no UI or runtime resources live here.
+import { patchValueSchema, validateStudioSchema, StudioProtocolError, StudioSchemas, utf8ByteLength } from '../studio-agent-protocol.js';
+
+import { isSettableElement } from '../studio-elements.js';
+
+const kinds = new Map();
+// Each kind registers its declared elements and persistence normalizer once.
+// Its command port supplies read()/write(); all schemas and path aliases use
+// this same spec so a migration adds a module, not another generic switch.
+export function registerElementKind(kind, spec) {
+  if (kinds.has(kind)) throw new Error(`Element kind already registered: ${kind}`);
+  kinds.set(kind, { documentKey: kind, ...spec });
+}
+const projectionKind = key => [...kinds].find(([, spec]) => spec.documentKey === key)?.[0] ?? key;
+const patchElements = kind => kinds.get(kind).elements.filter(isSettableElement);
+const object = () => ({ type: 'object', properties: {}, required: [], additionalProperties: false });
+// String mappings retain the single-document schema. Component mappings use
+// the logical field in set args and fan out only at the storage boundary.
+const setPath = element => typeof element.documentPath === 'string' ? element.documentPath : element.path.slice(element.path.indexOf('.') + 1);
+const atPath = (value, path) => path.split('.').reduce((value, key) => value?.[key], value);
+const nestedValue = (path, value) => path.split('.').reduceRight((value, key) => ({ [key]: value }), value);
+export function elementSetSchema(kind) {
+  const schema = object();
+  for (const element of patchElements(kind)) {
+    const keys = setPath(element).split('.');
+    let parent = schema;
+    for (const key of keys.slice(0, -1)) parent = parent.properties[key] ??= object();
+    // Validate the wire type here; persistence owns numeric clamps. Empty
+    // strings are valid authored text, including intermediate typing states.
+    const value = element.type === 'number' ? { type: 'number' }
+      : element.type === 'string' ? { oneOf: [{ const: '' }, { type: 'string', maxLength: 240 }] } : patchValueSchema(element);
+    parent.properties[keys.at(-1)] = element.nullable ? { oneOf: [value, { type: 'null' }] } : value;
+  }
+  if (!kinds.get(kind).collection) return schema;
+  // A single item is { id, set }; a batch is { ops: [{ id, set }] }.
+  // Both forms publish once and therefore own exactly one history entry.
+  const item = { ...object(), properties: { id: StudioSchemas.TargetGuard.properties.targetId, set: schema }, required: ['id', 'set'] };
+  const batch = { ...object(), properties: { ops: { type: 'array', items: item, minItems: 1, maxItems: 32 } }, required: ['ops'] };
+  return { ...object(), properties: { ...item.properties, ...batch.properties }, oneOf: [item, batch] };
+}
+export function elementTarget(kind, value, id, sceneId) {
+  return kinds.get(projectionKind(kind)).collection ? value.find(row => row.id === id) : id === sceneId ? value : undefined;
+}
+export function readElementDocument(projection, { ids, select } = {}, sceneId) {
+  const entries = Object.entries(projection).flatMap(([key, value]) => {
+    const kind = projectionKind(key);
+    if (select && !select.includes(key) && !select.includes(kind)) return [];
+    if (!ids || ids.includes(key) || ids.includes(kind) || ids.includes(sceneId)) return [[key, value]];
+    const selected = kinds.get(kind).collection ? value.filter(row => ids.includes(row.id)) : [];
+    return selected.length ? [[key, selected]] : [];
+  });
+  return { document: structuredClone(Object.fromEntries(entries)), schema: Object.fromEntries(entries.map(([key]) => [key, elementSetSchema(projectionKind(key))])) };
+}
+export function readElement(document, path) {
+  const element = kinds.get(path.slice(0, path.indexOf('.'))).elements.find(row => row.path === path);
+  return element.documentPath && typeof element.documentPath === 'object'
+    ? Object.fromEntries(Object.entries(element.documentPath).map(([component, stored]) => [component, atPath(document, stored)]))
+    : atPath(document, setPath(element));
+}
+export 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)
+    ? mergeElementSet(document[key], value) : value;
+  return next;
+}
+function storedElementSet(kind, patch) {
+  let stored = mergeElementSet({}, patch);
+  for (const element of patchElements(kind)) {
+    if (!element.documentPath || typeof element.documentPath !== 'object') continue;
+    const value = atPath(patch, setPath(element));
+    if (value === undefined) continue;
+    const keys = setPath(element).split('.');
+    const parent = keys.slice(0, -1).reduce((value, key) => value[key], stored);
+    delete parent[keys.at(-1)];
+    for (const [component, path] of Object.entries(element.documentPath)) stored = mergeElementSet(stored, nestedValue(path, value[component]));
+  }
+  return stored;
+}
+export function elementPatchArgs(kind, args) {
+  const set = { ...object(), additionalProperties: true };
+  const collection = kinds.get(kind).collection;
+  const target = { ...object(), properties: { kind: { const: kind }, ...(collection ? { id: StudioSchemas.TargetGuard.properties.targetId } : {}) }, required: collection ? ['kind', 'id'] : ['kind'] };
+  const op = { ...object(), properties: { target, set }, required: ['target', 'set'] };
+  const schema = { ...object(), properties: { ops: { type: 'array', items: op, minItems: 1, maxItems: 32 } }, required: ['ops'] };
+  const validated = validateStudioSchema(schema, args);
+  const ops = validated.ops.map(({ target, set }) => {
+    let patch = {};
+    for (const [key, value] of Object.entries(set)) {
+      const element = patchElements(kind).find(row => row.path === `${kind}.${key}`);
+      if (!element) throw new StudioProtocolError('INVALID_ARGUMENT', `Unknown ${kind} path: ${key}`);
+      const nested = nestedValue(setPath(element), value);
+      patch = mergeElementSet(patch, nested);
+    }
+    return { id: target.id, set: patch };
+  });
+  return collection ? ops.length === 1 ? ops[0] : { ops } : ops.reduce((patch, op) => mergeElementSet(patch, op.set), {});
+}
+export function elementReadback(kind, item, paths, document) {
+  return patchElements(projectionKind(kind)).filter(element => !paths || paths.includes(element.path)).map(element => {
+    const path = element.path;
+    if (element.readback) return { path, ...element.readback(item, document) };
+    const value = readElement(item, path);
+    if (value === null || value === undefined || value === '') return { path, text: null };
+    if (element.type === 'image') return { path, bytes: utf8ByteLength(value) };
+    if (element.type === 'vec3') return { path, vec: value };
+    if (element.type === 'array') return { path, count: Array.isArray(value) ? value.length : value.points?.length ?? 0 };
+    return { path, [typeof value === 'number' ? 'number' : typeof value === 'boolean' ? 'flag' : 'text']: value };
+  });
+}
+// Normalizer-added defaults are allowed; changed/clamped requested members
+// are reported as dropped, just like the native patch planners.
+function survives(requested, actual) {
+  if (requested === null || typeof requested !== 'object') return requested === actual;
+  if (Array.isArray(requested)) return Array.isArray(actual) && requested.length === actual.length && requested.every((value, index) => survives(value, actual[index]));
+  return actual !== null && typeof actual === 'object' && !Array.isArray(actual) && Object.entries(requested).every(([key, value]) => survives(value, actual[key]));
+}
+export function elementPatchReceipt(receipt, request, projection) {
+  const kind = request?.args.ops[0].target.kind;
+  if (!receipt.ok || !kind || !kinds.get(kind).collection) return receipt;
+  const value = projection[kinds.get(kind).documentKey];
+  const ops = request.args.ops.map(({ target, set }, index) => {
+    const item = elementTarget(kind, value, target.id, receipt.host.sceneId);
+    const droppedPaths = Object.entries(set).filter(([key, requested]) => {
+      const element = patchElements(kind).find(element => element.path === `${kind}.${key}`);
+      return !element.readback && !survives(requested, readElement(item, element.path));
+    }).map(([key]) => `${kind}.${key}`);
+    return { index, status: droppedPaths.length ? 'partial' : receipt.authored ? 'applied' : 'noop', ...(droppedPaths.length ? { droppedPaths } : {}) };
+  });
+  const partial = receipt.authored && ops.some(op => op.status === 'partial');
+  // The protocol's partial variant is a patch receipt, not an action receipt.
+  const { action, summary, ...base } = receipt;
+  return { ...(partial ? base : receipt), ops, status: partial ? 'partial' : receipt.status,
+    delta: !receipt.authored ? [] : request.args.ops.slice(0, 8).map(({ target, set }) => ({ id: target.id, after: {
+      patched: elementReadback(kind, elementTarget(kind, value, target.id, receipt.host.sceneId), Object.keys(set).map(key => `${kind}.${key}`), value),
+    } })) };
+}
+export function registerElementSet(registry, ports, declaration) {
+  const kind = declaration.id.slice(0, declaration.id.indexOf('.'));
+  const { normalize, collection } = kinds.get(kind);
+  registry.register({ ...declaration, available: () => true, run(args) {
+    const domain = ports.storeDomain(declaration.undoDomain ?? kind);
+    let next = domain.read();
+    const ops = collection ? args.ops ?? [args] : [{ id: ports.state().activeSceneId, set: args }];
+    for (const { id, set } of ops) {
+      const before = collection ? next.find(row => row.id === id) : next;
+      if (!before) throw new StudioProtocolError('TARGET_NOT_READY', `Unknown ${kind} id: ${id}`);
+      const after = normalize(mergeElementSet(before, storedElementSet(kind, set)));
+      next = collection ? next.map(row => row.id === id ? { ...after, id } : row) : after;
+    }
+    if (JSON.stringify(next) !== JSON.stringify(domain.read())) domain.write(next);
+    return { affectedIds: [...new Set(ops.map(op => op.id))], summary: `Updated ${kind}.` };
+  } });
+}

package/src/commands/export.js

@@ -0,0 +1,20 @@
+// Export commands: the Export menu's Video (mp4), the same export, awaited to
+// its file. A failure was already shown in the export panel, so it refuses
+// silently.
+import { studioActionDeclaration } from "../studio-actions.js";
+import { fail, shotLabel, shotOf } from "./shared.js";
+
+export const declarations = Object.freeze(["export.shotVideo"].map(studioActionDeclaration));
+
+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) => {
+			const shot = shotId ? shotOf(ports, shotId) : null;
+			const result = await ports.exportShotVideo({ shotId: shotId ?? null }, 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.` };
+		} });
+}

package/src/commands/index.js

@@ -0,0 +1,40 @@
+// The editor's Studio actions: ONE registry whose entries call the same
+// handlers the UI controls call, so a timeline button and the agent's
+// run_action share one code path. Each command module registers its own
+// actions over `ports`, the one generic port object App refreshes on every
+// render; `ports.state()` reads the synchronously published document, so an
+// action sees its own edit at once.
+import { createStudioActionRegistry, STUDIO_ACTIONS } from "../studio-actions.js";
+import * as shot from "./shot.js";
+import * as cast from "./cast.js";
+import * as motion from "./motion.js";
+import * as objects from "./objects.js";
+import * as view from "./view.js";
+import * as scene from "./scene.js";
+import * as project from "./project.js";
+import * as exporting from "./export.js";
+import * as ai from "./ai.js";
+import * as stage from "./stage.js";
+
+export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, objects, view, scene, project, export: exporting, ai, stage });
+
+export function commandDeclarations(modules = COMMAND_MODULES) {
+	return Object.values(modules).flatMap(module => module.declarations.map(declaration => ({
+		...STUDIO_ACTIONS.find(entry => entry.id === declaration.id), ...declaration,
+	})));
+}
+
+export function createStudioAppActions(ports, modules = COMMAND_MODULES) {
+	const registry = createStudioActionRegistry({ readState: () => ports.state() });
+	const declarations = new Map(commandDeclarations(modules).map(entry => [entry.id, entry]));
+	const register = registry.register;
+	registry.register = entry => register({ ...entry, ...declarations.get(entry.id) });
+	const aliases = new Map();
+	registry.registerToolAlias = (tool, action, args = value => value) => {
+		if (aliases.has(tool)) throw new Error(`Tool alias already registered: ${tool}`);
+		aliases.set(tool, { action, args });
+	};
+	registry.toolAlias = tool => aliases.get(tool);
+	for (const module of Object.values(modules)) module.register(registry, ports);
+	return registry;
+}