@rig-c/pose 0.29.0 → 0.30.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)) 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).
+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 on sequences where that clamp acts, the clamped vertical nod (`clampedY`) 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), [#205](https://github.com/rig-c/pose/issues/205); gains calibrated against the hand-polished reference `p1`). 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:
 
@@ -147,7 +147,10 @@ and what the run cannot decide for you it lists:
 - `BODY` — per-frame body yaw read from the camera-normalised shoulder width (`r_shoulder + l_shoulder`) and hip width (`r_hip + l_hip`) projected perpendicular to the trunk against the sequence's standing width (`yaw ≈ acos(w / w_standing)`, [#173](https://github.com/rig-c/pose/issues/173)): its overall and opening (`frames 0–47`) range, every span with `|yaw| ≥ 45°`, and, when `body.yaw` or `body.sets` is declared in the map, its knee-mapped dial keys and every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `body` in `--report`.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `frames`, `duration`, `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `inputs` (consumed rig spec, map and pose files, each with invocation-relative `path` and exact-byte `sha256`; a folder rig resolves to its actual rig.json; these three identities do not claim to bind optional base motion, sets or images), `frames`, `duration`, `frameTimes` (the exact motion-key time for each pose frame; never FPS inferred from duration), `render` (the separate renderer sampling domain, `{ fps, frames }` from frame-set metadata, or `null` when not measured), `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `jumpEvents`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+
+Report event objects with a pose `frame` or inclusive `frames` also carry exact `t` or `times` from `frameTimes`; existing `seconds` remain span lengths, with additive `spanSeconds`. Holds preserve their frame-index `from`/`to`. Existing scan joint/chain identities remain beside map-derived `bone` (a unique mapped target) or `bones` (all actual mapped targets); no joint-name heuristic chooses a target. `feet.jumps` stays an array of original frame pairs; `feet.jumpEvents` adds matching `{ frames, times }` objects. Fold and uncovered rows preserve their discrete `times` and gaps, declare `domain: "render"`, and use the separate root `render` domain, never fabricated nearest pose-frame indices. The run hashes map/pose from the exact buffers passed to their readers, snapshots the resolved rig file before its gate, and rechecks all three before user-output writes. The writer validates coordinates before output writes and never changes motion keys. The switch diagnostic `moved.frame` is a selected-to-keyed pair with signed `frames`/`seconds` displacement; it is preserved as diagnostic data, not reinterpreted as an inclusive interval. An explicitly supplied uniform writer clock requires both positive `fps` and seconds offset `frame0`; canonical pose input does not yet declare FPS, so the retarget producer always writes exact `frameTimes`.
+
 
 | field | each entry |
 | --- | --- |
@@ -315,7 +318,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), [#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`).
+- `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), [#205](https://github.com/rig-c/pose/issues/205)): `{ "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 the head nod channel's clamped vertical travel (`clampedY`, `+2.8°/unit` when the `±2%` neck-length clamp acts on the sequence) into `pitch` in phase ([#190](https://github.com/rig-c/pose/issues/190), [#205](https://github.com/rig-c/pose/issues/205)), 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`
@@ -352,8 +355,8 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 - `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`).
+- `symmetric` (optional, [#188](https://github.com/rig-c/pose/issues/188), [#206](https://github.com/rig-c/pose/issues/206)): `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)), ramping in and out in joint space across any adjacent bridge frames where the set's slots remain shown. 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), [#206](https://github.com/rig-c/pose/issues/206)): 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's slots show (`loShow..hiShow`), each support chain's bones anchor to `drawn` within `±2.5°` (`≤ ±3°`) of the pose's delta relative to the set's reference pose (bridging in joint space across any preceding gap frames where the leaving set's slots still show), and an unplaced active raised arm in the same set clears the head/bun outward along the 2D shoulder→wrist direction (`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`.
 
@@ -365,7 +368,7 @@ The bound exists because speed alone rewarded showing art far from its pose. Unb
 
 Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's old and new frame (the same under `first`), the frames and seconds it moved, the speed on both and its window, and the report carries the same under `moved`.
 
-**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. Between two sets that both draw an arm behind the torso, a frame that belongs to neither set stays behind (the set nearer in hand position and segment distance, not frame count); the default front slot is for a frame no set can claim **and** whose arm is read in front — not a fallback ([#136](https://github.com/rig-c/pose/issues/136), [#139](https://github.com/rig-c/pose/issues/139), [#162](https://github.com/rig-c/pose/issues/162), [#180](https://github.com/rig-c/pose/issues/180)). A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
+**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. Between two sets that both draw an arm behind the torso, a frame that belongs to neither set stays behind (the set nearer in hand position and segment distance, not frame count), with any adjacent bridge or `SHORT` ramp interpolated in joint space (parent-local angle for child bones) and any extended hold of a tight set included in `chainHolds`/`covered` so the held art is clamped and exempted from `capShortSteps` and `range`; the default front slot is for a frame no set can claim **and** whose arm is read in front — not a fallback ([#136](https://github.com/rig-c/pose/issues/136), [#139](https://github.com/rig-c/pose/issues/139), [#162](https://github.com/rig-c/pose/issues/162), [#180](https://github.com/rig-c/pose/issues/180), [#187](https://github.com/rig-c/pose/issues/187), [#206](https://github.com/rig-c/pose/issues/206)). A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
 
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds, held as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.29.0",
+  "version": "0.30.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/report.ts

@@ -0,0 +1,88 @@
+/** Add report coordinates without touching the retarget or any source value. */
+import type { JointMap } from './map.ts';
+import { isObject, Problems, Refusal } from './problems.ts';
+
+export type ReportClock={frameTimes:readonly number[]}|{fps:number;frame0:number;frames:number};
+export interface RenderDomain {fps:number;frames:number}
+export interface ReportInput {path:string;sha256:string}
+export interface ReportInputs {rig:ReportInput;map:ReportInput;pose:ReportInput}
+function fail(field:string,text:string):never {throw new Refusal([{code:'REPORT_TIMEBASE',text:`${field}: ${text}`}]);}
+function finite(value:unknown,field:string):number {if(typeof value!=='number'||!Number.isFinite(value)||value<0)return fail(field,`found ${String(value)}; expected finite seconds >= 0`);return value;}
+function integer(value:unknown,field:string):number {const n=finite(value,field);if(!Number.isSafeInteger(n))fail(field,`found ${n}; expected nonnegative safe integer`);return n;}
+export function reportFrameTimes(clock:ReportClock):number[] {
+  if('frameTimes' in clock){
+    if(!Array.isArray(clock.frameTimes))fail('frameTimes','expected an explicit array');
+    const values=clock.frameTimes.map((time,i)=>finite(time,`frameTimes[${i}]`));
+    if(!values.length)fail('frameTimes','expected at least one explicit frame');
+    for(let i=1;i<values.length;i++)if(values[i]!<=values[i-1]!)fail(`frameTimes[${i}]`,`found ${values[i]}; must follow ${values[i-1]}`);return values;
+  }
+  const fps=finite(clock.fps,'fps');if(fps===0)fail('fps','expected positive explicit rate');const frame0=finite(clock.frame0,'frame0'),count=integer(clock.frames,'frames');
+  if(count===0)fail('frames','expected at least one frame');const times=Array.from({length:count},(_,i)=>frame0+i/fps);
+  for(let i=0;i<times.length;i++){finite(times[i],`frame ${i}`);if(i>0&&times[i]!<=times[i-1]!)fail(`frame ${i}`,'uniform clock cannot represent distinct frame samples');}return times;
+}
+export function reportRenderDomain(input:unknown,animation:string):RenderDomain {
+  if(!isObject(input)||!Array.isArray(input.sets))fail('render.sets','expected renderer frame-set metadata');
+  const set=input.sets.find((value:unknown)=>isObject(value)&&value.animation===animation);
+  if(!isObject(set))fail('render.animation',`missing ${JSON.stringify(animation)} frame-set metadata`);
+  const fps=finite(set.fps,'render.fps'),frames=integer(set.sampled,'render.frames');if(fps===0||frames===0)fail('render','expected positive declared fps and sampled frame count');return {fps,frames};
+}
+function clone(value:unknown):unknown {if(Array.isArray(value))return value.map(clone);if(isObject(value))return Object.fromEntries(Object.entries(value).map(([key,item])=>[key,clone(item)]));return value;}
+
+export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null=null,inputs?:ReportInputs):Record<string,unknown> {
+  const times=reportFrameTimes(clock),report=clone(input) as Record<string,unknown>;
+  if(render!==null){const fps=finite(render.fps,'render.fps'),frames=integer(render.frames,'render.frames');if(fps===0||frames===0)fail('render','expected positive declared fps and sampled frame count');}
+  if(report.frames!==times.length)fail('frames',`report has ${String(report.frames)}, clock has ${times.length}`);
+  const problems=new Problems();
+  const time=(frame:unknown,where:string):number=>{const n=integer(frame,where);if(n>=times.length)fail(where,`frame ${n} outside ${times.length} declared frames`);return times[n]!;};
+  const add=(row:Record<string,unknown>,key:string,value:unknown,where:string)=>{
+    if(row[key]!==undefined&&JSON.stringify(row[key])!==JSON.stringify(value))problems.add('REPORT_COORDINATE',`${where}.${key}: supplied ${JSON.stringify(row[key])}, expected ${JSON.stringify(value)}`);
+    else row[key]=value;
+  };
+  // A joint can influence several mapped segments. Preserve all actual matches;
+  // only a unique match may occupy the singular bone field.
+  const bonesFor=(joint:string)=>{const bones=new Set<string>();if(map.translate?.joint===joint)bones.add(map.translate.bone);for(const chain of map.chains)for(let i=0;i<chain.bones.length;i++)if(chain.joints[i]===joint||chain.joints[i+1]===joint)bones.add(chain.bones[i]!);return [...bones];};
+  const pair=(value:unknown,where:string):[number,number]=>{if(!Array.isArray(value)||value.length!==2)fail(where,'expected inclusive [first,last] frame pair');const first=integer(value[0],where+'[0]'),last=integer(value[1],where+'[1]');if(last<first)fail(where,`found [${first},${last}]; inclusive last must be >= first`);return [first,last];};
+  const poseEvent=(where:string)=>/^report\.(?:holds|short|endOn|bends|flips|turns|range|artRange|raised|byHip|landings|shear|switches|cleaned\.(?:holds|seams|spikes\.found)|feet\.(?:supports|changes|steps|lowered|tracked|shifts)|stance\.(?:runs|over))\[\d+\]$/.test(where);
+  const targets=(row:Record<string,unknown>,where:string)=>{
+    if(row.bone!==undefined||row.slot!==undefined)return;
+    const joints=typeof row.joint==='string'?[row.joint]:typeof row.point==='string'?[row.point]:Array.isArray(row.joints)?row.joints.filter((v):v is string=>typeof v==='string'):[];
+    const chain=typeof row.chain==='string'?map.chains.find(c=>c.name===row.chain):undefined;
+    const bones=[...new Set(chain?chain.bones:joints.flatMap(bonesFor))];
+    if(bones.length===1)add(row,'bone',bones[0],where);else if(bones.length>1)add(row,'bones',bones,where);
+    // Multiple affected targets remain explicit lists, never a guessed winner.
+    if(typeof row.point==='string')add(row,'joint',row.point,where);
+  };
+  const visit=(value:unknown,where:string):void=>{
+    if(Array.isArray(value)){value.forEach((row,i)=>visit(row,`${where}[${i}]`));return;}
+    if(!isObject(value))return;
+    // Preserve uncovered's discrete renderer times; they do not index the pose.
+    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')){
+      if(!render)fail(where,'render-domain event requires declared renderer metadata');
+      add(value,'domain','render',where);return;
+    }
+    let coordinates=false;
+    if(poseEvent(where)&&value.frame!==undefined&&typeof value.frame!=='number')fail(where+'.frame','expected nonnegative integer pose frame');
+    if(typeof value.frame==='number'){add(value,'t',time(value.frame,where+'.frame'),where);coordinates=true;}
+    if((poseEvent(where)&&value.frames!==undefined)||(Array.isArray(value.frames)&&value.frames.length===2&&value.frames.every(frame=>typeof frame==='number'))){const frames=pair(value.frames,where+'.frames');add(value,'times',frames.map((frame,i)=>time(frame,`${where}.frames[${i}]`)),where);coordinates=true;}
+    if(where.startsWith('report.holds[')&&typeof value.from==='number'&&typeof value.to==='number'){
+      pair([value.from,value.to],where+'.from/to');add(value,'frames',[value.from,value.to],where);add(value,'times',[time(value.from,where+'.from'),time(value.to,where+'.to')],where);coordinates=true;
+    }
+    if(coordinates){if(typeof value.seconds==='number')add(value,'spanSeconds',value.seconds,where);targets(value,where);}
+    // Recurse over the original fields only; added time/target arrays are data.
+    for(const [key,item] of Object.entries(value))if(!['t','times','bones','spanSeconds'].includes(key))visit(item,where+'.'+key);
+  };
+  visit(report,'report');
+  if(isObject(report.feet)&&Array.isArray(report.feet.jumps)){
+    add(report.feet,'jumpEvents',report.feet.jumps.map((frames:unknown,index:number)=>{
+      const interval=pair(frames,`feet.jumps[${index}]`);
+      return {frames:[...interval],times:interval.map((frame,i)=>time(frame,`feet.jumps[${index}][${i}]`))};
+    }),'report.feet');
+  }
+  // The actual producer uses frameTimes. Uniform clocks exist only when a
+  // caller explicitly supplies fps/frame0, never inferred from samples.
+  if('frameTimes' in clock)add(report,'frameTimes',[...times],'report');else{add(report,'fps',clock.fps,'report');add(report,'frame0',clock.frame0,'report');}
+  add(report,'render',render,'report');
+  if(inputs!==undefined){if(!isObject(inputs))throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);for(const key of ['rig','map','pose'] as const){const entry=inputs[key];if(!isObject(entry)||typeof entry.path!=='string'||!entry.path||entry.path.startsWith('/')||entry.path.charCodeAt(0)===92||/^[A-Za-z]:/.test(entry.path)||typeof entry.sha256!=='string'||! /^[a-f0-9]{64}$/.test(entry.sha256))throw new Refusal([{code:'REPORT_INPUTS',text:`inputs.${key}: expected invocation-relative consumed file path and exact SHA-256`}]);}add(report,'inputs',clone(inputs),'report');}
+  problems.throwIfAny();return report;
+}
+export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}

package/src/retarget.ts

@@ -99,18 +99,20 @@ 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`).
+ * Beat-nod phase-coupling gain (`°/unit`) from the clamped `head.translate.y`
+ * offset (`clampedY`, bounded by `±2%` of neck length) onto `map.face.pitch`
+ * (`pitch_dial.rotate`, `rig-c/pose#190`, `#205`) when the neck-length clamp
+ * acts on the sequence. 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`).
+ * Beat-nod phase-coupling gain (`°/unit`) from the clamped `head.translate.y`
+ * offset (`clampedY`, bounded by `±2%` of neck length) onto the head chain
+ * bone's `rotate` track (`head.rotate`, `rig-c/pose#190`, `#205`) when the
+ * neck-length clamp acts on the sequence. Measured on the dancer reference
+ * hand pass (`hand/p1` HP2: `+1.6°/unit`).
  */
 export const NOD_RESIDUAL_HEAD_GAIN = 1.6;
 
@@ -1396,14 +1398,14 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
     }
     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) {
+    if (headNodReading !== null && headNodReading.bone === hb && headNodReading.residual.some((r) => r !== 0)) {
+      const nodY = headNodReading.clampedY[i] ?? 0;
+      if (nodY !== 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);
+        let next = wrap(rotDeg + NOD_RESIDUAL_HEAD_GAIN * nodY);
         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) {
@@ -1580,9 +1582,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   };
   /**
-   * #188: For a `set.symmetric === true` gesture set, normalise its two two-bone arm chains
-   * on frame `i` to the set's `drawn` symmetry centre so `|elbow_l.y - elbow_r.y| == 0` and
-   * clamp both forearms so the wrists stay inside the head silhouette.
+   * #188 / #207: For a `set.symmetric === true` gesture set, solve its two two-bone arm chains
+   * on frame `i` in the chest-local frame so the diamond is symmetric about the torso axis and
+   * torso lean carries the whole diamond without collapsing one arm into the ±20° turn clamp.
    */
   const solveSymmetricFrame = (set: (typeof map.alternates)[number], i: number): { cR: Chain; cL: Chain; wR: Pt; wL: Pt; hc: Pt; ed: number } | null => {
     if (set.chains.length !== 2) return null;
@@ -1624,6 +1626,21 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         ed = d;
       }
     }
+    let hc0: Pt = [(SR0[0] + SL0[0]) / 2, (SR0[1] + SL0[1]) / 2 + 0.85 * Math.hypot(SL0[0] - SR0[0], SL0[1] - SR0[1])];
+    let ed0 = Math.max(1e-3, 0.30 * Math.hypot(SL0[0] - SR0[0], SL0[1] - SR0[1]));
+    if (gestureHead !== null) {
+      const ha0 = rigPoint(rest, gestureHead.points[0]);
+      const hb0 = rigPoint(rest, gestureHead.points[1]);
+      if (ha0 !== null && hb0 !== null) {
+        const d0 = Math.hypot(hb0[0] - ha0[0], hb0[1] - ha0[1]);
+        if (d0 > 1e-6) {
+          hc0 = [(ha0[0] + hb0[0]) / 2, (ha0[1] + hb0[1]) / 2];
+          ed0 = d0;
+        }
+      }
+    }
+    const above0 = mappedAbove(bR0);
+    const chestTurn = above0 === null ? 0 : turn(above0, i);
     const drawnR0 = set.drawn[bR0]!;
     const drawnR1 = set.drawn[bR1]!;
     const drawnL0 = set.drawn[bL0]!;
@@ -1632,19 +1649,39 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     const turnR1 = set.turn[bR1] ?? [-20, 20];
     const turnL0 = set.turn[bL0] ?? [-20, 20];
     const turnL1 = set.turn[bL1] ?? [-20, 20];
-    const rawR0 = rawTargets.get(bR0)?.[i] ?? drawnR0;
-    const rawL0 = rawTargets.get(bL0)?.[i] ?? drawnL0;
-    const offR0 = wrap(rawR0 - drawnR0);
-    const offL0 = wrap(rawL0 - drawnL0);
-    let cOpen = Math.max(-4, Math.min(2, 0.15 * 0.5 * (offR0 - offL0)));
-    const solveTilt = (open: number): { aR0: number; aL0: number; exR: number; eyR: number; exL: number; eyL: number } => {
+    const erDrawnX = SR0[0] + lR0 * Math.cos((drawnR0 + dR0) / DEG);
+    const elDrawnX = SL0[0] + lL0 * Math.cos((drawnL0 + dL0) / DEG);
+    let aR0_c: number;
+    let aL0_c: number;
+    let aR1_c: number;
+    let aL1_c: number;
+    if (Math.abs(wrap(drawnR0 + drawnL0 - 180)) > 1 && (hc0[0] - erDrawnX > lR1 || elDrawnX - hc0[0] > lL1)) {
+      const eyTarget = hc0[1] - 0.30 * ed0;
+      const sR = Math.max(-1, Math.min(1, (eyTarget - SR0[1]) / Math.max(1e-6, lR0)));
+      const sL = Math.max(-1, Math.min(1, (eyTarget - SL0[1]) / Math.max(1e-6, lL0)));
+      const wantR0 = wrap(180 - Math.asin(sR) * DEG - dR0);
+      const wantL0 = wrap(Math.asin(sL) * DEG - dL0);
+      const offR0_c = Math.min(Math.max(wrap(wantR0 - drawnR0), turnR0[0]), turnR0[1]);
+      const offL0_c = Math.min(Math.max(wrap(wantL0 - drawnL0), turnL0[0]), turnL0[1]);
+      aR0_c = wrap(drawnR0 + offR0_c);
+      aL0_c = wrap(drawnL0 + offL0_c);
+      const offR1_c = Math.min(Math.max(-0.35 * offR0_c, turnR1[0]), turnR1[1]);
+      const offL1_c = Math.min(Math.max(-0.35 * offL0_c, turnL1[0]), turnL1[1]);
+      aR1_c = wrap(drawnR1 + offR1_c);
+      aL1_c = wrap(drawnL1 + offL1_c);
+    } else {
+      const rawR0 = wrap((rawTargets.get(bR0)?.[i] ?? drawnR0) - chestTurn);
+      const rawL0 = wrap((rawTargets.get(bL0)?.[i] ?? drawnL0) - chestTurn);
+      const offR0 = wrap(rawR0 - drawnR0);
+      const offL0 = wrap(rawL0 - drawnL0);
+      const cOpen = Math.max(-4, Math.min(2, 0.15 * 0.5 * (offR0 - offL0)));
       const evalDiff = (deg: number) => {
         const dR = deg < 0 ? 0.25 * deg : deg;
         const dL = deg > 0 ? 0.25 * deg : deg;
-        const ar = drawnR0 + Math.min(Math.max(open + dR, turnR0[0]), turnR0[1]);
-        const al = drawnL0 + Math.min(Math.max(-open + dL, turnL0[0]), turnL0[1]);
-        const eyr = sr[1] + lR0 * Math.sin((ar + dR0) / DEG);
-        const eyl = sl[1] + lL0 * Math.sin((al + dL0) / DEG);
+        const ar = drawnR0 + Math.min(Math.max(cOpen + dR, turnR0[0]), turnR0[1]);
+        const al = drawnL0 + Math.min(Math.max(-cOpen + dL, turnL0[0]), turnL0[1]);
+        const eyr = SR0[1] + lR0 * Math.sin((ar + dR0) / DEG);
+        const eyl = SL0[1] + lL0 * Math.sin((al + dL0) / DEG);
         return eyl - eyr;
       };
       let lo = -45;
@@ -1669,68 +1706,73 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
       const dR = deg < 0 ? 0.25 * deg : deg;
       const dL = deg > 0 ? 0.25 * deg : deg;
-      let aR0 = drawnR0 + Math.min(Math.max(open + dR, turnR0[0]), turnR0[1]);
-      let aL0 = drawnL0 + Math.min(Math.max(-open + dL, turnL0[0]), turnL0[1]);
-      const eyR0 = sr[1] + lR0 * Math.sin((aR0 + dR0) / DEG);
-      const eyL0 = sl[1] + lL0 * Math.sin((aL0 + dL0) / DEG);
+      aR0_c = drawnR0 + Math.min(Math.max(cOpen + dR, turnR0[0]), turnR0[1]);
+      aL0_c = drawnL0 + Math.min(Math.max(-cOpen + dL, turnL0[0]), turnL0[1]);
+      const eyR0 = SR0[1] + lR0 * Math.sin((aR0_c + dR0) / DEG);
+      const eyL0 = SL0[1] + lL0 * Math.sin((aL0_c + dL0) / DEG);
       if (Math.abs(eyL0 - eyR0) > 1e-4) {
-        const sL = Math.max(-1, Math.min(1, (eyR0 - sl[1]) / Math.max(1e-6, lL0)));
+        const sL = Math.max(-1, Math.min(1, (eyR0 - SL0[1]) / Math.max(1e-6, lL0)));
         const candL = wrap(Math.asin(sL) * DEG - dL0);
         const tL = wrap(candL - drawnL0);
-        if (tL >= turnL0[0] && tL <= turnL0[1]) aL0 = candL;
+        if (tL >= turnL0[0] && tL <= turnL0[1]) aL0_c = candL;
       }
-      const rR0 = (aR0 + dR0) / DEG;
-      const rL0 = (aL0 + dL0) / DEG;
-      return {
-        aR0: wrap(aR0),
-        aL0: wrap(aL0),
-        exR: sr[0] + lR0 * Math.cos(rR0),
-        eyR: sr[1] + lR0 * Math.sin(rR0),
-        exL: sl[0] + lL0 * Math.cos(rL0),
-        eyL: sl[1] + lL0 * Math.sin(rL0),
-      };
-    };
-    const upper = solveTilt(cOpen);
-    const aimFore = (ex: number, ey: number, l1: number, d1: number, drawn1: number, turn1: readonly [number, number], tx: number, ty: number): [number, Pt] => {
-      const want = wrap(Math.atan2(ty - ey, tx - ex) * DEG - d1);
-      const off = Math.min(Math.max(wrap(want - drawn1), turn1[0]), turn1[1]);
-      let a1 = wrap(drawn1 + off);
-      let r1 = (a1 + d1) / DEG;
-      let wx = ex + l1 * Math.cos(r1);
-      let wy = ey + l1 * Math.sin(r1);
-      const xMin = hc[0] - 0.30 * ed;
-      const xMax = hc[0] + 0.30 * ed;
-      const yMin = hc[1] + 0.15 * ed;
-      const yMax = hc[1] + 0.95 * ed;
-      if (wx < xMin || wx > xMax || wy < yMin || wy > yMax) {
-        let bestA = a1;
-        let bestErr = Infinity;
-        for (let step = -200; step <= 200; step++) {
-          const candOff = turn1[0] + ((turn1[1] - turn1[0]) * (step + 200)) / 400;
-          const candA = wrap(drawn1 + candOff);
-          const cr = (candA + d1) / DEG;
-          const cwx = ex + l1 * Math.cos(cr);
-          const cwy = ey + l1 * Math.sin(cr);
-          const ox = cwx < xMin ? xMin - cwx : cwx > xMax ? cwx - xMax : 0;
-          const oy = cwy < yMin ? yMin - cwy : cwy > yMax ? cwy - yMax : 0;
-          const err = (ox + oy) * 1000 + Math.hypot(cwx - tx, cwy - ty);
-          if (err < bestErr) {
-            bestErr = err;
-            bestA = candA;
+      aR0_c = wrap(aR0_c);
+      aL0_c = wrap(aL0_c);
+      const rR0_c = (aR0_c + dR0) / DEG;
+      const rL0_c = (aL0_c + dL0) / DEG;
+      const exR_c = SR0[0] + lR0 * Math.cos(rR0_c);
+      const eyR_c = SR0[1] + lR0 * Math.sin(rR0_c);
+      const exL_c = SL0[0] + lL0 * Math.cos(rL0_c);
+      const eyL_c = SL0[1] + lL0 * Math.sin(rL0_c);
+      const aimFore0 = (ex: number, ey: number, l1: number, d1: number, drawn1: number, turn1: readonly [number, number], tx: number, ty: number): number => {
+        const want = wrap(Math.atan2(ty - ey, tx - ex) * DEG - d1);
+        const off = Math.min(Math.max(wrap(want - drawn1), turn1[0]), turn1[1]);
+        let a1 = wrap(drawn1 + off);
+        const r1 = (a1 + d1) / DEG;
+        const wx = ex + l1 * Math.cos(r1);
+        const wy = ey + l1 * Math.sin(r1);
+        const xMin = hc0[0] - 0.30 * ed0;
+        const xMax = hc0[0] + 0.30 * ed0;
+        const yMin = hc0[1] + 0.15 * ed0;
+        const yMax = hc0[1] + 0.95 * ed0;
+        if (wx < xMin || wx > xMax || wy < yMin || wy > yMax) {
+          let bestA = a1;
+          let bestErr = Infinity;
+          for (let step = -200; step <= 200; step++) {
+            const candOff = turn1[0] + ((turn1[1] - turn1[0]) * (step + 200)) / 400;
+            const candA = wrap(drawn1 + candOff);
+            const cr = (candA + d1) / DEG;
+            const cwx = ex + l1 * Math.cos(cr);
+            const cwy = ey + l1 * Math.sin(cr);
+            const ox = cwx < xMin ? xMin - cwx : cwx > xMax ? cwx - xMax : 0;
+            const oy = cwy < yMin ? yMin - cwy : cwy > yMax ? cwy - yMax : 0;
+            const err = (ox + oy) * 1000 + Math.hypot(cwx - tx, cwy - ty);
+            if (err < bestErr) {
+              bestErr = err;
+              bestA = candA;
+            }
           }
+          a1 = bestA;
         }
-        a1 = bestA;
-        r1 = (a1 + d1) / DEG;
-        wx = ex + l1 * Math.cos(r1);
-        wy = ey + l1 * Math.sin(r1);
-      }
-      return [a1, [wx, wy]];
-    };
-    const [aR1, wR] = aimFore(upper.exR, upper.eyR, lR1, dR1, drawnR1, turnR1, hc[0] - 0.20 * ed, hc[1] + 0.65 * ed);
-    const [aL1, wL] = aimFore(upper.exL, upper.eyL, lL1, dL1, drawnL1, turnL1, hc[0] + 0.20 * ed, hc[1] + 0.65 * ed);
-    targets.get(bR0)![i] = upper.aR0;
+        return a1;
+      };
+      aR1_c = aimFore0(exR_c, eyR_c, lR1, dR1, drawnR1, turnR1, hc0[0] - 0.20 * ed0, hc0[1] + 0.65 * ed0);
+      aL1_c = aimFore0(exL_c, eyL_c, lL1, dL1, drawnL1, turnL1, hc0[0] + 0.20 * ed0, hc0[1] + 0.65 * ed0);
+    }
+    const carry = 0.35 * chestTurn;
+    const aR0 = wrap(aR0_c + carry);
+    const aR1 = wrap(aR1_c + carry);
+    const aL0 = wrap(aL0_c + carry);
+    const aL1 = wrap(aL1_c + carry);
+    const rR0 = (aR0 + dR0) / DEG;
+    const rR1 = (aR1 + dR1) / DEG;
+    const rL0 = (aL0 + dL0) / DEG;
+    const rL1 = (aL1 + dL1) / DEG;
+    const wR: Pt = [sr[0] + lR0 * Math.cos(rR0) + lR1 * Math.cos(rR1), sr[1] + lR0 * Math.sin(rR0) + lR1 * Math.sin(rR1)];
+    const wL: Pt = [sl[0] + lL0 * Math.cos(rL0) + lL1 * Math.cos(rL1), sl[1] + lL0 * Math.sin(rL0) + lL1 * Math.sin(rL1)];
+    targets.get(bR0)![i] = aR0;
     targets.get(bR1)![i] = aR1;
-    targets.get(bL0)![i] = upper.aL0;
+    targets.get(bL0)![i] = aL0;
     targets.get(bL1)![i] = aL1;
     return { cR, cL, wR, wL, hc, ed };
   };
@@ -2145,15 +2187,38 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const [lo, hi] = s.frames;
       if (lo <= 0 || hi + 1 >= n) continue;
       if (cov?.[lo - 1] !== true && cov?.[hi + 1] !== true) continue;
+      if (cov?.[lo - 1] === true && cov?.[hi + 1] === true && hi - lo + 1 <= 10) continue;
+      const ch = map.chains.find((c) => c.name === s.chain);
+      const bIdx = ch !== undefined ? ch.bones.indexOf(s.bone) : -1;
+      const parentTg = ch !== undefined && bIdx > 0 ? targets.get(ch.bones[bIdx - 1]!) : undefined;
       const tg = targets.get(s.bone)!;
-      const startA = tg[lo - 1]!;
-      const total = wrap(tg[hi + 1]! - startA);
+      const startA = parentTg !== undefined ? wrap(tg[lo - 1]! - parentTg[lo - 1]!) : tg[lo - 1]!;
+      const endA = parentTg !== undefined ? wrap(tg[hi + 1]! - parentTg[hi + 1]!) : tg[hi + 1]!;
+      const total = wrap(endA - startA);
       const steps = hi - lo + 2;
       for (let k = lo; k <= hi; k++) {
-        tg[k] = wrap(startA + ((k - lo + 1) / steps) * total);
+        const localA = wrap(startA + ((k - lo + 1) / steps) * total);
+        tg[k] = parentTg !== undefined ? wrap(parentTg[k]! + localA) : localA;
       }
       s.step = r3(total / steps);
     }
+    const interpolateChainInJointSpace = (ch: Chain, i0: number, i1: number) => {
+      const steps = i1 - i0;
+      if (steps < 2 || i0 < 0 || i1 >= n) return;
+      for (let bIdx = 0; bIdx < ch.bones.length; bIdx++) {
+        const b = ch.bones[bIdx]!;
+        const tg = targets.get(b);
+        if (!tg) continue;
+        const parentTg = bIdx > 0 ? targets.get(ch.bones[bIdx - 1]!) : undefined;
+        const startA = parentTg !== undefined ? wrap(tg[i0]! - parentTg[i0]!) : tg[i0]!;
+        const endA = parentTg !== undefined ? wrap(tg[i1]! - parentTg[i1]!) : tg[i1]!;
+        const total = wrap(endA - startA);
+        for (let k = i0 + 1; k < i1; k++) {
+          const localA = wrap(startA + ((k - i0) / steps) * total);
+          tg[k] = parentTg !== undefined ? wrap(parentTg[k]! + localA) : localA;
+        }
+      }
+    };
     const holds = sw.chainHolds ?? [];
     for (const h of holds) {
       const swParent = sw.switches.find((s) => s.set === h.set && s.frames[0] === h.frames[0] && s.frames[1] > h.frames[1]);
@@ -2165,19 +2230,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       if (lo > hi || lo <= 0 || hi + 1 >= n) continue;
       const ch = map.chains.find((c) => c.name === h.chain);
       if (!ch) continue;
-      const steps = hi - lo + 2;
-      for (const b of ch.bones) {
-        const tg = targets.get(b);
-        if (!tg) continue;
-        const startA = tg[lo - 1]!;
-        const total = wrap(tg[hi + 1]! - startA);
-        for (let k = lo; k <= hi; k++) {
-          tg[k] = wrap(startA + ((k - lo + 1) / steps) * total);
-        }
-      }
+      interpolateChainInJointSpace(ch, lo - 1, hi + 1);
     }
   }
