cozyclay 2.1.1 → 3.0.1

package/src/commands/elements/motion.js

@@ -1,14 +1,9 @@
 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),
-} }) });
+registerElementKind('motion', { collection: true, elements, normalize: row => ({ ...row, take: row.take && { ...row.take } }) });

package/src/commands/elements/object.js

@@ -1,4 +1,4 @@
-import { normalizeSceneObject } from '../../scene-objects.js';
+import { normalizeSceneObject, updateSceneObject } from '../../scene-objects.js';
 import { STUDIO_ELEMENTS } from '../../studio-elements.js';
 import { registerElementKind } from '../elements.js';
 
@@ -19,4 +19,8 @@ function normalizeObjectSet(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 });
+// A set that moves or turns a record carries its descendants exactly as object.update, the
+// inspector and the gizmo do (updateSceneObject): rigidly about the record's pivot, scale not carried.
+const TRANSFORM = ['x', 'y', 'z', 'rotX', 'rot', 'rotZ'];
+const carryDescendants = (rows, id, after) => after ? updateSceneObject(rows, id, Object.fromEntries(TRANSFORM.map(key => [key, after[key]]))) : rows;
+registerElementKind('object', { collection: true, documentKey: 'objects', elements, normalize: normalizeObjectSet, carry: carryDescendants });

package/src/commands/elements/shot.js

@@ -1,3 +1,4 @@
+import { cameraKeyWarnings } from '../../camera-direction.js';
 import { createShotAuthoringDocument } from '../../shot-authoring.js';
 import { STUDIO_ELEMENTS } from '../../studio-elements.js';
 import { registerElementKind } from '../elements.js';
@@ -5,5 +6,7 @@ import { registerElementKind } from '../elements.js';
 function normalizeShot(record) {
   return createShotAuthoringDocument({ shots: [record], frameCount: Math.max(24, record.endFrame + 1) }).shots[0];
 }
+// A shot.set that writes camera keys hears when they halt the move, like frame_shot does.
 registerElementKind('shot', { collection: true, documentKey: 'shots',
-  elements: STUDIO_ELEMENTS.filter(row => row.path.startsWith('shot.')), normalize: normalizeShot });
+  elements: STUDIO_ELEMENTS.filter(row => row.path.startsWith('shot.')), normalize: normalizeShot,
+  warn: (shot, set) => (Object.hasOwn(set, 'cameraKeys') ? cameraKeyWarnings(shot) : []) });

package/src/commands/elements.js

@@ -97,24 +97,34 @@ export function elementPatchArgs(kind, args) {
   });
   return collection ? ops.length === 1 ? ops[0] : { ops } : ops.reduce((patch, op) => mergeElementSet(patch, op.set), {});
 }
+// Unasked, an optional structured value (a glow, a light) is listed only where
+// the item has one, so every plain object's receipt stays as short as before.
+const listed = (element, item, paths) => paths ? paths.includes(element.path) : element.type !== 'object' || readElement(item, element.path) != null;
 export function elementReadback(kind, item, paths, document) {
-  return patchElements(projectionKind(kind)).filter(element => !paths || paths.includes(element.path)).map(element => {
+  return patchElements(projectionKind(kind)).filter(element => listed(element, item, paths)).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) };
+    // A small structured value (a light, a glow) reads back whole, as compact JSON.
+    if (element.type === 'object') return { path, text: JSON.stringify(value).slice(0, 512) };
     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) {
+// are reported as dropped, just like the native patch planners. A number that
+// landed within float noise (a wrap leaves -17.529999999999973 for -17.53),
+// or an angle that landed one or more whole turns away (190 kept as -170), survives.
+const turn = (delta, angle) => angle ? delta - 360 * Math.round(delta / 360) : delta;
+function survives(requested, actual, angle = false) {
+  if (typeof requested === 'number' && typeof actual === 'number') return requested === actual
+    || Math.abs(turn(requested - actual, angle)) <= 1e-9 * Math.max(1, Math.abs(requested), Math.abs(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]));
+  if (Array.isArray(requested)) return Array.isArray(actual) && requested.length === actual.length && requested.every((value, index) => survives(value, actual[index], angle));
+  return actual !== null && typeof actual === 'object' && !Array.isArray(actual) && Object.entries(requested).every(([key, value]) => survives(value, actual[key], angle));
 }
 export function elementPatchReceipt(receipt, request, projection) {
   const kind = request?.args.ops[0].target.kind;
@@ -124,32 +134,46 @@ export function elementPatchReceipt(receipt, request, projection) {
     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));
