cozyclay 2.1.1 → 3.0.1

package/src/stage-sky.jsx

@@ -0,0 +1,159 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { stageLook } from "./stage-lighting.js";
+import { ENV_HEIGHT, ENV_WIDTH, environmentPixels } from "./stage-environment.js";
+import { installOcclusion } from "./stage-occlusion.js";
+import { useHdrMap } from "./stage-hdr-map.js";
+import { refreshHdrLibrary } from "./stage-hdr-library.js";
+
+// Rows of the equirectangular gradient: v runs from straight down (0) through
+// the horizon (0.5) to straight up (1).
+const SKY_ROWS = 128;
+const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+
+/** A sky that grades from `bottom` at the horizon (and below it) to `top`
+ * overhead, eased so most of the change happens in the lower 60 degrees a shot
+ * camera actually sees. Built once per look as an sRGB equirectangular texture;
+ * three draws it as the background in the same pass as the scene. */
+function gradientSky(bottom, top) {
+	const [from, to] = [rgb(bottom), rgb(top)];
+	const data = new Uint8Array(SKY_ROWS * 4);
+	for (let row = 0; row < SKY_ROWS; row++) {
+		const elevation = ((row + 0.5) / SKY_ROWS - 0.5) * 180;
+		const t = elevation <= 0 ? 0 : 1 - (1 - Math.min(1, elevation / 60)) ** 2;
+		for (let channel = 0; channel < 3; channel++) data[row * 4 + channel] = Math.round(from[channel] + (to[channel] - from[channel]) * t);
+		data[row * 4 + 3] = 255;
+	}
+	const texture = new THREE.DataTexture(data, 1, SKY_ROWS);
+	texture.colorSpace = THREE.SRGBColorSpace;
+	texture.mapping = THREE.EquirectangularReflectionMapping;
+	texture.magFilter = THREE.LinearFilter;
+	texture.minFilter = THREE.LinearFilter;
+	texture.needsUpdate = true;
+	return texture;
+}
+
+/** The look's environment map (stage-environment.js), prefiltered for image-based
+ * lighting. Half floats keep the glow around the key above 1 and filter
+ * everywhere WebGL2 runs. */
+function environmentMap(gl, spec) {
+	const pixels = environmentPixels(spec), half = new Uint16Array(pixels.length);
+	for (let i = 0; i < pixels.length; i++) half[i] = THREE.DataUtils.toHalfFloat(pixels[i]);
+	const texture = new THREE.DataTexture(half, ENV_WIDTH, ENV_HEIGHT, THREE.RGBAFormat, THREE.HalfFloatType);
+	texture.mapping = THREE.EquirectangularReflectionMapping;
+	texture.magFilter = THREE.LinearFilter;
+	texture.minFilter = THREE.LinearFilter;
+	texture.needsUpdate = true;
+	try { return prefiltered(gl, texture); } finally { texture.dispose(); }
+}
+
+/** An equirectangular map prefiltered for image-based lighting (PMREM). */
+function prefiltered(gl, texture) {
+	const generator = new THREE.PMREMGenerator(gl);
+	try { return generator.fromEquirectangular(texture); } finally { generator.dispose(); }
+}
+
+/**
+ * The stage's sky, fog and exposure (stage.lighting through stageLook), set on
+ * the one scene and renderer every path draws with: the viewport panes, the
+ * shot preview card, capture_frame, contact sheets and video export
+ * (stage-capture.jsx). Nothing here is a post-process; it is all the same pass.
+ *
+ * The open stage runs 500 m; without a falloff the whole deck reads at once and
+ * the horizon sits a kilometre away. The fog fades the floor INTO the sky colour,
+ * so past its far distance the deck simply ceases to exist with no horizon line,
+ * no clip edge and no tone break. Haze (stage.lighting.fog) pulls that fade in.
+ *
+ * Perspective cameras see the gradient sky when skyTop is set; orthographic ones
+ * (the plan) keep the flat horizon colour, since a box-mapped sky has no meaning
+ * looking straight down. A caller that swaps the background for a pass of its
+ * own (render-passes.js) is left alone.
+ *
+ * The environment light (scene.environment) and the ambient occlusion pass
+ * (stage-occlusion.js) are set here too, for the same paths. Both are off in the
+ * studio look, which therefore draws exactly what it drew before them. The map
+ * is rebuilt only when its colours or the key's direction change.
+ *
+ * An HDR environment (stage.lighting.hdr, stage-hdr-map.js) replaces that map
+ * once it has loaded: its prefiltered texture is the light (prefiltered again
+ * only when the map changes; rotation and intensity are uniforms), and with
+ * hdrBackground the map itself is the perspective backdrop, the deck fading
+ * into the map's horizon colour. Until a file loads, the look's own sky lights.
+ */
+export function StageAtmosphere({ lighting = null, keyLight, theme = "dark", grid = false }) {
+	// The scene and renderer are read inside the effects: they are three objects
+	// this component configures, not React state.
+	const get = useThree((state) => state.get), invalidate = useThree((state) => state.invalidate);
+	const look = stageLook({ lighting, keyLight, theme, grid });
+	const { sky, skyTop, exposure } = look, { near, far } = look.fog;
+	const hazeNear = look.captureFog?.near ?? null, hazeFar = look.captureFog?.far ?? null;
+	const envKey = look.env ? JSON.stringify(look.env) : null, { envIntensity, ao } = look;
+	const hdrMap = useHdrMap(look.hdr?.id ?? null), hdr = hdrMap ? look.hdr : null;
+	const backdrop = hdr?.background ? hdrMap : null, backdropIntensity = backdrop ? hdr.intensity : 1;
+	const hdrLight = hdr ? hdr.envIntensity : null, hdrTurn = hdr ? (hdr.rotation * Math.PI) / 180 : 0;
+	useEffect(() => { void refreshHdrLibrary(); }, []);
+	useLayoutEffect(() => {
+		const { scene } = get();
+		const flat = backdrop ? new THREE.Color().setRGB(...backdrop.horizon.map((value) => value * backdropIntensity), THREE.LinearSRGBColorSpace) : new THREE.Color(sky);
+		const gradient = skyTop ? gradientSky(sky, skyTop) : null, map = backdrop?.texture ?? null;
+		scene.background = flat;
+		scene.backgroundIntensity = backdropIntensity;
+		scene.fog = new THREE.Fog(flat, near, far);
+		scene.onBeforeRender = (_renderer, _scene, camera) => {
+			if (scene.background === flat || scene.background === gradient || (map && scene.background === map)) scene.background = camera.isPerspectiveCamera ? map ?? gradient ?? flat : flat;
+		};
+		invalidate();
+		return () => {
+			scene.onBeforeRender = () => {};
+			gradient?.dispose();
+		};
+	}, [get, invalidate, sky, skyTop, near, far, backdrop, backdropIntensity]);
+	useLayoutEffect(() => {
+		// The viewport applies exposure in tone mapping. Exports render into a
+		// target, which three never tone-maps, so CaptureRig reads it from here
+		// and scales the lights for its draw instead (same pass, same scene).
+		const { scene, gl } = get();
+		gl.toneMappingExposure = exposure;
+		// An HDR backdrop is light as well, so exports scale it (and the horizon the deck fades into) too.
+		scene.userData.stageCapture = { exposure, fog: hazeNear === null ? null : { near: hazeNear, far: hazeFar }, backdrop: Boolean(backdrop) };
+		invalidate();
+	}, [get, invalidate, exposure, hazeNear, hazeFar, backdrop]);
+	const hdrTexture = hdrMap?.texture ?? null, envSource = hdrTexture ? null : envKey;
+	useLayoutEffect(() => {
+		if (!hdrTexture && !envSource) return undefined;
+		const { scene, gl } = get();
+		const target = hdrTexture ? prefiltered(gl, hdrTexture) : environmentMap(gl, JSON.parse(envSource));
+		scene.environment = target.texture;
+		invalidate();
+		return () => {
+			if (scene.environment === target.texture) scene.environment = null;
+			target.dispose();
+			invalidate();
+		};
+	}, [get, invalidate, hdrTexture, envSource]);
+	useLayoutEffect(() => {
+		const { scene } = get();
+		scene.environmentIntensity = hdrLight ?? envIntensity;
+		// The light and the backdrop turn together: +90 deg carries +x to -z.
+		scene.environmentRotation.set(0, hdrTurn, 0);
+		scene.backgroundRotation.set(0, hdrTurn, 0);
+		invalidate();
+	}, [get, invalidate, envIntensity, hdrLight, hdrTurn]);
+	// The pass stays installed while ao > 0; the slider only changes its strength.
+	const occlusion = useRef({ strength: ao }), occluded = ao > 0;
+	useLayoutEffect(() => {
+		if (!occluded) return undefined;
+		const remove = installOcclusion(get().scene, occlusion.current);
+		invalidate();
+		return () => {
+			remove();
+			invalidate();
+		};
+	}, [get, invalidate, occluded]);
+	useLayoutEffect(() => {
+		occlusion.current.strength = ao;
+		invalidate();
+	}, [invalidate, ao]);
+	return null;
+}

