@rig-c/parts 1.6.0 → 1.8.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';
@@ -70,7 +70,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { BARS, besideIdleLine, causeLines, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { BARS, besideIdleLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
 import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
@@ -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 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 } from './rig.ts';
+import { pyRound } from './round.ts';
 
 /** Where a stage's lines go. The commands hand it `console.log`; `build` hands it a prefixing wrapper. */
 export type Log = (line: string) => void;
@@ -229,6 +230,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;
 }
@@ -819,6 +821,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
     `  bones ${rig.rig.bones.length} (${rig.controls.length} control) slots ${rig.rig.slots.length} meshes ${rig.meshReport.length} regions ${regions} vertices ${vertices}; idle ${rig.motion.animations.idle.duration} s, ${tracks.length} track(s), ${keys} key(s)`,
   );
   if (from !== null) log(`  animations beside the idle, from ${from.file} as written: ${Object.keys(from.table).join(', ') || 'none'}`);
+  log(faceAxisLine(rig.faceAxis));
   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`
@@ -941,6 +944,33 @@ export function barsSummary(r: CheckReport): string {
   return `${measured.length} of ${BARS.length} bar(s) measured, ${skipped.length} skipped${skipped.length === 0 ? '' : ` (${skipped.map((s) => s.bar).join(', ')})`}`;
 }
 
+/**
+ * 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; 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`;
+  if (f.degrees === null) return `  face axis: none — ${f.none}; ${f.ownTip.length === 0 ? 'the face bones keep' : 'the other face bones keep'} the page's axes${own}`;
+  const turned = f.turned.length === 0 ? 'no face bone to turn' : `${f.turned.join(', ')} turned to it`;
+  const held =
+    f.axis !== null
+      ? `; invariants.axes "${f.axis.name}" holds ${f.axis.bones.join(', ')} to the line through ${f.axis.through.join(' -> ')}, tolerance ${f.axis.tolerance} degrees (rigc's A51)`
+      : f.noAxis !== null
+        ? `; no invariants.axes entry: ${f.noAxis}`
+        : '';
+  // 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}`;
+}
+
 /** 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). */
 export function judgementLine(name: string, line: JudgementLine | ReportedLine): string {
   if (line.status === 'SKIP') return `${name}: SKIP — ${String(line.reason)}`;
@@ -1027,19 +1057,141 @@ export interface LoopResult {
   error: PaletteError | null;
 }
 
+/**
+ * The idle `build --loop --lead-in <n>` renders (issue #224's follow-up):
+ * `idle` played n + 1 times back to back, of which the loop keeps the last
+ * period. rigc's render resets physics at frame 0, so an idle whose rig
+ * carries a physics constraint does not end where it starts; played on, a
+ * spring the idle drives settles into the idle's period, and the last period
+ * of the run is that steady state.
+ */
+export const LEAD_IN_ANIMATION = 'idle_lead_in';
+
+/** Which frames of a lead-in run the loop keeps: the last of `periods + 1` periods. */
+export interface LoopWindow {
+  periods: number;
+}
+
+const LEAD_IN_ANIMATION_KEYS = ['duration', 'loop', 'note', 'tracks'];
+
+/**
+ * `motion` with {@link LEAD_IN_ANIMATION} added: every idle track's keys
+ * repeated `periods + 1` times, each copy shifted by one idle duration, its
+ * Bezier `curve` times with it, and the key at the end of a copy dropped for
+ * the next copy's first key at the same time. Refused by name
+ * (`LOOP_LEAD_IN_IDLE`), every problem at once, when the motion has no idle,
+ * already has an animation of that name, or the idle is not a loop this can
+ * repeat without inventing a value: a field besides duration, loop, note and
+ * tracks; a track whose keys do not start at 0 and end at the duration; or one
+ * whose last value is not its first.
+ */
+export function repeatIdle(motion: Record<string, unknown>, periods: number): Record<string, unknown> {
+  const problems: Problem[] = [];
+  const fail = (object: string, detail: string): void => {
+    problems.push({ code: 'LOOP_LEAD_IN_IDLE', object, detail });
+  };
+  const anims = motion.animations;
+  const table = typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? (anims as Record<string, unknown>) : null;
+  const idle = table?.idle;
+  if (table === null || typeof idle !== 'object' || idle === null || Array.isArray(idle)) {
+    fail('motion.json animations.idle', 'is absent; the lead-in repeats the idle');
+    refuseIfAny(problems);
+  }
+  const t = table as Record<string, unknown>;
+  const a = idle as Record<string, unknown>;
+  if (LEAD_IN_ANIMATION in t) fail(`motion.json animations.${LEAD_IN_ANIMATION}`, 'exists; the lead-in writes an animation of that name and never replaces one');
+  for (const k of Object.keys(a)) if (!LEAD_IN_ANIMATION_KEYS.includes(k)) fail(`motion.json animations.idle.${k}`, `is a field the lead-in does not repeat; the idle it repeats holds ${LEAD_IN_ANIMATION_KEYS.join(', ')}`);
+  const d = a.duration;
+  if (typeof d !== 'number' || !(d > 0)) fail('motion.json animations.idle.duration', `is ${JSON.stringify(d)}; a positive number is required`);
+  const tracks = Array.isArray(a.tracks) ? a.tracks : [];
+  const duration = d as number;
+  const out: unknown[] = [];
+  tracks.forEach((track, i) => {
+    const tr = track as Record<string, unknown>;
+    const keys = Array.isArray(tr.keys) ? (tr.keys as Array<Record<string, unknown>>) : [];
+    const at = `motion.json animations.idle.tracks[${i}]`;
+    const first = keys[0];
+    const last = keys[keys.length - 1];
+    if (first === undefined || first.t !== 0 || last.t !== duration) {
+      fail(at, `keys run from ${String(first?.t)} to ${String(last?.t)}; a track the lead-in repeats starts at 0 and ends at the duration ${duration}`);
+      return;
+    }
+    if (JSON.stringify(first.v) !== JSON.stringify(last.v)) {
+      fail(at, `ends at ${JSON.stringify(last.v)} and starts at ${JSON.stringify(first.v)}; repeated, the idle would jump where one copy meets the next`);
+      return;
+    }
+    const repeated: Array<Record<string, unknown>> = [];
+    for (let r = 0; r <= periods; r++) {
+      const shift = r * duration;
+      keys.forEach((k, j) => {
+        if (r < periods && j === keys.length - 1) return;
+        const moved: Record<string, unknown> = { ...k, t: (k.t as number) + shift };
+        if (Array.isArray(k.curve)) moved.curve = (k.curve as number[]).map((c, n) => (n % 2 === 0 ? c + shift : c));
+        repeated.push(moved);
+      });
+    }
+    out.push({ ...tr, keys: repeated });
+  });
+  refuseIfAny(problems);
+  return { ...motion, animations: { ...t, [LEAD_IN_ANIMATION]: { duration: duration * (periods + 1), loop: false, tracks: out } } };
+}
+
+/**
+ * Render {@link LEAD_IN_ANIMATION} of the rig in `rigDir` as `check` renders
+ * the idle (the packed build, `IDLE_FPS`, `IDLE_MAX_PX`), every other
+ * animation kept so the viewport is fitted as for the idle frames. Writes
+ * under `dir` and returns the frame set's directory.
+ */
+export function leadInFrames(rigDir: string, dir: string, periods: number, rigc: RigcRunner, mode: PackMode): string {
+  const rig = JSON.parse(readFileSync(join(rigDir, 'rig.json'), 'utf8')) as Record<string, unknown>;
+  const motion = repeatIdle(JSON.parse(readFileSync(join(rigDir, 'motion.json'), 'utf8')) as Record<string, unknown>, periods);
+  const images = typeof rig.images === 'string' ? resolve(rigDir, rig.images) : rig.images;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'rig.json'), JSON.stringify({ ...rig, images }));
+  writeFileSync(join(dir, 'motion.json'), JSON.stringify(motion));
+  const what = `the idle played ${periods + 1} times (${LEAD_IN_ANIMATION})`;
+  const b = rigc(['build', '--rig', join(dir, 'rig.json'), '--motion', join(dir, 'motion.json'), '--out', join(dir, 'build'), ...packedBuildArgs(mode)]);
+  if (b.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (${what})`, b, buildGateLines(b.out)));
+  const r = rigc(['render', '--candidate', join(dir, 'build'), '--animation', LEAD_IN_ANIMATION, '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--out', join(dir, 'frames')]);
+  if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation ${LEAD_IN_ANIMATION} (${what})`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+  return join(dir, 'frames');
+}
+
+/** Pixels whose largest RGB channel difference between `a` and `b` is above `level`. */
+function pixelsOver(a: Raster, b: Raster, level: number): number {
+  let n = 0;
+  for (let p = 0; p < a.width * a.height; p++) {
+    let m = 0;
+    for (let c = 0; c < 3; c++) m = Math.max(m, Math.abs(a.data[p * 4 + c] - b.data[p * 4 + c]));
+    if (m > level) n++;
+  }
+  return n;
+}
+
 /**
  * Encode a rigc frame set as a looping APNG, indexed APNG or GIF and write it.
  * An encoder refusal is a PartsError coded `LOOP_ENCODE`, so it prints like
  * every other.
  */