-  // #188 / #191: Cover the full shown/bridged span of symmetric sets, support-arm sets, and head-anchored chains after short interpolation.
+  // #188 / #191 / #206: 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)!;
@@ -2237,12 +2293,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           for (const cn of set.chains) {
             const c = map.chains.find((x) => x.name === cn);
             if (!c) continue;
-            for (const b of c.bones) {
+            for (let bIdx = 0; bIdx < c.bones.length; bIdx++) {
+              const b = c.bones[bIdx]!;
               const tg = targets.get(b)!;
-              const startA = tg[loRamp]!;
-              const total = wrap(tg[loShow]! - startA);
+              const parentTg = bIdx > 0 ? targets.get(c.bones[bIdx - 1]!) : undefined;
+              const startA = parentTg !== undefined ? wrap(tg[loRamp]! - parentTg[loRamp]!) : tg[loRamp]!;
+              const endA = parentTg !== undefined ? wrap(tg[loShow]! - parentTg[loShow]!) : tg[loShow]!;
+              const total = wrap(endA - startA);
               for (let k = loRamp + 1; k < loShow; k++) {
-                tg[k] = wrap(startA + ((k - loRamp) / steps) * total);
+                const localA = wrap(startA + ((k - loRamp) / steps) * total);
+                tg[k] = parentTg !== undefined ? wrap(parentTg[k]! + localA) : localA;
               }
             }
           }
@@ -2257,23 +2317,43 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const [cR, cL] = S0_0[0] <= S0_1[0] ? [c0, c1] : [c1, c0];
           const bR0 = cR.bones[0]!;
           const bL0 = cL.bones[0]!;
+          const bR1 = cR.bones[1]!;
+          const bL1 = cL.bones[1]!;
           const SR0 = rigPoint(rest, bR0)!;
-          const ER0 = rigPoint(rest, cR.bones[1]!)!;
+          const ER0 = rigPoint(rest, bR1)!;
           const SL0 = rigPoint(rest, bL0)!;
-          const EL0 = rigPoint(rest, cL.bones[1]!)!;
+          const EL0 = rigPoint(rest, bL1)!;
           const lR0 = Math.hypot(ER0[0] - SR0[0], ER0[1] - SR0[1]);
           const lL0 = Math.hypot(EL0[0] - SL0[0], EL0[1] - SL0[1]);
           const dR0 = wrap(Math.atan2(ER0[1] - SR0[1], ER0[0] - SR0[0]) * DEG - restOf.get(bR0)!);
           const dL0 = wrap(Math.atan2(EL0[1] - SL0[1], EL0[0] - SL0[0]) * DEG - restOf.get(bL0)!);
-          for (let i = s.frames[1] + 1; i <= hiShow; i++) {
+          const iEnd = s.frames[1];
+          const iNext = Math.min(n - 1, hiShow + 1);
+          const spanOut = Math.max(1, iNext - iEnd);
+          const startR0 = targets.get(bR0)![iEnd]!;
+          const startL0 = targets.get(bL0)![iEnd]!;
+          const drawnR0 = set.drawn[bR0] ?? startR0;
+          const drawnL0 = set.drawn[bL0] ?? startL0;
+          const drawnR1 = set.drawn[bR1] ?? targets.get(bR1)![iEnd]!;
+          const drawnL1 = set.drawn[bL1] ?? targets.get(bL1)![iEnd]!;
+          const inR1 = wrap(drawnR1 + (set.turn[bR1]?.[0] ?? 0));
+          const inL1 = wrap(drawnL1 + 0.6 * (set.turn[bL1]?.[1] ?? 0));
+          const endR0 = targets.get(bR0)![iNext]!;
+          const endL0 = targets.get(bL0)![iNext]!;
+          for (let i = iEnd + 1; i <= hiShow; i++) {
+            const u = (i - iEnd) / spanOut;
+            const w = 1 - u;
+            const alpha = 0.25 * u + 0.75 * u * u;
             const sr = posedOrigin(bR0, i);
             const sl = posedOrigin(bL0, i);
-            const baseR = targets.get(bR0)![i]!;
-            const baseL = targets.get(bL0)![i]!;
-            let lo = -20;
-            let hi = 20;
+            const baseR = wrap(startR0 + alpha * wrap(endR0 - startR0));
+            const baseL = wrap(startL0 + alpha * wrap(endL0 - startL0));
+            let lo = -30;
+            let hi = 30;
+            const dR = (deg: number) => (deg < 0 ? 0.25 * deg : deg);
+            const dL = (deg: number) => (deg > 0 ? 0.25 * deg : deg);
             const evalD = (deg: number) =>
-              sl[1] + lL0 * Math.sin((baseL + deg + dL0) / DEG) - (sr[1] + lR0 * Math.sin((baseR + deg + dR0) / DEG));
+              0.4 * w * (sl[1] - sr[1]) + lL0 * Math.sin((baseL + dL(deg) + dL0) / DEG) - lR0 * Math.sin((baseR + dR(deg) + dR0) / DEG);
             let fLo = evalD(lo);
             for (let it = 0; it < 32; it++) {
               const mid = 0.5 * (lo + hi);
@@ -2284,24 +2364,50 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               } else hi = mid;
             }
             const deg = 0.5 * (lo + hi);
-            targets.get(bR0)![i] = wrap(baseR + deg);
-            targets.get(bL0)![i] = wrap(baseL + deg);
+            const aR0 = wrap(baseR + dR(deg));
+            const aL0 = wrap(baseL + dL(deg));
+            targets.get(bR0)![i] = aR0;
+            targets.get(bL0)![i] = aL0;
+            targets.get(bR1)![i] = wrap(inR1 + 0.45 * wrap(aR0 - drawnR0));
+            targets.get(bL1)![i] = wrap(inL1 + 0.45 * wrap(aL0 - drawnL0));
           }
         }
       }
     }
