@downdraft/engine 0.1.1 → 0.1.2-alpha.5

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

@@ -0,0 +1,123 @@
+import { mat4 } from "wgpu-matrix";
+import { createValidatedShaderModule } from "./shader-validator.js";
+const SKYBOX_SHADER = /* wgsl */ `
+struct CameraUniforms {
+  viewProj: mat4x4<f32>,
+  invViewProj: mat4x4<f32>,
+  position: vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> camera: CameraUniforms;
+@group(0) @binding(1) var envMap: texture_cube<f32>;
+@group(0) @binding(2) var envSampler: sampler;
+
+struct VertexOutput {
+  @builtin(position) clipPosition: vec4<f32>,
+  @location(0) direction: vec3<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vid: u32) -> VertexOutput {
+  // Full-screen triangle
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>( 3.0, -1.0),
+    vec2<f32>(-1.0,  3.0),
+  );
+
+  let pos = positions[vid];
+  var output: VertexOutput;
+  output.clipPosition = vec4<f32>(pos, 1.0, 1.0);
+  // Reconstruct direction from clip position using inverse view-proj
+  let farPoint = camera.invViewProj * vec4<f32>(pos, 1.0, 1.0);
+  let nearPoint = camera.invViewProj * vec4<f32>(pos, -1.0, 1.0);
+  let dir = normalize(farPoint.xyz / farPoint.w - nearPoint.xyz / nearPoint.w);
+  output.direction = dir;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let color = textureSample(envMap, envSampler, normalize(input.direction));
+  return vec4<f32>(color.rgb, 1.0);
+}
+`;
+export class SkyboxRenderer {
+    device;
+    pipeline = null;
+    bindGroupLayout = null;
+    cameraBuffer = null;
+    sampler;
+    format;
+    depthFormat;
+    constructor(device, options) {
+        this.device = device;
+        this.format = options?.format ?? "bgra8unorm";
+        this.depthFormat = options?.depthFormat ?? "depth32float";
+        this.sampler = device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+            mipmapFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+    }
+    ensurePipeline() {
+        if (this.pipeline)
+            return;
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "cube" } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+            ],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: SKYBOX_SHADER, label: "SkyboxPass" });
+        this.pipeline = this.device.createRenderPipeline({
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] }),
+            vertex: { module: shaderModule, entryPoint: "vs_main" },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_main",
+                targets: [{ format: this.format }],
+            },
+            primitive: { topology: "triangle-list" },
+            depthStencil: {
+                format: this.depthFormat,
+                depthWriteEnabled: false,
+                depthCompare: "less-equal",
+            },
+        });
+        this.cameraBuffer = this.device.createBuffer({
+            size: 144, // mat4x4 (64) + mat4x4 (64) + vec4 (16)
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    render(passEncoder, cubemap, viewProj, cameraPos) {
+        this.ensurePipeline();
+        // Update camera buffer
+        const camData = new Float32Array(36);
+        camData.set(viewProj, 0);
+        camData.set(mat4.invert(viewProj), 16);
+        camData[32] = cameraPos[0];
+        camData[33] = cameraPos[1];
+        camData[34] = cameraPos[2];
+        camData[35] = 0;
+        this.device.queue.writeBuffer(this.cameraBuffer, 0, camData);
+        const cubemapView = cubemap.createView({ dimension: "cube" });
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraBuffer } },
+                { binding: 1, resource: cubemapView },
+                { binding: 2, resource: this.sampler },
+            ],
+        });
+        passEncoder.setPipeline(this.pipeline);
+        passEncoder.setBindGroup(0, bindGroup);
+        passEncoder.draw(3, 1, 0, 0);
+    }
+    destroy() {
+        this.cameraBuffer?.destroy();
+    }
+}

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

