lecodes-sdk 1.0.0 → 1.1.0

package/src/gl/terrain/Terrain.ts

@@ -46,11 +46,13 @@ import {
 } from "./terrainMesh"
 
 export type TerrainLayer = {
-  /** Albedo texture (a URL / `asset()` handle, or a loaded Texture). Unset = white. */
+  /** Albedo texture (a URL / `asset()` handle, or a loaded Texture). Unset = white. Its ALPHA is the layer's roughness
+   *  map (`lecodes assets terrain-pack --roughness` puts it there): an opaque albedo reads 1. */
   albedo?: string | Texture
   /** Metres per texture repeat. Default 8. */
   tiling?: number
-  /** Perceptual roughness of the layer. Default 1. */
+  /** Perceptual roughness of the layer — a factor on the albedo's alpha (its roughness map), the whole value when the
+   *  albedo is opaque. A terrain has no metallic: ground is a dielectric. Default 1. */
   roughness?: number
   /** Normal-map strength (0 = the layer's slot of the pack is not read). Default 0 — set 1 when the
    *  layer has a normal map in `normals`. */

package/src/inject.ts

@@ -123,8 +123,16 @@ export type { UINode, UINodeChild } from "./ui/UINode"
 export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
 
 // ---- animate ----
-export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
+// animate() runs on the keyframe core (a VALUE track) since 2026-09-14: same handle, easing and clocks
+// as animateTo; stop / pause / resume are the handle's methods, a matrix is just a value kind.
+export { animate, type AnimateOptions, type AnimateValue, type AnimateOut } from "./animate/tween/animateValue"
 export { cubicBezier } from "./animate/bezier"
+// Keyframe animation core (docs/timeline-plan.md): the handle `animateTo` / `animateFrom` return,
+// and `Timeline()` — choreography over UI elements, 3D / 2D nodes, lights and cameras.
+export { Timeline, type TimelineOptions, type TimelineAddOptions, type TimelinePosition } from "./animate/tween/Timeline"
+export { type Animation } from "./animate/tween/Animation"
+export { type TweenMeta } from "./animate/tween/spec"
+export { type EasingInput } from "./animate/tween/easing"
 export { easeIn, easeOut, easeInOut } from "./animate/easings"
 
 // ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
@@ -182,7 +190,7 @@ export { Vehicle } from "./gl/vehicle/Vehicle"
 export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, SteeringFeedback, SteeringDriver, AeroConfig } from "./gl/vehicle/Vehicle"
 export { Wheel, Tire, resolveTire } from "./gl/vehicle/Wheel"
 export { Ragdoll } from "./gl/physics/Ragdoll"
-export type { RagdollPart, RagdollHinge } from "./gl/physics/Ragdoll"
+export type { RagdollPart, RagdollHinge, RagdollFacing, RagdollActivateOptions, RagdollDeactivateOptions, RagdollHitOptions } from "./gl/physics/Ragdoll"
 export type { Point, WheelSuspension } from "./gl/vehicle/Wheel"
 export { AnimationClip } from "./gl/animation/AnimationClip"
 export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
@@ -203,6 +211,8 @@ export type { DynamicBoneCurve, DynamicBoneFloor, DynamicBoneColliders } from ".
 export type { IKTwoBone, IKLookAt } from "./gl/animation/IK"
 export { Light } from "./gl/Light"
 export { Lightmap } from "./gl/Lightmap"
+export { Foliage } from "./gl/Foliage"
+export type { FoliageOptions, FoliageWind } from "./gl/Foliage"
 export { Terrain } from "./gl/terrain/Terrain"
 export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/terrain/Terrain"
 export { NavMesh, NavCrowd } from "./gl/nav/NavMesh"

package/src/scene/defineScene.ts

@@ -48,10 +48,12 @@ import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
-import { Lightmap } from "../gl/Lightmap"
+import { Lightmap, type LightmapTransmit } from "../gl/Lightmap"
+import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
 import { Light, type SunOptions } from "../gl/Light"
