@rig-c/pose 0.38.0 → 0.40.0

package/src/run.ts

@@ -10,19 +10,22 @@ 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 { 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';
-import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, pelvisLine, rangeLine, reachCostLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
+import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, pelvisLine, rangeLine, reachCostLine, reachOriginLine, reachOriginWarn, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, seamRender, slotsOf } from './rigc.ts';
 import { partsPath, projectSeams, readSeamDoc, readSeamPairs, seamLines, type SeamPair } from './seams.ts';
-import { artRangeLine, chainsMoving, phaseLines, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
+import { artRangeLine, chainsMoving, phaseLines, raisedLine, RAISED_WITHIN, reachLine, switchLine, switchMinLines, uncoveredFolds } from './switch.ts';
 import { jitterLine, landed, type FeetReading, type JitterRow, type Landing, measureFeet, measureJitter, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
-import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
+import { FRONTAL_DISAGREE, legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, smoothTrunk, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
-import type { BlendHold, Closure, Floor, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import type { BlendHold, Closure, Feet, Floor, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun, SupportSignal } from './legs.ts';
 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';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -62,6 +65,8 @@ export interface RetargetArgs extends RetargetOptions {
   merge?: string;
   /** Thin the mapped bones' rotate keys within this many degrees (#32). */
   reduce?: number;
+  /** With reduce: a map chain's own tolerance in degrees, by chain name, in place of `reduce` on its bones (#283). */
+  reduceChains?: Record<string, number>;
   /** With reduce: thin the hip's translate keys within this many rig units. */
   reduceHip?: number;
   /** With reduce and plantFeet: keep each support span's frames on the supporting leg at its dense keys (#251). */
@@ -74,6 +79,8 @@ export interface RetargetArgs extends RetargetOptions {
    * same in all three and the gate is the same gate.
    */
   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';
 }
 
 export interface RunResult {
@@ -104,15 +111,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const report = a.report ?? defaultReportPath(a.out);
   // A file this run writes goes into a directory the user named: one that is not there yet is made
   // after the run is green (one line says so), as --build and --render make theirs; a file in the way is refused.
-  const makeDirs = new Map<string, string[]>();
-  for (const [flag, path] of [['--out', a.out], ['--report', report], ['--camera', a.camera]] as const) {
-    if (path === undefined) continue;
-    const dir = dirname(path);
-    let up = dir;
-    while (!existsSync(up) && dirname(up) !== up) up = dirname(up);
-    if (!statSync(up).isDirectory()) args.add('ARG_PATH', up === dir ? `${flag} ${path} — ${dir} is not a directory` : `${flag} ${path} — ${up} is a file, so directory ${dir} cannot be made under it`);
-    else if (up !== dir) makeDirs.set(dir, [...(makeDirs.get(dir) ?? []), `${flag} ${path}`]);
-  }
+  const makeDirs = planOutDirs([['--out', a.out], ['--report', report], ['--camera', a.camera]], args);
+  // #284: --build and --render make their own directories (rigc, the copy); a file in the way is refused here, up front.
+  planOutDirs([['--build', a.build], ['--render', a.render]], args);
   if (a.reference !== undefined && a.build === undefined) args.add('ARG_REFERENCE', `--reference ${a.reference} needs --build: the record it goes in is written beside the build (${PROVENANCE_FILE})`);
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
@@ -132,9 +133,13 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
   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);
   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);
   const times = seq.frames.map((f) => f.t);
 
@@ -168,7 +173,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         }
       }
     }
-    tell(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}${a.reduceKeepPlanted === true ? ', planted legs kept dense' : ''}` : ''}`);
+    tell(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${chainsText(a.reduceChains)}${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}${a.reduceKeepPlanted === true ? ', planted legs kept dense' : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     // #250: the gate was green without it, so nothing else would say the rig's own animations are not in --out.
     const unread = unreadMotionLine(a.rig, input.motion);
@@ -195,6 +200,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (map.alternates.length > 0) {
       if (r.switches.length === 0) say(`  SWITCH none — no set within ${a.switchTolerance}° of the pose for ${a.switchMin}s`);
       for (const s of r.switches) say(`  SWITCH ${switchLine(s, r.times)}`);
+      // #279: only for a set the minimum span held back, so a run where nothing was suppressed prints what it always has.
+      for (const l of switchMinLines(r.switchRuns, a.switchMin)) say(`  SWITCH-MIN ${l}`);
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
       for (const l of phaseLines(map, r.switches)) say(`  PHASE  ${l}`);
     }
@@ -206,10 +213,23 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const e of r.byHip) say(`  BY-HIP ${raisedLine(e, r.times)}`);
     for (const e of r.byHip) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.reach) say(`  REACH  ${reachCostLine(e, r.times)}`);
