@driftengine/core 3.61.0

package/dist/render/backend/webgpu/clusterBinner.js

@@ -0,0 +1,206 @@
+import { CLUSTER_COUNT, LIGHT_RECORD, LIGHT_TEXELS, NO_IES_PROFILE, POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER, MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, } from '../../clusteredLights.js';
+import { MAX_POINT_LIGHTS } from '../../lightBudget.js';
+import { CLUSTER_BIN_WGSL } from './shaders/clusterBin.wgsl.js';
+/**
+ * The froxel binner on the GPU: the first thing in this engine to dispatch compute.
+ *
+ * **What it replaces is not a slow thing, it is a thing on the wrong processor.** The CPU binner
+ * in `clusteredLights.ts` is measured at 0.386 ms a frame for sixteen lights and 2.0 ms for 256,
+ * and 2 ms is 12% of a 60 fps frame spent on the main thread where a consumer's own game logic
+ * lives. On WebGL2 there is nowhere else to put it. Here there is.
+ *
+ * **It writes the same table, and that is asserted rather than assumed.** `scripts/cluster-check.mjs`
+ * runs both binners over one camera and one light set and compares the tables, because the
+ * 2026-08-17 rule says two implementations of one decision drift invisibly when their constants
+ * agree — which is exactly the situation this is.
+ */
+/*
+ * WebGPU usage flags, named rather than read off the globals, for the reason `buffers.ts` gives:
+ * the values are normative in the specification and the globals do not exist outside a browser.
+ */
+const BUFFER_USAGE = {
+    COPY_DST: 0x0008,
+    UNIFORM: 0x0040,
+    STORAGE: 0x0080,
+};
+const TEXTURE_USAGE = {
+    COPY_SRC: 0x01,
+    TEXTURE_BINDING: 0x04,
+    STORAGE_BINDING: 0x08,
+};
+/** `mat4` plus a `vec4` plus four `u32`, which is 96 bytes and already 16-byte aligned. */
+const PARAMS_BYTES = 16 * 4 + 4 * 4 + 4 * 4;
+/** Invocations a workgroup, matching `@workgroup_size` in the shader. */
+const WORKGROUP = 64;
+export class ClusterBinner {
+    /** The table the lit pass samples. Written by the dispatch, never by the CPU on this backend. */
+    texture = null;
+    view = null;
+    pipeline = null;
+    group = null;
+    params = null;
+    lightBuffer = null;
+    device = null;
+    /** Staging for the two uploads, allocated once: `dispatch` is a per-frame path. */
+    paramsStaging = new ArrayBuffer(PARAMS_BYTES);
+    paramsFloats = new Float32Array(this.paramsStaging);
+    paramsUints = new Uint32Array(this.paramsStaging);
+    lightStaging = new Float32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
+    frame = null;
+    /** The table's view, for whoever binds it into the lit pass. Null before `init`. */
+    get tableView() {
+        return this.view;
+    }
+    /** The table itself, which a readback needs and the lit pass does not. */
+    get tableTexture() {
+        return this.texture;
+    }
+    /**
+     * The device `init` was handed, for a caller that needs to encode a copy of its own.
+     *
+     * **Exposed rather than fetched from somewhere else**, because there is nowhere else: a
+     * `GPUTexture` does not name its device and `createRenderer` does not return one. The seam
+     * hands a definition the device precisely so it can do work of its own outside a dispatch, and
+     * a readback is that work.
+     */
+    get gpuDevice() {
+        return this.device;
+    }
+    /** What the next dispatch bins. Set per frame; nothing is copied until `dispatch`. */
+    setFrame(frame) {
+        this.frame = frame;
+    }
+    definition() {
+        return {
+            label: 'lights.bin',
+            init: (device) => this.build(device.device),
+            dispatch: (ctx) => this.run(ctx),
+            dispose: () => this.release(),
+        };
+    }
+    build(device) {
+        this.device = device;
+        this.texture = device.createTexture({
+            label: 'lights.clusterTable',
+            size: [TABLE_WIDTH, TABLE_HEIGHT],
+            /*
+             * `rgba32uint` because the indices are integers and an integer is what a texture carries
+             * exactly. It is also one of core WebGPU's storage-capable formats, which is what lets the
+             * dispatch write it at all — and `texelFetch` reads the same format on WebGL2, which is the
+             * whole reason the interface between binning and shading is a texture.
+             */
+            format: 'rgba32uint',
+            usage: TEXTURE_USAGE.STORAGE_BINDING | TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_SRC,
+        });
+        this.view = this.texture.createView({ label: 'lights.clusterTable' });
+        this.params = device.createBuffer({
+            label: 'lights.bin.params',
+            size: PARAMS_BYTES,
+            usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST,
+        });
+        this.lightBuffer = device.createBuffer({
+            label: 'lights.bin.lights',
+            size: this.lightStaging.byteLength,
+            usage: BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_DST,
+        });
+        this.pipeline = device.createComputePipeline({
+            label: 'lights.bin',
+            layout: 'auto',
+            compute: {
+                module: device.createShaderModule({ label: 'lights.bin', code: CLUSTER_BIN_WGSL }),
+                entryPoint: 'main',
+            },
+        });
+        this.group = device.createBindGroup({
+            label: 'lights.bin',
+            layout: this.pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.params } },
+                { binding: 1, resource: { buffer: this.lightBuffer } },
+                { binding: 2, resource: this.view },
+            ],
+        });
+    }
+    run(ctx) {
+        const frame = this.frame;
+        const { device, pipeline, group, params, lightBuffer } = this;
+        if (frame === null || device === null || pipeline === null || group === null)
+            return;
+        if (params === null || lightBuffer === null)
+            return;
+        const count = Math.min(frame.lights.count, MAX_CLUSTERED_LIGHTS);
+        /*
+         * The records, in exactly the order `buildLightClusters` writes them, because the shader
+         * copies them into the table verbatim and the lit pass reads one layout on both backends.
+         */
+        for (let light = 0; light < count; light++) {
+            const at = light * LIGHT_TEXELS * 4;
+            this.lightStaging[at] = frame.lights.positions[light * 3] ?? 0;
+            this.lightStaging[at + 1] = frame.lights.positions[light * 3 + 1] ?? 0;
+            this.lightStaging[at + 2] = frame.lights.positions[light * 3 + 2] ?? 0;
+            this.lightStaging[at + 3] = frame.lights.radii[light] ?? 0;
+            this.lightStaging[at + 4] = frame.lights.colors[light * 3] ?? 0;
+            this.lightStaging[at + 5] = frame.lights.colors[light * 3 + 1] ?? 0;
+            this.lightStaging[at + 6] = frame.lights.colors[light * 3 + 2] ?? 0;
+            this.lightStaging[at + 7] = frame.lights.sourceRadii[light] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.weight] = frame.lights.weights[light] ?? 1;
+            this.lightStaging[at + LIGHT_RECORD.shadowSlot] = light < frame.shadowSlots ? light : -1;
+            /*
+             * The cone, addressed through `LIGHT_RECORD` rather than by number. Two writers fill this
+             * record — the CPU binner in `clusteredLights.ts` and this — and the 2026-08-17 rule is that
+             * two implementations of one decision drift invisibly when the constants are identical. They
+             * now read the same table of offsets, so a field can only move in both at once.
+             *
+             * `POINT_LIGHT_COS_OUTER` and its inner twin are what make a light with no cone collapse to
+             * exactly the arithmetic a point light had. `scripts/cluster-check.mjs` compares the two
+             * tables byte for byte and is what would catch this being wrong anyway.
+             */
+            const directions = frame.lights.directions;
+            const cone = frame.lights.coneCos;
+            this.lightStaging[at + LIGHT_RECORD.directionX] = directions?.[light * 3] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.directionY] = directions?.[light * 3 + 1] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.directionZ] = directions?.[light * 3 + 2] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.cosInner] = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
+            this.lightStaging[at + LIGHT_RECORD.cosOuter] =
+                cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+            this.lightStaging[at + LIGHT_RECORD.iesProfile] =
+                frame.lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
+            /* The azimuth reference an asymmetric profile is oriented by; zero where a consumer gave
+               none, which the shader reads as no usable reference and leaves on the first plane. */
+            const axes = frame.lights.iesAxes;
+            this.lightStaging[at + LIGHT_RECORD.iesAxisX] = axes?.[light * 3] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.iesAxisY] = axes?.[light * 3 + 1] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.iesAxisZ] = axes?.[light * 3 + 2] ?? 0;
+            this.lightStaging[at + LIGHT_RECORD.cookie] = frame.lights.cookies?.[light] ?? NO_IES_PROFILE;
+        }
+        this.paramsFloats.set(frame.view, 0);
+        this.paramsFloats[16] = frame.near;
+        this.paramsFloats[17] = frame.far;
+        this.paramsFloats[18] = frame.tanHalfFovY;
+        this.paramsFloats[19] = frame.aspect;
+        this.paramsUints[20] = count;
+        device.queue.writeBuffer(params, 0, this.paramsStaging);
+        device.queue.writeBuffer(lightBuffer, 0, this.lightStaging.buffer, 0, count * LIGHT_TEXELS * 16);
+        ctx.pass.setPipeline(pipeline);
+        ctx.pass.setBindGroup(0, group);
+        /*
+         * Enough invocations for every cluster. The first `count` of them also write a light record,
+         * which they can because there are always far more clusters than lights.
+         */
+        ctx.pass.dispatchWorkgroups(Math.ceil(CLUSTER_COUNT / WORKGROUP));
+    }
+    release() {
+        this.texture?.destroy();
+        this.params?.destroy();
+        this.lightBuffer?.destroy();
+        this.texture = null;
+        this.view = null;
+        this.params = null;
+        this.lightBuffer = null;
+        this.pipeline = null;
+        this.group = null;
+        this.device = null;
+    }
+}
+/** The shadow slots a frame has, which is the fixed budget the pool is sized for. */
+export const DEFAULT_SHADOW_SLOTS = MAX_POINT_LIGHTS;

