cozyclay 2.1.1 → 3.0.1

package/src/motion3/compiler/grip.js

@@ -0,0 +1,171 @@
+// The hand a fit puts on a scene body takes a grip on it (lane wrist). A fit only places a point of the
+// hand (reachGrip's fingers on the anchor); with nothing asking for the hand's turn, the wrist stayed
+// straight on the forearm and kept whatever roll the arm left it, so the palm did not face what it held
+// (a box side, a guitar neck: 0 deg of wrist on every holding frame, bench S10, session df388a9b), or
+// the agent keyed wflex/wtwist to fix it at the wrist alone. Now, while a fit's weight is on and its
+// anchor is on a body (an object anchor's body, or any body within NEAR m of the anchor):
+//   fingers  stay on the forearm's line: no flex or deviation is asked (a power grip turns the
+//            forearm, not the wrist: the wrist stays in its comfortable middle)
+//   roll     the hand turns about the forearm: on a thin body (two half sizes under THIN m: a can, a
+//            cup, a bar, a handle, a neck) the knuckle line takes the body's long axis, a cylindrical
+//            grasp with the body across the palm, at the end the forearm turns to least; on anything
+//            else the end-state-comfort thumb (people take the grip that ends comfortable, Rosenbaum):
+//            up when the forearm is level, toward the midline when it points down or up. The turn
+//            stops where the forearm's whole twist leaves its comfortable range (arm-orient.js
+//            WRIST_COMFORT, +-50 deg: Morrey's daily-task range); the forearm bone takes its share and
+//            the wrist the rest (hold.js orient), by the fit's weight
+//   point    the fingers' point stays where the fit put it, the elbow in the plane the arm had
+// The spec wins: a hand whose wtwist_<k> or wflex_<k> is turned on the frame keeps it, a fit with
+// orient: false is left alone, and a prop anchor is the second-hand grip's (second-hand.js). A hand
+// that carries something keeps the carry's own grip (its grab offset) once the carry leads it. A keyed
+// carry's grab offset is read off the plain solve of its grab frame (object-keys.js attach), so when it
+// carries a body that is not thin (a box, a crate) the carrying hand takes the grip on the reach, on
+// that frame and up to its first key (ownGrip): the offset the carry keeps is then a grip, not the
+// forearm's neutral roll. A thin body (a cup, a can) keeps the neutral offset: its aim keys pick the
+// roll the arm holds most easily from it, and the cylindrical grip measured worse on every bench cup.
+// Those frames read the carried body where it rested before the grab, never a pose the hand moves.
+import { add, sub, scale, norm, cross, dot, len, apply, ry, mul, T, axisRot } from "./math.js";
+import { palmAxes, twoBone } from "./limbs.js";
+import { aimArm, orient } from "./hold.js";
+import { ELBOW_REST, WRIST_COMFORT, wristNeed } from "./arm-orient.js";
+import { resolveAnchor } from "./anchors.js";
+import { sdBox } from "../qa/geometry.js";
+import { partsOf } from "../object-pose.js";
+
+const NEAR = 0.06, THIN = 0.045, ALIGN = 0.3, PREFER = 30, DEG = 180 / Math.PI, ITER = 2, UP = [0, 1, 0];
+const cols = (a, b, c) => [[a[0], b[0], c[0]], [a[1], b[1], c[1]], [a[2], b[2], c[2]]];
+const flat = (v, n) => sub(v, scale(n, dot(v, n)));
+
+/** The fit of side k whose weight is on most at channels c (null when none), its weight times the arm's IK weight. */
+function activeFit(spec, c, k) {
+	let best = null;
+	for (const fit of spec.fits ?? []) {
+		const w = c[`w_${fit.anchor}_${fit.side}`] ?? 0;
+		if (fit.side === k && fit.orient !== false && w > 1e-4 && (!best || w > best.w)) best = { fit, w };
+	}
+	return best && { ...best, w: best.w * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0)) };
+}
+
+/** The fit's effector point on pose s (anchors.js measureProps' rule for a prop point; the joints' mean otherwise). */
+function effectorAt(sk, spec, s, side, eff) {
+	if (eff.prop) {
+		const prop = spec.props?.[eff.prop];
+		if (!prop) return null;
+		const ax = palmAxes(sk, s, side), o = scale(prop.origin.map(b => s.P[sk.index[b]]).reduce(add, [0, 0, 0]), 1 / prop.origin.length);
+		const [d, l, n] = eff.point === "origin" ? [0, 0, 0] : prop.points?.[eff.point] ?? [0, 0, 0];
+		return add(o, add(scale(ax.d, d), add(scale(ax.l, l), scale(ax.n, n))));
+	}
+	const js = eff.joints ?? [`${side}HandIndex2`, `${side}HandMiddle2`];
+	return scale(js.map(j => s.P[sk.index[j]]).reduce(add, [0, 0, 0]), 1 / js.length);
+}
+
+/** The carry entry over body id (its own or a group's) and the side whose prop carries it, else null. */
+function carryOf(ctx, id) {
+	const { spec } = ctx, o = ctx.scene?.objects?.[id];
+	for (const k of [id, ...(o?.ancestors ?? [])]) { const e = spec.objects?.[k]; if (e?.prop) return { key: k, entry: e, side: spec.props?.[e.prop]?.hand ?? null }; }
+	return null;
+}
+
+/**
+ * Whether hand k takes the grip on keyed carry `key` at frame f although it carries it (see above): a keyed
+ * carry that keeps its grab offset, from its reach to its grab frame and up to its first key. Answers the
+ * frame to read the carried body at (before the grab), or null.
+ */
+function ownGrip(ctx, key, k, f) {
+	const o = ctx.spec.objects?.[key];
+	const half = ctx.scene?.objects?.[key]?.half;
+	if (!ctx.hold?.span || !o?.prop || ctx.spec.props?.[o.prop]?.hand !== k || !o.keys?.length || o.grab === undefined || o.at !== undefined || o.along !== undefined || (half && thinAxis(half) >= 0)) return null;
+	const [grab] = ctx.hold.span(key);
+	return grab >= 1 && f <= Math.max(grab, ctx.hold.firstKey(key) - 1) ? Math.min(f, grab - 1) : null;
+}
+
+/** The body box the grip is on: the anchor's object (its nearest part) or the nearest body within NEAR m; null when none. */
+function bodyAt(ctx, f, k, A, anchor, now) {
+	const scene = ctx.scene?.objects ?? {}, ids = anchor?.kind === "object" ? partsOf(ctx.scene, anchor.object) : Object.keys(scene);
+	let best = null;
+	for (const id of ids) {
+		const half = scene[id]?.half;
+		if (!half) continue;
+		const own = ownGrip(ctx, carryOf(ctx, id)?.key, k, f), pose = ctx.objectPose?.(id, own ?? f, own === null ? now : null) ?? scene[id];
+		if (!pose?.R) continue;
+		const box = { pos: pose.pos, R: pose.R, half }, d = sdBox(A, box);
+		if (!best || d < best.d) best = { box, d, id };
+	}
+	// a body this hand carries keeps the carry's own grip (its grab offset, which its keys are written on:
+	// the same with keys or without), and no other body takes its place
+	const carry = best && carryOf(ctx, best.id);
+	if (!best || (carry?.side === k && ownGrip(ctx, carry.key, k, f) === null)) return null;
+	return anchor?.kind === "object" || best.d <= NEAR ? best.box : null;
+}
+
+const AXES = [0, 1, 2];
+/** The long axis of a thin body (two half sizes under THIN m: a can, a cup, a bar, a handle, a neck), else -1. */
+function thinAxis(half) {
+	const long = AXES.reduce((a, i) => (half[i] > half[a] ? i : a), 0);
+	return AXES.filter(i => i !== long).every(i => half[i] < THIN) ? long : -1;
+}
+
+/**
+ * The hand's palm frame (columns d, l, n of limbs.js palmAxes) for the grip: the fingers stay on the
+ * forearm's line (no flex or deviation added: a power grip turns the forearm, not the wrist) and the
+ * hand turns about it. On a thin body the knuckle line takes the body's long axis (a cylindrical grasp:
+ * the can, the bar, the neck across the palm) with the thumb at its comfortable end; on anything else,
+ * or a thin body along the forearm, the end-state-comfort thumb: up when the forearm is level, toward
+ * the midline when it points down or up.
+ */
+function gripFrame(side, d, now, yawDeg, axis) {
+	const right = side === "Right", medial = apply(ry(yawDeg ?? 0), [right ? 1 : -1, 0, 0]), vy = Math.abs(d[1]);
+	const thumb = flat(add(scale(UP, 1 - vy), scale(medial, vy)), d), want = norm(len(thumb) > 1e-3 ? thumb : flat(medial, d));
+	// a thin body lies across the palm, the knuckle line along its long axis: of its two ends the thumb takes the
+	// one the forearm turns to least (the end-state-comfort thumb counts PREFER deg in its favour)
+	const across = axis ? flat(axis, d) : null;
+	if (!across || len(across) <= ALIGN) return cols(d, want, cross(d, want));
+	const turn = l => Math.acos(Math.max(-1, Math.min(1, dot(l, now)))) * DEG - (dot(l, want) > 0 ? PREFER : 0);
+	const a = norm(across), l = turn(a) <= turn(scale(a, -1)) ? a : scale(a, -1);
+	return cols(d, l, cross(d, l));
+}
+
+/** Frame F (columns d, l, n) turned about its own d so the forearm's whole twist (from `twist` deg now) stays within the comfortable range: the roll stops where the forearm is comfortable. */
+function comfortable(F, now, twist) {
+	const d = [F[0][0], F[1][0], F[2][0]], l = [F[0][1], F[1][1], F[2][1]];
+	const want = Math.atan2(dot(cross(now, l), d), dot(now, l)) * DEG, [lo, hi] = WRIST_COMFORT.twist;
+	const got = Math.min(hi, Math.max(lo, twist + want)) - twist;
+	if (Math.abs(got - want) < 1e-6) return F;
+	const r = apply(axisRot(d, got), now);
+	return cols(d, r, cross(d, r));
+}
+
+/**
+ * gripHand(ctx, sk, s, side, k, c, f, diag): turn the hand of a fit onto the body under its anchor
+ * (see above); a no-op when nothing asks for it. diag.grip_<k> = { w, twist, flex, dev, body }.
+ */
+export function gripHand(ctx, sk, s, side, k, c, f, diag) {
+	// a wrist the spec turns on this frame is the agent's (or a skill's) own; a neutral 0 asks for nothing
+	if (Math.abs(c[`wtwist_${k}`] ?? 0) > 1e-3 || Math.abs(c[`wflex_${k}`] ?? 0) > 1e-3) return;
+	const on = activeFit(ctx.spec, c, k);
+	if (!on || on.w < 1e-3) return;
+	// a hand that carries something on this frame holds that (its carry's grip), whatever its fit's anchor
+	if (Object.keys(ctx.spec.objects ?? {}).some(id => ctx.spec.objects[id]?.prop && ctx.objectHand?.(id, f) === k && ownGrip(ctx, id, k, f) === null)) return;
+	const now = { s, diag, c }, anchor = ctx.spec.anchors?.[on.fit.anchor];
+	// a point of a prop another hand holds is the second-hand grip's (second-hand.js)
+	if (anchor?.kind === "prop") return;
+	const A = add(resolveAnchor(ctx, on.fit.anchor, s, diag, c, k), on.fit.offset ?? [0, 0, 0]);
+	const box = bodyAt(ctx, f, k, A, anchor, now);
+	const eff = box && effectorAt(sk, ctx.spec, s, side, on.fit.effector ?? {});
+	if (!eff) return;
+	const measure = st => ({ pos: effectorAt(sk, ctx.spec, st, side, on.fit.effector ?? {}), R: (({ d, l, n }) => cols(d, l, n))(palmAxes(sk, st, side)) });
+	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`];
+	const long = thinAxis(box.half), axis = long >= 0 ? apply(box.R, AXES.map(i => (i === long ? 1 : 0))) : null;
+	const ax = palmAxes(sk, s, side), roll = norm(flat(ax.l, ax.d));
+	const axT = norm(sub(s.P[h], s.P[fa])), neutral = mul(s.R[fa], mul(T(sk.restWorldRot[fa]), sk.restWorldRot[h]));
+	const twist = wristNeed(neutral, s.R[h], axT, apply(mul(neutral, T(s.R[h])), ax.l)).twist;
+	const palm = { pos: eff, R: comfortable(gripFrame(side, ax.d, roll, c.yaw, axis), roll, twist) };
+	const { goal, plane, wristAt } = aimArm(sk, s, side, palm, measure(s), on.w, "palm");
+	let need = { twist: 0, flex: 0, dev: 0 };
+	for (let i = 0; i < ITER; i++) {
+		// the elbow keeps the plane the arm had (bendPlane), the fingers' point goes back where the fit put it
+		twoBone(sk, s, a, fa, h, wristAt(i ? s.R[h] : goal), plane, ELBOW_REST, "elbow");
+		need = orient(sk, s, side, h, fa, goal);
+	}
+	diag[`grip_${k}`] = { w: on.w, ...need };
+}

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

@@ -0,0 +1,48 @@
+// While a walk runs the head keeps the gaze steadier than the trunk: the trunk's quick sway (the root's and the
+// spine's yaw, pitch and roll less their moving average over about a stride, so a turn, a lean or a bow the keys
+// hold is not swayed against) is taken back by the head, a part of it (STEADY) and no more than LIMIT degrees; little
+// of the pitch: a person's head nods with the trunk's dip at each step.
+// Only from a walk's start to its last step (walk.js tags them "<tag> start", "<tag> step <n>"; the settle after
+// holds still, and a take cut in it ends the same), faded in and out over FADE frames, and never on a head axis the
+// spec's own keys move during that walk: a keyed look wins. The average holds the take's end value past its end.
+const STEADY = { yaw: 0.5, pitch: 0.2, roll: 0.7 }, LIMIT = { yaw: 4, pitch: 6, roll: 10 }, WINDOW = 33, FADE = 8;
+const AXES = ["yaw", "pitch", "roll"];
+
+/** The walk spans in the keys, start to last step: [[f0, f1], ...]. */
+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);
+		if (!m || !/\bwalk(To)?$/.test(tag)) continue;
+		const span = spans.get(tag) ?? [Infinity, -Infinity];
+		spans.set(tag, [Math.min(span[0], k.f), Math.max(span[1], k.f)]);
+	}
+	return [...spans.values()].filter(([a, b]) => b > a);
+}
+
+const movingAverage = (xs, w) => {
+	const half = Math.floor(w / 2), at = i => xs[Math.max(0, Math.min(xs.length - 1, i))];
+	return xs.map((_, f) => { let s = 0; for (let i = f - half; i <= f + half; i++) s += at(i); return s / (2 * half + 1); });
+};
+
+/** Adds the head's share of the trunk's sway to the baked head channels inside every walk (in place). */
+export function steadyHead(baked, keys, frameCount) {
+	const spans = walkSpans(keys);
+	if (!spans.length) return;
+	const series = name => baked[name] ?? new Array(frameCount).fill(0);
+	for (const axis of AXES) {
+		const spine = series(`spine_${axis}`), trunk = series(axis).map((v, f) => v + spine[f]);
+		const mean = movingAverage(trunk, WINDOW);
+		let head = null;
+		for (const [f0, f1] of spans) {
+			const keyed = keys.some(k => k.f >= f0 && k.f <= f1 && k.set?.[`head_${axis}`] !== undefined && !/\bwalk(To)? (start|step \d+|end)$/.test(k.src ?? ""));
+			if (keyed) continue;
+			head ??= series(`head_${axis}`).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), sway = Math.max(-LIMIT[axis], Math.min(LIMIT[axis], trunk[f] - mean[f]));
+				head[f] -= STEADY[axis] * sway * fade * fade * (3 - 2 * fade);
+			}
+		}
+		if (head) baked[`head_${axis}`] = head;
+	}
+}

package/src/motion3/compiler/hold.js

@@ -0,0 +1,134 @@
+// The hand follows a held object (docs/motion-api-v3.1.md C14). On frames where
+// spec.objects[id].keys lead (../object-keys.js), pose.js calls holdHand after the plain arm
+// (IK or FK, wrist channels, fingers): the wrist target and the hand's orientation are solved so
+// the grip (the prop's palm frame) lands on the pose the object keys ask for, hand = object o
+// attach^-1. The whole arm turns the object (arm-orient.js, lane K8): the elbow swings about the
+// shoulder-wrist axis to the pole that leaves the wrist least strained, the forearm takes its
+// share of the turn about its own axis, and the wrist adds the rest within anatomical limits
+// relative to the forearm: twist about the forearm, flex about the knuckle line, deviation toward
+// the thumb (+, radial) or the little finger (-, ulnar). What the arm or the wrist cannot do is
+// left as a residual: QA measures it on the object (qa/key-checks.js) and reads the reasons from
+// diag.hold_<side>.
+import { add, sub, scale, norm, dot, len, mul, T, apply, axisRot, angle, quatFromMat, matFromQuat } from "./math.js";
+import { twoBone, palmAxes, carried, askedFold, reachAt, ELBOW_FOLD } from "./limbs.js";
+import { rotateSubtree } from "./skeleton.js";
+import { slerp } from "./quat.js";
+import { bodyFor, segmentDepth } from "../body.js";
+import { WRIST_LIMITS, FOREARM_SHARE, ELBOW_REST, wristNeed, swivel, landscape, shoulderPrice, comfortPrice } from "./arm-orient.js";
+
+// STRAIGHT: a plain arm whose elbow sits less than this (m) off its shoulder-wrist midpoint is
+// straight and has no bend plane of its own. A straight FK arm keeps 1 to 3 mm there from its bone
+// lengths (Y Bot: the upper arm is 2 mm shorter than the forearm, so the elbow sits 1 mm up the
+// arm), and that direction is no bend: as the swivel's reference it put the elbow "up", so the
+// limit 100 deg from it ruled out an elbow pointing down (session d5c110a7's batting stance).
+// ROLL_MARGIN: the share of each wrist half range by which holdCost tightens the limits, so the
+// roll picked for a key leaves the frames between keys (they turn between the picks) some room.
+// The fold price (holdCost): an arm folded near flat turns the hand any way at all, so without a price
+// the roll of a stance key at the shoulder folded it (session d5c110a7: wrist 6-9 cm from the shoulder,
+// 162 deg), and the frames between keys, where the wrist moves a few cm, broke away from it. twoBone
+// now stops the fold (limbs.js ELBOW_FOLD, ELBOW_STOP); the price still steers the roll off it.
+const ITERATIONS = 3, REACH_PRICE = 1, STRAIGHT = 0.005, ROLL_MARGIN = 0.15, BODY_PRICE = 4;
+const clampTo = (v, [lo, hi]) => Math.min(hi, Math.max(lo, v));
+
+/**
+ * Turn the hand (and its fingers) about the wrist so its world rotation is `goal`, as far as the
+ * limits let it: the forearm bone turns FOREARM_SHARE of the twist about its own axis, the hand
+ * the rest plus flex and deviation. Returns what it needed, degrees { twist, flex, dev }.
+ */
+export function orient(sk, s, side, h, fa, goal) {
+	const axT = scale(sub(s.P[h], s.P[fa]), 1 / len(sub(s.P[h], s.P[fa]))), neutral = mul(s.R[fa], mul(T(sk.restWorldRot[fa]), sk.restWorldRot[h]));
+	const { axF, axD, ...need } = wristNeed(neutral, goal, axT, apply(mul(neutral, T(s.R[h])), palmAxes(sk, s, side).l));
+	const got = Object.fromEntries(Object.entries(need).map(([k, v]) => [k, clampTo(v, WRIST_LIMITS[k])]));
+	const want = mul(mul(axisRot(add(scale(axF, got.flex), scale(axD, got.dev)), Math.hypot(got.flex, got.dev)), axisRot(axT, got.twist)), neutral);
+	rotateSubtree(sk, s, fa, s.P[fa].slice(), axisRot(axT, FOREARM_SHARE * got.twist));
+	rotateSubtree(sk, s, h, s.P[h].slice(), mul(want, T(s.R[h])));
+	return need;
+}
+
+/**
+ * The bend direction the channels gave the arm of `side` on pose s, what its swivel turns from: the
+ * elbow off the shoulder-wrist midpoint, or for a straight arm (STRAIGHT) where its elbow would
+ * point if it bent, the upper arm's rest bend carried by the bone, so the swivel's limits sit on
+ * the upper arm's own roll.
+ */
+export function bendPlane(sk, s, side) {
+	const I = sk.index, a = I[`${side}Arm`], bend = sub(s.P[I[`${side}ForeArm`]], scale(add(s.P[a], s.P[I[`${side}Hand`]]), 0.5));
+	return len(bend) > STRAIGHT ? bend : carried(sk, s, a, ELBOW_REST);
+}
+
+/**
+ * What holding `palm` with weight w needs on pose s: the hand's goal rotation, the wrist target for
+ * a hand rotation (pin "wrist": where it is; "palm": where the palm stays put), the bend direction
+ * (bendPlane).
+ */
+export function aimArm(sk, s, side, palm, now, w, pin) {
+	const I = sk.index, h = I[`${side}Hand`];
+	// the palm frame in the hand bone's frame: fixed for this frame's finger curl
+	const localR = mul(T(s.R[h]), now.R), localP = apply(T(s.R[h]), sub(now.pos, s.P[h]));
+	const goal = matFromQuat(slerp(quatFromMat(s.R[h]), quatFromMat(mul(palm.R, T(localR))), w));
+	const from = s.P[h].slice();
+	// the wrist goes where the grip lands with the orientation the wrist reached (the goal at first)
+	const grip = R => sub(palm.pos, apply(R, localP));
+	return { goal, plane: bendPlane(sk, s, side), wristAt: pin === "wrist" ? () => from : pin === "palm" ? grip : R => add(from, scale(sub(grip(R), from), w)) };
+}
+
+/**
+ * held = { w, palm: { pos, R }, measure(s) -> { pos, R }, pole?, second?, pin? }: blend weight
+ * (1 inside the keyed span), the palm frame the keys ask for, the function that measures it on a
+ * pose, the planned elbow pole (../hold-plan.js; searched here when absent) and, for a second hand
+ * (../second-hand.js), the id of the object it grips and what stays put (pin "wrist" or "palm").
+ */
+export function holdHand(sk, s, side, held, restBend, diag, k) {
+	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`], { w } = held;
+	const { goal, plane, wristAt } = aimArm(sk, s, side, held.palm, held.measure(s), w, held.pin);
+	const arm = swivel(sk, s, side, goal, wristAt(goal), plane, restBend, { toward: held.pole, w, comfort: held.comfort });
+	let miss = 0, fold = 0, need = { twist: 0, flex: 0, dev: 0 };
+	for (let i = 0; i < ITERATIONS; i++) {
+		const W = wristAt(i ? s.R[h] : goal);
+		fold = askedFold(sk, s, side, W);
+		miss = twoBone(sk, s, a, fa, h, W, arm.pole, restBend, "elbow");
+		need = orient(sk, s, side, h, fa, goal);
+	}
+	// fold: the flexion (deg) the wrist asked when past ELBOW_FOLD; miss is then how far inside the fold it is
+	diag[`hold_${k}`] = { w, miss: Math.max(0, miss), ...need, swivel: swungFrom(s, a, fa, h, plane), ...(fold > ELBOW_FOLD ? { fold } : {}), ...(held.second ? { second: held.second } : {}) };
+	diag[`arm_miss_${k}`] *= 1 - w;
+}
+
+/**
+ * The swivel landscape holdHand searches for `held` on pose s (the plain arm of `side`): what
+ * ../hold-plan.js plans the elbow's path on.
+ */
+export function holdLandscape(sk, s, side, held) {
+	const { goal, plane, wristAt } = aimArm(sk, s, side, held.palm, held.measure(s), held.w);
+	return landscape(sk, s, side, goal, wristAt(goal), plane, ELBOW_REST, 0, held.comfort);
+}
+
+/**
+ * The arm's cost of holding the palm frame `palm` on pose s (the plain arm of `side`, `now` its
+ * palm frame there): the wrist strain at the pole holdHand would take, its limits ROLL_MARGIN
+ * tighter, plus REACH_PRICE per squared centimetre the arm is short or the wrist nearer the shoulder
+ * than the elbow folds (ELBOW_FOLD), plus the shoulder's price with opts.shoulder. An aim key without roll takes the cheapest roll (key-aim.js).
+ */
+export function holdCost(sk, s, side, palm, now, { shoulder = false } = {}) {
+	const { goal, plane, wristAt } = aimArm(sk, s, side, palm, now, 1), W = wristAt(goal);
+	const arm = swivel(sk, s, side, goal, W, plane, ELBOW_REST, { margin: ROLL_MARGIN });
+	// the wrist no nearer the shoulder than the elbow folds (ELBOW_FOLD): an arm folded flat holds anything, and nothing between keys
+	const I = sk.index, S = s.P[I[`${side}Arm`]], A = len(sub(s.P[I[`${side}ForeArm`]], S)), B = len(sub(s.P[I[`${side}Hand`]], s.P[I[`${side}ForeArm`]]));
+	const fold = Math.max(0, reachAt(A, B, ELBOW_FOLD) - len(sub(W, S)));
+	// opts.shoulder adds the shoulder's price at that elbow (arm-orient.js shoulderPrice) and the arm's depth into the body
+	// (body.js, priced as grip-choice.js prices it): a leaning aim key's pick (key-aim.js) keeps the elbow down, not in the chest
+	const arm2 = shoulder ? swivel(sk, s, side, goal, W, plane, ELBOW_REST, { comfort: true }) : arm;
+	return (shoulder ? comfortPrice(arm2.need) + shoulderPrice(S, arm2.elbow) + intoBody(sk, s, side, S, arm2.elbow, W) : arm.cost) + REACH_PRICE * ((arm.miss * 100) ** 2 + (fold * 100) ** 2);
+}
+
+/** BODY_PRICE per squared centimetre the upper arm or the forearm at elbow E and wrist W goes into the body (body.js). */
+function intoBody(sk, s, side, S, E, W) {
+	const body = bodyFor(sk), I = sk.index;
+	return body ? BODY_PRICE * (Math.max(segmentDepth(body, sk, s, I[`${side}Arm`], S, E), segmentDepth(body, sk, s, I[`${side}ForeArm`], E, W)) * 100) ** 2 : 0;
+}
+
+/** Degrees the elbow swung about the shoulder-wrist axis from the bend direction `plane` the channels gave. */
+function swungFrom(s, a, fa, h, plane) {
+	const u = norm(sub(s.P[h], s.P[a])), off = v => sub(v, scale(u, dot(v, u)));
+	return angle(off(sub(s.P[fa], s.P[a])), off(plane));
+}

