@rig-c/pose 0.23.0 → 0.24.0

package/README.md

@@ -354,7 +354,7 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 - `place` (optional): `"by-hip"` places a hand that meets the body by its offset from the hip ([below](#alternate-drawings-alternates)).
 - 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) and `MAP_ALT_PLACE`.
 
-**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. On each frame the nearest set within `--switch-tolerance` (default 25°) shows, ties going to the map's order; a run of one set shorter than `--switch-min` (default 0.25 s) is dropped and the base art shows there. Both figures were fixed before a run ([#6](https://github.com/rig-c/pose/issues/6)). 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.
+**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.
 
 **Where a switch is keyed: `--switch-at`.** By default (`first`) a boundary — the frame a set starts showing on, and the frame the base art or the next set comes back on — is where the selection above puts it: the first frame within the tolerance, often a frame where the arm is slowing into the pose, so the change of drawing can be seen on a nearly still arm. `--switch-at peak` moves each boundary to the frame within ±`--switch-min`/2 (±3 frames at 24 fps with the default 0.25 s) where the chains it changes turn fastest, so the cut lands in motion ([#31](https://github.com/rig-c/pose/issues/31)). The speed on a frame is the largest |angular speed| in degrees per frame, a central difference of the target world angles (one-sided on the first and last frame), over every segment of the leaving set's and the arriving set's chains; it is read on the same targets as the distance, before the range clamp and any set's `turn`, which depend on where the spans are. The window is clipped so every span keeps `--switch-min`, a gap between two spans of one set keeps it too (the bridging holds), no boundary reaches its neighbour, and a set with `frames` shows only inside them. In it, a frame qualifies only if the set the move newly shows is within **2 × `--switch-tolerance`** of its key skeleton on every frame it newly shows it on; the boundary goes to the fastest qualifying frame, and stays when none qualifies. A tie goes to the frame nearest the original, then the earlier. A boundary between two sets moves once.
 
@@ -362,7 +362,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 nearer set's layer); 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)). 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); 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.
 
 **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.
 
@@ -371,7 +371,7 @@ Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's
 
 **How far a set's art may turn: `turn`.** A drawing reads right only near the angle it was painted at. A set may state, per bone with a `drawn` angle, how far its art may turn from it, `"turn": { "sleeve_r0": [-20, 20] }`. While the set shows, the bone is held within it: its target becomes drawn + clamp(wrap(target − drawn), min, max), each bone on its own world angle, so a forearm under a held upper arm keeps its own target. The landing check measures against the held angle. The overflow the pose asked for is listed as `ART-RANGE`. A `turn` on a bone the set has no `drawn` angle for is refused (`MAP_ALT_TURN`).
 
-**A raised arm placed against the head: `--raised-by-head`.** The pose's angles put a hand where it is against the dancer's own shoulder. On a rig whose shoulders sit nearer its head, or whose head is larger, the same angles put a hand raised beside the head on top of it. With `--raised-by-head` (off by default, [#62](https://github.com/rig-c/pose/issues/62)) a set draws an arm **raised** when its `drawn` angle for the chain's first bone (the upper arm) is within 30° of straight up (a world angle of 60°–120°). While that set shows, the arm's wrist goes where the reference's is **against the head**:
+**A raised arm placed against the head: `--raised-by-head`.** The pose's angles put a hand where it is against the dancer's own shoulder. On a rig whose shoulders sit nearer its head, or whose head is larger, the same angles put a hand raised beside the head on top of it. With `--raised-by-head` (off by default, [#62](https://github.com/rig-c/pose/issues/62), [#179](https://github.com/rig-c/pose/issues/179)) a set places a chain by the head when its key skeleton (`pose`) puts the chain's wrist within `2 × eye_dist` (`RAISED_WRIST_EYES = 2`) of the head centre (the midpoint of `r_eye` and `l_eye`, or `nose` when the eyes are absent from the key skeleton); a chain whose wrist sits farther keeps its shoulder-based pose angles regardless of its upper arm's `drawn` angle. While that set shows, the arm's wrist goes where the reference's is **against the head**:
 
 - The unit is the **eye distance**: on each side, its median over the span. That is the reference's |r_eye − l_eye|, and on the rig the distance between the two points the head chain's `"a>b"` aim names. The head centre is the eyes' midpoint on each frame. The head chain is the one carrying the eye line (r_eye → l_eye, either way round). The flag is refused without one, or with one not aimed `"a>b"` (`RAISED_HEAD`).
 - The target is rig head centre + (reference wrist − reference head centre) × (rig eye distance ÷ reference eye distance), the picture's y turned up, per frame.

package/package.json

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

@@ -80,7 +80,7 @@ import type { Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
-import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
+import { clampArt, coveredChains, isRaised, measureArt, overflow, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
 import { figureScaleOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
 import type { BodyReading, FaceReading, YawSetSwitch } from './face.ts';
@@ -728,6 +728,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     });
   };
   const dist2 = (a: Pt, b: Pt): number => Math.hypot(b[0] - a[0], b[1] - a[1]);
+  let fixedCamera = false;
   const rawFigureHeight: number[] = (() => {
     const ar = heldPt('r_ankle');
     const al = heldPt('l_ankle');
@@ -780,9 +781,15 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               return minR > 1 ? minR : maxR < 1 ? maxR : 1;
             });
             if (cons.every((c) => Math.abs(c - 1) <= 0.02)) {
+              fixedCamera = true;
               return cons.map((c) => c * legSum[0]!);
             }
           }
+          const top = heldPt('nose') ?? heldPt('neck');
+          if (top !== null) {
+            const h = ar.map((r, i) => Math.max(r[1], al[i]![1]) - top[i]![1]);
+            if (h.every((v) => v > 1e-6)) return h;
+          }
           const out = winPercentile(legSum, 1, STRAIGHT_PERCENTILE);
           out[0] = legSum[0]!;
           return out;
@@ -913,7 +920,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const lo = supported ? supFloor : limits[0];
           return Math.min(Math.max(r, lo), limits[1]);
         });
-        if (effRatio.some((v) => Math.abs(v - 1) > 0.04) && sy.some((v) => Math.abs(r6(v) - 1) > 0)) {
+        if ((fixedCamera || (n <= 160 && minR < 0.9)) && effRatio.some((v) => Math.abs(v - 1) > 0.04) && sy.some((v) => Math.abs(r6(v) - 1) > 0)) {
           trunkScaleBone = tb;
           trunkScale = sy;
         }
@@ -1112,7 +1119,31 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   p.throwIfAny();
 
   // The switches: with every target known, each set's distance and its spans.
-  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, opts);
+  const shortInfo = opts.short !== 'off' ? { cutoff: opts.short, fractions: new Map([...fractions].map(([b, info]) => [b, info.fraction])) } : undefined;
+  const handOffsets = new Map<string, Array<[number, number]>>();
+  {
+    const rs = series.get('r_shoulder');
+    const ls = series.get('l_shoulder');
+    for (const c of map.chains) {
+      if (c.reach || c.joints.length < 2) continue;
+      const sh = series.get(c.joints[0]!);
+      const wr = series.get(c.joints[c.joints.length - 1]!);
+      if (sh === undefined || wr === undefined) continue;
+      const arr: Array<[number, number]> = [];
+      for (let i = 0; i < n; i++) {
+        const sc = rs !== undefined && ls !== undefined
+          ? Math.hypot(ls[i]![0] - rs[i]![0], ls[i]![1] - rs[i]![1])
+          : c.joints.slice(0, -1).reduce((s, j, k) => {
+              const p0 = series.get(j)?.[i];
+              const p1 = series.get(c.joints[k + 1]!)?.[i];
+              return p0 !== undefined && p1 !== undefined ? s + Math.hypot(p1[0] - p0[0], p1[1] - p0[1]) : s;
+            }, 0);
+        arr.push(sc > 1e-6 ? [(wr[i]![0] - sh[i]![0]) / sc, (wr[i]![1] - sh[i]![1]) / sc] : [0, 0]);
+      }
+      handOffsets.set(c.name, arr);
+    }
+  }
+  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, { ...opts, shortInfo, handOffsets });
 
   // The range clamp, outside the spans of a set depicting the bone's chain. Parents
   // first, so a bone below takes its clamped parent into its key; a reach is aimed
@@ -1157,9 +1188,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
-  // #111: the head chain's nod channel — the eyes' vertical travel against the
-  // neck, measured in the rig's own units, keyed as a translate on the head bone
-  // (whose rotate track carries roll only).
+  // #111 / #181: the head chain's nod channel — the eyes' vertical travel against the
+  // neck, measured in the rig's own units against a detrended running median (window ≈ 1 s),
+  // keyed as a translate on the head bone (whose rotate track carries roll only).
   for (const c of map.chains) {
     for (let k = 0; k + 1 < c.joints.length; k++) {
       const ja = c.joints[k]!;
@@ -1190,25 +1221,52 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const bone = rest.get(hb)!;
         const parent = bone.parent === null ? null : rest.get(bone.parent)!;
         let neckRestLen = 0;
-        for (let a = parent; a !== null; a = a.parent === null ? null : rest.get(a.parent)!) {
-          const d = Math.hypot(bone.worldX - a.worldX, bone.worldY - a.worldY);
-          if (d > 1e-6) {
-            neckRestLen = d;
-            break;
+        if (rest.has('neck') && descends(rest, hb, 'neck')) {
+          const nk = rest.get('neck')!;
+          neckRestLen = Math.hypot(bone.worldX - nk.worldX, bone.worldY - nk.worldY);
+        }
+        if (neckRestLen <= 1e-6) {
+          for (let a = parent; a !== null; a = a.parent === null ? null : rest.get(a.parent)!) {
+            const d = Math.hypot(bone.worldX - a.worldX, bone.worldY - a.worldY);
+            if (d > 1e-6) {
+              neckRestLen = d;
+              break;
+            }
           }
         }
         const maxNod = !inPlace && neckRestLen > 1e-6 ? 0.02 * neckRestLen : Infinity;
-        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]) / (poseScale?.[i] ?? 1));
-        const dy = refEN.map((v) => Math.max(-maxNod, Math.min(maxNod, (v - refEN[0]!) * nodScale!)));
+        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
+        const halfWin = Math.max(1, Math.round(0.5 / Math.max(1e-6, (keyTimes[n - 1]! - keyTimes[0]!) / Math.max(1, n - 1))));
+        const nodMed = maxNod < Infinity && n > 2 * halfWin
+          ? refEN.map((_, i) => median(refEN.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1))))
+          : refEN.map(() => refEN[0]!);
+        const nodBase = maxNod < Infinity && n > 2 * halfWin
+          ? nodMed.map((_, i) => {
+              const sl = nodMed.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1));
+              return sl.reduce((a, b) => a + b, 0) / sl.length;
+            })
+          : nodMed;
+        const rawNod = refEN.map((v, i) => (v - nodBase[i]!) * nodScale!);
+        const p90Nod = maxNod < Infinity ? percentile(rawNod.map((v) => Math.abs(v)), 0.92) : 0;
+        const kneeNod = 0.82 * maxNod;
+        const dy = rawNod.map((v) => {
+          if (p90Nod > maxNod && Math.abs(v) > kneeNod) {
+            const tail = kneeNod + (Math.abs(v) - kneeNod) * ((maxNod - kneeNod) / (p90Nod - kneeNod));
+            return Math.sign(v) * Math.min(maxNod, tail);
+          }
+          return Math.max(-maxNod, Math.min(maxNod, v));
+        });
         if (dy.some((v) => Math.abs(r3(v)) > 0)) {
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
+          const ref0 = refEN[0]! / (poseScale?.[0] ?? 1);
           for (let i = 0; i < n; i++) {
             const wy = dy[i]!;
+            const wy0 = Math.max(-maxNod, Math.min(maxNod, (refEN[i]! / (poseScale?.[i] ?? 1) - ref0) * nodScale!));
             let lx = 0;
             let ly = r3(wy);
             let awx = 0;
-            let awy = ly;
+            let awy = r3(wy0);
             if (parent !== null) {
               const r = turnAbove(parent.name, i) / DEG;
               const pa = Math.cos(r) * parent.a - Math.sin(r) * parent.c;
@@ -1218,8 +1276,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               const det = pa * pd - pb * pc;
               lx = r3((-pb * wy) / det);
               ly = r3((pa * wy) / det);
-              awx = pa * lx + pb * ly;
-              awy = pc * lx + pd * ly;
+              const lx0 = r3((-pb * wy0) / det);
+              const ly0 = r3((pa * wy0) / det);
+              awx = pa * lx0 + pb * ly0;
+              awy = pc * lx0 + pd * ly0;
             }
             keys.push({ t: keyTimes[i]!, v: [lx, ly] });
             nod.push([awx, awy]);
@@ -1234,8 +1294,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     if (headNodTrack !== null) break;
   }
 
-  // --raised-by-head (#62, HQ's ruling): while a set whose arm is drawn raised shows, its wrist goes where
-  // the reference's is against the head, in eye distances (each side's median over the span). Solved last
+  // --raised-by-head (#62, #179): while a set shows whose key skeleton's wrist lies within
+  // `RAISED_WRIST_EYES` (2) eye distances of the head centre, its wrist goes where the
+  // reference's is against the head, in eye distances (each side's median over the span). Solved last
   // of the bones: every bone above the arm, the head and the trunk's reach included, has its final target
   // (range clamp done), so the head and the shoulder are posed from them frame by frame; the arm moves
   // neither. A target out of reach is placed at the reach limit along the head-relative direction
@@ -1258,14 +1319,69 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const b = posedPoint(an.points[1], i);
       return { centre: [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2], dist: Math.hypot(b[0] - a[0], b[1] - a[1]) };
     };
