@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/render/camera.js

@@ -0,0 +1,332 @@
+// ============================================================================
+// Camera System — view matrix calculation for 1st/3rd person and freecam
+// Generic camera with configurable eye height and player height parameters.
+// ============================================================================
+import { mat4 } from "wgpu-matrix";
+export var CameraMode;
+(function (CameraMode) {
+    CameraMode[CameraMode["FirstPerson"] = 0] = "FirstPerson";
+    CameraMode[CameraMode["ThirdPerson"] = 1] = "ThirdPerson";
+    CameraMode[CameraMode["FreeCam"] = 2] = "FreeCam";
+})(CameraMode || (CameraMode = {}));
+const DEFAULT_CONFIG = {
+    eyeHeight: 1.62,
+    playerHeight: 1.8,
+    thirdPersonDistance: 12,
+    firstPersonSensitivity: 1.0,
+    thirdPersonSensitivity: 1.0,
+    freecamSensitivity: 1.0,
+};
+const FREECAM_MOUSE_SENSITIVITY = 0.001;
+const FIRST_PERSON_MOUSE_SENSITIVITY = 0.001;
+const THIRD_PERSON_MOUSE_SENSITIVITY = 0.005;
+const KEY_W = 87, KEY_A = 65, KEY_S = 83, KEY_D = 68;
+const KEY_SPACE = 32, KEY_SHIFT = 16;
+// ── Math utilities ──
+const tmpProj = new Float32Array(16);
+const tmpView = new Float32Array(16);
+const tmpResult = new Float32Array(16);
+export function calculateViewProj(camera) {
+    return calculateViewProjInto(camera, tmpResult);
+}
+export function calculateViewProjInto(camera, target) {
+    if (camera.projectionMatrix && camera.viewMatrix) {
+        return mat4.multiply(camera.projectionMatrix, camera.viewMatrix, target);
+    }
+    if (camera.projectionMatrix) {
+        mat4.lookAt(camera.position, camera.target, camera.up, tmpView);
+        return mat4.multiply(camera.projectionMatrix, tmpView, target);
+    }
+    if (camera.viewMatrix) {
+        const fov = (camera.fov * Math.PI) / 180;
+        mat4.perspective(fov, camera.aspect, camera.near, camera.far, tmpProj);
+        return mat4.multiply(tmpProj, camera.viewMatrix, target);
+    }
+    const fov = (camera.fov * Math.PI) / 180;
+    mat4.perspective(fov, camera.aspect, camera.near, camera.far, tmpProj);
+    mat4.lookAt(camera.position, camera.target, camera.up, tmpView);
+    return mat4.multiply(tmpProj, tmpView, target);
+}
+export function transformVec4(m, v) {
+    return [
+        m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12] * v[3],
+        m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13] * v[3],
+        m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14] * v[3],
+        m[3] * v[0] + m[7] * v[1] + m[11] * v[2] + m[15] * v[3],
+    ];
+}
+export function normalize3(v) {
+    const len = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) || 1;
+    return [v[0] / len, v[1] / len, v[2] / len];
+}
+export function dot3(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+// ── CameraSystem class ──
+export class CameraSystem {
+    config;
+    thirdPersonDistance;
+    thirdPersonHeight;
+    smoothPos = null;
+    smoothTarget = null;
+    lastMode = CameraMode.FirstPerson;
+    prevPlayerPos = null;
+    freecamPos = [0, 10, 0];
+    freecamAngles = { pitch: 0, yaw: 0 };
+    freecamInitialized = false;
+    lookHeading = 0;
+    lookPitch = 0;
+    lookSyncedTick = -1;
+    /**
+     * Set the look direction directly, bypassing mouse deltas, and mark it as
+     * synced (unlike resetLook(), does not trigger reinit from SAB on next tick).
+     * Used by the native/test harness.
+     */
+    setLookState(heading, pitch) {
+        this.lookHeading = heading;
+        this.lookPitch = pitch;
+        this.lookSyncedTick = 0;
+    }
+    getLookSyncedTick() { return this.lookSyncedTick; }
+    firstPersonSensitivity;
+    thirdPersonSensitivity;
+    freecamSensitivity;
+    pooledReturnState = {
+        position: [0, 0, 0],
+        target: [0, 0, 0],
+        up: [0, 1, 0],
+        fov: 60,
+        near: 0.1,
+        far: 4096,
+        aspect: 1,
+    };
+    pooledPos = [0, 0, 0];
+    pooledTarget = [0, 0, 0];
+    pooledDesiredOffset = [0, 0, 0];
+    pooledCurrentOffset = [0, 0, 0];
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.thirdPersonDistance = this.config.thirdPersonDistance;
+        this.thirdPersonHeight = this.config.playerHeight * 0.8;
+        this.firstPersonSensitivity = this.config.firstPersonSensitivity;
+        this.thirdPersonSensitivity = this.config.thirdPersonSensitivity;
+        this.freecamSensitivity = this.config.freecamSensitivity;
+    }
+    calculateCamera(playerPos, heading, pitch, mode, viewportIdx, dt, aspect) {
+        const pos = this.pooledPos;
+        const target = this.pooledTarget;
+        const modeChanged = mode !== this.lastMode;
+        this.lastMode = mode;
+        switch (mode) {
+            case CameraMode.FirstPerson: {
+                const eyeY = playerPos.y + this.config.eyeHeight;
+                pos[0] = playerPos.x;
+                pos[1] = eyeY;
+                pos[2] = playerPos.z;
+                const lookDist = 100;
+                const cp = Math.cos(this.lookPitch);
+                const sp = Math.sin(this.lookPitch);
+                target[0] = playerPos.x + Math.sin(this.lookHeading) * cp * lookDist;
+                target[1] = eyeY + sp * lookDist;
+                target[2] = playerPos.z - Math.cos(this.lookHeading) * cp * lookDist;
+                break;
+            }
+            case CameraMode.ThirdPerson: {
+                const dist = this.thirdPersonDistance;
+                const clampedPitch = Math.max(-0.8, Math.min(0.6, this.lookPitch));
+                const cp = Math.cos(clampedPitch);
+                const sp = Math.sin(clampedPitch);
+                pos[0] = playerPos.x - Math.sin(this.lookHeading) * cp * dist;
+                pos[1] = playerPos.y + this.thirdPersonHeight - sp * dist;
+                pos[2] = playerPos.z + Math.cos(this.lookHeading) * cp * dist;
+                const torsoOffset = this.config.playerHeight * 0.5;
+                target[0] = playerPos.x;
+                target[1] = playerPos.y + torsoOffset;
+                target[2] = playerPos.z;
+                break;
+            }
+            case CameraMode.FreeCam: {
+                pos[0] = this.freecamPos[0];
+                pos[1] = this.freecamPos[1];
+                pos[2] = this.freecamPos[2];
+                const cp = Math.cos(this.freecamAngles.pitch);
+                const sp = Math.sin(this.freecamAngles.pitch);
+                const lookDist = 100;
+                target[0] = this.freecamPos[0] + Math.sin(this.freecamAngles.yaw) * cp * lookDist;
+                target[1] = this.freecamPos[1] + sp * lookDist;
+                target[2] = this.freecamPos[2] - Math.cos(this.freecamAngles.yaw) * cp * lookDist;
+                break;
+            }
+            default: {
+                pos[0] = playerPos.x;
+                pos[1] = playerPos.y + 3;
+                pos[2] = playerPos.z + 8;
+                target[0] = playerPos.x;
+                target[1] = playerPos.y;
+                target[2] = playerPos.z;
+                break;
+            }
+        }
+        if (mode === CameraMode.FirstPerson || mode === CameraMode.FreeCam || modeChanged) {
+            if (!this.smoothPos)
+                this.smoothPos = [0, 0, 0];
+            if (!this.smoothTarget)
+                this.smoothTarget = [0, 0, 0];
+            this.smoothPos[0] = pos[0];
+            this.smoothPos[1] = pos[1];
+            this.smoothPos[2] = pos[2];
+            this.smoothTarget[0] = target[0];
+            this.smoothTarget[1] = target[1];
+            this.smoothTarget[2] = target[2];
+            if (!this.prevPlayerPos)
+                this.prevPlayerPos = [0, 0, 0];
+            this.prevPlayerPos[0] = playerPos.x;
+            this.prevPlayerPos[1] = playerPos.y;
+            this.prevPlayerPos[2] = playerPos.z;
+        }
+        else {
+            if (!this.smoothPos)
+                this.smoothPos = [pos[0], pos[1], pos[2]];
+            if (!this.smoothTarget)
+                this.smoothTarget = [target[0], target[1], target[2]];
+            const lerp = 1 - Math.pow(0.001, dt);
+            if (mode === CameraMode.ThirdPerson) {
+                if (this.prevPlayerPos) {
+                    this.smoothPos[0] += playerPos.x - this.prevPlayerPos[0];
+                    this.smoothPos[1] += playerPos.y - this.prevPlayerPos[1];
+                    this.smoothPos[2] += playerPos.z - this.prevPlayerPos[2];
+                }
+                if (!this.prevPlayerPos)
+                    this.prevPlayerPos = [0, 0, 0];
+                this.prevPlayerPos[0] = playerPos.x;
+                this.prevPlayerPos[1] = playerPos.y;
+                this.prevPlayerPos[2] = playerPos.z;
+                const desiredOffset = this.pooledDesiredOffset;
+                desiredOffset[0] = pos[0] - playerPos.x;
+                desiredOffset[1] = pos[1] - playerPos.y;
+                desiredOffset[2] = pos[2] - playerPos.z;
+                const currentOffset = this.pooledCurrentOffset;
+                currentOffset[0] = this.smoothPos[0] - playerPos.x;
+                currentOffset[1] = this.smoothPos[1] - playerPos.y;
+                currentOffset[2] = this.smoothPos[2] - playerPos.z;
+                currentOffset[0] += (desiredOffset[0] - currentOffset[0]) * lerp;
+                currentOffset[1] += (desiredOffset[1] - currentOffset[1]) * lerp;
+                currentOffset[2] += (desiredOffset[2] - currentOffset[2]) * lerp;
+                this.smoothPos[0] = playerPos.x + currentOffset[0];
+                this.smoothPos[1] = playerPos.y + currentOffset[1];
+                this.smoothPos[2] = playerPos.z + currentOffset[2];
+                this.smoothTarget[0] = target[0];
+                this.smoothTarget[1] = target[1];
+                this.smoothTarget[2] = target[2];
+            }
+            else {
+                this.smoothPos[0] += (pos[0] - this.smoothPos[0]) * lerp;
+                this.smoothPos[1] += (pos[1] - this.smoothPos[1]) * lerp;
+                this.smoothPos[2] += (pos[2] - this.smoothPos[2]) * lerp;
+                this.smoothTarget[0] += (target[0] - this.smoothTarget[0]) * lerp;
+                this.smoothTarget[1] += (target[1] - this.smoothTarget[1]) * lerp;
+                this.smoothTarget[2] += (target[2] - this.smoothTarget[2]) * lerp;
+            }
+        }
+        const ret = this.pooledReturnState;
+        ret.position[0] = this.smoothPos[0];
+        ret.position[1] = this.smoothPos[1];
+        ret.position[2] = this.smoothPos[2];
+        ret.target[0] = this.smoothTarget[0];
+        ret.target[1] = this.smoothTarget[1];
+        ret.target[2] = this.smoothTarget[2];
+        ret.aspect = aspect;
+        return ret;
+    }
+    getThirdPersonDistance() {
+        return this.thirdPersonDistance;
+    }
+    setThirdPersonDistance(d) {
+        this.thirdPersonDistance = Math.max(2, Math.min(20, d));
+    }
+    setThirdPersonHeight(h) {
+        this.thirdPersonHeight = Math.max(1, Math.min(10, h));
+    }
+    updateFreecam(keysDown, mouseDelta, dt, playerPos, playerHeading, playerPitch) {
+        if (!this.freecamInitialized) {
+            this.freecamPos = [playerPos.x, playerPos.y + 5, playerPos.z];
+            this.freecamAngles = { pitch: playerPitch, yaw: playerHeading };
+            this.freecamInitialized = true;
+        }
+        const speed = 20 * dt;
+        const cos = Math.cos(this.freecamAngles.yaw);
+        const sin = Math.sin(this.freecamAngles.yaw);
+        if (keysDown.has(KEY_W)) {
+            this.freecamPos[0] += sin * speed;
+            this.freecamPos[2] -= cos * speed;
+        }
+        if (keysDown.has(KEY_S)) {
+            this.freecamPos[0] -= sin * speed;
+            this.freecamPos[2] += cos * speed;
+        }
+        if (keysDown.has(KEY_A)) {
+            this.freecamPos[0] -= cos * speed;
+            this.freecamPos[2] -= sin * speed;
+        }
+        if (keysDown.has(KEY_D)) {
+            this.freecamPos[0] += cos * speed;
+            this.freecamPos[2] += sin * speed;
+        }
+        if (keysDown.has(KEY_SPACE)) {
+            this.freecamPos[1] += speed;
+        }
+        if (keysDown.has(KEY_SHIFT)) {
+            this.freecamPos[1] -= speed;
+        }
+        const fSens = FREECAM_MOUSE_SENSITIVITY * this.freecamSensitivity;
+        if (mouseDelta.dx !== 0)
+            this.freecamAngles.yaw += mouseDelta.dx * fSens;
+        if (mouseDelta.dy !== 0) {
+            this.freecamAngles.pitch -= mouseDelta.dy * fSens;
+            this.freecamAngles.pitch = Math.max(-1.4, Math.min(1.4, this.freecamAngles.pitch));
+        }
+    }
+    updateLook(mouseDelta, simTick, sabHeading, sabPitch, mode) {
+        if (this.lookSyncedTick < 0) {
+            this.lookHeading = sabHeading;
+            this.lookPitch = sabPitch;
+        }
+        this.lookSyncedTick = simTick;
+        const baseSens = mode === CameraMode.ThirdPerson
+            ? THIRD_PERSON_MOUSE_SENSITIVITY
+            : FIRST_PERSON_MOUSE_SENSITIVITY;
+        const sens = baseSens * (mode === CameraMode.ThirdPerson
+            ? this.thirdPersonSensitivity
+            : this.firstPersonSensitivity);
+        if (mouseDelta.dx !== 0)
+            this.lookHeading += mouseDelta.dx * sens;
+        if (mouseDelta.dy !== 0) {
+            if (mode === CameraMode.ThirdPerson) {
+                this.lookPitch -= mouseDelta.dy * sens;
+                this.lookPitch = Math.max(-0.8, Math.min(0.6, this.lookPitch));
+            }
+            else {
+                this.lookPitch -= mouseDelta.dy * sens;
+                this.lookPitch = Math.max(-1.4, Math.min(1.4, this.lookPitch));
+            }
+        }
+    }
+    resetLook(heading, pitch) {
+        this.lookHeading = heading;
+        this.lookPitch = pitch;
+        this.lookSyncedTick = -1;
+    }
+    getLookHeading() { return this.lookHeading; }
+    getLookPitch() { return this.lookPitch; }
+    resetFreecam(playerPos, heading, pitch) {
+        this.freecamPos = [playerPos.x, playerPos.y + 5, playerPos.z];
+        this.freecamAngles = { pitch, yaw: heading };
+        this.freecamInitialized = true;
+    }
+    clearFreecam() {
+        this.freecamInitialized = false;
+    }
+    setFirstPersonSensitivity(v) { this.firstPersonSensitivity = v; }
+    setThirdPersonSensitivity(v) { this.thirdPersonSensitivity = v; }
+    setFreecamSensitivity(v) { this.freecamSensitivity = v; }
+}

