spine-rigc 1.3.0 → 1.4.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

@@ -145,6 +145,10 @@ import {
   FRAMES_SIDECAR,
   FRAMES_SPEC,
   framingViewport,
+  GEOMETRY_FILE,
+  GeometryError,
+  geometryFileOf,
+  geometryText,
   loadPosable,
   PROTOCOL_FPS,
   renderFrame,
@@ -153,6 +157,7 @@ import {
   SETUP_POSE_DIR,
   SHEET_FILE,
   SHEET_TILE,
+  sidecarViewport,
   SlotSubsetError,
   slotSubsetOf,
   type Frame,
@@ -259,7 +264,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 +2015,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}`);
@@ -2043,8 +2066,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 +2106,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 +2119,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 +2137,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`);
@@ -3808,6 +3844,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 +4188,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 +4539,13 @@ 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.
+  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,31 @@ 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
+  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.
 - **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.
@@ -827,6 +853,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 +948,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
@@ -6262,6 +6293,119 @@ 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 naming the frame, the slot, the attachment and the vertex,
+rather than written as `null`.
+
+**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 +8732,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; 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
 
 - **above the floor** — a 200x150 black-and-white checker the frame does not hold:
 
@@ -8615,24 +8759,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) | 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) |
+| `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 | 2/3 | 0 | 1 | 0 |
+| 0.5–0.75 | 44/81 | 16 | 21 | 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 |
 
 **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 +8798,42 @@ 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, **8.2%**
+of the trials were found (10/122); at or over it, **72.8%** (217/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).
+
+⚠️ **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
+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
+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 this change was made for.
 
 ## 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.4.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

@@ -518,6 +518,37 @@ export interface EmitPage {
  * ([`src/validate.ts`](validate.ts)) and `artUvsOf`
  * ([`src/render.ts`](render.ts)), which returns no art UVs for a turned region
  * attachment, so `check`'s texture substitution would report it unmatched.
+ *
+ * 📏 **Measured again for issue #866, on twelve region sets, and held back again.**
+ * The sets are the two painting rigs above and ten production rigs of 20 to 22
+ * parts. Each was packed by this file's own search at padding 2 twice: as
+ * shipped, and with every cell also tried turned under the same BSSF score
+ * (ties go to the unturned cell). The shipped search reproduced the page every
+ * one of the twelve atlases was written at. Area change from turning:
+ *
+ *   | set | `pot` | `pot` + turn | `free` | `free` + turn |
+ *   | --- | --- | --- | --- | --- |
+ *   | 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` 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
+ * 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.
  */
 export const PACK_NO_ROTATE = 0;
 

package/src/pose.ts

@@ -116,15 +116,63 @@ export const COARSE_LONG_SIDE = 40;
  */
 export const COARSE_PART_SPAN = 10;
 
