lecodes-gl-lite 2.0.0

package/src/webgl/createViewerLite.ts

@@ -0,0 +1,1627 @@
+// The lite web 3D engine: a from-scratch WebGL2 implementation of the `_creator` bridge
+// (sdk/src/bridges.d.ts) built on OGL instead of the 3.2MB Filament wasm. Same object
+// shape as viewer/createViewer.ts, so host.ts / the SDK / the touch system consume it unchanged.
+//
+// Scene semantics live in the shared, GL-free SceneCore (gl/core) — the SAME core the headless
+// renderer drives — so the pixels a human sees and the JSON an AI reads come from one state and can't
+// disagree. This file is the WebGL BACKEND for that core: it owns the OGL objects (Transforms,
+// Programs, Geometry/Mesh, Textures) keyed by the core's entity ids and reacts to the core's
+// SceneBackend hooks (build a Program on materialCreated, a Mesh on meshSet, sample a clip on
+// morphWeights, …). The scene-graph bridge methods come from core.methods; this file adds the
+// GL-only + capability methods (textures, shadows, raycast, AR throws, capture).
+//
+// Lighting follows Filament's model: photometric intensities (lux) × the default-camera exposure, the
+// published BRDF, the same neutral IBL asset (KTX cubemap + SH). See shaders.ts. Custom .mat shaders
+// run via the backend's webgl-lite JSON artifact (customMaterial.ts); a binary filamat or an
+// `unsupported` artifact falls back to unlit white + warn.
+//
+// Not implemented (honest stubs, same failure shape as the Filament web build where possible):
+// particles (warn-once no-op), AR/VR (throw / reject), Jolt physics (the core's creator-physics wasm),
+// bloom (no-op). The headless backend records those instead (recording.ts).
+
+import { Camera, Geometry, Mesh, GLTFSkin, Program, Renderer, RenderTarget, Texture, Transform, type OGLRenderingContext } from 'ogl'
+import { _fetch, getBlob, getBuffer as getFetchedBuffer, getLocalName, hasLocalBuffer, putBuffer, putLocalBuffer } from 'lecodes-web-shared/src/utils/fetch'
+import { getPlayer, removePlayers } from 'lecodes-web-shared/src/utils/mediaplayer'
+import type { CanvasHost } from 'lecodes-web-shared/src/canvas/createCanvasHost'
+import {
+  identity, intersectRayBox, intersectRaySphere, invertTRS, multiply, orthographic,
+  transformPoint, type Mat4Like,
+} from '../core/math3d'
+import {
+  EXPOSURE, depthFragment, depthVertex, gltfVertex, hexToLinearRgb, hexToLinearRgba,
+  litFragment, litVertex, shadowCatcherFragment, terrainFragment, tonemapJs, unlitBlendFragment, unlitFragment,
+  videoFragment, wireFragment,
+} from './shaders'
+import { loadIbl, type IblData } from './ibl'
+import { buildEdgeIndices, createBlackCubemap, createWhiteTexture, loadGlbLite } from './glb'
+import { buildCustomProgram, parseLiteMaterial } from './customMaterial'
+import { createEditorLayer, type EditorHandlers, type EditorLayer } from './editor'
+import { createBatcher, type Batcher } from './batching'
+import { particlesPointVertex, particlesPointFragment, particlesQuadVertex, particlesQuadFragment } from './shaders'
+import { createSceneCore, type SceneBackend, type UniformRec } from '../core/sceneCore'
+import { loadCreatorAnim } from '../core/animBridge'
+import { loadCreatorPhysics } from '../core/physicsBridge'
+import { loadCreatorParticles, type ParticleFrame } from '../core/particleBridge'
+import { MODE } from '../vendor/creator-particles/js/index'
+import { serialize as serializeScene3d } from '../core/serialize'
+import { unsupported } from '../gen/unsupported.gen'
+// The global `Handle` the contract's creators return (declared with the tree bridge): without it
+// gl.d.ts reads `Handle` as any and the `satisfies` check cannot see a creator returning a number.
+import type {} from 'lecodes-sdk/bridges/tree'
+import iblTextureUrl from '../assets/neutral_ibl128.ktx?url'
+
+// `backend` is only ever a name fragment the compiled bundle substitutes into a shader URL
+// (`<hash>_${_creator.backend}.filamat`); 'webgl-lite' selects the parsed-.mat JSON artifact
+// (sdk/compile liteMaterial.ts) this engine wraps in its own GLSL template.
+export const basePropsLite = {
+  backend: 'webgl-lite',
+}
+
+// Same shape as the full viewer's ViewerOptions (viewer/createViewer.ts) — defined locally so the
+// lite engine has no dependency on the viewer package.
+export type ViewerOptions = {
+  preloads?: Set<string>
+  /** The core 2D-canvas host (`_creatorCanvas`); lets createTextureFromCanvas read baked surfaces. */
+  canvasHost?: CanvasHost
+  /** Clear to transparent instead of the skybox color (and open the context with an alpha
+   *  channel). Capture hosts use this so PNG thumbnails composite over any page theme. */
+  transparent?: boolean
+}
+
+const FOV = 60 // vertical fov set by the native setViewport (scene.cpp) — matches the core default
+const NEAR = 0.01
+const FAR = 1000 // matches the native far plane (scene.cpp setViewport)
+
+type Collider =
+  | { type: 'box', center: number[], extent: number[] }
+  | { type: 'sphere', center: number[], radius: number }
+
+/** The OGL objects the backend keeps per core entity id. `transform.matrix` is the core entity's `m`. */
+type GlEnt = { transform: Transform, drawables: Mesh[] }
+
+type MaterialKind = 'lit' | 'unlit' | 'video' | 'shadow' | 'terrain' | 'particles' | 'particles-quad' | 'gltf' | 'custom' | 'unknown'
+
+/** The OGL objects behind one particle system (creator-particles' stream → one dynamic drawable). */
+type GlParticles = {
+  materialId: number
+  mesh: Mesh | null
+  geometry: Geometry | null
+  /** The interleaved stream buffer (points / quads / ribbon); mesh mode uses plain attributes. */
+  buffer: WebGLBuffer | null
+  version: number
+  mode: number
+}
+type GlMaterial = {
+  kind: MaterialKind
+  program: Program
+  /** custom (.mat) materials: declared parameter names — the SDK sets uniforms by the bare
+   *  parameter name, the program declares them as materialParams_<name> */
+  customParams?: Set<string>
+}
+
+// glTF ubershader parameter names (what the SDK sets on model materials) → our uniform names.
+const GLTF_UNIFORM_ALIAS: Record<string, string> = {
+  baseColorFactor: 'uBaseColorFactor',
+  metallicFactor: 'uMetallic',
+  roughnessFactor: 'uRoughness',
+  emissiveFactor: 'uEmissive',
+  baseColorMap: 'uBaseColorMap',
+  baseColorIndex: 'uBaseColorIndex',
+}
+
+export const createViewerLite = async (canvas: HTMLCanvasElement, options: ViewerOptions = {}) => {
+  const renderer = new Renderer({
+    canvas,
+    dpr: 1, // set per-resize to the host's resolution factor (devicePixelRatio × CSS zoom); see _onResize
+    alpha: options.transparent ?? false,
+    antialias: true,
+    premultipliedAlpha: true,
+    powerPreference: 'high-performance',
+    preserveDrawingBuffer: options.preloads?.has('capture') ?? false,
+  })
+  const gl = renderer.gl as OGLRenderingContext & WebGL2RenderingContext
+  renderer.autoClear = false // we clear manually (per-scene clear color, overlay depth clears)
+
+  const white = createWhiteTexture(gl)
+  const blackCube = createBlackCubemap(gl)
+
+  // The SDK resolves built-in shaders via `_creatorFetch.local("lit.filamat")` — register the
+  // names with empty payloads so fetchLocal yields a systemId whose NAME identifies the material
+  // (the lite engine picks shaders by name; it never compiles filamat packages). ALWAYS registered,
+  // never from options.preloads: a host that passes no preloads (the scene editor) must still get
+  // lit materials — an unresolved name means every material silently renders unlit. Names the
+  // Filament engine already materialized keep their real buffers (same-page engine switches).
+  for (const name of [
+    'lit.filamat', 'unlit.filamat', 'unlit-transparent.filamat', 'video.filamat', 'shadow.filamat',
+    'particles.filamat', 'particles-quad.filamat', 'terrain.filamat',
+  ]) {
+    if (!hasLocalBuffer(name)) putLocalBuffer(name, new ArrayBuffer(0))
+  }
+
+  // ---- shared per-frame lighting uniforms (every lit/gltf/shadow program references these) ------
+  const sceneUniforms = {
+    sunDirection: { value: [0, -1, 0] as number[] },
+    sunColorIntensity: { value: [1, 1, 1, 0] as number[] },
+    iblLuminance: { value: 0 },
+    // NOTE: uniform ARRAYS must be plain JS arrays — OGL's name-component resolution drops typed
+    // arrays for `iblSH[0]`-style active uniforms.
+    iblSH: { value: new Array(27).fill(0) as number[] },
+    envMap: { value: blackCube as Texture },
+    envMapMaxLod: { value: 0 },
+    shadowMap: { value: white as Texture },
+    shadowEnabled: { value: 0 },
+    shadowMapSize: { value: 1024 },
+    shadowMatrix: { value: identity() },
+    exposure: { value: EXPOSURE },
+  }
+  // getUserTime() for custom .mat materials: [seconds, fract(seconds), 0, 0], updated per frame.
+  const userTime = { value: [0, 0, 0, 0] as number[] }
+
+  // The same neutral IBL the Filament build ships (KTX cubemap + SH metadata).
+  let ibl: IblData | null = null
+  const iblReady = fetch(iblTextureUrl)
+    .then((r) => r.arrayBuffer())
+    .then((buf) => {
+      ibl = loadIbl(gl, buf)
+      sceneUniforms.envMap.value = ibl.cubemap
+      sceneUniforms.envMapMaxLod.value = ibl.maxLod
+      sceneUniforms.iblSH.value = Array.from(ibl.sh)
+    })
+    .catch((e) => console.warn('[viewer-lite] IBL load failed:', e))
+
+  // ---- WebGL backend state (GL objects keyed by the core's ids) ---------------------------------
+  const glEnts = new Map<number, GlEnt>()
+  const sceneRoots = new Map<number, Transform>()
+  const sceneColliders = new Map<number, Map<number, Collider>>() // web CPU raycast (not in the core)
+  const glMaterials = new Map<number, GlMaterial>()
+  const glTextures = new Map<number, Texture>()
+  const glParticles = new Map<number, GlParticles>()
+  /** viewportHeightPx / (2 tan(fov/2)) — point sprites' world-space diameter (particles.mat's material global 3). */
+  const perspScale = { value: 1 }
+  /** CPU copies of raw-pixel textures (createTexturePixels) for sub-rectangle updates. */
+  const pixelTextures = new Map<number, { rgba: Uint8Array, width: number, height: number, channels: number }>()
+  let nextTexture = 1
+  let castShadowsGlobal = true
+  let receiveShadowsGlobal = true
+  /** Engine-side editor layer (grid/outline/gizmo/picking) — created on _editorConnect, editor-only. */
+  let editorLayer: EditorLayer | null = null
+  const activeVideoTextures: { video: HTMLVideoElement, texture: Texture, lastTime: number }[] = []
+
+  const glEnt = (id: number): GlEnt => {
+    let g = glEnts.get(id)
+    if (!g) {
+      const transform = new Transform()
+      transform.matrixAutoUpdate = false
+      ;(transform as any)._entId = id
+      g = { transform, drawables: [] }
+      glEnts.set(id, g)
+    }
+    return g
+  }
+
+  // ---- materials --------------------------------------------------------------------------------
+
+  // `blend` splits the two unlit materials: unlit.filamat is opaque (depth-written, no blending),
+  // unlit-transparent.filamat is premultiplied alpha. Everything else ignores it.
+  const makeMaterial = (kind: MaterialKind, blend = false): GlMaterial => {
+    let program: Program
+    if (kind === 'lit') {
+      program = new Program(gl, {
+        vertex: litVertex,
+        fragment: litFragment,
+        uniforms: {
+          ...sceneUniforms,
+          // factor×map identity defaults — color alone or map alone shows through unchanged
+          baseColor: { value: [1, 1, 1] },
+          baseColorMap: { value: white },
+          roughness: { value: 0 },
+          metallic: { value: 0 },
+        } as any,
+      })
+    } else if (kind === 'terrain') {
+      // terrain.mat's twin (shaders.ts terrainFragment): the SDK primes every scalar; samplers start white
+      program = new Program(gl, {
+        vertex: litVertex,
+        fragment: terrainFragment,
+        uniforms: {
+          ...sceneUniforms,
+          control: { value: white }, albedo0: { value: white }, albedo1: { value: white }, albedo2: { value: white }, albedo3: { value: white },
+          normals01: { value: white }, normals23: { value: white },
+          tiling: { value: [8, 8, 8, 8] }, roughness: { value: [1, 1, 1, 1] }, normalScale: { value: [0, 0, 0, 0] }, triplanar: { value: [0, 0, 0, 0] },
+          gridSize: { value: [2, 2] }, cellSize: { value: 1 }, tint: { value: [1, 1, 1] },
+        } as any,
+      })
+    } else if (kind === 'video') {
+      program = new Program(gl, {
+        vertex: litVertex,
+        fragment: videoFragment,
+        // shadowMatrix: the shared vertex shader declares it even though video ignores shadows.
+        uniforms: { baseColorMap: { value: white }, shadowMatrix: sceneUniforms.shadowMatrix } as any,
+      })
+    } else if (kind === 'shadow') {
+      program = new Program(gl, {
+        vertex: litVertex,
+        fragment: shadowCatcherFragment,
+        uniforms: { ...sceneUniforms, color: { value: [0, 0, 0, 0.66] } } as any,
+        transparent: true,
+      })
+      program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+    } else if (kind === 'particles' || kind === 'particles-quad') {
+      // particles.mat / particles-quad.mat twins (shaders.ts): the SDK's Material.particles primes
+      // every look knob; the stream carries the per-vertex rest. Premultiplied, no depth write.
+      const quad = kind === 'particles-quad'
+      program = new Program(gl, {
+        vertex: quad ? particlesQuadVertex : particlesPointVertex,
+        fragment: quad ? particlesQuadFragment : particlesPointFragment,
+        uniforms: {
+          baseColorMap: { value: white }, sheetSize: { value: [1, 1] },
+          emissive: { value: 0 }, additive: { value: 0 }, softness: { value: 0 }, depthFade: { value: 0 },
+          ...(quad
+            ? { mode: { value: 0 }, stretch: { value: 0 }, emissiveMap: { value: white }, emissiveColor: { value: [0, 0, 0] }, frameBlend: { value: 0 } }
+            : { perspScale }),
+        } as any,
+        transparent: true,
+        depthWrite: false,
+        cullFace: false,
+      } as any)
+      program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+    } else {
+      // unlit + unknown custom shaders (Material.load of a .filamat can't run here)
+      program = new Program(gl, {
+        vertex: litVertex,
+        fragment: blend ? unlitBlendFragment : unlitFragment,
+        uniforms: {
+          baseColor: { value: [1, 1, 1, 1] },
+          baseColorMap: { value: white },
+          shadowMatrix: sceneUniforms.shadowMatrix,
+        } as any,
+        transparent: blend,
+      })
+      if (blend) program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA)
+    }
+    return { kind, program }
+  }
+
+  // Custom .mat material: the fetched buffer is the backend's webgl-lite JSON artifact (parsed
+  // .mat) — wrap its fragment body in the lite GLSL template. Null → caller falls back to unlit.
+  const makeCustomMaterial = (systemId: number): GlMaterial | null => {
+    const artifact = parseLiteMaterial(getFetchedBuffer(systemId))
+    if (!artifact) return null
+    if (artifact.unsupported) {
+      console.warn(`[viewer-lite] custom material not supported in lite (${artifact.unsupported}) — rendering unlit`)
+      return null
+    }
+    if (artifact.hasVertexBlock) {
+      console.warn('[viewer-lite] custom material has a vertex{} block — the custom vertex stage is ignored in lite')
+    }
+    const spec = buildCustomProgram(artifact)
+    if (!spec) return null
+
+    const uniforms: Record<string, { value: any }> = spec.needsSceneUniforms
+      ? { ...sceneUniforms, userTime }
+      : { shadowMatrix: sceneUniforms.shadowMatrix, userTime }
+    for (const u of spec.uniforms) uniforms[u.key] = { value: u.value === 'texture' ? white : u.value }
+
+    const opaque = artifact.blending === 'opaque' || artifact.blending === 'masked'
+    const program = new Program(gl, {
+      vertex: litVertex,
+      fragment: spec.fragment,
+      uniforms: uniforms as any,
+      transparent: !opaque,
+      cullFace: artifact.doubleSided || artifact.culling === 'none' ? false
+        : artifact.culling === 'front' ? gl.FRONT : gl.BACK,
+      depthWrite: artifact.depthWrite,
+    } as any)
+    if (!gl.getProgramParameter(program.program, gl.LINK_STATUS)) {
+      console.warn('[viewer-lite] custom material failed to compile — rendering unlit')
+      return null
+    }
+    if (!opaque) program.setBlendFunc(gl.ONE, artifact.blending === 'add' ? gl.ONE : gl.ONE_MINUS_SRC_ALPHA)
+    return { kind: 'custom', program, customParams: spec.paramNames }
+  }
+
+  // Build a GlMaterial from a shader NAME (createMaterial / builtinMaterial via the materialCreated hook).
+  // systemId is present for fetched shaders (needed to load a custom .mat), absent for a built-in one.
+  const buildProgramFor = (name: string, systemId?: number): GlMaterial => {
+    const kind: MaterialKind =
+      name.startsWith('lit') ? 'lit'
+      : name.startsWith('unlit') ? 'unlit'
+      : name.startsWith('video') ? 'video'
+      : name.startsWith('shadow') ? 'shadow'
+      : name.startsWith('terrain') ? 'terrain'
+      : name.startsWith('particles-quad') ? 'particles-quad'
+      : name.startsWith('particles') ? 'particles'
+      : 'unknown'
+    if (kind === 'unknown' && systemId !== undefined) {
+      const custom = makeCustomMaterial(systemId)
+      if (custom) return custom
+      console.warn(`[viewer-lite] custom shader can't run here (material "${name || systemId}") — rendering unlit`)
+    }
+    // 'unlit-transparent' is the same shader family (kind 'unlit'), drawn blended instead of opaque.
+    return makeMaterial(kind, name.startsWith('unlit-transparent'))
+  }
+
+  const materialUniform = (rec: GlMaterial, name: string): { value: any } => {
+    const key = rec.kind === 'gltf' ? (GLTF_UNIFORM_ALIAS[name] ?? name)
+      : rec.customParams?.has(name) ? `materialParams_${name}`
+      : name
+    const uniforms = rec.program.uniforms as Record<string, { value: any }>
+    if (!uniforms[key]) uniforms[key] = { value: 0 }
+    return uniforms[key]
+  }
+
+  // React to a core uniform change (semantic value) by converting + setting it on the Program. Texture
+  // uniforms are finalized by setUniformTexture (which also carries wrap modes); here we bind by id.
+  const applyUniform = (materialId: number, uniform: string, u: UniformRec): void => {
+    const rec = glMaterials.get(materialId)
+    if (!rec) return
+    // Legacy bundles cleared the lit/unlit map with `useBaseColorMap = false` — the factor×map
+    // shaders dropped that flag, so translate the clear into the white-texture reset it meant
+    // (custom materials may declare their own useBaseColorMap; leave those alone).
+    if (uniform === 'useBaseColorMap' && (rec.kind === 'lit' || rec.kind === 'unlit')) {
+      if (u.kind === 'bool' && !u.v) {
+        const map = materialUniform(rec, 'baseColorMap')
+        if (map.value instanceof Texture) map.value = white
+      }
+      return
+    }
+    const target = materialUniform(rec, uniform)
+    switch (u.kind) {
+      case 'rgb': {
+        const [r, g, b] = hexToLinearRgb(u.v)
+        if (Array.isArray(target.value) && target.value.length === 4) target.value = [r, g, b, target.value[3]]
+        else target.value = [r, g, b]
+        break
+      }
+      case 'rgba': {
+        // A vec3 uniform (lit baseColor, terrain tint) takes the colour and drops the alpha, like
+        // creator-gl's FLOAT3 branch: every SDK colour is '#rrggbbaa' now, opaque or not.
+        const rgba = hexToLinearRgba(u.v)
+        target.value = Array.isArray(target.value) && target.value.length === 3 ? rgba.slice(0, 3) : rgba
+        break
+      }
+      case 'float': target.value = u.v; break
+      case 'bool': target.value = u.v ? 1 : 0; break
+      case 'array': target.value = Float32Array.from(u.v); break
+      case 'texture': { const tex = glTextures.get(u.v); if (tex) target.value = tex; break }
+      case 'null': if (target.value instanceof Texture) target.value = white; break
+    }
+  }
+
+  // receiveShadows is per-drawable, programs are per-material — resolve at draw time.
+  const wireReceiveShadows = (mesh: Mesh, rec: GlMaterial): void => {
+    if (rec.kind !== 'lit' && rec.kind !== 'gltf' && rec.kind !== 'shadow' && rec.kind !== 'custom') return
+    mesh.onBeforeRender(() => {
+      const uniforms = mesh.program.uniforms as any
+      if (uniforms.shadowEnabled) {
+        const on = sceneUniforms.shadowEnabled.value === 1 && (mesh as any)._receiveShadows !== false
+        uniforms.shadowEnabled = on ? sceneUniforms.shadowEnabled : { value: 0 }
+      }
+    })
+  }
+
+  // Build the OGL Mesh for a primitive setMesh (core already recorded bounds + kind). The core always
+  // records the mesh; if the material never resolved to a program we skip the drawable (native/web).
+  const buildMesh = (entityId: number, materialId: number, arrays: {
+    vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, colors?: Uint8Array,
+  }, meshType: number): void => {
+    const rec = glMaterials.get(materialId)
+    if (!rec) return
+    const { vertices, normals, indices, uv, colors } = arrays
+    const geometry = new Geometry(gl, {
+      position: { size: 3, data: Float32Array.from(vertices) },
+      normal: { size: 3, data: normals.length ? Float32Array.from(normals) : new Float32Array(vertices.length) },
+      uv: { size: 2, data: uv.length ? Float32Array.from(uv) : new Float32Array((vertices.length / 3) * 2) },
+      // the vertex colours as 0..1 floats (Geometry.colors is bytes); a program that declares no
+      // `color` attribute simply ignores them — lite's custom materials have no getColor() yet
+      ...(colors && colors.length ? { color: { size: 4, data: Float32Array.from(colors, (v) => v / 255) } } : {}),
+      index: { data: Uint16Array.from(indices) },
+    } as any)
+    geometry.computeBoundingBox()
+    const mode = meshType === 1 ? gl.LINES : meshType === 2 ? gl.POINTS : gl.TRIANGLES
+    const mesh = new Mesh(gl, { geometry, program: rec.program, mode })
+    mesh.matrixAutoUpdate = false
+    ;(mesh as any)._entId = entityId
+    ;(mesh as any)._castShadows = castShadowsGlobal
+    ;(mesh as any)._receiveShadows = receiveShadowsGlobal
+    wireReceiveShadows(mesh, rec)
+    const g = glEnt(entityId)
+    for (const d of g.drawables) {
+      g.transform.removeChild(d) // native rebuilds the renderable
+      const wire = wireMeshes.get(d) as any
+      if (wire) { wire.setParent(null as any); wireMeshes.delete(d) }
+    }
+    g.drawables = [mesh]
+    g.transform.addChild(mesh)
+  }
+
+  // Stage 2 of GLB load (the core built the structure entities): run OGL's GLTFLoader, then adopt the
+  // loader's node Transforms AS this GLB's entities (rebindMatrix) so animation/skinning — which the
+  // loader binds to those transforms — keep working, and attach the drawable meshes under them.
+  const attachGlb = async (systemId: number, rootId: number, entIds: number[]): Promise<void> => {
+    const buf = getFetchedBuffer(systemId)
+    let result
+    try {
+      result = await loadGlbLite(gl, buf!, sceneUniforms, white)
+    } catch (e) {
+      // Honest degrade: the core's structure entities (hierarchy, bounds, animation clocks) stay —
+      // this model just gets no drawables. A bad/unsupported GLB must not take the whole run down.
+      console.warn(`[viewer-lite] GLB "${getLocalName(systemId) ?? systemId}" drawables failed to load:`,
+        e instanceof Error ? e.message : e)
+      return
+    }
+
+    result.nodes.forEach((node: any, i: number) => {
+      const coreId = entIds[i]
+      if (coreId === undefined) return
+      const g = glEnt(coreId)
+      g.transform.setParent(null as any) // drop the gl-free placeholder transform
+      core.rebindMatrix(coreId, node.matrix as unknown as Mat4Like)
+      node.matrixAutoUpdate = false
+      node._entId = coreId
+      g.transform = node
+      g.drawables = []
+      for (const child of node.children as any[]) {
+        if (child.draw) {
+          child.matrixAutoUpdate = false
+          child._entId = coreId
+          child._castShadows = castShadowsGlobal
+          child._receiveShadows = receiveShadowsGlobal
+          g.drawables.push(child)
+        }
+      }
+    })
+    // The loader parents child nodes under parent nodes already; parent its scene roots under the
+    // model-root entity's transform so the whole model moves with the root.
+    for (const lr of result.roots as any[]) lr.setParent(glEnt(rootId).transform)
+  }
+
+  /** Skins cloned during the current `cloneEntity`, still pointing at the SOURCE's joints — the
+   *  clones of those joints do not exist yet when their mesh is cloned (pre-order). `subtreeCloned`
+   *  re-points them once the whole subtree is there. */
+  const pendingSkinClones: GLTFSkin[] = []
+  const cloneDrawables = (sourceId: number, cloneId: number): void => {
+    const src = glEnt(sourceId)
+    const copy = glEnt(cloneId)
+    for (const d of src.drawables as any[]) {
+      const mesh = d instanceof GLTFSkin
+        ? new GLTFSkin(gl, { skeleton: d.skeleton, geometry: d.geometry, program: d.program, mode: d.mode })
+        : new Mesh(gl, { geometry: d.geometry, program: d.program, mode: d.mode })
+      if (mesh instanceof GLTFSkin) pendingSkinClones.push(mesh)
+      ;(mesh as any)._entId = cloneId
+      ;(mesh as any)._castShadows = d._castShadows
+      ;(mesh as any)._receiveShadows = d._receiveShadows
+      mesh.frustumCulled = d.frustumCulled
+      mesh.matrixAutoUpdate = false
+      copy.drawables.push(mesh)
+      copy.transform.addChild(mesh)
+    }
+  }
+
+  /** A clone's skin must follow the CLONE's joints: the Animator on the clone writes those, while
+   *  the source's (a `defineScene` model template, never in a scene) stay at rest — sharing the
+   *  source skeleton drew every cloned character in its bind pose. Each joint is swapped for its
+   *  clone's Transform with the same inverse bind matrix; a joint outside the cloned subtree keeps
+   *  the source's. Native gets this from gltfio's createInstance (one skeleton per instance). */
+  const rebindClonedSkins = (map: ReadonlyMap<number, number>): void => {
+    for (const mesh of pendingSkinClones.splice(0) as any[]) {
+      const joints = (mesh.skeleton.joints as any[]).map((j) => {
+        const cloneId = j._entId === undefined ? undefined : map.get(j._entId)
+        if (cloneId === undefined) return j
+        const t = glEnt(cloneId).transform as any
+        t.bindInverse = j.bindInverse
+        return t
+      })
+      mesh.skeleton = { ...mesh.skeleton, joints }
+    }
+  }
+
+  // ---- wireframe (editor viewport display modes — HOST API, not part of the bridge ABI) ---------
+  // A gl.LINES companion mesh per triangle drawable: unique-edge indices (buildEdgeIndices) over the
+  // SAME vertex data (shared GPU buffers when already uploaded), drawn with a solid-color program.
+  // 'overlay' keeps the shaded pass and polygon-offsets its fill so the lines win the depth tie;
+  // 'only' hides the shaded drawables. Existing LINES/POINTS content (grid, path lines) stays as-is.
+  // Companions are created lazily and re-synced every frame while a wire mode is active, so
+  // drawables that appear later (live patches, async GLB loads, clones) pick theirs up.
+  type WireframeMode = 'off' | 'overlay' | 'only'
+  let wireframeMode: WireframeMode = 'off'
+
+  const wireColor = { value: [0.05, 0.06, 0.08] as number[] }
+  const wireProgram = new Program(gl, {
+    vertex: litVertex,
+    fragment: wireFragment,
+    uniforms: { uWireColor: wireColor, shadowMatrix: sceneUniforms.shadowMatrix } as any,
+  })
+  const wireSkinProgram = new Program(gl, {
+    vertex: gltfVertex('HAS_SKIN'),
+    fragment: wireFragment,
+    uniforms: {
+      uWireColor: wireColor,
+      shadowMatrix: sceneUniforms.shadowMatrix,
+      boneTexture: { value: white },
+      boneTextureSize: { value: 4 },
+    } as any,
+  })
+
+  const wireGeometries = new WeakMap<object, Geometry>() // triangle geometry → LINES geometry
+  const wireMeshes = new WeakMap<object, Mesh>()         // drawable → its wire companion
+
+  const wireGeometryFor = (src: any): Geometry => {
+    let g = wireGeometries.get(src)
+    if (!g) {
+      const attrs: Record<string, any> = {}
+      for (const [ name, a ] of Object.entries<any>(src.attributes)) {
+        if (name === 'index') continue
+        // Share the source attribute's CPU data AND (when already uploaded) its GPU buffer;
+        // stride/offset carry over for interleaved glTF attributes.
+        attrs[name] = {
+          size: a.size, data: a.data, type: a.type, normalized: a.normalized,
+          stride: a.stride, offset: a.offset, buffer: a.buffer, count: a.count,
+        }
+      }
+      const position = src.attributes.position
+      const vertexCount = position ? (position.count ?? position.data.length / position.size) : 0
+      attrs.index = { data: buildEdgeIndices(src.attributes.index?.data, vertexCount) }
+      g = new Geometry(gl, attrs)
+      wireGeometries.set(src, g)
+    }
+    return g
+  }
+
+  const ensureWireMesh = (d: any): Mesh | null => {
+    let wire = wireMeshes.get(d) as any
+    if (wire) return wire
+    if (!d.parent || !d.geometry?.attributes?.position) return null
+    const geometry = wireGeometryFor(d.geometry)
+    wire = d instanceof GLTFSkin
+      ? new GLTFSkin(gl, { skeleton: d.skeleton, geometry, program: wireSkinProgram, mode: gl.LINES })
+      : new Mesh(gl, { geometry, program: wireProgram, mode: gl.LINES })
+    wire.frustumCulled = false
+    wire.matrixAutoUpdate = false
+    wire.matrix.copy(d.matrix)
+    wire._entId = d._entId
+    wire._castShadows = false
+    wire._receiveShadows = false
+    wire.setParent(d.parent)
+    wireMeshes.set(d, wire)
+    touchGraph()
+    return wire
+  }
+
+  const updateWireframe = (): void => {
+    for (const g of glEnts.values()) {
+      for (const d of g.drawables as any[]) {
+        if (d.mode !== gl.TRIANGLES) continue
+        if (wireframeMode === 'off') {
+          d.visible = true
+          const wire = wireMeshes.get(d) as any
+          if (wire) wire.visible = false
+        } else {
+          const wire = ensureWireMesh(d) as any
+          d.visible = wireframeMode === 'overlay'
+          if (wire) wire.visible = true
+        }
+      }
+    }
+  }
+
+  const updateVideoTextures = (): void => {
+    for (const v of activeVideoTextures) {
+      if (v.video.videoWidth === 0 || v.video.currentTime === v.lastTime) continue
+      v.texture.image = v.video as any
+      ;(v.texture as any).needsUpdate = true
+      v.lastTime = v.video.currentTime
+    }
+  }
+
+  // ---- render loop ------------------------------------------------------------------------------
+
+  const camera = new Camera(gl, { fov: FOV, near: NEAR, far: FAR, aspect: 1 })
+  camera.matrixAutoUpdate = false
+
+  let sceneOpened = false
+  let lastTime = 0
+  let lastAspect = 0
+  // last projection pushed to the OGL camera — the scene's own (setCameraProjection) or the defaults
+  let lastFov = FOV, lastNear = NEAR, lastFar = FAR
+  // Resolution factor (devicePixelRatio × CSS zoom) the backing store renders at, set by _onResize.
+  // The bridge's screen-space contract is LOGICAL px, so getViewRay scales its inputs up to backing
+  // px by this factor and getDisplaySize reports the logical size. See docs/simulator-plan.md phase 3.
+  let resFactor = 1
+
+  // Shadow pass resources (lazy)
+  let shadowTarget: RenderTarget | null = null
+  let shadowMapSize = 0
+  const depthProgram = new Program(gl, {
+    vertex: depthVertex(false),
+    fragment: depthFragment,
+    uniforms: { modelMatrix: { value: identity() }, shadowViewProjection: { value: identity() } } as any,
+    cullFace: gl.FRONT, // reduces acne on closed meshes
+  })
+  const depthSkinProgram = new Program(gl, {
+    vertex: depthVertex(true),
+    fragment: depthFragment,
+    uniforms: {
+      modelMatrix: { value: identity() },
+      shadowViewProjection: { value: identity() },
+      boneTexture: { value: white },
+      boneTextureSize: { value: 4 },
+    } as any,
+    cullFace: gl.FRONT,
+  })
+  // the batches' depth program: the world matrix is the instance stream (batching.ts)
+  const depthInstancedProgram = new Program(gl, {
+    vertex: depthVertex(false, true),
+    fragment: depthFragment,
+    uniforms: { shadowViewProjection: { value: identity() } } as any,
+    cullFace: gl.FRONT,
+  })
+
+  // One batcher per scene root (the main scene, each overlay): its batches persist across frames,
+  // `collect` refreshes them from the graph, the passes draw from them. See batching.ts.
+  const batchers = new Map<Transform, Batcher>()
+  let batchingEnabled = true
+  const batcherFor = (root: Transform): Batcher => {
+    let b = batchers.get(root)
+    if (!b) { b = createBatcher(gl, renderer); b.setEnabled(batchingEnabled); batchers.set(root, b) }
+    return b
+  }
+  // The scene-graph mutation counter the batchers key their graph walk on. Every path that moves
+  // a node, re-parents it, shows/hides it or changes what it draws bumps it — the core's backend
+  // hooks cover the SDK, physics and animation; the host bumps for its own drawable changes
+  // (GLB attach, clones, particles, wireframe companions, flags). A frame whose counter didn't
+  // move skips the 57 k-node traversal entirely.
+  let graphVersion = 0
+  const touchGraph = (): void => { graphVersion++ }
+  /** OGL's world-matrix pass is a full recursive walk too — run it per root only when the graph
+   *  moved since that root's last pass (the dirty flags it propagates were all set through
+   *  `touchGraph`'s callers). */
+  const worldPassVersion = new Map<Transform, number>()
+  const updateWorld = (root: Transform): void => {
+    if (worldPassVersion.get(root) === graphVersion) return
+    root.updateMatrixWorld()
+    worldPassVersion.set(root, graphVersion)
+  }
+  /** Draw a scene root through the batcher with an arbitrary camera (the editor's preview inset
+   *  reuses it — the main frame's shadow map / lighting uniforms stay as set). `force` re-walks
+   *  the graph: the preview hides drawables behind the counter's back. */
+  const renderScene = (root: Transform, cam: Camera, force = false): void => {
+    const b = batcherFor(root)
+    updateWorld(root)
+    b.collect(root, cam, true, graphVersion, force)
+    b.drawMain(cam, sceneUniforms.shadowEnabled)
+    if (force) touchGraph()   // the next main frame re-walks too (the hidden drawables come back)
+  }
+
+  /** The visible sun light entity that resolves to this scene, if any. */
+  const findSun = (sceneId: number) => {
+    for (const [id, e] of core.entities) {
+      if (e.light && core.methods.isVisible(id) && core.sceneOf(id)?.id === sceneId) return e.light
+    }
+    return null
+  }
+
+  const collectMeshes = (root: Transform): Mesh[] => {
+    const out: Mesh[] = []
+    root.traverse((node: any) => {
+      if (!node.visible) return true
+      if (node.draw) out.push(node)
+      return false
+    })
+    return out
+  }
+
+  const renderShadowPass = (root: Transform, sun: NonNullable<ReturnType<typeof findSun>>): void => {
+    const size = sun.shadowsQuality >= 3 ? 4096 : sun.shadowsQuality >= 2 ? 2048 : 1024
+    if (!shadowTarget || shadowMapSize !== size) {
+      shadowTarget = new RenderTarget(gl, { width: size, height: size, depthTexture: true })
+      shadowMapSize = size
+    }
+
+    // Casters: the walk's caster singles (every hierarchy-visible one, not only the camera-visible —
+    // a tree behind the camera still shadows the view) + the batches' `all` streams.
+    const batcher = batcherFor(root)
+    const meshes = batcher.casterSingles
+
+    // Fit an ortho frustum around the casters along the sun direction: the singles' transformed
+    // AABB corners + the batches' cached world bounds.
+    const min = [ Infinity, Infinity, Infinity ], max = [ -Infinity, -Infinity, -Infinity ]
+    const corner: number[] = [0, 0, 0]
+    for (const mesh of meshes as any[]) {
+      const g = mesh.geometry
+      if (!g.bounds) g.computeBoundingBox()
+      if (!g.bounds || !isFinite(g.bounds.min.x)) continue
+      const w = mesh.worldMatrix
+      for (let i = 0; i < 8; i++) {
+        transformPoint(corner, w,
+          i & 1 ? g.bounds.max.x : g.bounds.min.x,
+          i & 2 ? g.bounds.max.y : g.bounds.min.y,
+          i & 4 ? g.bounds.max.z : g.bounds.min.z, 1)
+        for (let k = 0; k < 3; k++) { if (corner[k] < min[k]) min[k] = corner[k]; if (corner[k] > max[k]) max[k] = corner[k] }
+      }
+    }
+    batcher.casterBounds(min, max)
+    if (!isFinite(min[0])) { sceneUniforms.shadowEnabled.value = 0; return }
+    const [ minX, minY, minZ ] = min, [ maxX, maxY, maxZ ] = max
+
+    const cx = (minX + maxX) / 2, cy = (minY + maxY) / 2, cz = (minZ + maxZ) / 2
+    const radius = Math.max(0.5, Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2)
+
+    // Light view: looking along the sun direction at the caster bounds center.
+    let dx = sun.direction[0], dy = sun.direction[1], dz = sun.direction[2]
+    const dl = Math.hypot(dx, dy, dz) || 1
+    dx /= dl; dy /= dl; dz /= dl
+    const eye = [cx - dx * radius * 2, cy - dy * radius * 2, cz - dz * radius * 2]
+    // Build an orthonormal basis (z = -dir → light looks down +dir).
+    const zx = -dx, zy = -dy, zz = -dz
+    const upY = Math.abs(dy) > 0.99 ? [1, 0, 0] : [0, 1, 0]
+    let xx = upY[1] * zz - upY[2] * zy, xy = upY[2] * zx - upY[0] * zz, xz = upY[0] * zy - upY[1] * zx
+    const xl = Math.hypot(xx, xy, xz) || 1; xx /= xl; xy /= xl; xz /= xl
+    const yx = zy * xz - zz * xy, yy = zz * xx - zx * xz, yz = zx * xy - zy * xx
+    // View matrix = inverse of the light's world matrix (rigid).
+    const view = new Float32Array(16)
+    view[0] = xx; view[4] = xy; view[8] = xz
+    view[1] = yx; view[5] = yy; view[9] = yz
+    view[2] = zx; view[6] = zy; view[10] = zz
+    view[12] = -(xx * eye[0] + xy * eye[1] + xz * eye[2])
+    view[13] = -(yx * eye[0] + yy * eye[1] + yz * eye[2])
+    view[14] = -(zx * eye[0] + zy * eye[1] + zz * eye[2])
+    view[15] = 1
+    const proj = orthographic(-radius, radius, -radius, radius, 0.05, radius * 4)
+    const viewProj = multiply(new Float32Array(16), proj, view)
+
+    depthProgram.uniforms.shadowViewProjection.value = viewProj
+    depthSkinProgram.uniforms.shadowViewProjection.value = viewProj
+    depthInstancedProgram.uniforms.shadowViewProjection.value = viewProj
+    sceneUniforms.shadowMatrix.value = viewProj
+    sceneUniforms.shadowMap.value = shadowTarget.depthTexture
+    sceneUniforms.shadowMapSize.value = size
+    sceneUniforms.shadowEnabled.value = 1
+
+    renderer.bindFramebuffer(shadowTarget)
+    renderer.setViewport(size, size)
+    gl.clearColor(1, 1, 1, 1)
+    renderer.enable(gl.DEPTH_TEST)
+    renderer.setDepthMask(true)
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+
+    const identityMat = identity()
+    for (const mesh of meshes as any[]) {
+      const isSkin = mesh instanceof GLTFSkin
+      const program = isSkin ? depthSkinProgram : depthProgram
+      const original = mesh.program
+      program.uniforms.modelMatrix.value = isSkin ? identityMat : mesh.worldMatrix
+      mesh.program = program
+      mesh.draw({})
+      mesh.program = original
+    }
+    batcher.drawShadow(depthInstancedProgram)
+    renderer.bindFramebuffer({ buffer: null } as any)
+  }
+
+  const stepFrame = (nowMs: number): void => {
+    let dt = lastTime === 0 ? 0 : (nowMs - lastTime) / 1000
+    if (dt > 0.05) dt = 0.05
+    lastTime = nowMs
+    const t = nowMs / 1000
+    userTime.value[0] = t
+    userTime.value[1] = t - Math.floor(t)
+    // The core runs early update → physics → animators (joint writes + morphWeights) → late update.
+    core.tick(dt)
+  }
+
+  const syncCamera = (sceneId: number): void => {
+    const aspect = canvas.width / Math.max(1, canvas.height)
+    const { fov, near, far } = core.projectionOf(sceneId)
+    perspScale.value = Math.max(1, canvas.height) / (2 * Math.tan((fov * Math.PI) / 360))
+    if (aspect !== lastAspect || fov !== lastFov || near !== lastNear || far !== lastFar) {
+      lastAspect = aspect
+      lastFov = fov; lastNear = near; lastFar = far
+      camera.perspective({ fov, aspect, near, far })
+    }
+    const camId = core.scenes.get(sceneId)?.camera
+    const world = camId !== undefined ? core.worldMatrix(camId) : identity()
+    for (let i = 0; i < 16; i++) (camera.matrix as any)[i] = world[i]
+    camera.worldMatrixNeedsUpdate = true
+  }
+
+  const renderFrame = (nowMs: number): boolean => {
+    const sceneId = core.activeSceneId()
+    const scene = core.scenes.get(sceneId)
+    const root = sceneRoots.get(sceneId)
+    if (!scene || !root) return false
+    stepFrame(nowMs)
+    updateVideoTextures()
+    syncCamera(sceneId)
+
+    // Wireframe companions track late-arriving drawables; polygon offset pushes the shaded fill
+    // back so overlay lines win the depth tie (fill-only state — lines/points are unaffected, and
+    // during the shadow pass it just adds a hair of depth bias).
+    if (wireframeMode !== 'off') {
+      updateWireframe()
+      gl.enable(gl.POLYGON_OFFSET_FILL)
+      gl.polygonOffset(1, 1)
+    } else {
+      gl.disable(gl.POLYGON_OFFSET_FILL)
+    }
+
+    // Sun + shadows. The batcher walks the graph once here; the shadow pass and the main pass
+    // both draw from what it collected.
+    updateWorld(root)
+    const batcher = batcherFor(root)
+    batcher.collect(root, camera, true, graphVersion)
+    const sun = findSun(sceneId)
+    if (sun) {
+      // Native passes HEX_TO_RGB straight to LightManager::Builder::color (linear) — no sRGB decode.
+      const r = ((sun.color >>> 16) & 0xff) / 255, g = ((sun.color >>> 8) & 0xff) / 255, b = (sun.color & 0xff) / 255
+      sceneUniforms.sunDirection.value = sun.direction as unknown as number[]
+      sceneUniforms.sunColorIntensity.value = [r, g, b, sun.intensity]
+      if (sun.shadowsQuality > 0) renderShadowPass(root, sun)
+      else sceneUniforms.shadowEnabled.value = 0
+    } else {
+      sceneUniforms.sunColorIntensity.value = [1, 1, 1, 0]
+      sceneUniforms.shadowEnabled.value = 0
+    }
+    sceneUniforms.iblLuminance.value = scene.ibl ?? 0
+
+    // Skybox clear color: native treats the hex as a LINEAR color rendered through the tonemapper;
+    // the default (no setSkybox) is Filament's default skybox color.
+    const clear = scene.skybox !== undefined
+      ? [tonemapJs(((scene.skybox >>> 16) & 0xff) / 255), tonemapJs(((scene.skybox >>> 8) & 0xff) / 255), tonemapJs((scene.skybox & 0xff) / 255)]
+      : [tonemapJs(0.1), tonemapJs(0.25), tonemapJs(0.57)]
+
+    // Main pass. Transparent hosts leave alpha 0 everywhere the scene doesn't draw — MSAA edge
+    // coverage lands as premultiplied (color × coverage, coverage), which is what the canvas declares.
+    renderer.bindFramebuffer({ buffer: null } as any)
+    renderer.setViewport(canvas.width, canvas.height)
+    if (options.transparent) gl.clearColor(0, 0, 0, 0)
+    else gl.clearColor(clear[0], clear[1], clear[2], 1)
+    renderer.enable(gl.DEPTH_TEST)
+    renderer.setDepthMask(true)
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+    batcher.drawMain(camera, sceneUniforms.shadowEnabled)
+
+    // Editor grid (if connected + enabled): depth-tested against the scene content just drawn.
+    // It gets the skybox color even on a transparent host — that's the backdrop the scene declares,
+    // and the grid inks itself against it (dark lines on a light sky, light lines on a dark one).
+    editorLayer?.renderScenePass(clear)
+
+    // Overlays: fresh depth, blended over (View::BlendMode::TRANSLUCENT equivalent)
+    for (const overlayId of scene.overlays) {
+      const overlay = sceneRoots.get(overlayId)
+      if (!overlay) continue
+      gl.clear(gl.DEPTH_BUFFER_BIT)
+      renderScene(overlay, camera)
+    }
+
+    // Editor selection outline + transform gizmo — always on top.
+    editorLayer?.renderOverlayPass()
+    // Editor camera preview inset (a CameraPlace's view) — last, in its own rect.
+    editorLayer?.renderPreviewPass(root, clear)
+    return true
+  }
+
+  // A throwing frame must not kill the loop permanently — log each distinct error once and keep going.
+  const frameErrors = new Set<string>()
+  const loop = (): void => {
+    if (!sceneOpened) return
+    try {
+      renderFrame(performance.now())
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!frameErrors.has(msg)) {
+        frameErrors.add(msg)
+        console.error('[viewer-lite] render frame failed:', e)
+      }
+    }
+    requestAnimationFrame(loop)
+  }
+
+  // ---- raycast (port of collider.cpp) ------------------------------------------------------------
+
+  const sceneIdOf = (id: number): number | undefined => core.sceneOf(id)?.id
+
+  let cameraRayOrigin = [0, 0, 0]
+  const getViewRay = (sceneId: number, screenX: number, screenY: number): { origin: number[], dir: number[] } => {
+    const camId = core.scenes.get(sceneId)?.camera
+    const w = camId !== undefined ? core.worldMatrix(camId) : identity()
+    const width = Math.max(1, canvas.width), height = Math.max(1, canvas.height)
+    const aspect = width / height
+    // Screen inputs are logical px; the backing store is logical × resFactor → scale up to match.
+    const sx = screenX * resFactor, sy = screenY * resFactor
+    const t = Math.tan((core.projectionOf(sceneId).fov * Math.PI) / 360)
+    const cx = ((sx / width) * 2 - 1) * t * aspect
+    const cy = (1 - (sy / height) * 2) * t
+    const dx = w[0] * cx + w[4] * cy - w[8]
+    const dy = w[1] * cx + w[5] * cy - w[9]
+    const dz = w[2] * cx + w[6] * cy - w[10]
+    const len = Math.hypot(dx, dy, dz) || 1
+    cameraRayOrigin = [w[12], w[13], w[14]]
+    return { origin: cameraRayOrigin, dir: [dx / len, dy / len, dz / len] }
+  }
+
+  const raycastColliders = (sceneId: number, origin: number[], dir: number[]): number => {
+    const colliders = sceneColliders.get(sceneId)
+    if (!colliders) return 0
+    let minDistance = Infinity
+    let target = 0
+    const localO: number[] = [0, 0, 0], localD: number[] = [0, 0, 0]
+    for (const [entityId, collider] of colliders) {
+      if (!core.entities.has(entityId) || !core.methods.isVisible(entityId)) continue
+      const inv = invertTRS(core.worldMatrixF(entityId))
+      transformPoint(localO, inv, origin[0], origin[1], origin[2], 1)
+      transformPoint(localD, inv, dir[0], dir[1], dir[2], 0)
+      const d = collider.type === 'box'
+        ? intersectRayBox(collider.center, collider.extent, localO, localD)
+        : intersectRaySphere(collider.center, collider.radius, localO, localD)
+      if (d > 0 && d < minDistance) { minDistance = d; target = entityId }
+    }
+    return target
+  }
+
+  const raycastRenderables = (sceneId: number, origin: number[], dir: number[]): number => {
+    const root = sceneRoots.get(sceneId)
+    if (!root) return 0
+    let minDistance = Infinity
+    let target = 0
+    const localO: number[] = [0, 0, 0], localD: number[] = [0, 0, 0]
+    root.updateMatrixWorld()
+    for (const mesh of collectMeshes(root) as any[]) {
+      const g = mesh.geometry
+      if (!g.bounds) g.computeBoundingBox()
+      if (!g.bounds || !isFinite(g.bounds.min.x)) continue
+      const inv = invertTRS(mesh.worldMatrix)
+      transformPoint(localO, inv, origin[0], origin[1], origin[2], 1)
+      transformPoint(localD, inv, dir[0], dir[1], dir[2], 0)
+      const c = [
+        (g.bounds.min.x + g.bounds.max.x) / 2, (g.bounds.min.y + g.bounds.max.y) / 2, (g.bounds.min.z + g.bounds.max.z) / 2,
+      ]
+      const e = [
+        (g.bounds.max.x - g.bounds.min.x) / 2, (g.bounds.max.y - g.bounds.min.y) / 2, (g.bounds.max.z - g.bounds.min.z) / 2,
+      ]
+      const d = intersectRayBox(c, e, localO, localD)
+      if (d > 0 && d < minDistance) {
+        minDistance = d
+        target = (mesh as any)._entId ?? 0
+      }
+    }
+    return target
+  }
+
+  // Pick order mirrors collider.cpp raycastView: overlay colliders (reverse) → scene colliders.
+  const raycastView = (screenX: number, screenY: number): number => {
+    const sceneId = core.activeSceneId()
+    const scene = core.scenes.get(sceneId)
+    if (!scene || scene.camera === undefined) return 0
+    const { origin, dir } = getViewRay(sceneId, screenX, screenY)
+    for (let i = scene.overlays.length - 1; i >= 0; i--) {
+      const hit = raycastColliders(scene.overlays[i], origin, dir)
+      if (hit !== 0) return hit
+    }
+    return raycastColliders(sceneId, origin, dir)
+  }
+
+  // ---- particle systems (creator-particles' streams → dynamic drawables) -----------------------
+  // One drawable per system under the emitter's transform: points / quads / ribbons share ONE
+  // interleaved buffer (the stream as is, re-uploaded per frame); a mesh system is unpacked into
+  // position / normal / uv for the lit / unlit programs (the frame's tangent quaternion → normal).
+  // The index buffer is the mode's pattern for the capacity, rebuilt with the geometry version.
+  const disposeParticles = (rec: GlParticles): void => {
+    if (rec.mesh) rec.mesh.setParent(null as any)
+    if (rec.buffer) gl.deleteBuffer(rec.buffer)
+    rec.mesh = null; rec.geometry = null; rec.buffer = null
+  }
+  const particleProgram = (rec: GlParticles, mode: number): Program => {
+    const mat = glMaterials.get(rec.materialId)
+    if (mode === MODE.MESH) return (mat ?? makeMaterial('unlit')).program
+    const wantQuad = mode !== MODE.POINTS
+    if (mat && (mat.kind === (wantQuad ? 'particles-quad' : 'particles'))) return mat.program
+    // a material of another family (custom, lit) cannot read the stream — draw with the default look
+    return makeMaterial(wantQuad ? 'particles-quad' : 'particles').program
+  }
+  const buildParticleGeometry = (entityId: number, rec: GlParticles, frame: ParticleFrame): void => {
+    disposeParticles(rec)
+    rec.version = frame.geometryVersion
+    rec.mode = frame.mode
+    if (frame.capacity === 0) return
+    const pattern = core.particleIndexPattern(entityId)
+    if (pattern.length === 0) return
+    let geometry: Geometry
+    if (frame.mode === MODE.MESH) {
+      const n = frame.capacity * frame.meshVertexCount
+      geometry = new Geometry(gl, {
+        position: { size: 3, data: new Float32Array(n * 3), usage: gl.DYNAMIC_DRAW },
+        normal: { size: 3, data: new Float32Array(n * 3), usage: gl.DYNAMIC_DRAW },
+        uv: { size: 2, data: new Float32Array(n * 2), usage: gl.DYNAMIC_DRAW },
+        index: { data: pattern },
+      } as any)
+    } else {
+      const buffer = gl.createBuffer()!
+      rec.buffer = buffer
+      const stride = frame.stride
+      const count = frame.mode === MODE.POINTS ? frame.capacity : frame.mode === MODE.QUADS ? frame.capacity * 4 : (frame.capacity + 1) * 2
+      const attr = (size: number, offset: number) => ({ size, type: gl.FLOAT, buffer, stride, offset, count, data: new Float32Array(0) })
+      const attrs: Record<string, unknown> = { position: attr(3, 0), color: attr(4, 12), custom: attr(4, 28) }
+      if (frame.mode !== MODE.POINTS) { attrs.aux = attr(3, 44); attrs.corner = attr(2, 56) }
+      attrs.index = { data: Uint16Array.from(pattern) }
+      geometry = new Geometry(gl, attrs as any)
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+      gl.bufferData(gl.ARRAY_BUFFER, count * stride, gl.DYNAMIC_DRAW)
+      ;(renderer.state as any).boundBuffer = buffer
+    }
+    const mesh = new Mesh(gl, { geometry, program: particleProgram(rec, frame.mode), mode: frame.mode === MODE.POINTS ? gl.POINTS : gl.TRIANGLES })
+    mesh.frustumCulled = false
+    mesh.matrixAutoUpdate = false
+    ;(mesh as any)._entId = entityId
+    ;(mesh as any)._particles = true
+    mesh.setParent(glEnt(entityId).transform)
+    rec.geometry = geometry
+    rec.mesh = mesh
+  }
+  const uploadParticles = (entityId: number, frame: ParticleFrame): void => {
+    let rec = glParticles.get(entityId)
+    if (!rec) { rec = { materialId: 0, mesh: null, geometry: null, buffer: null, version: 0, mode: -1 }; glParticles.set(entityId, rec) }
+    if (rec.version !== frame.geometryVersion || rec.mode !== frame.mode || !rec.mesh) { buildParticleGeometry(entityId, rec, frame); touchGraph() }
+    if (!rec.mesh || !rec.geometry) return
+    const show = frame.indexCount > 0
+    if (rec.mesh.visible !== show) { rec.mesh.visible = show; touchGraph() }
+    if (!show) return
+    rec.mesh.renderOrder = frame.order
+    if (frame.mode === MODE.MESH) {
+      const n = frame.vertexCount
+      const f = new Float32Array(frame.bytes.buffer, frame.bytes.byteOffset, n * 10)
+      const pos = rec.geometry.attributes.position, nrm = rec.geometry.attributes.normal, uv = rec.geometry.attributes.uv
+      const P = pos.data as Float32Array, N = nrm.data as Float32Array, U = uv.data as Float32Array
+      for (let i = 0; i < n; i++) {
+        const o = i * 10
+        P[i * 3] = f[o]; P[i * 3 + 1] = f[o + 1]; P[i * 3 + 2] = f[o + 2]
+        // the tangent frame's +z (the vertex normal): rotate (0, 0, 1) by the quaternion
+        const x = f[o + 3], y = f[o + 4], z = f[o + 5], w = f[o + 6]
+        N[i * 3] = 2 * (x * z + y * w); N[i * 3 + 1] = 2 * (y * z - x * w); N[i * 3 + 2] = 1 - 2 * (x * x + y * y)
+        U[i * 2] = f[o + 8]; U[i * 2 + 1] = f[o + 9]
+      }
+      pos.needsUpdate = nrm.needsUpdate = uv.needsUpdate = true
+    } else if (rec.buffer) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, rec.buffer)
+      gl.bufferSubData(gl.ARRAY_BUFFER, 0, frame.bytes)
+      ;(renderer.state as any).boundBuffer = rec.buffer
+    }
+    rec.geometry.drawRange.start = 0
+    rec.geometry.drawRange.count = frame.indexCount
+  }
+
+  // ---- SceneBackend hooks (core → GL reactions) -------------------------------------------------
+
+  const backend: SceneBackend = {
+    allocMatrix: (id) => glEnt(id).transform.matrix as unknown as Mat4Like,
+    localMatrixChanged: (id) => { glEnt(id).transform.worldMatrixNeedsUpdate = true; touchGraph() },
+    parentChanged: (childId, parentId) => {
+      touchGraph()
+      const child = glEnt(childId).transform
+      if (parentId !== 0) child.setParent(glEnt(parentId).transform)
+      else {
+        // Detach → back under the owning scene's root (if a member), else orphaned.
+        const s = core.sceneOf(childId)
+        child.setParent(((s && sceneRoots.get(s.id)) ?? null) as any)
+      }
+    },
+    sceneCreated: (sceneId) => { sceneRoots.set(sceneId, new Transform()); sceneColliders.set(sceneId, new Map()) },
+    entitySceneChanged: (id, sceneId, added) => {
+      touchGraph()
+      const root = sceneRoots.get(sceneId)
+      if (!root) return
+      const g = glEnt(id)
+      if (added) {
+        // Move any collider bookkeeping to this scene (scene.cpp move_elements; colliders are web-side).
+        for (const [sid, cmap] of sceneColliders) {
+          if (sid === sceneId) continue
+          const col = cmap.get(id)
+          if (col) { sceneColliders.get(sceneId)!.set(id, col); cmap.delete(id) }
+        }
+        if (core.ent(id).parent === 0) g.transform.setParent(root)
+      } else {
+        if (core.ent(id).parent === 0 && g.transform.parent === root) g.transform.setParent(null as any)
+      }
+    },
+    visibleChanged: (id, visible) => { glEnt(id).transform.visible = visible; touchGraph() },
+    materialCreated: (id, rec, systemId) => { glMaterials.set(id, buildProgramFor(rec.shader, systemId)) },
+    uniformChanged: (materialId, uniform, u) => applyUniform(materialId, uniform, u),
+    meshSet: (entityId, materialId, mesh, arrays) => { buildMesh(entityId, materialId, arrays, mesh.kind); touchGraph() },
+    glbAttach: (systemId, rootId, entIds) => attachGlb(systemId, rootId, entIds).then(touchGraph),
+    // Animator-sampled blendshape weights → the node's weight array from buildMorphState (glb.ts)
+    morphWeights: (entityId, weights) => {
+      const w = (glEnt(entityId).transform as any).weights as Float32Array | undefined
+      if (w) w.set(weights.subarray(0, Math.min(w.length, weights.length)))
+    },
+    entityDestroyed: (id) => {
+      touchGraph()
+      const g = glEnts.get(id)
+      if (g) { g.transform.setParent(null as any); glEnts.delete(id) }
+      for (const cmap of sceneColliders.values()) cmap.delete(id)
+    },
+    entityCloned: (sourceId, cloneId) => { cloneDrawables(sourceId, cloneId); touchGraph() },
+    subtreeCloned: (_sourceRootId, _cloneRootId, map) => rebindClonedSkins(map),
+    particleSystemCreated: (entityId, materialId) => {
+      const rec = glParticles.get(entityId)
+      if (rec) { disposeParticles(rec); rec.materialId = materialId; rec.version = 0 }
+      else glParticles.set(entityId, { materialId, mesh: null, geometry: null, buffer: null, version: 0, mode: -1 })
+    },
+    particlesFrame: (entityId, frame) => uploadParticles(entityId, frame),
+    particleSystemDestroyed: (entityId) => {
+      const rec = glParticles.get(entityId)
+      if (rec) { disposeParticles(rec); glParticles.delete(entityId) }
+      touchGraph()
+    },
+  }
+
+  // The animation runtime (creator-anim wasm) must be resident before the first animator call.
+  // The animation + physics runtimes (creator-anim / creator-physics wasm, base64-embedded in the bundle):
+  // resident before the scene core exists, so the SDK's first call finds them ready.
+  await Promise.all([loadCreatorAnim(), loadCreatorPhysics(), loadCreatorParticles()])
+  const core = createSceneCore(backend, {
+    getBuffer: getFetchedBuffer,
+    getSourceName: getLocalName,
+    width: canvas.width || 1,
+    height: canvas.height || 1,
+    fov: FOV,
+  })
+
+  // ---- the bridge: shared scene-graph (core.methods) + GL-only / capability methods --------------
+
+  // PNG/JPG/WebP… via the browser decoder → sRGB8_A8 texture.
+  const createBitmapTexture = (blob: Blob, onComplete: (id: number, width: number, height: number) => void, onReject: () => void): void => {
+    createImageBitmap(blob)
+      .then((bitmap) => {
+        const texture = new Texture(gl, {
+          image: bitmap as any,
+          internalFormat: gl.SRGB8_ALPHA8,
+          format: gl.RGBA,
+          generateMipmaps: false,
+          flipY: false,
+          premultiplyAlpha: false,
+        })
+        const id = nextTexture++
+        glTextures.set(id, texture)
+        onComplete(id, bitmap.width, bitmap.height)
+      })
+      .catch(onReject)
+  }
+  const bridge = {
+    // the contract's completeness layer (generated): every required method a stub UNDER ours
+    ...unsupported,
+    ...basePropsLite,
+    ...core.methods,
+
+    // --- the OWNED creators (docs/owned.md): the SDK keeps the Handle and puts `_h.id` on the wire. The
+    // lite engine keeps no owned records (a drop frees nothing), so it is a plain `{ id }` over the
+    // core's id — the wrap creator-gl's generated bridge does. createTexture* below return one too ---
+    createEntity: (): Handle => ({ id: core.methods.createEntity() }),
+    cloneEntity: (entityId: number): Handle => ({ id: core.methods.cloneEntity(entityId) }),
+    createMaterial: (systemId: number): Handle => ({ id: core.methods.createMaterial(systemId) }),
+    // Never null: a name this engine has no program for draws unlit (buildProgramFor), as it always did.
+    builtinMaterial: (name: string): Handle | null => ({ id: core.methods.createMaterialNamed(name) }),
+    createGlb(systemId: number, onComplete: (root: Handle | null) => void, onReject: () => void): void {
+      core.methods.createGlb(systemId, (root) => onComplete({ id: root }), onReject)
+    },
+
+    // --- scene lifecycle (core sets active scene; web adds the render loop + canvas display) ---
+    openScene(sceneId: number): void {
+      const wasOpen = sceneOpened
+      core.methods.openScene(sceneId)
+      sceneOpened = core.scenes.has(sceneId)
+      canvas.style.display = 'block'
+      if (!wasOpen && sceneOpened) requestAnimationFrame(loop)
+    },
+    closeScene(): void {
+      canvas.style.display = 'none'
+      sceneOpened = false
+      core.methods.closeScene()
+    },
+    launchAR(): void { throw new Error('launchAR is not implemented') },
+    stopAR(): void { throw new Error('stopAR is not implemented') },
+    launchVR(_sceneId: number, _onComplete: () => void, onReject: (err?: unknown) => void): void {
+      onReject(new Error('VR is not supported on this device'))
+    },
+    stopVR(): void {},
+    async warmRender(_sceneId: number, onComplete: () => void): Promise<void> { onComplete() },
+
+    // --- camera (dynamic canvas viewport; web ignores the projection callback like the Filament host) ---
+    attachCameraToAR(sceneId: number, cameraEntityId: number, _onProjectionChange: unknown): void {
+      const s = core.scenes.get(sceneId)
+      if (!s) return
+      s.camera = cameraEntityId
+      for (const overlayId of s.overlays) { const o = core.scenes.get(overlayId); if (o) o.camera = cameraEntityId }
+    },
+    // core.methods carries setCameraProjection (per-scene state); this override only re-derives the
+    // HORIZONTAL fov against the live canvas aspect instead of the core's fixed width/height.
+    getCameraFov(sceneId: number, fovType: number): number {
+      const fov = core.projectionOf(sceneId).fov
+      if (fovType !== 1) return fov
+      const vert = (fov * Math.PI) / 180
+      const aspect = canvas.width / Math.max(1, canvas.height)
+      return (2 * Math.atan(Math.tan(vert / 2) * aspect) * 180) / Math.PI
+    },
+    getCameraViewDirection(sceneId: number, screenX: number, screenY: number, out: Float32Array): void {
+      if (!core.scenes.has(sceneId)) { out[0] = 0; out[1] = 0; out[2] = -1; return }
+      const { dir } = getViewRay(sceneId, screenX, screenY)
+      out[0] = dir[0]; out[1] = dir[1]; out[2] = dir[2]
+    },
+    // Logical (CSS-px) viewport — device.pixelRatio carries the density separately. renderer.width/
+    // height hold the logical size passed to setSize (backing is that × dpr).
+    getDisplaySize: (): Float32Array => Float32Array.of(renderer.width || canvas.width, renderer.height || canvas.height),
+
+    // --- textures (GL) ---
+    createTexture(systemId: number, onComplete: (texture: Handle, width: number, height: number) => void, onReject: () => void): void {
+      const done = (id: number, width: number, height: number) => onComplete({ id }, width, height)
+      const blob = getBlob(systemId)
+      // KTX2 (Basis Universal): the browser can't decode it — route through the same lazy basis
+      // worker GLBs use (ASTC/BPTC/S3TC, else an rgba32 bitmap). sRGB vs linear from the file's DFD.
+      blob.slice(0, 12).arrayBuffer().then(async (head) => {
+        const decoders = await import('./decoders')
+        if (!decoders.isKtx2Bytes(new Uint8Array(head))) return false
+        const buf = await blob.arrayBuffer()
+        const parsed = await decoders.transcodeKtx2(gl, buf)
+        const srgb = decoders.ktx2IsSrgb(buf)
+        let texture: Texture
+        if (parsed.isCompressedTexture) {
+          texture = new Texture(gl, {
+            image: parsed,
+            internalFormat: srgb && parsed.srgbInternalFormat ? parsed.srgbInternalFormat : parsed.internalFormat,
+            generateMipmaps: false,
+            minFilter: parsed.length > 1 ? gl.LINEAR_MIPMAP_LINEAR : gl.LINEAR,
+            flipY: false,
+          })
+        } else {
+          texture = new Texture(gl, {
+            image: parsed,
+            internalFormat: srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8,
+            format: gl.RGBA,
+            generateMipmaps: true,
+            flipY: false,
+            premultiplyAlpha: false,
+          })
+        }
+        const id = nextTexture++
+        glTextures.set(id, texture)
+        done(id, parsed.width, parsed.height)
+        return true
+      }).then((handled) => { if (!handled) createBitmapTexture(blob, done, onReject) }, onReject)
+    },
+    // Raw-pixel textures (Texture.fromPixels / a terrain's control map). OGL textures re-upload the
+    // whole image, so a CPU copy per texture takes the sub-rectangle updates.
+    createTexturePixels(width: number, height: number, channels: number, data: Uint8Array, srgb: boolean): Handle {
+      if (width <= 0 || height <= 0 || data.length < width * height * channels) return { id: 0xFFFFFFFF }
+      const rgba = new Uint8Array(width * height * 4)
+      for (let i = 0, n = width * height; i < n; i++) {
+        const s = i * channels, d = i * 4
+        rgba[d] = data[s]
+        rgba[d + 1] = channels >= 2 ? data[s + 1] : data[s]
+        rgba[d + 2] = channels >= 3 ? data[s + 2] : data[s]
+        rgba[d + 3] = channels >= 4 ? data[s + 3] : 255
+      }
+      const texture = new Texture(gl, {
+        image: rgba as any, width, height,
+        internalFormat: srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8, format: gl.RGBA,
+        generateMipmaps: false, flipY: false, premultiplyAlpha: false,
+        minFilter: gl.LINEAR, magFilter: gl.LINEAR,
+      })
+      const id = nextTexture++
+      glTextures.set(id, texture)
+      pixelTextures.set(id, { rgba, width, height, channels })
+      return { id }
+    },
+    updateTexturePixels(textureId: number, x: number, y: number, width: number, height: number, data: Uint8Array): void {
+      const rec = pixelTextures.get(textureId)
+      const texture = glTextures.get(textureId)
+      if (!rec || !texture) return
+      const ch = rec.channels
+      for (let row = 0; row < height; row++) {
+        const ty = y + row
+        if (ty < 0 || ty >= rec.height) continue
+        for (let col = 0; col < width; col++) {
+          const tx = x + col
+          if (tx < 0 || tx >= rec.width) continue
+          const s = (row * width + col) * ch, d = (ty * rec.width + tx) * 4
+          rec.rgba[d] = data[s]
+          rec.rgba[d + 1] = ch >= 2 ? data[s + 1] : data[s]
+          rec.rgba[d + 2] = ch >= 3 ? data[s + 2] : data[s]
+          rec.rgba[d + 3] = ch >= 4 ? data[s + 3] : 255
+        }
+      }
+      texture.image = rec.rgba as any
+      ;(texture as any).needsUpdate = true
+    },
+    createTextureFromCanvas(surfaceId: number): number {
+      const surf = options.canvasHost?.readSurface(surfaceId)
+      if (!surf) return 0
+      const texture = new Texture(gl, {
+        image: new Uint8Array(surf.data.buffer.slice(0)) as any,
+        width: surf.width,
+        height: surf.height,
+        internalFormat: gl.SRGB8_ALPHA8,
+        format: gl.RGBA,
+        generateMipmaps: false,
+        flipY: false,
+      })
+      const id = nextTexture++
+      glTextures.set(id, texture)
+      return id
+    },
+    updateTextureFromCanvas(texId: number, surfaceId: number): void {
+      const surf = options.canvasHost?.readSurface(surfaceId)
+      const texture = glTextures.get(texId)
+      if (!surf || !texture) return
+      texture.image = new Uint8Array(surf.data.buffer.slice(0)) as any
+      texture.width = surf.width
+      texture.height = surf.height
+      ;(texture as any).needsUpdate = true
+    },
+    createMediaPlayerTexture(id: number): number {
+      const video = getPlayer(id) as HTMLVideoElement
+      const texture = new Texture(gl, { generateMipmaps: false, flipY: false, premultiplyAlpha: false })
+      activeVideoTextures.push({ video, texture, lastTime: -1 })
+      const texId = nextTexture++
+      glTextures.set(texId, texture)
+      return texId
+    },
+
+    // --- materials that need GL specifics on top of the core's semantic recording ---
+    setUniformTexture(materialId: number, uniform: string, systemId: number, wrapS: number, wrapT: number): void {
+      core.methods.setUniformTexture(materialId, uniform, systemId) // record semantic + bind by id
+      const rec = glMaterials.get(materialId)
+      const texture = glTextures.get(systemId)
+      if (!rec || !texture) return
+      const WRAP = [gl.CLAMP_TO_EDGE, gl.REPEAT, gl.MIRRORED_REPEAT]
+      texture.wrapS = WRAP[wrapS] ?? gl.REPEAT
+      texture.wrapT = WRAP[wrapT] ?? gl.REPEAT
+      ;(texture as any).needsUpdate = true
+      materialUniform(rec, uniform).value = texture
+    },
+    setMaterial(entityId: number, materialId: number, index: number): void {
+      core.methods.setMaterial(entityId, materialId, index)
+      const rec = glMaterials.get(materialId)
+      const mesh = glEnt(entityId).drawables[index]
+      if (!rec || !mesh) return
+      mesh.program = rec.program
+      wireReceiveShadows(mesh, rec)
+      touchGraph()
+    },
+    getMaterial(entityId: number, index: number): number {
+      const mesh = glEnt(entityId).drawables[index] as any
+      if (!mesh) return 0
+      const id = core.nextMaterialId()
+      glMaterials.set(id, { kind: 'gltf', program: mesh.program })
+      return id
+    },
+
+    // --- culling / shadows (per-drawable GL flags; core also records cast/receive semantics) ---
+    setCulling(entityId: number, culling: boolean): void {
+      for (const d of glEnt(entityId).drawables) d.frustumCulled = culling
+      touchGraph()
+    },
+    setGlbCulling(entityId: number, culling: boolean): void {
+      const walk = (id: number): void => {
+        for (const d of glEnt(id).drawables) d.frustumCulled = culling
+        for (const c of core.ent(id).children) walk(c)
+      }
+      walk(entityId)
+      touchGraph()
+    },
+    // draw order / depth state (Mesh.renderPriority, Material.depthTest / depthWrite): the OGL
+    // renderer sorts by renderOrder inside a pass; the depth flags live on the program
+    setRenderPriority(entityId: number, priority: number): void {
+      for (const d of glEnt(entityId).drawables as any[]) d.renderOrder = priority
+      touchGraph()
+    },
+    setMaterialDepthTest(materialId: number, enable: boolean): void {
+      const rec = glMaterials.get(materialId)
+      if (rec) (rec.program as any).depthTest = enable
+    },
+    setMaterialDepthWrite(materialId: number, enable: boolean): void {
+      const rec = glMaterials.get(materialId)
+      if (rec) (rec.program as any).depthWrite = enable
+    },
+    setMaterialCulling(materialId: number, mode: number): void {
+      const rec = glMaterials.get(materialId)
+      if (rec) (rec.program as any).cullFace = mode === 0 ? false : mode === 1 ? gl.FRONT : gl.BACK
+    },
+    setCastShadows(entityId: number, value: boolean): void {
+      core.methods.setCastShadows(entityId, value)
+      for (const d of glEnt(entityId).drawables as any[]) d._castShadows = value
+      touchGraph()
+    },
+    setReceiveShadows(entityId: number, value: boolean): void {
+      core.methods.setReceiveShadows(entityId, value)
+      for (const d of glEnt(entityId).drawables as any[]) d._receiveShadows = value
+      touchGraph()
+    },
+    setGlbShadows(entityId: number, cast: boolean, receive: boolean): void {
+      core.methods.setGlbShadows(entityId, cast, receive)
+      const walk = (id: number): void => {
+        for (const d of glEnt(id).drawables as any[]) { d._castShadows = cast; d._receiveShadows = receive }
+        for (const c of core.ent(id).children) walk(c)
+      }
+      walk(entityId)
+      touchGraph()
+    },
+    setCastShadowsGlobal(value: boolean): void { castShadowsGlobal = value },
+    setReceiveShadowsGlobal(value: boolean): void { receiveShadowsGlobal = value },
+
+    // --- colliders (CPU raycast picking; web-side, from mesh bounds) ---
+    setColliderFromMesh(entityId: number, meshEntityId: number, form: number): void {
+      if (form !== 0) return
+      const mesh = glEnt(meshEntityId).drawables[0] as any
+      if (!mesh) return
+      const g = mesh.geometry
+      if (!g.bounds) g.computeBoundingBox()
+      if (!g.bounds) return
+      const sid = sceneIdOf(entityId) ?? core.activeSceneId()
+      sceneColliders.get(sid)?.set(entityId, {
+        type: 'box',
+        center: [(g.bounds.min.x + g.bounds.max.x) / 2, (g.bounds.min.y + g.bounds.max.y) / 2, (g.bounds.min.z + g.bounds.max.z) / 2],
+        extent: [(g.bounds.max.x - g.bounds.min.x) / 2, (g.bounds.max.y - g.bounds.min.y) / 2, (g.bounds.max.z - g.bounds.min.z) / 2],
+      })
+    },
+    setColliderBox(entityId: number, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): void {
+      const sid = sceneIdOf(entityId) ?? core.activeSceneId()
+      sceneColliders.get(sid)?.set(entityId, { type: 'box', center: [cx, cy, cz], extent: [sx / 2, sy / 2, sz / 2] })
+    },
+    setColliderSphere(entityId: number, cx: number, cy: number, cz: number, radius: number): void {
+      const sid = sceneIdOf(entityId) ?? core.activeSceneId()
+      sceneColliders.get(sid)?.set(entityId, { type: 'sphere', center: [cx, cy, cz], radius })
+    },
+
+    // (physics: the core's real simulation — creator-physics' wasm, loaded above with the animation runtime)
+
+    // --- AR (not supported in lite; the simulator overrides these with its own webcam AR methods) ---
+    createARController(): void { throw new Error('createARController is not implemented') },
+    createRootAnchor(): number { throw new Error('createRootAnchor is not implemented') },
+    createAnchor(): number { throw new Error('createAnchor is not implemented') },
+    createARPlane: (): number => 0,
+    updateProjectionMatrixAR(): void {},
+    _setARController(): void {},
+
+    // (particles + noise: the core's creator-particles wasm, drawn through particlesFrame above)
+
+    // --- capture ---
+    /** Draw one frame synchronously — hosts call this immediately before reading the canvas back
+     *  (the simulator's "Save image"), since without preserveDrawingBuffer the pixels only survive
+     *  inside the task that drew them. captureImage below does the same thing for the app-facing ABI. */
+    _renderNow: () => renderFrame(performance.now()),
+    async captureImage(_sceneId: number, onComplete: (bufferId: number, name: string, size: number) => void, onReject: () => void): Promise<void> {
+      try {
+        renderFrame(performance.now()) // make sure the framebuffer holds a fresh frame
+        const temp = new OffscreenCanvas(canvas.width, canvas.height)
+        const ctx = temp.getContext('2d')!
+        ctx.drawImage(canvas, 0, 0)
+        const blob = await temp.convertToBlob({ type: 'image/png' })
+        const buffer = await blob.arrayBuffer()
+        onComplete(putBuffer(buffer), 'image.png', blob.size)
+      } catch {
+        onReject()
+      }
+    },
+
+    // --- host plumbing (same seam as viewer/createViewer.ts) ---
+    raycastView,
+    _raycastView: raycastView,
+    /** VR-style pick (native raycastPick): colliders first, then renderable AABBs as fallback. */
+    raycastPick(screenX: number, screenY: number): number {
+      const sceneId = core.activeSceneId()
+      const scene = core.scenes.get(sceneId)
+      if (!scene || scene.camera === undefined) return 0
+      const hit = raycastView(screenX, screenY)
+      if (hit !== 0) return hit
+      const { origin, dir } = getViewRay(sceneId, screenX, screenY)
+      return raycastRenderables(sceneId, origin, dir)
+    },
+    computeBoundingBox(entityId: number): Float32Array {
+      // Subtree AABB in the entity's local space (mirrors collider.cpp computeBoundingBox).
+      const out = Float32Array.of(Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity)
+      const corner: number[] = [0, 0, 0]
+      const walk = (id: number, mat: Mat4Like | null): void => {
+        for (const mesh of glEnt(id).drawables as any[]) {
+          const g = mesh.geometry
+          if (!g.bounds) g.computeBoundingBox()
+          if (!g.bounds || !isFinite(g.bounds.min.x)) continue
+          for (let i = 0; i < 8; i++) {
+            const x = i & 1 ? g.bounds.max.x : g.bounds.min.x
+            const y = i & 2 ? g.bounds.max.y : g.bounds.min.y
+            const z = i & 4 ? g.bounds.max.z : g.bounds.min.z
+            if (mat) transformPoint(corner, mat, x, y, z, 1)
+            else { corner[0] = x; corner[1] = y; corner[2] = z }
+            for (let k = 0; k < 3; k++) {
+              if (corner[k] < out[k]) out[k] = corner[k]
+              if (corner[k] > out[k + 3]) out[k + 3] = corner[k]
+            }
+          }
+        }
+        for (const c of core.ent(id).children) {
+          const childLocal = glEnt(c).transform.matrix as unknown as Mat4Like
+          const childMat = mat ? multiply(new Float32Array(16), mat, childLocal) : Float32Array.from(childLocal as ArrayLike<number>)
+          walk(c, childMat)
+        }
+      }
+      walk(entityId, null)
+      if (!isFinite(out[0])) out.fill(0)
+      return out
+    },
+    stopAllPlayers(): void { removePlayers() },
+    /** The agreement seam: serialize the LIVE core state to the exact `scene3d` JSON `lecodes render`
+     *  emits — so a scene running in the browser can be dumped and cross-checked against the pixels
+     *  (and the headless output). Colliders/physics/texture names are GL-side here, so they don't
+     *  appear; the scene graph, materials, camera and screen-space `frame` do. */
+    _dumpScene3d: (): unknown => serializeScene3d(core),
+    /** EDITOR host API (not part of the bridge ABI / parity surface): wireframe display mode —
+     *  'overlay' draws edge lines over the shaded pass, 'only' replaces it. See the wireframe
+     *  section above. The scene editor calls this on its lite viewport; apps never see it. */
+    _setWireframeMode(mode: 'off' | 'overlay' | 'only'): void {
+      wireframeMode = mode === 'overlay' || mode === 'only' ? mode : 'off'
+      // dark lines read on shaded surfaces; light lines read on the bare skybox
+      wireColor.value = wireframeMode === 'only' ? [ 0.62, 0.66, 0.72 ] : [ 0.05, 0.06, 0.08 ]
+      updateWireframe()
+      touchGraph()
+    },
+    /** HOST API (not part of the bridge ABI / parity surface): instanced batching on/off — off
+     *  draws every mesh through the per-object path, the reference the batched picture must
+     *  match (render-check compares the two). Diagnostics via `_batchStats`. */
+    _setBatching(enabled: boolean): void {
+      for (const b of batchers.values()) b.setEnabled(enabled)
+      batchingEnabled = enabled
+      touchGraph()
+    },
+    _batchStats(): { batches: number, instances: number, visible: number, singles: number } {
+      const root = sceneRoots.get(core.activeSceneId())
+      return root ? batcherFor(root).stats() : { batches: 0, instances: 0, visible: 0, singles: 0 }
+    },
+    /** EDITOR host API (not part of the bridge ABI / parity surface): connect the engine-side
+     *  editor layer — grid, selection outline, viewport picking, and the transform gizmo (see
+     *  editor.ts). Returns { setGrid, setSelection, setGizmoMode, setGizmoSpace, setColliders, setGizmos };
+     *  the handlers
+     *  receive picks (entity ids) and completed gizmo drags. The scene editor is the only caller. */
+    _editorConnect(handlers: EditorHandlers) {
+      editorLayer ??= createEditorLayer({
+        gl, renderer, canvas, camera, core, sceneRoots,
+        drawablesOf: (id) => glEnt(id).drawables,
+        collectMeshes, wireGeometryFor, getViewRay, renderScene,
+      })
+      editorLayer.setHandlers(handlers)
+      return editorLayer.api
+    },
+    async createEngine(): Promise<void> {},
+    _fetch,
+    _getPlayer: getPlayer,
+    _createGLTexture(source: HTMLCanvasElement | OffscreenCanvas) {
+      const texture = new Texture(gl, {
+        image: source as any,
+        generateMipmaps: false,
+        flipY: false,
+        premultiplyAlpha: false,
+      })
+      const textureId = nextTexture++
+      glTextures.set(textureId, texture)
+      texture.update()
+      return { gl, glTexture: texture.texture, textureId }
+    },
+    _onResize(width: number, height: number, factor = 1): void {
+      resFactor = factor
+      renderer.dpr = factor // OGL setSize then sizes the backing (× dpr) and pins the CSS box to logical px
+      renderer.setSize(width, height)
+      lastAspect = 0 // force projection refresh
+    },
+    _dispose(): void {
+      editorLayer?.dispose()
+      editorLayer = null
+      for (const b of batchers.values()) b.dispose()
+      batchers.clear()
+      this.closeScene()
+      this.stopAllPlayers()
+      gl.getExtension('WEBGL_lose_context')?.loseContext()
+    },
+  }
+
+  bridge satisfies typeof _creator   // the whole contract, our signatures checked against it
+  return bridge
+}
+
+export type CreatorLite = Awaited<ReturnType<typeof createViewerLite>>