spine-rigc 2.47.0 → 2.47.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.47.0",
+  "version": "2.47.1",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/core/raw.ts

@@ -496,13 +496,71 @@ export function poseRawAnimation(doc: CompiledDocument, animation: string, steps
  * A refusal is thrown from the pose it is met at, after `visit` has seen the
  * poses before it. `clock`, when given, is what each step moves the physics
  * clock by in place of the step itself — the render's offline schedule
- * (`physicsClockStep` in `src/render_core.ts`, issue #1380); the track time and
+ * (`physicsClockStep` below, issue #1380); the track time and
  * the animation time are the steps' running sum either way.
  */
 export function poseRawAnimationEach(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, visit: (pose: RawPose, index: number) => void, clock?: (dt: number) => number): void {
   walkEach(doc, animation, steps, plant, reset, clock === undefined ? RAW_MODE : { ...RAW_MODE, clock: (dt) => clock(dt) }, RAW_SHAPE, visit);
 }
 
+/**
+ * How much faster than the frames a render's physics clock runs — and, since issue
+ * #1389, a mesh comparison's (`src/meshcompare.ts`, `comparisonWalk`): each frame
+ * moves the skeleton's clock — the time a physics constraint integrates — by
+ * `physicsClockStep(1 / fps)`, the frame's step and `2⁻³⁰` of it more, while
+ * the animation is applied at the running sum of the frame steps as before
+ * (issue #1380).
+ *
+ * ⭐ **Why a render's physics clock is not the frame clock.** A physics
+ * constraint keeps the time it has not yet integrated (`remaining`), takes
+ * whole steps of `1 / fps` (its own `fps`, 60 by default) while at least one
+ * step remains, and shows `offset − lag·(1 − remaining / step)`, `lag` being
+ * everything this update's steps moved (`src/core/constraints_physics.ts`,
+ * *The step*). Whenever a frame lasts a whole number of physics steps — 12,
+ * 20, 30 and 60 fps against 60 Hz, and every second frame at 24 — the time
+ * left at the frame's end is zero in exact arithmetic, and in doubles it is
+ * either a few ulps above zero or a few ulps short of one whole step. Which of
+ * the two is decided by rounding, not by the motion: the shown weight is 1 or
+ * 0, so the spring is drawn one frame late or on time, and it changes regime
+ * on a single frame. Measured on the public trailer (`show`, 20 fps, 321
+ * frames): every spring jumps at frames 5, 12, 45 and 188 — the four frames
+ * that arithmetic alone predicts — and the loop's start (frame 80, on time)
+ * and end (frame 320, a frame late, which is what exact arithmetic draws)
+ * differ by 31.70 units of vertex and 10.37 of bone
+ * while every keyed bone agrees to 1.3e-12. spine-core 4.3.13 stepped the
+ * same way draws the same frames to the bit: this is the runtime under a
+ * fixed offline step, not a defect of the core's port, which is why the fix
+ * is the render's schedule and the physics is untouched.
+ *
+ * Running the clock `2⁻³⁰` fast puts the time left a little ABOVE every
+ * whole number of steps instead of on it, by `2⁻³⁰ · t` after `t` seconds:
+ * 1.5e-8 s at 16 s, against a rounding error of at most a few ulps of the
+ * clock (3.6e-15 s at 16 s) — so every tie resolves the way exact arithmetic
+ * resolves it, a step taken, and the shown weight sits at 1 − 9e-7 rather
+ * than flipping. It stays below the smallest gap a step boundary can fall
+ * into for 7.8e5 s even at 23 fps against 60 Hz (a gap of 1/1380 s), and a
+ * physics `reset` key, which restarts the time left from zero, is resolved
+ * the same way on every frame after it, because the lead is taken on every
+ * frame rather than once (read off the clock arithmetic with a reset at frame
+ * 100, 16 s at the five rates: no tie; no tree probe keys a reset under the
+ * render's clock). A pose stays a function of its frame
+ * index alone: the lead does not depend on how many frames are asked for.
+ *
+ * Rejected, measured over the same arithmetic (16 s at 12, 20, 24, 25, 30 and
+ * 60 fps): the clock as `i / fps` rather than a running sum (90 frames still
+ * flipped at 20 fps); a one-time lead of half a step (114 flipped at 24 fps,
+ * where half a step lands on the other tie); a one-time lead of any size,
+ * which a `reset` key cancels; and snapping `remaining` inside the physics,
+ * which changes the runtime's physics rather than the render's schedule and
+ * which spine-core's poser could not follow.
+ */
+export const PHYSICS_CLOCK_LEAD = 2 ** -30;
+
+/** What one frame of `step` seconds moves a render's physics clock by — `PHYSICS_CLOCK_LEAD`; both render posers and the mesh comparison step with it. */
+export function physicsClockStep(step: number): number {
+  return step + step * PHYSICS_CLOCK_LEAD;
+}
+
 /**
  * The animation time a looping track applies its animation at (`./walk.ts`,
  * *The time*): the track time wrapped by the duration, and 0 over a duration

package/src/folds.ts

@@ -170,6 +170,8 @@ export interface FoldPlant {
   boxWholeMesh?: boolean;
   /** Size the folded triangles by their unsigned area as posed at the frame, rather than at the setup pose. */
   areaPosed?: boolean;
+  /** Read degeneracy against this share of the largest coordinate rather than `DEGENERATE_SHARE` — 0 drops the line (issue #1390). */
+  degenerateShare?: number;
 }
 
 /** Twice the signed area of triangle `t` in `xy` (`x, y` per vertex). */
@@ -201,12 +203,13 @@ function magnitude(xy: readonly number[]): number {
 
 /**
  * The sign of triangle `t`'s area in `xy`: +1, −1, or 0 when it is degenerate
- * — its height over its longest edge at most `DEGENERATE_SHARE` of `scale`.
+ * — its height over its longest edge at most `share` (`DEGENERATE_SHARE`
+ * unplanted) of `scale`.
  */
-function orientation(xy: readonly number[], triangles: readonly number[], t: number, scale: number): -1 | 0 | 1 {
+function orientation(xy: readonly number[], triangles: readonly number[], t: number, scale: number, share: number): -1 | 0 | 1 {
   const twice = cross2(xy, triangles, t);
   const edge = longestEdge(xy, triangles, t);
-  if (edge === 0 || Math.abs(twice) / edge <= DEGENERATE_SHARE * scale) return 0;
+  if (edge === 0 || Math.abs(twice) / edge <= share * scale) return 0;
   return twice > 0 ? 1 : -1;
 }
 
@@ -220,6 +223,7 @@ export interface SetupReading {
 /** The setup reading of one mesh — see the module comment for what degenerate and inverted mean. */
 export function setupReading(rest: FoldRest, plant: FoldPlant = {}): SetupReading {
   const count = Math.floor(rest.triangles.length / 3);
+  const share = plant.degenerateShare ?? DEGENERATE_SHARE;
   const signs = new Int8Array(count);
   const world: number[] = [];
   const uvSigns: number[] = [];
@@ -229,8 +233,8 @@ export function setupReading(rest: FoldRest, plant: FoldPlant = {}): SetupReadin
   let sense = 0;
   const degenerate: number[] = [];
   for (let t = 0; t < count; t++) {
-    const w = orientation(rest.vertices, rest.triangles, t, worldScale);
-    const u = uvs.length === rest.vertices.length ? orientation(uvs, rest.triangles, t, uvScale) : 1;
+    const w = orientation(rest.vertices, rest.triangles, t, worldScale, share);
+    const u = uvs.length === rest.vertices.length ? orientation(uvs, rest.triangles, t, uvScale, share) : 1;
     world.push(w);
     uvSigns.push(u);
     if (w === 0 || u === 0) {
@@ -263,11 +267,12 @@ export function foldedAt(rest: FoldRest, setup: SetupReading, vertices: readonly
     );
   }
   const scale = magnitude(vertices);
+  const share = plant.degenerateShare ?? DEGENERATE_SHARE;
   const out: number[] = [];
   for (let t = 0; t < setup.signs.length; t++) {
     const before = setup.signs[t];
     if (before === 0) continue;
-    const now = orientation(vertices, rest.triangles, t, scale);
+    const now = orientation(vertices, rest.triangles, t, scale, share);
     if (now === 0) continue;
     if (plant.signFlipped ? now === before : now === -before) out.push(t);
   }

package/src/meshcompare.ts

@@ -66,7 +66,11 @@
  *   on every walk and stepped at the declared `dt` to each frame (the oracle's
  *   `stepSchedule` rule: from the last frame, steps of `dt` while before the
  *   next, then to it), the same steps for the reference and every candidate. A
- *   nonzero `warmupSteps` is refused, never run as zero.
+ *   nonzero `warmupSteps` is refused, never run as zero. The physics clock
+ *   moves by `physicsClockStep` of each step, the render's clock
+ *   (`PHYSICS_CLOCK_LEAD` in `src/core/raw.ts`, issue #1380), so a step
+ *   lasting a whole number of a constraint's steps takes them as exact
+ *   arithmetic does (`comparisonWalk`, issue #1389).
  *
  * ## What it never does
  *
@@ -106,8 +110,8 @@ import {
 import { areaBand, stretchSingularValues, triangleAreas } from './areaband.ts';
 import { uvCarriers, uvCarriersWith, type Carrier, type CarrierPlant } from './meshcarriers.ts';
 import { CoreInputError, readModel, underNoSkin, underSkin, type CompiledDocument } from './core/index.ts';
-import { poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
-import { sampleTime } from './core/animation.ts';
+import { physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawPose } from './core/raw.ts';
+import { sampleTime, type TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN } from './core/skins.ts';
 import { readVersion } from './package_meta.ts';
 import { hypot2 } from './numeric.ts';
@@ -187,7 +191,9 @@ export interface MotionComparisonInput {
  * Issue #1291's faults in carrying `motionAmplitude` into the setup measurement, for the `mesh-compare` suite's
  * negative controls: the amplitude not handed over; `null` handed over as the field left out; the field not validated
  * before the builds are read; `null` echoed for a field left out; and the load counted as a required row, so the
- * amplitude moves a verdict. `compareMeshesInMotion` plants none. Issue #1323 adds `CarrierPlant`
+ * amplitude moves a verdict. `compareMeshesInMotion` plants none. Issue #1389 adds `'frame-physics-clock'`: every
+ * build posed with the physics clock moved by the schedule's step itself, the walk before that issue
+ * (`comparisonWalk`). Issue #1323 adds `CarrierPlant`
  * (`src/meshcarriers.ts`): a fault in resolving a sample's several carriers, planted in every `uvCarriers` the
  * comparison reads.
  */
@@ -197,6 +203,7 @@ export type ComparePlant =
   | 'amplitude-unvalidated'
   | 'echo-when-unset'
   | 'amplitude-gates-acceptance'
+  | 'frame-physics-clock'
   | OverBoundPlant
   | CarrierPlant;
 
@@ -594,7 +601,37 @@ function drawnOf(pose: RawPose, ref: AttachmentRef): number[] | null {
   return row === undefined ? null : row.vertices;
 }
 
-function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames: readonly Planned[], walks: readonly Walk[]): Posed | { refused: string } {
+/**
+ * The walk every build of a comparison is posed on (issue #1389): `poseRawAnimationEach`, reset at the animation, the
+ * physics clock moved by `physicsClockStep` of each step — the render's clock (`src/core/raw.ts`). A walk time that
+ * ends on a whole number of a physics constraint's steps leaves zero time over in exact arithmetic and a few ulps
+ * either side of zero in doubles, so with the step itself as the clock the constraint took one step too few or one
+ * too many by rounding. Measured over the clock arithmetic on 300 durations as the core reads them (float32, as Spine
+ * does: n/12 s to 20 s and tenths to 8 s): at 12 fps and `dt` 1/12, the rate `@rig-c/parts` walks, 11,248 of 44,486
+ * grid updates sit on a tie against a 60 Hz constraint and the frame clock happens to resolve every one as exact
+ * arithmetic does, while against 30, 24 and 50 Hz it mis-steps 3,274, 3,350 and 3,160 of them; at 4 fps and `dt` 1/60
+ * it mis-steps 19,876 grid and 594 irr updates against 60 Hz. The render's clock mis-steps none of any, so no time
+ * that is not a tie came within its lead of a whole step. `clock: 'frame'` is that walk, the step itself — `ComparePlant`
+ * `'frame-physics-clock'` and `MQ178`'s planted red. With no physics constraint the clock is read by nothing, so every
+ * pose is the same either way (`MQ179`); with one, the lead moves the shown lag weight by about `2⁻³⁰` of the time
+ * walked even where no step moves: on `MQ179`'s spring at parts' rate and 60 Hz, one unit of a row's sixth decimal,
+ * which can move the worst sample to a neighbour that nearly ties it.
+ */
+export function comparisonWalk(doc: CompiledDocument, animation: string, deltas: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, clock: 'render' | 'frame' = 'render'): void {
+  poseRawAnimationEach(doc, animation, deltas, plant, 'animation', visit, clock === 'render' ? physicsClockStep : undefined);
+}
+
+/**
+ * The walks `schedule` plans over the model document `model`, in walk order, each with the steps every build is posed
+ * on — `planSchedule`'s, read for the `mesh-compare` suite's `MQ178`. Internal: merely exported, so not promised; it
+ * reads the schedule without the input checks `compareMeshesInMotion` runs first.
+ */
+export function comparisonWalks(schedule: MotionSchedule, model: string): Array<{ animation: string; phase: 'grid' | 'irr' | null; deltas: number[] }> {
+  const doc = readModel(model, 'the model document');
+  return planSchedule(schedule, doc, doc.constraints.filter((c) => c.kind === 'physics').length).walks.map((w) => ({ animation: w.animation, phase: w.phase, deltas: [...w.deltas] }));
+}
+
+function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames: readonly Planned[], walks: readonly Walk[], clock: 'render' | 'frame'): Posed | { refused: string } {
   try {
     const view = viewOf(doc, refs[0].skin);
     const setupPose = poseRawSetup(view);
@@ -612,12 +649,19 @@ function poseBuild(doc: CompiledDocument, refs: readonly AttachmentRef[], frames
         list.push(i);
         wanted.set(f.pose, list);
       });
-      poseRawAnimationEach(view, w.animation, w.deltas, {}, 'animation', (pose, index) => {
-        const at = wanted.get(index);
-        if (at === undefined) return;
-        const drawn = refs.map((r) => drawnOf(pose, r));
-        for (const i of at) out[i] = drawn;
-      });
+      comparisonWalk(
+        view,
+        w.animation,
+        w.deltas,
+        {},
+        (pose, index) => {
+          const at = wanted.get(index);
+          if (at === undefined) return;
+          const drawn = refs.map((r) => drawnOf(pose, r));
+          for (const i of at) out[i] = drawn;
+        },
+        clock,
+      );
     });
     return { setup, frames: out, setupBones };
   } catch (err) {
@@ -1003,11 +1047,12 @@ function compareMeshesInMotionWith(input: MotionComparisonInput, plant: CompareP
     const carriersOf = (uvs: readonly number[], triangles: readonly number[], samples: ReadonlyArray<{ uv: [number, number] }>, who: string): Array<Carrier | null> =>
       uvCarriersWith(uvs, triangles, samples, who, carrierPlant);
     const refCarriers = order.map((i, k) => carriersOf(reference.meshes[i].uvs, reference.meshes[i].triangles, samplesOf[k].samples, `reference "${reference.id}", attachment ${nameOf(refs[i])}`));
-    const posedRef = poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks);
+    const clock = plant === 'frame-physics-clock' ? 'frame' : 'render';
+    const posedRef = poseBuild(reference.doc, order.map((i) => refs[i]), frames, walks, clock);
 
     motionOf = (b: Build, isReference: boolean) => {
       const carriers = isReference ? refCarriers : order.map((i, k) => carriersOf(b.meshes[i].uvs, b.meshes[i].triangles, samplesOf[k].samples, `candidate "${b.id}", attachment ${nameOf(refs[i])}`));
-      const posed = isReference ? posedRef : poseBuild(b.doc, order.map((i) => refs[i]), frames, walks);
+      const posed = isReference ? posedRef : poseBuild(b.doc, order.map((i) => refs[i]), frames, walks, clock);
       const built: Built[] = [];
       const perFrame: NonNullable<CandidateReport['perFrame']> = [];
       // Issue #1315: kept for a candidate only, and only when asked — a call without the field does none of this.

package/src/render_core.ts

@@ -30,7 +30,7 @@
  *   the same walk handing each pose over as it is posed (`CORE_RAW_WALK`), so
  *   one pose is held at a time. Since issue #1380 the physics clock — and
  *   nothing else — moves by `physicsClockStep(1/fps)` rather than by the step
- *   (`PHYSICS_CLOCK_LEAD` below), in both posers: `CR03` still holds the walk
+ *   (`PHYSICS_CLOCK_LEAD`, `./core/raw.ts`), in both posers: `CR03` still holds the walk
  *   under the step itself, and the loop-seam suite's `LS06` holds the two
  *   posers equal under the render's clock.
  * - **Vertices, triangles, bones, slot colours, draw order** are the raw
@@ -100,7 +100,7 @@ import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
@@ -369,61 +369,10 @@ export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: read
 export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep);
 
 /**
- * How much faster than the frames a render's physics clock runs: each frame
- * moves the skeleton's clock — the time a physics constraint integrates — by
- * `physicsClockStep(1 / fps)`, the frame's step and `2⁻³⁰` of it more, while
- * the animation is applied at the running sum of the frame steps as before
- * (issue #1380).
- *
- * ⭐ **Why a render's physics clock is not the frame clock.** A physics
- * constraint keeps the time it has not yet integrated (`remaining`), takes
- * whole steps of `1 / fps` (its own `fps`, 60 by default) while at least one
- * step remains, and shows `offset − lag·(1 − remaining / step)`, `lag` being
- * everything this update's steps moved (`src/core/constraints_physics.ts`,
- * *The step*). Whenever a frame lasts a whole number of physics steps — 12,
- * 20, 30 and 60 fps against 60 Hz, and every second frame at 24 — the time
- * left at the frame's end is zero in exact arithmetic, and in doubles it is
- * either a few ulps above zero or a few ulps short of one whole step. Which of
- * the two is decided by rounding, not by the motion: the shown weight is 1 or
- * 0, so the spring is drawn one frame late or on time, and it changes regime
- * on a single frame. Measured on the public trailer (`show`, 20 fps, 321
- * frames): every spring jumps at frames 5, 12, 45 and 188 — the four frames
- * that arithmetic alone predicts — and the loop's start (frame 80, on time)
- * and end (frame 320, a frame late, which is what exact arithmetic draws)
- * differ by 31.70 units of vertex and 10.37 of bone
- * while every keyed bone agrees to 1.3e-12. spine-core 4.3.13 stepped the
- * same way draws the same frames to the bit: this is the runtime under a
- * fixed offline step, not a defect of the core's port, which is why the fix
- * is the render's schedule and the physics is untouched.
- *
- * Running the clock `2⁻³⁰` fast puts the time left a little ABOVE every
- * whole number of steps instead of on it, by `2⁻³⁰ · t` after `t` seconds:
- * 1.5e-8 s at 16 s, against a rounding error of at most a few ulps of the
- * clock (3.6e-15 s at 16 s) — so every tie resolves the way exact arithmetic
- * resolves it, a step taken, and the shown weight sits at 1 − 9e-7 rather
- * than flipping. It stays below the smallest gap a step boundary can fall
- * into for 7.8e5 s even at 23 fps against 60 Hz (a gap of 1/1380 s), and a
- * physics `reset` key, which restarts the time left from zero, is resolved
- * the same way on every frame after it, because the lead is taken on every
- * frame rather than once (read off the clock arithmetic with a reset at frame
- * 100, 16 s at the five rates: no tie; no tree probe keys a reset under the
- * render's clock). A pose stays a function of its frame
- * index alone: the lead does not depend on how many frames are asked for.
- *
- * Rejected, measured over the same arithmetic (16 s at 12, 20, 24, 25, 30 and
- * 60 fps): the clock as `i / fps` rather than a running sum (90 frames still
- * flipped at 20 fps); a one-time lead of half a step (114 flipped at 24 fps,
- * where half a step lands on the other tie); a one-time lead of any size,
- * which a `reset` key cancels; and snapping `remaining` inside the physics,
- * which changes the runtime's physics rather than the render's schedule and
- * which spine-core's poser could not follow.
+ * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
+ * comparison (`./meshcompare.ts`, issue #1389) reads the same clock without this module's closure.
  */
-export const PHYSICS_CLOCK_LEAD = 2 ** -30;
-
-/** What one frame of `step` seconds moves a render's physics clock by — `PHYSICS_CLOCK_LEAD`; both posers step with it. */
-export function physicsClockStep(step: number): number {
-  return step + step * PHYSICS_CLOCK_LEAD;
-}
+export { PHYSICS_CLOCK_LEAD, physicsClockStep };
 
 /** What a suite passes `corePoser` in place of the poser's own parts — `PieceArrays` (`RC43`) and the raw walk (`RC44`). */
 export interface CorePoserPlants {