spine-rigc 2.17.1 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.17.1",
+  "version": "2.19.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": {

package/src/areaband.ts

@@ -0,0 +1,96 @@
+/**
+ * The area band a triangle's sign is read against — the one A39 reads a
+ * winding by, and the one the mesh-quality measurement reads orientation and
+ * 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.
+ * 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
+ * compiler to read three numbers would also close an import cycle through
+ * `src/compile.ts`, which imports `src/mesh.ts`.
+ *
+ * Imports nothing: no clock, no runtime, no other module.
+ */
+
+/**
+ * How near zero a triangle's area has to be, as a fraction of the largest
+ * triangle in the same mesh at the same pose, before a sign is not read off it.
+ *
+ * A RELATIVE band, because an absolute one has no scale that means anything on
+ * its own — these are pixel² figures on whatever plate the rig was drawn at, and
+ * `gallery/flex`'s leaf tops out at 792.6 px² where `spineboy-pro`'s hoverboard
+ * reaches 3338.4 px². On those two it comes to 7.9e-4 and 3.3e-3 px².
+ *
+ * ⚠️ It is **not** what holds the float32 noise off; `float32AreaNoise` is, and
+ * the two are combined rather than ranked because on a big mesh the noise bound
+ * is the larger of them. This one is the shape band: it keeps a setup triangle
+ * that has no area from being read as a reversal of anything, and a triangle the
+ * key collapses onto zero from being read as turned over.
+ */
+export const DEFORM_AREA_EPSILON = 1e-6;
+
+/** Half an ulp of a float32 mantissa — the relative error of one stored coordinate. */
+const FLOAT32_HALF_ULP = 2 ** -24;
+
+/**
+ * An upper bound on how much of a triangle's signed area is float32 noise.
+ *
+ * The world vertices arrive in a `Float32Array`, so each coordinate carries up
+ * to `|c|·2⁻²⁴` of error. An area is `½·(Δx₁·Δy₂ − Δx₂·Δy₁)`, and propagating
+ * that error through one product gives `Δ·|c|·2⁻²⁴` twice over; four such terms
+ * across the two products, halved, bounds the area error by `2·C²·2⁻²⁴` with `C`
+ * the largest coordinate magnitude in the mesh (which also bounds every `Δ`).
+ * Doubled once more for the subtraction, so the constant is 4.
+ *
+ * On a mesh whose vertices reach 500 units that is 6e-2 px², i.e. **larger** than
+ * the relative band above — which is the whole reason this exists. It is a bound
+ * rather than a measurement, and deliberately loose: what has to stay clear of it
+ * is a genuine reversal, and the smallest one anywhere in the corpus is
+ * `spineboy-pro`'s hoverboard triangle at 8.478 px², more than two orders of
+ * magnitude above. Nothing measured lands between the two, so nothing between
+ * them is being tuned.
+ */
+export function float32AreaNoise(world: ArrayLike<number>): number {
+  let coordinate = 0;
+  for (let i = 0; i < world.length; i++) coordinate = Math.max(coordinate, Math.abs(world[i]));
+  return 4 * coordinate * coordinate * FLOAT32_HALF_ULP;
+}
+
+/**
+ * Twice-signed area, halved, of every triangle of `triangles` over the
+ * interleaved `x, y` world vertices in `world`.
+ *
+ * The SIGN is the whole point and the magnitude is the tolerance's yardstick, so
+ * this returns the signed figure rather than an absolute one. Positive and
+ * negative are not "correct" and "wrong" — a mesh may be wound either way, and
+ * what A39 reads is whether one triangle's sign CHANGED.
+ */
+export function triangleAreas(world: ArrayLike<number>, triangles: ArrayLike<number>): number[] {
+  const out: number[] = [];
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    const i0 = triangles[t] * 2;
+    const i1 = triangles[t + 1] * 2;
+    const i2 = triangles[t + 2] * 2;
+    const x0 = world[i0];
+    const y0 = world[i0 + 1];
+    out.push(0.5 * ((world[i1] - x0) * (world[i2 + 1] - y0) - (world[i2] - x0) * (world[i1 + 1] - y0)));
+  }
+  return out;
+}
+
+/**
+ * The dead band a set of areas is read against.
+ *
+ * Both bands, and the wider one wins. The relative one is about the SHAPE (a
+ * triangle with no area has no winding); the noise one is about the arithmetic (a
+ * sign read off float32 rounding is not a measurement). Each is the larger on a
+ * different mesh.
+ */
+export function areaBand(plainAreas: readonly number[], ...worlds: ReadonlyArray<ArrayLike<number>>): number {
+  const largest = plainAreas.reduce((m, a) => Math.max(m, Math.abs(a)), 0);
+  let band = largest * DEFORM_AREA_EPSILON;
+  for (const world of worlds) band = Math.max(band, float32AreaNoise(world));
+  return band;
+}

package/src/deformsurvey.ts

