cozyclay 2.0.0 → 2.1.0

package/src/studio-app-binding.js

@@ -5,10 +5,12 @@ import { createCommandBus } from "./command-bus.js";
 import { readElementDocument, elementReadback, elementPatchArgs, elementTarget, elementPatchReceipt } from "./commands/elements.js";
 import { physicsKeyStamp } from "./ardy/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 { buildStudioContext, physicsFingerprintInput, studioEntityCursor, validateStudioCursor } from "./studio-agent-context.js";
-import { createStudioCommandJournal, framingChecks, placementChecks, studioObjectCatalogue } from "./studio-agent-commands.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 { STUDIO_TOOL_FAMILIES, StudioProtocolError, validateReceipt, validateStudioCommand, validateStudioIdentity } from "./studio-agent-protocol.js";
 import { CONTACT_SHEET_LAYOUT, buildContactSheet, sampleContactSheetFrames } from "./studio-contact-sheet.js";
 
@@ -120,12 +122,15 @@ export function createStudioAppBinding(ports) {
 				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 },
-				capabilities: { rigReady: Boolean(t?.rig), ik: Boolean(t?.rig?.userData?.poseBind), measuredFeet: false } };
-		}), ...s.objects.map(o => ({ id: o.id, kind: "object", token: tokens.get(o.id).token, name: o.name || o.id,
+				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 } : {}),
-			parentId: o.parent ?? null, attachment: o.attach ?? null, pathPointCount: o.path?.points.length ?? 0 }))];
+			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) {
@@ -147,7 +152,7 @@ export function createStudioAppBinding(ports) {
 		return buildStudioContext({ schema: "studio-context-v1", host: { surface: "studio", ...s.host, workspaceHandle: s.workspaceHandle },
 			revision: { scene: s.revision, physics: s.physicsRevision, view: s.viewRevision },
 			units: { distance: "m", angle: "deg", up: "+Y", yawZero: "+Z", yawPositiveToward: "+X", pivot: "base", fps: 24, rangeEnd: "exclusive" },
-			scene: { name: s.sceneName, aspect: s.aspect, floorY: 0, frameCount: s.frameCount, objectCount: s.objects.length, characterCount: s.characters.length },
+			scene: { name: s.sceneName, aspect: s.aspect, floorY: 0, frameCount: s.frameCount, objectCount: s.objects.length, characterCount: s.characters.length, ...(s.previsMode ? { previsMode: s.previsMode } : {}) },
 			selection: s.selection, activeCharacterId: s.activeCharacterId, view: s.view,
 			shot: shot ? { id: shot.id, name: shot.name, range: range(shot), mode: shot.camera?.mode ?? "keys" } : null, camera: s.camera,
 			// buildStudioContext selects the detailed rows and writes the real page.
@@ -155,7 +160,8 @@ export function createStudioAppBinding(ports) {
 			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) })),
 			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 },
+				rigReady: Boolean(s.targets.get(s.activeCharacterId)?.rig), cameraReady: Boolean(s.camera), bridgeReady: s.bridgeReady,
+				...(s.previsMode ? { storyboard: s.previsMode === "storyboard" } : {}) },
 			// Every registered command; buildStudioContext keeps only its id/label index.
 			...(registry ? { actions: registry.list() } : {}) });
 	}
@@ -182,19 +188,32 @@ export function createStudioAppBinding(ports) {
 		return s;
 	}
 	/** Actual state of one action target after it ran. */
-	function actionReadback(id, s) {
+	function actionReadback(id, s, compact = false) {
 		const patched = Object.entries(s.document).flatMap(([kind, value]) => {
 			const target = elementTarget(kind, value, id, s.host.sceneId);
 			return target ? elementReadback(kind, target) : [];
 		});
 		if (id === s.host.sceneId) return { selection: s.selection, activeCharacterId: s.activeCharacterId, shotId: s.selectedShotId, view: s.view,
 			...(patched.length ? { patched } : {}) };
-		if (patched.length) return { 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.
+		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 }),
+				...(childIds.length ? { childIds: childIds.slice(0, 12), ...(childIds.length > 12 ? { childCount: childIds.length } : {}) } : {}) };
+		};
+		if (patched.length) return { patched, ...extras() };
 		const shot = s.shots.find(row => row.id === id);
 		if (shot) return { name: shot.name || shot.id, range: { startFrame: shot.startFrame, endFrameExclusive: shot.endFrame + 1 } };
