cozyclay 2.1.0 → 3.0.0

package/src/commands/motion3.js

@@ -0,0 +1,207 @@
+// CozyClay 3 motion: the agent writes a motion spec (keys, anchors, props, fits, generators,
+// checks, goals), the deterministic compiler bakes every frame, QA measures it, and the take is
+// installed on the character. Cheap enough to run in a loop until QA reports nothing. The words
+// the agent reads live in motion3/docs.js; the contracts in docs/motion-api-v3.1.md.
+import { fail, characterOf } from "./shared.js";
+import { motionScene } from "../motion3/scene.js";
+import { skeletonFor } from "../motion3/rigs/index.js";
+import { fk } from "../motion3/compiler/skeleton.js";
+import { add, apply, ry } from "../motion3/compiler/math.js";
+import { resolveBone } from "../motion3/bones.js";
+import { MOTION_ACTION_HELP as HELP } from "../motion3/docs.js";
+import { DESCRIBE_TOPICS } from "../motion3/schema/fields.js";
+import { describe, describeMany } from "../motion3/describe.js";
+import { createSpecStore, specIdOf, SPEC_STORE_SIZE } from "../motion3/spec-store.js";
+import { applyPatch } from "../motion3/json-patch.js";
+import { deltaOf } from "../motion3/delta.js";
+import { fitOutput, reportPage } from "../motion3/report.js";
+import { keyObject } from "../motion3/key-edit.js";
+import { expandUse } from "../motion3/skills/index.js";
+import { publishDraft } from "../agent-progress.js";
+import { carryEdit } from "../motion3/edit-carry.js";
+import { normalizeCompileArgs } from "../motion3/lenient.js";
+import { createCompileRunner } from "./motion3-compile.js";
+
+const TIMELINE_FPS = 24;
+const id = { type: "string", minLength: 1 };
+const specId = { type: "string", pattern: "^spec-[0-9a-f]{12}$" };
+const openObject = { type: "object", properties: {}, required: [], additionalProperties: true };
+const input = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required, additionalProperties: false });
+const list = (items, maxItems) => ({ type: "array", items, minItems: 1, maxItems });
+const numbers = n => ({ type: "array", items: { type: "number" }, minItems: n, maxItems: n });
+
+// readOnly: reads the scene and the take, never changes them (C10).
+const declarations = Object.freeze([
+	{ id: "motion.compile", label: "Compile motion", kind: "job", domain: "motion", timeoutMs: 120000, description: HELP.compile,
+		// patch may be empty: base alone (or patch: []) re-measures the stored spec, with new probes; "never" is install: false
+		input: input({ characterId: id, spec: openObject, base: specId, patch: { type: "array", items: openObject, maxItems: 64 },
+			install: { oneOf: [{ type: "boolean" }, { const: "ifClean" }, { const: "never" }], default: true },
+			probes: list(openObject, 16), repair: input({ rounds: { type: "integer", minimum: 1, maximum: 8, default: 4 } }, []) }, ["characterId"]) },
+	{ id: "motion.qa", label: "Measure motion", kind: "job", domain: "motion", timeoutMs: 120000, readOnly: true, description: HELP.qa,
+		input: input({ characterId: id, checks: openObject }, ["characterId"]) },
+	{ id: "motion.sample", label: "Sample motion", kind: "job", domain: "motion", timeoutMs: 30000, readOnly: true, description: HELP.sample,
+		input: input({ characterId: id, frames: { type: "array", items: { type: "integer", minimum: 0 }, minItems: 1, maxItems: 64 },
+			bones: { type: "array", items: id, maxItems: 65 } }, ["characterId", "frames"]) },
+	{ id: "motion.describe", label: "Describe motion spec", kind: "job", domain: "motion", timeoutMs: 10000, readOnly: true, description: HELP.describe,
+		input: input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id,
+			topics: list({ oneOf: [{ type: "string", enum: DESCRIBE_TOPICS }, input({ topic: { type: "string", enum: DESCRIBE_TOPICS }, name: id }, ["topic"])] }, 8) }, []) },
+	{ id: "motion.report", label: "Read motion report", kind: "job", domain: "motion", timeoutMs: 10000, readOnly: true, description: HELP.report,
+		input: input({ specId, part: { type: "string", enum: ["groups", "timeline", "probes"], default: "groups" }, from: { type: "integer", minimum: 0, default: 0 } }, ["specId"]) },
+	{ id: "motion.keyObject", label: "Key held object", kind: "job", domain: "motion", timeoutMs: 120000, description: HELP.keyObject,
+		input: input({ characterId: id, objectId: id, frame: { type: "integer", minimum: 0 }, pos: numbers(3), rot: numbers(4), aim: numbers(3), roll: { type: "number" },
+			angle: { type: "number" }, remove: { type: "boolean", default: false } }, ["characterId", "objectId", "frame"]) },
+]);
+export { declarations };
+
+const DEFAULT_BONES = ["Hips", "Head", "LeftHand", "RightHand", "LeftFoot", "RightFoot"];
+// the inputs a compile fixed instead of refusing (lenient.js), kept in every answer (report.js keeps the head)
+const MAX_ADJUSTED = 8;
+const adjustedOf = notes => (notes.length ? { adjusted: notes.length > MAX_ADJUSTED ? [...notes.slice(0, MAX_ADJUSTED - 1), `${notes.length - MAX_ADJUSTED + 1} more`] : notes } : {});
+const adjustedSay = notes => (notes.length ? `; ${notes.length} input${notes.length > 1 ? "s" : ""} adjusted (output.adjusted)` : "");
+const unknownSpec = (what, value, then = "send spec") => fail("INVALID_ARGUMENT", `${what} "${value}" is not known (the editor keeps the last ${SPEC_STORE_SIZE} compiled specs this session); ${then}`);
+
+const sameArray = (a, b) => a?.length === b?.length && Array.prototype.every.call(a, (v, i) => v === b[i]);
+/** True when `installed` is the take `take` would install: the same spec, placement, bones and object tracks. */
+function sameTake(installed, take) {
+	return installed?.schema === take.schema && installed.frameCount === take.frameCount && installed.rig === take.rig
+		&& specIdOf(installed.spec ?? null) === specIdOf(take.spec) && JSON.stringify(installed.placement) === JSON.stringify(take.placement)
+		&& sameArray(installed.rot, take.rot) && sameArray(installed.hips, take.hips) && JSON.stringify(installed.objects ?? {}) === JSON.stringify(take.objects);
+}
+
+/** then(value) now, or when the promise settles (a compile answers at once in Node, later from the browser's worker). */
+const after = (value, then) => (typeof value?.then === "function" ? value.then(then) : then(value));
+/** Runs `run`, turning a MOTION_SPEC_INVALID error into INVALID_ARGUMENT with the exact message. */
+function asArgument(run) {
+	try {
+		return run();
+	} catch (error) {
+		if (/^MOTION_SPEC_INVALID/.test(error.message)) fail("INVALID_ARGUMENT", error.message.replace(/^MOTION_SPEC_INVALID:\s*/, ""));
+		throw error;
+	}
+}
+
+export function register(registry, ports) {
+	const store = createSpecStore();
+	const owner = () => ports.storeDomain("motion");
+	const mounted = () => Boolean(ports.storeDomain?.("motion")) || "The motion owner is not mounted.";
+	const always = () => true;
+	const rigOf = character => {
+		const sk = skeletonFor(character.model);
+		if (!sk) fail("TARGET_NOT_READY", `${character.subject || character.id} is a ${character.model} body, which motion compile cannot drive; use an X Bot or Y Bot character.`);
+		if (Math.abs((character.scale ?? 1) - 1) > 1e-6) fail("TARGET_NOT_READY", "Set the character's scale back to 1 before compiling motion.");
+		return sk;
+	};
+	// one compile worker per editor in the browser, the calling thread elsewhere (motion3-compile.js)
+	const runner = createCompileRunner();
+	const workerWarning = () => { const note = runner.takeWarning(); return note ? { warnings: [note] } : {}; };
+	/**
+	 * spec on the character's rig and the current scene (compile-job.js) -> { stored (the spec a take keeps and its specId
+	 * names), qa, ..., take when bake is given }, at once or as a promise. opts: probes, checks, lenient, repair.
+	 */
+	const compile = (character, spec, opts = {}, bake) => {
+		rigOf(character);
+		const placed = bake && { position: [character.x ?? 0, character.y ?? 0, character.z ?? 0], yaw: character.rot ?? 0, ...bake };
+		return runner.run({ model: character.model, scene: motionScene(ports.state().objects), spec, ...opts, ...(placed ? { bake: placed } : {}) });
+	};
+	/** The whole output, kept in the store (motion.report, delta) and cut to the receipt budget (report.js). */
+	const report = (r, head, extra = {}) => {
+		const specIdValue = store.put(r.stored);
+		store.keepParts(specIdValue, { groups: r.qa.groups, timeline: r.timeline, probes: r.probes ?? {} });
+		return fitOutput({ ...head, specId: specIdValue, qa: r.qa, observations: r.observations, ...extra, ...(r.probes ? { probes: r.probes } : {}), timeline: r.timeline,
+			fixed: r.fixed, ...(r.search ? { search: r.search } : {}), ...(r.used.length ? { skills: r.used } : {}), ms: r.ms });
+	};
+	/**
+	 * A compiled take on the character, installed as one undo entry; put() keeps the timing edit of the take it replaces
+	 * (edit-carry.js) and returns what it did with it (a note for the receipt), or undefined.
+	 */
+	const put = (character, take, context) => {
+		let note;
+		const apply = () => {
+			const id = character.id, edit = owner().layer?.(id)?.take?.edit, full = edit && owner().fullMotionFor?.(id), carried = full && carryEdit(edit, full.frames ?? full.frameCount, take.frameCount);
+			owner().replace(id, { ...take, frames: take.frameCount });
+			if (carried?.edit) { owner().writeLayer(id, { take: { ...owner().layer(id).take, edit: carried.edit } }); ports.storeDomain("cast")?.syncTimeline?.(); }
+			note = carried?.note;
+		};
+		if (context?.commit) context.commit(apply); else apply();
+		return note;
+	};
+	const installed = characterId => owner().motionFor(characterId)?.schema === "cozyclay.take.v3" ? owner().motionFor(characterId)
+		: fail("TARGET_NOT_READY", "This character has no compiled take; run motion.compile first.");
+
+	// normalizeArgs: other spellings of install and repair become the declared ones before the schema check (lenient.js)
+	registry.register({ ...declarations[0], normalizeArgs: normalizeCompileArgs, available: mounted, target: args => args.characterId, run({ characterId, spec, base, patch, install: asked = true, probes, repair }, context) {
+		const install = asked === "never" ? false : asked;
+		const character = characterOf(ports, characterId);
+		if ((spec === undefined) === (base === undefined)) fail("INVALID_ARGUMENT", "Send exactly one of spec or base (the specId of a compiled spec, with patch).");
+		if (patch !== undefined && base === undefined) fail("INVALID_ARGUMENT", "patch applies to base, the specId of a compiled spec; send base with it, or the whole spec.");
+		const patched = [], source = spec ?? asArgument(() => applyPatch(store.get(base) ?? unknownSpec("base", base), patch ?? [], patched));
+		// the take is always baked: the user watches every draft, installed or not
+		return after(compile(character, source, { probes, repair }, {}), r => {
+			const { qa, take } = r, notes = [...patched, ...(r.notes ?? [])];
+			// ifClean: install only a clean final result (qa.ok includes the goals; after repair when asked)
+			const wanted = install === "ifClean" ? qa.ok : install;
+			let installs = wanted, kept = false, timing;
+			// open ranges are stored with the values the search chose, so motion.qa re-measures this take
+			if (wanted) {
+				// ifClean of the take already installed changes nothing (no undo entry; IK edits on it stay)
+				kept = install === "ifClean" && sameTake(owner().motionFor(characterId), take);
+				installs = !kept;
+				if (installs) timing = put(character, take, context);
+			}
+			const delta = base === undefined ? {} : { delta: deltaOf(store.parts(base)?.groups ?? [], qa.groups, base) };
+			const how = kept ? "; already installed, unchanged" : install === "ifClean" ? (installs ? "; installed" : "; not installed") : "";
+			const output = report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: wanted, ...adjustedOf(notes) }, { ...delta, ...(r.repair ? { repair: r.repair } : {}), ...(timing ? { timing } : {}) });
+			// agent-progress.js: viewport ghost, timeline beats, agent panel
+			publishDraft(characterId, { take, installed: installs || kept, specId: output.specId, label: r.label, qa, timeline: r.timeline });
+			return { affectedIds: installs ? [characterId] : [], summary: `Compiled ${r.frameCount} frames; QA ${qa.ok ? "clean" : `${qa.total} issues`}${how}${adjustedSay(notes)}.`, output, ...workerWarning() };
+		});
+	} });
+	registry.register({ ...declarations[1], available: mounted, run({ characterId, checks }) {
+		const character = characterOf(ports, characterId), take = installed(characterId);
+		return after(compile(character, take.spec, { checks }), r => ({ affectedIds: [], summary: `QA ${r.qa.ok ? "clean" : `${r.qa.total} issues`}${adjustedSay(r.notes ?? [])}.`,
+			output: report(r, adjustedOf(r.notes ?? [])), ...workerWarning() }));
+	} });
+	registry.register({ ...declarations[2], available: mounted, run({ characterId, frames, bones = DEFAULT_BONES }) {
+		const character = characterOf(ports, characterId), take = installed(characterId), sk = rigOf(character);
+		const yaw = ry(take.placement?.yaw ?? 0), at = take.placement?.position ?? [0, 0, 0], B = take.bones.length;
+		const rows = frames.map(f => {
+			const ff = Math.min(take.frameCount - 1, f);
+			const quats = Array.from({ length: B }, (_, b) => Array.from(take.rot.subarray((ff * B + b) * 4, (ff * B + b) * 4 + 4)));
+			const state = fk(sk, quats, Array.from(take.hips.subarray(ff * 3, ff * 3 + 3)));
+			return { frame: ff, bones: Object.fromEntries(bones.map(name => {
+				const { bone, hint } = resolveBone(sk, name);
+				if (bone === null) fail("INVALID_ARGUMENT", `Unknown bone ${name}${hint || "."}`);
+				return [name, add(at, apply(yaw, state.P[sk.index[bone]])).map(v => Math.round(v * 1e4) / 1e4)];
+			})) };
+		});
+		return { affectedIds: [], summary: `Sampled ${rows.length} frames.`, output: { frames: rows } };
+	} });
+	registry.register({ ...declarations[3], available: always, run({ topic, name, topics }) {
+		if (topic === undefined && topics === undefined) fail("INVALID_ARGUMENT", "Send topic (and name) for one answer, or topics: [{ topic, name? }] for several in one call.");
+		if (topics) {
+			// C19: a topic beside topics joins them; a name beside topics goes to the one ask that can take it
+			const asks = [...(topic === undefined ? [] : [{ topic }]), ...topics.map(t => (typeof t === "string" ? { topic: t } : { ...t }))];
+			const open = asks.filter(a => a.name === undefined && (asks.length === 1 || a.topic === "skills"));
+			if (name !== undefined && open.length !== 1) fail("INVALID_ARGUMENT", "name goes with one topic; inside topics give each its own: topics: [{ topic, name? }].");
+			if (name !== undefined) open[0].name = name;
+			const output = asArgument(() => describeMany(asks));
+			return { affectedIds: [], summary: `Described ${output.topics.map(a => (a.name ? `${a.topic} ${a.name}` : a.topic)).join(", ")}${output.more ? `; ${output.more.length} more did not fit` : ""}.`, output };
+		}
+		return { affectedIds: [], summary: `Described ${topic}${name ? ` ${name}` : ""}.`, output: asArgument(() => describe(topic, name)) };
+	} });
+	registry.register({ ...declarations[4], available: always, run({ specId: wanted, part = "groups", from = 0 }) {
+		const page = reportPage(store.parts(wanted) ?? unknownSpec("specId", wanted, "compile it again"), wanted, part, from);
+		return { affectedIds: [], summary: `${page.items.length} ${part} from ${from}.`, output: page };
+	} });
+	// motion.keyObject (C14): one key of a held object (or a hinge angle) in the installed take's spec, compiled
+	// and installed whatever QA says (a user edit), as one undo entry
+	registry.register({ ...declarations[5], available: mounted, target: args => args.characterId, run({ characterId, ...args }, context) {
+		const character = characterOf(ports, characterId), take = installed(characterId), scene = motionScene(ports.state().objects);
+		const { spec, keyed } = asArgument(() => keyObject(take.spec, scene, args, expandUse(take.spec, { sk: rigOf(character), scene, lenient: true }).spec.objects));
+		return after(compile(character, spec, { lenient: true }, { prompt: take.prompt }), r => {
+			const timing = put(character, r.take, context);
+			return { affectedIds: [characterId], summary: `${keyed.removed ? "Removed the key of" : "Keyed"} ${keyed.objectId} at f${keyed.f}; QA ${r.qa.ok ? "clean" : `${r.qa.total} issues`}; installed.`,
+				output: report(r, { frames: r.frameCount, fps: TIMELINE_FPS, installed: true, keyed }, timing ? { timing } : {}), ...workerWarning() };
+		});
+	} });
+}

