@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/assets/model-normalizer.js

@@ -0,0 +1,213 @@
+// ============================================================================
+// Model Normalizer — pure transform math for model import normalization
+// ============================================================================
+// These functions operate on plugin MeshData (interleaved pos+normal, 6 floats
+// per vertex: [px, py, pz, nx, ny, nz, ...]). They mutate in place, matching
+// the existing convertZUpToYUp pattern.
+//
+// Higher-level orchestration (sidecar resolution, node-transform baking, the
+// full normalize pipeline) lives in @downdraft/engine/libraries/models/normalize.
+//
+const VERTEX_STRIDE = 6; // pos(3) + normal(3)
+/** Unit conversion factors: source unit → meters. */
+export const UNIT_TO_METERS = {
+    meters: 1.0,
+    centimeters: 0.01,
+    inches: 0.0254,
+    millimeters: 0.001,
+    units: 1.0, // unknown — no conversion
+};
+/**
+ * Rotate vertices and normals from Z-up to Y-up.
+ * Transformation: (x, y, z) → (x, z, -y)  [-90° rotation around X]
+ * No-op if already Y-up.
+ */
+export function applyUpAxisConversion(meshes, fromAxis) {
+    if (fromAxis === "y")
+        return;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            // Position: (x, y, z) → (x, z, -y)
+            const py = verts[base + 1];
+            const pz = verts[base + 2];
+            verts[base + 1] = pz;
+            verts[base + 2] = -py;
+            // Normal: same rotation
+            const ny = verts[base + 4];
+            const nz = verts[base + 5];
+            verts[base + 4] = nz;
+            verts[base + 5] = -ny;
+        }
+    });
+}
+/**
+ * Scale all vertex positions by a unit conversion factor (source → meters).
+ * Normals are unchanged (direction vectors are not affected by uniform scale).
+ */
+export function applyUnitScale(meshes, fromUnits) {
+    const factor = UNIT_TO_METERS[fromUnits] ?? 1.0;
+    if (factor === 1.0)
+        return;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            verts[base] *= factor;
+            verts[base + 1] *= factor;
+            verts[base + 2] *= factor;
+        }
+    });
+}
+/**
+ * Apply a uniform scale factor to all vertex positions.
+ * Used for user scale overrides and auto-fit.
+ */
+export function applyRootScale(meshes, scaleFactor) {
+    if (scaleFactor === 1.0)
+        return;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            verts[base] *= scaleFactor;
+            verts[base + 1] *= scaleFactor;
+            verts[base + 2] *= scaleFactor;
+        }
+    });
+}
+/** Quaternion multiply: a * b (Hamilton product). */
+function qmul(a, b) {
+    return [
+        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+    ];
+}
+/** Rotate vector v by quaternion q. */
+function qrotate(q, v) {
+    const qx = q[0], qy = q[1], qz = q[2], qw = q[3];
+    const vx = v[0], vy = v[1], vz = v[2];
+    // v + 2*cross(q.xyz, cross(q.xyz, v) + q.w * v)
+    const c1x = qy * vz - qz * vy + qw * vx;
+    const c1y = qz * vx - qx * vz + qw * vy;
+    const c1z = qx * vy - qy * vx + qw * vz;
+    const c2x = qy * c1z - qz * c1y;
+    const c2y = qz * c1x - qx * c1z;
+    const c2z = qx * c1y - qy * c1x;
+    return [vx + 2 * c2x, vy + 2 * c2y, vz + 2 * c2z];
+}
+/** Check if a quaternion is identity [0,0,0,1]. */
+function isIdentityQuat(q) {
+    return q[0] === 0 && q[1] === 0 && q[2] === 0 && q[3] === 1;
+}
+/**
+ * Rotate all vertices and normals by a quaternion (root pre-rotation).
+ * Normals are rotated by the same quaternion (correct for uniform scale;
+ * for non-uniform scale the inverse-transpose would be needed, but root
+ * rotations are typically uniform).
+ */
+export function applyRootRotation(meshes, rotation) {
+    if (isIdentityQuat(rotation))
+        return;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            // Position
+            const pos = [verts[base], verts[base + 1], verts[base + 2]];
+            const rotated = qrotate(rotation, pos);
+            verts[base] = rotated[0];
+            verts[base + 1] = rotated[1];
+            verts[base + 2] = rotated[2];
+            // Normal
+            const norm = [verts[base + 3], verts[base + 4], verts[base + 5]];
+            const rotatedN = qrotate(rotation, norm);
+            verts[base + 3] = rotatedN[0];
+            verts[base + 4] = rotatedN[1];
+            verts[base + 5] = rotatedN[2];
+        }
+    });
+}
+/**
+ * Compute the axis-aligned bounding box of all meshes.
+ * Returns {min, max} corners. Returns degenerate bounds if no vertices.
+ */
+export function computeBounds(meshes) {
+    let minX = Infinity, minY = Infinity, minZ = Infinity;
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            const x = verts[base];
+            const y = verts[base + 1];
+            const z = verts[base + 2];
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+    });
+    if (minX === Infinity) {
+        return { min: [0, 0, 0], max: [0, 0, 0] };
+    }
+    return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
+/** Get the max dimension (largest axis extent) of a bounding box. */
+export function maxDimension(bounds) {
+    return Math.max(bounds.max[0] - bounds.min[0], bounds.max[1] - bounds.min[1], bounds.max[2] - bounds.min[2], 0);
+}
+/**
+ * Subtract the bounding-box center from all vertex positions, placing the
+ * model at the origin. Normals are unchanged.
+ */
+export function centerToOrigin(meshes, bounds) {
+    const cx = (bounds.min[0] + bounds.max[0]) / 2;
+    const cy = (bounds.min[1] + bounds.max[1]) / 2;
+    const cz = (bounds.min[2] + bounds.max[2]) / 2;
+    if (cx === 0 && cy === 0 && cz === 0)
+        return;
+    meshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        for (let v = 0; v < mesh.vertexCount; v++) {
+            const base = v * VERTEX_STRIDE;
+            verts[base] -= cx;
+            verts[base + 1] -= cy;
+            verts[base + 2] -= cz;
+        }
+    });
+}
+/**
+ * Uniformly scale the model so its max dimension equals targetMaxDim.
+ * Returns the scale factor applied (or 1.0 if no scaling needed).
+ */
+export function autoFit(meshes, bounds, targetMaxDim) {
+    const currentMax = maxDimension(bounds);
+    if (currentMax <= 0 || currentMax === targetMaxDim)
+        return 1.0;
+    const scaleFactor = targetMaxDim / currentMax;
+    applyRootScale(meshes, scaleFactor);
+    return scaleFactor;
+}
+/**
+ * Check if a model's max dimension is outside a sane range.
+ * Used to trigger the dev-mode auto-fit prompt.
+ * Threshold: < 0.01m (microscopic) or > 100m (massive).
+ */
+export function isExtremeScale(bounds) {
+    const maxDim = maxDimension(bounds);
+    return maxDim > 0 && (maxDim < 0.01 || maxDim > 100);
+}
+// Re-export quaternion helpers for the node-transform baking module
+export { isIdentityQuat, qmul, qrotate };

