cozyclay 2.1.0 → 3.0.0

package/src/stage-occlusion.js

@@ -0,0 +1,210 @@
+// Ambient occlusion for the stage look (stage.lighting.ao): contact darkening
+// where a body meets the floor or a prop, and in creases (an armpit, the back of
+// a knee in a squat). Screen space, because the bodies are skinned and move: a
+// baked aoMap cannot follow a skinned mesh, and contact blobs under the feet
+// miss every crease.
+//
+// One hook on the scene (scene.onAfterRender) runs it after each draw of the
+// stage through a perspective camera, so every path gets it with no code of its
+// own: the viewport panes, the shot preview card, capture_frame, contact sheets
+// and video export (stage-capture.jsx renders the same scene into its target).
+// A draw with an override material (the outline prepass, the depth and normal
+// plates) is left alone, and so is the orthographic plan.
+//
+// Per draw, at half resolution past 960 px wide: a depth-only prepass of the
+// opaque set, the occlusion within AO_RADIUS of each pixel from SAMPLES samples
+// (how far each sample's direction rises above the surface the depth holds,
+// weighted toward the near ones and faded with the fog), a depth-aware 5x5
+// blur, then a multiply over the frame just drawn. The prepass reuses the
+// shadow maps the draw already made. On an Apple M4 Pro it adds about 0.4 ms of
+// GPU time to a 1920x1080 export frame.
+import * as THREE from "three";
+import { FullScreenQuad } from "three/examples/jsm/postprocessing/Pass.js";
+import { GIZMO_LAYER, POSER_LAYER } from "./dualview.jsx";
+
+const AO_RADIUS = 0.4;
+const SAMPLES = 16;
+// A sample whose direction rises less than this cosine above the normal is the
+// same surface (floor noise at grazing angles), not an occluder.
+const BIAS = 0.15;
+// Occlusion to darkening, tuned by eye on the clay figure (a squat's creases, feet on the deck).
+const GAIN = 3;
+// Size buckets kept alive at once (the main pane, the preview card, the exports).
+const CACHED_SIZES = 4;
+
+const VERTEX = "varying vec2 vUv;\nvoid main() { vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }";
+const OCCLUSION = `
+uniform sampler2D tDepth;
+uniform mat4 projection;
+uniform mat4 inverseProjection;
+uniform vec2 size;
+uniform vec2 fog;
+varying vec2 vUv;
+vec3 viewAt(vec2 uv, float depth) {
+	vec4 p = inverseProjection * vec4(vec3(uv, depth) * 2.0 - 1.0, 1.0);
+	return p.xyz / p.w;
+}
+vec3 viewAt(vec2 uv) { return viewAt(uv, texture2D(tDepth, uv).x); }
+void main() {
+	float depth = texture2D(tDepth, vUv).x;
+	if (depth >= 1.0) { gl_FragColor = vec4(1.0); return; }
+	vec3 p = viewAt(vUv, depth);
+	// The normal of the surface the depth buffer holds (each axis from the nearer
+	// neighbour, so an edge does not bend it): flat facets of the low-poly clay
+	// then occlude nothing of their own, whatever their smoothed shading normal says.
+	vec2 texel = 1.0 / size;
+	vec3 right = viewAt(vUv + vec2(texel.x, 0.0)) - p, left = p - viewAt(vUv - vec2(texel.x, 0.0));
+	vec3 up = viewAt(vUv + vec2(0.0, texel.y)) - p, down = p - viewAt(vUv - vec2(0.0, texel.y));
+	vec3 n = normalize(cross(abs(right.z) < abs(left.z) ? right : left, abs(up.z) < abs(down.z) ? up : down));
+	float reach = min(${AO_RADIUS.toFixed(2)} * projection[1][1] * 0.5 * size.y / -p.z, size.y * 0.2);
+	float fade = 1.0 - smoothstep(fog.x, fog.y, -p.z);
+	if (reach < 1.0 || fade <= 0.0) { gl_FragColor = vec4(1.0); return; }
+	float spin = 6.2831853 * fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
+	// A weighted mean over the samples near the surface (weight falls to 0 at RADIUS),
+	// so an occluder close by counts fully however small it is on screen.
+	float occlusion = 0.0, weights = 0.25;
+	for (int i = 0; i < ${SAMPLES}; i++) {
+		float angle = float(i) * 2.39996323 + spin;
+		// snapped to a texel centre, so the depth read and the position rebuilt from it agree
+		vec2 uv = (floor((vUv + vec2(cos(angle), sin(angle)) * ((float(i) + 0.5) / ${SAMPLES}.0) * reach / size) * size) + 0.5) / size;
+		vec3 v = viewAt(uv) - p;
+		float distance = length(v), weight = pow(max(0.0, 1.0 - distance / ${AO_RADIUS.toFixed(2)}), 2.0);
+		occlusion += max(dot(v, n) / max(distance, 1e-4) - ${BIAS.toFixed(2)}, 0.0) * weight;
+		weights += weight;
+	}
+	float ao = clamp(1.0 - ${GAIN.toFixed(2)} * occlusion / (weights * ${(1 - BIAS).toFixed(2)}), 0.0, 1.0);
+	gl_FragColor = vec4(vec3(mix(1.0, ao, fade)), 1.0);
+}`;
+const BLUR = `
+#include <packing>
+uniform sampler2D tOcclusion;
+uniform sampler2D tDepth;
+uniform vec2 size;
+uniform vec2 clip;
+varying vec2 vUv;
+float viewZ(vec2 uv) { return perspectiveDepthToViewZ(texture2D(tDepth, uv).x, clip.x, clip.y); }
+void main() {
+	float z = viewZ(vUv), total = 0.0, weights = 0.0;
+	for (int x = -2; x <= 2; x++) for (int y = -2; y <= 2; y++) {
+		vec2 uv = vUv + vec2(float(x), float(y)) / size;
+		float weight = 1.0 - smoothstep(0.02, 0.06, abs(viewZ(uv) - z) / -z);
+		total += texture2D(tOcclusion, uv).r * weight;
+		weights += weight;
+	}
+	gl_FragColor = vec4(vec3(total / max(weights, 1e-4)), 1.0);
+}`;
+const COMPOSITE = `
+uniform sampler2D tOcclusion;
+uniform float strength;
+varying vec2 vUv;
+void main() { gl_FragColor = vec4(vec3(mix(1.0, texture2D(tOcclusion, vUv).r, strength)), 1.0); }`;
+
+const pass = (fragmentShader, uniforms, extra = {}) => new THREE.ShaderMaterial({ vertexShader: VERTEX, fragmentShader, uniforms, depthTest: false, depthWrite: false, ...extra });
+const target = (width, height, filter, depth = false) => new THREE.WebGLRenderTarget(width, height, {
+	minFilter: filter, magFilter: filter, depthBuffer: depth, generateMipmaps: false,
+	...(depth ? { depthTexture: Object.assign(new THREE.DepthTexture(width, height, THREE.UnsignedIntType), { minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter }) } : {}),
+});
+// What the prepass leaves out: light rather than surface (glow halos, smoke,
+// see-through and faded parts, ghosts), picture cards whose alpha a solid
+// depth pass would ignore, lines and points.
+const seeThrough = (material) => [material].flat().some((m) => m && (m.transparent || m.depthWrite === false));
+const leftOut = (node) => node.userData?.beautyOnly || node.userData?.cutoutTexture !== undefined || node.isSprite || node.isPoints || node.isLine || (node.isMesh && seeThrough(node.material));
+
+/**
+ * Put the occlusion pass on `scene`. `settings.strength` (0..1) is read at each
+ * draw, so a slider changes it without rebuilding anything. Answers a function
+ * that takes the hook off and frees the targets.
+ */
+export function installOcclusion(scene, settings) {
+	// Depth is all the pass reads: the prepass writes no colour at all.
+	const depthOnly = new THREE.MeshBasicMaterial({ side: THREE.DoubleSide, colorWrite: false });
+	const occlusion = pass(OCCLUSION, { tDepth: { value: null }, projection: { value: new THREE.Matrix4() }, inverseProjection: { value: new THREE.Matrix4() }, size: { value: new THREE.Vector2() }, fog: { value: new THREE.Vector2() } });
+	const blur = pass(BLUR, { tOcclusion: { value: null }, tDepth: { value: null }, size: { value: new THREE.Vector2() }, clip: { value: new THREE.Vector2() } });
+	const composite = pass(COMPOSITE, { tOcclusion: { value: null }, strength: { value: 1 } }, {
+		blending: THREE.CustomBlending, blendEquation: THREE.AddEquation, blendSrc: THREE.ZeroFactor, blendDst: THREE.SrcColorFactor,
+		blendSrcAlpha: THREE.ZeroFactor, blendDstAlpha: THREE.OneFactor, toneMapped: false,
+	});
+	const quad = new FullScreenQuad(), sizes = new Map(), viewport = new THREE.Vector4(), scissor = new THREE.Vector4();
+	let running = false;
+	const targetsFor = (width, height) => {
+		const key = `${width}x${height}`;
+		let set = sizes.get(key);
+		if (set) sizes.delete(key);
+		else set = { prepass: target(width, height, THREE.NearestFilter, true), raw: target(width, height, THREE.NearestFilter), smooth: target(width, height, THREE.LinearFilter) };
+		sizes.set(key, set);
+		if (sizes.size > CACHED_SIZES) {
+			const [oldest, stale] = sizes.entries().next().value;
+			sizes.delete(oldest);
+			for (const t of Object.values(stale)) { t.depthTexture?.dispose(); t.dispose(); }
+		}
+		return set;
+	};
+	scene.onAfterRender = (renderer, _scene, camera) => {
+		if (running || scene.overrideMaterial || !camera?.isPerspectiveCamera || !(settings.strength > 0)) return;
+		running = true;
+		const output = renderer.getRenderTarget(), autoClear = renderer.autoClear, background = scene.background, mask = camera.layers.mask;
+		const shadows = renderer.shadowMap, shadowAuto = shadows.autoUpdate, shadowNeeds = shadows.needsUpdate;
+		renderer.getViewport(viewport);
+		renderer.getScissor(scissor);
+		const pixels = renderer.getCurrentViewport(new THREE.Vector4()), half = pixels.z > 960 ? 0.5 : 1;
+		const width = Math.max(1, Math.round(pixels.z * half)), height = Math.max(1, Math.round(pixels.w * half));
+		const { prepass, raw, smooth } = targetsFor(width, height), hidden = [];
+		try {
+			scene.traverse((node) => { if (node.visible && leftOut(node)) { hidden.push(node); node.visible = false; } });
+			scene.background = null;
+			scene.overrideMaterial = depthOnly;
+			camera.layers.disable(GIZMO_LAYER);
+			camera.layers.disable(POSER_LAYER);
+			shadows.autoUpdate = false;
+			renderer.autoClear = true;
+			renderer.setRenderTarget(prepass);
+			renderer.render(scene, camera);
+			for (const node of hidden.splice(0)) node.visible = true;
+			scene.background = background;
+			scene.overrideMaterial = null;
+			camera.layers.mask = mask;
+			const u = occlusion.uniforms, b = blur.uniforms, fog = scene.fog;
+			u.tDepth.value = b.tDepth.value = prepass.depthTexture;
+			u.projection.value.copy(camera.projectionMatrix);
+			u.inverseProjection.value.copy(camera.projectionMatrixInverse);
+			u.size.value.set(width, height);
+			u.fog.value.set(fog?.near ?? 1e5, fog?.far ?? 2e5);
+			renderer.setRenderTarget(raw);
+			quad.material = occlusion;
+			quad.render(renderer);
+			b.tOcclusion.value = raw.texture;
+			b.size.value.set(width, height);
+			b.clip.value.set(camera.near, camera.far);
+			renderer.setRenderTarget(smooth);
+			quad.material = blur;
+			quad.render(renderer);
+			composite.uniforms.tOcclusion.value = smooth.texture;
+			composite.uniforms.strength.value = Math.min(1, settings.strength);
+			renderer.setRenderTarget(output);
+			// The canvas takes back the pane's own viewport (setRenderTarget(null) floors it, the draw rounded it).
+			if (output === null) {
+				renderer.setViewport(viewport);
+				renderer.setScissor(scissor);
+			}
+			renderer.autoClear = false;
+			quad.material = composite;
+			quad.render(renderer);
+		} finally {
+			for (const node of hidden) node.visible = true;
+			if (renderer.getRenderTarget() !== output) renderer.setRenderTarget(output);
+			scene.background = background;
+			scene.overrideMaterial = null;
+			camera.layers.mask = mask;
+			shadows.autoUpdate = shadowAuto;
+			shadows.needsUpdate = shadowNeeds;
+			renderer.autoClear = autoClear;
+			running = false;
+		}
+	};
+	return () => {
+		delete scene.onAfterRender;
+		for (const set of sizes.values()) for (const t of Object.values(set)) { t.depthTexture?.dispose(); t.dispose(); }
+		for (const material of [depthOnly, occlusion, blur, composite]) material.dispose();
+		quad.dispose();
+	};
+}

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,8 +108,8 @@ 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: "object.attach", label: "Attach to character", kind: "mutation", undoDomain: "objects",
@@ -125,6 +123,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 +151,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 +213,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';
@@ -11,6 +11,8 @@ import { coplanarConflicts } from './coplanar-depth.js';
 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); };
