@rig-c/core 2.68.0 → 2.70.0

package/README.md

@@ -137,15 +137,35 @@ writes them into `--out`; `--atlas-in` builds against a pack somebody else made.
 Both are opt-in and both are narrow — no trimming, no rotation, no scaling — and
 [AUTHORING §0.1–§0.2](docs/AUTHORING.md) states the limits before you hit them.
 
-rigc runs on [Bun](https://bun.sh). The package ships its TypeScript sources and
-Bun runs them, so there is no build step and no `dist/` that can drift from the
-repository it was cut from. What is measured is the install itself — pack,
-install into an empty directory, build, render — on Linux, macOS and Windows
-runners and on Linux at the declared minimum, Bun 1.2.0 (the `installs` and
-`installs-matrix` jobs in
+rigc runs on [Bun](https://bun.sh) (`engines.bun` declares `>=1.4.0`). The
+package ships its TypeScript sources and Bun runs them, so there is no build step
+and no `dist/` that can drift from the repository it was cut from. What is
+measured is the install itself — pack, install into an empty directory, build,
+render — on Linux, macOS and Windows runners on the Bun `setup-bun` resolves that
+day (the `installs` and `installs-matrix` jobs in
 [`ci.yml`](https://github.com/rig-c/core/blob/main/.github/workflows/ci.yml),
-repository material, not in the npm package); a platform
-whose leg is red there is not one the package is known to run on.
+repository material, not in the npm package); a platform whose leg is red there
+is not one the package is known to run on. The declared `>=1.4.0` floor itself is
+not pinned in CI — older `1.4.x` releases are untested until a report arrives.
+
+From a source checkout, `bun run verify:nova -- --label "<issue + purpose>"
+--owner "<who>" --session "<session id>" [--bun <version>]` sends the full
+selftest to the Nova pool (`NOVA_RUN` names the runner, or `nova-run.sh` is on
+PATH). `--bun 1.4.0` selects that exact stable release. Before upload, the hand
+fetches Bun's official `SHASUMS256.txt` and checks that the Linux x64 baseline
+archive is available; on the pool it downloads the pinned archive, verifies its
+SHA-256, checks its executable's version, and puts that private Bun first on PATH
+for corpus fetch and selftest. The remote command's first line is
+`verify:nova: Bun 1.4.0`. The temporary runtime is removed on exit. Without
+`--bun`, the pool's Bun and existing command are unchanged; dependency installation
+still uses the pool runner's installation step. The selftest's exit is returned
+unchanged: selecting a runtime does not promise a green run. Memory ceilings
+remain those of that platform and Bun major.minor's tracked row; a missing
+measurement remains a reported HOLE. Malformed, duplicate or missing
+versions, unavailable releases/assets and unreadable checksums are refused by
+name with exit 2 before upload. Use a published exact `X.Y.Z` (no `v` prefix,
+alias, range or prerelease), or retry a failed network fetch. This is repository
+verification tooling, not an installed `rigc` command or a change to CI's matrix.
 
 **The npm package is `rig-c`; the command it installs is `rigc`.** npm
 refuses the name `rigc` as too similar to packages that already exist, so the
@@ -186,6 +206,16 @@ of them: it reads whatever frames you point it at, so it runs from the installed
 package on pictures of your own — which is what *Where to go next* below tells you
 to do with it, and it is the one instrument here that can see a wrong animation.
 
+Programmatic checked consumers can import `rig-c/render-shared`: the official
+candidate chooser (`loadCandidate`, `throughPoser`), setup and animation samplers
+(`sampleSetupPose`, `sampleAnimation`) and raster reads (`pageFor`, `projector`,
+`rasterisePiece`, `renderFrame`), with their argument/result types and named
+failures. It loads without the optional Spine runtime; a Spine input requires
+explicitly loading `rig-c/render`, whose eager runtime dependency is unchanged.
+The promised scope and planned first minor release are in
+[RELEASING.md, The import surface](https://github.com/rig-c/core/blob/main/RELEASING.md#the-import-surface);
+[AUTHORING §0.5](docs/AUTHORING.md#05-reading-a-build-from-code) shows the call chain.
+
 ### Install it into your agent
 
 The guides under [Documentation](#documentation) also ship as
@@ -606,7 +636,7 @@ commands take it and what its default is.
 | `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 |
 | `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
 | `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/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--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. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--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. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's |
 | `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/bin/rigc.cjs

@@ -56,8 +56,8 @@ const entry = present === null ? 'cli_core.ts' : 'cli.ts';
 const args = process.argv.slice(2);
 const result = spawnSync('bun', [path.join(root, entry), ...args], { stdio: 'inherit' });
 
-// ⚠️ The exit and the signal are read before `error` (issue #1488): Bun 1.2.0 —
-// the declared minimum, and what runs this file as `bun bin/rigc.cjs` — sets
+// ⚠️ The exit and the signal are read before `error` (issue #1488): Bun 1.2.0
+// (then the declared minimum, and what ran this file as `bun bin/rigc.cjs`) sets
 // `error` on every child that exits non-zero, so reading it first answered the
 // CLI's own refusal (exit 2) with "could not launch bun" and exit 1. `error` is
 // a launch that failed only where the child left neither a status nor a signal.

package/docs/AUTHORING.md

@@ -75,6 +75,27 @@ which is also repository material and not in the published package,
 *What a run may read* — the prompt that starts a run quotes them
 outright, which is the copy that binds.
 
+Repository maintainers can run the full selftest on Nova with
+`bun run verify:nova -- --label "<issue + purpose>" --owner "<who>"
+--session "<session id>" [--bun <version>]`. This is checkout tooling, not an
+installed `rigc` command. `NOVA_RUN` names `nova-run.sh`, or it is found on PATH.
+Without `--bun` the pool's runtime and command are unchanged. With `--bun 1.4.0`,
+the remote command's first line reads `verify:nova: Bun 1.4.0`; both corpus fetch
+and selftest use that privately downloaded runtime, removed on exit. The runner's
+dependency installation step still uses the pool's Bun.
+The selftest's exit is returned unchanged, including a failure under the chosen
+runtime. Memory ceilings still use that platform and Bun major.minor's tracked
+row; selecting a version neither raises a ceiling nor turns a missing measurement
+(a reported HOLE) into a pass.
+
+| `verify:nova` refusal (exit 2) | Repair |
+| --- | --- |
+| `--bun needs a value`, `--bun was given more than once`, or `--bun "<value>": expected an exact stable version X.Y.Z` | State one published exact stable release, e.g. `--bun 1.4.0`; aliases, prefixes, ranges, prereleases and whitespace are refused before upload |
+| `--bun "<version>": cannot fetch …` | The official release manifest or Linux x64 baseline archive is unavailable, or its fetch failed. Choose a published release with that asset or retry with network access to github.com. The pool runner has not been started |
+| `--bun "<version>": Bun's SHASUMS256.txt must name exactly one SHA-256 …` | The official manifest has no unambiguous valid digest for that archive; choose a release whose manifest names it. Refused before upload |
+| `--bun <version>: pinned runtime preparation failed; selftest was not started` | On the pool, check the download, SHA-256, archive extraction and Linux x64 host. The pinned archive must match Bun's official manifest; do not bypass the check |
+| `--bun <version>: downloaded Bun reports <found>; selftest was not started` | The downloaded executable is not the requested runtime; retry a verified official release. No selftest ran under the wrong version |
+
 ## The vocabulary is Spine's
 
 Wherever rigc has no better abstraction it uses **Spine 4.3's own concept, its own
@@ -245,7 +266,7 @@ What the flags mean:
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. The default is one page per part — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1**. `repack` takes it with the same meaning — **§0.4** |
 | `--padding` | `build --pack` only: the gutter each region reserves on every side (default `2`), filled by extending the region's own edge pixels outwards. `0` is not a legal-but-tight choice, it is bleed — **§0.1**. `repack` takes it with the same meaning — **§0.4** |
-| `--page-edges` | `build --pack` only: `pot` (default) or `free`. `pot` keeps both page edges powers of two; `free` sizes the page to the parts — a smaller page, at the cost of region attachments sampling within one least significant bit of the loose build instead of exactly. Any other value is refused by name — **§0.1**. `repack` takes it with the same meaning — **§0.4** |
+| `--page-edges` | `build --pack` only: `pot` (default) or `free`. `pot` keeps both page edges powers of two; `free` sizes the page to the parts — a smaller page, at the cost of region attachments sampling within one least significant bit of the loose build instead of exactly. Any other value is refused by name — **§0.1**. `repack` takes it with the same meaning — **§0.4**. `render --sheet` also takes `pot` (default) or `free` to size the packed sheet pages (`pot` power-of-two edges up to `2048` vs `free` tight edges up to `2048`), and is refused on `render` without `--sheet` — **§8.10** |
 | `--pack-shape` | `build --pack` only: `rect` (default) or `polygon`. `rect` keeps every region's cell apart; `polygon` packs a region that only meshes draw by its emitted hull, so a neighbour may sit inside its rectangle where the hull is not, with the padding kept between footprints. A region attachment's footprint stays its rectangle. Any other value is refused by name, and so is the flag without `--pack` — **§0.1**. `repack` takes it with the same meaning, and always packs — **§0.4** |
 | `--atlas-in` | `build` and `explain`: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; `build` re-emits the atlas into `--out`, re-anchored, and `explain` writes nothing and poses through it — **§0.2**. On `explain` it is the flag that makes a **size-only** spec readable at all (`ingest --art none`), because posing resolves every attachment against an atlas; without it that pair is refused by name rather than thrown through (§5.1) |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order. For `chainfit` it is only where each attachment's image name **resolves**: the candidate decides what the parts are, so extra PNGs are unused and a missing name is refused by name (§12.3) |
@@ -263,6 +284,8 @@ What the flags mean:
 | `--seam` | `render` only: `<slot>:<slot>[,<slot>:<slot>…]` — also read, for each pair, where the two drawings **stop meeting**, and write a `seam.json` into each frame directory: per pair, the frames with a **gap** (background inside the joint, where the two covered together at the setup pose) and the frames with a **ghost** (the overlap band of one showing where, from its partner's point of view, nothing was drawn), each with its cell count, area and world box, and as runs of frames with their times. One printed line per pair; a pair whose drawings share no cell at the setup pose is a **SKIP**. A reading, not a gate: the exit status never moves. Every other file is byte for byte what the render writes without it. An unknown slot, a slot with itself, a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name, and so is `--slot`/`--hide` beside it — **§8.8** |
 | `--overlaps` | `render` only: also read **which slot each frame drew over which**, and write an `overlaps.json` into each frame directory: per frame, every pair of slots where the slot drawn later covers pixels the earlier one drew (drawn at 128 of 255 or more, on the frames' own pixels), with the pixel count and the pixel box. One `OVERLAP` line per pair that covers anything — its frames as runs, how many of the set, and the most pixels and the frame of them — and one line counting the pairs that are layering the motion does not move. Each frame with a moving pair also gets an **outline plate**, `overlaps-f<NNNN>.png`: every slot in a moving pair as its contour in its own colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Every other file is byte for byte what the render writes without it, and `frames.json` gains each set's `overlaps` record. Refused beside `--slot`/`--hide` — **§8.9** |
 | `--angle-range` | `render` only: `<bone>:<relative-to>[,<bone>:<relative-to>…]` — also read, for each pair, the range of the first bone's world direction against the second's over each set's frames, and print one line per pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. A reading, not a gate: nothing is written, and every file is the bytes the render writes without it. An unknown bone (with the bones there are), a bone against itself, a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame — **§8.7** |
+| `--sheet` | `render` only: also pack each rendered animation set as a straight-alpha transparent sprite sheet (`sheet.png` + `sheet.json`, plus `sheet2.png` / `sheet2.json` on multi-page spill, and `sheet-manifest.json` (`rigc-sheet/1`)) inside its set directory, and record `sheet` on each set in `frames.json`. Diagnostic `f####.png` and `contact.png` stay byte for byte what the render writes without it — **§8.10** |
+| `--sheet-format` | `render --sheet` only: `json-hash` (default, TexturePacker JSON Hash with `frames`, `animations` and `meta`, verified against `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`). Refused without `--sheet` or on an unknown value, exit 2, nothing written — **§8.10** |
 | `--viewport`, `--viewport-from` | `render`: give the box every frame is drawn over instead of fitting one — `--viewport <x,y,w,h>`, a world box, y up, `x,y` its bottom-left corner, at the pixel size `--max` gives; or `--viewport-from <frames.json \| dir>`, an earlier render's grid exactly (its box, scale and pixel size), so two candidates land on one pixel grid. A slot that reaches past the box is named by set and frame, and `frames.json` records the box was given under `pinned`. The two together are refused, and so is `--max` beside `--viewport-from` — **§8.6**. On `check` and `inspect`, `--viewport` pins the box those commands draw over instead |
 | `--environment` | `render` only: the wind and gravity the rig's physics constraints answer, in time — a schedule file `{ "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`, x right and **y down**, each step holding from its `t` until the next. Both posers set each change before the step that poses the first frame at or after its `t`, and draw the same frames, `geometry.json` and `frames.json` (`RE01`). `frames.json` and `geometry.json` record it, and the framing reads it. A malformed file, a half no physics constraint answers, two steps on one frame and a step after every set's last frame are refused by name, exit 2, nothing written; `check` refuses a frame set drawn under one as a reference. Without it every file is the bytes it always was. An inspection of the response the rig states, not a scene — **§8.4** |
 | `--poser` | `render`, `inspect`, `check` and `explain`: `core` or `spine` — on `render`, `inspect` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
@@ -1617,6 +1640,68 @@ written`, followed by `rigc repack: nothing was written to <out>; the work direc
 
 ---
 
+### 0.5 Reading a build from code
+
+The named `rig-c/render-shared` entry promises the official renderer reads for
+checked consumers (issue #1561). It is planned for the next minor, 2.69.0; wait
+for the measured release before using `>=2.69.0 <3.0.0`. It requires Bun and the
+candidate's real files, but imports no optional Spine runtime. The existing
+`rig-c/render` entry still eagerly imports that runtime.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  loadCandidate, throughPoser, sampleSetupPose, sampleAnimation,
+  pageFor, projector, rasterisePiece, renderFrame,
+  type Viewport,
+} from 'rig-c/render-shared';
+
+const dir = 'build';
+const skeleton = join(dir, 'skeleton.json');
+const atlas = join(dir, 'skeleton.atlas');
+const candidate = loadCandidate({
+  skeletonText: readFileSync(skeleton, 'utf8'),
+  atlasText: readFileSync(atlas, 'utf8'),
+  atlasDir: dir, label: skeleton,
+}, { skeleton, atlas }, undefined);
+const read = throughPoser(candidate.choice, (poser, roster) => ({
+  setup: sampleSetupPose(poser, { bones: true, geometry: true })[0],
+  frames: sampleAnimation(poser, 'wave', 12),
+  skins: roster.skins,
+}));
+// The consumer supplies the world box and pixel grid it intends to measure.
+const viewport: Viewport = {
+  minX: 0, minY: 0, maxX: 256, maxY: 256,
+  scale: 1, width: 256, height: 256,
+};
+const project = projector(viewport);
+for (const piece of read.value.setup.pieces) {
+  rasterisePiece(pageFor(candidate.pages, piece), piece, project, viewport,
+    (x, y, r, g, b, a) => { /* read each covered sample */ });
+}
+const image = renderFrame(read.value.setup, candidate.pages, viewport, [0, 0, 0, 0]);
+```
+
+The animation name and viewport above belong to the consumer; the loader does
+not invent them. The chooser checks the model document beside the skeleton,
+its `spine.sha256`, atlas placement, page files and bone/slot/animation rosters.
+A /3 document can be loaded with `atlasText: null` when its atlas is absent.
+`throughPoser` returns `poser` and `note` with its value. Keep its callback free
+of writes: an explicitly registered runtime fallback can rerun it.
+
+The entry also exports the original `CandidateAtlasError` (missing required
+atlas), `CandidatePairError` (unloadable pair or missing page),
+`SpineRuntimeError` (input needs an unregistered or unusable Spine side),
+`PoserChoiceError` (a forced-core pose refusal), `SlotSubsetError` (invalid
+slot subset) and `CoreInputError` (core input/pose refusal). The chooser's
+mismatch reason remains in the refusal: no silent substitute is selected by
+this entry. Unknown animation and missing `pageFor` page are `Error`s naming
+the requested name and available names. A forced-core flag keeps the existing
+deferred choice check; it alone does not prove `candidate.choice.core` exists.
+To use a Spine export or `forced: 'spine'`, install the runtime and explicitly
+import `rig-c/render` first; importing `render-shared` never registers it.
+
 ## 1. The two files
 
 ### 1.1 A complete minimal rig spec
@@ -9147,6 +9232,118 @@ is a defect is yours; when it is, the remedy is a `drawOrder` key in the motion
 spec (or the slot's place in the rig's `slots`), and the next render says whether
 the line moved.
 
+### 8.10 Sprite sheets from a render — `render --sheet`
+
+```bash
+bun cli.ts render --candidate path/to/build --sheet [--sheet-format json-hash] [--page-edges pot|free] [--animation idle] [--fps 12] [--max 256]
+```
+
+Packs each rendered animation set into a deterministic, transparent sprite sheet
+beside the diagnostic frames, with a TexturePacker JSON Hash descriptor per page
+and a rigc manifest stating the source identities, provenance, and coordinate
+contract.
+
+**What it writes per set (`<out>/<set>/`):**
+
+- `sheet.png` and `sheet.json` (plus `sheet2.png`, `sheet2.json`, … when a set
+  spills across `2048 × 2048` pages) — RGBA PNG pages rendered over transparent
+  `[0, 0, 0, 0]` (`alphaMode: "straight"`), packed through `packAtlas` with a
+  fixed `2048` page ceiling and `2`-px clamped edge extrusion around every cell.
+  `--page-edges pot` (the default) rounds each page edge up to a power of two;
+  `--page-edges free` sizes each page tightly to the packed cells plus their
+  `2`-px border.
+- `sheet-manifest.json` (`spec: "rigc-sheet/1"`) — the set's machine-readable
+  provenance and coordinate contract: `format` (`"json-hash"`), `namespace`,
+  `source` (`{ skeleton: { file, sha256 }, model: { file, sha256 } | null }`,
+  recording the relative filenames and SHA-256 digests of the `skeleton.json`
+  and `skeleton.model.json` the sheet was rendered from, with no paths),
+  `animation` (`null` on a setup-pose set), optional `skin` / `slots` / `hidden` /
+  `environment` / `pinned`, `fps`, `duration`, `sampled`, `endpointPolicy`
+  (`"inclusive-grid"`), `alphaMode` (`"straight"`), `filterPolicy`
+  (`{ recommended: "linear", paddingPx: 2, extrusion: "clamp-edge" }`),
+  `pageEdges`, `pageSize` (`2048`), `padding` (`2`), `sourceSize` (`{ w, h }`),
+  `viewport`, `pivot` (`{ world: [0, 0], canvasPx: { x, y }, anchor: { x, y } }`),
+  `pages[]` (`{ index, image, table, width, height, occupancy, frames }`),
+  and `frames[]` in chronological `0 .. N - 1` order (`{ index, key, time, page, image, table, empty, frame, spriteSourceSize, sourceSize, anchor }`).
+- `frames.json` gains `sheet` on each set entry (`manifest`, `format`,
+  `pageEdges`, `pages`, `frames`, `emptyFrames`).
+
+**What does not move.** The diagnostic `f####.png` frames and `contact.png` stay
+drawn over `BACKGROUND` (`[232, 232, 232, 255]`) and are byte for byte what `render`
+writes without `--sheet`; stripping `sheet` from each set in `frames.json`
+leaves the plain render's `frames.json` to the byte (`SH02`). Two runs and both
+posers (`--poser core` and `--poser spine`) write the same `sheet*.png`,
+`sheet*.json`, and `sheet-manifest.json` byte for byte (`SH03`), with no
+timestamps, host strings, or absolute paths.
+
+**Trimming, empty frames, and `alpha > 0`.** Every frame is rendered at the
+set's full canvas (`sourceSize: { w: viewport.width, h: viewport.height }`) over
+straight-alpha `[0, 0, 0, 0]` and trimmed to the minimal bounding box of pixels
+with `alpha > 0` (`alpha >= 1`), preserving `alpha === 1` feather edges (`SH13`)
+and un-premultiplied RGB channels (`SH14`). When every pixel on a frame has
+`alpha === 0` (for instance, when `--hide` or `--slot` hides every visible slot
+on that step), the frame is emitted as a `1 × 1` transparent `[0, 0, 0, 0]`
+sentinel cell (`empty: true`, `trimmed: true`,
+`spriteSourceSize: { x: 0, y: 0, w: 1, h: 1 }`, `sourceSize` preserved) so the
+animation's frame count and timing stay intact and reconstructing the frame
+yields an all-zero full canvas (`SH12`).
+
+**Shared world `(0, 0)` anchor and multi-page layout.**
+
+- Each entry in `frames` carries `"anchor": { "x": ax, "y": ay }`, where
+  `canvasPx = projector(viewport)(0, 0)` projects Spine world `(0, 0)` into
+  untrimmed canvas pixel coordinates and `ax = canvasPx.x / viewport.width`,
+  `ay = canvasPx.y / viewport.height`. When a pinned `--viewport` excludes world
+  `(0, 0)`, `ax` and `ay` are preserved un-clamped outside `[0, 1]` so placing a
+  sprite at `(worldOriginX, worldOriginY)` still lands every pixel at its exact
+  world coordinate (`SH15`).
+- Each `sheet*.json` carries `frames`, `animations`, and `meta` (`app: "rig-c"`,
+  `format: "RGBA8888"`, `image`, `size: { w, h }` as a single object and never an
+  array, and `scale: "1"`). When a set spills across multiple pages, `packAtlas`
+  assigns trimmed cells to pages by descending area rather than by frame time:
+  each page's `frames` and `animations[<namespace>]` list only the frames that
+  landed on that page (ordered chronologically within that page), `meta.related_multi_packs`
+  names the sibling descriptor files (`SH16`), and the full set's playback order
+  across all pages comes from `sheet-manifest.json`'s `frames[]` (`0 .. N - 1`).
+
+**Collision-free frame keys and sampling policy.** Frame keys are
+`<rig>/<set>[/<variants>]/f<NNNN>` (for example, `squash/bounce/f0000` at the
+default `12` fps or `squash/bounce@24fps/skin=alt/f0000` at `24` fps under
+`--skin alt`), where `<rig>` is derived from `rig.archetype` in
+`skeleton.model.json` (the rig spec's `name`, never the build output folder) and
+`<set>` is `frameSetDir(animation, fps)`, so rendering one animation at different
+rates or copying a build into differently named folders never collides or moves
+a byte (`SH04`, `SH17`, `SH19`, `SH20`). Sampling follows `render`'s closed grid
+(`[0, duration]` at `Math.round(duration * fps) + 1` frames, recorded as
+`endpointPolicy: "inclusive-grid"`): whether a looping playback drops the
+closing endpoint frame or plays the full grid is a scene playback decision left
+to the consumer.
+
+**Self-check, external reader verification, and refusals.** Before any file is
+written, `verifySheetPack`
+reconstructs every frame from the packed `sheet*.png` pages and `sheet*.json`
+descriptors onto a blank `sourceSize.w × sourceSize.h` canvas and checks that
+every reconstructed canvas is byte-identical (`0` differing RGBA bytes) to the
+untrimmed transparent render (`SH05`), that every cell's `2`-px border is
+clamped edge extrusion (`SH06`), that no two padded cells overlap (`SH07`–`SH11`),
+and that `source` records relative filenames and valid 64-hex SHA-256 digests (`SH21`).
+On a source checkout, `bun tools/sheet_readers.ts --sheet <dir>` loads a packed
+set (single-page or multi-page via `meta.related_multi_packs`) in headless
+Playwright Chromium through the pinned `pixi.js@8.22.0` (`PIXI.Assets.load` /
+`PIXI.Spritesheet`) and `phaser@3.90.0` (`Phaser.Textures.Parsers.JSONHash` /
+`addAtlasJSONHash`) loaders and checks cut rectangles, `sourceSize` and
+`spriteSourceSize`, `defaultAnchor` / `customPivot` alignment at
+`pivot.canvasPx` (`0` px drift; in Phaser 3.86+, set `roundPixels: false` on the
+game or camera when `pivot.canvasPx` is sub-pixel so `CanvasRenderer` does not
+round the sprite translation before adding `-displayOrigin + frame.{x,y}`),
+chronological playback order, multipage membership, and straight-alpha rendering
+over light (`[232, 232, 232, 255]`) and dark (`[28, 28, 32, 255]`) backgrounds;
+`SH22`–`SH25` hold its host-side refusals.
+`--sheet-format` with an unknown value or without `--sheet`, `--page-edges` on
+`render` without `--sheet` or with an unknown value, and any frame whose trimmed
+bounds plus its `2`-px border on each side exceed `2048` (`w + 4 > 2048` or
+`h + 4 > 2048`) are refused by name, exit 2, with nothing written (`SH17`).
+
 ---
 
 ## 9. Checking against the frames — `rigc check`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.68.0",
+  "version": "2.70.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "./font5x7": "./tools/font5x7.ts",
     "./transform": "./src/transform.ts",
     "./render": "./src/render.ts",
+    "./render-shared": "./src/render_read.ts",
     "./png": "./src/png.ts",
     "./compile": "./src/compile.ts",
     "./rig": "./src/rig.ts",
@@ -31,7 +32,7 @@
     "./*": "./*.ts"
   },
   "engines": {
-    "bun": ">=1.2.0"
+    "bun": ">=1.4.0"
   },
   "license": "MIT",
   "author": "firejune",
@@ -105,6 +106,8 @@
     "@esotericsoftware/spine-core": "4.3.13",
     "@types/bun": "^1.4.0",
     "eslint": "^10.9.0",
+    "phaser": "3.90.0",
+    "pixi.js": "8.22.0",
     "spine-html": "^0.4.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.67.0",

package/skills/rigc/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc
 description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output with named assertions before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
+compatibility: Requires Bun 1.4 or later. The tool is the npm package rig-c (bunx rig-c, or bun add -d rig-c); the command it installs is rigc.
 ---
 
 # rigc — a rig compiler for agents

package/skills/rigc-face/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Face — a turn, a gaze and a blink

package/skills/rigc-ingest/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Ingest — a skeleton you did not author

package/skills/rigc-motion/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Motion — what goes between two poses

package/skills/rigc-rigging/SKILL.md

@@ -2,7 +2,7 @@
 name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
-compatibility: Requires Bun 1.2 or later and the npm package rig-c.
+compatibility: Requires Bun 1.4 or later and the npm package rig-c.
 ---
 
 # Rigging — the hierarchy itself

package/src/atlas.ts

@@ -775,6 +775,11 @@ export interface PackInput {
   absPath: string;
   width: number;
   height: number;
+  /**
+   * Already-drawn pixels (`render --sheet`), used in place of `readPlate(absPath)`
+   * when given so an in-memory crop is not written out only to be read back in.
+   */
+  plate?: Plate;
   /**
    * What the region's attachments draw (`packFootprints`), read only under
    * `shape: 'polygon'`. Absent means the rectangle.
@@ -2535,7 +2540,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
     const owners: Array<{ source: Plate; place: Placement; shape: CellShape }> = [];
     for (const place of onPage) {
       const input = byRegion.get(place.region)!;
-      const source = readPlate(input.absPath);
+      const source = input.plate ?? readPlate(input.absPath);
       if (source.width !== input.width || source.height !== input.height) {
         // The size in the atlas came from the PNG's IHDR (`readPngInfo`); this is
         // the decoded image. They disagreeing means the file changed between the

package/src/cli/core_commands.ts

@@ -40,6 +40,7 @@ import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOf
 import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
 import type { Plate } from '../../tools/plate.ts';
 import { OVERLAPS_FILE, OverlapError, overlapLine, overlapPlate, overlapsFileOf, overlapsOf, overlapsPlateFile, overlapsText, plateParticipants, staticLine } from '../overlaps.ts';
+import { buildSheetSet, SHEET_MANIFEST_FILE, type SheetSetPack, SheetUsageError, sheetRigNameOf, sheetSidecarRecord, sheetSourceOf } from '../sheet.ts';
 import { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
@@ -49,7 +50,7 @@ import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
 import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPageEdges, readPoserFlag, readSheetFormat, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -656,6 +657,18 @@ export function cmdRender(flags: Record<string, string>): void {
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
   const given = readGivenViewport(flags);
+  const wantsSheet = flags.sheet !== undefined;
+  if (flags['sheet-format'] !== undefined && !wantsSheet) {
+    throw new UsageError('--sheet-format takes --sheet: pass --sheet alongside --sheet-format <format>, or drop --sheet-format');
+  }
+  if (flags['page-edges'] !== undefined && !wantsSheet) {
+    throw new UsageError(
+      '--page-edges on render takes --sheet: without --sheet, render writes loose f####.png frames and contact.png, ' +
+        'which have no packed atlas pages. Pass --sheet or drop --page-edges',
+    );
+  }
+  const sheetFormat = wantsSheet ? readSheetFormat(flags) : undefined;
+  const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -953,9 +966,45 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings };
+    const sheetPacks = new Map<string, SheetSetPack>();
+    if (wantsSheet) {
+      const modelDocText = modelTextBeside(skeletonPath, skeletonText) ?? null;
+      const rigName = sheetRigNameOf(skeletonPath, modelDocText, skeletonText);
+      const source = sheetSourceOf(skeletonPath, skeletonText, modelDocText);
+      const pinned = given === undefined ? undefined : pinnedRecord(given.by, outsideViewport(sampled, viewport));
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const setName = frameSetDir(name, fps);
+        try {
+          sheetPacks.set(
+            name,
+            buildSheetSet({
+              rigName,
+              setName,
+              animation,
+              fps,
+              maxSide,
+              viewport,
+              frames,
+              atlasPages: pages,
+              source,
+              format: sheetFormat,
+              pageEdges: sheetPageEdges,
+              skin,
+              subset,
+              environment: environment?.steps,
+              pinned,
+            }),
+          );
+        } catch (err) {
+          if (err instanceof SheetUsageError) throw new UsageError(err.message);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings, overlapReadings, sheetPacks } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -1014,6 +1063,14 @@ export function cmdRender(flags: Record<string, string>): void {
       writeFileSync(join(dir, OVERLAPS_FILE), overlapsText(overlapReading.file));
       for (const [index, plate] of overlapReading.plates) plate.writePng(join(dir, overlapsPlateFile(index)));
     }
+    const sheetPack = sheetPacks.get(name);
+    if (sheetPack !== undefined) {
+      for (const page of sheetPack.pages) {
+        page.plate.writePng(join(dir, page.image));
+        writeFileSync(join(dir, page.table), page.jsonText);
+      }
+      writeFileSync(join(dir, SHEET_MANIFEST_FILE), sheetPack.manifestText);
+    }
     const duration = frames[frames.length - 1].time;
     const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
@@ -1026,6 +1083,7 @@ export function cmdRender(flags: Record<string, string>): void {
       duration,
       ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
       ...(overlapReading === undefined ? {} : { overlaps: overlapsRecord(overlapReading.file, overlapReading.plates.size) }),
+      ...(sheetPack === undefined ? {} : { sheet: sheetSidecarRecord(sheetPack) }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
@@ -1038,7 +1096,11 @@ export function cmdRender(flags: Record<string, string>): void {
       overlapReading === undefined
         ? ''
         : ` + ${OVERLAPS_FILE} (${overlapReading.file.pairs.filter((p) => p.varies).length} moving pair(s), ${overlapReading.plates.size} outline plate(s))`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
+    const sheetNote =
+      sheetPack === undefined
+        ? ''
+        : ` + ${sheetPack.pages.map((p) => `${p.image} + ${p.table}`).join(' + ')} + ${SHEET_MANIFEST_FILE} (${sheetPack.pages.length} page(s), ${sheetPack.pageEdges})`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${sheetNote}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}${overlapNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
@@ -2313,7 +2375,7 @@ function resolveDelegate(name: string): string | null {
 
 /**
  * Whether the Bun running this hands an empty argument to a process it starts
- * (issue #1465). Bun 1.2.0 — the declared minimum — does not: `["a", "", "b"]`
+ * (issue #1465). Bun 1.2.0 (then the declared minimum) does not: `["a", "", "b"]`
  * reaches the child as `["a", "b"]`, through `spawnSync` and `Bun.spawnSync`
  * alike and whatever the child is; 1.4.2 hands it over. That is measured here
  * rather than read off a version number, by starting this Bun twice with
@@ -2466,7 +2528,7 @@ function cmdDelegate(command: string, raw: readonly string[]): void {
   // `rigc review -- <dir>` reached the bin as `<dir>` (measured, issue #1486). One given here is the one dropped, and
   // the arguments after it arrive as they were.
   const ran = spawnSync(process.execPath, [bin, '--', ...argv], { stdio: 'inherit' });
-  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
+  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 (then the declared minimum) sets `error` on every
   // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a
   // launch that failed only where the child left neither a status nor a signal.
   if (typeof ran.status === 'number') process.exit(ran.status);