spine-rigc 0.2.1 → 0.3.0

package/docs/SPEC_COVERAGE.md

@@ -522,6 +522,9 @@ Legend: ✅ emits · 🟡 partial · ❌ not emitted · 🚫 deliberately exclud
 
 ### 2.1 Coverage against Part 1
 
+> 🔄 **Re-synced 2026-08-23** against `src/compile.ts`/`src/rig.ts` on `main`. Only the rows below
+> were touched; the rest of this table was not re-verified in this pass.
+
 **Header** (`compile.ts:634-646`)
 
 | Part-1 row | rigc | Note |
@@ -530,7 +533,8 @@ Legend: ✅ emits · 🟡 partial · ❌ not emitted · 🚫 deliberately exclud
 | `x`, `y` | ✅ | always literal `0, 0` |
 | `width`, `height` | ✅ | from `manifest.crop.w/h` |
 | `hash` | ❌ | never emitted (harmless; the parser stores it and nothing reads it) |
-| `fps`, `images`, `audio`, `referenceScale` | ❌ | |
+| `fps`, `images`, `referenceScale` | ✅ | copied from `rig.skeleton` when the rig spec gives them, omitted when it does not (`compile.ts:810-812`, landed in `c5eda3b`) |
+| `audio` | ❌ | |
 
 **Bones** (`compile.ts:367-456`; type at `types.ts:285-292`)
 
@@ -551,7 +555,7 @@ Legend: ✅ emits · 🟡 partial · ❌ not emitted · 🚫 deliberately exclud
 | `attachment` | ✅ — only when the motion spec's `setup` block names one; `null` means "show nothing" and the key is omitted |
 | `color` | ✅ — from `setup.color`, hex-encoded (`compile.ts:63-66`) |
 | `dark` | 🚫 **A12_NO_DARK_COLOR** (`validate.ts:250-262`) |
-| `blend` | ❌ |
+| `blend` | ✅ — copied from the rig spec's slot when it gives one (`compile.ts:600`, landed in `c5eda3b`) |
 | `visible` | ❌ |
 | draw order = slots array order | ✅, and **A26_SLOT_DRAW_ORDER** pins it to the archetype's `slotOrder` table |
 
@@ -564,11 +568,11 @@ Legend: ✅ emits · 🟡 partial · ❌ not emitted · 🚫 deliberately exclud
 | --- | --- | --- |
 | `region` | 🟡 | emits `width`, `height` (always, from PNG measurement — the fix for case 6c), `x`, `y` (only when non-zero), `rotation` (only when non-zero, cancelling the bone's world rotation). ❌ `path` (region name == attachment name == PNG basename, enforced by **A08** + **A27**), ❌ `scaleX`/`scaleY`, ❌ `color`, ❌ `sequence` |
 | `mesh` | 🟡 | emits `type`, `uvs`, `triangles`, `vertices` (**weighted encoding only**), `hull`, `width`, `height`. ❌ `edges`, ❌ `path`, ❌ `color`, ❌ `sequence`. Unweighted meshes are 🚫 **A20_MESH_WEIGHTS_COHERENT** (`validate.ts:430-433`) |
-| `linkedmesh` | ❌ | |
-| `boundingbox` | ❌ | |
-| `path` | ❌ | |
-| `point` | ❌ | |
-| `clipping` | 🚫 | **A11_NO_CLIPPING_ATTACHMENTS** (`validate.ts:373-377`) |
+| `linkedmesh` | ❌ | deliberately deferred — never appears in the corpus (part 3-1) |
+| `boundingbox` | ✅ | `vertexCount` (required and cross-checked), `vertices` **or** by-name `weights`, `color`. **A33_VERTEX_ATTACHMENT_GEOMETRY** |
+| `path` | ❌ | deliberately deferred — never appears in the corpus (part 3-1) |
+| `point` | ❌ | deliberately deferred — never appears in the corpus (part 3-1) |
+| `clipping` | ✅ under `--profile spine` · 🚫 under `spine-html` | `end` (refused when it names no slot), `convex`, `inverse`, `vertexCount`, geometry, `color`. **A33**, and **A11_NO_CLIPPING_ATTACHMENTS** is the renderer-profile refusal |
 | `sequence` block | ❌ | |
 
 Mesh geometry is generated by exactly two procedural generators (`mesh.ts`): `buildRingMesh`
@@ -580,8 +584,8 @@ chain). There is **no triangulator for arbitrary art** and no importer for edito
 | Part-1 type | rigc |
 | --- | --- |
 | `physics` | ✅ — full field set: `bone`, the five components `x`/`y`/`rotate`/`scaleX`/`shearX`, and `inertia`/`strength`/`damping`/`mass`/`wind`/`gravity`/`mix`/`fps`/`limit`. Values equal to the parser default are **omitted** (`compile.ts:555-559`). ❌ `scaleY` (ScaleYMode), ❌ the seven `*Global` flags, ❌ `skin` |
