spine-rigc 1.4.0 → 1.5.0

package/cli.ts

@@ -103,7 +103,6 @@ import {
   DEFAULT_PADDING,
   DEFAULT_PAGE_EDGES,
   DEFAULT_PAGE_SIZE,
-  FREE_EDGE_STEP,
   PAGE_EDGES,
   packAtlas,
   type PageEdges,
@@ -2054,6 +2053,9 @@ function cmdRender(flags: Record<string, string>): void {
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
 
+  // `null` is a skeleton that posed no vertex at all. One that posed a vertex
+  // it cannot frame — Infinity or NaN — is thrown from the framing as a
+  // `GeometryError` naming the number (issue #873), and never reaches this.
   const viewport = framingViewport(data, maxSide, pose);
   if (!viewport) {
     throw new UsageError(
@@ -3825,7 +3827,7 @@ const FLAG_MEANINGS: Record<string, string> = {
   padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
     "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
   'page-edges': `what a page's edges may be, --pack only (default ${DEFAULT_PAGE_EDGES}): pot is a power of two on ` +
-    `both; free tries every width on a ${FREE_EDGE_STEP}px step, takes the height the placement needs and keeps ` +
+    'both; free tries every width from the widest part up, takes the height the placement needs and keeps ' +
     'the least area — a smaller page, at the cost of region attachments sampling within 1 LSB of the loose ' +
     'build rather than exactly',
   'atlas-in':
@@ -4539,9 +4541,10 @@ try {
   // the one reader's and already names the file, what it is and what rigc
   // reads; a stack under it is the tool describing its own internals instead.
   // Exit 1, like a compile error: the invocation was fine, a file was not.
-  // A pose the geometry export cannot write as numbers (issue #864): the
-  // invocation was fine and the skeleton posed a NaN or an infinity, so exit 1
-  // like a file that is not a PNG. Raised before the first file is written.
+  // A pose that is not finite (issues #864, #873): the invocation was fine and
+  // the skeleton posed a NaN or an infinity, so exit 1 like a file that is not
+  // a PNG. Raised by the geometry export and by the framing — the one sentence
+  // naming the bone or vertex and its value — before the first file is written.
   if (err instanceof GeometryError) {
     console.error(`rigc render: ${err.message}`);
     process.exit(1);

package/docs/AUTHORING.md

@@ -341,9 +341,12 @@ a gap:
 
   Under `pot` turning shrank no page. Under `free` the largest gain, 13.37 %, is
   inside the search's own noise: the neighbouring width on the 32-pixel grid
-  moves that set's unturned page by 18.13 %, and trying every width instead
-  finds an unturned page 10.22 % smaller. With every width tried, no set gains
-  more than 5.05 % from turning — so the packer still never turns a region.
+  `free` then searched moves that set's unturned page by 18.13 %, and trying
+  every width instead finds an unturned page 10.22 % smaller. With every width
+  tried, no set gains more than 5.05 % from turning — so the packer still never
+  turns a region. (The `free` column is that day's 32-pixel grid. `free` has
+  tried every width since issue #872 — below — so the 5.05 % is the turn gain on
+  the search that ships.)
 - **no re-ordering of anything the skeleton says.** `skeleton.json` from a packed
   build is **byte-identical** to the unpacked one, because sizes are still
   measured from the loose PNGs and packing is an output arrangement.
@@ -383,7 +386,7 @@ every power-of-two pair up to `--page-size` in order of area and writes the firs
 the pack fits — it never doubles past a smaller page that would do. So when the
 parts' own area already exceeds the next power-of-two page down, no `pot` packer
 can do better, and `free` is the lever left. Under `free` the candidate widths
-are the multiples of 32 from the widest padded part up to `--page-size`; at each
+are **every width** from the widest padded part up to `--page-size`; at each
 width the parts are placed by the same MaxRects pass on a page `--page-size`
 tall, and the height is the bottom edge of the lowest part. The page with the
 least area wins, then the squarer one (smaller |width − height|), then the
@@ -391,13 +394,65 @@ narrower one — every candidate has a different width, so the order is total an
 two builds of the same parts write the same bytes. Spilling, the packing order
 and `--page-size` as the ceiling are the same as under `pot`.
 
+Every width is affordable because of two bounds, and neither can change the
+page: a width is not tried when the parts' area cannot fit it or when its
+tallest part alone already makes it larger than the best page so far, and a
+placement stops as soon as its lowest part makes it larger than that best page.
+Both are strict, so a width that could tie the best is always placed to the end.
+
+**Why every width, measured (issue #872).** Until then the widths were the
+multiples of 32. On twelve region sets — the two painting rigs below and ten
+production rigs of 20 to 22 parts, the sets of the rotation table above — and,
+as a held-out check, on the ten atlases of the fetched `examples/` corpus, each
+search was run against the every-width page (padding 2, `--page-size` 2048).
+Area change against the 32-pixel grid:
+
+| Set | 32 px (before) | step 8 | step 4 | coarse 32 → ±31 px of the best 2 | coarse 12 → ±11 px of the best | every width (now) |
+| --- | --- | --- | --- | --- | --- | --- |
+| 22-part painting | 1888x697 | −1.58 % | −1.58 % | −1.68 % | −1.68 % | 967x1338, −1.68 % |
+| 20-part painting | 480x1166 | 0.00 % | 0.00 % | −0.21 % | −0.21 % | 479x1166, −0.21 % |
+| P1 | 416x1633 | −1.92 % | −2.88 % | −2.88 % | −2.88 % | 404x1633, −2.88 % |
+| P2 | 1184x810 | 0.00 % | 0.00 % | −0.08 % | −0.08 % | 1183x810, −0.08 % |
+| P3 | 480x1000 | 0.00 % | 0.00 % | 0.00 % | 0.00 % | 480x1000, 0.00 % |
+| P4 | 864x1346 | −3.07 % | −3.07 % | −2.66 % | −3.15 % | 1231x915, −3.15 % |
+| P5 | 1344x1768 | −9.90 % | −10.16 % | −10.22 % | −10.22 % | 1427x1495, −10.22 % |
+| P6 | 800x1934 | −1.00 % | −1.50 % | −1.50 % | −1.50 % | 788x1934, −1.50 % |
+| P7 | 1024x928 | −0.78 % | −0.78 % | −0.88 % | −0.88 % | 1015x928, −0.88 % |
+| P8 | 608x1250 | 0.00 % | 0.00 % | −0.16 % | −0.16 % | 607x1250, −0.16 % |
+| P9 | 1024x2037 | −2.34 % | −2.73 % | −2.93 % | −2.93 % | 994x2037, −2.93 % |
+| P10 | 352x1433 | 0.00 % | −1.14 % | −1.70 % | −1.70 % | 346x1433, −1.70 % |
+| worst miss of the every-width page, twelve sets | 11.38 % | 1.73 % | 0.58 % | 0.50 % | 0.00 % | 0.00 % |
+| worst miss, the ten `examples/` atlases | 4.12 % | 2.67 % | 0.77 % | 0.82 % | 0.82 % | 0.00 % |
+| cell placements, twelve sets | 12,361 | 49,063 | 98,021 | 40,230 | 38,371 | 47,978 |
+
+The rule was the cheapest search that lands on the every-width page. Flipping
+the packer's own last tie-break (leftmost before topmost) changes no page on any
+of the 22 sets, so there is no tie-break noise to land "within": the target is
+the page itself. The coarse-to-fine search that met it on all twelve sets missed
+it on the first held-out atlas, and its failures do not follow its grid — on
+the twelve sets, refining around the best width of a 9-pixel grid misses where
+10 to 12 do not, and a 14-pixel grid misses again —
+because the area as a function of the width has minima one pixel wide (a 4-pixel
+grid refined around its best four widths still misses one). Every width is exact
+by construction. Its placement count overstates its cost, because an abandoned
+placement stops early: all twelve sets take 53 ms in the measuring harness,
+against 22 ms for the 32-pixel grid and 810 ms for every width unbounded, and a
+whole `build --pack --page-edges free` of the 22-part rig takes the same wall
+time either way. ⚠️ The cost grows with the part count faster than the grid's:
+on generated sets of 100 and 300 small parts, where no bound prunes much, the
+search places 15 times the grid's cells.
+
 The default stays `pot` because every runtime accepts a power-of-two page and
 the editor's own packer writes one by default: 9 of the 10 atlases in the
 fetched `examples/` corpus are power-of-two on both edges. What `free` costs is
 the exactness above. `x / pageWidth` is no longer exact, so a **region**
 attachment's samples join a mesh's at one least significant bit against the
 loose build instead of 0. No region's bytes change: every one lifts back byte for
-byte, as under `pot`. Observed on two painting rigs of 22 and 20 parts:
+byte, as under `pot`. Observed on two painting rigs of 22 and 20 parts, on the
+32-pixel grid `free` shipped with (issue #860); every width now packs them at
+967x1338 = 1,293,846 (−38.3 %, 91.2 % covered, 59.7 % opaque) and 479x1166 =
+558,514 (−46.7 %, 93.4 % covered, 53.9 % opaque), and the render columns are
+held to their bound of one by `PK72` on every build rather than re-measured here:
 
 | Rig | `pot` page | `free` page | Area | Covered | Opaque (alpha > 0) | Render vs loose, region attachments only | Render vs loose, whole rig |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -1443,6 +1498,20 @@ renderers and reports its step 5 as a **SKIP** naming that, and the round trip
 comes back green on the strength of `validate` and `diff`. A skin only **one** side
 can draw is the other case entirely, and stays red.
 
+🔢 **"Nothing to draw" is said only of a skeleton that posed no vertex at all.** One
+whose attachment is there but posed to `Infinity` or `NaN` is refused by the bone or
+the vertex that holds it and the value — `rigc render: the setup pose: bone "head" has
+worldX Infinity; a world transform is finite`, or `… animation "turn" frame 31 at 60
+fps (t=0.5167s): bone "head" has a NaN; …` for a key, or `… slot "x" attachment "y"
+vertex 3 has x NaN; a posed vertex is finite` — exit 1, before anything is written.
+It is the sentence `render --geometry` refuses on (§8.2), from the same code, and
+`rigc check` prints it after `the candidate is posed to a number that is not finite,
+so no frame of it can be compared:`. The bone is named before its vertices because
+it is the cause; look for its value in the skeleton file — a setup `x`/`y`/`rotation`,
+or a timeline key at the time given — and, for a rig spec you wrote, in `rigc explain`,
+which prints every bone's local transform. A frame's time is the framing pass's own
+(every animation at 60 fps); the key that overflowed is at or just before it.
+
 **Region attachment** ([Spine: region attachments](http://esotericsoftware.com/spine-regions)),
 the default `type`:
 
@@ -5359,6 +5428,13 @@ rather than linked, like the references at the top of this page: that page cites
 corpus inventory, and a ladder run reads this guide without following its references
 out of it.)
 
+🔢 **A fourth surface is a pose that is not finite**, which `render` and `check`
+refuse before drawing anything, naming the bone or vertex and its value. `validate`
+does not always get there first: a bone `rotation` of `1e309`, in the setup pose or
+in a key, was measured leaving `A10_NO_NAN_AFTER_STEPPING` green, because the bone's
+world position stays finite while its matrix is `NaN`. The sentence, and where to
+look for the number, is under *nothing to draw* in §3.4.
+
 ### 5.1 Compile errors — before the gate
 
 A `CompileError` names the object and the field, and nothing is written.
@@ -6366,8 +6442,13 @@ show what the clip left of them. Bounding boxes, points, paths and clipping poly
 draw nothing and are not listed. Numbers are printed the way every JSON file this
 tool writes prints them — the shortest decimal that reads back as the same double —
 so a vertex in the file *is* the runtime's vertex, not a rounding of it; a pose that
-is not finite is refused naming the frame, the slot, the attachment and the vertex,
-rather than written as `null`.
+is not finite is refused rather than written as `null`, naming where — the setup pose,
+`animation "a" frame i at F fps (t=…s)`, or the rest table — and then the bone and
+its world-transform field, or the slot, the attachment and the vertex, with the
+value. Bones come first, so a bone that overflowed is named as itself rather than as
+its first vertex. Since issue #873 plain `render` refuses the same pose in the same
+sentence while framing it (§3.4's note under *nothing to draw*), so the flag is not
+needed to find out which number it was.
 
 **The two judgements the file was designed for**, written once so a consumer
 implements what the file promises:
@@ -8732,7 +8813,7 @@ ambiguous one ends with a sentence saying which reading its figures support:
 
 - **below the floor** — a 40x28 part of one flat colour, cut from a plain block it fits anywhere inside:
 
-  > part is 40x28 px (span 40 frame px, opaque 1) with texture 0, detail 0; 14 candidate(s), best 0.0000, next 0.0000, spread 0.0000 — below the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up): pose placed 8% of the measured parts this plain, so this part is too plain for pose to tell its placements apart; that says nothing about whether the cut is right
+  > part is 40x28 px (span 40 frame px, opaque 1) with texture 0, detail 0; 17 candidate(s), best 0.0000, next 0.0000, spread 0.0000 — below the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up): pose placed 7% of the measured parts this plain, so this part is too plain for pose to tell its placements apart; that says nothing about whether the cut is right
 
 - **above the floor** — a 200x150 black-and-white checker the frame does not hold:
 
@@ -8759,9 +8840,9 @@ Found within 2 px of the truth, out of 15 trials per cell (free search, default
 
 | texture level (mean) | 24 px | 32 px | 48 px | 64 px | 96 px | 128 px | 192 px |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `native` (detail 3.49) | 12/15 (3 amb) | 14/15 (1 amb) | 13/15 (2 amb) | 15/15 | 12/15 (2 amb, 1 wrong) | 14/15 (1 wrong) | 14/15 (1 wrong) |
-| `blur1` (detail 1.58) | 10/15 (5 amb) | 12/15 (2 amb, 1 wrong) | 13/15 (2 amb) | 13/15 (2 amb) | 12/15 (1 amb, 2 wrong) | 11/15 (1 amb, 3 wrong) | 11/15 (2 amb, 2 wrong) |
-| `blur2` (detail 0.59) | 7/15 (7 amb, 1 wrong) | 8/15 (5 amb, 2 wrong) | 9/15 (4 amb, 2 wrong) | 8/15 (3 amb, 4 wrong) | 7/15 (3 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) | 6/15 (2 amb, 7 wrong) |
+| `native` (detail 3.49) | 13/15 (2 amb) | 15/15 | 15/15 | 15/15 | 13/15 (1 amb, 1 wrong) | 14/15 (1 wrong) | 14/15 (1 wrong) |
+| `blur1` (detail 1.58) | 12/15 (3 amb) | 12/15 (2 amb, 1 wrong) | 13/15 (2 amb) | 12/15 (3 amb) | 12/15 (2 amb, 1 wrong) | 11/15 (1 amb, 3 wrong) | 11/15 (2 amb, 2 wrong) |
+| `blur2` (detail 0.59) | 9/15 (5 amb, 1 wrong) | 9/15 (4 amb, 2 wrong) | 9/15 (4 amb, 2 wrong) | 8/15 (3 amb, 4 wrong) | 7/15 (3 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) | 7/15 (3 amb, 5 wrong) |
 | `flat` (detail 0.00) | 0/15 (14 amb, 1 wrong) | 0/15 (14 amb, 1 wrong) | 0/15 (13 amb, 2 wrong) | 0/15 (11 amb, 4 wrong) | 0/15 (13 amb, 2 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (12 amb, 3 wrong) |
 
 The same trials, grouped by `detail`:
@@ -8769,14 +8850,14 @@ The same trials, grouped by `detail`:
 | detail | found | ambiguous | wrong | refused |
 | --- | --- | --- | --- | --- |
 | under 0.25 | 8/119 | 89 | 22 | 0 |
-| 0.25–0.5 | 2/3 | 0 | 1 | 0 |
-| 0.5–0.75 | 44/81 | 16 | 21 | 0 |
+| 0.25–0.5 | 1/3 | 1 | 1 | 0 |
+| 0.5–0.75 | 48/81 | 14 | 19 | 0 |
 | 0.75–1 | 17/34 | 14 | 3 | 0 |
-| 1–1.5 | 24/25 | 1 | 0 | 0 |
-| 1.5–2 | 34/48 | 11 | 3 | 0 |
-| 2–3 | 36/44 | 5 | 3 | 0 |
-| 3–4 | 33/34 | 1 | 0 | 0 |
-| 4 and over | 29/32 | 3 | 0 | 0 |
+| 1–1.5 | 25/25 | 0 | 0 | 0 |
+| 1.5–2 | 34/48 | 12 | 2 | 0 |
+| 2–3 | 40/44 | 1 | 3 | 0 |
+| 3–4 | 34/34 | 0 | 0 | 0 |
+| 4 and over | 30/32 | 2 | 0 | 0 |
 
 **Method.** The truth set is `examples/spineboy`: its setup pose and one frame of
 `walk` (a third of the way in). For every trial the figure is rendered twice with one
@@ -8798,8 +8879,8 @@ part has a low per-pixel gradient and still places — and size alone has no
 measurable effect across 24–192 px at any level.
 
 **The edge**, derived by `deriveFloor` as the largest rung of a fixed ladder under
-which at most a tenth of the trials were found: **`detail` 0.5**. Under it, **8.2%**
-of the trials were found (10/122); at or over it, **72.8%** (217/298). A part is below
+which at most a tenth of the trials were found: **`detail` 0.5**. Under it, **7.4%**
+of the trials were found (9/122); at or over it, **76.5%** (228/298). A part is below
 the floor when its `detail` is under 0.5, or when its own longest side is under 24 px,
 the smallest size measured (there, nothing measured says `pose` can place it).
 
@@ -8813,17 +8894,35 @@ two anchors — and only 3 had it ranked under the old cutoff of three. The fine
 took the grid from 185 to 227 trials found and those misses from 65 to 14, for about
 10–14% more CPU over the grid (615 s of user time before it, 678 s and 704 s on two runs after).
 
-⚠️ **What this is and is not.** The grid is not a reliability line: four native cells
-place 14 or 15 of 15 and the trials at `detail` 3 and over place 62 of 66, but the
-goggles still place 10 of 42, and a threshold read off two dozen parts of one figure
+The refinement then polishes each place down the pyramid, and at full resolution a
+polish that has stopped tries its scale **up by half a coarse rung** (2^(1/6)), re-fits
+the position there, and restarts if that scores better; fifteen places survive each
+level. Both were set on this grid too (issue #877): of the 14 misses left after #865,
+12 reached full resolution with the truth's place ranked first or second and the
+full-resolution objective preferring the truth, and stopped 2–7 px off it at a shrunk
+scale — the objective couples scale to position along a diagonal, so every
+one-axis step from there is worse while a joint one is better. None of them had
+accepted a worse residual. One more was the 24 px shin, its truth's place ranked
+15th at the 2x level and cut at twelve. Up only because the objective charges part
+pixels that land off the figure and nothing for figure left uncovered, so the
+reduced levels err small: every stuck point sat below scale 1. It took the grid from
+227 to 237 found and the misses from 14 to 8 (12 trials gained, 2 lost — each a
+blurred part now reported with a second placement at the same spot and another
+scale, one of them with the truth itself as its best answer), for 43% more
+refinement samples and the coarse pass untouched.
+
+⚠️ **What this is and is not.** The grid is not a reliability line: five native cells
+place 14 or 15 of 15 and the trials at `detail` 3 and over place 64 of 66, but the
+goggles still place 12 of 42, and a threshold read off two dozen parts of one figure
 would be a claim about that figure. What the grid can separate is **whose** failure a
 failure is. `bun tools/pose_floor.ts` prints the residual at the truth for every
 failed trial and marks it **missed** when the truth scores better than everything
 reported and nothing reported is on it — a failure the search could fix. The other
 failures are the objective preferring another placement (a blurred part shrunk into
 its own region scores better than its truth) or the truth reported and tied, and no
-search can fix those. After the change, 14 of the 193 failed trials are misses, and 13
-of those sit within 7 px of the truth rather than on another hill. All this was
+search can fix those. After #877, 8 of the 183 failed trials are misses, and 7 of
+those sit within 3.1 px of the truth rather than on another hill; the `--from`
+listing prints, for each, where the refinement left the truth level by level. All this was
 measured on **ideal cuts**, the frame's own pixels, where a residual at the truth is
 near zero. A generated cut also disagrees with its picture, which can only make it
 harder to place. So the edge is where `pose` fails even on ideal cuts, and never a
@@ -8833,7 +8932,10 @@ Re-run it with `bun tools/pose_floor.ts --textures <level> --json <out>` (one le
 process parallelises it), then `bun tools/pose_floor.ts --from <a.json>,<b.json>,…` to
 print the table, derive the edge and list the misses per cell. `PO22` in
 `bun run selftest` re-measures three of its cells, `PO24` holds those three cells to
-no miss at all, and `PO23` places the 48 px fist this change was made for.
+no miss at all, and `PO23` places the 48 px fist #865 was made for; `PO28` and
+`PO29` place the four trials #877 was made for and read where the shin survived the
+cutoff, and `PO26` holds every polish to strictly descending residuals, read through
+the same trace.
 
 ## 12. Reading the half of that picture `pose` refuses — `rigc chainfit`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, round-trips it through spine-core and named assertions, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/atlas.ts

@@ -543,12 +543,18 @@ export interface EmitPage {
  *
  * Under `pot` a turn shrank no page on any set, and on P9 an ungated one doubled
  * it. Under `free` the largest gain, P5's 13.37 %, is inside the search's own
- * noise: the nearest other width on the `FREE_EDGE_STEP` grid moves P5's
- * unturned page by 18.13 %, and searching every width instead of every 32nd
- * finds an unturned P5 page 10.22 % smaller with nothing turned. With every
+ * noise: the nearest other width on the 32-px grid the search then used moves
+ * P5's unturned page by 18.13 %, and searching every width instead of every
+ * 32nd finds an unturned P5 page 10.22 % smaller with nothing turned. With every
  * width searched, the largest turn gain on any set is 5.05 % (P5), then 4.96 %
  * (P8) and 4.22 % (P4). That is not a page worth two readers changing, so the
  * packer still never turns a region.
+ *
+ * ⚠️ The `free` column and the 18.13 % are measurements of the search as it was
+ * on that day, a 32-px width grid. Issue #872 replaced it with every width (see
+ * `FREE_EDGE_STEP`), so today's `free` pages for these sets are the every-width
+ * ones the paragraph above compares against, and the 5.05 % is the turn gain
+ * measured on the search that ships.
  */
 export const PACK_NO_ROTATE = 0;
 
@@ -628,7 +634,7 @@ export const DEFAULT_PADDING = 2;
  * What a packed page's edges may be — `--page-edges`. See `packAtlas`, *Page size*.
  *
  * `pot` is the default and the only value until issue #860: both edges are powers
- * of two. `free` lets the width be any multiple of `FREE_EDGE_STEP` and the height
+ * of two. `free` lets the width be any whole number of pixels and the height
  * whatever the placement needs. What `free` costs is measured rather than
  * conceded: a region attachment's sampling coordinate stops being exact and moves
  * to `PK05`'s bound of one least significant bit, the bound a mesh already had.
@@ -636,8 +642,28 @@ export const DEFAULT_PADDING = 2;
 export const PAGE_EDGES = ['pot', 'free'] as const;
 export type PageEdges = (typeof PAGE_EDGES)[number];
 export const DEFAULT_PAGE_EDGES: PageEdges = 'pot';
-/** The step a `free` page's width is tried on. See `packAtlas`, *Page size*. */
-export const FREE_EDGE_STEP = 32;
+/**
+ * The step a `free` page's width is tried on: **1, every width** (issue #872).
+ * See `smallestFreePageFor` for the search and `packAtlas`, *Page size*, for
+ * what it buys.
+ *
+ * It was 32 until #872, and the grid was the cost. On twelve region sets (two
+ * painting rigs and ten production rigs of 20 to 22 parts) the 32-px grid's page
+ * was larger than the every-width page on eleven, by up to 11.38 % (P5: 1344x1768
+ * against 1427x1495). Finer fixed steps and coarse-to-fine searches were measured
+ * against the every-width page too, and none of them is safe: the area as a
+ * function of the width has minima one pixel wide, so a step-4 grid refined
+ * over ±3 px of its best four widths still misses one (the fetched
+ * `5-squash-and-stretch` atlas: 867x415 against 863x415), and the coarse-to-fine
+ * search that was exact on all twelve sets missed by 0.82 % on the first
+ * held-out atlas it met. Every width is exact by construction; what keeps it
+ * cheap is the two bounds `smallestFreePageFor` prunes with, and they are exact
+ * too.
+ *
+ * Kept as a named constant rather than deleted because it is importable, and a
+ * reader of the old value should find the new one rather than a missing name.
+ */
+export const FREE_EDGE_STEP = 1;
 
 /** The part a page is packed from: its region name and its pixels. */
 export interface PackInput {
@@ -751,9 +777,8 @@ function smallestPageFor(
  *
  * The rule, which `docs/AUTHORING.md` §0.1 states in the same words:
  *
- *   * the candidate WIDTHS are the multiples of `FREE_EDGE_STEP` from the widest
- *     cell up to `maxEdge`, plus `maxEdge` itself (it is a power of two, so this
- *     only adds anything when it is smaller than the step);
+ *   * the candidate WIDTHS are every whole width from the widest cell up to
+ *     `maxEdge` (`FREE_EDGE_STEP` is 1);
  *   * at each width the cells are placed by the same MaxRects pass as a `pot`
  *     page, on a page `maxEdge` tall, and the HEIGHT is the bottom edge of the
  *     lowest cell — what that placement needs, not rounded;
@@ -766,26 +791,84 @@ function smallestPageFor(
  * in the page height (a shorter page changes which free rectangle scores best),
  * so "the least height that fits" is not a quantity a bisection could find, and a
  * definition that could not be computed exactly would not be deterministic.
+ *
+ * ⭐ **Two bounds make every width cheap, and neither can change the answer**
+ * (issue #872). Both compare against the best page found so far, and both are
+ * strict, so a width that could still TIE the best — and win on the squarer or
+ * narrower key — is always placed to the end:
+ *
+ *   * a width is not placed at all when the cells' own area exceeds
+ *     `width x maxEdge` (it cannot fit), or when `width x` the tallest cell
+ *     already exceeds the best area (no page at that width is shorter than its
+ *     tallest cell);
+ *   * a placement is abandoned the moment its lowest cell's bottom edge makes
+ *     `width x bottom` exceed the best area. The bottom edge only grows as cells
+ *     are added, so the page that placement would have finished is larger still.
+ *
+ * Neither changes a placement that runs to the end — the pass is the `pot` pass,
+ * on the same page, and abandoning it only stops it early — so the winner is the
+ * every-width winner, and `PK75` compares the two on every set it builds. What
+ * they save, measured on the twelve sets: 391,854 cell placements for an
+ * unbounded every-width search, 47,978 bounded, against 12,361 for the retired
+ * 32-px grid.
  */
 function smallestFreePageFor(
   cells: Array<{ w: number; h: number }>,
   maxEdge: number,
 ): { width: number; height: number; rects: Rect[] } | null {
+  return freePageSearch(cells, maxEdge).page;
+}
+
+/** What one `free` page search did: the page it chose, and what each width cost. */
+export interface FreePageSearch {
+  page: { width: number; height: number; rects: Array<{ x: number; y: number; w: number; h: number }> } | null;
+  /** Candidate widths, from the widest cell to `maxEdge`. */
+  widths: number;
+  /** Widths whose placement ran to the end. */
+  completed: number;
+  /** Widths whose placement stopped once its lowest cell made the page larger than the best so far. */
+  abandoned: number;
+  /** Widths never placed: too narrow for the cells' area, or wide enough that the tallest cell alone loses. */
+  skipped: number;
+}
+
+/**
+ * `smallestFreePageFor`'s search with its bookkeeping — exported so the
+ * selftest can compare its page against an unbounded every-width reference and
+ * see that the bounds did prune (`PK75`). The page is the whole of what the
+ * packer uses; the counts are for the control.
+ */
+export function freePageSearch(cells: Array<{ w: number; h: number }>, maxEdge: number): FreePageSearch {
   let widest = 0;
-  for (const cell of cells) widest = Math.max(widest, cell.w);
-  const widths: number[] = [];
-  for (let w = Math.ceil(widest / FREE_EDGE_STEP) * FREE_EDGE_STEP; w <= maxEdge; w += FREE_EDGE_STEP) widths.push(w);
-  if (widths[widths.length - 1] !== maxEdge && widest <= maxEdge) widths.push(maxEdge);
+  let tallest = 0;
+  let cellArea = 0;
+  for (const cell of cells) {
+    widest = Math.max(widest, cell.w);
+    tallest = Math.max(tallest, cell.h);
+    cellArea += cell.w * cell.h;
+  }
+  const out: FreePageSearch = { page: null, widths: 0, completed: 0, abandoned: 0, skipped: 0 };
   let best: { width: number; height: number; rects: Rect[] } | null = null;
-  for (const width of widths) {
-    const attempt = packOnePage(cells, width, maxEdge);
+  for (let width = Math.ceil(widest / FREE_EDGE_STEP) * FREE_EDGE_STEP; width <= maxEdge; width += FREE_EDGE_STEP) {
+    out.widths++;
+    const bestArea = best === null ? Infinity : best.width * best.height;
+    if (cellArea > width * maxEdge || width * tallest > bestArea) {
+      out.skipped++;
+      continue;
+    }
+    const maxBottom = best === null ? Infinity : Math.floor(bestArea / width);
+    const attempt = packOnePage(cells, width, maxEdge, maxBottom);
+    let height = 0;
+    for (const r of attempt) if (r !== null) height = Math.max(height, r.y + r.h);
+    if (height > maxBottom) {
+      out.abandoned++;
+      continue;
+    }
+    out.completed++;
     if (attempt.some((r) => r === null)) continue;
     const rects = attempt as Rect[];
-    let height = 0;
-    for (const r of rects) height = Math.max(height, r.y + r.h);
     if (best !== null) {
       const area = width * height;
-      const bestArea = best.width * best.height;
       if (area > bestArea) continue;
       if (area === bestArea) {
         const square = Math.abs(width - height);
@@ -796,7 +879,28 @@ function smallestFreePageFor(
     }
     best = { width, height, rects };
   }
-  return best;
+  out.page = best;
+  return out;
+}
+
+/**
+ * One `free` candidate, unbounded: the cells placed at `width` on a page
+ * `maxEdge` tall, and the height that placement needs — or `null` when they do
+ * not all fit. It is the pass `freePageSearch` runs at each width with no
+ * bound, exported so the selftest can rebuild a reference search from the same
+ * placement (`PK74`'s 32-px grid, `PK75`'s every width, `PK76`'s `pot` search).
+ */
+export function placeAtWidth(
+  cells: Array<{ w: number; h: number }>,
+  width: number,
+  height: number,
+): { width: number; height: number; rects: Array<{ x: number; y: number; w: number; h: number }> } | null {
+  const attempt = packOnePage(cells, width, height);
+  if (attempt.some((r) => r === null)) return null;
+  const rects = attempt as Rect[];
+  let bottom = 0;
+  for (const r of rects) bottom = Math.max(bottom, r.y + r.h);
+  return { width, height: bottom, rects };
 }
 
 /**
@@ -813,8 +917,18 @@ function smallestFreePageFor(
  * to be pushed. So the tie-break is spelled out and total — smallest long-side
  * leftover, then topmost, then leftmost — and the caller sorts its input before
  * calling. Same inputs, byte-identical page.
+ *
+ * `maxBottom` is the `free` search's abandon bound (see `freePageSearch`): once a
+ * placed cell's bottom edge passes it the pass stops, and the cells not placed
+ * are `null`. The default, `Infinity`, never stops a pass — which is every `pot`
+ * call, so a `pot` page is placed exactly as it was before the bound existed.
  */
-function packOnePage(cells: Array<{ w: number; h: number }>, pageW: number, pageH: number): Array<Rect | null> {
+function packOnePage(
+  cells: Array<{ w: number; h: number }>,
+  pageW: number,
+  pageH: number,
+  maxBottom = Infinity,
+): Array<Rect | null> {
   const free: Rect[] = [{ x: 0, y: 0, w: pageW, h: pageH }];
   const placed: Array<Rect | null> = [];
 
@@ -848,6 +962,10 @@ function packOnePage(cells: Array<{ w: number; h: number }>, pageW: number, page
     }
     const put: Rect = { x: best.x, y: best.y, w: cell.w, h: cell.h };
     placed.push(put);
+    if (put.y + put.h > maxBottom) {
+      while (placed.length < cells.length) placed.push(null);
+      return placed;
+    }
 
     // Split every free rectangle the placement overlaps, then prune.
     const next: Rect[] = [];
@@ -981,15 +1099,18 @@ function extrudeCell(page: Plate, source: Plate, cellX: number, cellY: number, p
  * Opt-in, and the default stays `pot`: every runtime accepts a power-of-two page
  * and the editor's own packer writes one by default — 9 of the 10 atlases in the
  * fetched `examples/` corpus are power-of-two on both edges. Under `free` the
- * search is `smallestFreePageFor`: widths on a `FREE_EDGE_STEP` grid, the height
- * the placement needs, least area first, then squarer, then narrower. Everything
+ * search is `smallestFreePageFor`: every width from the widest cell up (issue
+ * #872; a 32-px grid until then), the height the placement needs, least area
+ * first, then squarer, then narrower, with two exact bounds that keep it cheap. Everything
  * else is shared — the MaxRects pass, the packing order, the spill rule (which
  * parts share a page is still decided at `maxEdge x maxEdge`) and `--page-size`
  * as the ceiling on both edges, floored to a power of two exactly as under `pot`.
  *
  * What it buys and what it costs, observed on two 20- and 22-part painting rigs:
- * the page went from 1024x2048 to 1888x697 (2,097,152 to 1,315,936 texels,
- * -37.3 %) and from 512x2048 to 480x1166 (1,048,576 to 559,680, -46.6 %). The cost is the exactness the paragraph above describes:
+ * the page goes from 1024x2048 to 967x1338 (2,097,152 to 1,293,846 texels,
+ * -38.3 %) and from 512x2048 to 479x1166 (1,048,576 to 558,514, -46.7 %). Under
+ * the 32-px grid #860 shipped with they were 1888x697 (-37.3 %) and 480x1166
+ * (-46.6 %). The cost is the exactness the paragraph above describes:
  * `x / pageWidth` is no longer exact, so a REGION attachment's sampling
  * coordinate joins a mesh's at `PK05`'s bound of one least significant bit
  * against the loose build. It does not go past it, and no region's bytes change

package/src/check.ts

@@ -80,6 +80,7 @@ import {
   PAD,
   FRAMES_SIDECAR,
   FRAMES_SPEC,
+  nonFinitePoseOf,
   SHEET_COLUMNS,
   SHEET_FILE,
   SHEET_GAP,
@@ -1225,6 +1226,27 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // to compare it — and posing twice is both slower and a chance for the framing
   // and the comparison to disagree about what they measured.
   const prepared = sets.map((set) => prepareSet(located.root, set, posable, options.as, poseOptions));
+  // 🔒 A pose that is not finite is refused before anything measures it (issue
+  // #873), in the words `render` and the geometry export use for it. Measured
+  // on a planted bone at x=1e309 before this: an overflowing root read "posed no
+  // drawable attachment", one at -1e309 "drew no pixel", and one at +1e309 or a
+  // rotation at 1e309 exited 0 with MAE 1.00 — the part missing from every
+  // frame, and nothing said why.
+  const posed = prepared.filter((p) => p.missing === null);
+  const overflow = posed.some((p) =>
+    p.frames.some((frame) => frame.pieces.some((piece) => piece.world.some((value) => !Number.isFinite(value)))),
+  );
+  if (overflow) {
+    const found = nonFinitePoseOf(
+      posable.data,
+      options.skin,
+      posed.map((p) => ({ animation: p.candidateAnimation, fps: p.set.fps })),
+    );
+    if (found === null) {
+      throw new Error('a drawn piece of the candidate is not finite and no bone or vertex of its pose is — the two were posed differently');
+    }
+    throw new CheckError(`the candidate is posed to a number that is not finite, so no frame of it can be compared: ${found}`);
+  }
   const pairs = prepared.flatMap((p) => p.pairs);
   if (pairs.length === 0) {
     notes.push('no reference frame has a candidate frame at the same index — nothing below was measured');

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,59 @@ 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 factor 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.
+ *
+ * 🔍 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.
+ */
+const POLISH_SCALE_ESCAPE = 2 ** (1 / (2 * SCALE_STEPS_PER_OCTAVE));
 
 /** Sample budgets per stage. The reported residual uses every pixel regardless. */
 const COARSE_SAMPLES = 96;
@@ -284,8 +347,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.074,
+  rateAbove: 0.765,
 };
 
 /** Which side of `POSE_FLOOR` a part is on, from its own longest side in part pixels and its detail. */
@@ -331,8 +394,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 +633,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 +1222,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 +1297,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 +1717,7 @@ export function estimatePose(options: PoseOptions): PoseReport {
         maxResidual,
         { min: scaleMin, max: scaleMax },
         rotationBounds,
+        options.trace,
       ),
     );
   }
@@ -1569,6 +1734,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 +1932,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_ESCAPE] : [], 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 +1945,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 +2023,7 @@ function placePart(
           true,
           scaleBounds,
           rotationBounds,
+          [],
         ),
       );
     }
@@ -1822,6 +2034,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,127 @@ 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;
+}
+
+/**
+ * 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 +1792,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 +1819,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);
 }