lecodes-cli 0.18.2 → 0.19.0

package/runtime/sdk/scene/defineScene.ts

@@ -48,6 +48,8 @@ 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 { Light, type SunOptions } from "../gl/Light"
 import { assignMaterialDef, MaterialHandle, resolveMaterialDef, type MaterialDef } from "./material"
 import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
@@ -63,6 +65,34 @@ export type MeshDef =
 
 export type LightDef = { kind: "sun" } & SunOptions
 
+/** A stamp: the terrain conforms to another node of this file (a road) at load — see Terrain.conform. */
+export type TerrainStampDef = {
+  /** Path of the node (a Mesh, a Model, or a node holding them) the ground hugs. */
+  node: string
+  offset?: number
+  falloff?: number
+  mode?: "both" | "lower" | "raise"
+}
+
+/** The `terrain: {}` source block (docs/terrain-plan.md §3.3): a `.terrain` file OR a flat grid to
+ *  generate from, its layers, and the stamps / holes applied at load (in order, after every node of the
+ *  file exists — a road built by `make()` is a valid target). Add `Shape { heightfield: true }` +
+ *  `Physics { motion: 'static' }` in `aspects` for collision. */
+export type TerrainNodeDef = {
+  /** `asset('./assets/terrain/valley.terrain')` — heights / holes / control from a file. */
+  data?: string
+  size?: number
+  sizeX?: number
+  sizeZ?: number
+  cellSize?: number
+  chunk?: number
+  layers?: TerrainLayer[]
+  normals?: TerrainOptions["normals"]
+  tint?: TerrainOptions["tint"]
+  stamps?: TerrainStampDef[]
+  holes?: TerrainRegion[]
+}
+
 // The material grammar (`{ lit }` / `{ unlit }` / `{ shadow }` / `{ shader, params }` / a
 // material asset handle / a code instance) lives in ./material.ts — re-exported for callers.
 export type { MaterialDef }
@@ -108,6 +138,8 @@ export type SceneNodeDef = {
   /** GLB url — `asset('./hero.glb')`. */
   model?: string
   light?: LightDef
+  /** A heightmap ground — see {@link TerrainNodeDef}. */
+  terrain?: TerrainNodeDef
   /** The scene camera as a NODE: in play mode `scene.camera` follows this node's world transform
    *  every frame (so movement aspects on it are camera flythroughs); the editor shows a frustum
    *  marker and refuses to delete the last camera node. The first camera node in file order wins;
@@ -141,6 +173,8 @@ export type SceneNodeDef = {
    *  (`time` freezes it at that second instead), so attachments / sight lines / a first-person eye
    *  are placed against the animated pose, not the rest pose. Never applied when the scene runs. */
   editor?: { clip?: string, time?: number }
+  /** `mesh` / `model` nodes: real-time shadow flags. On a `model` they reach every renderable of
+   *  the GLB instance, so `castShadows: false` on a first-person viewmodel covers the whole gun. */
   castShadows?: boolean
   receiveShadows?: boolean
   /** Baked lighting (a scene with `env.lightmap`): is this model/mesh node a lightmap STATIC — a
@@ -148,6 +182,12 @@ 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
+  /** 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). */
+  nav?: false | "unwalkable"
+  /** The named navmesh area this static body's surface belongs to (a key of `env.navmesh.areas`). */
+  navArea?: string
   // -- capabilities / hierarchy --
   aspects?: readonly AspectEntry<any>[]
   children?: Record<string, SceneNodeDef>
@@ -166,14 +206,29 @@ export type SceneLightmapDef = {
   data: string
   /** `asset('./assets/lightmap/lightmap.ktx2')` */
   texture: 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. */
+  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
 }
 
+/** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
+ *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
+export type SceneNavmeshDef = {
+  /** `asset('./assets/nav/<scene>.navmesh')` */
+  data: string
+  /** The agent the mesh is built for (radius 0.4 · height 1.8 · climb 0.4 · slope 50 by default). */
+  agent?: { radius?: number, height?: number, climb?: number, slope?: number }
+  /** Named areas → traversal cost (1 = plain ground); nodes join one with `navArea`. */
+  areas?: Record<string, number>
+}
+
 export type SceneDef = {
-  env?: SceneOptions & { lightmap?: SceneLightmapDef }
+  env?: SceneOptions & { lightmap?: SceneLightmapDef, navmesh?: SceneNavmeshDef }
   camera?: SceneCameraDef
   nodes?: Record<string, SceneNodeDef>
 }
