rig-c 2.20.4 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.20.4",
+  "version": "2.21.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/meshcompare.ts

@@ -191,8 +191,11 @@ function missing(field: string, found: unknown, required: string): never {
 }
 
 function validateFit(field: string, f: unknown): void {
-  if (!isObject(f) || !isFiniteNumber(f.minCoverage) || f.minCoverage < 0 || f.minCoverage > 1 || !isFiniteNumber(f.maxOvershoot) || f.maxOvershoot < 0 || !isFiniteNumber(f.maxUndercut) || f.maxUndercut < 0) {
-    missing(field, f, '{ minCoverage in 0..1, maxOvershoot >= 0, maxUndercut >= 0 }');
+  // `null` on maxOvershoot or maxUndercut is a bound declared absent (issue #1254): measured, reported `undeclared`,
+  // never refusing a reference or failing a candidate. A field left out is still refused.
+  const distance = (v: unknown): boolean => v === null || (isFiniteNumber(v) && v >= 0);
+  if (!isObject(f) || !isFiniteNumber(f.minCoverage) || f.minCoverage < 0 || f.minCoverage > 1 || !distance(f.maxOvershoot) || !distance(f.maxUndercut)) {
+    missing(field, f, '{ minCoverage in 0..1, maxOvershoot >= 0 or null, maxUndercut >= 0 or null }');
   }
 }
 

package/src/meshquality.ts

@@ -116,14 +116,23 @@ export interface SourceMesh {
   weights: Array<Array<{ bone: string; weight: number }>> | null;
 }
 
-/** All distances in the drawing's pixels; converted to texels by `pageScale`. */
+/**
+ * All distances in the drawing's pixels; converted to texels by `pageScale`.
+ *
+ * `maxOvershoot` and `maxUndercut` may be `null` — a bound **declared absent**
+ * (issue #1254): the row is measured and reported `undeclared`, with its value
+ * and worst sample, and never passes, fails, blocks a step or refuses a source.
+ * A field left out (`undefined`) is still refused by name: an omission cannot be
+ * told from a caller that forgot, and only the explicit `null` says "measured,
+ * not bounded". `minCoverage` has no such form and is always required.
+ */
 export interface ArtFitBounds {
   /** Share of art pixel centres the triangles cover, 0..1. */
   minCoverage: number;
-  /** Furthest a covered pixel may sit outside the filled silhouette, px. */
-  maxOvershoot: number;
-  /** Furthest an uncovered art pixel may sit from the covered set, px. */
-  maxUndercut: number;
+  /** Furthest a covered pixel may sit outside the filled silhouette, px; null = declared absent. */
+  maxOvershoot: number | null;
+  /** Furthest an uncovered art pixel may sit from the covered set, px; null = declared absent. */
+  maxUndercut: number | null;
 }
 
 /** What a reduction's RESULT must satisfy (correction 3). Read by `reduceMesh`, stage B2. */
@@ -607,7 +616,7 @@ function validateInput(input: MeshMeasureInput): void {
     if (!isFiniteNumber(coverage) || coverage < 0 || coverage > 1) refuse('REDUCE_INPUT_MISSING', `${who}: targets.artFit.minCoverage is ${JSON.stringify(coverage)}; required a fraction in 0..1`);
     for (const field of ['maxOvershoot', 'maxUndercut'] as const) {
       const v = fit[field];
-      if (!isFiniteNumber(v) || v < 0) refuse('REDUCE_INPUT_MISSING', `${who}: targets.artFit.${field} is ${JSON.stringify(v)}; required a finite number of px, 0 or more`);
+      if (v !== null && (!isFiniteNumber(v) || v < 0)) refuse('REDUCE_INPUT_MISSING', `${who}: targets.artFit.${field} is ${JSON.stringify(v)}; required a finite number of px, 0 or more, or null (declared absent: measured, reported undeclared)`);
     }
   }
   present(who, 'targets.maxBoundaryDeviation', targets.maxBoundaryDeviation, 'a number of px or null');
@@ -1298,8 +1307,8 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   if (artCount < input.minArtSamples) {
     const why = `attachment ${nameOf(attachment)} has ${artCount} art sample(s) at alpha >= ${threshold}; required at least ${input.minArtSamples} (minArtSamples, P9) — a row over fewer is not a measurement`;
     rows.push(withRaster(unmeasuredRow(spec('MQ_COVERAGE', 'fraction'), 'not-measurable', why, fit !== null), rasterArt(null), grid, artCount === 0 ? 1 : 1 / artCount));
-    rows.push(withRaster(unmeasuredRow(spec('MQ_OVERSHOOT', 'px'), 'not-measurable', why, fit !== null), rasterArt(8), grid, pxIncrement));
-    rows.push(withRaster(unmeasuredRow(spec('MQ_UNDERCUT', 'px'), 'not-measurable', why, fit !== null), rasterArt(null), grid, pxIncrement));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_OVERSHOOT', 'px'), 'not-measurable', why, fit !== null && fit.maxOvershoot !== null), rasterArt(8), grid, pxIncrement));
+    rows.push(withRaster(unmeasuredRow(spec('MQ_UNDERCUT', 'px'), 'not-measurable', why, fit !== null && fit.maxUndercut !== null), rasterArt(null), grid, pxIncrement));
     rows.push(withRaster(unmeasuredRow(spec('MQ_HOLES', 'count'), 'not-measurable', why, false), rasterArt(8), grid, 1));
     rows.push(withRaster(unmeasuredRow(spec('MQ_ISLANDS', 'count'), 'not-measurable', why, false), rasterArt(4), grid, 1));
   } else {
@@ -1322,8 +1331,8 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
     rows.push(
       withRaster(
         !anyCovered
-          ? unmeasuredRow(undercutSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the triangles cover no pixel centre of the ${w}x${h} grid, so no art pixel has a distance to a covered one`, fit !== null)
-          : measuredRow(undercutSpec, r6(Math.sqrt(undercutSq) / scale), fit === null ? null : { op: '<=', value: fit.maxUndercut }, missingWorst, true),
+          ? unmeasuredRow(undercutSpec, 'not-measurable', `attachment ${nameOf(attachment)}: the triangles cover no pixel centre of the ${w}x${h} grid, so no art pixel has a distance to a covered one`, fit !== null && fit.maxUndercut !== null)
+          : measuredRow(undercutSpec, r6(Math.sqrt(undercutSq) / scale), fit === null || fit.maxUndercut === null ? null : { op: '<=', value: fit.maxUndercut }, missingWorst, true),
         rasterArt(null),
         grid,
         pxIncrement,
@@ -1335,7 +1344,7 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
     const fillsDiffer = rasters.fills().differ;
     const silhouetteRows = (connectivity: 4 | 8, gated: boolean): void => {
       const { overAt, overSq, holes, holeAt } = reading.silhouette(connectivity);
-      const bound = gated && fit !== null ? { op: '<=' as const, value: fit.maxOvershoot } : null;
+      const bound = gated && fit !== null && fit.maxOvershoot !== null ? { op: '<=' as const, value: fit.maxOvershoot } : null;
       rows.push(
         withRaster(
           measuredRow(spec('MQ_OVERSHOOT', 'px'), r6(Math.sqrt(overSq) / scale), bound, overAt === -1 ? NOTHING_WORSE : { at: { pixel: pixelOf(overAt) } }, gated),

package/src/meshreduce.ts

@@ -29,7 +29,8 @@
  * #1240), and as `measureMeshQualityStep` carried from the last step's
  * measurement (`StepRasters`, issue #1246), each of which returns the same
  * report — and taken only when every row the caller's
- * contract requires is `pass`: the art fit at `targets.artFit`, the boundary
+ * contract requires is `pass`: the art fit at `targets.artFit` (an overshoot or
+ * undercut bound declared `null` is measured and never required), the boundary
  * deviation from the source hull at `targets.maxBoundaryDeviation`, the minimum
  * angle when declared, orientation and degeneracy at 0, and every region's
  * `MQ_MAX_EDGE` and `MQ_TRANSITION`. Before the measurement, the structural
@@ -216,11 +217,27 @@ class Stop extends Error {
 function checkFit(who: string, field: string, fit: unknown): void {
   if (fit === undefined || fit === null || !isObject(fit)) refuse('REDUCE_INPUT_MISSING', `${who}: ${field} is ${JSON.stringify(fit)}; required { minCoverage, maxOvershoot, maxUndercut } — no field has a default`);
   if (!isFiniteNumber(fit.minCoverage) || fit.minCoverage < 0 || fit.minCoverage > 1) refuse('REDUCE_INPUT_MISSING', `${who}: ${field}.minCoverage is ${JSON.stringify(fit.minCoverage)}; required a fraction in 0..1`);
+  // `null` is a bound declared absent (issue #1254): measured, reported `undeclared`, never gating. A field left
+  // out is not the same thing and stays refused — `JSON.stringify` names it `undefined` in the message.
   for (const k of ['maxOvershoot', 'maxUndercut'] as const) {
-    if (!isFiniteNumber(fit[k]) || (fit[k] as number) < 0) refuse('REDUCE_INPUT_MISSING', `${who}: ${field}.${k} is ${JSON.stringify(fit[k])}; required a finite number of px, 0 or more`);
+    const v = fit[k];
+    if (v !== null && (!isFiniteNumber(v) || v < 0)) refuse('REDUCE_INPUT_MISSING', `${who}: ${field}.${k} is ${JSON.stringify(v)}; required a finite number of px, 0 or more, or null (declared absent: measured, reported undeclared)`);
   }
 }
 
+/**
+ * Whether `fit` declares the bound of an art row absent (issue #1254): the
+ * 8-connected `MQ_OVERSHOOT` under `maxOvershoot: null`, `MQ_UNDERCUT` under
+ * `maxUndercut: null`. Such a row is `undeclared` when measured and is never
+ * required — not for admission, not for a step, not when it could not be
+ * measured. Every other row answers false.
+ */
+function artBoundAbsent(fit: ArtFitBounds, row: MeasureRow): boolean {
+  if (row.code === 'MQ_OVERSHOOT') return fit.maxOvershoot === null;
+  if (row.code === 'MQ_UNDERCUT') return fit.maxUndercut === null;
+  return false;
+}
+
 /**
  * The fields a reduction reads and a measurement does not, refused by name. The
  * art, the mesh's arrays, the regions' shapes and the sample floors are refused
@@ -755,12 +772,14 @@ function rowName(row: MeasureRow): string {
 
 /**
  * The first required row that is not `pass`, in `BLOCKING_ORDER`, or null when
- * every one passes. A row is required exactly when its bound is declared; the
+ * every one passes. A row is required exactly when its bound is declared — an
+ * art bound declared `null` is not (`artBoundAbsent`, issue #1254); the
  * overshoot row gated is the 8-connected one (P12).
  */
-function firstBlockingRow(report: MeshQualityReport): MeasureRow | null {
+function firstBlockingRow(report: MeshQualityReport, artFit: ArtFitBounds): MeasureRow | null {
   const rows = report.candidates[0]?.geometry?.rows ?? [];
   const required = (r: MeasureRow): boolean => {
+    if (artBoundAbsent(artFit, r)) return false;
     if (r.code === 'MQ_OVERSHOOT') return r.art?.connectivity === 8;
     if (r.code === 'MQ_MIN_ANGLE') return r.bound !== null;
     if (r.code === 'MQ_HOLES' || r.code === 'MQ_ISLANDS' || r.code === 'MQ_TRACE_DEVIATION' || r.code === 'MQ_FILL_DISTANCE') return false;
@@ -1142,7 +1161,7 @@ function tryRemoval(run: Run, v: number): string | null {
     undo();
     return `outline: ${err.message}`;
   }
-  const blocking = firstBlockingRow(measureAgainstTargets(run, canon.mesh, 'candidate'));
+  const blocking = firstBlockingRow(measureAgainstTargets(run, canon.mesh, 'candidate'), run.input.targets.artFit);
   if (blocking !== null) {
     undo();
     return rowName(blocking);
@@ -1250,7 +1269,7 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     }
     for (const code of ['MQ_ORIENTATION', 'MQ_DEGENERATE', 'MQ_COVERAGE', 'MQ_OVERSHOOT', 'MQ_UNDERCUT']) {
       const row = admitRows.find((r) => r.code === code && (code !== 'MQ_OVERSHOOT' || r.art?.connectivity === 8));
-      if (row !== undefined && row.state !== 'pass') {
+      if (row !== undefined && row.state !== 'pass' && !artBoundAbsent(input.sourceBounds, row)) {
         const found = row.state === 'fail' ? `${row.value} against ${row.bound!.op} ${row.bound!.value}` : `${row.state} (${row.reason ?? ''})`;
         throw new Stop(
           'invalid-input',
@@ -1294,7 +1313,7 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
     const refined = refineRegions(run);
     if (refined.kind === 'budget') return noMesh({ reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'none-met-the-targets' });
     const startCanon = canonicalise(work, run.sourceTurn, boneRank);
-    const startBlock = firstBlockingRow(measureAgainstTargets(run, startCanon.mesh, 'start'));
+    const startBlock = firstBlockingRow(measureAgainstTargets(run, startCanon.mesh, 'start'), input.targets.artFit);
     let termination: Termination;
     if (startBlock !== null) {
       const constraint = refined.kind === 'stuck' ? refined.constraint : rowName(startBlock);