@rig-c/core 2.40.1 → 2.41.0

package/README.md

@@ -41,6 +41,7 @@ installed.
 | the same, and one texture instead of many | `rigc build --pack` | the parts arranged onto shared atlas pages, written beside the skeleton — losslessly, so the picture is the picture |
 | a pack somebody already made | `rigc build --atlas-in` | the same skeleton, with every part resolved to a region of that atlas — or a named refusal, never a part that silently does not draw |
 | a compiled rig | `rigc render` | every animation as PNG frames, plus one labelled contact sheet of the whole shot |
+| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot — and a legend that puts every mark back in world units |
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
 | a picture of a key pose | `rigc pose` | where each loose part PNG sits in it, in spec coordinates — the movement between two poses is then yours to key ([docs/MOTION.md](docs/MOTION.md)) |
@@ -402,8 +403,22 @@ second package, no server.
 ```bash
 rigc render  --candidate spine          # PNG frames + a contact sheet, in render/
 rigc preview --candidate spine          # one .html file that plays it: preview.html
+rigc inspect --candidate spine --show art,bones,names --dim   # inspect.png + inspect.json
 ```
 
+**`inspect`** answers a question about geometry rather than appearance — *is this
+bone where the art is*, *which way does it squash*, *where in rig units is this
+point*, *is this axis held*. It draws the build's art, framed as `render` frames it,
+and over it any of `bones` (origin to tip, a bone of length 0 marked as one),
+`names`, `axes` (each bone's world x and y), `grid` (in world units) and `declared`
+(each `invariants.axes` line and the bones held to it), at the setup pose, at
+`--animation <name> --at <s[,s…]>` — one picture, or a sheet — or zoomed with
+`--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`. Beside the PNG it writes a legend:
+the world-to-pixel transform both ways, what each colour means, and every bone's
+origin and tip in world units and in pixels, so a position read off the picture goes
+straight back into the spec. [AUTHORING §13](docs/AUTHORING.md#13-asking-the-picture-a-question--rigc-inspect)
+maps each question to its view.
+
 **`render`** samples every animation at 12 fps and writes `render/<animation>/f0000.png…`
 with a `contact.png` beside them — every frame of the shot as one labelled grid,
 which is the picture to open first, because spacing is a comparison *across*

package/docs/AUTHORING.md

@@ -126,6 +126,12 @@ bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spi
 #   ↳ a green build ends by naming this command for its own --out; repeat
 #     --candidate for a pane per candidate on one page
 
+# …and when the question is about geometry — is this bone where the art is, which
+# way does it squash — draw the bones over the art and read the legend beside it:
+bun cli.ts inspect --candidate path/to/spine --show art,bones,names --dim --out look.png
+#   ↳ look.png and look.json: every bone's origin and tip in world units and in
+#     pixels, and the transform between them — §13
+
 # …and where you have several green candidates and no instrument that separates
 # them, ask a human — the one loop step this toolchain cannot run for you:
 bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> ballot.html
@@ -235,10 +241,11 @@ What the flags mean:
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 35 validity rules (**the default**) · `spine-html` = all 51, opt-in |
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
-| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`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 |
+| `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`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 |
+| `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone or slot it frames to; §13 says each, with the refusals |
 | `--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** |
-| `--poser` | `render`, `check` and `explain`: `core` or `spine` — on `render` 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 |
+| `--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 |
 | `--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 |
@@ -10048,3 +10055,117 @@ simply unused; a name the directory lacks is refused `no-part-image` by name.
   is a given condition and once your spec states it there is nothing left to be
   close to. Every threshold in the report is a reporting threshold. There is no pass
   bar and `caveats` says so in the file.
+
+## 13. Asking the picture a question — `rigc inspect`
+
+The gate answers everything a number can say, and a geometric judgement is not
+one of those: *the bones around the head look odd* is a sentence about a picture.
+`inspect` draws that picture of a green build — the art, and over it the rig's own
+geometry at one moment — and writes a **legend** beside it that turns every mark
+back into world units. The picture is for reading; the legend is for acting on what
+was read, because a position taken off it goes straight into a spec.
+
+```bash
+bun cli.ts inspect --candidate gallery/look/build --show art,bones,names --dim --max 640 --out look.png
+# rigc inspect
+#   ..    skeleton …/gallery/look/build/skeleton.json
+#   ..    atlas    …/gallery/look/build/skeleton.atlas
+#   ..    poser    rigc core — …/skeleton.model.json
+#   ..    view     art,bones,names over dimmed art — the setup pose
+#   ..    box      world x -35.2..835.2, y -35.2..915.2 at 0.6734 px per unit — 1 tile(s) of 586x640px (exact in the legend)
+# rigc: wrote …/look.png
+# rigc: wrote …/look.json
+```
+
+It poses through the poser `render` would pose the candidate with, and the `poser`
+line says which — rigc's core for a build with its `skeleton.model.json`, spine-core
+for an export or a named fallback (the `--poser` row in §0). Without `--zoom` or
+`--viewport` the picture is framed exactly as `render` frames the build at the same
+`--max`, so with nothing drawn over it the art **is** `render`'s frame, pixel for
+pixel (`IN09`).
+
+### 13.1 Which question, which view
+
+| The question | The view | What to read |
+| --- | --- | --- |
+| Is this bone where the art is? | `--show art,bones,names --dim` | each bone as a line from its origin to its tip, the origin a filled square, the tip a hollow one; a bone of length 0 is a hollow 5x5 square around its origin, so a joint nobody gave a length is not mistaken for a point on another bone. Three fringe chains drawn as evenly spaced page verticals is the kind of thing this shows at a glance |
+| Which way does this bone squash? | `--show art,axes --zoom <bone>` | the bone's world **x** axis (red) and **y** axis (green), each 24 px long at a world scale of 1 — longer or shorter as the bone scales. A `scaley` key squashes along the green one; if that is the page's vertical on a face painted at an angle, the blink squashes along the page |
+| Where in rig units is this point? | `--show art,grid --zoom <bone or slot>` or `--viewport x,y,w,h` | grid lines at whole multiples of a step in **world units**, each labelled with its value, the lines through 0 darker. The legend's transform converts any pixel exactly; the grid is for reading by eye |
+| Is this axis declared, and held? | `--show art,declared,bones` | each `invariants.axes` line (§3.7) through its two bones' origins, drawn across the whole tile, and the bones it holds drawn in their own colour; the legend states each held bone's world x axis and how far off the line it lies, as `A51` measures it, at the pose drawn |
+| Did it break during the move? | any of the above `--animation <name> --at <s,s,…>` | one tile per time, left to right on one grid, each labelled with its time and frame |
+
+Two questions are not this cut's: **what does this bone move** (its weights over
+the meshes it skins, the mesh edges and hulls, the slots' draw order) and **did this
+change move anything** (two builds side by side on one grid). `--show mesh`,
+`hull`, `weights:<bone>`, `slots` and `--compare` are refused as any unknown word
+or flag is, naming what this version draws.
+
+### 13.2 Where it looks
+
+- **The setup pose** by default.
+- **One time, or several** — `--animation <name> --at <s[,s…]>`. A time is a frame
+  of the grid `render --fps <n>` draws the animation on (default 12): the pose at
+  `--at 0.5` is `render`'s `f0006.png`, the same continuous trajectory stepped the
+  same way, physics included. A time off that grid is refused naming the frames
+  either side (`--at 0.3 is not on the 12 fps frame grid … the frames either side
+  are 3 (0.2500s) and 4 (0.3333s)`); pass `--fps` for another grid. A time past the
+  end is refused naming the animation's length. Several times are a sheet: tiles
+  left to right, eight to a row, a one-pixel rule between them, all on one world box
+  so a mark that moves between two tiles moved in the rig.
+- **The whole rig**, framed as `render` frames it; **a box** — `--viewport x,y,w,h`
+  in world units, y up, `x,y` its bottom-left corner; or **one bone or slot** —
+  `--zoom <name>[:<pad>]`, the bone's origin and tip or the slot's attachment
+  vertices over every time drawn, padded by `<pad>` world units on every side
+  (default a quarter of the box's longer side). A name that is both a bone and a slot
+  is refused until it is written `bone:<name>` or `slot:<name>`; a bone of length 0
+  with no pad is one point, and is refused asking for one.
+- `--max` is each tile's longer side in pixels (default 256), as on `render`.
+- `--dim` fades the art toward white (each channel keeps 0.4 of its distance from
+  white) so what is drawn over it reads.
+
+### 13.3 The legend
+
+`<out>.json` beside `<out>.png`, `rigc-inspect/1`. What it states:
+
+- `coordinates` — the two spaces and the transform, in both directions, as text:
+  `px = x0 + (x - minX) * scale; py = y0 + (maxY - y) * scale` and
+  `x = minX + (px - x0) / scale; y = maxY - (py - y0) / scale`. World is Spine's, y up;
+  the picture is y down from its top-left corner, and pixel (i, j) covers
+  `[i, i+1) x [j, j+1)` — a position's pixel is its floor.
+- `viewport` — the world box every tile is a picture of and its size in pixels;
+  `size` — the whole picture's.
+- `tiles[]` — per tile: `animation`, `frame` and `time` (`frame / fps`), its `box` in
+  the picture, its own `transform` (`minX`, `maxY`, `scale`, and `x0`, `y0`, its
+  top-left pixel), and `bones[]` — every bone in declaration order with its
+  `parent`, `length`, `zeroLength`, `origin` and `tip` each as `{ world, pixel }`,
+  `undrawn` (why it is not drawn — its world matrix is 0 at this time, unposed by the
+  skin or scaled to 0 — or `null`), and with `axes` shown, the two axis ends. With
+  `grid`, the step and every line's value; with `declared`, each entry's line in
+  degrees, its two points, and each held bone's angle and how far off the line it is.
+- `colours` — every colour the picture draws, as RGBA, with what it means.
+- `poser`, `show`, `dim`, `skin`, `animation`, `fps` and `framing` — what was drawn
+  and how it was framed (`shot`, `zoom` with the bone or slot, the pad and whether it
+  was stated, or `viewport`).
+
+Every number is `JSON.stringify`'s, the double the pose produced, not a rounding of
+it. The same build and flags write the same bytes (`IN10`).
+
+### 13.4 What it refuses
+
+Each of these exits 2, writes nothing, and names what exists: a bone or slot the
+build does not have (both rosters listed), an animation or skin it does not declare,
+a `--show` word it does not draw, a flag it does not take, a time off the frame grid
+or past the end, `--at` without `--animation` and the reverse, `--zoom` beside
+`--viewport`, and `--show declared` on a skeleton with no `skeleton.model.json`
+beside it whose `spine.sha256` is its own — a Spine export states no rig invariants.
+A rig that declares no `invariants.axes` is not refused: the picture draws nothing
+for `declared` and the run says so on a line of its own.
+
+### 13.5 What it is not
+
+- **Not a score.** Nothing in it is a pass bar; the picture is read, and what is read
+  is acted on in the spec.
+- **Not a player.** It is one still, or a sheet of stills. A person watches
+  `@rig-c/play` or `rigc preview`.
+- **Not a second poser.** Everything it draws is a pose `render` would have drawn at
+  the same frame; where it disagrees with `render --geometry`, it is wrong (`IN04`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.40.1",
+  "version": "2.41.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": {

package/skills/rigc/SKILL.md

@@ -74,6 +74,11 @@ row for each.
    cover a feature the art shows — and answer each with `render --hide <slot>` (or
    `--slot <slot,…>`), which draws the frame again without that part on the same
    grid, so the two frames say which part a pixel is. AUTHORING §0 holds the three.
+   When the question is geometry — is this bone where the art is, which way does it
+   squash, where in rig units is this point — `rigc inspect --candidate <out> --show
+   art,bones,names --dim` draws the bones over the art and writes a legend beside the
+   picture that puts every mark back in world units; AUTHORING §13 maps each
+   question to its view.
 5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures
    (`--out <dir>` writes the picture each of its numbers came from — open the worst).
    Read its output from the top: the framing block says whether the figures under

package/src/cli/core_commands.ts

@@ -1,6 +1,6 @@
 /**
  * The bodies of the commands that reach nothing of spine-core — `explain`,
- * `ingest`, `diff`, `check`, `render`, `pose`, `chainfit` and `skills` —
+ * `ingest`, `diff`, `check`, `render`, `inspect`, `pose`, `chainfit` and `skills` —
  * moved here unchanged from `cli.ts` (issue #1052, step 4e of #380), with the
  * helpers only they call. Both entries register them (`CORE_COMMAND_RUNS`):
  * `cli.ts` beside the runtime's, `cli_core.ts` alone. And the body
@@ -30,12 +30,13 @@ import { ingest, INGEST_GUTTERS, type IngestFinding, IngestSpecRefused, type Ing
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
+import { type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readShowWords, readTimes, readZoom } from '../inspect.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, 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, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, 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 { 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';
 
@@ -648,6 +649,87 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
+export const DEFAULT_INSPECT_OUT = 'inspect.png';
+
+/**
+ * inspect — one moment of a build drawn for an agent to read, and the legend
+ * that turns its pixels back into world units (issue #1357). The view is
+ * `src/inspect.ts`'s; this reads the flags, loads the candidate the way
+ * `render` loads it and writes the two files.
+ *
+ * ⚠️ A flag this command does not take is refused by name here rather than
+ * ignored: the parser accepts any `--word value`, and a view asked for with a
+ * flag that does nothing would be a picture of something other than what the
+ * caller asked about.
+ */
+export function cmdInspect(flags: Record<string, string>): void {
+  const doc = COMMANDS.find((c) => c.name === 'inspect');
+  const accepted = [...(doc?.flags ?? []), 'help'];
+  const stray = Object.keys(flags).filter((name) => !accepted.includes(name));
+  if (stray.length > 0) {
+    throw new InspectError(`inspect takes no --${stray.join(', --')}; it takes --${accepted.filter((f) => f !== 'help').join(', --')}`);
+  }
+  if (flags.candidate === undefined) {
+    throw new UsageError('inspect needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
+  }
+  if (flags.zoom !== undefined && flags.viewport !== undefined) {
+    throw new InspectError('--zoom and --viewport both choose the box the picture is of; give one of them');
+  }
+  const show = readShowWords(flags.show);
+  const times = readTimes(flags.at);
+  const fps = readPositiveNumber(flags, 'fps', INSPECT_DEFAULT_FPS, 1);
+  const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  let frame: InspectFrame = { kind: 'shot' };
+  if (flags.zoom !== undefined) frame = { kind: 'zoom', ...readZoom(flags.zoom) };
+  if (flags.viewport !== undefined) {
+    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    }
+    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
+    frame = { kind: 'viewport', x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+  }
+  const target = resolve(flags.out ?? DEFAULT_INSPECT_OUT);
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_INSPECT_OUT) : target;
+  if (!out.endsWith('.png')) throw new InspectError(`--out ${flags.out}: the picture is a PNG, so --out names a .png file (its legend is written beside it as .json)`);
+  const legendPath = `${out.slice(0, -'.png'.length)}.json`;
+
+  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
+  const skeletonText = readSkeletonText(skeletonPath);
+  console.log('rigc inspect');
+  console.log(`  ..    skeleton ${skeletonPath}`);
+  console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
+  // `render`'s loading, in `render`'s order (issue #1014): the poser is chosen before anything is read off the candidate.
+  const candidate = loadCandidate(
+    { skeletonText, atlasText, atlasDir: dirname(atlasPath), label: skeletonPath },
+    { skeleton: skeletonPath, atlas: atlasPath },
+    posersAsked(flags),
+  );
+  const animation = readAnimationFlag(flags, [...candidate.facts.animations]) ?? null;
+  readPoserFlag(flags);
+  refuseUnchosen(candidate.choice);
+  const result = inspectCandidate(
+    candidate,
+    { skeletonText, modelText: modelTextBeside(skeletonPath, skeletonText) },
+    { show, dim: flags.dim !== undefined, animation, times, fps, skin: flags.skin, frame, maxSide },
+  );
+  const { legend } = result;
+  console.log(`  ..    poser    ${result.poserNote}`);
+  const when = animation === null ? 'the setup pose' : `${animation} at ${legend.tiles.map((t) => `${t.time.toFixed(4)}s (frame ${t.frame})`).join(', ')}, ${fps} fps grid`;
+  console.log(`  ..    view     ${legend.show.join(',')}${legend.dim ? ' over dimmed art' : ''} — ${when}`);
+  const v = legend.viewport;
+  // Four places for reading; the legend carries every number exactly.
+  const f = (n: number): string => String(Number(n.toFixed(4)));
+  console.log(`  ..    box      world x ${f(v.minX)}..${f(v.maxX)}, y ${f(v.minY)}..${f(v.maxY)} at ${f(v.scale)} px per unit — ${legend.tiles.length} tile(s) of ${v.width}x${v.height}px (exact in the legend)`);
+  for (const note of result.notes) console.log(`  ..    ${note}`);
+  mkdirSync(dirname(out), { recursive: true });
+  result.plate.writePng(out);
+  writeFileSync(legendPath, legendText(legend));
+  console.log(`rigc: wrote ${out}`);
+  console.log(`rigc: wrote ${legendPath}`);
+}
+
 /** `--scale 0.5,2` / `--rotation -30,30` — a pair of numbers, low first. */
 function readRange(flags: Record<string, string>, key: string): { low: number; high: number } | undefined {
   const raw = flags[key];
@@ -1621,6 +1703,7 @@ export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   diff: ({ flags, lists, positional }) => cmdDiff(flags, lists, positional),
   check: ({ flags }) => cmdCheck(flags),
   render: ({ flags }) => cmdRender(flags),
+  inspect: ({ flags }) => cmdInspect(flags),
   pose: ({ flags }) => cmdPose(flags),
   chainfit: ({ flags }) => cmdChainFit(flags),
   skills: ({ flags, positional }) => cmdSkills(flags, positional),

package/src/cli/shared.ts

@@ -56,6 +56,7 @@ import { BallotError } from '../ballot.ts';
 import { ChainFitError } from '../chainfit.ts';
 import { CheckError } from '../check.ts';
 import { IngestError, type IngestStage } from '../ingest.ts';
+import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAMES, SHOW_WORDS } from '../inspect.ts';
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
@@ -125,7 +126,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * 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', 'geometry', 'accept-skeleton-differences', 'keep-pages']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -996,7 +997,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     "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',
   poser:
-    "`render` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
+    "`render`, `inspect` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
     "beside the skeleton and the skeleton is the one the document records (spine.sha256), `spine` otherwise and wherever the core refuses the input by name; the `poser` " +
     'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
@@ -1061,6 +1062,22 @@ const FLAG_MEANINGS: Record<string, string> = {
     'draw every slot but these, comma-separated — `--slot` the other way round, on the same grid, recorded and ' +
     'refused the same way. Not with `--slot`: the two are one statement',
   max: 'longest side of a rendered frame, in pixels (default 256)',
+  show:
+    `what \`inspect\` draws, comma-separated, from [${SHOW_WORDS.join(', ')}] (default \`${DEFAULT_SHOW.join(',')}\`): art = the ` +
+    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; declared = each invariants.axes " +
+    "line through its two bones' origins, its held bones drawn in their own colour; bones = each bone from origin to tip, " +
+    'a bone of length 0 marked as one; axes = each bone\'s world x and y axes; names = each bone\'s name. Any other word ' +
+    'is refused naming these',
+  dim: `fade the art toward white (each channel keeps ${DIM_KEEP} of its distance from white), so what is drawn over it reads`,
+  at:
+    `the times of --animation to draw, in seconds, comma-separated — one is a picture, several a sheet of tiles on one ` +
+    `grid in the order given. Each must be a frame of the --fps grid render draws the animation on (within ` +
+    `${ON_GRID_FRAMES} of a frame), and is refused naming the frames either side otherwise; without --animation the ` +
+    'picture is the setup pose and --at is refused',
+  zoom:
+    'frame the picture to one bone (origin to tip) or one slot (its attachment\'s vertices) over every time drawn, padded ' +
+    'by <pad> world units on every side (default: a quarter of the box\'s longer side). A name that is both a bone and a ' +
+    'slot is refused until written bone:<name> or slot:<name>; a name that is neither lists both rosters. Not with --viewport',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
   ledger: `the append-only JSONL the vote lands in (default \`${DEFAULT_LEDGER}\`)`,
@@ -1158,6 +1175,9 @@ const FLAG_VALUES: Record<string, string> = {
   slot: '<name[,name…]>',
   hide: '<name[,name…]>',
   max: '<px>',
+  show: '<view[,view…]>',
+  at: '<s[,s…]>',
+  zoom: '<name>[:<pad>]',
   record: '<result.json>',
   ballot: '<ballot.html>',
   ledger: '<votes.jsonl>',
@@ -1536,6 +1556,36 @@ export const COMMANDS: CommandDoc[] = [
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
     },
   },
+  {
+    name: 'inspect',
+    runtime: false,
+    spineFormat: false,
+    usage: [
+      'rigc inspect --candidate <dir | skeleton.json> [--show art,bones,…] [--dim] [--max 256] [--poser core|spine] [--out inspect.png]   (the setup pose)',
+      'rigc inspect … --animation <name> --at <s[,s…]> [--fps 12] [--skin <name>]   (one time, or a sheet of several on one grid)',
+      'rigc inspect … --zoom <bone|slot>[:<pad>] | --viewport <x,y,w,h>   (a box, in world units)',
+    ],
+    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'max', 'poser', 'out'],
+    overrides: {
+      animation: { meaning: 'the animation --at reads its times from (default: the setup pose, with no --at)' },
+      fps: { meaning: `the frame grid --at is read on, which is the grid \`render --fps\` draws (default ${INSPECT_DEFAULT_FPS})` },
+      viewport: { meaning: 'frame the picture to this world box, y up — x,y its bottom-left corner — instead of render\'s framing of the whole rig' },
+      out: {
+        value: '<file.png>',
+        meaning:
+          'the picture to write (default `inspect.png`; a directory means that name in it), and beside it the legend, the same ' +
+          'path with .json for .png: the world-to-pixel transform both ways, what each colour means, and every bone\'s origin ' +
+          'and tip in world units and in pixels',
+      },
+    },
+    notes: [
+      'inspect draws one moment of the build for an agent to read, and its legend says',
+      'where every mark is in world units and in pixels. It poses through the poser',
+      'render would pose the candidate with, and the poser line says which. Without',
+      '--zoom or --viewport the picture is framed as render frames the build, so its',
+      'art is render\'s frame at the same time and --max. Nothing in it is a score.',
+    ],
+  },
   {
     name: 'preview',
     runtime: { for: "its gate line is the round trip's, and it names the pages it embeds through spine-core's atlas reader" },
@@ -2704,6 +2754,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
   // Same kind as a PoseError, and printed the same way for the same reason: the
   // messages name a path, a bone or an attachment, and reprinting the whole
   // usage under them buries the one line that says what to change.
+  // A view refused before anything was drawn (issue #1357): a name the build does not have, a time off render's
+  // frame grid, a box with no size. The message lists what exists; the usage under it would bury that.
+  if (err instanceof InspectError) {
+    console.error(`rigc inspect: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof ChainFitError) {
     console.error(`rigc chainfit: ${err.message}`);
     process.exit(2);

package/src/inspect.ts

@@ -0,0 +1,751 @@
+/**
+ * `rigc inspect` — a picture of a compiled build made for an agent to read,
+ * and the legend that turns a pixel of it back into a number (issue #1357).
+ *
+ * ⭐ **The picture is a question about geometry, and the legend is its answer
+ * key.** `render` draws what the rig looks like; this draws what the rig IS at
+ * one moment — where each bone starts and ends, which way its axes point, where
+ * the world's units fall, and the line a rig declares some bones to lie along —
+ * over the same art on the same pixel grid. Without the legend the picture is
+ * for a person: an agent that reads "the elbow is at pixel 412, 180" needs the
+ * transform to say where that is in the rig spec, and every drawn bone's pixel
+ * origin and tip to say which mark is which. So the legend states the transform
+ * exactly, in both directions, and every mark the picture carries.
+ *
+ * 🔒 **It poses through what `render` poses the candidate with, and says
+ * which.** The caller hands over the candidate `loadCandidate` read and runs
+ * this through `throughPoser`, the seam `render` runs — so a rigc build is posed
+ * by rigc's own core and an export by spine-core, a fallback is named, and the
+ * art of a picture with nothing drawn over it is `render`'s frame at the same
+ * time and the same `--max`, pixel for pixel (`IN09`).
+ *
+ * ⭐ **A time is a frame of `render`'s grid.** The poser steps one continuous
+ * trajectory at `1/fps` (physics included), so the pose "at t" is the one
+ * `render --fps <fps>` wrote as frame `t·fps`, and a time off that grid is
+ * refused naming the two grid times either side rather than posed some other
+ * way — a second recipe for one moment would be a second opinion about the pose.
+ *
+ * Links nothing from the runtime: the poser is handed in.
+ */
+import { drawText, GLYPH_H, textWidth } from '../tools/font5x7.ts';
+import { Plate, type RGBA } from '../tools/plate.ts';
+import { lineGap, worldAxisDegrees } from './assertions/bodies/a51.ts';
+import {
+  BACKGROUND,
+  type BoneSnapshot,
+  type Candidate,
+  type Frame,
+  framingViewport,
+  type Poser,
+  type PoseOptions,
+  renderFrame,
+  sampleAnimation,
+  sampleSetupPose,
+  SHEET_COLUMNS,
+  SHEET_GAP,
+  SHEET_LABEL,
+  SHEET_RULE,
+  type SkinRoster,
+  throughPoser,
+  type Viewport,
+  viewportFor,
+} from './render_shared.ts';
+
+/** The legend's format tag. */
+export const INSPECT_SPEC = 'rigc-inspect/1';
+
+/** Every word `--show` takes, in the order the picture draws them (bottom first). */
+export const SHOW_WORDS = ['art', 'grid', 'declared', 'bones', 'axes', 'names'] as const;
+export type ShowWord = (typeof SHOW_WORDS)[number];
+
+/** What `--show` draws when it is not given. */
+export const DEFAULT_SHOW: readonly ShowWord[] = ['art', 'bones'];
+
+/** The frame rate a time is read on when `--fps` is not given — `render`'s own default, so the two grids are one. */
+export const INSPECT_DEFAULT_FPS = 12;
+
+/**
+ * How far from a whole frame `t·fps` may be and still name that frame, in
+ * frames. Not a tolerance on the pose: it absorbs the binary spelling of a
+ * decimal time (`0.1 · 12` is `1.2000000000000002`), and the frame posed is the
+ * whole one, filed under `index / fps` in the legend.
+ */
+export const ON_GRID_FRAMES = 1e-6;
+
+/** A zoom with no pad stated is padded by this share of the zoomed box's longer side, on every side. */
+export const DEFAULT_ZOOM_PAD_SHARE = 0.25;
+
+/** The grid's step is the smallest 1, 2 or 5 × 10ⁿ world units at least this many pixels apart. */
+export const GRID_MIN_PIXELS = 32;
+
+/** An axis is drawn this many pixels long for a bone whose world scale on it is 1 — longer or shorter as it scales. */
+export const AXIS_PIXELS = 24;
+
+/** `--dim`: every art pixel is moved toward white, keeping this share of its distance from white. */
+export const DIM_KEEP = 0.4;
+
+/** What each colour the picture draws means — the legend repeats this table. */
+export const INSPECT_COLOURS = {
+  bone: { rgba: [0, 110, 255, 255], meaning: "a bone's line, from its origin to its tip (origin + length along its world x axis)" },
+  origin: { rgba: [235, 0, 190, 255], meaning: "a bone's origin: a filled 3x3 square centred on the origin's pixel" },
+  tip: { rgba: [255, 140, 0, 255], meaning: "a bone's tip: a hollow 3x3 square centred on the tip's pixel" },
+  zero: { rgba: [255, 210, 0, 255], meaning: 'a bone of length 0: a hollow 5x5 square around its origin, which is also its tip' },
+  name: { rgba: [25, 25, 25, 255], meaning: "a bone's name, starting 4 px right of and 3 px below its origin's pixel; bones sharing that pixel list their names one per line under it, in declaration order" },
+  axisX: { rgba: [215, 30, 30, 255], meaning: `a bone's world x axis from its origin, ${AXIS_PIXELS} px long at a world scale of 1` },
+  axisY: { rgba: [20, 160, 40, 255], meaning: `a bone's world y axis from its origin, ${AXIS_PIXELS} px long at a world scale of 1` },
+  grid: { rgba: [150, 150, 150, 255], meaning: 'a grid line at a whole multiple of the step, in world units, with its value at the edge' },
+  gridZero: { rgba: [70, 70, 70, 255], meaning: 'the grid line at world x = 0 or y = 0' },
+  declared: { rgba: [0, 190, 190, 255], meaning: 'an invariants.axes line, through its two bones\' origins, across the whole tile' },
+  held: { rgba: [0, 95, 95, 255], meaning: 'the line of a bone an invariants.axes entry holds to its line, in place of the bone colour' },
+  label: { rgba: [...SHEET_LABEL], meaning: "a sheet tile's time and frame, at its bottom-left corner" },
+  rule: { rgba: [...SHEET_RULE], meaning: 'the gap between two tiles of a sheet' },
+} as const satisfies Record<string, { rgba: readonly number[]; meaning: string }>;
+
+type ColourName = keyof typeof INSPECT_COLOURS;
+const colour = (name: ColourName): RGBA => [...INSPECT_COLOURS[name].rgba] as RGBA;
+
+/** A refusal of the invocation: a name the build does not have, a time off the grid, a box that cannot be drawn. Exit 2, nothing written. */
+export class InspectError extends Error {}
+
+/** What to frame a picture to. */
+export type InspectFrame =
+  | { kind: 'shot' }
+  | { kind: 'zoom'; target: string; pad: number | null }
+  | { kind: 'viewport'; x: number; y: number; width: number; height: number };
+
+/** One `rigc inspect` invocation, its flags read but not yet checked against the build. */
+export interface InspectRequest {
+  show: readonly ShowWord[];
+  dim: boolean;
+  /** `null` is the setup pose. */
+  animation: string | null;
+  /** Seconds, in the order given; empty with no animation. */
+  times: readonly number[];
+  fps: number;
+  skin: string | undefined;
+  frame: InspectFrame;
+  maxSide: number;
+}
+
+/** What the picture is made from besides the poser: the build's own texts. */
+export interface InspectTexts {
+  /** `skeleton.json` — read for each bone's `length`, which no pose carries. */
+  skeletonText: string;
+  /** The `skeleton.model.json` that is this skeleton's, or `undefined` — what `declared` reads `rig.axes` from. */
+  modelText: string | undefined;
+}
+
+/**
+ * A planted defect, for the suite's mutants only (`IN` controls in
+ * `selftest.ts`). Each one is a way the picture or the legend can be wrong that
+ * a control has to catch by name; production passes none.
+ */
+export interface InspectPlant {
+  /** Draw every bone mark this many pixels off where the legend says it is. */
+  overlayShift?: [number, number];
+  /** State every bone mark this many pixels off where the picture draws it. */
+  legendShift?: [number, number];
+  /** Read the grid step as pixels rather than world units. */
+  gridInPixels?: boolean;
+  /** Map world y to image y without turning it over. */
+  unflipped?: boolean;
+  /** Zoom to this bone, whatever the request named. */
+  zoomBone?: string;
+}
+
+/** A point in both spaces. */
+export interface LegendPoint {
+  /** Spine world, y up, world units. */
+  world: [number, number];
+  /** The picture's pixels, y down, from its top-left corner; pixel (i, j) covers [i, i+1) x [j, j+1). */
+  pixel: [number, number];
+}
+
+/** One bone in one tile. */
+export interface LegendBone {
+  name: string;
+  parent: string | null;
+  /** The skeleton's `length` for it, world units (0 where the file states none). */
+  length: number;
+  /** `length` is 0: origin and tip are one point, marked by the `zero` square. */
+  zeroLength: boolean;
+  /** `null` when the bone is drawn; otherwise why it is not (its world matrix is 0). */
+  undrawn: string | null;
+  origin: LegendPoint;
+  tip: LegendPoint;
+  /** The ends of its drawn world x and y axes — present when `axes` is shown and the bone is drawn. */
+  axes?: { x: LegendPoint; y: LegendPoint };
+}
+
+/** One `invariants.axes` entry in one tile. */
+export interface LegendDeclared {
+  name: string;
+  through: [string, string];
+  tolerance: number;
+  /** The line's direction in world degrees (CCW from +x), or `null` when the two origins coincide (`why`). */
+  degrees: number | null;
+  why: string | null;
+  from: LegendPoint | null;
+  to: LegendPoint | null;
+  /** Each held bone's world x axis, and how far off the line it lies, as A51 measures it, at this tile's pose. */
+  bones: Array<{ name: string; degrees: number | null; off: number | null }>;
+}
+
+export interface LegendTile {
+  /** `null` for the setup pose. */
+  animation: string | null;
+  /** The frame of `render --fps <fps>` this pose is, and its time `frame / fps`. */
+  frame: number;
+  time: number;
+  /** Where the tile sits in the picture: its top-left pixel and its size. */
+  box: { x: number; y: number; width: number; height: number };
+  /** The tile's transform. `px = x0 + (x - minX)·scale`, `py = y0 + (maxY - y)·scale`; back: `x = minX + (px - x0)/scale`, `y = maxY - (py - y0)/scale`. */
+  transform: { minX: number; maxY: number; scale: number; x0: number; y0: number };
+  bones: LegendBone[];
+  declared?: LegendDeclared[];
+  grid?: { step: number; x: number[]; y: number[] };
+}
+
+export interface InspectLegend {
+  spec: typeof INSPECT_SPEC;
+  poser: 'core' | 'spine';
+  show: ShowWord[];
+  dim: boolean;
+  skin?: string;
+  animation: string | null;
+  fps: number;
+  framing:
+    | { kind: 'shot'; note: string }
+    | { kind: 'zoom'; bone?: string; slot?: string; pad: number; padFrom: 'stated' | 'default' }
+    | { kind: 'viewport' };
+  coordinates: { world: string; image: string; toPixel: string; toWorld: string };
+  /** The world box every tile is a picture of, and its pixels — one for the whole picture. */
+  viewport: { minX: number; minY: number; maxX: number; maxY: number; scale: number; width: number; height: number };
+  size: { width: number; height: number };
+  colours: Record<ColourName, { rgba: number[]; meaning: string }>;
+  tiles: LegendTile[];
+}
+
+/** The picture and its legend, and which poser posed it and why. */
+export interface InspectResult {
+  plate: Plate;
+  legend: InspectLegend;
+  poserNote: string;
+  /** Lines worth printing beside the picture: what a view drew nothing for, and why. */
+  notes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// reading the request against the build
+// ---------------------------------------------------------------------------
+
+/** `--show`'s words, refused by name — a word this command does not draw lists every one it does. */
+export function readShowWords(raw: string | undefined): ShowWord[] {
+  if (raw === undefined) return [...DEFAULT_SHOW];
+  const words = raw.split(',').map((w) => w.trim()).filter((w) => w !== '');
+  if (words.length === 0) throw new InspectError(`--show ${JSON.stringify(raw)} names no view; it takes [${SHOW_WORDS.join(', ')}]`);
+  const out: ShowWord[] = [];
+  for (const word of words) {
+    const known = SHOW_WORDS.find((w) => w === word);
+    if (known === undefined) throw new InspectError(`--show ${JSON.stringify(word)} is not a view inspect draws; it draws [${SHOW_WORDS.join(', ')}]`);
+    if (out.includes(known)) throw new InspectError(`--show names ${JSON.stringify(word)} twice`);
+    out.push(known);
+  }
+  // In the drawing order, so two spellings of one set are one picture and one legend.
+  return SHOW_WORDS.filter((w) => out.includes(w));
+}
+
+/** `--at`'s seconds. Their grid frames are checked against the animation later, where its length is known. */
+export function readTimes(raw: string | undefined): number[] {
+  if (raw === undefined) return [];
+  const parts = raw.split(',').map((s) => s.trim());
+  const times = parts.map(Number);
+  const bad = parts.find((s, i) => s === '' || !Number.isFinite(times[i]) || times[i] < 0);
+  if (bad !== undefined) throw new InspectError(`--at ${JSON.stringify(raw)}: ${JSON.stringify(bad)} is not a time in seconds of at least 0`);
+  return times;
+}
+
+/** `--zoom <name>[:<pad>]`: the name, and the pad in world units when one is stated. */
+export function readZoom(raw: string): { target: string; pad: number | null } {
+  const colon = raw.lastIndexOf(':');
+  if (colon > 0) {
+    const tail = raw.slice(colon + 1);
+    const pad = Number(tail);
+    if (tail.trim() !== '' && Number.isFinite(pad)) {
+      if (pad < 0) throw new InspectError(`--zoom ${JSON.stringify(raw)}: the pad ${tail} is below 0; it is world units on every side`);
+      return { target: raw.slice(0, colon), pad };
+    }
+  }
+  if (raw === '') throw new InspectError('--zoom needs a bone or slot name: --zoom <name>[:<pad>]');
+  return { target: raw, pad: null };
+}
+
+/** The grid frame `t` names at `fps`, or the refusal naming the two either side. */
+function gridFrame(t: number, fps: number, duration: number, animation: string): number {
+  const exact = t * fps;
+  const frame = Math.round(exact);
+  const last = Math.round(duration * fps);
+  if (Math.abs(exact - frame) > ON_GRID_FRAMES) {
+    const below = Math.floor(exact);
+    throw new InspectError(
+      `--at ${t} is not on the ${fps} fps frame grid render draws "${animation}" on: the frames either side are ` +
+        `${below} (${(below / fps).toFixed(4)}s) and ${below + 1} (${((below + 1) / fps).toFixed(4)}s). Name one of them, or pass --fps for another grid`,
+    );
+  }
+  if (frame > last) {
+    throw new InspectError(
+      `--at ${t} is past the end of "${animation}": it lasts ${duration}s, frame ${last} (${(last / fps).toFixed(4)}s) at ${fps} fps`,
+    );
+  }
+  return frame;
+}
+
+/** Each bone's `length` off the skeleton file — Spine's default is 0, which is what a file that states none means. */
+export function boneLengths(skeletonText: string): Map<string, number> {
+  const parsed = JSON.parse(skeletonText) as { bones?: Array<{ name?: unknown; length?: unknown }> };
+  const out = new Map<string, number>();
+  for (const bone of parsed.bones ?? []) {
+    if (typeof bone.name !== 'string') continue;
+    out.set(bone.name, typeof bone.length === 'number' ? bone.length : 0);
+  }
+  return out;
+}
+
+/** One `invariants.axes` entry, as the model document's `rig.axes` spells it. */
+export interface DeclaredAxis {
+  name: string;
+  through: [string, string];
+  bones: string[];
+  tolerance: number;
+}
+
+/** `rig.axes` off the build's model document, or the refusal saying why `declared` has nothing to read. */
+export function declaredAxes(modelText: string | undefined): DeclaredAxis[] {
+  if (modelText === undefined) {
+    throw new InspectError(
+      '--show declared reads invariants.axes from the skeleton.model.json `build` writes beside a skeleton, and there is none ' +
+        'here whose spine.sha256 is this skeleton\'s — a Spine export states no rig invariants',
+    );
+  }
+  const doc = JSON.parse(modelText) as { rig?: { axes?: unknown } };
+  const axes = doc.rig?.axes;
+  if (!Array.isArray(axes)) {
+    throw new InspectError(
+      '--show declared reads rig.axes from the skeleton.model.json beside this skeleton, and that document states no rig.axes — ' +
+        'it was written by a rigc older than invariants.axes; build it again',
+    );
+  }
+  return axes as DeclaredAxis[];
+}
+
+// ---------------------------------------------------------------------------
+// drawing
+// ---------------------------------------------------------------------------
+
+/** One pixel, set outright; off the tile is nothing. */
+function put(plate: Plate, x: number, y: number, rgba: RGBA): void {
+  if (x < 0 || y < 0 || x >= plate.width || y >= plate.height) return;
+  const i = (y * plate.width + x) * 4;
+  plate.data[i] = rgba[0];
+  plate.data[i + 1] = rgba[1];
+  plate.data[i + 2] = rgba[2];
+  plate.data[i + 3] = rgba[3];
+}
+
+/** A one-pixel line between two continuous pixel positions: every pixel whose square a dense walk along it enters. */
+function line(plate: Plate, x0: number, y0: number, x1: number, y1: number, rgba: RGBA): void {
+  const steps = Math.ceil(Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0)) * 2) + 1;
+  for (let s = 0; s <= steps; s++) {
+    const u = s / steps;
+    put(plate, Math.floor(x0 + (x1 - x0) * u), Math.floor(y0 + (y1 - y0) * u), rgba);
+  }
+}
+
+/** A square of side `2r + 1` centred on pixel (cx, cy): filled, or its border only. */
+function square(plate: Plate, cx: number, cy: number, r: number, hollow: boolean, rgba: RGBA): void {
+  for (let dy = -r; dy <= r; dy++) {
+    for (let dx = -r; dx <= r; dx++) {
+      if (hollow && Math.abs(dx) !== r && Math.abs(dy) !== r) continue;
+      put(plate, cx + dx, cy + dy, rgba);
+    }
+  }
+}
+
+function text(plate: Plate, value: string, x: number, y: number, rgba: RGBA): void {
+  drawText(value, x, y, 1, (px, py) => put(plate, px, py, rgba));
+}
+
+/** The grid step: the smallest 1, 2 or 5 × 10ⁿ world units whose lines land at least `GRID_MIN_PIXELS` apart. */
+export function gridStep(scale: number): number {
+  const least = GRID_MIN_PIXELS / scale;
+  let power = 10 ** Math.floor(Math.log10(least));
+  for (;;) {
+    for (const m of [1, 2, 5]) if (m * power >= least) return m * power;
+    power *= 10;
+  }
+}
+
+/** A grid value as its label prints it: as many decimals as the step has, no more. */
+function gridLabel(value: number, step: number): string {
+  const decimals = Math.max(0, -Math.floor(Math.log10(step) + 1e-9));
+  const shown = value.toFixed(decimals);
+  return /^-0(\.0*)?$/.test(shown) ? shown.slice(1) : shown;
+}
+
+/** Whole multiples of `step` from `lo` to `hi`, inclusive. */
+function multiples(lo: number, hi: number, step: number): number[] {
+  const out: number[] = [];
+  for (let k = Math.ceil(lo / step); k * step <= hi; k++) out.push(k * step === 0 ? 0 : k * step);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// the view
+// ---------------------------------------------------------------------------
+
+/** The poses one picture is of: the frames, in the order the request named their times. */
+function posesOf(poser: Poser, request: InspectRequest, needAttachments: boolean): Array<{ frame: Frame; index: number }> {
+  const opts: PoseOptions = { bones: true, ...(needAttachments ? { geometry: true } : {}), ...(request.skin === undefined ? {} : { skin: request.skin }) };
+  if (request.animation === null) return [{ frame: sampleSetupPose(poser, opts)[0], index: 0 }];
+  const animation = poser.animations.find((a) => a.name === request.animation);
+  if (animation === undefined) {
+    throw new InspectError(`no animation ${JSON.stringify(request.animation)} in this skeleton; it has [${poser.animations.map((a) => a.name).join(', ') || 'none'}]`);
+  }
+  const indices = request.times.map((t) => gridFrame(t, request.fps, animation.duration, animation.name));
+  const seen = new Set<number>();
+  for (const [i, index] of indices.entries()) {
+    if (seen.has(index)) throw new InspectError(`--at names frame ${index} (${(index / request.fps).toFixed(4)}s) twice — at ${request.times[i]}`);
+    seen.add(index);
+  }
+  const frames = sampleAnimation(poser, animation.name, request.fps, opts);
+  return indices.map((index) => ({ frame: frames[index], index }));
+}
+
+/** The world box of what `--zoom` names, over every pose of the picture. */
+function zoomBox(
+  poser: Poser,
+  poses: ReadonlyArray<{ frame: Frame }>,
+  target: string,
+  lengths: Map<string, number>,
+): { box: [number, number, number, number]; bone?: string; slot?: string } {
+  const isBone = poser.bones.some((b) => b.name === target);
+  const isSlot = poser.slots.some((s) => s.name === target);
+  if (isBone && isSlot) {
+    // A rig names a slot after its bone often; which box is meant is the caller's to say, not a guess.
+    throw new InspectError(
+      `--zoom ${JSON.stringify(target)} names both a bone and a slot; say which with --zoom bone:${target} or --zoom slot:${target}`,
+    );
+  }
+  let kind: 'bone' | 'slot' | null = isBone ? 'bone' : isSlot ? 'slot' : null;
+  let name = target;
+  for (const prefix of ['bone', 'slot'] as const) {
+    if (kind === null && target.startsWith(`${prefix}:`)) {
+      name = target.slice(prefix.length + 1);
+      const has = prefix === 'bone' ? poser.bones.some((b) => b.name === name) : poser.slots.some((s) => s.name === name);
+      if (has) kind = prefix;
+    }
+  }
+  if (kind === null) {
+    throw new InspectError(
+      `--zoom ${JSON.stringify(target)}: no bone or slot of that name. Bones: [${poser.bones.map((b) => b.name).join(', ')}]; ` +
+        `slots: [${poser.slots.map((s) => s.name).join(', ')}]`,
+    );
+  }
+  const box: [number, number, number, number] = [Infinity, Infinity, -Infinity, -Infinity];
+  const take = (x: number, y: number): void => {
+    box[0] = Math.min(box[0], x);
+    box[1] = Math.min(box[1], y);
+    box[2] = Math.max(box[2], x);
+    box[3] = Math.max(box[3], y);
+  };
+  for (const { frame } of poses) {
+    if (kind === 'bone') {
+      const b = frame.bones?.find((s) => s.name === name);
+      if (b === undefined) continue;
+      if (b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0) continue;
+      const length = lengths.get(name) ?? 0;
+      take(b.worldX, b.worldY);
+      take(b.worldX + length * b.a, b.worldY + length * b.c);
+    } else {
+      for (const shown of frame.attachments ?? []) {
+        if (shown.slot !== name) continue;
+        for (let i = 0; i + 1 < shown.vertices.length; i += 2) take(shown.vertices[i], shown.vertices[i + 1]);
+      }
+    }
+  }
+  if (!box.every(Number.isFinite)) {
+    throw new InspectError(
+      kind === 'bone'
+        ? `--zoom ${JSON.stringify(target)}: bone "${name}" is not posed at any time of this picture (its world matrix is 0 — unposed by the skin, or a scale of 0)`
+        : `--zoom ${JSON.stringify(target)}: slot "${name}" shows no region or mesh at any time of this picture`,
+    );
+  }
+  return kind === 'bone' ? { box, bone: name } : { box, slot: name };
+}
+
+/**
+ * The picture and its legend, posed through `candidate`'s chosen poser — the
+ * one `render` would pose it with (`throughPoser`), named in the result.
+ */
+export function inspectCandidate(candidate: Candidate, texts: InspectTexts, request: InspectRequest, plant: InspectPlant = {}): InspectResult {
+  const { facts, pages } = candidate;
+  if (request.skin !== undefined && !facts.skins.includes(request.skin)) {
+    throw new InspectError(`no skin ${JSON.stringify(request.skin)} in this skeleton; it declares [${facts.skins.join(', ') || 'none'}]`);
+  }
+  if (request.animation === null && request.times.length > 0) {
+    throw new InspectError('--at needs --animation <name>: the setup pose has no time. Without --at the picture is the setup pose');
+  }
+  if (request.animation !== null && request.times.length === 0) {
+    throw new InspectError(`--animation ${request.animation} needs --at <s[,s…]>: the times of it to draw, on the ${request.fps} fps grid render draws it on`);
+  }
+  const axes = request.show.includes('declared') ? declaredAxes(texts.modelText) : [];
+  const lengths = boneLengths(texts.skeletonText);
+  const posed = throughPoser(candidate.choice, (poser, roster) => view(poser, roster, pages, lengths, axes, request, plant));
+  return { ...posed.value, legend: { ...posed.value.legend, poser: posed.poser }, poserNote: posed.note };
+}
+
+function view(
+  poser: Poser,
+  roster: SkinRoster,
+  pages: Map<string, Plate>,
+  lengths: Map<string, number>,
+  axes: readonly DeclaredAxis[],
+  request: InspectRequest,
+  plant: InspectPlant,
+): Omit<InspectResult, 'poserNote'> {
+  const notes: string[] = [];
+  const zooming = request.frame.kind === 'zoom';
+  const poses = posesOf(poser, request, zooming);
+  // The world box and its pixels: one for every tile, so a sheet's tiles overlay.
+  let viewport: Viewport;
+  let framing: InspectLegend['framing'];
+  if (request.frame.kind === 'viewport') {
+    const f = request.frame;
+    viewport = viewportFor(f.x, f.y, f.x + f.width, f.y + f.height, request.maxSide);
+    framing = { kind: 'viewport' };
+  } else if (request.frame.kind === 'zoom') {
+    const target = plant.zoomBone ?? request.frame.target;
+    const found = zoomBox(poser, poses, target, lengths);
+    const [x0, y0, x1, y1] = found.box;
+    const longer = Math.max(x1 - x0, y1 - y0);
+    const pad = request.frame.pad ?? longer * DEFAULT_ZOOM_PAD_SHARE;
+    if (longer + 2 * pad === 0) {
+      throw new InspectError(
+        `--zoom ${JSON.stringify(request.frame.target)}: what it names is one point, (${x0}, ${y0}), at every time of this picture, so ` +
+          `the box has no size — state a pad in world units: --zoom ${request.frame.target}:<pad>`,
+      );
+    }
+    viewport = viewportFor(x0 - pad, y0 - pad, x1 + pad, y1 + pad, request.maxSide);
+    framing = { kind: 'zoom', ...(found.bone === undefined ? {} : { bone: found.bone }), ...(found.slot === undefined ? {} : { slot: found.slot }), pad, padFrom: request.frame.pad === null ? 'default' : 'stated' };
+  } else {
+    const shot = framingViewport(poser, request.maxSide, request.skin === undefined ? undefined : { skin: request.skin }, roster);
+    if (shot === null) throw new InspectError('this skeleton poses no drawable attachment in any animation or in its setup pose — there is nothing to frame; name a box with --viewport');
+    viewport = shot;
+    framing = { kind: 'shot', note: "render's own framing: every animation's posed box at 60 fps, padded — the grid render draws this build on at the same --max" };
+  }
+  const { width, height, scale } = viewport;
+  const sheet = poses.length > 1;
+  const columns = sheet ? Math.min(SHEET_COLUMNS, poses.length) : 1;
+  const rows = Math.ceil(poses.length / columns);
+  const gap = sheet ? SHEET_GAP : 0;
+  const plate = new Plate(columns * (width + gap) + gap, rows * (height + gap) + gap);
+  for (let i = 0; i < plate.data.length; i += 4) plate.data.set(colour('rule'), i);
+  const [shiftX, shiftY] = plant.overlayShift ?? [0, 0];
+  const [lieX, lieY] = plant.legendShift ?? [0, 0];
+  const tiles: LegendTile[] = [];
+  for (const [i, { frame, index }] of poses.entries()) {
+    const x0 = gap + (i % columns) * (width + gap);
+    const y0 = gap + Math.floor(i / columns) * (height + gap);
+    // ⭐ The one projection both the picture and the legend read: continuous pixels in the whole picture.
+    const toPixel = (wx: number, wy: number): [number, number] => [
+      x0 + (wx - viewport.minX) * scale,
+      y0 + (plant.unflipped ? wy - viewport.minY : viewport.maxY - wy) * scale,
+    ];
+    const point = (wx: number, wy: number): LegendPoint => {
+      const [px, py] = toPixel(wx, wy);
+      return { world: [wx, wy], pixel: [px + lieX, py + lieY] };
+    };
+    const tile = request.show.includes('art') ? renderFrame(frame, pages, viewport, BACKGROUND) : filled(width, height, BACKGROUND);
+    if (request.dim) {
+      for (let p = 0; p < tile.data.length; p += 4) {
+        for (let c = 0; c < 3; c++) tile.data[p + c] = Math.round(255 - (255 - tile.data[p + c]) * DIM_KEEP);
+      }
+    }
+    // Drawn on the tile in tile pixels; `tx`/`ty` take a picture pixel back to the tile's.
+    const tx = (px: number): number => px - x0;
+    const ty = (py: number): number => py - y0;
+    const legendTile: LegendTile = {
+      animation: request.animation,
+      frame: index,
+      time: request.animation === null ? 0 : index / request.fps,
+      box: { x: x0, y: y0, width, height },
+      transform: { minX: viewport.minX, maxY: viewport.maxY, scale, x0, y0 },
+      bones: [],
+    };
+    if (request.show.includes('grid')) {
+      const step = plant.gridInPixels ? gridStep(scale) / scale : gridStep(scale);
+      const xs = multiples(viewport.minX, viewport.maxX, step);
+      const ys = multiples(viewport.minY, viewport.maxY, step);
+      for (const gx of xs) {
+        const col = Math.floor(tx(toPixel(gx, 0)[0]));
+        for (let y = 0; y < height; y++) put(tile, col, y, colour(gx === 0 ? 'gridZero' : 'grid'));
+      }
+      for (const gy of ys) {
+        const row = Math.floor(ty(toPixel(0, gy)[1]));
+        for (let x = 0; x < width; x++) put(tile, x, row, colour(gy === 0 ? 'gridZero' : 'grid'));
+      }
+      for (const gx of xs) text(tile, gridLabel(gx, step), Math.floor(tx(toPixel(gx, 0)[0])) + 2, 2, colour('gridZero'));
+      for (const gy of ys) text(tile, gridLabel(gy, step), 2, Math.floor(ty(toPixel(0, gy)[1])) + 2, colour('gridZero'));
+      legendTile.grid = { step, x: xs, y: ys };
+    }
+    const snapshots = new Map<string, BoneSnapshot>((frame.bones ?? []).map((b) => [b.name, b]));
+    const isPosed = (b: BoneSnapshot | undefined): b is BoneSnapshot => b !== undefined && !(b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0);
+    const held = new Set<string>();
+    if (request.show.includes('declared')) {
+      legendTile.declared = [];
+      for (const axis of axes) {
+        const a = snapshots.get(axis.through[0]);
+        const b = snapshots.get(axis.through[1]);
+        const entry: LegendDeclared = { name: axis.name, through: axis.through, tolerance: axis.tolerance, degrees: null, why: null, from: null, to: null, bones: [] };
+        if (!isPosed(a) || !isPosed(b)) {
+          entry.why = `${!isPosed(a) ? axis.through[0] : axis.through[1]} is not posed at this time (its world matrix is 0), so the line has no point there`;
+        } else if (a.worldX === b.worldX && a.worldY === b.worldY) {
+          entry.why = `"${axis.through[0]}" and "${axis.through[1]}" share the world origin (${a.worldX}, ${a.worldY}), so they draw no line`;
+        } else {
+          const degrees = (Math.atan2(b.worldY - a.worldY, b.worldX - a.worldX) * 180) / Math.PI;
+          entry.degrees = degrees;
+          entry.from = point(a.worldX, a.worldY);
+          entry.to = point(b.worldX, b.worldY);
+          // Across the whole tile: extend the line past both ends by the tile's diagonal, in world units.
+          const reach = Math.hypot(viewport.maxX - viewport.minX, viewport.maxY - viewport.minY);
+          const ux = (b.worldX - a.worldX) / Math.hypot(b.worldX - a.worldX, b.worldY - a.worldY);
+          const uy = (b.worldY - a.worldY) / Math.hypot(b.worldX - a.worldX, b.worldY - a.worldY);
+          const [p0x, p0y] = toPixel(a.worldX - ux * reach, a.worldY - uy * reach);
+          const [p1x, p1y] = toPixel(a.worldX + ux * reach, a.worldY + uy * reach);
+          line(tile, tx(p0x) + shiftX, ty(p0y) + shiftY, tx(p1x) + shiftX, ty(p1y) + shiftY, colour('declared'));
+          for (const name of axis.bones) {
+            const s = snapshots.get(name);
+            if (!isPosed(s) || (s.a === 0 && s.c === 0)) {
+              entry.bones.push({ name, degrees: null, off: null });
+              continue;
+            }
+            const found = worldAxisDegrees(s);
+            entry.bones.push({ name, degrees: found, off: lineGap(found, degrees) });
+            held.add(name);
+          }
+        }
+        if (entry.why !== null && i === 0) notes.push(`declared: axis "${axis.name}" — ${entry.why}`);
+        legendTile.declared.push(entry);
+      }
+      if (axes.length === 0 && i === 0) notes.push('declared: the rig declares no invariants.axes — nothing drawn for it');
+    }
+    // Every bone, in declaration order — drawn or not, so the legend names each.
+    const drawn: Array<{ bone: LegendBone; o: [number, number]; t: [number, number] }> = [];
+    for (const declared of poser.bones) {
+      const s = snapshots.get(declared.name);
+      const length = lengths.get(declared.name) ?? 0;
+      const posedBone = isPosed(s);
+      const ox = s?.worldX ?? 0;
+      const oy = s?.worldY ?? 0;
+      const bone: LegendBone = {
+        name: declared.name,
+        parent: declared.parent,
+        length,
+        zeroLength: length === 0,
+        undrawn: posedBone ? null : 'its world matrix is 0 at this time — unposed by the skin, or a scale of 0',
+        origin: point(ox, oy),
+        tip: point(ox + length * (s?.a ?? 0), oy + length * (s?.c ?? 0)),
+      };
+      if (posedBone && request.show.includes('axes')) {
+        const unit = AXIS_PIXELS / scale;
+        bone.axes = { x: point(ox + s.a * unit, oy + s.c * unit), y: point(ox + s.b * unit, oy + s.d * unit) };
+      }
+      legendTile.bones.push(bone);
+      if (posedBone) drawn.push({ bone, o: toPixel(ox, oy), t: toPixel(bone.tip.world[0], bone.tip.world[1]) });
+    }
+    // Lines, then axes, then names, then the marks — so a mark is never covered.
+    const at = (p: [number, number]): [number, number] => [tx(p[0]) + shiftX, ty(p[1]) + shiftY];
+    if (request.show.includes('bones')) {
+      for (const { bone, o, t } of drawn) {
+        if (bone.zeroLength) continue;
+        const [ax, ay] = at(o);
+        const [bx, by] = at(t);
+        line(tile, ax, ay, bx, by, colour(held.has(bone.name) ? 'held' : 'bone'));
+      }
+    }
+    if (request.show.includes('axes')) {
+      for (const { bone, o } of drawn) {
+        if (bone.axes === undefined) continue;
+        const [ax, ay] = at(o);
+        for (const [end, name] of [[bone.axes.y, 'axisY'], [bone.axes.x, 'axisX']] as const) {
+          const [ex, ey] = at(toPixel(end.world[0], end.world[1]));
+          line(tile, ax, ay, ex, ey, colour(name));
+        }
+      }
+    }
+    if (request.show.includes('names')) {
+      // Bones whose origins share a pixel — a `_ctl` parent and its child, a chain's joint — list their names one per
+      // line under it, in declaration order, rather than printing them over each other.
+      const below = new Map<string, number>();
+      for (const { bone, o } of drawn) {
+        const [ax, ay] = at(o);
+        const key = `${Math.floor(ax)},${Math.floor(ay)}`;
+        const line = below.get(key) ?? 0;
+        below.set(key, line + 1);
+        text(tile, bone.name, Math.floor(ax) + 4, Math.floor(ay) + 3 + line * (GLYPH_H + 2), colour('name'));
+      }
+    }
+    if (request.show.includes('bones')) {
+      for (const { bone, t } of drawn) {
+        if (bone.zeroLength) continue;
+        const [bx, by] = at(t);
+        square(tile, Math.floor(bx), Math.floor(by), 1, true, colour('tip'));
+      }
+      for (const { bone, o } of drawn) {
+        const [ax, ay] = at(o);
+        if (bone.zeroLength) square(tile, Math.floor(ax), Math.floor(ay), 2, true, colour('zero'));
+        square(tile, Math.floor(ax), Math.floor(ay), 1, false, colour('origin'));
+      }
+    }
+    if (sheet) {
+      const label = request.animation === null ? 'setup' : `t=${legendTile.time.toFixed(3)} f${index}`;
+      const ly = height - GLYPH_H - 2;
+      for (let y = ly - 1; y < ly + GLYPH_H + 1; y++) for (let x = 1; x < textWidth(label, 1) + 3; x++) put(tile, x, y, BACKGROUND);
+      text(tile, label, 2, ly, colour('label'));
+    }
+    for (let y = 0; y < height; y++) plate.data.set(tile.data.subarray(y * width * 4, (y + 1) * width * 4), ((y0 + y) * plate.width + x0) * 4);
+    tiles.push(legendTile);
+  }
+  const legend: InspectLegend = {
+    spec: INSPECT_SPEC,
+    poser: 'core',
+    show: [...request.show],
+    dim: request.dim,
+    ...(request.skin === undefined ? {} : { skin: request.skin }),
+    animation: request.animation,
+    fps: request.fps,
+    framing,
+    coordinates: {
+      world: 'spine world: y up, world units',
+      image: 'the picture: y down, from its top-left corner; pixel (i, j) covers [i, i+1) x [j, j+1), so a position\'s pixel is its floor',
+      toPixel: 'px = x0 + (x - minX) * scale; py = y0 + (maxY - y) * scale — each tile\'s own transform',
+      toWorld: 'x = minX + (px - x0) / scale; y = maxY - (py - y0) / scale',
+    },
+    viewport: { minX: viewport.minX, minY: viewport.minY, maxX: viewport.maxX, maxY: viewport.maxY, scale, width, height },
+    size: { width: plate.width, height: plate.height },
+    colours: Object.fromEntries(Object.entries(INSPECT_COLOURS).map(([k, v]) => [k, { rgba: [...v.rgba], meaning: v.meaning }])) as InspectLegend['colours'],
+    tiles,
+  };
+  return { plate, legend, notes };
+}
+
+function filled(width: number, height: number, rgba: RGBA): Plate {
+  const plate = new Plate(width, height);
+  for (let i = 0; i < plate.data.length; i += 4) plate.data.set(rgba, i);
+  return plate;
+}
+
+/** The legend as its file holds it: two-space JSON and a newline, so two runs over one build are one byte sequence. */
+export function legendText(legend: InspectLegend): string {
+  return `${JSON.stringify(legend, null, 2)}\n`;
+}