cozyclay 1.9.0 → 2.0.0

package/src/studio-actions.js

@@ -0,0 +1,210 @@
+// One Studio action registry for the editor UI and the agent. The
+// declarations below are data shared with the sidecar (ids, descriptions,
+// input schemas, kinds); the editor registers ONE implementation per id, and
+// both its UI controls and the agent's `run_action` family call
+// `registry.run(id, args)`. No React, renderer or Node imports.
+import { StudioProtocolError, StudioSchemas, freezeStudioData, validateStudioSchema } from "./studio-agent-protocol.js";
+
+/** mutation: authored, undoable, answered with a journal receipt.
+ * transient: view state only. job: long-running work (a generation, an
+ * export); it answers "started", or "completed" with its output when it runs
+ * to its end. A job that needs longer than the hub's 30 s default declares
+ * `timeoutMs` (at most the hub's 300 s ceiling); one that starts a motion
+ * generation declares `generation: "motion"`, the agent's one per message.
+ * document: project-level work outside the undo history (scenes, the project
+ * file); it answers "completed", with the new host when the open scene moved. */
+export const STUDIO_ACTION_KINDS = freezeStudioData(["mutation", "transient", "job", "document"]);
+
+const idSchema = StudioSchemas.TargetGuard.properties.targetId;
+const frame = { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+const input = (required = {}, optional = {}) => ({ type: "object", properties: { ...required, ...optional }, required: Object.keys(required), additionalProperties: false });
+const shotId = { shotId: idSchema };
+const sceneId = { sceneId: idSchema };
+const NOT_UNDOABLE = "Scenes are outside the undo history: undo_edit and Ctrl+Z cannot revert this.";
+const SCENE_MOVES = "The open scene changes, so later commands in this message are admitted in it; the receipt's host names it.";
+const characterId = { characterId: idSchema };
+/** A world floor point in metres; y is the floor. */
+const floorPoint = input({ x: { type: "number" }, z: { type: "number" } });
+const waypointFrame = { ...frame, minimum: 1 };
+/** The tracks an IK key stores (src/ardy/ik.js IK_TRACKS and FK_TRACKS). A
+ * chain track keys its three bones (upper, lower, end); a joint track one. */
+export const STUDIO_IK_CHAIN_TRACKS = freezeStudioData(["leftHand", "rightHand", "leftFoot", "rightFoot"]);
+export const STUDIO_IK_JOINT_TRACKS = freezeStudioData(["hips", "spine", "chest", "neck", "head", "leftShoulder", "rightShoulder"]);
+const num = { type: "number" };
+const perBone = items => ({ type: "array", items, minItems: 1, maxItems: 3 });
+const quaternion = input({ x: num, y: num, z: num, w: num });
+/** One track's key: the IK state's { q, p, baseQ, basePos, chainP,
+ * keepTranslations, blend, pin } with quaternions as {x,y,z,w} and positions
+ * as {x,y,z}; blend is the key's own correction range in frames (src/ardy/ik.js
+ * correctionWeight), absent for the editor's default range; pin is the id of
+ * the range pin that baked the key (src/ardy/range-pin.js). */
+const ikTrackKey = input({}, { q: perBone(quaternion), p: StudioSchemas.Vec3, baseQ: perBone(quaternion), basePos: StudioSchemas.Vec3,
+	chainP: perBone(StudioSchemas.Vec3), keepTranslations: { type: "boolean" }, blend: { type: "integer", minimum: 1, maximum: 240 },
+	pin: { type: "string", minLength: 1, maxLength: 64 } });
+const ikTracks = input({}, Object.fromEntries([...STUDIO_IK_CHAIN_TRACKS, ...STUDIO_IK_JOINT_TRACKS].map(track => [track, ikTrackKey])));
+/** The bones an object can ride (src/scene-objects.js SCENE_ATTACH_BONES). */
+export const STUDIO_ATTACH_BONES = freezeStudioData(["hips", "spine", "chest", "neck", "head", "leftShoulder", "leftElbow", "leftHand",
+	"rightShoulder", "rightElbow", "rightHand", "leftKnee", "leftFoot", "rightKnee", "rightFoot"]);
+/** The shot frame's composition guides (src/shot-guides.js GUIDE_MODES). */
+const GUIDE_MODES = freezeStudioData(["off", "thirds", "golden", "center", "safe"]);
+/** The image models the Studio writes Send-to-AI prompts for (src/shot.js IMAGE_MODELS). */
+const AI_IMAGE_MODELS = freezeStudioData(["nano_banana_pro", "nano_banana_2", "gpt_image_2", "seedream_5", "flux_2"]);
+const WAYPOINT_RULES = "Pins sit at least 8 frames apart, the walk between two pins must stay within 0.5-3 m/s, and x/z are clamped to +/-11 m; a pin that breaks a rule is refused with the frame or distance that would work.";
+
+export const STUDIO_ACTIONS = freezeStudioData([
+	{ id: "shot.create", label: "Add shot", kind: "mutation", undoDomain: "shot", input: input(),
+		description: "Add a new shot at the playhead, keyed with the current camera framing (the timeline's + Add shot). Move the playhead first with operate_studio { frame }. When the playhead is inside a shot, the new one goes in the next free gap." },
+	{ id: "shot.split", label: "Split shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
+		description: "Cut a shot in two at the playhead. The playhead must be inside that shot, after its first frame; the second half starts at the playhead." },
+	{ id: "shot.duplicate", label: "Duplicate shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
+		description: "Copy a shot, its camera and its keys into the next free gap on the timeline." },
+	{ id: "shot.remove", label: "Delete shot", kind: "mutation", undoDomain: "shot", input: input(shotId),
+		description: "Delete a shot and leave its frames as free-camera time." },
+	{ id: "shot.setRange", label: "Set shot range", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, range: StudioSchemas.FrameRange }),
+		description: "Move a shot's start and end to a half-open frame range. Edges are clamped to the timeline and refused where they would overlap another shot; the receipt's delta shows the range that landed." },
+	{ id: "shot.reorder", label: "Move shot", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, startFrame: frame }),
+		description: "Move a shot in time to start at startFrame, keeping its length and camera keys. Refused (a noop) where it would overlap another shot." },
+	{ id: "motion.generateAllBlocks", label: "Generate all blocks", kind: "job", generation: "motion", domain: "motion", background: true, input: input(),
+		description: "Generate the active character's motion from all of its prompt blocks, like the top-bar Generate Motion button when prompt blocks have text. It starts a job and returns status \"started\"; the take lands in the editor when the job finishes. Counts as the one motion generation of this message." },
+	{ id: "character.addWaypoint", label: "Add root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, position: floorPoint }, { frame: waypointFrame }),
+		description: `Pin a character's root path: at frame, the character's root stands at position (world x/z metres). Frame 0 is the character's own spot, so pins start at frame 1 and each frame holds one pin. Omit frame to pace the pin at a walk (1.4 m/s) from the previous one. ${WAYPOINT_RULES} Read paths with inspect_studio { scope: "motion" }.` },
+	{ id: "character.moveWaypoint", label: "Move root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, frame: waypointFrame, position: floorPoint }),
+		description: `Move the character's root waypoint at frame to a new floor position (world x/z metres), keeping its frame. ${WAYPOINT_RULES}` },
+	{ id: "character.removeWaypoint", label: "Remove root waypoint", kind: "mutation", undoDomain: "cast", input: input({ ...characterId, frame: waypointFrame }),
+		description: "Remove the character's root waypoint at frame." },
+	{ id: "character.clearWaypoints", label: "Clear root path", kind: "mutation", undoDomain: "cast", input: input(characterId),
+		description: "Remove every root waypoint of the character, leaving its motion unconstrained by a path." },
+	{ id: "character.setIkKey", label: "Set IK key", kind: "mutation", undoDomain: "motion", input: input({ ...characterId, frame, tracks: ikTracks }),
+		description: "Key a character's IK correction layer at frame, the same key a pose drag bakes. tracks maps a track id to its key: q is the bones' LOCAL rotations as unit quaternions {x,y,z,w}, three for a chain track (leftHand, rightHand, leftFoot, rightFoot: upper, lower and end bone) and one for a joint track (hips, spine, chest, neck, head, leftShoulder, rightShoulder); p is a joint's local position {x,y,z} (the hips' height and lean). Optional baseQ/basePos give the take's own pose the key was made over, so it applies as a delta on the take; chainP gives a chain's three local bone positions; keepTranslations keeps them over the take's; blend (frames, 1-240) is how far this key's correction eases into the take around it, 6 when omitted; pin (1-64 characters) tags the key as baked by that range pin. A key needs q or p. Each named track replaces its key at frame and starts evaluating; other tracks at that frame stay. Keyed frames are in inspect_studio { scope: \"motion\" } ikKeyFrames." },
+	{ id: "character.removeIkKey", label: "Delete IK key", kind: "mutation", undoDomain: "motion", input: input({ ...characterId, frame }),
+		description: "Delete the character's whole IK key at frame (every track keyed there), like the Full-Body lane's delete." },
+	{ id: "character.clearIkKeys", label: "Clear IK keys", kind: "mutation", undoDomain: "motion", input: input(characterId),
+		description: "Delete every IK key of the character, returning it to its take or pose without corrections." },
+	{ id: "shot.setCameraRail", label: "Set camera rail", kind: "mutation", undoDomain: "shot",
+		input: input({ ...shotId, points: { type: "array", items: floorPoint, minItems: 2, maxItems: 512 } }),
+		description: "Lay a shot's dolly rail through points (world floor x/z metres, in travel order) and put the shot's camera on it, like drawing the rail in the Top-View. It replaces any rail the shot had; an authored rail-follow range is kept, otherwise the camera travels the rail over the whole shot. Read rails with inspect_studio { scope: \"shot\" }." },
+	{ id: "shot.clearCameraRail", label: "Delete camera rail", kind: "mutation", undoDomain: "shot", input: input(shotId),
+		description: "Delete a shot's camera rail; the shot's camera goes back to following its subject at the current distance." },
+	{ id: "object.attach", label: "Attach to character", kind: "mutation", undoDomain: "objects",
+		input: input({ objectId: idSchema, ...characterId }, { bone: { type: "string", enum: STUDIO_ATTACH_BONES } }),
+		description: "Make a scene object ride a character, like dropping it on the character's Hierarchy row: on one bone (a cup in the right hand: bone \"rightHand\") or, with bone omitted, on the character's animated root so it travels with the body. The object keeps its place on screen: its position, rotation and scale are rewritten into the new frame (local to that bone while attached), and it leaves any group. Needs the character's rig on stage." },
+	{ id: "object.detach", label: "Detach object", kind: "mutation", undoDomain: "objects", input: input({ objectId: idSchema }),
+		description: "Put an attached or grouped object back in the world where it is now, like the Inspector's Detach or dropping it on the Props row: it stops following the character, keeps its current world placement and leaves any group." },
+	{ id: "view.setPartColours", label: "Part colours", kind: "transient", input: input({ mode: { type: "string", enum: ["off", "flat", "shaded"] } }),
+		description: "Paint the characters in stable per-body-part colours (the View menu's Part colours): flat colours, shaded colours that keep the surface lighting (the look motion reading from a frame needs), or off. A viewer setting: never saved in the scene or undone." },
+	{ id: "view.setGuideMode", label: "Composition guides", kind: "transient", input: input({ mode: { type: "string", enum: GUIDE_MODES } }),
+		description: "Show a composition guide over the shot frame: rule of thirds, golden ratio, center cross, safe areas, or off. Overlay only, never in exported pixels; a viewer setting that is never undone." },
+	{ id: "view.setInset", label: "Top-View inset", kind: "transient", input: input({ collapsed: { type: "boolean" } }),
+		description: "Fold (collapsed: true) or unfold the Top-View inset pane over the viewport. A viewer setting that is never undone." },
+	{ id: "export.shotVideo", exposure: "confirm", confirmationReason: "Exporting writes a video file outside the Studio.", label: "Export video (mp4)", kind: "job", timeoutMs: 300_000, input: input({}, shotId),
+		description: "Record a shot to an MP4 (camera move and character motion, no editor chrome), like the Export menu's Video (mp4), and ask the browser to download it. With shotId it records that shot's own range; without it, what the menu records: the whole take when there is motion, else the shot under the playhead (else the first shot), keyed from the current camera if it has no keys. Waits until the file is encoded (up to 5 minutes) and answers status \"completed\" with output.fileName and output.frameCount. One export at a time; not a motion generation." },
+	{ id: "scene.create", label: "New scene", kind: "document", input: input(),
+		description: `Add an empty scene (named SCENE 01, SCENE 02, ...) after the others and open it, like the scene menu's New scene. ${SCENE_MOVES} ${NOT_UNDOABLE}` },
+	{ id: "scene.duplicate", label: "Duplicate scene", kind: "document", input: input(sceneId),
+		description: `Copy a scene (objects, shots, cast and stage) right after it and open the copy, like the Hierarchy scene menu's Duplicate. ${SCENE_MOVES} ${NOT_UNDOABLE}` },
+	{ id: "scene.rename", label: "Rename scene", kind: "document", input: input({ ...sceneId, name: { type: "string", minLength: 1, maxLength: 240 } }),
+		description: `Rename a scene; a name another scene already has gets a number. ${NOT_UNDOABLE}` },
+	{ id: "scene.delete", exposure: "confirm", confirmationReason: "Deleting a scene cannot be undone.", label: "Delete scene", kind: "document", input: input(sceneId),
+		description: `Delete a scene and everything in it, like the Hierarchy scene menu's Delete; delete only a scene the user asked to delete. The last scene cannot be deleted. Deleting the open scene opens its neighbour. ${SCENE_MOVES} ${NOT_UNDOABLE}` },
+	{ id: "scene.switch", label: "Open scene", kind: "document", input: input(sceneId),
+		description: `Open another scene of the project, like the scene pill's menu; the scene being left keeps its state. ${SCENE_MOVES}` },
+	{ id: "project.save", exposure: "confirm", confirmationReason: "Saving may overwrite a file or open a file picker.", label: "Save project", kind: "document", input: input(),
+		description: "Save the whole project to its current file, like the Project menu's Save Project, and answer status \"completed\" with output.fileName. A browser file picker opens only from the user's own click, so it is refused, with the reason, when the project has no file yet this session or the browser must re-grant access to it; ask the user to press Save Project once. An unnamed project opens the Save dialog for the user to name it. Browsers without file access download the project file instead." },
+	{ id: "asset.import", label: "Import asset", kind: "mutation", undoDomain: "objects",
+		input: input({ source: { type: "string", minLength: 1, maxLength: 8_000_000, pattern: "^(data:|https?://)" }, name: { type: "string", minLength: 1, maxLength: 120 },
+			placeAs: { type: "string", enum: ["cutout", "backdrop", "mesh"] } }),
+		description: "Import a picture or a 3D model into the scene through the editor's own import path and place it: \"cutout\" stands a picture up as a 1.8 m card in front of the camera, \"backdrop\" as a 5 m plate 12 m down the shot camera's view, facing it, and \"mesh\" stands a GLB, OBJ or FBX model on the floor in front of the camera. source is a data: URL (up to 8 MB of text) or an http(s) URL the editor fetches (its server must allow cross-origin reads); name is the file name with its extension (poster.png, chair.glb). One undo entry; the new object is in affectedIds and its asset id in the summary. A file on the user's disk needs their own click: ask them to drop it on the Assets shelf." },
+	{ id: "object.duplicate", label: "Duplicate object", kind: "mutation", undoDomain: "objects", input: input({}, { objectId: idSchema }),
+		description: "Copy a scene object (the selected one when objectId is omitted) and place the copy half a metre beside it." },
+	{ id: "ai.prepareShot", label: "Send to AI", kind: "job", input: input({}, { mode: { type: "string", enum: ["image", "video"] }, model: { type: "string", enum: AI_IMAGE_MODELS } }),
+		description: "Prepare the Studio's Send-to-AI package for the shot under the playhead (else the current camera): the prompt for an external image or video model, written from the shot's camera, cast, poses, environment and style, plus reference frames rendered from the shot camera (its first and last camera key when it has keys). No AI service is called. mode \"image\" is a still, \"video\" a shot with its camera move; model is the image model the prompt is written for (image mode only). Each omitted choice keeps the Studio's current one; a given one becomes it. The Studio opens its result panel, where the user copies the prompt and downloads the frames; the frame images stay there and are not in the answer. Answers status \"completed\" with output.prompt, mode, modelLabel, shot (id, name, range), aspectRatio, cameraMode and referenceFrames (how many frames the panel shows). Changes nothing in the scene; not a motion generation." },
+	// The instruction leads the H3 prompt, which the motion API caps at 4000
+	// characters with its camera-lock text (about 225) appended.
+	{ id: "motion.generateFromVideo", exposure: "confirm", confirmationReason: "AI video motion uses a paid external generation.", label: "Generate motion (AI video)", kind: "job", generation: "motion", timeoutMs: 300_000,
+		input: input({ instruction: { type: "string", minLength: 1, maxLength: 3700 } }),
+		description: "Make the active character perform instruction through a hosted AI video model (Fal H3 Max Turbo, 480P), like the agent panel's Generate motion button. It sends the character's pose frame (pose A from the Fal card, else a fresh capture from the shot camera) with the instruction to the hosted model, and each run spends one of the account's daily AI video generations. Run it only when the user explicitly asked for AI-video motion; for ordinary motion use generate_motion or motion.generateAllBlocks. The capture needs the character's full body inside the shot frame and shaded part colours (view.setPartColours { mode: \"shaded\" }); a prompt the user hand-edited in the Fal card is sent instead of instruction. Waits for the clip (up to 5 minutes) and answers status \"completed\" with output.videoUrl, resolution, durationSeconds, ingested, frames, fps and dailyRemaining. The clip is ingested as Video capture footage and the timeline takes its length and frame rate; no take is installed until GVHMR extraction runs on it in the Video capture panel. Counts as the one motion generation of this message." },
+]);
+export const STUDIO_ACTION_IDS = freezeStudioData(STUDIO_ACTIONS.map(action => action.id));
+
+const fail = (code, message) => { throw new StudioProtocolError(code, message); };
+
+/** A refusal an editor control can also meet. `message` is written for the
+ * model; `uiMessage` is the localized text the editor's UI door shows a
+ * person. A refusal without one stays silent in the UI. */
+export function studioActionRefusal(code, message, uiMessage) {
+	return Object.assign(new StudioProtocolError(code, message), { uiMessage });
+}
+// A localized toast producer is evaluated twice, without showing it twice:
+// once for the existing UI and once in English for command evidence.
+export function resolveStudioToast(value, isKo, ko) {
+	return typeof value === "function" ? { uiMessage: value(isKo, ko), message: value(false, en => en) } : { uiMessage: value, message: value };
+}
+const unknown = (id, known) => fail("INVALID_ARGUMENT", `Unknown Studio action "${id}". Known actions: ${known.join(", ")}. List them with inspect_studio { scope: "actions" }.`);
+
+export function studioActionDeclaration(id) {
+	return STUDIO_ACTIONS.find(action => action.id === id) ?? unknown(id, STUDIO_ACTION_IDS);
+}
+
+/** `readState` is the editor's current action state; when it is supplied,
+ * run() refuses an unavailable action with its reason before anything runs. */
+export function createStudioActionRegistry({ readState } = {}) {
+	const entries = new Map();
+	const availability = (entry, state) => {
+		const verdict = entry.available(state);
+		if (verdict !== true && (typeof verdict !== "string" || !verdict.trim())) throw new Error(`Studio action ${entry.id} must answer availability with true or a reason.`);
+		return verdict;
+	};
+	const settled = (id, result) => {
+		if (!Array.isArray(result?.affectedIds) || result.affectedIds.some(value => typeof value !== "string") || typeof result.summary !== "string") {
+			throw new Error(`Studio action ${id} must return { affectedIds, summary }.`);
+		}
+		return { affectedIds: [...result.affectedIds], summary: result.summary, ...(result.output === undefined ? {} : { output: structuredClone(result.output) }) };
+	};
+	const registry = {
+		register(entry) {
+			if (typeof entry?.id !== "string" || !new RegExp(idSchema.pattern).test(entry.id)) throw new Error("A Studio action needs an id.");
+			if (entries.has(entry.id)) throw new Error(`Studio action ${entry.id} is already registered.`);
+			if (!STUDIO_ACTION_KINDS.includes(entry.kind)) throw new Error(`Studio action ${entry.id} has an unknown kind.`);
+			if (entry.input?.type !== "object" || !entry.input.properties || !Array.isArray(entry.input.required)) throw new Error(`Studio action ${entry.id} needs an object input schema.`);
+			if (typeof entry.available !== "function") throw new Error(`Studio action ${entry.id} needs available(state).`);
+			if (typeof entry.run !== "function") throw new Error(`Studio action ${entry.id} needs run(args).`);
+			if (entry.timeoutMs !== undefined && (!Number.isSafeInteger(entry.timeoutMs) || entry.timeoutMs < 1 || entry.timeoutMs > 300_000)) throw new Error(`Studio action ${entry.id} timeoutMs must be 1..300000.`);
+			if (entry.exposure !== undefined && !["open", "confirm", "ui-only"].includes(entry.exposure)) throw new Error(`Studio action ${entry.id} has an invalid exposure.`);
+			entries.set(entry.id, Object.freeze({ exposure: "open", ...entry }));
+			return registry;
+		},
+		get(id) { return entries.get(id) ?? unknown(id, [...entries.keys()]); },
+		ids() { return [...entries.keys()]; },
+		state() { return readState?.(); },
+		/** Available actions carry their description and input schema;
+		 * unavailable ones carry the reason instead of arguments. The declared
+		 * hub timeout and generation travel with each, so no caller keeps its
+		 * own copy of them. */
+		list(state = readState?.()) {
+			return [...entries.values()].map(entry => {
+				const verdict = availability(entry, state);
+				const row = { id: entry.id, label: entry.label, kind: entry.kind, description: entry.description, exposure: entry.exposure,
+					...(entry.timeoutMs === undefined ? {} : { timeoutMs: entry.timeoutMs }), ...(entry.generation ? { generation: entry.generation } : {}) };
+				return verdict === true ? { ...row, available: true, input: entry.input } : { ...row, available: false, reason: verdict };
+			});
+		},
+		prepare(id, args = {}) {
+			const entry = registry.get(id);
+			const validated = validateStudioSchema(entry.input, args ?? {}, "INVALID_ARGUMENT", "$.args");
+			if (readState) {
+				const verdict = availability(entry, readState());
+				if (verdict !== true) fail("TARGET_NOT_READY", verdict);
+			}
+			return { entry, args: validated };
+		},
+		invoke(entry, args, context) {
+			const result = entry.run(args, context);
+			return typeof result?.then === "function" ? result.then(value => settled(entry.id, value)) : settled(entry.id, result);
+		},
+		run(id, args = {}, context) {
+			const prepared = registry.prepare(id, args);
+			return registry.invoke(prepared.entry, prepared.args, context);
+		},
+	};
+	return registry;
+}

