feat(stdlib): add Anim.* + Tween.* — deterministic 2D animation & tweening (#5)

Two ECS-native, deterministic namespaces for 2D motion, driven off the fixed
frame clock so replays and lockstep netcode reproduce every frame and every
eased value exactly. Both are pure computed-inline Q16.16 / integer math (no new
runtime, no heap) — the game stores a timer on a component and calls these each
frame, exactly the way Collision.* / Grid.* are used.

Anim.* — spritesheet frame animation:
  - Anim.frame(timer,fps,count) -> int      looping frame index
  - Anim.once(timer,fps,count) -> int       one-shot, clamps on the last frame
  - Anim.pingpong(timer,fps,count) -> int   bounce 0..count-1..0
  - Anim.finished(timer,fps,count) -> bool   has a one-shot run past its end?
  - Anim.duration(fps,count) -> fixed        seconds for one cycle
  - Anim.cell_x/cell_y(frame,cols,cell) -> int  source rect on a grid sheet

Tween.* — value interpolation over a timeline:
  - Tween.progress/loop/yoyo(timer,duration) -> fixed  normalized amount
  - Tween.done(timer,duration) -> bool
  - Tween.ease(t, mode) -> fixed             shape by a literal curve 0..6,
                                             the same curves as Ease.* (now
                                             factored into a shared ease_eval)
  - Tween.number/round/point/tint(from,to,t) blend a fixed / int / Vector / color

The typed blends reuse the existing fixed / Vector / color helpers, and
Tween.ease shares Ease.*'s exact formulas via the new ease_eval(mode,t) — one
source of truth for every easing curve in the engine.

examples/library/anim.ludic asserts 34 cases (frame math, clamping, ping-pong,
cell geometry, timeline clamp/loop/yoyo, rounding, color/vector blends, and
Ease.in == Tween.ease(.,1)); wired into x test (now 62 passed). Docs: Anim +
Tween sections with 16 per-symbol pages, inventory/coverage green. Seed
reseeded; the C-free bootstrap fixpoint holds.

The stateful sugar the proposal sketches (named clips, Anim.play, fluent
Tween.chain/parallel handles, and an auto-injected advance system) is deliberately
left as a follow-up — this lands the deterministic math core both halves stand on.

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

docs/language/anim/_section.md

@@ -0,0 +1,7 @@
+---
+id: anim
+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.

docs/language/anim/anim-cell_x.md

@@ -0,0 +1,31 @@
+---
+id: anim-cell_x
+name: Anim.cell_x
+category: anim
+kind: namespace-method
+tokens: Anim.cell_x
+sig: Anim.cell_x(frame, cols, cell_w) -> int
+tip: The source x (pixels) of a frame on a grid spritesheet.
+order: 6
+ns: Anim
+member: cell_x
+---
+
+Turns a frame index into the left pixel of its cell on a spritesheet laid out as a grid of <code>cols</code> columns: <code>(frame mod cols) * cell_w</code>. Combine with <a href="anim-cell_y"><code>Anim.cell_y</code></a> to get the top-left source coordinate to blit from.
+
+Parameters:
+- `frame` — the frame index (e.g. from <a href="anim-frame"><code>Anim.frame</code></a>)
+- `cols` — columns in the sheet
+- `cell_w` — cell width in pixels
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let f  = Anim.frame(fixed(1), 12, 8)
+    let sx = Anim.cell_x(f, 4, 16)
+    let sy = Anim.cell_y(f, 4, 16)
+    print(sx)
+    print(sy)
+  }
+}
+```

docs/language/anim/anim-cell_y.md

@@ -0,0 +1,29 @@
+---
+id: anim-cell_y
+name: Anim.cell_y
+category: anim
+kind: namespace-method
+tokens: Anim.cell_y
+sig: Anim.cell_y(frame, cols, cell_h) -> int
+tip: The source y (pixels) of a frame on a grid spritesheet.
+order: 7
+ns: Anim
+member: cell_y
+---
+
+Turns a frame index into the top pixel of its cell on a spritesheet laid out as a grid of <code>cols</code> columns: <code>(frame / cols) * cell_h</code>. Pair with <a href="anim-cell_x"><code>Anim.cell_x</code></a> for the full source rectangle of the frame.
+
+Parameters:
+- `frame` — the frame index (e.g. from <a href="anim-frame"><code>Anim.frame</code></a>)
+- `cols` — columns in the sheet
+- `cell_h` — cell height in pixels
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let f  = Anim.frame(fixed(1), 12, 8)
+    let sy = Anim.cell_y(f, 4, 16)
+    print(sy)
+  }
+}
+```

