spine-rigc 2.19.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "./rig": "./src/rig.ts",
     "./mesh": "./src/mesh.ts",
     "./errors": "./src/errors.ts",
+    "./meshcompare": "./src/meshcompare.ts",
     "./cli": "./cli.ts",
     "./package.json": "./package.json",
     "./*.ts": "./*.ts",

package/src/areaband.ts

@@ -4,7 +4,10 @@
  * degeneracy by (`src/meshquality.ts`).
  *
  * Moved here unchanged from `src/deformsurvey.ts`, which imports these back
- * and re-exports every name it exported before, so no caller changed an import.
+ * and re-exports every name it exported before, so no caller changed an import
+ * — and `stretchSingularValues` after them (issue #1230), for the motion
+ * comparison (`src/meshcompare.ts`), which reads a triangle's stretch the way
+ * the deform survey does and must not reach the compiler either.
  * They moved because a module the `spine-rigc/mesh` entry reaches has to read
  * the same band, and `src/deformsurvey.ts` reaches the compiler and the core
  * (`src/deformstructure.ts`, `src/core/`) — a geometry entry that loaded the
@@ -94,3 +97,63 @@ export function areaBand(plainAreas: readonly number[], ...worlds: ReadonlyArray
   for (const world of worlds) band = Math.max(band, float32AreaNoise(world));
   return band;
 }
+
+/**
+ * The two singular values of the linear map that takes one triangle onto the
+ * other — the largest and smallest factor by which it scales a direction.
+ *
+ * ## Why this is the texture's stretch
+ *
+ * A mesh's uvs are fixed to the attachment and a deform never touches them, so
+ * the texture is mapped affinely onto the *plain* triangle and the same texels
+ * end up on the *deformed* one. The change in that mapping is exactly `J = D·P⁻¹`
+ * with `P` and `D` the two triangles' edge pairs, and its singular values are the
+ * worst stretch and the worst squash the drawing takes there. A σ of 1.4 means
+ * every texel in that direction is drawn 1.4 px wide; 0.6 means the art is
+ * crushed to 60%.
+ *
+ * `σ₁·σ₂ = |det J|` is the signed-area ratio's magnitude, which is why the two
+ * quantities in the report cannot disagree — and `DR01` is the control that says
+ * so on a case whose ratio the closed form predicts.
+ *
+ * Returns `null` for a plain triangle with no area: `P` is singular, there is no
+ * map, and inventing one would be the report's own version of the false green
+ * this file exists to avoid. Those triangles are counted as `degenerate`.
+ */
+export function stretchSingularValues(
+  plain: ArrayLike<number>,
+  deformed: ArrayLike<number>,
+  triangles: ArrayLike<number>,
+  t: number,
+): { max: number; min: number } | null {
+  const i0 = triangles[t * 3] * 2;
+  const i1 = triangles[t * 3 + 1] * 2;
+  const i2 = triangles[t * 3 + 2] * 2;
+  const ux = plain[i1] - plain[i0];
+  const uy = plain[i1 + 1] - plain[i0 + 1];
+  const vx = plain[i2] - plain[i0];
+  const vy = plain[i2 + 1] - plain[i0 + 1];
+  const det = ux * vy - vx * uy;
+  if (det === 0) return null;
+  const px = deformed[i1] - deformed[i0];
+  const py = deformed[i1 + 1] - deformed[i0 + 1];
+  const qx = deformed[i2] - deformed[i0];
+  const qy = deformed[i2 + 1] - deformed[i0 + 1];
+  // J = D·P⁻¹, written out — P⁻¹ = (1/det)·[[vy, −vx], [−uy, ux]].
+  const a = (px * vy - qx * uy) / det;
+  const b = (-px * vx + qx * ux) / det;
+  const c = (py * vy - qy * uy) / det;
+  const d = (-py * vx + qy * ux) / det;
+  // σ₁² + σ₂² = ‖J‖²_F and σ₁·σ₂ = |det J|, which is two equations for the two
+  // values and needs no eigen decomposition. The discriminant is non-negative in
+  // exact arithmetic (it is `(σ₁² − σ₂²)²`); the clamp is for rounding on a map
+  // that is very nearly a rotation.
+  const frobenius = a * a + b * b + c * c + d * d;
+  const determinant = a * d - b * c;
+  const discriminant = Math.max(0, frobenius * frobenius - 4 * determinant * determinant);
+  const root = Math.sqrt(discriminant);
+  return {
+    max: Math.sqrt(Math.max(0, (frobenius + root) / 2)),
+    min: Math.sqrt(Math.max(0, (frobenius - root) / 2)),
+  };
+}

package/src/cli/shared.ts

@@ -39,6 +39,7 @@ import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
 import { MODEL_DOCUMENT_FILE, MODEL_DOCUMENT_SPEC, modelDocument, spineFileSha256 } from '../model.ts';
+import { PACKAGE_ROOT, readPackageMeta, readVersion } from '../package_meta.ts';
 import { DEFAULT_MAX_RESIDUAL, DEFAULT_SCALE_MAX, DEFAULT_SCALE_MIN } from '../pose.ts';
 import {
   CandidateAtlasError,
@@ -98,37 +99,9 @@ export class ExplainError extends Error {}
 // and for naming a remedy `bench` can only give from a repo checkout.
 // ---------------------------------------------------------------------------
 
-interface PackageMeta {
-  version?: string;
-  repository?: string | { url?: string };
-}
-
-let packageMeta: PackageMeta | null | undefined;
-
-/**
- * The directory `cli.ts` sits in: `package.json`, `skills/` and, in a
- * checkout, `examples/` and `scripts/` are beside it, in the repository and
- * once installed. Two levels above this file (`src/cli/`), which is where the
- * commands that read those live since issue #1052 — every path they built off
- * `cli.ts`'s own directory is built off this one, and comes out the same.
- */
-export const PACKAGE_ROOT = join(import.meta.dir, '..', '..');
-
-/** `package.json` sits next to `cli.ts` both in the repo and once installed (`PACKAGE_ROOT`). */
-export function readPackageMeta(): PackageMeta | null {
-  if (packageMeta === undefined) {
-    try {
-      packageMeta = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as PackageMeta;
-    } catch {
-      packageMeta = null;
-    }
-  }
-  return packageMeta;
-}
-
-export function readVersion(): string {
-  return readPackageMeta()?.version ?? 'unknown';
-}
+// The reader moved to `../package_meta.ts` (issue #1230), so a library module can read
+// the version without loading the CLI; every name it had here is re-exported unchanged.
+export { PACKAGE_ROOT, readPackageMeta, readVersion };
 
 // ---------------------------------------------------------------------------
 // argument parsing

package/src/deformsurvey.ts

@@ -25,72 +25,14 @@
 import { CoreInputError, underSkin, type CompiledDocument } from './core/index.ts';
 import { float32Rows, meshWorld, poseDial as corePoseDial, poseJump, recordIdentity, sliderRecordOf, slotDraw, type CoreSurveyPose } from './core/hooks.ts';
 import { modelStructure, type SurveyAnimation, type SurveyDeformTimeline, type SurveyMesh, type SurveySkin, type SurveySlider, type SurveyStructure } from './deformstructure.ts';
-import { areaBand, DEFORM_AREA_EPSILON, float32AreaNoise, triangleAreas } from './areaband.ts';
+import { areaBand, DEFORM_AREA_EPSILON, float32AreaNoise, stretchSingularValues, triangleAreas } from './areaband.ts';
 
 // The area band lives in `src/areaband.ts` (moved unchanged, issue #1224) so the
-// geometry entry can read it without reaching the compiler; every name this
-// module exported before is exported from here still.
-export { DEFORM_AREA_EPSILON, float32AreaNoise, triangleAreas };
-
-/**
- * The two singular values of the linear map that takes one triangle onto the
- * other — the largest and smallest factor by which it scales a direction.
- *
- * ## Why this is the texture's stretch
- *
- * A mesh's uvs are fixed to the attachment and a deform never touches them, so
- * the texture is mapped affinely onto the *plain* triangle and the same texels
- * end up on the *deformed* one. The change in that mapping is exactly `J = D·P⁻¹`
- * with `P` and `D` the two triangles' edge pairs, and its singular values are the
- * worst stretch and the worst squash the drawing takes there. A σ of 1.4 means
- * every texel in that direction is drawn 1.4 px wide; 0.6 means the art is
- * crushed to 60%.
- *
- * `σ₁·σ₂ = |det J|` is the signed-area ratio's magnitude, which is why the two
- * quantities in the report cannot disagree — and `DR01` is the control that says
- * so on a case whose ratio the closed form predicts.
- *
- * Returns `null` for a plain triangle with no area: `P` is singular, there is no
- * map, and inventing one would be the report's own version of the false green
- * this file exists to avoid. Those triangles are counted as `degenerate`.
- */
-export function stretchSingularValues(
-  plain: ArrayLike<number>,
-  deformed: ArrayLike<number>,
-  triangles: ArrayLike<number>,
-  t: number,
-): { max: number; min: number } | null {
-  const i0 = triangles[t * 3] * 2;
-  const i1 = triangles[t * 3 + 1] * 2;
-  const i2 = triangles[t * 3 + 2] * 2;
-  const ux = plain[i1] - plain[i0];
-  const uy = plain[i1 + 1] - plain[i0 + 1];
-  const vx = plain[i2] - plain[i0];
-  const vy = plain[i2 + 1] - plain[i0 + 1];
-  const det = ux * vy - vx * uy;
-  if (det === 0) return null;
-  const px = deformed[i1] - deformed[i0];
-  const py = deformed[i1 + 1] - deformed[i0 + 1];
-  const qx = deformed[i2] - deformed[i0];
-  const qy = deformed[i2 + 1] - deformed[i0 + 1];
-  // J = D·P⁻¹, written out — P⁻¹ = (1/det)·[[vy, −vx], [−uy, ux]].
-  const a = (px * vy - qx * uy) / det;
-  const b = (-px * vx + qx * ux) / det;
-  const c = (py * vy - qy * uy) / det;
-  const d = (-py * vx + qy * ux) / det;
-  // σ₁² + σ₂² = ‖J‖²_F and σ₁·σ₂ = |det J|, which is two equations for the two
-  // values and needs no eigen decomposition. The discriminant is non-negative in
-  // exact arithmetic (it is `(σ₁² − σ₂²)²`); the clamp is for rounding on a map
-  // that is very nearly a rotation.
-  const frobenius = a * a + b * b + c * c + d * d;
-  const determinant = a * d - b * c;
-  const discriminant = Math.max(0, frobenius * frobenius - 4 * determinant * determinant);
-  const root = Math.sqrt(discriminant);
-  return {
-    max: Math.sqrt(Math.max(0, (frobenius + root) / 2)),
-    min: Math.sqrt(Math.max(0, (frobenius - root) / 2)),
-  };
-}
+// geometry entry can read it without reaching the compiler, and
+// `stretchSingularValues` joined it (moved unchanged, issue #1230) so the motion
+// comparison can too; every name this module exported before is exported from
+// here still.
+export { DEFORM_AREA_EPSILON, float32AreaNoise, stretchSingularValues, triangleAreas };
 
 /** A quantity's worst triangle on one key, and which triangle it was. */
 export interface DeformExtreme {

package/src/mesh.ts

@@ -118,7 +118,11 @@ export interface MeshGeometry {
   points: Array<[number, number]>;
   /** Normalised region UVs, v measured from the top edge. */
   uvs: number[];
-  /** Triangle indices, counter-clockwise in Spine world (y up). */
+  /**
+   * Triangle indices, counter-clockwise in Spine world (y up) — every builder
+   * here, measured on spine-core's posed world by `CT15` in `selftest.ts`
+   * (issue #1236: `contour` and `ring` wound the other way until then).
+   */
   triangles: number[];
   /** Per-vertex weights, parallel to `points`. */
   weights: MeshVertexWeight[][];
@@ -221,6 +225,33 @@ export function signedArea(poly: Array<[number, number]>): number {
   return a / 2;
 }
 
+/**
+ * Turn a triangle list built ALONG `poly` — every triple carrying the
+ * polygon's own winding, as an ear-clip of it or a ring strip around it does —
+ * counter-clockwise in Spine world, the winding `MeshGeometry.triangles`
+ * promises. `poly` is in part-local pixels, y down.
+ *
+ * Counter-clockwise in Spine world (y up) is a NEGATIVE shoelace area in y-down
+ * pixels: the flip changes the sign of the area and not the direction the loop
+ * turns as drawn. So a polygon whose y-down area is positive — clockwise on
+ * screen, and therefore clockwise in Spine world — has each triangle's last two
+ * corners swapped, the way `buildSegmentsLattice` does per triangle; one with a
+ * negative area is already right and is returned as it came. The triangle SET
+ * is unchanged either way: only the order of two indices inside a triple moves.
+ *
+ * The decision is the polygon's, not each triangle's, so a near-collinear ear
+ * whose own sign is rounding noise is turned with its neighbours rather than
+ * read on its own (issue #1236 — `contour` and `ring` emitted every triangle
+ * clockwise in Spine world before this existed, under comments that derived the
+ * opposite from the y flip).
+ */
+export function windCounterClockwiseInSpineWorld(poly: Array<[number, number]>, triangles: readonly number[]): number[] {
+  const out = triangles.slice();
+  if (signedArea(poly) <= 0) return out;
+  for (let t = 0; t + 2 < out.length; t += 3) [out[t + 1], out[t + 2]] = [out[t + 2], out[t + 1]];
+  return out;
+}
+
 /**
  * Is every hull edge visible from `center`? If not, scaling the polygon toward
  * the centre can fold the inner ring through the rim and the triangles cross —
@@ -379,23 +410,25 @@ export function buildRingMesh(input: MeshSpecInput): MeshGeometry {
   const uvs: number[] = [];
   for (const [x, y] of points) uvs.push(r6(x / w), r6(y / h));
 
-  // Counter-clockwise in Spine world: the manifest polygon runs clockwise on
-  // screen (y down), and the y flip into world space reverses that.
-  const triangles: number[] = [];
+  // Each triple below runs along the hull's own list order, so it carries the
+  // hull's winding; `windCounterClockwiseInSpineWorld` then turns the list to
+  // the winding every generator here emits (issue #1236).
+  const along: number[] = [];
   const hub = 3 * n;
   const strip = (outerBase: number, innerBase: number) => {
     for (let i = 0; i < n; i++) {
       const j = (i + 1) % n;
-      triangles.push(outerBase + i, outerBase + j, innerBase + j);
-      triangles.push(outerBase + i, innerBase + j, innerBase + i);
+      along.push(outerBase + i, outerBase + j, innerBase + j);
+      along.push(outerBase + i, innerBase + j, innerBase + i);
     }
   };
   strip(0, n); // window edge -> seam
   strip(n, 2 * n); // seam -> aperture ring
   for (let i = 0; i < n; i++) {
     const j = (i + 1) % n;
-    triangles.push(2 * n + i, 2 * n + j, hub);
+    along.push(2 * n + i, 2 * n + j, hub);
   }
+  const triangles = windCounterClockwiseInSpineWorld(hull, along);
 
   return { kind: 'ring', points, uvs, triangles, weights, hullVertices: n };
 }
@@ -940,9 +973,16 @@ function pointInTriangle(
  *
  * Repeatedly find a vertex whose two edges make a convex turn in the polygon's
  * own winding and whose triangle holds no other vertex, emit it as a triangle,
- * and remove it. The emitted triples carry the polygon's own winding, so a
- * clockwise-on-screen outline yields triangles that are counter-clockwise in
- * Spine world after the y flip — the convention the rest of this file keeps.
+ * and remove it. The emitted triples carry the polygon's own winding — the
+ * order its list runs in — and nothing else decides it: clipping the same
+ * outline mirrored picks the same ears in the same order and writes the same
+ * triples. ⚠️ A y flip does NOT turn that winding over. Flipping y changes the
+ * sign of a signed area, but the y-up frame is drawn with y up, so the loop
+ * turns the same way on screen as it does in Spine world: an outline that is
+ * clockwise on screen (positive `signedArea` in y-down pixels) yields
+ * triangles that are clockwise in Spine world. A caller that emits them turns
+ * them with `windCounterClockwiseInSpineWorld` (issue #1236: this paragraph
+ * said the opposite, and `contour` emitted clockwise for that reason).
  *
  * ## What it refuses, and why by name
  *
@@ -1592,7 +1632,7 @@ export function buildContourMesh(input: ContourSpecInput): MeshGeometry {
         'has a neck too thin to mesh',
     );
   }
-  const triangles = earClip(points);
+  const triangles = windCounterClockwiseInSpineWorld(points, earClip(points));
 
   // The bound on the grid the fit is measured on: its last term is one cell of
   // that grid, which is why it is derived from the texel figures rather than
@@ -1905,7 +1945,7 @@ export function meshEdges(vertexCount: number, triangles: readonly number[], hul
 //      bottom-left), each cell two triangles with the diagonal alternating by
 //      `(i + j) % 2`, so the lattice has no preferred shear. Emitted
 //      counter-clockwise in Spine world, the winding every generator here
-//      writes (GR02 holds the grid to it).
+//      writes (GR02 holds the grid to it, CT15 every generator).
 //   4. **Outline first.** The boundary is walked from the edges used by exactly
 //      one triangle, in first-seen order, and every interior vertex follows in
 //      index order — the arrangement `checkHullOrder` requires.