spine-rigc 0.2.1 → 0.3.0

package/README.md

@@ -133,7 +133,11 @@ per animation and per frame:
   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.
+  of everything else: get it wrong and the error arrives disguised as motion. On a
+  skeleton root it is decided **per animation directory**: a set whose own pixels
+  land in the box `frames.json` records is measured there, exactly, and the rest
+  share one fitted framing. `--framing shared` measures every set in the shared one
+  — the whole-root behaviour before issue #100, and worth 15–25 MAE on a character.
 - **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
@@ -146,6 +150,13 @@ per animation and per frame:
   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.
+- **Per-chain attribution** — the same two, rolled up onto the unit an author
+  repairs. `check` cuts the **candidate's own** bone tree into chains at its branch
+  points and prints, per chain per set, the worst slot drift with its slot and
+  frame, the mean, the error per pixel inside it, and its share of the set's error
+  over the reference's own drawn pixels — plus one rollup line per chain across
+  every set. A figure with a dozen joints otherwise collapses to one number a shot,
+  and *"motion ✗"* over sixteen shots does not say which limb to re-key.
 
 🔒 **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
@@ -195,6 +206,46 @@ closed**; B3's validator half is (the packed-atlas clauses live behind `--profil
 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).
 
+## Run viewer — watching a run instead of reading it
+
+`check.txt` says a candidate's worst frame is f0012 at 56 MAE. The viewer shows
+you f0012.
+
+```bash
+bun run viewer      # http://localhost:5173
+```
+
+Pick a run, a candidate and an animation. The left pane plays the candidate's
+emitted `skeleton.json` — rendered by **[spine-html](https://github.com/firejune/spine-html)**,
+plain DOM, one CSS matrix per slot — and the right pane shows the reference
+frames for the same animation from `bench/reference/`, indexed by the scrubber's
+time at the frame set's own fps. Both panes use the world box the run was
+measured in (`bench.json`'s `check.viewport`, per frame set where the run framed
+them separately), so the two pictures are comparable exactly as far as the
+check's numbers say they are — and the pane label names which box that was.
+Under them: `bench.json`'s section means and the framing plus per-animation
+summary from `check.txt`.
+
+It is also the smallest end-to-end proof the two modules have. rigc emits Spine
+data; spine-html consumes Spine data; neither is checking its own work when the
+skeleton one wrote comes up animating in the other.
+
+Every run under `bench/runs/` is listed, including the ones that predate a
+convention — those are greyed out with the reason (a missing atlas page usually
+means `bun run fetch-examples` has not run) rather than dropped, because the
+ladder's history is part of what the viewer is for.
+
+🚫 **There is no build, and that is deliberate.** The viewer reads the working
+tree: the runs, the reference frames, and `examples/` — which is Esoteric
+Software's art, fetched rather than redistributed and non-commercial even then
+(see [NOTICE.md](NOTICE.md)). A bundle would copy those pixels into a
+distributable artifact. So there is one mode, `vite dev` on localhost, the dev
+server serves nothing outside `bench/` and `examples/`, and `vite build` fails
+on purpose. `viewer/` is not in `package.json`'s `files`, so it never ships
+either; it is also outside the root `tsconfig.json` (it needs the DOM lib, which
+the rest of the repository must not have) and is type-checked on its own with
+`bunx tsc -p viewer --noEmit`. `bun run lint` covers it like everything else.
+
 ## What exists today
 
 **Inputs — three files, one domain each.** Only the middle one is required.
@@ -249,7 +300,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 32 named assertions over the loaded skeleton. Each one exists because
+and then runs 34 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
@@ -257,7 +308,7 @@ 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
+Not all 34 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 —
@@ -270,8 +321,8 @@ 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? |
+| `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? |
 
 The **Profile** column below says which is which — `both` = validity, `renderer` and
 `archetype` = `spine-html` only, and **`both ◑`** = a mixed assertion whose validity
@@ -315,6 +366,8 @@ the renderer policy*.
 | `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 |
+| `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
 
@@ -347,6 +400,174 @@ 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.
+
 ## Usage
 
 📘 **Writing a spec? Read [docs/AUTHORING.md](docs/AUTHORING.md) first.** It is the
@@ -508,7 +729,7 @@ 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
+  validate.ts   spine-core round trip + the 34 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,
@@ -530,6 +751,10 @@ bench/          count_features.ts — what the example corpus actually uses
                 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)
+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),
                 SPEC_COVERAGE.md (format survey),
                 feature_matrix.{csv,json}

package/cli.ts

@@ -358,8 +358,14 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
  *
  * There is no pass mark, for the same reason `diff` has none.
  */
-function readCheckFlags(flags: Record<string, string>): Pick<CheckOptions, 'fps' | 'viewport' | 'as'> {
-  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as'> = {};
+function readCheckFlags(flags: Record<string, string>): Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing'> {
+  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing'> = {};
+  if (flags.framing !== undefined) {
+    if (flags.framing !== 'per-shot' && flags.framing !== 'shared') {
+      throw new UsageError('--framing takes per-shot (the default) or shared');
+    }
+    out.framing = flags.framing;
+  }
   if (flags.fps !== undefined) {
     const fps = Number(flags.fps);
     if (!Number.isFinite(fps) || fps <= 0) throw new UsageError('--fps must be a positive number');
@@ -503,6 +509,13 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
     // summary that reported those numbers without saying how the two shots were
     // put on each other is how issue #34 stayed invisible for two ladder runs.
     const framing = check.framingFit;
+    if (!framing && check.sharedFraming) {
+      const f = check.sharedFraming.fit;
+      console.log(
+        `  framing    one per set (${check.animations.length}); one shared box leaves ` +
+          `x${f.scale.toFixed(6)}, rms ${f.rms.toFixed(2)}px — see the check table above for each set's own`,
+      );
+    }
     if (framing) {
       const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
       const how = !framing.applied
@@ -528,9 +541,19 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
         anim.changeDisagreements === 0
           ? ''
           : `, ${anim.changeDisagreements}/${anim.changePairs} pair(s) change unlike the reference`;
+      // Which of the candidate's own bone chains the error is in — one name, so a
+      // loop between builds reads a unit to fix rather than a verdict on the shot.
+      // The full table is in `check`'s own report; this is its headline.
+      const worstChain = [...anim.chains].sort((a, b) => b.maeShare - a.maeShare)[0];
+      const chain =
+        worstChain === undefined ? '' : `, ${worstChain.chain} carries ${(worstChain.maeShare * 100).toFixed(0)}%`;
+      // `ref=` is the same difference over the reference's own drawn pixels. It is
+      // carried here and not only in `check`'s own table because this is the line a
+      // loop reads between builds, and `mean=` has a denominator the candidate can
+      // grow — see `FrameCheck.maeReference`.
       console.log(
-        `  ${anim.dir.padEnd(10)} MAE mean=${anim.meanMae.toFixed(2)} worst=${anim.worstMae.toFixed(2)}  ` +
-          `over ${anim.compared} frame(s)  ${drift}${change}`,
+        `  ${anim.dir.padEnd(10)} MAE mean=${anim.meanMae.toFixed(2)} worst=${anim.worstMae.toFixed(2)} ` +
+          `ref=${anim.meanMaeReference.toFixed(2)}  over ${anim.compared} frame(s)  ${drift}${change}${chain}`,
       );
     }
   } else {
@@ -541,10 +564,17 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
   console.log('  a rung is cleared by a person reading the measures, and docs/LADDER.md records it.');
 
   if (flags.json !== undefined) {
+    // No `gates` field, deliberately. The rung's gate string names its features
+    // and its per-skeleton counts, which `bench/runs/README.md` forbids a run
+    // from reading — and this report is one of the six files the run protocol
+    // requires committing, so a copy of it here would sit inside every future
+    // run's directory, which is exactly where the next author looks for process
+    // notes. `rung` identifies the rung and carries nothing (issue #137). The
+    // console block above still prints the gate string: that is for the person
+    // reading the run, not a file the protocol commits.
     writeJson(flags.json, {
       rung: rung.id,
       example: rung.example,
-      gates: rung.gates,
       profile,
       candidate: { skeleton: skeletonPath, atlas: atlasPath },
       validate: report,
@@ -700,6 +730,10 @@ const USAGE = [
   '  --atlas <path>        the candidate\'s atlas, when it is not beside the skeleton',
   '  --fps <n>             only for a frame set with no frames.json sidecar',
   '  --viewport x,y,w,h    pin the candidate\'s world box, y up, instead of fitting it',
+  '  --framing per-shot|shared   decide the framing per frame set (default), or once',
+  '                        across all of them. Per set, a set whose own pixels land in',
+  '                        frames.json\'s box is measured there; on a multi-shot root that',
+  '                        is worth 15-25 MAE against one shared fit for every set',
   '  --as <name>           the candidate animation to play, when it is named differently',
   '  --all-frames          print every frame, not just the worst by MAE',
   '  --json <out>          the whole per-frame, per-slot report',