package/dist/core/src/render/canvas-resize-watcher.js

@@ -0,0 +1,36 @@
+export class CanvasResizeWatcher {
+    canvas;
+    handler;
+    observer = null;
+    dpr = 1;
+    onSurfaceResize = () => this.resize();
+    constructor(canvas, handler) {
+        this.canvas = canvas;
+        this.handler = handler;
+        this.dpr = (typeof window !== "undefined" ? window.devicePixelRatio : 0) || 1;
+        // DOM hosts: element box changes fire ResizeObserver. Native surfaces
+        // aren't Elements — they push a "resize" event instead. Both paths feed
+        // the same resize() so either host drives layout updates.
+        if (typeof ResizeObserver !== "undefined") {
+            this.observer = new ResizeObserver(() => this.resize());
+            this.observer.observe(canvas);
+        }
+        canvas.addEventListener("resize", this.onSurfaceResize);
+        this.resize();
+    }
+    resize() {
+        this.handler.onResize(this.canvas.clientWidth, this.canvas.clientHeight, this.dpr);
+    }
+    setDpr(dpr) {
+        this.dpr = dpr;
+        this.resize();
+    }
+    getDpr() {
+        return this.dpr;
+    }
+    destroy() {
+        this.observer?.disconnect();
+        this.observer = null;
+        this.canvas.removeEventListener("resize", this.onSurfaceResize);
+    }
+}

