cozyclay 2.1.0 → 2.1.1

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"2.1.0\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"94d0d33855916922202e0ff1c4afc9aff0e6db281adae8072ae72da7936dd906\"}","signature":"BDrFE1pch5PcqsC6Q9eeqhgX+hfAdOLbJEbdZGM+upY9ACMIItqHsHEmqan1Qkl1i636NrVs0e0zGH7cVmFPCQ=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"2.1.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"05301230e82860f17fdf3043274840c0f9959ec99907187cb5d516cc937dfabb\"}","signature":"GuUScV2s3XXtftHL6hEMO+nBbLKD37dy3TSdrqeM4mg0+Fm5V+sFbISCkGAMLKyaGkNDCeMUmtNGWsWGENm9Aw=="}

package/dist/index.html

@@ -301,9 +301,9 @@
         .btn, a.card, .seg button, .tutorial-steps li { transition: none; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/landing-BSesrCpL.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/analytics-B41FmPYI.js">
-    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-BlT33CGf.js">
+    <script type="module" crossorigin src="/assets/landing-ChUvB_zL.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/analytics-C9pMpW7s.js">
+    <link rel="modulepreload" crossorigin href="/assets/first-shot-handoff-msLI71g1.js">
   </head>
   <body>
     <header class="site">

package/dist/llms.txt

@@ -11,6 +11,20 @@
 - [Camera control for AI video](https://cozyclay.org/ai-camera-control/): why camera prompts drift and what the models actually accept.
 - [Privacy](https://cozyclay.org/privacy/): analytics and telemetry disclosure.
 
+## Agent loop
+
+1. Install and open the Studio: `npx cozyclay`.
+2. Wait for a live editor: `cclay live status --wait`.
+3. Read before editing: `cclay live inspect --scope scene` or `--scope catalogue`.
+4. Apply one semantic batch with `cclay live arrange-objects`, `arrange-characters`, `frame-shot`, or `patch`.
+5. Verify the result. For a whole shot, use `cclay live verify --targets <id> --checks framing --range whole_clip --visual contact_sheet --out verify.png`.
+6. Use `--strict` when sampled framing findings should make the command fail. A sampled result is evidence for the returned frames, not proof of every frame.
+7. Read the receipt before retrying. `UNCERTAIN_APPLY` means reconcile or inspect first. `STALE_HANDLE` means status and workspace selection again. `NOT_IN_MODE` means switch Storyboard/Animation before using motion tools.
+
+The Studio, MCP server and `cclay live` use the same command contract. `script` can call several tools in one QuickJS transaction for computed layouts. Every authored edit returns a receipt and can be undone.
+
+For source-checkout CI, start the same Studio in owned headless Chrome with `node tools/headless-studio.mjs --project shot.cclayproject --port 5920 --live-port 5924`; then point `COZYCLAY_LIVE_PORT=5924 cclay live ...` at it. The launcher owns the Vite and Chrome children and cleans them up on exit.
+
 ## Source
 
 - GitHub: https://github.com/NomaDamas/CozyClay

package/dist/workflow/index.html

@@ -8,10 +8,10 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-Br-K7Srs.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-jJRBR94Z.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
-    <link rel="modulepreload" crossorigin href="/assets/analytics-B41FmPYI.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-BCWDJB1d.js">
+    <link rel="modulepreload" crossorigin href="/assets/analytics-C9pMpW7s.js">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-DKkpjKBV.js">
     <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-DjJ_cJ2R.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",

package/src/App.jsx

@@ -6,6 +6,7 @@ import { useScenes } from "./domains/scenes.js";
 import { useStage } from "./domains/stage.js";
 import StudioShell from "./shell/StudioShell.jsx";
 import ViewportToolbar from "./shell/ViewportToolbar.jsx";
+import CompositionGuideButton from "./shell/CompositionGuideButton.jsx";
 import { StudioShellContext } from "./shell/studio-shell-context.js";
 
 import {
@@ -275,9 +276,7 @@ import { exportOffscreenVideo } from "./offscreen-export.js";
 import { parseRigNodeId } from "./hierarchy-model.js";
 import { timelineContentExtent } from "./timeline-extent.js";
 import {
-	GUIDE_LABELS,
 	guideGeometry,
-	nextGuideMode,
 	readStoredGuideMode,
 	writeStoredGuideMode,
 } from "./shot-guides.js";
@@ -4219,7 +4218,7 @@ export default function App() {
 		generate: (kind) => void generateI2vMotion(kind),
 		enableShaded: () => runStudioAction("view.setPartColours", { mode: "shaded" }),
 	};
-	const viewLooksActive = gridView || autoColor || partColoursEnabled;
+	const viewLooksActive = gridView || autoColor || partColoursEnabled || guideMode !== "off";
 	const rigSelection = parseRigNodeId(selectedHierarchyId);
 	const isRigSelection = rigSelection !== null;
 	const inspectorHasContent = isSceneSelection || isCameraSelection || isCharacterSelection || isRigSelection
@@ -6857,6 +6856,25 @@ export default function App() {
 			bridgeReady: Boolean(bridge?.ok), busy: storeRef.current.present() !== storeRef.current.objects || Boolean(studioGestureRef.current ||
 				ikBodyDragRef.current || lineDragRef.current || lineDrawRef.current || linePinDragRef.current || live.studioPhysicsRunning || recRef.current) };
 	}
+	function sampleStudioStateAt(frame, current = readStudioState()) {
+		const shot = shotAtFrame(current.shots ?? current.shotDocument?.shots ?? [], frame);
+		const sampledPlayback = sampleAt(playbackScene, shot, frame);
+		const sampledSubject = sampledPlayback.subject;
+		const primaryId = current.activeCharacterId ?? current.characters[0]?.id;
+		const characters = sampledSubject && primaryId
+			? current.characters.map(character => character.id === primaryId ? { ...character, x: sampledSubject.x, z: sampledSubject.z } : character)
+			: current.characters;
+		const sampled = sampledPlayback.camera;
+		if (!sampled) return { ...current, frame, characters, view: { ...current.view, frame } };
+		const position = { x: sampled.pos.x, y: sampled.pos.y, z: sampled.pos.z };
+		const direction = forwardFrom(sampled.yaw, sampled.pitch);
+		return { ...current, frame, characters, view: { ...current.view, frame }, camera: {
+			position,
+			lookAt: { x: position.x + direction.x, y: position.y + direction.y, z: position.z + direction.z },
+			focalMm: fovToFocalMm(sampled.fovDeg * Math.PI / 180, current.filmback.sensorId, current.filmback.aspectRatio),
+			sensorId: current.filmback.sensorId,
+		} };
+	}
 
 	/** The authored stage envelope (key light, environment, filmback) published
 	 * as one body: the live read model first, so the next synchronous read sees
@@ -6994,6 +7012,7 @@ export default function App() {
 	appContext.updatePorts({
 		read: readStudioState, revision: sceneRevisionRef, bounds: studioBounds, commit: commitStudioDraft,
 		operate: operateStudio, undo: () => stepStudioHistory(false), redo: () => stepStudioHistory(true),
+		sampleStateAt: sampleStudioStateAt,
 		history: redo => appContext.historyEntry(redo), finishHistoryGesture: finishStudioHistoryGesture,
 		stepHistory: stepStudioHistory, capture: () => liveQueries.capture_framing_png({}), capturePlan: () => liveQueries.capture_plan_png({}),
 		// One shot frame as raw read-back pixels (rows bottom-up), from the export
@@ -7165,6 +7184,7 @@ export default function App() {
 		fovDeg, shotsDomain, shot, setNonce, workspaceLayout,
 		viewMenuTriggerRef, viewMenuOpen, setViewMenuAnchor, setViewMenuOpen, viewLooksActive,
 		viewMenuAnchor, gridView, setGridView, autoColor, setAutoColor,
+		guideMode,
 		isCharacterSelection, partColoursChoice, embedMode, agentCollapsed, sceneSaveError,
 		studioAgentError, studioAgentMode, setStudioAgentMode, AgentPanel, setAgentCollapsed,
 		buildStudioAgentContext, highlightAgentTargets, generateI2vMotionFromUi, selectedSceneObject, rigSelection,
@@ -7253,6 +7273,7 @@ export default function App() {
 						}
 					}}>
 				<ViewportToolbar />
+				{(embedMode || playgroundMode) && <CompositionGuideButton guideMode={guideMode} onCycle={(mode) => runStudioAction("view.setGuideMode", { mode })} />}
 				{sculptMode && !sculptTarget && (
 					<div className="vp-sculpt-hint" role="status" data-testid="sculpt-empty">
 						<strong>{ko("New sculpt", "새 조형물")}</strong>
@@ -7907,18 +7928,6 @@ export default function App() {
 							<span className="vp-inset-tag vp-shot-preview-tag">
 								<span className="vp-rec-dot" aria-hidden="true" />
 								{ko("Shot", "샷")}
-								<button
-									type="button"
-									className={"vp-guide-cycle" + (guideMode === "off" ? "" : " on")}
-									aria-label={ko("Cycle composition guides", "구도 가이드 전환")}
-									title={ko(GUIDE_LABELS[guideMode].en, GUIDE_LABELS[guideMode].ko) + ko(" · click to cycle", " · 클릭으로 전환")}
-									onClick={() => runStudioAction("view.setGuideMode", { mode: nextGuideMode(guideMode) })}
-								>
-									<svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
-										<path d="M3 3h18v18H3z" />
-										<path d="M9 3v18M15 3v18M3 9h18M3 15h18" />
-									</svg>
-								</button>
 								<button
 									type="button"
 									className="vp-look-through"

package/src/ardy/timeline.jsx

@@ -1863,7 +1863,7 @@ export default function Timeline({
 									{ko("+ Block", "+ 블록")}
 								</button>}
 							</>) : workflowMode === "pose" || ikMode ? (
-								<button
+								selectedMotionSegment ? <button
 									type="button"
 									className="tl-seq-action cut"
 									data-testid="sequencer-cut"
@@ -1871,9 +1871,9 @@ export default function Timeline({
 									onClick={() => handlers.current.onMotionCut?.()}
 								>
 									{ko("Cut", "컷")}
-								</button>
+								</button> : null
 							) : (<>
-								<button
+								{shots.length > 0 && <button
 									type="button"
 									className="tl-seq-action cut"
 									data-testid="sequencer-cut"
@@ -1882,8 +1882,8 @@ export default function Timeline({
 									onClick={() => activeShotForCut && handlers.current.onShotSplit?.(activeShotForCut.id)}
 								>
 									{ko("Cut", "컷")}
-								</button>
-								<button
+								</button>}
+								{cameraBlockIdx != null && <button
 									type="button"
 									className="tl-seq-action rail"
 									data-testid="sequencer-draw-rail"
@@ -1894,8 +1894,8 @@ export default function Timeline({
 									onClick={() => handlers.current.onCameraRailDrawToggle?.()}
 								>
 									{ko("Draw rail", "레일 그리기")}
-								</button>
-								<button
+								</button>}
+								{!shotCutDisabled && <button
 									type="button"
 									className="tl-seq-action"
 									data-testid="sequencer-add-track"
@@ -1904,7 +1904,7 @@ export default function Timeline({
 									onClick={() => handlers.current.onShotCut?.()}
 								>
 									{ko("+ Track", "+ 트랙")}
-								</button>
+								</button>}
 							</>) }
 						</div>
 						<div className="tl-head-group tl-view-tools" role="group" aria-label={ko("Timeline view tools", "타임라인 보기 도구")}>

package/src/panels/PoseImagePanel.jsx

@@ -82,7 +82,7 @@ export default function PoseImagePanel({ hidden, capturePoseImage }) {
 	};
 
 	return (
-		<Foldout hidden={hidden} title={ko("Image from pose", "포즈로 이미지 생성")}>
+		<Foldout hidden={hidden} defaultOpen={false} title={ko("Image from pose", "포즈로 이미지 생성")}>
 			<div className="pose-image" data-testid="pose-image">
 				<div className="pose-image-frame">
 					<div className="pose-image-source" role="radiogroup" aria-label={ko("Frame source", "프레임 시점")}>

package/src/shell/BottomDock.jsx

@@ -482,12 +482,12 @@ function ShotCard() {
 						{ko("Exit", "나가기")}
 						<kbd>Esc</kbd>
 					</button>
-				) : (
+				) : activeShot ? (
 					<button type="button" className="dock-shot-look" aria-pressed="false" onClick={enterShotLook} title={ko("Look through the shot camera (Esc returns)", "샷 카메라 시점으로 보기 (Esc로 복귀)")}>
 						<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1.75 8S4 3.75 8 3.75 14.25 8 14.25 8 12 12.25 8 12.25 1.75 8 1.75 8z M8 6.25a1.75 1.75 0 1 1 0 3.5 1.75 1.75 0 1 1 0-3.5z" /></svg>
 						{ko("Look through", "샷 시점")}
 					</button>
-				)}
+				) : null}
 			</footer>
 		</section>
 	);

package/src/shell/CompositionGuideButton.jsx

@@ -0,0 +1,20 @@
+import { GUIDE_LABELS, nextGuideMode } from "../shot-guides.js";
+import { ko } from "../locale.js";
+
+export default function CompositionGuideButton({ guideMode, onCycle }) {
+	return (
+		<button
+			type="button"
+			className={"vp-guide-cycle vp-embed-guide" + (guideMode === "off" ? "" : " on")}
+			aria-label={ko("Cycle composition guides", "구도 가이드 전환")}
+			aria-pressed={guideMode !== "off"}
+			title={ko(GUIDE_LABELS[guideMode].en, GUIDE_LABELS[guideMode].ko) + ko(" · click to cycle", " · 클릭으로 전환")}
+			onClick={() => onCycle(nextGuideMode(guideMode))}
+		>
+			<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+				<path d="M3 3h18v18H3z" />
+				<path d="M9 3v18M15 3v18M3 9h18M3 15h18" />
+			</svg>
+		</button>
+	);
+}

package/src/shell/ShotPreviewHeader.jsx

@@ -0,0 +1,17 @@
+import { useLayoutEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+export default function ShotPreviewHeader({ name, lens }) {
+	const [host, setHost] = useState(null);
+	useLayoutEffect(() => {
+		setHost(document.querySelector(".vp-shot-preview .vp-shot-preview-tag"));
+	}, []);
+	if (!host) return null;
+	return createPortal(
+		<span className="vp-shot-preview-meta" data-testid="shot-preview-header">
+			<span className="vp-shot-preview-name">{name}</span>
+			<span className="vp-shot-preview-lens">{lens}</span>
+		</span>,
+		host,
+	);
+}

package/src/shell/TopBar.jsx

@@ -124,6 +124,7 @@ function GenerateMotion() {
 							key={action.id}
 							className="menubar-item"
 							data-generate-action={action.id}
+							disabled={Boolean(action.reason)}
 							aria-disabled={action.reason ? "true" : undefined}
 							data-disabled-reason={action.reason || undefined}
 							onClick={() => {

package/src/shell/ViewportToolbar.jsx

@@ -1,6 +1,6 @@
-import { useEffect, useLayoutEffect, useState } from "react";
-import { createPortal } from "react-dom";
+import { useEffect, useState } from "react";
 import { useStudioShell } from "./studio-shell-context.js";
+import ShotPreviewHeader from "./ShotPreviewHeader.jsx";
 import { ko } from "../locale.js";
 import { PRESETS, SHOT_ASPECT_PRESETS } from "../app-stage.jsx";
 import { CAMERA_PRESETS } from "../camera-move.js";
@@ -10,6 +10,7 @@ import { CHARACTER_MODEL_IDS } from "../scenes.js";
 import { elementByPath } from "../studio-elements.js";
 import { saveAutoColor } from "../auto-color.js";
 import { trackFeature } from "../analytics.js";
+import { GUIDE_LABELS, nextGuideMode } from "../shot-guides.js";
 import "./viewport.css";
 
 // G1: the single mode+tool pill. Keys 1-5 and W/E/R are bound in App's
@@ -113,30 +114,13 @@ function MenuItem({ checked, role = "menuitemradio", className = "", children, .
 	);
 }
 
-/** The inset card's header (violet dot, shot name, lens) lives in App's
- * `.vp-shot-preview-tag`; this region only fills in the words it shows. */
-function ShotPreviewHeader({ name, lens }) {
-	const [host, setHost] = useState(null);
-	useLayoutEffect(() => {
-		setHost(document.querySelector(".vp-shot-preview .vp-shot-preview-tag"));
-	}, []);
-	if (!host) return null;
-	return createPortal(
-		<span className="vp-shot-preview-meta" data-testid="shot-preview-header">
-			<span className="vp-shot-preview-name">{name}</span>
-			<span className="vp-shot-preview-lens">{lens}</span>
-		</span>,
-		host,
-	);
-}
-
 export default function ViewportToolbar() {
 	const {
 		workflowMode, selectWorkflowMode, poseRefusal, gizmoMode, setGizmoMode, snapEnabled,
 		setSnapEnabled, preset, applyPreset, cameraPresetId, i2vMotionCameraLocked,
 		runStudioAction, shotAspectKey, fovDeg, shotsDomain, shot, shots, activeShot,
 		setNonce, workspaceLayout, viewMenuTriggerRef, viewMenuOpen,
-		setViewMenuOpen, viewLooksActive, gridView, setGridView,
+		setViewMenuOpen, viewLooksActive, gridView, setGridView, guideMode,
 		autoColor, setAutoColor, isCharacterSelection, partColoursChoice, embedMode,
 		agentCollapsed, addSceneObject, spawnCharacter, characters, flySpeed,
 		ikEditTool, setIkEditTool, showTrails, setShowTrails, motion, setRangePinPartPick,
@@ -515,20 +499,13 @@ export default function ViewportToolbar() {
 							onClick={() => menu.toggle("shading")}
 						>
 							<RailIcon name="shading" />
-							<span className="vp-label">{autoColor ? ko("Auto Color", "자동 색") : ko("Clay Lit", "클레이 조명")}</span>
+							<span className="vp-label">{ko("Clay Lit", "클레이 조명")}</span>
 						</button>
 						{menu.open === "shading" && (
 							<div className="vp-menu" role="menu" aria-label={ko("Shading", "셰이딩")}>
 								<MenuItem checked={!autoColor} onClick={() => { setAutoColorOn(false); menu.close(); }}>
 									{ko("Clay Lit", "클레이 조명")}
 								</MenuItem>
-								<MenuItem
-									checked={autoColor}
-									title={ko("Flat, distinct colour per object — captures include them while on", "오브젝트별 평면 구분 색 — 켜둔 동안 캡처에도 포함됩니다")}
-									onClick={() => { setAutoColorOn(true); menu.close(); }}
-								>
-									{ko("Auto Color", "자동 색")}
-								</MenuItem>
 							</div>
 						)}
 					</div>
@@ -587,6 +564,19 @@ export default function ViewportToolbar() {
 									<span className="view-menu-mark" aria-hidden="true">{autoColor ? "✓" : ""}</span>
 									{ko("Auto Color", "자동 색")}
 								</button>
+								<button
+									type="button"
+									role="menuitemcheckbox"
+									className={"view-menu-item vp-guide-cycle" + (guideMode === "off" ? "" : " active")}
+									aria-checked={guideMode !== "off"}
+									aria-pressed={guideMode !== "off"}
+									title={ko(GUIDE_LABELS[guideMode].en, GUIDE_LABELS[guideMode].ko) + ko(" · click to cycle", " · 클릭으로 전환")}
+									onClick={() => runStudioAction("view.setGuideMode", { mode: nextGuideMode(guideMode) })}
+								>
+									<span className="view-menu-mark" aria-hidden="true">{guideMode !== "off" ? "✓" : ""}</span>
+									{ko("Composition guides", "구도 가이드")}
+									<small>{ko(GUIDE_LABELS[guideMode].en, GUIDE_LABELS[guideMode].ko)}</small>
+								</button>
 								<button
 									type="button"
 									role="menuitemcheckbox"

package/src/shell/viewport.css

@@ -32,6 +32,18 @@
 		color: var(--text-1);
 	}
 	.app[data-embed-mode] .viewport-titlebar { display: none; }
+	.app[data-embed-mode] .vp-embed-guide {
+		position: absolute;
+		top: var(--sp-1);
+		right: var(--sp-1);
+		z-index: 6;
+		padding: var(--sp-1);
+		border-radius: var(--r-2);
+		background: var(--surface-panel);
+		color: var(--text-2);
+	}
+	.app[data-embed-mode] .vp-embed-guide:hover,
+	.app[data-embed-mode] .vp-embed-guide.on { color: var(--select); }
 
 	.viewport-titlebar button { font-family: inherit; }
 	.viewport-titlebar button:focus-visible {

package/src/studio-agent-commands.js

@@ -11,6 +11,7 @@ import { coplanarConflicts } from './coplanar-depth.js';
 import { clampWarning } from './receipt-findings.js';
 import { occludersOf, primarySubjects, sideOfAxis } from './studio-geometry-facts.js';
 import { StudioProtocolError, StudioSchemas, STUDIO_PATCH_KINDS, STUDIO_PATCH_DESCRIPTORS, validateStudioSchema, validateStudioIdentity, validateReceipt, freezeStudioData } from './studio-agent-protocol.js';
+import { sampleContactSheetFrames } from './studio-contact-sheet.js';
 
 const DEG = Math.PI / 180, EPS = 1e-8, CHARACTER_SUPPORT_TOLERANCE = 5e-3;
 const fail = (code, message) => { throw new StudioProtocolError(code, message); };
@@ -399,6 +400,32 @@ export function framingChecks(ids, state, ports) {
   const projected = projectSubject(boxes.flat(), state.camera, focalMmToFov(state.camera.focalMm, state.filmback.sensorId, state.filmback.aspectRatio), state.filmback.aspectRatio).checks;
   return { ...projected, ...sightChecks(subjects, boxes, state.camera.position, state, ports).checks };
 }
+
+/** Framing evidence over explicit timeline samples. The caller supplies the
+ * sampled state so camera keys and animated subject bounds use the same frame.
+ * A sample is evidence for that frame only; it is never advertised as an
+ * all-frame proof. */
+export function sampledFramingChecks(ids, state, ports, frames) {
+  if (!Array.isArray(frames) || !frames.length) fail('INVALID_RANGE', 'Framing sampling needs at least one timeline frame.');
+  if (typeof ports.sampleStateAt !== 'function') fail('CAPABILITY_MISSING', 'This editor cannot sample framing at timeline frames.');
+  const samples = frames.map(frame => {
+    const sampledState = ports.sampleStateAt(frame, state);
+    if (!sampledState) fail('TARGET_NOT_READY', `The editor could not read timeline frame ${frame}.`);
+    const checks = framingChecks(ids, sampledState, ports), codes = [checks.clipped ? 'CLIPPED' : null, checks.behindCamera ? 'BEHIND_CAMERA' : null, checks.occluded ? 'OCCLUDED' : null].filter(Boolean);
+    return { frame, checks, codes };
+  });
+  const sampledChecks = samples.map(({ frame, checks }) => ({ frame, screenFraction: checks.screenFraction, clipped: checks.clipped, behindCamera: checks.behindCamera, occluded: checks.occluded }));
+  const issueFrames = samples.filter(sample => sample.codes.length).map(({ frame, checks, codes }) => ({ frame, codes, screenFraction: checks.screenFraction }));
+  return { ...samples.at(-1).checks, coverage: 'sampled-timeline-subject-bounds-projection', evaluatedFrames: frames.length, sampledFrames: frames, sampledChecks, issueFrames };
+}
+export function sampledFramingResult(args, scene, ports, frameCount, measured, receipt) {
+  const range = args.range === 'whole_clip' ? { startFrame: 0, endFrameExclusive: frameCount } : args.range;
+  if (range.endFrameExclusive > frameCount) fail('INVALID_RANGE', 'Framing verification range exceeds the scene timeline.');
+  const ids = measured ?? (args.targets ?? receipt?.affectedIds ?? []).filter(id => scene.objects.some(o => o.id === id) || scene.characters.some(c => c.id === id));
+  if (!ids.length) return { reason: 'No target is available for sampled framing verification.' };
+  try { return sampledFramingChecks(ids, scene, ports, sampleContactSheetFrames(args.range, frameCount)); }
+  catch (error) { if (!(error instanceof StudioProtocolError)) throw error; return { reason: error.message }; }
+}
 export function frameDraft(command, state, ports) {
   if (state.frameCount <= 0) fail('TARGET_NOT_READY', 'A nonempty timeline is required.');
   const subject = state.characters.find(e => e.id === command.args.subjectIds[0]);

package/src/studio-agent-protocol.js

@@ -277,7 +277,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({
@@ -511,7 +511,10 @@ export function validateStudioCommand(command) {
 	}
 	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";
+		if (args.checks.includes("motion") && args.range === undefined) {
+			args.range = "whole_clip";
+			Object.defineProperty(args, "rangeWasDefaulted", { value: true, enumerable: false });
+		}
 	}
 	return { name: command.name, args };
 }

package/src/studio-app-binding.js

@@ -8,7 +8,7 @@ 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, entityWorldBounds, framingChecks, localTransformReadback, placementChecks, studioObjectCatalogue } from "./studio-agent-commands.js";
+import { createStudioCommandJournal, entityWorldBounds, framingChecks, localTransformReadback, placementChecks, sampledFramingResult, 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";
@@ -293,6 +293,10 @@ export function createStudioAppBinding(ports) {
 					try { result.checks[check] = check === "placement" ? placementChecks(measured, scene, { bounds: ports.bounds }) : 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.");

package/tools/gt-render/browser.mjs

@@ -154,6 +154,29 @@ export async function openStudioClean(cdp, studioUrl) {
 	await loaded;
 }
 
+/** Load a portable project into the same Studio that a user opens. The project
+ * document is seeded before the app bundle runs, so this path exercises the
+ * real scene store and live-control connection instead of a test renderer. */
+export async function openStudioProject(cdp, studioUrl, project) {
+	const origin = new URL(studioUrl).origin;
+	if (!project?.scenesDocument || typeof project.scenesDocument !== "object") throw new Error("headless Studio needs a parsed project with scenesDocument");
+	await cdp.send("Page.enable");
+	await cdp.send("Storage.clearDataForOrigin", { origin, storageTypes: "all" });
+	const scenes = JSON.stringify(project.scenesDocument), name = String(project.name || "Headless Project");
+	const values = [
+		`localStorage.setItem('cozyclay.scenes.v5', ${JSON.stringify(scenes)})`,
+		`localStorage.setItem('cozyclay.project-session.v1', ${JSON.stringify(JSON.stringify({ name, previsMode: project.previsMode || "animation", updatedAt: Date.now() }))})`,
+		project.workflow ? `localStorage.setItem('cozyclay.workflow.v1', ${JSON.stringify(JSON.stringify(project.workflow))})` : null,
+		project.workspaceLayout ? `localStorage.setItem('cozyclay.workspace-layout.v1', ${JSON.stringify(JSON.stringify(project.workspaceLayout))})` : null,
+	].filter(Boolean);
+	const source = `${values.join("; ")};`;
+	await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+	const loaded = cdp.once("Page.loadEventFired");
+	await cdp.send("Page.navigate", { url: studioUrl });
+	await loaded;
+	await waitFor("Studio canvas", async () => cdp.evaluate("Boolean(document.querySelector('canvas'))"), { timeoutMs: 60000 });
+}
+
 export async function terminateAll(children) {
 	await Promise.allSettled(children.splice(0).reverse().map((child) => terminateOwned(child)));
 }

package/tools/headless-studio.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Start the real CozyClay Studio in an owned headless Chrome process.
+ *
+ * This is intentionally a source-checkout tool. It starts the same dev server,
+ * seeds a portable .cclayproject into the browser's storage before the app
+ * loads, and leaves the live hub available to `cclay live` or an MCP client.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnOwned, terminateOwned } from "./process-supervisor.mjs";
+import { openStudioProject, startChrome, waitFor } from "./gt-render/browser.mjs";
+import { readProjectDocument } from "../src/project.js";
+
+const ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const usage = `headless-studio - start the real Studio without a visible tab
+
+  node tools/headless-studio.mjs --project shot.cclayproject
+
+Options:
+  --project <file>   portable .cclayproject to load (required)
+  --port <port>      Vite/Studio port (default 5920)
+  --live-port <port> live hub port (default 5924)
+  --cdp-port <port>  Chrome DevTools port (default 9320)
+`;
+
+function value(argv, name, fallback = undefined) {
+	const index = argv.findIndex((arg) => arg === name || arg.startsWith(`${name}=`));
+	if (index < 0) return fallback;
+	const arg = argv[index];
+	return arg.includes("=") ? arg.slice(name.length + 1) : argv[index + 1];
+}
+function port(argv, name, fallback) {
+	const parsed = Number(value(argv, name, fallback));
+	if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) throw new Error(`${name} must be an integer in 1..65535`);
+	return parsed;
+}
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) { console.log(usage); process.exit(0); }
+const projectPath = value(argv, "--project");
+if (!projectPath) { console.error(usage); process.exit(2); }
+const projectRaw = readFileSync(resolve(projectPath), "utf8");
+const parsed = readProjectDocument(projectRaw);
+if (!parsed.ok) throw new Error(`Cannot load project: ${parsed.reason}`);
+const studioPort = port(argv, "--port", 5920);
+const livePort = port(argv, "--live-port", 5924);
+const cdpPort = port(argv, "--cdp-port", 9320);
+const children = [];
+const cleanups = [];
+let cdp = null;
+let shuttingDown = false;
+const shutdown = async (code = 0) => {
+	if (shuttingDown) return;
+	shuttingDown = true;
+	try { cdp?.close(); } catch { /* already closed */ }
+	for (const cleanup of cleanups.splice(0).reverse()) { try { cleanup(); } catch { /* best effort */ } }
+	await Promise.allSettled(children.reverse().map((child) => terminateOwned(child)));
+	process.exitCode = code;
+};
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void shutdown(128 + (signal === "SIGINT" ? 2 : 15)); });
+
+let dev = null;
+try {
+	dev = spawnOwned(process.execPath, [join(ROOT, "tools/dev-full.mjs"), "--host", "127.0.0.1", "--port", String(studioPort)], {
+		cwd: ROOT,
+		env: { ...process.env, COZYCLAY_LIVE_PORT: String(livePort) },
+		stdio: ["ignore", "inherit", "inherit"],
+	});
+	children.push(dev);
+	await waitFor("Studio server", async () => (await fetch(`http://127.0.0.1:${studioPort}/app/`)).ok, { child: dev });
+	cdp = await startChrome({ port: cdpPort, children, cleanups });
+	await openStudioProject(cdp, `http://127.0.0.1:${studioPort}/app/`, parsed.project);
+	console.log(JSON.stringify({ ok: true, studio: `http://127.0.0.1:${studioPort}/app/`, livePort, cdpPort, project: parsed.project.name, warnings: parsed.warnings }, null, 2));
+	await new Promise((resolve) => {
+		const done = () => resolve();
+		dev.once("exit", done);
+		if (dev.exitCode !== null || dev.signalCode !== null) done();
+	});
+	await shutdown(dev.exitCode ?? 1);
+} catch (error) {
+	console.error(`headless Studio: ${error?.message || error}`);
+	await shutdown(1);
+}