spine-rigc 2.1.3 → 2.2.0

package/README.md

@@ -622,7 +622,10 @@ example corpus, ingested, rebuilt through the pack beside it and `diff`ed agains
 source, comes back **12 of 12, no blockers, 1.000 on every measure the report
 carries** — and each rebuild is its export's own text in canonical form, apart from
 the header's `hash` and `spine`: the editor's project hash and the runtime version
-rigc stamps, the two keys the rig spec has no field for by design (12 of 12).
+rigc stamps, the two keys the rig spec has no field for by design (12 of 12) — and
+the header's box, which `build` computes rather than carries (issue #907): the rebuild
+writes spine-core's `getBounds` over the export on the header's 1e-6 grid at float32, equal on all twelve,
+where the editor wrote its own arithmetic, up to 0.0071 units away.
 [INGEST.md §2.3](docs/INGEST.md) states that pass line and why those two are the
 exceptions.
 
@@ -643,7 +646,10 @@ specs are still written — a spec plus a list of what is missing from it beats
   too**, for the opposite reason: two sources for one value, where the file is the record
   of what was measured. **All twelve exports in the example corpus carry a stage** and
   none of them needs the flag. It is the value that costs least to get wrong, because
-  `diff` reports the box and gates nothing on it.
+  `diff` reports the box and gates nothing on it. 🔁 The box an export's header carries
+  is its setup-pose bounding box, and it becomes the rebuild's *stage*; the rebuild's own
+  header is computed again, because since issue #907 `build` writes the setup-pose
+  bounding box there — never the stage — held to spine-core's `getBounds`.
 - **An animation's duration.** The format has no such field. The largest key time is
   the only derivable answer and it is what a runtime plays to; it is wrong for an
   animation that holds its last pose past its last key, so it is recorded as a finding

package/docs/AUTHORING.md

@@ -947,7 +947,7 @@ repository builds on every run.
 | `--art loose` (default) | name an `image` per attachment — `<path or placeholder>.png` — so the rebuild resolves loose PNGs and rigc measures them |
 | `--art none` | state `width`/`height` only, so the rebuild is `build --atlas-in <pack.atlas>` and every part resolves out of the pack |
 | `--images <dir>` | **write** the rig spec's own `images` directory, spelled relative to `--out`, so the rebuild is a plain `build --rig … --motion … --out …`. Without it the field is left out and every `image` resolves against `--out` itself, which holds the specs and no art — so every rebuild has to repeat `build --images <dir>`. Refused together with `--art none`, which writes no `image` for it to be the base of |
-| `--stage x,y,w,h` | a setup bounding box to **add** to a skeleton that declares none — without it the absence is carried as `"width": null, "height": null`. An editor export *may* be such a file; every export under `examples/` carries a box and `ingest` reads it straight through — so passing the flag at one of them is **refused**, naming both boxes, rather than silently doing nothing |
+| `--stage x,y,w,h` | a stage to **add** to a skeleton whose header carries no box (a header's box — its setup-pose bounding box — is otherwise read as the rebuild's stage) — without it the absence is carried as `"width": null, "height": null`. An editor export *may* be such a file; every export under `examples/` carries a box and `ingest` reads it straight through — so passing the flag at one of them is **refused**, naming both boxes, rather than silently doing nothing |
 | `--name <n>` | the rig spec's `name`, which the motion spec's `archetype` must equal (default: the file's basename) |
 
 ⚠️ **`ingest --images` and `build --images` point opposite ways.** `build --images`
@@ -968,23 +968,40 @@ supply it from the project the file came from, or from the editor's own canvas
 is recorded as a `NO_STAGE` judgement. A header stating **half** a stage (an origin
 with no extent) is a `NO_STAGE` blocker: the spec holds a stage as four fields or none.
 
+🔁 **Where the rebuild's stage comes from** (issue #907). A **rigc build**'s stage is read
+from the `skeleton.model.json` beside it, when that document's `spine.sha256` is the
+skeleton's digest (the run prints `stage … read from the skeleton.model.json beside it`) —
+its header is the setup-pose bounding box, not the stage. An **export**'s stage is its
+header box. A file's header box is its setup-pose bounding box, and for an export `ingest`
+writes it into the spec as the rebuild's **stage** — the only box an export carries, so `A14` and `A19` on the rebuild measure against it, as
+they did on the export. The rebuild's own header is then not carried but computed:
+`build` writes the bounding box of what it drew, which is `getBounds` of the source at
+float32 when the rebuild draws the source's vertices — on the twelve example exports it
+does, to the bit — and the editor's numbers are its own arithmetic, up to 0.0071 units
+away. So the four header numbers of a rebuild are not the export's spelling, and that
+is not a loss: the export's box is in the spec, as the stage. (A licensed 4.3.26
+editor's command-line import and export carried a header box through **verbatim** —
+a forged `0, 0, 1, 1` came back as `width 1, height 1` — so the editor does not
+recompute it on a round trip either; whatever box a file states travels.)
+
 ⛔ **The flag is refused beside a box the file states.** Two sources for one value, and
 the file is the one that was measured — so `ingest` names both boxes and stops rather
 than writing one of them and saying nothing. Drop the flag, or correct `skeleton` in the
 source if its box is wrong. What it does **not** do is refuse an *omitted origin*:
 inside a declared extent an omitted `x`/`y` is `0` — the reading `build` emits and
 `diff` compares — so the written spec states it and a `LOSS HEADER_ORIGIN` line says