-export function loopStage(frames: string, out: string, format: LoopFormat, log: Log): LoopResult {
+export function loopStage(frames: string, out: string, format: LoopFormat, log: Log, window?: LoopWindow): LoopResult {
   const set = readFrameSet(frames);
   const images = set.frames.map((fr) => fr.image);
   log(`rig-parts loop: ${set.dir} -> ${out}`);
   log(`  ${images.length} frame(s) ${images[0]?.width ?? 0}x${images[0]?.height ?? 0} at ${set.fps} fps (from frames.json), animation ${set.animation ?? '(none)'}`);
   let used = images;
   const lastName = set.frames[set.frames.length - 1]?.name ?? '';
-  if (images.length > 1 && sameRgba(images[0].data, images[images.length - 1].data)) {
+  if (window !== undefined) {
+    const per = (images.length - 1) / (window.periods + 1);
+    if (!Number.isInteger(per) || per < 1) {
+      throw new PartsError([{ code: 'LOOP_LEAD_IN_IDLE', object: set.dir, detail: `holds ${images.length} frame(s), which is not ${window.periods + 1} whole period(s) and the end frame; the lead-in keeps the last period` }]);
+    }
+    const start = window.periods * per;
+    const end = start + per;
+    const jump = maxRgbDiff(images[start], images[end]);
+    used = images.slice(start, end);
+    const name = (i: number): string => set.frames[i].name.replace('.png', '');
+    log(`  lead-in: ${window.periods} period(s) of the idle played ahead, physics running; ${name(start)}–${name(end - 1)} kept (${per} frame(s), the last period); ${name(end)}, one period after ${name(start)}, differs from it by max |d| ${jump.max}, ${pixelsOver(images[start], images[end], 40)} px over 40 — the jump at the wrap`);
+  } else if (images.length > 1 && sameRgba(images[0].data, images[images.length - 1].data)) {
     used = images.slice(0, -1);
     log(`  ${lastName} equals f0000.png byte for byte, so it is dropped: the loop wraps onto frame 0, and showing it twice would hold that pose for two ticks`);
   } else if (images.length > 1) {
@@ -1103,6 +1255,12 @@ export interface BuildInput {
   requirements?: string;
   /** `--idle-keys`, forwarded to the rig stage as `rig` takes it (issue #95); {@link DEFAULT_IDLE_KEYS} when absent. */
   idleKeys?: IdleKeys;
+  /**
+   * `--lead-in <n>`, with `loop` only: the loop is encoded from the last of n + 1
+   * idle periods played back to back ({@link leadInFrames}) instead of from
+   * `check/idle_frames/`; absent, the loop is as before.
+   */
+  leadIn?: number;
 }
 
 /**
@@ -1116,7 +1274,7 @@ export interface BuildRunners {
   check: RigcRunner;
   /** Where the check's rigc binary is, for its header line. */
   checkBin: string;
-  /** A directory the rig stage may stage its gate in; emptied before and after. */
+  /** A directory the rig stage may stage its gate in, and the loop its lead-in render after it; emptied before and after each. */
   scratch: string;
 }
 
@@ -1178,7 +1336,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   for (const p of BUILD_OWNS) rmSync(join(out, p), { recursive: true, force: true });
   // The idle-keys value is named only when it is not the default, so a build without the flag, or with the default, prints the line it printed before issue #95.
   const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
-  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? ', with the idle loop' : ''}`);
+  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
 
   try {
     // build runs rig next, which needs the whole config, so the full loader is
@@ -1215,12 +1373,15 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   }
 
   if (input.loop) {
-    const frames = join(out, 'check', 'idle_frames');
     try {
       const say = prefixed('loop');
-      const lossless = loopStage(frames, join(out, 'idle.png'), 'apng', say);
-      const indexed = loopStage(frames, join(out, 'idle-indexed.png'), 'indexed', say);
-      const gif = loopStage(frames, join(out, 'idle.gif'), 'gif', say);
+      const window = input.leadIn === undefined ? undefined : { periods: input.leadIn };
+      if (window !== undefined) rmSync(run.scratch, { recursive: true, force: true });
+      const frames = window === undefined ? join(out, 'check', 'idle_frames') : leadInFrames(join(out, 'rig'), run.scratch, window.periods, run.check, { pageEdges: input.pageEdges, packShape: input.packShape ?? DEFAULT_PACK_SHAPE });
+      const lossless = loopStage(frames, join(out, 'idle.png'), 'apng', say, window);
+      const indexed = loopStage(frames, join(out, 'idle-indexed.png'), 'indexed', say, window);
+      const gif = loopStage(frames, join(out, 'idle.gif'), 'gif', say, window);
+      if (window !== undefined) rmSync(run.scratch, { recursive: true, force: true });
       const fig = (e: PaletteError | null): string => (e === null ? 'lossless' : `max ${e.max}, mean ${e.mean.toFixed(3)}`);
       say(`loop: idle.png ${lossless.bytes} B (${fig(lossless.error)}); idle-indexed.png ${indexed.bytes} B (${fig(indexed.error)}); idle.gif ${gif.bytes} B (${fig(gif.error)}) — palette error per channel over all frames`);
     } catch (err) {

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`,
         },
       ]);
     }