spine-rigc 0.5.0 → 0.7.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner.svg" alt="rigc - Rig compiler for Spine" width="100%" />
+  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/banner.svg" alt="rigc - Rig compiler for Spine" width="100%" />
 </p>
 
 <p align="center">
@@ -53,6 +53,268 @@ weights. Every one of those loads clean, plays, and is wrong. rigc's answer is t
 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.**
 
+## Install
+
+📦 **rigc measures loose PNGs directly — one atlas page per image.** It is not an
+atlas packer: packing several regions onto one page is tracked as
+[issue #4](https://github.com/firejune/rigc/issues/4), not something the tool does
+today.
+
+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.
+
+## First rig in ten minutes
+
+A whole rig, end to end, in a scratch directory: three tiny plates, two JSON
+files, one `build`, one `validate`. No clone, no art pipeline, nothing fetched.
+
+🚫 **Every value below is invented for this section** — a doll that exists
+nowhere else in this repository. That is [AUTHORING.md](docs/AUTHORING.md) §3's
+rule applied here: no example value in these documents is copied out of a
+reference export, so nothing you read in a quickstart is an answer to anything
+[the ladder](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) measures.
+
+**1. Install the command.**
+
+```bash
+bun add -g spine-rigc     # installs `rigc`
+```
+
+Or skip the install and prefix every command below with `bunx `, e.g.
+`bunx spine-rigc build …`.
+
+**2. Make a directory and three plates.** rigc measures PNGs rather than trusting
+a number you typed (R5), so the art has to exist. These three are solid colours a
+few dozen pixels across — a hull, a mast and a lamp:
+
+```bash
+mkdir -p buoy/images && cd buoy
+bun -e '
+const parts = {
+  "images/hull.png": "iVBORw0KGgoAAAANSUhEUgAAADgAAAAMCAYAAAA3bX6lAAAAKElEQVR42mOI8bL6P5wxw6gHRz046sFRD456cNSDox4c9eCoBwcrBgDSZ+mdl2OiDgAAAABJRU5ErkJggg==",
+  "images/mast.png": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAA0CAYAAAC3t3ldAAAAH0lEQVR42mO4dunIf3yYYVTBqIJRBaMKRhWMKhgcCgBGJo4s9YnopgAAAABJRU5ErkJggg==",
+  "images/lamp.png": "iVBORw0KGgoAAAANSUhEUgAAABIAAAASCAYAAABWzo5XAAAAHElEQVR42mP4v8HhPzUww6hBowaNGjRq0HAzCADvdrVmFPbc+QAAAABJRU5ErkJggg=="
+};
+for (const [p, b] of Object.entries(parts)) await Bun.write(p, Buffer.from(b, "base64"));
+'
+```
+
+**3. The rig spec — `buoy.rig.json`.** Structure only: bones, the slots array in
+draw order, and one skin mapping each slot to a plate.
+
+```json
+{
+  "spec": "rigc-rig/1",
+  "name": "buoy",
+  "images": "images",
+  "skeleton": { "width": 200, "height": 200 },
+  "bones": [
+    { "name": "root" },
+    { "name": "hull", "parent": "root", "x": 0, "y": 0 },
+    { "name": "mast", "parent": "hull", "x": 0, "y": 4 },
+    { "name": "lamp", "parent": "mast", "x": 0, "y": 52 }
+  ],
+  "slots": [
+    { "name": "mast", "bone": "mast", "attachment": "mast" },
+    { "name": "hull", "bone": "hull", "attachment": "hull" },
+    { "name": "lamp", "bone": "lamp", "attachment": "lamp" }
+  ],
+  "skins": {
+    "default": {
+      "mast": { "mast": { "image": "mast.png", "y": 26 } },
+      "hull": { "hull": { "image": "hull.png" } },
+      "lamp": { "lamp": { "image": "lamp.png" } }
+    }
+  }
+}
+```
+
+Three things in there are worth naming, because each is a rule rather than a
+style: the **slots array is the setup draw order** (R4) — index 0 is furthest
+back, so the mast is behind the hull; the attachment carries an **`image`
+instead of a `width`/`height`** (R5), which is what makes the size in the
+skeleton and the size in the atlas incapable of drifting apart; and the mast's
+`"y": 26` offsets the plate *within* its slot so the bone sits at the mast's foot
+rather than its middle.
+
+**4. The motion spec — `buoy.motion.json`.** Time only, aimed at the rig by name:
+
+```json
+{
+  "spec": "rigc-motion/1",
+  "archetype": "buoy",
+  "cut": "buoy",
+  "easings": { "swing": [0.42, 0, 0.58, 1] },
+  "animations": {
+    "bob": {
+      "duration": 2,
+      "loop": true,
+      "tracks": [
+        {
+          "bone": "hull",
+          "property": "translatey",
+          "keys": [
+            { "t": 0,   "v": [0],  "ease": "swing" },
+            { "t": 0.5, "v": [5],  "ease": "swing" },
+            { "t": 1.5, "v": [-5], "ease": "swing" },
+            { "t": 2,   "v": [0] }
+          ]
+        },
+        {
+          "bone": "mast",
+          "property": "rotate",
+          "keys": [
+            { "t": 0, "v": [-6], "ease": "swing" },
+            { "t": 1, "v": [6],  "ease": "swing" },
+            { "t": 2, "v": [-6] }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+`archetype` must equal the rig's `name`. `duration` is declared and then checked
+against what actually compiled (R7). The **last key of each track carries no
+easing** — there is nothing after it to ease towards, and saying otherwise is a
+compile error.
+
+**5. Build, then re-gate what it wrote.**
+
+```bash
+rigc build --rig buoy.rig.json --motion buoy.motion.json --images images --out spine
+rigc validate spine
+```
+
+`build` prints every assertion by name, then the shape of what it emitted, then
+the two files:
+
+```
+  ..    pages=3 regions=3 bones=4 slots=3 animations=1 version=4.3.13 regionAttachments=3 meshAttachments=0 physicsConstraints=0 rig=buoy profile=spine
+rigc: wrote …/buoy/spine/skeleton.json
+rigc: wrote …/buoy/spine/skeleton.atlas
+```
+
+`profile=spine` is the rulebook that judged it: *is this valid Spine 4.3 that any
+runtime plays correctly?* That is the default, and the [Profiles](#profiles--wrong-versus-not-how-we-do-it-here)
+section below is where the other one lives. `validate` then re-reads those
+artifacts from disk and ends `rigc: green`. That is a rig. `spine/skeleton.json`
+is Spine 4.3 skeleton data — it loads in a Spine runtime and it imports into the
+Spine editor.
+
+**Try breaking it**, because the validator's messages are the interface here and
+they are worth meeting once on purpose. With `spine/` built, rename
+`images/hull.png` to `images/raft.png` and re-run `rigc validate spine`:
+
+```
+FAIL  A17_ATLAS_PAGE_FILES_EXIST: page "../images/hull.png" is not on disk at …/images/hull.png
+rigc: 1 assertion(s) failed
+```
+
+Put the name back and it is green again. The same gate runs inside `build`, and
+a FAIL there stops it **before it writes** — a red build leaves no half-built
+artifact on disk to mistake for a result, and there is no flag that changes that.
+
+**6. See what you built.**
+
+🚨 **Green is a claim about validity and about nothing else.** A rig whose head
+sits visibly off its torso passes every assertion, loads in `spine-core` and steps
+numerically clean — the offsets are the ones your spec asked for, and no
+assertion can know you did not mean them. The only remedy is looking, and both
+commands below need nothing you do not already have: no reference frames, no
+second package, no server.
+
+```bash
+rigc render  --candidate spine          # PNG frames + a contact sheet, in render/
+rigc preview --candidate spine          # one .html file that plays it: preview.html
+```
+
+**`render`** samples every animation at 12 fps and writes `render/<animation>/f0000.png…`
+with a `contact.png` beside them — every frame of the shot as one labelled grid,
+which is the picture to open first, because spacing is a comparison *across*
+frames. It draws with rigc's own rasteriser (the one `check` measures with), so
+it needs no browser and no network, and the `frames.json` it leaves beside the
+directories makes the result a frame set like any other — the world box every
+frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
+`--max` change the rate and the frame size.
+
+**`preview`** writes a single self-contained `.html`: your skeleton, your atlas
+and every page's PNG bytes are embedded in it as data URIs, and it plays them in
+the **official [Spine Web Player](https://esotericsoftware.com/spine-player)**.
+Double-click it, or attach it to a message — the file carries the whole artifact.
+It is also the strongest interop statement in this repository: a rig that plays
+there has been played by Esoteric Software's own runtime rather than by ours.
+
+> ⚖️ The player itself is **referenced, not embedded** — the page loads it from
+> unpkg, so the first open needs a network, and rigc redistributes nothing
+> Esoteric Software owns (see [NOTICE.md](NOTICE.md)). Everything the player
+> draws is inside your file.
+
+**7. Let someone choose.** Sooner or later you will have two builds that both pass
+the gate and no instrument that can separate them. `vote` puts them in one page
+side by side, labelled `A` and `B` with no paths on screen, and takes an answer
+back:
+
+```bash
+rigc vote --candidate spine-a --candidate spine-b   # -> ballot.html, open it and pick one
+rigc vote --record vote-<id>.json                   # -> checks the answer into votes.jsonl
+```
+
+The voter picks a winner or says "tie / no preference"; the page hands them a
+small JSON file to save; `--record` checks that file against the ballot's own
+hashes and appends one line to an append-only ledger, refusing by name anything
+that does not belong to it. See
+[Letting someone choose](#letting-someone-choose--rigc-vote).
+
+**Where to go next.**
+
+- 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** is the real guide — both files
+  field by field, the emission rules, every named failure mapped to the file that
+  has to change, and §8–§9 for reproducing a shot you were given as pictures. It
+  ships inside the npm package too, at
+  `node_modules/spine-rigc/docs/AUTHORING.md`.
+- `rigc explain --rig buoy.rig.json --motion buoy.motion.json --out spine` prints
+  the compiled rig as a table — every bone with its resolved parent, the slots in
+  draw order, every timeline key by key — and writes nothing. It is what to reach
+  for when a rig compiles and still looks wrong.
+- 🚨 **A green gate does not mean the animation is right**, and no assertion
+  could. If you have reference pictures of the shot,
+  `rigc check --candidate spine --frames <dir>` is the half of the loop that can
+  see a wrong animation — AUTHORING.md §9.
+- [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) is the benchmark: the same job, from a brief
+  and rendered frames, scored. [docs/PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is how to run an
+  agent through it and score what comes back.
+- 🤖 **Handing the authoring to an AI agent?**
+  [docs/PROMPTING.md](docs/PROMPTING.md) is the operator's page — the six prompt
+  clauses a measured pilot run paid for, and what you can leave unsaid.
+
 ## The yardstick
 
 The measure of whether this works is **Spine's own official example projects** —
@@ -193,13 +455,14 @@ the scale for a run.
 
 There is no pass mark **in the tool**, for the same reason `diff` has none. The
 ladder's pass definition and its thresholds are a document read by a person over
-the whole table — [docs/LADDER.md](docs/LADDER.md)'s *Operating rules* — and not an
+the whole table — [docs/GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) states the clauses and
+[docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md)'s *Operating rules* derives them — and not an
 exit code either command could produce.
 
 ### Benchmark ladder — the rungs, and where they stand
 
 🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
-spineboy graduation exam are cleared under gate v2.1, every clause PASS or SKIP:
+spineboy graduation exam are cleared under gate v2.1 and hold under **v2.2**, 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
@@ -212,11 +475,11 @@ 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.
 
-**[docs/LADDER.md](docs/LADDER.md) is the live ledger**: the rung order
+**[docs/LADDER.md](https://github.com/firejune/rigc/blob/main/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, the operating rules — what a pass is, and
-the numbered thresholds of the current gate (**gate v2.1**) that decide one — and a status table. Run
+the numbered thresholds of the current gate (**gate v2.2**, stated in [docs/GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md)) that decide one — and a status table. Run
 one with:
 
 ```bash
@@ -239,9 +502,93 @@ that every example declares; and **B3**, every example ships a **packed** atlas
 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).
