lecodes-web-runtime 2.0.0

package/src/profile.ts

@@ -0,0 +1,50 @@
+/// <reference path="./native.d.ts" />
+// The BROWSER profiles of runtime/web/native/CMakeLists.txt: one Emscripten module per engine set, one
+// heap for every engine in it. A web host loads the profile its bundle needs — the imports below are
+// static strings so a bundler splits each profile into its own chunk and a page that never opens a
+// 3D scene never downloads Filament.
+import type { WasmModule } from "./gen/wasm"
+
+// The other two are not a page's: `headless` is Bun's (runtime/headless loads it itself), `nav` an
+// engine-only twin — named here, a bundler would put both into every browser build.
+export type Profile = "full" | "2d" | "ui"
+
+export type ProfileOptions = {
+  /** creator-gl's WebGL2 context + the attributes it was created with (init() registers it). */
+  glContext?: WebGL2RenderingContext
+  glOptions?: WebGLContextAttributes
+  /** creator-2d's own WebGL2 context (c2dInit registers it) — a second canvas in dual mode. */
+  gl2dContext?: WebGL2RenderingContext
+  gl2dOptions?: WebGLContextAttributes
+  /** Extra Emscripten module arguments (print, printErr, …). */
+  moduleArgs?: Record<string, unknown>
+}
+
+const factories: Record<Profile, () => Promise<{ default: (args?: Record<string, unknown>) => Promise<any> }>> = {
+  full: () => import("../native/dist/creator-full.js"),
+  "2d": () => import("../native/dist/creator-2d.js"),
+  ui: () => import("../native/dist/creator-ui.js"),
+}
+
+// the .wasm beside each module
+const wasmUrl: Record<Profile, () => string> = {
+  full: () => new URL("../native/dist/creator-full.wasm", import.meta.url).href,
+  "2d": () => new URL("../native/dist/creator-2d.wasm", import.meta.url).href,
+  ui: () => new URL("../native/dist/creator-ui.wasm", import.meta.url).href,
+}
+
+/** Instantiate a profile module. The engines' WebGL contexts ride in as module fields (the engines
+ *  read `Module.filament_glContext` / `Module.creator2d_glContext` when they init). */
+export const loadProfileModule = async (profile: Profile, options: ProfileOptions = {}): Promise<WasmModule> => {
+  const factory = (await factories[profile]()).default
+  const url = wasmUrl[profile]()
+  const args: Record<string, unknown> = {
+    locateFile: (file: string) => (file.endsWith(".wasm") ? url : file),
+    ...(options.glContext ? { filament_glContext: options.glContext, filament_glOptions: options.glOptions ?? {} } : {}),
+    ...(options.gl2dContext ? { creator2d_glContext: options.gl2dContext, creator2d_glOptions: options.gl2dOptions ?? {} } : {}),
+    ...options.moduleArgs,
+  }
+  const module = (await factory(args)) as WasmModule
+  if (typeof module._creatorWebVersion !== "function") throw new Error(`creator-web: ${profile} is not a creator-web profile module`)
+  return module
+}

package/src/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 engines/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/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/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 '../native/dist/creator-full.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))
+}