cozyclay 1.9.0 → 2.0.0

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;
+}

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}).` };
+		} });
+}