spine-rigc 0.6.0 → 0.8.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,108 @@ 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.
 
+🎞️ **Authoring the movement that these two show you** — key poses, in-betweening,
+and how to spread candidates so a ballot informs — is
+[docs/MOTION.md](docs/MOTION.md).
+
+### 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)).
+
+## Reading a pose you were given — `rigc pose`
+
+```bash
+rigc pose --images parts/ --frame poseA.png [--out pose.json]
+```
+
+Every command above takes something you authored and tells you about it. This one
+runs the other way: it takes a **picture the user already has** — one key pose —
+and reports where each loose part PNG sits in it, so an agent can write those
+coordinates into a rig and a motion **by construction** and spend its effort on the
+part no instrument can measure, the movement between two poses.
+
+```
+  PLACE  torso.png    x=   44.4  y=   65.4  rot=    0.0°  scale=1.118  residual=0.0770  unexplained= 19%
+  AMBIG  arm.png      x=   27.1  y=   56.3  rot=  -35.2°  scale=1.111  residual=0.0262  unexplained=  2%
+                      alt 2: x=   61.5  y=   56.3  rot=   35.4°  scale=1.116  residual=0.0279  unexplained=  2%
+  PLACE  ball.png     x=   44.3  y=  104.6  rot=    0.0°  scale=1.144  residual=0.0203  unexplained=  3%
+                      rotation is a FREE degree of freedom — the 0° above is a placeholder
+  REFUSE foreign.png  no-match: the best placement found has residual 0.4245, above --max-residual 0.25
+```
+
+🚨 **Nothing here is a score, and no pass bar attaches to any of it.** `check` and
+`bench` measure a build against a reference, so their numbers mean *how close*. A
+pose frame is not a reference — it is a **given condition**, and once the spec
+states those coordinates there is nothing left to be close to. The residual says
+how far to trust a placement and where two answers are equally good, which is a
+different job and needs the opposite defaults:
+
+- a part that matches nowhere is **refused by name**, with its best guess still in
+  the JSON — a refusal tells you not to trust a number rather than hiding it;
+- two near-equal optima are reported as **both**, flagged `ambiguous`, never
+  silently resolved. Two identical limbs look exactly like that;
+- a part whose rotation genuinely does not matter — a ball — reports rotation as a
+  **free degree of freedom** rather than as a failure;
+- a part the canvas cannot contain at any tested scale, and a part with no material
+  in it at all, each get their own named refusal.
+
+⚠️ **Residuals degrade under occlusion and there is no depth solver here.** A part
+drawn behind another has the occluder's pixels where its own should be, so its
+residual rises at the *correct* placement; `unexplained` is the share of the part
+that disagrees, and a middling residual beside a high `unexplained` usually means
+*right place, seen through something else*. The output carries its own `caveats`
+block saying so. Fields, coordinate contract and the rest of the limits:
+**[AUTHORING.md §11](docs/AUTHORING.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 +704,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 +734,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 +742,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 +755,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 +809,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 +872,24 @@ 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
+bun cli.ts pose    --images path/to/parts --frame poseA.png # read a pose OUT of a picture
 ```
 
 `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). `pose` is the
+one command that runs *before* a spec exists rather than after — see
+[Reading a pose you were given](#reading-a-pose-you-were-given--rigc-pose).
 
 ## Checks
 
@@ -856,20 +986,26 @@ 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 / pose
 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
+  pose.ts       the other direction: loose part PNGs against ONE pose frame, and
+                where each part sits in it. An entry instrument — it reads a given
+                condition into spec coordinates and grades nothing
   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