@solidrt/3d 0.0.51 → 0.0.52

package/src/glsl.ts

@@ -16,6 +16,13 @@
 
 import { glsl } from "@solidrt/core/gpu"
 
+/** The directional-light cap of the scene's light list (DirectionalLight nodes)
+ * and of the `lit` fragment; a custom fragment declares
+ * `uniform vec3 uLightDir[MAX_LIGHTS]` / `uLightColor[MAX_LIGHTS]` and
+ * loops to `uLightCount`. A shader-source constant, so it is fixed for
+ * the app (see okf/backlog/app-runtime-config.md). */
+export const MAX_LIGHTS = 4
+
 /**
  * The standard lit vertex stage: clip position via uViewProj * uModel,
  * with world position, world normal (via `mat3(uNormal)`, correct under
@@ -50,9 +57,9 @@ export const LIT_VERTEX = glsl`
  * LIT_VERTEX for "colored"-layout geometry: the same interface plus the
  * per-vertex aColor vec4 forwarded raw as `in vec4 vColor` - what it means
  * (a tint, baked AO in one channel, anything) is the fragment's business.
- * Using this constant opts the material into the colored layout (its
- * meshes need withColors() geometry), because shaderMaterial detects
- * aColor in the vertex source.
+ * Using this constant makes the material read aColor (shaderMaterial
+ * collects the vertex stage's `in` declarations), so its meshes need
+ * geometry carrying that channel - withColors() - or add() throws.
  */
 export const LIT_VERTEX_COLORED = glsl`
   in vec3 aPos;
@@ -110,3 +117,76 @@ export const FRESNEL = glsl`
     return pow(1.0 - max(dot(n, v), 0.0), power);
   }
 `
+
+/**
+ * The scene's shadow set as a receiving program declares it, one slot per
+ * directional light index: `uShadowMap0..N-1` (each light's depth map, a
+ * white texel when it does not cast), `uShadowMatrix[N]` (its light-space
+ * viewProj), `uShadowCast[N]` (1 when light i casts), `uShadowBias[N]` and
+ * `uShadowNormalBias[N]`. The scene binds and writes all of it on every
+ * target a receiving material can draw into; a custom material composes
+ * this, then SHADOW, then SHADOW_LOOKUP (in that order) and multiplies
+ * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape.
+ * A material that does not receive composes none of it, so it declares
+ * no samplers for nothing.
+ */
+export const SHADOW_SLOTS = glsl`
+  ${Array.from({ length: MAX_LIGHTS }, (_, i) => `uniform sampler2D uShadowMap${i};`).join("\n  ")}
+  uniform mat4 uShadowMatrix[${MAX_LIGHTS}];
+  uniform int uShadowCast[${MAX_LIGHTS}];
+  uniform float uShadowBias[${MAX_LIGHTS}];
+  uniform float uShadowNormalBias[${MAX_LIGHTS}];
+`
+
+/**
+ * `float shadow(sampler2D map, vec4 coord, float bias)` - the directional
+ * shadow factor (1 lit, 0 shadowed) for a world point carried into a
+ * casting light's clip space by its `uShadowMatrix[i]`:
+ * `shadow(uShadowMap0, uShadowMatrix[0] * vec4(vWorldPos, 1.0), uShadowBias[0])`.
+ * Perspective divide, 0..1 remap, out-of-frustum returns 1 (lit), then a
+ * 3x3 PCF over texel neighbours comparing the map's `.r` (a stage-1 depth
+ * texture samples nearest, so the softness is this loop, not the sampler).
+ * `bias` is subtracted from the point's depth against acne; SHADOW_LOOKUP
+ * also offsets the point along its normal by `uShadowNormalBias[i]`
+ * before the transform.
+ */
+export const SHADOW = glsl`
+  float shadow(sampler2D map, vec4 coord, float bias) {
+    vec3 p = coord.xyz / coord.w * 0.5 + 0.5;
+    if (p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0 || p.z > 1.0) return 1.0;
+    vec2 texel = 1.0 / vec2(textureSize(map, 0));
+    float lit = 0.0;
+    for (int y = -1; y <= 1; y++) {
+      for (int x = -1; x <= 1; x++) {
+        float d = texture(map, p.xy + vec2(float(x), float(y)) * texel).r;
+        lit += p.z - bias <= d ? 1.0 : 0.0;
+      }
+    }
+    return lit / 9.0;
+  }
+`
+
+/**
+ * The step from a light index to its shadow factor, over SHADOW_SLOTS and
+ * SHADOW (compose both first). `float shadowAt(int i, vec4 coord, float
+ * bias)` picks light i's map - an if-chain over the slots, because GLSL
+ * ES 3.00 only indexes a sampler array by a constant - and samples it
+ * with `shadow`. `float lightShadow(int i, vec3 worldPos, vec3 n)` is
+ * the one to call per light: 1 for a light that does not cast, else the
+ * factor for `worldPos` pushed along its normal `n` by
+ * `uShadowNormalBias[i]` (the acne knob to reach for first) and carried
+ * through `uShadowMatrix[i]` with `uShadowBias[i]`. Position and normal
+ * are arguments, so no varying name is pinned and a custom vertex stage
+ * composes freely.
+ */
+export const SHADOW_LOOKUP = glsl`
+  float shadowAt(int i, vec4 coord, float bias) {
+    ${Array.from({ length: MAX_LIGHTS }, (_, i) => `if (i == ${i}) return shadow(uShadowMap${i}, coord, bias);`).join("\n    ")}
+    return 1.0;
+  }
+
+  float lightShadow(int i, vec3 worldPos, vec3 n) {
+    if (uShadowCast[i] != 1) return 1.0;
+    return shadowAt(i, uShadowMatrix[i] * vec4(worldPos + n * uShadowNormalBias[i], 1.0), uShadowBias[i]);
+  }
+`

package/src/gltf.ts

@@ -0,0 +1,437 @@
+// glTF 2.0, the subset an app needs to show authored models: the scene's
+// node tree with world transforms BAKED into the vertices (one part per
+// mesh node, its name kept), triangles with positions, normals (flat ones
+// generated when absent, per the spec), one UV set and indices, and
+// materials reduced to what lit()/unlit() draw - base color factor and
+// texture, double-sidedness, alpha blending. Both containers: .gltf JSON
+// with external or data: buffers and images, and single-file .glb.
+//
+// Pure module by design - a parse is JSON plus typed-array views plus one
+// interleave loop per primitive, so it runs the same under bun (the bake
+// tool in tools/model.ts, the check rig) and on flux (loadGltf in
+// model.ts). It never decodes images: material.map indexes the encoded
+// bytes in `images`, and uploading is the engine side's job.
+//
+// Outside the subset: Draco/meshopt-compressed meshes and any other
+// required extension throw naming it; non-triangle primitives, sparse
+// accessors and morph/skin data are skipped or ignored; vertex colors,
+// tangents and further UV sets are dropped (the standard layout has no
+// slot for them yet).
+
+import { compose, mat4, multiply, normalMatrix } from "./math.ts"
+import type { Mat4, Quat, Vec3 } from "./math.ts"
+import { packGeometry, STANDARD_FLOATS } from "./geometry.ts"
+import type { Geometry } from "./geometry.ts"
+
+/** What lit()/unlit() take from a glTF material. */
+export type ModelMaterial = {
+  name: string
+  /** Straight [r, g, b, a] 0..1 (glTF baseColorFactor). */
+  color: [number, number, number, number]
+  /** Index into ModelData.images (the base color texture), or null. */
+  map: number | null
+  /** glTF doubleSided. Reported, not applied: the standard materials cull
+   * back faces. */
+  doubleSided: boolean
+  /** alphaMode BLEND. MASK draws opaque (no alpha test). */
+  transparent: boolean
+}
+
+/** One drawable: a mesh node's primitive, vertices in WORLD space. */
+export type ModelPart = {
+  /** The glTF node's name (or the mesh's, or `node<i>`); a node with
+   * several primitives numbers them `name#<k>`. */
+  name: string
+  geometry: Geometry
+  /** Index into ModelData.materials. */
+  material: number
+}
+
+/** A parsed model: plain data, no GPU resources. What parseGltf and
+ * decodeModel produce and createModel consumes. */
+export type ModelData = {
+  parts: ModelPart[]
+  materials: ModelMaterial[]
+  /** Encoded image files (PNG/JPEG bytes) the materials' `map` index. */
+  images: Uint8Array[]
+  /** World-space [minX, minY, minZ, maxX, maxY, maxZ] over every part. */
+  bounds: Float32Array
+}
+
+/** Resolves a relative uri of a .gltf (its .bin buffers, image files) to
+ * bytes. Not needed for .glb or data: uris. */
+export type UriResolver = (uri: string) => Uint8Array
+
+const GLB_MAGIC = 0x46546c67
+const CHUNK_JSON = 0x4e4f534a
+const CHUNK_BIN = 0x004e4942
+const MODE_TRIANGLES = 4
+
+const COMPONENT_BYTES: Record<number, number> = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }
+const TYPE_ELEMENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 }
+
+const DEFAULT_MATERIAL: ModelMaterial = { name: "default", color: [1, 1, 1, 1], map: null, doubleSided: false, transparent: false }
+
+/** True when the bytes are a .glb container (the "glTF" magic). */
+export function isGlb(bytes: Uint8Array): boolean {
+  return bytes.length >= 12 && new DataView(bytes.buffer, bytes.byteOffset, 12).getUint32(0, true) === GLB_MAGIC
+}
+
+/** The external uris a .gltf document references (buffers and images), so
+ * an async caller can fetch them before parseGltf. Empty for .glb and
+ * data: uris. */
+export function gltfExternalUris(bytes: Uint8Array): string[] {
+  if (isGlb(bytes)) return []
+  let gltf = JSON.parse(new TextDecoder().decode(bytes))
+  let uris: string[] = []
+  for (let item of [...(gltf.buffers ?? []), ...(gltf.images ?? [])]) {
+    if (typeof item.uri === "string" && !item.uri.startsWith("data:")) uris.push(item.uri)
+  }
+  return uris
+}
+
+/**
+ * Parse a .glb or .gltf into ModelData. `resolve` supplies the bytes of a
+ * .gltf's external files by their uri as written in the document (still
+ * percent-encoded); omit it for .glb.
+ */
+export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
+  let gltf: any
+  let bin: Uint8Array | null = null
+  if (isGlb(bytes)) {
+    let glb = readGlb(bytes)
+    gltf = glb.json
+    bin = glb.bin
+  } else {
+    gltf = JSON.parse(new TextDecoder().decode(bytes))
+  }
+  if (gltf.asset?.version !== undefined && !String(gltf.asset.version).startsWith("2")) {
+    throw new Error("parseGltf: glTF version " + gltf.asset.version + " (only 2.x is supported)")
+  }
+  for (let ext of gltf.extensionsRequired ?? []) {
+    if (ext === "KHR_draco_mesh_compression" || ext === "EXT_meshopt_compression") {
+      throw new Error("parseGltf: the file's meshes are compressed (" + ext + "), which is not supported: re-export without mesh compression")
+    }
+    // Quantized attributes read through the normalized-integer path; every
+    // other required extension changes what the file means.
+    if (ext !== "KHR_mesh_quantization") {
+      throw new Error("parseGltf: the file requires the " + ext + " extension, which is not supported")
+    }
+  }
+
+  let external = (uri: string, what: string): Uint8Array => {
+    if (uri.startsWith("data:")) return decodeDataUri(uri)
+    if (resolve === undefined) throw new Error("parseGltf: " + what + " references the external file " + uri + " and no resolver was given")
+    return resolve(uri)
+  }
+
+  let buffers: Uint8Array[] = (gltf.buffers ?? []).map((b: any, i: number): Uint8Array => {
+    if (b.uri === undefined) {
+      if (bin === null) throw new Error("parseGltf: buffer " + i + " has no uri and the file has no binary chunk")
+      return bin
+    }
+    return external(b.uri, "buffer " + i)
+  })
+
+  let bufferViewBytes = (index: number): Uint8Array => {
+    let view = gltf.bufferViews[index]
+    let buffer = buffers[view.buffer]
+    if (buffer === undefined) throw new Error("parseGltf: bufferView " + index + " names a missing buffer")
+    return buffer.subarray(view.byteOffset ?? 0, (view.byteOffset ?? 0) + view.byteLength)
+  }
+
+  // Images are pulled in only when a material samples them, in first-use
+  // order, so `map` indexes a compact list.
+  let images: Uint8Array[] = []
+  let imageSlots = new Map<number, number>()
+  let imageSlot = (index: number): number => {
+    let slot = imageSlots.get(index)
+    if (slot === undefined) {
+      let image = gltf.images?.[index]
+      if (image === undefined) throw new Error("parseGltf: texture names a missing image " + index)
+      let bytes = image.uri !== undefined ? external(image.uri, "image " + index) : bufferViewBytes(image.bufferView)
+      slot = images.length
+      images.push(bytes)
+      imageSlots.set(index, slot)
+    }
+    return slot
+  }
+
+  let materials: ModelMaterial[] = (gltf.materials ?? []).map((m: any, i: number): ModelMaterial => {
+    let pbr = m.pbrMetallicRoughness ?? {}
+    let factor = pbr.baseColorFactor ?? [1, 1, 1, 1]
+    let map: number | null = null
+    if (pbr.baseColorTexture !== undefined) {
+      let texture = gltf.textures?.[pbr.baseColorTexture.index]
+      if (texture?.source !== undefined) map = imageSlot(texture.source)
+    }
+    return {
+      name: m.name ?? "material" + i,
+      color: [factor[0], factor[1], factor[2], factor[3] ?? 1],
+      map,
+      doubleSided: m.doubleSided === true,
+      transparent: m.alphaMode === "BLEND",
+    }
+  })
+  // Primitives without a material draw the spec's default; it is appended
+  // only when something uses it.
+  let defaultMaterial = -1
+
+  let accessorFloats = (index: number, what: string): { data: Float32Array; elements: number; count: number } => {
+    let acc = gltf.accessors[index]
+    if (acc === undefined) throw new Error("parseGltf: " + what + " names a missing accessor " + index)
+    if (acc.sparse !== undefined) throw new Error("parseGltf: " + what + " uses a sparse accessor, which is not supported")
+    let elements = TYPE_ELEMENTS[acc.type]
+    let compBytes = COMPONENT_BYTES[acc.componentType]
+    if (elements === undefined || compBytes === undefined) throw new Error("parseGltf: " + what + " has an unknown accessor type")
+    let out = new Float32Array(acc.count * elements)
+    if (acc.bufferView === undefined) return { data: out, elements, count: acc.count }
+    let view = gltf.bufferViews[acc.bufferView]
+    let bytes = bufferViewBytes(acc.bufferView)
+    let stride = view.byteStride ?? compBytes * elements
+    let dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    let base = acc.byteOffset ?? 0
+    let normalized = acc.normalized === true
+    let read = readerFor(acc.componentType, normalized)
+    for (let i = 0; i < acc.count; i++) {
+      let at = base + i * stride
+      for (let e = 0; e < elements; e++) out[i * elements + e] = read(dv, at + e * compBytes)
+    }
+    return { data: out, elements, count: acc.count }
+  }
+
+  let parts: ModelPart[] = []
+  let bounds = new Float32Array([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity])
+  let normal = mat4()
+
+  let emit = (prim: any, name: string, world: Mat4): void => {
+    if ((prim.mode ?? MODE_TRIANGLES) !== MODE_TRIANGLES) return
+    if (prim.attributes?.POSITION === undefined) return
+    let pos = accessorFloats(prim.attributes.POSITION, name + " POSITION")
+    if (pos.elements !== 3) throw new Error("parseGltf: " + name + " POSITION is not VEC3")
+    let count = pos.count
+    let nrm = prim.attributes.NORMAL !== undefined ? accessorFloats(prim.attributes.NORMAL, name + " NORMAL").data : null
+    let uv = prim.attributes.TEXCOORD_0 !== undefined ? accessorFloats(prim.attributes.TEXCOORD_0, name + " TEXCOORD_0").data : null
+    let indices: ArrayLike<number> =
+      prim.indices !== undefined ? accessorFloats(prim.indices, name + " indices").data : Array.from({ length: count }, (_, i) => i)
+    if (indices.length % 3 !== 0) throw new Error("parseGltf: " + name + " index count is not a multiple of 3")
+
+    normalMatrix(normal, world)
+    let flip = det3(world) < 0
+
+    let vertices: Float32Array
+    let packedIndices: number[]
+    if (nrm !== null) {
+      vertices = new Float32Array(count * STANDARD_FLOATS)
+      for (let i = 0; i < count; i++) writeVertex(vertices, i, pos.data, nrm, uv, i, world, normal)
+      packedIndices = new Array(indices.length)
+      for (let i = 0; i < indices.length; i += 3) {
+        packedIndices[i] = indices[i]!
+        packedIndices[i + 1] = flip ? indices[i + 2]! : indices[i + 1]!
+        packedIndices[i + 2] = flip ? indices[i + 1]! : indices[i + 2]!
+      }
+    } else {
+      // No normals: the spec asks for flat shading, which needs one vertex
+      // per triangle corner, so the primitive is un-indexed here and each
+      // corner takes its face normal (computed in world space, after the
+      // bake, so a mirroring transform is already accounted for).
+      let triangles = indices.length / 3
+      vertices = new Float32Array(triangles * 3 * STANDARD_FLOATS)
+      packedIndices = new Array(triangles * 3)
+      let face: Vec3 = [0, 0, 0]
+      for (let t = 0; t < triangles; t++) {
+        let a = indices[t * 3]!, b = indices[t * 3 + 1]!, c = indices[t * 3 + 2]!
+        if (flip) [b, c] = [c, b]
+        let out = t * 3
+        writeVertex(vertices, out, pos.data, null, uv, a, world, normal)
+        writeVertex(vertices, out + 1, pos.data, null, uv, b, world, normal)
+        writeVertex(vertices, out + 2, pos.data, null, uv, c, world, normal)
+        faceNormal(face, vertices, out)
+        for (let k = 0; k < 3; k++) {
+          let at = (out + k) * STANDARD_FLOATS + 3
+          vertices[at] = face[0]
+          vertices[at + 1] = face[1]
+          vertices[at + 2] = face[2]
+          packedIndices[out + k] = out + k
+        }
+      }
+      count = triangles * 3
+    }
+
+    for (let i = 0; i < count; i++) {
+      let at = i * STANDARD_FLOATS
+      let x = vertices[at]!, y = vertices[at + 1]!, z = vertices[at + 2]!
+      if (x < bounds[0]!) bounds[0] = x
+      if (y < bounds[1]!) bounds[1] = y
+      if (z < bounds[2]!) bounds[2] = z
+      if (x > bounds[3]!) bounds[3] = x
+      if (y > bounds[4]!) bounds[4] = y
+      if (z > bounds[5]!) bounds[5] = z
+    }
+
+    let material = prim.material
+    if (material === undefined) {
+      if (defaultMaterial < 0) {
+        defaultMaterial = materials.length
+        materials.push({ ...DEFAULT_MATERIAL })
+      }
+      material = defaultMaterial
+    }
+    parts.push({ name, geometry: packGeometry(vertices, packedIndices, { label: name }), material })
+  }
+
+  let local = mat4()
+  let walk = (index: number, parent: Mat4): void => {
+    let node = gltf.nodes[index]
+    if (node === undefined) throw new Error("parseGltf: scene names a missing node " + index)
+    let world = mat4()
+    multiply(world, parent, nodeMatrix(local, node))
+    if (node.mesh !== undefined) {
+      let mesh = gltf.meshes[node.mesh]
+      if (mesh === undefined) throw new Error("parseGltf: node " + index + " names a missing mesh " + node.mesh)
+      let name = node.name ?? mesh.name ?? "node" + index
+      let prims: any[] = mesh.primitives ?? []
+      for (let k = 0; k < prims.length; k++) emit(prims[k], prims.length > 1 ? name + "#" + k : name, world)
+    }
+    for (let child of node.children ?? []) walk(child, world)
+  }
+
+  let scene = gltf.scenes?.[gltf.scene ?? 0]
+  let roots: number[] = scene?.nodes ?? (gltf.nodes ?? []).map((_: unknown, i: number) => i)
+  let root = mat4()
+  for (let index of roots) walk(index, root)
+
+  if (parts.length === 0) bounds.fill(0)
+  return { parts, materials, images, bounds }
+}
+
+function readGlb(bytes: Uint8Array): { json: any; bin: Uint8Array | null } {
+  let dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let version = dv.getUint32(4, true)
+  if (version !== 2) throw new Error("parseGltf: glb version " + version + " (only 2 is supported)")
+  let length = Math.min(dv.getUint32(8, true), bytes.byteLength)
+  let json: any = null
+  let bin: Uint8Array | null = null
+  let at = 12
+  while (at + 8 <= length) {
+    let chunkLength = dv.getUint32(at, true)
+    let chunkType = dv.getUint32(at + 4, true)
+    let chunk = bytes.subarray(at + 8, at + 8 + chunkLength)
+    if (chunkType === CHUNK_JSON) json = JSON.parse(new TextDecoder().decode(chunk))
+    else if (chunkType === CHUNK_BIN && bin === null) bin = chunk
+    at += 8 + chunkLength
+  }
+  if (json === null) throw new Error("parseGltf: glb has no JSON chunk")
+  return { json, bin }
+}
+
+function decodeDataUri(uri: string): Uint8Array {
+  let comma = uri.indexOf(",")
+  if (comma < 0) throw new Error("parseGltf: malformed data: uri")
+  let meta = uri.slice(0, comma)
+  let payload = uri.slice(comma + 1)
+  if (!meta.endsWith(";base64")) return new TextEncoder().encode(decodeURIComponent(payload))
+  let text = atob(payload)
+  let out = new Uint8Array(text.length)
+  for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i)
+  return out
+}
+
+function readerFor(componentType: number, normalized: boolean): (dv: DataView, at: number) => number {
+  switch (componentType) {
+    case 5126:
+      return (dv, at) => dv.getFloat32(at, true)
+    case 5125:
+      return (dv, at) => dv.getUint32(at, true)
+    case 5123:
+      return normalized ? (dv, at) => dv.getUint16(at, true) / 65535 : (dv, at) => dv.getUint16(at, true)
+    case 5122:
+      return normalized ? (dv, at) => Math.max(dv.getInt16(at, true) / 32767, -1) : (dv, at) => dv.getInt16(at, true)
+    case 5121:
+      return normalized ? (dv, at) => dv.getUint8(at) / 255 : (dv, at) => dv.getUint8(at)
+    default:
+      return normalized ? (dv, at) => Math.max(dv.getInt8(at) / 127, -1) : (dv, at) => dv.getInt8(at)
+  }
+}
+
+const NO_TRANSLATION: Vec3 = [0, 0, 0]
+const NO_ROTATION: Quat = [0, 0, 0, 1]
+const NO_SCALE: Vec3 = [1, 1, 1]
+
+function nodeMatrix(out: Mat4, node: any): Mat4 {
+  if (node.matrix !== undefined) {
+    for (let i = 0; i < 16; i++) out[i] = node.matrix[i]
+    return out
+  }
+  return compose(out, node.translation ?? NO_TRANSLATION, node.rotation ?? NO_ROTATION, node.scale ?? NO_SCALE)
+}
+
+function det3(m: Mat4): number {
+  return (
+    m[0] * (m[5] * m[10] - m[6] * m[9]) -
+    m[4] * (m[1] * m[10] - m[2] * m[9]) +
+    m[8] * (m[1] * m[6] - m[2] * m[5])
+  )
+}
+
+// One interleaved vertex: position through the world matrix, normal (when
+// given) through the normal matrix and re-normalized, uv copied or zero.
+function writeVertex(
+  out: Float32Array,
+  slot: number,
+  pos: Float32Array,
+  nrm: Float32Array | null,
+  uv: Float32Array | null,
+  src: number,
+  world: Mat4,
+  normal: Mat4,
+): void {
+  let at = slot * STANDARD_FLOATS
+  let x = pos[src * 3]!, y = pos[src * 3 + 1]!, z = pos[src * 3 + 2]!
+  out[at] = world[0] * x + world[4] * y + world[8] * z + world[12]
+  out[at + 1] = world[1] * x + world[5] * y + world[9] * z + world[13]
+  out[at + 2] = world[2] * x + world[6] * y + world[10] * z + world[14]
+  if (nrm !== null) {
+    let nx = nrm[src * 3]!, ny = nrm[src * 3 + 1]!, nz = nrm[src * 3 + 2]!
+    let wx = normal[0] * nx + normal[4] * ny + normal[8] * nz
+    let wy = normal[1] * nx + normal[5] * ny + normal[9] * nz
+    let wz = normal[2] * nx + normal[6] * ny + normal[10] * nz
+    let len = Math.hypot(wx, wy, wz)
+    if (len > 1e-12) {
+      wx /= len
+      wy /= len
+      wz /= len
+    } else {
+      wx = 0
+      wy = 1
+      wz = 0
+    }
+    out[at + 3] = wx
+    out[at + 4] = wy
+    out[at + 5] = wz
+  }
+  if (uv !== null) {
+    out[at + 6] = uv[src * 2]!
+    out[at + 7] = uv[src * 2 + 1]!
+  }
+}
+
+// The unit normal of the triangle at three consecutive vertex slots.
+function faceNormal(out: Vec3, v: Float32Array, first: number): void {
+  let a = first * STANDARD_FLOATS, b = (first + 1) * STANDARD_FLOATS, c = (first + 2) * STANDARD_FLOATS
+  let abx = v[b]! - v[a]!, aby = v[b + 1]! - v[a + 1]!, abz = v[b + 2]! - v[a + 2]!
+  let acx = v[c]! - v[a]!, acy = v[c + 1]! - v[a + 1]!, acz = v[c + 2]! - v[a + 2]!
+  let nx = aby * acz - abz * acy
+  let ny = abz * acx - abx * acz
+  let nz = abx * acy - aby * acx
+  let len = Math.hypot(nx, ny, nz)
+  if (len > 1e-12) {
+    out[0] = nx / len
+    out[1] = ny / len
+    out[2] = nz / len
+  } else {
+    out[0] = 0
+    out[1] = 1
+    out[2] = 0
+  }
+}

