spine-rigc 0.25.2 → 0.25.4

package/src/compile.ts

@@ -761,6 +761,20 @@ interface ValueTrackShape {
  * The defaults matter more than they look: Spine omits a field that equals the
  * setup value, and `scale` defaults to 1 while `translate` defaults to 0. Emit
  * `x: 0` on a scale key and the bone collapses to nothing, silently.
+ *
+ * ⭐ **The table IS the dispatch**, the same way `SLOT_TRACKS` is: `resolveTargets`
+ * asks `property in BONE_TRACKS` to decide the family, `compileValueTrack` writes
+ * a key out of the shape it finds here, and the refusal for a property that is not
+ * in it prints `Object.keys` of the same object — so the ten an author is handed
+ * cannot disagree with the ten the emitter has, because there is only one list.
+ *
+ * 🚨 It printed nothing until issue #656. The dispatch was already this table, but
+ * a bone track whose property missed it was refused as *"bone X cannot take slot
+ * property Y"* — the wrong family for a spelling that usually belongs to none, and
+ * the one target family whose refusal offered no way forward. That is also why the
+ * selftest's spelling census had to STATE these ten (`PS143`, `PS144`): four
+ * families printed their own vocabulary in their refusals and the bone family
+ * printed nothing, so there was nothing to read it off.
  */
 const BONE_TRACKS: Record<string, ValueTrackShape> = {
   translate: { fields: ['x', 'y'], identity: [0, 0] },
@@ -853,6 +867,38 @@ const SLIDER_TRACKS: Record<string, ValueTrackShape> = {
   mix: { fields: ['value'], identity: [1] },
 };
 
+/**
+ * Slot timelines (`animations.<a>.slots.<slot>.<timeline>`): the two
+ * `compileTrack` writes, and which key shape each one is written with.
+ *
+ * ⭐ **The table IS the dispatch.** `compileTrack` reads the shape out of here
+ * to pick its branch, and the refusal for a property that is not in it prints
+ * `Object.keys` of the same object — so the list an author is given cannot
+ * disagree with the list the emitter has, because there is only one.
+ *
+ * 🚨 It exists because the dispatch used to be one `if` on `attachment` and a
+ * fall-through to rgba, which made **every** other property name a legal
+ * spelling of an rgba timeline: `{"slot": "x", "property": "sequence", "v": [0,
+ * 0, 0, 0]}` compiled and wrote `slots.x.sequence` with rgba-shaped keys. The
+ * gate caught the file (`A00_ROUNDTRIP_PARSE: threw: Invalid timeline type for
+ * a slot`, and `A05_CURVE_ARRAY_LENGTH`) and the one-channel spelling of the
+ * same mistake was refused at compile as *"rgba value needs 4 channels, got
+ * 1"* — a message about a key nobody wrote. It is the shape `A21`'s
+ * `meshKinds[slot] || 'ring'` had (issue #44): a default that turns "nothing to
+ * emit" into an emission of the wrong thing (issue #650).
+ *
+ * ⚠️ The KEY is the timeline name as the file carries it, and the VALUE names
+ * the branch below that writes its keys — so an entry added here without a
+ * branch to write it is an entry emitted in some other timeline's shape, which
+ * is the defect this table closed rather than a new affordance. The format has
+ * four more (`rgb`, `alpha`, `rgba2`, `rgb2`); rigc emits none of them, and
+ * `A12_NO_DARK_COLOR` refuses the last two outright.
+ */
+export const SLOT_TRACKS: Record<string, 'attachment' | 'rgba'> = {
+  attachment: 'attachment',
+  rgba: 'rgba',
+};
+
 /**
  * The three constraint families a `MotionTrack` can target, and the table of
  * timelines each one accepts.
@@ -4686,6 +4732,42 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
         // time = to + (value - from) * 0, so the slider holds one frame forever.
         throw new CompileError(`${where}: scale is 0, so the bone's property cannot move the slider's time at all`);
       }
+      // The window of driving values that can reach a frame at all, and the two
+      // functions every figure in the two reader clauses below comes off.
+      //
+      // ⭐ **One copy, read by both readers** (issue #657). The circle owned
+      // this arithmetic while it was the only reader with a bound; the world
+      // `scale` readers have a floor at 0 and the same mapping carries them
+      // there, so the second clause reads these numbers instead of computing its
+      // own. That is the rule this clause has already paid for twice — #417
+      // tested one end because its fixture only left the circle at that end, and
+      // #431 wrapped by one subtraction because every fixture sat within a turn
+      // — and a second copy with a sign edited is exactly the shape both took.
+      const fromValue = spec.from === undefined ? 0 : needNumber(spec.from, 'from');
+      const toTime = spec.to === undefined ? 0 : needNumber(spec.to, 'to');
+      const perUnit = spec.scale === undefined ? 1 : needNumber(spec.scale, 'scale');
+      const duration = ctx.animationDurations.get(animation) ?? 0;
+      /** The driving value that maps to the animation's first frame, and to its last. */
+      const atStart = fromValue - toTime / perUnit;
+      const atEnd = fromValue + (duration - toTime) / perUnit;
+      const lowest = Math.min(atStart, atEnd);
+      const highest = Math.max(atStart, atEnd);
+      /**
+       * The time this mapping puts a driving value at, before the runtime
+       * touches it — the one arithmetic every figure below comes off.
+       *
+       * ⚠️ **Computed, not asserted** (issue #423). The circle's clause used to
+       * end *"— outside the animation's Ds. With `loop`: false that is
+       * `Math.max(0, time)` holding the last frame; with `loop`: true it wraps
+       * to some other frame"*, which states a consequence rather than measuring
+       * one — and is flatly false for a range spanning a full turn, where the
+       * wrapped reading lands INSIDE the animation. It also printed both loop
+       * modes and left the reader to pick. A message that hedges is a message
+       * that has not measured.
+       */
+      const timeAt = (value: number): number => toTime + (value - fromValue) * perUnit;
+      /** That time clamped into the animation — the frame a pose actually holds. */
+      const intoFrame = (time: number): number => Math.min(Math.max(time, 0), duration);
       // ⚠️ `local: false` reads the bone's WORLD rotation, and `FromRotate.value`
       // (`TransformConstraintData.js`) ends
       //
@@ -4741,15 +4823,6 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
       // or the whole turn 0°..360° — is how you write this axis under
       // `local: false` and it works.
       if (property === 'rotate' && spec.local !== true) {
-        const fromValue = spec.from === undefined ? 0 : needNumber(spec.from, 'from');
-        const toTime = spec.to === undefined ? 0 : needNumber(spec.to, 'to');
-        const perUnit = spec.scale === undefined ? 1 : needNumber(spec.scale, 'scale');
-        const duration = ctx.animationDurations.get(animation) ?? 0;
-        /** The driving value that maps to the animation's first frame, and to its last. */
-        const atStart = fromValue - toTime / perUnit;
-        const atEnd = fromValue + (duration - toTime) / perUnit;
-        const lowest = Math.min(atStart, atEnd);
-        const highest = Math.max(atStart, atEnd);
         // Which end of the circle the range leaves. One record, so the end, its
         // reading, the time it lands on and the two clauses that name the side
         // are derived once rather than twice.
@@ -4805,20 +4878,6 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
            * tracks the closed form to 3.3e-8s.
            */
           const readAs = ((dead.end % 360) + 360) % 360;
-          /**
-           * The time this mapping puts a driving value at, before the runtime
-           * touches it — the one arithmetic every figure below comes off.
-           *
-           * ⚠️ **Computed, not asserted** (issue #423). This clause used to end
-           * *"— outside the animation's Ds. With `loop`: false that is
-           * `Math.max(0, time)` holding the last frame; with `loop`: true it
-           * wraps to some other frame"*, which states a consequence rather than
-           * measuring one — and is flatly false for a range spanning a full
-           * turn, where the wrapped reading lands INSIDE the animation. It also
-           * printed both loop modes and left the reader to pick. A message that
-           * hedges is a message that has not measured.
-           */
-          const timeAt = (value: number): number => toTime + (value - fromValue) * perUnit;
           const lands = timeAt(readAs);
           // `[0, 360)` is the whole of what `FromRotate.value` returns (issue
           // #417), so the readings that reach the animation at all are that
@@ -4829,7 +4888,6 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
           const reachLo = Math.max(0, lowest);
           const reachHi = Math.min(360, highest);
           const reaches = reachLo <= reachHi;
-          const intoFrame = (time: number): number => Math.min(Math.max(time, 0), duration);
           const reachA = intoFrame(timeAt(reachLo));
           const reachB = intoFrame(timeAt(reachHi));
           const span = `${Math.min(reachA, reachB).toFixed(3)}s..${Math.max(reachA, reachB).toFixed(3)}s`;
@@ -4923,6 +4981,78 @@ function buildRigConstraint(spec: RigConstraintInput, ctx: ConstraintContext): S
           );
         }
       }
