lecodes-sdk 1.2.0 → 2.0.1

package/src/scene/defineScene.ts

@@ -31,14 +31,18 @@
 // sources are instantiated for real so the viewport shows the scene, but aspects are held as data
 // (`node._sceneAspects`) WITHOUT attaching — no onAttach side effects (physics bodies, timers), no
 // update() ticks. Defined handles register on `globalThis.__lecodesScenes` for the host to pick up.
+//
+// Edit mode exists in EDITOR BUNDLES only. Every edit-mode branch here reads `EDITOR && isEditMode()`
+// — `EDITOR` is the compile-time half (bundler.ts: `false` in a shipped bundle, where chisel folds
+// the branch away and tree-shakes what only it reached), the flag the run-time one. What the editor
+// DOES to a loaded scene (patch / rename / live props / inspector cards) is not here at all: it is
+// ./editor.ts, which only an editor bundle injects. The `@internal` exports below are its seam.
 
-import { Aspect, type AspectCtor, type With } from "../core/Aspect"
-import { describeAspect, describeFields, type AspectClassInfo } from "../core/fields"
+import { Aspect, type With } from "../core/Aspect"
 import {
   collectRefDeps, isEditMode, isNodeRef, resolveRefPath, resolveRefs, use, ref, make, EDIT_FLAG,
   type AspectEntry, type MakeEntry as SharedMakeEntry,
 } from "./grammar"
-import { InspectorUI, type InspectorEvent, type InspectorWidget } from "../core/InspectorUI"
 import type { Vec3Like } from "../math/vec"
 import { Scene, type SceneOptions } from "../gl/Scene"
 import { CAMERA_DEFAULTS } from "../gl/Camera"
@@ -56,7 +60,7 @@ 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"
+import { GizmoBuffer, Gizmos, withGizmoScope } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
 
@@ -207,7 +211,7 @@ export type SceneCameraDef = CameraProjectionDef & {
   target?: Vec3Like
 }
 
-/** `env.lightmap` — the level's baked lighting (packages/creator-bake): the files `lecodes lightmap bake`
+/** `env.lightmap` — the level's baked lighting (engines/bake): the files `lecodes lightmap bake`
  *  writes. Absent = real-time only. */
 export type SceneLightmapDef = {
   /** `asset('./assets/lightmap/level.bake')` */
@@ -312,7 +316,7 @@ export type LoadedScene<D extends SceneDef> = {
 // A model's internal hierarchy is addressed by PART PATHS — '/'-joined segments from the model
 // root down, where a segment is the child's name, disambiguated as `name[i]` among same-named
 // siblings and `[i]` for unnamed children (i = index within that same-named group). The editor
-// enumerates rows via `SceneHandle._modelParts` and writes the paths as `overrides` keys; the
+// enumerates rows via `sceneEditor.modelParts` (./editor.ts) and writes the paths as `overrides` keys; the
 // loader resolves them back through the same enumeration, so writer and resolver can't drift.
 
 /** One instance of a scene file built as a subtree (`handle.instantiate`). */
@@ -402,7 +406,7 @@ const resolveMountNode = (parent: Node, mountPath: string, ownerPath: string): N
 }
 
 /** Where a def node attaches: its `mount` part when it resolves, else the parent itself. */
-const attachHost = (parent: Node, def: SceneNodeDef, path: string): Node =>
+export const attachHost = (parent: Node, def: SceneNodeDef, path: string): Node =>
   def.mount !== undefined ? resolveMountNode(parent, def.mount, path) ?? parent : parent
 
 // ---- runtime -------------------------------------------------------------------
@@ -478,7 +482,8 @@ const loadModel = (source: string, lightmap: boolean, foliage: boolean): Promise
   return template.then((t) => t.clone())
 }
 
-const createSource = (path: string, def: SceneNodeDef, lightmap: boolean): Node | Promise<Node> => {
+/** @internal */
+export 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, !!def.foliage)
@@ -510,7 +515,8 @@ export const applyEditorPose = (node: Node, pose: { clip?: string, time?: number
   }
 }
 
-const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
+/** @internal */
+export const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   node.name = name
   // def-built marker: part enumeration must skip this node (it is not asset-internal — it has
   // its own def path), even when it is parented inside a model via `mount`
@@ -520,8 +526,8 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   if (def.scale !== undefined) node.scale = def.scale
   if (def.visible !== undefined) node.visible = def.visible
   // editor-only flag (the harness's manipulation layer consults it); inert at runtime
