lecodes-gl-lite 2.0.0

package/src/webgl/glb.ts

@@ -0,0 +1,593 @@
+// GLB loading for the lite engine: OGL's GLTFLoader parses the container/geometry/skins/animations,
+// then we replace its placeholder programs with our Filament-calibrated PBR programs (shaders.ts)
+// built from the glTF metallic-roughness material data. The caller (createViewerLite) maps the
+// returned node graph onto bridge entities.
+
+import { GLTFLoader, GLTFSkin, Mesh, Program, Quat, Texture, Transform } from 'ogl'
+import { gltfFragment, gltfVertex } from './shaders'
+
+export type GlbClipChannel = {
+  node: Transform
+  /** `weights` writes the node's morph-weight array (set up by buildMorphState), not a TRS field. */
+  transform: 'position' | 'quaternion' | 'scale' | 'weights'
+  interpolation: 'STEP' | 'LINEAR' | 'CUBICSPLINE'
+  times: ArrayLike<number>
+  values: ArrayLike<number>
+}
+
+export type GlbClip = {
+  name: string
+  duration: number
+  animation: { loop: boolean, duration: number, startTime: number, data: GlbClipChannel[] }
+  /** Unique nodes this clip writes TRS to — recomposed into matrices after each update. */
+  nodes: Transform[]
+}
+
+export type GlbResult = {
+  roots: Transform[]
+  nodes: Transform[]
+  animations: GlbClip[]
+}
+
+export type SceneUniforms = Record<string, { value: unknown }>
+
+// Compression extensions the lite loader has no decoder for. A GLB *requiring* one would render
+// garbage/nothing — loadGlbLite throws instead, and the backend degrades that model to its
+// structure entities (hierarchy + animation clocks, no drawables). Draco and KTX2/basisu are NOT
+// here anymore: their decoders lazy-load on first use (src/gl/decoders).
+const UNSUPPORTED_REQUIRED = [ 'EXT_meshopt_compression' ]
+
+/** OGL's GLTFLoader auto-instances any mesh referenced by more than one node — and then NULLS every
+ *  non-first referencing node (`parseNodes` → "Remove unused nodes just providing an instance
+ *  transform"). That crashes `parseAnimations` on channels targeting those nodes ("Cannot read
+ *  properties of null"), silently bakes per-node animation into static instance matrices, and
+ *  splices `gltf.nodes` out of glTF-index alignment — which the backend relies on to bind loader
+ *  transforms onto the core's index-aligned entities. We want plain per-node drawables: give every
+ *  extra reference its own mesh entry (a shallow copy — primitives/accessors stay shared in the
+ *  JSON; only the GL-side Geometry duplicates). Exported for tests. */
+export const dedupeSharedMeshes = (desc: { nodes?: { mesh?: number }[], meshes?: Record<string, unknown>[] }): void => {
+  const meshes = desc.meshes
+  if (!meshes) return
+  const seen = new Set<number>()
+  for (const n of desc.nodes ?? []) {
+    if (n.mesh === undefined || !meshes[n.mesh]) continue
+    if (seen.has(n.mesh)) {
+      meshes.push({ ...meshes[n.mesh] })
+      n.mesh = meshes.length - 1
+    } else {
+      seen.add(n.mesh)
+    }
+  }
+}
+
+export type MorphChannelRef = {
+  anim: number
+  node: number
+  input: number
+  output: number
+  interpolation: 'STEP' | 'LINEAR' | 'CUBICSPLINE'
+}
+
+/** OGL has no morph-target support: a `weights` animation channel maps through its TRANSFORMS
+ *  table to `undefined`, and GLTFAnimation.update would crash on `node[undefined].lerp` EVERY
+ *  frame — killing the whole render loop (city.scene.ts: snake.glb carries 4 such channels).
+ *  Remove them from the desc BEFORE parse and return refs so loadGlbLite can re-attach them to
+ *  OUR sampler afterwards — morph support (buildMorphState + the HAS_MORPH programs) is ours,
+ *  not OGL's. Animations left with zero channels are KEPT so clip indices stay glTF-aligned;
+ *  a morph-only clip still becomes a working GlbClip. Exported for tests. */
+export const extractMorphAnimationChannels = (
+  desc: { animations?: { channels: { sampler?: number, target?: { node?: number, path?: string } }[], samplers?: { input: number, output: number, interpolation?: string }[] }[] },
+): MorphChannelRef[] => {
+  const out: MorphChannelRef[] = []
+  ;(desc.animations ?? []).forEach((anim, ai) => {
+    const kept: typeof anim.channels = []
+    for (const c of anim.channels ?? []) {
+      const sampler = c.sampler !== undefined ? anim.samplers?.[c.sampler] : undefined
+      if (c.target?.path === 'weights' && c.target.node !== undefined && sampler) {
+        out.push({
+          anim: ai, node: c.target.node,
+          input: sampler.input, output: sampler.output,
+          interpolation: (sampler.interpolation ?? 'LINEAR') as MorphChannelRef['interpolation'],
+        })
+      } else {
+        kept.push(c)
+      }
+    }
+    anim.channels = kept
+  })
+  return out
+}
+
+const COMPONENT_CTORS: Record<number, new (buf: ArrayBuffer, off: number, len: number) => ArrayLike<number>> = {
+  5120: Int8Array, 5121: Uint8Array, 5122: Int16Array, 5123: Uint16Array, 5125: Uint32Array, 5126: Float32Array,
+}
+const NORMALIZE_SCALE: Record<number, number> = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 }
+const TYPE_COMPONENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16 }
+
+/** Read a glTF accessor into a Float32Array (denormalized) straight from the desc + raw GLB
+ *  binary. Unlike OGL's parseAccessor this handles SPARSE accessors and accessors with no
+ *  bufferView (both common for morph targets — only the displaced vertices are stored).
+ *  Exported for tests. */
+export const readAccessorF32 = (desc: any, buffers: (ArrayBuffer | undefined)[], index: number): Float32Array => {
+  const acc = desc?.accessors?.[index]
+  const comps = TYPE_COMPONENTS[acc?.type as string] ?? 1
+  const out = new Float32Array((acc?.count ?? 0) * comps)
+  if (!acc || out.length === 0) return out
+
+  const readRaw = (bufferViewIndex: number, byteOffset: number, componentType: number, count: number, n: number, byteStride: number): Float32Array => {
+    const dst = new Float32Array(count * n)
+    const bv = desc.bufferViews?.[bufferViewIndex]
+    // After OGL's parse, bufferView.buffer is MUTATED from an index into the live WebGLBuffer
+    // (parseBufferViews). A GLB has exactly one binary buffer, so anything non-numeric means 0.
+    const bin = bv ? buffers[typeof bv.buffer === 'number' ? bv.buffer : 0] : undefined
+    const Ctor = COMPONENT_CTORS[componentType]
+    if (!bv || !bin || !Ctor) return dst
+    const elemBytes = (Ctor as any).BYTES_PER_ELEMENT as number
+    const base = (bv.byteOffset ?? 0) + byteOffset
+    if (!byteStride || byteStride === n * elemBytes) {
+      const src = new Ctor(bin, base, count * n)
+      for (let i = 0; i < dst.length; i++) dst[i] = src[i]!
+    } else {
+      for (let i = 0; i < count; i++) {
+        const src = new Ctor(bin, base + i * byteStride, n)
+        for (let k = 0; k < n; k++) dst[i * n + k] = src[k]!
+      }
+    }
+    return dst
+  }
+
+  if (acc.bufferView !== undefined) {
+    out.set(readRaw(acc.bufferView, acc.byteOffset ?? 0, acc.componentType, acc.count, comps, desc.bufferViews?.[acc.bufferView]?.byteStride ?? 0))
+  }
+  if (acc.sparse) {
+    const s = acc.sparse
+    const idx = readRaw(s.indices.bufferView, s.indices.byteOffset ?? 0, s.indices.componentType, s.count, 1, 0)
+    const vals = readRaw(s.values.bufferView, s.values.byteOffset ?? 0, acc.componentType, s.count, comps, 0)
+    for (let i = 0; i < s.count; i++) {
+      for (let k = 0; k < comps; k++) out[idx[i]! * comps + k] = vals[i * comps + k]!
+    }
+  }
+  const scale = acc.normalized ? NORMALIZE_SCALE[acc.componentType] : undefined
+  if (scale) for (let i = 0; i < out.length; i++) out[i] = Math.max(out[i]! / scale, -1)
+  return out
+}
+
+const tmpQuatA = new Quat()
+const tmpQuatB = new Quat()
+
+/** Sample one channel at an absolute clip time, writing the node's TRS component (or its morph
+ *  weights). Values CLAMP to the first/last keyframe outside the channel's time range, per glTF
+ *  spec. */
+const sampleChannel = (ch: GlbClipChannel, elapsed: number): void => {
+  const { node, transform, interpolation, times, values } = ch
+  const isQuat = transform === 'quaternion'
+  const isWeights = transform === 'weights'
+  // weights → the node's Float32Array from buildMorphState (absent = no usable targets; skip)
+  const target: any = isWeights ? (node as any).weights : node[transform]
+  if (!target) return
+  const size = isWeights ? target.length as number : isQuat ? 4 : 3
+  if (size === 0) return
+  const cubic = interpolation === 'CUBICSPLINE'
+  // CUBICSPLINE keyframes are [inTangent, value, outTangent] triplets
+  const stride = cubic ? size * 3 : size
+  const valueOffset = cubic ? size : 0
+  const setAt = (k: number): void => {
+    const o = k * stride + valueOffset
+    if (target.fromArray) target.fromArray(values, o)
+    else for (let i = 0; i < size; i++) target[i] = values[o + i]
+  }
+  const last = times.length - 1
+  if (last === 0 || elapsed <= times[0]!) return setAt(0)
+  if (elapsed >= times[last]!) return setAt(last)
+  let lo = 0, hi = last  // binary search: greatest lo with times[lo] <= elapsed
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1
+    if (times[mid]! <= elapsed) lo = mid
+    else hi = mid
+  }
+  const dt = times[hi]! - times[lo]!
+  const t = interpolation === 'STEP' || dt <= 0 ? 0 : (elapsed - times[lo]!) / dt
+  if (cubic) {
+    // Hermite with tangents scaled by the keyframe interval (glTF spec formula)
+    const t2 = t * t, t3 = t2 * t
+    const s0 = 2 * t3 - 3 * t2 + 1, s1 = dt * (t3 - 2 * t2 + t), s2 = -2 * t3 + 3 * t2, s3 = dt * (t3 - t2)
+    const p0 = lo * stride + size, m0 = lo * stride + size * 2, m1 = hi * stride, p1 = hi * stride + size
+    for (let i = 0; i < size; i++) {
+      target[i] = s0 * (values[p0 + i] as number) + s1 * (values[m0 + i] as number)
+        + s2 * (values[p1 + i] as number) + s3 * (values[m1 + i] as number)
+    }
+    if (isQuat) target.normalize()
+  } else if (isQuat) {
+    tmpQuatA.fromArray(values as number[], lo * 4)
+    tmpQuatB.fromArray(values as number[], hi * 4)
+    tmpQuatA.slerp(tmpQuatB, t)
+    target.copy(tmpQuatA)
+  } else {
+    for (let i = 0; i < size; i++) {
+      const a = values[lo * size + i] as number
+      target[i] = a + t * ((values[hi * size + i] as number) - a)
+    }
+  }
+}
+
+/** Set a clip's pose at `time` (seconds from clip start). Replaces OGL's `GLTFAnimation.update`,
+ *  which EXTRAPOLATES outside a channel's keyframe range (negative/huge alpha from the first
+ *  segment) — city.scene.ts: snake.glb's snowflakes keep scale keys only for t=19.8–24s of a 60s
+ *  clip, so at t=0 OGL put them at scale ≈ −224 instead of the clamped 0.005. The caller
+ *  recomposes matrices from clip.nodes afterwards. Exported for tests. */
+export const sampleClip = (clip: GlbClip, time: number): void => {
+  const anim = clip.animation
+  const elapsed = anim.duration > 0
+    ? (anim.loop ? time % anim.duration : Math.min(time, anim.duration)) + anim.startTime
+    : anim.startTime
+  for (const ch of anim.data) sampleChannel(ch, elapsed)
+}
+
+/** Unique-edge index list (gl.LINES pairs) for a triangle geometry — the wireframe overlay's
+ *  index buffer. `index` is the triangle index data (absent = non-indexed, sequential triples).
+ *  Exported for tests. */
+export const buildEdgeIndices = (index: ArrayLike<number> | undefined, vertexCount: number): Uint16Array | Uint32Array => {
+  const triCount = Math.floor((index ? index.length : vertexCount) / 3)
+  // key = lo·2²⁴ + hi — exact in a double for vertex indices < 16.7M (far beyond any real GLB)
+  const K = 1 << 24
+  const edges = new Set<number>()
+  for (let t = 0; t < triCount; t++) {
+    const a = index ? index[t * 3] : t * 3
+    const b = index ? index[t * 3 + 1] : t * 3 + 1
+    const c = index ? index[t * 3 + 2] : t * 3 + 2
+    edges.add(Math.min(a, b) * K + Math.max(a, b))
+    edges.add(Math.min(b, c) * K + Math.max(b, c))
+    edges.add(Math.min(c, a) * K + Math.max(c, a))
+  }
+  const out = vertexCount > 65535 ? new Uint32Array(edges.size * 2) : new Uint16Array(edges.size * 2)
+  let i = 0
+  for (const key of edges) {
+    out[i++] = Math.floor(key / K)
+    out[i++] = key % K
+  }
+  return out
+}
+
+/** Shared 1x1 white fallback so declared-but-unset samplers are always bound. */
+export const createWhiteTexture = (gl: any): Texture =>
+  new Texture(gl, { image: new Uint8Array([255, 255, 255, 255]), width: 1, height: 1, generateMipmaps: false })
+
+export const createBlackCubemap = (gl: any): Texture => {
+  const tex = new Texture(gl, {
+    target: gl.TEXTURE_CUBE_MAP,
+    width: 1, height: 1,
+    generateMipmaps: false,
+    minFilter: gl.LINEAR,
+  })
+  // OGL's cubemap upload path only accepts TexImageSource faces — typed-array faces make
+  // texImage2D throw ("Overload resolution failed") on first bind, which happens whenever a lit
+  // program renders before the real IBL finished loading, and the throw kills the render loop.
+  // Upload the 1×1 black faces manually and mark the texture clean (same trick as loadIbl).
+  gl.bindTexture(gl.TEXTURE_CUBE_MAP, tex.texture)
+  const black = new Uint8Array(4)
+  for (let i = 0; i < 6; i++) {
+    gl.texImage2D(gl.TEXTURE_CUBE_MAP_POSITIVE_X + i, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, black)
+  }
+  ;(tex as any).store.image = (tex as any).image = black
+  ;(tex as any).needsUpdate = false
+  return tex
+}
+
+// ---- morph targets (blendshapes) --------------------------------------------------------------
+
+/** Uniform array size in the shader (`uMorphWeights[8]`); targets beyond it don't deform. */
+const MAX_MORPH_TARGETS = 8
+
+type MorphInfo = {
+  texture: Texture
+  count: number         // active targets (≤ MAX_MORPH_TARGETS)
+  vertexCount: number
+  texWidth: number
+  hasNormals: boolean
+  /** The node's live weight array — the SAME Float32Array the clip sampler writes, so mutation
+   *  reaches the GPU via OGL's per-draw uniform compare (it caches a copy, not the reference). */
+  weights: Float32Array
+}
+
+/** Build morph state for every node whose mesh carries primitive `targets`: a per-node weight
+ *  array (defaults from node.weights ?? mesh.weights) stored on the OGL node Transform for the
+ *  clip sampler, and per-primitive RGBA32F delta textures (three.js-style, fetched by gl_VertexID)
+ *  tagged onto the OGL meshes as `_morph` for buildProgram. */
+const buildMorphState = (gl: any, desc: any, gltf: any, buffers: (ArrayBuffer | undefined)[]): void => {
+  const nodes = desc.nodes ?? []
+  for (let i = 0; i < nodes.length; i++) {
+    const meshIndex = nodes[i].mesh
+    if (meshIndex === undefined) continue
+    const meshDesc = desc.meshes?.[meshIndex]
+    const prims = meshDesc?.primitives as any[] | undefined
+    if (!prims?.some((p) => p.targets?.length)) continue
+    const nodeTransform = gltf.nodes?.[i]
+    const gltfMesh = gltf.meshes?.[meshIndex]
+    if (!nodeTransform || !gltfMesh) continue
+
+    const targetCount = Math.max(...prims.map((p) => p.targets?.length ?? 0))
+    const weights = new Float32Array(targetCount)
+    const defaults = nodes[i].weights ?? meshDesc.weights
+    if (defaults) for (let k = 0; k < Math.min(targetCount, defaults.length); k++) weights[k] = defaults[k]
+    nodeTransform.weights = weights
+    if (targetCount > MAX_MORPH_TARGETS) {
+      console.warn(`[viewer-lite] GLB: mesh has ${targetCount} morph targets — only the first ${MAX_MORPH_TARGETS} deform`)
+    }
+
+    // Skinned meshes nest per-instance primitive arrays (exactly one after dedupeSharedMeshes).
+    const primList: any[] = Array.isArray(gltfMesh.primitives?.[0]) ? gltfMesh.primitives[0] : gltfMesh.primitives ?? []
+    for (let j = 0; j < prims.length; j++) {
+      const targets = prims[j].targets as { POSITION?: number, NORMAL?: number }[] | undefined
+      const prim = primList[j]
+      if (!targets?.length || !prim?.geometry) continue
+      const vertexCount = prim.geometry.attributes?.position?.count ?? 0
+      if (vertexCount === 0) continue
+      const n = Math.min(targets.length, MAX_MORPH_TARGETS)
+      // Draco-compressed primitives keep their morph deltas as PLAIN accessors in the original
+      // vertex order — encoders are expected to preserve that order when a mesh carries targets
+      // (Filament's gltfio applies them under the same assumption, so files that look right in
+      // the full viewer line up here too). A decode that DID drop/merge vertices shows up as an
+      // accessor-count mismatch — skip then, garbage deltas are worse than a rest pose.
+      const badTarget = targets.slice(0, n).find((t) => {
+        const check = (ai?: number): boolean => ai !== undefined && desc.accessors?.[ai]?.count !== vertexCount
+        return check(t.POSITION) || check(t.NORMAL)
+      })
+      if (badTarget) {
+        console.warn(`[viewer-lite] GLB: morph targets skipped on a primitive — target accessor count doesn't match the ${vertexCount}-vertex geometry (draco decode changed the vertex set)`)
+        continue
+      }
+      const hasNormals = targets.slice(0, n).some((t) => t.NORMAL !== undefined)
+      const total = vertexCount * n * (hasNormals ? 2 : 1)
+      const texWidth = Math.max(1, Math.ceil(Math.sqrt(total)))
+      const texHeight = Math.max(1, Math.ceil(total / texWidth))
+      const data = new Float32Array(texWidth * texHeight * 4)
+      for (let t = 0; t < n; t++) {
+        const pos = targets[t]!.POSITION !== undefined ? readAccessorF32(desc, buffers, targets[t]!.POSITION!) : null
+        const nrm = hasNormals && targets[t]!.NORMAL !== undefined ? readAccessorF32(desc, buffers, targets[t]!.NORMAL!) : null
+        for (let v = 0; v < vertexCount; v++) {
+          if (pos) {
+            const d = (t * vertexCount + v) * 4
+            data[d] = pos[v * 3] ?? 0; data[d + 1] = pos[v * 3 + 1] ?? 0; data[d + 2] = pos[v * 3 + 2] ?? 0
+          }
+          if (nrm) {
+            const d = ((n + t) * vertexCount + v) * 4
+            data[d] = nrm[v * 3] ?? 0; data[d + 1] = nrm[v * 3 + 1] ?? 0; data[d + 2] = nrm[v * 3 + 2] ?? 0
+          }
+        }
+      }
+      const texture = new Texture(gl, {
+        image: data, width: texWidth, height: texHeight,
+        type: gl.FLOAT, format: gl.RGBA, internalFormat: gl.RGBA32F,
+        generateMipmaps: false, minFilter: gl.NEAREST, magFilter: gl.NEAREST, flipY: false,
+      })
+      prim._morph = { texture, count: n, vertexCount, texWidth, hasNormals, weights } satisfies MorphInfo
+    }
+  }
+}
+
+/** Tag baseColor/emissive textures sRGB before their first GPU upload (glTF color inputs are sRGB).
+ *  Basis-compressed images swap to their sRGB sibling internal format instead (srgbInternalFormat,
+ *  set by the basis manager; 0 = the context lacks the sRGB variant — stay linear rather than
+ *  break the compressed upload). */
+const markSrgb = (gl: any, textureInfo: any): void => {
+  const tex = textureInfo?.texture
+  if (!tex || tex._srgbTagged) return
+  tex._srgbTagged = true
+  if (tex.image?.isCompressedTexture) {
+    if (tex.image.srgbInternalFormat) tex.internalFormat = tex.image.srgbInternalFormat
+    return
+  }
+  tex.internalFormat = gl.SRGB8_ALPHA8
+  tex.format = gl.RGBA
+}
+
+const buildProgram = (
+  gl: any,
+  material: any,
+  isSkin: boolean,
+  hasColor: boolean,
+  sceneUniforms: SceneUniforms,
+  white: Texture,
+  morph?: MorphInfo,
+): Program => {
+  const m = material ?? {}
+  const defines: string[] = []
+  if (isSkin) defines.push('#define HAS_SKIN')
+  if (hasColor) defines.push('#define HAS_COLOR')
+  if (m.baseColorTexture?.texture) defines.push('#define HAS_BASECOLOR_MAP')
+  if (m.metallicRoughnessTexture?.texture) defines.push('#define HAS_MR_MAP')
+  if (m.normalTexture?.texture) defines.push('#define HAS_NORMAL_MAP')
+  if (m.occlusionTexture?.texture) defines.push('#define HAS_OCCLUSION_MAP')
+  if (m.emissiveTexture?.texture) defines.push('#define HAS_EMISSIVE_MAP')
+  // KHR_materials_unlit — flat base colour, the shading model stylised assets are authored for.
+  // gltfio implements it natively (unlit_opaque in the uberarchive), so both engines agree.
+  if (m.extensions?.KHR_materials_unlit) defines.push('#define UNLIT')
+  if (m.doubleSided) defines.push('#define DOUBLE_SIDED')
+  if (m.alphaMode === 'MASK') defines.push('#define ALPHA_MASK')
+  if (m.alphaMode === 'BLEND') defines.push('#define ALPHA_BLEND')
+  const defineStr = defines.join('\n')
+
+  markSrgb(gl, m.baseColorTexture)
+  markSrgb(gl, m.emissiveTexture)
+
+  const uniforms: SceneUniforms = {
+    // Scene-shared: same { value } objects across every program — updated once per frame.
+    ...sceneUniforms,
+    uBaseColorFactor: { value: m.baseColorFactor ?? [1, 1, 1, 1] },
+    uMetallic: { value: m.metallicFactor ?? 1 },
+    uRoughness: { value: m.roughnessFactor ?? 1 },
+    uEmissive: { value: m.emissiveFactor ?? [0, 0, 0] },
+    uAlphaCutoff: { value: m.alphaCutoff ?? 0.5 },
+  }
+  if (m.baseColorTexture?.texture) uniforms.uBaseColorMap = { value: m.baseColorTexture.texture }
+  if (m.metallicRoughnessTexture?.texture) uniforms.uMRMap = { value: m.metallicRoughnessTexture.texture }
+  if (m.normalTexture?.texture) uniforms.uNormalMap = { value: m.normalTexture.texture }
+  if (m.occlusionTexture?.texture) uniforms.uOcclusionMap = { value: m.occlusionTexture.texture }
+  if (m.emissiveTexture?.texture) uniforms.uEmissiveMap = { value: m.emissiveTexture.texture }
+  if (morph) {
+    uniforms.uMorphTex = { value: morph.texture }
+    uniforms.uMorphCount = { value: morph.count }
+    uniforms.uMorphVertexCount = { value: morph.vertexCount }
+    uniforms.uMorphTexWidth = { value: morph.texWidth }
+    // The subarray view shares the node's buffer, so the clip sampler's writes flow through. It
+    // must be WRAPPED in a plain array: OGL resolves the active uniform `uMorphWeights[0]` by
+    // walking name components and only recognizes an array value via Array.isArray — a bare
+    // Float32Array fails that and the uniform is never uploaded ("has not been supplied"). The
+    // wrapper also routes through OGL's flatten(), which re-copies the live values every draw.
+    uniforms.uMorphWeights = { value: [ morph.weights.length > MAX_MORPH_TARGETS ? morph.weights.subarray(0, MAX_MORPH_TARGETS) : morph.weights ] }
+  }
+
+  const defineVertexFlags = (isSkin ? 'HAS_SKIN ' : '') + (hasColor ? 'HAS_COLOR ' : '')
+    + (morph ? 'HAS_MORPH ' : '') + (morph?.hasNormals ? 'HAS_MORPH_NORMALS' : '')
+  const program = new Program(gl, {
+    vertex: gltfVertex(defineVertexFlags),
+    fragment: gltfFragment(defineStr),
+    uniforms: uniforms as any,
+    transparent: m.alphaMode === 'BLEND',
+    cullFace: m.doubleSided ? false : gl.BACK,
+  })
+  if (m.alphaMode === 'BLEND') program.setBlendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA)
+  return program
+}
+
+/**
+ * Parse a GLB buffer and outfit it with the lite PBR programs. `sceneUniforms` are the shared
+ * per-frame lighting uniform slots (sun/IBL/shadow/exposure) every program references.
+ */
+export const loadGlbLite = async (
+  gl: any,
+  buffer: ArrayBuffer,
+  sceneUniforms: SceneUniforms,
+  white: Texture,
+): Promise<GlbResult> => {
+  const desc = (GLTFLoader as any).unpackGLB(buffer)
+  const unsupported = ((desc.extensionsRequired ?? []) as string[]).filter((e) => UNSUPPORTED_REQUIRED.includes(e))
+  if (unsupported.length > 0) {
+    throw new Error(`GLB requires ${unsupported.join(', ')} — the lite engine has no decoder for it`)
+  }
+
+  // Draco geometry / KTX2 textures: bring the lazy decoder workers up BEFORE parse (page-global
+  // singletons — the import and wasm fetch happen once, every later model reuses the same worker).
+  const extensions = [ ...(desc.extensionsUsed ?? []), ...(desc.extensionsRequired ?? []) ] as string[]
+  const needsDraco = extensions.includes('KHR_draco_mesh_compression')
+  const needsBasis = extensions.includes('KHR_texture_basisu')
+    || ((desc.images ?? []) as { mimeType?: string }[]).some((i) => i.mimeType === 'image/ktx2')
+  if (needsDraco || needsBasis) {
+    const decoders = await import('./decoders')
+    await Promise.all([
+      needsDraco ? decoders.ensureDracoDecoder() : null,
+      needsBasis ? decoders.ensureBasisTranscoder(gl) : null,
+    ])
+  }
+
+  dedupeSharedMeshes(desc)
+  // Morph `weights` channels must not reach OGL's parser (it crashes on them) — pull them out and
+  // re-attach to OUR sampler after parse, once buildMorphState has set up the weight arrays.
+  const morphChannels = extractMorphAnimationChannels(desc)
+  const gltf = await (GLTFLoader as any).parse(gl, desc, '')
+  const rawBuffers = ((desc.buffers ?? []) as { binary?: ArrayBuffer }[]).map((b) => b.binary)
+  buildMorphState(gl, desc, gltf, rawBuffers)
+
+  // Replace the loader's NormalProgram placeholders with our PBR programs. `gltf.nodes` holds both
+  // parents and children, so traversing every node reaches shared meshes more than once — dedupe,
+  // otherwise the second visit reads the already-swapped program (no gltfMaterial) and overwrites
+  // the textured program with a material-less white one.
+  const programCache = new Map<any, Program>()
+  const seen = new Set<any>()
+  const allMeshes: Mesh[] = []
+  for (const node of gltf.nodes as Transform[]) {
+    node.traverse((child: any) => {
+      if (child.draw && !seen.has(child)) { seen.add(child); allMeshes.push(child) }
+      return false
+    })
+  }
+  for (const mesh of allMeshes as any[]) {
+    // The lite programs consume `normal` and `uv` unconditionally, and OGL crashes drawing a
+    // program whose active attribute the geometry lacks ("reading 'needsUpdate'") — but glTF only
+    // guarantees POSITION (robot.glb ships no UVs; snake.glb has a skinned primitive without
+    // TEXCOORD_0). Pad missing ones with zeros: untextured materials are unaffected, textured
+    // ones sample texel (0,0) — a solid-color degrade instead of a dead render loop. The
+    // wireframe companions copy attributes from here, so they inherit the padding.
+    const geoAttrs = mesh.geometry?.attributes
+    const vertexCount = geoAttrs?.position?.count ?? 0
+    if (geoAttrs && vertexCount > 0) {
+      if (!geoAttrs.normal) {
+        const n = new Float32Array(vertexCount * 3)
+        for (let i = 2; i < n.length; i += 3) n[i] = 1  // +Z, not zeros — normalize(0) is NaN
+        mesh.geometry.addAttribute('normal', { size: 3, data: n })
+      }
+      if (!geoAttrs.uv) mesh.geometry.addAttribute('uv', { size: 2, data: new Float32Array(vertexCount * 2) })
+    }
+    const material = mesh.program?.gltfMaterial
+    const isSkin = mesh instanceof GLTFSkin
+    const colorAttr = mesh.geometry?.attributes?.color
+    const hasColor = !!colorAttr && colorAttr.size === 4
+    const morph = mesh._morph as MorphInfo | undefined
+    // Programs are shareable when the material AND variant flags match. Skinned programs can be
+    // shared too (GLTFSkin re-binds boneTexture per draw); morphed ones can't (per-mesh texture
+    // + weight uniforms).
+    const key = material ?? mesh
+    const cacheKey = isSkin || hasColor || morph ? mesh : key
+    let program = programCache.get(cacheKey)
+    if (!program) {
+      program = buildProgram(gl, material, isSkin, hasColor, sceneUniforms, white, morph)
+      programCache.set(cacheKey, program)
+    }
+    mesh.program = program
+    mesh._receiveShadows = true
+    mesh._castShadows = true
+  }
+
+  // Wait for texture image decodes so the model doesn't pop in texture-less (mirrors the Filament
+  // path's poll-until-transcoded behavior).
+  if (gltf.images) {
+    await Promise.all((gltf.images as any[]).map((img) => img?.ready).filter(Boolean))
+  }
+
+  // Animation clips: name + duration + the unique set of nodes each clip drives.
+  const animations: GlbClip[] = (gltf.animations ?? []).map((a: any, i: number) => {
+    const nodes: Transform[] = []
+    for (const ch of a.animation.data) if (!nodes.includes(ch.node)) nodes.push(ch.node)
+    return {
+      name: typeof a.name === 'string' && a.name.length > 0 ? a.name : `animation_${i}`,
+      duration: a.animation.duration,
+      animation: a.animation,
+      nodes,
+    }
+  })
+
+  // Re-attach the extracted morph channels to our sampler (only nodes that built morph state —
+  // a weights channel on a target-less mesh is meaningless and skipped).
+  let attachedMorph = 0
+  for (const mc of morphChannels) {
+    const clip = animations[mc.anim]
+    const node = gltf.nodes?.[mc.node] as any
+    if (!clip || !node?.weights) continue
+    clip.animation.data.push({
+      node, transform: 'weights', interpolation: mc.interpolation,
+      times: readAccessorF32(desc, rawBuffers, mc.input),
+      values: readAccessorF32(desc, rawBuffers, mc.output),
+    })
+    attachedMorph++
+  }
+  if (morphChannels.length > attachedMorph) {
+    console.warn(`[viewer-lite] GLB: ${morphChannels.length - attachedMorph} morph (weights) animation channel(s) ignored — their nodes carry no usable morph targets`)
+  }
+  // Recompute every clip's clock from its channels: weights channels may extend or (for
+  // morph-only clips, which OGL parsed as empty) entirely define it — and OGL's reduce over an
+  // empty channel list leaves duration at -Infinity.
+  for (const clip of animations) {
+    let start = Infinity, end = 0
+    for (const chd of clip.animation.data) {
+      start = Math.min(start, chd.times[0] as number)
+      end = Math.max(end, chd.times[chd.times.length - 1] as number)
+    }
+    clip.animation.startTime = start === Infinity ? 0 : start
+    clip.animation.duration = clip.duration = start === Infinity ? 0 : end - start
+  }
+
+  // glTF `scene` (the default scene index) is OPTIONAL — glTF-Transform output (lecodes-assets
+  // convert/doctor) omits it, and OGL then resolves `scenes[undefined]` to nothing: the model loads
+  // with zero roots, nothing is parented, zero draw calls. Fall back to the first scene like gltfio.
+  return { roots: gltf.scene ?? gltf.scenes?.[0] ?? [], nodes: gltf.nodes ?? [], animations }
+}