+      return !element.readback && !survives(requested, readElement(item, element.path), element.angle === true);
     }).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;
+  // A dropped path makes the receipt "partial" whenever it published one revision: an applied
+  // patch, or one inside an agent turn (which the bus answers "completed"). A composite that moved
+  // the revision further stays "completed", and its ops name the dropped paths.
+  const partial = receipt.authored && ops.some(op => op.status === 'partial') && receipt.revision.after === receipt.revision.before + 1 && !receipt.nextHost;
+  // The protocol's partial variant is a patch receipt, not an action or composite receipt.
+  const { action, summary, kind: composite, ...base } = receipt;
+  // A row the edit carried along (a moved group's part) reads back where it went: its vec3 transform paths.
+  const targets = new Set(request.args.ops.map(({ target }) => target.id));
+  const moved = patchElements(kind).filter(element => element.type === 'vec3').map(element => element.path);
+  const carried = receipt.affectedIds.filter(id => !targets.has(id) && elementTarget(kind, value, id, receipt.host.sceneId)).map(id => ({ id, paths: moved }));
   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),
-    } })) };
+    delta: !receipt.authored ? [] : [...request.args.ops.map(({ target, set }) => ({ id: target.id, paths: Object.keys(set).map(key => `${kind}.${key}`) })), ...carried]
+      .slice(0, 8).map(({ id, paths }) => ({ id, after: { patched: elementReadback(kind, elementTarget(kind, value, id, receipt.host.sceneId), paths, value) } })) };
 }
 export function registerElementSet(registry, ports, declaration) {
   const kind = declaration.id.slice(0, declaration.id.indexOf('.'));
-  const { normalize, collection } = kinds.get(kind);
+  const { normalize, collection, carry, warn } = 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 }];
+    const carried = new Set(), warnings = [];
     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)));
