lecodes-viewer 0.19.0

package/src/host.ts

@@ -0,0 +1,428 @@
+// The viewer host: engine bring-up and bundle execution, decoupled.
+//
+// `createHost` brings up the engines/bridges for a root element once; `host.run(code)` executes a
+// compiled bundle against them and can be called repeatedly — each run gets its own timer scope and
+// error attribution, so the scene editor can re-run a scene bundle without re-initializing Filament
+// (and without stopping the editor-harness bundle running in the same host).
+//
+// `mountCreator` (createViewer.ts) is the one-shot convenience wrapper: header sniffing + one host +
+// one run, returning the shape the Simulator and embed always used.
+
+import { createViewer, type ViewerOptions } from './viewer/createViewer'
+import { createCanvasHost } from './canvas/createCanvasHost'
+import { putBuffer, getBuffer } from './utils/fetch'
+import { createNavHostBridge } from 'lecodes-viewer-lite/src/gl/core/navBridge'
+import { createInputHost } from "lecodes-viewer-lite/src/utils/input"
+import { createUtils } from './utils/createUtils'
+import { ensureFontsLoaded, loadBootFonts, type BootFont } from './utils/fonts'
+import type { SafeAreaSpec } from './ui/safeAreaSpec'
+import { createTimers } from './utils/globals'
+import { viewScale } from './ui/viewScale'
+import { extractInlineSourceMap, isNativeError, mapErrorStack, SourceMap, type MappedFrame, type PreviewError } from './sourcemapError'
+import { symbolizeWasmFrames } from './viewer/wasmCrashSymbolizer'
+
+export type CreatorMethods = Awaited<ReturnType<typeof createViewer>>
+
+// A UI renderer factory: returns the `_creatorUI`-shaped object for a root element. The DOM renderer
+// is `createUI`; `createCanvasUIRenderer` runs the canvas-ui package instead. The canvas host is
+// threaded in so UIImage(canvas) can resolve a baked surface to an image.
+export type UIFactory = (root: HTMLElement, canvasHost?: ReturnType<typeof createCanvasHost>) => Promise<any>
+
+// Which engine(s) to bring up. `mountCreator` derives this from the compiler's header directives;
+// callers that know their content (the scene editor is always pure 3D) pass it explicitly.
+//   gl      — Filament 3D on one canvas
+//   gl-lite — the lightweight WebGL2 3D engine (viewer-lite, no Filament wasm) on one canvas
+//   2d      — creator-2d (sokol) on one canvas, 3D creator stubbed
+//   dual    — both engines on separate canvases, openScene toggles visibility
+//   defer   — 3D creator stubbed; the bundle brings the engine up via `createEngine()` (also used
+//             for UI-only projects, which simply never call it)
+export type EngineMode = 'gl' | 'gl-lite' | '2d' | 'dual' | 'defer'
+
+export type HostOptions = {
+  engine?: EngineMode
+  // UI renderer factory, or false for an engine-only host (no fonts preload, no `_creatorUI`).
+  ui?: UIFactory | false
+  // Override the measurement fonts to force-load before the first layout (default: the vendored
+  // variable Roboto — one face, all weights). Only meaningful when `ui` is set.
+  fonts?: string[]
+  // App-declared boot faces from the bundle's `// fonts:` header — loaded in parallel with the
+  // wasm/engine and awaited (≤2s budget) before the host returns. Only meaningful when `ui` is set.
+  bootFonts?: BootFont[]
+  preloads?: Set<string>
+  // Method overrides assigned onto the 3D creator (test/interception seam).
+  methods?: Partial<CreatorMethods>
+  // Wire window key listeners into `_creatorUtils.inputKey` (Input.key). Default true.
+  keyboard?: boolean
+  // Extra windows to also poll physical keys from, beyond the host's own `window`. The editor passes
+  // its parent window so the app sees keys before the user clicks into the (iframe) preview — the
+  // dual-window pattern the lite host already uses.
+  keyboardTargets?: Window[]
+  // The URL the app was opened with (app.launchUrl / the cold-start deep link). Warm links go
+  // through `_creatorUtils._emitAppEvent("url", url)`.
+  launchUrl?: string | null
+  // Device-emulation safe-area override (the Simulator's iOS/Android shells) — pins the insets
+  // per orientation and declares system-bar edges. Absent = the neutral web defaults.
+  safeArea?: SafeAreaSpec
+  // gl-lite only: clear to transparent instead of the skybox color (capture hosts — asset
+  // preview thumbnails composite over any page theme).
+  transparent?: boolean
+  // app.setOrientation sink: the embedder rotates its device frame ("landscape" | "portrait" |
+  // "auto"). Absent = best-effort screen.orientation.lock on the page (see createUtils).
+  onOrientation?: (mode: string) => void
+}
+
+export type RunOptions = {
+  // Called when this bundle throws, with the error mapped back to original source.
+  onError?: (error: PreviewError) => void
+}
+
+export type Run = {
+  // Whatever the bundle's final expression returned (bundles are IIFE-shaped scripts).
+  result: unknown
+  // Stop this run's timers/loops and stop attributing window errors to it. Engine state the bundle
+  // created (entities, scenes, screens) is NOT torn down here — that's the host's lifetime.
+  dispose(): void
+}
+
+type RunRecord = {
+  sourceMap: SourceMap | null
+  onError?: (error: PreviewError) => void
+  dispose(): void
+}
+
+export type Host = Awaited<ReturnType<typeof createHost>>
+
+export const createHost = async (root: HTMLElement, options: HostOptions = {}) => {
+  const engineMode = options.engine ?? 'gl'
+  const preloads = options.preloads ?? new Set<string>()
+
+  // Logical (layout-px) size of the host root, and the resolution factor the engines render at.
+  // Under the simulator's CSS zoom the root's on-screen size is logical × zoom, so an engine's
+  // backing store must grow to real device pixels: factor = devicePixelRatio × viewScale (the visual
+  // scale recovered from the DOM). Recomputed every resize — DPR changes when a window moves between
+  // displays of different density. See docs/simulator-plan.md phase 3.
+  const logicalSize = (): [number, number] => [Math.max(1, root.clientWidth), Math.max(1, root.clientHeight)]
+  const resolutionFactor = (): number =>
+    (typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1) * viewScale(root)
+  // Size a backing canvas to device px (logical × factor) while pinning its CSS box to logical px, so
+  // CSS zoom scales it as vector geometry — never a resampled texture (the HiDPI + zoom crispness fix).
+  const sizeCanvas = (c: HTMLCanvasElement, w: number, h: number, factor: number) => {
+    c.width = Math.max(1, Math.round(w * factor))
+    c.height = Math.max(1, Math.round(h * factor))
+    c.style.width = w + "px"
+    c.style.height = h + "px"
+  }
+
+  // Start loading the measurement font in parallel with the wasm/engine; awaited before returning so
+  // the first run's layout measures text against the real font, not a fallback.
+  const fontsReady = options.ui ? ensureFontsLoaded(options.fonts) : undefined
+  // App-declared boot faces (`// fonts:` header): loaded alongside, awaited with a ≤2s budget —
+  // the boot hold that makes first paint use the app's font (a loser face swaps in late).
+  const bootFontsReady = options.ui ? loadBootFonts(options.bootFonts ?? []) : undefined
+
+  const canvas = document.createElement("canvas")
+  root.appendChild(canvas)
+  let extraCanvas: HTMLCanvasElement | undefined
+
+  let createEngine = () => {}
+
+  let _creator: CreatorMethods
+  // The creator-2d bridge the 2D SDK calls through. Undefined for pure-3D projects (the bundled 2D
+  // code only references it when `// 2d: enable` is set, so nothing touches it otherwise).
+  let _creator2d: any = undefined
+  // Core 2D canvas host (OffscreenCanvas). Shared by 2D/3D/UI; the engine wrappers read its baked
+  // surfaces to upload textures. Cheap to construct (no OffscreenCanvas until first draw/measure).
+  const canvasHost = createCanvasHost(putBuffer, getBuffer)
+  // Navigation meshes (docs/navmesh-plan.md): creator-nav's wasm behind `_creatorNav` (lazy).
+  const navBridge = createNavHostBridge(getBuffer)
+
+  if (engineMode === 'dual') {
+    // Bring up both engines on separate canvases; wrap openScene to toggle visibility.
+    const canvas2d = document.createElement("canvas")
+    root.appendChild(canvas2d)
+    extraCanvas = canvas2d
+    const [ lw, lh ] = logicalSize()
+    const factor = resolutionFactor()
+    for (const c of [ canvas, canvas2d ]) { sizeCanvas(c, lw, lh, factor); c.style.display = "none" }
+
+    const { createViewer2d } = await import("./viewer2d/createViewer2d")
+    _creator2d = await createViewer2d(canvas2d, {}, canvasHost)
+    _creator = await createViewer(canvas, { preloads, canvasHost })
+    if (options.methods) Object.assign(_creator, options.methods)
+
+    const show = (active: HTMLCanvasElement) => {
+      canvas.style.display = active === canvas ? "block" : "none"
+      canvas2d.style.display = active === canvas2d ? "block" : "none"
+    }
+    const open3d = _creator.openScene.bind(_creator)
+    _creator.openScene = (id: number) => { show(canvas); return open3d(id) }
+    const open2d = _creator2d.openScene.bind(_creator2d)
+    _creator2d.openScene = (id: number) => { show(canvas2d); return open2d(id) }
+  } else if (engineMode === '2d') {
+    const [ lw, lh ] = logicalSize()
+    sizeCanvas(canvas, lw, lh, resolutionFactor())
+    canvas.style.display = "none"
+
+    // Lazy chunk: creator2d.{js,wasm} load only for 2D projects (a 3D project pays nothing).
+    const { createViewer2d } = await import("./viewer2d/createViewer2d")
+    _creator2d = await createViewer2d(canvas, {}, canvasHost)
+
+    // Stub the 3D creator so the UI renderer, resize observer and teardown keep working without
+    // bringing up Filament (same shape as the deferred stub below).
+    _creator = {
+      raycastView() { return 0 },
+      _onResize() { },
+      _dispose() { }
+    } as any
+  } else if (engineMode === 'gl-lite') {
+    const [ lw, lh ] = logicalSize()
+    sizeCanvas(canvas, lw, lh, resolutionFactor())
+    canvas.style.display = "none"
+
+    // Lazy chunk: ogl + the viewer-lite package's engine load only when the lite engine is
+    // requested — and the Filament wasm is never fetched at all. Deep import keeps the chunk to
+    // the engine alone (the package root also carries the standalone lite host + UI renderer).
+    const { createViewerLite } = await import("lecodes-viewer-lite/src/gl/createViewerLite")
+    _creator = await createViewerLite(canvas, { preloads, canvasHost, transparent: options.transparent }) as unknown as CreatorMethods
+    if (options.methods) {
+      Object.assign(_creator, options.methods)
+    }
+  } else if (engineMode === 'defer') {
+    _creator = {
+      raycastView() { return 0 },
+      _onResize() { },
+      _dispose() {}
+    } as any
+    createEngine = async () => {
+      const [ lw, lh ] = logicalSize()
+      sizeCanvas(canvas, lw, lh, resolutionFactor())
+
+      canvas.style.display = "block"
+
+      const viewer = await createViewer(canvas, { preloads, canvasHost })
+      Object.assign(_creator, viewer)
+      // Re-apply method overrides after the real engine lands, so they win over its defaults.
+      if (options.methods) Object.assign(_creator, options.methods)
+    }
+  } else {
+    const [ lw, lh ] = logicalSize()
+    sizeCanvas(canvas, lw, lh, resolutionFactor())
+
+    canvas.style.display = "none"
+
+    _creator = await createViewer(canvas, { preloads, canvasHost })
+    if (options.methods) {
+      Object.assign(_creator, options.methods)
+    }
+  }
+
+  const _creatorUI = options.ui ? await options.ui(root, canvasHost) : undefined
+  const _creatorUtils = createUtils({ launchUrl: options.launchUrl, onOrientation: options.onOrientation })
+  _creatorUI?._setCreator(_creator)
+  // Before the ResizeObserver's initial fire, so the first applied layout already has the insets.
+  if (options.safeArea) _creatorUI?._setSafeAreaSpec?.(options.safeArea)
+
+  // Presentable navigation (docs/navigation-presentable-plan.md): hand the UI layer the scene
+  // canvases + engine activation hooks, so scenes present as destinations (openView) instead of
+  // living under the screens. Read `_creator.openScene` at call time — the defer mode fills the
+  // stub in later (createEngine), and dual mode's visibility-toggling wrapper stays honored.
+  _creatorUI?._setSceneHost?.({
+    scene3d: engineMode !== '2d'
+      ? { el: canvas, open: (id: number) => _creator.openScene(id), close: () => _creator.closeScene?.() }
+      : undefined,
+    scene2d: engineMode === '2d' || engineMode === 'dual'
+      ? { el: extraCanvas ?? canvas, open: (id: number) => _creator2d.openScene(id), close: () => _creator2d.closeScene?.() }
+      : undefined,
+  })
+
+  // Push a logical size + fresh resolution factor to every engine. The factor carries the device-pixel
+  // target; the DOM UI renderer ignores it (its width/height stay logical px).
+  const pushResize = (w: number, h: number) => {
+    const factor = resolutionFactor()
+    _creator?._onResize(w, h, factor)
+    _creator2d?._onResize(w, h, factor)
+    _creatorUI?._onResize(w, h, factor)
+  }
+
+  const resizeObserver = new ResizeObserver(([ entry ]) => {
+    // contentRect is layout px (zoom-independent) — the logical viewport the app lays out against.
+    pushResize(entry.contentRect.width, entry.contentRect.height)
+  })
+  resizeObserver.observe(root)
+
+  // Recompute + re-push the resolution factor without a layout change. A CSS-zoom change (the phone
+  // shrinking to fit a resized window) leaves the logical size fixed, so the ResizeObserver stays
+  // silent — but the factor (× zoom) moved, and the engines must re-size their backing stores.
+  const refreshResolution = () => {
+    const [ w, h ] = logicalSize()
+    pushResize(w, h)
+  }
+
+  // Input host (keys / mouse / gamepads → Input.*). Keys listen on this window plus any extra windows
+  // the embedder passes (the editor passes its parent — the app runs in the runner iframe, but keeps
+  // focus in the editor document until the user clicks the preview). Host-lifetime, like the window
+  // error listeners.
+  const inputHost = createInputHost({
+    windows: [window, ...(options.keyboardTargets ?? []).filter(w => w && w !== window)],
+    root, keyboard: options.keyboard !== false,
+  })
+  _creatorUtils.inputKey = inputHost.inputKey
+  _creatorUtils.inputRead = inputHost.inputRead
+  _creatorUtils.inputSetPointerLock = inputHost.inputSetPointerLock
+  _creatorUtils.registerInputEvent = inputHost.registerInputEvent
+
+  // ---- error reporting -------------------------------------------------------------------------
+  // Window listeners are shared across runs (installed lazily on the first run); each async error is
+  // attributed to the run whose source map its stack resolves into. Native (WASM engine) errors have
+  // no JS frames, so they go to the most recent run.
+
+  const runs: RunRecord[] = []
+  let windowListenersInstalled = false
+
+  const emitError = (record: RunRecord, e: unknown, frames: MappedFrame[], eventMessage?: string) => {
+    const native = frames.length === 0 && isNativeError(e)
+    if (native) {
+      // The engine (Emscripten) prints the real message to the console; the value that reaches JS is a
+      // pointer/abort code. Surface it as an engine error and keep whatever description we do have.
+      const raw = typeof e === "number" || typeof e === "bigint"
+        ? `code ${e}`
+        : e instanceof Error ? (e.message || e.name) : String(e)
+      const detail = [ eventMessage, raw ].filter((v): v is string => !!v).filter((v, i, a) => a.indexOf(v) === i).join("\n")
+      console.error(`[le.codes] native engine error — ${detail || raw} (see console for the engine's message)`)
+      const preview: PreviewError = { message: "Native engine error", detail, frames: [], native: true, stack: e instanceof Error ? e.stack : undefined }
+      record.onError?.(preview)
+      // Late enrichment: decode the trap's wasm frames through the lazy symbol map (fetched only
+      // now, on the first crash) and emit again. Consumers treat a follow-up error as an overlay
+      // update, so the C++ stack appears as soon as the map arrives.
+      if (preview.stack) {
+        void symbolizeWasmFrames(preview.stack).then(nativeFrames => {
+          if (nativeFrames.length > 0) record.onError?.({ ...preview, nativeFrames })
+        })
+      }
+      return
+    }
+
+    const message = e instanceof Error ? e.message : String(e)
+    if (frames.length > 0) {
+      const top = frames[0]!
+      console.error(`[le.codes] ${message}\n    at ${top.source}:${top.line}:${top.column}${top.fn ? ` (${top.fn})` : ""}`)
+    } else {
+      console.error(`[le.codes] ${message}`)
+    }
+    record.onError?.({ message, frames, stack: e instanceof Error ? e.stack : undefined })
+  }
+
+  // Window events fire for the whole page, so only report what's clearly a preview bundle's: a JS
+  // error whose stack maps into one of the runs' source maps, or a native (WASM engine) error.
+  // `eventMessage` is the ErrorEvent's text, which for a native trap is often more descriptive than
+  // the raw thrown value.
+  const reportWindowError = (e: unknown, eventMessage?: string) => {
+    for (let i = runs.length - 1; i >= 0; i--) {
+      const record = runs[i]!
+      if (!record.sourceMap) continue
+      const frames = mapErrorStack(e, record.sourceMap)
+      if (frames.length > 0) return emitError(record, e, frames, eventMessage)
+    }
+    if (isNativeError(e)) {
+      const record = runs[runs.length - 1]
+      if (record) emitError(record, e, [], eventMessage)
+    }
+  }
+
+  const onWindowError = (ev: ErrorEvent) => reportWindowError(ev.error ?? ev.message, ev.message)
+  const onUnhandledRejection = (ev: PromiseRejectionEvent) => reportWindowError(ev.reason)
+
+  const ensureWindowListeners = () => {
+    if (windowListenersInstalled) return
+    windowListenersInstalled = true
+    window.addEventListener("error", onWindowError)
+    window.addEventListener("unhandledrejection", onUnhandledRejection)
+  }
+
+  // ---- run -------------------------------------------------------------------------------------
+
+  const run = (userCode: string, runOptions: RunOptions = {}): Run => {
+    ensureWindowListeners()
+
+    const timers = createTimers()
+    // The bundle carries an inline source map; the browser can't apply it to `new Function` frames,
+    // so error mapping happens host-side (see reportWindowError).
+    const sourceMap = extractInlineSourceMap(userCode)
+
+    let disposed = false
+    const dispose = () => {
+      if (disposed) return
+      disposed = true
+      const i = runs.indexOf(record)
+      if (i >= 0) runs.splice(i, 1)
+      timers.disposeAll()
+    }
+
+    const record: RunRecord = { sourceMap, onError: runOptions.onError, dispose }
+    runs.push(record)
+
+    const entries = {
+      _creator,
+      _creator2d,
+      _creatorUI,
+      _creatorUtils,
+      _creatorCanvas: canvasHost.bridge,
+      _creatorNav: navBridge,
+      ...timers.globals,
+      createEngine,
+    }
+
+    const func = new Function(...Object.keys(entries), userCode)
+    let result: unknown
+    try {
+      result = func(...Object.values(entries))
+    } catch (e) {
+      // Report the original location, then let it propagate as before. The record stays registered:
+      // whatever the bundle set up before throwing can still surface async errors.
+      emitError(record, e, sourceMap ? mapErrorStack(e, sourceMap) : [])
+      throw e
+    }
+
+    return { result, dispose }
+  }
+
+  const destroy = () => {
+    // Disconnect first: the observer callback closes over _creator/_creatorUI, so leaving it
+    // connected pins the WASM modules alive (and keeps firing into a torn-down engine).
+    resizeObserver.disconnect()
+
+    for (const record of [ ...runs ]) record.dispose()
+    if (windowListenersInstalled) {
+      window.removeEventListener("error", onWindowError)
+      window.removeEventListener("unhandledrejection", onUnhandledRejection)
+    }
+
+    _creator._dispose()
+    _creator2d?._dispose()
+    _creatorUI?._destroy?.()
+    root.removeChild(canvas)
+    if (extraCanvas) root.removeChild(extraCanvas)
+
+    _creatorUtils._disposeWebsockets()
+    _creatorUtils._disposeServices()
+    _creatorUtils._disposeAppEvents()
+
+    inputHost.dispose()
+  }
+
+  // Gate callers (a run's first openScreen triggers the first layout/measure) on the font being
+  // ready, so canvas-based text measurement never runs against a fallback font.
+  await fontsReady
+  await bootFontsReady
+
+  return {
+    _creator,
+    _creator2d,
+    _creatorUI,
+    _creatorUtils,
+    canvasHost,
+    run,
+    refreshResolution,
+    destroy,
+  }
+}

