@rig-c/parts 1.7.0 → 1.9.0

package/src/assemble.ts

@@ -73,6 +73,17 @@
  *   recorded with the same `<run>:<tag>` (its pixels came from that layer).
  *   The cut is made after step 4, so the new part takes the merged pixels and
  *   every later step treats it as a part of its own.
+ * - **The owner of a pixel follows the plan** (`pixelOwners`, issue #255):
+ *   where two planned layers of one run are both opaque, the one the plan
+ *   draws in front owns the pixel for projection; the reference went by
+ *   See-through's depth alone. The proposer writes each run's parts in depth
+ *   order, so the two differ only where an author reorders a plan; on the
+ *   public examples no pixel changes owner, and they assemble to the bytes
+ *   they did.
+ * - **The drift line** (`driftBodies`, issue #255) is this port's: a part
+ *   whose `DRIFT_LIMIT` refusals hold a body another part holds in the draw
+ *   order is named, with the body and that part; the reference printed the
+ *   refused count alone.
  * - **What lies under a piece** (`cuts[].under`, `fillUnder`, issue #193) is
  *   this port's: an authored image the base takes where the cut removed its
  *   pixels, so a piece that swings away leaves no hole. The stage reads that
@@ -449,8 +460,8 @@ export interface ProjectionStats {
   taken: number;
   refused: number;
   /**
-   * Where no later layer of the run is opaque (`alpha >= 250`) in front of
-   * this one: the run's owner of the pixel is this layer or one behind it. A
+   * Where no layer of the run in front of this one (`frontOf`) owns the
+   * pixel (`pixelOwners`): the owner is this layer, one behind it, or none. A
    * pixel of this layer with alpha above 8 is VISIBLE exactly where this is
    * set, and OCCLUDED everywhere else.
    */
@@ -466,12 +477,71 @@ function maxDiff(a: Uint8ClampedArray, i: number, b: Uint8ClampedArray, j: numbe
   return Math.max(Math.abs(a[i] - b[j]), Math.abs(a[i + 1] - b[j + 1]), Math.abs(a[i + 2] - b[j + 2]));
 }
 
+/**
+ * The plan's rank of each layer of one run (issue #255): the index of the
+ * last plan entry that takes the layer from this run, or -1 for a layer no
+ * plan entry takes (an `extend_below_crop` layer included: its pixels are
+ * copied into another part, and it keeps See-through's depth).
+ */
+export function planRanks(tags: readonly string[], run: Run, plan: readonly PlanEntry[]): number[] {
+  return tags.map((tag) => {
+    let r = -1;
+    plan.forEach(([, ru, tg], i) => {
+      if (ru === run && tg === tag) r = i;
+    });
+    return r;
+  });
+}
+
+/**
+ * Whether layer `o` of a run is in front of layer `i` of the same run: by the
+ * plan when both are planned (`rank` >= 0 for both; the later plan entry is
+ * drawn in front), by See-through's depth (the run's own order) otherwise.
+ * `rank` null is depth throughout, the reference's rule.
+ */
+export function frontOf(o: number, i: number, rank: readonly number[] | null): boolean {
+  if (rank !== null && rank[o] >= 0 && rank[i] >= 0) return rank[o] > rank[i];
+  return o > i;
+}
+
+/**
+ * Who owns each rig pixel of one run, for projection (issue #255).
+ *
+ * ⚖️ Invariant: per pixel, the DEPTH owner is the run's top-most layer with
+ * alpha >= `CORE_ALPHA` there (-1: none), the reference's rule. When `rank`
+ * is given and the depth owner is a planned layer, the owner is instead the
+ * planned layer at alpha >= `CORE_ALPHA` there with the greatest rank: where
+ * two planned parts both hold a pixel, the one the plan draws in front takes
+ * it, whatever See-through's depth says. A depth owner no plan entry takes is
+ * kept — the painting there shows a layer the rig does not draw, and no
+ * planned part may take it. Where plan and depth agree the owner is the
+ * reference's, pixel for pixel.
+ */
+export function pixelOwners(rigLayers: readonly Raster[], rank: readonly number[] | null): Int32Array {
+  const n = rigLayers.length === 0 ? 0 : rigLayers[0].width * rigLayers[0].height;
+  const owner = new Int32Array(n).fill(-1);
+  for (let p = 0; p < n; p++) {
+    let depth = -1;
+    let best = -1;
+    for (let i = 0; i < rigLayers.length; i++) {
+      if (rigLayers[i].data[p * 4 + 3] < CORE_ALPHA) continue;
+      depth = i;
+      if (rank !== null && rank[i] >= 0 && (best < 0 || rank[i] > rank[best])) best = i;
+    }
+    owner[p] = rank !== null && depth >= 0 && rank[depth] >= 0 ? best : depth;
+  }
+  return owner;
+}
+
 /**
  * Step 3, over one run's layers in draw order. Modifies each rig layer's
  * colour in place and returns its counts.
  *
- * ⚖️ Invariant: a layer's CORE is where it is the top-most `alpha >= 250`
- * layer of its own run, eroded by a 5x5 square. Inside the core, the pixels
+ * ⚖️ Invariant: a layer's CORE is where it is the pixel's owner
+ * (`pixelOwners`: the top-most `alpha >= 250` layer of its own run, or, with
+ * `rank`, the planned one the plan draws in front — issue #255, not in the
+ * reference, which is the same wherever plan and depth agree), eroded by a
+ * 5x5 square. Inside the core, the pixels
  * that agree with the painting (max channel difference <= `DRIFT_LIMIT`),
  * closed by 5x5 and cut back to the core — and, for the head run, kept
  * `HEAD_WINDOW_INSET` pixels inside the head crop — are the ACCEPTED set. The
@@ -484,22 +554,20 @@ function maxDiff(a: Uint8ClampedArray, i: number, b: Uint8ClampedArray, j: numbe
  *
  * With `rule: 'visible'` (NOT in the reference) the core is the top-most
  * `alpha >= 250` set less every pixel within the 5x5 square of a pixel where a
- * LATER layer of the run is the owner — the erosion kept only along a rim with
+ * layer in front of it (`frontOf`) is the owner — the erosion kept only along a rim with
  * a neighbour in front, where the painting's pixel may be that neighbour's
  * edge. Every other step is the same. Fringe pixels (alpha below 250) are not
  * projected under either rule: the painting there is this layer blended with
  * what is behind it.
  *
- * Both rules return `clear` (no later layer is the owner) and `takenMask`, the
+ * Both rules return `clear` (no layer in front of this one, by `frontOf`, is the owner) and `takenMask`, the
  * masks the part counts in `parts.json` are derived from; `takenMask` is a
  * subset of the top-most set, and so of `clear`.
  */
-export function projectSource(rigLayers: Raster[], srcr: Raster, frame: Frame, run: Run, rule: ProjectRule = DEFAULT_PROJECT_RULE): ProjectionStats[] {
+export function projectSource(rigLayers: Raster[], srcr: Raster, frame: Frame, run: Run, rule: ProjectRule = DEFAULT_PROJECT_RULE, rank: readonly number[] | null = null): ProjectionStats[] {
   const { W, H } = frame;
-  const owner = new Int32Array(W * H).fill(-1);
-  rigLayers.forEach((r, i) => {
-    for (let p = 0; p < W * H; p++) if (r.data[p * 4 + 3] >= CORE_ALPHA) owner[p] = i;
-  });
+  const owner = pixelOwners(rigLayers, rank);
+  const inFront = (o: number, i: number): boolean => frontOf(o, i, rank);
   let win: Mask | null = null;
   if (run === 'head') {
     win = newMask(W, H);
@@ -516,7 +584,7 @@ export function projectSource(rigLayers: Raster[], srcr: Raster, frame: Frame, r
     const takenMask = newMask(W, H);
     let anyTop = false;
     for (let p = 0; p < W * H; p++) {
-      if (owner[p] <= i) clear.data[p] = 1;
+      if (owner[p] === -1 || owner[p] === i || !inFront(owner[p], i)) clear.data[p] = 1;
       if (owner[p] === i && r.data[p * 4 + 3] >= CORE_ALPHA) {
         top.data[p] = 1;
         anyTop = true;
@@ -527,7 +595,7 @@ export function projectSource(rigLayers: Raster[], srcr: Raster, frame: Frame, r
     if (rule === 'core') core = erode(top, CORE_KERNEL);
     else {
       const front = newMask(W, H);
-      for (let p = 0; p < W * H; p++) if (owner[p] > i) front.data[p] = 1;
+      for (let p = 0; p < W * H; p++) if (owner[p] >= 0 && owner[p] !== i && inFront(owner[p], i)) front.data[p] = 1;
       const rim = dilate(front, CORE_KERNEL);
       core = newMask(W, H);
       for (let p = 0; p < W * H; p++) if (top.data[p] === 1 && rim.data[p] === 0) core.data[p] = 1;
@@ -1602,6 +1670,8 @@ export interface AssembleResult {
   cuts: CutCount[];
   /** The full-run layers the plan does not take from the full run whose uncovered error holds a body (`uncoveredErrorLayers`); empty otherwise. */
   uncovered: UncoveredErrorLayer[];
+  /** The parts whose `DRIFT_LIMIT` refusals hold a body another part holds in the draw order (`driftBodies`), in draw order; empty otherwise. */
+  drift: DriftBodies[];
   seamRule: SeamRule;
   projectRule: ProjectRule;
 }
@@ -1664,7 +1734,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     const layers = runLayers(set, input.resolution);
     if (run === 'full') fullTags.push(...layers.filter((l) => l.opaqueRunPx > 0).map((l) => l.tag));
     const rigLayers = layers.map((l) => layerToRig(l.canvas, frame, run));
-    const st = projectSource(rigLayers, srcr, frame, run, projectRule);
+    const st = projectSource(rigLayers, srcr, frame, run, projectRule, planRanks(layers.map((l) => l.tag), run, plan));
     layers.forEach((l, i) => {
       rig.set(`${run}:${l.tag}`, rigLayers[i]);
       stats.set(`${run}:${l.tag}`, st[i]);
@@ -1958,6 +2028,23 @@ export function assemble(input: AssembleInput): AssembleResult {
     return { record: whole, image: b.r };
   });
   const pushedBy = pushBackFringe(stack, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null);
+  // Issue #255: a part's drift refusals in a body, and who holds the body in the draw order (the push-back clears
+  // only fringe below CORE_ALPHA, and the seam override only recolours, so the holders read here are final).
+  const holderAt = new Int32Array(W * H).fill(-1);
+  stack.forEach(({ image }, i) => {
+    for (let p = 0; p < W * H; p++) if (image.data[p * 4 + 3] >= CORE_ALPHA) holderAt[p] = i;
+  });
+  const stackNames = stack.map((q) => q.record.name);
+  const drift: DriftBodies[] = [];
+  order.forEach((d) => {
+    if ('patch' in d) return;
+    const { name, b } = pieceAt(d);
+    if (b.st.refusedMask === null) return;
+    const refused = newMask(W, H);
+    for (let p = 0; p < W * H; p++) if (b.st.refusedMask.data[p] === 1 && (b.region === null || b.region.data[p] === 1)) refused.data[p] = 1;
+    const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames);
+    if (found !== null) drift.push(found);
+  });
   const pushedOf: FringePushed[][] = plan.map(() => []);
   const pushedOfCut: FringePushed[][] = cuts.map(() => []);
   order.forEach((d, i) => {
@@ -2048,11 +2135,99 @@ export function assemble(input: AssembleInput): AssembleResult {
     figures,
     cuts: cutCounts,
     uncovered,
+    drift,
     seamRule,
     projectRule,
   };
 }
 
+// ---------------------------------------------------------------------------
+// refused bodies: a part whose layer is not what the painting shows (issue #255)
+// ---------------------------------------------------------------------------
+
+/** A part whose `DRIFT_LIMIT` refusals hold a body, and which parts the draw order puts there. */
+export interface DriftBodies {
+  /** The part, and its `<run>:<tag>`. */
+  part: string;
+  from: string;
+  /** The part's `refused_drift_px`, in a body or not. */
+  refusedPx: number;
+  /** The bar the bodies were held to (`bodyMinPx`, the uncovered line's). */
+  minPx: number;
+  /** The bodies, largest first (`bodiesOf`). */
+  bodies: UncoveredBody[];
+  /**
+   * Over every pixel of the bodies, the part that holds it in the draw order
+   * — the top-most at alpha >= `CORE_ALPHA`, as the seam pass reads a holder
+   * (`seamCandidates`) — with its pixel count, most first, then by name.
+   */
+  holders: Array<{ part: string; px: number }>;
+}
+
+/**
+ * A part's refused bodies that another part holds in the draw order (issue
+ * #255).
+ *
+ * ⚖️ Invariant: `refused` is the part's projection core pixels whose layer
+ * colour is more than `DRIFT_LIMIT` off the painting (`projectSource`'s
+ * `refusedMask`, cut to the part's region); its bodies are `bodiesOf(refused,
+ * minPx)` — the pixels that survive a `BODY_KERNEL` opening, in 8-connected
+ * components of at least `minPx` — the same reading of "a body" as an
+ * uncovered layer's, and the stage passes the same bar (`bodyMinPx`).
+ * `holderAt` is, per rig pixel, the index into `names` of the top-most part
+ * at alpha >= `CORE_ALPHA` in draw order (-1: none), as the seam pass reads a
+ * holder. The result is non-null exactly when the bodies hold a pixel whose
+ * holder is another part: the plan draws that part over the body, which is
+ * the signature of "this layer is not the owner here".
+ *
+ * Not every body: a body the part holds itself, with nothing drawn over it,
+ * is See-through's colour for the part's own pixels disagreeing with the
+ * painting, and on four of the five public paintings it holds bodies of
+ * hundreds to tens of thousands of pixels that no other part touches (the
+ * pull request that added this has the figures); a line there would name no
+ * owner, which is what the line exists to name.
+ */
+export function driftBodies(part: string, from: string, refused: Mask, minPx: number, holderAt: Int32Array, names: readonly string[]): DriftBodies | null {
+  let refusedPx = 0;
+  for (let p = 0; p < refused.data.length; p++) refusedPx += refused.data[p];
+  if (refusedPx === 0) return null;
+  const { bodies, pixels } = bodiesWithPixels(refused, minPx);
+  if (bodies.length === 0) return null;
+  const count = new Map<string, number>();
+  for (let p = 0; p < pixels.data.length; p++) {
+    if (pixels.data[p] === 0 || holderAt[p] < 0) continue;
+    const n = names[holderAt[p]];
+    count.set(n, (count.get(n) ?? 0) + 1);
+  }
+  if (![...count.keys()].some((n) => n !== part)) return null;
+  const holders = [...count.entries()].map(([q, px]) => ({ part: q, px })).sort((a, b) => b.px - a.px || (a.part < b.part ? -1 : a.part > b.part ? 1 : 0));
+  return { part, from, refusedPx, minPx, bodies, holders };
+}
+
+/**
+ * One `drift` line under the `uncovered` lines: the part, its refused pixels,
+ * their bodies, and the parts the plan's draw order puts on them —
+ * `drift: "topwear" refuses 196 px of full:topwear (its colour more than 90
+ * off the painting, max channel), in a body of 196 px at 16,12 14x14 (at
+ * least 150 px past a 5x5 opening); by the plan's draw order "face" holds 196
+ * px of it (the top-most part at alpha >= 250), drawn in front of "topwear"`.
+ */
+export function driftLine(d: DriftBodies): string {
+  const total = d.bodies.reduce((a, b) => a + b.px, 0);
+  const big = d.bodies[0];
+  const held = d.bodies.length > 1 ? `${d.bodies.length} bodies of ${total} px, the largest ${big.px} px at ${bodyBox(big)}` : `a body of ${big.px} px at ${bodyBox(big)}`;
+  const others = d.holders.filter((h) => h.part !== d.part).map((h) => `"${h.part}"`);
+  return (
+    `drift: "${d.part}" refuses ${d.refusedPx} px of ${d.from} (its colour more than ${DRIFT_LIMIT} off the painting, max channel), in ${held} (at least ${fmtPx(d.minPx)} px past a ${BODY_KERNEL}x${BODY_KERNEL} opening); ` +
+    `by the plan's draw order ${d.holders.map((h) => `"${h.part}" holds ${h.px} px`).join(', ')} of it (the top-most part at alpha >= ${CORE_ALPHA}), ${others.join(', ')} drawn in front of "${d.part}"`
+  );
+}
+
+/** A rig-pixel bar as the lines print it: a whole number as it is, otherwise to one decimal. */
+function fmtPx(n: number): string {
+  return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+
 // ---------------------------------------------------------------------------
 // uncovered bodies: a full-run layer the plan leaves out (issue #233)
 // ---------------------------------------------------------------------------
@@ -2104,12 +2279,20 @@ export interface UncoveredLayer {
  * the box's top row and left column.
  */
 export function bodiesOf(mask: Mask, minPx: number): UncoveredBody[] {
+  return bodiesWithPixels(mask, minPx).bodies;
+}
+
+/** `bodiesOf`, and the mask of every pixel that lies in one of the bodies it returns. */
+export function bodiesWithPixels(mask: Mask, minPx: number): { bodies: UncoveredBody[]; pixels: Mask } {
   const opened = dilate(erode(mask, BODY_KERNEL), BODY_KERNEL);
   for (let p = 0; p < opened.data.length; p++) if (mask.data[p] === 0) opened.data[p] = 0;
   const cc = connectedComponents(opened, 8);
-  const all = cc.stats.slice(1).filter((s) => s.area > 0 && s.area >= minPx);
+  const keep = cc.stats.map((s, l) => l > 0 && s.area > 0 && s.area >= minPx);
+  const all = cc.stats.filter((s, l) => keep[l]);
   all.sort((a, b) => b.area - a.area || a.top - b.top || a.left - b.left);
-  return all.map((s) => ({ px: s.area, x: s.left, y: s.top, w: s.width, h: s.height }));
+  const pixels = newMask(mask.width, mask.height);
+  for (let p = 0; p < pixels.data.length; p++) if (keep[cc.labels[p]]) pixels.data[p] = 1;
+  return { bodies: all.map((s) => ({ px: s.area, x: s.left, y: s.top, w: s.width, h: s.height })), pixels };
 }
 
 /** A body's box as the hole lines print one: `x,y wxh`. */

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, driftLine, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, stimulusMotion, withStimulus } from './automotion.ts';
@@ -82,7 +82,8 @@ import { type PartRecord, readParts, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
-import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, type StrayCleared } from './rig.ts';
+import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, type StrayCleared, type TurnRow } from './rig.ts';
+import { TURN_BONE } from './turn.ts';
 import { pyRound } from './round.ts';
 
 /** Where a stage's lines go. The commands hand it `console.log`; `build` hands it a prefixing wrapper. */
@@ -230,6 +231,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   log(figuresLine(result.figures));
   for (const l of holeLines(result.figures)) log(l);
   for (const u of result.uncovered) log(uncoveredLine(u));
+  for (const d of result.drift) log(driftLine(d));
   log(`wrote ${outs.partsJson}, ${result.images.length} PNG(s) in ${outs.partsDir}, ${outs.recomposite}, ${outs.errorMap} (uncovered error px red, covered error px blue, the painting grey)`);
   return result;
 }
@@ -821,6 +823,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
   );
   if (from !== null) log(`  animations beside the idle, from ${from.file} as written: ${Object.keys(from.table).join(', ') || 'none'}`);
   log(faceAxisLine(rig.faceAxis));
+  if (rig.turn !== null) log(turnLine(rig.turn));
   log(
     rig.idleKeys === 'ctl'
       ? `  idle keys ctl: ${rig.meshKeyed.length} mesh-driving bone(s) keyed by the idle, each keyed through a same-origin <bone>_ctl parent`
@@ -946,7 +949,9 @@ export function barsSummary(r: CheckReport): string {
 /**
  * The rig stage's face-axis line (issue #239): the eye line's angle, the parts it runs between and the face bones
  * turned to it, or why there is no line and the face bones keep the page's axes — the note a one-eyed painting gets.
- * With a line it also names the `invariants.axes` entry written for rigc's A51, its tolerance, or why none was.
+ * With a line it also names the `invariants.axes` entry written for rigc's A51, its tolerance, or why none was; and
+ * the entry holding the face bones whose own tip lies along the line, or each such bone with why it is not held
+ * (issue #258) — a face with no entry is never silent.
  */
 export function faceAxisLine(f: FaceAxis): string {
   const own = f.ownTip.length === 0 ? '' : `; ${f.ownTip.join(', ')} ${f.ownTip.length === 1 ? 'takes its' : 'take their'} own tip`;
@@ -958,7 +963,25 @@ export function faceAxisLine(f: FaceAxis): string {
       : f.noAxis !== null
         ? `; no invariants.axes entry: ${f.noAxis}`
         : '';
-  return `  face axis: ${pyRound(f.degrees, 6)} degrees, the line through the eye bones eye_r and eye_l (on ${f.parts[0]} and ${f.parts[1]}); ${turned}${own}${held}`;
+  // Issue #258: the tipped face bones are held in an entry of their own, or each is named with why it is not.
+  const tips =
+    f.noAxis !== null && f.turned.length === 0
+      ? ''
+      : `${f.tipAxis === null ? '' : `; invariants.axes "${f.tipAxis.name}" holds ${f.tipAxis.bones.join(', ')}, whose own tips lie along the line within whole-pixel rounding, tolerance ${f.tipAxis.tolerance} degrees (rigc's A51)`}${f.tipOff.map((t) => `; ${t}`).join('')}`;
+  // Issue #250: the slotless bone carrying the face's up axis under head, or why there is none.
+  const up = f.headUp !== null ? `; head_up under head along the face's up axis, ${f.headUp.rotation} degrees, ${f.headUp.length} px (head's origin to the eye midpoint along it)` : f.headUpNone !== null ? `; no head_up: ${f.headUpNone}` : '';
+  return `  face axis: ${pyRound(f.degrees, 6)} degrees, the line through the eye bones eye_r and eye_l (on ${f.parts[0]} and ${f.parts[1]}); ${turned}${own}${held}${tips}${up}`;
+}
+
+/**
+ * The rig stage's turn line (issue #251): the control, and per carried part its fraction, the depth it came from and
+ * how many twins carry it — a part at the pivot depth said to stay. Printed only when the config has `turn`.
+ */
+export function turnLine(rows: readonly TurnRow[]): string {
+  const carried = rows.filter((r) => r.twins.length > 0);
+  const twins = carried.reduce((n, r) => n + r.twins.length, 0);
+  const parts = rows.map((r) => (r.twins.length === 0 ? `${r.part} stays (depth ${r.depth}, the pivot's)` : `${r.part} ${r.fraction} (depth ${r.depth}, ${r.twins.length} twin(s))`));
+  return `  turn: control "${TURN_BONE}" under root, keyed by nothing; ${carried.length} part(s) carried by ${carried.length} transform constraint(s) over ${twins} twin bone(s), each part's x a fraction of the control's: ${parts.join(', ')}`;
 }
 
 /** A judgement line as the console prints it: its name, its status, then its figures and bars as check.json holds them (a SKIP prints its reason). */

package/src/check.ts

@@ -68,14 +68,15 @@
  * was that for every rig it ever saw); the grey is read from rigc's
  * `frames.json` rather than typed; the crop-to-world map comes from the rig's
  * own stage box through `src/coords.ts` rather than an open-coded `-W/2`; and
- * the last idle frame is refused unless it sits at t = duration.
+ * the last idle frame is refused unless it sits at t = duration (within
+ * `TIME_SLACK`, issue #244).
  */
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { measureRecomposite, type RecompositeFigures, recompositeRecord, sourceInRig } from './assemble.ts';
 import { cropToSpineY } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
-import { framesInside, IDLE_FPS } from './motion.ts';
+import { framesInside, IDLE_FPS, TIME_SLACK } from './motion.ts';
 import {
   blinkFigures,
   type GeometryPose,
@@ -1816,12 +1817,14 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     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];
-    if (idle.stride !== 1 || idle.written !== idle.sampled || idle.duration !== inp.idleDuration || last.index !== idle.sampled - 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 and every frame written are required`,
+          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`,
         },
       ]);
     }
@@ -2447,10 +2450,17 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
     rows.push({ part: p.name, ...said, root_rig_px: round3(t.root), tip_rig_px: round3(t.tip), ratio });
     if (!ok) {
       failed = true;
+      // Issue #262: a root the breath carries is named with its carrier, not blamed on the chain.
+      const carry = breathCarrier(inp.rig, inp.motion, p.name, geometryPath, frames, { art, box: p, stage: inp.stage, shown, toward: rises ? 'up' : 'down', root: t.root, tip: t.tip });
+      if (carry !== null) rows[rows.length - 1] = { ...rows[rows.length - 1], carried_by: carry.bone, breath_rig_px: round3(carry.breath), root_without_breath_rig_px: round3(carry.root), tip_without_breath_rig_px: round3(carry.tip) };
+      const why =
+        carry === null
+          ? "the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain"
+          : `the root travels with the breath (${round3(t.root)} px of ${round3(carry.breath)} px): it is carried by \`${carry.bone}\`, which moves it more than the tip; with \`${carry.keyed}\`'s translate held still the root travels ${round3(carry.root)} rig px and the tip ${round3(carry.tip)}, which the bar passes (ratio ${carry.root > 0 ? round3(carry.tip / carry.root) : 'undefined: the root moves only with it'}) — bind the root to the bone the part hangs from, not to \`${carry.bone}\``;
       problems.push({
         code: 'CHECK_TIP_OVER_ROOT',
         object: `part "${p.name}", box ${p.x},${p.y} ${p.w}x${p.h} rig px, posed by the idle's geometry${rises ? ', declared rises' : ''}`,
-        detail: `the art in its ${tipHalf} half travels ${round3(t.tip)} rig px and in its ${rootHalf} half ${round3(t.root)} rig px (ratio ${ratio ?? 'undefined: nothing moves'}); a ratio >= ${TIP_RATIO_FLOOR} is required — the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain`,
+        detail: `the art in its ${tipHalf} half travels ${round3(t.tip)} rig px and in its ${rootHalf} half ${round3(t.root)} rig px (ratio ${ratio ?? 'undefined: nothing moves'}); a ratio >= ${TIP_RATIO_FLOOR} is required — ${why}`,
       });
     }
   }
@@ -2462,6 +2472,110 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
   return { status: failed ? 'FAIL' : 'PASS', ...declared, instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR };
 }
 
+/**
+ * The bones a part's attachments are bound to in the default skin (issue #231): a mesh's weights, or its slot's
+ * bone for an attachment that carries no weights.
+ */
+function boundBones(rig: Record<string, unknown>, part: string): Set<string> {
+  const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((sl) => sl.name === part);
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
+  const bound = new Set<string>();
+  for (const a of atts) {
+    if (isRecord(a) && Array.isArray(a.weights)) for (const v of a.weights) for (const w of Array.isArray(v) ? v : []) if (isRecord(w) && typeof w.bone === 'string') bound.add(w.bone);
+    if (!(isRecord(a) && Array.isArray(a.weights)) && slot !== undefined && typeof slot.bone === 'string') bound.add(slot.bone);
+  }
+  return bound;
+}
+
+/** The idle track properties that move a bone without turning it: the breath is one of these (issue #262). */
+const BREATH_PROPS: readonly string[] = ['translate', 'translatex', 'translatey'];
+
+/**
+ * The bone a failing part's root travels with, when that is the breath's (issue #262). The breath is every idle
+ * track that translates a bone ({@link BREATH_PROPS}), each read on its own: `K` the bone it keys. Its motion is
+ * `K`'s world origin less where `K`'s parent carries `K`'s setup position, frame by frame — what the translate keys
+ * add — and the breath's travel is that, less its frame-0 value, at its largest. The part (one weighted mesh; a
+ * region is carried whole and cannot stretch) is posed again with that motion taken out of every vertex in
+ * proportion to its weight on `K` and the bones under it, and its halves measured as {@link halfTravels} measures
+ * them. The root travels with the breath when the breath adds more to the root's travel than to the tip's and, held
+ * still, the halves pass the bar: tip >= {@link TIP_RATIO_FLOOR} x root, the tip above 0 at the line's precision
+ * (round3). The margin is the bar's own, so the line names the carrier exactly when the breath is what fails it;
+ * the carrier named is the bone the part is bound to ({@link boundBones}) at or under `K` that no other such bone is
+ * above (the sleeve's links ride `chest`, which is the carrier). Null otherwise.
+ */
+function breathCarrier(
+  rig: Record<string, unknown>,
+  motion: Record<string, unknown>,
+  part: string,
+  geometryPath: string,
+  frames: number,
+  m: { art: ArtMask; box: { x: number; y: number; w: number; h: number }; stage: StageBox; shown: ReadonlyArray<PosedAttachment | null>; toward: 'down' | 'up'; root: number; tip: number },
+): { bone: string; keyed: string; breath: number; root: number; tip: number } | null {
+  const anims = isRecord(motion.animations) ? motion.animations : {};
+  const idle = isRecord(anims.idle) ? anims.idle : {};
+  const keyed = [...new Set((Array.isArray(idle.tracks) ? idle.tracks : []).filter(isRecord).filter((t) => typeof t.bone === 'string' && typeof t.property === 'string' && BREATH_PROPS.includes(t.property)).map((t) => String(t.bone)))];
+  if (keyed.length === 0) return null;
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
+  const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  const setupAt = new Map(bones.map((b) => [String(b.name), [typeof b.x === 'number' ? b.x : 0, typeof b.y === 'number' ? b.y : 0] as const]));
+  const atOrUnder = (b: string, anc: string): boolean => {
+    const seen = new Set<string>();
+    for (let x: string | null = b; x !== null && !seen.has(x); x = parent.get(x) ?? null) {
+      if (x === anc) return true;
+      seen.add(x);
+    }
+    return false;
+  };
+  // The one weighted mesh the part draws, its weights in the order of the geometry's vertices.
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
+  const first = m.shown[0];
+  if (atts.length !== 1 || first === null || first === undefined) return null;
+  const att = atts[0];
+  if (!isRecord(att) || !Array.isArray(att.weights) || att.weights.length * 2 !== first.rest.length) return null;
+  const weights = att.weights.map((v) => (Array.isArray(v) ? v.filter(isRecord).filter((w) => typeof w.bone === 'string' && typeof w.weight === 'number') : []));
+  const geo = readGeometry(geometryPath, frames);
+  if (geo === null) return null;
+  const world = (bs: unknown, name: string): BoneWorld | null => {
+    const b = Array.isArray(bs) ? bs.filter(isRecord).find((x) => x.name === name) : undefined;
+    if (b === undefined) return null;
+    const f = [b.a, b.b, b.c, b.d, b.worldX, b.worldY];
+    if (!f.every((v) => typeof v === 'number' && Number.isFinite(v))) return null;
+    return { a: b.a as number, b: b.b as number, c: b.c as number, d: b.d as number, worldX: b.worldX as number, worldY: b.worldY as number };
+  };
+  const bound = [...boundBones(rig, part)];
+  for (const k of keyed) {
+    const under = bound.filter((b) => atOrUnder(b, k));
+    const carrier = under.find((b) => !under.some((o) => o !== b && atOrUnder(b, o)));
+    if (carrier === undefined) continue;
+    // What the translate keys add to K's world origin, frame by frame, less frame 0's.
+    const [lx, ly] = setupAt.get(k) ?? [0, 0];
+    const pk = parent.get(k) ?? null;
+    const added: Array<[number, number] | null> = geo.frameBones.map((bs) => {
+      const w = world(bs, k);
+      if (w === null) return null;
+      const pw = pk === null ? { a: 1, b: 0, c: 0, d: 1, worldX: 0, worldY: 0 } : world(bs, pk);
+      if (pw === null) return null;
+      return [w.worldX - (pw.a * lx + pw.b * ly + pw.worldX), w.worldY - (pw.c * lx + pw.d * ly + pw.worldY)];
+    });
+    const a0 = added[0];
+    if (a0 === null || added.some((d) => d === null)) continue;
+    const delta = (added as Array<[number, number]>).map(([x, y]) => [x - a0[0], y - a0[1]] as const);
+    const breath = Math.max(...delta.map(([x, y]) => Math.hypot(x, y)));
+    if (!(breath > 0)) continue;
+    const share = weights.map((v) => v.filter((w) => atOrUnder(String(w.bone), k)).reduce((s, w) => s + (w.weight as number), 0));
+    const held = m.shown.map((f, i) => (f === null ? null : { rest: f.rest, triangles: f.triangles, posed: f.posed.map((v, j) => v - share[j >> 1] * delta[i][j & 1]) }));
+    const t = halfTravels(m.art, m.box, m.stage, held, m.toward);
+    if (t.root === null || t.tip === null) continue;
+    if (!(m.root - t.root > m.tip - t.tip) || round3(t.tip) === 0 || !(t.tip >= TIP_RATIO_FLOOR * t.root)) continue;
+    return { bone: carrier, keyed: k, breath, root: t.root, tip: t.tip };
+  }
+  return null;
+}
+
 /**
  * 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
@@ -2477,15 +2591,7 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
 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 } {
   const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
   const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
-  const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((sl) => sl.name === part);
-  const skins = isRecord(rig.skins) ? rig.skins : {};
-  const skin = isRecord(skins.default) ? skins.default : {};
-  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
-  const bound = new Set<string>();
-  for (const a of atts) {
-    if (isRecord(a) && Array.isArray(a.weights)) for (const v of a.weights) for (const w of Array.isArray(v) ? v : []) if (isRecord(w) && typeof w.bone === 'string') bound.add(w.bone);
-    if (!(isRecord(a) && Array.isArray(a.weights)) && slot !== undefined && typeof slot.bone === 'string') bound.add(slot.bone);
-  }
+  const bound = boundBones(rig, part);
   const under = (b: string, anc: string): boolean => {
     const seen = new Set<string>();
     for (let x = parent.get(b) ?? null; x !== null && !seen.has(x); x = parent.get(x) ?? null) {