-  if (def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
-  if (def.editor !== undefined && isEditMode()) applyEditorPose(node, def.editor)
+  if (EDITOR && def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
+  if (EDITOR && def.editor !== undefined && isEditMode()) applyEditorPose(node, def.editor)
   if (def.camera !== undefined) (node as { _sceneCamera?: boolean })._sceneCamera = true
   // waypoint/def order for aspects that read children (FollowPath) — the engine's live child
   // order is insertion-based and may not match the file
@@ -552,9 +558,9 @@ const isGroupDef = (def: SceneNodeDef): boolean =>
  *  an axis cross / a frustum in the node's local frame (scene/gizmos.ts) — so they show and pick
  *  in the viewport. Never scene content: nothing renders in Filament, nothing outlines, and the
  *  engine follows the node live, so the buffer is filled once and lives on the node
- *  (`_editorMarker`) — `_editorGizmos()` reads it off the handle's own def nodes, so a removed
+ *  (`_editorMarker`) — `sceneEditor.gizmos()` reads it off the handle's own def nodes, so a removed
  *  node's marker goes with its record and prefab / instance internals (not selectable) draw none. */
-const addEditorMarker = (node: Node, def: SceneNodeDef): void => {
+export const addEditorMarker = (node: Node, def: SceneNodeDef): void => {
   const buffer = new GizmoBuffer()
   if (def.camera !== undefined) {
     withGizmoScope(buffer, () => Gizmos.frustum(def.camera?.fov ?? CAMERA_DEFAULTS.fov, { node, color: "#cfd4dd" }))
@@ -603,7 +609,7 @@ const findCamera = (defs?: Record<string, SceneNodeDef>, prefix = ""): { path: s
 /** fov / near / far from a camera block onto the live camera. The build path leaves an empty block
  *  alone (a host may run with its own configured fov); `reset` — the editor's live patch — fills
  *  omitted keys with the defaults instead, so clearing a field in the inspector takes effect. */
-const applyCameraProjection = (scene: Scene, def: CameraProjectionDef, reset = false): void => {
+export const applyCameraProjection = (scene: Scene, def: CameraProjectionDef, reset = false): void => {
   const { fov, near, far } = def
   if (!reset && fov === undefined && near === undefined && far === undefined) return
   scene.camera.setProjection(reset
@@ -614,8 +620,8 @@ const applyCameraProjection = (scene: Scene, def: CameraProjectionDef, reset = f
 // ---- editor-run aspects (generators) ------------------------------------------------------------
 // A class with `static editor = { rebuild: true }` runs while a scene is edited: the loader
 // constructs it (refs resolved, node + `generated` set — NEVER onAttach) and calls rebuild(); the
-// editor re-runs rebuild() on inspector prop edits (`_editorSetProp`) and whenever a node its
-// ref() fields point at changes (`_editorNodeChanged` — dep tracking is derived from the props).
+// editor re-runs rebuild() on inspector prop edits (`sceneEditor.setProp`, ./editor.ts) and whenever a
+// node its ref() fields point at changes (`sceneEditor.nodeChanged` — dep tracking is derived from the props).
 // Generated output lives under `this.generated`, a scene-added container child: never written to
 // the file, absent from the doc tree — the file stores the recipe, the viewport shows the result.
 
@@ -637,7 +643,7 @@ class GeneratedGroup extends Node {
   clear(): this {
     this.version++
     for (const c of [ ...this.children ]) {
-      dropForeignRuns(c)
+      if (EDITOR) dropForeignRuns(c)
       this._scene.remove(c)
       c.destroy()
     }
@@ -649,7 +655,7 @@ class GeneratedGroup extends Node {
 // arms' gun socket) are not the edited handle's runs — not inspector-addressable, not
 // dep-tracked — but their gizmos (the weapon's sight line) must still draw. They register here
 // keyed by the instance root; `dispose()` / a hosting `generated.clear()` drops them.
-const foreignRuns = new Map<Node, EditorRun[]>()
+export const foreignRuns = new Map<Node, EditorRun[]>()
 const dropForeignRuns = (root: Node): void => {
   for (const key of [ ...foreignRuns.keys() ]) {
     let n: Node | null = key
@@ -668,7 +674,7 @@ const makeGenerated = (node: Node, scene: Scene): GeneratedGroup => {
 }
 
 /** One live editor-run aspect instance (edit mode only). */
-type EditorRun = {
+export type EditorRun = {
   /** Absolute path of the host def node (re-keyed on rename/reparent). */
   hostPath: string
   node: Node
@@ -677,7 +683,7 @@ type EditorRun = {
   inst: { rebuild?(): void | Promise<void> }
   /** Async rebuild() supersession counter (see safeRebuild). */
   generation: number
-  /** Mutable props snapshot — `_editorSetProp` updates it and re-derives `deps`. Holds the
+  /** Mutable props snapshot — `sceneEditor.setProp` updates it and re-derives `deps`. Holds the
    *  DOC-LITERAL `$ref` strings (never resolved paths): the inspector's doc-sync compares these
    *  against the file's props, so rewriting them would re-fire on every render. */
   props: Record<string, unknown>
@@ -690,8 +696,13 @@ type EditorRun = {
 
 /** Bumped on every editor-run rebuild — the host compares it to know when to re-push gizmos. */
 let gizmoVersion = 0
+/** @internal */
+export const bumpGizmoVersion = (): number => ++gizmoVersion
+/** @internal */
+export const currentGizmoVersion = (): number => gizmoVersion
 
-const safeRebuild = (run: EditorRun): Promise<void> | void => {
+/** @internal */
+export const safeRebuild = (run: EditorRun): Promise<void> | void => {
   // a throwing generator must not take the editor session down with it; the gizmo scope is the
   // SYNCHRONOUS part of the call — whatever rebuild draws replaces the run's previous lines. An
   // async rebuild() (one that instantiates a scene file) is awaited; lines it wants to draw after
@@ -714,7 +725,7 @@ const safeRebuild = (run: EditorRun): Promise<void> | void => {
 
 /** Re-assign every ref-carrying prop from the CURRENT nodes map — a live patch replaces node
  *  instances, so a generator's resolved fields would otherwise point at destroyed nodes. */
-const assignRefProps = (run: EditorRun, nodes: Record<string, Node>): void => {
+export const assignRefProps = (run: EditorRun, nodes: Record<string, Node>): void => {
   const lookup = (r: string): Node | null => {
     const p = resolveRefPath(nodes, run.hostPath, r)
     return p === null ? null : nodes[p]
@@ -735,7 +746,7 @@ const assignRefProps = (run: EditorRun, nodes: Record<string, Node>): void => {
 // machinery generator aspects use — live, no compile (the code is already in the bundle).
 
 /** EditorRun.index for a node's make() run (aspect runs use their array index, always >= 0). */
-const MAKE_INDEX = -1
+export const MAKE_INDEX = -1
 
 const createMakeInst = (path: string, entry: MakeEntry<any>, generated: GeneratedGroup): { rebuild(): void } => {
   let token = 0
@@ -743,7 +754,7 @@ const createMakeInst = (path: string, entry: MakeEntry<any>, generated: Generate
   inst.rebuild = () => {
     const t = ++token
     generated.clear()
-    // current args = the instance's own fields (that's where _editorSetProp/assignRefProps write)
+    // current args = the instance's own fields (that's where sceneEditor.setProp / assignRefProps write)
     const args: Record<string, unknown> = {}
     for (const [ k, v ] of Object.entries(inst)) if (k !== "rebuild") args[k] = v
     const result = entry.fn(args as never)
@@ -766,7 +777,7 @@ const attachMake = (
   const entry = def.make
   if (!entry) return undefined
   const generated = makeGenerated(node, scene)
-  if (isEditMode()) {
+  if (EDITOR && isEditMode()) {
     const props = { ...(entry.args ?? {}) } as Record<string, unknown>
     const inst = createMakeInst(path, entry, generated)
     Object.assign(inst, resolveRefs(props, nodes, path))
@@ -781,11 +792,12 @@ const attachMake = (
   })
 }
 
-const attachAspects = (
+/** @internal */
+export const attachAspects = (
   node: Node, path: string, def: SceneNodeDef,
   nodes: Record<string, Node>, scene: Scene, editorRuns: EditorRun[],
 ): Promise<void> | void => {
-  if (isEditMode()) {
+  if (EDITOR && isEditMode()) {
     const waits: Promise<void>[] = []
     // Data-only: the inspector reads [ctor, props] from here; nothing attaches, so no onAttach side
     // effects (physics bodies, loops) run while editing. `ref()` markers stay unresolved data too.
@@ -840,23 +852,26 @@ const prefabPartRows = (defs: Record<string, SceneNodeDef>, local: Record<string
     const node = local[path]
     if (!node) continue
     out.push({ path, name, depth, node })
-    out.push(...prefabPartRows(nd.children ?? {}, local, path, depth + 1))
+    // no argument spreads here: a 78 000-node level (an imported Unity scene, every rock and grass tuft
+    // a placement) blew QuickJS's 65 534-argument cap on the top-level prefab's rows
+    for (const r of prefabPartRows(nd.children ?? {}, local, path, depth + 1)) out.push(r)
     const inner = node instanceof Model
       ? modelPartRows(node)
       : (node as { _prefabParts?: ModelPartRow[] })._prefabParts
-    if (inner) out.push(...inner.map((r) => ({ ...r, path: `${path}/${r.path}`, depth: depth + 1 + r.depth })))
+    if (inner) for (const r of inner) out.push({ ...r, path: `${path}/${r.path}`, depth: depth + 1 + r.depth })
   }
   return out
 }
 
-const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>, lm: LightmapCtx | null): Promise<void> => {
+/** @internal */
+export const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>, lm: LightmapCtx | null): Promise<void> => {
   const pdef = (def.prefab as { def?: SceneDef } | undefined)?.def
   if (!pdef || typeof pdef !== "object") {
     console.error(`[scene] "${path}".prefab is not a scene handle (import the .scene file's default export)`)
     return
   }
-  // editor marker: the harness enumerates prefab internals as parts, like a GLB's (`_modelParts`)
-  ;(wrapper as { _scenePrefab?: boolean })._scenePrefab = true
+  // editor marker: the harness enumerates prefab internals as parts, like a GLB's (`sceneEditor.modelParts`)
+  if (EDITOR) (wrapper as { _scenePrefab?: boolean })._scenePrefab = true
   if (stack.has(pdef)) {
     console.error(`[scene] prefab cycle detected at "${path}" — instance skipped`)
     return
@@ -903,7 +918,7 @@ const buildNodes = async (
     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)
+    if (EDITOR && 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}/` } : null)
     pending.push({ path, node, def: nd })
@@ -971,10 +986,10 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   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: "" } : null
+  const lm: LightmapCtx | null = lightmap && !(EDITOR && isEditMode()) ? { prefix: "" } : null
   if (lm) Lightmap.clear()
   await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]), lm)
-  if (navmesh && !isEditMode()) registerNavOverrides(def.nodes, nodes)
+  if (navmesh && !(EDITOR && 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
@@ -990,13 +1005,13 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
     scene.camera.position = placeNode.worldPosition
     scene.camera.quaternion = placeNode.worldQuaternion
     applyCameraProjection(scene, proj)
-    if (!isEditMode()) scene.camera.follow(placeNode)
+    if (!(EDITOR && isEditMode())) scene.camera.follow(placeNode)
   } else if (cam && camNode) {
     // legacy: the `camera: {}` node source block (still honoured — prefer a CameraPlace aspect)
     scene.camera.position = camNode.worldPosition
     scene.camera.quaternion = camNode.worldQuaternion
     applyCameraProjection(scene, cam.def)
-    if (!isEditMode()) scene.camera.follow(camNode)
+    if (!(EDITOR && isEditMode())) scene.camera.follow(camNode)
   } else if (def.camera) {
     if (def.camera.position) scene.camera.position = def.camera.position
     if (def.camera.target) scene.camera.lookAt(def.camera.target)
@@ -1010,7 +1025,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   }
   // 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()) {
+  if (navmesh && !(EDITOR && isEditMode())) {
     await NavMesh.load(scene, { data: navmesh.data, agent: navmesh.agent, areas: navmesh.areas })
   }
 
@@ -1020,14 +1035,13 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
 export class SceneHandle<D extends SceneDef = SceneDef> {
   readonly def: D
   private _loading?: Promise<LoadedScene<D>>
-  /** @internal Live editor-run aspect instances (edit mode only — see attachAspects). */
-  private _editorRuns: EditorRun[] = []
-  /** @internal Custom-inspector cards (`static inspector`), per `<host>:<index>` — see _inspectorRender. */
-  private _inspectorCards = new Map<string, { ui: InspectorUI, inst: Record<string, unknown>, node: Node }>()
-  /** @internal The loaded scene + path-keyed node record, for the editor methods below (set once
+  /** @internal Live editor-run aspect instances (edit mode only — see attachAspects). The editor
+   *  (./editor.ts) reads and replaces the list. */
+  _editorRuns: EditorRun[] = []
+  /** @internal The loaded scene + path-keyed node record, for the editor (./editor.ts; set once
    *  load resolves). The record object is SHARED with the returned LoadedScene — patches and
    *  rename/reparent re-keying are visible through both. */
-  private _live: { scene: Scene, nodes: Record<string, Node> } | null = null
+  _live: { scene: Scene, nodes: Record<string, Node> } | null = null
 
   constructor(def: D) { this.def = def }
 
@@ -1070,10 +1084,10 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     // their generators' gizmos still draw (foreignRuns — a nested rig's sight line)
     const runs: EditorRun[] = []
     await buildNodes(this.def.nodes ?? {}, root, scene, nodes, runs, new Set([ this.def ]))
-    if (isEditMode() && runs.length > 0) { foreignRuns.set(root, runs); gizmoVersion++ }
+    if (EDITOR && isEditMode() && runs.length > 0) { foreignRuns.set(root, runs); gizmoVersion++ }
     const get = (path: string): Node | null => nodes[path] ?? null
     const dispose = (): void => {
-      foreignRuns.delete(root)
+      if (EDITOR) foreignRuns.delete(root)
       root.visible = false   // the visibility cascade retires the subtree's pick colliders first
       scene.remove(root)
       root.destroy()
@@ -1086,324 +1100,6 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     }
     return { root, nodes, get, dispose, alignTo } as unknown as SceneInstance<D>
   }
-
-  /**
-   * @internal Editor (edit mode): apply ONE node's change to the already-loaded scene without
-   * recompiling — the same "scenes as data" grammar, but as a patch: `def` rebuilds the node at
-   * `path` in place (or adds it when the path is new — the path's parent must exist, root paths
-   * mount at the root), `def === null` removes it with its whole subtree. The def must be PLAIN
-   * data — the editor falls back to a full re-run for `$expr` and `$asset` values; aspect changes
-   * are inert in edit mode and stay out of defs.
-   *
-   * Named children survive a rebuild: they are re-parented onto the replacement node keeping their
-   * local transforms (exactly what the scene file describes). Returns the fresh node, null for a
-   * removal (or an add under an unknown parent). Old GPU resources (geometry/material instances)
-   * are not reclaimed until the next full re-run — acceptable churn for an edit session.
-   */
-  async _patchNode(path: string, def: SceneNodeDef | null): Promise<Node | null> {
-    const { scene, nodes } = (await this.load()) as unknown as { scene: Scene, nodes: Record<string, Node> }
-    const old: Node | undefined = nodes[path]
-
-    const dispose = (root: Node): void => {
-      // Hide first: the visibility cascade deactivates the subtree's pick colliders (the ABI has
-      // no removeCollider — a destroyed entity's stale collider entry must never pick again).
-      root.visible = false
-      const doomed = new Set<Node>()
-      root.traverse((n) => doomed.add(n))
-      for (const [ key, n ] of Object.entries(nodes)) if (doomed.has(n)) delete nodes[key]
-      // editor-run aspect instances hosted in the doomed subtree go with it (generated children
-      // are subtree children, so the destroy below reclaims them too)
-      this._editorRuns = this._editorRuns.filter((r) => !doomed.has(r.node))
-      gizmoVersion++
-      scene.remove(root)
-      root.destroy()   // native destroyEntity recurses over remaining children
-    }
-
-    if (def === null) {
-      if (old) {
-        dispose(old)
-        this._refreshRunDeps()
-      }
-      return null
-    }
-
-    const build = async (p: string, d: SceneNodeDef, parent: Node | null): Promise<Node> => {
-      // child reuse is by FULL path — only the live subtree at this exact address is carried
-      // over (a bare-name lookup would adopt a like-named node from anywhere in the scene)
-      const existing = p === path ? undefined : nodes[p]
-      if (existing) {   // an already-live child subtree — keep it, just re-parent (local transform stays)
-        if (parent) attachHost(parent, d, p).add(existing)
-        return existing
-      }
-      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)))
-      return node
-    }
-
-    const cut = path.lastIndexOf("/")
-    const parentPath = cut < 0 ? null : path.slice(0, cut)
-    if (!old && parentPath !== null && !nodes[parentPath]) return null
-    const parent = old ? old.parent : (parentPath !== null ? nodes[parentPath] : null)
-    const fresh = await build(path, def, parent)
-    if (old) {
-      // named children not listed in the def still move over (the editor patches one node at a time)
-      const named = new Set(Object.values(nodes))
-      for (const child of old.children) if (named.has(child)) fresh.add(child)
-      dispose(old)               // fresh already replaced nodes[path] in build(), so it survives
-      nodes[path] = fresh
-    }
-    // the projection lives on the scene camera, not on the node — re-apply it here so an inspector
-    // fov/near/far edit lands live (a rebuilt node alone would carry none of it)
-    if (def.camera !== undefined) applyCameraProjection(scene, def.camera, true)
-    this._refreshRunDeps()
-    return fresh
-  }
-
-  /** @internal Editor: every run's gizmo lines (world-space LINES batches) + a version that
-   *  changes whenever any rebuild ran — the host re-pushes to the engine only on a change. */
-  _editorGizmos(): { version: number, batches: GizmoBatch[] } {
-    const batches: GizmoBatch[] = []
-    for (const run of this._editorRuns) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
-    for (const runs of foreignRuns.values()) for (const run of runs) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
-    for (const node of Object.values(this._live?.nodes ?? {})) {
-      const marker = (node as { _editorMarker?: GizmoBuffer })._editorMarker
-      if (marker) for (const b of marker.batches) batches.push(b)
-    }
-    return { version: gizmoVersion, batches }
-  }
-
-  /** @internal Re-derive every editor run's deps from the CURRENT record. Deps are RESOLVED
-   *  absolute paths, so any structural change can invalidate them: an add can satisfy a
-   *  previously-null ref, a remove/rename can re-bind one to a different scope (shadowing). */
-  private _refreshRunDeps(): void {
-    const nodes = this._live?.nodes
-    if (!nodes) return
-    for (const run of this._editorRuns) {
-      run.deps = collectRefDeps(run.props, nodes, run.hostPath)
-      // aspect runs keep their host as a dep (see attachAspects); make() runs must NOT — the
-      // wrapper's transform is editor-owned and moving it never re-calls the factory
-      if (run.index !== MAKE_INDEX) run.deps.add(run.hostPath)
-    }
-  }
-
-  /** @internal Re-key everything addressed under `oldPath` (the node itself, descendants, editor
-   *  runs, inspector cards) to `newPath`, then re-derive deps. The record object is shared with
-   *  the host — mutation, not replacement. */
-  private _rekey(oldPath: string, newPath: string): void {
-    const nodes = this._live!.nodes
-    const move = (key: string): string | null =>
-      key === oldPath ? newPath
-      : key.startsWith(oldPath + "/") ? newPath + key.slice(oldPath.length)
-      : null
-    for (const key of Object.keys(nodes)) {
-      const next = move(key)
-      if (next === null) continue
-      const n = nodes[key]
-      delete nodes[key]
-      nodes[next] = n
-    }
-    for (const run of this._editorRuns) {
-      const next = move(run.hostPath)
-      if (next !== null) run.hostPath = next
-    }
-    for (const [ key, card ] of [ ...this._inspectorCards ]) {
-      const i = key.lastIndexOf(":")
-      const next = move(key.slice(0, i))
-      if (next === null) continue
-      this._inspectorCards.delete(key)
-      this._inspectorCards.set(next + key.slice(i), card)
-    }
-    this._refreshRunDeps()
-  }
-
-  /** @internal Editor: rename ONE node (bare sibling segment — the subtree's paths follow).
-   *  Owns the shared record's re-keying (the host re-keys only its own part/selection state).
-   *  Returns the new path; null on refusal (unknown node, invalid name, sibling collision). */
-  _renameNode(path: string, newName: string): string | null {
-    const nodes = this._live?.nodes
-    const node = nodes?.[path]
-    if (!nodes || !node || newName === "" || newName.includes("/") || newName.includes(":")) return null
-    const cut = path.lastIndexOf("/")
-    const newPath = cut < 0 ? newName : path.slice(0, cut + 1) + newName
-    if (newPath === path) return path
-    if (nodes[newPath]) return null
-    this._rekey(path, newPath)
-    node.name = newName   // engine-side name stays the bare segment
-    return newPath
-  }
-
-  /** @internal Editor: reparent keeping the LOCAL transform (null = scene root) — the node's and
-   *  every descendant's paths follow. Returns the new path; null on refusal (unknown node/parent,
-   *  cycle, name taken among the new siblings). */
-  _reparentNode(path: string, newParentPath: string | null): string | null {
-    const nodes = this._live?.nodes
-    const node = nodes?.[path]
-    if (!nodes || !node) return null
-    const parent = newParentPath === null ? null : nodes[newParentPath]
-    if (newParentPath !== null && !parent) return null
-    if (newParentPath !== null && (newParentPath === path || newParentPath.startsWith(path + "/"))) return null
-    const name = path.slice(path.lastIndexOf("/") + 1)
-    const newPath = newParentPath === null ? name : `${newParentPath}/${name}`
-    if (newPath === path) return path
-    if (nodes[newPath]) return null
-    this._rekey(path, newPath)
-    node.setParent(parent ?? null, false)
-    return newPath
-  }
-
-  /** @internal Editor: a node changed (transform edit / gizmo drag / live patch) — re-resolve refs
-   *  and re-run rebuild() on every editor-run aspect whose ref() props point at it. Deps are
-   *  absolute paths, so "the change counts for its ancestors too" (generators read subtrees —
-   *  FollowPath's waypoints are the children of its referenced path node) is a prefix test:
-   *  a dep hits when the changed path IS the dep or lies inside the dep's subtree. */
-  _editorNodeChanged(path: string): void {
-    const nodes = this._live?.nodes
-    if (!nodes) return
-    for (const run of this._editorRuns) {
-      let hit = false
-      for (const d of run.deps) if (path === d || path.startsWith(`${d}/`)) { hit = true; break }
-      if (!hit) continue
-      assignRefProps(run, nodes)   // a patch may have replaced the referenced node instance
-      safeRebuild(run)
-    }
-  }
-
-  /** @internal Editor: live arg edit on a make() node — re-calls the factory through the tracked
-   *  run (no compile; the factory is already in the bundle). False for non-make nodes. */
-  _editorSetMakeArg(hostPath: string, key: string, value: unknown): boolean {
-    return this._editorSetProp(hostPath, MAKE_INDEX, key, value)
-  }
-
-  /** @internal Editor: live prop edit on ONE editor-run aspect (`index` = the doc's aspect index
-   *  on the host node) — updates the instance (`{ $ref }` values resolve to live nodes), re-derives
-   *  its deps, and rebuilds. False when that entry isn't editor-run (inert data — nothing to do). */
-  _editorSetProp(hostPath: string, index: number, key: string, value: unknown): boolean {
-    const run = this._editorRuns.find((r) => r.hostPath === hostPath && r.index === index)
-    const nodes = this._live?.nodes
-    if (!run || !nodes) return false
-    run.props[key] = value
-    run.deps = collectRefDeps(run.props, nodes, run.hostPath)
-    // aspect runs keep their host as a dep (see attachAspects); make() runs must NOT — the
-    // wrapper's transform is editor-owned and moving it never re-calls the factory
-    if (run.index !== MAKE_INDEX) run.deps.add(run.hostPath)
-    if (isNodeRef(value) || (Array.isArray(value) && value.some(isNodeRef))) assignRefProps(run, nodes)
-    else (run.inst as Record<string, unknown>)[key] = value
-    safeRebuild(run)
-    return true
-  }
-
-  /**
-   * @internal Editor: run an aspect's custom `static inspector` card (immediate-mode — see
-   * core/InspectorUI.ts) and return its widget list. Null when the class has no inspector (the
-   * editor falls back to the inferred fields).
-   *
-   * `props` is the entry's CURRENT doc props, passed on EVERY call — the world syncs its side
-   * from it (a generator syncs through the `_editorSetProp` machinery, so an undo that changes a
-   * prop rebuilds for free; a plain aspect's preview instance is reassigned). `event` carries only
-   * buttons and editor-state field edits — doc-bound field edits arrive as changed `props`.
-   *
-   * Cards persist per `<host>:<index>` across calls (that's where `ui.state` lives); a card whose
-   * node instance was replaced by a live patch is rebuilt transparently.
-   */
-  _inspectorRender(
-    hostPath: string, index: number,
-    props: Record<string, unknown>, event?: InspectorEvent,
-  ): InspectorWidget[] | null {
-    const live = this._live
-    const node = live?.nodes[hostPath]
-    const entry = (node as unknown as { _sceneAspects?: readonly AspectEntry<any>[] } | undefined)
-      ?._sceneAspects?.[index]
-    if (!live || !node || !entry) return null
-    const ctor = entry.ctor as unknown as { inspector?: (ui: InspectorUI, aspect: unknown) => void }
-    if (typeof ctor.inspector !== "function") return null
-
-    const run = this._editorRuns.find((r) => r.hostPath === hostPath && r.index === index)
-    const key = `${hostPath}:${index}`
-    let card = this._inspectorCards.get(key)
-    if (!card || card.node !== node) {
-      // (Re)create — generators reuse their tracked live instance; plain aspects get a persistent
-      // preview instance: node set, refs resolved, NEVER onAttach (edit mode stays side-effect
-      // free). Editor state (ui._state) survives a node patch by carrying the old ui over.
-      let inst: Record<string, unknown>
-      if (run) {
-        inst = run.inst as unknown as Record<string, unknown>
-      } else {
-        inst = new (entry.ctor as unknown as new () => Record<string, unknown>)()
-        inst.node = node
-        Object.assign(inst, resolveRefs({ ...props }, live.nodes, hostPath))
-      }
-      const ui = card?.ui ?? new InspectorUI()
-      ui._fields = describeFields(entry.ctor as unknown as abstract new () => unknown)
-      ui._docKeys = new Set(ui._fields.map((f) => f.key))
-      card = { ui, inst, node }
-      this._inspectorCards.set(key, card)
-    }
-
-    // Sync the doc props into the world side. A key REMOVED from the doc (undo past its first
-    // edit) resets to the class-field default — otherwise the instance would keep the stale value.
-    const c = card
-    const fieldDefault = (k: string): unknown => c.ui._fields.find((f) => f.key === k)?.value
-    // `$expr` markers (values set in code) never sync into instances — the widget shows them
-    // read-only; the instance keeps the compile-time evaluation.
-    const isExpr = (v: unknown): boolean =>
-      typeof v === "object" && v !== null && typeof (v as { $expr?: unknown }).$expr === "string"
-    const changed = (a: unknown, b: unknown): boolean =>
-      a !== b && JSON.stringify(a) !== JSON.stringify(b)
-    if (run) {
-      for (const [ k, v ] of Object.entries(props)) {
-        if (!isExpr(v) && changed(run.props[k], v)) this._editorSetProp(hostPath, index, k, v)
-      }
-      for (const k of Object.keys(run.props)) {
-        if (k in props) continue
-        this._editorSetProp(hostPath, index, k, fieldDefault(k))
-        delete run.props[k]   // keep run.props mirroring the doc, or this reset re-fires every call
-      }
-      c.ui._props = run.props
-    } else {
-      const snapshot = { ...props }
-      const resolved = (resolveRefs(snapshot, live.nodes, hostPath) ?? snapshot) as Record<string, unknown>
-      for (const f of c.ui._fields) {
-        if (isExpr(resolved[f.key])) continue
-        c.inst[f.key] = f.key in resolved ? resolved[f.key] : f.value
-      }
-      c.ui._props = snapshot
-    }
-
-    return c.ui._run((u) => ctor.inspector!(u, c.inst), event)
-  }
-
-  /** @internal Editor: the INTERNAL part rows of a loaded model node or prefab instance (by its
-   *  absolute def path) — path/name/depth/live node, in the same asset-internal part-path grammar
-   *  `overrides` keys use. Empty for plain nodes / unknown paths. */
-  async _modelParts(path: string): Promise<ModelPartRow[]> {
-    const { nodes } = (await this.load()) as unknown as { nodes: Record<string, Node> }
-    const node = nodes[path]
-    if (node instanceof Model) return modelPartRows(node)
-    // prefab instances precompute their rows in DEF order (engine child order isn't stable)
-    return (node as { _prefabParts?: ModelPartRow[] } | undefined)?._prefabParts ?? []
-  }
-
-  /** @internal Editor: describe every aspect class this scene references (fields + defaults). */
-  _describeAspects(): AspectClassInfo[] {
-    const ctors = new Set<AspectCtor<any>>()
-    const walk = (defs?: Record<string, SceneNodeDef>): void => {
-      for (const nd of Object.values(defs ?? {})) {
-        for (const e of nd.aspects ?? []) ctors.add(e.ctor)
-        walk(nd.children)
-      }
-    }
-    walk(this.def.nodes)
-    return [ ...ctors ].map((c) => describeAspect(c))
-  }
 }
 
 /**
@@ -1417,6 +1113,6 @@ export const defineScene = <const D extends SceneDef>(def: D): SceneHandle<D> =>
   const g = globalThis as unknown as { [EDIT_FLAG]?: boolean, __lecodesScenes?: SceneHandle[] }
   // Editor hook: expose defined handles to the host (the scene editor runs the bundle, then picks
   // up the handle to load it in edit mode and drive the inspector).
-  if (g[EDIT_FLAG]) (g.__lecodesScenes ??= []).push(handle as SceneHandle)
+  if (EDITOR && g[EDIT_FLAG]) (g.__lecodesScenes ??= []).push(handle as SceneHandle)
   return handle
 }