@rig-c/pose 0.31.1 → 0.33.0

package/src/run.ts

@@ -5,21 +5,22 @@
  * and write — only when every check passed.
  */
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 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, inferredSource } from './clean.ts';
+import { cleanLine, cleanSummaryLine, inferredSource } from './clean.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 { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions } from './retarget.ts';
-import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
+import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, rangeLine, reachCostLine, 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, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
-import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.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 { 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, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import type { BlendHold, Closure, Floor, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
 import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
 import { bodyLine, faceLine } from './face.ts';
 
@@ -41,6 +42,8 @@ export interface RetargetArgs extends RetargetOptions {
   build?: string;
   /** Keep rigc's render of the animation (frames, contact sheet, folds.json) here. */
   render?: string;
+  /** @rig-c/parts' `parts.json` (or the directory holding it): the neighbour pairs the seam reading reads (#216). */
+  parts?: string;
   /** Write the run's measurements as JSON here. */
   report?: string;
   /** Write the sequence's per-frame relative figure scale and pan as a sidecar JSON here (#161). */
@@ -55,6 +58,14 @@ export interface RetargetArgs extends RetargetOptions {
   reduce?: number;
   /** With reduce: thin the hip's translate keys within this many rig units. */
   reduceHip?: number;
+  /**
+   * What stdout carries (rig-c/pose#238). `default`: the CLEAN line's hold record
+   * as a count and each hinge's wrong-way frames as one line; `verbose`: every
+   * line in full, as before #238; `summary`: the run line, one line per measure
+   * (GATE, FEET, LIFT, JITTER, LAND) and the `wrote` lines. Refusals are the
+   * same in all three and the gate is the same gate.
+   */
+  output?: 'default' | 'verbose' | 'summary';
 }
 
 export interface RunResult {
@@ -64,10 +75,16 @@ export interface RunResult {
 
 export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunResult {
   const lines: string[] = [];
-  const say = (l: string) => {
+  const output = a.output ?? 'default';
+  /** A line every mode prints: the run line, the summary lines, the `wrote` lines. */
+  const tell = (l: string) => {
     lines.push(l);
     log(l);
   };
+  /** A line of the full output: default and --verbose print it; --summary does not. */
+  const say = (l: string) => {
+    if (output !== 'summary') tell(l);
+  };
   const refuse = (problems: readonly Problem[]): never => {
     throw new Refusal(problems);
   };
@@ -75,12 +92,18 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   for (const [flag, path] of [['--map', a.map], ['--pose', a.pose], ['--merge', a.merge]] as const) {
     if (path !== undefined && !existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
   }
-  // A file this run writes goes into a directory that is there already; --build and --render make theirs.
-  for (const [flag, path] of [['--out', a.out], ['--report', a.report], ['--camera', a.camera]] as const) {
+  // rig-c/pose#239: the report is written unless asked elsewhere — beside the motion, as <out>.report.json.
+  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);
-    if (!existsSync(dir)) args.add('ARG_PATH', `${flag} ${path} — directory ${dir} does not exist`);
-    else if (!statSync(dir).isDirectory()) args.add('ARG_PATH', `${flag} ${path} — ${dir} is not a directory`);
+    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}`]);
   }
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
@@ -92,6 +115,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   if (!(idleName in animations) && (a.idle !== undefined || a.carryIdle === true)) {
     refuse([{ code: 'IDLE_NAME', text: `${a.idle !== undefined ? `--idle "${idleName}"` : '--carry-idle reads the animation "idle", and'} the rig's motion spec ${input.motion === null ? '— there is none, so it has no animations' : `${input.motion} has no animation "${idleName}" (it has ${Object.keys(animations).join(', ') || 'none'})`}; name the rig's idle with --idle` }]);
   }
+  // #216: the neighbour pairs, read before any work so a bad --parts is refused first.
+  const seamDecl = a.parts === undefined ? null : (() => {
+    const path = partsPath(a.parts);
+    return { path, pairs: readSeamPairs(readFileSync(path, 'utf8'), path) };
+  })();
   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);
@@ -106,7 +134,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     // The rig as it stands, through the gate, so the rest pose is rig-c's reading of a green build.
     const g0 = gate(input.rig, base, join(scratch, 'base'), a.profile, a.images);
     if (!g0.green) {
-      refuse([{ code: 'RIG_GATE_BASE', text: `${input.rig} with ${input.motion ?? 'no motion spec'} is red under rigc build --profile ${a.profile} before any animation is added (exit ${g0.run.status})` }, ...g0.fails.map((f) => ({ code: 'RIGC', text: f }))]);
+      refuse([{ code: 'RIG_GATE_BASE', text: `${input.rig} with ${input.motion ?? 'no motion spec'} is red under rigc build --profile ${a.profile} before any animation is added (exit ${g0.run.status})${unreadMotionHint(a.rig, input.motion)}` }, ...g0.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
     const doc0 = readBuild(g0.build);
     const rigc = rigcVersion();
@@ -114,7 +142,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 } : {}) }, slots, input.sets);
+    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}) }, 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 ?? [])]) {
@@ -131,20 +159,25 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         }
       }
     }
-    say(`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)` : ''}` : ''}`);
+    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)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
-    say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
+    say(`  CLEAN  ${output === 'verbose' ? cleanLine(seq.cleaned!) : cleanSummaryLine(seq.cleaned!)}`);
     if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
     if (seq.camera !== undefined) say(`  CAMERA ${cameraLine(seq.camera, times, seq.cameraSource)}`);
     else if (a.plantFeet === true) say('  CAMERA none in the sequence: --plant-feet reads the picture as a fixed camera, so a zoom or a pan in the video moves the floor with it and the floor may step with the picture (tools/scan.py reads the camera, rig-c/pose#63)');
-    if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
+    if (r.scale !== null) {
+      const fit = r.scaleFit === null ? [] : scaleFitLines(r.scale.factor, r.scaleFit);
+      say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})${r.scaleFit === null ? '' : `; ${segmentClause(r.scaleFit)}`}`);
+      for (const l of fit) say(`  SCALE  ${l}`);
+    }
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
     for (const s of r.short) say(`  ${s.across === true ? 'HOLD  ' : 'SHORT '} ${shortLine(s, r.times, a.short)}`);
     if (a.short !== 'off') {
       for (const e of r.endOn) say(`  END-ON ${endOnLine(e, r.times, a.short)}`);
     }
     if (a.flip !== 'off') for (const fl of r.flips) say(`  FLIP   ${flipLine(fl, r.times, a.flip)}`);
-    for (const e of r.bends) say(`  BEND   ${bendLine(e)} — clamped straight`);
+    if (output === 'verbose') for (const e of r.bends) say(`  BEND   ${bendLine(e)} — clamped straight`);
+    else for (const g of bendGroups(r.bends)) say(`  BEND   ${bendGroupLine(g, 'clamp')}`);
     for (const e of r.turns) say(`  TURN   ${turnLine(e, r.times)}`);
     for (const u of r.turnsUnread) say(`  TURN   line "${u.line}" (${u.joints[0]} → ${u.joints[1]}) not measured: ${u.why}`);
     if (map.alternates.length > 0) {
@@ -159,14 +192,16 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (map.alternates.some((x) => x.place !== undefined && x.place !== null) && r.byHip.length === 0) say(`  BY-HIP none — no set with "place": "by-hip" showed; no key moved`);
     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)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
-    for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times)}`);
+    for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times, r.feet?.legLength ?? null, r.rigLeg)}`);
     for (const l of r.legScale) for (const s of l.support ?? []) say(`  LEG-SCALE ${supportScaleLine(l, s, r.times)}`);
     if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
     if (r.feet !== null) {
       const f = r.feet;
       const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
       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'}`);
       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)}`);
@@ -179,7 +214,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       }
       if (r.blendHold !== null) for (const l of blendLines(r.blendHold, r.times)) say(`  FEET   ${l}`);
     }
-    if (r.stance !== null) for (const l of stanceLines(r.stance, r.times)) say(`  STANCE ${l}`);
+    if (seq.travel === TRAVEL_IN_PLACE && !r.planted) say(`  TRAVEL ${openTravelLine(r.openDrift)}`);
+    if (r.stance !== null) for (const l of stanceLines(r.stance, r.times, r.feet === null || r.legStraight === null ? undefined : { legLength: r.feet.legLength, straight: r.legStraight, rigLeg: r.rigLeg })) say(`  STANCE ${l}`);
+    const nod = nodLine(r.headNod, r.nodSkipped, map.face?.pitch !== undefined);
+    if (nod !== null) say(`  NOD    ${nod}`);
     if (r.face !== null) say(`  FACE   ${faceLine(r.face)}`);
     if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
@@ -247,17 +285,27 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (!g1.green) {
       refuse([{ code: 'RIG_GATE', text: `rigc build --profile ${a.profile} is red with "${a.name}" in (exit ${g1.run.status}); nothing written` }, ...g1.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
-    say(`  GATE   rigc build --profile ${a.profile}: green${g1.summary === null ? '' : ` — ${g1.summary}`}`);
+    const gateText = gateLine(a.profile, g1.summary);
+    say(`  GATE   ${gateText}`);
 
     const doc = readBuild(g1.build);
     const posed = poseFrames(doc, a.name, r.times);
     // A reduced track is held to the dense target plus its tolerance (#32); an ankle, to what the
     // reduced bones above it may move it by (#94, `footReduce`). A scale keeps its own: it is reduced within half of it.
-    const landings = measureLanding(doc, a.name, map, r, posed).map((l) => (a.reduce === undefined ? l
-      : l.kind === 'angle' ? { ...l, tolerance: l.tolerance + a.reduce }
-      : l.kind === 'origin' && a.reduceHip !== undefined ? { ...l, tolerance: l.tolerance + a.reduceHip }
-      : l.kind === 'foot' ? { ...l, tolerance: l.tolerance + footReduce(rest, r, l.bone.replace(/:tip$/, ''), a.reduce, a.reduceHip) }
-      : l));
+    // #240: each ankle's allowance is computed once, here, and both the LAND tolerance and the drift line read it.
+    const drift: AnkleDrift[] = [];
+    const landings = measureLanding(doc, a.name, map, r, posed).map((l) => {
+      if (a.reduce === undefined) return l;
+      if (l.kind === 'angle') return { ...l, tolerance: l.tolerance + a.reduce };
+      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 lb = legBonesOf(map);
+      const side = lb?.r.ankle === ankle ? 'r' : lb?.l.ankle === ankle ? 'l' : null;
+      drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: side === null || r.rigLeg === null ? null : (l.tolerance + by) / r.rigLeg[side] });
+      return { ...l, tolerance: l.tolerance + by };
+    });
     const p = new Problems();
     // A carried idle track on a bone above a mapped one moves it where the keys did not ask (the key formula holds unmapped bones at setup).
     const carriedAbove = (bone: string): string => {
@@ -278,6 +326,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       else p.add('POSE_LANDS', `${line} — the rig does not turn the way the key formula assumes (a constraint, a scaled or sheared parent, a non-normal inherit mode)${carriedAbove(l.bone)}`);
     }
     p.throwIfAny();
+    // #236: each keyed bone's jitter as posed, against its map pair's — names the bone that moved a group's ratio.
+    const jitter = measureJitter(posed, map, r, frames, a.minScore);
+    for (const j of jitter) say(`  JITTER ${jitterLine(j)}`);
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
     const hips = seq.cleaned?.params.hipsInferred;
@@ -286,15 +337,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
     if (feetReading !== null) {
-      const f = feetReading;
-      say(`  FEET   the posed build, outside jumps: the lowest ankle's vertical range ${f.lowest.range.toFixed(2)} units = ${f.lowest.legs.toFixed(4)} leg lengths (rig leg r ${f.legLength.r.toFixed(1)}, l ${f.legLength.l.toFixed(1)} units) over ${f.lowest.frames} frames`);
-      const worst = (k: 'verticalLegs' | 'horizontalLegs') => f.plants.reduce<(typeof f.plants)[number] | null>((m, x) => (m === null || x[k] > m[k] ? x : m), null);
-      const wv = worst('verticalLegs');
-      const wh = worst('horizontalLegs');
-      if (wv !== null && wh !== null) say(`  FEET   the supporting ankle over each support span: worst vertical range ${wv.vertical.toFixed(2)} units = ${wv.verticalLegs.toFixed(4)} leg lengths (${wv.side} ${wv.frames[0]}–${wv.frames[1]}), worst horizontal drift ${wh.horizontal.toFixed(2)} units = ${wh.horizontalLegs.toFixed(4)} leg lengths (${wh.side} ${wh.frames[0]}–${wh.frames[1]})`);
+      for (const l of posedFeetLines(feetReading)) say(`  FEET   ${l}`);
     }
     const shear = r.scales.size === 0 ? [] : measureShear(doc, posed, r.scales.keys());
