cozyclay 2.1.0 → 3.0.0

package/src/motion3/compiler/walk-pelvis.js

@@ -0,0 +1,275 @@
+// The walk's hips, heel rise and swings (walk.js), hips first, the way a person walks:
+// - fitPelvis: the hips' height, as high as the legs holding them allow with the knee a person keeps through
+//   stance. A leg reaching for the floor straightens in terminal swing (REACH_IN periods before its strike) and
+//   strikes a little bent; it gives as the weight comes on (loading, LOAD_SPAN periods) and is nearly straight at
+//   mid-stance. Once the hips pass over a planted foot it no longer holds them down: its heel rises instead
+//   (fitTrail). The height runs on a C2 cubic spline (no kink) through a trough at each heel strike and the highest
+//   point the limit allows a quarter to a half of the way to the next strike (a person's hips top out as they pass
+//   over the foot, then fall with the flat foot's reach); no half-step bends it harder than CURVE, and an extremum
+//   comes down until the whole curve stays under the limit. Across the floor the hips
+//   keep the walk's path (walk.js keys), blurred XZ_BLUR frames so their speed has no kink.
+// - fitTrail: from the hips passing over a planted foot to its lift-off the heel rises, about the ball, just as
+//   far as the leg needs to reach with the stance knee and then the push-off knee (from walk.js's heel-off frame
+//   to KNEE_TOEOFF at lift-off), never lowered, never faster than PITCH_RATE a frame and never past PITCH_MAX
+//   (beyond about 60 deg the toes sit behind the ankle and QA reads a bent knee as bending backward); out of reach
+//   even then, the toe comes off the floor, the foot drawn toward the hip, as a person's does once the other foot
+//   is down.
+// - fitSwing: each swing on a clamped cubic spline from that lift-off, through walk.js's swing keys, into the strike;
+//   the foot's pitch follows the shank on the way.
+// The knee schedule eases with the walk's pace (brisk): a stroll strikes, loads and pushes off with straighter knees.
+import { bakeChannels } from "./channels.js";
+import { add, sub, scale, len, dot, apply, rx, ry, rz } from "./math.js";
+
+// knee flexion (deg): at the strike, the loading peak, mid-stance, and at lift-off (TRAIL_POW shapes the push-off:
+// slow while the other foot is in the air, fast once it lands); a quick walk (period down to FAST frames from SLOW)
+// bends them FAST_MORE further, as a person's knees give more the faster they walk
+const KNEE_STRIKE = 18, KNEE_LOAD = 22, KNEE_MID = 7, KNEE_TOEOFF = 45, TRAIL_POW = 1, LOAD_SPAN = 0.4, PITCH_MAX = 50, PITCH_RATE = 15;
+const SLOW = 13, FAST = 9, FAST_MORE = { strike: 4, load: 4, mid: 3, toeOff: 5 };
+// a slow walk keeps the knees straighter (a person strolling strikes and loads nearly straight-legged): the schedule
+// eases from STROLL at a pace of PACE[0] (walk.js's pace: 1 = 0.5 m per 20 frames) up to the one above at PACE[1]
+const STROLL = { strike: 2, load: 14, mid: 7, toeOff: 48, pow: 1.8 }, PACE = [1, 2.2];
+/** 0 at a stroll's pace, 1 at a brisk walk's, smooth between. */
+export const brisk = pace => { const t = Math.min(1, Math.max(0, ((pace ?? PACE[1]) - PACE[0]) / (PACE[1] - PACE[0]))); return t * t * (3 - 2 * t); };
+const SOFT = 0.004, EASE = 8, BELOW_STAND = 0.008, REACH_IN = 0.35, MARGIN = 0.001, XZ_BLUR = 2;
+// a strike's trough is the lowest limit from 2 frames before it to TROUGH_SPAN periods after (its loading)
+const TROUGH_SPAN = 0.25, PEAK = [0.25, 0.5], CURVE = 0.008, smoother = t => t * t * t * (t * (6 * t - 15) + 10);
+// the keys fitSwing writes, so a second pass reads walk.js's swing keys only
+const SWUNG = new WeakSet();
+
+/**
+ * Appends a root key per frame between f0 and end to `out` (the walk's keys). ground: per foot, its spans on
+ * the ground, { a, b, strike, heel }: from a (a heel strike, or f0) to b (its lift-off), heel the frame its
+ * heel starts up before that lift; start the src of keys before the first step. The keys keep the root's path across the
+ * floor; only its height changes.
+ */
+/** A foot pitched `deg` about a point on the ground (its heel or ball), heading yw: where the ankle goes. */
+export const pivot = (p, yw, deg, from) => add(p, apply(ry(yw), apply(rx(deg), apply(ry(-yw), sub(from, p)))));
+
+/** The leg's reach at a knee flexion, the hip joints from the hips, and the knee schedule of a walk of this period. */
+function legOf(sk, period, pace) {
+	const I = sk.index, P = sk.restWorldPos;
+	const a = len(sub(P[I.LeftLeg], P[I.LeftUpLeg])), b = len(sub(P[I.LeftFoot], P[I.LeftLeg]));
+	const q = Math.min(1, Math.max(0, (SLOW - period) / (SLOW - FAST))), u = brisk(pace), mix = (s, k) => s + (k - s) * u;
+	const strike = mix(STROLL.strike, KNEE_STRIKE) + q * FAST_MORE.strike, load = mix(STROLL.load, KNEE_LOAD) + q * FAST_MORE.load;
+	const mid = mix(STROLL.mid, KNEE_MID) + q * FAST_MORE.mid, toeOff = mix(STROLL.toeOff, KNEE_TOEOFF) + q * FAST_MORE.toeOff;
+	return {
+		reach: deg => Math.sqrt(a * a + b * b + 2 * a * b * Math.cos((deg * Math.PI) / 180)),
+		hipOff: { l: sub(P[I.LeftUpLeg], P[I.Hips]), r: sub(P[I.RightUpLeg], P[I.Hips]) },
+		strike, load, mid, trail: u => mid + (toeOff - mid) * Math.min(1, Math.max(0, u)) ** mix(STROLL.pow, TRAIL_POW),
+	};
+}
+const hipAt = (ch, f, off) => add(ch.root[f], apply(ry(ch.yaw?.[f] ?? 0), apply(rz(ch.roll?.[f] ?? 0), off)));
+
+export function fitPelvis(sk, out, { f0, end, period, pace, ground, start }) {
+	const I = sk.index, P = sk.restWorldPos;
+	const { reach, hipOff, strike, load, mid, trail } = legOf(sk, period, pace);
+	const lead = Math.max(2, Math.round(REACH_IN * period));
+	const knee = (g, f) => {
+		if (f < g.a) return strike;
+		if (g.heel !== undefined && f >= g.heel) return trail((f - g.heel) / Math.max(1, g.b - g.heel));
+		// loading: from the strike's knee up to the loading peak half way through LOAD_SPAN, then down to mid-stance's
+		const u = (f - g.a) / period / LOAD_SPAN;
+		return g.strike && u < 1 ? (u < 0.5 ? strike : mid) + (load - (u < 0.5 ? strike : mid)) * Math.sin(Math.PI * u) : mid;
+	};
+	const ch = bakeChannels(out, end + 1), top = P[I.Hips][1] - BELOW_STAND;
+	// the path across the floor, blurred twice (ends held), so the forward speed has no kink
+	let xz = ch.root.map(r => [r[0], r[2]]);
+	for (let pass = 0; pass < 2; pass++) xz = xz.map((p, f) => {
+		if (f <= f0 || f >= end) return p;
+		let sx = 0, sz = 0, w = 0;
+		for (let d = -3 * XZ_BLUR; d <= 3 * XZ_BLUR; d++) { const g = Math.min(end, Math.max(f0, f + d)), k = Math.exp(-(d * d) / (2 * XZ_BLUR * XZ_BLUR)); sx += k * xz[g][0]; sz += k * xz[g][1]; w += k; }
+		const t = Math.min(1, (f - f0) / EASE, (end - f) / EASE), e = t * t * (3 - 2 * t);
+		return [p[0] + (sx / w - p[0]) * e, p[1] + (sz / w - p[1]) * e];
+	});
+	// the highest the hips may be at frame f, eased in from the pose before the walk and out into the stand after it
+	const limit = f => {
+		const root = [xz[f][0], ch.root[f][1], xz[f][1]], yaw = ch.yaw?.[f] ?? 0, roll = ch.roll?.[f] ?? 0, ys = [];
+		for (const k of ["l", "r"]) {
+			const g = ground[k].find(x => f >= x.a - (x.strike ? lead : 0) && f <= x.b);
+			// once the hips pass over a planted foot it no longer holds them down: its heel rises as far as it must and
+			// past PITCH_MAX its toe leaves the floor (fitTrail)
+			if (!g || (g.free !== undefined && f >= g.free)) continue;
+			const ankle = ch[`foot_${k}`][f], off = apply(ry(yaw), apply(rz(roll), hipOff[k]));
+			const d = reach(knee(g, f)), dh = Math.hypot(root[0] + off[0] - ankle[0], root[2] + off[2] - ankle[2]);
+			if (dh < d) ys.push(ankle[1] + Math.sqrt(d * d - dh * dh) - off[1]);
+		}
+		if (!ys.length) return top;
+		const m = Math.min(...ys), fit = Math.min(top, m - SOFT * Math.log(ys.reduce((s, y) => s + Math.exp(-(y - m) / SOFT), 0))) - MARGIN;
+		const t = Math.min(1, (f - f0) / EASE, (end - f) / EASE), w = t * t * (3 - 2 * t);
+		return root[1] + (fit - root[1]) * w;
+	};
+	// the frame the hips pass over each planted foot (its ankle along the foot's heading)
+	for (const k of ["l", "r"]) for (const g of ground[k]) {
+		if (g.heel === undefined || !g.flat) continue;
+		const fw = apply(ry(g.yw), [0, 0, 1]);
+		let f = Math.max(f0 + 1, g.a);
+		while (f < g.heel && (xz[f][0] - g.flat[0]) * fw[0] + (xz[f][1] - g.flat[2]) * fw[2] < 0) f++;
+		g.free = f;
+	}
+	const low = [];
+	for (let f = f0; f <= end; f++) low[f] = limit(f);
+	// extrema: the pose before the walk, a trough over each strike's loading, the highest point between, the stand after
+	const loadSpan = Math.max(2, Math.round(TROUGH_SPAN * period)), lowest = (a, b) => { let m = a; for (let f = a; f <= b; f++) if (low[f] < low[m]) m = f; return m; };
+	const strikes = [...new Set(["l", "r"].flatMap(k => ground[k].filter(g => g.strike && g.a > f0 + 2 && g.a < end - 2).map(g => g.a)))].sort((p, q) => p - q);
+	const knots = [{ f: f0, y: low[f0] }];
+	strikes.forEach((a, n) => {
+		const t = lowest(Math.max(knots.at(-1).f + 2, a - 2), Math.min(end - 2, a + loadSpan));
+		// the peak between two troughs: of the frames PEAK of the way between them, the one whose highest smootherstep rise
+		// from the last trough and fall to this one both stay under the limit is highest (smootherstep stands in for the
+		// spline here: it is the flatter of the two at each end)
+		if (n > 0) {
+			const A = knots.at(-1), B = { f: t, y: low[t] }, span = B.f - A.f;
+			let best = null;
+			for (let c = Math.ceil(A.f + PEAK[0] * span); c <= Math.floor(A.f + PEAK[1] * span); c++) {
+				let top = low[c];
+				for (let f = A.f + 1; f < c; f++) { const w = smoother((f - A.f) / (c - A.f)); if (w > 1e-6) top = Math.min(top, A.y + (low[f] - A.y) / w); }
+				for (let f = c + 1; f < B.f; f++) { const w = smoother((f - c) / (B.f - c)); if (w < 1 - 1e-6) top = Math.min(top, (low[f] - B.y * w) / (1 - w)); }
+				if (!best || top > best.y) best = { f: c, y: top };
+			}
+			if (best && best.y > Math.max(A.y, B.y)) knots.push(best);
+		}
+		if (t > knots.at(-1).f) knots.push({ f: t, y: low[t] });
+	});
+	knots.push({ f: end, y: low[end] });
+	// no half-step bends the hips harder than CURVE (a spline's turn is about 2 rise / frames^2): a peak
+	// too high for the frames it has to the next trough comes down
+	for (let n = 1; n + 1 < knots.length; n++) {
+		const K = knots[n], room = Math.min(...[knots[n - 1], knots[n + 1]].map(o => o.y + (CURVE * (K.f - o.f) ** 2) / 2));
+		if (K.y > Math.max(knots[n - 1].y, knots[n + 1].y)) K.y = Math.min(K.y, room);
+	}
+	// the spline through the knots; a segment that rises past the limit lowers its higher knot by the excess
+	let y = [];
+	for (let pass = 0; pass < 30; pass++) {
+		let worst = 0;
+		const S = spline(knots.map(K => K.f), knots.map(K => K.y), 0, 0);
+		for (let n = 0; n + 1 < knots.length; n++) {
+			const A = knots[n], B = knots[n + 1];
+			let ex = 0;
+			for (let f = A.f; f <= B.f; f++) { y[f] = S(f); ex = Math.max(ex, y[f] - low[f]); }
+			if (ex > 0.0003) { const hi = A.y > B.y && n > 0 ? A : B.f === end ? A : B; if (hi.f !== f0 && hi.f !== end) { hi.y -= ex; worst = Math.max(worst, ex); } }
+		}
+		if (!worst) break;
+	}
+	for (let f = f0; f <= end; f++) y[f] = Math.min(y[f], low[f]);
+	// each key names the step it falls in, so QA's causes and hints still point at that step of the walk
+	const steps = out.filter(k => / step \d+$/.test(k.src ?? "")).sort((p, q) => p.f - q.f);
+	let i = 0, src = start;
+	for (let f = f0 + 1; f < end; f++) {
+		while (i < steps.length && steps[i].f <= f) src = steps[i++].src;
+		out.push({ f, set: { root: [xz[f][0], y[f], xz[f][1]] }, src });
+	}
+}
+
+/**
+ * The planted foot's heel rise, once the hips are set (fitPelvis): each frame from the hips passing over it to lift-off
+ * pitches the foot about its ball just far enough that the leg reaches it with the knee the stance keeps (mid-stance's,
+ * then the push-off's from walk.js's heel-off frame), so the heel comes up when the leg needs it to; never lowering the
+ * heel again and never past PITCH_MAX. Its keys replace walk.js's scheduled rise on the same frames.
+ */
+export function fitTrail(sk, out, { end, period, pace, ground }) {
+	const { reach, hipOff, trail } = legOf(sk, period, pace), ch = bakeChannels(out, end + 1);
+	const srcAt = new Map(out.map(x => [x.f, x.src]));
+	for (const k of ["l", "r"]) for (const g of ground[k]) {
+		if (g.free === undefined || !Number.isFinite(g.b) || g.b > end) continue;
+		// the pitch each frame needs (never lowering), then raised ahead of any rise faster than PITCH_RATE a frame
+		const need = [], frames = [];
+		let prev = 0;
+		for (let f = g.free; f <= g.b; f++) {
+			const hip = hipAt(ch, f, hipOff[k]), want = reach(trail((f - g.heel) / Math.max(1, g.b - g.heel)));
+			const far = p => len(sub(hip, pivot(g.ball, g.yw, p, g.flat))) - want;
+			let lo = prev, hi = PITCH_MAX;
+			if (far(lo) <= 0) hi = lo;
+			else if (far(hi) <= 0) for (let n = 0; n < 24; n++) { const m = (lo + hi) / 2; if (far(m) > 0) lo = m; else hi = m; }
+			prev = hi; need.push(hi); frames.push({ f, hip, want });
+		}
+		let pitch = need.map((_, i) => Math.max(...need.slice(i).map((p, j) => p - j * PITCH_RATE)));
+		// eased (never under the need): the rise starts and ends without a kink, which would jolt the knee
+		for (let pass = 0; pass < 2; pass++) pitch = pitch.map((p, i) => Math.max(need[i], ((pitch[i - 1] ?? 0) + p + (pitch[i + 1] ?? p)) / 3));
+		frames.forEach(({ f, hip, want }, i) => {
+			// out of reach even at PITCH_MAX: the toe comes off the floor, the foot drawn toward the hip to the push-off knee
+			let ankle = pivot(g.ball, g.yw, pitch[i], g.flat);
+			const gap = len(sub(hip, ankle)) - want;
+			if (gap > 0) ankle = add(ankle, scale(sub(hip, ankle), gap / len(sub(hip, ankle))));
+			out.push({ f, set: { [`foot_${k}`]: ankle, [`fpitch_${k}`]: pitch[i], [`fyaw_${k}`]: g.yw }, src: srcAt.get(f) });
+		});
+	}
+}
+
+/** A clamped cubic spline through (xs, ys) with end slopes d0, dn: C2 inside, so a path through it has no kinks. */
+function spline(xs, ys, d0, dn) {
+	const n = xs.length - 1, h = xs.slice(1).map((x, i) => x - xs[i]), a = [], b = [], c = [], r = [];
+	for (let i = 0; i <= n; i++) {
+		if (i === 0) { a[i] = 0; b[i] = 2 * h[0]; c[i] = h[0]; r[i] = 6 * ((ys[1] - ys[0]) / h[0] - d0); }
+		else if (i === n) { a[i] = h[n - 1]; b[i] = 2 * h[n - 1]; c[i] = 0; r[i] = 6 * (dn - (ys[n] - ys[n - 1]) / h[n - 1]); }
+		else { a[i] = h[i - 1]; b[i] = 2 * (h[i - 1] + h[i]); c[i] = h[i]; r[i] = 6 * ((ys[i + 1] - ys[i]) / h[i] - (ys[i] - ys[i - 1]) / h[i - 1]); }
+	}
+	for (let i = 1; i <= n; i++) { const m = a[i] / b[i - 1]; b[i] -= m * c[i - 1]; r[i] -= m * r[i - 1]; }
+	const M = []; M[n] = r[n] / b[n];
+	for (let i = n - 1; i >= 0; i--) M[i] = (r[i] - c[i] * M[i + 1]) / b[i];
+	return x => {
+		let i = 0; while (i < n - 1 && x > xs[i + 1]) i++;
+		const t = x - xs[i], H = h[i], A = (xs[i + 1] - x) / H, B = t / H;
+		return A * ys[i] + B * ys[i + 1] + ((A ** 3 - A) * M[i] + (B ** 3 - B) * M[i + 1]) * H * H / 6;
+	};
+}
+
+// the swing foot keeps the ankle near neutral, as a person's does: its pitch follows the shank (SWING_DORSI deg toes-up
+// of it), eased in from the toe-off's pitch over FOLLOW_IN of the swing and out into the strike's over FOLLOW_OUT, the
+// ball held BALL_CLEAR m over its flat height away from the ends, the pitch no more than PITCH_MAX (a foot kept level would flap at the ankle as the shank swings)
+const SWING_DORSI = 3, FOLLOW_IN = 0.35, FOLLOW_OUT = 0.2, BALL_CLEAR = 0.03, HEEL_FREE = 0.04, HEEL_LOW = 0.025, deg = r => (r * 180) / Math.PI;
+const ease = x => { const t = Math.min(1, Math.max(0, x)); return t * t * (3 - 2 * t); };
+
+/** The shank's tilt (deg, + with the ankle behind the knee) of a leg from hip H to ankle A, thigh a, shank b, knee forward fw. */
+function shankTilt(H, A, fw, a, b) {
+	const d = sub(A, H), L = Math.min(a + b - 1e-6, Math.max(Math.abs(a - b) + 1e-6, len(d))), u = scale(d, 1 / len(d));
+	let v = sub(fw, scale(u, dot(fw, u)));
+	v = scale(v, 1 / (len(v) || 1));
+	const c = (a * a + L * L - b * b) / (2 * a * L), K = add(H, add(scale(u, a * c), scale(v, a * Math.sqrt(Math.max(0, 1 - c * c))))), sh = sub(A, K);
+	return deg(Math.atan2(-dot(sh, fw), -sh[1]));
+}
+
+/**
+ * Each swing (lift-off to the next strike of that foot), once the toe-off is set (fitTrail): the ankle runs on a
+ * clamped cubic spline from the lift-off, at the speed the push-off leaves it with, through walk.js's swing keys
+ * (the heel kicked up behind, mid-swing, over the strike) into the strike at the heel rocker's speed, keyed every
+ * frame: the knee and the foot move without the kinks per-channel keys leave where the path turns. Given the skeleton
+ * (the last pass, the hips set), each frame's foot pitch follows the shank too.
+ */
+export function fitSwing(out, { end, ground, sk }) {
+	const ch = bakeChannels(out, end + 2), srcAt = new Map(out.map(x => [x.f, x.src]));
+	const I = sk?.index, P = sk?.restWorldPos, a = sk && len(sub(P[I.LeftLeg], P[I.LeftUpLeg])), b = sk && len(sub(P[I.LeftFoot], P[I.LeftLeg]));
+	for (const k of ["l", "r"]) {
+		const spans = ground[k], side = k === "l" ? "Left" : "Right";
+		const hipOff = sk && sub(P[I[`${side}UpLeg`]], P[I.Hips]), ball = sk && sub(P[I[`${side}ToeBase`]], P[I[`${side}Foot`]]), ballY = sk && P[I[`${side}ToeBase`]][1];
+		// QA's heel point from the ankle (qa/geometry.js solePoints)
+		const heel = sk && [0, 0.005 - P[I[`${side}Foot`]][1], -0.045];
+		for (let n = 0; n + 1 < spans.length; n++) {
+			const g = spans[n], h = spans[n + 1];
+			if (!Number.isFinite(g.b) || !h.strike || h.a > end || h.a - g.b < 3) continue;
+			const via = [...new Set(out.filter(x => !SWUNG.has(x) && x.f > g.b && x.f < h.a && x.set[`foot_${k}`]).map(x => x.f))].sort((p, q) => p - q);
+			const xs = [g.b, ...via, h.a], foot = ch[`foot_${k}`], at = f => foot[Math.max(0, Math.min(foot.length - 1, f))];
+			const v0 = sub(at(g.b), at(g.b - 1)), vn = sub(at(h.a + 1), at(h.a));
+			const axes = [0, 1, 2].map(i => spline(xs, xs.map(f => at(f)[i]), v0[i], vn[i]));
+			const yawAt = f => ch[`fyaw_${k}`]?.[f] ?? 0, pitchAt = f => ch[`fpitch_${k}`]?.[f] ?? 0;
+			const follow = (f, p) => shankTilt(hipAt(ch, f, hipOff), p, apply(ry(yawAt(f)), [0, 0, 1]), a, b) - SWING_DORSI;
+			const span = h.a - g.b, off0 = sk && pitchAt(g.b) - follow(g.b, at(g.b)), off1 = sk && pitchAt(h.a) - follow(h.a, at(h.a));
+			for (let f = g.b + 1; f < h.a; f++) {
+				const p = axes.map(e => e(f)), set = { [`foot_${k}`]: p };
+				if (sk) {
+					// never past PITCH_MAX (QA would read the bent knee as bending backward)
+					let pitch = Math.min(PITCH_MAX, follow(f, p) + off0 * (1 - ease((f - g.b) / (FOLLOW_IN * span))) + off1 * (1 - ease((h.a - f) / (FOLLOW_OUT * span))));
+					// the ball no lower than its flat height plus BALL_CLEAR (eased in and out over 3 frames at the ends)
+					const floor = ballY + BALL_CLEAR * ease(Math.min(f - g.b, h.a - f) / 3), ballAt = d => p[1] + apply(rx(d), ball)[1];
+					if (ballAt(pitch) < floor) { let lo = -30, hi = pitch; for (let it = 0; it < 20; it++) { const m = (lo + hi) / 2; if (ballAt(m) < floor) hi = m; else lo = m; } pitch = lo; }
+					// toes up lowers the heel: it comes no lower than HEEL_LOW (or the walk's keys, if they had it lower), so the strike
+					// lands when it did and the heel never skims the floor
+					const was = pitchAt(f), heelAt = d => p[1] + apply(rx(d), heel)[1], low = Math.min(HEEL_FREE, Math.max(heelAt(was), HEEL_LOW));
+					if (pitch < was && heelAt(pitch) < low) { let lo = pitch, hi = was; for (let it = 0; it < 20; it++) { const m = (lo + hi) / 2; if (heelAt(m) < low) lo = m; else hi = m; } pitch = hi; }
+					set[`fpitch_${k}`] = pitch;
+				}
+				const key = { f, set, src: srcAt.get(f) };
+				SWUNG.add(key); out.push(key);
+			}
+		}
+	}
+}

