@driftengine/core 3.61.0

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

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function createGpuSurface(canvas, device) {
+    const context = canvas.getContext('webgpu');
+    if (context === null) {
+        throw new Error('createGpuSurface: the canvas would not give a webgpu context');
+    }
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    const listeners = [];
+    let lost = false;
+    let disposed = false;
+    void device.lost.then(() => {
+        if (disposed)
+            return;
+        lost = true;
+        for (const listener of listeners)
+            listener();
+    });
+    /*
+     * **Say what the device rejected, because otherwise nothing does.**
+     *
+     * WebGPU does not throw on a bad resource. `createBindGroup` with a mismatched sample type
+     * returns an object that is invalid, every pass built on it records nothing, and the frame
+     * still presents — so the failure arrives as a picture that is merely wrong, and gets
+     * attributed to shaders, matrices and orientation in that order. That is not hypothetical:
+     * the shadow peel cost three implementations across two sessions, all of them measuring the
+     * frame produced by a pass that could not run, and one line of this would have named it.
+     * The water shader's invalid pipeline was the same silence.
+     *
+     * **Measured, because when it arrives decides whether it is any use.** Making the peel's
+     * exact mistake and listening gives *nothing* at `createBindGroup` — Dawn defers it — and
+     * then three messages at `queue.submit`, root cause first:
+     *
+     *     None of the supported sample types (UnfilterableFloat|Depth) of
+     *       [Texture "shadow.static"] match the expected sample types (Float).
+     *     [Invalid BindGroup (unlabeled)] is invalid due to a previous error.
+     *     [Invalid CommandBuffer] is invalid due to a previous error.
+     *
+     * So the useful line is there, and it is there a frame later than the call that caused it.
+     * **Label every resource**, because that first message is only readable thanks to
+     * `shadow.static` being one.
+     *
+     * `console.error` rather than a throw, and for that reason: submission is inside the frame
+     * loop, and the house rule is that nothing throws there. Once per distinct message, because
+     * an invalid bind group set per draw arrives every frame — the same argument `warnedFull`
+     * makes in the renderer.
+     */
+    const said = new Set();
+    device.addEventListener('uncapturederror', (event) => {
+        const { error } = event;
+        const message = error.message;
+        if (disposed || said.has(message))
+            return;
+        said.add(message);
+        console.error(`[driftengine] the GPU rejected something, and drew nothing for it:\n${message}`);
+    });
+    const configure = (width, height) => {
+        if (disposed)
+            return;
+        canvas.width = width;
+        canvas.height = height;
+        /*
+         * `opaque` rather than `premultiplied`: this engine draws a sky behind everything and
+         * has no use for a transparent canvas, and the opaque path is the one a compositor can
+         * take without a blend.
+         */
+        context.configure({ device, format, alphaMode: 'opaque' });
+    };
+    configure(canvas.width, canvas.height);
+    return {
+        device,
+        context,
+        canvas,
+        format,
+        get lost() {
+            return lost;
+        },
+        onLost(listener) {
+            /* Late is the normal case for a renderer built after a driver reset, not an edge one. */
+            if (lost) {
+                listener();
+                return;
+            }
+            listeners.push(listener);
+        },
+        configure,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            listeners.length = 0;
+            context.unconfigure();
+            device.destroy();
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * One recorded draw, in the only shape this backend ever issues.
+ *
+ * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
+ * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
+ * drawn except the values.
+ *
+ * So the frame graph does not need to know what a plume is. It records these fields and
+ * replays them, which is what turns migrating twenty-three verbs into twenty-three call-site
+ * edits rather than twenty-three implementations.
+ */
+export interface DrawCommand {
+    pipeline: GPURenderPipeline | null;
+    bindGroup: GPUBindGroup | null;
+    /** Dynamic offsets, held as two numbers rather than an array so a reset stays free. */
+    offsetA: number;
+    offsetB: number;
+    offsetCount: number;
+    /** Fixed length; `vertexCount` says how many slots are live. */
+    readonly vertexBuffers: (GPUBuffer | null)[];
+    vertexCount: number;
+    indexBuffer: GPUBuffer | null;
+    indexed: boolean;
+    count: number;
+    instances: number;
+}
+export interface CommandPool {
+    commands: DrawCommand[];
+    taken: number;
+    /** The most any frame has taken, so growth converges instead of repeating. */
+    highWater: number;
+}
+export declare function createCommandPool(capacity: number): CommandPool;
+/**
+ * Hand out the next command, growing if a frame overruns.
+ *
+ * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
+ * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ */
+export declare function takeCommand(pool: CommandPool): number;
+/** Empty the pool for a new frame. Keeps every entry; that is the whole point. */
+export declare function resetPool(pool: CommandPool): void;

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

@@ -0,0 +1,54 @@
+/**
+ * One recorded draw, in the only shape this backend ever issues.
+ *
+ * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
+ * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
+ * drawn except the values.
+ *
+ * So the frame graph does not need to know what a plume is. It records these fields and
+ * replays them, which is what turns migrating twenty-three verbs into twenty-three call-site
+ * edits rather than twenty-three implementations.
+ */
+/** The most vertex buffers any verb on this backend binds is three. Four leaves a margin. */
+const VERTEX_BUFFER_SLOTS = 4;
+function emptyCommand() {
+    return {
+        pipeline: null,
+        bindGroup: null,
+        offsetA: 0,
+        offsetB: 0,
+        offsetCount: 0,
+        vertexBuffers: new Array(VERTEX_BUFFER_SLOTS).fill(null),
+        vertexCount: 0,
+        indexBuffer: null,
+        indexed: false,
+        count: 0,
+        instances: 1,
+    };
+}
+export function createCommandPool(capacity) {
+    const commands = [];
+    for (let i = 0; i < capacity; i += 1)
+        commands.push(emptyCommand());
+    return { commands, taken: 0, highWater: 0 };
+}
+/**
+ * Hand out the next command, growing if a frame overruns.
+ *
+ * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
+ * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ */
+export function takeCommand(pool) {
+    const at = pool.taken;
+    while (at >= pool.commands.length)
+        pool.commands.push(emptyCommand());
+    pool.taken = at + 1;
+    if (pool.taken > pool.highWater)
+        pool.highWater = pool.taken;
+    return at;
+}
+/** Empty the pool for a new frame. Keeps every entry; that is the whole point. */
+export function resetPool(pool) {
+    pool.taken = 0;
+}

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

@@ -0,0 +1,28 @@
+/** Linear RGBA floats packed into whatever format the environment cube was actually allocated as. */
+/** The packed texels and how wide one is, which is what a `writeTexture` layout needs. */
+export interface PackedTexels {
+    readonly data: ArrayBufferView;
+    readonly bytesPerTexel: number;
+}
+/**
+ * Pack linear RGBA floats for `format`.
+ *
+ * **`writeTexture` does not convert, and that is the whole reason this exists.** Its `bytesPerRow`
+ * describes the *source* stride and it reads `width * bytesPerTexel-of-the-destination` bytes from
+ * each row — so float data handed to an eight-bit cube is a legal layout that reinterprets the raw
+ * bytes of the floats as unorm bytes. Nothing raises anything: no validation error, no device
+ * message, and a cube full of a plausible-looking environment.
+ *
+ * That is the 2026-08-14 family of WebGPU failure wearing its quietest face. The others at least
+ * invalidate a command buffer and leave an empty canvas; this one draws a picture.
+ *
+ * **Measured, because it was found by measuring rather than by reading.** On a uniform sky the
+ * other backend read 81 of 255 and this one read 45.7 from the same file. Neither number looks
+ * wrong on its own — the two backends being a control for each other is the only thing that
+ * separated them.
+ *
+ * **What it costs** is one conversion pass over six faces at load. **What would make it wrong** is
+ * a format this does not know, which is why the default arm throws rather than guessing: a guess
+ * here is exactly the silent picture this function exists to prevent.
+ */
+export declare function environmentTexels(pixels: Float32Array, format: GPUTextureFormat): PackedTexels;

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

@@ -0,0 +1,79 @@
+/** Linear RGBA floats packed into whatever format the environment cube was actually allocated as. */
+import { toHalfFloats } from '../../halfFloat.js';
+/**
+ * Pack linear RGBA floats for `format`.
+ *
+ * **`writeTexture` does not convert, and that is the whole reason this exists.** Its `bytesPerRow`
+ * describes the *source* stride and it reads `width * bytesPerTexel-of-the-destination` bytes from
+ * each row — so float data handed to an eight-bit cube is a legal layout that reinterprets the raw
+ * bytes of the floats as unorm bytes. Nothing raises anything: no validation error, no device
+ * message, and a cube full of a plausible-looking environment.
+ *
+ * That is the 2026-08-14 family of WebGPU failure wearing its quietest face. The others at least
+ * invalidate a command buffer and leave an empty canvas; this one draws a picture.
+ *
+ * **Measured, because it was found by measuring rather than by reading.** On a uniform sky the
+ * other backend read 81 of 255 and this one read 45.7 from the same file. Neither number looks
+ * wrong on its own — the two backends being a control for each other is the only thing that
+ * separated them.
+ *
+ * **What it costs** is one conversion pass over six faces at load. **What would make it wrong** is
+ * a format this does not know, which is why the default arm throws rather than guessing: a guess
+ * here is exactly the silent picture this function exists to prevent.
+ */
+export function environmentTexels(pixels, format) {
+    switch (format) {
+        /* Already what the source is. No copy, because there is nothing to change. */
+        case 'rgba32float':
+            return { data: pixels, bytesPerTexel: 16 };
+        case 'rgba16float':
+            return { data: toHalf(pixels), bytesPerTexel: 8 };
+        case 'rgba8unorm':
+            return { data: toUnorm(pixels, false, false), bytesPerTexel: 4 };
+        case 'bgra8unorm':
+            return { data: toUnorm(pixels, true, false), bytesPerTexel: 4 };
+        /*
+         * An sRGB view decodes what it samples, so the byte stored has to be the *encoded* value or
+         * every environment comes back roughly twice as bright as the file. The engine's own scene
+         * targets are linear, so this arm is for a surface format a device chose rather than one this
+         * renderer asked for.
+         */
+        case 'rgba8unorm-srgb':
+            return { data: toUnorm(pixels, false, true), bytesPerTexel: 4 };
+        case 'bgra8unorm-srgb':
+            return { data: toUnorm(pixels, true, true), bytesPerTexel: 4 };
+        default:
+            throw new Error(`environmentTexels: no packing for "${format}". Add one rather than letting a wrong ` +
+                'layout through — WebGPU accepts a mismatched stride without complaint and draws a ' +
+                'plausible picture from reinterpreted bytes.');
+    }
+}
+function toHalf(pixels) {
+    return toHalfFloats(pixels);
+}
+/**
+ * Eight bits a channel, clipped at white.
+ *
+ * **Clipped rather than tone-mapped**, matching what the other backend does with a non-float cube
+ * and for the reason a bake documents at length: the cube stores radiance, and a curve applied here
+ * would be a viewing transform baked into stored light.
+ */
+function toUnorm(pixels, swapRedAndBlue, encodeSrgb) {
+    const texels = pixels.length / 4;
+    const out = new Uint8Array(texels * 4);
+    for (let texel = 0; texel < texels; texel++) {
+        for (let channel = 0; channel < 3; channel++) {
+            const linear = pixels[texel * 4 + channel] ?? 0;
+            const clipped = linear <= 0 ? 0 : linear >= 1 ? 1 : linear;
+            const value = encodeSrgb ? srgbEncode(clipped) : clipped;
+            const at = texel * 4 + (swapRedAndBlue ? 2 - channel : channel);
+            out[at] = Math.round(value * 255);
+        }
+        out[texel * 4 + 3] = 255;
+    }
+    return out;
+}
+/** The sRGB transfer function, in the direction that prepares a value for a decoding sampler. */
+function srgbEncode(linear) {
+    return linear <= 0.0031308 ? linear * 12.92 : 1.055 * linear ** (1 / 2.4) - 0.055;
+}

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

@@ -0,0 +1,29 @@
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
+ *
+ * Its own pass because it is its own material: view-dependent iridescence and a dissolving
+ * edge, neither of which the flat shader can express. `renderer.ts` says the rest, including
+ * why `sheen` is iridescence rather than wetness and where its usable range is.
+ *
+ * The geometry is an ordinary mesh, so the vertex layout is the flat pass's own — the shader
+ * reads position, normal, colour and a coverage weight, and the pipeline still has to describe
+ * every attribute the module declares.
+ */
+export declare const FILM_VERT_FIELDS: UniformFields;
+export declare const FILM_VERT_SIZE: 128;
+export declare const FILM_FRAG_FIELDS: UniformFields;
+export declare const FILM_FRAG_SIZE: 144;
+export declare function createFilmBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/** Bound once against both rings; a dynamic offset per film. See `createPanelBindGroup`. */
+export declare function createFilmBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer, reflection: GPUTextureView, sampler: GPUSampler): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written.** A slick lies on the surface it was built
+ * against instead of fighting it for the depth buffer, which is what `renderer.ts` says by
+ * turning `depthMask` off around the draw. Writing depth would let a translucent patch occlude
+ * whatever is drawn after it.
+ */
+export declare function filmPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, present: Readonly<Record<string, boolean>>): GPURenderPipeline;

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

