spine-rigc 0.8.1 → 0.9.0

package/README.md

@@ -394,9 +394,9 @@ work on any frames you have, and `bench` is a repository workflow that needs a c
 and `bun run fetch-examples`. The reasoning behind all three is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
-`build` and `validate` both default to `--profile spine` — the 22 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 25 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 36: the other 14 are one renderer's policy and one canvas budget's, and they
+adds all 39: the other 14 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, so reach for that profile when
 you are shipping into *that* project rather than to be thorough. A report always names
 the profile it ran and lists what that profile left out.
@@ -424,13 +424,22 @@ rigc is measured against **Spine's own official example projects** — the
 `1-weight-and-mass` … `8-follow-through` series as a difficulty ladder, with spineboy
 as the graduation exam.
 
-🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
-spineboy graduation exam are cleared under gate v2.1 and hold under **v2.2**, every clause PASS or SKIP:
+🎓 **The ladder was completed 2026-08-28.** All eight numbered rungs and the
+spineboy graduation exam cleared under gate v2.1 and held under **v2.2**, every clause PASS or SKIP:
 worst attributable slot drift **5.55 px** against a 6.0 px bar, and **0 of 124**
 frame-change disagreements. Recompiling the same spec in a different session
 reproduced every field of the measurement record **to the digit**. The rungs stay
 in place as regression gates.
 
+⚠️ **Current state, 2026-09-02: seven of the eight hold, and rung 7 is open.**
+`check`'s extent tolerance ([PR #254](https://github.com/firejune/rigc/pull/254))
+changed which box a set is measured in, and rung 7's stored candidate fails **G2**
+under it — one of its three slots draws in every set and is attributable in none,
+and no read-down kind survives the framing change. **Rungs 1–6 and 8 and the
+graduation exam are unaffected**: each reproduces its gated figures to the digit,
+and the 5.55 px and 0-of-124 figures above are among them. Verdict and reasoning
+in [docs/LADDER.md](docs/LADDER.md)'s *PR #254 instrument re-inspection*.
+
 ⚠️ **What that certifies, stated exactly.** That **the tool, the guide and the
 protocol reach the bar across a bounded series of honest attempts, each residual
 diagnosed and fixed** — spineboy took five, and the last inherited its
@@ -439,7 +448,7 @@ that an agent authors a spineboy-scale rig from the brief alone in one run: the
 ladder has not demonstrated that, and each row records which of the two it is.
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 36 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 39 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

package/cli.ts

@@ -332,6 +332,26 @@ function runGate(result: CompileResult, opts: CompileOptions, profile: ValidateP
   return report.failures.length;
 }
 
