lecodes-sdk 1.1.0 → 2.0.0

package/src/animate/tween/Animation.ts

@@ -1,378 +1,262 @@
-// 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 }
+// 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 (`_creatorTree.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"
+import { DEAD_HANDLE, Pins } from "../../core/pins"
+
+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
+}
+
+
+// ---- host events -------------------------------------------------------------------------------
+
+/** The animations native owns right now (playing), by id — what the host's events resolve to. */
+const tweens = new Pins<TweenAnimation>()
+let eventsRegistered = false
+const ensureEvents = (): void => {
+  if (eventsRegistered) return
+  eventsRegistered = true
+  _creatorTree.registerTweenEvent(function (this: unknown, id: number, kind: number, index: number) {
+    const a = tweens.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>()
+
+  /** @internal The host animation's owned handle (DEAD_HANDLE while there is none). */
+  _h: Handle = DEAD_HANDLE
+  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> = []
+
+  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._h.id) _creatorTree.tweenSetRate(this._h.id, r)
+  }
+
+  get time(): number {
+    if (this._h.id) return _creatorTree.tweenGetTime(this._h.id)
+    return 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._h.id) return _creatorTree.tweenGetElapsed(this._h.id)
+    return this._endTime > 0 ? this._totalMs() : 0
+  }
+  private _seekTotal(ms: number): void {
+    this._ensure()
+    _creatorTree.tweenSeek(this._h.id, ms)
+  }
+
+  /** Create the host animation (paused at t = 0) if it doesn't exist. */
+  private _ensure(): void {
+    if (this._h.id) return
+    ensureEvents()
+    const blob = buildBlob(this._spec)
+    this._h = _creatorTree.tweenCreate(blob.data, blob.strings, blob.targets as number[]) ?? DEAD_HANDLE
+    if (this._h.id && this._rate !== 1) _creatorTree.tweenSetRate(this._h.id, this._rate)
+  }
+
+  private _destroy(): void {
+    if (this._h.id) {
+      tweens.unpin(this._h.id)
+      _creatorTree.tweenControl(this._h.id, OP_CANCEL)   // the runtime frees it; drop the handle too
+      this._h = DEAD_HANDLE
+    }
+  }
+
+  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
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_PLAY)
+    tweens.pin(this)   // playing: native owns it, its events must find it
+    return this
+  }
+
+  pause(): this {
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_PAUSE)
+    this._playing = false
+    tweens.unpin(this._h.id)   // paused: only the app's reference keeps it
+    return this
+  }
+
+  resume(): this {
+    if (this._settled) return this.play()
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_RESUME)
+    this._playing = true
+    tweens.pin(this)
+    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 {
+    this._ensure()
+    _creatorTree.tweenControl(this._h.id, OP_FINISH)   // the host answers with EV_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._h.id) { tweens.unpin(this._h.id); this._h = DEAD_HANDLE }   // the runtime freed it
+    this._endTime = this._spec.durationMs
+    this._settle(true)
+  }
+
+}
+
+/** @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 }