spine-rigc 1.4.0 → 1.5.1

package/src/pose.ts

@@ -153,11 +153,23 @@ const COARSE_PART_THICKNESS = 4;
  * the search misses fell from 65 to 15, for 10–14% more CPU over the grid.
  *
  * 🔸 Not free of losses, and they are stated rather than averaged away: 9 trials
- * that placed on the quarter grid do not on this one. Five of them are blurred
- * parts that now come back ambiguous between two scales at the same spot, or
- * 2.0 px off against a 2 px bar; three are a basin reached and then polished
- * onto a worse placement beside it, and one a basin ranked out of the
- * refinement's twelve — the refinement, not this grid.
+ * that placed on the quarter grid did not on this one when it shipped. Five are
+ * blurred parts at 24–96 px that came back ambiguous between two scales at the
+ * same spot, or 2.0 px off against a 2 px bar — the objective's, not this
+ * grid's. The other four were the refinement's, and since issue #877 all four
+ * place at their truth again: the native 48 px arm (walk) at 0.07 px, 48 px
+ * goggles (walk) 0.04, 96 px goggles (setup) 0.03 — three polishes stopped in a
+ * scale–position valley, now left by `POLISH_SCALE_ESCAPE` — and the 24 px shin
+ * (setup) 0.03, ranked 15th into full resolution, now carried by
+ * `REFINE_CANDIDATES`. Of the five blurred ones, the blur2 32 px shin (setup)
+ * and the blur1 24 px mouth are found again too.
+ *
+ * ⚠️ #877 lost two of its own, both inside the ambiguity margin rather than
+ * off the truth: the blur2 24 px front shin (walk) now reports the truth as its
+ * BEST (0.03 px, 0.00989) with the old 0.57 px answer 0.0094 above it, and the
+ * blur1 64 px mouth (walk) keeps its best at 0.93 px and gains a second scale
+ * at the same spot 0.0031 above it. Each is two readings of one place the
+ * 0.01 absolute margin will not pick between — the verdict it exists to give.
  */
 export const COARSE_STRIDE_FRACTION = 0.125;
 
@@ -243,8 +255,84 @@ export const BACKGROUND_BORDER_SHARE = 0.6;
  */
 const MINIMA_PER_SCALE = 5;
 