@@ -25,72 +25,12 @@
 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';
 
-/**
- * How near zero a triangle's area has to be, as a fraction of the largest
- * triangle in the same mesh at the same pose, before a sign is not read off it.
- *
- * A RELATIVE band, because an absolute one has no scale that means anything on
- * its own — these are pixel² figures on whatever plate the rig was drawn at, and
- * `gallery/flex`'s leaf tops out at 792.6 px² where `spineboy-pro`'s hoverboard
- * reaches 3338.4 px². On those two it comes to 7.9e-4 and 3.3e-3 px².
- *
- * ⚠️ It is **not** what holds the float32 noise off; `float32AreaNoise` is, and
- * the two are combined rather than ranked because on a big mesh the noise bound
- * is the larger of them. This one is the shape band: it keeps a setup triangle
- * that has no area from being read as a reversal of anything, and a triangle the
- * key collapses onto zero from being read as turned over.
- */
-export const DEFORM_AREA_EPSILON = 1e-6;
-
-/** Half an ulp of a float32 mantissa — the relative error of one stored coordinate. */
-const FLOAT32_HALF_ULP = 2 ** -24;
-
-/**
- * An upper bound on how much of a triangle's signed area is float32 noise.
- *
- * The world vertices arrive in a `Float32Array`, so each coordinate carries up
- * to `|c|·2⁻²⁴` of error. An area is `½·(Δx₁·Δy₂ − Δx₂·Δy₁)`, and propagating
- * that error through one product gives `Δ·|c|·2⁻²⁴` twice over; four such terms
- * across the two products, halved, bounds the area error by `2·C²·2⁻²⁴` with `C`
- * the largest coordinate magnitude in the mesh (which also bounds every `Δ`).
- * Doubled once more for the subtraction, so the constant is 4.
- *
- * On a mesh whose vertices reach 500 units that is 6e-2 px², i.e. **larger** than
- * the relative band above — which is the whole reason this exists. It is a bound
- * rather than a measurement, and deliberately loose: what has to stay clear of it
- * is a genuine reversal, and the smallest one anywhere in the corpus is
- * `spineboy-pro`'s hoverboard triangle at 8.478 px², more than two orders of
- * magnitude above. Nothing measured lands between the two, so nothing between
- * them is being tuned.
- */
-export function float32AreaNoise(world: ArrayLike<number>): number {
-  let coordinate = 0;
-  for (let i = 0; i < world.length; i++) coordinate = Math.max(coordinate, Math.abs(world[i]));
-  return 4 * coordinate * coordinate * FLOAT32_HALF_ULP;
-}
-
-/**
- * Twice-signed area, halved, of every triangle of `triangles` over the
- * interleaved `x, y` world vertices in `world`.
- *
- * The SIGN is the whole point and the magnitude is the tolerance's yardstick, so
- * this returns the signed figure rather than an absolute one. Positive and
- * negative are not "correct" and "wrong" — a mesh may be wound either way, and
- * what A39 reads is whether one triangle's sign CHANGED.
- */
-export function triangleAreas(world: ArrayLike<number>, triangles: ArrayLike<number>): number[] {
-  const out: number[] = [];
-  for (let t = 0; t + 2 < triangles.length; t += 3) {
-    const i0 = triangles[t] * 2;
-    const i1 = triangles[t + 1] * 2;
-    const i2 = triangles[t + 2] * 2;
-    const x0 = world[i0];
-    const y0 = world[i0 + 1];
-    out.push(0.5 * ((world[i1] - x0) * (world[i2 + 1] - y0) - (world[i2] - x0) * (world[i1 + 1] - y0)));
-  }
-  return out;
-}
+// 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
@@ -1624,21 +1564,6 @@ function measurePosed(
   };
 }
 
-/**
- * The dead band a set of areas is read against.
- *
- * Both bands, and the wider one wins. The relative one is about the SHAPE (a
- * triangle with no area has no winding); the noise one is about the arithmetic (a
- * sign read off float32 rounding is not a measurement). Each is the larger on a
- * different mesh.
- */
-function areaBand(plainAreas: readonly number[], ...worlds: ReadonlyArray<ArrayLike<number>>): number {
-  const largest = plainAreas.reduce((m, a) => Math.max(m, Math.abs(a)), 0);
-  let band = largest * DEFORM_AREA_EPSILON;
-  for (const world of worlds) band = Math.max(band, float32AreaNoise(world));
-  return band;
-}
-
 // ---------------------------------------------------------------------------
 // Between two keys — issue #403
 // ---------------------------------------------------------------------------

package/src/mesh.ts

@@ -44,6 +44,16 @@
  */
 import type { ModelBinding, ModelVertices } from './model.ts';
 
