@rig-c/pose 0.15.0 → 0.16.0

package/README.md

@@ -96,6 +96,8 @@ and what the run cannot decide for you it lists:
 - `UNCOVERED` — with `alternates` in the map: every fold on a frame where no switch took the folding mesh off screen. This is the list of poses still to paint.
 - `RANGE` — a chain's `range` ([below](#a-joints-range-range)): a bone whose rotate key the pose asks past its range, outside every span of a set depicting its chain, is clamped at the limit; one line per run, with the frames, the seconds and the largest overflow. The demand for an alternate.
 - `ART-RANGE` — inside a set's span: a bone with a `drawn` angle in the set, turned from it past its limits — the set's `turn` for that bone (held at the limit) or, without one, its chain's `range` (the bone follows the pose). Listed as the pose asked it either way: the demand for another drawing of that set.
+- `RAISED` — with `--raised-by-head` ([below](#alternate-drawings-alternates)): one line per span of a set that draws an arm raised, per chain. It gives the frames and the median eye distances (the rig's in units, the reference's in px). It gives the wrist's offset from the head centre in eye distances: the median of the reference's, of where the wrist was placed, of the rig's on the pose's angles, and of the rig's as keyed. It gives the worst |rig − reference| before and after, the worst |after − placed|, and the frames whose upper arm the set's `turn` held. `RAISED none` when the flag is given and no such set showed.
+- `REACH` — with `--raised-by-head`: a raised span whose target was out of the arm's reach, too far or too near. It names the frames, which way, and the shortfall in eye distances. The wrist was placed at the reach limit instead. This is not `ART-RANGE`: the rig's proportions were the limit, not the art's range. A too-near frame is placed at the limit like a too-far one, and graded at the placed distance.
 - `LEG-SCALE` — with `--leg-scale` ([below](#the-legs-foreshortening-and-planted-feet)): per leg segment, its straight length, the spread of its picture length over it, and the frames clamped at each limit.
 - `PIVOT` — when the map translates a bone and has both legs: the translated bone's origin against its thigh roots' midpoint at setup, in units and hip widths — the pivot every hip turn swings the legs about.
 - `FEET` — when the map has both legs: the supports and jumps read off the reference ankles (planted or not), and on the posed build, outside the jumps, the lowest ankle's vertical range and each support span's worst vertical range and horizontal drift of the supporting ankle, in leg lengths.
@@ -105,7 +107,7 @@ and what the run cannot decide for you it lists:
 - `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet` and `stance` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `stance` (`tolerance`, `bounds`, `runs`: `{ state, side, frames, maxHeight, k }`, `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `stance` (`tolerance`, `bounds`, `runs`: `{ state, side, frames, maxHeight, k }`, `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
 
 | field | each entry |
 | --- | --- |
@@ -122,7 +124,8 @@ The demand lists:
 - `endOn` — above, under the short hold.
 - `turns: [{ line, joints, frames, seconds, minFraction, reversed }]` — `line` is `hip`, `shoulder` or `eye`.
 - `range: [{ chain, bone, frames, seconds, maxOverflow, key, limits }]` — `key` is the rotate key the pose asked for on the frame of the largest overflow, before the clamp.
-- `artRange: [{ set, chain, bone, frames, seconds, maxOverflow, turn, limits, clamped }]` — `turn` is the signed art turn the pose asked on that frame; `clamped` says whether the set's `turn` held the bone there.
+- `artRange: [{ set, chain, bone, frames, seconds, maxOverflow, turn, limits, clamped, shortfall? }]` — `turn` is the signed art turn the pose asked on that frame; `clamped` says whether the set's `turn` held the bone there. `shortfall` (with `--raised-by-head`) marks a held upper arm whose re-aimed forearm left the wrist short of its placed point: the most, in eye distances, with `turn` and `maxOverflow` the upper arm's on that frame.
+- `raised: [{ set, chain, frames, seconds, eyes: { rig, reference }, reference, placed, before, after, worst: { before, after, placed }, short, upperHeld, reach: { min, max, farthest } }]` — with `--raised-by-head`. `reference`, `placed`, `before` and `after` are the wrist's offset from the head centre on each frame of the span, `[x, y]` in eye distances, x right and y up. `eyes` holds each side's median eye distance over the span. `worst.before` and `worst.after` are the largest |rig − reference| in x and in y; `worst.placed` is the largest |after − placed|. `short` lists the `REACH` runs, each `{ frames, how, shortfall: { max, median } }`, where `how` is `far`, `near` or `missed`. `upperHeld` lists the frames whose upper arm the set's `turn` held. `reach` gives |l0 − l1|, l0 + l1 and the farthest target from the shoulder, in world units.
 
 Runs in `turns`, `range` and `artRange` merge across a gap of one frame, as `endOn` does; `seconds` runs from the first frame's key time to the end of the last frame.
 
@@ -309,6 +312,16 @@ Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's
 **A stopgap window: `frames`.** A set may state `"frames": [[first, last], …]`: it shows only inside those windows, and on them it is chosen over any set within tolerance that has no window. It is for two sets whose key skeletons the angles cannot tell apart. Measured on HQ's dancer, the hands clasped behind the back and the hands low in front differ by only 2–21°, and the wrist and hand-point scores do not separate them either; the cue that might is #33's depth state. It is recorded in the map as a stopgap, not a selection rule. A window **restricts** a set; it never forces one. Where the set does not show inside its window, the run says why in a `FRAMES` line: the stretch, and whether the pose there was past the tolerance (with the largest distance), or within it but the run was dropped.
 
 **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**:
+
+- 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.
+- **The order of solving.** The arm is solved last of the bones. By then the hip's travel, every reach, the head and every range clamp are final, and the arm moves neither the head nor its own shoulder. On each frame the rig's eye points and the shoulder are posed forward from those targets, as a reach's origin is: each rest offset is turned by the nearest mapped bone above.
+- **Reach.** The arm reaches the annulus about the shoulder from |l0 − l1| to l0 + l1. Here l0 runs from the upper arm's origin to the forearm's, and l1 from there to the wrist (the forearm's tip, or the point it aims at). A target outside it is replaced by the reach limit along the head-relative direction. That is the point inside the annulus, on the ray from the head centre through the target, nearest the target. Where the ray crosses the annulus twice, the nearer stretch wins, and a tie goes to the point nearer the head. A ray that never enters it gives the annulus point nearest the target. Every such frame is listed in `REACH`. A too-near frame is treated as a too-far one: the wrist is placed at the reach limit, and the distance the rule grades it at is the placed one. That is |placed − head centre|, not the reference's, which the arm cannot fold to.
+- **The solve.** Two bones on the rig's own lengths put the wrist on that point, the elbow bending to the side the pose's does. The set's `turn` is part of the solve. When it holds the upper arm, the forearm is re-aimed from the held elbow at the placed wrist rather than held on its own. `ART-RANGE` lists where the re-aimed forearm still cannot reach within `turn`, in two cases. One is a forearm past its own `turn`, held there. The other is a held upper arm whose re-aimed forearm leaves the wrist more than 0.01 eye distances short of its placed point; 0.01 is the float and rounding scale. That case is listed on the upper arm, with the shortfall in eye distances. The solved angles become the targets, which the keys and the landing check follow.
+- Frames outside those spans, and sets that draw no arm raised, are keyed as without the flag, byte for byte. A raised chain must have two bones, each aimed `"x"` or at one point, and the eye points must not turn with it (`RAISED_CHAIN`).
+
 ## Compare: the rig's render against the video
 
 ```sh

package/cli.ts

@@ -98,6 +98,18 @@ retarget
                         reaches the floor, raised or lowered, k within [0.92, 1.08] (past it, reported, not forced); above
                         it the foot is lifted and keeps the pose's height (STANCE lines; default: off; 0.07 is
                         the card's, rig-c/pose#60)
+  --raised-by-head      while a set whose arm is drawn raised shows (its "drawn" upper arm within 30° of straight
+                        up), that arm's wrist goes where the reference's is against the head, in eye distances:
+                        rig head centre + (reference wrist − reference head centre) × rig eye distance ÷ the
+                        reference's, per frame; each eye distance is its median over the span. The head centre is
+                        the eyes' midpoint; the rig's eyes are the two points the head chain's "a>b" aim names
+                        (refused without one, RAISED_HEAD), posed from the targets of the bones above. A target out
+                        of the arm's reach, too far or too near, goes to the reach limit on the ray from the head
+                        centre toward it and is graded at that placed distance (REACH lines, in eye distances). A
+                        two-bone solve on the rig's own lengths keeps the pose's elbow side; when the set's "turn"
+                        holds the upper arm the forearm is re-aimed at the wrist. ART-RANGE: a forearm still past
+                        its turn, or a held arm leaving the wrist > 0.01 eye distances short of its placed point
+                        (the shortfall listed). RAISED lines (default: off; rig-c/pose#62)
   --idle <name>         the rig's animation read as its idle (default: idle). Every idle track the new
                         animation does not key, on any channel, is listed as IDLE-DROPPED (a blink, a
                         breath); one it keys is IDLE-KEPT-OUT, naming the track that keys it, and so is a
@@ -129,7 +141,7 @@ retarget
   --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
   --report <file>       write the run's measurements (holds, short, endOn, flips, bends, landings, folds,
-                        switches, uncovered, turns, range, artRange,
+                        switches, uncovered, turns, range, artRange, raised,
                         idleDropped, idleKeptOut, merged, reduce) as JSON
 
   It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
@@ -228,7 +240,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance'], ['coco', 'plant-feet', 'carry-idle']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -254,6 +266,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     legScale: legScaleOf(f),
     plantFeet: f.has('plant-feet'),
     stance: stanceOf(f),
+    raisedByHead: f.has('raised-by-head'),
     bends,
     bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     switchTolerance: num(f, 'switch-tolerance', 25, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.15.0",
+  "version": "0.16.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

@@ -50,6 +50,14 @@
  * Inside a span nothing is clamped, but a bone with a `drawn` angle is read
  * against it (`artTurn`, and `artRange` where it leaves its range).
  *
+ * With `raisedByHead` (rig-c/pose#62), after the range clamp and before the art
+ * turn is read: inside each span of a set that draws an arm raised, the arm is
+ * solved last, so its wrist lands where the reference's is against the head, in
+ * eye distances (each side's median over the span). The head and the shoulder
+ * are posed from the final targets of the bones above. A target out of reach
+ * goes to the reach limit along the head-relative direction (REACH); the set's
+ * `turn` is part of the solve, and only a forearm it still holds is ART-RANGE.
+ *
  * The lines across the body — hips, shoulders, eyes — are read from the pose
  * after holds, whether the map uses them or not: a line under
  * `TURN_FRACTION` of its median picture length, or reversed (pointing more
@@ -63,16 +71,26 @@ import { screenToSpineDegrees } from 'rig-c/transform';
 import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
 import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
-import { aimAngle, descends, rigPoint } from './map.ts';
+import { aimAngle, aimEnds, descends, partBone, pointParts, rigPoint } from './map.ts';
 import type { Joint } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
-import { clampArt, coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
+import type { ArtRange, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { Feet, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
 import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
+/**
+ * --raised-by-head (#62): a held upper arm whose re-aimed forearm leaves the
+ * wrist farther than this from its placed point, in eye distances, "cannot
+ * reach within turn" — ART-RANGE. It sits at the float and rounding scale, so
+ * any real miss counts: the solve itself closes to ~1e-12, and the writer's
+ * 0.001° rounding of two keys moves a wrist by ≤ 2 × 1.75e-5 × (l0 + l1), which
+ * is 0.0004 eye distances on the tests' stick rig (a 130-unit arm, 12-unit eyes).
+ */
+export const HELD_MISS = 0.01;
+
 export interface RetargetOptions extends SwitchOptions {
   /** A joint with a score below this is not good on that frame (a joint with no score is). */
   minScore: number;
@@ -90,6 +108,8 @@ export interface RetargetOptions extends SwitchOptions {
   plantFeet?: boolean;
   /** With plantFeet: a free ankle within this many leg lengths of the floor plants both feet, its leg stretched to reach it (`legs.ts` stanceOf, #60); 'off' (the default) plants one. */
   stance?: number | 'off';
+  /** While a set whose arm is drawn raised shows, its wrist is placed against the rig's head in eye distances (rig-c/pose#62); false (the default) keeps the pose's angles. */
+  raisedByHead?: boolean;
 }
 
 export interface Hold {
@@ -272,6 +292,8 @@ export interface Retarget {
   ankles: { bones: Record<Side, string>; at: Record<Side, Pt[]> } | null;
   /** The translated bone's origin against its thigh roots' midpoint, at setup. */
   pivot: Pivot | null;
+  /** With --raised-by-head: each raised set's span on each raised chain, its wrist placed against the head. */
+  raised: Raised[];
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -368,6 +390,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const endOf = (i: number): number => (i + 1 < n ? keyTimes[i + 1]! : n > 1 ? 2 * keyTimes[i]! - keyTimes[i - 1]! : keyTimes[i]!);
   const secondsOf = (run: [number, number]): number => Math.round((endOf(run[1]) - keyTimes[run[0]]!) * 1e6) / 1e6;
 
+  // --raised-by-head (#62) measures against the head in eye distances: the map's head chain must carry the
+  // eye line with an "a>b" aim, whose two ends are the rig's eyes.
+  const head = opts.raisedByHead === true ? headOf(map) : null;
+  if (head !== null && 'problem' in head) p.add('RAISED_HEAD', head.problem);
+
   // Every point the map reads, held where it is not good.
   const needed = new Set<string>();
   for (const c of map.chains) c.joints.forEach((j) => needed.add(j));
@@ -713,29 +740,52 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     for (let a = rest.get(b)!.parent; a !== null; a = rest.get(a)!.parent) d++;
     return d;
   };
+  /** The world turn of `b`'s nearest mapped bone-or-ancestor, degrees, on frame i, by the targets as they stand. */
+  const turnAbove = (b: string, i: number): number => {
+    for (let a: string | null = b; a !== null; a = rest.get(a)!.parent) {
+      const tg = targets.get(a);
+      if (tg !== undefined) return tg[i]! - restOf.get(a)!;
+    }
+    return 0;
+  };
+  /**
+   * Where the poser will put `b`'s origin on frame i: forward from the
+   * translated bone (moved by its travel) or the root (at setup), each rest
+   * offset turned by the nearest mapped bone above — the key formula's own
+   * assumption (unit scale, no shear), which the landing check holds to account.
+   */
+  const posedOrigin = (b: string, i: number): Pt => {
+    const own = rest.get(b)!;
+    if (t !== null && b === t.bone) return [own.worldX + (travel[i]?.[0] ?? 0), own.worldY + (travel[i]?.[1] ?? 0)];
+    if (own.parent === null) return [own.worldX, own.worldY];
+    const parent = own.parent;
+    const po = posedOrigin(parent, i);
+    const r = turnAbove(parent, i) / DEG;
+    const ox = own.worldX - rest.get(parent)!.worldX;
+    const oy = own.worldY - rest.get(parent)!.worldY;
+    return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
+  };
+  /** A rig point (a bone, `name:tip`, `a+b`) posed on frame i the same way. */
+  const posedPoint = (spec: string, i: number): Pt => {
+    let x = 0;
+    let y = 0;
+    const parts = pointParts(spec);
+    for (const part of parts) {
+      const name = partBone(part);
+      const o = posedOrigin(name, i);
+      const bone = rest.get(name)!;
+      const l = part.endsWith(':tip') ? bone.length : 0;
+      const r = turnAbove(name, i) / DEG;
+      x += o[0] + l * (Math.cos(r) * bone.a - Math.sin(r) * bone.c);
+      y += o[1] + l * (Math.sin(r) * bone.a + Math.cos(r) * bone.c);
+    }
+    return [x / parts.length, y / parts.length];
+  };
   const reaches = map.chains.filter((c) => c.reach).sort((x, y) => depth(x.bones[0]!) - depth(y.bones[0]!));
   let aimReach: ((c: Chain) => void) | null = null;
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
-    /** The world turn of `b`'s nearest mapped bone-or-ancestor, degrees, on frame i. */
-    const turnAbove = (b: string, i: number): number => {
-      for (let a: string | null = b; a !== null; a = rest.get(a)!.parent) {
-        const tg = targets.get(a);
-        if (tg !== undefined) return tg[i]! - restOf.get(a)!;
-      }
-      return 0;
-    };
-    /** Where the poser will put `b`'s origin on frame i: forward from the translated bone. */
-    const posedOrigin = (b: string, i: number): Pt => {
-      if (b === t.bone) return [tb.worldX + travel[i]![0], tb.worldY + travel[i]![1]];
-      const parent = rest.get(b)!.parent!;
-      const po = posedOrigin(parent, i);
-      const r = turnAbove(parent, i) / DEG;
-      const ox = rest.get(b)!.worldX - rest.get(parent)!.worldX;
-      const oy = rest.get(b)!.worldY - rest.get(parent)!.worldY;
-      return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
-    };
     aimReach = (c: Chain): void => {
       const b = c.bones[0]!;
       const anchor = series.get(c.joints[0]!)!;
@@ -793,8 +843,214 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   }
   p.throwIfAny();
-  const artRange = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+
+  // --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
+  // 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
+  // (`reachLimit`, a REACH line). The set's `turn` is part of the solve: a held upper arm has its forearm
+  // re-aimed at the placed wrist, and only a forearm the turn still holds is ART-RANGE.
+  const raised: Raised[] = [];
+  const raisedArt: Array<{ sw: Switch; entries: ArtRange[] }> = [];
+  const raisedJobs: Array<{ sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; l0: number; l1: number; farthest: number; eyePoints: [string, string] }> = [];
+  if (head !== null && !('problem' in head)) {
+    const eyesOn = (i: number): { centre: Pt; dist: number } => {
+      const a = posedPoint(head.points[0], i);
+      const b = posedPoint(head.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 headBones = new Set([...head.points.flatMap((x) => pointParts(x).map(partBone))]);
+    const ra = series.get(head.joints[0])!;
+    const rb = series.get(head.joints[1])!;
+    const refCentre = (i: number): Pt => [(ra[i]![0] + rb[i]![0]) / 2, (ra[i]![1] + rb[i]![1]) / 2];
+    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]!];
+        if (drawn === undefined || !isRaised(drawn)) continue;
+        const label = `--raised-by-head: set "${set.name}" draws chain "${c.name}" raised (bone "${c.bones[0]}" at ${drawn}°)`;
+        if (c.bones.length !== 2) {
+          p.add('RAISED_CHAIN', `${label}, and the chain has ${c.bones.length} bone(s); the wrist is placed by a two-bone solve, so it must have two (upper arm, forearm)`);
+          continue;
+        }
+        if (c.reach || c.aim.some((x) => x.includes('>'))) {
+          p.add('RAISED_CHAIN', `${label}, and it aims ${JSON.stringify(c.aim)}${c.reach ? ' with "reach"' : ''}; the solve turns each bone about its own origin toward the next point, so each must aim "x" or at one point`);
+          continue;
+        }
+        const [b0, b1] = c.bones as [string, string];
+        const moved = [...headBones].filter((h) => h === b0 || h === b1 || descends(rest, h, b0));
+        if (moved.length > 0) {
+          p.add('RAISED_CHAIN', `${label}, and the head's eye point ${moved.map((h) => `"${h}"`).join(', ')} turns with it; the wrist cannot be placed against a head the arm moves`);
+          continue;
+        }
+        const wristSpec = c.aim[1] === 'x' ? `${b1}:tip` : c.aim[1]!;
+        if (c.aim[1] === 'x' && !(rest.get(b1)!.length > 1e-9)) {
+          p.add('RAISED_CHAIN', `${label}, and its last bone "${b1}" aims "x" with no length; its wrist (the tip) is its origin, so there is nothing to place`);
+          continue;
+        }
+        const wristOf = (i: number): Pt => posedPoint(wristSpec, i);
+        const refWrist = series.get(c.joints[2]!)!;
+        // The unit, each side's median over the span (HQ's ruling).
+        const span: number[] = [];
+        for (let i = s.frames[0]; i <= s.frames[1]; i++) span.push(i);
+        const refEye = median(span.map((i) => Math.hypot(rb[i]![0] - ra[i]![0], rb[i]![1] - ra[i]![1])));
+        const rigEye = median(span.map((i) => eyesOn(i).dist));
+        if (!(refEye > 1e-9) || !(rigEye > 1e-9)) {
+          p.add('RAISED_EYES', `${label}: over frames ${s.frames[0]}–${s.frames[1]} the median eye distance is ${refEye > 1e-9 ? `${rigEye} units on the rig (points "${head.points[0]}", "${head.points[1]}")` : `${refEye}px in the reference (${head.joints[0]}, ${head.joints[1]})`}; an eye distance of 0 is no unit`);
+          continue;
+        }
+        // The rig's own lengths, and each bone's aim against the vector it carries, at setup.
+        const S0 = rigPoint(rest, b0)!;
+        const E0 = rigPoint(rest, b1)!;
+        const W0 = rigPoint(rest, wristSpec)!;
+        const l0 = Math.hypot(E0[0] - S0[0], E0[1] - S0[1]);
+        const l1 = Math.hypot(W0[0] - E0[0], W0[1] - E0[1]);
+        const d0 = wrap(Math.atan2(E0[1] - S0[1], E0[0] - S0[0]) * DEG - restOf.get(b0)!);
+        const d1 = wrap(Math.atan2(W0[1] - E0[1], W0[0] - E0[0]) * DEG - restOf.get(b1)!);
+        const t0 = targets.get(b0)!;
+        const t1 = targets.get(b1)!;
+        const turn0 = set.turn[b0];
+        const turn1 = set.turn[b1];
+        const job: (typeof raisedJobs)[number] = { sw: s, chain: c, wrist: wristOf, before: [], reference: [], placed: [], refEye, rigEye, short: [], upperHeld: [], l0, l1, farthest: 0, eyePoints: head.points };
+        /** Per frame of the span: the forearm's art turn the re-aim asked, and how far past its turn. */
+        const foreAsked: number[] = [];
+        const foreOver: number[] = [];
+        /** Per frame of the span: the upper arm's art turn the solve asked, how far past its turn, and — where the turn held it — how far the wrist ends from its placed point, eye distances (0 elsewhere). */
+        const upperAsked: number[] = [];
+        const upperOver: number[] = [];
+        const heldMiss: number[] = [];
+        for (const i of span) {
+          const h = eyesOn(i);
+          const rc = refCentre(i);
+          // The reference's wrist from its head centre, in its eye distances, y turned up.
+          const ref: Pt = [(refWrist[i]![0] - rc[0]) / refEye, -(refWrist[i]![1] - rc[1]) / refEye];
+          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 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 });
+          // 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);
+          if (sol.upper === null) {
+            foreAsked.push(wrap(t1[i]! - (set.drawn[b1] ?? 0)));
+            foreOver.push(0);
+            upperAsked.push(0);
+            upperOver.push(0);
+            heldMiss.push(0);
+            continue;
+          }
+          let a0 = wrap(sol.upper - d0);
+          let a1 = wrap(sol.fore - d1);
+          // The set's turn holds the upper arm; the forearm is then re-aimed at the placed wrist from where the held upper arm puts the elbow.
+          let held = false;
+          const tt = turn0 === undefined ? 0 : wrap(a0 - set.drawn[b0]!);
+          upperAsked.push(tt);
+          upperOver.push(turn0 === undefined ? 0 : overflow(tt, turn0));
+          if (turn0 !== undefined) {
+            const cl = Math.min(Math.max(tt, turn0[0]), turn0[1]);
+            if (Math.abs(cl - tt) > RANGE_SLACK) {
+              held = true;
+              a0 = wrap(set.drawn[b0]! + cl);
+              job.upperHeld.push(i);
+              const r = (a0 + d0) / DEG;
+              const E: Pt = [shoulder[0] + l0 * Math.cos(r), shoulder[1] + l0 * Math.sin(r)];
+              a1 = wrap(Math.atan2(P[1] - E[1], P[0] - E[0]) * DEG - d1);
+            }
+          }
+          // A forearm the turn still holds: the re-aim failed within the art's range — ART-RANGE.
+          const asked = turn1 === undefined ? 0 : wrap(a1 - set.drawn[b1]!);
+          const over = turn1 === undefined ? 0 : overflow(asked, turn1);
+          foreAsked.push(asked);
+          foreOver.push(over);
+          if (turn1 !== undefined && over > RANGE_SLACK) a1 = wrap(set.drawn[b1]! + Math.min(Math.max(asked, turn1[0]), turn1[1]));
+          // Where the held arm leaves the wrist: the re-aimed forearm points at the placed point, but from a held
+          // elbow its length need not reach it (rule 3, "cannot reach within turn").
+          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);
+          t0[i] = a0;
+          t1[i] = a1;
+        }
+        // A held upper arm whose re-aimed forearm leaves the wrist more than HELD_MISS short of its placed point: ART-RANGE on the upper arm, with the shortfall.
+        if (turn0 !== undefined) {
+          for (const [a, b] of runsOf(heldMiss.map((m) => m > HELD_MISS), RANGE_GAP)) {
+            let worst = a;
+            for (let k = a; k <= b; k++) if (heldMiss[k]! > heldMiss[worst]!) worst = k;
+            const first = s.frames[0] + a;
+            const last = s.frames[0] + b;
+            art.push({ set: set.name, chain: c.name, bone: b0, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(upperOver[worst]!), turn: r3(upperAsked[worst]!), limits: turn0, clamped: true, shortfall: r3(heldMiss[worst]!) });
+          }
+        }
+        if (turn1 !== undefined) {
+          for (const [a, b] of runsOf(foreOver.map((o) => o > RANGE_SLACK), RANGE_GAP)) {
+            let worst = a;
+            for (let k = a; k <= b; k++) if (foreOver[k]! > foreOver[worst]!) worst = k;
+            const first = s.frames[0] + a;
+            const last = s.frames[0] + b;
+            art.push({ set: set.name, chain: c.name, bone: b1, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(foreOver[worst]!), turn: r3(foreAsked[worst]!), limits: turn1, clamped: true });
+          }
+        }
+        raisedJobs.push(job);
+      }
+      art.sort((x, y) => x.frames[0] - y.frames[0]);
+      if (art.length > 0) raisedArt.push({ sw: s, entries: art });
+    }
+  }
+  p.throwIfAny();
+  // The art turn of every span; a raised chain's bones were held by the solve, and only its re-aimed forearm is listed (above).
+  const measured = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+  const solvedBy = (e: ArtRange, s: Switch) => raisedJobs.some((j) => j.sw === s && j.chain.name === e.chain);
+  const artRange: ArtRange[] = [];
+  for (const s of sw.switches) {
+    const own = measured.filter((e) => e.set === s.set && e.frames[0] >= s.frames[0] && e.frames[1] <= s.frames[1]);
+    artRange.push(...own.filter((e) => !solvedBy(e, s)), ...(raisedArt.find((x) => x.sw === s)?.entries ?? []));
+  }
   clampArt(sw.switches, map, targets);
