cozyclay 3.1.4 → 3.1.5

package/src/motion3/compiler/limbs.js

@@ -164,17 +164,24 @@ const FINGER_PRESETS = {
 // thumb side (+), by preset weight; the index leads the thumb round one side, the little finger the other.
 const SPREAD = { spherical: { Index: 9, Middle: 2, Ring: -5, Pinky: -12 } };
 
+// Two presets keyed at 1 together (a reach's grip over a held fist) would add their curls: 137 deg at the PIP. Past a
+// sum of 1 the weights share it, so a blend never curls further than its strongest preset.
+function shares(weights) {
+	const sum = Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (p === "relaxed" ? 0 : w || 0), 0);
+	return sum > 1 ? Object.fromEntries(Object.entries(weights).map(([p, w]) => [p, p === "relaxed" ? w : (w || 0) / sum])) : weights;
+}
+
 /** Degrees phalanx k (0..2) of finger f curls at preset weights `weights` (blended over relaxed). */
 export function fingerCurl(weights, f, k) {
 	const base = FINGER_PRESETS.relaxed;
-	return base[f][k] + Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
+	return base[f][k] + Object.entries(shares(weights) ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * ((FINGER_PRESETS[p]?.[f]?.[k] ?? base[f][k]) - base[f][k]), 0);
 }
 /** The fist's curl of phalanx k of finger f: as far as a finger closes. */
 export const fistCurl = (f, k) => FINGER_PRESETS.fist[f][k];
 
 /** Blend presets by weight over `relaxed` and curl every finger toward the palm. */