docs/language/anim/anim-duration.md

@@ -0,0 +1,27 @@
+---
+id: anim-duration
+name: Anim.duration
+category: anim
+kind: namespace-method
+tokens: Anim.duration
+sig: Anim.duration(fps, count) -> fixed
+tip: Seconds for one full cycle of a clip: count / fps.
+order: 5
+ns: Anim
+member: duration
+---
+
+Returns the length of one cycle of a clip in seconds as a <code>fixed</code>: <code>count / fps</code>. Handy to schedule the next event, size a progress bar, or line a tween up with an animation.
+
+Parameters:
+- `fps` — frames per second
+- `count` — number of frames in the clip
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let secs = Anim.duration(12, 4)   # 4 frames / 12 fps = 0.333s
+    print(secs)
+  }
+}
+```

docs/language/anim/anim-finished.md

@@ -0,0 +1,30 @@
+---
+id: anim-finished
+name: Anim.finished
+category: anim
+kind: namespace-method
+tokens: Anim.finished
+sig: Anim.finished(timer, fps, count) -> bool
+tip: True once a one-shot clip has run past its last frame.
+order: 4
+ns: Anim
+member: finished
+---
+
+Returns <code>true</code> once <code>floor(timer * fps) >= count</code> — i.e. a one-shot clip driven by <a href="anim-once"><code>Anim.once</code></a> has played its final frame. Use it to despawn an effect, fire a follow-up, or switch back to an idle clip.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `fps` — frames per second
+- `count` — number of frames in the clip
+
+```ludic
+program Demo {
+  property Blast { timer: fixed = 0.0 }
+  model Boom { Blast }
+  handler Run phase Update {
+    Blast.timer = Blast.timer + Time.delta()
+    if Anim.finished(Blast.timer, 15, 6) { despawn(self()) }
+  }
+}
+```

docs/language/anim/anim-frame.md

@@ -0,0 +1,31 @@
+---
+id: anim-frame
+name: Anim.frame
+category: anim
+kind: namespace-method
+tokens: Anim.frame
+sig: Anim.frame(timer, fps, count) -> int
+tip: The looping frame index for an elapsed timer at a given fps.
+order: 1
+ns: Anim
+member: frame
+---
+
+Returns the current frame of a looping clip: <code>floor(timer * fps)</code> reduced modulo <code>count</code>. <code>timer</code> is elapsed seconds as a <code>fixed</code>, <code>fps</code> the clip's frames per second, and <code>count</code> the number of frames. The clip wraps forever — frame <code>count-1</code> is followed by frame <code>0</code>.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `fps` — frames per second
+- `count` — number of frames in the clip
+
+```ludic
+program Demo {
+  property Sprite { timer: fixed = 0.0 }
+  model Hero { Sprite }
+  handler Run phase Update {
+    Sprite.timer = Sprite.timer + Time.delta()
+    let cell = Anim.frame(Sprite.timer, 12, 4)   # 4-frame run at 12 fps
+    print(cell)
+  }
+}
+```

docs/language/anim/anim-once.md

@@ -0,0 +1,31 @@
+---
+id: anim-once
+name: Anim.once
+category: anim
+kind: namespace-method
+tokens: Anim.once
+sig: Anim.once(timer, fps, count) -> int
+tip: A non-looping frame index that clamps on the last frame.
+order: 2
+ns: Anim
+member: once
+---
+
+Like <a href="anim-frame"><code>Anim.frame</code></a> but for a one-shot clip: the frame is <code>min(floor(timer * fps), count - 1)</code>, so once it reaches the last frame it stays there instead of wrapping. Use it for a play-once animation like an explosion or a door opening; pair it with <a href="anim-finished"><code>Anim.finished</code></a> to know when it is done.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `fps` — frames per second
+- `count` — number of frames in the clip
+
+```ludic
+program Demo {
+  property Blast { timer: fixed = 0.0 }
+  model Boom { Blast }
+  handler Run phase Update {
+    Blast.timer = Blast.timer + Time.delta()
+    let cell = Anim.once(Blast.timer, 15, 6)
+    print(cell)
+  }
+}
+```

docs/language/anim/anim-pingpong.md

@@ -0,0 +1,31 @@
+---
+id: anim-pingpong
+name: Anim.pingpong
+category: anim
+kind: namespace-method
+tokens: Anim.pingpong
+sig: Anim.pingpong(timer, fps, count) -> int
+tip: A frame index that bounces 0..count-1..0 and repeats.
+order: 3
+ns: Anim
+member: pingpong
+---
+
+Returns a frame index that plays forward to <code>count-1</code>, then back to <code>0</code>, then forward again — a triangle wave over the frames. Ideal for a two-way idle bob or a breathing/pulsing loop where a plain wrap would snap.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `fps` — frames per second
+- `count` — number of frames in the clip
+
+```ludic
+program Demo {
+  property Idle { timer: fixed = 0.0 }
+  model Fish { Idle }
+  handler Run phase Update {
+    Idle.timer = Idle.timer + Time.delta()
+    let cell = Anim.pingpong(Idle.timer, 8, 4)   # 0 1 2 3 2 1 0 1 ...
+    print(cell)
+  }
+}
+```

docs/language/tween/_section.md

@@ -0,0 +1,7 @@
+---
+id: tween
+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.

docs/language/tween/tween-done.md

@@ -0,0 +1,29 @@
+---
+id: tween-done
+name: Tween.done
+category: tween
+kind: namespace-method
+tokens: Tween.done
+sig: Tween.done(timer, duration) -> bool
+tip: True once a one-shot tween's timer reaches its duration.
+order: 4
+ns: Tween
+member: done
+---
+
+Returns <code>true</code> once <code>timer >= duration</code> — the companion to <a href="tween-progress"><code>Tween.progress</code></a> for ending a one-shot tween: kick off the next step, clear a component, or snap the value to its target.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `duration` — the tween's length in seconds (a `fixed`)
+
+```ludic
+program Demo {
+  property Slide { timer: fixed = 0.0 }
+  model Menu { Slide }
+  handler Run phase Update {
+    Slide.timer = Slide.timer + Time.delta()
+    if Tween.done(Slide.timer, fixed(1)) { print(1) }
+  }
+}
+```

docs/language/tween/tween-ease.md

@@ -0,0 +1,37 @@
+---
+id: tween-ease
+name: Tween.ease
+category: tween
+kind: namespace-method
+tokens: Tween.ease
+sig: Tween.ease(t, mode) -> fixed
+tip: Shape a 0..1 amount through an easing curve chosen by a literal mode.
+order: 5
+ns: Tween
+member: ease
+---
+
+Shapes a normalized amount <code>t</code> (<code>0.0</code>..<code>1.0</code>) through one of the engine's easing curves and returns the eased <code>fixed</code>. <code>mode</code> must be a literal integer selecting the curve — the same curves as the <a href="ease"><code>Ease</code></a> namespace:
+
+- `0` — linear
+- `1` — ease-in (quadratic)
+- `2` — ease-out (quadratic)
+- `3` — smooth ease-in-out
+- `4` — ease-in-back (overshoots below 0)
+- `5` — ease-out-elastic (springy settle)
+- `6` — ease-out-bounce
+
+Parameters:
+- `t` — the amount to shape (a `fixed` in 0..1, e.g. from <a href="tween-progress"><code>Tween.progress</code></a>)
+- `mode` — a literal `int` 0..6 selecting the curve
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let t = Tween.progress(fixed(1), fixed(2))
+    let e = Tween.ease(t, 4)          # ease-in-back
+    let x = Tween.round(0, 200, e)
+    print(x)
+  }
+}
+```

