@rig-c/core 2.64.3 → 2.65.0

package/README.md

@@ -26,7 +26,7 @@ published beside it with the same files at every version.
 
 <p align="center"><em>Fourteen part PNGs drawn from scratch for this repo, one rig spec, one motion spec — the assembly,
 the breathing and the wave are all rigc-compiled Spine animations, rendered with
-<code>rigc render</code>.</em></p>
+<code>rigc render</code>. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-demo@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 Loose part PNGs and two small JSON files in; **Spine 4.3 skeleton data out** — a
 `skeleton.json` and a `skeleton.atlas` that load in any Spine runtime and **import
@@ -526,7 +526,7 @@ a rig compiles green, because green says nothing at all about the picture.
 conditions, <code>rigc pose</code> reads where every part sits in each picture, two
 candidate in-betweenings are compiled from the same pair — and a real
 <code>rigc vote</code> ballot picks the winner, because the movement between the poses
-is the one thing no instrument here will grade.</em></p>
+is the one thing no instrument here will grade. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-keypose@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 Three properties of `vote` are worth stating, because they are what make its ledger
 usable by the next agent rather than by a reader: **a tie is a recorded outcome, not a
@@ -580,7 +580,7 @@ while <code>gaze</code> and <code>turn</code> return to rest, so the hand-offs m
 differing pixels — and the composing is the consumer's. Authorable on plain Spine 4.3, no
 plugin, no runtime patch; what the turn costs is authoring rather than runtime capability,
 and that cost is one stated expression per key. Compiled and rendered entirely by the
