lecodes-cli 0.13.0 → 0.13.2

package/runtime/sdk/scene/defineScene.ts

@@ -1,8 +1,8 @@
 // Scenes as data: the runtime behind `.scene.ts` files (docs/scene-editor-plan.md in the repo root).
 //
 // A scene file default-exports one `defineScene({...})` call whose argument is a plain literal —
-// nodes keyed by name, each with one source block (mesh / model / light / make / prefab, or none
-// = group),
+// nodes keyed by name (unique among SIBLINGS; the runtime addresses them by '/'-joined absolute
+// PATH), each with one source block (mesh / model / light / make / prefab, or none = group),
 // a transform, an optional material, `aspects: [use(Ctor, props), …]` and `children`. The visual
 // editor parses and rewrites that literal; at runtime it lowers to ordinary SDK calls (Mesh.box,
 // node.aspect, scene.add), so scenes run identically on every platform with no loader ABI.
@@ -35,7 +35,7 @@
 import { Aspect, type AspectCtor, type With } from "../core/Aspect"
 import { describeAspect, describeFields, type AspectClassInfo } from "../core/fields"
 import {
-  collectRefDeps, isEditMode, isNodeRef, resolveRefs, use, ref, make, EDIT_FLAG,
+  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"
@@ -165,16 +165,19 @@ type NodeOf<N extends SceneNodeDef> =
 type UnionToIntersection<U> =
   (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
 
-// The child maps of a def level, as a union (never when no node has children — guarded below,
-// since `unknown` would absorb the union and `never` would poison the intersection).
-type ChildMapsOf<T extends Record<string, SceneNodeDef>> =
-  { [K in keyof T]: T[K] extends { children: infer C extends Record<string, SceneNodeDef> } ? NodesOf<C> : never }[keyof T]
+// The child maps of a def level, prefixed with their parent's path, as a union (never when no
+// node has children — guarded below, since `unknown` would absorb the union and `never` would
+// poison the intersection).
+type ChildMapsOf<T extends Record<string, SceneNodeDef>, P extends string> =
+  { [K in keyof T & string]:
+      T[K] extends { children: infer C extends Record<string, SceneNodeDef> } ? NodesOf<C, `${P}${K}/`> : never
+  }[keyof T & string]
 
-// All nodes of a def tree, flattened into one name → node map (names are unique per scene file —
-// the editor enforces it; at runtime a duplicate key simply overwrites in the map).
-type NodesOf<T extends Record<string, SceneNodeDef>> =
-  { [K in keyof T]: NodeOf<T[K]> } &
-  ([ChildMapsOf<T>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T>>)
+// All nodes of a def tree, keyed by ABSOLUTE PATH — '/'-joined def keys, a root node's path is
+// its bare name. Names are unique among SIBLINGS only; paths are unique by construction.
+type NodesOf<T extends Record<string, SceneNodeDef>, P extends string = ""> =
+  { [K in keyof T & string as `${P}${K}`]: NodeOf<T[K]> } &
+  ([ChildMapsOf<T, P>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T, P>>)
 
 export type SceneNodes<D extends SceneDef> =
   D["nodes"] extends Record<string, SceneNodeDef> ? NodesOf<D["nodes"]> : Record<string, Node>
@@ -182,6 +185,11 @@ export type SceneNodes<D extends SceneDef> =
 export type LoadedScene<D extends SceneDef> = {
   scene: Scene
   nodes: SceneNodes<D>
+  /** Path lookup — typed for this scene's literal paths, `Node | null` for arbitrary strings. */
+  get: {
+    <P extends keyof SceneNodes<D> & string>(path: P): SceneNodes<D>[P]
+    (path: string): Node | null
+  }
 }
 
 // ---- GLB internal parts --------------------------------------------------------
@@ -253,9 +261,9 @@ const createMesh = (def: MeshDef, material?: MaterialDef): Mesh => {
   }
 }
 
-const createSource = (name: string, def: SceneNodeDef): Node | Promise<Node> => {
+const createSource = (path: string, def: SceneNodeDef): 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 "${name}" declares more than one source (mesh/model/light/make/prefab/camera)`)
+  if (sources > 1) throw new Error(`Scene node "${path}" declares more than one source (mesh/model/light/make/prefab/camera)`)
   if (def.model !== undefined) return Model.load(def.model)
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
   if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
@@ -329,11 +337,12 @@ class CameraRig extends Aspect<"__cameraRig"> {
   }
 }
 
-/** The first camera-source def in file order (depth-first) — its name and block — or null. */
-const findCamera = (defs?: Record<string, SceneNodeDef>): { name: string, def: CameraNodeDef } | null => {
+/** The first camera-source def in file order (depth-first) — its path and block — or null. */
+const findCamera = (defs?: Record<string, SceneNodeDef>, prefix = ""): { path: string, def: CameraNodeDef } | null => {
   for (const [ name, nd ] of Object.entries(defs ?? {})) {
-    if (nd.camera !== undefined) return { name, def: nd.camera }
-    const inner = findCamera(nd.children)
+    const path = prefix === "" ? name : `${prefix}/${name}`
+    if (nd.camera !== undefined) return { path, def: nd.camera }
+    const inner = findCamera(nd.children, path)
     if (inner) return inner
   }
   return null
@@ -390,29 +399,37 @@ const makeGenerated = (node: Node, scene: Scene): GeneratedGroup => {
 
 /** One live editor-run aspect instance (edit mode only). */
 type EditorRun = {
-  hostName: string
+  /** Absolute path of the host def node (re-keyed on rename/reparent). */
+  hostPath: string
   node: Node
   /** Index within the def's `aspects` array — the doc's aspect index addresses it. */
   index: number
   inst: { rebuild?(): void }
-  /** Mutable props snapshot — `_editorSetProp` updates it and re-derives `deps`. */
+  /** Mutable props snapshot — `_editorSetProp` 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>
-  /** Names of nodes the ref() props point at — a change to any of them re-runs rebuild(). */
+  /** ABSOLUTE paths the ref() props resolved to — a change to any of them (or anything inside
+   *  their subtrees) re-runs rebuild(). Re-derived after every structural change. */
   deps: Set<string>
 }
 
 const safeRebuild = (run: EditorRun): void => {
   // a throwing generator must not take the editor session down with it
-  try { run.inst.rebuild?.() } catch (e) { console.error(`[scene] editor aspect rebuild failed on "${run.hostName}":`, e) }
+  try { run.inst.rebuild?.() } catch (e) { console.error(`[scene] editor aspect rebuild failed on "${run.hostPath}":`, e) }
 }
 
 /** 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 => {
+  const lookup = (r: string): Node | null => {
+    const p = resolveRefPath(nodes, run.hostPath, r)
+    return p === null ? null : nodes[p]
+  }
   for (const [ k, v ] of Object.entries(run.props)) {
-    if (isNodeRef(v)) (run.inst as Record<string, unknown>)[k] = nodes[v.$ref] ?? null
+    if (isNodeRef(v)) (run.inst as Record<string, unknown>)[k] = lookup(v.$ref)
     else if (Array.isArray(v) && v.some(isNodeRef)) {
-      ;(run.inst as Record<string, unknown>)[k] = v.map((el) => (isNodeRef(el) ? nodes[el.$ref] ?? null : el))
+      ;(run.inst as Record<string, unknown>)[k] = v.map((el) => (isNodeRef(el) ? lookup(el.$ref) : el))
     }
   }
 }
@@ -427,7 +444,7 @@ const assignRefProps = (run: EditorRun, nodes: Record<string, Node>): void => {
 /** EditorRun.index for a node's make() run (aspect runs use their array index, always >= 0). */
 const MAKE_INDEX = -1
 
-const createMakeInst = (name: string, entry: MakeEntry<any>, generated: GeneratedGroup): { rebuild(): void } => {
+const createMakeInst = (path: string, entry: MakeEntry<any>, generated: GeneratedGroup): { rebuild(): void } => {
   let token = 0
   const inst: Record<string, unknown> = {}
   inst.rebuild = () => {
@@ -441,7 +458,7 @@ const createMakeInst = (name: string, entry: MakeEntry<any>, generated: Generate
     void Promise.resolve(result).then((made) => {
       // a newer rebuild superseded this call while the factory awaited — drop the stale subtree
       if (t === token && made instanceof Node) generated.add(made)
-    }).catch((e) => console.error(`[scene] make() factory failed on "${name}":`, e))
+    }).catch((e) => console.error(`[scene] make() factory failed on "${path}":`, e))
   }
   return inst as unknown as { rebuild(): void }
 }
@@ -450,7 +467,7 @@ const createMakeInst = (name: string, entry: MakeEntry<any>, generated: Generate
  *  awaits it, so `open()` resolves with generated content in place. Edit mode tracks an EditorRun
  *  and returns immediately (async content pops in when ready, like a model load). */
 const attachMake = (
-  node: Node, name: string, def: SceneNodeDef,
+  node: Node, path: string, def: SceneNodeDef,
   nodes: Record<string, Node>, scene: Scene, editorRuns: EditorRun[],
 ): Promise<void> | undefined => {
   const entry = def.make
@@ -458,21 +475,21 @@ const attachMake = (
   const generated = makeGenerated(node, scene)
   if (isEditMode()) {
     const props = { ...(entry.args ?? {}) } as Record<string, unknown>
-    const inst = createMakeInst(name, entry, generated)
-    Object.assign(inst, resolveRefs(props, nodes))
-    const run: EditorRun = { hostName: name, node, index: MAKE_INDEX, inst, props, deps: collectRefDeps(props) }
+    const inst = createMakeInst(path, entry, generated)
+    Object.assign(inst, resolveRefs(props, nodes, path))
+    const run: EditorRun = { hostPath: path, node, index: MAKE_INDEX, inst, props, deps: collectRefDeps(props, nodes, path) }
     editorRuns.push(run)
     safeRebuild(run)
     return undefined
   }
-  const args = resolveRefs({ ...(entry.args ?? {}) } as Record<string, unknown>, nodes) ?? {}
+  const args = resolveRefs({ ...(entry.args ?? {}) } as Record<string, unknown>, nodes, path) ?? {}
   return Promise.resolve(entry.fn(args as never)).then((made) => {
     if (made instanceof Node) generated.add(made)
   })
 }
 
 const attachAspects = (
-  node: Node, name: string, def: SceneNodeDef,
+  node: Node, path: string, def: SceneNodeDef,
   nodes: Record<string, Node>, scene: Scene, editorRuns: EditorRun[],
 ): void => {
   if (isEditMode()) {
@@ -486,17 +503,17 @@ const attachAspects = (
       const inst = new (entry.ctor as unknown as new () => { rebuild?(): void })()
       ;(inst as { node: unknown }).node = node
       ;(inst as { generated: unknown }).generated = makeGenerated(node, scene)
-      Object.assign(inst, resolveRefs(props, nodes))
+      Object.assign(inst, resolveRefs(props, nodes, path))
       // the HOST node is a dep too: a generator that draws relative to its node (path lines)
       // must re-run when the node itself is dragged, not only when its ref() targets move
-      const run: EditorRun = { hostName: name, node, index, inst, props, deps: collectRefDeps(props).add(name) }
+      const run: EditorRun = { hostPath: path, node, index, inst, props, deps: collectRefDeps(props, nodes, path).add(path) }
       editorRuns.push(run)
       safeRebuild(run)
     })
     return
   }
   for (const entry of def.aspects ?? []) {
-    const props = resolveRefs(entry.props as Record<string, unknown> | undefined, nodes)
+    const props = resolveRefs(entry.props as Record<string, unknown> | undefined, nodes, path)
     const withGenerated = isEditorCtor(entry.ctor) ? { ...props, generated: makeGenerated(node, scene) } : props
     ;(node as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(entry.ctor, withGenerated)
   }
@@ -512,15 +529,15 @@ const attachAspects = (
 // `overrides`, not per-instance aspect edits). `stack` guards import cycles by def identity.
 
 /** An instance's part rows in DEF order (the live `children` walk reflects engine insertion
- *  order, which some hosts reverse) — def names are unique per file, so paths are just the names
- *  joined. Models inside the prefab drill into their GLB parts, nested prefabs into their own
- *  precomputed rows; both keep producing the exact paths `applyModelOverrides` resolves. */
+ *  order, which some hosts reverse) — the instance-local record is path-keyed, so row paths ARE
+ *  the record keys. Models inside the prefab drill into their GLB parts, nested prefabs into
+ *  their own precomputed rows; both keep producing the exact paths `applyModelOverrides` resolves. */
 const prefabPartRows = (defs: Record<string, SceneNodeDef>, local: Record<string, Node>, prefix: string, depth: number): ModelPartRow[] => {
   const out: ModelPartRow[] = []
   for (const [ name, nd ] of Object.entries(defs)) {
-    const node = local[name]
-    if (!node) continue
     const path = prefix === "" ? name : `${prefix}/${name}`
+    const node = local[path]
+    if (!node) continue
     out.push({ path, name, depth, node })
     out.push(...prefabPartRows(nd.children ?? {}, local, path, depth + 1))
     const inner = node instanceof Model
@@ -531,16 +548,16 @@ const prefabPartRows = (defs: Record<string, SceneNodeDef>, local: Record<string
   return out
 }
 
-const attachPrefab = async (wrapper: Node, name: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>): Promise<void> => {
+const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>): Promise<void> => {
   const pdef = (def.prefab as { def?: SceneDef } | undefined)?.def
   if (!pdef || typeof pdef !== "object") {
-    console.error(`[scene] "${name}".prefab is not a scene handle (import the .scene file's default export)`)
+    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
   if (stack.has(pdef)) {
-    console.error(`[scene] prefab cycle detected at "${name}" — instance skipped`)
+    console.error(`[scene] prefab cycle detected at "${path}" — instance skipped`)
     return
   }
   const local: Record<string, Node> = {}
@@ -558,26 +575,33 @@ const buildNodes = async (
   defs: Record<string, SceneNodeDef>, parent: Node | null, scene: Scene,
   nodes: Record<string, Node>, editorRuns: EditorRun[], stack: Set<SceneDef>,
 ): Promise<void> => {
-  const pending: { name: string, node: Node, def: SceneNodeDef }[] = []
+  const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
 
-  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null): Promise<void> => {
-    const node = await createSource(name, nd)
+  const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string): Promise<void> => {
+    // names are path segments — '/' would fork the path, ':' would ambiguate editor card keys
+    if (name === "" || name.includes("/") || name.includes(":")) {
+      throw new Error(`Scene node name "${name}" is invalid — names are non-empty and contain no '/' or ':'`)
+    }
+    // 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 node = await createSource(path, nd)
     if (parentNode) parentNode.add(node)
     // Draw-set membership is separate from parenting (see docs/3d/node.md) — every def node joins.
     scene.add(node)
-    applyNode(node, name, nd)
+    applyNode(node, name, nd)   // engine-side name stays the bare sibling segment
     if (isEditMode()) addEditorMarker(node, nd, scene)
-    if (nd.prefab !== undefined) await attachPrefab(node, name, nd, scene, stack)
-    pending.push({ name, node, def: nd })
-    nodes[name] = node
-    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node)))
+    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack)
+    pending.push({ path, node, def: nd })
+    nodes[path] = node
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path)))
   }
 