@@ -240,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;
@@ -368,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);
@@ -399,6 +400,32 @@ export function framingChecks(ids, state, ports) {
   const projected = projectSubject(boxes.flat(), state.camera, focalMmToFov(state.camera.focalMm, state.filmback.sensorId, state.filmback.aspectRatio), state.filmback.aspectRatio).checks;
   return { ...projected, ...sightChecks(subjects, boxes, state.camera.position, state, ports).checks };
 }
+
+/** Framing evidence over explicit timeline samples. The caller supplies the
+ * sampled state so camera keys and animated subject bounds use the same frame.
+ * A sample is evidence for that frame only; it is never advertised as an
+ * all-frame proof. */
+export function sampledFramingChecks(ids, state, ports, frames) {
+  if (!Array.isArray(frames) || !frames.length) fail('INVALID_RANGE', 'Framing sampling needs at least one timeline frame.');
+  if (typeof ports.sampleStateAt !== 'function') fail('CAPABILITY_MISSING', 'This editor cannot sample framing at timeline frames.');
+  const samples = frames.map(frame => {
+    const sampledState = ports.sampleStateAt(frame, state);
+    if (!sampledState) fail('TARGET_NOT_READY', `The editor could not read timeline frame ${frame}.`);
+    const checks = framingChecks(ids, sampledState, ports), codes = [checks.clipped ? 'CLIPPED' : null, checks.behindCamera ? 'BEHIND_CAMERA' : null, checks.occluded ? 'OCCLUDED' : null].filter(Boolean);
+    return { frame, checks, codes };
+  });
+  const sampledChecks = samples.map(({ frame, checks }) => ({ frame, screenFraction: checks.screenFraction, clipped: checks.clipped, behindCamera: checks.behindCamera, occluded: checks.occluded }));
+  const issueFrames = samples.filter(sample => sample.codes.length).map(({ frame, checks, codes }) => ({ frame, codes, screenFraction: checks.screenFraction }));
+  return { ...samples.at(-1).checks, coverage: 'sampled-timeline-subject-bounds-projection', evaluatedFrames: frames.length, sampledFrames: frames, sampledChecks, issueFrames };
+}
+export function sampledFramingResult(args, scene, ports, frameCount, measured, receipt) {
+  const range = args.range === 'whole_clip' ? { startFrame: 0, endFrameExclusive: frameCount } : args.range;
+  if (range.endFrameExclusive > frameCount) fail('INVALID_RANGE', 'Framing verification range exceeds the scene timeline.');
+  const ids = measured ?? (args.targets ?? receipt?.affectedIds ?? []).filter(id => scene.objects.some(o => o.id === id) || scene.characters.some(c => c.id === id));
+  if (!ids.length) return { reason: 'No target is available for sampled framing verification.' };
+  try { return sampledFramingChecks(ids, scene, ports, sampleContactSheetFrames(args.range, frameCount)); }
+  catch (error) { if (!(error instanceof StudioProtocolError)) throw error; return { reason: error.message }; }
+}
 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]);
@@ -409,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;
@@ -430,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] } };
 }
@@ -487,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}.`))])) });