@rig-c/pose 0.20.0 → 0.20.2

package/README.md

@@ -136,7 +136,7 @@ and what the run cannot decide for you it lists:
 - `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.
 - `BY-HIP` — with a set's `"place": "by-hip"` ([below](#alternate-drawings-alternates)): the `RAISED` line against the hip, one per span of such a set per chain it places. The unit is the hip width, the offset is from the mid-hip. `BY-HIP none` when the map has such a set and none of its spans showed.
 - `REACH` — with `--raised-by-head`, or a `"by-hip"` set: a placed 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 (hip widths for `"by-hip"`). 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.
+- `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, the frames clamped at each limit, and (with `--plant-feet`) one `past the floor (support)` line per supporting run that asked under the floor ([#133](https://github.com/rig-c/pose/issues/133), `legScale[].support` in the report).
 - `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.
 - `STANCE` — with `--stance` ([below](#the-legs-foreshortening-and-planted-feet)): one line per run of frames planted both (with the stretch keyed, its largest k), lifted, or past the tolerance below (the pose's height kept, [#114](https://github.com/rig-c/pose/issues/114)), with the free side, the frames and the tolerance; and one per run whose stretch fell past its bounds (`past the bounds`), with the k the floor needed, the bound it had and how far the foot was left from it; and, where the leg's own range set a lower bound below 0.92, one `bound from the leg's own range` line with each side's lowest.
@@ -199,7 +199,7 @@ A knee bending toward the camera is seen from the front only as a shorter leg, a
 
 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.
 
-**`--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 holds the bone and does not lift the hip by what the clamp withheld, [#107](https://github.com/rig-c/pose/issues/107)), instead of moving it by the pose's mid_hip travel:
+**`--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.

package/package.json

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

@@ -253,6 +253,17 @@ export function rootOf(rest: Rest, b: string): string {
 
 // --- leg scale -------------------------------------------------------------
 
+export interface SupportScaleRun {
+  side: Side;
+  frames: [number, number];
+  /** The lowest and highest scale asked on the run's frames. */
+  asked: { min: number; max: number };
+  /** The lowest and highest scale keyed on the run's frames (clamped at `bound` when `asked` went under #95's bound). */
+  used: { min: number; max: number };
+  /** Present when `asked` went under #95's bound on any frame of the run: the lowest bound on the run, and the largest hip rise (world units, ≥ 0). */
+  clamped?: { bound: number; hipRise: number };
+}
+
 export interface LegScale {
   chain: string;
   bone: string;
@@ -270,6 +281,13 @@ export interface LegScale {
   scale: number[];
   /** The scale the pose asked for on each frame before the clamp floor (`min(ratio, limits[1])`, rig-c/pose#107). */
   asked: number[];
+  /**
+   * rig-c/pose#133: under `--plant-feet`, runs of supporting frames on this
+   * segment where the asked scale went under `limits[0]` and followed `asked`
+   * down to the bound #95 derives from the leg's own range (`min(limits[0], r(i))`).
+   * Absent when no supporting frame on this segment asked under `limits[0]`.
+   */
+  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. */
@@ -800,6 +818,96 @@ export function stanceRangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Si
   return out;
 }
 
+/**
+ * Under `--plant-feet` and `--leg-scale`, a supporting leg segment that asks a
+ * scale under `--leg-scale`'s floor (`limits[0]`) follows its asked scale down
+ * to the bound #95 derives from the leg's own range (`min(limits[0], r(i))`) so
+ * the supporting ankle stays on #85's floor after #107 (rig-c/pose#133). The
+ * free leg keeps the configured clamp. When an asked scale goes under #95's
+ * bound (`lower`, defaulting to the segment's own range `asked[i]`), it is
+ * clamped there and the hip rises by the vertical remainder (`askedOffset −
+ * usedOffset`), never sinks.
+ */
+export function scaleSupport(
+  legScale: LegScale[],
+  scales: Map<string, number[]>,
+  feet: Feet,
+  legs: Record<Side, { chain: Chain; ankleBone: string }>,
+  hip: Pt[],
+  askedOffset: (i: number, s: Side) => Pt,
+  usedOffset: (i: number, s: Side) => Pt,
+  lower?: StanceLower,
+): void {
+  const n = feet.support.length;
+  const tracked = new Array<Side | null>(n).fill(null);
+  for (const t of feet.tracked ?? []) for (let i = t.frames[0]; i <= t.frames[1]; i++) tracked[i] = t.side;
+  const byBone = new Map(legScale.map((ls) => [ls.bone, ls]));
+  const copied = new Set<string>();
+  const ensureCopy = (b: string): number[] => {
+    const cur = scales.get(b)!;
+    if (copied.has(b)) return cur;
+    const copy = [...cur];
+    scales.set(b, copy);
+    copied.add(b);
+    return copy;
+  };
+  const perBone = new Map<string, Array<{ frame: number; side: Side; asked: number; used: number; bound: number; clamped: boolean; hipRise: number }>>();
+  for (let i = 0; i < n; i++) {
+    const s = feet.support[i] ?? tracked[i] ?? null;
+    if (s === null) continue;
+    const touched: Array<{ bone: string; asked: number; used: number; bound: number; clamped: boolean }> = [];
+    for (const b of legs[s].chain.bones) {
+      const ls = byBone.get(b);
+      if (ls === undefined) continue;
+      const asked = ls.asked[i]!;
+      const floor = ls.limits[0];
+      if (!(asked < floor)) continue;
+      const r = lower !== undefined ? lower[s][i]! : asked;
+      const bound = Math.min(floor, r);
+      const used = Math.max(asked, bound);
+      const clamped = used > asked + 1e-12;
+      ensureCopy(b)[i] = used;
+      touched.push({ bone: b, asked, used, bound, clamped });
+    }
+    if (touched.length === 0) continue;
+    let hipRise = 0;
+    if (touched.some((t) => t.clamped)) {
+      hipRise = Math.max(0, askedOffset(i, s)[1] - usedOffset(i, s)[1]);
+      hip[i]![1] += hipRise;
+    }
+    for (const t of touched) {
+      const list = perBone.get(t.bone) ?? [];
+      list.push({ frame: i, side: s, ...t, hipRise });
+      perBone.set(t.bone, list);
+    }
+  }
+  for (const ls of legScale) {
+    const entries = perBone.get(ls.bone);
+    if (entries === undefined || entries.length === 0) continue;
+    const out: SupportScaleRun[] = [];
+    for (const e of entries) {
+      const last = out[out.length - 1];
+      if (last !== undefined && last.side === e.side && last.frames[1] === e.frame - 1 && (last.clamped !== undefined) === e.clamped) {
+        last.frames[1] = e.frame;
+        last.asked = { min: Math.min(last.asked.min, e.asked), max: Math.max(last.asked.max, e.asked) };
+        last.used = { min: Math.min(last.used.min, e.used), max: Math.max(last.used.max, e.used) };
+        if (last.clamped !== undefined) {
+          last.clamped = { bound: Math.min(last.clamped.bound, e.bound), hipRise: Math.max(last.clamped.hipRise, e.hipRise) };
+        }
+      } else {
+        out.push({
+          side: e.side,
+          frames: [e.frame, e.frame],
+          asked: { min: e.asked, max: e.asked },
+          used: { min: e.used, max: e.used },
+          ...(e.clamped ? { clamped: { bound: e.bound, hipRise: e.hipRise } } : {}),
+        });
+      }
+    }
+    ls.support = out;
+  }
+}
+
 /** The lower bound on frame i for side s: the leg's own (#95), or the default. */
 function lowerOf(lower: StanceLower | undefined, s: Side, i: number): number {
   return lower?.[s][i] ?? STANCE_BOUNDS[0];
@@ -906,7 +1014,61 @@ export interface StancePosed {
  * free side and with no frame between, takes their state, and is listed with
  * `absorbed`.
  */
-export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, tolerance: number, posed: (i: number) => StancePosed, secondsOf: (run: [number, number]) => number, lower?: StanceLower): Stance {
+/**
+ * Under `--stance` and `--leg-scale` (rig-c/pose#137), a free foot read `both`
+ * (planted beside the supporting one within `tolerance`) whose posed ankle sits
+ * above the floor (`ankle[free][1] > ankle[support][1]`) while neither the
+ * whole leg (`lo >= STANCE_BOUNDS[0]`) nor its thigh (`s0 >= STANCE_BOUNDS[0]`)
+ * is folded below `STANCE_BOUNDS[0]`, yet its shin was shortened below it
+ * (`s1 < STANCE_BOUNDS[0]`), owes that shin shortening to a low knee / high
+ * ankle split along a straight stance leg in the picture. Keeping the shortened
+ * shin scale makes `--stance` multiply both thigh and shin by `needed`,
+ * over-stretching the thigh (pushing the knee down), leaving the shin and foot
+ * squashed, and exceeding `STANCE_BOUNDS[1]` so the free ankle floats off #85's
+ * floor. Lifting the shin's scale to `min(1, s0)` before `stanceOf` reads
+ * `needed` restores the straight leg's shin proportion first so the chain is
+ * stretched only by the remaining gap.
+ */
+export function unshortenStanceShin(
+  scales: Map<string, number[]>,
+  legs: Record<Side, { chain: Chain; ankleBone: string }>,
+  posed: (i: number) => StancePosed,
+  lower?: StanceLower,
+): (i: number, free?: Side) => StancePosed {
+  const copied = new Set<string>();
+  const ensureCopy = (b: string): number[] => {
+    const cur = scales.get(b)!;
+    if (copied.has(b)) return cur;
+    const copy = [...cur];
+    scales.set(b, copy);
+    copied.add(b);
+    return copy;
+  };
+  return (i: number, free?: Side): StancePosed => {
+    const p = posed(i);
+    if (free === undefined) return p;
+    if (lowerOf(lower, free, i) < STANCE_BOUNDS[0]) return p;
+    const support: Side = free === 'r' ? 'l' : 'r';
+    const floor = p.ankle[support][1];
+    const root = p.root[free][1];
+    const a = p.ankle[free][1];
+    if (!(root - a > 1e-9 && a > floor + 1e-9)) return p;
+    const bones = legs[free].chain.bones;
+    if (bones.length < 2) return p;
+    const b0 = bones[0]!;
+    const b1 = bones[bones.length - 1]!;
+    const arr0 = scales.get(b0);
+    const arr1 = scales.get(b1);
+    if (arr0 === undefined || arr1 === undefined) return p;
+    const s0 = arr0[i]!;
+    const s1 = arr1[i]!;
+    if (!(s0 >= STANCE_BOUNDS[0] && s1 < STANCE_BOUNDS[0])) return p;
+    ensureCopy(b1)[i] = Math.min(1, s0);
+    return posed(i);
+  };
+}
+
+export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, tolerance: number, posed: (i: number, free?: Side) => StancePosed, secondsOf: (run: [number, number]) => number, lower?: StanceLower): Stance {
   const n = feet.support.length;
   const stretch: Stance['stretch'] = new Array(n).fill(null);
   const tracked = new Array<Side | null>(n).fill(null);
@@ -977,7 +1139,7 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
       rows[i] = { state: r.state, side: f, height, k: null, needed: null, over: false, left: 0, lo };
       continue;
     }
-    const p = posed(i);
+    const p = posed(i, f);
     const floor = p.ankle[s][1];
     const root = p.root[f][1];
     const a = p.ankle[f][1];

package/src/map.ts

@@ -111,6 +111,8 @@ export interface JointMap {
 export interface RigSlot {
   setup: string | null;
   attachments: ReadonlySet<string>;
+  /** The bone the slot is attached to, when read from a compiled build. */
+  bone?: string;
 }
 export type RigSlots = ReadonlyMap<string, RigSlot>;
 

package/src/retarget.ts

@@ -82,7 +82,7 @@ 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, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf } from './legs.ts';
+import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -739,8 +739,13 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     const hip = planted.hip;
     floor = planted.floor;
     closure = planted.closure;
-    for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
     const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
+    // #133: on a frame where the supporting leg asks under --leg-scale's floor, its scalex follows the asked
+    // value down to #95's bound so the ankle stays on #85's floor; the free leg keeps the configured clamp.
+    if (legScaleOn && feet !== null) {
+      scaleSupport(legScale, scales, feet, L, hip, (i, s) => offsets[i]![s], (i, s) => tipOf(rest, poseLegs(i), L[s].ankleBone));
+    }
+    for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
     const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
     /** Both legs posed on frame i by the scales as they stand, world (y up): each chain's root and ankle. */
     const posedFeet = (i: number) => {
@@ -774,7 +779,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     // --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') {
-      stance = stanceOf(feet!, ankleSeries, opts.stance, posedFeet, secondsOf, lower);
+      stance = stanceOf(feet!, ankleSeries, opts.stance, legScaleOn ? unshortenStanceShin(scales, L, posedFeet, lower) : posedFeet, secondsOf, lower);
       // The supporting leg (the blend's) and the free leg (the stance's) are different chains on a frame.
       for (let i = 0; i < n; i++) {
         const b = blendHold.stretch[i];
@@ -892,7 +897,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     return null;
   };
   const turn = (bone: string, i: number) => targets.get(bone)![i]! - restOf.get(bone)!;
-  const covered = coveredChains(sw.switches, n);
+  const covered = coveredChains(sw.switches, n, sw.chainHolds);
   if (opts.short !== 'off') {
     for (const [b, info] of fractions) {
       for (const s of capShortSteps(targets.get(b)!, info.fraction, covered.get(info.chain))) {
@@ -1183,7 +1188,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     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);
+  clampArt(sw.switches, map, targets, sw.chainHolds);
   // Where each raised wrist lands as keyed: after the solve and the set's `turn`.
   for (const job of raisedJobs) {
     const after: Pt[] = [];

package/src/rigc.ts

@@ -143,7 +143,7 @@ export function slotsOf(doc: CompiledDocument): RigSlots {
   for (const s of doc.slots) {
     const attachments = new Set<string>();
     for (const k of doc.skins) for (const name of Object.keys(k.attachments[s.name] ?? {})) attachments.add(name);
-    out.set(s.name, { setup: s.setup, attachments });
+    out.set(s.name, { setup: s.setup, attachments, bone: s.bone });
   }
   return out;
 }

package/src/run.ts

@@ -18,7 +18,7 @@ import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switc
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 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 } from './legs.ts';
+import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -138,6 +138,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const e of r.byHip) 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)}`);
+    for (const l of r.legScale) for (const s of l.support ?? []) say(`  LEG-SCALE ${supportScaleLine(l, s, 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`);
     if (r.feet !== null) {
       const f = r.feet;
@@ -673,6 +674,16 @@ function legScaleLine(l: LegScale, times: readonly number[]): string {
   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')}`;
 }
 
+/** 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. */
+export function supportScaleLine(l: LegScale, s: SupportScaleRun, times: readonly number[]): string {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
+  const val = (r: { min: number; max: number }) => (r.min === r.max ? r.min.toFixed(4) : `${r.min.toFixed(4)}–${r.max.toFixed(4)}`);
+  if (s.clamped !== undefined) {
+    return `past the floor (support): chain "${l.chain}" bone "${l.bone}" (supporting foot ${s.side}) ${span(s.frames)} — asked ${val(s.asked)} under ${l.limits[0]}, clamped at the leg's own range ${s.clamped.bound.toFixed(4)} (#95), used ${val(s.used)}; hip rose by up to +${s.clamped.hipRise.toFixed(2)} units (never sinks)`;
+  }
+  return `past the floor (support): chain "${l.chain}" bone "${l.bone}" (supporting foot ${s.side}) ${span(s.frames)} — asked ${val(s.asked)} under ${l.limits[0]}, used ${val(s.used)} (within the leg's own range, #95; ankle stays on the floor)`;
+}
+
 /**
  * POSE_NOT_CLEANED (#67): retarget reads only a sequence `rig-pose clean` wrote.
  * The message is the command to run on this file; the output name is a

package/src/switch.ts

@@ -154,19 +154,35 @@ export interface Switches {
   shown: Map<string, Array<string | null>>;
   /** Per set, its distance on each frame, degrees. */
   distances: Map<string, number[]>;
+  /** Per chain, the behind-the-torso set spans (including same-set gap holds, #136) for `clampArt`. */
+  chainHolds?: Array<{ set: string; chain: string; frames: [number, number] }>;
 }
 
-/** Per set, its distance to the pose on every frame: the largest segment difference over its chains. */
-export function setDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number): Map<string, number[]> {
-  const out = new Map<string, number[]>();
+/** Per set and chain, its distance to the pose on every frame: the largest segment difference over that chain. */
+export function chainDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number): Map<string, Map<string, number[]>> {
+  const out = new Map<string, Map<string, number[]>>();
   for (const a of map.alternates) {
-    const segs: Array<{ asked: readonly number[]; key: number }> = [];
+    const byChain = new Map<string, number[]>();
     for (const cn of a.chains) {
       const c = map.chains.find((x) => x.name === cn)!;
-      c.bones.forEach((b, k) => segs.push({ asked: targets.get(b)!, key: pictureAngle(a.pose[c.joints[k]!]!, a.pose[c.joints[k + 1]!]!) }));
+      const segs = c.bones.map((b, k) => ({ asked: targets.get(b)!, key: pictureAngle(a.pose[c.joints[k]!]!, a.pose[c.joints[k + 1]!]!) }));
+      const d: number[] = [];
+      for (let i = 0; i < n; i++) d.push(Math.max(...segs.map((s) => Math.abs(wrap(s.asked[i]! - s.key)))));
+      byChain.set(cn, d);
     }
+    out.set(a.name, byChain);
+  }
+  return out;
+}
+
+/** Per set, its distance to the pose on every frame: the largest segment difference over its chains. */
+export function setDistances(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, n: number): Map<string, number[]> {
+  const byChain = chainDistances(map, targets, n);
+  const out = new Map<string, number[]>();
+  for (const a of map.alternates) {
+    const cs = a.chains.map((cn) => byChain.get(a.name)!.get(cn)!);
     const d: number[] = [];
-    for (let i = 0; i < n; i++) d.push(Math.max(...segs.map((s) => Math.abs(wrap(s.asked[i]! - s.key)))));
+    for (let i = 0; i < n; i++) d.push(Math.max(...cs.map((c) => c[i]!)));
     out.set(a.name, d);
   }
   return out;
@@ -210,6 +226,59 @@ function competing(sets: readonly AlternateSet[]): AlternateSet[][] {
   return [...groups.values()];
 }
 
+/**
+ * How a competing group's slots sit against the torso in the rig's draw order
+ * (`slots` is in draw order, back to front, #136): which slot is the never-hidden
+ * torso slot (when the group touches or sits beside one), which sets draw their
+ * limb slots behind it vs in front of it, whether the base setup slots sit in
+ * front of it, and which chain owns each non-torso slot.
+ */
+function groupLayering(group: readonly AlternateSet[], map: JointMap, slots: RigSlots) {
+  const rank = new Map([...slots.keys()].map((s, i) => [s, i]));
+  const touched = [...new Set(group.flatMap((a) => [...Object.keys(a.slots), ...a.hides]))].filter((s) => rank.has(s));
+  const hiddenSetup = touched.filter((s) => slots.get(s)!.setup !== null && group.some((a) => a.hides.includes(s)));
+  const extra = touched.filter((s) => slots.get(s)!.setup === null);
+  const torsoSlot = touched.find((s) => slots.get(s)!.setup !== null && !group.some((a) => a.hides.includes(s))) ?? null;
+  let torsoRank: number | null = torsoSlot !== null ? rank.get(torsoSlot)! : null;
+  if (torsoRank === null && hiddenSetup.length > 0 && extra.length > 0) {
+    const minFront = Math.min(...hiddenSetup.map((s) => rank.get(s)!));
+    const maxBack = Math.max(...extra.filter((s) => rank.get(s)! < minFront).map((s) => rank.get(s)!));
+    if (Number.isFinite(maxBack)) {
+      const between = [...slots.keys()].find((s) => !touched.includes(s) && slots.get(s)!.setup !== null && rank.get(s)! > maxBack && rank.get(s)! < minFront);
+      torsoRank = between !== undefined ? rank.get(between)! : minFront - 0.5;
+    }
+  }
+  const limbSlotsOf = (a: AlternateSet) => Object.keys(a.slots).filter((s) => s !== torsoSlot && rank.has(s));
+  const isBehind = (a: AlternateSet): boolean => {
+    if (torsoRank === null) return false;
+    const ls = limbSlotsOf(a);
+    return ls.length > 0 && ls.every((s) => rank.get(s)! < torsoRank) && a.hides.some((h) => (rank.get(h) ?? -1) > torsoRank);
+  };
+  const isFront = (a: AlternateSet): boolean => {
+    if (torsoRank === null) return false;
+    const ls = limbSlotsOf(a);
+    return ls.length > 0 && ls.every((s) => rank.get(s)! > torsoRank);
+  };
+  const baseInFront = torsoRank !== null && hiddenSetup.length > 0 && hiddenSetup.every((s) => rank.get(s)! > torsoRank);
+  const groupChains = [...new Set(group.flatMap((a) => a.chains))];
+  const boneOwner = new Map<string, string>();
+  for (const cn of groupChains) for (const b of map.chains.find((c) => c.name === cn)!.bones) boneOwner.set(b, cn);
+  const slotChain = new Map<string, string>();
+  for (const s of touched) {
+    if (s === torsoSlot) continue;
+    const b = slots.get(s)?.bone;
+    if (b !== undefined && boneOwner.has(b)) {
+      slotChain.set(s, boneOwner.get(b)!);
+      continue;
+    }
+    const side = /(?:^|_)([rl])(?:_|$)/.exec(s)?.[1];
+    const bySide = side === undefined ? undefined : groupChains.find((c) => new RegExp(`(?:^|_)${side}(?:_|$)`).test(c));
+    if (bySide !== undefined) slotChain.set(s, bySide);
+    else if (groupChains.length === 1) slotChain.set(s, groupChains[0]!);
+  }
+  return { torsoSlot, torsoRank, touched, isBehind, isFront, baseInFront, slotChain };
+}
+
 /**
  * Per frame, the largest |angular speed| over the given bones' target world
  * angles, degrees per frame: a central difference, one-sided on the first and
@@ -305,9 +374,12 @@ const changeAt = (times: readonly number[], i: number): number => (i === 0 ? 0 :
  */
 export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, readonly number[]>, times: readonly number[], duration: number, slots: RigSlots, opts: SwitchOptions): Switches {
   const n = times.length;
+  const byChain = chainDistances(map, targets, n);
   const distances = setDistances(map, targets, n);
   const switches: Switch[] = [];
-  for (const group of competing(map.alternates)) {
+  const groups = competing(map.alternates);
+  for (const group of groups) {
+    const layer = groupLayering(group, map, slots);
     const pick: Array<AlternateSet | null> = [];
     for (let i = 0; i < n; i++) {
       // A set with a `frames` window shows only inside it, and there it is chosen
@@ -328,22 +400,25 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       pick.push(best);
     }
+    const bridgeSame = (arr: Array<AlternateSet | null>) => {
+      for (let i = 0; i < n;) {
+        const a = arr[i];
+        let j = i;
+        while (j + 1 < n && arr[j + 1] === a) j++;
+        const before = i > 0 ? arr[i - 1] : null;
+        const after = j + 1 < n ? arr[j + 1] : null;
+        if (before !== null && before !== undefined && before === after && a !== before) {
+          const gap = times[j + 1]! - times[i]!;
+          if (gap < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) arr[k] = before;
+        }
+        i = j + 1;
+      }
+    };
     // A gap shorter than the minimum span between two runs of one set is that set
     // too: the base art flashing for a frame between them is the flicker the
     // minimum span exists to prevent (measured on the dancer: one-frame breaks at
     // a blurred frame inside a span of one set).
-    for (let i = 0; i < n;) {
-      const a = pick[i];
-      let j = i;
-      while (j + 1 < n && pick[j + 1] === a) j++;
-      const before = i > 0 ? pick[i - 1] : null;
-      const after = j + 1 < n ? pick[j + 1] : null;
-      if (before !== null && before !== undefined && before === after && a !== before) {
-        const gap = times[j + 1]! - times[i]!;
-        if (gap < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = before;
-      }
-      i = j + 1;
-    }
+    bridgeSame(pick);
     // A run shorter than the minimum span shows the base art.
     for (let i = 0; i < n;) {
       const a = pick[i];
@@ -353,6 +428,31 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = null;
       i = j + 1;
     }
+    // #136: a short front-set window (< 2 × switchMin) between two behind-set windows is dropped.
+    if (layer.torsoRank !== null) {
+      let dropped = false;
+      for (let i = 0; i < n;) {
+        const a = pick[i] ?? null;
+        let j = i;
+        while (j + 1 < n && (pick[j + 1] ?? null) === a) j++;
+        if (a !== null && layer.isFront(a)) {
+          let p = i - 1;
+          while (p >= 0 && (pick[p] ?? null) === null) p--;
+          let q = j + 1;
+          while (q < n && (pick[q] ?? null) === null) q++;
+          const prev = p >= 0 ? (pick[p] ?? null) : null;
+          const next = q < n ? (pick[q] ?? null) : null;
+          const to = j + 1 < n ? times[j + 1]! : duration;
+          if (prev !== null && next !== null && layer.isBehind(prev) && layer.isBehind(next) && to - times[i]! < 2 * opts.switchMin - 1e-9) {
+            const fill = prev === next && p === i - 1 && q === j + 1 && Array.from({ length: j - i + 1 }, (_, k) => distances.get(prev.name)![i + k]! <= opts.switchTolerance).every(Boolean) ? prev : null;
+            for (let k = i; k <= j; k++) pick[k] = fill;
+            dropped = true;
+          }
+        }
+        i = j + 1;
+      }
+      if (dropped) bridgeSame(pick);
+    }
     // The segments between boundaries, then each boundary moved (#31).
     const vals: Array<AlternateSet | null> = [pick[0] ?? null];
     const pos: number[] = [];
@@ -398,6 +498,112 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       for (let i = sw.frames[0]; i <= sw.frames[1]; i++) row[i] = o;
     }
   }
+  // #136: when a group's base setup slots sit in front of the torso, an unswitched gap between two
+  // behind-the-torso switches keeps each chain on its behind-the-torso slots on the frames where that
+  // chain stays within tolerance of the surrounding behind sets (with the same minimum-span bridging),
+  // and across a joint behind-to-behind transition where all chains move from one behind set to another.
+  const chainHolds: Array<{ set: string; chain: string; frames: [number, number] }> = [];
+  for (const group of groups) {
+    const layer = groupLayering(group, map, slots);
+    if (!layer.baseInFront) continue;
+    const names = new Set(group.map((a) => a.name));
+    const gSwitches = switches.filter((s) => names.has(s.set));
+    const groupChains = [...new Set(group.flatMap((a) => a.chains))];
+    const cClamp = new Map<string, Array<AlternateSet | null>>();
+    for (const cn of groupChains) {
+      const arr: Array<AlternateSet | null> = Array.from({ length: n }, () => null);
+      for (const sw of gSwitches) {
+        if (!sw.chains.includes(cn)) continue;
+        const set = group.find((a) => a.name === sw.set)!;
+        if (layer.isBehind(set)) for (let i = sw.frames[0]; i <= sw.frames[1]; i++) arr[i] = set;
+      }
+      cClamp.set(cn, arr);
+    }
+    for (let m = 0; m + 1 < gSwitches.length; m++) {
+      const sw0 = gSwitches[m]!;
+      const sw1 = gSwitches[m + 1]!;
+      const set0 = group.find((a) => a.name === sw0.set)!;
+      const set1 = group.find((a) => a.name === sw1.set)!;
+      if (!layer.isBehind(set0) || !layer.isBehind(set1)) continue;
+      const g0 = sw0.frames[1] + 1;
+      const g1 = sw1.frames[0] - 1;
+      if (g0 > g1) continue;
+      const chains = [...new Set([...set0.chains, ...set1.chains])];
+      const cPick = new Map<string, Array<AlternateSet | null>>();
+      for (const cn of chains) {
+        const arr: Array<AlternateSet | null> = Array.from({ length: n }, () => null);
+        for (let i = sw0.frames[0]; i <= sw0.frames[1]; i++) arr[i] = set0;
+        for (let i = sw1.frames[0]; i <= sw1.frames[1]; i++) arr[i] = set1;
+        const d0s = byChain.get(set0.name)?.get(cn);
+        const d1s = byChain.get(set1.name)?.get(cn);
+        for (let i = g0; i <= g1; i++) {
+          const d0 = d0s?.[i] ?? Infinity;
+          const d1 = d1s?.[i] ?? Infinity;
+          if (Math.min(d0, d1) <= opts.switchTolerance) arr[i] = d0 <= d1 ? set0 : set1;
+        }
+        for (let i = g0; i <= g1;) {
+          const a = arr[i];
+          let j = i;
+          while (j + 1 <= g1 && arr[j + 1] === a) j++;
+          const before = arr[i - 1] ?? null;
+          const after = arr[j + 1] ?? null;
+          if (before !== null && before === after && a !== before) {
+            const gap = times[j + 1]! - times[i]!;
+            if (gap < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) arr[k] = before;
+          }
+          i = j + 1;
+        }
+        for (let i = g0; i <= g1;) {
+          const a = arr[i];
+          let j = i;
+          while (j + 1 <= g1 && arr[j + 1] === a) j++;
+          if (a !== null && i > g0 && j < g1 && times[j + 1]! - times[i]! < opts.switchMin - 1e-9) {
+            for (let k = i; k <= j; k++) arr[k] = null;
+          }
+          i = j + 1;
+        }
+        for (let i = g0; i <= g1; i++) {
+          if (arr[i] !== null) cClamp.get(cn)![i] = arr[i]!;
+        }
+        cPick.set(cn, arr);
+      }
+      const anyHeldBehind = chains.some((cn) => {
+        const arr = cPick.get(cn)!;
+        for (let i = g0; i <= g1; i++) if (arr[i] === null) return false;
+        return true;
+      });
+      if (!anyHeldBehind && set0 !== set1) {
+        const frontNear = group.filter((a) => layer.isFront(a)).some((a) => {
+          for (let i = g0; i <= g1; i++) if (distances.get(a.name)![i]! <= opts.switchTolerance) return true;
+          return false;
+        });
+        if (!frontNear) for (const cn of chains) for (let i = g0; i <= g1; i++) cPick.get(cn)![i] = set0;
+      }
+      for (const s of layer.touched) {
+        if (!shown.has(s)) shown.set(s, Array.from({ length: n }, () => slots.get(s)!.setup));
+      }
+      for (let i = g0; i <= g1; i++) {
+        for (const [s, cn] of layer.slotChain) {
+          const a = cPick.get(cn)?.[i] ?? null;
+          if (a !== null) shown.get(s)![i] = a.slots[s] ?? null;
+        }
+        if (layer.torsoSlot !== null && shown.has(layer.torsoSlot)) {
+          const picked = chains.map((cn) => cPick.get(cn)![i]);
+          if (picked.every((a) => a !== null)) shown.get(layer.torsoSlot)![i] = picked[0]!.slots[layer.torsoSlot] ?? slots.get(layer.torsoSlot)!.setup;
+        }
+      }
+    }
+    for (const cn of groupChains) {
+      const arr = cClamp.get(cn)!;
+      for (let i = 0; i < n;) {
+        const a = arr[i];
+        let j = i;
+        while (j + 1 < n && arr[j + 1] === a) j++;
+        if (a !== null) chainHolds.push({ set: a.name, chain: cn, frames: [i, j] });
+        i = j + 1;
+      }
+    }
+  }
   const slotTracks: SlotTrack[] = [];
   for (const s of slotOrder) {
     const row = shown.get(s);
@@ -425,11 +631,11 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
     for (let k = 0; k + 1 < keys.length; k++) keys[k]!.ease = 'stepped';
     offsetTracks.push({ bone: b, property: 'translate', keys });
   }
-  return { switches, slotTracks, offsetTracks, shown, distances };
+  return { switches, slotTracks, offsetTracks, shown, distances, chainHolds };
 }
 
 /** Per chain, the frames on which a switch of a set depicting it shows: its art was painted for that pose. */
-export function coveredChains(switches: readonly Switch[], n: number): Map<string, boolean[]> {
+export function coveredChains(switches: readonly Switch[], n: number, chainHolds?: ReadonlyArray<{ set: string; chain: string; frames: [number, number] }>): Map<string, boolean[]> {
   const out = new Map<string, boolean[]>();
   for (const sw of switches) {
     for (const c of sw.chains) {
@@ -438,6 +644,11 @@ export function coveredChains(switches: readonly Switch[], n: number): Map<strin
       for (let i = sw.frames[0]; i <= sw.frames[1]; i++) row[i] = true;
     }
   }
+  for (const h of chainHolds ?? []) {
+    if (!out.has(h.chain)) out.set(h.chain, Array.from({ length: n }, () => false));
+    const row = out.get(h.chain)!;
+    for (let i = h.frames[0]; i <= h.frames[1]; i++) row[i] = true;
+  }
   return out;
 }
 
@@ -606,35 +817,50 @@ export const ART_EASE_STEP = 3;
  * own world angle, and keys are differences of world angles, so a forearm
  * under a clamped upper arm keeps its own target.
  */
-export function clampArt(switches: readonly Switch[], map: JointMap, targets: Map<string, number[]>): void {
+export function clampArt(switches: readonly Switch[], map: JointMap, targets: Map<string, number[]>, chainHolds?: ReadonlyArray<{ set: string; chain: string; frames: [number, number] }>): void {
+  const boneChain = new Map<string, string>();
+  for (const c of map.chains) for (const b of c.bones) boneChain.set(b, c.name);
+  const clampSpan = (set: AlternateSet, bone: string, [a, b]: [number, number]) => {
+    const limits = set.turn[bone];
+    if (limits === undefined) return;
+    const drawn = set.drawn[bone]!;
+    const target = targets.get(bone)!;
+    const n = target.length;
+    const delta = (i: number): number => {
+      const t = wrap(target[i]! - drawn);
+      const c = Math.min(Math.max(t, limits[0]), limits[1]);
+      return Math.abs(c - t) > RANGE_SLACK ? c - t : 0;
+    };
+    const da = delta(a);
+    const db = delta(b);
+    const easeIn = a > 0 && da !== 0 && Math.sign(delta(a - 1)) === Math.sign(da)
+      ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(da) / ART_EASE_STEP) - 1)
+      : 0;
+    const easeOut = b + 1 < n && db !== 0 && Math.sign(delta(b + 1)) === Math.sign(db)
+      ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(db) / ART_EASE_STEP) - 1)
+      : 0;
+    for (let i = a; i <= b; i++) {
+      const d = delta(i);
+      if (d === 0) continue;
+      const wIn = i - a < easeIn ? (i - a + 1) / (easeIn + 1) : 1;
+      const wOut = b - i < easeOut ? (b - i + 1) / (easeOut + 1) : 1;
+      const w = Math.min(wIn, wOut);
+      target[i] = wrap(target[i]! + w * d);
+    }
+  };
+  const heldChains = new Set((chainHolds ?? []).map((h) => `${h.set}:${h.chain}`));
   for (const sw of switches) {
     const set = map.alternates.find((a) => a.name === sw.set)!;
-    const [a, b] = sw.frames;
-    for (const [bone, limits] of Object.entries(set.turn)) {
-      const drawn = set.drawn[bone]!;
-      const target = targets.get(bone)!;
-      const n = target.length;
-      const delta = (i: number): number => {
-        const t = wrap(target[i]! - drawn);
-        const c = Math.min(Math.max(t, limits[0]), limits[1]);
-        return Math.abs(c - t) > RANGE_SLACK ? c - t : 0;
-      };
-      const da = delta(a);
-      const db = delta(b);
-      const easeIn = a > 0 && da !== 0 && Math.sign(delta(a - 1)) === Math.sign(da)
-        ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(da) / ART_EASE_STEP) - 1)
-        : 0;
-      const easeOut = b + 1 < n && db !== 0 && Math.sign(delta(b + 1)) === Math.sign(db)
-        ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(db) / ART_EASE_STEP) - 1)
-        : 0;
-      for (let i = a; i <= b; i++) {
-        const d = delta(i);
-        if (d === 0) continue;
-        const wIn = i - a < easeIn ? (i - a + 1) / (easeIn + 1) : 1;
-        const wOut = b - i < easeOut ? (b - i + 1) / (easeOut + 1) : 1;
-        const w = Math.min(wIn, wOut);
-        target[i] = wrap(target[i]! + w * d);
-      }
+    for (const bone of Object.keys(set.turn)) {
+      const cn = boneChain.get(bone);
+      if (cn !== undefined && heldChains.has(`${sw.set}:${cn}`)) continue;
+      clampSpan(set, bone, sw.frames);
+    }
+  }
+  for (const h of chainHolds ?? []) {
+    const set = map.alternates.find((a) => a.name === h.set)!;
+    for (const bone of Object.keys(set.turn)) {
+      if (boneChain.get(bone) === h.chain) clampSpan(set, bone, h.frames);
     }
   }
 }