package/src/stage-startup-defaults.js

@@ -59,19 +59,15 @@ export function nextCharacterId(list) {
 	}
 	return id;
 }
-export const DEMO_MOTION_URL = "/demo/walk-then-stop.npz";
-export const DEMO_MOTION_PROMPT = "A person walks forward.";
 // How long a deletion keeps offering its one-press Undo. Both toasts use the
 // same window so the two deletion paths feel like one rule.
 export const OBJECT_DELETE_UNDO_MS = 7000;
 export const ASSET_DELETE_UNDO_MS = 7000;
-// Neutral grey clay: the set is the grey workbench, so the figures are grey
-// too, light enough to stand off the deck and the sky.
-export const CLAY = "#bdbec3";
-export const CLAY_B = "#a4a5aa";
-// X Bot's shell is smooth (no raised exoskeleton like Y Bot's), so it gets a
-// brighter, whiter clay to keep it readable against the set.
-export const CLAY_X = "#d0d0d4";
+// White clay: every figure starts white (the renderer still drops the value a
+// little and shades the joint shells darker, so the body keeps its form).
+export const CLAY = "#ffffff";
+export const CLAY_B = "#ffffff";
+export const CLAY_X = "#ffffff";
 // Model/role default for a cast member; a user-picked entry.tint always wins
 // over this at render time.
 export const defaultCharacterTint = (entry, index) => (entry.model === "x-bot-tpose" ? CLAY_X : index === 0 ? CLAY : CLAY_B);

