@rig-c/pose 0.17.0 → 0.19.0

package/src/legs.ts

@@ -24,11 +24,13 @@
  * **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
  * picture, changing only when the other ankle has been ≥ `PLANT_SWITCH` leg
- * lengths lower for ≥ `PLANT_SWITCH_SECONDS`. The supporting foot is held where
+ * lengths lower for ≥ `PLANT_SWITCH_SECONDS`, and taking support from the frame
+ * it crossed that margin once confirmed (rig-c/pose#102). The supporting foot is held where
  * it was on the frame it took support, moved in y onto the one floor every span
  * shares (rig-c/pose#85, `plantHip`), and the hip is placed so it stays there,
  * through the posed (scaled) legs. A change of support blends the two
- * derivations over `PLANT_BLEND` frames. A jump — both ankles and mid_hip more
+ * derivations in y over `PLANT_BLEND` frames while taking the new derivation's x
+ * immediately (rig-c/pose#102). A jump — both ankles and mid_hip more
  * than `JUMP_RISE` leg lengths above their rolling floor (the 95th-percentile
  * picture y over ± `FLOOR_SECONDS`), for ≥ `JUMP_FRAMES` frames — releases the
  * plant: the hip follows the pose's travel from where it was, and re-plants on
@@ -39,6 +41,15 @@
  * less than `STILL_SPEED` for `STILL_FRAMES` frames (rig-c/pose#47, round 2).
  * The floor is rolling because an ankle's picture y drifts with depth: under
  * one floor for the sequence, HQ's dancer standing still read as jumping.
+ *
+ * **In place** (rig-c/pose#92). A sequence declared `travel: "in-place"` is a
+ * gait that does not travel: its supporting foot moves back in the picture
+ * while the body stays, so holding it turns that slide into travel. Under the
+ * declaration each plant's anchor follows its own ankle's track (`follow`, the
+ * picture x scaled) from the frame it planted, its y still on the one floor; no
+ * step is read, since a foot that follows its track has no plant to drag; and
+ * the hip's x drift from the first frame to the last is spread back over the
+ * frames (`closeLoop`), so the loop carries no net travel.
  */
 import type { Chain, JointMap, Rest } from './map.ts';
 
@@ -325,6 +336,28 @@ export interface Feet {
   steps: Step[];
   /** The frames a change of support (or a landing, or a re-plant) was keyed on: the blend starts there. */
   changes: Array<{ frame: number; from: Side | null; to: Side }>;
+  /**
+   * rig-c/pose#113, read from the lower ankle: each run of frames whose
+   * supporting side differs from the reading before #113 (`was`, `now`; null:
+   * no foot supports). Absent where the rule does not apply (in place, or
+   * without `lowerAnkle`).
+   */
+  lowered?: Lowered[];
+}
+
+/** A run of frames whose support the lower-ankle rule (rig-c/pose#113) reads differently from the reading before it. */
+export interface Lowered {
+  frames: [number, number];
+  was: Side | null;
+  now: Side | null;
+  /**
+   * Why no foot supports, where `now` is null: `released` — the supporting foot
+   * was released on the run's first frame because the other ankle had been lower
+   * past the margin for `PLANT_SWITCH_SECONDS` and could not take support
+   * (released by a step, or moving); `higher` — the only foot free to take
+   * support was the higher one.
+   */
+  cause?: 'released' | 'higher';
 }
 
 /** Each frame's rolling floor of a picture-y series: its `FLOOR_PERCENTILE` over the frames within ± `FLOOR_SECONDS`. */
@@ -339,9 +372,36 @@ export function rollingFloor(ys: readonly number[], times: readonly number[]): n
 /**
  * Which foot supports on each frame, from the reference ankles and hips (picture
  * px, y down) — the header's rules. `times` are the key times; `secondsOf`
- * times a run of frames as the rest of the retarget does.
+ * times a run of frames as the rest of the retarget does. `inPlace` (#92): no
+ * ankle is moving for the step rules, so nothing is released and every foot is
+ * free to take support.
+ *
+ * `lowerAnkle` (rig-c/pose#113, `--plant-feet` on a sequence not declared in
+ * place): a foot whose ankle is higher in the picture than the other's by
+ * `PLANT_SWITCH` leg lengths or more never takes support — not when the plant
+ * starts, not when a step releases the other foot. A supporting foot whose
+ * other ankle has been that much lower for `PLANT_SWITCH_SECONDS` hands support
+ * to it when it is free (as before) and is otherwise released (the hip follows
+ * the pose until a foot may take support). Steps and jumps are read as before.
+ * The frames whose support this changes are `lowered`.
  */
-export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number): Feet {
+export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number, inPlace = false, lowerAnkle = false): Feet {
+  if (inPlace || !lowerAnkle) return readSupports(ankle, hip, times, secondsOf, inPlace, false).feet;
+  const { feet, released } = readSupports(ankle, hip, times, secondsOf, false, true);
+  const before = readSupports(ankle, hip, times, secondsOf, false, false).feet.support;
+  const lowered: Lowered[] = [];
+  feet.support.forEach((now, i) => {
+    const was = before[i] ?? null;
+    if (was === now) return;
+    const last = lowered[lowered.length - 1];
+    if (last !== undefined && last.frames[1] === i - 1 && last.was === was && last.now === now) last.frames[1] = i;
+    else lowered.push({ frames: [i, i], was, now, ...(now === null ? { cause: released.includes(i) ? ('released' as const) : ('higher' as const) } : {}) });
+  });
+  return { ...feet, lowered };
+}
+
+/** The reader; `released` (#113): the frames a supporting foot was released because the lower foot could not take support. */
+function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number, inPlace: boolean, lowerAnkle: boolean): { feet: Feet; released: number[] } {
   const n = ankle.r.length;
   const legLength = {} as Record<Side, number>;
   for (const s of SIDES) legLength[s] = percentile(ankle[s].map((a, i) => Math.hypot(a[0] - hip[s][i]![0], a[1] - hip[s][i]![1])), 0.5);
@@ -364,7 +424,9 @@ export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side,
   // Ankle speeds, leg lengths a frame (0 on the first frame).
   const speed = {} as Record<Side, number[]>;
   for (const s of SIDES) speed[s] = ankle[s].map((a, i) => (i === 0 ? 0 : Math.hypot(a[0] - ankle[s][i - 1]![0], a[1] - ankle[s][i - 1]![1]) / legLength[s]));
-  const moving = (s: Side, i: number) => speed[s][i]! > STEP_SPEED;
+  // In place (rig-c/pose#92) the supporting foot follows its own track instead of being held, so a
+  // moving ankle has no plant to drag and nothing is released: no step, and every foot is free.
+  const moving = (s: Side, i: number) => !inPlace && speed[s][i]! > STEP_SPEED;
   const still = (s: Side, i: number) => {
     for (let k = i - STILL_FRAMES + 1; k <= i; k++) if (k >= 0 && !(speed[s][k]! < STILL_SPEED)) return false;
     return true;
@@ -375,6 +437,8 @@ export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side,
   const open: Partial<Record<Side, Step>> = {};
   let cur: Side | null = null;
   let lowerFrom = -1;
+  let freeFrom = -1;
+  const released: number[] = [];
   const lower = (cands: Side[], i: number): Side => (cands.length === 2 ? (ankle.l[i]![1] > ankle.r[i]![1] ? 'l' : 'r') : cands[0]!);
   for (let i = 0; i < n; i++) {
     // A released ankle re-plants once it has been still for STILL_FRAMES frames.
@@ -389,35 +453,57 @@ export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side,
     if (jump[i]) {
       cur = null;
       lowerFrom = -1;
+      freeFrom = -1;
       continue;
     }
     const free = (s: Side) => open[s] === undefined && !moving(s, i);
+    // #113: a foot higher than the other by PLANT_SWITCH leg lengths or more does not take support.
+    const higher = (s: Side) => ankle[s === 'r' ? 'l' : 'r'][i]![1] - ankle[s][i]![1] >= PLANT_SWITCH * mean;
+    const may = (s: Side) => free(s) && !(lowerAnkle && higher(s));
     if (cur !== null && moving(cur, i)) {
       const other: Side = cur === 'r' ? 'l' : 'r';
-      const to: Side | null = free(other) ? other : null;
+      const to: Side | null = may(other) ? other : null;
       const st: Step = { side: cur, frames: [i, n - 1], replant: null, to };
       steps.push(st);
       open[cur] = st;
       if (to !== null) changes.push({ frame: i, from: cur, to });
       cur = to;
       lowerFrom = -1;
+      freeFrom = -1;
     } else if (cur === null) {
-      const cands = SIDES.filter(free);
+      const cands = SIDES.filter(may);
       if (cands.length > 0) {
         cur = lower(cands, i);
         changes.push({ frame: i, from: null, to: cur });
         lowerFrom = -1;
+        freeFrom = -1;
       }
     } else {
       const other: Side = cur === 'r' ? 'l' : 'r';
-      if (free(other) && ankle[other][i]![1] - ankle[cur][i]![1] >= PLANT_SWITCH * mean) {
+      if ((free(other) || lowerAnkle) && higher(cur)) {
         if (lowerFrom < 0) lowerFrom = i;
-        if (secondsOf([lowerFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
-          changes.push({ frame: i, from: cur, to: other });
-          cur = other;
-          lowerFrom = -1;
+        if (free(other)) {
+          if (freeFrom < 0) freeFrom = i;
+          // #102: once confirmed over PLANT_SWITCH_SECONDS, the incoming foot takes support from the landing frame it crossed the margin on.
+          if (secondsOf([freeFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
+            for (let k = freeFrom; k < i; k++) support[k] = other;
+            changes.push({ frame: freeFrom, from: cur, to: other });
+            cur = other;
+            lowerFrom = -1;
+            freeFrom = -1;
+          }
+        } else {
+          freeFrom = -1;
+          if (secondsOf([lowerFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
+            cur = null; // #113: the lower foot may not take support (released, or moving); neither foot supports
+            released.push(i);
+            lowerFrom = -1;
+          }
         }
-      } else lowerFrom = -1;
+      } else {
+        lowerFrom = -1;
+        freeFrom = -1;
+      }
     }
     support[i] = cur;
   }
@@ -429,7 +515,7 @@ export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side,
     if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
     else supports.push({ side: s, frames: [i, i] });
   }
-  return { legLength, support, supports, jumps, steps, changes };
+  return { feet: { legLength, support, supports, jumps, steps, changes }, released };
 }
 
 /** One support span's shift onto the floor (rig-c/pose#85): its side, its frames, and floor − its planted height, world units. */
@@ -459,23 +545,49 @@ export interface Floor {
  * floor is `floor` when given (`--floor`, world units), and otherwise the median
  * of the spans' planted heights; each span's anchor moves in y by floor − its
  * planted height, and the hip with it, so everything above follows. A change of
- * support still blends the two derivations over `PLANT_BLEND` frames, now
- * between two spans on the floor; a jump follows the pose's travel from the hip
+ * support still blends the two derivations' y over `PLANT_BLEND` frames, now
+ * between two spans on the floor, while holding the planted foot's x from the
+ * frame it lands on (#102); a jump follows the pose's travel from the hip
  * it left (on the floor) and lands on the floor. On a blend frame the hip is
  * between the two derivations, so the supporting ankle is off its anchor:
  * `blends` lists those frames with the anchor's y, and `holdBlend` stretches
  * the supporting leg to keep it there. Null `floor` in the result: there is no
  * support span.
+ *
+ * `follow(i, side)` (#92, an in-place sequence): the supporting ankle's track,
+ * world x. A plant's anchor x then moves by follow(i) − follow(the frame it
+ * planted), and the loop is closed (`closeLoop`, `closure` in the result; null
+ * without `follow`).
  */
-export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floor?: number): { hip: Pt[]; floor: Floor | null; blends: BlendFrame[] } {
-  const picture = placeHip(feet, offset, travel, start, null);
+export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floor?: number, follow?: (i: number, s: Side) => number): { hip: Pt[]; floor: Floor | null; blends: BlendFrame[]; closure: Closure | null } {
+  const picture = placeHip(feet, offset, travel, start, null, follow);
   const heights = feet.supports.map((sp) => picture.anchors.get(sp.frames[0]));
-  if (heights.length === 0) return { hip: picture.hip, floor: null, blends: picture.blends };
+  if (heights.length === 0) return { hip: picture.hip, floor: null, blends: picture.blends, closure: null };
   if (heights.some((h) => h === undefined)) throw new Error('plantHip: a support span starts on a frame no plant started on');
   const y = floor ?? percentile(heights as number[], 0.5);
   const shifts = feet.supports.map((sp, k) => ({ side: sp.side, frames: [sp.frames[0], sp.frames[1]] as [number, number], shift: y - heights[k]! }));
-  const placed = placeHip(feet, offset, travel, start, y);
-  return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends };
+  const placed = placeHip(feet, offset, travel, start, y, follow);
+  const closure = follow === undefined ? null : closeLoop(placed.hip);
+  return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
+}
+
+/** In place (rig-c/pose#92): the hip's x travel from the first frame to the last before the loop was closed, world units, and the frames it was spread over. */
+export interface Closure {
+  drift: number;
+  frames: number;
+}
+
+/**
+ * Close an in-place loop (rig-c/pose#92): the hip's x on frame i moves by
+ * −drift · i / (n − 1), drift its x on the last frame less its x on the first,
+ * so the last frame's hip x is the first's and the loop carries no net travel.
+ * The y is the floor's (#85) and is not touched. In place.
+ */
+export function closeLoop(hip: Pt[]): Closure {
+  const n = hip.length;
+  const drift = n > 1 ? hip[n - 1]![0] - hip[0]![0] : 0;
+  if (n > 1) for (let i = 0; i < n; i++) hip[i]![0] -= (drift * i) / (n - 1);
+  return { drift, frames: n };
 }
 
 /** A frame inside the blend after a change of support (or a landing): the side now supporting, and the world y its plant holds the ankle at. */
@@ -490,17 +602,19 @@ export interface BlendFrame {
  * picture puts it (`floorY` null) or at world y `floorY`; and each plant's
  * picture anchor y, by the frame its support span starts on.
  */
-function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floorY: number | null): { hip: Pt[]; anchors: Map<number, number>; blends: BlendFrame[] } {
+function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floorY: number | null, follow?: (i: number, s: Side) => number): { hip: Pt[]; anchors: Map<number, number>; blends: BlendFrame[] } {
   const n = feet.support.length;
   const hip: Pt[] = [];
   const anchors = new Map<number, number>();
   const blends: BlendFrame[] = [];
   /** How the hip is derived on a frame: held over a foot's anchor, or carried by the pose's travel from a frame's hip. */
-  type Mode = { kind: 'plant'; side: Side; anchor: Pt } | { kind: 'travel'; from: number; at: Pt };
+  type Mode = { kind: 'plant'; side: Side; anchor: Pt; from: number } | { kind: 'travel'; from: number; at: Pt };
   const of = (mode: Mode, i: number): Pt => {
     if (mode.kind === 'plant') {
       const o = offset(i, mode.side);
-      return [mode.anchor[0] - o[0], mode.anchor[1] - o[1]];
+      // In place (#92) the anchor's x follows the supporting ankle's own track from the frame it planted.
+      const dx = follow === undefined ? 0 : follow(i, mode.side) - follow(mode.from, mode.side);
+      return [mode.anchor[0] + dx - o[0], mode.anchor[1] - o[1]];
     }
     const a = travel(i);
     const b = travel(mode.from);
@@ -509,7 +623,7 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
   /** A plant from frame i: its anchor's x where the foot is, its y there or on the floor. */
   const plant = (i: number, side: Side, at: Pt): Mode => {
     anchors.set(i, at[1]);
-    return { kind: 'plant', side, anchor: [at[0], floorY ?? at[1]] };
+    return { kind: 'plant', side, anchor: [at[0], floorY ?? at[1]], from: i };
   };
   let mode: Mode | null = null;
   let from: Mode | null = null;
@@ -538,7 +652,8 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     if (from !== null && i - blendAt < PLANT_BLEND) {
       const w = (i - blendAt + 1) / (PLANT_BLEND + 1);
       const f = of(from, i);
-      hip.push([f[0] + (to[0] - f[0]) * w, f[1] + (to[1] - f[1]) * w]);
+      // #102: blend y only; x takes the new derivation immediately so the planted foot does not slide across the blend.
+      hip.push([to[0], f[1] + (to[1] - f[1]) * w]);
       const m = mode!;
       if (m.kind === 'plant') blends.push({ frame: i, side: m.side, y: m.anchor[1] });
     } else {
@@ -551,23 +666,72 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
 
 // --- stance (rig-c/pose#60) --------------------------------------------------
 
-/** A free leg is scaled within these factors to reach the floor (raised from below or lowered from above); past them the frame is reported, not forced. */
+/**
+ * A free leg is scaled within these factors to reach the floor (raised from below or lowered from above); past them the frame is reported, not forced.
+ * The default: a frame whose leg the picture folds further has its lower bound from the leg's own range (`stanceRangeOf`, #95).
+ */
 export const STANCE_BOUNDS: readonly [number, number] = [0.92, 1.08];
 
+/** Per side, per frame: the lower bound of the leg's stretch (#95). */
+export type StanceLower = Record<Side, readonly number[]>;
+
+/**
+ * The leg's own range (rig-c/pose#95). Per side, r(i) = the leg's picture
+ * length hip → ankle on frame i ÷ its straight length (`STRAIGHT_PERCENTILE`
+ * of that length over the sequence, as `--leg-scale` reads a segment's), and
+ * the lower bound on frame i is min(`STANCE_BOUNDS[0]`, r(i)): the rig leg may
+ * 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 {
+  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]));
+  }
+  return 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];
+}
+
+/** The lowest lower bound per side over `frames`, where any is below the default (#95); null where none is. */
+function rangeUsed(lower: StanceLower | undefined, frames: ReadonlyArray<{ side: Side; frame: number }>): Partial<Record<Side, number>> | null {
+  const out: Partial<Record<Side, number>> = {};
+  for (const { side, frame } of frames) {
+    const lo = lowerOf(lower, side, frame);
+    if (lo < STANCE_BOUNDS[0]) out[side] = Math.min(out[side] ?? Infinity, lo);
+  }
+  return Object.keys(out).length === 0 ? null : out;
+}
+
 /** A lifted free foot is planted again only when its height comes back under this fraction of the tolerance (#87): hysteresis, a stated factor, not tuned. */
 export const STANCE_RELEASE = 0.8;
 /** A run of one state shorter than this many seconds, between two runs of the other state, takes their state (#87): a foot cannot take a stance for one frame. */
 export const STANCE_MIN_SECONDS = 0.1;
 
+/**
+ * A free ankle's state on a frame (#60, #114): `both`, within the tolerance of
+ * the supporting one in either direction, so both feet are planted; `lifted`,
+ * past it above; `below`, past it below — a support error, not a stance, never
+ * planted. Past the tolerance either way the pose's height is kept.
+ */
+export type StanceState = 'both' | 'lifted' | 'below';
+
 /** A run of frames with one free side in one state. */
 export interface StanceRun {
-  /** `both`: the free ankle within the tolerance of the floor, so both feet are planted; `lifted`: above it, the pose's height kept. */
-  state: 'both' | 'lifted';
+  /** `both`: the free ankle within the tolerance of the floor, so both feet are planted; `lifted`: past it above, `below`: past it below (#114), the pose's height kept. */
+  state: StanceState;
   /** The side that is not supporting. */
   side: Side;
   frames: [number, number];
-  /** The free ankle's largest height above the supporting one in the picture, in that side's leg lengths. */
+  /** The free ankle's largest height above the supporting one in the picture, in that side's leg lengths (negative where it is below on every frame). */
   maxHeight: number;
+  /** `below` (#114): the free ankle's largest distance below the supporting one in the picture, in that side's leg lengths. */
+  maxDepth?: number;
   /** `both`: the smallest and largest stretch keyed (bounded); `lifted`: null. */
   k: { min: number; max: number } | null;
   /** #87: a run read in `state`, shorter than `STANCE_MIN_SECONDS` between two runs of the other state, which took their state; its frames are in their run too, and `k` is null. */
@@ -582,6 +746,8 @@ export interface StanceOver {
   needed: number | null;
   /** The free ankle's largest distance left from the floor after the bound, world units. */
   left: number;
+  /** #95: the bound on the frame of `needed`, where the leg's own range set it below the default. */
+  bound?: [number, number];
 }
 
 export interface Stance {
@@ -592,6 +758,8 @@ export interface Stance {
   /** The shortest run kept as its own state, seconds (#87). */
   minSeconds: number;
   bounds: readonly [number, number];
+  /** #95: per side, the lowest lower bound the leg's own range set on a planted-both frame, where any is below `bounds[0]`. */
+  range?: Partial<Record<Side, number>>;
   runs: StanceRun[];
   over: StanceOver[];
   /** Per frame: the free side and the stretch keyed on it, or null (lifted, a jump, no support). */
@@ -608,26 +776,33 @@ export interface StancePosed {
  * Both feet planted when the free ankle is near the floor (rig-c/pose#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 (`ankle`, px, y down) in the
- * free side's leg length — the unit of every FEET threshold. Within `tolerance`,
- * the frame is planted both: the free leg is to be stretched along its chain by
+ * free side's leg length — the unit of every FEET threshold. The tolerance is a
+ * distance (#114): within `tolerance` of the supporting ankle, above it or below
+ * it (|h| ≤ tolerance), the frame is planted both: the free leg is to be stretched along its chain by
  * k = (root y − floor y) / (root y − ankle y) on the posed rig (`posed`, world,
  * y up), the floor being the supporting ankle's posed y; k is held within
  * `STANCE_BOUNDS` (a free ankle below the floor shortens its leg, one above
- * lengthens it), and a frame past them is listed in `over`. Above the tolerance
- * the foot is lifted and keeps the pose's height.
+ * lengthens it), its lower bound on the frame the leg's own (`lower`, #95)
+ * where the picture folds that leg further, and a frame past them is listed in
+ * `over`. Past the tolerance above, the foot is lifted and keeps the pose's
+ * height. Past it below (h < −tolerance), the free ankle is far below the
+ * supporting one: a support error, not a stance. That frame is never planted
+ * both, keeps the pose's height, and is read `below` (#114); before #114 the
+ * gap was signed, and a lifted foot read as supporting had the grounded leg
+ * shrunk up to it.
  *
- * The state is read with hysteresis (#87): a planted foot is lifted when its
- * height goes past `tolerance`, and a lifted one is planted again only under
- * `STANCE_RELEASE × tolerance`, so noise at the threshold does not flip it. A
+ * The state is read with hysteresis (#87) on |h|: a planted foot leaves the
+ * stance when |h| goes past `tolerance`, and one past it is planted again only
+ * under `STANCE_RELEASE × tolerance`, so noise at the threshold does not flip it. A
  * run of one state shorter than `STANCE_MIN_SECONDS` (`secondsOf`, the
  * retarget's timing of a run) between two runs of the other state, on the same
  * 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): Stance {
+export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, tolerance: number, posed: (i: number) => StancePosed, secondsOf: (run: [number, number]) => number, lower?: StanceLower): Stance {
   const n = feet.support.length;
   const stretch: Stance['stretch'] = new Array(n).fill(null);
-  type Read = { state: 'both' | 'lifted'; side: Side; height: number };
+  type Read = { state: StanceState; side: Side; height: number };
   const read: Array<Read | null> = new Array<Read | null>(n).fill(null);
   for (let i = 0; i < n; i++) {
     const s = feet.support[i] ?? null;
@@ -636,9 +811,12 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
     read[i] = { state: 'both', side: f, height: (ankle[s][i]![1] - ankle[f][i]![1]) / feet.legLength[f] };
   }
   // Blocks of consecutive frames with one free side. Inside a block the state changes only when the
-  // other state's condition (lifted: past the tolerance; planted again: under STANCE_RELEASE of it)
-  // holds for STANCE_MIN_SECONDS; a shorter crossing with the current state on both sides of it is
-  // absorbed. A crossing that runs to the block's end is taken: nothing of the current state follows it.
+  // other state's condition (out of the stance: |h| past the tolerance; planted again: |h| under
+  // STANCE_RELEASE of it) holds for STANCE_MIN_SECONDS; a shorter crossing with the current state on
+  // both sides of it is absorbed. A crossing that runs to the block's end is taken: nothing of the
+  // current state follows it. Out of the stance, a frame is `lifted` or `below` by the sign of h; a
+  // frame absorbed into it takes the state of the frame before it.
+  const away = (h: number): 'lifted' | 'below' => (h > 0 ? 'lifted' : 'below');
   const absorbed: StanceRun[] = [];
   for (let i = 0; i < n; ) {
     const r0 = read[i];
@@ -648,34 +826,36 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
     }
     let end = i;
     while (end + 1 < n && read[end + 1] !== null && read[end + 1]!.side === r0.side) end++;
-    let state: 'both' | 'lifted' = r0.height > tolerance ? 'lifted' : 'both';
+    let planted = Math.abs(r0.height) <= tolerance;
     let j = i;
     while (j <= end) {
-      const crosses = (k: number) => (state === 'both' ? read[k]!.height > tolerance : read[k]!.height <= STANCE_RELEASE * tolerance);
+      const crosses = (k: number) => (planted ? Math.abs(read[k]!.height) > tolerance : Math.abs(read[k]!.height) <= STANCE_RELEASE * tolerance);
       if (!crosses(j)) {
-        read[j]!.state = state;
+        read[j]!.state = planted ? 'both' : away(read[j]!.height);
         j++;
         continue;
       }
       let k = j;
       while (k + 1 <= end && crosses(k + 1)) k++;
-      const other = state === 'both' ? 'lifted' : 'both';
       if (k < end && secondsOf([j, k]) < STANCE_MIN_SECONDS) {
         let maxHeight = -Infinity;
+        let far = 0;
         for (let x = j; x <= k; x++) {
-          read[x]!.state = state;
+          read[x]!.state = planted ? 'both' : read[x - 1]!.state;
           maxHeight = Math.max(maxHeight, read[x]!.height);
+          if (Math.abs(read[x]!.height) > Math.abs(far)) far = read[x]!.height;
         }
-        absorbed.push({ state: other, side: r0.side, frames: [j, k], maxHeight, k: null, absorbed: true });
+        const other: StanceState = planted ? away(far) : 'both';
+        absorbed.push({ state: other, side: r0.side, frames: [j, k], maxHeight, ...(other === 'below' ? { maxDepth: -far } : {}), k: null, absorbed: true });
       } else {
-        state = other;
-        for (let x = j; x <= k; x++) read[x]!.state = state;
+        planted = !planted;
+        for (let x = j; x <= k; x++) read[x]!.state = planted ? 'both' : away(read[x]!.height);
       }
       j = k + 1;
     }
     i = end + 1;
   }
-  type Row = { state: 'both' | 'lifted'; side: Side; height: number; k: number | null; needed: number | null; over: boolean; left: number };
+  type Row = { state: StanceState; side: Side; height: number; k: number | null; needed: number | null; over: boolean; left: number; lo: number };
   const rows: Array<Row | null> = new Array<Row | null>(n).fill(null);
   for (let i = 0; i < n; i++) {
     const r = read[i];
@@ -683,8 +863,9 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
     const s: Side = r.side === 'r' ? 'l' : 'r';
     const f = r.side;
     const height = r.height;
-    if (r.state === 'lifted') {
-      rows[i] = { state: 'lifted', side: f, height, k: null, needed: null, over: false, left: 0 };
+    const lo = lowerOf(lower, f, i);
+    if (r.state !== 'both') {
+      rows[i] = { state: r.state, side: f, height, k: null, needed: null, over: false, left: 0, lo };
       continue;
     }
     const p = posed(i);
@@ -693,12 +874,13 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
     const a = p.ankle[f][1];
     const ok = root - a > 1e-9 && root - floor > 1e-9;
     const needed = ok ? (root - floor) / (root - a) : null;
-    const k = needed === null ? 1 : Math.min(Math.max(needed, STANCE_BOUNDS[0]), STANCE_BOUNDS[1]);
-    const over = needed === null || needed < STANCE_BOUNDS[0] || needed > STANCE_BOUNDS[1];
+    const k = needed === null ? 1 : Math.min(Math.max(needed, lo), STANCE_BOUNDS[1]);
+    const over = needed === null || needed < lo || needed > STANCE_BOUNDS[1];
     const left = Math.abs(root - k * (root - a) - floor);
-    rows[i] = { state: 'both', side: f, height, k, needed, over, left };
+    rows[i] = { state: 'both', side: f, height, k, needed, over, left, lo };
     if (k !== 1) stretch[i] = { side: f, k };
   }
+  const boundOf = (lo: number): { bound?: [number, number] } => (lo < STANCE_BOUNDS[0] ? { bound: [lo, STANCE_BOUNDS[1]] } : {});
   const runs: StanceRun[] = [];
   const over: StanceOver[] = [];
   for (let i = 0; i < n; i++) {
@@ -708,19 +890,26 @@ export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, toleran
     if (last !== undefined && last.frames[1] === i - 1 && last.state === r.state && last.side === r.side) {
       last.frames[1] = i;
       last.maxHeight = Math.max(last.maxHeight, r.height);
+      if (last.maxDepth !== undefined) last.maxDepth = Math.max(last.maxDepth, -r.height);
       if (last.k !== null && r.k !== null) last.k = { min: Math.min(last.k.min, r.k), max: Math.max(last.k.max, r.k) };
-    } else runs.push({ state: r.state, side: r.side, frames: [i, i], maxHeight: r.height, k: r.k === null ? null : { min: r.k, max: r.k } });
+    } else runs.push({ state: r.state, side: r.side, frames: [i, i], maxHeight: r.height, ...(r.state === 'below' ? { maxDepth: -r.height } : {}), k: r.k === null ? null : { min: r.k, max: r.k } });
     if (!r.over) continue;
     const o = over[over.length - 1];
     if (o !== undefined && o.frames[1] === i - 1 && o.side === r.side) {
       o.frames[1] = i;
-      o.needed = o.needed === null || r.needed === null ? null : Math.abs(r.needed - 1) > Math.abs(o.needed - 1) ? r.needed : o.needed;
+      const takes = o.needed !== null && (r.needed === null || Math.abs(r.needed - 1) > Math.abs(o.needed - 1));
+      o.needed = o.needed === null || r.needed === null ? null : takes ? r.needed : o.needed;
+      if (takes) {
+        delete o.bound;
+        Object.assign(o, boundOf(r.lo));
+      }
       o.left = Math.max(o.left, r.left);
-    } else over.push({ side: r.side, frames: [i, i], needed: r.needed, left: r.left });
+    } else over.push({ side: r.side, frames: [i, i], needed: r.needed, left: r.left, ...boundOf(r.lo) });
   }
   for (const x of absorbed) runs.push(x);
   runs.sort((a, b) => a.frames[0] - b.frames[0] || (a.absorbed === true ? 1 : 0) - (b.absorbed === true ? 1 : 0));
-  return { tolerance, release: STANCE_RELEASE, minSeconds: STANCE_MIN_SECONDS, bounds: STANCE_BOUNDS, runs, over, stretch };
+  const range = rangeUsed(lower, rows.flatMap((r, i) => (r !== null && r.state === 'both' ? [{ side: r.side, frame: i }] : [])));
+  return { tolerance, release: STANCE_RELEASE, minSeconds: STANCE_MIN_SECONDS, bounds: STANCE_BOUNDS, ...(range === null ? {} : { range }), runs, over, stretch };
 }
 
 // --- the blend held on the floor (rig-c/pose#85) ------------------------------
@@ -734,10 +923,14 @@ export interface BlendRun {
   frames: [number, number];
   /** The smallest and largest stretch keyed (bounded). */
   k: { min: number; max: number };
+  /** #95: the lowest lower bound on the run's frames, where the leg's own range set it below the default. */
+  lower?: number;
 }
 
 export interface BlendHold {
   bounds: readonly [number, number];
+  /** #95: per side, the lowest lower bound the leg's own range set on a blend frame, where any is below `bounds[0]`. */
+  range?: Partial<Record<Side, number>>;
   runs: BlendRun[];
   /** Runs whose stretch needed a factor past the bounds: held at the bound, the remainder left to the blend. */
   over: StanceOver[];
@@ -751,38 +944,50 @@ export interface BlendHold {
  * supporting ankle is off the y its plant holds. Its leg is stretched along its
  * chain about the chain's root, as `--stance` stretches a free leg (`stanceOf`):
  * k = (root y − anchor y) / (root y − ankle y) on the posed rig (`posed`, world,
- * y up), held within `STANCE_BOUNDS`; a frame past them is listed in `over`, and
+ * y up), held within `STANCE_BOUNDS` — its lower bound on the frame the leg's own
+ * (`lower`, #95) as `stanceOf`'s; a frame past them is listed in `over`, and
  * the remainder stays with the blend. An ankle within `BLEND_HOLD_WITHIN` of the
  * anchor is not stretched.
  */
-export function holdBlend(blends: readonly BlendFrame[], n: number, posed: (i: number) => StancePosed): BlendHold {
+export function holdBlend(blends: readonly BlendFrame[], n: number, posed: (i: number) => StancePosed, lower?: StanceLower): BlendHold {
   const stretch: BlendHold['stretch'] = new Array(n).fill(null);
   const runs: BlendRun[] = [];
   const over: StanceOver[] = [];
+  const held: Array<{ side: Side; frame: number }> = [];
   for (const b of blends) {
     const p = posed(b.frame);
     const root = p.root[b.side][1];
     const a = p.ankle[b.side][1];
     if (Math.abs(a - b.y) <= BLEND_HOLD_WITHIN) continue;
+    held.push({ side: b.side, frame: b.frame });
     const ok = root - a > 1e-9 && root - b.y > 1e-9;
     const needed = ok ? (root - b.y) / (root - a) : null;
-    const k = needed === null ? 1 : Math.min(Math.max(needed, STANCE_BOUNDS[0]), STANCE_BOUNDS[1]);
+    const lo = lowerOf(lower, b.side, b.frame);
+    const k = needed === null ? 1 : Math.min(Math.max(needed, lo), STANCE_BOUNDS[1]);
     const left = Math.abs(root - k * (root - a) - b.y);
+    const bound = lo < STANCE_BOUNDS[0] ? { bound: [lo, STANCE_BOUNDS[1]] as [number, number] } : {};
     if (k !== 1) {
       stretch[b.frame] = { side: b.side, k };
       const last = runs[runs.length - 1];
       if (last !== undefined && last.side === b.side && last.frames[1] === b.frame - 1) {
         last.frames[1] = b.frame;
         last.k = { min: Math.min(last.k.min, k), max: Math.max(last.k.max, k) };
-      } else runs.push({ side: b.side, frames: [b.frame, b.frame], k: { min: k, max: k } });
+        if (lo < STANCE_BOUNDS[0]) last.lower = Math.min(last.lower ?? Infinity, lo);
+      } else runs.push({ side: b.side, frames: [b.frame, b.frame], k: { min: k, max: k }, ...(lo < STANCE_BOUNDS[0] ? { lower: lo } : {}) });
     }
-    if (needed !== null && needed >= STANCE_BOUNDS[0] && needed <= STANCE_BOUNDS[1]) continue;
+    if (needed !== null && needed >= lo && needed <= STANCE_BOUNDS[1]) continue;
     const o = over[over.length - 1];
     if (o !== undefined && o.side === b.side && o.frames[1] === b.frame - 1) {
       o.frames[1] = b.frame;
-      o.needed = o.needed === null || needed === null ? null : Math.abs(needed - 1) > Math.abs(o.needed - 1) ? needed : o.needed;
+      const takes = o.needed !== null && (needed === null || Math.abs(needed - 1) > Math.abs(o.needed - 1));
+      o.needed = o.needed === null || needed === null ? null : takes ? needed : o.needed;
+      if (takes) {
+        delete o.bound;
+        Object.assign(o, bound);
+      }
       o.left = Math.max(o.left, left);
-    } else over.push({ side: b.side, frames: [b.frame, b.frame], needed, left });
+    } else over.push({ side: b.side, frames: [b.frame, b.frame], needed, left, ...bound });
   }
-  return { bounds: STANCE_BOUNDS, runs, over, stretch };
+  const range = rangeUsed(lower, held);
+  return { bounds: STANCE_BOUNDS, ...(range === null ? {} : { range }), runs, over, stretch };
 }