package/src/lite-test.ts

@@ -0,0 +1,160 @@
+// Dev-only smoke page for the lite 3D engine (lite-test.html → vite dev, port 12073).
+// Runs a raw `_creator`-level bundle through mountCreator with the gl-lite engine override:
+// lit/unlit materials, sun + shadows, IBL, a GLB with skeletal animation, and raycast picking.
+// The window exposes __liteStatus for the headless-Chrome check.
+
+import { mountCreator } from './createViewer'
+
+const bundle = `// preload: lit.filamat;unlit.filamat;uberarchive
+(function() {
+  const status = { frames: 0, raycast: -1, glb: 'pending', animations: [], errors: [] }
+  window.__liteStatus = status
+
+  const sceneId = _creator.createScene()
+
+  // camera: slightly above, looking down at the origin
+  const cameraId = _creator.createEntity()
+  _creator.attachCameraToAR(sceneId, cameraId, () => {})
+  _creator.setPosition(cameraId, 0, 2.2, 5)
+  _creator.setEulerAngles(cameraId, -16, 0, 0, 1)
+
+  // sun + ambient
+  const light = _creator.createEntity()
+  _creator.createSunLight(light, -0.6, -1, -0.4, 100000, 0xffffff, 1)
+  _creator.addEntityToScene(sceneId, light)
+  _creator.setDefaultIbl(sceneId, 20000)
+  _creator.setSkybox(sceneId, 0x24324e)
+
+  // --- geometry helpers ------------------------------------------------------------------------
+  const cube = (s) => {
+    const p = [], n = [], u = [], idx = []
+    const faces = [
+      [[ 1,0,0],[0,0,-1],[0,1,0]], [[-1,0,0],[0,0,1],[0,1,0]],
+      [[0, 1,0],[1,0,0],[0,0,-1]], [[0,-1,0],[1,0,0],[0,0,1]],
+      [[0,0, 1],[1,0,0],[0,1,0]], [[0,0,-1],[-1,0,0],[0,1,0]],
+    ]
+    for (let f = 0; f < 6; f++) {
+      const [nrm, ta, tb] = faces[f]
+      const base = p.length / 3
+      for (let i = 0; i < 4; i++) {
+        const a = (i === 1 || i === 2) ? 1 : -1
+        const b = (i >= 2) ? 1 : -1
+        p.push((nrm[0] + ta[0]*a + tb[0]*b) * s/2, (nrm[1] + ta[1]*a + tb[1]*b) * s/2, (nrm[2] + ta[2]*a + tb[2]*b) * s/2)
+        n.push(nrm[0], nrm[1], nrm[2])
+        u.push((a+1)/2, (b+1)/2)
+      }
+      idx.push(base, base+1, base+2, base, base+2, base+3)
+    }
+    return { p: new Float32Array(p), n: new Float32Array(n), u: new Float32Array(u), i: new Uint16Array(idx) }
+  }
+  const plane = (s) => ({
+    p: new Float32Array([-s,0,-s,  s,0,-s,  s,0,s,  -s,0,s]),
+    n: new Float32Array([0,1,0, 0,1,0, 0,1,0, 0,1,0]),
+    u: new Float32Array([0,0, 1,0, 1,1, 0,1]),
+    i: new Uint16Array([0,2,1, 0,3,2]),
+  })
+
+  // --- ground (lit, white) ---------------------------------------------------------------------
+  const groundMat = _creator.createMaterial(_creatorUtils.fetchLocal('lit.filamat'))
+  _creator.setUniformRgb(groundMat, 'baseColor', 0xdddddd)
+  _creator.setUniformFloat(groundMat, 'roughness', 0.9)
+  const g = plane(6)
+  const ground = _creator.createEntity()
+  _creator.setMesh(ground, groundMat, g.p, g.n, g.i, g.u, 0)
+  _creator.setCastShadows(ground, false)
+  _creator.addEntityToScene(sceneId, ground)
+
+  // --- spinning lit cube (red, semi-rough) -------------------------------------------------------
+  const cubeMat = _creator.createMaterial(_creatorUtils.fetchLocal('lit.filamat'))
+  _creator.setUniformRgb(cubeMat, 'baseColor', 0xdd3333)
+  _creator.setUniformFloat(cubeMat, 'roughness', 0.35)
+  _creator.setUniformFloat(cubeMat, 'metallic', 0.0)
+  const c = cube(1)
+  const box = _creator.createEntity()
+  _creator.setMesh(box, cubeMat, c.p, c.n, c.i, c.u, 0)
+  _creator.setPosition(box, -1.2, 0.8, 0)
+  _creator.addEntityToScene(sceneId, box)
+  _creator.setColliderBox(box, 0, 0, 0, 1, 1, 1)
+
+  // --- metallic cube ------------------------------------------------------------------------------
+  const metalMat = _creator.createMaterial(_creatorUtils.fetchLocal('lit.filamat'))
+  _creator.setUniformRgb(metalMat, 'baseColor', 0xccccdd)
+  _creator.setUniformFloat(metalMat, 'roughness', 0.15)
+  _creator.setUniformFloat(metalMat, 'metallic', 1.0)
+  const metal = _creator.createEntity()
+  _creator.setMesh(metal, metalMat, c.p, c.n, c.i, c.u, 0)
+  _creator.setPosition(metal, 1.2, 0.5, 0)
+  _creator.setEulerAngles(metal, 0, 30, 0, 1)
+  _creator.addEntityToScene(sceneId, metal)
+
+  // --- unlit marker -------------------------------------------------------------------------------
+  const unlitMat = _creator.createMaterial(_creatorUtils.fetchLocal('unlit.filamat'))
+  _creator.setUniformRgb(unlitMat, 'baseColor', 0x33ff88)
+  const marker = _creator.createEntity()
+  _creator.setMesh(marker, unlitMat, cube(0.25).p, cube(0.25).n, cube(0.25).i, cube(0.25).u, 0)
+  _creator.setPosition(marker, 0, 2, -1)
+  _creator.addEntityToScene(sceneId, marker)
+
+  // --- GLB with skeletal animation ---------------------------------------------------------------
+  _creatorUtils.fetch(location.origin + '/lite-test.glb', {}, (systemId) => {
+    _creator.createGlb(systemId, (entityId) => {
+      status.glb = 'loaded'
+      _creator.setGlbCulling(entityId, false)
+      _creator.setPosition(entityId, 0, 0, 1.4)
+      _creator.setScale(entityId, 0.5, 0.5, 0.5)
+      _creator.addEntityToScene(sceneId, entityId)
+      const set = _creator.getGlbClipSet(entityId)
+      const anims = set ? _creator.getClipSetInfo(set) : []
+      status.animations = anims
+      if (anims.length > 0) {   // what model.anim.play(0, { loop: true }) does
+        const a = _creator.animatorCreate(entityId)
+        const slot = _creator.animatorBind(a, set, 0, 0)
+        _creator.animatorPlay(a, slot, true, 1, 0, -1, true)
+      }
+    }, (e) => { status.glb = 'failed'; status.errors.push(String(e)) })
+  }, () => { status.glb = 'fetch-failed' })
+
+  // --- spin + probe --------------------------------------------------------------------------------
+  let angle = 0
+  _creator.setEarlyUpdate((dt) => {
+    angle += dt * 60
+    _creator.setEulerAngles(box, 0, angle, 0, 1)
+    status.frames++
+    if (status.frames === 30) {
+      // scan a screen grid — the red box has a collider, so some rays must return its entity id
+      const size = _creator.getDisplaySize()
+      const hits = new Set()
+      for (let fx = 0.05; fx < 1; fx += 0.1) {
+        for (let fy = 0.3; fy < 0.95; fy += 0.1) {
+          const hit = _creator.raycastView(size[0] * fx, size[1] * fy)
+          if (hit) hits.add(hit)
+        }
+      }
+      status.raycast = [...hits]
+      status.boxEntity = box
+      const m = new Float32Array(16)
+      _creator.getWorldMatrix(box, m)
+      status.boxWorldY = m[13]
+    }
+  })
+
+  _creator.openScene(sceneId)
+})()
+`
+
+const root = document.getElementById('root')!
+// ?engine=gl compares against the real Filament build; default is the lite engine.
+const engineParam = new URLSearchParams(location.search).get('engine')
+mountCreator(root, bundle, undefined, undefined, {
+  engine: engineParam === 'gl' ? undefined : 'gl-lite',
+  onError: (err) => {
+    ;(window as any).__liteStatus = (window as any).__liteStatus ?? {}
+    ;((window as any).__liteStatus.errors ??= []).push(err.message)
+    console.error('preview error', err)
+  },
+}).then(() => {
+  console.log('[lite-test] mounted')
+}).catch((e) => {
+  ;(window as any).__liteMountError = String(e)
+  console.error(e)
+})

