cozyclay 2.1.0 → 3.0.0

package/src/studio-agent-motion.js

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

package/src/studio-agent-protocol.js

@@ -1,5 +1,8 @@
 // Shared by the browser and sidecar. No Node, React, renderer or provider imports.
 import { STUDIO_ELEMENTS, isSettableElement } from "./studio-elements.js";
+import { STUDIO_ERROR_CODES } from "./studio-error-codes.js";
+import { EFFECT_VALUE_SCHEMA } from "./effects/effect-record.js";
+import { wrongType, unknownField, missingField, arrayRefusal, duplicateItem, stringRefusal, enumRefusal, numberRefusal, unionRefusal } from "./studio-schema-errors.js";
 // Mirrors PREVIS_MODES (project.js) and POSTURES (scenes.js). Neither is imported:
 // both pull in three.js, which the agent sidecar must not load. The protocol test pins the lists to their owners.
 const PREVIS_MODES = ["storyboard", "animation"], POSTURES = ["stand", "sit", "lie"];
@@ -10,7 +13,7 @@ export const STUDIO_PROTOCOL_VERSION = "studio-agent-v1";
 export const STUDIO_CONTEXT_MAX_BYTES = 64 * 1024;
 export const STUDIO_CONTEXT_LIMITS = Object.freeze({ entities: 24, entityIndex: 400, shots: 8, assets: 48, recentReceipts: 3, jobs: 8 });
 export const STUDIO_TOOL_FAMILIES = Object.freeze(["inspect_studio", "run_action", "verify_result"]);
