spine-rigc 2.1.2 → 2.2.0

package/src/diff.ts

@@ -1702,64 +1702,66 @@ function diffEvents(c: Json, r: Json): DiffSection {
 // ---------------------------------------------------------------------------
 
 /**
- * The stage: `x`, `y`, `width`, `height` of the setup-pose bounding box, or the
- * absence of all four.
+ * The header's box: `x`, `y`, `width`, `height` of the setup-pose bounding box
+ * — the box around the attachments at the setup pose, which is what the Spine
+ * format says the four are — or the absence of all four.
  *
- * 🔍 **Why this measure exists at all** (issue #578). The stage was the one value
- * `build` required and no instrument in this tree could see: `validate`, `check`
- * and `render` all ignore it — `render` frames from the posed bounds — and `diff`
- * had no header measure, so a sweep that handed a deliberately absurd unit stage
- * `0,0,1,1` to 37 real exports read **1.000 on every measure** for 32 of them. A
- * required-and-unmeasured field is the worst combination a field can have: the
- * only way to satisfy it was to invent a number, and nothing would ever say so.
+ * 🔁 **Renamed from `stage_present`/`stage_box` by issue #907, because the old
+ * name had become a lie.** Until then `build` copied rigc's stage — the crop
+ * the art was painted in — into these four fields, so on a rigc candidate the
+ * measure read a stage and on an editor export it read a bounding box, under
+ * one word. Since #907 `build` writes the setup-pose bounding box there too
+ * (`headerBoundsOf` in `src/compile.ts`, held to spine-core's `getBounds`), so
+ * both sides of every comparison carry the same kind of value, and the stage —
+ * which a rig spec states and the model document carries — is not in the file
+ * at all. A measure called `stage` would send a reader to change the stage,
+ * which no longer moves this number.
  *
- * ⭐ **`stage_present` is 1/1 or 0/1 and never `0/0`.** Both sides always have a
- * presence to compare, including when both say "none" — that is agreement, not
- * an absence of data, and `total: 0` here would be the vacuous 1.000 this file
- * refuses. `stage_box` is the one that goes vacuous, and only when there are not
- * two boxes to compare.
+ * 🔍 **Why this measure exists at all** (issue #578). The header box was the
+ * one value `build` required and no instrument in this tree could see:
+ * `validate`, `check` and `render` all ignore it — `render` frames from the
+ * posed bounds — and `diff` had no header measure, so a sweep that handed a
+ * deliberately absurd unit stage `0,0,1,1` to 37 real exports read **1.000 on
+ * every measure** for 32 of them.
+ *
+ * ⭐ **`bounds_present` is 1/1 or 0/1 and never `0/0`.** Both sides always have
+ * a presence to compare, including when both say "none" — that is agreement,
+ * not an absence of data, and `total: 0` here would be the vacuous 1.000 this
+ * file refuses. `bounds_box` is the one that goes vacuous, and only when there
+ * are not two boxes to compare.
  */
-interface StageFacts {
+interface HeaderBox {
   present: boolean;
   /**
    * The four fields as the header MEANS them: the extent exactly as stated, and
-   * the origin of a declared stage as stated or `0` where it is omitted. See
-   * `stageFacts` for why the second half is a reading and not a fallback.
+   * the origin of a stated box as stated or `0` where it is omitted. See
+   * `headerBox` for why the second half is a reading and not a fallback.
    */
   box: Array<number | null>;
 }
 
-const STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
+const BOX_FIELDS = ['x', 'y', 'width', 'height'] as const;
 
 /**
- * A stage is declared by its EXTENT: a numeric `width` and `height`.
+ * A header states a box by its EXTENT: a numeric `width` and `height`.
  *
  * `x`/`y` alone are an origin for a box that is not there — no export carries
- * that shape, and rigc refuses to emit it — so they do not make a stage on their
- * own. It is also what the compiler requires and what `A14_NO_FULL_FRAME_MESH`
- * and `A19_OVERLAY_PNGS_HAVE_ALPHA` measure against, so the three agree on the
- * word by construction rather than by memory.
+ * that shape, and rigc never emits it — so they do not make a box on their own.
  *
- * ⭐ **Inside a declared stage, an omitted `x`/`y` IS `0`** (issue #620). That is
- * a reading of the format, not a value invented for a gap — the distinction this
- * file lives or dies by — and four measurements carry it, none of them anybody's
- * word for the convention:
+ * ⭐ **Inside a stated box, an omitted `x`/`y` IS `0`** (issue #620). That is a
+ * reading of the format, not a value invented for a gap — the distinction this
+ * file lives or dies by — and three measurements carry it, none of them
+ * anybody's word for the convention:
  *
- * - **This tree had already decided it, one file over.** `compile.ts` assembles
- *   the header as `header.x = rig.skeleton?.x ?? 0`, under the same guard: only
- *   when the extent is there. So a rig spec that omits its origin emits `0`, and
- *   reading the same omission in a file as absence made the compiler and the
- *   comparison disagree about one value in one header. This measure is not
- *   adopting the editor's convention so much as stopping contradicting the
- *   emitter it is pointed at.
  * - **The header's writer omits a field at its default.** All twelve exports
  *   under `examples/` omit `referenceScale`, whose default the parser itself
  *   spells two lines below the four raw assignments (`SkeletonJson.js:74`,
  *   `getValue(skeletonMap, "referenceScale", 100)`), and none of the 389 bone
  *   `x`/`y`/`rotation`/`shearX`/`shearY` values those same files DO write is an
- *   explicit `0`. A stage at the origin therefore has no spelling but the
+ *   explicit `0`. A box at the origin therefore has no spelling but the
  *   omission, so reading the omission as absence reads a value the format cannot
- *   express.
+ *   express. (An editor round trip of a header stating `"x": 0, "y": 0` wrote
+ *   neither back — measured through a licensed 4.3.26 editor for issue #907.)
  * - **The binary reader supplies it unconditionally.** `SkeletonBinary.js:69-72`
  *   reads the four as four floats with no key to be missing, so one skeleton's
  *   origin is `0` in a `.skel` and absent in a `.json`. A measure that called
@@ -1772,13 +1774,13 @@ const STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
  *   editor has never exported a frame rate.
  *
  * ⚠️ **The default is the ORIGIN's alone**, and the guard is the paragraph above
- * it: the extent is what declares a stage, so defaulting it would turn the
- * stage-less header of issue #578 into a `0x0` stage at `0,0` and answer the
- * question instead of reading it.
+ * it: the extent is what states a box, so defaulting it would turn the box-less
+ * header of issue #578 into a `0x0` box at `0,0` and answer the question
+ * instead of reading it.
  */
-function stageFacts(root: Json): StageFacts {
+function headerBox(root: Json): HeaderBox {
   const header = isObj(root.skeleton) ? root.skeleton : {};
-  const box = STAGE_FIELDS.map((k) => num(header[k]));
+  const box = BOX_FIELDS.map((k) => num(header[k]));
   const present = box[2] !== null && box[3] !== null;
   return { present, box: present ? [box[0] ?? 0, box[1] ?? 0, box[2], box[3]] : box };
 }
@@ -1787,47 +1789,51 @@ function stageFacts(root: Json): StageFacts {
  * The two header measures.
  *
  * ⚠️ **The box is compared EXACTLY, and that is a measurement rather than a
- * choice.** The brief this was built from asked for "the tolerance the other
- * measures use"; the structural measures in this file have exactly one —
+ * choice.** The structural measures in this file have exactly one tolerance —
  * `FRAME`, one sixtieth of a second, used once, for `animations.duration` — and
  * no spatial one anywhere, because they compare no position at all (that is
- * `bonedist.ts`). A stage is a box an exporter *wrote down*, not a pose anybody
- * measured, so there is nothing for it to be within a tolerance *of*; inventing
- * a spatial epsilon here would be a number nobody measured, in the file whose
- * whole job is to report measured ones.
+ * `bonedist.ts`). Each side's box is a number its writer computed: rigc's is
+ * spine-core's `getBounds` on the header's 1e-6 grid at float32 (`headerBoxNumber`; `tools/core_gate.ts` holds it), and
+ * the editor's is its own arithmetic, which on the twelve examples sits up to
+ * 0.0071 units from `getBounds` on the same skeleton and agrees with its
+ * float32 on 13 of the 48 numbers (issue #907's measurement). A rebuild and its
+ * export therefore read below 4/4 here by the editor's arithmetic alone, and an
+ * epsilon chosen to hide that would be a number nobody measured, in the file
+ * whose whole job is to report measured ones. The measure is reported and gates
+ * nothing on the ladder.
  *
  * ⭐ `diffSkeletonValues` (issue #615) is the second tolerance in the file and
  * it does not weaken this one. It compares positions, so it needs one; both its
  * terms are read off other code — the 1e-6 grid rigc's closed-form models are
- * evaluated on and the parser's float32 storage — rather than chosen here; and the four numbers above are the
- * one place the two overlap, where `stage_box` stays the stricter reading and
- * says so by staying exact.
+ * evaluated on and the parser's float32 storage — rather than chosen here; and
+ * the four numbers above are the one place the two overlap, where `bounds_box`
+ * stays the stricter reading and says so by staying exact.
  */
 function diffHeader(c: Json, r: Json): DiffReported {
-  const a = stageFacts(c);
-  const b = stageFacts(r);
+  const a = headerBox(c);
+  const b = headerBox(r);
   const both = a.present && b.present;
   const agreed = both ? a.box.filter((v, i) => v === b.box[i]).length : 0;
-  const side = (f: StageFacts): string => (f.present ? `${f.box[2]}x${f.box[3]} at ${f.box[0]},${f.box[1]}` : 'none');
+  const side = (f: HeaderBox): string => (f.present ? `${f.box[2]}x${f.box[3]} at ${f.box[0]},${f.box[1]}` : 'none');
   return {
     measures: [
       measure(
-        'skeleton.stage_present',
-        'both sides declare a setup-pose stage, or neither does',
+        'skeleton.bounds_present',
+        'both headers carry a setup-pose bounding box, or neither does',
         a.present === b.present ? 1 : 0,
         1,
-        `candidate ${side(a)}; reference ${side(b)}. A skeleton declares a stage by stating a width and a height`,
+        `candidate ${side(a)}; reference ${side(b)}. A header carries a box by stating a width and a height`,
       ),
       measure(
-        'skeleton.stage_box',
-        'the stage is the same box (x, y, width, height — the extent as stated, an omitted origin as the 0 it means)',
+        'skeleton.bounds_box',
+        'the header carries the same box (x, y, width, height — the extent as stated, an omitted origin as the 0 it means)',
         agreed,
-        both ? STAGE_FIELDS.length : 0,
+        both ? BOX_FIELDS.length : 0,
         both
           ? `candidate ${side(a)}; reference ${side(b)}`
           : a.present === b.present
-            ? 'neither side declares a stage, so there is no box to compare — `stage_present` carries that'
-            : 'only one side declares a stage, so there is no second box to compare — `stage_present` carries that',
+            ? 'neither header carries a box, so there is no box to compare — `bounds_present` carries that'
+            : 'only one header carries a box, so there is no second box to compare — `bounds_present` carries that',
       ),
     ],
   };
@@ -1971,7 +1977,7 @@ function valuesAgree(a: number | string, b: number | string): boolean {
  * distinction `DiffMeasure.total` draws everywhere else in this file.
  */
 const VALUE_MEASURES: ReadonlyArray<{ id: string; what: string; prefix: string }> = [
-  { id: 'values.skeleton', what: 'the header and the setup-pose stage', prefix: 'skeleton/' },
+  { id: 'values.skeleton', what: 'the header and its setup-pose bounding box', prefix: 'skeleton/' },
   { id: 'values.bones', what: 'every bone setup pose, its length and its colour', prefix: 'bones/' },
   { id: 'values.slots', what: 'every slot colour, dark colour, blend mode and setup attachment', prefix: 'slots/' },
   { id: 'values.attachments', what: 'every attachment offset, size, vertex, weight, uv and triangle', prefix: 'skins/' },
@@ -2170,7 +2176,7 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   // with `(no mean)` for the same reason a section's `(reported)` block has one.
   lines.push(
     `  ${'skeleton (reported)'.padEnd(21)} (no mean)   over ${report.header.measures.length} measures` +
-      '  — the stage, which no reading of the frames could decide',
+      '  — the header\'s setup-pose bounding box, which no reading of the frames could decide',
   );
   lines.push(...measureLines(report.header.measures, 'skeleton.'.length));
   lines.push('');
@@ -2232,10 +2238,10 @@ export function diffLines(report: DiffReport, labels: { candidate: string; refer
   lines.push('  the block is absent rather than guessed — and its absence beside `names` 0.000');
   lines.push('  is the report saying the candidate named its shots itself and nothing said how.');
   lines.push('');
-  lines.push('  `skeleton` is the file\'s own header block and reports two measures for the stage.');
+  lines.push('  `skeleton` is the file\'s own header block and reports two measures for its box.');
   lines.push('  It has no mean for the reason a `(reported)` block never does, and it never');
   lines.push('  gates for two: no reading of the frames recovers a setup-pose bounding box, and');
-  lines.push('  the ladder\'s briefs withhold the stage size outright.');
+  lines.push('  each side\'s box is its writer\'s own arithmetic.');
   lines.push('');
   lines.push('  A `(reported)` block has no mean because its measures have unlike units, and');
   lines.push('  it stays out of the section mean above it for the same reason no clause may');

package/src/emit_spine.ts

@@ -755,19 +755,33 @@ export function emitAnimations(
  *     stated, `images` spelled relative to `--out` (`skeletonImagesPath`);
  *     each only when present.
  *
+ *   - `bounds` — the setup-pose bounding box, `x`, `y`, `width`, `height`,
+ *     which is what the format says the header's four are (issue #907):
+ *     computed by `compile` with rigc's core over the model
+ *     (`headerBoundsOf`), each on the 1e-6 grid at float32 (`headerBoxNumber`), or `null` for no box — a rig that
+ *     declares no stage (issue #578), a setup pose that draws nothing, a
+ *     region with no atlas rectangle, or a setup pose the core leaves out
+ *     (that function's header). Four fields or none.
+ *
  * `referenceScale` is not here: wind and gravity act over it, so a posing
  * core reads it, and the model holds it (`CompiledModel.referenceScale`,
  * issue #958). The emitter writes the model's value into the header, where
- * `withoutParserDefaults` drops it at the parser's 100. Nor is the stage —
- * the setup-pose box, four fields or none (issue #578) — since issue #1026:
- * `render` and `check` read whether one is declared, and the model holds it
- * (`CompiledModel.stage`), so the emitter writes the model's.
+ * `withoutParserDefaults` drops it at the parser's 100.
+ *
+ * ⚠️ Nor is the stage (`CompiledModel.stage`, issue #1026) — and since issue
+ * #907 the header does not carry it at all. Until then the emitter copied the
+ * stage into the four box fields, so a reader that took the header for what
+ * the format says it is — the box around the figure at rest, for scaling and
+ * layout — got the crop the art was painted in. The stage stays the model's:
+ * the document states it, and everything that measures against it reads it
+ * there.
  */
 export interface SkeletonHeader {
   spine: string;
   fps?: number;
   images?: string;
   audio?: string | null;
+  bounds: { x: number; y: number; width: number; height: number } | null;
 }
 
 /** The editor's orders the emitter applies, passed for the reason the header's 🔸 gives. */
@@ -776,7 +790,7 @@ export interface SkeletonOrder extends EditorOrder {
 }
 
 /** The model fields a skeleton is written from. */
-export type SkeletonSource = Pick<CompiledModel, 'referenceScale' | 'stage' | 'bones' | 'slots' | 'skins' | 'constraints' | 'events' | 'animations'>;
+export type SkeletonSource = Pick<CompiledModel, 'referenceScale' | 'bones' | 'slots' | 'skins' | 'constraints' | 'events' | 'animations'>;
 
 /**
  * The Spine 4.3 skeleton of a compiled model: the emitter's one entry, and
@@ -791,7 +805,7 @@ export type SkeletonSource = Pick<CompiledModel, 'referenceScale' | 'stage' | 'b
  * between `skins` and `animations`, where the editor writes it), `constraints`
  * only when the model holds one (assigned after, so it lands last until the
  * key-order pass moves it). The header's keys: `spine, x, y, width, height,
- * fps, referenceScale, images, audio`, the stage's four only together.
+ * fps, referenceScale, images, audio`, the box's four only together.
  *
  * Then, on the finished object and once: `withoutParserDefaults` drops every
  * key at the value the 4.3 parser reads in its absence, and `inEditorKeyOrder`
@@ -800,7 +814,7 @@ export type SkeletonSource = Pick<CompiledModel, 'referenceScale' | 'stage' | 'b
  * throws, so a refusal raised here is raised by a section emitter, in the
  * order above.
  *
- * The stage (`model.stage`, issue #1026) is written as the model holds it,
+ * The box (`header.bounds`, issue #907) is written as `compile` computed it,
  * its four fields together or none. `referenceScale` is the model's, written
  * always and dropped by the parser-default pass at 100 — so a rig stating none and a rig stating 100
  * write the same bytes, as they did when the header carried the stated value.
@@ -811,11 +825,11 @@ export type SkeletonSource = Pick<CompiledModel, 'referenceScale' | 'stage' | 'b
  */
 export function emitSkeleton(model: SkeletonSource, header: SkeletonHeader, order: SkeletonOrder): SpineSkeletonJson {
   const head: SpineSkeletonJson['skeleton'] = { spine: header.spine };
-  if (model.stage !== null) {
-    head.x = model.stage.x;
-    head.y = model.stage.y;
-    head.width = model.stage.width;
-    head.height = model.stage.height;
+  if (header.bounds !== null) {
+    head.x = header.bounds.x;
+    head.y = header.bounds.y;
+    head.width = header.bounds.width;
+    head.height = header.bounds.height;
   }
   if (header.fps !== undefined) head.fps = header.fps;
   head.referenceScale = model.referenceScale;

package/src/ingest.ts

@@ -209,6 +209,18 @@ export interface IngestOptions {
    * refuses it rather than answering it quietly.
    */
   stage?: IngestStage;
+  /**
+   * The stage a rigc build's model document states (issue #907): its `stage`,
+   * or `null` for a rig that declared none. Given, it is read IN PLACE OF the
+   * header's `x`, `y`, `width`, `height` — which on a rigc build since #907 are
+   * the setup-pose bounding box, not the stage — and everything below reads it
+   * as it would read a header stating it (`--stage` beside it is the same
+   * refusal). Absent, the header is read, as for an export: an export carries
+   * no other box. The caller reads it — `src/` reads no files —
+   * (`documentStageBeside` in `src/cli/shared.ts`: the `rigc-compiled/3`
+   * document beside the skeleton, only when its digest is that skeleton's).
+   */
+  documentStage?: IngestStage | null;
   /** The source file's basename, for the provenance note. No path: no leak. */
   source: string;
   /** rigc's own version, for the provenance note. Passed in — `src/` reads no files. */
@@ -1149,9 +1161,9 @@ function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): st
 /**
  * The rig spec's `skeleton` block — and the one judgement in this module.
  *
- * 🚨 **A skeleton JSON need not carry the stage, and it cannot be derived.**
- * Posing the rig gives the ANIMATED extent, which is a different number from the
- * editor's setup box. So a file that declares none is written as declaring none
+ * 🚨 **A skeleton JSON need not carry a box, and a stage cannot be derived.**
+ * The stage is the working area the art was painted in; no pose of the rig
+ * states it. So a file that declares none is written as declaring none
  * — `"width": null, "height": null`, the rig spec's spelling for that claim since
  * issue #578 — and `compile` then emits a header with none of the four fields,
  * which is the file that was read, byte for byte. No finding: nothing was lost,
@@ -1173,9 +1185,22 @@ function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): st
  * that shape; the blocker names the fields it does state.
  *
  * ⭐ It is still the judgement that costs least to get wrong. `diff` does report
- * the box — `stage_present` and `stage_box`, since issue #578 — but they sit in
- * the `(reported)` block that no rung consults, so a deliberately absurd unit box
- * is green everywhere a candidate is scored.
+ * the header's box — `bounds_present` and `bounds_box` (issue #578, renamed by
+ * #907) — but they sit in the `(reported)` block that no rung consults.
+ *
+ * 🔁 **What the box becomes (issue #907).** A header's box is its setup-pose
+ * bounding box — what the format says the four are, and what every editor
+ * export carries there. It is the only box a file has, so it becomes the
+ * rebuild's stage (`A14` and `A19` measure against it, as they did against the
+ * export's header). The rebuild's own header is not carried from it: `build`
+ * computes the setup-pose bounding box of what it draws (`headerBoundsOf` in
+ * `src/compile.ts`), which for a rebuild drawing the source's vertices is
+ * spine-core's `getBounds` over the source on the header's 1e-6 grid at float32 — not the editor's
+ * arithmetic, which on the twelve examples sits up to 0.0071 units away. A
+ * rigc build's own header is likewise its bounding box, not its stage: the
+ * stage is in `skeleton.model.json`, which the caller reads and hands in as
+ * `documentStage` when that document digests this skeleton — and then it is
+ * read in place of the header's box.
  *
  * 🔇 **Both of its silences were here, and both were around the DECLARED branch
  * rather than the missing one.** That branch used to be a bare early return, so
@@ -1186,7 +1211,10 @@ function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): st
  * a decompiler that is right for a reason it never states is a decompiler nobody
  * can check.
  */
-function ingestHeader(head: JsonObject, opts: IngestOptions, note: Note): JsonObject {
+function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note): JsonObject {
+  // A rigc build's stage is its model document's (issue #907, `IngestOptions.documentStage`): read in place of the header's box.
+  const head: JsonObject = opts.documentStage === undefined ? source : Object.fromEntries(Object.entries(source).filter(([key]) => !(STAGE_FIELDS as readonly string[]).includes(key)));
+  if (opts.documentStage) Object.assign(head, opts.documentStage);
   // 🚨 Before a line of transcription, because a header the caller contradicted
   // is not a header to start writing a spec from (issue #626).
   if (declaresStage(head) && opts.stage !== undefined) {
@@ -1243,9 +1271,10 @@ function ingestHeader(head: JsonObject, opts: IngestOptions, note: Note): JsonOb
         `skeleton.${omitted.join('/')}`,
         `the source declares a ${String(head.width)}x${String(head.height)} stage and omits ` +
           `${omitted.map((field) => `"${field}"`).join(' and ')}; inside a declared extent an omitted origin is 0, ` +
-          'which is what `compile` emits and what `diff` compares (#620), so the rig spec states x=' +
+          'which is how `compile` and `diff` read it (#620), so the rig spec states x=' +
           `${String(out.x)}, y=${String(out.y)} rather than leaving the rebuild to a default in another module. ` +
-          `⚠️ The rebuild WILL spell ${omitted.length > 1 ? 'those fields' : 'that field'}: same box, different bytes`,
+          `⚠️ The rebuilt header WILL spell ${omitted.length > 1 ? 'those fields' : 'that field'}: it carries the ` +
+          'setup-pose bounding box `build` computes (#907), whose origin is wherever the art sits',
       );
     }
     return out;

package/src/model.ts

@@ -572,18 +572,21 @@ export interface CompiledAnimation {
 }
 
 /**
- * The setup-pose box the skeleton declares (issue #1026): its origin `x`, `y`
- * and its extent `width`, `height`, exactly as the Spine header states them —
- * the rig spec's `skeleton.width`/`height` (or the manifest's crop), and its
- * `x`/`y` or 0 beside them, which is what the header has always written
- * (issue #578: four fields or none). `null` where the rig declares no stage.
+ * The stage the skeleton declares (issue #1026): its origin `x`, `y` and its
+ * extent `width`, `height` — the rig spec's `skeleton.width`/`height` (or the
+ * manifest's crop), and its `x`/`y` or 0 beside them (issue #578: four fields
+ * or none). `null` where the rig declares no stage.
  *
  * ⭐ **Why the model holds it.** `render` and `check` say whether a candidate
  * declares a stage (issue #714), and `A14`/`A19` read its box; until this field
  * the header of `skeleton.json` was the only place the value was written, so a
- * reader of the document had to open the Spine file beside it. The Spine
- * emitter writes this value into the header (`emitSkeleton`), as it writes
- * `referenceScale` (issue #958): one value, read by both.
+ * reader of the document had to open the Spine file beside it.
+ *
+ * 🔁 **And since issue #907 this is the only place it is written.** The Spine
+ * emitter used to copy it into the header's `x`, `y`, `width`, `height`,
+ * which the format defines as the setup-pose bounding box; the header now
+ * carries that box (`headerBoundsOf` in `src/compile.ts`), and every reader of
+ * the stage — `A14`, `A19`, `explain` — reads it here.
  */
 export interface ModelStage {
   x: number;
@@ -626,8 +629,9 @@ export interface ModelEditorOrder {
 
 export interface CompiledModel extends CarriedFromCompileResult {
   /**
-   * The setup-pose box the skeleton declares, or `null` (issue #1026,
-   * `ModelStage`). The Spine header carries it as `x`, `y`, `width`, `height`.
+   * The stage the skeleton declares, or `null` (issue #1026, `ModelStage`).
+   * Not in the Spine header since issue #907, which carries the setup-pose
+   * bounding box there.
    */
   stage: ModelStage | null;
   /**

package/src/rig.ts

@@ -73,7 +73,14 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
 // ---------------------------------------------------------------------------
 
 /**
- * The setup-pose bounding box and the runtime hints, all optional.
+ * The stage and the runtime hints, all optional.
+ *
+ * 🔁 The four box fields here are rigc's **stage** — the working area the art
+ * was painted in, the frame the coordinate transform and `A14`/`A19` read —
+ * and not the Spine header's box of the same names, which the format defines
+ * as the setup-pose bounding box. Since issue #907 `build` writes that box
+ * into the header, computed from the rig (`headerBoundsOf` in
+ * `src/compile.ts`), and states the stage in `skeleton.model.json`.
  *
  * `x`/`y` default to 0 and `width`/`height` fall back to the cut manifest's crop
  * when there is one. With neither a manifest nor a declaration here the compile
@@ -85,7 +92,7 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
  * stage** (issue #578). Omitting them is silence and stays a refusal by name;
  * stating them `null` is a claim, and the emitted header then carries none of
  * `x`/`y`/`width`/`height` — which is what an editor export of a skeleton whose
- * stage was never set looks like, and what a transcriber of one has to be able
+ * bounds were never set looks like, and what a transcriber of one has to be able
  * to write down. `null` is this spec's spelling for a stated absence everywhere
  * else it has one (`RigSlot.attachment` = "show nothing", the cut manifest's
  * `image` = "this cut does not carry the part"), so it is the spelling here too

package/src/types.ts

@@ -1167,10 +1167,12 @@ export interface SpineSkeletonJson {
   skeleton: {
     spine: string;
     /**
-     * The setup-pose bounding box. All four together or none of them: a rig spec
+     * The setup-pose bounding box — and since issue #907 that is what `build`
+     * writes here, computed by rigc's core (`headerBoundsOf` in `compile.ts`);
+     * it used to copy the stage. All four together or none of them: a rig spec
      * that declares no stage (`skeleton.width`/`height` stated `null` — see
      * `RigSkeletonHeader`) emits a header without any of them, which is what an
-     * export of a skeleton whose stage was never set carries (issue #578).
+     * export of a skeleton whose bounds were never set carries (issue #578).
      *
      * ⚠️ Optional here because the *runtime* leaves them `undefined` when they
      * are absent, not 0. `SkeletonData` declares `x = 0 … height = 0`

package/src/validate.ts

@@ -68,6 +68,7 @@ import {
   type SpineGeneration,
 } from './generation.ts';
 import { posedNumbersOf } from './render.ts';
+import { MODEL_DOCUMENT_SPEC } from './model.ts';
 import { BONE_INHERIT_KNOWN } from './rig.ts';
 import {
   CHANNELS_BY_KIND,
@@ -860,7 +861,7 @@ export function spineSkinEntries(data: ReturnType<SkeletonJson['readSkeletonData
  * line would hide a difference (an order nothing failed on, a name no line
  * printed); `validate()` itself builds them from its own round trip.
  */
-export function runtimeFacts(skeletonText: string, atlasText: string): {
+export function runtimeFacts(skeletonText: string, atlasText: string, modelText?: string): {
   skinEntries: SkinEntryFacts;
   atlasPages: AtlasPageFacts;
   slotColour: SlotColourFacts;
@@ -890,7 +891,7 @@ export function runtimeFacts(skeletonText: string, atlasText: string): {
     skinMembers: data,
     regionJoins: spineRegionJoins(atlasText, raw),
     atlasRegions: { atlas },
-    stage: spineStage(data),
+    stage: spineStage(data, modelText),
     skeletonRoster: rawSkeletonRoster(raw),
     boneTimelines: rawBoneTimelines(raw),
     eventKeys: rawEventKeys(raw),
@@ -1231,9 +1232,42 @@ export function spineAnimatedBones(raw: Json | null): AnimatedBoneFacts {
   };
 }
 
-/** The runtime's supply of `StageFacts` (issue #1025, cut 4c-1): the loaded skeleton's `width` and `height`, as spine-core holds them — `undefined` where the header states none — or both absent with no skeleton. */
-export function spineStage(data: ReturnType<SkeletonJson['readSkeletonData']> | null): StageFacts {
-  return { width: data?.width, height: data?.height };
+/**
+ * The runtime's supply of `StageFacts` (issue #1025, cut 4c-1): the stage A14
+ * and A19 measure against.
+ *
+ * 🔸 **A rigc build's stage is its model document's, not its header's**
+ * (issue #907). Since then the header of a rigc build carries the setup-pose
+ * bounding box — what the format says it is — and the stage, the working
+ * area the art was painted in, is stated by the `rigc-compiled/3` document
+ * written beside the pair (`stage`, issue #1026). So where the caller hands a
+ * `/3` document (`modelText`), its `stage` is read: the two extents, or both
+ * `undefined` where it states `null`. Everywhere else — an editor export, a
+ * bare directory with no document, a `/2` or `/1` document, written when the
+ * header still was the stage — it is the loaded skeleton's `width` and
+ * `height`, as spine-core holds them (`undefined` where the header states
+ * none), or both absent with no skeleton. An export carries no other box, so
+ * on an export the rules measure against its bounding box, as they always
+ * did.
+ */
+export function spineStage(data: ReturnType<SkeletonJson['readSkeletonData']> | null, modelText?: string): StageFacts {
+  return documentStage(modelText) ?? { width: data?.width, height: data?.height };
+}
+
+/** The stage a `rigc-compiled/3` document states, or `undefined` where there is no such document (`spineStage`). */
+function documentStage(modelText: string | undefined): StageFacts | undefined {
+  if (modelText === undefined) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(modelText);
+  } catch {
+    return undefined;
+  }
+  if (!isObj(doc) || doc.spec !== MODEL_DOCUMENT_SPEC || !('stage' in doc)) return undefined;
+  const stage = doc.stage;
+  if (stage === null) return { width: undefined, height: undefined };
+  if (isObj(stage) && typeof stage.width === 'number' && typeof stage.height === 'number') return { width: stage.width, height: stage.height };
+  return undefined;
 }
 
 /**
@@ -2556,7 +2590,7 @@ export function validate(input: ValidateInput): ValidateReport {
     // somebody else's canvas. A rig that declares no budget has nothing to be
     // measured against, and the assertion says so instead of inventing a wall.
     check('A13_MESH_BUDGET', () => a13MeshBudget(verdicts, loadedMeshFacts(), input));
-    check('A14_NO_FULL_FRAME_MESH', () => a14NoFullFrameMesh(verdicts, loadedMeshFacts(), spineStage(data)));
+    check('A14_NO_FULL_FRAME_MESH', () => a14NoFullFrameMesh(verdicts, loadedMeshFacts(), spineStage(data, input.modelText)));
 
     // --- A15: idle must not key a mesh-driving bone (dirty-skip lever) -----
     //
@@ -3200,7 +3234,7 @@ export function validate(input: ValidateInput): ValidateReport {
   // fires, and it now has to name the profile it belongs to as well as the one
   // that does not ask — the reader opted in, and the message is where they find
   // out what they opted into.
-  check('A19_OVERLAY_PNGS_HAVE_ALPHA', () => a19OverlayPngsHaveAlpha(verdicts, { atlas }, spineStage(skeletonData), { regionAttachments }, input));
+  check('A19_OVERLAY_PNGS_HAVE_ALPHA', () => a19OverlayPngsHaveAlpha(verdicts, { atlas }, spineStage(skeletonData, input.modelText), { regionAttachments }, input));
   // Two regions on one page whose rectangles overlap and whose footprints do
   // too — a mesh's hull, else the rectangle (issue #1099). The clause A06 held
   // about two rectangles over the same texels, read over what each region