lecodes-sdk 1.1.0 → 1.2.0

package/src/animate/tween/Timeline.ts

@@ -1,175 +1,175 @@
-// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
-// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
-// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
-// builder every target class delegates to (`tweenBag`).
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
-import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
-
-/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
-const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
-
-const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
-  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
-
-/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
-export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
-  const meta = bag as TweenMeta
-  const tracks: Track[] = []
-  for (const [prop, value] of bagProps(bag)) {
-    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
-    if (track) tracks.push(track)
-  }
-  return tracks
-}
-
-/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
-export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
-  const meta = bag as TweenMeta
-  const tracks = bagTracks(target, bag, 0, fromCurrent)
-  let durationMs = 0
-  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
-  const spec: TweenSpec = {
-    clock: clockOf(meta.clock, target._tweenClock),
-    durationMs, delayMs: 0,
-    iterations: iterationsOf(meta.loop),
-    pingPong: meta.loopMode !== "restart",
-    rate: 1, tracks, calls: [],
-  }
-  return new TweenAnimation(spec).play()
-}
-
-export type TimelineOptions = {
-  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
-  clock?: "ui" | "game",
-  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
-  loop?: boolean | number,
-  loopMode?: "restart" | "ping-pong",
-  /** Wait before the first play, ms. */
-  delay?: number,
-}
-
-/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
-export type TimelinePosition = number | string | [string, number]
-
-export type TimelineAddOptions = {
-  at?: TimelinePosition,
-  /** With several targets: each starts this many ms after the previous one. */
-  stagger?: number,
-}
-
-/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
- *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
- *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
- *  starts, the last one after it ends). */
-export class TimelineImpl extends TweenAnimation {
-  private _labels = new Map<string, number>()
-  private _end = 0
-
-  constructor(options: TimelineOptions = {}) {
-    super({
-      clock: clockOf(options.clock, CLOCK_UI),
-      durationMs: 0,
-      delayMs: options.delay ?? 0,
-      iterations: iterationsOf(options.loop),
-      pingPong: options.loopMode !== "restart",
-      rate: 1, tracks: [], calls: [],
-    })
-  }
-
-  private _at(at: TimelinePosition | undefined): number {
-    if (at === undefined) return this._end
-    if (typeof at === "number") return at
-    const name = Array.isArray(at) ? at[0] : at
-    const offset = Array.isArray(at) ? at[1] : 0
-    const base = this._labels.get(name)
-    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
-    return base + offset
-  }
-
-  private _grow(endMs: number): void {
-    if (endMs > this._end) this._end = endMs
-    this._spec.durationMs = this._end
-  }
-
-  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
-   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
-  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, true)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
-  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, false)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
-   *  every frame with the value. */
-  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
-    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
-    this._values.set(slot, deliver)
-    this._spec.tracks.push(track)
-    this._grow(track.atMs + track.durMs)
-    return this
-  }
-
-  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
-   *  finish, never from a previous run. */
-  call(at: TimelinePosition, fn: () => void): this {
-    const t = this._at(at)
-    this._spec.calls.push(t)
-    this._calls.push(fn)
-    this._grow(t)
-    return this
-  }
-
-  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
-  label(name: string, at?: TimelinePosition): this {
-    this._labels.set(name, this._at(at))
-    return this
-  }
-
-  /** Named times, ms. */
-  get labels(): Record<string, number> {
-    const o: Record<string, number> = {}
-    for (const [k, v] of this._labels) o[k] = v
-    return o
-  }
-
-  /** Extend the timeline with stillness after its current end. */
-  hold(ms: number): this {
-    this._grow(this._end + Math.max(0, ms))
-    return this
-  }
-
-  /** The current end, ms (tracks, calls and holds). */
-  get end(): number { return this._end }
-
-  /** `seek` also accepts a label. */
-  override seek(at: number | string): this {
-    return super.seek(typeof at === "string" ? this._at(at) : at)
-  }
-}
-
-/** The timeline handle type (see {@link TimelineImpl} for the members). */
-export type Timeline = TimelineImpl
-
-/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
-export function Timeline(options?: TimelineOptions): Timeline {
-  return new TimelineImpl(options)
-}
+// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
+// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
+// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
+// builder every target class delegates to (`tweenBag`).
+
+import { TweenAnimation, type Animation } from "./Animation"
+import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
+import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
+
+/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
+const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
+
+const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
+  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
+
+/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
+export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
+  const meta = bag as TweenMeta
+  const tracks: Track[] = []
+  for (const [prop, value] of bagProps(bag)) {
+    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
+    if (track) tracks.push(track)
+  }
+  return tracks
+}
+
+/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
+export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
+  const meta = bag as TweenMeta
+  const tracks = bagTracks(target, bag, 0, fromCurrent)
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  const spec: TweenSpec = {
+    clock: clockOf(meta.clock, target._tweenClock),
+    durationMs, delayMs: 0,
+    iterations: iterationsOf(meta.loop),
+    pingPong: meta.loopMode !== "restart",
+    rate: 1, tracks, calls: [],
+  }
+  return new TweenAnimation(spec).play()
+}
+
+export type TimelineOptions = {
+  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
+  clock?: "ui" | "game",
+  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
+  loop?: boolean | number,
+  loopMode?: "restart" | "ping-pong",
+  /** Wait before the first play, ms. */
+  delay?: number,
+}
+
+/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
+export type TimelinePosition = number | string | [string, number]
+
+export type TimelineAddOptions = {
+  at?: TimelinePosition,
+  /** With several targets: each starts this many ms after the previous one. */
+  stagger?: number,
+}
+
+/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
+ *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
+ *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
+ *  starts, the last one after it ends). */
+export class TimelineImpl extends TweenAnimation {
+  private _labels = new Map<string, number>()
+  private _end = 0
+
+  constructor(options: TimelineOptions = {}) {
+    super({
+      clock: clockOf(options.clock, CLOCK_UI),
+      durationMs: 0,
+      delayMs: options.delay ?? 0,
+      iterations: iterationsOf(options.loop),
+      pingPong: options.loopMode !== "restart",
+      rate: 1, tracks: [], calls: [],
+    })
+  }
+
+  private _at(at: TimelinePosition | undefined): number {
+    if (at === undefined) return this._end
+    if (typeof at === "number") return at
+    const name = Array.isArray(at) ? at[0] : at
+    const offset = Array.isArray(at) ? at[1] : 0
+    const base = this._labels.get(name)
+    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
+    return base + offset
+  }
+
+  private _grow(endMs: number): void {
+    if (endMs > this._end) this._end = endMs
+    this._spec.durationMs = this._end
+  }
+
+  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
+   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
+  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, true)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
+  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, false)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
+   *  every frame with the value. */
+  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
+    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
+    this._values.set(slot, deliver)
+    this._spec.tracks.push(track)
+    this._grow(track.atMs + track.durMs)
+    return this
+  }
+
+  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
+   *  finish, never from a previous run. */
+  call(at: TimelinePosition, fn: () => void): this {
+    const t = this._at(at)
+    this._spec.calls.push(t)
+    this._calls.push(fn)
+    this._grow(t)
+    return this
+  }
+
+  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
+  label(name: string, at?: TimelinePosition): this {
+    this._labels.set(name, this._at(at))
+    return this
+  }
+
+  /** Named times, ms. */
+  get labels(): Record<string, number> {
+    const o: Record<string, number> = {}
+    for (const [k, v] of this._labels) o[k] = v
+    return o
+  }
+
+  /** Extend the timeline with stillness after its current end. */
+  hold(ms: number): this {
+    this._grow(this._end + Math.max(0, ms))
+    return this
+  }
+
+  /** The current end, ms (tracks, calls and holds). */
+  get end(): number { return this._end }
+
+  /** `seek` also accepts a label. */
+  override seek(at: number | string): this {
+    return super.seek(typeof at === "string" ? this._at(at) : at)
+  }
+}
+
+/** The timeline handle type (see {@link TimelineImpl} for the members). */
+export type Timeline = TimelineImpl
+
+/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
+export function Timeline(options?: TimelineOptions): Timeline {
+  return new TimelineImpl(options)
+}

