cozyclay 1.9.0 → 2.0.0

package/src/studio-app-binding.js

@@ -0,0 +1,379 @@
+// The Studio's agent binding: inspection, admission and the agent's commands
+// over the editor's native state. App.jsx supplies the ports (reads, commits,
+// history, the action registry); this module owns no React or renderer state.
+import { createCommandBus } from "./command-bus.js";
+import { readElementDocument, elementReadback, elementPatchArgs, elementTarget, elementPatchReceipt } from "./commands/elements.js";
+import { physicsKeyStamp } from "./ardy/physics-review.js";
+import { shotAtFrame } from "./cuts.js";
+import { CUTOUT_KIND, MESH_KIND, OBJECT_LIBRARY, supportHeightForObject } from "./scene-objects.js";
+import { buildStudioContext, physicsFingerprintInput, studioEntityCursor, validateStudioCursor } from "./studio-agent-context.js";
+import { createStudioCommandJournal, framingChecks, placementChecks, studioObjectCatalogue } from "./studio-agent-commands.js";
+import { verifyInstalledTake } from "./studio-agent-motion.js";
+import { STUDIO_TOOL_FAMILIES, StudioProtocolError, validateReceipt, validateStudioCommand, validateStudioIdentity } from "./studio-agent-protocol.js";
+import { CONTACT_SHEET_LAYOUT, buildContactSheet, sampleContactSheetFrames } from "./studio-contact-sheet.js";
+
+// App-owned adapter: the shared command modules remain the only
+// planners and validators. Ports below publish through the native editor stores.
+export function createStudioAppBinding(ports) {
+	const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+	const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+	const identities = new WeakMap(); let identitySequence = 0, tokenSequence = 0;
+	const motionStamps = new Map(), calibrationStamps = new Map();
+	const identityOf = value => {
+		if (!value || typeof value !== "object") return 0;
+		if (!identities.has(value)) identities.set(value, ++identitySequence);
+		return identities.get(value);
+	};
+	const stableStamp = (stamps, key) => {
+		if (key === null) return 0;
+		if (!stamps.has(key)) stamps.set(key, stamps.size + 1);
+		return stamps.get(key);
+	};
+	const motionContentKey = value => {
+		if (!value || typeof value !== "object") return null;
+		if (typeof value.studioTakeId === "string" && value.studioTakeId) return value.studioTakeId;
+		if (typeof value.motionRef?.motionId === "string" && value.motionRef.motionId) return value.motionRef.motionId;
+		return `${value.frames ?? 0}:${value.fps ?? 0}:${value.rotMats?.length ?? 0}:${value.rootPos?.length ?? 0}:${value.posedJoints?.length ?? 0}`;
+	};
+	const calibrationContentKey = value => value && typeof value === "object" ? JSON.stringify(value) : null;
+	const tokens = new Map(), receipts = new Map(), images = new Map();
+	let owner = null, journal = null, actionBus = null;
+	const domainKeys = new Map(), domainRevisions = {};
+	let authoredKey, physicsKey, viewKey, observedSceneRevision = ports.revision.current;
+	let physicsRevision = 0, viewRevision = 0;
+	function refresh() {
+		const document = Object.assign({}, ...(ports.storeDomains?.() ?? []).map(domain => domain.document()));
+		const raw = { ...ports.read(), ...document, document };
+		const host = validateStudioIdentity(raw.host);
+		if (!same(owner, host)) {
+			owner = host; tokens.clear(); receipts.clear(); images.clear();
+			authoredKey = physicsKey = viewKey = undefined;
+			journal = createStudioCommandJournal({ host, isRetained: receipt => ports.isRetained(receipt) });
+		}
+		const characters = raw.characters.map(character => {
+			const target = raw.targets.get(character.id);
+			return { ...character, sessionMotion: identityOf(target?.motion),
+				ik: physicsKeyStamp(target?.ikState?.keys ?? new Map()), rig: target?.rig?.uuid ?? null };
+		});
+		// Runtime motion, IK and rig fields are derived from the active editor
+		// buffers, not authored document state. A fresh equivalent buffer object
+		// must not advance the scene clock on a read.
+		const authoredCharacters = raw.characters.map(({ sessionMotion, ik, rig, ...character }) => character);
+		// The stage is authored state too: a key-light or environment edit from any
+		// surface bumps the scene revision exactly like a cast or object edit.
+		const authored = JSON.stringify([raw.objects, authoredCharacters, raw.shots, raw.frameCount, raw.stage, document]);
+		if (authoredKey !== undefined && authoredKey !== authored && observedSceneRevision === ports.revision.current) ports.revision.current++;
+		authoredKey = authored; observedSceneRevision = ports.revision.current;
+		const liveIds = new Set([...raw.objects, ...raw.characters, ...raw.shots].map(row => row.id));
+		for (const id of tokens.keys()) if (!liveIds.has(id)) tokens.delete(id);
+		for (const entry of [...raw.objects, ...characters, ...raw.shots]) {
+			// Display-only name/tint changes never revoke a motion target.
+			const { name, subject, tint, identityImage, ...content } = entry;
+			const key = JSON.stringify(content), previous = tokens.get(entry.id);
+			if (!previous || previous.key !== key) tokens.set(entry.id, { key, token: `target-${++tokenSequence}`, incarnation: previous?.incarnation ?? crypto.randomUUID() });
+		}
+		const physical = physicsFingerprintInput({ floor: { model: "flat", y: 0 }, frameCount: raw.frameCount,
+			objects: raw.objects.map(o => ({ id: o.id, renderer: o.renderer,
+				position: { x: o.x, y: o.y ?? 0, z: o.z }, rotationDeg: { x: o.rotX ?? 0, y: o.rot ?? 0, z: o.rotZ ?? 0 },
+				scale: { x: o.scaleX, y: o.scaleY, z: o.scaleZ }, footprint: o.footprint, height: o.height,
+				supportY: supportHeightForObject(o), parentId: o.parent ?? null, attachment: o.attach ?? null, path: o.path ?? null, hidden: o.hidden === true })),
+			characters: raw.characters.map(c => {
+				const t = raw.targets.get(c.id), summary = characters.find(row => row.id === c.id);
+				const motionKey = motionContentKey(t?.motion), calibrationKey = calibrationContentKey(t?.motion?.sceneCalibration);
+				return { id: c.id, incarnation: tokens.get(c.id).incarnation, modelId: c.model ?? null,
+					rigId: t?.rig?.uuid ?? null, rigReady: Boolean(t?.rig), hidden: Boolean(c.hidden),
+					position: { x: c.x, y: c.y ?? 0, z: c.z }, yawDeg: c.rot ?? 0, scale: c.scale ?? 1,
+					takeId: t?.motion?.studioTakeId ?? null, sessionMotionId: motionKey ? `motion-${motionKey}` : null,
+					motionRevision: stableStamp(motionStamps, motionKey), calibrationRevision: stableStamp(calibrationStamps, calibrationKey),
+					ikRevision: ports.ikRevision(c.id, summary.ik),
+					waypoints: (c.layer?.waypoints ?? []).map(p => ({ frame: p.frame, position: { x: p.x, y: p.y ?? 0, z: p.z } })) };
+			}) });
+		const physicalKey = JSON.stringify(physical);
+		if (physicsKey !== undefined && physicsKey !== physicalKey) physicsRevision++;
+		physicsKey = physicalKey;
+		const nextViewKey = JSON.stringify([raw.selection, raw.activeCharacterId, raw.selectedShotId, raw.view, raw.camera]);
+		if (viewKey !== undefined && viewKey !== nextViewKey) viewRevision++;
+		viewKey = nextViewKey;
+		for (const [domain, value] of Object.entries({ objects: raw.objects, shot: raw.shots, stage: raw.stage, cast: authoredCharacters, motion: characters, ...document })) {
+			const key = JSON.stringify(value);
+			if (domainKeys.get(domain) !== key) domainRevisions[domain] = (domainRevisions[domain] ?? 0) + 1;
+			domainKeys.set(domain, key);
+		}
+		return { ...raw, host, revision: ports.revision.current, physicsRevision, viewRevision, domainRevisions: { ...domainRevisions } };
+	}
+	function guard(id) {
+		const raw = refresh(), token = tokens.get(id)?.token;
+		if (!token) fail("STALE_TARGET", "The exact target no longer exists.");
+		return { ...raw.host, targetId: id, token };
+	}
+	function readCommand() {
+		const s = refresh();
+		return { host: s.host, revision: s.revision, frame: s.view.frame, frameCount: s.frameCount,
+			objects: s.objects, characters: s.characters, activeCharacterId: s.activeCharacterId,
+			selectedShotId: s.selectedShotId, shotDocument: { shots: s.shots }, camera: s.camera, stage: s.stage,
+			filmback: s.filmback, manual: s.manual, floorY: 0, busy: s.busy };
+	}
+	function entityProjection(s) {
+		return [...s.characters.map(c => {
+			const t = s.targets.get(c.id);
+			return { id: c.id, kind: "character", token: tokens.get(c.id).token, name: c.subject || c.id,
+				position: { x: c.x, y: c.y ?? 0, z: c.z }, yawDeg: c.rot ?? 0, scale: c.scale ?? 1, tint: c.tint ?? null, modelId: c.model ?? null,
+				motion: { takeId: t?.motion?.studioTakeId ?? null, frames: t?.motion?.frames ?? 0,
+					ikKeyCount: t?.ikState?.keys.size ?? 0, promptBlockCount: c.layer?.promptClips?.length ?? 0 },
+				capabilities: { rigReady: Boolean(t?.rig), ik: Boolean(t?.rig?.userData?.poseBind), measuredFeet: false } };
+		}), ...s.objects.map(o => ({ id: o.id, kind: "object", token: tokens.get(o.id).token, name: o.name || o.id,
+			position: { x: o.x, y: o.y ?? 0, z: o.z }, yawDeg: o.rot ?? 0,
+			rotationDeg: { x: o.rotX ?? 0, y: o.rot ?? 0, z: o.rotZ ?? 0 }, scale: { x: o.scaleX, y: o.scaleY, z: o.scaleZ },
+			renderer: o.renderer, color: o.color ?? null, ...(o.assetId ? { assetId: o.assetId } : {}),
+			parentId: o.parent ?? null, attachment: o.attach ?? null, pathPointCount: o.path?.points.length ?? 0 }))];
+	}
+	const frameRange = row => ({ startFrame: row.startFrame, endFrameExclusive: row.endFrame + 1 });
+	function assetList(s) {
+		const catalogue = studioObjectCatalogue().objects.map(({ kind }) => {
+			const entry = OBJECT_LIBRARY.find(row => row.kind === kind);
+			return { kind, name: entry?.label ?? kind, type: entry?.group === "Primitives" ? "primitive" : "set-piece" };
+		});
+		const imported = new Map();
+		for (const o of s.objects) {
+			const assetId = o.renderer === CUTOUT_KIND ? o.sourceAssetId || o.assetId : o.renderer === MESH_KIND ? o.assetId : null;
+			if (assetId && !imported.has(assetId)) imported.set(assetId, { id: assetId, name: o.name || assetId, type: o.renderer === CUTOUT_KIND ? "image" : "mesh" });
+		}
+		return [...catalogue, ...imported.values()];
+	}
+	function context() {
+		const s = refresh(), entities = entityProjection(s), registry = ports.actions?.();
+		const shot = s.shots.find(row => row.id === s.selectedShotId) ?? shotAtFrame(s.shots, s.view.frame);
+		const range = frameRange;
+		return buildStudioContext({ schema: "studio-context-v1", host: { surface: "studio", ...s.host, workspaceHandle: s.workspaceHandle },
+			revision: { scene: s.revision, physics: s.physicsRevision, view: s.viewRevision },
+			units: { distance: "m", angle: "deg", up: "+Y", yawZero: "+Z", yawPositiveToward: "+X", pivot: "base", fps: 24, rangeEnd: "exclusive" },
+			scene: { name: s.sceneName, aspect: s.aspect, floorY: 0, frameCount: s.frameCount, objectCount: s.objects.length, characterCount: s.characters.length },
+			selection: s.selection, activeCharacterId: s.activeCharacterId, view: s.view,
+			shot: shot ? { id: shot.id, name: shot.name, range: range(shot), mode: shot.camera?.mode ?? "keys" } : null, camera: s.camera,
+			// buildStudioContext selects the detailed rows and writes the real page.
+			entities, entityPage: { returned: 0, total: 0, truncated: false, nextCursor: null },
+			shots: s.shots.map(row => ({ id: row.id, name: row.name, range: range(row), keyCount: row.cameraKeys.length })), shotsTruncated: false,
+			assets: assetList(s), recentReceipts: [...receipts.values()].filter(r => r.ok).reverse().slice(0, 3).map(r => ({ id: r.receiptId, summary: r.status, canUndoDirect: ports.canUndo(r) })),
+			jobs: [], capabilities: { profile: "studio-slice-1", tools: STUDIO_TOOL_FAMILIES,
+				rigReady: Boolean(s.targets.get(s.activeCharacterId)?.rig), cameraReady: Boolean(s.camera), bridgeReady: s.bridgeReady },
+			// Every registered command; buildStudioContext keeps only its id/label index.
+			...(registry ? { actions: registry.list() } : {}) });
+	}
+	function readEnvironment() {
+		const s = refresh();
+		return { host: s.host, physicsRevision: s.physicsRevision, floor: { model: "flat", y: 0 }, objects: s.objects, frameCount: s.frameCount,
+			cast: s.characters.map(character => ({ character, ...s.targets.get(character.id) })) };
+	}
+	function remember(receipt) { if (receipt?.receiptId) receipts.set(receipt.receiptId, receipt); return receipt; }
+	function rejection(request, error, phase = "admission") {
+		// The refusal's own words are what the model acts on; the receipt keeps
+		// the first 120 characters the protocol carries.
+		const words = [...String(error?.message ?? "").trim()];
+		return validateReceipt({ ok: false, commandId: request.commandId, host: request.host ?? request.binding?.host,
+			code: error.code ?? "INVALID_ARGUMENT", phase, affectedIds: [], expectedTargets: [], currentTargets: [], mutated: false,
+			preserved: { authoredState: "unchanged" }, recovery: { action: "inspect", retryAllowed: false },
+			...(words.length ? { message: words.length > 120 ? `${words.slice(0, 119).join("")}…` : words.join("") } : {}) });
+	}
+	function admit(request) {
+		const s = refresh();
+		if (!same(validateStudioIdentity(request.host), s.host)) fail("STALE_SCENE", "The live document changed.");
+		if (request.expectedRevision !== s.revision) fail("STALE_SCENE", "Authored state changed; obtain fresh intent.");
+		if (s.busy) fail("TARGET_BUSY", "Finish the current editor gesture first.");
+		return s;
+	}
+	/** Actual state of one action target after it ran. */
+	function actionReadback(id, s) {
+		const patched = Object.entries(s.document).flatMap(([kind, value]) => {
+			const target = elementTarget(kind, value, id, s.host.sceneId);
+			return target ? elementReadback(kind, target) : [];
+		});
+		if (id === s.host.sceneId) return { selection: s.selection, activeCharacterId: s.activeCharacterId, shotId: s.selectedShotId, view: s.view,
+			...(patched.length ? { patched } : {}) };
+		if (patched.length) return { patched };
+		const shot = s.shots.find(row => row.id === id);
+		if (shot) return { name: shot.name || shot.id, range: { startFrame: shot.startFrame, endFrameExclusive: shot.endFrame + 1 } };
+		const entity = s.objects.find(row => row.id === id) ?? s.characters.find(row => row.id === id);
+		if (entity) return { name: entity.name || entity.subject || entity.id, position: { x: entity.x, y: entity.y ?? 0, z: entity.z } };
+		return { removed: true };
+	}
+	/** One registered Studio action, run for the agent through the same
+	 * registry the UI controls call. A mutation is bound to the native history
+	 * entry it pushed, so its receipt is an ordinary journal receipt that
+	 * undo_edit reverts; a job answers "started" and lands later. */
+	const patchRequests = new Map();
+	function commandBus() {
+		if (!actionBus) actionBus = createCommandBus({ registry: ports.actions(), ports: {
+			read: refresh, journal: () => {
+				const admitted = journal;
+				return { ...admitted, record: receipt => {
+					const patch = patchRequests.get(receipt.commandId);
+					return admitted.record(patch ? elementPatchReceipt(receipt, patch, refresh().document) : receipt);
+				} };
+			}, recordAction: (...args) => ports.recordAction(...args), beginAction: (...args) => ports.beginAction(...args),
+			readback: actionReadback, remember, receipt: id => receipts.get(id), isRetained: receipt => ports.isRetained(receipt),
+			canUndo: receipt => ports.canUndo(receipt), undo: () => ports.undo(), redo: () => ports.redo(),
+			history: redo => ports.history?.(redo), finishHistoryGesture: () => ports.finishHistoryGesture?.(),
+			readTarget: id => { refresh(); return tokens.get(id)?.token; },
+			captureToasts: listener => ports.captureToasts?.(listener), showRefusal: message => ports.showRefusal?.(message), emit: event => ports.emitCommandEvent?.(event),
+		} });
+		return actionBus;
+	}
+	function runAction(request, args) {
+		const { name: _name, args: _args, ...options } = request;
+		const result = commandBus().run(args.action, args.args, { ...options, origin: "agent", confirmationToken: args.confirmationToken ?? request.confirmationToken });
+		const answer = receipt => receipt.nextHost ? { ...receipt, host: receipt.nextHost } : receipt;
+		return result?.then ? result.then(answer) : answer(result);
+	}
+	function execute(request) {
+		refresh();
+		if (request.name === "run_action") return runAction(request, validateStudioCommand({ name: request.name, args: request.args }).args);
+		const alias = ports.actions?.().toolAlias?.(request.name);
+		if (alias) {
+			try { return runAction(request, { action: typeof alias.action === 'function' ? alias.action(request.args) : alias.action, args: alias.args(request.args) }); }
+			catch (error) { return rejection(request, error); }
+		}
+		const patchKind = request.name === "patch_elements" && request.args?.ops?.[0]?.target?.kind;
+		if (patchKind) {
+			try {
+				const args = elementPatchArgs(patchKind, request.args);
+				patchRequests.set(request.commandId, request);
+				return runAction(request, { action: `${patchKind}.set`, args });
+			} catch (error) { return rejection(request, error); }
+			finally { patchRequests.delete(request.commandId); }
+		}
+		const signature = JSON.stringify(request);
+		if (!same(request.host, owner)) return rejection(request, new StudioProtocolError("STALE_SCENE", "Document changed."));
+		try {
+			if (!journal.begin(request.commandId, signature)) return journal.get(request.commandId);
+			// Verification only observes: the document identity (checked above) is
+			// its whole fence, so a later edit never refuses it.
+			const { args } = validateStudioCommand({ name: request.name, args: request.args }), s = request.name === "verify_result" ? refresh() : admit(request);
+			if (request.name === "verify_result") {
+				const receipt = args.receiptId ? receipts.get(args.receiptId) : null;
+				if (args.receiptId && !receipt) fail("STALE_TARGET", "Receipt is not retained in this document.");
+				for (const id of args.targets ?? []) guard(id);
+				// A receipt edited over since is still evidence of what it did: return it
+				// marked stale with the revision it describes beside the current one.
+				const evidenceRevision = receipt ? receipt.revision.after : s.revision;
+				// Targets, and a receipt without evidence of its own, are measured now with
+				// the helpers the arrange/frame_shot receipts and the motion candidate use.
+				// Only a check nothing could compute is unsupported, and says why; a motion
+				// check computed for some characters still names the ones it skipped.
+				const scene = readCommand(), entityIds = ids => ids.filter(id => scene.objects.some(o => o.id === id) || scene.characters.some(c => c.id === id));
+				const measured = args.targets ? entityIds(args.targets) : receipt.checks ? null : entityIds(receipt.affectedIds);
+				const result = { receiptId: receipt?.receiptId ?? null, revision: s.revision, evidenceRevision, stale: evidenceRevision !== s.revision, checks: measured ? { coverage: "current-scene-targets" } : receipt.checks,
+					verification: receipt?.verification ?? null, semanticStatus: "unavailable", visualRefs: [], unsupportedChecks: [], unsupportedReasons: {} };
+				const reasons = result.unsupportedReasons, verified = [], skipped = [], pending = [];
+				for (const check of args.checks.filter(check => check !== "motion" && measured)) {
+					if (!measured.length) { reasons[check] = "No target is an object or character in the current scene."; continue; }
+					try { result.checks[check] = check === "placement" ? placementChecks(measured, scene, { bounds: ports.bounds }) : framingChecks(measured, scene, { bounds: ports.bounds }); }
+					catch (error) { if (!(error instanceof StudioProtocolError)) throw error; reasons[check] = error.message; }
+				}
+				if (args.checks.includes("motion") && !receipt?.verification) {
+					const subjects = args.targets ?? receipt.affectedIds.filter(id => s.characters.some(c => c.id === id));
+					if (!subjects.length) skipped.push("The receipt affected no character.");
+					subjects.forEach((id, index) => {
+						const character = s.characters.find(c => c.id === id), target = s.targets.get(id), name = character?.subject || id;
+						if (!character) return skipped.push(`${id} is not a character; motion checks a character's take.`);
+						if (!target?.motion) return skipped.push(`${name} has no motion take to check.`);
+						if (!target.rig) return skipped.push(`${name}'s rig is not loaded yet.`);
+						pending.push(verifyInstalledTake({ target: { ...target, character }, environment: readEnvironment(), range: args.range === "whole_clip" ? undefined : args.range, poseCast: ports.poseCast })
+							.then(verification => { verified[index] = verification; }, error => { if (!(error instanceof StudioProtocolError)) throw error; skipped.push(`${name}: ${error.message}`); }));
+					});
+				}
+				if (args.visual !== "none") {
+					if (args.visual === "contact_sheet") {
+						// One image of frames across the range, each rendered through the export
+						// path, which puts the playhead pose, shot camera and props back.
+						const frames = sampleContactSheetFrames(args.range, s.frameCount), sheet = buildContactSheet(frames, ports.renderFrameBuffer), imageId = crypto.randomUUID();
+						images.set(imageId, { dataUrl: ports.encodePng(sheet.data, sheet), width: sheet.width, height: sheet.height, frames, layout: CONTACT_SHEET_LAYOUT, revision: s.revision, receiptId: result.receiptId });
+						result.visualRefs.push({ imageId, frames, layout: CONTACT_SHEET_LAYOUT });
+					} else { const capture = ports.capture(); const imageId = crypto.randomUUID(); images.set(imageId, { ...capture, revision: s.revision, receiptId: result.receiptId }); result.visualRefs.push({ imageId }); }
+				}
+				const finish = () => {
+					const computed = verified.filter(Boolean);
+					if (computed.length) result.verification = computed.length === 1 ? computed[0] : computed;
+					if (skipped.length) reasons.motion = skipped.join(" ");
+					result.unsupportedChecks = args.checks.filter(check => reasons[check] && (check !== "motion" || !computed.length));
+					return result;
+				};
+				if (!pending.length) return finish();
+				// Motion evaluation yields between frames: answer when it settles, with the
+				// same rejection receipt a synchronous failure would journal.
+				return Promise.all(pending).then(finish).catch(error => {
+					const rejected = rejection(request, error);
+					return same(rejected.host, journal.host) ? journal.record(rejected) : rejected;
+				});
+			}
+			fail("CAPABILITY_MISSING", "Generation is owned by the server runtime.");
+		} catch (error) { const receipt = rejection(request, error); return journal.record(receipt); }
+	}
+	const handlers = {
+		read_studio_context(request) { const c = context(); if (!same(validateStudioIdentity(request.host), owner)) fail("STALE_SCENE", "This is not the requested document."); return c; },
+		inspect_studio(args) {
+			const command = validateStudioCommand({ name: "inspect_studio", args }); const c = context();
+			// Every scope carries the context: its revision is what the agent's next
+			// command is admitted at, so a scope without it leaves that admission stale.
+			if (command.args.scope === "catalogue") return { context: c, ...studioObjectCatalogue() };
+			if (command.args.scope === "document") return { context: c, scope: "document",
+				...readElementDocument(refresh().document, command.args, c.host.sceneId) };
+			// Discovery for run_action: every registered action with its label, kind,
+			// exposure and availability (the reason when unavailable). Schemas are on
+			// request: ids answer those actions' full declarations, input included.
+			if (command.args.scope === "actions") {
+				const actions = ports.actions?.()?.list() ?? [];
+				return { context: c, actions: command.args.ids ? actions.filter(row => command.args.ids.includes(row.id)) : actions.map(({ input, description, ...row }) => row) };
+			}
+			const s = refresh();
+			const wanted = row => (!args.ids || args.ids.includes(row.id)) && (!args.query || Boolean(row.name?.includes(args.query)));
+			if (["scene", "shot", "motion", "selection"].includes(command.args.scope)) {
+				const select = { shot: ["shot"], motion: ["motion", "character"] }[command.args.scope];
+				const ids = args.ids ?? (command.args.scope === "selection" ? [s.selection?.id ?? s.host.sceneId]
+					: args.query && select ? (command.args.scope === "shot" ? s.shots : entityProjection(s).filter(row => row.kind === "character")).filter(wanted).map(row => row.id) : undefined);
+				return { context: c, scope: "document", ...readElementDocument(s.document, { ...command.args, ids, select }, c.host.sceneId) };
+			}
+			// Build each page from the same complete authoritative projection; never
+			// page by slicing an already-truncated Send context.
+			// Stable id order, so an offset cursor survives unrelated edits.
+			const filtered = entityProjection(s).filter(wanted).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+			const offset = args.cursor ? validateStudioCursor(args.cursor, c) : 0, limit = command.args.limit;
+			return { context: c, entities: filtered.slice(offset, offset + limit), total: filtered.length,
+				nextCursor: offset + limit < filtered.length ? studioEntityCursor(c, offset + limit) : null };
+		},
+		operate_studio: request => execute({ ...request, name: "operate_studio" }),
+		arrange_objects: request => execute({ ...request, name: "arrange_objects" }),
+		arrange_characters: request => execute({ ...request, name: "arrange_characters" }),
+		patch_elements: request => execute({ ...request, name: "patch_elements" }),
+		frame_shot: request => execute({ ...request, name: "frame_shot" }),
+		generate_motion: request => execute({ ...request, name: "generate_motion" }),
+		verify_result: request => execute({ ...request, name: "verify_result" }),
+		undo_edit: request => runAction(request, { action: "edit.undo", args: request.args }),
+		run_action: request => execute({ ...request, name: "run_action" }),
+		resolve_studio_image(request) {
+			refresh(); const image = images.get(request.imageId);
+			if (!image || (request.receiptId && request.receiptId !== image.receiptId) || (request.revision !== undefined && request.revision !== image.revision)) fail("STALE_TARGET", "Image observation does not belong to this receipt.");
+			return image;
+		},
+		reconcile_studio_command(request) { refresh(); const value = journal.reconcile({ commandId: request.commandId, host: request.host ?? request.binding?.host }); return value.status === "not_applied" ? { ...value, evidence: value.receipt } : value; },
+	};
+	function invalidate(domain, before, after) {
+		if (before === after) return;
+		if (domain === "pose") {
+			const id = ports.read().activeCharacterId, previous = tokens.get(id);
+			if (previous) tokens.set(id, { ...previous, key: null });
+			return;
+		}
+		if (!["characters", "objects"].includes(domain) || !Array.isArray(before) || !Array.isArray(after)) return;
+		const content = row => {
+			if (!row) return null;
+			const { subject, name, tint, identityImage, sessionMotion, ...rest } = row;
+			return { ...rest, motionIdentity: identityOf(sessionMotion) };
+		};
+		for (const row of before) {
+			const next = after.find(c => c.id === row.id), previous = tokens.get(row.id);
+			if (!next) tokens.delete(row.id);
+			else if (previous && !same(content(row), content(next))) tokens.set(row.id, { ...previous, key: null });
+		}
+	}
+	return { handlers, context, guard, refresh, invalidate, get bus() { refresh(); return commandBus(); }, dispose: () => { actionBus?.dispose(); } };
+}