+live status, and B1's proof, in [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
+
+## Looking at a rig — `rigc render` and `rigc preview`
+
+The validator cannot see a wrong pose and says so honestly; `check` can, and needs
+reference frames a first user does not have. That left looking as the one thing
+the package could not do, and these two commands are it. Both take a compiled
+artifact — the directory `build --out` wrote — and neither needs a reference, a
+clone or a server:
 
-## Run viewer — watching a run instead of reading it
+```bash
+rigc render  --candidate spine [--animation <name>] [--fps 12] [--max 256] [--out render/]
+rigc preview --candidate spine [--animation <name>] [--out preview.html]
+```
+
+`render` writes `render/<animation>/f0000.png…` plus a `contact.png` grid of every
+frame and a `frames.json` sidecar describing the world box they are pictures of —
+the same frame-set shape `bench/render_reference.ts` writes and `rigc check`
+reads, drawn by the same rasteriser, so the output is a frame set rather than a
+pile of images. `preview` writes one self-contained `.html` that plays the
+artifact in the official Spine Web Player, with the skeleton, the atlas and every
+page embedded as data URIs; the player is loaded from unpkg rather than copied, so
+the first open needs a network and rigc redistributes nothing Esoteric Software
+owns ([NOTICE.md](NOTICE.md)).
+
+They complement each other rather than overlap. `render` is offline, deterministic
+and measurable — its pixels are the ones `check` reports on. `preview` is the
+interop proof: what plays there was played by Esoteric's own runtime, not by ours.
+
+### Letting someone choose — `rigc vote`
+
+Sometimes looking is not enough on its own, because there is more than one
+candidate and no instrument that can separate them: a pose fit with two local
+optima that measure the same, a key density that is a matter of taste, a first
+draft with no reference to compare against. `vote` is the deliberate human gate
+for exactly that residue, and only for that residue.
+
+```bash
+rigc vote --candidate spine-a --candidate spine-b [--animation <name>] [--out ballot.html]
+rigc vote --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl] [--again]
+```
+
+The first form writes one self-contained `ballot.html`: two to four compiled
+candidates side by side, each in its own official player, looping, with one
+button that restarts them together. The panes are labelled `A`, `B`, `C`, `D` and
+show **no paths** — a voter who can see that `B` came out of `experiments/` is not
+comparing pictures any more — so the path→label mapping lives in a manifest
+embedded in the same file and is never rendered. A voter picks a winner or says
+"tie / no preference", optionally writes a sentence, and copies or downloads a
+small JSON result the page prints the filename for.
+
+The second form checks that result against the ballot's own manifest and appends
+it to an append-only JSONL ledger. Nothing is trusted: the result carries a
+content **digest** per candidate, and a result whose digests are not this
+ballot's, whose choice is not on it, or whose reason code contradicts its choice
+is refused by a named rule (`V02_CANDIDATE_DIGESTS_ARE_THE_BALLOTS` and friends)
+with nothing appended. A second vote on one ballot needs `--again`.
+
+The loop it is built for, in one line: **the agent compiles N candidates that all
+pass the gate → `rigc vote` writes the ballot → a human opens it, watches, and
+votes → `rigc vote --record` checks the answer into `votes.jsonl` → the agent
+reads the ledger and proceeds.** Compile first, vote last: a candidate reaches a
+ballot only because it already validated green, so the human is never asked to
+read JSON, a diff or a spec.
+
+Three properties are worth stating because they are what make the ledger usable
+by the next agent rather than by a reader:
+
+- **A tie is a recorded outcome, not a missing one.** The ledger distinguishes a
+  ballot with a winner, a ballot the human called a tie, and a ballot nobody
+  opened. `both-unacceptable` is the tie that means *propose again*, and it is
+  unreachable if ties are not recordable.
+- **The winner is a digest, not a label.** `B` means nothing outside one ballot;
+  the digest identifies the same pixels anywhere. Every line also carries its
+  `coverage` — which candidates the vote compared — so completeness is
+  computable rather than assumed.
+- **Every line carries a reason code** from a closed enumeration, and the
+  enumeration is enforced: "tie, because this one is better" is refused.
+
+Same player, same posture as `preview`: referenced from a CDN, never vendored,
+and the file contains only your own art ([NOTICE.md](NOTICE.md)).
+
+## Run viewer — watching a *run* instead of reading it
+
+🔎 **This is the ladder's instrument, not the way to look at your own rig** — that
+is the section above. The viewer is reference-bound and repository-bound, and it
+deliberately never ships.
 
 `check.txt` says a candidate's worst frame is f0012 at 56 MAE. The viewer shows
 you f0012.
