lecodes-sdk 0.20.2 → 1.1.0

package/src/scene/defineScene.ts

@@ -46,13 +46,16 @@ import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
-import { Physics } from "../gl/Physics"
-import { Lightmap } from "../gl/Lightmap"
-import { NavMesh } from "../gl/NavMesh"
-import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/Terrain"
+import { Physics } from "../gl/physics/Physics"
+import { CharacterController } from "../gl/physics/CharacterController"
+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 { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
+import type { CapsuleOptions, CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
 import { GizmoBuffer, Gizmos, withGizmoScope, type GizmoBatch } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
@@ -61,6 +64,7 @@ export type MeshDef =
   | { kind: "box", size?: Vec3Like | number }
   | ({ kind: "sphere" } & SphereOptions)
   | ({ kind: "cylinder" } & CylinderOptions)
+  | ({ kind: "capsule" } & CapsuleOptions)
   | ({ kind: "plane" } & PlaneOptions)
 
 export type LightDef = { kind: "sun" } & SunOptions
@@ -182,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). */
@@ -199,37 +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
+  /** 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`
@@ -244,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>
 }
@@ -402,6 +417,7 @@ const createMesh = async (def: MeshDef, material?: MaterialDef): Promise<Mesh> =
     case "box": mesh = Mesh.box({ size: def.size, material: mat }); break
     case "sphere": { const { kind: _k, ...opts } = def; mesh = Mesh.sphere({ ...opts, material: mat }); break }
     case "cylinder": { const { kind: _k, ...opts } = def; mesh = Mesh.cylinder({ ...opts, material: mat }); break }
+    case "capsule": { const { kind: _k, ...opts } = def; mesh = Mesh.capsule({ ...opts, material: mat }); break }
     case "plane": { const { kind: _k, ...opts } = def; mesh = Mesh.plane({ ...opts, material: mat }); break }
   }
   if (material instanceof MaterialHandle) material._users.add({ node: mesh, slot: 0 })
@@ -415,21 +431,25 @@ 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).
 const movesByPhysics = (def: SceneNodeDef): boolean =>
   (def.aspects ?? []).some((e) =>
-    (e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
+    || (e.ctor as unknown) === CharacterController)
 
-/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
+ *  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
@@ -446,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))
@@ -461,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
@@ -520,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 -------------------------------------------
@@ -859,8 +878,11 @@ const buildNodes = async (
   lm: LightmapCtx | null = null,
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
+  const moverRoots: Node[] = []
 
-  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string): Promise<void> => {
+  // `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`
+  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string, parentMoves = false): Promise<void> => {
     // names are path segments — '/' would fork the path, ':' would ambiguate editor card keys
     if (name === "" || name.includes("/") || name.includes(":")) {
       throw new Error(`Scene node name "${name}" is invalid — names are non-empty and contain no '/' or ':'`)
@@ -868,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 && 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)
@@ -879,14 +900,15 @@ 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)))
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
   }
 
   await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
@@ -913,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) ------------------------------------------------------------------
@@ -941,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)
 
@@ -981,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 })
+    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)
@@ -1112,11 +1135,14 @@ 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)
       if (isEditMode()) addEditorMarker(node, d)
+      // a prefab wrapper instantiates its file's nodes (same path as buildNodes; no lightmap
+      // context — a patched node is an edit-mode rebuild, baked lighting is the level's business)
+      if (d.prefab !== undefined) await attachPrefab(node, p, d, scene, new Set([ this.def ]), null)
       attachAspects(node, p, d, nodes, scene, this._editorRuns)
       nodes[p] = node
       await Promise.all(Object.entries(d.children ?? {}).map(([ cn, cd ]) => build(`${p}/${cn}`, cd, node)))

package/src/scene/level.ts

@@ -14,8 +14,8 @@
 
 import { Node } from "../gl/Node"
 import { Model } from "../gl/Model"
-import { Shape } from "../gl/Shape"
-import { Physics } from "../gl/Physics"
+import { Shape } from "../gl/physics/Shape"
+import { Physics } from "../gl/physics/Physics"
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
 
 /** One placement handed to a `build` function (all coordinates local to the group). */

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 {};

package/dist/types/gl/Gearbox.d.ts

@@ -1,86 +0,0 @@
-import { Aspect } from "../core/Aspect";
-import type { FieldMeta } from "../core/fields";
-import type { Node } from "./Node";
-import type { Vehicle } from "./Vehicle";
-export declare class Gearbox extends Aspect<"gearbox", Node> {
-    static readonly aspect = "gearbox";
-    /** Forward gear ratios, first gear first. Engine RPM = wheel speed × ratio × the differential. */
-    ratios: number[];
-    /** Reverse ratio — negative, because a ratio's SIGN is what reverse means to the engine. */
-    reverse: number;
-    /** Shift up when the engine passes this fraction of its redline. */
-    shiftUp: number;
-    /** Shift down when it falls below this fraction. */
-    shiftDown: number;
-    /** How long a shift takes, in seconds — the clutch is out for this long. */
-    shiftTime: number;
-    /** How long the clutch takes to re-engage afterwards. */
-    clutchTime: number;
-    /** How long to wait after a shift before another is allowed — without it a car sitting on a
-     *  threshold hunts between two gears. */
-    latency: number;
-    /** How far the clutch bites the instant drive is asked for from rest, 0..1. It only has to COUPLE
-     *  the shafts — how much torque that passes is the engine's business, so a feathered throttle
-     *  still pulls away gently at the same bite point. */
-    bite: number;
-    static fields: FieldMeta<Gearbox>;
-    /** Current gear: −1 reverse, 0 neutral, 1… forward. Read it for a HUD. */
-    gear: number;
-    /** True while a shift is in progress — the clutch is out and the engine is not driving the wheels. */
-    get shifting(): boolean;
-    private _shiftLeft;
-    private _engageLeft;
-    private _waitLeft;
-    private _take;
-    /** EARLY phase: the pair has to be latched before this frame's step consumes it. */
-    updateBefore(dt: number): void;
-    /**
-     * The driver's left foot: where the clutch pedal is, ignoring shifts. Returns the new engagement.
-     *
-     * A driver does not compute anything. They watch the tacho: **revs sinking to idle means the
-     * wheels are about to drag the engine under, and that is when you push the clutch in.** That
-     * single test replaces every ratio and threshold — the crossover it finds is the exact speed where
-     * engine braking stops and the engine would start PUSHING instead, and it finds it per gear
-     * without being told the gear.
-     *
-     * The pedal comes back UP only for the throttle. Healthy revs are not on their own a reason to
-     * engage: a car standing still shows healthy revs too — the wheels simply are not turning to say
-     * otherwise — and a clutch dropped on that evidence lurches the car off with no throttle at all.
-     *
-     * Three things fall out of it for free:
-     *
-     * - **A braked car stops.** The engine cannot stall, so a clutch left in at 0 km/h feeds idle
-     *   torque to the wheels forever and the car creeps against its own brakes. Here the revs pin at
-     *   idle, so the pedal goes down and the brakes have nothing to fight.
-     * - **Reverse is not a special case.** No ratio takes part, so it needs no separate number — which
-     *   is exactly why a fixed road-speed threshold got reverse wrong.
-     * - **Hill starts judder instead of stalling.** Let the pedal out, the load pulls the revs down,
-     *   the rule pushes it straight back in, and the clutch sits slipping at the bite point until the
-     *   car moves. So the test deliberately ignores the throttle — gating it on "no throttle" would
-     *   stall the car under load. Throttle only holds the floor at `bite`.
-     *
-     * The cost is honest and small: once the pedal is down the revs sit at idle and cannot rise on
-     * their own, so **coasting downhill gives no engine braking until you touch the throttle** — which
-     * is precisely what a car with the clutch in does. Slipping it permanently to keep listening would
-     * bring the creep straight back.
-     */
-    protected takeUp(v: Vehicle, dt: number): number;
-    /**
-     * Which gear the car should be in. The default is an ordinary automatic: pull away from neutral in
-     * the direction of the throttle, shift up past `shiftUp` of the redline and down below `shiftDown`,
-     * and refuse to shift again for `latency` seconds. Override this and nothing else.
-     */
-    select(v: Vehicle): number;
-    /** Change gear now, with the clutch envelope. Safe to call from `select()` or from game code
-     *  (a sequential manual is `if (Input.key('KeyE')) car.gearbox.shift(car.gearbox.gear + 1)`). */
-    shift(gear: number): void;
-    /** The ratio the engine should be running: 0 in neutral, negative in reverse. */
-    get ratio(): number;
-    /**
-     * The clutch scalar 0..1 the engine is given: the SHIFT envelope (out during a shift, ramping back
-     * over `clutchTime`) times the driver's pedal (`takeUp`). Two independent reasons for the clutch
-     * to be out, so they multiply: mid-shift is out however healthy the revs are, and an engine being
-     * dragged to idle is out whatever gear it just picked.
-     */
-    get clutch(): number;
-}