+import { Material } from "../gl/Material"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
 import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
 import { GizmoBuffer, Gizmos, withGizmoScope, type GizmoBatch } from "./gizmos"
@@ -184,6 +186,10 @@ export type SceneNodeDef = {
    *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
    *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
   lightmap?: boolean
+  /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
+   *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
+   *  copy past `end` — for ground cover. The fade is per ASSET: every node of the same GLB shares it. */
+  foliage?: boolean | { fade?: [number, number] }
   /** Navigation (a scene with `env.navmesh`, see navmesh.md): every STATIC body is walkable by
    *  default. `false` leaves this one out of the bake; `'unwalkable'` cuts its footprint out
    *  (nobody stands on or crosses it). */
@@ -201,41 +207,44 @@ export type SceneCameraDef = CameraProjectionDef & {
   target?: Vec3Like
 }
 
-/** `env.lightmap` — the level's baked lighting (see lightmap.md): the two files
- *  `lecodes lightmap bake` writes, plus how the bake is applied. Absent = real-time only. */
+/** `env.lightmap` — the level's baked lighting (packages/creator-bake): the files `lecodes lightmap bake`
+ *  writes. Absent = real-time only. */
 export type SceneLightmapDef = {
-  /** `asset('./assets/lightmap/lightmap.bake')` */
+  /** `asset('./assets/lightmap/level.bake')` */
   data: string
-  /** `asset('./assets/lightmap/lightmap.ktx2')` — or, for a bake that took more than one atlas PAGE
-   *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x.ktx2'), asset('x_1.ktx2')]`. */
-  texture: string | string[]
-  /** `asset('./assets/lightmap/lightmap-light.ktx2')` (pages like `texture`) — the point lights' baked
-   *  irradiance the bake writes when the level holds point lights; the real-time lights it carries are
-   *  switched off once it applies. Absent = the lamps stay real-time. */
-  light?: string | string[]
-  /** `asset('./assets/lightmap/lightmap.volume')` — the light VOLUME for everything that moves (the
-   *  same bake writes it): dynamic nodes, and every model loaded in code while the level runs, read
-   *  the baked sun/ambient at their own position. Absent = movers stay real-time only. */
+  /** `asset('./assets/lightmap/level-light.ktx2')` — or, for a bake that took more than one atlas PAGE
+   *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x-light.ktx2'), asset('x-light_1.ktx2')]`. */
+  light: string | string[]
+  /** `asset('./assets/lightmap/level-aux.ktx2')` (pages like `light`) — sun / sky visibility + light direction. */
+  aux: string | string[]
+  /** DEBUG: the page sets a `lecodes lightmap bake --split` wrote (`<stem>-direct[_n].ktx2`, `<stem>-indirect[_n].ktx2`),
+   *  pages like `light` — the `Lightmap.debug("direct" | "indirect")` views bind them in place of `light`. */
+  direct?: string | string[]
+  indirect?: string | string[]
+  /** `asset('./assets/lightmap/level-probes.ktx2')` — the bake's reflection probes (one prefiltered cubemap of the level's
+   *  radiance per probe; every static reflects the nearest). Absent = statics reflect the sky's SH alone. */
+  probes?: string
+  /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
+   *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK (the school's panels
+   *  say 10); this is where the level says what they give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default: what
+   *  the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. `--emissive-nits` overrides. */
+  emissiveNits?: number
+  /** `false` = the emissive surfaces light nothing in the bake - the level is lit by its lamps (`Light.point` with a
+   *  `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only says how
+   *  bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. */
+  emissiveBake?: boolean
+  /** FOR THE BAKE: materials that let light THROUGH them, by glTF material name (`"name*"` = every name with that start) →
+   *  the share of a shadow ray that passes, tinted by the material's base colour x map: `{ mat_awning: 0.3 }` puts the
+   *  awning's warm, patterned light on the sand. The surface stays opaque - baked, drawn as before, a shadow caster.
+   *  `{ through, diffuse }` splits it: `through` goes straight (the picture of the map), `diffuse` is scattered by the
+   *  fibres (the underside glows, a soft fill with no picture) - dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
+  transmit?: Record<string, LightmapTransmit>
+  /** `asset('./assets/lightmap/level.lgrid')` — THE LIGHT GRID for movers: every node a Physics aspect or a
+   *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
+   *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
   volume?: string
-  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-  sunStrength?: number
-  /** Multiplier on the ambient share in the shadow math (1 = filament's own darkness). Default 1. */
-  ambientScale?: number
-  /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by its
-   *  ambient probe alone can want less than the geometric truth. Default 1. */
-  aoStrength?: number
-  /** Multiplier on the baked point lights' irradiance (default 1) - dial the lamps up or down
-   *  without a re-bake, since their irradiance lives in the atlas. Scales the light volume with the
-   *  atlas, so movers match the statics. See `LightmapLoadOptions.lightBoost`. */
-  lightBoost?: number
-  /** Multiplier on the light VOLUME's irradiance alone (default = `lightBoost`). Since the volume is an
-   *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
-   *  trim. See `LightmapLoadOptions.volumeBoost`. */
-  volumeBoost?: number
-  /** Occluder-only statics (props without lightmap UVs): `"baked"` (default) = their shadow is in the
-   *  atlas, they stop casting in real time and the shadow pass draws only the movers; `"realtime"` =
-   *  they keep casting (their shadow on other non-receiver props). See `LightmapLoadOptions.occluderShadows`. */
-  occluderShadows?: "baked" | "realtime"
+  /** A DEBUG multiplier on the atlas' lux (default 1). */
+  lightScale?: number
 }
 
 /** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
@@ -250,7 +259,7 @@ export type SceneNavmeshDef = {
 }
 
 export type SceneDef = {
-  env?: SceneOptions & { lightmap?: SceneLightmapDef, navmesh?: SceneNavmeshDef }
+  env?: SceneOptions & { lightmap?: SceneLightmapDef, navmesh?: SceneNavmeshDef, foliage?: FoliageOptions }
   camera?: SceneCameraDef
   nodes?: Record<string, SceneNodeDef>
 }
@@ -422,7 +431,7 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
 // rename honestly invalidates the rect. make() subtrees are code — they register themselves with
 // Lightmap.add. Edit mode never bakes or applies (the editor shows real-time shadows).
 
-type LightmapCtx = { prefix: string, volume: boolean, dynamicOnly?: boolean }
+type LightmapCtx = { prefix: string }
 
 // A CharacterController moves its node as surely as a dynamic body does (2026-09-11: the hero's
 // capsule was read as static, so its sword baked a shadow into the terrain at the spawn point).
@@ -435,12 +444,12 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
  *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
 export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
 
-// `lightmap` undefined = Model.load's own default ('dynamic' while a level with a light volume runs —
-// this is how a weapon or arms scene instantiated from code reads the volume; an explicit false would win)
 /** A terrain node: from its file or a fresh flat grid; textures load before the node appears (like a
  *  mesh's material). Stamps and holes apply later in buildNodes, once every target node exists. */
-const createTerrain = async (def: TerrainNodeDef): Promise<Node> => {
-  const { data, stamps: _s, holes: _h, ...opts } = def
+const createTerrain = async (def: TerrainNodeDef, lightmap: boolean): Promise<Node> => {
+  const { data, stamps: _s, holes: _h, ...rest } = def
+  // a lightmap static is built with the baked material from the start, like a model is loaded lightmapped
+  const opts = lightmap ? { ...rest, material: Material.terrainLightmap() } : rest
   const t = data !== undefined ? await Terrain.load(data, opts) : Terrain.create(opts)
   await t.ready
   return t.node
@@ -457,14 +466,11 @@ const createTerrain = async (def: TerrainNodeDef): Promise<Node> => {
 // cannot leak into the next node that leaves the flag alone.
 const modelTemplates = new Map<string, Promise<Model>>()
 
-const loadModel = (source: string, lightmap: boolean | "dynamic" | undefined): Promise<Model> => {
-  // `Model.load` resolves an omitted mode against Model._lightmapDefault, which the running level
-  // sets — so the KEY has to hold the resolved mode, not the argument.
-  const mode = lightmap ?? Model._lightmapDefault
-  const key = `${mode}\u0000${source}`
+const loadModel = (source: string, lightmap: boolean, foliage: boolean): Promise<Model> => {
+  const key = `${lightmap}\u0000${foliage ? "foliage" : ""}\u0000${source}`
   let template = modelTemplates.get(key)
   if (template === undefined) {
-    template = Model.load(source, { lightmap: mode })
+    template = Model.load(source, { lightmap, foliage })
     modelTemplates.set(key, template)
     // a failed load must not poison the cache — the next node retries
     void template.catch(() => modelTemplates.delete(key))
@@ -472,12 +478,12 @@ const loadModel = (source: string, lightmap: boolean | "dynamic" | undefined): P
   return template.then((t) => t.clone())
 }
 
-const createSource = (path: string, def: SceneNodeDef, lightmap: boolean | "dynamic" | undefined): Node | Promise<Node> => {
+const createSource = (path: string, def: SceneNodeDef, lightmap: boolean): Node | Promise<Node> => {
   const sources = [ def.mesh, def.model, def.light, def.make, def.prefab, def.camera, def.terrain ].filter((s) => s !== undefined).length
   if (sources > 1) throw new Error(`Scene node "${path}" declares more than one source (mesh/model/light/make/prefab/camera/terrain)`)
-  if (def.model !== undefined) return loadModel(def.model, lightmap)
+  if (def.model !== undefined) return loadModel(def.model, lightmap, !!def.foliage)
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
-  if (def.terrain !== undefined) return createTerrain(def.terrain)
+  if (def.terrain !== undefined) return createTerrain(def.terrain, lightmap)
   if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
   // make/prefab/camera/group nodes are plain wrappers — make/prefab subtrees mount under them
   // during the build (attachPrefab) or in phase 2 (attachMake); a camera node drives scene.camera
@@ -531,6 +537,8 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
     if (t && def.receiveShadows !== undefined) t.receiveShadows = def.receiveShadows
   }
   if (def.overrides && def.model !== undefined) applyModelOverrides(node, def.overrides)
+  // the foliage fade is per asset — one node's range is every copy's (the last def wins)
+  if (typeof def.foliage === "object" && def.foliage.fade && node instanceof Model && node._foliage) Foliage.fade(node, def.foliage.fade[0], def.foliage.fade[1])
 }
 
 // ---- edit-mode node markers + the play-mode camera rig -------------------------------------------
@@ -870,6 +878,7 @@ const buildNodes = async (
   lm: LightmapCtx | null = null,
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
+  const moverRoots: Node[] = []
 
   // `parentMoves`: a child of a mover moves with it (the body under the hero's capsule) — it never
   // bakes, whatever its own def says short of an explicit `lightmap: true`
@@ -881,10 +890,9 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const lmStatic = lm !== null && !lm.dynamicOnly && (nd.lightmap ?? (!parentMoves && isLightmapStatic(nd)))
+    const lmStatic = lm !== null && (nd.lightmap ?? (!parentMoves && isLightmapStatic(nd)))
     // a mover in a level with a light volume reads the volume (models: the engine binds it; meshes: registered below)
-    const lmDynamic = lm !== null && !lmStatic && lm.volume
-    const node = await createSource(path, nd, lmStatic ? true : lmDynamic ? "dynamic" : undefined)
+    const node = await createSource(path, nd, lmStatic)
     // a `mount` def parents to an internal part of the parent asset — safe here: the parent's
     // model was awaited and attachPrefab completed before its children build
     if (parentNode) attachHost(parentNode, nd, path).add(node)
@@ -892,11 +900,12 @@ const buildNodes = async (
     scene.add(node)
     applyNode(node, name, nd)   // engine-side name stays the bare sibling segment
     if (lmStatic && (node instanceof Model || node instanceof Mesh)) Lightmap._register(node, lm!.prefix + path)
-    else if (lmStatic && Terrain.of(node)) Lightmap._registerTerrain(Terrain.of(node)!, lm!.prefix + path)
-    else if (lmDynamic && node instanceof Mesh) Lightmap._registerDynamic(node)
+    else if (lmStatic && nd.terrain !== undefined) Lightmap._registerGround(node, lm!.prefix + path)
+    // the top of a moving subtree: everything under it reads the level's light grid (Lightmap.track walks it at load)
+    if (lm !== null && !lmStatic && !parentMoves) moverRoots.push(node)
     if (isEditMode()) addEditorMarker(node, nd)
     // a prefab under a static wrapper bakes; under a mover its internals stay movers (volume-lit)
-    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, volume: lm!.volume } : lm && lm.volume ? { prefix: `${lm.prefix}${path}/`, volume: true, dynamicOnly: true } : null)
+    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/` } : null)
     pending.push({ path, node, def: nd })
     nodes[path] = node
     await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
@@ -926,6 +935,8 @@ const buildNodes = async (
     for (const h of td.holes ?? []) t.hole(h)
     t.commit()
   }
+  // the movers read the level's light grid: their subtrees are whole by now (prefab internals, children)
+  for (const n of moverRoots) Lightmap.track(n)
 }
 
 // ---- navigation (env.navmesh) ------------------------------------------------------------------
@@ -954,14 +965,14 @@ const registerNavOverrides = (defs: Record<string, SceneNodeDef> | undefined, no
 }
 
 const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ scene: Scene, nodes: Record<string, Node> }> => {
-  const { lightmap, navmesh, ...env } = def.env ?? {}
+  const { lightmap, navmesh, foliage, ...env } = def.env ?? {}
   const scene = new Scene(env)
+  // the vegetation tier's level-wide knobs (wind, sway, variation) — before the models load
+  if (foliage) Foliage.configure(foliage)
   const nodes: Record<string, Node> = {}
   // baked lighting is a play-mode concern; the level owns the registry (a rebuild starts clean)
-  const lm: LightmapCtx | null = lightmap && !isEditMode() ? { prefix: "", volume: !!lightmap.volume } : null
+  const lm: LightmapCtx | null = lightmap && !isEditMode() ? { prefix: "" } : null
   if (lm) Lightmap.clear()
-  // with a light volume every model loaded from now on (weapons, spawns, make() subtrees) is a mover by default
-  if (lm) Model._lightmapDefault = lm.volume ? "dynamic" : false
   await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]), lm)
   if (navmesh && !isEditMode()) registerNavOverrides(def.nodes, nodes)
 
@@ -994,9 +1005,8 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
 
   // the level is complete: apply the bake — or, under `lecodes lightmap bake`, run it
   if (lm && lightmap) {
-    await Lightmap.load(scene, { data: lightmap.data, texture: lightmap.texture, light: lightmap.light, volume: lightmap.volume },
-      { sunStrength: lightmap.sunStrength, ambientScale: lightmap.ambientScale, aoStrength: lightmap.aoStrength,
-        lightBoost: lightmap.lightBoost, volumeBoost: lightmap.volumeBoost, occluderShadows: lightmap.occluderShadows })
+    await Lightmap.load(scene, { data: lightmap.data, light: lightmap.light, aux: lightmap.aux, direct: lightmap.direct, indirect: lightmap.indirect, probes: lightmap.probes, volume: lightmap.volume },
+                        { lightScale: lightmap.lightScale, emissiveNits: lightmap.emissiveNits, emissiveBake: lightmap.emissiveBake, transmit: lightmap.transmit })
   }
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)
@@ -1125,7 +1135,7 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
         if (parent) attachHost(parent, d, p).add(existing)
         return existing
       }
-      const node = await createSource(p, d, undefined)
+      const node = await createSource(p, d, false)
       if (parent) attachHost(parent, d, p).add(node)
       scene.add(node)
       applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)

package/src/ui/UIButton.ts

@@ -1,12 +1,12 @@
 import { ClickEvent, TouchStartEvent, LongPressEvent } from "../runtime/touch"
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color, type LayerEasing } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
 /** A tappable container — row + centered children by default. Press feedback via the `onPressed`
  *  style block, the `$pressed` class, or `rippleColor`. */
-export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
   readonly type: "button",
 
   /** Fired on a completed tap/click. */

package/src/ui/UIInput.ts

@@ -1,4 +1,4 @@
-import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
+import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase, type LayerEasing } from "./UINode";
 
 type InputStyle = {
   placeholder?: string,
@@ -51,7 +51,7 @@ type SubmitStyle = {
 
 /** A single-line text input. Keyboard/picker kind via the `type` style, return-key behavior via
  *  `enterKey` + `onSubmit`; keyboard policy on `keyboardShrink`/`keyboardDismiss`. */
-export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
   readonly type: "input",
 
   /**
@@ -78,7 +78,7 @@ export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { on
 }
 
 /** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
-export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
   readonly type: "textarea",
 
   /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */

package/src/ui/UINode.ts

@@ -1,5 +1,8 @@
 import type { FetchResponse } from "../runtime/fetch"
 import { createBinding, disposeBinding } from "../core/signals"
+import type { Animation } from "../animate/tween/Animation"
+import { CLOCK_UI, DOM_UI, KIND_DISCRETE, KIND_TRANSFORM, KIND_TRANSFORM_MATRIX, parseTransformList, uiValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import { tweenBag } from "../animate/tween/Timeline"
 
 export interface UINode {
   readonly type: string
@@ -330,8 +333,13 @@ const classHandler: ProxyHandler<any> = {
  *  static — bindings are extracted at the top level only. */
 export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]) }
 
+/** The curve of a state block's swap (`$class` / `onPressed` / `onFocused` with a `duration`): a
+ *  curve name (`outCubic`, `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)`
+ *  or `steps(n)`. A function cannot ride a style block; use `animateTo` for those. */
+export type LayerEasing = string
+
 /** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
- *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. Class state INHERITS
+ *  from code via the `el.class` proxy; `duration`/`delay`/`easing` animate the swap. Class state INHERITS
  *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
  *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
  *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
@@ -340,7 +348,7 @@ export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T
  *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
  *  `.style()` does, like `onLandscape`. Narrowing it wrongly rejects valid props such as
  *  `$active: { color }`; guarded by tests/ui-types.test.ts. */
-export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number } }
+export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number, easing?: LayerEasing } }
 
 /** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
  *  the class then tracks the signals the function reads (re-evaluated on change). Reads through
@@ -425,28 +433,15 @@ export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationSt
  *  installs a reactive binding). */
 export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
 
-/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
- *  (stripped before the commit into the element's style). */
-export type AnimateStyle<R, T extends object> = ((style: T & {
-  /** Tween length in **milliseconds** (default 225). */
-  duration?: number,
-  /** Wait before starting, in **milliseconds**. A looping animation delays once, not per cycle. */
-  delay?: number,
-  /** Escape hatch: target an internal style layer (the onPressed/orientation mechanism). Not part of the supported surface. */
-  layer?: number,
-  /** `false` = animate without writing the targets into the element's style (e.g. a fade-out right before `.hide()`). */
-  commit?: boolean,
-  /** Repeat the animation: `true` = forever, a number = that many cycles. A looping animation is an
-   *  effect, not a state change — it never commits, and the element ends back at its base style.
-   *  The loop stops when a later `animateTo`/`animateFrom` runs on the element or it leaves the screen. */
-  loop?: boolean | number,
-  /** `"ping-pong"` (default) animates there and back each cycle — no jump. `"restart"` snaps back and
-   *  replays forward — for full-turn spinners (`transform: "rotate(360deg)"`) and shimmers. Only meaningful with `loop`. */
-  loopMode?: "restart" | "ping-pong",
-}) => R)
-
-/** Meta keys of the animateTo/animateFrom options bag — everything that is not a style target. */
-const ANIMATE_META = new Set(["duration", "delay", "layer", "commit", "loop", "loopMode"])
+/** Style props of an animate bag: a single value (tween from the current value) or an array of
+ *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
+export type AnimateProps<T extends object> = { [K in keyof T]?: T[K] | T[K][] }
+
+/** The `animateTo`/`animateFrom` surface: target style props (single values or keyframe arrays) plus
+ *  the flat meta keys — `duration` / `delay` / `easing` / `times` / `loop` / `loopMode` / `commit` /
+ *  `clock`, see {@link TweenMeta}. Returns the {@link Animation} handle (seek, rate, `finished`). */
+export type AnimateStyle<R, T extends object> = ((style: AnimateProps<T> & TweenMeta) => Animation)
+
 
 export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
 export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
@@ -518,20 +513,50 @@ export class Element<T extends string> {
   }
 
   /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
-   *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
-  animateTo(style: any): this{
-    _creatorUI.animateTo(this._id, style)
-    if (style.commit !== false && !style.loop) {
-      for (const key in style) {
-        if (!ANIMATE_META.has(key)) this._style[key] = style[key]
+   *  effect, not a state change). A prop value may be an array of keyframes; meta keys
+   *  `duration`/`delay`/`easing`/`times`/`loop`/… — see {@link AnimateStyle}. Returns the
+   *  {@link Animation} handle. */
+  animateTo(style: any): Animation {
+    // The last keyframe commits into the stored style at play (Animation.play) — reads and later
+    // `.style()` merges see the final state while the host is still tweening, as before.
+    return tweenBag(this, style, true)
+  }
+  /** Tween FROM the given style to the element's current one (entrance animations): the element's
+   *  own style is the implicit last keyframe. Never modifies the stored style. */
+  animateFrom(style: any): Animation {
+    return tweenBag(this, style, false)
+  }
+
+  /** @internal Keyframe-core target protocol (animate/tween/spec.ts): every style prop is a channel
+   *  on the UI domain; `text` is a discrete channel on text elements. */
+  readonly _tweenClock = CLOCK_UI
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null {
+    if (prop === "text") {
+      if (!("text" in this)) return null
+      return {
+        domain: DOM_UI, id: () => this._id,
+        value: (v) => (typeof v === "string" || typeof v === "number" ? { kind: KIND_DISCRETE, str: String(v) } : null),
+        commit: (v) => { (this as any).text = String(v) },
       }
     }
-    return this
-  }
-  /** Tween FROM the given style to the element's current one (entrance animations). */
-  animateFrom(style: any): this{
-    _creatorUI.animateFrom(this._id, style)
-    return this
+    if (prop === "transform") {
+      // A function list tweens per argument when every key shares the list; anything else is handed
+      // to the host as a raw string for matrix decomposition (its old path).
+      return {
+        domain: DOM_UI, id: () => this._id,
+        value: (v) => {
+          if (typeof v !== "string") return null
+          const list = parseTransformList(v)
+          return list ? { kind: KIND_TRANSFORM, sig: list.sig, lanes: list.lanes } : { kind: KIND_TRANSFORM_MATRIX, str: v }
+        },
+        commit: (v) => { this._style.transform = v },
+      }
+    }
+    return {
+      domain: DOM_UI, id: () => this._id, value: uiValue,
+      commit: (v) => { this._style[prop] = v },
+    }
   }
 
   /** @internal Active style-class names (stored without the `$`). Kept on the element — not just in

package/dist/types/animate/animate.d.ts

@@ -1,20 +0,0 @@
-type mat4 = Float32Array | number[];
-type quat = Float32Array | number[];
-type vec2 = Float32Array | number[];
-type vec3 = Float32Array | number[];
-import type { Easing } from "./easings";
-type AnimateProps = number | string | vec2 | vec3 | quat;
-export type AnimateOptions<T> = {
-    from: T;
-    to: T;
-    duration: number;
-    onUpdate(val: T): void;
-    onComplete?(): void;
-    easing?: Easing;
-};
-export declare const animate: <T extends AnimateProps>(options: AnimateOptions<T>) => number;
-export declare const stopAnimation: (id: number) => void;
-export declare const pauseAnimation: (id: number) => void;
-export declare const resumeAnimation: (id: number) => void;
-export declare const animateMat4: (options: AnimateOptions<mat4>) => number;
-export {};