@@ -308,8 +655,11 @@ the rest of the repository must not have) and is type-checked on its own with
 - 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`).
+  tracks, and five timeline families that sit on the animation rather than in `tracks`:
+  `drawOrder` and `events`, which name no target at all, and `ik`, `transform`
+  and `deform`, whose keys carry named fields instead of one value (an IK mix and
+  softness, six transform mixes, a sparse run of vertex offsets) — which is also
+  where 4.3 writes each of them.
 
 **Outputs — two files per cut**, written to the cut's `out` directory:
 
@@ -335,7 +685,7 @@ model (what is pinned, what may move, how authority falls off), and the
 ### The validator
 
 [`src/validate.ts`](src/validate.ts) parses the emitted artifacts with `spine-core`
-and then runs 34 named assertions over the loaded skeleton. Each one exists because
+and then runs 36 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
@@ -343,7 +693,7 @@ count — an assertion with nothing to check has not checked anything.
 
 #### Profiles — "wrong" versus "not how we do it here"
 
-Not all 34 rules are about Spine. Some are about **spine-html**, the renderer this
+Not all 36 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 —
@@ -356,8 +706,15 @@ So `validate` and `build` take a `--profile`:
 
 | Profile | Runs | For |
 | --- | --- | --- |
-| `spine-html` | all 34 | **the default.** Is this a rig this project can ship? |
-| `spine` | the 20 validity rules | Is this valid Spine 4.3 that any runtime plays correctly? |
+| `spine` | the 22 validity rules | **the default.** Is this valid Spine 4.3 that any runtime plays correctly? |
+| `spine-html` | all 36 | Opt-in. Is this a rig *this* project can ship? |
+
+`spine` is the default because it is the question this package's output answers:
+the artifact imports into the Spine editor and plays in any 4.3 runtime, and
+that is what the 22 validity rules are about. The other 14 are somebody's policy
+— one renderer's, one canvas budget's, one compiler's own formations' — and a
+rig arriving from anywhere else has no stake in them. Ask for them with
+`--profile spine-html` when you want them.
 
 The **Profile** column below says which is which — `both` = validity, `renderer` and
 `archetype` = `spine-html` only, and **`both ◑`** = a mixed assertion whose validity
@@ -388,7 +745,7 @@ the renderer policy*.
 | `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 |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | every overlay part image can be transparent somewhere — an alpha channel (colour type 4 or 6) **or** a `tRNS` chunk, which is where indexed and greyscale PNGs keep theirs. 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 |