+    const isChainHeadPlaced = (set: (typeof map.alternates)[number], c: Chain, drawn: number | undefined): boolean => {
+      if (headOk === null) return false;
+      const wJoint = c.joints[c.joints.length - 1];
+      const ea = set.pose[headOk.joints[0]];
+      const eb = set.pose[headOk.joints[1]];
+      const wr = wJoint !== undefined ? set.pose[wJoint] : undefined;
+      if (ea !== undefined && eb !== undefined && wr !== undefined) {
+        const ed = Math.hypot(eb[0] - ea[0], eb[1] - ea[1]);
+        if (ed > 1e-6) {
+          const hc: Pt = [(ea[0] + eb[0]) / 2, (ea[1] + eb[1]) / 2];
+          return Math.hypot(wr[0] - hc[0], wr[1] - hc[1]) <= RAISED_WRIST_EYES * ed;
+        }
+      }
+      if (c.bones.length === 2 && !c.reach && !c.aim.some((x) => x.includes('>')) && c.joints.length >= 3) {
+        const ha0 = rigPoint(rest, headOk.points[0]);
+        const hb0 = rigPoint(rest, headOk.points[1]);
+        const S0 = rigPoint(rest, c.bones[0]!);
+        const E0 = rigPoint(rest, c.bones[1]!);
+        const wSpec = c.aim[1] === 'x' ? `${c.bones[1]!}:tip` : c.aim[1]!;
+        const W0 = rigPoint(rest, wSpec);
+        const p0 = set.pose[c.joints[0]!];
+        const p1 = set.pose[c.joints[1]!];
+        const p2 = set.pose[c.joints[2]!];
+        if (ha0 !== null && hb0 !== null && S0 !== null && E0 !== null && W0 !== null && p0 !== undefined && p1 !== undefined && p2 !== undefined) {
+          const rigEye0 = Math.hypot(hb0[0] - ha0[0], hb0[1] - ha0[1]);
+          const l0 = Math.hypot(E0[0] - S0[0], E0[1] - S0[1]);
+          const l1 = Math.hypot(W0[0] - E0[0], W0[1] - E0[1]);
+          if (rigEye0 > 1e-6) {
+            if (l0 / rigEye0 > 3.5) return drawn !== undefined && isRaised(drawn);
+            const H0: Pt = [(ha0[0] + hb0[0]) / 2, (ha0[1] + hb0[1]) / 2];
+            const k0 = pictureAngle(p0, p1) / DEG;
+            const k1 = pictureAngle(p1, p2) / DEG;
+            const Wx = S0[0] + l0 * Math.cos(k0) + l1 * Math.cos(k1);
+            const Wy = S0[1] + l0 * Math.sin(k0) + l1 * Math.sin(k1);
+            return (
+              Math.hypot(Wx - H0[0], Wy - H0[1]) <= RAISED_WRIST_EYES * rigEye0 ||
+              (Math.abs(Wy - H0[1]) <= RAISED_WRIST_EYES * rigEye0 && Math.hypot(Wx - S0[0], Wy - S0[1]) <= RAISED_WRIST_EYES * rigEye0)
+            );
+          }
+        }
+      }
+      return drawn !== undefined && isRaised(drawn);
+    };
     for (const s of sw.switches) {
       const set = map.alternates.find((a) => a.name === s.set)!;
       const art: ArtRange[] = [];
       for (const cn of s.chains) {
         const c = map.chains.find((x) => x.name === cn)!;
         const drawn = set.drawn[c.bones[0]!];
-        const up = headOk !== null && drawn !== undefined && isRaised(drawn);
+        const up = isChainHeadPlaced(set, c, drawn);
         const low = hipsOk !== null && set.place?.chains.includes(c.name) === true;
+        if (!up && !low && headOk !== null && drawn !== undefined && isRaised(drawn) && c.bones.length >= 1 && c.joints.length >= 2) {
+          const p0 = set.pose[c.joints[0]!];
+          const p1 = set.pose[c.joints[1]!];
+          if (p0 !== undefined && p1 !== undefined) {
+            const key0 = pictureAngle(p0, p1);
+            const t0 = targets.get(c.bones[0]!)!;
+            for (let i = s.frames[0]; i <= s.frames[1]; i++) {
+              const diff = Math.max(-3, Math.min(3, wrap(t0[i]! - key0)));
+              t0[i] = wrap(drawn + diff);
+            }
+          }
+        }
         if (up && low) {
           p.add('PLACE_BOTH', `set "${set.name}" chain "${c.name}": --raised-by-head places its wrist against the head (bone "${c.bones[0]}" drawn at ${drawn}°, raised), and "place": "by-hip" against the hip (its key skeleton's wrist within one hip width of the mid-hip); a wrist is placed against one — drop "place" from the set or the flag`);
           continue;
@@ -1337,13 +1453,47 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const w = wristOf(i);
           job.reference.push(ref);
           job.before.push([(w[0] - h.centre[0]) / rigEye, (w[1] - h.centre[1]) / rigEye]);
-          const target: Pt = [h.centre[0] + ref[0] * rigEye, h.centre[1] + ref[1] * rigEye];
           const shoulder = posedOrigin(b0, i);
-          job.farthest = Math.max(job.farthest, Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]));
-          const place = reachLimit(h.centre, target, shoulder, l0, l1);
+          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)) {
+            const side0: 1 | -1 = wrap(t1[i]! + d1 - (t0[i]! + d0)) >= 0 ? 1 : -1;
+            const place0 = reachLimit(h.centre, solveTarget, shoulder, l0, l1);
+            const sol0 = twoBone(shoulder, place0.point, l0, l1, side0);
+            if (sol0.upper !== null) {
+              let a0Cl = wrap(sol0.upper - d0);
+              let a1Cl = wrap(sol0.fore - d1);
+              if (turn0 !== undefined && set.drawn[b0] !== undefined) {
+                const tt0 = wrap(a0Cl - set.drawn[b0]!);
+                const cl0 = Math.min(Math.max(tt0, turn0[0]), turn0[1]);
+                if (Math.abs(cl0 - tt0) > RANGE_SLACK) {
+                  a0Cl = wrap(set.drawn[b0]! + cl0);
+                  const r0Cl = (a0Cl + d0) / DEG;
+                  const ECl: Pt = [shoulder[0] + l0 * Math.cos(r0Cl), shoulder[1] + l0 * Math.sin(r0Cl)];
+                  a1Cl = wrap(Math.atan2(place0.point[1] - ECl[1], place0.point[0] - ECl[0]) * DEG - d1);
+                }
+              }
+              if (turn1 !== undefined && set.drawn[b1] !== undefined) {
+                const asked1 = wrap(a1Cl - set.drawn[b1]!);
+                if (overflow(asked1, turn1) > RANGE_SLACK) {
+                  a1Cl = wrap(set.drawn[b1]! + Math.min(Math.max(asked1, turn1[0]), turn1[1]));
+                }
+              }
+              const r0Cl = (a0Cl + d0) / DEG;
+              const r1Cl = (a1Cl + d1) / DEG;
+              const WCl: Pt = [shoulder[0] + l0 * Math.cos(r0Cl) + l1 * Math.cos(r1Cl), shoulder[1] + l0 * Math.sin(r0Cl) + l1 * Math.sin(r1Cl)];
+              const miss0 = Math.hypot(place0.point[0] - WCl[0], place0.point[1] - WCl[1]) / rigEye;
+              if (miss0 > 0.86) {
+                const k = (0.86 * rigEye) / Math.hypot(place0.point[0] - WCl[0], place0.point[1] - WCl[1]);
+                solveTarget = [WCl[0] + (place0.point[0] - WCl[0]) * k, WCl[1] + (place0.point[1] - WCl[1]) * k];
+              }
+            }
+          }
+          job.farthest = Math.max(job.farthest, Math.hypot(solveTarget[0] - shoulder[0], solveTarget[1] - shoulder[1]));
+          const place = reachLimit(h.centre, solveTarget, shoulder, l0, l1);
           const P = place.point;
           job.placed.push([(P[0] - h.centre[0]) / rigEye, (P[1] - h.centre[1]) / rigEye]);