-the source omitted it and that the rebuild will spell it.
+the source omitted it and that the rebuilt header will spell an origin — the bounding
+box's, wherever the art sits.
 
 ⚠️ **All twelve exports under `examples/` declare `x`, `y`, `width` and `height`**,
-`ingest` reads each box straight through, and not one needs the flag. What an
+`ingest` reads each box straight through into the stage, and not one needs the flag. What an
 editor export *may* do is carry none: a rigc build that declares no stage came back
 from a Spine 4.3.26 round trip with a header of `hash`, `spine`, `images`, `audio`
 and **no box at all** — the editor preserves the absence rather than inventing a
 stage. So `--stage` is for a file that really has none; the example corpus holds no
 such file, and production exports do — 48 of 48 measured. It is the value that
-costs least to get wrong: `diff` reports the box as `stage_present` and
-`stage_box` and both are `(reported)`, so nothing on the ladder consults them.
+costs least to get wrong: `diff` reports the header's box as `bounds_present` and
+`bounds_box` and both are `(reported)`, so nothing on the ladder consults them.
 
 ⚠️ **The duration is a convention, and it is recorded as one.** Skeleton JSON has no
 duration field. The largest key time is the only derivable answer and it is what a
@@ -1530,8 +1547,8 @@ that is a defect in this guide: report it.
 
 | Field | Spine meaning | Default |
 | --- | --- | --- |
