@rig-c/pose 0.19.0 → 0.20.1

package/src/legs.ts

@@ -32,9 +32,11 @@
  * 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
- * landing. A step does too: while the supporting ankle moves more than
+ * 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
+ * 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
  * follows the pose; the released ankle may support again once it has moved
@@ -251,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;
@@ -266,13 +279,23 @@ export interface LegScale {
   high: Array<[number, number]>;
   /** The scale keyed on each frame (clamped). */
   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; and the runs clamped. */
+/** 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);
   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]));
   const sorted = [...ratio].sort((a, b) => a - b);
   const mid = sorted.length >> 1;
   const median = sorted.length % 2 === 1 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2;
@@ -283,6 +306,7 @@ export function legScaleOf(lengths: readonly number[], limits: [number, number])
     low: runs(ratio.map((r) => r < limits[0])),
     high: runs(ratio.map((r) => r > limits[1])),
     scale,
+    asked,
   };
 }
 
@@ -339,10 +363,18 @@ export interface Feet {
   /**
    * 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
+   * no foot is planted). Absent where the rule does not apply (in place, or
    * without `lowerAnkle`).
    */
   lowered?: Lowered[];
+  /**
+   * rig-c/pose#119: runs of frames after a jump or a release where no foot is
+   * planted because the only foot free under #113 is the higher one, and the
+   * lower foot supports as a tracked foot (its x follows its own scaled ankle
+   * track, its y sits on #85's floor) until a foot plants. Absent where the
+   * rule does not apply.
+   */
+  tracked?: Array<{ side: Side; frames: [number, number] }>;
 }
 
 /** A run of frames whose support the lower-ankle rule (rig-c/pose#113) reads differently from the reading before it. */
