spine-rigc 0.32.0 → 0.33.0

package/README.md

@@ -516,7 +516,7 @@ commands take it and what its default is.
 | `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
-| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the stage for a skeleton that declares none — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
+| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/` |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
@@ -595,10 +595,12 @@ One thing it drops on purpose and says so: a path attachment's `lengths`, which
 
 ⚠️ **Two values are not in a skeleton at all.**
 
-- **The stage.** `skeleton.width`/`height`: rigc always writes one, and a skeleton that
-  carries none is refused by name unless `--stage x,y,w,h` supplies it. It is not
-  derivable — posing the rig gives the *animated* extent, which is a different number
-  from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
+- **The stage.** `skeleton.width`/`height`. A skeleton that declares none is carried as
+  declaring none — the rig spec states `"width": null, "height": null` and the rebuild
+  carries no box either, byte for byte
+  ([#714](https://github.com/firejune/rigc/issues/714)) — and `--stage x,y,w,h` is how a
+  caller *adds* one, recorded as a judgement. It is not derivable — posing the rig gives
+  the *animated* extent, which is a different number from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
   too**, for the opposite reason: two sources for one value, where the file is the record
   of what was measured. It used to be read after the box and therefore never
   ([#626](https://github.com/firejune/rigc/issues/626)). ⚠️ This said *"an editor export carries none"* until #594 measured

package/cli.ts

@@ -1746,6 +1746,46 @@ function readPositiveNumber(flags: Record<string, string>, key: string, fallback
   return value;
 }
 
+/**
+ * Does this skeleton declare a setup stage — a numeric width AND height?
+ *
+ * Read off the loaded `SkeletonData` for `render` and off the file's header for
+ * `preview`, which never loads one; both are the same two fields, because
+ * `SkeletonJson` copies them across unconditionally (`SkeletonJson.js:70-73`),
+ * so a header that omits them leaves `undefined` on a field typed `number`.
+ */
+function declaresSetupStage(header: { width?: unknown; height?: unknown }): boolean {
+  return typeof header.width === 'number' && typeof header.height === 'number';
+}
+
+/** The `skeleton` block of a skeleton file's text, or an empty one where it has none. */
+function skeletonHeaderOf(skeletonText: string): { width?: unknown; height?: unknown } {
+  const root = JSON.parse(skeletonText) as { skeleton?: { width?: unknown; height?: unknown } };
+  return root.skeleton ?? {};
+}
+
+/**
+ * What `render` and `preview` say of their framing on a skeleton that declares
+ * no stage (issue #714).
+ *
+ * ⚠️ **Neither frames to a stage on ANY skeleton**, so this is not a fallback
+ * being announced: `framingViewport` is the union of every animation's posed
+ * bounds, and the Spine Web Player's `calculateAnimationViewport` samples the
+ * playing animation's bounds whenever its config states no viewport box, which
+ * `buildPreview` never does. The line is printed only where a stage is absent
+ * because that is the one case where a reader can ask *what box stood in for
+ * it* — and the answer has to be "none", said, rather than a rectangle that looks
+ * like a default. On a staged skeleton the output is the bytes it always was.
+ */
+const STAGELESS_FRAMING = {
+  render:
+    'framing  the posed extent of every animation, padded — this skeleton declares no stage, and nothing stands ' +
+    'in for one: render frames to the posed extent whether or not a stage is declared',
+  preview:
+    "framing  the Spine Web Player's own: the posed extent of the animation it plays — this skeleton declares no " +
+    'stage, and nothing stands in for one: the player frames that way whether or not a stage is declared',
+} as const;
+
 /**
  * render — the frame series, drawn by the same rasteriser `check` measures with.
  *
@@ -1788,6 +1828,7 @@ function cmdRender(flags: Record<string, string>): void {
   const sampled: Map<string, Frame[]> =
     only === undefined ? sampleAll(data, fps, pose) : new Map([[only, sampleAnimation(data, only, fps, pose)]]);
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
+  if (!declaresSetupStage(data)) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
   mkdirSync(outRoot, { recursive: true });
   const sets: FrameSet[] = [];
@@ -1903,6 +1944,7 @@ function cmdPreview(flags: Record<string, string>): void {
   for (const page of pages) {
     console.log(`  ..    page     ${page.name.padEnd(28)} ${(page.bytes.length / 1024).toFixed(1)} KiB`);
   }
+  if (!declaresSetupStage(skeletonHeaderOf(skeletonText))) console.log(`  ..    ${STAGELESS_FRAMING.preview}`);
 
   const html = buildPreview({
     skeletonText,
@@ -3263,9 +3305,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     '--images <dir>` on every rebuild), `none` states width/height only for `build --atlas-in <pack>` to ' +
     'resolve (default: loose)',
   stage:
-    'the setup bounding box — `skeleton.x,y,width,height` — for a skeleton that declares none. It cannot be ' +
+    'the setup bounding box — `skeleton.x,y,width,height` — to ADD to a skeleton that declares none. It cannot be ' +
     'derived: posing the rig gives the ANIMATED extent, which is a different number from the setup box, so this ' +
-    "is the caller's value, and without it the missing stage is reported as a blocker. ⚠️ An editor export MAY " +
+    "is the caller's value, and without it the absence is carried: the spec states `\"width\": null, \"height\": " +
+    'null` and the rebuild declares no stage either. ⚠️ An editor export MAY ' +
     'carry none; every editor export measured for this project carries one and ingest reads it straight through, ' +
     'so the flag is for a file that really has none rather than for editor exports as a class. ⛔ Beside a ' +
     'skeleton that already declares a box it is REFUSED rather than ignored: two sources for one value, and the ' +
@@ -3677,12 +3720,11 @@ const USAGE = [
   '  rigc ingest hero.json --out specs/ --images parts/         rig.json + motion.json',
   'The contract is an equality, not a rulebook: build(ingest(x)) is x, byte for byte.',
   'It reads the skeleton and nothing else — no .spine project, no binary .skel, no',
-  'atlas — so two things are the caller\'s and are refused rather than guessed: the',
-  'setup stage (--stage, only when the skeleton itself declares none — beside a box the',
-  'file states, the flag is refused rather than ignored) and how the spec',
-  'reaches the art (--art). --images <dir> is the third and the only optional one: it',
-  'WRITES the rig spec\'s own images directory, relative to --out, so the rebuild needs',
-  'no flag.',
+  'atlas — so how the spec reaches the art is the caller\'s (--art) and is not guessed.',
+  'A setup stage the skeleton states is read; one it does not state is carried as',
+  'absent, and --stage is how a caller adds a box to such a file — beside a box the',
+  'file states, the flag is refused rather than ignored. --images <dir> WRITES the rig',
+  'spec\'s own images directory, relative to --out, so the rebuild needs no flag.',
   'Everything the spec format cannot hold is printed as a named finding and',
   'exits non-zero, with both files still written, because a spec plus a list of what',
   'is missing from it beats no spec at all.',

package/docs/AUTHORING.md

@@ -573,7 +573,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` | the setup bounding box, **for a skeleton that declares none**. An editor export *may* be one; 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 ([#626](https://github.com/firejune/rigc/issues/626)) |
+| `--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` ([#714](https://github.com/firejune/rigc/issues/714)). 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 ([#626](https://github.com/firejune/rigc/issues/626)) |
 | `--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`
@@ -586,9 +586,13 @@ where the parts are in one convention.
 🚨 **The stage is one of the two values `ingest` will not guess.** A skeleton JSON
 *need not* carry `skeleton.width`/`height`, and when it does not rigc cannot derive
 one — 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 a **blocker**, named, unless
-`--stage x,y,w,h` supplies it; supply it from the project the file came from, or from
-the editor's own canvas.
+editor's setup box. So a file that declares none is **carried as declaring none**: the
+spec states `"width": null, "height": null` (§3.1), the rebuild emits no box, and
+nothing is recorded, because the rebuild is the file that was read
+([#714](https://github.com/firejune/rigc/issues/714)). `--stage x,y,w,h` *adds* a box —
+supply it from the project the file came from, or from the editor's own canvas — and
+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.
 
 ⛔ **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
@@ -609,7 +613,8 @@ early return on every one of them, and not one needs the flag. What an editor ex
 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
 ([#616](https://github.com/firejune/rigc/issues/616)). So `--stage` is for a file that
-really has none, and this repository's corpus holds no example of one. It is still the
+really has none, and this repository's corpus holds no example of one; a production
+corpus measured for [#714](https://github.com/firejune/rigc/issues/714) holds 48 of 48. It is still the
 value that costs least to get wrong: `diff` reports the box as `stage_present` and
 `stage_box` ([#578](https://github.com/firejune/rigc/issues/578)) and both are
 `(reported)`, so nothing on the ladder consults them.
@@ -1079,6 +1084,23 @@ Three readings stay apart, and the middle one is the point of the other two:
 | one `null`, one number | refused — a stage has both extents or neither, and which half was meant is not derivable |
 | the pair `null` **and** an `x` or `y` | refused — an origin for a box that is not there |
 
+What each tool does without one — every reader of the stage in the tree, measured
+for [#714](https://github.com/firejune/rigc/issues/714), and not one of them puts a
+number where the box would be:
+
+| Reader | With a stage | Without one |
+| --- | --- | --- |
+| `build` | emits `x`/`y`/`width`/`height` | 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 one image that covers the stage | exempts nothing, and says so |
+| `diff` | `stage_present` and `stage_box` | `stage_present` 1/1 when neither side declares one (agreement), `stage_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 |
+
 ⚠️ 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

package/docs/INGEST.md

@@ -531,14 +531,23 @@ at the policy rather than implying the file was read.
 
 **Two values are not in a skeleton**, so `ingest` asks rather than guesses:
 
-- **the stage** (`skeleton.width`/`height`) — `--stage x,y,w,h` is how you supply one
-  when the file has none. ⚠️ **This page said an editor export carries none until
+- **the stage** (`skeleton.width`/`height`) — a file that declares none is **carried as
+  declaring none**: the rig spec states `"width": null, "height": null` (§2.1 step 3's
+  spelling, [#578](https://github.com/firejune/rigc/issues/578)), the rebuild emits a
+  header with none of `x`/`y`/`width`/`height`, and it is the file that was read, byte
+  for byte. No finding is recorded, because nothing was lost and nobody decided
+  anything ([#714](https://github.com/firejune/rigc/issues/714)). `--stage x,y,w,h` is how
+  a caller *adds* a box to such a file, and that is a `NO_STAGE` **judgement**. Until
+  #714 the absence was a blocker and the flag the only road through it — a number the
+  source never stated, on the shape #714 counts in 48 of 48 production exports.
+  ⚠️ **This page said an editor export carries none until
   [#594](https://github.com/firejune/rigc/issues/594) measured it: all twelve exports in
   the fetched corpus carry a stage**, `ingest` reads it straight through, and not one of
   them needed the flag. What holds without qualification is that the box cannot be
   *derived* — posing the rig gives the *animated* extent, which is a different number
-  from the setup box — so a skeleton that really declares none is a `NO_STAGE` blocker
-  rather than a guess. It is also the value that costs least to get wrong: `diff`
+  from the setup box. 🔸 **Half a stage is still 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`, since
   [#578](https://github.com/firejune/rigc/issues/578)) and they are `(reported)`, so
   nothing on the ladder reads them and an absurd box is green nearly everywhere. The
@@ -609,7 +618,7 @@ is the one failure a comparison of two sets cannot show you.
 | `HEADER_ORIGIN` | `LOSS` | 0 | the source declares an extent and omits `x`/`y`. Inside a declared extent an omitted origin **is** 0, so the spec states it — and the rebuild then spells two fields the source did not | nothing. Same box, different bytes — which is why byte identity is not the claim for an export that takes this branch |
 | `HEADER_REDERIVED` | `LOSS` | 0 | `skeleton.spine`: the rebuild writes the version of the runtime rigc links. The line says whether that is the same string the source states | nothing — but read the line: a 4.2 export rebuilds as 4.3 in that one field, and a source from another generation raises `GENERATION_UNSUPPORTED` beside it, which is the blocker about the DATA rather than about the string |
 | `IK_KEY_FIELD` | `BLOCK` | 1 | a key field on an `ik` timeline that is not part of its shape | check the spelling; an unknown field is dropped from the rebuilt track |
-| `NO_STAGE` | `BLOCK` `JUDGE` | 1 | the skeleton declares no stage. It is a blocker with no `--stage`, and a **judgement** — exit 0 — when `--stage x,y,w,h` supplies one, because nothing measured the box you gave it | supply the box from the project the file came from. It cannot be derived: posing the rig gives the animated extent, which is a different number |
+| `NO_STAGE` | `BLOCK` `JUDGE` | 1 | the skeleton declares no stage, and one of two things follows. A **judgement** — exit 0 — when `--stage x,y,w,h` supplied a box, because nothing measured the box you gave it. A **blocker** when the header states **half** a stage — an origin with no extent, or one extent without the other — which the rig spec cannot hold; the detail names the fields it states. A header with **none** of the four is not a finding at all: it is carried as `"width": null, "height": null` and rebuilds byte for byte ([#714](https://github.com/firejune/rigc/issues/714)) | for the judgement, nothing if the box came from the project the file came from. For the blocker, supply the box with `--stage`, or take the stray field(s) out of the source and the absence is carried. It cannot be derived: posing the rig gives the animated extent, which is a different number |
 | `PATH_LENGTHS` | `LOSS` | 0 | the source states a path attachment's `lengths` and rigc re-measures it as `PathConstraint` does | nothing. Dropping it is the correct reading: the field is the runtime's own four-sample forward difference, not an arc length |
 | `PATH_TIMELINE` | `BLOCK` | 1 | a path-constraint timeline the motion spec has no track for — it carries position, spacing and mix | transcribe it, or accept that the rebuild plays nothing there |
 | `PHYSICS_DRIVES_NOTHING` | `LOSS` | 0 | a physics constraint none of whose `x`, `y`, `rotate`, `scaleX`, `shearX` is above 0 — absent, or stated at 0 or below. `PhysicsConstraint.update` applies a component only above 0 (`PhysicsConstraint.js:112`), so it moves no bone, and `build` refuses exactly that shape by name at `A23_PHYSICS_CONSTRAINT_EFFECTIVE` — which, until [#731](https://github.com/firejune/rigc/issues/731), meant the whole rebuild of a file an editor exports was refused over a constraint that did nothing in it. The rig spec **omits** it, together with every timeline keyed to it (a track naming it would be an unknown constraint to the rebuild, refused at compile) and its place on any skin's `physics` list; the detail names each, and the values it did state. Measured on a generated rig through spine-core, posing the source with and without such a constraint differs by **0** on every bone world value — and by at most 9e-8 when it sits on the root, which is the runtime's `modifyWorld` recomputing a local transform it had no reason to, not a component. ⚠️ **One thing does move:** a duration is the last key an animation has left, so an omitted timeline that held the last key shortens the rebuilt animation, and the detail says which animation and both lengths | nothing, if it was meant to do nothing. If it was meant to jiggle, the file never said so: give it the component it should drive and it is carried like any other. Where the detail names a shortened animation and the length matters to whatever loops it, key something at the length it had |
@@ -693,7 +702,8 @@ it, and the only differing paths were the name and the `note`.
    the file: `attachment` simply absent.
 
    ⚠️ **If the export's `skeleton` block carries no `x`/`y`/`width`/`height`, write
-   `"width": null, "height": null` and do not invent one** (issue #578). That shape is
+   `"width": null, "height": null` and do not invent one** (issue #578) — which is
+   also what `rigc ingest` writes for such a file since #714. That shape is
    common — the twelve exports in `examples/` all carry the four, and 37 of 37 exports
    in one production corpus carry none of them — and until the `null` pair existed the
    only two moves were a made-up stage or a file that could not be transcribed. The
@@ -1389,7 +1399,7 @@ clean page:
 exists to make explicit".** The clause was not wrong that a decompiler meets an
 invention — it was wrong about *which*, and wrong that it is unavoidable: a refusal
 naming the field is what this repository does with a missing number everywhere else,
-and it is what `ingest` does here (§2.0). ⚠️ Not to be confused with the *atlas*
+and a stated absence is what `ingest` writes where the skeleton has none (§2.0, #714). ⚠️ Not to be confused with the *atlas*
 importer below, which is a different direction and also exists.
 
 ⚠️ **What `ingest` is still not.** It reads skeleton JSON and writes two spec files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/skills/ingest/SKILL.md

@@ -36,11 +36,12 @@ rigc build --rig specs/rig.json --motion specs/motion.json --images parts/ --out
 It reads the skeleton — **only** the skeleton — and writes the rig spec and motion
 spec that rebuild it: **byte for byte for a skeleton rigc emitted**, and for an editor
 export the weaker claim `diff` measures, with three kinds of benign difference left —
-INGEST §2.3. Two values it refuses rather than guessing: the
-**stage** (`--stage`, for a skeleton that declares none — an editor export *may* be
-one, though every one in the example corpus carries a box, and passing the flag at a
-file that declares a box is refused rather than ignored) and each animation's
-**duration** (the largest key time, recorded as a finding).
+INGEST §2.3. Two values it will not guess: the
+**stage** (a skeleton that declares none is carried as declaring none, and `--stage`
+adds a box to one — an editor export *may* be such a file, though every one in the
+example corpus carries a box, and passing the flag at a file that declares a box is
+refused rather than ignored) and each animation's **duration** (the largest key time,
+recorded as a finding).
 Read `findings.json`: a `BLOCK` line means the rebuild will be missing something and
 the command exits non-zero. Every code it can print — gutter, exit, meaning, what to
 do — is the finding-code table in INGEST §2.0. Keep the `note` both specs carry.

package/src/check.ts

@@ -1059,6 +1059,18 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const notes: string[] = [];
 
   const posable = posableFromText(options.skeletonText, options.atlasText, options.atlasDir);
+  // A candidate that declares no stage is framed exactly as one that does,
+  // because no framing here reads a stage: the world box is fitted from what the
+  // candidate draws. Said on the one candidate where a reader can ask what box
+  // stood in for the absent one (issue #714) — `SkeletonJson` copies the header
+  // fields across unconditionally (`SkeletonJson.js:70-73`), so an omitted
+  // extent is `undefined` here, not 0.
+  if (typeof posable.data.width !== 'number' || typeof posable.data.height !== 'number') {
+    notes.push(
+      'the candidate declares no stage (no `skeleton.width`/`height`), and nothing stands in for one: its world ' +
+        'box is fitted from the pixels it draws, as it is for every candidate, so the absence moves no figure below.',
+    );
+  }
   // The substitution is loaded before anything is posed, because posing has to
   // record each piece's original-art UVs for it and that is the one thing about
   // this measure that cannot be added afterwards — see `PieceTexture`.

package/src/ingest.ts

@@ -24,9 +24,11 @@
  * something nobody wrote. Where the skeleton cannot answer, this records a
  * **finding** with a code and writes nothing: `findings` is the product, not a
  * log. Exactly two values are not in a skeleton at all (the stage and an
- * animation's duration) and both are `judgement` findings; every construct the
- * spec format cannot hold is a `blocker`; everything rigc re-derives rather than
- * carries is `lossy`. The one thing it refuses outright rather than recording is
+ * animation's duration), and a value somebody supplies for either is a
+ * `judgement` finding — a stage the file does not declare is carried as the
+ * absence it is, and only a caller's `--stage` is somebody deciding (issue
+ * #714); every construct the spec format cannot hold is a `blocker`; everything
+ * rigc re-derives rather than carries is `lossy`. The one thing it refuses outright rather than recording is
  * an OPTION that contradicts the file — see `IngestError`.
  *
  * ## What it does not read
@@ -120,8 +122,8 @@ export class IngestSpecRefused extends Error {
  *
  * - `blocker` — the spec format cannot say this, so the rebuilt skeleton will
  *   NOT be the one that was read. Non-zero exit.
- * - `judgement` — the skeleton does not carry it and somebody has to decide.
- *   There are exactly two: the stage, and an animation's duration.
+ * - `judgement` — the skeleton does not carry it and somebody decided. There
+ *   are exactly two: a stage the caller supplied, and an animation's duration.
  * - `lossy` — the skeleton's spelling and rigc's differ, on purpose, and the
  *   difference is named: a value rigc re-derives rather than takes (`lengths`,
  *   the `spine` version), a field the spec has no home for (`hash`, `audio`), or
@@ -646,8 +648,8 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   // -- header ---------------------------------------------------------------
   // 🚨 THE SEAM. One function decides the rig spec's `skeleton` block, and the
   // stage is the only value in this whole module that a skeleton cannot answer
-  // for. Issue #578 is landing a way for a rig spec to SAY that a skeleton
-  // declares no stage; when it does, this is the one place that changes.
+  // for. Since #578 a rig spec can SAY that a skeleton declares no stage, and
+  // since #714 this is where a file that declares none is carried as saying so.
   const rigHeader = ingestHeader(obj(root.skeleton), opts, note);
 
   // -- physics constraints that drive nothing (issue #731) ------------------
@@ -1014,6 +1016,9 @@ function readGeneration(root: JsonObject, note: Note): void {
   );
 }
 
+/** The four fields a stage is, in the order the editor and `compile` write them. */
+const STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
+
 /**
  * Does this header declare a stage?
  *
@@ -1043,18 +1048,28 @@ 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.** rigc
- * always emits `x`/`y`/`width`/`height`, so a rigc build round-trips with nothing
- * to decide. `compile` refuses without one, and there is no derivation: posing
- * the rig gives the ANIMATED extent, which is a different number from the
- * editor's setup box. So with no `--stage` this records a blocker naming the
- * field and writes nothing plausible.
+ * 🚨 **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
+ * — `"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,
+ * nothing re-derived and nobody decided anything, and a line saying so would be
+ * a finding about a file that rebuilds exactly (issue #714).
+ *
+ * ⚠️ **That is the shape of a whole production corpus, not a corner.** Until
+ * #714 this branch was a `NO_STAGE` blocker and the only road through it was a
+ * caller's `--stage` — a number the source never stated. Issue #714 counts 48 of
+ * 48 production exports at 4.3.26 carrying no box; all twelve exports under
+ * `examples/` carry all four fields, and take the declared branch below.
  *
- * ⚠️ This said an editor export's `skeleton` block is `hash`, `spine`, `images`,
- * `audio` **and no box at all** until issue #594 measured the corpus: all twelve
- * exports under `examples/` carry `x`/`y`/`width`/`height`, and the declared-stage
- * branch below is the one they take. The blocker is for a file that really has
- * none, and this module has no example of one.
+ * 🔸 **Half a stage is still a blocker, and keeps the code.** A header that
+ * states an origin with no extent, or one extent without the other, declares no
+ * stage — the extent is what declares one — but it is not the absence either:
+ * the rig spec holds a stage as four fields or none (`parseRigSpec` refuses the
+ * pair `null` beside an `x`, and one extent alone is `compile`'s `no stage size`),
+ * so the rebuild cannot carry what the file states. No export measured here has
+ * 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
@@ -1135,13 +1150,28 @@ function ingestHeader(head: JsonObject, opts: IngestOptions, note: Note): JsonOb
     return out;
   }
   if (opts.stage === undefined) {
+    const stated = STAGE_FIELDS.filter((field) => head[field] !== undefined);
+    if (stated.length === 0) {
+      // The absence, carried: the pair goes where `RIG_KEYS` orders it, so the
+      // spec reads like one a transcriber would have written by hand.
+      const carried: JsonObject = {};
+      for (const field of RIG_KEYS.RigSkeletonHeader) {
+        if (field === 'width' || field === 'height') carried[field] = null;
+        else if (out[field] !== undefined) carried[field] = out[field];
+      }
+      return carried;
+    }
+    const unstated = STAGE_FIELDS.filter((field) => head[field] === undefined);
     note(
       'blocker',
       'NO_STAGE',
       'skeleton.width/height',
-      'the skeleton declares no stage; give --stage x,y,w,h — the value is the caller\'s, not derived. Posing the ' +
-        'rig would give the ANIMATED extent, which is a different number from the setup box, so rigc refuses rather ' +
-        'than measuring the wrong thing (or state the absence once the spec can)',
+      `the skeleton states ${stated.map((field) => `"${field}"`).join(', ')} and no ` +
+        `${unstated.map((field) => `"${field}"`).join(', ')}, so it declares no stage — a width and a height are ` +
+        'what declare one — and it is not the absence either. A rig spec holds a stage as four fields or none, so ' +
+        'the rebuild cannot carry what this header states. Give --stage x,y,w,h if the box is known — the value is ' +
+        'the caller\'s, not derived: posing the rig would give the ANIMATED extent, which is a different number from ' +
+        'the setup box — or take the stray field(s) out of the source, and the absence is then carried as it stands',
     );
     return out;
   }
@@ -1151,8 +1181,9 @@ function ingestHeader(head: JsonObject, opts: IngestOptions, note: Note): JsonOb
     'NO_STAGE',
     'skeleton.width/height',
     `the skeleton declares no stage and the caller supplied ${opts.stage.x},${opts.stage.y},${opts.stage.width},` +
-      `${opts.stage.height}. Nothing measured it: no gate in this tree reads the skeleton header, so a wrong box is ` +
-      'green everywhere (or state the absence once the spec can)',
+      `${opts.stage.height}. Nothing measured it against the art: \`A14\` and \`A19\` measure the art against it ` +
+      'and `diff` reports it, so a wrong box is green everywhere. Without --stage the absence is carried instead, ' +
+      'and the rebuild declares no stage either',
   );
   return out;
 }