package/src/studio-actions.js

@@ -38,7 +38,7 @@ const castOverride = {
 /** 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
+/** The tracks an IK key stores (src/motion/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"]);
@@ -47,9 +47,9 @@ 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, correctionRange } 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
+ * as {x,y,z}; blend is the key's own correction range in frames (src/motion/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). correctionRange
+ * the range pin that baked the key (src/motion/range-pin.js). correctionRange
  * pairs the boundary keys of an explicitly selected interval. */
 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 },
@@ -87,12 +87,10 @@ export const STUDIO_ACTIONS = freezeStudioData([
 	{ 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." },
+		description: "Move a shot's start and end to a half-open frame range, e.g. { shotId, range: { startFrame: 0, endFrameExclusive: 240 } } for frames 0-239. range: [0, 240] ([start, endExclusive]) and flat { shotId, startFrame: 0, endFrameExclusive: 240 } are taken as the same range. Edges are clamped to the timeline and refused where they would overlap another shot; the receipt's summary shows the range that landed (\"Set shot range: Shot 1 [0, 240).\")." },
 	{ id: "shot.reorder", label: "Move shot", kind: "mutation", undoDomain: "shot",
 		input: input(shotId, { startFrame: frame, index: stillIndex }),
 		description: "Move a shot; give exactly one of startFrame or index. With startFrame, a clip moves in time to start there, keeping its length and camera keys (a noop where it would overlap another shot), and a still moves to the place in the still order that frame falls in. With index (stills only), the still moves to that position among the stills (0 is first; past the end means last). Stills stay end to end from frame 0." },
-	{ 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.move", label: "Move character", kind: "mutation", undoDomain: "cast", input: input(characterId, { x: num, z: num, rot: num }),
@@ -110,10 +108,14 @@ export const STUDIO_ACTIONS = freezeStudioData([
 	{ 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\" }." },
+		input: input({ ...shotId, points: { type: "array", items: floorPoint, minItems: 2, maxItems: 512 } }, { height: { oneOf: [{ type: "number", minimum: 0.1, maximum: 30 }, { type: "array", items: input({ t: { type: "number", minimum: 0, maximum: 1 }, height: { type: "number", minimum: 0.1, maximum: 30 } }), minItems: 2, maxItems: 8 }] }, aim: { oneOf: [{ type: "array", items: idSchema, minItems: 1, maxItems: 4 }, input({ x: num, y: num, z: num }), { type: "null" }] }, aimHeight: { type: "number", minimum: 0, maximum: 30 }, focalMm: { oneOf: [{ type: "number", minimum: 10, maximum: 300 }, { type: "null" }] } }),
+		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: the camera runs the rail at an even speed over the whole shot (or its authored rail-follow range), so a push-in, pull-out, orbit, track or crane is one call with 2-6 points (a line, or an arc through a few points; the rail is a smooth curve through them). height is the lens height in metres, one number or crane marks [{ t: 0..1 along the rail, height }] (default the follow height, 1.6). aim is what the camera holds: up to 4 character or object ids (their middle, frame by frame: a character's chest, an object's middle) or a world point { x, y, z }; without an aim it follows the scene's first character. aimHeight puts a cast aim at that world height instead of the chest, e.g. 0.9 to hold a whole standing body, 1.6 for faces. focalMm is the shot's lens (default the scene lens). It replaces any rail the shot had and keeps any height, aim or lens you leave out (null clears aim and lens), and it removes the camera keys the rail covers. Answers the rail's length, speed, height, aim and lens; check the framing with verify_result { targets, checks: [\"framing\"], range: the shot's frames } and a contact sheet. 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: "shot.setCameraMode", label: "Set shot camera mode", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, mode: { type: "string", enum: ["keys", "follow", "rail"] } }),
+		description: "Set how a shot's camera moves: keys plays the shot's camera keys (frame_shot frames them; one framing holds the whole shot), follow keeps the captured distance from the subject, rail rides the shot's rail (lay one first with shot.setCameraRail). Deleting a rail leaves follow; set keys to hold a framed camera instead." },
+	{ id: "shot.rename", label: "Rename shot", kind: "mutation", undoDomain: "shot", input: input({ ...shotId, name: { type: "string", maxLength: 240 } }),
+		description: "Rename a shot: its label on the timeline and in shot lists." },
 	{ 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." },
@@ -125,6 +127,8 @@ export const STUDIO_ACTIONS = freezeStudioData([
 		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: "view.setGhosts", label: "Ghosts", kind: "transient", input: input({ mode: { type: "string", enum: ["off", "step", "keys"] } }, { count: { type: "integer", minimum: 1, maximum: 6 }, step: { type: "integer", minimum: 1, maximum: 24 } }),
+		description: "Onion skin in the editor viewport, like the View menu's Ghosts: translucent poses of the active character's installed take, count (1-6, default 3) before the playhead in blue and as many after it in orange, fading with distance in time; props the take carries (a kit's bat) ghost with the body. mode step spaces them every step frames (1-24, default 4), keys puts them on the spec's key frames, off hides them; e.g. { mode: \"step\", count: 3, step: 4 }. An editor overlay: never in capture_frame, exports or contact sheets (verify_result ghosts: true draws them on a views sheet). A viewer setting: never saved or 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, scope: { type: "string", enum: ["timeline", "shot"], description: "timeline: the whole timeline, every shot back to back; shot: one shot (shotId, or the one under the playhead)." } }),
 		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(),
@@ -151,9 +155,6 @@ export const STUDIO_ACTIONS = freezeStudioData([
 		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));
 
@@ -216,14 +217,15 @@ export function createStudioActionRegistry({ readState } = {}) {
 		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.agentHidden ? { agentHidden: true } : {}),
+				const row = { id: entry.id, label: entry.label, kind: entry.kind, description: entry.description, exposure: entry.exposure, ...(entry.agentHidden ? { agentHidden: true } : {}), ...(entry.readOnly ? { readOnly: true } : {}),
 					...(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");
+			const entry = registry.get(id), given = args ?? {};
+			// normalizeArgs (optional) rewrites another spelling the action takes into its declared input first.
+			const validated = validateStudioSchema(entry.input, entry.normalizeArgs ? entry.normalizeArgs(given) : given, "INVALID_ARGUMENT", "$.args");
 			if (readState) {
 				const verdict = availability(entry, readState());
 				if (verdict !== true) fail("TARGET_NOT_READY", verdict);

package/src/studio-agent-commands.js

@@ -1,7 +1,7 @@
 // Studio composites prepare private domain drafts; the App owns publication,
 // history, gesture fences and semantic revision/telemetry. No UI callbacks here.
 import { Euler, Vector3, Quaternion, PerspectiveCamera } from 'three';
-import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, isEffectivelyHidden, supportHeightForObject, OBJECT_LIBRARY } from './scene-objects.js';
+import { createSceneObject, updateSceneObject, removeSceneObject, setSceneObjectParent, descendantsOf, isEffectivelyHidden, supportHeightForObject, OBJECT_MENU_ENTRIES } from './scene-objects.js';
 import { createCharacterEntry } from './scenes.js';
 import { createShot, shotAtFrame } from './cuts.js';
 import { captureFraming } from './camera-move.js';
@@ -12,6 +12,7 @@ import { clampWarning } from './receipt-findings.js';
 import { occludersOf, primarySubjects, sideOfAxis } from './studio-geometry-facts.js';
 import { StudioProtocolError, StudioSchemas, STUDIO_PATCH_KINDS, STUDIO_PATCH_DESCRIPTORS, validateStudioSchema, validateStudioIdentity, validateReceipt, freezeStudioData } from './studio-agent-protocol.js';
 import { sampleContactSheetFrames } from './studio-contact-sheet.js';
+import { supportGaps } from './studio-support-gap.js';
 
 const DEG = Math.PI / 180, EPS = 1e-8, CHARACTER_SUPPORT_TOLERANCE = 5e-3;
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -241,9 +242,8 @@ export function entityWorldBounds(entity, state, ports) {
   } catch { return null; }
 }
 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));
+// Placement evidence for entity ids: the AABB overlap an arrangement receipt reports, and each object's support gap (studio-support-gap.js).
+export const placementChecks = (ids, state, ports) => ({ ...overlapEvidence(overlapsOf(ids, state, ports)), ...supportGaps(ids, state, ports.takes, entity => entityWorldBounds(entity, state, ports)) });
 function avoid(entity, relation, state, ports) {
   const blocked = overlapsFor(entity, state, ports);
   if (!blocked.length) return entity;
@@ -369,7 +369,7 @@ const LEVELS = { ground: 0.3 / 1.8, low: 0.7 / 1.8, hip: 1.1 / 1.8, eye: 1.65 /
 const ANGLES = { front: 0, 'front three-quarter': 40, profile: 90, 'rear three-quarter': 140, back: 180 };
 /** 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) {
+export 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);
@@ -436,9 +436,13 @@ export function frameDraft(command, state, ports) {
   const created = !shot && !state.shotDocument.shots.length && !command.args.shotId;
   if (created) shot = createShot('Shot 1', 0, state.frameCount - 1);
   if (!shot) fail('AMBIGUOUS_TARGET', 'No shot owns this frame; select an existing shot explicitly.');
-  const still = shot.kind === 'still';
+  // The shot's camera keys are what the contact sheet and the export render, so
+  // every framing lands in them. Without keyAtFrame, a shot that holds one
+  // framing (a still, or a clip with at most one key) is reframed whole; a clip
+  // that already moves takes the framing as a key at the playhead.
   const existingKey = shot.cameraKeys[0];
-  const frame = still ? (existingKey?.frame ?? shot.startFrame) : command.args.keyAtFrame ?? state.frame;
+  const hold = shot.kind === 'still' || (command.args.keyAtFrame === undefined && shot.cameraKeys.length <= 1);
+  const frame = hold ? (existingKey?.frame ?? shot.startFrame) : command.args.keyAtFrame ?? state.frame;
   if (frame < shot.startFrame || frame > shot.endFrame || shot.endFrame >= state.frameCount) fail('INVALID_RANGE', 'Framing/key frame must be inside the shot range.');
   const intent = command.args.framing.intent;
   let camera = command.args.framing.exact;
@@ -457,19 +461,17 @@ export function frameDraft(command, state, ports) {
   const direction = vector(camera.lookAt).sub(vector(camera.position));
   if (direction.length() <= EPS) fail('INVALID_ARGUMENT', 'Camera position and aim must differ.');
   const framing = captureFraming({ pos: camera.position, yaw: Math.atan2(-direction.x, -direction.z), pitch: Math.atan2(direction.y, Math.hypot(direction.x, direction.z)), fovDeg: fov / DEG });
-  let keyId;
-  let keys = shot.cameraKeys;
-  if (still || command.args.keyAtFrame !== undefined) {
-    keyId = (still ? existingKey?.id : keys.find(k => k.frame === frame)?.id) ?? createStableItemId('camera-key');
-    keys = still ? [{ id: keyId, frame, framing }] : [...keys.filter(k => k.frame !== frame), { id: keyId, frame, framing }].sort((a, b) => a.frame - b.frame);
-  }
+  const keyId = (hold ? existingKey?.id : shot.cameraKeys.find(k => k.frame === frame)?.id) ?? createStableItemId('camera-key');
+  const keys = hold ? [{ id: keyId, frame, framing }] : [...shot.cameraKeys.filter(k => k.frame !== frame), { id: keyId, frame, framing }].sort((a, b) => a.frame - b.frame);
   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 { screenBounds, checks: projected } = projectSubject(points, camera, fov, state.filmback.aspectRatio), derivedSize = projected.derivedSize;
   const sight = sightChecks([subject], [points], camera.position, state, ports), checks = { ...projected, ...sight.checks };
   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] : [])],
+  // Not a manual override: the keys drive the live shot camera from here, so a
+  // later playhead move shows what the export renders at that frame.
+  const draft = { shotDocument: { ...state.shotDocument, shots }, camera: resolvedCamera, manual: false };
+  return { domain: 'shot', draft, affectedIds: [shot.id, keyId],
     checks,
     warnings: sight.occluders.slice(0, 5).map(item => ({ code: 'OCCLUDED', id: item.byObjectId })), details: { created, shotId: shot.id, keyId, frame, framing, screenBounds, subjectIds: [subject.id] } };
 }
@@ -514,7 +516,8 @@ export function createStudioCommandJournal({ host, now = Date.now, isRetained =
   };
 }
 export function studioObjectCatalogue() {
-  return freezeStudioData({ objects: OBJECT_LIBRARY.map(({ kind, footprint, height, supportY }) => ({ kind, footprint: { ...footprint }, height, supportY: supportY ?? height })), imageRefs: [],
+  // Every creatable kind: the sized library, the Empty and the two practical lights (zero footprint).
+  return freezeStudioData({ objects: OBJECT_MENU_ENTRIES.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
     // ranges instead of guessing them from a rejection.
     patchable: Object.fromEntries(STUDIO_PATCH_KINDS.map(kind => [kind, STUDIO_PATCH_DESCRIPTORS.filter(descriptor => descriptor.path.startsWith(`${kind}.`))])) });

package/src/studio-agent-motion.js

@@ -3,14 +3,14 @@
 import * as THREE from 'three';
 import { clone as cloneSkeleton } from 'three/examples/jsm/utils/SkeletonUtils.js';
 import { StudioProtocolError, freezeStudioData } from './studio-agent-protocol.js';
-import { applyMotionFrame } from './ardy/playback.js';
-import { resolveIkRig, createIkState, ikEvaluate, findBone, hasBindPose } from './ardy/ik.js';
-import { PHYSICS_LIMITS, createSupportSampler, copyPhysicsKeys, supportIntervals, physicsMetrics } from './ardy/physics-review.js';
-import { createDynamicsSampler, supportDiagnostics } from './ardy/physics-support.js';
-import { computeCenterOfMass } from './ardy/auto-physics.js';
-import { buildCollisionCapsules, detectPenetrations, supportsCollisionCleanup } from './ardy/fix-collisions.js';
-import { collisionBlockers, blockerSummary } from './ardy/collision-blockers.js';
-import { createGroundSampler } from './ardy/ground.js';
+import { applyTakeFrame } from './motion3/playback.js';
+import { resolveIkRig, createIkState, ikEvaluate, findBone, hasBindPose } from './motion/ik.js';
+import { PHYSICS_LIMITS, createSupportSampler, copyPhysicsKeys, supportIntervals, physicsMetrics } from './motion/physics-review.js';
+import { createDynamicsSampler, supportDiagnostics } from './motion/physics-support.js';
+import { computeCenterOfMass } from './motion/center-of-mass.js';
+import { buildCollisionCapsules, detectPenetrations, supportsCollisionCleanup } from './motion/fix-collisions.js';
+import { collisionBlockers, blockerSummary } from './motion/collision-blockers.js';
+import { createGroundSampler } from './motion/ground.js';
 import { OBJECT_LIBRARY } from './scene-objects.js';
 import { objectTransformAt } from './object-path.js';
 import { sampleAt } from './sample-at.js';
@@ -50,7 +50,7 @@ function disposeRig(value) {
 }
 function poseFrame(evaluator, motion, layer, frame) {
   restore(evaluator.rest);
-  if (motion) applyMotionFrame(evaluator.rig, motion, sampleAt({ frameCount: motion.frames, motion }, null, frame).motionFrame);
+  if (motion) applyTakeFrame(evaluator.rig, motion, sampleAt({ frameCount: motion.frames, motion }, null, frame).motionFrame);
   if (layer) ikEvaluate(evaluator.chains, layer, frame, evaluator.fkJoints, motion ? BLEND : 0);
   evaluator.parent.updateMatrixWorld(true);
 }