-		const entity = s.objects.find(row => row.id === id) ?? s.characters.find(row => row.id === id);
-		if (entity) return { name: entity.name || entity.subject || entity.id, position: { x: entity.x, y: entity.y ?? 0, z: entity.z } };
-		return { removed: true };
+		if (!entity) return { removed: true };
+		const brief = { name: entity.name || entity.subject || entity.id, position: { x: entity.x, y: entity.y ?? 0, z: entity.z } };
+		if (compact) return brief;
+		if (!object) return { ...brief, yawDeg: entity.rot ?? 0, scale: entity.scale ?? 1, ...extras() };
+		return { ...brief, rotationDeg: { x: object.rotX ?? 0, y: object.rot ?? 0, z: object.rotZ ?? 0 }, scale: { x: object.scaleX, y: object.scaleY, z: object.scaleZ },
+			parentId: object.parent ?? null, ...extras() };
 	}
 	/** One registered Studio action, run for the agent through the same
 	 * registry the UI controls call. A mutation is bound to the native history
@@ -220,7 +239,7 @@ export function createStudioAppBinding(ports) {
 	}
 	function runAction(request, args) {
 		const { name: _name, args: _args, ...options } = request;
-		const result = commandBus().run(args.action, args.args, { ...options, origin: "agent", confirmationToken: args.confirmationToken ?? request.confirmationToken });
+		const result = commandBus().run(args.action, args.args, { ...options, origin: "agent", turnId: request.turnId, confirmationToken: args.confirmationToken ?? request.confirmationToken });
 		const answer = receipt => receipt.nextHost ? { ...receipt, host: receipt.nextHost } : receipt;
 		return result?.then ? result.then(answer) : answer(result);
 	}
@@ -260,9 +279,14 @@ export function createStudioAppBinding(ports) {
 				// Only a check nothing could compute is unsupported, and says why; a motion
 				// check computed for some characters still names the ones it skipped.
 				const scene = readCommand(), entityIds = ids => ids.filter(id => scene.objects.some(o => o.id === id) || scene.characters.some(c => c.id === id));
-				const measured = args.targets ? entityIds(args.targets) : receipt.checks ? null : entityIds(receipt.affectedIds);
+				// A receipt's checks are evidence only for what they measured: every receipt carries a coverage tag, but
+				// only an arrange/frame receipt carries overlap or framing numbers. Anything else is measured here.
+				const measuredBy = { placement: "overlapIds", framing: "screenFraction" }, unmeasured = receipt && args.checks.some(check => measuredBy[check] && receipt.checks?.[measuredBy[check]] === undefined);
+				const measured = args.targets ? entityIds(args.targets) : unmeasured ? entityIds(receipt.affectedIds) : null;
+				// 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: {} };
+					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)) {
 					if (!measured.length) { reasons[check] = "No target is an object or character in the current scene."; continue; }
@@ -281,6 +305,8 @@ 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
@@ -288,7 +314,7 @@ export function createStudioAppBinding(ports) {
 						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 = ports.capture(); const imageId = crypto.randomUUID(); images.set(imageId, { ...capture, revision: s.revision, receiptId: result.receiptId }); result.visualRefs.push({ imageId }); }
+					} 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" } : {}) }); }
 				}
 				const finish = () => {
 					const computed = verified.filter(Boolean);
@@ -312,17 +338,20 @@ export function createStudioAppBinding(ports) {
 		read_studio_context(request) { const c = context(); if (!same(validateStudioIdentity(request.host), owner)) fail("STALE_SCENE", "This is not the requested document."); return c; },
 		inspect_studio(args) {
 			const command = validateStudioCommand({ name: "inspect_studio", args }); const c = context();
-			// Every scope carries the context: its revision is what the agent's next
-			// command is admitted at, so a scope without it leaves that admission stale.
-			if (command.args.scope === "catalogue") return { context: c, ...studioObjectCatalogue() };
-			if (command.args.scope === "document") return { context: c, scope: "document",
+			// Every scope carries the revision and document identity, not the whole
+			// context (the turn already holds that, and resending it per call is what
+			// 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 === "document") return { ...head, scope: "document",
 				...readElementDocument(refresh().document, command.args, c.host.sceneId) };
 			// Discovery for run_action: every registered action with its label, kind,
 			// exposure and availability (the reason when unavailable). Schemas are on
 			// request: ids answer those actions' full declarations, input included.
 			if (command.args.scope === "actions") {
-				const actions = ports.actions?.()?.list() ?? [];
-				return { context: c, actions: command.args.ids ? actions.filter(row => command.args.ids.includes(row.id)) : actions.map(({ input, description, ...row }) => row) };
+				const actions = (ports.actions?.()?.list() ?? []).filter(row => !row.agentHidden);
+				return { ...head, actions: command.args.ids ? actions.filter(row => command.args.ids.includes(row.id)) : actions.map(({ input, description, ...row }) => row) };
 			}
 			const s = refresh();
 			const wanted = row => (!args.ids || args.ids.includes(row.id)) && (!args.query || Boolean(row.name?.includes(args.query)));
@@ -330,14 +359,14 @@ export function createStudioAppBinding(ports) {
 				const select = { shot: ["shot"], motion: ["motion", "character"] }[command.args.scope];
 				const ids = args.ids ?? (command.args.scope === "selection" ? [s.selection?.id ?? s.host.sceneId]
 					: args.query && select ? (command.args.scope === "shot" ? s.shots : entityProjection(s).filter(row => row.kind === "character")).filter(wanted).map(row => row.id) : undefined);
-				return { context: c, scope: "document", ...readElementDocument(s.document, { ...command.args, ids, select }, c.host.sceneId) };
+				return { ...head, scope: "document", ...readElementDocument(s.document, { ...command.args, ids, select }, c.host.sceneId) };
 			}
 			// Build each page from the same complete authoritative projection; never
 			// page by slicing an already-truncated Send context.
 			// 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 { context: c, entities: filtered.slice(offset, offset + limit), total: filtered.length,
+			return { ...head, entities: filtered.slice(offset, offset + limit), total: filtered.length,
 				nextCursor: offset + limit < filtered.length ? studioEntityCursor(c, offset + limit) : null };
 		},
 		operate_studio: request => execute({ ...request, name: "operate_studio" }),

package/src/studio-contact-sheet.js

@@ -2,10 +2,10 @@
 // shot render shrinks, and where it lands on the one image the agent sees.
 // Pure over RGBA byte buffers; App.jsx supplies the render and the encoder.
 
-export const CONTACT_SHEET_COLUMNS = 3;
-export const CONTACT_SHEET_ROWS = 2;
+const CONTACT_SHEET_COLUMNS = 3;
+const CONTACT_SHEET_ROWS = 2;
 export const CONTACT_SHEET_LAYOUT = "3x2 row-major";
-export const CONTACT_SHEET_MAX_SIDE = 1600;
+const CONTACT_SHEET_MAX_SIDE = 1600;
 
 /** 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. */