package/dist/core/src/assets/model-to-gpu.js

@@ -0,0 +1,44 @@
+export function uploadMeshToGPU(device, mesh, cache) {
+    const vertexBuffer = device.createBuffer({
+        size: mesh.vertices.byteLength,
+        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(vertexBuffer, 0, mesh.vertices.buffer);
+    const indexByteLen = mesh.indices.byteLength;
+    const paddedIndexSize = Math.ceil(indexByteLen / 4) * 4;
+    const indexBuffer = device.createBuffer({
+        size: paddedIndexSize,
+        usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+    });
+    if (paddedIndexSize === indexByteLen) {
+        device.queue.writeBuffer(indexBuffer, 0, mesh.indices.buffer);
+    }
+    else {
+        const padded = new Uint8Array(paddedIndexSize);
+        padded.set(new Uint8Array(mesh.indices.buffer, mesh.indices.byteOffset, indexByteLen));
+        device.queue.writeBuffer(indexBuffer, 0, padded);
+    }
+    const indexFormat = mesh.indices instanceof Uint32Array ? "uint32" : "uint16";
+    const gpuMesh = {
+        vertexBuffer,
+        indexBuffer,
+        vertexCount: mesh.vertexCount,
+        indexCount: mesh.indexCount,
+        layout: mesh.layout,
+        indexFormat,
+    };
+    if (cache) {
+        cache.register(`gpuMesh:${vertexBuffer.label || "mesh"}`, gpuMesh, async () => {
+            vertexBuffer.destroy();
+            indexBuffer.destroy();
+        });
+    }
+    return gpuMesh;
+}
+export function uploadMeshesToGPU(device, meshes, cache) {
+    return meshes.map((mesh) => uploadMeshToGPU(device, mesh, cache));
+}
+export function destroyGPUMesh(mesh) {
+    mesh.vertexBuffer.destroy();
+    mesh.indexBuffer.destroy();
+}

package/dist/core/src/assets/model-to-mesh.js

@@ -0,0 +1,171 @@
+import { PBR_VERTEX_LAYOUT, SKINNED_VERTEX_LAYOUT, STANDARD_VERTEX_LAYOUT } from "../mesh/vertex-layout.js";
+function resolveLayout(target, hasSkinning) {
+    if (hasSkinning)
+        return SKINNED_VERTEX_LAYOUT;
+    if (target === "pbr")
+        return PBR_VERTEX_LAYOUT;
+    return STANDARD_VERTEX_LAYOUT;
+}
+function generateTangents(positions, normals, uvs, indices, vertexCount) {
+    if (!uvs)
+        return null;
+    const tangents = new Float32Array(vertexCount * 4);
+    const tan1 = new Float32Array(vertexCount * 3);
+    const tan2 = new Float32Array(vertexCount * 3);
+    for (let i = 0; i < indices.length; i += 3) {
+        const i0 = indices[i];
+        const i1 = indices[i + 1];
+        const i2 = indices[i + 2];
+        const v0x = positions[i0 * 3], v0y = positions[i0 * 3 + 1], v0z = positions[i0 * 3 + 2];
+        const v1x = positions[i1 * 3], v1y = positions[i1 * 3 + 1], v1z = positions[i1 * 3 + 2];
+        const v2x = positions[i2 * 3], v2y = positions[i2 * 3 + 1], v2z = positions[i2 * 3 + 2];
+        const u0 = uvs[i0 * 2], v0u = uvs[i0 * 2 + 1];
+        const u1 = uvs[i1 * 2], v1u = uvs[i1 * 2 + 1];
+        const u2 = uvs[i2 * 2], v2u = uvs[i2 * 2 + 1];
+        const d1x = v1x - v0x, d1y = v1y - v0y, d1z = v1z - v0z;
+        const d2x = v2x - v0x, d2y = v2y - v0y, d2z = v2z - v0z;
+        const du1 = u1 - u0, dv1 = v1u - v0u;
+        const du2 = u2 - u0, dv2 = v2u - v0u;
+        const r = 1.0 / (du1 * dv2 - du2 * dv1);
+        if (!isFinite(r))
+            continue;
+        const t1x = (d1x * dv2 - d2x * dv1) * r;
+        const t1y = (d1y * dv2 - d2y * dv1) * r;
+        const t1z = (d1z * dv2 - d2z * dv1) * r;
+        const t2x = (d2x * du1 - d1x * du2) * r;
+        const t2y = (d2y * du1 - d1y * du2) * r;
+        const t2z = (d2z * du1 - d1z * du2) * r;
+        tan1[i0 * 3] += t1x;
+        tan1[i0 * 3 + 1] += t1y;
+        tan1[i0 * 3 + 2] += t1z;
+        tan1[i1 * 3] += t1x;
+        tan1[i1 * 3 + 1] += t1y;
+        tan1[i1 * 3 + 2] += t1z;
+        tan1[i2 * 3] += t1x;
+        tan1[i2 * 3 + 1] += t1y;
+        tan1[i2 * 3 + 2] += t1z;
+        tan2[i0 * 3] += t2x;
+        tan2[i0 * 3 + 1] += t2y;
+        tan2[i0 * 3 + 2] += t2z;
+        tan2[i1 * 3] += t2x;
+        tan2[i1 * 3 + 1] += t2y;
+        tan2[i1 * 3 + 2] += t2z;
+        tan2[i2 * 3] += t2x;
+        tan2[i2 * 3 + 1] += t2y;
+        tan2[i2 * 3 + 2] += t2z;
+    }
+    for (let i = 0; i < vertexCount; i++) {
+        const nx = normals[i * 3], ny = normals[i * 3 + 1], nz = normals[i * 3 + 2];
+        const tx = tan1[i * 3], ty = tan1[i * 3 + 1], tz = tan1[i * 3 + 2];
+        // Gram-Schmidt orthogonalize
+        const dot = nx * tx + ny * ty + nz * tz;
+        const tX = tx - nx * dot;
+        const tY = ty - ny * dot;
+        const tZ = tz - nz * dot;
+        const len = Math.sqrt(tX * tX + tY * tY + tZ * tZ) || 1;
+        // Handedness
+        const bx = (ny * tz - nz * ty);
+        const by = (nz * tx - nx * tz);
+        const bz = (nx * ty - ny * tx);
+        const bCrossT = bx * tan2[i * 3] + by * tan2[i * 3 + 1] + bz * tan2[i * 3 + 2];
+        const w = bCrossT < 0 ? -1 : 1;
+        tangents[i * 4] = tX / len;
+        tangents[i * 4 + 1] = tY / len;
+        tangents[i * 4 + 2] = tZ / len;
+        tangents[i * 4 + 3] = w;
+    }
+    return tangents;
+}
+export function convertPluginMesh(pluginMesh, target = "pbr") {
+    const hasSkinning = !!(pluginMesh.joints && pluginMesh.weights);
+    const layout = resolveLayout(target, hasSkinning);
+    const stride = layout.stride / 4; // floats per vertex
+    const vertexCount = pluginMesh.vertexCount;
+    // Module vertices are interleaved as: pos(3) + normal(3) = 6 floats per vertex
+    const positions = pluginMesh.vertices; // [px,py,pz, nx,ny,nz, ...]
+    const normals = pluginMesh.vertices; // same array, offset by 3
+    // Generate tangents if needed
+    let tangents = null;
+    if (target === "pbr" || hasSkinning) {
+        tangents = generateTangents(positions, normals, pluginMesh.uvs, pluginMesh.indices, vertexCount);
+    }
+    // Build interleaved vertex buffer matching the target layout
+    const vertices = new Float32Array(vertexCount * stride);
+    for (let i = 0; i < vertexCount; i++) {
+        const src = i * 6; // 6 floats per vertex in plugin format (pos+norm)
+        const dst = i * stride;
+        // Position (float32x3)
+        vertices[dst + 0] = positions[src + 0];
+        vertices[dst + 1] = positions[src + 1];
+        vertices[dst + 2] = positions[src + 2];
+        // Normal (float32x3)
+        vertices[dst + 3] = positions[src + 3];
+        vertices[dst + 4] = positions[src + 4];
+        vertices[dst + 5] = positions[src + 5];
+        // UV (float32x2)
+        if (pluginMesh.uvs) {
+            vertices[dst + 6] = pluginMesh.uvs[i * 2];
+            vertices[dst + 7] = pluginMesh.uvs[i * 2 + 1];
+        }
+        else {
+            vertices[dst + 6] = 0;
+            vertices[dst + 7] = 0;
+        }
+        if (target === "pbr" || hasSkinning) {
+            // Tangent (float32x4)
+            if (tangents) {
+                vertices[dst + 8] = tangents[i * 4];
+                vertices[dst + 9] = tangents[i * 4 + 1];
+                vertices[dst + 10] = tangents[i * 4 + 2];
+                vertices[dst + 11] = tangents[i * 4 + 3];
+            }
+            else {
+                vertices[dst + 8] = 1;
+                vertices[dst + 9] = 0;
+                vertices[dst + 10] = 0;
+                vertices[dst + 11] = 1;
+            }
+        }
+        else {
+            // Color (float32x4) for standard layout
+            if (pluginMesh.colors) {
+                vertices[dst + 8] = pluginMesh.colors[i * 4];
+                vertices[dst + 9] = pluginMesh.colors[i * 4 + 1];
+                vertices[dst + 10] = pluginMesh.colors[i * 4 + 2];
+                vertices[dst + 11] = pluginMesh.colors[i * 4 + 3];
+            }
+            else {
+                vertices[dst + 8] = 1;
+                vertices[dst + 9] = 1;
+                vertices[dst + 10] = 1;
+                vertices[dst + 11] = 1;
+            }
+        }
+        // Skinning data (uint16x4 boneIndices + float32x4 boneWeights)
+        if (hasSkinning) {
+            const joints = pluginMesh.joints;
+            const weights = pluginMesh.weights;
+            // uint16x4 packed as 4 uint16 values at byte offset 48
+            const byteOffset = dst * 4 + 48;
+            const view = new Uint16Array(vertices.buffer);
+            view[byteOffset / 2 + 0] = joints[i * 4 + 0];
+            view[byteOffset / 2 + 1] = joints[i * 4 + 1];
+            view[byteOffset / 2 + 2] = joints[i * 4 + 2];
+            view[byteOffset / 2 + 3] = joints[i * 4 + 3];
+            vertices[dst + 14] = weights[i * 4 + 0];
+            vertices[dst + 15] = weights[i * 4 + 1];
+            vertices[dst + 16] = weights[i * 4 + 2];
+            vertices[dst + 17] = weights[i * 4 + 3];
+        }
+    }
+    return {
+        vertices,
+        indices: pluginMesh.indices,
+        layout,
+        vertexCount,
+        indexCount: pluginMesh.indexCount,
+    };
+}
+export function convertPluginModel(model, target = "pbr") {
+    return model.meshes.map((mesh) => convertPluginMesh(mesh, target));
+}

package/dist/core/src/assets/prefilter-generator.js

@@ -0,0 +1,220 @@
+import { createValidatedShaderModule } from "../render/shader-validator.js";
+const PREFILTER_SHADER = /* wgsl */ `
+struct Uniforms {
+  faceSize: u32,
+  roughness: f32,
+  sampleCount: u32,
+  srcSize: u32,
+};
+
+@group(0) @binding(0) var srcTex: texture_2d_array<f32>;
+@group(0) @binding(1) var dstTex: texture_storage_2d_array<rgba16float, write>;
+@group(0) @binding(2) var<uniform> uniforms: Uniforms;
+@group(0) @binding(3) var srcSampler: sampler;
+
+const PI: f32 = 3.141592653589793;
+
+fn faceDirToUV(face: u32, u: f32, v: f32) -> vec3<f32> {
+  let a = u * 2.0 - 1.0;
+  let b = v * 2.0 - 1.0;
+  switch face {
+    case 0u: { return vec3<f32>( 1.0, -b, -a); }
+    case 1u: { return vec3<f32>(-1.0, -b,  a); }
+    case 2u: { return vec3<f32>( a,  1.0,  b); }
+    case 3u: { return vec3<f32>( a, -1.0, -b); }
+    case 4u: { return vec3<f32>( a, -b,  1.0); }
+    case 5u: { return vec3<f32>(-a, -b, -1.0); }
+    default: { return vec3<f32>(0.0, 0.0, 0.0); }
+  }
+}
+
+fn dirToFaceUV(dir: vec3<f32>) -> vec3<f32> {
+  let absX = abs(dir.x);
+  let absY = abs(dir.y);
+  let absZ = abs(dir.z);
+
+  var face: u32 = 0u;
+  var ma: f32 = 0.0;
+  var sc: f32 = 0.0;
+  var tc: f32 = 0.0;
+
+  if (absX > absY && absX > absZ) {
+    if (dir.x > 0.0) { face = 0u; sc = -dir.z; tc = -dir.y; ma = dir.x; }
+    else { face = 1u; sc = dir.z; tc = -dir.y; ma = -dir.x; }
+  } else if (absY > absZ) {
+    if (dir.y > 0.0) { face = 2u; sc = dir.x; tc = dir.z; ma = dir.y; }
+    else { face = 3u; sc = dir.x; tc = -dir.z; ma = -dir.y; }
+  } else {
+    if (dir.z > 0.0) { face = 4u; sc = dir.x; tc = -dir.y; ma = dir.z; }
+    else { face = 5u; sc = -dir.x; tc = -dir.y; ma = -dir.z; }
+  }
+
+  let u = (sc / ma + 1.0) * 0.5;
+  let v = (tc / ma + 1.0) * 0.5;
+  return vec3<f32>(u, v, f32(face));
+}
+
+fn sampleCubemap(dir: vec3<f32>) -> vec3<f32> {
+  let info = dirToFaceUV(dir);
+  let face = u32(info.z);
+  let coords = vec2<i32>(
+    i32(clamp(info.x, 0.0, 1.0) * f32(uniforms.srcSize)),
+    i32(clamp(info.y, 0.0, 1.0) * f32(uniforms.srcSize)),
+  );
+  return textureLoad(srcTex, coords, i32(face), 0).rgb;
+}
+
+fn radicalInverse(bits: u32) -> f32 {
+  var b = bits;
+  b = (b << 16u) | (b >> 16u);
+  b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);
+  b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);
+  b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);
+  b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);
+  return f32(b) * 2.3283064365386963e-10;
+}
+
+fn hammersley(i: u32, N: u32) -> vec2<f32> {
+  return vec2<f32>(f32(i) / f32(N), radicalInverse(i));
+}
+
+fn importanceSampleGGX(xi: vec2<f32>, N: vec3<f32>, roughness: f32) -> vec3<f32> {
+  let a = roughness * roughness;
+  let phi = 2.0 * PI * xi.x;
+  let cosTheta = sqrt((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y));
+  let sinTheta = sqrt(1.0 - cosTheta * cosTheta);
+
+  let H = vec3<f32>(
+    sinTheta * cos(phi),
+    sinTheta * sin(phi),
+    cosTheta,
+  );
+
+  let up = select(vec3<f32>(0.0, 1.0, 0.0), vec3<f32>(1.0, 0.0, 0.0), abs(N.z) > 0.999);
+  let tangent = normalize(cross(up, N));
+  let bitangent = cross(N, tangent);
+
+  return normalize(tangent * H.x + bitangent * H.y + N * H.z);
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let faceSize = uniforms.faceSize;
+  if (gid.x >= faceSize || gid.y >= faceSize) { return; }
+
+  let face = gid.z;
+  let u = (f32(gid.x) + 0.5) / f32(faceSize);
+  let v = (f32(gid.y) + 0.5) / f32(faceSize);
+  let N = normalize(faceDirToUV(face, u, v));
+
+  let roughness = uniforms.roughness;
+  let sampleCount = uniforms.sampleCount;
+
+  var color = vec3<f32>(0.0);
+  var totalWeight = 0.0;
+
+  for (var i = 0u; i < sampleCount; i++) {
+    let xi = hammersley(i, sampleCount);
+    let H = importanceSampleGGX(xi, N, roughness);
+    let V = N;
+    let L = normalize(2.0 * dot(V, H) * H - V);
+
+    let NdotL = max(dot(N, L), 0.0);
+    if (NdotL > 0.0) {
+      color += sampleCubemap(L) * NdotL;
+      totalWeight += NdotL;
+    }
+  }
+
+  color = color / max(totalWeight, 0.001);
+  textureStore(dstTex, vec2<i32>(i32(gid.x), i32(gid.y)), i32(face), vec4<f32>(color, 1.0));
+}
+`;
+export class PrefilteredSpecularGenerator {
+    device;
+    pipeline = null;
+    bindGroupLayout = null;
+    uniformBuffer = null;
+    sampler = null;
+    constructor(device) {
+        this.device = device;
+    }
+    ensurePipeline() {
+        if (this.pipeline)
+            return;
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: "float", viewDimension: "2d-array" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, sampler: { type: "filtering" } },
+            ],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: PREFILTER_SHADER, label: "PrefilterGenerator" });
+        this.pipeline = this.device.createComputePipeline({
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            compute: { module: shaderModule, entryPoint: "cs_main" },
+        });
+        this.uniformBuffer = this.device.createBuffer({
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    generate(srcCubemap, options) {
+        this.ensurePipeline();
+        const faceSize = options.faceSize;
+        const sampleCount = options.sampleCount ?? 512;
+        const dstTexture = this.device.createTexture({
+            size: [faceSize, faceSize, 6],
+            format: "rgba16float",
+            usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const srcView = srcCubemap.createView({ dimension: "2d-array" });
+        const dstView = dstTexture.createView({ dimension: "2d-array" });
+        const uniformData = new Uint32Array(4);
+        const uniformFloats = new Float32Array(uniformData.buffer);
+        uniformData[0] = faceSize;
+        uniformFloats[1] = options.roughness;
+        uniformData[2] = sampleCount;
+        uniformData[3] = srcCubemap.width;
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, uniformData);
+        const sampler = this.sampler ??= this.device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+        });
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: srcView },
+                { binding: 1, resource: dstView },
+                { binding: 2, resource: { buffer: this.uniformBuffer } },
+                { binding: 3, resource: sampler },
+            ],
+        });
+        const encoder = this.device.createCommandEncoder();
+        const pass = encoder.beginComputePass();
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(faceSize / 8), Math.ceil(faceSize / 8), 6);
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        // GPUSampler has no destroy() — it's lightweight and GC'd. Cached on the
+        // instance via ??= above to avoid per-call allocation.
+        return dstTexture;
+    }
+    generateMipmapChain(srcCubemap, baseFaceSize, levels = 5, sampleCount) {
+        const textures = [];
+        let currentSize = baseFaceSize;
+        for (let level = 0; level < levels; level++) {
+            const roughness = level / (levels - 1);
+            const tex = this.generate(srcCubemap, {
+                faceSize: currentSize,
+                roughness,
+                sampleCount: sampleCount ?? Math.max(64, 512 >> level),
+            });
+            textures.push(tex);
+            currentSize = Math.max(1, Math.floor(currentSize / 2));
+        }
+        return textures;
+    }
+}