lecodes-viewer 0.19.0

package/src/viewer/mediaplayer.ts

@@ -0,0 +1,3 @@
+// Moved to viewer-lite (shared media-player registry); re-export shim so viewer and the
+// lite engine address the SAME player slots.
+export * from "lecodes-viewer-lite/src/utils/mediaplayer"

package/src/viewer/physics.ts

@@ -0,0 +1,140 @@
+// Thin, typed wrapper + helpers for the JoltPhysics bring-up in creator-gl.
+//
+// The actual entry points live on the viewer returned by `createViewer` (physicsCreateBox,
+// physicsSetLinearVelocity, …). This file adds the things that don't belong in the raw
+// passthroughs: the motion-type enum, a typed surface, and a runnable test scene.
+//
+// Ownership convention (mirror of creator.h):
+//   - Dynamic bodies: physics OWNS the transform. After physicsCreate*, do NOT call
+//     setPosition / setMatrix on the entity per frame — move it via velocity / impulse.
+//   - Kinematic bodies: move via physicsSetBodyPosition.
+//   - The fixed-step simulation + transform sync happen in C++ inside `_render`; nothing
+//     crosses the JS boundary per frame.
+
+export const MotionType = {
+  Static: 0,    // immovable (ground / walls)
+  Kinematic: 1, // moved by code via physicsSetBodyPosition, pushes dynamics
+  Dynamic: 2,   // simulated: gravity, collisions, impulses
+} as const
+
+export type MotionType = (typeof MotionType)[keyof typeof MotionType]
+
+// The physics slice of the createViewer() return value.
+export interface PhysicsApi {
+  /** True only when creator-gl was built with -DCREATOR_GL_PHYSICS=ON. */
+  physicsHasSupport(): boolean
+  /** Gravity + max body count. maxBodies only takes effect before any body exists (it resizes
+   *  the world); pass 0 to keep the current limit. Derived pair/contact/temp limits scale with it. */
+  physicsConfigure(gx: number, gy: number, gz: number, maxBodies: number): void
+  /** halfExtents = half the full box size on each axis. Returns a bodyId (0 = failure). */
+  physicsCreateBox(entityId: number, hx: number, hy: number, hz: number, motionType: MotionType, mass: number): number
+  physicsCreateSphere(entityId: number, radius: number, motionType: MotionType, mass: number): number
+  physicsCreateCylinder(entityId: number, halfHeight: number, radius: number, motionType: MotionType, mass: number): number
+  physicsSetLinearVelocity(bodyId: number, x: number, y: number, z: number): void
+  /** Writes the body's current linear velocity (3 floats) into `out`. */
+  physicsGetLinearVelocity(bodyId: number, out: Float32Array): void
+  physicsApplyImpulse(bodyId: number, x: number, y: number, z: number): void
+  /** Teleport / drive a kinematic or dynamic body. */
+  physicsSetBodyPosition(bodyId: number, x: number, y: number, z: number): void
+  physicsRemoveBody(bodyId: number): void
+}
+
+// Minimal viewer surface this module needs (avoids importing the whole createViewer type).
+type SceneViewer = PhysicsApi & {
+  createEntity(): number
+  addEntityToScene(sceneId: number, entityId: number): void
+  setPosition(entityId: number, x: number, y: number, z: number): void
+  setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number): void
+}
+
+// ---------------------------------------------------------------------------
+// Geometry generators (so the rendered shape matches the collider exactly).
+// ---------------------------------------------------------------------------
+
+export type MeshData = { vertices: Float32Array; normals: Float32Array; indices: Uint16Array; uv: Float32Array }
+
+/** Axis-aligned box with half-extents (hx,hy,hz). 24 verts (hard normals), 36 indices. */
+export function makeBoxMesh(hx: number, hy: number, hz: number): MeshData {
+  // 6 faces × 4 verts. Each face: { normal, 4 corners (ccw) }.
+  const faces: { n: [number, number, number]; c: [number, number, number][] }[] = [
+    { n: [0, 0, 1],  c: [[-hx, -hy, hz], [hx, -hy, hz], [hx, hy, hz], [-hx, hy, hz]] },     // +Z
+    { n: [0, 0, -1], c: [[hx, -hy, -hz], [-hx, -hy, -hz], [-hx, hy, -hz], [hx, hy, -hz]] }, // -Z
+    { n: [1, 0, 0],  c: [[hx, -hy, hz], [hx, -hy, -hz], [hx, hy, -hz], [hx, hy, hz]] },     // +X
+    { n: [-1, 0, 0], c: [[-hx, -hy, -hz], [-hx, -hy, hz], [-hx, hy, hz], [-hx, hy, -hz]] }, // -X
+    { n: [0, 1, 0],  c: [[-hx, hy, hz], [hx, hy, hz], [hx, hy, -hz], [-hx, hy, -hz]] },     // +Y
+    { n: [0, -1, 0], c: [[-hx, -hy, -hz], [hx, -hy, -hz], [hx, -hy, hz], [-hx, -hy, hz]] }, // -Y
+  ]
+  const vertices: number[] = [], normals: number[] = [], uv: number[] = [], indices: number[] = []
+  const faceUv = [[0, 0], [1, 0], [1, 1], [0, 1]]
+  faces.forEach((f, fi) => {
+    const base = fi * 4
+    f.c.forEach((p, i) => { vertices.push(p[0], p[1], p[2]); normals.push(f.n[0], f.n[1], f.n[2]); uv.push(faceUv[i][0], faceUv[i][1]) })
+    indices.push(base, base + 1, base + 2, base, base + 2, base + 3)
+  })
+  return { vertices: new Float32Array(vertices), normals: new Float32Array(normals), indices: new Uint16Array(indices), uv: new Float32Array(uv) }
+}
+
+/** UV sphere of the given radius. */
+export function makeSphereMesh(radius: number, segments = 16, rings = 12): MeshData {
+  const vertices: number[] = [], normals: number[] = [], uv: number[] = [], indices: number[] = []
+  for (let y = 0; y <= rings; y++) {
+    const v = y / rings, theta = v * Math.PI
+    for (let x = 0; x <= segments; x++) {
+      const u = x / segments, phi = u * Math.PI * 2
+      const nx = Math.sin(theta) * Math.cos(phi), ny = Math.cos(theta), nz = Math.sin(theta) * Math.sin(phi)
+      vertices.push(nx * radius, ny * radius, nz * radius); normals.push(nx, ny, nz); uv.push(u, v)
+    }
+  }
+  const stride = segments + 1
+  for (let y = 0; y < rings; y++) for (let x = 0; x < segments; x++) {
+    const a = y * stride + x, b = a + stride
+    indices.push(a, b, a + 1, a + 1, b, b + 1)
+  }
+  return { vertices: new Float32Array(vertices), normals: new Float32Array(normals), indices: new Uint16Array(indices), uv: new Float32Array(uv) }
+}
+
+// ---------------------------------------------------------------------------
+// Test scene — ground + a scatter of dynamic boxes & spheres that fall, collide and settle.
+// `materialId` is a material-instance id the caller already created (material creation is
+// app-specific). Returns the created entity ids (e.g. to remove them later).
+// ---------------------------------------------------------------------------
+export function createPhysicsTestScene(viewer: SceneViewer, sceneId: number, materialId: number): number[] {
+  if (!viewer.physicsHasSupport()) {
+    console.warn("[physics] creator-gl was built without physics (CREATOR_GL_PHYSICS=OFF)")
+    return []
+  }
+
+  viewer.physicsConfigure(0, -9.81, 0, 0)
+  const created: number[] = []
+
+  const addEntity = (mesh: MeshData, x: number, y: number, z: number): number => {
+    const e = viewer.createEntity()
+    viewer.setMesh(e, materialId, mesh.vertices, mesh.normals, mesh.indices, mesh.uv, 0)
+    viewer.addEntityToScene(sceneId, e)
+    viewer.setPosition(e, x, y, z) // body reads its initial pose from this transform
+    created.push(e)
+    return e
+  }
+
+  // Static ground: a wide flat box, top surface at y = 0.
+  const groundHalf: [number, number, number] = [12, 0.5, 12]
+  const ground = addEntity(makeBoxMesh(...groundHalf), 0, -0.5, 0)
+  viewer.physicsCreateBox(ground, ...groundHalf, MotionType.Static, 0)
+
+  // Dynamic boxes — dropped at varied heights/offsets so they collide and stack.
+  const boxMesh = makeBoxMesh(0.5, 0.5, 0.5)
+  for (let i = 0; i < 6; i++) {
+    const e = addEntity(boxMesh, (i - 2.5) * 0.6, 4 + i * 1.2, (i % 2) * 0.3)
+    viewer.physicsCreateBox(e, 0.5, 0.5, 0.5, MotionType.Dynamic, 1.0)
+  }
+
+  // Dynamic spheres — one nudged sideways with an initial velocity.
+  const sphereMesh = makeSphereMesh(0.5)
+  for (let i = 0; i < 3; i++) {
+    const e = addEntity(sphereMesh, 2 + i * 0.4, 6 + i * 1.0, -1)
+    const body = viewer.physicsCreateSphere(e, 0.5, MotionType.Dynamic, 1.0)
+    if (i === 0) viewer.physicsSetLinearVelocity(body, -2, 0, 0)
+  }
+
+  return created
+}

