lecodes-sdk 1.0.0 → 1.2.0

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/scene/gizmos.ts

@@ -1,148 +1,148 @@
-// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
-// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
-// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
-// currently executing (an ambient scope the scene loader opens around each synchronous call), and
-// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
-// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
-//
-//   rebuild() {
-//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
-//     for (const p of points) Gizmos.cross(p, 0.07)
-//   }
-//
-// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
-// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
-// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
-//
-// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
-// follows the node live — through a gizmo drag, not only after it — with the node's scale
-// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
-// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
-// accent while selected. World-space calls (path lines) are never pickable.
-
-import { Mat4, type Mat4Like } from "../math/mat4"
-import type { Vec3Like } from "../math/vec"
-
-/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
-export type GizmoAnchor = { readonly id: number }
-
-export type GizmoStyle = {
-  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
-  color?: string
-  /** 0..1, default 1. */
-  alpha?: number
-  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
-   *  live, are pickable (a click selects the node) and turn the selection accent when it is
-   *  selected. Omit for world-space lines (not pickable). */
-  node?: GizmoAnchor | null
-}
-
-/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
- *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
-export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
-
-const DEFAULT_COLOR = "#cfd4dd"
-
-/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
- *  hundred same-colored segments cost one draw. */
-export class GizmoBuffer {
-  batches: GizmoBatch[] = []
-  private _byStyle = new Map<string, GizmoBatch>()
-
-  clear(): void {
-    this.batches = []
-    this._byStyle.clear()
-  }
-
-  segments(style: GizmoStyle | undefined): number[] {
-    const color = style?.color ?? DEFAULT_COLOR
-    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
-    const entityId = style?.node?.id
-    const key = `${color}@${alpha}@${entityId ?? ""}`
-    let b = this._byStyle.get(key)
-    if (!b) {
-      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
-      this._byStyle.set(key, b)
-      this.batches.push(b)
-    }
-    return b.segments
-  }
-}
-
-let current: GizmoBuffer | null = null
-let warnedOutOfScope = false
-
-const xyz = (p: Vec3Like): [number, number, number] =>
-  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
-
-const target = (style: GizmoStyle | undefined): number[] | null => {
-  if (current) return current.segments(style)
-  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
-    warnedOutOfScope = true
-    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
-  }
-  return null
-}
-
-/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
- *  restore the outer one. */
-export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
-  const prev = current
-  buffer.clear()
-  current = buffer
-  try { return fn() } finally { current = prev }
-}
-
-/**
- * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
- * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
- * off — a path through a wall is still a path); invisible everywhere else.
- */
-export const Gizmos = {
-  /** One segment from `a` to `b`. */
-  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    out.push(...xyz(a), ...xyz(b))
-  },
-
-  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
-  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
-    if (points.length < 2) return
-    const out = target(style)
-    if (!out) return
-    const n = points.length
-    const last = style?.closed ? n : n - 1
-    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
-  },
-
-  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
-   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
-   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
-   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
-  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
-    const out = target(style)
-    if (!out) return
-    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
-    const m = style?.matrix ? new Mat4(style.matrix) : null
-    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
-    const P = (x: number, y: number, zz: number): [number, number, number] => {
-      if (!m) return [ x, y, zz ]
-      const v = m.transformPoint([ x, y, zz ])
-      return [ v.x, v.y, v.z ]
-    }
-    const o = P(0, 0, 0)
-    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
-    for (const q of c) out.push(...o, ...q)
-    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
-    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
-  },
-
-  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
-  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    const [ x, y, z ] = xyz(p)
-    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
-  },
-}
+// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
+// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
+// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
+// currently executing (an ambient scope the scene loader opens around each synchronous call), and
+// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
+// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
+//
+//   rebuild() {
+//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
+//     for (const p of points) Gizmos.cross(p, 0.07)
+//   }
+//
+// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
+// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
+// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
+//
+// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
+// follows the node live — through a gizmo drag, not only after it — with the node's scale
+// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
+// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
+// accent while selected. World-space calls (path lines) are never pickable.
+
+import { Mat4, type Mat4Like } from "../math/mat4"
+import type { Vec3Like } from "../math/vec"
+
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = { readonly id: number }
+
+export type GizmoStyle = {
+  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
+  color?: string
+  /** 0..1, default 1. */
+  alpha?: number
+  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+   *  live, are pickable (a click selects the node) and turn the selection accent when it is
+   *  selected. Omit for world-space lines (not pickable). */
+  node?: GizmoAnchor | null
+}
+
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
+ *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
+
+const DEFAULT_COLOR = "#cfd4dd"
+
+/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
+ *  hundred same-colored segments cost one draw. */
+export class GizmoBuffer {
+  batches: GizmoBatch[] = []
+  private _byStyle = new Map<string, GizmoBatch>()
+
+  clear(): void {
+    this.batches = []
+    this._byStyle.clear()
+  }
+
+  segments(style: GizmoStyle | undefined): number[] {
+    const color = style?.color ?? DEFAULT_COLOR
+    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
+    const entityId = style?.node?.id
+    const key = `${color}@${alpha}@${entityId ?? ""}`
+    let b = this._byStyle.get(key)
+    if (!b) {
+      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
+      this._byStyle.set(key, b)
+      this.batches.push(b)
+    }
+    return b.segments
+  }
+}
+
+let current: GizmoBuffer | null = null
+let warnedOutOfScope = false
+
+const xyz = (p: Vec3Like): [number, number, number] =>
+  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
+
+const target = (style: GizmoStyle | undefined): number[] | null => {
+  if (current) return current.segments(style)
+  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
+    warnedOutOfScope = true
+    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
+  }
+  return null
+}
+
+/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
+ *  restore the outer one. */
+export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
+  const prev = current
+  buffer.clear()
+  current = buffer
+  try { return fn() } finally { current = prev }
+}
+
+/**
+ * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
+ * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
+ * off — a path through a wall is still a path); invisible everywhere else.
+ */
+export const Gizmos = {
+  /** One segment from `a` to `b`. */
+  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    out.push(...xyz(a), ...xyz(b))
+  },
+
+  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
+  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
+    if (points.length < 2) return
+    const out = target(style)
+    if (!out) return
+    const n = points.length
+    const last = style?.closed ? n : n - 1
+    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
+  },
+
+  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
+    const out = target(style)
+    if (!out) return
+    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
+    const m = style?.matrix ? new Mat4(style.matrix) : null
+    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
+    const P = (x: number, y: number, zz: number): [number, number, number] => {
+      if (!m) return [ x, y, zz ]
+      const v = m.transformPoint([ x, y, zz ])
+      return [ v.x, v.y, v.z ]
+    }
+    const o = P(0, 0, 0)
+    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
+    for (const q of c) out.push(...o, ...q)
+    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
+    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
+  },
+
+  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
+  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    const [ x, y, z ] = xyz(p)
+    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
+  },
+}

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