@@ -403,208 +760,8 @@ the renderer policy*.
 | `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 |
 | `A32_EVENT_KEYS_RESOLVE` | both | every event key fires an event the skeleton declares, no key sits earlier in time than the one before it, and `volume`/`balance` appear only on an event with an `audio` path. Only the first of those is loud in the parser; the other two load clean and drop the firing or the value in silence. SKIPs when no animation carries an event timeline |
 | `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | every bounding box and clipping polygon states a `vertexCount` that agrees with its vertex array, its weighted run decodes to that many vertices with bone indices in range, and a clipping `end` names a slot that exists. All three load clean: a missing count reads as zero and empties the polygon, and a missing end slot makes the clip run to the bottom of the draw order. SKIPs when the skeleton carries neither type |
-
-## 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.
-
-## First rig in ten minutes
-
-A whole rig, end to end, in a scratch directory: three tiny plates, two JSON
-files, one `build`, one `validate`. No clone, no art pipeline, nothing fetched.
-
-🚫 **Every value below is invented for this section** — a doll that exists
-nowhere else in this repository. That is [AUTHORING.md](docs/AUTHORING.md) §3's
-rule applied here: no example value in these documents is copied out of a
-reference export, so nothing you read in a quickstart is an answer to anything
-[the ladder](docs/LADDER.md) measures.
-
-**1. Install the command.**
-
-```bash
-bun add -g spine-rigc     # installs `rigc`
-```
-
-Or skip the install and prefix every command below with `bunx `, e.g.
-`bunx spine-rigc build …`.
-
-**2. Make a directory and three plates.** rigc measures PNGs rather than trusting
-a number you typed (R5), so the art has to exist. These three are solid colours a
-few dozen pixels across — a hull, a mast and a lamp:
-
-```bash
-mkdir -p buoy/images && cd buoy
-bun -e '
-const parts = {
-  "images/hull.png": "iVBORw0KGgoAAAANSUhEUgAAADgAAAAMCAYAAAA3bX6lAAAAKElEQVR42mOI8bL6P5wxw6gHRz046sFRD456cNSDox4c9eCoBwcrBgDSZ+mdl2OiDgAAAABJRU5ErkJggg==",
-  "images/mast.png": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAA0CAYAAAC3t3ldAAAAH0lEQVR42mO4dunIf3yYYVTBqIJRBaMKRhWMKhgcCgBGJo4s9YnopgAAAABJRU5ErkJggg==",
-  "images/lamp.png": "iVBORw0KGgoAAAANSUhEUgAAABIAAAASCAYAAABWzo5XAAAAHElEQVR42mP4v8HhPzUww6hBowaNGjRq0HAzCADvdrVmFPbc+QAAAABJRU5ErkJggg=="
-};
-for (const [p, b] of Object.entries(parts)) await Bun.write(p, Buffer.from(b, "base64"));
-'
-```
-
-**3. The rig spec — `buoy.rig.json`.** Structure only: bones, the slots array in
-draw order, and one skin mapping each slot to a plate.
-
-```json
-{
-  "spec": "rigc-rig/1",
-  "name": "buoy",
-  "images": "images",
-  "skeleton": { "width": 200, "height": 200 },
-  "bones": [
-    { "name": "root" },
-    { "name": "hull", "parent": "root", "x": 0, "y": 0 },
-    { "name": "mast", "parent": "hull", "x": 0, "y": 4 },
-    { "name": "lamp", "parent": "mast", "x": 0, "y": 52 }
-  ],
-  "slots": [
-    { "name": "mast", "bone": "mast", "attachment": "mast" },
-    { "name": "hull", "bone": "hull", "attachment": "hull" },
-    { "name": "lamp", "bone": "lamp", "attachment": "lamp" }
-  ],
-  "skins": {
-    "default": {
-      "mast": { "mast": { "image": "mast.png", "y": 26 } },
-      "hull": { "hull": { "image": "hull.png" } },
-      "lamp": { "lamp": { "image": "lamp.png" } }
-    }
-  }
-}
-```
-
-Three things in there are worth naming, because each is a rule rather than a
-style: the **slots array is the setup draw order** (R4) — index 0 is furthest
-back, so the mast is behind the hull; the attachment carries an **`image`
-instead of a `width`/`height`** (R5), which is what makes the size in the
-skeleton and the size in the atlas incapable of drifting apart; and the mast's
-`"y": 26` offsets the plate *within* its slot so the bone sits at the mast's foot
-rather than its middle.
-
-**4. The motion spec — `buoy.motion.json`.** Time only, aimed at the rig by name:
-
-```json
-{
-  "spec": "rigc-motion/1",
-  "archetype": "buoy",
-  "cut": "buoy",
-  "easings": { "swing": [0.42, 0, 0.58, 1] },
-  "animations": {
-    "bob": {
-      "duration": 2,
-      "loop": true,
-      "tracks": [
-        {
-          "bone": "hull",
-          "property": "translatey",
-          "keys": [
-            { "t": 0,   "v": [0],  "ease": "swing" },
-            { "t": 0.5, "v": [5],  "ease": "swing" },
-            { "t": 1.5, "v": [-5], "ease": "swing" },
-            { "t": 2,   "v": [0] }
-          ]
-        },
-        {
-          "bone": "mast",
-          "property": "rotate",
-          "keys": [
-            { "t": 0, "v": [-6], "ease": "swing" },
-            { "t": 1, "v": [6],  "ease": "swing" },
-            { "t": 2, "v": [-6] }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
-`archetype` must equal the rig's `name`. `duration` is declared and then checked
-against what actually compiled (R7). The **last key of each track carries no
-easing** — there is nothing after it to ease towards, and saying otherwise is a
-compile error.
-
-**5. Build, then re-gate what it wrote.**
-
-```bash
-rigc build --rig buoy.rig.json --motion buoy.motion.json --images images --out spine
-rigc validate spine
-```
-
-`build` prints every assertion by name, then the shape of what it emitted, then
-the two files:
-
-```
-  ..    pages=3 regions=3 bones=4 slots=3 animations=1 version=4.3.13 regionAttachments=3 meshAttachments=0 physicsConstraints=0 rig=buoy profile=spine-html
-rigc: wrote …/buoy/spine/skeleton.json
-rigc: wrote …/buoy/spine/skeleton.atlas
-```
-
-and `validate` re-reads those artifacts from disk and ends `rigc: green`. That is
-a rig. `spine/skeleton.json` is Spine 4.3 skeleton data — it loads in a Spine
-runtime and it imports into the Spine editor.
-
-**Try breaking it**, because the validator's messages are the interface here and
-they are worth meeting once on purpose. Rename `images/hull.png` to
-`images/raft.png`, point the spec's `image` at the new name, and build again:
-
-```
-FAIL  A08_REGION_NAMES_MATCH_ATTACHMENTS: attachment "hull" resolves to region "raft"; v0 requires them identical
-rigc: 1 assertion(s) failed — nothing written
-```
-
-Nothing was written. A red run leaves no half-built artifact on disk to mistake
-for a result, and there is no flag that changes that.
-
-**Where to go next.**
-
-- 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** is the real guide — both files
-  field by field, the emission rules, every named failure mapped to the file that
-  has to change, and §8–§9 for reproducing a shot you were given as pictures. It
-  ships inside the npm package too, at
-  `node_modules/spine-rigc/docs/AUTHORING.md`.
-- `rigc explain --rig buoy.rig.json --motion buoy.motion.json --out spine` prints
-  the compiled rig as a table — every bone with its resolved parent, the slots in
-  draw order, every timeline key by key — and writes nothing. It is what to reach
-  for when a rig compiles and still looks wrong.
-- 🚨 **A green gate does not mean the animation is right**, and no assertion
-  could. If you have reference pictures of the shot,
-  `rigc check --candidate spine --frames <dir>` is the half of the loop that can
-  see a wrong animation — AUTHORING.md §9.
-- [docs/LADDER.md](docs/LADDER.md) is the benchmark: the same job, from a brief
-  and rendered frames, scored. [docs/PILOT.md](docs/PILOT.md) is how to run an
-  agent through it and score what comes back.
-- 🤖 **Handing the authoring to an AI agent?**
-  [docs/PROMPTING.md](docs/PROMPTING.md) is the operator's page — the six prompt
-  clauses a measured pilot run paid for, and what you can leave unsaid.
+| `A34_CONSTRAINT_TIMELINE_TARGETS` | both | every `ik` / `transform` timeline names a constraint of that type and carries at least one key. The name-and-type miss is loud in the parser (`IK Constraint not found`) and this one says which constraints the skeleton *does* have; the empty key array is silent — `readAnimation` reads key 0, finds nothing and skips the timeline without a word. SKIPs when no animation carries one |
+| `A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` | both | every deform key's run lands inside the attachment's own deform array, starts on an even index, holds an even count of finite numbers, and names a skin/slot/attachment triple that resolves. The array is one `x, y` pair per **vertex** on an unweighted attachment and one per **bone influence** on a weighted one, so its length is measured from the attachment rather than assumed. An overlong run is the format's quietest defect: `Utils.arrayCopy` into a `Float32Array` drops everything past the end, so part of the mesh deforms and it looks nearly right. SKIPs when no animation carries a deform timeline |
 
 ## Usage
 
@@ -629,6 +786,11 @@ bun cli.ts build \
   [--manifest path/to/manifest.json] [--images path/to/images]
 ```
 