package/src/animate/tween/animateValue.ts

@@ -1,100 +1,100 @@
-// `animate()` — "animate a VALUE, I apply it" (docs/timeline-plan.md): the free-value tween for
-// anything without a native writer (a material parameter, a volume, a number the Canvas draws).
-// Since 2026-09-14 it runs on the keyframe core like everything else: a VALUE-domain track the host
-// evaluates natively and hands back to JS once per frame, the same easing vocabulary, keyframes,
-// loops and clocks, and the same `Animation` handle. `Timeline.animate` puts one into a timeline.
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { Mat4 } from "../../math/mat4"
-import type { Vec2Like, Vec3Like } from "../../math/vec"
-import type { QuatLike } from "../../math/quat"
-import type { Mat4Like } from "../../math/mat4"
-import type { ColorInput } from "../../core/color"
-import {
-  CLOCK_GAME, CLOCK_UI, DOM_VALUE, KIND_FLOAT, KIND_MAT4, DEFAULT_DURATION_MS, easingFor, iterationsOf, lanesOf, valueValue,
-  type Keyframe, type Track, type TweenChannel, type TweenMeta, type TweenSpec, type TweenTarget,
-} from "./spec"
-
-/** What `animate()` tweens: a number, a color (string / packed / rgb(a) array — delivered as rgba
- *  0..1), a 2 / 3-vector, a quaternion (slerp), or a 4x4 matrix (position / rotation / scale). */
-export type AnimateValue = number | string | Vec2Like | Vec3Like | QuatLike | Mat4Like | ColorInput
-
-/** `onUpdate` receives a number for a number; every other kind arrives as the SAME `Float32Array`
- *  every frame (overwritten in place — copy it if you keep it). A matrix is the 16 floats. */
-export type AnimateOut<T> = T extends number ? number : Float32Array
-
-export type AnimateOptions<T extends AnimateValue> = Omit<TweenMeta, "commit" | "layer"> & {
-  /** Start value (required unless `values` is given). */
-  from?: T,
-  /** End value. */
-  to?: T,
-  /** Keyframes instead of from/to (offsets via `times`). */
-  values?: T[],
-  onUpdate(value: AnimateOut<T>): void,
-  /** After the last frame of a run that reached its end (not on cancel). */
-  onComplete?(): void,
-}
-
-/** @internal Deliverers turn the host's lanes into the `onUpdate` argument without allocating. */
-const deliverer = (kind: number, lanes: number, onUpdate: (v: any) => void): ((l: Float32Array) => void) => {
-  if (kind === KIND_FLOAT) return (l) => onUpdate(l[0])
-  if (kind === KIND_MAT4) {
-    const out = new Float32Array(16)
-    return (l) => {
-      const m = Mat4.compose([l[0]!, l[1]!, l[2]!], [l[3]!, l[4]!, l[5]!, l[6]!], [l[7]!, l[8]!, l[9]!]).m
-      for (let i = 0; i < 16; i++) out[i] = m[i]!
-      onUpdate(out)
-    }
-  }
-  const out = new Float32Array(lanes)
-  return (l) => { for (let i = 0; i < lanes; i++) out[i] = l[i]!; onUpdate(out) }
-}
-
-/** VALUE slots are unique per world: the host addresses a value track by (animation, slot), and the
- *  evaluator must never see two animations naming the same slot (a channel is owned by the newest
- *  animation that names it — values have no shared state to own). */
-let nextSlot = 0
-
-/** @internal Build a VALUE track from animate options. Returns the track, its deliverer and its slot. */
-export const makeValueTrack = (o: AnimateOptions<any>, atMs: number): { track: Track, deliver: (l: Float32Array) => void, slot: number } => {
-  const slot = ++nextSlot
-  const raw: unknown[] = o.values ?? (o.from !== undefined && o.to !== undefined ? [o.from, o.to] : [])
-  if (raw.length < 1) throw new Error("animate: give `from` + `to`, or `values`")
-  const norm = raw.map((v) => valueValue(v))
-  if (norm.some((n) => n === null)) throw new Error("animate: a value is not a number, color, vector, quaternion or matrix")
-  const kind = norm[0]!.kind
-  if (norm.some((n) => n!.kind !== kind)) throw new Error("animate: every value must be the same kind")
-  const lanes = lanesOf(kind)
-  const easing = easingFor(o.easing, "value")
-  const keys: Keyframe[] = norm.map((n, i) => ({
-    t: o.times && o.times.length === norm.length ? o.times[i]! : norm.length === 1 ? 1 : i / (norm.length - 1),
-    easing,
-    value: { lanes: (n as { lanes: number[] }).lanes },
-    raw: raw[i],
-  }))
-  const channel: TweenChannel = { domain: DOM_VALUE, id: () => slot, value: valueValue }
-  const target: TweenTarget = { _tweenClock: CLOCK_UI, _tweenChannel: () => channel }
-  const track: Track = {
-    target, prop: "value", channel, kind, lanes,
-    atMs: atMs + (o.delay ?? 0), durMs: Math.max(0, o.duration ?? DEFAULT_DURATION_MS),
-    commit: false, keys,
-  }
-  return { track, deliver: deliverer(kind, lanes, o.onUpdate), slot }
-}
-
-/** Tween a free value and apply it yourself in `onUpdate` — the primitive for anything without a
- *  native channel (material params, volumes, numbers a Canvas draws). Same easing / keyframes /
- *  `loop` / `clock` as `animateTo`; returns the {@link Animation} handle. Default clock: `'ui'`. */
-export const animate = <T extends AnimateValue>(options: AnimateOptions<T>): Animation => {
-  const { track, deliver, slot } = makeValueTrack(options, 0)
-  const spec: TweenSpec = {
-    clock: options.clock === "game" ? CLOCK_GAME : CLOCK_UI,
-    durationMs: track.atMs + track.durMs, delayMs: 0,
-    iterations: iterationsOf(options.loop), pingPong: options.loopMode !== "restart",
-    rate: 1, tracks: [track], calls: [],
-  }
-  const a = new TweenAnimation(spec)
-  a._values.set(slot, deliver)
-  if (options.onComplete) a.onFinish((done) => { if (done) options.onComplete!() })
-  return a.play()
-}
+// `animate()` — "animate a VALUE, I apply it" (docs/timeline-plan.md): the free-value tween for
+// anything without a native writer (a material parameter, a volume, a number the Canvas draws).
+// Since 2026-09-14 it runs on the keyframe core like everything else: a VALUE-domain track the host
+// evaluates natively and hands back to JS once per frame, the same easing vocabulary, keyframes,
+// loops and clocks, and the same `Animation` handle. `Timeline.animate` puts one into a timeline.
+
+import { TweenAnimation, type Animation } from "./Animation"
+import { Mat4 } from "../../math/mat4"
+import type { Vec2Like, Vec3Like } from "../../math/vec"
+import type { QuatLike } from "../../math/quat"
+import type { Mat4Like } from "../../math/mat4"
+import type { ColorInput } from "../../core/color"
+import {
+  CLOCK_GAME, CLOCK_UI, DOM_VALUE, KIND_FLOAT, KIND_MAT4, DEFAULT_DURATION_MS, easingFor, iterationsOf, lanesOf, valueValue,
+  type Keyframe, type Track, type TweenChannel, type TweenMeta, type TweenSpec, type TweenTarget,
+} from "./spec"
+
+/** What `animate()` tweens: a number, a color (string / packed / rgb(a) array — delivered as rgba
+ *  0..1), a 2 / 3-vector, a quaternion (slerp), or a 4x4 matrix (position / rotation / scale). */
+export type AnimateValue = number | string | Vec2Like | Vec3Like | QuatLike | Mat4Like | ColorInput
+
+/** `onUpdate` receives a number for a number; every other kind arrives as the SAME `Float32Array`
+ *  every frame (overwritten in place — copy it if you keep it). A matrix is the 16 floats. */
+export type AnimateOut<T> = T extends number ? number : Float32Array
+
+export type AnimateOptions<T extends AnimateValue> = Omit<TweenMeta, "commit" | "layer"> & {
+  /** Start value (required unless `values` is given). */
+  from?: T,
+  /** End value. */
+  to?: T,
+  /** Keyframes instead of from/to (offsets via `times`). */
+  values?: T[],
+  onUpdate(value: AnimateOut<T>): void,
+  /** After the last frame of a run that reached its end (not on cancel). */
+  onComplete?(): void,
+}
+
+/** @internal Deliverers turn the host's lanes into the `onUpdate` argument without allocating. */
+const deliverer = (kind: number, lanes: number, onUpdate: (v: any) => void): ((l: Float32Array) => void) => {
+  if (kind === KIND_FLOAT) return (l) => onUpdate(l[0])
+  if (kind === KIND_MAT4) {
+    const out = new Float32Array(16)
+    return (l) => {
+      const m = Mat4.compose([l[0]!, l[1]!, l[2]!], [l[3]!, l[4]!, l[5]!, l[6]!], [l[7]!, l[8]!, l[9]!]).m
+      for (let i = 0; i < 16; i++) out[i] = m[i]!
+      onUpdate(out)
+    }
+  }
+  const out = new Float32Array(lanes)
+  return (l) => { for (let i = 0; i < lanes; i++) out[i] = l[i]!; onUpdate(out) }
+}
+
+/** VALUE slots are unique per world: the host addresses a value track by (animation, slot), and the
+ *  evaluator must never see two animations naming the same slot (a channel is owned by the newest
+ *  animation that names it — values have no shared state to own). */
+let nextSlot = 0
+
+/** @internal Build a VALUE track from animate options. Returns the track, its deliverer and its slot. */
+export const makeValueTrack = (o: AnimateOptions<any>, atMs: number): { track: Track, deliver: (l: Float32Array) => void, slot: number } => {
+  const slot = ++nextSlot
+  const raw: unknown[] = o.values ?? (o.from !== undefined && o.to !== undefined ? [o.from, o.to] : [])
+  if (raw.length < 1) throw new Error("animate: give `from` + `to`, or `values`")
+  const norm = raw.map((v) => valueValue(v))
+  if (norm.some((n) => n === null)) throw new Error("animate: a value is not a number, color, vector, quaternion or matrix")
+  const kind = norm[0]!.kind
+  if (norm.some((n) => n!.kind !== kind)) throw new Error("animate: every value must be the same kind")
+  const lanes = lanesOf(kind)
+  const easing = easingFor(o.easing, "value")
+  const keys: Keyframe[] = norm.map((n, i) => ({
+    t: o.times && o.times.length === norm.length ? o.times[i]! : norm.length === 1 ? 1 : i / (norm.length - 1),
+    easing,
+    value: { lanes: (n as { lanes: number[] }).lanes },
+    raw: raw[i],
+  }))
+  const channel: TweenChannel = { domain: DOM_VALUE, id: () => slot, value: valueValue }
+  const target: TweenTarget = { _tweenClock: CLOCK_UI, _tweenChannel: () => channel }
+  const track: Track = {
+    target, prop: "value", channel, kind, lanes,
+    atMs: atMs + (o.delay ?? 0), durMs: Math.max(0, o.duration ?? DEFAULT_DURATION_MS),
+    commit: false, keys,
+  }
+  return { track, deliver: deliverer(kind, lanes, o.onUpdate), slot }
+}
+
+/** Tween a free value and apply it yourself in `onUpdate` — the primitive for anything without a
+ *  native channel (material params, volumes, numbers a Canvas draws). Same easing / keyframes /
+ *  `loop` / `clock` as `animateTo`; returns the {@link Animation} handle. Default clock: `'ui'`. */
+export const animate = <T extends AnimateValue>(options: AnimateOptions<T>): Animation => {
+  const { track, deliver, slot } = makeValueTrack(options, 0)
+  const spec: TweenSpec = {
+    clock: options.clock === "game" ? CLOCK_GAME : CLOCK_UI,
+    durationMs: track.atMs + track.durMs, delayMs: 0,
+    iterations: iterationsOf(options.loop), pingPong: options.loopMode !== "restart",
+    rate: 1, tracks: [track], calls: [],
+  }
+  const a = new TweenAnimation(spec)
+  a._values.set(slot, deliver)
+  if (options.onComplete) a.onFinish((done) => { if (done) options.onComplete!() })
+  return a.play()
+}