@@ -383,7 +415,9 @@ export function rollingFloor(ys: readonly number[], times: readonly number[]): n
  * 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`.
+ * The frames whose support this changes are `lowered`. On a frame where no foot
+ * is planted because the only foot free is the higher one (rig-c/pose#119), the
+ * lower foot is tracked (`tracked`).
  */
 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;
@@ -407,6 +441,9 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
   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);
   const mean = (legLength.r + legLength.l) / 2;
   // A jump: both ankles and mid_hip above their rolling floors, for ≥ JUMP_FRAMES frames.
+  // #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.
   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 },
@@ -417,8 +454,23 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     const floor = rollingFloor(ys, times);
     return ys.map((y, i) => floor[i]! - y > JUMP_RISE * unit);
   });
+  const ankleRuns = { r: runs(up[0]!), l: runs(up[1]!) };
+  const stillY = (s: Side, from: number): boolean => {
+    if (from + STILL_FRAMES > n) return false;
+    for (let k = from; k < from + STILL_FRAMES; k++) {
+      if (!up[s === 'r' ? 0 : 1]![k] || Math.abs(ankle[s][k]![1] - ankle[s][k - 1]![1]) / legLength[s] >= STILL_SPEED) return false;
+    }
+    return true;
+  };
+  const raisedHeel = (a: number, b: number): boolean => {
+    const rSpan = ankleRuns.r.find(([s, e]) => s <= a && b <= e)!;
+    const lSpan = ankleRuns.l.find(([s, e]) => s <= a && b <= e)!;
+    if (rSpan[1] === lSpan[1]) return false;
+    const [fSpan, back]: [[number, number], Side] = rSpan[1] < lSpan[1] ? [rSpan, 'l'] : [lSpan, 'r'];
+    return stillY(back, fSpan[1] + 1);
+  };
   const lifted = Array.from({ length: n }, (_, i) => up.every((u) => u[i]));
-  const jumps = runs(lifted).filter(([a, b]) => b - a + 1 >= JUMP_FRAMES);
+  const jumps = runs(lifted).filter(([a, b]) => b - a + 1 >= JUMP_FRAMES && !raisedHeel(a, b));
   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).
@@ -432,6 +484,7 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     return true;
   };
   const support: Array<Side | null> = new Array<Side | null>(n).fill(null);
+  const trkAt: Array<Side | null> = new Array<Side | null>(n).fill(null);
   const changes: Feet['changes'] = [];
   const steps: Step[] = [];
   const open: Partial<Record<Side, Step>> = {};
@@ -505,6 +558,9 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
         freeFrom = -1;
       }
     }
+    if (lowerAnkle && cur === null && released[released.length - 1] !== i && SIDES.some((x) => free(x) && higher(x))) {
+      trkAt[i] = lower(['r', 'l'], i);
+    }
     support[i] = cur;
   }
   const supports: Feet['supports'] = [];
@@ -515,7 +571,15 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
     else supports.push({ side: s, frames: [i, i] });
   }
-  return { feet: { legLength, support, supports, jumps, steps, changes }, released };
+  const tracked: Array<{ side: Side; frames: [number, number] }> = [];
+  for (let i = 0; i < n; i++) {
+    const s = trkAt[i];
+    if (s === null || s === undefined) continue;
+    const last = tracked[tracked.length - 1];
+    if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
+    else tracked.push({ side: s, frames: [i, i] });
+  }
+  return { feet: { legLength, support, supports, jumps, steps, changes, ...(tracked.length > 0 ? { tracked } : {}) }, released };
 }
 
 /** One support span's shift onto the floor (rig-c/pose#85): its side, its frames, and floor − its planted height, world units. */
@@ -532,6 +596,8 @@ export interface Floor {
   shifts: FloorShift[];
 }
 
+let trackFn: ((i: number, s: Side) => number) | undefined;
+
 /**
  * The hip's world origin on every frame, from the supporting foot (header),
  * with every support span on one floor (rig-c/pose#85). `offset(i, side)` is
@@ -548,7 +614,8 @@ export interface Floor {
  * 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
+ * it left (on the floor), carried so the landing frame meets the floor and no
+ * frame inside the flight puts a foot below it (#103). 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
@@ -557,18 +624,24 @@ export interface Floor {
  * `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`).
+ * without `follow`). `track(i, side)` (#119): the same world-x ankle track for
+ * `feet.tracked` frames on a sequence not declared in place.
  */
-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, 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, follow);
-  const closure = follow === undefined ? null : closeLoop(placed.hip);
-  return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
+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, track?: (i: number, s: Side) => number): { hip: Pt[]; floor: Floor | null; blends: BlendFrame[]; closure: Closure | null } {
+  trackFn = track;
+  try {
+    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, 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, follow);
+    const closure = follow === undefined ? null : closeLoop(placed.hip);
+    return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
+  } finally {
+    trackFn = undefined;
+  }
 }
 
 /** 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. */
@@ -607,8 +680,14 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
   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; from: number } | { kind: 'travel'; from: number; at: Pt };
+  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 trkX = trackFn ?? follow;
+  /** How the hip is derived on a frame: held over a foot's anchor, tracking the lower foot on the floor (#119), or carried by the pose's travel from a frame's hip (and for a jump against `floorY`, carried so the landing frame meets the floor and frames inside the flight never go below it, #103). */
+  type Mode =
+    | { kind: 'plant'; side: Side; anchor: Pt; from: number }
+    | { kind: 'track'; side: Side; anchor: Pt; from: number; at: Pt }
+    | { kind: 'travel'; from: number; at: Pt; end?: number; land?: number; carry?: number };
   const of = (mode: Mode, i: number): Pt => {
     if (mode.kind === 'plant') {
       const o = offset(i, mode.side);
@@ -616,9 +695,40 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
       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]];
     }
+    if (mode.kind === 'track') {
+      const o = offset(i, mode.side);
+      const dx = trkX === undefined ? o[0] - offset(mode.from, mode.side)[0] : trkX(i, mode.side) - trkX(mode.from, mode.side);
+      const y = floorY === null ? mode.at[1] + travel(i)[1] - travel(mode.from)[1] : mode.anchor[1] - o[1];
+      return [mode.anchor[0] + dx - o[0], y];
+    }
     const a = travel(i);
     const b = travel(mode.from);
-    return [mode.at[0] + a[0] - b[0], mode.at[1] + a[1] - b[1]];
+    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 (i <= mode.end) {
+        y = Math.max(y, floorY - Math.min(offset(i, 'r')[1], offset(i, 'l')[1]));
+      }
+    }
+    return [mode.at[0] + a[0] - b[0], y];
+  };
+  /** A travel span from `startFrame` off frame `from`'s hip `at`: carried to meet `floorY` at landing when it contains a jump (#103). */
+  const makeTravel = (startFrame: number, from: number, at: Pt): Mode => {
+    let end = startFrame;
+    while (end + 1 < n && (feet.support[end + 1] ?? null) === null && (tracked[end + 1] ?? null) === null) end++;
+    const isJump = floorY !== null && feet.jumps.some(([ja, jb]) => ja <= end && jb >= startFrame);
+    if (!isJump) return { kind: 'travel', from, at };
+    const land = end + 1;
+    let carry = 0;
+    if (land < n) {
+      const landSide = (feet.support[land] ?? tracked[land] ?? null)!;
+      const rawLandY = at[1] + travel(land)[1] - travel(from)[1];
+      const targetLandY = floorY - offset(land, landSide)[1];
+      carry = targetLandY - rawLandY;
+    }
+    return { kind: 'travel', from, at, end, land, carry };
   };
   /** 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 => {
@@ -630,23 +740,38 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
   let blendAt = -1;
   for (let i = 0; i < n; i++) {
     const s = feet.support[i] ?? null;
+    const tr = s === null ? (tracked[i] ?? null) : null;
     if (i === 0) {
-      if (s === null) mode = { kind: 'travel', from: 0, at: start };
-      else {
+      if (s !== null) {
         const o = offset(0, s);
         mode = plant(0, s, [start[0] + o[0], start[1] + o[1]]);
+      } else if (tr !== null) {
+        const o = offset(0, tr);
+        mode = { kind: 'track', side: tr, anchor: [start[0] + o[0], floorY ?? (start[1] + o[1])], from: 0, at: start };
+      } else {
+        mode = makeTravel(0, 0, start);
       }
-    } else if (s === null && mode!.kind === 'plant') {
-      mode = { kind: 'travel', from: i - 1, at: hip[i - 1]! };
+    } else if (s !== null) {
+      if (mode!.kind !== 'plant' || mode!.side !== s) {
+        // The new support is held where it is on this frame, under the hip the old derivation gives here.
+        const here = of(mode!, i);
+        const o = offset(i, s);
+        from = mode;
+        mode = plant(i, s, [here[0] + o[0], here[1] + o[1]]);
+        blendAt = i;
+      }
+    } else if (tr !== null) {
+      if (mode!.kind !== 'track' || mode!.side !== tr) {
+        const prev = hip[i - 1]!;
+        const o = offset(i - 1, tr);
+        mode = { kind: 'track', side: tr, anchor: [prev[0] + o[0], floorY ?? (prev[1] + o[1])], from: i - 1, at: prev };
+        from = null;
+        blendAt = -1;
+      }
+    } else if (mode!.kind !== 'travel') {
+      mode = makeTravel(i, i - 1, hip[i - 1]!);
       from = null;
       blendAt = -1;
-    } else if (s !== null && (mode!.kind === 'travel' || (mode as { side: Side }).side !== s)) {
-      // The new support is held where it is on this frame, under the hip the old derivation gives here.
-      const here = of(mode!, i);
-      const o = offset(i, s);
-      from = mode;
-      mode = plant(i, s, [here[0] + o[0], here[1] + o[1]]);
-      blendAt = i;
     }
     const to = of(mode!, i);
     if (from !== null && i - blendAt < PLANT_BLEND) {
@@ -693,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];
@@ -802,10 +1017,12 @@ export interface StancePosed {
 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);
+  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;
   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;
+    const s = feet.support[i] ?? tracked[i] ?? null;
     if (s === null) continue;
     const f: Side = s === 'r' ? 'l' : 'r';
     read[i] = { state: 'both', side: f, height: (ankle[s][i]![1] - ankle[f][i]![1]) / feet.legLength[f] };

package/src/pose.ts

@@ -150,6 +150,7 @@ export interface HoldParams {
 export interface CleanHold {
   joint: Body18;
   frames: [number, number];
+  excursion?: [number, number];
   jitter: { before: number | null; after: number | null };
 }
 /**
@@ -432,10 +433,16 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
         p.add('POSE_CLEANED', `${hw} is ${typeName(h)}; a hold is { joint, frames: [first, last], jitter: { before, after } }`);
         return;
       }
-      refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['joint', 'frames', 'jitter']);
+      refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['joint', 'frames', 'excursion', 'jitter']);
       if (typeof h.joint !== 'string' || !isBody18(h.joint)) p.add('POSE_CLEANED', `${hw} "joint" is ${typeName(h.joint)}; it must be a body-18 joint: ${BODY18.join(', ')}`);
       const f = h.frames;
-      if (!(Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number))) p.add('POSE_CLEANED', `${hw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      const fOk = Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number);
+      if (!fOk) p.add('POSE_CLEANED', `${hw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      if ('excursion' in h) {
+        const ex = h.excursion;
+        const exOk = Array.isArray(ex) && ex.length === 2 && frameOk(ex[0]) && frameOk(ex[1]) && (ex[0] as number) <= (ex[1] as number) && (!fOk || ((f[0] as number) < (ex[0] as number) && (ex[1] as number) < (f[1] as number)));
+        if (!exOk) p.add('POSE_CLEANED', `${hw} "excursion" is ${typeName(ex)}; it must be [first, last], frame indices strictly inside "frames", first ≤ last`);
+      }
       const j = h.jitter;
       if (!isObject(j)) p.add('POSE_CLEANED', `${hw} "jitter" is ${typeName(j)}; it must be { before, after }`);
       else {
@@ -642,7 +649,7 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
   if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are ${filledLabel} but not declined; only a frame the reading declined is filled, and "declined" says why`);
 }
 const holdParamsOf = (h: HoldParams | 'off'): HoldParams | 'off' => (h === 'off' ? 'off' : { speed: h.speed, reach: h.reach, minSeconds: h.minSeconds, blend: h.blend });
-const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: h.jitter.before, after: h.jitter.after } });
+const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], ...(h.excursion !== undefined ? { excursion: [h.excursion[0], h.excursion[1]] as [number, number] } : {}), jitter: { before: h.jitter.before, after: h.jitter.after } });
 const copyUnheld = (u: CleanUnheld): CleanUnheld => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value });
 
 function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Body18, Joint>> {
@@ -836,7 +843,7 @@ export function writePoseSequence(seq: PoseSequence): string {
     params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(c.params.hipsInferred) } : {}), ...(c.params.hold !== undefined ? { hold: holdParamsOf(c.params.hold) } : {}) },
     spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] },
     jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) },
-    ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
+    ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], ...(h.excursion !== undefined ? { excursion: [h.excursion[0], h.excursion[1]] } : {}), jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
     ...(c.seams !== undefined ? { seams: c.seams.map((x) => ({ joint: x.joint, frame: x.frame, step: round(x.step, 4), gap: x.gap })) } : {}),
     ...(c.unheld !== undefined ? { unheld: c.unheld.map((u) => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value === null ? null : round(u.value, 4) })) } : {}),
   };