package/src/viewer/validateGlb.ts

@@ -0,0 +1,262 @@
+// Pre-flight GLB validator — runs in the browser and in Bun (no Node/DOM APIs, no deps).
+//
+// Why this exists: the creator-gl wasm is shipped WITHOUT emscripten assertions, so when a
+// model violates a filament hard-limit the C++ code calls abort() with no usable message
+// (e.g. "bone count > 256", or a missing texture-decoder for webp). Validate the bytes here,
+// BEFORE handing them to module._loadGlb(), and reject with a clear, actionable error instead.
+//
+// Mirrors the exact constraints filament/gltfio enforce at load time:
+//   - filament CONFIG_MAX_BONE_COUNT        = 256  (skin.joints per renderable)
+//   - filament CONFIG_MAX_MORPH_TARGET_COUNT = 256  (morph targets per primitive)
+//   - gltfio texture providers registered in glb.cpp: image/png, image/jpeg, image/ktx2 only
+//     (webp / EXT_texture_webp has no provider -> load fails).
+
+// ---- filament limits (keep in sync with EngineEnums.h) ----------------------------------------
+export const MAX_BONE_COUNT = 256
+export const MAX_MORPH_TARGET_COUNT = 256
+
+// Texture formats with a provider registered in creator-gl (see packages/creator-gl/src/glb.cpp).
+export const SUPPORTED_IMAGE_FORMATS = ['png', 'jpeg', 'ktx2'] as const
+export type ImageFormat = (typeof SUPPORTED_IMAGE_FORMATS)[number] | 'webp' | 'unknown'
+
+export interface GlbIssue {
+  level: 'error' | 'warning'
+  code: 'CONTAINER' | 'BONE_COUNT' | 'MORPH_COUNT' | 'TEXTURE_FORMAT'
+  message: string
+  detail?: Record<string, unknown>
+}
+
+export interface GlbValidationResult {
+  ok: boolean
+  errors: GlbIssue[]
+  warnings: GlbIssue[]
+  summary: {
+    skins: number
+    maxJointCount: number
+    images: number
+    formats: Record<string, number>
+  }
+}
+
+const GLB_MAGIC = 0x46546c67 // "glTF"
+const CHUNK_JSON = 0x4e4f534a // "JSON"
+const CHUNK_BIN = 0x004e4942 // "BIN\0"
+
+class GlbParseError extends Error {}
+
+export interface ParsedGlb {
+  json: any
+  bin: Uint8Array | null
+}
+
+function toBytes(data: ArrayBuffer | Uint8Array): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data)
+}
+
+/** Container parse only (JSON chunk + BIN chunk); also accepts raw .gltf JSON bytes.
+ *  Exported for reuse (backend asset-metadata extraction) — throws GlbParseError on bad input. */
+export function parseGlb(bytes: Uint8Array): ParsedGlb {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+
+  // Accept a raw .gltf (JSON) too — useful for editor/CI paths. No BIN chunk in that case,
+  // so byte-sniffing of embedded images is skipped (uri/mimeType still validated).
+  if (bytes.byteLength < 12 || dv.getUint32(0, true) !== GLB_MAGIC) {
+    try {
+      return { json: JSON.parse(new TextDecoder().decode(bytes)), bin: null }
+    } catch {
+      throw new GlbParseError('Not a GLB (bad magic) and not parseable as glTF JSON')
+    }
+  }
+
+  const version = dv.getUint32(4, true)
+  if (version !== 2) throw new GlbParseError(`Unsupported GLB container version ${version} (expected 2)`)
+
+  let offset = 12
+  let json: any = null
+  let bin: Uint8Array | null = null
+  while (offset + 8 <= bytes.byteLength) {
+    const chunkLen = dv.getUint32(offset, true)
+    const chunkType = dv.getUint32(offset + 4, true)
+    const start = offset + 8
+    const end = start + chunkLen
+    if (end > bytes.byteLength) throw new GlbParseError(`Chunk at ${offset} overruns the file`)
+    if (chunkType === CHUNK_JSON) {
+      json = JSON.parse(new TextDecoder().decode(bytes.subarray(start, end)))
+    } else if (chunkType === CHUNK_BIN) {
+      bin = bytes.subarray(start, end)
+    }
+    offset = end // chunkLength already includes the 4-byte alignment padding (glTF spec)
+  }
+
+  if (!json) throw new GlbParseError('GLB has no JSON chunk')
+  return { json, bin }
+}
+
+// ---- image format detection -------------------------------------------------------------------
+
+function mimeToFormat(mime: string): ImageFormat {
+  switch (mime) {
+    case 'image/png': return 'png'
+    case 'image/jpeg': return 'jpeg'
+    case 'image/ktx2': return 'ktx2'
+    case 'image/webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function extToFormat(ext: string): ImageFormat {
+  switch (ext) {
+    case 'png': return 'png'
+    case 'jpg':
+    case 'jpeg': return 'jpeg'
+    case 'ktx2': return 'ktx2'
+    case 'webp': return 'webp'
+    default: return 'unknown'
+  }
+}
+
+function sniffMagic(b: Uint8Array): ImageFormat {
+  if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'png'
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg'
+  // RIFF....WEBP
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) return 'webp'
+  // KTX2: 0xAB 'KTX 20' 0xBB 0x0D 0x0A 0x1A 0x0A
+  if (b.length >= 8 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58 &&
+      b[4] === 0x20 && b[5] === 0x32 && b[6] === 0x30 && b[7] === 0xbb) return 'ktx2'
+  return 'unknown'
+}
+
+function detectFormat(image: any, json: any, bin: Uint8Array | null): { format: ImageFormat; via: string } {
+  if (typeof image?.uri === 'string') {
+    const uri: string = image.uri
+    if (uri.startsWith('data:')) {
+      const m = /^data:([^;,]+)[;,]/.exec(uri)
+      const mime = (m?.[1] ?? '').toLowerCase()
+      return { format: mimeToFormat(mime), via: `data-uri "${mime || '?'}"` }
+    }
+    const ext = (uri.split('?')[0].split('#')[0].split('.').pop() ?? '').toLowerCase()
+    return { format: extToFormat(ext), via: `uri ".${ext}"` }
+  }
+  if (typeof image?.mimeType === 'string') {
+    const mime = image.mimeType.toLowerCase()
+    return { format: mimeToFormat(mime), via: `mimeType "${image.mimeType}"` }
+  }
+  if (typeof image?.bufferView === 'number' && bin) {
+    const bv = json.bufferViews?.[image.bufferView]
+    // embedded images live in buffer 0 (the BIN chunk) for GLB
+    if (bv && (bv.buffer ?? 0) === 0) {
+      const start = bv.byteOffset ?? 0
+      return { format: sniffMagic(bin.subarray(start, start + 16)), via: 'magic-bytes' }
+    }
+  }
+  return { format: 'unknown', via: 'undetermined' }
+}
+
+// Image indices actually referenced by a texture (standard source + ktx2/webp extension sources).
+function collectUsedImages(json: any): Set<number> {
+  const used = new Set<number>()
+  for (const t of json.textures ?? []) {
+    if (typeof t.source === 'number') used.add(t.source)
+    const basisu = t.extensions?.KHR_texture_basisu
+    if (typeof basisu?.source === 'number') used.add(basisu.source)
+    const webp = t.extensions?.EXT_texture_webp
+    if (typeof webp?.source === 'number') used.add(webp.source)
+  }
+  return used
+}
+
+// ---- main entry -------------------------------------------------------------------------------
+
+export function validateGlb(data: ArrayBuffer | Uint8Array): GlbValidationResult {
+  const errors: GlbIssue[] = []
+  const warnings: GlbIssue[] = []
+  const formats: Record<string, number> = {}
+
+  let parsed: ParsedGlb
+  try {
+    parsed = parseGlb(toBytes(data))
+  } catch (e) {
+    return {
+      ok: false,
+      errors: [{ level: 'error', code: 'CONTAINER', message: (e as Error).message }],
+      warnings: [],
+      summary: { skins: 0, maxJointCount: 0, images: 0, formats: {} },
+    }
+  }
+  const { json, bin } = parsed
+
+  // --- skins: joints per skin == filament mSkinningBoneCount, capped at CONFIG_MAX_BONE_COUNT ---
+  const skins: any[] = json.skins ?? []
+  let maxJointCount = 0
+  for (let i = 0; i < skins.length; i++) {
+    const n = skins[i]?.joints?.length ?? 0
+    maxJointCount = Math.max(maxJointCount, n)
+    if (n > MAX_BONE_COUNT) {
+      errors.push({
+        level: 'error',
+        code: 'BONE_COUNT',
+        message: `skin[${i}]${skins[i].name ? ` "${skins[i].name}"` : ''} has ${n} joints, exceeds filament limit of ${MAX_BONE_COUNT}`,
+        detail: { skin: i, name: skins[i].name, joints: n, limit: MAX_BONE_COUNT },
+      })
+    }
+  }
+
+  // --- morph targets per primitive, capped at CONFIG_MAX_MORPH_TARGET_COUNT --------------------
+  for (let mi = 0; mi < (json.meshes?.length ?? 0); mi++) {
+    const mesh = json.meshes[mi]
+    for (let pi = 0; pi < (mesh.primitives?.length ?? 0); pi++) {
+      const n = mesh.primitives[pi]?.targets?.length ?? 0
+      if (n > MAX_MORPH_TARGET_COUNT) {
+        errors.push({
+          level: 'error',
+          code: 'MORPH_COUNT',
+          message: `mesh[${mi}]${mesh.name ? ` "${mesh.name}"` : ''} primitive ${pi} has ${n} morph targets, exceeds filament limit of ${MAX_MORPH_TARGET_COUNT}`,
+          detail: { mesh: mi, primitive: pi, targets: n, limit: MAX_MORPH_TARGET_COUNT },
+        })
+      }
+    }
+  }
+
+  // --- textures: every image must decode with a registered provider (png/jpeg/ktx2) -----------
+  const images: any[] = json.images ?? []
+  const used = collectUsedImages(json)
+  for (let i = 0; i < images.length; i++) {
+    const { format, via } = detectFormat(images[i], json, bin)
+    formats[format] = (formats[format] ?? 0) + 1
+    const supported = (SUPPORTED_IMAGE_FORMATS as readonly string[]).includes(format)
+    if (supported) continue
+
+    const referenced = used.has(i)
+    const issue: GlbIssue = {
+      level: referenced ? 'error' : 'warning',
+      code: 'TEXTURE_FORMAT',
+      message:
+        `image[${i}]${images[i].name ? ` "${images[i].name}"` : ''} is ${format.toUpperCase()} ` +
+        `(${via})${referenced ? '' : ' [unreferenced]'} — only ${SUPPORTED_IMAGE_FORMATS.join('/')} are supported`,
+      detail: { image: i, format, via, referenced },
+    }
+    ;(referenced ? errors : warnings).push(issue)
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    summary: { skins: skins.length, maxJointCount, images: images.length, formats },
+  }
+}
+
+// Human-readable report (string, so it works identically in browser console and Bun stdout).
+export function formatReport(result: GlbValidationResult, label = 'GLB'): string {
+  const lines: string[] = []
+  const s = result.summary
+  lines.push(`${result.ok ? '✅ VALID' : '❌ INVALID'}  ${label}`)
+  lines.push(
+    `  skins=${s.skins} (max joints=${s.maxJointCount}/${MAX_BONE_COUNT})  ` +
+    `images=${s.images} [${Object.entries(s.formats).map(([k, v]) => `${k}:${v}`).join(', ') || 'none'}]`,
+  )
+  for (const e of result.errors) lines.push(`  ✗ ${e.code}: ${e.message}`)
+  for (const w of result.warnings) lines.push(`  ⚠ ${w.code}: ${w.message}`)
+  return lines.join('\n')
+}

