cozyclay 2.1.0 → 3.0.0

package/src/motion3/compiler/arm-orient.js

@@ -0,0 +1,128 @@
+// The arm turns a held object, not the wrist alone (docs/motion-api-v3.1.md C14, lane K8). When a
+// hand must take a world rotation (the object leads, hold.js), most of a held object's angle comes
+// from the elbow's swivel about the shoulder-wrist axis and from the forearm's turn about its own
+// axis (pronation and supination, the twist); the wrist adds the rest (flex and deviation).
+//   swivel    the elbow on the circle twoBone can put it on for this wrist: POLES poles are scored
+//             and their soft minimum (a Boltzmann-weighted mean pole) taken, so two near-equal
+//             poles blend instead of flipping; ../hold-plan.js smooths it over the frames
+//   score     each turn's squared share of its range, plus a steep price past the limits, plus a
+//             light pull toward the pole the channels gave (a keyed elbow_<side> is a preference)
+//             and the same steep price past SWING degrees from it (the upper arm's own roll limit:
+//             a straight arm swung half a turn would twist the shoulder, not hold the object)
+//   twist     the forearm bone takes FOREARM_SHARE of the turn about the forearm and the hand the
+//             rest, so the skin twists along the forearm instead of at the wrist alone
+// Everything here is analytic on the pose (no bone moves): twoBone's result does not depend on the
+// arm it starts from, so the forearm's frame for a pole is its rest frame aligned onto it.
+import { add, sub, scale, norm, dot, cross, len, mul, T, apply, align, clamp, quatFromMat, matFromQuat } from "./math.js";
+import { qmul, qconj, qlog, qexp } from "./quat.js";
+import { palmAxes, foldPoint, backOf } from "./limbs.js";
+
+/** Wrist limits in degrees, relative to the hand at rest on the forearm (twist: the forearm's turn). */
+export const WRIST_LIMITS = { twist: [-85, 85], flex: [-70, 70], dev: [-35, 20] };
+/**
+ * The comfortable part of each range, what observations.wrist counts frames past (qa/wrist-obs.js):
+ * daily tasks keep the wrist within about 40 deg of flex and extension and 25 ulnar / 15 radial
+ * deviation (Ryu et al.; Gates et al. 2016) and the forearm within 50 deg of pronation and supination
+ * (Morrey 1981).
+ */
+export const WRIST_COMFORT = { twist: [-50, 50], flex: [-40, 40], dev: [-25, 15] };
+/** The share of the turn about the forearm the forearm bone takes (the hand takes the rest). */
+export const FOREARM_SHARE = 0.5;
+/** The direction an arm's elbow points at rest, carried by the bones (pose.js, twoBone). */
+export const ELBOW_REST = [0, 0, -1];
+const POLES = 72, TEMP = 0.02, OVER = 400, PULL = 0.5, SWING = 100 / (180 / Math.PI), DEG = 180 / Math.PI;
+/**
+ * The shoulder's comfort (lane elbow): upper-arm elevation, degrees from hanging straight down (90 level, more
+ * the elbow over the shoulder). Daily handling (drinking, eating, a cup or a can at the mouth) keeps the upper
+ * arm low and forward, well below the level (Magermans et al. 2005); only overhead work lifts it. A pole pays
+ * SHOULDER_PRICE times the squared share of SHOULDER_SPAN it lifts the elbow past SHOULDER_COMFORT on the comfort
+ * landscape only (a carry whose aim keys may lean, key-aim.js): priced on every hold, it moved the bench's recompiled
+ * cup and can takes into wrist limits and QA (their keys were written for the elbow-up hold).
+ */
+const SHOULDER_COMFORT = 70, SHOULDER_SPAN = 30, SHOULDER_PRICE = 2;
+/** A wrist need's price against the comfortable range first and the limits second (the shape grip-choice.js prices a grip with): 1 at the comfortable edge, steep past it. */
+export function comfortPrice(need, steep = 8, over = 400) {
+	let cost = 0;
+	for (const k of ["twist", "flex", "dev"]) {
+		const v = need[k], c = v >= 0 ? WRIST_COMFORT[k][1] : -WRIST_COMFORT[k][0], L = v >= 0 ? WRIST_LIMITS[k][1] : -WRIST_LIMITS[k][0], a = Math.abs(v);
+		cost += a <= c ? (a / c) ** 2 : 1 + steep * ((Math.min(a, L) - c) / Math.max(1e-6, L - c)) ** 2 + (a > L ? over * ((a - L) / L) ** 2 : 0);
+	}
+	return cost;
+}
+
+/** The shoulder's price for an elbow at E with the shoulder at S (SHOULDER_COMFORT above). */
+export function shoulderPrice(S, E) {
+	const u = norm(sub(E, S)), el = Math.acos(clamp(-u[1], -1, 1)) * DEG;
+	return SHOULDER_PRICE * (Math.max(0, el - SHOULDER_COMFORT) / SHOULDER_SPAN) ** 2;
+}
+
+/** What the hand needs from neutral (its rest on the forearm) to goal, degrees { twist, flex, dev }; axT the forearm axis, l the palm's l axis at neutral. */
+export function wristNeed(neutral, goal, axT, l) {
+	let q = quatFromMat(mul(goal, T(neutral)));
+	if (q[3] < 0) q = q.map(v => -v);
+	const twist = 2 * Math.atan2(dot([q[0], q[1], q[2]], axT), q[3]), spin = qexp(scale(axT, twist));
+	const swing = qlog(qmul(q, qconj(spin))), lTwisted = apply(matFromQuat(spin), l);
+	const axF = norm(sub(lTwisted, scale(axT, dot(lTwisted, axT)))), axD = cross(axT, axF);
+	return { twist: twist * DEG, flex: dot(swing, axF) * DEG, dev: dot(swing, axD) * DEG, axF, axD };
+}
+
+/**
+ * The strain of a wrist need: each turn's squared share of its half range, plus OVER times the
+ * squared share past a limit; `margin` (a share of the half range) moves the limits that far in.
+ */
+function strainOf(need, margin = 0) {
+	let cost = 0;
+	for (const [k, [lo, hi]] of Object.entries(WRIST_LIMITS)) {
+		const z = (need[k] - (lo + hi) / 2) / ((hi - lo) / 2), over = Math.max(0, Math.abs(z) - 1 + margin);
+		cost += z * z + OVER * over * over;
+	}
+	return cost;
+}
+
+/**
+ * The arm's swivel landscape for hand rotation `goal` with the wrist at W, on pose s (the plain
+ * arm of `side`): at(th) -> { pv, need, elbow, cost } for the elbow th radians about the shoulder-wrist
+ * axis from `ref` (the bend direction the channels gave), angleOf(world direction) -> th,
+ * softmin() -> the th of the Boltzmann-weighted mean of POLES poles, miss the metres the arm is
+ * short of W (a wrist nearer the shoulder than the elbow folds is no miss here; hold.js holdCost
+ * prices it). `margin` tightens the wrist limits the strain prices (strainOf).
+ */
+export function landscape(sk, s, side, goal, W, ref, restBend, margin = 0, comfort = false) {
+	const I = sk.index, a = I[`${side}Arm`], fa = I[`${side}ForeArm`], h = I[`${side}Hand`], S = s.P[a];
+	const A = len(sub(s.P[fa], S)), B = len(sub(s.P[h], s.P[fa]));
+	// the elbow where twoBone puts it: the wrist no further folded than limbs.js foldPoint lets it
+	const v = sub(foldPoint(S, W, A, B, backOf(sk, s)), S), d = len(v), u = scale(v, 1 / Math.max(d, 1e-9)), dc = clamp(d, Math.abs(A - B) + 1e-4, (A + B) * 0.9995);
+	const along = (A * A - B * B + dc * dc) / (2 * dc), rad = Math.sqrt(Math.max(A * A - along * along, 0));
+	const off = x => sub(x, scale(u, dot(x, u))), e1 = norm(len(off(ref)) > 1e-6 ? off(ref) : cross(u, Math.abs(u[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0]));
+	const e2 = cross(u, e1), Wn = add(S, scale(u, dc));
+	const rw = sk.restWorldRot, faDir = apply(T(rw[fa]), sub(sk.restWorldPos[h], sk.restWorldPos[fa])), faBend = apply(T(rw[fa]), restBend);
+	const neutralRel = mul(T(rw[fa]), rw[h]), lLocal = apply(T(s.R[h]), palmAxes(sk, s, side).l);
+	const at = th => {
+		const pv = add(scale(e1, Math.cos(th)), scale(e2, Math.sin(th))), fdir = sub(Wn, add(S, add(scale(u, along), scale(pv, rad))));
+		const neutral = mul(align(faDir, faBend, fdir, pv), neutralRel), need = wristNeed(neutral, goal, norm(fdir), apply(neutral, lLocal));
+		const z = Math.abs(Math.atan2(Math.sin(th), Math.cos(th))) / SWING;
+		const elbow = add(S, add(scale(u, along), scale(pv, rad)));
+		// comfort (a carry that lets its aim lean, key-aim.js): the wrist priced against its comfortable range and the shoulder's price
+		return { pv, need, elbow, cost: (comfort ? comfortPrice(need) + shoulderPrice(S, elbow) : strainOf(need, margin)) + PULL * (1 - Math.cos(th)) + OVER * Math.max(0, z - 1) ** 2 };
+	};
+	const angleOf = x => (len(off(x)) > 1e-6 ? Math.atan2(dot(x, e2), dot(x, e1)) : 0);
+	const softmin = () => {
+		const all = Array.from({ length: POLES }, (_, i) => at((2 * Math.PI * i) / POLES)), low = Math.min(...all.map(p => p.cost));
+		const mean = all.reduce((m, p) => add(m, scale(p.pv, Math.exp(-(p.cost - low) / TEMP))), [0, 0, 0]);
+		return len(mean) > 1e-3 ? angleOf(mean) : (2 * Math.PI * all.findIndex(p => p.cost === low)) / POLES;
+	};
+	return { at, angleOf, softmin, miss: Math.max(0, d - dc) };
+}
+
+/**
+ * The elbow pole for hand rotation `goal` with the wrist at W (landscape above). opts.toward, a
+ * world direction, sets the pole instead of the soft minimum (a planned pole, ../hold-plan.js);
+ * opts.w (0..1, the keys' blend weight) scales the swing from ref, so the elbow eases out of and
+ * back into the plain arm; opts.margin as for landscape. Returns { pole, need, cost, miss }: pole
+ * a world direction for twoBone.
+ */
+export function swivel(sk, s, side, goal, W, ref, restBend, { toward, w = 1, margin = 0, comfort = false } = {}) {
+	const land = landscape(sk, s, side, goal, W, ref, restBend, margin, comfort), best = toward ? land.angleOf(toward) : land.softmin();
+	const pick = land.at(w * Math.atan2(Math.sin(best), Math.cos(best)));
+	return { pole: pick.pv, need: pick.need, cost: pick.cost, miss: land.miss, elbow: pick.elbow };
+}

package/src/motion3/compiler/channels.js

@@ -0,0 +1,125 @@
+// Keyed channels -> per-frame values. A channel is interpolated only through the keys that
+// set it; before its first key and after its last it holds. Numbers, number arrays and
+// {preset: weight} objects are supported. `step` keys jump at that frame (visibility switches
+// and the like).
+// Flow (spec.flow): the channels that place the body against the world or a target (feet,
+// root, yaw, hand targets and weights, poles, fingers, objects) are monotone cubic / PCHIP and on
+// time, so a held value never overshoots and a contact lands on its key. The body's own swing
+// (FLOW_SMOOTH: spine, head, arm swing and bend, wrist) carries its speed through a key instead of
+// stopping on it (Catmull-Rom, the overshoot past a key bounded), and trails the body
+// (FLOW_LAG frames: the head behind the body, the arms behind both), the trail easing out over the
+// take's last frames so every value is reached. An arm on its IK (armw) reaches for a target, so
+// flow is gone by the time the arm is a quarter of the way onto it: an arm's swing and bend by its
+// own armw, the spine (which carries the shoulders) and the head (the hands work near it) by the
+// larger of the two; a reach or a held prop lands as keyed. A hold (two equal keys in a row) stays
+// exactly flat either way.
+
+function pchipSlopes(x, y) {
+	const n = y.length, m = new Array(n).fill(0);
+	for (let i = 1; i < n - 1; i++) {
+		const h0 = x[i] - x[i - 1], h1 = x[i + 1] - x[i];
+		const d0 = (y[i] - y[i - 1]) / h0, d1 = (y[i + 1] - y[i]) / h1;
+		if (d0 * d1 > 0) {
+			const w1 = 2 * h1 + h0, w2 = h1 + 2 * h0;
+			m[i] = (w1 + w2) / (w1 / d0 + w2 / d1);
+		}
+	}
+	return m;
+}
+
+function pchipEval(x, y, m, q) {
+	if (x.length === 1 || q <= x[0]) return y[0];
+	if (q >= x[x.length - 1]) return y[y.length - 1];
+	let i = 0;
+	while (q > x[i + 1]) i++;
+	const h = x[i + 1] - x[i], t = (q - x[i]) / h;
+	const t2 = t * t, t3 = t2 * t;
+	return (2 * t3 - 3 * t2 + 1) * y[i] + (t3 - 2 * t2 + t) * h * m[i] + (-2 * t3 + 3 * t2) * y[i + 1] + (t3 - t2) * h * m[i + 1];
+}
+
+const FLOW_SMOOTH = /^(spine|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
+const FLOW_LAG = { spine: 0, head: 2, arms: 3 };
+const OVER_FRAC = 0.15, OVER_MAX = 6; // a smooth segment's overshoot: at most this share of its change, and degrees
+const ikSides = ch => (/^(spine|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
+const lagFamily = ch => (/^spine_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
+
+/** spec.flow -> { smooth, lag: { spine, head, arms } }: undefined is the default, false turns both off. */
+export function flowOptions(flow) {
+	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 } };
+	const f = flow ?? {}, lag = f.lag === false ? 0 : f.lag;
+	const each = typeof lag === "number" ? { spine: lag, head: lag, arms: lag } : { ...FLOW_LAG, ...(lag ?? {}) };
+	return { smooth: f.smooth !== false, lag: each };
+}
+
+/** Catmull-Rom slopes, flat at a hold and at the ends, each segment's overshoot bounded. */
+function smoothSlopes(x, y) {
+	const n = y.length, m = new Array(n).fill(0);
+	for (let i = 1; i < n - 1; i++) if (y[i] !== y[i - 1] && y[i] !== y[i + 1]) m[i] = (y[i + 1] - y[i - 1]) / (x[i + 1] - x[i - 1]);
+	for (let i = 0; i < n - 1; i++) {
+		const h = x[i + 1] - x[i], lo = Math.min(y[i], y[i + 1]), hi = Math.max(y[i], y[i + 1]), limit = Math.min(OVER_MAX, OVER_FRAC * (hi - lo));
+		for (let tries = 0; tries < 12; tries++) {
+			let over = 0;
+			for (let k = 1; k < 16; k++) {
+				const v = pchipEval([x[i], x[i + 1]], [y[i], y[i + 1]], [m[i], m[i + 1]], x[i] + (h * k) / 16);
+				over = Math.max(over, v - hi, lo - v);
+			}
+			if (over <= limit + 1e-9) break;
+			m[i] *= 0.7; m[i + 1] *= 0.7;
+		}
+	}
+	return m;
+}
+
+const shapeOf = v => (Array.isArray(v) ? "vec" : v && typeof v === "object" ? "map" : "num");
+
+/** keys: [{ f, set: { channel: value }, step?: [channel...] }] -> { channel: Array(frameCount) }; flow: flowOptions(spec.flow). */
+export function bakeChannels(keys, frameCount, flow = flowOptions()) {
+	const byChannel = new Map();
+	for (const key of [...keys].sort((a, b) => a.f - b.f)) {
+		for (const [ch, value] of Object.entries(key.set ?? {})) {
+			if (!byChannel.has(ch)) byChannel.set(ch, []);
+			byChannel.get(ch).push({ f: key.f, value, step: key.step?.includes(ch) });
+		}
+	}
+	const out = {}, plain = {};
+	for (const [ch, list] of byChannel) {
+		// later keys at the same frame win
+		const pts = [...new Map(list.map(k => [k.f, k])).values()];
+		const shape = shapeOf(pts[0].value);
+		const comps = shape === "vec" ? pts[0].value.length : 0;
+		const series = shape === "num" ? [pts.map(p => p.value)]
+			: shape === "vec" ? Array.from({ length: comps }, (_, i) => pts.map(p => p.value[i]))
+				: [...new Set(pts.flatMap(p => Object.keys(p.value)))].map(name => ({ name, y: pts.map(p => p.value[name] ?? 0) }));
+		const x = pts.map(p => p.f), smooth = flow.smooth && FLOW_SMOOTH.test(ch), lag = flow.lag[lagFamily(ch)] ?? 0;
+		// the trail eases out over the last 2 * lag frames, so the take ends on the last value
+		const at = f => (lag > 0 ? f - lag * Math.min(1, (frameCount - 1 - f) / (2 * lag)) : f);
+		const evalSeries = (y, flowing = true) => {
+			const m = smooth && flowing ? smoothSlopes(x, y) : pchipSlopes(x, y);
+			return q => {
+				const f = flowing ? at(q) : q;
+				// a step key holds the previous value right up to its frame
+				for (let i = 1; i < pts.length; i++) if (pts[i].step && f >= x[i - 1] && f < x[i]) return y[i - 1];
+				return pchipEval(x, y, m, f);
+			};
+		};
+		const frames = new Array(frameCount);
+		if (shape === "num") { const e = evalSeries(series[0]); for (let f = 0; f < frameCount; f++) frames[f] = e(f); }
+		else if (shape === "vec") { const es = series.map(evalSeries); for (let f = 0; f < frameCount; f++) frames[f] = es.map(e => e(f)); }
+		else {
+			const es = series.map(({ name, y }) => [name, evalSeries(y)]);
+			for (let f = 0; f < frameCount; f++) frames[f] = Object.fromEntries(es.map(([n, e]) => [n, e(f)]));
+		}
+		out[ch] = frames;
+		if (shape === "num" && (smooth || lag > 0) && ikSides(ch).length) { const e = evalSeries(series[0], false); plain[ch] = Array.from({ length: frameCount }, (_, f) => e(f)); }
+	}
+	// flow fades out as the arm goes onto its IK (the spine with either arm)
+	for (const [ch, keyed] of Object.entries(plain)) {
+		const ws = ikSides(ch).map(k => out[`armw_${k}`]).filter(Boolean);
+		if (!ws.length) continue;
+		out[ch] = out[ch].map((v, f) => { const w = Math.min(1, 4 * Math.max(0, ...ws.map(a => a[f]))); return v + (keyed[f] - v) * w * (2 - w); });
+	}
+	return out;
+}
+
+/** Frame f's channel dict. */
+export const channelsAt = (baked, f) => Object.fromEntries(Object.entries(baked).map(([k, v]) => [k, v[f]]));

package/src/motion3/compiler/compile.js

@@ -0,0 +1,205 @@
+// Motion spec -> baked frames. Deterministic and pure: the same spec and scene give the same
+// frames, so the agent can edit keys and recompile in a loop.
+//
+// spec = { schema: "cozyclay.motion-spec.v1", fps, frames, keys, anchors, props, fits, objects, generators, checks }
+//   keys:       [{ f, set: { channel: value }, step?: [channel] }]   (see pose.js for channel names)
+//   hand mix:   hand_<l|r> (world point) blended with w_<anchor>_<l|r> weights (anchors.js)
+//   fits:       [{ side, anchor, effector: { prop, point } | { joints: [...] }, offset? }]
+//               moves the wrist so the effector lands on the anchor whenever that weight is on
+//   objects:    { id: { pivot: [x,y,z], axis: [x,y,z], channel: "door" } }  hinge angle in degrees
+//               { id: { prop, grab?, release?, at?, along?, visible?, keys? } }   carried (../object-pose.js);
+//               keys lead the holding hand (../object-keys.js, hold.js)
+//               { id: { visible?, level? } }   a switch: shown/hidden and dimmed, never moved (C15)
+//               { id: { follow, offset?, aim?, visible?, level? } }   rides a point of the body (C16, ../follow.js)
+//               { id: { keys?, fall?, visible?, level? } }   moves on its own: keys and gravity falls (C17, ../free-motion.js)
+//               id is a body or a group (Empty); a group moves every body under it
+//   generators: [{ type: "walk", f0, ... }]  (walk.js)
+//   fix:        { reach, slide, penetration, retime }  deterministic auto-fixes (../fix/)
+//   flow:       { smooth, lag } | false  the body's swing carries through keys and trails (channels.js)
+//   idle:       false turns off the idle layer (idle.js: a held pose breathes, drifts its head, shifts its weight)
+// ctx = { sk, scene: { objects: { id: { pos, R, half, ancestors } } } }; out.ctx.scene keeps the scene (object-pose.js)
+import { add, sub, scale, norm, len, dot, apply, axisRot } from "./math.js";
+import { isCarried, isFollow, hingePose, movesRecord, compose, relative } from "../carried.js";
+import { isFree, freePoseAt } from "../free-motion.js";
+import { groupsOf } from "../scene.js";
+import { pose, SIDES } from "./pose.js";
+import { gripHand } from "./grip.js";
+import { bakeChannels, channelsAt, flowOptions } from "./channels.js";
+import { idleLayer, withIdle, busyHands } from "./idle.js";
+import { resolveAnchor, measureProps } from "./anchors.js";
+import { expandGenerators } from "./walk.js";
+import { steadyHead } from "./head-steady.js";
+import { fixOptions, applyFixes } from "../fix/index.js";
+import { fitWeight } from "../fix/self.js";
+import { holdHook } from "../object-keys.js";
+import { HAND_CLEAR, keepOut, wristBody } from "../body.js";
+import { objectPoseAt, handOf, restingAt } from "../object-pose.js";
+
+const smooth = x => x * x * (3 - 2 * x);
+
+/**
+ * Scene boxes by frame. A body moves with its own spec.objects entry or its nearest group's (a
+ * switch entry moves nothing; hinge: turned; free (C17): where its keys and falls put it, under the time map `mapOf()`;
+ * carry and follow: left at its scene pose and marked `carried` with the moving id). `obstacles` drops the carried
+ * ones: QA, refs and object anchors read a carry where it rides (object-pose.js objectPoseAt, qa/object-checks.js);
+ * a follow entry rides the body and is no obstacle.
+ */
+function objectTracks(spec, scene, baked, mapOf = () => undefined) {
+	const cache = new Map(), kept = new Map();
+	let map = mapOf();
+	const all = f => {
+		// a retime maps free keys and falls too: frames read before it are read again
+		if (mapOf() !== map) { map = mapOf(); cache.clear(); kept.clear(); }
+		if (cache.has(f)) return cache.get(f);
+		const out = {};
+		for (const [id, o] of Object.entries(scene?.objects ?? {})) {
+			const mover = [id, ...(o.ancestors ?? [])].find(k => movesRecord(spec.objects?.[k])), entry = spec.objects?.[mover];
+			if (!entry) out[id] = o;
+			else if (isCarried(entry) || isFollow(entry)) out[id] = { ...o, carried: mover };
+			else if (isFree(entry)) out[id] = { ...o, ...compose(freePoseAt({ spec, scene, timeMap: map }, mover, f), relative(scene.objects[mover] ?? groupsOf(scene)[mover], o)) };
+			else out[id] = { ...o, ...hingePose(entry, o, baked, f) };
+		}
+		cache.set(f, out);
+		return out;
+	};
+	const obstacles = f => {
+		if (mapOf() !== map) all(f);
+		if (!kept.has(f)) kept.set(f, Object.fromEntries(Object.entries(all(f)).filter(([, box]) => !box.carried)));
+		return kept.get(f);
+	};
+	return { all, obstacles };
+}
+
+function effectorPoint(sk, s, diag, eff) {
+	if (eff.prop) return diag.props?.[eff.prop]?.[eff.point];
+	const js = eff.joints ?? ["RightHandIndex2", "RightHandMiddle2"];
+	return scale(js.map(j => s.P[sk.index[j]]).reduce((a, p) => add(a, p), [0, 0, 0]), 1 / js.length);
+}
+
+/** `lead` false solves without the object keys; a fit's own hand is solved without them (the keys override it). */
+function hooksFor(ctx, c, f, inFit = false, lead = true, fitSide = null) {
+	const { sk } = ctx;
+	return {
+		softReach: ctx.softReach,
+		// a fit's passes find where the wrist must go with the elbow unstopped; the final pose stops its fold (limbs.js) and leaves the residual
+		foldFree: inFit,
+		hold: lead && ctx.hold ? (k, s) => (k === fitSide ? null : ctx.hold.lead(k, f, s, c)) : undefined,
+		// auto-fix offsets ride on the final pose only, so a fit never cancels them
+		push: inFit ? undefined : k => ctx.push?.[k]?.get(f),
+		swivel: k => ctx.swivel?.[k]?.get(f), // in a fit's passes too: a turn that stops at the wrist's limit moves the fit's point (wrist-clamp.js)
+		skinPush: inFit ? undefined : k => ctx.skinPush?.[k]?.get(f),
+		handTarget(k, s, diag) {
+			diag.frame = f;
+			const fkHand = s.P[sk.index[k === "l" ? "LeftHand" : "RightHand"]];
+			const terms = [];
+			for (const [ch, w] of Object.entries(c)) {
+				const m = /^w_(.+)_([lr])$/.exec(ch);
+				if (!m || m[2] !== k || !(w > 1e-6)) continue;
+				terms.push([w, add(resolveAnchor(ctx, m[1], s, diag, c, k), c[`fit_${m[1]}_${k}`] ?? [0, 0, 0])]);
+			}
+			let tot = terms.reduce((a, [w]) => a + w, 0);
+			if (tot > 1) { for (const t of terms) t[0] /= tot; tot = 1; }
+			let target = scale(c[`hand_${k}`] ?? fkHand, 1 - tot);
+			for (const [w, p] of terms) target = add(target, scale(p, w));
+			// Between targets, arc around the torso instead of cutting through it.
+			const trans = Math.max(0, ...terms.map(([w]) => smooth(Math.min(1, Math.min(w, 1 - w) * 3))));
+			if (trans > 0) {
+				const a = s.P[sk.index.Spine], b = s.P[sk.index.Neck], u = sub(b, a);
+				const t = Math.min(1, Math.max(0, dot(sub(target, a), u) / dot(u, u))), q = add(a, scale(u, t));
+				const r = ctx.spec.detourRadius ?? 0.25, dv = sub(target, q), d = len(dv);
+				if (d < r) {
+					const fwd = apply(axisRot([0, 1, 0], c.yaw ?? 0), [0, 0, 1]);
+					const dir = norm(add(d > 1e-6 ? scale(dv, 1 / d) : fwd, scale(fwd, 0.6)));
+					target = add(target, scale(sub(add(q, scale(dir, r)), target), trans));
+				}
+			}
+			// a wrist target inside the body (a pocket on a squatting thigh, a path through the chest) goes out onto its skin
+			return target;
+		},
+		// the wrist target, blended with the FK hand, inside the body goes out onto its skin, twice at most (out of
+		// one bone, then the next): a pocket the squat moved into the thigh, a path through the chest, a hand leaving
+		// a thigh for its FK rest. A measured target (a fit's anchor: the mouth; or a prop another hand's fit is on:
+		// the cigarette under the flame) stays where its goal needs it, and the move fades in and out with its weight;
+		// an arm coming in from FK moves it no more than its IK weight.
+		keepOut: ctx.keepOut && !inFit ? (k, s, target) => {
+			const free = (1 - fitWeight(ctx.spec, c, k)) * Math.min(1, Math.max(0, c[`armw_${k}`] ?? 0));
+			for (let i = 0; i < 2 && free > 1e-3; i++) {
+				const moved = keepOut(ctx.keepOut.body, sk, s, target, HAND_CLEAR, ctx.keepOut.skip);
+				if (moved === target) break;
+				target = add(target, scale(sub(moved, target), free));
+			}
+			return target;
+		} : undefined,
+		afterArm: (k, s, diag) => measureProps(ctx, k, s, diag),
+		// a fit's passes only place the wrist; the final pose (and a plain one) turns the hand onto the body
+		grip: inFit ? undefined : (k, s, diag) => gripHand(ctx, sk, s, SIDES[k], k, c, f, diag),
+	};
+}
+
+/** One frame with every active fit solved (fits run in spec order); lead false leaves the object keys out. */
+export function solveFrame(ctx, c0, f, lead = true) {
+	const c = { ...withIdle(c0, ctx.idle, f) };
+	// a working hand keeps its forearm's slant (pose.js arm_hang)
+	for (const k of ["l", "r"]) if (ctx.busy?.[k]) c[`hangoff_${k}`] = ctx.busy[k][f];
+	for (const fit of ctx.spec.fits ?? []) {
+		const wch = `w_${fit.anchor}_${fit.side}`;
+		if (!(c[wch] > 1e-4)) continue;
+		const full = { ...c, [wch]: 1, [`armw_${fit.side}`]: 1 };
+		for (const ch of Object.keys(full)) if (ch !== wch && new RegExp(`^w_.+_${fit.side}$`).test(ch)) full[ch] = 0;
+		let corr = [0, 0, 0];
+		for (let i = 0; i < 6; i++) {
+			full[`fit_${fit.anchor}_${fit.side}`] = corr;
+			const { s, diag } = pose(ctx.sk, full, hooksFor(ctx, full, f, true, lead, fit.side));
+			const eff = effectorPoint(ctx.sk, s, diag, fit.effector);
+			const goal = add(resolveAnchor(ctx, fit.anchor, s, diag, full, fit.side), fit.offset ?? [0, 0, 0]);
+			if (!eff) break;
+			corr = add(corr, sub(goal, eff));
+		}
+		c[`fit_${fit.anchor}_${fit.side}`] = corr;
+	}
+	const { s, diag } = pose(ctx.sk, c, hooksFor(ctx, c, f, false, lead));
+	// readers of the solved frame (refs, checks, hints) resolve its anchors at f, IK arms or not
+	diag.frame = f;
+	return { s, diag, c };
+}
+
+/**
+ * opts.window = [a, b] solves only frames a..b (out.f0 = a, out.frames[i] is frame a + i);
+ * opts.keys replaces the generator expansion; opts.fixes = false skips the auto-fix pass.
+ */
+export function compileMotion(spec, { sk, scene }, opts = {}) {
+	if (spec?.schema !== "cozyclay.motion-spec.v1") throw new Error("MOTION_SPEC_INVALID: schema must be cozyclay.motion-spec.v1");
+	const frameCount = Math.round(spec.frames);
+	if (!(frameCount >= 1 && frameCount <= 20000)) throw new Error("MOTION_SPEC_INVALID: frames must be 1..20000");
+	const fix = fixOptions(spec.fix);
+	const [a, b] = opts.window ? [Math.max(0, opts.window[0]), Math.min(frameCount - 1, opts.window[1])] : [0, frameCount - 1];
+	const ctx = { sk, spec, scene, softReach: fix.reach, push: { l: new Map(), r: new Map() }, swivel: { l: new Map(), r: new Map() }, skinPush: { l: new Map(), r: new Map() }, keepOut: fix.self ? wristBody(sk) : null };
+	const out = { ctx, fps: spec.fps ?? 30, frameCount, f0: a, frames: [] };
+	// object anchors read the pose refs read (object-pose.js), on the frame being solved
+	ctx.objectPose = (id, f, now) => objectPoseAt(out, id, f, now);
+	ctx.objectHand = (id, f) => handOf(out, id, f);
+	// a keyed carry's grab offset is taken where it rests at grab (object-keys.js; a fall before grab: where it landed)
+	ctx.restingAt = (id, f) => restingAt(out, id, f);
+	const engine = {
+		rebake(keys) {
+			out.keys = keys;
+			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
+			steadyHead(out.baked, keys, frameCount);
+			// a held pose breathes and shifts its weight (idle.js): offsets solveFrame adds, contacts and out.baked stay as keyed
+			ctx.idle = idleLayer(out.baked, { spec, sk, frameCount });
+			ctx.busy = busyHands(out.baked, spec, frameCount, out.fps);
+			const tracks = objectTracks(spec, scene, out.baked, () => out.timeMap);
+			ctx.objectsAt = tracks.all;
+			out.objectsAt = a ? f => tracks.obstacles(f + a) : tracks.obstacles;
+		},
+		solve(frames) { for (const f of frames) if (f >= a && f <= b) out.frames[f - a] = solveFrame(ctx, channelsAt(out.baked, f), f); },
+		all: () => Array.from({ length: b - a + 1 }, (_, i) => a + i),
+	};
+	ctx.hold = holdHook(ctx, out, f => solveFrame(ctx, channelsAt(out.baked, f), f, false), f => solveFrame(ctx, channelsAt(out.baked, f), f));
+	engine.rebake(opts.keys ?? expandGenerators(spec, sk));
+	engine.solve(engine.all());
+	out.fixed = opts.fixes === false ? {} : applyFixes(out, fix, engine, { whole: !opts.window });
+	// a retime maps the key frames only once it is done: solve the keyed frames again on the final map
+	if (ctx.hold && out.timeMap) engine.solve(engine.all());
+	return out;
+}

package/src/motion3/compiler/gait-rhythm.js

@@ -0,0 +1,97 @@
+// The walk's rhythm (walk.js): when each step lifts off, how long the foot is in the air, how far
+// it goes, how high it lifts and how much the arms swing. A person does not give every step the
+// same time: the first steps build up, the last one slows into the stop, one side is a little
+// quicker than the other, no two steps are alike, and a turn takes slower, shorter steps.
+// Deterministic (a hash of the walk's own parameters seeds the step-to-step part) and zero-sum:
+// the lift-offs are moved inside the walk's span (the walk still ends 16 + steps * period + 18
+// frames after f0) and the middle strides keep their sum (the walk ends where it did). The first
+// stride stays firstStep and the last step still brings the feet together.
+// A person's strides also differ in length from one another as wholes (both steps a little longer or shorter),
+// which the step-to-step terms alone do not show: their left/right part cancels over a stride. LENGTH.stride gives
+// each middle stride its own length. (A stride time term is left out: any more time variation lowers the hips'
+// rise and fall that walk-pelvis.js fits under the legs below a person's ~5 cm.)
+// vary scales every term: 0 is the metronome (every step period frames apart, swing frames in the
+// air, step metres long), 1 the default, 2 twice as uneven.
+const clamp = (x, a, b) => Math.min(b, Math.max(a, x));
+
+/** text -> a generator of numbers in [-1, 1) (FNV-1a hash, then mulberry32). */
+function noiseOf(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+	let a = h >>> 0;
+	return () => {
+		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) * 2 - 1;
+	};
+}
+
+// Sizes at vary 1, as fractions of the step's time or length.
+const TIME = { noise: 0.02, side: 0.03, first: 0.22, second: 0.08, last: 0.22, beforeLast: 0.08, turn: 0 };
+const LENGTH = { noise: 0.025, side: 0.012, stride: 0.035, second: 0.05, beforeLast: 0.06, turn: 0.06 };
+const LIFT = { noise: 0.1, first: 0.1, last: 0.25 }, ARM = 0.1;
+const CLOSE = 3; // frames the closing step may swing longer than swing
+const TURN_FULL = 60; // degrees turned in one step at which a step is as slow and short as a turn makes it
+
+/**
+ * walkRhythm(W, { s0, turn, seed }) -> per step i (0-based, W.steps of them):
+ *   lift[i]   frames after f0 + 16 at which the foot lifts off (lift[0] = 0)
+ *   air[i]    frames that foot is in the air
+ *   inc[i]    metres it advances along the path (inc[0] = firstStep, the last one 0)
+ *   height[i] its lift, m;  arm[i] a factor on the arm swing it lands with
+ * W: the walk's fields with defaults; s0 the path position the first step starts from; turn(sa, sb)
+ * the degrees the heading turns between two path positions; seed a text naming this walk.
+ */
+export function walkRhythm(W, { s0, turn, seed }) {
+	const n = W.steps, v = clamp(W.vary ?? 1, 0, 2), next = noiseOf(seed);
+	const rows = Array.from({ length: n }, () => ({ time: next(), length: next(), lift: next(), arm: next() }));
+	const quick = next() < 0 ? 1 : -1, side = i => (i % 2 === 0 ? quick : -quick);
+	// one draw per stride (steps 1-2, 3-4, ...), after the step draws so those stay as they were
+	const strides = Array.from({ length: Math.ceil(n / 2) }, () => next()), strideOf = i => strides[Math.floor((i - 1) / 2)];
+	const inc0 = Array.from({ length: n }, (_, i) => (i === n - 1 ? 0 : i === 0 ? W.firstStep : W.step));
+	let s = s0;
+	const turned = inc0.map(d => { const deg = Math.abs(turn(s, s + d)); s += d; return Math.min(1, deg / TURN_FULL); });
+	const long = n >= 4;
+	// time: a share of the walk's steps * period frames per step, the shares summing to steps
+	const share = rows.map((r, i) => {
+		if (n < 2) return 1;
+		// the first and the last step vary half as much: their build-up and slow-down should show
+		const ends = i === 0 || i === n - 1 ? 0.5 : 1;
+		let x = ends * (TIME.noise * r.time + TIME.side * side(i)) + TIME.turn * turned[i];
+		if (i === 0) x += TIME.first * (1 - turned[0]);
+		if (i === 1 && long) x += TIME.second;
+		if (i === n - 1) x += TIME.last;
+		if (i === n - 2 && long) x += TIME.beforeLast;
+		return 1 + v * x;
+	});
+	const total = share.reduce((a, b) => a + b, 0), span = n * W.period;
+	const lift = [];
+	for (let i = 0, t = 0; i < n; i++) { lift.push(Math.round(t)); t += (span * share[i]) / total; }
+	// air: a long step swings slower, keeping the double support the walk gives every step (period -
+	// swing), so the trailing foot leaves the ground no further behind the hips than in an even walk (its
+	// knee would snap straight at toe-off); a short step keeps its swing and shortens the double
+	// support instead, the trailing heel rising before the other foot lands. The closing step swings at
+	// most CLOSE frames longer: the hips go ahead over the other foot while it swings, and a slower
+	// trailing foot falls out of the leg's reach; the time left over is standing still
+	const support = W.period - W.swing;
+	const air = lift.map((t, i) => {
+		if (v === 0) return W.swing;
+		const gap = (i < n - 1 ? lift[i + 1] : span) - t;
+		return Math.min(gap - 2, Math.max(W.swing, gap - support), i === n - 1 ? W.swing + CLOSE : Infinity);
+	});
+	// length: the middle strides (not the first, not the closing one) keep their sum
+	const mid = inc0.map((_, i) => i > 0 && i < n - 1);
+	const g = rows.map((r, i) => {
+		if (!mid[i]) return 1;
+		let x = LENGTH.noise * (0.7 * r.length + 0.3 * r.time) + LENGTH.side * side(i) + LENGTH.stride * strideOf(i) - LENGTH.turn * turned[i];
+		if (i === 1 && long) x -= LENGTH.second;
+		if (i === n - 2 && long) x -= LENGTH.beforeLast;
+		return 1 + v * x;
+	});
+	const count = mid.filter(Boolean).length, sum = g.reduce((a, b, i) => a + (mid[i] ? b : 0), 0);
+	const inc = inc0.map((d, i) => (mid[i] && v > 0 ? (d * g[i] * count) / sum : d));
+	const height = rows.map((r, i) => W.lift * (1 + v * (LIFT.noise * r.lift - (i === 0 ? LIFT.first : 0) - (i === n - 1 && n > 1 ? LIFT.last : 0))));
+	const arm = rows.map(r => 1 + v * ARM * r.arm);
+	return { lift, air, inc, height, arm };
+}