spine-rigc 2.18.0 → 2.19.1

package/package.json

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

@@ -49,7 +49,10 @@ import type { ModelBinding, ModelVertices } from './model.ts';
 // `spine-rigc/mesh` names. That module imports helpers from this one, so the
 // two form an import cycle: safe only because neither reads the other's
 // bindings while it is being evaluated — every use is inside a function.
+// The reduction (`reduceMesh`, stage B2 of #1224) sits in the same cycle, by
+// the same rule.
 export * from './meshquality.ts';
+export * from './meshreduce.ts';
 
 export interface MeshSpecInput {
   /** Polygon in part-local pixels, y down, in manifest order. */

package/src/meshquality.ts

@@ -6,9 +6,9 @@
  * attachment draws, and the bounds the caller declared, measured into one
  * `mesh-quality-report/1` document (`writeMeshQualityReport` writes its text).
  * Every type the contract declares is declared here too, including the ones
- * only the reduction (`reduceMesh`, stage B2) and the motion comparison
- * (stage C) will fill, so that those stages build on one set of types rather
- * than restating them.
+ * only the reduction (`reduceMesh`, stage B2, in `src/meshreduce.ts`) and the
+ * motion comparison (stage C) fill, so that those stages build on one set of
+ * types rather than restating them.
  *
  * ## What it is for
  *
@@ -181,7 +181,28 @@ export interface InfluenceLimits {
   minWeight: number;
 }
 
-/** Everything a reduction reads (stage B2). No field has a default inside the operation. */
+/**
+ * One deform key of a timeline the reduced attachment is keyed under (§6, P18),
+ * in the form the compiler emits it: a `vertices` run is the emitted `offset`
+ * (an index into the deform array — two numbers per vertex unweighted, two per
+ * influence weighted, AUTHORING §4.11) and the numbers copied in from there; a
+ * `transform` key is a model the compile evaluates over the attachment's own
+ * geometry (§4.11.1), so it has no run to remap; a `setup` key carries no run.
+ */
+export type DeformKeyInput =
+  | { time: number; kind: 'setup' }
+  | { time: number; kind: 'vertices'; offset: number; vertices: number[] }
+  | { time: number; kind: 'transform' };
+
+/** One deform timeline: the animation, the attachment it is keyed on, and its keys in order. */
+export interface DeformTimelineInput {
+  animation: string;
+  /** The reduced attachment itself, or one of `MeshReductionInput.linkedMeshes`. */
+  attachment: AttachmentRef;
+  keys: DeformKeyInput[];
+}
+
+/** Everything a reduction reads (stage B2, `reduceMesh` in `src/meshreduce.ts`). No field has a default inside the operation. */
 export interface MeshReductionInput {
   attachment: AttachmentRef;
   art: ArtInput;
@@ -198,8 +219,16 @@ export interface MeshReductionInput {
   boneOrder: string[] | null;
   /** P5: the preset the caller expanded, if any, echoed and never read. */
   preset: { name: string; version: string } | null;
-  /** Work bound — *Termination reasons*. */
+  /** Work bound — *Termination reasons*. Every refinement insertion and every removal attempted counts one. */
   budget: { maxCandidates: number };
+  /** P9: the fewest art samples the attachment's raster rows are taken over. A whole number >= 1. */
+  minArtSamples: number;
+  /** P9: one floor per region, by region name — every region named once. */
+  regionArtSamples: Array<{ region: string; minArtSamples: number }>;
+  /** P18: every deform timeline keyed on the attachment or on one of its linked meshes; empty when none. */
+  deform: DeformTimelineInput[];
+  /** Every linked mesh of the source (they inherit the new topology); empty when none. */
+  linkedMeshes: AttachmentRef[];
 }
 
 /**
@@ -341,6 +370,29 @@ export interface CandidateReport {
   accepted: boolean;
   /** Opt-in (P7): every row's value at every frame. Absent unless asked for. */
   perFrame?: Array<{ code: string; frame: string; value: number | null }>;
+  /** A `reduce` whose result exists: what the operation changed. Absent on a `measure` and when no mesh is returned. */
+  changes?: ReductionChanges;
+}
+
+/**
+ * What a reduction changed, counted rather than described — the figures the
+ * contract says are reported (§6, P18 and P19) and that no geometry row carries.
+ */
+export interface ReductionChanges {
+  /** Source vertices the reduction removed. */
+  removedVertices: number;
+  /** Vertices the refinement inserted (§5). */
+  insertedVertices: number;
+  /** P19: positive interpolated shares that are 0 on the 6-decimal weight grid, dropped rather than written as 0. */
+  sharesDroppedOnGrid: number;
+  /** Interpolated shares pruned by `InfluenceLimits` — over `maxInfluences`, or under a nonzero `minWeight`. */
+  sharesPruned: number;
+  /** P18: `vertices` keys remapped, each with the source vertices whose offsets were dropped. */
+  deformRemapped: Array<{ animation: string; attachment: AttachmentRef; key: number; droppedVertices: number[] }>;
+  /** P18: `transform` keys, re-evaluated over the new geometry at compile rather than remapped. */
+  deformReevaluated: Array<{ animation: string; attachment: AttachmentRef; key: number }>;
+  /** Every linked mesh of the source: each inherits the new topology. */
+  linkedMeshes: AttachmentRef[];
 }
 
 export interface MeshQualityReport {
@@ -421,6 +473,20 @@ const HAUSDORFF_TOLERANCE = 1e-9;
 /** The predicate epsilon `segmentsMeet` and `prunePolygon` use (`src/mesh.ts`), for "on the boundary". */
 const ON_BOUNDARY = 1e-9;
 
+/**
+ * How near a region's band's outer boundary, in drawing px, an edge's nearest
+ * point has to come to count as touching it rather than entering the band —
+ * the precision of "a single point on the outer boundary" in
+ * `edgeIsHeldByRegion`, ten units of the `r6` grid. The refinement puts the
+ * vertex it splits an edge at half of this inside the outer boundary and then
+ * on the grid, which moves it by at most √2 × 5e-7 px, so the piece beyond it
+ * lands inside this tolerance from either side.
+ */
+export const BAND_CONTACT_TOLERANCE = 1e-5;
+
+/** Halvings of the parameter interval in the convex searches along an edge (`edgeIsHeldByRegion`): 2^-60 of an edge is below a double's resolution of it. */
+const EDGE_SEARCH_STEPS = 60;
+
 // ---------------------------------------------------------------------------
 // refusals
 // ---------------------------------------------------------------------------
@@ -656,6 +722,110 @@ function segmentToPolygon(a: Pt, b: Pt, poly: readonly Pt[]): number {
   return best;
 }
 
+/**
+ * The parameter in `[0, 1]` along `a`–`b` nearest which `c`–`d` lies — the
+ * minimum of the distance from `a + t(b − a)` to the segment `c`–`d`, which is
+ * convex in `t`, found by golden-section search. A flat minimum (parallel
+ * segments) returns some point of it; the callers never read one there.
+ */
+function nearestParameter(a: Pt, b: Pt, c: Pt, d: Pt): number {
+  const at = (t: number): number => distanceToSegment([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t], c, d);
+  const g = (Math.sqrt(5) - 1) / 2;
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < EDGE_SEARCH_STEPS; i++) {
+    const p = hi - g * (hi - lo);
+    const q = lo + g * (hi - lo);
+    if (at(p) <= at(q)) hi = q;
+    else lo = p;
+  }
+  return (lo + hi) / 2;
+}
+
+/**
+ * Does `a`–`b` run along the outer boundary of a band of width `transition`
+ * for a positive length — some polygon edge it overlaps in projection by more
+ * than `BAND_CONTACT_TOLERANCE`, at that edge's perpendicular distance
+ * `transition` (within the tolerance) at both ends of the overlap, so at every
+ * point between them? The caller has already found the edge's nearest approach
+ * to the polygon within the tolerance of `transition`.
+ */
+function runsAlongOuterBoundary(a: Pt, b: Pt, poly: readonly Pt[], transition: number): boolean {
+  const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const c = poly[i];
+    const e = poly[(i + 1) % n];
+    const side = Math.hypot(e[0] - c[0], e[1] - c[1]);
+    if (side === 0) continue;
+    const ux = (e[0] - c[0]) / side;
+    const uy = (e[1] - c[1]) / side;
+    const sa = (a[0] - c[0]) * ux + (a[1] - c[1]) * uy;
+    const sb = (b[0] - c[0]) * ux + (b[1] - c[1]) * uy;
+    let t0 = 0;
+    let t1 = 1;
+    if (sa === sb) {
+      if (sa < 0 || sa > side) continue;
+    } else {
+      const p = (0 - sa) / (sb - sa);
+      const q = (side - sa) / (sb - sa);
+      t0 = Math.max(0, Math.min(p, q));
+      t1 = Math.min(1, Math.max(p, q));
+    }
+    if ((t1 - t0) * length <= BAND_CONTACT_TOLERANCE) continue;
+    const off = (t: number): number => Math.abs(ux * (a[1] + (b[1] - a[1]) * t - c[1]) - uy * (a[0] + (b[0] - a[0]) * t - c[0]));
+    if (Math.abs(off(t0) - transition) <= BAND_CONTACT_TOLERANCE && Math.abs(off(t1) - transition) <= BAND_CONTACT_TOLERANCE) return true;
+  }
+  return false;
+}
+
+/**
+ * [agreed, spine-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.
+ *
+ * The region's active domain is its closed polygon and, when `transition > 0`,
+ * the band of that width outside it. An edge is held when it meets that domain,
+ * except for one case: its intersection with the domain is a **single point on
+ * the band's outer boundary** and the rest of the edge lies outside — an edge
+ * that only touches the band from outside is exempt.
+ *
+ * - An edge that meets the closed polygon is held, whatever the band.
+ * - With `transition: 0` there is no outer band, and a contact with the
+ *   authored boundary is held under the closed-region rule — never exempt.
+ * - A positive-length intersection is held, including a segment lying along
+ *   the band's outer boundary.
+ * - Two separate touches of the outer boundary are two points, not one, and
+ *   the edge is held.
+ *
+ * "On the outer boundary" is within `BAND_CONTACT_TOLERANCE`. Each region is
+ * read on its own: an exemption from one never removes another's bound.
+ */
+export function edgeIsHeldByRegion(a: readonly [number, number], b: readonly [number, number], region: RefinementRegion): boolean {
+  const poly: readonly Pt[] = region.polygon;
+  if (segmentMeetsPolygon(a, b, poly)) return true;
+  const transition = region.transition;
+  if (!(transition > 0)) return false;
+  const d = segmentToPolygon(a, b, poly);
+  if (d > transition) return false;
+  if (d < transition - BAND_CONTACT_TOLERANCE) return true;
+  if (runsAlongOuterBoundary(a, b, poly, transition)) return true;
+  // Where on the edge each polygon side is touched: one point, or several apart.
+  const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  let first = Infinity;
+  let last = -Infinity;
+  const n = poly.length;
+  for (let i = 0; i < n; i++) {
+    const c = poly[i];
+    const e = poly[(i + 1) % n];
+    if (segmentDistance(a, b, c, e) > transition) continue;
+    const t = nearestParameter(a, b, c, e);
+    first = Math.min(first, t);
+    last = Math.max(last, t);
+  }
+  return (last - first) * length > BAND_CONTACT_TOLERANCE;
+}
+
 /** Distance from a point to a closed polyline (the polygon's boundary), and the edge that realises it. */
 function pointToBoundary(p: Pt, poly: readonly Pt[]): { d: number; edge: number } {
   let d = Infinity;
@@ -1149,9 +1319,12 @@ interface Edge {
  * graded band, only where the band has width) and `MQ_FILL_DISTANCE` (`h(R)`,
  * sampled, informational).
  *
- * 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 band
- * it lies in, `d` its distance from that region. A row's value is the edge whose
+ * 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
+ * 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
  * 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.
  */
@@ -1190,15 +1363,29 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
     else refusals.set(region.name, `${refusal.code}: ${refusal.message}`);
   }
 