+    if (set.anchor === undefined && set.symmetric !== true && set.support === undefined && loShow < s.frames[0]) {
+      for (const cn of s.chains) {
+        const c = map.chains.find((x) => x.name === cn);
+        if (!c || c.bones.length < 2) continue;
+        const b1 = c.bones[1]!;
+        const t1 = targets.get(b1)!;
+        const entryWorld1 = t1[s.frames[0]]!;
+        for (let i = loShow; i < s.frames[0]; i++) {
+          t1[i] = entryWorld1;
+        }
+      }
+    }
     if (set.support !== undefined) {
       const prevSw = sIdx > 0 ? sw.switches[sIdx - 1] : undefined;
       const loGap = prevSw !== undefined && s.frames[0] - prevSw.frames[1] <= 10 ? prevSw.frames[1] + 1 : loShow;
       for (const cn of s.chains) {
         const c = map.chains.find((x) => x.name === cn)!;
         if (set.support.includes(c.name)) {
-          for (let i = Math.min(loGap, loShow); i <= hiShow; i++) solveSupportChainFrame(set, c, i);
-          const anchorStart = Math.min(loGap, loShow);
-          if (anchorStart >= 2) {
-            for (const b of c.bones) {
+          for (let i = loShow; i <= hiShow; i++) solveSupportChainFrame(set, c, i);
+          if (loGap < loShow && loGap >= 1) {
+            const i0 = loGap - 1;
+            const i1 = loShow;
+            const steps = i1 - i0;
+            for (let bIdx = 0; bIdx < c.bones.length; bIdx++) {
+              const b = c.bones[bIdx]!;
               const tg = targets.get(b)!;
-              tg[anchorStart - 1] = wrap(tg[anchorStart - 2]! + 0.5 * wrap(tg[anchorStart]! - tg[anchorStart - 2]!));
+              const parentTg = bIdx > 0 ? targets.get(c.bones[bIdx - 1]!) : undefined;
+              const startA = parentTg !== undefined ? wrap(tg[i0]! - parentTg[i0]!) : tg[i0]!;
+              const endA = parentTg !== undefined ? wrap(tg[i1]! - parentTg[i1]!) : tg[i1]!;
+              const total = wrap(endA - startA);
+              for (let k = loGap; k < loShow; k++) {
+                const localA = wrap(startA + ((k - i0) / steps) * total);
+                tg[k] = parentTg !== undefined ? wrap(parentTg[k]! + localA) : localA;
+              }
             }
           }
         } else if (c.bones.length >= 2) {
@@ -2325,6 +2431,18 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               if (i >= s.frames[0] || outSign * wrap(t0[i]! - pair[0]) < 0) t0[i] = pair[0];
               if (i >= s.frames[0] || outSign * wrap(t1[i]! - pair[1]) < 0) t1[i] = pair[1];
             }
+            if (loGap <= loShow && loGap >= 1 && loShow + 1 <= hiShow) {
+              const i0 = loGap - 1;
+              const i1 = loShow + 1;
+              const steps = i1 - i0;
+              const startLocal = wrap(t1[i0]! - t0[i0]!);
+              const endLocal = wrap(t1[i1]! - t0[i1]!);
+              const totalLocal = wrap(endLocal - startLocal);
+              for (let k = loGap; k <= loShow; k++) {
+                const localA = wrap(startLocal + ((k - i0) / steps) * totalLocal);
+                t1[k] = wrap(t0[k]! + localA);
+              }
+            }
           }
         }
       }
@@ -2350,9 +2468,11 @@ 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) {
+  // #190 / #205: when the neck-length clamp acts on the sequence, couple the clamped
+  // head.translate.y (`clampedY`, the signal the gains were calibrated against) into
+  // head.rotate (+NOD_RESIDUAL_HEAD_GAIN °/unit) and pitch_dial.rotate (+NOD_RESIDUAL_PITCH_GAIN °/unit).
+  const nodCoupled = headNodReading !== null && headNodReading.residual.some((r) => r !== 0) ? headNodReading.clampedY : null;
+  if (headNodReading !== null && nodCoupled !== null) {
     const hb = headNodReading.bone;
     const tg = targets.get(hb);
     if (tg !== undefined) {
@@ -2361,9 +2481,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       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);
+        const nodY = nodCoupled[i]!;
+        if (nodY === 0) continue;
+        let next = wrap(tg[i]! + NOD_RESIDUAL_HEAD_GAIN * nodY);
         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) {
@@ -2410,7 +2530,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, headNodReading?.residual ?? null, NOD_RESIDUAL_PITCH_GAIN);
+    face = readFace(map.face, series.get('nose')!, series.get('r_eye')!, series.get('l_eye')!, rEar, lEar, nodCoupled, NOD_RESIDUAL_PITCH_GAIN);
     for (const axis of ['yaw', 'pitch'] as const) {
       const ax = face[axis];
       if (ax === undefined) continue;

package/src/run.ts

@@ -4,9 +4,10 @@
  * measure where the rig landed, read the folds (and which no switch covers),
  * and write — only when every check passed.
  */
-import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
@@ -19,6 +20,7 @@ import { landed, measureFeet, measureLanding, measurePosture, measureShear, pose
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, smoothTrunk, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
 import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
 import { bodyLine, faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -82,6 +84,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   }
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
+  const rigSnapshot = readReportInput(input.rig);
   const base = baseMotionOf(input);
   const animations = base.animations as Record<string, unknown>;
   if (a.name in animations) refuse([{ code: 'MOTION_NAME_FREE', text: `the rig's motion spec already has an animation "${a.name}" (it has ${Object.keys(animations).join(', ')}); name this one with --name` }]);
@@ -90,8 +93,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     refuse([{ code: 'IDLE_NAME', text: `${a.idle !== undefined ? `--idle "${idleName}"` : '--carry-idle reads the animation "idle", and'} the rig's motion spec ${input.motion === null ? '— there is none, so it has no animations' : `${input.motion} has no animation "${idleName}" (it has ${Object.keys(animations).join(', ') || 'none'})`}; name the rig's idle with --idle` }]);
   }
   const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
-  const map = readMap(readFileSync(a.map, 'utf8'), a.map);
-  const poseText = readFileSync(a.pose, 'utf8');
+  const mapSnapshot = readReportInput(a.map), poseSnapshot = readReportInput(a.pose);
+  const map = readMap(mapSnapshot.bytes.toString('utf8'), a.map);
+  const poseText = poseSnapshot.bytes.toString('utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
   if (seq.cleaned === undefined) refuse([{ code: 'POSE_NOT_CLEANED', text: notCleaned(a.pose, a.coco) }]);
   const frames = personTrack(seq, a.person, a.pose);
@@ -305,48 +309,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const u of uncovered) say(`  UNCOVERED mesh "${u.attachment}" (slot "${u.slot}"; chains ${u.chains.length === 0 ? 'none' : u.chains.join(', ')}) folds with no switch covering it on ${u.times.length} frame(s): t=${spans(u.times, 1 / fps)}`);
     }
 
-    if (a.build !== undefined) {
-      // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
-      rmSync(a.build, { recursive: true, force: true });
-      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
-      if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
-    }
-    writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
-    if (a.camera !== undefined) {
-      const ss = r.figureScale.frames.map((x) => x.s);
-      const minS = ss.length === 0 ? 1 : Math.min(...ss);
-      const maxS = ss.length === 0 ? 1 : Math.max(...ss);
-      writeFileSync(a.camera, `${JSON.stringify({
-        spec: 'rig-pose-camera/1',
-        rig: input.name,
-        animation: a.name,
-        frames: r.figureScale.frames.map((f, i) => {
-          const cam = seq.camera?.[i];
-          const camS = cam?.s ?? 1;
-          return {
-            frame: f.frame,
-            t: f.t,
-            s: f.s,
-            rawS: f.rawS,
-            tx: cam?.tx ?? 0,
-            ty: cam?.ty ?? 0,
-            videoS: Number((f.s * camS).toFixed(6)),
-          };
-        }),
-        summary: {
-          minS,
-          maxS,
-          maxStep: r.figureScale.maxStep,
-          endOverStart: r.figureScale.endOverStart,
-        },
-      }, null, 2)}\n`);
-    }
-    if (a.render !== undefined && f.meshes !== null && f.frames !== '') {
-      rmSync(a.render, { recursive: true, force: true });
-      cpSync(f.frames, a.render, { recursive: true });
-    }
-    if (a.report !== undefined) {
-      writeFileSync(a.report, `${JSON.stringify({
+    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    const reportText = a.report === undefined ? null : writeReport({
         spec: 'rig-pose-report/1',
         rigc,
         rig: input.name,
@@ -403,8 +367,51 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
         reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows },
+      }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : null, {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
+    if (a.build !== undefined) {
+      // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
+      rmSync(a.build, { recursive: true, force: true });
+      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
+      if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
+    }
+    // The kept build reads the rig again; its bytes must still match the report.
+    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
+    if (a.camera !== undefined) {
+      const ss = r.figureScale.frames.map((x) => x.s);
+      const minS = ss.length === 0 ? 1 : Math.min(...ss);
+      const maxS = ss.length === 0 ? 1 : Math.max(...ss);
+      writeFileSync(a.camera, `${JSON.stringify({
+        spec: 'rig-pose-camera/1',
+        rig: input.name,
+        animation: a.name,
+        frames: r.figureScale.frames.map((f, i) => {
+          const cam = seq.camera?.[i];
+          const camS = cam?.s ?? 1;
+          return {
+            frame: f.frame,
+            t: f.t,
+            s: f.s,
+            rawS: f.rawS,
+            tx: cam?.tx ?? 0,
+            ty: cam?.ty ?? 0,
+            videoS: Number((f.s * camS).toFixed(6)),
+          };
+        }),
+        summary: {
+          minS,
+          maxS,
+          maxStep: r.figureScale.maxStep,
+          endOverStart: r.figureScale.endOverStart,
+        },
       }, null, 2)}\n`);
     }
+    if (a.render !== undefined && f.meshes !== null && f.frames !== '') {
+      rmSync(a.render, { recursive: true, force: true });
+      cpSync(f.frames, a.render, { recursive: true });
+    }
+    if (a.report !== undefined && reportText !== null) writeFileSync(a.report, reportText);
+
     if (a.camera !== undefined) say(`  wrote ${a.camera} — camera track (${r.figureScale.frames.length} frames)`);
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
     return { lines, written: true };
@@ -794,3 +801,14 @@ export function notCleaned(pose: string, coco: boolean): string {
   const what = coco ? `${pose} is COCO-17 (--coco), which carries no "cleaned" record` : `${pose} has no "cleaned" record`;
   return `${what}; retarget reads a sequence rig-pose clean wrote (spikes, occlusion, smoothing; there is no flag to skip it). Run \`rig-pose clean ${coco ? '--coco ' : ''}--pose ${pose} --out ${out}\` (add --loop for one cycle of a gait) and retarget --pose ${out}`;
 }
+
+/** File-bound identities are assembled only in this existing IO boundary. */
+export interface ReportInputSnapshot {file:string;bytes:Buffer;identity:ReportInput;size:number;mtimeMs:number}
+export function readReportInput(file:string):ReportInputSnapshot {
+  const path=realpathSync(resolve(file)),before=statSync(path),bytes=readFileSync(path),after=statSync(path);
+  if(!before.isFile()||before.size!==after.size||before.mtimeMs!==after.mtimeMs)throw new Refusal([{code:'REPORT_INPUTS',text:`${file}: input changed while reading; expected one stable regular file`}]);
+  return {file:resolve(file),bytes,identity:{path:relative(process.cwd(),path).split('\\').join('/'),sha256:createHash('sha256').update(bytes).digest('hex')},size:after.size,mtimeMs:after.mtimeMs};
+}
+export function assertReportInputs(inputs:readonly ReportInputSnapshot[]):void {
+  for(const expected of inputs){const current=readReportInput(expected.file);if(current.identity.path!==expected.identity.path||current.identity.sha256!==expected.identity.sha256)throw new Refusal([{code:'REPORT_INPUTS_CHANGED',text:`${expected.identity.path}: consumed input changed before output writes; expected SHA-256 ${expected.identity.sha256}, found ${current.identity.sha256}`}]);}
+}

package/src/switch.ts

@@ -787,14 +787,14 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
         }
         const tight0 = isTightSet(set0, cn);
         const tight1 = isTightSet(set1, cn);
-        if (tight0 && set0 !== set1) {
+        if (tight0 && set0 !== set1 && g1 - g0 + 1 <= 10) {
           let i = g0;
           while (i <= g1 && rawChainMax(set0, cn, i) <= opts.switchTolerance + hyst) {
             cClamp.get(cn)![i] = set0;
             i++;
           }
         }
-        if (tight1 && set0 !== set1) {
+        if (tight1 && set0 !== set1 && g1 - g0 + 1 <= 10) {
           let enter1 = g1 + 1;
           for (let i = g0; i <= g1; i++) {
             if (rawChainMax(set1, cn, i) <= opts.switchTolerance) {
@@ -809,63 +809,53 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
             if (arr[i] !== null) cClamp.get(cn)![i] = arr[i]!;
           }
         }
-        if (!tight0 && set0 !== set1) {
-          const c = map.chains.find((x) => x.name === cn);
-          if (c !== undefined) {
-            let k = sw0.frames[1];
-            while (
-              k >= sw0.frames[0] &&
-              c.bones.some((b) => {
-                const lim = set0.turn[b];
-                const dr = set0.drawn[b];
-                const ndr = set1.drawn[b];
-                if (lim === undefined || dr === undefined || ndr === undefined) return false;
-                const t = wrap(targets.get(b)![k]! - dr);
-                return overflow(t, lim) > RANGE_SLACK && Math.abs(wrap(targets.get(b)![k + 1]! - ndr)) < Math.abs(wrap(targets.get(b)![k]! - ndr));
-              })
-            ) {
-              cClamp.get(cn)![k] = null;
-              k--;
-            }
-          }
-        }
         cPick.set(cn, arr);
       }
-      // #187 Rule 1 & Rule 2: when two gesture sets are adjacent (gap <= 10 frames, or the arm is moving
-      // toward the next set's pose), unwrap any bone that turned the long way (> 180° through inverted angles)
-      // onto the short arc and pick one shared switch frame t_switch where the measured path crosses halfway
+      // #187 Rule 1 & Rule 2 / #206: when two gesture sets are adjacent (gap <= 10 frames),
+      // unwrap any bone that turned the long way (> 180° through inverted angles in its own joint
+      // space — world angle for a chain's root bone, parent-local angle for a child bone) onto the
+      // short arc and pick one shared switch frame t_switch where the measured path crosses halfway
       // between set0.drawn and set1.drawn.
-      const movingTowardNext =
-        set0 !== set1 &&
-        distances.get(set1.name)![g1]! < distances.get(set1.name)![g0]! &&
-        distances.get(set0.name)![g1]! > distances.get(set0.name)![g0]!;
-      const bridgeDirect = set0 !== set1 && (g1 - g0 + 1 <= 10 || movingTowardNext);
+      const bridgeDirect = set0 !== set1 && g1 - g0 + 1 <= 10;
       let tSwitch = g1 + 1;
       if (bridgeDirect && switchingChains.length > 0) {
-        const swBones = switchingChains.flatMap((cn) => map.chains.find((c) => c.name === cn)?.bones ?? []);
-        for (const b of swBones) {
-          const tg = targets.get(b) as number[] | undefined;
-          const d0 = set0.drawn[b];
-          const d1 = set1.drawn[b];
-          if (tg === undefined || d0 === undefined || d1 === undefined) continue;
-          const i0 = sw0.frames[1];
-          const i1 = sw1.frames[0];
-          const startA = tg[i0]!;
-          const endA = tg[i1]!;
-          const unwrapped: number[] = [startA];
-          for (let i = i0 + 1; i <= i1; i++) {
-            unwrapped.push(unwrapped[unwrapped.length - 1]! + wrap(tg[i]! - tg[i - 1]!));
-          }
-          const totalTurn = unwrapped[unwrapped.length - 1]! - startA;
-          const shortTurn = wrap(endA - startA);
-          const invertsBetween = Array.from({ length: g1 - g0 + 1 }, (_, k) => {
-            const a = tg[g0 + k]!;
-            return Math.abs(wrap(a - d0)) > 90 && Math.abs(wrap(a - d1)) > 90;
-          }).some(Boolean);
-          if (Math.abs(totalTurn) > 180 && Math.abs(totalTurn - shortTurn) > 1e-6 && invertsBetween && Math.abs(shortTurn) <= 150) {
-            for (let i = g0; i <= g1; i++) {
-              const p = (unwrapped[i - i0]! - startA) / totalTurn;
-              tg[i] = wrap(startA + p * shortTurn);
+        for (const cn of switchingChains) {
+          const ch = map.chains.find((c) => c.name === cn);
+          if (!ch) continue;
+          for (let bIdx = 0; bIdx < ch.bones.length; bIdx++) {
+            const b = ch.bones[bIdx]!;
+            const parentBone = bIdx > 0 ? ch.bones[bIdx - 1] : undefined;
+            const tg = targets.get(b) as number[] | undefined;
+            const parentTg = parentBone !== undefined ? targets.get(parentBone) : undefined;
+            const d0World = set0.drawn[b];
+            const d1World = set1.drawn[b];
+            if (tg === undefined || d0World === undefined || d1World === undefined) continue;
+            const pd0 = parentBone !== undefined ? set0.drawn[parentBone] : undefined;
+            const pd1 = parentBone !== undefined ? set1.drawn[parentBone] : undefined;
+            const jointAngle = (i: number): number =>
+              parentTg !== undefined ? wrap(tg[i]! - parentTg[i]!) : tg[i]!;
+            const d0 = pd0 !== undefined ? wrap(d0World - pd0) : d0World;
+            const d1 = pd1 !== undefined ? wrap(d1World - pd1) : d1World;
+            const i0 = sw0.frames[1];
+            const i1 = sw1.frames[0];
+            const startA = jointAngle(i0);
+            const endA = jointAngle(i1);
+            const unwrapped: number[] = [startA];
+            for (let i = i0 + 1; i <= i1; i++) {
+              unwrapped.push(unwrapped[unwrapped.length - 1]! + wrap(jointAngle(i) - jointAngle(i - 1)));
+            }
+            const totalTurn = unwrapped[unwrapped.length - 1]! - startA;
+            const shortTurn = wrap(endA - startA);
+            const invertsBetween = Array.from({ length: g1 - g0 + 1 }, (_, k) => {
+              const a = jointAngle(g0 + k);
+              return Math.abs(wrap(a - d0)) > 90 && Math.abs(wrap(a - d1)) > 90;
+            }).some(Boolean);
+            if (Math.abs(totalTurn) > 180 && Math.abs(totalTurn - shortTurn) > 1e-6 && invertsBetween && Math.abs(shortTurn) <= 150) {
+              for (let i = g0; i <= g1; i++) {
+                const p = (unwrapped[i - i0]! - startA) / totalTurn;
+                const localA = wrap(startA + p * shortTurn);
+                tg[i] = parentTg !== undefined ? wrap(parentTg[i]! + localA) : localA;
+              }
             }
           }
         }
@@ -904,7 +894,8 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
             ? pairs.reduce((s, b) => s + Math.abs(wrap(effAngle(b, i) - set1.drawn[b]!)), 0) / pairs.length
             : (distances.get(set1.name)?.[i] ?? Infinity);
           const rootsCrossed =
-            activeSwChains.length === switchingChains.length ||
+            switchingChains.length === 1 ||
+            rootBones.length === 0 ||
             rootBones.every((b) => Math.abs(wrap(effAngle(b, i) - set1.drawn[b]!)) <= Math.abs(wrap(effAngle(b, i) - set0.drawn[b]!)));
           if ((d1 <= d0 || (span > 1e-6 && d0 >= 0.5 * span)) && rootsCrossed) {
             tSwitch = i;
@@ -912,6 +903,9 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
           }
         }
       }
+      const syncBridgeClamp = (cn: string, i: number, picked: AlternateSet) => {
+        if (isTightSet(picked, cn)) cClamp.get(cn)![i] = picked;
+      };
       const anyHeldBehind = switchingChains.some((cn) => {
         const arr = cPick.get(cn)!;
         for (let i = g0; i <= g1; i++) if (arr[i] === null) return false;
@@ -924,7 +918,11 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
         });
         if (bridgeDirect) {
           for (const cn of switchingChains) {
-            for (let i = g0; i <= g1; i++) cPick.get(cn)![i] = i < tSwitch ? set0 : set1;
+            for (let i = g0; i <= g1; i++) {
+              const picked = i < tSwitch ? set0 : set1;
+              cPick.get(cn)![i] = picked;
+              syncBridgeClamp(cn, i, picked);
+            }
           }
         } else if (!frontNear) for (const cn of chains) for (let i = g0; i <= g1; i++) cPick.get(cn)![i] = set0;
       } else {
@@ -980,7 +978,11 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
         }
         if (bridgeDirect) {
           for (const cn of switchingChains) {
-            for (let i = g0; i <= g1; i++) cPick.get(cn)![i] = i < tSwitch ? set0 : set1;
+            for (let i = g0; i <= g1; i++) {
+              const picked = i < tSwitch ? set0 : set1;
+              cPick.get(cn)![i] = picked;
+              syncBridgeClamp(cn, i, picked);
+            }
           }
         }
       }
@@ -1224,7 +1226,7 @@ export const ART_EASE_STEP = 3;
 export function clampArt(switches: readonly Switch[], map: JointMap, targets: Map<string, number[]>, chainHolds?: ReadonlyArray<{ set: string; chain: string; frames: [number, number] }>): void {
   const boneChain = new Map<string, string>();
   for (const c of map.chains) for (const b of c.bones) boneChain.set(b, c.name);
-  const clampSpan = (set: AlternateSet, bone: string, [a, b0]: [number, number]) => {
+  const clampSpan = (set: AlternateSet, bone: string, [a, b]: [number, number]) => {
     const limits = set.turn[bone];
     if (limits === undefined) return;
     const drawn = set.drawn[bone]!;
@@ -1236,28 +1238,14 @@ export function clampArt(switches: readonly Switch[], map: JointMap, targets: Ma
       return Math.abs(c - t) > RANGE_SLACK ? c - t : 0;
     };
     const tightHold = limits[1] - limits[0] <= 10;
-    let b = b0;
-    let trimmedExit = false;
-    if (!tightHold && b + 1 < n && delta(b) !== 0) {
-      const nextSw = switches.find((s) => s.frames[0] > b && s.frames[0] - b <= 10 && s.set !== set.name);
-      const nextDrawn = nextSw !== undefined ? map.alternates.find((x) => x.name === nextSw.set)?.drawn[bone] : undefined;
-      if (nextDrawn !== undefined) {
-        const distNext = (i: number) => Math.abs(wrap(target[i]! - nextDrawn));
-        if (distNext(b + 1) < distNext(b)) {
-          while (b >= a && delta(b) !== 0 && (b === a || distNext(b) < distNext(b - 1))) {
-            b--;
-            trimmedExit = true;
-          }
-        }
-      }
-    }
-    if (a > b) return;
+    const prevNearSw = switches.some((s) => s.frames[1] < a && a - s.frames[1] <= 11);
+    const nextNearSw = switches.some((s) => s.frames[0] > b && s.frames[0] - b <= 11);
     const da = delta(a);
     const db = delta(b);
-    const easeIn = a > 0 && da !== 0 && Math.sign(delta(a - 1)) === Math.sign(da) && !tightHold
+    const easeIn = a > 0 && da !== 0 && Math.sign(delta(a - 1)) === Math.sign(da) && !(tightHold && prevNearSw)
       ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(da) / ART_EASE_STEP) - 1)
       : 0;
-    const easeOut = b + 1 < n && db !== 0 && Math.sign(delta(b + 1)) === Math.sign(db) && !tightHold && !trimmedExit
+    const easeOut = b + 1 < n && db !== 0 && Math.sign(delta(b + 1)) === Math.sign(db) && !(tightHold && nextNearSw)
       ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(db) / ART_EASE_STEP) - 1)
       : 0;
     for (let i = a; i <= b; i++) {