+/**
+ * Pixels the part's SHORT side must still span at the coarse level — the same
+ * argument as `COARSE_PART_SPAN`, applied to the axis that rule does not read.
+ *
+ * ⚠️ Found by the change that tightened the coarse grid (issue #865), not by the
+ * floor grid, whose parts are none of them thin enough to reach it. MOTION.md
+ * §6's 60x14 signal arm is 3.5 px thick at the 4x level its length chose; on the
+ * quarter-span grid an anchor cell happened to sit where refinement found its
+ * truth (residual 0.0305), and on the eighth-span grid none did, so pose B
+ * reported a placement 15 px down the arm at 0.1482. A part three pixels thick
+ * at the coarse level has no across-the-part signal for any grid to read. 4, 5
+ * and 6 were each measured to move that arm up one level and place it; 4 is the
+ * least, and at 4 no trial of the floor grid moves at all.
+ */
+const COARSE_PART_THICKNESS = 4;
+
 /**
  * Coarse anchor positions are stepped at a fraction of the part's own size.
  *
- * The objective varies over distances of order the part, not of order a pixel, so
- * scanning every pixel of the coarse level buys resolution the refinement stages
- * supply anyway — and it is what makes the scan's cost grow with the frame's area
- * instead of with the number of places the part could plausibly be.
+ * Scanning every pixel of the coarse level would make the scan's cost grow with
+ * the frame's area instead of with the number of places the part could plausibly
+ * be, so the anchors are strided. How far apart is the part's own business.
+ *
+ * ⚠️ An eighth, not the quarter it was, and the reason is measured rather than
+ * assumed (issue #865). "The objective varies over distances of order the part"
+ * is true of a solid part and false of a thin or holey one: a gun whose material
+ * is a third of its box, or a fist with gaps between the fingers, loses most of
+ * its fit a quarter-span off its truth. On `tools/pose_floor.ts`'s grid, 65
+ * failed trials had a truth that scored better than the answer reported and was
+ * missing from the final list; in 38 of them the truth, evaluated exactly at the
+ * coarse level, beat every cell of its scale rung, and the anchor CELL holding it
+ * did not — the basin fell between two anchors. A cutoff on how many minima
+ * survive (3 of the 65) was not what lost them. At an eighth the grid found
+ * 226 of 420 trials against 185 (with `MINIMA_PER_SCALE` still at three), and
+ * 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.
+ */
+export const COARSE_STRIDE_FRACTION = 0.125;
+
+/**
+ * Grid cells around a coarse cell that must not beat it for it to be a minimum,
+ * and the spacing kept between the minima one scale rung sends down.
+ *
+ * Four at an eighth-span stride is, nominally, the half-span the old two cells
+ * at a quarter held (the stride is rounded to whole level pixels, so only
+ * nominally). Measured on the grid: leaving it at two when the stride halved let one
+ * wrong hill fill a rung's `MINIMA_PER_SCALE` with its own neighbours — 223
+ * trials found rather than 226, and 12 that placed on the old grid lost rather
+ * than 9 (both at three minima per rung).
  */
-export const COARSE_STRIDE_FRACTION = 0.25;
+const COARSE_SUPPRESSION_CELLS = 4;
 
 /** How many scale rungs one octave gets in the coarse ladder. */
 export const SCALE_STEPS_PER_OCTAVE = 3;
@@ -180,8 +228,20 @@ export const BACKGROUND_TOLERANCE = 10;
 /** Share of the frame's border ring one colour must hold before it is called the background. */
 export const BACKGROUND_BORDER_SHARE = 0.6;
 
-/** How many distinct places each coarse scale rung sends down for refinement. */
-const MINIMA_PER_SCALE = 3;
+/**
+ * How many distinct places each coarse scale rung sends down for refinement.
+ *
+ * ⚠️ Five rather than three, and read off the grid rather than off a probe
+ * (issue #865). The card's own probe raised this to ten and recovered the fist it
+ * was chasing; on the full grid that bought 2 trials net (3 gained, 1 lost),
+ * because only 3 of the 65 trials the search missed had their truth's basin
+ * ranked under the cutoff — the rest had fallen between anchor cells, which is
+ * `COARSE_STRIDE_FRACTION`'s job. With the stride fixed, one miss of that kind was
+ * left (a 48 px fist, its basin fifth on its rung), and five is the count that
+ * carries it: 227 trials found against 226 at three, none lost, and a CPU cost
+ * inside the grid's run-to-run noise.
+ */
+const MINIMA_PER_SCALE = 5;
 
 /** How many candidates survive each refinement level. */
 const REFINE_CANDIDATES = 12;
@@ -224,8 +284,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.066,
-  rateAbove: 0.594,
+  rateBelow: 0.082,
+  rateAbove: 0.728,
 };
 
 /** Which side of `POSE_FLOOR` a part is on, from its own longest side in part pixels and its detail. */