@@ -0,0 +1,60 @@
+// ============================================================================
+// Split-Screen Layout — viewport computation for 1-4 players
+// ============================================================================
+export function computeViewports(layout, screenW, screenH) {
+    switch (layout) {
+        case "1p":
+            return [{ index: 0, x: 0, y: 0, width: screenW, height: screenH }];
+        case "2p-horizontal":
+            return [
+                { index: 0, x: 0, y: 0, width: screenW / 2, height: screenH },
+                { index: 1, x: screenW / 2, y: 0, width: screenW / 2, height: screenH },
+            ];
+        case "2p-vertical":
+            return [
+                { index: 0, x: 0, y: 0, width: screenW, height: screenH / 2 },
+                { index: 1, x: 0, y: screenH / 2, width: screenW, height: screenH / 2 },
+            ];
+        case "3p-top-wide":
+            return [
+                { index: 0, x: 0, y: 0, width: screenW, height: screenH / 2 },
+                { index: 1, x: 0, y: screenH / 2, width: screenW / 2, height: screenH / 2 },
+                { index: 2, x: screenW / 2, y: screenH / 2, width: screenW / 2, height: screenH / 2 },
+            ];
+        case "3p-bottom-wide":
+            return [
+                { index: 0, x: 0, y: 0, width: screenW / 2, height: screenH / 2 },
+                { index: 1, x: screenW / 2, y: 0, width: screenW / 2, height: screenH / 2 },
+                { index: 2, x: 0, y: screenH / 2, width: screenW, height: screenH / 2 },
+            ];
+        case "4p-corners":
+            return [
+                { index: 0, x: 0, y: 0, width: screenW / 2, height: screenH / 2 },
+                { index: 1, x: screenW / 2, y: 0, width: screenW / 2, height: screenH / 2 },
+                { index: 2, x: 0, y: screenH / 2, width: screenW / 2, height: screenH / 2 },
+                { index: 3, x: screenW / 2, y: screenH / 2, width: screenW / 2, height: screenH / 2 },
+            ];
+        default:
+            return [{ index: 0, x: 0, y: 0, width: screenW, height: screenH }];
+    }
+}
+export function getLayoutForPlayerCount(count) {
+    switch (count) {
+        case 1: return "1p";
+        case 2: return "2p-horizontal";
+        case 3: return "3p-top-wide";
+        case 4: return "4p-corners";
+        default: return "1p";
+    }
+}
+export function getPlayerCountForLayout(layout) {
+    switch (layout) {
+        case "1p": return 1;
+        case "2p-horizontal":
+        case "2p-vertical": return 2;
+        case "3p-top-wide":
+        case "3p-bottom-wide": return 3;
+        case "4p-corners": return 4;
+        default: return 1;
+    }
+}

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

@@ -0,0 +1,63 @@
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export class SurfaceManager {
+    device;
+    context = null;
+    config = null;
+    canvas = null;
+    constructor(device) {
+        this.device = device;
+    }
+    configure(canvas, config = {}) {
+        this.canvas = canvas;
+        this.context = canvas.getContext("webgpu");
+        if (!this.context) {
+            log.error("gpu", "Failed to get WebGPU context from canvas");
+            return;
+        }
+        const format = config.format ?? (navigator.gpu ? navigator.gpu.getPreferredCanvasFormat() : "bgra8unorm");
+        this.config = {
+            format,
+            width: config.width ?? canvas.width,
+            height: config.height ?? canvas.height,
+            usage: config.usage ?? GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+            alphaMode: config.alphaMode ?? "opaque",
+            viewFormats: config.viewFormats ?? [],
+        };
+        this.context.configure({
+            device: this.device,
+            format: this.config.format,
+            usage: this.config.usage,
+            alphaMode: this.config.alphaMode,
+            viewFormats: this.config.viewFormats,
+        });
+    }
+    getCurrentTexture() {
+        if (!this.context)
+            return null;
+        return this.context.getCurrentTexture();
+    }
+    reconfigure(width, height) {
+        if (!this.context || !this.config || !this.canvas)
+            return;
+        this.config.width = width;
+        this.config.height = height;
+        if (this.canvas.width !== width)
+            this.canvas.width = width;
+        if (this.canvas.height !== height)
+            this.canvas.height = height;
+        this.context.configure({
+            device: this.device,
+            format: this.config.format,
+            usage: this.config.usage,
+            alphaMode: this.config.alphaMode,
+            viewFormats: this.config.viewFormats,
+        });
+    }
+    getFormat() {
+        return this.config?.format ?? null;
+    }
+    getConfig() {
+        return this.config;
+    }
+}

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