docs/language/tween/tween-loop.md

@@ -0,0 +1,30 @@
+---
+id: tween-loop
+name: Tween.loop
+category: tween
+kind: namespace-method
+tokens: Tween.loop
+sig: Tween.loop(timer, duration) -> fixed
+tip: A repeating 0..1 sawtooth amount over duration.
+order: 2
+ns: Tween
+member: loop
+---
+
+Returns the fractional part of <code>timer / duration</code> — a sawtooth that ramps <code>0.0</code>→<code>1.0</code> then jumps back to <code>0.0</code> and repeats. Use it for a continuously cycling value: a scrolling offset, a rotating hue, a repeating pulse.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `duration` — seconds per cycle (a `fixed`)
+
+```ludic
+program Demo {
+  property Spin { timer: fixed = 0.0 }
+  model Coin { Spin }
+  handler Run phase Update {
+    Spin.timer = Spin.timer + Time.delta()
+    let t = Tween.loop(Spin.timer, fixed(2))   # a 2-second cycle
+    print(t)
+  }
+}
+```

docs/language/tween/tween-number.md

@@ -0,0 +1,29 @@
+---
+id: tween-number
+name: Tween.number
+category: tween
+kind: namespace-method
+tokens: Tween.number
+sig: Tween.number(from, to, t) -> fixed
+tip: Linear blend of two fixeds by amount t.
+order: 6
+ns: Tween
+member: number
+---
+
+Interpolates two <code>fixed</code> values: <code>from + (to - from) * t</code>. Feed it an eased <code>t</code> from <a href="tween-ease"><code>Tween.ease</code></a> to tween any fractional quantity — an alpha, a scale, a fixed-point position.
+
+Parameters:
+- `from` — the value at `t = 0` (a `fixed`)
+- `to` — the value at `t = 1` (a `fixed`)
+- `t` — the blend amount (a `fixed`, usually 0..1)
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let t = Tween.progress(fixed(1), fixed(2))
+    let scale = Tween.number(fixed(1), fixed(2), Tween.ease(t, 2))
+    print(scale)
+  }
+}
+```

docs/language/tween/tween-point.md

@@ -0,0 +1,31 @@
+---
+id: tween-point
+name: Tween.point
+category: tween
+kind: namespace-method
+tokens: Tween.point
+sig: Tween.point(from, to, t) -> Vector
+tip: Component-wise blend of two Vectors by amount t.
+order: 8
+ns: Tween
+member: point
+---
+
+Interpolates two <a href="vector"><code>Vector</code></a> endpoints component-wise by amount <code>t</code> — the 2D version of <a href="tween-number"><code>Tween.number</code></a>. Move an entity along a straight path, or ease a camera toward a target, in one call.
+
+Parameters:
+- `from` — the point at `t = 0` (a `Vector`)
+- `to` — the point at `t = 1` (a `Vector`)
+- `t` — the blend amount (a `fixed`, usually 0..1)
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let a = Vector.make(fixed(0), fixed(0))
+    let b = Vector.make(fixed(100), fixed(40))
+    let t = Tween.progress(fixed(1), fixed(2))
+    let p = Tween.point(a, b, Tween.ease(t, 3))
+    print(Vector.x(p))
+  }
+}
+```