-| `ik` | ❌ |
-| `transform` | ❌ |
+| `ik` | ✅ — `bones`, `target`, `scaleY`/`mix`/`softness`/`bendPositive`/`compress`/`stretch`/`skin` (`compile.ts:1425-1430`, landed in `c5eda3b`) |
+| `transform` | ✅ — `bones`, `source`, the 4.3 `properties{from→to}` model, and the full field set (`compile.ts:1431-1462`, landed in `c5eda3b`) |
 | `path` | ❌ |
 | `slider` | ❌ |
 | flat `constraints[]` shape | ✅ — and **A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS** actively rejects the 4.1/4.2 shape (`validate.ts:225-235`), which is the machine form of case 6a |
@@ -602,7 +606,7 @@ chain). There is **no triangulator for arbitrary art** and no importer for edito
 | `attachments.<skin>.…deform` | ❌ (validator knows it: 1 channel, `validate.ts:104-107`) |
 | `attachments.…sequence` | ❌ |
 | `drawOrder`, `drawOrderFolder` | ❌ |
-| `events` (+ the `root.events` block) | ❌ |
+| `events` (+ the `root.events` block) | ✅ — the rig spec declares the names (`rig.ts` `RigEvent`), the motion spec's per-animation `events` array fires them, and **A32_EVENT_KEYS_RESOLVE** checks the three ways the timeline goes wrong quietly. `int`/`float`/`string` overrides and `audio`/`volume`/`balance` all round-trip |
 | animation `color` | ❌ |
 
 **Curves** — ✅ all three encodings. Linear = no `curve` key; `"stepped"` passes through as the string
@@ -663,6 +667,8 @@ This is the split Part 4(c) needs. **Spine-validity** = the file is wrong for an
 | `A24_AXIS_SPACE_STROKE` | archetype | screen-space stroke keys |
 | `A25_DETACHED_BONE_PARENTAGE` | archetype | a bone the rig declares detached, parented under the bone it must stay clear of |
 | `A26_SLOT_DRAW_ORDER` | archetype | draw order ≠ the archetype's slot table |