package/src/motion3/compiler/idle.js

@@ -0,0 +1,113 @@
+// The idle layer: a body that holds its place is never a statue. Wherever the take holds a pose (no
+// keyed channel changes: not a hand, a door or a finger) with its hands free (no arm on IK, no hand
+// target or fit weight, nothing carried), it breathes (the chest lifts and settles:
+// spine_pitch), lets its head drift a little (head_yaw, head_pitch) and, standing, shifts its weight
+// from foot to foot (the hips sway over the planted feet, the pelvis lists toward the unloaded side and
+// the spine rights it: root, roll, spine_roll). The layer only adds to channels that carry no contact:
+// the feet, hand targets, anchors and objects are left as keyed, so a planted foot stays put and a hand
+// on a target stays on it. It fades in RAMP s after the take starts or the body stops, out before it
+// moves again, and stays off across the span of a `still` goal. Deterministic: its phases come from where the character
+// first stands, so a recompile bakes the same take. spec.idle: false turns it off. The offsets ride on
+// the solved pose only (compile.js solveFrame): out.baked keeps the keyed values, so QA's causes and
+// patches still name the keys.
+const BREATH = { period: 3.8, deg: 0.8 }, HEAD = { yaw: 0.9, pitch: 0.6 }, SWAY = { period: 5.6, m: 0.012, list: 1.4 };
+const RAMP = 0.5, MOVE = 1e-4, TAU = 2 * Math.PI;
+const smoothstep = x => x * x * (3 - 2 * x);
+const differs = (a, b) => (Array.isArray(a) ? a.some((v, i) => Math.abs(v - b[i]) > MOVE)
+	: a && typeof a === "object" ? Object.keys({ ...a, ...b }).some(k => Math.abs((a[k] ?? 0) - (b?.[k] ?? 0)) > 1e-3) : Math.abs((a ?? 0) - (b ?? 0)) > 0.01);
+
+/** Phases in [0, TAU) from a text (FNV-1a hash, then mulberry32). */
+function phases(text, n) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+	let a = h >>> 0;
+	return Array.from({ length: n }, () => {
+		a = (a + 0x6d2b79f5) >>> 0;
+		let t = Math.imul(a ^ (a >>> 15), a | 1);
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+		return (((t ^ (t >>> 14)) >>> 0) / 4294967296) * TAU;
+	});
+}
+
+/** The weight of the layer per frame: 0 while anything keyed moves, a hand works or a still goal holds the body, easing to 1 RAMP s into a hold. */
+function holdWeights(baked, spec, frameCount, fps) {
+	// the take's first frame is its keyed pose: the layer fades in from there
+	const moving = new Array(frameCount).fill(false), watch = Object.keys(baked);
+	moving[0] = true;
+	for (let f = 1; f < frameCount; f++) if (watch.some(ch => differs(baked[ch][f], baked[ch][f - 1]))) moving[f] = moving[f - 1] = true;
+	// a working hand: an arm on IK, a hand target or fit weight, or an object carried from its grab on
+	const hands = watch.filter(ch => /^(armw_[lr]|w_.+_[lr])$/.test(ch));
+	for (let f = 0; f < frameCount; f++) if (hands.some(ch => baked[ch][f] > 1e-3)) moving[f] = true;
+	for (const o of Object.values(spec.objects ?? {})) {
+		if (!Number.isFinite(o?.grab)) continue;
+		for (let f = Math.max(0, o.grab); f < Math.min(frameCount, Number.isFinite(o.release) ? o.release : frameCount); f++) moving[f] = true;
+	}
+	for (const g of spec.goals ?? []) {
+		const at = Array.isArray(g?.at) ? g.at : null;
+		if (g?.still === undefined || !at?.length) continue;
+		for (let f = Math.max(0, Math.round(at[0])); f <= Math.min(frameCount - 1, Math.round(at[at.length - 1])); f++) moving[f] = true;
+	}
+	const ramp = Math.max(1, Math.round(RAMP * fps)), d = new Array(frameCount).fill(Infinity);
+	for (let f = 0, last = -Infinity; f < frameCount; f++) { if (moving[f]) last = f; d[f] = f - last; }
+	for (let f = frameCount - 1, next = Infinity; f >= 0; f--) { if (moving[f]) next = f; d[f] = Math.min(d[f], next - f); }
+	return d.map(x => smoothstep(Math.min(1, x / ramp)));
+}
+
+/**
+ * Per hand, how much it works at each frame: 1 while its arm is on IK, a hand target or fit weight of that hand is
+ * on, or it carries an object from its grab on; easing to 0 over RAMP s away from that. pose.js keeps a working
+ * hand's forearm on its slant (arm_hang), eased so the arm does not jump as it goes onto IK. null for an idle hand.
+ */
+export function busyHands(baked, spec, frameCount, fps) {
+	const out = {}, ramp = Math.max(1, Math.round(RAMP * fps));
+	for (const k of ["l", "r"]) {
+		const own = Object.keys(baked).filter(ch => ch === `armw_${k}` || new RegExp(`^w_.+_${k}$`).test(ch));
+		const busy = Array.from({ length: frameCount }, (_, f) => own.some(ch => baked[ch][f] > 1e-3));
+		for (const o of Object.values(spec.objects ?? {})) {
+			if (!Number.isFinite(o?.grab) || spec.props?.[o.prop]?.hand !== k) continue;
+			for (let f = Math.max(0, o.grab); f < Math.min(frameCount, Number.isFinite(o.release) ? o.release : frameCount); f++) busy[f] = true;
+		}
+		if (!busy.some(Boolean)) { out[k] = null; continue; }
+		const d = new Array(frameCount).fill(Infinity);
+		for (let f = 0, last = -Infinity; f < frameCount; f++) { if (busy[f]) last = f; d[f] = f - last; }
+		for (let f = frameCount - 1, next = Infinity; f >= 0; f--) { if (busy[f]) next = f; d[f] = Math.min(d[f], next - f); }
+		out[k] = d.map(x => 1 - smoothstep(Math.min(1, x / ramp)));
+	}
+	return out;
+}
+
+/** The idle offsets per frame ({ channel: delta }, root a world [dx, 0, dz]) for the baked channels, or null (compile.js rebake). */
+export function idleLayer(baked, { spec, sk, frameCount }) {
+	if (spec.idle === false || !baked.root || !baked.foot_l || !baked.foot_r) return null;
+	const fps = spec.fps ?? 30, w = holdWeights(baked, spec, frameCount, fps);
+	if (!w.some(x => x > 0)) return null;
+	const P = sk.restWorldPos, standY = P[sk.index.Hips][1], ankY = P[sk.index.LeftFoot][1];
+	const [pb, py, pp, ps, py2] = phases(JSON.stringify([baked.root[0].map(v => v.toFixed(3)), (baked.yaw?.[0] ?? 0).toFixed(1)]), 5);
+	const out = new Array(frameCount).fill(null);
+	for (let f = 0; f < frameCount; f++) {
+		if (!(w[f] > 0)) continue;
+		const t = f / fps, k = w[f];
+		// breathing in lifts the chest (spine_pitch + bends forward)
+		const d = out[f] = { spine_pitch: -k * BREATH.deg * Math.sin((TAU * t) / BREATH.period + pb),
+			head_yaw: k * HEAD.yaw * (0.6 * Math.sin((TAU * t) / 7.3 + py) + 0.4 * Math.sin((TAU * t) / 11.9 + py2)),
+			head_pitch: k * HEAD.pitch * Math.sin((TAU * t) / 9.1 + pp) };
+		// the weight shift: standing only (both feet flat on the floor, the hips at standing height)
+		const feet = ["l", "r"].every(s => baked[`foot_${s}`][f][1] < ankY + 0.03 && Math.abs(baked[`fpitch_${s}`]?.[f] ?? 0) < 2);
+		if (!feet || baked.root[f][1] < standY - 0.15) continue;
+		const s = k * Math.sin((TAU * t) / SWAY.period + ps), yaw = ((baked.yaw?.[f] ?? 0) * Math.PI) / 180;
+		d.root = [Math.cos(yaw) * SWAY.m * s, 0, -Math.sin(yaw) * SWAY.m * s];
+		// the hips over the left foot drop the right side (roll +), the spine stays upright
+		d.roll = SWAY.list * s;
+		d.spine_roll = -SWAY.list * s;
+	}
+	return out;
+}
+
+/** Frame f's channels with the idle offsets added (a new object; c itself is left alone). */
+export function withIdle(c, layer, f) {
+	const d = layer?.[f];
+	if (!d) return c;
+	const out = { ...c };
+	for (const [ch, v] of Object.entries(d)) out[ch] = Array.isArray(v) ? (Array.isArray(c[ch]) ? c[ch].map((x, i) => x + v[i]) : c[ch]) : (Number(c[ch]) || 0) + v;
+	return out;
+}