package/src/motion3/compiler/walk.js

@@ -0,0 +1,207 @@
+// Generators expand into ordinary keys before baking. "walk" plans footsteps along a curving
+// path from the pose the earlier keys leave at f0: weight shift over the stance foot, pelvis
+// bob and twist, toe-off, arm swing, feet together at the end. The steps keep a natural rhythm
+// (gait-rhythm.js): period, swing, step, lift and armSwing are the averages, vary: 0 makes every
+// step exactly those.
+//
+// { type: "walk", f0, steps: 8, step: 0.5, period: 20, swing: 14, halfWidth: 0.08, lift: 0.08,
+//   heading: [h0, h1], turnDistance: 0.4, pelvisHigh: dy, pelvisLow: dy, firstStep: 0.4, armSwing: 14, vary: 1 }
+// heading in degrees (yaw convention); pelvis heights are offsets from the standing hips height.
+// The feet roll as a person's do, heel first (the three rockers of gait): the heel strikes with the
+// toes up and the foot rolls down about the heel to flat; it stays flat while the shin passes over
+// it; the heel comes up well before lift-off and the foot rolls over the ball, toes flat, to toe-off;
+// in the air the foot follows the shin, the ankle near neutral (walk-pelvis.js fitSwing), into the next strike.
+// The heel strikes with the toes up STRIKE_DF (a stroll's, then a brisk walk's), half that on the closing step (a walk generated from motion
+// capture lands with the foot nearly flat: the heel touches a frame or two before the sole); TOE_OFF is the push-off pitch at a full stride (STRIDE_REF m of foot travel), less for
+// a shorter one. A pivot is the very point QA reads (qa/geometry.js solePoints), so a rolling foot
+// never counts as sliding.
+// The upper body leads the legs and its sizes follow the pace (the speed against the default walk's 0.5 m per 20 frames),
+// as a person's do: the slower the walk, the less the arms swing and the more the trunk dips and sways. Each arm peaks
+// forward or back at a step's mid-swing (the arm's flow lag puts the visible peak about a quarter of a step before the
+// strike), ARM_SWING deg a unit of pace (armSwing, when not given); each elbow bends with its swing, most with the arm
+// forward and least behind (ELBOW +- ELBOW_SWING, both growing with the pace), and the hands hang with the wrists a
+// little flexed (WRIST). The pelvis and chest turns, the side sway and the dip each peak at their own phase of the step
+// (the constants below). All of it fades in over the first steps and back out on the closing one.
+import { add, sub, scale, len, apply, ry, clamp } from "./math.js";
+import { walkRhythm } from "./gait-rhythm.js";
+import { fitPelvis, fitTrail, fitSwing, pivot, brisk } from "./walk-pelvis.js";
+
+const STRIKE_DF = [6, 4], TOE_OFF = 50, STRIDE_REF = 1.1, ELBOW = [18, 3], ELBOW_SWING = [6, 3], WRIST = 8;
+// The trunk over the stepping hips (degrees at a full stride, less for a shorter one): the pelvis drops on the
+// swing side in single support (LIST), the trunk held over it but for SWAY of it; the pelvis turns with the leading
+// leg (PELVIS_TURN) and the chest the other way (CHEST_TURN); the trunk dips forward before each strike and back in
+// single support (LEAN).
+const LIST = 4.5, SWAY = 0.26, PELVIS_TURN = 4.5, CHEST_TURN = 5.5, MID_SLOW = 0.015, STRIKE_AHEAD = [0.52, 0.64], HEEL_OFF = 0.3, HEEL_MIN = 4;
+// the upper body by the pace p (module doc), measured against motion-capture walks of 0.7 and 1.4 m/s: the arm swing
+// (ARM_SWING deg a unit of pace, at the strike ARM_FALL of its wave: a hanging arm falls back from its peak a little
+// ahead of a sine); the chest turn peaking CHEST_AT(p) steps before the strike and the pelvis turn PELVIS_AT(p)
+// steps after it (at a stroll the two turn nearly together, at a brisk walk against each other); the side sway SIDE(p)
+// deg peaking SIDE_AT steps before the strike (just after the last); the dip LEAN(p) deg with its peaks LEAN_AT steps
+// before the strike, about a forward lean of WALK_LEAN deg a unit of pace
+const ARM_SWING = 6.4, ARM_FALL = 0.8, CHEST_AT = p => clamp(0.66 - 0.18 * p, 0.2, 0.48), PELVIS_AT = p => clamp(0.32 - 0.11 * p, 0, 0.45);
+const SIDE = p => clamp(2.8 - 0.45 * p, 1.2, 3), SIDE_AT = 0.92, LEAN = p => clamp(4.7 - 1.1 * p, 1.8, 4), LEAN_AT = [0.2, 0.6], WALK_LEAN = 0.9;
+// the swing's path: the heel kicks up right after toe-off (EARLY_AT of the swing, 2 frames at least: EARLY_FWD of the
+// way to mid-swing, EARLY_LIFT m up at a full stride and a swing of KICK_AIR frames or more, KICK_STROLL of that at a stroll's
+// pace: a person strolling folds the knee less), so the knee folds as the
+// toe leaves; it comes down LAND_BACK of the stride behind and LAND_ABOVE m over the strike LAND_AT of the swing before
+// it. A swing too short for a key leaves it out (the foot would jolt between keys a frame apart), and the closing step
+// sets down without either. The heel takes HEEL_MIN frames at least to rise and rises no higher than PITCH_MAX: past about 60 deg
+// the toes sit behind the ankle and QA reads a bent knee as bending backward.
+const EARLY_AT = 0.18, EARLY_FWD = 0.35, EARLY_LIFT = 0.18, KICK_STROLL = 0.55, KICK_AIR = 10, LAND_AT = 0.22, LAND_BACK = 0.12, LAND_ABOVE = 0.03, PITCH_MAX = 50;
+const fwd = h => apply(ry(h), [0, 0, 1]);
+const leftOf = h => apply(ry(h), [1, 0, 0]);
+const smoothstep = x => { const t = Math.min(1, Math.max(0, x)); return t * t * (3 - 2 * t); };
+
+/** Last keyed value of every channel at or before frame f. */
+export function stateAt(keys, f) {
+	const st = {};
+	for (const k of [...keys].sort((a, b) => a.f - b.f)) if (k.f <= f) Object.assign(st, k.set);
+	return st;
+}
+
+/** gen -> keys; every key carries src (tag + step number) so QA can name the step it came from. */
+export function walk(gen, keys, sk, tag = "walk") {
+	let src = `${tag} start`;
+	const out = [], at = (f, set) => { const key = { f, set, src }; out.push(key); return key; };
+	const st = stateAt(keys, gen.f0);
+	if (!st.foot_l || !st.foot_r || !st.root) throw new Error("MOTION_SPEC_INVALID: walk needs foot_l, foot_r and root keyed before f0");
+	if (gen.vary !== undefined && !(Number.isFinite(gen.vary) && gen.vary >= 0 && gen.vary <= 2)) throw new Error(`MOTION_SPEC_INVALID: ${tag} vary must be a number from 0 (every step the same) to 2, got ${JSON.stringify(gen.vary)}`);
+	const I = sk.index, P = sk.restWorldPos;
+	const ank = P[I.LeftFoot][1], standY = P[I.Hips][1];
+	const footRest = { l: sub(P[I.LeftToeBase], P[I.LeftFoot]), r: sub(P[I.RightToeBase], P[I.RightFoot]) };
+	// QA's heel point from the ankle of a flat foot at yaw 0; a foot pitched `deg` about a point on the ground
+	const heelOff = [0, 0.005 - ank, -0.045];
+	const flatAt = { l: -Infinity, r: -Infinity };
+	// Pelvis heights from the leg length: straight-ish over the stance foot, low enough at
+	// double support that the trailing leg still reaches (2% knee slack).
+	const leg = len(sub(P[I.LeftLeg], P[I.LeftUpLeg])) + len(sub(P[I.LeftFoot], P[I.LeftLeg]));
+	const hipDrop = P[I.Hips][1] - P[I.LeftUpLeg][1], step0 = gen.step ?? 0.5, hw = gen.halfWidth ?? 0.08;
+	const hipsAt = horiz => Math.sqrt(Math.max(0, (0.98 * leg) ** 2 - horiz ** 2)) + ank + hipDrop - standY;
+	const W = { steps: 8, step: step0, period: 20, swing: 14, halfWidth: hw, lift: 0.08, turnDistance: 0.4, firstStep: 0.4,
+		pelvisHigh: Math.min(-0.005, hipsAt(Math.hypot(0.03, hw - 0.035))), pelvisLow: hipsAt(Math.hypot(step0 / 2, hw)), vary: 1, ...gen };
+	const pace = (W.step / W.period) / (0.5 / 20);
+	W.armSwing = gen.armSwing ?? clamp(ARM_SWING * pace, 4, 22);
+	const chestAt = CHEST_AT(pace), pelvisAt = PELVIS_AT(pace), sideSway = SIDE(pace), dipBy = LEAN(pace), walkLean = clamp(WALK_LEAN * pace, 0, 3);
+	const elbow = ELBOW[0] + ELBOW[1] * Math.min(pace, 2.5), elbowSwing = ELBOW_SWING[0] + ELBOW_SWING[1] * Math.min(pace, 2.5);
+	const [h0, h1] = W.heading ?? [st.yaw ?? 0, st.yaw ?? 0];
+	const hs = s => h0 + (h1 - h0) * smoothstep(s / W.turnDistance);
+	const c0 = scale(add(st.foot_l, st.foot_r), 0.5); c0[1] = 0;
+	const path = [c0];
+	for (let i = 0; i < 4000; i++) path.push(add(path[i], scale(fwd(hs(i * 0.01)), 0.01)));
+	const C = s => path[Math.max(0, Math.min(path.length - 1, Math.round(s / 0.01)))];
+	const footAt = (s, k) => { const p = add(C(s), scale(leftOf(hs(s)), (k === "l" ? 1 : -1) * W.halfWidth)); p[1] = ank; return p; };
+	const stance = { l: -0.07, r: 0.07 }, state = { foot_l: st.foot_l, foot_r: st.foot_r, fyaw_l: st.fyaw_l ?? h0, fyaw_r: st.fyaw_r ?? h0 };
+	const holdAll = ["root", "yaw", "roll", "foot_l", "foot_r", "fyaw_l", "fyaw_r", "spine_yaw", "spine_roll", "spine_pitch", "aswing_l", "aswing_r", "abend_l", "abend_r",
+		"wflex_l", "wflex_r", "head_yaw"];
+	const r0 = st.roll ?? 0, sr0 = st.spine_roll ?? 0, sp0 = st.spine_pitch ?? 0;
+	// each foot's spans on the ground (fitPelvis): from a heel strike (or f0) to its lift-off, heel the frame its heel comes up
+	const ground = { l: [{ a: gen.f0, b: Infinity, strike: false }], r: [{ a: gen.f0, b: Infinity, strike: false }] };
+	at(gen.f0, Object.fromEntries(holdAll.map(ch => [ch, st[ch] ?? state[ch] ?? (ch === "yaw" ? h0 : 0)])));
+	let sLast = stance.r, prev = null;
+	const R = walkRhythm(W, { s0: sLast, turn: (a, b) => hs(b) - hs(a),
+		seed: [gen.f0, W.steps, W.step, W.period, W.swing, W.firstStep, h0, h1, c0[0].toFixed(3), c0[2].toFixed(3)].join("|") });
+	for (let i = 0; i < W.steps; i++) {
+		src = `${tag} step ${i + 1}`;
+		const k = i % 2 === 0 ? "l" : "r", other = k === "l" ? "r" : "l", last = i === W.steps - 1;
+		const sNew = last ? sLast : sLast + R.inc[i];
+		const ts = gen.f0 + 16 + R.lift[i], tl = ts + R.air[i], tm = ts + Math.floor(R.air[i] / 2);
+		// gait initiation: move the weight over the stance foot before the first heel comes up
+		if (i === 0) {
+			const pre = add(C(stance[other]), scale(leftOf(h0), (other === "l" ? 1 : -1) * W.halfWidth * 0.75)); pre[1] = st.root[1];
+			at(ts - 4, { root: pre, yaw: h0 });
+			at(ts, { arm_hang: 1 });
+		}
+		// a longer stride pushes off more; the closing step pushes and strikes less
+		const size = clamp(Math.abs(sNew - stance[k]) / STRIDE_REF, 0.3, 1.15), toeOff = TOE_OFF * (0.55 + 0.45 * size) * (last ? 0.8 : 1);
+		// forefoot rocker: the heel comes up HEEL_OFF of a step before lift-off (a little sooner on the first
+		// step, the weight only just over the other foot) and the foot rolls over the ball, slowly
+		// while the other foot is still in the air, then fast to toe-off
+		const ankle = state[`foot_${k}`], yw = state[`fyaw_${k}`], ball = add(ankle, apply(ry(yw), footRest[k]));
+		const tHeel = Math.max(ts - Math.max(HEEL_MIN, Math.round((i === 0 ? 0.35 : HEEL_OFF) * W.period)), flatAt[k] + 1, gen.f0 + 1);
+		Object.assign(ground[k].at(-1), { b: ts, heel: tHeel, ball, yw, flat: ankle });
+		for (let f = tHeel; f <= ts; f++) {
+			const d = toeOff * ((f - tHeel) / Math.max(1, ts - tHeel)) ** 1.8;
+			at(f, { [`foot_${k}`]: pivot(ball, yw, d, ankle), [`fpitch_${k}`]: d, [`fyaw_${k}`]: yw });
+		}
+		// swing: the foot rises behind first (the knee folds right after toe-off), the toes trailing down, level at
+		// mid-swing, and comes down onto the heel from above (the toes up) instead of skimming the floor
+		const lead = Math.max(1, Math.round(LAND_AT * R.air[i]));
+		const mid = footAt((stance[k] + sNew) / 2, k); mid[1] += R.height[i];
+		const off = pivot(ball, yw, Math.min(toeOff, PITCH_MAX), ankle), rise = add(off, scale(sub(mid, off), EARLY_FWD));
+		// a shorter swing kicks lower (the same rise in fewer frames would jolt the foot): by its length against KICK_AIR
+		// and with the step's own lift (gait-rhythm), so no two swings fold the knee alike
+		rise[1] = off[1] + EARLY_LIFT * size * Math.min(1, (R.air[i] / KICK_AIR) ** 2) * (KICK_STROLL + (1 - KICK_STROLL) * brisk(pace)) * (R.height[i] / W.lift);
+		// in a turn the line from the toe-off to mid-swing cuts in toward the other foot: the kick stays out at mid-swing's side
+		const outward = scale(leftOf(hs(stance[other])), k === "l" ? 1 : -1), foot = state[`foot_${other}`];
+		const side = p => (p[0] - foot[0]) * outward[0] + (p[2] - foot[2]) * outward[2], inside = side(mid) - side(rise);
+		if (inside > 0) { rise[0] += outward[0] * inside; rise[2] += outward[2] * inside; }
+		const early = ts + Math.max(2, Math.round(EARLY_AT * R.air[i]));
+		if (!last && early < tm - 1) at(early, { [`foot_${k}`]: rise, [`fpitch_${k}`]: 0.7 * Math.min(toeOff, PITCH_MAX) });
+		at(tm, { [`foot_${k}`]: mid, [`fyaw_${k}`]: hs((stance[k] + sNew) / 2), [`fpitch_${k}`]: 0 });
+		// at the strike the hips are past the middle of the stride (STRIKE_AHEAD: about half way at a stroll, well past it
+		// at a brisk walk, so a slow walk's hips dip between spread legs), over the landing foot's side;
+		// between strikes they cross the floor at an even pace, a little slower over mid-stance (MID_SLOW of the step)
+		const sLand = stance[other] + (STRIKE_AHEAD[0] + (STRIKE_AHEAD[1] - STRIKE_AHEAD[0]) * brisk(pace)) * (sNew - stance[other]);
+		const sEven = prev ? prev.s + (sLand - prev.s) * ((tm - prev.f) / (tl - prev.f)) : null;
+		const sMid = sEven === null ? stance[other] + 0.03 : sEven - MID_SLOW * Math.abs(sNew - stance[k]) / 2, shift = i === 0 ? 0.015 : 0.032;
+		const pm = add(C(sMid), scale(leftOf(hs(sMid)), (other === "l" ? 1 : -1) * shift)); pm[1] = standY + W.pelvisHigh;
+		// a stride longer than the nominal one drops the hips a little more at double support, so the trailing leg still reaches
+		const low = gen.pelvisLow ?? (R.inc[i] > step0 ? Math.min(W.pelvisLow, hipsAt(Math.hypot(R.inc[i] / 2, hw))) : W.pelvisLow);
+		const pl = C(sLand).slice(); pl[1] = standY + (last ? W.pelvisHigh : low);
+		prev = { f: tl, s: sLand };
+		// heel rocker: the toes come up before the strike, then the foot rolls down about the heel to flat
+		const land = footAt(sNew, k), lyaw = hs(sNew), heel = add(land, apply(ry(lyaw), heelOff));
+		const strike = -(STRIKE_DF[0] + (STRIKE_DF[1] - STRIKE_DF[0]) * brisk(pace)) * (last ? 0.5 : 1), nFlat = Math.max(2, Math.round(0.2 * W.period));
+		const touch = pivot(heel, lyaw, strike, land), above = add(touch, scale(fwd(lyaw), -LAND_BACK * Math.abs(sNew - stance[k])));
+		above[1] += LAND_ABOVE;
+		if (!last && lead > 1 && tl - lead > tm + 1) at(tl - lead, { [`foot_${k}`]: above, [`fpitch_${k}`]: 0.6 * strike });
+		for (let j = 0; j <= nFlat; j++) {
+			const d = strike * (1 - smoothstep(j / nFlat));
+			at(tl + j, { [`foot_${k}`]: pivot(heel, lyaw, d, land), [`fpitch_${k}`]: d, [`fyaw_${k}`]: lyaw });
+		}
+		flatAt[k] = tl + nFlat;
+		ground[k].push({ a: tl, b: Infinity, strike: true });
+		state[`foot_${k}`] = land; state[`fyaw_${k}`] = lyaw; stance[k] = sNew;
+		const swing = (last ? 0 : i < 3 ? [0, 0.3, 0.7][i] : 1) * R.arm[i], sg = k === "l" ? 1 : -1;
+		const sp = clamp(size, 0.4, 1.1), ramp = last ? 0 : i === 0 ? 0.5 : 1, list = LIST * sp * ramp * (other === "l" ? 1 : -1);
+		// the upper body leads the legs (module doc): the arms, the turns and the side sway are waves keyed at mid-swing (tm, dm
+		// of a step before the strike) and at the strike, the arms peaking at tm: a wave peaking `peak` steps before the strike,
+		// scaled so the larger of its two keys is 1 (the interpolation does not overshoot its keys); the dip is keyed at its peaks
+		const dm = (tl - tm) / W.period, wave = peak => { const v = [Math.cos(Math.PI * (peak - dm)), Math.cos(Math.PI * peak)]; return v.map(x => x / Math.max(...v.map(Math.abs))); };
+		const pelvis = wave(-pelvisAt).map(v => -PELVIS_TURN * sp * sg * swing * v), chest = wave(chestAt).map(v => CHEST_TURN * sp * sg * swing * v);
+		const sway = wave(SIDE_AT).map(v => -Math.sign(list) * sideSway * sp * ramp * v);
+		const arm = wave(dm).map((v, j) => (j ? ARM_FALL * v : v)), armAt = v => ({ aswing_l: -0.85 * W.armSwing * sg * swing * v,
+			aswing_r: W.armSwing * sg * swing * v, abend_l: swing * (elbow - sg * elbowSwing * v), abend_r: swing * (elbow + sg * elbowSwing * v) });
+		at(tm, { root: pm, yaw: hs(sMid) + pelvis[0], roll: r0 + list, spine_roll: sr0 - list * (1 + SWAY) + sway[0], spine_yaw: chest[0] - pelvis[0],
+			...armAt(arm[0]), wflex_l: WRIST * swing, wflex_r: WRIST * swing });
+		at(tl, { root: pl, yaw: hs(sLand) + pelvis[1], roll: r0, spine_roll: sr0 + sway[1], spine_yaw: chest[1] - pelvis[1], ...armAt(arm[1]), head_yaw: 0 });
+		const lean = sp0 + walkLean * ramp, dip = dipBy * sp * ramp;
+		at(Math.max(gen.f0 + 1, tl - Math.round(LEAN_AT[1] * W.period)), { spine_pitch: lean - 0.6 * dip });
+		at(Math.max(gen.f0 + 1, tl - Math.round(LEAN_AT[0] * W.period)), { spine_pitch: lean + dip });
+		sLast = sNew;
+	}
+	const tend = gen.f0 + 16 + W.steps * W.period + 18;
+	// the hips' height from the legs on the ground, unless the walk gives its own pelvis heights
+	// (only up to the walk's last key: after it the settle just holds, and a take may end there, walkTo)
+	const settle = Math.max(...out.map(k => k.f));
+	// each swing's path (from the planned toe-off), the hips over it, the heel rise they leave the trailing foot, and
+	// each swing again from where that foot now lifts (its approach to the strike, which the hips saw, unchanged)
+	if (gen.pelvisHigh === undefined && gen.pelvisLow === undefined) {
+		fitSwing(out, { end: settle, ground });
+		fitPelvis(sk, out, { f0: gen.f0, end: settle, period: W.period, pace, ground, start: `${tag} start` });
+		fitTrail(sk, out, { end: settle, period: W.period, pace, ground });
+		fitSwing(out, { end: settle, ground, sk });
+	}
+	src = `${tag} end`;
+	at(tend, stateAt(out, tend));
+	return out;
+}
+
+export function expandGenerators(spec, sk) {
+	let keys = (spec.keys ?? []).map((k, i) => (k.src ? k : { ...k, src: `keys[${i}]` }));
+	(spec.generators ?? []).forEach((gen, i) => {
+		if (gen.type !== "walk") throw new Error(`MOTION_SPEC_INVALID: generators[${i}] has unknown type "${gen.type}" (only "walk")`);
+		keys = keys.concat(walk(gen, keys, sk, `generators[${i}] walk`));
+	});
+	return keys;
+}