package/src/studio-contact-sheet.js

@@ -0,0 +1,73 @@
+// verify_result's contact sheet: which frames of the range it shows, how each
+// shot render shrinks, and where it lands on the one image the agent sees.
+// Pure over RGBA byte buffers; App.jsx supplies the render and the encoder.
+
+export const CONTACT_SHEET_COLUMNS = 3;
+export const CONTACT_SHEET_ROWS = 2;
+export const CONTACT_SHEET_LAYOUT = "3x2 row-major";
+export const CONTACT_SHEET_MAX_SIDE = 1600;
+
+/** Up to 6 frames spread evenly over a half-open range, first and last
+ * included; "whole_clip" (or no range) is timeline frames 0..frameCount-1. */
+export function sampleContactSheetFrames(range, frameCount, count = CONTACT_SHEET_COLUMNS * CONTACT_SHEET_ROWS) {
+	const { startFrame, endFrameExclusive } = range && range !== "whole_clip" ? range : { startFrame: 0, endFrameExclusive: frameCount };
+	const length = endFrameExclusive - startFrame;
+	if (length <= count) return Array.from({ length }, (_, i) => startFrame + i);
+	return Array.from({ length: count }, (_, i) => startFrame + Math.round((i * (length - 1)) / (count - 1)));
+}
+
+/** Box filter: each output pixel is the mean of the source pixels it covers. */
+export function boxDownscaleRgba(data, width, height, outWidth, outHeight) {
+	const out = new Uint8Array(outWidth * outHeight * 4);
+	for (let y = 0; y < outHeight; y += 1) {
+		const y0 = Math.floor((y * height) / outHeight), y1 = Math.max(y0 + 1, Math.floor(((y + 1) * height) / outHeight));
+		for (let x = 0; x < outWidth; x += 1) {
+			const x0 = Math.floor((x * width) / outWidth), x1 = Math.max(x0 + 1, Math.floor(((x + 1) * width) / outWidth));
+			let r = 0, g = 0, b = 0, a = 0;
+			for (let sy = y0; sy < y1; sy += 1) {
+				for (let sx = x0; sx < x1; sx += 1) {
+					const i = (sy * width + sx) * 4;
+					r += data[i]; g += data[i + 1]; b += data[i + 2]; a += data[i + 3];
+				}
+			}
+			const n = (y1 - y0) * (x1 - x0), o = (y * outWidth + x) * 4;
+			out[o] = Math.round(r / n); out[o + 1] = Math.round(g / n); out[o + 2] = Math.round(b / n); out[o + 3] = Math.round(a / n);
+		}
+	}
+	return out;
+}
+
+/** Equal tiles row-major into one buffer; empty cells stay opaque black. With
+ * bottomUp the buffer's rows run bottom-up (WebGL read-back order), so the
+ * first row of tiles is the last block of rows. */
+export function tileRgba(tiles, tileWidth, tileHeight, { columns = CONTACT_SHEET_COLUMNS, rows = CONTACT_SHEET_ROWS, bottomUp = false } = {}) {
+	const width = tileWidth * columns, height = tileHeight * rows, data = new Uint8Array(width * height * 4);
+	for (let i = 3; i < data.length; i += 4) data[i] = 255;
+	tiles.forEach((tile, index) => {
+		const column = index % columns, row = Math.floor(index / columns);
+		const top = (bottomUp ? rows - 1 - row : row) * tileHeight;
+		for (let y = 0; y < tileHeight; y += 1) {
+			data.set(tile.subarray(y * tileWidth * 4, (y + 1) * tileWidth * 4), ((top + y) * width + column * tileWidth) * 4);
+		}
+	});
+	return { data, width, height };
+}
+
+/** Render each frame (render(frame) -> { data, width, height }, rows bottom-up),
+ * shrink it so the whole sheet's longest side is at most maxSide, and tile
+ * the frames 3x2 row-major into one bottom-up buffer. */
+export function buildContactSheet(frames, render, { maxSide = CONTACT_SHEET_MAX_SIDE } = {}) {
+	const tiles = [];
+	let tileWidth, tileHeight;
+	for (const frame of frames) {
+		const shot = render(frame);
+		if (tileWidth === undefined) {
+			const scale = Math.min(1, maxSide / Math.max(shot.width * CONTACT_SHEET_COLUMNS, shot.height * CONTACT_SHEET_ROWS));
+			tileWidth = Math.max(1, Math.floor(shot.width * scale));
+			tileHeight = Math.max(1, Math.floor(shot.height * scale));
+		}
+		// The renderer reuses one read-back buffer: shrink this frame before the next render.
+		tiles.push(boxDownscaleRgba(shot.data, shot.width, shot.height, tileWidth, tileHeight));
+	}
+	return tileRgba(tiles, tileWidth, tileHeight, { bottomUp: true });
+}

