rig-c 2.23.0 → 2.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.23.0",
+  "version": "2.24.1",
   "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

@@ -2036,7 +2036,7 @@ export function meshEdges(vertexCount: number, triangles: readonly number[], hul
 // that used to re-implement distance weighting outside the compiler states the
 // segment list and nothing else.
 //
-// The algorithm is a port of `spine-parts`' lattice mesh and segment weights
+// The algorithm is a port of `rig-parts`' lattice mesh and segment weights
 // (MIT, same owner). What it does, in order:
 //
 //   1. **Cells.** A square lattice of `cell`-pixel squares over the part; the

package/src/meshquality.ts

@@ -235,6 +235,14 @@ export interface MeshReductionInput {
   deform: DeformTimelineInput[];
   /** Every linked mesh of the source (they inherit the new topology); empty when none. */
   linkedMeshes: AttachmentRef[];
+  /**
+   * Replay (issue #1268, §7 mechanism 2): stop after the n-th accepted step — a refinement insertion or a removal
+   * taken, counted as `ReductionChanges.acceptedAt` counts them — and return the mesh the same call without this field
+   * had at that step, byte for byte, terminated `replayed-to-accepted-step`. Left out = today's behaviour. A whole
+   * number, 0 or more: 0 takes no step. A number the run never reaches leaves the run to end as it would have, and
+   * that termination says so (`stopAfterAccepted` on it).
+   */
+  stopAfterAccepted?: number;
 }
 
 /**
@@ -402,6 +410,12 @@ export interface ReductionChanges {
   deformReevaluated: Array<{ animation: string; attachment: AttachmentRef; key: number }>;
   /** Every linked mesh of the source: each inherits the new topology. */
   linkedMeshes: AttachmentRef[];
+  /**
+   * Issue #1268: the attempt number — `candidatesTried` as it stood when the step was taken, 1-based — of every
+   * accepted step, ascending: each refinement insertion and each removal, so its length is
+   * `insertedVertices + removedVertices`. `stopAfterAccepted: k` replays to the step at `acceptedAt[k - 1]`.
+   */
+  acceptedAt: number[];
 }
 
 export interface MeshQualityReport {
@@ -445,6 +459,8 @@ export interface EffectiveSettings {
   boneOrder: string[] | null;
   schedule: MotionSchedule | null;
   budget: { maxCandidates: number } | null;
+  /** A reduction's `stopAfterAccepted`, echoed when the input set it (issue #1268); absent otherwise. */
+  stopAfterAccepted?: number;
 }
 
 export interface MeshCounts {
@@ -457,10 +473,20 @@ export interface MeshCounts {
   maxInfluences: number;
 }
 
+/**
+ * Issue #1268: carried by a run's own termination when the input asked for `stopAfterAccepted` and the run ended
+ * before that many steps were accepted — `requested` the input's n, `acceptedSteps` how many the run took.
+ */
+export interface StopNotReached {
+  requested: number;
+  acceptedSteps: number;
+}
+
 /** *Termination reasons*. Every `reduce` report carries exactly one; a `measure` carries one only when it could not read the mesh. */
 export type Termination =
-  | { reason: 'no-further-valid-reduction'; candidatesTried: number; blockingConstraint: string }
-  | { reason: 'budget-exhausted'; candidatesTried: number; budget: number; result: 'best-meeting-every-bound' | 'none-met-the-targets' }
+  | { reason: 'no-further-valid-reduction'; candidatesTried: number; blockingConstraint: string; stopAfterAccepted?: StopNotReached }
+  | { reason: 'budget-exhausted'; candidatesTried: number; budget: number; result: 'best-meeting-every-bound' | 'none-met-the-targets'; stopAfterAccepted?: StopNotReached }
+  | { reason: 'replayed-to-accepted-step'; acceptedSteps: number; candidatesTried: number }
   | { reason: 'invalid-input'; code: string; detail: string }
   | { reason: 'unsupported-topology'; code: string; detail: string };
 
@@ -908,7 +934,7 @@ function runsAlongOuterBoundary(a: Pt, b: Pt, poly: readonly Pt[], transition: n
 }
 
 /**
- * [agreed, spine-parts#126] Is the edge `a`–`b` held by `region` — does the
+ * [agreed, rig-parts#126] Is the edge `a`–`b` held by `region` — does the
  * region's density bound (`MQ_MAX_EDGE` or `MQ_TRANSITION`) apply to it? The
  * one definition both `measureMeshQuality` and `reduceMesh`'s refinement read.
  *
@@ -1648,7 +1674,7 @@ interface Edge {
  *
  * Which edges a region holds is `edgeIsHeldByRegion`'s answer and nothing
  * else's: an edge that only touches the band's outer boundary at one point,
- * from outside, is not held (spine-parts#126). One bound per edge, the smallest
+ * from outside, is not held (rig-parts#126). One bound per edge, the smallest
  * applicable anywhere on it (P16): `L0` of every region whose closed polygon it
  * meets, and `L0 + grade·d` of every other region that holds it, `d` its
  * distance from that region. A row's value is the edge whose
@@ -1963,6 +1989,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     boneOrder: e.boneOrder === null ? null : [...e.boneOrder],
     schedule: scheduleJson(e.schedule),
     budget: e.budget === null ? null : { maxCandidates: e.budget.maxCandidates },
+    ...(e.stopAfterAccepted === undefined ? {} : { stopAfterAccepted: e.stopAfterAccepted }),
   };
 }
 
@@ -2040,18 +2067,24 @@ function candidateJson(c: CandidateReport): Json {
       deformRemapped: k.deformRemapped.map((d) => ({ animation: d.animation, attachment: attachmentJson(d.attachment), key: d.key, droppedVertices: [...d.droppedVertices] })),
       deformReevaluated: k.deformReevaluated.map((d) => ({ animation: d.animation, attachment: attachmentJson(d.attachment), key: d.key })),
       linkedMeshes: k.linkedMeshes.map(attachmentJson),
+      acceptedAt: [...k.acceptedAt],
     };
   }
   return out;
 }
 
+const notReachedJson = (s: StopNotReached | undefined): { [key: string]: Json } =>
+  s === undefined ? {} : { stopAfterAccepted: { requested: s.requested, acceptedSteps: s.acceptedSteps } };
+
 function terminationJson(t: Termination | null): Json {
   if (t === null) return null;
   switch (t.reason) {
     case 'no-further-valid-reduction':
-      return { reason: t.reason, candidatesTried: t.candidatesTried, blockingConstraint: t.blockingConstraint };
+      return { reason: t.reason, candidatesTried: t.candidatesTried, blockingConstraint: t.blockingConstraint, ...notReachedJson(t.stopAfterAccepted) };
     case 'budget-exhausted':
-      return { reason: t.reason, candidatesTried: t.candidatesTried, budget: t.budget, result: t.result };
+      return { reason: t.reason, candidatesTried: t.candidatesTried, budget: t.budget, result: t.result, ...notReachedJson(t.stopAfterAccepted) };
+    case 'replayed-to-accepted-step':
+      return { reason: t.reason, acceptedSteps: t.acceptedSteps, candidatesTried: t.candidatesTried };
     case 'invalid-input':
     case 'unsupported-topology':
       return { reason: t.reason, code: t.code, detail: t.detail };

package/src/meshreduce.ts

@@ -17,7 +17,7 @@
  *
  * Each is its own function with its own entry and exit, so a control can run
  * one with the other idle — regions empty, or every source vertex protected —
- * which is the shape the consumer asked for (spine-parts#126, comment
+ * which is the shape the consumer asked for (rig-parts#126, comment
  * 6042150608: "separate composed operations … with independently passing
  * controls for each").
  *
@@ -53,7 +53,7 @@
  * the edge lies outside the region and its band, the split is where the edge
  * leaves the band, so the piece to that end only touches the band's outer
  * boundary and `edgeIsHeldByRegion` — the one definition the rows read —
- * exempts it (spine-parts#126). Otherwise the split is at the midpoint when
+ * exempts it (rig-parts#126). Otherwise the split is at the midpoint when
  * the midpoint lies in the region or its band, else at the point of the edge
  * inside them nearest the midpoint. A region no edge meets — one
  * inside a single triangle — gets the first vertex of its polygon inserted into
@@ -105,6 +105,7 @@ import {
   type RefinementRegion,
   type ReductionChanges,
   type SourceMesh,
+  type StopNotReached,
   type Termination,
 } from './meshquality.ts';
 import { artRastersOf, stepRastersOf, type ArtRasters, type StepRasters } from './meshrasters.ts';
@@ -260,6 +261,9 @@ function validateReduction(input: MeshReductionInput): void {
   if (!isObject(b) || !Number.isInteger(b.maxCandidates) || (b.maxCandidates as number) < 0) {
     refuse('REDUCE_INPUT_MISSING', `${who}: budget is ${JSON.stringify(b)}; required { maxCandidates: a whole number, 0 or more } — the work bound has no default`);
   }
+  if ('stopAfterAccepted' in input && input.stopAfterAccepted !== undefined && (!Number.isInteger(input.stopAfterAccepted) || input.stopAfterAccepted < 0)) {
+    refuse('REDUCE_INPUT_MISSING', `${who}: stopAfterAccepted is ${JSON.stringify(input.stopAfterAccepted)}; required a whole number of accepted steps, 0 or more, or the field left out (issue #1268: replay to that step)`);
+  }
   const src = input.source;
   if (!isObject(src) || !Array.isArray(src.points)) refuse('REDUCE_INPUT_MISSING', `${who}: source is not { points, uvs, triangles, hull, weights }`);
   const n = src.points.length;
@@ -729,6 +733,10 @@ interface Run {
   sourceHull: Array<[number, number]>;
   /** Steps tried so far, refinement insertions and removal attempts alike. */
   steps: number;
+  /** Issue #1268: `steps` as it stood at each accepted step — every insertion made and every removal taken — in order. */
+  acceptedAt: number[];
+  /** The replay fault planted for a control, or null. */
+  plant: ReplayPlant | null;
   tally: Tally;
   keyed: Map<number, { animation: string; ref: AttachmentRef; key: number; time: number }>;
   protectedVertices: Set<number>;
@@ -875,7 +883,7 @@ function offsetExit(inner: Pt, outer: Pt, poly: readonly Pt[], level: number): n
 }
 
 /**
- * [agreed, spine-parts#126] A split of `inner`–`outer` where it leaves
+ * [agreed, rig-parts#126] A split of `inner`–`outer` where it leaves
  * `region`'s band, so that the piece to `outer` only touches the band's outer
  * boundary and is exempt by `edgeIsHeldByRegion` — the one definition the
  * measurement reads. The split is put half of `BAND_CONTACT_TOLERANCE` inside
@@ -959,7 +967,27 @@ function insertPoint(run: Run, p: Pt): boolean {
 type PhaseEnd =
   | { kind: 'done' }
   | { kind: 'budget' }
-  | { kind: 'stuck'; constraint: string };
+  | { kind: 'stuck'; constraint: string }
+  | { kind: 'replayed' };
+
+/**
+ * Record an accepted step (issue #1268) and say whether the call's `stopAfterAccepted` is now reached — checked
+ * straight after the step, before the budget is read again, so the replay stops in exactly the state the
+ * unreplayed run held after that step.
+ */
+function accept(run: Run): boolean {
+  run.acceptedAt.push(run.steps);
+  const stop = run.input.stopAfterAccepted;
+  if (stop === undefined) return false;
+  const at = run.plant === 'stop-one-early' ? stop - 1 : run.plant === 'stop-one-late' ? stop + 1 : stop;
+  return run.acceptedAt.length >= at;
+}
+
+/**
+ * A fault planted on purpose in the replay, for the mesh-quality suite's controls (issue #1268): the stop taken
+ * one accepted step before or after the one asked for. `reduceMesh` plants none.
+ */
+export type ReplayPlant = 'stop-one-early' | 'stop-one-late';
 
 /**
  * Refine the working mesh until every region's `MQ_MAX_EDGE` and
@@ -983,13 +1011,14 @@ function refineRegions(run: Run): PhaseEnd {
     if (target.state === 'not-measurable') {
       const p: Pt = [r6(region.polygon[0][0]), r6(region.polygon[0][1])];
       if (!insertPoint(run, p)) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no triangle holding the region's first vertex)` };
+      if (accept(run)) return { kind: 'replayed' };
       continue;
     }
     const [ra, rb] = target.worst!.at.edge!;
     const a = canon.order[ra];
     const b = canon.order[rb];
     // An end outside the region and its band: split where the edge leaves the band, so the piece to that
-    // end only touches the band's outer boundary and is exempt (spine-parts#126) — the same predicate the
+    // end only touches the band's outer boundary and is exempt (rig-parts#126) — the same predicate the
     // measurement reads decides it, so the next measurement agrees.
     let exited = false;
     for (const [inner, outer] of [[b, a], [a, b]] as const) {
@@ -1000,7 +1029,10 @@ function refineRegions(run: Run): PhaseEnd {
       exited = true;
       break;
     }
-    if (exited) continue;
+    if (exited) {
+      if (accept(run)) return { kind: 'replayed' };
+      continue;
+    }
     // An end outside the region and its band further beyond it than the edge's own bound, with no split on
     // the band's outer boundary that frees the piece to it — always so with transition 0, where a contact
     // with the authored boundary stays held: every split keeps a held edge from a vertex inside the region
@@ -1013,7 +1045,7 @@ function refineRegions(run: Run): PhaseEnd {
         const why =
           region.transition > 0
             ? 'no point of the edge on the band\'s outer boundary leaves the piece to it exempt, so an edge from inside the region and its band to it stays over the bound'
-            : 'with no band, an edge from the region to it touches the authored boundary and stays held (spine-parts#126), so it stays over the bound';
+            : 'with no band, an edge from the region to it touches the authored boundary and stays held (rig-parts#126), so it stays over the bound';
         return {
           kind: 'stuck',
           constraint: `${rowName(target)} (vertex ${end} of edge ${ra}–${rb} lies ${r6(beyond)} px beyond region "${region.name}"'s ${region.transition} px band, further than the edge's bound ${target.bound!.value}: ${why}, and the refinement inserts only inside them — P16)`,
@@ -1023,6 +1055,7 @@ function refineRegions(run: Run): PhaseEnd {
     const p = splitPoint(run.work.pos[a], run.work.pos[b], region);
     if (p === null) return { kind: 'stuck', constraint: `${rowName(target)} (the refinement found no point of edge ${ra}–${rb} strictly between its ends inside region "${region.name}" or its band)` };
     splitEdge(run, a, b, p);
+    if (accept(run)) return { kind: 'replayed' };
   }
 }
 
@@ -1115,8 +1148,10 @@ function removeVertices(run: Run): PhaseEnd {
       run.steps++;
       tried++;
       const block = tryRemoval(run, v);
-      if (block === null) taken++;
-      else lastBlock = `${block}, removing source vertex ${v}`;
+      if (block === null) {
+        taken++;
+        if (accept(run)) return { kind: 'replayed' };
+      } else lastBlock = `${block}, removing source vertex ${v}`;
     }
     if (taken === 0) {
       if (tried === 0) lastBlock = 'protect: every surviving source vertex is protected (protect.hull, protect.vertices, protect.edges, protect.regionBoundaries or a weightJump edge)';
@@ -1193,6 +1228,11 @@ function tryRemoval(run: Run, v: number): string | null {
  *   returned when it meets every required bound, and none is when it does not;
  * - `no-further-valid-reduction`: a pass took no step, naming what blocked the
  *   last one. A local stop: nothing here says the result is the smallest.
+ * - `replayed-to-accepted-step`: the input's `stopAfterAccepted` was reached —
+ *   the mesh is the one the same call without it held after that many accepted
+ *   steps, byte for byte (issue #1268). Never reported as an exhausted budget; a
+ *   stop the run does not reach leaves the run's own termination, which then
+ *   carries `stopAfterAccepted: { requested, acceptedSteps }`.
  */
 export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
   validateReduction(input);
@@ -1215,19 +1255,19 @@ export function reduceMesh(input: MeshReductionInput): MeshReductionResult {
  * module with `export *`, and a symbol that is merely exported is not promised
  * (RELEASING.md, *The import surface*).
  */
-export function reduceMeshWith(input: MeshReductionInput, rasters: ArtRasters, steps: StepRasters | null = stepRastersOf(rasters)): MeshReductionResult {
+export function reduceMeshWith(input: MeshReductionInput, rasters: ArtRasters, steps: StepRasters | null = stepRastersOf(rasters), plant: ReplayPlant | null = null): MeshReductionResult {
   validateReduction(input);
   if (steps !== null && steps.rasters !== rasters) {
     refuse('REDUCE_ART_RASTERS_MISMATCH', `attachment ${nameOf(input.attachment)}: the step rasters were made over another rasters object; required step rasters made over the rasters passed beside them (stepRastersOf(rasters))`);
   }
-  return reduceValidated(input, rasters, steps);
+  return reduceValidated(input, rasters, steps, plant);
 }
 
 /**
  * The operation, over an input `validateReduction` accepted; the art's rasters are computed at most once, in
  * `rasters`, and every refinement and removal step is measured through `steps` when it is given (issue #1246).
  */
-function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps: StepRasters | null): MeshReductionResult {
+function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps: StepRasters | null, plant: ReplayPlant | null = null): MeshReductionResult {
   const who = `attachment ${nameOf(input.attachment)}`;
   const src = input.source;
   const sourceHull: Array<[number, number]> = src.points.slice(0, Math.max(0, src.hull)).map(([x, y]): [number, number] => [x, y]);
@@ -1302,6 +1342,8 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
       sourceTurn: Math.sign(signedArea(sourceHull)),
       sourceHull,
       steps: 0,
+      acceptedAt: [],
+      plant,
       tally: { sharesDroppedOnGrid: 0, sharesPruned: 0 },
       keyed: keyedSourceVertices(input),
       ...protectionOf(input, work, sourceEdges),
@@ -1310,20 +1352,28 @@ function reduceValidated(input: MeshReductionInput, rasters: ArtRasters, steps:
       stepRasters: steps,
     };
 
+    // Issue #1268: a replay ends in its own termination, never as an exhausted budget; a stop the run never reaches
+    // leaves the run's own termination, which then carries `stopAfterAccepted` saying so.
+    const replayed = (): Termination => ({ reason: 'replayed-to-accepted-step', acceptedSteps: run.acceptedAt.length, candidatesTried: run.steps });
+    const stop = input.stopAfterAccepted;
+    const notReached = (): { stopAfterAccepted?: StopNotReached } => (stop === undefined ? {} : { stopAfterAccepted: { requested: stop, acceptedSteps: run.acceptedAt.length } });
+    if (stop === 0) return finish(run, effective, sourceCounts, replayed());
     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' });
+    if (refined.kind === 'replayed') return finish(run, effective, sourceCounts, replayed());
+    if (refined.kind === 'budget') return noMesh({ reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'none-met-the-targets', ...notReached() });
     const startCanon = canonicalise(work, run.sourceTurn, boneRank);
     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);
-      termination = { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: `${constraint} — before any removal: the refined source does not meet its targets, so no step from it can` };
+      termination = { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: `${constraint} — before any removal: the refined source does not meet its targets, so no step from it can`, ...notReached() };
     } else {
       const reduced = removeVertices(run);
+      if (reduced.kind === 'replayed') return finish(run, effective, sourceCounts, replayed());
       termination =
         reduced.kind === 'budget'
-          ? { reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'best-meeting-every-bound' }
-          : { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: reduced.kind === 'stuck' ? reduced.constraint : '' };
+          ? { reason: 'budget-exhausted', candidatesTried: run.steps, budget: input.budget.maxCandidates, result: 'best-meeting-every-bound', ...notReached() }
+          : { reason: 'no-further-valid-reduction', candidatesTried: run.steps, blockingConstraint: reduced.kind === 'stuck' ? reduced.constraint : '', ...notReached() };
     }
     return finish(run, effective, sourceCounts, termination);
   } catch (err) {
@@ -1403,6 +1453,7 @@ function finish(run: Run, effective: EffectiveSettings, sourceCounts: MeshCounts
     deformRemapped: deform.remapped.map((d) => ({ animation: d.animation, attachment: d.attachment, key: d.key, droppedVertices: d.droppedVertices })),
     deformReevaluated: deform.reevaluated.map((d) => ({ animation: d.animation, attachment: d.attachment, key: d.key })),
     linkedMeshes: input.linkedMeshes,
+    acceptedAt: [...run.acceptedAt],
   };
   const counts = candidate.counts!;
   const mesh: ReducedMesh = {
@@ -1440,5 +1491,6 @@ function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sou
     targets: input.targets,
     referenceHull: sourceHull,
     budget: { maxCandidates: input.budget.maxCandidates },
+    ...(input.stopAfterAccepted === undefined ? {} : { stopAfterAccepted: input.stopAfterAccepted }),
   };
 }

package/src/transform.ts

@@ -68,7 +68,7 @@ import { modeMatrix, RUNTIME_ARITHMETIC, worldTransforms, type CoreWorld, type W
 
 /**
  * What `computeWorldTransforms` reads off a bone — a structural type, so both a
- * Spine bone (`SpineBone`, what spine-parts and every skeleton reader hold) and
+ * Spine bone (`SpineBone`, what rig-parts and every skeleton reader hold) and
  * a compiled-model bone (`ModelBone`, what `compile` holds) satisfy it as they
  * are, without a cast.
  *