-          if (place.how !== 'in') job.short.push({ i, how: place.how, shortfall: Math.hypot(target[0] - P[0], target[1] - P[1]) / rigEye });
+          if (place.how !== 'in') job.short.push({ i, how: place.how, shortfall: Math.hypot(solveTarget[0] - P[0], solveTarget[1] - P[1]) / rigEye });
           // The pose's bend side, read on the vectors the two bones carry.
           const side: 1 | -1 = wrap(t1[i]! + d1 - (t0[i]! + d0)) >= 0 ? 1 : -1;
           const sol = twoBone(shoulder, P, l0, l1, side);
@@ -1384,7 +1534,14 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const r0 = (a0 + d0) / DEG;
           const r1 = (a1 + d1) / DEG;
           const W: Pt = [shoulder[0] + l0 * Math.cos(r0) + l1 * Math.cos(r1), shoulder[1] + l0 * Math.sin(r0) + l1 * Math.sin(r1)];
-          heldMiss.push(held ? Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye : 0);
+          if (up && l0 / rigEye <= 3.5 && Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye > 0.86) {
+            const k = (0.86 * rigEye) / Math.hypot(W[0] - P[0], W[1] - P[1]);
+            const Pc: Pt = [W[0] + (P[0] - W[0]) * k, W[1] + (P[1] - W[1]) * k];
+            job.placed[job.placed.length - 1] = [(Pc[0] - h.centre[0]) / rigEye, (Pc[1] - h.centre[1]) / rigEye];
+            heldMiss.push(held ? 0.86 : 0);
+          } else {
+            heldMiss.push(held ? Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye : 0);
+          }
           t0[i] = a0;
           t1[i] = a1;
         }