+    // rig-c/pose#282: each reach chain's origin against its source joint; a map without one prints none.
+    for (const e of r.reachOrigin) {
+      say(`  REACH-ORIGIN ${reachOriginLine(e, r.times)}`);
+      if (e.warn) say(`  WARN   ${reachOriginWarn(e)}`);
+    }
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
-    for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times, r.feet?.legLength ?? null, r.rigLeg)}`);
+    // #287: a range that clamps no frame says so once, on the last segment's line (the line count stays one per segment).
+    const noClamp = legScaleNoClamp(r.legScale);
+    r.legScale.forEach((l, k) => say(`  LEG-SCALE ${legScaleLine(l, r.times, r.feet?.legLength ?? null, r.rigLeg)}${k === r.legScale.length - 1 && noClamp !== null ? `; ${noClamp}` : ''}`));
     for (const l of r.legScale) for (const s of l.support ?? []) say(`  LEG-SCALE ${supportScaleLine(l, s, r.times)}`);
     if (r.pelvis !== null) say(`  ${pelvisLine(r.pelvis, seq.frames.length)}`);
+    // 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}`);
     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;
@@ -217,6 +237,7 @@ 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}`);
       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(', ')}`);
@@ -236,15 +257,16 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
     // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
-    const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true);
+    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'];
-        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)`);
+        const own = row.kind === 'angle' && reduceOf!(row.bone) !== a.reduce ? ` — within its chain's ${reduceOf!(row.bone)}°` : '';
+        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}`);
       }
       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}°${scales}${a.reduceHip === undefined ? '; the hip stays dense (no --reduce-hip)' : ''}`);
+      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)' : ''}`);
     }
 
     // The idle against the new animation (#43 item 2): what it drops, and with --carry-idle, looped back in.
@@ -293,7 +315,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const tr of fragment) say(`  MERGE  ${a.merge}: ${trackLabel(tr, groups)}, ${tr.keys.length} key(s) at t=${tr.keys[0]!.t}${tr.keys.length > 1 ? `–${tr.keys[tr.keys.length - 1]!.t}` : ''}s`);
     }
     const added = [...carried, ...fragment];
-    const animation = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    const tracked = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    // #304: rig-c's one draw-order timeline sits on the animation beside its tracks; written only when keyed.
+    const animation = drawOrder === null || drawOrder.keys.length === 0 ? tracked : { ...tracked, drawOrder: drawOrderKeys(drawOrder) };
     const motion = { ...base, animations: { ...animations, [a.name]: animation } };
     const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile, a.images);
     if (!g1.green) {
@@ -312,11 +336,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const support = a.reduce !== undefined && a.reduceKeepPlanted === true && r.feet !== null ? supportFrames(r.feet.supports) : undefined;
     const landings = measureLanding(doc, a.name, map, r, posed, support).map((l) => {
       if (a.reduce === undefined) return l;
-      if (l.kind === 'angle') return { ...l, tolerance: l.tolerance + a.reduce };
+      // #283: a chain's own tolerance is added as the run's is; the sum is rounded only under a per-chain --reduce.
+      if (l.kind === 'angle') return { ...l, tolerance: a.reduceChains === undefined ? l.tolerance + a.reduce : Number((l.tolerance + reduceOf!(l.bone)).toPrecision(12)) };
       if (l.kind === 'origin' && a.reduceHip !== undefined) return { ...l, tolerance: l.tolerance + a.reduceHip };
       if (l.kind !== 'foot') return l;
       const ankle = l.bone.replace(/:tip$/, '');
-      const by = footReduce(rest, r, ankle, a.reduce, a.reduceHip);
+      const by = footReduce(rest, r, ankle, a.reduce, a.reduceHip, a.reduceChains === undefined ? undefined : reduceOf!);
       // #251: on its support frames every mapped bone from the hip down was kept at its target, so only the hip's tolerance moves it.
       const hip = a.reduceHip ?? 0;
       if (!drift.some((d) => d.bone === l.bone)) {
@@ -324,7 +349,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         const side = lb?.r.ankle === ankle ? 'r' : lb?.l.ankle === ankle ? 'l' : null;
         const legs = (u: number) => (side === null || r.rigLeg === null ? null : u / r.rigLeg[side]);
         const held = support === undefined ? {} : { support: side === null || support[side].size === 0 ? null : { reduce: hip, units: l.tolerance + hip, legLengths: legs(l.tolerance + hip) } };
-        drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: legs(l.tolerance + by), ...held });
+        // #283: under a per-chain --reduce, the tolerance its leg was reduced within.
+        const leg = a.reduceChains === undefined ? {} : { legTolerance: legTolerance(rest, r, ankle, reduceOf!) };
+        drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: legs(l.tolerance + by), ...held, ...leg });
       }
       return { ...l, tolerance: l.tolerance + (l.on === 'support' ? hip : by) };
     });