-    for (const x of shear) say(`  SHEAR  bone "${x.bone}": art sheared up to ${x.shear.toFixed(2)}° (frame ${x.frame}); world x axis ${x.x[0].toFixed(3)} … ${x.x[1].toFixed(3)}, y axis ${x.y[0].toFixed(3)} … ${x.y[1].toFixed(3)} of setup — a scaled bone, or one under it; a reading`);
+    for (const x of shear) say(`  SHEAR  bone "${x.bone}": art sheared up to ${x.shear.toFixed(2)}° (frame ${x.frame}); world x axis ${x.x[0].toFixed(3)} … ${x.x[1].toFixed(3)}, y axis ${x.y[0].toFixed(3)} … ${x.y[1].toFixed(3)} of setup — a scaled bone, or one under it; a reading${shearRemedy(x, rest, shear)}`);
 
     const dts = r.times.slice(1).map((t, i) => t - r.times[i]!).sort((x, y) => x - y);
     const fps = dts.length === 0 ? 12 : Math.max(1, Math.min(60, Math.round(1 / dts[dts.length >> 1]!)));
@@ -309,8 +355,15 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const u of uncovered) say(`  UNCOVERED mesh "${u.attachment}" (slot "${u.slot}"; chains ${u.chains.length === 0 ? 'none' : u.chains.join(', ')}) folds with no switch covering it on ${u.times.length} frame(s): t=${spans(u.times, 1 / fps)}`);
     }
 
