@rig-c/pose 0.27.0 → 0.29.0

package/README.md

@@ -107,7 +107,7 @@ A retarget of the cleaned dancer, with `--flip 90 --short 0.35 --bends clamp --l
 rig-pose retarget --rig out/rig --map map.json --pose dance.pose.json --out motion.json --name dance
 ```
 
-For every frame of the pose and every bone the map names, the segment that bone carries (an upper arm: shoulder → elbow) points somewhere in the picture. The bone is turned so its segment points the same way: the picture angle, flipped into rig-c's y-up world, minus the bone's angle at the rig's setup pose (read through rig-c's own poser), less the turn of the mapped bone above it — because a `rotate` key in rig-c adds to the setup rotation and a child turns with its parent. The travel of the pelvis midpoint, scaled by a length measured on both the rig and the pose, moves the hip. When a head chain carries the eye line (`r_eye → l_eye`), the eyes' vertical travel against `neck` in the reference, scaled into the rig's units, keys a vertical `translate` nod channel on the head bone ([#111](https://github.com/rig-c/pose/issues/111)), leaving its `rotate` (roll) track unchanged. The result is one animation in rig-c's motion format (`rigc-motion/1`): a `rotate` track per mapped bone, a `translate` track on the hip (and on the head when the reference nods), one key per pose frame — and, when the map lists alternate drawings, an `attachment` track per slot they switch (and a `translate` track per bone a set offsets).
+For every frame of the pose and every bone the map names, the segment that bone carries (an upper arm: shoulder → elbow) points somewhere in the picture. The bone is turned so its segment points the same way: the picture angle, flipped into rig-c's y-up world, minus the bone's angle at the rig's setup pose (read through rig-c's own poser), less the turn of the mapped bone above it — because a `rotate` key in rig-c adds to the setup rotation and a child turns with its parent. The travel of the pelvis midpoint, scaled by a length measured on both the rig and the pose, moves the hip. When a head chain carries the eye line (`r_eye → l_eye`), the eyes' vertical travel against `neck` in the reference, scaled into the rig's units, keys a vertical `translate` nod channel on the head bone ([#111](https://github.com/rig-c/pose/issues/111)) clamped within `±2%` of the setup neck length (`head − neck`, [#181](https://github.com/rig-c/pose/issues/181)), while any vertical residual removed by that clamp (`rawNod − dy`) is coupled in phase into `face.pitch`'s dial (`+2.8°/unit`, mapped through `face.pitch.range`) and the head bone's `rotate` track (`+1.6°/unit`, [#190](https://github.com/rig-c/pose/issues/190); gains calibrated against the hand-polished reference `p1`), adding `0°` on frames where the clamp does not act. The result is one animation in rig-c's motion format (`rigc-motion/1`): a `rotate` track per mapped bone, a `translate` track on the hip (and on the head when the reference nods), one key per pose frame — and, when the map lists alternate drawings, an `attachment` track per slot they switch (and a `translate` track per bone a set offsets).
 
 Nothing is written until every check passes:
 
@@ -315,7 +315,7 @@ Which bones carry which joints. You write it for your rig:
   ⚠️ **Seen from the front, an elbow's side is not a joint limit.** An elbow flexes toward the camera, and its picture falls on either side of the upper arm depending on how the arm is turned. On a real 13 s front-facing dance (313 frames, RTMPose), the right elbow sat on the "wrong" side of the rig's rest on 165 frames (median 23°), and the left on 200 (median 29°, up to 179° with the hands behind the head). Every one was a real elbow bend. The knees strayed at most 8.8° and 14.7°, which is pose noise around a straight leg. So for front-facing material, arms go `"free"`. Legs on `"rest"` with `--bends clamp` hold only while the knees stay near straight. On a second dance with knee bends (Toca Toca, rig-c/pose#27), that setting straightened the left knee for most of the dance: `leg_l1` was 48.3° off at p90, against 0.0–0.3° with free legs. Leave legs `"free"` unless the dance keeps its knees straight.
 - `mid_hip` and `mid_shoulder` are the midpoints of the two hips and the two shoulders.
 - `translate.scale` is one length measured on both: two points on the rig, two points in the pose (its median over the frames where both are good). Pick a long segment that does not foreshorten much.
-- `face` (optional, [#138](https://github.com/rig-c/pose/issues/138), [#164](https://github.com/rig-c/pose/issues/164), [#173](https://github.com/rig-c/pose/issues/173), [#189](https://github.com/rig-c/pose/issues/189)): `{ "yaw"?: { "bone": "yaw", "range": [-15, 15], "sets"?: [{ "set": "T1", "above": 45 }] }, "pitch"?: { "bone": "pitch", "range": [-10, 15] }, "sets"?: [{ "set": "T1", "above": 45 }] }` (`min ≤ 0 ≤ max`, `min < max`). Reads per-frame yaw and pitch from `nose` against `r_eye + l_eye` (and `r_ear + l_ear` when present — where the eye span is foreshortened below `0.85 × median(de)` and the ear-chord offset `xea = (mid_ears − mid_eyes) · u / da` exceeds both `1.8 × |xne|` and `0.15`, yaw blends toward the ear chord `atan(2 × xea)` with weight `w = clamp((0.85 × median(de) − de) / ((0.85 − 0.80) × median(de)), 0, 1)` so a side gaze whose 2D nose sits near the eye midpoint reaches `atan(2 × xea)` below `0.80 × median(de)` and exits without a step), maps 1:1 inside `0.8 × range` (`[-12, 12]°` on `[-15, 15]°`) and compresses only the overshoot above the knee into the remaining 20% of the range so a single outlier frame does not crush the rest of the clip, and keys the named dial bone's `rotate` track (`FACE`). When `sets` (`[{ "set": "<name>", "above": <deg> }]`, `0 < above ≤ 90`) is declared on `face.yaw.sets` or `face.sets`, each set enters on frames where `|yaw| ≥ above` (or the highest `above` satisfied when multiple sets are declared) and leaves only when `|yaw| < above − 10°` (`10°` hysteresis), emitting stepped slot `attachment` keys for the set's `slots` and `hides` (resolved from `alternates` in the map or `sets.json` (`rig-parts-sets/1`) beside `rig.json`; an unknown set is refused by name as `MAP_SET_EXISTS`).
+- `face` (optional, [#138](https://github.com/rig-c/pose/issues/138), [#164](https://github.com/rig-c/pose/issues/164), [#173](https://github.com/rig-c/pose/issues/173), [#189](https://github.com/rig-c/pose/issues/189), [#190](https://github.com/rig-c/pose/issues/190)): `{ "yaw"?: { "bone": "yaw", "range": [-15, 15], "sets"?: [{ "set": "T1", "above": 45 }] }, "pitch"?: { "bone": "pitch", "range": [-10, 15] }, "sets"?: [{ "set": "T1", "above": 45 }] }` (`min ≤ 0 ≤ max`, `min < max`). Reads per-frame yaw and pitch from `nose` against `r_eye + l_eye` (and `r_ear + l_ear` when present — where the eye span is foreshortened below `0.85 × median(de)` and the ear-chord offset `xea = (mid_ears − mid_eyes) · u / da` exceeds both `1.8 × |xne|` and `0.15`, yaw blends toward the ear chord `atan(2 × xea)` with weight `w = clamp((0.85 × median(de) − de) / ((0.85 − 0.80) × median(de)), 0, 1)` so a side gaze whose 2D nose sits near the eye midpoint reaches `atan(2 × xea)` below `0.80 × median(de)` and exits without a step), couples any vertical residual removed by the head nod channel's `±2%` neck-length clamp (`+2.8°/unit`, `0°` where un-clamped) into `pitch` in phase ([#190](https://github.com/rig-c/pose/issues/190)), maps 1:1 inside `0.8 × range` (`[-12, 12]°` on `[-15, 15]°`) and compresses only the overshoot above the knee into the remaining 20% of the range so a single outlier frame does not crush the rest of the clip, and keys the named dial bone's `rotate` track (`FACE`). When `sets` (`[{ "set": "<name>", "above": <deg> }]`, `0 < above ≤ 90`) is declared on `face.yaw.sets` or `face.sets`, each set enters on frames where `|yaw| ≥ above` (or the highest `above` satisfied when multiple sets are declared) and leaves only when `|yaw| < above − 10°` (`10°` hysteresis), emitting stepped slot `attachment` keys for the set's `slots` and `hides` (resolved from `alternates` in the map or `sets.json` (`rig-parts-sets/1`) beside `rig.json`; an unknown set is refused by name as `MAP_SET_EXISTS`).
 - `body` (optional, [#173](https://github.com/rig-c/pose/issues/173)): `{ "yaw"?: { "bone": "body_yaw", "range": [-30, 30], "sets"?: [{ "set": "T8", "above": 45 }] }, "sets"?: [{ "set": "T8", "above": 45 }] }` (`min ≤ 0 ≤ max`, `min < max`). Maps the per-frame body yaw read from the camera-normalised shoulder and hip width (`BODY`) into `range` with the same `0.8 × range` knee mapping as `face`, keying the named dial bone's `rotate` track, and switches any declared `sets` (`body.sets` or `body.yaw.sets`) with the same `above` / `above − 10°` hysteresis (overriding `face` sets and arm `alternates` on slots they share while active). Without `body` in the map, `BODY` and `--report`'s `body` still report the reading while leaving every track in `motion.json` unchanged.
 
 ### A joint's range: `range`
@@ -349,12 +349,13 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 
 - `slots`: what each slot of the set shows while it shows; each attachment must be in that slot under some skin of the rig, as rig-c built it. `hides`: the slots that are empty while it shows. A slot's place in the draw order is the rig's own, so a drawing that must sit in front of the torso is an attachment in a slot that is: a switch is attachment keys only, and no draw-order key is written.
 - `chains`: the map's chains whose pose the set depicts; it is selected by them. `pose`: the key skeleton the art was painted from, body-18 (or `mid_hip`/`mid_shoulder`) in picture px, y down, any scale and place — only its directions are read; every joint the listed chains use must be in it.
-- `drawn` (optional): each bone's world angle (Spine degrees) as painted. It changes no key unless the set declares `symmetric` or `support` ([below](#alternate-drawings-alternates)): otherwise, while a set shows, a bone is keyed to the pose as always, and the art turns with it. What it gives is a figure: the art turn, how far each bone is from the angle its art was painted at (`artTurn`, and `ART-RANGE` past the bone's range).
+- `drawn` (optional): each bone's world angle (Spine degrees) as painted. It changes no key unless the set declares `symmetric`, `support` or `anchor` ([below](#alternate-drawings-alternates)): otherwise, while a set shows, a bone is keyed to the pose as always, and the art turns with it. What it gives is a figure: the art turn, how far each bone is from the angle its art was painted at (`artTurn`, and `ART-RANGE` past the bone's range).
 - `offsets` (optional): a translate per bone, in its parent's axes, held while the set shows and 0 elsewhere (stepped keys), so the joints as painted are the pivots. A bone `translate` already keys (the hip) cannot take one.
 - `place` (optional): `"by-hip"` places a hand that meets the body by its offset from the hip ([below](#alternate-drawings-alternates)).
 - `symmetric` (optional, [#188](https://github.com/rig-c/pose/issues/188)): `true` normalises a two-arm symmetric gesture set (such as hands behind the head) to its `drawn` symmetry centre so both elbows sit at the same world height and neither wrist extends past the head silhouette ([below](#alternate-drawings-alternates)). Requires two 2-bone chains with `drawn` angles on all four bones (`MAP_ALT_SYMMETRIC`).
 - `support` (optional, [#188](https://github.com/rig-c/pose/issues/188)): a chain name or non-empty list of chain names of the set (`"support": "arm_l"` or `["arm_l"]`) whose bones carry a stationary support arm (such as a waist-resting hand while the other arm gestures); while the set shows, each support chain's bones anchor to `drawn` within `±2.5°` (`≤ ±3°`) of the pose's delta relative to the set's reference pose, and an unplaced active raised arm in the same set clears the head/bun outward along the 2D shoulder→wrist direction (`MAP_ALT_SUPPORT`).
-- Each name resolves against the built rig and the map, and a miss is refused by name, listing what exists: `MAP_ALT_SLOT`, `MAP_ALT_ATTACHMENT`, `MAP_ALT_HIDES`, `MAP_ALT_CHAIN`, `MAP_ALT_JOINT`, `MAP_ALT_POSE`, `MAP_ALT_DRAWN`, `MAP_ALT_OFFSET` (a bone that is not a bone of the set's chains), `MAP_ALT_PLACE`, `MAP_ALT_SYMMETRIC` and `MAP_ALT_SUPPORT`.
+- `anchor` (optional, [#191](https://github.com/rig-c/pose/issues/191)): a chain name or non-empty list of chain names of the set (`"anchor": "arm_l"` or `["arm_l"]`) whose hand is anchored to the set's drawn hand-tip-to-head offset in the `head` bone's local frame (`MAP_ALT_ANCHOR`, `ANCHOR_HEAD`); while the set's slots for that chain show, the target hand tip is `head_posed_origin + rotate(W_drawn − H_setup, head_posed_rot − head_drawn_rot)` and the 2-bone arm is solved by two-circle intersection (`twoBone` / `reachLimit`) inside the set's `turn`, listing any frame where `turn` saturates and leaves a residual hand-tip shortfall (`saturated: [{ frame, residual }]` on `raised`, printed as `; residual f46 9.68u, …` on `RAISED`).
+- Each name resolves against the built rig and the map, and a miss is refused by name, listing what exists: `MAP_ALT_SLOT`, `MAP_ALT_ATTACHMENT`, `MAP_ALT_HIDES`, `MAP_ALT_CHAIN`, `MAP_ALT_JOINT`, `MAP_ALT_POSE`, `MAP_ALT_DRAWN`, `MAP_ALT_OFFSET` (a bone that is not a bone of the set's chains), `MAP_ALT_PLACE`, `MAP_ALT_SYMMETRIC`, `MAP_ALT_SUPPORT` and `MAP_ALT_ANCHOR`.
 
 **When one shows.** Per frame and per set, the distance is the largest difference, in degrees, between a segment of its chains as the retarget asked for it (after holds, the short hold, the flip guard and the hinge check; before any range clamp) and the same segment in its key skeleton, with a foreshortened segment (`SHORT`) weighted at `0.5 ×` (`SHORT_SWITCH_WEIGHT`, [#180](https://github.com/rig-c/pose/issues/180)). On each frame the nearest set within `--switch-tolerance` (default 25°) shows, ties going to the map's order; once entered, a set stays active until its distance exceeds `--switch-tolerance + 15°` (`SWITCH_LEAVE_HYSTERESIS`, [#180](https://github.com/rig-c/pose/issues/180)) for at least `--switch-min` (default 0.25 s) or a competing set with a lower distance enters within `--switch-tolerance`; a run of one set shorter than `--switch-min` is dropped and the base art shows there. Sets compete only with those they share a slot (shown or hidden) or an offset bone with, so a drawing of each arm can show at once; two that compete never overlap.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/face.ts

@@ -293,18 +293,35 @@ export function readFace(
   lEye: readonly Pt[],
   rEar: readonly Pt[] | null,
   lEar: readonly Pt[] | null,
+  nodResidual?: readonly number[] | null,
+  pitchGain = 0,
 ): FaceReading {
   const { ears, yaw, pitch } = readFaceAngles(nose, rEye, lEye, rEar, lEar);
+  const coupledPitch =
+    nodResidual !== undefined && nodResidual !== null && nodResidual.length === pitch.length && pitchGain !== 0
+      ? pitch.map((p, i) => (nodResidual[i]! === 0 ? p : p + pitchGain * nodResidual[i]!))
+      : pitch;
+  const basePitch = face.pitch === undefined ? undefined : mapFaceAxis(pitch, face.pitch);
+  const mappedPitch =
+    face.pitch === undefined
+      ? undefined
+      : coupledPitch === pitch
+        ? basePitch!
+        : (() => {
+            const m = mapFaceAxis(coupledPitch, face.pitch);
+            const keys = m.keys.map((v, i) => (nodResidual![i]! === 0 ? basePitch!.keys[i]! : v));
+            return { ...m, mapped: spanOf(keys), corr: corrOf(m.raw, keys), keys };
+          })();
   return {
     ears,
     read: {
       yaw: spanOf(yaw),
-      pitch: spanOf(pitch),
+      pitch: spanOf(coupledPitch),
       rawYaw: yaw,
-      rawPitch: pitch,
+      rawPitch: coupledPitch,
     },
     ...(face.yaw === undefined ? {} : { yaw: mapFaceAxis(yaw, face.yaw) }),
-    ...(face.pitch === undefined ? {} : { pitch: mapFaceAxis(pitch, face.pitch) }),
+    ...(mappedPitch === undefined ? {} : { pitch: mappedPitch }),
   };
 }
 

package/src/map.ts

@@ -104,6 +104,8 @@ export interface AlternateSet {
   symmetric?: boolean;
   /** `support` (rig-c/pose#188): the set's chains whose bones anchor to the set's `drawn` local angles while the non-support chains track the active gesture. */
   support?: string[];
+  /** `anchor` (rig-c/pose#191): the set's two-bone arm chains whose hand-tip is anchored to the set's `drawn` head-local offset while the set shows. */
+  anchor?: string[];
 }
 export interface YawSet {
   set: string;
@@ -439,7 +441,7 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
       p.add('MAP_ALT_SHAPE', `${aw} is ${typeName(a)}; a set is ${SET_SHAPE}`);
       return;
     }
-    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place', 'symmetric', 'support']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place', 'symmetric', 'support', 'anchor']);
     const name = typeof a.name === 'string' && a.name !== '' ? a.name : null;
     if (name === null) p.add('MAP_ALT_NAME', `${aw} "name" is ${typeName(a.name)}; it must be a non-empty string`);
     else if (names.has(name)) p.add('MAP_ALT_NAME', `${aw} "name" "${name}" names two sets`);
@@ -602,7 +604,48 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         if (ok) support = sup;
       }
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }), ...(symmetric === undefined ? {} : { symmetric }), ...(support === undefined ? {} : { support }) });
+    let anchor: string[] | undefined;
+    if ('anchor' in a) {
+      const anc = typeof a.anchor === 'string' && a.anchor !== '' ? [a.anchor] : strings(a.anchor);
+      if (anc === null || anc.length === 0 || anc.some((s) => s === '')) {
+        p.add('MAP_ALT_ANCHOR', `${label} "anchor" is ${JSON.stringify(a.anchor)}; it must name one or more of the set's chains (${(cs ?? []).join(', ') || 'none'})`);
+        ok = false;
+      } else {
+        if (new Set(anc).size !== anc.length) {
+          p.add('MAP_ALT_ANCHOR', `${label} "anchor" names a chain twice: ${anc.join(', ')}`);
+          ok = false;
+        }
+        const outside = anc.filter((c) => !(cs ?? []).includes(c));
+        if (outside.length > 0) {
+          p.add('MAP_ALT_ANCHOR', `${label} "anchor" names chain ${outside.map((c) => `"${c}"`).join(', ')}, which is not in the set's chains (${(cs ?? []).join(', ') || 'none'})`);
+          ok = false;
+        }
+        const ancChains = own.filter((c) => anc.includes(c.name));
+        const nonTwo = ancChains.filter((c) => c.bones.length !== 2);
+        if (nonTwo.length > 0) {
+          p.add('MAP_ALT_ANCHOR', `${label} "anchor" chain ${nonTwo.map((c) => `"${c.name}" (${c.bones.length} bone(s))`).join(', ')} is not a two-bone chain; a head-anchored chain solves a two-bone arm`);
+          ok = false;
+        }
+        if (a.symmetric === true) {
+          p.add('MAP_ALT_ANCHOR', `${label} names both "symmetric" and "anchor"; a set either normalises both arms symmetrically or anchors an arm to the head`);
+          ok = false;
+        }
+        const supRaw = typeof a.support === 'string' ? [a.support] : strings(a.support) ?? [];
+        const bothSup = anc.filter((c) => supRaw.includes(c));
+        if (bothSup.length > 0) {
+          p.add('MAP_ALT_ANCHOR', `${label} names chain ${bothSup.map((c) => `"${c}"`).join(', ')} in both "support" and "anchor"; a chain is anchored one way`);
+          ok = false;
+        }
+        const ancBones = ancChains.flatMap((c) => c.bones);
+        const missing = ancBones.filter((b) => !(b in drawn));
+        if (missing.length > 0) {
+          p.add('MAP_ALT_ANCHOR', `${label} "anchor" chain has no "drawn" angle for ${missing.map((b) => `"${b}"`).join(', ')}; a head-anchored chain derives its head-local offset from its drawn angles`);
+          ok = false;
+        }
+        if (ok) anchor = anc;
+      }
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }), ...(symmetric === undefined ? {} : { symmetric }), ...(support === undefined ? {} : { support }), ...(anchor === undefined ? {} : { anchor }) });
   });
   return out;
 }

package/src/retarget.ts

@@ -98,6 +98,38 @@ const DEG = 180 / Math.PI;
  */
 export const HELD_MISS = 0.01;
 
+/**
+ * Beat-nod phase-coupling gain (`°/unit`) from the vertical residual that the
+ * `±2%` neck-length clamp removes from `head.translate.y` (`rawNod - dy`) onto
+ * `map.face.pitch` (`pitch_dial.rotate`, `rig-c/pose#190`). Measured on the
+ * dancer reference hand pass (`hand/p1` HP2: `+2.8°/unit`).
+ */
+export const NOD_RESIDUAL_PITCH_GAIN = 2.8;
+
+/**
+ * Beat-nod phase-coupling gain (`°/unit`) from the vertical residual that the
+ * `±2%` neck-length clamp removes from `head.translate.y` (`rawNod - dy`) onto
+ * the head chain bone's `rotate` track (`head.rotate`, `rig-c/pose#190`).
+ * Measured on the dancer reference hand pass (`hand/p1` HP2: `+1.6°/unit`).
+ */
+export const NOD_RESIDUAL_HEAD_GAIN = 1.6;
+
+/**
+ * Reference frame for sets declaring `anchor` (`rig-c/pose#191`): `'head-local'`
+ * rotates the set's drawn hand-tip-to-head offset by the head bone's posed world
+ * turn on each frame; `'world-fixed'` holds the unrotated setup world offset;
+ * `'off'` disables head-anchored end-effector solving.
+ */
+export const HEAD_ANCHOR_FRAME: 'head-local' | 'world-fixed' | 'off' = 'head-local';
+
+export interface HeadNodReading {
+  bone: string;
+  maxNod: number;
+  rawY: number[];
+  clampedY: number[];
+  residual: number[];
+}
+
 export interface RetargetOptions extends SwitchOptions {
   /** A joint with a score below this is not good on that frame (a joint with no score is). */
   minScore: number;
@@ -334,6 +366,8 @@ export interface Retarget {
   body: BodyReading | null;
   /** Continuous per-frame figure scale relative to frame 0 (`#163`, `#161`). */
   figureScale: FigureScaleReading;
+  /** Per-frame vertical head nod reading (`rawY`, `clampedY`, and clamped `residual`, `#111`, `#181`, `#190`). */
+  headNod: HeadNodReading | null;
 }
 
 export interface FigureScaleFrame {
@@ -455,6 +489,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // `place: "by-hip"` (#93) measures against the hip in hip widths: the map must name the rig's two hip points.
   const hips = map.alternates.some((a) => a.place !== undefined && a.place !== null) ? hipOf(map) : null;
   if (hips !== null && 'problem' in hips) p.add('PLACE_HIP', hips.problem);
+  const headAnchorBone = map.alternates.some((a) => a.anchor !== undefined) ? headBoneOf(map) : null;
+  if (map.alternates.some((a) => a.anchor !== undefined) && headAnchorBone === null) {
+    p.add('ANCHOR_HEAD', '"anchor" anchors a set\'s hand to the head bone\'s local frame, and no chain of the map carries the eye line (joints r_eye → l_eye)');
+  }
 
   // Every point the map reads, held where it is not good.
   const needed = new Set<string>();
@@ -1080,6 +1118,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   let headNodBone: string | null = null;
   let headNod: Pt[] | null = null;
   let headNodTrack: MotionTrack | null = null;
+  let headNodReading: HeadNodReading | null = null;
   const posedOrigin = (b: string, i: number): Pt => {
     const own = rest.get(b)!;
     if (t !== null && b === t.bone) return [own.worldX + (travel[i]?.[0] ?? 0), own.worldY + (travel[i]?.[1] ?? 0)];
@@ -1271,6 +1310,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           }
           return Math.max(-maxNod, Math.min(maxNod, v));
         });
+        const residual = rawNod.map((v, i) => v - dy[i]!);
+        headNodReading = { bone: hb, maxNod, rawY: rawNod, clampedY: dy, residual };
         if (dy.some((v) => Math.abs(r3(v)) > 0)) {
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
@@ -1324,11 +1365,147 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const raised: Raised[] = [];
   const byHip: ByHip[] = [];
   const raisedArt: Array<{ sw: Switch; entries: ArtRange[] }> = [];
-  const raisedJobs: Array<{ anchor: Anchor; sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; l0: number; l1: number; farthest: number }> = [];
+  const raisedJobs: Array<{ anchor: Anchor; sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; saturated?: Array<{ frame: number; residual: number }>; l0: number; l1: number; farthest: number }> = [];
   const headOk: Anchor | null = head !== null && !('problem' in head) ? { kind: 'head', joints: head.joints, points: head.points } : null;
   const hipsOk: Anchor | null = hips !== null && !('problem' in hips) ? { kind: 'hip', joints: hips.joints, points: hips.points } : null;
   const fallbackHead = headOf(map);
   const gestureHead: Anchor | null = headOk ?? (!('problem' in fallbackHead) ? { kind: 'head', joints: fallbackHead.joints, points: fallbackHead.points } : null);
+  /**
+   * #191: Posed origin and final world rotation (degrees, including #190's nod-residual coupling
+   * and `headNodTrack` translation) of the head bone `hb` on frame `i`.
+   */
+  const finalHeadPose = (hb: string, i: number): { origin: Pt; rotDeg: number } => {
+    let origin = posedOrigin(hb, i);
+    if (headNodTrack !== null && headNodTrack.bone === hb) {
+      const k = headNodTrack.keys.find((x) => Math.abs(x.t - keyTimes[i]!) < 1e-5);
+      if (k !== undefined && Array.isArray(k.v)) {
+        const pName = rest.get(hb)?.parent ?? null;
+        const pRest = pName !== null ? rest.get(pName) : undefined;
+        if (pName !== null && pRest !== undefined) {
+          const pTurn = turnAbove(pName, i);
+          const rad = pTurn / DEG;
+          const c = Math.cos(rad);
+          const s = Math.sin(rad);
+          const pa = c * pRest.a - s * pRest.c;
+          const pb = c * pRest.b - s * pRest.d;
+          const pc = s * pRest.a + c * pRest.c;
+          const pd = s * pRest.b + c * pRest.d;
+          const [lx, ly] = k.v;
+          origin = [origin[0] + pa * lx + pb * ly, origin[1] + pc * lx + pd * ly];
+        }
+      }
+    }
+    let rotDeg = targets.get(hb)?.[i] ?? restOf.get(hb) ?? 0;
+    if (headNodReading !== null && headNodReading.bone === hb) {
+      const res = headNodReading.residual[i] ?? 0;
+      if (res !== 0) {
+        const above = mappedAbove(hb);
+        const hc = map.chains.find((c) => c.bones.includes(hb));
+        const limits = hc?.range[hb];
+        const cov = hc !== undefined ? covered.get(hc.name) : undefined;
+        let next = wrap(rotDeg + NOD_RESIDUAL_HEAD_GAIN * res);
+        if (limits !== undefined && cov?.[i] !== true) {
+          const key = wrap((next - restOf.get(hb)!) - (above === null ? 0 : turn(above, i)));
+          if (overflow(key, limits) > RANGE_SLACK) {
+            next = wrap(next + Math.min(Math.max(key, limits[0]), limits[1]) - key);
+          }
+        }
+        rotDeg = next;
+      }
+    }
+    return { origin, rotDeg };
+  };
+  /**
+   * #191: For a chain listed in `set.anchor`, compute the target hand-tip position from the set's
+   * `drawn` hand-tip-to-head offset in the `head` bone's local frame (or fixed world offset when
+   * `HEAD_ANCHOR_FRAME === 'world-fixed'`), and solve the two-bone arm inside `set.turn`.
+   */
+  const solveHeadAnchorFrame = (
+    set: (typeof map.alternates)[number],
+    c: Chain,
+    i: number,
+  ): {
+    a0: number;
+    a1: number;
+    targetTip: Pt;
+    placedTip: Pt;
+    achievedTip: Pt;
+    residual: number;
+    saturated: boolean;
+    upperHeld: boolean;
+  } | null => {
+    if (HEAD_ANCHOR_FRAME === 'off' || headAnchorBone === null || c.bones.length < 2) return null;
+    const [b0, b1] = c.bones as [string, string];
+    const drawn0 = set.drawn[b0];
+    const drawn1 = set.drawn[b1];
+    if (drawn0 === undefined || drawn1 === undefined) return null;
+    const S0 = rigPoint(rest, b0);
+    const E0 = rigPoint(rest, b1);
+    const wSpec = c.aim[1] === 'x' ? `${b1}:tip` : c.aim[1]!;
+    const W0 = rigPoint(rest, wSpec);
+    const H0 = rigPoint(rest, headAnchorBone);
+    const headRestRot = restOf.get(headAnchorBone);
+    if (S0 === null || E0 === null || W0 === null || H0 === null || headRestRot === undefined) return null;
+    const l0 = Math.hypot(E0[0] - S0[0], E0[1] - S0[1]);
+    const l1 = Math.hypot(W0[0] - E0[0], W0[1] - E0[1]);
+    const d0 = wrap(Math.atan2(E0[1] - S0[1], E0[0] - S0[0]) * DEG - restOf.get(b0)!);
+    const d1 = wrap(Math.atan2(W0[1] - E0[1], W0[0] - E0[0]) * DEG - restOf.get(b1)!);
+    const r0Drawn = (drawn0 + d0) / DEG;
+    const r1Drawn = (drawn1 + d1) / DEG;
+    const WDrawn: Pt = [
+      S0[0] + l0 * Math.cos(r0Drawn) + l1 * Math.cos(r1Drawn),
+      S0[1] + l0 * Math.sin(r0Drawn) + l1 * Math.sin(r1Drawn),
+    ];
+    const dWorld0: Pt = [WDrawn[0] - H0[0], WDrawn[1] - H0[1]];
+    const drawnHeadRot = set.drawn[headAnchorBone] ?? headRestRot;
+    const { origin: H, rotDeg: headRot } = finalHeadPose(headAnchorBone, i);
+    const dRotRad = HEAD_ANCHOR_FRAME === 'world-fixed' ? 0 : wrap(headRot - drawnHeadRot) / DEG;
+    const cosH = Math.cos(dRotRad);
+    const sinH = Math.sin(dRotRad);
+    const targetTip: Pt = [
+      H[0] + dWorld0[0] * cosH - dWorld0[1] * sinH,
+      H[1] + dWorld0[0] * sinH + dWorld0[1] * cosH,
+    ];
+    const shoulder = posedOrigin(b0, i);
+    const place = reachLimit(H, targetTip, shoulder, l0, l1);
+    const P = place.point;
+    const side: 1 | -1 = wrap(drawn1 + d1 - (drawn0 + d0)) >= 0 ? 1 : -1;
+    const sol = twoBone(shoulder, P, l0, l1, side);
+    const turn0 = set.turn[b0];
+    const turn1 = set.turn[b1];
+    let a0 = sol.upper !== null ? wrap(sol.upper - d0) : drawn0;
+    let a1 = sol.upper !== null ? wrap(sol.fore - d1) : drawn1;
+    let upperHeld = false;
+    let foreHeld = false;
+    if (turn0 !== undefined) {
+      const tt0 = wrap(a0 - drawn0);
+      const cl0 = Math.min(Math.max(tt0, turn0[0]), turn0[1]);
+      if (Math.abs(cl0 - tt0) > RANGE_SLACK) {
+        upperHeld = true;
+        a0 = wrap(drawn0 + cl0);
+        const r0 = (a0 + d0) / DEG;
+        const E: Pt = [shoulder[0] + l0 * Math.cos(r0), shoulder[1] + l0 * Math.sin(r0)];
+        a1 = wrap(Math.atan2(P[1] - E[1], P[0] - E[0]) * DEG - d1);
+      }
+    }
+    if (turn1 !== undefined) {
+      const tt1 = wrap(a1 - drawn1);
+      const cl1 = Math.min(Math.max(tt1, turn1[0]), turn1[1]);
+      if (Math.abs(cl1 - tt1) > RANGE_SLACK) {
+        foreHeld = true;
+        a1 = wrap(drawn1 + cl1);
+      }
+    }
+    const r0 = (a0 + d0) / DEG;
+    const r1 = (a1 + d1) / DEG;
+    const achievedTip: Pt = [
+      shoulder[0] + l0 * Math.cos(r0) + l1 * Math.cos(r1),
+      shoulder[1] + l0 * Math.sin(r0) + l1 * Math.sin(r1),
+    ];
+    const residual = Math.hypot(achievedTip[0] - targetTip[0], achievedTip[1] - targetTip[1]);
+    const saturated = (place.how !== 'in' || upperHeld || foreHeld) && residual > 1e-3;
+    return { a0, a1, targetTip, placedTip: P, achievedTip, residual, saturated, upperHeld };
+  };
   /**
    * #188: For an active raised chain in a set that declares a `support` arm, compute the
    * outward-cleared world angles `[a0, a1]` on frame `i` from the scan's 2D shoulder→wrist
@@ -1566,6 +1743,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     };
     const isChainHeadPlaced = (set: (typeof map.alternates)[number], c: Chain, drawn: number | undefined): boolean => {
       if (headOk === null) return false;
+      if (set.anchor?.includes(c.name) === true) return true;
       const wJoint = c.joints[c.joints.length - 1];
       const ea = set.pose[headOk.joints[0]];
       const eb = set.pose[headOk.joints[1]];
@@ -1707,6 +1885,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const upperAsked: number[] = [];
         const upperOver: number[] = [];
         const heldMiss: number[] = [];
+        const isHeadAnchored = HEAD_ANCHOR_FRAME !== 'off' && set.anchor?.includes(c.name) === true;
+        if (isHeadAnchored) job.saturated = [];
         for (const i of span) {
           const h = pairOn(anchor, i);
           const rc = refCentre(i);
@@ -1716,6 +1896,25 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           job.reference.push(ref);
           job.before.push([(w[0] - h.centre[0]) / rigEye, (w[1] - h.centre[1]) / rigEye]);
           const shoulder = posedOrigin(b0, i);
+          if (isHeadAnchored) {
+            const ha = solveHeadAnchorFrame(set, c, i);
+            if (ha !== null) {
+              job.farthest = Math.max(job.farthest, Math.hypot(ha.targetTip[0] - shoulder[0], ha.targetTip[1] - shoulder[1]));
+              job.placed.push([(ha.placedTip[0] - h.centre[0]) / rigEye, (ha.placedTip[1] - h.centre[1]) / rigEye]);
+              if (ha.upperHeld) job.upperHeld.push(i);
+              if (ha.saturated) job.saturated!.push({ frame: i, residual: r3(ha.residual) });
+              const tt0 = turn0 === undefined ? 0 : wrap(ha.a0 - set.drawn[b0]!);
+              const tt1 = turn1 === undefined ? 0 : wrap(ha.a1 - set.drawn[b1]!);
+              upperAsked.push(tt0);
+              upperOver.push(0);
+              foreAsked.push(tt1);
+              foreOver.push(0);
+              heldMiss.push(ha.saturated ? ha.residual / rigEye : 0);
+              t0[i] = ha.a0;
+              t1[i] = ha.a1;
+              continue;
+            }
+          }
           const target: Pt = [h.centre[0] + ref[0] * rigEye, h.centre[1] + ref[1] * rigEye];
           let solveTarget: Pt = target;
           if (up && l0 / rigEye <= 3.5 && (turn0 !== undefined || turn1 !== undefined)) {
@@ -1848,12 +2047,28 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       if (art.length > 0) raisedArt.push({ sw: s, entries: art });
     }
   }
-  // #188: Even without --raised-by-head, apply symmetric normalisation and support-arm anchoring on each switch's span.
+  // #188 / #191: Even without --raised-by-head, apply symmetric normalisation, support-arm anchoring, and head-anchored IK on each switch's span.
   for (const s of sw.switches) {
     const set = map.alternates.find((a) => a.name === s.set)!;
     if (set.symmetric === true && headOk === null && hipsOk === null) {
       for (let i = s.frames[0]; i <= s.frames[1]; i++) solveSymmetricFrame(set, i);
     }
+    if (set.anchor !== undefined && headOk === null && hipsOk === null && HEAD_ANCHOR_FRAME !== 'off') {
+      for (const cn of set.anchor) {
+        if (!s.chains.includes(cn)) continue;
+        const c = map.chains.find((x) => x.name === cn);
+        if (!c || c.bones.length < 2) continue;
+        const t0 = targets.get(c.bones[0]!)!;
+        const t1 = targets.get(c.bones[1]!)!;
+        for (let i = s.frames[0]; i <= s.frames[1]; i++) {
+          const ha = solveHeadAnchorFrame(set, c, i);
+          if (ha !== null) {
+            t0[i] = ha.a0;
+            t1[i] = ha.a1;
+          }
+        }
+      }
+    }
     if (set.support !== undefined) {
       for (const cn of s.chains) {
         const c = map.chains.find((x) => x.name === cn)!;
@@ -1915,6 +2130,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       worst: { before: worst(job.before), after: worst(after), placed: r6(Math.max(...after.map((v, k) => Math.hypot(v[0] - job.placed[k]![0], v[1] - job.placed[k]![1])))) },
       short,
       upperHeld: job.upperHeld,
+      ...(job.saturated !== undefined ? { saturated: job.saturated } : {}),
       reach: { min: r6(Math.abs(job.l0 - job.l1)), max: r6(job.l0 + job.l1), farthest: r6(job.farthest) },
     };
     // The unit sits after `seconds`, as the report has always written it.
@@ -1961,7 +2177,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
     }
   }
-  // #188: Cover the full shown/bridged span of symmetric sets and support-arm sets after short interpolation.
+  // #188 / #191: Cover the full shown/bridged span of symmetric sets, support-arm sets, and head-anchored chains after short interpolation.
   for (let sIdx = 0; sIdx < sw.switches.length; sIdx++) {
     const s = sw.switches[sIdx]!;
     const set = map.alternates.find((a) => a.name === s.set)!;
@@ -1972,6 +2188,46 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     while (loShow - 1 >= 0 && isSetShownAt(loShow - 1)) loShow--;
     let hiShow = s.frames[1];
     while (hiShow + 1 < n && isSetShownAt(hiShow + 1)) hiShow++;
+    if (set.anchor !== undefined && HEAD_ANCHOR_FRAME !== 'off') {
+      for (const cn of set.anchor) {
+        const c = map.chains.find((x) => x.name === cn);
+        if (!c || c.bones.length < 2) continue;
+        const chainSlots = setSlots.filter(([sl]) => {
+          const sb = slots.get(sl)?.bone;
+          return sb !== undefined && c.bones.includes(sb);
+        });
+        const isChainShownAt = (i: number): boolean =>
+          chainSlots.length > 0
+            ? chainSlots.every(([sl, att]) => sw.shown.get(sl)?.[i] === att)
+            : isSetShownAt(i);
+        let loC = s.frames[0];
+        while (loC - 1 >= 0 && isChainShownAt(loC - 1)) loC--;
+        let hiC = s.frames[1];
+        while (hiC + 1 < n && isChainShownAt(hiC + 1)) hiC++;
+        const t0 = targets.get(c.bones[0]!)!;
+        const t1 = targets.get(c.bones[1]!)!;
+        for (let i = loC; i <= hiC; i++) {
+          const ha = solveHeadAnchorFrame(set, c, i);
+          if (ha !== null) {
+            t0[i] = ha.a0;
+            t1[i] = ha.a1;
+          }
+        }
+        // If `short` or `chainHolds` ramp-interpolated the boundary frame immediately outside the
+        // anchored chain's shown window (`loC - 1` or `hiC + 1`) while a neighbouring set's
+        // attachment is still displayed on that bone, restore that boundary frame from the
+        // neighbouring set's clamped key (`loC - 2` / `hiC + 2`) so the neighbouring set's art
+        // is not bent toward the anchored pose before its slot switches.
+        if (loC >= 2 && covered.get(cn)?.[loC - 1] === true) {
+          t0[loC - 1] = t0[loC - 2]!;
+          t1[loC - 1] = t1[loC - 2]!;
+        }
+        if (hiC + 2 < n && covered.get(cn)?.[hiC + 1] === true) {
+          t0[hiC + 1] = t0[hiC + 2]!;
+          t1[hiC + 1] = t1[hiC + 2]!;
+        }
+      }
+    }
     if (set.symmetric === true) {
       for (let i = loShow; i <= s.frames[1]; i++) solveSymmetricFrame(set, i);
       if (loShow < s.frames[0]) {
@@ -2094,6 +2350,31 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   const solvedKey = (b: string, i: number) => legPoses?.[i]!.solved.get(b);
 
+  // #190: couple the vertical residual removed by the neck-length clamp into head.rotate
+  // in phase (+NOD_RESIDUAL_HEAD_GAIN °/unit), adding 0 on frames where the clamp did not act.
+  if (headNodReading !== null) {
+    const hb = headNodReading.bone;
+    const tg = targets.get(hb);
+    if (tg !== undefined) {
+      const above = mappedAbove(hb);
+      const hc = map.chains.find((c) => c.bones.includes(hb));
+      const limits = hc?.range[hb];
+      const cov = hc !== undefined ? covered.get(hc.name) : undefined;
+      for (let i = 0; i < n; i++) {
+        const res = headNodReading.residual[i]!;
+        if (res === 0) continue;
+        let next = wrap(tg[i]! + NOD_RESIDUAL_HEAD_GAIN * res);
+        if (limits !== undefined && cov?.[i] !== true) {
+          const key = wrap((next - restOf.get(hb)!) - (above === null ? 0 : turn(above, i)));
+          if (overflow(key, limits) > RANGE_SLACK) {
+            next = wrap(next + Math.min(Math.max(key, limits[0]), limits[1]) - key);
+          }
+        }
+        tg[i] = next;
+      }
+    }
+  }
+
   // Keys: the bone's turn less the turn of the nearest mapped bone above it.
   const tracks: Array<MotionTrack | SlotTrack> = [];
   for (const c of map.chains) {
@@ -2129,7 +2410,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const h = heldOf('l_ear');
       return 'never' in h ? null : h.at;
     })();
-    face = readFace(map.face, series.get('nose')!, series.get('r_eye')!, series.get('l_eye')!, rEar, lEar);
+    face = readFace(map.face, series.get('nose')!, series.get('r_eye')!, series.get('l_eye')!, rEar, lEar, headNodReading?.residual ?? null, NOD_RESIDUAL_PITCH_GAIN);
     for (const axis of ['yaw', 'pitch'] as const) {
       const ax = face[axis];
       if (ax === undefined) continue;
@@ -2260,7 +2541,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face, body, figureScale,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face, body, figureScale, headNod: headNodReading,
   };
 }
 
@@ -2327,6 +2608,20 @@ function headOf(map: JointMap): Head | { problem: string } {
   return { problem: `${lead}; no chain of the map carries the eye line (joints r_eye → l_eye), so the rig has no eye points to measure` };
 }
 
+/** The rig's head bone (the bone carrying `r_eye → l_eye` or `l_eye → r_eye` in the map), or null if no chain carries the eye line. */
+function headBoneOf(map: JointMap): string | null {
+  for (const c of map.chains) {
+    for (let k = 0; k + 1 < c.joints.length; k++) {
+      const a = c.joints[k]!;
+      const b = c.joints[k + 1]!;
+      if ((a === 'r_eye' && b === 'l_eye') || (a === 'l_eye' && b === 'r_eye')) {
+        return c.bones[k] ?? null;
+      }
+    }
+  }
+  return null;
+}
+
 type ShortSpan = Omit<Short, 'chain' | 'bone' | 'joints'>;
 
 /**

package/src/switch.ts

@@ -1426,6 +1426,8 @@ export interface Raised {
   short: ReachShort[];
   /** The frames whose upper arm the set's `turn` held: the forearm re-aimed at the placed wrist. */
   upperHeld: number[];
+  /** For a head-anchored chain (`anchor`, rig-c/pose#191): each frame where the set's `turn` clamp saturated and left a non-zero wrist residual, in rig world units. */
+  saturated?: Array<{ frame: number; residual: number }>;
   /** The arm's reach (from |l0 − l1| to l0 + l1, world units from the shoulder) and the farthest target from the shoulder over the span. */
   reach: { min: number; max: number; farthest: number };
 }
@@ -1459,7 +1461,8 @@ export function raisedLine(e: Raised | ByHip, times: readonly number[]): string
   const w = anchorOf(e);
   const units = 'hips' in e ? e.hips : e.eyes;
   const med = (vs: readonly P2[]): P2 => [median(vs.map((v) => v[0])), median(vs.map((v) => v[1]))];
-  const held = e.upperHeld.length === 0 ? 'the upper arm within its turn on every frame' : `the upper arm held by the set's turn on ${e.upperHeld.length} frame(s) (${framesText(e.upperHeld)}), the forearm re-aimed`;
+  const satText = e.saturated !== undefined && e.saturated.length > 0 ? `; residual ${e.saturated.map((s) => `f${s.frame} ${s.residual.toFixed(2)}u`).join(', ')}` : '';
+  const held = e.upperHeld.length === 0 ? 'the upper arm within its turn on every frame' : `the upper arm held by the set's turn on ${e.upperHeld.length} frame(s) (${framesText(e.upperHeld)}${satText}), the forearm re-aimed`;
   const out = e.short.length === 0 ? 'every target in reach' : `out of reach on ${e.short.reduce((k, s) => k + s.frames[1] - s.frames[0] + 1, 0)} frame(s) (REACH)`;
   return `set "${e.set}" chain "${e.chain}" ${spanOf(e.frames, times)}: the wrist placed against ${w.against}; ${w.unitOne} (median) rig ${units.rig.toFixed(2)} units, reference ${units.reference.toFixed(2)} px; wrist − ${w.centre} in ${w.unit} (x right, y up), median reference ${xy(med(e.reference))}, placed ${xy(med(e.placed))}, before ${xy(med(e.before))}, after ${xy(med(e.after))}; worst |rig − reference| before ${xy(e.worst.before)}, after ${xy(e.worst.after)}; worst |after − placed| ${e.worst.placed.toFixed(2)}; ${held}; ${out}`;
 }