package/dist/render/backend/webgpu/depthPass.d.ts

@@ -0,0 +1,114 @@
+import { DEPTH_FRAG_WGSL } from '../../shaders/generated/depth.wgsl.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The shadow pass: the world drawn from the light, into a depth map.
+ *
+ * **A pass of its own, before the frame.** `beginShadowPass` is called by a scene *before*
+ * `beginFrame`, so this owns its own encoder and its own render pass rather than sharing the
+ * frame's. That ordering is the scene's and is not this backend's to change.
+ */
+export declare const DEPTH_VERT_FIELDS: {
+    readonly uLightViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uModel: {
+        readonly offset: 64;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uWindDirection: {
+        readonly offset: 128;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uWindSpeed: {
+        readonly offset: 136;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindGust: {
+        readonly offset: 140;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindTime: {
+        readonly offset: 144;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindSpatialPhase: {
+        readonly offset: 152;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+};
+export declare const DEPTH_VERT_SIZE: 160;
+export declare const DEPTH_FRAG_SIZE: 16;
+/** Re-exported so the scatter depth pass can pair with the same fragment stage. */
+export { DEPTH_FRAG_WGSL };
+export declare const DEPTH_FRAG_BINDING: 1;
+export declare const DEPTH_PREVIOUS_BINDING: {
+    readonly texture: 32;
+    readonly sampler: 33;
+    readonly type: "sampler2D";
+};
+/** Where the skinned vertex stage reads the joint palette. Generated, not chosen here. */
+export declare const DEPTH_PALETTE_BINDING: {
+    readonly texture: 16;
+    readonly sampler: 17;
+    readonly type: "sampler2D";
+};
+/**
+ * The format the shadow map is stored in.
+ *
+ * `depth32float` rather than the frame's `depth24plus`, because this one is *sampled* as
+ * well as written and a comparison against a quantised depth is where shadow acne comes
+ * from. It is also the format `shadowMap.ts` asks WebGL2 for, so the two backends compare
+ * the same numbers.
+ */
+export declare const SHADOW_FORMAT: GPUTextureFormat;
+export declare function createDepthBindGroupLayout(device: GPUDevice, 
+/**
+ * Whether this layout carries the joint palette.
+ *
+ * A **separate layout** rather than the palette added to the one layout with a stand-in bound
+ * when nothing is skinned, which is the shape `flatLayoutFor` already uses. What it buys is that
+ * the rigid path is untouched: no extra binding, no one-pixel texture to keep alive, and a
+ * frame that skins nothing pays nothing at all.
+ */
+skinned?: boolean): GPUBindGroupLayout;
+export declare function createDepthBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perPass: GPUBuffer, previous: GPUTextureView, sampler: GPUSampler, 
+/** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
+palette?: GPUTextureView | null): GPUBindGroup;
+/**
+ * The depth pipeline.
+ *
+ * **No colour target at all.** The pass writes depth and nothing else, which is what makes
+ * it cheap; a colour attachment here would be a buffer written and never read.
+ *
+ * The vertex layout is the mesh's own, because the depth shader takes position from
+ * location 0 and the pipeline still has to describe every attribute the module declares.
+ */
+export declare function depthPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, present: Readonly<Record<string, boolean>>, 
+/**
+ * **`none` for a cubemap face, and the directional pass's own comment says why not here.**
+ *
+ * That comment argues against culling front faces to cure acne, and it is about the
+ * *directional* map, which is rendered from far away over a whole world. A point light's
+ * cube is rendered from inside a room, and `pointShadowMap.ts` disables culling outright for
+ * a reason that is not about acne at all: rendering back faces only stores the far side of
+ * every caster, and for a character's limbs the near and far sides are centimetres apart, so
+ * the caster effectively vanishes from the map. Two passes, two answers, one parameter.
+ */
+cullMode?: GPUCullMode, 
+/** Whether this pipeline's vertex stage reads a joint palette. See `DEPTH_SKINNED_VERT`. */
+skinned?: boolean, 
+/**
+ * Whether placement arrives per instance. See `DEPTH_INSTANCED_VERT`.
+ *
+ * Excludes `skinned`, and the layout is why rather than the shader: an instanced pipeline
+ * reclaims the two attribute locations the joint indices and weights occupy.
+ */
+instanced?: boolean): GPURenderPipeline;

package/dist/render/backend/webgpu/depthPass.js

@@ -0,0 +1,228 @@
+import { DEPTH_BINDINGS, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
+import { vertexBufferLayouts } from './buffers.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The shadow pass: the world drawn from the light, into a depth map.
+ *
+ * **A pass of its own, before the frame.** `beginShadowPass` is called by a scene *before*
+ * `beginFrame`, so this owns its own encoder and its own render pass rather than sharing the
+ * frame's. That ordering is the scene's and is not this backend's to change.
+ */
+export const DEPTH_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_VERT.fields;
+export const DEPTH_VERT_SIZE = DEPTH_BINDINGS.DEPTH_VERT.uniformSize;
+export const DEPTH_FRAG_SIZE = DEPTH_BINDINGS.DEPTH_FRAG.uniformSize;
+/** Re-exported so the scatter depth pass can pair with the same fragment stage. */
+export { DEPTH_FRAG_WGSL };
+export const DEPTH_FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
+export const DEPTH_PREVIOUS_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.textures.uPreviousShadowMap;
+const VERT_BINDING = DEPTH_BINDINGS.DEPTH_VERT.uniforms;
+const FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
+const PREVIOUS = DEPTH_BINDINGS.DEPTH_FRAG.textures.uPreviousShadowMap;
+/** Where the skinned vertex stage reads the joint palette. Generated, not chosen here. */
+export const DEPTH_PALETTE_BINDING = DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uJointPalette;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+/**
+ * The format the shadow map is stored in.
+ *
+ * `depth32float` rather than the frame's `depth24plus`, because this one is *sampled* as
+ * well as written and a comparison against a quantised depth is where shadow acne comes
+ * from. It is also the format `shadowMap.ts` asks WebGL2 for, so the two backends compare
+ * the same numbers.
+ */
+export const SHADOW_FORMAT = 'depth32float';
+export function createDepthBindGroupLayout(device, 
+/**
+ * Whether this layout carries the joint palette.
+ *
+ * A **separate layout** rather than the palette added to the one layout with a stand-in bound
+ * when nothing is skinned, which is the shape `flatLayoutFor` already uses. What it buys is that
+ * the rigid path is untouched: no extra binding, no one-pixel texture to keep alive, and a
+ * frame that skins nothing pays nothing at all.
+ */
+skinned = false) {
+    return device.createBindGroupLayout({
+        label: skinned ? 'depth.layout.skinned' : 'depth.layout',
+        entries: [
+            /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
+               coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
+               palette. naga declares a sampler for it and nothing ever reads one. */
+            ...(skinned
+                ? [
+                    {
+                        binding: DEPTH_PALETTE_BINDING.texture,
+                        visibility: VISIBILITY_VERTEX,
+                        texture: { sampleType: 'unfilterable-float' },
+                    },
+                ]
+                : []),
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: DEPTH_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', minBindingSize: DEPTH_FRAG_SIZE },
+            },
+            /*
+             * **`unfilterable-float`, because the peel binds `SHADOW_FORMAT` here.**
+             *
+             * The defaults are `sampleType: 'float'` and `type: 'filtering'`, and a `depth32float`
+             * view satisfies neither. The device rejects the pair in as many words — *"None of the
+             * supported sample types (UnfilterableFloat|Depth) of [Texture "shadow.static"] match
+             * the expected sample types (Float)"* — and it rejects it by returning an **invalid
+             * bind group rather than throwing**. A peel pass built on one records nothing, so the
+             * peel map keeps the undefined contents it was created with and the frame still
+             * presents. Three ports of the peel were measured and reverted against that silence.
+             *
+             * The one-pixel `rgba8unorm` stand-in every non-peel frame binds here satisfies this
+             * too — measured, both ways — and the sampler beside it is all-`nearest` already, which
+             * is what `non-filtering` requires. `flatPass.ts` reaches the same declaration from the
+             * name, and `uPreviousShadowMap` is one of the names it would match.
+             */
+            {
+                binding: PREVIOUS.texture,
+                visibility: VISIBILITY_FRAGMENT,
+                texture: { sampleType: 'unfilterable-float' },
+            },
+            {
+                binding: PREVIOUS.sampler,
+                visibility: VISIBILITY_FRAGMENT,
+                sampler: { type: 'non-filtering' },
+            },
+        ],
+    });
+}
+export function createDepthBindGroup(device, layout, perDraw, perPass, previous, sampler, 
+/** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
+palette = null) {
+    return device.createBindGroup({
+        label: palette === null ? 'depth.bindGroup' : 'depth.bindGroup.skinned',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: perDraw, size: DEPTH_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: perPass, size: DEPTH_FRAG_SIZE } },
+            { binding: PREVIOUS.texture, resource: previous },
+            { binding: PREVIOUS.sampler, resource: sampler },
+            ...(palette !== null ? [{ binding: DEPTH_PALETTE_BINDING.texture, resource: palette }] : []),
+        ],
+    });
+}
+/**
+ * The depth pipeline.
+ *
+ * **No colour target at all.** The pass writes depth and nothing else, which is what makes
+ * it cheap; a colour attachment here would be a buffer written and never read.
+ *
+ * The vertex layout is the mesh's own, because the depth shader takes position from
+ * location 0 and the pipeline still has to describe every attribute the module declares.
+ */
+export function depthPipeline(cache, device, layout, key, present, 
+/**
+ * **`none` for a cubemap face, and the directional pass's own comment says why not here.**
+ *
+ * That comment argues against culling front faces to cure acne, and it is about the
+ * *directional* map, which is rendered from far away over a whole world. A point light's
+ * cube is rendered from inside a room, and `pointShadowMap.ts` disables culling outright for
+ * a reason that is not about acne at all: rendering back faces only stores the far side of
+ * every caster, and for a character's limbs the near and far sides are centimetres apart, so
+ * the caster effectively vanishes from the map. Two passes, two answers, one parameter.
+ */
+cullMode = 'back', 
+/** Whether this pipeline's vertex stage reads a joint palette. See `DEPTH_SKINNED_VERT`. */
+skinned = false, 
+/**
+ * Whether placement arrives per instance. See `DEPTH_INSTANCED_VERT`.
+ *
+ * Excludes `skinned`, and the layout is why rather than the shader: an instanced pipeline
+ * reclaims the two attribute locations the joint indices and weights occupy.
+ */
+instanced = false) {
+    return cache.get(key, () => ({
+        label: key,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, instanced
+                ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+                : skinned
+                    ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+                    : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: vertexBufferLayouts(present, instanced),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'depth.frag', code: DEPTH_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [],
+        },
+        /*
+         * **Back faces culled, matching the frame.** Culling front faces instead is the textbook
+         * answer to shadow acne, and it is the wrong answer here: `renderer.ts` keeps the
+         * frame's own back-face culling through the directional pass and handles acne with
+         * receiver-plane compensation instead, so a depth map built from the far side of every
+         * surface disagrees with what the shader expects to compare against.
+         *
+         * The symptom was unmistakable and worth recording: the whole scene came out uniformly
+         * in shadow — paving, pillars and all — because every fragment compared itself against a
+         * depth recorded behind it.
+         *
+         * **`frontFace: 'cw'`, and it is this pass's projection that asks for it rather than a
+         * preference.** Facing is decided in framebuffer coordinates, whose Y points down while
+         * clip space's points up, so a triangle wound counter-clockwise in clip space reaches the
+         * rasteriser clockwise. Every presented pass is projected through `CLIP_CORRECTION`, which
+         * negates Y and turns that back over, so the default `ccw` is right for all of them. This
+         * map is sampled rather than presented, so `SHADOW_CLIP_CORRECTION` leaves Y alone — and
+         * the default then culls precisely the faces this pass exists to record.
+         *
+         * That shipped and was invisible for a fortnight, because it takes geometry the light can
+         * see through to show: on a world of a vault over an arcade, the vault was missing from the
+         * map, so the arcade under it was lit here and in shadow on WebGL2. Read back texel for
+         * texel against that backend, 2,000,709 texels of 2,095,575 differed by more than 0.2 m and
+         * 805,117 by more than 2 m, this map holding surfaces 8.4 m further from the light on
+         * average; declaring the winding takes those to 6,972 and 0.
+         *
+         * **What would make it wrong** is giving this pass the Y flip after all — the winding has to
+         * move back with it, and neither half is inert on its own.
+         * `webgpu/renderer.test.ts` asserts the pair against the matrix rather than against the
+         * literal for that reason.
+         */
+        primitive: { topology: 'triangle-list', cullMode, frontFace: 'cw' },
+        /*
+         * **The raster offset the other backend has always had, and this one never did.**
+         *
+         * `shadowMap.ts` sets `gl.polygonOffset(1.1, 4)` for its directional pass and calls it
+         * load-bearing in its own comment: *"a small slope-aware raster offset separates the stored
+         * caster from its receiver"*. This pipeline declared a format, a write and a compare, and
+         * nothing else — so every WebGPU shadow was compared against a depth with no separation at
+         * all.
+         *
+         * **It was measured as minor and it was not.** Adding it moved 2,178 pixels when it was first
+         * tried, which read as a small thing worth taking on its own terms. What that measurement
+         * could not see is that the pass was, at the time, storing the *far* side of every caster
+         * because its winding was inverted — and a caster's own thickness is an enormous accidental
+         * bias. Correcting the winding removed the masking, and what it exposed is what a shadow pass
+         * with no offset does: acne on ground in shadow, and self-shadowing near geometry that reads
+         * as a shadow with nothing casting it.
+         *
+         * **`depthBias` is not the same quantity on the two backends and that is stated rather than
+         * hidden.** WebGL2's `units` are multiples of the smallest resolvable difference of a
+         * `DEPTH_COMPONENT24` map; WebGPU applies the constant against a `depth32float`, where the
+         * specification scales it by the exponent of the primitive's maximum depth. The slope term is
+         * the same quantity in both. So these are the other backend's numbers as a starting point and
+         * the constant is the half to distrust — which is why `shadows.html` exists.
+         *
+         * **What would make it wrong** is over-biasing, which detaches a shadow from its caster: the
+         * failure `shadowMap.ts` names as the reason it culls back faces rather than front. Too small
+         * shows as acne, too large as a floating shadow, and only one of them looks like a bug.
+         */
+        depthStencil: {
+            format: SHADOW_FORMAT,
+            depthWriteEnabled: true,
+            depthCompare: 'less',
+            depthBias: 4,
+            depthBiasSlopeScale: 1.1,
+        },
+    }));
+}

package/dist/render/backend/webgpu/device.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A device, a configured canvas, and loss adapted to the shape the renderer already handles.
+ *
+ * Everything WebGPU-specific about *owning* a drawing surface lives here, so that
+ * `webgpu/renderer.ts` is about drawing and this is about the context it draws into. The
+ * split matters because these two fail for unrelated reasons: a device is lost by a driver
+ * reset the page did not cause, and a frame is wrong because of something the frame did.
+ */
+/** What the renderer needs from the canvas it draws into, with the API's shape absorbed. */
+export interface GpuSurface {
+    readonly device: GPUDevice;
+    readonly context: GPUCanvasContext;
+    /**
+     * The canvas being drawn into.
+     *
+     * Carried because the renderer's public measurements are questions about it and nothing
+     * else: `cssWidth` and `cssHeight` are its CSS box, `aspect` its drawing buffer. WebGL2
+     * answers them off `this.canvas` and a second backend has to answer the same questions
+     * from somewhere.
+     */
+    readonly canvas: HTMLCanvasElement;
+    /** The swap chain's format, which every render pipeline has to be built against. */
+    readonly format: GPUTextureFormat;
+    /** Whether the device has gone. Read per frame; never throws. */
+    readonly lost: boolean;
+    /** Called when the device is lost. Fires immediately if it already has been. */
+    onLost(listener: () => void): void;
+    /** Resize the drawing buffer and reconfigure the swap chain. */
+    configure(width: number, height: number): void;
+    /** Tear down on purpose. A disposed surface never reports a loss. */
+    dispose(): void;
+}
+/**
+ * Take a canvas and a device, and hand back the surface the renderer draws into.
+ *
+ * **Device loss is a promise, and that is a different shape from the event WebGL gives.**
+ * `webglcontextlost` fires once and is missed by anybody not already listening;
+ * `device.lost` is a promise that resolves once, never rejects, and stays resolved. A
+ * renderer constructed after the loss therefore gets no event at all from the WebGL-shaped
+ * mental model, and would draw into a dead device forever without ever being told.
+ *
+ * So the resolution is latched here and `onLost` fires immediately for a listener that
+ * arrives late. Adapting it once, at the boundary, is why no call site has to know that the
+ * two APIs disagree about what a failure looks like — the same argument `contextLoss.ts`
+ * makes for owning the WebGL half rather than letting a game listen for it.
+ *
+ * **Disposal is not loss.** Tearing a surface down calls `destroy()`, which resolves
+ * `device.lost` exactly as a driver reset would. Reporting that to listeners would tell a
+ * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
+ * surface stays silent.
+ */
+export declare function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice): GpuSurface;