spine-rigc 0.4.0 → 0.6.0

package/docs/PROMPTING.md

@@ -0,0 +1,106 @@
+# Prompting an AI to author with rigc
+
+This page is for the person **operating** an AI agent — any AI agent — that will
+author a rig with rigc. It is not authoring guidance; that is
+[AUTHORING.md](AUTHORING.md), and the agent should read that file, not this one.
+This page tells you what to put in the prompt, and it earns its claims from a
+measured case: in August 2026 a deliberately small model — Gemini 3.7 Flash on
+the Antigravity harness — authored a benchmark rung unattended for three hours,
+and every stumble below is one it actually made, priced by the instruments in
+[PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md)'s protocol. A large model makes fewer of these mistakes
+unprompted; the clauses cost you three lines and make the small model's run
+land and the large model's run land cleaner.
+
+## The prompt skeleton
+
+For ordinary use (not a benchmark), the whole prompt is short:
+
+> Author a Spine rig with rigc for <what you want>. The images are in
+> `<dir>`. Read `docs/AUTHORING.md` in full before writing either spec —
+> sections 1–5 are the two file formats and the failure map, section 8 is how
+> to fit poses against picture references, section 10 is the editor's
+> conventions. Build with `rigc build`, keep going until `rigc validate` is
+> green, and treat every named failure as pointing at the file to change.
+
+Then add the clauses below. If you are running the **benchmark**, do not
+improvise a prompt at all — hand the agent
+[pilot/rung3-runner-prompt.md](https://github.com/firejune/rigc/blob/main/docs/pilot/rung3-runner-prompt.md) verbatim; it
+carries the honesty rule, and an improvised summary of that rule is how a run
+stops being scorable.
+
+## Five clauses the pilot paid for
+
+**1. Any search loop must print progress and carry a time-box.**
+The pilot wrote a pose-fitting script with no output and no bound, and its
+operator spent part of the evening deciding whether a silent 99 %-CPU process
+was working or hung. (It was working — but nobody could tell.) Say:
+
+> Long-running scripts must print one progress line per unit of work and state
+> an expected total up front. If a search would exceed ten minutes, stop and
+> narrow it instead.
+
+**2. Intermediate results go to files, not scrollback.**
+The pilot's first fitters printed results to stdout; a crashed step would have
+lost the lot. It later switched to JSON files on its own — start there. Say:
+
+> Write measured values (placements, angles, fitted poses) to files in the
+> working directory as you go. Treat your transcript as disposable.
+
+**3. Point the fitting method at AUTHORING §8, by number.**
+Given frames to match, the pilot's first instinct was a nested grid over every
+knob at once — tens of thousands of renders per frame. §8 describes the cheap
+loop (one knob at a time, render back, keep what the measurement keeps). The
+pilot had the file "in hand" and did not apply the section until it had burned
+hours. Say:
+
+> Fit poses the way AUTHORING §8 does — one variable at a time against a
+> render-back measurement. Do not grid-search several knobs jointly.
+
+**4. Keys are structure, not samples.**
+A fitter produces one pose per frame, and the pilot keyed nearly every one of
+them. The result *placed* its parts well — and still scored poorly on every
+timing measure, because animation data is sparse keys plus interpolation
+(AUTHORING §10.3–§10.4), and a key on every frame is a pixel transcription
+wearing a skeleton. Say:
+
+> Key extremes and contacts, then let curves carry the in-betweens, per
+> AUTHORING §10.3–10.4. If your fitted poses disagree with a curve, move the
+> curve, not key count. Also §4.4: when a bone's two axes need different
+> timing or easing, key the single-axis timelines, not the paired one.
+
+**5. Keep the loop log live.**
+The pilot wrote its `LOOP.md` at the end, from memory — two entries for a
+three-hour session, with eight generations of fitting scripts invisible
+between them. A log written afterwards records the story, not the work. Say:
+
+> Append to `LOOP.md` at the moment each build/measure/change step happens,
+> not at the end. One line per step is enough.
+
+**6. Make the agent typecheck its own helper scripts.**
+Bun strips types and runs, so an agent can call methods that do not exist and
+watch the script fail — or worse, silently misbehave — without ever learning
+the API was imagined. The pilot left behind a helper written against
+spine-core methods that were never real; the repository's `typecheck` gate
+caught it at landing, hours too late to help the run. Say:
+
+> After writing any helper script, run `bunx tsc --noEmit <file>` (or the
+> project's `typecheck` task) before trusting its output.
+
+## What you do not need to say
+
+The same pilot, unprompted, did all of this correctly: it looped
+`build → validate` until green and read the named failures as pointers; it ran
+the whole thing without a human answer for three hours; it killed its own
+stray processes; it recorded its model name honestly; and under the benchmark
+protocol it ran the scored diff exactly once, at the end, editing nothing
+after. The tool's own error surface carries that part of the conversation —
+prompt for the five clauses above and then let the agent work.
+
+## If you are scoring the run
+
+That is a different document: [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is the protocol,
+`pilot/rung3-runner-prompt.md` is the exact prompt, and the evaluator sheet it
+names is for the judge only. The one rule that reaches this page: **never put
+baseline figures, reference structure, or previous runs' measures into the
+runner's prompt** — a number in the prompt is a target, and a run that aimed
+at a target measured nothing.

package/docs/SPEC_COVERAGE.md

@@ -5,18 +5,20 @@ what rigc emits today, and what the official example projects actually use — s
 ordered by what the benchmark ladder needs rather than by the spec's alphabet.
 
 Reproduce the measurements with `bun run fetch-examples && bun run bench:usage`
-([`bench/count_features.ts`](../bench/count_features.ts) → [`feature_matrix.csv`](feature_matrix.csv),
-[`feature_matrix.json`](feature_matrix.json)).
+([`bench/count_features.ts`](https://github.com/firejune/rigc/blob/main/bench/count_features.ts) → [`feature_matrix.csv`](https://github.com/firejune/rigc/blob/main/docs/feature_matrix.csv),
+[`feature_matrix.json`](https://github.com/firejune/rigc/blob/main/docs/feature_matrix.json)).
 
 > 🔼 **This note is dated and does not move; the measurements below are the corpus as it
 > stood on 2026-08-22 and stay as written. Its statements about what rigc *does* have gone
-> stale in five places, and the live ledger is [LADDER.md](LADDER.md):**
+> stale in five places, and the live ledger is [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md):**
 >
 > - **B2 is fixed** — A16 accepts `4.3`, `4.3.N` and `4.3.N-<suffix>`, so all twelve example
 >   exports pass it.
-> - **The profile split exists** — `--profile spine | spine-html`, default `spine-html`, so the
->   nine renderer-policy assertions of §2.2 no longer apply to foreign data. That closes the
->   validator half of B3; the emitter half (no packer, no atlas importer) is untouched.
+> - **The profile split exists** — `--profile spine | spine-html`, **default `spine` since
+>   2026-08-29** (issue #221; it was `spine-html` when this survey was written), so the nine
+>   renderer-policy assertions of §2.2 no longer apply to foreign data, and no longer apply
+>   unasked. That closes the validator half of B3; the emitter half (no packer, no atlas
+>   importer) is untouched.
 > - **`walkTimelines` reaches all eleven groups** — §2.3 item 1 and §4.3 item 4 are done, so
 >   A05 is no longer blind to `ik` / `transform` / `path` / `slider` / `drawOrder` /
 >   `drawOrderFolder` / `events`.
@@ -25,7 +27,7 @@ Reproduce the measurements with `bun run fetch-examples && bun run bench:usage`
 >   attachments, the 4.3 typed constraint array and the invariants, all as data. So §2.4's
 >   "the bone tree is code, not data", §4.0's B1 row and executive-summary item 7 describe a
 >   state that no longer exists. Rung 3 transcribed into that format scores 1.000 on every
->   measure of every section — figures in [LADDER.md](LADDER.md).
+>   measure of every section — figures in [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
 > - Since that change rigc also emits **ik and transform constraints**, the **single-axis bone
 >   timelines** (`translatex`/`translatey`/`scalex`/`scaley`/`shear`/`shearx`/`sheary`), bone
 >   `length`/`scale`/`shear`/`inherit`/`skin`/`color` setup fields, slot `dark`/`blend`, region
@@ -659,7 +661,7 @@ This is the split Part 4(c) needs. **Spine-validity** = the file is wrong for an
 | `A12_NO_DARK_COLOR` | **renderer-profile** | slot `dark`, `rgba2`/`rgb2` timelines — "parsed, then ignored" |
 | `A13_MESH_BUDGET` | **renderer-profile** | >4 mesh slots, >80 triangles per mesh |
 | `A14_NO_FULL_FRAME_MESH` | **renderer-profile** | a mesh spanning the whole stage |
-| `A19_OVERLAY_PNGS_HAVE_ALPHA` | **renderer-profile** | an overlay page with no alpha channel |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | **renderer-profile** | an overlay page that can never be transparent — no alpha channel and no `tRNS` chunk |
 | `A20_MESH_WEIGHTS_COHERENT` | **renderer-profile / archetype** | **unweighted meshes**, weights not summing to 1, out-of-range bone indices |
 | `A21_MESH_RIM_PINNED` | archetype | ring/ribbon rim not pinned |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | validity-ish | UVs outside 0..1 |
@@ -716,7 +718,7 @@ one.
 
 > 🔼 Both halves of that paragraph are now stale. The walker reaches all eleven groups and the
 > mutants that prove it exist; the suite runs on fixtures it **generates**, so it needs no
-> project's art. Current shape: [CLAUDE.md](../CLAUDE.md), *The selftest and its fixtures*.
+> project's art. Current shape: [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md), *The selftest and its fixtures*.
 
 ### 2.4 The input model — where the rig actually comes from
 
@@ -751,10 +753,10 @@ The manifest supplies *positions* for those bones (`anchors`), never their *name
 ## Part 3 — what the example ladder actually uses
 
 Corpus: the nine official example projects on branch `4.3`, fetched by
-[`scripts/fetch-examples.sh`](../scripts/fetch-examples.sh) into the gitignored `examples/<name>/`
+[`scripts/fetch-examples.sh`](https://github.com/firejune/rigc/blob/main/scripts/fetch-examples.sh) into the gitignored `examples/<name>/`
 (**12 skeleton JSON files** — some examples ship more than one — **10 `.atlas` files**, 8 `license.txt`).
-Counted by [`bench/count_features.ts`](../bench/count_features.ts); full output in
-[`feature_matrix.json`](feature_matrix.json) and [`feature_matrix.csv`](feature_matrix.csv)
+Counted by [`bench/count_features.ts`](https://github.com/firejune/rigc/blob/main/bench/count_features.ts); full output in
+[`feature_matrix.json`](https://github.com/firejune/rigc/blob/main/docs/feature_matrix.json) and [`feature_matrix.csv`](https://github.com/firejune/rigc/blob/main/docs/feature_matrix.csv)
 (12 rows × 135 columns), both regenerated by `bun run bench:usage`.
 
 > ⚠️ **Verification note.** The timeline columns below were re-derived independently from the raw JSON
@@ -913,7 +915,7 @@ Crossing Part 2 with Part 3. Categories, as requested:
 **(d) JSON-inexpressible** — things the format genuinely cannot hold.
 
 **Nothing below was implemented when this was written. This is a survey.** Three of its items
-have been built since — see the banner at the top of this document and [LADDER.md](LADDER.md) for
+have been built since — see the banner at the top of this document and [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) for
 which; the requirement text itself is left exactly as surveyed.
 
 ### 4.0 Three blockers that precede rung 1
@@ -977,7 +979,7 @@ Nothing structurally new (attachment timeline, blend, inherit all arrived by run
 #### Rung 6 — `6-arcs`
 
 > ✅ **Measured, 2026-08-23.** The rows below were written as predictions; the
-> transcription in [`bench/transcriptions/6-arcs/`](../bench/transcriptions/6-arcs/)
+> transcription in [`bench/transcriptions/6-arcs/`](https://github.com/firejune/rigc/tree/main/bench/transcriptions/6-arcs/)
 > settled them. It compiles green under `--profile spine` and `bench 6` reports
 > **1.000 on all 44 measures in all six sections**, so the rig spec expresses this
 > skeleton — weighted meshes, `edges` and the 4.3 transform constraints alike. A

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "spine-rigc",
-  "version": "0.4.0",
+  "version": "0.6.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": {
-    "rigc": "./cli.ts"
+    "rigc": "./bin/rigc.cjs"
   },
   "engines": {
     "bun": ">=1.2.0"
@@ -31,12 +31,14 @@
     "cli"
   ],
   "files": [
+    "bin/rigc.cjs",
     "cli.ts",
     "src",
     "tools/plate.ts",
     "tools/font5x7.ts",
     "docs/AUTHORING.md",
     "docs/SPEC_COVERAGE.md",
+    "docs/PROMPTING.md",
     "NOTICE.md"
   ],
   "publishConfig": {

package/src/compile.ts

@@ -21,6 +21,7 @@ import { basename, dirname, relative, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { readPngInfo } from './png.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { parseJsonWithPosition } from './json-position.ts';
 import {
   parseRigSpec,
   type RigAttachment,
@@ -255,8 +256,17 @@ export function bezierForChannel(
 // ---------------------------------------------------------------------------
 
 function readJson<T>(path: string): T {
+  let text: string;
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+  try {
+    // A parse failure gets a line/column appended to the runtime's own
+    // message — see `parseJsonWithPosition` for why `JSON.parse` alone
+    // cannot say where.
+    return parseJsonWithPosition(text) as T;
   } catch (err) {
     throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
   }
@@ -319,6 +329,36 @@ export interface CompileOptions {
   imagesDir?: string;
 }
 
+/**
+ * One part = one page. No packer, so no PMA trap, no rotation, no strip
+ * offsets. Region covers the page exactly => u2=v2=1.
+ *
+ * Two text-shape traps are load-bearing here:
+ *   * a region name is the RAW line, not a trimmed one -> no indentation;
+ *   * a blank line closes the page block -> none between header and regions.
+ *
+ * Exported (rather than inlined into `compile`) so `--copy-images` can call it a
+ * second time with `page` rewritten to the copies' filenames, after the copy
+ * itself has happened — see [`src/emit.ts`](emit.ts). Everything else about an
+ * image (`region`, `width`, `height`) is unchanged by that rewrite; only where the
+ * bytes live moved.
+ */
+export function buildAtlasText(images: CompiledImage[]): string {
+  const atlasLines: string[] = [];
+  images.forEach((img, i) => {
+    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
+    atlasLines.push(img.page);
+    atlasLines.push(`size: ${img.width}, ${img.height}`);
+    atlasLines.push('filter: Linear, Linear');
+    atlasLines.push('pma: false');
+    atlasLines.push(img.region);
+    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push('rotate: 0');
+  });
+  return `${atlasLines.join('\n')}\n`;
+}
+
 export function compile(opts: CompileOptions): CompileResult {
   const rigPath = resolve(opts.rigPath);
   const motionPath = resolve(opts.motionPath);
@@ -330,17 +370,38 @@ export function compile(opts: CompileOptions): CompileResult {
   const motion = readJson<MotionSpec>(motionPath);
   const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
 
-  if (motion.spec !== 'rigc-motion/1') {
-    throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
-  }
-  // The motion spec was authored against one formation. Pairing it with another
-  // rig would aim its keys at bones whose names happen to match and whose meaning
-  // does not — the class of wrongness that loads, plays and lies.
-  if (motion.archetype !== rig.name) {
-    throw new CompileError(
-      `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
-    );
-  }
+  // The rig spec names its own path in every message `parseRigSpec` throws (its
+  // `where` argument, above). The motion spec gets no such treatment below —
+  // every "animation … bone … property" refusal is built from data alone — so a
+  // reader with two input files and one error has no way to tell which one is at
+  // fault. This wraps the motion-only regions (the version/archetype check right
+  // below, the physics table and the animation loop further down) and prefixes
+  // the motion path onto any `CompileError` that escapes them, unless the
+  // message already names it.
+  const withMotionSource = <T>(fn: () => T): T => {
+    try {
+      return fn();
+    } catch (err) {
+      if (err instanceof CompileError && !err.message.includes(motionPath)) {
+        throw new CompileError(`${motionPath}: ${err.message}`);
+      }
+      throw err;
+    }
+  };
+
+  withMotionSource(() => {
+    if (motion.spec !== 'rigc-motion/1') {
+      throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
+    }
+    // The motion spec was authored against one formation. Pairing it with another
+    // rig would aim its keys at bones whose names happen to match and whose meaning
+    // does not — the class of wrongness that loads, plays and lies.
+    if (motion.archetype !== rig.name) {
+      throw new CompileError(
+        `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
+      );
+    }
+  });
 
   // The stage. The rig may state it outright (a foreign skeleton has no crop);
   // otherwise the manifest's crop is it. With neither there is nothing to
@@ -546,25 +607,7 @@ export function compile(opts: CompileOptions): CompileResult {
   }
 
   // -- 2. atlas --------------------------------------------------------------
-  // One part = one page. No packer, so no PMA trap, no rotation, no strip
-  // offsets. Region covers the page exactly => u2=v2=1.
-  //
-  // Two text-shape traps are load-bearing here:
-  //   * a region name is the RAW line, not a trimmed one -> no indentation;
-  //   * a blank line closes the page block -> none between header and regions.
-  const atlasLines: string[] = [];
-  images.forEach((img, i) => {
-    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
-    atlasLines.push(img.page);
-    atlasLines.push(`size: ${img.width}, ${img.height}`);
-    atlasLines.push('filter: Linear, Linear');
-    atlasLines.push('pma: false');
-    atlasLines.push(img.region);
-    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push('rotate: 0');
-  });
-  const atlasText = `${atlasLines.join('\n')}\n`;
+  const atlasText = buildAtlasText(images);
 
   // -- 3. bones --------------------------------------------------------------
   //
@@ -728,128 +771,132 @@ export function compile(opts: CompileOptions): CompileResult {
     constraints.push(buildRigConstraint(spec as RigConstraintInput, boneNames));
     constraintNames.add(spec.name);
   }
-  for (const [name, spec] of Object.entries(motion.physics ?? {})) {
-    if (constraintNames.has(name)) {
-      throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
-    }
-    constraintNames.add(name);
-    if (!boneNames.has(spec.bone)) {
-      throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
-    }
-    const entry: SpineConstraint = {
-      name,
-      type: 'physics',
-      bone: spec.bone,
-    };
-    const components: string[] = [];
-    for (const comp of PHYSICS_COMPONENTS) {
-      const v = spec[comp];
-      if (v === undefined || v === 0) continue;
-      entry[comp] = r6(v);
-      components.push(comp);
-    }
-    if (!components.length) {
-      // The parser is happy with this and the constraint does nothing at all.
-      // A23 catches it too; refusing here means it never reaches the gate.
-      throw new CompileError(
-        `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
-      );
+  withMotionSource(() => {
+    for (const [name, spec] of Object.entries(motion.physics ?? {})) {
+      if (constraintNames.has(name)) {
+        throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
+      }
+      constraintNames.add(name);
+      if (!boneNames.has(spec.bone)) {
+        throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
+      }
+      const entry: SpineConstraint = {
+        name,
+        type: 'physics',
+        bone: spec.bone,
+      };
+      const components: string[] = [];
+      for (const comp of PHYSICS_COMPONENTS) {
+        const v = spec[comp];
+        if (v === undefined || v === 0) continue;
+        entry[comp] = r6(v);
+        components.push(comp);
+      }
+      if (!components.length) {
+        // The parser is happy with this and the constraint does nothing at all.
+        // A23 catches it too; refusing here means it never reaches the gate.
+        throw new CompileError(
+          `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
+        );
+      }
+      for (const [param, dflt] of PHYSICS_PARAMS) {
+        const v = spec[param as keyof typeof spec] as number | undefined;
+        if (v === undefined || v === dflt) continue;
+        entry[param] = r6(v);
+      }
+      constraints.push(entry);
+      physicsReport.push({
+        name,
+        bone: spec.bone,
+        components,
+        mix: spec.mix ?? 1,
+        drivesMesh: meshBones.has(spec.bone),
+      });
     }
-    for (const [param, dflt] of PHYSICS_PARAMS) {
-      const v = spec[param as keyof typeof spec] as number | undefined;
-      if (v === undefined || v === dflt) continue;
-      entry[param] = r6(v);
-    }
-    constraints.push(entry);
-    physicsReport.push({
-      name,
-      bone: spec.bone,
-      components,
-      mix: spec.mix ?? 1,
-      drivesMesh: meshBones.has(spec.bone),
-    });
-  }
+  });
 
   // -- 5. animations ---------------------------------------------------------
   const animations: SpineSkeletonJson['animations'] = {};
   const declaredDurations: Record<string, number> = {};
   const slotNames = new Set(slots.map((s) => s.name));
 
-  for (const [animName, anim] of Object.entries(motion.animations)) {
-    declaredDurations[animName] = anim.duration;
-    const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const claimed = new Set<string>();
-    let compiledDuration = 0;
-
-    for (const track of anim.tracks) {
-      const isPhysicsTrack = track.property in PHYSICS_TRACKS;
-      const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
-      const targets = resolveTargets(track, motion, animName);
-      targets.forEach((target, index) => {
-        if (isPhysicsTrack) {
-          if (!constraintNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+  withMotionSource(() => {
+    for (const [animName, anim] of Object.entries(motion.animations)) {
+      declaredDurations[animName] = anim.duration;
+      const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const claimed = new Set<string>();
+      let compiledDuration = 0;
+
+      for (const track of anim.tracks) {
+        const isPhysicsTrack = track.property in PHYSICS_TRACKS;
+        const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
+        const targets = resolveTargets(track, motion, animName);
+        targets.forEach((target, index) => {
+          if (isPhysicsTrack) {
+            if (!constraintNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+            }
+          } else if (isBoneTrack) {
+            if (!boneNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+            }
+          } else if (!slotNames.has(target)) {
+            throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
           }
-        } else if (isBoneTrack) {
-          if (!boneNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+          const claim = `${target}.${track.property}`;
+          if (claimed.has(claim)) {
+            throw new CompileError(
+              `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
+            );
           }
-        } else if (!slotNames.has(target)) {
-          throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
-        }
-        const claim = `${target}.${track.property}`;
-        if (claimed.has(claim)) {
-          throw new CompileError(
-            `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
-          );
-        }
-        claimed.add(claim);
-
-        const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
-        const keys = isPhysicsTrack
-          ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
-          : isBoneTrack
-            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
-            : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
-        for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
-        if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
-        else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
-        else (slotTimelines[target] ??= {})[track.property] = keys;
-      });
-    }
+          claimed.add(claim);
+
+          const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
+          const keys = isPhysicsTrack
+            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
+            : isBoneTrack
+              ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
+              : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
+          for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
+          if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
+          else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
+          else (slotTimelines[target] ??= {})[track.property] = keys;
+        });
+      }
 
-    const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
-    if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
-    // An event timeline counts towards the animation's length the same as any
-    // other: `readAnimation` takes the duration from the longest timeline it
-    // built, and `EventTimeline.getDuration()` is its last frame like the rest.
-    if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    // Rule 4: the declared duration is verified, because skeleton JSON does not
-    // carry one — the loader takes the max key time.
-    //
-    // This arm is about the DECLARED DURATION being wrong, so it compares one
-    // number per animation and tolerates a frame of it. The other arm —
-    // `checkKeyTime`, above, per key — is about a key landing past the end, and
-    // a frame is 16,667 times too coarse to see one. Both are needed: this one
-    // catches an animation that stops a second early, and only that one catches
-    // a key on a track whose neighbour already sits on the declared duration.
-    if (Math.abs(compiledDuration - anim.duration) > FRAME) {
-      throw new CompileError(
-        `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
-      );
+      const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
+      if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
+      // An event timeline counts towards the animation's length the same as any
+      // other: `readAnimation` takes the duration from the longest timeline it
+      // built, and `EventTimeline.getDuration()` is its last frame like the rest.
+      if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      // Rule 4: the declared duration is verified, because skeleton JSON does not
+      // carry one — the loader takes the max key time.
+      //
+      // This arm is about the DECLARED DURATION being wrong, so it compares one
+      // number per animation and tolerates a frame of it. The other arm —
+      // `checkKeyTime`, above, per key — is about a key landing past the end, and
+      // a frame is 16,667 times too coarse to see one. Both are needed: this one
+      // catches an animation that stops a second early, and only that one catches
+      // a key on a track whose neighbour already sits on the declared duration.
+      if (Math.abs(compiledDuration - anim.duration) > FRAME) {
+        throw new CompileError(
+          `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
+        );
+      }
+      animations[animName] = {};
+      if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
+      if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
+      if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
+      if (drawOrder) animations[animName].drawOrder = drawOrder;
+      if (eventKeys) animations[animName].events = eventKeys;
     }
-    animations[animName] = {};
-    if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
-    if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
-    if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
-    if (drawOrder) animations[animName].drawOrder = drawOrder;
-    if (eventKeys) animations[animName].events = eventKeys;
-  }
+  });
 
   // -- 6. assemble -----------------------------------------------------------
   const header: SpineSkeletonJson['skeleton'] = {