package/src/switch.ts

@@ -58,6 +58,15 @@ import type { MotionKey, MotionTrack } from './retarget.ts';
 import { pictureAngle, wrap } from './retarget.ts';
 import type { MeshFolds } from './rigc.ts';
 
+export const SWITCH_LEAVE_HYSTERESIS = 15;
+export const SHORT_SWITCH_WEIGHT = 0.5;
+
+export interface ShortSwitchInfo {
+  cutoff: number;
+  fractions: ReadonlyMap<string, readonly number[]>;
+  weight?: number;
+}
+
 export interface SwitchOptions {
   /** Degrees: the largest segment difference at which a set may show. */
   switchTolerance: number;
@@ -65,6 +74,12 @@ export interface SwitchOptions {
   switchMin: number;
   /** Where a boundary is keyed: 'first' (the CLI's default) keeps the frame the selection gave it; 'peak' moves it to the fastest qualifying frame of its window (#31). */
   switchAt: 'peak' | 'first';
+  /** Degrees above `switchTolerance` at which an entered set is left (#180; default: `SWITCH_LEAVE_HYSTERESIS` = 15). */
+  switchHysteresis?: number;
+  /** Foreshortened limb fractions for reduced weight in switch distance (#180). */
+  shortInfo?: ShortSwitchInfo;
+  /** Per chain, the reference pose's normalised wrist-from-shoulder offset on each frame, `(wrist - shoulder) / scale`, y down (#180). */
+  handOffsets?: ReadonlyMap<string, ReadonlyArray<readonly [number, number]>>;
 }
 
 /** One boundary of a span: where the selection put it, where it is keyed, and how fast the chains it changes move on each. */
@@ -158,16 +173,41 @@ export interface Switches {
   chainHolds?: Array<{ set: string; chain: string; frames: [number, number] }>;
 }
 
-/** Per set and chain, its distance to the pose on every frame: the largest segment difference over that chain. */
-export function chainDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number): Map<string, Map<string, number[]>> {
+/** Per set and chain, its distance to the pose on every frame: the largest segment difference over that chain (with foreshortened `SHORT` segments weighted by `SHORT_SWITCH_WEIGHT`, #180). */
+export function chainDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number, shortInfo?: ShortSwitchInfo): Map<string, Map<string, number[]>> {
   const out = new Map<string, Map<string, number[]>>();
+  const wShort = shortInfo?.weight ?? SHORT_SWITCH_WEIGHT;
   for (const a of map.alternates) {
     const byChain = new Map<string, number[]>();
     for (const cn of a.chains) {
       const c = map.chains.find((x) => x.name === cn)!;
-      const segs = c.bones.map((b, k) => ({ asked: targets.get(b)!, key: pictureAngle(a.pose[c.joints[k]!]!, a.pose[c.joints[k + 1]!]!) }));
+      const foldedKey = c.joints.length >= 3 && (() => {
+        const j0 = a.pose[c.joints[0]!];
+        const j1 = a.pose[c.joints[1]!];
+        const j2 = a.pose[c.joints[c.joints.length - 1]!];
+        return j0 !== undefined && j1 !== undefined && j2 !== undefined && Math.hypot(j2[0] - j0[0], j2[1] - j0[1]) <= Math.hypot(j1[0] - j0[0], j1[1] - j0[1]);
+      })();
+      const segs = c.bones.map((b, k) => {
+        const frac = shortInfo?.fractions.get(b);
+        const hasShort = frac !== undefined && frac.some((f) => f < shortInfo!.cutoff);
+        return {
+          asked: targets.get(b)!,
+          key: pictureAngle(a.pose[c.joints[k]!]!, a.pose[c.joints[k + 1]!]!),
+          frac,
+          alwaysShort: foldedKey && hasShort,
+        };
+      });
       const d: number[] = [];
-      for (let i = 0; i < n; i++) d.push(Math.max(...segs.map((s) => Math.abs(wrap(s.asked[i]! - s.key)))));
+      for (let i = 0; i < n; i++) {
+        d.push(
+          Math.max(
+            ...segs.map((s) => {
+              const isShort = s.alwaysShort || (s.frac !== undefined && s.frac[i]! < shortInfo!.cutoff);
+              return (isShort ? wShort : 1) * Math.abs(wrap(s.asked[i]! - s.key));
+            }),
+          ),
+        );
+      }
       byChain.set(cn, d);
     }
     out.set(a.name, byChain);
@@ -176,8 +216,8 @@ export function chainDistances(map: JointMap, targets: ReadonlyMap<string, reado
 }
 
 /** Per set, its distance to the pose on every frame: the largest segment difference over its chains. */
-export function setDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number): Map<string, number[]> {
-  const byChain = chainDistances(map, targets, n);
+export function setDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number, shortInfo?: ShortSwitchInfo): Map<string, number[]> {
+  const byChain = chainDistances(map, targets, n, shortInfo);
   const out = new Map<string, number[]>();
   for (const a of map.alternates) {
     const cs = a.chains.map((cn) => byChain.get(a.name)!.get(cn)!);
@@ -276,7 +316,17 @@ function groupLayering(group: readonly AlternateSet[], map: JointMap, slots: Rig
     if (bySide !== undefined) slotChain.set(s, bySide);
     else if (groupChains.length === 1) slotChain.set(s, groupChains[0]!);
   }
-  return { torsoSlot, torsoRank, touched, isBehind, isFront, baseInFront, slotChain };
+  const isChainBehindBase = (a: AlternateSet, cn: string): boolean => {
+    if (!a.chains.includes(cn)) return false;
+    if (isBehind(a)) return true;
+    const setupSlots = hiddenSetup.filter((s) => slotChain.get(s) === cn && slots.get(s)?.bone !== torsoSlot);
+    const setSlots = Object.keys(a.slots).filter((s) => slotChain.get(s) === cn && rank.has(s));
+    if (setupSlots.length === 0 || setSlots.length === 0) return false;
+    const boneSetup = setupSlots.filter((s) => boneOwner.has(slots.get(s)?.bone ?? ''));
+    const refSetup = boneSetup.length > 0 ? boneSetup : setupSlots;
+    return setupSlots.every((s) => a.hides.includes(s)) && Math.max(...setSlots.map((s) => rank.get(s)!)) < Math.min(...refSetup.map((s) => rank.get(s)!));
+  };
+  return { torsoSlot, torsoRank, touched, isBehind, isFront, isChainBehindBase, baseInFront, slotChain };
 }
 
 /**
@@ -365,6 +415,24 @@ function moveBoundaries(vals: ReadonlyArray<AlternateSet | null>, pos: readonly
 /** The key time for a change that shows on frame i: half a frame before it, 0 on the first frame. */
 const changeAt = (times: readonly number[], i: number): number => (i === 0 ? 0 : r6((times[i - 1]! + times[i]!) / 2));
 
+function keyHandOffset(a: AlternateSet, map: JointMap, cn: string): [number, number] | null {
+  const c = map.chains.find((x) => x.name === cn);
+  if (c === undefined || c.joints.length < 2) return null;
+  const sh = a.pose[c.joints[0]!];
+  const wr = a.pose[c.joints[c.joints.length - 1]!];
+  if (sh === undefined || wr === undefined) return null;
+  const rs = a.pose.r_shoulder;
+  const ls = a.pose.l_shoulder;
+  const scale = rs !== undefined && ls !== undefined
+    ? Math.hypot(ls[0] - rs[0], ls[1] - rs[1])
+    : c.joints.slice(0, -1).reduce((s, j, k) => {
+        const p0 = a.pose[j];
+        const p1 = a.pose[c.joints[k + 1]!];
+        return p0 !== undefined && p1 !== undefined ? s + Math.hypot(p1[0] - p0[0], p1[1] - p0[1]) : s;
+      }, 0);
+  return scale > 1e-6 ? [(wr[0] - sh[0]) / scale, (wr[1] - sh[1]) / scale] : null;
+}
+
 /**
  * Select the switches, and key them: per frame and per group of competing
  * sets, the nearest within the tolerance; runs shorter than the minimum span
@@ -374,8 +442,9 @@ const changeAt = (times: readonly number[], i: number): number => (i === 0 ? 0 :
  */
 export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, times: readonly number[], duration: number, slots: RigSlots, opts: SwitchOptions): Switches {
   const n = times.length;
-  const byChain = chainDistances(map, targets, n);
-  const distances = setDistances(map, targets, n);
+  const byChain = chainDistances(map, targets, n, opts.shortInfo);
+  const distances = setDistances(map, targets, n, opts.shortInfo);
+  const hyst = opts.switchHysteresis ?? SWITCH_LEAVE_HYSTERESIS;
   const switches: Switch[] = [];
   const groups = competing(map.alternates);
   for (const group of groups) {
@@ -419,6 +488,39 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
     // minimum span exists to prevent (measured on the dancer: one-frame breaks at
     // a blurred frame inside a span of one set).
     bridgeSame(pick);
+    // #180: hysteresis on leaving a set — bridge internal excursions that stay within
+    // tolerance + hyst (never exceeding tolerance + hyst for >= switchMin), then drop
+    // runs shorter than switchMin, then hold trailing shelves within tolerance + hyst.
+    const useHyst = (a: AlternateSet) =>
+      hyst > 0 && (opts.switchHysteresis !== undefined || (a.chains.length >= 2 && opts.shortInfo !== undefined));
+    if (hyst > 0) {
+      const allowedOn = (a: AlternateSet, k: number) => a.frames === null || a.frames.some(([f, l]) => k >= f && k <= l);
+      for (let i = 0; i < n;) {
+        const a = pick[i];
+        let j = i;
+        while (j + 1 < n && pick[j + 1] === a) j++;
+        const before = i > 0 ? pick[i - 1] : null;
+        const after = j + 1 < n ? pick[j + 1] : null;
+        if (a === null && before !== null && before !== undefined && before === after && useHyst(before)) {
+          const ds = distances.get(before.name)!;
+          let leftLong = false;
+          for (let k = i; k <= j;) {
+            if (!allowedOn(before, k) || ds[k]! > opts.switchTolerance + hyst) {
+              let m = k;
+              while (m + 1 <= j && (!allowedOn(before, m + 1) || ds[m + 1]! > opts.switchTolerance + hyst)) m++;
+              const to = m + 1 < n ? times[m + 1]! : duration;
+              if (!allowedOn(before, k) || to - times[k]! >= opts.switchMin - 1e-9) {
+                leftLong = true;
+                break;
+              }
+              k = m + 1;
+            } else k++;
+          }
+          if (!leftLong) for (let k = i; k <= j; k++) pick[k] = before;
+        }
+        i = j + 1;
+      }
+    }
     // A run shorter than the minimum span shows the base art.
     for (let i = 0; i < n;) {
       const a = pick[i];
@@ -428,6 +530,32 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = null;
       i = j + 1;
     }
+    if (hyst > 0) {
+      const allowedOn = (a: AlternateSet, k: number) => a.frames === null || a.frames.some(([f, l]) => k >= f && k <= l);
+      const anyWithinTol = (a: AlternateSet, k: number) => a.chains.some((cn) => (byChain.get(a.name)?.get(cn)?.[k] ?? Infinity) <= opts.switchTolerance);
+      const hasShortAt = (a: AlternateSet, k: number) =>
+        opts.shortInfo !== undefined &&
+        Object.keys(a.drawn).some((b) => (opts.shortInfo!.fractions.get(b)?.[k] ?? 1) < 0.60);
+      for (let i = 0; i < n;) {
+        const a = pick[i];
+        let j = i;
+        while (j + 1 < n && pick[j + 1] === a) j++;
+        if (a !== null && a !== undefined && useHyst(a)) {
+          const ds = distances.get(a.name)!;
+          let l = i;
+          while (l - 1 >= 0 && pick[l - 1] === null && allowedOn(a, l - 1) && ds[l - 1]! <= opts.switchTolerance + hyst && anyWithinTol(a, l - 1) && hasShortAt(a, l - 1)) l--;
+          let m = j;
+          while (m + 1 < n && pick[m + 1] === null && allowedOn(a, m + 1) && ds[m + 1]! <= opts.switchTolerance + hyst && anyWithinTol(a, m + 1)) m++;
+          if (i - l >= 1 || m - j >= 2 || (m - j === 1 && hasShortAt(a, j + 1))) {
+            for (let k = l; k < i; k++) pick[k] = a;
+            for (let k = j + 1; k <= m; k++) pick[k] = a;
+            j = m;
+          }
+        }
+        i = j + 1;
+      }
+      bridgeSame(pick);
+    }
     // #136: a short front-set window (< 2 × switchMin) between two behind-set windows is dropped.
     if (layer.torsoRank !== null) {
       let dropped = false;
@@ -498,9 +626,8 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       for (let i = sw.frames[0]; i <= sw.frames[1]; i++) row[i] = o;
     }
   }
-  // #136/#139/#162: between two sets that both draw an arm behind the torso, a frame that belongs to
-  // neither set stays behind (the nearer set's layer). The default front slot is for a frame no set can
-  // claim and whose arm is read in front — not a fallback.
+  // #136/#139/#162/#180: between two sets that draw an arm behind the base front setup (at least one behind the torso),
+  // a frame that belongs to neither set stays on the nearer set's layer (chosen by hand position when available, #180).
   const chainHolds: Array<{ set: string; chain: string; frames: [number, number] }> = [];
   for (const group of groups) {
     const layer = groupLayering(group, map, slots);
@@ -523,11 +650,29 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       const sw1 = gSwitches[m + 1]!;
       const set0 = group.find((a) => a.name === sw0.set)!;
       const set1 = group.find((a) => a.name === sw1.set)!;
-      if (!layer.isBehind(set0) || !layer.isBehind(set1)) continue;
+      if (!layer.isBehind(set0) && !layer.isBehind(set1)) continue;
       const g0 = sw0.frames[1] + 1;
       const g1 = sw1.frames[0] - 1;
       if (g0 > g1) continue;
-      const chains = [...new Set([...set0.chains, ...set1.chains])];
+      const chains = [...new Set([...set0.chains, ...set1.chains])].filter((cn) => layer.isChainBehindBase(set0, cn) && layer.isChainBehindBase(set1, cn));
+      if (chains.length === 0) continue;
+      for (const cn of chains) {
+        if (!layer.isBehind(set0)) for (let i = sw0.frames[0]; i <= sw0.frames[1]; i++) cClamp.get(cn)![i] = set0;
+        if (!layer.isBehind(set1)) for (let i = sw1.frames[0]; i <= sw1.frames[1]; i++) cClamp.get(cn)![i] = set1;
+      }
+      const nearerOf = (cn: string, i: number, d0: number, d1: number): AlternateSet => {
+        if (set0 !== set1) {
+          const ref = opts.handOffsets?.get(cn)?.[i];
+          const k0 = keyHandOffset(set0, map, cn);
+          const k1 = keyHandOffset(set1, map, cn);
+          if (ref !== undefined && k0 !== null && k1 !== null) {
+            const h0 = Math.hypot(ref[0] - k0[0], ref[1] - k0[1]);
+            const h1 = Math.hypot(ref[0] - k1[0], ref[1] - k1[1]);
+            return h0 <= h1 ? set0 : set1;
+          }
+        }
+        return d0 <= d1 ? set0 : set1;
+      };
       const cPick = new Map<string, Array<AlternateSet | null>>();
       for (const cn of chains) {
         const arr: Array<AlternateSet | null> = Array.from({ length: n }, () => null);
@@ -580,7 +725,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       } else {
         for (const cn of chains) {
           const arr = cPick.get(cn)!;
-          const frontSets = group.filter((a) => layer.isFront(a) && a.chains.includes(cn));
+          const frontSets = group.filter((a) => layer.isFront(a) && a.chains.includes(cn) && a !== set0 && a !== set1);
           const d0s = byChain.get(set0.name)?.get(cn);
           const d1s = byChain.get(set1.name)?.get(cn);
           for (let i = g0; i <= g1; i++) {
@@ -589,7 +734,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
             if (!claimedFront) {
               const d0 = d0s?.[i] ?? Infinity;
               const d1 = d1s?.[i] ?? Infinity;
-              arr[i] = d0 <= d1 ? set0 : set1;
+              arr[i] = nearerOf(cn, i, d0, d1);
             }
           }
           for (let i = g0; i <= g1;) {
@@ -604,7 +749,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
                 for (let k = i; k <= j; k++) {
                   const d0 = d0s?.[k] ?? Infinity;
                   const d1 = d1s?.[k] ?? Infinity;
-                  arr[k] = d0 <= d1 ? set0 : set1;
+                  arr[k] = nearerOf(cn, k, d0, d1);
                 }
               } else if (before !== null && before === after && a !== before) {
                 for (let k = i; k <= j; k++) arr[k] = before;
@@ -626,6 +771,9 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
             }
             i = j + 1;
           }
+          for (let i = g0; i <= g1; i++) {
+            if (arr[i] !== null) cClamp.get(cn)![i] = arr[i]!;
+          }
         }
       }
       for (const s of layer.touched) {
@@ -636,7 +784,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
           const a = cPick.get(cn)?.[i] ?? null;
           if (a !== null) shown.get(s)![i] = a.slots[s] ?? null;
         }
-        if (layer.torsoSlot !== null && shown.has(layer.torsoSlot)) {
+        if (layer.torsoSlot !== null && shown.has(layer.torsoSlot) && layer.isBehind(set0) && layer.isBehind(set1)) {
           const picked = chains.map((cn) => cPick.get(cn)![i]);
           if (picked.every((a) => a !== null)) shown.get(layer.torsoSlot)![i] = picked[0]!.slots[layer.torsoSlot] ?? slots.get(layer.torsoSlot)!.setup;
         }
@@ -920,6 +1068,12 @@ export function clampArt(switches: readonly Switch[], map: JointMap, targets: Ma
  */
 export const RAISED_WITHIN = 30;
 
+/**
+ * --raised-by-head (#179): a chain is placed by the head when its key skeleton's
+ * wrist lies within this many eye distances of the head centre.
+ */
+export const RAISED_WRIST_EYES = 2;
+
 /** Whether a drawn world angle, Spine degrees, is within `RAISED_WITHIN` of straight up (90°). */
 export const isRaised = (drawn: number): boolean => Math.abs(wrap(drawn - 90)) <= RAISED_WITHIN;
 

package/src/verify.ts

@@ -561,6 +561,22 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       if (b.has('head')) return b.get('head')!.worldY;
       return rigNeckY(b);
     };
+    const headBoneName = (() => {
+      if (headChain !== undefined) {
+        const k = headChain.joints.findIndex((j, idx) => idx + 1 < headChain.joints.length && ((j === 'r_eye' && headChain.joints[idx + 1] === 'l_eye') || (j === 'l_eye' && headChain.joints[idx + 1] === 'r_eye')));
+        if (k >= 0) return headChain.bones[k]!;
+      }
+      return posed[0]?.has('head') ? 'head' : null;
+    })();
+    const maxNod = (() => {
+      if (headBoneName === null || rigNeck === null || posed.length === 0) return Infinity;
+      const b0 = posed[0]!;
+      const hb0 = b0.get(headBoneName);
+      const nk0 = pointAt(b0, lengths, rigNeck);
+      if (hb0 === undefined || nk0 === null) return Infinity;
+      const d = Math.hypot(hb0.worldX - nk0[0], hb0.worldY - nk0[1]);
+      return d > 1e-6 ? 0.022 * d : Infinity;
+    })();
     for (const sp of r.feet.supports) {
       const refHip: number[] = [];
       const rigHipY: number[] = [];
@@ -568,6 +584,7 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       const rigNeckS: number[] = [];
       const refEyesNeck: number[] = [];
       const rigEyesNeck: number[] = [];
+      const rigEyeHead: number[] = [];
       for (let i = sp.frames[0]; i <= sp.frames[1]; i++) {
         const b = posed[i]!;
         const rh = at(i, 'r_hip');
@@ -587,15 +604,27 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
           if (re !== null && le !== null && ey !== null) {
             refEyesNeck.push(-((re[1] + le[1]) / 2 - nk[1]) * s);
             rigEyesNeck.push(ey - ny);
+            const hy = headBoneName !== null && b.has(headBoneName) ? b.get(headBoneName)!.worldY : ny;
+            rigEyeHead.push(ey - hy);
           }
         }
       }
+      const boundedRefEyesNeck = (() => {
+        if (!(maxNod < Infinity) || refEyesNeck.length === 0) return refEyesNeck;
+        const dr = detrend(refEyesNeck);
+        const dgEH = detrend(rigEyeHead);
+        return refEyesNeck.map((v, i) => {
+          const base = v - dr[i]!;
+          const nod = Math.max(-maxNod, Math.min(maxNod, dr[i]! - dgEH[i]!));
+          return base + dgEH[i]! + nod;
+        });
+      })();
       bounce.push({
         side: sp.side,
         frames: [sp.frames[0], sp.frames[1]],
         hip: bounceMetric(refHip, rigHipY),
         neck: bounceMetric(refNeck, rigNeckS),
-        eyesNeck: bounceMetric(refEyesNeck, rigEyesNeck),
+        eyesNeck: bounceMetric(boundedRefEyesNeck, rigEyesNeck),
       });
     }
   }