-published package.</em></p>
+published package. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-scene@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 🎞️ **How the three films on this page were made** is kept with them, one directory per
 film in [`films/`](https://github.com/rig-c/core/tree/main/films) — a `run.sh` that

package/docs/AUTHORING.md

@@ -4993,6 +4993,14 @@ consumer's, decided by dressing the skeleton rather than by the animation.
   Seconds, not frames: nothing requires a key to land on any frame grid, and a
   reference rendered at some rate says nothing about where its keys are. Put keys
   where the motion changes.
+  ⚠️ **A phrase generated cycle by cycle ends one key before its period.** Write
+  each cycle of a 1 s phrase as t = 0…1 and the closing key of one cycle lands on
+  the opening key of the next, so the track is refused at the first boundary; the
+  refusal names both keys and, when the keys after the pair repeat the spacing of
+  the keys before it, says so. Generate each cycle without its closing key and
+  keep that key on the last cycle only: a looping player takes `time % duration`
+  and nothing interpolates across the wrap, so a track that stops short of its
+  period holds its last key until it (issue #1506).
 - **Key times are emitted as float32s like every other number, and never stored
   LATER than you wrote them.** Every emitted number is the shortest decimal naming
   its float32 — the text the editor writes, and the precision the runtime keeps,
@@ -7213,7 +7221,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_CURVE_VALUE_NONFINITE"></a>`CE_COMPILE_CURVE_VALUE_NONFINITE` | “&lt;value&gt; (t=&lt;value&gt;): raw curve holds a non-finite value &lt;value&gt;” | Supply finite numbers in the raw curve array. |
 | <a id="CE_COMPILE_VALUE_TIMELINE_PROPERTY_UNKNOWN"></a>`CE_COMPILE_VALUE_TIMELINE_PROPERTY_UNKNOWN` | “animation "&lt;value&gt;": &lt;value&gt; "&lt;value&gt;" has no property "&lt;value&gt;"” | Use a property present on the named target's timeline family. |
 | <a id="CE_COMPILE_TIMELINE_KEYS_EMPTY"></a>`CE_COMPILE_TIMELINE_KEYS_EMPTY` | “&lt;value&gt;: no keys”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" events”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Supply at least one key in the timeline. |
-| <a id="CE_COMPILE_KEY_TIMES_NOT_INCREASING"></a>`CE_COMPILE_KEY_TIMES_NOT_INCREASING` | “&lt;value&gt;: key times must strictly increase (at t=&lt;value&gt;)”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Order keys by strictly increasing time. |
+| <a id="CE_COMPILE_KEY_TIMES_NOT_INCREASING"></a>`CE_COMPILE_KEY_TIMES_NOT_INCREASING` | “&lt;value&gt;: key times must strictly increase — key &lt;value&gt; at t=&lt;value&gt; does not come after key &lt;value&gt; at t=&lt;value&gt; (keys counted from 0)”, and when the two keys share a time and the keys after them repeat the spacing of the keys before them: “. The keys from t=&lt;value&gt; repeat every &lt;value&gt;s, so key &lt;value&gt; closes one cycle and key &lt;value&gt; opens the next at the same time: a phrase that repeats every &lt;value&gt;s ends one key before its period. Generate each cycle without its closing key and keep that key on the last cycle only — a looping player wraps from it to t=0, and a track that stops short holds its last key until the wrap”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Order keys by strictly increasing time; the message names both keys of the pair. A phrase generated cycle by cycle with each cycle written from its start to its end repeats every boundary key — drop each cycle's closing key and keep it on the last cycle only (§4.5). |
 | <a id="CE_COMPILE_STEPPED_TIMELINE_EASING"></a>`CE_COMPILE_STEPPED_TIMELINE_EASING` | “&lt;value&gt; key at t=&lt;value&gt; carries [an easing ("&lt;value&gt;") / a curve], and this timeline is stepped by the format — its reader builds no curve, so the mode changes AT the key and holds until the next one. Remove it”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;” | Remove easing/curve from the stepped mode timeline. |
 | <a id="CE_COMPILE_TIMELINE_MODE_UNKNOWN"></a>`CE_COMPILE_TIMELINE_MODE_UNKNOWN` | “&lt;value&gt; key at t=&lt;value&gt; names mode &lt;value&gt;; &lt;value&gt;”<br>“known: &lt;value&gt; — the runtime folds the case of the first letter and of nothing else”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;”<br>“, ”<br>Here the values named in the message include: “noScaleOrReflection”, “normal”, “onlyTranslation”, “noRotationOrReflection”. | Use a mode named in the timeline's allowed mode list. |
 | <a id="CE_COMPILE_VALUELESS_TIMELINE_VALUE"></a>`CE_COMPILE_VALUELESS_TIMELINE_VALUE` | “&lt;value&gt;: this timeline takes no value; use null”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;” | Use null for a timeline that takes no value. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.64.3",
+  "version": "2.65.0",
   "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/compile.ts

@@ -1148,6 +1148,51 @@ function checkKeyTime(where: string, time: number, authored: number, duration: n
   );
 }
 
+/**
+ * The one refusal for a key that does not come after the key before it, for
+ * every timeline kind (issue #1506) — six call sites used to spell it six times.
+ *
+ * It names both keys by index and authored time, because the time alone does
+ * not say which pair to look at: a generated phrase of four one-second cycles,
+ * each written t = 0…1, collides at every cycle boundary, and `(at t=1)` read
+ * the same as an ordinary slip. When the two keys share a time AND the keys
+ * after the pair repeat the spacing of the keys before it, the period is read
+ * off the keys themselves — the second key's time less the first key's — and
+ * the message says that the closing key of one cycle is the opening key of the
+ * next. Nothing else is inferred: a duplicate with no keys after it, or with
+ * keys that do not repeat, carries the pair alone, and the declared `loop` is
+ * not consulted because it is a player hint (§4.1) and the boundary is the same
+ * either way. The fix is phrased from the runtime rather than from taste:
+ * `Animation.apply` wraps a looping time as `time % duration` and the last
+ * frame of every curve timeline is stepped, so a track that stops short of its
+ * period holds its last key until the wrap rather than easing into t = 0.
+ *
+ * ⚠️ The repetition is compared in authored seconds within one float32 step of
+ * the later key (`float32Step`) — `lag`/`stagger` shift every key of a track by
+ * the same amount, so the spacing is the same before and after them.
+ */
+function refuseKeyOrder(where: string, keys: ReadonlyArray<{ t: number }>, i: number, duplicate: boolean): never {
+  const at = keys[i].t;
+  const before = keys[i - 1].t;
+  const period = at - keys[0].t;
+  const following = Math.min(i - 1, keys.length - 1 - i);
+  let repeats = duplicate && period > 0 && following >= 1;
+  for (let j = 1; repeats && j <= following; j++) {
+    if (Math.abs(keys[i + j].t - keys[j].t - period) > float32Step(keys[i + j].t)) repeats = false;
+  }
+  const boundary = repeats
+    ? `. The keys from t=${keys[0].t} repeat every ${period}s, so key ${i - 1} closes one cycle and key ${i} opens ` +
+      `the next at the same time: a phrase that repeats every ${period}s ends one key before its period. Generate ` +
+      'each cycle without its closing key and keep that key on the last cycle only — a looping player wraps from ' +
+      'it to t=0, and a track that stops short holds its last key until the wrap'
+    : '';
+  throw new CompileError(
+    `${where}: key times must strictly increase — key ${i} at t=${at} does not come after key ${i - 1} at ` +
+      `t=${before} (keys counted from 0)${boundary}`,
+    'CE_COMPILE_KEY_TIMES_NOT_INCREASING',
+  );
+}
+
 function channelHex(v: number): string {
   const clamped = Math.max(0, Math.min(1, v));
   return Math.round(clamped * 255)
@@ -8106,9 +8151,7 @@ function compileValueTrack(
     const key = track.keys[i];
     const next = track.keys[i + 1];
     const time = keyTime(key.t + shift);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // A named-value timeline (`inherit`): the key's `v` is one name, stepped by
     // the format. The name is resolved rather than copied, and what is WRITTEN
@@ -8237,9 +8280,7 @@ function compileDrawOrder(
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // No offsets = "back to the setup draw order", which is the parser's own
     // encoding for it. An empty array means the same thing and is written the
@@ -8478,9 +8519,7 @@ function compileConstraintTrack(
     const key = keys[i];
     const next = keys[i + 1];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
 
     const entry: ModelKey = { time };
@@ -8906,9 +8945,7 @@ function compileSequenceTrack(
   for (let i = 0; i < track.keys.length; i++) {
     const key = track.keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     if (key.index !== undefined && key.index >= series.count) {
       throw new CompileError(
@@ -8946,9 +8983,7 @@ function compileDeformTrack(
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // -- a key that states a MODEL rather than a run (issue #294) ------------
     //
@@ -9660,9 +9695,7 @@ function compileTrack(
     const key = track.keys[i];
     const next = track.keys[i + 1];
     const time = keyTime(key.t + shift);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
 
     if (shape === 'attachment') {