+By default, atlas page paths point back at the source art wherever it lives —
+often outside `--out` — so add `--copy-images` when `spine/` itself needs to be
+self-contained (zipped, committed, or handed off on its own): it copies every
+referenced page PNG into `--out` and rewrites the atlas to match.
+
 …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:
@@ -654,17 +816,28 @@ 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 validate --profile spine-html path/to/spine      # …and this project's policy too (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
+bun cli.ts render  --candidate path/to/spine                # PNG frames + a contact sheet
+bun cli.ts preview --candidate path/to/spine                # one .html that plays it
+bun cli.ts vote    --candidate path/to/a --candidate path/to/b   # one .html that asks which
+bun cli.ts vote    --record vote-<id>.json                  # check the answer into votes.jsonl
 ```
 
 `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`.
+report says which it had. `build` and `validate` both default to `--profile spine`,
+the 22 validity rules; `--profile spine-html` adds this project's renderer and
+archetype policy on top.
+
+`render` and `preview` are the two that need no reference at all — see
+[Looking at a rig](#looking-at-a-rig--rigc-render-and-rigc-preview). Run either
+straight after a green `build`, on the same directory `--out` wrote. `vote` is the
+same idea with more than one candidate in the page and an answer coming back —
+see [Letting someone choose](#letting-someone-choose--rigc-vote).
 
 ## Checks
 
@@ -675,7 +848,7 @@ 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
+[`.github/workflows/ci.yml`](https://github.com/firejune/rigc/blob/main/.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
@@ -695,7 +868,7 @@ 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)
+**The rigs it breaks are generated.** [`fixtures/public.ts`](https://github.com/firejune/rigc/blob/main/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
@@ -761,22 +934,28 @@ nothing substantive executed exits 2 rather than printing green.
 
 ```
 tsconfig.json   type-check config (noEmit); eslint.config.js — the no-any gate
