feat(anim): animation ergonomics — named clips, Anim.play/Motion.to, frame events, fluent Tween handles (#48)

The ergonomic layer over the engine-owned SpriteAnim/Motion systems (#43):

- Named clips: Anim.clip("run", frames, fps, mode) registers a clip by name and
  Anim.play(entity, "run") plays it; Anim.play(entity, fps, frames, mode) sets
  the clip directly. A name-keyed registry in systems.ludic.
- Frame events: Anim.on_frame(entity, frame) arms optional SpriteAnim
  event_frame/event_fired fields; the engine flags the tick the clip first lands
  on that frame, and Anim.fired(entity) reads it — the game reacts, so it stays
  inside the no-runtime-dispatch event model.
- Motion.to(entity, from, to, dur, ease) starts a value tween over the Motion
  component in one call (reflection-ABI writes, resetting the timer).
- Fluent Tween handles (runtime/native/tween.ludic): Tween.to / Tween.chain /
  Tween.delay build a sequenced, disposable handle advanced by a new engine-owned
  system (esys_tween, run each Update tick); Tween.value / Tween.done /
  Tween.parallel / Tween.stop read and control it. The 1-arg Tween.done(handle)
  is disambiguated from the 2-arg pure Tween.done(timer, dur).

Splicing: g_uses_anim_rt pulls in systems.ludic; g_uses_tween_rt pulls in
tween.ludic and inserts esys_tween into the Update phase. All integer and
deterministic, so animation and motion reproduce exactly under replay/lockstep.

Worked example + regression: examples/library/anim_sugar.ludic
(4 8 2 1 0 100 100 0 0 1 20 20 30 0 1). Twelve new docs pages (Anim, the new
Motion namespace, Tween handles). Full suite 77 passed, self-host C-free fixpoint
intact, no golden drift.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/anim/_section.md

@@ -4,4 +4,4 @@ title: Anim
 order: 28
 ---
 
-Spritesheet frame animation off the fixed frame clock. Store an elapsed <code>timer</code> (seconds, a <code>fixed</code>) on a component and each frame ask <a href="anim-frame"><code>Anim.frame</code></a> / <a href="anim-once"><code>Anim.once</code></a> / <a href="anim-pingpong"><code>Anim.pingpong</code></a> which cell to draw; <a href="anim-cell_x"><code>Anim.cell_x</code></a>/<a href="anim-cell_y"><code>Anim.cell_y</code></a> turn a frame index into a source rectangle on the sheet. Everything is integer/fixed and deterministic — the same timer reproduces the same frame every run, so replays and lockstep netcode match exactly.
+Spritesheet frame animation off the fixed frame clock. Store an elapsed <code>timer</code> (seconds, a <code>fixed</code>) on a component and each frame ask <a href="anim-frame"><code>Anim.frame</code></a> / <a href="anim-once"><code>Anim.once</code></a> / <a href="anim-pingpong"><code>Anim.pingpong</code></a> which cell to draw; <a href="anim-cell_x"><code>Anim.cell_x</code></a>/<a href="anim-cell_y"><code>Anim.cell_y</code></a> turn a frame index into a source rectangle on the sheet. Everything is integer/fixed and deterministic — the same timer reproduces the same frame every run, so replays and lockstep netcode match exactly. For the ECS engine-owned <code>SpriteAnim</code> component there is also an ergonomic layer: register named clips with <a href="anim-clip"><code>Anim.clip</code></a> and play them by name with <a href="anim-play"><code>Anim.play</code></a>, and arm frame events with <a href="anim-on_frame"><code>Anim.on_frame</code></a> / <a href="anim-fired"><code>Anim.fired</code></a>.

docs/language/anim/anim-clip.md

@@ -0,0 +1,35 @@
+---
+id: anim-clip
+name: Anim.clip
+category: anim
+kind: namespace-method
+tokens: Anim.clip
+sig: Anim.clip(name, frames, fps, mode)
+tip: Register a named spritesheet clip so Anim.play can play it by name.
+order: 31
+ns: Anim
+member: clip
+---
+
+Registers (or updates) a spritesheet clip under a <code>name</code>, so gameplay refers to a motion by name — <code>Anim.play(entity, "run")</code> — instead of repeating its frame count and rate everywhere. The clip stores <code>frames</code> (cell count), <code>fps</code> (rate) and <code>mode</code> (0 loop, 1 once, 2 ping-pong). Names compare by identity (a string literal interns to one pointer), and the registry holds up to 32 clips. Registering the same name again overwrites it.
+
+Parameters:
+- `name` — the clip name (a string)
+- `frames` — number of cells in the clip
+- `fps` — playback rate in frames per second
+- `mode` — 0 loop, 1 once (clamp on last), 2 ping-pong
+
+```ludic
+program Demo {
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0 }
+  model Hero { SpriteAnim }
+  entry {
+    Anim.clip("idle", 2, 4, 0)          # a slow 2-frame idle loop
+    Anim.clip("run",  6, 12, 0)         # a 6-frame run
+    Anim.clip("hit",  3, 15, 1)         # a one-shot hit reaction
+    spawn Hero { SpriteAnim { } }
+    Anim.play(World.query_next(World.prop_id("SpriteAnim"), 0), "run")
+    quit()
+  }
+}
+```

docs/language/anim/anim-fired.md

@@ -0,0 +1,28 @@
+---
+id: anim-fired
+name: Anim.fired
+category: anim
+kind: namespace-method
+tokens: Anim.fired
+sig: Anim.fired(entity) -> bool
+tip: Did the entity's clip land on its armed frame event this tick?
+order: 33
+ns: Anim
+member: fired
+---
+
+Returns whether an entity's <code>SpriteAnim</code> clip landed on the frame armed by <a href="anim-on_frame"><code>Anim.on_frame</code></a> this tick — the read side of a frame event. It is true only on the single tick the clip first reaches that cell, so a game can poll it each frame and turn it into a gameplay action (emit an event, spawn a hitbox, play a footstep). Returns <code>false</code> if the entity has no <code>SpriteAnim</code> or no <code>event_fired</code> field.
+
+Parameters:
+- `entity` — the entity carrying `SpriteAnim`
+
+```ludic
+program Demo {
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0, event_frame: int = 0, event_fired: int = 0 }
+  model Hero { SpriteAnim }
+  handler Step phase Update {
+    let e = World.query_next(World.prop_id("SpriteAnim"), 0)
+    if Anim.fired(e) { print(42) }      # react: footstep, hitbox, event…
+  }
+}
+```

docs/language/anim/anim-on_frame.md

@@ -0,0 +1,33 @@
+---
+id: anim-on_frame
+name: Anim.on_frame
+category: anim
+kind: namespace-method
+tokens: Anim.on_frame
+sig: Anim.on_frame(entity, frame)
+tip: Arm a frame event — the engine flags the tick a clip lands on this frame.
+order: 32
+ns: Anim
+member: on_frame
+---
+
+Arms a <strong>frame event</strong> on an entity's <code>SpriteAnim</code>: the engine sets the component's <code>event_fired</code> flag on the tick the clip <em>first lands</em> on <code>frame</code> — a footstep on the contact cell, a hitbox going live mid-swing. Gameplay reads the flag with <a href="anim-fired"><code>Anim.fired</code></a> in its own handler and reacts (emit its own event, spawn, play a sound). The engine detects the boundary; the game owns the reaction, so it stays inside the deterministic, no-runtime-dispatch event model. Requires the component to carry <code>event_frame</code> and <code>event_fired</code> fields.
+
+Parameters:
+- `entity` — the entity carrying `SpriteAnim`
+- `frame` — the cell index that should fire the event
+
+```ludic
+program Demo {
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0, event_frame: int = 0, event_fired: int = 0 }
+  model Hero { SpriteAnim }
+  entry {
+    spawn Hero { SpriteAnim { fps: 12, frames: 6, mode: 0 } }
+    let e = World.query_next(World.prop_id("SpriteAnim"), 0)
+    Anim.on_frame(e, 3)                 # fire when the run clip hits its contact frame
+    tick_fixed()
+    if Anim.fired(e) { print(1) }
+    quit()
+  }
+}
+```

docs/language/anim/anim-play.md

@@ -0,0 +1,34 @@
+---
+id: anim-play
+name: Anim.play
+category: anim
+kind: namespace-method
+tokens: Anim.play
+sig: Anim.play(entity, clip) | Anim.play(entity, fps, frames, mode)
+tip: Start (or restart) a spritesheet clip on an entity in one call.
+order: 30
+ns: Anim
+member: play
+---
+
+Starts a spritesheet clip on an entity's <code>SpriteAnim</code> component and rewinds it to its first cell, so gameplay swaps or replays an animation with one call instead of setting five fields by hand. Two forms: <code>Anim.play(entity, "run")</code> plays a <a href="anim-clip"><code>named clip</code></a> registered with <code>Anim.clip</code>; <code>Anim.play(entity, fps, frames, mode)</code> sets the clip directly (<code>mode</code> 0 loop, 1 once, 2 ping-pong). A no-op if the entity has no <code>SpriteAnim</code>. The engine advances the clip from there each tick.
+
+Parameters:
+- `entity` — the entity carrying `SpriteAnim`
+- `clip` — a registered clip name (2-argument form), **or**
+- `fps`, `frames`, `mode` — the clip rate, cell count and play mode (4-argument form)
+
+```ludic
+program Demo {
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0 }
+  model Hero { SpriteAnim }
+  entry {
+    Anim.clip("run", 6, 12, 0)
+    spawn Hero { SpriteAnim { } }
+    let e = World.query_next(World.prop_id("SpriteAnim"), 0)
+    Anim.play(e, "run")                 # by name
+    Anim.play(e, 8, 4, 1)               # or directly: 4 frames @ 8fps, once
+    quit()
+  }
+}
+```

docs/language/motion/_section.md

@@ -0,0 +1,7 @@
+---
+id: motion
+title: Motion
+order: 29
+---
+
+Ergonomic control of the engine-owned <code>Motion</code> component — the value tween the engine advances each tick (see the ECS engine-systems). <a href="motion-to"><code>Motion.to</code></a> starts a tween on an entity from one value to another over a number of ticks with an easing curve, rewinding it so it plays from the start, instead of setting the component's <code>from</code>/<code>to</code>/<code>dur</code>/<code>ease</code> fields by hand. The tween is integer and deterministic, so motion reproduces exactly under replay and lockstep. For a standalone, sequenced tween not tied to a component, see the fluent <a href="tween"><code>Tween</code></a> handles. Related: <a href="anim"><code>Anim</code></a>, <a href="ease"><code>Ease</code></a>, <a href="tween"><code>Tween</code></a>.

docs/language/motion/motion-to.md

@@ -0,0 +1,33 @@
+---
+id: motion-to
+name: Motion.to
+category: motion
+kind: namespace-method
+tokens: Motion.to
+sig: Motion.to(entity, from, to, dur, ease)
+tip: Start a value tween on an entity's Motion component in one call.
+order: 1
+ns: Motion
+member: to
+---
+
+Starts a value tween on an entity's <code>Motion</code> component: it sets <code>from</code>, <code>to</code>, <code>dur</code> and <code>ease</code>, resets the timer, and seeds <code>value</code> at <code>from</code>, so the engine interpolates <code>value</code> from <code>from</code> to <code>to</code> over <code>dur</code> ticks and latches <code>done</code> at the end. One call replaces setting five fields by hand — a health bar sliding, a door opening, an alpha fade. A no-op if the entity has no <code>Motion</code>. Integer and deterministic.
+
+Parameters:
+- `entity` — the entity carrying `Motion`
+- `from`, `to` — the start and end values (integer game units)
+- `dur` — the duration in engine ticks
+- `ease` — 0 linear, 1 in, 2 out, 3 in-out
+
+```ludic
+program Demo {
+  property Motion { ticks: int = 0, dur: int = 0, from: int = 0, to: int = 0, ease: int = 0, value: int = 0, done: int = 0 }
+  model Door { Motion }
+  entry {
+    spawn Door { Motion { } }
+    let e = World.query_next(World.prop_id("Motion"), 0)
+    Motion.to(e, 0, 64, 30, 2)          # slide 0 -> 64 over 30 ticks, ease-out
+    quit()
+  }
+}
+```

docs/language/tween/_section.md

@@ -4,4 +4,4 @@ title: Tween
 order: 29
 ---
 
-Value interpolation over a timeline, off the fixed frame clock. The timeline helpers <a href="tween-progress"><code>Tween.progress</code></a>/<a href="tween-loop"><code>Tween.loop</code></a>/<a href="tween-yoyo"><code>Tween.yoyo</code></a> turn an elapsed <code>timer</code> and a <code>duration</code> into a normalized amount; <a href="tween-ease"><code>Tween.ease</code></a> shapes that amount through an easing curve (shared with <a href="ease"><code>Ease</code></a>); and the typed blends <a href="tween-number"><code>Tween.number</code></a>/<a href="tween-round"><code>Tween.round</code></a>/<a href="tween-point"><code>Tween.point</code></a>/<a href="tween-tint"><code>Tween.tint</code></a> interpolate a <code>fixed</code>, <code>int</code>, <code>Vector</code>, or color. All deterministic fixed-point, so a replay reproduces every eased value exactly.
+Value interpolation over a timeline, off the fixed frame clock. The timeline helpers <a href="tween-progress"><code>Tween.progress</code></a>/<a href="tween-loop"><code>Tween.loop</code></a>/<a href="tween-yoyo"><code>Tween.yoyo</code></a> turn an elapsed <code>timer</code> and a <code>duration</code> into a normalized amount; <a href="tween-ease"><code>Tween.ease</code></a> shapes that amount through an easing curve (shared with <a href="ease"><code>Ease</code></a>); and the typed blends <a href="tween-number"><code>Tween.number</code></a>/<a href="tween-round"><code>Tween.round</code></a>/<a href="tween-point"><code>Tween.point</code></a>/<a href="tween-tint"><code>Tween.tint</code></a> interpolate a <code>fixed</code>, <code>int</code>, <code>Vector</code>, or color. All deterministic fixed-point, so a replay reproduces every eased value exactly. Beyond these pure interpolators there are <strong>fluent handles</strong> the engine advances for you: <a href="tween-to"><code>Tween.to</code></a> starts one and returns a handle, <a href="tween-chain"><code>Tween.chain</code></a> and <a href="tween-delay"><code>Tween.delay</code></a> sequence more segments, and <a href="tween-value"><code>Tween.value</code></a> / <a href="tween-done"><code>Tween.done</code></a> / <a href="tween-parallel"><code>Tween.parallel</code></a> / <a href="tween-stop"><code>Tween.stop</code></a> read and control them.

docs/language/tween/tween-chain.md

@@ -0,0 +1,32 @@
+---
+id: tween-chain
+name: Tween.chain
+category: tween
+kind: namespace-method
+tokens: Tween.chain
+sig: Tween.chain(handle, to, dur, ease) -> handle
+tip: Append a tween segment that runs after the handle's current queue.
+order: 31
+ns: Tween
+member: chain
+---
+
+Appends a tween segment to a <a href="tween-to"><code>handle</code></a> that runs <em>after</em> its current segments finish, continuing from where the previous one ended — so the game only names the new target. Returns the same handle, so calls chain fluently. A handle holds up to eight segments; combine with <a href="tween-delay"><code>Tween.delay</code></a> for pauses. The engine advances the whole sequence one segment at a time.
+
+Parameters:
+- `handle` — the tween handle to extend
+- `to` — the target value for this segment
+- `dur` — the segment length in engine ticks
+- `ease` — 0 linear, 1 in, 2 out, 3 in-out
+
+```ludic
+program Demo {
+  property Marker { n: int = 0 }
+  model M { Marker }
+  entry {
+    var h = Tween.to(0, 100, 20, 2)     # rise
+    h = Tween.chain(h, 0, 20, 1)        # then fall back
+    quit()
+  }
+}
+```

docs/language/tween/tween-delay.md

@@ -0,0 +1,31 @@
+---
+id: tween-delay
+name: Tween.delay
+category: tween
+kind: namespace-method
+tokens: Tween.delay
+sig: Tween.delay(handle, ticks) -> handle
+tip: Append a pause to a tween handle's sequence.
+order: 32
+ns: Tween
+member: delay
+---
+
+Appends a <strong>pause</strong> of <code>ticks</code> ticks to a <a href="tween-to"><code>handle</code></a>'s sequence: the value holds where the previous segment left it, then the next <a href="tween-chain"><code>chained</code></a> segment begins. Returns the handle for fluent chaining. Use it to stagger a multi-step motion — rise, hold, fall — or to offset one handle from another running in parallel.
+
+Parameters:
+- `handle` — the tween handle to extend
+- `ticks` — how many engine ticks to hold
+
+```ludic
+program Demo {
+  property Marker { n: int = 0 }
+  model M { Marker }
+  entry {
+    var h = Tween.to(0, 50, 15, 0)      # move
+    h = Tween.delay(h, 10)              # wait
+    h = Tween.chain(h, 100, 15, 0)      # move again
+    quit()
+  }
+}
+```

docs/language/tween/tween-parallel.md

@@ -0,0 +1,30 @@
+---
+id: tween-parallel
+name: Tween.parallel
+category: tween
+kind: namespace-method
+tokens: Tween.parallel
+sig: Tween.parallel(a, b) -> bool
+tip: Are two tween handles both finished? — a parallel completion query.
+order: 35
+ns: Tween
+member: parallel
+---
+
+Returns whether two <a href="tween-to"><code>handles</code></a> are <em>both</em> finished. Independent handles are advanced together every frame, so running several at once already runs them in parallel; this is the "wait for all" query over a pair — start a fade and a slide together, then act when both complete. For longer sequences on a single value, chain segments with <a href="tween-chain"><code>Tween.chain</code></a> instead.
+
+Parameters:
+- `a`, `b` — the two tween handles to test
+
+```ludic
+program Demo {
+  property Marker { n: int = 0 }
+  model M { Marker }
+  entry {
+    let fade  = Tween.to(255, 0, 20, 0)
+    let slide = Tween.to(0, 80, 30, 2)
+    if Tween.parallel(fade, slide) { print(1) }   # both done?
+    quit()
+  }
+}
+```

docs/language/tween/tween-stop.md

@@ -0,0 +1,29 @@
+---
+id: tween-stop
+name: Tween.stop
+category: tween
+kind: namespace-method
+tokens: Tween.stop
+sig: Tween.stop(handle)
+tip: Stop and dispose a tween handle, freezing its value.
+order: 34
+ns: Tween
+member: stop
+---
+
+Stops a <a href="tween-to"><code>tween handle</code></a> immediately and frees its slot back to the pool. Its <a href="tween-value"><code>value</code></a> is frozen where it was, and <a href="tween-done"><code>Tween.done</code></a> then reports it finished. Use it to cancel a motion early — an interrupted animation, an entity that despawned mid-tween — so long-lived games recycle handles instead of exhausting the pool.
+
+Parameters:
+- `handle` — the tween handle to stop
+
+```ludic
+program Demo {
+  property Marker { n: int = 0 }
+  model M { Marker }
+  entry {
+    let h = Tween.to(0, 100, 60, 0)
+    Tween.stop(h)                       # cancel it now
+    quit()
+  }
+}
+```

docs/language/tween/tween-to.md

@@ -0,0 +1,34 @@
+---
+id: tween-to
+name: Tween.to
+category: tween
+kind: namespace-method
+tokens: Tween.to
+sig: Tween.to(from, to, dur, ease) -> handle
+tip: Start a fluent, engine-advanced tween and return a handle.
+order: 30
+ns: Tween
+member: to
+---
+
+Starts a <strong>stateful tween handle</strong> — from <code>from</code> to <code>to</code> over <code>dur</code> ticks with easing <code>ease</code> — and returns an integer handle. Unlike the pure <a href="tween-progress"><code>Tween.progress</code></a> interpolators (which the game drives from its own timer), a handle is <em>advanced by the engine</em> one tick per frame: fire it once, then read <a href="tween-value"><code>Tween.value</code></a> each frame and <a href="tween-done"><code>Tween.done</code></a> to know when it finishes. <a href="tween-chain"><code>Tween.chain</code></a> and <a href="tween-delay"><code>Tween.delay</code></a> append segments for a sequence. Integer and deterministic, so a sequence plays identically under replay. The handle pool is fixed-size and reuses finished slots.
+
+Parameters:
+- `from`, `to` — the start and end values (integer game units)
+- `dur` — the segment length in engine ticks
+- `ease` — 0 linear, 1 in, 2 out, 3 in-out
+
+```ludic
+program Demo {
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0 }
+  property Pop { h: int = 0 }
+  model Coin { SpriteAnim, Pop }
+  entry {
+    spawn Coin { Pop { h: 0 } }
+    let e = World.query_next(World.prop_id("Pop"), 0)
+    let f = World.field_id(World.prop_id("Pop"), "h")
+    World.set(e, World.prop_id("Pop"), f, Tween.to(0, 40, 20, 2))   # pop upward
+    quit()
+  }
+}
+```

docs/language/tween/tween-value.md

@@ -0,0 +1,32 @@
+---
+id: tween-value
+name: Tween.value
+category: tween
+kind: namespace-method
+tokens: Tween.value
+sig: Tween.value(handle) -> int
+tip: The current value of a fluent tween handle this frame.
+order: 33
+ns: Tween
+member: value
+---
+
+Returns the current interpolated value of a <a href="tween-to"><code>tween handle</code></a> this frame — the number the engine advanced it to. Read it each frame to drive a position, an alpha, a scale. Once every segment has finished the value rests on the final target; <a href="tween-done"><code>Tween.done</code></a> reports when that has happened. Returns <code>0</code> for an invalid handle.
+
+Parameters:
+- `handle` — the tween handle to read
+
+```ludic
+program Demo {
+  property Pos { x: int = 0 }
+  property Tw { h: int = 0 }
+  model Mover { Pos, Tw }
+  handler Move phase Update {
+    let p = World.prop_id("Pos")
+    let t = World.prop_id("Tw")
+    let e = World.query_next(t, 0)
+    let h = World.get(e, t, World.field_id(t, "h"))
+    World.set(e, p, World.field_id(p, "x"), Tween.value(h))
+  }
+}
+```