@driftengine/core 3.61.0

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

@@ -0,0 +1,133 @@
+import type { BudgetCounter } from '../budget.ts';
+/**
+ * WebGPU's default minimum alignment for a dynamic uniform offset.
+ *
+ * Exported because the bloom chain lays out its stages by hand rather than through this class —
+ * its blocks never change between frames, so it has nothing to reset and nothing to flush — and
+ * an alignment restated somewhere else is an alignment that can disagree.
+ */
+export declare const DYNAMIC_ALIGNMENT = 256;
+/**
+ * Per-draw uniforms, in slots, written once and bound by offset.
+ *
+ * **This exists because `queue.writeBuffer` does not interleave with draw commands.** Writes
+ * are ordered on the queue timeline and the encoder's commands are submitted afterwards, so
+ * writing one model matrix into one buffer between two `draw` calls gives *both* draws the
+ * last matrix written. The picture is every object stacked at the position of whichever was
+ * drawn last, which looks like a transform bug and is not one.
+ *
+ * So each draw takes its own slot, all the slots are uploaded in a single write at the end
+ * of the frame, and the draw binds its slot with a dynamic offset. One upload per frame
+ * rather than one per draw, and no allocation in the frame loop: the staging array is
+ * allocated once and reused, which is what `AGENTS.md` requires of a per-frame path.
+ */
+export declare class UniformRing {
+    private readonly budget;
+    /**
+     * The device buffer every bind group over this ring holds.
+     *
+     * **Not `readonly`, because `growTo` replaces it**, and a bind group built against the old one
+     * is invalid the moment it does. That is the whole reason `growTo` reports whether it happened.
+     */
+    buffer: GPUBuffer;
+    /** Bytes per slot, rounded up to the alignment a dynamic offset requires. */
+    readonly slotSize: number;
+    private readonly device;
+    private readonly usage;
+    private readonly label;
+    private staging;
+    private floats;
+    private ints;
+    private capacity;
+    private used;
+    /**
+     * `label` names the buffer on the device, and it is not decoration.
+     *
+     * A validation failure arrives at `queue.submit` naming the resource it was about, and the
+     * only reason that message is readable is that somebody labelled the resource — the shadow
+     * peel's root cause read *"of [Texture "shadow.static"]"*. A dozen rings all called
+     * `uniforms.ring` would name none of themselves. See `device.ts`.
+     *
+     * `budget` is the line this ring's ceiling is reported on, and most rings have none.
+     * **Only one ring of a pair carries it**: several subsystems take a vertex slot and a fragment
+     * slot together, from two rings of equal capacity, and refuse the work if either is null — so a
+     * line on both would count every water body twice and report a ceiling of sixteen exceeded at
+     * eight. The vertex ring carries it by convention and the fragment ring beside it carries none.
+     */
+    constructor(device: GPUDevice, bytesPerSlot: number, slots: number, usage: number, label?: string, budget?: BudgetCounter | null);
+    /** How many slots this ring holds. What a frame may take before `allocate` starts refusing. */
+    get slots(): number;
+    /**
+     * Make room for at least `slots`, and say whether the buffer was replaced.
+     *
+     * **Called at the start of a frame and nowhere else**, which is what keeps `allocate`'s refusal
+     * to grow intact: there is no encoder open, everything from the last frame has been submitted,
+     * and nothing has been written into the staging that discarding it would lose. Growing where
+     * `allocate` runs out would stall the frame to make room, which is the thing this class exists
+     * to avoid and still does.
+     *
+     * **A `true` means every bind group holding `buffer` is now invalid.** The old buffer is
+     * destroyed rather than dropped: commands already submitted against it keep it alive until they
+     * retire, which is the implementation's job, and nothing recorded for *this* frame exists yet.
+     *
+     * Refuses past `MAX_RING_BYTES` and says `false`, leaving the ring it has — a frame asking for
+     * more than that goes back to skipping the work and reporting it.
+     */
+    growTo(slots: number): boolean;
+    /** How many slots have been taken this frame. */
+    get count(): number;
+    /** Start a frame. Slots are reused; nothing is freed. */
+    reset(): void;
+    /**
+     * Take the next slot and return its byte offset, or null when the ring is full.
+     *
+     * **Null rather than growing.** Growing means allocating a buffer mid-frame, which is the
+     * thing this class exists to avoid; a caller that runs out should skip the draw and say so
+     * once, not stall the frame to make room.
+     *
+     * **And say so in a number as well as in a line of text.** Every caller already wrote one
+     * `console.warn` per renderer lifetime and nothing else, which is unobservable from a headless
+     * check and gone by the time anybody looks — a consumer lost weeks to a ceiling whose
+     * open lead was still *"ask the reporter for the console"*. The count is taken here rather than
+     * at the callers because here is the only place that knows both halves: what was asked for, and
+     * whether it fit.
+     *
+     * **What comes back is a byte offset, not an index**, and it is what `setBindGroup` wants.
+     *
+     * Said plainly because the name says "slot" and the value is already scaled: a caller that
+     * multiplies it by `slotSize` on the way to a dynamic offset lands a whole ring away. That
+     * happened — the second panel of a frame addressed 65,536 into a 16,384-byte ring — and the
+     * only reason it took a minute rather than an afternoon is that `device.ts` now prints what
+     * the device rejected, naming the buffer and both numbers.
+     */
+    allocate(): number | null;
+    /** Write floats into a slot, at a byte offset within it. */
+    writeFloats(slot: number, byteOffset: number, values: ArrayLike<number>): void;
+    /**
+     * Write one float into a slot.
+     *
+     * Separate from `writeFloats` because the alternative at a call site with a dozen scalars in
+     * it is a one-element array per field — either allocated in the frame loop, which
+     * `AGENTS.md` forbids, or a shared scratch that reads as a value being passed when it is a
+     * buffer being reused.
+     */
+    writeFloat(slot: number, byteOffset: number, value: number): void;
+    /** Write one integer into a slot. Separate because a `Float32Array` cannot hold an `i32`. */
+    writeInt(slot: number, byteOffset: number, value: number): void;
+    /**
+     * Copy a whole prepared block into a slot, bit for bit.
+     *
+     * **Through the integer view, and that is not a detail.** A block that mixes floats and
+     * `i32`s copied through `Float32Array` is a numeric conversion, and `-1` as an `i32` is
+     * `0xFFFFFFFF`, which read as a float is a NaN — free to be canonicalised to a different NaN
+     * on the way through. `-1` is the *sentinel* for "this light has no shadow cubemap", so that
+     * conversion would turn "no point shadows" into a number matching nothing or, worse,
+     * something. Bug 9 on this branch was that sentinel being wrong in the other direction.
+     *
+     * `Int32Array.set` from an `Int32Array` is an exact copy of every bit, whatever the bits mean.
+     */
+    writeBlock(slot: number, block: Int32Array): void;
+    /** Upload every slot taken this frame, in one write. */
+    flush(): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,208 @@
+/**
+ * WebGPU's default minimum alignment for a dynamic uniform offset.
+ *
+ * Exported because the bloom chain lays out its stages by hand rather than through this class —
+ * its blocks never change between frames, so it has nothing to reset and nothing to flush — and
+ * an alignment restated somewhere else is an alignment that can disagree.
+ */
+export const DYNAMIC_ALIGNMENT = 256;
+/**
+ * The most staging one ring may hold, and therefore the most device memory it may take.
+ *
+ * **A ceiling on the growth, because a runaway consumer should degrade rather than crash.** Past
+ * this the ring refuses to grow and goes on skipping work and reporting it, which is the right end
+ * state for a frame asking for something no device should be asked for. What growth changes is
+ * where that line sits: at a number chosen against a phone's memory rather than at whatever the
+ * ring happened to be constructed with.
+ *
+ * Sixty-four mebibytes is far past any legitimate scene — the flat vertex ring's slot is 1,540
+ * bytes, so this is forty-three thousand draws, and the fragment ring's is at most 13,312, which
+ * is five thousand material changes in one frame. The device buffer matches the staging, so a ring
+ * at this ceiling holds 128 MiB in total and only ever reaches it by being asked to.
+ */
+const MAX_RING_BYTES = 64 * 1024 * 1024;
+/**
+ * Per-draw uniforms, in slots, written once and bound by offset.
+ *
+ * **This exists because `queue.writeBuffer` does not interleave with draw commands.** Writes
+ * are ordered on the queue timeline and the encoder's commands are submitted afterwards, so
+ * writing one model matrix into one buffer between two `draw` calls gives *both* draws the
+ * last matrix written. The picture is every object stacked at the position of whichever was
+ * drawn last, which looks like a transform bug and is not one.
+ *
+ * So each draw takes its own slot, all the slots are uploaded in a single write at the end
+ * of the frame, and the draw binds its slot with a dynamic offset. One upload per frame
+ * rather than one per draw, and no allocation in the frame loop: the staging array is
+ * allocated once and reused, which is what `AGENTS.md` requires of a per-frame path.
+ */
+export class UniformRing {
+    budget;
+    /**
+     * The device buffer every bind group over this ring holds.
+     *
+     * **Not `readonly`, because `growTo` replaces it**, and a bind group built against the old one
+     * is invalid the moment it does. That is the whole reason `growTo` reports whether it happened.
+     */
+    buffer;
+    /** Bytes per slot, rounded up to the alignment a dynamic offset requires. */
+    slotSize;
+    device;
+    usage;
+    label;
+    staging;
+    floats;
+    ints;
+    capacity;
+    used = 0;
+    /**
+     * `label` names the buffer on the device, and it is not decoration.
+     *
+     * A validation failure arrives at `queue.submit` naming the resource it was about, and the
+     * only reason that message is readable is that somebody labelled the resource — the shadow
+     * peel's root cause read *"of [Texture "shadow.static"]"*. A dozen rings all called
+     * `uniforms.ring` would name none of themselves. See `device.ts`.
+     *
+     * `budget` is the line this ring's ceiling is reported on, and most rings have none.
+     * **Only one ring of a pair carries it**: several subsystems take a vertex slot and a fragment
+     * slot together, from two rings of equal capacity, and refuse the work if either is null — so a
+     * line on both would count every water body twice and report a ceiling of sixteen exceeded at
+     * eight. The vertex ring carries it by convention and the fragment ring beside it carries none.
+     */
+    constructor(device, bytesPerSlot, slots, usage, label = 'uniforms.ring', budget = null) {
+        this.budget = budget;
+        this.device = device;
+        this.usage = usage;
+        this.label = label;
+        this.slotSize = Math.ceil(bytesPerSlot / DYNAMIC_ALIGNMENT) * DYNAMIC_ALIGNMENT;
+        this.capacity = slots;
+        this.staging = new ArrayBuffer(this.slotSize * slots);
+        this.floats = new Float32Array(this.staging);
+        this.ints = new Int32Array(this.staging);
+        this.buffer = device.createBuffer({
+            label,
+            size: this.staging.byteLength,
+            usage,
+        });
+    }
+    /** How many slots this ring holds. What a frame may take before `allocate` starts refusing. */
+    get slots() {
+        return this.capacity;
+    }
+    /**
+     * Make room for at least `slots`, and say whether the buffer was replaced.
+     *
+     * **Called at the start of a frame and nowhere else**, which is what keeps `allocate`'s refusal
+     * to grow intact: there is no encoder open, everything from the last frame has been submitted,
+     * and nothing has been written into the staging that discarding it would lose. Growing where
+     * `allocate` runs out would stall the frame to make room, which is the thing this class exists
+     * to avoid and still does.
+     *
+     * **A `true` means every bind group holding `buffer` is now invalid.** The old buffer is
+     * destroyed rather than dropped: commands already submitted against it keep it alive until they
+     * retire, which is the implementation's job, and nothing recorded for *this* frame exists yet.
+     *
+     * Refuses past `MAX_RING_BYTES` and says `false`, leaving the ring it has — a frame asking for
+     * more than that goes back to skipping the work and reporting it.
+     */
+    growTo(slots) {
+        if (slots <= this.capacity)
+            return false;
+        const bytes = this.slotSize * slots;
+        if (bytes > MAX_RING_BYTES)
+            return false;
+        this.buffer.destroy();
+        this.capacity = slots;
+        this.staging = new ArrayBuffer(bytes);
+        this.floats = new Float32Array(this.staging);
+        this.ints = new Int32Array(this.staging);
+        this.buffer = this.device.createBuffer({
+            label: this.label,
+            size: bytes,
+            usage: this.usage,
+        });
+        return true;
+    }
+    /** How many slots have been taken this frame. */
+    get count() {
+        return this.used;
+    }
+    /** Start a frame. Slots are reused; nothing is freed. */
+    reset() {
+        this.used = 0;
+    }
+    /**
+     * Take the next slot and return its byte offset, or null when the ring is full.
+     *
+     * **Null rather than growing.** Growing means allocating a buffer mid-frame, which is the
+     * thing this class exists to avoid; a caller that runs out should skip the draw and say so
+     * once, not stall the frame to make room.
+     *
+     * **And say so in a number as well as in a line of text.** Every caller already wrote one
+     * `console.warn` per renderer lifetime and nothing else, which is unobservable from a headless
+     * check and gone by the time anybody looks — a consumer lost weeks to a ceiling whose
+     * open lead was still *"ask the reporter for the console"*. The count is taken here rather than
+     * at the callers because here is the only place that knows both halves: what was asked for, and
+     * whether it fit.
+     *
+     * **What comes back is a byte offset, not an index**, and it is what `setBindGroup` wants.
+     *
+     * Said plainly because the name says "slot" and the value is already scaled: a caller that
+     * multiplies it by `slotSize` on the way to a dynamic offset lands a whole ring away. That
+     * happened — the second panel of a frame addressed 65,536 into a 16,384-byte ring — and the
+     * only reason it took a minute rather than an afternoon is that `device.ts` now prints what
+     * the device rejected, naming the buffer and both numbers.
+     */
+    allocate() {
+        this.budget?.ask();
+        if (this.used >= this.capacity) {
+            this.budget?.drop();
+            return null;
+        }
+        const offset = this.used * this.slotSize;
+        this.used += 1;
+        return offset;
+    }
+    /** Write floats into a slot, at a byte offset within it. */
+    writeFloats(slot, byteOffset, values) {
+        this.floats.set(values, (slot + byteOffset) / 4);
+    }
+    /**
+     * Write one float into a slot.
+     *
+     * Separate from `writeFloats` because the alternative at a call site with a dozen scalars in
+     * it is a one-element array per field — either allocated in the frame loop, which
+     * `AGENTS.md` forbids, or a shared scratch that reads as a value being passed when it is a
+     * buffer being reused.
+     */
+    writeFloat(slot, byteOffset, value) {
+        this.floats[(slot + byteOffset) / 4] = value;
+    }
+    /** Write one integer into a slot. Separate because a `Float32Array` cannot hold an `i32`. */
+    writeInt(slot, byteOffset, value) {
+        this.ints[(slot + byteOffset) / 4] = value;
+    }
+    /**
+     * Copy a whole prepared block into a slot, bit for bit.
+     *
+     * **Through the integer view, and that is not a detail.** A block that mixes floats and
+     * `i32`s copied through `Float32Array` is a numeric conversion, and `-1` as an `i32` is
+     * `0xFFFFFFFF`, which read as a float is a NaN — free to be canonicalised to a different NaN
+     * on the way through. `-1` is the *sentinel* for "this light has no shadow cubemap", so that
+     * conversion would turn "no point shadows" into a number matching nothing or, worse,
+     * something. Bug 9 on this branch was that sentinel being wrong in the other direction.
+     *
+     * `Int32Array.set` from an `Int32Array` is an exact copy of every bit, whatever the bits mean.
+     */
+    writeBlock(slot, block) {
+        this.ints.set(block, slot / 4);
+    }
+    /** Upload every slot taken this frame, in one write. */
+    flush() {
+        if (this.used === 0)
+            return;
+        this.device.queue.writeBuffer(this.buffer, 0, this.staging, 0, this.used * this.slotSize);
+    }
+    dispose() {
+        this.buffer.destroy();
+    }
+}

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

@@ -0,0 +1,73 @@
+import type { PipelineCache } from './pipelineCache.ts';
+import type { UniformFields } from './scatterPass.ts';
+/**
+ * The water pass: two sheets and a patch, displaced by a wave field in the vertex stage.
+ *
+ * **One vertex attribute for the whole surface.** `aGrid` is a `vec2` of grid coordinates and
+ * everything else — height, normal, crest, the reflection's clip position — is computed from
+ * it. So the geometry here is a buffer of pairs and an index list, and the interesting part is
+ * entirely in the shader and the uniforms.
+ */
+export declare const WATER_VERT_FIELDS: UniformFields;
+export declare const WATER_VERT_SIZE: 208;
+export declare const WATER_FRAG_FIELDS: UniformFields;
+export declare const WATER_FRAG_SIZE: 1248;
+/** The two meshes and the numbers the grid decided, behind the surface's opaque handle. */
+export interface GpuWater {
+    /** The ocean: near sheet and far skirt in one buffer. */
+    readonly sheet: {
+        buffer: GPUBuffer;
+        index: GPUBuffer;
+        count: number;
+    };
+    /** A unit square, scaled per draw: every bounded body shares this one mesh. */
+    readonly patch: {
+        buffer: GPUBuffer;
+        index: GPUBuffer;
+        count: number;
+    };
+    readonly cellSize: number;
+    readonly nearHalfExtent: number;
+    readonly farHalfExtent: number;
+    readonly reflectionFilterTaps: number;
+    dispose(): void;
+}
+export declare function createGpuWater(device: GPUDevice, resolution: number, nearExtent: number, farHalfExtent: number, reflectionFilterTaps: number): GpuWater;
+export declare function waterVertexLayouts(): GPUVertexBufferLayout[];
+/**
+ * The water bind group's layout, whose two buffers are addressed by a dynamic offset.
+ *
+ * **A frame draws more than one body of water and this is what makes that true here.** A ditch at
+ * its own level, a fountain in a courtyard and the sea beyond them are three draws, and with one
+ * buffer rewritten between them all three read whatever was written last: `queue.write*` calls are
+ * ordered on the queue timeline and the encoder is submitted after every one of them, so the
+ * picture is every body wearing the last one's extents, level and colour. That is the hazard
+ * `UniformRing` exists for, recorded in `AGENTS.md` on 2026-08-27, and water was the pass still
+ * carrying it — invisible for as long as no scene drew two, which is exactly how the joint palette
+ * survived eight releases.
+ *
+ * WebGL2 needs none of this: it sets uniforms and draws in one stream. Per the 2026-08-13 rule
+ * that makes it a binder's problem here and not a decision anybody has to take twice.
+ */
+export declare function createWaterBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/**
+ * The bind group over both rings and the mirror.
+ *
+ * **One mirror serves every body, and that is correct rather than a limit worked around.** The
+ * frame renders at most one planar reflection, at one plane height; `reflectionFor` hands it to the
+ * body whose level matches and hands nothing to the rest, which then draw with
+ * `uReflectionEnabled` at zero and never sample the view this group still holds.
+ */
+export declare function createWaterBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perFrame: GPUBuffer, reflection: GPUTextureView, sampler: GPUSampler): GPUBindGroup;
+/**
+ * The water pipeline.
+ *
+ * **Blended, and culling off.** `renderer.ts` brackets the draw with
+ * `SRC_ALPHA, ONE_MINUS_SRC_ALPHA` and `gl.disable(gl.CULL_FACE)` — the second because waves
+ * are displaced far enough that back faces show at grazing angles, which is a surface you can
+ * see the underside of rather than a winding mistake.
+ *
+ * **Depth tested and not written**, which is what a transparent surface wants: it must not
+ * occlude what comes after it, and it must still be occluded by what came before.
+ */
+export declare function waterPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

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