-cli.ts          build / validate / explain / diff / check / bench
+cli.ts          build / validate / explain / diff / check / bench / render / preview / vote
 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 34 assertions
+  validate.ts   spine-core round trip + the 36 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
+  render.ts     the rasteriser (regions + meshes), shared by the reference renderer,
+                `rigc render` and check
+  preview.ts    the single-file HTML player page — the artifact embedded as data
+                URIs, played by the official Spine Web Player (referenced, not vendored)
+  ballot.ts     the same page with 2–4 candidates in it and a vote coming back —
+                candidate digests, the ballot manifest, and the refusals that
+                stand between a saved vote and the ledger
   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)
+  png.ts        PNG header reader (size, colour type, tRNS; no pixel 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
@@ -793,7 +972,8 @@ viewer/         the run viewer — dev server only, no build (see above)
                   vite.config.ts  /api/inventory and /repo/<path>, and the build refusal
                   inventory.ts    what is under bench/runs, resolved to URLs
                   main.ts         the two panes, the transport, the report
-docs/           AUTHORING.md (how to author a rig), LADDER.md (live rung status),
+docs/           AUTHORING.md (how to author a rig), GATE.md (the clause statements
+                a candidate is graded against), 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)
@@ -806,14 +986,14 @@ CONTRIBUTING.md how to propose a change; RELEASING.md — how a version is cut
 | --- | --- |
 | `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 |
+| `plate.ts` / `png_probe.mjs` | minimal PNG read/write and decode. The writer emits colour type 6 only; the reader takes every colour type and bit depth PNG allows except interlaced, expanding indexed palettes (`PLTE` + `tRNS`) and greyscale to RGBA — because the gate accepts that art, so the renderer has to as well (issue #226) |
 | `font5x7.ts` | bitmap labels for diagnostic images and generated plates |
 
 ## Contributing
 
-Issues are the ledger; see [CONTRIBUTING.md](CONTRIBUTING.md) for what a change
+Issues are the ledger; see [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) for what a change
 has to clear before it lands. Releases are cut by release-please —
-[RELEASING.md](RELEASING.md).
+[RELEASING.md](https://github.com/firejune/rigc/blob/main/RELEASING.md).
 
 ## Licence