@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/render/shader-validator.js

@@ -0,0 +1,172 @@
+// ============================================================================
+// shader-validator.ts — Centralized shader module creation with validation
+// ============================================================================
+//
+// All GPU shader module creation in the engine should go through
+// `createValidatedShaderModule()` (sync, background validation) or
+// `createValidatedShaderModuleAsync()` (async, blocking validation for
+// startup/bake-time). These helpers call `GPUShaderModule.getCompilationInfo()`
+// after creation and surface errors as FATAL+throw and warnings as dedup'd
+// warns, preventing malformed shaders from silently reaching the render
+// pipeline and spamming the console with uncaptured-error messages.
+//
+// `installShaderValidationGuard(device)` monkey-patches `device.createShaderModule`
+// so even direct calls (third-party code, missed call sites) route through
+// validation. Install it once at device creation.
+//
+// Set `DOWNDRAFT_SHADER_VALIDATE=0` to disable validation (emergencies only).
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+// ── Dedup state ──
+// Prevents the same shader error/warning from being logged more than once.
+// Cleared on HMR reload via `clearShaderValidationDedup()`.
+const validatedDedup = new Set();
+let suppressedCount = 0;
+const SUPPRESS_THRESHOLD = 50;
+/** Clear the dedup set. Call on HMR reload so recompiled shaders get fresh validation. */
+export function clearShaderValidationDedup() {
+    validatedDedup.clear();
+    suppressedCount = 0;
+}
+function dedupKey(label, message, lineNum) {
+    return `${label}:${lineNum}:${message.slice(0, 200)}`;
+}
+// ── Validation enabled flag ──
+const validationEnabled = (() => {
+    const env = globalThis.process?.env ?? {};
+    return env.DOWNDRAFT_SHADER_VALIDATE !== "0";
+})();
+/**
+ * Process compilation info messages from a shader module.
+ * Logs errors at FATAL level (and collects them for throwing), warnings at
+ * warn level (deduplicated). Returns the array of error messages.
+ */
+function processCompilationInfo(module, label) {
+    // If the module doesn't support getCompilationInfo (e.g. mock devices in
+    // tests), skip validation gracefully.
+    if (!validationEnabled || typeof module.getCompilationInfo !== "function") {
+        return [];
+    }
+    let errors = [];
+    // getCompilationInfo is async, but we want to process synchronously in the
+    // background. We use .then() and collect errors into the closure.
+    module
+        .getCompilationInfo()
+        .then((info) => {
+        for (let _i = 0, _it = info.messages, _n = _it.length; _i < _n; _i++) {
+            const msg = _it[_i];
+            const key = dedupKey(label, msg.message, msg.lineNum);
+            if (validatedDedup.has(key)) {
+                suppressedCount++;
+                continue;
+            }
+            validatedDedup.add(key);
+            const location = msg.lineNum > 0 ? ` (line ${msg.lineNum}:${msg.linePos})` : "";
+            const fullMsg = `[${label}] ${msg.message}${location}`;
+            if (msg.type === "error") {
+                log.fatal("shader", fullMsg);
+                errors.push(fullMsg);
+            }
+            else if (msg.type === "warning") {
+                log.warn("shader", fullMsg);
+            }
+            else {
+                log.debug("shader", fullMsg);
+            }
+        }
+        if (suppressedCount > 0 && suppressedCount % SUPPRESS_THRESHOLD === 0) {
+            log.warn("shader", `[${label}] ${suppressedCount} duplicate shader messages suppressed`);
+        }
+    })
+        .catch(() => {
+        // getCompilationInfo can reject on some implementations; ignore.
+    });
+    return errors;
+}
+/**
+ * Create a validated shader module (sync, background validation).
+ *
+ * Returns the GPUShaderModule immediately. Validation runs asynchronously via
+ * `getCompilationInfo()`. If errors are found, they are logged at FATAL level.
+ * For startup-blocking validation, use `createValidatedShaderModuleAsync()`.
+ *
+ * This is the primary entry point for all shader creation in the engine.
+ */
+export function createValidatedShaderModule(device, descriptor) {
+    const label = descriptor.label ?? "unnamed";
+    const module = device.createShaderModule(descriptor);
+    processCompilationInfo(module, label);
+    return module;
+}
+/**
+ * Create a validated shader module (async, blocking validation).
+ *
+ * Awaits `getCompilationInfo()` before returning. If compilation errors are
+ * found, logs them at FATAL level and throws. Use this at startup/bake-time
+ * where you want to block before the render loop begins.
+ */
+export async function createValidatedShaderModuleAsync(device, descriptor) {
+    const label = descriptor.label ?? "unnamed";
+    const module = device.createShaderModule(descriptor);
+    if (!validationEnabled || typeof module.getCompilationInfo !== "function") {
+        return module;
+    }
+    try {
+        const info = await module.getCompilationInfo();
+        const errors = [];
+        for (let _i = 0, _it = info.messages, _n = _it.length; _i < _n; _i++) {
+            const msg = _it[_i];
+            const key = dedupKey(label, msg.message, msg.lineNum);
+            if (validatedDedup.has(key))
+                continue;
+            validatedDedup.add(key);
+            const location = msg.lineNum > 0 ? ` (line ${msg.lineNum}:${msg.linePos})` : "";
+            const fullMsg = `[${label}] ${msg.message}${location}`;
+            if (msg.type === "error") {
+                log.fatal("shader", fullMsg);
+                errors.push(fullMsg);
+            }
+            else if (msg.type === "warning") {
+                log.warn("shader", fullMsg);
+            }
+            else {
+                log.debug("shader", fullMsg);
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Shader compilation failed for "${label}":\n${errors.join("\n")}`);
+        }
+    }
+    catch (e) {
+        // If getCompilationInfo itself throws, rethrow only if it's our error.
+        if (e instanceof Error && e.message.includes("Shader compilation failed")) {
+            throw e;
+        }
+        // Otherwise, getCompilationInfo rejected — skip validation.
+    }
+    return module;
+}
+// ── Enforcement: monkey-patch guard ──
+/**
+ * Install a guard on `device.createShaderModule` that routes all calls through
+ * `createValidatedShaderModule()`. This ensures even direct calls (from
+ * third-party code or call sites that weren't migrated) go through validation.
+ *
+ * Install once at device creation. The guard checks for `getCompilationInfo`
+ * existence before using it; mock devices in tests are unaffected.
+ */
+export function installShaderValidationGuard(device) {
+    if (!validationEnabled)
+        return;
+    // Avoid double-install.
+    if (device.__shaderValidationGuardInstalled)
+        return;
+    device.__shaderValidationGuardInstalled = true;
+    const originalCreateShaderModule = device.createShaderModule.bind(device);
+    device.createShaderModule = (descriptor) => {
+        const module = originalCreateShaderModule(descriptor);
+        const label = descriptor.label ?? "unnamed";
+        processCompilationInfo(module, label);
+        return module;
+    };
+}

package/dist/core/src/render/shaders/debug/debug-line.wgsl

@@ -0,0 +1,27 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+};
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct LineVertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) color: vec4<f32>,
+};
+
+struct LineVertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) color: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: LineVertexInput) -> LineVertexOutput {
+  var output: LineVertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.color = input.color;
+  return output;
+}
+
+@fragment
+fn fs_main(input: LineVertexOutput) -> @location(0) vec4<f32> {
+  return input.color;
+}

package/dist/core/src/render/shaders/debug/debug-point.wgsl

@@ -0,0 +1,30 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+};
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct PointVertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) color: vec4<f32>,
+  @location(2) size: f32,
+};
+
+struct PointVertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) color: vec4<f32>,
+  @location(1) pointSize: f32,
+};
+
+@vertex
+fn vs_main(input: PointVertexInput) -> PointVertexOutput {
+  var output: PointVertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.color = input.color;
+  output.pointSize = input.size;
+  return output;
+}
+
+@fragment
+fn fs_main(input: PointVertexOutput) -> @location(0) vec4<f32> {
+  return input.color;
+}

package/dist/core/src/render/shaders/debug/debug-text.wgsl

@@ -0,0 +1,42 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  screenSize: vec2<f32>,
+  _pad: vec2<f32>,
+};
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var glyphAtlas: texture_2d<f32>;
+@group(0) @binding(2) var glyphSampler: sampler;
+
+struct TextVertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) uv: vec2<f32>,
+  @location(2) color: vec4<f32>,
+};
+
+struct TextVertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+  @location(1) color: vec4<f32>,
+};
+
+@vertex
+fn vs_main(input: TextVertexInput) -> TextVertexOutput {
+  var output: TextVertexOutput;
+  if (input.position.z == -1.0) {
+    // Screen space: position is in pixels, convert to NDC
+    let ndcX = (input.position.x / camera.screenSize.x) * 2.0 - 1.0;
+    let ndcY = 1.0 - (input.position.y / camera.screenSize.y) * 2.0;
+    output.clipPosition = vec4<f32>(ndcX, ndcY, 0.0, 1.0);
+  } else {
+    output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  }
+  output.uv = input.uv;
+  output.color = input.color;
+  return output;
+}
+
+@fragment
+fn fs_main(input: TextVertexOutput) -> @location(0) vec4<f32> {
+  let sampled = textureSample(glyphAtlas, glyphSampler, input.uv);
+  return vec4<f32>(input.color.rgb, sampled.r * input.color.a);
+}

package/dist/core/src/render/shaders/debug-viz/aabb.wgsl

@@ -0,0 +1,20 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> @builtin(position) vec4<f32> {
+  return camera.viewProj * vec4<f32>(input.position, 1.0);
+}
+
+@fragment
+fn fs_main() -> @location(0) vec4<f32> {
+  return vec4<f32>(0.0, 1.0, 0.0, 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/depth.wgsl

@@ -0,0 +1,29 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) depth: f32,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.depth = output.clipPosition.z / output.clipPosition.w;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let d = input.depth;
+  return vec4<f32>(d, d, d, 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/lod.wgsl

@@ -0,0 +1,38 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+struct LodUniforms {
+  level: f32,
+  _pad: vec3<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var<uniform> lod: LodUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) vLevel: f32,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.vLevel = lod.level;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let l = input.vLevel;
+  if (l < 0.5) { return vec4<f32>(0.0, 1.0, 0.0, 1.0); }
+  if (l < 1.5) { return vec4<f32>(1.0, 1.0, 0.0, 1.0); }
+  if (l < 2.5) { return vec4<f32>(1.0, 0.5, 0.0, 1.0); }
+  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/normals.wgsl

@@ -0,0 +1,30 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) normal: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.normal = input.normal;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let n = normalize(input.normal);
+  return vec4<f32>(abs(n), 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/overdraw.wgsl

@@ -0,0 +1,21 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> @builtin(position) vec4<f32> {
+  return camera.viewProj * vec4<f32>(input.position, 1.0);
+}
+
+@fragment
+fn fs_main() -> @location(0) vec4<f32> {
+  // Each overdraw adds more red — accumulates via additive blend
+  return vec4<f32>(0.1, 0.0, 0.0, 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/tangents.wgsl

@@ -0,0 +1,29 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) tangent: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) vColor: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.vColor = abs(normalize(input.tangent));
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  return vec4<f32>(input.vColor, 1.0);
+}

package/dist/core/src/render/shaders/debug-viz/wireframe.wgsl

@@ -0,0 +1,33 @@
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  _pad0: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) normal: vec3<f32>,
+  @location(1) depth: f32,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  output.clipPosition = camera.viewProj * vec4<f32>(input.position, 1.0);
+  output.normal = input.normal;
+  output.depth = output.clipPosition.z / output.clipPosition.w;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let n = normalize(input.normal);
+  let color = (n * 0.5 + 0.5);
+  return vec4<f32>(color, 1.0);
+}

package/dist/core/src/render/shaders/shadow-chunks.js

@@ -0,0 +1,133 @@
+export const CSM_SHADER_CHUNK = /* wgsl */ `
+const MAX_CASCADES = 4u;
+
+struct CSMUniforms {
+  cascades: array<mat4x4<f32>, MAX_CASCADES>,
+  cascadeSplits: vec4<f32>,
+  lightDir: vec4<f32>,
+  cascadeCount: vec4<f32>,
+};
+
+@group(0) @binding(11) var<uniform> csmUniforms: CSMUniforms;
+@group(0) @binding(12) var csmShadowMap: texture_depth_2d_array;
+@group(0) @binding(13) var csmSampler: sampler_comparison;
+
+fn selectCascade(viewDepth: f32) -> u32 {
+  let count = u32(csmUniforms.cascadeCount.x);
+  for (var i = 0u; i < MAX_CASCADES; i++) {
+    if (i >= count) { break; }
+    if (viewDepth <= csmUniforms.cascadeSplits[i]) {
+      return i;
+    }
+  }
+  return count - 1u;
+}
+
+fn csmShadowFactor(worldPos: vec3<f32>, viewDepth: f32, N: vec3<f32>) -> f32 {
+  let cascadeIdx = selectCascade(viewDepth);
+  let lightViewProj = csmUniforms.cascades[cascadeIdx];
+  let shadowCoord = lightViewProj * vec4<f32>(worldPos, 1.0);
+  let shadowUV = shadowCoord.xy / shadowCoord.w * 0.5 + 0.5;
+  let shadowDepth = shadowCoord.z / shadowCoord.w;
+
+  if (shadowUV.x < 0.0 || shadowUV.x > 1.0 || shadowUV.y < 0.0 || shadowUV.y > 1.0) {
+    return 1.0;
+  }
+
+  let bias = csmUniforms.cascadeCount.y;
+  let normalBias = csmUniforms.cascadeCount.z;
+  let lightDir = normalize(csmUniforms.lightDir.xyz);
+  let slopeScale = clamp(1.0 - dot(N, lightDir), 0.0, 1.0);
+  let adjustedBias = bias + normalBias * slopeScale;
+
+  // 3x3 PCF
+  var shadow = 0.0;
+  let texelSize = 1.0 / f32(textureDimensions(csmShadowMap, 0).x);
+  for (var y = -1; y <= 1; y++) {
+    for (var x = -1; x <= 1; x++) {
+      let offset = vec2<f32>(f32(x), f32(y)) * texelSize;
+      shadow += textureSampleCompareLevel(
+        csmShadowMap, csmSampler,
+        shadowUV + offset, cascadeIdx,
+        shadowDepth - adjustedBias,
+      );
+    }
+  }
+  shadow = shadow / 9.0;
+
+  // Cascade blend
+  let blendDist = csmUniforms.cascadeCount.w;
+  let cascadeFar = csmUniforms.cascadeSplits[cascadeIdx];
+  let distToEdge = cascadeFar - viewDepth;
+  if (distToEdge < blendDist && cascadeIdx < count - 1u) {
+    let blendFactor = distToEdge / blendDist;
+    let nextIdx = cascadeIdx + 1u;
+    let nextVP = csmUniforms.cascades[nextIdx];
+    let nextCoord = nextVP * vec4<f32>(worldPos, 1.0);
+    let nextUV = nextCoord.xy / nextCoord.w * 0.5 + 0.5;
+    let nextDepth = nextCoord.z / nextCoord.w;
+    if (nextUV.x >= 0.0 && nextUV.x <= 1.0 && nextUV.y >= 0.0 && nextUV.y <= 1.0) {
+      var nextShadow = 0.0;
+      for (var y2 = -1; y2 <= 1; y2++) {
+        for (var x2 = -1; x2 <= 1; x2++) {
+          let offset2 = vec2<f32>(f32(x2), f32(y2)) * texelSize;
+          nextShadow += textureSampleCompareLevel(
+            csmShadowMap, csmSampler,
+            nextUV + offset2, nextIdx,
+            nextDepth - adjustedBias,
+          );
+        }
+      }
+      nextShadow = nextShadow / 9.0;
+      shadow = mix(nextShadow, shadow, blendFactor);
+    }
+  }
+
+  return shadow;
+}
+`;
+export const POINT_SHADOW_SHADER_CHUNK = /* wgsl */ `
+const MAX_POINT_LIGHT_SHADOWS = 4u;
+
+@group(0) @binding(14) var pointShadowMaps: array<texture_depth_cube, MAX_POINT_LIGHT_SHADOWS>;
+@group(0) @binding(15) var pointShadowSampler: sampler_comparison;
+
+fn pointLightShadow(worldPos: vec3<f32>, lightPos: vec3<f32>, lightIndex: u32, farPlane: f32) -> f32 {
+  let toLight = worldPos - lightPos;
+  let dist = length(toLight);
+  let dir = toLight / max(dist, 0.001);
+  let normalizedDepth = dist / farPlane;
+  let bias = 0.01;
+  return textureSampleCompareLevel(
+    pointShadowMaps[lightIndex], pointShadowSampler,
+    dir, normalizedDepth - bias,
+  );
+}
+`;
+export const SPOT_SHADOW_SHADER_CHUNK = /* wgsl */ `
+const MAX_SPOT_LIGHT_SHADOWS = 4u;
+
+struct SpotShadowData {
+  viewProjs: array<mat4x4<f32>, MAX_SPOT_LIGHT_SHADOWS>,
+};
+
+@group(0) @binding(16) var<uniform> spotShadowData: SpotShadowData;
+@group(0) @binding(17) var spotShadowMaps: texture_depth_2d_array;
+@group(0) @binding(18) var spotShadowSampler: sampler_comparison;
+
+fn spotLightShadow(worldPos: vec3<f32>, lightIndex: u32) -> f32 {
+  let vp = spotShadowData.viewProjs[lightIndex];
+  let shadowCoord = vp * vec4<f32>(worldPos, 1.0);
+  let shadowUV = shadowCoord.xy / shadowCoord.w * 0.5 + 0.5;
+  let shadowDepth = shadowCoord.z / shadowCoord.w;
+  if (shadowUV.x < 0.0 || shadowUV.x > 1.0 || shadowUV.y < 0.0 || shadowUV.y > 1.0) {
+    return 1.0;
+  }
+  let bias = 0.001;
+  return textureSampleCompareLevel(
+    spotShadowMaps, spotShadowSampler,
+    shadowUV, lightIndex,
+    shadowDepth - bias,
+  );
+}
+`;