package/src/studio-elements.js

@@ -22,7 +22,11 @@ const entries = [
 	{ path: "character.scale", type: "number", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", min: 0.2, max: 3 },
 	{ path: "character.subject", type: "string", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
 	{ path: "character.hidden", type: "boolean", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
-	{ path: "character.model", type: "enum", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", enum: ["y-bot-tpose", "x-bot-tpose"] },
+	{ path: "character.parent", type: "id", nullable: true, persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", note: "scene object id the character is grouped under and rides; null stands in the world" },
+	// The model and posture enums mirror scenes.js CHARACTER_KIND_IDS and
+	// POSTURES; they are literal because scenes.js imports this module.
+	{ path: "character.model", type: "enum", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", enum: ["y-bot-tpose", "x-bot-tpose", "proxy-figure"] },
+	{ path: "character.posture", type: "enum", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry", enum: ["stand", "sit", "lie"] },
 	{ path: "character.tint", type: "color", persisted: true, undoDomain: "cast", normalizer: "createCharacterEntry" },
 	{ 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" },
@@ -32,12 +36,13 @@ const entries = [
 	{ 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"] },
+	{ 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.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.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" },
 	{ path: "object.parent", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
 	{ path: "object.attach", type: "id", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", actions: ["object.attach", "object.detach"], note: "carried by a character's root or bone; channels convert so the prop stays put" },
 	{ path: "object.path", type: "array", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject" },
@@ -59,6 +64,10 @@ const entries = [
 	{ 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" },
 	{ path: "shot.targetModel", type: "id", persisted: true, undoDomain: "shot", normalizer: "repairCamera" },
+	{ path: "shot.kind", type: "enum", persisted: true, undoDomain: "shot", normalizer: null, readOnly: true, enum: ["clip", "still"], note: "clip or still; a still holds one picture for endFrame - startFrame + 1 frames" },
+	{ path: "shot.caption", type: "string", persisted: true, undoDomain: "shot", normalizer: null, readOnly: true, note: "trimmed, at most 500 characters" },
+	{ path: "shot.cast", type: "array", persisted: true, undoDomain: "shot", normalizer: null, readOnly: true, note: "per-shot placement overrides keyed by character id: { x, z, rot, posture?, pose? }" },
+	{ path: "shot.stylizedAssetId", type: "id", nullable: true, persisted: true, undoDomain: "shot", normalizer: null, readOnly: true, note: "image asset id only" },
 	{ path: "shot.freeCamera", type: "vec3", persisted: false, undoDomain: "shot", normalizer: null, note: "transient until keyed" },
 	{ path: "scenes", type: "array", persisted: true, undoDomain: null, normalizer: null, actions: ["scene.create", "scene.duplicate", "scene.rename", "scene.delete", "scene.switch"], note: "the project's scene list and the open scene; outside the undo history" },
 	{ path: "project", type: "string", persisted: true, undoDomain: null, normalizer: null, actions: ["project.save"], note: "save to the current project file; opening one needs the user's file picker" },

package/src/studio-geometry-facts.js

@@ -0,0 +1,114 @@
+// Shot geometry the Studio agent reads as facts instead of judging from a picture:
+// where the cast stands, which side of the line between the two leading
+// characters each shot camera sits on (the 180-degree rule), and which props
+// stand between a camera and its subject. Pure: no renderer, no React.
+import { entityWorldBounds } from './studio-agent-commands.js';
+import { isEffectivelyHidden } from './scene-objects.js';
+import { shotAtFrame } from './cuts.js';
+
+export const GEOMETRY_FACTS_LIMITS = Object.freeze({ shots: 8, subjects: 24, pairs: 24, occluders: 8 });
+/** Closer to the action line than this (m) is "on-axis", neither side. */
+const ON_AXIS_M = 0.05;
+const EPS = 1e-9;
+const round = v => Math.round(v * 1000) / 1000 + 0;
+const point = p => ({ x: round(p.x), y: round(p.y ?? 0), z: round(p.z) });
+const visibleCharacters = state => state.characters.filter(c => !isEffectivelyHidden(c, state.objects, state.characters));
+
+/** Does the segment p0->p1 pass through the box {min, max}? Slab test over t in [0, 1]. */
+export function segmentIntersectsAabb(p0, p1, box) {
+  let t0 = 0, t1 = 1;
+  for (const a of ['x', 'y', 'z']) {
+    const d = p1[a] - p0[a];
+    if (Math.abs(d) < EPS) {
+      if (p0[a] < box.min[a] || p0[a] > box.max[a]) return false;
+      continue;
+    }
+    let near = (box.min[a] - p0[a]) / d, far = (box.max[a] - p0[a]) / d;
+    if (near > far) [near, far] = [far, near];
+    t0 = Math.max(t0, near); t1 = Math.min(t1, far);
+    if (t0 > t1) return false;
+  }
+  return true;
+}
+const contains = (box, p) => ['x', 'y', 'z'].every(a => p[a] >= box.min[a] && p[a] <= box.max[a]);
+
+/** Which side of the horizontal line a->b the point p stands on, seen from above
+ * (+Y up) looking along a->b: the sign of (axis x (p - a)).y with the axis
+ * normalised, so the threshold is metres. Negative is right, positive left;
+ * within ON_AXIS_M it is "on-axis". Null when a and b share a spot. */
+export function sideOfAxis(a, b, p) {
+  const ax = b.x - a.x, az = b.z - a.z, length = Math.hypot(ax, az);
+  if (length < EPS) return null;
+  const offset = (az * (p.x - a.x) - ax * (p.z - a.z)) / length;
+  return Math.abs(offset) < ON_AXIS_M ? 'on-axis' : offset > 0 ? 'left' : 'right';
+}
+
+/** The two characters a camera is read against: the given ids that are visible
+ * characters, then the visible characters nearest the camera. Ordered by id, so
+ * every shot of the same pair reads the line in the same direction. */
+export function primarySubjects(ids, cameraPosition, state) {
+  const visible = visibleCharacters(state);
+  const chosen = ids.map(id => visible.find(c => c.id === id)).filter(Boolean);
+  const near = c => Math.hypot(c.x - cameraPosition.x, c.z - cameraPosition.z);
+  const rest = visible.filter(c => !chosen.includes(c)).sort((p, q) => near(p) - near(q));
+  return [...chosen, ...rest].slice(0, 2).sort((p, q) => (p.id < q.id ? -1 : p.id > q.id ? 1 : 0));
+}
+
+/** Props whose world box crosses the sight line from the camera to the centre of
+ * the subject's box. The subject itself, props attached to it, hidden props and
+ * an enclosure the camera stands inside (a room set) never count. */
+export function occludersOf(subject, cameraPosition, state, ports, subjectBounds = entityWorldBounds(subject, state, ports)) {
+  if (!subjectBounds) return [];
+  const centre = Object.fromEntries(['x', 'y', 'z'].map(a => [a, (subjectBounds.min[a] + subjectBounds.max[a]) / 2]));
+  return state.objects.filter(o => o.id !== subject.id && o.attach?.characterId !== subject.id && !isEffectivelyHidden(o, state.objects, state.characters))
+    .flatMap(o => {
+      const box = entityWorldBounds(o, state, ports);
+      return box && !contains(box, cameraPosition) && segmentIntersectsAabb(cameraPosition, centre, box) ? [{ subjectId: subject.id, byObjectId: o.id }] : [];
+    });
+}
+
+/** A shot's camera as position + aim: the live camera for the shot under the
+ * playhead, else the shot's first camera key; null when it has neither. */
+export function shotCamera(shot, state) {
+  if (state.camera && shotAtFrame(state.shotDocument.shots, state.frame)?.id === shot.id) return { position: state.camera.position, lookAt: state.camera.lookAt };
+  const framing = shot.cameraKeys?.[0]?.framing;
+  if (!framing) return null;
+  const { pos, yaw, pitch } = framing;
+  return { position: pos, lookAt: { x: pos.x - Math.sin(yaw) * Math.cos(pitch), y: pos.y + Math.sin(pitch), z: pos.z - Math.cos(yaw) * Math.cos(pitch) } };
+}
+
+/** The 180-degree rule over shots read against the same pair: false when any
+ * pair has cameras on both sides, true when some pair has two sided shots and
+ * none crosses, null when no pair has two sided shots to compare. */
+function axisConsistency(shots) {
+  const byPair = new Map();
+  for (const shot of shots) {
+    if (shot.cameraSide !== 'left' && shot.cameraSide !== 'right') continue;
+    const key = shot.subjectIds.join('|');
+    byPair.set(key, [...(byPair.get(key) ?? []), shot.cameraSide]);
+  }
+  const compared = [...byPair.values()].filter(sides => sides.length >= 2);
+  return compared.length ? compared.every(sides => sides.every(side => side === sides[0])) : null;
+}
+
+/** Facts for the given shots, bounded by GEOMETRY_FACTS_LIMITS. Without shotIds:
+ * the shots named in `first` (other ids are skipped), then the rest of the cut, so
+ * axisConsistent compares the named shots with the others. */
+export function shotGeometryFacts(state, { shotIds, first = [], ports } = {}) {
+  const cast = visibleCharacters(state).slice(0, GEOMETRY_FACTS_LIMITS.subjects);
+  const subjects = cast.map(c => ({ id: c.id, position: point(c), yawDeg: round(c.rot ?? 0) }));
+  const pairs = cast.flatMap((a, i) => cast.slice(i + 1).map(b => ({ a: a.id, b: b.id, distanceM: round(Math.hypot(b.x - a.x, b.z - a.z)) })))
+    .sort((p, q) => p.distanceM - q.distanceM).slice(0, GEOMETRY_FACTS_LIMITS.pairs);
+  const all = state.shotDocument.shots;
+  const named = all.filter(s => first.includes(s.id)).sort((p, q) => first.indexOf(p.id) - first.indexOf(q.id));
+  const wanted = (shotIds ? shotIds.map(id => all.find(s => s.id === id)) : [...named, ...all.filter(s => !named.includes(s))]).filter(Boolean).slice(0, GEOMETRY_FACTS_LIMITS.shots);
+  const shots = wanted.map(shot => {
+    const camera = shotCamera(shot, state);
+    if (!camera) return { shotId: shot.id, subjectIds: [], camera: null, cameraSide: null, occluders: [] };
+    const pair = primarySubjects(shot.subjectIds ?? [], camera.position, state);
+    return { shotId: shot.id, subjectIds: pair.map(c => c.id), camera: { position: point(camera.position), lookAt: point(camera.lookAt) },
+      cameraSide: pair.length === 2 ? sideOfAxis(pair[0], pair[1], camera.position) : null,
+      occluders: pair.flatMap(subject => occludersOf(subject, camera.position, state, ports)).slice(0, GEOMETRY_FACTS_LIMITS.occluders) };
+  });
+  return { subjects, pairs, shots, axisConsistent: axisConsistency(shots) };
+}

package/src/styles.css

@@ -847,6 +847,9 @@ select {
 	display: none;
 }
 .app[data-embed-mode="playground"] .tl-view-tools { display: none !important; }
+/* The v2 Sequencer styles sit outside the legacy layer, so the lane rule above
+   needs !important to keep only the Shots lane. */
+.app[data-embed-mode="playground"] .tl-track:not(.shots) { display: none !important; }
 /* Title bar keeps nothing but the pane's own name: the drawn dolly plays
    full-screen through the shot camera's look-through button, and Esc is the
    way back to flying. */
@@ -855,6 +858,8 @@ select {
 /* The plan inset only matters while a rail is being drawn into it. */
 .app[data-embed-mode="playground"]:not([data-rail-draw="1"]) .vp-inset.plan { display: none !important; }
 .app[data-embed-mode="playground"][data-rail-draw="1"] .vp-inset.plan { width: 44% !important; height: 62% !important; }
+/* The shot monitor would sit over the map's corner while the rail is drawn. */
+.app[data-embed-mode="playground"][data-rail-draw="1"] .vp-shot-preview { display: none !important; }
 .app[data-embed-mode="playground"] .bottom-window,
 .app[data-embed-mode="playground"] .bottom-timeline {
 	flex: 0 0 auto;
@@ -865,7 +870,7 @@ select {
 .app[data-embed-mode="playground"] .timeline.empty-shots { height: auto !important; min-height: 0 !important; max-height: none; }
 .app[data-embed-mode="playground"] .tl-body { flex: 0 0 auto; overflow: hidden; }
 .app[data-embed-mode="playground"] .tl-body { min-height: 0 !important; height: auto !important; }
-.app[data-embed-mode="playground"] .tl-surface { height: auto !important; min-height: 0; grid-template-rows: auto auto !important; }
+.app[data-embed-mode="playground"] .tl-surface { height: auto !important; min-height: 0 !important; grid-template-rows: auto auto !important; }
 /* The Shots lane keeps its full-studio height so the block's hover actions
    (Duplicate / Delete) sit in a strip above the clickable body instead of
    covering it. */
@@ -875,7 +880,8 @@ select {
 /* The shot monitor is the pane the tutorial points at: keep it small. */
 .app[data-embed-mode="playground"] .vp-shot-preview { width: 22% !important; height: auto !important; aspect-ratio: 16 / 9; right: 12px; bottom: 12px; }
 .app[data-embed-mode="playground"] .vp-shot-preview-tag { font-size: 12px; }
-.app[data-embed-mode="playground"] .vp-look-through { width: 24px; height: 24px; }
+/* The look-through button carries its label now; keep it on one line. */
+.app[data-embed-mode="playground"] .vp-look-through { height: 24px; padding: 0 8px; white-space: nowrap; }
 .app[data-embed-mode="playground"] .vp-look-through svg { width: 15px; height: 15px; }
 /* Tutorial hints: the landing page names the control the current step needs. */
 .app[data-playground-hint="look"] .vp-look-through,
@@ -899,7 +905,8 @@ select {
 .app[data-tutorial-step="shot"] .tl-track.shots .tl-track-add,
 .app[data-tutorial-step="rail"] .tl-track.shots .tl-shot-block:not(.selected),
 .app[data-tutorial-step="rail"] .tl-rail-draw,
-.app[data-tutorial-step="play"] .vp-look-through {
+.app[data-tutorial-step="play"] .vp-look-through,
+.app[data-tutorial-step="play"] .dock-shot-look {
 	animation: tutorial-spotlight 1.5s var(--ease) infinite;
 	box-shadow: 0 0 0 3px var(--accent);
 }
@@ -3031,6 +3038,28 @@ input[type=range]::-moz-range-thumb {
 	color: #eafff3;
 }
 
+/* The selected dot's lean: two small scrub fields, the word as their badge. */
+.objmo-lean {
+	display: inline-flex;
+	align-items: stretch;
+	gap: 6px;
+}
+
+.objmo-lean .number-field {
+	flex: none;
+	width: 104px;
+}
+
+.objmo-lean .number-field .axis {
+	width: auto;
+	padding: 0 6px;
+	font-size: 10px;
+}
+
+.number-field.disabled { opacity: .45; }
+.number-field.disabled .axis,
+.number-field.disabled input { cursor: not-allowed; }
+
 .tl-path-hint {
 	margin-left: auto;
 	color: #7fae95;
@@ -3135,9 +3164,22 @@ input[type=range]::-moz-range-thumb {
 	vector-effect: non-scaling-stroke;
 }
 
-.sg-cut-diamond { fill: #ffb454; }
+/* The pin head lives outside the SVG: the graph's 1×1 viewBox is stretched to
+   the lane, so anything drawn inside it is as wide as the lane is long. */
+.sg-cut-pin {
+	position: absolute;
+	top: 3px;
+	width: 9px;
+	height: 9px;
+	padding: 0;
+	border: 0;
+	border-radius: 2px;
+	background: #ffb454;
+	transform: translateX(-50%) rotate(45deg);
+	cursor: pointer;
+}
 
-.sg-pin.selected .sg-cut-diamond { fill: #ffd08a; }
+.sg-cut-pin.selected { background: #ffd08a; box-shadow: 0 0 0 2px rgba(255, 208, 138, .35); }
 .sg-pin.selected .sg-cut { stroke-width: 2; stroke-dasharray: none; }
 
 .sg-cut-pick {
@@ -3333,7 +3375,9 @@ input[type=range]::-moz-range-thumb {
 .sg-shot .sg-line { stroke: #b9a1e8; }
 .sg-shot .sg-axis, .sg-shot .sg-average { stroke: rgba(185, 161, 232, .4); }
 .sg-shot .sg-readout { background: #4a3d6e; }
-.sg-shot .sg-scale-top, .sg-shot .sg-scale-avg, .sg-shot .sg-scale-zero { color: #7d6a9e; }
+/* The box's own width is its clock and it has no room for an axis: a dozen
+   pixels tall, three marks would sit on top of one another. */
+.sg-bare .sg-scale-top, .sg-bare .sg-scale-avg, .sg-bare .sg-scale-zero { display: none; }
 
 
 
@@ -3389,10 +3433,13 @@ input[type=range]::-moz-range-thumb {
 	pointer-events: none;
 }
 
+/* One axis, one edge: all three scale marks sit on the left. */
 .sg-scale-top,
-.sg-scale-avg {
+.sg-scale-avg,
+.sg-scale-zero {
 	position: absolute;
 	left: 4px;
+	right: auto;
 	color: #7fae95;
 	font-size: 8px;
 	pointer-events: none;
@@ -5991,6 +6038,12 @@ input[type=range]::-moz-range-thumb {
 	border-radius: 3px;
 }
 
+/* an Empty has no colour: a dashed, hollow swatch reads as "nothing to draw" */
+.add-object-swatch.empty {
+	background: transparent !important;
+	border-style: dashed;
+}
+
 /* inspector cards clip their overflow, so the menu opens inline there */
 .card .add-object {
 	display: block;
@@ -6802,10 +6855,9 @@ input[type=range]::-moz-range-thumb {
 
 /* Keep the timeline focused on the selected workflow.  Pose-correction and
    take-generation controls are useful while authoring motion, but they are
-   noise during blocking and camera work.  The controls stay mounted so the
-   mode switch is lossless; only their always-on chrome is hidden. */
+   noise during blocking and camera work.  The motion clear action stays
+   visible in Stage so a loaded take is always reversible. */
 .app[data-workflow-mode="scene"] .tl-pose-tools,
-.app[data-workflow-mode="scene"] .tl-motion-tools,
 .app[data-workflow-mode="scene"] .take-bar,
 .app[data-workflow-mode="camera"] .tl-pose-tools,
 .app[data-workflow-mode="camera"] .tl-motion-tools,
@@ -9427,6 +9479,23 @@ input[type=range] {
 	width: clamp(220px, calc(50% - 92px), 360px);
 }
 
+/* The floating shell covers the full-bleed viewport with panels. Keep the
+   instructions inside its open stage, clear of the tool rail and dock. */
+.app[data-shell="glass"]:not([data-embed-mode]) .camera-tutorial {
+	top: calc(var(--shell-view-top, 52px) + 12px);
+	left: calc(var(--shell-center-left) + 64px);
+	width: min(430px, calc(100% - var(--shell-center-left) - var(--shell-center-right) - 128px));
+}
+.app[data-shell="glass"][data-tutorial-step="rail"] .camera-tutorial,
+.app[data-shell="glass"] .camera-tutorial[data-previewing="1"] {
+	top: auto;
+	bottom: calc(var(--shell-center-bottom) + 12px);
+}
+.app[data-shell="glass"]:not([data-embed-mode]) .tutorial-cue {
+	left: calc((var(--shell-center-left) + 100% - var(--shell-center-right)) / 2);
+	bottom: calc(var(--shell-center-bottom) + 18px);
+}
+
 .camera-tutorial-steps {
 	display: flex;
 	flex-wrap: wrap;
@@ -10199,4 +10268,36 @@ input[type=range] {
 	margin: 8px 0 0;
 	color: var(--muted);
 }
+
+/* Sculpt mode (#739): the turntable owns the main pane and the shot preview
+   shows the scene, so the Top-View inset has nothing to add. */
+.app[data-workflow-mode="sculpt"] .vp-inset { display: none !important; }
+
+/* The empty turntable says what the mode is waiting for, under the mode pill
+   (the dock floats over the pane's foot). Overlay chrome, like the viewport
+   pills: it never takes the pointer from the orbit. */
+.vp-sculpt-hint {
+	position: absolute;
+	left: 50%;
+	top: calc(2 * var(--sp-2, 12px) + var(--h-control, 28px));
+	z-index: 7;
+	display: grid;
+	gap: var(--sp-1, 4px);
+	max-width: min(420px, calc(100% - 2 * var(--sp-3, 16px)));
+	padding: var(--sp-2, 8px) var(--sp-3, 16px);
+	border-radius: var(--r-2, 6px);
+	background: var(--overlay);
+	color: var(--text-2);
+	font-size: 11px;
+	line-height: 1.45;
+	text-align: center;
+	transform: translateX(-50%);
+	pointer-events: none;
+}
+
+.vp-sculpt-hint strong {
+	color: var(--text-1);
+	font-size: 12px;
+	font-weight: 600;
+}
 }

package/src/theme.js

@@ -2,7 +2,7 @@
 // shell, its regions and body-level popovers all read the same token set.
 export const THEMES = ["dark", "light"];
 export const THEME_KEY = "cozyclay.theme.v1";
-export const DEFAULT_THEME = "dark";
+export const DEFAULT_THEME = "light";
 
 import { useEffect, useState } from "react";
 

package/src/timeline-fps.js

@@ -0,0 +1,13 @@
+// The timeline clock, on its own so the agent sidecar (bin/agent) can read it
+// without importing scenes.js, whose scene-object and motion-trail imports pull
+// in `three` — a devDependency the npm package does not ship
+// (test/verify-package-agent-imports.mjs).
+
+/** v3 and older authored every frame number on ARDY's 20 fps clock; v4 reads
+ * them on the 24 fps production clock. The numbers are MULTIPLIED, never
+ * reinterpreted: a waypoint at frame 40 meant 2.0 s and must still mean 2.0 s,
+ * which is frame 48 — reinterpreting it would silently speed the scene up. */
+export const LEGACY_FRAME_FPS = 20;
+export const TIMELINE_FRAME_FPS = 24;
+export const toTimelineFrame = (frame) =>
+	Math.round((frame * TIMELINE_FRAME_FPS) / LEGACY_FRAME_FPS);

package/src/ui-scrub.js

@@ -28,7 +28,7 @@ export const SCRUB_THRESHOLD_PX = 4;
 
 /** Shift buys a quarter-speed pass for fine detail; Alt keeps its old 0.1x. */
 export const FINE_SCRUB_FACTOR = 0.25;
-export const EXTRA_FINE_SCRUB_FACTOR = 0.1;
+const EXTRA_FINE_SCRUB_FACTOR = 0.1;
 
 /**
  * The meaningful span a full drag sweeps when the field does not name one.
@@ -39,8 +39,8 @@ export const SCRUB_RANGE_STEPS = 100;
 
 /** The span one full `SCRUB_TRAVEL_PX` drag covers for a field. */
 export function scrubRangeFor({ scrubRange, step } = {}) {
-	if (typeof scrubRange === "number" && Number.isFinite(scrubRange) && scrubRange > 0) return scrubRange;
-	const size = typeof step === "number" && Number.isFinite(step) && step > 0 ? step : 1;
+	if (Number.isFinite(scrubRange) && scrubRange > 0) return scrubRange;
+	const size = Number.isFinite(step) && step > 0 ? step : 1;
 	return size * SCRUB_RANGE_STEPS;
 }
 
@@ -95,7 +95,7 @@ export function createScrubGesture({ x, value, step, precision, scrubRange }) {
  * 1.7000000000000002 in the input.
  */
 export function snapScrubValue(value, { step, precision = 2 } = {}) {
-	const size = typeof step === "number" && Number.isFinite(step) && step > 0 ? step : 0;
+	const size = Number.isFinite(step) && step > 0 ? step : 0;
 	const snapped = size > 0 ? Math.round(value / size) * size : value;
 	const digits = Number.isFinite(precision) ? Math.max(0, Math.min(15, Math.round(precision))) : 2;
 	return Number(snapped.toFixed(digits));