@rig-c/pose 0.20.4 → 0.21.0

package/README.md

@@ -143,6 +143,7 @@ and what the run cannot decide for you it lists:
 - `SHEAR` — with `--leg-scale`: every scaled bone and every bone under one, how far its art is sheared and how long its world axes are against setup. A reading.
 - `IDLE`, `IDLE-DROPPED`, `IDLE-KEPT-OUT`, `MERGE` — the rig's idle against the new animation, and what `--carry-idle` and `--merge` put back ([below](#the-idle-what-the-retarget-drops)).
 - `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total.
+- `FACE` — with `face` in the map ([#138](https://github.com/rig-c/pose/issues/138)): per-frame yaw and pitch read from `nose` against the eye midpoint (`r_eye + l_eye`) and, when present, the ear midpoint (`r_ear + l_ear`), de-rolled by the eye line, then compressed into each configured axis's `[min, max]` range (`scale` and correlation `r`), and written as `face` in `--report`.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
 `--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `frames`, `duration`, `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
@@ -195,19 +196,19 @@ Re-checked on the exam01 test rig with `--short 0.35 --flip 90 --bends clamp`. O
 
 A knee bending toward the camera is seen from the front only as a shorter leg, and a rig with rigid legs cannot lower its hip without lifting its feet ([#47](https://github.com/rig-c/pose/issues/47)). Two flags, both off by default:
 
-**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the 95th percentile of its picture length over the sequence, clamped to [min, max]. The card's range is `0.8,1.05`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit.
+**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the larger of the two sides' 95th-percentile picture lengths for that segment over the sequence ([#148](https://github.com/rig-c/pose/issues/148); on a non-`in-place` sequence longer than 25 frames, each frame's segment length is normalised by the rolling 25-frame median trunk length over the sequence median so residual camera zoom does not shrink earlier phrases against a zoomed-in ending, and the shared thigh + shin straight lengths are capped at the larger 95th-percentile whole-leg `hip → ankle` length so a drifting knee split does not inflate their sum, [#159](https://github.com/rig-c/pose/issues/159)), clamped to [min, max]. The card's range is `0.8,1.05`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit.
 
-rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inherit mode takes its parent's whole world matrix. So under a thigh scaled by s, a shin at angle φ in the thigh's axes points at atan2(sin φ, s·cos φ), and is itself scaled by |(s·cos φ, sin φ)|. The rotate key `turn − turn above` assumes unit scale. A mapped bone under a scaled bone is therefore keyed through its parent's posed matrix: a `rotate` key k and a `scalex` key s' make its local matrix R(k) · L · diag(s', 1), L its setup local matrix, and k and s' are solved so its world x axis lands on its target at the scale asked. On HQ's dancer the unit-scale formula missed the shins by up to 2.4°, their length by 0.16 of setup and the ankles by 38 units; solved, every bone lands. The child's art is still sheared by its parent's scale, and a bone under it (a foot) is squashed along the shin: `SHEAR` reads both.
+rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inherit mode takes its parent's whole world matrix. So under a thigh scaled by s, a shin at angle φ in the thigh's axes points at atan2(sin φ, s·cos φ), and is itself scaled by |(s·cos φ, sin φ)|. A child (or its intermediate control bone) with `noScale` or `noScaleOrReflection` ([#153](https://github.com/rig-c/pose/issues/153)) still has its direction carried through the parent's scaled matrix, so its angle is skewed the same way, while rig-c normalises that direction to unit length so the parent's scale is not inherited. The rotate key `turn − turn above` assumes unit scale. A mapped bone under a scaled bone is therefore keyed through its parent's posed matrix: a `rotate` key k and a `scalex` key s' put its world x axis on its target at the scale asked (under `noScale`, s' is the bone's own asked scale s directly). On HQ's dancer the unit-scale formula missed the shins by up to 2.4°, their length by 0.16 of setup and the ankles by 38 units; solved, every bone lands. A `normal` child's art is still sheared by its parent's scale, and a bone under it (a foot) is squashed along the shin: `SHEAR` reads both.
 
 **`--plant-feet`** places the hip so the supporting foot stays where it took support, through the posed legs at the scale the pose asked for (when a segment asks for a scale below `--leg-scale`'s clamp floor, the clamp does not lift the hip by what it withheld, [#107](https://github.com/rig-c/pose/issues/107); on a supporting leg, the segment's `scalex` follows the asked scale down to the bound #95 derives from the leg's own range so the supporting ankle stays on #85's floor while the free leg keeps the configured clamp, and any frame clamped at #95's bound lifts the hip by the remainder so the ankle never sinks, listed as `LEG-SCALE past the floor (support)`, [#133](https://github.com/rig-c/pose/issues/133)), instead of moving it by the pose's mid_hip travel:
 
 - The supporting foot is the one whose reference ankle is lower in the picture. It changes only when the other ankle has been at least **0.02 leg lengths** lower for at least **0.1 s** (timed as `END-ON` runs are), and once confirmed takes support from the frame it crossed that margin ([#102](https://github.com/rig-c/pose/issues/102)); a leg length is each side's median picture length hip → ankle, and the switch compares against their mean.
 - The new support is held where it is on the frame it takes over, and the hip blends in y from the old derivation to the new over **3 frames** while taking the new derivation's x immediately ([#102](https://github.com/rig-c/pose/issues/102)), so the planted foot does not slide across the blend.
-- A **jump** — both reference ankles **and** mid_hip more than **0.05** leg lengths above their **rolling floor**, the 95th-percentile picture y over ±1.0 s around the frame, for at least **2 frames** — releases the plant: the hip follows the pose's travel from where it was, and re-plants on landing (blended the same way). At a walking hand-over the front foot has not landed yet while the back ankle lifts its heel and the hip rises 0.051–0.065 leg lengths; when the front foot lands while the back ankle stays above its floor, a back ankle that holds its height in y (< **0.01** leg lengths a frame for **2 frames**) is on a raised heel rather than in flight and is not read as a jump ([#101](https://github.com/rig-c/pose/issues/101)). The body has to lift: an ankle's picture y drifts with depth, and under one floor for the whole sequence HQ's dancer standing still (frames 0–29 and 277–312, mid_hip moving 10 and 14 px) read as jumping, 152–155 of 313 frames in all.
+- A **jump** — both reference ankles **and** mid_hip more than **0.05** leg lengths above their **rolling floor**, the 95th-percentile picture y over ±1.0 s around the frame, for at least **2 frames**, starting from the first immediately preceding push-off frame where both ankles are already above their rolling floor while mid_hip lags ([#142](https://github.com/rig-c/pose/issues/142)) — releases the plant: the hip follows the pose's travel from where it was, and re-plants on landing (blended the same way). At a walking hand-over the front foot has not landed yet while the back ankle lifts its heel and the hip rises 0.051–0.065 leg lengths; when the front foot lands while the back ankle stays above its floor, a back ankle that holds its height in y (< **0.01** leg lengths a frame for **2 frames**) is on a raised heel rather than in flight and is not read as a jump ([#101](https://github.com/rig-c/pose/issues/101)). The body has to lift: an ankle's picture y drifts with depth, and under one floor for the whole sequence HQ's dancer standing still (frames 0–29 and 277–312, mid_hip moving 10 and 14 px) read as jumping, 152–155 of 313 frames in all.
 - **In place** ([#92](https://github.com/rig-c/pose/issues/92)). On a sequence with `"travel": "in-place"`, the supporting foot of a figure that does not travel moves back in the picture while the body stays. Holding it where it planted turns that slide into the body's travel, so the hip walks off and never comes back. Under the declaration each plant's anchor follows its own ankle's picture x, scaled into the rig, from the frame it planted, and keeps its y on the one floor. No step releases a foot, since a foot that follows its track has no plant to drag. Every foot may take support, and the lower one does, by the rules above. The loop is then closed: the hip's x on frame i moves by −drift · i / (n − 1), where drift is its x on the last frame less its x on the first. The last frame's hip x is then the first's, and the loop carries no net travel. The y is the floor's and is not touched. `FEET` prints the drift closed, in place of the steps line, and the report's `feet.closure` carries `{ drift, frames }` (`null` otherwise). On the tests' synthetic in-place loop (40 frames, each supporting ankle sliding back 2 px a frame, the hips still), the hip moves less than 10⁻⁹ px. The same joints without the declaration put it 68 px forward over the loop. With a slide of 0.04 leg lengths a frame, both feet are released as stepping and never re-plant without the declaration, and the supports alternate with it. Jumps are read as before.
 - A **step** releases the plant too: while the supporting ankle moves more than **0.03** leg lengths a frame, the other foot takes support if it is planted (not itself released or moving), and otherwise the hip follows the pose's travel. The released ankle may support again once it has moved less than **0.01** leg lengths a frame for **2 frames**. On the dancer the plant held the supporting ankle through a real step (frames 176–181, 579 → 718 px) and threw the hip sideways.
 - **Read from the lower ankle** ([#113](https://github.com/rig-c/pose/issues/113), [#119](https://github.com/rig-c/pose/issues/119)). On a sequence not declared `"in-place"`, a foot whose ankle is at least **0.02 leg lengths** higher in the picture than the other's never takes support: not when a plant starts, and not when a step releases the other foot. Before, a step handed support to the only foot free to take it, even a folded, lifted one, and the hip was then placed under a foot in the air. A supporting foot that the other ankle has been that much lower than for **0.1 s** hands support to it when it may take it, as before; when the lower foot may not (it is released and not yet still, or moving), the supporting foot is released, and the hip follows the pose's travel until a foot may take support. On a frame after a jump or a step's release where the only foot free under #113 is the higher one (`cause: "higher"`), the lower foot supports **tracked, not planted** ([#119](https://github.com/rig-c/pose/issues/119)): the hip puts it on #85's floor and follows its scaled ankle track (`FEET tracked`, `feet.tracked`) until it has been still for 2 frames (`< 0.01`), when the normal plant takes over at that position. Steps and jumps are read as before, and under `"in-place"` #92's reading stands. `FEET support read from the lower ankle` names every run of frames whose support differs from the reading before #113, the side before and after (`none`: no foot supports), and for each `none` why: `released`, the supporting foot let go because the lower ankle could not take support (released by a step, or moving), or the only foot free to take support was the higher one. The report's `feet.lowered` holds them as `{ frames, was, now, cause }` (absent in place). On the tests' synthetic step under a lifted leg (the lifted ankle 0.2 leg lengths up, the grounded one stepping 0.05 leg lengths on frame 10 and still from 11), the lifted leg took support on frames 10–11 before; now frames 10–11 track the lower foot on the floor (`feet.tracked`) and the grounded one is planted from 12, when it is still again.
-- **One floor** ([#85](https://github.com/rig-c/pose/issues/85)). A 2D rig has no depth, so its floor is one line, and a planted foot is on it. The picture disagrees: a step toward the camera puts the foot lower in the frame, and a camera residual puts a whole span higher, so a plant held where the picture puts each span leaves the floor stepping between spans. Every support span's supporting ankle is therefore moved in y onto one floor, the hip and everything above with it. A span's *planted height* is the world y (on the rig, posed by rig-c) its supporting ankle would be held at; the floor is the median of the spans' planted heights, or **`--floor <y>`** (world units, y up; only with `--plant-feet`, exit 2 without it). Each span's *shift* is floor − its planted height. A change of support still blends the hip over the 3 frames, now between two spans on the floor, and a planted foot does not leave the floor: on each blend frame the **supporting** leg is stretched along its chain about its root, by the factor `--stance` uses, k = (root y − floor y) / (root y − ankle y), held within **[0.92, 1.08]**, its lower bound on the frame the supporting leg's own range as `--stance`'s ([#95](https://github.com/rig-c/pose/issues/95); where that went below 0.92, a `FEET bound from the leg's own range` line, the report's `feet.blend.range`, and each blend run's `lower`). A frame that needs more is held at the bound, the rest left to the blend, and listed `FEET past the bounds` with the k needed and how far the foot was left from the floor. An ankle already within 0.01 units (the landing check's origin tolerance) is not stretched. The stretched scales are scale targets, so the landing check holds them; `--stance` then stretches the free leg, a different chain, to the supporting ankle. A jump follows the pose's travel from the hip it left, which is on the floor, carried linearly from take-off so the landing frame meets the floor and clamped so no frame inside the flight puts a foot below it ([#103](https://github.com/rig-c/pose/issues/103)), and is held the same way over its first 3 planted frames. `--stance` is unchanged: it stretches the free leg to the supporting ankle, which is on the floor. On the tests' synthetic stick, three spans 0, 6 and 1 px apart in the picture (0, 9 and 1.5 units on the rig) plant within 0.0001 units of one floor. With the shift forced to 0 they stay 9 units apart; without the stretch, the supporting ankle leaves the floor by 6.75 units on the first blend frame.
+- **One floor** ([#85](https://github.com/rig-c/pose/issues/85)). A 2D rig has no depth, so its floor is one line, and a planted foot is on it. The picture disagrees: a step toward the camera puts the foot lower in the frame, and a camera residual puts a whole span higher, so a plant held where the picture puts each span leaves the floor stepping between spans. Every support span's supporting ankle is therefore moved in y onto one floor, the hip and everything above with it. A span's *planted height* is the world y (on the rig, posed by rig-c) its supporting ankle would be held at; the floor is the median of the spans' planted heights, or **`--floor <y>`** (world units, y up; only with `--plant-feet`, exit 2 without it). Each span's *shift* is floor − its planted height. A change of support still blends the hip over the 3 frames, now between two spans on the floor, and a planted foot does not leave the floor: on each blend frame the **supporting** leg is stretched along its chain about its root, by the factor `--stance` uses, k = (root y − floor y) / (root y − ankle y), held within **[0.92, 1.08]**, its lower bound on the frame the supporting leg's own range as `--stance`'s ([#95](https://github.com/rig-c/pose/issues/95); where that went below 0.92, a `FEET bound from the leg's own range` line, the report's `feet.blend.range`, and each blend run's `lower`). A frame that needs more is held at the bound, the rest left to the blend, and listed `FEET past the bounds` with the k needed and how far the foot was left from the floor. An ankle already within 0.01 units (the landing check's origin tolerance) is not stretched. The stretched scales are scale targets, so the landing check holds them; `--stance` then stretches the free leg, a different chain, to the supporting ankle. A jump follows the pose's travel from the hip it left, which is on the floor, carried linearly from take-off so the landing frame meets the floor and clamped so no frame inside the flight puts a foot below it ([#103](https://github.com/rig-c/pose/issues/103)), and is held the same way over its first 3 planted frames, with the flight's carry held across the landing blend so it fades out with the blend weights rather than dropping on the first frame after landing ([#147](https://github.com/rig-c/pose/issues/147)). `--stance` is unchanged: it stretches the free leg to the supporting ankle, which is on the floor. On the tests' synthetic stick, three spans 0, 6 and 1 px apart in the picture (0, 9 and 1.5 units on the rig) plant within 0.0001 units of one floor. With the shift forced to 0 they stay 9 units apart; without the stretch, the supporting ankle leaves the floor by 6.75 units on the first blend frame.
 - `FEET` lists the supports, the jumps and the steps (each with the side, its frames, who took support and where it re-planted; in place, the loop's closure instead), and with `--plant-feet` the floor: its world y and where it came from, each span's shift in units and in that side's rig leg at setup (thigh origin → ankle), and the shifts' range, then one line per run of blend frames whose supporting leg was stretched (`blend held on the floor`) and per run `past the bounds`. The report carries them under `feet` (`supports`, `jumps`, `steps`, `changes`, `floor`, `shifts`, `blend`, `closure`).
 - **`--stance <leg lengths>`** (only with `--plant-feet`, which it is refused without; off by default) plants **both** feet when the free one is near the floor ([#60](https://github.com/rig-c/pose/issues/60)). On a frame with a supporting side (so outside every jump), the free ankle's height above the supporting one is read in the picture, in the free side's leg length — the leg length `FEET` uses. The tolerance is a **distance** ([#114](https://github.com/rig-c/pose/issues/114)): within it, above the supporting ankle or below it, the frame is **planted both**: every bone of the free leg's chain has its `scalex` key multiplied by k = (root y − floor y) / (root y − ankle y) on the posed rig, the root being the chain's first bone's origin and the floor the supporting ankle, so the foot reaches the floor. A free ankle within the tolerance below the supporting one is planted too: its k is under 1, since a foot slightly under the floor is the same fault as one floating above it. A free ankle **past the tolerance below** the supporting one is not a stance but a support error (the foot read as supporting is the one in the air), so that frame is never planted both and keeps the pose's height; it is named on a `STANCE past the tolerance below` line with the side, the frames and the largest distance, and read `"below"` in the report's `stance.runs`. Before #114 the gap was signed, so any free ankle below the supporting one counted as within, and a lifted foot read as supporting had the grounded leg shrunk up to it. On the tests' synthetic stance, a free ankle 0.5 leg lengths below is read below and not planted; one 0.03 below is planted with k under 1. k is held within **[0.92, 1.08]**, except that the lower bound comes from the leg's own range in the sequence ([#95](https://github.com/rig-c/pose/issues/95)): per side, r = the leg's picture length hip → ankle on the frame ÷ its straight length (the 95th percentile of that length, as `--leg-scale` reads a segment's), and the frame's lower bound is min(0.92, r), so the rig leg may fold as far as the picture folds it on that frame and never less far than 0.92. The upper bound stays 1.08, since a picture leg does not read longer than straight. A sequence whose legs never fold below 0.92 keeps exactly [0.92, 1.08]. Where the range set a bound below 0.92 on a planted-both frame, one `STANCE bound from the leg's own range` line gives each side's lowest, as does the report's `stance.range`. A frame past its bound is listed `past the bounds` with the bound it had, held at the bound and not forced. Past the tolerance above, the foot is **lifted** and keeps the pose's height. The state is read with **hysteresis** and a **shortest run** ([#87](https://github.com/rig-c/pose/issues/87)), on the distance: a planted foot leaves the stance when its distance from the supporting one goes past the tolerance, and one past it is planted again only under **0.8** of it (both figures are on the `STANCE` line). A change of state takes effect only when its condition holds for **0.1 s** (by the frames' times). A shorter crossing with the other state on both sides of it keeps their state and is listed `absorbed` with its frames and the height that crossed (`absorbed: true` in the report's `stance.runs`, beside the run that took it in). One that runs to the end of a support span is taken, since nothing of the other state follows it. A threshold read frame by frame turned noise at the threshold into a pop: one frame at 0.0708 against 0.07 dropped the stretch for one frame and the foot jumped up and back. The stretched scales are the scale targets, so the landing check holds them. Measured with `--stance 0.07` and HQ's flags (`--smooth 7 --flip 90 --short 0.35 --bends clamp --leg-scale 0.8,1.05 --plant-feet --carry-idle`): on HQ's dancer, frames 94–175 outside the jumps, the free ankle's height above the supporting one on the posed build went from median 18.3 and p90 25.4 units to 0.0 and 0.0. On a second sequence (Toca, 492 frames at 30 fps) the 29 frames labelled by eye as both feet flat, outside the jumps, read 0.0 and 0.0. Of the 6 labelled one foot lifted, 5 stay above the tolerance; the sixth (frame 360) was 0.042 leg lengths up in the picture, within the tolerance, and so planted; without `--stance` it stood 6.5 units up, also under the tolerance (22.6 units there). That is 83 %, under the 90 % the card asked.
 - The map needs one chain ending at each ankle whose last bone is aimed `"x"` (the ankle is that bone's tip), and a `translate` the legs hang from (`LEGS_MAP`). A `range`, or a set's `turn` or `offsets`, on a bone between the hip and an ankle is refused (`LEGS_RANGE`): the plant is derived before the range clamp, and a clamp after it would move the planted foot.
@@ -312,6 +313,7 @@ Which bones carry which joints. You write it for your rig:
   ⚠️ **Seen from the front, an elbow's side is not a joint limit.** An elbow flexes toward the camera, and its picture falls on either side of the upper arm depending on how the arm is turned. On a real 13 s front-facing dance (313 frames, RTMPose), the right elbow sat on the "wrong" side of the rig's rest on 165 frames (median 23°), and the left on 200 (median 29°, up to 179° with the hands behind the head). Every one was a real elbow bend. The knees strayed at most 8.8° and 14.7°, which is pose noise around a straight leg. So for front-facing material, arms go `"free"`. Legs on `"rest"` with `--bends clamp` hold only while the knees stay near straight. On a second dance with knee bends (Toca Toca, rig-c/pose#27), that setting straightened the left knee for most of the dance: `leg_l1` was 48.3° off at p90, against 0.0–0.3° with free legs. Leave legs `"free"` unless the dance keeps its knees straight.
 - `mid_hip` and `mid_shoulder` are the midpoints of the two hips and the two shoulders.
 - `translate.scale` is one length measured on both: two points on the rig, two points in the pose (its median over the frames where both are good). Pick a long segment that does not foreshorten much.
+- `face` (optional, [#138](https://github.com/rig-c/pose/issues/138)): `{ "yaw"?: { "bone": "yaw", "range": [-15, 15] }, "pitch"?: { "bone": "pitch", "range": [-10, 15] } }` (`min ≤ 0 ≤ max`, `min < max`). Reads per-frame yaw and pitch from `nose` against `r_eye + l_eye` (and `r_ear + l_ear` when present), compresses each axis into its declared range so peaks are scaled rather than clipped flat, and keys the named dial bone's `rotate` track (`FACE`).
 
 ### A joint's range: `range`
 

package/package.json

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

package/src/face.ts

@@ -0,0 +1,221 @@
+/**
+ * Face direction (`rig-c/pose#138`): read yaw and pitch per frame from the five
+ * body-18 face points (`nose` against the eye midpoint `r_eye + l_eye` and,
+ * when present, the ear midpoint `r_ear + l_ear`, de-rolled by the eye line),
+ * and map each configured axis into its declared range by compression (never
+ * clipping, so motion changes at the extremes survive).
+ */
+import type { FaceAxis, FaceMap } from './map.ts';
+
+type Pt = [number, number];
+
+const DEG = 180 / Math.PI;
+
+export interface FaceSpan {
+  min: number;
+  max: number;
+  range: number;
+}
+
+export interface FaceAxisReading {
+  bone: string;
+  limits: [number, number];
+  read: FaceSpan;
+  mapped: FaceSpan;
+  /** Compression factors [kNeg, kPos] in (0, 1] applied to negative and positive read angles. */
+  scale: [number, number];
+  /** Pearson correlation between the read angle and the mapped keys over the clip. */
+  corr: number;
+  /** Per-frame read angle in degrees, before range compression. */
+  raw: number[];
+  /** Per-frame mapped rotate key in degrees, rounded to 0.001°. */
+  keys: number[];
+}
+
+export interface FaceReading {
+  ears: boolean;
+  read: {
+    yaw: FaceSpan;
+    pitch: FaceSpan;
+    rawYaw: number[];
+    rawPitch: number[];
+  };
+  yaw?: FaceAxisReading;
+  pitch?: FaceAxisReading;
+}
+
+const r3 = (v: number): number => {
+  const r = Math.round(v * 1000) / 1000;
+  return Object.is(r, -0) ? 0 : r;
+};
+
+function median(xs: readonly number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+function spanOf(xs: readonly number[]): FaceSpan {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const x of xs) {
+    if (x < min) min = x;
+    if (x > max) max = x;
+  }
+  return { min: r3(min), max: r3(max), range: r3(max - min) };
+}
+
+function corrOf(a: readonly number[], b: readonly number[]): number {
+  if (a.length < 2 || a.length !== b.length) return 1;
+  const ma = a.reduce((x, y) => x + y, 0) / a.length;
+  const mb = b.reduce((x, y) => x + y, 0) / b.length;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < a.length; i++) {
+    const xa = a[i]! - ma;
+    const xb = b[i]! - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  const den = Math.sqrt(da * db);
+  return den > 1e-9 ? r3(num / den) : 1;
+}
+
+/**
+ * Read per-frame yaw and pitch (degrees) from `nose`, `r_eye`, `l_eye`, and
+ * (when both are present) `r_ear` and `l_ear`.
+ *
+ * Sign convention (matching `rig-c` gallery `look` and the Part 1 range sweep):
+ * - `yaw > 0`: nose turned toward the subject's right (`r_eye`, viewer-left).
+ * - `pitch > 0`: nose tilted down (chin down / nod down).
+ */
+export function readFaceAngles(
+  nose: readonly Pt[],
+  rEye: readonly Pt[],
+  lEye: readonly Pt[],
+  rEar: readonly Pt[] | null,
+  lEar: readonly Pt[] | null,
+): { ears: boolean; yaw: number[]; pitch: number[] } {
+  const n = nose.length;
+  const ears = rEar !== null && lEar !== null && rEar.length === n && lEar.length === n;
+  const xne: number[] = [];
+  const xna: number[] = [];
+  const yne: number[] = [];
+  const yna: number[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const N = nose[i]!;
+    const Er = rEye[i]!;
+    const El = lEye[i]!;
+    const ex = El[0] - Er[0];
+    const ey = El[1] - Er[1];
+    const de = Math.hypot(ex, ey);
+    if (!(de > 1e-9)) {
+      xne.push(xne[i - 1] ?? 0);
+      yne.push(yne[i - 1] ?? 0);
+      if (ears) {
+        xna.push(xna[i - 1] ?? 0);
+        yna.push(yna[i - 1] ?? 0);
+      }
+      continue;
+    }
+    const ux = ex / de;
+    const uy = ey / de;
+    const vx = -uy;
+    const vy = ux;
+    const mex = 0.5 * (Er[0] + El[0]);
+    const mey = 0.5 * (Er[1] + El[1]);
+    xne.push(((mex - N[0]) * ux + (mey - N[1]) * uy) / de);
+    yne.push(((N[0] - mex) * vx + (N[1] - mey) * vy) / de);
+    if (ears) {
+      const Ar = rEar[i]!;
+      const Al = lEar[i]!;
+      const max = 0.5 * (Ar[0] + Al[0]);
+      const may = 0.5 * (Ar[1] + Al[1]);
+      const da = Math.max(de, (Al[0] - Ar[0]) * ux + (Al[1] - Ar[1]) * uy);
+      xna.push(((max - N[0]) * ux + (may - N[1]) * uy) / da);
+      yna.push(((N[0] - max) * vx + (N[1] - may) * vy) / de);
+    }
+  }
+
+  const yne0 = median(yne);
+  const yna0 = ears ? median(yna) : 0;
+  const yaw: number[] = [];
+  const pitch: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const ty = ears ? (2 * xne[i]! + xna[i]!) / 2 : 2 * xne[i]!;
+    const tp = ears ? (yne[i]! - yne0 + (yna[i]! - yna0)) / 2 : yne[i]! - yne0;
+    yaw.push(Math.atan(ty) * DEG);
+    pitch.push(Math.atan(tp) * DEG);
+  }
+  return { ears, yaw, pitch };
+}
+
+/**
+ * Compress a read angle series into `axis.range` (`[min, max]` with `min <= 0 <= max`):
+ * negative readings scale by `kNeg = min(1, limits[0] / rawMin)` and positive
+ * readings by `kPos = min(1, limits[1] / rawMax)`, so peaks above the range are
+ * compressed to the limit rather than clipped flat, while motion already inside
+ * the range keeps unit gain (`1`).
+ */
+export function mapFaceAxis(raw: readonly number[], axis: FaceAxis): FaceAxisReading {
+  const limits = axis.range;
+  let rawMin = Infinity;
+  let rawMax = -Infinity;
+  for (const x of raw) {
+    if (x < rawMin) rawMin = x;
+    if (x > rawMax) rawMax = x;
+  }
+  const kNeg = rawMin < limits[0] && rawMin < -1e-9 ? limits[0] / rawMin : 1;
+  const kPos = rawMax > limits[1] && rawMax > 1e-9 ? limits[1] / rawMax : 1;
+  const keys = raw.map((x) => r3(x < 0 ? x * kNeg : x * kPos));
+  return {
+    bone: axis.bone,
+    limits: [limits[0], limits[1]],
+    read: spanOf(raw),
+    mapped: spanOf(keys),
+    scale: [r3(kNeg), r3(kPos)],
+    corr: corrOf(raw, keys),
+    raw: [...raw],
+    keys,
+  };
+}
+
+export function readFace(
+  face: FaceMap,
+  nose: readonly Pt[],
+  rEye: readonly Pt[],
+  lEye: readonly Pt[],
+  rEar: readonly Pt[] | null,
+  lEar: readonly Pt[] | null,
+): FaceReading {
+  const { ears, yaw, pitch } = readFaceAngles(nose, rEye, lEye, rEar, lEar);
+  return {
+    ears,
+    read: {
+      yaw: spanOf(yaw),
+      pitch: spanOf(pitch),
+      rawYaw: yaw,
+      rawPitch: pitch,
+    },
+    ...(face.yaw === undefined ? {} : { yaw: mapFaceAxis(yaw, face.yaw) }),
+    ...(face.pitch === undefined ? {} : { pitch: mapFaceAxis(pitch, face.pitch) }),
+  };
+}
+
+const f1 = (x: number): string => x.toFixed(1);
+const sg = (x: number): string => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
+
+export function faceLine(f: FaceReading): string {
+  const joints = f.ears ? 'nose against r_eye + l_eye, r_ear + l_ear' : 'nose against r_eye + l_eye (ears absent)';
+  const readPart = `read yaw ${sg(f.read.yaw.min)}° … ${sg(f.read.yaw.max)}° (${f1(f.read.yaw.range)}°), pitch ${sg(f.read.pitch.min)}° … ${sg(f.read.pitch.max)}° (${f1(f.read.pitch.range)}°)`;
+  const axes: string[] = [];
+  for (const name of ['yaw', 'pitch'] as const) {
+    const ax = f[name];
+    if (ax === undefined) continue;
+    axes.push(`${name} → bone "${ax.bone}" [${ax.limits[0]}, ${ax.limits[1]}]°: ${sg(ax.mapped.min)}° … ${sg(ax.mapped.max)}° (scale ${ax.scale[0].toFixed(3)}/${ax.scale[1].toFixed(3)}, r=${ax.corr.toFixed(3)})`);
+  }
+  return `${joints}: ${readPart}; mapped ${axes.join(', ')}`;
+}

package/src/legs.ts

@@ -12,14 +12,16 @@
  * x axis, and a child with the `normal` inherit mode takes the parent's whole
  * world matrix — so under a thigh scaled by s, a shin at angle φ in the thigh's
  * axes points at atan2(sin φ, s·cos φ), not φ, and its own length is scaled by
- * |(s·cos φ, sin φ)|. The rotate key `turn − turn above` assumes unit scale. A
- * mapped bone below a scaled bone is therefore keyed through its parent's
- * posed matrix (`posePath`): with rig-c's semantics, a `rotate` key k and a
- * `scalex` key s' make the bone's local matrix R(k) · L · diag(s', 1), L its
- * setup local matrix (from rig-c's setup world matrices), so k and s' are the
- * ones that put its world x axis on the target angle at the asked length. Its
- * art is still sheared by the parent's scale; that is measured, not hidden
- * (`shear` in the report).
+ * |(s·cos φ, sin φ)|. A child with `noScale` or `noScaleOrReflection`
+ * (rig-c/pose#153) still has its direction carried through the parent's scaled
+ * matrix, so its angle is skewed the same way, while rig-c normalises that
+ * direction to unit length so the parent's scale is not inherited. The rotate
+ * key `turn − turn above` assumes unit scale. A mapped bone below a scaled bone
+ * is therefore keyed through its parent's posed matrix (`posePath`): with
+ * rig-c's semantics, a `rotate` key k and a `scalex` key s' put its world x
+ * axis on the target angle at the asked length (under `noScale`, s' is the
+ * bone's own asked scale s directly). Its art is still sheared by a `normal`
+ * parent's scale; that is measured, not hidden (`shear` in the report).
  *
  * **Planted feet.** The hip is no longer the pose's mid_hip travel scaled. On
  * every frame one foot supports: the one whose reference ankle is lower in the
@@ -35,7 +37,9 @@
  * picture y over ± `FLOOR_SECONDS`), for ≥ `JUMP_FRAMES` frames, excluding a
  * hand-over whose back ankle stays up and holds its height in y (`< STILL_SPEED`
  * for `STILL_FRAMES` frames) when the front foot lands (a raised heel,
- * rig-c/pose#101) — releases the plant: the hip follows the pose's travel from
+ * rig-c/pose#101), and starting from the first preceding push-off frame where
+ * both ankles are already above their rolling floor while mid_hip lags
+ * (rig-c/pose#142) — releases the plant: the hip follows the pose's travel from
  * where it was, and re-plants on landing. A step does too: while the supporting ankle moves more than
  * `STEP_SPEED` leg lengths a frame its plant is released, the other foot takes
  * support if it is planted (not released, not moving) and otherwise the hip
@@ -162,12 +166,37 @@ export interface PathPose {
   solved: Map<string, { rotate: number; scale: number }>;
 }
 
+/**
+ * World 2×2 of a `noScale` or `noScaleOrReflection` bone under `Wp` at rotate
+ * key `k` (degrees) and scalex key `sk` (rig-c/pose#153), matching rig-c's
+ * `modeMatrix` (`rigc/src/core/world.ts`): the bone's local x direction is
+ * rotated by `k`, carried through `Wp` and normalised to unit length before its
+ * setup local frame (`F0`) and `sk` are applied.
+ */
+export function poseNoScale(Wp: M2, Wp0: M2, W0: M2, inherit: 'noScale' | 'noScaleOrReflection', k: number, sk: number): M2 {
+  const L0 = mul(inv(Wp0), W0);
+  const l0: Pt = [L0[0], L0[2]];
+  const len0 = Math.hypot(W0[0], W0[2]);
+  const u0: Pt = [W0[0] / len0, W0[2] / len0];
+  const flip0 = inherit === 'noScale' && Wp0[0] * Wp0[3] - Wp0[1] * Wp0[2] < 0 ? -1 : 1;
+  const turned0: M2 = [u0[0], -u0[1] * flip0, u0[1], u0[0] * flip0];
+  const F0 = mul(inv(turned0), W0);
+  const u = apply(Wp, apply(rot(k), l0));
+  const invLen = 1 / Math.sqrt(u[0] * u[0] + u[1] * u[1]);
+  const ux = u[0] * invLen;
+  const uy = u[1] * invLen;
+  const flip = inherit === 'noScale' && Wp[0] * Wp[3] - Wp[1] * Wp[2] < 0 ? -1 : 1;
+  const turned: M2 = [ux, -uy * flip, uy, ux * flip];
+  return mul(mul(turned, F0), scaleX(sk));
+}
+
 /**
  * Pose a path of bones, parents first, the first the path's top (its origin is
  * (0, 0)). A mapped bone with no scaled bone above it turns rigidly from setup
  * (R(turn) · setup world · diag(scale, 1)); a mapped bone under a scaled bone
  * is solved through its parent's posed matrix (the header); an unmapped bone
- * keeps its setup local matrix. Every setup matrix and origin is rig-c's.
+ * keeps its setup local matrix (or its `noScale` unit frame, #153). Every setup
+ * matrix and origin is rig-c's.
  */
 export function posePath(rest: Rest, path: readonly string[], posing: (b: string) => Posing | null, scaleOf: (b: string) => number | null): PathPose | string {
   const origin = new Map<string, Pt>();
@@ -197,7 +226,8 @@ export function posePath(rest: Rest, path: readonly string[], posing: (b: string
     origin.set(b, [po[0] + o[0], po[1] + o[1]]);
     const L0 = mul(inv(Wp0), W0);
     const under = scaledAbove.has(p);
-    if (pz === null) m.set(b, mul(Wp, L0));
+    const noScale = rb.inherit === 'noScale' || rb.inherit === 'noScaleOrReflection' ? rb.inherit : null;
+    if (pz === null) m.set(b, noScale !== null ? poseNoScale(Wp, Wp0, W0, noScale, 0, 1) : mul(Wp, L0));
     else if (!under) m.set(b, mul(mul(rot(pz.turn), W0), scaleX(s)));
     else {
       if (!pz.aimX) return `bone "${b}" is mapped under a scaled bone and aimed other than along its x axis; only an "x" aim is solved through a scaled parent`;
@@ -206,8 +236,9 @@ export function posePath(rest: Rest, path: readonly string[], posing: (b: string
       const v = apply(inv(Wp), X);
       const l0: Pt = [L0[0], L0[2]];
       const k = (Math.atan2(v[1], v[0]) - Math.atan2(l0[1], l0[0])) * DEG;
-      const sk = Math.hypot(v[0], v[1]) / Math.hypot(l0[0], l0[1]);
-      m.set(b, mul(mul(mul(Wp, rot(k)), L0), scaleX(sk)));
+      // Under noScale / noScaleOrReflection (#153), rig-c normalises the direction carried through Wp to unit length, so the parent's scale is not inherited and the bone's own scalex is s directly.
+      const sk = noScale !== null ? s : Math.hypot(v[0], v[1]) / Math.hypot(l0[0], l0[1]);
+      m.set(b, noScale !== null ? poseNoScale(Wp, Wp0, W0, noScale, k, sk) : mul(mul(mul(Wp, rot(k)), L0), scaleX(sk)));
       solved.set(b, { rotate: k, scale: sk });
     }
     if (under || scaleOf(b) !== null) scaledAbove.add(b);
@@ -268,7 +299,7 @@ export interface LegScale {
   chain: string;
   bone: string;
   joints: [string, string];
-  /** The straight length: the 95th percentile of the segment's picture length, px. */
+  /** The straight length: the larger of the two sides' 95th-percentile picture lengths for this segment (#148), px. */
   straight: number;
   /** The picture length over the straight length, before the clamp: lowest, median, highest. */
   ratio: { min: number; median: number; max: number };
@@ -290,9 +321,8 @@ export interface LegScale {
   support?: SupportScaleRun[];
 }
 
-/** One segment's scale per frame: picture length ÷ its 95th percentile, clamped; its asked scale without the clamp floor (#107); and the runs clamped. */
-export function legScaleOf(lengths: readonly number[], limits: [number, number]): Omit<LegScale, 'chain' | 'bone' | 'joints'> {
-  const straight = percentile(lengths, STRAIGHT_PERCENTILE);
+/** One segment's scale per frame: picture length ÷ straight length (the larger of the two sides' 95th percentiles, #148), clamped; its asked scale without the clamp floor (#107); and the runs clamped. */
+export function legScaleOf(lengths: readonly number[], limits: [number, number], straight = percentile(lengths, STRAIGHT_PERCENTILE)): Omit<LegScale, 'chain' | 'bone' | 'joints'> {
   const ratio = lengths.map((l) => l / straight);
   const scale = ratio.map((r) => Math.min(Math.max(r, limits[0]), limits[1]));
   const asked = ratio.map((r) => Math.min(r, limits[1]));
@@ -444,6 +474,9 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
   // #101: at a hand-over the front foot has not landed yet while the back ankle lifts its heel; when
   // the front foot lands (the first frame after its lifted run) while the back ankle stays up, a back
   // ankle that holds its height in y (< STILL_SPEED a frame for STILL_FRAMES frames) is a raised heel.
+  // #142: a run's push-off lifts the ankles off the floor while mid_hip is already rising from its
+  // crouch bottom; a jump starts at the first immediately preceding frame where both ankles are above
+  // their rolling floors and mid_hip is rising, so the support span ends at its ankle's push-off.
   const midY = hip.r.map((h, i) => (h[1] + hip.l[i]![1]) / 2);
   const rises: Array<{ ys: number[]; unit: number }> = [
     { ys: ankle.r.map((a) => a[1]), unit: legLength.r },
@@ -471,6 +504,7 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
   };
   const lifted = Array.from({ length: n }, (_, i) => up.every((u) => u[i]));
   const jumps = runs(lifted).filter(([a, b]) => b - a + 1 >= JUMP_FRAMES && !raisedHeel(a, b));
+  for (const j of jumps) while (j[0] > 1 && up[0]![j[0] - 1] && up[1]![j[0] - 1] && midY[j[0] - 1]! < midY[j[0] - 2]!) j[0]--;
   const jump = new Array<boolean>(n).fill(false);
   for (const [a, b] of jumps) for (let i = a; i <= b; i++) jump[i] = true;
   // Ankle speeds, leg lengths a frame (0 on the first frame).
@@ -705,8 +739,8 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     const b = travel(mode.from);
     let y = mode.at[1] + a[1] - b[1];
     if (mode.carry !== undefined && mode.land !== undefined && mode.end !== undefined && floorY !== null) {
-      if (mode.land < n && i <= mode.land && mode.land > mode.from) {
-        y += mode.carry * ((i - mode.from) / (mode.land - mode.from));
+      if (mode.land < n && mode.land > mode.from) {
+        y += mode.carry * ((Math.min(i, mode.land) - mode.from) / (mode.land - mode.from));
       }
       if (i <= mode.end) {
         y = Math.max(y, floorY - Math.min(offset(i, 'r')[1], offset(i, 'l')[1]));
@@ -808,12 +842,16 @@ export type StanceLower = Record<Side, readonly number[]>;
  * fold as far as the picture's leg is folded on that frame, never less far
  * than the default. A leg with no straight length keeps the default.
  */
-export function stanceRangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>): StanceLower {
+export function stanceRangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, inPlace = false): StanceLower {
   const out = {} as Record<Side, number[]>;
   for (const s of SIDES) {
     const len = ankle[s].map((a, i) => Math.hypot(a[0] - hip[s][i]![0], a[1] - hip[s][i]![1]));
-    const straight = percentile(len, STRAIGHT_PERCENTILE);
-    out[s] = len.map((l) => (straight > 1e-9 && Number.isFinite(l) ? Math.min(STANCE_BOUNDS[0], l / straight) : STANCE_BOUNDS[0]));
+    const n = len.length;
+    const globalStraight = percentile(len, STRAIGHT_PERCENTILE);
+    out[s] = len.map((l, i) => {
+      const straight = inPlace || n <= 25 ? globalStraight : percentile(len.slice(Math.max(0, i - 24), Math.min(n, i + 25)), STRAIGHT_PERCENTILE);
+      return straight > 1e-9 && Number.isFinite(l) ? Math.min(STANCE_BOUNDS[0], l / straight) : STANCE_BOUNDS[0];
+    });
   }
   return out;
 }

package/src/map.ts

@@ -101,10 +101,19 @@ export interface AlternateSet {
   /** `place: "by-hip"` (rig-c/pose#93): the chains whose wrist `pose` puts within one hip width of the mid-hip, their wrists placed by the offset from the hip while the set shows. Absent or null: the pose's angles. */
   place?: { by: 'hip'; chains: string[] } | null;
 }
+export interface FaceAxis {
+  bone: string;
+  range: [number, number];
+}
+export interface FaceMap {
+  yaw?: FaceAxis;
+  pitch?: FaceAxis;
+}
 export interface JointMap {
   chains: Chain[];
   translate: Translate | null;
   alternates: AlternateSet[];
+  face?: FaceMap;
 }
 
 /** What a slot of the built rig shows at setup, and every attachment any skin gives it. */
@@ -116,10 +125,14 @@ export interface RigSlot {
 }
 export type RigSlots = ReadonlyMap<string, RigSlot>;
 
+export type InheritMode = 'normal' | 'onlyTranslation' | 'noRotationOrReflection' | 'noScale' | 'noScaleOrReflection';
+
 /** The rig as the map is resolved against it: each bone's setup pose, by rig-c's poser. */
 export interface RestBone extends RawBone {
   /** The bone's `length` in the compiled model (0 when it has none). */
   length: number;
+  /** The bone's `inheritMode` in the compiled model, folded to its canonical lowercase-first name (`normal` when absent). */
+  inherit?: InheritMode;
 }
 export type Rest = ReadonlyMap<string, RestBone>;
 
@@ -131,7 +144,7 @@ export function readMap(text: string, where: string): JointMap {
     p.throwIfAny();
     throw new Error('unreachable');
   }
-  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate', 'alternates']);
+  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate', 'alternates', 'face']);
   if (doc.spec !== MAP_SPEC) p.add('MAP_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${MAP_SPEC}"`);
   const chains: Chain[] = [];
   if (!Array.isArray(doc.chains) || doc.chains.length === 0) {
@@ -231,8 +244,42 @@ export function readMap(text: string, where: string): JointMap {
     }
   }
   const alternates = 'alternates' in doc ? readAlternates(p, where, doc.alternates, chains, translate) : [];
+  const face = 'face' in doc ? readFaceMap(p, where, doc.face) : undefined;
   p.throwIfAny();
-  return { chains, translate, alternates };
+  return { chains, translate, alternates, ...(face === undefined ? {} : { face }) };
+}
+
+function readFaceMap(p: Problems, where: string, raw: unknown): FaceMap | undefined {
+  const fw = `${where} "face"`;
+  if (!isObject(raw)) {
+    p.add('MAP_FACE_SHAPE', `${fw} is ${typeName(raw)}; it is { yaw?: { bone, range: [min, max] }, pitch?: { bone, range: [min, max] } }`);
+    return undefined;
+  }
+  refuseUnknownKeys(p, 'MAP_KEYS', fw, raw, ['yaw', 'pitch']);
+  if (!('yaw' in raw) && !('pitch' in raw)) {
+    p.add('MAP_FACE_SHAPE', `${fw} names neither "yaw" nor "pitch"; it must name at least one axis`);
+    return undefined;
+  }
+  const out: FaceMap = {};
+  for (const axis of ['yaw', 'pitch'] as const) {
+    if (!(axis in raw)) continue;
+    const aw = `${fw} "${axis}"`;
+    const ax = raw[axis];
+    if (!isObject(ax)) {
+      p.add('MAP_FACE_SHAPE', `${aw} is ${typeName(ax)}; it is { bone, range: [min, max] }`);
+      continue;
+    }
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, ax, ['bone', 'range']);
+    const bone = typeof ax.bone === 'string' && ax.bone !== '' ? ax.bone : null;
+    if (bone === null) p.add('MAP_FACE_BONE', `${aw} "bone" is ${typeName(ax.bone)}; it must name a bone`);
+    const v = ax.range;
+    if (!Array.isArray(v) || v.length !== 2 || !v.every((x) => typeof x === 'number' && Number.isFinite(x)) || (v[0] as number) > 0 || (v[1] as number) < 0 || (v[0] as number) >= (v[1] as number)) {
+      p.add('MAP_FACE_RANGE', `${aw} "range" is ${JSON.stringify(v)}; it must be [min, max], two finite numbers of degrees with min ≤ 0 ≤ max and min < max`);
+    } else if (bone !== null) {
+      out[axis] = { bone, range: [v[0] as number, v[1] as number] };
+    }
+  }
+  return out;
 }
 
 const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …], place?: "by-hip" }';
@@ -556,6 +603,22 @@ export function resolveMap(map: JointMap, rest: Rest, where: string, slots: RigS
       p.add('MAP_REACH', `chain "${c.name}" — bone "${b}" reaches from its posed origin, but it does not descend from the translated bone "${t.bone}"; its origin would not travel with the anchor`);
     }
   }
+  if (map.face !== undefined) {
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = map.face[axis];
+      if (ax === undefined) continue;
+      const label = `"face.${axis}"`;
+      if (!rest.has(ax.bone)) {
+        p.add('MAP_BONE_EXISTS', `${label} — bone "${ax.bone}" is not in the rig; its bones are ${listed}`);
+        continue;
+      }
+      const prev = owner.get(ax.bone);
+      if (prev !== undefined) p.add('MAP_BONE_ONCE', `bone "${ax.bone}" is in ${prev.startsWith('"') ? prev : `chain "${prev}"`} and in ${label}; a bone carries one rotate track`);
+      owner.set(ax.bone, label);
+      const o = rest.get(ax.bone)!;
+      if (Math.hypot(o.a, o.c) < 1e-9) p.add('MAP_AIM_LENGTH', `${label} — bone "${ax.bone}" has a collapsed x axis at setup (scale 0)`);
+    }
+  }
   resolveAlternates(p, map.alternates, slots);
   if (p.any) p.list.unshift({ code: 'MAP_RESOLVES', text: `${where} does not resolve against the rig` });
   p.throwIfAny();

package/src/reduce.ts

@@ -31,6 +31,7 @@
  * of the gated build against the dense targets with the tolerance added.
  */
 import { f32 } from 'rig-c/compile';
+import { poseNoScale } from './legs.ts';
 
 /** A key as the reducer writes it: a time, its values, and a raw curve on the segment to the next key. */
 export interface ReducedKey {
@@ -444,11 +445,21 @@ const wrap180 = (d: number): number => {
  * the reduced ones), or another bone of the same call given before it — times
  * the setup locals of the unmapped bones between (`via`).
  */
+export interface UnderStep {
+  wp0: M2;
+  w0: M2;
+  inherit?: 'noScale' | 'noScaleOrReflection';
+}
+
 export interface UnderBone {
   bone: string;
-  parent: { rigid: { turn: readonly number[]; world0: M2; scale: readonly number[] }; via: M2 } | { under: string; via: M2 };
+  parent: { rigid: { turn: readonly number[]; world0: M2; scale: readonly number[] }; via: M2; steps?: readonly UnderStep[] } | { under: string; via: M2; steps?: readonly UnderStep[] };
   /** Its setup local 2×2 in its parent's axes: inv(parent's setup world) · its setup world, by rig-c's setup. */
   local: M2;
+  /** Its parent's and its own setup world 2×2 when `inherit` is `noScale` or `noScaleOrReflection` (#153). */
+  wp0?: M2;
+  w0?: M2;
+  inherit?: 'noScale' | 'noScaleOrReflection';
   /** Its setup world x-axis length. */
   len0: number;
   /** The world angle its x axis is asked on every frame (degrees), and the scale of it asked (1: none). */
@@ -475,6 +486,12 @@ export function reduceUnderScale(times: readonly number[], bones: readonly Under
   const rotate = new Map<string, ReducedKey[]>();
   const scale = new Map<string, ReducedKey[]>();
   const rows: ReduceRow[] = [];
+  const stepVia = (m: M2, via: M2, steps: readonly UnderStep[] | undefined): M2 => {
+    if (steps === undefined || !steps.some((st) => st.inherit !== undefined)) return mul(m, via);
+    let cur = m;
+    for (const st of steps) cur = st.inherit !== undefined ? poseNoScale(cur, st.wp0, st.w0, st.inherit, 0, 1) : mul(cur, mul(inv(st.wp0), st.w0));
+    return cur;
+  };
   for (const b of bones) {
     for (const [what, xs] of [['target', b.target], ['asked', b.asked], ['dense', b.dense]] as const) {
       if (xs.length !== n) throw new Error(`reduce: bone "${b.bone}" has ${xs.length} ${what} value(s) for ${n} frame(s)`);
@@ -484,9 +501,9 @@ export function reduceUnderScale(times: readonly number[], bones: readonly Under
     if ('under' in p) {
       const above = world.get(p.under);
       if (above === undefined) throw new Error(`reduce: bone "${b.bone}" hangs from bone "${p.under}", which is not given before it`);
-      parent = above.map((m) => mul(m, p.via));
+      parent = above.map((m) => stepVia(m, p.via, p.steps));
     } else {
-      parent = Array.from({ length: n }, (_, i) => mul(mul(mul(rot(p.rigid.turn[i]!), p.rigid.world0), scaleX(p.rigid.scale[i]!)), p.via));
+      parent = Array.from({ length: n }, (_, i) => stepVia(mul(mul(rot(p.rigid.turn[i]!), p.rigid.world0), scaleX(p.rigid.scale[i]!)), p.via, p.steps));
     }
     const l0: [number, number] = [b.local[0], b.local[2]];
     const a0 = Math.atan2(l0[1], l0[0]) * DEG;
@@ -507,13 +524,14 @@ export function reduceUnderScale(times: readonly number[], bones: readonly Under
     const kAt = trackAt(rk, samples, 1).map((v) => v[0]!);
     const ae = worstOf(kAt.map((_, i) => i), (i) => aimError(i, kAt[i]!))!;
     rows.push({ bone: b.bone, kind: 'angle', before: n, after: rk.length, worst: ae.worst, frame: ae.frame });
-    // The scale that gives it the length asked on the rotate as reduced.
-    const reach = kAt.map((k, i) => Math.hypot(...axis(i, k)) / b.len0);
+    // The scale that gives it the length asked on the rotate as reduced (#153: under noScale, parent scale is normalised to 1).
+    const noScale = b.inherit;
+    const reach = noScale !== undefined ? kAt.map(() => 1) : kAt.map((k, i) => Math.hypot(...axis(i, k)) / b.len0);
     const sk = fitTrack(times, samples, { targets: reach.map((r, i) => [b.asked[i]! / r]), keep, tolerance: scaleTolerance, error: (i, v) => Math.abs(v[0]! * reach[i]! - b.asked[i]!), round: r6 });
     const sAt = trackAt(sk, samples, 1).map((v) => v[0]!);
     const se = worstOf(sAt.map((_, i) => i), (i) => Math.abs(sAt[i]! * reach[i]! - b.asked[i]!))!;
     rows.push({ bone: b.bone, kind: 'scale', before: n, after: sk.length, worst: se.worst, frame: se.frame });
-    world.set(b.bone, parent.map((m, i) => mul(mul(mul(m, rot(kAt[i]!)), b.local), scaleX(sAt[i]!))));
+    world.set(b.bone, parent.map((m, i) => (noScale !== undefined ? poseNoScale(m, b.wp0!, b.w0!, noScale, kAt[i]!, sAt[i]!) : mul(mul(mul(m, rot(kAt[i]!)), b.local), scaleX(sAt[i]!)))));
     rotate.set(b.bone, rk);
     scale.set(b.bone, sk);
   }

package/src/retarget.ts

@@ -82,7 +82,9 @@ import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, 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 type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
+import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
+import type { FaceReading } from './face.ts';
+import { readFace } from './face.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -322,6 +324,8 @@ export interface Retarget {
   raised: Raised[];
   /** Each span of a `place: "by-hip"` set on each chain it places, its wrist placed against the hip (#93). */
   byHip: ByHip[];
+  /** With "face" in the map (#138): per-frame yaw/pitch reading and range-compressed mapping. */
+  face: FaceReading | null;
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -433,6 +437,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     needed.add(map.translate.joint);
     map.translate.scale.pose.forEach((j) => needed.add(j));
   }
+  if (map.face !== undefined) {
+    needed.add('nose');
+    needed.add('r_eye');
+    needed.add('l_eye');
+  }
   const series = new Map<string, Pt[]>();
   const good = new Map<string, boolean[]>();
   const holds: Hold[] = [];
@@ -678,8 +687,23 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       else if (plantOn) p.add('LEGS_MAP', `--plant-feet reads both hips and both ankles from the pose; the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`);
     }
   }
+  const poseScale: number[] | null =
+    t !== null && scale !== null && !inPlace
+      ? (() => {
+          const [pa, pb] = t.scale.pose;
+          const A = series.get(pa)!;
+          const B = series.get(pb)!;
+          const raw = A.map((a, i) => Math.hypot(B[i]![0] - a[0], B[i]![1] - a[1]));
+          return raw.map((_, i) => {
+            const win = raw.slice(Math.max(0, i - 12), Math.min(n, i + 13)).filter((v) => v > 1e-6);
+            const m = win.length > 0 ? median(win) : scale!.pose;
+            return m > 1e-6 ? m / scale!.pose : 1;
+          });
+        })()
+      : null;
   if (legScaleOn) {
     const limits = opts.legScale as [number, number];
+    const rawSegments: Array<{ chain: string; bone: string; joints: [string, string]; kind: string; lengths: number[]; ownStraight: number }> = [];
     for (const c of map.chains) {
       if (c.reach) continue;
       c.bones.forEach((b, k) => {
@@ -691,15 +715,56 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         }
         const from = series.get(joints[0])!;
         const to = series.get(joints[1])!;
-        const ls = legScaleOf(from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1])), limits);
-        if (!(ls.straight > 1e-6)) {
-          p.add('LEGS_MAP', `--leg-scale: chain "${c.name}" bone "${b}"'s segment ${joints[0]} → ${joints[1]} has a straight length (95th percentile) of ${ls.straight}px; there is nothing to scale against`);
+        const lengths = from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1]));
+        const ownStraight = percentile(lengths, STRAIGHT_PERCENTILE);
+        if (!(ownStraight > 1e-6)) {
+          p.add('LEGS_MAP', `--leg-scale: chain "${c.name}" bone "${b}"'s segment ${joints[0]} → ${joints[1]} has a straight length (95th percentile) of ${ownStraight}px; there is nothing to scale against`);
           return;
         }
-        legScale.push({ chain: c.name, bone: b, joints, ...ls });
-        scales.set(b, ls.scale);
+        rawSegments.push({ chain: c.name, bone: b, joints, kind: `${joints[0].slice(2)}:${joints[1].slice(2)}`, lengths, ownStraight });
       });
     }
+    const straightByKind = new Map<string, number>();
+    for (const seg of rawSegments) straightByKind.set(seg.kind, Math.max(straightByKind.get(seg.kind) ?? 0, seg.ownStraight));
+    if (!inPlace && n > 25) {
+      const byChain = new Map<string, typeof rawSegments>();
+      for (const seg of rawSegments) {
+        const list = byChain.get(seg.chain) ?? [];
+        list.push(seg);
+        byChain.set(seg.chain, list);
+      }
+      const chainTotals = [...byChain.values()].filter((list) => list.length >= 2).map((list) => list[0]!.lengths.map((_, i) => list.reduce((s, seg) => s + seg.lengths[i]!, 0)));
+      const rawBySeg = new Map(rawSegments.map((seg) => [seg, [...seg.lengths]]));
+      for (const seg of rawSegments) {
+        const globalStraight = straightByKind.get(seg.kind)!;
+        const peers = rawSegments.filter((s) => s.kind === seg.kind);
+        seg.lengths = rawBySeg.get(seg)!.map((l, i) => {
+          const lo = Math.max(0, i - 24);
+          const hi = Math.min(n, i + 25);
+          let localStraight = 0;
+          for (const peer of peers) localStraight = Math.max(localStraight, percentile(rawBySeg.get(peer)!.slice(lo, hi), STRAIGHT_PERCENTILE));
+          if (chainTotals.length > 0 && straightByKind.size >= 2) {
+            let sumKindStraight = 0;
+            for (const kind of straightByKind.keys()) {
+              let ks = 0;
+              for (const s of rawSegments) if (s.kind === kind) ks = Math.max(ks, percentile(rawBySeg.get(s)!.slice(lo, hi), STRAIGHT_PERCENTILE));
+              sumKindStraight += ks;
+            }
+            let maxChainTotal = 0;
+            for (const tot of chainTotals) maxChainTotal = Math.max(maxChainTotal, percentile(tot.slice(lo, hi), STRAIGHT_PERCENTILE));
+            if (sumKindStraight > maxChainTotal && maxChainTotal > 1e-6) {
+              localStraight *= maxChainTotal / sumKindStraight;
+            }
+          }
+          return localStraight > 1e-6 ? l * (globalStraight / localStraight) : l;
+        });
+      }
+    }
+    for (const seg of rawSegments) {
+      const ls = legScaleOf(seg.lengths, limits, straightByKind.get(seg.kind)!);
+      legScale.push({ chain: seg.chain, bone: seg.bone, joints: seg.joints, ...ls });
+      scales.set(seg.bone, ls.scale);
+    }
     if (legScale.length === 0 && !p.any) p.add('LEGS_MAP', '--leg-scale scales the leg segments (two of one side\'s hip, knee and ankle), and the map aims none');
   }
   if (opts.stance !== undefined && opts.stance !== 'off' && !plantOn) p.add('STANCE', `--stance ${opts.stance} plants the free foot beside the supporting one that --plant-feet holds, and --plant-feet is not given`);
@@ -773,9 +838,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     // (stanceOf's mechanism, its bounds) so its ankle stays on the floor. Before --stance, whose
     // floor is that supporting ankle. #95: the lower bound on a frame is the leg's own range there.
     const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
-    const lower = stanceRangeOf(ankleSeries, { r: series.get('r_hip')!, l: series.get('l_hip')! });
+    const lower = stanceRangeOf(ankleSeries, { r: series.get('r_hip')!, l: series.get('l_hip')! }, inPlace);
     blendHold = holdBlend(planted.blends, n, posedFeet, lower);
+    const beforeBlendX = blendHold.stretch.map((b, i) => (b === null ? 0 : posedFeet(i).ankle[b.side][0]));
     stretchChain(blendHold.stretch);
+    blendHold.stretch.forEach((b, i) => {
+      if (b === null) return;
+      const dx = beforeBlendX[i]! - posedFeet(i).ankle[b.side][0];
+      hip[i]![0] += dx;
+      travel[i]![0] += dx;
+    });
     // --stance (#60): with the hip placed, a free ankle within the tolerance of the floor has its leg
     // stretched (every bone of its chain's scalex, about the chain's root) until it reaches it.
     if (opts.stance !== undefined && opts.stance !== 'off') {
@@ -962,11 +1034,20 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         if (refEye > 1e-6 && rigEye > 1e-6) nodScale = rigEye / refEye;
       }
       if (neckSeries !== undefined && nodScale !== null) {
-        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
-        const dy = refEN.map((v) => (v - refEN[0]!) * nodScale);
+        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;
+          }
+        }
+        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!)));
         if (dy.some((v) => Math.abs(r3(v)) > 0)) {
-          const bone = rest.get(hb)!;
-          const parent = bone.parent === null ? null : rest.get(bone.parent)!;
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
           for (let i = 0; i < n; i++) {
@@ -1273,6 +1354,26 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
     }
   }
+  let face: FaceReading | null = null;
+  if (map.face !== undefined) {
+    const rEar = series.get('r_ear') ?? (() => {
+      const h = heldOf('r_ear');
+      return 'never' in h ? null : h.at;
+    })();
+    const lEar = series.get('l_ear') ?? (() => {
+      const h = heldOf('l_ear');
+      return 'never' in h ? null : h.at;
+    })();
+    face = readFace(map.face, series.get('nose')!, series.get('r_eye')!, series.get('l_eye')!, rEar, lEar);
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = face[axis];
+      if (ax === undefined) continue;
+      const rest0 = restAngle(rest, ax.bone, 'x');
+      const above = mappedAbove(ax.bone);
+      targets.set(ax.bone, ax.keys.map((v, i) => wrap(rest0 + (above === null ? 0 : turn(above, i)) + v)));
+      tracks.push({ bone: ax.bone, property: 'rotate', keys: ax.keys.map((v, i) => ({ t: keyTimes[i]!, v: [v] })) });
+    }
+  }
   // Scale keys: a scaled leg segment's own scale, or the scale that lands a bone under one at its asked length.
   for (const c of map.chains) {
     for (const b of c.bones) {
@@ -1288,7 +1389,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face,
   };
 }
 

package/src/rigc.ts

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { poseRawSetup, readModel, type CompiledDocument } from 'rig-c/core';
-import type { Rest, RestBone, RigSlot, RigSlots } from './map.ts';
+import type { InheritMode, Rest, RestBone, RigSlot, RigSlots } from './map.ts';
 import { isObject, parseJson, Problems, Refusal, typeName } from './problems.ts';
 
 export interface RigInput {
@@ -129,11 +129,18 @@ export function readBuild(build: string): CompiledDocument {
   return readModel(readFileSync(path, 'utf8'), path);
 }
 
-/** Every bone's setup pose, by rig-c's poser, with its model `length`. */
+/** Every bone's setup pose, by rig-c's poser, with its model `length` and `inheritMode`. */
 export function restOf(doc: CompiledDocument): Rest {
   const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
+  const inherits = new Map<string, InheritMode>(
+    doc.bones.map((b) => {
+      const s = b.inheritMode;
+      const folded = s === undefined || s.length === 0 ? 'normal' : `${s[0]!.toLowerCase()}${s.slice(1)}`;
+      return [b.name, folded === 'onlyTranslation' || folded === 'noRotationOrReflection' || folded === 'noScale' || folded === 'noScaleOrReflection' ? folded : 'normal'];
+    }),
+  );
   const out = new Map<string, RestBone>();
-  for (const b of poseRawSetup(doc).bones) out.set(b.name, { ...b, length: lengths.get(b.name) ?? 0 });
+  for (const b of poseRawSetup(doc).bones) out.set(b.name, { ...b, length: lengths.get(b.name) ?? 0, inherit: inherits.get(b.name) ?? 'normal' });
   return out;
 }
 

package/src/run.ts

@@ -19,6 +19,7 @@ import { landed, measureFeet, measureLanding, measurePosture, measureShear, pose
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
 import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import { faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -157,6 +158,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       if (r.blendHold !== null) for (const l of blendLines(r.blendHold, r.times)) say(`  FEET   ${l}`);
     }
     if (r.stance !== null) for (const l of stanceLines(r.stance, r.times)) say(`  STANCE ${l}`);
+    if (r.face !== null) say(`  FACE   ${faceLine(r.face)}`);
 
     // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
     const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip);
@@ -183,7 +185,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         if ((t.kind === 'bone' || t.kind === 'group') && Array.isArray(sample)) return boneIdentity(property, sample.length);
         return undefined;
       };
-      const mapped = [...map.chains.flatMap((c) => c.bones), ...(map.translate === null ? [] : [map.translate.bone])];
+      const mapped = [
+        ...map.chains.flatMap((c) => c.bones),
+        ...(map.translate === null ? [] : [map.translate.bone]),
+        ...(map.face?.yaw === undefined ? [] : [map.face.yaw.bone]),
+        ...(map.face?.pitch === undefined ? [] : [map.face.pitch.bone]),
+      ];
       const below = new Map<string, string[]>();
       for (const m of new Set(mapped)) {
         for (let b = rest.get(m)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) {
@@ -317,6 +324,16 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         raised: r.raised,
         // Only when a set declares `place` (#93): a map without one writes the report it always has.
         ...(map.alternates.some((x) => x.place !== undefined && x.place !== null) ? { byHip: r.byHip } : {}),
+        ...(r.face === null
+          ? {}
+          : {
+              face: {
+                ears: r.face.ears,
+                read: { yaw: r.face.read.yaw, pitch: r.face.read.pitch },
+                ...(r.face.yaw === undefined ? {} : { yaw: { bone: r.face.yaw.bone, limits: r.face.yaw.limits, read: r.face.yaw.read, mapped: r.face.yaw.mapped, scale: r.face.yaw.scale, corr: r.face.yaw.corr } }),
+                ...(r.face.pitch === undefined ? {} : { pitch: { bone: r.face.pitch.bone, limits: r.face.pitch.limits, read: r.face.pitch.read, mapped: r.face.pitch.mapped, scale: r.face.pitch.scale, corr: r.face.pitch.corr } }),
+              },
+            }),
         legScale: r.legScale.map(({ scale: _scale, asked: _asked, ...rest }) => rest),
         pivot: r.pivot,
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, ...(r.stance.range === undefined ? {} : { range: r.stance.range }), runs: r.stance.runs, over: r.stance.over },
@@ -431,21 +448,34 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
     return d;
   };
   const underBones = [...rotate.keys()].filter(under).sort((x, y) => depth(x) - depth(y));
+  const noScaleOf = (b: string): 'noScale' | 'noScaleOrReflection' | undefined => {
+    const inh = rest.get(b)!.inherit;
+    return inh === 'noScale' || inh === 'noScaleOrReflection' ? inh : undefined;
+  };
   const given: UnderBone[] = underBones.map((b) => {
     if (!scalex.has(b)) throw new Refusal([{ code: 'POSE_REDUCE', text: `bone "${b}" hangs under a scaled bone and has no scalex track, so it was not keyed through its parent's posed matrix; --reduce re-solves only a bone the legs keyed that way` }]);
-    // Up through the unmapped bones between (their setup locals), to a bone given before it or one the key formula holds for.
+    // Up through the unmapped bones between (their setup locals, or their noScale unit frames, #153), to a bone given before it or one the key formula holds for.
     let via: M2 = M2_IDENTITY;
+    const steps: Array<{ wp0: M2; w0: M2; inherit?: 'noScale' | 'noScaleOrReflection' }> = [];
     let p = rest.get(b)!.parent!;
     while (under(p) && !mapped.has(p)) {
-      via = mulM2(setupLocal(world0(rest.get(p)!.parent!), world0(p)), via);
+      const wp0 = world0(rest.get(p)!.parent!);
+      const w0 = world0(p);
+      via = mulM2(setupLocal(wp0, w0), via);
+      const inherit = noScaleOf(p);
+      steps.unshift({ wp0, w0, ...(inherit !== undefined ? { inherit } : {}) });
       p = rest.get(p)!.parent!;
     }
-    const parent: UnderBone['parent'] = under(p) ? { under: p, via } : { rigid: { turn: turnOf(p), world0: world0(p), scale: scaleAt.get(p) ?? new Array<number>(n).fill(1) }, via };
+    const viaSteps = steps.some((st) => st.inherit !== undefined) ? { steps } : {};
+    const parent: UnderBone['parent'] = under(p) ? { under: p, via, ...viaSteps } : { rigid: { turn: turnOf(p), world0: world0(p), scale: scaleAt.get(p) ?? new Array<number>(n).fill(1) }, via, ...viaSteps };
+    const wp0 = world0(rest.get(b)!.parent!);
     const w0 = world0(b);
+    const inherit = noScaleOf(b);
     return {
       bone: b,
       parent,
-      local: setupLocal(world0(rest.get(b)!.parent!), w0),
+      local: setupLocal(wp0, w0),
+      ...(inherit !== undefined ? { wp0, w0, inherit } : {}),
       len0: Math.hypot(w0[0], w0[2]),
       target: r.targets.get(b)!,
       asked: r.scales.get(b) ?? new Array<number>(n).fill(1),
@@ -671,7 +701,7 @@ function legScaleLine(l: LegScale, times: readonly number[]): string {
   const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
   const count = (rs: Array<[number, number]>) => rs.reduce((k, x) => k + x[1] - x[0] + 1, 0);
   const clamp = (rs: Array<[number, number]>, at: number, how: string) => (rs.length === 0 ? `none ${how} ${at}` : `${count(rs)} frame(s) ${how} ${at}, clamped (frames ${rs.map(span).join(', ')})`);
-  return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (95th percentile of ${times.length} frames); picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}]: ${clamp(l.low, l.limits[0], 'under')}; ${clamp(l.high, l.limits[1], 'over')}`;
+  return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (larger 95th percentile of ${times.length} frames, both legs); picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}]: ${clamp(l.low, l.limits[0], 'under')}; ${clamp(l.high, l.limits[1], 'over')}`;
 }
 
 /** A LEG-SCALE past the floor (support) line (rig-c/pose#133): the supporting leg segment scaled below `--leg-scale`'s floor down to #95's bound. */

package/src/verify.ts

@@ -61,13 +61,19 @@ export function poseFrames(doc: CompiledDocument, animation: string, times: read
 export function measureLanding(doc: CompiledDocument, animation: string, map: JointMap, r: Retarget, posed = poseFrames(doc, animation, r.times)): Landing[] {
   const out: Landing[] = [];
   const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
+  const faceBones = new Set([r.face?.yaw?.bone, r.face?.pitch?.bone].filter((b): b is string => b !== undefined));
+  const isFaceSlider = (c: CompiledDocument['constraints'][number]): boolean => c.record?.kind === 'slider' && c.record.bone !== null && faceBones.has(c.record.bone);
+  const hasFaceSliders = faceBones.size > 0 && doc.constraints.some(isFaceSlider);
+  const chainPosed = hasFaceSliders
+    ? poseFrames({ ...doc, constraints: doc.constraints.filter((c) => !isFaceSlider(c)) }, animation, r.times)
+    : posed;
   for (const c of map.chains) {
     c.bones.forEach((b, k) => {
       const aim = c.aim[k]!;
       const asked = r.targets.get(b)!;
       let worst = -1;
       let frame = 0;
-      posed.forEach((bones, i) => {
+      chainPosed.forEach((bones, i) => {
         const reached = aimAngle(bones, lengths, b, aim);
         const e = Math.abs(wrap(reached - asked[i]!));
         if (e > worst) {
@@ -78,6 +84,24 @@ export function measureLanding(doc: CompiledDocument, animation: string, map: Jo
       out.push({ bone: b, worst, frame, kind: 'angle', tolerance: ANGLE_TOLERANCE });
     });
   }
+  if (r.face !== null) {
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = r.face[axis];
+      if (ax === undefined) continue;
+      const asked = r.targets.get(ax.bone)!;
+      let worst = -1;
+      let frame = 0;
+      posed.forEach((bones, i) => {
+        const reached = aimAngle(bones, lengths, ax.bone, 'x');
+        const e = Math.abs(wrap(reached - asked[i]!));
+        if (e > worst) {
+          worst = e;
+          frame = i;
+        }
+      });
+      out.push({ bone: ax.bone, worst, frame, kind: 'angle', tolerance: ANGLE_TOLERANCE });
+    }
+  }
   const setup = new Map(poseRawSetup(doc).bones.map((b) => [b.name, b]));
   for (const [b, asked] of r.scales) {
     const s0 = setup.get(b)!;