@@ -355,7 +382,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
     const hips = seq.cleaned?.params.hipsInferred;
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned), hips?.by === 'measured' ? hips : null);
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned), hips?.by === 'measured' ? hips : null, seq.pelvisSource !== undefined ? { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } : null);
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
@@ -387,7 +414,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', reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}) };
+    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 reportText = writeReport({
         spec: 'rig-pose-report/1',
         rigc,
@@ -412,9 +439,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         seams: seamRead.seams,
         seamPairs: seamRead.seamPairs,
         switches: r.switches,
+        switchRuns: r.switchRuns,
         uncovered,
         turns: r.turns,
         reach: r.reach,
+        // Only when the map has a reach chain (#282): a map without one writes the report it always has.
+        ...(r.reachOrigin.length > 0 ? { reachOrigin: r.reachOrigin } : {}),
         range: r.range,
         artRange: r.artRange,
         raised: r.raised,
@@ -444,13 +474,17 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         legScale: r.legScale.map(({ scale: _scale, asked: _asked, picture: _picture, ...rest }) => rest),
         pivot: r.pivot,
         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 } } : {}),
         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, hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
+        reduce: reduced === null ? null : { tolerance: a.reduce, ...(a.reduceChains === undefined ? {} : { chains: a.reduceChains }), 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).
@@ -622,7 +656,7 @@ const spanText = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}
  * aim and length it lands on (`reduceUnderScale`). With none, this is #32's
  * reduction, unchanged.
  */
-function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined, keepPlanted: boolean): Reduced {
+function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined, keepPlanted: boolean, tolOf: (bone: string) => number = () => tolerance): Reduced {
   const n = r.times.length;
   const keep = new Map<string, Set<number>>();
   const add = (bone: string, ...frames: number[]) => {
@@ -661,7 +695,9 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
     return false;
   };
   const dense = new Map([...rotate].map(([b, tr]) => [b, tr.keys.map((k) => k.v[0]!)]));
-  const bones: ReduceBone[] = [...rotate.values()].filter((tr) => !under(tr.bone)).map((tr) => ({ bone: tr.bone, above: above(tr.bone), dense: dense.get(tr.bone)!, keep: keep.get(tr.bone) ?? new Set<number>() }));
+  // #283: a bone whose chain --reduce names carries its own tolerance; every other takes the run's.
+  const own = (b: string): { tolerance?: number } => (tolOf(b) === tolerance ? {} : { tolerance: tolOf(b) });
+  const bones: ReduceBone[] = [...rotate.values()].filter((tr) => !under(tr.bone)).map((tr) => ({ bone: tr.bone, above: above(tr.bone), dense: dense.get(tr.bone)!, keep: keep.get(tr.bone) ?? new Set<number>(), ...own(tr.bone) }));
   const hipTrack = r.origin === null || hipTolerance === undefined ? undefined : r.animation.tracks.find((tr): tr is MotionTrack => 'bone' in tr && tr.property === 'translate' && tr.bone === r.origin!.bone && tr.keys.every((k) => k.ease === undefined));
   const parent = hipTrack === undefined ? null : rest.get(hipTrack.bone)!.parent;
   const pm = parent === null ? null : rest.get(parent)!;
@@ -754,6 +790,7 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
       asked: r.scales.get(b) ?? new Array<number>(n).fill(1),
       dense: dense.get(b)!,
       keep: keepOf(b),
+      ...own(b),
     };
   });
   const red = reduceUnderScale(r.times, given, tolerance, SCALE_REDUCE);
