cozyclay 3.1.4 → 3.1.6

package/src/first-success-guide.jsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from "react";
 import { ko } from "./locale.js";
+import { noteGuideDismissed, noteGuideOpened, noteGuideStep } from "./guide-telemetry.js";
 
 const ANIMATION_STEPS = [
 	{
@@ -76,13 +77,16 @@ const STEPS_BY_MODE = { animation: ANIMATION_STEPS, storyboard: STORYBOARD_STEPS
 /** A compact, dismissible first-run checklist that follows the v2 shell grammar. */
 export default function FirstSuccessGuide({ open, onDismiss, previsMode = "animation" }) {
 	const storyboard = previsMode === "storyboard";
-	const STEPS = STEPS_BY_MODE[storyboard ? "storyboard" : "animation"];
+	const mode = storyboard ? "storyboard" : "animation";
+	const STEPS = STEPS_BY_MODE[mode];
 	const [step, setStep] = useState(0);
 	useEffect(() => {
-		if (open) setStep(0);
-	}, [open]);
+		if (open) { setStep(0); noteGuideOpened(mode); }
+	}, [open]); // eslint-disable-line react-hooks/exhaustive-deps -- the mode at opening time
 	if (!open) return null;
 	const complete = step >= STEPS.length;
+	// Closing after the last step is not a drop-off: only an unfinished guide reports guide:dismissed.
+	const dismiss = () => { if (!complete) noteGuideDismissed(mode, step + 1); onDismiss(); };
 
 	return (
 		<aside className="v2-first-success-guide first-success-guide" role="dialog" aria-labelledby="first-success-guide-title" aria-describedby="first-success-guide-description">
@@ -91,14 +95,14 @@ export default function FirstSuccessGuide({ open, onDismiss, previsMode = "anima
 					<strong id="first-success-guide-title">{ko("Your first 60 seconds", "첫 60초")}</strong>
 					<span>{complete ? ko("Core loop complete", "핵심 흐름 완료", "核心流程完成") : ko(`Step ${step + 1} of ${STEPS.length}`, `${step + 1} / ${STEPS.length} 단계`, `第 ${step + 1} / ${STEPS.length} 步`)}</span>
 				</div>
-				<button type="button" className="v2-first-success-guide-close first-success-guide-close" onClick={onDismiss} aria-label={ko("Dismiss guide", "가이드 닫기")}>×</button>
+				<button type="button" className="v2-first-success-guide-close first-success-guide-close" onClick={dismiss} aria-label={ko("Dismiss guide", "가이드 닫기")}>×</button>
 			</div>
 			{complete ? (
 				<div className="v2-first-success-guide-complete first-success-guide-complete" id="first-success-guide-description" role="status">
 					<div className="v2-first-success-guide-check first-success-guide-check">✓</div>
 					<strong>{storyboard ? ko("You made your first panel.", "첫 패널을 만들었어요.") : ko("You made your first shot.", "첫 샷을 만들었어요.")}</strong>
 					<p>{storyboard ? ko("Describe, review on the Board, then stylize or export. You can close this guide and keep adding panels.", "설명하고, 보드에서 확인한 뒤 스타일을 입히거나 내보내세요. 가이드를 닫고 패널을 계속 추가하세요.") : ko("Select, move, ask, and play are the core CozyClay loop. You can close this guide and keep blocking.", "선택하고, 움직이고, 요청하고, 재생하는 것이 CozyClay의 핵심 흐름입니다. 가이드를 닫고 계속 블로킹하세요.")}</p>
-					<button type="button" className="v2-first-success-guide-next first-success-guide-next btn primary" onClick={onDismiss}>{ko("Continue editing", "편집 계속하기")}</button>
+					<button type="button" className="v2-first-success-guide-next first-success-guide-next btn primary" onClick={dismiss}>{ko("Continue editing", "편집 계속하기")}</button>
 				</div>
 			) : (
 				<>
@@ -111,12 +115,12 @@ export default function FirstSuccessGuide({ open, onDismiss, previsMode = "anima
 							</li>
 						))}
 					</ol>
-					<button type="button" className="v2-first-success-guide-next first-success-guide-next btn primary" onClick={() => setStep((value) => value + 1)}>
+					<button type="button" className="v2-first-success-guide-next first-success-guide-next btn primary" onClick={() => { noteGuideStep(mode, step + 1, STEPS.length); setStep(step + 1); }}>
 						{ko(step === STEPS.length - 1 ? "Mark complete" : "I did this", step === STEPS.length - 1 ? "완료로 표시" : "했어요", step === STEPS.length - 1 ? "标记完成" : "我做了这一步")}
 					</button>
 				</>
 			)}
-			<button type="button" className="v2-first-success-guide-skip first-success-guide-skip" onClick={onDismiss}>{ko("Skip guide", "가이드 건너뛰기")}</button>
+			<button type="button" className="v2-first-success-guide-skip first-success-guide-skip" onClick={dismiss}>{ko("Skip guide", "가이드 건너뛰기")}</button>
 		</aside>
 	);
 }

package/src/guide-telemetry.js

@@ -0,0 +1,60 @@
+// guide:opened, guide:step, guide:dismissed, guide:completed: the first-60-seconds
+// guide (first-success-guide.jsx) as a funnel. The mode and step numbers are the
+// component's own (its STEPS_BY_MODE keys, 1-based step index); each event and step
+// is sent at most once per session. Only the mode, a step number and a duration
+// bucket leave: never step text or what the user did.
+import { initAnalytics, track } from "./analytics.js";
+import { admit } from "./analytics-friction.js";
+import { bucketLong } from "./analytics-strict.js";
+
+const GUIDE_MODES = Object.freeze(["animation", "storyboard"]);
+const GUIDE_STEP_VALUES = Object.freeze(["1", "2", "3", "4"]);
+
+// The guide can open before the SDK has loaded; initAnalytics() is idempotent (main.jsx started
+// it), so waiting on it keeps an early guide:opened instead of spending its cap on a no-op.
+let send = (event, props) => { initAnalytics().then(() => track(event, props), () => {}); }, clock = () => Date.now();
+let stepStartedAt = null;
+
+const stepValue = (step) => (GUIDE_STEP_VALUES.includes(String(step)) ? String(step) : null);
+const guarded = (run) => { try { run(); } catch { /* Telemetry must never affect the guide. */ } };
+
+/** The guide became visible in `mode`; its first step's clock starts. */
+export function noteGuideOpened(mode) {
+	guarded(() => {
+		if (!GUIDE_MODES.includes(mode)) return;
+		stepStartedAt = clock();
+		if (admit("guide:opened", 1)) send("guide:opened", { mode });
+	});
+}
+
+/** The user marked step `step` (1-based) of `total` done; the last one also completes the guide. */
+export function noteGuideStep(mode, step, total) {
+	guarded(() => {
+		const value = stepValue(step);
+		if (!GUIDE_MODES.includes(mode) || !value) return;
+		const now = clock();
+		const stepMs = stepStartedAt === null ? NaN : now - stepStartedAt;
+		stepStartedAt = now;
+		if (admit(`guide:step:${value}`, 1)) send("guide:step", { mode, step: value, step_ms: bucketLong(stepMs) });
+		if (step === total && admit("guide:completed", 1)) send("guide:completed", { mode });
+	});
+}
+
+/** The guide was closed before its last step; `reached` is the step it was showing (1-based). */
+export function noteGuideDismissed(mode, reached) {
+	guarded(() => {
+		const value = stepValue(reached);
+		if (!GUIDE_MODES.includes(mode) || !value) return;
+		stepStartedAt = null;
+		if (admit("guide:dismissed", 1)) send("guide:dismissed", { mode, reached: value });
+	});
+}
+
+/** Tests only: capture what is sent and drive the clock; returns the restore. */
+export function guideTelemetrySeam(capture, now) {
+	const previous = [send, clock];
+	send = capture;
+	if (now) clock = now;
+	stepStartedAt = null;
+	return () => { [send, clock] = previous; stepStartedAt = null; };
+}

package/src/hierarchy-panel.jsx

@@ -7,6 +7,7 @@ import { CatalogueEntries, displayObjectLabel } from "./object-catalog.jsx";
 import { Dropdown } from "./ui.jsx";
 import { usePopover } from "./popover.js";
 import { isImeComposing } from "./ime.js";
+import { SearchEmpty } from "./search-friction.js";
 import "./hierarchy-panel.css";
 
 const HIERARCHY_LABELS_KO = {
@@ -881,7 +882,7 @@ export default function HierarchyPanel({
 			</label>
 			<div className="hierarchy-tree" role="tree" ref={treeRef} onKeyDown={onTreeKeyDown} onContextMenu={openCreateMenu}>
 				{filteredHierarchyNodes.length > 0 ? renderNodes(filteredHierarchyNodes) : (
-					<div className="v2-outliner-empty" role="status">{ko("No matches", "일치하는 항목 없음")}</div>
+					<SearchEmpty surface="outliner" query={search}><div className="v2-outliner-empty" role="status">{ko("No matches", "일치하는 항목 없음")}</div></SearchEmpty>
 				)}
 			</div>
 			{sceneHint && (

package/src/live-control.js

@@ -4,11 +4,7 @@
 import { sanitizeProps, track } from "./analytics.js";
 import { EXECUTION_TELEMETRY_EVENTS, EXECUTION_TELEMETRY_PROPERTY_KEYS } from "./execution-telemetry.js";
 
-const MOTION_TELEMETRY_EVENTS = new Set([
-	"motion:generate_requested", "motion:preflight_blocked", "motion:preflight_passed",
-	"motion:job_started", "motion:job_succeeded", "motion:job_failed", "motion:result_applied",
-]);
-const LIVE_TELEMETRY_EVENTS = new Set([...MOTION_TELEMETRY_EVENTS, ...EXECUTION_TELEMETRY_EVENTS.filter((event) => event.startsWith("mcp:"))]);
+const LIVE_TELEMETRY_EVENTS = new Set(EXECUTION_TELEMETRY_EVENTS.filter((event) => event.startsWith("mcp:")));
 
 const LIVE_CONTROL_PORT = import.meta.env?.VITE_COZYCLAY_LIVE_PORT ?? "5184";
 // The npm launcher serves a prebuilt bundle, so the build-time port above is
@@ -159,7 +155,6 @@ export function createLiveControl({
 	// A duplicated tab carries a copy of this tab's id; the hub refuses the
 	// second socket, so the loser mints and stores a new identity, then retries.
 	onDuplicate = () => mintLiveWorkspaceId(),
-	captureMotionTelemetry = track,
 	captureTelemetry = track,
 	workspaceId = "",
 	// Optional identity for the hub's live_status listing (scene/project names).
@@ -191,13 +186,11 @@ export function createLiveControl({
 		if (!correlationId) return;
 		if (EXECUTION_TELEMETRY_EVENTS.includes(payload.event)
 			&& EXECUTION_TELEMETRY_PROPERTY_KEYS[payload.event]?.some((key) => !Object.hasOwn(props, key))) return;
-		if ((payload.event === "motion:generate_requested" || payload.event.startsWith("motion:preflight_")) && props.surface !== "mcp") return;
 		const key = `${correlationId}:${payload.event}`;
 		if (capturedStages.has(key)) return;
 		capturedStages.add(key);
-		const capture = payload.event.startsWith("motion:") ? captureMotionTelemetry : captureTelemetry;
 		try {
-			Promise.resolve(capture(payload.event, props)).catch(() => {
+			Promise.resolve(captureTelemetry(payload.event, props)).catch(() => {
 				// SDK failures must not affect command dispatch or generation.
 			});
 		} catch {

package/src/locale-zh/domains.js

@@ -9,6 +9,7 @@ export const ZH_DOMAINS = {
 	"Edited pose": "已编辑的姿势",
 	"Pose saved": "姿势已保存",
 	"Nothing to undo": "没有可撤销的操作",
+	"IK edit undone": "已撤销 IK 修改",
 	"Nothing to redo": "没有可重做的操作",
 	"Confirm Replace existing keys before applying this pin.": "应用此固定前请确认替换现有键。",
 	"Pose mode — preview the correction, then apply it to the selected motion block": "姿势模式 — 先预览修正，再应用到所选动作片段",

package/src/main.jsx

@@ -11,11 +11,14 @@ import "./styles.css";
 import { registerPwa } from "./pwa.js";
 import { LOCALE } from "./locale.js";
 import { initAnalytics } from "./analytics.js";
+import { StudioReadyMark } from "./studio-telemetry.js";
+import { listenForUnboundShortcuts } from "./shortcut-friction.js";
 import { fetchPlaygroundProject, isPlaygroundEmbed, playgroundSceneUrl, stashPlaygroundProject } from "./playground.js";
 import { preloadBodies } from "./motion3/body.js";
 
 registerPwa();
 void initAnalytics();
+listenForUnboundShortcuts();
 document.documentElement.lang = LOCALE === "zh" ? "zh-CN" : LOCALE;
 applyTheme(readTheme());
 
@@ -32,6 +35,8 @@ async function boot() {
 		<StrictMode>
 			<ErrorBoundary>
 				<App />
+				{/* studio:ready: one frame after this first commit, without delaying it. */}
+				<StudioReadyMark />
 			</ErrorBoundary>
 		</StrictMode>,
 	);

package/src/motion/timeline.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { frameFromClientX, groupKeyRuns, KEY_RUN_MIN, rangePinBandGeometry, shotBlockGeometry } from "./timeline-coordinates.js";
 import { createPlaybackClock } from "./playback-clock.js";
+import { startPlaybackRun } from "../playback-telemetry.js";
 
 import { ko } from "../locale.js";
 import { isImeComposing } from "../ime.js";
@@ -1195,14 +1196,17 @@ export default function Timeline({
 	useEffect(() => {
 		if (!playing) return;
 		const elapsedFrames = createPlaybackClock(fps, playbackSpeed, performance.now());
+		// playback:summary: steps > 1 is a late tick (an estimate of dropped frames, not a measured one).
+		const run = startPlaybackRun(fps, playbackSpeed);
 		const id = window.setInterval(
 			() => {
 				const steps = elapsedFrames(performance.now());
+				run.tick(steps);
 				if (steps) handlers.current.onAdvance?.(steps);
 			},
 			1000 / Math.max(1, fps * playbackSpeed),
 		);
-		return () => window.clearInterval(id);
+		return () => { window.clearInterval(id); run.end(); };
 	}, [playing, fps, playbackSpeed]);
 
 	// Space toggles playback, j/k step the playhead, p toggles waypoint mode —
@@ -1592,7 +1596,7 @@ export default function Timeline({
 							</button>
 							<button
 								type="button"
-								className={"tl-btn play" + (playing ? " on" : "")}
+								className={"tl-btn play" + (playing ? " on" : "")} data-fid="tl_play"
 								aria-label={playing ? ko("Pause playback", "재생 일시중지") : ko("Play playback", "재생 시작")}
 								title={ko("Play / pause (Space)", "재생/일시중지 (Space)")}
 								onClick={() => handlers.current.onPlayToggle?.()}
@@ -1849,7 +1853,7 @@ export default function Timeline({
 									{name === SHOTS_LANE && (
 										<button
 											type="button"
-											className="tl-track-add cut"
+											className="tl-track-add cut" data-fid="shot_add"
 											disabled={shotCutDisabled}
 											title={ko("Add a 2 second shot without changing existing shots", "기존 샷을 바꾸지 않고 2초 샷 추가")}
 											onClick={() => handlers.current.onShotCut?.()}
@@ -1993,7 +1997,7 @@ export default function Timeline({
 											<span className="tl-shot-actions">
 												<button type="button" title={ko("Split at the playhead", "재생 헤드에서 분할")} disabled={frame <= shot.startFrame || frame > shot.endFrame} onClick={(e) => { e.stopPropagation(); handlers.current.onShotSplit?.(shot.id); }}>{ko("Split", "분할")}</button>
 												<button type="button" title={ko("Duplicate shot", "샷 복제")} onClick={(e) => { e.stopPropagation(); handlers.current.onShotDuplicate?.(shot.id); }}>{ko("Duplicate", "복제")}</button>
-													<button type="button" title={ko("Delete shot and leave free-camera time", "샷을 지우고 자유 카메라 구간으로 비우기")} onClick={(e) => { e.stopPropagation(); handlers.current.onShotRemove?.(shot.id); }}>{ko("Delete", "삭제")}</button>
+													<button type="button" data-fid="shot_delete" title={ko("Delete shot and leave free-camera time", "샷을 지우고 자유 카메라 구간으로 비우기")} onClick={(e) => { e.stopPropagation(); handlers.current.onShotRemove?.(shot.id); }}>{ko("Delete", "삭제")}</button>
 												</span>
 												<span className="tl-shot-camera-summary">
 													<span className="tl-camera-block-state">{stateLabel}</span>
@@ -2055,7 +2059,7 @@ export default function Timeline({
 												    one gesture cannot both reorder a shot and edit a curve. */}
 												<button
 													type="button"
-													className="tl-shot-key-surface"
+													className="tl-shot-key-surface" data-fid="camera_key_add"
 													aria-label={shot.camera?.mode === "rail" && shot.camera?.craneHeight
 														? ko(`Add crane point in ${shot.name}`, `${shot.name}에 크레인 점 추가`, `在 ${shot.name} 中添加摇臂点`)
 														: ko(`Add camera key in ${shot.name}`, `${shot.name}에 카메라 키 추가`, `在 ${shot.name} 中添加摄影机关键帧`)}

package/src/motion-draft-telemetry.js

@@ -0,0 +1,62 @@
+// motion:draft_compiled: one event per motion.compile draft (commands/motion3.js, right
+// after publishDraft), so the compile -> QA -> repair loop is visible per draft. Only
+// counts, buckets and flags leave: never the spec, the take, skill names or QA text.
+// At most 50 per session; past the cap only the friction counter `compiles` moves.
+import { track } from "./analytics.js";
+import { admit, bucketFrictionCount, bucketShortMs, bump } from "./analytics-friction.js";
+import { qaProblems } from "./qa-label.js";
+
+const DRAFTS_PER_SESSION = 50;
+let send = track;
+
+function bucketQaFrames(n) {
+	if (!(n > 0)) return "0";
+	if (n <= 10) return "1-10";
+	if (n <= 50) return "11-50";
+	if (n <= 200) return "51-200";
+	return "gte201";
+}
+
+function bucketFrames(n) {
+	if (!(n >= 30)) return "lt30";
+	if (n <= 120) return "30-120";
+	if (n <= 480) return "121-480";
+	return "gte481";
+}
+
+/**
+ * The draft publishDraft just stored (`n`: its ordinal for the character this turn,
+ * from 1) and the compile result `r`: qa, ms (the whole draft: ms.repair, the repair
+ * loop's wall time with every candidate, when it ran, else ms.total, which includes QA;
+ * the pipeline has no separate QA time), frameCount, search. `flags` are the
+ * handler's own: installed, stuck, repaired, adjusted.
+ */
+export function noteDraftCompiled(draft, r, { installed = false, stuck = false, repaired = false, adjusted = false } = {}) {
+	try {
+		bump("compiles");
+		const problems = qaProblems(r?.qa);
+		const props = {
+			draft_index: bucketFrictionCount(draft?.n),
+			qa_clean: problems === 0,
+			qa_problems: bucketFrictionCount(problems),
+			// QA records one issue per frame per group (qa-label.js): frame-level issues, not distinct frames.
+			qa_frames: bucketQaFrames(r?.qa?.total ?? 0),
+			// A repaired draft compiled many candidates: ms.total is only the one it kept (compile-job.js).
+			compile: bucketShortMs(r?.ms?.repair ?? r?.ms?.total),
+			installed: Boolean(installed), stuck: Boolean(stuck), repaired: Boolean(repaired),
+			searched: Boolean(r?.search), adjusted: Boolean(adjusted),
+			frames: bucketFrames(r?.frameCount),
+		};
+		// The payload is built first: a malformed result takes no slot of the cap.
+		if (admit("motion:draft_compiled", DRAFTS_PER_SESSION)) send("motion:draft_compiled", props);
+	} catch {
+		// Telemetry must never affect a compile.
+	}
+}
+
+/** Tests only: capture what is sent; returns the restore. */
+export function draftTelemetrySeam(capture) {
+	const previous = send;
+	send = capture;
+	return () => { send = previous; };
+}

package/src/motion3/compiler/channels.js

@@ -42,23 +42,25 @@ function pchipEval(x, y, m, q) {
 }
 
 const FLOW_SMOOTH = /^(spine|chest|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
-const FLOW_LAG = { spine: 0, head: 2, arms: 3 };
+const FLOW_LAG = { spine: 0, head: 2, arms: 3 }, HEAD_LEAD = 5;
 const ARM = /^(hand|armw|elbow|aswing|abend|wflex|wtwist)_[lr]$/; // one side's arm: trails as one (overlap.js sideTrail)
 const OVER_FRAC = 0.15, OVER_MAX = 6; // a smooth segment's overshoot: at most this share of its change, and degrees
 const ikSides = ch => (/^(spine|chest|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend|wflex|wtwist)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
 const lagFamily = ch => (/^(spine|chest)_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
 
 /**
- * spec.flow -> { smooth, lag: { spine, head, arms }, overlap, seed, hands }: undefined is the default, false turns all off.
- * overlap: true (1) | false (0) | a scale of its delays and settle (overlap.js); seed (the spec's label) picks which side trails;
+ * spec.flow -> { smooth, lag: { spine, head, arms }, overlap, headLead, seed, hands }: undefined is the default, false turns all off.
+ * overlap: true (1) | false (0) | a scale of its delays and settle (overlap.js); headLead: the frames the head leads the trunk's
+ * turn by, true (HEAD_LEAD) | false (0) | frames (head-lead.js); seed (the spec's label) picks which side trails;
  * hands: the frames each hand works on something (overlap.js handBusy), where a free IK hand's trail stops.
  */
 export function flowOptions(flow, seed = "", hands = { l: [], r: [] }) {
-	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 }, overlap: 0, seed, hands };
+	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 }, overlap: 0, headLead: 0, seed, hands };
 	const f = flow ?? {}, lag = f.lag === false ? 0 : f.lag;
 	const each = typeof lag === "number" ? { spine: lag, head: lag, arms: lag } : { ...FLOW_LAG, ...(lag ?? {}) };
 	const overlap = f.overlap === false ? 0 : typeof f.overlap === "number" ? f.overlap : 1;
-	return { smooth: f.smooth !== false, lag: each, overlap, seed, hands };
+	const headLead = f.headLead === false ? 0 : typeof f.headLead === "number" ? Math.round(f.headLead) : HEAD_LEAD;
+	return { smooth: f.smooth !== false, lag: each, overlap, headLead, seed, hands };
 }
 
 /** Catmull-Rom slopes, flat at a hold and at the ends, each segment's overshoot bounded. */

package/src/motion3/compiler/compile.js

@@ -31,12 +31,13 @@ import { idleLayer, withIdle, busyHands } from "./idle.js";
 import { resolveAnchor, measureProps, armReach } from "./anchors.js";
 import { expandGenerators } from "./walk.js";
 import { steadyHead } from "./head-steady.js";
+import { leadHead } from "./head-lead.js";
 import { fixOptions, applyFixes } from "../fix/index.js";
 import { fitWeight } from "../fix/self.js";
 import { holdHook } from "../object-keys.js";
 import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
 import { objectPoseAt, handOf, restingAt, frameAt, spanOf } from "../object-pose.js";
-import { heldFor } from "./finger-close.js";
+import { heldFor, carryFingers } from "./finger-close.js";
 import { sagOf } from "../load.js";
 
 const smooth = x => x * x * (3 - 2 * x);
@@ -143,6 +144,7 @@ function hooksFor(ctx, c, f, inFit = false, lead = true, fitSide = null) {
 		sag: inFit ? undefined : (k, s, target) => sagOf(ctx, k, f, s, target, (1 - fitWeight(ctx.spec, c, k)) * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0))),
 		// fingers close on what the hand holds, on the final pose only (finger-close.js)
 		heldShapes: inFit || !ctx.grasp ? undefined : (k, s) => heldFor(ctx, c, f, k, s),
+		fingerWeights: inFit || !ctx.grasp ? undefined : k => carryFingers(ctx, c, f, k),
 	};
 }
 
@@ -209,10 +211,12 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
-			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow, spec.label ?? "", handBusy(spec)));
+			const flow = flowOptions(spec.flow, spec.label ?? "", handBusy(spec));
+			out.baked = bakeChannels(keys, frameCount, flow);
 			ctx.socketTurns = new Map();
 			ctx.graspPlans = new Map();
 			steadyHead(out.baked, keys, frameCount);
+			leadHead(out.baked, keys, frameCount, flow.headLead);
 			// a held pose breathes and shifts its weight (idle.js): offsets solveFrame adds, contacts and out.baked stay as keyed
 			ctx.idle = idleLayer(out.baked, { spec, sk, frameCount });
 			ctx.busy = busyHands(out.baked, spec, frameCount, out.fps);

package/src/motion3/compiler/finger-close.js

@@ -8,14 +8,15 @@
 // then turned once; weighted by how far the hand holds (a fit's weight), so the fingers close over the reach and open
 // on the release. A joint the preset curled into the body straightens when that leaves the finger shallower; a
 // joint whose sub-chain already touches stays, and the next joint out closes on: the finger wraps the body.
-import { add, sub, scale, norm, cross, apply, axisRot } from "./math.js";
+import { add, sub, scale, norm, cross, dot, apply, axisRot } from "./math.js";
 import { rotateSubtree } from "./skeleton.js";
 import { palmAxes, fingerCurl, fistCurl } from "./limbs.js";
-import { capsuleDepth } from "../shapes.js";
+import { capsuleDepth, shapeOf } from "../shapes.js";
+import { GRASP_FINGERS } from "./vocab.js";
 import { partsOf } from "../object-pose.js";
 import { seatsInHand } from "../seat.js";
 
-const PHALANX = 0.009, TOUCH = 0.002, STEPS = 8, THUMB_FLEX = 70;
+const PHALANX = 0.009, TOUCH = 0.002, STEPS = 8, THUMB_FLEX = 70, SPREAD_STEP = 5, SPREAD_MAX = 15, SELF_GAP = 0.014;
 const FINGERS = ["Index", "Middle", "Ring", "Pinky"];
 // the hand stays open for most of a reach and closes as it arrives: from OPEN_UNTIL of the fit's weight to CLOSED_AT
 const OPEN_UNTIL = 0.6, CLOSED_AT = 0.9;
@@ -49,6 +50,34 @@ function clearTurn(points, pivot, axis, limit, entries) {
 	return hi;
 }
 
+const saveChain = (sk, s, j) => new Map(sk.subtree[j].map(i => [i, [s.P[i].slice(), s.R[i].map(r => r.slice())]]));
+const restoreChain = (s, saved) => { for (const [i, [p, r]] of saved) { s.P[i] = p.slice(); s.R[i] = r.map(row => row.slice()); } };
+
+/** Degrees each of joints 1..3 of finger f is flexed: each phalanx against the one before about the knuckle line. */
+function flexion(sk, s, side, f) {
+	const P = i => s.P[sk.index[`${side}Hand${f}${i}`]], { d, l } = palmAxes(sk, s, side), axis = scale(l, side === "Left" ? -1 : 1);
+	const flat = v => norm(sub(v, scale(axis, dot(v, axis)))), bone = [1, 2, 3].map(i => flat(norm(sub(P(i + 1), P(i)))));
+	return [flat(d), bone[0], bone[1]].map((a, i) => (Math.atan2(dot(cross(a, bone[i]), axis), dot(a, bone[i])) * 180) / Math.PI);
+}
+
+/** Closest distance between segments p1-q1 and p2-q2. */
+function segmentGap(p1, q1, p2, q2) {
+	const d1 = sub(q1, p1), d2 = sub(q2, p2), r = sub(p1, p2), a = dot(d1, d1), e = dot(d2, d2), f = dot(d2, r), c = dot(d1, r), b = dot(d1, d2);
+	const den = a * e - b * b, clamp = x => Math.min(1, Math.max(0, x));
+	let t1 = den > 1e-12 ? clamp((b * f - c * e) / den) : 0, t2 = e > 1e-12 ? (b * t1 + f) / e : 0;
+	if (t2 < 0) { t2 = 0; t1 = clamp(-c / a); } else if (t2 > 1) { t2 = 1; t1 = clamp((b - c) / a); }
+	return Math.hypot(...sub(add(p1, scale(d1, t1)), add(p2, scale(d2, t2))));
+}
+
+/** True when no phalanx of finger f lies within SELF_GAP of a phalanx of another (non-thumb) finger. */
+function clearOfNeighbours(sk, s, side, f) {
+	const P = name => s.P[sk.index[`${side}Hand${name}`]];
+	for (const g of FINGERS) if (g !== f) for (let a = 1; a <= 3; a++) for (let b = 1; b <= 3; b++) {
+		if (segmentGap(P(`${f}${a}`), P(`${f}${a + 1}`), P(`${g}${b}`), P(`${g}${b + 1}`)) < SELF_GAP) return false;
+	}
+	return true;
+}
+
 /** Turns joint j by the touching turn about `axis` (or `limit` when it never touches, unless `air` is false), weighted; true when it touched. */
 function closeJoint(sk, s, j, chain, axis, limit, entries, weight, air = true) {
 	const turn = touchTurn(chain.map(i => s.P[i]), s.P[j], axis, limit, entries), deg = turn ?? (air ? limit : 0);
@@ -66,9 +95,7 @@ export function closeOnShape(sk, s, side, { entries: held, stops = [], weight, p
 	// a finger stops on what it holds or on what that rests against (a table under a ball)
 	const entries = [...held, ...stops];
 	const sign = side === "Left" ? -1 : 1, J = name => sk.index[`${side}Hand${name}`], touched = [];
-	for (const f of FINGERS) {
-		const joints = [1, 2, 3, 4].map(i => J(`${f}${i}`));
-		if (joints.some(j => j === undefined)) continue;
+	const close = (f, joints) => {
 		let tip = false;
 		// a finger the preset curled into the body straightens, joint by joint, when the straight finger is shallower (a
 		// finger lying across a box would go deeper); each joint then closes until the finger touches
@@ -80,6 +107,35 @@ export function closeOnShape(sk, s, side, { entries: held, stops = [], weight, p
 			if (open > 0) rotateSubtree(sk, s, joints[k], s.P[joints[k]].slice(), axisRot(axis, -open * weight));
 			tip = closeJoint(sk, s, joints[k], joints.slice(k), axis, Math.max(0, fistCurl(f, k) - curl + open), entries, weight, false);
 		}
+		return tip;
+	};
+	for (const f of FINGERS) {
+		const joints = [1, 2, 3, 4].map(i => J(`${f}${i}`));
+		if (joints.some(j => j === undefined)) continue;
+		const before = saveChain(sk, s, joints[0]);
+		let tip = close(f, joints);
+		// a finger whose curl passes beside what it holds (a ring or little finger off a ball's side) turns toward it at the
+		// knuckle, SPREAD_STEP at a time up to SPREAD_MAX, and closes again; kept when it touches without lying in a neighbour
+		if (!tip && f !== "Middle") {
+			const after = saveChain(sk, s, joints[0]), { l, n } = palmAxes(sk, s, side);
+			const toward = Math.sign(dot(sub(held[0].pos, before.get(joints[0])[0]), l)) * sign;
+			for (let deg = SPREAD_STEP; deg <= SPREAD_MAX && !tip; deg += SPREAD_STEP) {
+				restoreChain(s, before);
+				rotateSubtree(sk, s, joints[0], s.P[joints[0]].slice(), axisRot(n, toward * sign * deg * weight));
+				tip = close(f, joints) && clearOfNeighbours(sk, s, side, f);
+			}
+			if (!tip) restoreChain(s, after);
+		}
+		// a finger that still cannot reach it curls with the finger next in toward the middle (the ring and little fingers
+		// move together), joint by joint as far as that finger's flexion, stopping where it touches
+		const inner = { Ring: "Middle", Pinky: "Ring" }[f];
+		if (!tip && inner) {
+			const axis = scale(palmAxes(sk, s, side).l, sign);
+			for (let k = 0; k < 3; k++) {
+				const more = flexion(sk, s, side, inner)[k] - flexion(sk, s, side, f)[k];
+				if (more > 1) tip = closeJoint(sk, s, joints[k], joints.slice(k), axis, more, entries, weight, true);
+			}
+		}
 		if (tip) touched.push(f);
 	}
 	const thumb = [1, 2, 3, 4].map(i => J(`Thumb${i}`));
@@ -119,6 +175,27 @@ export function heldFor(ctx, c, f, k, s) {
 	return best ?? carriedFor(ctx, c, f, k, s);
 }
 
+// A carry outlives the reach that took it: reachGrip lets its grip go after `hold` while the object stays in the hand, and
+// the thumb, wrapped by the grip preset (limbs.js THUMB_WRAP), swung back out 2.3 cm off the ball it held. While hand k
+// holds a seated carry, its grasp's preset is on at full weight, eased in over SETTLE frames from the grab and out over
+// SETTLE before a release (a carry that runs to the end of the take stays held).
+const SETTLE = 4;
+const graspOf = (o, scene, id) => o.grasp ?? ({ sphere: "spherical", cylinder: "power" }[partsOf(scene, id).length === 1 ? shapeOf(scene.objects[partsOf(scene, id)[0]]).kind : "box"] ?? "palm");
+
+/** The finger preset weights of hand k at frame f with channels c: the channel's, with a seated carry's grasp preset held on. */
+export function carryFingers(ctx, c, f, k) {
+	const { spec, scene } = ctx, own = c[`fingers_${k}`];
+	for (const [id, o] of Object.entries(spec.objects ?? {})) {
+		if (!seatsInHand(spec, o, scene, id) || spec.props?.[o.prop]?.hand !== k) continue;
+		const [grab, release] = ctx.carrySpan(o), on = Math.min(1, (f - grab) / SETTLE, o.release === undefined ? 1 : (release - f) / SETTLE);
+		if (!(on > 0)) continue;
+		const preset = GRASP_FINGERS[graspOf(o, scene, id)];
+		if (preset === "relaxed") return own;
+		return { ...own, [preset]: Math.max(own?.[preset] ?? 0, on) };
+	}
+	return own;
+}
+
 /** A carry on the grasp path hand k holds at frame f, at its seat on pose s (seat.js), as { entries, weight, preset }. */
 function carriedFor(ctx, c, f, k, s) {
 	const { spec, scene } = ctx;
@@ -131,7 +208,7 @@ function carriedFor(ctx, c, f, k, s) {
 		// where it is on this pose (object-pose.js: easing into its seat over the settle, as it is drawn), not the full seat
 		const entries = partsOf(scene, id).map(p => ({ ...scene.objects[p], ...ctx.objectPose(p, f, { s }) }));
 		const near = Object.entries(ctx.objectsAt(f)).filter(([key, e]) => !partsOf(scene, id).includes(key) && e.half && !e.carried && entries.some(h => Math.hypot(...h.pos.map((v, i) => v - e.pos[i])) < 0.25 + Math.hypot(...e.half))).map(([, e]) => e);
-		if (entries.length) return { entries, stops: near, weight, preset: c[`fingers_${k}`] };
+		if (entries.length) return { entries, stops: near, weight, preset: carryFingers(ctx, c, f, k) };
 	}
 	return null;
 }

package/src/motion3/compiler/head-lead.js

@@ -0,0 +1,70 @@
+// When the trunk turns the head turns first: a person's head leads the pelvis into a turn by about 200 ms (about 5
+// frames at 24 fps), walking or standing. The head takes the turn the trunk (the root's and the spine's yaw) makes
+// over the next LEAD frames, no more than MAX degrees (half the neck's turn one way); inside a walk its heading, so the
+// head leads the walk's turns, not each step's sway (head-steady.js steadies that). Inside every walk (start to last
+// step, head-steady.js walkSpans) and around every turn of the trunk faster than TURN deg/frame (from LEAD + FADE
+// frames before it, so the head starts first), faded in and out over FADE frames, and never where the spec's own keys move
+// head_yaw during that span (keys on it, or on either side of it, that differ): a keyed look wins; a head held still
+// (a stance's head_yaw 0) leads.
+import { walkSpans } from "./head-steady.js";
+
+const MAX = 30, TURN = 0.3, FADE = 8, STRIDE = 33;
+
+/** Inside a walk the trunk's heading, its sway each step taken out: the median over about a stride keeps a turn's timing. */
+function heading(trunk, walks) {
+	const out = trunk.slice(), half = Math.floor(STRIDE / 2), n = trunk.length;
+	for (const [f0, f1] of walks) for (let f = Math.max(0, f0); f <= Math.min(n - 1, f1); f++) {
+		const w = trunk.slice(Math.max(0, f - half), Math.min(n, f + half + 1)).sort((a, b) => a - b);
+		out[f] = w.length % 2 ? w[(w.length - 1) / 2] : (w[w.length / 2 - 1] + w[w.length / 2]) / 2;
+	}
+	return out;
+}
+
+/** Frame runs [f0, f1] (inclusive) where the trunk turns faster than TURN, widened by `before` and `after` frames. */
+function turnSpans(trunk, frameCount, before, after) {
+	const spans = [];
+	for (let f = 0; f < frameCount - 1; f++) {
+		if (Math.abs(trunk[f + 1] - trunk[f]) <= TURN) continue;
+		const a = Math.max(0, f - before), b = Math.min(frameCount - 1, f + 1 + after), last = spans.at(-1);
+		if (last && a <= last[1] + 1) last[1] = Math.max(last[1], b);
+		else spans.push([a, b]);
+	}
+	return spans;
+}
+
+/** Overlapping or touching spans joined. */
+function merged(spans) {
+	const out = [];
+	for (const [a, b] of [...spans].sort((x, y) => x[0] - y[0])) {
+		const last = out.at(-1);
+		if (last && a <= last[1] + 1) last[1] = Math.max(last[1], b);
+		else out.push([a, b]);
+	}
+	return out;
+}
+
+/** The keys outside walks that move head_yaw during [f0, f1]: those in it and the nearest on either side differ. */
+function looked(keys, f0, f1) {
+	const looks = keys.filter(k => k.set?.head_yaw !== undefined && !/\bwalk(To)? (start|step \d+|end)$/.test(k.src ?? "")).sort((a, b) => a.f - b.f);
+	const near = [looks.filter(k => k.f < f0).at(-1), ...looks.filter(k => k.f >= f0 && k.f <= f1), looks.find(k => k.f > f1)].filter(Boolean);
+	return near.some(k => JSON.stringify(k.set.head_yaw) !== JSON.stringify(near[0].set.head_yaw));
+}
+
+/** Adds the turn the trunk makes over the next `lead` frames to the baked head yaw (in place); lead 0 is off. */
+export function leadHead(baked, keys, frameCount, lead = 5) {
+	if (!(lead > 0)) return;
+	const zero = new Array(frameCount).fill(0), yaw = baked.yaw ?? zero, spine = baked.spine_yaw ?? zero;
+	// a retime keeps its keys on fractional frames (fix/retime.js): the spans are frame indices
+	const walks = walkSpans(keys).map(([a, b]) => [Math.ceil(a), Math.floor(b)]), trunk = heading(yaw.map((v, f) => v + spine[f]), walks), at = f => trunk[Math.min(frameCount - 1, f)];
+	const spans = merged([...walks, ...turnSpans(trunk, frameCount, lead + FADE, FADE)]);
+	let head = null;
+	for (const [f0, f1] of spans) {
+		if (looked(keys, f0, f1)) continue;
+		head ??= (baked.head_yaw ?? zero).slice();
+		for (let f = Math.max(0, f0); f <= Math.min(frameCount - 1, f1); f++) {
+			const fade = Math.min(1, (f - f0) / FADE, (f1 - f) / FADE), d = Math.max(-MAX, Math.min(MAX, at(f + lead) - trunk[f]));
+			head[f] += d * fade * fade * (3 - 2 * fade);
+		}
+	}
+	if (head) baked.head_yaw = head;
+}

package/src/motion3/compiler/head-steady.js

@@ -9,7 +9,7 @@ const STEADY = { yaw: 0.5, pitch: 0.2, roll: 0.7 }, LIMIT = { yaw: 4, pitch: 6,
 const AXES = ["yaw", "pitch", "roll"];
 
 /** The walk spans in the keys, start to last step: [[f0, f1], ...]. */
-function walkSpans(keys) {
+export function walkSpans(keys) {
 	const spans = new Map();
 	for (const k of keys) {
 		const m = / (start|step \d+)$/.exec(k.src ?? ""), tag = m && k.src.slice(0, -m[0].length);