spine-rigc 0.14.1 → 0.16.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "rigc",
+  "owner": {
+    "name": "firejune",
+    "url": "https://github.com/firejune"
+  },
+  "description": "rigc, the rig compiler for Spine, packaged as agent skills over the guides the npm package ships.",
+  "plugins": [
+    {
+      "name": "rigc",
+      "source": "./",
+      "description": "Author Spine 4.3 rigs with rigc: an entry skill with the install line and the build, validate, render, check and vote loop, plus routers for rigging, motion, faces and foreign skeletons, each linking the shipped guide that owns its rules.",
+      "homepage": "https://github.com/firejune/rigc#readme",
+      "repository": "https://github.com/firejune/rigc",
+      "license": "MIT",
+      "keywords": ["spine", "spine2d", "skeletal-animation", "rig", "compiler", "ai-agents"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "rigc",
+  "description": "Author Spine 4.3 rigs with rigc, the rig compiler that verifies its own output through a spine-core round-trip. Skills that route an agent to the shipped guide for the need at hand: the hierarchy, a motion, a face, or a skeleton somebody else authored.",
+  "author": {
+    "name": "firejune",
+    "url": "https://github.com/firejune"
+  },
+  "homepage": "https://github.com/firejune/rigc#readme",
+  "repository": "https://github.com/firejune/rigc",
+  "license": "MIT",
+  "keywords": ["spine", "spine2d", "skeletal-animation", "rig", "compiler", "ai-agents"]
+}

package/LICENSE

@@ -19,3 +19,12 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+THIRD-PARTY MATERIAL
+
+The licence above covers rigc's own code, documentation and art. It does not cover
+third-party material distributed alongside them - in particular the rendered
+reference frames under bench/reference/, which carry Esoteric Software's example
+image data and are governed by each example's own license.txt beside them:
+redistribution only with that file, and no commercial use. See NOTICE.md.

package/NOTICE.md

@@ -54,9 +54,11 @@ Two consequences worth stating plainly:
 ## Example assets
 
 The official Spine example projects are the yardstick this compiler is measured
-against. They are owned by Esoteric Software and are **not redistributed** in this
-repository: `scripts/fetch-examples.sh` downloads them into a gitignored
-`examples/` directory for local evaluation.
+against. They are owned by Esoteric Software. **The example projects themselves are
+not committed to this repository**: `scripts/fetch-examples.sh` downloads them into a
+gitignored `examples/` directory for local evaluation. What this repository *does*
+commit is its own rendered frames of them, under the grant the examples' own licence
+files carry — *Rendered reference frames*, below.
 
 Each example directory upstream carries its own `license.txt`, so the terms are
 per-directory rather than repository-wide. Verified on 2026-08-22 against
@@ -87,7 +89,9 @@ the copyright line:
 So, for this repository's purposes:
 
 - **Images** — redistributable only with the accompanying `license.txt`, and
-  **non-commercial only**. That is why they are fetched rather than committed.
+  **non-commercial only**. That is why the example projects are fetched rather than
+  committed, and why the rendered frames this repository *does* commit each carry a
+  verbatim copy of that file beside them — *Rendered reference frames*, below.
 - **Project files** (`.spine`, and the exports derived from them) — **public
   domain**, usable as the basis for derivative work. This is what makes the
   examples usable as a structural yardstick.
@@ -95,3 +99,31 @@ So, for this repository's purposes:
   grant its siblings carry does not exist for it — there is no licence file to
   accompany its images with. `scripts/fetch-examples.sh` prints a warning naming
   it. Treat its images as not redistributable.
+
+### Rendered reference frames
+
+`bench/reference/` contains **1,293 PNG frames rendered by this project** from the
+examples' own exports: `bench/render_reference.ts` loads each example's `export/`
+out of the gitignored `examples/`, poses it with `spine-core`, and rasterises each
+posed attachment.
+
+A rendered frame contains those images' pixels, so committing one **is**
+redistribution — and each example's `license.txt` grants exactly that, *"as long as
+they are accompanied by this license file"*. So **a verbatim copy of the relevant
+`license.txt` sits at each example root** under `bench/reference/`, put there by
+`render_reference.ts` rather than left to memory; all eight are present. The
+**non-commercial** condition in that same file rides along with those images, and
+`LICENSE` says so — rigc's MIT grant covers rigc's own code, documentation and art,
+and does not extend to this material.
+
+⚠️ **`7-anticipation` is excluded, and mechanically so.** With no upstream
+`license.txt` there is no grant to rely on, so its frames are never committed:
+`render_reference.ts` writes them only into a gitignored directory, refuses any
+`--out` inside the repository that `git check-ignore` will not accept, fails closed
+if git cannot answer, and drops a `LOCAL-ONLY.txt` beside them in place of the
+licence file that does not exist.
+
+`bench/reference/` is repository material — it is not in `package.json`'s `files`
+list, so it is not part of the published npm package. The full reasoning, and the
+per-rung framing behind it, is in
+[`bench/reference/README.md`](https://github.com/firejune/rigc/blob/main/bench/reference/README.md).

package/README.md

@@ -18,7 +18,7 @@ their own work.
   <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-demo.gif" alt="Loose part PNGs assembling themselves into a character that breathes, blinks and waves" width="600" />
 </p>
 
-<p align="center"><em>Fourteen hand-drawn part PNGs, one rig spec, one motion spec — the assembly,
+<p align="center"><em>Fourteen part PNGs drawn from scratch for this repo, one rig spec, one motion spec — the assembly,
 the breathing and the wave are all rigc-compiled Spine animations, rendered with
 <code>rigc render</code>.</em></p>
 
@@ -73,6 +73,22 @@ the following is a restatement of Esoteric Software's terms, not a term of ours:
 
 See [NOTICE.md](NOTICE.md) for the full notice.
 
+📐 **What of Esoteric Software's is in this repository, and under what grant.** No
+example asset is committed: `bun run fetch-examples` downloads the example projects
+into a gitignored `examples/`. What *is* committed is `bench/reference/` — 1,293 PNG
+frames **this project renders** from those examples' own exports, so a frame carries
+those images' pixels and committing one **is** redistribution. Each example's own
+`license.txt` permits exactly that, *"as long as they are accompanied by this license
+file"*, and a verbatim copy of it sits at each example root here — all eight, written
+there by the render script rather than left to memory. The same file's
+**non-commercial** condition rides along with those images, and
+[LICENSE](LICENSE) says so: rigc's MIT grant covers rigc's own code, documentation
+and art, not this material. `7-anticipation` publishes no `license.txt` upstream, so
+no such grant exists for it and its frames are never committed — they render only
+into a gitignored directory, enforced by `git check-ignore`. Full reasoning:
+[`bench/reference/README.md`](https://github.com/firejune/rigc/blob/main/bench/reference/README.md)
+(repository material, not in the npm package).
+
 The problem rigc is aimed at is narrow. An agent asked to author a rig has no way
 to tell whether it succeeded: Spine's JSON parser accepts a great deal of nonsense
 without a murmur — a constraint in the 4.2 shape simply vanishes, a `size:` that
@@ -114,10 +130,34 @@ the CLI in place); the two are interchangeable — `rigc build …` is
 `bun cli.ts build …`.
 
 Two commands are repository workflows rather than package ones: `bench` and
-`check` measure against Spine's official example projects and the reference
-frames rendered from them, which are fetched rather than redistributed (see
-[NOTICE.md](NOTICE.md)). They need a clone and `bun run fetch-examples`, and say
-so by name when the corpus is absent.
+`check` measure against Spine's official example projects — fetched, never
+committed — and against reference frames this project renders from them, which
+**are** committed, each example's own `license.txt` beside them under the
+redistribution grant those files carry; the images stay **non-commercial only**.
+The reasoning is in
+[`bench/reference/README.md`](https://github.com/firejune/rigc/blob/main/bench/reference/README.md)
+and the terms in [NOTICE.md](NOTICE.md). Both commands need a clone and `bun run
+fetch-examples`, and say so by name when the corpus is absent.
+
+### Install it into your agent
+
+The guides under [Documentation](#documentation) also ship as
+[Agent Skills](https://agentskills.io) — `skills/<name>/SKILL.md`, in this
+repository and in the npm package — so an agent finds rigc the way it finds its
+other tools. Each skill is a router and nothing more: when to load it, the
+non-negotiables in a line apiece, and a link to the guide that owns every rule, so
+a rule keeps living in exactly one place. The repository is also a Claude Code
+plugin marketplace:
+
+```shell
+/plugin marketplace add firejune/rigc
+/plugin install rigc@rigc
+```
+
+With the package already installed, `claude --plugin-dir node_modules/spine-rigc`
+loads the same skills without a marketplace. The plugin carries no version of its
+own — `/plugin update` follows `main` commit by commit, and the only version on
+disk stays the one in `package.json`.
 
 ## First rig in ten minutes
 
@@ -386,7 +426,7 @@ limits: [AUTHORING.md §11](docs/AUTHORING.md). The parts it refuses because
 something is drawn over them are `rigc chainfit`'s, once a candidate exists —
 [§12](docs/AUTHORING.md).
 
-## The gallery — five complete rigs over art that ships with them
+## The gallery — six complete rigs over art that ships with them
 
 Each directory in [`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) is
 one rig spec, one motion spec and the PNGs they name, small enough to read in one
@@ -402,6 +442,7 @@ was verified, and what writing it cost. Repository material: a clone and
 | [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex) | **`contour` meshes** | A swallow-tailed banner and a serrated leaf: four meshes traced off their own alpha, waved by bone timelines and rippled by a `deform` |
 | [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride) | `path` attachments + **path constraints** | A trolley coasting down a drawn rail and rolling back, driven by a `position` timeline, with `groups` + `stagger` keying the wheels and the ears |
 | [`gallery/portrait`](https://github.com/firejune/rigc/tree/main/gallery/portrait) | **deform `transform`** + `derive` group tracks | A 2.5D head turn: two meshes and six feature bones all keyed from one stated expression, `dx = x(cos t − 1) − z·sin t`, with the depths in the spec rather than a README |
+| [`gallery/nod`](https://github.com/firejune/rigc/tree/main/gallery/nod) | the **`pitch`** and **`wave`** transform kinds | A head bowing and two lop ears rippling, on three meshes each laid out for the closed form that moves it — a fold angle solved for before authoring, and a shear whose winding no amplitude can reverse |
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-scene.gif" alt="A portrait rig breathing, glancing aside, then turning its head in 2.5D — hair and features sliding at different depths" width="600" />
@@ -409,10 +450,17 @@ was verified, and what writing it cost. Repository material: a clone and
 
 <p align="center"><em>The portrait rig playing its three animations in one take — the turn is
 the shot: both silhouette edges move apart, which a flat slide cannot do, because every
-feature carries its own depth. Scene direction of this kind was Live2D's territory; the
-split was authoring cost, and the cost is now one stated expression per key. Compiled and
+feature carries its own depth. Scene direction of this kind is authorable on plain Spine
+4.3 — no plugin, no runtime patch — and the split was authoring cost rather than runtime
+capability; the cost is now one stated expression per key. Compiled and
 rendered entirely by the published package.</em></p>
 
+🎞️ **How the three films on this page were made** is kept with them, one directory per
+film in [`films/`](https://github.com/firejune/rigc/tree/main/films) — a `run.sh` that
+names every step, the assembler that cuts the shots and draws the type, and a README
+saying what the film claims and which tool printed each figure on screen. Repository
+material, like the gallery: a clone runs them.
+
 ## Commands
 
 Every command takes its paths explicitly. `rigc <command> --help` prints its flags, and
@@ -421,7 +469,7 @@ commands take it and what its default is.
 
 | Command | Does |
 | --- | --- |
-| `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained |
+| `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
 | `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 |
@@ -442,7 +490,7 @@ and `bun run fetch-examples`. The reasoning behind all three is in
 
 `build` and `validate` both default to `--profile spine` — the 25 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 39: the other 14 are one renderer's policy and one canvas budget's, and they
+adds all 40: the other 15 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, so reach for that profile when
 you are shipping into *that* project rather than to be thorough. A report always names
 the profile it ran and lists what that profile left out.
@@ -464,7 +512,7 @@ the art. Its shape is under
 | 📥 **[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 36 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 40 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 |
 
 ## Why you can trust the output
@@ -474,11 +522,12 @@ rigc is measured against **Spine's own official example projects** — the
 as the graduation exam.
 
 🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
-spineboy graduation exam are cleared and hold under the current gate, **v2.3**, every clause PASS or SKIP:
-worst attributable slot drift **5.55 px** against a 6.0 px bar, and **0 of 124**
-frame-change disagreements. Recompiling the same spec in a different session
-reproduced every field of the measurement record **to the digit**. The rungs stay
-in place as regression gates.
+spineboy graduation exam are cleared and hold under the current gate, **v2.4**, every clause PASS or SKIP:
+worst attributable slot drift **5.5550 px** against a 6.0 px bar — a **1.0801×**
+margin, the thinnest of the ladder's **G2** figures, and **G5**'s 1.0376× is thinner
+still — and **0 of 124** frame-change disagreements. Recompiling the same spec in a
+different session reproduced every field of the measurement record **to the digit**.
+The rungs stay in place as regression gates.
 
 🗓️ **One rung's pass was withdrawn and restored on 2026-09-02, and both are dated
 facts.** `check`'s extent tolerance ([PR #254](https://github.com/firejune/rigc/pull/254))
@@ -489,11 +538,15 @@ clause questions that exposed, as **v2.3**: a read-down names the framing of its
 evidence, and a slot whose attributability is **measured** to be capped below the bar
 reads down when everything observable about it is independently verified strict. That
 rung's third attempt clears on those grounds, on the candidate it already had.
-**Rungs 1–6 and 8 and the graduation exam were unaffected throughout**: each reproduces
-its gated figures to the digit, and the 5.55 px and 0-of-124 figures above are among
-them. Both verdicts, and the sweep of every candidate under the new gate, are in
+**Rungs 1–6 and 8 and the graduation exam were unaffected throughout**: each keeps its
+pass on the clause, and recompiling a stored candidate reproduces its record **to the
+digit within one gate**. Across an instrument change the digits do move, and the
+record says where — the graduation **G2** figure went 5.5491 → 5.5544 → **5.5550 px**
+over the #301 sampler repair and v2.4's adoption of the re-rendered reference basis,
+while **0 of 124** held throughout. Both verdicts, and the sweep of every candidate under the gate of the day, are in
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md)'s *PR #254 instrument re-inspection* and *gate-v2.3
-re-inspection*.
+re-inspection*; the standing figures quoted above are from its *gate-v2.4
+re-inspection*, which is the current sweep.
 
 ⚠️ **What that certifies, stated exactly.** That **the tool, the guide and the
 protocol reach the bar across a bounded series of honest attempts, each residual
@@ -502,6 +555,17 @@ predecessor's specs under the run protocol's inheritance clause. It is **not**
 that an agent authors a spineboy-scale rig from the brief alone in one run: the
 ladder has not demonstrated that, and each row records which of the two it is.
 
+🧪 **A separate series measures that harder question, and it has not been kind.**
+From-zero attempts at spineboy — no inherited specs — have landed at **18.2, 18.8,
+19.57, 7.86, 9.33 and 18.98 px** worst drift against the 6.0 px bar, a spread with no
+monotone trend, and the two most recent — both **2026-09-03**, after the ladder's
+2026-08-28 completion — are recorded 🔴 **FAIL**. They move no rung and reopen nothing —
+a from-zero run is a tooling-progress measurement rather than a re-climb, which is
+why the certification above is scoped to tool + guide + protocol. One of those
+attempts states the residual in its own words: *"in motion it is not at editor
+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 40 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).

package/cli.ts

@@ -727,9 +727,10 @@ function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
   const packing = flags.pack !== undefined;
-  // Three combinations are refused rather than silently resolved, because in each
+  // Two combinations are refused rather than silently resolved, because in each
   // one the two flags disagree about a single question and there is no answer
-  // that is not a guess about which the caller meant.
+  // that is not a guess about which the caller meant. (There were three until
+  // issue #266 — see the note below the second.)
   if (packing && opts.atlasInPath !== undefined) {
     throw new UsageError(
       '--pack and --atlas-in are opposite directions through the same door: --pack MAKES an atlas out of the ' +
@@ -742,13 +743,16 @@ function cmdBuild(flags: Record<string, string>): void {
         'the loose part PNGs, which a packed atlas does not reference. Drop --copy-images',
     );
   }
-  if (packing && profile === 'spine-html') {
-    throw new UsageError(
-      "--profile spine-html asserts one part per page (A06's full-page coverage clause), which is rigc's unpacked " +
-        'convention and exactly what --pack stops being true. A packed atlas is valid Spine — build it under the ' +
-        'default --profile spine',
-    );
-  }
+  // The copy itself happens after the gate (below). The header has to know NOW,
+  // because the skeleton text the gate reads is the skeleton text that is written
+  // — `skeleton.images` says where the parts will be (issue #370).
+  if (flags['copy-images'] !== undefined) opts.copyImages = true;
+  // `--pack --profile spine-html` used to be the third refusal here, because
+  // A06's coverage clause was "one part per page" flat and a legitimate pack
+  // arrived at the gate reading as a defect. Since issue #266's second follow-up
+  // that clause is "one part per page OR a tiling page", so the combination is
+  // now a build like any other — and it is the only one that puts the renderer's
+  // own rulebook over shared-page sampling.
   if (!packing) {
     for (const name of ['page-size', 'padding'] as const) {
       if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
@@ -2248,12 +2252,13 @@ function cmdExplain(flags: Record<string, string>): void {
 const FLAG_MEANINGS: Record<string, string> = {
   rig: 'the rig spec — skeleton structure',
   motion: 'the motion spec — time',
-  out: 'directory for skeleton.json + skeleton.atlas; atlas page paths are written relative to it',
+  out: 'directory for skeleton.json + skeleton.atlas; atlas page paths and skeleton.images are written relative to it',
   images: "override the rig spec's own images directory (relative to your working directory)",
   manifest: 'a cut manifest, for a rig with measured art behind it; a foreign skeleton has none',
   'copy-images':
     'also copy every referenced page PNG into --out and rewrite the atlas to the copies, so the directory is ' +
-    'self-contained enough to zip or commit on its own (default: page paths still point at the source art)',
+    'self-contained enough to zip or commit on its own, and point skeleton.images at --out itself so the editor finds ' +
+    'the parts beside the skeleton on import (default: page paths still point at the source art)',
   pack: 'arrange every part PNG onto shared atlas page(s) written into --out as real PNGs, instead of one page ' +
     'per part. Lossless: every region is a byte-for-byte copy and nothing is resampled, trimmed or rotated ' +
     '(default: one part, one page, pointing at the source art)',