spine-rigc 2.20.3 → 2.21.0

package/package.json

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

@@ -69,7 +69,7 @@ import {
   type MeshOutline,
 } from './mesh.ts';
 import { areaBand, triangleAreas } from './areaband.ts';
-import { artRastersOf, type ArtRasters, type CoverageReading, type OutlineMemo, type SilhouetteReading, type StepRasters } from './meshrasters.ts';
+import { artRastersOf, type ArtRasters, type CoverageReading, type OutlineMemo, type RegionEdgeReading, type SilhouetteReading, type StepRasters } from './meshrasters.ts';
 import { cropToSpineY } from './transform.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),
@@ -1427,7 +1436,7 @@ function measureValidated(input: MeshMeasureInput, rasters: ArtRasters, steps: S
   );
 
   // --- regions (§5) ------------------------------------------------------------------------
-  rows.push(...regionRows(input, outline, hullPolygon, rasters));
+  rows.push(...regionRows(input, outline, hullPolygon, rasters, steps));
 
   const ordered = rows.slice().sort((a, b) => compareRows(a.row, b.row));
   const geometry = sectionOf(ordered);
@@ -1477,7 +1486,7 @@ function sectionOf(built: readonly Built[]): EvidenceSection {
 // ---------------------------------------------------------------------------
 
 /** A region's own refusal (§2's `refused`: this measurement's input is invalid), or null when it is measurable. */
-function regionRefusal(region: RefinementRegion, pageScale: number, who: string): { code: string; message: string } | null {
+function regionRefusal(region: RefinementRegion, pageScale: number, who: string, steps: StepRasters | null): { code: string; message: string } | null {
   const numbers: Array<[string, unknown]> = [
     ['maxEdgeLength', region.maxEdgeLength],
     ['transition', region.transition],
@@ -1495,7 +1504,8 @@ function regionRefusal(region: RefinementRegion, pageScale: number, who: string)
       message: `${who}, region "${region.name}": maxEdgeLength is ${region.maxEdgeLength} px; required at least one texel, ${r6(1 / pageScale)} px at pageScale ${pageScale}`,
     };
   }
-  const crossing = findSelfIntersection(region.polygon);
+  // A function of the polygon alone: a reduction step has it handed back by its `StepRasters` (issue #1253).
+  const crossing = steps === null ? findSelfIntersection(region.polygon) : steps.polygonCrossing(region.polygon, () => findSelfIntersection(region.polygon));
   if (crossing !== null) {
     return {
       code: 'REGION_SELF_INTERSECTS',
@@ -1524,8 +1534,13 @@ interface Edge {
  * distance from that region. A row's value is the edge whose
  * length most exceeds its own bound — so the row fails exactly when some edge
  * it covers is over — and the row names that edge and that bound.
+ *
+ * `MQ_FILL_DISTANCE` reads the art pixels whose centre lies in the region's
+ * closed polygon, a function of the art and the polygon alone: a reduction
+ * step has it handed back by its `StepRasters` (`regionPixels`, issue #1253)
+ * rather than testing every art pixel against the polygon again.
  */
-function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon: readonly Pt[], rasters: ArtRasters): Built[] {
+function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon: readonly Pt[], rasters: ArtRasters, steps: StepRasters | null): Built[] {
   const { attachment, source, art } = input;
   const who = `attachment ${nameOf(attachment)}`;
   const scale = art.frame.pageScale;
@@ -1541,14 +1556,35 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
   }
   edges.sort((p, q) => p.a - q.a || p.b - q.b);
 
+  // Each edge's answers for a region: computed here, or — on a reduction step — carried by its `StepRasters` from
+  // the last reading of the region for an edge with the same two ends (`regionEdges`, issue #1253).
+  const readings = new Map<RefinementRegion, RegionEdgeReading | null>();
+  const readingOf = (region: RefinementRegion): RegionEdgeReading | null => {
+    if (!readings.has(region)) readings.set(region, steps === null ? null : steps.regionEdges(region.polygon, region.transition));
+    return readings.get(region)!;
+  };
+  const meetsOf = (region: RefinementRegion, e: Edge): boolean => {
+    const record = readingOf(region)?.entry(points[e.a], points[e.b]);
+    if (record === undefined) return segmentMeetsPolygon(points[e.a], points[e.b], region.polygon);
+    if (record.meets === undefined) record.meets = segmentMeetsPolygon(points[e.a], points[e.b], region.polygon);
+    return record.meets;
+  };
+  const heldOf = (region: RefinementRegion, e: Edge): number | null => {
+    const held = (): number | null => (edgeIsHeldByRegion(points[e.a], points[e.b], region) ? segmentToPolygon(points[e.a], points[e.b], region.polygon) : null);
+    const record = readingOf(region)?.entry(points[e.a], points[e.b]);
+    if (record === undefined) return held();
+    if (record.held === undefined) record.held = held();
+    return record.held;
+  };
+
   // Which regions are measurable, and the one refusal of each that is not.
   const live: RefinementRegion[] = [];
   const refusals = new Map<string, string>();
   for (const region of input.targets.regions) {
-    let refusal = regionRefusal(region, scale, who);
+    let refusal = regionRefusal(region, scale, who, steps);
     if (refusal === null) {
       const poly: Pt[] = region.polygon;
-      const meets = edges.some((e) => segmentMeetsPolygon(points[e.a], points[e.b], poly)) || poly.some((p) => inClosedPolygon(p, hullPolygon));
+      const meets = edges.some((e) => meetsOf(region, e)) || poly.some((p) => inClosedPolygon(p, hullPolygon));
       if (!meets) {
         refusal = {
           code: 'REGION_OUTSIDE_ART',
@@ -1569,7 +1605,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
   for (const region of live) {
     holds.set(
       region,
-      edges.map((e) => (edgeIsHeldByRegion(points[e.a], points[e.b], region) ? segmentToPolygon(points[e.a], points[e.b], region.polygon) : null)),
+      edges.map((e) => heldOf(region, e)),
     );
   }
   const edgeIndex = new Map(edges.map((e, i) => [e, i]));
@@ -1632,23 +1668,42 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
       }
     }
 
-    // h(R): art pixel centres inside the region clipped to the hull, each to its nearest mesh vertex.
+    // h(R): art pixel centres inside the region clipped to the hull, each to its nearest mesh vertex. The art
+    // pixels inside the region come in ascending order, so the scan below visits what a scan of every art pixel
+    // would keep, in the same order.
+    const centreOf = (i: number): Pt => [((i % mask.width) + 0.5) / scale, (Math.floor(i / mask.width) + 0.5) / scale];
+    const inRegion = (): Int32Array => {
+      const kept: number[] = [];
+      for (let i = 0; i < artBits.length; i++) if (artBits[i] && inClosedPolygon(centreOf(i), poly)) kept.push(i);
+      return Int32Array.from(kept);
+    };
+    const regionPixels = steps === null ? inRegion() : steps.regionPixels(poly, inRegion);
     let count = 0;
     let worst = -1;
     let worstAt = -1;
-    for (let i = 0; i < artBits.length; i++) {
-      if (!artBits[i]) continue;
-      const x = i % mask.width;
-      const y = Math.floor(i / mask.width);
-      const centre: Pt = [(x + 0.5) / scale, (y + 0.5) / scale];
-      if (!inClosedPolygon(centre, poly) || !inClosedPolygon(centre, hullPolygon)) continue;
+    const visit = (i: number, nearest: number): void => {
       count++;
-      let nearest = Infinity;
-      for (const p of points) nearest = Math.min(nearest, Math.hypot(p[0] - centre[0], p[1] - centre[1]));
       if (nearest > worst) {
         worst = nearest;
         worstAt = i;
       }
+    };
+    const distance = (i: number, p: Pt): number => {
+      const centre = centreOf(i);
+      return Math.hypot(p[0] - centre[0], p[1] - centre[1]);
+    };
+    if (steps === null) {
+      for (const i of regionPixels) {
+        const centre = centreOf(i);
+        if (!inClosedPolygon(centre, hullPolygon)) continue;
+        let nearest = Infinity;
+        for (const p of points) nearest = Math.min(nearest, Math.hypot(p[0] - centre[0], p[1] - centre[1]));
+        visit(i, nearest);
+      }
+    } else {
+      // A reduction step: the pixels in the hull and their nearest distances carried from the last reading (issue #1253).
+      const carried = steps.regionFill(poly, { pixels: regionPixels, centre: centreOf, hull: hullPolygon, points, inHull: (i) => inClosedPolygon(centreOf(i), hullPolygon), distance });
+      for (let j = 0; j < carried.inside.length; j++) visit(carried.inside[j], carried.nearest[j]);
     }
     const fillSpec = spec('MQ_FILL_DISTANCE', 'px', region.name);
     const floor = floorOf(region.name);

package/src/meshrasters.ts

@@ -215,15 +215,38 @@ export interface StepRasterTally {
   /** Edges a carried list took from the last list of its point, and edges it computed because the edge is new. */
   edgesCarried: number;
   edgesComputed: number;
+  /** Region pixel sets (`regionPixels`) computed, and handed back because the polygon equals one already read. */
+  regionSetsComputed: number;
+  regionSetsReused: number;
+  /** Region polygons checked for a self-intersection (`polygonCrossing`), and checks handed back for an equal polygon. */
+  polygonChecksComputed: number;
+  polygonChecksReused: number;
+  /** Region edge readings (`regionEdges`): an edge's answers carried from the last reading of its region, or computed. */
+  regionEdgesCarried: number;
+  regionEdgesComputed: number;
+  /** Fill readings (`regionFill`): the region pixels in the hull handed back for an equal hull, carried by the hull edges that changed, or measured from nothing; and pixels measured again inside a changed hull's box. */
+  fillHullsReused: number;
+  fillHullsCarried: number;
+  fillHullsMeasured: number;
+  fillHullPixelsMeasured: number;
+  /** Fill readings whose nearest-vertex distances were built from nothing, and pixels carried or measured again in the others. */
+  fillNearestRebuilt: number;
+  fillNearestCarried: number;
+  fillNearestMeasured: number;
 }
 
 /**
  * A fault planted on purpose in the carried path, for the mesh-quality
  * controls to show they catch it: one added triangle not drawn, one changed
- * column or row of the distance transform not redone, or an outline reading
- * reused when only the vertex counts match. `reduceMesh` plants none.
+ * column or row of the distance transform not redone, an outline reading
+ * reused when only the vertex counts match, or a region's art pixels handed
+ * back, or a region polygon's self-intersection check handed back, for a
+ * polygon that only has as many vertices as one read before, or a region
+ * edge's answers carried from an edge that shares only its first end,
+ * the region pixels near a changed hull edge not measured again, or a pixel's
+ * nearest vertex kept after that vertex was removed. `reduceMesh` plants none.
  */
-export type StepRasterPlant = 'skip-a-triangle' | 'skip-a-column' | 'skip-a-row' | 'stale-outline' | 'skip-an-edge';
+export type StepRasterPlant = 'skip-a-triangle' | 'skip-a-column' | 'skip-a-row' | 'stale-outline' | 'skip-an-edge' | 'stale-region' | 'stale-polygon-check' | 'stale-region-edge' | 'stale-fill-hull' | 'stale-fill-nearest';
 
 /**
  * One outline slot's carried distances (`src/meshquality.ts`, `hausdorff`): a
@@ -283,6 +306,38 @@ export interface OutlineMemo {
  *   with a zero's sign, to the last ones of that slot — the same pure function
  *   of the same input.
  *
+ * - **A region's art pixels** (`regionPixels`, issue #1253) — the art pixels
+ *   whose centre lies in a region's closed polygon, which `MQ_FILL_DISTANCE`
+ *   reads — are a function of the art and the polygon alone, so a set is
+ *   handed back whenever the polygon equals, coordinate by coordinate with a
+ *   zero's sign, one already read through this object. A region polygon's
+ *   self-intersection check (`polygonCrossing`), a function of the polygon
+ *   alone, is handed back the same way.
+ * - **A region's edge answers** (`regionEdges`, issue #1253) — whether an
+ *   edge meets the closed polygon, and whether the region holds it and how far
+ *   it lies — are functions of the edge's two ends and the region's polygon and
+ *   band alone, so each is carried from the last reading of that region for an
+ *   edge with both ends equal, coordinate by coordinate, in the same order.
+ * - **A region's fill distances** (`regionFill`, issue #1253) — which of its
+ *   art pixels lie in the hull, and each one's distance to the nearest vertex.
+ *   Whether a pixel lies in the hull is measured again only inside the box of
+ *   the hull edges that changed (directed, both ends exact), widened by
+ *   `HULL_CARRY_MARGIN`: outside it the edges the two hulls share answer the
+ *   same, a changed edge is further than the boundary tolerance, and the
+ *   changed edges cross a horizontal ray from the pixel an even number of
+ *   times between them — none when the pixel is right of, above or below the
+ *   box, and when it is left of it, every changed edge that spans its row,
+ *   whose count is even because the removed and added edges meet each vertex
+ *   an even number of times — so the crossing parity is the last one's.
+ *   A pixel's nearest distance is carried by the vertices that differ
+ *   from the last reading's, compared as a multiset of exact coordinates: when
+ *   the vertex that attained it is still there, the minimum over the vertices
+ *   kept is the last minimum, and the new one is the smaller of it and the
+ *   distances to the vertices added; when that vertex is gone, the pixel is
+ *   measured again over every vertex. A minimum is exact, so either way it is
+ *   the same number. A reading whose vertices differ from the last in more than
+ *   they share is built from nothing.
+ *
  * A reading whose triangles differ from the last in more triangles than they
  * share is built from nothing, as the first one is; which way a reading is
  * built changes its cost and never its values.
@@ -300,6 +355,64 @@ export interface StepRasters {
    * distances, which `measure` reads and keeps current.
    */
   outline<T>(slot: string, outline: ReadonlyArray<readonly [number, number]>, against: ReadonlyArray<readonly [number, number]>, measure: (memo: OutlineMemo) => T): T;
+  /**
+   * `compute()`'s value — the art pixels, ascending, whose centre lies in the
+   * closed `polygon` — or the set already computed for a polygon equal to it
+   * coordinate by coordinate. The art is this object's, so the polygon is the
+   * whole of the key.
+   */
+  regionPixels(polygon: ReadonlyArray<readonly [number, number]>, compute: () => Int32Array): Int32Array;
+  /** `compute()`'s value — `findSelfIntersection` of `polygon` — or the one already computed for a polygon equal to it coordinate by coordinate. */
+  polygonCrossing(polygon: ReadonlyArray<readonly [number, number]>, compute: () => [number, number] | null): [number, number] | null;
+  /**
+   * One reading's answers per edge for the region with this polygon and band:
+   * `entry(a, b)` is the edge's record, carried from the last reading of the
+   * region when an edge with the same two ends (exact coordinates, this order)
+   * was read there, else empty for the caller to fill. Records not read again
+   * are dropped at the next reading.
+   */
+  regionEdges(polygon: ReadonlyArray<readonly [number, number]>, transition: number): RegionEdgeReading;
+  /** The region's fill reading, carried from the last one of the region with this polygon; valid until the next. */
+  regionFill(polygon: ReadonlyArray<readonly [number, number]>, question: RegionFillQuestion): RegionFillReading;
+}
+
+/** A region edge's answers, as `src/meshquality.ts`'s `regionRows` reads them; a field absent is not yet computed. */
+export interface RegionEdgeRecord {
+  /** `segmentMeetsPolygon` of the edge against the closed polygon. */
+  meets?: boolean;
+  /** The edge's distance from the closed polygon when the region holds it (`edgeIsHeldByRegion`), else null. */
+  held?: number | null;
+}
+
+export interface RegionEdgeReading {
+  entry(a: readonly [number, number], b: readonly [number, number]): RegionEdgeRecord;
+}
+
+/**
+ * How far beyond the box of a hull's changed edges a pixel centre must lie for
+ * its answer to be carried, in the hull's units. Far larger than any rounding
+ * of a crossing's abscissa and than the boundary tolerance the test reads.
+ */
+const HULL_CARRY_MARGIN = 1;
+
+/** What `regionFill` is handed: the definitions it reads, which stay `src/meshquality.ts`'s. */
+export interface RegionFillQuestion {
+  /** The region's art pixels, ascending (`regionPixels`). */
+  pixels: Int32Array;
+  /** The centre of art pixel `i`, in the hull's units. */
+  centre(i: number): readonly [number, number];
+  hull: ReadonlyArray<readonly [number, number]>;
+  points: ReadonlyArray<readonly [number, number]>;
+  /** Does the centre of art pixel `i` lie in the closed hull? */
+  inHull(i: number): boolean;
+  /** The distance from the centre of art pixel `i` to `p`. */
+  distance(i: number, p: readonly [number, number]): number;
+}
+
+/** The region pixels in the hull, ascending, and each one's distance to its nearest vertex. */
+export interface RegionFillReading {
+  inside: Int32Array;
+  nearest: Float64Array;
 }
 
 /** A coordinate as a key: its shortest round-trip decimal, with a negative zero told from a positive one. */
@@ -325,6 +438,19 @@ function flat(p: ReadonlyArray<readonly [number, number]>): Float64Array {
 
 type Corners = [readonly [number, number], readonly [number, number], readonly [number, number]];
 
+/** One region's carried fill state: the pixels it was read for, the hull and the positions inside it, and per pixel the nearest vertex. */
+interface FillSlot {
+  polygon: Float64Array;
+  pixels: Int32Array;
+  /** The last hull's directed edges by both ends' exact coordinates, with their counts, and per pixel whether it lay in that hull. */
+  hullEdges: Map<string, { a: readonly [number, number]; b: readonly [number, number]; n: number }> | null;
+  inHull: Uint8Array;
+  points: Map<string, { p: readonly [number, number]; n: number }> | null;
+  nearest: Float64Array;
+  nearX: Float64Array;
+  nearY: Float64Array;
+}
+
 interface HeldTriangles {
   corners: Corners;
   n: number;
@@ -367,11 +493,28 @@ export function stepRastersOf(rasters: ArtRasters, plant: StepRasterPlant | null
     distanceListsCarried: 0,
     edgesCarried: 0,
     edgesComputed: 0,
+    regionSetsComputed: 0,
+    regionSetsReused: 0,
+    polygonChecksComputed: 0,
+    polygonChecksReused: 0,
+    regionEdgesCarried: 0,
+    regionEdgesComputed: 0,
+    fillHullsReused: 0,
+    fillHullsCarried: 0,
+    fillHullsMeasured: 0,
+    fillHullPixelsMeasured: 0,
+    fillNearestRebuilt: 0,
+    fillNearestCarried: 0,
+    fillNearestMeasured: 0,
   };
   const { width: w, height: h } = rasters.art.mask;
   let state: CoverageState | null = null;
   const outlines = new Map<string, { outline: Float64Array; against: Float64Array; value: unknown }>();
   const memos = new Map<string, OutlineMemo>();
+  const regionSets: Array<{ polygon: Float64Array; pixels: Int32Array }> = [];
+  const polygonChecks: Array<{ polygon: Float64Array; crossing: [number, number] | null }> = [];
+  const regionEdgeSlots: Array<{ polygon: Float64Array; transition: number; last: Map<string, RegionEdgeRecord> }> = [];
+  const fillSlots: FillSlot[] = [];
 
   /** Add `sign` to the count of every centre the triangle covers, pushing each such centre to `touched`. */
   const draw = (count: Int32Array, corners: Corners, sign: number, touched: number[] | null): void => {
@@ -617,5 +760,185 @@ export function stepRastersOf(rasters: ArtRasters, plant: StepRasterPlant | null
       outlines.set(slot, { outline: flat(outline), against: flat(against), value });
       return value;
     },
+    regionPixels: (polygon, compute) => {
+      const kept = regionSets.find((r) => (plant === 'stale-region' ? r.polygon.length === polygon.length * 2 : samePolygon(polygon, r.polygon)));
+      if (kept !== undefined) {
+        tally.regionSetsReused++;
+        return kept.pixels;
+      }
+      tally.regionSetsComputed++;
+      const pixels = compute();
+      regionSets.push({ polygon: flat(polygon), pixels });
+      return pixels;
+    },
+    polygonCrossing: (polygon, compute) => {
+      const kept = polygonChecks.find((r) => (plant === 'stale-polygon-check' ? r.polygon.length === polygon.length * 2 : samePolygon(polygon, r.polygon)));
+      if (kept !== undefined) {
+        tally.polygonChecksReused++;
+        return kept.crossing;
+      }
+      tally.polygonChecksComputed++;
+      const crossing = compute();
+      polygonChecks.push({ polygon: flat(polygon), crossing });
+      return crossing;
+    },
+    regionFill: (polygon, q) => {
+      let slot = fillSlots.find((r) => samePolygon(polygon, r.polygon));
+      if (slot === undefined) {
+        slot = { polygon: flat(polygon), pixels: q.pixels, hullEdges: null, inHull: new Uint8Array(0), points: null, nearest: new Float64Array(0), nearX: new Float64Array(0), nearY: new Float64Array(0) };
+        fillSlots.push(slot);
+      }
+      const n = q.pixels.length;
+      // The vertices, as a multiset of exact coordinates, against the last reading's.
+      const keyOf = (p: readonly [number, number]): string => `${coordKey(p[0])},${coordKey(p[1])}`;
+      const points = new Map<string, { p: readonly [number, number]; n: number }>();
+      for (const p of q.points) {
+        const k = keyOf(p);
+        const e = points.get(k);
+        if (e === undefined) points.set(k, { p, n: 1 });
+        else e.n++;
+      }
+      const measure = (k: number): void => {
+        let best = Infinity;
+        let bx = NaN;
+        let by = NaN;
+        for (const p of q.points) {
+          const d = q.distance(q.pixels[k], p);
+          if (d < best) {
+            best = d;
+            bx = p[0];
+            by = p[1];
+          }
+        }
+        slot!.nearest[k] = best;
+        slot!.nearX[k] = bx;
+        slot!.nearY[k] = by;
+      };
+      // A vertex whose coordinates are gone, and one whose coordinates are new; a count that only moved changes no minimum.
+      let gone: Set<string> | null = null;
+      const added: Array<readonly [number, number]> = [];
+      const samePixels = slot.points !== null && slot.pixels === q.pixels;
+      if (samePixels) {
+        gone = new Set();
+        let kept = 0;
+        let differ = 0;
+        for (const [k, { p, n: now }] of points) {
+          const was = slot.points!.get(k)?.n ?? 0;
+          kept += Math.min(was, now);
+          differ += Math.max(0, now - was);
+          if (was === 0) added.push(p);
+        }
+        for (const [k, { n: was }] of slot.points!) {
+          const now = points.get(k)?.n ?? 0;
+          differ += Math.max(0, was - now);
+          if (now === 0) gone.add(k);
+        }
+        if (differ > kept) gone = null;
+      }
+      if (gone === null) {
+        tally.fillNearestRebuilt++;
+        slot.pixels = q.pixels;
+        slot.nearest = new Float64Array(n);
+        slot.nearX = new Float64Array(n);
+        slot.nearY = new Float64Array(n);
+        for (let k = 0; k < n; k++) measure(k);
+      } else {
+        for (let k = 0; k < n; k++) {
+          if (plant !== 'stale-fill-nearest' && gone.has(`${coordKey(slot.nearX[k])},${coordKey(slot.nearY[k])}`)) {
+            tally.fillNearestMeasured++;
+            measure(k);
+            continue;
+          }
+          tally.fillNearestCarried++;
+          for (const p of added) {
+            const d = q.distance(q.pixels[k], p);
+            if (d < slot.nearest[k]) {
+              slot.nearest[k] = d;
+              slot.nearX[k] = p[0];
+              slot.nearY[k] = p[1];
+            }
+          }
+        }
+      }
+      slot.points = points;
+      // The pixels in the hull: carried outside the box of the hull edges that changed, measured again inside it.
+      const hullEdges = new Map<string, { a: readonly [number, number]; b: readonly [number, number]; n: number }>();
+      for (let k = 0; k < q.hull.length; k++) {
+        const a = q.hull[k];
+        const b = q.hull[(k + 1) % q.hull.length];
+        const key = `${keyOf(a)}>${keyOf(b)}`;
+        const e = hullEdges.get(key);
+        if (e === undefined) hullEdges.set(key, { a, b, n: 1 });
+        else e.n++;
+      }
+      if (!samePixels || slot.hullEdges === null) {
+        tally.fillHullsMeasured++;
+        slot.inHull = new Uint8Array(n);
+        for (let k = 0; k < n; k++) slot.inHull[k] = q.inHull(q.pixels[k]) ? 1 : 0;
+      } else {
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        const widen = (p: readonly [number, number]): void => {
+          minX = Math.min(minX, p[0]);
+          maxX = Math.max(maxX, p[0]);
+          minY = Math.min(minY, p[1]);
+          maxY = Math.max(maxY, p[1]);
+        };
+        for (const [key, e] of hullEdges) if ((slot.hullEdges.get(key)?.n ?? 0) !== e.n) (widen(e.a), widen(e.b));
+        for (const [key, e] of slot.hullEdges) if ((hullEdges.get(key)?.n ?? 0) !== e.n) (widen(e.a), widen(e.b));
+        if (minX === Infinity) tally.fillHullsReused++;
+        else {
+          tally.fillHullsCarried++;
+          minX -= HULL_CARRY_MARGIN;
+          minY -= HULL_CARRY_MARGIN;
+          maxX += HULL_CARRY_MARGIN;
+          maxY += HULL_CARRY_MARGIN;
+          for (let k = 0; k < n; k++) {
+            const c = q.centre(q.pixels[k]);
+            if (c[0] < minX || c[0] > maxX || c[1] < minY || c[1] > maxY) continue;
+            if (plant === 'stale-fill-hull') continue;
+            tally.fillHullPixelsMeasured++;
+            slot.inHull[k] = q.inHull(q.pixels[k]) ? 1 : 0;
+          }
+        }
+      }
+      slot.hullEdges = hullEdges;
+      const kept: number[] = [];
+      for (let k = 0; k < n; k++) if (slot.inHull[k]) kept.push(k);
+      const inside = new Int32Array(kept.length);
+      const nearest = new Float64Array(kept.length);
+      kept.forEach((k, j) => {
+        inside[j] = q.pixels[k];
+        nearest[j] = slot!.nearest[k];
+      });
+      return { inside, nearest };
+    },
+    regionEdges: (polygon, transition) => {
+      let slot = regionEdgeSlots.find((r) => Object.is(r.transition, transition) && samePolygon(polygon, r.polygon));
+      if (slot === undefined) {
+        slot = { polygon: flat(polygon), transition, last: new Map() };
+        regionEdgeSlots.push(slot);
+      }
+      const last = slot.last;
+      const now = new Map<string, RegionEdgeRecord>();
+      slot.last = now;
+      const keyOf = (p: readonly [number, number]): string => `${coordKey(p[0])},${coordKey(p[1])}`;
+      return {
+        entry: (a, b) => {
+          const key = plant === 'stale-region-edge' ? keyOf(a) : `${keyOf(a)};${keyOf(b)}`;
+          let record = now.get(key);
+          if (record !== undefined) return record;
+          record = last.get(key);
+          if (record === undefined) {
+            tally.regionEdgesComputed++;
+            record = {};
+          } else tally.regionEdgesCarried++;
+          now.set(key, record);
+          return record;
+        },
+      };
+    },
   };
 }

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);
@@ -1214,24 +1233,23 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
   const sourceHull: Array<[number, number]> = src.points.slice(0, Math.max(0, src.hull)).map(([x, y]): [number, number] => [x, y]);
 
   // The source, measured against its own admissibility bounds (correction 3) — this is also what refuses a
-  // malformed art, mesh, region list or sample floor, by measureMeshQuality's own codes.
-  const admit = measureMeshQualityWith(
-    {
-      id: 'source',
-      attachment: input.attachment,
-      art: input.art,
-      source: src,
-      targets: { artFit: input.sourceBounds, maxBoundaryDeviation: null, regions: input.targets.regions },
-      referenceHull: null,
-      minArtSamples: input.minArtSamples,
-      regionArtSamples: input.regionArtSamples,
-      protect: input.protect,
-      influences: input.influences,
-      boneOrder: input.boneOrder,
-      preset: input.preset,
-    },
-    rasters,
-  );
+  // malformed art, mesh, region list or sample floor, by measureMeshQuality's own codes. Through the step
+  // rasters when the call carries them, so what a region reads of the art alone is computed once (issue #1253).
+  const admitInput: MeshMeasureInput = {
+    id: 'source',
+    attachment: input.attachment,
+    art: input.art,
+    source: src,
+    targets: { artFit: input.sourceBounds, maxBoundaryDeviation: null, regions: input.targets.regions },
+    referenceHull: null,
+    minArtSamples: input.minArtSamples,
+    regionArtSamples: input.regionArtSamples,
+    protect: input.protect,
+    influences: input.influences,
+    boneOrder: input.boneOrder,
+    preset: input.preset,
+  };
+  const admit = steps === null ? measureMeshQualityWith(admitInput, rasters) : measureMeshQualityStep(admitInput, steps);
   const effective = effectiveOf(input, admit.effective, sourceHull);
   const sourceCounts = admit.sourceCounts;
   const noMesh = (termination: Termination): MeshReductionResult => ({
@@ -1251,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',
@@ -1295,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);