cozyclay 3.0.2 → 3.1.0

package/src/shell/preferences.css

@@ -203,8 +203,7 @@
 .v2-preferences .v2-preferences__select:focus-visible,
 .v2-preferences .v2-preferences__toggle:focus-visible,
 .v2-preferences .v2-preferences__primary-button:focus-visible,
-.v2-preferences .v2-preferences__reset:focus-visible,
-.v2-preferences .v2-preferences__help button:focus-visible {
+.v2-preferences .v2-preferences__reset:focus-visible {
 	outline: none;
 	box-shadow: var(--prefs-focus-ring, 0 0 0 1px var(--select, #e8a33d));
 }
@@ -506,36 +505,6 @@
 	font: 500 var(--prefs-secondary-size, 11px) var(--mono, 'JetBrains Mono');
 }
 
-.v2-preferences .v2-preferences__help {
-	padding-top: var(--sp-3, 16px);
-}
-
-.v2-preferences .v2-preferences__help h4 {
-	margin: 0 0 var(--sp-1, 8px);
-	color: var(--text-3, #636369);
-	font-size: var(--prefs-secondary-size, 11px);
-	font-weight: 500;
-	letter-spacing: 0;
-	text-transform: none;
-}
-
-.v2-preferences .v2-preferences__help button {
-	min-height: var(--h-control, 28px);
-	padding: 0 var(--sp-2, 12px);
-	border: 0;
-	border-radius: var(--r-1, 4px);
-	background: var(--field-fill, var(--surface-raised, #1e1e21));
-	color: var(--text-2, #9b9ba1);
-	font: inherit;
-	font-size: var(--prefs-secondary-size, 11px);
-	cursor: pointer;
-}
-
-.v2-preferences .v2-preferences__help button:hover {
-	background: var(--surface-raised, #1e1e21);
-	color: var(--text-1, #e4e4e7);
-}
-
 .v2-preferences .v2-preferences__motion-setup {
 	max-width: var(--prefs-control-width, 240px);
 	display: grid;

package/src/shell/shell.css

@@ -24,6 +24,9 @@
 		--shell-center-left: calc(var(--shell-left) + var(--shell-gap) * 2);
 		--shell-center-right: calc(var(--shell-right) + var(--shell-gap) * 2);
 		--shell-center-bottom: calc(var(--shell-dock) + var(--shell-status-h) + var(--shell-dock-bottom) + var(--shell-gap));
+		/* Top edge of the open stage: the cut-out the frame mask leaves under the
+		   top bar (.workspace::after). */
+		--shell-stage-top: calc(var(--shell-gap) * 2 + 40px);
 		/* The shot card's picture. The slot is the room the card leaves between
 		   its 48px head and the 84px of ratios + footer under it; the picture is
 		   the shot aspect fitted into that slot and centred in it, so the stage
@@ -242,7 +245,7 @@
 		   this frame through their glass, and on the darker --surface-0 they
 		   went a step darker than designed. */
 		background: var(--shell-frame, var(--surface-panel));
-		--shell-view-top: calc(var(--shell-gap) * 2 + 40px);
+		--shell-view-top: var(--shell-stage-top);
 		--shell-cut-w: calc(100% - var(--shell-center-left) - var(--shell-center-right));
 		--shell-view-h: max(0px, calc(100% - var(--shell-view-top) - var(--shell-center-bottom)));
 		--shell-shot-w: var(--shot-pic-w);
@@ -268,6 +271,20 @@
 	}
 	.app[data-dock-tab="assets"]:not([data-embed-mode]) .workspace::after,
 	.app[data-shot-look]:not([data-embed-mode]) .workspace::after { --shell-shot-w: 0px; --shell-shot-h: 0px; }
+	/* Look through: the panels and the frame mask cover the canvas outside the
+	   open stage, and inside it the tool rails (44px, a gutter off each side,
+	   glass.css) and the top-centre exit pill (styles.css) float over it. The
+	   shot pane is the open stage less those bands, the same on both sides so
+	   its centre is the stage centre. DualRender fits the shot aspect into
+	   this pane, centred, with bars (fitAspect); the gizmo and the guides map
+	   onto the same rect. Drawn under the panels or the rails, the frame lost
+	   picture the export keeps. */
+	.app[data-shot-look]:not([data-embed-mode]) .vp-main,
+	.app[data-shot-look]:not([data-embed-mode]) .shot-guides.lookthrough {
+		--shot-look-x: calc(var(--shell-gap) * 2 + 44px);
+		--shot-look-y: 36px;
+		inset: calc(var(--shell-stage-top) + var(--shot-look-y)) calc(var(--shell-center-right) + var(--shot-look-x)) calc(var(--shell-center-bottom) + var(--shot-look-y)) calc(var(--shell-center-left) + var(--shot-look-x));
+	}
 	.app[data-dock-tab="assets"]:not([data-embed-mode]) .vp-shot-preview,
 	.app[data-dock-tab="assets"]:not([data-embed-mode]) .shell-camera-splitter { display: none; }
 

package/src/shell/studio-shell-context.js

@@ -1,4 +1,5 @@
 import { createContext, useContext } from "react";
+import { playbackFrame, usePlaybackSnapshot } from "../motion/playback-frame-store.js";
 
 // App owns the document/domain wiring. Region components consume this one
 // render snapshot and call its named actions; they never acquire domain state
@@ -20,3 +21,7 @@ export const StudioShellContext = createContext(null);
 export function useStudioShell() {
 	return useContext(StudioShellContext);
 }
+
+export function useStudioPlaybackFrame() {
+	return usePlaybackSnapshot(playbackFrame);
+}

package/src/shot-frame.js

@@ -0,0 +1,26 @@
+// Shot framing: one rule for every surface that shows the shot camera.
+//
+// The frustum is the shot camera's pose, its vertical FOV (camera.fov, the
+// value a shot stores as fovDeg) and the shot aspect. The aspect only changes
+// the horizontal extent, about the optical axis: a wider ratio extends the
+// sides, a narrower one crops them, and the picture centre never moves. The
+// exports render exactly that (CaptureRig: aspect = output width / height,
+// fov untouched). The focal length shown for a ratio is that FOV read on the
+// ratio's gate (shot.js usedSensorHeightMm), so it is a readout, not the
+// invariant.
+//
+// On screen the frame is the largest centred rect of the shot aspect inside
+// the pane, with bars around it. The dock preview pane is the card's picture
+// slot; the Look through pane is the open stage between the panels (shell.css
+// .vp-main under [data-shot-look]), never the whole canvas under them.
+
+/** largest centred sub-rect of `rect` with the given aspect */
+export function fitAspect(rect, aspect) {
+	let w = rect.w;
+	let h = w / aspect;
+	if (h > rect.h) {
+		h = rect.h;
+		w = h * aspect;
+	}
+	return { x: rect.x + (rect.w - w) / 2, y: rect.y + (rect.h - h) / 2, w, h };
+}

package/src/stage-canvas-rigs.jsx

@@ -5,13 +5,14 @@ import { aimAt } from "./controls.jsx";
 import { SUBJECT_HEIGHT_M } from "./shot.js";
 import { shotAtFrame } from "./cuts.js";
 import { sampleAt } from "./sample-at.js";
+import { playbackProbe, probeVisibility } from "./motion/playback-probe.js";
 import { RENDER_ACTIVITY_EVENT } from "./use-render-activity.js";
 import { PRESETS, editorFrameForSubject } from "./stage-startup-defaults.js";
 
 /** Selection marker for the picked cast member: a Unity-style XYZ tripod
  * plus a ground ring at the feet. X/Z arrows also drag the character on the
  * floor (Y is display-only — characters stand on the deck). */
-export function ShotRig({ preset, nonce, fovDeg, charA, charB, showB, probeX, probeZ, camRef, look, onMetrics, appliedPresetRef, lastPosRef }) {
+export function ShotRig({ preset, nonce, fovDeg, charA, charB, showB, probe: playbackProbeInput = {}, camRef, look, onMetrics, appliedPresetRef, lastPosRef }) {
 	useEffect(() => {
 		const cam = camRef.current;
 		if (!cam) return;
@@ -65,13 +66,11 @@ export function ShotRig({ preset, nonce, fovDeg, charA, charB, showB, probeX, pr
 	useFrame(() => {
 		const cam = camRef.current;
 		if (!cam) return;
-		let visible = false;
-		for (const y of [0.1, SUBJECT_HEIGHT_M * 0.94]) {
-			// During motion playback the probe follows the played root, so the
-			// "subject out of frame" caption stays honest.
-			probe.current.set(probeX ?? charA.x, y, probeZ ?? charA.z).project(cam);
-			if (probe.current.z < 1 && Math.abs(probe.current.x) <= 1 && Math.abs(probe.current.y) <= 1) visible = true;
-		}
+		// During motion playback the probe follows the played root, so the
+		// "subject out of frame" caption stays honest.
+		const frame = playbackProbeInput.frameRef?.current ?? 0;
+		const current = playbackProbe(playbackProbeInput, frame, charA);
+		const visible = probeVisibility(probe.current, cam, current, SUBJECT_HEIGHT_M);
 		const previous = lastMetrics.current;
 		if (
 			Math.abs(previous.x - cam.position.x) +

package/src/stage-characters.jsx

@@ -8,12 +8,38 @@ import { isProxyFigure } from "./scenes.js";
 import { applyPartColours } from "./part-colours.js";
 import { applyHipsOffset, applyPose, primeBindPose } from "./poses.js";
 import { REST_BONES } from "./stage-startup-defaults.js";
+import { playbackFrame, usePlaybackSnapshot } from "./motion/playback-frame-store.js";
+import { placementAt } from "./root-path.js";
+import { shotAtFrame } from "./cuts.js";
+import { sampleAt } from "./sample-at.js";
 
 // Memoized: unchanged cast members skip re-rendering on every playhead tick.
 export const Character = memo(function Character(props) {
 	return isProxyFigure(props) ? <ProxyFigure {...props} /> : <RiggedCharacter {...props} />;
 });
 
+export const PlaybackCharacter = memo(function PlaybackCharacter({
+	entry,
+	clip,
+	shots,
+	...props
+}) {
+	const frame = usePlaybackSnapshot(playbackFrame);
+	const placement = placementAt(entry, frame, {
+		shotAt: (at) => shotAtFrame(shots, at),
+		takeRoot: clip ? sampleAt({ frameCount: clip.frames, motion: clip }, null, frame).subject : null,
+	});
+	return (
+		<Character
+			{...props}
+			position={[placement.x, entry.y ?? 0, placement.z]}
+			rot={placement.rot}
+			pose={clip ? null : (placement.pose ?? props.pose)}
+			posture={placement.posture}
+		/>
+	);
+});
+
 const RiggedCharacter = memo(function RiggedCharacter({ url, position, rot, tint, pose, scale = 1, onRig, pickId, partColoursEnabled = false, partColoursMode = "shaded" }) {
 	const fbx = useFBX(url);
 	const model = useMemo(() => {

package/src/stage-gizmo.js

@@ -0,0 +1,43 @@
+import { placementAt } from "./root-path.js";
+import { shotAtFrame } from "./cuts.js";
+
+export function characterGizmoView({ selected, characters, activeCharacterId, activeCharacter, motion, shots, activeId, frame }) {
+	if (!selected) return null;
+	const entry = characters.find((item) => item.id === activeId);
+	if (!entry || entry.hidden) return null;
+	const hasTake = activeId === activeCharacterId ? Boolean(motion) : Boolean(activeCharacter.sessionMotion);
+	const placement = hasTake ? entry : placementAt(entry, frame, { shotAt: (at) => shotAtFrame(shots, at) });
+	return { position: [placement.x, entry.y ?? 0, placement.z], rot: placement.rot };
+}
+
+export function characterGizmoObject(gizmoView, entry) {
+	if (!gizmoView) return null;
+	return {
+		id: "__character__",
+		x: gizmoView.position[0],
+		y: gizmoView.position[1],
+		z: gizmoView.position[2],
+		height: 1.15,
+		footprint: { width: 0.6, depth: 0.6 },
+		rotY: gizmoView.rot ?? entry?.rot ?? 0,
+		scaleX: entry?.scale ?? 1,
+		scaleY: entry?.scale ?? 1,
+		scaleZ: entry?.scale ?? 1,
+	};
+}
+
+export function playbackSceneWithTrack(base, subjectTrack, followTrack) {
+	return { ...base, subjectTrack, cameraTrack: followTrack };
+}
+
+export function followCameraActive(mode, track, frame, preview, ikMode, waypointMode, posing) {
+	return mode !== "keys" && Boolean(track?.[frame]) && (preview || (!ikMode && !waypointMode && !posing));
+}
+
+export function updateShotMetrics({ position, visible, playing, setCameraPos, setSubjectVisible, cameraRef, visibleRef }) {
+	cameraRef.current = { x: position.x, y: position.y, z: position.z };
+	if (!playing) setCameraPos((prev) => Math.abs(prev.x - position.x) + Math.abs(prev.y - position.y) + Math.abs(prev.z - position.z) > 1e-4
+		? { x: position.x, y: position.y, z: position.z } : prev);
+	visibleRef.current = visible;
+	if (!playing) setSubjectVisible((prev) => (prev === visible ? prev : visible));
+}

package/src/stage-labels-ko.js

@@ -119,9 +119,6 @@ export const SCENE_RENDERER_LABELS_KO = new Map([
 	["cylinder", ko("cylinder", "원기둥")],
 	["cone", ko("cone", "원뿔")],
 	["plane", ko("plane", "평면")],
-	["chair", ko("chair", "의자")],
-	["car", ko("car", "자동차")],
-	["aircraft", ko("aircraft", "비행기")],
 	[CUTOUT_KIND, ko("cutout", "컷아웃")],
 	[MESH_KIND, ko("Mesh", "모델")],
 	["sculpt", ko("Sculpt", "조형")],
@@ -134,9 +131,6 @@ export const SCENE_OBJECT_NAME_LABELS_KO = new Map([
 	["Cylinder", ko("Cylinder", "원기둥")],
 	["Cone", ko("Cone", "원뿔")],
 	["Plane", ko("Plane", "평면")],
-	["Chair", ko("Chair", "의자")],
-	["Car", ko("Car", "자동차")],
-	["Plane (aircraft)", ko("Plane (aircraft)", "비행기")],
 	["Mesh", ko("Mesh", "모델")],
 	["Model", ko("Model", "모델")],
 ]);

package/src/stage-startup-defaults.js

@@ -32,16 +32,10 @@ export const SHOT_ASPECT_PRESETS = Object.freeze({
 	"12:7": Object.freeze({ label: "12:7", aspect: SHOT_ASPECT_RATIOS["12:7"], width: 1536, height: 896, title: "12:7 video-inbetweener ratio" }),
 	"fal 480P": Object.freeze({ label: "fal 480P", aspect: SHOT_ASPECT_RATIOS["fal 480P"], width: 1664, height: 960, title: "Fal H3 480P canvas (832x480)" }),
 });
-// Pre-generated clip shipped with the build so a bridge-less session (a hosted
-// static demo, or `npm run dev:ui`) still shows real generated motion.
-// Root-absolute on purpose: the studio is served from "/app/" while these
-// public files stay at the site root, so a page-relative path would resolve
-// to "/app/models/..." and 404. Vite's base is "/" (own apex domain), so a
-// leading slash is now the correct — and only — form that works from both
-// the dev server and the built site.
 // Per-character rig model: the stage entry's `model` is the FBX file stem in
-// public/models AND the wire rig name sent to ARDY, so mesh and export can
-// never drift apart.
+// public/models. Root-absolute on purpose: the studio is served from "/app/"
+// while public files stay at the site root, so a page-relative path would
+// resolve to "/app/models/..." and 404.
 export const characterModelUrl = (model) => `/models/${model}.fbx`;
 
 /** Shipped rig names as the operator says them, not as the files spell them. */

package/src/starter-scenes.js

@@ -1,15 +1,9 @@
-// Starter scenes ship inside the build (public/scenes/) so `npx cozyclay`
-// can open the same set the landing-page playground uses. The landing page
-// and the launcher refer to them by id; the studio resolves the id to the
-// same-origin file.
+// Starter scenes ship inside the build (public/scenes/<id>.cclayproject) and
+// are referred to by id: `npx cozyclay --scene <id>`, `?scene=<id>` and the
+// chooser's template cards. The build ships none today; an unknown id resolves
+// to null, and the studio ignores it.
 
-export const STARTER_SCENES = Object.freeze([
-	Object.freeze({
-		id: "city-block",
-		name: "City Block",
-		blurb: "The set from the cozyclay.org tutorial: an alley, parked cars, one character mid-walk.",
-	}),
-]);
+export const STARTER_SCENES = Object.freeze([]);
 
 function starterSceneById(id) {
 	return STARTER_SCENES.find((scene) => scene.id === id) ?? null;

package/src/studio-agent-commands.js

@@ -91,9 +91,9 @@ function basisAxis(spec, reference, state) {
 }
 function support(spec, state) {
   const id = spec.onObject ?? (typeof spec.support === 'object' ? spec.support.objectId : null);
-  if (!id) return { y: state.floorY, label: 'floor' };
+  if (!id) return { y: state.floorY ?? 0, label: 'floor' }; // live app state carries no floorY; the 3.0 floor is flat at 0
   const object = entityById(state, id);
-  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'car', 'small-plane', 'empty', 'sculpt'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS || isEffectivelyHidden(object, state.objects, state.characters)) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
+  if (!object.renderer || object.renderer === 'cutout' || ['sphere', 'capsule', 'cone', 'empty', 'sculpt'].includes(object.renderer) || object.path || object.attach || Math.abs(object.rotX) > EPS || Math.abs(object.rotZ) > EPS || isEffectivelyHidden(object, state.objects, state.characters)) fail('TARGET_NOT_READY', 'Support must be a stationary solid upright surface.');
   return { y: object.y + supportHeightForObject(object) * object.scaleY, label: `object:${id}`, object };
 }
 function facingYaw(spec, entity, state) {

package/src/studio-agent-protocol.js

@@ -8,7 +8,6 @@ import { wrongType, unknownField, missingField, arrayRefusal, duplicateItem, str
 // 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"];
 
-export const STUDIO_PROTOCOL_VERSION = "studio-agent-v1";
 // Sized for the compact index of up to 400 entities (~100 bytes each) beside
 // 24 detailed rows; a small scene stays far below it.
 export const STUDIO_CONTEXT_MAX_BYTES = 64 * 1024;
@@ -30,7 +29,6 @@ export const STUDIO_TOOLS = Object.freeze(Object.keys(STUDIO_TOOL_LABELS));
 /** One patch target kind per authored commit domain: character→cast,
  * 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 { STUDIO_ERROR_CODES, refusalCode };
 export const STUDIO_VARIANTS = freezeStudioData({
 	selectionKinds: ["scene", "object", "character", "rig", "camera"], modes: ["scene", "pose", "camera", "motion"], shotModes: ["keys", "follow", "rail"],
@@ -47,7 +45,6 @@ export class StudioProtocolError extends Error {
 	constructor(code, message, details = {}) { super(message); this.name = "StudioProtocolError"; this.code = code; this.details = details; }
 	toJSON() { return { code: this.code, message: this.message, ...(Object.keys(this.details).length ? { details: this.details } : {}) }; }
 }
-export const studioError = (code, message, details) => ({ ok: false, error: new StudioProtocolError(code, message, details).toJSON() });
 export const utf8ByteLength = (text) => new TextEncoder().encode(text).byteLength;
 export function freezeStudioData(value) {
 	if (value && typeof value === "object" && !Object.isFrozen(value)) { for (const child of Object.values(value)) freezeStudioData(child); Object.freeze(value); }
@@ -302,8 +299,7 @@ const receiptVariants = {
 	installed: object({ ...authoredReceipt, status: literal("installed"), jobId: id, artifactId: id, installed, verification }, {
 		// Who accepted an unverified take: the user's explicit button, or the
 		// runtime's advisory install policy. Exactly these two may admit one.
-		mutated: literal(true), explicitUnverifiedAcceptance: bool, acceptance: literal("advisory-policy"),
-		repairs: object({ autoPhysicsInvocations: integer(0, 1), fixCollisionsInvocations: integer(0, 1), remaining: integer(0, 2) }), ...batchDetails,
+		mutated: literal(true), explicitUnverifiedAcceptance: bool, acceptance: literal("advisory-policy"), ...batchDetails,
 	}),
 	undone: object({ ...authoredReceipt, status: literal("undone"), undoneReceiptId: id, restoredTargets: array(guardSchema, 100, 1) }, { mutated: literal(true), ...batchDetails }),
 };
@@ -382,7 +378,6 @@ export function validateStudioSchema(schema, value, code = "INVALID_ARGUMENT", p
 	throw new Error("Unsupported internal Studio schema.");
 }
 export const validateStudioIdentity = value => validateStudioSchema(identity, value, "INVALID_IDENTITY");
-export const validateFrameRange = value => freezeStudioData(validateStudioSchema(range, value, "INVALID_RANGE"));
 
 export function mandatoryStudioTargetIds(context) {
 	return [...new Set([
@@ -544,6 +539,6 @@ export function validateReceipt(value) {
 		if (previous !== frameCount || r.installed.durationSeconds !== frameCount / 24 || r.verification.range.startFrame !== 0 || r.verification.range.endFrameExclusive !== frameCount || r.verification.evaluatedFrames > frameCount) fail("INVALID_RECEIPT", "Installed schedule and verification coverage disagree.");
 		if (r.verification.status === "verified" && r.verification.evaluatedFrames !== frameCount) fail("INVALID_RECEIPT", "Verified motion requires whole-clip coverage.");
 		if (r.verification.status === "unverified" && r.explicitUnverifiedAcceptance !== true && r.acceptance !== "advisory-policy") fail("INVALID_RECEIPT", "Unverified installation requires explicit user or advisory-policy acceptance.");
-	} else if (r.installed || r.verification || (r.jobId && !["started", "completed"].includes(r.status)) || r.artifactId || r.repairs || r.explicitUnverifiedAcceptance !== undefined) fail("INVALID_RECEIPT", "Installation evidence is exclusive to installed receipts.");
+	} else if (r.installed || r.verification || (r.jobId && !["started", "completed"].includes(r.status)) || r.artifactId || r.explicitUnverifiedAcceptance !== undefined) fail("INVALID_RECEIPT", "Installation evidence is exclusive to installed receipts.");
 	return freezeStudioData(r);
 }

package/src/studio-app-binding.js

@@ -1,6 +1,7 @@
 // The Studio's agent binding: inspection, admission and the agent's commands
 // over the editor's native state. App.jsx supplies the ports (reads, commits,
 // history, the action registry); this module owns no React or renderer state.
+import { taskTargetPorts } from "./bus-task-targets.js";
 import { createCommandBus } from "./command-bus.js";
 import { readElementDocument, elementReadback, elementPatchArgs, elementTarget, elementPatchReceipt } from "./commands/elements.js";
 import { physicsKeyStamp } from "./motion/physics-review.js";
@@ -220,15 +221,14 @@ export function createStudioAppBinding(ports) {
 			}, recordAction: (...args) => ports.recordAction(...args), beginAction: (...args) => ports.beginAction(...args),
 			readback: actionReadback, remember, receipt: id => receipts.get(id), isRetained: receipt => ports.isRetained(receipt),
 			canUndo: receipt => ports.canUndo(receipt), undo: () => ports.undo(), redo: () => ports.redo(),
-			history: redo => ports.history?.(redo), finishHistoryGesture: () => ports.finishHistoryGesture?.(),
-			readTarget: id => { refresh(); return tokens.get(id)?.token; },
+			history: redo => ports.history?.(redo), finishHistoryGesture: () => ports.finishHistoryGesture?.(), readTarget: id => { refresh(); return tokens.get(id)?.token; }, ...taskTargetPorts(ports),
 			captureToasts: listener => ports.captureToasts?.(listener), showRefusal: message => ports.showRefusal?.(message), emit: event => ports.emitCommandEvent?.(event),
 		} });
 		return actionBus;
 	}
 	function runAction(request, args) {
 		const { name: _name, args: _args, ...options } = request;
-		const result = commandBus().run(args.action, args.args, { ...options, origin: "agent", turnId: request.turnId, confirmationToken: args.confirmationToken ?? request.confirmationToken });
+		const result = commandBus().run(args.action, args.args, { ...options, origin: "agent", turnId: request.turnId, taskId: request.taskId, confirmationToken: args.confirmationToken ?? request.confirmationToken });
 		const answer = receipt => receipt.nextHost ? { ...receipt, host: receipt.nextHost } : receipt;
 		return result?.then ? result.then(answer) : answer(result);
 	}

package/src/studio-elements.js

@@ -34,7 +34,7 @@ const entries = [
 	
 	{ 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", "light", "effect", "text"], note: "light is made from catalogue kind point-light or spot-light; effect (smoke, fire, rain, trail...) from kind effect; text (words, a sign, a logo) from kind text" },
+	{ path: "object.renderer", type: "enum", persisted: true, undoDomain: "objects", normalizer: "normalizeSceneObject", enum: ["cube", "sphere", "capsule", "cylinder", "cone", "plane", "empty", "light", "effect", "text"], note: "light is made from catalogue kind point-light or spot-light; effect (smoke, fire, rain, trail...) from kind effect; text (words, a sign, a logo) from kind text" },
 	{ 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 }, 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 } },

package/src/studio-error-codes.js

@@ -4,7 +4,7 @@ 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", "INTERNAL_ERROR",
+	"VERIFICATION_FAILED", "REPAIR_REGRESSED", "CANCELLED", "UNCERTAIN_APPLY", "UNDO_CONFLICT", "CONFIRMATION_REQUIRED", "TIMEOUT", "UNDO_EXPIRED", "INTERNAL_ERROR", "SCOPE_DENIED", "SCOPE_BUSY",
 ]);
 /**
  * A refusal's code. A protocol error carries its own; a JavaScript runtime error (TypeError, ReferenceError, RangeError,

package/src/studio-motion-visual.js

@@ -9,7 +9,7 @@ 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 { cameraAt, 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";
@@ -92,14 +92,14 @@ function viewSheet(args, r, { s, frames, span, grid, picks, ports, added }) {
 	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 sheet = buildContactSheet(cells, ({ cam: view, frame }) => {
+		const cam = cameraAt(view, frame), 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 views = cameras.map(cam => ({ name: cam.name, eye: round2(cam.eye), target: round2(cam.target), ...(cam.ride ? { rides: "focus" } : {}) }));
 	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];

package/src/styles/themes.css

@@ -13,6 +13,16 @@
 		--float-head: 48px;
 		--sans: -apple-system, BlinkMacSystemFont, "SF Pro Text", "IBM Plex Sans", "Pretendard", "Noto Sans KR", "Apple SD Gothic Neo", "Malgun Gothic", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
 		--mono: "SF Mono", ui-monospace, "JetBrains Mono", SFMono-Regular, Menlo, Consolas, monospace;
+		/* Shell popovers (project menu, dropdowns, Outliner context menu): one
+		   solid surface and one layer above every panel and rail. They are
+		   portaled to <body> and exclusive (src/popover.js), so the open one is
+		   always on top. The top bar's menus use the same layer. */
+		--z-popover: 90;
+		--popover-surface: var(--surface-raised);
+		--popover-border: var(--row-divider);
+		--popover-radius: var(--r-2, 6px);
+		--popover-blur: none;
+		--popover-shadow: 0 8px 24px rgba(0,0,0,.45);
 	}
 
 	/* Dark: the v2 surfaces with a deep clay-orange accent and shaded panels. */
@@ -73,6 +83,9 @@
 		--surface-bar: #f4f4f6;
 		--surface-panel: #f7f7f9;
 		--surface-raised: #ffffff;
+		--popover-surface: rgba(255,255,255,.96);
+		--popover-blur: blur(24px) saturate(1.6);
+		--popover-shadow: 0 10px 30px rgba(30,32,40,.16), 0 1px 3px rgba(30,32,40,.08);
 		--surface-active: #e4e4e9;
 		--field: #ececf0;
 		--field-deep: #e6e6eb;