@@ -344,7 +399,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 }
+type LightmapCtx = { prefix: string, volume: boolean, dynamicOnly?: boolean }
 
 const movesByPhysics = (def: SceneNodeDef): boolean =>
   (def.aspects ?? []).some((e) =>
@@ -353,11 +408,23 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
 /** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
 export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap ?? !movesByPhysics(def)
 
-const createSource = (path: string, def: SceneNodeDef, lightmap = false): Node | Promise<Node> => {
-  const sources = [ def.mesh, def.model, def.light, def.make, def.prefab, def.camera ].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)`)
+// `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 t = data !== undefined ? await Terrain.load(data, opts) : Terrain.create(opts)
+  await t.ready
+  return t.node
+}
+
+const createSource = (path: string, def: SceneNodeDef, lightmap: boolean | "dynamic" | undefined): 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 Model.load(def.model, { lightmap })
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
+  if (def.terrain !== undefined) return createTerrain(def.terrain)
   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
@@ -400,9 +467,15 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   // waypoint/def order for aspects that read children (FollowPath) — the engine's live child
   // order is insertion-based and may not match the file
   if (def.children) (node as { _sceneChildOrder?: string[] })._sceneChildOrder = Object.keys(def.children)
-  if (node instanceof Mesh) {
+  // shadow flags: a Mesh has one renderable, a Model a whole GLB instance (Model routes the pair
+  // through setGlbShadows) — every other node kind is transform-only and carries none
+  if (node instanceof Mesh || node instanceof Model) {
     if (def.castShadows !== undefined) node.castShadows = def.castShadows
     if (def.receiveShadows !== undefined) node.receiveShadows = def.receiveShadows
+  } else if (def.terrain !== undefined) {
+    const t = Terrain.of(node)
+    if (t && def.castShadows !== undefined) t.castShadows = def.castShadows
+    if (t && def.receiveShadows !== undefined) t.receiveShadows = def.receiveShadows
   }
   if (def.overrides && def.model !== undefined) applyModelOverrides(node, def.overrides)
 }
@@ -412,7 +485,7 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
 /** True for a def with no source block at all — a plain group ("Empty" in the editor). */
 const isGroupDef = (def: SceneNodeDef): boolean =>
   def.mesh === undefined && def.model === undefined && def.light === undefined
-  && def.make === undefined && def.prefab === undefined && def.camera === undefined
+  && def.make === undefined && def.prefab === undefined && def.camera === undefined && def.terrain === undefined
 
 /** Edit mode: otherwise-invisible nodes (empties, `camera:` nodes) get an ANCHORED gizmo marker —
  *  an axis cross / a frustum in the node's local frame (scene/gizmos.ts) — so they show and pick
@@ -753,8 +826,10 @@ 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 && isLightmapStatic(nd)
-    const node = await createSource(path, nd, lmStatic)
+    const lmStatic = lm !== null && !lm.dynamicOnly && 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)
     // 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)
@@ -762,8 +837,11 @@ 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)
     if (isEditMode()) addEditorMarker(node, nd)
-    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/` } : null)
+    // 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)
     pending.push({ path, node, def: nd })
     nodes[path] = node
     await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path)))
@@ -778,16 +856,59 @@ const buildNodes = async (
     if (wait) makeWaits.push(wait)
   }
   if (makeWaits.length > 0) await Promise.all(makeWaits)
+
+  // terrain stamps + holes: every node of the file exists now (make() subtrees included), and a
+  // Shape { heightfield } attached above takes the edits through commit() (an in-place SetHeights)
+  for (const p of pending) {
+    const td = p.def.terrain
+    const t = td ? Terrain.of(p.node) : null
+    if (!td || !t || (!td.stamps?.length && !td.holes?.length)) continue
+    for (const s of td.stamps ?? []) {
+      const target = nodes[s.node]
+      if (!target) { console.warn(`[scene] "${p.path}".terrain stamp "${s.node}" matches no node — skipped`); continue }
+      t.conform(target, { offset: s.offset, falloff: s.falloff, mode: s.mode })
+    }
+    for (const h of td.holes ?? []) t.hole(h)
+    t.commit()
+  }
+}
+
+// ---- navigation (env.navmesh) ------------------------------------------------------------------
+// Walkable = every STATIC Physics body (what the CharacterController collides with), derived like
+// the lightmap statics — no per-node declaration. `nav: false | 'unwalkable'` and `navArea` are the
+// per-node overrides, keyed by the node's entity for the bake (NavMesh.exclude / unwalkable / area).
+// Prefab internals are not walked (v1): override them in the prefab's own file.
+
+const forEachNodeDef = (defs: Record<string, SceneNodeDef> | undefined, prefix: string, fn: (path: string, def: SceneNodeDef) => void): void => {
+  for (const [ key, d ] of Object.entries(defs ?? {})) {
+    const path = prefix ? `${prefix}/${key}` : key
+    fn(path, d)
+    forEachNodeDef(d.children, path, fn)
+  }
+}
+
+const registerNavOverrides = (defs: Record<string, SceneNodeDef> | undefined, nodes: Record<string, Node>): void => {
+  NavMesh.clear()
+  forEachNodeDef(defs, "", (path, d) => {
+    const node = nodes[path]
+    if (!node) return
+    if (d.nav === false) NavMesh.exclude(node)
+    else if (d.nav === "unwalkable") NavMesh.unwalkable(node)
+    else if (d.navArea) NavMesh.area(node, d.navArea)
+  })
 }
 
 const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ scene: Scene, nodes: Record<string, Node> }> => {
-  const { lightmap, ...env } = def.env ?? {}
+  const { lightmap, navmesh, ...env } = def.env ?? {}
   const scene = new Scene(env)
   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: "" } : null
+  const lm: LightmapCtx | null = lightmap && !isEditMode() ? { prefix: "", volume: !!lightmap.volume } : 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)
 
   // a camera NODE wins over the top-level `camera:` block; in play mode it keeps driving the view
   // (CameraRig), in edit mode it only seeds the editor's starting viewpoint. The PROJECTION applies
@@ -818,9 +939,14 @@ 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 },
+    await Lightmap.load(scene, { data: lightmap.data, texture: lightmap.texture, volume: lightmap.volume },
       { sunStrength: lightmap.sunStrength, ambientScale: lightmap.ambientScale })
   }
+  // 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)
+  if (navmesh && !isEditMode()) {
+    await NavMesh.load(scene, { data: navmesh.data, agent: navmesh.agent, areas: navmesh.areas })
+  }
 
   return { scene, nodes }
 }
@@ -943,7 +1069,7 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
         if (parent) attachHost(parent, d, p).add(existing)
         return existing
       }
-      const node = await createSource(p, d)
+      const node = await createSource(p, d, undefined)
       if (parent) attachHost(parent, d, p).add(node)
       scene.add(node)
       applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)

package/runtime/sdk/scene/editorPlugins.ts

@@ -52,6 +52,15 @@ export type EditorApi = {
   raycast(screenX: number, screenY: number): EditorRayHit | null
   /** Group every doc edit inside `fn` into ONE undo step. */
   transact(fn: () => void): void
+  /** Read one def prop of a node as document data (`asset()` refs come as `{ $asset: "./x" }`);
+   *  undefined when the node or key doesn't exist. */
+  getProp(path: string, key: string): unknown
+  /** Write a BINARY asset file for a node (a terrain's `.terrain`, a baked mask…). `ref` = the
+   *  node's existing def-relative `asset()` ref to overwrite, or null to create `./<name>` at the
+   *  project root (a free name is picked on collisions). Resolves to the ref to store in the node's
+   *  def (`{ $asset: ref }` via `setProp`), null when the host can't write files. Not a doc edit —
+   *  it is not undoable; keep the doc pointing at the file. */
+  writeAsset(path: string, ref: string | null, name: string, bytes: Uint8Array): Promise<string | null>
 }
 
 export type EditorWindowFn = (ui: InspectorUI, editor: EditorApi) => void
