cozyclay 2.1.0 → 3.0.0

package/src/studio-elements.js

@@ -31,15 +31,13 @@ const entries = [
 	{ path: "character.identityImage", type: "image", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", note: "data:image only" },
 	{ path: "character.pose", type: "id", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
 	{ path: "character.waypoints", type: "array", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", actions: ["character.addWaypoint", "character.moveWaypoint", "character.removeWaypoint", "character.clearWaypoints"], note: "root path pins, addressed by frame" },
-	{ path: "character.promptBlocks", type: "array", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", note: "stored at layer.promptClips" },
-	{ path: "character.motionRef.url", type: "string", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
-	{ path: "character.motionRef.motionId", type: "id", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
+	
 	{ path: "character.sessionMotion", type: "array", persisted: false, undoDomain: "cast", normalizer: "createCharacterEntry", note: "dropped by createCharacterEntry" },
 	{ path: "character.ikKeys", type: "array", persisted: false, undoDomain: "cast", normalizer: "createCharacterEntry", actions: ["character.setIkKey", "character.removeIkKey", "character.clearIkKeys"], note: "dropped by createCharacterEntry; keys travel as JSON quaternions/positions" },
-	{ path: "object.renderer", type: "enum", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["cube", "sphere", "capsule", "cylinder", "cone", "plane", "chair", "car", "small-plane", "empty"] },
+	{ path: "object.renderer", type: "enum", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["cube", "sphere", "capsule", "cylinder", "cone", "plane", "chair", "car", "small-plane", "empty", "light", "effect"], note: "light is made from catalogue kind point-light or spot-light; effect (smoke, fire, rain, trail...) from kind effect" },
 	{ path: "object.position", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: -240, y: 0, z: -240 }, max: { x: 240, y: 240, z: 240 }, note: "y is the object's base: y=0 rests on the floor; height/supportY rise from it" },
-	{ path: "object.rotation", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: -180, y: -180, z: -180 }, max: { x: 180, y: 180, z: 180 }, note: "rot/rotX/rotZ degrees, wrapped at the upper bound" },
-	{ path: "object.scale", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: 0.1, y: 0.1, z: 0.1 }, max: { x: 100, y: 100, z: 100 } },
+	{ path: "object.rotation", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: -180, y: -180, z: -180 }, max: { x: 180, y: 180, z: 180 }, angle: true, note: "rot/rotX/rotZ degrees, wrapped at the upper bound" },
+	{ path: "object.scale", type: "vec3", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: { x: 0.01, y: 0.01, z: 0.01 }, max: { x: 100, y: 100, z: 100 } },
 	{ path: "object.name", type: "string", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.color", type: "color", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.opacity", type: "number", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", min: 0.05, max: 1, note: "1 is solid; lower is see-through, e.g. 0.3 for clear glass" },
@@ -48,6 +46,9 @@ const entries = [
 	{ path: "object.path", type: "array", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.remove", type: "boolean", persisted: true, undoDomain: "objects", normalizer: null, note: "lifecycle operation, not a document field" },
 	{ path: "object.cutout", type: "image", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", actions: ["asset.import"], note: "assetId-backed cutout record; imported pictures and models are placed by asset.import" },
+	{ path: "object.light", type: "object", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", note: "renderer light only. { type point|spot, color, intensity 0..1000 candela (lighter 0.45, candle 0.3, desk lamp 5, street lamp 40), range m (0 none), angle 1..89 deg spot half-angle, softness 0..1, shadow (first 2 lights only; inside a solid record it is blocked: receipt LIGHT_BLOCKED), flicker 0..1 (lighter 0.6), aim {x,y,z} world point or null = local -Y }, e.g. { intensity: 40, aim: { x: 0, y: 0, z: 1 } }; a take level track scales it" },
+	{ path: "object.glow", type: "object", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", note: "any record: self-lit colour plus additive halo, same under any stage light; casts no shadow, so a light inside a glowing bulb shines out. { color, intensity 0..20, halo 0..4 x the record's radius }, e.g. ember { color: \"#ff5a1f\", intensity: 6, halo: 2 }; null removes; a take level track scales it" },
+	{ path: "object.effect", type: "object", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", note: "renderer effect only (object.add kind \"effect\"). { preset: smoke|exhale|steam|fire|sparks|dust|rain|snow|trail, rate particles/s, life s, size m start diameter, grow end/start size, speed m/s along the record's local +Y (rotX 90 aims +Z), spread 0..1 cone, gravity m/s2 (+ falls, - rises), wind {x,y,z} m/s, color, opacity 0..1, additive (emissive: fire, sparks), seed int, area {x,y,z} m birth box (rain/snow/dust fall through it from its top), width m trail ribbon across local Y }. A new preset loads its defaults and fields in the same set override them, e.g. { preset: \"fire\", rate: 40 }; the record stores the merged numbers. Particles are born where the record is at each frame (route, parent, take carry), only while it and its parents are shown, at rate x the take level. To emit from the body (a breath at the mouth), a motion spec entry objects.<id> = { follow: \"landmark:mouth\", aim: \"face\" } moves it there every frame. Measure with inspect_studio { scope: \"entities\", ids }: effect { frame (the playhead), alive, emitter [x,y,z], bounds { min, max } m }" },
 	{ path: "stage.keyLight.x", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: -30, max: 30 },
 	{ path: "stage.keyLight.y", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0.5, max: 30 },
 	{ path: "stage.keyLight.z", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: -30, max: 30 },
@@ -60,6 +61,25 @@ const entries = [
 	{ path: "stage.camera", documentPath: "shotAspect", type: "enum", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", enum: ["16:9", "2.39:1", "9:16", "1:1", "4:3", "12:7", "fal 480P"], note: "output aspect ratio" },
 	{ path: "stage.cameraPresetId", type: "id", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage" },
 	{ path: "stage.sensorId", type: "enum", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", enum: ["super16", "super35", "fullFrame", "65mm"] },
+	// The stage look (src/stage-lighting.js). stage.applyLighting writes all of it from a recipe; each field stays tweakable.
+	{ path: "stage.keyLight.color", type: "color", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "key light colour #rrggbb, overrides warmth, e.g. \"#9db6e6\" cool moonlight or \"#ffad5c\" low sun; null = white tinted by warmth" },
+	{ path: "stage.lighting.preset", type: "enum", persisted: true, readOnly: true, undoDomain: "stage", normalizer: "createSceneStage", enum: ["studio", "day", "overcast", "golden", "dusk", "night", "interior", "stage"], note: "label of the last recipe stage.applyLighting applied; studio is the neutral grey default" },
+	{ path: "stage.lighting.sky", type: "color", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "background and fog colour at the horizon, e.g. \"#0b1426\" night; null = the UI theme's studio grey" },
+	{ path: "stage.lighting.skyTop", type: "color", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "sky colour overhead: shot camera and exports grade from sky at the horizon to this, e.g. \"#020408\"; null = flat sky" },
+	{ path: "stage.lighting.ambient", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 3, note: "multiplier on the hemisphere and ambient light; 1 = studio, 0.6 = night, 0 = black stage" },
+	{ path: "stage.lighting.hemiSky", type: "color", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "hemisphere light from above, e.g. \"#34507f\" cool night sky; studio \"#ffffff\"" },
+	{ path: "stage.lighting.hemiGround", type: "color", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "hemisphere bounce from below, e.g. \"#6e5136\" warm ground; studio \"#5a5d64\"" },
+	{ path: "stage.lighting.fill", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 3, note: "multiplier on the fixed fill and rim lights; 1 = studio, 0 = key only" },
+	{ path: "stage.lighting.fog", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 1, note: "haze 0..1 fading the set into the sky colour: 0 = far horizon only, 0.45 = from ~18 m to ~38 m, 1 = from 2 m to 14 m" },
+	{ path: "stage.lighting.exposure", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0.2, max: 3, note: "camera exposure multiplier on lit surfaces; 1 = studio, e.g. 1.4 to lift a dark frame" },
+	{ path: "stage.lighting.shadowSoftness", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 1, note: "key shadow penumbra; 0 = crisp (studio), 0.75 = soft moonlight, 1 = overcast" },
+	{ path: "stage.lighting.envLight", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 2, note: "sky environment light on every surface: a map from sky, skyTop, hemiGround and a glow toward the key (sun or moon) tints and fills clay from all sides; it takes over the flat hemisphere as it rises. 0 = hemisphere only (studio), 1 = the map alone at the same brightness (every other recipe), e.g. 1.4 for a brighter fill" },
+	{ path: "stage.lighting.ao", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 1, note: "ambient occlusion strength: contact darkening within ~0.5 m where a body meets the floor or a prop and in creases (armpits, the back of a squat's knees), in the viewport and every export. 0 = off (studio), 0.8 = most recipes, 1 = overcast" },
+	// An HDR environment map (src/stage-hdr.js): the light and, with hdrBackground, the backdrop.
+	{ path: "stage.lighting.hdr", type: "id", nullable: true, persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "HDR environment map that replaces the sky environment light: a built-in (\"builtin:night-street\", \"builtin:overcast-field\", \"builtin:studio-softbox\") or a file the user loaded (\"hdr-<32 hex>\"); inspect_studio { scope: \"catalogue\" } environments lists them with each map's brightest direction. It lights the set only while envLight > 0 (its light = map x hdrIntensity x envLight; studio has envLight 0, so set envLight 1). stage.applyLighting clears it unless keep has \"lighting.hdr\". null = the look's own sky" },
+	{ path: "stage.lighting.hdrRotation", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: -180, max: 180, angle: true, note: "degrees the HDR map turns about the vertical axis, light and backdrop together: +90 carries a light at +x (screen right from the default camera) to -z (behind the subject), so a brightest [x, y, z] lands at [x cos r + z sin r, y, z cos r - x sin r]; wrapped at the upper bound" },
+	{ path: "stage.lighting.hdrIntensity", type: "number", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", min: 0, max: 4, note: "multiplier on the HDR map's radiance in its light and its backdrop; 1 = the file as authored, e.g. 0.5 to calm a bright daylight map" },
+	{ path: "stage.lighting.hdrBackground", type: "boolean", persisted: true, undoDomain: "stage", normalizer: "createSceneStage", note: "true = the HDR map is the backdrop behind the set (the floor fades into its horizon), in the viewport, shot and every export; false = keep the look's sky as the backdrop and use the map only as light" },
 	{ path: "shot.crud", type: "array", persisted: true, undoDomain: "shot", normalizer: null, actions: ["shot.create", "shot.split", "shot.duplicate", "shot.remove", "shot.setRange", "shot.reorder"], note: "create/split/duplicate/reorder/remove/range through the shared action registry" },
 	{ path: "shot.cameraKeys", type: "array", persisted: true, undoDomain: "shot", normalizer: null, frameMin: 0 },
 	{ path: "shot.cameraRail", type: "array", persisted: true, undoDomain: "shot", normalizer: "repairCamera", actions: ["shot.setCameraRail", "shot.clearCameraRail"], note: "rail points; crane/dolly timing follow the shot's camera block" },
@@ -74,7 +94,7 @@ const entries = [
 	{ path: "selection", type: "id", persisted: false, undoDomain: null, normalizer: null },
 	{ path: "timeline", type: "number", persisted: false, undoDomain: null, normalizer: null },
 	{ path: "view.mode", type: "enum", persisted: false, undoDomain: null, normalizer: null, enum: ["scene", "pose", "camera", "motion"] },
-	{ path: "view.partColoursGuideModeInset", type: "array", persisted: false, undoDomain: null, normalizer: null, actions: ["view.setPartColours", "view.setGuideMode", "view.setInset"], note: "partColours/guideMode/inset; viewer settings, not document fields" },
+	{ path: "view.partColoursGuideModeInset", type: "array", persisted: false, undoDomain: null, normalizer: null, actions: ["view.setPartColours", "view.setGuideMode", "view.setInset", "view.setGhosts"], note: "partColours/guideMode/inset/ghosts; viewer settings, not document fields" },
 	{ path: "read.sceneDescription", type: "string", persisted: false, undoDomain: null, normalizer: null },
 	{ path: "read.captureFrame", type: "image", persisted: false, undoDomain: null, normalizer: null },
 	{ path: "undo", type: "boolean", persisted: false, undoDomain: null, normalizer: null },

package/src/studio-entity-bounds.js

@@ -0,0 +1,18 @@
+// The world box an object row reports, in inspect_studio entities, the per-turn context and an
+// action readback alike: a body's own box at the playhead (entityWorldBounds, metres, 4 decimals);
+// for a node with no body (an empty or a light) the union of every body under it, so a group
+// built from parts shows where the whole thing ends; null when nothing there can be measured.
+import { entityWorldBounds } from "./studio-agent-commands.js";
+import { descendantsOf, isEmptyObject } from "./scene-objects.js";
+
+const AXES = ["x", "y", "z"];
+
+/** World AABB {min,max} of scene object `object` in refreshed Studio state `s`, or null. */
+export function objectRowBounds(object, s, ports) {
+	const state = { ...s, frame: s.view.frame }, measure = o => entityWorldBounds(o, state, { bounds: ports.bounds });
+	if (!isEmptyObject(object)) return measure(object);
+	const boxes = descendantsOf(s.objects, object.id).filter(o => !isEmptyObject(o)).map(measure).filter(Boolean);
+	if (!boxes.length) return null;
+	return { min: Object.fromEntries(AXES.map(a => [a, Math.min(...boxes.map(b => b.min[a]))])),
+		max: Object.fromEntries(AXES.map(a => [a, Math.max(...boxes.map(b => b.max[a]))])) };
+}

package/src/studio-error-codes.js

@@ -0,0 +1,8 @@
+// The error codes a Studio receipt or failure may carry. Shared by the browser
+// and sidecar; no imports.
+export const STUDIO_ERROR_CODES = Object.freeze([
+	"INVALID_ARGUMENT", "INVALID_CONTEXT", "INVALID_IDENTITY", "INVALID_TURN_ID", "INVALID_SESSION_ID", "INVALID_RECEIPT", "INVALID_RANGE", "INVALID_REQUEST",
+	"UNKNOWN_TOOL", "UNKNOWN_VARIANT", "DUPLICATE_NAME", "CONTEXT_LIMIT", "CONTEXT_TOO_LARGE", "AMBIGUOUS_TARGET", "AMBIGUOUS_BASIS", "TARGET_NOT_READY", "TARGET_BUSY",
+	"STALE_TARGET", "STALE_SCENE", "STALE_ENVIRONMENT", "STALE_CURSOR", "CAPABILITY_MISSING", "LIVE_HUB_UNAVAILABLE", "AUTH_REQUIRED", "GENERATION_LIMIT", "RATE_LIMITED", "BACKEND_UNAVAILABLE",
+	"VERIFICATION_FAILED", "REPAIR_REGRESSED", "CANCELLED", "UNCERTAIN_APPLY", "UNDO_CONFLICT", "CONFIRMATION_REQUIRED", "TIMEOUT", "UNDO_EXPIRED",
+]);

package/src/studio-export-framing.js

@@ -0,0 +1,152 @@
+// What the export camera shows of a take (verify_result motion, exportFraming): at each sampled frame
+// the camera the export renders there (ports.sampleStateAt: the shot's camera where a shot covers the
+// frame, else the Studio camera as it stands), and through it the character's joints (as motion.sample
+// reads them) and the take's objects (moved by the take's tracks, object-travel.js), projected as
+// frame_shot projects a subject (studio-agent-commands.js projectSubject). Measurements, not verdicts:
+// how much of the character and of each object is inside the frame, and over which sampled frames a
+// part (head, hands, feet) or an object (the outline of each of its bodies) is cut or out. Frames are
+// absolute timeline frames; a span joins consecutive samples ([first, last] sampled frame).
+import { Euler, Vector3 } from "three";
+import { StudioProtocolError } from "./studio-agent-protocol.js";
+import { projectSubject, entityWorldBounds } from "./studio-agent-commands.js";
+import { focalMmToFov, SENSOR_FORMATS } from "./shot.js";
+import { shotAtFrame } from "./cuts.js";
+import { sceneObjectsAt } from "./object-travel.js";
+import { descendantsOf, isEmptyObject } from "./scene-objects.js";
+import { skeletonFor } from "./motion3/rigs/index.js";
+import { fk } from "./motion3/compiler/skeleton.js";
+import { add, apply, ry } from "./motion3/compiler/math.js";
+
+const SAMPLES = 24, TAKE_SCHEMA = "cozyclay.take.v3", BARE_OBJECT = /^object:(.+?)(\.(?:center|top|base))?$/s;
+const PARTS = Object.freeze({ head: ["Head", "HeadTop_End"], hand_l: ["LeftHand", "LeftHandMiddle4", "LeftHandIndex4"], hand_r: ["RightHand", "RightHandMiddle4", "RightHandIndex4"],
+	foot_l: ["LeftFoot", "LeftToe_End"], foot_r: ["RightFoot", "RightToe_End"] });
+const r2 = v => Math.round(v * 100) / 100;
+
+/** Up to n frames spread evenly over [lo, hi], both ends included. */
+export function exportSampleFrames(lo, hi, n = SAMPLES) {
+	if (hi <= lo) return [lo];
+	const count = Math.min(n, hi - lo + 1);
+	return [...new Set(Array.from({ length: count }, (_, i) => Math.round(lo + (i * (hi - lo)) / (count - 1))))];
+}
+
+/** [[first, last], ...] of the sampled frames whose flag is set, consecutive samples joined. */
+export function sampleSpans(frames, flags) {
+	const spans = [];
+	frames.forEach((frame, i) => {
+		if (!flags[i]) return;
+		if (i > 0 && flags[i - 1]) spans.at(-1)[1] = frame; else spans.push([frame, frame]);
+	});
+	return spans;
+}
+
+/** World joint positions of a v3 take at timeline frame f, in take bone order (motion.sample's reading). */
+function jointsAt(sk, take, f) {
+	const B = take.bones.length, ff = Math.max(0, Math.min(take.frameCount - 1, Math.round(f)));
+	const quats = Array.from({ length: B }, (_, b) => Array.from(take.rot.subarray((ff * B + b) * 4, (ff * B + b) * 4 + 4)));
+	const state = fk(sk, quats, Array.from(take.hips.subarray(ff * 3, ff * 3 + 3)));
+	const yaw = ry(take.placement?.yaw ?? 0), at = take.placement?.position ?? [0, 0, 0];
+	return state.P.map(p => add(at, apply(yaw, p)));
+}
+
+/** Scene object ids a spec names: spec.objects keys, object:<id> refs and any string value that is an object id. */
+export function takeObjectIds(spec, objects) {
+	const known = new Set(objects.map(o => o.id)), ids = new Set(Object.keys(spec?.objects ?? {}).filter(id => known.has(id)));
+	const walk = value => {
+		if (typeof value === "string") { const id = BARE_OBJECT.exec(value)?.[1] ?? value; if (known.has(id)) ids.add(id); }
+		else if (Array.isArray(value)) value.forEach(walk);
+		else if (value && typeof value === "object") Object.values(value).forEach(walk);
+	};
+	walk(spec);
+	return [...ids];
+}
+
+/** How a set of world points lands in the camera: the projection and how much of its screen box is inside the frame. */
+function landing(points, view) {
+	const forward = new Vector3().subVectors(view.lookAt, view.position);
+	const behind = points.filter(p => p.clone().sub(view.position).dot(forward) <= 0).length;
+	if (behind === points.length) return { behind: true, cut: true, fraction: 0, screenFraction: 0 };
+	const { screenBounds: b, checks } = projectSubject(points, view.camera, view.fov, view.aspect);
+	if (behind) return { behind: true, cut: true, fraction: null, screenFraction: checks.screenFraction };
+	// the share of each screen axis inside [-1, 1]; a box flat along an axis is in or out whole
+	const share = ({ min, max }) => max - min > 1e-6 ? Math.max(0, Math.min(1, max) - Math.max(-1, min)) / (max - min) : Math.abs(min) <= 1 ? 1 : 0;
+	return { behind: false, cut: checks.clipped, fraction: share(b.x) * share(b.y), screenFraction: checks.screenFraction };
+}
+
+const corners = box => [box.min.x, box.max.x].flatMap(x => [box.min.y, box.max.y].flatMap(y => [box.min.z, box.max.z].map(z => new Vector3(x, y, z))));
+const RING = Array.from({ length: 8 }, (_, i) => [Math.cos(i * Math.PI / 4), Math.sin(i * Math.PI / 4)]);
+// A body's outline in its own frame (base pivot, local +Y up, 1 m primitives scaled): rims for the round
+// primitives, so a disc seen face on is not measured by the corners of its box; box corners otherwise.
+const OUTLINES = { cylinder: [[0, 1], [1, 1]], cone: [[0, 1], [1, 0]], sphere: [[0, 0], [0.5, 1], [1, 0]], capsule: [[0, 0], [0.25, 1], [0.75, 1], [1, 0]] };
+/** World points outlining a body as drawn at its posed record: the same placement geometry() uses for a box. */
+function bodyPoints(object, state, ports) {
+	const outline = OUTLINES[object.renderer];
+	if (object.attach || object.path || !object.footprint) { const box = entityWorldBounds(object, state, { bounds: ports.bounds }); return box ? corners(box) : []; }
+	const w = object.footprint.width * object.scaleX / 2, d = object.footprint.depth * object.scaleZ / 2, h = object.height * object.scaleY;
+	const local = outline ? outline.flatMap(([y, r]) => r ? RING.map(([c, s]) => [w * r * c, y * h, d * r * s]) : [[0, y * h, 0]])
+		: [-w, w].flatMap(x => [0, h].flatMap(y => [-d, d].map(z => [x, y, z])));
+	const rotation = new Euler((object.rotX ?? 0) * Math.PI / 180, (object.rot ?? 0) * Math.PI / 180, (object.rotZ ?? 0) * Math.PI / 180, "XYZ");
+	return local.map(([x, y, z]) => new Vector3(x, y, z).applyEuler(rotation).add(new Vector3(object.x, object.y ?? 0, object.z)));
+}
+const lowest = (rows, frames) => rows.reduce((best, row, i) => row !== null && (best === null || row < best[0]) ? [r2(row), frames[i]] : best, null);
+
+/**
+ * exportFraming for one character's installed v3 take. scene: the binding's command state (objects,
+ * characters, camera, filmback, shotDocument); ports: { sampleStateAt, bounds }; range: verify_result's
+ * range ("whole_clip" or { startFrame, endFrameExclusive }).
+ */
+export function exportFraming({ character, take, scene, ports, range }) {
+	const sensorId = scene.filmback?.sensorId, aspect = scene.filmback?.aspectRatio;
+	if (!SENSOR_FORMATS[sensorId] || !(aspect > 0)) throw new StudioProtocolError("TARGET_NOT_READY", "The shot camera and filmback must be available.");
+	if (typeof ports.sampleStateAt !== "function") throw new StudioProtocolError("CAPABILITY_MISSING", "This editor cannot sample the export camera at timeline frames.");
+	const sk = skeletonFor(take.rig ?? character.model), last = take.frameCount - 1;
+	const lo = range && range !== "whole_clip" ? Math.max(0, range.startFrame) : 0, hi = range && range !== "whole_clip" ? Math.min(last, range.endFrameExclusive - 1) : last;
+	const frames = exportSampleFrames(lo, hi), shots = scene.shotDocument?.shots ?? [];
+	const tracks = new Map(Object.entries(take.objects ?? {}).map(([id, track]) => [id, { frameCount: take.frameCount, characterId: character.id, ...track }]));
+	const objectIds = takeObjectIds(take.spec, scene.objects), partIndex = Object.fromEntries(Object.entries(PARTS).map(([part, bones]) => [part, bones.map(b => sk.index[b]).filter(i => i !== undefined)]));
+	const shotIds = new Set(), sources = new Set(), body = [], parts = Object.fromEntries(Object.keys(PARTS).map(p => [p, []])), objects = objectIds.map(() => []);
+	for (const frame of frames) {
+		const sampled = ports.sampleStateAt(frame, scene), camera = sampled?.camera ?? scene.camera;
+		if (!camera) throw new StudioProtocolError("TARGET_NOT_READY", "The shot camera must be available.");
+		const shot = shotAtFrame(shots, frame);
+		if (shot) shotIds.add(shot.id);
+		sources.add(shot ? "shot" : "studio");
+		const view = { camera, position: new Vector3(camera.position.x, camera.position.y, camera.position.z), lookAt: new Vector3(camera.lookAt.x, camera.lookAt.y, camera.lookAt.z),
+			fov: focalMmToFov(camera.focalMm, sensorId, aspect), aspect };
+		const joints = jointsAt(sk, take, frame).map(([x, y, z]) => new Vector3(x, y, z));
+		body.push(landing(joints, view));
+		for (const [part, index] of Object.entries(partIndex)) parts[part].push(landing(index.map(i => joints[i]), view));
+		const posed = sceneObjectsAt(scene.objects, frame, { frameCount: take.frameCount, fps: 24, objectTracks: tracks }), state = { ...scene, objects: posed, frame };
+		objectIds.forEach((id, k) => {
+			const object = posed.find(o => o.id === id), bodies = object && (isEmptyObject(object) ? descendantsOf(posed, id).filter(o => !isEmptyObject(o)) : [object]);
+			const points = (bodies ?? []).filter(o => !o.hidden).flatMap(o => bodyPoints(o, state, ports));
+			objects[k].push(points.length ? landing(points, view) : null);
+		});
+	}
+	const spans = (rows, key) => sampleSpans(frames, rows.map(row => !!row?.[key]));
+	const cut = Object.fromEntries(Object.entries(parts).map(([part, rows]) => [part, spans(rows, "cut")]).filter(([, s]) => s.length));
+	const fractions = body.map(row => row.screenFraction);
+	return {
+		coverage: "sampled-export-camera-joints-and-object-outlines",
+		camera: sources.size === 1 ? [...sources][0] : "mixed", shotIds: [...shotIds], sampledFrames: frames,
+		character: { id: character.id, screenFraction: [r2(Math.min(...fractions)), r2(Math.max(...fractions))], inFrame: lowest(body.map(row => row.fraction), frames),
+			...(spans(body, "behind").length ? { behindCamera: spans(body, "behind") } : {}), ...(Object.keys(cut).length ? { cut } : {}) },
+		objects: objectIds.map((id, k) => {
+			const rows = objects[k], out = sampleSpans(frames, rows.map(row => row !== null && row.fraction === 0));
+			const partly = sampleSpans(frames, rows.map(row => row !== null && row.cut && row.fraction !== 0));
+			return { id, name: scene.objects.find(o => o.id === id)?.name ?? id, inFrame: lowest(rows.map(row => row?.fraction ?? null), frames), ...(out.length ? { out } : {}), ...(partly.length ? { cut: partly } : {}) };
+		}),
+	};
+}
+
+/** verify_result motion: result.exportFraming for every subject character with an installed v3 take (one: the row itself). */
+export function exportFramingInto(result, { args, s, receipt, scene, ports }) {
+	const rows = [];
+	for (const id of (args.targets ?? receipt?.affectedIds ?? []).filter(id => s.characters.some(c => c.id === id))) {
+		const take = s.targets.get(id)?.motion, character = s.characters.find(c => c.id === id);
+		if (take?.schema !== TAKE_SCHEMA || !take.rot || !take.hips) continue;
+		// what could not be measured says why in its own row, beside the motion check's reasons
+		try { rows.push(exportFraming({ character, take, scene, ports, range: args.range })); }
+		catch (error) { rows.push({ character: { id }, reason: String(error?.message ?? error) }); }
+	}
+	if (rows.length) result.exportFraming = rows.length === 1 ? rows[0] : rows;
+}

package/src/studio-lighting-check.js

@@ -0,0 +1,103 @@
+// verify_result checks ["lighting"]: how the shot frame is exposed, measured from
+// the pixels the export path renders (the same frame capture_frame and the
+// contact sheets show), not from the light settings. The agent reads the
+// numbers; it does not have to judge darkness from a thumbnail.
+import { PerspectiveCamera, Vector3 } from "three";
+import { StudioProtocolError } from "./studio-agent-protocol.js";
+import { entityWorldBounds } from "./studio-agent-commands.js";
+import { focalMmToFov } from "./shot.js";
+import { normalizeLighting } from "./stage-lighting.js";
+import { readyHdrMap } from "./stage-hdr-map.js";
+
+// Rec. 709 weights on the 8-bit sRGB values: luma as a monitor shows it.
+const lumaOf = (data, i) => 0.2126 * data[i] + 0.7152 * data[i + 1] + 0.0722 * data[i + 2];
+const round = (value, digits) => Number(value.toFixed(digits));
+// A clipped pixel has a channel at full scale; a crushed one is black in every channel.
+const CLIP = 254, CRUSH = 3;
+
+/** Percentile of a 256-bin luma histogram, as 0..1. */
+function percentile(histogram, count, fraction) {
+	let seen = 0;
+	for (let bin = 0; bin < 256; bin++) if ((seen += histogram[bin]) >= fraction * count) return bin / 255;
+	return 1;
+}
+
+/**
+ * Exposure statistics of one RGBA frame (rows bottom-up, as the GPU reads them
+ * back) and of pixel boxes inside it: meanLuma 0..1, clippedPct and crushedPct
+ * of the whole frame; per box its meanLuma and contrast (the spread between
+ * the 5th and 95th luma percentile, 0..1). A box is { id, x0, y0, x1, y1 } in
+ * pixels with y up, or { id } alone when the subject is out of frame.
+ */
+export function frameLighting({ data, width, height }, boxes = []) {
+	let sum = 0, clipped = 0, crushed = 0;
+	for (let i = 0; i < width * height * 4; i += 4) {
+		sum += lumaOf(data, i);
+		const high = Math.max(data[i], data[i + 1], data[i + 2]);
+		if (high >= CLIP) clipped++;
+		else if (high <= CRUSH) crushed++;
+	}
+	const pixels = width * height;
+	const subjects = boxes.map(({ id, x0, y0, x1, y1 }) => {
+		if (x0 === undefined || x1 < x0 || y1 < y0) return { id, meanLuma: null, contrast: null };
+		const histogram = new Uint32Array(256);
+		let total = 0, count = 0;
+		for (let y = y0; y <= y1; y++) for (let x = x0; x <= x1; x++) {
+			const luma = lumaOf(data, (y * width + x) * 4);
+			histogram[Math.min(255, Math.round(luma))]++;
+			total += luma;
+			count++;
+		}
+		return { id, meanLuma: round(total / count / 255, 3), contrast: round(percentile(histogram, count, 0.95) - percentile(histogram, count, 0.05), 3) };
+	});
+	return { meanLuma: round(sum / pixels / 255, 3), clippedPct: round((100 * clipped) / pixels, 1), crushedPct: round((100 * crushed) / pixels, 1), subjects };
+}
+
+/** A world box projected through the shot camera to a clamped pixel box (y up), or null off screen. */
+function pixelBox(bounds, state, width, height) {
+	const { camera, filmback } = state, aspect = width / height;
+	const view = new PerspectiveCamera((focalMmToFov(camera.focalMm, filmback.sensorId, aspect) * 180) / Math.PI, aspect, 0.01, 10000);
+	view.position.set(camera.position.x, camera.position.y, camera.position.z);
+	view.lookAt(camera.lookAt.x, camera.lookAt.y, camera.lookAt.z);
+	view.updateMatrixWorld(true);
+	const forward = new Vector3(camera.lookAt.x - camera.position.x, camera.lookAt.y - camera.position.y, camera.lookAt.z - camera.position.z);
+	const corners = [bounds.min.x, bounds.max.x].flatMap((x) => [bounds.min.y, bounds.max.y].flatMap((y) => [bounds.min.z, bounds.max.z].map((z) => new Vector3(x, y, z))))
+		.filter((corner) => corner.clone().sub(view.position).dot(forward) > 0).map((corner) => corner.project(view));
+	if (!corners.length) return null;
+	const px = (ndc, size) => Math.round(((ndc + 1) / 2) * size);
+	const box = { x0: px(Math.min(...corners.map((c) => c.x)), width), x1: px(Math.max(...corners.map((c) => c.x)), width) - 1,
+		y0: px(Math.min(...corners.map((c) => c.y)), height), y1: px(Math.max(...corners.map((c) => c.y)), height) - 1 };
+	const clamped = { x0: Math.max(0, box.x0), x1: Math.min(width - 1, box.x1), y0: Math.max(0, box.y0), y1: Math.min(height - 1, box.y1) };
+	return clamped.x1 >= clamped.x0 && clamped.y1 >= clamped.y0 ? clamped : null;
+}
+
+/** The lighting check for verify_result: the shot frame at the playhead, its
+ * subjects the target characters (every visible one when no target is a
+ * character). Fails as TARGET_NOT_READY when nothing can be rendered. */
+export function lightingChecks(ids, state, ports) {
+	if (typeof ports.renderFrameBuffer !== "function") throw new StudioProtocolError("CAPABILITY_MISSING", "This editor cannot render the shot frame.");
+	if (!state.camera || !(state.camera.focalMm > 0)) throw new StudioProtocolError("TARGET_NOT_READY", "The shot camera must be available.");
+	const named = state.characters.filter((character) => ids.includes(character.id));
+	const characters = named.length ? named : state.characters.filter((character) => !character.hidden);
+	let image;
+	try { image = ports.renderFrameBuffer(state.frame); }
+	catch (error) { throw new StudioProtocolError("TARGET_NOT_READY", `The shot frame could not be rendered: ${error.message}`); }
+	const boxes = characters.map((character) => {
+		const bounds = entityWorldBounds(character, state, ports);
+		return { id: character.id, ...(bounds && !character.hidden ? pixelBox(bounds, state, image.width, image.height) : {}) };
+	});
+	// What lit the frame beyond the lights: the look, its environment light and its occlusion pass.
+	// An HDR environment is named with whether its map had loaded for this frame (until then the look's sky lit it).
+	const { preset, envLight, ao, hdr, hdrRotation, hdrIntensity, hdrBackground } = normalizeLighting(state.stage?.lighting);
+	return { coverage: "rendered-shot-frame", frame: state.frame, ...frameLighting(image, boxes),
+		look: { preset, envLight, ao, ...(hdr ? { hdr, hdrLoaded: Boolean(readyHdrMap(hdr)), hdrRotation, hdrIntensity, hdrBackground } : {}) } };
+}
+
+/** Puts the lighting check on a verify_result answer, or its reason in unsupportedReasons. */
+export function verifyLighting(result, ids, state, ports) {
+	try { result.checks = { ...result.checks, lighting: lightingChecks(ids, state, ports) }; }
+	catch (error) {
+		if (!(error instanceof StudioProtocolError)) throw error;
+		result.unsupportedReasons.lighting = error.message;
+	}
+}

package/src/studio-motion-visual.js

@@ -0,0 +1,150 @@
+// verify_result's visual: the one image the agent asks to see. "frame" and "plan" are captures;
+// "contact_sheet" tiles frames spread evenly, picked from the installed take's beats
+// (frames: "beats") or named (frames: [f, ...]), seen by the shot camera or by views of its own
+// (views, focus, trail); "trace" plots hand heights and distances of the take over the range (C11).
+// The beats, the views and the trace read one lenient compile of the take's stored spec, as motion.qa does.
+import { StudioProtocolError } from "./studio-agent-protocol.js";
+import { buildContactSheet, paintDots, sampleContactSheetFrames, sheetGrid, viewTileSide } from "./studio-contact-sheet.js";
+import { compileSpec } from "./motion3/pipeline.js";
+import { motionScene } from "./motion3/scene.js";
+import { skeletonFor } from "./motion3/rigs/index.js";
+import { beatFrames, grabReleases, traceSeries, TRACE_COLORS } from "./motion3/beats.js";
+import { depthViews, projectPoint, trailPoints, viewCameras } from "./motion3/views.js";
+import { checkRef } from "./motion3/refs.js";
+import { renderWithGhosts } from "./ghost-set.js";
+import { GHOST_COLORS, sheetGhostSettings } from "./view-ghosts.js";
+import { publishSheet } from "./agent-progress.js";
+import { clampFrames } from "./motion3/lenient.js";
+import { sheetCaption } from "./workflow/agent-progress-view.js";
+// verify_result's lighting check also reads the rendered shot frame; the binding imports it from here.
+export { verifyLighting } from "./studio-lighting-check.js";
+
+const TIMELINE_FPS = 24, TRACE_WIDTH = 960, TRACE_HEIGHT = 360, PAD = 12;
+const rgb = hex => [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16));
+
+/** [first, last] absolute frames of a verify_result range ("whole_clip" or none: the timeline). */
+const rangeOf = (range, frameCount) => range && range !== "whole_clip" ? [range.startFrame, range.endFrameExclusive - 1] : [0, frameCount - 1];
+
+/** The first subject character with a compiled take, compiled again (null when none or it fails). */
+function takeCompile(args, s, receipt) {
+	for (const id of args.targets ?? receipt?.affectedIds ?? []) {
+		const character = s.characters.find(c => c.id === id), take = s.targets.get(id)?.motion;
+		const sk = take?.schema === "cozyclay.take.v3" && take.spec ? skeletonFor(take.rig ?? character?.model) : null;
+		if (!character || !sk) continue;
+		try {
+			return { ...compileSpec({ fps: TIMELINE_FPS, ...take.spec }, { sk, scene: motionScene(s.objects) }, { lenient: true }), characterId: id };
+		} catch { return null; }
+	}
+	return null;
+}
+
+/**
+ * Line series on a dark plot, as RGBA rows bottom-up (WebGL read-back order, what the encodePng
+ * port flips): x is frames lo..hi, y one metre scale for every series. Grey lines mark each second
+ * and every 0.1 m; `marks` are frames drawn as light verticals (beat starts, grab, release).
+ */
+export function traceRgba(series, [lo, hi], { width = TRACE_WIDTH, height = TRACE_HEIGHT, marks = [] } = {}) {
+	const data = new Uint8Array(width * height * 4);
+	const put = (x, y, [r, g, b]) => {
+		if (x < 0 || y < 0 || x >= width || y >= height) return;
+		const i = (y * width + x) * 4; data[i] = r; data[i + 1] = g; data[i + 2] = b; data[i + 3] = 255;
+	};
+	for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) put(x, y, [22, 24, 29]);
+	let bottom = Math.min(...series.map(s => s.min)), top = Math.max(...series.map(s => s.max));
+	if (!(top > bottom)) { bottom = (Number.isFinite(bottom) ? bottom : 0) - 0.05; top = bottom + 0.1; }
+	const X = f => Math.round(PAD + ((f - lo) / Math.max(1, hi - lo)) * (width - 2 * PAD));
+	const Y = v => Math.round(PAD + ((v - bottom) / (top - bottom)) * (height - 2 * PAD));
+	for (let m = Math.ceil(bottom * 10); m <= top * 10; m++) for (let x = PAD; x < width - PAD; x++) put(x, Y(m / 10), m === 0 ? [90, 94, 104] : [44, 47, 55]);
+	for (let f = Math.ceil(lo / TIMELINE_FPS) * TIMELINE_FPS; f <= hi; f += TIMELINE_FPS) for (let y = PAD; y < height - PAD; y++) put(X(f), y, [44, 47, 55]);
+	for (const f of marks) if (f >= lo && f <= hi) for (let y = PAD; y < height - PAD; y++) put(X(f), y, [150, 154, 164]);
+	for (const s of series) {
+		const color = rgb(s.color);
+		for (let i = 1; i < s.values.length; i++) {
+			const a = s.values[i - 1], b = s.values[i];
+			if (a === null || b === null) continue;
+			const x0 = X(lo + i - 1), y0 = Y(a), x1 = X(lo + i), y1 = Y(b), n = Math.max(1, Math.abs(x1 - x0), Math.abs(y1 - y0));
+			for (let k = 0; k <= n; k++) {
+				const x = Math.round(x0 + ((x1 - x0) * k) / n), y = Math.round(y0 + ((y1 - y0) * k) / n);
+				put(x, y, color); put(x + 1, y, color); put(x, y + 1, color); put(x + 1, y + 1, color);
+			}
+		}
+	}
+	return { data, width, height };
+}
+
+const listOf = value => value === undefined ? [] : [value].flat();
+const round2 = p => p.map(v => Math.round(v * 100) / 100);
+
+/**
+ * A contact sheet from views of its own (motion3/views.js), a row per view, never the shot
+ * camera: each view is placed once for every frame, framed on args.focus (default the whole
+ * character) and the trails. A trail is a dot per frame of its ref over the range, so spacing is
+ * speed: frames up to the tile's frame solid, later ones faint, the tile's frame ringed. With
+ * args.ghosts every tile also draws the take's poses around its frame (ghost-set.js). args.views
+ * are the rendered ones (depthViews); `added` names the view added to them and why.
+ */
+function viewSheet(args, r, { s, frames, span, grid, picks, ports, added }) {
+	if (!r) throw new StudioProtocolError("TARGET_NOT_READY", "views frame a character's compiled take; name a character that has one (run motion.compile first).");
+	const focus = listOf(args.focus), refs = listOf(args.trail), ctx = { sk: r.out.ctx.sk, scene: r.out.ctx.scene };
+	for (const [field, list] of [["focus", focus], ["trail", refs]]) list.forEach((ref, i) => checkRef(r.expanded, message => { throw new StudioProtocolError("INVALID_ARGUMENT", message); }, ctx, `${field}[${i}]`, ref));
+	const trails = refs.map((ref, i) => ({ ref, color: TRACE_COLORS[i], points: trailPoints(r.out, ref, span) }));
+	const side = viewTileSide(grid), cameras = viewCameras(r.out, { views: args.views, frames, focus, trails });
+	if (!cameras.length) throw new StudioProtocolError("TARGET_NOT_READY", "views found no compiled frame of the take in the range.");
+	const cells = cameras.flatMap(cam => frames.map(frame => ({ cam, frame }))), target = args.ghosts ? s.targets.get(r.characterId) : null;
+	if (args.ghosts && !target?.rig) throw new StudioProtocolError("TARGET_NOT_READY", "ghosts pose a copy of the character's rig; it has not loaded in the editor yet.");
+	const sheet = buildContactSheet(cells, ({ cam, frame }) => {
+		const render = () => ports.renderFrameBuffer(frame, { eye: cam.eye, quaternion: cam.quaternion, fovDeg: cam.fovDeg, output: { width: side, height: side } });
+		const tile = target ? renderWithGhosts({ rig: target.rig, take: target.motion, objects: s.objects }, frame, render) : render();
+		const dots = trails.flatMap(t => t.points.map(({ f, p }) => [f, projectPoint(cam, p, tile.width, tile.height), rgb(t.color)])
+			.filter(([, q]) => q).map(([f, [x, y], color]) => ({ x, y, color, r: f === frame ? 4 : 1.5, alpha: f <= frame ? 1 : 0.35, ring: f === frame })));
+		return { ...tile, data: paintDots(tile.data, tile.width, tile.height, dots) };
+	}, grid);
+	const views = cameras.map(cam => ({ name: cam.name, eye: round2(cam.eye), target: round2(cam.target) }));
+	const ref = { frames, layout: grid.layout, views, ...(added ? { addedView: added } : {}), focus: focus.length ? focus : "character", ...(trails.length ? { trails: trails.map(({ ref: of, color }) => ({ ref: of, color })) } : {}), ...(picks ? { picks } : {}),
+		...(target ? { ghosts: { ...sheetGhostSettings(), ...GHOST_COLORS } } : {}) };
+	return [{ dataUrl: ports.encodePng(sheet.data, sheet), width: sheet.width, height: sheet.height, frames, layout: grid.layout, views: views.map(v => v.name) }, ref];
+}
+
+/** Answers args.visual into result.visualRefs and keeps the image for resolve_studio_image. */
+export function studioVisual(args, { s, receipt, result, images, ports }) {
+	const keep = (image, ref) => {
+		const imageId = crypto.randomUUID();
+		images.set(imageId, { ...image, revision: s.revision, receiptId: result.receiptId });
+		result.visualRefs.push({ imageId, ...ref });
+		// the user sees what the agent looked at (agent-progress.js: the agent panel's progress card)
+		const kind = image.kind ?? (args.visual === "contact_sheet" ? "contact sheet" : args.visual);
+		publishSheet({ characterId: args.targets?.[0] ?? receipt?.affectedIds?.[0] ?? null, dataUrl: image.dataUrl, width: image.width, height: image.height,
+			caption: sheetCaption({ kind, views: image.views ?? [], frames: image.frames ?? [] }), frames: image.frames ?? [] });
+	};
+	if (args.visual !== "contact_sheet" && (args.views || args.focus || args.trail)) throw new StudioProtocolError("INVALID_ARGUMENT", 'views, focus and trail shape a contact sheet; send visual: "contact_sheet".');
+	if (args.ghosts && (args.visual !== "contact_sheet" || !args.views)) throw new StudioProtocolError("INVALID_ARGUMENT", 'ghosts are drawn on a contact sheet from views of its own; send visual: "contact_sheet" with views, e.g. ["side"].');
+	if (!args.views && (args.focus || args.trail)) throw new StudioProtocolError("INVALID_ARGUMENT", 'focus and trail are drawn by views of its own; add views, e.g. ["front", "side"] (the shot camera stays the user\'s).');
+	if (args.visual === "contact_sheet") {
+		// One image of frames across the range, each rendered through the export
+		// path, which puts the playhead pose, shot camera and props back.
+		const span = rangeOf(args.range, s.frameCount), r = args.frames === "beats" || args.views ? takeCompile(args, s, receipt) : null;
+		let frames = sampleContactSheetFrames(args.range, s.frameCount), picks, adjusted;
+		// named frames past the range are drawn at its nearest end, and visualRefs[0].adjusted says so (lenient.js)
+		if (Array.isArray(args.frames)) ({ frames, adjusted } = clampFrames(args.frames, span));
+		else if (args.frames === "beats") ({ frames, picks } = beatFrames({ range: span, even: frames, timeline: r?.timeline, groups: r?.qa.groups, objects: r?.expanded.objects }));
+		// Views of its own always include two that look across each other (motion3/views.js depthViews).
+		const depth = args.views ? depthViews(args.views) : null, grid = sheetGrid(frames.length, depth?.views.length ?? 0);
+		const said = ref => (adjusted ? { ...ref, adjusted } : ref);
+		if (depth) { const [image, ref] = viewSheet({ ...args, views: depth.views }, r, { s, frames, span, grid, picks, ports, added: depth.added }); return keep(image, said(ref)); }
+		const sheet = buildContactSheet(frames, ports.renderFrameBuffer, grid);
+		return keep({ dataUrl: ports.encodePng(sheet.data, sheet), width: sheet.width, height: sheet.height, frames, layout: grid.layout }, said({ frames, layout: grid.layout, ...(picks ? { picks } : {}) }));
+	}
+	if (args.visual === "trace") {
+		const r = takeCompile(args, s, receipt);
+		if (!r) throw new StudioProtocolError("TARGET_NOT_READY", "visual trace plots a character's compiled take; name a character that has one (run motion.compile first).");
+		const { range, series } = traceSeries(r.out, r.expanded, rangeOf(args.range, s.frameCount));
+		const marks = [...(r.timeline ?? []).map(entry => entry.f?.[0]), ...grabReleases(r.timeline, r.expanded.objects).map(row => row.f)];
+		const plot = traceRgba(series, range, { marks });
+		return keep({ dataUrl: ports.encodePng(plot.data, plot), width: plot.width, height: plot.height, kind: "trace" },
+			{ kind: "trace", range, series: series.map(({ values, ...summary }) => summary) });
+	}
+	// A frame is the shot camera's view; a plan is the Top View, the set from above
+	// with names and the shot camera's wedge.
+	const capture = args.visual === "plan" ? (ports.capturePlan ?? (() => { throw new StudioProtocolError("CAPABILITY_MISSING", "This editor cannot render the top view."); }))() : ports.capture();
+	keep(capture, args.visual === "plan" ? { kind: "plan" } : {});
+}

package/src/studio-schema-errors.js

@@ -0,0 +1,80 @@
+// The refusal texts of validateStudioSchema (studio-agent-protocol.js). Every text starts with the
+// path ("$.args.topic") and says what the schema allows there: the allowed values, the allowed
+// fields, the expected type or bounds. What arrived is named by its kind ("got a string"), or by
+// a short preview of a scalar (at most 40 characters), never as a whole payload such as an image.
+// Shared by the browser and the sidecar: no imports.
+const LIST_MAX = 24, PREVIEW_MAX = 40;
+
+const preview = value => {
+	const text = JSON.stringify(value) ?? String(value);
+	return text.length > PREVIEW_MAX ? `${text.slice(0, PREVIEW_MAX - 3)}...` : text;
+};
+const kindOf = value => (value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object"
+	: typeof value === "number" && !Number.isFinite(value) ? String(value) : `a ${typeof value}`);
+/** A list of names, cut after LIST_MAX with how many there are in all. */
+const listOf = values => (values.length > LIST_MAX ? `${values.slice(0, LIST_MAX).join(", ")}, ... (${values.length} in all)` : values.join(", "));
+const typeName = schema => (Object.hasOwn(schema, "const") ? JSON.stringify(schema.const) : schema.type === "integer" ? "an integer"
+	: schema.type === "array" ? `an array${schema.items?.type ? ` of ${schema.items.type}s` : ""}`
+		: schema.type === "object" ? "an object" : schema.type === "null" ? "null" : `a ${schema.type}`);
+
+/** Wrong type, or a constant that differs: what the schema wants and what arrived. */
+export const wrongType = (path, schema, value) => `${path}: expected ${typeName(schema)}, got ${Object.hasOwn(schema, "const") ? preview(value) : kindOf(value)}.`;
+
+export const unknownField = (path, schema, key) => {
+	const allowed = Object.keys(schema.properties);
+	return `${path} has unknown field ${preview(key)}; ${allowed.length ? `allowed: ${listOf(allowed)}` : "it takes no fields"}.`;
+};
+
+export const missingField = (path, key) => `${path}: missing required field "${key}".`;
+
+/** An array of the wrong type or length. */
+export function arrayRefusal(path, schema, value) {
+	if (!Array.isArray(value)) return wrongType(path, schema, value);
+	const lo = schema.minItems ?? 0, hi = schema.maxItems ?? Infinity;
+	const want = lo === hi ? `exactly ${lo}` : hi === Infinity ? `at least ${lo}` : lo === 0 ? `at most ${hi}` : `${lo} to ${hi}`;
+	return `${path}: expected ${want} item${lo === hi && lo === 1 ? "" : "s"}, got ${value.length}.`;
+}
+
+export const duplicateItem = (path, items) => {
+	const seen = new Set(), twice = items.map(item => JSON.stringify(item)).find(text => (seen.has(text) ? true : (seen.add(text), false)));
+	return `${path}: items must be unique; ${twice && twice.length <= PREVIEW_MAX ? twice : "one item"} appears twice.`;
+};
+
+/** A string of the wrong type, empty, too long, or off its pattern. */
+export function stringRefusal(path, schema, value) {
+	if (typeof value !== "string") return wrongType(path, schema, value);
+	if (!value.trim()) return `${path}: must not be empty.`;
+	const length = [...value].length;
+	if (schema.maxLength !== undefined && length > schema.maxLength) return schema.description ? `${path}: over ${schema.maxLength} characters. ${schema.description}` : `${path}: at most ${schema.maxLength} characters, got ${length}.`;
+	return `${path}: ${preview(value)} does not match ${schema.pattern}.`;
+}
+
+export const enumRefusal = (path, schema, value) => `${path}: ${preview(value)} is not one of: ${listOf(schema.enum)}.`;
+
+/** A number of the wrong type, not an integer, or not above an exclusive minimum. */
+export function numberRefusal(path, schema, value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return wrongType(path, schema, value);
+	if (schema.type === "integer" && !Number.isSafeInteger(value)) return `${path}: expected an integer, got ${value}.`;
+	return `${path}: must be greater than ${schema.exclusiveMinimum}, got ${value}.`;
+}
+
+const isPlain = schema => ((schema.oneOf ?? schema.anyOf) ? (schema.oneOf ?? schema.anyOf).every(isPlain) : schema.type !== "object" && schema.type !== "array");
+const bounded = schema => [schema.minimum, schema.maximum].some(bound => bound !== undefined) ? ` within [${[schema.minimum ?? "-inf", schema.maximum ?? "inf"].join(", ")}]` : "";
+/** Each value or type a schema admits, in words: true, false, "ifClean", an integer within [1, 8]. */
+const formsOf = schema => ((schema.oneOf ?? schema.anyOf) ? (schema.oneOf ?? schema.anyOf).flatMap(formsOf)
+	: Object.hasOwn(schema, "const") ? [JSON.stringify(schema.const)] : schema.enum ? schema.enum.map(v => JSON.stringify(v))
+		: schema.type === "boolean" ? ["true", "false"] : [`${typeName(schema)}${schema.type === "number" || schema.type === "integer" ? bounded(schema) : ""}`]);
+
+/**
+ * A union no branch matched, when every branch failed at the union's own path and the branches are
+ * plain values (or the value is not an object): `$.args.install must be true, false or "ifClean",
+ * got "yes".` Otherwise null, and the caller surfaces the deepest branch failure.
+ */
+export function unionRefusal(path, failures, value) {
+	if (!failures.every(({ error }) => error.details?.path === path)) return null;
+	if (value !== null && typeof value === "object" && !failures.every(({ branch }) => isPlain(branch))) return null;
+	const forms = [...new Set(failures.flatMap(({ branch }) => formsOf(branch)))];
+	const shown = forms.length > LIST_MAX ? [...forms.slice(0, LIST_MAX), `... (${forms.length} in all)`] : forms;
+	const words = shown.length > 1 ? `${shown.slice(0, -1).join(", ")} or ${shown.at(-1)}` : shown[0];
+	return `${path} must be ${words}, got ${value !== null && typeof value === "object" ? kindOf(value) : preview(value)}.`;
+}