docs/language/tween/tween-progress.md

@@ -0,0 +1,31 @@
+---
+id: tween-progress
+name: Tween.progress
+category: tween
+kind: namespace-method
+tokens: Tween.progress
+sig: Tween.progress(timer, duration) -> fixed
+tip: A one-shot 0..1 amount, clamped, for timer over duration.
+order: 1
+ns: Tween
+member: progress
+---
+
+Returns <code>timer / duration</code> clamped to <code>0.0</code>..<code>1.0</code> — the normalized progress of a one-shot tween. Feed it to <a href="tween-ease"><code>Tween.ease</code></a> to shape it, then to a typed blend. Once <code>timer</code> reaches <code>duration</code> it pins at <code>1.0</code> (a non-positive <code>duration</code> also reads as done).
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `duration` — the tween's length in seconds (a `fixed`)
+
+```ludic
+program Demo {
+  property Fade { timer: fixed = 0.0 }
+  model Panel { Fade }
+  handler Run phase Update {
+    Fade.timer = Fade.timer + Time.delta()
+    let t = Tween.progress(Fade.timer, fixed(1))
+    let a = Tween.round(0, 255, Tween.ease(t, 2))
+    print(a)
+  }
+}
+```

docs/language/tween/tween-round.md

@@ -0,0 +1,32 @@
+---
+id: tween-round
+name: Tween.round
+category: tween
+kind: namespace-method
+tokens: Tween.round
+sig: Tween.round(from, to, t) -> int
+tip: Linear blend of two ints by amount t, rounded to the nearest int.
+order: 7
+ns: Tween
+member: round
+---
+
+Interpolates two <code>int</code> endpoints by amount <code>t</code> and rounds to the nearest integer (half up): <code>from + round((to - from) * t)</code>. The go-to for tweening a pixel position, a channel byte, or any integer field. Combine with <a href="tween-ease"><code>Tween.ease</code></a> for shaped motion.
+
+Parameters:
+- `from` — the value at `t = 0` (an `int`)
+- `to` — the value at `t = 1` (an `int`)
+- `t` — the blend amount (a `fixed`, usually 0..1)
+
+```ludic
+program Demo {
+  property Slide { timer: fixed = 0.0 }
+  model Card { Slide }
+  handler Run phase Update {
+    Slide.timer = Slide.timer + Time.delta()
+    let t = Tween.progress(Slide.timer, fixed(1))
+    let x = Tween.round(0, 320, Tween.ease(t, 2))
+    print(x)
+  }
+}
+```