-  await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent)))
+  await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
   const makeWaits: Promise<void>[] = []
   for (const p of pending) {
-    attachAspects(p.node, p.name, p.def, nodes, scene, editorRuns)
-    const wait = attachMake(p.node, p.name, p.def, nodes, scene, editorRuns)
+    attachAspects(p.node, p.path, p.def, nodes, scene, editorRuns)
+    const wait = attachMake(p.node, p.path, p.def, nodes, scene, editorRuns)
     if (wait) makeWaits.push(wait)
   }
   if (makeWaits.length > 0) await Promise.all(makeWaits)
@@ -593,7 +617,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   // in both modes — it is a property of the scene, not of the viewpoint, so the editor shows the
   // lens the running app will use.
   const cam = findCamera(def.nodes)
-  const camNode = cam ? nodes[cam.name] : undefined
+  const camNode = cam ? nodes[cam.path] : undefined
   if (cam && camNode) {
     scene.camera.position = camNode.worldPosition
     scene.camera.quaternion = camNode.worldQuaternion
@@ -617,7 +641,9 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
   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/nodes, for the editor methods below (set once load resolves). */
+  /** @internal The loaded scene + path-keyed node record, for the editor methods below (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
 
   constructor(def: D) { this.def = def }
@@ -627,7 +653,8 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     if (!this._loading) {
       this._loading = instantiate(this.def, this._editorRuns).then((live) => {
         this._live = live
-        return live as LoadedScene<D>
+        const get = (path: string): Node | null => live.nodes[path] ?? null
+        return { ...live, get } as unknown as LoadedScene<D>
       })
     }
     return this._loading
@@ -642,19 +669,20 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
 
   /**
    * @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 named node
-   * in place (or adds it when the name is new, under `parentName`/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.
+   * 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. Old GPU resources (geometry/material instances) are not reclaimed until the next full
-   * re-run — acceptable churn for an edit session.
+   * 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(name: string, def: SceneNodeDef | null, parentName?: string | null): Promise<Node | null> {
+  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[name]
+    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
@@ -671,58 +699,141 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     }
 
     if (def === null) {
-      if (old) dispose(old)
+      if (old) {
+        dispose(old)
+        this._refreshRunDeps()
+      }
       return null
     }
 
-    const build = async (n: string, d: SceneNodeDef, parent: Node | null): Promise<Node> => {
-      const existing = n === name ? undefined : nodes[n]
+    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) parent.add(existing)
         return existing
       }
-      const node = await createSource(n, d)
+      const node = await createSource(p, d)
       if (parent) parent.add(node)
       scene.add(node)
-      applyNode(node, n, d)
+      applyNode(node, p.slice(p.lastIndexOf("/") + 1), d)
       if (isEditMode()) addEditorMarker(node, d, scene)
-      attachAspects(node, n, d, nodes, scene, this._editorRuns)
-      nodes[n] = node
-      await Promise.all(Object.entries(d.children ?? {}).map(([ cn, cd ]) => build(cn, cd, node)))
+      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 parent = old ? old.parent : (parentName ? nodes[parentName] ?? null : null)
-    const fresh = await build(name, def, parent)
+    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[name] in build(), so it survives
-      nodes[name] = fresh
+      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: 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. A change also
-   *  counts for the node's ANCESTORS: generators read subtrees (FollowPath's waypoints are the
-   *  children of its referenced path node), so dragging a child must rebuild the parent's deps. */
-  _editorNodeChanged(name: string): void {
+  /** @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
-    const changed = new Set([ name ])
-    let cur = nodes[name]?.parent ?? null
-    for (let i = 0; cur && i < 64; i++) {
-      for (const [ n, node ] of Object.entries(nodes)) if (node === cur) { changed.add(n); break }
-      cur = cur.parent
+    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 n of changed) if (run.deps.has(n)) { hit = true; break }
+      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)
@@ -731,22 +842,22 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
 
   /** @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(hostName: string, key: string, value: unknown): boolean {
-    return this._editorSetProp(hostName, MAKE_INDEX, key, value)
+  _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(hostName: string, index: number, key: string, value: unknown): boolean {
-    const run = this._editorRuns.find((r) => r.hostName === hostName && r.index === index)
+  _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)
+    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.hostName)
+    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)
@@ -767,19 +878,19 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
    * node instance was replaced by a live patch is rebuilt transparently.
    */
   _inspectorRender(
-    hostName: string, index: number,
+    hostPath: string, index: number,
     props: Record<string, unknown>, event?: InspectorEvent,
   ): InspectorWidget[] | null {
     const live = this._live
-    const node = live?.nodes[hostName]
+    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.hostName === hostName && r.index === index)
-    const key = `${hostName}:${index}`
+    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
@@ -791,7 +902,7 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       } else {
         inst = new (entry.ctor as unknown as new () => Record<string, unknown>)()
         inst.node = node
-        Object.assign(inst, resolveRefs({ ...props }, live.nodes))
+        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)
@@ -812,17 +923,17 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       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(hostName, index, k, v)
+        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(hostName, index, k, fieldDefault(k))
+        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) ?? snapshot) as Record<string, unknown>
+      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
@@ -833,12 +944,12 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     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 —
-   *  path/name/depth/live node, in the same part-path grammar `overrides` keys use. Empty for
-   *  plain nodes / unknown names. */
-  async _modelParts(name: string): Promise<ModelPartRow[]> {
+  /** @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[name]
+    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 ?? []
@@ -860,8 +971,9 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
 
 /**
  * Define a scene as data — the default export of a `.scene.ts` file. Returns a typed handle:
- * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
- * (Mesh / Model / Light / Node) with its `use(...)`d aspects attached.
+ * `const { scene, nodes, get } = await handle.open()` gives `nodes[path]` typed by its source
+ * block (Mesh / Model / Light / Node) with its `use(...)`d aspects attached — root nodes read as
+ * plain properties (`nodes.hero`), nested ones by path (`nodes['hero/halo']` / `get('hero/halo')`).
  */
 export const defineScene = <const D extends SceneDef>(def: D): SceneHandle<D> => {
   const handle = new SceneHandle(def)