-export const STUDIO_TOOL_ALIASES = Object.freeze(["operate_studio", "arrange_objects", "arrange_characters", "patch_elements", "frame_shot", "generate_motion", "undo_edit"]);
+export const STUDIO_TOOL_ALIASES = Object.freeze(["operate_studio", "arrange_objects", "arrange_characters", "patch_elements", "frame_shot", "undo_edit"]);
 export const STUDIO_TOOL_LABELS = Object.freeze({
 	inspect_studio: "Read the scene",
 	operate_studio: "Selection and view",
@@ -18,7 +21,6 @@ export const STUDIO_TOOL_LABELS = Object.freeze({
 	arrange_characters: "Arrange characters",
 	patch_elements: "Edit properties",
 	frame_shot: "Frame the shot",
-	generate_motion: "Generate motion",
 	verify_result: "Verify the result",
 	undo_edit: "Undo an edit",
 	run_action: "Run an editor action",
@@ -28,12 +30,7 @@ export const STUDIO_TOOLS = Object.freeze(Object.keys(STUDIO_TOOL_LABELS));
  * object→objects, shot→shot, stage→stage. */
 export const STUDIO_PATCH_KINDS = Object.freeze(["character", "object", "shot", "stage"]);
 export const STUDIO_PATCH_DOMAINS = Object.freeze({ character: "cast", object: "objects", shot: "shot", stage: "stage" });
-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",
-]);
+export { STUDIO_ERROR_CODES };
 export const STUDIO_VARIANTS = freezeStudioData({
 	selectionKinds: ["scene", "object", "character", "rig", "camera"], modes: ["scene", "pose", "camera", "motion"], shotModes: ["keys", "follow", "rail"],
 	framingSizes: ["extreme close-up", "close-up", "medium close-up", "medium shot", "medium-wide shot", "wide shot", "extreme wide shot"],
@@ -60,8 +57,7 @@ const record = value => value !== null && typeof value === "object" && !Array.is
 const text = (maxLength = 120) => ({ type: "string", minLength: 1, maxLength });
 const number = (minimum, maximum) => ({ type: "number", ...(minimum !== undefined ? { minimum } : {}), ...(maximum !== undefined ? { maximum } : {}) });
 const integer = (minimum = 0, maximum = Number.MAX_SAFE_INTEGER) => ({ ...number(minimum, maximum), type: "integer" });
-const bool = { type: "boolean" };
-const literal = value => ({ const: value });
+const bool = { type: "boolean" }, literal = value => ({ const: value });
 const choices = values => ({ type: "string", enum: values });
 const nullable = schema => ({ oneOf: [schema, { type: "null" }] });
 const array = (items, maxItems, minItems = 0, uniqueItems = false) => ({ type: "array", items, minItems, maxItems, ...(uniqueItems ? { uniqueItems } : {}) });
@@ -114,9 +110,6 @@ const characterOp = union(
 	object({ op: literal("update"), characterId: id }, { position, facing, scale: positive, name, hidden: bool }),
 	object({ op: literal("remove"), characterId: id }),
 );
-export const BEAT_TEXT_MAX = 500;
-const generateSource = object({ kind: literal("generate"), beats: array(object({ text: { ...text(BEAT_TEXT_MAX), description: 'An English description of the body movement starting with "A person". The editor refuses prompts over 500 characters.' } }, { seconds: number(0.5, 60) }), 8, 1) }, { durationSeconds: number(2, 60), seed: integer(-2147483648, 2147483647) });
-const source = union(generateSource, object({ kind: literal("reuse"), artifactId: id }));
 
 /* ----------------------------------------------- element patches ----
  * The accepted fields of `patch_elements` are DERIVED from the element
@@ -126,18 +119,20 @@ const source = union(generateSource, object({ kind: literal("reuse"), artifactId
  * (schedules, routes, pictures) declare their shape here, because the table
  * records what an element IS, not how JSON carries it. */
 const dataImage = { ...text(2 * 1024 * 1024), pattern: "^data:image/[A-Za-z0-9.+-]+[;,]" };
-const promptBlock = object({ startFrame: integer(), endFrame: integer(1), text: text(2000) }, { id });
+
 const cameraKey = object({ frame: integer(), framing: object({ pos: vec3, yaw: number(), pitch: number(), fovDeg: number(1, 179) }) }, { id });
 // A mark is an arc fraction, or { t, bank, pitch } when the object should lean
 // there (degrees, +-90). The route normaliser (src/object-path.js) owns the
 // rules; this only carries the shape through untouched.
 const routeMark = union(number(0, 1), object({ t: number(0, 1) }, { bank: number(-90, 90), pitch: number(-90, 90) }));
 const objectRoute = nullable(object({ points: array(vec3, 64, 2) }, { speed: number(0, 50), faceTravel: bool, loop: bool, extend: bool, marks: array(routeMark, 6) }));
+// A practical light and a glow (src/object-look.js owns the defaults and the repair).
+const objectLight = object({}, { type: choices(["point", "spot"]), color: { ...text(32), pattern: "^#[0-9a-fA-F]{6}$" }, intensity: number(0, 1000), range: number(0, 100), angle: number(1, 89), softness: number(0, 1), shadow: bool, flicker: number(0, 1), aim: nullable(vec3) });
+const objectGlow = nullable(object({}, { color: { ...text(32), pattern: "^#[0-9a-fA-F]{6}$" }, intensity: number(0, 20), halo: number(0, 4) }));
 const PATCH_VALUE_SCHEMAS = {
-	"character.pose": nullable(id), "character.identityImage": nullable(dataImage), "character.promptBlocks": array(promptBlock, 64),
+	"character.pose": nullable(id), "character.identityImage": nullable(dataImage), "object.light": objectLight, "object.glow": objectGlow, "object.effect": EFFECT_VALUE_SCHEMA,
 	"object.parent": nullable(id), "object.path": objectRoute, "stage.environmentImage": nullable(dataImage),
-	"shot.cameraKeys": array(cameraKey, 64), "shot.targetModel": nullable(id),
-};
+	"shot.cameraKeys": array(cameraKey, 64), "shot.targetModel": nullable(id) };
 /** One declared element as a JSON value schema, or null when the declaration
  * carries no carriable shape (a structured element without a declared value
  * schema above). Null elements are omitted from the patch schema, and
@@ -204,8 +199,7 @@ const toolSchemas = {
 	arrange_characters: object({ ops: array(characterOp, 8, 1) }),
 	patch_elements: object({ ops: array(patchOp, 32, 1) }),
 	frame_shot: object({ subjectIds: ids(1), framing }, { shotId: id, caption: { type: "string", maxLength: 500 }, keyAtFrame: integer() }),
-	generate_motion: object({ characterId: id, source }, { repair: { ...choices(["bounded", "none"]), default: "bounded" } }),
-	verify_result: object({ checks: array(choices(["placement", "framing", "motion"]), 3, 1, true) }, { receiptId: id, targets: ids(), range: union(literal("whole_clip"), range), visual: { ...choices(["none", "frame", "contact_sheet", "plan"]), default: "none" } }),
+	verify_result: object({ checks: { ...array(choices(["placement", "framing", "motion", "lighting"]), 4, 1, true), description: "lighting measures the shot frame rendered at the playhead: checks.lighting { meanLuma 0..1, clippedPct (a channel at full scale), crushedPct (pure black), subjects: [{ id, meanLuma, contrast (5th to 95th percentile luma spread, 0..1) }] inside each target character's projected box, look: { preset, envLight, ao } the stage look's environment light and occlusion strength }. motion also answers exportFraming (one per character with a take): what the camera the export renders shows of the take over sampledFrames: camera (shot where a shot covers the frame, studio = the Studio camera as it stands when none does; shotIds), character { screenFraction [min, max] of the frame height, inFrame [lowest share of its joints' screen box inside the frame, frame], behindCamera, cut { head, hand_l, hand_r, foot_l, foot_r } }, and every object the take names { id, name, inFrame, out, cut }; out, cut and behindCamera are spans [first, last] of sampled frames; { character: { id }, reason } when it cannot be measured" } }, { receiptId: id, targets: ids(), range: union(literal("whole_clip"), range), visual: { ...choices(["none", "frame", "contact_sheet", "plan", "trace"]), default: "none" }, frames: { ...union(choices(["even", "beats"]), array(integer(), 8, 1, true)), default: "even", description: "contact_sheet frames: even spacing, beats (grab/release, beat starts, the worst QA frames, then even fill, answered in visualRefs[0].picks), or up to 8 timeline frames of your choice" }, views: { ...array(choices(["front", "side", "three-quarter", "top"]), 2, 1, true), description: "contact_sheet from cameras of its own around the character instead of the shot camera (which stays as it is): a row per view, each held still over the frames and framed on focus, so small actions fill the tile; side and three-quarter look from the focus's side; a sheet always holds two views at least 60 degrees apart: if the asked ones look along nearly one line, side, front or top is added and named in visualRefs[0].addedView" }, focus: { ...union(text(120), array(text(120), 3, 1, true)), description: "with views: what to frame, as refs (object:<id>, joint:<Bone>, prop:<prop>.<point>, landmark:mouth); default the whole character" }, trail: { ...union(text(120), array(text(120), 3, 1, true)), description: "with views: refs whose path over the range is drawn as one dot per frame (spacing shows speed; later frames faint, the tile's own frame ringed), colours in visualRefs[0].trails" }, ghosts: { ...bool, description: "with views: each tile also shows the first target's poses around its frame as translucent ghosts (onion skin), earlier ones blue, later ones orange, carried props included, so spacing and arcs read in one tile; how many and how far apart is view.setGhosts (while it is off: 3 each side, every 4 frames), answered in visualRefs[0].ghosts" } }),
 	undo_edit: object({ receiptId: id }),
 	run_action: object({ action: id }, { args: openObject, confirmationToken: id }),
 };
@@ -219,7 +213,7 @@ const entity = object({ id, kind: choices(["object", "character", "rig"]), token
 	name, detailsOmitted: bool, position: vec3, yawDeg: number(), rotationDeg: vec3, scale: union(positive, positiveVec3), bounds: nullable(bounds),
 	libraryKind: id, renderer: id, color: nullable(text(32)), tint: nullable(text(32)), modelId: nullable(text(120)), assetId: id, parentId: nullable(id), attachment: nullable(object({ characterId: id, bone: nullable(id) })), pathPointCount: integer(0, 64), pathMarks: array(union(number(0, 1), object({ t: number(0, 1) }, { bank: number(-90, 90), pitch: number(-90, 90) })), 6),
 	local: object({ position: vec3, rotationDeg: vec3 }),
-	motion: object({ takeId: nullable(id), frames: integer(), ikKeyCount: integer(), promptBlockCount: integer() }, { poseId: nullable(id), keyIds: ids(8, 0) }),
+	motion: object({ takeId: nullable(id), frames: integer(), ikKeyCount: integer() }, { poseId: nullable(id), keyIds: ids(8, 0) }),
 	capabilities: object({ rigReady: bool, ik: bool, measuredFeet: bool }),
 	// `kind` above already names the entity class ("character"); a character's own
 	// kind is `characterKind`: a rigged model, or a rig-free capsule figure.
@@ -277,7 +271,7 @@ const readback = object({}, { position: vec3, yawDeg: number(), rotationDeg: vec
 const CAMERA_SIDES = ["left", "right", "on-axis"];
 const checks = object({ coverage: name }, { relationSatisfied: bool, overlapIds: ids(100, 0), actualGapM: number(), requestedGapM: number(0), maximumFootprintOverlapM: number(0),
 	basis: choices(STUDIO_VARIANTS.positionBases), clipped: bool, occluded: bool, behindCamera: bool, screenFraction: number(0), derivedSize: choices(STUDIO_VARIANTS.framingSizes), support: name, baseY: number(), facesTargetId: id,
-	cameraSide: choices(CAMERA_SIDES), axisConsistent: bool });
+	cameraSide: choices(CAMERA_SIDES), axisConsistent: bool, evaluatedFrames: integer(1), sampledFrames: array(integer(), 64, 1), sampledChecks: array(object({ frame: integer(), screenFraction: number(), clipped: bool, behindCamera: bool, occluded: bool }), 64, 1), issueFrames: array(object({ frame: integer(), codes: array(name, 4, 1), screenFraction: number() }), 64, 0) });
 // Code-computed shot geometry verify_result carries beside a framing check
 // (src/studio-geometry-facts.js): bounded to 8 shots and 24 subjects.
 const geometryFacts = object({
@@ -298,7 +292,9 @@ const authoredReceipt = { ...receiptBase, authored: literal(true), undo };
 // A run_action receipt names the registered action and what it did.
 const actionFields = { action: id, summary: text(240) };
 const receiptVariants = {
-	completed: object({ ...receiptBase, status: literal("completed"), kind: choices(["job", "document", "transaction", "mutation"]) }, { ...actionFields, ...batchDetails, output: openObject, jobId: id, txId: id, nextHost: identity }),
+	// A mutation inside an agent turn answers "completed" (the turn owns its undo entry); a patch
+	// among them still reports each op, so ops ride here too.
+	completed: object({ ...receiptBase, status: literal("completed"), kind: choices(["job", "document", "transaction", "mutation"]) }, { ...actionFields, ...batchDetails, output: openObject, jobId: id, txId: id, nextHost: identity, ops: opResults }),
 	started: object({ ...receiptBase, status: literal("started"), kind: literal("job"), jobId: id, authored: literal(false), undo: literal(null) }, { ...actionFields }),
 	applied: object({ ...authoredReceipt, status: literal("applied") }, { mutated: literal(true), ops: opResults, ...batchDetails, ...actionFields }),
 	partial: object({ ...authoredReceipt, status: literal("partial"), ops: opResults }, { mutated: literal(true), ...batchDetails }),
@@ -321,65 +317,66 @@ const failureSchema = object({ ok: literal(false), commandId: id, host: identity
 // These are JSON Schema data, not validators with hidden browser dependencies.
 // x-studio-range is the sole relational schema annotation: end > start.
 export const StudioSchemas = freezeStudioData({ catalogue: STUDIO_CATALOGUE, variants: STUDIO_VARIANTS, Vec3: vec3, FrameRange: range, PositionSpec: position, FacingSpec: facing,
-	ObjectOp: objectOp, CharacterOp: characterOp, Framing: framing, GenerateSource: generateSource, Source: source, Identity: identity, Host: host, TargetGuard: guardSchema,
+	ObjectOp: objectOp, CharacterOp: characterOp, Framing: framing, Identity: identity, Host: host, TargetGuard: guardSchema,
 	Entity: entity, ShotSummary: shotSummary, StudioContextV1: contextSchema, StudioTurn: turnSchema, StudioStop: stopSchema, Receipt: receiptSchema, ReceiptVariants: receiptVariants, Failure: failureSchema, GeometryFacts: geometryFacts });
 
-/** Validate the closed JSON Schema subset used above; return a detached value
- * with declared defaults. Errors contain schema paths, never payload values. */
+/** Validate the closed JSON Schema subset used above; return a detached value with declared
+ * defaults. Errors name the path and what it allows (studio-schema-errors.js). */
 export function validateStudioSchema(schema, value, code = "INVALID_ARGUMENT", path = "$") {
-	if (schema.oneOf) {
-		const matches = [];
-		const failures = [];
-		for (const branch of schema.oneOf) {
+	if (schema.oneOf || schema.anyOf) {
+		const matches = [], failures = [];
+		for (const branch of schema.oneOf ?? schema.anyOf) {
 			try { matches.push(validateStudioSchema(branch, value, code, path)); }
 			catch (error) { if (!(error instanceof StudioProtocolError)) throw error; failures.push({ branch, error }); }
 		}
 		// No variant matched: the generic "one of N" message hides which path and
 		// bound actually offended. Surface the failure from the variant the input
 		// discriminates to (matching target.kind), or else the deepest failing
-		// path, instead of the union's own shallow message.
+		// path, instead of the union's own shallow message. A union of plain values
+		// (true, false or "ifClean") that failed at its own path names every form.
 		if (matches.length === 0 && failures.length) {
-			const kind = record(value) && record(value.target) ? value.target.kind : undefined;
-			const discriminated = kind !== undefined && failures.find(({ branch }) => branch.properties?.target?.properties?.kind?.const === kind);
+			const kind = record(value) && record(value.target) ? value.target.kind : undefined, discriminated = kind !== undefined && failures.find(({ branch }) => branch.properties?.target?.properties?.kind?.const === kind);
+			const forms = !discriminated && unionRefusal(path, failures, value);
+			if (forms) fail(code, forms, path);
 			const chosen = discriminated || failures.reduce((best, next) => next.error.details.path.length > best.error.details.path.length ? next : best);
 			throw chosen.error;
 		}
-		if (matches.length !== 1) fail(code, "Expected exactly one supported variant.", path);
+		if (matches.length !== 1 && schema.oneOf) fail(code, `${path}: matches ${matches.length} variants; send the fields of exactly one.`, path);
 		return matches[0];
 	}
-	if (Object.hasOwn(schema, "const")) { if (value !== schema.const) fail(code, "Invalid constant.", path); return value; }
-	if (schema.type === "null") { if (value !== null) fail(code, "Expected null.", path); return null; }
+	if (Object.hasOwn(schema, "const")) { if (value !== schema.const) fail(code, wrongType(path, schema, value), path); return value; }
+	if (schema.type === "null") { if (value !== null) fail(code, wrongType(path, schema, value), path); return null; }
 	if (schema.type === "object") {
-		if (!record(value)) fail(code, "Expected object.", path);
+		if (!record(value)) fail(code, wrongType(path, schema, value), path);
 		const open = schema.additionalProperties === true;
-		for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key) && !open) fail(code, "Unexpected field.", path);
+		for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key) && !open) fail(code, unknownField(path, schema, key), path);
 		const result = {};
 		if (open) for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key)) result[key] = structuredClone(value[key]);
 		for (const [key, child] of Object.entries(schema.properties)) {
 			if (Object.hasOwn(value, key)) result[key] = validateStudioSchema(child, value[key], code, `${path}.${key}`);
-			else if (schema.required.includes(key)) fail(code, "Required field missing.", `${path}.${key}`);
+			else if (schema.required.includes(key)) fail(code, missingField(path, key), `${path}.${key}`);
 			else if (Object.hasOwn(child, "default")) result[key] = structuredClone(child.default);
 		}
 		if (schema["x-studio-range"] && result.endFrameExclusive <= result.startFrame) fail(code, "Frame range must be nonempty and half-open.", path);
 		return result;
 	}
 	if (schema.type === "array") {
-		if (!Array.isArray(value) || value.length < schema.minItems || value.length > schema.maxItems) fail(code, "Array outside supported bounds.", path);
+		if (!Array.isArray(value) || value.length < schema.minItems || value.length > schema.maxItems) fail(code, arrayRefusal(path, schema, value), path);
 		const result = value.map((item, i) => validateStudioSchema(schema.items, item, code, `${path}[${i}]`));
-		if (schema.uniqueItems && new Set(result.map(item => JSON.stringify(item))).size !== result.length) fail(code, "Duplicate array member.", path);
+		if (schema.uniqueItems && new Set(result.map(item => JSON.stringify(item))).size !== result.length) fail(code, duplicateItem(path, result), path);
 		return result;
 	}
 	if (schema.type === "string") {
-		if (typeof value !== "string" || !value.trim() || (schema.maxLength !== undefined && [...value].length > schema.maxLength) || (schema.pattern && !new RegExp(schema.pattern).test(value))) fail(code, typeof value === "string" && schema.description && [...value].length > schema.maxLength ? `Over ${schema.maxLength} characters. ${schema.description}` : "Invalid or oversized string.", path);
-		if (schema.enum && !schema.enum.includes(value)) fail(code, "Unsupported enum value.", path);
+		if (typeof value !== "string" || !value.trim() || (schema.maxLength !== undefined && [...value].length > schema.maxLength) || (schema.pattern && !new RegExp(schema.pattern).test(value))) fail(code, stringRefusal(path, schema, value), path);
+		if (schema.enum && !schema.enum.includes(value)) fail(code, enumRefusal(path, schema, value), path);
 		return value;
 	}