package/src/index.ts

@@ -5,23 +5,28 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, createInstancedMesh, createMesh, createScene, disposeInstances, getRotation, lookAt, remove, setGeometry, setInstanceCount, setInstances, setMaterial, setMeshParams, setRenderOrder, setTransform, setVisible, worldPosition } from "./scene.ts"
-export type { CameraUpdate, Hit, InstancedMesh as InstancedMeshNode, InstancedMeshOptions, Mesh as MeshNode, MeshInstances, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, TransformUpdate } from "./scene.ts"
+export { add, createDirectionalLight, createGroup, createHemisphereLight, createInstancedMesh, createMesh, createScene, createSprite, setLight, disposeInstances, getRotation, lookAt, remove, setCastShadow, setGeometry, setInstanceCount, setInstances, setMaterial, setMeshParams, setRenderOrder, setTransform, setTransition, setVisible, worldPosition, MAX_SHADOWS } from "./scene.ts"
+export type { CameraUpdate, DirectionalLight as DirectionalLightNode, DirectionalLightOptions, HemisphereLight as HemisphereLightNode, HemisphereLightOptions, Hit, Light, InstancedMesh as InstancedMeshNode, InstancedMeshOptions, Mesh as MeshNode, MeshInstances, OrthoExtent, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, ShadowCamera, ShadowOptions, TransformUpdate, TransitionEndEvent, View, ViewOptions } from "./scene.ts"
+export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
 export { disposeGeometry } from "./geometry-gpu.ts"