@@ -778,7 +815,7 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
  * world aim is within the angle tolerance of its dense one, top-down, so the
  * segments' errors are each bounded and the sum bounds the ankle's.
  */
-export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolerance: number, hipTolerance: number | undefined): number {
+export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolerance: number, hipTolerance: number | undefined, tolOf?: (bone: string) => number): number {
   const top = r.origin?.bone ?? null;
   let sMax = 1;
   for (const s of r.scales.values()) for (const v of s) sMax = Math.max(sMax, v);
@@ -790,7 +827,8 @@ export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: st
     if (p === null) break;
     lever += Math.hypot(x.worldX - p.worldX, x.worldY - p.worldY);
   }
-  return (hipTolerance ?? 0) + lever * sMax * ((tolerance * Math.PI) / 180 + SCALE_REDUCE);
+  const deg = tolOf === undefined ? tolerance : legTolerance(rest, r, ankle, tolOf);
+  return (hipTolerance ?? 0) + lever * sMax * ((deg * Math.PI) / 180 + SCALE_REDUCE);
 }
 
 function spans(ts: number[], step: number): string {
@@ -916,6 +954,48 @@ function loweredLine(lowered: readonly Lowered[]): string {
   return `${head}: ${frames} frame(s) read differently from before — ${lowered.map((x) => `frames ${span(x.frames)} ${side(x.was)} → ${side(x.now)}${x.cause === undefined ? '' : ` (${CAUSE[x.cause]})`}`).join(', ')}`;
 }
 
+/**
+ * The support-signal lines (rig-c/pose#280). On a clip read as frontal: two
+ * lines — how often the ankle's vertical speed contradicts ankle height against
+ * `FRONTAL_DISAGREE`, and where the stride shows (in depth) — then one line per
+ * support span (a stride) naming the signal that decided its frames and what
+ * ankle height alone would have read. On any other clip ankle height decided as
+ * before and nothing is printed: the output of a clip the second signal does not
+ * decide stays as it was, in every mode (`Feet.signal` still carries the figures).
+ */
+export function signalLines(sig: SupportSignal, supports: Feet['supports']): string[] {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+  const n = Math.round(FRONTAL_DISAGREE * 100);
+  const pct = sig.read === 0 ? 0 : (100 * sig.contradict.length) / sig.read;
+  if (!sig.frontal) return [];
+  const ranges = `x · y against the hips: r ${sig.range.r.x.toFixed(1)} · ${sig.range.r.y.toFixed(1)} px, l ${sig.range.l.x.toFixed(1)} · ${sig.range.l.y.toFixed(1)} px`;
+  const contra = `${sig.contradict.length} of ${sig.read} frame(s) (${pct.toFixed(1)} %`;
+  const out = [
+    `support: ankle vertical speed (rig-c/pose#280) — it contradicts ankle height on ${contra}, past ${n} %): the lower ankle moving while the higher moves with the ground`,
+    `support: read as a frontal view — ankles move more in y than x (${ranges}); ankle height only where neither foot moves with the ground`,
+  ];
+  for (const sp of supports) {
+    let speed = 0;
+    let height = 0;
+    let both = 0;
+    let differ = 0;
+    const was = new Set<string>();
+    for (let i = sp.frames[0]; i <= sp.frames[1]; i++) {
+      if (sig.by[i] === 'speed') speed++;
+      else if (sig.by[i] === 'height') height++;
+      if (sig.contact[i] === 'both') both++;
+      if (sig.height[i] !== sp.side) {
+        differ++;
+        was.add(sig.height[i] ?? 'none');
+      }
+    }
+    const by = speed > 0 ? `ankle vertical speed on ${speed} frame(s)${height > 0 ? `, ankle height on ${height} (neither foot moved with the ground)` : ''}` : `ankle height on ${height} frame(s) (neither foot moved with the ground)`;
+    const alone = differ === 0 ? 'ankle height alone reads the same' : `ankle height alone would read ${[...was].join(' or ')} on ${differ} of them`;
+    out.push(`stride ${sp.side} ${span(sp.frames)}: ${by} (both feet down on ${both}); ${alone}`);
+  }
+  return out;
+}
+
 /**
  * The in-place line without --plant-feet (rig-c/pose#242): what the declaration still changes, and the one thing it
  * cannot without planted feet — the loop closure, which spreads back the planted hip's drift. `drift` is the
@@ -1052,6 +1132,21 @@ export function legScaleLine(l: LegScale, times: readonly number[], legLength: R
   return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (larger 95th percentile of ${times.length} frames, both legs)${share}; picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}] of the straight length (${limitsPx}): ${clamp(l.low, l.limits[0], 'under', 'low')}; ${clamp(l.high, l.limits[1], 'over', 'high')}${free}`;
 }
 
+/**
+ * rig-c/pose#287: when `--leg-scale`'s range clamps no frame on any leg segment
+ * (no run under the floor, none over the ceiling, no supporting frame scaled past
+ * the floor), the clause naming the range and the picture's own spread across
+ * every segment, so a reader learns the range never bound and what floor would.
+ * Null when any frame was clamped, or with no segment scaled.
+ */
+export function legScaleNoClamp(ls: readonly LegScale[]): string | null {
+  if (ls.length === 0 || ls.some((l) => l.low.length > 0 || l.high.length > 0 || (l.support ?? []).length > 0)) return null;
+  const [floor, ceiling] = ls[0]!.limits;
+  const min = Math.min(...ls.map((l) => l.ratio.min));
+  const max = Math.max(...ls.map((l) => l.ratio.max));
+  return `no frame clamped on any leg segment: the range [${floor}, ${ceiling}] holds the picture's whole spread, picture length ÷ straight ${min.toFixed(3)} … ${max.toFixed(3)} over the ${ls.length} segment(s), so each segment is scaled to the picture on every frame; a floor above ${min.toFixed(3)} would clamp`;
+}
+
 /** A LEG-SCALE past the floor (support) line (rig-c/pose#133): the supporting leg segment scaled below `--leg-scale`'s floor down to #95's bound. */
 export function supportScaleLine(l: LegScale, s: SupportScaleRun, times: readonly number[]): string {
   const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
@@ -1136,11 +1231,6 @@ export function defaultReportPath(out: string): string {
   return `${out.endsWith('.json') ? out.slice(0, -'.json'.length) : out}.report.json`;
 }
 
-/** rig-c/pose#239: the line a directory this run made prints — the directory, and the paths that named it. */
-export function madeLine(dir: string, flags: readonly string[]): string {
-  return `  made directory ${dir} — it did not exist; ${flags.join(' and ')} ${flags.length === 1 ? 'is' : 'are'} written into it`;
-}
-
 /** rig-c/pose#239: the report's `wrote` line — whether it was the default, and the mtime of the report it replaced. */
 export function reportLine(report: string, byDefault: boolean, previous: Date | null): string {
   return `  wrote ${report} — the run's report (rig-pose-report/1)${byDefault ? ', beside --out by default; name another path with --report' : ''}${previous === null ? '' : `; it replaced the report there last written ${previous.toISOString()}`}`;
@@ -1234,6 +1324,8 @@ export interface AnkleDrift {
    * Absent without the flag.
    */
   support?: { reduce: number; units: number; legLengths: number | null } | null;
+  /** rig-c/pose#283: under a per-chain --reduce, the largest tolerance a bone from the hip down to it was reduced within (degrees). */
+  legTolerance?: number;
 }
 
 /** #251: each side's support frames, from the spans --plant-feet read. */
@@ -1245,11 +1337,46 @@ function supportFrames(supports: ReadonlyArray<{ side: 'r' | 'l'; frames: [numbe
 
 /** The drift line: the allowance on one frame, and what it lets a planted ankle slide between two. */
 export function ankleDriftLine(d: AnkleDrift): string {
+  const chainDeg = d.legTolerance;
   const legs = (v: number) => (d.legLengths === null ? '' : ` = ${(d.legLengths * v / d.units).toPrecision(3)} leg lengths`);
   const line = `ankle drift allowed: bone "${d.bone}" ${d.units.toPrecision(3)} units${legs(d.units)} on any one frame (plant ${d.plant.toPrecision(3)} + reduce ${d.reduce.toPrecision(3)}); between two frames up to ${(2 * d.units).toPrecision(3)} units${legs(2 * d.units)}`;
-  if (d.support === undefined) return `${line} — a tighter slide bar needs a smaller --reduce`;
+  if (d.support === undefined) return `${line} — ${chainDeg === undefined ? 'a tighter slide bar needs a smaller --reduce' : `its leg reduced within ${chainDeg}° (--reduce <deg>,<chain>=<deg>); a tighter slide bar needs a smaller one on its chain`}`;
   if (d.support === null) return `${line}; its side never supports, so --reduce-keep-planted keeps no frame of it`;
   const s = d.support;
   const sLegs = (v: number) => (s.legLengths === null ? '' : ` = ${(s.legLengths * v / s.units).toPrecision(3)} leg lengths`);
   return `${line} off its support frames; on them, kept dense (--reduce-keep-planted), ${s.units.toPrecision(3)} units${sLegs(s.units)} (plant ${d.plant.toPrecision(3)} + hip ${s.reduce.toPrecision(3)}), between two frames of a support span up to ${(2 * s.units).toPrecision(3)} units${sLegs(2 * s.units)}`;
 }
+
+/** rig-c/pose#283: the largest tolerance any bone from `ankle` up to the legs' top was reduced within. */
+export function legTolerance(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolOf: (bone: string) => number): number {
+  const top = r.origin?.bone ?? null;
+  let deg = tolOf(ankle);
+  for (let b: string | null = rest.get(ankle)!.parent; b !== null && b !== top; b = rest.get(b)!.parent) deg = Math.max(deg, tolOf(b));
+  return deg;
+}
+
+/**
+ * rig-c/pose#283: the reduction's tolerance per bone. Every bone takes `tolerance`
+ * but a bone of a chain `chains` names, which takes that chain's (the smallest,
+ * when two named chains list it). A name the map has no chain for is refused by
+ * name, beside the chains it has.
+ */
+export function reduceTolerances(map: JointMap, tolerance: number, chains: Record<string, number> | undefined, mapPath: string): (bone: string) => number {
+  if (chains === undefined) return () => tolerance;
+  const names = map.chains.map((c) => c.name);
+  const missing = Object.keys(chains).filter((c) => !names.includes(c));
+  if (missing.length > 0) throw new Refusal(missing.map((c) => ({ code: 'POSE_REDUCE', text: `--reduce names chain "${c}", which ${mapPath} does not have; its chains are ${names.map((x) => `"${x}"`).join(', ')}` })));
+  const by = new Map<string, number>();
+  for (const c of map.chains) {
+    const t = Object.hasOwn(chains, c.name) ? chains[c.name] : undefined;
+    if (t === undefined) continue;
+    for (const b of c.bones) by.set(b, Math.min(by.get(b) ?? t, t));
+  }
+  return (bone) => by.get(bone) ?? 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 '';
+  return ` (${Object.entries(chains).map(([c, t]) => `chain "${c}" ${t}°`).join(', ')})`;
+}

package/src/runcompare.ts

@@ -5,12 +5,12 @@
  * not a failure: the run exits 0 whenever it compared.
  */
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { compare, findingLine, readCloth, readHands, readSpans, summaryLine, writeComparison, type ClothWindow, type CompareInput, type Comparison } from './compare.ts';
 import { readMap } from './map.ts';
 import { personTrack, readPoseSequence, type PoseSequence } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import { drawable, drawSheet } from './sheet.ts';
+import { makeOutDirs, planOutDirs } from './outdir.ts';
 
 export interface CompareArgs {
   reference: string;
@@ -37,12 +37,9 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     if (!existsSync(path)) p.add('ARG_PATH', `${flag} ${path} does not exist`);
     else if (!statSync(path).isFile()) p.add('ARG_PATH', `${flag} ${path} is not a file`);
   }
-  for (const [flag, path] of [['--report', a.report], ['--sheet', a.sheet]] as const) {
-    if (path === undefined) continue;
-    const dir = dirname(path);
-    if (!existsSync(dir)) p.add('ARG_PATH', `${flag} ${path} — directory ${dir} does not exist`);
-    else if (!statSync(dir).isDirectory()) p.add('ARG_PATH', `${flag} ${path} — ${dir} is not a directory`);
-  }
+  // #284: a directory --report or --sheet names that is not there yet is made just before that file is written.
+  const reportDirs = planOutDirs([['--report', a.report]], p);
+  const sheetDirs = planOutDirs([['--sheet', a.sheet]], p);
   p.throwIfAny();
 
   // Every reader runs, and every refusal is reported together.
@@ -98,6 +95,7 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     if (c.cloth.windows.length > 0) log(`  CLOTH  the render's stroke threshold ${c.cloth.stroke.render.toFixed(4)} of its hip widths = ${c.cloth.stroke.carried}`);
   }
   if (a.report !== undefined) {
+    makeOutDirs(reportDirs, log);
     writeFileSync(a.report, writeComparison(c, {
       reference: a.reference, render: a.render, map: a.map, retargetReport: a.retargetReport ?? null,
       referenceHands: a.referenceHands ?? null, renderHands: a.renderHands ?? null, clothReference: a.clothReference ?? null, clothRender: a.clothRender ?? null,
@@ -108,6 +106,7 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     const plate = drawSheet({ frames: ref!.frames, width: ref!.seq.width, height: ref!.seq.height }, { frames: ren!.frames, width: ren!.seq.width, height: ren!.seq.height }, c.findings);
     if (plate === null) log(`  SHEET  no finding has a frame to draw (${c.findings.length} finding(s), none outside cloth); ${a.sheet} not written`);
     else {
+      makeOutDirs(sheetDirs, log);
       plate.writePng(a.sheet);
       log(`  SHEET  ${drawable(c.findings).length} finding(s), reference | render at each worst frame: wrote ${a.sheet}`);
     }

package/src/switch.ts

@@ -180,8 +180,28 @@ export interface Uncovered {
   times: number[];
 }
 
+/** One run of frames (rig-c/pose#279): first and last frame, how many, and the seconds the minimum span measured it by (first frame's time to the next frame's, the animation's end for the last). */
+export interface FrameRun {
+  frames: [number, number];
+  count: number;
+  seconds: number;
+}
+
+/**
+ * rig-c/pose#279: per set selected by angle (not `phase`), the runs of frames on which it was the nearest set within
+ * the tolerance (inside its `frames` window, before bridging, hysteresis and the minimum span), and the runs the
+ * minimum span dropped — shorter than `switchMin` where they stood — on frames the set did not show in the end.
+ */
+export interface SetRuns {
+  set: string;
+  nearest: FrameRun[];
+  suppressed: FrameRun[];
+}
+
 export interface Switches {
   switches: Switch[];
+  /** rig-c/pose#279: one per set without a `phase`, in the map's order. */
+  runs: SetRuns[];
   /** The `attachment` tracks, one per slot whose picture changes. */
   slotTracks: SlotTrack[];
   /** The offsets' `translate` tracks, one per bone a shown set offsets. */
@@ -490,6 +510,11 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   const distances = setDistances(map, targets, n, opts.shortInfo);
   const hyst = opts.switchHysteresis ?? SWITCH_LEAVE_HYSTERESIS;
   const switches: Switch[] = [];
+  // rig-c/pose#279: per angle set, the frames it was nearest on and the frames the minimum span dropped it from.
+  const nearestOn = new Map<string, boolean[]>();
+  const droppedOn = new Map<string, boolean[]>();
+  const runOf = (i: number, j: number): FrameRun => ({ frames: [i, j], count: j - i + 1, seconds: r3((j + 1 < n ? times[j + 1]! : duration) - times[i]!) });
+  const runsOfFlags = (flag: readonly boolean[]): FrameRun[] => runsOf(flag, 0).map(([i, j]) => runOf(i, j));
   // rig-c/pose#286: the supporting side on each frame, from the report's support spans (null: no foot, or no set declares a phase).
   const supportAt: Array<Side | null> = Array.from({ length: n }, () => null);
   for (const sp of opts.phaseSupports ?? []) for (let i = sp.frames[0]; i <= Math.min(sp.frames[1], n - 1); i++) supportAt[i] = sp.side;
@@ -546,6 +571,10 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       pick.push(best);
     }
+    for (const a of group) {
+      nearestOn.set(a.name, pick.map((p) => p === a));
+      droppedOn.set(a.name, Array.from({ length: n }, () => false));
+    }
     const bridgeSame = (arr: Array<AlternateSet | null>) => {
       for (let i = 0; i < n;) {
         const a = arr[i];
@@ -604,7 +633,13 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       let j = i;
       while (j + 1 < n && pick[j + 1] === a) j++;
       const to = j + 1 < n ? times[j + 1]! : duration;
-      if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = null;
+      if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) {
+        const dropped = droppedOn.get(a.name)!;
+        for (let k = i; k <= j; k++) {
+          pick[k] = null;
+          dropped[k] = true;
+        }
+      }
       i = j + 1;
     }
     if (hyst > 0) {
@@ -658,8 +693,14 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       if (dropped) bridgeSame(pick);
     }
+    // rig-c/pose#279: a dropped frame the set came back to (hysteresis, bridging) was not suppressed.
+    for (const a of group) {
+      const dropped = droppedOn.get(a.name)!;
+      for (let k = 0; k < n; k++) if (pick[k] === a) dropped[k] = false;
+    }
     spans(pick, opts);
   }
+  const runs: SetRuns[] = map.alternates.filter((a) => nearestOn.has(a.name)).map((a) => ({ set: a.name, nearest: runsOfFlags(nearestOn.get(a.name)!), suppressed: runsOfFlags(droppedOn.get(a.name)!) }));
   const order = (name: string) => map.alternates.findIndex((a) => a.name === name);
   switches.sort((x, y) => x.frames[0] - y.frames[0] || order(x.set) - order(y.set));
 
@@ -1094,7 +1135,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
     for (let k = 0; k + 1 < keys.length; k++) keys[k]!.ease = 'stepped';
     offsetTracks.push({ bone: b, property: 'translate', keys });
   }
-  return { switches, slotTracks, offsetTracks, shown, distances, chainHolds };
+  return { switches, runs, slotTracks, offsetTracks, shown, distances, chainHolds };
 }
 
 /** Per chain, the frames on which a switch of a set depicting it shows: its art was painted for that pose. */
@@ -1281,6 +1322,27 @@ export function phaseLines(map: JointMap, switches: readonly Switch[]): string[]
   return out;
 }
 
+/** How many runs a `SWITCH-MIN` line lists before it points at the report for the rest. */
+export const SWITCH_MIN_LISTED = 4;
+
+/**
+ * rig-c/pose#279: one `SWITCH-MIN` line per set the minimum span held back — the runs it dropped (frames, count,
+ * seconds), and the set's nearest runs (how many, and the longest) — so a set that matched but was held back reads
+ * apart from one that never matched. A set with nothing suppressed prints no line.
+ */
+export function switchMinLines(runs: readonly SetRuns[], switchMin: number): string[] {
+  const runText = (r: FrameRun) => `${r.count === 1 ? `frame ${r.frames[0]}` : `frames ${r.frames[0]}–${r.frames[1]}`} (${r.count} frame${r.count === 1 ? '' : 's'}, ${r.seconds.toFixed(3)}s)`;
+  const out: string[] = [];
+  for (const s of runs) {
+    if (s.suppressed.length === 0) continue;
+    const listed = s.suppressed.slice(0, SWITCH_MIN_LISTED).map(runText).join(', ');
+    const more = s.suppressed.length > SWITCH_MIN_LISTED ? `, and ${s.suppressed.length - SWITCH_MIN_LISTED} more (the report's switchRuns lists every one)` : '';
+    const longest = s.nearest.reduce((m, r) => (r.count > m.count ? r : m), s.nearest[0]!);
+    out.push(`set "${s.set}": ${s.suppressed.length} run(s) shorter than --switch-min ${switchMin}s not shown: ${listed}${more}; nearest on ${s.nearest.length} run(s), the longest ${runText(longest)}`);
+  }
+  return out;
+}
+
 const spd = (v: number) => `${v.toFixed(1)}°/frame`;
 const win = (w: [number, number]) => (w[0] === w[1] ? `window frame ${w[0]}` : `window frames ${w[0]}–${w[1]}`);
 function moveText(m: Move): string {