package/src/commands/objects.js

@@ -8,6 +8,8 @@ import { expandSculptParts, normalizeSculptRecipe, patchSculptRecipe } from '../
 import { rankingRow, scoreSculptAgainstReference } from '../sculpt-compare.js';
 import { browserSculptImages, shrinkRgba } from './sculpt-images.js';
 import { clampWarning } from '../receipt-findings.js';
+import { effectPresetSet } from '../effects/effect-record.js';
+import { withLightWarnings } from '../light-blockers.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 
 const id = StudioSchemas.TargetGuard.properties.targetId;
@@ -80,7 +82,7 @@ export function register(registry, ports) {
 			// goes to the top where it is seen, not below a long expanded group.
 			const next = args.first ? [placed, ...before] : [...before, placed];
 			owned().write(args.parent === undefined ? next : setSceneObjectParent(next, placed.id, args.parent));
-			return result(before, 'Added object.');
+			return withLightWarnings(result(before, 'Added object.'), owned().read());
 		},
 		'object.sculpt': args => {
 			const before = owned().read();
@@ -156,13 +158,13 @@ export function register(registry, ports) {
 		},
 		'objects.arrange': args => {
 			const plan = owned().arrange(args);
-			return { affectedIds: plan.affectedIds, summary: 'Arranged objects.', checks: plan.checks, warnings: plan.warnings };
+			return withLightWarnings({ affectedIds: plan.affectedIds, summary: 'Arranged objects.', checks: plan.checks, warnings: plan.warnings }, owned().read());
 		},
 	};
 	// 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;