+      if (warn) warnings.push(...warn({ ...after, id }, set));
+      // A kind whose rows hang off each other (a group's parts) moves the rows its target carries.
+      if (collection && carry) {
+        const rows = carry(next, id, after);
+        rows.forEach((row, index) => { if (row !== next[index] && row.id !== id) carried.add(row.id); });
+        next = rows;
+      }
       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}.` };
+    return { affectedIds: [...new Set([...ops.map(op => op.id), ...carried])], summary: `Updated ${kind}.`, ...(warnings.length ? { warnings } : {}) };
   } });
 }

package/src/commands/index.js

@@ -8,6 +8,7 @@ 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 motion3 from "./motion3.js";
 import * as objects from "./objects.js";
 import * as view from "./view.js";
 import * as scene from "./scene.js";
@@ -15,8 +16,9 @@ import * as project from "./project.js";
 import * as exporting from "./export.js";
 import * as ai from "./ai.js";
 import * as stage from "./stage.js";
+import * as kits from "./kits.js";
 
-export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, objects, view, scene, project, export: exporting, ai, stage });
+export const COMMAND_MODULES = Object.freeze({ shot, cast, motion, motion3, objects, kits, view, scene, project, export: exporting, ai, stage });
 
 export function commandDeclarations(modules = COMMAND_MODULES) {
 	return Object.values(modules).flatMap(module => module.declarations.map(declaration => ({

package/src/commands/kits.js

@@ -0,0 +1,37 @@
+// object.createKit: a ready-made prop (src/kits/) built as one group, an Empty root at the grip
+// plus its parts, written as one undo entry. It is a job so the answer carries its output:
+// { rootId, parts: { role: id }, bind, props?, skill? }. bind is the spec.objects snippet a take
+// pastes: the root's carry (at/along pin it to the prop origin) and the switch entries of the
+// parts that light up (docs/motion-api-v3.1.md C15).
+import { buildKit, KIT_NAMES } from "../kits/index.js";
+import { fail } from "./shared.js";
+
+const KIT_HELP = `Create a ready-made, correctly scaled prop as one group (an Empty root at the grip plus its parts), one undo entry. kit: ${KIT_NAMES.join(", ")} (inspect_studio scope catalogue lists each with its parts). `
+	+ "position { x, y, z, rot? } places the root (world m, yaw degrees; default the origin, lifted so nothing is under the floor); name names the root. "
+	+ "Answers rootId, parts { role: id } and bind: the spec.objects snippet to paste into a motion spec (the root's carry: prop, at, along, plus switch entries { visible, level } that show the lit parts). "
+	+ "Kits without a skill also answer props (the grip prop to paste into spec.props). The cigarette, lighter and exhale need no paste: smokeCigarette args.kit { cig, lighter, exhale? } adds the entries itself "
+	+ "(exhale: a puff that follows the mouth, no placing). "
+	+ "Example: { kit: \"cigarette\" } -> { rootId: \"empty-3\", parts: { body: \"sculpt-2\", ember: \"sphere\", light: \"point-light\", smoke: \"effect\" }, bind: { \"empty-3\": { prop: \"cig\", at: [0, 0, 0], along: [0, 0, 1], visible: \"cig_vis\" }, "
+	+ "sphere: { visible: \"ember_vis\", level: \"ember\" }, \"point-light\": { visible: \"ember_vis\", level: \"ember\" }, effect: { visible: \"ember_vis\" } } }; "
+	+ "then motion.compile use [{ skill: \"smokeCigarette\", f0: 0, args: { kit: { cig: \"empty-3\", lighter: \"<lighter rootId>\" } } }].";
+
+const number = { type: "number" };
+const input = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required, additionalProperties: false });
+
+export const declarations = Object.freeze([
+	{ id: "object.createKit", label: "Create a prop kit", kind: "job", domain: "objects", description: KIT_HELP,
+		input: input({ kit: { type: "string", enum: KIT_NAMES }, name: { type: "string", minLength: 1, maxLength: 120 }, position: input({ x: number, y: number, z: number, rot: number }, []) }, ["kit"]) },
+]);
+
+export function register(registry, ports) {
+	const owned = () => ports.storeDomain("objects");
+	const available = () => Boolean(ports.storeDomain?.("objects")) || "The objects document owner is not mounted.";
+	registry.register({ ...declarations[0], available, run({ kit, name, position }, context) {
+		const before = owned().read(), built = buildKit(kit, before, { name, position });
+		if (built.error) fail("INVALID_ARGUMENT", built.error);
+		const write = () => owned().write([...before, ...built.records]);
+		if (context?.commit) context.commit(write); else write();
+		const { records, ...output } = built, ids = records.map(row => row.id);
+		return { affectedIds: ids, output, summary: `Created the ${kit} kit ${built.rootId} (${Object.entries(built.parts).map(([role, id]) => `${role} ${id}`).join(", ")}).` };
+	} });
+}

package/src/commands/motion-timing.js

@@ -0,0 +1,57 @@
+// Timing edits on an installed take (take-edit.js): cut it into segments, play a segment faster
+// or slower, drop one, trim the ends, or restore the full take. The compiled take stays as it
+// is; the edit rides its descriptor, so Undo, save/load and export all see the same timing.
+// IK correction keys pinned to timeline frames move with the poses they address.
+import { fail, characterOf } from "./shared.js";
+import { createTakeEdit, isIdentityEdit, remapFrameKeys, removeSegment, setSegmentSpeed, splitTakeEdit, takeEditDuration, takeEditLayout, trimTakeEdit } from "../motion3/take-edit.js";
+
+const id = { type: "string", minLength: 1 }, frame = { type: "integer", minimum: 0 };
+const timing = (actionId, label, description, properties) => ({ id: actionId, label, description, kind: "mutation", undoDomain: "motion",
+	input: { type: "object", properties: { characterId: id, ...properties }, required: ["characterId", ...Object.keys(properties)], additionalProperties: false } });
+const SEGMENTS = "The receipt output lists the segments ({ id, sourceStart, sourceEnd, speed, timelineStart, timelineEnd }) and the new frame count.";
+
+export const timingDeclarations = [
+	timing("motion.cut", "Cut motion segment", `Cut the installed take into two segments at a timeline frame, so each part can get its own speed. ${SEGMENTS}`, { frame }),
+	timing("motion.setSegmentSpeed", "Set segment speed", `Play one segment faster or slower: 0.1-4 in 0.1 steps (0.5 = half-speed slow motion, 2 = double speed). The timeline grows or shrinks with it. ${SEGMENTS}`,
+		{ segmentId: id, speed: { type: "number", minimum: 0.1, maximum: 4 } }),
+	timing("motion.removeSegment", "Remove motion segment", `Drop one segment from the take; the rest close the gap. ${SEGMENTS}`, { segmentId: id }),
+	timing("motion.trim", "Trim motion", `Keep timeline frames start..end (inclusive) of the take. ${SEGMENTS}`, { start: frame, end: frame }),
+	timing("motion.resetTiming", "Restore full take timing", `Undo every cut, speed change and trim: the take plays as compiled. ${SEGMENTS}`, {}),
+];
+
+/** The take descriptor with this edit; an identity edit leaves no key (authored intent stays plain). */
+function withEdit(take, edit, frames) {
+	const next = { ...take };
+	delete next.edit;
+	return isIdentityEdit(edit, frames) ? next : { ...next, edit };
+}
+
+function nextEdit(action, edit, args, frames) {
+	const known = () => edit.some(segment => segment.id === args.segmentId) || fail("INVALID_ARGUMENT", `No segment ${args.segmentId}; segments: ${edit.map(segment => segment.id).join(", ")}.`);
+	if (action === "motion.cut") {
+		const next = splitTakeEdit(edit, args.frame);
+		return next !== edit ? next : fail("INVALID_RANGE", `Frame ${args.frame} is not inside a segment (0 < frame < ${takeEditDuration(edit)}, not on a segment start).`);
+	}
+	if (action === "motion.setSegmentSpeed") { known(); return setSegmentSpeed(edit, args.segmentId, args.speed); }
+	if (action === "motion.removeSegment") { known(); return edit.length > 1 ? removeSegment(edit, args.segmentId) : fail("INVALID_ARGUMENT", "Use motion.clear to remove the last segment."); }
+	if (action === "motion.trim") {
+		try { return trimTakeEdit(edit, args.start, args.end); } catch (error) { return fail("INVALID_RANGE", error.message); }
+	}
+	return createTakeEdit(frames);
+}
+
+export function registerTiming(registry, ports, available) {
+	const owner = () => ports.storeDomain("motion");
+	for (const declaration of timingDeclarations) registry.register({ ...declaration, available, run(args) {
+		const { characterId } = args;
+		characterOf(ports, characterId);
+		const row = owner().layer(characterId), full = owner().fullMotionFor(characterId);
+		if (!row.take || !full) fail("TARGET_NOT_READY", "Load a take for this character first.");
+		const previous = row.take.edit ?? createTakeEdit(full.frames), edit = nextEdit(declaration.id, previous, args, full.frames);
+		if (edit !== previous) {
+			owner().writeLayer(characterId, { take: withEdit(row.take, edit, full.frames), ikKeys: remapFrameKeys(row.ikKeys, previous, edit) });
+			ports.storeDomain("cast")?.syncTimeline?.();
+		}
+		return { affectedIds: [characterId], summary: declaration.label, output: { frames: takeEditDuration(edit), segments: takeEditLayout(edit) } };
+	} });
+}

package/src/commands/motion.js

@@ -2,16 +2,11 @@
 import { STUDIO_IK_CHAIN_TRACKS, studioActionDeclaration } from "../studio-actions.js";
 import { fail, characterOf } from "./shared.js";
 import { elementSetSchema, registerElementSet } from './elements.js';
+import { registerTiming, timingDeclarations } from './motion-timing.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
@@ -26,108 +21,28 @@ 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 edits = [{ ...mutation('motion.set', 'Set take fields', {}), input: setInput }];
 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, prompt blocks and take-owned cast fields.',
+const clear = { id: 'motion.clear', label: 'Clear motion', description: 'Clear the character\'s compiled take and its IK corrections.',
 	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 const declarations = Object.freeze([...tools, ...rangePins, ...edits, ...timingDeclarations, ...legacyIk, ...ik, clear]);
 
 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);
-		}
+		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) {
@@ -137,37 +52,11 @@ export function register(registry, ports) {
 			: 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 };
-	} });
+	registerTiming(registry, ports, mounted);
 	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;
@@ -194,38 +83,6 @@ export function register(registry, ports) {
 				if (ports.state().activeCharacterId !== characterId) fail('TARGET_NOT_READY', 'Select this character before clearing its take.');
 				ports.clearMotionNative();
 			}
-			return { affectedIds: [characterId], summary: 'Cleared motion and prompt blocks.' };
-		} });
-	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.` };
+			return { affectedIds: [characterId], summary: 'Cleared motion.' };
 		} });
 }