@@ -0,0 +1,171 @@
+export var ToneMappingOperator;
+(function (ToneMappingOperator) {
+    ToneMappingOperator["None"] = "none";
+    ToneMappingOperator["ACES"] = "aces";
+    ToneMappingOperator["ACESFilmic"] = "aces-filmic";
+    ToneMappingOperator["Reinhard"] = "reinhard";
+    ToneMappingOperator["Reinhard2"] = "reinhard2";
+    ToneMappingOperator["Uncharted2"] = "uncharted2";
+    ToneMappingOperator["Filmic"] = "filmic";
+    ToneMappingOperator["AgX"] = "agx";
+    ToneMappingOperator["Uchimura"] = "uchimura";
+})(ToneMappingOperator || (ToneMappingOperator = {}));
+export const DEFAULT_TONE_MAPPING_SETTINGS = {
+    operator: ToneMappingOperator.ACES,
+    exposure: 1.0,
+    gamma: 2.2,
+    whitePoint: 11.2,
+};
+export const TONE_MAPPING_SHADER_CHUNK = /* wgsl */ `
+enum ToneMappingOp {
+  None = 0,
+  ACES = 1,
+  ACESFilmic = 2,
+  Reinhard = 3,
+  Reinhard2 = 4,
+  Uncharted2 = 5,
+  Filmic = 6,
+  AgX = 7,
+  Uchimura = 8,
+};
+
+struct ToneMappingUniforms {
+  operator: u32,
+  exposure: f32,
+  gamma: f32,
+  whitePoint: f32,
+};
+
+fn tonemapNone(color: vec3<f32>) -> vec3<f32> {
+  return clamp(color, vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn tonemapACES(color: vec3<f32>) -> vec3<f32> {
+  let a = 2.51; let b = 0.03; let c = 2.43; let d = 0.59; let e = 0.14;
+  return clamp((color * (a * color + b)) / (color * (c * color + d) + e), vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn tonemapACESFilmic(color: vec3<f32>) -> vec3<f32> {
+  let a = 0.15; let b = 0.50; let c = 0.10; let d = 0.20; let e = 0.02; let f = 0.30;
+  return (color * (color * a + b * c + d * e)) / (color * (color * a + b) + d * f) - e / f;
+}
+
+fn tonemapReinhard(color: vec3<f32>) -> vec3<f32> {
+  return color / (color + 1.0);
+}
+
+fn tonemapReinhard2(color: vec3<f32>, whitePoint: f32) -> vec3<f32> {
+  let lum = dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
+  let tonemappedLum = lum * (1.0 + lum / (whitePoint * whitePoint)) / (1.0 + lum);
+  return color * (tonemappedLum / max(lum, 0.001));
+}
+
+fn tonemapUncharted2(color: vec3<f32>, whitePoint: f32) -> vec3<f32> {
+  let A = 0.15; let B = 0.50; let C = 0.10; let D = 0.20; let E = 0.02; let F = 0.30;
+  fn curve(x: vec3<f32>) -> vec3<f32> {
+    return ((x * (A * x + C * B) + D * E) / (x * (A * x + B) + D * F)) - E / F;
+  }
+  return curve(color) / curve(vec3<f32>(whitePoint));
+}
+
+fn tonemapFilmic(color: vec3<f32>) -> vec3<f32> {
+  let X = max(color.r - 0.0024, 0.0);
+  let Y = max(color.g - 0.0024, 0.0);
+  let Z = max(color.b - 0.0024, 0.0);
+  let r = (X * (6.2 * X + 0.5)) / (X * (6.2 * X + 1.7) + 0.06);
+  let g = (Y * (6.2 * Y + 0.5)) / (Y * (6.2 * Y + 1.7) + 0.06);
+  let b = (Z * (6.2 * Z + 0.5)) / (Z * (6.2 * Z + 1.7) + 0.06);
+  return vec3<f32>(r, g, b);
+}
+
+fn tonemapAgX(color: vec3<f32>) -> vec3<f32> {
+  let MinEv = -12.47393;
+  let MaxEv = 4.026069;
+  let x = clamp(log2(color.r), MinEv, MaxEv);
+  let y = clamp(log2(color.g), MinEv, MaxEv);
+  let z = clamp(log2(color.b), MinEv, MaxEv);
+  let r = (x - MinEv) / (MaxEv - MinEv);
+  let g = (y - MinEv) / (MaxEv - MinEv);
+  let b = (z - MinEv) / (MaxEv - MinEv);
+  let r2 = pow(r, 2.2);
+  let g2 = pow(g, 2.2);
+  let b2 = pow(b, 2.2);
+  return vec3<f32>(r2, g2, b2);
+}
+
+fn tonemapUchimura(color: vec3<f32>) -> vec3<f32> {
+  let P = 1.0; let a = 5.0; let m = 0.22; let l = 0.4; let c = 1.633; let b = 0.63;
+  fn uchimuraCurve(x: f32) -> f32 {
+    let l0 = ((P - m) * l) / a;
+    let L0 = m - m / a;
+    let L1 = m + (1.0 - m) / a;
+    let L2 = m + (1.0 - m) / a + (c + b) / c;
+    let s = (1.0 + c) * a / (P - m);
+    let S0 = m + l0;
+    let S1 = m + a * l0;
+    let S2 = m + a * (l0 + c / a);
+    let C2 = (a * P) / (P - S1);
+    let C1 = 1.0 + C2 * (S1 - S0);
+    let C0 = 1.0 + C2 * (S0 - 0.0);
+    if (x < S0) { return C0 * x; }
+    if (x < S1) { return C1 * x - C2 * S0; }
+    if (x < S2) { return a * x + b; }
+    return C2 * x - C2 * S2;
+  }
+  return vec3<f32>(
+    uchimuraCurve(color.r),
+    uchimuraCurve(color.g),
+    uchimuraCurve(color.b),
+  );
+}
+
+fn applyToneMapping(color: vec3<f32>, op: u32, exposure: f32, whitePoint: f32) -> vec3<f32> {
+  let exposed = color * exposure;
+  switch (op) {
+    case 0u: { return tonemapNone(exposed); }
+    case 1u: { return tonemapACES(exposed); }
+    case 2u: { return tonemapACESFilmic(exposed); }
+    case 3u: { return tonemapReinhard(exposed); }
+    case 4u: { return tonemapReinhard2(exposed, whitePoint); }
+    case 5u: { return tonemapUncharted2(exposed, whitePoint); }
+    case 6u: { return tonemapFilmic(exposed); }
+    case 7u: { return tonemapAgX(exposed); }
+    case 8u: { return tonemapUchimura(exposed); }
+    default: { return tonemapACES(exposed); }
+  }
+}
+
+fn linearToSRGB(color: vec3<f32>) -> vec3<f32> {
+  return select(
+    color * 12.92,
+    pow(color, vec3<f32>(1.0 / 2.4)) * 1.055 - 0.055,
+    color >= vec3<f32>(0.0031308),
+  );
+}
+
+fn srgbToLinear(color: vec3<f32>) -> vec3<f32> {
+  return select(
+    color / 12.92,
+    pow((color + 0.055) / 1.055, vec3<f32>(2.4)),
+    color >= vec3<f32>(0.04045),
+  );
+}
+
+fn linearToDisplayP3(color: vec3<f32>) -> vec3<f32> {
+  return linearToSRGB(color);
+}
+`;
+export function getToneMappingOperatorIndex(op) {
+    const map = {
+        [ToneMappingOperator.None]: 0,
+        [ToneMappingOperator.ACES]: 1,
+        [ToneMappingOperator.ACESFilmic]: 2,
+        [ToneMappingOperator.Reinhard]: 3,
+        [ToneMappingOperator.Reinhard2]: 4,
+        [ToneMappingOperator.Uncharted2]: 5,
+        [ToneMappingOperator.Filmic]: 6,
+        [ToneMappingOperator.AgX]: 7,
+        [ToneMappingOperator.Uchimura]: 8,
+    };
+    return map[op] ?? 1;
+}

