spine-rigc 0.31.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 |
@@ -533,9 +533,9 @@ first three work on any reference you have, and `bench` is a repository workflow
 and `bun run fetch-examples`. The reasoning behind them is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
-`build` and `validate` both default to `--profile spine` — the 31 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 32 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 46: the other 15 are one renderer's policy and one canvas budget's, and they
+adds all 47: the other 15 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
 ⇒ **That reason is about foreign data and does not carry to a rig you are authoring
 yourself: author under `--profile spine-html` and read the extra 15 as findings, and
@@ -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
@@ -681,7 +683,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
-| 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 46 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
+| 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 47 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
 | 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 has to mean before the number is claimed — conditions rather than a feature list, because direction here comes from what users hit |
 | 📐 [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
@@ -738,7 +740,7 @@ quality."* All six, with their verdicts, are in
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 46 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 47 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

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.',