spine-rigc 0.6.0 → 0.7.0

package/README.md

@@ -277,6 +277,22 @@ there has been played by Esoteric Software's own runtime rather than by ours.
 > 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
@@ -515,6 +531,59 @@ They complement each other rather than overlap. `render` is offline, determinist
 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
@@ -586,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:
 
@@ -613,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
@@ -621,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 —
@@ -634,12 +706,12 @@ So `validate` and `build` take a `--profile`:
 
 | Profile | Runs | For |
 | --- | --- | --- |
-| `spine` | the 20 validity rules | **the default.** Is this valid Spine 4.3 that any runtime plays correctly? |
-| `spine-html` | all 34 | Opt-in. Is this a rig *this* project can ship? |
+| `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 20 validity rules are about. The other 14 are somebody's policy
+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.
@@ -688,6 +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 |
+| `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
 
@@ -749,17 +823,21 @@ bun cli.ts check --candidate path/to/spine \
 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 default to `--profile spine`,
-the 20 validity rules; `--profile spine-html` adds this project's renderer and
+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.
+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
 
@@ -856,18 +934,21 @@ 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 / render / preview
+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,
                 `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