package/dist/core/src/render/tracked-render-pass.js

@@ -0,0 +1,115 @@
+export class TrackedRenderPass {
+    state = {
+        pipeline: null,
+        bindGroups: new Map(),
+        vertexBuffers: new Map(),
+        indexBuffer: null,
+        indexFormat: null,
+    };
+    pass;
+    _drawCalls = 0;
+    _triangles = 0;
+    _pipelineSwitches = 0;
+    _bindGroupChanges = 0;
+    _bufferRebinds = 0;
+    constructor(pass) {
+        this.pass = pass;
+    }
+    /**
+     * Rebind to a fresh GPURenderPassEncoder and clear stats/state so this
+     * wrapper can be reused instead of allocating one per pass per frame.
+     * (FrameGraph keeps a per-slot pool.)
+     */
+    resetForReuse(pass) {
+        this.pass = pass;
+        this.state.pipeline = null;
+        this.state.bindGroups.clear();
+        this.state.vertexBuffers.clear();
+        this.state.indexBuffer = null;
+        this.state.indexFormat = null;
+        this._drawCalls = 0;
+        this._triangles = 0;
+        this._pipelineSwitches = 0;
+        this._bindGroupChanges = 0;
+        this._bufferRebinds = 0;
+    }
+    get drawCalls() {
+        return this._drawCalls;
+    }
+    get triangles() {
+        return this._triangles;
+    }
+    get pipelineSwitches() {
+        return this._pipelineSwitches;
+    }
+    get bindGroupChanges() {
+        return this._bindGroupChanges;
+    }
+    get bufferRebinds() {
+        return this._bufferRebinds;
+    }
+    resetStats() {
+        this._drawCalls = 0;
+        this._triangles = 0;
+        this._pipelineSwitches = 0;
+        this._bindGroupChanges = 0;
+        this._bufferRebinds = 0;
+    }
+    setPipeline(pipeline) {
+        if (this.state.pipeline !== pipeline) {
+            this.pass.setPipeline(pipeline);
+            this.state.pipeline = pipeline;
+            this._pipelineSwitches++;
+        }
+    }
+    setBindGroup(index, group, dynamicOffsets) {
+        const existing = this.state.bindGroups.get(index);
+        if (existing !== group) {
+            this.pass.setBindGroup(index, group, dynamicOffsets ?? []);
+            this.state.bindGroups.set(index, group);
+            this._bindGroupChanges++;
+        }
+    }
+    setVertexBuffer(slot, buffer, offset = 0) {
+        const existing = this.state.vertexBuffers.get(slot);
+        if (existing !== buffer) {
+            this.pass.setVertexBuffer(slot, buffer, offset);
+            this.state.vertexBuffers.set(slot, buffer);
+            this._bufferRebinds++;
+        }
+    }
+    setIndexBuffer(buffer, format, offset = 0) {
+        if (this.state.indexBuffer !== buffer || this.state.indexFormat !== format) {
+            this.pass.setIndexBuffer(buffer, format, offset);
+            this.state.indexBuffer = buffer;
+            this.state.indexFormat = format;
+            this._bufferRebinds++;
+        }
+    }
+    draw(vertexCount, instanceCount = 1, firstVertex = 0, firstInstance = 0) {
+        this.pass.draw(vertexCount, instanceCount, firstVertex, firstInstance);
+        this._drawCalls++;
+        this._triangles += Math.floor(vertexCount / 3) * instanceCount;
+    }
+    drawIndexed(indexCount, instanceCount = 1, firstIndex = 0, baseVertex = 0, firstInstance = 0) {
+        this.pass.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance);
+        this._drawCalls++;
+        this._triangles += Math.floor(indexCount / 3) * instanceCount;
+    }
+    drawIndirect(indirectBuffer, indirectOffset = 0) {
+        this.pass.drawIndirect(indirectBuffer, indirectOffset);
+        this._drawCalls++;
+        // Indirect arg counts are on the GPU; triangle count is not available synchronously.
+    }
+    drawIndexedIndirect(indirectBuffer, indirectOffset = 0) {
+        this.pass.drawIndexedIndirect(indirectBuffer, indirectOffset);
+        this._drawCalls++;
+        // Indirect arg counts are on the GPU; triangle count is not available synchronously.
+    }
+    end() {
+        this.pass.end();
+    }
+    getRawPass() {
+        return this.pass;
+    }
+}

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