@@ -0,0 +1,160 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { WATER_BINDINGS, WATER_FRAG_WGSL, WATER_VERT_WGSL, } from '../../shaders/generated/water.wgsl.js';
+import { PATCH_RESOLUTION, buildUnitSheet, buildWaterGrid } from '../../waterGrid.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The water pass: two sheets and a patch, displaced by a wave field in the vertex stage.
+ *
+ * **One vertex attribute for the whole surface.** `aGrid` is a `vec2` of grid coordinates and
+ * everything else — height, normal, crest, the reflection's clip position — is computed from
+ * it. So the geometry here is a buffer of pairs and an index list, and the interesting part is
+ * entirely in the shader and the uniforms.
+ */
+export const WATER_VERT_FIELDS = WATER_BINDINGS.WATER_VERT.fields;
+export const WATER_VERT_SIZE = WATER_BINDINGS.WATER_VERT.uniformSize;
+export const WATER_FRAG_FIELDS = WATER_BINDINGS.WATER_FRAG.fields;
+export const WATER_FRAG_SIZE = WATER_BINDINGS.WATER_FRAG.uniformSize;
+const VERT_BINDING = WATER_BINDINGS.WATER_VERT.uniforms;
+const FRAG_BINDING = WATER_BINDINGS.WATER_FRAG.uniforms;
+const REFLECTION = WATER_BINDINGS.WATER_FRAG.textures.uReflectionMap;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+export function createGpuWater(device, resolution, nearExtent, farHalfExtent, reflectionFilterTaps) {
+    const upload = (offsets, indices, label) => {
+        const buffer = device.createBuffer({
+            label: `${label}.offsets`,
+            size: Math.max(4, offsets.byteLength),
+            usage: USAGE_VERTEX,
+        });
+        device.queue.writeBuffer(buffer, 0, offsets);
+        const index = device.createBuffer({
+            label: `${label}.indices`,
+            size: Math.max(4, indices.byteLength),
+            usage: USAGE_INDEX,
+        });
+        device.queue.writeBuffer(index, 0, indices);
+        return { buffer, index, count: indices.length };
+    };
+    const grid = buildWaterGrid(resolution, nearExtent, farHalfExtent);
+    const sheet = upload(grid.offsets, grid.indices, 'water.sheet');
+    const unit = buildUnitSheet(PATCH_RESOLUTION);
+    const patch = upload(unit.offsets, unit.indices, 'water.patch');
+    return {
+        sheet,
+        patch,
+        cellSize: grid.cellSize,
+        nearHalfExtent: grid.nearHalfExtent,
+        farHalfExtent: grid.farHalfExtent,
+        reflectionFilterTaps,
+        dispose() {
+            sheet.buffer.destroy();
+            sheet.index.destroy();
+            patch.buffer.destroy();
+            patch.index.destroy();
+        },
+    };
+}
+export function waterVertexLayouts() {
+    return [
+        {
+            arrayStride: 2 * 4,
+            stepMode: 'vertex',
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' }],
+        },
+    ];
+}
+/**
+ * The water bind group's layout, whose two buffers are addressed by a dynamic offset.
+ *
+ * **A frame draws more than one body of water and this is what makes that true here.** A ditch at
+ * its own level, a fountain in a courtyard and the sea beyond them are three draws, and with one
+ * buffer rewritten between them all three read whatever was written last: `queue.write*` calls are
+ * ordered on the queue timeline and the encoder is submitted after every one of them, so the
+ * picture is every body wearing the last one's extents, level and colour. That is the hazard
+ * `UniformRing` exists for, recorded in `AGENTS.md` on 2026-08-27, and water was the pass still
+ * carrying it — invisible for as long as no scene drew two, which is exactly how the joint palette
+ * survived eight releases.
+ *
+ * WebGL2 needs none of this: it sets uniforms and draws in one stream. Per the 2026-08-13 rule
+ * that makes it a binder's problem here and not a decision anybody has to take twice.
+ */
+export function createWaterBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'water.layout',
+        entries: [
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: WATER_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: WATER_FRAG_SIZE },
+            },
+            { binding: REFLECTION.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+            { binding: REFLECTION.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+        ],
+    });
+}
+/**
+ * The bind group over both rings and the mirror.
+ *
+ * **One mirror serves every body, and that is correct rather than a limit worked around.** The
+ * frame renders at most one planar reflection, at one plane height; `reflectionFor` hands it to the
+ * body whose level matches and hands nothing to the rest, which then draw with
+ * `uReflectionEnabled` at zero and never sample the view this group still holds.
+ */
+export function createWaterBindGroup(device, layout, perDraw, perFrame, reflection, sampler) {
+    return device.createBindGroup({
+        label: 'water.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: perDraw, size: WATER_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: perFrame, size: WATER_FRAG_SIZE } },
+            { binding: REFLECTION.texture, resource: reflection },
+            { binding: REFLECTION.sampler, resource: sampler },
+        ],
+    });
+}
+/**
+ * The water pipeline.
+ *
+ * **Blended, and culling off.** `renderer.ts` brackets the draw with
+ * `SRC_ALPHA, ONE_MINUS_SRC_ALPHA` and `gl.disable(gl.CULL_FACE)` — the second because waves
+ * are displaced far enough that back faces show at grazing angles, which is a surface you can
+ * see the underside of rather than a winding mistake.
+ *
+ * **Depth tested and not written**, which is what a transparent surface wants: it must not
+ * occlude what comes after it, and it must still be occluded by what came before.
+ */
+export function waterPipeline(cache, device, layout) {
+    return cache.get('water', () => ({
+        label: 'water',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'water.vert', code: WATER_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: waterVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'water.frag', code: WATER_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: {
+                        color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

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

@@ -0,0 +1,46 @@
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The wind-streak pass: a lattice of debris that follows the camera and wraps.
+ *
+ * **Nothing here is per frame except ten uniforms.** The whole effect lives in the vertex
+ * shader — a particle's place comes from its index and the clock, and the box it sits in wraps
+ * around the camera — so there is no spawning, no pooling and no upload once the lattice is
+ * built.
+ *
+ * Blended over what is behind it rather than added, because dust in air occludes: this is the
+ * one effect in this backend that is neither opaque nor additive.
+ */
+export declare const WIND_STREAK_VERT_FIELDS: UniformFields;
+export declare const WIND_STREAK_VERT_SIZE: 128;
+export declare const WIND_STREAK_FRAG_FIELDS: UniformFields;
+export declare const WIND_STREAK_FRAG_SIZE: 16;
+/** A lattice on the device, behind the surface's opaque handle. */
+export interface GpuWindStreaks {
+    readonly corners: GPUBuffer;
+    readonly indices: GPUBuffer;
+    readonly vertexCount: number;
+    readonly cellSize: number;
+    readonly count: number;
+    readonly onsetSpeed: number;
+    readonly fullSpeed: number;
+    dispose(): void;
+}
+export declare function createGpuWindStreaks(device: GPUDevice, count: number, cellSize: number, onsetSpeed: number, fullSpeed: number): GpuWindStreaks;
+/**
+ * `aCorner` and `aIndex`, one buffer each, matching what `WindStreakRenderer` binds.
+ *
+ * Not interleaved, because they are two separate arrays on both sides and two of eight slots is
+ * nothing. The flat pass interleaves only because ten attributes will not fit.
+ */
+export declare function windStreakVertexLayouts(): GPUVertexBufferLayout[];
+export declare function createWindStreakBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createWindStreakBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written, nothing culled.** A streak is a two-sided
+ * card carried past the camera at any angle, so culling it would drop half of them for no
+ * saving; writing depth would let a translucent smear occlude whatever is drawn after it.
+ */
+export declare function windStreakPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;