-/** How many candidates survive each refinement level. */
-const REFINE_CANDIDATES = 12;
+/**
+ * How many candidates survive each refinement level.
+ *
+ * ⚠️ Fifteen rather than twelve, and it is the smallest count the grid named
+ * (issue #877). Of the 14 trials the search missed after #865, one was lost by
+ * this cutoff rather than by any polish: the native 24 px front shin, whose
+ * truth's candidate ranked 15th (index 14) of 28 at the 2x level — that part's
+ * coarse level — and was cut on the way into full resolution, where the truth
+ * scores 0.0199 against the 0.1188 reported. Fifteen is the least count that
+ * carries index 14; sixteen alone was measured to place it at 0.03 px and move
+ * no other trial (228 found, none lost). A band of the level's best was the
+ * alternative, and it was rejected on its number: to carry that candidate it
+ * would have had to reach 1.73x the best, and a band that wide carried up to 27
+ * candidates (14 of 108 sampled refinement levels over twelve) — a cost set by
+ * one trial and paid on all of them.
+ */
+const REFINE_CANDIDATES = 15;
+
+/**
+ * The factors a converged full-resolution polish tries its scale up by before it
+ * stops — half a coarse scale rung, the resolution the coarse ladder itself had,
+ * and a quarter of one (issue #886); the better of the two re-fits wins.
+ *
+ * 🔍 What the pattern search cannot do, and the trace table of issue #877 is
+ * how it was seen: every probe moves ONE degree of freedom, and the objective
+ * couples scale to position along a diagonal valley — a part shrunk a little
+ * fits best a pixel or two off its truth, so from there every single-axis probe
+ * is worse and every joint move is better. In 12 of the 14 missed trials the
+ * truth's candidate reached full resolution ranked first or second, the
+ * full-resolution objective preferred the truth to everything kept, and the
+ * polish stopped 2–7 px off it at a scale of 0.64–0.96. Not one polish ever
+ * accepted a worse residual — a polish moves only on a strictly lower probe of
+ * its own level's objective, and `PO26` holds that — so the rise from one level
+ * to the next is a change of objective, never a step taken uphill.
+ *
+ * ⭐ So the escape re-fits position at the new scale before comparing — the
+ * joint move, taken one axis at a time — and a better point restarts the polish
+ * there. UP only, and that is derived rather than tuned: the objective charges a
+ * part pixel that lands off the figure and charges nothing for figure left
+ * uncovered, so a shrunk placement is the cheap error the reduced levels make —
+ * every stuck point in the table sat below scale 1, none above.
+ *
+ * 📏 Measured on the grid with `REFINE_CANDIDATES` at fifteen: 227 → 237 trials
+ * found, 12 gained, 2 lost, search misses 14 → 8, for 43% more refinement
+ * samples (the coarse pass is untouched). Both ways at twelve found 236 (12
+ * gained, 3 lost) for 38% more against up only's 21%; a second step each way,
+ * 237 (15, 5) for 76%. ⚠️ The two it loses are one shape, a scale twin at the
+ * same spot: the blurred 64 px mouth (walk) keeps its best at 0.9 px and now
+ * reports a second placement 1.8 px off at scale 0.825 within the ambiguity
+ * margin, and the blurred 24 px front shin (walk) now places AT its truth
+ * (0.03 px, 0.00989) where it placed 0.57 px off at 0.0191 — the old answer is
+ * still reported beside it, 0.0094 above, inside the 0.01 absolute margin.
+ *
+ * 🔍 The quarter rung is issue #886, and the fixed-scale profile is what
+ * named it. MOTION.md §6's post (14x96, pose A, `--scale 0.85,1.2`) came back
+ * at scale 0.917 and residual 0.0649 where the page had recorded 0.975 at
+ * 0.0589 — the old placement still scores 0.0589 on this objective, so the
+ * search missed it. The trace: the coarse cell nearest the truth (2.4 px off
+ * it, at the 2x level) kept a half-turned post, its polish ended 6.7 px from
+ * the truth, the full-resolution rotation re-grid set it upright there, and
+ * the polish climbed the scale–position valley to 0.917.
+ * The half-rung escape then tried 1.029: best position there 0.0980, worse
+ * than 0.0649, so it declined — while the best position at every scale
+ * between 0.94 and 1.00 scores 0.0619–0.0589. A part whose material fills its
+ * image pays for every pixel pushed past the figure, so its profile above the
+ * truth is a cliff, and half a rung stepped over the basin onto it. A quarter
+ * rung lands at 0.971 (0.0593, 0.1 px off the page's placement).
+ *
+ * 📏 Both, not the quarter alone, and measured on the grid rather than argued:
+ * the quarter alone found 234 (3 gained, 6 lost — the native arms #877 was
+ * made for need the half); half then quarter, the quarter tried only when the
+ * half declines, 237 (1, 1); both, the better kept, 238 (2 gained, 1 lost) and
+ * misses 8 → 6, for 16% more user CPU over the grid. The one it loses is a
+ * margin reading of the kind named above: the blurred 32 px front shin (walk)
+ * now reports its truth as its BEST (0.07 px, 0.00968) with the old 0.51 px
+ * answer 0.0045 above it, inside the 0.01 absolute margin.
+ */
+const POLISH_SCALE_ESCAPES = [2 ** (1 / (4 * SCALE_STEPS_PER_OCTAVE)), 2 ** (1 / (2 * SCALE_STEPS_PER_OCTAVE))];
 
 /** Sample budgets per stage. The reported residual uses every pixel regardless. */
 const COARSE_SAMPLES = 96;
@@ -284,8 +372,8 @@ export const POSE_FLOOR = {
   span: 24,
   detail: 0.5,
   /** Found share of the grid's trials under `detail`, and over it — both measured by `deriveFloor`. */
-  rateBelow: 0.082,
-  rateAbove: 0.728,
+  rateBelow: 0.066,
+  rateAbove: 0.772,
 };
 
 /** Which side of `POSE_FLOOR` a part is on, from its own longest side in part pixels and its detail. */
