@rig-c/pose 0.40.0 → 0.42.0

package/src/pelvis.ts

@@ -31,6 +31,11 @@
  *   scan runs down to where the colour was found. The first patch that holds
  *   and is not the background is the garment; with none, the midpoint's median
  *   is read as it is.
+ *   The line is fitted through the band's top edge (rig-c/pose#318): where a
+ *   strip of the garment is too thin for the colour test (a waistband drawn as
+ *   two ink lines), the tops step between the strip's lines, and each column
+ *   is followed up to its topmost garment pixel; an edge that cuts across the
+ *   band under it (a fold) is declined.
  *
  * The forearms are not read: pixels near the segments elbow → wrist (and the
  * hands) are masked, since a hanging arm passes the hips in a walk. A frame
@@ -76,13 +81,17 @@ export const MAX_RMS = 2.5;
 export const ARM_RADIUS = 0.15;
 /** Hips closer than this in the picture, px, have no span to read across (a figure seen side-on). */
 export const MIN_SPAN = 6;
+/** The band's top is taken above the scan's tops only when their climbs to it differ by more than this many rows (rig-c/pose#318): each end of a clean edge's climb is found to a row. */
+export const CLIMB_SPREAD = 2;
+/** The band's top is climbed against at most this many garment colours (rig-c/pose#318): a paletted garment's own, or a painted one's fullest cells. */
+export const MAX_CLOTH = 16;
 
 /**
  * One frame's reading: the tilt (Spine degrees, r_hip → l_hip), or why it was declined. A waistband
  * read through the window mean says so (`mean`), and one whose colour was found below the hips says
- * how far (`below`, px).
+ * how far (`below`, px); one whose band top lay above the colour's edge in some columns says how many (`raised`, #318).
  */
-export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number } | { kind: string; why: string };
+export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number; raised?: number } | { kind: string; why: string };
 
 /** The frame as RGB over white, its background colour, and which pixels are masked (forearms, hands). */
 interface Frame {
@@ -321,6 +330,7 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
       }
     }
   }