package/src/main.ts

@@ -0,0 +1,77 @@
+// Scene-editor dev playground (`bun run dev` in packages/viewer, port 12073). Runs the compiled
+// scene-editor harness + demo scene bundle against an engine-only host — the manual verification
+// rig for the 3D scene editor. Defaults to the lite engine (like the editor); `?engine=gl` runs
+// Filament instead.
+//
+// Rebuild the bundle after touching packages/projects/src/scene-editor*:
+//   bun packages/projects/build.mjs   (needs chisel; LECODES_CHISEL_BIN for a local build)
+//
+// Interactions: click a HUD row = select (viewport picking is removed), drag = orbit,
+// wheel = zoom, shift+drag / middle-drag = pan (host-driven), F = focus selection.
+
+import { createHost } from "./createViewer"
+import { createBareUI } from "./ui/createBareUI"
+// @ts-ignore — built artifact (bun packages/projects/build.mjs)
+import bundle from "../../projects/out/scene-editor-dev.js?raw"
+
+const root = document.getElementById("app")!
+const hud = document.getElementById("hud")!
+
+const main = async () => {
+  const params = new URLSearchParams(location.search)
+  const filament = params.get("engine") === "gl"
+  const host = await createHost(root, {
+    engine: filament ? "gl" : "gl-lite",
+    ui: createBareUI,
+    preloads: filament ? new Set([ "lit.filamat", "unlit.filamat" ]) : new Set(),
+  })
+  // ?wire=only|overlay — the lite engine's wireframe display mode (editor host API)
+  const wire = params.get("wire")
+  if (wire === "only" || wire === "overlay") (host as any)._creator?._setWireframeMode?.(wire)
+
+  // the editor-host flow: edit flag → run the combined bundle → attach the registered handle
+  ;(globalThis as any).__lecodesSceneEdit = true
+  host.run(bundle, { onError: (e) => { hud.textContent = `error: ${e.message}` } })
+  const harness = (globalThis as any).__lecodesSceneHarness
+  const scenes = (globalThis as any).__lecodesScenes ?? []
+  if (!harness || scenes.length === 0) { hud.textContent = "bundle didn't install the harness — rebuild it (see src/main.ts)"; return }
+
+  const { nodes } = await harness.attach(scenes[scenes.length - 1])
+
+  let selected: string | null = null
+  const render = (status = "") => {
+    hud.innerHTML = ""
+    for (const name of nodes) {
+      const el = document.createElement("div")
+      el.className = "node" + (name === selected ? " sel" : "")
+      el.textContent = name
+      el.onclick = () => { selected = name; harness.select(name); render() }
+      hud.appendChild(el)
+    }
+    const hint = document.createElement("div")
+    hint.className = "hint"
+    hint.textContent = status || "click a row: select · drag: orbit · wheel: zoom · shift-drag: pan · F: focus"
+    hud.appendChild(hint)
+  }
+  render()
+
+  // fired only by plugin `editor.select` calls (viewport picking is removed)
+  harness.callbacks.onSelect = (name: string | null) => { selected = name; render() }
+
+  root.addEventListener("wheel", (e) => { e.preventDefault(); harness.zoom(Math.sign(e.deltaY)) }, { passive: false })
+  window.addEventListener("keydown", (e) => { if (e.code === "KeyF") harness.focus() })
+  // shift+drag / middle-drag pan. The capture listener swallows the pointerdown so the harness's
+  // touch system never starts its orbit track for the same drag (both would run otherwise).
+  let panning = false
+  root.addEventListener("pointerdown", (e) => {
+    if (e.shiftKey || e.button === 1) {
+      panning = true
+      e.preventDefault()
+      e.stopImmediatePropagation()
+    }
+  }, { capture: true })
+  window.addEventListener("pointermove", (e) => { if (panning && e.buttons) harness.pan(e.movementX, e.movementY) })
+  window.addEventListener("pointerup", () => { panning = false })
+}
+
+main()

package/src/sourcemapError.ts

@@ -0,0 +1,2 @@
+// Moved to viewer-lite; re-export shim.
+export * from "lecodes-viewer-lite/src/sourcemapError"