lecodes-sdk 1.1.0 → 2.0.0

package/src/animate/tween/animateValue.ts

@@ -1,100 +1,103 @@
-// `animate()` — "animate a VALUE, I apply it" (docs/timeline-plan.md): the free-value tween for
-// anything without a native writer (a material parameter, a volume, a number the Canvas draws).
-// Since 2026-09-14 it runs on the keyframe core like everything else: a VALUE-domain track the host
-// evaluates natively and hands back to JS once per frame, the same easing vocabulary, keyframes,
-// loops and clocks, and the same `Animation` handle. `Timeline.animate` puts one into a timeline.
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { Mat4 } from "../../math/mat4"
-import type { Vec2Like, Vec3Like } from "../../math/vec"
-import type { QuatLike } from "../../math/quat"
-import type { Mat4Like } from "../../math/mat4"
-import type { ColorInput } from "../../core/color"
-import {
-  CLOCK_GAME, CLOCK_UI, DOM_VALUE, KIND_FLOAT, KIND_MAT4, DEFAULT_DURATION_MS, easingFor, iterationsOf, lanesOf, valueValue,
-  type Keyframe, type Track, type TweenChannel, type TweenMeta, type TweenSpec, type TweenTarget,
-} from "./spec"
-
-/** What `animate()` tweens: a number, a color (string / packed / rgb(a) array — delivered as rgba
- *  0..1), a 2 / 3-vector, a quaternion (slerp), or a 4x4 matrix (position / rotation / scale). */
-export type AnimateValue = number | string | Vec2Like | Vec3Like | QuatLike | Mat4Like | ColorInput
-
-/** `onUpdate` receives a number for a number; every other kind arrives as the SAME `Float32Array`
- *  every frame (overwritten in place — copy it if you keep it). A matrix is the 16 floats. */
-export type AnimateOut<T> = T extends number ? number : Float32Array
-
-export type AnimateOptions<T extends AnimateValue> = Omit<TweenMeta, "commit" | "layer"> & {
-  /** Start value (required unless `values` is given). */
-  from?: T,
-  /** End value. */
-  to?: T,
-  /** Keyframes instead of from/to (offsets via `times`). */
-  values?: T[],
-  onUpdate(value: AnimateOut<T>): void,
-  /** After the last frame of a run that reached its end (not on cancel). */
-  onComplete?(): void,
-}
-
-/** @internal Deliverers turn the host's lanes into the `onUpdate` argument without allocating. */
-const deliverer = (kind: number, lanes: number, onUpdate: (v: any) => void): ((l: Float32Array) => void) => {
-  if (kind === KIND_FLOAT) return (l) => onUpdate(l[0])
-  if (kind === KIND_MAT4) {
-    const out = new Float32Array(16)
-    return (l) => {
-      const m = Mat4.compose([l[0]!, l[1]!, l[2]!], [l[3]!, l[4]!, l[5]!, l[6]!], [l[7]!, l[8]!, l[9]!]).m
-      for (let i = 0; i < 16; i++) out[i] = m[i]!
-      onUpdate(out)
-    }
-  }
-  const out = new Float32Array(lanes)
-  return (l) => { for (let i = 0; i < lanes; i++) out[i] = l[i]!; onUpdate(out) }
-}
-
-/** VALUE slots are unique per world: the host addresses a value track by (animation, slot), and the
- *  evaluator must never see two animations naming the same slot (a channel is owned by the newest
- *  animation that names it — values have no shared state to own). */
-let nextSlot = 0
-
-/** @internal Build a VALUE track from animate options. Returns the track, its deliverer and its slot. */
-export const makeValueTrack = (o: AnimateOptions<any>, atMs: number): { track: Track, deliver: (l: Float32Array) => void, slot: number } => {
-  const slot = ++nextSlot
-  const raw: unknown[] = o.values ?? (o.from !== undefined && o.to !== undefined ? [o.from, o.to] : [])
-  if (raw.length < 1) throw new Error("animate: give `from` + `to`, or `values`")
-  const norm = raw.map((v) => valueValue(v))
-  if (norm.some((n) => n === null)) throw new Error("animate: a value is not a number, color, vector, quaternion or matrix")
-  const kind = norm[0]!.kind
-  if (norm.some((n) => n!.kind !== kind)) throw new Error("animate: every value must be the same kind")
-  const lanes = lanesOf(kind)
-  const easing = easingFor(o.easing, "value")
-  const keys: Keyframe[] = norm.map((n, i) => ({
-    t: o.times && o.times.length === norm.length ? o.times[i]! : norm.length === 1 ? 1 : i / (norm.length - 1),
-    easing,
-    value: { lanes: (n as { lanes: number[] }).lanes },
-    raw: raw[i],
-  }))
-  const channel: TweenChannel = { domain: DOM_VALUE, id: () => slot, value: valueValue }
-  const target: TweenTarget = { _tweenClock: CLOCK_UI, _tweenChannel: () => channel }
-  const track: Track = {
-    target, prop: "value", channel, kind, lanes,
-    atMs: atMs + (o.delay ?? 0), durMs: Math.max(0, o.duration ?? DEFAULT_DURATION_MS),
-    commit: false, keys,
-  }
-  return { track, deliver: deliverer(kind, lanes, o.onUpdate), slot }
-}
-
-/** Tween a free value and apply it yourself in `onUpdate` — the primitive for anything without a
- *  native channel (material params, volumes, numbers a Canvas draws). Same easing / keyframes /
- *  `loop` / `clock` as `animateTo`; returns the {@link Animation} handle. Default clock: `'ui'`. */
-export const animate = <T extends AnimateValue>(options: AnimateOptions<T>): Animation => {
-  const { track, deliver, slot } = makeValueTrack(options, 0)
-  const spec: TweenSpec = {
-    clock: options.clock === "game" ? CLOCK_GAME : CLOCK_UI,
-    durationMs: track.atMs + track.durMs, delayMs: 0,
-    iterations: iterationsOf(options.loop), pingPong: options.loopMode !== "restart",
-    rate: 1, tracks: [track], calls: [],
-  }
-  const a = new TweenAnimation(spec)
-  a._values.set(slot, deliver)
-  if (options.onComplete) a.onFinish((done) => { if (done) options.onComplete!() })
-  return a.play()
-}
+// `animate()` — "animate a VALUE, I apply it" (docs/timeline-plan.md): the free-value tween for
+// anything without a native writer (a material parameter, a volume, a number the Canvas draws).
+// Since 2026-09-14 it runs on the keyframe core like everything else: a VALUE-domain track the host
+// evaluates natively and hands back to JS once per frame, the same easing vocabulary, keyframes,
+// loops and clocks, and the same `Animation` handle. `Timeline.animate` puts one into a timeline.
+
+import { LINEAR } from "./easing"
+import { TweenAnimation, type Animation } from "./Animation"
+import { Mat4 } from "../../math/mat4"
+import type { Vec2Like, Vec3Like } from "../../math/vec"
+import type { QuatLike } from "../../math/quat"
+import type { Mat4Like } from "../../math/mat4"
+import type { ColorInput } from "../../core/color"
+import {
+  CLOCK_GAME, CLOCK_UI, DOM_VALUE, KIND_FLOAT, KIND_MAT4, DEFAULT_DURATION_MS, easingFor, iterationsOf, lanesOf, valueValue,
+  type Keyframe, type Track, type TweenChannel, type TweenMeta, type TweenSpec, type TweenTarget,
+} from "./spec"
+
+/** What `animate()` tweens: a number (a 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`
+ *  every frame (overwritten in place — copy it if you keep it). A matrix is the 16 floats. */
+export type AnimateOut<T> = T extends number ? number : Float32Array
+
+export type AnimateOptions<T extends AnimateValue> = Omit<TweenMeta, "commit" | "layer"> & {
+  /** Start value (required unless `values` is given). */
+  from?: T,
+  /** End value. */
+  to?: T,
+  /** Keyframes instead of from/to (offsets via `times`). */
+  values?: T[],
+  onUpdate(value: AnimateOut<T>): void,
+  /** After the last frame of a run that reached its end (not on cancel). */
+  onComplete?(): void,
+}
+
+/** @internal Deliverers turn the host's lanes into the `onUpdate` argument without allocating. */
+const deliverer = (kind: number, lanes: number, onUpdate: (v: any) => void): ((l: Float32Array) => void) => {
+  if (kind === KIND_FLOAT) return (l) => onUpdate(l[0])
+  if (kind === KIND_MAT4) {
+    const out = new Float32Array(16)
+    return (l) => {
+      const m = Mat4.compose([l[0]!, l[1]!, l[2]!], [l[3]!, l[4]!, l[5]!, l[6]!], [l[7]!, l[8]!, l[9]!]).m
+      for (let i = 0; i < 16; i++) out[i] = m[i]!
+      onUpdate(out)
+    }
+  }
+  const out = new Float32Array(lanes)
+  return (l) => { for (let i = 0; i < lanes; i++) out[i] = l[i]!; onUpdate(out) }
+}
+
+/** VALUE slots are unique per world: the host addresses a value track by (animation, slot), and the
+ *  evaluator must never see two animations naming the same slot (a channel is owned by the newest
+ *  animation that names it — values have no shared state to own). */
+let nextSlot = 0
+
+/** @internal Build a VALUE track from animate options. Returns the track, its deliverer and its slot. */
+export const makeValueTrack = (o: AnimateOptions<any>, atMs: number): { track: Track, deliver: (l: Float32Array) => void, slot: number } => {
+  const slot = ++nextSlot
+  const raw: unknown[] = o.values ?? (o.from !== undefined && o.to !== undefined ? [o.from, o.to] : [])
+  if (raw.length < 1) throw new Error("animate: give `from` + `to`, or `values`")
+  const norm = raw.map((v) => valueValue(v))
+  if (norm.some((n) => n === null)) throw new Error("animate: a value is not a number, color, vector, quaternion or matrix")
+  const kind = norm[0]!.kind
+  if (norm.some((n) => n!.kind !== kind)) throw new Error("animate: every value must be the same kind")
+  const lanes = lanesOf(kind)
+  const easing = easingFor(o.easing, "value", 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,
+    value: { lanes: (n as { lanes: number[] }).lanes },
+    raw: raw[i],
+  }))
+  const channel: TweenChannel = { domain: DOM_VALUE, id: () => slot, value: valueValue }
+  const target: TweenTarget = { _tweenClock: CLOCK_UI, _tweenChannel: () => channel }
+  const track: Track = {
+    target, prop: "value", channel, kind, lanes,
+    atMs: atMs + (o.delay ?? 0), durMs: Math.max(0, o.duration ?? DEFAULT_DURATION_MS),
+    commit: false, keys,
+  }
+  return { track, deliver: deliverer(kind, lanes, o.onUpdate), slot }
+}
+
+/** Tween a free value and apply it yourself in `onUpdate` — the primitive for anything without a
+ *  native channel (material params, volumes, numbers a Canvas draws). Same easing / keyframes /
+ *  `loop` / `clock` as `animateTo`; returns the {@link Animation} handle. Default clock: `'ui'`. */
+export const animate = <T extends AnimateValue>(options: AnimateOptions<T>): Animation => {
+  const { track, deliver, slot } = makeValueTrack(options, 0)
+  const spec: TweenSpec = {
+    clock: options.clock === "game" ? CLOCK_GAME : CLOCK_UI,
+    durationMs: track.atMs + track.durMs, delayMs: 0,
+    iterations: iterationsOf(options.loop), pingPong: options.loopMode !== "restart",
+    rate: 1, tracks: [track], calls: [],
+  }
+  const a = new TweenAnimation(spec)
+  a._values.set(slot, deliver)
+  if (options.onComplete) a.onFinish((done) => { if (done) options.onComplete!() })
+  return a.play()
+}

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. */