@@ -266,8 +326,13 @@ export function legibilityReading(l: Omit<PoseLegibility, 'reading'>, verdict: '
   // ⚠️ "Above the floor" is not "the search found the right hill". Measured on
   // the floor's own material, a part above it came back ambiguous between two
   // equally WRONG placements (residual 0.148 each, 173 px off) while the truth
-  // scored 0.035 — a basin the coarse pass never sent down. So the sentence
-  // names that reading too, with the one remedy that separates it: a window.
+  // scored 0.035 — a basin the coarse pass never sent down. Issue #865 fixed
+  // that one (the coarse grid had stepped over it), and the reading still
+  // 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.
   return (
     `${figures} — above the measured floor (AUTHORING §11.5: ${floorClause()}), so size and texture do not explain this; ` +
     (verdict === 'refused'
@@ -1623,9 +1688,18 @@ function placePart(
   // only about the frame. The pyramid stops when the frame fits in
   // COARSE_LONG_SIDE; this then walks back UP it until the part still spans
   // COARSE_PART_SPAN pixels there, because a level that has reduced the part to
-  // three pixels cannot say where the part is at any price.
+  // three pixels cannot say where the part is at any price — and until its short
+  // side still spans COARSE_PART_THICKNESS, which is the same sentence about a
+  // part that is long and thin.
   let coarseIndex = levels.length - 1;
-  while (coarseIndex > 0 && (span * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_SPAN) coarseIndex--;
+  const thickness = Math.min(tw, th);
+  while (
+    coarseIndex > 0 &&
+    ((span * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_SPAN ||
+      (thickness * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_THICKNESS)
+  ) {
+    coarseIndex--;
+  }
   const coarse = levels[coarseIndex];
   const spanAtCoarse = (span * scaleReference) / coarse.reduction;
   const stride = Math.max(1, Math.round(spanAtCoarse * COARSE_STRIDE_FRACTION));
@@ -1635,7 +1709,7 @@ function placePart(
   for (const scale of scales) {
     const field = coarseScan(coarse, coarseSamples, scale, searchRotations, stride);
     grid = { reduction: coarse.reduction, cols: field.cols, rows: field.rows, stride };
-    candidates.push(...localMinima(field, 2, MINIMA_PER_SCALE));
+    candidates.push(...localMinima(field, COARSE_SUPPRESSION_CELLS, MINIMA_PER_SCALE));
   }
   base.coarse = grid;
   candidates.sort((a, b) => a.residual - b.residual);

package/src/render.ts

@@ -336,6 +336,17 @@ export interface PoseOptions {
    * one instrument that does (`bonedist.ts`) needs it on every frame.
    */
   bones?: boolean;
+  /**
+   * Also record every slot's attachment geometry, whole — see `AttachmentPose`
+   * and `Frame.attachments` (issue #864). Off by default for `bones`' reason:
+   * nothing that draws reads it, and `render --geometry` is the one caller.
+   *
+   * ⭐ **It is not filtered by `slots`/`hidden` and not cut by a clip.** Those
+   * are statements about which pixels are drawn; the geometry is a statement
+   * about where the pose put each attachment, and it is the same pose whatever
+   * a picture of it leaves out.
+   */
+  geometry?: boolean;
   /**
    * Pose under this skin, by the name the skeleton declares for it.
    *
@@ -635,6 +646,44 @@ export interface Frame {
    * the two rigs.
    */
   bones?: BoneSnapshot[];
+  /**
+   * Every slot's attachment as the pose left it, in draw order — present only
+   * when `PoseOptions.geometry` asked for it (issue #864).
+   *
+   * ⚠️ Not `pieces` again. A piece is what gets DRAWN: `--slot`/`--hide` remove
+   * pieces and a clip replaces one with the clipper's own triangle list, whose
+   * vertices are not the attachment's and are not numbered like them. A
+   * consumer comparing a triangle's edges across frames needs vertex `i` to be
+   * the same vertex in every frame, so these are the attachment's own vertices,
+   * whole, for every slot that shows a region or a mesh.
+   *
+   * Read off the same skeleton at the same step as `pieces` and `bones`, which
+   * is what puts it on render's frame grid by construction rather than by a
+   * second derivation of it.
+   */
+  attachments?: AttachmentPose[];
+}
+
+/**
+ * One slot's region or mesh attachment in one posed frame (issue #864).
+ *
+ * `vertices` come from the runtime's own `computeWorldVertices` over the whole
+ * attachment — the call `pieceOf` makes, through the one helper both share —
+ * so skinning and deform live in spine-core and nowhere here.
+ */
+export interface AttachmentPose {
+  slot: string;
+  /** The attachment's own name, which is what a deform or attachment timeline keys. */
+  attachment: string;
+  /**
+   * World positions, `x, y` per vertex, **y up**. A region's four corners are in
+   * spine-core's order — bottom-left, top-left, top-right, bottom-right — and a
+   * mesh's vertices in the attachment's own order, so index `i` names the same
+   * vertex in every frame.
+   */
+  vertices: number[];
+  /** Slot colour x attachment colour, straight alpha, 0..1 — the piece's `tint`, by the same arithmetic. */
+  color: [number, number, number, number];
 }
 
 /** Where the world sits in a frame: the four world numbers plus the scale. */
@@ -732,6 +781,7 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
       time: i * step,
       pieces: piecesOf(skeleton, pieceOpts),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
+      ...(opts?.geometry ? { attachments: attachmentsOf(skeleton) } : {}),
     });
   }
   return frames;
@@ -746,20 +796,31 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
  * whole content is the setup pose.
  */
 export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[] {
-  const skeleton = skeletonUnderSkin(data, opts?.skin);
-  skeleton.setupPose();
-  skeleton.update(0);
-  skeleton.updateWorldTransform(Physics.reset);
+  const skeleton = setupPosed(data, opts?.skin);
   return [
     {
       index: 0,
       time: 0,
       pieces: piecesOf(skeleton, piecesOptions(opts)),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
+      ...(opts?.geometry ? { attachments: attachmentsOf(skeleton) } : {}),
     },
   ];
 }
 
+/**
+ * A fresh skeleton under `skin`, stepped into its setup pose — the one recipe
+ * `sampleSetupPose` and the geometry export's `rest` table both pose from, so
+ * the two cannot come to describe different rest poses.
+ */
+function setupPosed(data: SkeletonData, skin: string | undefined): Skeleton {
+  const skeleton = skeletonUnderSkin(data, skin);
+  skeleton.setupPose();
+  skeleton.update(0);
+  skeleton.updateWorldTransform(Physics.reset);
+  return skeleton;
+}
+
 /**
  * Every animation of one skeleton at one rate, keyed by the name its frames are
  * filed under. A skeleton with no animation at all contributes its setup pose
@@ -877,14 +938,7 @@ function pieceOf(
         'the attachment names a region the atlas does not have',
     );
   }
-  const colour = pose.color;
-  const own = attachment.color;
-  const tint: [number, number, number, number] = [
-    colour.r * own.r,
-    colour.g * own.g,
-    colour.b * own.b,
-    colour.a * own.a,
-  ];
+  const tint = tintOf(slot, attachment);
   // The dark colour is the SLOT's alone — an attachment has a `color` and no
   // dark one, so there is nothing to multiply it by. Read off `appliedPose`
   // like the light colour, so an `rgba2` timeline reaches the picture.
@@ -897,18 +951,11 @@ function pieceOf(
 
   let piece: Piece;
   let triangles: number[];
+  const world = worldVerticesOf(skeleton, slot, attachment);
   if (isMesh) {
-    // `worldVerticesLength` is 2 per vertex whether or not the mesh is
-    // weighted — the weight runs live in `vertices`, not here — so this is the
-    // full output length and the whole mesh is computed in one call. Deform
-    // offsets, if the pose carries any, are applied inside it.
-    const world = new Array<number>(attachment.worldVerticesLength).fill(0);
-    attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, world, 0, 2);
     triangles = attachment.triangles;
     piece = { kind: 'mesh', ...common, texture, world, uvs, triangles };
   } else {
-    const world = new Array<number>(8).fill(0);
-    attachment.computeWorldVertices(slot, attachment.getOffsets(pose), world, 0, 2);
     triangles = QUAD_TRIANGLES;
     piece = { kind: 'region', ...common, texture, world, uvs };
   }
@@ -916,6 +963,56 @@ function pieceOf(
   return clippedPiece(piece, triangles, uvs, clipper);
 }
 
+/** Slot colour x attachment colour, straight alpha — what a piece is tinted by and a geometry entry records. */
+function tintOf(slot: Slot, attachment: MeshAttachment | RegionAttachment): [number, number, number, number] {
+  const colour = slot.appliedPose.color;
+  const own = attachment.color;
+  return [colour.r * own.r, colour.g * own.g, colour.b * own.b, colour.a * own.a];
+}
+
+/**
+ * One attachment's world vertices on `slot`, whole, by the runtime's own routine.
+ *
+ * The one place either kind is asked for them: `pieceOf` draws what this returns
+ * and `attachmentsOf` records it, so a drawn frame and its geometry export
+ * cannot disagree about where a vertex is.
+ *
+ * `worldVerticesLength` is 2 per vertex whether or not the mesh is weighted —
+ * the weight runs live in `vertices`, not here — so this is the full output
+ * length and the whole mesh is computed in one call. Deform offsets, if the
+ * slot's pose carries any, are applied inside it; a region's offsets are read
+ * for the sequence frame the slot's pose resolves.
+ */
+function worldVerticesOf(skeleton: Skeleton, slot: Slot, attachment: MeshAttachment | RegionAttachment): number[] {
+  if (attachment instanceof MeshAttachment) {
+    const world = new Array<number>(attachment.worldVerticesLength).fill(0);
+    attachment.computeWorldVertices(skeleton, slot, 0, attachment.worldVerticesLength, world, 0, 2);
+    return world;
+  }
+  const world = new Array<number>(8).fill(0);
+  attachment.computeWorldVertices(slot, attachment.getOffsets(slot.appliedPose), world, 0, 2);
+  return world;
+}
+
+/**
+ * Every slot's region or mesh attachment, whole, in the posed draw order — see
+ * `Frame.attachments`. No subset and no clip: those are `piecesOf`'s business.
+ */
+function attachmentsOf(skeleton: Skeleton): AttachmentPose[] {
+  const out: AttachmentPose[] = [];
+  for (const slot of skeleton.drawOrder.appliedPose) {
+    const attachment = slot.appliedPose.attachment;
+    if (!(attachment instanceof MeshAttachment) && !(attachment instanceof RegionAttachment)) continue;
+    out.push({
+      slot: slot.data.name,
+      attachment: attachment.name,
+      vertices: worldVerticesOf(skeleton, slot, attachment),
+      color: tintOf(slot, attachment),
+    });
+  }
+  return out;
+}
+
 /**
  * `piece` as the active clip leaves it, or `piece` itself when the clipper cut
  * nothing — see `piecesOf`.
@@ -951,6 +1048,262 @@ function clippedPiece(piece: Piece, triangles: number[], uvs: Float32Array, clip
   return { kind: 'mesh', tint, dark, slot, page, texture, world, uvs: clippedUvs, triangles: clipped };
 }
 
+// ---------------------------------------------------------------------------
+// the geometry export — `render --geometry` (issue #864)
+// ---------------------------------------------------------------------------
+//
+// ⭐ A frame set is pixels, and two judgements a consumer that does not link
+// spine-core wants to make are not about pixels: how far a mesh triangle is
+// stretched over its rest shape, and whether a region holds still in its own
+// bone's frame. Both need the numbers the pose was drawn FROM. So `render` writes
+// them beside the pictures, off the very `Frame`s it drew — one call, one frame
+// grid, one viewport — rather than a second command re-deriving any of the three.
+
+/** The export's file name inside an animation's frame directory, and its format tag. */
+export const GEOMETRY_FILE = 'geometry.json';
+export const GEOMETRY_SPEC = 'rigc-geometry/1';
+/** Stated in the file, so a reader cannot take the numbers for frame pixels. */
+export const GEOMETRY_COORDINATES = 'spine world, y up, world units';
+
+/** A geometry file's frame: `Frame` reduced to the numbers the export promises. */
+export interface GeometryFrame {
+  index: number;
+  time: number;
+  bones: GeometryBone[];
+  attachments: AttachmentPose[];
+}
+
+/** One bone's world transform: `world = [a b; c d]·local + (worldX, worldY)`. */
+export interface GeometryBone {
+  name: string;
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  worldX: number;
+  worldY: number;
+}
+
+/**
+ * One attachment's rest geometry and its topology — the half of a stretch ratio
+ * no frame carries.
+ *
+ * ⭐ **Rest is the setup pose's bones with no deform**, taken for every
+ * attachment any frame of 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, these vertices are the `setup` entry's own, bit for bit: both come off
+ * one skeleton posed by `setupPosed`.
+ */
+export interface AttachmentRest {
+  slot: string;
+  attachment: string;
+  kind: 'region' | 'mesh';
+  vertices: number[];
+  /** Vertex index triplets. A region's are the runtime's own `0 1 2 2 3 0`. */
+  triangles: number[];
+  /** A mesh's hull vertex count — the first `hull` vertices, as the format's `hull` field counts them. */
+  hull?: number;
+  /** A mesh's `uvs`, `u, v` per vertex over the untrimmed drawing, y down — the attachment's own, not a page's. */
+  uvs?: number[];
+}
+
+export interface GeometryFile {
+  spec: string;
+  coordinates: string;
+  /** The animation, or `null` for a skeleton with none (its one frame is the setup pose). */
+  animation: string | null;
+  skin?: string;
+  fps: number;
+  /** The box the PNG frames beside this file were drawn over — `frames.json`'s own `viewport`. */
+  viewport: FramesSidecar['viewport'];
+  /** Every bone in the skeleton's declaration order, and its parent's name. */
+  bones: Array<{ name: string; parent: string | null }>;
+  /**
+   * Every slot in the skeleton's declaration order, and the bone it hangs from —
+   * which is the bone whose frame "still in its own bone's frame" is read in.
+   */
+  slots: Array<{ name: string; bone: string }>;
+  rest: AttachmentRest[];
+  /** The setup pose, sampled the way `sampleSetupPose` samples it. */
+  setup: Omit<GeometryFrame, 'index' | 'time'>;
+  frames: GeometryFrame[];
+}
+
+/**
+ * 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.
+ */
+export class GeometryError extends Error {}
+
+/** `frames.json`'s viewport block for `v` — the one spelling both files use. */
+export function sidecarViewport(v: Viewport): FramesSidecar['viewport'] {
+  return {
+    x: v.minX,
+    y: v.minY,
+    width: v.maxX - v.minX,
+    height: v.maxY - v.minY,
+    scale: v.scale,
+    pixelWidth: v.width,
+    pixelHeight: v.height,
+  };
+}
+
+/**
+ * The geometry file for one frame set — `frames` exactly as a sampler returned
+ * them with `{ bones: true, geometry: true }`, which is what makes its grid the
+ * frame set's own.
+ *
+ * Refused by `GeometryError`, naming the frame, the slot, the attachment and the
+ * vertex (or the bone), when any number in it is not finite.
+ */
+export function geometryFileOf(
+  data: SkeletonData,
+  animation: string | null,
+  fps: number,
+  frames: Frame[],
+  viewport: Viewport,
+  skin: string | undefined,
+): GeometryFile {
+  const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
+    if (frame.bones === undefined || frame.attachments === undefined) {
+      throw new Error(`${where} was sampled without { bones: true, geometry: true }; the geometry export needs both`);
+    }
+    return {
+      bones: frame.bones.map(({ name, a, b, c, d, worldX, worldY }) => ({ name, a, b, c, d, worldX, worldY })),
+      attachments: frame.attachments,
+    };
+  };
+  const posed = frames.map((frame) => ({
+    index: frame.index,
+    time: frame.time,
+    ...geometryFrame(frame, `frame ${frame.index}`),
+  }));
+  const setupFrame = sampleSetupPose(data, { ...(skin === undefined ? {} : { skin }), bones: true, geometry: true })[0];
+  const setup = geometryFrame(setupFrame, 'the setup pose');
+  const file: GeometryFile = {
+    spec: GEOMETRY_SPEC,
+    coordinates: GEOMETRY_COORDINATES,
+    animation,
+    ...(skin === undefined ? {} : { skin }),
+    fps,
+    viewport: sidecarViewport(viewport),
+    bones: data.bones.map((bone) => ({ name: bone.name, parent: bone.parent?.name ?? null })),
+    slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
+    rest: restOf(data, skin, [setup.attachments, ...posed.map((frame) => frame.attachments)]),
+    setup,
+    frames: posed,
+  };
+  refuseNonFinite(file);
+  return file;
+}
+
+/**
+ * The rest table: every (slot, attachment) the given frames show, in order of
+ * first appearance, posed on one setup skeleton with the slot's deform empty.
+ *
+ * The attachment is resolved the way the pose resolved it — `Skeleton.getAttachment`,
+ * the skin first and the default skin second — so a name means the object the
+ * frames drew. A region's rest corners are read for the sequence frame the setup
+ * pose resolves, which is the frame its setup pose draws.
+ */
+function restOf(data: SkeletonData, skin: string | undefined, shown: AttachmentPose[][]): AttachmentRest[] {
+  const skeleton = setupPosed(data, skin);
+  // Slot, then attachment: two maps rather than one joined key, so no pair of
+  // names can fold into another's entry whatever characters they carry.
+  const seen = new Map<string, Set<string>>();
+  const out: AttachmentRest[] = [];
+  for (const entries of shown) {
+    for (const entry of entries) {
+      const names = seen.get(entry.slot) ?? new Set<string>();
+      if (names.has(entry.attachment)) continue;
+      names.add(entry.attachment);
+      seen.set(entry.slot, names);
+      const slotIndex = data.findSlot(entry.slot)?.index ?? -1;
+      const slot = skeleton.slots[slotIndex];
+      const attachment = slot === undefined ? null : skeleton.getAttachment(slotIndex, entry.attachment);
+      if (slot === undefined || !(attachment instanceof MeshAttachment || attachment instanceof RegionAttachment)) {
+        throw new Error(
+          `slot ${JSON.stringify(entry.slot)} showed attachment ${JSON.stringify(entry.attachment)} in a frame, and ` +
+            'the setup skeleton resolves no region or mesh of that name there',
+        );
+      }
+      // A mesh reads the slot's deform array; the setup pose leaves it empty,
+      // and emptying it here says so rather than trusting that it is.
+      slot.appliedPose.deform.length = 0;
+      const vertices = worldVerticesOf(skeleton, slot, attachment);
+      out.push(
+        attachment instanceof MeshAttachment
+          ? {
+              slot: entry.slot,
+              attachment: entry.attachment,
+              kind: 'mesh',
+              vertices,
+              triangles: Array.from(attachment.triangles),
+              hull: attachment.hullLength / 2,
+              uvs: Array.from(attachment.regionUVs),
+            }
+          : { slot: entry.slot, attachment: entry.attachment, kind: 'region', vertices, triangles: [...QUAD_TRIANGLES] },
+      );
+    }
+  }
+  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`);
+        }
+      }
+    }
+    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`,
+      );
+    }
+  };
+  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);
+}
+
+/**
+ * The file's text: a JSON object whose header fields sit one per line and whose
+ * `rest` entries and `frames` sit one per line each, so a diff of two exports
+ * names the frame that moved.
+ *
+ * Numbers are `JSON.stringify`'s, which is how every JSON this tree writes prints
+ * them — the shortest decimal that reads back as the same double, fixed by the
+ * language rather than a locale — so a vertex in the file IS the runtime's
+ * vertex, not a rounding of it.
+ */
+export function geometryText(file: GeometryFile): string {
+  const lines: string[] = [];
+  const entries = Object.entries(file);
+  entries.forEach(([key, value], i) => {
+    const comma = i + 1 < entries.length ? ',' : '';
+    if ((key === 'rest' || key === 'frames') && Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`  ${JSON.stringify(key)}: []${comma}`);
+        return;
+      }
+      lines.push(`  ${JSON.stringify(key)}: [`);
+      value.forEach((item, j) => lines.push(`    ${JSON.stringify(item)}${j + 1 < value.length ? ',' : ''}`));
+      lines.push(`  ]${comma}`);
+      return;
+    }
+    lines.push(`  ${JSON.stringify(key)}: ${JSON.stringify(value)}${comma}`);
+  });
+  return `{\n${lines.join('\n')}\n}\n`;
+}
+
 // ---------------------------------------------------------------------------
 // texture-only substitution — see `substituteTexture`
 // ---------------------------------------------------------------------------
@@ -1347,7 +1700,9 @@ export function framingViewport(data: SkeletonData, maxSide: number, opts?: Pose
   // A clip is taken off for the same reason (issue #844): what it removes still
   // counts toward the box, so adding or keying a mask moves no pixel it leaves
   // drawn — see `PoseOptions.unclipped`.
-  const { slots: _drawn, hidden: _hidden, ...whole } = opts ?? {};
+  // Neither the bone snapshots nor the geometry export frame anything, and
+  // both would be taken at `FRAMING_FPS` for every animation only to be dropped.
+  const { slots: _drawn, hidden: _hidden, bones: _bones, geometry: _geometry, ...whole } = opts ?? {};
   const framed: PoseOptions = { ...whole, unclipped: true };
   const sets =
     data.animations.length === 0