lecodes-sdk 1.0.0 → 1.2.0

package/src/animate/tween/easing.ts

@@ -0,0 +1,172 @@
+// Easing vocabulary of the keyframe animation core (docs/timeline-plan.md §2.1). Every form the
+// options bag accepts is normalized here into an `EasingSpec` the native evaluator (creator-tween)
+// understands: linear, a NAMED curve (evaluated natively by id — the formulas below are the twin,
+// used for the old-host path and tests), a cubic bezier, `steps(n)`, or a sampled TABLE for an
+// arbitrary `Easing` function (65 points, linear between them — the only way a JS function can
+// cross the bridge).
+
+import type { Easing } from "../easings"
+
+export const EASE_LINEAR = 0
+export const EASE_NAMED = 1
+export const EASE_BEZIER = 2
+export const EASE_STEPS = 3
+export const EASE_TABLE = 4
+
+/** Samples per table (t = i / 64). Interpolation error for the smooth built-ins is < 1e-3. */
+export const EASE_TABLE_SIZE = 65
+
+export type EasingSpec = {
+  kind: number,
+  /** kind-specific parameters: NAMED [id], BEZIER [x1, y1, x2, y2], STEPS [n, jumpAtStart], TABLE [tableIndex] */
+  p: [number, number, number, number],
+  /** TABLE only — the samples, appended to the blob's table section by the builder. */
+  table?: Float32Array,
+}
+
+/** A curve in the options bag: a name, `"cubic-bezier(x1,y1,x2,y2)"`, `"steps(n)"`, a bezier tuple,
+ *  or any `Easing` function. */
+export type EasingInput = string | readonly [number, number, number, number] | Easing
+
+// ---- named curves (ids are the native contract — append, never renumber) ------------------------
+
+const c1 = 1.70158
+const c2 = c1 * 1.525
+const c3 = c1 + 1
+const c4 = (2 * Math.PI) / 3
+const c5 = (2 * Math.PI) / 4.5
+
+const outBounce = (x: number): number => {
+  const n1 = 7.5625, d1 = 2.75
+  if (x < 1 / d1) return n1 * x * x
+  if (x < 2 / d1) return n1 * (x -= 1.5 / d1) * x + 0.75
+  if (x < 2.5 / d1) return n1 * (x -= 2.25 / d1) * x + 0.9375
+  return n1 * (x -= 2.625 / d1) * x + 0.984375
+}
+
+/** id → (name, formula). The formulas are the standard easings.net set; creator-tween's
+ *  `ctweenEaseNamed` implements the same list by id. */
+export const NAMED_EASINGS: ReadonlyArray<readonly [string, Easing]> = [
+  ["linear", (x) => x],                                                              // 0
+  ["inSine", (x) => 1 - Math.cos((x * Math.PI) / 2)],                                // 1
+  ["outSine", (x) => Math.sin((x * Math.PI) / 2)],                                   // 2
+  ["inOutSine", (x) => -(Math.cos(Math.PI * x) - 1) / 2],                            // 3
+  ["inQuad", (x) => x * x],                                                          // 4
+  ["outQuad", (x) => 1 - (1 - x) * (1 - x)],                                         // 5
+  ["inOutQuad", (x) => (x < 0.5 ? 2 * x * x : 1 - (-2 * x + 2) ** 2 / 2)],          // 6
+  ["inCubic", (x) => x * x * x],                                                     // 7
+  ["outCubic", (x) => 1 - (1 - x) ** 3],                                             // 8
+  ["inOutCubic", (x) => (x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2)],     // 9
+  ["inQuart", (x) => x ** 4],                                                        // 10
+  ["outQuart", (x) => 1 - (1 - x) ** 4],                                             // 11
+  ["inOutQuart", (x) => (x < 0.5 ? 8 * x ** 4 : 1 - (-2 * x + 2) ** 4 / 2)],        // 12
+  ["inExpo", (x) => (x === 0 ? 0 : 2 ** (10 * x - 10))],                             // 13
+  ["outExpo", (x) => (x === 1 ? 1 : 1 - 2 ** (-10 * x))],                            // 14
+  ["inOutExpo", (x) => (x === 0 ? 0 : x === 1 ? 1 : x < 0.5 ? 2 ** (20 * x - 10) / 2 : (2 - 2 ** (-20 * x + 10)) / 2)], // 15
+  ["inCirc", (x) => 1 - Math.sqrt(1 - x * x)],                                       // 16
+  ["outCirc", (x) => Math.sqrt(1 - (x - 1) ** 2)],                                   // 17
+  ["inOutCirc", (x) => (x < 0.5 ? (1 - Math.sqrt(1 - (2 * x) ** 2)) / 2 : (Math.sqrt(1 - (-2 * x + 2) ** 2) + 1) / 2)], // 18
+  ["inBack", (x) => c3 * x * x * x - c1 * x * x],                                    // 19
+  ["outBack", (x) => 1 + c3 * (x - 1) ** 3 + c1 * (x - 1) ** 2],                     // 20
+  ["inOutBack", (x) => (x < 0.5 ? ((2 * x) ** 2 * ((c2 + 1) * 2 * x - c2)) / 2 : ((2 * x - 2) ** 2 * ((c2 + 1) * (x * 2 - 2) + c2) + 2) / 2)], // 21
+  ["inElastic", (x) => (x === 0 ? 0 : x === 1 ? 1 : -(2 ** (10 * x - 10)) * Math.sin((x * 10 - 10.75) * c4))], // 22
+  ["outElastic", (x) => (x === 0 ? 0 : x === 1 ? 1 : 2 ** (-10 * x) * Math.sin((x * 10 - 0.75) * c4) + 1)],   // 23
+  ["inOutElastic", (x) => (x === 0 ? 0 : x === 1 ? 1 : x < 0.5 ? -(2 ** (20 * x - 10) * Math.sin((20 * x - 11.125) * c5)) / 2 : (2 ** (-20 * x + 10) * Math.sin((20 * x - 11.125) * c5)) / 2 + 1)], // 24
+  ["inBounce", (x) => 1 - outBounce(1 - x)],                                         // 25
+  ["outBounce", outBounce],                                                          // 26
+  ["inOutBounce", (x) => (x < 0.5 ? (1 - outBounce(1 - 2 * x)) / 2 : (1 + outBounce(2 * x - 1)) / 2)], // 27
+  ["smoothstep", (x) => x * x * (3 - 2 * x)],                                        // 28 — the $class / onPressed default
+]
+
+/** Short spellings → canonical names. `in`/`out`/`inOut` are the quadratics, matching the SDK's
+ *  `easeIn`/`easeOut`/`easeInOut` functions. */
+const ALIASES: Record<string, string> = {
+  in: "inQuad", out: "outQuad", inOut: "inOutQuad",
+  easeIn: "inQuad", easeOut: "outQuad", easeInOut: "inOutQuad",
+  "ease-in": "inQuad", "ease-out": "outQuad", "ease-in-out": "inOutQuad",
+}
+
+const namedId = (name: string): number => {
+  const canon = ALIASES[name] ?? name
+  for (let i = 0; i < NAMED_EASINGS.length; i++) if (NAMED_EASINGS[i]![0] === canon) return i
+  return -1
+}
+
+/** The CSS `ease` curve — what a bare `"ease"` means. */
+const CSS_EASE: [number, number, number, number] = [0.25, 0.1, 0.25, 1]
+
+const LINEAR: EasingSpec = { kind: EASE_LINEAR, p: [0, 0, 0, 0] }
+
+/** Sample an `Easing` function into a table. Endpoints are forced exact so a curve that is
+ *  numerically 0.9999 at 1 still lands on the keyframe. */
+export const sampleEasing = (fn: Easing): Float32Array => {
+  const t = new Float32Array(EASE_TABLE_SIZE)
+  for (let i = 0; i < EASE_TABLE_SIZE; i++) t[i] = fn(i / (EASE_TABLE_SIZE - 1))
+  t[0] = 0
+  t[EASE_TABLE_SIZE - 1] = 1
+  return t
+}
+
+/** Normalize one easing input. Unknown strings fall back to linear with a console warning (a typo
+ *  should be visible, not a silent snap). */
+export const parseEasing = (input: EasingInput | undefined): EasingSpec => {
+  if (input === undefined) return LINEAR
+  if (typeof input === "function") return { kind: EASE_TABLE, p: [0, 0, 0, 0], table: sampleEasing(input) }
+  if (Array.isArray(input)) {
+    const [x1, y1, x2, y2] = input as readonly number[]
+    return { kind: EASE_BEZIER, p: [x1!, y1!, x2!, y2!] }
+  }
+  const s = (input as string).trim()
+  if (s === "linear") return LINEAR
+  if (s === "ease") return { kind: EASE_BEZIER, p: CSS_EASE }
+  if (s === "steps") return { kind: EASE_STEPS, p: [1, 0, 0, 0] }
+  let m = /^steps\(\s*(\d+)\s*(?:,\s*(start|end|jump-start|jump-end)\s*)?\)$/.exec(s)
+  if (m) return { kind: EASE_STEPS, p: [Math.max(1, parseInt(m[1]!, 10)), m[2] === "start" || m[2] === "jump-start" ? 1 : 0, 0, 0] }
+  m = /^cubic-bezier\(\s*([-\d.e]+)\s*,\s*([-\d.e]+)\s*,\s*([-\d.e]+)\s*,\s*([-\d.e]+)\s*\)$/.exec(s)
+  if (m) return { kind: EASE_BEZIER, p: [parseFloat(m[1]!), parseFloat(m[2]!), parseFloat(m[3]!), parseFloat(m[4]!)] }
+  const id = namedId(s)
+  if (id === 0) return LINEAR
+  if (id > 0) return { kind: EASE_NAMED, p: [id, 0, 0, 0] }
+  console.warn(`[tween] unknown easing "${s}" — using linear`)
+  return LINEAR
+}
+
+// ---- evaluation twin (old-host path + tests) ---------------------------------------------------
+
+const bezierY = (x: number, x1: number, y1: number, x2: number, y2: number): number => {
+  // Newton on the x polynomial, then y at that t — the same method creator-tween uses.
+  const ax = 1 - 3 * x2 + 3 * x1, bx = 3 * x2 - 6 * x1, cx = 3 * x1
+  const ay = 1 - 3 * y2 + 3 * y1, by = 3 * y2 - 6 * y1, cy = 3 * y1
+  let t = x
+  for (let i = 0; i < 8; i++) {
+    const xt = ((ax * t + bx) * t + cx) * t - x
+    const dx = (3 * ax * t + 2 * bx) * t + cx
+    if (Math.abs(xt) < 1e-6) break
+    if (Math.abs(dx) < 1e-6) break
+    t -= xt / dx
+  }
+  t = Math.min(1, Math.max(0, t))
+  return ((ay * t + by) * t + cy) * t
+}
+
+/** Evaluate an `EasingSpec` at `u` ∈ [0, 1] — the JS twin of `ctweenEase`. */
+export const evalEasing = (e: EasingSpec, u: number): number => {
+  if (u <= 0) return e.kind === EASE_STEPS && e.p[1] === 1 ? 1 / e.p[0] : 0
+  if (u >= 1) return 1
+  switch (e.kind) {
+    case EASE_NAMED: return NAMED_EASINGS[e.p[0]]![1](u)
+    case EASE_BEZIER: return bezierY(u, e.p[0], e.p[1], e.p[2], e.p[3])
+    case EASE_STEPS: {
+      const n = e.p[0]
+      return e.p[1] === 1 ? Math.min(1, Math.ceil(u * n) / n) : Math.floor(u * n) / n
+    }
+    case EASE_TABLE: {
+      const t = e.table!
+      const f = u * (EASE_TABLE_SIZE - 1)
+      const i = Math.floor(f)
+      const a = t[i]!, b = t[Math.min(i + 1, EASE_TABLE_SIZE - 1)]!
+      return a + (b - a) * (f - i)
+    }
+    default: return u
+  }
+}

package/src/animate/tween/spec.ts

@@ -0,0 +1,479 @@
+// 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 }
+}