@rig-c/pose 0.23.0 → 0.24.1

package/README.md

@@ -182,7 +182,7 @@ The threshold was fixed by measuring first ([#15](https://github.com/rig-c/pose/
 
 Re-measured with the guard on, against the guarded unsmoothed run, on #11's criteria (power above 6 Hz down ≥ 2× on every point, timing lag 0, p95 speed ≥ 0.85×): no window passes. `--smooth 7` comes closest — the left wrist's power drops 1.99× and the hip's p95 speed is 0.847× — so `--smooth` stays off by default, and so does the guard: the rule posted before the run made a default for either one depend on a window passing. **Use `--flip 90`**: with it, no bone of the gated build turns more than 90° in one frame (without it, 148.6°), and every bone still lands.
 
-**The short hold.** A segment pointing at the camera is short in the picture, and its picture direction is then detector noise: the rig turns the bone to follow it. So after holds, and before the flip guard, every limb segment the map aims is measured on every frame (not a `reach`, and not a line across the body from a left joint to its right twin, such as the hip line or the eye line: those shorten when the body or head turns, which is a different thing, and the cutoff below was measured on limbs only) — its picture length, between the same two points its angle is read from, over its own median length across the pose. On a frame under `--short <fraction>` its angle is not read from the pose: it is interpolated, the short way round, from the last frame at or above the cutoff to the next one, and held flat at the first or last frame of the pose. The flip guard, the hinge check and the keys all see the held angle. `--short off` (the default) reads every frame. The report lists each span under `short` (chain, bone, segment, first and last frame, the lowest fraction).
+**The short hold.** A segment pointing at the camera is short in the picture, and its picture direction is then detector noise: the rig turns the bone to follow it. So after holds, and before the flip guard, every mapped segment is measured on every frame (not a `reach`) — its picture length, between the same two points its angle is read from, over its own median length across the pose. On a frame under `--short <fraction>` its angle is not read from the pose: it is interpolated, the short way round, from the last frame at or above the cutoff to the next one, and held flat at the first or last frame of the pose. A horizontal line across the body from a left joint to its right twin (`a>b`, such as the hip line or the eye line) also holds its last confident angle and interpolates across the span whenever its picture length falls under `--short` or its 2D reading reverses sign within one frame past `--flip` (when the left and right joints cross in 2D during a full side turn, [#184](https://github.com/rig-c/pose/issues/184)); its hold is printed as `HOLD chain "..."` and is not counted toward limb `END-ON` runs. The flip guard, the hinge check and the keys all see the held angle. `--short off` (the default) reads every frame unless an across-body line reverses past `--flip`. The report lists each span under `short` (chain, bone, segment, first and last frame, the lowest fraction, and `across` / `reversed` when across-body).
 
 The cutoff was fixed by measuring first ([#22](https://github.com/rig-c/pose/issues/22)), over both upper arms, forearms, thighs and shins. On the 13 s dance (24 fps, 2,504 segment-frames) the fraction's 0.5th percentile is 0.51, its 5th 0.82, and 7 segment-frames (0.28%) are under 0.35; on a 16 s second sequence (30 fps, 3,936) they are 0.27 and 0.75, and 34 (0.86%). Every frame under 0.35 was looked at, and was one of two kinds:
 
@@ -191,7 +191,7 @@ The cutoff was fixed by measuring first ([#22](https://github.com/rig-c/pose/iss
 
 Both have a meaningless direction; only the first is a pose the rig cannot draw. **0.35** is the smallest round value that takes in every end-on frame (the highest is 0.35, on the dance) without reaching normal motion (the 5th percentiles are 0.75 and 0.82). A run under the cutoff — spans merged across a gap of one frame — lasting **≥ 0.15 s** (3.6 frames at 24 fps, 4.5 at 30) is the end-on kind: it excludes every blur collapse above (at most 3 frames, 0.10 s at 30 fps) and keeps every end-on span (6–8 frames). The run prints it as `END-ON` and the report lists it under `endOn` (chain, bone, segment, frames, seconds, the lowest fraction): it is the list of moments that need an alternate drawing ([#6](https://github.com/rig-c/pose/issues/6)).
 
-Re-checked on the exam01 test rig with `--short 0.35 --flip 90 --bends clamp`. On the second sequence the three spreads the flip guard made out of end-on segments are SHORT holds now, not FLIPs: right upper arm 399–400, right thigh 368–369, right shin 368–371. Of the flip guard's other spreads only one is left, the left forearm at 322–323; every other one fell on frames under the cutoff and is a SHORT hold instead. No guarded bone of the gated build turns more than 81.4° in one frame (85.1° with `--flip 90` alone), and every bone lands. `endOn` there lists the right upper arm (395–401) and the right shin (365–370). It does not list the right thigh, which is under 0.35 on one frame only (369, 0.16). The plan before the run expected the thigh too, and that expectation was wrong. On the dance `endOn` lists exactly S2's left upper arm (30–37); the three FLIPs are #15's, the largest one-frame turn is 78.2°, and every bone lands. A first implementation also held the lines across the body. It listed the eye line (head in profile) and the hip line (body side-on) as end-on, and holding the hip line narrowed the rig's hip tilt range to 39.3° against the pose's 125.2°. The cutoff was never measured on those lines, so they are excluded; with them out the rig reads 125.2° again. The default stays off: a default needs its own criterion and a third sequence.
+Re-checked on the exam01 test rig with `--short 0.35 --flip 90 --bends clamp`. On the second sequence the three spreads the flip guard made out of end-on segments are SHORT holds now, not FLIPs: right upper arm 399–400, right thigh 368–369, right shin 368–371. Of the flip guard's other spreads only one is left, the left forearm at 322–323; every other one fell on frames under the cutoff and is a SHORT hold instead. No guarded bone of the gated build turns more than 81.4° in one frame (85.1° with `--flip 90` alone), and every bone lands. `endOn` there lists the right upper arm (395–401) and the right shin (365–370). It does not list the right thigh, which is under 0.35 on one frame only (369, 0.16). The plan before the run expected the thigh too, and that expectation was wrong. On the dance `endOn` lists exactly S2's left upper arm (30–37); the three FLIPs are #15's, the largest one-frame turn is 78.2°, and every bone lands. When the second sequence's pelvis is mapped (`r_hip → l_hip`), its side-on turn (frames 463–491, body yaw +79.5°) foreshortens the hip line to 0.17 of standing and crosses `r_hip.x` past `l_hip.x` on frames 482–484 (+177.4° / −179.4°); `holdAcross` ([#184](https://github.com/rig-c/pose/issues/184)) holds `hip.rotate` across the unconfident span (`[−2.2°, +2.6°]` over 463–491, `0` `FLIP`s) without listing horizontal lines as limb `END-ON`. The default stays off: a default needs its own criterion and a third sequence.
 
 ### The legs: foreshortening and planted feet
 
@@ -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.1",
   "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';
@@ -182,6 +182,10 @@ export interface Short {
   /** Present when a foreshortened segment (< `SHORT_STEP_FRACTION`) had its per-frame step capped (#110): the one-frame step after capping and the largest step asked, degrees, signed. */
   step?: number;
   asked?: number;
+  /** Present when a horizontal chain across the body (`isAcross`) held its last confident angle (#184). */
+  across?: boolean;
+  /** Largest one-frame turn (degrees, signed) inside a held horizontal-chain span when it reversed beyond `--flip` (#184). */
+  reversed?: number;
 }
 
 /** A limb segment shorter than this fraction of its median picture length has its per-frame angle step capped at `SHORT_STEP_CAP` degrees (rig-c/pose#110). */
@@ -610,30 +614,40 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
-  // The short hold, on every limb segment the pose aims directly (not a reach, and
-  // not a line across the body from a left joint to its right twin — the hip line,
-  // the eye line — whose shortening is the body or head turning, not a limb seen
-  // end-on; #22's cutoff was measured on limb segments only): its picture length
-  // against its own median, on the points the angle was read from.
+  // The short hold, on every segment the pose aims directly (not a reach): its
+  // picture length against its own median, on the points the angle was read from.
+  // A horizontal line across the body (`isAcross`: pelvis, shoulders, head line)
+  // holds and interpolates across spans under `--short` or reversed within a frame
+  // beyond `--flip` (#184), without listing the run as `endOn` (`TURN` reads turned
+  // body/head lines).
   const short: Short[] = [];
   const endOn: EndOn[] = [];
   const fractions = new Map<string, { chain: string; joints: [string, string]; fraction: number[] }>();
-  if (opts.short !== 'off') {
-    const cutoff = opts.short;
+  if (opts.short !== 'off' || opts.flip !== 'off') {
     for (const c of map.chains) {
       if (c.reach) continue;
       c.bones.forEach((b, k) => {
         const joints: [string, string] = [c.joints[k]!, c.joints[k + 1]!];
-        if (isAcross(joints[0], joints[1])) return;
+        const across = isAcross(joints[0], joints[1]);
+        if (!across && opts.short === 'off') return;
         const from = series.get(joints[0])!;
         const to = series.get(joints[1])!;
         const lengths = from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1]));
         const med = median(lengths);
         if (med < 1e-6) {
-          p.add('POSE_SHORT_MEDIAN', `chain "${c.name}" — bone "${b}"'s segment ${joints[0]} → ${joints[1]} has median picture length ${med}px over the ${n} frames; --short measures a frame's length against that median, and there is none to measure against`);
+          if (opts.short !== 'off') {
+            p.add('POSE_SHORT_MEDIAN', `chain "${c.name}" — bone "${b}"'s segment ${joints[0]} → ${joints[1]} has median picture length ${med}px over the ${n} frames; --short measures a frame's length against that median, and there is none to measure against`);
+          }
           return;
         }
         const fraction = lengths.map((l) => l / med);
+        if (across) {
+          const restDir = joints[0].startsWith('r_') ? 0 : 180;
+          const spans = holdAcross(targets.get(b)!, fraction, opts.short, opts.flip, restDir);
+          for (const s of spans) short.push({ chain: c.name, bone: b, joints, ...s });
+          return;
+        }
+        const cutoff = opts.short as number;
         fractions.set(b, { chain: c.name, joints, fraction });
         const spans = holdShort(targets.get(b)!, fraction, cutoff);
         for (const s of spans) short.push({ chain: c.name, bone: b, joints, ...s });
@@ -728,6 +742,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 +795,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 +934,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 +1133,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 +1202,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 +1235,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 +1290,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 +1308,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 +1333,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 +1467,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 +1548,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;
         }
@@ -1755,6 +1926,79 @@ export function holdShort(angles: number[], fraction: readonly number[], cutoff:
   return out;
 }
 
+/**
+ * Hold and interpolate across unconfident spans on a horizontal chain (`isAcross`,
+ * e.g. `r_hip → l_hip`, `r_eye → l_eye`, `r_shoulder → l_shoulder`, rig-c/pose#184),
+ * in place. A frame is unconfident when its picture length over its median is under
+ * `shortCutoff` (with `--short`) or when its angle turns more than `flipThreshold`
+ * from the last confident angle or reverses more than 90° from the line's rest
+ * direction `restDir` (with `--flip`). Each contiguous unconfident run has its
+ * angles interpolated between the confident frames either side (flat at the ends),
+ * the short way round, exactly as `holdShort` does on limb chains.
+ */
+export function holdAcross(
+  angles: number[],
+  fraction: readonly number[],
+  shortCutoff: number | 'off',
+  flipThreshold: number | 'off',
+  restDir = 0,
+): ShortSpan[] {
+  const n = angles.length;
+  if (n === 0 || (shortCutoff === 'off' && flipThreshold === 'off')) return [];
+  const raw = [...angles];
+  const unconf = new Array<boolean>(n).fill(false);
+  let lastConfident = raw[0]!;
+  for (let i = 0; i < n; i++) {
+    const s = shortCutoff !== 'off' && fraction[i]! < shortCutoff;
+    const rev = Math.abs(wrap(raw[i]! - restDir)) > 90;
+    if (!s && !rev) {
+      lastConfident = raw[i]!;
+      break;
+    }
+  }
+  for (let i = 0; i < n; i++) {
+    const isShort = shortCutoff !== 'off' && fraction[i]! < shortCutoff;
+    const isFlipped =
+      flipThreshold !== 'off' &&
+      (Math.abs(wrap(raw[i]! - lastConfident)) > flipThreshold || Math.abs(wrap(raw[i]! - restDir)) > 90);
+    if (isShort || isFlipped) {
+      unconf[i] = true;
+    } else {
+      lastConfident = raw[i]!;
+    }
+  }
+  const out: ShortSpan[] = [];
+  for (let i = 0; i < n; i++) {
+    if (!unconf[i]) continue;
+    let j = i;
+    while (j + 1 < n && unconf[j + 1]) j++;
+    const lo = i - 1;
+    const hi = j + 1;
+    let minFraction = fraction[i]!;
+    for (let k = i + 1; k <= j; k++) minFraction = Math.min(minFraction, fraction[k]!);
+    let maxTurn = 0;
+    for (let k = Math.max(1, i); k <= Math.min(n - 1, j + 1); k++) {
+      const jmp = wrap(raw[k]! - raw[k - 1]!);
+      if (Math.abs(jmp) > Math.abs(maxTurn)) maxTurn = jmp;
+    }
+    if (lo >= 0 || hi < n) {
+      const a = lo >= 0 ? angles[lo]! : angles[hi]!;
+      const b = hi < n ? angles[hi]! : a;
+      const turn = wrap(b - a);
+      for (let k = i; k <= j; k++) angles[k] = lo < 0 ? b : wrap(a + (turn * (k - lo)) / (hi - lo));
+    }
+    const revThreshold = flipThreshold !== 'off' ? flipThreshold : 90;
+    out.push({
+      frames: [i, j],
+      minFraction,
+      across: true,
+      ...(Math.abs(maxTurn) > revThreshold ? { reversed: r3(maxTurn) } : {}),
+    });
+    i = j;
+  }
+  return out;
+}
+
 /** Short spans `gap` frames apart or fewer, as one run each: its first and last frame, and the lowest fraction. */
 export function mergeRuns(spans: readonly ShortSpan[], gap: number): ShortSpan[] {
   const out: ShortSpan[] = [];
@@ -1854,9 +2098,9 @@ export function capShortSteps(
 const spanOf = (frames: [number, number], times: readonly number[]): string =>
   frames[0] === frames[1] ? `frame ${frames[0]} (t=${times[frames[0]]!.toFixed(3)}s)` : `frames ${frames[0]}–${frames[1]} (t=${times[frames[0]]!.toFixed(3)}–${times[frames[1]]!.toFixed(3)}s)`;
 
-export function shortLine(s: Short, times: readonly number[], cutoff: number): string {
+export function shortLine(s: Short, times: readonly number[], cutoff: number | 'off'): string {
+  const sg = (v: number) => `${v >= 0 ? '+' : '−'}${Math.abs(v).toFixed(1)}°`;
   if (s.step !== undefined && s.asked !== undefined) {
-    const sg = (v: number) => `${v >= 0 ? '+' : '−'}${Math.abs(v).toFixed(1)}°`;
     return `chain "${s.chain}" bone "${s.bone}" (${s.joints[0]} → ${s.joints[1]}) ${spanOf(s.frames, times)}: picture length down to ${s.minFraction.toFixed(2)} of its median, under ${SHORT_STEP_FRACTION.toFixed(2)}, turned ${sg(s.asked)} in one frame (over ${SHORT_STEP_CAP}°); spread to ${sg(s.step)} per frame`;
   }
   const lo = s.frames[0] - 1;
@@ -1866,6 +2110,12 @@ export function shortLine(s: Short, times: readonly number[], cutoff: number): s
     : lo < 0 ? `held flat at frame ${hi}'s angle (the pose starts short)`
       : hi >= times.length ? `held flat at frame ${lo}'s angle (the pose ends short)`
         : `interpolated from frame ${lo}'s angle to frame ${hi}'s, the short way round`;
+  if (s.across === true) {
+    const shortWhy = cutoff !== 'off' && s.minFraction < cutoff ? `picture length down to ${s.minFraction.toFixed(2)} of its median, under ${cutoff}` : null;
+    const revWhy = s.reversed !== undefined ? `reversed ${sg(s.reversed)} in one frame` : null;
+    const why = shortWhy !== null && revWhy !== null ? `${shortWhy}, ${revWhy}` : shortWhy ?? `${revWhy ?? 'reversed'} (picture length down to ${s.minFraction.toFixed(2)} of its median)`;
+    return `chain "${s.chain}" bone "${s.bone}" (${s.joints[0]} → ${s.joints[1]}) ${spanOf(s.frames, times)}: ${why}; its direction is not read — ${held}`;
+  }
   return `chain "${s.chain}" bone "${s.bone}" (${s.joints[0]} → ${s.joints[1]}) ${spanOf(s.frames, times)}: picture length down to ${s.minFraction.toFixed(2)} of its median, under ${cutoff}; its direction is not read — ${held}`;
 }
 

package/src/run.ts

@@ -135,8 +135,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     else if (a.plantFeet === true) say('  CAMERA none in the sequence: --plant-feet reads the picture as a fixed camera, so a zoom or a pan in the video moves the floor with it and the floor may step with the picture (tools/scan.py reads the camera, rig-c/pose#63)');
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
+    for (const s of r.short) say(`  ${s.across === true ? 'HOLD  ' : 'SHORT '} ${shortLine(s, r.times, a.short)}`);
     if (a.short !== 'off') {
-      for (const s of r.short) say(`  SHORT  ${shortLine(s, r.times, a.short)}`);
       for (const e of r.endOn) say(`  END-ON ${endOnLine(e, r.times, a.short)}`);
     }
     if (a.flip !== 'off') for (const fl of r.flips) say(`  FLIP   ${flipLine(fl, r.times, a.flip)}`);

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),
       });
     }
   }