+  const raised = toBandTop(f, tops, g, top, colourAt);
   const share = tops.length / cols;
   if (share < MIN_COVER) {
     return above > cols / 2 ? { kind: 'garment above the band', why: `the garment runs above the band read (${above} of ${cols} columns carry its colour ${(1.5 * span).toFixed(0)} px above the hips); no waistband edge` } : { kind: 'waistband edge too short', why: `the garment's top edge is found in ${tops.length} of the ${cols} columns between the hips (${(100 * share).toFixed(0)}% < ${100 * MIN_COVER}%)` };
@@ -329,7 +339,197 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
   if (fit === null) return { kind: 'no line', why: 'the garment\'s top edge does not fit a line (fewer than three columns)' };
   if (fit.rms > MAX_RMS) return { kind: 'not a straight waistband', why: `the garment's top edge lies ${fit.rms.toFixed(2)} px from its line (root mean square > ${MAX_RMS}); not a straight waistband` };
   if (Math.abs(Math.atan(fit.m)) * (180 / Math.PI) > 45) return { kind: 'waistband too steep', why: `the garment's top edge runs ${(Math.atan(fit.m) * (180 / Math.PI)).toFixed(1)}° from level; a waistband is within 45°` };
-  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}) };
+  const off = notTheBand(f, fit, tops, top, colourAt);
+  if (off !== null) return off;
+  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}), ...(raised > 0 ? { raised } : {}) };
+}
+
+/**
+ * rig-c/pose#318: the band's top edge, the topmost garment boundary in each column. The three-row test misses garment
+ * above the row it finds when a strip of it is too thin to carry the colour three rows deep (through the window mean,
+ * a strip between two ink lines never does), so the tops step between a strip's top line and the cloth under its lower
+ * line. The garment's colours are the picture's own: the pixels of three rows in each column `DITHER_RADIUS + 1` below
+ * the row the scan found, clear of the edge's blend (an outline there would lend the colour above to the garment). The
+ * thing above has one colour, `a`: the median, over the columns read, of the rows from the scan's top down to
+ * `3 · (DITHER_RADIUS + 1)` above the topmost top — clear of the edge's blend, an outline and a window, and by area, so
+ * a line crossing it or a tilted band's outline in a few of its rows does not move it. From each top
+ * the column is followed up, pixel by pixel, while a pixel is no nearer to `a` than to the nearest garment pixel (cloth
+ * of any shade, and the ink lines on it, are); a climb that reaches the scan's top or a forearm does not see the top.
+ * The band's top is the topmost cloth pixel on the path (within `GARMENT_DIFF` of a garment pixel), from where the climb
+ * stopped down to the scan's three rows: an outline above it, or a line leaving the band upward, is ink, not garment;
+ * a thin strip's cloth between its two lines is garment. A clean edge climbs
+ * about the same rows in every column — the distance between two boundaries each found to a row — so only when the
+ * climbs differ by more than `CLIMB_SPREAD` rows (90th less 10th percentile) do the columns take their topmost garment
+ * row — and a column whose top was not seen is then not read, since its scan top is the lower level; otherwise the
+ * tops stay exactly as read. Nothing is done when the colour above is the garment's (its median
+ * within `GARMENT_DIFF`). Rewrites `tops` in place; returns how many moved.
+ */
+function toBandTop(f: Frame, tops: Pt[], g: RGB, top: number, colourAt: (x: number, y: number) => RGB | null): number {
+  if (tops.length === 0) return 0;
+  const lift = DITHER_RADIUS + 1;
+  const ya = Math.min(...tops.map((p) => p[1])) - 3 * lift;
+  if (ya < top) return 0;
+  // The garment's colours, at most `MAX_CLOTH`: a paletted garment's few, as they are; a painted one's many, as the mean
+  // colours of the `MAX_CLOTH` fullest cells of a `GARMENT_DIFF / 2` grid (first filled first among equals). The climb
+  // compares each pixel against them all, so their number is bounded whatever the span.
+  const exact = new Map<string, RGB>();
+  const cells = new Map<string, { s: RGB; n: number }>();
+  const step = GARMENT_DIFF / 2;
+  for (const [x, y0] of tops) {
+    for (let k = 0; k < 3; k++) {
+      const y = y0 + lift + k;
+      if (y < 0 || y >= f.h || f.masked(x, y)) continue;
+      const p = f.rgb(x, y);
+      if (exact.size <= MAX_CLOTH) exact.set(p.join(','), p);
+      const key = p.map((v) => Math.floor(v / step)).join(',');
+      const c = cells.get(key);
+      if (c === undefined) cells.set(key, { s: [p[0], p[1], p[2]], n: 1 });
+      else {
+        c.s[0] += p[0];
+        c.s[1] += p[1];
+        c.s[2] += p[2];
+        c.n++;
+      }
+    }
+  }
+  const cloth: RGB[] = exact.size <= MAX_CLOTH ? [...exact.values()] : [...cells.values()].sort((u, v) => v.n - u.n).slice(0, MAX_CLOTH).map((c) => [c.s[0] / c.n, c.s[1] / c.n, c.s[2] / c.n]);
+  if (cloth.length === 0) return 0;
+  // The colour above: the median of the region, channel by channel, read twice over it rather than held.
+  const a = regionMedian((visit) => {
+    for (const [x] of tops) {
+      for (let y = top; y <= ya; y++) {
+        const p = f.masked(x, y) ? null : colourAt(x, y);
+        if (p !== null) visit(p);
+      }
+    }
+  });
+  if (a === null) return 0;
+  if (diff(a, g) <= GARMENT_DIFF) return 0;
+  const nearest = (p: RGB, cs: RGB[]) => Math.min(...cs.map((q) => diff(p, q)));
+  const climbs = tops.map(([x, y0]) => {
+    let y = y0;
+    while (true) {
+      if (y - 1 < top || f.masked(x, y - 1)) return null;
+      const p = f.rgb(x, y - 1);
+      if (diff(p, a) < nearest(p, cloth)) break;
+      y--;
+    }
+    // The band's top: the topmost cloth pixel on the path, from where the climb stopped down to the scan's three rows.
+    for (let v = y; v <= y0 + 2; v++) if (v < f.h && nearest(f.rgb(x, v), cloth) <= GARMENT_DIFF) return y0 - v;
+    return null;
+  });
+  const ks = climbs.filter((k): k is number => k !== null).sort((p, q) => p - q);
+  if (ks.length === 0) return 0;
+  const rank = (q: number) => ks[Math.min(ks.length - 1, Math.max(0, Math.ceil(q * ks.length) - 1))]!;
+  if (rank(0.9) - rank(0.1) <= CLIMB_SPREAD) return 0;
+  let moved = 0;
+  const read = tops.flatMap((t, i): Pt[] => {
+    const k = climbs[i];
+    if (k === null || k === undefined) return [];
+    if (k !== 0) moved++;
+    return [[t[0], t[1] - k]];
+  });
+  tops.splice(0, tops.length, ...read);
+  return moved;
+}
+
+/**
+ * The median, channel by channel, of the colours a region yields (`median`'s value: the middle one, or the mean of the
+ * two middle ones), without holding them: a first pass counts each channel's values by whole step (0–255), which names
+ * the step the middle rank falls in; a second keeps only the values in that step, as distinct values and counts. Memory
+ * is the 256 counts and the distinct values of one step. Null for an empty region.
+ */
+function regionMedian(each: (visit: (p: RGB) => void) => void): RGB | null {
+  const bin = (v: number) => Math.max(0, Math.min(255, Math.floor(v)));
+  const hist = [new Float64Array(256), new Float64Array(256), new Float64Array(256)];
+  let n = 0;
+  each((p) => {
+    n++;
+    for (let k = 0; k < 3; k++) hist[k]![bin(p[k]!)]!++;
+  });
+  if (n === 0) return null;
+  const m = n >> 1;
+  const ranks = n % 2 === 1 ? [m] : [m - 1, m];
+  // For each channel and rank: the step it falls in and its rank within the step.
+  const want = [0, 1, 2].map((k) => ranks.map((r) => {
+    let below = 0;
+    for (let b = 0; b < 256; b++) {
+      const c = hist[k]![b]!;
+      if (r < below + c) return { b, r: r - below };
+      below += c;
+    }
+    throw new Error('unreachable: a rank beyond the count');
+  }));
+  const kept = [0, 1, 2].map(() => new Map<number, Map<number, number>>());
+  for (let k = 0; k < 3; k++) for (const w of want[k]!) kept[k]!.set(w.b, new Map());
+  each((p) => {
+    for (let k = 0; k < 3; k++) {
+      const vs = kept[k]!.get(bin(p[k]!));
+      if (vs !== undefined) vs.set(p[k]!, (vs.get(p[k]!) ?? 0) + 1);
+    }
+  });
+  const at = (k: number, w: { b: number; r: number }) => {
+    let below = 0;
+    for (const [v, c] of [...kept[k]!.get(w.b)!.entries()].sort((u, z) => u[0] - z[0])) {
+      if (w.r < below + c) return v;
+      below += c;
+    }
+    throw new Error('unreachable: a rank beyond the step');
+  };
+  return [0, 1, 2].map((k) => {
+    const vs = want[k]!.map((w) => at(k, w));
+    return vs.length === 1 ? vs[0]! : (vs[0]! + vs[1]!) / 2;
+  }) as RGB;
+}
+
+/**
+ * rig-c/pose#318: the edge the waistband reader fitted is declined when it cuts across the band instead of running
+ * along it — a fold's edge under a band the colour test passed over. Above the edge, in each column read, the colour
+ * `DITHER_RADIUS + 1` rows up (past the outline and the window's blend) is followed up while it holds within
+ * `GARMENT_DIFF`; where it stops is the band's top. When at least `MIN_COVER` of the columns read show such a band (not
+ * the ground, not open up to the scan's top), its top is fitted as a line. The two lines bound a strip of thickness
+ * `ta` and `tb` at the read columns' ends. A line inside a band of thickness t across a width W departs from the band's
+ * direction by at most atan(t / W); an edge whose strip more than doubles across the hips (|ta − tb| > min(ta, tb)), or
+ * crosses the band's top, cuts across the garment instead of running along the band.
+ *
+ * Null when the edge is the band's (or nothing above it is a band to hold it to).
+ */
+function notTheBand(f: Frame, fit: { m: number; q: number }, tops: Pt[], top: number, colourAt: (x: number, y: number) => RGB | null): Reading | null {
+  const edgeAt = (x: number) => fit.m * x + fit.q;
+  const bandTops: Pt[] = [];
+  for (const [x, y] of tops) {
+    const s = y - (DITHER_RADIUS + 1);
+    if (s < top || f.masked(x, s)) continue;
+    const c0 = colourAt(x, s);
+    if (c0 === null || diff(c0, f.bg) <= FIGURE_DIFF) continue;
+    let v = s;
+    let closed = false;
+    while (v - 1 >= top) {
+      if (f.masked(x, v - 1)) break;
+      const p = colourAt(x, v - 1);
+      if (p === null) break;
+      if (diff(p, c0) > GARMENT_DIFF) {
+        closed = true;
+        break;
+      }
+      v--;
+    }
+    if (closed) bandTops.push([x, v]);
+  }
+  if (bandTops.length < MIN_COVER * tops.length) return null;
+  const band = fitLine(bandTops);
+  if (band === null || band.rms > MAX_RMS) return null;
+  const xa = Math.min(...tops.map((p) => p[0]));
+  const xb = Math.max(...tops.map((p) => p[0]));
+  const ta = edgeAt(xa) - (band.m * xa + band.q);
+  const tb = edgeAt(xb) - (band.m * xb + band.q);
+  if (Math.abs(ta - tb) <= Math.min(ta, tb)) return null;
+  const deg = (m: number) => Math.atan(m) * (180 / Math.PI);
+  const allow = Math.max(0, Math.min(ta, tb));
+  return {
+    kind: 'edge leaves the band',
+    why: `the garment's edge fitted across the hips runs ${Math.abs(deg(fit.m) - deg(band.m)).toFixed(1)}° from the top of the band above it (${bandTops.length} of ${tops.length} columns; the band ${ta.toFixed(1)} px thick at x ${xa} and ${tb.toFixed(1)} px at x ${xb}); an edge inside a band ${allow.toFixed(1)} px thick at its thinnest departs from it by at most ${deg(allow / (xb - xa)).toFixed(1)}° across the ${xb - xa} px read, so this edge cuts across the garment (a fold), not along the band`,
+  };
 }
 
 /**
@@ -420,6 +620,8 @@ function viaNote(readings: Reading[]): string {
   const parts: string[] = [];
   if (mean > 0) parts.push(`${mean} through the ${2 * DITHER_RADIUS + 1}×${2 * DITHER_RADIUS + 1} window mean (the garment's colour does not hold pixel by pixel: a dithered or paletted picture)`);
   if (below > 0) parts.push(`${below} with the colour found below the hips (up to ${Math.max(...ok.map((r) => r.below ?? 0)).toFixed(1)} px; the hips on the band's edge)`);
+  const raised = ok.filter((r) => r.raised !== undefined);
+  if (raised.length > 0) parts.push(`${raised.length} with the band's top read above the colour's edge in some columns (up to ${Math.max(...raised.map((r) => r.raised ?? 0))} columns: a strip too thin to carry the colour, read as its top line)`);
   return parts.length === 0 ? '' : `; of the frames read, ${parts.join(', ')}`;
 }
 

package/src/pose.ts

@@ -74,7 +74,7 @@ export interface SegmentDepth {
   source: DepthSource;
 }
 export type FrameDepth = Partial<Record<DepthSegment, SegmentDepth>>;
-/** The gait `clean --depth` was told the clip is: it decides the sign of a foreshortened shin. */
+/** The gait `clean --depth` was told the clip is (rig-c/pose#336): the signs are the same for both; it decides the joint `--draw-order depth` orders the legs by. */
 export const DEPTH_GAITS = ['walk', 'run'] as const;
 export type DepthGait = (typeof DEPTH_GAITS)[number];
 /**

package/src/reduce.ts

@@ -80,6 +80,12 @@ export interface Reduced {
   rows: ReduceRow[];
   /** Each bone's world-aim error on every frame (reduced less dense, degrees), as the poser evaluates the reduced keys. */
   errors: Map<string, number[]>;