package/dist/core/src/render/compute-kernel.js

@@ -0,0 +1,130 @@
+// ============================================================================
+// runComputeKernel — thin imperative helper for quick one-off GPGPU dispatch.
+// The "gpu.js replacement": throw a WGSL kernel at the GPU with typed inputs,
+// dispatch once, and read back results. No graph, no frame graph, no editor.
+// ============================================================================
+import { createValidatedShaderModule } from "./shader-validator.js";
+/** GPUBufferUsage flags. Defined locally for testability. */
+const BUFFER_USAGE = {
+    UNIFORM: 0x40,
+    STORAGE: 0x80,
+    COPY_DST: 0x8,
+    COPY_SRC: 0x4,
+    MAP_READ: 0x1,
+};
+/** GPUShaderStage.COMPUTE = 0x4. */
+const SHADER_STAGE_COMPUTE = 0x4;
+/** GPUMapMode.READ = 0x1. */
+const MAP_MODE_READ = 0x1;
+/**
+ * Run a WGSL compute kernel once and return a result handle for readback.
+ *
+ * The WGSL must declare `@group(0) @binding(N)` for each input, matching the
+ * `name` → `binding` index in the `inputs` array (0-based). The entry point
+ * must be `@compute @workgroup_size(...)` with the default name "cs_main"
+ * (override via `entryPoint`).
+ *
+ * @example
+ * ```ts
+ * const result = await runComputeKernel(device, `
+ *   @group(0) @binding(0) var<storage, read_write> data: array<f32>;
+ *   @group(0) @binding(1) var<uniform> params: Params;
+ *   @compute @workgroup_size(64)
+ *   fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+ *     data[gid.x] = data[gid.x] * 2.0;
+ *   }
+ * `, [
+ *   { name: "data", data: new Float32Array([1,2,3,4]), type: "storage", access: "read_write" },
+ *   { name: "params", data: paramData, type: "uniform" },
+ * ], [64,1,1], [1,1,1]);
+ * const output = await result.readBuffer("data");
+ * ```
+ */
+export async function runComputeKernel(device, wgsl, inputs, workgroupSize, dispatchCount, entryPoint = "cs_main") {
+    const buffers = new Map();
+    const readbackBuffers = new Map();
+    const bindGroupEntries = [];
+    for (let i = 0; i < inputs.length; i++) {
+        const input = inputs[i];
+        const data = input.data;
+        const byteLength = data.byteLength;
+        const isUniform = input.type === "uniform";
+        const access = input.access ?? (isUniform ? "read" : "read_write");
+        const usage = isUniform
+            ? BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST
+            : BUFFER_USAGE.STORAGE |
+                BUFFER_USAGE.COPY_DST |
+                BUFFER_USAGE.COPY_SRC;
+        const buffer = device.createBuffer({
+            label: `kernel:${input.name}`,
+            size: Math.max(byteLength, 16),
+            usage,
+        });
+        device.queue.writeBuffer(buffer, 0, data);
+        buffers.set(input.name, buffer);
+        bindGroupEntries.push({ binding: i, resource: { buffer } });
+        // Create a readback buffer for storage buffers with read access
+        if (!isUniform && access !== "write") {
+            const readbackBuf = device.createBuffer({
+                label: `kernel:${input.name}:readback`,
+                size: Math.max(byteLength, 16),
+                usage: BUFFER_USAGE.MAP_READ | BUFFER_USAGE.COPY_DST,
+            });
+            readbackBuffers.set(input.name, readbackBuf);
+        }
+    }
+    // Build bind group layout from inputs
+    const layoutEntries = inputs.map((input, i) => {
+        const isUniform = input.type === "uniform";
+        const access = input.access ?? (isUniform ? "read" : "read_write");
+        return {
+            binding: i,
+            visibility: SHADER_STAGE_COMPUTE,
+            buffer: {
+                type: isUniform
+                    ? "uniform"
+                    : access === "read"
+                        ? "read-only-storage"
+                        : "storage",
+            },
+        };
+    });
+    const bindGroupLayout = device.createBindGroupLayout({ entries: layoutEntries });
+    const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] });
+    const shaderModule = createValidatedShaderModule(device, { code: wgsl, label: "ComputeKernel" });
+    const pipeline = device.createComputePipeline({
+        layout: pipelineLayout,
+        compute: { module: shaderModule, entryPoint },
+    });
+    const bindGroup = device.createBindGroup({
+        layout: bindGroupLayout,
+        entries: bindGroupEntries,
+    });
+    // Dispatch
+    const encoder = device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    pass.dispatchWorkgroups(dispatchCount[0], dispatchCount[1], dispatchCount[2]);
+    pass.end();
+    // Copy storage buffers to readback buffers
+    for (const [name, readbackBuf] of readbackBuffers.entries()) {
+        const src = buffers.get(name);
+        if (src) {
+            encoder.copyBufferToBuffer(src, 0, readbackBuf, 0, readbackBuf.size);
+        }
+    }
+    device.queue.submit([encoder.finish()]);
+    // Readback function
+    const readBuffer = async (name) => {
+        const readbackBuf = readbackBuffers.get(name);
+        if (!readbackBuf) {
+            throw new Error(`No readback buffer for "${name}" (it may be write-only or uniform)`);
+        }
+        await readbackBuf.mapAsync(MAP_MODE_READ);
+        const arrayBuffer = readbackBuf.getMappedRange().slice(0);
+        readbackBuf.unmap();
+        return arrayBuffer;
+    };
+    return { buffers, readBuffer };
+}