-	if (schema.type === "boolean") { if (typeof value !== "boolean") fail(code, "Expected boolean.", path); return value; }
+	if (schema.type === "boolean") { if (typeof value !== "boolean") fail(code, wrongType(path, schema, value), path); return value; }
 	if (schema.type === "number" || schema.type === "integer") {
-		if (typeof value !== "number" || !Number.isFinite(value) || (schema.type === "integer" && !Number.isSafeInteger(value)) || (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum)) fail(code, "Number outside supported bounds.", path);
+		if (typeof value !== "number" || !Number.isFinite(value) || (schema.type === "integer" && !Number.isSafeInteger(value)) || (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum)) fail(code, numberRefusal(path, schema, value), path);
 		if ((schema.minimum !== undefined && value < schema.minimum) || (schema.maximum !== undefined && value > schema.maximum)) {
 			const bounds = [schema.minimum, schema.maximum].filter(bound => bound !== undefined);
-			fail(code, `${path}: Expected a number within [${bounds.join(", ")}].`, path);
+			fail(code, `${path}: Expected a number within [${bounds.join(", ")}], got ${value}.`, path);
 		}
 		return value;
 	}
@@ -455,13 +452,6 @@ export function validateStudioContextFreshness(submitted, current) {
 }
 const pickIdentity = value => Object.fromEntries(Object.keys(identityFields).map(key => [key, value[key]]));
 