+		const expand = op => effectPresetSet(typeof op.set.scale === 'number' ? { ...op, set: { ...op.set, scale: { x: op.set.scale, y: op.set.scale, z: op.set.scale } } } : op, ports.state().objects);
 		registry.register({ ...entry, available, run: args => {
 			const ops = (args.ops ?? [args]).map(expand);
 			let draft = owned().read();
@@ -173,7 +175,7 @@ export function register(registry, ports) {
 				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]);
+			return withLightWarnings(entry.run(args.ops ? { ops } : ops[0]), owned().read());
 		} });
 	} }, ports, semantic[0]);
 	for (const declaration of semantic.slice(1)) registry.register({ ...declaration, available, run: methods[declaration.id] });

package/src/commands/shot.js

@@ -7,6 +7,9 @@ import { track } from '../analytics.js';
 import { isImageAssetId } from '../scene-assets.js';
 import { createStableItemId, updateStableItem } from '../stable-items.js';
 import { railFollowForNewGeometry } from '../camera-rail-schedule.js';
+import { buildRail } from '../camera-follow.js';
+import { cameraKeyWarnings } from '../camera-direction.js';
+import { TIMELINE_FPS } from '../timeline-defaults.js';
 import { studioActionDeclaration, studioActionRefusal } from '../studio-actions.js';
 import { STUDIO_TOOL_SCHEMAS, StudioSchemas } from '../studio-agent-protocol.js';
 import { elementSetSchema, registerElementSet } from './elements.js';