package/src/studio-agent-commands.js

@@ -1,15 +1,13 @@
 // Studio composites prepare private domain drafts; the App owns publication,
 // history, gesture fences and semantic revision/telemetry. No UI callbacks here.
 import { Euler, Vector3, PerspectiveCamera } from 'three';
-import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, supportHeightForObject, OBJECT_LIBRARY } from './scene-objects.js';
-import { createCharacterEntry, createSceneStage } from './scenes.js';
-import { createShotAuthoringDocument } from './shot-authoring.js';
-import { elementByPath } from './studio-elements.js';
+import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, isEffectivelyHidden, supportHeightForObject, OBJECT_LIBRARY } from './scene-objects.js';
+import { createCharacterEntry } from './scenes.js';
 import { createShot, shotAtFrame } from './cuts.js';
 import { captureFraming } from './camera-move.js';
 import { createStableItemId } from './stable-items.js';
 import { focalMmToFov, SENSOR_FORMATS } from './shot.js';
-import { StudioProtocolError, StudioSchemas, STUDIO_PATCH_DOMAINS, STUDIO_PATCH_KINDS, STUDIO_PATCH_DESCRIPTORS, validateStudioSchema, validateStudioCommand, validateStudioIdentity, validateReceipt, freezeStudioData, utf8ByteLength } from './studio-agent-protocol.js';
+import { StudioProtocolError, StudioSchemas, STUDIO_PATCH_KINDS, STUDIO_PATCH_DESCRIPTORS, validateStudioSchema, validateStudioIdentity, validateReceipt, freezeStudioData } from './studio-agent-protocol.js';
 
 const DEG = Math.PI / 180, EPS = 1e-8, CHARACTER_SUPPORT_TOLERANCE = 5e-3;
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -57,7 +55,7 @@ function support(spec, state) {
   const id = spec.onObject ?? (typeof spec.support === 'object' ? spec.support.objectId : null);
   if (!id) return { y: state.floorY, label: 'floor' };
   const object = entityById(state, id);
-  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'car', 'small-plane'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
+  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'car', 'small-plane'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS || isEffectivelyHidden(object, state.objects, state.characters)) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
   return { y: object.y + supportHeightForObject(object) * object.scaleY, label: `object:${id}`, object };
 }
 function facingYaw(spec, entity, state) {
@@ -120,8 +118,16 @@ function place(entity, op, state, ports) {
 }
 function overlapsFor(entity, state, ports) {
   const own = aabb(geometry(entity, state, ports));
-  return [...state.objects, ...state.characters].filter(e => e.id !== entity.id && !e.hidden).map(other => ({ id: other.id, bounds: aabb(geometry(other, state, ports)) })).map(other => ({ ...other, depth: overlap(own, other.bounds) })).filter(o => o.depth > EPS);
+  return [...state.objects, ...state.characters].filter(e => e.id !== entity.id && !isEffectivelyHidden(e, state.objects, state.characters)).map(other => ({ id: other.id, bounds: aabb(geometry(other, state, ports)) })).map(other => ({ ...other, depth: overlap(own, other.bounds) })).filter(o => o.depth > EPS);
 }
+function overlapsOf(ids, state, ports) {
+  const entities = [...state.objects, ...state.characters];
+  return ids.flatMap(id => { const e = entities.find(row => row.id === id); return e ? overlapsFor(e, state, ports) : []; });
+}
+const overlapEvidence = overlaps => ({ coverage: 'same-frame-world-AABB-proxies', overlapIds: [...new Set(overlaps.map(o => o.id))].slice(0, 100), maximumFootprintOverlapM: Math.max(0, ...overlaps.map(o => o.depth)) });
+/** Placement evidence for entity ids in the given scene: the same-frame AABB
+ * overlap an arrangement receipt reports for the entities it moved. */
+export const placementChecks = (ids, state, ports) => overlapEvidence(overlapsOf(ids, state, ports));
 function avoid(entity, relation, state, ports) {
   const blocked = overlapsFor(entity, state, ports);
   if (!blocked.length) return entity;
@@ -143,7 +149,7 @@ function transformPatch(op, isObject) {
   if (op.rotationDeg) Object.assign(patch, { rotX: op.rotationDeg.x, rot: op.rotationDeg.y, rotZ: op.rotationDeg.z });
   return patch;
 }
-function arrangement(command, before, ports) {
+export function arrangement(command, before, ports) {
   const isObject = command.name === 'arrange_objects', key = isObject ? 'objects' : 'characters';
   let rows = before[key];
   const relations = [], warnings = [];
@@ -188,7 +194,7 @@ function arrangement(command, before, ports) {
   }
   const after = { ...before, [key]: rows };
   const affectedIds = [...new Set([...before[key], ...rows].map(e => e.id))].filter(id => !equal(before[key].find(e => e.id === id), rows.find(e => e.id === id)));
-  const overlaps = affectedIds.flatMap(id => { const e = rows.find(e => e.id === id); return e ? overlapsFor(e, after, ports) : []; });
+  const overlaps = overlapsOf(affectedIds, after, ports);
   for (const relation of relations) {
     if (!relation.spec.relativeTo) continue;
     const subject = rows.find(e => e.id === relation.id), reference = entityById(after, relation.spec.relativeTo);
@@ -203,7 +209,7 @@ function arrangement(command, before, ports) {
   if (relations.some(r => r.adjustmentM)) warnings.push({ code: 'OUTWARD_ADJUSTMENT', count: relations.filter(r => r.adjustmentM).length });
   const relation = relations.length === 1 ? relations[0] : null;
   return { domain: isObject ? 'objects' : 'cast', draft: equal(rows, before[key]) ? before[key] : rows, affectedIds,
-    checks: { coverage: 'same-frame-world-AABB-proxies', overlapIds: [...new Set(overlaps.map(o => o.id))].slice(0, 100), maximumFootprintOverlapM: Math.max(0, ...overlaps.map(o => o.depth)),
+    checks: { ...overlapEvidence(overlaps),
       ...(relation ? { support: relation.support, baseY: relation.baseY, relationSatisfied: true, ...(relation.axis ? { basis: relation.basis, requestedGapM: relation.requestedGapM, actualGapM: relation.actualGapM } : {}) } : {}) },
     warnings, details: relations.map(({ axis, ...rest }) => rest) };
 }
@@ -211,7 +217,29 @@ function arrangement(command, before, ports) {
 const FRACTIONS = { 'extreme close-up': 3.4, 'close-up': 2.2, 'medium close-up': 1.375, 'medium shot': 0.975, 'medium-wide shot': 0.66, 'wide shot': 0.41, 'extreme wide shot': 0.2 };
 const LEVELS = { ground: 0.3 / 1.8, low: 0.7 / 1.8, hip: 1.1 / 1.8, eye: 1.65 / 1.8, high: 2.1 / 1.8, overhead: 2.8 / 1.8 };
 const ANGLES = { front: 0, 'front three-quarter': 40, profile: 90, 'rear three-quarter': 140, back: 180 };
-function frameDraft(command, state, ports) {
+/** Where subject bound points land through one camera: the evidence a
+ * frame_shot receipt reports, plus the screen box its details keep. */
+function projectSubject(points, camera, fov, aspectRatio) {
+  const direction = vector(camera.lookAt).sub(vector(camera.position));
+  const projection = new PerspectiveCamera(fov / DEG, aspectRatio, 0.01, 10000);
+  projection.position.copy(vector(camera.position)); projection.lookAt(vector(camera.lookAt)); projection.updateMatrixWorld(true);
+  const screen = points.map(p => p.clone().project(projection));
+  const screenBounds = aabb(screen);
+  const behindCamera = points.some(p => p.clone().sub(projection.position).dot(direction) <= 0);
+  // Measured projection, not distance to an arbitrary aim point. Moving lookAt
+  // along the same ray cannot change the subject's observed screen coverage.
+  const screenFraction = (screenBounds.y.max - screenBounds.y.min) / 2;
+  const derivedSize = [['extreme close-up', 2.8], ['close-up', 1.6], ['medium close-up', 1.15], ['medium shot', 0.8], ['medium-wide shot', 0.52], ['wide shot', 0.3], ['extreme wide shot', 0]].find(([, threshold]) => screenFraction >= threshold)[0];
+  return { screenBounds, checks: { coverage: 'same-frame-subject-bounds-projection', screenFraction, derivedSize, behindCamera, clipped: behindCamera || screen.some(p => Math.abs(p.x) > 1 || Math.abs(p.y) > 1 || p.z < -1 || p.z > 1) } };
+}
+/** Framing evidence for entity ids through the current shot camera at the
+ * current frame: the same subject-bounds projection frame_shot reports. */
+export function framingChecks(ids, state, ports) {
+  if (!state.camera || !SENSOR_FORMATS[state.filmback?.sensorId] || !(state.filmback.aspectRatio > 0)) fail('TARGET_NOT_READY', 'The shot camera and filmback must be available.');
+  const points = ids.flatMap(id => geometry(entityById(state, id), state, ports));
+  return projectSubject(points, state.camera, focalMmToFov(state.camera.focalMm, state.filmback.sensorId, state.filmback.aspectRatio), state.filmback.aspectRatio).checks;
+}
+export function frameDraft(command, state, ports) {
   if (state.frameCount <= 0) fail('TARGET_NOT_READY', 'A nonempty timeline is required.');
   const subject = state.characters.find(e => e.id === command.args.subjectIds[0]);
   if (!subject || subject.hidden) fail('TARGET_NOT_READY', 'Framing requires one visible character.');
@@ -248,188 +276,14 @@ function frameDraft(command, state, ports) {
   }
   const nextShot = { ...shot, cameraKeys: keys, camera: { ...shot.camera, mode: 'keys' } };
   const shots = created ? [nextShot] : state.shotDocument.shots.map(s => s.id === shot.id ? nextShot : s);
-  const projection = new PerspectiveCamera(fov / DEG, state.filmback.aspectRatio, 0.01, 10000);
-  projection.position.copy(vector(camera.position)); projection.lookAt(vector(camera.lookAt)); projection.updateMatrixWorld(true);
-  const screen = points.map(p => p.clone().project(projection));
-  const screenBounds = aabb(screen);
-  const behindCamera = points.some(p => p.clone().sub(projection.position).dot(direction) <= 0);
-  // Measured projection, not distance to an arbitrary aim point. Moving lookAt
-  // along the same ray cannot change the subject's observed screen coverage.
-  const screenFraction = (screenBounds.y.max - screenBounds.y.min) / 2;
-  const derivedSize = [['extreme close-up', 2.8], ['close-up', 1.6], ['medium close-up', 1.15], ['medium shot', 0.8], ['medium-wide shot', 0.52], ['wide shot', 0.3], ['extreme wide shot', 0]].find(([, threshold]) => screenFraction >= threshold)[0];
+  const { screenBounds, checks } = projectSubject(points, camera, fov, state.filmback.aspectRatio), derivedSize = checks.derivedSize;
   const resolvedCamera = { ...camera, sensorId: state.filmback.sensorId, slate: derivedSize };
   const draft = { shotDocument: { ...state.shotDocument, shots }, camera: resolvedCamera, manual: true };
   return { domain: 'shot', draft, affectedIds: [shot.id, ...(keyId ? [keyId] : [])],
-    checks: { coverage: 'same-frame-subject-bounds-projection', screenFraction, derivedSize, behindCamera, clipped: behindCamera || screen.some(p => Math.abs(p.x) > 1 || Math.abs(p.y) > 1 || p.z < -1 || p.z > 1) },
+    checks,
     warnings: [{ code: 'OCCLUSION_UNMEASURED' }], details: { created, shotId: shot.id, keyId, frame, framing, screenBounds, subjectIds: [subject.id] } };
 }
 
-/* ------------------------------------------------ element patches ----
- * One thin family over the declared element table. Every value goes through
- * the domain's own persistence normalizer (createCharacterEntry,
- * updateSceneObject, createShotAuthoringDocument's shot repair,
- * createSceneStage) and is then READ BACK: a field the normalizer refused to
- * keep is reported as a dropped path, never as a silent success. One patch is
- * one domain, so it is one draft, one commit and one history entry. */
-const DOMAIN_KEYS = { objects: 'objects', cast: 'characters', stage: 'stage' };
-const domainState = (state, domain) => domain === 'shot'
-  ? { shotDocument: state.shotDocument, camera: state.camera, manual: state.manual }
-  : state[DOMAIN_KEYS[domain]];
-const withDomain = (state, domain, draft) => domain === 'shot' ? { ...state, ...draft } : { ...state, [DOMAIN_KEYS[domain]]: draft };
-/** Did the requested value survive? Normalizer-added members (stable ids,
- * default route flags) are allowed; a changed, clamped or refused value is not. */
-function survives(requested, actual) {
-  if (requested === null || typeof requested !== 'object') return requested === actual;
-  if (Array.isArray(requested)) return Array.isArray(actual) && requested.length === actual.length && requested.every((item, index) => survives(item, actual[index]));
-  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return false;
-  return Object.entries(requested).every(([key, value]) => survives(value, actual[key]));
-}
-const PATH_READERS = {
-  'character.position': row => ({ x: row.x, y: row.y ?? 0, z: row.z }),
-  'character.rot': row => row.rot, 'character.scale': row => row.scale, 'character.subject': row => row.subject,
-  'character.hidden': row => row.hidden === true, 'character.model': row => row.model, 'character.tint': row => row.tint ?? null,
-  'character.identityImage': row => row.identityImage ?? null, 'character.pose': row => row.pose?.id ?? null,
-  'character.promptBlocks': row => row.layer?.promptClips ?? [],
-  'character.motionRef.url': row => row.motionRef?.url ?? null, 'character.motionRef.motionId': row => row.motionRef?.motionId ?? null,
-  'object.renderer': row => row?.renderer ?? null, 'object.position': row => row && ({ x: row.x, y: row.y ?? 0, z: row.z }),
-  'object.rotation': row => row && ({ x: row.rotX, y: row.rot, z: row.rotZ }), 'object.scale': row => row && ({ x: row.scaleX, y: row.scaleY, z: row.scaleZ }),
-  'object.name': row => row?.name, 'object.color': row => row?.color ?? null, 'object.parent': row => row?.parent ?? null,
-  'object.path': row => row?.path ?? null, 'object.remove': row => row === undefined,
-  'shot.cameraKeys': shot => shot.cameraKeys, 'shot.targetModel': shot => shot.targetModel ?? null,
-  'stage.environmentImage': stage => stage.environmentImage, 'stage.camera': stage => stage.shotAspect,
-  'stage.environment': stage => stage.environment, 'stage.style': stage => stage.style, 'stage.hasEnvSheet': stage => stage.hasEnvSheet === true,
-  ...Object.fromEntries(['x', 'y', 'z', 'intensity', 'warmth'].map(axis => [`stage.keyLight.${axis}`, stage => stage.keyLight[axis]])),
-};
-/** Measured readback for one path: one typed member, never the payload. A
- * picture is reported by its size and a schedule by its length. */
-function patchedValue(path, value) {
-  // A cleared, removed or refused field has no measurement but its own absence.
-  if (value === null || value === undefined) return { path, text: null };
-  const type = elementByPath(path)?.type;
-  if (type === 'image') return { path, bytes: utf8ByteLength(value) };
-  if (type === 'array') return { path, count: Array.isArray(value) ? value.length : value.points?.length ?? 0 };
-  if (type === 'vec3') return { path, vec: { x: value.x, y: value.y, z: value.z } };
-  if (typeof value === 'number') return { path, number: value };
-  if (typeof value === 'boolean') return { path, flag: value };
-  return { path, text: [...String(value)].slice(0, 512).join('') };
-}
-function patchCharacters(command, before, ports) {
-  let rows = before.characters;
-  const poses = ports.poses?.() ?? [];
-  const targets = [];
-  for (const op of command.args.ops) {
-    const entity = rows.find(row => row.id === op.target.id);
-    if (!entity) fail('AMBIGUOUS_TARGET', 'Patched character is not present in the admitted scene.');
-    const source = { ...entity }, fields = new Set();
-    for (const [key, value] of Object.entries(op.set)) {
-      if (key === 'position') { Object.assign(source, value); for (const axis of ['x', 'y', 'z']) fields.add(axis); }
-      else if (key === 'pose') { source.pose = value === null ? null : poses.find(pose => pose.id === value) ?? null; fields.add('pose'); }
-      else if (key === 'promptBlocks') { source.layer = { ...(source.layer ?? {}), promptClips: value }; fields.add('layer'); }
-      else if (key.startsWith('motionRef.')) { source.motionRef = { ...(source.motionRef ?? {}), [key.slice('motionRef.'.length)]: value }; fields.add('motionRef'); }
-      else { source[key] = value; fields.add(key); }
-    }
-    // The domain normalizer owns every clamp and whitelist; only the patched
-    // fields are taken from it, so runtime-only state stays where it lives.
-    const normalized = createCharacterEntry(source);
-    const next = { ...entity };
-    for (const field of fields) next[field] = normalized[field];
-    rows = rows.map(row => row.id === entity.id ? next : row);
-    targets.push({ id: entity.id, read: path => PATH_READERS[path](rows.find(row => row.id === entity.id)) });
-  }
-  return { draft: rows, targets };
-}
-function patchObjects(command, before) {
-  let rows = before.objects;
-  const targets = [];
-  for (const op of command.args.ops) {
-    const entity = rows.find(row => row.id === op.target.id);
-    if (!entity) fail('AMBIGUOUS_TARGET', 'Patched object is not present in the admitted scene.');
-    const patch = {};
-    for (const [key, value] of Object.entries(op.set)) {
-      if (key === 'position') Object.assign(patch, { x: value.x, y: value.y, z: value.z });
-      else if (key === 'rotation') Object.assign(patch, { rotX: value.x, rot: value.y, rotZ: value.z });
-      else if (key === 'scale') Object.assign(patch, { scaleX: value.x, scaleY: value.y, scaleZ: value.z });
-      else if (!['parent', 'remove'].includes(key)) patch[key] = value;
-    }
-    if (Object.keys(patch).length) rows = updateSceneObject(rows, entity.id, patch);
-    if (Object.hasOwn(op.set, 'parent')) {
-      if (op.set.parent !== null && descendantsOf(rows, entity.id).some(row => row.id === op.set.parent)) fail('INVALID_ARGUMENT', 'Grouping would create a cycle.');
-      rows = setSceneObjectParent(rows, entity.id, op.set.parent);
-    }
-    if (op.set.remove === true) rows = removeSceneObject(rows, entity.id);
-    targets.push({ id: entity.id, read: path => PATH_READERS[path](rows.find(row => row.id === entity.id)) });
-  }
-  return { draft: rows, targets };
-}
-function patchShot(command, before) {
-  let shots = before.shotDocument.shots;
-  const targets = [];
-  for (const op of command.args.ops) {
-    const shot = op.target.id ? shots.find(row => row.id === op.target.id)
-      : shotAtFrame(shots, before.frame) ?? shots.find(row => row.id === before.selectedShotId);
-    if (!shot) fail('AMBIGUOUS_TARGET', 'No shot owns this frame; name the shot explicitly.');
-    const patched = { ...shot };
-    for (const [key, value] of Object.entries(op.set)) patched[key] = value === null ? undefined : value;
-    shots = shots.map(row => row.id === shot.id ? patched : row);
-    targets.push({ id: shot.id, read: path => PATH_READERS[path](shots.find(row => row.id === shot.id)) });
-  }
-  // The shot document's own repair owns key ordering, ranges and the video
-  // model whitelist; rebuilding it is how a patched shot stays a legal shot.
-  shots = createShotAuthoringDocument({ shots, waypoints: [], frameCount: before.frameCount }).shots;
-  return { draft: { shotDocument: { ...before.shotDocument, shots }, camera: before.camera, manual: before.manual }, targets };
-}
-const STAGE_FIELDS = ['hasCharSheet', 'environmentImage', 'environment', 'style', 'hasEnvSheet', 'shotAspect', 'cameraPresetId', 'sensorId', 'keyLight'];
-function patchStage(command, before) {
-  if (!before.stage) fail('CAPABILITY_MISSING', 'This editor does not publish an authored stage.');
-  let stage = before.stage;
-  const targets = [];
-  for (const op of command.args.ops) {
-    const merged = { ...stage, keyLight: { ...stage.keyLight } };
-    for (const [key, value] of Object.entries(op.set)) {
-      if (key.startsWith('keyLight.')) merged.keyLight[key.slice('keyLight.'.length)] = value;
-      else if (key === 'camera') merged.shotAspect = value;
-      else merged[key] = value;
-    }
-    const normalized = createSceneStage(merged);
-    // Spread over the live envelope: the stage keeps its own field order, and
-    // the cast stays owned by the cast domain rather than the stage draft.
-    stage = { ...stage, ...Object.fromEntries(STAGE_FIELDS.map(field => [field, normalized[field]])) };
-    targets.push({ id: before.host.sceneId, read: path => PATH_READERS[path](stage) });
-  }
-  return { draft: stage, targets };
-}
-function patchPlan(command, before, ports) {
-  const kind = command.args.ops[0].target.kind, domain = STUDIO_PATCH_DOMAINS[kind];
-  const { draft, targets } = kind === 'character' ? patchCharacters(command, before, ports)
-    : kind === 'object' ? patchObjects(command, before)
-      : kind === 'shot' ? patchShot(command, before) : patchStage(command, before);
-  const ops = command.args.ops.map((op, index) => {
-    const droppedPaths = Object.entries(op.set)
-      .filter(([key, value]) => !survives(value, targets[index].read(`${kind}.${key}`)))
-      .map(([key]) => `${kind}.${key}`);
-    return { index, status: droppedPaths.length ? 'partial' : 'applied', ...(droppedPaths.length ? { droppedPaths } : {}) };
-  });
-  const unchanged = equal(draft, domainState(before, domain));
-  const readback = state => command.args.ops.map((op, index) => ({ id: targets[index].id,
-    after: { patched: Object.keys(op.set).map(key => patchedValue(`${kind}.${key}`, patchTargetRead(kind, state, targets[index].id, `${kind}.${key}`))) } }));
-  return { domain, draft, unchanged,
-    status: unchanged ? 'noop' : ops.some(op => op.status === 'partial') ? 'partial' : 'applied',
-    ops: unchanged ? ops.map(op => ({ ...op, status: op.status === 'partial' ? 'partial' : 'noop' })) : ops,
-    affectedIds: [...new Set(targets.map(target => target.id))], patchReadback: readback,
-    checks: { coverage: 'declared-element-readback' }, warnings: [], details: { kind, paths: command.args.ops.flatMap(op => Object.keys(op.set).map(key => `${kind}.${key}`)) } };
-}
-/** Read one path back out of the COMMITTED state, so the receipt quotes the
- * editor and not the draft the planner built. */
-function patchTargetRead(kind, state, id, path) {
-  if (kind === 'stage') return PATH_READERS[path](state.stage);
-  if (kind === 'shot') {
-    const shot = state.shotDocument.shots.find(row => row.id === id);
-    if (!shot) fail('UNCERTAIN_APPLY', 'Committed shot is unavailable at readback.');
-    return PATH_READERS[path](shot);
-  }
-  return PATH_READERS[path]((kind === 'character' ? state.characters : state.objects).find(row => row.id === id));
-}
-
 /** Local journal. Unsettled/protected records are never evicted. Call prune on
  * history/job release; completed unprotected outcomes expire after ten minutes. */
 export function createStudioCommandJournal({ host, now = Date.now, isRetained = () => false, maxCompleted = 256, retentionMs = 600000 } = {}) {
@@ -469,90 +323,6 @@ export function createStudioCommandJournal({ host, now = Date.now, isRetained =
     details(commandId) { return records.get(commandId)?.details ?? null; },
   };
 }
-function readback(plan, state) {
-  if (plan.patchReadback) return plan.patchReadback(state);
-  return plan.affectedIds.map(id => {
-    if (plan.domain === 'shot') {
-      const shot = state.shotDocument.shots.find(s => s.id === plan.details.shotId);
-      if (!shot) fail('UNCERTAIN_APPLY', 'Committed shot is unavailable at readback.');
-      return { id, after: { shotId: shot.id, range: { startFrame: shot.startFrame, endFrameExclusive: shot.endFrame + 1 }, camera: state.camera, subjectIds: plan.details.subjectIds, ...(id === plan.details.keyId ? { keyId: id, frame: shot.cameraKeys.find(k => k.id === id).frame } : {}) } };
-    }
-    const entity = state[plan.domain === 'objects' ? 'objects' : 'characters'].find(e => e.id === id);
-    return { id, after: !entity ? { removed: true } : { position: pos(entity), yawDeg: entity.rot,
-      ...(entity.renderer ? { name: entity.name, renderer: entity.renderer, rotationDeg: { x: entity.rotX, y: entity.rot, z: entity.rotZ }, scale: { x: entity.scaleX, y: entity.scaleY, z: entity.scaleZ }, parentId: entity.parent, color: entity.color } : { name: entity.subject, scale: entity.scale, modelId: entity.model, hidden: entity.hidden, activeCharacterId: state.activeCharacterId }) } };
-  });
-}
-/** ports: synchronous read/bounds/commit. commit must atomically publish
- * exactly the draft and one history entry, or throw before changing anything.
- * A thrown/invalid commit is conservatively unknown, never automatically retried. */
-export function createStudioCommands(ports) {
-  const journal = ports.journal ?? createStudioCommandJournal({ host: ports.read().host, isRetained: ports.isRetained });
-  const documentIsCurrent = () => equal(validateStudioIdentity(ports.read().host), journal.host);
-  function execute(request) {
-    const host = validateStudioIdentity(request.host);
-    validateStudioSchema(StudioSchemas.TargetGuard.properties.targetId, request.commandId);
-    const signature = JSON.stringify(request);
-    let phase = 'admission', committing = false;
-    function failure(code, failurePhase, mutated, message) {
-      return validateReceipt({ ok: false, commandId: request.commandId, host, code, phase: failurePhase, affectedIds: [], expectedTargets: [], currentTargets: [], mutated,
-        preserved: { authoredState: mutated === false ? 'unchanged' : 'unknown' }, recovery: { action: mutated === false ? 'inspect' : 'reconcile', ...(mutated === false ? { retryAllowed: false } : {}) }, ...(message ? { message: [...message].slice(0, 120).join('') } : {}) });
-    }
-    if (!equal(host, journal.host) || !documentIsCurrent()) return failure('STALE_SCENE', phase, false, 'Request belongs to a different live document.');
-    try {
-      if (!journal.begin(request.commandId, signature)) return journal.get(request.commandId) ?? failure('UNCERTAIN_APPLY', 'reconcile', 'unknown');
-    } catch (error) { return failure(error.code, phase, false, error.message); }
-    try {
-      const command = validateStudioCommand({ name: request.name, args: request.args });
-      if (!['arrange_objects', 'arrange_characters', 'frame_shot', 'patch_elements'].includes(command.name)) fail('CAPABILITY_MISSING', 'This module exposes arrangement, framing and element patches only.');
-      const before = structuredClone(ports.read());
-      const fence = () => {
-        const current = ports.read();
-        if (!equal(host, validateStudioIdentity(current.host)) || !equal(host, journal.host)) fail('STALE_SCENE', 'Live document identity changed.');
-        if (request.expectedRevision !== current.revision) fail('STALE_SCENE', 'Authored scene revision changed.');
-        if (current.busy) fail('TARGET_BUSY', 'A domain gesture is in progress.');
-        // The exact scene revision is the whole authored fence here: it bumps on
-        // every authored change, so per-dependency incarnation tokens added
-        // nothing but a false refusal for a turn's second edit to one entity.
-        // A dependency that vanished is refused by the planner, which resolves
-        // every referenced ID against the admitted draft.
-        if (current.frame !== before.frame || !equal(current.camera, before.camera)) fail('STALE_SCENE', 'Reference view changed during draft evaluation.');
-      };
-      fence(); phase = 'prepare';
-      const plan = command.name === 'frame_shot' ? frameDraft(command, before, ports)
-        : command.name === 'patch_elements' ? patchPlan(command, before, ports) : arrangement(command, before, ports);
-      const unchanged = plan.unchanged ?? (plan.domain === 'shot' ? equal(plan.draft, before.shotState ?? { shotDocument: before.shotDocument, camera: before.camera, manual: before.manual }) : !plan.affectedIds.length);
-      const ops = plan.ops ? { ops: plan.ops } : {};
-      const base = { ok: true, commandId: request.commandId, receiptId: createStableItemId('receipt'), host, revision: { before: before.revision, after: before.revision }, affectedIds: plan.affectedIds, delta: [], checks: plan.checks, warnings: plan.warnings, undo: null };
-      if (unchanged) return journal.record({ ...base, ...ops, status: 'noop', authored: false, mutated: false });
-      if (plan.affectedIds.length > 100) fail('INVALID_ARGUMENT', 'Affected domain exceeds receipt capacity.');
-      const preview = withDomain(before, plan.domain, plan.draft);
-      const allDelta = readback(plan, preview);
-      const makeReceipt = (delta, historyEntryId) => {
-        const r = { ...base, ...ops, status: plan.status ?? 'applied', authored: true, revision: { before: before.revision, after: before.revision + 1 }, delta: delta.slice(0, 8), undo: { historyEntryId, entries: 1, canUndoDirect: true }, detailCursor: request.commandId };
-        while (r.delta.length > 1 && utf8ByteLength(JSON.stringify(r)) > 8000) r.delta.pop();
-        return validateReceipt(r);
-      };
-      makeReceipt(allDelta, 'preflight-history'); // Reject receipt overflow BEFORE mutation.
-      fence(); phase = 'commit'; committing = true;
-      const committed = ports.commit({ domain: plan.domain, before, draft: plan.draft, commandId: request.commandId, host, expectedRevision: before.revision });
-      if (committed?.then) fail('UNCERTAIN_APPLY', 'Commit must publish synchronously.');
-      const current = ports.read();
-      const actual = domainState(current, plan.domain);
-      if (current.revision !== before.revision + 1 || !equal(current.host, host) || !equal(actual, plan.draft)) fail('UNCERTAIN_APPLY', 'Commit did not synchronously publish the admitted poststate.');
-      const delta = readback(plan, current);
-      return journal.record(makeReceipt(delta, committed.historyEntryId), { delta, geometry: plan.details });
-    } catch (error) {
-      const receipt = failure(committing ? 'UNCERTAIN_APPLY' : error instanceof StudioProtocolError ? error.code : 'INVALID_ARGUMENT', phase, committing ? 'unknown' : false, error.message);
-      // An owner may already have journaled the commit before a lost ack.
-      const recorded = journal.reconcile({ commandId: request.commandId });
-      if (recorded.status === 'applied') return recorded.receipt;
-      return journal.record(receipt);
-    }
-  }
-  return { execute, journal,
-    reconcile_studio_command: args => documentIsCurrent() ? journal.reconcile(args) : { status: 'unknown' },
-    readDetails: commandId => documentIsCurrent() ? journal.details(commandId) : null };
-}
 export function studioObjectCatalogue() {
   return freezeStudioData({ objects: OBJECT_LIBRARY.map(({ kind, footprint, height, supportY }) => ({ kind, footprint: { ...footprint }, height, supportY: supportY ?? height })), imageRefs: [],
     // The patchable vocabulary, so a caller reads the paths and their declared