-function validateGenerationTiming(value) {
-	const timed = value.beats.filter(beat => beat.seconds !== undefined).length;
-	if ((value.durationSeconds !== undefined && timed !== 0) || (value.durationSeconds === undefined && timed !== value.beats.length)) fail("INVALID_ARGUMENT", "Use total duration or a duration for every beat, not mixed timing.");
-	const total = value.durationSeconds ?? value.beats.reduce((sum, beat) => sum + beat.seconds, 0);
-	if (total < 2 || total > 60 || total / value.beats.length < 0.5) fail("INVALID_ARGUMENT", "Generation must be 2-60 seconds with at least 0.5 seconds per beat.");
-	return total;
-}
 /** Unknown paths are answered with the paths that DO exist for that kind, so a
  * caller never has to guess the vocabulary from a rejection. */
 function validatePatchPaths(args) {
@@ -501,35 +491,18 @@ export function validateStudioCommand(command) {
 		// final batch is still checked for overlap.
 		if (args.collisionPolicy === "avoid" && !args.ops.some(op => ["create", "update"].includes(op.op) && op.position?.relativeTo)) fail("INVALID_ARGUMENT", "collisionPolicy avoid needs at least one op with position.relativeTo (it nudges outward from that reference); other ops are placed as given.");
 	}
-	if (command.name === "generate_motion" && args.source.kind === "generate") {
-		args.source.beats = args.source.beats.map(beat => ({ ...beat, text: beat.text.trim().replace(/\s+/g, " ") }));
-		validateGenerationTiming(args.source);
-	}
 	if (command.name === "frame_shot" && args.framing.exact && JSON.stringify(args.framing.exact.position) === JSON.stringify(args.framing.exact.lookAt)) fail("INVALID_ARGUMENT", "Camera position and aim cannot coincide.");
 	if (command.name === "patch_elements") {
 		for (const op of args.ops) if (!Object.keys(op.set).length) fail("INVALID_ARGUMENT", "Patch has no fields.");
 	}
 	if (command.name === "verify_result") {
 		if (Boolean(args.receiptId) === Boolean(args.targets)) fail("INVALID_ARGUMENT", "Exactly one of receiptId or targets is required.");
-		if (args.checks.includes("motion") && args.range === undefined) args.range = "whole_clip";
-	}
-	return { name: command.name, args };
-}
-export function compileStudioBeats(value) {
-	const source = validateStudioSchema(generateSource, value);
-	const totalSeconds = validateGenerationTiming(source);
-	const frameCount = Math.round(totalSeconds * 24);
-	const blocks = []; let cumulative = 0, startFrame = 0;
-	for (const [sourceBeat, beat] of source.beats.entries()) {
-		cumulative += beat.seconds ?? totalSeconds / source.beats.length;
-		const end = sourceBeat === source.beats.length - 1 ? frameCount : Math.round(cumulative * 24);
-		const pieces = Math.ceil((end - startFrame) / 120), start = startFrame;
-		for (let i = 0; i < pieces; i++) {
-			const endFrameExclusive = start + Math.round((end - start) * (i + 1) / pieces);
-			blocks.push({ sourceBeat, text: beat.text.trim().replace(/\s+/g, " "), startFrame, endFrameExclusive }); startFrame = endFrameExclusive;
+		if (args.checks.includes("motion") && args.range === undefined) {
+			args.range = "whole_clip";
+			Object.defineProperty(args, "rangeWasDefaulted", { value: true, enumerable: false });
 		}
 	}
-	return freezeStudioData({ fps: 24, frameCount, durationSeconds: frameCount / 24, blocks });
+	return { name: command.name, args };
 }
 export function validateReceipt(value) {
 	if (value?.ok === false) {

package/src/studio-app-binding.js

@@ -3,16 +3,18 @@
 // history, the action registry); this module owns no React or renderer state.
 import { createCommandBus } from "./command-bus.js";
 import { readElementDocument, elementReadback, elementPatchArgs, elementTarget, elementPatchReceipt } from "./commands/elements.js";
-import { physicsKeyStamp } from "./ardy/physics-review.js";
+import { physicsKeyStamp } from "./motion/physics-review.js";
 import { shotAtFrame } from "./cuts.js";
 import { isProxyFigure } from "./scenes.js";
-import { CUTOUT_KIND, MESH_KIND, OBJECT_LIBRARY, supportHeightForObject } from "./scene-objects.js";
+import { supportHeightForObject } from "./scene-objects.js";
+import { studioAssetList } from "./studio-asset-list.js";
 import { buildStudioContext, physicsFingerprintInput, studioEntityCursor, validateStudioCursor } from "./studio-agent-context.js";
-import { createStudioCommandJournal, entityWorldBounds, framingChecks, localTransformReadback, placementChecks, studioObjectCatalogue } from "./studio-agent-commands.js";
-import { verifyInstalledTake } from "./studio-agent-motion.js";
-import { shotGeometryFacts } from "./studio-geometry-facts.js";
+import { createStudioCommandJournal, framingChecks, localTransformReadback, placementChecks, sampledFramingResult, studioObjectCatalogue } from "./studio-agent-commands.js";
+import { verifyInstalledTake } from "./studio-agent-motion.js"; import { objectRowBounds } from "./studio-entity-bounds.js"; import { exportFramingInto } from "./studio-export-framing.js";
+import { shotGeometryFacts } from "./studio-geometry-facts.js"; import { KIT_CATALOGUE } from "./kits/index.js";
 import { STUDIO_TOOL_FAMILIES, StudioProtocolError, validateReceipt, validateStudioCommand, validateStudioIdentity } from "./studio-agent-protocol.js";
-import { CONTACT_SHEET_LAYOUT, buildContactSheet, sampleContactSheetFrames } from "./studio-contact-sheet.js";
+import { studioVisual, verifyLighting } from "./studio-motion-visual.js";
+import { withEffectState } from "./effects/state.js"; import { hdrEnvironmentCatalogue } from "./stage-hdr-library.js";
 
 // App-owned adapter: the shared command modules remain the only
 // planners and validators. Ports below publish through the native editor stores.
@@ -34,8 +36,7 @@ export function createStudioAppBinding(ports) {
 	const motionContentKey = value => {
 		if (!value || typeof value !== "object") return null;
 		if (typeof value.studioTakeId === "string" && value.studioTakeId) return value.studioTakeId;
-		if (typeof value.motionRef?.motionId === "string" && value.motionRef.motionId) return value.motionRef.motionId;
-		return `${value.frames ?? 0}:${value.fps ?? 0}:${value.rotMats?.length ?? 0}:${value.rootPos?.length ?? 0}:${value.posedJoints?.length ?? 0}`;
+				return `${value.frames ?? 0}:${value.fps ?? 0}`;
 	};
 	const calibrationContentKey = value => value && typeof value === "object" ? JSON.stringify(value) : null;
 	const tokens = new Map(), receipts = new Map(), images = new Map();
@@ -121,30 +122,18 @@ export function createStudioAppBinding(ports) {
 			return { id: c.id, kind: "character", token: tokens.get(c.id).token, name: c.subject || c.id,
 				position: { x: c.x, y: c.y ?? 0, z: c.z }, yawDeg: c.rot ?? 0, scale: c.scale ?? 1, tint: c.tint ?? null, modelId: c.model ?? null,
 				motion: { takeId: t?.motion?.studioTakeId ?? null, frames: t?.motion?.frames ?? 0,
-					ikKeyCount: t?.ikState?.keys.size ?? 0, promptBlockCount: c.layer?.promptClips?.length ?? 0 },
+					ikKeyCount: t?.ikState?.keys.size ?? 0 },
 				capabilities: { rigReady: Boolean(t?.rig), ik: Boolean(t?.rig?.userData?.poseBind), measuredFeet: false },
 				characterKind: isProxyFigure(c) ? "proxy" : "rig", ...(isProxyFigure(c) ? { posture: c.posture ?? "stand" } : {}) };
 		}), ...s.objects.map(o => { const local = localTransformReadback(o, s.objects); return { id: o.id, kind: "object", token: tokens.get(o.id).token, name: o.name || o.id,
 			position: { x: o.x, y: o.y ?? 0, z: o.z }, yawDeg: o.rot ?? 0,
 			rotationDeg: { x: o.rotX ?? 0, y: o.rot ?? 0, z: o.rotZ ?? 0 }, scale: { x: o.scaleX, y: o.scaleY, z: o.scaleZ },
-			renderer: o.renderer, color: o.color ?? null, ...(o.assetId ? { assetId: o.assetId } : {}),
+			renderer: o.renderer, color: o.color ?? null, bounds: objectRowBounds(o, s, ports), ...(o.assetId ? { assetId: o.assetId } : {}),
 			parentId: o.parent ?? null, attachment: o.attach ?? null, pathPointCount: o.path?.points.length ?? 0,
 			// the dots on the route, with the lean (degrees) a mark carries
 			...(o.path?.marks?.length ? { pathMarks: o.path.marks.map(mark => typeof mark === "number" ? mark : { t: mark.t, ...(mark.bank !== undefined ? { bank: mark.bank } : {}), ...(mark.pitch !== undefined ? { pitch: mark.pitch } : {}) }) } : {}), ...(local ? { local } : {}) }; })];
 	}
 	const frameRange = row => ({ startFrame: row.startFrame, endFrameExclusive: row.endFrame + 1 });
