lecodes-cli 0.18.1 → 0.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "dependencies": {
     "@letary/chisel": "^0.10.0",
     "jimp": "^1.6.1"

package/runtime/scene-harness.json

@@ -1 +1 @@
-{"main.ts":"// The 3D scene-editor harness — a LeCodes app the editor host runs alongside a user scene bundle\r\n// (compiled with the modern SDK; replaces the legacy worker-SDK scene-viewer). The host:\r\n//\r\n//   1. runs the user's scene bundle with `__lecodesSceneEdit` set → the scene handle registers on\r\n//      `globalThis.__lecodesScenes` (sources real, aspects inert — see sdk docs/3d/scene-files.md);\r\n//   2. runs this bundle → it installs `globalThis.__lecodesSceneHarness` (the controller);\r\n//   3. calls `controller.attach(handle)` and wires `controller.callbacks`.\r\n//\r\n// The viewport DISPLAY layer (grid, selection outline, transform gizmo, viewport picking) lives in\r\n// the ENGINE now — viewer-lite's editor layer (`_creator._editorConnect`), lite viewport only; the\r\n// filament preview renders the bare scene. This harness stays the POLICY half: the host feeds it\r\n// engine picks (`pickName` — locked nodes, GLB part drill-down) and completed gizmo drags\r\n// (`applyPose` — applied live, transform read back for the file), and `entityOf` hands the host\r\n// the entity id behind a selection key. Orbit is any drag; zoom/pan/focus come from the host\r\n// (DOM wheel/keys belong to the Vue viewport). Plugin viewport tools keep working: an active tool\r\n// receives clicks as raycast hits (physics bodies when the build has them, ground plane otherwise).\r\n\r\nimport { OrbitCamera } from \"./orbit\"\r\n\r\n// The low-level bridge global every bundle runs against — the harness only walks the entity\r\n// hierarchy with it (wrapping foreign entity ids in `new Node(id)` would OVERWRITE the real nodes\r\n// in the SDK's registry, so id-level walking is the safe form). `computeBoundingBox` (subtree AABB\r\n// in the entity's local space) is a lite-engine host API — absent on filament.\r\ndeclare const _creator: {\r\n  getParent(entityId: number): number\r\n  computeBoundingBox?(entityId: number): Float32Array\r\n  getWorldMatrix(entityId: number, mat: Float32Array): void\r\n  setMaterial(entityId: number, materialId: number, index: number): void\r\n  getMaterial(entityId: number, index: number): number\r\n}\r\n\r\ntype SceneHandleLike = {\r\n  /** `nodes` is keyed by ABSOLUTE PATH ('/'-joined def keys) — the SDK owns this record; the\r\n   *  harness holds the same object and must never re-key it itself (see renameNode). */\r\n  load(): Promise<{ scene: Scene, nodes: Record<string, Node> }>\r\n  /** SceneHandle._describeAspects — aspect field schemas for the inspector (plain data). */\r\n  _describeAspects?(): unknown[]\r\n  /** SceneHandle._patchNode — live single-node rebuild/add/remove; the path carries the mount\r\n   *  point (its parent must exist for adds). */\r\n  _patchNode?(path: string, def: unknown): Promise<Node | null>\r\n  /** SceneHandle._renameNode — re-keys the node record (subtree included) + the engine name;\r\n   *  returns the new path, null on refusal. */\r\n  _renameNode?(path: string, newName: string): string | null\r\n  /** SceneHandle._reparentNode — re-keys + setParent keeping the local transform. */\r\n  _reparentNode?(path: string, newParentPath: string | null): string | null\r\n  /** SceneHandle._modelParts — a model node's INTERNAL rows (the `overrides` path grammar). */\r\n  _modelParts?(path: string): Promise<{ path: string, name: string, depth: number, node: Node }[]>\r\n  /** SceneHandle._editorNodeChanged — rebuild editor-run aspects whose ref() deps cover `path`. */\r\n  _editorNodeChanged?(path: string): void\r\n  /** SceneHandle._editorGizmos — every editor run's `Gizmos` lines + a change version. */\r\n  _editorGizmos?(): { version: number, batches: { color: string, alpha: number, segments: number[] }[] }\r\n  /** SceneHandle._editorSetProp — live prop edit on one editor-run aspect (rebuilds it). */\r\n  _editorSetProp?(hostPath: string, index: number, key: string, value: unknown): boolean\r\n  /** SceneHandle._editorSetMakeArg — live arg edit on a `make()` node (re-calls the factory). */\r\n  _editorSetMakeArg?(path: string, key: string, value: unknown): boolean\r\n  /** SceneHandle._inspectorRender — run an aspect's custom `static inspector` card. */\r\n  _inspectorRender?(\r\n    hostPath: string, index: number,\r\n    props: Record<string, unknown>, event?: { id: string, value?: unknown },\r\n  ): unknown[] | null\r\n}\r\n\r\ntype Vec3Tuple = [number, number, number]\r\n/** The SDK Shape one-of, as the host names it (see fitShape / SceneHarness). */\r\ntype ShapeKindName = \"auto\" | \"box\" | \"sphere\" | \"cylinder\" | \"capsule\" | \"mesh\" | \"convex\"\r\n\r\ntype HarnessCallbacks = {\r\n  /** Selection changed from INSIDE the world (a plugin's `editor.select`) — mirror host-side. */\r\n  onSelect?(name: string | null): void\r\n}\r\n\r\n/** Document operations the HOST implements (its commit/undo/patch machinery) — the doc-op half of\r\n *  the `editor` API handed to plugins (windows/tools). Installed via `controller.setEditorOps`. */\r\ntype EditorOps = {\r\n  nodes(): { path: string, name: string, kind: string }[]\r\n  uniqueName(base: string, parentPath?: string): string\r\n  addNode(name: string, def: Record<string, unknown>): boolean\r\n  setProp(path: string, key: string, value: unknown): boolean\r\n  removeNode(path: string): void\r\n  duplicate(path: string): string | null\r\n  transact(fn: () => void): void\r\n}\r\n\r\nconst state = {\r\n  handle: null as SceneHandleLike | null,\r\n  scene: null as Scene | null,\r\n  /** The SDK's path-keyed node record — the SAME object the handle owns (rename/reparent re-key\r\n   *  it SDK-side; the harness re-keys only its own part/selection state). */\r\n  nodes: {} as Record<string, Node>,\r\n  /** Reverse map: live node → absolute def path. */\r\n  paths: new Map<Node, string>(),\r\n  /** GLB internal nodes, addressable like nodes: key = `<defPath>::<partPath>` (+ reverse map). */\r\n  parts: new Map<string, Node>(),\r\n  partNames: new Map<Node, string>(),\r\n  orbit: null as OrbitCamera | null,\r\n  /** Selection key: absolute def path or `<defPath>::<partPath>`. */\r\n  selected: null as string | null,\r\n  /** The active viewport tool (`registerEditorTool` name) — clicks route to it. */\r\n  activeTool: null as string | null,\r\n  /** Host-implemented doc operations (the `editor` API's write half). */\r\n  editorOps: null as EditorOps | null,\r\n}\r\n\r\n// ---- part keys ---------------------------------------------------------------------------------\r\n// A model's internal nodes are selectable/editable through PART KEYS: `<defPath>::<partPath>` (the\r\n// part-path grammar is the SDK's — SceneHandle._modelParts enumerates it, `overrides` keys store\r\n// it; names exclude ':', so the first `::` is always the boundary). Everything key-addressed\r\n// (select / setNodeProp / focus) resolves through `resolveKey`, so a part behaves like a node —\r\n// except its persistence: the editor writes the transform into the MODEL's `overrides` record.\r\n\r\nconst PART_SEP = \"::\"\r\n\r\n/** Re-key `key` after `oldPath` moved to `newPath` (the path itself, `/` descendants, and `::`\r\n *  part keys of either). Null = untouched. Mirrors scene-editor/types.ts `rekeyPath` — the\r\n *  harness compiles standalone and cannot import it. */\r\nconst rekeyPath = (key: string, oldPath: string, newPath: string): string | null => {\r\n  if (key === oldPath) return newPath\r\n  if (key.startsWith(oldPath + \"/\") || key.startsWith(oldPath + PART_SEP)) {\r\n    return newPath + key.slice(oldPath.length)\r\n  }\r\n  return null\r\n}\r\n\r\nconst resolveKey = (key: string): Node | null => state.nodes[key] ?? state.parts.get(key) ?? null\r\n\r\n// ---- materials ---------------------------------------------------------------------------------\r\n// Live material edits (docs/scene-materials-plan.md §4): a parameter lands on the LIVE material of\r\n// a mesh node / a GLB-part slot / a material asset with `.set()` — the value tier, no rebuild; a\r\n// shader or kind switch reloads ONE material. Doc defs reach the harness as plain data in which a\r\n// material asset is `{ $material: \"./x.material.ts\" }` — lowered here to the handle the compile's\r\n// virtual entry registered on `__lecodesMaterials`.\r\n\r\ntype MaterialTarget = { node: string } | { part: string, slot?: number } | { asset: string }\r\n\r\n/** The registry captured at attach — a second bundle run in the same page (the preview host)\r\n *  overwrites the global with ITS handles, so each harness keeps the one that was current when it\r\n *  attached (the host sets it right before). Falls back to the global for older hosts. */\r\nlet capturedMaterials: Record<string, MaterialHandle> | null = null\r\nconst materialHandles = (): Record<string, MaterialHandle> =>\r\n  capturedMaterials ?? ((globalThis as any).__lecodesMaterials as Record<string, MaterialHandle> | undefined) ?? {}\r\n\r\nconst isMaterialRef = (v: unknown): v is { $material: string } =>\r\n  typeof v === \"object\" && v !== null && typeof (v as { $material?: unknown }).$material === \"string\"\r\n\r\n/** A doc material def → runtime def (asset refs resolved to handles). Null = unknown asset path. */\r\nconst lowerMaterial = (def: unknown): unknown => (isMaterialRef(def) ? materialHandles()[def.$material] ?? null : def)\r\n\r\n/** Lower every material position of a node def (its own, part-override slots, children). Null\r\n *  when a reference doesn't resolve — the host falls back to a re-run. */\r\nconst lowerNodeDef = (def: Record<string, unknown>): Record<string, unknown> | null => {\r\n  const out = { ...def }\r\n  if (out.material !== undefined) {\r\n    const m = lowerMaterial(out.material)\r\n    if (m === null) return null\r\n    out.material = m\r\n  }\r\n  if (out.overrides && typeof out.overrides === \"object\") {\r\n    const ov: Record<string, unknown> = {}\r\n    for (const [ p, entry ] of Object.entries(out.overrides as Record<string, Record<string, unknown>>)) {\r\n      const e = { ...entry }\r\n      if (e.materials && typeof e.materials === \"object\") {\r\n        const mats: Record<string, unknown> = {}\r\n        for (const [ slot, m ] of Object.entries(e.materials as Record<string, unknown>)) {\r\n          const lowered = lowerMaterial(m)\r\n          if (lowered === null) return null\r\n          mats[slot] = lowered\r\n        }\r\n        e.materials = mats\r\n      }\r\n      ov[p] = e\r\n    }\r\n    out.overrides = ov\r\n  }\r\n  if (out.children && typeof out.children === \"object\") {\r\n    const ch: Record<string, unknown> = {}\r\n    for (const [ n, c ] of Object.entries(out.children as Record<string, Record<string, unknown>>)) {\r\n      const lowered = lowerNodeDef(c)\r\n      if (lowered === null) return null\r\n      ch[n] = lowered\r\n    }\r\n    out.children = ch\r\n  }\r\n  return out\r\n}\r\n\r\n/** The live Material behind a target (null = none assigned yet / unknown key). */\r\nconst materialAt = (target: MaterialTarget): Material | null => {\r\n  if (\"asset\" in target) return materialHandles()[target.asset]?.material ?? null\r\n  if (\"node\" in target) return resolveKey(target.node)?.getMaterial(0) ?? null\r\n  return resolveKey(target.part)?.getMaterial(target.slot ?? 0) ?? null\r\n}\r\n\r\n/** Push one parameter into a live material. Built-in materials take `color`/`map` through their\r\n *  accessors (they know the shader's uniform names); everything else is a `.set()`, where a\r\n *  non-`#` string is a texture URL that loads in. */\r\nconst pushMaterialParam = (m: Material, name: string, value: unknown): void => {\r\n  const builtin = (m as unknown as { _colorKey: string | null })._colorKey !== null\r\n  if (builtin && name === \"color\") { m.color = value as string; return }\r\n  if (builtin && name === \"map\") {\r\n    if (typeof value === \"string\") void Texture.load(value).then((t) => { m.map = t })\r\n    else m.map = null\r\n    return\r\n  }\r\n  void __applyMaterialParam(m, name, value as never)\r\n}\r\n\r\n/** The original (glTF) material of every part slot overridden live, so clearing restores it. */\r\nconst originalSlotMaterials = new Map<string, number>()\r\n\r\n/** (Re-)enumerate one model's internal nodes into the part maps; returns plain rows for the host. */\r\nconst refreshModelParts = async (path: string): Promise<{ path: string, name: string, depth: number }[]> => {\r\n  const handle = state.handle\r\n  if (!handle?._modelParts) return []\r\n  const rows = await handle._modelParts(path)\r\n  for (const [ key, node ] of [ ...state.parts ]) {\r\n    if (key.startsWith(path + PART_SEP)) { state.parts.delete(key); state.partNames.delete(node) }\r\n  }\r\n  for (const r of rows) {\r\n    const key = path + PART_SEP + r.path\r\n    state.parts.set(key, r.node)\r\n    state.partNames.set(r.node, key)\r\n  }\r\n  return rows.map((r) => ({ path: r.path, name: r.name, depth: r.depth }))\r\n}\r\n\r\n/** Editor-tool gizmo lines (a tool's hooks draw through `Gizmos` too) — one buffer for the active\r\n *  tool, cleared on every hook call and on tool switch. */\r\nconst toolGizmos = new __GizmoBuffer()\r\nlet toolGizmosVersion = 0\r\n\r\n/** A node (or a part inside a model) changed — let the scene's editor-run aspects (generators)\r\n *  that reference it via ref() rebuild. Part keys collapse to their model's def path. */\r\nconst notifyEditorChanged = (key: string | null): void => {\r\n  if (!key) return\r\n  const i = key.indexOf(PART_SEP)\r\n  state.handle?._editorNodeChanged?.(i < 0 ? key : key.slice(0, i))\r\n}\r\n\r\n/** After the SDK re-keyed the shared node record (rename/reparent), re-key the HARNESS-owned\r\n *  state that mirrors those paths: the reverse map, part keys, node-card cache, selection. */\r\nconst rekeyLocal = (oldPath: string, newPath: string): void => {\r\n  state.paths = new Map(Object.entries(state.nodes).map(([ p, n ]) => [ n, p ]))\r\n  for (const [ key, part ] of [ ...state.parts ]) {\r\n    const next = rekeyPath(key, oldPath, newPath)\r\n    if (next === null) continue\r\n    state.parts.delete(key)\r\n    state.parts.set(next, part)\r\n    state.partNames.set(part, next)\r\n  }\r\n  for (const [ key, ui ] of [ ...nodeCards ]) {\r\n    const next = rekeyPath(key, oldPath, newPath)\r\n    if (next === null) continue\r\n    nodeCards.delete(key)\r\n    nodeCards.set(next, ui)\r\n  }\r\n  if (state.selected) state.selected = rekeyPath(state.selected, oldPath, newPath) ?? state.selected\r\n}\r\n\r\nconst isEditorNode = (node: Node): boolean => (node.name ?? \"\").startsWith(\"__editor\")\r\n\r\n// ---- built-in node cards (immediate-mode inspector protocol — sdk core/InspectorUI.ts) ----------\r\n// The ANIMATION card on model nodes with baked clips: clip dropdown (live from model.anim.clips),\r\n// speed/loop, Play/Stop preview. Pure editor state — nothing here writes to the scene file\r\n// (it's a preview; play-mode behavior belongs in aspects/code). ModelAnimation is attached by the\r\n// Model constructor itself, so it is live even in edit mode.\r\n\r\nconst nodeCards = new Map<string, InspectorUI>()\r\n\r\nconst renderNodeCard = (name: string, event?: { id: string, value?: unknown }): unknown[] | null => {\r\n  const node = state.nodes[name]\r\n  if (!(node instanceof Model)) return null\r\n  const clips = node.anim.clips\r\n  if (clips.length === 0) return null\r\n  let ui = nodeCards.get(name)\r\n  if (!ui) { ui = new InspectorUI(); nodeCards.set(name, ui) }\r\n  return ui._run((u) => {\r\n    u.header(\"Animation\")\r\n    const clip = String(u.select(\"clip\", clips.map((c) => c.name)))\r\n    const speed = u.number(\"speed\", { min: 0.1, max: 4, step: 0.1, value: 1 })\r\n    const loop = u.switch(\"loop\", { value: true })\r\n    const playing = node.anim.busy || node.anim.loop !== undefined\r\n    if (playing) node.anim.speed = speed\r\n    if (u.button(playing ? \"Restart\" : \"Play\")) {\r\n      node.anim.speed = speed\r\n      if (loop) node.anim.playLoop(clip)\r\n      else node.anim.play(clip, { restart: true })\r\n    }\r\n    if (u.button(\"Stop\")) node.anim.stop()   // fades to the rest pose\r\n    const duration = clips.find((c) => c.name === clip)?.duration\r\n    u.info(playing ? \"playing…\" : duration !== undefined ? `${duration.toFixed(2)}s` : \"\")\r\n  }, event)\r\n}\r\n\r\n/** The def path a raycast-hit entity belongs to (a GLB hit resolves to its Model, etc.). */\r\nconst ownerPath = (node: Node | null): string | null => {\r\n  let cur: Node | null = node\r\n  for (let i = 0; cur && i < 32; i++) {\r\n    const path = state.paths.get(cur)\r\n    if (path) return path\r\n    cur = cur.parent\r\n  }\r\n  return null\r\n}\r\n\r\nconst applySelection = (name: string | null, notify: boolean): void => {\r\n  state.selected = name\r\n  if (notify) controller.callbacks.onSelect?.(name)\r\n}\r\n\r\n// ---- editor plugins (windows + viewport tools — sdk scene/editorPlugins.ts) ---------------------\r\n// `*.editor.ts` files register into the injected `__editorPlugins` registry (same bundle → same\r\n// module instance). Windows render through the immediate-mode InspectorUI protocol like inspector\r\n// cards; tools receive viewport clicks as raycast hits. Both get the `editor` scripting API:\r\n// selection/raycast are answered here, doc writes delegate to the host's EditorOps (plugins write\r\n// the DOCUMENT, never live state — one undo stack for humans and plugins alike).\r\n\r\nconst isInSubtree = (node: Node, root: Node): boolean => {\r\n  let cur: Node | null = node\r\n  for (let i = 0; cur && i < 64; i++) {\r\n    if (cur === root) return true\r\n    cur = cur.parent\r\n  }\r\n  return false\r\n}\r\n\r\n/** Raycast under a viewport pixel: precise mesh hit via Jolt bodies when the build/scene has any\r\n *  (edit mode attaches none itself — aspects are inert), else / on miss the ground plane.\r\n *  `exclude` steps the ray past any hit inside that subtree (editor nodes are always stepped). */\r\nconst raycastViewport = (x: number, y: number, exclude?: Node | null): { point: Vec3Tuple, normal: Vec3Tuple, node: string | null } | null => {\r\n  const scene = state.scene\r\n  if (!scene) return null\r\n  const ray = scene.camera.getRay(x, y)\r\n  if (Physics.supported) {\r\n    let origin: Vec3Tuple = [ ray.origin.x, ray.origin.y, ray.origin.z ]\r\n    let remaining = 2000\r\n    for (let i = 0; i < 8 && remaining > 0; i++) {\r\n      const hit = Physics.raycast(origin, ray.dir, remaining)\r\n      if (!hit) break\r\n      // (empties/cameras have no geometry — their markers are overlay gizmos, never hit here)\r\n      if (hit.node && !isEditorNode(hit.node)\r\n          && !(exclude && isInSubtree(hit.node, exclude))) {\r\n        return {\r\n          point: [ hit.point.x, hit.point.y, hit.point.z ],\r\n          normal: [ hit.normal.x, hit.normal.y, hit.normal.z ],\r\n          node: hit.node ? ownerPath(hit.node) : null,\r\n        }\r\n      }\r\n      // an excluded/editor body — resume the cast just past it\r\n      const step = remaining * hit.fraction + 0.01\r\n      origin = [ origin[0] + ray.dir.x * step, origin[1] + ray.dir.y * step, origin[2] + ray.dir.z * step ]\r\n      remaining -= step\r\n    }\r\n  }\r\n  const t = -ray.origin.y / ray.dir.y\r\n  if (!Number.isFinite(t) || t <= 0) return null\r\n  const p = ray.getPoint(t)\r\n  return { point: [ p.x, p.y, p.z ], normal: [ 0, 1, 0 ], node: null }\r\n}\r\n\r\nconst editorApi = {\r\n  get selection(): string | null { return state.selected },\r\n  select(name: string | null): void { applySelection(name && resolveKey(name) ? name : null, true) },\r\n  nodes: (): { name: string, kind: string }[] => state.editorOps?.nodes() ?? [],\r\n  uniqueName: (base: string): string => state.editorOps?.uniqueName(base) ?? base,\r\n  addNode: (name: string, def: Record<string, unknown>): boolean => state.editorOps?.addNode(name, def) === true,\r\n  setProp: (name: string, key: string, value: unknown): boolean => state.editorOps?.setProp(name, key, value) === true,\r\n  removeNode: (name: string): void => { state.editorOps?.removeNode(name) },\r\n  duplicate: (name: string): string | null => state.editorOps?.duplicate(name) ?? null,\r\n  raycast: raycastViewport,\r\n  transact: (fn: () => void): void => { state.editorOps ? state.editorOps.transact(fn) : fn() },\r\n}\r\n\r\n/** Per-window InspectorUI instances (all their field keys are transient editor state). */\r\nconst windowUIs = new Map<number, InspectorUI>()\r\n\r\n/** A node's subtree AABB in WORLD space (the engine's local box through the node's own world\r\n *  matrix), null while degenerate / unsupported. */\r\nconst worldBounds = (node: Node): { min: Vec3Tuple, max: Vec3Tuple } | null => {\r\n  const box = _creator.computeBoundingBox?.(node.id)\r\n  if (!box) return null\r\n  if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return null\r\n  // world AABB from the 8 local-space corners (the local box doesn't include the node's own\r\n  // transform — worldMatrix carries it)\r\n  const m = node.worldMatrix\r\n  const min: Vec3Tuple = [ Infinity, Infinity, Infinity ]\r\n  const max: Vec3Tuple = [ -Infinity, -Infinity, -Infinity ]\r\n  for (let i = 0; i < 8; i++) {\r\n    const p = m.transformPoint([ box[i & 1 ? 3 : 0], box[i & 2 ? 4 : 1], box[i & 4 ? 5 : 2] ])\r\n    const c = [ p.x, p.y, p.z ]\r\n    for (let k = 0; k < 3; k++) {\r\n      if (c[k] < min[k]) min[k] = c[k]\r\n      if (c[k] > max[k]) max[k] = c[k]\r\n    }\r\n  }\r\n  return { min, max }\r\n}\r\n\r\n/** Orbit onto a world AABB: target = center, distance from the largest extent. */\r\nconst frameBounds = (min: Vec3Tuple, max: Vec3Tuple) => {\r\n  const size = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2])\r\n  state.orbit?.focus(\r\n    [ (min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2 ],\r\n    Math.max(1, size * 1.4),\r\n  )\r\n}\r\n\r\nconst controller = {\r\n  callbacks: {} as HarnessCallbacks,\r\n\r\n  /** Attach to a user scene handle (from `globalThis.__lecodesScenes`). Returns the node PATHS\r\n   *  (build-completion order, not file order — the host sorts for display). */\r\n  async attach(handle: SceneHandleLike): Promise<{ nodes: string[] }> {\r\n    // synchronously, before any await: the host sets the registry for THIS world right around\r\n    // the call (a second bundle run in the page — the preview host — writes the same global)\r\n    capturedMaterials = ((globalThis as any).__lecodesMaterials as Record<string, MaterialHandle> | undefined) ?? null\r\n    const { scene, nodes } = await handle.load()\r\n    state.handle = handle\r\n    state.scene = scene\r\n    state.nodes = nodes\r\n    state.paths = new Map(Object.entries(nodes).map(([ path, node ]) => [ node, path ]))\r\n\r\n    scene.open()\r\n\r\n    state.orbit = new OrbitCamera(scene.camera)\r\n\r\n    // any drag orbits (nothing else claims viewport touches — no pick colliders in the world)\r\n    scene.addEventListener(\"touchstart\", (ev) => {\r\n      ev.track({ onMove: (pos) => state.orbit?.rotate(pos.deltaX, pos.deltaY) })\r\n    })\r\n\r\n    // an active plugin tool owns viewport clicks — they arrive as raycast hits (selection itself\r\n    // is host-driven from the tree, so a click outside a tool does nothing)\r\n    scene.addEventListener(\"click\", (ev) => {\r\n      if (!state.activeTool) return\r\n      const tool = __editorPlugins.tools.find((t) => t.name === state.activeTool)\r\n      if (!tool?.hooks.onViewportClick) return\r\n      const hit = raycastViewport(ev.clientX, ev.clientY)\r\n      if (hit) {\r\n        // a throwing tool logs and skips — it can't take the editor down; Gizmos calls inside\r\n        // the hook land in the tool's own buffer (cleared per call)\r\n        try { toolGizmosVersion++; __withGizmoScope(toolGizmos, () => tool.hooks.onViewportClick!(hit, editorApi)) }\r\n        catch (e) { console.error(\"[scene-editor] tool click failed:\", e) }\r\n      }\r\n    })\r\n\r\n    // GLB internal hierarchies are part of the editable scene — enumerate them up front so part\r\n    // keys resolve before the host asks for the rows\r\n    await Promise.all(Object.keys(nodes).map((name) => refreshModelParts(name)))\r\n\r\n    return { nodes: Object.keys(nodes) }\r\n  },\r\n\r\n  /** Host-driven selection (tree click). Accepts node names AND part keys. Does not echo onSelect. */\r\n  select(name: string | null): void {\r\n    applySelection(name && resolveKey(name) ? name : null, false)\r\n  },\r\n\r\n  /** The entity id behind a selection key (node name or GLB part key); 0 = unknown. The host\r\n   *  feeds it to the engine's editor layer (selection outline + gizmo target). */\r\n  entityOf(name: string): number {\r\n    return resolveKey(name)?.id ?? 0\r\n  },\r\n\r\n  /** Resolve an ENGINE pick (raw entity id) to a selection key — the policy half of viewport\r\n   *  picking. Walks the hit entity up to the NEAREST tracked def node (its absolute path — with\r\n   *  nested def nodes the deepest one wins); a hit inside the CURRENTLY SELECTED model resolves\r\n   *  to its deepest part key instead (click-again drill-down). Locked nodes yield null (the\r\n   *  click selects nothing — the host keeps the current selection). */\r\n  pickName(entityId: number): string | null {\r\n    if (!entityId) return null\r\n    const nodeIds = new Map<number, string>()\r\n    for (const [ path, node ] of Object.entries(state.nodes)) nodeIds.set(node.id, path)\r\n    const partIds = new Map<number, string>()\r\n    for (const [ key, node ] of state.parts) partIds.set(node.id, key)\r\n    let part: string | null = null\r\n    for (let id = entityId, i = 0; id !== 0 && i < 64; i++) {\r\n      part ??= partIds.get(id) ?? null   // the deepest enumerated part containing the hit\r\n      const path = nodeIds.get(id)\r\n      if (path !== undefined) {\r\n        const node = state.nodes[path]\r\n        if (node && (node as { _sceneLocked?: boolean })._sceneLocked) return null\r\n        const inSelected = state.selected === path || state.selected?.startsWith(path + PART_SEP)\r\n        return part && inSelected ? part : path\r\n      }\r\n      id = _creator.getParent(id)\r\n    }\r\n    return null\r\n  },\r\n\r\n  /** The selection key an entity belongs to — its deepest enumerated GLB part, else the owning\r\n   *  def node's path — with no lock / drill-down policy (drop targets: a material tile lands on\r\n   *  whatever is under the cursor). Null for editor-only / untracked entities. */\r\n  hitKey(entityId: number): string | null {\r\n    if (!entityId) return null\r\n    const nodeIds = new Map<number, string>()\r\n    for (const [ path, node ] of Object.entries(state.nodes)) nodeIds.set(node.id, path)\r\n    const partIds = new Map<number, string>()\r\n    for (const [ key, node ] of state.parts) partIds.set(node.id, key)\r\n    let part: string | null = null\r\n    for (let id = entityId, i = 0; id !== 0 && i < 64; i++) {\r\n      part ??= partIds.get(id) ?? null\r\n      const path = nodeIds.get(id)\r\n      if (path !== undefined) return part ?? path\r\n      id = _creator.getParent(id)\r\n    }\r\n    return null\r\n  },\r\n\r\n  /** Apply a completed gizmo drag: set the node's (or part's) local transform from the engine's\r\n   *  decomposed pose, then return position/eulerAngles/scale read BACK from the engine — exactly\r\n   *  the values the host should persist (same read-back rule as setFromView: never compose eulers\r\n   *  by hand, the engines' setter conventions differ). */\r\n  applyPose(\r\n    name: string,\r\n    pose: { position: Vec3Tuple, quaternion: [number, number, number, number], scale: Vec3Tuple },\r\n  ): { position: Vec3Tuple, eulerAngles: Vec3Tuple, scale: Vec3Tuple } | null {\r\n    const node = resolveKey(name)\r\n    if (!node) return null\r\n    node.position = pose.position\r\n    node.quaternion = pose.quaternion\r\n    node.scale = pose.scale\r\n    notifyEditorChanged(name)\r\n    const p = node.position, e = node.eulerAngles, s = node.scale\r\n    return {\r\n      position: [ p.x, p.y, p.z ],\r\n      eulerAngles: [ e.x, e.y, e.z ],\r\n      scale: [ s.x, s.y, s.z ],\r\n    }\r\n  },\r\n\r\n  /** A model node's internal GLB rows (path/name/depth) — the tree's expandable part list. Also\r\n   *  (re-)binds the part keys, so call it after anything that reloads the model. */\r\n  modelParts(name: string): Promise<{ path: string, name: string, depth: number }[]> {\r\n    return refreshModelParts(name)\r\n  },\r\n\r\n  /** The camera PREVIEW source for a node carrying a `CameraPlace` (edit mode registers the\r\n   *  generator instance on the node): its entity + lens. Null when the node is unknown or has no\r\n   *  place. (`hide` stays for older engine builds — markers are overlay gizmos now, not scene\r\n   *  entities, and the inset skips overlay roots by itself.) */\r\n  cameraPreview(name: string): { entityId: number, fov: number, near: number, far: number, hide: number[] } | null {\r\n    const node = resolveKey(name)\r\n    if (!node) return null\r\n    const place = (node as Node & { cameraPlace?: { fov: number, near: number, far: number } }).cameraPlace\r\n      ?? (node.get(CameraPlace) as { fov: number, near: number, far: number } | undefined)\r\n    if (!place) return null\r\n    return { entityId: node.id, fov: place.fov, near: place.near, far: place.far, hide: [] }\r\n  },\r\n\r\n  /** Clip names of a loaded model node (the inspector's preview-pose dropdown); [] otherwise. */\r\n  modelClips(name: string): string[] {\r\n    const node = resolveKey(name) as (Node & { anim?: { clips: readonly { name: string }[] } }) | null\r\n    return node?.anim ? node.anim.clips.map((c) => c.name) : []\r\n  },\r\n\r\n  /** Current live transform of a node OR part (part inspectors have no doc def to read from). */\r\n  getNodeProps(name: string): { position: Vec3Tuple, eulerAngles: Vec3Tuple, scale: Vec3Tuple, visible: boolean } | null {\r\n    const node = resolveKey(name)\r\n    if (!node) return null\r\n    const p = node.position, e = node.eulerAngles, s = node.scale\r\n    return {\r\n      position: [ p.x, p.y, p.z ],\r\n      eulerAngles: [ e.x, e.y, e.z ],\r\n      scale: [ s.x, s.y, s.z ],\r\n      visible: !!node.visible,   // native bridges answer 0/1 — normalize for the inspector\r\n    }\r\n  },\r\n\r\n  /** Apply an inspector value edit to the live node or GLB part. Transform/visibility/locked only —\r\n   *  anything else is a structural change (the host recompiles the scene bundle instead). */\r\n  setNodeProp(name: string, key: \"position\" | \"eulerAngles\" | \"scale\" | \"visible\" | \"locked\" | \"editor\", value: unknown): void {\r\n    const node = resolveKey(name)\r\n    if (!node) return\r\n    if (key === \"editor\") {\r\n      // the preview pose (`editor: { clip, time }`) — edit-mode only, never a runtime default\r\n      __applyEditorPose(node, (value ?? undefined) as { clip?: string, time?: number } | undefined)\r\n      return\r\n    }\r\n    if (key === \"position\") node.position = value as Vec3Tuple\r\n    else if (key === \"eulerAngles\") node.eulerAngles = value as Vec3Tuple\r\n    else if (key === \"scale\") node.scale = (typeof value === \"number\" ? value : value as Vec3Tuple) as any\r\n    else if (key === \"visible\") node.visible = value === true\r\n    else if (key === \"locked\") {\r\n      // an editor-only flag kept on the live node (the coming selection/manipulation layer\r\n      // consults it; fields edit regardless)\r\n      ;(node as { _sceneLocked?: boolean })._sceneLocked = value === true\r\n      return\r\n    }\r\n    notifyEditorChanged(name)\r\n  },\r\n\r\n  /** Live prop edit on an editor-run aspect (generator): update the instance + rebuild. False =\r\n   *  that entry isn't editor-run (inert doc data) or the bundle predates generators. */\r\n  updateEditorAspect(name: string, index: number, key: string, value: unknown): boolean {\r\n    return state.handle?._editorSetProp?.(name, index, key, value) === true\r\n  },\r\n\r\n  /** Every editor gizmo line currently drawn (generator rebuilds + the active tool) as world-space\r\n   *  LINES batches, with a version that changes whenever any of them re-ran — the host pushes to\r\n   *  the engine overlay only when it moves. Empty on bundles predating gizmos. */\r\n  gizmos(): { version: number, batches: { color: string, alpha: number, segments: number[] }[] } {\r\n    const runs = state.handle?._editorGizmos?.() ?? { version: 0, batches: [] }\r\n    const batches = runs.batches.slice()\r\n    for (const b of toolGizmos.batches) if (b.segments.length > 0) batches.push(b)\r\n    return { version: runs.version * 1000003 + toolGizmosVersion, batches }\r\n  },\r\n\r\n  /** Live arg edit on a `make()` node: re-calls the factory through the tracked run — no compile\r\n   *  (the factory is already in the bundle). False = not a make node / older SDK. */\r\n  setMakeArg(name: string, key: string, value: unknown): boolean {\r\n    return state.handle?._editorSetMakeArg?.(name, key, value) === true\r\n  },\r\n\r\n  /** Custom inspector cards (immediate-mode widget lists — sdk core/InspectorUI.ts). An aspect\r\n   *  target runs the class's `static inspector` through the scene handle (`opts.props` = the\r\n   *  entry's CURRENT doc props, passed on every call; `opts.event` = buttons/state edits only);\r\n   *  a bare node name renders the built-in node card (the ANIMATION card on models with clips).\r\n   *  Null = no card — the host falls back to plain fields. */\r\n  inspector(\r\n    target: { name: string, aspect?: number },\r\n    opts?: { props?: Record<string, unknown>, event?: { id: string, value?: unknown } },\r\n  ): unknown[] | null {\r\n    if (typeof target.aspect === \"number\") {\r\n      return state.handle?._inspectorRender?.(target.name, target.aspect, opts?.props ?? {}, opts?.event) ?? null\r\n    }\r\n    return renderNodeCard(target.name, opts?.event)\r\n  },\r\n\r\n  /** Live parameter write on a mesh node's material, a GLB part's slot material, or a material\r\n   *  asset (every user follows). `value` is plain: number / bool / `#colour` / texture URL /\r\n   *  vector; null clears a texture. False = no live material there (the host re-runs/patches). */\r\n  setMaterialParam(target: MaterialTarget, name: string, value: unknown): boolean {\r\n    if (\"asset\" in target) {\r\n      const h = materialHandles()[target.asset]\r\n      if (!h) return false\r\n      h.setParam(name, value as never)\r\n      return true\r\n    }\r\n    const m = materialAt(target)\r\n    if (!m) return false\r\n    pushMaterialParam(m, name, value)\r\n    return true\r\n  },\r\n\r\n  /** Replace a material asset's whole definition (a shader / kind switch): the shared instance\r\n   *  rebuilds and re-assigns to every node using it. False = unknown asset. */\r\n  async patchMaterial(assetPath: string, def: Record<string, unknown>): Promise<boolean> {\r\n    const h = materialHandles()[assetPath]\r\n    if (!h) return false\r\n    await h.reset(def as never)\r\n    return true\r\n  },\r\n\r\n  /** Assign (def) or clear (null) the material of one GLB-part slot live. Clearing restores the\r\n   *  glTF material captured on the first live override; a slot never overridden live has nothing\r\n   *  to restore → false (the host re-runs, which rebuilds the model from its def). */\r\n  async setPartMaterial(partKey: string, slot: number, def: Record<string, unknown> | null): Promise<boolean> {\r\n    const node = resolveKey(partKey)\r\n    if (!node) return false\r\n    const key = `${partKey}#${slot}`\r\n    if (def === null) {\r\n      const orig = originalSlotMaterials.get(key)\r\n      if (orig === undefined) return false\r\n      _creator.setMaterial(node.id, orig, slot)\r\n      const cache = (node as unknown as { _materials?: (Material | undefined)[] })._materials\r\n      if (cache) cache[slot] = undefined\r\n      return true\r\n    }\r\n    const lowered = lowerMaterial(def)\r\n    if (lowered === null) return false\r\n    if (!originalSlotMaterials.has(key)) originalSlotMaterials.set(key, _creator.getMaterial(node.id, slot))\r\n    await __assignMaterialDef(node, slot, lowered as never)\r\n    return true\r\n  },\r\n\r\n  /** Live structural patch: rebuild / add (`def`) or remove (`def === null`) ONE node at `path`\r\n   *  from plain def data — the SDK re-instantiates it through the same defineScene builder, so\r\n   *  nothing recompiles. The path carries the mount point. The HOST guarantees the def is plain\r\n   *  data (it bails to a re-run on `$expr` and `$asset` values). False = the SDK can't patch. */\r\n  async patchNode(path: string, def: Record<string, unknown> | null): Promise<boolean> {\r\n    const handle = state.handle\r\n    if (!handle?._patchNode) return false\r\n    // material asset refs → registered handles (an unknown one means the bundle predates the\r\n    // asset — only a compile picks it up)\r\n    const lowered = def === null ? null : lowerNodeDef(def)\r\n    if (def !== null && lowered === null) return false\r\n    const node = await handle._patchNode(path, lowered)\r\n    state.paths = new Map(Object.entries(state.nodes).map(([ p, nd ]) => [ nd, p ]))\r\n    notifyEditorChanged(path)   // generators referencing the patched node follow it\r\n    // the node object was replaced/removed — its part bindings (if it was a model) went with it\r\n    await refreshModelParts(path)\r\n    const sel = state.selected\r\n    if (sel === path || sel?.startsWith(path + \"/\") || sel?.startsWith(path + PART_SEP)) {\r\n      const alive = sel === path ? node : (sel ? resolveKey(sel) : null)\r\n      if (!alive) state.selected = null\r\n    }\r\n    return true\r\n  },\r\n\r\n  /** Live rename (bare sibling segment). The SDK owns the shared node record and re-keys it —\r\n   *  subtree, editor runs, and the engine-side display name included; the harness re-keys only\r\n   *  its OWN state (reverse path map, part keys, node-card cache, selection). The document is\r\n   *  the source of truth. */\r\n  renameNode(path: string, newName: string): boolean {\r\n    const newPath = state.handle?._renameNode?.(path, newName) ?? null\r\n    if (newPath === null) return false\r\n    rekeyLocal(path, newPath)\r\n    return true\r\n  },\r\n\r\n  /** Live reparent keeping the LOCAL transform — the same semantics the scene file describes\r\n   *  (a node under a transformed parent shifts in world space). `newParentPath` null = root.\r\n   *  The node's (and its subtree's) PATHS change with the move — same re-key story as rename. */\r\n  reparentNode(path: string, newParentPath: string | null): boolean {\r\n    const newPath = state.handle?._reparentNode?.(path, newParentPath) ?? null\r\n    if (newPath === null) return false\r\n    rekeyLocal(path, newPath)\r\n    return true\r\n  },\r\n\r\n  /** Live scene-level tweak. Only `skybox` is applicable post-creation for now — the host falls\r\n   *  back to a re-run for everything else. */\r\n  setSceneProp(key: string, value: unknown): boolean {\r\n    if (key === \"skybox\" && state.scene && typeof value === \"string\") {\r\n      state.scene.skybox = value\r\n      return true\r\n    }\r\n    return false\r\n  },\r\n\r\n  zoom(delta: number): void { state.orbit?.zoom(delta) },\r\n  pan(deltaX: number, deltaY: number): void { state.orbit?.pan(deltaX, deltaY) },\r\n\r\n  /** Raycast under a viewport pixel (physics bodies when present, ground-plane fallback) — the\r\n   *  host's drop-to-place path; same hit shape the plugin `editor.raycast` answers. */\r\n  raycast(x: number, y: number): { point: Vec3Tuple, normal: Vec3Tuple, node: string | null } | null {\r\n    return raycastViewport(x, y)\r\n  },\r\n\r\n  /** Aspect field schemas (AspectClassInfo[]) for every aspect class the scene references — the\r\n   *  inspector's editors. Computed in-bundle because only the bundle holds the ctors. */\r\n  aspectSchemas(): unknown[] {\r\n    return state.handle?._describeAspects?.() ?? []\r\n  },\r\n\r\n  /** Registered editor windows (`registerEditorWindow` in `*.editor.ts` files), display order. */\r\n  editorWindows(): { title: string }[] {\r\n    return __editorPlugins.windows.map((w) => ({ title: w.title }))\r\n  },\r\n\r\n  /** One immediate-mode pass of a registered window — same widget-list protocol as inspector\r\n   *  cards, except every field key is transient editor state (windows have no doc entry). */\r\n  renderWindow(index: number, event?: { id: string, value?: unknown }): unknown[] | null {\r\n    const win = __editorPlugins.windows[index]\r\n    if (!win) return null\r\n    let ui = windowUIs.get(index)\r\n    if (!ui) { ui = new InspectorUI(); windowUIs.set(index, ui) }\r\n    return ui._run((u) => win.render(u, editorApi), event)\r\n  },\r\n\r\n  /** Registered viewport tools (`registerEditorTool`) — the host's extra toolbar entries. */\r\n  editorTools(): { name: string, cursor?: string, icon?: string }[] {\r\n    return __editorPlugins.tools.map((t) => ({ name: t.name, cursor: t.hooks.cursor, icon: t.hooks.icon }))\r\n  },\r\n\r\n  /** Activate a plugin tool (null = deactivate). While active, viewport clicks route to the\r\n   *  tool's hooks; selection itself is unaffected. */\r\n  setActiveTool(name: string | null): void {\r\n    state.activeTool = name && __editorPlugins.tools.some((t) => t.name === name) ? name : null\r\n    toolGizmos.clear()\r\n    toolGizmosVersion++\r\n  },\r\n\r\n  /** Install the host's document operations — the write half of the plugin `editor` API. */\r\n  setEditorOps(ops: EditorOps): void {\r\n    state.editorOps = ops\r\n  },\r\n\r\n  /** Introspection for driving the editor headlessly (CDP/tests): selection + tool state, plus a\r\n   *  live euler-semantics probe against the running engine (the setter convention differs across\r\n   *  shipped engines — see setFromView). */\r\n  _debug(): unknown {\r\n    const probe = new Node()\r\n    probe.eulerAngles = [ 0, 0, 90 ]\r\n    const y = probe.quaternion.rotateVec3([ 0, 1, 0 ])\r\n    const probe2 = new Node()\r\n    probe2.quaternion = Quat.fromAxisAngle([ 0, 0, 1 ], Math.PI / 2)\r\n    const y2 = probe2.quaternion.rotateVec3([ 0, 1, 0 ])\r\n    // world poses of every def node + any node named in `names` under them — a numeric probe\r\n    const poses: Record<string, number[]> = {}\r\n    const visit = (n: Node, key: string, depth: number): void => {\r\n      const m = n.worldMatrix\r\n      const pos = m.position, z = m.basisZ, y = m.basisY\r\n      poses[key] = [ pos.x, pos.y, pos.z, z.x, z.y, z.z, y.x, y.y, y.z ].map((v) => Math.round(v * 1000) / 1000)\r\n      if (depth > 6) return\r\n      for (const c of n.children) if (c.name && !isEditorNode(c)) visit(c, `${key}/${c.name}`, depth + 1)\r\n    }\r\n    for (const [ path, n ] of Object.entries(state.nodes)) if (!path.includes(\"/\")) visit(n, path, 0)\r\n    return {\r\n      poses,\r\n      selected: state.selected,   // def PATH (\"city/in1/pt1\") OR `<defPath>::<partPath>` part key\r\n      activeTool: state.activeTool,\r\n      eulerZ90MapsYTo: [ y.x, y.y, y.z ],\r\n      quatZ90MapsYTo: [ y2.x, y2.y, y2.z ],   // standard/faithful: (−1, 0, 0)\r\n    }\r\n  },\r\n\r\n  /** Pose the named node from the CURRENT editor viewpoint (the camera node's \"Set from view\"):\r\n   *  applies the live camera's world pose to the node quaternion-faithfully, then returns the\r\n   *  parent-local position/eulerAngles read BACK from the engine — exactly the values the host\r\n   *  should write to the file (never compose eulers by hand: the shipped engines apply the\r\n   *  eulerAngles setter with differing conventions, so only an engine read-back round-trips). */\r\n  setFromView(name: string): { position: Vec3Tuple, eulerAngles: Vec3Tuple } | null {\r\n    const node = resolveKey(name)\r\n    const cam = state.scene?.camera\r\n    if (!node || !cam) return null\r\n    const parent = node.parent\r\n    const camPos = cam.worldPosition\r\n    node.quaternion = parent\r\n      ? parent.worldQuaternion.invert().mul(cam.worldQuaternion)\r\n      : cam.worldQuaternion\r\n    node.position = parent ? parent.worldMatrix.invert().transformPoint(camPos) : camPos\r\n    notifyEditorChanged(name)\r\n    const p = node.position, e = node.eulerAngles\r\n    return { position: [ p.x, p.y, p.z ], eulerAngles: [ e.x, e.y, e.z ] }\r\n  },\r\n\r\n  /** Frame the named node or part (or the selection). */\r\n  focus(name?: string): void {\r\n    const node = resolveKey(name ?? state.selected ?? \"\")\r\n    if (!node) return\r\n    const p = node.worldPosition\r\n    state.orbit?.focus([ p.x, p.y, p.z ])\r\n  },\r\n\r\n  /** \"Fit to mesh\": dimensions + origin that make `kind` hug what the node actually renders, as\r\n   *  plain numbers for the host to write into the file (nothing is applied here — aspects are\r\n   *  inert in edit mode, and the collider overlay redraws from the document). Null while the\r\n   *  subtree measures as nothing: an empty node, or a model still loading — the host can retry.\r\n   *\r\n   *  The measuring is `Shape.fitBounds` from the SDK, the same code `shape.fit()` runs at runtime.\r\n   *  Both inputs come from the ENGINE rather than from the node object: the node belongs to the\r\n   *  user's bundle, whose accessors the bundler may have shaken out (see the `_creator` note). */\r\n  fitShape(name: string, kind?: ShapeKindName): unknown {\r\n    const node = resolveKey(name)\r\n    const box = node ? _creator.computeBoundingBox?.(node.id) : undefined\r\n    if (!node || !box) return null\r\n    if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return null\r\n    const m = new Float32Array(16)\r\n    _creator.getWorldMatrix(node.id, m)\r\n    const scale: Vec3Tuple = [\r\n      Math.hypot(m[0], m[1], m[2]) || 1,\r\n      Math.hypot(m[4], m[5], m[6]) || 1,\r\n      Math.hypot(m[8], m[9], m[10]) || 1,\r\n    ]\r\n    const bounds = { min: [ box[0], box[1], box[2] ] as Vec3Tuple, max: [ box[3], box[4], box[5] ] as Vec3Tuple }\r\n    return Shape.fitBounds(bounds, scale, kind ?? \"box\")\r\n  },\r\n\r\n  /** Frame the named node from its subtree AABB: orbit target = world-space center, distance from\r\n   *  the extent (the host's preview captures + a future \"frame selection\"). False while the AABB is\r\n   *  degenerate — the engine answers zeros for empty/not-yet-loaded subtrees, so the host can poll\r\n   *  this as its \"model loaded\" signal — or without engine bounds support (filament). */\r\n  frameNode(name: string): boolean {\r\n    const node = resolveKey(name)\r\n    const bounds = node ? worldBounds(node) : null\r\n    if (!bounds) return false\r\n    frameBounds(bounds.min, bounds.max)\r\n    return true\r\n  },\r\n\r\n  /** Frame the whole scene — the union AABB of every top-level node (a prefab file's preview\r\n   *  capture). False while nothing has real bounds yet (same polling contract as `frameNode`). */\r\n  frameAll(): boolean {\r\n    const min: Vec3Tuple = [ Infinity, Infinity, Infinity ]\r\n    const max: Vec3Tuple = [ -Infinity, -Infinity, -Infinity ]\r\n    let any = false\r\n    for (const [ path, node ] of Object.entries(state.nodes)) {\r\n      if (path.includes(\"/\")) continue\r\n      const b = worldBounds(node)\r\n      if (!b) continue\r\n      any = true\r\n      for (let k = 0; k < 3; k++) {\r\n        if (b.min[k] < min[k]) min[k] = b.min[k]\r\n        if (b.max[k] > max[k]) max[k] = b.max[k]\r\n      }\r\n    }\r\n    if (!any) return false\r\n    frameBounds(min, max)\r\n    return true\r\n  },\r\n}\r\n\r\n;(globalThis as any).__lecodesSceneHarness = controller\r\n","math.ts":"// Pure orbit-camera math — plain number tuples in/out, no SDK dependencies, so it unit-tests\n// directly (packages/sdk/tests import it) and the harness bundle stays engine-agnostic here.\n// (The gizmo math that used to live beside it moved into the lite ENGINE's editor layer,\n// viewer-lite/src/gl/editor.ts, together with the gizmo itself.)\n\nexport type V3 = readonly [number, number, number]\n\nexport const dot = (a: V3, b: V3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]\n\n/** Yaw/pitch (radians) + radius around a target → camera position. */\nexport const orbitPosition = (target: V3, yaw: number, pitch: number, radius: number): V3 => {\n  const cp = Math.cos(pitch)\n  return [\n    target[0] + radius * cp * Math.sin(yaw),\n    target[1] + radius * Math.sin(pitch),\n    target[2] + radius * cp * Math.cos(yaw),\n  ]\n}\n\n/**\n * The camera's LOCAL screen basis at a yaw/pitch: `right` is horizontal (the orbit never rolls the\n * view) and `up` leans away from the camera as the pitch grows — both perpendicular to the view\n * direction, i.e. the plane a screen-space pan slides along (panning up must NOT climb world Y).\n */\nexport const orbitBasis = (yaw: number, pitch: number): { right: V3, up: V3 } => {\n  const sy = Math.sin(yaw), cy = Math.cos(yaw)\n  const sp = Math.sin(pitch), cp = Math.cos(pitch)\n  return { right: [ cy, 0, -sy ], up: [ -sp * sy, cp, -sp * cy ] }\n}\n","orbit.ts":"// Orbit camera controller: drag anywhere (that the gizmo didn't claim) rotates around a target;\n// zoom/pan/focus are driven by the host (wheel events belong to the DOM, which the harness never\n// touches — the Vue viewport forwards them through the controller).\n\nimport { orbitBasis, orbitPosition, type V3 } from \"./math\"\n\nconst PITCH_LIMIT = Math.PI / 2 - 0.05\n\nexport class OrbitCamera {\n  target: V3 = [ 0, 0, 0 ]\n  yaw = Math.PI / 4\n  pitch = 0.5\n  radius = 8\n\n  constructor(private readonly camera: Camera) {\n    this.apply()\n  }\n\n  apply(): void {\n    this.camera.position = orbitPosition(this.target, this.yaw, this.pitch, this.radius) as [number, number, number]\n    this.camera.lookAt([ ...this.target ])\n  }\n\n  rotate(deltaX: number, deltaY: number): void {\n    this.yaw -= deltaX * 0.008\n    this.pitch = Math.min(PITCH_LIMIT, Math.max(-PITCH_LIMIT, this.pitch + deltaY * 0.008))\n    this.apply()\n  }\n\n  /** Exponential zoom (host wheel: pass ±1-ish steps). */\n  zoom(delta: number): void {\n    this.radius = Math.min(200, Math.max(0.5, this.radius * Math.exp(delta * 0.2)))\n    this.apply()\n  }\n\n  /** Pan the target in the camera's screen plane (host drives, e.g. middle-drag). */\n  pan(deltaX: number, deltaY: number): void {\n    const k = this.radius * 0.0015\n    // Camera-LOCAL screen basis, so a vertical drag slides along the view plane (like the\n    // horizontal one already did) instead of climbing the world Y axis.\n    const { right, up } = orbitBasis(this.yaw, this.pitch)\n    this.target = [\n      this.target[0] - (right[0] * deltaX - up[0] * deltaY) * k,\n      this.target[1] - (right[1] * deltaX - up[1] * deltaY) * k,\n      this.target[2] - (right[2] * deltaX - up[2] * deltaY) * k,\n    ]\n    this.apply()\n  }\n\n  focus(point: V3, radius?: number): void {\n    this.target = point\n    if (radius !== undefined) this.radius = Math.max(0.5, radius)\n    this.apply()\n  }\n}\n"}
+{"main.ts":"// The 3D scene-editor harness — a LeCodes app the editor host runs alongside a user scene bundle\n// (compiled with the modern SDK; replaces the legacy worker-SDK scene-viewer). The host:\n//\n//   1. runs the user's scene bundle with `__lecodesSceneEdit` set → the scene handle registers on\n//      `globalThis.__lecodesScenes` (sources real, aspects inert — see sdk docs/3d/scene-files.md);\n//   2. runs this bundle → it installs `globalThis.__lecodesSceneHarness` (the controller);\n//   3. calls `controller.attach(handle)` and wires `controller.callbacks`.\n//\n// The viewport DISPLAY layer (grid, selection outline, transform gizmo, viewport picking) lives in\n// the ENGINE now — viewer-lite's editor layer (`_creator._editorConnect`), lite viewport only; the\n// filament preview renders the bare scene. This harness stays the POLICY half: the host feeds it\n// engine picks (`pickName` — locked nodes, GLB part drill-down) and completed gizmo drags\n// (`applyPose` — applied live, transform read back for the file), and `entityOf` hands the host\n// the entity id behind a selection key. Orbit is any drag; zoom/pan/focus come from the host\n// (DOM wheel/keys belong to the Vue viewport). Plugin viewport tools keep working: an active tool\n// receives clicks as raycast hits (physics bodies when the build has them, ground plane otherwise).\n\nimport { OrbitCamera } from \"./orbit\"\n\n// The low-level bridge global every bundle runs against — the harness only walks the entity\n// hierarchy with it (wrapping foreign entity ids in `new Node(id)` would OVERWRITE the real nodes\n// in the SDK's registry, so id-level walking is the safe form). `computeBoundingBox` (subtree AABB\n// in the entity's local space) is a lite-engine host API — absent on filament.\ndeclare const _creator: {\n  getParent(entityId: number): number\n  computeBoundingBox?(entityId: number): Float32Array\n  getWorldMatrix(entityId: number, mat: Float32Array): void\n  setMaterial(entityId: number, materialId: number, index: number): void\n  getMaterial(entityId: number, index: number): number\n}\n\ntype SceneHandleLike = {\n  /** `nodes` is keyed by ABSOLUTE PATH ('/'-joined def keys) — the SDK owns this record; the\n   *  harness holds the same object and must never re-key it itself (see renameNode). */\n  load(): Promise<{ scene: Scene, nodes: Record<string, Node> }>\n  /** SceneHandle._describeAspects — aspect field schemas for the inspector (plain data). */\n  _describeAspects?(): unknown[]\n  /** SceneHandle._patchNode — live single-node rebuild/add/remove; the path carries the mount\n   *  point (its parent must exist for adds). */\n  _patchNode?(path: string, def: unknown): Promise<Node | null>\n  /** SceneHandle._renameNode — re-keys the node record (subtree included) + the engine name;\n   *  returns the new path, null on refusal. */\n  _renameNode?(path: string, newName: string): string | null\n  /** SceneHandle._reparentNode — re-keys + setParent keeping the local transform. */\n  _reparentNode?(path: string, newParentPath: string | null): string | null\n  /** SceneHandle._modelParts — a model node's INTERNAL rows (the `overrides` path grammar). */\n  _modelParts?(path: string): Promise<{ path: string, name: string, depth: number, node: Node }[]>\n  /** SceneHandle._editorNodeChanged — rebuild editor-run aspects whose ref() deps cover `path`. */\n  _editorNodeChanged?(path: string): void\n  /** SceneHandle._editorGizmos — every editor run's `Gizmos` lines + a change version. */\n  _editorGizmos?(): { version: number, batches: { color: string, alpha: number, segments: number[] }[] }\n  /** SceneHandle._editorSetProp — live prop edit on one editor-run aspect (rebuilds it). */\n  _editorSetProp?(hostPath: string, index: number, key: string, value: unknown): boolean\n  /** SceneHandle._editorSetMakeArg — live arg edit on a `make()` node (re-calls the factory). */\n  _editorSetMakeArg?(path: string, key: string, value: unknown): boolean\n  /** SceneHandle._inspectorRender — run an aspect's custom `static inspector` card. */\n  _inspectorRender?(\n    hostPath: string, index: number,\n    props: Record<string, unknown>, event?: { id: string, value?: unknown },\n  ): unknown[] | null\n}\n\ntype Vec3Tuple = [number, number, number]\n/** The SDK Shape one-of, as the host names it (see fitShape / SceneHarness). */\ntype ShapeKindName = \"auto\" | \"box\" | \"sphere\" | \"cylinder\" | \"capsule\" | \"mesh\" | \"convex\"\n\ntype HarnessCallbacks = {\n  /** Selection changed from INSIDE the world (a plugin's `editor.select`) — mirror host-side. */\n  onSelect?(name: string | null): void\n}\n\n/** Document operations the HOST implements (its commit/undo/patch machinery) — the doc-op half of\n *  the `editor` API handed to plugins (windows/tools). Installed via `controller.setEditorOps`. */\ntype EditorOps = {\n  nodes(): { path: string, name: string, kind: string }[]\n  uniqueName(base: string, parentPath?: string): string\n  addNode(name: string, def: Record<string, unknown>): boolean\n  setProp(path: string, key: string, value: unknown): boolean\n  removeNode(path: string): void\n  duplicate(path: string): string | null\n  transact(fn: () => void): void\n}\n\nconst state = {\n  handle: null as SceneHandleLike | null,\n  scene: null as Scene | null,\n  /** The SDK's path-keyed node record — the SAME object the handle owns (rename/reparent re-key\n   *  it SDK-side; the harness re-keys only its own part/selection state). */\n  nodes: {} as Record<string, Node>,\n  /** Reverse map: live node → absolute def path. */\n  paths: new Map<Node, string>(),\n  /** GLB internal nodes, addressable like nodes: key = `<defPath>::<partPath>` (+ reverse map). */\n  parts: new Map<string, Node>(),\n  partNames: new Map<Node, string>(),\n  orbit: null as OrbitCamera | null,\n  /** Selection key: absolute def path or `<defPath>::<partPath>`. */\n  selected: null as string | null,\n  /** The active viewport tool (`registerEditorTool` name) — clicks route to it. */\n  activeTool: null as string | null,\n  /** Host-implemented doc operations (the `editor` API's write half). */\n  editorOps: null as EditorOps | null,\n}\n\n// ---- part keys ---------------------------------------------------------------------------------\n// A model's internal nodes are selectable/editable through PART KEYS: `<defPath>::<partPath>` (the\n// part-path grammar is the SDK's — SceneHandle._modelParts enumerates it, `overrides` keys store\n// it; names exclude ':', so the first `::` is always the boundary). Everything key-addressed\n// (select / setNodeProp / focus) resolves through `resolveKey`, so a part behaves like a node —\n// except its persistence: the editor writes the transform into the MODEL's `overrides` record.\n\nconst PART_SEP = \"::\"\n\n/** Re-key `key` after `oldPath` moved to `newPath` (the path itself, `/` descendants, and `::`\n *  part keys of either). Null = untouched. Mirrors scene-editor/types.ts `rekeyPath` — the\n *  harness compiles standalone and cannot import it. */\nconst rekeyPath = (key: string, oldPath: string, newPath: string): string | null => {\n  if (key === oldPath) return newPath\n  if (key.startsWith(oldPath + \"/\") || key.startsWith(oldPath + PART_SEP)) {\n    return newPath + key.slice(oldPath.length)\n  }\n  return null\n}\n\nconst resolveKey = (key: string): Node | null => state.nodes[key] ?? state.parts.get(key) ?? null\n\n// ---- materials ---------------------------------------------------------------------------------\n// Live material edits (docs/scene-materials-plan.md §4): a parameter lands on the LIVE material of\n// a mesh node / a GLB-part slot / a material asset with `.set()` — the value tier, no rebuild; a\n// shader or kind switch reloads ONE material. Doc defs reach the harness as plain data in which a\n// material asset is `{ $material: \"./x.material.ts\" }` — lowered here to the handle the compile's\n// virtual entry registered on `__lecodesMaterials`.\n\ntype MaterialTarget = { node: string } | { part: string, slot?: number } | { asset: string }\n\n/** The registry captured at attach — a second bundle run in the same page (the preview host)\n *  overwrites the global with ITS handles, so each harness keeps the one that was current when it\n *  attached (the host sets it right before). Falls back to the global for older hosts. */\nlet capturedMaterials: Record<string, MaterialHandle> | null = null\nconst materialHandles = (): Record<string, MaterialHandle> =>\n  capturedMaterials ?? ((globalThis as any).__lecodesMaterials as Record<string, MaterialHandle> | undefined) ?? {}\n\nconst isMaterialRef = (v: unknown): v is { $material: string } =>\n  typeof v === \"object\" && v !== null && typeof (v as { $material?: unknown }).$material === \"string\"\n\n/** A doc material def → runtime def (asset refs resolved to handles). Null = unknown asset path. */\nconst lowerMaterial = (def: unknown): unknown => (isMaterialRef(def) ? materialHandles()[def.$material] ?? null : def)\n\n/** Lower every material position of a node def (its own, part-override slots, children). Null\n *  when a reference doesn't resolve — the host falls back to a re-run. */\nconst lowerNodeDef = (def: Record<string, unknown>): Record<string, unknown> | null => {\n  const out = { ...def }\n  if (out.material !== undefined) {\n    const m = lowerMaterial(out.material)\n    if (m === null) return null\n    out.material = m\n  }\n  if (out.overrides && typeof out.overrides === \"object\") {\n    const ov: Record<string, unknown> = {}\n    for (const [ p, entry ] of Object.entries(out.overrides as Record<string, Record<string, unknown>>)) {\n      const e = { ...entry }\n      if (e.materials && typeof e.materials === \"object\") {\n        const mats: Record<string, unknown> = {}\n        for (const [ slot, m ] of Object.entries(e.materials as Record<string, unknown>)) {\n          const lowered = lowerMaterial(m)\n          if (lowered === null) return null\n          mats[slot] = lowered\n        }\n        e.materials = mats\n      }\n      ov[p] = e\n    }\n    out.overrides = ov\n  }\n  if (out.children && typeof out.children === \"object\") {\n    const ch: Record<string, unknown> = {}\n    for (const [ n, c ] of Object.entries(out.children as Record<string, Record<string, unknown>>)) {\n      const lowered = lowerNodeDef(c)\n      if (lowered === null) return null\n      ch[n] = lowered\n    }\n    out.children = ch\n  }\n  return out\n}\n\n/** The live Material behind a target (null = none assigned yet / unknown key). */\nconst materialAt = (target: MaterialTarget): Material | null => {\n  if (\"asset\" in target) return materialHandles()[target.asset]?.material ?? null\n  if (\"node\" in target) return resolveKey(target.node)?.getMaterial(0) ?? null\n  return resolveKey(target.part)?.getMaterial(target.slot ?? 0) ?? null\n}\n\n/** Push one parameter into a live material. Built-in materials take `color`/`map` through their\n *  accessors (they know the shader's uniform names); everything else is a `.set()`, where a\n *  non-`#` string is a texture URL that loads in. */\nconst pushMaterialParam = (m: Material, name: string, value: unknown): void => {\n  const builtin = (m as unknown as { _colorKey: string | null })._colorKey !== null\n  if (builtin && name === \"color\") { m.color = value as string; return }\n  if (builtin && name === \"map\") {\n    if (typeof value === \"string\") void Texture.load(value).then((t) => { m.map = t })\n    else m.map = null\n    return\n  }\n  void __applyMaterialParam(m, name, value as never)\n}\n\n/** The original (glTF) material of every part slot overridden live, so clearing restores it. */\nconst originalSlotMaterials = new Map<string, number>()\n\n/** (Re-)enumerate one model's internal nodes into the part maps; returns plain rows for the host. */\nconst refreshModelParts = async (path: string): Promise<{ path: string, name: string, depth: number }[]> => {\n  const handle = state.handle\n  if (!handle?._modelParts) return []\n  const rows = await handle._modelParts(path)\n  for (const [ key, node ] of [ ...state.parts ]) {\n    if (key.startsWith(path + PART_SEP)) { state.parts.delete(key); state.partNames.delete(node) }\n  }\n  for (const r of rows) {\n    const key = path + PART_SEP + r.path\n    state.parts.set(key, r.node)\n    state.partNames.set(r.node, key)\n  }\n  return rows.map((r) => ({ path: r.path, name: r.name, depth: r.depth }))\n}\n\n/** Editor-tool gizmo lines (a tool's hooks draw through `Gizmos` too) — one buffer for the active\n *  tool, cleared on every hook call and on tool switch. */\nconst toolGizmos = new __GizmoBuffer()\nlet toolGizmosVersion = 0\n\n/** A node (or a part inside a model) changed — let the scene's editor-run aspects (generators)\n *  that reference it via ref() rebuild. Part keys collapse to their model's def path. */\nconst notifyEditorChanged = (key: string | null): void => {\n  if (!key) return\n  const i = key.indexOf(PART_SEP)\n  state.handle?._editorNodeChanged?.(i < 0 ? key : key.slice(0, i))\n}\n\n/** After the SDK re-keyed the shared node record (rename/reparent), re-key the HARNESS-owned\n *  state that mirrors those paths: the reverse map, part keys, node-card cache, selection. */\nconst rekeyLocal = (oldPath: string, newPath: string): void => {\n  state.paths = new Map(Object.entries(state.nodes).map(([ p, n ]) => [ n, p ]))\n  for (const [ key, part ] of [ ...state.parts ]) {\n    const next = rekeyPath(key, oldPath, newPath)\n    if (next === null) continue\n    state.parts.delete(key)\n    state.parts.set(next, part)\n    state.partNames.set(part, next)\n  }\n  for (const [ key, ui ] of [ ...nodeCards ]) {\n    const next = rekeyPath(key, oldPath, newPath)\n    if (next === null) continue\n    nodeCards.delete(key)\n    nodeCards.set(next, ui)\n  }\n  if (state.selected) state.selected = rekeyPath(state.selected, oldPath, newPath) ?? state.selected\n}\n\nconst isEditorNode = (node: Node): boolean => (node.name ?? \"\").startsWith(\"__editor\")\n\n// ---- built-in node cards (immediate-mode inspector protocol — sdk core/InspectorUI.ts) ----------\n// The ANIMATION card on model nodes with baked clips: clip dropdown (live from model.anim.clips),\n// speed/loop, Play/Stop preview. Pure editor state — nothing here writes to the scene file\n// (it's a preview; play-mode behavior belongs in aspects/code). ModelAnimation is attached by the\n// Model constructor itself, so it is live even in edit mode.\n\nconst nodeCards = new Map<string, InspectorUI>()\n\nconst renderNodeCard = (name: string, event?: { id: string, value?: unknown }): unknown[] | null => {\n  const node = state.nodes[name]\n  if (!(node instanceof Model)) return null\n  const clips = node.anim.clips\n  if (clips.length === 0) return null\n  let ui = nodeCards.get(name)\n  if (!ui) { ui = new InspectorUI(); nodeCards.set(name, ui) }\n  return ui._run((u) => {\n    u.header(\"Animation\")\n    const clip = String(u.select(\"clip\", clips.map((c) => c.name)))\n    const speed = u.number(\"speed\", { min: 0.1, max: 4, step: 0.1, value: 1 })\n    const loop = u.switch(\"loop\", { value: true })\n    const playing = node.anim.busy || node.anim.loop !== undefined\n    if (playing) node.anim.speed = speed\n    if (u.button(playing ? \"Restart\" : \"Play\")) {\n      node.anim.speed = speed\n      if (loop) node.anim.playLoop(clip)\n      else node.anim.play(clip, { restart: true })\n    }\n    if (u.button(\"Stop\")) node.anim.stop()   // fades to the rest pose\n    const duration = clips.find((c) => c.name === clip)?.duration\n    u.info(playing ? \"playing…\" : duration !== undefined ? `${duration.toFixed(2)}s` : \"\")\n  }, event)\n}\n\n/** The def path a raycast-hit entity belongs to (a GLB hit resolves to its Model, etc.). */\nconst ownerPath = (node: Node | null): string | null => {\n  let cur: Node | null = node\n  for (let i = 0; cur && i < 32; i++) {\n    const path = state.paths.get(cur)\n    if (path) return path\n    cur = cur.parent\n  }\n  return null\n}\n\nconst applySelection = (name: string | null, notify: boolean): void => {\n  state.selected = name\n  if (notify) controller.callbacks.onSelect?.(name)\n}\n\n// ---- editor plugins (windows + viewport tools — sdk scene/editorPlugins.ts) ---------------------\n// `*.editor.ts` files register into the injected `__editorPlugins` registry (same bundle → same\n// module instance). Windows render through the immediate-mode InspectorUI protocol like inspector\n// cards; tools receive viewport clicks as raycast hits. Both get the `editor` scripting API:\n// selection/raycast are answered here, doc writes delegate to the host's EditorOps (plugins write\n// the DOCUMENT, never live state — one undo stack for humans and plugins alike).\n\nconst isInSubtree = (node: Node, root: Node): boolean => {\n  let cur: Node | null = node\n  for (let i = 0; cur && i < 64; i++) {\n    if (cur === root) return true\n    cur = cur.parent\n  }\n  return false\n}\n\n/** Raycast under a viewport pixel: precise mesh hit via Jolt bodies when the build/scene has any\n *  (edit mode attaches none itself — aspects are inert), else / on miss the ground plane.\n *  `exclude` steps the ray past any hit inside that subtree (editor nodes are always stepped). */\nconst raycastViewport = (x: number, y: number, exclude?: Node | null): { point: Vec3Tuple, normal: Vec3Tuple, node: string | null } | null => {\n  const scene = state.scene\n  if (!scene) return null\n  const ray = scene.camera.getRay(x, y)\n  if (Physics.supported) {\n    let origin: Vec3Tuple = [ ray.origin.x, ray.origin.y, ray.origin.z ]\n    let remaining = 2000\n    for (let i = 0; i < 8 && remaining > 0; i++) {\n      const hit = Physics.raycast(origin, ray.dir, remaining)\n      if (!hit) break\n      // (empties/cameras have no geometry — their markers are overlay gizmos, never hit here)\n      if (hit.node && !isEditorNode(hit.node)\n          && !(exclude && isInSubtree(hit.node, exclude))) {\n        return {\n          point: [ hit.point.x, hit.point.y, hit.point.z ],\n          normal: [ hit.normal.x, hit.normal.y, hit.normal.z ],\n          node: hit.node ? ownerPath(hit.node) : null,\n        }\n      }\n      // an excluded/editor body — resume the cast just past it\n      const step = remaining * hit.fraction + 0.01\n      origin = [ origin[0] + ray.dir.x * step, origin[1] + ray.dir.y * step, origin[2] + ray.dir.z * step ]\n      remaining -= step\n    }\n  }\n  const t = -ray.origin.y / ray.dir.y\n  if (!Number.isFinite(t) || t <= 0) return null\n  const p = ray.getPoint(t)\n  return { point: [ p.x, p.y, p.z ], normal: [ 0, 1, 0 ], node: null }\n}\n\nconst editorApi = {\n  get selection(): string | null { return state.selected },\n  select(name: string | null): void { applySelection(name && resolveKey(name) ? name : null, true) },\n  nodes: (): { name: string, kind: string }[] => state.editorOps?.nodes() ?? [],\n  uniqueName: (base: string): string => state.editorOps?.uniqueName(base) ?? base,\n  addNode: (name: string, def: Record<string, unknown>): boolean => state.editorOps?.addNode(name, def) === true,\n  setProp: (name: string, key: string, value: unknown): boolean => state.editorOps?.setProp(name, key, value) === true,\n  removeNode: (name: string): void => { state.editorOps?.removeNode(name) },\n  duplicate: (name: string): string | null => state.editorOps?.duplicate(name) ?? null,\n  raycast: raycastViewport,\n  transact: (fn: () => void): void => { state.editorOps ? state.editorOps.transact(fn) : fn() },\n}\n\n/** Per-window InspectorUI instances (all their field keys are transient editor state). */\nconst windowUIs = new Map<number, InspectorUI>()\n\n/** A node's subtree AABB in WORLD space (the engine's local box through the node's own world\n *  matrix), null while degenerate / unsupported. */\nconst worldBounds = (node: Node): { min: Vec3Tuple, max: Vec3Tuple } | null => {\n  const box = _creator.computeBoundingBox?.(node.id)\n  if (!box) return null\n  if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return null\n  // world AABB from the 8 local-space corners (the local box doesn't include the node's own\n  // transform — worldMatrix carries it)\n  const m = node.worldMatrix\n  const min: Vec3Tuple = [ Infinity, Infinity, Infinity ]\n  const max: Vec3Tuple = [ -Infinity, -Infinity, -Infinity ]\n  for (let i = 0; i < 8; i++) {\n    const p = m.transformPoint([ box[i & 1 ? 3 : 0], box[i & 2 ? 4 : 1], box[i & 4 ? 5 : 2] ])\n    const c = [ p.x, p.y, p.z ]\n    for (let k = 0; k < 3; k++) {\n      if (c[k] < min[k]) min[k] = c[k]\n      if (c[k] > max[k]) max[k] = c[k]\n    }\n  }\n  return { min, max }\n}\n\n/** Orbit onto a world AABB: target = center, distance from the largest extent. */\nconst frameBounds = (min: Vec3Tuple, max: Vec3Tuple) => {\n  const size = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2])\n  state.orbit?.focus(\n    [ (min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2 ],\n    Math.max(1, size * 1.4),\n  )\n}\n\nconst controller = {\n  callbacks: {} as HarnessCallbacks,\n\n  /** Attach to a user scene handle (from `globalThis.__lecodesScenes`). Returns the node PATHS\n   *  (build-completion order, not file order — the host sorts for display). */\n  async attach(handle: SceneHandleLike): Promise<{ nodes: string[] }> {\n    // synchronously, before any await: the host sets the registry for THIS world right around\n    // the call (a second bundle run in the page — the preview host — writes the same global)\n    capturedMaterials = ((globalThis as any).__lecodesMaterials as Record<string, MaterialHandle> | undefined) ?? null\n    const { scene, nodes } = await handle.load()\n    state.handle = handle\n    state.scene = scene\n    state.nodes = nodes\n    state.paths = new Map(Object.entries(nodes).map(([ path, node ]) => [ node, path ]))\n\n    scene.open()\n\n    state.orbit = new OrbitCamera(scene.camera)\n\n    // any drag orbits (nothing else claims viewport touches — no pick colliders in the world)\n    scene.addEventListener(\"touchstart\", (ev) => {\n      ev.track({ onMove: (pos) => state.orbit?.rotate(pos.deltaX, pos.deltaY) })\n    })\n\n    // an active plugin tool owns viewport clicks — they arrive as raycast hits (selection itself\n    // is host-driven from the tree, so a click outside a tool does nothing)\n    scene.addEventListener(\"click\", (ev) => {\n      if (!state.activeTool) return\n      const tool = __editorPlugins.tools.find((t) => t.name === state.activeTool)\n      if (!tool?.hooks.onViewportClick) return\n      const hit = raycastViewport(ev.clientX, ev.clientY)\n      if (hit) {\n        // a throwing tool logs and skips — it can't take the editor down; Gizmos calls inside\n        // the hook land in the tool's own buffer (cleared per call)\n        try { toolGizmosVersion++; __withGizmoScope(toolGizmos, () => tool.hooks.onViewportClick!(hit, editorApi)) }\n        catch (e) { console.error(\"[scene-editor] tool click failed:\", e) }\n      }\n    })\n\n    // GLB internal hierarchies are part of the editable scene — enumerate them up front so part\n    // keys resolve before the host asks for the rows\n    await Promise.all(Object.keys(nodes).map((name) => refreshModelParts(name)))\n\n    return { nodes: Object.keys(nodes) }\n  },\n\n  /** Host-driven selection (tree click). Accepts node names AND part keys. Does not echo onSelect. */\n  select(name: string | null): void {\n    applySelection(name && resolveKey(name) ? name : null, false)\n  },\n\n  /** The entity id behind a selection key (node name or GLB part key); 0 = unknown. The host\n   *  feeds it to the engine's editor layer (selection outline + gizmo target). */\n  entityOf(name: string): number {\n    return resolveKey(name)?.id ?? 0\n  },\n\n  /** Resolve an ENGINE pick (raw entity id) to a selection key — the policy half of viewport\n   *  picking. Walks the hit entity up to the NEAREST tracked def node (its absolute path — with\n   *  nested def nodes the deepest one wins); a hit inside the CURRENTLY SELECTED model resolves\n   *  to its deepest part key instead (click-again drill-down). Locked nodes yield null (the\n   *  click selects nothing — the host keeps the current selection). */\n  pickName(entityId: number): string | null {\n    if (!entityId) return null\n    const nodeIds = new Map<number, string>()\n    for (const [ path, node ] of Object.entries(state.nodes)) nodeIds.set(node.id, path)\n    const partIds = new Map<number, string>()\n    for (const [ key, node ] of state.parts) partIds.set(node.id, key)\n    let part: string | null = null\n    for (let id = entityId, i = 0; id !== 0 && i < 64; i++) {\n      part ??= partIds.get(id) ?? null   // the deepest enumerated part containing the hit\n      const path = nodeIds.get(id)\n      if (path !== undefined) {\n        const node = state.nodes[path]\n        if (node && (node as { _sceneLocked?: boolean })._sceneLocked) return null\n        const inSelected = state.selected === path || state.selected?.startsWith(path + PART_SEP)\n        return part && inSelected ? part : path\n      }\n      id = _creator.getParent(id)\n    }\n    return null\n  },\n\n  /** The selection key an entity belongs to — its deepest enumerated GLB part, else the owning\n   *  def node's path — with no lock / drill-down policy (drop targets: a material tile lands on\n   *  whatever is under the cursor). Null for editor-only / untracked entities. */\n  hitKey(entityId: number): string | null {\n    if (!entityId) return null\n    const nodeIds = new Map<number, string>()\n    for (const [ path, node ] of Object.entries(state.nodes)) nodeIds.set(node.id, path)\n    const partIds = new Map<number, string>()\n    for (const [ key, node ] of state.parts) partIds.set(node.id, key)\n    let part: string | null = null\n    for (let id = entityId, i = 0; id !== 0 && i < 64; i++) {\n      part ??= partIds.get(id) ?? null\n      const path = nodeIds.get(id)\n      if (path !== undefined) return part ?? path\n      id = _creator.getParent(id)\n    }\n    return null\n  },\n\n  /** Apply a completed gizmo drag: set the node's (or part's) local transform from the engine's\n   *  decomposed pose, then return position/eulerAngles/scale read BACK from the engine — exactly\n   *  the values the host should persist (same read-back rule as setFromView: never compose eulers\n   *  by hand, the engines' setter conventions differ). */\n  applyPose(\n    name: string,\n    pose: { position: Vec3Tuple, quaternion: [number, number, number, number], scale: Vec3Tuple },\n  ): { position: Vec3Tuple, eulerAngles: Vec3Tuple, scale: Vec3Tuple } | null {\n    const node = resolveKey(name)\n    if (!node) return null\n    node.position = pose.position\n    node.quaternion = pose.quaternion\n    node.scale = pose.scale\n    notifyEditorChanged(name)\n    const p = node.position, e = node.eulerAngles, s = node.scale\n    return {\n      position: [ p.x, p.y, p.z ],\n      eulerAngles: [ e.x, e.y, e.z ],\n      scale: [ s.x, s.y, s.z ],\n    }\n  },\n\n  /** A model node's internal GLB rows (path/name/depth) — the tree's expandable part list. Also\n   *  (re-)binds the part keys, so call it after anything that reloads the model. */\n  modelParts(name: string): Promise<{ path: string, name: string, depth: number }[]> {\n    return refreshModelParts(name)\n  },\n\n  /** The camera PREVIEW source for a node carrying a `CameraPlace` (edit mode registers the\n   *  generator instance on the node): its entity + lens. Null when the node is unknown or has no\n   *  place. (`hide` stays for older engine builds — markers are overlay gizmos now, not scene\n   *  entities, and the inset skips overlay roots by itself.) */\n  cameraPreview(name: string): { entityId: number, fov: number, near: number, far: number, hide: number[] } | null {\n    const node = resolveKey(name)\n    if (!node) return null\n    const place = (node as Node & { cameraPlace?: { fov: number, near: number, far: number } }).cameraPlace\n      ?? (node.get(CameraPlace) as { fov: number, near: number, far: number } | undefined)\n    if (!place) return null\n    return { entityId: node.id, fov: place.fov, near: place.near, far: place.far, hide: [] }\n  },\n\n  /** Clip names of a loaded model node (the inspector's preview-pose dropdown); [] otherwise. */\n  modelClips(name: string): string[] {\n    const node = resolveKey(name) as (Node & { anim?: { clips: readonly { name: string }[] } }) | null\n    return node?.anim ? node.anim.clips.map((c) => c.name) : []\n  },\n\n  /** Current live transform of a node OR part (part inspectors have no doc def to read from). */\n  getNodeProps(name: string): { position: Vec3Tuple, eulerAngles: Vec3Tuple, scale: Vec3Tuple, visible: boolean } | null {\n    const node = resolveKey(name)\n    if (!node) return null\n    const p = node.position, e = node.eulerAngles, s = node.scale\n    return {\n      position: [ p.x, p.y, p.z ],\n      eulerAngles: [ e.x, e.y, e.z ],\n      scale: [ s.x, s.y, s.z ],\n      visible: !!node.visible,   // native bridges answer 0/1 — normalize for the inspector\n    }\n  },\n\n  /** Apply an inspector value edit to the live node or GLB part. Transform/visibility/locked only —\n   *  anything else is a structural change (the host recompiles the scene bundle instead). */\n  setNodeProp(name: string, key: \"position\" | \"eulerAngles\" | \"scale\" | \"visible\" | \"locked\" | \"editor\", value: unknown): void {\n    const node = resolveKey(name)\n    if (!node) return\n    if (key === \"editor\") {\n      // the preview pose (`editor: { clip, time }`) — edit-mode only, never a runtime default\n      __applyEditorPose(node, (value ?? undefined) as { clip?: string, time?: number } | undefined)\n      return\n    }\n    if (key === \"position\") node.position = value as Vec3Tuple\n    else if (key === \"eulerAngles\") node.eulerAngles = value as Vec3Tuple\n    else if (key === \"scale\") node.scale = (typeof value === \"number\" ? value : value as Vec3Tuple) as any\n    else if (key === \"visible\") node.visible = value === true\n    else if (key === \"locked\") {\n      // an editor-only flag kept on the live node (the coming selection/manipulation layer\n      // consults it; fields edit regardless)\n      ;(node as { _sceneLocked?: boolean })._sceneLocked = value === true\n      return\n    }\n    notifyEditorChanged(name)\n  },\n\n  /** Live prop edit on an editor-run aspect (generator): update the instance + rebuild. False =\n   *  that entry isn't editor-run (inert doc data) or the bundle predates generators. */\n  updateEditorAspect(name: string, index: number, key: string, value: unknown): boolean {\n    return state.handle?._editorSetProp?.(name, index, key, value) === true\n  },\n\n  /** Every editor gizmo line currently drawn (generator rebuilds + the active tool) as world-space\n   *  LINES batches, with a version that changes whenever any of them re-ran — the host pushes to\n   *  the engine overlay only when it moves. Empty on bundles predating gizmos. */\n  gizmos(): { version: number, batches: { color: string, alpha: number, segments: number[] }[] } {\n    const runs = state.handle?._editorGizmos?.() ?? { version: 0, batches: [] }\n    const batches = runs.batches.slice()\n    for (const b of toolGizmos.batches) if (b.segments.length > 0) batches.push(b)\n    return { version: runs.version * 1000003 + toolGizmosVersion, batches }\n  },\n\n  /** Live arg edit on a `make()` node: re-calls the factory through the tracked run — no compile\n   *  (the factory is already in the bundle). False = not a make node / older SDK. */\n  setMakeArg(name: string, key: string, value: unknown): boolean {\n    return state.handle?._editorSetMakeArg?.(name, key, value) === true\n  },\n\n  /** Custom inspector cards (immediate-mode widget lists — sdk core/InspectorUI.ts). An aspect\n   *  target runs the class's `static inspector` through the scene handle (`opts.props` = the\n   *  entry's CURRENT doc props, passed on every call; `opts.event` = buttons/state edits only);\n   *  a bare node name renders the built-in node card (the ANIMATION card on models with clips).\n   *  Null = no card — the host falls back to plain fields. */\n  inspector(\n    target: { name: string, aspect?: number },\n    opts?: { props?: Record<string, unknown>, event?: { id: string, value?: unknown } },\n  ): unknown[] | null {\n    if (typeof target.aspect === \"number\") {\n      return state.handle?._inspectorRender?.(target.name, target.aspect, opts?.props ?? {}, opts?.event) ?? null\n    }\n    return renderNodeCard(target.name, opts?.event)\n  },\n\n  /** Live parameter write on a mesh node's material, a GLB part's slot material, or a material\n   *  asset (every user follows). `value` is plain: number / bool / `#colour` / texture URL /\n   *  vector; null clears a texture. False = no live material there (the host re-runs/patches). */\n  setMaterialParam(target: MaterialTarget, name: string, value: unknown): boolean {\n    if (\"asset\" in target) {\n      const h = materialHandles()[target.asset]\n      if (!h) return false\n      h.setParam(name, value as never)\n      return true\n    }\n    const m = materialAt(target)\n    if (!m) return false\n    pushMaterialParam(m, name, value)\n    return true\n  },\n\n  /** Replace a material asset's whole definition (a shader / kind switch): the shared instance\n   *  rebuilds and re-assigns to every node using it. False = unknown asset. */\n  async patchMaterial(assetPath: string, def: Record<string, unknown>): Promise<boolean> {\n    const h = materialHandles()[assetPath]\n    if (!h) return false\n    await h.reset(def as never)\n    return true\n  },\n\n  /** Assign (def) or clear (null) the material of one GLB-part slot live. Clearing restores the\n   *  glTF material captured on the first live override; a slot never overridden live has nothing\n   *  to restore → false (the host re-runs, which rebuilds the model from its def). */\n  async setPartMaterial(partKey: string, slot: number, def: Record<string, unknown> | null): Promise<boolean> {\n    const node = resolveKey(partKey)\n    if (!node) return false\n    const key = `${partKey}#${slot}`\n    if (def === null) {\n      const orig = originalSlotMaterials.get(key)\n      if (orig === undefined) return false\n      _creator.setMaterial(node.id, orig, slot)\n      const cache = (node as unknown as { _materials?: (Material | undefined)[] })._materials\n      if (cache) cache[slot] = undefined\n      return true\n    }\n    const lowered = lowerMaterial(def)\n    if (lowered === null) return false\n    if (!originalSlotMaterials.has(key)) originalSlotMaterials.set(key, _creator.getMaterial(node.id, slot))\n    await __assignMaterialDef(node, slot, lowered as never)\n    return true\n  },\n\n  /** Live structural patch: rebuild / add (`def`) or remove (`def === null`) ONE node at `path`\n   *  from plain def data — the SDK re-instantiates it through the same defineScene builder, so\n   *  nothing recompiles. The path carries the mount point. The HOST guarantees the def is plain\n   *  data (it bails to a re-run on `$expr` and `$asset` values). False = the SDK can't patch. */\n  async patchNode(path: string, def: Record<string, unknown> | null): Promise<boolean> {\n    const handle = state.handle\n    if (!handle?._patchNode) return false\n    // material asset refs → registered handles (an unknown one means the bundle predates the\n    // asset — only a compile picks it up)\n    const lowered = def === null ? null : lowerNodeDef(def)\n    if (def !== null && lowered === null) return false\n    const node = await handle._patchNode(path, lowered)\n    state.paths = new Map(Object.entries(state.nodes).map(([ p, nd ]) => [ nd, p ]))\n    notifyEditorChanged(path)   // generators referencing the patched node follow it\n    // the node object was replaced/removed — its part bindings (if it was a model) went with it\n    await refreshModelParts(path)\n    const sel = state.selected\n    if (sel === path || sel?.startsWith(path + \"/\") || sel?.startsWith(path + PART_SEP)) {\n      const alive = sel === path ? node : (sel ? resolveKey(sel) : null)\n      if (!alive) state.selected = null\n    }\n    return true\n  },\n\n  /** Live rename (bare sibling segment). The SDK owns the shared node record and re-keys it —\n   *  subtree, editor runs, and the engine-side display name included; the harness re-keys only\n   *  its OWN state (reverse path map, part keys, node-card cache, selection). The document is\n   *  the source of truth. */\n  renameNode(path: string, newName: string): boolean {\n    const newPath = state.handle?._renameNode?.(path, newName) ?? null\n    if (newPath === null) return false\n    rekeyLocal(path, newPath)\n    return true\n  },\n\n  /** Live reparent keeping the LOCAL transform — the same semantics the scene file describes\n   *  (a node under a transformed parent shifts in world space). `newParentPath` null = root.\n   *  The node's (and its subtree's) PATHS change with the move — same re-key story as rename. */\n  reparentNode(path: string, newParentPath: string | null): boolean {\n    const newPath = state.handle?._reparentNode?.(path, newParentPath) ?? null\n    if (newPath === null) return false\n    rekeyLocal(path, newPath)\n    return true\n  },\n\n  /** Live scene-level tweak. Only `skybox` is applicable post-creation for now — the host falls\n   *  back to a re-run for everything else. */\n  setSceneProp(key: string, value: unknown): boolean {\n    if (key === \"skybox\" && state.scene && typeof value === \"string\") {\n      state.scene.skybox = value\n      return true\n    }\n    return false\n  },\n\n  zoom(delta: number): void { state.orbit?.zoom(delta) },\n  pan(deltaX: number, deltaY: number): void { state.orbit?.pan(deltaX, deltaY) },\n\n  /** Raycast under a viewport pixel (physics bodies when present, ground-plane fallback) — the\n   *  host's drop-to-place path; same hit shape the plugin `editor.raycast` answers. */\n  raycast(x: number, y: number): { point: Vec3Tuple, normal: Vec3Tuple, node: string | null } | null {\n    return raycastViewport(x, y)\n  },\n\n  /** Aspect field schemas (AspectClassInfo[]) for every aspect class the scene references — the\n   *  inspector's editors. Computed in-bundle because only the bundle holds the ctors. */\n  aspectSchemas(): unknown[] {\n    return state.handle?._describeAspects?.() ?? []\n  },\n\n  /** Registered editor windows (`registerEditorWindow` in `*.editor.ts` files), display order. */\n  editorWindows(): { title: string }[] {\n    return __editorPlugins.windows.map((w) => ({ title: w.title }))\n  },\n\n  /** One immediate-mode pass of a registered window — same widget-list protocol as inspector\n   *  cards, except every field key is transient editor state (windows have no doc entry). */\n  renderWindow(index: number, event?: { id: string, value?: unknown }): unknown[] | null {\n    const win = __editorPlugins.windows[index]\n    if (!win) return null\n    let ui = windowUIs.get(index)\n    if (!ui) { ui = new InspectorUI(); windowUIs.set(index, ui) }\n    return ui._run((u) => win.render(u, editorApi), event)\n  },\n\n  /** Registered viewport tools (`registerEditorTool`) — the host's extra toolbar entries. */\n  editorTools(): { name: string, cursor?: string, icon?: string }[] {\n    return __editorPlugins.tools.map((t) => ({ name: t.name, cursor: t.hooks.cursor, icon: t.hooks.icon }))\n  },\n\n  /** Activate a plugin tool (null = deactivate). While active, viewport clicks route to the\n   *  tool's hooks; selection itself is unaffected. */\n  setActiveTool(name: string | null): void {\n    state.activeTool = name && __editorPlugins.tools.some((t) => t.name === name) ? name : null\n    toolGizmos.clear()\n    toolGizmosVersion++\n  },\n\n  /** Install the host's document operations — the write half of the plugin `editor` API. */\n  setEditorOps(ops: EditorOps): void {\n    state.editorOps = ops\n  },\n\n  /** Introspection for driving the editor headlessly (CDP/tests): selection + tool state, plus a\n   *  live euler-semantics probe against the running engine (the setter convention differs across\n   *  shipped engines — see setFromView). */\n  _debug(): unknown {\n    const probe = new Node()\n    probe.eulerAngles = [ 0, 0, 90 ]\n    const y = probe.quaternion.rotateVec3([ 0, 1, 0 ])\n    const probe2 = new Node()\n    probe2.quaternion = Quat.fromAxisAngle([ 0, 0, 1 ], Math.PI / 2)\n    const y2 = probe2.quaternion.rotateVec3([ 0, 1, 0 ])\n    // world poses of every def node + any node named in `names` under them — a numeric probe\n    const poses: Record<string, number[]> = {}\n    const visit = (n: Node, key: string, depth: number): void => {\n      const m = n.worldMatrix\n      const pos = m.position, z = m.basisZ, y = m.basisY\n      poses[key] = [ pos.x, pos.y, pos.z, z.x, z.y, z.z, y.x, y.y, y.z ].map((v) => Math.round(v * 1000) / 1000)\n      if (depth > 6) return\n      for (const c of n.children) if (c.name && !isEditorNode(c)) visit(c, `${key}/${c.name}`, depth + 1)\n    }\n    for (const [ path, n ] of Object.entries(state.nodes)) if (!path.includes(\"/\")) visit(n, path, 0)\n    return {\n      poses,\n      selected: state.selected,   // def PATH (\"city/in1/pt1\") OR `<defPath>::<partPath>` part key\n      activeTool: state.activeTool,\n      eulerZ90MapsYTo: [ y.x, y.y, y.z ],\n      quatZ90MapsYTo: [ y2.x, y2.y, y2.z ],   // standard/faithful: (−1, 0, 0)\n    }\n  },\n\n  /** Pose the named node from the CURRENT editor viewpoint (the camera node's \"Set from view\"):\n   *  applies the live camera's world pose to the node quaternion-faithfully, then returns the\n   *  parent-local position/eulerAngles read BACK from the engine — exactly the values the host\n   *  should write to the file (never compose eulers by hand: the shipped engines apply the\n   *  eulerAngles setter with differing conventions, so only an engine read-back round-trips). */\n  setFromView(name: string): { position: Vec3Tuple, eulerAngles: Vec3Tuple } | null {\n    const node = resolveKey(name)\n    const cam = state.scene?.camera\n    if (!node || !cam) return null\n    const parent = node.parent\n    const camPos = cam.worldPosition\n    node.quaternion = parent\n      ? parent.worldQuaternion.invert().mul(cam.worldQuaternion)\n      : cam.worldQuaternion\n    node.position = parent ? parent.worldMatrix.invert().transformPoint(camPos) : camPos\n    notifyEditorChanged(name)\n    const p = node.position, e = node.eulerAngles\n    return { position: [ p.x, p.y, p.z ], eulerAngles: [ e.x, e.y, e.z ] }\n  },\n\n  /** Frame the named node or part (or the selection). */\n  focus(name?: string): void {\n    const node = resolveKey(name ?? state.selected ?? \"\")\n    if (!node) return\n    const p = node.worldPosition\n    state.orbit?.focus([ p.x, p.y, p.z ])\n  },\n\n  /** \"Fit to mesh\": dimensions + origin that make `kind` hug what the node actually renders, as\n   *  plain numbers for the host to write into the file (nothing is applied here — aspects are\n   *  inert in edit mode, and the collider overlay redraws from the document). Null while the\n   *  subtree measures as nothing: an empty node, or a model still loading — the host can retry.\n   *\n   *  The measuring is `Shape.fitBounds` from the SDK, the same code `shape.fit()` runs at runtime.\n   *  Both inputs come from the ENGINE rather than from the node object: the node belongs to the\n   *  user's bundle, whose accessors the bundler may have shaken out (see the `_creator` note). */\n  fitShape(name: string, kind?: ShapeKindName): unknown {\n    const node = resolveKey(name)\n    const box = node ? _creator.computeBoundingBox?.(node.id) : undefined\n    if (!node || !box) return null\n    if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return null\n    const m = new Float32Array(16)\n    _creator.getWorldMatrix(node.id, m)\n    const scale: Vec3Tuple = [\n      Math.hypot(m[0], m[1], m[2]) || 1,\n      Math.hypot(m[4], m[5], m[6]) || 1,\n      Math.hypot(m[8], m[9], m[10]) || 1,\n    ]\n    const bounds = { min: [ box[0], box[1], box[2] ] as Vec3Tuple, max: [ box[3], box[4], box[5] ] as Vec3Tuple }\n    return Shape.fitBounds(bounds, scale, kind ?? \"box\")\n  },\n\n  /** Frame the named node from its subtree AABB: orbit target = world-space center, distance from\n   *  the extent (the host's preview captures + a future \"frame selection\"). False while the AABB is\n   *  degenerate — the engine answers zeros for empty/not-yet-loaded subtrees, so the host can poll\n   *  this as its \"model loaded\" signal — or without engine bounds support (filament). */\n  frameNode(name: string): boolean {\n    const node = resolveKey(name)\n    const bounds = node ? worldBounds(node) : null\n    if (!bounds) return false\n    frameBounds(bounds.min, bounds.max)\n    return true\n  },\n\n  /** Frame the whole scene — the union AABB of every top-level node (a prefab file's preview\n   *  capture). False while nothing has real bounds yet (same polling contract as `frameNode`). */\n  frameAll(): boolean {\n    const min: Vec3Tuple = [ Infinity, Infinity, Infinity ]\n    const max: Vec3Tuple = [ -Infinity, -Infinity, -Infinity ]\n    let any = false\n    for (const [ path, node ] of Object.entries(state.nodes)) {\n      if (path.includes(\"/\")) continue\n      const b = worldBounds(node)\n      if (!b) continue\n      any = true\n      for (let k = 0; k < 3; k++) {\n        if (b.min[k] < min[k]) min[k] = b.min[k]\n        if (b.max[k] > max[k]) max[k] = b.max[k]\n      }\n    }\n    if (!any) return false\n    frameBounds(min, max)\n    return true\n  },\n}\n\n;(globalThis as any).__lecodesSceneHarness = controller\n","math.ts":"// Pure orbit-camera math — plain number tuples in/out, no SDK dependencies, so it unit-tests\n// directly (packages/sdk/tests import it) and the harness bundle stays engine-agnostic here.\n// (The gizmo math that used to live beside it moved into the lite ENGINE's editor layer,\n// viewer-lite/src/gl/editor.ts, together with the gizmo itself.)\n\nexport type V3 = readonly [number, number, number]\n\nexport const dot = (a: V3, b: V3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]\n\n/** Yaw/pitch (radians) + radius around a target → camera position. */\nexport const orbitPosition = (target: V3, yaw: number, pitch: number, radius: number): V3 => {\n  const cp = Math.cos(pitch)\n  return [\n    target[0] + radius * cp * Math.sin(yaw),\n    target[1] + radius * Math.sin(pitch),\n    target[2] + radius * cp * Math.cos(yaw),\n  ]\n}\n\n/**\n * The camera's LOCAL screen basis at a yaw/pitch: `right` is horizontal (the orbit never rolls the\n * view) and `up` leans away from the camera as the pitch grows — both perpendicular to the view\n * direction, i.e. the plane a screen-space pan slides along (panning up must NOT climb world Y).\n */\nexport const orbitBasis = (yaw: number, pitch: number): { right: V3, up: V3 } => {\n  const sy = Math.sin(yaw), cy = Math.cos(yaw)\n  const sp = Math.sin(pitch), cp = Math.cos(pitch)\n  return { right: [ cy, 0, -sy ], up: [ -sp * sy, cp, -sp * cy ] }\n}\n","orbit.ts":"// Orbit camera controller: drag anywhere (that the gizmo didn't claim) rotates around a target;\n// zoom/pan/focus are driven by the host (wheel events belong to the DOM, which the harness never\n// touches — the Vue viewport forwards them through the controller).\n\nimport { orbitBasis, orbitPosition, type V3 } from \"./math\"\n\nconst PITCH_LIMIT = Math.PI / 2 - 0.05\n\nexport class OrbitCamera {\n  target: V3 = [ 0, 0, 0 ]\n  yaw = Math.PI / 4\n  pitch = 0.5\n  radius = 8\n\n  constructor(private readonly camera: Camera) {\n    this.apply()\n  }\n\n  apply(): void {\n    this.camera.position = orbitPosition(this.target, this.yaw, this.pitch, this.radius) as [number, number, number]\n    this.camera.lookAt([ ...this.target ])\n  }\n\n  rotate(deltaX: number, deltaY: number): void {\n    this.yaw -= deltaX * 0.008\n    this.pitch = Math.min(PITCH_LIMIT, Math.max(-PITCH_LIMIT, this.pitch + deltaY * 0.008))\n    this.apply()\n  }\n\n  /** Exponential zoom (host wheel: pass ±1-ish steps). */\n  zoom(delta: number): void {\n    this.radius = Math.min(200, Math.max(0.5, this.radius * Math.exp(delta * 0.2)))\n    this.apply()\n  }\n\n  /** Pan the target in the camera's screen plane (host drives, e.g. middle-drag). */\n  pan(deltaX: number, deltaY: number): void {\n    const k = this.radius * 0.0015\n    // Camera-LOCAL screen basis, so a vertical drag slides along the view plane (like the\n    // horizontal one already did) instead of climbing the world Y axis.\n    const { right, up } = orbitBasis(this.yaw, this.pitch)\n    this.target = [\n      this.target[0] - (right[0] * deltaX - up[0] * deltaY) * k,\n      this.target[1] - (right[1] * deltaX - up[1] * deltaY) * k,\n      this.target[2] - (right[2] * deltaX - up[2] * deltaY) * k,\n    ]\n    this.apply()\n  }\n\n  focus(point: V3, radius?: number): void {\n    this.target = point\n    if (radius !== undefined) this.radius = Math.max(0.5, radius)\n    this.apply()\n  }\n}\n"}

package/runtime/sdk/gl/Camera.ts

@@ -36,6 +36,12 @@ export class Camera extends Node {
    *  defaults (the headless core takes a `fov` option) and a blind push would overwrite them. */
   private _projSet = false
 
+  // Exposure the app asked for (filament's physical defaults until it does): f/16, 1/125 s, ISO 100 =
+  // EV100 15, bright sunlight — what every light intensity in the docs is tuned against.
+  private _exposure = { aperture: 16, shutterSpeed: 1 / 125, iso: 100 }
+  private _ev = 0
+  private _exposureSet = false
+
   /** @internal — Scene wires the camera to its native scene id + projection callback. */
   _attach(sceneId: number): void {
     this._sceneId = sceneId
@@ -43,6 +49,39 @@ export class Camera extends Node {
       for (let i = 0; i < 16; i++) this.projectionMatrix[i] = mat[i]
     })
     if (this._projSet) this._applyProjection()
+    if (this._exposureSet) this._applyExposure()
+  }
+
+  /** Exposure compensation in stops (default 0): +1 doubles how bright the scene renders, −2
+   *  quarters it. The one exposure knob most games need — a dark interior, a flash of white, or eye
+   *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
+   *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
+   *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+  get exposureCompensation(): number { return this._ev }
+  set exposureCompensation(stops: number) {
+    this._ev = Number.isFinite(stops) ? stops : 0
+    this._exposureSet = true
+    this._applyExposure()
+  }
+
+  /** The physical camera: `aperture` in f-stops, `shutterSpeed` in seconds, `iso`, plus the same
+   *  `compensation` in stops — any subset, one call. `camera.setExposure({ iso: 400 })` is two stops
+   *  brighter than the default f/16 · 1/125 · ISO 100. */
+  setExposure(exposure: { aperture?: number, shutterSpeed?: number, iso?: number, compensation?: number }): this {
+    if (exposure.aperture !== undefined) this._exposure.aperture = exposure.aperture
+    if (exposure.shutterSpeed !== undefined) this._exposure.shutterSpeed = exposure.shutterSpeed
+    if (exposure.iso !== undefined) this._exposure.iso = exposure.iso
+    if (exposure.compensation !== undefined) this._ev = exposure.compensation
+    this._exposureSet = true
+    this._applyExposure()
+    return this
+  }
+
+  /** Hosts that predate the call keep the fixed default (older wasm / native builds). */
+  private _applyExposure(): void {
+    if (this._sceneId < 0) return
+    const e = this._exposure
+    _creator.setCameraExposure?.(this._sceneId, e.aperture, e.shutterSpeed, e.iso * 2 ** this._ev)
   }
 
   /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */

package/runtime/sdk/gl/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/runtime/sdk/gl/Scene.ts

@@ -8,6 +8,7 @@
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem, _detachAllSystems, type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect"
 import { _bumpNavEpoch, _navEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
+import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { _requestCameraPermission } from "../plugins/permission"
@@ -115,6 +116,14 @@ export type SceneOptions = {
    *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
    *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
   anisotropy?: number
+  /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
+   *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
+   *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
+   *  1..8 is where white lands as a multiple of SDR white — the "HDR brightness" of a console
+   *  calibration screen, where 1.5–2 is the norm; default 1 keeps a white wall at the UI's white,
+   *  faithful but dim next to what "HDR on" is expected to look like. Engine-wide like `anisotropy`;
+   *  `device.hdr` is the runtime form and tells you whether the display has any headroom at all. */
+  hdr?: { strength?: number; paperWhite?: number }
 }
 
 // Route aspect update(dt) through the render-synced native phases (render() early = before physics,
@@ -188,6 +197,10 @@ export class Scene implements Presentable {
     // Before anything else in this constructor that could load a texture: the value has to be in
     // place by the time assets bind their samplers.
     if (options.anisotropy !== undefined) _creator.setTextureAnisotropy?.(options.anisotropy)
+    if (options.hdr) {
+      if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
+      if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
+    }
     if (options.renderScale !== undefined || options.dynamicResolution) {
       this.setRenderOptions(options.renderScale ?? 1, options.dynamicResolution ?? false)
     }

package/runtime/sdk/gl/Trigger.ts

@@ -1,45 +1,45 @@
-// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
-// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
-// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
-//
-//   const goal = new Mesh(box(), material)
-//     .aspect(Shape, { box: [1, 2, 1] })
-//     .aspect(Trigger)
-//   goal.addEventListener('enter', other => win(other))
-//   goal.addEventListener('exit',  other => …)
-
-import { Aspect } from "../core/Aspect"
-import { Shape } from "./Shape"
-import { ensurePhysicsEvents } from "./physicsEvents"
-import type { Node } from "./Node"
-
-export class Trigger extends Aspect<"trigger", Node> {
-  static readonly aspect = "trigger"
-
-  private _bodyId = 0
-  /** Native body id (0 if no physics support). */
-  get id(): number { return this._bodyId }
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
-    }
-    const shapeId = shape._claim()
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
-    shape._ownBody(this._bodyId)
-    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    const shape = this.node.get(Shape)
-    if (shape) {
-      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
-      shape._recreatePickBody()
-    }
-  }
-
-  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
-}
+// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
+//
+//   const goal = new Mesh(box(), material)
+//     .aspect(Shape, { box: [1, 2, 1] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => …)
+
+import { Aspect } from "../core/Aspect"
+import { Shape } from "./Shape"
+import { ensurePhysicsEvents } from "./physicsEvents"
+import type { Node } from "./Node"
+
+export class Trigger extends Aspect<"trigger", Node> {
+  static readonly aspect = "trigger"
+
+  private _bodyId = 0
+  /** Native body id (0 if no physics support). */
+  get id(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    const shapeId = shape._claim()
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
+    shape._ownBody(this._bodyId)
+    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()
+    }
+  }
+
+  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
+}