@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/entities/src/model-renderer.js

@@ -0,0 +1,1307 @@
+// ============================================================================
+// Model Renderer — renders imported 3D models (FBX/GLTF/OBJ) via WebGPU
+//
+// Bindless binding model: per-draw material data lives in a shared material
+// SSBO (@group(3)), indexed by a `materialIndex` written into the per-draw
+// uniform struct (@group(0)). Textures are registered into the
+// BindlessTextureRegistry's texture_2d_array buckets. The bindless bind group
+// (@group(3)) is set once per frame by the caller (via setBindlessBindGroup)
+// — no per-draw bind-group creation or texture bind-group churn.
+// ============================================================================
+import { calculateViewProj, createLogger, createValidatedShaderModule, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
+const MODEL_WGSL = "struct Uniforms {\n  viewProj: mat4x4<f32>,\n  cameraPos: vec3<f32>,\n  time: f32,\n  modelPos: vec3<f32>,\n  modelScale: vec3<f32>,\n  modelRot: vec4<f32>,\n  materialIndex: u32,\n  lightDirX: f32,\n  lightDirY: f32,\n  lightDirZ: f32,\n  lightAmbient: f32,\n  lightIntensity: f32,\n  // Per-draw highlight mode: 0 = normal shading, 1 = ghost hologram (cyan,\n  // used for the physgun's no-collision grab), 2 = hover outline (drawn by a\n  // separate inverted-hull pipeline — see vs_outline / fs_outline).\n  // Values >= 3 encode per-prop material overrides (spawn settings):\n  //   combined = u32(highlight) - 3\n  //   shaderMode = combined & 3   (0=Standard 1=Toon 2=Hologram 3=Outline)\n  //   texMode    = combined >> 2  (0=Default 1=Wireframe 2=Checker)\n  highlight: f32,\n  // Inverted-hull outline parameters (used by vs_outline / fs_outline only).\n  outlineWidth: f32,\n  outlineColor: vec3<f32>,\n};\n\n@group(0) @binding(0) var<uniform> uniforms: Uniforms;\n\n// Skin matrices for skinned meshes (@group(1)). A dynamic storage buffer of\n// mat4x4<f32>, one per bone. Updated per-frame by the renderer via\n// updateSkinMatrices(). Only bound when drawing skinned meshes.\n@group(1) @binding(0) var<storage, read> skinMatrices: array<mat4x4<f32>>;\n\n// Frame-global lighting (@group(2)): sun color, hemisphere ambient, point lights.\n// Games that want colored lighting provide a compatible uniform buffer; the\n// default bind group supplies a neutral white sun + no point lights so existing\n// consumers see no visual change.\nstruct FrameLighting {\n  sunDir: vec3<f32>,\n  ambientIntensity: f32,\n  sunColor: vec3<f32>,\n  pointLightCount: u32,\n  skyAmbient: vec3<f32>,\n  _pad0: u32,\n  groundAmbient: vec3<f32>,\n  _pad1: u32,\n  pointLights: array<vec4<f32>, 16>,\n};\n@group(2) @binding(0) var<uniform> frameLighting: FrameLighting;\n\n// Bindless material binding model (@group(3)):\n//   binding 0: material SSBO (read-only storage)\n//   bindings 1..8: texture_2d_array pages (rgba8unorm color textures)\n//   binding 9: shared sampler (repeat)\n//   binding 10: shared sampler (clamp)\nstruct BindlessMaterial {\n  baseColor: vec4<f32>,\n  roughness: f32,\n  metallic: f32,\n  emissiveIntensity: f32,\n  hasTexTransform: f32,\n  albedoTex: u32,\n  normalTex: u32,\n  metallicRoughnessTex: u32,\n  aoEmissiveTex: u32,\n  texOffset: vec2<f32>,\n  texScale: vec2<f32>,\n  texRotation: f32,\n  _pad0: f32,\n  _pad1: f32,\n  _pad2: f32,\n};\n\n@group(3) @binding(0) var<storage, read> bindlessMaterials: array<BindlessMaterial>;\n@group(3) @binding(1) var albedoArray0: texture_2d_array<f32>;\n@group(3) @binding(2) var albedoArray1: texture_2d_array<f32>;\n@group(3) @binding(3) var albedoArray2: texture_2d_array<f32>;\n@group(3) @binding(4) var albedoArray3: texture_2d_array<f32>;\n@group(3) @binding(5) var albedoArray4: texture_2d_array<f32>;\n@group(3) @binding(6) var albedoArray5: texture_2d_array<f32>;\n@group(3) @binding(7) var albedoArray6: texture_2d_array<f32>;\n@group(3) @binding(8) var albedoArray7: texture_2d_array<f32>;\n@group(3) @binding(9) var bindlessSamplerRepeat: sampler;\n@group(3) @binding(10) var bindlessSamplerClamp: sampler;\n\nfn unpackArrayIndex(handle: u32) -> u32 { return (handle >> 16u) & 0xFFFFu; }\nfn unpackLayerIndex(handle: u32) -> u32 { return handle & 0xFFFFu; }\n\nfn sampleBindlessArray(arr: u32, uv: vec2<f32>, layer: u32) -> vec4<f32> {\n  // textureSample (auto-LOD) so mipmapped registrations actually filter;\n  // single-mip textures behave identically to textureSampleLevel(..., 0.0).\n  switch (arr) {\n    case 0u: { return textureSample(albedoArray0, bindlessSamplerRepeat, uv, layer); }\n    case 1u: { return textureSample(albedoArray1, bindlessSamplerRepeat, uv, layer); }\n    case 2u: { return textureSample(albedoArray2, bindlessSamplerRepeat, uv, layer); }\n    case 3u: { return textureSample(albedoArray3, bindlessSamplerRepeat, uv, layer); }\n    case 4u: { return textureSample(albedoArray4, bindlessSamplerRepeat, uv, layer); }\n    case 5u: { return textureSample(albedoArray5, bindlessSamplerRepeat, uv, layer); }\n    case 6u: { return textureSample(albedoArray6, bindlessSamplerRepeat, uv, layer); }\n    case 7u: { return textureSample(albedoArray7, bindlessSamplerRepeat, uv, layer); }\n    default: { return vec4<f32>(1.0, 1.0, 1.0, 1.0); }\n  }\n}\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Skinned vertex input — extends VertexInput with joints (4 bone indices,\n// packed as vec4<u32>) and weights (4 normalized bone weights). Lives in a\n// second vertex buffer slot (buffer index 1).\nstruct SkinnedVertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n  @location(4) joints: vec4<u32>,\n  @location(5) weights: vec4<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) worldPos: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) uv: vec2<f32>,\n  @location(3) color: vec3<f32>,\n};\n\n// Build a tangent basis from the geometric normal. Uses a reference vector\n// instead of screen-space derivatives (dpdx/dpdy) which can produce NaN on\n// some implementations / degenerate UVs. The tangent direction is arbitrary\n// (determined by the reference vector) but is sufficient for normal mapping\n// on meshes without explicit tangent attributes.\nfn buildTangentBasis(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>) -> mat3x3<f32> {\n  var refVec = vec3<f32>(0.0, 1.0, 0.0);\n  if (abs(N.y) >= 0.99) {\n    refVec = vec3<f32>(1.0, 0.0, 0.0);\n  }\n  let T = normalize(cross(refVec, N));\n  let B = cross(N, T);\n  return mat3x3<f32>(T, B, N);\n}\n\n// Sample the normal map and perturb the geometric normal. Returns the\n// perturbed world-space normal. If the material has no normal map (normalTex\n// points at the default white texture), the sampled tangent-space normal is\n// (0.5, 0.5, 1.0) → unpacked to (0, 0, 1) → no perturbation.\nfn perturbNormal(N: vec3<f32>, worldPos: vec4<f32>, uv: vec2<f32>, normalTexHandle: u32) -> vec3<f32> {\n  let arr = unpackArrayIndex(normalTexHandle);\n  let layer = unpackLayerIndex(normalTexHandle);\n  let sampled = sampleBindlessArray(arr, uv, layer);\n  let tangentNormal = sampled.xyz * 2.0 - 1.0;\n  let basis = buildTangentBasis(N, worldPos, uv);\n  return normalize(basis * tangentNormal);\n}\n\nfn qrotate(q: vec4<f32>, v: vec3<f32>) -> vec3<f32> {\n  return v + 2.0 * cross(q.xyz, cross(q.xyz, v) + q.w * v);\n}\n\n// Accumulate the 4-bone skinning matrix: sum(weights[i] * skinMatrices[joint[i]]).\n// If all weights are zero (vertex has no bone assignment), return identity so\n// the vertex renders at its baked position instead of collapsing to the origin.\nfn skinMatrix(j: vec4<u32>, w: vec4<f32>) -> mat4x4<f32> {\n  let m = skinMatrices[j.x] * w.x\n        + skinMatrices[j.y] * w.y\n        + skinMatrices[j.z] * w.z\n        + skinMatrices[j.w] * w.w;\n  let wsum = w.x + w.y + w.z + w.w;\n  if (wsum < 0.001) {\n    return mat4x4<f32>(\n      vec4(1.0, 0.0, 0.0, 0.0),\n      vec4(0.0, 1.0, 0.0, 0.0),\n      vec4(0.0, 0.0, 1.0, 0.0),\n      vec4(0.0, 0.0, 0.0, 1.0),\n    );\n  }\n  return m;\n}\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let scaled = input.position * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, input.normal));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n// Skinned vertex entry point. Applies linear blend skinning in model space\n// (skinMatrices already encode bone-world * inverseBind), then the same\n// model transform (scale/rot/pos) as vs_main.\n@vertex\nfn vs_skinned(input: SkinnedVertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let sm = skinMatrix(input.joints, input.weights);\n  let skinnedPos = (sm * vec4<f32>(input.position, 1.0)).xyz;\n  let skinnedNormal = (sm * vec4<f32>(input.normal, 0.0)).xyz;\n\n  let scaled = skinnedPos * uniforms.modelScale;\n  let rotated = qrotate(uniforms.modelRot, scaled);\n  let worldPos = rotated + uniforms.modelPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = normalize(qrotate(uniforms.modelRot, normalize(skinnedNormal)));\n  output.uv = input.uv;\n  output.color = input.color;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let geometricN = normalize(input.normal);\n\n  // Bindless material lookup (needed for normal map handle + albedo).\n  let m = bindlessMaterials[uniforms.materialIndex];\n\n  // Perturb the normal using the material's normal map (if any). Materials\n  // without a normal map use the default flat-normal texture (0.5,0.5,1.0)\n  // → unpacked to (0,0,1) → no perturbation.\n  let N = perturbNormal(geometricN, vec4<f32>(input.worldPos, 1.0), input.uv, m.normalTex);\n\n  // Decode per-prop material overrides (highlight >= 3).\n  var shaderMode = 0u;\n  var texMode = 0u;\n  if (uniforms.highlight >= 3.0) {\n    let combined = u32(uniforms.highlight) - 3u;\n    shaderMode = combined & 3u;\n    texMode = combined >> 2u;\n  }\n\n  // Colored directional sun light — matches the procedural cube/sphere shader.\n  let sunDir = normalize(frameLighting.sunDir);\n  var ndotl = max(dot(N, sunDir), 0.0);\n  // Toon shader override: quantize the sun term into discrete bands.\n  if (shaderMode == 1u) {\n    ndotl = floor(ndotl * 3.0 + 0.5) / 3.0;\n    ndotl = max(ndotl, 0.15);\n  }\n  let sunDiffuse = ndotl * frameLighting.sunColor;\n\n  // Hemisphere ambient: blend sky/ground based on normal.y (same as cube shader).\n  let hemiMix = N.y * 0.5 + 0.5;\n  let hemisphere = mix(frameLighting.groundAmbient, frameLighting.skyAmbient, hemiMix);\n  let ambient = hemisphere * frameLighting.ambientIntensity;\n\n  // Bindless albedo sample: index the material SSBO by materialIndex, then\n  // sample the texture_2d_array page/layer the material points at.\n  let arr = unpackArrayIndex(m.albedoTex);\n  let layer = unpackLayerIndex(m.albedoTex);\n  let texColor = sampleBindlessArray(arr, input.uv, layer);\n\n  // All inputs are sRGB: texture (rgba8unorm), vertex color (white), and\n  // baseColor (parser converts FBX linear DiffuseColor to sRGB). The swapchain\n  // is non-sRGB (bgra8unorm), so output sRGB directly.\n  var baseColor = texColor.rgb * input.color * m.baseColor.rgb;\n\n  // ── Texture override modes ──\n  // Wireframe: darken albedo, UV-grid lines overlaid after lighting.\n  // Checker: two-tone checkerboard over the UVs.\n  var texLine = 0.0;\n  if (texMode == 1u) {\n    let g = fract(input.uv * 6.0);\n    let lx = min(g.x, 1.0 - g.x);\n    let ly = min(g.y, 1.0 - g.y);\n    texLine = 1.0 - smoothstep(0.0, 0.08, min(lx, ly));\n    baseColor = baseColor * 0.15;\n  } else if (texMode == 2u) {\n    let cell = floor(input.uv * 8.0);\n    let check = (cell.x + cell.y) - floor((cell.x + cell.y) * 0.5) * 2.0;\n    baseColor = mix(baseColor * 0.35, baseColor * 1.4 + vec3<f32>(0.08), check);\n  }\n\n  // Channel-inspection modes — bypass lighting entirely for material review.\n  // 3 = perturbed normals (normal-map contribution visible), 4 = unlit albedo\n  // (texture/baseColor only), 5 = geometric normals (no normal map).\n  if (texMode == 3u) { return vec4<f32>(N * 0.5 + vec3<f32>(0.5), 1.0); }\n  if (texMode == 4u) { return vec4<f32>(baseColor, 1.0); }\n  if (texMode == 5u) { return vec4<f32>(geometricN * 0.5 + vec3<f32>(0.5), 1.0); }\n\n  var litColor = baseColor * (ambient + sunDiffuse);\n\n  // Point lights (up to 8). Each light is 2 vec4s: (pos.xyz, radius) + (color.rgb, intensity).\n  let plCount = frameLighting.pointLightCount;\n  for (var i = 0u; i < plCount; i++) {\n    let pl0 = frameLighting.pointLights[i * 2u];\n    let pl1 = frameLighting.pointLights[i * 2u + 1u];\n    let plPos = pl0.xyz;\n    let plRadius = pl0.w;\n    let plColor = pl1.xyz;\n    let plIntensity = pl1.w;\n    let L = plPos - input.worldPos;\n    let dist = length(L);\n    if (dist < plRadius) {\n      let atten = 1.0 / (1.0 + dist * dist / (plRadius * plRadius));\n      let ndotl_pl = max(dot(N, normalize(L)), 0.0);\n      litColor += baseColor * plColor * plIntensity * atten * ndotl_pl;\n    }\n  }\n\n  // Wireframe overlay: paint the UV-grid lines in a bright tint.\n  if (texLine > 0.0) {\n    litColor = mix(litColor, vec3<f32>(0.55, 0.95, 1.0), texLine * 0.9);\n  }\n\n  // Distance fog — anchored to the camera→model distance so it scales with\n  // the subject instead of a fixed 400m absolute (a 200m model viewed from\n  // 500m would otherwise fog to the ambient color entirely). Small models\n  // near the camera keep the original ~400m reach.\n  let modelDist = length(uniforms.cameraPos - uniforms.modelPos);\n  let fogStart = max(modelDist * 1.5, 60.0);\n  let fogEnd = max(modelDist * 4.0, 400.0);\n  let dist = length(uniforms.cameraPos - input.worldPos);\n  let fog = clamp(1.0 - (dist - fogStart) / (fogEnd - fogStart), 0.0, 1.0);\n  var outColor = mix(frameLighting.skyAmbient, litColor, fog);\n\n  // Outline shader override (shaderMode == 3): darken the body and add a\n  // bright fresnel rim so the prop reads with a bold cel edge.\n  if (shaderMode == 3u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 3.0);\n    outColor = outColor * 0.7 + vec3<f32>(1.0, 0.95, 0.6) * smoothstep(0.35, 0.9, fresnel);\n  }\n\n  // Hologram shader override (shaderMode == 2): fresnel rim + scanline pulse\n  // tinted toward the prop's own base color. Opaque output (the pipeline has\n  // no blend state) but reads as a hologram.\n  if (shaderMode == 2u) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let holoBase = baseColor * vec3<f32>(0.3, 0.9, 1.1) + vec3<f32>(0.05, 0.2, 0.25);\n    let holoRim = vec3<f32>(0.7, 1.0, 1.0);\n    var holoCol = mix(holoBase, holoRim, fresnel) * pulse;\n    holoCol = holoCol + holoRim * scan * 0.15 * fresnel;\n    return vec4<f32>(holoCol, 1.0);\n  }\n\n  // Ghost hologram override (highlight == 1): render the prop as a\n  // translucent-looking cyan shell with a fresnel rim and a vertical\n  // scanline pulse so it's visually distinct from normally-grabbed (solid)\n  // props. Opaque output (the pipeline has no blend state) but reads as a\n  // hologram. Hover outline (highlight == 2) is handled by a separate\n  // inverted-hull draw — see vs_outline / fs_outline below.\n  if (uniforms.highlight > 0.5 && uniforms.highlight < 1.5) {\n    let viewDir = normalize(uniforms.cameraPos - input.worldPos);\n    let fresnel = pow(1.0 - max(dot(N, viewDir), 0.0), 2.5);\n    let pulse = 0.65 + 0.35 * sin(uniforms.time * 5.0 + input.worldPos.y * 3.0);\n    let scan = 0.5 + 0.5 * sin((input.worldPos.y + uniforms.time * 2.0) * 20.0);\n    let ghostBase = vec3<f32>(0.15, 0.75, 0.95);\n    let ghostRim = vec3<f32>(0.7, 1.0, 1.0);\n    var ghostCol = mix(ghostBase, ghostRim, fresnel) * pulse;\n    ghostCol = ghostCol + ghostRim * scan * 0.15 * fresnel;\n    return vec4<f32>(ghostCol, 1.0);\n  }\n\n  return vec4<f32>(outColor, 1.0);\n}\n\n// ── Mask entry point for post-process outline ──\n// Renders the model as solid white to a mask texture.  Uses the same\n// vertex shader as the normal render (vs_main / vs_skinned).\n@fragment\nfn fs_mask() -> @location(0) vec4f {\n  return vec4f(1.0, 1.0, 1.0, 1.0);\n}\n";
+const log = createLogger();
+export class ModelRenderer {
+    device;
+    format;
+    pipeline = null;
+    /** Inverted-hull outline pipeline (front-face culled, vertex-extruded). */
+    maskPipeline = null;
+    /** Depth-only pipeline for shadow map rendering (no color targets). */
+    depthPipeline = null;
+    bindGroupLayout = null;
+    uniformBuffer = null;
+    bindGroup = null;
+    perSlotBindGroups = [];
+    // 4096 slots × 256 bytes = 1 MiB uniform buffer. Character FBX models can
+    // have hundreds of meshes (e.g. Aisha has 374 geometry nodes → 374 uniform
+    // slots). The old limit of 256 was exhausted by a single character model,
+    // leaving zero slots for prop models — props then uploaded 0 meshes but
+    // still had their nodeId written to the SAB, making them invisible (skipped
+    // by builtin rendering, early-returned by model rendering) while their
+    // physics bodies still provided collision.
+    static MAX_MODELS = 4096;
+    static UNIFORM_SIZE = 256; // 64 floats, padded to 256
+    /** Initial bone buffer capacity. Grows dynamically when larger skeletons are loaded. */
+    static INITIAL_BONE_CAPACITY = 256;
+    modelResources = new Map();
+    // Per-model instance uniform base offsets. Key = nodeId, value = array of
+    // base offsets (in bytes) for each instance. Instance 0 uses the original
+    // offsets from modelResources; instances 1+ use allocated offsets from here.
+    modelInstanceOffsets = new Map();
+    viewProjCache = null;
+    cameraPosCache = [0, 0, 0];
+    // Light state for the fragment shader (defaults match the old hardcoded values).
+    // lightDir is in world space (does not need to be normalized — the shader normalizes).
+    lightDirCache = [0.5, 0.8, 0.3];
+    lightAmbientCache = 0.5;
+    lightIntensityCache = 0.5;
+    nextUniformOffset = 0;
+    reusableUniforms = new Float32Array(64);
+    reusableUniformsU32 = new Uint32Array(this.reusableUniforms.buffer);
+    textureLoadVersion = new Map();
+    // Skinning: a shared storage buffer of bone matrices (MAX_BONES * mat4),
+    // updated per-frame via updateSkinMatrices. Bound at @group(1) for skinned
+    // draws only.
+    skinMatrixBuffer = null;
+    skinBindGroupLayout = null;
+    skinBindGroup = null;
+    skinnedPipeline = null;
+    skinBindGroupSetThisFrame = false;
+    /** Current bone capacity (number of mat4s the skin buffer can hold). Grows on demand. */
+    boneCapacity = ModelRenderer.INITIAL_BONE_CAPACITY;
+    // Bindless deps
+    bindless = null;
+    bindlessLayout = null;
+    bindlessBindGroup = null;
+    bindlessBindGroupSetThisFrame = false;
+    // Frame-global lighting bind group (group 2). Provides sun color, hemisphere
+    // ambient, and point lights. Defaults to a neutral white-sun / no-point-light
+    // bind group so existing consumers see no visual change. Games with colored
+    // lighting call setFrameLightingBindGroup() each frame to override.
+    frameLightingLayout = null;
+    defaultFrameLightingBuffer = null;
+    defaultFrameLightingBg = null;
+    frameLightingBg = null;
+    frameLightingBgSetThisFrame = false;
+    /** materialIndex for the default white material (albedo = default white layer). */
+    defaultMaterialIndex = 0;
+    /** Composite key `${nodeId}:${matIdx}` → bindless materialIndex, so reupload reuses the same slot. */
+    meshMaterialIndex = new Map();
+    /** Composite key `${nodeId}:${matIdx}` → texture sourceId (used for async update + cleanup). */
+    meshTextureSourceId = new Map();
+    meshNormalTextureSourceId = new Map();
+    /** Track the current albedo handle per materialKey (for normal texture updates). */
+    meshAlbedoHandle = new Map();
+    /** The desired baseColor per materialKey — async texture-load updates re-apply
+     *  it instead of stomping to white, so runtime tints survive texture swaps. */
+    meshBaseColor = new Map();
+    /** When true, newly registered mesh textures get a full mip chain.
+     *  Toggle takes effect on the next uploadModel/reuploadModel (textures are
+     *  re-registered into a mipmapped bucket). */
+    mipmapsEnabled = false;
+    constructor(device, format) {
+        this.device = device;
+        this.format = format;
+    }
+    /** Provide the bindless texture registry + material manager. Required before init. */
+    setBindlessDeps(deps) {
+        this.bindless = deps;
+        this.bindlessLayout = deps.bindGroupLayout;
+        // Register a default white material (all texture slots → default white handle).
+        this.defaultMaterialIndex = deps.materialManager.registerMaterial({
+            baseColor: [1, 1, 1, 1],
+            roughness: 1,
+            metallic: 0,
+            emissiveIntensity: 0,
+            albedoTexHandle: deps.registry.defaultWhiteHandle,
+            normalTexHandle: deps.registry.defaultNormalHandle,
+            metallicRoughnessTexHandle: deps.registry.defaultWhiteHandle,
+            aoTexHandle: deps.registry.defaultWhiteHandle,
+            emissiveTexHandle: deps.registry.defaultWhiteHandle,
+        });
+    }
+    /** Set the shared bindless bind group (@group(3)) for the frame. */
+    setBindlessBindGroup(bg) {
+        this.bindlessBindGroup = bg;
+        this.bindlessBindGroupSetThisFrame = false;
+    }
+    /**
+     * Set the frame-global lighting bind group (group 2). Provides sun color,
+     * hemisphere ambient, and point lights via a uniform buffer matching the
+     * FrameLighting WGSL struct. Call once per frame before render(). If never
+     * called, a default neutral bind group is used (white sun, no point lights).
+     */
+    setFrameLightingBindGroup(bg) {
+        this.frameLightingBg = bg;
+        this.frameLightingBgSetThisFrame = false;
+    }
+    /** Get the frame-lighting bind group layout (for creating compatible bind groups). */
+    getFrameLightingLayout() {
+        return this.frameLightingLayout;
+    }
+    async init() {
+        this.uniformBuffer = this.device.createBuffer({
+            size: ModelRenderer.MAX_MODELS * ModelRenderer.UNIFORM_SIZE,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // Explicit bind group layout for group(0) — per-draw uniform with
+        // hasDynamicOffset so we can index into the uniform buffer per instance.
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: { type: "uniform", hasDynamicOffset: true },
+                },
+            ],
+        });
+        this.bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.uniformBuffer, size: ModelRenderer.UNIFORM_SIZE } },
+            ],
+        });
+        // Per-slot bind groups with the uniform offset baked into the resource.
+        // The layout declares hasDynamicOffset, so bind calls must pass [0].
+        this.perSlotBindGroups = [];
+        for (let i = 0; i < ModelRenderer.MAX_MODELS; i++) {
+            this.perSlotBindGroups.push(this.device.createBindGroup({
+                layout: this.bindGroupLayout,
+                entries: [{ binding: 0, resource: { buffer: this.uniformBuffer, offset: i * ModelRenderer.UNIFORM_SIZE, size: ModelRenderer.UNIFORM_SIZE } }],
+            }));
+        }
+        // Frame-lighting bind group layout (group 2): a single uniform buffer
+        // providing sun color, hemisphere ambient, and point lights. A default
+        // neutral bind group is created so existing consumers see no visual change.
+        this.frameLightingLayout = this.device.createBindGroupLayout({
+            label: "model-frame-lighting-layout",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+            ],
+        });
+        // Default frame-lighting UBO: white sun, neutral hemisphere, no point lights.
+        // Layout: sunDir(3)+ambientIntensity(1), sunColor(3)+pointLightCount(1),
+        //         skyAmbient(3)+pad(1), groundAmbient(3)+pad(1), pointLights(16 vec4s)
+        const defaultLightingData = new Float32Array(80);
+        // sunDir must be non-zero: fs_main does normalize(sunDir), and a zero
+        // vector produces NaN that turns the entire fragment output black.
+        defaultLightingData[0] = 0.4;
+        defaultLightingData[1] = 0.8;
+        defaultLightingData[2] = 0.3; // sunDir
+        defaultLightingData[3] = 1.0; // ambientIntensity
+        defaultLightingData[4] = 1.0;
+        defaultLightingData[5] = 1.0;
+        defaultLightingData[6] = 1.0; // sunColor
+        defaultLightingData[8] = 1.0;
+        defaultLightingData[9] = 1.0;
+        defaultLightingData[10] = 1.0; // skyAmbient
+        defaultLightingData[12] = 1.0;
+        defaultLightingData[13] = 1.0;
+        defaultLightingData[14] = 1.0; // groundAmbient
+        this.defaultFrameLightingBuffer = this.device.createBuffer({
+            label: "model-default-frame-lighting",
+            size: defaultLightingData.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.defaultFrameLightingBuffer, 0, defaultLightingData);
+        this.defaultFrameLightingBg = this.device.createBindGroup({
+            label: "model-default-frame-lighting-bg",
+            layout: this.frameLightingLayout,
+            entries: [{ binding: 0, resource: { buffer: this.defaultFrameLightingBuffer } }],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: MODEL_WGSL, label: "ModelRenderer" });
+        // Explicit pipeline layout: group(0) = per-draw uniform (dynamic offset),
+        // group(2) = frame-lighting UBO, group(3) = bindless materials SSBO +
+        // texture arrays. Group 1 is unused by the non-skinned pipeline (empty layout).
+        const emptyLayout = this.device.createBindGroupLayout({ entries: [] });
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout, emptyLayout, this.frameLightingLayout, this.bindlessLayout],
+        });
+        this.pipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_main",
+                buffers: [
+                    {
+                        arrayStride: 44, // pos3 + normal3 + uv2 + color3 = 11 floats
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x2" },
+                            { shaderLocation: 3, offset: 32, format: "float32x3" },
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_main",
+                targets: [{ format: this.format }],
+            },
+            primitive: { topology: "triangle-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: true,
+                depthCompare: "less",
+            },
+        });
+        // ── Skinning resources ──
+        // Shared storage buffer for bone matrices. Starts at INITIAL_BONE_CAPACITY
+        // and grows on demand when larger skeletons are loaded.
+        this.skinMatrixBuffer = this.device.createBuffer({
+            size: this.boneCapacity * 64, // mat4x4 = 64 bytes
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        // Bind group layout for @group(1): a single read-only storage buffer.
+        this.skinBindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX,
+                    buffer: { type: "read-only-storage" },
+                },
+            ],
+        });
+        this.skinBindGroup = this.device.createBindGroup({
+            layout: this.skinBindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
+        });
+        // Skinned pipeline: same pipeline layout (group 1 is now the skin layout
+        // instead of an empty layout, group 2 is the frame-lighting layout), with
+        // a second vertex buffer for joints + weights and the vs_skinned entry point.
+        const skinnedPipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout, this.skinBindGroupLayout, this.frameLightingLayout, this.bindlessLayout],
+        });
+        this.skinnedPipeline = this.device.createRenderPipeline({
+            layout: skinnedPipelineLayout,
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_skinned",
+                buffers: [
+                    {
+                        arrayStride: 44, // pos3 + normal3 + uv2 + color3 = 11 floats
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x2" },
+                            { shaderLocation: 3, offset: 32, format: "float32x3" },
+                        ],
+                    },
+                    {
+                        // joints (4 x uint8 packed as uint32x4 = 16 bytes) + weights (4 x float32 = 16 bytes) = 32 bytes
+                        arrayStride: 32,
+                        attributes: [
+                            { shaderLocation: 4, offset: 0, format: "uint32x4" },
+                            { shaderLocation: 5, offset: 16, format: "float32x4" },
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_main",
+                targets: [{ format: this.format }],
+            },
+            primitive: { topology: "triangle-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: true,
+                depthCompare: "less",
+            },
+        });
+        // ── Mask pipeline for post-process outline ──
+        // Renders the model as solid white to a mask texture.  Uses the same
+        // vertex shader as the normal render (vs_main) with back-face culling
+        // and depth testing (read-only) so the mask respects occlusion.
+        this.maskPipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_main",
+                buffers: [
+                    {
+                        arrayStride: 44,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x2" },
+                            { shaderLocation: 3, offset: 32, format: "float32x3" },
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_mask",
+                targets: [{ format: "rgba8unorm" }],
+            },
+            primitive: { topology: "triangle-list", cullMode: "back" },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: "less-equal",
+            },
+        });
+        // ── Depth-only pipeline for shadow map rendering ──
+        // Reuses vs_main (same vertex transform) but has no fragment shader /
+        // color targets — only writes depth. Uses a minimal pipeline layout with
+        // just group(0) (the per-draw uniform with dynamic offset) so the caller
+        // doesn't need to bind lighting/bindless groups for the shadow pass.
+        const depthPipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout],
+        });
+        this.depthPipeline = this.device.createRenderPipeline({
+            label: "model-depth-only",
+            layout: depthPipelineLayout,
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_main",
+                buffers: [
+                    {
+                        arrayStride: 44,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x2" },
+                            { shaderLocation: 3, offset: 32, format: "float32x3" },
+                        ],
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "back" },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: true,
+                depthCompare: "less",
+            },
+        });
+    }
+    /**
+     * Upload a model's meshes to GPU buffers and allocate uniform slots.
+     * Returns the number of meshes actually uploaded — this may be less than
+     * `meshes.length` (or 0) if the uniform buffer is full. Callers should
+     * check the return value and fall back appropriately when 0 meshes are
+     * uploaded (e.g. render as a builtin cube instead of leaving the entity
+     * invisible).
+     */
+    uploadModel(nodeId, meshes, materials, modelBaseUrl) {
+        this.removeModel(nodeId);
+        const resources = [];
+        let uniformOffset = this.nextUniformOffset;
+        for (let i = 0; i < meshes.length && uniformOffset < ModelRenderer.MAX_MODELS; i++) {
+            const mesh = meshes[i];
+            // Degenerate mesh (partial parse failure, empty geometry): nothing to
+            // draw, and a 0-byte index buffer trips wgpu-native's setIndexBuffer
+            // validation — a Rust panic that aborts the whole process.
+            if (mesh.indexCount === 0 || mesh.vertexCount === 0 || mesh.indices.byteLength === 0)
+                continue;
+            const vertexCount = mesh.vertexCount;
+            const stride = 11; // pos3 + normal3 + uv2 + color3
+            const interleaved = new Float32Array(vertexCount * stride);
+            const sOff = mesh.surfaceOffset ?? 0;
+            const sg = mesh.surfaceGirth;
+            const gA = sg ? sg.axes[0] : -1, gB = sg ? sg.axes[1] : -1;
+            const gCA = sg ? sg.centers[0] : 0, gCB = sg ? sg.centers[1] : 0;
+            const p = [0, 0, 0];
+            for (let v = 0; v < vertexCount; v++) {
+                const nx = mesh.vertices[v * 6 + 3], ny = mesh.vertices[v * 6 + 4], nz = mesh.vertices[v * 6 + 5];
+                p[0] = mesh.vertices[v * 6];
+                p[1] = mesh.vertices[v * 6 + 1];
+                p[2] = mesh.vertices[v * 6 + 2];
+                if (sg) {
+                    const s = 1 + sg.factor * sg.weights[v];
+                    p[gA] = gCA + (p[gA] - gCA) * s;
+                    p[gB] = gCB + (p[gB] - gCB) * s;
+                }
+                interleaved[v * stride] = p[0] - nx * sOff;
+                interleaved[v * stride + 1] = p[1] - ny * sOff;
+                interleaved[v * stride + 2] = p[2] - nz * sOff;
+                interleaved[v * stride + 3] = nx;
+                interleaved[v * stride + 4] = ny;
+                interleaved[v * stride + 5] = nz;
+                interleaved[v * stride + 6] = mesh.uvs ? mesh.uvs[v * 2] : 0;
+                interleaved[v * stride + 7] = mesh.uvs ? mesh.uvs[v * 2 + 1] : 0;
+                interleaved[v * stride + 8] = mesh.colors ? mesh.colors[v * 3] : 1;
+                interleaved[v * stride + 9] = mesh.colors ? mesh.colors[v * 3 + 1] : 1;
+                interleaved[v * stride + 10] = mesh.colors ? mesh.colors[v * 3 + 2] : 1;
+            }
+            const vertexBuffer = this.device.createBuffer({
+                size: interleaved.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            this.device.queue.writeBuffer(vertexBuffer, 0, interleaved);
+            const indexFormat = mesh.indices instanceof Uint32Array ? "uint32" : "uint16";
+            const indexByteLength = mesh.indices.byteLength;
+            const paddedIndexSize = Math.ceil(indexByteLength / 4) * 4;
+            const indexBuffer = this.device.createBuffer({
+                size: paddedIndexSize,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+            if (paddedIndexSize === indexByteLength) {
+                this.device.queue.writeBuffer(indexBuffer, 0, mesh.indices);
+            }
+            else {
+                const padded = new Uint8Array(paddedIndexSize);
+                padded.set(new Uint8Array(mesh.indices.buffer, mesh.indices.byteOffset, indexByteLength));
+                this.device.queue.writeBuffer(indexBuffer, 0, padded);
+            }
+            // Determine the bindless material index for this mesh based on its
+            // materialIndex field (index into ModelData.materials). Each unique
+            // (nodeId, matIdx) gets its own bindless material slot so multi-material
+            // models render each sub-mesh with its own texture.
+            const matIdx = mesh.materialIndex ?? 0;
+            const materialKey = `${nodeId}:${matIdx}`;
+            let bindlessMatIndex = this.defaultMaterialIndex;
+            if (this.bindless) {
+                const existing = this.meshMaterialIndex.get(materialKey);
+                if (existing !== undefined) {
+                    bindlessMatIndex = existing;
+                }
+                else {
+                    const mat = materials?.[matIdx];
+                    const baseColor = mat?.baseColor ?? [1, 1, 1, 1];
+                    bindlessMatIndex = this.bindless.materialManager.registerMaterial({
+                        baseColor,
+                        roughness: mat?.roughness ?? 1,
+                        metallic: mat?.metallic ?? 0,
+                        emissiveIntensity: 0,
+                        albedoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        normalTexHandle: this.bindless.registry.defaultNormalHandle,
+                        metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    });
+                    this.meshMaterialIndex.set(materialKey, bindlessMatIndex);
+                    this.meshBaseColor.set(materialKey, baseColor);
+                    // Async load this material's texture (embedded data or external URI)
+                    if (mat?.textureData && mat.textureData.byteLength > 0) {
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.textureLoadVersion.set(materialKey, version);
+                        this.loadMeshTexture(materialKey, mat.textureData, version);
+                    }
+                    else if (mat?.textureUri && modelBaseUrl) {
+                        // Resolve relative texture URI against the model's base URL.
+                        const resolvedUri = modelBaseUrl + mat.textureUri;
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.textureLoadVersion.set(materialKey, version);
+                        this.loadMeshTextureFromUri(materialKey, resolvedUri, version);
+                    }
+                    // Async load the normal texture if present.
+                    if ((mat?.normalTextureData && mat.normalTextureData.byteLength > 0) || mat?.normalTextureUri) {
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.loadMeshNormalTexture(materialKey, mat.normalTextureData ?? null, mat?.normalTextureUri, version);
+                    }
+                }
+            }
+            // Build the skin vertex buffer (joints + weights) if this mesh is skinned.
+            const skinVertexBuffer = this.buildSkinVertexBuffer(mesh);
+            resources.push({
+                vertexBuffer,
+                indexBuffer,
+                indexCount: mesh.indexCount,
+                indexFormat,
+                uniformOffset: uniformOffset * ModelRenderer.UNIFORM_SIZE,
+                materialIndex: bindlessMatIndex,
+                skinVertexBuffer,
+                skinned: skinVertexBuffer !== undefined,
+            });
+            uniformOffset++;
+        }
+        this.nextUniformOffset = uniformOffset;
+        this.modelResources.set(nodeId, resources);
+        if (resources.length < meshes.length) {
+            log.warn("model-renderer", `Uniform buffer full: uploaded ${resources.length}/${meshes.length} meshes for "${nodeId}" ` +
+                `(${uniformOffset}/${ModelRenderer.MAX_MODELS} slots used). ` +
+                `Increase MAX_MODELS to avoid invisible models.`);
+        }
+        return resources.length;
+    }
+    /**
+     * Allocate an additional uniform slot for an existing model, sharing its
+     * vertex/index buffers. Returns the instance index (1-based, since instance
+     * 0 uses the original offsets), or -1 if the model doesn't exist or the
+     * uniform buffer is full.
+     *
+     * Use with render()'s instanceIndex parameter to draw multiple instances of
+     * the same model at different positions in a single frame. Without this,
+     * multiple render() calls with the same nodeId overwrite each other's
+     * uniforms (device.queue.writeBuffer is a queue-level op, so all writes
+     * execute before the render pass — only the last write is visible).
+     */
+    allocateInstance(nodeId) {
+        const resources = this.modelResources.get(nodeId);
+        if (!resources || resources.length === 0)
+            return -1;
+        const meshCount = resources.length;
+        if (this.nextUniformOffset + meshCount > ModelRenderer.MAX_MODELS)
+            return -1;
+        // Allocate `meshCount` contiguous uniform slots for this instance.
+        const baseOffset = this.nextUniformOffset * ModelRenderer.UNIFORM_SIZE;
+        this.nextUniformOffset += meshCount;
+        const instances = this.modelInstanceOffsets.get(nodeId) ?? [];
+        instances.push(baseOffset);
+        this.modelInstanceOffsets.set(nodeId, instances);
+        return instances.length; // 1-based instance index
+    }
+    /**
+     * Free all instance uniform slots for a model (except instance 0 which is
+     * tied to the model upload). Call when an instance is no longer needed.
+     */
+    freeInstances(nodeId) {
+        const instances = this.modelInstanceOffsets.get(nodeId);
+        if (instances && instances.length > 0) {
+            // Reclaim uniform slots (simple: just reset nextUniformOffset if these
+            // were the last allocated. A production implementation would use a free
+            // list, but instance lifetimes are typically long-lived.)
+            this.nextUniformOffset = Math.max(0, this.nextUniformOffset - instances.length * this.modelResources.get(nodeId).length);
+            instances.length = 0;
+        }
+        this.modelInstanceOffsets.delete(nodeId);
+    }
+    /** Get the number of allocated instances for a model (0 = only the original). */
+    getInstanceCount(nodeId) {
+        return this.modelInstanceOffsets.get(nodeId)?.length ?? 0;
+    }
+    /**
+     * Build the per-mesh skin vertex buffer: joints as uint32x4 (4 bone indices,
+     * upcast from uint8/uint16/uint32 source) followed by weights as float32x4.
+     * 32 bytes/vertex. Returns undefined when the mesh has no skinning data.
+     */
+    buildSkinVertexBuffer(mesh) {
+        if (!mesh.joints || !mesh.weights || mesh.joints.length < mesh.vertexCount * 4)
+            return undefined;
+        const vertexCount = mesh.vertexCount;
+        // 8 slots of 4 bytes per vertex: [j0,j1,j2,j3, w0,w1,w2,w3] = 32 bytes.
+        const data = new Float32Array(vertexCount * 8);
+        const dataU32 = new Uint32Array(data.buffer);
+        for (let v = 0; v < vertexCount; v++) {
+            const src = v * 4;
+            const dst = v * 8;
+            dataU32[dst] = mesh.joints[src];
+            dataU32[dst + 1] = mesh.joints[src + 1];
+            dataU32[dst + 2] = mesh.joints[src + 2];
+            dataU32[dst + 3] = mesh.joints[src + 3];
+            data[dst + 4] = mesh.weights[src];
+            data[dst + 5] = mesh.weights[src + 1];
+            data[dst + 6] = mesh.weights[src + 2];
+            data[dst + 7] = mesh.weights[src + 3];
+        }
+        const buffer = this.device.createBuffer({
+            size: data.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(buffer, 0, data);
+        return buffer;
+    }
+    async loadMeshTexture(materialKey, textureData, version) {
+        if (!this.bindless)
+            return;
+        try {
+            const blob = new Blob([textureData]);
+            const imageBitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
+            if (this.textureLoadVersion.get(materialKey) !== version) {
+                imageBitmap.close();
+                return;
+            }
+            // Register the bitmap into the bindless texture registry. The sourceId
+            // is the materialKey so reuploadModel can reuse/update it.
+            const sourceId = `model:${materialKey}`;
+            const existing = this.bindless.registry.getRegistration(sourceId);
+            let handle;
+            if (existing) {
+                // Update in place (same dimensions expected).
+                this.bindless.registry.updateFromImageBitmap(sourceId, imageBitmap);
+                handle = existing.handle;
+            }
+            else {
+                // Atlas textures must not be mipmapped — adjacent atlas regions bleed
+                // into each other during mip downsample, causing distance-based color shifts.
+                // Albedo/color textures are sRGB-encoded (e.g. Kenney colormap.png) — use
+                // the srgb format so the GPU decodes to linear on sample. Treating them as
+                // linear (rgba8unorm) washes out midtones since the pipeline renders in
+                // linear HDR and re-encodes to sRGB at the tonemap/output stage.
+                const reg = this.bindless.registry.registerFromImageBitmap(sourceId, imageBitmap, "rgba8unorm-srgb", 1, this.mipmapsEnabled);
+                handle = reg.handle;
+            }
+            this.meshTextureSourceId.set(materialKey, sourceId);
+            this.meshAlbedoHandle.set(materialKey, handle);
+            // Update the material to point at the real albedo texture.
+            const materialIndex = this.meshMaterialIndex.get(materialKey);
+            if (materialIndex !== undefined) {
+                const matParams = {
+                    baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
+                    roughness: 1,
+                    metallic: 0,
+                    emissiveIntensity: 0,
+                    albedoTexHandle: handle,
+                    normalTexHandle: this.bindless.registry.defaultNormalHandle,
+                    metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+                };
+                this.bindless.materialManager.updateMaterial(materialIndex, matParams);
+            }
+            log.info("model-renderer", `Texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height} (bindless)`);
+            imageBitmap.close();
+        }
+        catch (e) {
+            log.error("model-renderer", `Failed to load texture for ${materialKey}: ${e}`);
+        }
+    }
+    /**
+     * Async-load a base color texture from an external URI (for GLBs that
+     * reference textures by relative path instead of embedding them).
+     */
+    async loadMeshTextureFromUri(materialKey, textureUri, version) {
+        if (!this.bindless)
+            return;
+        try {
+            const resp = await fetch(textureUri);
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            const blob = await resp.blob();
+            const imageBitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
+            if (this.textureLoadVersion.get(materialKey) !== version) {
+                imageBitmap.close();
+                return;
+            }
+            const sourceId = `model:${materialKey}`;
+            const existing = this.bindless.registry.getRegistration(sourceId);
+            let handle;
+            if (existing) {
+                this.bindless.registry.updateFromImageBitmap(sourceId, imageBitmap);
+                handle = existing.handle;
+            }
+            else {
+                // sRGB-encoded albedo (see loadMeshTexture for rationale).
+                const reg = this.bindless.registry.registerFromImageBitmap(sourceId, imageBitmap, "rgba8unorm-srgb", 1, this.mipmapsEnabled);
+                handle = reg.handle;
+            }
+            this.meshTextureSourceId.set(materialKey, sourceId);
+            this.meshAlbedoHandle.set(materialKey, handle);
+            const materialIndex = this.meshMaterialIndex.get(materialKey);
+            if (materialIndex !== undefined) {
+                const matParams = {
+                    baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
+                    roughness: 1,
+                    metallic: 0,
+                    emissiveIntensity: 0,
+                    albedoTexHandle: handle,
+                    normalTexHandle: this.bindless.registry.defaultNormalHandle,
+                    metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+                };
+                this.bindless.materialManager.updateMaterial(materialIndex, matParams);
+            }
+            imageBitmap.close();
+        }
+        catch (e) {
+            log.error("model-renderer", `Failed to load texture from URI for ${materialKey} (${textureUri}): ${e}`);
+        }
+    }
+    /**
+     * Async-load a normal texture for a material and update the bindless material
+     * to point at it. Normal textures are loaded from embedded bufferView data
+     * (normalTextureData) or fetched from normalTextureUri.
+     */
+    async loadMeshNormalTexture(materialKey, textureData, textureUri, version) {
+        if (!this.bindless)
+            return;
+        try {
+            let imageBitmap;
+            if (textureData && textureData.byteLength > 0) {
+                const blob = new Blob([textureData]);
+                imageBitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
+            }
+            else if (textureUri) {
+                const resp = await fetch(textureUri);
+                const blob = await resp.blob();
+                imageBitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
+            }
+            else {
+                return;
+            }
+            if (this.textureLoadVersion.get(materialKey) !== version) {
+                imageBitmap.close();
+                return;
+            }
+            const sourceId = `model-normal:${materialKey}`;
+            const existing = this.bindless.registry.getRegistration(sourceId);
+            let handle;
+            if (existing) {
+                this.bindless.registry.updateFromImageBitmap(sourceId, imageBitmap);
+                handle = existing.handle;
+            }
+            else {
+                const reg = this.bindless.registry.registerFromImageBitmap(sourceId, imageBitmap, "rgba8unorm", 1, this.mipmapsEnabled);
+                handle = reg.handle;
+            }
+            this.meshNormalTextureSourceId.set(materialKey, sourceId);
+            // Update the material's normalTexHandle. Preserve existing albedo handle.
+            const materialIndex = this.meshMaterialIndex.get(materialKey);
+            if (materialIndex !== undefined) {
+                const albedoHandle = this.meshAlbedoHandle.get(materialKey) ?? this.bindless.registry.defaultWhiteHandle;
+                const matParams = {
+                    baseColor: this.meshBaseColor.get(materialKey) ?? [1, 1, 1, 1],
+                    roughness: 1,
+                    metallic: 0,
+                    emissiveIntensity: 0,
+                    albedoTexHandle: albedoHandle,
+                    normalTexHandle: handle,
+                    metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+                };
+                this.bindless.materialManager.updateMaterial(materialIndex, matParams);
+            }
+            log.info("model-renderer", `Normal texture ready for ${materialKey}: ${imageBitmap.width}x${imageBitmap.height}`);
+            imageBitmap.close();
+        }
+        catch (e) {
+            log.error("model-renderer", `Failed to load normal texture for ${materialKey}: ${e}`);
+        }
+    }
+    removeModel(nodeId) {
+        const resources = this.modelResources.get(nodeId);
+        if (resources) {
+            for (let i = 0; i < resources.length; i++) {
+                resources[i].vertexBuffer.destroy();
+                resources[i].indexBuffer.destroy();
+                resources[i].skinVertexBuffer?.destroy();
+            }
+            this.nextUniformOffset = Math.max(0, this.nextUniformOffset - resources.length);
+            this.modelResources.delete(nodeId);
+        }
+        // Unregister all per-mesh textures + materials from the bindless managers.
+        // Clean up any materialKey that starts with `${nodeId}:`.
+        const prefix = `${nodeId}:`;
+        for (const [materialKey, matIdx] of this.meshMaterialIndex.entries()) {
+            if (materialKey.startsWith(prefix)) {
+                const sourceId = this.meshTextureSourceId.get(materialKey);
+                if (sourceId && this.bindless) {
+                    this.bindless.registry.unregister(sourceId);
+                    this.meshTextureSourceId.delete(materialKey);
+                }
+                if (this.bindless && matIdx !== this.defaultMaterialIndex) {
+                    this.bindless.materialManager.unregisterMaterial(matIdx);
+                }
+                this.meshMaterialIndex.delete(materialKey);
+                this.meshBaseColor.delete(materialKey);
+                this.meshAlbedoHandle.delete(materialKey);
+                this.meshNormalTextureSourceId.delete(materialKey);
+                this.textureLoadVersion.delete(materialKey);
+            }
+        }
+    }
+    /**
+     * Update an already-registered material at runtime: reload its albedo
+     * texture when `mat.textureData` is present (in-place registry update — no
+     * mesh re-upload or texture flicker) and apply its baseColor. Used by the
+     * character customizer for texture options + tints; a no-op for materials
+     * the node never registered.
+     */
+    updateMeshMaterial(nodeId, materialIndex, mat) {
+        if (!this.bindless)
+            return;
+        const materialKey = `${nodeId}:${materialIndex}`;
+        const bindlessMatIndex = this.meshMaterialIndex.get(materialKey);
+        if (bindlessMatIndex === undefined)
+            return;
+        this.meshBaseColor.set(materialKey, mat.baseColor ?? [1, 1, 1, 1]);
+        if (mat.textureData && mat.textureData.byteLength > 0) {
+            const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+            this.textureLoadVersion.set(materialKey, version);
+            void this.loadMeshTexture(materialKey, mat.textureData, version);
+            // The async load completes the updateMaterial call with the real
+            // texture handle; the immediate write below just applies the tint early.
+        }
+        const normalSourceId = this.meshNormalTextureSourceId.get(materialKey);
+        const normalHandle = normalSourceId
+            ? (this.bindless.registry.getRegistration(normalSourceId)?.handle ?? this.bindless.registry.defaultNormalHandle)
+            : this.bindless.registry.defaultNormalHandle;
+        this.bindless.materialManager.updateMaterial(bindlessMatIndex, {
+            baseColor: this.meshBaseColor.get(materialKey),
+            roughness: mat.roughness ?? 1,
+            metallic: mat.metallic ?? 0,
+            emissiveIntensity: 0,
+            albedoTexHandle: this.meshAlbedoHandle.get(materialKey) ?? this.bindless.registry.defaultWhiteHandle,
+            normalTexHandle: normalHandle,
+            metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+            aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+            emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+        });
+    }
+    reuploadModel(nodeId, meshes, materials, modelBaseUrl) {
+        // Preserve existing per-mesh texture registrations to avoid flickering on
+        // part selection changes. Per-mesh material indices are reused.
+        const oldResources = this.modelResources.get(nodeId);
+        if (oldResources) {
+            for (let i = 0; i < oldResources.length; i++) {
+                oldResources[i].vertexBuffer.destroy();
+                oldResources[i].indexBuffer.destroy();
+                oldResources[i].skinVertexBuffer?.destroy();
+            }
+            this.nextUniformOffset = Math.max(0, this.nextUniformOffset - oldResources.length);
+            this.modelResources.delete(nodeId);
+        }
+        const newResources = [];
+        let uniformOffset = this.nextUniformOffset;
+        for (let i = 0; i < meshes.length && uniformOffset < ModelRenderer.MAX_MODELS; i++) {
+            const mesh = meshes[i];
+            if (mesh.indexCount === 0 || mesh.vertexCount === 0 || mesh.indices.byteLength === 0)
+                continue;
+            const vertexCount = mesh.vertexCount;
+            const stride = 11;
+            const interleaved = new Float32Array(vertexCount * stride);
+            const sOff = mesh.surfaceOffset ?? 0;
+            const sg = mesh.surfaceGirth;
+            const gA = sg ? sg.axes[0] : -1, gB = sg ? sg.axes[1] : -1;
+            const gCA = sg ? sg.centers[0] : 0, gCB = sg ? sg.centers[1] : 0;
+            const p = [0, 0, 0];
+            for (let v = 0; v < vertexCount; v++) {
+                const nx = mesh.vertices[v * 6 + 3], ny = mesh.vertices[v * 6 + 4], nz = mesh.vertices[v * 6 + 5];
+                p[0] = mesh.vertices[v * 6];
+                p[1] = mesh.vertices[v * 6 + 1];
+                p[2] = mesh.vertices[v * 6 + 2];
+                if (sg) {
+                    const s = 1 + sg.factor * sg.weights[v];
+                    p[gA] = gCA + (p[gA] - gCA) * s;
+                    p[gB] = gCB + (p[gB] - gCB) * s;
+                }
+                interleaved[v * stride] = p[0] - nx * sOff;
+                interleaved[v * stride + 1] = p[1] - ny * sOff;
+                interleaved[v * stride + 2] = p[2] - nz * sOff;
+                interleaved[v * stride + 3] = nx;
+                interleaved[v * stride + 4] = ny;
+                interleaved[v * stride + 5] = nz;
+                interleaved[v * stride + 6] = mesh.uvs ? mesh.uvs[v * 2] : 0;
+                interleaved[v * stride + 7] = mesh.uvs ? mesh.uvs[v * 2 + 1] : 0;
+                interleaved[v * stride + 8] = mesh.colors ? mesh.colors[v * 3] : 1;
+                interleaved[v * stride + 9] = mesh.colors ? mesh.colors[v * 3 + 1] : 1;
+                interleaved[v * stride + 10] = mesh.colors ? mesh.colors[v * 3 + 2] : 1;
+            }
+            const vertexBuffer = this.device.createBuffer({
+                size: interleaved.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            this.device.queue.writeBuffer(vertexBuffer, 0, interleaved);
+            const indexFormat = mesh.indices instanceof Uint32Array ? "uint32" : "uint16";
+            const indexByteLength = mesh.indices.byteLength;
+            const paddedIndexSize = Math.ceil(indexByteLength / 4) * 4;
+            const indexBuffer = this.device.createBuffer({
+                size: paddedIndexSize,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+            if (paddedIndexSize === indexByteLength) {
+                this.device.queue.writeBuffer(indexBuffer, 0, mesh.indices);
+            }
+            else {
+                const padded = new Uint8Array(paddedIndexSize);
+                padded.set(new Uint8Array(mesh.indices.buffer, mesh.indices.byteOffset, indexByteLength));
+                this.device.queue.writeBuffer(indexBuffer, 0, padded);
+            }
+            // Per-mesh material: reuse existing bindless material if already registered,
+            // otherwise register a new one and start async texture load.
+            const matIdx = mesh.materialIndex ?? 0;
+            const materialKey = `${nodeId}:${matIdx}`;
+            let bindlessMatIndex = this.defaultMaterialIndex;
+            if (this.bindless) {
+                const existing = this.meshMaterialIndex.get(materialKey);
+                if (existing !== undefined) {
+                    bindlessMatIndex = existing;
+                }
+                else {
+                    const mat = materials?.[matIdx];
+                    const baseColor = mat?.baseColor ?? [1, 1, 1, 1];
+                    bindlessMatIndex = this.bindless.materialManager.registerMaterial({
+                        baseColor,
+                        roughness: mat?.roughness ?? 1,
+                        metallic: mat?.metallic ?? 0,
+                        emissiveIntensity: 0,
+                        albedoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        normalTexHandle: this.bindless.registry.defaultNormalHandle,
+                        metallicRoughnessTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        aoTexHandle: this.bindless.registry.defaultWhiteHandle,
+                        emissiveTexHandle: this.bindless.registry.defaultWhiteHandle,
+                    });
+                    this.meshMaterialIndex.set(materialKey, bindlessMatIndex);
+                    this.meshBaseColor.set(materialKey, baseColor);
+                    // Start async texture load if this material has texture data and no
+                    // existing registration (first time seeing this material).
+                    if (mat?.textureData && mat.textureData.byteLength > 0 && !this.meshTextureSourceId.has(materialKey)) {
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.textureLoadVersion.set(materialKey, version);
+                        this.loadMeshTexture(materialKey, mat.textureData, version);
+                    }
+                    else if (mat?.textureUri && modelBaseUrl && !this.meshTextureSourceId.has(materialKey)) {
+                        const resolvedUri = modelBaseUrl + mat.textureUri;
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.textureLoadVersion.set(materialKey, version);
+                        this.loadMeshTextureFromUri(materialKey, resolvedUri, version);
+                    }
+                    // Start async normal texture load if present and not yet loaded.
+                    if (((mat?.normalTextureData && mat.normalTextureData.byteLength > 0) || mat?.normalTextureUri) && !this.meshNormalTextureSourceId.has(materialKey)) {
+                        const version = (this.textureLoadVersion.get(materialKey) ?? 0) + 1;
+                        this.loadMeshNormalTexture(materialKey, mat.normalTextureData ?? null, mat?.normalTextureUri, version);
+                    }
+                }
+            }
+            const skinVertexBuffer = this.buildSkinVertexBuffer(mesh);
+            newResources.push({
+                vertexBuffer,
+                indexBuffer,
+                indexCount: mesh.indexCount,
+                indexFormat,
+                uniformOffset: uniformOffset * ModelRenderer.UNIFORM_SIZE,
+                materialIndex: bindlessMatIndex,
+                skinVertexBuffer,
+                skinned: skinVertexBuffer !== undefined,
+            });
+            uniformOffset++;
+        }
+        this.nextUniformOffset = uniformOffset;
+        this.modelResources.set(nodeId, newResources);
+        return newResources.length;
+    }
+    beginFrame(camera) {
+        this.viewProjCache = calculateViewProj(camera);
+        this.cameraPosCache = [camera.position[0], camera.position[1], camera.position[2]];
+        this.bindlessBindGroupSetThisFrame = false;
+        this.skinBindGroupSetThisFrame = false;
+        this.frameLightingBgSetThisFrame = false;
+    }
+    /**
+     * The effective frame-lighting bind group for group(2): the caller-provided
+     * one if set, otherwise the default neutral one created in init(). The model
+     * pipeline's group(2) layout is the explicit frameLightingLayout, so a
+     * compatible bind group MUST be bound before every draw — otherwise a stale
+     * group(2) from a prior pipeline (e.g. an auto-layout procedural pipeline)
+     * triggers a WebGPU bind-group-layout incompatibility error.
+     */
+    get effectiveFrameLightingBg() {
+        return this.frameLightingBg ?? this.defaultFrameLightingBg;
+    }
+    /**
+     * Set the directional light state for the fragment shader.
+     * Call once per frame before render(). All values are in world space.
+     *
+     * @param dir Light direction (the direction the light travels). The shader
+     *   normalizes this. For a sun at the top of the sky in a Y-down world, use
+     *   a negative Y (e.g. [0.5, -0.8, 0.3]).
+     * @param ambient Ambient light level (0-1). Combined with directional.
+     * @param intensity Directional light intensity (0-1). Final lighting = ambient + ndotl * intensity.
+     */
+    setLightState(dir, ambient, intensity) {
+        this.lightDirCache = dir;
+        this.lightAmbientCache = ambient;
+        this.lightIntensityCache = intensity;
+    }
+    /**
+     * Enable/disable mip-chain generation for mesh textures. Takes effect on
+     * the next uploadModel/reuploadModel — existing registrations are not
+     * re-bucketed. Callers should re-upload (removeModel + uploadModel) to
+     * apply the change to already-loaded models.
+     */
+    setMipmapsEnabled(enabled) {
+        this.mipmapsEnabled = enabled;
+    }
+    getMipmapsEnabled() {
+        return this.mipmapsEnabled;
+    }
+    /**
+     * Upload bone skin matrices for the current frame. The `matrices` buffer is
+     * a flat Float32Array of boneCount * 16 floats (column-major mat4s). It is
+     * copied into the shared skin matrix storage buffer. If the buffer is too
+     * small for the current skeleton, it is recreated (grown) automatically.
+     * Call once per frame before render() for skinned models.
+     */
+    updateSkinMatrices(matrices) {
+        if (!this.skinMatrixBuffer)
+            return;
+        const requiredBones = matrices.length / 16;
+        if (requiredBones > this.boneCapacity) {
+            // Grow the skin matrix buffer to fit the larger skeleton.
+            // Round up to the next power of 2 to reduce reallocations.
+            const newCapacity = Math.max(requiredBones, this.boneCapacity * 2);
+            this.skinMatrixBuffer.destroy();
+            this.skinMatrixBuffer = this.device.createBuffer({
+                size: newCapacity * 64,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            this.boneCapacity = newCapacity;
+            // Recreate the bind group with the new buffer
+            if (this.skinBindGroupLayout) {
+                this.skinBindGroup = this.device.createBindGroup({
+                    layout: this.skinBindGroupLayout,
+                    entries: [{ binding: 0, resource: { buffer: this.skinMatrixBuffer } }],
+                });
+            }
+            this.skinBindGroupSetThisFrame = false; // force re-bind
+        }
+        this.device.queue.writeBuffer(this.skinMatrixBuffer, 0, matrices);
+    }
+    render(passEncoder, nodeId, position, rotation, scale, instanceIndex = 0, 
+    /** Per-draw highlight: 0 = normal shading, 1 = ghost hologram (cyan),
+     *  2 = hover outline (bright rim). Values >= 3 encode per-prop material
+     *  overrides: `3 + shaderMode + texMode * 4` where shaderMode is
+     *  0=Standard 1=Toon 2=Hologram 3=Outline and texMode is
+     *  0=Default 1=Wireframe 2=Checker. Defaults to 0 (normal). */
+    highlight = 0) {
+        if (!this.pipeline || !this.bindGroup || !this.uniformBuffer || !this.viewProjCache)
+            return;
+        const resources = this.modelResources.get(nodeId);
+        if (!resources || resources.length === 0)
+            return;
+        // For instance 0, use the original uniform offsets stored in resources.
+        // For instance 1+, compute offsets from the allocated instance base.
+        let instanceBaseOffset = 0; // in bytes, added to each mesh's uniformOffset
+        if (instanceIndex > 0) {
+            const instances = this.modelInstanceOffsets.get(nodeId);
+            if (!instances || instanceIndex > instances.length)
+                return;
+            instanceBaseOffset = instances[instanceIndex - 1];
+            // instanceBaseOffset is the absolute byte offset for mesh 0 of this
+            // instance. Mesh r's offset = instanceBaseOffset + r * UNIFORM_SIZE.
+            // But res.uniformOffset is already mesh 0's original offset + r * UNIFORM_SIZE.
+            // So the per-mesh offset for this instance = instanceBaseOffset + r * UNIFORM_SIZE.
+            // We compute it as: instanceBaseOffset - resources[0].uniformOffset + res.uniformOffset
+            // = instanceBaseOffset + (res.uniformOffset - resources[0].uniformOffset)
+            // = instanceBaseOffset + r * UNIFORM_SIZE (since original offsets are contiguous).
+        }
+        // Set the bindless material bind group once per frame (group 3).
+        if (this.bindlessBindGroup && !this.bindlessBindGroupSetThisFrame) {
+            passEncoder.setBindGroup(3, this.bindlessBindGroup);
+            this.bindlessBindGroupSetThisFrame = true;
+        }
+        // Set the frame-lighting bind group once per frame (group 2). Must be
+        // bound explicitly — the model pipeline's group(2) uses an explicit layout
+        // that is incompatible with auto-layout bind groups left over from other
+        // pipelines drawn earlier in the same pass.
+        const frameLightBg = this.effectiveFrameLightingBg;
+        if (frameLightBg && !this.frameLightingBgSetThisFrame) {
+            passEncoder.setBindGroup(2, frameLightBg);
+            this.frameLightingBgSetThisFrame = true;
+        }
+        // Set the skin-matrix bind group once per frame (group 1) when any skinned
+        // mesh is drawn. The skin matrix buffer is updated per-frame by the caller
+        // via updateSkinMatrices().
+        const hasSkinned = resources.some((r) => r.skinned);
+        if (hasSkinned && this.skinBindGroup && !this.skinBindGroupSetThisFrame) {
+            passEncoder.setBindGroup(1, this.skinBindGroup);
+            this.skinBindGroupSetThisFrame = true;
+        }
+        const mesh0Offset = resources[0].uniformOffset;
+        for (let r = 0; r < resources.length; r++) {
+            const res = resources[r];
+            // Compute the uniform offset for this instance + mesh.
+            const uniformOffset = instanceIndex === 0
+                ? res.uniformOffset
+                : instanceBaseOffset + (res.uniformOffset - mesh0Offset);
+            const uniforms = this.reusableUniforms;
+            for (let i = 0; i < 16; i++)
+                uniforms[i] = this.viewProjCache[i];
+            uniforms[16] = this.cameraPosCache[0];
+            uniforms[17] = this.cameraPosCache[1];
+            uniforms[18] = this.cameraPosCache[2];
+            uniforms[19] = performance.now() / 1000;
+            uniforms[20] = position[0];
+            uniforms[21] = position[1];
+            uniforms[22] = position[2];
+            // uniforms[23] = padding (vec3<f32> alignment in WGSL uniform layout)
+            uniforms[24] = scale[0];
+            uniforms[25] = scale[1];
+            uniforms[26] = scale[2];
+            // uniforms[27] = padding (vec4<f32> alignment in WGSL uniform layout)
+            uniforms[28] = rotation[0];
+            uniforms[29] = rotation[1];
+            uniforms[30] = rotation[2];
+            uniforms[31] = rotation[3];
+            // materialIndex (u32) at float slot 32 — write via Uint32Array view so
+            // the shader reads the correct u32 bit pattern (not a float reinterpretation).
+            this.reusableUniformsU32[32] = res.materialIndex;
+            // Light state at float slots 33-35 (the former _pad3/_pad4/_pad5 slots):
+            //   33: lightDir.x, 34: lightDir.y, 35: lightDir.z
+            //   36: ambient, 37: intensity
+            uniforms[33] = this.lightDirCache[0];
+            uniforms[34] = this.lightDirCache[1];
+            uniforms[35] = this.lightDirCache[2];
+            uniforms[36] = this.lightAmbientCache;
+            uniforms[37] = this.lightIntensityCache;
+            // highlight flag (float slot 38 — the former _pad6). Written as a float
+            // so the WGSL `highlight: f32` field reads the correct bit pattern.
+            uniforms[38] = highlight;
+            // Outline params (slots 39-42) — unused by fs_main but written so the
+            // same uniform buffer works for the outline pipeline (vs_outline /
+            // fs_outline). Defaults: 0 width, black color.
+            uniforms[39] = 0.0;
+            uniforms[40] = 0.0;
+            uniforms[41] = 0.0;
+            uniforms[42] = 0.0;
+            this.device.queue.writeBuffer(this.uniformBuffer, uniformOffset, uniforms);
+            // Select the skinned pipeline + skin vertex buffer for skinned meshes,
+            // otherwise the standard non-skinned pipeline.
+            const slotIdx = uniformOffset / ModelRenderer.UNIFORM_SIZE;
+            const mBg = this.perSlotBindGroups[slotIdx] ?? this.bindGroup;
+            if (res.skinned && this.skinnedPipeline && res.skinVertexBuffer) {
+                passEncoder.setPipeline(this.skinnedPipeline);
+                if (this.perSlotBindGroups.length > 0)
+                    passEncoder.setBindGroup(0, mBg, [0]);
+                else
+                    passEncoder.setBindGroup(0, mBg, [uniformOffset]);
+                passEncoder.setVertexBuffer(0, res.vertexBuffer);
+                passEncoder.setVertexBuffer(1, res.skinVertexBuffer);
+                passEncoder.setIndexBuffer(res.indexBuffer, res.indexFormat);
+                passEncoder.drawIndexed(res.indexCount);
+            }
+            else {
+                passEncoder.setPipeline(this.pipeline);
+                if (this.perSlotBindGroups.length > 0)
+                    passEncoder.setBindGroup(0, mBg, [0]);
+                else
+                    passEncoder.setBindGroup(0, mBg, [uniformOffset]);
+                passEncoder.setVertexBuffer(0, res.vertexBuffer);
+                passEncoder.setIndexBuffer(res.indexBuffer, res.indexFormat);
+                passEncoder.drawIndexed(res.indexCount);
+            }
+        }
+    }
+    /**
+     * Render the model as solid white to a mask texture for the post-process
+     * outline.  Uses the same vertex shader as the normal render (vs_main)
+     * with a simple white fragment shader (fs_mask).  Depth-tested against
+     * the scene depth (read-only) so the mask respects occlusion.
+     */
+    renderMask(passEncoder, nodeId, position, rotation, scale) {
+        if (!this.maskPipeline || !this.bindGroup || !this.uniformBuffer || !this.viewProjCache)
+            return;
+        const resources = this.modelResources.get(nodeId);
+        if (!resources || resources.length === 0)
+            return;
+        if (this.bindlessBindGroup && !this.bindlessBindGroupSetThisFrame) {
+            passEncoder.setBindGroup(3, this.bindlessBindGroup);
+            this.bindlessBindGroupSetThisFrame = true;
+        }
+        // renderMask() runs in a separate render pass from render(), so the
+        // per-frame "set this frame" flags are unreliable (they may already be
+        // true from the scene pass). Bind group 2 (frame lighting) and group 3
+        // (bindless) explicitly here — both are non-empty in the mask pipeline's
+        // layout and must be re-bound for this pass.
+        const maskFrameLightBg = this.effectiveFrameLightingBg;
+        if (maskFrameLightBg)
+            passEncoder.setBindGroup(2, maskFrameLightBg);
+        if (this.bindlessBindGroup)
+            passEncoder.setBindGroup(3, this.bindlessBindGroup);
+        for (let r = 0; r < resources.length; r++) {
+            const res = resources[r];
+            const uniformOffset = res.uniformOffset;
+            const uniforms = this.reusableUniforms;
+            for (let i = 0; i < 16; i++)
+                uniforms[i] = this.viewProjCache[i];
+            uniforms[16] = this.cameraPosCache[0];
+            uniforms[17] = this.cameraPosCache[1];
+            uniforms[18] = this.cameraPosCache[2];
+            uniforms[19] = performance.now() / 1000;
+            uniforms[20] = position[0];
+            uniforms[21] = position[1];
+            uniforms[22] = position[2];
+            uniforms[24] = scale[0];
+            uniforms[25] = scale[1];
+            uniforms[26] = scale[2];
+            uniforms[28] = rotation[0];
+            uniforms[29] = rotation[1];
+            uniforms[30] = rotation[2];
+            uniforms[31] = rotation[3];
+            this.reusableUniformsU32[32] = res.materialIndex;
+            // Remaining fields not read by fs_mask.
+            this.device.queue.writeBuffer(this.uniformBuffer, uniformOffset, uniforms);
+            passEncoder.setPipeline(this.maskPipeline);
+            passEncoder.setBindGroup(0, this.bindGroup, [uniformOffset]);
+            passEncoder.setVertexBuffer(0, res.vertexBuffer);
+            passEncoder.setIndexBuffer(res.indexBuffer, res.indexFormat);
+            passEncoder.drawIndexed(res.indexCount);
+        }
+    }
+    /**
+     * Render the model depth-only into a shadow map from an arbitrary
+     * view-projection (the light's VP). Uses the depthPipeline (no color
+     * targets, depthWriteEnabled). Only group(0) (per-draw uniform) is bound
+     * — the depthPipeline's layout has no lighting/bindless groups.
+     *
+     * @param viewProj The light's view-projection matrix (16 floats).
+     */
+    renderDepth(passEncoder, viewProj, nodeId, position, rotation, scale) {
+        if (!this.depthPipeline || !this.bindGroup || !this.uniformBuffer)
+            return;
+        const resources = this.modelResources.get(nodeId);
+        if (!resources || resources.length === 0)
+            return;
+        const uniforms = this.reusableUniforms;
+        for (let r = 0; r < resources.length; r++) {
+            const res = resources[r];
+            const uniformOffset = res.uniformOffset;
+            // viewProj (light VP) replaces the camera viewProj for shadow rendering.
+            for (let i = 0; i < 16; i++)
+                uniforms[i] = viewProj[i];
+            // cameraPos + time not read by the vertex shader, but zero for safety.
+            uniforms[16] = 0;
+            uniforms[17] = 0;
+            uniforms[18] = 0;
+            uniforms[19] = 0;
+            uniforms[20] = position[0];
+            uniforms[21] = position[1];
+            uniforms[22] = position[2];
+            uniforms[24] = scale[0];
+            uniforms[25] = scale[1];
+            uniforms[26] = scale[2];
+            uniforms[28] = rotation[0];
+            uniforms[29] = rotation[1];
+            uniforms[30] = rotation[2];
+            uniforms[31] = rotation[3];
+            this.reusableUniformsU32[32] = res.materialIndex;
+            this.device.queue.writeBuffer(this.uniformBuffer, uniformOffset, uniforms);
+            passEncoder.setPipeline(this.depthPipeline);
+            passEncoder.setBindGroup(0, this.bindGroup, [uniformOffset]);
+            passEncoder.setVertexBuffer(0, res.vertexBuffer);
+            passEncoder.setIndexBuffer(res.indexBuffer, res.indexFormat);
+            passEncoder.drawIndexed(res.indexCount);
+        }
+    }
+    hasModel(nodeId) {
+        return this.modelResources.has(nodeId);
+    }
+    /**
+     * Overwrite a mesh's vertex buffer with new interleaved data (stride 11:
+     * pos3 + normal3 + uv2 + color3). Used for CPU-side mesh deformation —
+     * the caller owns the vertex layout and must supply vertexCount*11 floats.
+     */
+    updateVertexBuffer(nodeId, meshIndex, interleaved) {
+        const res = this.modelResources.get(nodeId)?.[meshIndex];
+        if (!res)
+            return;
+        this.device.queue.writeBuffer(res.vertexBuffer, 0, interleaved);
+    }
+    /**
+     * Overwrite a mesh's index buffer with a compacted triangle list and update
+     * the draw count. Used for CPU-side mesh deformation that deletes triangles
+     * (e.g. punched-through holes). `indices`/`indexCount` describe the live
+     * prefix of the caller's index array.
+     */
+    updateIndexBuffer(nodeId, meshIndex, indices, indexCount) {
+        const res = this.modelResources.get(nodeId)?.[meshIndex];
+        if (!res)
+            return;
+        const live = indices.subarray(0, indexCount);
+        const byteLen = live.byteLength;
+        if (byteLen % 4 === 0) {
+            this.device.queue.writeBuffer(res.indexBuffer, 0, live);
+        }
+        else {
+            const padded = new Uint8Array(Math.ceil(byteLen / 4) * 4);
+            padded.set(new Uint8Array(live.buffer, live.byteOffset, byteLen));
+            this.device.queue.writeBuffer(res.indexBuffer, 0, padded);
+        }
+        res.indexCount = indexCount;
+    }
+    destroy() {
+        const ids = Array.from(this.modelResources.keys());
+        for (let i = 0; i < ids.length; i++) {
+            this.removeModel(ids[i]);
+        }
+        this.skinMatrixBuffer?.destroy();
+    }
+}