+/**
+ * One line per mesh kind on this cut, printed above the table.
+ *
+ * A legend rather than a heading: the heading used to describe the ring tier
+ * unconditionally, so a build whose only mesh was a ribbon or a contour got a
+ * sentence about a rim ring and a seam it does not have.
+ */
+const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
+  ring: 'ring      rim ring pinned on the window edge, seam ring pinned on the mask contour, aperture moves',
+  ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
+  contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
+  authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
+};
+
+/** What a contour mesh measured about its own fit, or nothing for the others. */
+function meshFit(m: CompileResult['meshes'][number]): string {
+  if (m.coverage === undefined) return '';
+  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -358,8 +378,8 @@ function cmdBuild(flags: Record<string, string>): void {
   }
   for (const m of result.meshes) {
     console.log(
-      `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(6)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `(budget 80)  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]`,
+      `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
+        `(budget 80)  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
     );
   }
   for (const ph of result.physics) {
@@ -508,8 +528,10 @@ 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' | 'framing'> {
-  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing'> = {};
+function readCheckFlags(
+  flags: Record<string, string>,
+): Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom'> {
+  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom'> = {};
   if (flags.framing !== undefined) {
     if (flags.framing !== 'per-shot' && flags.framing !== 'shared') {
       throw new UsageError('--framing takes per-shot (the default) or shared');
@@ -530,6 +552,16 @@ function readCheckFlags(flags: Record<string, string>): Pick<CheckOptions, 'fps'
     out.viewport = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   if (flags.as !== undefined) out.as = flags.as;
+  if (flags['texture-from'] !== undefined) {
+    const path = resolve(flags['texture-from']);
+    if (!existsSync(path)) {
+      throw new UsageError(
+        `--texture-from ${path} is not a file. It takes the ATLAS the reference frames were rendered through — the ` +
+          "example's own .atlas — so check can measure how much of the MAE is texture resampling.",
+      );
+    }
+    out.textureFrom = { atlasText: readFileSync(path, 'utf8'), atlasDir: dirname(path), label: flags['texture-from'] };
+  }
   return out;
 }
 
@@ -1368,6 +1400,24 @@ function cmdExplain(flags: Record<string, string>): void {
         }
       }
     }
+    // The other two constraint groups. These DO carry a timeline name under the
+    // constraint (`path.<name>.position`), which is the physics shape rather
+    // than the ik/transform one, so the name printed is both.
+    for (const group of ['path', 'slider'] as const) {
+      for (const [name, timelines] of Object.entries(anim[group] ?? {})) {
+        for (const [timelineName, keys] of Object.entries(timelines)) {
+          console.log(`    ${group}.${name}.${timelineName}  ${keys.length} key(s)`);
+          for (const key of keys) {
+            const fields = Object.entries(key)
+              .filter(([k]) => k !== 'time' && k !== 'curve')
+              .map(([k, v]) => `${k}=${String(v)}`)
+              .join(' ');
+            const curve = Array.isArray(key.curve) ? `bezier[${key.curve.length}]` : key.curve === 'stepped' ? 'stepped' : 'linear';
+            console.log(`      t=${String(key.time).padEnd(7)} ${(fields || '(all defaults)').padEnd(46)} ${curve}`);
+          }
+        }
+      }
+    }
     // Deform timelines are keyed on a skin/slot/attachment triple, and the run
     // is printed as its span rather than its numbers: `offset` plus a length is
     // what tells a reader whether the key lands where they meant, and a hundred
@@ -1413,11 +1463,66 @@ function cmdExplain(flags: Record<string, string>): void {
     }
   }
 
+  // Path constraints, with the curve each one follows MEASURED — its length and
+  // its curve count are the two numbers an author cannot get from the spec, and
+  // `position` means nothing without the first of them under `positionMode:
+  // "percent"`. Read off the emitted attachment rather than recomputed here.
+  const constraintsOf = (type: string) => (result.skeleton.constraints ?? []).filter((c) => c.type === type);
+  const pathConstraints = constraintsOf('path');
+  if (pathConstraints.length) {
+    console.log('\npath constraints  (position is a fraction of the measured length under positionMode "percent")');
+    for (const c of pathConstraints) {
+      const slot = String(c.slot);
+      const attachments = result.skeleton.skins.flatMap((skin) => Object.values(skin.attachments[slot] ?? {}));
+      const curve = attachments.find((att) => (att as { type?: string }).type === 'path') as
+        | { lengths?: number[]; closed?: boolean; constantSpeed?: boolean }
+        | undefined;
+      const lengths = curve?.lengths ?? [];
+      console.log(
+        `  ${c.name.padEnd(12)} slot=${slot.padEnd(12)} bones=[${(c.bones as string[]).join(', ')}] ` +
+          `position=${c.position ?? 0} ${String(c.positionMode ?? 'percent')}/${String(c.spacingMode ?? 'length')}/${String(c.rotateMode ?? 'tangent')}`,
+      );
+      console.log(
+        `  ${''.padEnd(12)} curve: ${lengths.length} curve(s), ${lengths[lengths.length - 1] ?? 0} long, ` +
+          `${curve?.closed ? 'closed' : 'open'}, constantSpeed=${curve?.constantSpeed ?? true}`,
+      );
+    }
+  }
+
+  const sliders = constraintsOf('slider');
+  if (sliders.length) {
+    console.log('\nsliders  (each applies one animation at a time it chooses)');
+    for (const c of sliders) {
+      const driver = c.bone === undefined ? `time=${c.time ?? 0} (keyed by slider.${c.name}.time)` : `bone=${String(c.bone)}.${String(c.property)}`;
+      console.log(
+        `  ${c.name.padEnd(12)} applies=${String(c.animation).padEnd(14)} ${driver}  ` +
+          `mix=${c.mix ?? 1} loop=${c.loop ?? false} additive=${c.additive ?? false}`,
+      );
+    }
+  }
+
+  // Which bones and constraints a skin switches on. Printed because the pairing
+  // with `skin: true` is invisible in the emitted file: a member list and a
+  // skinRequired flag are two keys in two places, and only together do they mean
+  // "this bone belongs to this skin".
+  const skinMembers = result.skeleton.skins.filter((skin) => skin.bones?.length || skin.ik?.length || skin.transform?.length || skin.path?.length || skin.physics?.length || skin.slider?.length);
+  if (skinMembers.length) {
+    console.log('\nskin members  (skinRequired bones and constraints, active only under their own skin)');
+    for (const skin of skinMembers) {
+      const lists = (['bones', 'ik', 'transform', 'path', 'physics', 'slider'] as const)
+        .filter((key) => skin[key]?.length)
+        .map((key) => `${key}=[${skin[key]!.join(', ')}]`)
+        .join(' ');
+      console.log(`  ${skin.name.padEnd(12)} ${lists}`);
+    }
+  }
+
   if (result.meshes.length) {
-    console.log('\nmeshes  (ring tier: rim ring pinned on the window edge, seam ring pinned on the mask contour)');
+    console.log('\nmeshes');
+    for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
       console.log(
-        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(6)} ${m.vertices} vertices / ${m.triangles} triangles  bones=[${m.bones.join(', ')}]`,
+        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
       );
     }
   }
@@ -1456,6 +1561,11 @@ const FLAG_MEANINGS: Record<string, string> = {
     'which rulebook to check against (default: spine) — spine = valid Spine 4.3 that any runtime plays ' +
     "correctly; spine-html = also this project's renderer/archetype policy",
   atlas: "the candidate's atlas, when it is not beside the skeleton",
+  'texture-from':
+    "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
+    'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
+    'through. ⚠️ NOT --atlas: that one names the candidate\'s own atlas and loading a foreign one there re-seats ' +
+    'every region attachment on its packing, so a rotated or trimmed pack moves the geometry too',
   candidate: 'a compiled skeleton: a directory holding skeleton.json + skeleton.atlas, or a skeleton.json path',
   frames: 'a rendered reference frame set (a skeleton root, or one animation directory)',
   fps: 'frame rate, only for a frame set with no frames.json sidecar',
@@ -1490,6 +1600,7 @@ const FLAG_VALUES: Record<string, string> = {
   cuts: '<path>',
   profile: 'spine|spine-html',
   atlas: '<path>',
+  'texture-from': '<path>',
   candidate: '<dir|skeleton.json>',
   frames: '<dir>',
   fps: '<n>',
@@ -1560,7 +1671,7 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'check',
     usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'fps', 'viewport', 'framing', 'as', 'all-frames', 'json'],
+    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'all-frames', 'json'],
   },
   {
     name: 'bench',