spine-rigc 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 firejune (Joon Kyoung)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

package/NOTICE.md

@@ -0,0 +1,76 @@
+# Third-party notices
+
+## Spine Runtimes
+
+This project depends on `@esotericsoftware/spine-core`, part of the
+[Spine Runtimes](https://github.com/EsotericSoftware/spine-runtimes),
+Copyright (c) 2013-2025 Esoteric Software LLC, licensed under the
+[Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license).
+
+Key obligation that propagates to users of this project: integration of the Spine
+Runtimes into software (including via this compiler, which links spine-core to
+validate what it emits) is permitted **provided that each user of the resulting
+product obtains their own Spine Editor license**, and any redistribution includes
+the Spine Runtimes license and copyright notice.
+
+### What that means for rigc, as a chain of facts
+
+rigc's own code is MIT (see `LICENSE`). The following is a restatement of Esoteric
+Software's terms, not a licence term of this project:
+
+1. rigc's output **is Spine skeleton data**.
+2. Playing Spine skeleton data in a product requires **a Spine Runtime**.
+3. The Spine Runtimes License requires **each user of such a product to own a Spine
+   Editor license**.
+4. rigc **links `spine-core`** itself — validation is not optional and cannot be
+   switched off — so the same obligation applies to running rigc at all.
+
+> **Using rigc, or shipping rigc's output in a product, requires a Spine Editor
+> license.** rigc does not change that requirement in either direction: it neither
+> creates one where none existed nor removes one that did. It is not a route around
+> the editor licence.
+
+## 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.
+
+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
+`spine-runtimes` branch `4.3`:
+
+| Example               | `license.txt` | Copyright line                                  |
+| --------------------- | ------------- | ----------------------------------------------- |
+| `1-weight-and-mass`   | present       | (c) 2021-2025, Esoteric Software LLC            |
+| `2-the-12-principles` | present       | (c) 2021-2025, Esoteric Software LLC            |
+| `3-timing-and-spacing`| present       | (c) 2021-2025, Esoteric Software                |
+| `4-wave-principle`    | present       | (c) 2021-2025, Esoteric Software LLC            |
+| `5-squash-and-stretch`| present       | (c) 2021-2025, Esoteric Software                |
+| `6-arcs`              | present       | (c) 2022-2025, Esoteric Software                |
+| `7-anticipation`      | **absent**    | —                                               |
+| `8-follow-through`    | present       | (c) 2024-2025, Esoteric Software                |
+| `spineboy`            | present       | (c) 2013, Esoteric Software LLC                 |
+
+Every `license.txt` above states the same two terms verbatim, differing only in
+the copyright line:
+
+> The images in this project may be redistributed as long as they are accompanied
+> by this license file. The images may not be used for commercial use of any
+> kind.
+>
+> The project file is released into the public domain. It may be used as the basis
+> for derivative work.
+
+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.
+- **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.
+- ⚠️ **`7-anticipation` has no `license.txt` upstream**, so the redistribution
+  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.

package/README.md

@@ -0,0 +1,558 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="rigc - Rig compiler for Spine" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/spine-rigc"><img src="https://img.shields.io/npm/v/spine-rigc.svg?style=flat-square&color=FF6B4A" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/spine-rigc"><img src="https://img.shields.io/npm/dm/spine-rigc.svg?style=flat-square&color=A855F7" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
+</p>
+
+**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.
+
+## What rigc is, and what it is not
+
+rigc emits **Spine's own skeleton data format**. That is the whole positioning, and
+it cuts both ways:
+
+- The output loads in any Spine runtime, and it **imports into the Spine editor**.
+  A compiled rig is a starting point on a timeline, not a finished shot — **an AI
+  drafts, a human refines in the editor**. rigc is complementary to the editor. It
+  is not a replacement for it, and it is not a way around one.
+- rigc **links `@esotericsoftware/spine-core`** to validate what it emits — the
+  round-trip through the official parser is the only reason its output can be
+  trusted at all. So the [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license)
+  applies to rigc exactly as it applies to any other runtime integration.
+
+### Licensing, stated plainly
+
+rigc's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine, and
+the following is a restatement of Esoteric Software's terms, not a term of ours:
+
+1. rigc's output **is Spine skeleton data**.
+2. Playing Spine skeleton data in a product requires **a Spine Runtime**.
+3. The Spine Runtimes License requires **each user of such a product to own a Spine
+   editor licence**.
+4. rigc **links `spine-core`** itself, so the same obligation covers running rigc.
+
+> **Using rigc, or shipping rigc's output in a product, requires a Spine editor
+> licence.** rigc does not change that requirement in either direction — it neither
+> adds one nor removes one. If you were going to need an editor licence to ship a
+> Spine animation, you still do; rigc is not a route around it.
+
+See [NOTICE.md](NOTICE.md) for the full notice.
+
+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
+disagrees with the PNG collapses every UV, a four-number curve array yields NaN,
+a mesh whose vertex count happens to equal its UV count silently loses its bone
+weights. Every one of those loads clean, plays, and is wrong. rigc's answer is to
+make the failure legible: compile from a spec, round-trip through the real parser,
+run a list of named assertions, and **write nothing unless all of them are green.**
+
+## The yardstick
+
+The measure of whether this works is **Spine's own official example projects** —
+the `1-weight-and-mass` … `8-follow-through` series as a difficulty ladder (one
+animation principle per rig, in roughly ascending order), and **spineboy as the
+graduation exam**. The question is structural and per-frame: given the same source
+art and a spec, does a compiled rig match the official export in bone hierarchy,
+timeline shape, mesh topology and posed vertex positions?
+
+`scripts/fetch-examples.sh` downloads those projects into a gitignored `examples/`
+directory (they are not redistributed here — see [NOTICE.md](NOTICE.md) for the
+per-example licence terms).
+
+### Comparing a rig against a reference — `rigc diff`
+
+```bash
+bun cli.ts diff candidate.json reference.json [--json report.json]
+```
+
+`diff` reads two skeletons and reports a ratio per **measure**, grouped into six
+sections — bones, slots, attachments, constraints, animations, events — and it
+does **not** combine them into a score. A single "87% match" cannot tell a rig
+with the right skeleton and the wrong timing apart from a rig with the right
+timing and the wrong skeleton, and those are opposite diagnoses.
+
+Three properties the measures are built to have:
+
+- **`diff X X` is 1.000 on every measure.** A comparison tool that cannot
+  recognise identity is reporting noise, and noise looks like a small honest gap.
+  The selftest asserts it.
+- **A difference moves as few measures as possible.** Reordering two slots moves
+  `slots.order` and nothing else — not the slot-to-bone bindings, not the setup
+  attachments — so the report says *where* a rig is wrong, not just *how much*.
+  Each selftest case names the exact set of measures its edit may disturb.
+- **Name-agnostic figures sit beside name-matched ones.** A candidate that builds
+  the right tree under its own bone names scores 0 on `bones.parent_by_name` and
+  1.000 on `bones.depth_histogram` and `bones.degree_sequence`. Reporting only the
+  first calls a correct rig a total failure; reporting only the second calls any
+  14-bone tree a match. That holds at the section level too: `bones` and `slots`
+  are the two sections whose measures are mostly name-keyed, so each reports **two
+  figures**, and the pair is the finding —
+
+  ```
+  bones 0.567 (name-matched) · 1.000 (name-agnostic)
+  ```
+
+  reads *"the tree is right and the vocabulary is different"*, which the single
+  mean on its own could not say. They are two comparisons with their own measure
+  sets rather than two halves of one; the name-matched figure is unchanged, so
+  older reports stay comparable. `sections[].nameAgnostic` in the JSON lists them.
+
+An assertion or measure with nothing to compare reports its `total` as 0 and says
+so, exactly as the validator's SKIP does — a vacuous 1.000 that looks earned is
+the same false green in a different costume.
+
+### Checking a rig against the pictures — `rigc check`
+
+```bash
+bun cli.ts check --candidate path/to/spine --frames bench/reference/3-timing-and-spacing
+```
+
+⭐ **Neither the gate nor `diff` can see a wrong animation.** The gate checks
+validity: it parses the skeleton, steps every animation and refuses anything
+degenerate, and it has no opinion about whether the animation is the one that was
+asked for. `diff` checks structure: a reversed easing is the same timeline, the
+same key count and the same curve kind. Three honest ladder runs have now produced
+**zero** validator FAILs between them, and one of them shipped a build in which
+every easing in the file was reversed — green, and sincerely reported as done.
+
+`check` is the instrument for that. It renders the candidate with the same
+rasteriser that drew the reference frames, onto the same pixel grid, and reports
+per animation and per frame:
+
+- **MAE over the union alpha** — the mean absolute RGB difference over the pixels
+  either side covers, 0..255. The whole-frame figure is printed beside it and never
+  instead of it: most of a frame is background on both sides, so that number is
+  small for every candidate and the gap between a good one and a bad one smaller
+  still.
+- **The framing** — where the candidate's drawn pixels sit against the reference's,
+  as a scale, an offset and a residual. It is printed first because it is upstream
+  of everything else: get it wrong and the error arrives disguised as motion.
+- **Per-frame change** — how many pixels each side moved since **its own** previous
+  frame, compared against each other. It is the only measure here that looks at the
+  relation between two frames rather than at one, and it is what catches a held pose
+  the candidate does not hold, or a one-frame event that never fired: both are cheap
+  in every individual frame and invisible to an aggregate.
+- **Per-slot drift** — where each of the candidate's own slots landed against the
+  reference frame, in pixels. MAE says *how wrong*; a slot's drift says *which
+  part, which way, how far*. Where the reference merged two parts into one blob —
+  the trap [AUTHORING §8](docs/AUTHORING.md) opens with — the slot is
+  template-matched against its own rendered pixels instead, with a confidence; and
+  where nothing inside the distance that slot could plausibly have moved matches
+  it, the answer is **no match** rather than a number about some other part.
+
+🔒 **It never reads the reference skeleton.** It opens the candidate and PNG
+frames, and nothing else: every reference-side read goes through one guard that
+refuses a path which is not a `.png` or the frame set's `frames.json`, and the
+selftest makes that guard fire. That is what lets `check` sit *inside* an
+authoring loop where `bench` cannot — running it as often as you like does not
+stop a run being an authoring run.
+
+The candidate is framed **by its own drawn pixels**, not by the reference's world
+box. A candidate is authored in its own coordinate system and under the ladder's
+honesty rule could not be authored in any other, so both sides are measured the
+same way — the content box of what each actually draws — and one similarity
+transform, fitted by least squares over every edge of every frame, carries the
+candidate's onto the reference's. Two skeletons depicting the same shot land on the
+same pixels whatever coordinates they were authored in, an invisible transparent
+margin cannot move the result, and no single quad corner in a single frame can set
+the scale for a run.
+
+There is no pass mark, for the same reason `diff` has none.
+
+### Benchmark ladder — the rungs, and where they stand
+
+**[docs/LADDER.md](docs/LADDER.md) is the live ledger**: the rung order
+(blockers → rung 3 first → 1 · 2 · 4 · 5 → 6 → 8 → 7 → spineboy), what each
+rung gates on, how a rung is scored, the honesty rule that keeps the reference
+export away from the authoring agent, and a status table. Run one with:
+
+```bash
+bun cli.ts bench 3 --candidate path/to/candidate/spine
+```
+
+`bench` validates the candidate under `--profile spine`, diffs it against that
+rung's reference export, and prints both. It exits non-zero only when validation
+fails: the diff has no threshold, because there is no rung score. Add
+`--frames <dir>` and it folds in the `check` table below, so a ladder row carries
+fidelity as well as structure.
+
+#### What the rungs need
+
+[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md) surveys the full Spine 4.3 export surface against what
+rigc emits and against what the nine examples measurably use (`bun run bench:usage` regenerates the
+counts). Three blockers sat *before* rung 1: **B1**, the bone tree was code in `archetype.ts` rather
+than data, so no example could be expressed at all; **B2**, `A16`'s regex rejected the `"4.3.75-beta"`
+that every example declares; and **B3**, every example ships a **packed** atlas (13–50 regions per
+page) against rigc's one-part-per-page model, which `A06` enforced unconditionally. **B1 and B2 are
+closed**; B3's validator half is (the packed-atlas clauses live behind `--profile`, above) and its
+emitter half — no packer, no atlas importer — is not. Ordered gap list in Part 4 of that document;
+live status, and B1's proof, in [docs/LADDER.md](docs/LADDER.md).
+
+## What exists today
+
+**Inputs — three files, one domain each.** Only the middle one is required.
+
+- A **cut manifest** (`FaceManifest` in [`src/types.ts`](src/types.ts)) owns
+  **measured art**. Crop rectangle, the base plate, one entry per part with its
+  offset and size, mask polygons, the state machine, bone anchors, and — for a
+  joint cut — the entry point, the insertion axis (`deg` in screen degrees plus a
+  `unit` vector, cross-checked against each other), stroke amplitudes and any
+  measured ceilings. The compiler **never re-measures art**: every number here is
+  produced by a measuring tool or by the pipeline that cut the plates, and rigc
+  only reads it. **Optional** — a skeleton with no measured art behind it (any of
+  the benchmark examples) has none.
+- A **rig spec** (`RigSpec` in [`src/rig.ts`](src/rig.ts), `spec: "rigc-rig/1"`)
+  owns **skeleton structure**: bones, slots, skins and their attachments, the 4.3
+  typed `constraints` array, and the invariants the emitted JSON cannot state
+  about itself. Its vocabulary is deliberately **Spine's own** — same concepts,
+  same field names, same defaults, cited to `SkeletonJson.ts` line numbers — so an
+  agent that has read Spine's documentation can author one without learning a
+  second vocabulary. rigc's additions sit on top and are namespaced: `from` on a
+  bone takes its position from the manifest instead of a literal that would drift
+  away from the art; `image` on an attachment names a PNG and rigc measures it;
+  `generator` on a mesh invokes a builder from `src/mesh.ts`; `invariants` carries
+  the axis bone, the forbidden parentage, the mesh budget.
+- A **motion spec** (`MotionSpec`, `spec: "rigc-motion/1"`) owns **time**: the rig
+  it was authored against, named easing handles, setup overrides, a physics tuning
+  table, and the animations — each with a declared duration, a loop flag, its
+  tracks, and optionally a `drawOrder` timeline (the one timeline that names no
+  target, so it sits on the animation rather than in `tracks`).
+
+**Outputs — two files per cut**, written to the cut's `out` directory:
+
+- `skeleton.json` — Spine **4.3** skeleton data. Bones, slots in draw order, one
+  skin, animations, and constraints in the 4.3 single `constraints` array.
+- `skeleton.atlas` — a **one-part-per-page** atlas: every region covers its whole
+  page, `pma: false`. That convention is what makes the region/attachment/filename
+  join key checkable exactly rather than by convention.
+
+**Where the three meet.** A manifest part joins a rig slot by its `rig_slot` field
+(falling back to `slot`), and that slot's position in the rig's `slots` array **is**
+the draw order — a manifest whose `draw_order` numbers disagree is a compile error
+rather than a silent overrule. A slot filled by both a manifest part and a rig skin
+is likewise refused, as is a setup pose declared in both the rig and the motion
+spec: one fact, one author. A missing anchor is a compile error by design, so that
+copying another cut's numbers is not the path of least resistance.
+
+Two things are code and stay code, because neither is a table of numbers: the
+**mesh generators** in [`src/mesh.ts`](src/mesh.ts), which encode a deformation
+model (what is pinned, what may move, how authority falls off), and the
+**coordinate contract** in [`src/transform.ts`](src/transform.ts).
+
+### The validator
+
+[`src/validate.ts`](src/validate.ts) parses the emitted artifacts with `spine-core`
+and then runs 32 named assertions over the loaded skeleton. Each one exists because
+the failure it catches is **silent**: the file loads, animates, and lies.
+
+Assertions whose data is absent are reported as **SKIP**, never folded into the pass
+count — an assertion with nothing to check has not checked anything.
+
+#### Profiles — "wrong" versus "not how we do it here"
+
+Not all 32 rules are about Spine. Some are about **spine-html**, the renderer this
+compiler was built to feed, and about one project's frame budget; they fire on real,
+correct, editor-produced Spine data, because the official example projects carry
+clipping attachments, unweighted meshes, 116-triangle meshes and packed atlases —
+all valid, none of them things spine-html will draw. Others are about **rigc's own
+rigs** and mean nothing at all on a skeleton rigc did not compile — they read the
+rig spec's `invariants` block, and they **SKIP** when it is absent rather than
+counting as passes.
+
+So `validate` and `build` take a `--profile`:
+
+| Profile | Runs | For |
+| --- | --- | --- |
+| `spine-html` | all 32 | **the default.** Is this a rig this project can ship? |
+| `spine` | the 18 validity rules | Is this valid Spine 4.3 that any runtime plays correctly? |
+
+The **Profile** column below says which is which — `both` = validity, `renderer` and
+`archetype` = `spine-html` only, and **`both ◑`** = a mixed assertion whose validity
+half always runs while its policy clauses are gated (A06's `pma`/rotation/full-page
+clauses, A08's "the two names must be identical", A20's "a mesh must be weighted at
+all"). A report always names the profile it ran and lists what that profile left
+out, on `PROF` lines: a `--profile spine` green means *valid Spine*, never *passes
+the renderer policy*.
+
+| Assertion | Profile | Holds that |
+| --- | --- | --- |
+| `A00_ROUNDTRIP_PARSE` | both | `spine-core` parses the skeleton and the atlas without throwing |
+| `A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS` | both | no 4.1/4.2-shaped `physics`/`ik`/… array — 4.3 folds them into one typed `constraints` array, and the old shape loads clean while the constraint vanishes |
+| `A02_NO_BONE_TRANSFORM_KEY` | both | no bone uses 4.2's `transform`; 4.3 renamed it `inherit`, and the old key silently falls back to Normal inheritance |
+| `A03_REGION_WIDTH_HEIGHT_FINITE` | both | every region attachment loaded a finite, positive width and height (a missing field loads as NaN, with no error) |
+| `A04_MESH_TRIANGLES_AND_ENCODING` | both | triangles are a multiple of 3, indices are in range, and the vertex array's encoding agrees with the UV count |
+| `A05_CURVE_ARRAY_LENGTH` | both | curve arrays carry 4 numbers per value channel and hold no non-finite value; timelines that cannot take a curve do not carry one. Covers all eleven 4.3 timeline groups — bone, slot, ik, transform, path, physics, slider, deform, drawOrder, drawOrderFolder, events |
+| `A06_ATLAS_PAGE_SIZE_MATCHES_PNG` | both ◑ | each page's declared `size:` matches the PNG on disk, and its region covers the whole page |
+| `A07_ATLAS_TEXT_SHAPE` | both | the atlas text obeys the parser's whitespace rules — no stray indentation on region names, no blank line splitting a page block |
+| `A08_REGION_NAMES_MATCH_ATTACHMENTS` | both ◑ | every attachment name resolves to a region of exactly that name |
+| `A09_ANIMATION_DURATION_MATCHES_SPEC` | both | the compiled duration equals the duration the spec declared (skeleton JSON has no duration field — the last key *is* the duration). Two tolerances: a frame of slack for a duration declared long, but a key landing *past* the declared end is held to the grid the times are stored on, because nothing playing the animation ever reaches it. SKIPs without a motion spec |
+| `A10_NO_NAN_AFTER_STEPPING` | both | stepping every animation frame by frame produces no NaN anywhere in the pose |
+| `A11_NO_CLIPPING_ATTACHMENTS` | renderer | no clipping attachments (the renderer skips them silently) |
+| `A12_NO_DARK_COLOR` | renderer | no dark / two-colour tint on slots or timelines — parsed, then ignored |
+| `A13_MESH_BUDGET` | renderer | no more mesh slots than the rig's `invariants.meshSlots`, and no mesh past its `invariants.meshTriangles`. SKIPs when the rig declares neither |
+| `A14_NO_FULL_FRAME_MESH` | renderer | no mesh spans the whole stage (a full-frame mesh is a full-frame canvas that can never dirty-skip) |
+| `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | `idle` keys no bone that drives a mesh, directly or as its control bone |
+| `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` version label is on the 4.3 line (the parser never checks it) |
+| `A17_ATLAS_PAGE_FILES_EXIST` | both | every page the atlas declares is a file on disk |
+| `A18_DETERMINISTIC_EMIT` | both | a second, independent compile of the same inputs is byte-identical. SKIPs when re-gating artifacts already on disk |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | every overlay page carries an alpha channel; only the base plate — identified structurally as the region covering the stage — may be opaque |
+| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | every weighted vertex has at least one bone, no negative weight, bone indices in range, and each vertex's weights sum to 1. `spine-html` also requires that a mesh be weighted at all and that no binding sit at weight 0 |
+| `A21_MESH_RIM_PINNED` | archetype | a ring mesh's rim vertices are pinned to the anchor bone and its hull is a real ring; a ribbon's entry row stays put. **SKIPs on authored geometry** — rigc did not place its rim |
+| `A22_MESH_UVS_IN_UNIT_RANGE` | both | every UV lies inside its region |
+| `A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | each physics constraint actually drives a component, is not muted by `mix: 0`, has non-zero mass, and has `damping < 1` so it settles |
+| `A24_AXIS_SPACE_STROKE` | archetype | the stroke is authored in **axis space** — no screen-space Y component anywhere in the axis subtree, and no keys at all on the axis bone (its rotation is the one per-cut setup value) |
+| `A25_DETACHED_BONE_PARENTAGE` | archetype | bones that must stay detached are not parented under a moving part |
+| `A26_SLOT_DRAW_ORDER` | archetype | the slots array — which *is* the draw order — matches the rig spec's slot table |
+| `A27_REGION_NAME_MATCHES_PAGE_FILENAME` | renderer | each region's name equals its page's basename, closing the second link of the attachment → region → file chain |
+| `A28_RIBBON_ROWS_SHARE_WEIGHTS` | archetype | both vertices of a ribbon row carry the same bones at the same weights, so the strip can lengthen and curve but never widen. **SKIPs on authored geometry** — rigc did not pair its rows |
+| `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | the stroke plus any inward keys stays within the cut's measured contact depth (skipped when the manifest declares none) |
+| `A30_STROKE_WITHIN_CAP_CONTAINMENT` | archetype | the stroke stays within the cut's measured containment ceiling, and nothing in the axis subtree scales — a scale key changes the contour the ceiling was measured on (skipped when the manifest declares none) |
+| `A31_DRAW_ORDER_OFFSETS_RESOLVE` | both | every draw-order key resolves to a real permutation: known slots, one entry per slot, each landing inside the slots array, offsets in ascending slot order. The **only assertion that runs before `A00`** — descending offsets make `readDrawOrder`'s forward-only cursor spin rather than return, so the round trip is refused by name instead of attempted |
+
+## Install
+
+rigc runs on [Bun](https://bun.sh). The package ships its TypeScript sources and
+Bun runs them, so there is no build step and no `dist/` that can drift from the
+repository it was cut from.
+
+**The npm package is `spine-rigc`; the command it installs is `rigc`.** npm
+refuses the name `rigc` as too similar to packages that already exist, so the
+project, this repository and the executable keep their name and only the
+registry entry is spelled out.
+
+```bash
+bunx spine-rigc --help    # run it without installing
+bun add -g spine-rigc     # or install the command
+bun add -d spine-rigc     # or pin it in a project
+```
+
+`npx spine-rigc` works too, as long as Bun is on `PATH` — the executable is a
+Bun script, and npm only writes the shim that calls it.
+
+Installed, the command is `rigc`. The examples below spell it `bun cli.ts`
+because they are written from a clone of this repository (`bun install`, then run
+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.
+
+## Usage
+
+📘 **Writing a spec? Read [docs/AUTHORING.md](docs/AUTHORING.md) first.** It is the
+guide an agent rigs from: both input files with a complete minimal example each,
+every field with its Spine meaning, the rules that decide what is emitted, the
+build → read the report → fix → repeat loop, the map from every named failure to
+the file that has to change, and the list of format features rigc refuses by name
+so you do not spend a loop discovering them. It travels **inside the npm package**
+too, so an agent working from an install has it on disk at
+`node_modules/spine-rigc/docs/AUTHORING.md`.
+
+Compile by spelling out the paths. `--manifest` is optional; `--images <dir>` says
+where a rig spec's `image` references live (it overrides the rig's own `images`
+field):
+
+```bash
+bun cli.ts build \
+  --rig      path/to/my_rig.rig.json \
+  --motion   path/to/my.motion.json \
+  --out      path/to/spine \
+  [--manifest path/to/manifest.json] [--images path/to/images]
+```
+
+…or register cuts in a `cuts.json` and build them by name. Every path in the table
+resolves **relative to the `cuts.json` file itself**, so the table lives with the
+project that owns the art:
+
+```json
+{
+  "my_cut": {
+    "rig": "rigs/my_rig.rig.json",
+    "manifest": "output/my_cut/manifest.json",
+    "motion": "specs/my_cut.motion.json",
+    "out": "output/my_cut/spine"
+  }
+}
+```
+
+```bash
+bun cli.ts build --cut my_cut --cuts path/to/cuts.json
+```
+
+`build` compiles, then validates, and **writes only if the gate is green**. Other
+commands:
+
+```bash
+bun cli.ts explain  --cut my_cut --cuts path/to/cuts.json   # the compiled rig as a table
+bun cli.ts validate path/to/spine                           # re-gate artifacts already on disk
+bun cli.ts validate --profile spine path/to/any/skeleton    # spec rules only (see Profiles)
+bun cli.ts diff candidate.json reference.json               # structural comparison
+bun cli.ts check --candidate path/to/spine \
+                 --frames bench/reference/3-timing-and-spacing   # against pictures
+bun cli.ts bench 3 --candidate path/to/spine                # one rung of the ladder
+```
+
+`validate` on a bare directory checks what it can see. Adding `--cut`/`--cuts` lets
+it re-derive the declared durations and the structural expectations too, and the
+report says which it had. `build` and `validate` both take `--profile spine` to drop
+the renderer and archetype policy; the default stays `spine-html`.
+
+## Checks
+
+```bash
+bun run typecheck    # bunx tsc --noEmit over cli.ts, selftest.ts, src/, bench/, tools/, fixtures/
+bun run lint         # one rule: @typescript-eslint/no-explicit-any, as an error
+bun run selftest     # the validator's own negative controls (next section)
+```
+
+All three run on every push and pull request —
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml). Bun runs the sources
+directly, so the first two are not on the path of anything; they exist because a
+convention nothing checks is a convention. `tsconfig.json` is
+`strict: false` with `strictNullChecks: true` and says in place why the rest is
+not on yet; `eslint.config.js` says why it carries exactly one rule.
+
+## Selftest
+
+```bash
+bun run selftest                            # everything below; no arguments needed
+bun run selftest --cuts path/to/cuts.json   # …plus an extra suite over those cuts
+```
+
+A gate nobody has seen fail is not a gate. The selftest compiles a rig, breaks the
+result one way at a time — 45 deliberate breaks, each modelled on a mistake that was
+actually made or actually measured — and asserts that the **named** assertion fires
+for each. Two further edits are *tolerance* controls the gate must let through,
+because a widened assertion can fail by firing too often as easily as by firing too
+rarely.
+
+**The rigs it breaks are generated.** [`fixtures/public.ts`](fixtures/public.ts)
+writes three synthetic cuts into a temp directory on every run, and between them
+they carry every structure the assertions have an opinion about — region
+attachments, attachment swaps, rgba fades, a ring mesh on a control bone, a ribbon
+on a bone chain, an axis bone whose subtree travels along it, a detached emitter,
+physics constraints, and two measured ceilings. Every plate is a checkerboard with
+`PLACEHOLDER` burned into it: they exist to be structurally real, and no claim
+about appearance is made from any of them.
+
+A fifth suite breaks an **input** instead of an artifact: nine malformed rig specs
+that the compiler must refuse by name — a forward parent reference, a duplicate bone
+name, a slot naming a missing bone, an ik target that does not exist, an attachment
+image that is not on disk, an authored mesh binding a bone the rig does not have,
+one that uses raw bone indices without asking for them, a wrong `spec` field, and a
+constraint type the emitter cannot write. Each of those produces a file Spine's own
+parser would accept while quietly meaning something else.
+
+A **motion** spec can be wrong the same way, and the shape that costs the most is
+the quietest: a key time that lands past the animation's declared duration is never
+sampled, so the motion it was meant to carry simply does not happen. Five controls
+hold that line — a key sitting exactly on a duration of 68/12 s is legal and must
+compile, a key that 4 dp rounding pushed 0.000034 s past one is refused by name, the
+same overshoot in an artifact the compiler never saw is caught by `A09`, an animation
+whose last key is a frame short of its declared end is still accepted because that
+direction is a different question, and a 32-second animation keyed exactly on its own
+duration is *not* failed for the float32 grid its times come back on.
+
+There is a positive control per suite as well: the pristine artifacts must come back
+with zero failures, because a validator that failed everything would otherwise look
+like a validator that worked.
+
+`rigc check` gets the same treatment, and its pair is deliberately the same rig
+twice: the rung 3 transcription against rung 3's frames, and then that transcription
+with every key time reversed. Reversing leaves the structure untouched — same
+timelines, same key count, same duration, and the gate stays green, which the
+control asserts — and changes only what the shot looks like. Faithful reads 0.67 px
+of slot drift; reversed reads 66.8 px. A third control makes the frames-only read
+guard refuse a reference skeleton, because an honesty invariant nobody has seen
+refuse anything is not an invariant.
+
+The **mesh** path gets the same pair, on the rung 6 transcription against rung 6's
+frames. Faithful reads a median 0.08 px of drift on the mesh-bearing slots; the
+break is the one an authored mesh is actually exposed to — its weights bind bones
+by *index*, so inserting a bone anywhere ahead of them rebinds every vertex in
+silence — and it reads 31 px with the gate still green. Four further controls run
+on a generated fixture and need no corpus: a ring mesh is posed at all, its pixels
+reach the coverage mask `check` reads, an all-zero deform is the identity while a
+real one moves the centroid, and two triangles sharing an edge draw it once.
+
+Point the run at a `cuts.json` and an **extra suite** compiles every cut in it,
+gates the result, and compiles it a second time for `A18`. That one is a positive
+control on purpose: what real art adds is geometry a fixture cannot fake — measured
+offsets, a measured axis, a measured ceiling, a mesh built over a contour nobody
+drew by hand — so the question it asks is whether the whole gate still comes back
+green on it. Without a cuts file it says it was skipped and the run passes on the
+public suite alone; a cuts path that is *named and missing* exits 2.
+
+Two suites measure against the Spine example corpus, which is downloaded rather
+than redistributed. When `examples/` is absent they say so loudly and the summary
+repeats it — an absent corpus is a hole in the run, not a pass — and a run in which
+nothing substantive executed exits 2 rather than printing green.
+
+## Layout
+
+```
+tsconfig.json   type-check config (noEmit); eslint.config.js — the no-any gate
+cli.ts          build / validate / explain / diff / check / bench
+selftest.ts     the validator's own negative controls, and diff's and check's
+fixtures/       public.ts — the three synthetic cuts the selftest breaks
+src/
+  compile.ts    rig + motion spec (+ manifest) -> skeleton JSON + atlas text (pure data assembly)
+  rig.ts        the rig spec — `spec: "rigc-rig/1"`, the skeleton as data
+  validate.ts   spine-core round trip + the 32 assertions
+  diff.ts       structural comparison of two skeletons, one ratio per measure
+  render.ts     the rasteriser (regions + meshes), shared by the reference renderer and check
+  check.ts      a candidate against rendered frames — pixels and per-slot drift,
+                and it never opens the reference skeleton
+  ladder.ts     which example is which rung, and which file in it is the reference
+  timelines.ts  the 4.3 timeline catalogue and its walker (shared, pure JSON)
+  mesh.ts       ring and ribbon mesh builders, weighted-vertex encoding
+  transform.ts  crop pixels (y down) <-> Spine world (y up), world transforms
+  png.ts        PNG header reader (size and colour type, no decode)
+  errors.ts     CompileError, and NotImplementedError for what the format holds
+                and the emitter does not write
+  types.ts      manifest, motion spec, and emitted-JSON shapes
+tools/          measurement and plate helpers (see below)
+scripts/        fetch-examples.sh
+bench/          count_features.ts — what the example corpus actually uses
+                render_reference.ts — a rung's official export as PNG frames
+                briefs/ — what an authoring agent is told about a rung
+                reference/ — those frames, with the licence they travel under
+                runs/ — one directory per attempt, and the run protocol
+                transcriptions/ — rung specs transcribed from a reference export,
+                which measure expressiveness and NOT authoring (see LADDER.md)
+docs/           AUTHORING.md (how to author a rig), LADDER.md (live rung status),
+                SPEC_COVERAGE.md (format survey),
+                feature_matrix.{csv,json}
+.github/        workflows/ — ci.yml (the gates) and release.yml (release-please)
+CONTRIBUTING.md how to propose a change; RELEASING.md — how a version is cut
+```
+
+`tools/` are standalone utilities, each taking its paths as arguments:
+
+| Tool | Does |
+| --- | --- |
+| `measure_contact_depth.ts` | measures a cut's contact depth from its plates, with the two-sided proof it has to satisfy. Both slot names are required: which plate is the mass and which is the occluder is a fact about one cut, and a default would measure the wrong pair and still print a number |
+| `contact.ts` | plate-vs-plate overlap measurement — the largest advance that keeps two footprints disjoint |
+| `plate.ts` / `png_probe.mjs` | minimal PNG read/write and decode |
+| `font5x7.ts` | bitmap labels for diagnostic images and generated plates |
+
+## Contributing
+
+Issues are the ledger; see [CONTRIBUTING.md](CONTRIBUTING.md) for what a change
+has to clear before it lands. Releases are cut by release-please —
+[RELEASING.md](RELEASING.md).
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Third-party terms, including the Spine editor licence
+requirement that this project inherits, are in [NOTICE.md](NOTICE.md).