package/src/studio-elements.js

@@ -1,6 +1,7 @@
 // The authored Studio surface, declared once for future patch, schema and
 // history layers. This module is intentionally data-only: it does not import
-// React or any persistence implementation.
+// React or any persistence implementation. Fields use generic set/read;
+// lifecycle and composite elements name the commands that own them.
 
 const freezeBounds = (bounds) => bounds && typeof bounds === "object"
 	? Object.freeze({ ...bounds })
@@ -9,62 +10,65 @@ const freezeBounds = (bounds) => bounds && typeof bounds === "object"
 const freezeEntry = (entry) => Object.freeze({
 	...entry,
 	...(entry.enum ? { enum: Object.freeze([...entry.enum]) } : {}),
+	...(entry.actions ? { actions: Object.freeze([...entry.actions]) } : {}),
 	...(entry.min && typeof entry.min === "object" ? { min: freezeBounds(entry.min) } : {}),
 	...(entry.max && typeof entry.max === "object" ? { max: freezeBounds(entry.max) } : {}),
 	...(entry.gizmo ? { gizmo: Object.freeze({ min: freezeBounds(entry.gizmo.min), max: freezeBounds(entry.gizmo.max) }) } : {}),
 });
 
 const entries = [
-	{ path: "character.position", type: "vec3", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", min: { x: -240, y: 0, z: -240 }, max: { x: 240, y: 240, z: 240 }, gizmo: { min: { x: -4, y: 0, z: -4 }, max: { x: 4, y: 240, z: 4 } }, note: "y is the feet" },
-	{ path: "character.rot", type: "number", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", min: -180, max: 180, angle: true, note: "yaw degrees, wrapped at the upper bound" },
-	{ path: "character.scale", type: "number", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", min: 0.2, max: 3 },
-	{ path: "character.subject", type: "string", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.hidden", type: "boolean", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.model", type: "enum", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", enum: ["y-bot-tpose", "x-bot-tpose"] },
-	{ path: "character.tint", type: "color", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.identityImage", type: "image", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", note: "data:image only" },
-	{ path: "character.pose", type: "id", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.waypoints", type: "array", persisted: true, undoDomain: "cast", agentExposure: "todo", normalizer: "createCharacterEntry", note: "agent exposure gap" },
-	{ path: "character.promptBlocks", type: "array", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry", note: "stored at layer.promptClips" },
-	{ path: "character.motionRef.url", type: "string", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.motionRef.motionId", type: "id", persisted: true, undoDomain: "cast", agentExposure: "patch", normalizer: "createCharacterEntry" },
-	{ path: "character.sessionMotion", type: "array", persisted: false, undoDomain: "cast", agentExposure: "readonly", normalizer: "createCharacterEntry", note: "dropped by createCharacterEntry" },
-	{ path: "character.ikKeys", type: "array", persisted: false, undoDomain: "cast", agentExposure: "todo", normalizer: "createCharacterEntry", note: "dropped by createCharacterEntry" },
-	{ path: "object.renderer", type: "enum", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject", enum: ["cube", "sphere", "capsule", "cylinder", "cone", "plane", "chair", "car", "small-plane"] },
-	{ path: "object.position", type: "vec3", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject", min: { x: -240, y: 0, z: -240 }, max: { x: 240, y: 240, z: 240 }, note: "y is the object's base: y=0 rests on the floor; height/supportY rise from it" },
-	{ path: "object.rotation", type: "vec3", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject", min: { x: -180, y: -180, z: -180 }, max: { x: 180, y: 180, z: 180 }, note: "rot/rotX/rotZ degrees, wrapped at the upper bound" },
-	{ path: "object.scale", type: "vec3", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject", min: { x: 0.1, y: 0.1, z: 0.1 }, max: { x: 100, y: 100, z: 100 } },
-	{ path: "object.name", type: "string", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject" },
-	{ path: "object.color", type: "color", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject" },
-	{ path: "object.parent", type: "id", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject" },
-	{ path: "object.attach", type: "id", persisted: true, undoDomain: "objects", agentExposure: "todo", normalizer: "normalizeSceneObject", note: "agent exposure gap" },
-	{ path: "object.path", type: "array", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: "normalizeSceneObject" },
-	{ path: "object.remove", type: "boolean", persisted: true, undoDomain: "objects", agentExposure: "patch", normalizer: null, note: "lifecycle operation, not a document field" },
-	{ path: "object.cutout", type: "image", persisted: true, undoDomain: "objects", agentExposure: "composite", normalizer: "normalizeSceneObject", note: "assetId-backed cutout record" },
-	{ path: "stage.keyLight.x", type: "number", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", min: -30, max: 30 },
-	{ path: "stage.keyLight.y", type: "number", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", min: 0.5, max: 30 },
-	{ path: "stage.keyLight.z", type: "number", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", min: -30, max: 30 },
-	{ path: "stage.keyLight.intensity", type: "number", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", min: 0, max: 4 },
-	{ path: "stage.keyLight.warmth", type: "number", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", min: 0, max: 1 },
-	{ path: "stage.environmentImage", type: "image", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", note: "data:image only" },
-	{ path: "stage.environment", type: "string", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", note: "location description every shot prompt is built from" },
-	{ path: "stage.style", type: "string", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", note: "look / style line for shot prompts" },
-	{ path: "stage.hasEnvSheet", type: "boolean", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", note: "author supplies an environment sheet instead of a description" },
-	{ path: "stage.camera", type: "enum", persisted: true, undoDomain: "stage", agentExposure: "patch", normalizer: "createSceneStage", enum: ["16:9", "2.39:1", "9:16", "1:1", "4:3", "12:7", "fal 480P"], note: "shotAspect/cameraPresetId/sensorId" },
-	{ path: "shot.crud", type: "array", persisted: true, undoDomain: "shot", agentExposure: "todo", normalizer: null, note: "create/split/duplicate/reorder/remove/range; agent exposure gap" },
-	{ path: "shot.cameraKeys", type: "array", persisted: true, undoDomain: "shot", agentExposure: "patch", normalizer: null, frameMin: 0 },
-	{ path: "shot.cameraRail", type: "array", persisted: true, undoDomain: "shot", agentExposure: "todo", normalizer: "repairCamera", note: "rail/crane/dolly timing; agent exposure gap" },
-	{ path: "shot.targetModel", type: "id", persisted: true, undoDomain: "shot", agentExposure: "patch", normalizer: "repairCamera" },
-	{ path: "shot.freeCamera", type: "vec3", persisted: false, undoDomain: "shot", agentExposure: "readonly", normalizer: null, note: "transient until keyed" },
-	{ path: "scenes", type: "array", persisted: true, undoDomain: null, agentExposure: "composite", normalizer: null },
-	{ path: "project", type: "string", persisted: true, undoDomain: null, agentExposure: "composite", normalizer: null, note: "save/open project file" },
-	{ path: "selection", type: "id", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null },
-	{ path: "timeline", type: "number", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null },
-	{ path: "view.mode", type: "enum", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null, enum: ["scene", "camera", "motion"] },
-	{ path: "view.partColoursGuideModeInset", type: "array", persisted: false, undoDomain: null, agentExposure: "todo", normalizer: null, note: "partColours/guideMode/inset; not a document field" },
-	{ path: "read.sceneDescription", type: "string", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null },
-	{ path: "read.captureFrame", type: "image", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null },
-	{ path: "undo", type: "boolean", persisted: false, undoDomain: null, agentExposure: "readonly", normalizer: null },
+	{ path: "character.position", type: "vec3", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", min: { x: -240, y: 0, z: -240 }, max: { x: 240, y: 240, z: 240 }, gizmo: { min: { x: -4, y: 0, z: -4 }, max: { x: 4, y: 240, z: 4 } }, note: "y is the feet" },
+	{ path: "character.rot", type: "number", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", min: -180, max: 180, angle: true, note: "yaw degrees, wrapped at the upper bound" },
+	{ path: "character.scale", type: "number", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", min: 0.2, max: 3 },
+	{ path: "character.subject", type: "string", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.hidden", type: "boolean", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.model", type: "enum", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", enum: ["y-bot-tpose", "x-bot-tpose"] },
+	{ path: "character.tint", type: "color", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.identityImage", type: "image", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", note: "data:image only" },
+	{ path: "character.pose", type: "id", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.waypoints", type: "array", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", actions: ["character.addWaypoint", "character.moveWaypoint", "character.removeWaypoint", "character.clearWaypoints"], note: "root path pins, addressed by frame" },
+	{ path: "character.promptBlocks", type: "array", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", note: "stored at layer.promptClips" },
+	{ path: "character.motionRef.url", type: "string", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.motionRef.motionId", type: "id", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	{ path: "character.sessionMotion", type: "array", persisted: false, undoDomain: "cast", normalizer: "createCharacterEntry", note: "dropped by createCharacterEntry" },
+	{ path: "character.ikKeys", type: "array", persisted: false, undoDomain: "cast", normalizer: "createCharacterEntry", actions: ["character.setIkKey", "character.removeIkKey", "character.clearIkKeys"], note: "dropped by createCharacterEntry; keys travel as JSON quaternions/positions" },
+	{ path: "object.renderer", type: "enum", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["cube", "sphere", "capsule", "cylinder", "cone", "plane", "chair", "car", "small-plane"] },
+	{ path: "object.position", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: -240, y: 0, z: -240 }, max: { x: 240, y: 240, z: 240 }, note: "y is the object's base: y=0 rests on the floor; height/supportY rise from it" },
+	{ path: "object.rotation", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: -180, y: -180, z: -180 }, max: { x: 180, y: 180, z: 180 }, note: "rot/rotX/rotZ degrees, wrapped at the upper bound" },
+	{ path: "object.scale", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: 0.1, y: 0.1, z: 0.1 }, max: { x: 100, y: 100, z: 100 } },
+	{ path: "object.name", type: "string", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
+	{ path: "object.color", type: "color", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
+	{ path: "object.parent", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
+	{ path: "object.attach", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", actions: ["object.attach", "object.detach"], note: "carried by a character's root or bone; channels convert so the prop stays put" },
+	{ path: "object.path", type: "array", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
+	{ path: "object.remove", type: "boolean", persisted: true, undoDomain: "objects", normalizer: null, note: "lifecycle operation, not a document field" },
+	{ path: "object.cutout", type: "image", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", actions: ["asset.import"], note: "assetId-backed cutout record; imported pictures and models are placed by asset.import" },
+	{ path: "stage.keyLight.x", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: -30, max: 30 },
+	{ path: "stage.keyLight.y", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0.5, max: 30 },
+	{ path: "stage.keyLight.z", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: -30, max: 30 },
+	{ path: "stage.keyLight.intensity", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 4 },
+	{ path: "stage.keyLight.warmth", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 1 },
+	{ path: "stage.environmentImage", type: "image", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "data:image only" },
+	{ path: "stage.environment", type: "string", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "location description every shot prompt is built from" },
+	{ path: "stage.style", type: "string", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "look / style line for shot prompts" },
+	{ path: "stage.hasEnvSheet", type: "boolean", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "author supplies an environment sheet instead of a description" },
+	{ path: "stage.camera", documentPath: "shotAspect", type: "enum", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", enum: ["16:9", "2.39:1", "9:16", "1:1", "4:3", "12:7", "fal 480P"], note: "output aspect ratio" },
+	{ path: "stage.cameraPresetId", type: "id", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage" },
+	{ path: "stage.sensorId", type: "enum", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", enum: ["super16", "super35", "fullFrame", "65mm"] },
+	{ path: "shot.crud", type: "array", persisted: true, undoDomain: "shot", normalizer: null, actions: ["shot.create", "shot.split", "shot.duplicate", "shot.remove", "shot.setRange", "shot.reorder"], note: "create/split/duplicate/reorder/remove/range through the shared action registry" },
+	{ path: "shot.cameraKeys", type: "array", persisted: true, undoDomain: "shot", normalizer: null, frameMin: 0 },
+	{ path: "shot.cameraRail", type: "array", persisted: true, undoDomain: "shot", normalizer: "repairCamera", actions: ["shot.setCameraRail", "shot.clearCameraRail"], note: "rail points; crane/dolly timing follow the shot's camera block" },
+	{ path: "shot.targetModel", type: "id", persisted: true, undoDomain: "shot", normalizer: "repairCamera" },
+	{ path: "shot.freeCamera", type: "vec3", persisted: false, undoDomain: "shot", normalizer: null, note: "transient until keyed" },
+	{ path: "scenes", type: "array", persisted: true, undoDomain: null, normalizer: null, actions: ["scene.create", "scene.duplicate", "scene.rename", "scene.delete", "scene.switch"], note: "the project's scene list and the open scene; outside the undo history" },
+	{ path: "project", type: "string", persisted: true, undoDomain: null, normalizer: null, actions: ["project.save"], note: "save to the current project file; opening one needs the user's file picker" },
+	{ path: "selection", type: "id", persisted: false, undoDomain: null, normalizer: null },
+	{ path: "timeline", type: "number", persisted: false, undoDomain: null, normalizer: null },
+	{ path: "view.mode", type: "enum", persisted: false, undoDomain: null, normalizer: null, enum: ["scene", "pose", "camera", "motion"] },
+	{ path: "view.partColoursGuideModeInset", type: "array", persisted: false, undoDomain: null, normalizer: null, actions: ["view.setPartColours", "view.setGuideMode", "view.setInset"], note: "partColours/guideMode/inset; viewer settings, not document fields" },
+	{ path: "read.sceneDescription", type: "string", persisted: false, undoDomain: null, normalizer: null },
+	{ path: "read.captureFrame", type: "image", persisted: false, undoDomain: null, normalizer: null },
+	{ path: "undo", type: "boolean", persisted: false, undoDomain: null, normalizer: null },
 ];
 
 export const STUDIO_ELEMENTS = Object.freeze(entries.map(freezeEntry));
@@ -76,3 +80,6 @@ export function elementByPath(path) {
 export function elementsFor(normalizer) {
 	return STUDIO_ELEMENTS.filter((entry) => entry.normalizer === normalizer);
 }
+
+// One writable vocabulary for UI and agent commands, not a second allowlist.
+export const isSettableElement = element => element.persisted !== false && !element.actions && !element.readOnly;