lecodes-sdk 1.0.0 → 1.2.0

package/prompts/select.ts

@@ -87,15 +87,30 @@ export function detectBundle(files: ProjectFile[]): Bundle | null {
 }
 
 /**
- * Sticky per-conversation upgrade: once a bundle is chosen, only ever move UP the specificity
- * ladder (ui → 2d/3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
- * stable while a project grows from "empty" to "3D game with a HUD".
+ * Sticky per-conversation upgrade from CODE DETECTION: once a bundle is chosen, only ever move UP
+ * the ladder (ui → 2d → 3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
+ * stable while a project grows from "empty" to "3D game with a HUD". The ladder mirrors
+ * detectBundle's priority (AR > 3D > 2D > UI): a 2D project that gains 3D code moves to the 3D
+ * bundle. (2D and 3D used to share a rank, which made 2D → 3D unreachable by any route — a project
+ * that started as a 2D game could never become a 3D one.)
  */
 export function upgradeBundle(current: Bundle, detected: Bundle): Bundle {
-  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 1, "ar-app": 2 }
+  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 2, "ar-app": 3 }
   return rank[detected] > rank[current] ? detected : current
 }
 
+/**
+ * Whether to honor the model's own `<bundle>` directive (parseBundleDirective). Unlike detection,
+ * an explicit request may move in ANY direction: the model is saying the APIs the request needs
+ * are not documented in its current bundle — turning a 2D game into 3D, a 3D app into AR, or a 3D
+ * scene back into a 2D game are all legitimate. The old code it rewrites is in its context; it
+ * needs no documentation to replace it. Only a no-op (asking for the bundle it already has) is
+ * refused, which also rules out a re-send loop.
+ */
+export function canSwitchBundle(current: Bundle, requested: Bundle): boolean {
+  return requested !== current
+}
+
 const DIRECTIVE_WORD: Record<string, Bundle> = { "2d": "2d-game", "3d": "3d-app", "ar": "ar-app" }
 
 /**

package/src/animate/tween/Animation.ts

@@ -0,0 +1,378 @@
+// The animation HANDLE (docs/timeline-plan.md §2.2): what `animateTo` / `animateFrom` / `Timeline`
+// return. Owns one spec; every `play()` builds the blob (target ids resolve at play time), hands it
+// to the host (`_creatorUI.tweenCreate`) and gets events back (`registerTweenEvent`: time-callbacks
+// and finish). On a host without the tween core the UI tracks fall back to the old
+// `animateTo` / `animateFrom` bridge pair (single-value tweens only) and the clock is a timer —
+// see `fallback` below.
+
+import { CLOCK_GAME, CLOCK_UI, DOM_UI, DOM_VALUE, buildBlob, evaluateTrack, type Track, type TweenSpec } from "./spec"
+
+const OP_PLAY = 0
+const OP_PAUSE = 1
+const OP_RESUME = 2
+const OP_CANCEL = 3
+const OP_FINISH = 4
+
+const EV_CALL = 0
+const EV_FINISH = 1
+const EV_VALUE = 2   // (id, 2, slot, lane0, lane1, …) — a VALUE track's frame, synchronous from the host
+
+/** Playback control shared by element tweens and timelines. Times are **milliseconds**. */
+export interface Animation {
+  /** One iteration, ms. */
+  readonly duration: number
+  /** Position inside the current iteration, ms. Writable = seek. */
+  time: number
+  /** 0..1 of the whole animation (iterations included). Writable = seek. */
+  progress: number
+  /** Playback rate; negative runs backwards, 0 freezes. */
+  rate: number
+  readonly playing: boolean
+  /** Resolves `true` when the animation reaches its end, `false` when cancelled, replaced or replayed. Never rejects. */
+  readonly finished: Promise<boolean>
+  /** Start from t = 0 (a running animation restarts). */
+  play(): this
+  pause(): this
+  resume(): this
+  /** Jump to `ms`; playback state is unchanged. */
+  seek(ms: number): this
+  /** Jump to the end: values land, commits apply, `finished` resolves `true`. */
+  finish(): this
+  /** Stop where it is — no commit, `finished` resolves `false`. */
+  cancel(): this
+  onFinish(fn: (done: boolean) => void): this
+}
+
+const hasCore = (): boolean => typeof _creatorUI !== "undefined" && typeof (_creatorUI as any).tweenCreate === "function"
+
+// ---- host events -------------------------------------------------------------------------------
+
+const live = new Map<number, TweenAnimation>()
+let eventsRegistered = false
+const ensureEvents = (): void => {
+  if (eventsRegistered) return
+  eventsRegistered = true
+  ;(_creatorUI as any).registerTweenEvent?.(function (this: unknown, id: number, kind: number, index: number) {
+    const a = live.get(id)
+    if (!a) return
+    if (kind === EV_CALL) a._fireCall(index)
+    else if (kind === EV_FINISH) a._hostFinished()
+    else if (kind === EV_VALUE) {
+      // lanes ride as plain number arguments (no per-frame array on either side)
+      const n = arguments.length - 3
+      for (let i = 0; i < n; i++) valueScratch[i] = arguments[i + 3] as number
+      a._fireValue(index, valueScratch)
+    }
+  })
+}
+
+/** Reused lane buffer for VALUE deliveries (the host's largest kind is 10 lanes). */
+const valueScratch = new Float32Array(16)
+
+/** The concrete handle — what the SDK instantiates behind `animateTo` / `animateFrom` / `Timeline`.
+ *  User code sees the {@link Animation} interface; the class itself must stay in the public
+ *  declarations because `TimelineImpl` extends it — marking it internal (even mentioning the tag in
+ *  this comment: the strip is a substring match) drops the timeline's playback members. */
+export class TweenAnimation implements Animation {
+  /** @internal */
+  _spec: TweenSpec
+  /** @internal Time-callbacks by call index (the spec's `calls[i]`). */
+  _calls: Array<() => void> = []
+  /** @internal VALUE-track deliverers by slot (`animate()` / `Timeline.animate`). */
+  _values = new Map<number, (lanes: Float32Array) => void>()
+
+  private _id = 0                 // host id, 0 = not created
+  private _started = false        // play() ran at least once (the first play keeps the constructor's promise)
+  private _endTime = 0            // `time` after the host freed a finished animation
+  private _playing = false
+  private _rate: number
+  private _finished!: Promise<boolean>
+  private _resolve!: (done: boolean) => void
+  private _settled = true
+  private _listeners: Array<(done: boolean) => void> = []
+  private _fb?: Fallback
+
+  constructor(spec: TweenSpec) {
+    this._spec = spec
+    this._rate = spec.rate
+    this._newPromise()
+  }
+
+  private _newPromise(): void {
+    this._finished = new Promise<boolean>((r) => { this._resolve = r })
+    this._settled = false
+  }
+
+  private _settle(done: boolean): void {
+    if (this._settled) return
+    this._settled = true
+    this._playing = false
+    this._resolve(done)
+    for (const fn of this._listeners) fn(done)
+  }
+
+  get duration(): number { return this._spec.durationMs }
+  get playing(): boolean { return this._playing }
+  get finished(): Promise<boolean> { return this._finished }
+
+  get rate(): number { return this._rate }
+  set rate(r: number) {
+    this._rate = r
+    if (this._id) (_creatorUI as any).tweenSetRate(this._id, r)
+    this._fb?.setRate(r)
+  }
+
+  get time(): number {
+    if (this._id) return (_creatorUI as any).tweenGetTime?.(this._id) ?? 0
+    return this._fb?.time ?? this._endTime
+  }
+  set time(ms: number) { this.seek(ms) }
+
+  get progress(): number {
+    const total = this._totalMs()
+    return total > 0 ? Math.min(1, Math.max(0, this._elapsedMs() / total)) : 1
+  }
+  set progress(p: number) {
+    const total = this._totalMs()
+    this._seekTotal(Math.min(1, Math.max(0, p)) * total)
+  }
+
+  private _totalMs(): number {
+    const s = this._spec
+    const n = s.iterations < 0 ? 1 : s.iterations
+    return s.durationMs * n * (s.pingPong && s.iterations !== 1 ? 2 : 1)
+  }
+  private _elapsedMs(): number {
+    if (this._id) return (_creatorUI as any).tweenGetElapsed?.(this._id) ?? this.time
+    return this._fb?.elapsed ?? (this._endTime > 0 ? this._totalMs() : 0)
+  }
+  private _seekTotal(ms: number): void {
+    if (hasCore()) {
+      this._ensure()
+      ;(_creatorUI as any).tweenSeek(this._id, ms)
+    } else {
+      this._ensureFallback().seek(ms)
+    }
+  }
+
+  /** Create the host animation (paused at t = 0) if it doesn't exist. */
+  private _ensure(): void {
+    if (this._id) return
+    ensureEvents()
+    const blob = buildBlob(this._spec)
+    this._id = (_creatorUI as any).tweenCreate(blob.data, blob.strings, blob.targets)
+    if (this._id) live.set(this._id, this)
+    if (this._rate !== 1) (_creatorUI as any).tweenSetRate(this._id, this._rate)
+  }
+
+  private _destroy(): void {
+    if (this._id) {
+      live.delete(this._id)
+      ;(_creatorUI as any).tweenControl(this._id, OP_CANCEL)
+      this._id = 0
+    }
+    this._fb?.cancel()
+    this._fb = undefined
+  }
+
+  play(): this {
+    // A replay: whoever waited on the previous run gets `false` (unless it already ended), the host
+    // object is rebuilt (ids may have changed — a screen re-mounts its nodes on every open). The
+    // FIRST play keeps the promise handed out before it — unless a `cancel()` before any play has
+    // already settled that one, in which case this run gets a fresh promise.
+    if (this._started) {
+      this._settle(false)
+      this._destroy()
+    }
+    if (this._settled) this._newPromise()
+    this._started = true
+    this._endTime = 0
+    // Commit = the last keyframe becomes the stored state NOW (as `animateTo` always did), so reads
+    // and later `.style()` merges see the final state while the host is still tweening.
+    for (const t of this._spec.tracks) {
+      if (!t.commit || !t.channel.commit) continue
+      const last = t.keys[t.keys.length - 1]
+      if (last && last.value !== undefined) t.channel.commit(last.raw)
+    }
+    this._playing = true
+    if (hasCore()) {
+      this._ensure()
+      ;(_creatorUI as any).tweenControl(this._id, OP_PLAY)
+    } else {
+      this._ensureFallback().play()
+    }
+    return this
+  }
+
+  pause(): this {
+    if (hasCore()) { this._ensure(); (_creatorUI as any).tweenControl(this._id, OP_PAUSE) }
+    else this._ensureFallback().pause()
+    this._playing = false
+    return this
+  }
+
+  resume(): this {
+    if (this._settled) return this.play()
+    if (hasCore()) { this._ensure(); (_creatorUI as any).tweenControl(this._id, OP_RESUME) }
+    else this._ensureFallback().resume()
+    this._playing = true
+    return this
+  }
+
+  seek(ms: number): this {
+    // `time` is inside the current iteration; a seek by time on a looping animation stays in it.
+    const s = this._spec
+    const period = s.durationMs * (s.pingPong && s.iterations !== 1 ? 2 : 1)
+    const iter = period > 0 ? Math.floor(this._elapsedMs() / period) : 0
+    this._seekTotal(iter * period + Math.max(0, ms))
+    return this
+  }
+
+  finish(): this {
+    if (hasCore()) {
+      this._ensure()
+      ;(_creatorUI as any).tweenControl(this._id, OP_FINISH)   // the host answers with EV_FINISH
+    } else {
+      this._ensureFallback().finish()
+    }
+    return this
+  }
+
+  cancel(): this {
+    this._destroy()
+    this._settle(false)
+    return this
+  }
+
+  onFinish(fn: (done: boolean) => void): this {
+    this._listeners.push(fn)
+    return this
+  }
+
+  /** @internal */
+  _fireCall(index: number): void { this._calls[index]?.() }
+  /** @internal */
+  _fireValue(slot: number, lanes: Float32Array): void { this._values.get(slot)?.(lanes) }
+
+  /** @internal The host reached the end (naturally or via finish()) and has freed the animation. */
+  _hostFinished(): void {
+    if (this._id) { live.delete(this._id); this._id = 0 }
+    // the old-host path's timers / value loop must stop with the run, or an interval outlives it
+    if (this._fb) { this._fb.cancel(); this._fb = undefined }
+    this._endTime = this._spec.durationMs
+    this._settle(true)
+  }
+
+  // ---- old hosts ------------------------------------------------------------------------------
+
+  private _ensureFallback(): Fallback {
+    if (!this._fb) this._fb = new Fallback(this)
+    return this._fb
+  }
+}
+
+/** Old-host path: UI tracks go through the legacy `animateTo` / `animateFrom` pair (one value per
+ *  prop — the last explicit key for a to-tween, the first for a from-tween; no easing, no seek), a
+ *  track on any other domain is dropped with one warning, and the clock is a timer that fires the
+ *  calls and the finish. Good enough for the simple cases on web / Apple until their core lands. */
+class Fallback {
+  time = 0
+  elapsed = 0
+  private _timers: ReturnType<typeof setTimeout>[] = []
+  private _startedAt = 0
+  private _rate = 1
+  private _warned = false
+  private _loop?: ReturnType<typeof setInterval>
+  private _valueTracks: Track[] = []
+  private _scratch = new Float32Array(16)
+  private _lanes: number[] = []
+
+  private a: TweenAnimation
+  constructor(a: TweenAnimation) { this.a = a }
+
+  setRate(r: number): void { this._rate = r }
+
+  play(): void {
+    const s = this.a._spec
+    this.cancel()
+    this._startedAt = Date.now()
+    const byTarget = new Map<Track["target"], { to: Record<string, unknown>, from: Record<string, unknown>, at: number, dur: number, commit: boolean }>()
+    this._valueTracks = []
+    for (const t of s.tracks) {
+      if (t.channel.domain === DOM_VALUE) { this._valueTracks.push(t); continue }
+      if (t.channel.domain !== DOM_UI) {
+        if (!this._warned) { this._warned = true; console.warn("[tween] this host animates UI elements and values only (no tween core) — 3D / 2D tracks skipped") }
+        continue
+      }
+      const rec = byTarget.get(t.target) ?? { to: {}, from: {}, at: t.atMs, dur: t.durMs, commit: t.commit }
+      byTarget.set(t.target, rec)
+      const first = t.keys[0]!, last = t.keys[t.keys.length - 1]!
+      if (last.value === undefined) rec.from[t.prop] = first.raw          // animateFrom shape
+      else rec.to[t.prop] = last.raw
+      rec.at = Math.min(rec.at, t.atMs)
+      rec.dur = Math.max(rec.dur, t.durMs)
+    }
+    for (const [target, rec] of byTarget) {
+      // Sent even for an unmounted element (id 0), exactly as the direct call used to be — the host
+      // ignores it; a stub host in tests records it.
+      const id = ((target as any)._id as number) ?? 0
+      const delay = rec.at + s.delayMs
+      const meta: Record<string, unknown> = { duration: rec.dur }
+      if (delay > 0) meta.delay = delay
+      if (s.iterations !== 1) { meta.loop = s.iterations < 0 ? true : s.iterations; meta.loopMode = s.pingPong ? "ping-pong" : "restart" }
+      // The host merges its animate layer into base on commit (the SDK committed its own style already)
+      if (Object.keys(rec.to).length) _creatorUI.animateTo?.(id, { ...rec.to, ...meta, ...(rec.commit ? {} : { commit: false }) })
+      if (Object.keys(rec.from).length) _creatorUI.animateFrom?.(id, { ...rec.from, ...meta })
+    }
+    const scale = this._rate > 0 ? 1 / this._rate : 0
+    if (scale === 0) return
+    for (let i = 0; i < s.calls.length; i++) {
+      this._timers.push(setTimeout(() => this.a._fireCall(i), (s.delayMs + s.calls[i]!) * scale))
+    }
+    if (s.iterations === 1) {
+      this._timers.push(setTimeout(() => { this._applyValues(s.durationMs); this.elapsed = this.time = s.durationMs; this.a._hostFinished() }, (s.delayMs + s.durationMs) * scale))
+    }
+    // VALUE tracks are evaluated here in JS (the C evaluator's twin), ~60 times a second
+    if (this._valueTracks.length) {
+      this._applyValues(0)
+      this._loop = setInterval(() => {
+        const total = (Date.now() - this._startedAt) * this._rate - s.delayMs
+        if (total < 0) return
+        const period = s.durationMs * (s.pingPong && s.iterations !== 1 ? 2 : 1)
+        let local = period > 0 ? total % period : 0
+        if (s.iterations !== 1 && s.pingPong && local > s.durationMs) local = 2 * s.durationMs - local
+        if (s.iterations === 1) local = Math.min(total, s.durationMs)
+        this.elapsed = total
+        this.time = local
+        this._applyValues(local)
+      }, 16)
+    }
+  }
+  private _applyValues(local: number): void {
+    for (const t of this._valueTracks) {
+      evaluateTrack(t, local, this._lanes)
+      for (let i = 0; i < t.lanes; i++) this._scratch[i] = this._lanes[i]!
+      this.a._fireValue(t.channel.id() as number, this._scratch)
+    }
+  }
+  pause(): void { this.cancel() }
+  resume(): void { /* no partial resume on the timer clock: the tween already ran on the host */ }
+  seek(ms: number): void { this.elapsed = ms; this.time = ms % Math.max(1, this.a._spec.durationMs); this._applyValues(this.time) }
+  finish(): void { this.cancel(); this._applyValues(this.a._spec.durationMs); this.a._hostFinished() }
+  cancel(): void {
+    for (const t of this._timers) clearTimeout(t)
+    this._timers = []
+    if (this._loop !== undefined) { clearInterval(this._loop); this._loop = undefined }
+    if (this._startedAt) this.elapsed = this.time = Math.min(this.a._spec.durationMs, (Date.now() - this._startedAt) * this._rate)
+  }
+}
+
+/** @internal Build a one-bag animation for a single target (the `animateTo` / `animateFrom` path). */
+export const singleTargetSpec = (tracks: Track[], clock: number, iterations: number, pingPong: boolean, delayMs: number): TweenSpec => {
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  // `delay` lives on the tracks (the first key holds through it, §3.1); the spec delay is 0 here
+  return { clock, durationMs, delayMs, iterations, pingPong, rate: 1, tracks, calls: [] }
+}
+
+export { CLOCK_UI, CLOCK_GAME }

package/src/animate/tween/Timeline.ts

@@ -0,0 +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)
+}

package/src/animate/tween/animateValue.ts

@@ -0,0 +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()
+}