cozyclay 2.1.1 → 3.0.0

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;
+}

package/src/motion3/compiler/limbs.js

@@ -0,0 +1,170 @@
+// Two-bone limb IK, foot orientation, wrist and finger posing on a world-space state.
+// Every edit rotates a bone's subtree about that bone's own joint, so the result maps
+// exactly back to local quaternions (skeleton.js toLocal).
+import { add, sub, scale, dot, len, norm, cross, clamp, apply, T, align, axisRot, ry, rx } from "./math.js";
+import { rotateSubtree } from "./skeleton.js";
+
+/** Direction fixed to bone b that points along `restDir` in the rest pose. */
+export const carried = (sk, s, b, restDir) => apply(s.R[b], apply(T(sk.restWorldRot[b]), restDir));
+
+// Elbow flexion: degrees between the upper arm and the forearm (0 straight), read on the joints as QA
+// reads it (Arm->ForeArm against ForeArm->Hand). Active flexion ends near 145 deg (clinical norms
+// 140-150: AMA 140, Kendall 145, AAOS 150), where the forearm's muscle meets the upper arm's; the
+// passive fold stops a few degrees on. An arm IK follows its wrist target freely to ELBOW_FOLD, eases
+// onto ELBOW_STOP (armReach) and leaves a target nearer the shoulder as a residual (REACH), like one
+// out of reach. Before, twoBone folded an arm flat: the forearm lay in the upper arm and the bend plane
+// was any plane at all (session df6acdcc, 171 deg).
+export const ELBOW_FOLD = 145, ELBOW_STOP = 150;
+// Knee flexion, read on the joints as QA reads it (UpLeg->Leg against Leg->Foot, 0 straight). Active
+// flexion ends near 135-140 deg (AAOS 135); past it the knee folds only passively, under the body's
+// weight, until the thigh rests on the calf: a deep squat with the heels down reaches 150-160 deg, and
+// passive flexion stops near 160 (the heel at the buttock). A leg IK follows its ankle target freely to
+// KNEE_FOLD (the squats the sessions keyed bend 125-138 deg), eases onto KNEE_STOP as the thigh presses
+// on the calf, and leaves a target nearer the hip as a residual (REACH leg_miss). Before, twoBone folded
+// a knee flat: the shin went into the thigh.
+export const KNEE_FOLD = 150, KNEE_STOP = 160;
+/** The flexion (deg) that puts the wrist d metres from the shoulder of an arm with bones a, b (180 at |a - b| or nearer). */
+export const flexionAt = (a, b, d) => (Math.acos(clamp((d * d - a * a - b * b) / (2 * a * b), -1, 1)) * 180) / Math.PI;
+/** The shoulder-wrist distance of an arm with bones a, b folded `deg` degrees. */
+export const reachAt = (a, b, deg) => Math.sqrt(a * a + b * b + 2 * a * b * Math.cos((deg * Math.PI) / 180));
+/**
+ * The shoulder-wrist distance an arm with bones a, b takes for a wrist target d metres away: d while
+ * the elbow folds ELBOW_FOLD or less (d >= k), then d + (k - d)^2 / 4w (w = k - the ELBOW_STOP distance)
+ * down to d = k - 2w, and the stop beyond. The wrist slows at a constant rate (C1, no kink as it
+ * engages: half the peak deceleration of an exponential ease as wide) and sits on the stop once the
+ * target is 2w inside. A leg passes KNEE_FOLD and KNEE_STOP (the hip-ankle distance).
+ */
+export function armReach(a, b, d, fold = ELBOW_FOLD, stop = ELBOW_STOP) {
+	const k = reachAt(a, b, fold);
+	if (d >= k) return d;
+	const w = k - reachAt(a, b, stop);
+	return d > k - 2 * w ? d + ((k - d) * (k - d)) / (4 * w) : k - w;
+}
+/**
+ * The wrist point an arm (shoulder S, bones a, b) reaches for a wrist target T: T while the elbow
+ * folds ELBOW_FOLD or less, else the point armReach(|T - S|) from the shoulder on the ray from the fold
+ * centre C through T. No point can stand for every target inside the stop and still move smoothly (a
+ * ball has no continuous retraction onto its boundary): the nearest point (the ray from the shoulder)
+ * whips round the shoulder as a target passes near it (session df6acdcc: 120 deg in 2 frames). So C
+ * sits on the stop's sphere straight behind the shoulder (`back`, the chest's -Z), in the back, where
+ * no hand reaches, and a target passing in front of, above, below or beside the shoulder glides.
+ * A leg passes the knee's fold and stop, and `back` is the pelvis's up (upOf): no foot goes into the
+ * pelvis, and a squat's ankle target under the hip goes on down from it.
+ */
+export function foldPoint(S, T, a, b, back, fold = ELBOW_FOLD, stop = ELBOW_STOP) {
+	const k = reachAt(a, b, fold), d = len(sub(T, S));
+	if (d >= k) return T;
+	const r = armReach(a, b, d, fold, stop), m = scale(back, reachAt(a, b, stop)), C = add(S, m), e = sub(T, C);
+	const u = len(e) > 1e-9 ? norm(e) : scale(back, -1), em = dot(u, m);
+	return add(C, scale(u, -em + Math.sqrt(Math.max(0, em * em - dot(m, m) + r * r))));
+}
+/** The direction behind the shoulders on pose s (the chest bone's rest -Z), where foldPoint's rays start. */
+export const backOf = (sk, s) => carried(sk, s, sk.index.Spine2 ?? sk.index.Hips, [0, 0, -1]);
+/** The direction up from the hips on pose s (the pelvis's rest +Y), where a knee's foldPoint rays start. */
+const upOf = (sk, s) => carried(sk, s, sk.index.Hips, [0, 1, 0]);
+/** The flexion (deg) an arm with bones a, b takes when `deg` is asked (armReach as an angle). */
+export const elbowFold = (a, b, deg) => flexionAt(a, b, armReach(a, b, reachAt(a, b, deg)));
+/** The flexion (deg) a wrist target asks of the arm of `side` on pose s (a leg's ankle target: bones UpLeg, Leg, Foot). */
+export function askedFold(sk, s, side, target, [u, m, e] = ["Arm", "ForeArm", "Hand"]) {
+	const S = s.P[sk.index[`${side}${u}`]], E = s.P[sk.index[`${side}${m}`]], W = s.P[sk.index[`${side}${e}`]];
+	return flexionAt(len(sub(E, S)), len(sub(W, E)), len(sub(target, S)));
+}
+
+/** Ease an elbow folded past ELBOW_FOLD (an FK abend) back as the IK would (elbowFold), the forearm turning in its bend plane. */
+export function limitFold(sk, s, side) {
+	const a = sk.index[`${side}Arm`], fa = sk.index[`${side}ForeArm`], up = sub(s.P[fa], s.P[a]), down = sub(s.P[sk.index[`${side}Hand`]], s.P[fa]);
+	const deg = (Math.acos(clamp(dot(norm(up), norm(down)), -1, 1)) * 180) / Math.PI, n = cross(up, down);
+	if (deg > ELBOW_FOLD && len(n) > 1e-12) rotateSubtree(sk, s, fa, s.P[fa].slice(), axisRot(n, elbowFold(len(up), len(down), deg) - deg));
+}
+
+/** The stops twoBone keeps to: the free fold and the stop (deg), and the fold centre's direction on pose s. */
+const STOPS = { elbow: [ELBOW_FOLD, ELBOW_STOP, backOf], knee: [KNEE_FOLD, KNEE_STOP, upOf] };
+
+/** Solve root-mid-end so `end` lands on `target` (clamped to reach), bending toward `pole`.
+ * `pole0` is the limb's current bend reference carried by the upper bone. Returns the miss (m).
+ * `stop`: "elbow" or "knee", the mid joint folds no further than armReach allows with that joint's
+ * fold and stop (foldPoint), and the miss is the residual either way (out of reach, or nearer the
+ * shoulder or hip than the fold). */
+export function twoBone(sk, s, root, mid, end, target, pole, restBend, stop = null) {
+	const Rt = s.P[root], M = s.P[mid], E = s.P[end];
+	const a = len(sub(M, Rt)), b = len(sub(E, M)), lim = STOPS[stop];
+	// a joint folds no further than armReach lets it: the end goes to foldPoint, and misses the target by the rest
+	const W = lim ? foldPoint(Rt, target, a, b, lim[2](sk, s), lim[0], lim[1]) : target, inside = W === target ? 0 : len(sub(W, target));
+	const v = sub(W, Rt), d = len(v), u = scale(v, 1 / Math.max(d, 1e-9));
+	const dc = clamp(d, Math.abs(a - b) + 1e-4, (a + b) * 0.9995);
+	const l = (a * a - b * b + dc * dc) / (2 * dc), h = Math.sqrt(Math.max(a * a - l * l, 0));
+	const pv = norm(sub(pole, scale(u, dot(pole, u))));
+	const Mn = add(Rt, add(scale(u, l), scale(pv, h)));
+	const p0 = carried(sk, s, root, restBend);
+	rotateSubtree(sk, s, root, Rt.slice(), align(sub(M, Rt), p0, sub(Mn, Rt), pv));
+	const p1 = carried(sk, s, mid, restBend);
+	const Tn = add(Rt, scale(u, dc));
+	rotateSubtree(sk, s, mid, s.P[mid].slice(), align(sub(s.P[end], s.P[mid]), p1, sub(Tn, s.P[mid]), pv));
+	return inside || d - dc;
+}
+
+/** Aim a foot: Foot->ToeBase along yaw/pitch of its rest direction, sole kept level. */
+export function orientFoot(sk, s, side, yawDeg, pitchDeg) {
+	const foot = sk.index[`${side}Foot`], toe = sk.index[`${side}ToeBase`];
+	const rest = sub(sk.restWorldPos[toe], sk.restWorldPos[foot]);
+	const want = apply(ry(yawDeg), apply(rx(pitchDeg), rest));
+	// level the sole: the foot's own carried up vector goes to world up (no roll from the leg IK)
+	rotateSubtree(sk, s, foot, s.P[foot].slice(), align(sub(s.P[toe], s.P[foot]), carried(sk, s, foot, [0, 1, 0]), want, [0, 1, 0]));
+	// Toe-off: bend the toe joint so the toes stay flat on the ground while the heel rises.
+	const tip = sk.index[`${side}Toe_End`];
+	if (pitchDeg > 0 && tip !== undefined) {
+		const seg = sub(s.P[tip], s.P[toe]), flat = [seg[0], 0, seg[2]];
+		if (len(flat) > 1e-6) rotateSubtree(sk, s, toe, s.P[toe].slice(), align(seg, [0, 1, 0], flat, [0, 1, 0]));
+	}
+}
+
+export function palmAxes(sk, s, side) {
+	const h = sk.index[`${side}Hand`], m1 = sk.index[`${side}HandMiddle1`];
+	const d = norm(sub(s.P[m1], s.P[h]));
+	let l = sub(s.P[sk.index[`${side}HandIndex1`]], s.P[sk.index[`${side}HandPinky1`]]);
+	l = norm(sub(l, scale(d, dot(l, d))));
+	return { d, l, n: cross(d, l) };
+}
+
+/** Turn the elbow `deg` about the shoulder-wrist line: the hand keeps its place and its world turn. */
+export function swivelElbow(sk, s, side, deg) {
+	const a = sk.index[`${side}Arm`], h = sk.index[`${side}Hand`], R = axisRot(sub(s.P[h], s.P[a]), deg);
+	rotateSubtree(sk, s, a, s.P[a].slice(), R);
+	rotateSubtree(sk, s, h, s.P[h].slice(), T(R));
+}
+
+/** Wrist twist (about the forearm) and flex (about the knuckle line), degrees, clamped. */
+export function wrist(sk, s, side, twistDeg, flexDeg) {
+	if (!twistDeg && !flexDeg) return;
+	const h = sk.index[`${side}Hand`], fa = sk.index[`${side}ForeArm`];
+	const axT = norm(sub(s.P[h], s.P[fa]));
+	const { l } = palmAxes(sk, s, side);
+	const axF = norm(sub(l, scale(axT, dot(l, axT))));
+	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axF, clamp(flexDeg, -70, 70)));
+	rotateSubtree(sk, s, h, s.P[h].slice(), axisRot(axT, clamp(twistDeg, -85, 85)));
+}
+
+// Finger curl presets, degrees per phalanx (1, 2, 3); thumb is [opposition, curl, curl].
+const FINGER_PRESETS = {
+	relaxed: { Index: [12, 18, 10], Middle: [15, 20, 12], Ring: [18, 22, 12], Pinky: [20, 24, 14], Thumb: [15, 10, 8] },
+	fist: { Index: [80, 95, 60], Middle: [85, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [45, 30, 35] },
+	grip: { Index: [55, 60, 35], Middle: [60, 62, 35], Ring: [62, 62, 35], Pinky: [65, 62, 35], Thumb: [40, 20, 20] },
+	cigarette: { Index: [8, 10, 6], Middle: [10, 12, 8], Ring: [60, 75, 45], Pinky: [65, 80, 45], Thumb: [35, 25, 20] },
+	point: { Index: [0, 0, 0], Middle: [80, 95, 60], Ring: [85, 95, 60], Pinky: [85, 95, 60], Thumb: [40, 30, 30] },
+};
+
+/** Blend presets by weight over `relaxed` and curl every finger toward the palm. */
+export function fingers(sk, s, side, weights) {
+	const base = FINGER_PRESETS.relaxed, sign = side === "Left" ? -1 : 1;
+	const curl = (f, k) => 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);
+	for (const f of ["Index", "Middle", "Ring", "Pinky", "Thumb"]) {
+		for (let k = 0; k < 3; k++) {
+			const j = sk.index[`${side}Hand${f}${k + 1}`];
+			if (j === undefined) continue;
+			const { l, d } = palmAxes(sk, s, side);
+			const ax = f === "Thumb" && k === 0 ? d : l;
+			rotateSubtree(sk, s, j, s.P[j].slice(), axisRot(ax, sign * curl(f, k)));
+		}
+	}
+}
+