+  // Where each raised wrist lands as keyed: after the solve and the set's `turn`.
+  for (const job of raisedJobs) {
+    const after: Pt[] = [];
+    for (let i = job.sw.frames[0]; i <= job.sw.frames[1]; i++) {
+      const a = posedPoint(job.eyePoints[0], i);
+      const b = posedPoint(job.eyePoints[1], i);
+      const w = job.wrist(i);
+      after.push([(w[0] - (a[0] + b[0]) / 2) / job.rigEye, (w[1] - (a[1] + b[1]) / 2) / job.rigEye]);
+    }
+    const worst = (rig: readonly Pt[]): Pt => [Math.max(...rig.map((v, k) => Math.abs(v[0] - job.reference[k]![0]))), Math.max(...rig.map((v, k) => Math.abs(v[1] - job.reference[k]![1])))].map(r6) as Pt;
+    const round = (vs: readonly Pt[]): Pt[] => vs.map((v) => [r6(v[0]), r6(v[1])]);
+    const short: ReachShort[] = [];
+    for (let k = 0; k < job.short.length;) {
+      let m = k;
+      while (m + 1 < job.short.length && job.short[m + 1]!.i === job.short[m]!.i + 1 && job.short[m + 1]!.how === job.short[k]!.how) m++;
+      const fs = job.short.slice(k, m + 1).map((x) => x.shortfall);
+      short.push({ frames: [job.short[k]!.i, job.short[m]!.i], how: job.short[k]!.how, shortfall: { max: r6(Math.max(...fs)), median: r6(median(fs)) } });
+      k = m + 1;
+    }
+    raised.push({
+      set: job.sw.set,
+      chain: job.chain.name,
+      frames: job.sw.frames,
+      seconds: secondsOf(job.sw.frames),
+      eyes: { rig: r6(job.rigEye), reference: r6(job.refEye) },
+      reference: round(job.reference),
+      placed: round(job.placed),
+      before: round(job.before),
+      after: round(after),
+      worst: { before: worst(job.before), after: worst(after), placed: r6(Math.max(...after.map((v, k) => Math.hypot(v[0] - job.placed[k]![0], v[1] - job.placed[k]![1])))) },
+      short,
+      upperHeld: job.upperHeld,
+      reach: { min: r6(Math.abs(job.l0 - job.l1)), max: r6(job.l0 + job.l1), farthest: r6(job.farthest) },
+    });
+  }
 
   // The legs on their final targets: a bone under a scaled bone is keyed through
   // its parent's posed matrix (legs.ts), and each ankle's world position is read.
