cozyclay 3.0.3 → 3.1.1

package/src/shell/BottomDock.jsx

@@ -1,12 +1,13 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import { useStudioShell } from "./studio-shell-context.js";
+import { useStudioPlaybackFrame, useStudioShell } from "./studio-shell-context.js";
 import { logStore } from "./log-store.js";
 import "./dock.css";
 import LibrarySlot from "./LibrarySlot.jsx";
 import BoardSlot from "./BoardSlot.jsx";
+import LensScrub from "./lens-scrub.jsx";
 import { ko } from "../locale.js";
 import Timeline, { timelineTake } from "../motion/timeline.jsx";
-import { DEFAULT_PLAYBACK_SPEED, SHOT_ASPECT_PRESETS, sceneObjectNameDisplayKo } from "../app-stage.jsx";
+import { DEFAULT_PLAYBACK_SPEED, sceneObjectNameDisplayKo } from "../app-stage.jsx";
 
 import { trackFeature } from "../analytics.js";
 import { defaultRailRange } from "../camera-rail-schedule.js";
@@ -67,11 +68,11 @@ function dockTabsFor(previsMode) {
  * switching keeps the Sequencer's scroll and zoom and the Library's folder
  * and search. Any stored tab the mode does not offer opens its first tab. */
 export default function BottomDock({ tab: requestedTab = "animation", onTabChange, embedded = false }) {
-	const { previsMode } = useStudioShell();
+	const { previsMode } = useStudioShell(), liveFrame = useStudioPlaybackFrame();
 	const tabs = embedded ? dockTabsFor(null) : dockTabsFor(previsMode);
 	const tab = tabs.some((entry) => entry.key === requestedTab) ? requestedTab : tabs[0].key;
 	const {
-		tlFrame, motion, waypointMode, craneSelectedIndex,
+		motion, waypointMode, craneSelectedIndex,
 		isCameraSelection, addActiveCranePoint, deleteSelectedCranePoint, setCraneSelectedIndex, tlFrameCount,
 		tlFps, characters, activeCharIndex, ghostLayers, pathSpeed,
 		tlPlaying, workflowMode, waypoints, pendingWaypointFrame,
@@ -205,7 +206,7 @@ export default function BottomDock({ tab: requestedTab = "animation", onTabChang
 			{!embedded && previsMode === "storyboard" && <BoardSlot active={tab === "board"} />}
 			<div className="bottom-timeline" hidden={tab !== "animation"}>
 			<Timeline
-				frame={tlFrame}
+				frame={liveFrame}
 				craneSelectedIndex={craneSelectedIndex}
 				cameraSelected={isCameraSelection}
 				onCranePointAdd={addActiveCranePoint}
@@ -390,11 +391,10 @@ const CARD_RATIOS = [
 
 /** The shot camera's card at the dock's right end. The camera itself is drawn
  * into the stage canvas under `.vp-shot-preview`, which sits over the card's
- * frame slot (see glass.css); the card holds its title, ratio and look-through. */
+ * frame slot (see glass.css); the card holds its title, lens, ratio and look-through. */
 function ShotCard() {
-	const { activeShot, shot, shotAspectKey, runStudioAction, enterShotLook, exitShotLook, lookThroughShot, tlFps, embedMode } = useStudioShell();
+	const { activeShot, shot, fovDeg, shotsDomain, shotAspectKey, runStudioAction, enterShotLook, exitShotLook, lookThroughShot, tlFps, embedMode } = useStudioShell();
 	if (embedMode) return null;
-	const ratio = SHOT_ASPECT_PRESETS[shotAspectKey]?.label?.replace(/:1$/, "") ?? shotAspectKey;
 	const frames = activeShot && Number.isFinite(activeShot.startFrame) && Number.isFinite(activeShot.endFrame)
 		? `${activeShot.startFrame}–${activeShot.endFrame} · ${((activeShot.endFrame - activeShot.startFrame + 1) / (tlFps || 24)).toFixed(1)}s`
 		: null;
@@ -403,7 +403,7 @@ function ShotCard() {
 			<header className="dock-shot-head">
 				<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 5.75A1.5 1.5 0 0 1 3.5 4.25h6A1.5 1.5 0 0 1 11 5.75v4.5a1.5 1.5 0 0 1-1.5 1.5h-6A1.5 1.5 0 0 1 2 10.25z M11 7l3-1.5v5L11 9" /></svg>
 				<span className="dock-shot-title">{ko("Shot Camera", "샷 카메라")}</span>
-				<span className="dock-shot-meta">{shot.focalMm} mm · {ratio}</span>
+				<LensScrub fovDeg={fovDeg} sensorHeightMm={shot?.usedSensorHeightMm} shotsDomain={shotsDomain} disabled={!shot} />
 			</header>
 			{/* While the main view looks through this camera the card has nothing
 			    of its own to show (the preview pass is off): it says where the

package/src/shell/MenuBar.jsx

@@ -196,7 +196,7 @@ export default function MenuBar({ preferences }) {
 		? panelCount ? "" : noPanels
 		: shots.length ? "" : ko("Add a shot first — a pack describes one cut", "샷을 먼저 추가하세요 — 팩은 컷 하나를 설명합니다");
 
-	// The camera tutorial's handoff opens Export directly; its flyout lives in File.
+	// Export's flyout lives in File, so an open Export menu opens File.
 	useEffect(() => {
 		if (exportMenuOpen) setOpen("file");
 	}, [exportMenuOpen]);
@@ -534,14 +534,6 @@ export default function MenuBar({ preferences }) {
 		),
 		help: (
 			<>
-				<button
-					type="button"
-					role="menuitem"
-					className="menubar-item"
-					onClick={item(() => window.dispatchEvent(new CustomEvent("cozyclay:camera-tutorial", { detail: { open: true, source: "help" } })))}
-				>
-					<span className="menubar-item-label">{ko("Tutorial", "튜토리얼")}</span>
-				</button>
 				<button type="button" role="menuitem" className="menubar-item" onClick={item(() => setDialog("shortcuts"))}>
 					<span className="menubar-item-label">{ko("Keyboard shortcuts", "단축키")}</span>
 				</button>

package/src/shell/PreferencesDialog.jsx

@@ -114,7 +114,7 @@ function ThemeControls() {
 }
 
 function preferenceSection(section, props) {
-	const { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView, cameraTutorial } = props;
+	const { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView } = props;
 	const languageControls = (
 		<div className="v2-preferences__language-controls">
 			{LANGUAGES.map((language) => (
@@ -158,7 +158,6 @@ function preferenceSection(section, props) {
 							/>
 						</PreferenceRow>
 					</PreferenceSection>
-					{cameraTutorial && <div className="v2-preferences__help">{cameraTutorial}</div>}
 				</>
 			);
 		case "Viewport":
@@ -181,7 +180,7 @@ function preferenceSection(section, props) {
 	}
 }
 
-export default function PreferencesDialog({ open, onClose, initialSection = "Appearance", cameraTutorial }) {
+export default function PreferencesDialog({ open, onClose, initialSection = "Appearance" }) {
 	const dialogRef = useRef(null);
 	const searchRef = useRef(null);
 	const closeRef = useRef(onClose);
@@ -233,7 +232,7 @@ export default function PreferencesDialog({ open, onClose, initialSection = "App
 	}, [open, initialSection]);
 
 	if (!open || typeof document === "undefined") return null;
-	const currentProps = { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView, cameraTutorial };
+	const currentProps = { autoColor, setAutoColor, analyticsOptOut, setAnalyticsOptOutState, gridView, setGridView };
 
 	return createPortal(
 		<div className="v2-preferences" data-testid="preferences-dialog-backdrop" onPointerDown={(event) => { if (event.target === event.currentTarget) closeRef.current?.(); }}>

package/src/shell/ViewportToolbar.jsx

@@ -11,7 +11,7 @@ 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 GhostsMenuGroup from "./GhostsMenuGroup.jsx";
+import GhostsMenuGroup from "./GhostsMenuGroup.jsx"; import { addCameraShot } from "./add-camera-shot.js";
 import "./viewport.css";
 
 // G1: the single mode+tool pill. Keys 1-5 and W/E/R are bound in App's
@@ -122,7 +122,7 @@ export default function ViewportToolbar() {
 		autoColor, setAutoColor, isCharacterSelection, partColoursChoice, embedMode,
 		agentCollapsed, addSceneObject, spawnCharacter, characters, flySpeed,
 		ikEditTool, setIkEditTool, motion, setRangePinPartPick,
-		previsMode, sculptView, requestSculptView,
+		previsMode, sculptView, requestSculptView, appContext, setToast,
 	} = useStudioShell();
 	const menu = useOverlayMenu();
 
@@ -292,7 +292,7 @@ export default function ViewportToolbar() {
 									role="menuitem"
 									className="add-object-item"
 									data-add="camera"
-									onClick={() => { runStudioAction("shot.create"); menu.close(); }}
+									onClick={() => { addCameraShot({ appContext, runStudioAction, setToast }); menu.close(); }}
 								>
 									<span className="add-object-swatch vp-add-swatch-camera" aria-hidden="true" />
 									<span>{ko("Camera", "카메라")}</span>

package/src/shell/add-camera-shot.js

@@ -0,0 +1,11 @@
+// Add > Camera names the cut it made (ViewportToolbar). A refusal is already toasted by runStudioAction.
+import { ko } from "../locale.js";
+
+export function addCameraShot({ appContext, runStudioAction, setToast }) {
+	const shots = appContext.storeDomain("shot"), before = shots.read(), receipt = runStudioAction("shot.create");
+	const made = shots.read().find((row) => row.id === receipt?.affectedIds.find((id) => !before.some((old) => old.id === id)));
+	if (!made) return;
+	setToast(made.kind === "still"
+		? ko(`${made.name} added — a storyboard panel at frame ${made.startFrame}`, `${made.name} 추가됨 — ${made.startFrame}프레임의 스토리보드 패널`)
+		: ko(`${made.name} added — a camera cut at frame ${made.startFrame}`, `${made.name} 추가됨 — ${made.startFrame}프레임에서 카메라 컷`));
+}

package/src/shell/glass-regions.css

@@ -800,11 +800,12 @@
 
 /* ----------------------------------------------- Dock: Animation | Assets */
 /* The switch sits at the head's left end, where the Sequencer's transport
-   and the Library's Content | Log row start after it. */
+   and the Library's Content | Log row start after it. It paints above the
+   timeline (z-index 6, timeline.css), which would otherwise take its clicks. */
 .app[data-shell="glass"]:not([data-embed-mode]) .v2-dock { --dock-tabs-w: 176px; }
 .app[data-shell="glass"]:not([data-embed-mode]) .dock-tabs {
 	position: absolute;
-	z-index: 3;
+	z-index: 7;
 	top: 9px;
 	left: 16px;
 	box-sizing: border-box;

package/src/shell/glass.css

@@ -326,11 +326,6 @@
 		font-size: 11.5px;
 		font-weight: 400;
 	}
-	.app[data-shell="glass"]:not([data-embed-mode]) .studio-project-head .project-menu {
-		top: calc(100% + 6px);
-		left: -6px;
-		z-index: 40;
-	}
 
 	/* --------------------------------------------- viewport overlay rails */
 	/* Overlays fill the open stage between the columns: the mode switch rides

package/src/shell/lens-scrub-math.js

@@ -0,0 +1,51 @@
+// The Shot Camera card's focal-length scrub (BottomDock ShotCard). The lens is
+// stored as a vertical FOV (shotsDomain.changeLens takes degrees); the card
+// speaks millimetres on the current filmback, the shot.js lens relation.
+import { PRIME_SET } from "../shot.js";
+
+// Editor lens range: shotsDomain.changeLens refuses FOVs outside 14-90°.
+const FOV_MIN = 14, FOV_MAX = 90;
+// px of horizontal drag per millimetre, and the Shift / Alt multipliers.
+const PX_PER_MM = 4, FINE = 0.1, COARSE = 4;
+
+const round1 = (value) => Math.round(value * 10) / 10;
+
+export function fovDegToMm(fovDeg, sensorHeightMm) {
+	return sensorHeightMm / (2 * Math.tan((fovDeg * Math.PI) / 360));
+}
+
+export function mmToFovDeg(mm, sensorHeightMm) {
+	return (2 * Math.atan(sensorHeightMm / (2 * mm)) * 180) / Math.PI;
+}
+
+/** The millimetre range the editor FOV range allows on this filmback. */
+export function lensRange(sensorHeightMm) {
+	return { min: round1(fovDegToMm(FOV_MAX, sensorHeightMm)) + 0.1, max: round1(fovDegToMm(FOV_MIN, sensorHeightMm)) - 0.1 };
+}
+
+export function clampMm(mm, range) {
+	return round1(Math.min(range.max, Math.max(range.min, mm)));
+}
+
+/** The lens a horizontal drag of dx px from startMm lands on. */
+export function dragMm(startMm, dx, { fine = false, coarse = false } = {}, range) {
+	const scale = fine ? FINE : coarse ? COARSE : 1;
+	return clampMm(startMm + (dx / PX_PER_MM) * scale, range);
+}
+
+/** A click steps to the next real prime in range, wrapping to the widest. */
+export function nextPrime(mm, range) {
+	const primes = PRIME_SET.filter((prime) => prime >= range.min && prime <= range.max);
+	return primes.find((prime) => prime > mm + 0.05) ?? primes[0];
+}
+
+/** The left arrow steps back to the previous real prime, wrapping to the longest. */
+export function previousPrime(mm, range) {
+	const primes = PRIME_SET.filter((prime) => prime >= range.min && prime <= range.max);
+	return [...primes].reverse().find((prime) => prime < mm - 0.05) ?? primes.at(-1);
+}
+
+export function formatMm(mm) {
+	const value = round1(mm);
+	return `${Number.isInteger(value) ? value : value.toFixed(1)} mm`;
+}

package/src/shell/lens-scrub.css

@@ -0,0 +1,73 @@
+/* The Shot Camera card's focal-length scrub (lens-scrub.jsx): a small field, the mm value over a track with a
+   thumb, so it reads as a control at rest; the step arrows appear just outside it on hover, taking no width. */
+.dock-lens-scrub {
+	position: relative;
+	flex: none;
+	display: inline-flex;
+	align-items: center;
+	gap: 0;
+	padding: 1px;
+	border-radius: 6px;
+	background: var(--chip-fill, rgba(127, 127, 127, .1));
+	color: var(--text-1, currentColor);
+	font: 500 11px var(--sans);
+	font-variant-numeric: tabular-nums;
+	cursor: ew-resize;
+	user-select: none;
+	touch-action: none;
+}
+.dock-lens-body { display: flex; flex-direction: column; align-items: stretch; gap: 2px; padding: 2px 4px; }
+.dock-lens-value { line-height: 1; white-space: nowrap; text-align: center; }
+.dock-lens-track {
+	position: relative;
+	width: 38px;
+	height: 2px;
+	border-radius: 1px;
+	background: var(--hairline, rgba(127, 127, 127, .3));
+}
+.dock-lens-fill {
+	position: absolute;
+	inset: 0 auto 0 0;
+	width: var(--lens-at, 0%);
+	border-radius: inherit;
+	background: var(--text-3, currentColor);
+}
+.dock-lens-thumb {
+	position: absolute;
+	top: 50%;
+	left: var(--lens-at, 0%);
+	width: 5px;
+	height: 5px;
+	border-radius: 50%;
+	background: var(--text-2, currentColor);
+	box-shadow: 0 0 0 1px var(--surface-raised, #fff);
+	transform: translate(-50%, -50%);
+}
+.dock-lens-step {
+	position: absolute;
+	top: 50%;
+	display: grid;
+	place-items: center;
+	width: 12px;
+	height: 18px;
+	border-radius: 3px;
+	color: var(--text-3, currentColor);
+	cursor: pointer;
+	opacity: 0;
+	transform: translateY(-50%);
+	transition: opacity .12s;
+}
+.dock-lens-step[data-step="back"] { right: 100%; }
+.dock-lens-step[data-step="next"] { left: 100%; }
+.dock-lens-scrub:is(:hover, :focus-visible, .dragging) .dock-lens-step { opacity: 1; }
+.dock-lens-step:hover { color: var(--select); background: var(--hairline, rgba(127, 127, 127, .2)); }
+.dock-lens-scrub:hover,
+.dock-lens-scrub.dragging { color: var(--select); }
+.dock-lens-scrub:hover .dock-lens-fill,
+.dock-lens-scrub.dragging .dock-lens-fill,
+.dock-lens-scrub:hover .dock-lens-thumb,
+.dock-lens-scrub.dragging .dock-lens-thumb { background: var(--select); }
+.dock-lens-scrub.dragging .dock-lens-thumb { transform: translate(-50%, -50%) scale(1.3); }
+.dock-lens-scrub:focus-visible { outline: 2px solid var(--select); outline-offset: 1px; }
+.dock-lens-scrub[aria-disabled="true"] { cursor: default; opacity: .45; background: none; box-shadow: none; color: var(--label, var(--text-2)); }
+.dock-lens-scrub[aria-disabled="true"] :is(.dock-lens-fill, .dock-lens-thumb, .dock-lens-step) { visibility: hidden; }

package/src/shell/lens-scrub.jsx

@@ -0,0 +1,98 @@
+import { useEffect, useRef, useState } from "react";
+import { FiChevronLeft, FiChevronRight } from "react-icons/fi";
+import { ko } from "../locale.js";
+import { PRESETS } from "../app-stage.jsx";
+import { clampMm, dragMm, fovDegToMm, formatMm, lensRange, mmToFovDeg, nextPrime, previousPrime } from "./lens-scrub-math.js";
+import "./lens-scrub.css";
+
+// A drag starts after this many px; less is a click (the next prime).
+const DRAG_SLOP = 3;
+// A click waits this long so a double-click (reset) does not also step.
+const CLICK_DELAY_MS = 220;
+
+/** The Shot Camera card's focal length: drag left/right to change the lens.
+ * A drag is one undo step (shotsDomain's gesture commits on pointer-up, Esc
+ * cancels); a click steps to the next prime (the left arrow: the previous
+ * one); a double-click resets. It is drawn as a field with arrows and a thumb
+ * so it reads as something to drag, not as a label. */
+export default function LensScrub({ fovDeg, sensorHeightMm, shotsDomain, disabled = false }) {
+	const off = disabled || !shotsDomain || !Number.isFinite(fovDeg) || !(sensorHeightMm > 0);
+	const range = off ? { min: 0, max: 0 } : lensRange(sensorHeightMm);
+	const mm = off ? 0 : clampMm(fovDegToMm(fovDeg, sensorHeightMm), range);
+	const drag = useRef(null);
+	const clickTimer = useRef(0);
+	const [dragging, setDragging] = useState(false);
+	useEffect(() => () => clearTimeout(clickTimer.current), []);
+
+	const setMm = (value) => shotsDomain.changeLens(mmToFovDeg(clampMm(value, range), sensorHeightMm));
+	const onPointerDown = (event) => {
+		if (off || event.button !== 0) return;
+		event.currentTarget.setPointerCapture?.(event.pointerId);
+		drag.current = { x: event.clientX, mm, moved: false, back: event.target.closest?.("[data-step]")?.dataset.step === "back" };
+	};
+	const onPointerMove = (event) => {
+		const state = drag.current;
+		if (!state) return;
+		const dx = event.clientX - state.x;
+		if (!state.moved) {
+			if (Math.abs(dx) < DRAG_SLOP) return;
+			state.moved = true;
+			setDragging(true);
+			shotsDomain.beginGesture();
+		}
+		setMm(dragMm(state.mm, dx, { fine: event.shiftKey, coarse: event.altKey }, range));
+	};
+	const onPointerUp = () => {
+		const state = drag.current;
+		drag.current = null;
+		setDragging(false);
+		if (!state || state.moved) return;
+		clearTimeout(clickTimer.current);
+		clickTimer.current = setTimeout(() => setMm((state.back ? previousPrime : nextPrime)(state.mm, range)), CLICK_DELAY_MS);
+	};
+	const onDoubleClick = () => {
+		if (off) return;
+		clearTimeout(clickTimer.current);
+		shotsDomain.changeLens(PRESETS.medium.fov);
+	};
+	const onKeyDown = (event) => {
+		if (off || (event.key !== "ArrowLeft" && event.key !== "ArrowRight")) return;
+		event.preventDefault();
+		event.stopPropagation();
+		const step = (event.shiftKey ? 10 : 1) * (event.key === "ArrowRight" ? 1 : -1);
+		setMm(Math.round(mm + step));
+	};
+
+	return (
+		<span
+			className={"dock-lens-scrub" + (dragging ? " dragging" : "")}
+			role="slider"
+			tabIndex={off ? -1 : 0}
+			aria-label={ko("Focal length", "초점 거리")}
+			aria-disabled={off || undefined}
+			aria-valuemin={range.min}
+			aria-valuemax={range.max}
+			aria-valuenow={mm}
+			aria-valuetext={off ? ko("No shot camera", "샷 카메라 없음") : formatMm(mm)}
+			aria-orientation="horizontal"
+			title={ko("Focal length — drag to change, click an arrow for the next lens", "초점 거리 — 드래그해 변경, 화살표를 눌러 다음 렌즈")}
+			data-testid="dock-lens-scrub"
+			onPointerDown={onPointerDown}
+			onPointerMove={onPointerMove}
+			onPointerUp={onPointerUp}
+			onPointerCancel={() => { drag.current = null; setDragging(false); }}
+			onDoubleClick={onDoubleClick}
+			onKeyDown={onKeyDown}
+		>
+			<span className="dock-lens-step" data-step="back" aria-hidden="true"><FiChevronLeft size={9} /></span>
+			<span className="dock-lens-body">
+				<span className="dock-lens-value">{off ? "— mm" : formatMm(mm)}</span>
+				<span className="dock-lens-track" aria-hidden="true" style={{ "--lens-at": `${off ? 0 : ((mm - range.min) / (range.max - range.min)) * 100}%` }}>
+					<span className="dock-lens-fill" />
+					<span className="dock-lens-thumb" />
+				</span>
+			</span>
+			<span className="dock-lens-step" data-step="next" aria-hidden="true"><FiChevronRight size={9} /></span>
+		</span>
+	);
+}

package/src/shell/mode.css

@@ -1,12 +1,13 @@
 /* Pose mode (#521) is IK editing on the motion workspace: it hides what
-   Motion hides (scene transform and camera framing chrome, the inset and the
-   shot preview) and shows the mode hint. The timeline's pose-correction
-   tools are hidden only in Scene and Camera, so they stay visible here. */
+   Motion hides (scene transform and camera framing chrome, the inset) and
+   shows the mode hint. The shot preview stays: it is drawn into the dock's
+   Shot Camera frame, and hiding it left that frame a hole onto the editor
+   view. The timeline's pose-correction tools are hidden only in Scene and
+   Camera, so they stay visible here. */
 .app[data-workflow-mode="pose"] .workflow-scene-context,
 .app[data-workflow-mode="pose"] .workflow-camera-context { display: none; }
 .app[data-workflow-mode="pose"] .workflow-toolbar-hint { display: inline-flex; }
-.app[data-workflow-mode="pose"] .vp-inset,
-.app[data-workflow-mode="pose"] .vp-shot-preview { display: none !important; }
+.app[data-workflow-mode="pose"] .vp-inset { display: none !important; }
 
 /* A storyboard project (#650) is stills: the take, motion and pose-correction
    tools, the root-path (waypoint) switch and a prop's Top-View travel path

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(() => {