-	function assetList(s) {
-		const catalogue = studioObjectCatalogue().objects.map(({ kind }) => {
-			const entry = OBJECT_LIBRARY.find(row => row.kind === kind);
-			return { kind, name: entry?.label ?? kind, type: entry?.group === "Primitives" ? "primitive" : "set-piece" };
-		});
-		const imported = new Map();
-		for (const o of s.objects) {
-			const assetId = o.renderer === CUTOUT_KIND ? o.sourceAssetId || o.assetId : o.renderer === MESH_KIND ? o.assetId : null;
-			if (assetId && !imported.has(assetId)) imported.set(assetId, { id: assetId, name: o.name || assetId, type: o.renderer === CUTOUT_KIND ? "image" : "mesh" });
-		}
-		return [...catalogue, ...imported.values()];
-	}
 	function context() {
 		const s = refresh(), entities = entityProjection(s), registry = ports.actions?.();
 		const shot = s.shots.find(row => row.id === s.selectedShotId) ?? shotAtFrame(s.shots, s.view.frame);
@@ -158,7 +147,7 @@ export function createStudioAppBinding(ports) {
 			// buildStudioContext selects the detailed rows and writes the real page.
 			entities, entityPage: { returned: 0, total: 0, truncated: false, nextCursor: null },
 			shots: s.shots.map(row => ({ id: row.id, name: row.name, range: range(row), keyCount: row.cameraKeys.length })), shotsTruncated: false,
-			assets: assetList(s), recentReceipts: [...receipts.values()].filter(r => r.ok).reverse().slice(0, 3).map(r => ({ id: r.receiptId, summary: r.status, canUndoDirect: ports.canUndo(r) })),
+			assets: studioAssetList(s.objects), recentReceipts: [...receipts.values()].filter(r => r.ok).reverse().slice(0, 3).map(r => ({ id: r.receiptId, summary: r.status, canUndoDirect: ports.canUndo(r) })),
 			jobs: [], capabilities: { profile: "studio-slice-1", tools: STUDIO_TOOL_FAMILIES,
 				rigReady: Boolean(s.targets.get(s.activeCharacterId)?.rig), cameraReady: Boolean(s.camera), bridgeReady: s.bridgeReady,
 				...(s.previsMode ? { storyboard: s.previsMode === "storyboard" } : {}) },
@@ -196,13 +185,13 @@ export function createStudioAppBinding(ports) {
 		if (id === s.host.sceneId) return { selection: s.selection, activeCharacterId: s.activeCharacterId, shotId: s.selectedShotId, view: s.view,
 			...(patched.length ? { patched } : {}) };
 		const object = s.objects.find(row => row.id === id), entity = object ?? s.characters.find(row => row.id === id);
-		// Beyond the transform an object's patched paths already carry: the world box it occupies and, for a
-		// group, who hangs off it. `compact` (a receipt near its size limit) drops back to the paths alone.
-		// A character's box means cloning and posing its rig, too dear for every receipt: inspect or verify has it.
+		// Beyond the transform an object's patched paths already carry: the world box it occupies (an empty: its
+		// parts', as inspect's rows) and, for a group, who hangs off it. `compact` (a receipt near its size limit) drops back to the paths alone.
+		// A character's box means cloning and posing its rig, too dear for every receipt or inspect row: verify has it.
 		const extras = () => {
 			if (!object || compact) return {};
 			const childIds = s.objects.filter(row => row.parent === id).map(row => row.id);
-			return { bounds: entityWorldBounds(object, { ...s, frame: s.view.frame }, { bounds: ports.bounds }),
+			return { bounds: objectRowBounds(object, s, ports),
 				...(childIds.length ? { childIds: childIds.slice(0, 12), ...(childIds.length > 12 ? { childCount: childIds.length } : {}) } : {}) };
 		};
 		if (patched.length) return { patched, ...extras() };
@@ -286,13 +275,18 @@ export function createStudioAppBinding(ports) {
 				// A framing check also carries the cut's geometry, read from the scene: side of the action line
 				// and sight lines per shot, the receipt's or targets' shots first (8 at most).
 				const result = { receiptId: receipt?.receiptId ?? null, revision: s.revision, evidenceRevision, stale: evidenceRevision !== s.revision, checks: measured ? { coverage: "current-scene-targets" } : receipt.checks,
-					verification: receipt?.verification ?? null, semanticStatus: "unavailable", visualRefs: [], unsupportedChecks: [], unsupportedReasons: {}, ...(args.checks.includes("framing") ? { geometry: shotGeometryFacts(scene, { first: receipt ? receipt.affectedIds : args.targets, ports: { bounds: ports.bounds } }) } : {}) };
-				const reasons = result.unsupportedReasons, verified = [], skipped = [], pending = [];
-				for (const check of args.checks.filter(check => check !== "motion" && measured)) {
+					verification: receipt?.verification ?? null, semanticStatus: "unavailable", visualRefs: [], unsupportedChecks: [], unsupportedReasons: {}, ...(args.checks.includes("framing") ? { geometry: shotGeometryFacts(scene, { first: receipt ? receipt.affectedIds : args.targets, ports: { bounds: ports.bounds } }) } : {}) }, reasons = result.unsupportedReasons, verified = [], skipped = [], pending = [];
+				// Lighting is measured from the rendered shot frame (studio-lighting-check.js), never from a receipt.
+				if (args.checks.includes("lighting")) verifyLighting(result, args.targets ?? receipt.affectedIds, scene, ports);
+				for (const check of args.checks.filter(check => !["motion", "lighting"].includes(check) && measured)) {
 					if (!measured.length) { reasons[check] = "No target is an object or character in the current scene."; continue; }
-					try { result.checks[check] = check === "placement" ? placementChecks(measured, scene, { bounds: ports.bounds }) : framingChecks(measured, scene, { bounds: ports.bounds }); }
+					try { result.checks[check] = check === "placement" ? placementChecks(measured, scene, { bounds: ports.bounds, takes: s.targets }) : framingChecks(measured, scene, { bounds: ports.bounds }); }
 					catch (error) { if (!(error instanceof StudioProtocolError)) throw error; reasons[check] = error.message; }
 				}
+				if (args.checks.includes("framing") && args.range !== undefined && !args.rangeWasDefaulted) {
+					const sampled = sampledFramingResult(args, scene, ports, s.frameCount, measured, receipt);
+					if (sampled.reason) reasons.framing = sampled.reason; else result.checks.framing = sampled;
+				}
 				if (args.checks.includes("motion") && !receipt?.verification) {
 					const subjects = args.targets ?? receipt.affectedIds.filter(id => s.characters.some(c => c.id === id));
 					if (!subjects.length) skipped.push("The receipt affected no character.");
@@ -305,17 +299,7 @@ export function createStudioAppBinding(ports) {
 							.then(verification => { verified[index] = verification; }, error => { if (!(error instanceof StudioProtocolError)) throw error; skipped.push(`${name}: ${error.message}`); }));
 					});
 				}
-				// 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.
-				if (args.visual !== "none") {
-					if (args.visual === "contact_sheet") {
-						// One image of frames across the range, each rendered through the export
-						// path, which puts the playhead pose, shot camera and props back.
-						const frames = sampleContactSheetFrames(args.range, s.frameCount), sheet = buildContactSheet(frames, ports.renderFrameBuffer), imageId = crypto.randomUUID();
-						images.set(imageId, { dataUrl: ports.encodePng(sheet.data, sheet), width: sheet.width, height: sheet.height, frames, layout: CONTACT_SHEET_LAYOUT, revision: s.revision, receiptId: result.receiptId });
-						result.visualRefs.push({ imageId, frames, layout: CONTACT_SHEET_LAYOUT });
-					} else { const capture = args.visual === "plan" ? (ports.capturePlan ?? (() => fail("CAPABILITY_MISSING", "This editor cannot render the top view.")))() : ports.capture(); const imageId = crypto.randomUUID(); images.set(imageId, { ...capture, revision: s.revision, receiptId: result.receiptId }); result.visualRefs.push({ imageId, ...(args.visual === "plan" ? { kind: "plan" } : {}) }); }
-				}
+				if (args.checks.includes("motion")) exportFramingInto(result, { args, s, receipt, scene, ports }); if (args.visual !== "none") studioVisual(args, { s, receipt, result, images, ports });
 				const finish = () => {
 					const computed = verified.filter(Boolean);
 					if (computed.length) result.verification = computed.length === 1 ? computed[0] : computed;
@@ -343,7 +327,7 @@ export function createStudioAppBinding(ports) {
 			// the model pays for): the revision is what the agent's next command is
 			// admitted at, so a scope without it leaves that admission stale.
 			const head = { revision: c.revision, host: (({ workspaceId, documentEpoch, sceneId, sceneEpoch }) => ({ workspaceId, documentEpoch, sceneId, sceneEpoch }))(c.host) };
-			if (command.args.scope === "catalogue") return { ...head, ...studioObjectCatalogue() };
+			if (command.args.scope === "catalogue") return { ...head, ...studioObjectCatalogue(), kits: KIT_CATALOGUE, environments: hdrEnvironmentCatalogue() };
 			if (command.args.scope === "document") return { ...head, scope: "document",
 				...readElementDocument(refresh().document, command.args, c.host.sceneId) };
 			// Discovery for run_action: every registered action with its label, kind,
@@ -366,7 +350,8 @@ export function createStudioAppBinding(ports) {
 			// Stable id order, so an offset cursor survives unrelated edits.
 			const filtered = entityProjection(s).filter(wanted).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 			const offset = args.cursor ? validateStudioCursor(args.cursor, c) : 0, limit = command.args.limit;
-			return { ...head, entities: filtered.slice(offset, offset + limit), total: filtered.length,
+			// An effect row also carries its particles at the playhead (src/effects/state.js).
+			return { ...head, entities: filtered.slice(offset, offset + limit).map(row => withEffectState(row, s.view.frame, s.objects)), total: filtered.length,
 				nextCursor: offset + limit < filtered.length ? studioEntityCursor(c, offset + limit) : null };
 		},
 		operate_studio: request => execute({ ...request, name: "operate_studio" }),
@@ -374,7 +359,6 @@ export function createStudioAppBinding(ports) {
 		arrange_characters: request => execute({ ...request, name: "arrange_characters" }),
 		patch_elements: request => execute({ ...request, name: "patch_elements" }),
 		frame_shot: request => execute({ ...request, name: "frame_shot" }),
-		generate_motion: request => execute({ ...request, name: "generate_motion" }),
 		verify_result: request => execute({ ...request, name: "verify_result" }),
 		undo_edit: request => runAction(request, { action: "edit.undo", args: request.args }),
 		run_action: request => execute({ ...request, name: "run_action" }),

package/src/studio-asset-list.js

@@ -0,0 +1,17 @@
+// The asset summary the agent's turn context lists: every catalogue kind the
+// Studio can create, then each imported picture or model once.
+import { CUTOUT_KIND, MESH_KIND, OBJECT_MENU_ENTRIES } from "./scene-objects.js";
+import { studioObjectCatalogue } from "./studio-agent-commands.js";
+
+export function studioAssetList(objects) {
+	const catalogue = studioObjectCatalogue().objects.map(({ kind }) => {
+		const entry = OBJECT_MENU_ENTRIES.find(row => row.kind === kind);
+		return { kind, name: entry?.label ?? kind, type: entry?.group === "Primitives" ? "primitive" : "set-piece" };
+	});
+	const imported = new Map();
+	for (const o of objects) {
+		const assetId = o.renderer === CUTOUT_KIND ? o.sourceAssetId || o.assetId : o.renderer === MESH_KIND ? o.assetId : null;
+		if (assetId && !imported.has(assetId)) imported.set(assetId, { id: assetId, name: o.name || assetId, type: o.renderer === CUTOUT_KIND ? "image" : "mesh" });
+	}
+	return [...catalogue, ...imported.values()];
+}

package/src/studio-contact-sheet.js

@@ -5,7 +5,7 @@
 const CONTACT_SHEET_COLUMNS = 3;
 const CONTACT_SHEET_ROWS = 2;
 export const CONTACT_SHEET_LAYOUT = "3x2 row-major";
-const CONTACT_SHEET_MAX_SIDE = 1600;
+const CONTACT_SHEET_MAX_SIDE = 1600, VIEW_SHEET_MAX_HEIGHT = 900;
 
 /** Up to 6 frames spread evenly over a half-open range, first and last
  * included; "whole_clip" (or no range) is timeline frames 0..frameCount-1. */
@@ -53,21 +53,53 @@ export function tileRgba(tiles, tileWidth, tileHeight, { columns = CONTACT_SHEET
 	return { data, width, height };
 }
 
+/** The grid of a sheet: 3x2 row-major for up to 6 frames, 4x2 for 7-8. Views of its own
+ * (viewCount >= 1) take a column per frame and a row per view when there are several views
+ * or at most 3 frames. viewCount 0 is the shot camera. */
+export function sheetGrid(frameCount, viewCount = 0) {
+	if (viewCount > 1 || (viewCount === 1 && frameCount <= 3)) return { columns: frameCount, rows: viewCount, layout: `${frameCount}x${viewCount} row-major, a row per view` };
+	return frameCount <= CONTACT_SHEET_COLUMNS * CONTACT_SHEET_ROWS ? { columns: CONTACT_SHEET_COLUMNS, rows: CONTACT_SHEET_ROWS, layout: CONTACT_SHEET_LAYOUT } : { columns: 4, rows: 2, layout: "4x2 row-major" };
+}
+
+/** Square tile side for a grid of own-camera views: the sheet stays within
+ * maxSide wide and VIEW_SHEET_MAX_HEIGHT high (1600x900 at most). */
+export const viewTileSide = ({ columns, rows }, maxSide = CONTACT_SHEET_MAX_SIDE) => Math.max(1, Math.floor(Math.min(maxSide / columns, VIEW_SHEET_MAX_HEIGHT / rows)));
+
+/** Paint dots on a bottom-up RGBA buffer: { x, y (from the bottom row), r, color [r,g,b],
+ * alpha 0..1, ring } with ring drawing a 1 px white circle around the dot at r + 2. */
+export function paintDots(data, width, height, dots) {
+	const put = (x, y, [r, g, b], a) => {
+		if (x < 0 || y < 0 || x >= width || y >= height) return;
+		const i = (y * width + x) * 4;
+		data[i] = Math.round(data[i] + (r - data[i]) * a); data[i + 1] = Math.round(data[i + 1] + (g - data[i + 1]) * a); data[i + 2] = Math.round(data[i + 2] + (b - data[i + 2]) * a);
+	};
+	for (const { x, y, r, color, alpha = 1, ring = false } of dots) {
+		const cx = Math.round(x), cy = Math.round(y), reach = Math.ceil(r) + (ring ? 3 : 0);
+		for (let dy = -reach; dy <= reach; dy++) for (let dx = -reach; dx <= reach; dx++) {
+			const d = Math.hypot(dx, dy);
+			if (d <= r) put(cx + dx, cy + dy, color, alpha);
+			else if (ring && Math.abs(d - r - 2) <= 0.5) put(cx + dx, cy + dy, [255, 255, 255], 1);
+		}
+	}
+	return data;
+}
+
 /** Render each frame (render(frame) -> { data, width, height }, rows bottom-up),
  * shrink it so the whole sheet's longest side is at most maxSide, and tile
- * the frames 3x2 row-major into one bottom-up buffer. */
-export function buildContactSheet(frames, render, { maxSide = CONTACT_SHEET_MAX_SIDE } = {}) {
+ * the frames row-major (3x2 unless columns and rows say) into one bottom-up buffer.
+ * A frame may be any cell the render understands (a frame and a view). */
+export function buildContactSheet(frames, render, { maxSide = CONTACT_SHEET_MAX_SIDE, columns = CONTACT_SHEET_COLUMNS, rows = CONTACT_SHEET_ROWS } = {}) {
 	const tiles = [];
 	let tileWidth, tileHeight;
 	for (const frame of frames) {
 		const shot = render(frame);
 		if (tileWidth === undefined) {
-			const scale = Math.min(1, maxSide / Math.max(shot.width * CONTACT_SHEET_COLUMNS, shot.height * CONTACT_SHEET_ROWS));
+			const scale = Math.min(1, maxSide / Math.max(shot.width * columns, shot.height * rows));
 			tileWidth = Math.max(1, Math.floor(shot.width * scale));
 			tileHeight = Math.max(1, Math.floor(shot.height * scale));
 		}
 		// The renderer reuses one read-back buffer: shrink this frame before the next render.
 		tiles.push(boxDownscaleRgba(shot.data, shot.width, shot.height, tileWidth, tileHeight));
 	}
-	return tileRgba(tiles, tileWidth, tileHeight, { bottomUp: true });
+	return tileRgba(tiles, tileWidth, tileHeight, { columns, rows, bottomUp: true });
 }