package/src/motion3/compiler/wrist-clamp.js

@@ -0,0 +1,32 @@
+// The wrist an elbow turn leaves (fix.self, lane selfwrist). fix/self.js turns an elbow about the shoulder-wrist
+// line to take an arm out of the body, and limbs.js swivelElbow keeps the hand's world turn while it does. With
+// the elbow bent (a cigarette at the lips) that line runs well off the forearm, so the turn lands on the wrist
+// as flex and deviation: the car exit's smoking hand went 57 deg toward the thumb (limit 20) on 88 frames, the
+// squat smoke 56, the kits 26-57 (QA WRIST). No turn of the elbow both clears the body and keeps that wrist in
+// range (the car exit at f500: 45 deg leaves the forearm 2.8 cm in the chest at 31 deg, 75 deg clears it at 57).
+// So the wrist stops at its limits and the hand turns on with the elbow for the rest, as a wrist does; a fit
+// (the filter at the lips) then moves the wrist until its point is back on its target (compile.js runs the turn
+// in the fit's passes too). A wrist the turn leaves within its limits is not touched: the hand keeps its world
+// turn exactly as before.
+import { add, sub, scale, norm, mul, T, apply, axisRot } from "./math.js";
+import { rotateSubtree } from "./skeleton.js";
+import { palmAxes } from "./limbs.js";
+import { WRIST_LIMITS, wristNeed } from "./arm-orient.js";
+
+const clampTo = (v, [lo, hi]) => Math.min(hi, Math.max(lo, v));
+
+/**
+ * clampWrist(sk, s, side): the hand of `side` turned back within WRIST_LIMITS on its forearm (twist, flex and
+ * deviation each clamped, the hand alone: the forearm bone keeps its turn). Returns { need, got } in degrees
+ * when it turned the hand, null when the wrist was within its limits.
+ */
+export function clampWrist(sk, s, side) {
+	const I = sk.index, h = I[`${side}Hand`], fa = I[`${side}ForeArm`], rw = sk.restWorldRot;
+	const axT = norm(sub(s.P[h], s.P[fa])), neutral = mul(s.R[fa], mul(T(rw[fa]), rw[h]));
+	const { axF, axD, ...need } = wristNeed(neutral, s.R[h], 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])]));
+	if (Object.keys(need).every(k => Math.abs(need[k] - got[k]) < 1e-6)) return null;
+	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, h, s.P[h].slice(), mul(want, T(s.R[h])));
+	return { need, got };
+}