-export function fingers(sk, s, side, weights) {
-	const sign = side === "Left" ? -1 : 1, curl = (f, k) => fingerCurl(weights, f, k);
+export function fingers(sk, s, side, given) {
+	const weights = shares(given), sign = side === "Left" ? -1 : 1, curl = (f, k) => fingerCurl(weights, f, k);
 	for (const f of ["Index", "Middle", "Ring", "Pinky"]) {
 		const spread = Object.entries(weights ?? {}).reduce((acc, [p, w]) => acc + (w || 0) * (SPREAD[p]?.[f] ?? 0), 0), j = sk.index[`${side}Hand${f}1`];
 		if (spread && j !== undefined) rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(palmAxes(sk, s, side).n, spread));

package/src/motion3/compiler/pose.js

@@ -165,7 +165,7 @@ export function pose(sk, c, hooks = {}) {
 			if (fold > ELBOW_FOLD && !hooks.foldFree) diag[`arm_fold_${k}`] = fold;
 		}
 		wrist(sk, s, side, num(c[`wtwist_${k}`]), num(c[`wflex_${k}`]));
-		fingers(sk, s, side, c[`fingers_${k}`]);
+		fingers(sk, s, side, hooks.fingerWeights?.(k) ?? c[`fingers_${k}`]);
 		const held = hooks.hold?.(k, s);
 		// a keyed carry's hand follows its object; else a fit's hand takes a grip on the body under its anchor (grip.js),
 		// and while the keys only ease in (before the first key) the arm they ease from takes it too

package/src/motion3/compiler/validate.js

@@ -107,14 +107,16 @@ function validateKeys(spec, err, frames, unknown, past = "") {
  * checked when given.
  * lenient (a saved take compiled again, take-source.js) ignores unknown fields.
  */
-/** spec.flow: false, or { smooth?: boolean, lag?: false | 0..6 frames | { spine?, head?, arms? }, overlap?: boolean | 0..2 } (channels.js, overlap.js). */
+/** spec.flow: false, or { smooth?: boolean, lag?: false | 0..6 frames | { spine?, head?, arms? }, overlap?: boolean | 0..2, headLead?: boolean | 0..12 frames } (channels.js, overlap.js, head-lead.js). */
 function validateFlow(flow, err, unknown) {
 	if (flow === undefined || flow === false) return;
-	if (!flow || typeof flow !== "object" || Array.isArray(flow)) return err(`spec.flow must be false or { smooth?, lag?, overlap? }, got ${fmt(flow)}`);
-	for (const k of Object.keys(flow)) if (!["smooth", "lag", "overlap"].includes(k)) unknown(`spec.flow has unknown field "${k}" (fields: smooth, lag, overlap)`);
+	if (!flow || typeof flow !== "object" || Array.isArray(flow)) return err(`spec.flow must be false or { smooth?, lag?, overlap?, headLead? }, got ${fmt(flow)}`);
+	for (const k of Object.keys(flow)) if (!["smooth", "lag", "overlap", "headLead"].includes(k)) unknown(`spec.flow has unknown field "${k}" (fields: smooth, lag, overlap, headLead)`);
 	if (flow.smooth !== undefined && typeof flow.smooth !== "boolean") err(`spec.flow.smooth must be true or false, got ${fmt(flow.smooth)}`);
 	const o = flow.overlap;
 	if (o !== undefined && typeof o !== "boolean" && !(Number.isFinite(o) && o >= 0 && o <= 2)) err(`spec.flow.overlap must be true, false or a scale 0..2, got ${fmt(o)}`);
+	const h = flow.headLead;
+	if (h !== undefined && typeof h !== "boolean" && !(Number.isInteger(h) && h >= 0 && h <= 12)) err(`spec.flow.headLead must be true, false or 0..12 whole frames, got ${fmt(h)}`);
 	const frames = v => Number.isFinite(v) && v >= 0 && v <= 6, lag = flow.lag, LAG = "false, 0..6 frames or { spine?, head?, arms? }";
 	if (lag === undefined || lag === false || frames(lag)) return;
 	if (!lag || typeof lag !== "object" || Array.isArray(lag)) return err(`spec.flow.lag must be ${LAG}, got ${fmt(lag)}`);

package/src/motion3/pipeline.js

@@ -32,6 +32,7 @@ import { observeNear, NEAR_UNITS } from "./qa/near.js";
 import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
 import { observeLoad, LOAD_UNITS } from "./load.js";
 import { observeLife, LIFE_UNITS } from "./qa/motion-life.js";
+import { observeGait, GAIT_UNITS } from "./qa/gait-observe.js";
 import { planWalks, applyWalkPlans } from "./walk-plan.js";
 import { relaxSpec } from "./lenient.js";
 import { observeAsked } from "./qa/asked.js";
@@ -128,6 +129,9 @@ function compilePrepared(prepared, { sk, scene }, opts, notes, refusals) {
 	const load = observeLoad(sk, out);
 	if (load) Object.assign(observations, { units: `${observations.units}; ${LOAD_UNITS}`, load });
 	Object.assign(observations, { units: `${observations.units}; ${LIFE_UNITS}`, life: observeLife(sk, out, resolved?.keys) });
+	const gait = observeGait(sk, out, out.keys);
+	// a walk too short to read is its steps alone, which need no units (the answer budget)
+	if (gait) Object.assign(observations, gait.cadence ? { units: `${observations.units}; ${GAIT_UNITS}`, gait } : { gait });
 	// a skill that paced its beats to fit a short span says so where every answer keeps it (C7 tier 1)
 	const paced = used.filter(u => u.paced).map(u => `${u.skill} paced ${u.paced.toFixed(2)} to fit f${u.f0}..f${u.end}`);
 	if (paced.length) observations.paced = paced;

package/src/motion3/qa/explain.js

@@ -10,9 +10,10 @@ import { goalHints } from "./hints-goal.js";
 import { wristHints } from "./wrist-checks.js";
 import { loadHints } from "../load.js";
 import { graspHints } from "./hints-grasp.js";
+import { fingerHints } from "./finger-checks.js";
 import { attachPatches } from "./patch.js";
 
-const HINTS = { ...contactHints, ...motionHints, ...objectHints, ...goalHints, ...wristHints, ...loadHints, ...graspHints };
+const HINTS = { ...contactHints, ...motionHints, ...objectHints, ...goalHints, ...wristHints, ...loadHints, ...graspHints, ...fingerHints };
 
 function keyTable(out) {
 	const byCh = new Map();

package/src/motion3/qa/finger-checks.js

@@ -0,0 +1,80 @@
+// Is each finger a finger a hand can make? grasp-checks.js judges a finger only against what the hand holds: a phalanx
+// into it, a fingertip off it. A finger bent backwards, curled past its range or lying in its neighbour passed while the
+// other three tips still touched, and a hand with nothing in it was not judged at all (30 finger mutations of the can and
+// ball takes: 16 passed). These checks read the pose alone, on every frame of either hand:
+//   FINGER_ROM   "<Bone> bent back" / "<Bone> curled past range": a joint's flexion about the hand's knuckle line, each
+//                phalanx against the one before (the first against the palm's finger axis), outside its band in degrees
+//                (MCP, PIP, DIP; active ranges of motion: flexion 85-90 / 100-115 / 80-90, extension 30-45 / 0 / 20)
+//   FINGER_SELF  "<Bone> into <Bone>": two phalanges of different fingers (the thumb aside: it lies on the index by
+//                design) closer than two phalanx radii less PEN, as FINGER_PEN measures a phalanx in a held thing
+// A rig without finger joints is not judged.
+import { add, sub, scale, dot, cross, norm } from "../compiler/math.js";
+import { palmAxes } from "../compiler/limbs.js";
+
+const PHALANX = 0.009, PEN = 0.004, SIDES = ["Left", "Right"], FINGERS = ["Index", "Middle", "Ring", "Pinky"];
+// degrees per joint (1 MCP, 2 PIP, 3 DIP): [most extension, most flexion]
+const ROM = [[-45, 100], [-5, 115], [-20, 90]];
+const deg = r => (r * 180) / Math.PI;
+
+/** Signed angle (deg) from a to b about unit axis, both projected on the plane normal to it. */
+function turn(a, b, axis) {
+	const pa = norm(sub(a, scale(axis, dot(a, axis)))), pb = norm(sub(b, scale(axis, dot(b, axis))));
+	return deg(Math.atan2(dot(cross(pa, pb), axis), dot(pa, pb)));
+}
+
+/** The flexion (deg) of joints 1..3 of finger f of hand S on pose s; null when the rig lacks the finger. */
+export function fingerFlexion(sk, s, S, f) {
+	const J = [1, 2, 3, 4].map(i => sk.index[`${S}Hand${f}${i}`]);
+	if (J.some(j => j === undefined)) return null;
+	const { d, l } = palmAxes(sk, s, S), knuckle = scale(l, S === "Left" ? -1 : 1);
+	const bone = [0, 1, 2].map(i => norm(sub(s.P[J[i + 1]], s.P[J[i]])));
+	return [d, bone[0], bone[1]].map((prev, i) => turn(prev, bone[i], knuckle));
+}
+
+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 s = den > 1e-12 ? clamp((b * f - c * e) / den) : 0, t = e > 1e-12 ? (b * s + f) / e : 0;
+	if (t < 0) { t = 0; s = clamp(-c / a); } else if (t > 1) { t = 1; s = clamp((b - c) / a); }
+	return Math.hypot(...sub(add(p1, scale(d1, s)), add(p2, scale(d2, t))));
+}
+
+function handIssues(sk, s, S, push, frame) {
+	for (const f of FINGERS) {
+		const flex = fingerFlexion(sk, s, S, f);
+		if (!flex) return;
+		flex.forEach((a, i) => {
+			const [lo, hi] = ROM[i], bone = `${S}Hand${f}${i + 1}`;
+			if (a < lo) push("FINGER_ROM", `${bone} bent back`, frame, -a, -lo);
+			else if (a > hi) push("FINGER_ROM", `${bone} curled past range`, frame, a, hi);
+		});
+	}
+	const P = name => s.P[sk.index[`${S}Hand${name}`]];
+	for (let i = 0; i < FINGERS.length; i++) for (let j = i + 1; j < FINGERS.length; j++) {
+		let worst = null;
+		for (let a = 1; a <= 3; a++) for (let b = 1; b <= 3; b++) {
+			const overlap = 2 * PHALANX - segmentGap(P(`${FINGERS[i]}${a}`), P(`${FINGERS[i]}${a + 1}`), P(`${FINGERS[j]}${b}`), P(`${FINGERS[j]}${b + 1}`));
+			if (overlap > PEN && (!worst || overlap > worst.overlap)) worst = { overlap, a, b };
+		}
+		if (worst) push("FINGER_SELF", `${S}Hand${FINGERS[i]}${worst.a} into ${S}Hand${FINGERS[j]}${worst.b}`, frame, worst.overlap, PEN);
+	}
+}
+
+/** FINGER_ROM and FINGER_SELF issues of both hands on every frame (frames index out.frames, as every check's). */
+export function fingerChecks(sk, out) {
+	const issues = [], push = (kind, msg, frame, value, limit) => issues.push({ kind, msg, frame, value: +value.toFixed(4), limit });
+	const sides = SIDES.filter(S => sk.index[`${S}Hand`] !== undefined);
+	out.frames.forEach((fr, i) => { for (const S of sides) handIssues(sk, fr.s, S, push, i); });
+	return issues;
+}
+
+export const fingerHints = {
+	FINGER_ROM(X, g) {
+		const k = g.subject.startsWith("Left") ? "l" : "r";
+		return { cause: X.cause(`fingers_${k}`, g.worstFrame), hint: `fingers_${k}: a joint is past what a finger does (${g.subject}); keep the preset weights summing to at most 1 and do not turn a phalanx past its curl` };
+	},
+	FINGER_SELF(X, g) {
+		const k = g.subject.startsWith("Left") ? "l" : "r";
+		return { cause: X.cause(`fingers_${k}`, g.worstFrame), hint: `fingers_${k}: two fingers lie in each other (${g.subject}); give them one preset so they curl side by side` };
+	},
+};

package/src/motion3/qa/gait-observe.js

@@ -0,0 +1,88 @@
+// Measured, not judged (output.observations.gait): how a take's walks compare with a person's. Only inside the walks
+// (start to last step, compiler/head-steady.js walkSpans, and the PAD frames after it where the last step lands). A
+// heel strikes where its sole point comes down under QA's plant height (QA_LIMITS.plantH). From the strikes: the
+// steps, the cadence (steps a minute), the step length and speed (the hips' travel strike to strike). Over each
+// stride (a foot's strike to its next): the share of it that foot is on the ground (heel or ball planted), and the
+// pelvis's peak-to-peak motion with the stride's own trend taken out (so a turn or a slope does not count): its turn
+// (the hip line's yaw), its obliquity (the hip line's tilt), its rise and fall (the hips' height) and its side to side
+// (the hips off the stride's line). Warnings past the ranges (RANGES) a person's walk keeps; never a QA group,
+// never qa.ok. No walk, no gait; under MIN_STEPS steps only the steps (too few strides to read; the answer budget).
+// Ranges: pelvis rotation 9.5 +-2 SD and obliquity 7.4 +-2 SD degrees (Bruening et al. 2017, 44 adults); cadence
+// normal 100-115, warned outside 80-140; stance 60% of a stride; the hips' rise and fall 2.7-5 cm is provisional.
+import { walkSpans } from "../compiler/head-steady.js";
+import { groundSole } from "./ground.js";
+import { QA_LIMITS } from "./checks.js";
+
+const DEG = 180 / Math.PI, PAD = 12, MIN_STEPS = 4;
+const RANGES = { cadence: [80, 140], stance: [0.55, 0.65], rotation: [3.7, 15.3], obliquity: [2.4, 12.4], vertical: [2.7, 5] };
+const r = (x, d) => Math.round(x * 10 ** d) / 10 ** d;
+
+export const GAIT_UNITS = "gait (walks, warnings not QA): cadence [steps/min, normal]; stepLength m; speed m/s; stance [L, R] stride share down; pelvis p-p a stride: rotation, obliquity deg, vertical (range provisional), lateral cm";
+
+/** Peak to peak of xs[a..b] less the line from xs[a] to xs[b]. */
+function swing(xs, a, b) {
+	let lo = Infinity, hi = -Infinity;
+	for (let f = a; f <= b; f++) {
+		const v = xs[f] - (xs[a] + ((xs[b] - xs[a]) * (f - a)) / (b - a));
+		lo = Math.min(lo, v); hi = Math.max(hi, v);
+	}
+	return hi - lo;
+}
+
+const unwrap = xs => xs.reduce((o, v, i) => (o.push(i ? o[i - 1] + (v - xs[i - 1]) - 360 * Math.round((v - xs[i - 1]) / 360) : v), o), []);
+const mean = xs => xs.reduce((a, b) => a + b, 0) / xs.length;
+
+/** One stride [a, b]: the pelvis's rotation, obliquity (deg) and vertical, lateral (cm) peak to peak. */
+function pelvisOf(hipLine, hips, a, b) {
+	const [ax, , az] = hips[a], dx = hips[b][0] - ax, dz = hips[b][2] - az, d = Math.hypot(dx, dz) || 1;
+	const side = hips.map(p => ((p[0] - ax) * dz - (p[2] - az) * dx) / d);
+	return [swing(hipLine.yaw, a, b), swing(hipLine.tilt, a, b), 100 * swing(hips.map(p => p[1]), a, b), 100 * swing(side, a, b)];
+}
+
+/** observeGait(sk, out, keys) -> observations.gait or null; keys are the compiled keys (walk.js tags their src). */
+export function observeGait(sk, out, keys) {
+	const F = out.frames, n = F.length, f0 = out.f0 ?? 0, fps = out.fps ?? 24, I = sk.index;
+	// a retime keeps its keys on fractional frames (fix/retime.js): the spans are frame indices
+	const spans = walkSpans(keys ?? []).map(([a, b]) => [Math.max(0, Math.round(a - f0)), Math.min(n - 1, Math.round(b - f0) + PAD)]).filter(([a, b]) => b > a);
+	if (!spans.length) return null;
+	const sole = { Left: [], Right: [] };
+	for (const [a, b] of spans) for (let f = a; f <= b; f++) for (const S of ["Left", "Right"]) sole[S][f] ??= groundSole(out, f, S);
+	const hips = F.map(({ s }) => s.P[I.Hips]), line = F.map(({ s }) => { const p = s.P[I.LeftUpLeg], q = s.P[I.RightUpLeg]; return [q[0] - p[0], q[1] - p[1], q[2] - p[2]]; });
+	const hipLine = { yaw: unwrap(line.map(v => Math.atan2(v[0], v[2]) * DEG)), tilt: line.map(v => Math.atan2(v[1], Math.hypot(v[0], v[2])) * DEG) };
+	let steps = 0, time = 0, path = 0;
+	const stance = { Left: [], Right: [] }, pelvis = [];
+	for (const [a, b] of spans) {
+		const strikes = [];
+		for (const S of ["Left", "Right"]) {
+			const own = [];
+			for (let f = a + 1; f <= b; f++) if (sole[S][f].heel[1] < QA_LIMITS.plantH && sole[S][f - 1].heel[1] >= QA_LIMITS.plantH) own.push(f);
+			strikes.push(...own);
+			for (let i = 1; i < own.length; i++) {
+				const [s0, s1] = [own[i - 1], own[i]];
+				let down = 0;
+				for (let f = s0; f < s1; f++) down += Math.min(sole[S][f].heel[1], sole[S][f].ball[1]) < QA_LIMITS.plantH ? 1 : 0;
+				stance[S].push(down / (s1 - s0));
+				pelvis.push(pelvisOf(hipLine, hips, s0, s1));
+			}
+		}
+		strikes.sort((x, y) => x - y);
+		if (strikes.length < 2) continue;
+		steps += strikes.length - 1;
+		time += (strikes.at(-1) - strikes[0]) / fps;
+		for (let i = 1; i < strikes.length; i++) path += Math.hypot(hips[strikes[i]][0] - hips[strikes[i - 1]][0], hips[strikes[i]][2] - hips[strikes[i - 1]][2]);
+	}
+	if (steps < MIN_STEPS || !pelvis.length) return { steps };
+	const cadence = (steps / time) * 60, st = ["Left", "Right"].map(S => (stance[S].length ? r(mean(stance[S]), 2) : null));
+	const [rotation, obliquity, vertical, lateral] = [0, 1, 2, 3].map(i => mean(pelvis.map(p => p[i])));
+	const warnings = [], warn = (name, v, [lo, hi]) => {
+		if (v < lo) warnings.push(`${name} ${v} < ${lo}`);
+		else if (v > hi) warnings.push(`${name} ${v} > ${hi}`);
+	};
+	warn("cadence", r(cadence, 1), RANGES.cadence);
+	st.forEach((v, i) => v !== null && warn(`stance ${"LR"[i]}`, v, RANGES.stance));
+	warn("rotation", r(rotation, 1), RANGES.rotation);
+	warn("obliquity", r(obliquity, 1), RANGES.obliquity);
+	warn("vertical", r(vertical, 2), RANGES.vertical);
+	return { steps, cadence: [r(cadence, 1), "100-115"], stepLength: r(path / steps, 3), speed: r(path / time, 2), stance: st,
+		pelvis: { rotation: r(rotation, 1), obliquity: r(obliquity, 1), vertical: r(vertical, 2), lateral: r(lateral, 2) }, warnings };
+}

package/src/motion3/qa/grasp-checks.js

@@ -9,6 +9,7 @@
 // The fingers are phalanx capsules
 // (PHALANX m) against the held object's shapes (shapes.js: a ball is round, not its box):
 //   FINGER_PEN  "<Bone> into <id>": a phalanx's skin deeper than PEN in it
+//   THUMB_OFF   "<side> thumb off <id>": a power or spherical hold whose fingers grip it with the thumb tip farther than GAP
 //   FINGER_GAP  "<side> fingers off <id>": fewer than 3 of the 4 fingertips within GAP of its surface (pinch: the thumb
 //               and the index); the thumb and two fingers hold too (a tripod: a small ball the ring and little fingers do
 //               not reach)
@@ -96,6 +97,8 @@ function frameIssues(sk, s, h, entries, push, f) {
 	// a pinch holds between the thumb and the index; a small ball in a tripod (the thumb and two fingers); else three fingers
 	const gripped = h.grasp === "pinch" ? thumb && tipOn("Index") : fingersOn >= 3 || (thumb && fingersOn >= 2);
 	if (!gripped) push("FINGER_GAP", `${side} fingers off ${h.id}`, f, fingersOn + (thumb ? 1 : 0), h.grasp === "pinch" ? 2 : 3);
+	// a power or spherical hold closes the thumb against the fingers: three fingertips on the ball with the thumb out passed
+	else if (!thumb && (h.grasp === "power" || h.grasp === "spherical")) push("THUMB_OFF", `${side} thumb off ${h.id}`, f, -Math.max(...touch.filter(c => c.finger === "Thumb" && c.tip).map(c => c.depth)), GAP);
 	const on = touch.filter(c => c.depth >= -GAP && c.normal);
 	const c0 = scale(entries.reduce((acc, e) => add(acc, add(e.pos, apply(e.R, [0, e.half[1], 0]))), [0, 0, 0]), 1 / entries.length);
 	const under = on.filter(c => c.normal[1] <= BELOW).map(c => c.at);

package/src/motion3/qa/hints-grasp.js

@@ -1,6 +1,7 @@
 // Hints for the grasp kinds (#816, qa/grasp-checks.js, skills/catch.js): { cause, hint, fix? } as the other hints-*.js.
 //   FINGER_GAP  fix.grasp false: the fingers stopped at the preset; fix /fix/grasp true. Else the hand toward the object
 //   FINGER_PEN  fix.grasp false: the same fix. Else the hand out of it along its surface normal at the phalanx
+//   THUMB_OFF   the fingers channel: a grip preset held on while the hand holds it (or the object nearer the palm)
 //   SUPPORT     the carry names the grasp its shape takes (sphere: spherical, cylinder: power, else palm); with
 //               fix.grasp false, grasp back on first
 //   CATCH       catchObject's f0 earlier by the frames the hand came late (the ball passed the catch point that much
@@ -41,6 +42,13 @@ export const graspHints = {
 		const into = parts.reduce((m, e) => (signedDistance(e, p) < signedDistance(m, p) ? e : m));
 		return moveHint(X, `hand_${k}`, f, scale(normalAt(into, p), g.worst - g.limit + MARGIN), ` (out of ${id})`);
 	},
+	THUMB_OFF(X, g) {
+		if (graspOff(X)) return turnOn;
+		const [, side, id] = /^(left|right) thumb off (\S+)$/.exec(g.subject) ?? [];
+		if (!id) return null;
+		const k = side === "left" ? "l" : "r";
+		return { cause: X.cause(`fingers_${k}`, g.worstFrame), hint: `${id}: the thumb is ${(g.worst * 100).toFixed(1)} cm off it; key fingers_${k} with the grip (or spherical) preset at 1 while the hand holds it, or set the hand so ${id} sits in the palm` };
+	},
 	SUPPORT(X, g) {
 		if (graspOff(X)) return turnOn;
 		const id = /^(\S+) not supported$/.exec(g.subject)?.[1], o = X.spec?.objects?.[id];

package/src/motion3/qa/index.js

@@ -9,6 +9,7 @@ import { styleChecks, floatChecks } from "./style.js";
 import { specChecks } from "./spec-checks.js";
 import { objectChecks } from "./object-checks.js";
 import { graspChecks } from "./grasp-checks.js";
+import { fingerChecks } from "./finger-checks.js";
 import { loadChecks } from "../load.js";
 import { goalChecks } from "./goals.js";
 import { wristIssues } from "./wrist-checks.js";
@@ -39,7 +40,7 @@ function summarizeIssues(issues) {
 export function runMotionQa(sk, out, spec, opts = {}) {
 	const checks = spec.checks ?? {}, goals = goalChecks(out, spec.goals ?? []);
 	const issues = [...generalChecks(sk, out, { allow: checks.allow, limits: checks.limits, mouthPoints: checks.mouthPoints }), ...specChecks(out, checks),
-		...objectChecks(sk, out, spec), ...graspChecks(sk, out), ...loadChecks(sk, out), ...floatChecks(out, checks),
+		...objectChecks(sk, out, spec), ...graspChecks(sk, out), ...fingerChecks(sk, out), ...loadChecks(sk, out), ...floatChecks(out, checks),
 		...styleChecks(sk, out, checks, { ...QA_LIMITS, ...checks.limits }), ...wristIssues(sk, out), ...peopleChecks(sk, out, checks), ...goals.issues];
 	if (out.f0) for (const i of issues) i.frame += out.f0;
 	const groups = summarizeIssues(issues);

package/src/motion3/qa/motion-life.js

@@ -1,4 +1,4 @@
-// Measured, not judged (output.observations.life): how mechanical a take reads. Five cheap readings
+// Measured, not judged (output.observations.life): how mechanical a take reads. Six cheap readings
 // over the baked frames and the keys the agent wrote, one linear pass each, warnings only (never a
 // QA group, never qa.ok):
 //   sync   outside walks, the frame each body part (CHAINS) starts and stops moving (its activity,
@@ -18,6 +18,9 @@
 //          sides do the same thing on the same frames. score = the share of windows that twin.
 //   dead   runs of a second or more with no joint moving over DEAD m a frame outside a still goal:
 //          a statue (idle false, or a pose held where the idle layer stays off).
+//   lead   where the pelvis turns (its heading spans LEAD_TURN degrees or more: more than a walk's sway), the lag (frames, -LAG..LAG) that best correlates the head's
+//          world yaw change with the pelvis's: positive, the head turns first (a person's leads by about 5 frames at
+//          24 fps, flow.headLead); [lag, correlation], or null without a turn. Read only, never warned.
 // Activity is a part's own motion: the turn (deg/frame) of its local rotation, and for the hips
 // their world turn or travel (cm/frame), so a hand carried by its arm does not count as moving.
 // Why: compiled takes pass QA and still read mechanical (every part starts and stops on one frame,
@@ -34,9 +37,10 @@ const GRID_CV = 0.15, GRID_KEYS = 4, HALF_SHARE = 0.7;
 const SPIKE = 4, JERK_FLOOR = 20;
 const WALK_SPEED = 0.25, FOOT_STILL = 0.005, WINDOW = 48, TWIN = 0.9, TWIN_SWEEP = 15;
 const DEAD = 1e-4;
+const LAG = 10, LEAD_TURN = 15;
 const r2 = x => Math.round(x * 100) / 100;
 
-export const LIFE_UNITS = "life (warnings, not QA): [share or s, worst f0, f1]; keys [gap cv, even channels, half-second share]; jerk [p95 m/s^3, joint, spikes]";
+export const LIFE_UNITS = "life (warnings, not QA): [share or s, worst f0, f1]; keys [gap cv, even channels, half-second share]; jerk [p95 m/s^3, joint, spikes]; lead [frames the head turns before the pelvis, correlation]";
 
 const p95 = xs => { const s = [...xs].sort((a, b) => a - b); return s.length ? s[Math.min(s.length - 1, Math.floor(0.95 * s.length))] : 0; };
 const cvOf = gaps => { const m = gaps.reduce((a, b) => a + b, 0) / gaps.length, v = gaps.reduce((a, g) => a + (g - m) ** 2, 0) / gaps.length; return m > 0 ? Math.sqrt(v) / m : 0; };
@@ -206,6 +210,25 @@ function deadOf(sk, F, spec, fps) {
 	return { frames, best };
 }
 
+/** [lag, correlation] of the head's world yaw change against the pelvis's (lag > 0: the head first), null without a turn. */
+function leadOf(sk, F) {
+	const I = sk.index, n = F.length, DEG = 180 / Math.PI, wrap = d => d - 360 * Math.round(d / 360);
+	const pelvis = F.map(({ s }) => { const a = s.P[I.LeftUpLeg], b = s.P[I.RightUpLeg]; return Math.atan2(b[0] - a[0], b[2] - a[2]) * DEG; });
+	const head = F.map(({ s }) => { const R = s.R[I.Head]; return Math.atan2(R[0][2], R[2][2]) * DEG; });
+	const dp = pelvis.map((v, f) => (f ? wrap(v - pelvis[f - 1]) : 0)), dh = head.map((v, f) => (f ? wrap(v - head[f - 1]) : 0));
+	let heading = 0, lo = 0, hi = 0;
+	for (const d of dp) { heading += d; lo = Math.min(lo, heading); hi = Math.max(hi, heading); }
+	if (n <= 4 * LAG || hi - lo < LEAD_TURN) return null;
+	let best = null;
+	for (let lag = -LAG; lag <= LAG; lag++) {
+		let ab = 0, aa = 0, bb = 0;
+		for (let f = LAG + 2; f < n - LAG - 2; f++) { ab += dp[f] * dh[f - lag]; aa += dp[f] ** 2; bb += dh[f - lag] ** 2; }
+		const c = aa > 0 && bb > 0 ? ab / Math.sqrt(aa * bb) : 0;
+		if (!best || c > best[1]) best = [lag, c];
+	}
+	return [best[0], r2(best[1])];
+}
+
 /**
  * observeLife(sk, out, keys) -> observations.life; keys are the spec keys as the agent wrote them
  * (a skill's keys are the compiler's). Frames are absolute (out.f0 added). flags names the metrics
@@ -237,7 +260,7 @@ export function observeLife(sk, out, keys) {
 	const at = (score, w) => (w ? [score, w[0] + f0, w[1] + f0] : [score]);
 	return {
 		sync: at(sync.score, sync.worst?.at), keys: [k.cv, k.grid.length, k.halfSec], jerk: [...jerk.p95, jerk.spikes],
-		arms: at(twin.arms.score, twin.arms.worst?.at), legs: at(twin.legs.score, twin.legs.worst?.at), dead: at(r2(dead.frames / fps), dead.best),
+		arms: at(twin.arms.score, twin.arms.worst?.at), legs: at(twin.legs.score, twin.legs.worst?.at), dead: at(r2(dead.frames / fps), dead.best), lead: leadOf(sk, F),
 		...(warnings.length ? { flags: warnings.map(w => w[1]), warn: warnings[0][2] } : {}),
 	};
 }

package/src/motion3/schema/topics.js

@@ -103,7 +103,7 @@ export const NOTES = {
 	probes: ["motion.compile { probes } (at most 16); spec.probes are measured too, not stored; answered whether or not it installs.",
 		"distance [a, b] -> { min, minAt, max, maxAt, mean, first, last } in m; a bare object:<id> measures to its surface. position -> { at: [{ f, p }] }, at most 16 rows."],
 	channels: ["key.set names channels; values ease between keys and hold after the last key. step: [channel] jumps at f instead.",
-		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); and each change breaks along the body (overlap: the lower spine, chest, head, upper arm, forearm and wrist start and settle a few frames apart, one side trailing the other, the arm's swing settling past its stop; less for a short move, none on an arm's IK or a walk); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false }, { lag: false } or { overlap: false } one part (overlap: a number 0..2 scales it).",
+		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); and each change breaks along the body (overlap: the lower spine, chest, head, upper arm, forearm and wrist start and settle a few frames apart, one side trailing the other, the arm's swing settling past its stop; less for a short move, none on an arm's IK or a walk); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. The head leads the trunk into a turn (headLead: walking or standing, the head takes the turn the trunk makes over the next 5 frames, at most 30 degrees; not where keys move head_yaw). flow: false turns it off; { smooth: false }, { lag: false }, { overlap: false } or { headLead: false } one part (overlap: a number 0..2 scales it; headLead: 0..12 whole frames).",
 		"w_<anchor>_<side> (0..1) weights a hand onto an anchor; the weights of one hand add up to at most 1.",
 		"Any other numeric channel must come from spec.channels, a hinge (objects.<id>.channel), a check's when or a visible switch; names ending _vis are visibility switches (shown above 0.5)."],
 	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base|.rim], person:<character id>.<Bone> (another character's joint in its installed take).",

package/src/playback-telemetry.js

@@ -0,0 +1,107 @@
+// playback:summary: one event per playback run (play until stop, or until the fps or
+// speed changes), at most 10 per session. `late_ticks` is an ESTIMATE of dropped
+// frames: the share of playback-timer ticks that had to catch up more than one frame
+// (createPlaybackClock steps > 1). It is not a measured render drop; `measured_fps`
+// is the separate rAF sample taken during the same run. Every tick, past the cap too,
+// feeds app:friction_summary.late_tick_ratio through noteTick as it happens, so the
+// session-end snapshot is current even mid-run; a run still playing when the page
+// goes away is ended on pagehide (its summary is sent best effort, like any unload
+// event). Only closed buckets leave: never the scene, the take or the frame range.
+import { analyticsActive, bucketFrameRate, track } from "./analytics.js";
+import { admit, bucketLateTicks, noteTick } from "./analytics-friction.js";
+import { bucketLong } from "./analytics-strict.js";
+
+const RUNS_PER_SESSION = 10;
+const IDLE_RUN = Object.freeze({ tick() {}, end() {} });
+let send = track;
+// The run still playing, ended on pagehide: React runs no effect cleanup on unload.
+let activeRun = null, unloadListener = false;
+const endActive = () => { try { activeRun?.end(); } catch { /* telemetry is advisory */ } };
+
+/** 1, 2, 3-5, gte6: the most frames one timer tick had to catch up. */
+export function bucketCatchup(steps) {
+	if (!(steps >= 2)) return "1";
+	if (steps < 3) return "2";
+	if (steps < 6) return "3-5";
+	return "gte6";
+}
+
+/** The take's own frame rate: 12, 24, 30, 60, else other. */
+export function bucketPlaybackFps(fps) {
+	return [12, 24, 30, 60].includes(fps) ? String(fps) : "other";
+}
+
+/** Playback speed: 0.5, 1, 2, else other. */
+export function bucketSpeed(speed) {
+	return [0.5, 1, 2].includes(speed) ? String(speed) : "other";
+}
+
+/**
+ * Start measuring one playback run. The caller reports every timer tick's step
+ * count and calls end() when the run stops; end() is idempotent. While analytics
+ * is off the run is a no-op and no rAF sampler starts.
+ */
+export function startPlaybackRun(fps, speed, {
+	now = () => performance.now(),
+	raf = globalThis.requestAnimationFrame,
+	cancelRaf = globalThis.cancelAnimationFrame,
+	active = analyticsActive,
+} = {}) {
+	try {
+		if (!active()) return IDLE_RUN;
+		const startedAt = now();
+		let ticks = 0, late = 0, maxCatchup = 0, frames = 0, firstFrame = null, lastFrame = null, frameId = null, ended = false;
+		const sample = (time) => {
+			if (ended) return;
+			if (firstFrame === null) firstFrame = time;
+			else frames += 1;
+			lastFrame = time;
+			frameId = raf(sample);
+		};
+		if (typeof raf === "function") frameId = raf(sample);
+		if (!unloadListener && typeof globalThis.addEventListener === "function") {
+			unloadListener = true;
+			globalThis.addEventListener("pagehide", endActive);
+			globalThis.addEventListener("beforeunload", endActive);
+		}
+		const run = {
+			tick(steps) {
+				if (ended || !Number.isFinite(steps) || steps < 0) return;
+				ticks += 1;
+				if (steps > 1) late += 1;
+				maxCatchup = Math.max(maxCatchup, steps);
+				noteTick(steps > 1 ? 1 : 0, 1);
+			},
+			end() {
+				if (ended) return;
+				ended = true;
+				if (activeRun === run) activeRun = null;
+				try {
+					if (frameId !== null && typeof cancelRaf === "function") cancelRaf(frameId);
+					if (!ticks) return;
+					const span = lastFrame - firstFrame;
+					const props = {
+						duration: bucketLong(now() - startedAt), late_ticks: bucketLateTicks(late, ticks),
+						max_catchup: bucketCatchup(maxCatchup), fps: bucketPlaybackFps(fps), speed: bucketSpeed(speed),
+						measured_fps: bucketFrameRate(frames > 0 && span > 0 ? (frames * 1000) / span : NaN),
+					};
+					if (admit("playback:summary", RUNS_PER_SESSION)) send("playback:summary", props);
+				} catch {
+					// Telemetry must never affect playback.
+				}
+			},
+		};
+		endActive();
+		activeRun = run;
+		return run;
+	} catch {
+		return IDLE_RUN;
+	}
+}
+
+/** Tests only: capture what is sent; returns the restore. */
+export function playbackTelemetrySeam(capture) {
+	const previous = send;
+	send = capture;
+	return () => { send = previous; };
+}

package/src/post-turn-edits.js

@@ -0,0 +1,62 @@
+// What the user changed right after an agent turn: agent:post_turn_edit, one per
+// turn. The window opens when a turn ends and closes 120 s later, when the next
+// turn starts, or when the page goes away, whichever comes first. It counts the
+// user's edits that changed the scene, by group, as the command bus records them
+// (command-bus-telemetry.js: UI-origin receipts only, one drag is one receipt).
+import { bucketFrictionCount } from "./analytics-friction.js";
+import { bucketLong } from "./analytics-strict.js";
+
+export const POST_TURN_WINDOW_MS = 120_000;
+const GROUPS = Object.freeze(["pose", "camera", "object", "shot", "prompt"]);
+let open = null;
+let pageListener = false;
+
+const defaultTimers = { set: (fn, ms) => setTimeout(fn, ms), clear: (id) => clearTimeout(id), now: () => Date.now() };
+
+/** Send the open window's summary, if any, and close it. */
+export function closePostTurnWindow() {
+	const window = open;
+	if (!window) return null;
+	open = null;
+	try { window.timers.clear(window.timer); } catch { /* a foreign timer cannot keep the window open */ }
+	const edited = window.firstAt !== null;
+	const props = {
+		turn_id: window.turnId, edited,
+		// The prompt group is sent as prompt_block: "prompt" is a denied property key.
+		...Object.fromEntries(GROUPS.map((group) => [group === "prompt" ? "prompt_block" : group, bucketFrictionCount(window.counts[group])])),
+		...(edited ? { first_delay: bucketLong(window.firstAt - window.openedAt) } : {}),
+	};
+	try { Promise.resolve(window.emit("agent:post_turn_edit", props)).catch(() => {}); } catch { /* telemetry is advisory */ }
+	return props;
+}
+
+/** A turn ended: watch the user's next 120 s. Any window still open is closed first. */
+export function openPostTurnWindow(turnId, emit, timers = defaultTimers) {
+	closePostTurnWindow();
+	if (typeof turnId !== "string" || typeof emit !== "function") return;
+	try {
+		const openedAt = timers.now();
+		open = { turnId, emit, timers, openedAt, firstAt: null, counts: Object.fromEntries(GROUPS.map((group) => [group, 0])) };
+		open.timer = timers.set(closePostTurnWindow, POST_TURN_WINDOW_MS);
+		if (!pageListener && typeof globalThis.addEventListener === "function") {
+			pageListener = true;
+			globalThis.addEventListener("pagehide", closePostTurnWindow);
+		}
+	} catch {
+		open = null;
+	}
+}
+
+/** One user edit of `group` (the caller passes only the user's own edits); counted while a window is open. */
+export function noteEditGesture(group) {
+	if (!open || !GROUPS.includes(group)) return false;
+	try {
+		const at = open.timers.now();
+		if (at - open.openedAt >= POST_TURN_WINDOW_MS) { closePostTurnWindow(); return false; }
+		open.counts[group] += 1;
+		if (open.firstAt === null) open.firstAt = at;
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/search-friction.js

@@ -0,0 +1,49 @@
+// search:no_results: a search box whose query has shown nothing for 1 s.
+// Only the surface and a bucket of the query's length leave; the query text
+// itself never leaves this module.
+import { useEffect } from "react";
+import { track } from "./analytics.js";
+import { admit, bump } from "./analytics-friction.js";
+
+const STABLE_MS = 1000, PER_SURFACE = 3;
+const SURFACES = new Set(["assets", "outliner"]);
+let send = track, timers = { set: (run, ms) => setTimeout(run, ms), clear: (id) => clearTimeout(id) };
+
+/** 1, 2-3, 4-8, gte9: how long a query was, never what it said. */
+export function bucketQueryLength(length) {
+	if (length <= 1) return "1";
+	if (length <= 3) return "2-3";
+	if (length <= 8) return "4-8";
+	return "gte9";
+}
+
+/**
+ * An empty result shown for `query` on `surface`. Once the query has stayed the
+ * same for 1 s, the search_empty counter moves and search:no_results goes out
+ * (3 per surface per session). Returns the cancel: a new query or results
+ * showing up again before 1 s sends nothing.
+ */
+export function watchNoResults(surface, query) {
+	const length = String(query ?? "").trim().length;
+	if (!SURFACES.has(surface) || !length) return () => {};
+	const id = timers.set(() => {
+		try {
+			bump("search_empty");
+			if (admit(`search:no_results:${surface}`, PER_SURFACE)) send("search:no_results", { surface, query_len: bucketQueryLength(length) });
+		} catch { /* telemetry is advisory */ }
+	}, STABLE_MS);
+	return () => timers.clear(id);
+}
+
+/** Wraps a search's empty state: watching while it is shown, restarted when the query changes. */
+export function SearchEmpty({ surface, query, children }) {
+	useEffect(() => watchNoResults(surface, query), [surface, query]);
+	return children;
+}
+
+/** Tests only: capture what is sent and drive the timer; returns the restore. */
+export function searchFrictionSeam({ track: capture = track, set = timers.set, clear = timers.clear } = {}) {
+	const previous = [send, timers];
+	send = capture; timers = { set, clear };
+	return () => { [send, timers] = previous; };
+}