@@ -18,7 +21,7 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const number = { type: 'number' };
 const frame = { type: 'integer', minimum: 0 };
 const input = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
-const mutation = (id, label, schema) => ({ id, label, description: label, kind: 'mutation', undoDomain: 'shot', input: schema });
+const mutation = (id, label, schema, description = label) => ({ id, label, description, kind: 'mutation', undoDomain: 'shot', input: schema });
 const existing = ['shot.create', 'shot.createStill', 'shot.setCaption', 'shot.setCastOverride', 'shot.setHold', 'shot.split', 'shot.duplicate', 'shot.remove', 'shot.setRange', 'shot.setCameraRail', 'shot.clearCameraRail', 'shot.reorder'].map(studioActionDeclaration);
 const extra = [
   mutation('shot.set', 'Set shot fields', elementSetSchema('shot')),
@@ -30,7 +33,8 @@ const extra = [
   mutation('shot.clearKeys', 'Clear camera keys', input({ shotId: id })),
   mutation('shot.setTimeline', 'Set shot timeline', input({ frameCount: { type: 'integer', minimum: 24, maximum: 28800 } })),
   mutation('shot.setLens', 'Set camera lens', input({ fovDeg: { ...number, minimum: 14, maximum: 90 } })),
-  mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] }),
+  mutation('shot.frame', 'Frame the shot', { ...input({ ...STUDIO_TOOL_SCHEMAS.frame_shot.properties, preset: { type: 'string' } }, []), oneOf: [STUDIO_TOOL_SCHEMAS.frame_shot, input({ preset: { type: 'string' } })] },
+    'Frame a shot on one character (the frame_shot tool): framing.intent { size, level, view, side, focalMm } or framing.exact { position, lookAt, focalMm }. Without keyAtFrame a shot that holds one framing is reframed whole: a held shot. keyAtFrame adds a camera key there; every key eases in and out, so the camera slows to a stop at each one: key a pan or zoom from one spot with two keys (its start and end), lay a moving camera as a rail (shot.setCameraRail) and cut to a new shot for a new view. On a rail shot it puts the shot back on keys. Answers checks { derivedSize, screenFraction, clipped, behindCamera, occluded, cameraSide } for the subject at that frame.'),
   { ...mutation('shot.replace', 'Replace shot authoring', input({ shots: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } } })), exposure: 'ui-only' },
   { ...mutation('shot.captureCamera', 'Capture camera framing', input({ shotId: id }, [])), exposure: 'ui-only' },
   // The Board's Stylize result (or null to clear it). UI-only: the picture has
