spine-rigc 0.32.0 → 0.33.1

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 32 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 34 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 47: the other 15 are one renderer's policy and one canvas budget's, and they
+adds all 49: 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 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 |
+| 🎓 **[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 49 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 47 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 49 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.',

package/docs/AUTHORING.md

@@ -169,7 +169,7 @@ What the flags mean:
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
-| `--profile` | `spine` = the 32 validity rules (**the default**) · `spine-html` = all 47, opt-in |
+| `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 49, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
@@ -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
@@ -4064,7 +4086,11 @@ exactly what a mix that was 0 at setup needs said.
   above 1 is a real editor idiom rather than a mistake.
 - ⚠️ A mix is only read by the runtime if the constraint declares the matching
   `properties` mapping (§3.5). Keying `mixScaleY` on a constraint that maps
-  rotation only is dead data — legal, loaded, and it moves nothing.
+  rotation only is dead data — legal, loaded, and it moves nothing. ⚠️ So is every
+  mix a key **omits**, and that one looks like a rescue: the parser reads an
+  omitted mix as 1, so a key of `mixRotate: 0` alone on a rotate-only constraint
+  carries five mixes of 1 that nothing reads. `A48` judges only the mixes of the
+  properties the constraint drives (§4.12).
 - The refusals are §4.9's, with `transform` in place of `ik`.
 
 ### 4.11 `deform` — moving an attachment's vertices
@@ -4942,6 +4968,35 @@ constraint declaring `mixGlobal`, since only the physics family has one. The ref
 says both halves — `path constraint "P" has mixRotate 0, mixX 0 and mixY 0 at setup
 and none of the 2 animations keys its mix above 0; …` — and names both repairs.
 
+⚠️ **The same question of an `ik` and a `transform` constraint is `A47` and `A48`**
+([#765](https://github.com/firejune/rigc/issues/765)); until then no assertion asked
+it, and a rig resting either kind muted with nothing keying it gated green with 0
+failures. [measured] on generated fixtures, an ik at `mix` 0 and a transform at
+every mix 0, each with nothing keying it and each keyed to 0 only, pose every bone
+exactly where the same rig with no constraint does. They read the timelines through
+the same helper as `A23`/`A36`/`A37`, so a lifted Bezier between two keys of 0 is a
+rescue and a 0-only timeline is not, with two differences that are the runtime's:
+
+- **Live is `!== 0`, not `> 0`.** `IkConstraint.update` returns on `mix === 0`, and
+  a transform applies a property only when its own mix `!== 0`, so a negative mix
+  runs the constraint inverted. [measured] five transform constraints across four of
+  the editor's example exports (`6-arcs-pro`, `8-follow-through-pro-ball`,
+  `sack-pro` twice, `spineboy-pro`) rest at `mixX` = `mixY` = −1 with nothing keying
+  them, each moves its bones against the same constraint at every mix 0, and a
+  `> 0` reading refuses all five. `A36`/`A37` still read `> 0`.
+- **A transform is judged on the mixes of the properties it drives.**
+  `TransformConstraint.update` returns early only when all six mixes are 0, but a
+  property is applied by its own mix, and a key omitting a mix reads it as 1
+  (§4.10). [measured] a rotate-only transform keyed to `mixRotate: 0` alone — five
+  mixes of 1 on the loaded timeline — and one keyed to `mixX: 1` both pose exactly
+  where no constraint does, and both are refused. A transform whose `properties`
+  name no `to` at all is refused with its own sentence: no mix it carries is read.
+
+`ik constraint "reach" has mix 0 at setup and none of the 1 animation keys its mix
+above 0; update() returns on mix 0, so "upper" never reaches for "goal" — rest it
+above 0, or key its mix above 0 in an animation`. A rig resting at 0 and keyed up by
+the animation that needs it — spineboy's aim — is refused by neither.
+
 ### 4.13 `sequence` — which frame of a numbered series shows
 
 The other attachment timeline, beside `deform` and for the same reason: its key is
@@ -5413,10 +5468,12 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET` | both | two or more sliders whose animations key the same timeline, where a later one is not `additive` — it writes that property outright at `mix: 1` and every earlier slider on it is dead (§3.5.2). Also fires when the shared timeline **cannot** be applied additively (a slot colour, an attachment swap, a draw order, an ik mix, a path's `spacing`, most physics properties), where `"additive": true` is not the fix and one of the two has to go. ⭐ Which of the two it is, is **posed rather than read off `Timeline.additive`**: the shared timeline is applied twice with `add` set and the detail says what it did ([#655](https://github.com/firejune/rigc/issues/655) — two classes declare that flag falsely about themselves, so a path constraint's `mix` and a slider's `time` were refused although they compose). The detail names the bone or slot and the property, every slider keying it in `constraints` order with its flag, which one wins today, and the class that was posed. Four shapes are deliberately not findings: a slider below `mix: 1` or with its `mix` keyed (the apply is then a lerp from the current pose, not an overwrite), two `skinRequired` sliders no skin activates together, two sliders on different properties, and a shared timeline that writes **nothing a pose holds** — an `events` timeline fires no event under a slider (`firedEvents` is null), so neither slider has anything there for the other to erase. **SKIP** when fewer than two sliders are at full authority; a PASS means two were compared |
 | `A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP` | both | a physics constraint driving a component the **Spine editor** cannot hold, on a rig that declared `invariants.editorRoundTrip` (§3.7). The editor's physics model holds `x` and `y` only, with no cap on how many at once, so a constraint driving `rotate`, `scaleX` or `shearX` is imported, exported and handed back driving **nothing** — measured over three rigs and twelve constraints with the predictions written first ([#540](https://github.com/firejune/rigc/issues/540)). The detail names the constraint and each component. ⚠️ rigc's own output is correct — every runtime plays a rotation jiggle — so this is opt-in and the default is *not* silence: on a rig that declares nothing it **SKIPs**, and the SKIP names the constraint and the component anyway, so an author learns without having asked. Fix by driving the constraint in `x`/`y`, or by dropping the declaration if the rig never goes near the editor. Disjoint from `A23_PHYSICS_CONSTRAINT_EFFECTIVE` by construction: A23 refuses an **empty** driven set, which is what comes back from the editor, and this refuses a non-empty one that will not survive going in. **SKIP** also when the rig declares the editor and carries no physics constraint at all |
 | `A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER` | both | a slider whose animation keys a property of a constraint **at or before it** in `constraints` (§3.5.2) — a slider's `mix` or `time`, an ik or transform mix, a path `position`, `spacing` or `mix`, any physics value. That array is the update order for every kind, and each constraint reads its own applied pose when its turn comes — `Slider.update` takes `mix` as the alpha it applies with and `time` as the time it applies at, `PhysicsConstraint.update` returns on `mix` 0 before reading the rest — so the key lands after the only read of it and `Posed.resetConstrained` discards it before the next frame: what the driven constraint drives is dead at every position of the driving dial, although its pose still holds the number ([#658](https://github.com/firejune/rigc/issues/658), [#665](https://github.com/firejune/rigc/issues/665)). The detail names the slider, the driven constraint with its kind, both array indices, the property, the runtime class whose `update` reads it, and the animation the key sits in. Fix by moving the driver earlier, or by keying that property from a slider that already is. **The two indices equal is the same failure**: a slider cannot key its own `mix` or `time`, and one muted at setup that keys its own `mix` up never applies anything at all — `A37` is silent there, because it asks whether *an* animation keys the mix and not which one. **Two shapes it deliberately leaves out**, both measured: a `physics` `reset` key, which fires on a crossed frame time and so never fires from a slider at all, in either order — the reorder would repair nothing; and a physics timeline naming no constraint, which is every physics constraint declaring that property global and IS refused for the ones already run. Disjoint from `A40` by construction: `A40` asks who writes a shared property last and excludes every slider whose `mix` is keyed, this asks whether anything reads what was written. **SKIP** when the skeleton declares no slider, and when no slider's animation keys a constraint property — that SKIP names any `reset` keys it found — a pass means a driver and a driven were compared |
-| `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | both | a slot's `dark` (§3.3) or an `rgba2` / `rgb2` timeline (§4.4) that the runtime does not hold as the file states it. Three shapes, all of which parse in silence: a `dark` the slot reader **drops** — it takes the field through a truthiness test, so `""` is discarded without a word and the slot renders with one colour; a `dark` that is **not six hex digits** — `Color.setFromString` slices fixed offsets and stores whatever `parseInt` gives back, so `"4020"` loads a channel of `NaN`; and an `rgba2` or `rgb2` timeline on a slot with **no `dark` at all**, where the runtime allocates no dark colour and the first `state.apply` throws in the consumer's process. The keyed half is read by posing: the animation is stepped to each key's own time and the posed `color` and `darkColor` are compared against the hex the key states, to half a quantisation step (`1/510`). The detail names the slot, the value found and the value required. ⚠️ The required value is parsed **here** and not through `Color.fromString`, because a check that read it out of the parser it is checking would agree with that parser whatever it did. `compile.ts` refuses the third shape outright in a rig rigc builds; this is the same fact held against a skeleton it did not write. An `rgb2` key's light colour is compared over its three channels only: the light alpha is not its to state, and that it is left where it was is measured in the selftest (`S85`). **SKIP** when no slot declares a `dark` and no animation keys an `rgba2` or `rgb2` — there is then no two-colour tint to read back |
+| `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | both | a slot's `dark` (§3.3) or an `rgba2` / `rgb2` timeline (§4.4) that the runtime does not hold as the file states it. Three shapes, all of which parse in silence: a `dark` the slot reader **drops** — it takes the field through a truthiness test, so `""` is discarded without a word and the slot renders with one colour; a `dark` that is **not six hex digits** — `Color.setFromString` slices fixed offsets and stores whatever `parseInt` gives back, so `"4020"` loads a channel of `NaN`; and an `rgba2` or `rgb2` timeline on a slot with **no `dark` at all**, where the runtime allocates no dark colour and the first `state.apply` throws in the consumer's process. The keyed half is read by posing: the animation is stepped to each key's own time — at the key **as the runtime stores it**: spine-core keeps key times as 32-bit floats, so a key at `0.2` is posed at `0.20000000298…`, the later of the two, and not one float step before it, where a first key still shows the setup value and a stepped key the one before (a correct file was refused that way until [#771](https://github.com/firejune/rigc/issues/771)), and the posed `color` and `darkColor` are compared against the hex the key states, to half a quantisation step (`1/510`). The detail names the slot, the value found and the value required. ⚠️ The required value is parsed **here** and not through `Color.fromString`, because a check that read it out of the parser it is checking would agree with that parser whatever it did. `compile.ts` refuses the third shape outright in a rig rigc builds; this is the same fact held against a skeleton it did not write. An `rgb2` key's light colour is compared over its three channels only: the light alpha is not its to state, and that it is left where it was is measured in the selftest (`S85`). **SKIP** when no slot declares a `dark` and no animation keys an `rgba2` or `rgb2` — there is then no two-colour tint to read back |
 | `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | both | a **linked mesh** (§3.4) — `type: "linkedmesh"`, or a `type: "mesh"` carrying `source` — that also states `uvs`, `triangles`, `vertices`, `hull` or `edges`. The parser returns from the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so those keys are read by **nothing at all** and `setSourceMesh` fills the attachment with the source's arrays instead: the file says one mesh and every runtime draws another, in silence. The detail names the attachment by skin, slot and placeholder, every key it states, the `source` and where the parser looks for it — the two defaults spelled out, because an omitted `skin` is the **default** skin rather than the one the link is written in — and the shape the keys describe beside the shape the attachment loaded. ⚠️ **`width`/`height` are not part of this.** `setSourceMesh` overwrites both with the source's, so they are as dead at runtime — but the parser reads them (`:569-570`), the format carries them on a link and rigc emits them, so refusing them would refuse every link rigc writes (§3.4). `compile.ts` refuses the same shape outright in a rig rigc builds (§5.1); this is that fact held against a skeleton it did not write, and `ingest` reports it as `ATTACHMENT_LINK_GEOMETRY` ([INGEST §2.0](INGEST.md)). **SKIP** when no attachment in the skeleton takes its geometry from another — which is almost every skeleton, so a pass here means a link was read ([#710](https://github.com/firejune/rigc/issues/710)) |
-| `A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN` | both | an `rgb` or `alpha` timeline (§4.4) the runtime does not hold as the file states it, in one of two shapes that both parse in silence. **A channel keyed twice**: another colour timeline of the same slot in the same animation poses a channel this one poses — `rgba` beside `alpha` is the shape a converter leaves when it writes a separable `rgb` back as `rgba` next to the `alpha` it kept. Every colour timeline poses its channels at every time, the setup value before its first key included, so the one the file states later overwrites the other everywhere; the detail names both timelines, the channel, and which one survives. **A key not posed as written**: the animation is stepped to each key's own time and the posed r g b (for `rgb`, against the hex, to half a quantisation step) or alpha (for `alpha`, against `value`, whose absence the parser reads as 0) is compared — a colour that is not six hex digits loads as NaN, and a key whose time another key repeats is read by nothing. ⚠️ An `rgb` alone written as an `rgba` holding the setup alpha is **not** caught and cannot be from the file: it is a correct `rgba`, and the difference shows only under another track that moves the alpha. The loaded timeline class and the channels a separable timeline leaves alone are measured in the selftest (`S83`–`S85`) rather than here, because against the linked parser neither can come out wrong. The channel table is `SLOT_COLOR_CHANNELS` in `src/timelines.ts`, shared with the compiler's refusal and held to the runtime's own property ids (`S89`). **SKIP** when no animation keys an `rgb` or `alpha` — there is then no separable slot colour to read back |
-| `A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES` | both | a **numbered series** (§3.4.3, §4.13) that the runtime does not show as the file states it. Every shape below loads without a word, measured on spine-core 4.3.13 ([#729](https://github.com/firejune/rigc/issues/729)). **The block**: a `sequence` with no `count` (`readSequence` reads 0, and the attachment holds no region) or a `setup` at or past `count` (`Sequence.resolveIndex` clamps it to the last frame). **The keys**: a `mode` outside the seven — `hold`, `once`, `loop`, `pingpong`, `onceReverse`, `loopReverse`, `pingpongReverse` — loads as `hold`; an `index` that is fractional (`index << 4` truncates it) or past the end (clamped); an advancing mode at an effective delay of 0 (the parser carries a key's `delay` from the key before; `(time - keyTime) / 0` is Infinity and `Infinity \| 0` is 0, so it never advances); a timeline on an attachment that carries no block (the parser gives every region a one-region series, so every mode shows it). **The pose**: every key is stepped to mid-frame sample times — enough to wrap every mode — and the region the slot shows is held to the frame the file's own statement gives, the arithmetic of `SequenceTimeline.applyToSlot` and the names of `Sequence.getPath` transcribed rather than read off the loaded timeline, so the check is not the runtime agreeing with itself. Before the first key the frame is `setup`. ⚠️ A sample where the slot shows another attachment is not compared, because the runtime writes nothing there; a timeline with no comparable sample is counted in `stats.sequenceSamplesUnshown`. `compile.ts` refuses every one of these shapes in a spec (§5.1); this is them held against a skeleton it did not write. **SKIP** when no attachment carries a `sequence` block and no animation keys a `sequence` timeline |
+| `A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN` | both | an `rgb` or `alpha` timeline (§4.4) the runtime does not hold as the file states it, in one of two shapes that both parse in silence. **A channel keyed twice**: another colour timeline of the same slot in the same animation poses a channel this one poses — `rgba` beside `alpha` is the shape a converter leaves when it writes a separable `rgb` back as `rgba` next to the `alpha` it kept. Every colour timeline poses its channels at every time, the setup value before its first key included, so the one the file states later overwrites the other everywhere; the detail names both timelines, the channel, and which one survives. **A key not posed as written**: the animation is stepped to each key's own time — at the key **as the runtime stores it**: spine-core keeps key times as 32-bit floats, so a key at `0.2` is posed at `0.20000000298…`, the later of the two, and not one float step before it, where a first key still shows the setup value and a stepped key the one before (a correct file was refused that way until [#771](https://github.com/firejune/rigc/issues/771)), and the posed r g b (for `rgb`, against the hex, to half a quantisation step) or alpha (for `alpha`, against `value`, whose absence the parser reads as 0) is compared — a colour that is not six hex digits loads as NaN, and a key whose time another key repeats is read by nothing. ⚠️ An `rgb` alone written as an `rgba` holding the setup alpha is **not** caught and cannot be from the file: it is a correct `rgba`, and the difference shows only under another track that moves the alpha. The loaded timeline class and the channels a separable timeline leaves alone are measured in the selftest (`S83`–`S85`) rather than here, because against the linked parser neither can come out wrong. The channel table is `SLOT_COLOR_CHANNELS` in `src/timelines.ts`, shared with the compiler's refusal and held to the runtime's own property ids (`S89`). **SKIP** when no animation keys an `rgb` or `alpha` — there is then no separable slot colour to read back |
+| `A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES` | both | a **numbered series** (§3.4.3, §4.13) that the runtime does not show as the file states it. Every shape below loads without a word, measured on spine-core 4.3.13 ([#729](https://github.com/firejune/rigc/issues/729)). **The block**: a `sequence` with no `count` (`readSequence` reads 0, and the attachment holds no region) or a `setup` at or past `count` (`Sequence.resolveIndex` clamps it to the last frame). **The keys**: a `mode` outside the seven — `hold`, `once`, `loop`, `pingpong`, `onceReverse`, `loopReverse`, `pingpongReverse` — loads as `hold`; an `index` that is fractional (`index << 4` truncates it) or past the end (clamped); an advancing mode at an effective delay of 0 (the parser carries a key's `delay` from the key before; `(time - keyTime) / 0` is Infinity and `Infinity \| 0` is 0, so it never advances); a timeline on an attachment that carries no block (the parser gives every region a one-region series, so every mode shows it). **The pose**: every key is stepped to mid-frame sample times — enough to wrap every mode, and a `hold` key to its own time as the runtime stores it, a 32-bit float ([#771](https://github.com/firejune/rigc/issues/771)) — and the region the slot shows is held to the frame the file's own statement gives, the arithmetic of `SequenceTimeline.applyToSlot` and the names of `Sequence.getPath` transcribed rather than read off the loaded timeline, so the check is not the runtime agreeing with itself. Before the first key the frame is `setup`. ⚠️ A sample where the slot shows another attachment is not compared, because the runtime writes nothing there; a timeline with no comparable sample is counted in `stats.sequenceSamplesUnshown`. `compile.ts` refuses every one of these shapes in a spec (§5.1); this is them held against a skeleton it did not write. **SKIP** when no attachment carries a `sequence` block and no animation keys a `sequence` timeline |
+| `A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT` | both | an ik constraint resting at `mix` 0 that no animation keys **away from 0** (§4.9, §4.12). `IkConstraint.update` returns on `mix === 0`, so it sits in the update cache and moves nothing. The keys are read the way `A23`/`A36`/`A37` read theirs — every value the loaded timeline poses on its `mix` channel, Bezier samples included — so a timeline keying 0 only is no rescue: [measured] it poses every bone exactly where the same rig with no constraint does, and before [#765](https://github.com/firejune/rigc/issues/765) it passed. Live is the runtime's `!== 0`, so a negative mix is not refused. `ik constraint "C" has mix 0 at setup and none of the 1 animation keys its mix above 0; update() returns on mix 0, so "upper" never reaches for "goal" — rest it above 0, or key its mix above 0 in an animation`. **SKIP** when the skeleton declares no ik constraint |
+| `A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT` | both | a transform constraint none of whose mixes **for a property it drives** is away from 0 at setup or on any value an animation poses (§4.10, §4.12), or one whose `properties` name no `to` at all. A property is applied only when its own mix `!== 0`, and a key that omits a mix reads it as 1, so the six-mix early return of `TransformConstraint.update` would take a key of `mixRotate: 0` alone as a rescue — [measured] that key, and one keying `mixX` 1 on a rotate-only constraint, pose every bone exactly where no constraint does ([#765](https://github.com/firejune/rigc/issues/765)). A negative mix runs, and five transforms in the editor's example exports rest at −1. `transform constraint "C" drives rotate and has mixRotate 0 at setup, and none of the 1 animation keys its mix above 0; a mix is read only for a property the constraint drives, and update() skips each one at 0, so nothing ever moves "follower" — rest mixRotate above 0, or key its mix above 0 in an animation`. **SKIP** when the skeleton declares no transform constraint |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.

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/docs/SPEC_COVERAGE.md

@@ -739,6 +739,8 @@ This is the split Part 4(c) needs. **Spine-validity** = the file is wrong for an
 | `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | validity | a linked mesh, in either spelling, that also states `uvs`, `triangles`, `vertices`, `hull` or `edges` — keys the `source` branch returns before reading, so the file says one mesh and every runtime draws its source's |
 | `A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN` | validity | an `rgb` or `alpha` timeline beside another colour timeline of the slot that poses the same channel — the later in the file overwrites the other at every time — or a key of one the pose does not reproduce |
 | `A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES` | validity | a numbered series that loads as something other than what the file states — a `sequence` block with no `count` (0 regions) or a `setup` past the end (clamped), or a `sequence` key whose `mode` is outside the seven (read as `hold`), whose `index` is fractional or past the end, whose advancing mode runs at an effective delay of 0, or that steps an attachment with no block — and then the pose: every key sampled mid-frame, the region shown held to the frame the file's statement gives ([#729](https://github.com/firejune/rigc/issues/729)) |
+| `A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT` | validity | an ik constraint at `mix` 0 at setup that no animation keys away from 0 — `update()` returns on it, and the rig parses and moves nothing ([#765](https://github.com/firejune/rigc/issues/765)) |
+| `A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT` | validity | a transform constraint whose mixes for the properties it drives are all 0 at setup and on every value a key poses, or one that drives no property ([#765](https://github.com/firejune/rigc/issues/765)) |
 | `A13_MESH_BUDGET` | **renderer-profile** | >4 mesh slots, >80 triangles per mesh |
 | `A14_NO_FULL_FRAME_MESH` | **renderer-profile** | a mesh spanning the whole stage |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | **renderer-profile** | an overlay page that can never be transparent — no alpha channel and no `tRNS` chunk |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "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;
 }

package/src/validate.ts

@@ -25,6 +25,8 @@ import {
   type ConstraintTimeline,
   type CurveTimeline,
   DeformTimeline,
+  IkConstraintData,
+  IkConstraintTimeline,
   Inherit,
   isBoneTimeline,
   isConstraintTimeline,
@@ -48,6 +50,14 @@ import {
   TextureAtlas,
   type TextureAtlasRegion,
   type Timeline,
+  ToRotate,
+  ToScaleX,
+  ToScaleY,
+  ToShearY,
+  ToX,
+  ToY,
+  TransformConstraintData,
+  TransformConstraintTimeline,
 } from '@esotericsoftware/spine-core';
 // ⚠️ `src/` reaches outside itself for exactly two modules and this is one of
 // them, so it is already on `package.json`'s `files` allowlist — see CLAUDE.md.
@@ -208,6 +218,8 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
   A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN: 'validity',
   A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES: 'validity',
+  A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+  A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
 };
 
 /**
@@ -677,6 +689,31 @@ function isObj(v: unknown): v is Json {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
+/**
+ * The time to pose a key at so that the runtime is AT it: the later of the
+ * file's number and that number as spine-core stores it (issue #771).
+ *
+ * 🚨 Every timeline keeps its key times in a `Float32Array`
+ * (`Utils.newFloatArray`), and a key time the float cannot hold exactly is
+ * stored at the nearest one — for `0.2`, `0.20000000298…`, which is LATER than
+ * the double `0.2`. Stepped to the file's own number, a timeline is then just
+ * BEFORE its key: before a first key it writes the setup value (`time <
+ * frames[0]`), and past a stepped key it still holds the one before
+ * (`frames[i] > time`). That is a pose one float step from the key, not the
+ * key's — measured on the selftest's own `ingest_probe`, whose `alpha` key at
+ * 0.2 posed the setup 1.0 and was refused as `the key states value 0.4`.
+ *
+ * ⚠️ The later of the two rather than `Math.fround` alone: where the float
+ * rounds DOWN, the file's number is already past the stored key, and a runtime
+ * built without typed arrays stores the double itself — in both, the file's
+ * number is the one at or after the key. What a key time rounds to is the
+ * runtime's storage and not the file's statement, so a rule judging what a KEY
+ * states poses at the key; the rounding itself is nothing an author can repair.
+ */
+function atStoredKey(time: number): number {
+  return Math.max(time, Math.fround(time));
+}
+
 /**
  * The atlas region names one raw skin entry will make the loader look up — or
  * `null` when the file states a sequence this walk cannot predict.
@@ -3037,10 +3074,17 @@ export function validate(input: ValidateInput): ValidateReport {
      * A timeline naming no constraint is the physics family's global form and
      * `unnamedPhysicsReach` answers who it reaches; every other constraint
      * timeline names its one constraint by index.
+     *
+     * `live` is handed the channel as well as the value, because not every
+     * channel of every constraint timeline is a mix (issue #765): an ik frame is
+     * mix, softness, bend direction, compress and stretch, so a bend direction of
+     * +1 is not a key that switches anything on, and a transform frame carries
+     * six mixes of which only the ones for a property the constraint drives are
+     * ever read.
      */
     const keyedLive = <T extends CurveTimeline & ConstraintTimeline>(
       owns: (timeline: Timeline) => timeline is T,
-      live: (timeline: T, value: number) => boolean,
+      live: (timeline: T, value: number, channel: number) => boolean,
     ): Set<object> => {
       const reached = new Set<object>();
       for (const animation of data.animations) {
@@ -3048,7 +3092,7 @@ export function validate(input: ValidateInput): ValidateReport {
           if (!owns(timeline)) continue;
           let keysLive = false;
           for (let channel = 0; channel < timeline.getFrameEntries() - 1 && !keysLive; channel++) {
-            keysLive = curveChannelValues(timeline, channel).some((value) => live(timeline, value));
+            keysLive = curveChannelValues(timeline, channel).some((value) => live(timeline, value, channel));
           }
           if (!keysLive) continue;
           const reach =
@@ -3470,6 +3514,108 @@ export function validate(input: ValidateInput): ValidateReport {
       stats.sliderConstraints = sliders.length;
     });
 
+    // --- A47 / A48: an ik or a transform constraint muted for good ----------
+    //
+    // The question A23, A36 and A37 ask of their own kinds, asked of the two
+    // kinds editor exports use most (issue #765): a constraint that rests muted
+    // and that no animation switches on parses, sits in the update cache and
+    // moves nothing. [measured] on generated fixtures, 61 steps at 60 fps: an ik
+    // at `mix` 0 that nothing keys, one keyed to 0 only, a transform at every mix
+    // 0 that nothing keys and one keyed to 0 only each pose every bone exactly
+    // where the same rig with no constraint does (max |Δ| 0.000000), and all four
+    // gated green with 0 failures before these two existed.
+    //
+    // 🔑 **Live is the runtime's own test, `!== 0`, and not `mixLive`'s `> 0`.**
+    // `IkConstraint.update` returns on `mix === 0` and a transform's inner loop
+    // applies a property only when `to.mix(pose) !== 0`, so a negative mix runs.
+    // That is not a corner: [measured] five transform constraints across four of
+    // the editor's own example exports rest at mixX = mixY = −1, nothing keys
+    // them, and each moves its bones at setup against the same constraint with
+    // every mix 0. A `> 0` reading refuses all five. (`A36`/`A37` still read
+    // `> 0` — a path or slider resting negative is a question for their own card.)
+    //
+    // 🔑 **A transform mix is read only for a property the constraint drives.**
+    // The early return in `TransformConstraint.update` is over all six mixes, but
+    // it is not what decides whether anything moves: each `to` entry reads its own
+    // mix (`ToRotate.mix` is `mixRotate`, …). At setup the parser only reads a mix
+    // whose property is declared, so the two tests agree there — but a timeline
+    // key that omits a mix is read as 1 (`SkeletonJson.js`, every `getValue(…, 1)`),
+    // so a key of `mixRotate: 0` alone on a rotate-only constraint passes the
+    // six-mix test on five mixes nothing reads. [measured] that key poses every
+    // bone exactly where no constraint does, and so does one keying `mixX` 1 on
+    // the same constraint. So this reads the mixes of the declared `to` kinds,
+    // at setup and on every value a key poses.
+    const ikLive = (value: number): boolean => value !== 0;
+    /** A transform timeline's six channels, in frame order, and the `to` kind each one is the mix of. */
+    const TRANSFORM_MIXES = [
+      ['mixRotate', ToRotate],
+      ['mixX', ToX],
+      ['mixY', ToY],
+      ['mixScaleX', ToScaleX],
+      ['mixScaleY', ToScaleY],
+      ['mixShearY', ToShearY],
+    ] as const;
+    /** Which of the six channels `constraint` reads at all: the ones whose `to` kind it declares. */
+    const transformReads = (constraint: TransformConstraintData): boolean[] =>
+      TRANSFORM_MIXES.map(([, kind]) => constraint.properties.some((from) => from.to.some((to) => to instanceof kind)));
+    const ikSwitchedOn = keyedLive(
+      (timeline): timeline is IkConstraintTimeline => timeline instanceof IkConstraintTimeline,
+      // Channel 0 is `mix`; the other four are softness, bend direction, compress and stretch.
+      (_timeline, value, channel) => channel === 0 && ikLive(value),
+    );
+    const transformSwitchedOn = keyedLive(
+      (timeline): timeline is TransformConstraintTimeline => timeline instanceof TransformConstraintTimeline,
+      (timeline, value, channel) => {
+        const constraint = data.constraints[timeline.constraintIndex];
+        return constraint instanceof TransformConstraintData && transformReads(constraint)[channel] && value !== 0;
+      },
+    );
+
+    check('A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT', () => {
+      const constraints = data.constraints.filter((c) => c instanceof IkConstraintData);
+      if (!constraints.length) return skip('A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT', 'the skeleton declares no ik constraint');
+      for (const constraint of constraints) {
+        const mix = constraint.setupPose.mix;
+        if (ikLive(mix) || ikSwitchedOn.has(constraint)) continue;
+        fail(
+          'A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT',
+          `ik constraint "${constraint.name}" has mix ${mix} at setup and ${noneKeysItsMixAbove0(data.animations.length)}; ` +
+            `update() returns on mix 0, so ${constraint.bones.map((bone) => `"${bone.name}"`).join(' and ')} never ` +
+            `reach${constraint.bones.length === 1 ? 'es' : ''} for "${constraint.target.name}" — ${REST_OR_KEY_ITS_MIX}`,
+        );
+      }
+    });
+
+    check('A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT', () => {
+      const NAME = 'A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+      const constraints = data.constraints.filter((c) => c instanceof TransformConstraintData);
+      if (!constraints.length) return skip(NAME, 'the skeleton declares no transform constraint');
+      for (const constraint of constraints) {
+        const where = `transform constraint "${constraint.name}"`;
+        const reads = transformReads(constraint);
+        const pose = constraint.setupPose;
+        const read = TRANSFORM_MIXES.filter((_, i) => reads[i]).map(([field]) => field);
+        if (read.length === 0) {
+          // No `to` at all: no mix is ever read, so neither remedy below applies.
+          fail(
+            NAME,
+            `${where} drives no property — its \`properties\` name no \`to\` — so no mix it carries is ever read and it ` +
+              'moves nothing; declare the property it should drive',
+          );
+          continue;
+        }
+        if (read.some((field) => pose[field] !== 0) || transformSwitchedOn.has(constraint)) continue;
+        fail(
+          NAME,
+          `${where} drives ${read.map((field) => field.slice(3).replace(/^./, (c) => c.toLowerCase())).join(', ')} and has ` +
+            `${read.map((field) => `${field} ${pose[field]}`).join(', ')} at setup, and ` +
+            `${noneKeysItsMixAbove0(data.animations.length)}; a mix is read only for a property the constraint drives, and ` +
+            `update() skips each one at 0, so nothing ever moves ${constraint.bones.map((bone) => `"${bone.name}"`).join(', ')} — ` +
+            `rest ${read.length === 1 ? read[0] : `one of ${read.join(', ')}`} above 0, or key its mix above 0 in an animation`,
+        );
+      }
+    });
+
     // --- A40: two sliders on one property, and the later one erases the other -
     //
     // 🚨 The hole A37 leaves. Every clause above is INTRA-slider — it asks
@@ -4300,9 +4446,10 @@ export function validate(input: ValidateInput): ValidateReport {
           skeleton.setupPose();
           skeleton.update(0);
           skeleton.updateWorldTransform(Physics.reset);
-          state.update(time);
+          // At the key as the runtime stores it — see `atStoredKey` (#771).
+          state.update(atStoredKey(time));
           state.apply(skeleton);
-          skeleton.update(time);
+          skeleton.update(atStoredKey(time));
           skeleton.updateWorldTransform(Physics.update);
           const posed = skeleton.slots.find((s) => s.data.name === slotName)?.appliedPose;
           const light = posed?.color;
@@ -4472,7 +4619,9 @@ export function validate(input: ValidateInput): ValidateReport {
             skeleton.setupPose();
             skeleton.update(0);
             skeleton.updateWorldTransform(Physics.reset);
-            state.update(time);
+            // At the key as the runtime stores it, not one float step before
+            // it — see `atStoredKey` (issue #771).
+            state.update(atStoredKey(time));
             state.apply(skeleton);
             const posed = skeleton.slots.find((s) => s.data.name === slotName)?.appliedPose;
             if (!posed) {
@@ -4792,7 +4941,10 @@ export function validate(input: ValidateInput): ValidateReport {
                 skeleton.setupPose();
                 skeleton.update(0);
                 skeleton.updateWorldTransform(Physics.reset);
-                state.update(sample.time);
+                // A `hold` sample is AT its key, so it is posed at the key as
+                // the runtime stores it (`atStoredKey`); a mid-frame sample is
+                // half a delay from any key and is posed where it is.
+                state.update(sample.key >= 0 && sample.steps === 0 ? atStoredKey(sample.time) : sample.time);
                 state.apply(skeleton);
                 const pose = skeleton.slots[slotIndex].appliedPose;
                 const shown = pose.attachment;