rig-c 2.28.0 → 2.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.28.0",
+  "version": "2.30.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/mesh.ts

@@ -50,9 +50,11 @@ import type { ModelBinding, ModelVertices } from './model.ts';
 // 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.
+// the same rule. So does the skinning residual and its envelope helper
+// (`src/meshskinning.ts`, issue #1294), which the measurement reads.
 export * from './meshquality.ts';
 export * from './meshreduce.ts';
+export * from './meshskinning.ts';
 
 export interface MeshSpecInput {
   /** Polygon in part-local pixels, y down, in manifest order. */

package/src/meshallocation.ts

@@ -54,6 +54,10 @@ type Weights = ReadonlyArray<ReadonlyArray<{ bone: string; weight: number }>>;
  * - `bstar-ignores-art`: B\* without the art test.
  * - `rows-required`: the rows counted as required.
  * - `mutates-input`: the measurement sorts the caller's triangle list in place.
+ * - `gradation-defaulted`: an amplitude whose `gradation` is left out or `null` read at 0.75, §8's fixtures' value —
+ *   the default issue #1291 measured and refused to choose.
+ * - `load-needs-gradation`: `MQ_DEFORM_LOAD` left unread for want of a `gradation` it does not read.
+ * - `gradation-ignored`: the need relaxed at 0.75 whatever `gradation` declares, so Δ no longer reads the field.
  */
 export type AllocationPlant =
   | 'omit-rows'
@@ -64,7 +68,10 @@ export type AllocationPlant =
   | 'undeclared-pair-is-rigid'
   | 'bstar-ignores-art'
   | 'rows-required'
-  | 'mutates-input';
+  | 'mutates-input'
+  | 'gradation-defaulted'
+  | 'load-needs-gradation'
+  | 'gradation-ignored';
 
 /** The art as the allocation rows read it: art pixels on the mask's grid, and the scale that grid is at. */
 export interface AllocationArt {
@@ -493,7 +500,11 @@ export interface AllocationContrast {
   worstVertex: number;
 }
 
-/** h\*: the largest local size every primary need allows at a point, each relaxed at gradation G away from its source. */
+/**
+ * h\*: the largest local size every primary need allows at a point, each relaxed at gradation G away from its source —
+ * G the caller's `motionAmplitude.gradation`, never a constant of this module: §8 measured that it derives from nothing
+ * a rig declares and that Δ moves with it (issue #1291). A region relaxes at its own declared `grade` over its band.
+ */
 interface Need {
   at(p: Pt): number;
 }
@@ -559,7 +570,8 @@ function needField(points: readonly Pt[], triangles: readonly number[], weights:
 const twiceSigned = (a: Pt, b: Pt, c: Pt): number => (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]);
 
 /**
- * Δ and E (§8; the stage-A record for #1271, M7). For each vertex the
+ * Δ and E (§8; the stage-A record for #1271, M7), with the need relaxing at `gradation` — the caller's declared G,
+ * which `measureMeshQuality` hands over only when it is set. For each vertex the
  * cheapest half-edge collapse into a neighbour — a hull vertex only along the
  * hull — that turns no triangle over; ν is the largest, over what that
  * collapse changes, of: the silhouette (the moved outline's chord distance
@@ -580,13 +592,15 @@ export function allocationContrast(
   art: AllocationArt,
   regions: readonly RefinementRegion[],
   declared: MotionAmplitude,
+  gradation: number,
   silhouette: number[],
   plant: AllocationPlant | null,
 ): Reading<AllocationContrast> {
   const n = points.length;
   const pairs = new PairAmplitudes(declared, plant);
   const amplitudeRead = plant !== 'contrast-without-amplitude';
-  const need = needField(points, triangles, weights, silhouette, regions, amplitudeRead ? pairs : new PairAmplitudes({ tracks: [], gradation: declared.gradation }, 'undeclared-pair-is-rigid'), declared.gradation);
+  const G = plant === 'gradation-ignored' ? 0.75 : gradation;
+  const need = needField(points, triangles, weights, silhouette, regions, amplitudeRead ? pairs : new PairAmplitudes({ tracks: [] }, 'undeclared-pair-is-rigid'), G);
   if (need === null) return unmeasured(undeclaredPairReason(pairs.missing!));
   const nb: Array<Set<number>> = Array.from({ length: n }, () => new Set<number>());
   const triOf: number[][] = Array.from({ length: n }, () => []);

package/src/meshcarriers.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a UV sample lies in a mesh's UV triangulation — §3 and correction 4 of
+ * docs/MESH_REDUCTION.md, the common domain two triangulations of one
+ * attachment are compared on.
+ *
+ * `uvCarriers` was written for the motion comparison (`src/meshcompare.ts`,
+ * issue #1230), which still re-exports it from `rig-c/meshcompare` where it is
+ * promised. It lives here, in a module that links no poser, because the
+ * skinning residual (`src/meshskinning.ts`, issue #1294) reads the same carriers
+ * from `rig-c/mesh`, which is geometry-only (§0, P1): one definition of "the
+ * triangle that carries this UV" for both, so the residual and the motion row
+ * it is compared with can never disagree about which triangle a sample is in.
+ *
+ * Pure: no clock, no randomness, no runtime.
+ */
+import { MeshReductionError } from './mesh.ts';
+import { areaBand, triangleAreas } from './areaband.ts';
+
+/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
+const CONTAINS = 1e-9;
+
+function refuse(code: string, message: string): never {
+  throw new MeshReductionError(code, message);
+}
+
+/** A sample's carrier: the UV triangle that contains it, its three vertex indices and the sample's barycentric coordinates there. */
+export interface Carrier {
+  triangle: number;
+  corners: [number, number, number];
+  bary: [number, number, number];
+}
+
+/**
+ * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
+ * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
+ * other than across a vertex or edge they share.
+ */
+export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
+  const areas = triangleAreas(uvs, triangles);
+  const band = areaBand(areas, uvs);
+  const live: number[] = [];
+  const boxes: number[] = [];
+  for (let t = 0; t < areas.length; t++) {
+    if (Math.abs(areas[t]) <= band) continue;
+    live.push(t);
+    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
+    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
+    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
+  }
+  return samples.map((s) => {
+    const [px, py] = s.uv;
+    const hits: Carrier[] = [];
+    live.forEach((t, k) => {
+      const slack = 1e-9;
+      if (px < boxes[k * 4] - slack || py < boxes[k * 4 + 1] - slack || px > boxes[k * 4 + 2] + slack || py > boxes[k * 4 + 3] + slack) return;
+      const i0 = triangles[t * 3];
+      const i1 = triangles[t * 3 + 1];
+      const i2 = triangles[t * 3 + 2];
+      const ax = uvs[i0 * 2];
+      const ay = uvs[i0 * 2 + 1];
+      const bx = uvs[i1 * 2] - ax;
+      const by = uvs[i1 * 2 + 1] - ay;
+      const cx = uvs[i2 * 2] - ax;
+      const cy = uvs[i2 * 2 + 1] - ay;
+      const qx = px - ax;
+      const qy = py - ay;
+      const det = bx * cy - cx * by;
+      const l1 = (qx * cy - cx * qy) / det;
+      const l2 = (bx * qy - qx * by) / det;
+      const l0 = 1 - l1 - l2;
+      if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return;
+      hits.push({ triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] });
+    });
+    if (hits.length === 0) return null;
+    if (hits.length === 1) return hits[0];
+    // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
+    // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
+    const support = (c: Carrier): string =>
+      c.corners
+        .filter((_v, k) => c.bary[k] > CONTAINS)
+        .sort((a, b) => a - b)
+        .join(',');
+    const first = support(hits[0]);
+    const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
+    if (!shared) {
+      refuse(
+        'COMPARE_UV_CARRIER_NOT_UNIQUE',
+        `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
+      );
+    }
+    return hits[0];
+  });
+}

package/src/meshcompare.ts

@@ -79,6 +79,7 @@ import { artOf, MeshReductionError, r6 } from './mesh.ts';
 import {
   measureMeshQuality,
   MESH_QUALITY_REPORT_SPEC,
+  validateMotionAmplitude,
   type ArtFitBounds,
   type ArtInput,
   type AttachmentRef,
@@ -89,6 +90,7 @@ import {
   type MeasureRow,
   type MeshCounts,
   type MeshQualityReport,
+  type MotionAmplitude,
   type MotionBounds,
   type MotionReading,
   type MotionRowDetail,
@@ -98,6 +100,7 @@ import {
   type WorstSample,
 } from './meshquality.ts';
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
+import { uvCarriers, type Carrier } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
 import { poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
 import { sampleTime } from './core/animation.ts';
@@ -151,15 +154,31 @@ export interface MotionComparisonInput {
   bounds: MotionBounds;
   motionRequired: boolean;
   perFrame: boolean;
+  /**
+   * Issue #1291: the motion amplitude the setup art fit's measurement reads — `MeshMeasureInput.motionAmplitude`, the
+   * same shape and the same handling, handed to that measurement of every build and to nothing else (no frame, no
+   * motion row and no acceptance reads it). Left out, it is not declared and the setup sections' `MQ_DEFORM_LOAD`
+   * and `MQ_ALLOCATION_CONTRAST` are `not-measurable` naming it, as before the field existed; `null` declares it
+   * absent; set, `MQ_DEFORM_LOAD` is measured on each build's setup section. `MQ_ALLOCATION_CONTRAST` stays
+   * `not-measurable` there either way, naming `targets.maxBoundaryDeviation`: the comparison declares no deviation
+   * bound and no reference hull. Anything that is not a `MotionAmplitude` in full is refused `COMPARE_INPUT_MISSING`
+   * before any build is read, in the measurement's words. Echoed in `effective` when set, `null` included.
+   */
+  motionAmplitude?: MotionAmplitude | null;
 }
 
+/**
+ * Issue #1291's faults in carrying `motionAmplitude` into the setup measurement, for the `mesh-compare` suite's
+ * negative controls: the amplitude not handed over; `null` handed over as the field left out; the field not validated
+ * before the builds are read; `null` echoed for a field left out; and the load counted as a required row, so the
+ * amplitude moves a verdict. `compareMeshesInMotion` plants none.
+ */
+export type ComparePlant = 'amplitude-not-carried' | 'null-read-as-left-out' | 'amplitude-unvalidated' | 'echo-when-unset' | 'amplitude-gates-acceptance';
+
 // ---------------------------------------------------------------------------
 // fixed tolerances — the tree's own
 // ---------------------------------------------------------------------------
 
-/** `pointInTriangle`'s epsilon in `src/mesh.ts`, applied to each barycentric coordinate. */
-const CONTAINS = 1e-9;
-
 /** §3 *Independent evidence* (a): the rows a reference is refused on — its art fit against its own mask, and only that. */
 const REFERENCE_ART_FIT: readonly string[] = ['MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT'];
 
@@ -204,7 +223,7 @@ function validateFit(field: string, f: unknown): void {
  * art itself (mask, threshold, frame) is `measureMeshQuality`'s to refuse, by
  * its own codes, when the setup art fit is taken.
  */
-function validateInput(input: MotionComparisonInput): void {
+function validateInput(input: MotionComparisonInput, plant: ComparePlant | null): void {
   if (!isObject(input)) missing('the input', input, 'a MotionComparisonInput object');
   const builds = [input.reference, ...(Array.isArray(input.candidates) ? input.candidates : [])];
   if (!Array.isArray(input.candidates) || input.candidates.length === 0) missing('candidates', input.candidates, 'a non-empty list of builds');
@@ -257,6 +276,16 @@ function validateInput(input: MotionComparisonInput): void {
   if (b.minStretch !== undefined && (!isFiniteNumber(b.minStretch) || b.minStretch < 0)) missing('bounds.minStretch', b.minStretch, 'a finite ratio >= 0, or the field left out');
   if (typeof input.motionRequired !== 'boolean') missing('motionRequired', input.motionRequired, 'true or false (P6)');
   if (typeof input.perFrame !== 'boolean') missing('perFrame', input.perFrame, 'true or false (P7)');
+  if (plant !== 'amplitude-unvalidated') {
+    // Issue #1291: the measurement's own validator, so a comparison and a measurement refuse one value in the same
+    // words — under the comparison's code, and here, before any build is read.
+    try {
+      validateMotionAmplitude('the comparison', input.motionAmplitude);
+    } catch (err) {
+      if (err instanceof MeshReductionError) refuse('COMPARE_INPUT_MISSING', err.message.slice(err.code.length + 2));
+      throw err;
+    }
+  }
   const s = input.schedule;
   if (s === null) return;
   if (!isObject(s)) missing('schedule', s, 'a MotionSchedule, or null for no motion');
@@ -554,6 +583,9 @@ function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames
 // §3 — the samples and their carriers
 // ---------------------------------------------------------------------------
 
+/** Promised on `rig-c/meshcompare` since issue #1230; defined in `src/meshcarriers.ts` since issue #1294, which the skinning residual shares. */
+export { uvCarriers };
+
 interface Sample {
   uv: [number, number];
   /** Part-local drawing px, y down — where a region's polygon is read. */
@@ -563,12 +595,6 @@ interface Sample {
   vertex: number | null;
 }
 
-interface Carrier {
-  triangle: number;
-  corners: [number, number, number];
-  bary: [number, number, number];
-}
-
 interface MeshOf {
   uvs: number[];
   triangles: number[];
@@ -576,68 +602,6 @@ interface MeshOf {
   weights: SourceMesh['weights'];
 }
 
-/**
- * Each sample's carrier in one mesh's UV triangulation — §3 and correction 4.
- * Throws `COMPARE_UV_CARRIER_NOT_UNIQUE` for a sample two triangles carry
- * other than across a vertex or edge they share.
- */
-export function uvCarriers(uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> {
-  const areas = triangleAreas(uvs, triangles);
-  const band = areaBand(areas, uvs);
-  const live: number[] = [];
-  const boxes: number[] = [];
-  for (let t = 0; t < areas.length; t++) {
-    if (Math.abs(areas[t]) <= band) continue;
-    live.push(t);
-    const xs = [uvs[triangles[t * 3] * 2], uvs[triangles[t * 3 + 1] * 2], uvs[triangles[t * 3 + 2] * 2]];
-    const ys = [uvs[triangles[t * 3] * 2 + 1], uvs[triangles[t * 3 + 1] * 2 + 1], uvs[triangles[t * 3 + 2] * 2 + 1]];
-    boxes.push(Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys));
-  }
-  return samples.map((s) => {
-    const [px, py] = s.uv;
-    const hits: Carrier[] = [];
-    live.forEach((t, k) => {
-      const slack = 1e-9;
-      if (px < boxes[k * 4] - slack || py < boxes[k * 4 + 1] - slack || px > boxes[k * 4 + 2] + slack || py > boxes[k * 4 + 3] + slack) return;
-      const i0 = triangles[t * 3];
-      const i1 = triangles[t * 3 + 1];
-      const i2 = triangles[t * 3 + 2];
-      const ax = uvs[i0 * 2];
-      const ay = uvs[i0 * 2 + 1];
-      const bx = uvs[i1 * 2] - ax;
-      const by = uvs[i1 * 2 + 1] - ay;
-      const cx = uvs[i2 * 2] - ax;
-      const cy = uvs[i2 * 2 + 1] - ay;
-      const qx = px - ax;
-      const qy = py - ay;
-      const det = bx * cy - cx * by;
-      const l1 = (qx * cy - cx * qy) / det;
-      const l2 = (bx * qy - qx * by) / det;
-      const l0 = 1 - l1 - l2;
-      if (l0 < -CONTAINS || l1 < -CONTAINS || l2 < -CONTAINS) return;
-      hits.push({ triangle: t, corners: [i0, i1, i2], bary: [l0, l1, l2] });
-    });
-    if (hits.length === 0) return null;
-    if (hits.length === 1) return hits[0];
-    // Several carriers are one hit only across a vertex or an edge they all share: the sample's support — the corners
-    // it does not sit at zero weight on — is then the same vertex indices in each, and the carried point is theirs.
-    const support = (c: Carrier): string =>
-      c.corners
-        .filter((_v, k) => c.bary[k] > CONTAINS)
-        .sort((a, b) => a - b)
-        .join(',');
-    const first = support(hits[0]);
-    const shared = first.split(',').length <= 2 && hits.every((c) => support(c) === first);
-    if (!shared) {
-      refuse(
-        'COMPARE_UV_CARRIER_NOT_UNIQUE',
-        `${who}: the sample at uv (${px}, ${py}) lies in ${hits.length} UV triangles — ${hits.map((c) => `triangle ${c.triangle} (vertices ${c.corners.join(', ')})`).join(' and ')} — that do not meet there at a shared vertex or edge; required one carrier per sample (correction 4: overlapping or folded UV triangles would carry it by an arbitrary one)`,
-      );
-    }
-    return hits[0];
-  });
-}
-
 /** The point a carrier puts the sample at over one pose's world vertices. */
 function carried(c: Carrier, world: readonly number[]): [number, number] {
   const [i0, i1, i2] = c.corners;
@@ -852,7 +816,24 @@ function foldingSlots(raw: unknown, who: string): Set<string> {
  * undercut at the setup pose fails `referenceArtFit`, and `measureMeshQuality`'s own codes for the art).
  */
 export function compareMeshesInMotion(input: MotionComparisonInput): MeshQualityReport {
-  validateInput(input);
+  return compareMeshesInMotionWith(input, null);
+}
+
+/**
+ * `compareMeshesInMotion` with a fault planted in how it carries `motionAmplitude` (`ComparePlant`) — the
+ * `mesh-compare` suite's negative controls. Internal: merely exported, so not promised (RELEASING.md *The import
+ * surface*).
+ */
+export function compareMeshesInMotionPlanted(input: MotionComparisonInput, plant: ComparePlant): MeshQualityReport {
+  return compareMeshesInMotionWith(input, plant);
+}
+
+function compareMeshesInMotionWith(input: MotionComparisonInput, plant: ComparePlant | null): MeshQualityReport {
+  validateInput(input, plant);
+  const amplitude = input.motionAmplitude;
+  // What the setup measurement is handed: the field as the caller set it — left out as left out, `null` as `null`.
+  const handed: { motionAmplitude?: MotionAmplitude | null } =
+    plant === 'amplitude-not-carried' || amplitude === undefined || (plant === 'null-read-as-left-out' && amplitude === null) ? {} : { motionAmplitude: amplitude };
   const refs = input.attachments.map((a) => a.attachment);
   const reference = readBuild(input.reference, 'reference', refs);
   const candidates = input.candidates.map((c, i) => readBuild(c, `candidates[${i}]`, refs));
@@ -895,9 +876,14 @@ export function compareMeshesInMotion(input: MotionComparisonInput): MeshQuality
         influences: null,
         boneOrder: null,
         preset: null,
+        ...handed,
       });
       const c = measured.candidates[0];
       if (c.geometry === null || c.counts === null) return { geometry: null, counts: null };
+      if (plant === 'amplitude-gates-acceptance') {
+        const load = c.geometry.rows.find((r) => r.code === 'MQ_DEFORM_LOAD');
+        if (load !== undefined && load.state === 'undeclared') c.geometry.verdict = 'fail';
+      }
       sections.push(c.geometry);
       counts.push(c.counts);
     }
@@ -1176,6 +1162,7 @@ export function compareMeshesInMotion(input: MotionComparisonInput): MeshQuality
     boneOrder: null,
     schedule,
     budget: null,
+    ...(amplitude === undefined ? (plant === 'echo-when-unset' ? { motionAmplitude: null } : {}) : { motionAmplitude: amplitude }),
   };
   return {
     spec: MESH_QUALITY_REPORT_SPEC,