spine-rigc 0.25.2 → 0.25.3

package/docs/AUTHORING.md

@@ -2006,13 +2006,27 @@ it, on every frame, with the gate green — the second reason to write
 later one. `PS130` in `selftest.ts` poses both models rather than quoting the
 runtime, and [`docs/FACE.md`](FACE.md) §8 is the same rule on a face's two axes.
 
-⚠️ **And `"additive": true` is not always available.** Only some timelines support
-additive application at all: bone, deform, transform-constraint, path `position`,
-physics `wind`/`gravity`, and a slider's own `mix`. A **slot colour, an attachment
-swap, a draw order or a sequence ignores the flag entirely**, so two sliders
-sharing one of those overwrite each other whatever you write. A40 names that case
-separately, because the fix is different: key such a property from one slider
-only, or move both edits into the single animation one slider applies.
+⚠️ **And `"additive": true` is not always available.** The list that supports
+additive application at all is the closed one: bone, deform, transform-constraint,
+path `position`, physics `wind`/`gravity`, and a slider's own `mix`. **Everything
+else ignores the flag** — a slot colour, an attachment swap, a draw order and a
+sequence, and also an **ik constraint's mix**, a path's `spacing`, and every
+physics timeline except those two — so two sliders sharing one of those overwrite
+each other whatever you write. ⚠️ The four spelled out here used to read as the
+whole of the complement and they are examples of it; `A40` was never reading a
+list, it reads the runtime's own `Timeline.additive`, which is why it refuses the
+ik case this sentence did not name.
+
+⇒ **And "overwrite each other" has a direction, measured**: the slider **later in
+the `constraints` array** puts its own animation's value there and the earlier one
+contributes nothing at all, at every reading of either dial, with both flags set
+to `true`. Swap the two array entries and the answer swaps with them — it is the
+array that decides, not the flags and not which animation the file names first
+(`PS135` in `selftest.ts` poses four such targets both ways; `PS136` poses the
+three that do compose, and they are the same sum §3.5.2 states, over each target's
+own setup value). A40 names this case separately, because the fix is different:
+key such a property from one slider only, or move both edits into the single
+animation one slider applies.
 
 #### 3.5.2.1 What each `property` can actually be read AS
 
@@ -2424,6 +2438,33 @@ a deform). Folding them in would make `v` mean four different things depending o
 Translate values are **relative to the bone's setup position**; scale values are
 multipliers where `1` is setup; rotation is in degrees.
 