docs/language/tween/tween-tint.md

@@ -0,0 +1,29 @@
+---
+id: tween-tint
+name: Tween.tint
+category: tween
+kind: namespace-method
+tokens: Tween.tint
+sig: Tween.tint(from, to, t) -> int
+tip: Per-channel blend of two colors by amount t.
+order: 9
+ns: Tween
+member: tint
+---
+
+Blends two colors (<code>0x00RRGGBB</code> ints) channel by channel by amount <code>t</code> — the color equivalent of <a href="tween-number"><code>Tween.number</code></a>. Fade a sprite to white on hit, cross-fade a sky, or pulse a UI accent. Matches <a href="color-lerp"><code>Color.lerp</code></a>, ready for an eased <code>t</code> from <a href="tween-ease"><code>Tween.ease</code></a>.
+
+Parameters:
+- `from` — the color at `t = 0` (an `int`, `0x00RRGGBB`)
+- `to` — the color at `t = 1` (an `int`, `0x00RRGGBB`)
+- `t` — the blend amount (a `fixed`, usually 0..1)
+
+```ludic
+program Demo {
+  handler Run phase Update {
+    let t = Tween.progress(fixed(1), fixed(2))
+    let c = Tween.tint(Color.rgb(0, 0, 0), Color.rgb(255, 255, 255), t)
+    print(c)
+  }
+}
+```

docs/language/tween/tween-yoyo.md

@@ -0,0 +1,31 @@
+---
+id: tween-yoyo
+name: Tween.yoyo
+category: tween
+kind: namespace-method
+tokens: Tween.yoyo
+sig: Tween.yoyo(timer, duration) -> fixed
+tip: A repeating 0..1..0 triangle amount over duration.
+order: 3
+ns: Tween
+member: yoyo
+---
+
+Returns a triangle wave: <code>timer / duration</code> ramps <code>0.0</code>→<code>1.0</code> over the first <code>duration</code>, then <code>1.0</code>→<code>0.0</code> over the next, and repeats. The smooth back-and-forth for a hover bob, a pulsing highlight, or a breathing scale — no snap at the ends the way <a href="tween-loop"><code>Tween.loop</code></a> has.
+
+Parameters:
+- `timer` — elapsed seconds (a `fixed`)
+- `duration` — seconds for each leg (a `fixed`)
+
+```ludic
+program Demo {
+  property Bob { timer: fixed = 0.0 }
+  model Pickup { Bob }
+  handler Run phase Update {
+    Bob.timer = Bob.timer + Time.delta()
+    let t = Tween.yoyo(Bob.timer, fixed(1))
+    let y = Tween.round(100, 108, Tween.ease(t, 3))
+    print(y)
+  }
+}
+```