-export { box, circle, cone, cylinder, fillColors, geometryBounds, mergeGeometries, plane, ring, sphere, torus, torusKnot, transformGeometry, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
-export type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
-export { rayBoxDistance } from "./bvh.ts"
+export { box, circle, cone, cylinder, fillAttribute, fillColors, geometryBounds, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, packGeometry, plane, ring, sphere, torus, torusKnot, transformGeometry, validateGeometry, withAttribute, withColors, STANDARD_FLOATS, VERTEX_LAYOUTS } from "./geometry.ts"
+export type { AttributeFill, BoxOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, Geometry, GeometryOptions, PlaneOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"
 export { fillet, roundRect, shape, triangulate } from "./profile.ts"
 export type { Profile, ProfilePoint } from "./profile.ts"
 export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
-export type { PathFrames, PathPoint, SweepPath } from "./sweep.ts"
-export { shaderMaterial, shaderMaterialClass, unlit } from "./material.ts"
-export type { Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
-export { Group, InstancedMesh, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
-export type { InstancedMeshProps, MeshProps, PerspectiveCameraProps, PointerEventProps, SceneProps, TransformProps } from "./components.tsx"
+export type { ExtrudeOptions, LatheOptions, PathFrames, PathPoint, SweepPath, TubeOptions } from "./sweep.ts"
+export { lit, shaderMaterial, shaderMaterialClass, sprite, unlit } from "./material.ts"
+export type { LitOptions, Material, ShaderMaterialClass, ShaderMaterialClassOptions, ShaderMaterialInstanceOptions, ShaderMaterialOptions, SpriteOptions, UnlitOptions } from "./material.ts"
+export { DirectionalLight, Group, HemisphereLight, InstancedMesh, Mesh, PerspectiveCamera, Scene, Sprite, useScene } from "./components.tsx"
+export type { DirectionalLightProps, HemisphereLightProps, InstancedMeshProps, MeshProps, PerspectiveCameraProps, PointerEventProps, SceneProps, SpriteProps, TransformProps } from "./components.tsx"
+export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
+export type { ModelData, ModelMaterial, ModelPart, UriResolver } from "./gltf.ts"
+export { decodeModel, encodeModel } from "./model-file.ts"
+export { createModel, loadGltf, loadModel } from "./model.ts"
+export type { Model, ModelOptions } from "./model.ts"
 export { createOrbitCamera } from "./orbit.ts"
-export type { OrbitCamera, OrbitCameraOptions, OrbitPose } from "./orbit.ts"
+export type { OrbitCamera, OrbitCameraOptions, OrbitPose, OrbitTarget } from "./orbit.ts"
 // math's lookAt (the camera view matrix) stays on the /math subpath: the
 // root's lookAt is the scene verb, the same split as `add`.
-export { compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"
+export { rayBoxDistance, compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, orthographic, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"
 export type { Mat4, Quat, Vec2, Vec3 } from "./math.ts"