package/src/motion3/delta.js

@@ -0,0 +1,47 @@
+// C7. What changed against a base spec's QA (lane D2). Groups match by severity.js groupKey
+// (kind + subject with the numbers as "#"); groups that share a key are summed into one entry.
+//   resolved   a key in the base only
+//   new        a key in this compile only
+//   worse      a key in both whose severity rose by DELTA_STEP (5 %) or more of the base severity
+//   better     a key in both whose severity fell by DELTA_STEP or more
+// keys lists at most DELTA_KEYS groupKeys of resolved, new and worse, most severe first; the
+// counts are always complete.
+import { groupKey, severityOf } from "./qa/severity.js";
+
+const DELTA_STEP = 0.05;
+const DELTA_KEYS = 6;
+
+/** groups -> Map(groupKey -> summed severity), in first-seen order. */
+function byKey(groups) {
+	const m = new Map();
+	for (const g of groups ?? []) {
+		const k = groupKey(g);
+		m.set(k, (m.get(k) ?? 0) + (Number.isFinite(g.severity) ? g.severity : severityOf(g)));
+	}
+	return m;
+}
+
+/** The first DELTA_KEYS keys of [key, weight] rows, the heaviest first (ties keep their order). */
+const top = rows => rows.map((r, i) => [...r, i]).sort((a, b) => b[1] - a[1] || a[2] - b[2]).slice(0, DELTA_KEYS).map(r => r[0]);
+
+/**
+ * deltaOf(baseGroups, groups, baseId) ->
+ *   { base, resolved, new, worse, better, keys: { resolved: [], new: [], worse: [] } }
+ * @param {object[]} baseGroups  the base spec's full qa.groups (spec store parts)
+ * @param {object[]} groups  this compile's qa.groups
+ * @param {string} baseId
+ */
+export function deltaOf(baseGroups, groups, baseId) {
+	const before = byKey(baseGroups), after = byKey(groups);
+	const resolved = [], added = [], worse = [];
+	let better = 0;
+	for (const [k, s] of before) if (!after.has(k)) resolved.push([k, s]);
+	for (const [k, s] of after) {
+		if (!before.has(k)) { added.push([k, s]); continue; }
+		const b = before.get(k), step = DELTA_STEP * Math.max(Math.abs(b), 0.01);
+		if (s - b >= step - 1e-9) worse.push([k, s - b]);
+		else if (b - s >= step - 1e-9) better += 1;
+	}
+	return { base: baseId, resolved: resolved.length, new: added.length, worse: worse.length, better,
+		keys: { resolved: top(resolved), new: top(added), worse: top(worse) } };
+}