@@ -0,0 +1,81 @@
+export class ViewportLayout {
+    static compute(playerCount, screenW, screenH, mode = "split") {
+        if (playerCount <= 0)
+            return [];
+        if (mode === "shared" || playerCount === 1) {
+            return fullScreen(playerCount);
+        }
+        if (playerCount === 2) {
+            return split2(screenW, screenH);
+        }
+        if (playerCount <= 4) {
+            return grid4(screenW, screenH, playerCount);
+        }
+        return gridDynamic(screenW, screenH, playerCount);
+    }
+}
+function fullScreen(count) {
+    const rects = [];
+    for (let i = 0; i < count; i++) {
+        rects.push({ x: 0, y: 0, w: 1, h: 1 });
+    }
+    return rects;
+}
+function split2(w, h) {
+    if (w >= h) {
+        return [
+            { x: 0, y: 0, w: 0.5, h: 1 },
+            { x: 0.5, y: 0, w: 0.5, h: 1 },
+        ];
+    }
+    return [
+        { x: 0, y: 0, w: 1, h: 0.5 },
+        { x: 0, y: 0.5, w: 1, h: 0.5 },
+    ];
+}
+function grid4(w, h, count) {
+    const rects = [];
+    const halfW = 0.5;
+    const halfH = 0.5;
+    const positions = [
+        { x: 0, y: 0 },
+        { x: halfW, y: 0 },
+        { x: 0, y: halfH },
+        { x: halfW, y: halfH },
+    ];
+    for (let i = 0; i < count; i++) {
+        rects.push({
+            x: positions[i].x,
+            y: positions[i].y,
+            w: halfW,
+            h: halfH,
+        });
+    }
+    return rects;
+}
+function gridDynamic(w, h, count) {
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    const cellW = 1 / cols;
+    const cellH = 1 / rows;
+    const rects = [];
+    for (let i = 0; i < count; i++) {
+        const col = i % cols;
+        const row = Math.floor(i / cols);
+        rects.push({
+            x: col * cellW,
+            y: row * cellH,
+            w: cellW,
+            h: cellH,
+        });
+    }
+    return rects;
+}
+export function viewportRectToPixels(rect, screenW, screenH) {
+    return {
+        x: Math.floor(rect.x * screenW),
+        y: Math.floor(rect.y * screenH),
+        w: Math.floor(rect.w * screenW),
+        h: Math.floor(rect.h * screenH),
+    };
+}