+// The mesh-quality measurement and its report (issue #1224) live in their own
+// module and reach a dependant through this file, which is what
+// `spine-rigc/mesh` names. That module imports helpers from this one, so the
+// two form an import cycle: safe only because neither reads the other's
+// bindings while it is being evaluated — every use is inside a function.
+// The reduction (`reduceMesh`, stage B2 of #1224) sits in the same cycle, by
+// the same rule.
+export * from './meshquality.ts';
+export * from './meshreduce.ts';
+
 export interface MeshSpecInput {
   /** Polygon in part-local pixels, y down, in manifest order. */
   hull: Array<[number, number]>;
@@ -139,13 +149,34 @@ export interface RibbonSpecInput {
 
 export class MeshError extends Error {}
 
+/**
+ * A refusal of the mesh-quality operations (`src/meshquality.ts`, issue #1224),
+ * by code: a `MeshError`, so a dependant that already catches `MeshError` keeps
+ * catching it, and `code` for one that wants to know which refusal it was. The
+ * codes are listed in docs/MESH_REDUCTION.md beside the section that defines
+ * each.
+ *
+ * ⚠️ Defined here and not in `src/meshquality.ts`, because that module imports
+ * this one and this one re-exports it: a class that extends `MeshError` at the
+ * top of the importing module would read `MeshError` before this module had
+ * run, and every import of `spine-rigc/mesh` would throw.
+ */
+export class MeshReductionError extends MeshError {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = 'MeshReductionError';
+  }
+}
+
 /**
  * The generator's own grid: 6 decimals, never "-0". Its rows, weights and
  * shares are built on it, and what it produces reaches the file through the
  * compiler's `f32` at emission (issue #716), so the emitted text is still each
  * number's float32 name — this is the generator's resolution, not the file's.
  */
-function r6(n: number): number {
+export function r6(n: number): number {
   const v = Math.round(n * 1e6) / 1e6;
   return v === 0 ? 0 : v;
 }
@@ -681,7 +712,7 @@ const CRACK_DIRS: ReadonlyArray<readonly [number, number]> = [
 ];
 
 /** Perpendicular distance from `p` to the segment `a`-`b`, clamped to its ends. */
-function distanceToSegment(
+export function distanceToSegment(
   p: readonly [number, number],
   a: readonly [number, number],
   b: readonly [number, number],
@@ -843,7 +874,7 @@ export function prunePolygon(poly: Array<[number, number]>): Array<[number, numb
 }
 
 /** Do two segments share a point? Touching counts — an ear needs strict simplicity. */
-function segmentsMeet(
+export function segmentsMeet(
   a: readonly [number, number],
   b: readonly [number, number],
   c: readonly [number, number],
@@ -979,14 +1010,14 @@ export function earClip(poly: Array<[number, number]>): number[] {
 }
 
 /** Which pixels of a mask are art, as 1/0 bytes. */
-function artOf(mask: AlphaMask, threshold: number): Uint8Array {
+export function artOf(mask: AlphaMask, threshold: number): Uint8Array {
   const out = new Uint8Array(mask.width * mask.height);
   for (let i = 0; i < out.length; i++) out[i] = mask.alpha[i] >= threshold ? 1 : 0;
   return out;
 }
 
 /** 4-connected island labels, 1-based; 0 is background. */
-function labelIslands(art: Uint8Array, w: number, h: number): { label: Int32Array; sizes: number[] } {
+export function labelIslands(art: Uint8Array, w: number, h: number): { label: Int32Array; sizes: number[] } {
   const label = new Int32Array(w * h);
   const sizes: number[] = [];
   const stack: number[] = [];
@@ -1185,7 +1216,7 @@ export function traceAlphaOutline(
  * The authored-mesh measurement floods 4, as it always has; the two agree on
  * every mask the trace accepts.
  */
-function fillEnclosed(
+export function fillEnclosed(
   inside: Uint8Array,
   w: number,
   h: number,
@@ -1242,7 +1273,7 @@ function fillEnclosed(
  * same convention `src/render.ts` rasterises by. A degenerate triangle — zero
  * doubled area — is skipped rather than given an orientation it does not have.
  */
-function rasteriseTriangles(points: Array<[number, number]>, triangles: number[], w: number, h: number): Uint8Array {
+export function rasteriseTriangles(points: Array<[number, number]>, triangles: number[], w: number, h: number): Uint8Array {
   const covered = new Uint8Array(w * h);
   for (let t = 0; t + 2 < triangles.length; t += 3) {
     const a = points[triangles[t]];
@@ -1420,7 +1451,7 @@ export function measureAuthoredMeshFit(
  * a distance. A grid with no set pixel at all comes back all `INF`; the one caller
  * never asks (a mask with no art has no covered-outside pixel to ask about).
  */
-function squaredDistanceToSet(inside: Uint8Array, w: number, h: number): Float64Array {
+export function squaredDistanceToSet(inside: Uint8Array, w: number, h: number): Float64Array {
   const INF = w * w + h * h + 1;
   const dist = new Float64Array(w * h);
   for (let i = 0; i < dist.length; i++) dist[i] = inside[i] ? 0 : INF;