-    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
-    const reportText = a.report === undefined ? null : writeReport({
+    // #216: the seam reading over the declared neighbour pairs — a reading, never a gate.
+    const seamRead = readSeams(seamDecl, input.rig, doc.slots.map((s) => s.name), g1.build, a.name, join(scratch, 'seams'), fps);
+    for (const l of seamRead.lines) say(`  SEAM   ${l}`);
+
+    // #240: what --reduce allowed each ankle, at the end of the run, from the same figure the LAND check applied.
+    for (const d of drift) say(`  REDUCE ${ankleDriftLine(d)}`);
+
+    assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    const reportText = writeReport({
         spec: 'rig-pose-report/1',
         rigc,
         rig: input.name,
@@ -320,6 +373,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         cleaned: seq.cleaned,
         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' },
         scale: r.scale,
+        scaleFit: r.scaleFit,
         holds: r.holds,
         short: r.short,
         endOn: r.endOn,
@@ -327,11 +381,15 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         flips: r.flips,
         gate: g1.summary,
         landings,
+        jitter,
         posture,
         folds: f.meshes,
+        seams: seamRead.seams,
+        seamPairs: seamRead.seamPairs,
         switches: r.switches,
         uncovered,
         turns: r.turns,
+        reach: r.reach,
         range: r.range,
         artRange: r.artRange,
         raised: r.raised,
@@ -358,16 +416,16 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
               ...(r.body.yaw === undefined ? {} : { yaw: { bone: r.body.yaw.bone, limits: r.body.yaw.limits, knee: r.body.yaw.knee, read: r.body.yaw.read, mapped: r.body.yaw.mapped, scale: r.body.yaw.scale, corr: r.body.yaw.corr } }),
               ...(r.body.sets === undefined ? {} : { sets: r.body.sets }),
             },
-        legScale: r.legScale.map(({ scale: _scale, asked: _asked, ...rest }) => rest),
+        legScale: r.legScale.map(({ scale: _scale, asked: _asked, picture: _picture, ...rest }) => rest),
         pivot: r.pivot,
         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, 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 },
+        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 },
-      }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : null, {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
+        reduce: reduced === null ? null : { tolerance: a.reduce, 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).
       rmSync(a.build, { recursive: true, force: true });
@@ -375,7 +433,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
     }
     // The kept build reads the rig again; its bytes must still match the report.