package/src/viewer/wasmCrashSymbolizer.ts

@@ -0,0 +1,133 @@
+// Lazy crash symbolizer for the creator-gl wasm. The shipped wasm has no name section
+// (see creator-gl/CMakeLists.txt: --emit-symbol-map), so a runtime trap surfaces as
+// "RuntimeError: unreachable at wasm-function[1234]" with anonymous frames. The build deploys
+// creator-gl.js.symbols (function index -> C++ name) next to the wasm; this module fetches that
+// map ONLY after a crash has already happened and prints a decoded trace to the console. Happy
+// path cost: zero — nothing is fetched or parsed until the first wasm frame appears in an error.
+//
+// The map is only valid for creator-gl.wasm. Frames from another wasm module (creator-ui,
+// creator-2d) carry their own URL in the stack line and are left untouched; frames with no URL
+// at all (Safari's "[wasm code]") are decoded anyway, since a creator-gl trap is by far the
+// likeliest source, and marked with "?" so a misattributed name isn't taken as gospel.
+
+import symbolsUrl from './creator-gl.js.symbols?url'
+
+const WASM_FRAME = /wasm-function\[(\d+)\]/g
+
+// index -> raw (still escaped) name. Parsed once, kept raw — escape decoding runs only on the
+// handful of frames actually printed, not on all ~40k entries.
+let mapPromise: Promise<Map<number, string> | null> | null = null
+
+const loadSymbolMap = (): Promise<Map<number, string> | null> => {
+  if (!mapPromise) {
+    mapPromise = fetch(symbolsUrl)
+      .then(resp => {
+        if (!resp.ok) throw new Error(`${resp.status} ${resp.statusText}`)
+        return resp.text()
+      })
+      .then(text => {
+        const map = new Map<number, string>()
+        for (const line of text.split('\n')) {
+          const sep = line.indexOf(':')
+          if (sep > 0) map.set(Number(line.slice(0, sep)), line.slice(sep + 1))
+        }
+        return map
+      })
+      .catch(e => {
+        console.warn('[creator-gl] creator-gl.js.symbols unavailable, wasm frames stay anonymous:', e)
+        return null
+      })
+  }
+  return mapPromise
+}
+
+// The symbol map escapes non-identifier chars as \XX hex (emscripten format): \20 = space,
+// \2c = comma, \28\29 = parens.
+const decodeName = (raw: string): string =>
+  raw.replace(/\\([0-9a-fA-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+
+// Which wasm module does this stack line reference? Matches "creator-ui.wasm:",
+// "creator-gl-B3xYz9.wasm)" etc., but not the ".wasm-function[N]" token itself (the lookahead
+// rejects the "-f"). The name is matched loosely ("creator-gl" prefix) because Vite hashes prod
+// asset filenames. null = no module URL in the line (Safari's "[wasm code]").
+const MODULE_REF = /([\w.-]+)\.wasm(?=[^\w-]|$)/g
+const lineModule = (line: string): 'ours' | 'other' | null => {
+  const refs = [...line.matchAll(MODULE_REF)].map(m => m[1]!)
+  if (refs.length === 0) return null
+  return refs.some(r => r.includes('creator-gl')) ? 'ours' : 'other'
+}
+
+/**
+ * Decode every creator-gl `wasm-function[N]` frame in a stack trace. Resolves to null when the
+ * stack has no wasm frames (or the symbol map can't be fetched) — callers use that to stay
+ * silent for ordinary JS errors.
+ */
+export const symbolizeWasmStack = async (stack: string): Promise<string | null> => {
+  WASM_FRAME.lastIndex = 0
+  if (!WASM_FRAME.test(stack)) return null
+  const map = await loadSymbolMap()
+  if (!map) return null
+
+  let decodedAny = false
+  const lines = stack.split('\n').map(line => {
+    WASM_FRAME.lastIndex = 0
+    if (!WASM_FRAME.test(line)) return line
+    const mod = lineModule(line)
+    // A frame naming a different wasm module belongs to that module's map, not ours. URL-less
+    // frames are decoded anyway (a creator-gl trap is by far the likeliest source) but marked "?".
+    if (mod === 'other') return line
+    return line.replace(WASM_FRAME, (frame, index) => {
+      const raw = map.get(Number(index))
+      if (raw === undefined) return frame
+      decodedAny = true
+      return `${mod === null ? '?' : ''}${decodeName(raw)} (${frame})`
+    })
+  })
+  return decodedAny ? lines.join('\n') : null
+}
+
+/**
+ * The display-friendly cut of symbolizeWasmStack for UI overlays: just the decoded C++ names of
+ * the creator-gl frames, top-first — no URLs, no JS glue frames. Empty when the stack has no
+ * decodable creator-gl frames (or the map can't be fetched).
+ */
+export const symbolizeWasmFrames = async (stack: string): Promise<string[]> => {
+  WASM_FRAME.lastIndex = 0
+  if (!WASM_FRAME.test(stack)) return []
+  const map = await loadSymbolMap()
+  if (!map) return []
+  const names: string[] = []
+  for (const line of stack.split('\n')) {
+    if (lineModule(line) === 'other') continue
+    for (const m of line.matchAll(WASM_FRAME)) {
+      const raw = map.get(Number(m[1]))
+      // libc++'s internal namespace is pure noise in a UI overlay.
+      if (raw !== undefined) names.push(decodeName(raw).replaceAll('std::__2::', 'std::'))
+    }
+  }
+  return names
+}
+
+/** Fire-and-forget: print a decoded trace for `err` if it contains creator-gl wasm frames. */
+export const symbolizeWasmError = (err: unknown): void => {
+  const stack = (err as { stack?: unknown } | null)?.stack
+  if (typeof stack !== 'string') return
+  symbolizeWasmStack(stack).then(decoded => {
+    if (decoded) console.error('[creator-gl] decoded wasm stack (via creator-gl.js.symbols):\n' + decoded)
+  })
+}
+
+let installed = false
+
+/**
+ * Catch wasm traps that escape to the top (the render rAF loop has no try/catch — an engine
+ * crash lands on the global 'error' event) and follow the browser's own report with a decoded
+ * trace. Errors swallowed by app-level try/catch never get here — those paths call
+ * symbolizeWasmError directly (see createGlb/loadGlb).
+ */
+export const installWasmCrashSymbolizer = (): void => {
+  if (installed) return
+  installed = true
+  addEventListener('error', e => symbolizeWasmError((e as ErrorEvent).error))
+  addEventListener('unhandledrejection', e => symbolizeWasmError((e as PromiseRejectionEvent).reason))
+}