+⚠️ **A `slot` track's `property` is one of the two above, and anything else is a
+compile error** — `animation "A" slot "X" has no timeline "P" (it has:
+attachment, rgba)`, §5.1's row. Until
+[#650](https://github.com/firejune/rigc/issues/650) it was not: the emitter had a
+branch for `attachment` and wrote **everything else** as an rgba timeline under
+the name you gave it, so a track spelled `sequence` compiled, emitted
+`slots.X.sequence` with rgba keys, and was refused one stage later by the gate
+(`A00_ROUNDTRIP_PARSE: threw: Invalid timeline type for a slot`) — while 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 you had not written.
+
+- The pair is the emitter's own dispatch table (`SLOT_TRACKS` in
+  `src/compile.ts`): `compileTrack` reads it to pick its branch, and the refusal
+  prints `Object.keys` of the same object, so what you are told a slot accepts
+  is what it accepts.
+- **Nothing derives this page's copy of that pair from the table**, and the list
+  is two names long: no `DQ*`/`RD*`/`CUR*` control reads §4.4 (the only gated
+  table on this page is §3.5.2.1's, held by `RD01`–`RD06`). What keeps the two
+  in step is the control that quotes the message — `RF23` in `selftest.ts` —
+  which goes red if the accepted pair ever widens without this page moving with
+  it.
+- The format has four more slot timelines (`rgb`, `alpha`, `rgba2`, `rgb2`) and
+  rigc emits none of them, so their names are refused here too; `A12_NO_DARK_COLOR`
+  refuses the last two in a file rigc did not write (SPEC_COVERAGE §2.1).
+  `sequence` is a timeline on an **attachment**, not on a slot, and rigc does
+  not emit that either.
+
 **A physics constraint's six tuning timelines override §4.6's table for the
 length of an animation.** `{ "physics": "hair", "property": "wind", "keys": […] }`
 is a wind that rises and falls; `damping` is how fast the jiggle settles,
@@ -4004,6 +4045,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `skin "S": uses the long form … and also has a key "X"` | §3.4.1 — move the slot inside `attachments` |
 | `animation "A" keys "X" as a path constraint, but the rig declares it as a "slider"` | §4.12 — a timeline group resolves by name AND type; use the field named after the constraint's own type |
 | `animation "A": "position" is a path constraint timeline, and this track names no constraint` | §4.12 — put the name in `"path"` |
+| `rgba value needs 4 channels, got 3` | §4.4 — an `rgba` key is `[r, g, b, a]`. It names no animation, slot or key time, and the only input that reaches it is a slot `rgba` key: the setup pose's `color` is refused earlier, by its own row, with the slot named |
+| `animation "A" slot "X" has no timeline "P" (it has: attachment, rgba)` | §4.4 — a slot has exactly two timelines and `P` is neither. Fix the spelling; a bone or constraint property written on a slot track is refused by its own row instead. Before [#650](https://github.com/firejune/rigc/issues/650) every other name compiled as an **rgba** timeline called `P`, and what you saw was `A00_ROUNDTRIP_PARSE` on the emitted file — or, for the one-channel spelling, `rgba value needs 4 channels, got 1` |
 | `N pair(s) of animation names have no one order: … "turn" / "Turn" (case) — they are one name in two cases, and which of them the editor puts first is not measured; rename one of them so they differ by more than letter case` | **R10** — rename until no pair is left. The kind in brackets says which of the editor comparator's four UNMEASURED choices decides the pair: `case` (a pure case tie), `number` (one number written two ways, or a run of digits against a word) or `separator` (make the first character that differs a letter or a digit). rigc keys `animations` in the editor's own comparator — natural and case-insensitive ([#539](https://github.com/firejune/rigc/issues/539), [#543](https://github.com/firejune/rigc/issues/543)) — so a pair that comparator settles is emitted rather than refused, and only the four choices nobody has measured are a compile error; on those, the editor's re-key repoints every slider whose animation moves index ([#535](https://github.com/firejune/rigc/issues/535)) |
 | `N pair(s) of skin names have no one order: … "Zulu" / "mike" (case) — folded to one case "Zulu" and "mike" order the other way round, so whether the editor folds SKIN names decides this pair` | **R11** — rename until no pair is left. The same shape as the row above with a **wider** family: #539 measured the editor's comparator for animation names and thereby ruled codepoint out, and nothing has ruled anything out for skin names, so a pair the candidates could disagree about is refused even where the animation rule would emit it. `Zulu`/`mike` and `mike10`/`mike2` build as animation names and are refused as skin names ([#541](https://github.com/firejune/rigc/issues/541)) |
 | `slot "patch": placeholder "patch" is filled by the "default" skin AND by skins "zulu", "mike", and the Spine editor has no way to hold that … Move the default skin's entry for this slot into a named skin — call it "base"` | **R12** — do what it says: move that entry out of `default` into a named skin. The editor has no representation for a placeholder the default skin shares with a named one, in either spelling, and §3.4.2 has both measurements. Renaming the placeholder does not help; the shape is what is refused |

package/docs/FACE.md

@@ -1205,6 +1205,43 @@ green. ⇒ write `"additive": true` on **every** slider that shares a target and
 not only on the later one, which is what the paragraph above already asks for and
 this is the second reason for.
 
+🚨 **A second dial on a slot colour, an attachment swap or a draw order is not a
+second dial at all.** Those timelines ignore `additive`, so the flag is not the
+repair and writing it on both changes nothing: the slider **later in the
+`constraints` array** owns that property outright and the earlier one contributes
+nothing, at every position of its dial. An **ik constraint's mix** behaves the
+same way. What does compose is the rest of what a face keys — a bone transform, a
+mesh deform, a transform constraint's mix, a physics `wind` — and those are the
+same sum as the two axes above, over each target's own setup value. ⇒ if a blink
+fades a slot and the yaw dial also fades it, one of the two has to stop: key that
+property from **one** slider, or move both edits into the animation a single
+slider applies. `A40` refuses the rest by name, and AUTHORING §3.5.2 is the
+mechanism.
+
+⭐ **Three dials are the same sum as two — as long as every one of them is
+additive.** The case worth knowing is a non-additive dial in the *middle* of
+three, because it is neither of the two failures you would expect: it erases every
+dial **before** it and is then added to by every dial **after** it, so the face is
+neither the sum nor the last dial alone, and no reading of a two-dial rig has that
+shape.
+
+⚠️ **`"loop": true` puts the animation's FIRST frame at the top of the dial.** A
+looping slider wraps its time as a positive modulo rather than holding the last
+frame, so the axis is a sawtooth: the two ends of the range are the same pose and
+every position past the top repeats the range from its bottom. That is right for a
+parameter that genuinely cycles — a wheel, a breath — and wrong for a yaw, where
+the range's top has to *stay* at the extreme of the turn. Leave `loop` off for a
+face axis; the default is the one you want.
+
+🔸 **And a `local: false` dial never reads back the number you set.** The world
+reader goes through the bone's matrix, where the reference runtime's float32 π
+leaves a fraction of a degree behind, and it has a period: a bone one whole turn
+from its position reads *identically*, so the dial cannot tell the two apart. The
+composition is unchanged — two world dials add exactly as two local ones do — but
+`local: true` is what makes the number on the dial the number the rig reads, which
+is the same repair §3.5.2's circle already asks for. Every one of the six
+`property` readings composes by that one arithmetic under `local: true`.
+
 ✅ **The editor half, measured.** This paragraph said *unknown* until the round
 trip was taken with `tools/editor_roundtrip.ts` on a licensed editor (data
 version 4.3.26) against a 4.3.13 build of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/compile.ts

@@ -853,6 +853,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.
@@ -6601,6 +6633,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 +6655,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 +6668,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.