lecodes-sdk 1.1.0 → 2.0.0

package/src/animate/tween/spec.ts

@@ -1,479 +1,505 @@
-// The keyframe animation SPEC (docs/timeline-plan.md §4) and its wire form.
-//
-// An animation is a list of TRACKS — (target, prop) → keyframes — plus a clock, iteration and call
-// (time-callback) metadata. The SDK builds the spec from the flat options bags (`animateTo`,
-// `Timeline.add`), and `buildBlob` flattens it into ONE Float32Array + a string table at play time
-// (target ids are only known then: UI nodes get their id at mount, screens re-assign it on every
-// open). creator-pkg parses the blob into creator-tween's structures; the layout below is the
-// contract (creator-tween/include/creator-tween/blob.h mirrors it).
-//
-// Blob layout (all floats; ids and indices are exact below 2^24):
-//   header  [version=1, clock, durationMs, delayMs, iterations, pingPong, rate, nTracks, nCalls, nTables]
-//   calls   nCalls × [tMs]
-//   tables  nTables × EASE_TABLE_SIZE samples
-//   tracks  nTracks × ( [domain, targetIdx, propStr, kind, lanes, atMs, durMs, commit, nKeys, sigStr]
-//                       + nKeys × [t01, easeKind, e0, e1, e2, e3, has, lanes × value] )
-// `targetIdx` indexes the `targets` list handed over next to the floats (a host node handle is an
-// opaque object on creator-pkg hosts, a number elsewhere — it can't ride in a Float32Array).
-// A key with has = 0 carries no value: the evaluator CAPTURES the target's current value when the
-// animation first plays (the implicit first key of `animateTo`, the implicit last of `animateFrom`).
-// String-valued lanes (DISCRETE / STRING / TRANSFORM_MATRIX keys) hold a string-table index.
-
-import { EASE_TABLE_SIZE, evalEasing, parseEasing, type EasingInput, type EasingSpec } from "./easing"
-import { Color } from "../../core/color"
-import { Mat4 } from "../../math/mat4"
-
-export const BLOB_VERSION = 1
-
-// ---- domains (who the target is; creator-pkg maps each to a writer) ----------------------------
-export const DOM_UI = 0          // targetId = the element's host node id
-export const DOM_GL_NODE = 1     // targetId = entity: position / quaternion / eulerAngles / scale
-export const DOM_GL_LIGHT = 2    // targetId = entity: intensity / color
-export const DOM_GL_CAMERA = 3   // targetId = scene id: fov / near / far
-export const DOM_NODE2D = 4      // targetId = entity: x / y / position / rotation / scale
-export const DOM_SPRITE2D = 5    // targetId = entity: opacity / color
-export const DOM_VALUE = 6       // no engine target: the host hands the lanes back to JS — animate() / Timeline.animate; targetId = slot + 1
-
-// ---- value kinds ------------------------------------------------------------------------------
-export const KIND_FLOAT = 0            // 1 lane
-export const KIND_FLOAT_UNIT = 1       // 1 lane, sig = the unit ("px" | "%" | "vw" | "vh" | "deg" | "em")
-export const KIND_COLOR = 2            // 4 lanes r g b a in 0..1
-export const KIND_TRANSFORM = 3        // n lanes = the function list's args; sig = "translate,rotate,scale,…"
-export const KIND_TRANSFORM_MATRIX = 4 // 1 lane = string index of the raw transform; the host decomposes
-export const KIND_VEC3 = 5             // 3 lanes
-export const KIND_QUAT = 6             // 4 lanes, slerp
-export const KIND_EULER = 7            // 3 lanes, degrees, no shortest arc
-export const KIND_DISCRETE = 8         // 1 lane = string index, steps at the key
-export const KIND_STRING = 9           // 1 lane = string index; the UI host resolves: color prop → COLOR, else DISCRETE
-export const KIND_VEC2 = 10            // 2 lanes
-export const KIND_MAT4 = 11            // 10 lanes: position 3, quaternion 4 (slerp), scale 3 — a decomposed 4x4
-
-export const CLOCK_UI = 0
-export const CLOCK_GAME = 1
-
-/** Lane counts per kind (TRANSFORM is per-signature, see `transformLanes`). */
-const LANES: Record<number, number> = {
-  [KIND_FLOAT]: 1, [KIND_FLOAT_UNIT]: 1, [KIND_COLOR]: 4, [KIND_TRANSFORM_MATRIX]: 1,
-  [KIND_VEC3]: 3, [KIND_QUAT]: 4, [KIND_EULER]: 3, [KIND_DISCRETE]: 1, [KIND_STRING]: 1, [KIND_VEC2]: 2, [KIND_MAT4]: 10,
-}
-export const lanesOf = (kind: number): number => LANES[kind] ?? 1
-
-/** One normalized value: numeric lanes, or a string (string-lane kinds). */
-export type TweenValue = { lanes: number[] } | { str: string }
-
-/** A target's answer to "can you animate `prop`?": the writer domain, the id resolver, the value
- *  normalizer, and the commit hook (UI writes the last key into its stored style). */
-export type TweenChannel = {
-  domain: number,
-  /** Host handle at play time — a number (entity, web node id) or the host's opaque node object
-   *  (creator-pkg hands `_id` out as one); falsy = not addressable right now (unmounted), the
-   *  track is skipped. Handed to the host in the blob's `targets` list, never in the float data. */
-  id: () => unknown,
-  /** Normalize one keyframe value; `null` = not animatable (a warning, the value is committed only). */
-  value: (v: unknown) => ({ kind: number, sig?: string } & TweenValue) | null,
-  commit?: (v: unknown) => void,
-}
-
-/** Implemented by every animatable class (Element, Node, Node2D, Sprite, Light, Camera). */
-export interface TweenTarget {
-  /** @internal */
-  _tweenChannel(prop: string): TweenChannel | null
-  /** @internal Default clock for `animateTo` on this target. */
-  readonly _tweenClock: number
-}
-
-export type Keyframe = {
-  /** 0..1 within the track. */
-  t: number,
-  easing: EasingSpec,
-  /** `undefined` = capture at play. */
-  value?: TweenValue,
-  /** The bag value as written — what the old-host path forwards verbatim. */
-  raw?: unknown,
-}
-
-export type Track = {
-  target: TweenTarget,
-  prop: string,
-  channel: TweenChannel,
-  kind: number,
-  lanes: number,
-  sig?: string,
-  atMs: number,
-  durMs: number,
-  commit: boolean,
-  keys: Keyframe[],
-}
-
-export type TweenSpec = {
-  clock: number,
-  /** One iteration, ms — the last track's end (holds included). */
-  durationMs: number,
-  delayMs: number,
-  /** -1 = forever. */
-  iterations: number,
-  pingPong: boolean,
-  rate: number,
-  tracks: Track[],
-  /** Time-callbacks, ms; index = the event index the host reports. */
-  calls: number[],
-}
-
-// ---- the options bag -----------------------------------------------------------------------------
-
-/** Meta keys of an `animateTo` / `Timeline.add` bag — everything that is not a prop target. */
-export const TWEEN_META = new Set(["duration", "delay", "easing", "times", "loop", "loopMode", "commit", "clock", "layer", "at", "stagger"])
-
-export type TweenMeta = {
-  /** Tween length in **milliseconds** (default 225). */
-  duration?: number,
-  /** Wait before starting, **milliseconds**. The first keyframe holds through the wait. A loop delays once. */
-  delay?: number,
-  /** A curve for every prop, or a per-prop map (`{ width: 'outExpo', opacity: 'linear' }`). Names
-   *  (`outCubic`, `inOutSine`, `outBack`, …), `cubic-bezier(…)` / a `[x1, y1, x2, y2]` tuple,
-   *  `steps(n)`, or any `Easing` function. Default linear. */
-  easing?: EasingInput | Record<string, EasingInput>,
-  /** Keyframe offsets 0..1 for array-valued props (default: evenly spaced). */
-  times?: number[],
-  /** `true` = forever, a number = that many cycles. A loop never commits. */
-  loop?: boolean | number,
-  /** `"ping-pong"` (default) there and back each cycle; `"restart"` snaps back and replays. */
-  loopMode?: "restart" | "ping-pong",
-  /** `false` = animate without writing the last keyframe into the element's style. */
-  commit?: boolean,
-  /** `'ui'` = wall time (menus animate while the game is paused); `'game'` follows `Time.scale`.
-   *  Default: `'ui'` on UI elements, `'game'` on 3D / 2D nodes. */
-  clock?: "ui" | "game",
-  /** Legacy escape hatch (old hosts only). */
-  layer?: number,
-}
-
-export const DEFAULT_DURATION_MS = 225
-
-/** Warn once per (prop) about a value that cannot be animated — the bag is committed anyway. */
-const warned = new Set<string>()
-export const warnOnce = (key: string, msg: string): void => {
-  if (warned.has(key)) return
-  warned.add(key)
-  console.warn(`[tween] ${msg}`)
-}
-
-/** Resolve the per-prop easing from the bag. */
-export const easingFor = (easing: TweenMeta["easing"], prop: string): EasingSpec => {
-  if (easing !== undefined && typeof easing === "object" && !Array.isArray(easing) && typeof easing !== "function") {
-    return parseEasing((easing as Record<string, EasingInput>)[prop])
-  }
-  return parseEasing(easing as EasingInput | undefined)
-}
-
-/** Iteration count from `loop`: 1 = one-shot, -1 = forever, n = cycles. */
-export const iterationsOf = (loop: TweenMeta["loop"]): number => {
-  if (loop === true) return -1
-  if (typeof loop === "number" && loop > 0) return Math.floor(loop)
-  return 1
-}
-
-// ---- value normalizers shared by the domains ----------------------------------------------------
-
-const UNIT_RE = /^\s*(-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*(px|%|vw|vh|vmin|vmax|deg|rad|em|rem)?\s*$/i
-
-/** A UI style value: number → FLOAT; "12px" / "50%" → FLOAT_UNIT; other strings → STRING (the host
- *  decides color vs discrete); booleans → DISCRETE. */
-export const uiValue = (v: unknown): ({ kind: number, sig?: string } & TweenValue) | null => {
-  if (typeof v === "number") return { kind: KIND_FLOAT, lanes: [v] }
-  if (typeof v === "boolean") return { kind: KIND_DISCRETE, str: v ? "true" : "false" }
-  if (typeof v === "string") {
-    const m = UNIT_RE.exec(v)
-    if (m) {
-      const unit = (m[2] ?? "").toLowerCase()
-      return unit === "" || unit === "px"
-        ? { kind: KIND_FLOAT, lanes: [parseFloat(m[1]!)] }
-        : { kind: KIND_FLOAT_UNIT, sig: unit, lanes: [parseFloat(m[1]!)] }
-    }
-    return { kind: KIND_STRING, str: v }
-  }
-  return null
-}
-
-/** Per-function argument counts of a UI transform list (degrees / px are the SDK's units). */
-const TRANSFORM_FNS: Record<string, number> = {
-  translate: 2, translateX: 1, translateY: 1, rotate: 1, scale: 2, scaleX: 1, scaleY: 1, skewX: 1, skewY: 1,
-}
-
-/** Parse `"translate(10px, 20px) rotate(45deg) scale(1.2)"` into a signature + lanes, or null when a
- *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
- *  `translate(5px)` complete their second argument like CSS. */
-export const parseTransformList = (s: string): { sig: string, lanes: number[] } | null => {
-  const sig: string[] = []
-  const lanes: number[] = []
-  const re = /([a-zA-Z]+)\s*\(([^)]*)\)/g
-  let m: RegExpExecArray | null
-  let consumed = 0
-  const src = s.trim()
-  if (src === "" || src === "none") return { sig: "", lanes: [] }
-  while ((m = re.exec(src)) !== null) {
-    const fn = m[1]!
-    const n = TRANSFORM_FNS[fn]
-    if (n === undefined) return null
-    const args = m[2]!.split(",").map((a) => {
-      const u = UNIT_RE.exec(a)
-      return u ? parseFloat(u[1]!) : NaN
-    })
-    if (args.some((a) => Number.isNaN(a)) || args.length === 0 || args.length > n) return null
-    if (args.length < n) args.push(fn === "translate" ? 0 : args[0]!)
-    sig.push(fn)
-    lanes.push(...args)
-    consumed = re.lastIndex
-  }
-  if (src.slice(consumed).trim() !== "") return null
-  return { sig: sig.join(","), lanes }
-}
-
-export const transformLanes = (sig: string): number => (sig === "" ? 0 : sig.split(",").reduce((n, fn) => n + (TRANSFORM_FNS[fn] ?? 0), 0))
-
-const num3 = (v: unknown): number[] | null => {
-  if (typeof v === "number") return [v, v, v]
-  if (v && typeof v === "object") {
-    const o = v as any
-    if (typeof o.length === "number" && o.length >= 3) return [+o[0], +o[1], +o[2]]
-    if (typeof o.x === "number") return [o.x, o.y, o.z]
-  }
-  return null
-}
-
-const num4 = (v: unknown): number[] | null => {
-  if (v && typeof v === "object") {
-    const o = v as any
-    if (typeof o.length === "number" && o.length >= 4) return [+o[0], +o[1], +o[2], +o[3]]
-    if (typeof o.x === "number" && typeof o.w === "number") return [o.x, o.y, o.z, o.w]
-  }
-  return null
-}
-
-const num2 = (v: unknown): number[] | null => {
-  if (typeof v === "number") return [v, v]
-  if (v && typeof v === "object") {
-    const o = v as any
-    if (typeof o.length === "number" && o.length >= 2) return [+o[0], +o[1]]
-    if (typeof o.x === "number") return [o.x, o.y]
-  }
-  return null
-}
-
-export const vec3Value = (v: unknown) => { const l = num3(v); return l ? { kind: KIND_VEC3, lanes: l } : null }
-export const quatValue = (v: unknown) => { const l = num4(v); return l ? { kind: KIND_QUAT, lanes: l } : null }
-export const eulerValue = (v: unknown) => { const l = num3(v); return l ? { kind: KIND_EULER, lanes: l } : null }
-export const vec2Value = (v: unknown) => { const l = num2(v); return l ? { kind: KIND_VEC2, lanes: l } : null }
-export const floatValue = (v: unknown) => (typeof v === "number" ? { kind: KIND_FLOAT, lanes: [v] } : null)
-export const colorValue = (v: unknown, toRgba: (c: any) => [number, number, number, number]) => {
-  if (typeof v === "string" || typeof v === "number" || Array.isArray(v)) return { kind: KIND_COLOR, lanes: toRgba(v) }
-  return null
-}
-
-/** A free value for animate(): number → FLOAT, a color string → COLOR, arrays / vectors by length
- *  (2 → VEC2, 3 → VEC3, 4 → QUAT, 16 → MAT4 decomposed into position · quaternion · scale). */
-export const valueValue = (v: unknown): ({ kind: number } & TweenValue) | null => {
-  if (typeof v === "number") return { kind: KIND_FLOAT, lanes: [v] }
-  if (typeof v === "string") return { kind: KIND_COLOR, lanes: Color.toRgba01(v) }
-  if (v && typeof v === "object") {
-    const o = v as any
-    const arr: ArrayLike<number> | undefined = typeof o.length === "number" ? o : Array.isArray(o.m) && o.m.length === 16 ? o.m : undefined
-    if (arr) {
-      if (arr.length === 2) return { kind: KIND_VEC2, lanes: [+arr[0]!, +arr[1]!] }
-      if (arr.length === 3) return { kind: KIND_VEC3, lanes: [+arr[0]!, +arr[1]!, +arr[2]!] }
-      if (arr.length === 4) return { kind: KIND_QUAT, lanes: [+arr[0]!, +arr[1]!, +arr[2]!, +arr[3]!] }
-      if (arr.length === 16) {
-        const d = new Mat4(arr as any).decompose()
-        return { kind: KIND_MAT4, lanes: [d.position.x, d.position.y, d.position.z, d.rotation.x, d.rotation.y, d.rotation.z, d.rotation.w, d.scale.x, d.scale.y, d.scale.z] }
-      }
-      return null
-    }
-    if (typeof o.x === "number") {
-      if (typeof o.w === "number") return { kind: KIND_QUAT, lanes: [o.x, o.y, o.z, o.w] }
-      if (typeof o.z === "number") return { kind: KIND_VEC3, lanes: [o.x, o.y, o.z] }
-      return { kind: KIND_VEC2, lanes: [o.x, o.y] }
-    }
-  }
-  return null
-}
-
-/** Is this bag value a KEYFRAME ARRAY for a vector prop, as opposed to one vector? A vector value
- *  is an array of NUMBERS (`[0, 2, 0]`); anything else in the array is a list of keyframes —
- *  `[[0,0,0], [0,2,0]]`, `[new Vec3(), …]`, and the UI's `color: ['#fff', '#e29a22']`. */
-export const isVectorKeyframes = (v: unknown): boolean =>
-  Array.isArray(v) && v.length > 0 && typeof v[0] !== "number"
-
-// ---- track construction ------------------------------------------------------------------------
-
-/** Build one track's keyframes from a bag value: a single value = one explicit key (the other end
- *  captured), an array = explicit keys spaced by `times` or evenly. `fromCurrent` says which end is
- *  implicit (animateTo: the first; animateFrom: the last). Returns null when a value can't be
- *  animated (already warned). */
-export const makeTrack = (
-  target: TweenTarget, prop: string, raw: unknown, meta: TweenMeta, atMs: number, fromCurrent: boolean, vectorProp: boolean,
-): Track | null => {
-  const channel = target._tweenChannel(prop)
-  if (!channel) {
-    warnOnce(`prop:${prop}`, `"${prop}" is not animatable on this target — set it directly`)
-    return null
-  }
-  const values: unknown[] = Array.isArray(raw) && (!vectorProp || isVectorKeyframes(raw)) ? raw : [raw]
-  const easing = easingFor(meta.easing, prop)
-  const norm = values.map((v) => channel.value(v))
-  if (norm.some((n) => n === null)) {
-    warnOnce(`value:${prop}`, `"${prop}" got a value that cannot be animated — set it directly`)
-    return null
-  }
-  const ns = norm as NonNullable<(typeof norm)[number]>[]
-
-  // One kind per track. Mismatched units / transform signatures degrade to DISCRETE (a flip at the
-  // key, like CSS), never to garbage interpolation.
-  let kind = ns[0]!.kind
-  let sig = ns[0]!.sig
-  for (const n of ns) {
-    if (n.kind !== kind || n.sig !== sig) {
-      // FLOAT vs FLOAT_UNIT(px) can't happen (px normalizes to FLOAT); anything else is discrete
-      kind = KIND_DISCRETE
-      sig = undefined
-      break
-    }
-  }
-  const lanes = kind === KIND_TRANSFORM ? transformLanes(sig ?? "") : LANES[kind]!
-  const toValue = (n: NonNullable<(typeof norm)[number]>): TweenValue =>
-    kind === KIND_DISCRETE && "lanes" in n ? { str: String(n.lanes[0]) } : ("str" in n ? { str: n.str } : { lanes: n.lanes })
-
-  const explicit = ns.length
-  const total = explicit + (explicit === 1 ? 1 : 0)   // a single value pairs with a captured end
-  const keys: Keyframe[] = []
-  const times = meta.times
-  for (let i = 0; i < total; i++) {
-    let t: number
-    if (times && times.length === total) t = times[i]!
-    else t = total === 1 ? 1 : i / (total - 1)
-    let value: TweenValue | undefined
-    let raw: unknown
-    if (explicit === 1) {
-      // animateTo: [captured, v]; animateFrom: [v, captured]
-      const isExplicit = fromCurrent ? i === 1 : i === 0
-      value = isExplicit ? toValue(ns[0]!) : undefined
-      raw = isExplicit ? values[0] : undefined
-    } else {
-      value = toValue(ns[i]!)
-      raw = values[i]
-    }
-    keys.push({ t, easing, value, raw })
-  }
-  // animateFrom with an explicit array: the element's own style is the implicit LAST key
-  if (!fromCurrent && explicit > 1) {
-    for (const k of keys) k.t *= (total) / (total + 1)
-    keys.push({ t: 1, easing, value: undefined })
-  }
-
-  return {
-    target, prop, channel, kind, lanes, sig,
-    atMs: atMs + (meta.delay ?? 0),
-    durMs: Math.max(0, meta.duration ?? DEFAULT_DURATION_MS),
-    // animateFrom never commits (its last key is the element's own state); loops never commit
-    commit: fromCurrent && meta.commit !== false && iterationsOf(meta.loop) === 1,
-    keys,
-  }
-}
-
-/** Every (prop → value) entry of a bag, meta keys stripped. */
-export const bagProps = (bag: Record<string, unknown>): [string, unknown][] =>
-  Object.entries(bag).filter(([k, v]) => !TWEEN_META.has(k) && v !== undefined)
-
-// ---- JS evaluation (the old-host path of VALUE tracks; the C evaluator is the reference) ----------
-
-const slerpInto = (out: number[], o: number, a: number[], ai: number, b: number[], bi: number, s: number): void => {
-  let bx = b[bi]!, by = b[bi + 1]!, bz = b[bi + 2]!, bw = b[bi + 3]!
-  let cosom = a[ai]! * bx + a[ai + 1]! * by + a[ai + 2]! * bz + a[ai + 3]! * bw
-  if (cosom < 0) { cosom = -cosom; bx = -bx; by = -by; bz = -bz; bw = -bw }
-  let k0: number, k1: number
-  if (1 - cosom > 1e-6) {
-    const omega = Math.acos(Math.min(1, cosom)), sinom = Math.sin(omega)
-    k0 = Math.sin((1 - s) * omega) / sinom
-    k1 = Math.sin(s * omega) / sinom
-  } else { k0 = 1 - s; k1 = s }
-  out[o] = k0 * a[ai]! + k1 * bx; out[o + 1] = k0 * a[ai + 1]! + k1 * by; out[o + 2] = k0 * a[ai + 2]! + k1 * bz; out[o + 3] = k0 * a[ai + 3]! + k1 * bw
-}
-
-/** The value of a numeric track at local time `ms` (the C evaluator's rule: first key holds before,
- *  last after; eased segment between). `out` receives `track.lanes` numbers. */
-export const evaluateTrack = (track: Track, ms: number, out: number[]): void => {
-  const u = track.durMs <= 0 ? (ms >= track.atMs ? 1 : 0) : Math.min(1, Math.max(0, (ms - track.atMs) / track.durMs))
-  const keys = track.keys
-  const lanesOfKey = (k: Keyframe): number[] => (k.value && "lanes" in k.value ? k.value.lanes : [])
-  if (keys.length === 0) return
-  if (u <= keys[0]!.t || keys.length === 1) { const l = lanesOfKey(keys[0]!); for (let i = 0; i < track.lanes; i++) out[i] = l[i] ?? 0; return }
-  const last = keys[keys.length - 1]!
-  if (u >= last.t) { const l = lanesOfKey(last); for (let i = 0; i < track.lanes; i++) out[i] = l[i] ?? 0; return }
-  let i = 0
-  while (i + 1 < keys.length && keys[i + 1]!.t <= u) i++
-  const a = keys[i]!, b = keys[i + 1]!
-  const span = b.t - a.t
-  const s = evalEasing(a.easing, span > 0 ? (u - a.t) / span : 1)
-  const la = lanesOfKey(a), lb = lanesOfKey(b)
-  if (track.kind === KIND_QUAT) { slerpInto(out, 0, la, 0, lb, 0, s); return }
-  if (track.kind === KIND_MAT4) {
-    for (let k = 0; k < 3; k++) out[k] = la[k]! + (lb[k]! - la[k]!) * s
-    slerpInto(out, 3, la, 3, lb, 3, s)
-    for (let k = 7; k < 10; k++) out[k] = la[k]! + (lb[k]! - la[k]!) * s
-    return
-  }
-  for (let k = 0; k < track.lanes; k++) out[k] = (la[k] ?? 0) + ((lb[k] ?? 0) - (la[k] ?? 0)) * s
-}
-
-// ---- the blob ----------------------------------------------------------------------------------
-
-export type TweenBlob = { data: Float32Array, strings: string[], targets: unknown[] }
-
-/** Flatten a spec for `_creatorUI.tweenCreate`. Tracks whose target has no host id right now are
- *  dropped (the animation still runs its clock, calls and finish). */
-export const buildBlob = (spec: TweenSpec): TweenBlob => {
-  const strings: string[] = []
-  const strIndex = new Map<string, number>()
-  const str = (s: string): number => {
-    let i = strIndex.get(s)
-    if (i === undefined) { i = strings.length; strings.push(s); strIndex.set(s, i) }
-    return i
-  }
-  const tables: Float32Array[] = []
-  const tableIndex = (e: EasingSpec): number => {
-    const i = tables.indexOf(e.table!)
-    if (i >= 0) return i
-    tables.push(e.table!)
-    return tables.length - 1
-  }
-
-  const tracks = spec.tracks.map((t) => ({ t, id: t.channel.id() })).filter((x) => !!x.id)
-  const targets: unknown[] = []
-  const targetIndex = (id: unknown): number => {
-    let i = targets.indexOf(id)
-    if (i < 0) { i = targets.length; targets.push(id) }
-    return i
-  }
-  const out: number[] = []
-  out.push(BLOB_VERSION, spec.clock, spec.durationMs, spec.delayMs, spec.iterations, spec.pingPong ? 1 : 0, spec.rate,
-    tracks.length, spec.calls.length, 0 /* nTables, patched */)
-  for (const c of spec.calls) out.push(c)
-  const tablesAt = out.length
-  for (const { t, id } of tracks) {
-    out.push(t.channel.domain, targetIndex(id), str(t.prop), t.kind, t.lanes, t.atMs, t.durMs, t.commit ? 1 : 0, t.keys.length, t.sig !== undefined ? str(t.sig) : -1)
-    for (const k of t.keys) {
-      const e = k.easing
-      const p: number[] = [e.p[0], e.p[1], e.p[2], e.p[3]]
-      if (e.table) p[0] = tableIndex(e)
-      out.push(k.t, e.kind, p[0]!, p[1]!, p[2]!, p[3]!, k.value ? 1 : 0)
-      if (!k.value) { for (let i = 0; i < t.lanes; i++) out.push(0) }
-      else if ("str" in k.value) { out.push(str(k.value.str)); for (let i = 1; i < t.lanes; i++) out.push(0) }
-      else { for (let i = 0; i < t.lanes; i++) out.push(k.value.lanes[i] ?? 0) }
-    }
-  }
-  // splice the tables in after the calls
-  const tableData: number[] = []
-  for (const tb of tables) for (let i = 0; i < EASE_TABLE_SIZE; i++) tableData.push(tb[i]!)
-  out.splice(tablesAt, 0, ...tableData)
-  out[9] = tables.length
-  return { data: Float32Array.from(out), strings, targets }
-}
+// The keyframe animation SPEC (docs/timeline-plan.md §4) and its wire form.
+//
+// An animation is a list of TRACKS — (target, prop) → keyframes — plus a clock, iteration and call
+// (time-callback) metadata. The SDK builds the spec from the flat options bags (`animateTo`,
+// `Timeline.add`), and `buildBlob` flattens it into ONE Float32Array + a string table at play time
+// (target ids are only known then: UI nodes get their id at mount, screens re-assign it on every
+// open). creator-pkg parses the blob into creator-tween's structures; the layout below is the
+// contract (creator-tween/include/creator-tween/blob.h mirrors it).
+//
+// Blob layout (all floats; ids and indices are exact below 2^24):
+//   header  [version=1, clock, durationMs, delayMs, iterations, pingPong, rate, nTracks, nCalls, nTables]
+//   calls   nCalls × [tMs]
+//   tables  nTables × EASE_TABLE_SIZE samples
+//   tracks  nTracks × ( [domain, targetIdx, propStr, kind, lanes, atMs, durMs, commit, nKeys, sigStr]
+//                       + nKeys × [t01, easeKind, e0, e1, e2, e3, has, lanes × value] )
+// `targetIdx` indexes the `targets` list handed over next to the floats (a host node handle is an
+// opaque object on creator-pkg hosts, a number elsewhere — it can't ride in a Float32Array).
+// A key with has = 0 carries no value: the evaluator CAPTURES the target's current value when the
+// animation first plays (the implicit first key of `animateTo`, the implicit last of `animateFrom`).
+// String-valued lanes (DISCRETE / STRING / TRANSFORM_MATRIX keys) hold a string-table index.
+
+import { DEFAULT_EASING, EASE_TABLE_SIZE, evalEasing, parseEasing, type EasingInput, type EasingSpec } from "./easing"
+import { Color } from "../../core/color"
+import { Mat4 } from "../../math/mat4"
+
+export const BLOB_VERSION = 1
+
+// ---- domains (who the target is; creator-pkg maps each to a writer) ----------------------------
+export const DOM_UI = 0          // targetId = the element's host node id
+export const DOM_GL_NODE = 1     // targetId = entity: position / quaternion / eulerAngles / scale
+export const DOM_GL_LIGHT = 2    // targetId = entity: intensity / color
+export const DOM_GL_CAMERA = 3   // targetId = scene id: fov / near / far
+export const DOM_NODE2D = 4      // targetId = entity: x / y / position / rotation / scale
+export const DOM_SPRITE2D = 5    // targetId = entity: opacity / color
+export const DOM_VALUE = 6       // no engine target: the host hands the lanes back to JS — animate() / Timeline.animate; targetId = slot + 1
+
+// ---- value kinds ------------------------------------------------------------------------------
+export const KIND_FLOAT = 0            // 1 lane
+export const KIND_FLOAT_UNIT = 1       // 1 lane, sig = the unit ("px" | "%" | "vw" | "vh" | "deg" | "em")
+export const KIND_COLOR = 2            // 4 lanes r g b a in 0..1
+export const KIND_TRANSFORM = 3        // n lanes = the function list's args; sig = "translate,rotate,scale,…"
+export const KIND_TRANSFORM_MATRIX = 4 // 1 lane = string index of the raw transform; the host decomposes
+export const KIND_VEC3 = 5             // 3 lanes
+export const KIND_QUAT = 6             // 4 lanes, slerp
+export const KIND_EULER = 7            // 3 lanes, degrees, no shortest arc
+export const KIND_DISCRETE = 8         // 1 lane = string index, steps at the key
+export const KIND_STRING = 9           // 1 lane = string index; the UI host resolves: color prop → COLOR, else DISCRETE
+export const KIND_VEC2 = 10            // 2 lanes
+export const KIND_MAT4 = 11            // 10 lanes: position 3, quaternion 4 (slerp), scale 3 — a decomposed 4x4
+
+export const CLOCK_UI = 0
+export const CLOCK_GAME = 1
+
+/** Lane counts per kind (TRANSFORM is per-signature, see `transformLanes`). */
+const LANES: Record<number, number> = {
+  [KIND_FLOAT]: 1, [KIND_FLOAT_UNIT]: 1, [KIND_COLOR]: 4, [KIND_TRANSFORM_MATRIX]: 1,
+  [KIND_VEC3]: 3, [KIND_QUAT]: 4, [KIND_EULER]: 3, [KIND_DISCRETE]: 1, [KIND_STRING]: 1, [KIND_VEC2]: 2, [KIND_MAT4]: 10,
+}
+export const lanesOf = (kind: number): number => LANES[kind] ?? 1
+
+/** One normalized value: numeric lanes, or a string (string-lane kinds). */
+export type TweenValue = { lanes: number[] } | { str: string }
+
+/** A target's answer to "can you animate `prop`?": the writer domain, the id resolver, the value
+ *  normalizer, and the commit hook (UI writes the last key into its stored style). */
+export type TweenChannel = {
+  domain: number,
+  /** Host handle at play time — a number (entity, web node id) or the host's opaque node object
+   *  (creator-pkg hands `_id` out as one); falsy = not addressable right now (unmounted), the
+   *  track is skipped. Handed to the host in the blob's `targets` list, never in the float data. */
+  id: () => unknown,
+  /** Normalize one keyframe value; `null` = not animatable (a warning, the value is committed only). */
+  value: (v: unknown) => ({ kind: number, sig?: string } & TweenValue) | null,
+  commit?: (v: unknown) => void,
+}
+
+/** Implemented by every animatable class (Element, Node, Node2D, Sprite, Light, Camera). */
+export interface TweenTarget {
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null
+  /** @internal Default clock for `animateTo` on this target. */
+  readonly _tweenClock: number
+}
+
+export type Keyframe = {
+  /** 0..1 within the track. */
+  t: number,
+  easing: EasingSpec,
+  /** `undefined` = capture at play. */
+  value?: TweenValue,
+  /** The bag value as written — what the old-host path forwards verbatim. */
+  raw?: unknown,
+}
+
+export type Track = {
+  target: TweenTarget,
+  prop: string,
+  channel: TweenChannel,
+  kind: number,
+  lanes: number,
+  sig?: string,
+  atMs: number,
+  durMs: number,
+  commit: boolean,
+  keys: Keyframe[],
+}
+
+export type TweenSpec = {
+  clock: number,
+  /** One iteration, ms — the last track's end (holds included). */
+  durationMs: number,
+  delayMs: number,
+  /** -1 = forever. */
+  iterations: number,
+  pingPong: boolean,
+  rate: number,
+  tracks: Track[],
+  /** Time-callbacks, ms; index = the event index the host reports. */
+  calls: number[],
+}
+
+// ---- the options bag -----------------------------------------------------------------------------
+
+/** Meta keys of an `animateTo` / `Timeline.add` bag — everything that is not a prop target. */
+export const TWEEN_META = new Set(["duration", "delay", "easing", "times", "loop", "loopMode", "commit", "clock", "layer", "at", "stagger"])
+
+export type TweenMeta = {
+  /** Tween length in **milliseconds** (default 225). */
+  duration?: number,
+  /** Wait before starting, **milliseconds**. The first keyframe holds through the wait. A loop delays once. */
+  delay?: number,
+  /** A curve for every prop, or a per-prop map (`{ width: 'outExpo', opacity: 'linear' }`). Names
+   *  (`outCubic`, `inOutSine`, `outBack`, …), `cubic-bezier(…)` / a `[x1, y1, x2, y2]` tuple,
+   *  `steps(n)`, or any `Easing` function. Default `ease-in-out` (cubic-bezier(0.42, 0, 0.58, 1),
+   *  the curve UIKit and CSS transitions ease with); `"linear"` for uniform motion. */
+  easing?: EasingInput | Record<string, EasingInput>,
+  /** Keyframe offsets 0..1 for array-valued props (default: evenly spaced). */
+  times?: number[],
+  /** `true` = forever, a number = that many cycles. A loop never commits. */
+  loop?: boolean | number,
+  /** `"ping-pong"` (default) there and back each cycle; `"restart"` snaps back and replays. */
+  loopMode?: "restart" | "ping-pong",
+  /** `false` = animate without writing the last keyframe into the element's style. */
+  commit?: boolean,
+  /** `'ui'` = wall time (menus animate while the game is paused); `'game'` follows `Time.scale`.
+   *  Default: `'ui'` on UI elements, `'game'` on 3D / 2D nodes. */
+  clock?: "ui" | "game",
+  /** Legacy escape hatch (old hosts only). */
+  layer?: number,
+}
+
+export const DEFAULT_DURATION_MS = 225
+
+/** Warn once per (prop) about a value that cannot be animated — the bag is committed anyway. */
+const warned = new Set<string>()
+export const warnOnce = (key: string, msg: string): void => {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[tween] ${msg}`)
+}
+
+/** Resolve the per-prop easing from the bag; nothing given (or no entry for `prop` in a per-prop
+ *  map) = `fallback` — the tracks' DEFAULT_EASING, linear for a value tween. */
+export const easingFor = (easing: TweenMeta["easing"], prop: string, fallback: EasingSpec = DEFAULT_EASING): EasingSpec => {
+  const one = easing !== undefined && typeof easing === "object" && !Array.isArray(easing) && typeof easing !== "function"
+    ? (easing as Record<string, EasingInput>)[prop]
+    : easing as EasingInput | undefined
+  return one === undefined ? fallback : parseEasing(one)
+}
+
+/** Iteration count from `loop`: 1 = one-shot, -1 = forever, n = cycles. */
+export const iterationsOf = (loop: TweenMeta["loop"]): number => {
+  if (loop === true) return -1
+  if (typeof loop === "number" && loop > 0) return Math.floor(loop)
+  return 1
+}
+
+// ---- value normalizers shared by the domains ----------------------------------------------------
+
+const UNIT_RE = /^\s*(-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*(px|%|vw|vh|vmin|vmax|deg|rad|em|rem)?\s*$/i
+
+/** A UI style value: number → FLOAT; "12px" / "50%" → FLOAT_UNIT; other strings → STRING (the host
+ *  decides color vs discrete); booleans → DISCRETE. The element hands over the WIRE value
+ *  (UINode._tweenChannel): a color key arrives as a string, never a packed number. */
+export const uiValue = (v: unknown): ({ kind: number, sig?: string } & TweenValue) | null => {
+  if (typeof v === "number") return { kind: KIND_FLOAT, lanes: [v] }
+  if (typeof v === "boolean") return { kind: KIND_DISCRETE, str: v ? "true" : "false" }
+  if (typeof v === "string") {
+    const m = UNIT_RE.exec(v)
+    if (m) {
+      const unit = (m[2] ?? "").toLowerCase()
+      return unit === "" || unit === "px"
+        ? { kind: KIND_FLOAT, lanes: [parseFloat(m[1]!)] }
+        : { kind: KIND_FLOAT_UNIT, sig: unit, lanes: [parseFloat(m[1]!)] }
+    }
+    return { kind: KIND_STRING, str: v }
+  }
+  return null
+}
+
+/** Per-function argument counts of a UI transform list (degrees / px are the SDK's units). A
+ *  translate named with a trailing `%` holds PERCENTS of the target's own box — a screen
+ *  transition's pose (ui/transitions.ts), the only place that writes one. */
+const TRANSFORM_FNS: Record<string, number> = {
+  translate: 2, translateX: 1, translateY: 1, rotate: 1, scale: 2, scaleX: 1, scaleY: 1, skewX: 1, skewY: 1,
+  "translate%": 2, "translateX%": 1, "translateY%": 1,
+}
+
+/** Parse `"translate(10px, 20px) rotate(45deg) scale(1.2)"` into a signature + lanes, or null when a
+ *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
+ *  `translate(5px)` complete their second argument like CSS.
+ *
+ *  `percent`: a `%` in a translate is a percent of the target's box (`translateX(100%)` →
+ *  `translateX%` [100]; a translate mixing the units splits into its two axes). Without it a `%`
+ *  reads as px, as the style's own parser reads it — with a warning: only a screen transition
+ *  measures a translate in percents. */
+export const parseTransformList = (s: string, percent = false): { sig: string, lanes: number[] } | null => {
+  const sig: string[] = []
+  const lanes: number[] = []
+  const re = /([a-zA-Z]+)\s*\(([^)]*)\)/g
+  let m: RegExpExecArray | null
+  let consumed = 0
+  const src = s.trim()
+  if (src === "" || src === "none") return { sig: "", lanes: [] }
+  while ((m = re.exec(src)) !== null) {
+    const fn = m[1]!
+    const n = TRANSFORM_FNS[fn]
+    if (n === undefined) return null
+    const units: string[] = []
+    const args = m[2]!.split(",").map((a) => {
+      const u = UNIT_RE.exec(a)
+      units.push(u ? (u[2] ?? "") : "")
+      return u ? parseFloat(u[1]!) : NaN
+    })
+    if (args.some((a) => Number.isNaN(a)) || args.length === 0 || args.length > n) return null
+    if (args.length < n) { args.push(fn === "translate" ? 0 : args[0]!); units.push(units[0]!) }
+    consumed = re.lastIndex
+    if (fn.startsWith("translate") && units.includes("%")) {
+      if (!percent) {
+        warnOnce("transform:%", `transform: a % in ${fn}() is read as px — percents of the box work in a screen transition only`)
+      } else if (fn === "translate" && units[0] !== units[1]) {
+        sig.push(units[0] === "%" ? "translateX%" : "translateX", units[1] === "%" ? "translateY%" : "translateY")
+        lanes.push(...args)
+        continue
+      } else {
+        sig.push(fn + "%")
+        lanes.push(...args)
+        continue
+      }
+    }
+    sig.push(fn)
+    lanes.push(...args)
+  }
+  if (src.slice(consumed).trim() !== "") return null
+  return { sig: sig.join(","), lanes }
+}
+
+export const transformLanes = (sig: string): number => (sig === "" ? 0 : sig.split(",").reduce((n, fn) => n + (TRANSFORM_FNS[fn] ?? 0), 0))
+
+const num3 = (v: unknown): number[] | null => {
+  if (typeof v === "number") return [v, v, v]
+  if (v && typeof v === "object") {
+    const o = v as any
+    if (typeof o.length === "number" && o.length >= 3) return [+o[0], +o[1], +o[2]]
+    if (typeof o.x === "number") return [o.x, o.y, o.z]
+  }
+  return null
+}
+
+const num4 = (v: unknown): number[] | null => {
+  if (v && typeof v === "object") {
+    const o = v as any
+    if (typeof o.length === "number" && o.length >= 4) return [+o[0], +o[1], +o[2], +o[3]]
+    if (typeof o.x === "number" && typeof o.w === "number") return [o.x, o.y, o.z, o.w]
+  }
+  return null
+}
+
+const num2 = (v: unknown): number[] | null => {
+  if (typeof v === "number") return [v, v]
+  if (v && typeof v === "object") {
+    const o = v as any
+    if (typeof o.length === "number" && o.length >= 2) return [+o[0], +o[1]]
+    if (typeof o.x === "number") return [o.x, o.y]
+  }
+  return null
+}
+
+export const vec3Value = (v: unknown) => { const l = num3(v); return l ? { kind: KIND_VEC3, lanes: l } : null }
+export const quatValue = (v: unknown) => { const l = num4(v); return l ? { kind: KIND_QUAT, lanes: l } : null }
+export const eulerValue = (v: unknown) => { const l = num3(v); return l ? { kind: KIND_EULER, lanes: l } : null }
+export const vec2Value = (v: unknown) => { const l = num2(v); return l ? { kind: KIND_VEC2, lanes: l } : null }
+export const floatValue = (v: unknown) => (typeof v === "number" ? { kind: KIND_FLOAT, lanes: [v] } : null)
+export const colorValue = (v: unknown, toRgba: (c: any) => [number, number, number, number]) => {
+  if (typeof v === "string" || typeof v === "number" || Array.isArray(v)) return { kind: KIND_COLOR, lanes: toRgba(v) }
+  return null
+}
+
+/** A free value for animate(): number → FLOAT, a color string → COLOR, arrays / vectors by length
+ *  (2 → VEC2, 3 → VEC3, 4 → QUAT, 16 → MAT4 decomposed into position · quaternion · scale). */
+export const valueValue = (v: unknown): ({ kind: number } & TweenValue) | null => {
+  if (typeof v === "number") return { kind: KIND_FLOAT, lanes: [v] }
+  if (typeof v === "string") return { kind: KIND_COLOR, lanes: Color.toRgba01(v) }
+  if (v && typeof v === "object") {
+    const o = v as any
+    const arr: ArrayLike<number> | undefined = typeof o.length === "number" ? o : Array.isArray(o.m) && o.m.length === 16 ? o.m : undefined
+    if (arr) {
+      if (arr.length === 2) return { kind: KIND_VEC2, lanes: [+arr[0]!, +arr[1]!] }
+      if (arr.length === 3) return { kind: KIND_VEC3, lanes: [+arr[0]!, +arr[1]!, +arr[2]!] }
+      if (arr.length === 4) return { kind: KIND_QUAT, lanes: [+arr[0]!, +arr[1]!, +arr[2]!, +arr[3]!] }
+      if (arr.length === 16) {
+        const d = new Mat4(arr as any).decompose()
+        return { kind: KIND_MAT4, lanes: [d.position.x, d.position.y, d.position.z, d.rotation.x, d.rotation.y, d.rotation.z, d.rotation.w, d.scale.x, d.scale.y, d.scale.z] }
+      }
+      return null
+    }
+    if (typeof o.x === "number") {
+      if (typeof o.w === "number") return { kind: KIND_QUAT, lanes: [o.x, o.y, o.z, o.w] }
+      if (typeof o.z === "number") return { kind: KIND_VEC3, lanes: [o.x, o.y, o.z] }
+      return { kind: KIND_VEC2, lanes: [o.x, o.y] }
+    }
+  }
+  return null
+}
+
+/** Is this bag value a KEYFRAME ARRAY for a vector prop, as opposed to one vector? A vector value
+ *  is an array of NUMBERS (`[0, 2, 0]`); anything else in the array is a list of keyframes —
+ *  `[[0,0,0], [0,2,0]]`, `[new Vec3(), …]`, and the UI's `color: ['#fff', '#e29a22']`. */
+export const isVectorKeyframes = (v: unknown): boolean =>
+  Array.isArray(v) && v.length > 0 && typeof v[0] !== "number"
+
+// ---- track construction ------------------------------------------------------------------------
+
+/** Build one track's keyframes from a bag value: a single value = one explicit key (the other end
+ *  captured), an array = explicit keys spaced by `times` or evenly. `fromCurrent` says which end is
+ *  implicit (animateTo: the first; animateFrom: the last). Returns null when a value can't be
+ *  animated (already warned). */
+export const makeTrack = (
+  target: TweenTarget, prop: string, raw: unknown, meta: TweenMeta, atMs: number, fromCurrent: boolean, vectorProp: boolean,
+): Track | null => {
+  const channel = target._tweenChannel(prop)
+  if (!channel) {
+    warnOnce(`prop:${prop}`, `"${prop}" is not animatable on this target — set it directly`)
+    return null
+  }
+  const values: unknown[] = Array.isArray(raw) && (!vectorProp || isVectorKeyframes(raw)) ? raw : [raw]
+  const easing = easingFor(meta.easing, prop)
+  const norm = values.map((v) => channel.value(v))
+  if (norm.some((n) => n === null)) {
+    warnOnce(`value:${prop}`, `"${prop}" got a value that cannot be animated — set it directly`)
+    return null
+  }
+  const ns = norm as NonNullable<(typeof norm)[number]>[]
+
+  // One kind per track. Mismatched units / transform signatures degrade to DISCRETE (a flip at the
+  // key, like CSS), never to garbage interpolation.
+  let kind = ns[0]!.kind
+  let sig = ns[0]!.sig
+  for (const n of ns) {
+    if (n.kind !== kind || n.sig !== sig) {
+      // FLOAT vs FLOAT_UNIT(px) can't happen (px normalizes to FLOAT); anything else is discrete
+      kind = KIND_DISCRETE
+      sig = undefined
+      break
+    }
+  }
+  const lanes = kind === KIND_TRANSFORM ? transformLanes(sig ?? "") : LANES[kind]!
+  const toValue = (n: NonNullable<(typeof norm)[number]>): TweenValue =>
+    kind === KIND_DISCRETE && "lanes" in n ? { str: String(n.lanes[0]) } : ("str" in n ? { str: n.str } : { lanes: n.lanes })
+
+  const explicit = ns.length
+  const total = explicit + (explicit === 1 ? 1 : 0)   // a single value pairs with a captured end
+  const keys: Keyframe[] = []
+  const times = meta.times
+  for (let i = 0; i < total; i++) {
+    let t: number
+    if (times && times.length === total) t = times[i]!
+    else t = total === 1 ? 1 : i / (total - 1)
+    let value: TweenValue | undefined
+    let raw: unknown
+    if (explicit === 1) {
+      // animateTo: [captured, v]; animateFrom: [v, captured]
+      const isExplicit = fromCurrent ? i === 1 : i === 0
+      value = isExplicit ? toValue(ns[0]!) : undefined
+      raw = isExplicit ? values[0] : undefined
+    } else {
+      value = toValue(ns[i]!)
+      raw = values[i]
+    }
+    keys.push({ t, easing, value, raw })
+  }
+  // animateFrom with an explicit array: the element's own style is the implicit LAST key
+  if (!fromCurrent && explicit > 1) {
+    for (const k of keys) k.t *= (total) / (total + 1)
+    keys.push({ t: 1, easing, value: undefined })
+  }
+
+  return {
+    target, prop, channel, kind, lanes, sig,
+    atMs: atMs + (meta.delay ?? 0),
+    durMs: Math.max(0, meta.duration ?? DEFAULT_DURATION_MS),
+    // animateFrom never commits (its last key is the element's own state); loops never commit
+    commit: fromCurrent && meta.commit !== false && iterationsOf(meta.loop) === 1,
+    keys,
+  }
+}
+
+/** Every (prop → value) entry of a bag, meta keys stripped. */
+export const bagProps = (bag: Record<string, unknown>): [string, unknown][] =>
+  Object.entries(bag).filter(([k, v]) => !TWEEN_META.has(k) && v !== undefined)
+
+// ---- JS evaluation (the old-host path of VALUE tracks; the C evaluator is the reference) ----------
+
+const slerpInto = (out: number[], o: number, a: number[], ai: number, b: number[], bi: number, s: number): void => {
+  let bx = b[bi]!, by = b[bi + 1]!, bz = b[bi + 2]!, bw = b[bi + 3]!
+  let cosom = a[ai]! * bx + a[ai + 1]! * by + a[ai + 2]! * bz + a[ai + 3]! * bw
+  if (cosom < 0) { cosom = -cosom; bx = -bx; by = -by; bz = -bz; bw = -bw }
+  let k0: number, k1: number
+  if (1 - cosom > 1e-6) {
+    const omega = Math.acos(Math.min(1, cosom)), sinom = Math.sin(omega)
+    k0 = Math.sin((1 - s) * omega) / sinom
+    k1 = Math.sin(s * omega) / sinom
+  } else { k0 = 1 - s; k1 = s }
+  out[o] = k0 * a[ai]! + k1 * bx; out[o + 1] = k0 * a[ai + 1]! + k1 * by; out[o + 2] = k0 * a[ai + 2]! + k1 * bz; out[o + 3] = k0 * a[ai + 3]! + k1 * bw
+}
+
+/** The value of a numeric track at local time `ms` (the C evaluator's rule: first key holds before,
+ *  last after; eased segment between). `out` receives `track.lanes` numbers. */
+export const evaluateTrack = (track: Track, ms: number, out: number[]): void => {
+  const u = track.durMs <= 0 ? (ms >= track.atMs ? 1 : 0) : Math.min(1, Math.max(0, (ms - track.atMs) / track.durMs))
+  const keys = track.keys
+  const lanesOfKey = (k: Keyframe): number[] => (k.value && "lanes" in k.value ? k.value.lanes : [])
+  if (keys.length === 0) return
+  if (u <= keys[0]!.t || keys.length === 1) { const l = lanesOfKey(keys[0]!); for (let i = 0; i < track.lanes; i++) out[i] = l[i] ?? 0; return }
+  const last = keys[keys.length - 1]!
+  if (u >= last.t) { const l = lanesOfKey(last); for (let i = 0; i < track.lanes; i++) out[i] = l[i] ?? 0; return }
+  let i = 0
+  while (i + 1 < keys.length && keys[i + 1]!.t <= u) i++
+  const a = keys[i]!, b = keys[i + 1]!
+  const span = b.t - a.t
+  const s = evalEasing(a.easing, span > 0 ? (u - a.t) / span : 1)
+  const la = lanesOfKey(a), lb = lanesOfKey(b)
+  if (track.kind === KIND_QUAT) { slerpInto(out, 0, la, 0, lb, 0, s); return }
+  if (track.kind === KIND_MAT4) {
+    for (let k = 0; k < 3; k++) out[k] = la[k]! + (lb[k]! - la[k]!) * s
+    slerpInto(out, 3, la, 3, lb, 3, s)
+    for (let k = 7; k < 10; k++) out[k] = la[k]! + (lb[k]! - la[k]!) * s
+    return
+  }
+  for (let k = 0; k < track.lanes; k++) out[k] = (la[k] ?? 0) + ((lb[k] ?? 0) - (la[k] ?? 0)) * s
+}
+
+// ---- the blob ----------------------------------------------------------------------------------
+
+export type TweenBlob = { data: Float32Array, strings: string[], targets: unknown[] }
+
+/** Flatten a spec for `_creatorTree.tweenCreate`. Tracks whose target has no host id right now are
+ *  dropped (the animation still runs its clock, calls and finish). */
+export const buildBlob = (spec: TweenSpec): TweenBlob => {
+  const strings: string[] = []
+  const strIndex = new Map<string, number>()
+  const str = (s: string): number => {
+    let i = strIndex.get(s)
+    if (i === undefined) { i = strings.length; strings.push(s); strIndex.set(s, i) }
+    return i
+  }
+  const tables: Float32Array[] = []
+  const tableIndex = (e: EasingSpec): number => {
+    const i = tables.indexOf(e.table!)
+    if (i >= 0) return i
+    tables.push(e.table!)
+    return tables.length - 1
+  }
+
+  const tracks = spec.tracks.map((t) => ({ t, id: t.channel.id() })).filter((x) => !!x.id)
+  const targets: unknown[] = []
+  const targetIndex = (id: unknown): number => {
+    let i = targets.indexOf(id)
+    if (i < 0) { i = targets.length; targets.push(id) }
+    return i
+  }
+  const out: number[] = []
+  out.push(BLOB_VERSION, spec.clock, spec.durationMs, spec.delayMs, spec.iterations, spec.pingPong ? 1 : 0, spec.rate,
+    tracks.length, spec.calls.length, 0 /* nTables, patched */)
+  for (const c of spec.calls) out.push(c)
+  const tablesAt = out.length
+  for (const { t, id } of tracks) {
+    out.push(t.channel.domain, targetIndex(id), str(t.prop), t.kind, t.lanes, t.atMs, t.durMs, t.commit ? 1 : 0, t.keys.length, t.sig !== undefined ? str(t.sig) : -1)
+    for (const k of t.keys) {
+      const e = k.easing
+      const p: number[] = [e.p[0], e.p[1], e.p[2], e.p[3]]
+      if (e.table) p[0] = tableIndex(e)
+      out.push(k.t, e.kind, p[0]!, p[1]!, p[2]!, p[3]!, k.value ? 1 : 0)
+      if (!k.value) { for (let i = 0; i < t.lanes; i++) out.push(0) }
+      else if ("str" in k.value) { out.push(str(k.value.str)); for (let i = 1; i < t.lanes; i++) out.push(0) }
+      else { for (let i = 0; i < t.lanes; i++) out.push(k.value.lanes[i] ?? 0) }
+    }
+  }
+  // splice the tables in after the calls
+  const tableData: number[] = []
+  for (const tb of tables) for (let i = 0; i < EASE_TABLE_SIZE; i++) tableData.push(tb[i]!)
+  out.splice(tablesAt, 0, ...tableData)
+  out[9] = tables.length
+  return { data: Float32Array.from(out), strings, targets }
+}