-  /** Every bound that applies to an edge, from every measurable region, and the smallest. */
+  /**
+   * Per measurable region, per edge (in `edges` order): the edge's distance
+   * from the closed polygon when the region holds it (`edgeIsHeldByRegion`,
+   * the one definition the refinement reads too), null when it does not.
+   */
+  const holds = new Map<RefinementRegion, Array<number | null>>();
+  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)),
+    );
+  }
+  const edgeIndex = new Map(edges.map((e, i) => [e, i]));
+
+  /** Every bound that applies to an edge, from every measurable region that holds it, and the smallest. */
   const boundOf = (e: Edge): number | null => {
     let bound: number | null = null;
+    const i = edgeIndex.get(e)!;
     for (const region of live) {
-      const d = segmentToPolygon(points[e.a], points[e.b], region.polygon);
-      let here: number | null = null;
-      if (d === 0) here = region.maxEdgeLength;
-      else if (region.transition > 0 && d <= region.transition) here = r6(region.maxEdgeLength + region.grade * d);
-      if (here !== null && (bound === null || here < bound)) bound = here;
+      const d = holds.get(region)![i];
+      if (d === null) continue;
+      const here = d === 0 ? region.maxEdgeLength : r6(region.maxEdgeLength + region.grade * d);
+      if (bound === null || here < bound) bound = here;
     }
     return bound;
   };
