cozyclay 3.0.3 → 3.1.0

package/src/domains/motion.js

@@ -29,8 +29,8 @@ import {
 } from "../motion/ik.js";
 import * as THREE from "three";
 import { StudioProtocolError } from "../studio-agent-protocol.js";
-
 import { applyTakeFrame } from "../motion3/playback.js";
+import { advancePlayback, installPlaybackApplier } from "./playback.js";
 import { isKo, ko } from "../locale.js";
 import { isProxyFigure } from "../scenes.js";
 import { refuseRigOnly } from "../character-kind.js";
@@ -625,15 +625,7 @@ export function useMotion(appContext) {
 
 
 	function advanceFrame(steps = 1) {
-		const count = Math.max(1, Math.floor(steps));
-		const previewEnd = appContext.shared.cameraPreviewEndRef.current;
-		if (previewEnd != null && appContext.shared.tlFrameRef.current + count >= previewEnd) {
-			appContext.shared.cameraPreviewEndRef.current = null;
-			appContext.shared.setTlFrame(previewEnd);
-			appContext.shared.setTlPlaying(false);
-			return;
-		}
-		appContext.shared.setTlFrame((f) => (f + count) % appContext.shared.frameCountRef.current);
+		advancePlayback(appContext.shared, steps);
 	}
 
 	function stepFrame(delta) {
@@ -677,6 +669,7 @@ export function useMotion(appContext) {
 			appContext.shared.poseMemberAtFrame(appContext.shared.rigs[entry.id], entry.sessionMotion, appContext.shared.ikStatesRef.current.get(entry.id), frame, IK_CORRECTION_BLEND_FRAMES);
 		}
 	};
+	installPlaybackApplier(appContext, motion, poseOtherCastMembers, ikEvaluate, IK_CORRECTION_BLEND_FRAMES);
 
 	function toggleIkMode() {
 		const next = !ikMode;

package/src/domains/playback.js

@@ -0,0 +1,32 @@
+import { advancePlaybackFrame, registerPlaybackFrameApplier } from "../motion/playback-frame-store.js";
+
+function createPlaybackApplier(appContext, motion, poseOtherCastMembers, ikEvaluate, blendFrames) {
+	return (frame) => {
+		appContext.shared.tlFrameRef.current = frame;
+		appContext.shared.propFrameRef.current = frame;
+		appContext.patchTimeline({ currentFrame: frame });
+		if (appContext.shared.activeRig) appContext.shared.poseMemberAtFrame(appContext.shared.activeRig, motion, null, frame);
+		poseOtherCastMembers(frame);
+		const state = appContext.shared.ikStateRef.current;
+		if (!appContext.shared.posing && state?.chains && (appContext.shared.ikMode || state.keys.size > 0)) {
+			ikEvaluate(state.chains, state, frame, state.fkJoints, motion ? blendFrames : 0);
+		}
+	};
+}
+
+export function installPlaybackApplier(...args) {
+	return registerPlaybackFrameApplier(createPlaybackApplier(...args));
+}
+
+// A camera-shot preview stops at its shot's end; otherwise the playhead wraps.
+export function advancePlayback(shared, steps) {
+	const count = Math.max(1, Math.floor(steps));
+	const previewEnd = shared.cameraPreviewEndRef.current;
+	if (previewEnd != null && shared.tlFrameRef.current + count >= previewEnd) {
+		shared.cameraPreviewEndRef.current = null;
+		shared.setTlFrame(previewEnd);
+		shared.setTlPlaying(false);
+		return;
+	}
+	advancePlaybackFrame(shared.frameCountRef.current, count);
+}

package/src/domains/scenes.js

@@ -208,9 +208,8 @@ export function useScenes(appContext) {
 	// A first-run author should choose a document (or explicitly start a named
 	// local draft). Keep this as a light startup sheet so the studio remains
 	// inspectable while the choice is pending; it never traps the topbar.
-	// ?tutorial=camera opens the starter scene itself (#209), so the chooser is
-	// suppressed the same way a ?scene= launch suppresses it.
-	const [projectStartupOpen, setProjectStartupOpen] = useState(() => !appContext.shared.playgroundMode && !appContext.shared.cameraTutorialQuery && !playgroundSceneUrl(globalThis.location?.search) && !loadProjectSession()?.name);
+	// A ?scene= launch opens its starter instead of the chooser.
+	const [projectStartupOpen, setProjectStartupOpen] = useState(() => !appContext.shared.playgroundMode && !playgroundSceneUrl(globalThis.location?.search) && !loadProjectSession()?.name);
 
 	const [projectManifest, setProjectManifest] = useState({ items: [], totals: { embedded: 0, external: 0, missing: 0, bytes: 0 }, missing: [] });
 
@@ -400,10 +399,6 @@ export function useScenes(appContext) {
 		if (!["valid", "migrated"].includes(checked.status)) throw new StudioProtocolError("INVALID_ARGUMENT", "Invalid project scene document.");
 		project = { ...project, scenesDocument: checked.document };
 		appContext.shared.studioDocumentEpochRef.current = crypto.randomUUID();
-		appContext.shared.tutorialProjectEpochRef.current += 1;
-		appContext.shared.tutorialSeedEpochRef.current = null;
-		appContext.shared.setTutorialSeedPending(false);
-		appContext.shared.setCameraTutorialHandoff(null);
 		appContext.shared.exportShotIdRef.current = null;
 		const source = project.scenesDocument;
 				// A project FILE carries its own scene document and never passes the
@@ -425,25 +420,16 @@ export function useScenes(appContext) {
 		domain.setDirty(false);
 		storeProjectSession(project.name, projectPrevisMode);
 		setProjectStartupOpen(false);
-		// Whatever document this is, it is no longer the scene the tutorial opened
-		// for itself; startCameraTutorial re-arms the flag after its own open.
-		appContext.shared.tutorialStarterRef.current = false;
 		setProjectManifest(resourceManifest({ scenesDocument: doc, workflow: resolvedWorkflow, poseLibrary: mergedCustomPoses, assets: project.assets ?? [], workflowOutputRefs }));
 		track("project:opened", { age_bucket: bucketProjectAge(Date.now() - (project.savedAt ?? Date.now())) });
 	}
 
 	/** Open a bundled starter scene as a fresh, saveable project. Used by the
-	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`), which is
-	 * how the landing-page tutorial hands people into the local studio. */
+	 * first-run dialog and by `npx cozyclay --scene <id>` (`?scene=`). */
 	async function openStarterScene(id, source = "starter", context = null, name = null) {
 		if (source === "starter" && domain.dirtyStore.read("projectDirty") && !window.confirm(ko("Discard unsaved changes and start a new project?", "저장되지 않은 변경사항을 버리고 새 프로젝트를 시작할까요?"))) return false;
-		const before = source === "tutorial" ? collectProjectSnapshot("Tutorial") : null;
-		const epoch = appContext.shared.tutorialProjectEpochRef.current;
 		const url = playgroundSceneUrl(`?scene=${encodeURIComponent(id)}`);
 		const project = url ? await fetchSceneProject(url) : null;
-		// A pending tutorial fetch has no authority over work authored/opened
-		// while it was loading, including an unnamed project.
-		if (source === "tutorial" && (epoch !== appContext.shared.tutorialProjectEpochRef.current || before !== collectProjectSnapshot("Tutorial"))) return false;
 		if (!project) {
 			appContext.notify(ko("That starter scene is not in this build", "이 빌드에는 그 시작 장면이 없어요"));
 			return false;
@@ -596,11 +582,6 @@ export function useScenes(appContext) {
 	}
 
 	function openScene(scene, nextScenes) {
-		appContext.shared.tutorialProjectEpochRef.current += 1;
-		appContext.shared.tutorialSeedEpochRef.current = null;
-		appContext.shared.setTutorialSeedPending(false);
-		appContext.shared.setCameraTutorial(false);
-		appContext.shared.setCameraTutorialHandoff(null);
 		appContext.shared.exportShotIdRef.current = null;
 		appContext.shared.studioSceneEpochRef.current = crypto.randomUUID();
 		const shotState = restoredShotState(scene);

package/src/domains/shots.js

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { aimAt } from '../controls.jsx';
 import { PRESETS, DEFAULT_DURATION_S, TIMELINE_FPS } from '../app-stage.jsx';
+import { usePlaybackFrameState } from '../motion/playback-frame-store.js';
 import { CAMERA_MOVES, SUBJECT_HEIGHT_M, focalMmToFov, fovToFocalMm } from '../shot.js';
 import { CAMERA_PRESETS, cameraPresetFraming } from '../camera-move.js';
 import { createDocumentStore } from '../document-store.js';
@@ -236,9 +237,8 @@ export function useShots(appContext) {
   const [moveFollow] = useState(true);
   const [railDraw, setRailDraw] = useState(false);
   const [craneSelectedIndex, setCraneSelectedIndex] = useState(null);
-  const [tlFrame, setTlFrame] = useState(0);
-  const [tlFps, setTlFps] = useState(TIMELINE_FPS);
-  const activeShotIdx = shotIndexAtFrame(shots, tlFrame), activeShot = shots[activeShotIdx] ?? null;
+  const [tlFrame, setTlFrameState] = useState(0), [tlFps, setTlFps] = useState(TIMELINE_FPS);
+  const { setTlFrame, commitPlaybackFrame, activeShotIdx, activeShot } = usePlaybackFrameState({ frameCount: tlFrameCount, setReactFrame: setTlFrameState, shots });
   const cameraKeys = activeShot?.cameraKeys ?? [], activeCamera = createCameraBlock(activeShot?.camera);
   const craneActive = !!activeCamera.craneHeight, cameraRail = activeCamera.cameraRail;
   const activeShotDuration = activeShot ? activeShot.endFrame - activeShot.startFrame + 1 : 0;
@@ -364,7 +364,7 @@ export function useShots(appContext) {
       const travel = Math.ceil(curve.length / speed * tlFps) + Math.round(tlFps * 0.5);
       const endFrame = Math.min(tlFrameCount - 1, activeShot.startFrame + Math.max(travel, activeShot.endFrame - activeShot.startFrame));
       setTimelineShotRange(activeShot.id, activeShot.startFrame, endFrame);
-      // The landing tutorial's last step is pressing ▶ (#602): open the player
+      // In the landing playground a drawn rail opens the player
       // on the shot camera, but leave playback to the visitor.
       appContext.shared.enterPreview(); appContext.shared.setTlPlaying(false); setTlFrame(activeShot.startFrame);
       appContext.notify(isKo ? '레일 완성 — 샷 카메라 시점으로 전환했습니다. ▶ 로 재생, Esc 로 복귀' : 'Rail drawn — you are looking through the shot camera. Press ▶ to ride it; Esc goes back to flying.'); return;
@@ -418,7 +418,7 @@ export function useShots(appContext) {
   }
   return { ...domain, shots, setShots, editShots, fovDeg, setFovDeg, cameraMove, customMove, startupShotState,
     movePlaying, setMovePlaying, moveFollow, railDraw, setRailDraw, craneSelectedIndex, setCraneSelectedIndex,
-    tlFrame, setTlFrame, tlFrameCount, setTlFrameCount, tlFps, setTlFps, activeShotIdx, activeShot, cameraKeys,
+    tlFrame, setTlFrame, commitPlaybackFrame, tlFrameCount, setTlFrameCount, tlFps, setTlFps, activeShotIdx, activeShot, cameraKeys,
     activeCamera, craneActive, cameraRail, activeShotDuration, hasCameraKeys, changeActiveCamera, changeShotTargetModel,
     syncActiveCameraFraming, commitManualCameraFraming, beginCameraFramingGesture, beginTimelineEditGesture,
     setShotCameraRail, clearShotCameraRail, changeCameraRail, addCameraKeyframe, moveCameraKeyframe, removeCameraKeyframe, clearMove,

package/src/dualview.jsx

@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import * as THREE from "three";
+import { fitAspect } from "./shot-frame.js";
+import { updateVisibleViewOffsets } from "./viewport-visible-rect.js";
 
 /**
  * Two live viewports out of one scene.
@@ -104,17 +106,6 @@ const EDGE_FRAGMENT = `
 	}
 `;
 
-/** 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 };
-}
-
 export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCamRef, planCamRef, poserCamRef, editorCamRef, ikMode = false, planIsMain, playMode = false, lookThrough = false, insetCollapsed = false, planZoom = 1, shotAspect = SHOT_ASPECT, editorLook = false }) {
 	const invalidate = useThree((state) => state.invalidate);
 	const lastPoserPose = useRef({ position: new THREE.Vector3(), quaternion: new THREE.Quaternion(), valid: false });
@@ -245,6 +236,7 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 			return { x: r.left - base.left, y: r.top - base.top, w: r.width, h: r.height };
 		};
 		const mainRect = rectOf(mainRef.current);
+		updateVisibleViewOffsets({ editorCam, poserCam, canvas: gl.domElement.getBoundingClientRect(), aspect: mainRect.w / mainRect.h });
 		// A collapsed inset is just its tag pill: skip the whole inset pass
 		// instead of drawing a squished viewport into it.
 		const insetRect = insetCollapsed ? { x: 0, y: 0, w: 0, h: 0 } : rectOf(insetRef.current);
@@ -451,8 +443,6 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// IK mode: the main pane is the poser working view (free navigation,
 				// handle layer visible); the inset is the FROZEN shot camera — the
 				// separate camera-placement screen the framing lives on.
-				poserCam.aspect = mainRect.w / mainRect.h;
-				poserCam.updateProjectionMatrix();
 				drawEditorPane(poserCam, mainRect, null, !navigatingCamera);
 				if (!navigatingCamera || redrawFrozenPanes) drawVisibleInset(shotCam, insetRect, fitAspect(insetRect, shotAspect), !navigatingCamera);
 				drawPreviewCard();
@@ -465,8 +455,6 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// navigation that never touches the recording. The shot camera only
 				// appears in its own preview pane, framed to the export aspect and
 				// stripped of editing chrome, exactly like an exported frame.
-				editorCam.aspect = mainRect.w / mainRect.h;
-				editorCam.updateProjectionMatrix();
 				// A right-drag is a camera gesture even with IK off. Keep the main
 				// image readable while the camera is moving by deferring the expensive
 				// edge/ink pass until the gesture ends; the plan inset stays frozen.
@@ -479,6 +467,14 @@ export function DualRender({ stageRef, mainRef, insetRef, shotPreviewRef, shotCa
 				// can fly the recording lens with the same bindings as the free camera.
 				// The QA hook (`window.__cozyclay.setLookThrough`) draws the same path.
 				// Look-through is the recording lens: it keeps the authored stage.
+				// The pane is the open stage less the rails (shell.css), so the
+				// canvas around it is bars too: clear it, or the last full-canvas
+				// draw stays there and reads as picture the export does not have.
+				if (lookThrough) {
+					gl.setScissorTest(false);
+					gl.setClearColor(letterbox, 1);
+					gl.clear(true, true, false);
+				}
 				draw(shotCam, shotPane, fitAspect(shotPane, shotAspect), !navigatingCamera);
 				if (!navigatingCamera || redrawFrozenPanes) drawVisibleInset(planCam, planPane, null, false);
 				drawPreviewCard();

package/src/hierarchy-panel.css

@@ -326,13 +326,27 @@
 	outline: var(--outliner-border-width, 1px) solid var(--select, #e8a33d);
 }
 
+/* The context menu is portaled to <body> inside this layer, which keeps the
+   `.v2-outliner` style scope without a box of its own (hierarchy-panel.jsx).
+   It and the scene switcher's list share the popover tokens (themes.css). */
+.v2-outliner.v2-outliner-layer {
+	display: contents;
+}
+
+.v2-outliner .hierarchy-context-menu,
+.dropdown-menu.hierarchy-scene-menu {
+	z-index: var(--z-popover, 90);
+	border: var(--outliner-border-width, 1px) solid var(--popover-border, var(--row-divider, #1d1d20));
+	border-radius: var(--popover-radius, 6px);
+	background: var(--popover-surface, var(--surface-raised, #1e1e21));
+	-webkit-backdrop-filter: var(--popover-blur, none);
+	backdrop-filter: var(--popover-blur, none);
+	box-shadow: var(--popover-shadow, 0 8px 24px rgba(0, 0, 0, .45));
+}
+
 .v2-outliner .hierarchy-context-menu {
 	min-width: var(--outliner-menu-width, 220px);
 	padding: var(--outliner-menu-padding, 4px);
-	border: var(--outliner-border-width, 1px) solid var(--row-divider, #1d1d20);
-	border-radius: var(--r-2, 6px);
-	background: var(--surface-raised, #1e1e21);
-	box-shadow: 0 var(--sp-1, 8px) var(--sp-3, 16px) var(--overlay, rgba(12,12,13,.78));
 }
 
 .v2-outliner .hierarchy-context-item {

package/src/hierarchy-panel.jsx

@@ -1,9 +1,11 @@
 import { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { ko, isKo } from "./locale.js";
 import { buildHierarchyNodes } from "./hierarchy-model.js";
 import { sceneObjectIdFromHierarchy } from "./scene-objects.js";
 import { CatalogueEntries, displayObjectLabel } from "./object-catalog.jsx";
 import { Dropdown } from "./ui.jsx";
+import { usePopover } from "./popover.js";
 import { isImeComposing } from "./ime.js";
 import "./hierarchy-panel.css";
 
@@ -97,6 +99,7 @@ function ScenePill({ scenes, activeSceneId, onSceneSelect, onSceneCreate, onRena
 				value={activeSceneId}
 				options={options}
 				ariaLabel={ko("Select scene", "장면 선택")}
+				menuClassName="hierarchy-scene-menu"
 				onChange={(value) => {
 					if (value === NEW_SCENE_OPTION) onSceneCreate?.();
 					else if (value !== activeSceneId) onSceneSelect?.(value);
@@ -194,11 +197,9 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 	const [deleteArmed, setDeleteArmed] = useState(false);
 	useEffect(() => setDeleteArmed(false), [menu]);
 
+	usePopover(menu, onClose, [rootRef]);
 	useEffect(() => {
 		if (!menu) return undefined;
-		const onDocDown = (event) => {
-			if (rootRef.current && !rootRef.current.contains(event.target)) onClose();
-		};
 		const onKey = (event) => {
 			if (event.key !== "Escape") return;
 			// Capture phase + stopImmediatePropagation: closing the menu must
@@ -206,12 +207,8 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 			event.stopImmediatePropagation();
 			onClose();
 		};
-		document.addEventListener("mousedown", onDocDown);
 		window.addEventListener("keydown", onKey, true);
-		return () => {
-			document.removeEventListener("mousedown", onDocDown);
-			window.removeEventListener("keydown", onKey, true);
-		};
+		return () => window.removeEventListener("keydown", onKey, true);
 	}, [menu, onClose]);
 
 	if (!menu) return null;
@@ -221,8 +218,11 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 		left: Math.max(4, Math.min(menu.x, window.innerWidth - 244)),
 		top: Math.max(4, Math.min(menu.y, window.innerHeight - menu.height)),
 	};
-	return (
-		<div className="hierarchy-context-menu" role="menu" style={style} ref={rootRef}>
+	// Portaled: the glass column clips and blurs its children, so an in-place
+	// menu was cut at the column edge and sat under body-level popovers. The
+	// display:contents layer keeps the `.v2-outliner` style scope.
+	return createPortal(
+		<div className="v2-outliner v2-outliner-layer"><div className="hierarchy-context-menu" role="menu" style={style} ref={rootRef}>
 			{menu.kind === "scene" ? (
 				<>
 					<button type="button" role="menuitem" className="hierarchy-context-item" onClick={() => onAction("rename", menu.id)}>
@@ -292,7 +292,8 @@ function RowContextMenu({ menu, onClose, onAction, onAddObject }) {
 			) : (
 				<CatalogueEntries onPick={onAddObject} />
 			)}
-		</div>
+		</div></div>,
+		document.body,
 	);
 }
 

package/src/kits/held.js

@@ -38,9 +38,10 @@ export const bat = {
 
 export const ball = {
 	label: "Baseball", prop: "ballGrip",
-	description: "7.4 cm baseball held in the right fingers",
+	description: "7.4 cm baseball held in the right palm and fingers",
 	props: { ballGrip: { hand: "r", origin: RIGHT_FINGERS, points: { centre: [0, 0, -0.035] } } },
-	carry: { prop: "ballGrip", at: [0, 0, -0.035], along: [0, 1, 0] },
+	// no pinned point: it rests against the palm where the hand takes it and the fingers close round it (motion3 seat.js)
+	carry: { prop: "ballGrip", grasp: "spherical" },
 	parts: [{ role: "body", kind: "sphere", at: [0, -0.037, 0], scale: [0.074, 0.074, 0.074], color: "#f1ede3" }],
 };
 

package/src/light-blockers.js

@@ -19,9 +19,9 @@
 import { practicalShadows, withShadowCapWarnings } from "./object-look.js";
 import { isEffectivelyHidden } from "./object-hidden.js";
 
-/** Renderers whose meshes cast shadows (props.jsx, set-pieces.jsx, sculpts, imported meshes).
+/** Renderers whose meshes cast shadows (props.jsx primitives, sculpts, imported meshes).
  * A plane and a cutout are cards: nothing can be inside them. */
-const CASTERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "car", "chair", "small-plane", "sculpt", "mesh"]);
+const CASTERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "sculpt", "mesh"]);
 const DEG = Math.PI / 180;
 const EPS = 1e-6;
 const MAX_WARNINGS = 4;

package/src/main.jsx

@@ -12,6 +12,7 @@ import { registerPwa } from "./pwa.js";
 import { LOCALE } from "./locale.js";
 import { initAnalytics } from "./analytics.js";
 import { fetchPlaygroundProject, isPlaygroundEmbed, playgroundSceneUrl, stashPlaygroundProject } from "./playground.js";
+import { preloadBodies } from "./motion3/body.js";
 
 registerPwa();
 void initAnalytics();
@@ -34,6 +35,10 @@ async function boot() {
 			</ErrorBoundary>
 		</StrictMode>,
 	);
+	// The motion compiler's body fits are not in the first-load bundle (motion3/body.js): fetch them once
+	// the first screen is up, so a saved take compiled on this thread does not have to wait for them.
+	const idle = globalThis.requestIdleCallback ?? (run => setTimeout(run, 200));
+	idle(() => preloadBodies().catch(error => console.warn("[cozyclay] could not preload the motion body fits", error)));
 }
 
 void boot();

package/src/motion/ground.js

@@ -3,20 +3,11 @@ import { isEffectivelyHidden, objectFootprintBounds } from "../scene-objects.js"
 /**
  * Ground height under a point, from the scene's objects (issue #250).
  *
- * AutoPhysics review measures every contact against ONE flat floor
- * (`floorY`). When a character stands on a box or a step its feet get pulled
- * down to the floor plane. This module answers "what is the ground here?" so
- * contact detection, span anchors, and toe minimum heights can use the
- * surface actually under the foot.
- *
- * DRAFT - the sampler exists and is tested; physics-review.js does not call
- * it yet. Wiring plan:
- *   1. supportIntervals(): compare the sole to groundAt(toe.x, toe.z), not
- *      floorY, in the "low enough to be a contact" test.
- *   2. Span anchors carry y = groundAt(anchor.x, anchor.z); footLockTrack
- *      anchors and relaxToePath's toeMinHeight take that value per frame.
- *   3. Penetration / float metrics and the root lift measure against the
- *      local ground under each support site.
+ * Against ONE flat floor (`floorY`), a character standing on a box or a step
+ * would read as sunk into it. This module answers "what is the ground here?":
+ * studio-agent-motion.js samples it per support site, and physics-review.js
+ * takes it as `groundAt` for contact spans, foot anchors and the floor/float
+ * metrics, so they measure against the surface actually under the foot.
  *
  * Surface model: each scene object is an axis-aligned box from
  * objectFootprintBounds (yaw-exact XZ footprint, flat top at topY). The

package/src/motion/playback-frame-store.js

@@ -0,0 +1,79 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { shotIndexAtFrame } from "../cuts.js";
+
+// The playhead lives here, outside React: playback ticks write it and only the
+// components that show the frame subscribe, so App does not re-render per frame.
+let currentFrame = 0;
+const listeners = new Set();
+let applyPlaybackFrame = null;
+
+export function playbackFrame() {
+	return currentFrame;
+}
+
+export function setPlaybackFrame(next) {
+	const frame = typeof next === "function" ? next(currentFrame) : next;
+	if (!Number.isFinite(frame) || frame === currentFrame) return currentFrame;
+	currentFrame = frame;
+	if (typeof window !== "undefined") window.__cozyclayPlaybackFrame = frame;
+	for (const listener of listeners) listener();
+	return currentFrame;
+}
+
+export function advancePlaybackFrame(frameCount, count) {
+	const frame = setPlaybackFrame((current) => (current + count) % frameCount);
+	applyPlaybackFrame?.(frame);
+	return frame;
+}
+
+export function registerPlaybackFrameApplier(applier) {
+	applyPlaybackFrame = applier;
+	return () => {
+		if (applyPlaybackFrame === applier) applyPlaybackFrame = null;
+	};
+}
+
+export function createPlaybackFrameSetter({ getFrameCount, setReactFrame, onFrame }) {
+	return (update) => {
+		const next = typeof update === "function" ? update(playbackFrame()) : update;
+		const frame = Math.max(0, Math.min(getFrameCount() - 1, Math.round(next)));
+		setPlaybackFrame(frame);
+		setReactFrame(frame);
+		onFrame?.(frame);
+	};
+}
+
+export function commitPlaybackFrame(setReactFrame, onFrame) {
+	const frame = playbackFrame();
+	setReactFrame(frame);
+	onFrame?.(frame);
+	return frame;
+}
+
+export function usePlaybackSnapshot(getSnapshot) {
+	return useSyncExternalStore(subscribePlaybackFrame, getSnapshot, getSnapshot);
+}
+
+export function usePlaybackEffects({ playing = false, commit = () => {}, onStop = null } = {}) {
+	useEffect(() => {
+		if (!playing) {
+			commit();
+			onStop?.();
+		}
+		// Runs on play/stop transitions only; commit and onStop are recreated every render.
+	}, [playing]);
+}
+
+/** The shots domain's timeline frame: React state (owned by the caller) for edits, the store for playback.
+ * activeShotIdx subscribes to the store, so it re-renders only when playback crosses a cut. */
+export function usePlaybackFrameState({ frameCount, setReactFrame, shots }) {
+	const setTlFrame = createPlaybackFrameSetter({ getFrameCount: () => frameCount, setReactFrame });
+	const activeShotIdx = usePlaybackSnapshot(() => shotIndexAtFrame(shots, playbackFrame()));
+	const activeShot = shots[activeShotIdx] ?? null;
+	return { setTlFrame, commitPlaybackFrame: () => commitPlaybackFrame(setReactFrame), activeShotIdx, activeShot };
+}
+
+function subscribePlaybackFrame(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}

package/src/motion/playback-probe.js

@@ -0,0 +1,16 @@
+import { sampleAt } from "../sample-at.js";
+
+export function playbackProbe(probe, frame, fallback) {
+	const sampled = probe.scene ? sampleAt(probe.scene, null, frame).subject : null;
+	const carried = sampled && probe.carry ? probe.carry(sampled, frame) : sampled;
+	return carried ?? fallback;
+}
+
+export function probeVisibility(vector, camera, subject, height) {
+	let visible = false;
+	for (const y of [0.1, height * 0.94]) {
+		vector.set(subject.x, y, subject.z).project(camera);
+		if (vector.z < 1 && Math.abs(vector.x) <= 1 && Math.abs(vector.y) <= 1) visible = true;
+	}
+	return visible;
+}

package/src/motion/playback-subject.js

@@ -0,0 +1,7 @@
+import { sampleAt } from "../sample-at.js";
+
+export function usePlaybackSubjectPosition({ motion, subjectCarry, scene, frame }) {
+	if (!motion && !subjectCarry) return null;
+	const subject = sampleAt(scene, null, frame).subject;
+	return subjectCarry ? subjectCarry(subject, frame) : subject;
+}

package/src/motion/timeline.css

@@ -778,11 +778,13 @@
 	box-shadow: none;
 }
 
+/* Shots cut against each other: a hairline between neighbours, not a wide gutter, so a run of cuts reads as
+   one sequence. Free-camera time between shots still shows as its own gap. */
 .v2-sequencer .tl-shot-block {
 	top: var(--tl-clip-inset, 7px);
 	bottom: var(--tl-clip-inset, 7px);
-	left: calc(var(--tl-f-start) * 100% + var(--tl-clip-inset, 7px));
-	width: max(var(--tl-min-clip-width, 1px), calc((var(--tl-f-end) - var(--tl-f-start)) * 100% - (var(--tl-clip-inset, 7px) * 2)));
+	left: calc(var(--tl-f-start) * 100% + var(--tl-shot-gap, 1px));
+	width: max(var(--tl-min-clip-width, 1px), calc((var(--tl-f-end) - var(--tl-f-start)) * 100% - (var(--tl-shot-gap, 1px) * 2)));
 	padding: var(--sp-1, 8px) var(--sp-1, 8px) var(--tl-shot-footer-height, 28px);
 	border: 0;
 	border-radius: var(--r-1, 4px);
@@ -854,6 +856,10 @@
 	background: var(--select-tint, rgba(232, 163, 61, .14));
 }
 
+/* The trim grips appear with the shot under the pointer, not as a column of marks at every cut. */
+.v2-sequencer .tl-shot-edge { opacity: 0; transition: opacity .12s; }
+.v2-sequencer .tl-shot-block:is(:hover, :focus-within) .tl-shot-edge { opacity: 1; }
+
 /* The bar hangs above the block's top-left corner instead of inside it: a
    short cut (40 frames ~ 38px) is narrower than Split + Duplicate + Delete,
    and an in-block bar would sit on the shot's name, turning a click on the
@@ -926,13 +932,22 @@
 	pointer-events: auto;
 }
 
+/* A camera key sits on its Shot's key strip (the line along the box's foot), as a small diamond: at the
+   lane's first-row height it landed on the box's top corner, in the gutter between two Shots. */
 .v2-sequencer .tl-marker.cam {
-	top: calc(var(--tl-track-row-height, 38px) / 2);
-	bottom: auto;
+	top: auto;
+	bottom: calc(var(--tl-clip-inset, 7px) + var(--tl-key-strip-height, 12px) / 2);
+	width: 7px;
+	height: 7px;
+	border-radius: 1.5px;
 	background: var(--camera, #a78bfa);
-	transform: translate(-50%, -50%) rotate(45deg);
+	box-shadow: 0 0 0 1.5px var(--tl-camera-clip, #3d3354);
+	transform: translate(-50%, 50%) rotate(45deg);
 	z-index: 7;
 }
+/* A key on a Shot's first or last frame steps just inside the box instead of straddling its edge. */
+.v2-sequencer .tl-marker.cam[data-edge="start"] { margin-left: 7px; }
+.v2-sequencer .tl-marker.cam[data-edge="end"] { margin-left: -7px; }
 
 .v2-sequencer .tl-marker.wp {
 	background: var(--ok, #4fbf7a);
@@ -1151,6 +1166,29 @@
 	background: var(--select, #e8a33d);
 }
 
+/* In a Shot box the height graph is a ~20 px strip: the points are small dots ON the curve, quiet on other
+   shots and full on the selected or hovered one, and their hit area stays a full finger wide. Hovering a curve
+   thickens it and the cursor says which way it moves. The axis labels have no room. */
+.v2-sequencer .tl-shot-block .tl-crane-knob {
+	width: 7px;
+	height: 7px;
+	border: 1.5px solid var(--tl-camera-rail, #302a40);
+	box-shadow: none;
+	opacity: .5;
+	transition: opacity .12s;
+}
+.v2-sequencer .tl-shot-block .sg-shot.height { z-index: 2; }
+.v2-sequencer .tl-shot-block .tl-crane-knob::before { content: ""; position: absolute; inset: -6px; border-radius: 50%; }
+.v2-sequencer .tl-shot-block .tl-crane-knob.selected { width: 9px; height: 9px; }
+.v2-sequencer .tl-shot-block:is(.selected, .active, :hover) .tl-crane-knob { opacity: 1; }
+.v2-sequencer .tl-shot-block .tl-crane-knob:hover, .v2-sequencer .tl-shot-block .tl-crane-knob:focus-visible { outline: none; transform: translate(-50%, -50%) scale(1.3); }
+.v2-sequencer .tl-shot-block .tl-crane-line { stroke-width: 1.5px; }
+.v2-sequencer .tl-shot-block .sg-shot .sg-body svg { cursor: ns-resize; }
+.v2-sequencer .tl-shot-block .sg-shot:hover :is(.sg-line, .tl-crane-line) { stroke-width: 2.5px; }
+.v2-sequencer .tl-shot-block .tl-crane-time-pick { opacity: 0; }
+.v2-sequencer .tl-shot-block .tl-crane-time-pick.selected { opacity: 1; }
+.v2-sequencer .tl-shot-block .tl-crane-editor :is(.sg-scale-top, .sg-scale-avg, .sg-scale-zero) { display: none; }
+
 .v2-sequencer .sg-shot {
 	left: var(--sp-1, 8px);
 	right: var(--sp-1, 8px);

package/src/motion/timeline.jsx

@@ -273,8 +273,9 @@ function CraneHeightEditor({ crane, railRange, durationFrames, selectedIndex, on
 					key={index}
 					type="button"
 					className={"tl-crane-knob" + (index === selectedIndex ? " selected" : "")}
-					// an end point sits ON the window edge; clamp it inside so the knob stays a whole, grabbable circle
-					style={{ left: `clamp(9px, ${xFor(point.t) * 100}%, calc(100% - 9px))`, top: `clamp(9px, ${yFor(point.height) * 100}%, calc(100% - 9px))` }}
+					// an end point sits ON the window edge; clamp it inside so the knob stays whole. The clamp is the
+					// knob's own radius: a wider one pinned every knob of a 20 px Shot strip to one row, off its curve.
+					style={{ left: `clamp(5px, ${xFor(point.t) * 100}%, calc(100% - 5px))`, top: `clamp(5px, ${yFor(point.height) * 100}%, calc(100% - 5px))` }}
 					aria-label={ko(`Crane point ${index + 1}, ${point.height.toFixed(1)} metres`, `크레인 점 ${index + 1}, ${point.height.toFixed(1)}미터`)}
 					onPointerDown={(event) => {
 						event.preventDefault();
@@ -2199,7 +2200,7 @@ export default function Timeline({
 									{name === SHOTS_LANE && shots.flatMap((shot, index) => (shot.cameraKeys ?? []).map((key) => (
 										<span
 											key={`${shot.id}:${key.frame}`}
-											className="tl-marker cam"
+											className="tl-marker cam" data-edge={key.frame <= shot.startFrame ? "start" : key.frame >= shot.endFrame ? "end" : undefined}
 											style={{ "--tl-f": framePct(key.frame, displayFrameCount) }}
 											title={isKo ? `${key.frame}프레임의 카메라 키 — 클릭해 이동, 드래그로 시간 변경, 오른쪽 클릭으로 삭제` : `Camera key at frame ${key.frame} — click to jump, drag to re-time, right-click to remove`}
 											onPointerDown={(e) => beginCameraKeyDrag(e, key, index)}