+| `A32_EVENT_KEYS_RESOLVE` | validity | an event key firing an undeclared name (parser throws), key times going backwards (silent — frames are filled in array order), `volume`/`balance` on an event with no `audio` (silent) |
+| `A33_VERTEX_ATTACHMENT_GEOMETRY` | validity | a bounding box or clipping polygon with a missing or disagreeing `vertexCount` (`undefined << 1` = 0, so the coordinates are decoded as a weight run), a weighted run of the wrong length, an out-of-range bone index, or a clipping `end` naming no slot (`findSlot` returns null and the null is assigned) |
 | `A27_REGION_NAME_MATCHES_PAGE_FILENAME` | policy | region name ≠ PNG basename |
 | `A28_RIBBON_ROWS_SHARE_WEIGHTS` | archetype | ribbon rows with divergent weights |
 | `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | stroke past the measured contact depth |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {
@@ -51,6 +51,7 @@
     "lint": "bunx eslint .",
     "fetch-examples": "bash scripts/fetch-examples.sh",
     "bench:usage": "bun bench/count_features.ts",
+    "viewer": "vite --config viewer/vite.config.ts",
     "prepublishOnly": "bun run typecheck && bun run lint && bun run selftest"
   },
   "dependencies": {
@@ -59,7 +60,9 @@
   "devDependencies": {
     "@types/bun": "^1.4.0",
     "eslint": "^10.9.0",
+    "spine-html": "^0.4.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.67.0"
+    "typescript-eslint": "^8.67.0",
+    "vite": "^8.2.2"
   }
 }

package/src/chains.ts

@@ -0,0 +1,170 @@
+/**
+ * Bone chains — the unit an author actually repairs.
+ *
+ * ## Why a figure needs more than one number per shot
+ *
+ * `check` reports a shot's MAE and its worst slot. On a ball that is the whole
+ * story. On a figure with a dozen joints it is a verdict with nowhere to put it:
+ * spineboy's second attempt read "structure ✅, motion ✗" across sixteen sets, and
+ * the fix that verdict implies is *"animate it again"*. What an author repairs is
+ * a **limb** — the gun arm, the front leg — so the report has to be able to say
+ * which limb the error is in, and how much of it (issue #123).
+ *
+ * The decomposition is **candidate-side**, and that is not an implementation
+ * detail. `docs/LADDER.md`'s honesty rule says the reference is pixels; a chain
+ * derived from the reference skeleton would be `check` reading the answer. So the
+ * chains here come from the candidate's own bone tree — its own idea of what its
+ * parts are — and the reference stays a picture that gets carved up by where the
+ * candidate drew.
+ *
+ * ## The rule
+ *
+ * **Cut the bone tree at every branch point.** A chain starts at a root bone or
+ * at a child of a bone with more than one child, and runs down while each bone it
+ * reaches has exactly one child. On a biped that is exactly the set of parts an
+ * author names: `front-thigh → front-shin → front-foot`, `rear-upper-arm →
+ * rear-bracer → gun → muzzle`, `neck → head`. On a serial figure with no branch
+ * at all — rung 8's pendulum, seven bones in a line — it is one chain, which is
+ * the honest answer: a pendulum *has* one chain, and the per-slot table below it
+ * still names which link drifted.
+ *
+ * **A single-bone chain that is itself a branch point folds into its parent
+ * chain.** Without this, spineboy's `torso` — one bone with three children — is a
+ * chain of its own carrying one slot, and the trunk above it (`root`, `hip`) is a
+ * chain carrying none: two rows that between them say what one row says. With it
+ * the trunk reads `root, hip, torso` and the figure decomposes into six chains
+ * that each own a limb.
+ *
+ * ⚠️ **Only when it is a branch point.** A single-bone chain that is a *leaf* is a
+ * real part — a one-bone arm, or rung 3's two independent bones under one root —
+ * and folding those would collapse the whole fixture into a single chain and
+ * attribute nothing. The rule keys on "does this bone branch", not on length.
+ *
+ * A chain is **named after the first bone in it that carries a slot**, root-ward
+ * first, falling back to its first bone when none does. Membership never depends
+ * on the name: it is a label, chosen so the roster reads `torso` rather than
+ * `root`. Bone names are unique in a skeleton, so chain names are too.
+ */
+
+/** One bone, as much of it as a chain cares about. */
+export interface BoneNode {
+  name: string;
+  /** The parent's name, or `null` for a root bone. */
+  parent: string | null;
+}
+
+/** One slot, as much of it as a chain cares about. */
+export interface SlotNode {
+  name: string;
+  /** The bone it hangs from. */
+  bone: string;
+}
+
+/** A run of bones cut out of the tree at its branch points, and what it draws. */
+export interface BoneChain {
+  /** The first bone in it that carries a slot, else its first bone. */
+  name: string;
+  /** Its bones, root-ward first. */
+  bones: string[];
+  /** The slots those bones carry, in the skeleton's own slot order. */
+  slots: string[];
+}
+
+interface Building {
+  bones: string[];
+  slots: string[];
+  /** Set when this chain was folded away into another. */
+  foldedInto: number | null;
+}
+
+/**
+ * Cut a bone tree into chains — see the rule at the top of this file.
+ *
+ * Deterministic in the order the bones arrive: chains come back in the order
+ * their first bone appears, and a bone that folds is appended to its parent
+ * chain's list. Both matter, because the roster is printed and a report that
+ * reorders itself between runs is a report nobody can diff.
+ */
+export function chainsOf(bones: BoneNode[], slots: SlotNode[]): BoneChain[] {
+  const order = new Map<string, number>();
+  for (const bone of bones) if (!order.has(bone.name)) order.set(bone.name, order.size);
+
+  const children = new Map<string, string[]>();
+  for (const bone of bones) {
+    if (bone.parent === null || !order.has(bone.parent)) continue;
+    const list = children.get(bone.parent);
+    if (list) list.push(bone.name);
+    else children.set(bone.parent, [bone.name]);
+  }
+  const childrenOf = (name: string): string[] => children.get(name) ?? [];
+
+  // A chain starts at a root, or wherever the tree forked above it.
+  const starts = bones.filter((b) => b.parent === null || !order.has(b.parent) || childrenOf(b.parent).length > 1);
+
+  const built: Building[] = [];
+  const chainOfBone = new Map<string, number>();
+  for (const start of starts) {
+    const run = [start.name];
+    let at = start.name;
+    for (;;) {
+      const next = childrenOf(at);
+      if (next.length !== 1) break;
+      at = next[0];
+      run.push(at);
+    }
+    const index = built.length;
+    built.push({ bones: run, slots: [], foldedInto: null });
+    for (const bone of run) chainOfBone.set(bone, index);
+  }
+
+  // Fold the hubs. Root-ward first, so a chain's parent is already final when it
+  // is asked for — and through `resolve`, so a hub whose own parent folded lands
+  // in the chain that absorbed it rather than in one that no longer exists.
+  const resolve = (index: number): number => {
+    let at = index;
+    while (built[at].foldedInto !== null) at = built[at].foldedInto as number;
+    return at;
+  };
+  const byDepth = built
+    .map((chain, index) => ({ index, at: order.get(chain.bones[0]) as number }))
+    .sort((a, b) => a.at - b.at);
+  for (const { index } of byDepth) {
+    const chain = built[index];
+    if (chain.bones.length !== 1) continue;
+    const only = chain.bones[0];
+    // A leaf that stands alone is a part in its own right; a hub is not.
+    if (childrenOf(only).length === 0) continue;
+    const parent = bones.find((b) => b.name === only)?.parent ?? null;
+    if (parent === null || !chainOfBone.has(parent)) continue;
+    const target = resolve(chainOfBone.get(parent) as number);
+    if (target === index) continue;
+    built[target].bones.push(only);
+    chain.foldedInto = target;
+    chainOfBone.set(only, target);
+  }
+
+  for (const slot of slots) {
+    const owner = chainOfBone.get(slot.bone);
+    if (owner === undefined) continue;
+    built[resolve(owner)].slots.push(slot.name);
+  }
+
+  return built
+    .filter((chain) => chain.foldedInto === null)
+    .map((chain) => ({
+      name: chain.bones.find((bone) => chain.slots.some((slot) => slotBone(slots, slot) === bone)) ?? chain.bones[0],
+      bones: chain.bones,
+      slots: chain.slots,
+    }));
+}
+
+function slotBone(slots: SlotNode[], name: string): string | null {
+  return slots.find((slot) => slot.name === name)?.bone ?? null;
+}
+
+/** The chain each slot belongs to, keyed by slot name. */
+export function chainBySlot(chains: BoneChain[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const chain of chains) for (const slot of chain.slots) out.set(slot, chain.name);
+  return out;
+}