+      // ⚠️ `local: false` reads the bone's WORLD scale, and `FromScaleX.value`
+      // / `FromScaleY.value` (`TransformConstraintData.js`) are
+      //
+      //   const a = source.a / skeleton.scaleX, c = source.c / skeleton.scaleY;
+      //   return Math.sqrt(a * a + c * c) + offsets[TransformConstraintData.SCALEX];
+      //
+      // — a MAGNITUDE. The driven field is in both terms, so the reading is
+      // `|value|` and `[0, ∞)` is the whole of what that reader can return. The
+      // floor is REACHED rather than approached (a bone whose own scale, or
+      // whose parent's, is 0 reads exactly 0), which is why a range whose bottom
+      // is exactly 0 stays legal and only one that dips below it is refused.
+      //
+      // 🚨 **Below the floor the axis does not go dead, it FOLDS** (issue #657),
+      // and that is why this is a second clause rather than the circle with
+      // another property name in it. A reading the range cannot reach is one
+      // frame pinned; a reading it reaches TWICE is two dial positions posing
+      // the same face, so the message has to name the mirror rather than a dead
+      // arc. Measured through spine-core on `from: 0, to: 0.5, scale: 0.25` over
+      // a 1 s animation — driving window −2..+2 — the applied time at −2.000,
+      // −1.500, −1.000 and −0.500 is 1.000000s, 0.875000s, 0.750000s and
+      // 0.625000s: the same six decimals the dial at +2.000, +1.500, +1.000 and
+      // +0.500 applies, with the posed bone matching to the digit. The same rig
+      // read `local: true` sweeps −2 → +2 monotonically from 0.000000s, which is
+      // what makes that repair worth naming.
+      //
+      // ⭐ **No loop branch, and that is measured rather than economised.** The
+      // circle's consequence turns on `Slider.loop` because a held frame is held
+      // only under `Math.max(0, time)`; a fold is not a clamp, so `loop: true`
+      // cannot undo it — the same ±1.500 pair applies 1.875000s either way.
+      if ((property === 'scaleX' || property === 'scaleY') && spec.local !== true && lowest < -SLIDER_WRAP_SLACK) {
+        /** What the reader returns for a bone parked at the bottom of the range: the magnitude. */
+        const readAs = Math.abs(lowest);
+        const lands = timeAt(readAs);
+        // The readings that reach the animation are `[0, ∞)` met with the
+        // driving window — the circle's `reachLo`/`reachHi` with the ceiling
+        // taken out, off the same two numbers the message has already printed.
+        const reaches = highest >= 0;
+        /**
+         * How much of the range lies below the floor: the WIDTH of
+         * `[lowest, highest]` under 0, not the distance to its far end.
+         *
+         * 🚨 `-lowest` is that distance, and the two are equal only while the
+         * range STRADDLES the floor — the same trap issue #434 paid for one
+         * reader over, where a range lying wholly outside was told a width wider
+         * than itself. A `-6..-2` window is 4.000 below the floor and `-lowest`
+         * would print 6.000, which is `readAs` again with a different name on it.
+         */
+        const below = Math.min(0, highest) - lowest;
+        // The arc an author writes twice: the part of the range above 0 that the
+        // part below 0 mirrors onto. Both ends are inside `[lowest, highest]` —
+        // 0 because the range straddles it and this is the `reaches` branch, the
+        // top because it is `highest` or less — so both map INTO the animation
+        // and neither needs clamping.
+        const mirrorTop = Math.min(highest, -lowest);
+        const mirrorA = timeAt(0);
+        const mirrorB = timeAt(mirrorTop);
+        const consequence = reaches
+          ? `${below.toFixed(3)} of the range below 0 repeats 0.000..${mirrorTop.toFixed(3)}, which is ` +
+            `${Math.min(mirrorA, mirrorB).toFixed(3)}s..${Math.max(mirrorA, mirrorB).toFixed(3)}s of the animation, in reverse.`
+          : `the whole ${below.toFixed(3)} of this range is below 0, so it reaches none of the animation's ${duration}s — ` +
+            `every value the reader can return maps past it and the pose holds the frame at ${intoFrame(timeAt(0)).toFixed(3)}s.`;
+        throw new CompileError(
+          `${where}: drives off bone "${String(spec.bone)}" ${property} with "local": false, and the driving values ` +
+            `that reach animation "${animation}" (0s..${duration}s) run from ${lowest.toFixed(3)} to ${highest.toFixed(3)}. ` +
+            `A world scale is read through \`From${property === 'scaleX' ? 'ScaleX' : 'ScaleY'}.value\` as ` +
+            `\`Math.sqrt(${property === 'scaleX' ? 'a² + c²' : 'b² + d²'})\`, a magnitude, so the bone at ` +
+            `${lowest.toFixed(3)} is read as ${readAs.toFixed(3)} and maps to time ${lands.toFixed(3)}s — the time the ` +
+            `bone at ${readAs.toFixed(3)} maps to. Positions below 0 read as the mirror of positions above it: ` +
+            `${consequence} Nothing at runtime reports it. Add \`"local": true\` to read the bone's own scale signed and ` +
+            'unfolded — that is the form a squash axis wants — or move the range so it does not dip below 0.',
+        );
+      }
       for (const field of timeSide) {
         if (spec[field] !== undefined) {
           throw new CompileError(
@@ -6371,18 +6501,59 @@ function resolveTargets(track: MotionTrack, motion: MotionSpec, animName: string
     throw new CompileError(`animation "${animName}": "${track.property}" is a bone track but no bone is named`);
   }
   if (!isBoneTrack && track.bone) {
-    throw new CompileError(`animation "${animName}": bone "${track.bone}" cannot take slot property "${track.property}"`);
+    // The bone family's sibling of `compileTrack`'s slot refusal, raised here for
+    // the same reason it is raised there: before any key is shaped, and printed
+    // from the dispatch table itself. What it replaces named the SLOT family for
+    // a property that is usually in no family at all, and enumerated nothing
+    // (issue #656). The tail clause is the one case where the old sentence was
+    // true — `rgba` and `attachment` really are slot timelines — so the redirect
+    // survives as a clause instead of as the whole message, and it is read off
+    // `SLOT_TRACKS` rather than spelled again. A constraint property never
+    // reaches here: `owning` above refuses it with the field that carries it.
+    throw new CompileError(
+      `animation "${animName}" bone "${track.bone}" has no timeline "${track.property}" ` +
+        `(it has: ${Object.keys(BONE_TRACKS).join(', ')})` +
+        (track.property in SLOT_TRACKS ? `. "${track.property}" is a slot timeline — put the name in "slot"` : ''),
+    );
   }
   if (track.bone) return [track.bone];
   if (track.slot) return [track.slot];
   if (track.group) {
-    // A group's members are bones or slots depending on the property, which is
-    // what lets `stagger` express the ring lag: four grips, one track, a few
-    // frames apart. Plan 02 section 4-2 calls that lag the real detail of the
-    // stroke, and it is the difference between a ring following the part and two
-    // objects moving together (which reads as a composite).
+    // A group's members are bones, slots or physics constraints depending on the
+    // property, which is what lets `stagger` express a lag across them: four
+    // members, one track, a few frames apart — the difference between a ring
+    // following the part and two objects moving together, which reads as a
+    // composite.
     const members = motion.groups?.[track.group];
     if (!members) throw new CompileError(`animation "${animName}": unknown group "${track.group}"`);
+    // 🚨 The group is the one target shape whose FAMILY is decided by the
+    // property, and three tables decide it: `constraintFamilyOf` asks
+    // `property in PHYSICS_TRACKS`, this function asks `property in BONE_TRACKS`,
+    // and what neither claims falls through to the slot branch. So a property in
+    // no table left the dispatch with no family at all and the track was read as
+    // a slot track — the first member was then refused for not being a slot
+    // (`animation "A" targets unknown slot "rim_grip_a"` on a group of bones and
+    // a misspelled bone property), or, when the members really were slots, with
+    // the slot table alone on a family nothing had determined (issue #661).
+    //
+    // Raised AFTER the group's own existence check, because "group G has no
+    // timeline P" would otherwise assert a group the file does not declare, and
+    // BEFORE the members are resolved against the rig or any key is shaped: the
+    // property is what the dispatch reads first, so it is what the refusal is
+    // about. All three lists come from the objects the dispatch reads, so none
+    // of them can drift from the emitter that owns it. A property that IS in
+    // `PHYSICS_TRACKS` never reaches this line — `constraintFamilyOf` returns
+    // `physics` for a group track that names one, and the family branch above
+    // has already returned — and a path or slider property is refused further up
+    // with the field its constraint's name goes in.
+    if (!(track.property in BONE_TRACKS) && !(track.property in SLOT_TRACKS)) {
+      throw new CompileError(
+        `animation "${animName}" group "${track.group}" has no timeline "${track.property}" ` +
+          `(a bone group has: ${Object.keys(BONE_TRACKS).join(', ')}; ` +
+          `a slot group has: ${Object.keys(SLOT_TRACKS).join(', ')}; ` +
+          `a ${CONSTRAINT_TRACK_FAMILIES.physics.label} group has: ${Object.keys(PHYSICS_TRACKS).join(', ')})`,
+      );
+    }
     return members;
   }
   throw new CompileError(`animation "${animName}": a track targets neither slot nor group`);
@@ -6601,6 +6772,16 @@ function compileTrack(
   skinAttachments: Record<string, Record<string, SpineAttachment>>,
 ): SpineTimelineKey[] {
   const where = `animation "${animName}" slot "${target}" ${track.property}`;
+  // Before any key is shaped, and before the empty-track refusal: a property
+  // the emitter has no branch for is the fault, and a track that names one has
+  // no shape to be missing keys from (issue #650).
+  const shape = SLOT_TRACKS[track.property];
+  if (shape === undefined) {
+    throw new CompileError(
+      `animation "${animName}" slot "${target}" has no timeline "${track.property}" ` +
+        `(it has: ${Object.keys(SLOT_TRACKS).join(', ')})`,
+    );
+  }
   if (!track.keys.length) throw new CompileError(`${where}: no keys`);
 
   const out: SpineTimelineKey[] = [];
@@ -6613,7 +6794,7 @@ function compileTrack(
     }
     checkKeyTime(where, time, key.t, duration);
 
-    if (track.property === 'attachment') {
+    if (shape === 'attachment') {
       if (key.v !== null && typeof key.v !== 'string') {
         throw new CompileError(`${where}: attachment key value must be a string or null`);
       }
@@ -6626,7 +6807,8 @@ function compileTrack(
       continue;
     }
 
-    // rgba
+    // rgba — the other shape `SLOT_TRACKS` names, and now the only way to reach
+    // this branch: a property the table does not carry was refused above.
     if (!Array.isArray(key.v)) throw new CompileError(`${where}: rgba key value must be [r,g,b,a]`);
     const entry: SpineTimelineKey = { time, color: rgbaHex(key.v) };
     if (key.ease !== undefined && key.curve !== undefined) {

package/src/ingest.ts

@@ -44,7 +44,7 @@
  * break `A18_DETERMINISTIC_EMIT` the first time anybody rebuilt from an ingested
  * spec.
  */
-import { SPINE_VERSION } from './compile.ts';
+import { SLOT_TRACKS as EMITTED_SLOT_TRACKS, SPINE_VERSION } from './compile.ts';
 import { MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
 import { parseRigSpec, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
 import type { MotionSpec } from './types.ts';
@@ -347,8 +347,18 @@ const HEADER_REDERIVED = ['spine'];
 /** The attachment types this module inverts. Everything else is refused by name. */
 const ATTACHMENT_TYPES = ['region', 'mesh', 'boundingbox', 'clipping', 'path'];
 
-/** The two slot timelines the motion spec carries (`compileTrack`'s two branches). */
-const SLOT_TRACKS = ['rgba', 'attachment'];
+/**
+ * The slot timelines the motion spec carries — `compileTrack`'s own table,
+ * rather than a second list of the same two names.
+ *
+ * ⚠️ It was that second list until issue #650, spelled `['rgba', 'attachment']`
+ * with a comment saying where it had been copied from. The copy was true, which
+ * is the point: the emitter had no list at all — one `if` and a fall-through —
+ * so this module's blocker was the only place in `src/` that said what a slot
+ * track may be, and it said it about a compiler that accepted anything. Now
+ * there is one list and both sides read it.
+ */
+const SLOT_TRACKS = Object.keys(EMITTED_SLOT_TRACKS);
 
 /**
  * Everything this module has a branch for, as the branches themselves state it.