@@ -331,8 +419,11 @@ export function legibilityReading(l: Omit<PoseLegibility, 'reading'>, verdict: '
   // occurs: on the grid after it, 10 ambiguous trials above the floor had a
   // truth scoring better than both answers — native 24 px gun and shin, 48 px
   // arm, 96 px goggles twice, and blurred gun, goggles and rear shin from 48 px
-  // up. Nine of the ten sat 2–6 px from the truth rather than on another hill. So the sentence names that reading too, with the one remedy that
-  // separates it: a window.
+  // up. Nine of the ten sat 2–6 px from the truth rather than on another hill.
+  // Issue #877's polish took that to 6 — native 24 px gun, 96 px goggles, and
+  // blurred goggles and gun from 128 px and rear shin at 48 px — five of them
+  // 2.1–2.7 px off, the rear shin 19 px. So the sentence names that reading
+  // too, with the one remedy that separates it: a window.
   return (
     `${figures} — above the measured floor (AUTHORING §11.5: ${floorClause()}), so size and texture do not explain this; ` +
     (verdict === 'refused'
@@ -567,6 +658,67 @@ export interface PoseOptions {
   scale?: { min: number; max: number };
   rotation?: { minDeg: number; maxDeg: number };
   maxResidual?: number;
+  /**
+   * An instrument's sink, never read by the search itself: when present, every
+   * level of every part's refinement is appended to it. See `PoseTrace`.
+   */
+  trace?: PoseTrace;
+}
+
+/** A search candidate as the trace states it: where the part image's centre would land, frame pixels. */
+export interface PoseTraceCandidate {
+  x: number;
+  y: number;
+  rotationDeg: number;
+  scale: number;
+  /** The level's own sampled objective — not the reported, every-pixel residual. */
+  residual: number;
+}
+
+/** One accepted move of a polish: the residual it moved to and the steps it moved with. */
+export interface PoseTraceStep {
+  residual: number;
+  translate: number;
+  rotate: number;
+  scale: number;
+  /** The accepted probe's scale or rotation was held by its window rather than taken as stepped. */
+  clamped: boolean;
+  /** A restart from a converged point to a different scale, rather than a step of the pattern. */
+  escape: boolean;
+}
+
+export interface PoseTraceLevel {
+  part: string;
+  /** Pyramid index; 0 is full resolution. */
+  level: number;
+  reduction: number;
+  /** How many of the candidates handed down this level took, before any rotation branching. */
+  keep: number;
+  /** The seeds this level polished, in the order they were ranked going in. */
+  seeds: PoseTraceCandidate[];
+  /** Per seed, this level's objective at the seed — where its polish started from. */
+  starts: number[];
+  /** Per seed, the moves its polish accepted, in order. */
+  paths: PoseTraceStep[][];
+  /** Per seed, where its polish ended. */
+  polished: PoseTraceCandidate[];
+  /** The candidates this level hands on, ranked and deduplicated. */
+  out: PoseTraceCandidate[];
+  /** This level's objective at `PoseTrace.probe`, when one was given. */
+  probeResidual: number | null;
+}
+
+/**
+ * The refinement written down level by level, for an instrument that knows
+ * where the truth is and needs to say where the search left it (issue #877).
+ * Pure bookkeeping: a search with a trace returns the same report as one without.
+ */
+export interface PoseTrace {
+  /** A placement, in the report's own space, to score at every level alongside the candidates. */
+  probe?: { x: number; y: number; rotationDeg: number; scale: number };
+  levels: PoseTraceLevel[];
+  /** Per part, every candidate that reached the report, with its every-pixel residual, best first. */
+  measured: { part: string; candidates: PoseTraceCandidate[] }[];
 }
 
 // ---------------------------------------------------------------------------
@@ -1095,16 +1247,47 @@ function polish(
    * default run moves.
    */
   rotationBounds: { min: number; max: number; wraps: boolean },
+  /** Scale factors tried from the point the steps converged on; a better one restarts the polish there. */
+  escapes: readonly number[],
+  /** An instrument's record of where the polish started and the moves it accepted; the search never reads it. */
+  path?: { start: number; steps: PoseTraceStep[] },
 ): Candidate {
   const clamp = (v: number): number => Math.min(bounds.max, Math.max(bounds.min, v));
   const hold = (v: number): number =>
     rotationBounds.wraps ? v : Math.min(rotationBounds.max, Math.max(rotationBounds.min, v));
   let cur: Candidate = { ...start, residual: residualAt(level, plate, s, start, smooth) };
+  if (path !== undefined) path.start = cur.residual;
   let dt = step.translate;
   let dr = step.rotate;
   let ds = step.scale;
   for (let guard = 0; guard < 200; guard++) {
-    if (dt <= floor.translate && dr <= floor.rotate && ds <= floor.scale) break;
+    if (dt <= floor.translate && dr <= floor.rotate && ds <= floor.scale) {
+      let jump = cur;
+      for (const f of escapes) {
+        const scale = clamp(cur.scale * f);
+        if (scale === cur.scale) continue;
+        const refit = polish(
+          level,
+          plate,
+          s,
+          { ...cur, scale },
+          { translate: step.translate, rotate: 0, scale: 0 },
+          { translate: floor.translate, rotate: 0, scale: 0 },
+          smooth,
+          bounds,
+          rotationBounds,
+          [],
+        );
+        if (refit.residual < jump.residual) jump = refit;
+      }
+      if (jump === cur) break;
+      path?.steps.push({ residual: jump.residual, translate: dt, rotate: dr, scale: jump.scale / cur.scale - 1, clamped: false, escape: true });
+      cur = jump;
+      dt = step.translate;
+      dr = step.rotate;
+      ds = step.scale;
+      continue;
+    }
     const probes: Candidate[] = [];
     const push = (cand: Omit<Candidate, 'residual'>): void => {
       probes.push({ ...cand, residual: residualAt(level, plate, s, { ...cand, residual: 0 }, smooth) });
@@ -1139,6 +1322,12 @@ function polish(
       ds /= 2;
       continue;
     }
+    if (path !== undefined) {
+      const clamped =
+        (best.scale !== cur.scale && best.scale !== cur.scale * (1 + ds) && best.scale !== cur.scale * (1 - ds)) ||
+        (best.rotDeg !== cur.rotDeg && best.rotDeg !== cur.rotDeg + dr && best.rotDeg !== cur.rotDeg - dr);
+      path.steps.push({ residual: best.residual, translate: dt, rotate: dr, scale: ds, clamped, escape: false });
+    }
     cur = best;
   }
   return cur;
@@ -1553,6 +1742,7 @@ export function estimatePose(options: PoseOptions): PoseReport {
         maxResidual,
         { min: scaleMin, max: scaleMax },
         rotationBounds,
+        options.trace,
       ),
     );
   }
@@ -1569,6 +1759,7 @@ function placePart(
   maxResidual: number,
   scaleBounds: { min: number; max: number },
   rotationBounds: { min: number; max: number; wraps: boolean },
+  trace?: PoseTrace,
 ): PosePart {
   const scaleMin = scaleBounds.min;
   /** The scale the sample sets are sized for — the middle of the window, and NOT the scale under test. */
@@ -1766,7 +1957,11 @@ function placePart(
       }
       seeds.push(start);
     }
-    candidates = seeds.map((seed) => polish(level, plate, s, seed, step, floor, smooth, scaleBounds, rotationBounds));
+    const paths = seeds.map((): { start: number; steps: PoseTraceStep[] } => ({ start: 0, steps: [] }));
+    candidates = seeds.map((seed, i) =>
+      polish(level, plate, s, seed, step, floor, smooth, scaleBounds, rotationBounds, li === 0 ? POLISH_SCALE_ESCAPES : [], trace === undefined ? undefined : paths[i]),
+    );
+    const polished = candidates.slice();
     candidates.sort((a, b) => a.residual - b.residual);
     // ⚠️ Eight branches that walked to one optimum are one candidate, not eight —
     // and the radius has to scale with the PART rather than be a pixel count.
@@ -1775,6 +1970,47 @@ function placePart(
     // instrument exists to keep: with a fixed one-pixel radius the fixture lost
     // one of its two identical arms.
     candidates = dedupe(candidates, Math.max(1, (0.2 * span * scaleReference) / level.reduction), 5, 1.03);
+    if (trace !== undefined) {
+      const ou = part.width / 2 - anchorX;
+      const ov = part.height / 2 - anchorY;
+      const said = (c: Candidate): PoseTraceCandidate => {
+        const cos = Math.cos(c.rotDeg * DEG) * c.scale;
+        const sin = Math.sin(c.rotDeg * DEG) * c.scale;
+        return {
+          x: c.cx * level.reduction + ou * cos - ov * sin,
+          y: c.cy * level.reduction + ou * sin + ov * cos,
+          rotationDeg: normaliseDegrees(c.rotDeg),
+          scale: c.scale,
+          residual: c.residual,
+        };
+      };
+      let probeResidual: number | null = null;
+      if (trace.probe !== undefined) {
+        const q = trace.probe;
+        const cos = Math.cos(q.rotationDeg * DEG) * q.scale;
+        const sin = Math.sin(q.rotationDeg * DEG) * q.scale;
+        const at: Candidate = {
+          cx: (q.x - (ou * cos - ov * sin)) / level.reduction,
+          cy: (q.y - (ou * sin + ov * cos)) / level.reduction,
+          rotDeg: q.rotationDeg,
+          scale: q.scale,
+          residual: 0,
+        };
+        probeResidual = residualAt(level, plate, s, at, smooth);
+      }
+      trace.levels.push({
+        part: name,
+        level: li,
+        reduction: level.reduction,
+        keep,
+        seeds: seeds.map(said),
+        starts: paths.map((p) => p.start),
+        paths: paths.map((p) => p.steps),
+        polished: polished.map(said),
+        out: candidates.map(said),
+        probeResidual,
+      });
+    }
     if (li > 0) {
       candidates = candidates.map((c) => ({ ...c, cx: c.cx * 2, cy: c.cy * 2 }));
       // A rotation-free part keeps its step at zero all the way down, so the
@@ -1812,6 +2048,7 @@ function placePart(
           true,
           scaleBounds,
           rotationBounds,
+          [],
         ),
       );
     }
@@ -1822,6 +2059,16 @@ function placePart(
   // candidates that walked to the same optimum are one answer, not two.
   const measured = candidates.map((cand) => ({ cand, placement: toPlacement(part, anchorX, anchorY, cand, measure(levels[0], plates[0], part, anchorX, anchorY, cand)) }));
   measured.sort((a, b) => a.placement.residual - b.placement.residual || b.placement.footprint - a.placement.footprint);
+  trace?.measured.push({
+    part: name,
+    candidates: measured.map((m) => ({
+      x: m.placement.x,
+      y: m.placement.y,
+      rotationDeg: m.placement.rotationDeg,
+      scale: m.placement.scale,
+      residual: m.placement.residual,
+    })),
+  });
   const distinct: typeof measured = [];
   for (const m of measured) {
     const same = distinct.some(

package/src/render.ts

@@ -1130,9 +1130,17 @@ export interface GeometryFile {
 }
 
 /**
- * A number the export could not print as a number — refused rather than written,
- * because `JSON.stringify` writes `NaN` and `Infinity` as `null` and a consumer
- * would read a hole in the geometry as a vertex at nothing.
+ * A pose holding a number that is not finite — refused by the bone or the vertex
+ * that holds it, and the value, rather than drawn, framed or written.
+ *
+ * Two callers throw it, with one sentence between them (`nonFiniteSentence`):
+ * the geometry export, because `JSON.stringify` writes `NaN` and `Infinity` as
+ * `null` and a consumer would read a hole in the geometry as a vertex at
+ * nothing; and `framingViewport`, because a box over an infinite vertex is no
+ * box at all (issue #873). Before that second caller the framing answered `null`
+ * for it, which `render` prints as "posed no drawable attachment" — true of a
+ * skeleton that draws nothing and false of this one, whose attachment is there
+ * and posed to a number no picture can hold.
  */
 export class GeometryError extends Error {}
 
@@ -1250,28 +1258,159 @@ function restOf(data: SkeletonData, skin: string | undefined, shown: AttachmentP
   return out;
 }
 
-/** Throw a `GeometryError` at the first number in `file` that is not finite, naming where it sits. */
-function refuseNonFinite(file: GeometryFile): void {
-  const check = (where: string, entries: AttachmentPose[] | AttachmentRest[], bones: GeometryBone[]): void => {
-    for (const bone of bones) {
-      for (const field of ['a', 'b', 'c', 'd', 'worldX', 'worldY'] as const) {
-        if (!Number.isFinite(bone[field])) {
-          throw new GeometryError(`${where}: bone ${JSON.stringify(bone.name)} has ${field} ${String(bone[field])}; a world transform is finite`);
-        }
+/** The bone fields a world transform is made of — what `firstNonFinite` reads off a bone. */
+type WorldTransform = Pick<GeometryBone, 'name' | 'a' | 'b' | 'c' | 'd' | 'worldX' | 'worldY'>;
+
+/** The fields of an attachment entry `firstNonFinite` reads — a frame's `AttachmentPose` or a rest entry. */
+type PosedVertices = Pick<AttachmentPose, 'slot' | 'attachment' | 'vertices'>;
+
+/**
+ * The sentence for the first number at `where` that is not finite — bones before
+ * vertices, since a bone that overflowed is the cause and its vertices the
+ * symptom — or `null` when every number there is finite.
+ */
+function firstNonFinite(where: string, entries: readonly PosedVertices[], bones: readonly WorldTransform[]): string | null {
+  for (const bone of bones) {
+    for (const field of ['a', 'b', 'c', 'd', 'worldX', 'worldY'] as const) {
+      if (!Number.isFinite(bone[field])) {
+        return `${where}: bone ${JSON.stringify(bone.name)} has ${field} ${String(bone[field])}; a world transform is finite`;
       }
     }
-    for (const entry of entries) {
-      const bad = entry.vertices.findIndex((value) => !Number.isFinite(value));
-      if (bad === -1) continue;
-      throw new GeometryError(
-        `${where}: slot ${JSON.stringify(entry.slot)} attachment ${JSON.stringify(entry.attachment)} vertex ` +
-          `${Math.floor(bad / 2)} has ${bad % 2 === 0 ? 'x' : 'y'} ${String(entry.vertices[bad])}; a posed vertex is finite`,
-      );
+  }
+  for (const entry of entries) {
+    const bad = entry.vertices.findIndex((value) => !Number.isFinite(value));
+    if (bad === -1) continue;
+    return (
+      `${where}: slot ${JSON.stringify(entry.slot)} attachment ${JSON.stringify(entry.attachment)} vertex ` +
+      `${Math.floor(bad / 2)} has ${bad % 2 === 0 ? 'x' : 'y'} ${String(entry.vertices[bad])}; a posed vertex is finite`
+    );
+  }
+  return null;
+}
+
+/**
+ * The same sentence for one skeleton as it stands posed now — its bones, then
+ * the vertices of every region and mesh its slots show, in draw order — or
+ * `null` when every one of those numbers is finite.
+ *
+ * ⭐ This is how `A10_NO_NAN_AFTER_STEPPING` reads each pose it steps (issue
+ * #882), so the gate and the renderer hold one definition of "not finite": the
+ * six terms `firstNonFinite` reads off a bone, and the vertices the runtime
+ * computes from them. Before it A10 read the world POSITION alone, and a bone at
+ * `rotation: 1e309` — finite position, NaN `a`, `b`, `c`, `d` — was gated green
+ * and then refused here. The vertices are read too because a bone can be finite
+ * and still carry one that is not: a two-bone `scaleX` chain of 1e154 × 1e154
+ * leaves the child's `a` at 1e308, finite, and every vertex of its attachment
+ * past the largest double. Only computed once every bone is finite, so a
+ * broken bone is named as the cause rather than through its vertices.
+ */
+export function nonFiniteOfPosed(where: string, skeleton: Skeleton): string | null {
+  const bones: WorldTransform[] = skeleton.bones.map((bone) => {
+    const { a, b, c, d, worldX, worldY } = bone.appliedPose;
+    return { name: bone.data.name, a, b, c, d, worldX, worldY };
+  });
+  const found = firstNonFinite(where, [], bones);
+  if (found !== null) return found;
+  const entries: PosedVertices[] = [];
+  for (const slot of skeleton.drawOrder.appliedPose) {
+    const attachment = slot.appliedPose.attachment;
+    if (!(attachment instanceof MeshAttachment) && !(attachment instanceof RegionAttachment)) continue;
+    entries.push({ slot: slot.data.name, attachment: attachment.name, vertices: worldVerticesOf(skeleton, slot, attachment) });
+  }
+  return firstNonFinite(where, entries, []);
+}
+
+/**
+ * How a sampled frame is named in that sentence: the animation, the frame's
+ * index at the rate it was sampled and its time — or the bare index for the one
+ * frame of a skeleton with no animation, whose setup pose is checked first.
+ */
+function frameWhere(animation: string | null, index: number, time: number, fps: number): string {
+  if (animation === null) return `frame ${index}`;
+  return `animation ${JSON.stringify(animation)} frame ${index} at ${fps} fps (t=${time.toFixed(4)}s)`;
+}
+
+/** One sampled frame's numbers, under the name the sentence gives it. */
+interface NamedPose {
+  where: string;
+  attachments: readonly PosedVertices[];
+  bones: readonly WorldTransform[];
+}
+
+/**
+ * ⭐ **The one derivation of the non-finite sentence** (issue #873): the setup
+ * pose, then every frame in order, then the rest table. The export and the
+ * framing both reach it, so `render` and `render --geometry` refuse one planted
+ * overflow in the same words.
+ *
+ * The setup pose first because a setup bone that overflowed is named there as
+ * the BONE, and the rest table — the setup's bones with no deform — would name
+ * the same fault one step on, as a vertex. Rest is still checked, last: it holds
+ * attachments the setup pose does not show.
+ */
+function nonFiniteSentence(
+  setup: Pick<NamedPose, 'attachments' | 'bones'>,
+  frames: readonly NamedPose[],
+  rest: readonly PosedVertices[],
+): string | null {
+  const first = firstNonFinite('the setup pose', setup.attachments, setup.bones);
+  if (first !== null) return first;
+  for (const frame of frames) {
+    const found = firstNonFinite(frame.where, frame.attachments, frame.bones);
+    if (found !== null) return found;
+  }
+  return firstNonFinite('the rest table', rest, []);
+}
+
+/** Throw a `GeometryError` at the first number in `file` that is not finite, naming where it sits. */
+function refuseNonFinite(file: GeometryFile): void {
+  const sentence = nonFiniteSentence(
+    file.setup,
+    file.frames.map((frame) => ({ ...frame, where: frameWhere(file.animation, frame.index, frame.time, file.fps) })),
+    file.rest,
+  );
+  if (sentence !== null) throw new GeometryError(sentence);
+}
+
+/**
+ * Where a skeleton's pose is not finite, as the sentence the geometry export
+ * refuses on — or `null` when every bone and vertex of it is finite.
+ *
+ * Each set is sampled at its own rate, with its bones and whole attachments —
+ * `animation: null` is the setup pose alone — so the frame it names is a frame of
+ * the caller's own grid. It samples again rather than taking the caller's
+ * frames, because a caller that only draws sampled no bones; it is run only
+ * once the caller has found a number that is not finite, so a finite pose never
+ * pays for it.
+ */
+export function nonFinitePoseOf(
+  data: SkeletonData,
+  skin: string | undefined,
+  sets: ReadonlyArray<{ animation: string | null; fps: number }>,
+): string | null {
+  const opts: PoseOptions = { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true };
+  // Every attachment list the frames showed, for the rest table's roster.
+  const shown: AttachmentPose[][] = [];
+  const named = (frame: Frame, where: string): NamedPose => {
+    if (frame.bones === undefined || frame.attachments === undefined) {
+      throw new Error(`${where} was sampled without { bones: true, geometry: true }`);
     }
+    shown.push(frame.attachments);
+    return { where, attachments: frame.attachments, bones: frame.bones };
   };
-  check('the rest table', file.rest, []);
-  check('the setup pose', file.setup.attachments, file.setup.bones);
-  for (const frame of file.frames) check(`frame ${frame.index}`, frame.attachments, frame.bones);
+  const setup = named(sampleSetupPose(data, opts)[0], 'the setup pose');
+  const frames = sets.flatMap(({ animation, fps }) =>
+    animation === null
+      ? []
+      : sampleAnimation(data, animation, fps, opts).map((frame) =>
+          named(frame, frameWhere(animation, frame.index, frame.time, fps)),
+        ),
+  );
+  // Not read unless the setup pose and every frame are finite: `restOf` poses
+  // what they show, and would be posing the same overflow a third time.
+  const found = nonFiniteSentence(setup, frames, []);
+  if (found !== null) return found;
+  return nonFiniteSentence({ attachments: [], bones: [] }, [], restOf(data, skin, shown));
 }
 
 /**
@@ -1685,6 +1824,10 @@ export function trimmedUnionBounds(
  *
  * Measuring the box densely and once makes the framing a property of the SHOT,
  * so every rate of one skeleton lands on the same pixels.
+ *
+ * `null` means the skeleton posed no vertex at all — nothing to draw. A pose
+ * holding a vertex at Infinity or NaN is refused by a `GeometryError` naming the
+ * bone or vertex and its value (issue #873), never answered `null`.
  */
 export function framingViewport(data: SkeletonData, maxSide: number, opts?: PoseOptions): Viewport | null {
   // The skin belongs here as much as in the frames: the union box is over the
@@ -1708,8 +1851,35 @@ export function framingViewport(data: SkeletonData, maxSide: number, opts?: Pose
     data.animations.length === 0
       ? [sampleSetupPose(data, framed)]
       : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS, framed));
+  // ⚠️ Two different reasons a box is not finite, told apart here and nowhere
+  // else (issue #873). A skeleton that posed no vertex at all has nothing to
+  // draw, and that is `null`. One that posed a vertex at Infinity or NaN has a
+  // drawable attachment in a place no box can hold — so it is refused by the
+  // bone or vertex and its value, in the geometry export's own sentence. Before
+  // this, the first case's `null` covered both, and a single overflowing bone
+  // among finite ones reached neither: its box was finite on one side, and
+  // `render` wrote a NaN-by-NaN frame set with exit 0.
+  const posedAny = sets.some((frames) => frames.some((frame) => frame.pieces.some((piece) => piece.world.length > 0)));
+  if (!posedAny) return null;
   const box = unionBounds(sets);
-  if (!Number.isFinite(box.minX)) return null;
+  if (![box.minX, box.minY, box.maxX, box.maxY].every(Number.isFinite)) {
+    const found = nonFinitePoseOf(
+      data,
+      framed.skin,
+      data.animations.length === 0
+        ? [{ animation: null, fps: FRAMING_FPS }]
+        : data.animations.map((a) => ({ animation: a.name, fps: FRAMING_FPS })),
+    );
+    // Reaching here with nothing found would mean the pieces and the whole
+    // attachments disagree about one pose — a defect here, said as one.
+    if (found === null) {
+      throw new Error(
+        `the framing box is not finite (${box.minX}, ${box.minY}, ${box.maxX}, ${box.maxY}) and no bone or ` +
+          'vertex of the pose is — the drawn pieces and the attachments were posed differently',
+      );
+    }
+    throw new GeometryError(found);
+  }
   const pad = Math.max(box.maxX - box.minX, box.maxY - box.minY) * PAD;
   return viewportFor(box.minX - pad, box.minY - pad, box.maxX + pad, box.maxY + pad, maxSide);
 }