+  /**
+   * rig-c/pose#320: each trunk root whose smoothing (`smoothTrunk`, #116) was not kept because it left a bone it
+   * manages past that bone's own tolerance — the bone, its smoothed worst error and its tolerance (degrees); the
+   * fitted keys stand. Absent when every smoothing was kept.
+   */
+  unsmoothed?: Array<{ root: string; bone: string; worst: number; tolerance: number }>;
 }
 
 // ---------------------------------------------------------------------------
@@ -607,7 +613,9 @@ function solveLimbPreservingJitter(
  * above the sequence's own. Optimizing knot values and handle y-coordinates
  * jointly within the ±tolerance world-aim tube removes those C0 breaks while
  * keeping any limb chains hanging from the trunk within 0.04 of their landing
- * and jitter.
+ * and jitter. The tube's bounds are a penalty, not a constraint: a root whose
+ * smoothing leaves any bone it manages past that bone's own tolerance keeps its
+ * fitted keys instead, recorded in `out.unsmoothed` (rig-c/pose#320).
  */
 export function smoothTrunk(
   times: readonly number[],
@@ -737,6 +745,16 @@ export function smoothTrunk(
       }
     };
 
+    // rig-c/pose#320: the smoothing is kept only within every managed bone's own tolerance; past it, the fitted keys
+    // (within it by construction) stand, and the run says so.
+    const past = allManaged.map((b) => {
+      const e = b === root ? eRoot : eSub.get(b)!;
+      return { b, worst: Math.max(...e.map(Math.abs)) };
+    }).find((x) => x.worst > tolOf(x.b));
+    if (past !== undefined) {
+      (out.unsmoothed ??= []).push({ root, bone: past.b, worst: past.worst, tolerance: tolOf(past.b) });
+      continue;
+    }
     updateBone(root, smRoot.keys, eRoot);
     for (const b of [...headBones, ...arm0Bones, ...arm1Bones]) {
       updateBone(b, smSub.get(b)!.keys, eSub.get(b)!);

package/src/retarget.ts

@@ -80,8 +80,9 @@ import type { Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SetRuns, SlotTrack, Switch, SwitchOptions } from './switch.ts';
-import { clampArt, coveredChains, isRaised, measureArt, overflow, phaseGroupProblems, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
+import { clampArt, coveredChains, isRaised, keyAtFrame, measureArt, overflow, phaseGroupProblems, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, LegSegmentRatio, PathPose, Posing, Side, Stance } from './legs.ts';
+import { contactKeysOf, type ContactKeys } from './contacts.ts';
 import { figureScaleOf, freeAnkleShiftOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, shiftOver, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
 import type { BodyReading, FaceReading, YawSetSwitch } from './face.ts';
 import { readBody, readFace, readFaceAngles, selectYawSets } from './face.ts';
@@ -181,6 +182,12 @@ export interface RetargetOptions extends SwitchOptions {
    * the hip line on the frames it does not; absent, from the hip line.
    */
   pelvis?: { source: string; tilt: ReadonlyArray<number | null> };
+  /**
+   * rig-c/pose#303: the hand contact keys (`--contact-keys`), read against the
+   * sequence. Applied last over the supports read (`contactKeysOf`): on every
+   * frame they cover they decide the support. Absent, nothing changes.
+   */
+  contactKeys?: ContactKeys;
 }
 
 /**
@@ -1020,6 +1027,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       else if (plantOn) p.add('LEGS_MAP', `--plant-feet reads both hips and both ankles from the pose; the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`);
     }
   }
+  // rig-c/pose#303: the contact keys decide last, over every reading above; with no support read they have nothing to decide, so they are refused.
+  if (opts.contactKeys !== undefined) {
+    if (feet !== null) feet = contactKeysOf(feet, opts.contactKeys);
+    else p.add('CONTACT_KEYS', `--contact-keys sets which foot supports, and no support is read: ${legs !== null && 'problems' in legs ? legs.problems.join('; ') : `the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`}`);
+  }
   const heldPt = (name: string): Pt[] | null => {
     const known = series.get(name);
     if (known !== undefined) return known;
@@ -3048,7 +3060,6 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         if (!slotOrder.includes(sl)) slotOrder.push(sl);
       }
     }
-    const yawExactAt = new Map<string, Set<number>>();
     for (const s of activeYawSets) {
       const def = known.get(s.set);
       if (def === undefined) continue;
@@ -3058,10 +3069,6 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const row = sw.shown.get(sl)!;
         for (const [lo, hi] of s.spans) {
           for (let i = lo; i <= hi; i++) row[i] = v;
-          const exact = yawExactAt.get(sl) ?? new Set<number>();
-          exact.add(lo);
-          if (hi + 1 < n) exact.add(hi + 1);
-          yawExactAt.set(sl, exact);
         }
       }
     }
@@ -3071,11 +3078,12 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       if (row === undefined) continue;
       let prev = slots.get(sl)?.setup ?? null;
       const keys: AttachmentKey[] = [];
-      const exact = yawExactAt.get(sl);
       row.forEach((v, i) => {
         if (v === prev) return;
-        const t = i === 0 ? 0 : exact?.has(i) === true ? keyTimes[i]! : r6((keyTimes[i - 1]! + keyTimes[i]!) / 2);
-        keys.push({ t, v });
+        // Half a frame before the frame it shows on, as every discrete key pose writes (`keyAtFrame`, rig-c/pose#334):
+        // written on their frames' exact times, 7 of the 10 yaw swaps of the 24 fps head turn in test/retarget.test.ts
+        // showed a frame late under the render's clock.
+        keys.push({ t: keyAtFrame(keyTimes, i), v });
         prev = v;
       });
       if (keys.length > 0) rebuilt.push({ slot: sl, property: 'attachment', keys });

package/src/run.ts

@@ -10,8 +10,8 @@ import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, cleanSummaryLine, inferredSource } from './clean.ts';
-import { depthLine, layersOf, type FrameLayers } from './depth.ts';
-import { drawOrderFromDepth, drawOrderKeys, drawOrderLines, type DrawOrderReading } from './draworder.ts';
+import { depthLine, depthRecleanText, forwardShinFrames, layersOf, type FrameLayers } from './depth.ts';
+import { drawGapLines, drawOrderFromDepth, drawOrderKeys, drawOrderLines, type DrawOrderReading } from './draworder.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
@@ -27,6 +27,7 @@ import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
 import { PROVENANCE_FILE, provenanceText } from './provenance.ts';
 import { madeLine, planOutDirs } from './outdir.ts';
 import { bodyLine, faceLine } from './face.ts';
+import { contactKeysLines, readContactKeys } from './contacts.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -81,6 +82,8 @@ export interface RetargetArgs extends RetargetOptions {
   output?: 'default' | 'verbose' | 'summary';
   /** `--draw-order depth` (rig-c/pose#304): key the animation's draw order from the sequence's depth. Absent: no draw-order key, the output as before. */
   drawOrder?: 'depth';
+  /** `--contact-keys` (rig-c/pose#303): the hand contact keys' file, `rig-pose-contact-keys/1`. Absent: the support as read, the output as before. */
+  contactKeysFile?: string;
 }
 
 export interface RunResult {
@@ -104,7 +107,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     throw new Refusal(problems);
   };
   const args = new Problems();
-  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose], ['--merge', a.merge]] as const) {
+  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose], ['--merge', a.merge], ['--contact-keys', a.contactKeysFile]] as const) {
     if (path !== undefined && !existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
   }
   // rig-c/pose#239: the report is written unless asked elsewhere — beside the motion, as <out>.report.json.
@@ -134,13 +137,22 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const mapSnapshot = readReportInput(a.map), poseSnapshot = readReportInput(a.pose);
   const map = readMap(mapSnapshot.bytes.toString('utf8'), a.map);
   // #283: each chain --reduce names must be the map's; a bone takes its chain's tolerance (the tighter, if two chains name it).
-  const reduceOf = a.reduce === undefined ? null : reduceTolerances(map, a.reduce, a.reduceChains, a.map);
+  let reduceOf = a.reduce === undefined ? null : reduceTolerances(map, a.reduce, a.reduceChains, a.map);
   const poseText = poseSnapshot.bytes.toString('utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
   if (seq.cleaned === undefined) refuse([{ code: 'POSE_NOT_CLEANED', text: notCleaned(a.pose, a.coco) }]);
   // #304: the draw order is read off the sequence's depth; asked for on a sequence without it, refused by name.
   if (a.drawOrder === 'depth' && !seq.frames.some((x) => x.depth !== undefined)) refuse([{ code: 'DRAWORDER_NO_DEPTH', text: `--draw-order depth keys the draw order from the sequence's depth, and ${a.pose} carries none (rig-pose-sequence/${seq.cleaned!.params.depth === undefined ? '1 or 1.1, no "depth" on any frame' : '1.2 with no frame naming a segment'}); clean it with --depth walk|run, or retarget without --draw-order` }]);
   const frames = personTrack(seq, a.person, a.pose);
+  // #336: a derived depth whose shins lean the way the trunk faces was cleaned with the table before #336 (a walk's lifted
+  // foot forward); the draw order now reads a walk at the ankle, and would draw that foot in front. Refused by name.
+  if (a.drawOrder === 'depth') {
+    const old = forwardShinFrames(frames, seq.frames);
+    if (old.length > 0) refuse([{ code: 'DEPTH_RECLEAN', text: depthRecleanText(a.pose, seq.cleaned!.params.depth?.gait ?? null, old) }]);
+  }
+  // rig-c/pose#303: the contact keys, read against the sequence's frames before any gate runs.
+  const contactKeysSnapshot = a.contactKeysFile === undefined ? null : readFileSync(a.contactKeysFile);
+  const contactKeys = contactKeysSnapshot === null ? null : readContactKeys(contactKeysSnapshot.toString('utf8'), a.contactKeysFile!, seq.frames.length);
   const times = seq.frames.map((f) => f.t);
 
   const scratch = mkdtempSync(join(tmpdir(), 'rig-pose-'));
@@ -156,7 +168,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const slots = slotsOf(doc0);
     resolveMap(map, rest, a.map, slots, input.sets);
 
-    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}), ...(seq.pelvisSource !== undefined ? { pelvis: { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } } : {}) }, slots, input.sets);
+    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}), ...(seq.pelvisSource !== undefined ? { pelvis: { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } } : {}), ...(contactKeys !== null ? { contactKeys } : {}) }, slots, input.sets);
     if (fragment.length > 0 && ((r.face?.sets?.length ?? 0) > 0 || (r.body?.sets?.length ?? 0) > 0)) {
       const known = knownSetsOf(map, input.sets);
       for (const s of [...(r.face?.sets ?? []), ...(r.body?.sets ?? [])]) {
@@ -227,9 +239,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     // rig-c/pose#281: the limbs' front-to-back order from the sequence's depth, only when it carries depth.
     const layers: FrameLayers[] | null = seq.frames.some((x) => x.depth !== undefined) ? frames.map((j, i) => layersOf(j, seq.frames[i]!.depth ?? {})) : null;
     if (layers !== null) say(`  ${depthLine(layers, seq.frames, seq.cleaned!.params.depth?.gait ?? null)}`);
-    // rig-c/pose#304: with --draw-order depth, the legs' draw order keyed from those layers.
-    const drawOrder: DrawOrderReading | null = a.drawOrder === 'depth' && layers !== null ? drawOrderFromDepth(layers, frames, seq.frames.map((x) => x.depth), r.times, map, rest, doc0.slots, input.sets, seq.cleaned!.params.loop) : null;
-    if (drawOrder !== null) for (const l of drawOrderLines(drawOrder)) say(`  ${l}`);
+    // rig-c/pose#304: with --draw-order depth, the legs' draw order keyed from the depth (#336: at the joint the recorded gait names).
+    const drawOrder: DrawOrderReading | null = a.drawOrder === 'depth' && layers !== null ? drawOrderFromDepth(layers, frames, seq.frames.map((x) => x.depth), r.times, map, rest, doc0.slots, input.sets, seq.cleaned!.params.loop, seq.cleaned!.params.depth?.gait ?? null) : null;
+    if (drawOrder !== null) for (const l of [...drawOrderLines(drawOrder), ...drawGapLines(drawOrder)]) say(`  ${l}`);
     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;
@@ -237,7 +249,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       say(`  FEET   ${r.planted ? 'planted' : 'read, not planted (no --plant-feet)'}: leg length (median hip → ankle) r ${f.legLength.r.toFixed(1)}px, l ${f.legLength.l.toFixed(1)}px; ${f.supports.length} support span(s), ${f.changes.filter((c) => c.from !== null).length} change(s) of support, ${f.jumps.length} jump(s), ${f.steps.length} step(s)`);
       for (const sg of r.segments) say(`  FEET   ${segmentLine(sg)}`);
       say(`  FEET   supports: ${f.supports.map((x) => `${x.side} ${span(x.frames)}`).join(', ') || 'none'}`);
-      if (f.signal !== undefined) for (const l of signalLines(f.signal, f.supports)) say(`  FEET   ${l}`);
+      // rig-c/pose#303: with contact keys, their stride lines stand in for #280's (the keys decide the frames they cover).
+      const signal = f.signal === undefined ? [] : signalLines(f.signal, f.supports);
+      for (const l of f.contactKeys === undefined ? signal : [...signal.filter((x) => !x.startsWith('stride ')), ...contactKeysLines(f)]) say(`  FEET   ${l}`);
       say(`  FEET   jumps (both ankles and mid_hip > 0.05 leg lengths above their rolling floor, ≥ 2 frames): ${f.jumps.map(span).join(', ') || 'none'}`);
       if (f.lowered !== undefined) say(`  FEET   ${loweredLine(f.lowered)}`);
       if (f.tracked !== undefined) say(`  FEET   tracked (the lower foot supports on the floor, following its scaled ankle track until still, rig-c/pose#119): ${f.tracked.map((x) => `${x.side} ${span(x.frames)}`).join(', ')}`);
@@ -256,14 +270,23 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (r.face !== null) say(`  FACE   ${faceLine(r.face)}`);
     if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
+    // #320: a mapped bone above a planted or aimed chain --reduce names is held to that chain's tolerance when its own is looser.
+    const held = reduceOf === null || a.reduceChains === undefined ? [] : holdParents(map, rest, new Set(r.targets.keys()), a.reduceChains, reduceOf, r.ankles === null ? [] : [r.ankles.bones.r, r.ankles.bones.l]);
+    if (held.length > 0) {
+      const first = reduceOf!;
+      reduceOf = (bone) => held.find((h) => h.bone === bone)?.to ?? first(bone);
+      for (const h of held) say(`  REDUCE ${heldLine(h)}`);
+    }
     // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
     const reduced = a.reduce === undefined ? null : a.reduceChains === undefined ? reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true) : reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true, reduceOf!);
     if (reduced !== null) {
       for (const row of reduced.rows) {
         const [who, track, what, unit] = row.kind === 'angle' ? ['bone', 'rotate', 'aim', '°'] : row.kind === 'origin' ? ['hip', 'translate', 'origin', ' units'] : ['bone', 'scalex', 'scale', ' of its setup length'];
-        const own = row.kind === 'angle' && reduceOf!(row.bone) !== a.reduce ? ` — within its chain's ${reduceOf!(row.bone)}°` : '';
+        const hold = held.find((h) => h.bone === row.bone && row.kind === 'angle');
+        const own = row.kind === 'angle' && reduceOf!(row.bone) !== a.reduce ? (hold === undefined ? ` — within its chain's ${reduceOf!(row.bone)}°` : ` — held to ${hold.to}° for ${hold.for.map((c) => `chain "${c.chain}"`).join(', ')} below it`) : '';
         say(`  REDUCE ${who} "${row.bone}" ${track}: ${row.before} → ${row.after} key(s); worst ${what} error ${row.worst.toPrecision(3)}${unit} at frame ${row.frame} (t=${r.times[row.frame]!.toFixed(3)}s)${own}`);
       }
+      for (const u of reduced.unsmoothed ?? []) say(`  REDUCE ${unsmoothedLine(u)}`);
       const sum = (kind: ReduceRow['kind'], k: 'before' | 'after') => reduced.rows.filter((x) => x.kind === kind).reduce((t, x) => t + x[k], 0);
       const scales = reduced.rows.some((x) => x.kind === 'scale') ? `; scalex keys ${sum('scale', 'before')} → ${sum('scale', 'after')} within ${SCALE_REDUCE} of the setup length` : '';
       say(`  REDUCE rotate keys ${sum('angle', 'before')} → ${sum('angle', 'after')} (${(sum('angle', 'before') / sum('angle', 'after')).toFixed(2)}×) within ${a.reduce}°${chainsText(a.reduceChains)}${scales}${a.reduceHip === undefined ? '; the hip stays dense (no --reduce-hip)' : ''}`);
@@ -414,7 +437,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
 
     assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
     // Every retarget option as resolved: the report's `options`, and with the name the build record's `flags` (#270).
-    const options = { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', ...(a.reduceChains === undefined ? {} : { reduceChains: a.reduceChains }), reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}), ...(a.drawOrder !== undefined ? { drawOrder: a.drawOrder } : {}) };
+    const options = { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', ...(a.reduceChains === undefined ? {} : { reduceChains: a.reduceChains }), reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}), ...(a.drawOrder !== undefined ? { drawOrder: a.drawOrder } : {}), ...(a.contactKeysFile !== undefined ? { contactKeys: a.contactKeysFile } : {}) };
     const reportText = writeReport({
         spec: 'rig-pose-report/1',
         rigc,
@@ -476,15 +499,18 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         pelvis: r.pelvis,
         // Only when the sequence carries depth (#281): a sequence without it writes the report it always has.
         ...(layers !== null ? { layers: layers.map((l, frame) => ({ frame, order: l.order, depth: l.depth })) } : {}),
-        // Only with --draw-order depth (#304).
-        ...(drawOrder !== null ? { drawOrder: { source: 'depth', pairs: drawOrder.pairs, keys: drawOrder.keys, spans: drawOrder.spans } } : {}),
+        // Only with --draw-order depth (#304). A key's `t` here is its frame's time, the report's clock (#214); the
+        // motion's key is written half a frame before it (#325).
+        ...(drawOrder !== null ? { drawOrder: { source: 'depth', pairs: drawOrder.pairs, keys: drawOrder.keys.map((k) => ({ ...k, t: r.times[k.frame]! })), spans: drawOrder.spans, gaps: drawOrder.gaps ?? [] } } : {}),
+        // Only with --contact-keys (#303).
+        ...(r.feet?.contactKeys !== undefined && contactKeysSnapshot !== null ? { contactKeys: { path: a.contactKeysFile, sha256: createHash('sha256').update(contactKeysSnapshot).digest('hex'), keys: r.feet.contactKeys.keys.length, from: r.feet.contactKeys.from, changed: r.feet.contactKeys.changed, kept: r.feet.contactKeys.kept, unreached: r.feet.contactKeys.unreached } } : {}),
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, ...(r.stance.range === undefined ? {} : { range: r.stance.range }), runs: r.stance.runs, over: r.stance.over },
         feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, straight: r.legStraight, rigLeg: r.rigLeg, segments: r.segments, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, ...(r.feet.lowered === undefined ? {} : { lowered: r.feet.lowered }), ...(r.feet.tracked === undefined ? {} : { tracked: r.feet.tracked }), floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, ...(r.blendHold.range === undefined ? {} : { range: r.blendHold.range }), runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading, closure: r.closure },
         shear,
         idleDropped: idle === null ? null : idle.dropped,
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
-        reduce: reduced === null ? null : { tolerance: a.reduce, ...(a.reduceChains === undefined ? {} : { chains: a.reduceChains }), hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
+        reduce: reduced === null ? null : { tolerance: a.reduce, ...(a.reduceChains === undefined ? {} : { chains: a.reduceChains }), ...(held.length === 0 ? {} : { held }), ...(reduced.unsmoothed === undefined ? {} : { unsmoothed: reduced.unsmoothed }), hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
       }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : seamRead.frames === null ? null : reportRenderDomain(seamRead.frames, a.name), {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
@@ -1375,6 +1401,80 @@ export function reduceTolerances(map: JointMap, tolerance: number, chains: Recor
   return (bone) => by.get(bone) ?? tolerance;
 }
 
+/** rig-c/pose#320: a mapped bone held to the tolerance of a planted or aimed chain below it. */
+export interface ReduceHeld {
+  /** The held bone, and the map chain it is a bone of (null for a mapped bone no chain lists). */
+  bone: string;
+  chain: string | null;
+  /** Its tolerance as --reduce gave it (the run's, or its own chain's), degrees. */
+  from: number;
+  /** The tolerance it is held to: the tightest planted or aimed chain --reduce names below it, degrees. */
+  to: number;
+  /**
+   * Each such chain below it reduced within `to`, in the map's order: its name, what holds it (`ankle`: it carries
+   * a planted ankle's landing; `aim`: the map aims it), its first bone, and the lever — that bone's origin's setup
+   * distance from the held bone's origin, rig units.
+   */
+  for: Array<{ chain: string; by: 'ankle' | 'aim'; bone: string; lever: number }>;
+}
+
+/**
+ * rig-c/pose#320: every mapped bone above a planted or aimed chain `chains`
+ * names, whose own tolerance (`tolOf`) is looser than that chain's, held to it
+ * — to the tightest such chain when several hang below it. A chain is planted
+ * when it carries an ankle the landing check holds (`ankles`), aimed when the
+ * map gives it an `aim` other than "x".
+ *
+ * The lever. A turn error θ on a bone turns everything under it rigidly: a
+ * chain below has its first bone moved by θ·L (L = `lever`) and its aim turned
+ * by θ. The reduction refits the chain against the turn (`target = dense −
+ * e_above`), so the aim is the chain's own error, but not the move: the ankle
+ * allowance (`footReduce`) sums every segment from the legs' top down — the
+ * held bone's lever among them — times the leg's own degrees. θ·L ≤ θ_leg·L is
+ * θ ≤ θ_leg whatever L is. An aimed chain is refitted, and on the trunk
+ * smoothed (#116), against its parent's error as it stands: held to the
+ * chain's degrees, that error never asks the chain to absorb more than its own
+ * tolerance. A bent chain (an arm, a leg with no ankle check) has only its aim
+ * checked, which the refit holds, so it holds nothing above it. Only a
+ * per-chain entry can be tighter than a bone above it: with none, nothing is held.
+ */
+export function holdParents(map: JointMap, rest: Rest, mapped: ReadonlySet<string>, chains: Record<string, number>, tolOf: (bone: string) => number, ankles: readonly string[]): ReduceHeld[] {
+  const held: ReduceHeld[] = [];
+  for (const c of map.chains) {
+    const t = Object.hasOwn(chains, c.name) ? chains[c.name] : undefined;
+    const top = c.bones[0];
+    const by = c.bones.some((b) => ankles.includes(b)) ? ('ankle' as const) : c.aim.some((x) => x !== 'x') ? ('aim' as const) : null;
+    if (t === undefined || top === undefined || by === null || !rest.has(top)) continue;
+    const at = rest.get(top)!;
+    for (let p = at.parent; p !== null; p = rest.get(p)?.parent ?? null) {
+      if (!mapped.has(p) || c.bones.includes(p) || !(tolOf(p) > t)) continue;
+      const was = held.findIndex((h) => h.bone === p);
+      if (was >= 0 && held[was]!.to < t) continue;
+      const x = rest.get(p)!;
+      const child = { chain: c.name, by, bone: top, lever: Number(Math.hypot(at.worldX - x.worldX, at.worldY - x.worldY).toPrecision(6)) };
+      if (was >= 0 && held[was]!.to === t) held[was]!.for.push(child);
+      else if (was >= 0) held[was] = { ...held[was]!, to: t, for: [child] };
+      else held.push({ bone: p, chain: map.chains.find((m) => m.bones.includes(p))?.name ?? null, from: tolOf(p), to: t, for: [child] });
+    }
+  }
+  return held;
+}
+
+/** rig-c/pose#320: the REDUCE line naming a held bone, the chains it was held for, and why. */
+export function heldLine(h: ReduceHeld): string {
+  const below = h.for.map((c) => `chain "${c.chain}" (${c.by === 'ankle' ? 'a planted ankle' : 'aimed'}; L = ${c.lever} units to bone "${c.bone}")`).join(', ');
+  const why = [
+    ...(h.for.some((c) => c.by === 'ankle') ? ['the ankle allowance counts L at the leg\'s own degrees'] : []),
+    ...(h.for.some((c) => c.by === 'aim') ? ['an aimed chain refits against its parent\'s error within its own'] : []),
+  ].join(' and ');
+  return `held: bone "${h.bone}"${h.chain === null ? '' : ` (chain "${h.chain}")`} reduced within ${h.to}°, not ${h.from}° — for ${below} below it, reduced within ${h.to}°: a turn error θ on bone "${h.bone}" moves a chain below it by θ·L and turns it by θ, and ${why}, so θ ≤ ${h.to}°`;
+}
+
+/** rig-c/pose#320: the REDUCE line for a trunk smoothing (#116) not kept. */
+export function unsmoothedLine(u: { root: string; bone: string; worst: number; tolerance: number }): string {
+  return `smoothing (rig-c/pose#116) from bone "${u.root}" down not kept: it left bone "${u.bone}" at ${u.worst.toPrecision(3)}°, past its ${u.tolerance}°; the fitted keys stand, each within its tolerance`;
+}
+
 /** rig-c/pose#283: the per-chain tolerances as the run and REDUCE lines print them; empty without. */
 export function chainsText(chains: Record<string, number> | undefined): string {
   if (chains === undefined) return '';