lecodes-gl-lite 2.0.0

package/src/webgl/customMaterial.ts

@@ -0,0 +1,228 @@
+// Custom .mat materials for the lite 3D engine.
+//
+// The backend compiles every shader asset with matc for the native platforms; for Web Lite it
+// additionally emits a JSON artifact (sdk/src/compile/liteMaterial.ts is the source of
+// truth for the format — the type below mirrors it): the parsed .mat definition plus the author's
+// fragment body with `materialParams.x` already rewritten to `materialParams_x`. This module wraps
+// that body in the lite engine's own GLSL frame — the MaterialInputs struct, getUV0()-style
+// accessors, and the shared PBR lighting chunk — so a custom material shades consistently with
+// everything else lite renders (approximate vs Filament by design; exact parity is what the full
+// viewer is for).
+//
+// Kept free of WebGL so the assembly logic is bun-testable; createViewerLite owns Program creation.
+
+import { LIGHTING_CHUNK } from './shaders'
+
+export type LiteMaterialParam = { name: string, type: string, size?: number }
+
+/** Mirror of sdk/compile liteMaterial.ts `LiteMaterialArtifact`. */
+export type LiteMaterialArtifact = {
+  lecodesLiteMaterial: 1
+  shadingModel: 'lit' | 'unlit'
+  blending: 'opaque' | 'transparent' | 'fade' | 'add' | 'masked'
+  maskThreshold: number
+  doubleSided: boolean
+  culling: 'back' | 'front' | 'none'
+  depthWrite: boolean
+  /** Filament's shadow-catcher flag (unlit + transparent, matc-enforced) */
+  shadowMultiplier: boolean
+  params: LiteMaterialParam[]
+  samplers: { name: string }[]
+  fragmentCode: string
+  writesNormal: boolean
+  hasVertexBlock: boolean
+  unsupported?: string
+}
+
+/** Decode a fetched shader buffer as a lite material artifact; null for anything else
+ *  (binary filamat packages, error pages, the built-ins' empty local buffers). */
+export const parseLiteMaterial = (buf: ArrayBuffer | null | undefined): LiteMaterialArtifact | null => {
+  if (!buf || buf.byteLength < 24 || buf.byteLength > 1_000_000) return null
+  if (new Uint8Array(buf, 0, 1)[0] !== 0x7b) return null // '{'
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(buf))
+    return parsed?.lecodesLiteMaterial === 1 ? parsed as LiteMaterialArtifact : null
+  } catch {
+    return null
+  }
+}
+
+// ---- GLSL assembly ------------------------------------------------------------------------------
+
+const GLSL_TYPE: Record<string, { decl: string, zero: number | number[] | Float32Array }> = {
+  float: { decl: 'float', zero: 0 },
+  float2: { decl: 'vec2', zero: [0, 0] },
+  float3: { decl: 'vec3', zero: [0, 0, 0] },
+  float4: { decl: 'vec4', zero: [0, 0, 0, 0] },
+  int: { decl: 'int', zero: 0 },
+  int2: { decl: 'ivec2', zero: [0, 0] },
+  int3: { decl: 'ivec3', zero: [0, 0, 0] },
+  int4: { decl: 'ivec4', zero: [0, 0, 0, 0] },
+  bool: { decl: 'bool', zero: 0 },
+  bool2: { decl: 'bvec2', zero: [0, 0] },
+  bool3: { decl: 'bvec3', zero: [0, 0, 0] },
+  bool4: { decl: 'bvec4', zero: [0, 0, 0, 0] },
+  float3x3: { decl: 'mat3', zero: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1]) },
+  float4x4: { decl: 'mat4', zero: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]) },
+}
+
+// The subset of Filament's material API that authored fragment code commonly touches. The struct
+// carries the full lit field set even for unlit materials — writes to ignored fields are harmless
+// and more forgiving than a compile error.
+const MATERIAL_API_CHUNK = /* glsl */ `
+struct MaterialInputs {
+  vec4 baseColor;
+  float roughness;
+  float metallic;
+  float reflectance;
+  float ambientOcclusion;
+  vec4 emissive;
+  vec3 normal;
+  float clearCoat;
+  float clearCoatRoughness;
+  vec4 postLightingColor;
+};
+void prepareMaterial(inout MaterialInputs m) {}
+vec2 getUV0() { return vUv; }
+vec2 getUV1() { return vUv; }
+vec3 getWorldPosition() { return vWorldPos; }
+vec3 getWorldGeometricNormalVector() { return normalize(vNormal); }
+vec3 getWorldViewVector() { return normalize(cameraPosition - vWorldPos); }
+vec4 getUserTime() { return userTime; }
+`
+
+// Filament defaults (common_material shading setup).
+const INPUT_DEFAULTS = /* glsl */ `
+  MaterialInputs inputs;
+  inputs.baseColor = vec4(1.0);
+  inputs.roughness = 1.0;
+  inputs.metallic = 0.0;
+  inputs.reflectance = 0.5;
+  inputs.ambientOcclusion = 1.0;
+  inputs.emissive = vec4(0.0, 0.0, 0.0, 1.0);
+  inputs.normal = vec3(0.0, 0.0, 1.0);
+  inputs.clearCoat = 0.0;
+  inputs.clearCoatRoughness = 0.0;
+  inputs.postLightingColor = vec4(0.0);
+  material(inputs);
+`
+
+// Tangent-frame from screen-space derivatives (same approach as the glTF normal-map path) — only
+// included when the fragment writes MaterialInputs.normal.
+const TANGENT_NORMAL_CHUNK = /* glsl */ `
+vec3 applyTangentNormal(vec3 nTangent, vec3 ng) {
+  vec3 pos_dx = dFdx(vWorldPos);
+  vec3 pos_dy = dFdy(vWorldPos);
+  vec2 tex_dx = dFdx(vUv);
+  vec2 tex_dy = dFdy(vUv);
+  float det = tex_dx.x * tex_dy.y - tex_dy.x * tex_dx.y;
+  if (abs(det) < 1e-8) return ng;
+  vec3 t = normalize(pos_dx * tex_dy.y - pos_dy * tex_dx.y);
+  t = normalize(t - ng * dot(ng, t));
+  vec3 b = normalize(cross(ng, t)) * sign(det);
+  return normalize(mat3(t, b, ng) * nTangent);
+}
+`
+
+// Standalone copy of the shared ACES fit for unlit materials (lit gets it from LIGHTING_CHUNK).
+const UNLIT_TONEMAP_CHUNK = /* glsl */ `
+vec3 tonemap(vec3 x) {
+  const float A = 2.51; const float B = 0.03; const float C = 2.43; const float D = 0.59; const float E = 0.14;
+  vec3 t = clamp((x * (A * x + B)) / (x * (C * x + D) + E), 0.0, 1.0);
+  return pow(t, vec3(1.0 / 2.2));
+}
+`
+
+export type CustomUniformSpec = { key: string, value: number | number[] | Float32Array | 'texture' }
+
+export type CustomProgramSpec = {
+  fragment: string
+  uniforms: CustomUniformSpec[]
+  /** parameter names as the SDK sets them — materialUniform maps these to materialParams_<name> */
+  paramNames: Set<string>
+  /** the program references the shared lighting/shadow uniforms (lit or shadowMultiplier) */
+  needsSceneUniforms: boolean
+}
+
+/** Assemble the fragment shader + uniform skeleton for a lite material artifact.
+ *  Returns null when the artifact declares something this build can't express (defensive —
+ *  the backend already gates types via `unsupported`). */
+export const buildCustomProgram = (artifact: LiteMaterialArtifact): CustomProgramSpec | null => {
+  if (artifact.unsupported) return null
+
+  const decls: string[] = []
+  const uniforms: CustomUniformSpec[] = []
+  const paramNames = new Set<string>()
+  for (const p of artifact.params) {
+    const glsl = GLSL_TYPE[p.type]
+    if (!glsl) return null
+    decls.push(`uniform ${glsl.decl} materialParams_${p.name}${p.size ? `[${p.size}]` : ''};`)
+    const zero = p.size
+      ? new Array(p.size * (Array.isArray(glsl.zero) ? glsl.zero.length : glsl.zero instanceof Float32Array ? glsl.zero.length : 1)).fill(0)
+      : glsl.zero
+    uniforms.push({ key: `materialParams_${p.name}`, value: Array.isArray(zero) ? [...zero] : zero })
+    paramNames.add(p.name)
+  }
+  for (const s of artifact.samplers) {
+    decls.push(`uniform sampler2D materialParams_${s.name};`)
+    uniforms.push({ key: `materialParams_${s.name}`, value: 'texture' })
+    paramNames.add(s.name)
+  }
+
+  const lit = artifact.shadingModel === 'lit'
+  const needsSceneUniforms = lit || artifact.shadowMultiplier
+  const opaque = artifact.blending === 'opaque' || artifact.blending === 'masked'
+  const masked = artifact.blending === 'masked'
+    ? `if (inputs.baseColor.a < ${artifact.maskThreshold.toFixed(4)}) discard;` : ''
+  const alpha = opaque ? '1.0' : 'inputs.baseColor.a'
+
+  // Shadow catcher (Filament shadowMultiplier semantics, same output as the built-in
+  // shadowCatcherFragment): baseColor scaled by the received shadow amount, premultiplied —
+  // fully transparent where nothing shades the surface. No tonemap, matching the built-in.
+  const main = artifact.shadowMultiplier ? /* glsl */ `
+void main() {
+${INPUT_DEFAULTS}
+  float shadowAmount = 1.0 - sampleShadowPCF();
+  fragColor = vec4(inputs.baseColor.rgb * shadowAmount, inputs.baseColor.a * shadowAmount);
+}
+` : lit ? /* glsl */ `
+void main() {
+${INPUT_DEFAULTS}
+  ${masked}
+  vec3 n = normalize(vNormal);
+  vec3 v = normalize(cameraPosition - vWorldPos);
+  ${artifact.doubleSided ? 'if (dot(n, v) < 0.0) n = -n;' : ''}
+  ${artifact.writesNormal ? 'n = applyTangentNormal(inputs.normal, n);' : ''}
+  vec3 diffuseColor = inputs.baseColor.rgb * (1.0 - inputs.metallic);
+  vec3 f0 = mix(vec3(0.16 * inputs.reflectance * inputs.reflectance), inputs.baseColor.rgb, inputs.metallic);
+  vec3 color = shadePBR(n, v, diffuseColor, f0, inputs.roughness, inputs.ambientOcclusion);
+  color += inputs.emissive.rgb * (iblLuminance * exposure);
+  color += inputs.postLightingColor.rgb;
+  fragColor = vec4(tonemap(color), ${alpha});
+}
+` : /* glsl */ `
+void main() {
+${INPUT_DEFAULTS}
+  ${masked}
+  vec3 color = inputs.baseColor.rgb + inputs.emissive.rgb + inputs.postLightingColor.rgb;
+  fragColor = vec4(tonemap(color), ${alpha});
+}
+`
+
+  const fragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec3 cameraPosition;
+uniform vec4 userTime;
+${decls.join('\n')}
+${needsSceneUniforms ? LIGHTING_CHUNK : UNLIT_TONEMAP_CHUNK}
+${MATERIAL_API_CHUNK}
+${artifact.writesNormal ? TANGENT_NORMAL_CHUNK : ''}
+out vec4 fragColor;
+${artifact.fragmentCode}
+${main}`
+
+  return { fragment, uniforms, paramNames, needsSceneUniforms }
+}

package/src/webgl/decoders/basis.ts

@@ -0,0 +1,123 @@
+// Lazy KTX2 / Basis Universal texture transcoder for OGL's GLTFLoader (KHR_texture_basisu,
+// `image/ktx2` images). Implements the interface GLTFLoader.setBasisManager expects:
+// `parseTexture(ktx2Data)` → Promise of an image OGL's Texture can upload.
+//
+// Two result shapes:
+// - GPU compressed (astc / bptc / s3tc, picked from the context's extensions): an array of mip
+//   levels `[{ data, width, height }]` with `isCompressedTexture` + `internalFormat` — OGL's
+//   Texture uploads each level via compressedTexImage2D. Only taken when the KTX2 carries a FULL
+//   mip chain (compressed textures can't generate mips on the GPU; a partial chain would sample
+//   as an incomplete texture).
+// - Fallback (no compressed format, partial mip chain, cubemaps): level 0 transcoded to RGBA32 as
+//   an ImageBitmap on the normal image path — mips regenerate GPU-side.
+//
+// Transcoder build: basis_transcoder.js/.wasm vendored from three.js (the upstream
+// BinomialLLC/basis_universal artifact), vendored in src/assets/decoders.
+
+import glueText from '../../assets/decoders/basis_transcoder.js?raw'
+import wasmUrl from '../../assets/decoders/basis_transcoder.wasm?url'
+import { spawnDecoderWorker } from './worker'
+
+export type BasisFormat = 'astc' | 'bptc' | 's3tc' | 'rgba32'
+
+/** linear + sRGB sibling internal formats per transcode target (sRGB applied by glb.ts markSrgb). */
+export const BASIS_INTERNAL_FORMATS: Record<Exclude<BasisFormat, 'rgba32'>, { linear: number, srgb: number }> = {
+  astc: { linear: 0x93b0, srgb: 0x93d0 },  // COMPRESSED_RGBA_ASTC_4x4_KHR / SRGB8_ALPHA8_ASTC_4x4_KHR
+  bptc: { linear: 0x8e8c, srgb: 0x8e8d },  // COMPRESSED_RGBA_BPTC_UNORM / COMPRESSED_SRGB_ALPHA_BPTC_UNORM
+  s3tc: { linear: 0x83f3, srgb: 0x8c4f },  // COMPRESSED_RGBA_S3TC_DXT5_EXT / COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT
+}
+
+// getExtension() also ENABLES the format on the context — required before compressedTexImage2D.
+const pickFormat = (gl: any): { format: BasisFormat, srgbOk: boolean } => {
+  if (gl.getExtension('WEBGL_compressed_texture_astc')) return { format: 'astc', srgbOk: true }
+  if (gl.getExtension('EXT_texture_compression_bptc')) return { format: 'bptc', srgbOk: true }
+  if (gl.getExtension('WEBGL_compressed_texture_s3tc')) {
+    return { format: 's3tc', srgbOk: !!gl.getExtension('WEBGL_compressed_texture_s3tc_srgb') }
+  }
+  return { format: 'rgba32', srgbOk: true }
+}
+
+// Runs inside the Blob worker AFTER the basis glue — only globals, no closure over this module.
+const basisWorkerBody = () => {
+  const scope = self as any
+  let modulePromise: Promise<any>
+  // basis transcoder_texture_format values (stable upstream enum)
+  const FORMAT_ENUM: Record<string, number> = { astc: 10, bptc: 6, s3tc: 3, rgba32: 13 }
+
+  const transcode = async (m: any, buffer: ArrayBuffer, format: string) => {
+    const ktx2 = new m.KTX2File(new Uint8Array(buffer))
+    try {
+      if (!ktx2.isValid()) throw new Error('invalid KTX2 file')
+      const width = ktx2.getWidth(), height = ktx2.getHeight(), levels = ktx2.getLevels()
+      if (!width || !height || !levels) throw new Error('empty KTX2 file')
+      if (!ktx2.startTranscoding()) throw new Error('KTX2 transcode init failed')
+
+      const fullChain = levels >= Math.floor(Math.log2(Math.max(width, height))) + 1
+      if (format !== 'rgba32' && fullChain && ktx2.getFaces() === 1) {
+        const fmt = FORMAT_ENUM[format]
+        const out: any[] = []
+        for (let level = 0; level < levels; level++) {
+          const info = ktx2.getImageLevelInfo(level, 0, 0)
+          const data = new Uint8Array(ktx2.getImageTranscodedSizeInBytes(level, 0, 0, fmt))
+          if (!ktx2.transcodeImage(data, level, 0, 0, fmt, 0, -1, -1)) throw new Error('KTX2 level transcode failed')
+          out.push({ data, width: info.origWidth, height: info.origHeight })
+        }
+        return { msg: { levels: out }, transfer: out.map((l) => l.data.buffer) }
+      }
+
+      const data = new Uint8Array(ktx2.getImageTranscodedSizeInBytes(0, 0, 0, FORMAT_ENUM.rgba32))
+      if (!ktx2.transcodeImage(data, 0, 0, 0, FORMAT_ENUM.rgba32, 0, -1, -1)) throw new Error('KTX2 transcode failed')
+      const bitmap = await createImageBitmap(new ImageData(new Uint8ClampedArray(data.buffer), width, height))
+      return { msg: { bitmap }, transfer: [bitmap] }
+    } finally {
+      ktx2.close()
+      ktx2.delete()
+    }
+  }
+
+  scope.onmessage = (e: MessageEvent) => {
+    const msg = e.data
+    if (msg.type === 'init') {
+      modulePromise = scope.BASIS({ wasmBinary: msg.wasmBinary }).then((m: any) => { m.initializeBasis(); return m })
+      return
+    }
+    modulePromise.then(async (m) => {
+      try {
+        const res = await transcode(m, msg.buffer, msg.format)
+        scope.postMessage({ id: msg.id, ...res.msg }, res.transfer)
+      } catch (err: any) {
+        scope.postMessage({ id: msg.id, error: String((err && err.message) || err) })
+      }
+    })
+  }
+}
+
+/** `gl` null = no GPU in play: transcode to plain RGBA32 (a picture of the texture rather than a
+ *  texture — the scene editor's KTX2 thumbnails). */
+export const createBasisManager = async (gl: any | null) => {
+  const { format, srgbOk } = gl ? pickFormat(gl) : { format: 'rgba32' as BasisFormat, srgbOk: true }
+  const call = await spawnDecoderWorker(glueText, wasmUrl, basisWorkerBody)
+  return {
+    parseTexture: async (buffer: ArrayBuffer): Promise<any> => {
+      const r = await call({ buffer, format })
+      if (r.bitmap) {
+        // normal (uncompressed) image path: GLTFLoader awaits `ready`, then assigns texture.image
+        r.bitmap.ready = Promise.resolve()
+        return r.bitmap
+      }
+      const fmts = BASIS_INTERNAL_FORMATS[format as Exclude<BasisFormat, 'rgba32'>]
+      return Object.assign(r.levels as any[], {
+        // isBasis routes GLTFLoader.createTexture onto its compressed branch (options.image +
+        // internalFormat); the bitmap fallback deliberately leaves it unset to ride the normal
+        // image path (ready → texture.image) and get GPU mipmap generation.
+        isBasis: true,
+        isCompressedTexture: true,
+        internalFormat: fmts.linear,
+        // markSrgb (glb.ts) swaps to this for baseColor/emissive; 0 = leave linear (ext missing)
+        srgbInternalFormat: srgbOk ? fmts.srgb : 0,
+        width: r.levels[0].width,
+        height: r.levels[0].height,
+      })
+    },
+  }
+}

package/src/webgl/decoders/draco.ts

@@ -0,0 +1,110 @@
+// Lazy Draco geometry decoder for OGL's GLTFLoader (KHR_draco_mesh_compression).
+//
+// The manager implements the exact interface GLTFLoader.setDracoManager expects:
+// `decodeGeometry(bufferViewData, { attributeIds, attributeTypes })` → Promise of
+// `{ attributes: [{ name, array, itemSize }], index?: { array, itemSize } }`.
+// The worker body is adapted from three.js' DRACOWorker against the same google decoder build
+// (draco_wasm_wrapper.js + draco_decoder.wasm, vendored in src/assets/decoders).
+
+import glueText from '../../assets/decoders/draco_wasm_wrapper.js?raw'
+import wasmUrl from '../../assets/decoders/draco_decoder.wasm?url'
+import { spawnDecoderWorker } from './worker'
+
+// Runs inside the Blob worker AFTER the draco glue — only globals, no closure over this module.
+const dracoWorkerBody = () => {
+  const scope = self as any
+  let decoderPromise: Promise<any>
+
+  const decodeAttribute = (draco: any, decoder: any, geom: any, name: string, typeName: string, attribute: any) => {
+    const numComponents = attribute.num_components()
+    const numValues = geom.num_points() * numComponents
+    const TypedArray = scope[typeName]
+    const dataType = ({
+      Float32Array: draco.DT_FLOAT32, Int8Array: draco.DT_INT8, Int16Array: draco.DT_INT16,
+      Int32Array: draco.DT_INT32, Uint8Array: draco.DT_UINT8, Uint16Array: draco.DT_UINT16,
+      Uint32Array: draco.DT_UINT32,
+    } as Record<string, unknown>)[typeName]
+    const byteLength = numValues * TypedArray.BYTES_PER_ELEMENT
+    const ptr = draco._malloc(byteLength)
+    decoder.GetAttributeDataArrayForAllPoints(geom, attribute, dataType, byteLength, ptr)
+    const array = new TypedArray(draco.HEAPF32.buffer, ptr, numValues).slice()
+    draco._free(ptr)
+    return { name, array, itemSize: numComponents }
+  }
+
+  const decode = (draco: any, buffer: ArrayBuffer, config: any) => {
+    const decoder = new draco.Decoder()
+    const dbuf = new draco.DecoderBuffer()
+    dbuf.Init(new Int8Array(buffer), buffer.byteLength)
+    let geom: any
+    try {
+      const type = decoder.GetEncodedGeometryType(dbuf)
+      let status: any
+      if (type === draco.TRIANGULAR_MESH) {
+        geom = new draco.Mesh()
+        status = decoder.DecodeBufferToMesh(dbuf, geom)
+      } else {
+        geom = new draco.PointCloud()
+        status = decoder.DecodeBufferToPointCloud(dbuf, geom)
+      }
+      if (!status.ok() || geom.ptr === 0) throw new Error('draco decode failed: ' + status.error_msg())
+
+      const attributes: any[] = []
+      for (const name in config.attributeIds) {
+        const attribute = decoder.GetAttributeByUniqueId(geom, config.attributeIds[name])
+        attributes.push(decodeAttribute(draco, decoder, geom, name, config.attributeTypes[name], attribute))
+      }
+      const geometry: any = { attributes }
+      if (type === draco.TRIANGULAR_MESH) {
+        const numIndices = geom.num_faces() * 3
+        const byteLength = numIndices * 4
+        const ptr = draco._malloc(byteLength)
+        decoder.GetTrianglesUInt32Array(geom, byteLength, ptr)
+        geometry.index = { array: new Uint32Array(draco.HEAPF32.buffer, ptr, numIndices).slice(), itemSize: 1 }
+        draco._free(ptr)
+      }
+      return geometry
+    } finally {
+      if (geom) draco.destroy(geom)
+      draco.destroy(dbuf)
+      draco.destroy(decoder)
+    }
+  }
+
+  scope.onmessage = (e: MessageEvent) => {
+    const msg = e.data
+    if (msg.type === 'init') {
+      decoderPromise = new Promise((res) => scope.DracoDecoderModule({ wasmBinary: msg.wasmBinary, onModuleLoaded: res }))
+      return
+    }
+    decoderPromise.then((draco) => {
+      try {
+        const geometry = decode(draco, msg.buffer, msg.config)
+        const transfer = geometry.attributes.map((a: any) => a.array.buffer)
+        if (geometry.index) transfer.push(geometry.index.array.buffer)
+        scope.postMessage({ id: msg.id, geometry }, transfer)
+      } catch (err: any) {
+        scope.postMessage({ id: msg.id, error: String((err && err.message) || err) })
+      }
+    })
+  }
+}
+
+/** De-instanced shared meshes (dedupeSharedMeshes) decode the same draco bufferView once per copy —
+ *  cache by the bufferView's data buffer so N references cost ONE decode (GL buffers still
+ *  duplicate downstream; that's the de-instancing tradeoff). */
+const decodeCache = new WeakMap<ArrayBuffer, Promise<any>>()
+
+export const createDracoManager = async () => {
+  const call = await spawnDecoderWorker(glueText, wasmUrl, dracoWorkerBody)
+  return {
+    decodeGeometry: (buffer: ArrayBuffer, config: unknown): Promise<any> => {
+      let p = decodeCache.get(buffer)
+      if (!p) {
+        p = call({ buffer, config }).then((r) => r.geometry)
+        decodeCache.set(buffer, p)
+      }
+      return p
+    },
+  }
+}

package/src/webgl/decoders/index.ts

@@ -0,0 +1,68 @@
+// Lazy compressed-GLB decoders (Draco geometry, KTX2/Basis textures) for the lite engine.
+//
+// glb.ts pulls this module in via dynamic import ONLY when a GLB actually declares the extension,
+// so plain models never pay for it. Each decoder is a module-level singleton promise — ONE worker
+// + one wasm fetch shared by every concurrent load, every host, every scene on the page. A failed
+// bring-up (offline, blocked wasm) resets the singleton so a later load can retry, and the failing
+// model degrades to structure entities via loadGlbLite's normal error path.
+
+import { GLTFLoader } from 'ogl'
+
+let dracoReady: Promise<void> | null = null
+let basisReady: Promise<void> | null = null
+let basisManager: { parseTexture: (buffer: ArrayBuffer) => Promise<any> } | null = null
+
+/** 12-byte KTX2 magic («KTX 20» CR LF 0x1A LF). */
+const KTX2_MAGIC = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]
+export const isKtx2Bytes = (b: Uint8Array): boolean => b.length >= 12 && KTX2_MAGIC.every((v, i) => b[i] === v)
+
+/** KHR_DF_TRANSFER from the KTX2 DFD: true = sRGB (colour), false = linear (data maps). */
+export const ktx2IsSrgb = (buf: ArrayBuffer): boolean => {
+  if (buf.byteLength < 80) return true
+  const dv = new DataView(buf)
+  const dfd = dv.getUint32(48, true)
+  if (dfd + 15 > buf.byteLength) return true
+  return dv.getUint8(dfd + 14) !== 1 // 1 = LINEAR, 2 = SRGB (default to sRGB when unspecified)
+}
+
+/**
+ * The same transcoder GLB loads use, for a standalone KTX2 file (Texture.load). Resolves to either
+ * an ImageBitmap (rgba32 fallback) or a compressed level array (isCompressedTexture +
+ * internalFormat / srgbInternalFormat) — see createBasisManager.parseTexture.
+ */
+export const transcodeKtx2 = async (gl: any, buffer: ArrayBuffer): Promise<any> => {
+  await ensureBasisTranscoder(gl)
+  return basisManager!.parseTexture(buffer)
+}
+
+/**
+ * A .ktx2 file as a PICTURE (ImageBitmap), for hosts that want to SHOW the texture rather than
+ * upload it — the scene editor's asset thumbnails. Keeps its own transcoder singleton: the
+ * engine's manager is bound to whatever compressed format its context picked, and a compressed
+ * level array can't be drawn to a canvas.
+ */
+let imageBasis: Promise<{ parseTexture: (buffer: ArrayBuffer) => Promise<any> }> | null = null
+export const decodeKtx2Image = async (buffer: ArrayBuffer): Promise<ImageBitmap> => {
+  imageBasis ??= import('./basis')
+    .then(({ createBasisManager }) => createBasisManager(null))
+    .catch((e) => { imageBasis = null; throw e })
+  const image = await (await imageBasis).parseTexture(buffer)
+  if (!image || (image as any).isCompressedTexture) throw new Error('KTX2 did not transcode to an image')
+  return image as ImageBitmap
+}
+
+export const ensureDracoDecoder = (): Promise<void> => {
+  dracoReady ??= import('./draco')
+    .then(({ createDracoManager }) => createDracoManager())
+    .then((manager) => { (GLTFLoader as any).setDracoManager(manager) })
+    .catch((e) => { dracoReady = null; throw e })
+  return dracoReady
+}
+
+export const ensureBasisTranscoder = (gl: any): Promise<void> => {
+  basisReady ??= import('./basis')
+    .then(({ createBasisManager }) => createBasisManager(gl))
+    .then((manager) => { basisManager = manager; (GLTFLoader as any).setBasisManager(manager) })
+    .catch((e) => { basisReady = null; throw e })
+  return basisReady
+}

package/src/webgl/decoders/worker.ts

@@ -0,0 +1,45 @@
+// Shared plumbing for the lazy GLB decoder workers (draco geometry, basis/KTX2 textures).
+//
+// Each decoder is an emscripten classic-script glue (`var DracoDecoderModule = ...` / `var BASIS
+// = ...`, vendored in src/assets/decoders) plus a wasm binary. We build the worker from a Blob:
+// glue text + our stringified worker body — no bundler worker plumbing, works identically in vite
+// dev and library builds. The wasm is fetched on the main thread (a plain `?url` asset) and handed
+// to the worker via the init message, so the whole decoder costs nothing until the first
+// compressed model actually needs it.
+
+export type WorkerRpc = (msg: Record<string, unknown>, transfer?: Transferable[]) => Promise<any>
+
+export const spawnDecoderWorker = async (
+  glueText: string,
+  wasmUrl: string,
+  body: () => void,
+): Promise<WorkerRpc> => {
+  const wasmBinary = await fetch(wasmUrl).then((r) => {
+    if (!r.ok) throw new Error(`decoder wasm fetch failed (${r.status}) — ${wasmUrl}`)
+    return r.arrayBuffer()
+  })
+  const blob = new Blob([glueText, '\n;(', body.toString(), ')();'], { type: 'application/javascript' })
+  const worker = new Worker(URL.createObjectURL(blob))
+  worker.postMessage({ type: 'init', wasmBinary }, [wasmBinary])
+
+  let nextId = 1
+  const pending = new Map<number, { resolve: (v: any) => void, reject: (e: Error) => void }>()
+  worker.onmessage = ({ data }) => {
+    const p = pending.get(data.id)
+    if (!p) return
+    pending.delete(data.id)
+    if (data.error) p.reject(new Error(data.error))
+    else p.resolve(data)
+  }
+  worker.onerror = (e) => {
+    // a worker-level crash (bad glue, wasm compile failure) fails every in-flight decode
+    const err = new Error(`decoder worker error: ${e.message ?? 'unknown'}`)
+    for (const p of pending.values()) p.reject(err)
+    pending.clear()
+  }
+  return (msg, transfer = []) => new Promise((resolve, reject) => {
+    const id = nextId++
+    pending.set(id, { resolve, reject })
+    worker.postMessage({ id, ...msg }, transfer)
+  })
+}