lecodes-sdk 1.2.0 → 2.0.0

package/src/animate/tween/Timeline.ts

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

package/src/animate/tween/animateValue.ts

@@ -4,6 +4,7 @@
 // evaluates natively and hands back to JS once per frame, the same easing vocabulary, keyframes,
 // loops and clocks, and the same `Animation` handle. `Timeline.animate` puts one into a timeline.
 
+import { LINEAR } from "./easing"
 import { TweenAnimation, type Animation } from "./Animation"
 import { Mat4 } from "../../math/mat4"
 import type { Vec2Like, Vec3Like } from "../../math/vec"
@@ -15,8 +16,10 @@ import {
   type Keyframe, type Track, type TweenChannel, type TweenMeta, type TweenSpec, type TweenTarget,
 } from "./spec"
 
-/** What `animate()` tweens: a number, a color (string / packed / rgb(a) array — delivered as rgba
- *  0..1), a 2 / 3-vector, a quaternion (slerp), or a 4x4 matrix (position / rotation / scale). */
+/** What `animate()` tweens: a number (a FLOAT, never a packed color), a color (any CSS color string,
+ *  through `Color` — delivered as rgba 0..1; a string that is not a color throws), a 2 / 3-vector (a
+ *  3-array is a vector, not a color), a quaternion (slerp), or a 4x4 matrix (position / rotation /
+ *  scale). */
 export type AnimateValue = number | string | Vec2Like | Vec3Like | QuatLike | Mat4Like | ColorInput
 
 /** `onUpdate` receives a number for a number; every other kind arrives as the SAME `Float32Array`
@@ -65,7 +68,7 @@ export const makeValueTrack = (o: AnimateOptions<any>, atMs: number): { track: T
   const kind = norm[0]!.kind
   if (norm.some((n) => n!.kind !== kind)) throw new Error("animate: every value must be the same kind")
   const lanes = lanesOf(kind)
-  const easing = easingFor(o.easing, "value")
+  const easing = easingFor(o.easing, "value", LINEAR)   // a raw progress: the app maps it, the core never pre-eases it
   const keys: Keyframe[] = norm.map((n, i) => ({
     t: o.times && o.times.length === norm.length ? o.times[i]! : norm.length === 1 ? 1 : i / (norm.length - 1),
     easing,

package/src/animate/tween/easing.ts

@@ -75,7 +75,7 @@ export const NAMED_EASINGS: ReadonlyArray<readonly [string, Easing]> = [
   ["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
+  ["smoothstep", (x) => x * x * (3 - 2 * x)],                                        // 28 — the $class block default
 ]
 
 /** Short spellings → canonical names. `in`/`out`/`inOut` are the quadratics, matching the SDK's
@@ -94,8 +94,15 @@ const namedId = (name: string): number => {
 
 /** 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] }
+/** The CSS `ease-in-out` curve — also UIKit's default animation curve, and web-lite's transition
+ *  default: what every host tweened with before the keyframe core. */
+export const CSS_EASE_IN_OUT: [number, number, number, number] = [0.42, 0, 0.58, 1]
+
+export const LINEAR: EasingSpec = { kind: EASE_LINEAR, p: [0, 0, 0, 0] }
+/** The default of every track with a TARGET (`animateTo` / `animateFrom` / `Timeline.add` on an
+ *  element, a 3D / 2D object): `ease-in-out` (2026-09-27; linear before). `animate()` — a raw
+ *  progress the app maps itself — stays linear. Write `easing: "linear"` for uniform motion. */
+export const DEFAULT_EASING: EasingSpec = { kind: EASE_BEZIER, p: CSS_EASE_IN_OUT }
 
 /** 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. */

package/src/animate/tween/spec.ts

@@ -19,7 +19,7 @@
 // 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 { DEFAULT_EASING, EASE_TABLE_SIZE, evalEasing, parseEasing, type EasingInput, type EasingSpec } from "./easing"
 import { Color } from "../../core/color"
 import { Mat4 } from "../../math/mat4"
 
@@ -131,7 +131,8 @@ export type TweenMeta = {
   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. */
+   *  `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[],
@@ -158,12 +159,13 @@ export const warnOnce = (key: string, msg: string): void => {
   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)
+/** 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. */
@@ -178,7 +180,8 @@ export const iterationsOf = (loop: TweenMeta["loop"]): number => {
 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. */
+ *  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" }
@@ -195,15 +198,23 @@ export const uiValue = (v: unknown): ({ kind: number, sig?: string } & TweenValu
   return null
 }
 
-/** Per-function argument counts of a UI transform list (degrees / px are the SDK's units). */
+/** 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. */
-export const parseTransformList = (s: string): { sig: string, lanes: number[] } | null => {
+ *  `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
@@ -215,15 +226,30 @@ export const parseTransformList = (s: string): { sig: string, lanes: number[] }
     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]!)
+    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)
-    consumed = re.lastIndex
   }
   if (src.slice(consumed).trim() !== "") return null
   return { sig: sig.join(","), lanes }
@@ -428,7 +454,7 @@ export const evaluateTrack = (track: Track, ms: number, out: number[]): void =>
 
 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
+/** 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[] = []

package/src/audio/Sound.ts

@@ -9,7 +9,7 @@
 //   gun.audio.play(shot)             // 3D, through an AudioSource aspect
 //
 // A Sound is APP-scoped (the menu and the level share one `shot`); the engine drops every clip
-// when `_creatorUtils.run()` swaps worlds. Without host support `load` resolves to a silent clip.
+// when `_creatorApp.run()` swaps worlds. Without host support `load` resolves to a silent clip.
 
 import { fetch } from "../runtime/fetch"
 import { audioSupported } from "./support"
@@ -48,7 +48,7 @@ export class Sound {
     let channels = 1
     for (const url of urls) {
       const resp = await fetch(url, { useOnce: true })
-      const systemId = (resp as unknown as { _id: number })._id
+      const systemId = (resp as unknown as { _h: Handle })._h.id
       try {
         const [ clipId, duration, ch ] = await new Promise<[number, number, number]>((resolve, reject) => {
           _creatorAudio.loadClip(systemId, !!options.stereo,
@@ -59,7 +59,7 @@ export class Sound {
         durations.push(duration)
         channels = ch
       } finally {
-        resp.dispose()
+        // the response body goes with `resp` (owned handle)
       }
     }
     return new Sound(urls, clips, durations, channels)

package/src/audio/audio.ts

@@ -81,7 +81,8 @@ class AudioSystem {
 
   /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
    *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
-   *  nearest 3D voices; the rest keep plain panning. */
+   *  nearest 3D voices; the rest keep plain panning. A host built without the filters (an iOS App
+   *  Clip: they are 184 KB) keeps every voice on the panner — `stats.hrtfVoices` stays 0. */
   get hrtf(): boolean { return this._hrtf }
   set hrtf(v: boolean) { this._hrtf = v; if (audioSupported) _creatorAudio.setHrtf(v, this._hrtfVoices) }
   /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default