@@ -65,6 +74,15 @@ export type EditorToolHooks = {
   /** A viewport click while the tool is active — `hit` is the raycast result under the pointer.
    *  Viewport clicks route to the tool while it is active. */
   onViewportClick?(hit: EditorRayHit, editor: EditorApi): void
+  /** Drag tools (brushes): a primary-button drag in the viewport routes here instead of orbiting
+   *  the camera — start / every pointer move (with the hit under it, null while off-world) /
+   *  release. A tool with `onDragStart` gets NO `onViewportClick` for the same gesture. */
+  onDragStart?(hit: EditorRayHit, editor: EditorApi): void
+  onDrag?(hit: EditorRayHit | null, editor: EditorApi): void
+  onDragEnd?(editor: EditorApi): void
+  /** The pointer moved over the viewport with no button down (throttled to the frame) — draw a
+   *  brush cursor through `Gizmos`; null when nothing is under it. */
+  onHover?(hit: EditorRayHit | null, editor: EditorApi): void
 }
 
 /** @internal The registry the scene-editor harness reads (windows/tools in registration order). */

package/runtime/sdk/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/runtime/sdk/ui/UINode.ts

@@ -26,6 +26,10 @@ export type Color = number | string | null
 export type BaseStyle = {
   opacity?: number | `${number}`,
   transform?: string | null,
+  /** Pivot of `transform` (CSS `transform-origin` subset): one or two values, each a keyword
+   *  (`left`/`center`/`right`, `top`/`center`/`bottom`), a percentage of the box, or a px length
+   *  (bare numbers are px). One value sets x, y stays `50%`. Default `"50% 50%"` = the centre. */
+  transformOrigin?: string | null,
   backgroundColor?: Color | null,
   bgColor?: Color | null,
   overflow?: "visible" | "hidden",