@@ -0,0 +1,97 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { FILM_BINDINGS, FILM_FRAG_WGSL, FILM_VERT_WGSL, } from '../../shaders/generated/film.wgsl.js';
+import { vertexBufferLayouts } from './buffers.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
+ *
+ * Its own pass because it is its own material: view-dependent iridescence and a dissolving
+ * edge, neither of which the flat shader can express. `renderer.ts` says the rest, including
+ * why `sheen` is iridescence rather than wetness and where its usable range is.
+ *
+ * The geometry is an ordinary mesh, so the vertex layout is the flat pass's own — the shader
+ * reads position, normal, colour and a coverage weight, and the pipeline still has to describe
+ * every attribute the module declares.
+ */
+export const FILM_VERT_FIELDS = FILM_BINDINGS.FILM_VERT.fields;
+export const FILM_VERT_SIZE = FILM_BINDINGS.FILM_VERT.uniformSize;
+export const FILM_FRAG_FIELDS = FILM_BINDINGS.FILM_FRAG.fields;
+export const FILM_FRAG_SIZE = FILM_BINDINGS.FILM_FRAG.uniformSize;
+const VERT_BINDING = FILM_BINDINGS.FILM_VERT.uniforms;
+const FRAG_BINDING = FILM_BINDINGS.FILM_FRAG.uniforms;
+const REFLECTION = FILM_BINDINGS.FILM_FRAG.textures.uReflectionMap;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+export function createFilmBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'film.layout',
+        entries: [
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FILM_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FILM_FRAG_SIZE },
+            },
+            /*
+             * The mirror is an ordinary colour target, so a filtering sampler is right here — unlike
+             * every `...ShadowMap`, which is a depth format and cannot take one. `depthPass.ts` has
+             * the message the device gives when the two are confused.
+             */
+            { binding: REFLECTION.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+            { binding: REFLECTION.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+        ],
+    });
+}
+/** Bound once against both rings; a dynamic offset per film. See `createPanelBindGroup`. */
+export function createFilmBindGroup(device, layout, vertices, fragments, reflection, sampler) {
+    return device.createBindGroup({
+        label: 'film.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: FILM_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: FILM_FRAG_SIZE } },
+            { binding: REFLECTION.texture, resource: reflection },
+            { binding: REFLECTION.sampler, resource: sampler },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written.** A slick lies on the surface it was built
+ * against instead of fighting it for the depth buffer, which is what `renderer.ts` says by
+ * turning `depthMask` off around the draw. Writing depth would let a translucent patch occlude
+ * whatever is drawn after it.
+ */
+export function filmPipeline(cache, device, layout, key, present) {
+    return cache.get(key, () => ({
+        label: key,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'film.vert', code: FILM_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: vertexBufferLayouts(present),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'film.frag', code: FILM_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: {
+                        color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'back' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

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

@@ -0,0 +1,213 @@
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The flat pipeline: the shader that draws the world.
+ *
+ * Built from the generated WGSL, with the bind group layout, the uniform sizes and every
+ * byte offset taken from the same generated file. **Nothing here restates a number the
+ * generator already knows** — a binding or an offset written twice is one that can disagree,
+ * and the disagreement draws a picture rather than raising an error.
+ *
+ * **Driven by the variant, not fixed to one.** `flatFrag` is sixteen permutations and they
+ * are not interchangeable: the one that compiles in the directional shadow path declares
+ * three more samplers and a 1,104-byte uniform block against the plain one's 1,072. Building
+ * the right shader and binding it against the wrong layout is a mistake that validates,
+ * draws, and is wrong, so the layout is derived from the variant every time.
+ */
+/** A key into `FLAT_FRAG_WGSL`: the flags that are on, sorted, joined by `+`, or `none`. */
+export type FlatVariant = string;
+/** The four flags `flatFrag` permutes on, which is what decides which of sixteen to build. */
+export interface FlatVariantFlags {
+    readonly directionalShadows: boolean;
+    readonly environmentProbe: boolean;
+    readonly nightEmissive: boolean;
+    readonly pointShadows: boolean;
+}
+/**
+ * The key for a set of flags.
+ *
+ * **The rule is `variantKey` in `scripts/wgsl.ts` and this is a second statement of it**, which
+ * is exactly the kind of restatement that drifts — except that a drift here cannot be silent:
+ * `flatFragmentBindings` throws on a key the generated table does not hold, at construction,
+ * naming the key it looked for. `scripts/` is a build tool and nothing under `src/` may import
+ * it, so a copy is the only option and a loud one is the acceptable form of it.
+ */
+export declare function flatVariant(flags: FlatVariantFlags): FlatVariant;
+/** Where one sampler's two halves ended up. */
+export interface TextureBinding {
+    readonly texture: number;
+    readonly sampler: number;
+    readonly type: string;
+}
+/** What the generator recorded about one shader stage. */
+export interface StageBindings {
+    readonly uniforms: number;
+    readonly uniformSize: number;
+    /**
+     * Byte offsets, and for an array the shape a `std140` block gives it.
+     *
+     * `length` and `stride` are present only on arrays, and `stride` is not `size / length`:
+     * every element gets its own sixteen-byte slot whatever it holds, so a `float[10]` is 160
+     * bytes. A writer that assumed packing would put ten lights in the space of two and a half
+     * and raise nothing, which is why the generator emits the number rather than leaving it to
+     * be derived.
+     */
+    readonly fields: Readonly<Record<string, {
+        readonly offset: number;
+        readonly size: number;
+        readonly length?: number;
+        readonly stride?: number;
+    }>>;
+    readonly textures: Readonly<Record<string, TextureBinding>>;
+}
+/** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
+export declare function flatVertexKey(skinned: boolean, morphed: boolean, instanced?: boolean): string;
+/** Everything the generator recorded about one variant of the vertex stage. */
+export declare function flatVertexBindings(skinned: boolean, morphed?: boolean, instanced?: boolean): StageBindings;
+export declare const FLAT_VERT_FIELDS: {
+    readonly uViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uHasTangents: {
+        readonly offset: 64;
+        readonly size: 4;
+        readonly type: "int";
+    };
+    readonly uLightViewProj: {
+        readonly offset: 80;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uUvScale: {
+        readonly offset: 144;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uModel: {
+        readonly offset: 160;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uTint: {
+        readonly offset: 224;
+        readonly size: 12;
+        readonly type: "vec3";
+    };
+    readonly uWindDirection: {
+        readonly offset: 240;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uWindSpeed: {
+        readonly offset: 248;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindGust: {
+        readonly offset: 252;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindTime: {
+        readonly offset: 256;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindSpatialPhase: {
+        readonly offset: 264;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+};
+/**
+ * The **largest** variant's block, because one ring serves every draw.
+ *
+ * A ring strided for the plain block would leave a morphed draw writing its weights into the next
+ * slot, which is a scrambled neighbour rather than an error. The unused tail on a plain draw is
+ * 144 bytes a slot and is what a single ring costs.
+ */
+export declare const FLAT_VERT_SIZE: number;
+/** Everything the generator recorded about one permutation of the fragment stage. */
+export declare function flatFragmentBindings(variant: FlatVariant): StageBindings;
+/** The depth format both backends compare with. */
+export { DEPTH_FORMAT } from '../../depthConvention.ts';
+/**
+ * The layout this variant binds against.
+ *
+ * The vertex block is **dynamic**, because every draw supplies its own model matrix and tint
+ * from its own slot of one buffer. The fragment block is not: it holds the lights, the fog
+ * and the camera, settled once by `bindMeshPass` and unchanged between draws.
+ */
+export declare function createFlatBindGroupLayout(device: GPUDevice, variant: FlatVariant, skinned?: boolean, morphed?: boolean): GPUBindGroupLayout;
+/**
+ * Bind the buffers and one view per declared texture.
+ *
+ * `resolve` is asked for a view by the shader's own name for it, so a caller supplies the
+ * shadow maps it has and a stand-in for the rest. **Every declared binding must be filled
+ * even when the shader never samples it** — `uAlbedoEnabled` is zero for nearly all geometry
+ * and WebGPU still requires something there, which is why `renderer.ts` keeps an
+ * `emptyTexture2D` for the same reason on the other side.
+ */
+export declare function createFlatBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, variant: FlatVariant, perDraw: GPUBuffer, perFrame: GPUBuffer, resolve: (name: string) => {
+    view: GPUTextureView;
+    sampler: GPUSampler;
+}, 
+/** The palette view for a skinned bind group, or null for an unskinned one. */
+palette?: GPUTextureView | null, 
+/** The delta view for a morphed bind group, or null for an unmorphed one. */
+deltas?: GPUTextureView | null): GPUBindGroup;
+/**
+ * The pipeline, cached by the state that distinguishes it.
+ *
+ * The key names the variant and which optional attributes the mesh supplied, because those
+ * two decide the fragment module and the vertex layout. Built once per mesh at construction
+ * time rather than per frame, which is the rule `PipelineCache` exists to keep.
+ */
+export declare function flatPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, variant: FlatVariant, key: string, present: Readonly<Record<string, boolean>>, 
+/**
+ * Alpha-blended, for `drawTranslucentMesh`.
+ *
+ * **A second pipeline rather than a flag on the first**, because blend state is baked into a
+ * WebGPU pipeline where WebGL2 toggles it around the draw with `gl.enable(BLEND)`. Keyed
+ * separately, so one mesh drawn both ways gets both and neither is rebuilt per frame.
+ *
+ * Depth still written, matching the other backend: `drawTranslucentMesh` there leaves
+ * `depthMask` alone and only turns blending on. A translucent part of a loaded model is a
+ * pane of glass in a solid object, not a particle, and it has to occlude what is behind it
+ * for the rest of the model to sort correctly.
+ */
+translucent?: boolean, 
+/** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
+skinned?: boolean, 
+/** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
+morphed?: boolean, 
+/**
+ * Whether this pipeline writes depth, and which coplanar layer it draws on.
+ *
+ * **Both are pipeline state here and per-draw state on the other backend**, which is why they
+ * arrive as arguments and why the caller's key has to carry them: two draws of one mesh that
+ * differ only in these would otherwise share a cached pipeline and the second would silently
+ * get the first one's depth behaviour.
+ */
+depthWrite?: boolean, depthLayer?: number, 
+/** Whether placement and tint arrive per instance. See `FlatVertexOptions`. */
+instanced?: boolean, 
+/** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
+oit?: OitTarget): GPURenderPipeline;
+/**
+ * The same pipeline, compiled off the main thread.
+ *
+ * **Preferred by everything that builds a mesh**, which is all of them: `createRenderPipeline`
+ * defers the shader compile to the first draw, so a scene that builds its meshes and then
+ * renders pays for every one of them inside a single frame. On a phone that is seconds of a
+ * blocked GPU queue with an idle main thread, which is invisible to every timer that is not
+ * this one. The descriptor is identical; only when the driver does the work changes.
+ */
+export declare function flatPipelineAsync(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, variant: FlatVariant, key: string, present: Readonly<Record<string, boolean>>, translucent?: boolean, 
+/** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
+skinned?: boolean, 
+/** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
+morphed?: boolean): Promise<GPURenderPipeline>;
+/** Which of the two order-independent buffers a pipeline writes, or neither. */
+export type OitTarget = 'none' | 'accum' | 'reveal';