spine-rigc 1.3.0 → 1.5.0

package/README.md

@@ -535,7 +535,7 @@ commands take it and what its default is.
 | `validate <dir>` | re-gates artifacts already on disk |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |

package/cli.ts

@@ -103,7 +103,6 @@ import {
   DEFAULT_PADDING,
   DEFAULT_PAGE_EDGES,
   DEFAULT_PAGE_SIZE,
-  FREE_EDGE_STEP,
   PAGE_EDGES,
   packAtlas,
   type PageEdges,
@@ -145,6 +144,10 @@ import {
   FRAMES_SIDECAR,
   FRAMES_SPEC,
   framingViewport,
+  GEOMETRY_FILE,
+  GeometryError,
+  geometryFileOf,
+  geometryText,
   loadPosable,
   PROTOCOL_FPS,
   renderFrame,
@@ -153,6 +156,7 @@ import {
   SETUP_POSE_DIR,
   SHEET_FILE,
   SHEET_TILE,
+  sidecarViewport,
   SlotSubsetError,
   slotSubsetOf,
   type Frame,
@@ -259,7 +263,7 @@ function repositoryUrl(): string {
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -2010,6 +2014,24 @@ function cmdRender(flags: Record<string, string>): void {
   const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   const outRoot = resolve(flags.out ?? 'render');
+  const geometry = flags.geometry !== undefined;
+  // Refused together rather than one of them ignored (issue #864). The export
+  // records every slot's whole geometry, because a subset is a statement about
+  // which pixels are DRAWN and the pose is the same whatever a picture leaves
+  // out — so a geometry.json beside a subset's frames would describe slots
+  // those frames do not draw, and one that dropped them would stop being the
+  // pose. The whole-rig run writes the same file either way.
+  if (geometry) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--geometry takes no --${flag}: it records every slot's whole geometry, which a subset of the drawn slots ` +
+            `does not change. Run \`rigc render --geometry\` on the whole rig for the file, and --${flag} ` +
+            `${flags[flag]} without --geometry for the pictures — both land on the same grid`,
+        );
+      }
+    }
+  }
 
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
@@ -2031,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(
@@ -2043,8 +2068,24 @@ function cmdRender(flags: Record<string, string>): void {
   // `sampleAll` covers the skeleton with no animation at all, which files its one
   // setup-pose frame under the reserved name. Narrowing to one animation reuses
   // the same sampler rather than a second path through it.
+  //
+  // `--geometry` rides on the SAME call (issue #864): the bones and the whole
+  // attachments are read off the skeleton at the step that drew each frame, so
+  // the export's grid is this frame set's by construction.
+  const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
   const sampled: Map<string, Frame[]> =
-    only === undefined ? sampleAll(data, fps, pose) : new Map([[only, sampleAnimation(data, only, fps, pose)]]);
+    only === undefined
+      ? sampleAll(data, fps, sampling)
+      : new Map([[only, sampleAnimation(data, only, fps, sampling)]]);
+  // Every file's text before the first write, so a refused number leaves the
+  // output directory as it was rather than half of a frame set behind it.
+  const geometryTexts = new Map<string, string>();
+  if (geometry) {
+    for (const [name, frames] of sampled) {
+      const animation = name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name;
+      geometryTexts.set(name, geometryText(geometryFileOf(data, animation, fps, frames, viewport, skin)));
+    }
+  }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!declaresSetupStage(data)) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
@@ -2067,6 +2108,8 @@ function cmdRender(flags: Record<string, string>): void {
     // would be the same picture with a border and a "0" on it.
     const sheet = frames.length > 1;
     if (sheet) contactSheet(frames, pages, viewport, SHEET_TILE).writePng(join(dir, SHEET_FILE));
+    const geometryOut = geometryTexts.get(name);
+    if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -2078,7 +2121,8 @@ function cmdRender(flags: Record<string, string>): void {
       duration,
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
-    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${sheet ? ` + ${SHEET_FILE}` : ''} -> ${dir}`);
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}`;
+    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:
@@ -2095,15 +2139,9 @@ function cmdRender(flags: Record<string, string>): void {
     // every slot says nothing and stays the bytes it always was (issue #835).
     ...subsetFields(subset),
     background: BACKGROUND,
-    viewport: {
-      x: viewport.minX,
-      y: viewport.minY,
-      width: viewport.maxX - viewport.minX,
-      height: viewport.maxY - viewport.minY,
-      scale: viewport.scale,
-      pixelWidth: viewport.width,
-      pixelHeight: viewport.height,
-    },
+    // The one spelling `geometry.json` repeats, so the two files cannot state
+    // two boxes for one grid.
+    viewport: sidecarViewport(viewport),
     sets: [...sets].sort((a, b) => a.dir.localeCompare(b.dir)),
   };
   writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
@@ -3789,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':
@@ -3808,6 +3846,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     'derived: a candidate is entitled to its own vocabulary, so a mapping worked out here would be a guess reported ' +
     'as a measurement',
   'all-bones': 'print every bone pair, not just the worst by position',
+  geometry:
+    `also write ${GEOMETRY_FILE} into each frame directory: per frame, every bone's world transform and every ` +
+    "slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry — on the " +
+    'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -4148,10 +4190,10 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'render',
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -4499,6 +4541,14 @@ 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 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);
+  }
   if (err instanceof NotAPngError) {
     console.error(`rigc: ${err.message}`);
     process.exit(1);

package/docs/AUTHORING.md

@@ -209,6 +209,7 @@ What the flags mean:
 | `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 49, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
+| `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -318,6 +319,34 @@ a gap:
   regions `rotate: 90` lifted every region back byte for byte and drew its
   region attachments with 0 differing pixels — and made neither page smaller,
   because both were already on the smallest power-of-two page their area allows.
+  Measured again on twelve region sets (issue #866: those two rigs and ten
+  production rigs of 20 to 22 parts), packing each with the same search twice —
+  as shipped, and with every part also tried turned under the same placement
+  score:
+
+  | Set | `pot` page | turned | `free` page | turned |
+  | --- | --- | --- | --- | --- |
+  | 22-part painting | 1024x2048 | 0.00 % | 1888x697 | −1.14 % |
+  | 20-part painting | 512x2048 | 0.00 % | 480x1166 | +2.31 % |
+  | P1 | 512x2048 | 0.00 % | 416x1633 | +1.43 % |
+  | P2 | 1024x1024 | 0.00 % | 1184x810 | +0.70 % |
+  | P3 | 512x1024 | 0.00 % | 480x1000 | +2.96 % |
+  | P4 | 1024x2048 | 0.00 % | 864x1346 | −6.16 % |
+  | P5 | 2048x2048 | 0.00 % | 1344x1768 | −13.37 % |
+  | P6 | 1024x2048 | 0.00 % | 800x1934 | −1.62 % |
+  | P7 | 512x2048 | 0.00 % | 1024x928 | −0.05 % |
+  | P8 | 512x2048 | 0.00 % | 608x1250 | −4.96 % |
+  | P9 | 1024x2048 | +100.00 % | 1024x2037 | +6.51 % |
+  | P10 | 512x2048 | 0.00 % | 352x1433 | +0.70 % |
+
+  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
+  `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.
@@ -357,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
@@ -365,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 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -827,6 +908,7 @@ bun cli.ts check    --candidate path/to/spine --frames path/to/frames [--skin
 bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
 bun cli.ts render   --candidate path/to/spine [--animation …] [--skin …] [--fps 12] [--max 256]
 bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,…>   # part of the rig, same grid
+bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per set: the numbers the frames were drawn from
 bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
 bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
 bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
@@ -921,7 +1003,11 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   in draw order; a slot whose art lives only under another skin is refused naming
   that skin (pass `--skin`); the two flags together are refused. `frames.json`
   records the subset as `slots` or `hidden`, and **`check` refuses such a set as
-  a reference** (§9). `preview`
+  a reference** (§9). `--geometry` writes the numbers each frame was drawn from
+  beside it — every bone's world transform and every attachment's world vertices
+  after skinning, with their rest geometry — for a judgement the pixels cannot
+  make: a mesh triangle's stretch, a region read in its own bone's frame (§8.2).
+  `preview`
   writes one self-contained `.html`: your skeleton, atlas and page PNGs are
   embedded in it as data URIs and played by the official **Spine Web Player**, so
   double-clicking it is also the interop proof — what plays there was played by
@@ -1412,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`:
 
@@ -5328,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.
@@ -6262,6 +6369,124 @@ the loop with **§9**: the fit's own number says how near this pose is to this f
 and only `check` says whether the shot is the shot. **§9.3** is the list of what even
 that cannot see.
 
+### 8.2 The numbers the frames were drawn from — `render --geometry`
+
+A frame set is pixels, and some judgements about a rig are not about pixels: how far
+a mesh triangle is stretched over its rest shape, or whether a region holds still in
+its own bone's frame. Both need the posed numbers, and both need them **on the frames'
+own grid** — a second tool re-sampling the animation would step the runtime its own
+way and drift from the pictures it is meant to explain. So `render --geometry` writes
+them beside the pictures, off the very frames it drew:
+
+```bash
+bun cli.ts render --candidate path/to/spine --geometry [--animation …] [--skin …] [--fps 12]
+```
+
+Each frame directory gains a `geometry.json` beside its `f####.png`. Nothing else
+changes: the PNGs, `contact.png` and `frames.json` are byte for byte what the same
+command writes without the flag. The export costs a small fraction of the render —
+measured on `spineboy-pro` at 12 fps, 190 frames: about 30 ms for the eleven files
+against about 610 ms for the rasterising alone — which is why there is no
+geometry-only mode: a consumer judging frames wants the frames, and skipping them
+would save little.
+
+⛔ **Not with `--slot`/`--hide`.** The two are refused together by name, exit 2,
+nothing written. A subset is a statement about which pixels are *drawn*; the
+geometry is the whole pose whatever a picture leaves out, so beside a subset's frames
+it would describe slots those frames do not draw. The whole-rig run writes the same
+file either way.
+
+**The file, field by field.** `spec` is `rigc-geometry/1`. The header fields sit one
+per line and each `rest` entry and each frame on a line of its own, so a diff of two
+exports names the frame that moved. Two exports of one skeleton are byte-identical.
+
+| Field | What it holds |
+| --- | --- |
+| `coordinates` | the string `spine world, y up, world units` — every position below is in the skeleton's world, not frame pixels |
+| `animation` | the animation, or `null` for a skeleton with none (its one frame is the setup pose) |
+| `skin` | the skin these frames were posed under — absent when none was set, exactly as in `frames.json` |
+| `fps` | the rate the frames were sampled at |
+| `viewport` | `frames.json`'s own `viewport` object, the same numbers: world box `x`, `y`, `width`, `height`, `scale` (frame pixels per world unit), `pixelWidth`, `pixelHeight`. World to frame pixel is `px = (x − viewport.x) · scale`, `py = (viewport.y + viewport.height − y) · scale`, which is the projection the renderer used |
+| `bones` | every bone in declaration order: `{ name, parent }`, `parent` `null` for the root |
+| `slots` | every slot in declaration order: `{ name, bone }` — the bone the slot hangs from |
+| `rest` | one entry per `(slot, attachment)` any frame shows, in order of first appearance: `slot`, `attachment`, `kind` (`region` or `mesh`), `vertices` at rest, `triangles` (vertex index triplets — a region's are the runtime's `0 1 2 2 3 0`), and for a mesh `hull` (the number of hull vertices, which are the first ones) and `uvs` (the attachment's own, `u, v` per vertex over the untrimmed drawing, y down) |
+| `setup` | the setup pose, sampled the way a skeleton with no animation is rendered: `{ bones, attachments }` |
+| `frames` | one per PNG, in index order: `{ index, time, bones, attachments }`. `index` is the number in `f####.png`, `time` is `index / fps` in seconds |
+
+Inside `setup` and each frame:
+
+- `bones` — every bone in declaration order: `{ name, a, b, c, d, worldX, worldY }`,
+  the world transform, so a point `(lx, ly)` in the bone's own frame lands at
+  `(a·lx + b·ly + worldX, c·lx + d·ly + worldY)`. The matrix is complete — rotation,
+  scale and shear all live in `a b c d`.
+- `attachments` — every slot showing a region or a mesh, in the frame's **draw
+  order**: `{ slot, attachment, vertices, color }`. `vertices` are `x, y` per vertex
+  in world units after skinning and deform — the runtime's own
+  `computeWorldVertices` over the **whole** attachment. A region's four are its
+  corners in the order bottom-left, top-left, top-right, bottom-right; a mesh's are
+  in the attachment's own order, so vertex `i` is the same vertex in every frame and
+  in `rest`. `color` is the slot colour times the attachment colour, straight RGBA
+  `0..1` — the same tint the frame was drawn with.
+
+What `rest` means, precisely: the **setup pose's bones with the slot's deform
+empty**, taken for every attachment the file shows — including one the setup pose
+does not show, which a slot only swaps to later. For an attachment the setup pose
+does show, its `rest` vertices and its `setup` vertices are the same numbers bit for
+bit, because they come off one posed skeleton.
+
+⚠️ **What is deliberately not in it.** Slots `--slot`/`--hide` would leave out are in
+it (see above). A clip is not applied: a clipping attachment removes pixels, and the
+clipper's output is a new triangle list whose vertices are not the attachment's and
+are not numbered like them — so `vertices` are the attachment's own, and the frames
+show what the clip left of them. Bounding boxes, points, paths and clipping polygons
+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 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:
+
+1. **Texture stretch of a mesh triangle.** For each `rest` entry of kind `mesh` and
+   each triangle `(i, j, k)` in its `triangles`, over every frame whose `attachments`
+   carry the same `slot` and `attachment`:
+
+   `stretch = max over frames, max over the edges (i,j) (j,k) (k,i) of |posed edge| / |rest edge|`
+
+   where an edge's length is `hypot(x_j − x_i, y_j − y_i)` over that frame's
+   `vertices` and over `rest`'s. The worst triangle is named by its `slot`, its
+   triangle index and its three vertex indices. A value of exactly `1` is a
+   triangle no frame moved. It is measured against rest, so it counts what the
+   bones do to a weighted mesh as well as what a deform key does — unlike the
+   `DEFORM` block, which compares a key against the same bones with the deform
+   cleared.
+2. **A region still in its bone's own frame.** Take the region's `slot`, look its
+   `bone` up in `slots`, and for each frame carry its four corners into that bone's
+   frame by the inverse of the bone's world transform:
+
+   `det = a·d − b·c`, `dx = x − worldX`, `dy = y − worldY`,
+   `lx = (d·dx − b·dy) / det`, `ly = (−c·dx + a·dy) / det`
+
+   Against the same four carried from `setup`, the largest difference over frames is
+   the region's motion *relative to its bone*: zero, to double rounding, for a region
+   nothing but its bone moves. A face region measured against a head bone this way
+   is the face with the head's own turn, translation and scale taken out.
+
+**Measured on the example corpus** at 12 fps (these are one run's figures, not
+thresholds): `spineboy-pro`'s eleven files total 5.1 MB, from 72 kB (`aim`, one
+frame) to 1.46 MB (`death`, 60 frames), and `sack-pro`'s four 1.4 MB. The largest
+stretch is `sack-pro` `fall-in`, `cape-back` triangle 15, ×6.744; the largest
+still-in-frame residual over every region of `spineboy-pro` is 4.7e-12 world units
+(`portal-streaks2`, whose bone scales; `sack-pro` has no region).
+Topology and UVs sit in `rest` rather than on every frame because they do not
+change: repeating them per frame would add 35 % to `spineboy-pro`'s files.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -8588,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; 11 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
+  > 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:
 
@@ -8615,24 +8840,24 @@ 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) | 10/15 (5 amb) | 8/15 (6 amb, 1 wrong) | 11/15 (4 amb) | 9/15 (4 amb, 2 wrong) | 10/15 (4 amb, 1 wrong) | 10/15 (3 amb, 2 wrong) | 12/15 (3 amb) |
-| `blur1` (detail 1.58) | 9/15 (6 amb) | 9/15 (6 amb) | 10/15 (4 amb, 1 wrong) | 8/15 (5 amb, 2 wrong) | 11/15 (2 amb, 2 wrong) | 9/15 (2 amb, 4 wrong) | 9/15 (5 amb, 1 wrong) |
-| `blur2` (detail 0.59) | 6/15 (9 amb) | 9/15 (4 amb, 2 wrong) | 8/15 (4 amb, 3 wrong) | 7/15 (4 amb, 4 wrong) | 8/15 (2 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) | 6/15 (4 amb, 5 wrong) |
-| `flat` (detail 0.00) | 0/15 (14 amb, 1 wrong) | 0/15 (14 amb, 1 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (11 amb, 4 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (12 amb, 3 wrong) | 0/15 (12 amb, 3 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`:
 
 | detail | found | ambiguous | wrong | refused |
 | --- | --- | --- | --- | --- |
-| under 0.25 | 8/119 | 87 | 24 | 0 |
-| 0.25–0.5 | 0/3 | 3 | 0 | 0 |
-| 0.5–0.75 | 46/81 | 15 | 20 | 0 |
-| 0.75–1 | 14/34 | 18 | 2 | 0 |
-| 1–1.5 | 19/25 | 3 | 3 | 0 |
-| 1.5–2 | 29/48 | 16 | 3 | 0 |
-| 2–3 | 27/44 | 14 | 3 | 0 |
-| 3–4 | 25/34 | 7 | 2 | 0 |
-| 4 and over | 17/32 | 14 | 1 | 0 |
+| under 0.25 | 8/119 | 89 | 22 | 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 | 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
@@ -8654,25 +8879,63 @@ 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, **6.6%**
-of the trials were found (8/122); at or over it, **59.4%** (177/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).
 
-⚠️ **What this is and is not.** No cell of the grid placed 90% of its trials (the best
-placed 12/15), so there is no size and texture above which `pose` is reliable, and
-none is claimed. The failures above the edge are the same few parts at every size
-(the gun placed 10 of 42, the goggles 11 of 42), and they are search failures rather
-than plainness: on one of them the true placement scored a lower residual than the two
-wrong answers the search reported. 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 guarantee above it.
+**What the search carries, and why.** The coarse pass scores the part at anchor
+cells an **eighth** of its own span apart, and every scale rung sends its **five**
+best distinct places down to the finer levels. Both were set on this grid (issue
+#865): of the 65 failures whose truth scored better than every answer reported, 38
+had a truth that beat its whole scale rung at the coarse level while the anchor cell
+holding it did not — at a quarter-span stride a thin gun or a gapped fist falls between
+two anchors — and only 3 had it ranked under the old cutoff of three. The finer grid
+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).
+
+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 #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
+guarantee above it.
 
 Re-run it with `bun tools/pose_floor.ts --textures <level> --json <out>` (one level per
 process parallelises it), then `bun tools/pose_floor.ts --from <a.json>,<b.json>,…` to
-print the table and derive the edge. `PO22` in `bun run selftest` re-measures three of
-its cells.
+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 #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.3.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": {