package/dist/core/src/render/wgsl-hmr.js

@@ -0,0 +1,66 @@
+// ============================================================================
+// wgslHotReload — shader source registry for fine-grained WGSL HMR
+// ============================================================================
+//
+// Zero-dependency module (no imports) to avoid circular dependency concerns.
+// The wgslHmrPlugin (vite) registers shader sources at module-load time and
+// calls reload() when a `*.wgsl?raw` module is hot-updated. Consumers
+// (MaterialLibrary, game pass classes, entity-shaders) subscribe to be
+// notified of changes so they can rebuild GPU pipelines without a full page
+// reload. When there are no subscribers for a given shader, reload() falls
+// back to a full page reload so edits always take effect.
+//
+// In production builds this registry is inert: register() still runs (harmless
+// Map insert) but reload() is never called because import.meta.hot is absent.
+class WgslHotReloadRegistry {
+    sources = new Map();
+    listeners = new Map();
+    /** Register a shader source by its absolute file path. */
+    register(id, source) {
+        this.sources.set(id, source);
+    }
+    /** Get the most recently registered source for a shader. */
+    get(id) {
+        return this.sources.get(id);
+    }
+    /**
+     * Subscribe to reload notifications for a shader id.
+     * Returns an unsubscribe function.
+     */
+    subscribe(id, fn) {
+        let set = this.listeners.get(id);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(id, set);
+        }
+        set.add(fn);
+        return () => {
+            set.delete(fn);
+            if (set.size === 0)
+                this.listeners.delete(id);
+        };
+    }
+    /**
+     * Notify subscribers that a shader was reloaded. If there are no
+     * subscribers, fall back to a full page reload so the edit always
+     * takes effect.
+     */
+    reload(id, newSource) {
+        this.sources.set(id, newSource);
+        const set = this.listeners.get(id);
+        if (set && set.size > 0) {
+            set.forEach((fn) => fn(newSource));
+        }
+        else {
+            // No fine-grained subscriber — restart so the change is visible. The
+            // host's requestRestart handles native (self-respawn); DOM hosts
+            // fall back to a page reload.
+            const req = globalThis.downdraft?.requestRestart;
+            if (typeof req === "function" && req("WGSL reload — no subscriber"))
+                return;
+            if (typeof window !== "undefined")
+                window.location.reload();
+        }
+    }
+}
+export const wgslHotReload = new WgslHotReloadRegistry();