@@ -854,10 +1110,34 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs),
+    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised,
   };
 }
 
+/** The head as --raised-by-head reads it: the chain carrying the eye line, its two pose joints and the rig's two eye points. */
+interface Head {
+  chain: string;
+  joints: [string, string];
+  points: [string, string];
+}
+
+/** The map's head chain (the one carrying r_eye → l_eye, either way round) and its "a>b" aim; or why there is none to read. */
+function headOf(map: JointMap): Head | { problem: string } {
+  const lead = '--raised-by-head places a raised arm\'s wrist against the head in eye distances, read on the rig between the two points the head chain\'s "a>b" aim names';
+  for (const c of map.chains) {
+    for (let k = 0; k + 1 < c.joints.length; k++) {
+      const a = c.joints[k]!;
+      const b = c.joints[k + 1]!;
+      if (!((a === 'r_eye' && b === 'l_eye') || (a === 'l_eye' && b === 'r_eye'))) continue;
+      const aim = c.aim[k]!;
+      if (!aim.includes('>')) return { problem: `${lead}; chain "${c.name}" carries ${a} → ${b} on bone "${c.bones[k]}", and aims it ${JSON.stringify(aim)}, not "a>b" between the rig's eye points` };
+      const [pa, pb] = aimEnds(c.bones[k]!, aim);
+      return { chain: c.name, joints: [a, b], points: [pa, pb] };
+    }
+  }
+  return { problem: `${lead}; no chain of the map carries the eye line (joints r_eye → l_eye), so the rig has no eye points to measure` };
+}
+
 type ShortSpan = Omit<Short, 'chain' | 'bone' | 'joints'>;
 
 /**

package/src/run.ts

@@ -14,7 +14,7 @@ import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
-import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
+import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf } from './legs.ts';
 import { reduceKeys, type ReduceBone, type Reduced } from './reduce.ts';
@@ -108,7 +108,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
+    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
     if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
@@ -130,6 +130,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
+    if (a.raisedByHead === true && r.raised.length === 0) say(`  RAISED none — no set drawing an arm within ${RAISED_WITHIN}° of straight up showed; no key moved`);
+    for (const e of r.raised) say(`  RAISED ${raisedLine(e, r.times)}`);
+    for (const e of r.raised) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
     for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times)}`);
     if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
@@ -273,7 +276,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         frames: seq.frames.length,
         duration: r.animation.duration,
         cleaned: seq.cleaned,
-        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -289,6 +292,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         turns: r.turns,
         range: r.range,
         artRange: r.artRange,
+        raised: r.raised,
         legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
         pivot: r.pivot,
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, bounds: r.stance.bounds, runs: r.stance.runs, over: r.stance.over },

package/src/switch.ts

@@ -129,6 +129,8 @@ export interface ArtRange {
   limits: [number, number];
   /** Whether the bone was held at the limit (the set's `turn`) or followed the pose (its chain's `range` only). */
   clamped: boolean;
