@downdraft/engine 0.0.0 → 0.1.1

package/core/src/render/sab-canvas-overlay.ts

@@ -0,0 +1,122 @@
+// ============================================================================
+// SabCanvasOverlay — DOM <canvas> overlay backed by a SharedArrayBuffer bitmap
+//
+// Generalized from overburden's MapCanvas. Provides the generic shell:
+//   - A visible <canvas> fixed-positioned over the game canvas
+//     (pointer-events: none, configurable z-index, hidden while opacity <= 0).
+//   - An offscreen "bitmap" canvas at a fixed data resolution that is repainted
+//     only when a SAB sequence counter changes (via getSeq + redrawBitmap).
+//   - Per-frame window resize tracking and opacity control.
+//
+// The game supplies the compositing + drawing logic via callbacks; the overlay
+// owns all DOM plumbing.
+// ============================================================================
+
+export interface SabCanvasOverlayOptions {
+  /** DOM id for the visible canvas. Default: "sab-canvas-overlay" */
+  id?: string;
+  /** CSS z-index. Default: 55 (above the game surface, below DOM overlays) */
+  zIndex?: number;
+  /** Offscreen bitmap resolution. If omitted, no bitmap canvas is created. */
+  bitmapWidth?: number;
+  bitmapHeight?: number;
+  /** CSS image-rendering for the visible canvas. Default: "pixelated" */
+  imageRendering?: "pixelated" | "auto";
+  /**
+   * Monotonic sequence number for the backing data (e.g. a SAB seq counter).
+   * The bitmap is repainted only when this value changes. Omit to repaint
+   * every visible frame.
+   */
+  getSeq?: () => number;
+  /**
+   * Repaint the offscreen bitmap canvas. Called only when getSeq() reports
+   * a new value (requires bitmapWidth/bitmapHeight).
+   */
+  redrawBitmap?: (ctx: CanvasRenderingContext2D, bitmapW: number, bitmapH: number) => void;
+  /**
+   * Draw the visible canvas each visible frame, after the bitmap has been
+   * refreshed. `bitmap` is the offscreen bitmap canvas (or null when no
+   * bitmap was configured).
+   */
+  draw: (ctx: CanvasRenderingContext2D, bitmap: HTMLCanvasElement | null, w: number, h: number) => void;
+}
+
+export class SabCanvasOverlay {
+  readonly canvas: HTMLCanvasElement;
+  protected ctx: CanvasRenderingContext2D;
+  /** Offscreen bitmap canvas (fixed data resolution). Null when unconfigured. */
+  readonly bitmapCanvas: HTMLCanvasElement | null = null;
+  protected bitmapCtx: CanvasRenderingContext2D | null = null;
+  private opts: SabCanvasOverlayOptions;
+  private lastSeq = -1;
+
+  constructor(opts: SabCanvasOverlayOptions) {
+    this.opts = opts;
+
+    this.canvas = document.createElement("canvas");
+    this.canvas.id = opts.id ?? "sab-canvas-overlay";
+    this.canvas.style.position = "fixed";
+    this.canvas.style.top = "0";
+    this.canvas.style.left = "0";
+    this.canvas.style.width = "100%";
+    this.canvas.style.height = "100%";
+    this.canvas.style.pointerEvents = "none";
+    this.canvas.style.zIndex = String(opts.zIndex ?? 55);
+    this.canvas.style.display = "none"; // hidden until opacity > 0
+    this.canvas.style.imageRendering = opts.imageRendering ?? "pixelated";
+    this.ctx = this.canvas.getContext("2d")!;
+
+    if (opts.bitmapWidth !== undefined && opts.bitmapHeight !== undefined) {
+      this.bitmapCanvas = document.createElement("canvas");
+      this.bitmapCanvas.width = opts.bitmapWidth;
+      this.bitmapCanvas.height = opts.bitmapHeight;
+      this.bitmapCtx = this.bitmapCanvas.getContext("2d")!;
+    }
+  }
+
+  /** Attach the canvas to the DOM (call once during init). */
+  mount(parent: HTMLElement = document.body): void {
+    parent.appendChild(this.canvas);
+  }
+
+  /**
+   * Per-frame update. Call from the render loop.
+   * Hides the canvas while `opacity <= 0`; otherwise resizes the canvas to the
+   * window, repaints the bitmap when the seq counter advanced, and invokes
+   * the draw callback.
+   */
+  update(opacity: number): void {
+    if (opacity <= 0) {
+      this.canvas.style.display = "none";
+      return;
+    }
+    this.canvas.style.display = "block";
+    this.canvas.style.opacity = String(opacity);
+
+    // Resize the visible canvas to match the window if needed.
+    const w = window.innerWidth;
+    const h = window.innerHeight;
+    if (this.canvas.width !== w || this.canvas.height !== h) {
+      this.canvas.width = w;
+      this.canvas.height = h;
+    }
+
+    // Repaint the bitmap if the backing data has a new seq value.
+    const seq = this.opts.getSeq?.();
+    if (this.bitmapCtx && (seq === undefined || seq !== this.lastSeq)) {
+      if (seq !== undefined) this.lastSeq = seq;
+      this.opts.redrawBitmap?.(this.bitmapCtx, this.bitmapCanvas!.width, this.bitmapCanvas!.height);
+    }
+
+    this.opts.draw(this.ctx, this.bitmapCanvas, w, h);
+  }
+
+  /** Mark the bitmap stale so it repaints on the next visible frame. */
+  invalidate(): void {
+    this.lastSeq = -1;
+  }
+
+  dispose(): void {
+    this.canvas.remove();
+  }
+}

package/core/src/render/shader-validator.ts

@@ -0,0 +1,200 @@
+// ============================================================================
+// 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";
+
+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<string>();
+let suppressedCount = 0;
+const SUPPRESS_THRESHOLD = 50;
+
+/** Clear the dedup set. Call on HMR reload so recompiled shaders get fresh validation. */
+export function clearShaderValidationDedup(): void {
+  validatedDedup.clear();
+  suppressedCount = 0;
+}
+
+function dedupKey(label: string, message: string, lineNum: number): string {
+  return `${label}:${lineNum}:${message.slice(0, 200)}`;
+}
+
+// ── Validation enabled flag ──
+const validationEnabled = (() => {
+  const env = (globalThis as any).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: GPUShaderModule,
+  label: string,
+): string[] {
+  // 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: string[] = [];
+  // 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: GPUCompilationInfo) => {
+      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: GPUDevice,
+  descriptor: GPUShaderModuleDescriptor,
+): GPUShaderModule {
+  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: GPUDevice,
+  descriptor: GPUShaderModuleDescriptor,
+): Promise<GPUShaderModule> {
+  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: string[] = [];
+    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: GPUDevice): void {
+  if (!validationEnabled) return;
+
+  // Avoid double-install.
+  if ((device as any).__shaderValidationGuardInstalled) return;
+  (device as any).__shaderValidationGuardInstalled = true;
+
+  const originalCreateShaderModule = device.createShaderModule.bind(device);
+
+  (device as any).createShaderModule = (
+    descriptor: GPUShaderModuleDescriptor,
+  ): GPUShaderModule => {
+    const module = originalCreateShaderModule(descriptor);
+    const label = descriptor.label ?? "unnamed";
+    processCompilationInfo(module, label);
+    return module;
+  };
+}

package/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/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/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/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/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/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/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/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/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/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);
+}