package/src/commands/motion3-compile.js

@@ -0,0 +1,65 @@
+// Where a motion compile runs. In the browser: one module Web Worker (motion3/compile-worker.js), started
+// on the first compile and reused, jobs answered in arrival order, so a compile costs the worker's time
+// and never blocks the viewport (the main thread runs the compiler ~4x slower and freezes while it does).
+// Where there is no Worker (Node, tests) or the worker fails: the same job on the calling thread,
+// synchronously, so `registry.run("motion.compile", ...)` there still answers at once. The answer is the
+// same either way (compile-job.js runs the same code on the same plain inputs).
+import { runCompileJob } from "../motion3/compile-job.js";
+import { StudioProtocolError } from "../studio-agent-protocol.js";
+
+/** A job error (or a worker's serialized one) as the Studio's protocol error when it carries a code. */
+function rethrow(error) {
+	if (error?.code && !(error instanceof StudioProtocolError)) throw new StudioProtocolError(error.code, error.message);
+	if (error instanceof Error) throw error;
+	throw Object.assign(new Error(error?.message ?? String(error)), { name: error?.name ?? "Error" });
+}
+const local = job => { try { return runCompileJob(job); } catch (error) { return rethrow(error); } };
+
+/** The browser's module worker, or null where there is none. */
+function browserWorker() {
+	if (typeof Worker !== "function") return null;
+	return new Worker(new URL("../motion3/compile-worker.js", import.meta.url), { type: "module", name: "motion-compile" });
+}
+
+/**
+ * createCompileRunner({ spawn }) -> { run(job) -> answer | Promise<answer>, takeWarning() -> string | null }
+ * spawn() -> a Worker-like object (postMessage, onmessage, onerror, terminate) or null for the calling thread.
+ */
+export function createCompileRunner({ spawn = browserWorker } = {}) {
+	let worker, dead = false, warning = null, next = 0;
+	const pending = new Map();
+	/** The worker failed (would not start, or crashed): every job from now on, and those in flight, run here. */
+	const fallBack = reason => {
+		dead = true;
+		worker?.terminate?.();
+		worker = null;
+		warning ??= `The motion compile worker stopped (${reason}); compiling on the main thread, which is slower and blocks the editor while it runs.`;
+		for (const [id, { job, resolve, reject }] of pending) { pending.delete(id); try { resolve(local(job)); } catch (error) { reject(error); } }
+	};
+	const started = () => {
+		if (worker || dead) return worker;
+		try { worker = spawn(); } catch (error) { fallBack(error?.message ?? String(error)); return null; }
+		if (!worker) { dead = true; return null; }
+		worker.onmessage = ({ data: { id, value, error } }) => {
+			const job = pending.get(id);
+			if (!job) return;
+			pending.delete(id);
+			if (error) { try { rethrow(error); } catch (thrown) { job.reject(thrown); } } else job.resolve(value);
+		};
+		worker.onerror = event => { event?.preventDefault?.(); fallBack(event?.message || "worker error"); };
+		worker.onmessageerror = () => fallBack("an answer could not be read");
+		return worker;
+	};
+	return {
+		run(job) {
+			if (!started()) return local(job);
+			return new Promise((resolve, reject) => {
+				const id = ++next;
+				pending.set(id, { job, resolve, reject });
+				try { worker.postMessage({ id, job }); } catch (error) { fallBack(error?.message ?? String(error)); }
+			});
+		},
+		/** The fallback note, once (a receipt warning), or null. */
+		takeWarning() { const note = warning; if (note) warning = ""; return note || null; },
+	};
+}