+  /** --raised-by-head (#62): on a held upper arm, the most the re-aimed forearm left the wrist short of its placed point, eye distances; `turn` and `maxOverflow` are then the upper arm's on that frame. */
+  shortfall?: number;
 }
 
 export interface Uncovered {
@@ -580,6 +582,9 @@ function moveText(m: Move): string {
 }
 
 export function artRangeLine(e: ArtRange, times: readonly number[]): string {
+  if (e.shortfall !== undefined) {
+    return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" held at its turn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s the re-aimed forearm leaves the wrist up to ${e.shortfall.toFixed(2)} eye distances short of its placed point (the upper arm asked ${sg(e.turn)} from drawn, ${deg(e.maxOverflow)} past) — demand for another drawing of the set`;
+  }
   return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it; ${e.clamped ? 'held at the limit' : 'the bone follows the pose'} — demand for another drawing of the set`;
 }
 
@@ -603,3 +608,162 @@ export function clampArt(switches: readonly Switch[], map: JointMap, targets: Ma
     }
   }
 }
+
+/**
+ * A set's arm is raised (rig-c/pose#62) when its `drawn` world angle on the
+ * chain's first bone (the upper arm) is within this many degrees of straight up.
+ */
+export const RAISED_WITHIN = 30;
+
+/** 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;
+
+type P2 = [number, number];
+
+/**
+ * A two-bone solve in the world (y up): the directions, degrees, of the vector
+ * from the shoulder to the elbow (`upper`) and from the elbow to the wrist
+ * (`fore`) that put the wrist on `target`, for bones of lengths `l0` and `l1`.
+ * `side` is the elbow's bend: +1 when the forearm turns counter-clockwise from
+ * the upper arm, −1 clockwise. Out of reach (farther than l0 + l1, nearer than
+ * |l0 − l1|, beyond a relative 1e-6) both point straight at the target and
+ * `reached` is false; on the shoulder, where there is no direction, `upper` is
+ * null. `reachLimit` puts a target inside first, so the raised solve always reaches.
+ */
+export function twoBone(shoulder: P2, target: P2, l0: number, l1: number, side: 1 | -1): { upper: number; fore: number; reached: boolean } | { upper: null; reached: false } {
+  const dx = target[0] - shoulder[0];
+  const dy = target[1] - shoulder[1];
+  const d = Math.hypot(dx, dy);
+  if (d < 1e-9) return { upper: null, reached: false };
+  const theta = Math.atan2(dy, dx) * (180 / Math.PI);
+  const eps = 1e-6 * Math.max(1, l0 + l1);
+  if (d > l0 + l1 + eps || d < Math.abs(l0 - l1) - eps) return { upper: theta, fore: theta, reached: false };
+  const cos = Math.min(1, Math.max(-1, (l0 * l0 + d * d - l1 * l1) / (2 * l0 * d)));
+  const upper = theta - side * Math.acos(cos) * (180 / Math.PI);
+  const r = upper * (Math.PI / 180);
+  const ex = shoulder[0] + l0 * Math.cos(r);
+  const ey = shoulder[1] + l0 * Math.sin(r);
+  return { upper: wrap(upper), fore: Math.atan2(target[1] - ey, target[0] - ex) * (180 / Math.PI), reached: true };
+}
+
+/** Where a raised wrist is placed: the target itself, or the reach limit (rig-c/pose#62, HQ's ruling). */
+export interface Placement {
+  point: P2;
+  /** `in`: the target is within reach. `far` / `near`: past l0 + l1, or nearer than |l0 − l1|, and placed on the ray from the head centre. `missed`: that ray never enters the reach; placed at the reach's point nearest the target. */
+  how: 'in' | 'far' | 'near' | 'missed';
+}
+
+/**
+ * The raised wrist's placement. The arm reaches the annulus about the shoulder
+ * between |l0 − l1| and l0 + l1. A target inside it is kept. Otherwise the wrist
+ * goes on the ray from the head centre through the target, at the point of
+ * that ray inside the annulus nearest the target — the reach limit along the
+ * head-relative direction. The ray can cross the annulus twice (out and back
+ * through the inner disc, or through the whole ring): of the reachable stretches
+ * the one nearest the target wins, a tie going to the point nearer the head. A
+ * ray that never enters it (`missed`) gives the annulus point nearest the
+ * target, on the line from the shoulder through it (toward the head centre when
+ * the target is on the shoulder).
+ */
+export function reachLimit(centre: P2, target: P2, shoulder: P2, l0: number, l1: number): Placement {
+  const rMin = Math.abs(l0 - l1);
+  const rMax = l0 + l1;
+  const eps = 1e-9 * Math.max(1, rMax);
+  const dT = Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]);
+  if (dT >= rMin - eps && dT <= rMax + eps) return { point: target, how: 'in' };
+  const how = dT > rMax ? 'far' : 'near';
+  const vx = target[0] - centre[0];
+  const vy = target[1] - centre[1];
+  const L = Math.hypot(vx, vy);
+  if (L > 1e-9) {
+    const u: P2 = [vx / L, vy / L];
+    // |C + s·u − S|² = s² + 2·s·b + c
+    const b = u[0] * (centre[0] - shoulder[0]) + u[1] * (centre[1] - shoulder[1]);
+    const c = (centre[0] - shoulder[0]) ** 2 + (centre[1] - shoulder[1]) ** 2;
+    const roots = (r: number): [number, number] | null => {
+      const disc = b * b - c + r * r;
+      return disc < 0 ? null : [-b - Math.sqrt(disc), -b + Math.sqrt(disc)];
+    };
+    const outer = roots(rMax);
+    const stretches: Array<[number, number]> = [];
+    if (outer !== null) {
+      const lo = Math.max(0, outer[0]);
+      const hi = outer[1];
+      const inner = rMin > 0 ? roots(rMin) : null;
+      if (hi >= lo) {
+        if (inner === null || inner[1] <= lo || inner[0] >= hi) stretches.push([lo, hi]);
+        else {
+          if (inner[0] > lo) stretches.push([lo, inner[0]]);
+          if (inner[1] < hi) stretches.push([inner[1], hi]);
+        }
+      }
+    }
+    let best: number | null = null;
+    for (const [lo, hi] of stretches) {
+      const s = Math.min(Math.max(L, lo), hi);
+      if (best === null || Math.abs(s - L) < Math.abs(best - L) - 1e-9 || (Math.abs(Math.abs(s - L) - Math.abs(best - L)) <= 1e-9 && s < best)) best = s;
+    }
+    if (best !== null) return { point: [centre[0] + best * u[0], centre[1] + best * u[1]], how };
+  }
+  const from: P2 = dT > 1e-9 ? target : centre;
+  const k = Math.hypot(from[0] - shoulder[0], from[1] - shoulder[1]) || 1;
+  const r = Math.min(Math.max(dT, rMin), rMax);
+  return { point: [shoulder[0] + (r * (from[0] - shoulder[0])) / k, shoulder[1] + (r * (from[1] - shoulder[1])) / k], how: 'missed' };
+}
+
+/** A run of frames whose target was out of reach, one way. */
+export interface ReachShort {
+  frames: [number, number];
+  how: 'far' | 'near' | 'missed';
+  /** |target − placed| in the rig's eye distances: the most, and the median, over the run. */
+  shortfall: { max: number; median: number };
+}
+
+/** One span of a raised set on one chain: its wrist placed against the head (rig-c/pose#62). */
+export interface Raised {
+  set: string;
+  chain: string;
+  frames: [number, number];
+  seconds: number;
+  /** The unit: the eye distance's median over the span, the rig's in world units, the reference's in picture px. */
+  eyes: { rig: number; reference: number };
+  /**
+   * Per frame of the span, the wrist's offset from the head centre in eye
+   * distances (x right, y up): the reference's; where the wrist was placed (the
+   * target, or the reach limit); the rig's on the pose's angles; the rig's as
+   * keyed.
+   */
+  reference: P2[];
+  placed: P2[];
+  before: P2[];
+  after: P2[];
+  /** The largest |rig − reference| over the span, x and y, before and after; and the largest |after − placed|, eye distances. */
+  worst: { before: P2; after: P2; placed: number };
+  /** The runs of frames out of the arm's reach (the REACH line). */
+  short: ReachShort[];
+  /** The frames whose upper arm the set's `turn` held: the forearm re-aimed at the placed wrist. */
+  upperHeld: number[];
+  /** The arm's reach (from |l0 − l1| to l0 + l1, world units from the shoulder) and the farthest target from the shoulder over the span. */
+  reach: { min: number; max: number; farthest: number };
+}
+
+const xy = (v: P2) => `(${v[0].toFixed(2)}, ${v[1].toFixed(2)})`;
+const framesText = (fs: readonly number[]): string => {
+  const flag: boolean[] = [];
+  for (const f of fs) flag[f] = true;
+  return runsOf(Array.from({ length: flag.length }, (_, i) => flag[i] === true), 0).map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
+};
+
+export function raisedLine(e: Raised, times: readonly number[]): string {
+  const med = (vs: readonly P2[]): P2 => [median(vs.map((v) => v[0])), median(vs.map((v) => v[1]))];
+  const held = e.upperHeld.length === 0 ? 'the upper arm within its turn on every frame' : `the upper arm held by the set's turn on ${e.upperHeld.length} frame(s) (${framesText(e.upperHeld)}), the forearm re-aimed`;
+  const out = e.short.length === 0 ? 'every target in reach' : `out of reach on ${e.short.reduce((k, s) => k + s.frames[1] - s.frames[0] + 1, 0)} frame(s) (REACH)`;
+  return `set "${e.set}" chain "${e.chain}" ${spanOf(e.frames, times)}: the wrist placed against the head; eye distance (median) rig ${e.eyes.rig.toFixed(2)} units, reference ${e.eyes.reference.toFixed(2)} px; wrist − head centre in eye distances (x right, y up), median reference ${xy(med(e.reference))}, placed ${xy(med(e.placed))}, before ${xy(med(e.before))}, after ${xy(med(e.after))}; worst |rig − reference| before ${xy(e.worst.before)}, after ${xy(e.worst.after)}; worst |after − placed| ${e.worst.placed.toFixed(2)}; ${held}; ${out}`;
+}
+
+/** The REACH line: a raised span whose target was out of the arm's reach on some frames — the proportions, not the art's range, were the limit. */
+export function reachLine(e: Raised, times: readonly number[]): string {
+  const why = { far: `farther than l0 + l1 = ${e.reach.max.toFixed(1)}`, near: `nearer than |l0 − l1| = ${e.reach.min.toFixed(1)}`, missed: 'and the ray from the head centre never enters the reach; placed at the reach\'s point nearest it' } as const;
+  const runs = e.short.map((s) => `${spanOf(s.frames, times)} ${s.how === 'missed' ? 'out of reach' : why[s.how]}${s.how === 'missed' ? `, ${why.missed}` : ''}: up to ${s.shortfall.max.toFixed(2)} eye distances short (median ${s.shortfall.median.toFixed(2)})`);
+  return `set "${e.set}" chain "${e.chain}": the target out of the arm's reach from the shoulder — ${runs.join('; ')}; the wrist placed at the reach limit along the head-relative direction (the farthest target ${e.reach.farthest.toFixed(1)} units from the shoulder). Not ART-RANGE: the rig's proportions, not the art's range, were the limit`;
+}