-    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    for (const [dir, flags] of makeDirs) {
+      mkdirSync(dir, { recursive: true });
+      tell(madeLine(dir, flags));
+    }
     writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
     if (a.camera !== undefined) {
       const ss = r.figureScale.frames.map((x) => x.s);
@@ -410,16 +472,96 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       rmSync(a.render, { recursive: true, force: true });
       cpSync(f.frames, a.render, { recursive: true });
     }
-    if (a.report !== undefined && reportText !== null) writeFileSync(a.report, reportText);
+    const previous = existsSync(report) ? statSync(report).mtime : null;
+    writeFileSync(report, reportText);
 
-    if (a.camera !== undefined) say(`  wrote ${a.camera} — camera track (${r.figureScale.frames.length} frames)`);
-    say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
+    if (output === 'summary') for (const l of summaryLines({ gate: gateText, feet: feetReading, stance: r.stance, jitter, landings, times: r.times })) tell(`  ${l}`);
+    if (a.camera !== undefined) tell(`  wrote ${a.camera} — camera track (${r.figureScale.frames.length} frames)`);
+    tell(reportLine(report, a.report === undefined, previous));
+    tell(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
     return { lines, written: true };
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }
 }
 
+/** The GATE line's text: the profile and rig-c's own summary of the green build. */
+export function gateLine(profile: string, summary: string | null): string {
+  return `rigc build --profile ${profile}: green${summary === null ? '' : ` — ${summary}`}`;
+}
+
+/** The FEET lines of the posed build: the lowest ankle's range, and the supporting ankle's worst over the support spans. */
+export function posedFeetLines(f: FeetReading): string[] {
+  const out = [`the posed build, outside jumps: the lowest ankle's vertical range ${lowestText(f)} (rig leg r ${f.legLength.r.toFixed(1)}, l ${f.legLength.l.toFixed(1)} units) over ${f.lowest.frames} frames`];
+  const plant = plantText(f);
+  if (plant !== null) out.push(`the supporting ankle over each support span: ${plant}`);
+  return out;
+}
+
+const lowestText = (f: FeetReading): string => `${f.lowest.range.toFixed(2)} units = ${f.lowest.legs.toFixed(4)} leg lengths`;
+
+function plantText(f: FeetReading): string | null {
+  const worst = (k: 'verticalLegs' | 'horizontalLegs') => f.plants.reduce<(typeof f.plants)[number] | null>((m, x) => (m === null || x[k] > m[k] ? x : m), null);
+  const wv = worst('verticalLegs');
+  const wh = worst('horizontalLegs');
+  if (wv === null || wh === null) return null;
+  return `worst vertical range ${wv.vertical.toFixed(2)} units = ${wv.verticalLegs.toFixed(4)} leg lengths (${wv.side} ${wv.frames[0]}–${wv.frames[1]}), worst horizontal drift ${wh.horizontal.toFixed(2)} units = ${wh.horizontalLegs.toFixed(4)} leg lengths (${wh.side} ${wh.frames[0]}–${wh.frames[1]})`;
+}
+
+/** What `--summary` reads (rig-c/pose#238): the same records the full lines print. */
+export interface SummaryInput {
+  gate: string;
+  feet: FeetReading | null;
+  stance: Stance | null;
+  jitter: readonly JitterRow[];
+  landings: readonly Landing[];
+  times: readonly number[];
+}
+
+/**
+ * `--summary`'s lines (rig-c/pose#238), one per measure, in the order a second
+ * run is compared on: GATE (the GATE line), FEET (the posed build's two FEET
+ * lines, joined), LIFT (the STANCE runs counted), JITTER (the JITTER rows' worst
+ * ratio) and LAND (each landing kind's worst against its tolerance). Each figure
+ * is formatted as the full line formats it, from the same record.
+ */
+export function summaryLines(x: SummaryInput): string[] {
+  const out = [`GATE   ${x.gate}`];
+  if (x.feet === null) out.push('FEET   not measured: the map maps no legs');
+  else {
+    const plant = plantText(x.feet);
+    out.push(`FEET   lowest ankle's vertical range ${lowestText(x.feet)} over ${x.feet.lowest.frames} frames; supporting ankle ${plant ?? 'over no support span'}`);
+  }
+  if (x.stance === null) out.push('LIFT   not read (no --stance)');
+  else {
+    const own = x.stance.runs.filter((r) => r.absorbed !== true);
+    const count = (state: Stance['runs'][number]['state']) => {
+      const rs = own.filter((r) => r.state === state);
+      return { runs: rs.length, frames: rs.reduce((t, r) => t + r.frames[1] - r.frames[0] + 1, 0), rs };
+    };
+    const lifted = count('lifted'), both = count('both'), below = count('below');
+    const top = lifted.rs.reduce<Stance['runs'][number] | null>((m, r) => (m === null || r.maxHeight > m.maxHeight ? r : m), null);
+    out.push(`LIFT   lifted ${lifted.runs} run(s), ${lifted.frames} frame(s)${top === null ? '' : `, highest ${top.maxHeight.toFixed(4)} leg lengths (${top.side} ${spanText(top.frames)})`}; planted both ${both.runs} run(s), ${both.frames} frame(s); below ${below.runs} run(s), ${below.frames} frame(s); ${x.stance.over.length} past the bounds`);
+  }
+  const read = x.jitter.filter((j) => j.ratio !== null);
+  const worst = read.reduce<JitterRow | null>((m, j) => (m === null || j.ratio! > m.ratio! ? j : m), null);
+  const still = x.jitter.filter((j) => j.triples > 0 && j.ratio === null).length;
+  const unread = x.jitter.filter((j) => j.triples === 0).length;
+  out.push(`JITTER ${x.jitter.length} bone(s): ${worst === null ? 'no ratio read' : `worst ${worst.ratio!.toFixed(2)}× on bone "${worst.bone}" (${worst.rig!.toFixed(4)}°/f² against its pair's ${worst.pair!.toFixed(4)}°/f²)`}; ${still} still pair(s), ${unread} not measured`);
+  const kinds: Array<[Landing['kind'], string, string]> = [['angle', 'aim', '°'], ['origin', 'origin', ' units'], ['scale', 'scale', ' of its setup length'], ['foot', 'ankle', ' units']];
+  const parts = kinds.flatMap(([kind, what, unit]) => {
+    const ls = x.landings.filter((l) => l.kind === kind);
+    if (ls.length === 0) return [];
+    const w = ls.reduce((m, l) => (l.worst > m.worst ? l : m));
+    const tol = kind === 'foot' ? Number(w.tolerance.toPrecision(3)) : w.tolerance;
+    return [`${what} ${ls.length}, worst ${w.worst.toPrecision(3)}${unit} on bone "${w.bone}" at frame ${w.frame} (t=${x.times[w.frame]!.toFixed(3)}s), tolerance ${tol}${unit}`];
+  });
+  out.push(`LAND   ${x.landings.length} landed: ${parts.join('; ') || 'none'}`);
+  return out;
+}
+
+const spanText = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+
 /**
  * The retarget's rotate tracks (and with a hip tolerance, its translate) thinned
  * in place (#32), on the final keys: the plant, the one floor, the stretches and
@@ -720,6 +862,16 @@ 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 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
+ * translated bone's x on the last frame less the first (null: the map translates no bone).
+ */
+export function openTravelLine(drift: number | null): string {
+  const hip = drift === null ? 'and the map translates no bone' : `so the hip follows the pose's own travel: x ${drift >= 0 ? '+' : ''}${drift.toFixed(2)} units from the first frame to the last, not closed`;
+  return `sequence declares travel: ${TRAVEL_IN_PLACE} but --plant-feet is off — its supports and the head nod are read in place as with it; the loop closure is --plant-feet's (it closes the planted hip), ${hip}`;
+}
+
 /** The in-place line (rig-c/pose#92): what --plant-feet did instead of holding the foot, and the loop's closure. */
 export function travelLine(c: Closure): string {
   const per = c.frames > 1 ? Math.abs(c.drift) / (c.frames - 1) : 0;
@@ -741,9 +893,16 @@ export function blendLines(h: BlendHold, times: readonly number[]): string[] {
  * frames, with the tolerance and the stretch keyed; one per run a stretch was
  * capped.
  */
-export function stanceLines(st: Stance, times: readonly number[]): string[] {
+export function stanceLines(st: Stance, times: readonly number[], unit?: StanceUnit): string[] {
   const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
-  const tol = `the tolerance ${st.tolerance} leg lengths`;
+  const tol = unit === undefined ? `the tolerance ${st.tolerance} leg lengths` : `the tolerance ${st.tolerance} leg lengths (${pxPair(st.tolerance, unit.legLength)})`;
+  // #237: what the tolerance is in px and in LEG-SCALE's straight length, and that "kept" is true only where no clamp moved the ankle.
+  const kept = (r: Stance['runs'][number]): string => {
+    if (r.moved === undefined) return "the pose's height kept";
+    const all = r.frames[1] - r.frames[0] + 1;
+    const head = r.moved.count === all ? `the pose's height not kept on any of its ${all} frame(s)` : `the pose's height kept on ${all - r.moved.count} of its ${all} frame(s)`;
+    return `${head}; on ${r.moved.count} (frames ${r.moved.frames.map(spanOf).join(', ')}) --leg-scale's clamps moved the free ankle off it, ${shiftText(r.moved, unit, "the pose's")}`;
+  };
   const release = `planted again under ${st.release} of it, ${(st.release * st.tolerance).toFixed(4)}`;
   const NAME: Record<Stance['runs'][number]['state'], string> = { both: 'planted-both', lifted: 'lifted', below: 'below' };
   // An absorbed run lies inside a run of the state it took; the line names that state.
@@ -755,13 +914,52 @@ export function stanceLines(st: Stance, times: readonly number[]): string[] {
     : r.state === 'both'
     ? `planted both: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, within ${tol}; its leg stretched by k ${r.k!.min === r.k!.max ? r.k!.max.toFixed(4) : `${r.k!.min.toFixed(4)} … ${r.k!.max.toFixed(4)}`} (largest ${r.k!.max.toFixed(4)})`
     : r.state === 'below'
-    ? `past the tolerance below: free foot ${r.side} ${span(r.frames)} — ${where(r)}, past ${tol} (${release}); a free foot that far below the supporting one is a support error, not a stance: never planted both, the pose's height kept`
-    : `lifted: free foot ${r.side} ${span(r.frames)} — ${where(r)}, over ${tol} (${release}); the pose's height kept`));
+    ? `past the tolerance below: free foot ${r.side} ${span(r.frames)} — ${where(r)}, past ${tol} (${release}); a free foot that far below the supporting one is a support error, not a stance: never planted both, ${kept(r)}`
+    : `lifted: free foot ${r.side} ${span(r.frames)} — ${where(r)}, over ${tol} (${release}); ${kept(r)}`));
+  if (unit !== undefined) out.unshift(stanceUnitLine(st.tolerance, unit));
   if (st.range !== undefined) out.push(legRangeLine('free', st.range, st.bounds));
   for (const o of st.over) out.push(`past the bounds: free foot ${o.side} ${span(o.frames)} — ${o.needed === null ? 'its ankle is not below its leg\'s root, so no stretch reaches the floor' : `the floor needed k ${o.needed.toFixed(4)}, past ${boundText(o.bound ?? st.bounds)}; held at the bound`}, the foot left up to ${o.left.toFixed(2)} units from the floor`);
   return out;
 }
 
+/** The units the STANCE lines print against (rig-c/pose#237): FEET's leg length, the straight leg, and the rig's leg at setup. */
+export interface StanceUnit {
+  /** FEET's: each side's median picture length hip → ankle, px. */
+  legLength: Record<Side, number>;
+  /** Each side's 95th-percentile picture length hip → ankle, px. */
+  straight: Record<Side, number>;
+  /** Each side's rig leg at setup, thigh origin → ankle, world units. */
+  rigLeg: Record<Side, number> | null;
+}
+
+const spanOf = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+
+/** `v` leg lengths in each side's px: `r 10.5 / l 10.6 px`. */
+function pxPair(v: number, legLength: Record<Side, number>): string {
+  return `r ${(v * legLength.r).toFixed(1)} / l ${(v * legLength.l).toFixed(1)} px`;
+}
+
+/** The STANCE unit line (rig-c/pose#237): --stance in FEET's leg length, in px and as a share of the straight leg LEG-SCALE's percentile reads. */
+export function stanceUnitLine(tolerance: number, u: StanceUnit): string {
+  const share = (s: Side) => (tolerance * u.legLength[s]) / u.straight[s];
+  return `unit: --stance ${tolerance} is in FEET's leg length (each side's median picture length hip → ankle, r ${u.legLength.r.toFixed(1)} / l ${u.legLength.l.toFixed(1)} px), not a straight length (a 95th percentile, as LEG-SCALE reads a segment's: the straight leg hip → ankle r ${u.straight.r.toFixed(1)} / l ${u.straight.l.toFixed(1)} px): ${tolerance} leg lengths = ${pxPair(tolerance, u.legLength)} = r ${share('r').toFixed(4)} / l ${share('l').toFixed(4)} of the straight leg`;
+}
+
+/** A free ankle's shift by the clamps, in its rig leg and in FEET's px: `up to 0.1500 leg lengths (22.6 px) above, up to … below`. */
+function shiftText(m: FreeAnkleShift, unit: { legLength: Record<Side, number> | null; rigLeg: Record<Side, number> | null } | undefined, against: string): string {
+  const one = (x: { legLengths: number }, way: string) => `up to ${x.legLengths.toFixed(4)} leg lengths${unit?.legLength == null ? '' : ` (${(x.legLengths * unit.legLength[m.side]).toFixed(1)} px of FEET's)`} ${way}`;
+  const parts = [...(m.above === null ? [] : [one(m.above, `above ${against}`)]), ...(m.below === null ? [] : [one(m.below, `below ${against}`)])];
+  const leg = unit?.rigLeg == null ? '' : ` (leg lengths: the rig's ${m.side} leg at setup, thigh origin → ankle, ${unit.rigLeg[m.side].toFixed(1)} units)`;
+  return `${parts.length === 0 ? `by 0 leg lengths, at ${against}` : parts.join(' and ')}${leg}`;
+}
+
+/** The FEET segment line (rig-c/pose#237): a mapped leg segment's picture length ÷ straight, read with or without --leg-scale. */
+export function segmentLine(sg: LegSegmentRatio): string {
+  const head = `segment chain "${sg.chain}" bone "${sg.bone}" (${sg.joints[0]} → ${sg.joints[1]})`;
+  if (sg.straight === null || sg.ratio === null) return `${head}: picture length ÷ straight not measured — ${sg.why ?? 'no straight length'}`;
+  return `${head}: picture length ÷ straight length (${sg.straight.toFixed(1)}px, the one --leg-scale scales against) min ${sg.ratio.min.toFixed(4)} · median ${sg.ratio.median.toFixed(4)} · max ${sg.ratio.max.toFixed(4)} — the scale --leg-scale asks before its clamp, read with or without it`;
+}
+
 /** A bound as the lines print it: the default's figures as written, a derived lower bound to 4 places (#95). */
 function boundText(b: readonly [number, number]): string {
   return `[${b[0] === STANCE_BOUNDS[0] ? `${b[0]}` : b[0].toFixed(4)}, ${b[1]}]`;
@@ -774,7 +972,7 @@ function legRangeLine(which: 'free' | 'supporting', range: Partial<Record<'r' |
 }
 
 /** A LEG-SCALE line: the segment, its straight length, its ratio's spread, and the frames clamped (with the asked value, #225). */
-function legScaleLine(l: LegScale, times: readonly number[]): string {
+export function legScaleLine(l: LegScale, times: readonly number[], legLength: Record<Side, number> | null = null, rigLeg: Record<Side, number> | null = null): string {
   const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
   const count = (rs: Array<[number, number]>) => rs.reduce((k, x) => k + x[1] - x[0] + 1, 0);
   const val = (r: { min: number; max: number }) => (r.min.toFixed(3) === r.max.toFixed(3) ? r.min.toFixed(3) : `${r.min.toFixed(3)}–${r.max.toFixed(3)}`);
@@ -789,7 +987,15 @@ function legScaleLine(l: LegScale, times: readonly number[]): string {
     const detail = rs.length === 1 ? ` (${askedOf(rs[0]!, kind)})` : ` (${rs.map((x) => `${span(x)}: ${askedOf(x, kind)}`).join(', ')})`;
     return `${count(rs)} frame(s) ${how} ${at}, clamped (frames ${rs.map(span).join(', ')})${detail}`;
   };
-  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); picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}]: ${clamp(l.low, l.limits[0], 'under', 'low')}; ${clamp(l.high, l.limits[1], 'over', 'high')}`;
+  // #237: the straight length against FEET's leg length, the limits in px, and what the clamps did to a free ankle.
+  const side: Side = l.joints[0].startsWith('r_') ? 'r' : 'l';
+  const share = legLength === null ? '' : ` = ${(l.straight / legLength[side]).toFixed(3)} of FEET's leg length (median hip → ankle, ${side} ${legLength[side].toFixed(1)}px)`;
+  const limitsPx = `${(l.limits[0] * l.straight).toFixed(1)}–${(l.limits[1] * l.straight).toFixed(1)}px`;
+  const clampedFrames = count(l.low) + count(l.high);
+  const free = l.free !== undefined
+    ? `; its leg free (the other foot supporting) on ${l.free.count} of its ${clampedFrames} clamped frame(s) (frames ${l.free.frames.map(span).join(', ')}): the clamps on that leg left the free ankle ${shiftText(l.free, { legLength, rigLeg }, "the picture's (the leg at picture length ÷ straight)")}`
+    : clampedFrames > 0 && legLength !== null ? `; its leg free on none of its ${clampedFrames} clamped frame(s)` : '';
+  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}`;
 }
 
 /** 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. */
@@ -823,3 +1029,144 @@ export function readReportInput(file:string):ReportInputSnapshot {
 export function assertReportInputs(inputs:readonly ReportInputSnapshot[]):void {
   for(const expected of inputs){const current=readReportInput(expected.file);if(current.identity.path!==expected.identity.path||current.identity.sha256!==expected.identity.sha256)throw new Refusal([{code:'REPORT_INPUTS_CHANGED',text:`${expected.identity.path}: consumed input changed before output writes; expected SHA-256 ${expected.identity.sha256}, found ${current.identity.sha256}`}]);}
 }
+
+/**
+ * #216: the seam reading end to end — the declared pairs, each pair whose part
+ * has no slot of its name left unread (rigc would refuse the whole render for
+ * it), one `rigc render --seam` over the rest, and its projection. Whatever it
+ * finds, or fails to read, it says so and refuses nothing.
+ */
+function readSeams(decl: { path: string; pairs: SeamPair[] } | null, rig: string, slotNames: string[], build: string, animation: string, dir: string, fps: number): ReturnType<typeof projectSeams> & { lines: string[]; frames: unknown } {
+  if (decl === null || decl.pairs.length === 0) {
+    let why: string;
+    if (decl !== null) why = `${decl.path} holds no limb segment below another (a part's "limb" record), so it declares no pair`;
+    else {
+      // @rig-c/parts writes rig/ and parts.json side by side under its --out; a rig spec itself carries no pair.
+      const home = dirname(dirname(rig));
+      why = `a rig spec carries none and no --parts was named${existsSync(join(home, 'parts.json')) ? ` (${home} holds parts.json: --parts ${home} reads its limbs)` : ''}`;
+    }
+    return { seams: [], seamPairs: [], frames: null, lines: [`no neighbour pair declared — ${why}; seams: []`] };
+  }
+  const have = new Set(slotNames);
+  const unread = new Map<string, string>();
+  for (const p of decl.pairs) {
+    const missing = [p.a, p.b].filter((n) => !have.has(n));
+    if (missing.length > 0) unread.set(p.pair, `${missing.map((n) => `part "${n}"`).join(' and ')} has no slot of its name in the rig (a part is drawn by the slot of its name)`);
+  }
+  const toRead = decl.pairs.filter((p) => !unread.has(p.pair));
+  let rows: ReturnType<typeof readSeamDoc> = [];
+  let frames: unknown = null;
+  if (toRead.length > 0) {
+    const s = seamRender(build, animation, dir, fps, toRead.map((p) => [p.a, p.b] as const));
+    let why: string | null = null;
+    if (s.seam === null) {
+      const said = s.run.out.split('\n').map((l) => l.trim()).find((l) => l.startsWith('rigc: ') && !l.startsWith('rigc: wrote'));
+      why = `rigc render --seam did not read (exit ${s.run.status})${said === undefined ? '' : `: ${said}`}`;
+    } else {
+      try {
+        rows = readSeamDoc(s.seam.text, s.seam.path);
+        frames = s.frames;
+      } catch (e) {
+        if (!(e instanceof Refusal)) throw e;
+        why = e.message;
+      }
+    }
+    if (why !== null) for (const p of toRead) unread.set(p.pair, why);
+  }
+  const projected = projectSeams(decl.pairs, rows, unread);
+  return { ...projected, frames, lines: seamLines(projected, fps) };
+}
+
+/** rig-c/pose#239: the report's path when --report is not given — `<out>.report.json`, beside the motion (a trailing `.json` of --out is replaced). */
+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()}`}`;
+}
+
+/**
+ * rig-c/pose#239: `--rig` naming a rig.json reads no motion spec, even with one beside it. When the base
+ * gate is red that way, the refusal says the motion beside it was not read and names the two forms that read it.
+ */
+export function unreadMotionHint(rigArg: string, motion: string | null): string {
+  if (motion !== null) return '';
+  const beside = join(dirname(rigArg), 'motion.json');
+  if (!existsSync(beside) || statSync(rigArg).isDirectory()) return '';
+  return `; ${beside} is beside it and was not read — --rig naming the rig.json reads no motion spec: pass --rig ${dirname(rigArg)} (the directory, which reads the motion.json beside its rig.json) or --base-motion ${beside}`;
+}
+
+/** The SCALE line's own clause (rig-c/pose#240): the median it divides by, against the segment at its longest. */
+export function segmentClause(f: ScaleFit): string {
+  const sg = f.segment;
+  return `the median is ${sg.ratio.toFixed(3)} of its 95th percentile ${sg.straight.toFixed(2)} — under 1, the median frame foreshortens ${sg.joints[0]} → ${sg.joints[1]} and the factor is ${(1 / sg.ratio).toFixed(3)}× the one at its longest`;
+}
+
+/**
+ * The SCALE reading's remedy lines (rig-c/pose#240): the scale segment's median
+ * against its 95th percentile, the legs' and hips' bands beside the factor (and
+ * the line naming a factor outside both), and the hip's travel, pose beside rig.
+ */
+export function scaleFitLines(factor: number, f: ScaleFit): string[] {
+  const out: string[] = [];
+  const sg = f.segment;
+  const band = (b: ScaleBand) => `${b.lo.toFixed(5)}–${b.hi.toFixed(5)}`;
+  const within = (w: boolean) => (w ? 'within' : 'outside');
+  const leg = f.leg === null ? 'leg not read (needs both legs)' : `leg ${band(f.leg.band)} (${within(f.leg.within)})`;
+  const hip = f.hip === null ? 'hip not read (needs both legs and both hips)' : `hip ${band(f.hip.band)} (${within(f.hip.within)})`;
+  out.push(`bands, rig ÷ picture at its 95th percentile – median: ${leg}, ${hip}; scale.factor ${factor.toFixed(5)} (within: rig ÷ factor inside the picture's lengths ± 1 px)`);
+  if (f.outside === true) {
+    out.push(`outside both bands: scale.factor ${factor.toFixed(5)} sizes the figure as neither its legs nor its hips do — "translate" "scale" ${sg.joints[0]} → ${sg.joints[1]} is proportioned unlike the rig; a pair on the legs or hips reads inside a band`);
+  }
+  const t = f.travel;
+  const per = (v: { legs: [number, number] | null; hips: [number, number] | null }, k: 0 | 1) => `${v.legs === null ? '' : ` = ${v.legs[k].toFixed(3)} legs`}${v.hips === null ? '' : ` = ${v.hips[k].toFixed(3)} hips`}`;
+  out.push(`hip travel (${t.joint} → bone "${t.bone}"), range: pose x ${t.pose.x.toFixed(2)}px${per(t.pose, 0)}, y ${t.pose.y.toFixed(2)}px${per(t.pose, 1)}; rig x ${t.rig.x.toFixed(2)}${per(t.rig, 0)}, y ${t.rig.y.toFixed(2)}${per(t.rig, 1)}`);
+  return out;
+}
+
+/**
+ * The SHEAR line's remedy clause (rig-c/pose#240): where the shear comes from
+ * and the rig spec's `inherit` setting that removes it. Nothing on a shear that
+ * prints as 0.00°, the line's own precision.
+ */
+export function shearRemedy(x: { bone: string; shear: number }, rest: Rest, measured: ReadonlyArray<{ bone: string }>): string {
+  if (x.shear.toFixed(2) === '0.00') return '';
+  const b = rest.get(x.bone);
+  if (b === undefined) return '';
+  const inherit = b.inherit ?? 'normal';
+  const parent = b.parent;
+  const carried = parent !== null && measured.some((m) => m.bone === parent);
+  if (inherit === 'normal' && carried) {
+    return `; it inherits "normal" from scaled "${parent}" — "inherit": "noScale" on bone "${x.bone}" in the rig spec unshears its art and still turns it with "${parent}" ("onlyTranslation" also stops the turn)`;
+  }
+  if (inherit !== 'normal') return `; bone "${x.bone}" inherits "${inherit}", so the shear is not carried from "${parent ?? 'its parent'}"`;
+  return `; its parent ${parent === null ? 'is none' : `"${parent}" is not scaled`}, so the shear is not carried from above`;
+}
+
+/** rig-c/pose#240: how far --reduce may leave one ankle off the dense run's, as the landing check applies it. */
+export interface AnkleDrift {
+  /** The ankle point, as its LAND line names it (`<bone>:tip`). */
+  bone: string;
+  side: 'r' | 'l' | null;
+  /** The plant's own tolerance (without --reduce). */
+  plant: number;
+  /** `footReduce`: the most the reduced bones above it may move it. */
+  reduce: number;
+  /** plant + reduce, world units — the LAND line's tolerance. */
+  units: number;
+  /** `units` in that side's rig leg at setup (thigh origin → ankle); null without both legs. */
+  legLengths: number | null;
+}
+
+/** 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 legs = (v: number) => (d.legLengths === null ? '' : ` = ${(d.legLengths * v / d.units).toPrecision(3)} leg lengths`);
+  return `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)} — a tighter slide bar needs a smaller --reduce`;
+}