lecodes-sdk 1.1.0 → 2.0.0

package/src/scene/editor.ts

@@ -0,0 +1,408 @@
+// The scene EDITOR's side of a loaded scene: everything a scene editor does to a `.scene.ts` world
+// while it is edited — live patches, rename / reparent, editor-run aspects (generators) and their
+// gizmo lines, custom inspector cards, the preview pose, live materials, the plugin registry.
+//
+// ONE object, `sceneEditor`, is the whole contract between the SDK and an editor's in-world half
+// (the scene-editor harness): the harness names nothing else of the SDK's internals — no `_`
+// member of a handle, a node or a material. It reaches it as the global `__sceneEditor`, which
+// exists in EDITOR BUNDLES only (src/inject.editor.ts, injected by a compile with `editor: true`);
+// a shipped bundle carries none of this file — nothing in it references the module, and the
+// edit-mode branches of ./defineScene.ts that feed it fold away with `EDITOR`
+// (sdk/tests/scene/editor-contract.test.ts holds both: the members, and their absence when shipped).
+//
+// A change here is a change of that contract: the harness is compiled against whatever SDK the
+// compiling host has, so a member is added, never renamed or re-shaped in place.
+
+import type { AspectCtor } from "../core/Aspect"
+import { describeAspect, describeFields, type AspectClassInfo } from "../core/fields"
+import { InspectorUI, type InspectorEvent, type InspectorWidget } from "../core/InspectorUI"
+import type { Material } from "../gl/Material"
+import { Model } from "../gl/Model"
+import type { Node } from "../gl/Node"
+import type { Scene } from "../gl/Scene"
+import {
+  addEditorMarker, applyCameraProjection, applyEditorPose, applyNode, assignRefProps, attachAspects,
+  attachHost, attachPrefab, bumpGizmoVersion, createSource, currentGizmoVersion, foreignRuns,
+  MAKE_INDEX, modelPartRows, safeRebuild,
+  type ModelPartRow, type SceneHandle, type SceneNodeDef,
+} from "./defineScene"
+import { __editorPlugins } from "./editorPlugins"
+import { GizmoBuffer, withGizmoScope, type GizmoBatch } from "./gizmos"
+import { collectRefDeps, isEditMode, isNodeRef, resolveRefs, type AspectEntry } from "./grammar"
+import { applyMaterialParam, assignMaterialDef } from "./material"
+
+type Handle = SceneHandle<any>
+
+/** Custom-inspector cards (`static inspector`) of a handle, per `<host>:<index>` — see inspectorRender. */
+type InspectorCard = { ui: InspectorUI, inst: Record<string, unknown>, node: Node }
+const inspectorCards = new WeakMap<Handle, Map<string, InspectorCard>>()
+const cardsOf = (handle: Handle): Map<string, InspectorCard> => {
+  let cards = inspectorCards.get(handle)
+  if (!cards) { cards = new Map(); inspectorCards.set(handle, cards) }
+  return cards
+}
+
+/** 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). */
+const refreshRunDeps = (handle: Handle): void => {
+  const nodes = handle._live?.nodes
+  if (!nodes) return
+  for (const run of handle._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)
+  }
+}
+
+/** 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. */
+const rekey = (handle: Handle, oldPath: string, newPath: string): void => {
+  const nodes = handle._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 handle._editorRuns) {
+    const next = move(run.hostPath)
+    if (next !== null) run.hostPath = next
+  }
+  const cards = cardsOf(handle)
+  for (const [ key, card ] of [ ...cards ]) {
+    const i = key.lastIndexOf(":")
+    const next = move(key.slice(0, i))
+    if (next === null) continue
+    cards.delete(key)
+    cards.set(next + key.slice(i), card)
+  }
+  refreshRunDeps(handle)
+}
+
+/**
+ * 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.
+ */
+const patchNode = async (handle: Handle, path: string, def: SceneNodeDef | null): Promise<Node | null> => {
+  const { scene, nodes } = (await handle.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)
+    handle._editorRuns = handle._editorRuns.filter((r) => !doomed.has(r.node))
+    bumpGizmoVersion()
+    scene.remove(root)
+    root.destroy()   // native destroyEntity recurses over remaining children
+  }
+
+  if (def === null) {
+    if (old) {
+      dispose(old)
+      refreshRunDeps(handle)
+    }
+    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([ handle.def ]), null)
+    attachAspects(node, p, d, nodes, scene, handle._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)
+  refreshRunDeps(handle)
+  return fresh
+}
+
+/** 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). */
+const renameNode = (handle: Handle, path: string, newName: string): string | null => {
+  const nodes = handle._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
+  rekey(handle, path, newPath)
+  node.name = newName   // engine-side name stays the bare segment
+  return newPath
+}
+
+/** 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). */
+const reparentNode = (handle: Handle, path: string, newParentPath: string | null): string | null => {
+  const nodes = handle._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
+  rekey(handle, path, newPath)
+  node.setParent(parent ?? null, false)
+  return newPath
+}
+
+/** 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. */
+const nodeChanged = (handle: Handle, path: string): void => {
+  const nodes = handle._live?.nodes
+  if (!nodes) return
+  for (const run of handle._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)
+  }
+}
+
+/** 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). */
+const setProp = (handle: Handle, hostPath: string, index: number, key: string, value: unknown): boolean => {
+  const run = handle._editorRuns.find((r) => r.hostPath === hostPath && r.index === index)
+  const nodes = handle._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
+}
+
+/** 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. */
+const setMakeArg = (handle: Handle, hostPath: string, key: string, value: unknown): boolean =>
+  setProp(handle, hostPath, MAKE_INDEX, key, value)
+
+/** 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. */
+const gizmos = (handle: Handle): { version: number, batches: GizmoBatch[] } => {
+  const batches: GizmoBatch[] = []
+  for (const run of handle._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(handle._live?.nodes ?? {})) {
+    const marker = (node as { _editorMarker?: GizmoBuffer })._editorMarker
+    if (marker) for (const b of marker.batches) batches.push(b)
+  }
+  return { version: currentGizmoVersion(), batches }
+}
+
+/**
+ * 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 `setProp` 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.
+ */
+const inspectorRender = (
+  handle: Handle, hostPath: string, index: number,
+  props: Record<string, unknown>, event?: InspectorEvent,
+): InspectorWidget[] | null => {
+  const live = handle._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 = handle._editorRuns.find((r) => r.hostPath === hostPath && r.index === index)
+  const cards = cardsOf(handle)
+  const key = `${hostPath}:${index}`
+  let card = cards.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 }
+    cards.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)) setProp(handle, hostPath, index, k, v)
+    }
+    for (const k of Object.keys(run.props)) {
+      if (k in props) continue
+      setProp(handle, 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)
+}
+
+/** 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. */
+const modelParts = async (handle: Handle, path: string): Promise<ModelPartRow[]> => {
+  const { nodes } = (await handle.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 ?? []
+}
+
+/** Describe every aspect class this scene references (fields + defaults). */
+const describeAspects = (handle: Handle): 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(handle.def.nodes)
+  return [ ...ctors ].map((c) => describeAspect(c))
+}
+
+/** The `locked` flag of a node (`locked: true` in its def, or set live): viewport manipulation
+ *  won't target it. */
+const isLocked = (node: Node): boolean => (node as { _sceneLocked?: boolean })._sceneLocked === true
+const setLocked = (node: Node, locked: boolean): void => { (node as { _sceneLocked?: boolean })._sceneLocked = locked }
+
+/** True for the SDK's own materials (lit / unlit / shadow), whose `color` / `map` go through their
+ *  accessors — they know the shader's uniform names; everything else takes `setMaterialParam`. */
+const isBuiltinMaterial = (material: Material): boolean =>
+  (material as unknown as { _colorKey: string | null })._colorKey !== null
+
+/** A slot's material was set behind the node's back (an engine-level restore of the glTF
+ *  material): drop what the node remembers of it, so the next read asks the engine. */
+const forgetMaterial = (node: Node, slot: number): void => {
+  const cache = (node as unknown as { _materials?: (Material | undefined)[] })._materials
+  if (cache) cache[slot] = undefined
+}
+
+/** One immediate-mode pass of a card the editor owns (a built-in node card, a plugin window). */
+const runCard = (ui: InspectorUI, render: (ui: InspectorUI) => void, event?: InspectorEvent): InspectorWidget[] =>
+  ui._run(render, event)
+
+export const sceneEditor = {
+  // ---- the loaded scene, by handle ----
+  patchNode, renameNode, reparentNode, nodeChanged, modelParts, describeAspects,
+  // ---- editor-run aspects (generators) and make() nodes ----
+  setProp, setMakeArg, gizmos, inspectorRender,
+  // ---- nodes ----
+  /** The preview pose of a model node (`editor: { clip, time }`) — idempotent; no clip = the rest pose. */
+  applyPose: applyEditorPose,
+  isLocked, setLocked,
+  // ---- materials ----
+  /** Assign a material def to one slot of a node (a material asset handle, an inline def, a shader). */
+  assignMaterial: assignMaterialDef,
+  /** One parameter into a live material: a value, or a texture URL that loads in. */
+  setMaterialParam: applyMaterialParam,
+  isBuiltinMaterial, forgetMaterial,
+  // ---- gizmo lines of the editor's own (a tool's hooks draw through `Gizmos` too) ----
+  GizmoBuffer, withGizmoScope,
+  // ---- cards + plugins ----
+  runCard,
+  /** The registry `registerEditorWindow` / `registerEditorTool` fill (`*.editor.ts` files). */
+  plugins: __editorPlugins,
+}
+
+/** The contract of an editor's in-world half with the SDK — the type of the `__sceneEditor` global. */
+export type SceneEditorApi = typeof sceneEditor

package/src/scene/editorPlugins.ts

@@ -3,9 +3,9 @@
 // scene-editor bundles (phase 10), so none of this reaches shipped app.js (nothing references it
 // there, and method-granular DCE drops it).
 //
-// The scene-editor harness (packages/projects/src/scene-editor) reads the registry through the
-// injected `__editorPlugins` global — the harness, the scene, and the editor files compile into
-// ONE bundle, so they share this module instance. Windows and tools describe their UI through the
+// The scene-editor harness reads the registry through the editor contract (`__sceneEditor.plugins`,
+// ./editor.ts) — the harness, the scene, and the editor files compile into ONE bundle, so they
+// share this module instance. Windows and tools describe their UI through the
 // same immediate-mode `InspectorUI` protocol custom inspector cards use (one widget vocabulary,
 // three mount points), and mutate the scene ONLY through the `editor` doc API — every plugin write
 // lands in the scene document (undoable, diffable), never in live engine state.