package/dist/core/src/render/constants.js

@@ -0,0 +1,2 @@
+export const DEPTH_FORMAT = "depth32float";
+export const MSAA_SAMPLE_COUNT = 1;

package/dist/core/src/render/device.js

@@ -0,0 +1,91 @@
+import { createLogger } from "../util/logger.js";
+import { installShaderValidationGuard } from "./shader-validator.js";
+const log = createLogger();
+export class GPUDeviceManager {
+    device = null;
+    adapter = null;
+    adapterInfo = null;
+    deviceLost = false;
+    lostHandlers = [];
+    /**
+     * Build requiredLimits for the bindless binding model. Values are clamped to
+     * the adapter's reported limits so unsupported caps don't fail device request.
+     */
+    buildRequiredLimits(adapter) {
+        const a = adapter.limits;
+        const clamp = (key, want) => {
+            const have = a[key];
+            if (have === undefined)
+                return null;
+            return [key, Math.min(want, have)];
+        };
+        const entries = [];
+        [
+            clamp("maxTextureArrayLayers", 512),
+            clamp("maxStorageBuffersPerShaderStage", 8),
+            clamp("maxStorageBufferBindingSize", 64 * 1024 * 1024),
+            clamp("maxSampledTexturesPerShaderStage", 16),
+        ].forEach((e) => {
+            if (e)
+                entries.push(e);
+        });
+        return Object.fromEntries(entries);
+    }
+    async requestDevice() {
+        if (!navigator.gpu) {
+            log.error("gpu", "WebGPU not available");
+            return null;
+        }
+        this.adapter = await navigator.gpu.requestAdapter({
+            powerPreference: "high-performance",
+        });
+        if (!this.adapter) {
+            log.error("gpu", "No suitable GPU adapter found");
+            return null;
+        }
+        this.adapterInfo = (this.adapter.info ?? {});
+        this.device = await this.adapter.requestDevice({
+            requiredLimits: this.buildRequiredLimits(this.adapter),
+        });
+        if (this.device) {
+            // Install the shader validation guard so all createShaderModule calls
+            // route through getCompilationInfo() validation.
+            installShaderValidationGuard(this.device);
+            this.device.lost.then((info) => {
+                this.deviceLost = true;
+                log.error("gpu", `GPU device lost: ${info?.message ?? "unknown reason"}. Application should attempt recovery or notify the user.`);
+                for (let i = 0; i < this.lostHandlers.length; i++) {
+                    try {
+                        this.lostHandlers[i](info);
+                    }
+                    catch (err) {
+                        log.error("gpu", `Device lost handler threw: ${err}`);
+                    }
+                }
+            });
+        }
+        return this.device;
+    }
+    getDevice() {
+        return this.device;
+    }
+    getAdapter() {
+        return this.adapter;
+    }
+    getAdapterInfo() {
+        return this.adapterInfo;
+    }
+    isDeviceLost() {
+        return this.deviceLost;
+    }
+    async reinit() {
+        log.warn("gpu", "Device lost — reinitializing GPU device. Pass-specific resources (pipelines, bind groups, textures) are NOT recreated and must be rebuilt by the application.");
+        this.deviceLost = false;
+        this.device = null;
+        this.adapter = null;
+        return this.requestDevice();
+    }
+    onDeviceLost(fn) {
+        this.lostHandlers.push(fn);
+    }
+}