@@ -1228,7 +1415,8 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
       continue;
     }
     const poly: Pt[] = region.polygon;
-    const inside = edges.filter((e) => segmentMeetsPolygon(points[e.a], points[e.b], poly));
+    const held = holds.get(region)!;
+    const inside = edges.filter((_, i) => held[i] === 0);
     const maxSpec = spec('MQ_MAX_EDGE', 'px', region.name);
     const inWorst = worstOf(inside);
     if (inWorst === null) {
@@ -1237,10 +1425,7 @@ function regionRows(input: MeshMeasureInput, outline: MeshOutline, hullPolygon:
       out.push(measuredRow(maxSpec, r6(inWorst.edge.length), { op: '<=', value: inWorst.bound }, { at: { edge: [inWorst.edge.a, inWorst.edge.b] } }, true));
     }
     if (region.transition > 0) {
-      const banded = edges.filter((e) => {
-        const d = segmentToPolygon(points[e.a], points[e.b], poly);
-        return d > 0 && d <= region.transition;
-      });
+      const banded = edges.filter((_, i) => held[i] !== null && held[i]! > 0);
       const bandWorst = worstOf(banded);
       const transitionSpec = spec('MQ_TRANSITION', 'px', region.name);
       if (bandWorst === null) {
@@ -1470,6 +1655,18 @@ function candidateJson(c: CandidateReport): Json {
     accepted: c.accepted,
   };
   if (c.perFrame !== undefined) out.perFrame = c.perFrame.map((p) => ({ code: p.code, frame: p.frame, value: p.value }));
+  if (c.changes !== undefined) {
+    const k = c.changes;
+    out.changes = {
+      removedVertices: k.removedVertices,
+      insertedVertices: k.insertedVertices,
+      sharesDroppedOnGrid: k.sharesDroppedOnGrid,
+      sharesPruned: k.sharesPruned,
+      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),
+    };
+  }
   return out;
 }