@@ -40,6 +44,14 @@ const extra = [
 ];
 export const declarations = Object.freeze([extra[0], ...existing, ...extra.slice(1).map(entry => entry.id === 'shot.frame' ? entry : { ...entry, exposure: 'ui-only' })]);
 
+// shot.setRange also takes range: [startFrame, endFrameExclusive] or flat startFrame/endFrameExclusive
+// fields; both become range: { startFrame, endFrameExclusive } before validation (registry normalizeArgs).
+function lenientRange(args) {
+  const { range, startFrame, endFrameExclusive, ...rest } = args, flat = Object.fromEntries(Object.entries({ startFrame, endFrameExclusive }).filter(([, v]) => v !== undefined));
+  if (Array.isArray(range) && range.length === 2 && !Object.keys(flat).length) return { ...rest, range: { startFrame: range[0], endFrameExclusive: range[1] } };
+  return range === undefined && Object.keys(flat).length ? { ...rest, range: flat } : args;
+}
+
 export function register(registry, ports) {
   const owner = () => ports.storeDomain('shot');
   const mounted = () => Boolean(ports.storeDomain?.('shot')) || 'The shots document owner is not mounted.';
@@ -97,6 +109,27 @@ export function register(registry, ports) {
     let next = 0;
     writeStills(current.map(row => row.kind === 'still' ? order[next++] : row));
   }
+  // A rail owns the frames it covers, so the camera keys there go. Its answer
+  // names the move it makes: length, speed, height, aim and lens.
+  function setRail({ shotId, points, height, aim, aimHeight, focalMm }) {
+    const shot = shotOf(shotId), cast = [...ports.state().characters, ...ports.state().objects];
+    for (const id of Array.isArray(aim) ? aim : []) if (!cast.some(row => row.id === id)) fail('STALE_TARGET', `Aim ${id} is not a character or object in this scene.`);
+    const railFollow = railFollowForNewGeometry(shot.camera?.railFollow, shot.endFrame - shot.startFrame + 1);
+    const span = railFollow?.mode === 'range' ? [shot.startFrame + railFollow.startFrame, shot.startFrame + railFollow.endFrame] : [shot.startFrame, shot.endFrame];
+    const patch = { cameraRail: points, mode: 'rail', railFollow, ...(focalMm === undefined ? {} : { focalMm }),
+      ...(height === undefined ? {} : { craneHeight: { points: typeof height === 'number' ? [{ t: 0, height }, { t: 1, height }] : height } }),
+      ...(aim === undefined && aimHeight === undefined ? {} : { aim: aimOf(aim === undefined ? createCameraBlock(shot.camera).aim : aim && (Array.isArray(aim) ? { ids: aim } : { point: aim }), aimHeight) }) };
+    const keys = shot.cameraKeys.filter(key => key.frame < span[0] || key.frame > span[1]);
+    patchShot(shotId, row => ({ ...row, cameraKeys: keys, camera: updateCameraBlock(row.camera, patch) }));
+    const camera = createCameraBlock(shotOf(shotId).camera), metres = buildRail(camera.cameraRail)?.length ?? 0, seconds = (span[1] - span[0] + 1) / TIMELINE_FPS;
+    const heights = camera.craneHeight?.points.map(point => point.height) ?? [camera.followCam.height], speed = metres / seconds;
+    const aimed = camera.aim?.ids ? `${camera.aim.ids.join(', ')}${camera.aim.height === undefined ? '' : ` at ${camera.aim.height.toFixed(2)} m`}` : (camera.aim ? `(${['x', 'y', 'z'].map(axis => camera.aim.point[axis].toFixed(2)).join(', ')})` : 'the follow subject');
+    const note = `${metres.toFixed(1)} m over ${seconds.toFixed(1)} s (${speed.toFixed(2)} m/s), height ${[...new Set([heights[0], heights.at(-1)])].map(h => h.toFixed(2)).join('-')} m, aim ${aimed}, ${camera.focalMm ? `${camera.focalMm} mm` : 'scene lens'}${shot.cameraKeys.length > keys.length ? `; ${shot.cameraKeys.length - keys.length} camera keys removed` : ''}.`;
+    const fast = speed > camera.followCam.maxDollySpeed ? [{ code: 'RAIL_TOO_FAST', id: shotId, message: `${speed.toFixed(1)} m/s is past the ${camera.followCam.maxDollySpeed} m/s dolly cap, so the camera lags; lengthen the shot or the rail.` }] : [];
+    return { note, warnings: fast };
+  }
+  // aimHeight moves a cast aim off the chest to a world height (a whole body, a face).
+  const aimOf = (aim, aimHeight) => (aim?.ids && aimHeight !== undefined ? { ids: aim.ids, height: aimHeight } : aim);
   const methods = {
     'shot.create': () => storyboard() ? createStill() : owner().write(current => addShotAtFrame(current, ports.state().frame, owner().state().frameCount, owner().capture())),
     'shot.createStill': args => createStill(args),
@@ -119,9 +152,7 @@ export function register(registry, ports) {
       const edges = startFrame > shot.endFrame ? [['end', endFrame], ['start', startFrame]] : [['start', startFrame], ['end', endFrame]];
       owner().write(current => edges.reduce((rows, [edge, frame]) => resizeShot(rows, shotId, edge, frame, owner().state().frameCount), current));
     },
-    'shot.setCameraRail': ({ shotId, points }) => patchShot(shotId, shot => ({ ...shot, camera: updateCameraBlock(shot.camera, {
-      cameraRail: points, mode: 'rail', railFollow: railFollowForNewGeometry(shot.camera?.railFollow, shot.endFrame - shot.startFrame + 1),
-    }) })),
+    'shot.setCameraRail': args => setRail(args),
     'shot.clearCameraRail': ({ shotId }) => {
       const shot = shotOf(shotId);
       if (!createCameraBlock(shot.camera).cameraRail) fail('TARGET_NOT_READY', `${shot.name || shotId} has no camera rail.`);
@@ -159,14 +190,12 @@ export function register(registry, ports) {
   };
   registerElementSet(registry, ports, extra[0]);
   for (const declaration of declarations.filter(row => row.id !== 'shot.set')) registry.register({ ...declaration,
+    ...(declaration.id === 'shot.setRange' ? { normalizeArgs: lenientRange } : {}),
     available: state => mounted() === true ? (availability[declaration.id] ?? (existing.includes(declaration) ? hasShots : () => true))(state) : mounted(),
     run(args, context) {
-      if (declaration.id === 'shot.frame') {
-        const plan = owner().frame(args);
-        return { affectedIds: plan.affectedIds, summary: 'Framed the shot.' };
-      }
+      if (declaration.id === 'shot.frame') return framed(args);
       const before = owner().read(), newPanel = declaration.id === 'shot.createStill' || (declaration.id === 'shot.create' && storyboard());
-      methods[declaration.id](args);
+      const answered = methods[declaration.id](args), answer = typeof answered?.note === 'string' ? answered : null;
       // Only the origin travels: never the caption, name or id of the panel.
       if (newPanel) track('storyboard:panel_created', { source: context?.origin && context.origin !== 'ui' ? 'agent' : 'manual' });
       // The owner re-normalizes every shot on write, so compare content, not
@@ -174,8 +203,17 @@ export function register(registry, ports) {
       // names (100), and the first 100 stand for the batch.
       const after = owner().read(), changed = changedIds(before.map(row => after.find(next => next.id === row.id && same(next, row)) ?? row), after).slice(0, 100);
       const affectedIds = changed.length ? changed : [args.shotId ?? ports.state().activeSceneId];
-      return { affectedIds, summary: changed.length ? `${declaration.label}: ${changed.map(id => after.find(row => row.id === id)).filter(Boolean).map(shotLabel).join('; ')}.` : `${declaration.label}.` };
+      const summary = changed.length ? `${declaration.label}: ${changed.map(id => after.find(row => row.id === id)).filter(Boolean).map(shotLabel).join('; ')}.` : `${declaration.label}.`;
+      return { affectedIds, summary: answer?.note ? `${summary.slice(0, -1)}: ${answer.note}`.slice(0, 240) : summary, ...(answer?.warnings ? { warnings: answer.warnings } : {}) };
     },
   });
+  // frame_shot answers what it measured, and what its keys do to a move.
+  function framed(args) {
+    const before = owner().read(), plan = owner().frame(args), shot = owner().read().find(row => row.id === plan.details.shotId);
+    const wasRail = createCameraBlock(before.find(row => row.id === shot.id)?.camera).mode === 'rail';
+    return { affectedIds: plan.affectedIds, summary: `Framed ${shotLabel(shot)}: ${plan.checks.derivedSize} at frame ${plan.details.frame}, ${shot.cameraKeys.length} camera key${shot.cameraKeys.length === 1 ? '' : 's'}.`.slice(0, 240),
+      checks: plan.checks, warnings: [...plan.warnings, ...(wasRail ? [{ code: 'RAIL_REPLACED', id: shot.id, message: 'This shot is back on camera keys; its rail no longer drives it. Re-lay it with shot.setCameraRail.' }] : []),
+        ...cameraKeyWarnings(shot)] };
+  }
   if (ports.storeDomain?.('shot')) registry.registerToolAlias('frame_shot', 'shot.frame');
 }

package/src/commands/stage.js

@@ -1,17 +1,30 @@
 import { elementSetSchema, registerElementSet } from './elements.js';
+import { normalizeStage } from './elements/stage.js';
+import { applyLightingRecipe, LIGHTING_KEEP_PATHS, LIGHTING_PRESETS } from '../stage-lighting.js';
 export { STAGE_FIELDS, normalizeStage } from './elements/stage.js';
 
 const input = elementSetSchema('stage');
 const declaration = (id, properties = input.properties) => ({ id, label: 'Set stage', kind: 'mutation', undoDomain: 'stage',
   description: 'Update authored stage fields, normalized by scene persistence.',
   input: { ...input, properties } });
+const applyLighting = { id: 'stage.applyLighting', label: 'Apply lighting', kind: 'mutation', undoDomain: 'stage',
+  description: 'Give the stage a whole lighting look in one undoable step: writes every stage.lighting field (sky, skyTop, ambient, hemiSky, hemiGround, fill, fog, exposure, shadowSoftness, envLight, ao) and the key light\'s colour, intensity and position from the recipe, then sets lighting.preset to its name. studio is the neutral grey default; day is a high sun under a blue sky; overcast is soft, shadowless grey daylight; golden a low warm sun with long shadows; dusk a dim warm horizon glow under a blue sky; night a dark blue-black sky, a dim cool moon key with soft shadows, low cool ambient and haze; interior a warm tungsten lamp in a dark room; stage a black void lit by the key alone. Every recipe but studio lights the set with a sky environment map (envLight 1) and darkens contacts and creases (ao 0.6 to 1); studio keeps both at 0. keep lists paths left as they are, e.g. ["keyLight.position"] to keep where the light stands; a recipe also clears an HDR environment (stage.lighting.hdr) unless keep has "lighting.hdr". Tweak any value afterwards with stage.set; check the result with verify_result checks ["lighting"].',
+  input: { type: 'object', properties: { preset: { type: 'string', enum: [...LIGHTING_PRESETS] },
+    keep: { type: 'array', items: { type: 'string', enum: [...LIGHTING_KEEP_PATHS] }, minItems: 1, maxItems: LIGHTING_KEEP_PATHS.length, uniqueItems: true } }, required: ['preset'], additionalProperties: false } };
 export const declarations = Object.freeze([
   declaration('stage.set'),
   declaration('stage.setKeyLight', { keyLight: input.properties.keyLight }),
   declaration('stage.setEnvironment', Object.fromEntries(['environment', 'environmentImage', 'hasEnvSheet'].map(key => [key, input.properties[key]]))),
   declaration('stage.setStyle', { style: input.properties.style }),
   declaration('stage.setFilmback', Object.fromEntries(['shotAspect', 'cameraPresetId', 'sensorId'].filter(key => input.properties[key]).map(key => [key, input.properties[key]]))),
+  applyLighting,
 ]);
 export function register(registry, ports) {
-  for (const declaration of declarations) registerElementSet(registry, ports, declaration);
+  for (const declaration of declarations.filter(entry => entry !== applyLighting)) registerElementSet(registry, ports, declaration);
+  registry.register({ ...applyLighting, available: () => true, run({ preset, keep = [] }) {
+    const domain = ports.storeDomain('stage'), before = domain.read();
+    const next = normalizeStage({ ...before, ...applyLightingRecipe(before, preset, keep) });
+    if (JSON.stringify(next) !== JSON.stringify(before)) domain.write(next);
+    return { affectedIds: [ports.state().activeSceneId], summary: `Applied the ${preset} lighting recipe${keep.length ? `, keeping ${keep.join(', ')}` : ''}.` };
+  } });
 }

package/src/commands/view.js

@@ -4,6 +4,7 @@ import { STUDIO_TOOL_SCHEMAS } from '../studio-agent-protocol.js';
 import { ko } from '../locale.js';
 import { shotAtFrame } from '../cuts.js';
 import { fail } from './shared.js';
+import { describeGhosts, setGhostSettings } from '../view-ghosts.js';
 
 const fields = STUDIO_TOOL_SCHEMAS.operate_studio.properties;
 const groups = { 'view.select': ['selection', 'shotId'], 'timeline.seek': ['frame'], 'timeline.play': ['playing'], 'view.setMode': ['mode', 'view'] };
@@ -11,7 +12,7 @@ const operations = Object.entries({ ...groups, 'view.update': Object.keys(fields
 	id, label: id, description: 'Change selection, timeline or viewer state without authoring history.', kind: 'transient',
 	input: { type: 'object', properties: Object.fromEntries(keys.map(key => [key, fields[key]])), required: [], additionalProperties: false },
 }));
-export const declarations = Object.freeze([...operations, ...["view.setPartColours", "view.setGuideMode", "view.setInset"].map(studioActionDeclaration)]);
+export const declarations = Object.freeze([...operations, ...["view.setPartColours", "view.setGuideMode", "view.setInset", "view.setGhosts"].map(studioActionDeclaration)]);
 // A storyboard project has no Motion department; every door says so the same way.
 export const STORYBOARD_MOTION_REFUSAL = Object.freeze({ en: 'Motion tools are not part of a Storyboard project.', ko: '모션 도구는 스토리보드 프로젝트에 없어요.' });
 export const viewCommand = args => Object.entries(groups).find(([, keys]) => Object.keys(args).every(key => keys.includes(key)))?.[0] ?? 'view.update';
@@ -45,4 +46,6 @@ export function register(registry, ports) {
 	viewAction("view.setPartColours", ({ mode }) => { ports.choosePartColours(mode); return `Part colours: ${mode}.`; });
 	viewAction("view.setGuideMode", ({ mode }) => { ports.setGuideMode(mode); return `Composition guide: ${mode}.`; });
 	viewAction("view.setInset", ({ collapsed }) => { ports.setInsetCollapsed(collapsed); return `Top-View inset ${collapsed ? "folded" : "unfolded"}.`; });
+	// The ghosts' setting lives with them (view-ghosts.js), not in the App: no port to reach.
+	viewAction("view.setGhosts", args => describeGhosts(setGhostSettings(args)));
 }

package/src/document-mirrors.js

@@ -0,0 +1,42 @@
+// The active scene's shot document and stage envelope, read from the stores at
+// the moment they are used. App used to rebuild both during render, so a
+// synchronous command read them one render behind: the Studio binding folds
+// them into the scene revision (stage and scenes documents), the receipt
+// answered revision N, and the next render moved the scene to N+1 by itself
+// when the mirrors caught up. An agent's next write, admitted at the receipt's
+// revision.after (a motion install, a cast move, a shot edit), then met
+// STALE_SCENE although nothing had changed.
+import { createShotAuthoringDocument } from "./shot-authoring.js";
+import { savedTakeSource } from "./domains/motion/take-source.js";
+
+// IK edits (Pose mode, IK keys, range pins) ride into the saved stage with each character.
+const ikEditsOf = row => (!row || (!row.ikKeys?.length && !row.ikPins?.length) ? null : { keys: row.ikKeys, pins: row.ikPins ?? [], pinResiduals: row.ikPinResiduals ?? [] });
+
+/** Ref-shaped mirrors (`.current`) for the scene snapshot and the stage domain.
+ * `actorStageRef.current` keeps the envelope App (or the stage domain) last set
+ * and always answers the cast as it is now: sessionMotion is stripped (baked
+ * takes are session-only and far too heavy for the stage envelope); a take v3
+ * persists as its source (spec, placement). */
+export function createDocumentMirrors(appContext) {
+	const cast = () => appContext.storeDomain("cast")?.projection() ?? appContext.live.characters ?? [];
+	const activeWaypoints = list => (list.find(entry => entry.id === appContext.storeDomain("cast")?.activeId) ?? list[0])?.layer?.waypoints ?? [];
+	const shotDocumentRef = {
+		get current() {
+			const shots = appContext.storeDomain("shot");
+			return createShotAuthoringDocument({ shots: shots?.read() ?? [], waypoints: activeWaypoints(cast()), frameCount: shots?.state().frameCount ?? null });
+		},
+	};
+	let envelope = null;
+	const stageCharacters = () => {
+		const layers = appContext.storeDomain("motion")?.read() ?? null;
+		return cast().map(({ sessionMotion, ...entry }) => {
+			const row = layers?.find(layer => layer.id === entry.id);
+			return { ...entry, ikEdits: ikEditsOf(row), motionTake: savedTakeSource(row?.take) };
+		});
+	};
+	const actorStageRef = {
+		get current() { return envelope && { ...envelope, characters: stageCharacters() }; },
+		set current(value) { envelope = value; },
+	};
+	return { shotDocumentRef, actorStageRef };
+}

package/src/document-store.js

@@ -38,6 +38,10 @@ export function createDocumentStore({ owned = {}, dev = import.meta.env?.DEV ??
       run(fn) { check(); running++; try { return fn(); } finally { running--; } },
       touch(domain) { check(); requireOwner(domain); },
       update(domain, update) { return session.run(() => write(domain, update)); },
+      // A point inside the open transaction (a script's start in an agent turn): rollback(mark)
+      // restores it and the transaction stays open; rollback() restores where it began.
+      mark() { check(); return slices; },
+      rollback(mark = before) { check(); publish(mark); },
       cancel({ restore = true } = {}) {
         if (active !== session) return false;
         active = null;