lecodes-cli 0.13.0 → 0.13.2

package/runtime/sdk/scene/editorPlugins.ts

@@ -17,31 +17,37 @@ import type { InspectorUI } from "../core/InspectorUI"
 export type EditorRayHit = {
   point: [number, number, number]
   normal: [number, number, number]
-  /** The scene-file node the hit belongs to — null for ground-plane fallback hits. */
+  /** Absolute path of the scene-file node the hit belongs to ("city/in1/pt1") — null for
+   *  ground-plane fallback hits. */
   node: string | null
 }
 
 /**
- * The editor scripting API handed to windows and tools. Doc-op methods write the scene DOCUMENT
- * through the editor's normal commit path (undo, file, live patching all included); they return
- * false / no-op when the document can't take the edit (duplicate name, unknown node).
+ * The editor scripting API handed to windows and tools. Nodes are addressed by ABSOLUTE PATH —
+ * '/'-joined names from the scene root; a root node's path is its bare name. Doc-op methods write
+ * the scene DOCUMENT through the editor's normal commit path (undo, file, live patching all
+ * included); they return false / no-op when the document can't take the edit (sibling-name
+ * collision, unknown path).
  */
 export type EditorApi = {
-  /** The currently selected node name (or `model::part` key), null when nothing is selected. */
+  /** The currently selected node path (or `path::part` key for asset internals), null when
+   *  nothing is selected. */
   readonly selection: string | null
-  select(name: string | null): void
-  /** The scene document's nodes (name + source kind: mesh / model / light / group). */
-  nodes(): { name: string, kind: string }[]
-  /** First unused "base", "base2", "base3", … node name. */
-  uniqueName(base: string): string
-  /** Add a node from plain def data (scene-file grammar; a string `model` value means an asset
-   *  path). One undo step unless grouped by `transact`. */
+  select(path: string | null): void
+  /** The scene document's nodes: absolute path, sibling-unique display name, source kind
+   *  (mesh / model / light / group / …). */
+  nodes(): { path: string, name: string, kind: string }[]
+  /** First unused "base", "base2", "base3", … name among the SIBLINGS under `parentPath`
+   *  (scene root when omitted). */
+  uniqueName(base: string, parentPath?: string): string
+  /** Add a ROOT node from plain def data (scene-file grammar; a string `model` value means an
+   *  asset path). `name` may not contain '/' or ':'. One undo step unless grouped by `transact`. */
   addNode(name: string, def: Record<string, unknown>): boolean
   /** Write one def prop (transforms apply live; anything else patches/re-runs the node). */
-  setProp(name: string, key: string, value: unknown): boolean
-  removeNode(name: string): void
-  /** Duplicate a node; returns the copy's name (null when it can't). */
-  duplicate(name: string): string | null
+  setProp(path: string, key: string, value: unknown): boolean
+  removeNode(path: string): void
+  /** Duplicate a node; returns the copy's path (null when it can't). */
+  duplicate(path: string): string | null
   /** Raycast the scene under a viewport pixel (same hit rules as tool clicks). */
   raycast(screenX: number, screenY: number): EditorRayHit | null
   /** Group every doc edit inside `fn` into ONE undo step. */

package/runtime/sdk/scene/grammar.ts

@@ -43,39 +43,74 @@ export const make = <A extends Record<string, unknown>, N>(
 ): MakeEntry<A, N> => ({ __make: true, fn, args })
 
 /**
- * Reference another scene node by name in an aspect's props:
- * `use(Road, { from: ref('pointA'), to: ref('pointB') })`. Resolves to the live node when aspects
- * attach — after EVERY node of the scene exists, so forward references work. An unknown name
- * resolves to `null` (type your aspect field `Node | null`). Scene files only — hand-written code
- * passes nodes directly: `node.aspect(Road, { from: nodes.pointA })`.
+ * Reference another scene node by PATH in an aspect's props:
+ * `use(Road, { from: ref('pointA'), to: ref('lane/pointB') })`. Resolves to the live node when
+ * aspects attach — after EVERY node of the scene exists, so declaration order doesn't matter.
+ * Resolution is scoped upward from the host node (like variable scoping): the host's own children
+ * first, then its siblings, then each ancestor's scope up to the scene root. The FIRST segment
+ * binds the scope; the remaining segments descend from there. Refs address def nodes only (no
+ * `::`/`name[i]` asset-internal segments); an unknown path resolves to `null` (type your aspect
+ * field `Node | null`). Scene files only — hand-written code passes nodes directly:
+ * `node.aspect(Road, { from: nodes.pointA })`.
  */
-export const ref = <T = Node>(name: string): T => ({ $ref: name } as unknown as T)
+export const ref = <T = Node>(path: string): T => ({ $ref: path } as unknown as T)
 
 export const isNodeRef = (v: unknown): v is { $ref: string } =>
   typeof v === "object" && v !== null && typeof (v as { $ref?: unknown }).$ref === "string"
 
-/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep). */
+/** Resolve one ref string against a path-keyed nodes record, scoped upward from `hostPath` (own
+ *  children → parent's scope (siblings + the host itself) → each ancestor scope → root, `""`).
+ *  The ref's FIRST segment binds the scope — a match there is final even when the rest of the
+ *  path doesn't exist (lexical shadowing). Returns the target's ABSOLUTE path, or null.
+ *  `Object.hasOwn`, not indexing: a node named `constructor` must not resolve via the prototype. */
+export const resolveRefPath = (
+  nodes: Record<string, unknown>, hostPath: string, ref: string,
+): string | null => {
+  const i = ref.indexOf("/")
+  const first = i < 0 ? ref : ref.slice(0, i)
+  for (let scope = hostPath; ; ) {
+    const base = scope === "" ? "" : `${scope}/`
+    if (Object.hasOwn(nodes, base + first)) return Object.hasOwn(nodes, base + ref) ? base + ref : null
+    if (scope === "") return null
+    const cut = scope.lastIndexOf("/")
+    scope = cut < 0 ? "" : scope.slice(0, cut)
+  }
+}
+
+/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep),
+ *  resolved scoped-upward from `hostPath` ("" = root scope only — the 2D flat-map case). */
 export const resolveRefs = <N>(
-  props: Record<string, unknown> | undefined, nodes: Record<string, N>,
+  props: Record<string, unknown> | undefined, nodes: Record<string, N>, hostPath = "",
 ): Record<string, unknown> | undefined => {
   if (!props) return props
+  const lookup = (r: string): N | null => {
+    const p = resolveRefPath(nodes, hostPath, r)
+    return p === null ? null : nodes[p]
+  }
   let out: Record<string, unknown> | undefined
   for (const [ k, v ] of Object.entries(props)) {
     if (isNodeRef(v)) {
-      ;(out ??= { ...props })[k] = nodes[v.$ref] ?? null
+      ;(out ??= { ...props })[k] = lookup(v.$ref)
     } else if (Array.isArray(v) && v.some(isNodeRef)) {
-      ;(out ??= { ...props })[k] = v.map((el) => (isNodeRef(el) ? nodes[el.$ref] ?? null : el))
+      ;(out ??= { ...props })[k] = v.map((el) => (isNodeRef(el) ? lookup(el.$ref) : el))
     }
   }
   return out ?? props
 }
 
-/** Names of the nodes a props record's ref() values point at (editor dep tracking). */
-export const collectRefDeps = (props: Record<string, unknown>): Set<string> => {
+/** ABSOLUTE paths of the nodes a props record's ref() values resolve to (editor dep tracking).
+ *  An unresolved ref contributes no dep — the handle re-derives deps after structural changes. */
+export const collectRefDeps = (
+  props: Record<string, unknown>, nodes: Record<string, unknown>, hostPath: string,
+): Set<string> => {
   const deps = new Set<string>()
+  const add = (r: string): void => {
+    const p = resolveRefPath(nodes, hostPath, r)
+    if (p !== null) deps.add(p)
+  }
   for (const v of Object.values(props)) {
-    if (isNodeRef(v)) deps.add(v.$ref)
-    else if (Array.isArray(v)) for (const el of v) if (isNodeRef(el)) deps.add(el.$ref)
+    if (isNodeRef(v)) add(v.$ref)
+    else if (Array.isArray(v)) for (const el of v) if (isNodeRef(el)) add(el.$ref)
   }
   return deps
 }