-| `x`, `y` | setup-pose bounding box origin | `0` — and refused outright beside a stated absence, below |
-| `width`, `height` | setup-pose bounding box size, **or both `null` for "this skeleton declares no stage"** | falls back to the manifest's crop; **with neither the number nor the `null`, the compile fails** |
+| `x`, `y` | the **stage**'s origin — rigc's own field: see below | `0` — and refused outright beside a stated absence, below |
+| `width`, `height` | the **stage**'s size, **or both `null` for "this skeleton declares no stage"** | falls back to the manifest's crop; **with neither the number nor the `null`, the compile fails** |
 | `fps` | nonessential editor hint | `SkeletonData.fps` stays 30 |
 | `referenceScale` | 4.2+ physics/scale reference: a physics constraint's `wind` and `gravity` act over it | parser default 100. Carried as stated — never rounded — and the header leaves it out at exactly 100. `skeleton.model.json` always states it, as `referenceScale` after `spec`: the number stated, or 100 when none is — the value the Spine file is read as — and rigc's posing core steps wind and gravity over it (issue #958) |
 | `images` | where the editor's import looks for the part PNGs, as a path from the skeleton file | **written for you**: under `--copy-images` the `--out` directory itself, spelled `../<its basename>/` (a literal `./` is dropped by the editor on import; a named directory is kept and every part is found — measured on 4.3.23); otherwise the relative path from `--out` to the one directory the spec names every part PNG in (the rig's images directory, or the manifest's plates). A declared value is carried through verbatim — and overridden by `--copy-images`, which moved the parts. Parts spread over several directories have no single true path, so nothing is written |
@@ -1547,6 +1564,33 @@ links, not the editor that will open the file, and the warning is harmless.
 `width`/`height` are what `A14` and `A19` measure against, so a guessed stage is a
 gate measuring against a number nobody wrote down.
 
+🔁 **The stage is not what `skeleton.json`'s header carries** (issue #907). In the
+Spine format the header's `x`, `y`, `width`, `height` are the **setup-pose bounding
+box** — the box around the attachments at rest, which a player reads to scale and lay
+the figure out. rigc's stage is something else: the working area the art was painted
+in (a manifest's crop), the frame the coordinate transform flips against, and what
+`A14`/`A19` measure against. Until issue #907 `build` copied the stage into the header,
+so a consumer reading the file the way the format says got the crop — 3.18 times the
+figure's area on a figure that fills a quarter of its crop. Now:
+
+- **the header** carries the setup-pose bounding box, which `build` computes with
+  rigc's own core: every region and mesh the default skin shows at the setup pose, no
+  skin set, every constraint applied, on active bones only — clipping polygons,
+  bounding boxes, paths and points not counted — `x`/`y` the least corner (bottom-left,
+  y up), each of the four on the model's 1e-6 grid at float32 (a box edge at the origin
+  is otherwise a cancellation residue such as `1.1368684e-13` that follows the platform's
+  libm to the last bit). It is held to spine-core's
+  `Skeleton.getBounds()` at tolerance 0 (`tools/core_gate.ts`, its `BOUNDS` rows), so
+  both entries write the same bytes;
+- **the stage** stays the rig spec's (or the crop), and `skeleton.model.json` states it
+  as `stage` — `A14`, `A19` and `explain` read it there, on `build` and on `validate`
+  over a directory whose model document is the skeleton's own;
+- **no box** is written where the rig declares no stage (`null`, below), where the
+  setup pose draws nothing, or where a region has no atlas rectangle (that build is
+  refused by `A08` anyway).
+
+You do not author the box and there is no field for it: it is a measurement of the rig.
+
 ⭐ **A skeleton may declare no stage, and saying so is not the same as saying
 nothing.** Write the pair as `null`:
 
@@ -1554,8 +1598,9 @@ nothing.** Write the pair as `null`:
 "skeleton": { "width": null, "height": null }
 ```
 
-and the emitted header carries **none** of `x`/`y`/`width`/`height` — which is
-what an export of a skeleton whose stage was never set looks like. `null` is this
+and the emitted header carries **none** of `x`/`y`/`width`/`height` — the input
+that asked for no box gets none, which is also what an export of a skeleton whose
+bounds were never set looks like. `null` is this
 spec's spelling for a stated absence wherever it has one (`slots[].attachment` is
 `null` for "show nothing").
 
@@ -1574,32 +1619,34 @@ would be:
 
 | Reader | With a stage | Without one |
 | --- | --- | --- |
-| `build` | emits `x`/`y`/`width`/`height` | emits none of them |
+| `build` | emits `x`/`y`/`width`/`height` — the setup-pose bounding box, not the stage | emits none of them |
 | `A14_NO_FULL_FRAME_MESH` | fails a mesh as big as the stage | **SKIP**, by name |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | exempts the base plate a cut manifest names — the part whose window is the crop — and, on a build that names none, the one image that covers the stage | a manifest build exempts the plate it names, exactly as with one. A rig-spec build names no base plate, so an opaque part is refused with *"this skeleton declares no stage size to measure one against, and the build names no base plate"* and the two ways to decide it: a `skeleton` stage the plate covers, or *"build from a cut manifest, whose base plate is the part whose window is the crop"* |
-| `diff` | `stage_present` and `stage_box` | `stage_present` 1/1 when neither side declares one (agreement), `stage_box` 0/0 |
+| `diff` | `bounds_present` and `bounds_box` — the header's box, which is the bounding box | `bounds_present` 1/1 when neither header carries one (agreement), `bounds_box` 0/0 |
 | `explain` | `stage  W x H` | `stage  none declared` |
 | `render` | frames the posed extent of every animation | the same frames, plus a line saying the viewport is the posed extent and no stage |
 | `preview` | the Spine Web Player frames the posed extent of the animation it plays | the same, plus the same line |
 | `check` | fits the candidate's world box from what it draws | the same figures, plus a note saying so |
 | `build --pack` | never reads it | the same pages and atlas |
-| `ingest` | reads it straight through | writes `"width": null, "height": null`; `--stage` adds one |
+| `ingest` | reads the header's box into the rebuild's stage — an export carries no other box, so its bounding box becomes the rebuild's stage, and the rebuild's header is computed again | writes `"width": null, "height": null`; `--stage` adds one |
 
 ⚠️ A stage-less skeleton is **unmeasured, not certified**: `A14_NO_FULL_FRAME_MESH`
 reports **SKIP** on one, because there is no full frame for a mesh to span. And
-`rigc diff` reports it — `skeleton.stage_present` and `skeleton.stage_box`, in the
-header block at the top of the report — so a stage somebody invented reads
-below 1.000 against a source that has none.
+`rigc diff` reports the header's box — `skeleton.bounds_present` and
+`skeleton.bounds_box`, in the header block at the top of the report — so a build that
+carries a box reads below 1.000 against a source that carries none.
 
-⭐ **A stage at `0,0` is not a stage-less one, and an editor export spells it by
+⭐ **A box at `0,0` is not a box-less header, and an editor export spells it by
 saying nothing.** The editor omits a header field that is at its default, so a
 skeleton whose box sits at the origin exports as a `width` and a `height` with no
-`x`/`y`; `stage_box` reads that omission as the `0` it means, and its line says so
-— *the extent as stated, an omitted origin as the 0 it means*. So `4/4` on a build
-of yours against an export of that same build is the right answer rather than a
-tolerance, and an origin that really did move still reads below 1.000. The extent
-is the half that is read exactly as stated: omit a `width` and you have declared no
-stage, which `stage_present` is the measure of. Both are reported and gate nothing, for
+`x`/`y`; `bounds_box` reads that omission as the `0` it means, and its line says so
+— *the extent as stated, an omitted origin as the 0 it means*. The box is compared
+exactly: rigc's is `getBounds` on the header's 1e-6 grid at float32, the editor's is its own arithmetic, which
+on the twelve example exports sits up to 0.0071 units from `getBounds` over the same
+file — so a rebuild of an export reads below 4/4 here by the editor's arithmetic
+alone, and that is a finding about two writers rather than a moved rig. The extent
+is the half that is read exactly as stated: omit a `width` and the header carries no
+box, which `bounds_present` is the measure of. Both are reported and gate nothing, for
 the reason every reported measure is: no reading of the rendered frames could have
 decided a setup-pose bounding box. The measure inventory that says so lives in
 [BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md), which

package/docs/INGEST.md

@@ -217,7 +217,8 @@ Spine runtime plays it, whatever rigc's own rasteriser or validator thinks.
 
 `diff` takes two compiled skeletons and reports 54 measures in eight groups, plus two
 blocks that report and gate nothing: the `(reported)` measures beside `attachments`
-and `animations`, and the `skeleton` header block at the top, which measures the stage.
+and `animations`, and the `skeleton` header block at the top, which measures the header's setup-pose
+bounding box.
 A ninth group of six joins them when something has paired the two sides'
 animations — `--as <candidate>=<reference>`, or one animation each side, which pairs by
 position (§1.3.1). Both sides may be foreign; the interesting pairing during ingest is
@@ -234,9 +235,9 @@ rigc diff
   reference  …/examples/3-timing-and-spacing/export/3-timing-and-spacing-ess.json
   ..         bones=3/3  slots=2/2  skins=1/1  attachments=2/2  constraints=0/0  animations=2/2  events=0/0   (candidate/reference)
 
-  skeleton (reported)   (no mean)   over 2 measures  — the stage, which no reading of the frames could decide
-      1.000  stage_present                1/1         both sides declare a setup-pose stage, or neither does  — …
-      1.000  stage_box                    4/4         the stage is the same box (x, y, width, height — the extent as stated, an omitted origin as the 0 it means)  — …
+  skeleton (reported)   (no mean)   over 2 measures  — the header's setup-pose bounding box, which no reading of the frames could decide
+      1.000  bounds_present               1/1         both headers carry a setup-pose bounding box, or neither does  — …
+      0.250  bounds_box                   1/4         the header carries the same box (x, y, width, height — the extent as stated, an omitted origin as the 0 it means)  — …
 
   bones                 mean 1.000  over 8 measures
       1.000  count                        3/3         how many bones
@@ -277,20 +278,21 @@ both files through `spine-core`, and a skeleton whose attachments carry a `seque
 cannot be parsed without the atlas that resolves it — so the measure takes two
 skeletons **and two packs**, which `rigc diff <a.json> <b.json>` does not have.
 
-⚠️ **The one exception is the skeleton's own declared box**, and it is an exception to
-the sentence and not to the rule: `skeleton.stage_box` compares four world numbers,
-but they are numbers an exporter *declared in the header* rather than a pose anything
-measured, and the block they sit in gates nothing. Moving a pivot does not move them
-either.
+⚠️ **The one exception is the header's own box**, and it is an exception to the
+sentence and not to the rule: `skeleton.bounds_box` compares four world numbers — the
+setup-pose bounding box each writer put in its header (rigc's is spine-core's
+`getBounds` on the header's 1e-6 grid at float32 since issue #907; the editor's is its own arithmetic, up to
+0.0071 units from `getBounds` on the twelve examples) — exactly, and the block they
+sit in gates nothing. The measure was called `stage_box` until #907, when `build`
+stopped writing the stage there.
 
 ⭐ **Declared is not the same as written down, and for the origin it is the
-difference between a green round trip and a false finding.** The editor omits a header
-field at its default, so a stage sitting at `0,0` exports as a `width` and a
-`height` and no `x`/`y` at all — there is no other spelling for it. The measure
-reads that omission as the `0` it means, so a rigc build whose stage is at the
-origin and the editor's export of that build read `stage_box` **4/4**. The extent is still read
-exactly as stated: it is what decides whether there is a stage at all, so a missing
-`width` is an absent stage rather than a stage of width zero.
+difference between a true reading and a false finding.** The editor omits a header
+field at its default, so a box sitting at `0,0` exports as a `width` and a `height`
+and no `x`/`y` at all — there is no other spelling for it. The measure reads that
+omission as the `0` it means. The extent is still read exactly as stated: it is what
+decides whether there is a box at all, so a missing `width` is an absent box rather
+than a box of width zero.
 
 ⛔ **And its ratios are not a score.** [`src/diff.ts`](../src/diff.ts) says so in the
 type itself (*"Unweighted mean of the measures below. NOT a quality score"*), and the
@@ -509,12 +511,17 @@ at the policy rather than implying the file was read.
   is the file that was read, byte for byte. No finding is recorded, because nothing
   was lost and nobody decided anything. `--stage x,y,w,h` is how a caller *adds* a box
   to such a file, and that is a `NO_STAGE` **judgement**. All twelve exports in the
-  fetched corpus carry a stage, and `ingest` reads it straight through. The box cannot be
-  *derived* — posing the rig gives the *animated* extent, which is a different number
-  from the setup box. 🔸 **Half a stage is a `NO_STAGE` blocker**: an origin with no
+  fetched corpus carry a box, and `ingest` reads it straight through into the rebuild's
+  stage. A **rigc build**'s stage is read instead from the `skeleton.model.json` beside it,
+  when that document's `spine.sha256` is the skeleton's digest — its header is the setup-pose
+  bounding box — and an export's from its header box. 🔁 What an export's header carries is its setup-pose bounding box; it is the
+  only box the file has, so it becomes the rebuild's stage, and the rebuild's own header
+  is computed again — `build` writes the setup-pose bounding box there, never the stage
+  (issue #907). The stage cannot be *derived*: it is the working area the art was
+  painted in, and no pose of the rig states it. 🔸 **Half a stage is a `NO_STAGE` blocker**: an origin with no
   extent, or one extent without the other, declares no stage and is not the absence
   either, and the rig spec holds a stage as four fields or none. It is also the value that costs least to get wrong: `diff`
-  reports it as two measures of its own (`stage_present`, `stage_box`) and they are
+  reports the header's box as two measures of its own (`bounds_present`, `bounds_box`) and they are
   `(reported)`, so no score reads them and an absurd box is green nearly everywhere.
   ⛔ **The flag is refused beside a box the file states** — two sources for one value,
   both named, and the file is the record of what was measured;
@@ -659,8 +666,9 @@ states.
    ⚠️ **If the export's `skeleton` block carries no `x`/`y`/`width`/`height`, write
    `"width": null, "height": null` and do not invent one** — which is also what
    `rigc ingest` writes for such a file. A made-up stage is a number no gate refuses;
-   `diff`'s header block reports `skeleton.stage_present` and `skeleton.stage_box`
-   against the source you are copying. Copy the four numbers when they are there;
+   `A14` and `A19` measure against the stage you state, and `diff`'s header block
+   reports `skeleton.bounds_present` and `skeleton.bounds_box` — your build's bounding
+   box, which you do not author, against the source's. Copy the four numbers when they are there;
    state the absence when they are not.
 4. **`explain`, then `build`.** `explain` first, because it prints what you wrote in a
    shape you can compare against the export by eye (§1.5) and it never gates. Then
@@ -704,11 +712,11 @@ State the ambition in the right units, because three different things get called
 | --- | --- | --- |
 | **Structural agreement** — same bones, slots, attachments, timelines, key counts, curve kinds | ✅ yes, and `diff` measures it | the 3-timing transcription reads **1.000 on all 54 measures**. Aim here first |
 | **Geometric agreement** — the same drawn pixels, allowing for the atlas | ✅ yes, and `check` measures it | see below |
-| **Byte-identical JSON** | ✅ **for a rebuild, in canonical form, apart from `hash` and `spine`** — the pass line below | a **rebuild** of an editor export (`ingest`, then `build`) is the export. A **transcription** by hand is not held to it: what differs there is what a person chose to write, not the emitter |
+| **Byte-identical JSON** | ✅ **for a rebuild, in canonical form, apart from `hash`, `spine` and the header's box** — the pass line below | a **rebuild** of an editor export (`ingest`, then `build`) is the export. A **transcription** by hand is not held to it: what differs there is what a person chose to write, not the emitter |
 
 ⭐ **The pass line of the byte round trip, stated once:** `build(ingest(x))` of an
 editor export `x` is **identical to `x` in canonical form, apart from `hash` and
-`spine`** — canonical form being `JSON.stringify(JSON.parse(text), null, 2)` of each
+`spine`**, and from the header's box (below) — canonical form being `JSON.stringify(JSON.parse(text), null, 2)` of each
 file, which keeps every number as parsed, every key in its order and every omitted key
 omitted, and drops only whitespace and the exponent's spelling (an export setting, not
 a property of the rig). It holds on all twelve exports under `examples/`; for a
@@ -722,11 +730,22 @@ has no field for, by design, and each has its finding:
 | `hash` | `undefined` vs `"VFWbaK2UoCM"` | the editor's project hash — a value about a file rigc did not write, so a spec that carried it would be claiming an export it did not come from. `HEADER_BOOKKEEPING` |
 | `spine` | `"4.3.13"` vs `"4.3.75-beta"` | the version of the runtime rigc links, stamped by design and re-checked by `A16`. `HEADER_REDERIVED` |
 
+🔁 **The header's box is the third difference, and it is not a key the spec lacks** (issue
+#907). The rig spec carries the export's `x`, `y`, `width`, `height` — as the rebuild's
+stage — and the rebuild does not copy them back: its header carries the setup-pose bounding
+box `build` computes, which is spine-core's `getBounds` over the export on the header's grid
+(the rebuild draws the export's vertices to the bit, so its box is the export's box), where
+the editor wrote its own arithmetic, at most 0.0071 units away on the twelve —
+`spineboy-pro`'s rebuild writes `-188.63641, -7.936074, 418.453, 686.19934` against the
+editor's `-188.6338, -7.939564, 418.4499, 686.2023`. The suite holds each rebuild's box to
+`getBounds` of its source at tolerance 0 (`IG97`) and reads every other byte against a copy
+of the export carrying that box.
+
 🔢 **The rest of the header, and every omitted default, comes back as the export
 spells it.** The **header's `audio`** is a stated value like `images`, and the rig
 spec carries it ([AUTHORING §3.1](AUTHORING.md)). The emitter leaves out exactly the
 keys the parser reads the same way without them ([AUTHORING §10.6c](AUTHORING.md)).
-One shape is left and it is deliberate: a stage at the origin, which the editor writes as
+One shape is left and it is deliberate: a box at the origin, which the editor writes as
 `width`/`height` with no `x`/`y` and rigc spells whole. The 4.3 JSON reader has no
 default for the origin — an absent one loads as `undefined`, a written `0` as `0` — so
 it is not a key the parser reads the same way without it, and the row is not in the

package/package.json

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

package/src/assertions/emitted/index.ts

@@ -26,7 +26,7 @@ import { ASSERTION_KIND, type AssertionProfile } from '../kinds.ts';
 import { verdictHarness, type VerdictLists } from '../harness.ts';
 import { MOVED_ASSERTIONS } from '../model/index.ts';
 import type { Verdicts } from '../harness.ts';
-import type { Json } from '../values.ts';
+import { isObj, type Json } from '../values.ts';
 import { a01NoLegacyToplevelConstraintArrays } from '../bodies/a01.ts';
 import { a02NoBoneTransformKey } from '../bodies/a02.ts';
 import { a05CurveArrayLength } from '../bodies/a05.ts';
@@ -35,6 +35,7 @@ import { a16SkeletonVersion43 } from '../bodies/a16.ts';
 import { a18DeterministicEmit } from '../bodies/a18.ts';
 import { a31DrawOrderOffsetsResolve } from '../bodies/a31.ts';
 import { a35DeformKeysFitTheAttachment } from '../bodies/a35.ts';
+import { parseAtlasText } from '../../atlas.ts';
 
 /** What the restated rules read: the emitted texts, the document written beside them, and a second compile's three. */
 export interface EmittedTextInput {
@@ -92,6 +93,31 @@ export const EMITTED_TEXT_RULES: ReadonlyArray<{ code: string; run: (v: Verdicts
   },
 ];
 
+/**
+ * The figures `validate()` reads off the pair it loaded, read off the same two
+ * texts here (issue #1114), into `stats` first — the order the round trip's
+ * report holds them in: `pages` and `regions` from the atlas text by rigc's own
+ * reader (`parseAtlasText`, whose pages and regions are the runtime atlas's in
+ * file order), then `bones`, `slots`, `animations` and `version` from the
+ * skeleton JSON — the arrays and the animation map the runtime loads them
+ * from, and `skeleton.spine` as it states it, `(none)` where it states none.
+ * The skeleton's four are left out where its JSON does not parse, as the round
+ * trip leaves them out where it loaded nothing; nothing here is a value the
+ * texts do not state.
+ */
+function pairFigures(stats: Record<string, number | string>, raw: Json | null, atlasText: string): void {
+  const atlas = parseAtlasText(atlasText);
+  stats.pages = atlas.pages.length;
+  stats.regions = atlas.regions.length;
+  if (!isObj(raw)) return;
+  const listed = (v: unknown): number => (Array.isArray(v) ? v.length : 0);
+  stats.bones = listed(raw.bones);
+  stats.slots = listed(raw.slots);
+  stats.animations = isObj(raw.animations) ? Object.keys(raw.animations).length : 0;
+  const declared = isObj(raw.skeleton) ? raw.skeleton.spine : undefined;
+  stats.version = declared === undefined || declared === null ? '(none)' : typeof declared === 'string' ? declared : JSON.stringify(declared);
+}
+
 /** Every code the model side does not run, read off the registry — what this file must account for. */
 export function roundTripOnlyCodes(): string[] {
   const moved = new Set(MOVED_ASSERTIONS.map((m) => m.code));
@@ -112,6 +138,7 @@ export function validateEmittedText(input: EmittedTextInput): VerdictLists & { p
   } catch (err) {
     h.fail(A00, `skeleton JSON is not parseable: ${(err as Error).message}`);
   }
+  pairFigures(h.stats, raw, input.atlasText);
   for (const rule of EMITTED_TEXT_RULES) {
     if (rule.code === A00 && raw === null) continue;
     h.check(rule.code, () => rule.run(h.verdicts, { raw, input }));

package/src/assertions/facts/stage.ts

@@ -11,9 +11,12 @@
  * rather than a number standing in for it, and each body reads it as it always
  * did.
  *
- * Not in the model document: the stage is the emitter's header
- * (`SkeletonHeader.stage`), and it enters the document with issue #1026. Until
- * then the model side is given it by its caller (`../model/stage.ts`).
+ * A `rigc-compiled/3` document states it (`stage`, issue #1026), and since
+ * issue #907 that is the only place a rigc build states it: the Spine header
+ * carries the setup-pose bounding box. So both suppliers read a rigc build's
+ * stage off its document (`spineStage` in `../../validate.ts`,
+ * `../model/stage.ts`); an export, which has no document, is read off its
+ * header.
  * Links nothing from the runtime.
  */
 

package/src/assertions/model/index.ts

@@ -45,7 +45,7 @@ import { a11NoClippingAttachments } from '../bodies/a11.ts';
 import { a17AtlasPageFilesExist } from '../bodies/a17.ts';
 import { a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten } from '../bodies/a45.ts';
 import { A00_MODEL_READ, A00_MODEL_REGIONS_ON_PAGES, MODEL_PARSE_KIND, modelRead, modelRegionsOnPages, SKIP_NO_MODEL_DOCUMENT, SKIP_NO_MODEL_PAGES, type ReadDocument } from './parse.ts';
-import { modelSkinEntries } from './skin_entries.ts';
+import { fileOrderedEntries, modelSkinEntries } from './skin_entries.ts';
 import { modelAtlasPages } from './atlas_pages.ts';
 import { modelSlotColour } from './slot_colour.ts';
 import type { SkinEntryFacts } from '../facts/skin_entries.ts';
@@ -332,6 +332,44 @@ function parse(h: VerdictHarness, modelText: string): { read: ReadDocument | nul
   return { read, held: h.check(A00_MODEL_REGIONS_ON_PAGES, () => modelRegionsOnPages(h.verdicts, read)) === true };
 }
 
+/**
+ * The row the rig's two figures are written before (issue #1114): `validate()`
+ * sets `rig` and `profile` where its archetype assertions begin, after every
+ * figure the bodies above them write and before A29's and A30's, so the figures
+ * line lists them in that place on both entries. `RC39` in `selftest.ts`
+ * compares the two lines key by key.
+ */
+const RIG_FIGURES_BEFORE = 'A24_AXIS_SPACE_STROKE';
+if (!MOVED_ASSERTIONS.some((m) => m.code === RIG_FIGURES_BEFORE)) throw new Error(`internal: the model side writes the rig's figures before ${RIG_FIGURES_BEFORE}, which it no longer runs`);
+
+/**
+ * The attachment figures `validate()` counts over the skins it loaded (issue
+ * #1114), counted over the document's skins in the file's walk order: a
+ * `region` record is a region attachment, and a `mesh` or `linkedmesh` record
+ * a mesh attachment — the runtime loads a linked mesh as a mesh. Written only
+ * where the document read and its regions held, as the round trip writes them
+ * only where it loaded the skeleton, and before any body's figure, which is
+ * where `validate()` writes them.
+ */
+function attachmentFigures(stats: Record<string, number | string>, read: ReadDocument): void {
+  const kinds = fileOrderedEntries(read).map((entry) => entry.record.kind);
+  stats.regionAttachments = kinds.filter((kind) => kind === 'region').length;
+  stats.meshAttachments = kinds.filter((kind) => kind === 'mesh' || kind === 'linkedmesh').length;
+}
+
+/**
+ * `rig` — the archetype the document's rig section states (`validate()` prints
+ * its caller's; the model side reads the document's, issue #1054 — read
+ * directly rather than through `supply.rigInfo`, whose refusal of a caller's
+ * `rig` beside the document is the rules' line to print, not this figure's),
+ * left out where there is no document to state one — and `profile`, the profile this
+ * run was handed: the same argument both entries read off `--profile`.
+ */
+function rigFigures(stats: Record<string, number | string>, read: ReadDocument | null, input: ModelValidateInput): void {
+  if (read !== null) stats.rig = modelRigInfo(read).archetype;
+  stats.profile = input.profile;
+}
+
 /**
  * Run the model side: the parse, then every moved assertion — each over the
  * document, or skipped naming the parse when there is none — and return the
@@ -343,7 +381,9 @@ export function validateModel(input: ModelValidateInput, plant: Partial<ModelSup
   const supply: ModelSupply = { ...MODEL_SUPPLY, ...plant };
   const h = verdictHarness(input.profile, { ...ASSERTION_KIND, ...MODEL_PARSE_KIND }, 'the model side');
   const { read, held } = parse(h, input.modelText);
+  if (read !== null && held) attachmentFigures(h.stats, read);
   for (const moved of MOVED_ASSERTIONS) {
+    if (moved.code === RIG_FIGURES_BEFORE) rigFigures(h.stats, read, input);
     const doc = read !== null && (held || moved.beforeTheParse === true) ? read : null;
     h.check(moved.code, () => (doc === null ? h.skip(moved.code, moved.unread) : moved.run(h.verdicts, doc, input, supply)));
   }

package/src/cli/core_commands.ts

@@ -28,13 +28,13 @@ import { deformReportBlock } from '../deformreport.ts';
 import { type DiffAnimationPair, diffLines, diffSkeletons } from '../diff.ts';
 import { ingest, INGEST_GUTTERS, type IngestFinding, IngestSpecRefused, type IngestStage } from '../ingest.ts';
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
-import { modelDocument } from '../model.ts';
+import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.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 { 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 } from './shared.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 { 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';
 
@@ -889,11 +889,9 @@ export function cmdExplain(flags: Record<string, string>): void {
   // A rig may state that it has no stage at all (issue #578), and the two must
   // not print alike: `undefined x undefined` is what a template does with an
   // absence, and it reads like a defect in the tool rather than a claim in the
-  // spec.
-  const stage =
-    result.skeleton.skeleton.width === undefined || result.skeleton.skeleton.height === undefined
-      ? 'none declared'
-      : `${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}`;
+  // spec. The stage is the model's (issue #907): the header's box is the
+  // setup-pose bounding box, which is not the stage and is not printed as it.
+  const stage = result.model.stage === null ? 'none declared' : `${result.model.stage.width} x ${result.model.stage.height}`;
   console.log(`\nstage  ${stage}  (spine ${result.skeleton.skeleton.spine})`);
 
   // The crop note describes where the numbers CAME from, and without a manifest
@@ -1295,9 +1293,16 @@ export function cmdIngest(flags: Record<string, string>, positional: string[]):
    * with them — `JSON.stringify` — and a cast to `RigSpec` here would be this
    * file claiming a parse that did not happen.
    */
+  // A rigc build's stage is the model document's beside it, when that document is this skeleton's (issue #907): its header is the
+  // setup-pose bounding box. An export, or a skeleton with no such document, is read off its header.
+  const documentStage = documentStageBeside(skeletonPath, readFileSync(skeletonPath, 'utf8'));
+  if (documentStage !== undefined) {
+    console.log(`  ..    stage  ${documentStage === null ? 'none declared' : `${documentStage.width} x ${documentStage.height}`} — read from the ${MODEL_DOCUMENT_FILE} beside it (its spine.sha256 is this skeleton's); the header's box is the setup-pose bounding box`);
+  }
   let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
   try {
     result = ingest(readJsonFile(skeletonPath), {
+      ...(documentStage === undefined ? {} : { documentStage }),
       name: flags.name ?? basename(skeletonPath, '.json'),
       art,
       images: specImages,
@@ -1559,7 +1564,9 @@ const MODEL_AND_TEXT_GATE: BuildGate = {
       passed: [...model.passed, ...text.passed],
       skipped: [...model.skipped, ...text.skipped],
       profileSkipped: [...model.profileSkipped, ...text.profileSkipped],
-      stats: { ...model.stats, ...text.stats },
+      // The emitted text's figures first: they are the pair's (`pages` … `version`), which `validate()` writes
+      // before any other, and the model side's follow in its order — one line, keyed and ordered as `cli.ts build`'s (issue #1114, `RC39`).
+      stats: { ...text.stats, ...model.stats },
       profile,
     };
     for (const line of reportLines(report)) console.log(line);