@rig-c/parts 1.13.0 → 1.14.0

package/src/check.ts

@@ -56,9 +56,12 @@
  * uncovered holes `assemble` recorded in `parts.json`'s `recomposite` block,
  * copied into `check.json` because the seam cannot see them — it compares the
  * setup pose with the flat stack of parts, and a pixel no part holds is
- * missing from both. The
- * part-alone renders and the shut-eye still are scratch (`_isolated/`,
- * `_still/`), removed before the stage returns.
+ * missing from both. When `motion.json` holds an animation beside the idle,
+ * one more bar, `ANIMATIONS_DO_NOT_FOLD` (issue #320): rigc's own
+ * `render --folds` over every animation, physics constraints left out
+ * ({@link FOLD_LINE}). The part-alone renders, the shut-eye still, the keyed
+ * build and the fold render are scratch (`_isolated/`, `_still/`, `_loop/`,
+ * `_folds/`), removed before the stage returns.
  *
  * Where this port deliberately differs from the reference, each written where
  * it applies below: a gate summary is read with a pattern rather than the
@@ -130,6 +133,7 @@ import {
   rangeLine,
   readRequirements,
   type RequirementLine,
+  type MayFold,
   type RequirementsFile,
   requirementProblem,
   type RequirementsSummary,
@@ -1642,6 +1646,8 @@ export interface CheckFigures {
   TIP_OVER_ROOT: JudgementLine;
   STILL_REGIONS_DARK: JudgementLine;
   TEXTURE_STRETCH: JudgementLine;
+  /** Written only when motion.json holds an animation beside the idle (issue #320): {@link FoldsLine}. */
+  [FOLD_LINE]?: FoldsLine;
   RECOMPOSITE_HOLES: ReportedLine;
   /** Written only under `--source` (issue #77): the setup pose against the painting, REPORTED. */
   SETUP_POSE_VS_SOURCE?: ReportedLine;
@@ -1665,22 +1671,46 @@ export interface RequirementsBlock {
   lines: Record<string, RequirementLine>;
 }
 
+/**
+ * The bar over the animations beside the idle (issue #320): no mesh triangle
+ * turned over against the setup pose on any frame, on rig-c's own reading —
+ * `rigc render --folds`, one run over every animation the build holds — and
+ * not a reading of this package's. A fold the art means is declared in the
+ * requirements file's `may_fold`, by slot and animation with its why, and is
+ * named and not held to the bar.
+ *
+ * ⭐ **Read with the physics constraints left out**, as the loop is, from the
+ * same build ({@link withoutPhysics}). rig-c's render steps physics by 1/fps
+ * from frame 0, so a fold a physics constraint makes is the sampling rate's:
+ * on the public `scarf` example `hop` folds `bottomwear` (3 of 308 triangles,
+ * frames 7-8) at 12 fps, and at none of 10, 15, 24, 30, 36, 48 and 60 fps;
+ * `hair_front` at 6 fps; and nothing at 6, 12 or 24 fps with its 30 physics
+ * constraints left out [measured for issue #320, rigc 2.47.1, a scratch run,
+ * not tracked]. The keys and weights fold at every rate or at none that the
+ * sampling resolves; the rate a consumer steps physics at is the scene's.
+ *
+ * The idle is not read here: written only when the motion holds an animation
+ * beside it, so a rig of the idle alone writes and prints what it did.
+ */
+export const FOLD_LINE = 'ANIMATIONS_DO_NOT_FOLD';
+
 /** The bars `PASS` reads, in the order the summary counts them: the gate, the reference's two, then the judgement lines. */
 export const BARS = ['gate', 'loop', 'seam', ...JUDGEMENT_LINES] as const;
 
 /**
  * The bars a character's own check may have failed and `compose --accept`
  * still take (issue #203): every bar of {@link BARS} but the gate, which is
- * rig-c's and never accepted.
+ * rig-c's and never accepted, and {@link FOLD_LINE} (issue #320).
  */
-export const ACCEPTABLE_BARS: readonly string[] = BARS.filter((b) => b !== 'gate');
+export const ACCEPTABLE_BARS: readonly string[] = [...BARS.filter((b) => b !== 'gate'), FOLD_LINE];
 
 /**
  * The bars a `check.json`, as `check` writes it, says were not met, in
  * {@link BARS} order: the gate when `gate_spine_html_green` is not true, the
  * loop when `loop_max_diff` is a number other than {@link LOOP_MAX_BAR}, the
  * seam when its figures fail {@link seamFails}, and each judgement line whose
- * status is `FAIL`. A bar that measured nothing (null figures, `SKIP`) is not
+ * status is `FAIL`, then {@link FOLD_LINE} when it is written and `FAIL`
+ * (issue #320). A bar that measured nothing (null figures, `SKIP`) is not
  * one of them. Read off the file rather than its problems, because the file is
  * all a finished build leaves (issue #203).
  */
@@ -1691,7 +1721,7 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
   // A check.json written before issue #216 has no seam_frame_scale; it is read by the frame count, the bar it was written under.
   const scale = typeof fig.seam_frame_scale === 'number' ? fig.seam_frame_scale : 1;
   if (typeof fig.seam_mean === 'number' && typeof fig.seam_px_over_40 === 'number' && seamFails(fig.seam_mean, fig.seam_px_over_40, scale)) out.push('seam');
-  for (const n of JUDGEMENT_LINES) {
+  for (const n of [...JUDGEMENT_LINES, FOLD_LINE]) {
     const l = fig[n];
     if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
   }
@@ -1743,7 +1773,179 @@ export interface CheckReport {
  */
 export function besideIdleLine(names: readonly string[]): string | null {
   if (names.length === 0) return null;
-  return `beside the idle: ${names.length} animation(s), ${names.join(', ')} — built and gated by rigc with the rig, not measured: every bar here reads the idle`;
+  return `beside the idle: ${names.length} animation(s), ${names.join(', ')} — built and gated by rigc with the rig; ${FOLD_LINE} reads each for folds, every other bar here reads the idle`;
+}
+
+// ---------------------------------------------------------------------------
+// the animations beside the idle, read for folds (issue #320)
+// ---------------------------------------------------------------------------
+
+/**
+ * The fold render's `--max`, rigc's smallest: `--folds` reads posed vertices
+ * in world units, which the frame size does not change (rig-c AUTHORING §8.3),
+ * so the frames are drawn as small as rigc draws them and thrown away. On
+ * `scarf` the `hop` folds.json was byte-identical at `--max` 16 and 640
+ * [measured for issue #320, a scratch run].
+ */
+export const FOLD_RENDER_MAX = 16;
+
+/** The fold render, under `--out`; removed before the stage returns. */
+const FOLD_SCRATCH = '_folds';
+
+/** One mesh that folds in one animation beside the idle: rigc's figures, the declaration that takes it if any, and rigc's own line. */
+export interface FoldRow {
+  animation: string;
+  slot: string;
+  attachment: string;
+  /** How many frames show a folded triangle. */
+  frames: number;
+  /** The frame with the most, the earliest on a tie (rigc's `worst`). */
+  worst_frame: number;
+  /** How many triangles are folded on that frame. */
+  worst_triangles: number;
+  /** How many triangles the mesh has. */
+  triangles: number;
+  /** The `may_fold` entry's why when the requirements file declares this slot and animation; null when nothing does. */
+  declared: string | null;
+  /** rigc's printed line for the mesh, verbatim (`rigc render --folds`). */
+  line: string;
+}
+
+/** `check.json`'s `ANIMATIONS_DO_NOT_FOLD`: written only when the motion holds an animation beside the idle. */
+export interface FoldsLine {
+  status: 'PASS' | 'FAIL';
+  /** Every animation beside the idle, in motion.json's order: each one read. */
+  animations: string[];
+  fps: number;
+  /** How many physics constraints the read build left out ({@link withoutPhysics}); 0 when the rig has none. */
+  physics_left_out: number;
+  /** Every mesh that folds in an animation read, in that animation's order and rigc's mesh order. */
+  folding: FoldRow[];
+  /** The rows no `may_fold` entry takes: the bar's figure. */
+  folding_undeclared: number;
+  /** The `may_fold` entries no row matches, each a FAIL — an exception that excepts nothing. */
+  declared_not_folding: Array<{ slot: string; animation: string }>;
+  /** The bar: undeclared folds, at most this many. */
+  bar: number;
+}
+
+/** One folding mesh as the reading states it. */
+export interface FoldingMesh {
+  slot: string;
+  attachment: string;
+  triangleCount: number;
+  frames: number;
+  worstFrame: number;
+  worstTriangles: number;
+  line: string;
+}
+
+/** The marker rigc prints before each fold line (`rigc render --folds`). */
+const FOLD_PRINTED = /^\s*\.\.\s+folds\s+(.*)$/;
+
+/**
+ * The folding meshes of each named animation, read off a `rigc render
+ * --folds` run over every animation: `frames.json` names each set's
+ * directory, each `folds.json` (`rigc-folds/1`) its meshes, and each folding
+ * mesh's line is the one rigc printed for it. Refuses (`CHECK_FOLDS_READ`),
+ * every problem at once, a set or file that is missing, a file that is not
+ * the animation's or not at the rate asked, a field of the wrong shape, and a
+ * folding mesh rigc printed no line for.
+ */
+export function readFoldSets(dir: string, named: readonly string[], fps: number, printed: string): Map<string, FoldingMesh[]> {
+  const problems: Problem[] = [];
+  const bad = (object: string, detail: string): void => {
+    problems.push({ code: 'CHECK_FOLDS_READ', object, detail });
+  };
+  const lines = printed.split('\n').map((l) => FOLD_PRINTED.exec(l)?.[1]).filter((l): l is string => l !== undefined);
+  const out = new Map<string, FoldingMesh[]>();
+  const sidecar = readJson(join(dir, 'frames.json'), problems);
+  const sets = sidecar !== null && Array.isArray(sidecar.sets) ? sidecar.sets.filter(isRecord) : [];
+  for (const name of named) {
+    const set = sets.find((x) => x.animation === name);
+    if (set === undefined || typeof set.dir !== 'string') {
+      bad(join(dir, 'frames.json'), `names no frame set for animation ${JSON.stringify(name)}; \`rigc render --folds\` over the build writes one per animation`);
+      continue;
+    }
+    const path = join(dir, set.dir, 'folds.json');
+    const file = readJson(path, problems);
+    if (file === null) continue;
+    if (file.spec !== 'rigc-folds/1') bad(path, `spec is ${JSON.stringify(file.spec)}; "rigc-folds/1" is required`);
+    if (file.animation !== name) bad(path, `animation is ${JSON.stringify(file.animation)}; ${JSON.stringify(name)} is required`);
+    if (file.fps !== fps) bad(path, `fps is ${JSON.stringify(file.fps)}; ${fps}, the rate asked for, is required`);
+    if (!Array.isArray(file.meshes)) {
+      bad(path, `meshes is ${JSON.stringify(file.meshes)?.slice(0, 40)}; an array is required`);
+      continue;
+    }
+    const rows: FoldingMesh[] = [];
+    file.meshes.forEach((m, i) => {
+      const at = `${path} meshes[${i}]`;
+      if (!isRecord(m) || typeof m.slot !== 'string' || typeof m.attachment !== 'string' || typeof m.triangleCount !== 'number' || !Array.isArray(m.frames)) {
+        bad(at, 'is not { slot, attachment, triangleCount, frames, worst } as rigc-folds/1 writes it');
+        return;
+      }
+      if (m.worst === null) return;
+      const worst = isRecord(m.worst) ? m.worst : null;
+      if (worst === null || typeof worst.index !== 'number' || !Array.isArray(worst.triangles)) {
+        bad(at, `worst is ${JSON.stringify(m.worst)?.slice(0, 40)}; null or { index, triangles, … } is required`);
+        return;
+      }
+      const prefix = `${JSON.stringify(name)}: mesh "${m.attachment}" (slot "${m.slot}") folds on `;
+      const line = lines.find((l) => l.startsWith(prefix));
+      if (line === undefined) {
+        bad(at, `folds on ${m.frames.length} frame(s), and rigc printed no line beginning ${prefix.trim()}`);
+        return;
+      }
+      rows.push({ slot: m.slot, attachment: m.attachment, triangleCount: m.triangleCount, frames: m.frames.length, worstFrame: worst.index, worstTriangles: worst.triangles.length, line });
+    });
+    out.set(name, rows);
+  }
+  refuseIfAny(problems);
+  return out;
+}
+
+/**
+ * The fold line (issue #320) from the reading: every folding mesh a row, a
+ * row no `may_fold` entry takes a `CHECK_ANIMATIONS_DO_NOT_FOLD` problem
+ * naming the animation, the slot and rigc's line, and an entry no row
+ * matches a problem of its own — a declaration that excepts nothing.
+ */
+export function foldsLine(named: readonly string[], fps: number, physicsLeftOut: number, readings: ReadonlyMap<string, readonly FoldingMesh[]>, mayFold: readonly MayFold[], requirementsPath: string | null, problems: Problem[]): FoldsLine {
+  const folding: FoldRow[] = [];
+  for (const name of named) {
+    for (const m of readings.get(name) ?? []) {
+      const entry = mayFold.find((e) => e.slot === m.slot && e.animation === name);
+      folding.push({ animation: name, slot: m.slot, attachment: m.attachment, frames: m.frames, worst_frame: m.worstFrame, worst_triangles: m.worstTriangles, triangles: m.triangleCount, declared: entry === undefined ? null : entry.why, line: m.line });
+    }
+  }
+  const physics = physicsLeftOut === 0 ? '' : `, its ${physicsLeftOut} physics constraint(s) left out`;
+  for (const r of folding) {
+    if (r.declared !== null) continue;
+    problems.push({
+      code: `CHECK_${FOLD_LINE}`,
+      object: `animation "${r.animation}", mesh "${r.attachment}" (slot "${r.slot}")`,
+      detail: `rigc render --folds at ${fps} fps${physics}: ${r.line}; no triangle turned over against the setup pose is required — a fold the art means is declared in the --requirements file's may_fold, { "slot": "${r.slot}", "animation": "${r.animation}", "why": … }`,
+    });
+  }
+  const declaredNotFolding = mayFold.filter((e) => !folding.some((r) => r.slot === e.slot && r.animation === e.animation)).map((e) => ({ slot: e.slot, animation: e.animation }));
+  for (const e of declaredNotFolding) {
+    problems.push({
+      code: `CHECK_${FOLD_LINE}`,
+      object: `${requirementsPath ?? 'the requirements file'} may_fold (slot "${e.slot}", animation "${e.animation}")`,
+      detail: `declares a fold, and rigc render --folds at ${fps} fps${physics} reads no folded triangle on slot "${e.slot}" in animation "${e.animation}"; an exception that excepts nothing is taken out of the file`,
+    });
+  }
+  const undeclared = folding.filter((r) => r.declared === null).length;
+  return {
+    status: undeclared === 0 && declaredNotFolding.length === 0 ? 'PASS' : 'FAIL',
+    animations: [...named],
+    fps,
+    physics_left_out: physicsLeftOut,
+    folding,
+    folding_undeclared: undeclared,
+    declared_not_folding: declaredNotFolding,
+    bar: 0,
+  };
 }
 
 /**
@@ -1830,7 +2032,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const loopDir = join(out, '_loop');
   const seamDir = join(out, SEAM_DIR);
   const keptDir = join(out, STILL_DIR);
-  for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir]) rmSync(d, { recursive: true, force: true });
+  const foldDir = join(out, FOLD_SCRATCH);
+  for (const d of [buildDir, idleDir, stillDir, isoDir, loopDir, seamDir, keptDir, foldDir]) rmSync(d, { recursive: true, force: true });
   const written: string[] = [];
   const write = (name: string, data: string): void => {
     writeFileSync(join(out, name), data);
@@ -1861,43 +2064,55 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   let loop: { max: number; x: number; y: number } | null = null;
   let loopSet: FrameSet | null = null;
   let loopPhysics: LoopPhysics[] | null = null;
-  if (inp.idleDuration !== null) {
-    const render = rigc(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--geometry', '--out', idleDir]);
-    if (render.status !== 0) refuseIfAny(rigcFailed('render --animation idle --geometry', render, render.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
-    idle = readFrameSet(idleDir);
-    const last = idle.frames[idle.frames.length - 1];
-    // Issue #244: the last frame's time and the duration are compared within TIME_SLACK, not with `!==` — a whole
-    // number of frames (40/12 s) is not exact in binary, and rigc writes its last frame at 40 * (1/12), one ulp off.
-    if (idle.stride !== 1 || idle.written !== idle.sampled || Math.abs(idle.duration - inp.idleDuration) > TIME_SLACK || last.index !== idle.sampled - 1) {
-      refuseIfAny([
-        {
-          code: 'CHECK_LOOP_LAST_FRAME_AT_DURATION',
-          object: `idle frame ${last.name}`,
-          detail: `rigc sampled ${idle.sampled} frame(s), wrote ${idle.written} at stride ${idle.stride}, the last at t = ${idle.duration}s; the loop compares frame 0 with the frame at the idle's duration, ${inp.idleDuration}s, so a duration that is a whole number of 1/${IDLE_FPS} s ticks (within ${TIME_SLACK} s) and every frame written are required`,
-        },
-      ]);
-    }
-    const contact = join(idle.dir, 'contact.png');
-    if (existsSync(contact)) {
-      copyFileSync(contact, join(out, 'contact.png'));
-      written.push('contact.png');
-    }
-    loop = maxRgbDiff(idle.frames[0].image, last.image);
-    loopSet = idle;
-    // The keyed loop (issue #183): with a physics constraint, the same rig and motion with every one left out, built
-    // the same way and rendered the same way, is what frame 0 and the frame at the duration are read from.
-    const stripped = withoutPhysics(inp.rig, inp.motion);
-    if (stripped !== null) {
-      loopPhysics = stripped.physics;
-      try {
-        mkdirSync(loopDir, { recursive: true });
-        const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
-        writeFileSync(join(loopDir, 'rig.json'), JSON.stringify({ ...stripped.rig, images }));
-        writeFileSync(join(loopDir, 'motion.json'), JSON.stringify(stripped.motion));
+  // The keyed build (issues #183, #320): with a physics constraint, the same rig and motion with every one left out,
+  // built once the same way, which the loop and the folds of the animations beside the idle are both read from.
+  const stripped = withoutPhysics(inp.rig, inp.motion);
+  let keyed: string | null = null;
+  const keyedBuild = (what: string): string => {
+    if (stripped === null) return buildDir;
+    if (keyed !== null) return keyed;
+    mkdirSync(loopDir, { recursive: true });
+    const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
+    writeFileSync(join(loopDir, 'rig.json'), JSON.stringify({ ...stripped.rig, images }));
+    writeFileSync(join(loopDir, 'motion.json'), JSON.stringify(stripped.motion));
+    const lb = rigc(['build', '--rig', join(loopDir, 'rig.json'), '--motion', join(loopDir, 'motion.json'), '--out', join(loopDir, 'build'), ...packedBuildArgs(mode)]);
+    if (lb.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (${what})`, lb, buildGateLines(lb.out)));
+    keyed = join(loopDir, 'build');
+    return keyed;
+  };
+  const named = isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations).filter((n) => n !== 'idle') : [];
+  let folds: FoldsLine | null = null;
+  const foldProblems: Problem[] = [];
+  try {
+    if (inp.idleDuration !== null) {
+      const render = rigc(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--geometry', '--out', idleDir]);
+      if (render.status !== 0) refuseIfAny(rigcFailed('render --animation idle --geometry', render, render.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+      idle = readFrameSet(idleDir);
+      const last = idle.frames[idle.frames.length - 1];
+      // Issue #244: the last frame's time and the duration are compared within TIME_SLACK, not with `!==` — a whole
+      // number of frames (40/12 s) is not exact in binary, and rigc writes its last frame at 40 * (1/12), one ulp off.
+      if (idle.stride !== 1 || idle.written !== idle.sampled || Math.abs(idle.duration - inp.idleDuration) > TIME_SLACK || last.index !== idle.sampled - 1) {
+        refuseIfAny([
+          {
+            code: 'CHECK_LOOP_LAST_FRAME_AT_DURATION',
+            object: `idle frame ${last.name}`,
+            detail: `rigc sampled ${idle.sampled} frame(s), wrote ${idle.written} at stride ${idle.stride}, the last at t = ${idle.duration}s; the loop compares frame 0 with the frame at the idle's duration, ${inp.idleDuration}s, so a duration that is a whole number of 1/${IDLE_FPS} s ticks (within ${TIME_SLACK} s) and every frame written are required`,
+          },
+        ]);
+      }
+      const contact = join(idle.dir, 'contact.png');
+      if (existsSync(contact)) {
+        copyFileSync(contact, join(out, 'contact.png'));
+        written.push('contact.png');
+      }
+      loop = maxRgbDiff(idle.frames[0].image, last.image);
+      loopSet = idle;
+      // The keyed loop (issue #183): with a physics constraint, the same rig and motion with every one left out, built
+      // the same way and rendered the same way, is what frame 0 and the frame at the duration are read from.
+      if (stripped !== null) {
+        loopPhysics = stripped.physics;
         const what = 'the idle with its physics constraint(s) left out';
-        const lb = rigc(['build', '--rig', join(loopDir, 'rig.json'), '--motion', join(loopDir, 'motion.json'), '--out', join(loopDir, 'build'), ...packedBuildArgs(mode)]);
-        if (lb.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (${what})`, lb, buildGateLines(lb.out)));
-        const lr = rigc(['render', '--candidate', join(loopDir, 'build'), '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--out', join(loopDir, 'frames')]);
+        const lr = rigc(['render', '--candidate', keyedBuild(what), '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--out', join(loopDir, 'frames')]);
         if (lr.status !== 0) refuseIfAny(rigcFailed(`render --animation idle (${what})`, lr, lr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
         const kept = readFrameSet(join(loopDir, 'frames'));
         const keptLast = kept.frames[kept.frames.length - 1];
@@ -1912,13 +2127,27 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         }
         loop = maxRgbDiff(kept.frames[0].image, keptLast.image);
         loopSet = kept;
+      }
+      const idleImages = idle.frames.map((f) => f.image);
+      writePng(join(out, 'motion_heat.png'), motionHeat(idleImages));
+      written.push('motion_heat.png');
+    }
+
+    // 3a. the animations beside the idle, read for folds by rigc (issue #320) — only when there is one; at the idle's
+    // rate whatever --requirements says, so a requirements file moves only what it declares (CK78), from the keyed build
+    if (named.length > 0) {
+      const fps = IDLE_FPS;
+      try {
+        const fr = rigc(['render', '--candidate', keyedBuild('the animations beside the idle with their physics constraint(s) left out'), '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
+        if (fr.status !== 0) refuseIfAny(rigcFailed(`render --folds --fps ${fps}${stripped === null ? '' : ' (physics constraint(s) left out)'}`, fr, fr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+        const readings = readFoldSets(foldDir, named, fps, fr.out);
+        folds = foldsLine(named, fps, stripped === null ? 0 : stripped.physics.length, readings, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems);
       } finally {
-        rmSync(loopDir, { recursive: true, force: true });
+        rmSync(foldDir, { recursive: true, force: true });
       }
     }
-    const idleImages = idle.frames.map((f) => f.image);
-    writePng(join(out, 'motion_heat.png'), motionHeat(idleImages));
-    written.push('motion_heat.png');
+  } finally {
+    rmSync(loopDir, { recursive: true, force: true });
   }
 
   // 3b. the parts a judgement reads alone: each rendered by its own slots, on the whole rig's grid
@@ -2059,6 +2288,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     TIP_OVER_ROOT: tip,
     STILL_REGIONS_DARK: still,
     TEXTURE_STRETCH: stretch,
+    ...(folds === null ? {} : { [FOLD_LINE]: folds }),
     RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
     ...(sourceRead === null ? {} : { [SOURCE_LINE]: sourceRead }),
     ...(Object.keys(skipped).length === 0 ? {} : { skipped }),
@@ -2090,7 +2320,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const rank = (q: Problem): number => JUDGEMENT_LINES.findIndex((n) => q.code === `CHECK_${n}`);
   problems.sort((a, b) => rank(a) - rank(b));
   problems.unshift(...barProblems);
-  problems.push(...reqProblems);
+  problems.push(...foldProblems, ...reqProblems);
   figures.PASS = problems.length === 0;
   write('check.json', `${JSON.stringify(figures, null, 1)}\n`);
   const bars: CheckReport['bars'] = { measured: ['gate'], skipped: [] };
@@ -2104,6 +2334,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     const l = figures[n];
     tally(n, l.status === 'SKIP' ? l.reason : null);
   }
+  // Issue #320: the fold bar is counted only where it is written, so a rig of the idle alone counts what it counted.
+  if (folds !== null) tally(FOLD_LINE, null);
   return {
     figures,
     gateHtml,
@@ -2116,7 +2348,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     problems,
     written,
     requirements: reqBlock,
-    besideIdle: isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations).filter((n) => n !== 'idle') : [],
+    besideIdle: named,
   };
 }
 
@@ -2220,7 +2452,8 @@ export function measureRequirements(inp: CheckInputs, file: RequirementsFile, bu
       if (r.kind === 'contact') line = contactLine(r, d.poses, facts);
       else if (r.kind === 'aim') line = aimLine(r, d.poses, facts);
       else if (r.kind === 'range') line = rangeLine(r, d.poses, facts);
-      else if (r.kind === 'stretch') line = stretchRequirementLine(r, d.geo.meshes, d.geo.frames, d.poses);
+      // Issue #321: the worst edge's vertices named as CHECK_TEXTURE_STRETCH names them (#314), off the rig this render posed.
+      else if (r.kind === 'stretch') line = stretchRequirementLine(r, d.geo.meshes, d.geo.frames, d.poses, (edge) => edgeBonesText(scene.rig, scene.motion, r.slot, r.attachment, edge));
       else if (r.kind === 'seam') {
         const shown = attachmentPoses(d.path, d.poses.indices.length);
         const frames: SeamFrame[] = shown.map((f) => ({ part: f.get(r.part) ?? null, neighbour: f.get(r.neighbour) ?? null }));
@@ -2378,12 +2611,24 @@ function noneHeldText(declared: readonly string[]): string {
  * figure, `declared_not_planted`, so the line never reads as though the feet
  * it names were held still. With every foot declared, the torso is measured
  * and the feet figures are an empty list and null.
+ *
+ * Issue #323: the two halves are read apart. With no `topwear` part the feet
+ * half is still measured, and with no `footwear` part the torso half is; the
+ * half that was measured decides the line, and the line says so first —
+ * `halves_measured` `1 of 2`, then each half's own status, the unmeasured one
+ * `SKIP` with its reason — so a half nobody read never passes by being silent.
+ * With neither, the line is the SKIP it was. A run that measured both halves
+ * writes the keys it always wrote.
  */
 function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], notPlanted: readonly string[] = []): JudgementLine {
   const torso = partsTagged(inp.parts, TORSO_TAGS);
   const { all: allFeet, held: feet, declared } = plantedFeet(inp.parts, notPlanted);
-  if (torso.length === 0) return skip(`no part comes from a See-through ${tagWords(TORSO_TAGS)} layer, so there is no torso to see breathe${declared.length === 0 ? '' : `; ${declared.map((n) => `"${n}"`).join(', ')} declared not planted`}`);
-  if (allFeet.length === 0) return skip(`no part comes from a See-through ${tagWords(FEET_TAGS)} layer, so there are no feet to hold still`);
+  const noTorso = `no part comes from a See-through ${tagWords(TORSO_TAGS)} layer, so there is no torso to see breathe`;
+  const noFeet = `no part comes from a See-through ${tagWords(FEET_TAGS)} layer, so there are no feet to hold still`;
+  // Issue #323: a figure without one of the two halves still has the other read; with neither, the SKIP it always was.
+  if (torso.length === 0 && feet.length === 0) return skip(`${noTorso}${declared.length === 0 ? '' : `; ${declared.map((n) => `"${n}"`).join(', ')} declared not planted`}`);
+  if (torso.length === 0) return oneHalf(inp, isolated, problems, 'feet', feet, noTorso, declared);
+  if (allFeet.length === 0) return oneHalf(inp, isolated, problems, 'torso', torso, noFeet, []);
   const H = inp.parts.rig_size[1];
   const ts = isolated('torso', torso);
   const fs = feet.length === 0 ? null : isolated('feet', feet);
@@ -2420,6 +2665,62 @@ function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], not
   };
 }
 
+/**
+ * `BREATH_VISIBLE` with one half to read (issue #323): the torso with no
+ * `footwear` part, or the feet with no `topwear` part. The half read decides
+ * the line by the bar it always had, its figures under the names they always
+ * had; the other half is `SKIP` with `reason`, and the line's first figure,
+ * `halves_measured`, says `1 of 2` — after `declared_not_planted` when the scene
+ * file declares some of the feet read (issue #231), which stays the first.
+ */
+function oneHalf(inp: FullInputs, isolated: Isolate, problems: Problem[], half: 'torso' | 'feet', ps: readonly PartRecord[], reason: string, declared: readonly string[]): JudgementLine {
+  const H = inp.parts.rig_size[1];
+  const fs = isolated(half, ps);
+  const box = frameBox(ps, H, inp.stage, fs.viewport);
+  if (box === null) return skip(`the ${half} box falls outside the idle frame, and ${reason}`);
+  const heat = regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, box);
+  if (half === 'torso') {
+    const mean = round3(heat.mean);
+    const ok = mean >= BREATH_TORSO_MEAN_FLOOR;
+    if (!ok) {
+      problems.push({
+        code: 'CHECK_BREATH_VISIBLE',
+        object: `torso ${quoteParts(ps)} rendered alone, frame box ${boxLabel(box)}; the feet half not measured: ${reason}`,
+        detail: `heat mean ${mean}/255 over the idle; >= ${BREATH_TORSO_MEAN_FLOOR} is required — the chest's breath track moves too little, or the torso is not weighted to the bone it keys`,
+      });
+    }
+    return {
+      status: ok ? 'PASS' : 'FAIL',
+      halves_measured: '1 of 2',
+      torso_status: ok ? 'PASS' : 'FAIL',
+      torso_parts: ps.map((p) => p.name),
+      torso_heat_mean: mean,
+      torso_floor: BREATH_TORSO_MEAN_FLOOR,
+      feet_status: 'SKIP',
+      feet_reason: reason,
+    };
+  }
+  const ok = heat.max <= BREATH_FEET_MAX_CEILING;
+  if (!ok) {
+    problems.push({
+      code: 'CHECK_BREATH_VISIBLE',
+      object: `feet ${quoteParts(ps)} rendered alone, frame box ${boxLabel(box)}${declared.length === 0 ? '' : ` (${declared.map((n) => `"${n}"`).join(', ')} declared not planted)`}; the torso half not measured: ${reason}`,
+      detail: `heat max ${heat.max}/255 over the idle; <= ${BREATH_FEET_MAX_CEILING} is required — the feet move: their slot rides, or their mesh is weighted to, a bone the idle keys`,
+    });
+  }
+  return {
+    status: ok ? 'PASS' : 'FAIL',
+    ...(declared.length === 0 ? {} : { declared_not_planted: [...declared] }),
+    halves_measured: '1 of 2',
+    torso_status: 'SKIP',
+    torso_reason: reason,
+    feet_status: ok ? 'PASS' : 'FAIL',
+    feet_parts: ps.map((p) => p.name),
+    feet_heat_max: heat.max,
+    feet_ceiling: BREATH_FEET_MAX_CEILING,
+  };
+}
+
 /** The scene file's exceptions to `TIP_OVER_ROOT` (issues #231, #245), and the file they were read from, which a refusal names. */
 export interface TipExceptions {
   path: string;
@@ -2453,7 +2754,8 @@ export const TIP_INSTRUMENT = 'geometry';
  * saying so, and its `rises` parts are read with the halves swapped once the
  * chain carrying each is measured to rise ({@link chainDirection}; refused by
  * name otherwise); both lists are the line's first figures. Without them the
- * line is the one written before.
+ * line is the one written before. Issue #322: the chain is read at its last
+ * link, and a declared row carries `tip_read`, the reading that let it rise.
  *
  * Issue #245: a part the scene declares `rests` — its tip at rest while its
  * root moves — is measured with the same halves and held to the opposite
@@ -2466,20 +2768,27 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
   if (swing.length === 0) return skip(`no part comes from a See-through ${tagWords(SWING_TAGS)} layer, so there is no hem or sleeve to swing`);
   const poses = attachmentPoses(geometryPath, frames);
   // Issue #231: a part declared `rises` is read up only when the chain carrying it does rise, measured at the setup pose.
+  // Issue #322: at its last link, the end the tip half is the art of; the row says what was read.
+  const risesRead = new Map<string, string>();
   if (excepted.rises.length > 0) {
     const geo = readGeometry(geometryPath, frames);
-    const origins = new Map<string, { x: number; y: number }>();
+    const origins = new Map<string, SetupBone>();
     for (const b of Array.isArray(geo?.setupBones) ? geo.setupBones : []) {
-      if (isRecord(b) && typeof b.name === 'string' && typeof b.worldX === 'number' && typeof b.worldY === 'number') origins.set(b.name, { x: b.worldX, y: b.worldY });
+      if (isRecord(b) && typeof b.name === 'string' && typeof b.worldX === 'number' && typeof b.worldY === 'number') {
+        origins.set(b.name, { x: b.worldX, y: b.worldY, ...(typeof b.a === 'number' && typeof b.c === 'number' ? { a: b.a, c: b.c } : {}) });
+      }
     }
     const refused: Problem[] = [];
     excepted.rises.forEach((name, i) => {
       const dir = chainDirection(inp.rig, inp.motion, name, origins);
-      if ('toward' in dir && dir.toward === 'up') return;
+      if ('toward' in dir && dir.toward === 'up') {
+        risesRead.set(name, dir.chains.join('; '));
+        return;
+      }
       refused.push({
         code: 'REQUIREMENTS_TIP_EXCEPTION',
         object: `${excepted.path} field "rises"[${i}]`,
-        detail: `names part "${name}", whose tip is not up: ${'none' in dir ? dir.none : `its chain runs ${dir.toward} — ${dir.chains.join('; ')}`}; a part declared rises must be carried by a chain whose last link's origin is above its first's at the setup pose`,
+        detail: `names part "${name}", whose tip is not up: ${'none' in dir ? dir.none : `its chain runs ${dir.toward} — ${dir.chains.join('; ')}`}; a part declared rises must be carried by a chain whose last link runs up at the setup pose — from its origin along its length, or, a last link with no length, from the link before's origin to its own`,
       });
     });
     refuseIfAny(refused);
@@ -2499,7 +2808,7 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
     const shown = poses.map((f) => f.get(p.name) ?? null);
     const t = halfTravels(art, p, inp.stage, shown, rises ? 'up' : 'down');
     // A part not declared writes the row it wrote before issue #231; a declared one says which half is its tip's.
-    const said = { ...(rests ? { declared: 'rests' } : {}), ...(rises ? { tip_half: tipHalf } : {}) };
+    const said = { ...(rests ? { declared: 'rests' } : {}), ...(rises ? { tip_half: tipHalf, tip_read: risesRead.get(p.name) as string } : {}) };
     if (t.root === null || t.tip === null) {
       rows.push({ part: p.name, ...said, unmeasured: shown[0] === null ? 'its slot shows no attachment on idle frame 0' : `on idle frame 0 the ${t.root === null ? rootHalf : tipHalf} half of its box holds no art its attachment draws` });
       continue;
@@ -2645,34 +2954,65 @@ function breathCarrier(
   return null;
 }
 
+/** A bone at the setup pose off the idle's geometry: its world origin, and its world x axis (a, c) when the file gives it. */
+export interface SetupBone {
+  x: number;
+  y: number;
+  a?: number;
+  c?: number;
+}
+
 /**
- * Which way the chain carrying a part runs (issue #231), for a part the scene
- * declares `rises`: the bones its attachments are bound to in the default skin
- * (a mesh's weights, or its slot's bone); the leaves among them — those with
- * no other of them below — walked up the bone tree to the first link of a
- * chain `CHAIN_LAG` reads ({@link chainFigures}: two or more rotate-keyed
- * links, each under the one before at one period); each chain so found runs
- * from its first link's setup-pose origin to its last link's
- * ({@link chainToward}). `{ none }`, the reason, when no leaf is under a chain,
- * when a chain runs as far across as along, or when the part's chains run
+ * Which way the chain carrying a part runs at its tip (issues #231, #322), for
+ * a part the scene declares `rises`: the bones its attachments are bound to in
+ * the default skin (a mesh's weights, or its slot's bone); the leaves among
+ * them — those with no other of them below — walked up the bone tree to the
+ * first link of a chain `CHAIN_LAG` reads ({@link chainFigures}: two or more
+ * rotate-keyed links, each under the one before at one period). Each chain so
+ * found is read at its **last link** ({@link chainToward}), the end
+ * `TIP_OVER_ROOT`'s tip half is the art of: from the link's setup-pose origin
+ * along its `length` in rig.json on its world x axis — the extent the rig
+ * stage turns a link to (issue #73) — or, a last link with no length, from the
+ * link before's origin to its own, the last extent the skeleton states. Until
+ * #322 it was the first link's origin to the last's, which reads a chain that
+ * hangs and then rises — a folded arm — as down, and on a two-link chain read
+ * the first link only. `{ none }`, the reason, when no leaf is under a chain,
+ * when a last link runs as far across as along, or when the part's chains run
  * different ways.
  */
-export function chainDirection(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string, origins: ReadonlyMap<string, { x: number; y: number }>): { toward: Toward; chains: string[] } | { none: string } {
+export function chainDirection(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string, origins: ReadonlyMap<string, SetupBone>): { toward: Toward; chains: string[] } | { none: string } {
   const { found, bound } = chainsCarrying(rig, motion, part);
   const boundText = [...bound].map((b) => `"${b}"`).join(', ') || 'no bone';
   if (found.length === 0) return { none: `it rides no chain: none of the bones it is bound to (${boundText}) is under a chain of rotate-keyed links` };
+  const lengths = new Map<string, number>();
+  for (const b of (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord)) if (typeof b.name === 'string' && typeof b.length === 'number' && b.length > 0) lengths.set(b.name, b.length);
   const read = found.map((c) => {
-    const a = origins.get(c[0]);
-    const z = origins.get(c[c.length - 1]);
+    const last = c[c.length - 1];
+    const before = c[c.length - 2];
     const label = c.join(' > ');
-    if (a === undefined || z === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${a === undefined ? c[0] : c[c.length - 1]} in the idle's geometry` };
-    const dx = z.x - a.x;
-    const dy = z.y - a.y;
+    const z = origins.get(last);
+    const len = lengths.get(last);
+    if (z === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${last} in the idle's geometry` };
+    let dx: number;
+    let dy: number;
+    let how: string;
+    if (len !== undefined) {
+      if (z.a === undefined || z.c === undefined) return { label, toward: null, text: `${label}: no setup-pose axis (a, c) for its last link ${last} in the idle's geometry` };
+      dx = len * z.a;
+      dy = len * z.c;
+      how = `its last link ${last}, from its origin along its length ${len},`;
+    } else {
+      const a = origins.get(before);
+      if (a === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${before} in the idle's geometry` };
+      dx = z.x - a.x;
+      dy = z.y - a.y;
+      how = `its last link ${last}, which has no length, from ${before}'s origin to its own,`;
+    }
     const toward = chainToward(dx, dy);
-    return { label, toward, text: `${label} ${toward ?? 'runs as far across as along'} (${round3(dx)}, ${round3(dy)} world px)` };
+    return { label, toward, text: `${label}: ${how} ${toward === null ? 'runs as far across as along' : `runs ${toward}`} (${round3(dx)}, ${round3(dy)} world px)` };
   });
   const ways = [...new Set(read.map((r) => r.toward))];
-  if (ways.length !== 1 || ways[0] === null) return { none: `its chains do not run one way: ${read.map((r) => r.text).join('; ')}` };
+  if (ways.length !== 1 || ways[0] === null) return { none: `its chains do not run one way at the tip: ${read.map((r) => r.text).join('; ')}` };
   return { toward: ways[0], chains: read.map((r) => r.text) };
 }