lecodes-cli 0.17.2 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "dependencies": {
     "@letary/chisel": "^0.8.0",
     "jimp": "^1.6.1"
@@ -16,8 +16,8 @@
   },
   "peerDependencies": {
     "lecodes-design": "^0.8.1",
-    "lecodes-renderer": "^0.8.7",
-    "lecodes-3d-editor": "^0.3.1",
+    "lecodes-renderer": "^0.8.8",
+    "lecodes-3d-editor": "^0.4.0",
     "lecodes-assets": "^0.1.0"
   },
   "bin": {

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\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}\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._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\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/** (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/** 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    if (node.anim.playing) { node.anim.speed = speed; node.anim.loop = loop }\n    if (u.button(node.anim.playing ? \"Restart\" : \"Play\")) {\n      node.anim.speed = speed\n      node.anim.play(clip, { loop })\n    }\n    if (u.button(\"Stop\")) {\n      // stop AND reset the pose (time 0 re-poses the skeleton even while stopped)\n      node.anim.stop()\n      node.anim.time = 0\n    }\n    const duration = clips.find((c) => c.name === clip)?.duration\n    u.info(node.anim.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      // marker-flagged nodes (empties/cameras) — placement/tool rays step past them like editor\n      // nodes (a drop must land on real geometry)\n      if (hit.node && !isEditorNode(hit.node)\n          && !(hit.node as { _sceneMarker?: string })._sceneMarker\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\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    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\n        try { 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  /** 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  /** 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\", value: unknown): void {\n    const node = resolveKey(name)\n    if (!node) return\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  /** 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 material tweak on a mesh node (color/roughness/metallic) — mirrors the inspector while\n   *  the document commit re-runs lazily. Unknown node / non-mesh is a no-op. */\n  setMaterialProp(name: string, key: \"color\" | \"roughness\" | \"metallic\", value: unknown): void {\n    const node = state.nodes[name]\n    if (!(node instanceof Mesh)) return\n    if (key === \"color\") node.material.color = value as string\n    else if (typeof value === \"number\") node.material.uniforms[key] = value\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    const node = await handle._patchNode(path, def)\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  },\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    return {\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  /** 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 box = node ? _creator.computeBoundingBox?.(node.id) : undefined\n    if (!node || !box) return false\n    if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return false\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    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    return true\n  },\n}\n\n;(globalThis as any).__lecodesSceneHarness = controller\n","math.ts":"// Pure gizmo math — plain number tuples in/out, no SDK dependencies, so it unit-tests directly\n// (packages/sdk/tests import it) and the harness bundle stays engine-agnostic here.\n\nexport type V3 = readonly [number, number, number]\n\nexport const add = (a: V3, b: V3): V3 => [ a[0] + b[0], a[1] + b[1], a[2] + b[2] ]\nexport const sub = (a: V3, b: V3): V3 => [ a[0] - b[0], a[1] - b[1], a[2] - b[2] ]\nexport const scale = (a: V3, s: number): V3 => [ a[0] * s, a[1] * s, a[2] * s ]\nexport const dot = (a: V3, b: V3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]\nexport const length = (a: V3): number => Math.hypot(a[0], a[1], a[2])\n\n/**\n * Parameter `t` along the axis line (origin + dir·t, dir unit-length) of the point closest to the\n * given ray. Standard closest-point-between-two-lines; falls back to projecting the ray origin when\n * the lines are near-parallel (denominator ~ 0).\n */\nexport const closestAxisParam = (rayOrigin: V3, rayDir: V3, axisOrigin: V3, axisDir: V3): number => {\n  // minimize |axisOrigin + t·axisDir − (rayOrigin + s·rayDir)|²:\n  //   t = s·b + d,  s = t·b − e   ⇒   t = (d − b·e) / (1 − b²)\n  const w = sub(rayOrigin, axisOrigin)\n  const b = dot(axisDir, rayDir)\n  const d = dot(axisDir, w)\n  const e = dot(rayDir, w)\n  const denom = 1 - b * b // axisDir·axisDir = rayDir·rayDir = 1\n  if (Math.abs(denom) < 1e-8) return d\n  return (d - b * e) / denom\n}\n\n/** Distance between a ray and an axis SEGMENT (t clamped to [0, segLength]). */\nexport const rayToAxisSegmentDistance = (\n  rayOrigin: V3, rayDir: V3, axisOrigin: V3, axisDir: V3, segLength: number,\n): number => {\n  const t = Math.max(0, Math.min(segLength, closestAxisParam(rayOrigin, rayDir, axisOrigin, axisDir)))\n  const p = add(axisOrigin, scale(axisDir, t))\n  // closest point on the ray to p (s clamped to ≥ 0 — the ray starts at the camera)\n  const s = Math.max(0, dot(sub(p, rayOrigin), rayDir))\n  const q = add(rayOrigin, scale(rayDir, s))\n  return length(sub(p, q))\n}\n\nexport type AxisPick = { axis: 0 | 1 | 2, startParam: number }\n\nconst AXES: V3[] = [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]\n\n/**\n * Which gizmo axis (if any) a ray grabs: the closest axis whose segment [origin, origin + dir·len]\n * passes within `threshold` of the ray. Returns the axis plus the grab parameter along it (the\n * drag delta is `currentParam - startParam` on subsequent moves).\n */\nexport const pickGizmoAxis = (\n  rayOrigin: V3, rayDir: V3, gizmoOrigin: V3, axisLength: number, threshold: number,\n): AxisPick | null => {\n  let best: AxisPick | null = null\n  let bestDist = threshold\n  for (let i = 0; i < 3; i++) {\n    const dist = rayToAxisSegmentDistance(rayOrigin, rayDir, gizmoOrigin, AXES[i], axisLength)\n    if (dist <= bestDist) {\n      bestDist = dist\n      best = { axis: i as 0 | 1 | 2, startParam: closestAxisParam(rayOrigin, rayDir, gizmoOrigin, AXES[i]) }\n    }\n  }\n  return best\n}\n\n/** The world-axis direction for an axis index. */\nexport const axisDir = (axis: 0 | 1 | 2): V3 => AXES[axis]\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}\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/** (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      // marker-flagged nodes (empties/cameras) — placement/tool rays step past them like editor\n      // nodes (a drop must land on real geometry)\n      if (hit.node && !isEditorNode(hit.node)\n          && !(hit.node as { _sceneMarker?: string })._sceneMarker\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\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    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  /** 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, plus the editor-marker entities to hide\n   *  from the inset. Null when the node is unknown or has no place. */\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    const hide: number[] = []\n    const walk = (n: Node): void => {\n      for (const c of n.children) {\n        if (c.name === \"__editor_marker\") hide.push(c.id)\n        walk(c)\n      }\n    }\n    for (const n of Object.values(state.nodes)) if (!n.parent || !(n.parent as { _sceneDef?: boolean })._sceneDef) walk(n)\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 material tweak on a mesh node (color/roughness/metallic) — mirrors the inspector while\n   *  the document commit re-runs lazily. Unknown node / non-mesh is a no-op. */\n  setMaterialProp(name: string, key: \"color\" | \"roughness\" | \"metallic\", value: unknown): void {\n    const node = state.nodes[name]\n    if (!(node instanceof Mesh)) return\n    if (key === \"color\") node.material.color = value as string\n    else if (typeof value === \"number\") node.material.uniforms[key] = value\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    const node = await handle._patchNode(path, def)\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 && c.name !== \"__editor_marker\") 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 box = node ? _creator.computeBoundingBox?.(node.id) : undefined\n    if (!node || !box) return false\n    if (!(box[3] - box[0] > 1e-6 || box[4] - box[1] > 1e-6 || box[5] - box[2] > 1e-6)) return false\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    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    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/compile/bundler.ts

@@ -54,7 +54,7 @@ const CHISEL_DEFINE: Record<string, string> = { RAD2DEG: "57.29577951308232", DE
 
 // Methods the native host invokes by name have no in-bundle caller, so method-DCE can't see them.
 // The SDK prefixes its framework / host-facing methods with `_` (`_emitTouchStart`, `_emitClick`,
-// `_onAnimationComplete`, `_emitAnim`, …), so keep every underscore-prefixed method on classes that survive.
+// `_onSlotEvent`, `_emitCollision`, …), so keep every underscore-prefixed method on classes that survive.
 const CHISEL_KEEP = [ "_*" ]
 
 /** The two inject modules (paths inside chisel's file map, see collectSdkFiles): the client SDK

package/runtime/sdk/compile/compileProject.ts

@@ -23,6 +23,10 @@ export type CompileEntry = {
   remote?: boolean
   /** Compiled-shader artifacts (platform + src); the first drives the per-backend URL. */
   shaders?: { platform: string, src: string }[]
+  /** `shaders` are LOCAL files staged next to the bundle (bare artifact names, not server srcs):
+   *  the module compiles to a fetchLocal lookup instead of a URL. Set by the CLI's local shader
+   *  compile for hosts with no asset server (the desktop host). */
+  shadersLocal?: boolean
 }
 
 export type CompileOptions = {
@@ -86,7 +90,18 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
       }
     } else if (e.type === "shader") {
       const shaders = e.shaders ?? []
-      if (shaders.length > 2) {
+      if (e.shadersLocal && shaders.length > 0) {
+        // Artifacts compiled locally and staged NEXT TO the bundle (no asset server): the host
+        // reads them by name through the same fetchLocal door the built-in materials use
+        // (`Material.lit` → fetchLocal("lit.filamat")), and Material.load parses the "id:" scheme.
+        // The name is built at RUNTIME because one bundle serves every native backend — the
+        // desktop host reports "desktop" on Windows and "opengl" on Linux, iOS "metal".
+        // Only entries the CLI actually compiled+staged carry `shadersLocal`; server artifacts
+        // (URLs) and un-staged ones keep the URL forms below.
+        const name = shaders[0].src.split(/[\\/]/).pop() ?? ""
+        const [prefix, suffix = ".filamat"] = name.split("_opengl")
+        files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
+      } else if (shaders.length > 2) {
         files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.subBackend ?? _creator.backend}")}\``
       } else if (shaders.length > 0) {
         files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.backend}")}\``

package/runtime/sdk/compile/header.ts

@@ -41,7 +41,12 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   // Local assets to preload: explicit fetchLocal() calls + implicit engine archives.
   const localAssets = new Set<string>()
   for (const m of code.matchAll(/_creatorUtils\.fetchLocal\((.+?)\)/g)) {
-    localAssets.add(m[1].replaceAll(/['"]/g, "").trim())
+    const arg = m[1].trim()
+    // Only a plain string literal names a file. A computed argument (the local-shader lookup
+    // builds `"<hash>_" + _creator.backend + ".filamat"` at runtime, since one bundle serves
+    // every backend) would otherwise land in the header as a garbage "name".
+    if (!/^(['"])[^'"]*\1$/.test(arg)) continue
+    localAssets.add(arg.slice(1, -1).trim())
   }
   if (/_creator\.createGlb/.test(code)) localAssets.add("uberarchive")
   if (/_creator\.captureImage/.test(code)) localAssets.add("capture")

package/runtime/sdk/compile/index.ts

@@ -28,6 +28,22 @@ export {
   type ScanModule,
 } from "./detectEntry"
 export { sanitizeAssetName, isCanonicalAssetName } from "./assetName"
+export {
+  PLATFORM_BUILD,
+  externalSamplerReg,
+  matcPlatformsFor,
+  matcArgs,
+  type MatcPlatform,
+  type ShaderPlatform,
+} from "./shaderTargets"
+export {
+  buildLiteMaterialArtifact,
+  extractMatBlocks,
+  parseJsonish,
+  type LiteMaterialArtifact,
+  type LiteMaterialParam,
+  type JsonishValue,
+} from "./liteMaterial"
 export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
 export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {

package/runtime/sdk/compile/liteMaterial.ts

@@ -0,0 +1,247 @@
+// .mat source → Web Lite material artifact.
+//
+// matc validates and compiles the .mat for the native platforms; the lite web runtime
+// (packages/viewer-lite) has no Filament, so it gets this JSON artifact instead: the parsed
+// material definition (parameters, shading model, blending) plus the author's fragment body with
+// `materialParams.x` rewritten to `materialParams_x`. viewer-lite wraps that body in its own GLSL
+// template (src/gl/customMaterial.ts mirrors the artifact type) — GLSL knowledge stays there, this
+// module only owns .mat syntax.
+//
+// The parsed `params`/`samplers` lists are deliberately structured (filament type names kept
+// verbatim): they are also the metadata a future "typed materials" codegen needs — generating a
+// Material subclass with typed uniform setters straight from the shader's parameter list.
+//
+// This module is dependency-free and must never throw: an exotic material becomes an
+// `unsupported` artifact (viewer-lite falls back to unlit + warning), never a failed shader save.
+
+export type LiteMaterialParam = {
+  name: string
+  /** filament type name: float, float2..4, int..4, bool..4, float3x3, float4x4 */
+  type: string
+  /** array parameters ("float[9]") */
+  size?: number
+}
+
+export type LiteMaterialArtifact = {
+  lecodesLiteMaterial: 1
+  shadingModel: "lit" | "unlit"
+  blending: "opaque" | "transparent" | "fade" | "add" | "masked"
+  maskThreshold: number
+  doubleSided: boolean
+  culling: "back" | "front" | "none"
+  depthWrite: boolean
+  /** Filament's shadow-catcher flag (unlit only, transparency mandatory — matc enforces both):
+   *  the fragment shows baseColor scaled by the received shadow amount, transparent elsewhere. */
+  shadowMultiplier: boolean
+  params: LiteMaterialParam[]
+  /** sampler2d / samplerExternal parameters — all become sampler2D in lite */
+  samplers: { name: string }[]
+  /** the author's fragment block body, `materialParams.x` rewritten to `materialParams_x` */
+  fragmentCode: string
+  /** the fragment writes MaterialInputs.normal — the template adds the tangent-frame transform */
+  writesNormal: boolean
+  /** a vertex{} block was present and dropped (lite ignores custom vertex stages) */
+  hasVertexBlock: boolean
+  /** set when the material can't run in lite at all (parse failure, unsupported param type) */
+  unsupported?: string
+}
+
+// ---- .mat block extraction ----------------------------------------------------------------------
+
+/** Split a .mat file into its top-level `name { ... }` blocks (material / fragment / vertex),
+ *  matching braces while skipping comments so `{` inside GLSL or comments can't derail it. */
+export const extractMatBlocks = (text: string): Record<string, string> => {
+  const blocks: Record<string, string> = {}
+  let i = 0
+  const skipNoise = (): void => {
+    for (;;) {
+      while (i < text.length && /\s/.test(text[i]!)) i++
+      if (text[i] === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++ }
+      else if (text[i] === "/" && text[i + 1] === "*") {
+        i += 2
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
+        i += 2
+      } else return
+    }
+  }
+  while (i < text.length) {
+    skipNoise()
+    const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(i))
+    if (!m) { i++; continue }
+    i += m[0].length
+    skipNoise()
+    if (text[i] !== "{") continue
+    // brace-match the block body, comment-aware
+    let depth = 0
+    const start = i
+    while (i < text.length) {
+      const c = text[i]
+      if (c === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i++ }
+      else if (c === "/" && text[i + 1] === "*") {
+        i += 2
+        while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
+        i++ // lands on '/', loop increment steps past
+      }
+      else if (c === "{") depth++
+      else if (c === "}") { depth--; if (depth === 0) break }
+      i++
+    }
+    blocks[m[0]] = text.slice(start + 1, i)
+    i++
+  }
+  return blocks
+}
+
+// ---- "jsonish" material-block parser --------------------------------------------------------------
+// matc's material block is relaxed JSON: unquoted keys/values, comments, optional commas, and both
+// `:` and `=` as separators. Small recursive-descent parser over that grammar.
+
+export type JsonishValue = string | number | boolean | JsonishValue[] | { [key: string]: JsonishValue }
+
+export const parseJsonish = (src: string): Record<string, JsonishValue> => {
+  let i = 0
+  const fail = (msg: string): never => { throw new Error(`material block: ${msg} at offset ${i}`) }
+  const skip = (): void => {
+    for (;;) {
+      while (i < src.length && /[\s,]/.test(src[i]!)) i++
+      if (src[i] === "/" && src[i + 1] === "/") { while (i < src.length && src[i] !== "\n") i++ }
+      else if (src[i] === "/" && src[i + 1] === "*") {
+        i += 2
+        while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) i++
+        i += 2
+      } else return
+    }
+  }
+  const quoted = (q: string): string => {
+    i++
+    const start = i
+    while (i < src.length && src[i] !== q) i++
+    return src.slice(start, i++)
+  }
+  const word = (): string => {
+    const m = /^[^\s{}[\]:,="']+/.exec(src.slice(i))
+    if (!m) fail("expected a value")
+    i += m![0].length
+    return m![0]
+  }
+  const value = (): JsonishValue => {
+    skip()
+    const c = src[i]
+    if (c === "{") return object()
+    if (c === "[") return array()
+    if (c === '"' || c === "'") return quoted(c)
+    const w = word()
+    if (w === "true") return true
+    if (w === "false") return false
+    const n = Number(w)
+    return Number.isNaN(n) ? w : n
+  }
+  const array = (): JsonishValue[] => {
+    i++ // [
+    const out: JsonishValue[] = []
+    for (;;) {
+      skip()
+      if (i >= src.length) fail("unterminated array")
+      if (src[i] === "]") { i++; return out }
+      out.push(value())
+    }
+  }
+  const object = (): Record<string, JsonishValue> => {
+    i++ // {
+    const out: Record<string, JsonishValue> = {}
+    for (;;) {
+      skip()
+      if (i >= src.length) fail("unterminated object")
+      if (src[i] === "}") { i++; return out }
+      const key = src[i] === '"' || src[i] === "'" ? quoted(src[i]!) : word()
+      skip()
+      if (src[i] !== ":" && src[i] !== "=") fail(`expected ':' after key "${key}"`)
+      i++
+      out[key] = value()
+    }
+  }
+  skip()
+  if (src[i] !== "{") fail("expected '{'")
+  return object()
+}
+
+// ---- artifact builder -----------------------------------------------------------------------------
+
+const PARAM_TYPES = new Set([
+  "float", "float2", "float3", "float4",
+  "int", "int2", "int3", "int4",
+  "bool", "bool2", "bool3", "bool4",
+  "float3x3", "float4x4",
+])
+const SAMPLER_TYPES = new Set(["sampler2d", "samplerExternal"])
+
+const unsupported = (reason: string): LiteMaterialArtifact => ({
+  lecodesLiteMaterial: 1, unsupported: reason,
+  shadingModel: "unlit", blending: "opaque", maskThreshold: 0.4,
+  doubleSided: false, culling: "back", depthWrite: true, shadowMultiplier: false,
+  params: [], samplers: [], fragmentCode: "", writesNormal: false, hasVertexBlock: false,
+})
+
+export const buildLiteMaterialArtifact = (text: string): LiteMaterialArtifact => {
+  try {
+    const blocks = extractMatBlocks(text)
+    if (blocks.material === undefined) return unsupported("no material block")
+    if (blocks.fragment === undefined) return unsupported("no fragment block")
+    const def = parseJsonish("{" + blocks.material + "}")
+
+    const params: LiteMaterialParam[] = []
+    const samplers: { name: string }[] = []
+    const rawParams = def.parameters === undefined ? []
+      : Array.isArray(def.parameters) ? def.parameters : [def.parameters]
+    for (const raw of rawParams) {
+      if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return unsupported("malformed parameter entry")
+      const name = String((raw as Record<string, JsonishValue>).name ?? "")
+      const typeRaw = String((raw as Record<string, JsonishValue>).type ?? "")
+      const typeMatch = /^(\w+)(?:\[(\d+)\])?$/.exec(typeRaw)
+      if (!name || !typeMatch) return unsupported(`malformed parameter "${name || typeRaw}"`)
+      const [, type, size] = typeMatch
+      if (SAMPLER_TYPES.has(type!)) {
+        if (size) return unsupported(`sampler arrays are not supported ("${name}")`)
+        samplers.push({ name })
+      } else if (PARAM_TYPES.has(type!)) {
+        params.push(size ? { name, type: type!, size: Number(size) } : { name, type: type! })
+      } else {
+        return unsupported(`parameter type "${typeRaw}" ("${name}")`)
+      }
+    }
+
+    // cloth/subsurface/specularGlossiness approximate as lit — better than refusing outright.
+    const shadingModel = def.shadingModel === "unlit" ? "unlit" : "lit"
+    const blendingRaw = String(def.blending ?? "opaque")
+    const blending =
+      blendingRaw === "transparent" || blendingRaw === "fade" || blendingRaw === "add" || blendingRaw === "masked"
+        ? blendingRaw
+        : blendingRaw === "multiply" || blendingRaw === "screen" ? "transparent" // approximate
+        : "opaque"
+    const culling = def.culling === "none" ? "none" : def.culling === "front" ? "front" : "back"
+    // Filament defaults: depth write on except for transparent/fade blending.
+    const depthWrite = typeof def.depthWrite === "boolean" ? def.depthWrite
+      : blending !== "transparent" && blending !== "fade" && blending !== "add"
+
+    const fragmentCode = blocks.fragment.replace(/\bmaterialParams\./g, "materialParams_")
+    if (!/\bvoid\s+material\s*\(/.test(fragmentCode)) return unsupported("fragment block has no material() function")
+
+    return {
+      lecodesLiteMaterial: 1,
+      shadingModel,
+      blending,
+      maskThreshold: typeof def.maskThreshold === "number" ? def.maskThreshold : 0.4,
+      doubleSided: def.doubleSided === true,
+      culling,
+      depthWrite,
+      shadowMultiplier: def.shadowMultiplier === true,
+      params,
+      samplers,
+      fragmentCode,
+      writesNormal: /\.normal\s*=/.test(fragmentCode),
+      hasVertexBlock: blocks.vertex !== undefined,
+    }
+  } catch (e) {
+    return unsupported(e instanceof Error ? e.message : String(e))
+  }
+}

package/runtime/sdk/compile/shaderTargets.ts

@@ -0,0 +1,42 @@
+// The one shader-compile target matrix, shared by the backend's server-side compile
+// (backend/src/utils/compileShader.ts) and the CLI's local compile (lecodes-cli
+// src/compile/shaders.ts). Both must produce the SAME artifact family for a .mat source —
+// the compiled bundle derives per-backend URLs by substituting `_creator.subBackend ??
+// _creator.backend` into the opengl src (compileProject.ts), so the set of names is ABI.
+
+export const externalSamplerReg = /type\s*:\s*samplerExternal/g
+
+// matc invocation per target. `profile` is matc's -p (mobile = shader model MOBILE / ESSL3,
+// desktop = shader model DESKTOP / GLSL 4.1); `api` is -a. WebGL and the Windows desktop host
+// both run OpenGL without external (OES) sampler support, so they get samplerExternal rewritten
+// to sampler2d. The desktop variant exists because the desktop Filament engine rejects the mobile
+// _opengl shader ("not built for desktop"); _creator.backend returns "desktop" there.
+export const PLATFORM_BUILD = {
+  opengl:  { profile: "mobile",  api: "opengl", replaceExternal: false },
+  metal:   { profile: "mobile",  api: "metal",  replaceExternal: false },
+  webgl:   { profile: "mobile",  api: "opengl", replaceExternal: true },
+  desktop: { profile: "desktop", api: "opengl", replaceExternal: true },
+} as const
+export type MatcPlatform = keyof typeof PLATFORM_BUILD
+
+// 'webgl-lite' is not a matc target: viewer-lite gets a JSON artifact (parsed .mat — see
+// liteMaterial.ts) that it wraps in its own GLSL template at runtime.
+export type ShaderPlatform = MatcPlatform | "webgl-lite"
+
+/** The matc platforms a .mat source needs compiled. WebGL is matc-compiled only when the shader
+ *  has an external sampler: its samplerExternal → sampler2d rewrite makes the output differ from
+ *  the mobile opengl build. Without one the WebGL artifact is byte-identical to the mobile shader,
+ *  so callers copy it from the opengl output instead of running matc again. Either way a _webgl
+ *  artifact must always exist — the web runtime always requests one (via _creator.subBackend). */
+export const matcPlatformsFor = (text: string): MatcPlatform[] => {
+  externalSamplerReg.lastIndex = 0
+  return externalSamplerReg.test(text)
+    ? ["opengl", "metal", "webgl", "desktop"]
+    : ["opengl", "metal", "desktop"]
+}
+
+/** The matc argv (without the executable) for one target. */
+export const matcArgs = (platform: MatcPlatform, outPath: string, inPath: string): string[] => {
+  const build = PLATFORM_BUILD[platform]
+  return ["-p", build.profile, "--no-essl1", "-a", build.api, "-o", outPath, inPath]
+}