@driftengine/core 3.61.0

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

@@ -0,0 +1,114 @@
+import { PANEL_BINDINGS, PANEL_FRAG_WGSL, PANEL_VERT_WGSL, } from '../../shaders/generated/panel.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The panel pass: two triangles in screen space, one colour, one alpha.
+ *
+ * The plain surface an overlay is read against — what `renderer.ts` says about `fillPanel`
+ * applies here unchanged, including why neither `beginInset` nor a plate of glyph cubes can
+ * stand in for it.
+ *
+ * **The corners are a vertex buffer rather than `vertex_index` arithmetic**, because the GLSL
+ * is the source of truth and it declares `aCorner`. Six vertices, uploaded once.
+ */
+export const PANEL_VERT_FIELDS = PANEL_BINDINGS.PANEL_VERT.fields;
+export const PANEL_VERT_SIZE = PANEL_BINDINGS.PANEL_VERT.uniformSize;
+export const PANEL_FRAG_FIELDS = PANEL_BINDINGS.PANEL_FRAG.fields;
+export const PANEL_FRAG_SIZE = PANEL_BINDINGS.PANEL_FRAG.uniformSize;
+const VERT_BINDING = PANEL_BINDINGS.PANEL_VERT.uniforms;
+const FRAG_BINDING = PANEL_BINDINGS.PANEL_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+/** The unit quad, as two triangles. The rect and the viewport turn it into pixels. */
+const CORNERS = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1]);
+export const PANEL_VERTEX_COUNT = CORNERS.length / 2;
+export function createPanelCorners(device) {
+    const buffer = device.createBuffer({
+        label: 'panel.corners',
+        size: CORNERS.byteLength,
+        usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(buffer, 0, CORNERS);
+    return buffer;
+}
+export function createPanelBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'panel.layout',
+        entries: [
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PANEL_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PANEL_FRAG_SIZE },
+            },
+        ],
+    });
+}
+/**
+ * Bound once against both rings, and addressed by dynamic offset per panel.
+ *
+ * **A ring rather than one buffer, because a frame draws more than one.** The loader alone
+ * draws a track and a fill, and `queue.writeBuffer` does not interleave with recorded commands
+ * — so a single block written twice would give both panels the second colour. That is the bug
+ * that left a flame leaning forty degrees in still air, one pass higher up.
+ */
+export function createPanelBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'panel.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: PANEL_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: PANEL_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Nothing culled, nothing depth-tested, nothing written to depth.** This is furniture drawn
+ * over a finished frame: it must neither be occluded by the scene nor occlude what comes after
+ * it. `renderer.ts` disables all three by hand for the same draw, and records that leaving
+ * culling on drew nothing at all, silently — a screen-space quad has no meaningful facing.
+ */
+export function panelPipeline(cache, device, layout) {
+    return cache.get('panel', () => ({
+        label: 'panel',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'panel.vert', code: PANEL_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: [
+                {
+                    arrayStride: 8,
+                    attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' }],
+                },
+            ],
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'panel.frag', code: PANEL_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: 'none' },
+        multisample: { count: cache.sampleCount },
+        /*
+         * `always` is how a WebGPU pipeline says what `gl.disable(DEPTH_TEST)` says. The attachment
+         * is still declared because the frame's pass has one, and a pipeline that omits it cannot
+         * be used in a pass that has one.
+         */
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: 'always' },
+    }));
+}

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

@@ -0,0 +1,89 @@
+import { type ParticleMaterial } from '../../particleMaterial.ts';
+import type { ParticleInstances } from '../../particlePool.ts';
+import type { ParticleBlend, ParticleFacing } from '../../particleBatch.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import type { UniformFields } from './scatterPass.ts';
+/**
+ * The particle pass: a crossed pair of quads per live particle, rebuilt every frame.
+ *
+ * **The one pass here whose per-instance data changes entirely every frame**, which is what
+ * separates it from `scatter`: foliage is placed once and never touched, and a particle system
+ * has nothing that survives a tick.
+ */
+export declare const PARTICLE_VERT_FIELDS: UniformFields;
+export declare const PARTICLE_VERT_SIZE: 96;
+/** Each material's own fragment block; the three are very different sizes. */
+export declare function particleFragBindings(material: ParticleMaterial): {
+    fields: UniformFields;
+    size: number;
+};
+export declare function particleVertexLayouts(): GPUVertexBufferLayout[];
+/** A particle pool on the device, behind the surface's opaque handle. */
+export interface GpuParticles {
+    readonly corners: GPUBuffer;
+    readonly instances: GPUBuffer;
+    readonly indexBuffer: GPUBuffer;
+    readonly capacity: number;
+    readonly material: ParticleMaterial;
+    readonly blend: ParticleBlend;
+    readonly stretchSec: number;
+    /** One camera-facing quad, or the world-fixed cross. See `ParticleBatchOptions.facing`. */
+    readonly facing: ParticleFacing;
+    readonly erosion: number;
+    readonly coreGain: number;
+    /** Whether the mote fragment stage mixes toward the medium. Ignored by the other materials. */
+    readonly fog: boolean;
+    /** Reused every frame; see `packInstances`. */
+    readonly staging: Float32Array;
+    /**
+     * This batch's own uniform buffers, staging and bind group — never shared with another
+     * batch of the same material. See the note on `createGpuParticles` for why: two pools of one
+     * material legitimately want different `fog`/`erosion`/`coreGain`, and a buffer shared
+     * between them would let one draw's `writeBuffer` overwrite what the other's draw call reads.
+     */
+    readonly vertUniforms: GPUBuffer;
+    readonly fragUniforms: GPUBuffer;
+    readonly vertStaging: ArrayBuffer;
+    readonly vertFloats: Float32Array;
+    readonly fragStaging: ArrayBuffer;
+    readonly fragFloats: Float32Array;
+    readonly fragInts: Int32Array;
+    readonly fields: UniformFields;
+    readonly bindGroup: GPUBindGroup;
+    dispose(): void;
+}
+/**
+ * **Every batch gets its own uniform buffers and bind group, not one shared per material.**
+ *
+ * They used to be shared, cached once per material and reused by every batch that named it —
+ * fine on WebGL2, where `gl.uniform*` and `gl.draw*` run synchronously in call order, so a
+ * shared uniform location always holds the value the draw right after it wrote. WebGPU's
+ * queue has no such guarantee across *two draws in one frame*: every `drawParticles` call here
+ * records into the same open encoder and calls `device.queue.writeBuffer` immediately, but the
+ * encoder is not submitted until `endFrame`, so every `writeBuffer` targeting one shared buffer
+ * completes before the submitted command buffer runs at all — by the time any of that buffer's
+ * draws execute on the GPU, the buffer holds only the *last* JS-side write, not the value each
+ * draw call thought it was setting. Two `'mote'` batches in one frame — a near field left
+ * `fog` unset and a far one at `{ fog: true }`, exactly what this material exists to let a
+ * caller ask for — drew identically, both taking whichever batch's uniforms happened to be
+ * written last. `layout` still comes from the caller and is shared per material: it is
+ * structural, not data, so nothing about sharing it can go stale mid-frame.
+ */
+export declare function createGpuParticles(device: GPUDevice, capacity: number, material: ParticleMaterial, blend: ParticleBlend, stretchSec: number, facing: ParticleFacing, erosion: number, coreGain: number, fog: boolean, layout: GPUBindGroupLayout, fragFields: UniformFields, fragSize: number): GpuParticles;
+/**
+ * Interleave the live prefix of eight streams into the batch's own staging array.
+ *
+ * Only `data.count` particles, which is what the pool's compaction guarantees is live, and
+ * into an array allocated with the batch — the frame loop may not allocate.
+ */
+export declare function packInstances(batch: GpuParticles, data: ParticleInstances): number;
+export declare function createParticleBindGroupLayout(device: GPUDevice, fragSize: number): GPUBindGroupLayout;
+export declare function createParticleBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perFrame: GPUBuffer, fragSize: number): GPUBindGroup;
+/**
+ * The pipeline for one material and blend.
+ *
+ * **Neither material writes depth**, which `particleBatch.ts` explains: a soft particle that
+ * did would punch a hole in everything drawn after it. Additive for sparks, over for smoke,
+ * the same pairing the plume pass makes.
+ */
+export declare function particlePipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, material: ParticleMaterial, blend: ParticleBlend): GPURenderPipeline;

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

@@ -0,0 +1,280 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { particleShaders } from '../../particleMaterial.js';
+import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.js';
+import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The particle pass: a crossed pair of quads per live particle, rebuilt every frame.
+ *
+ * **The one pass here whose per-instance data changes entirely every frame**, which is what
+ * separates it from `scatter`: foliage is placed once and never touched, and a particle system
+ * has nothing that survives a tick.
+ */
+export const PARTICLE_VERT_FIELDS = PARTICLE_BINDINGS.PARTICLE_VERT.fields;
+export const PARTICLE_VERT_SIZE = PARTICLE_BINDINGS.PARTICLE_VERT.uniformSize;
+const VERT_BINDING = PARTICLE_BINDINGS.PARTICLE_VERT.uniforms;
+const FRAG_BINDING = PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG.uniforms;
+/** Each material's own fragment block; the three are very different sizes. */
+export function particleFragBindings(material) {
+    const stage = material === 'spark'
+        ? PARTICLE_BINDINGS.PARTICLE_SPARK_FRAG
+        : material === 'mote'
+            ? PARTICLE_BINDINGS.PARTICLE_MOTE_FRAG
+            : PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG;
+    return { fields: stage.fields, size: stage.uniformSize };
+}
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
+/**
+ * Ten attributes and eight slots, so the per-instance eight share one buffer.
+ *
+ * **`maxVertexBuffers` is eight and this shader declares ten inputs**, so something has to
+ * interleave. The per-instance streams are the ones that do: the engine holds them as eight
+ * separate arrays and they are packed into one interleaved buffer per frame, which is a copy
+ * the upload was already paying per stream rather than new work.
+ *
+ * Floats per instance, in the order they are packed: position 3, size 1, spin 1, colour 3,
+ * alpha 1, age 1, seed 1, velocity 3.
+ */
+const INSTANCE_FLOATS = 14;
+const INSTANCE_ATTRIBUTES = [
+    { shaderLocation: 2, offset: 0, format: 'float32x3' },
+    { shaderLocation: 3, offset: 12, format: 'float32' },
+    { shaderLocation: 4, offset: 16, format: 'float32' },
+    { shaderLocation: 5, offset: 20, format: 'float32x3' },
+    { shaderLocation: 6, offset: 32, format: 'float32' },
+    { shaderLocation: 7, offset: 36, format: 'float32' },
+    { shaderLocation: 8, offset: 40, format: 'float32' },
+    { shaderLocation: 9, offset: 44, format: 'float32x3' },
+];
+export function particleVertexLayouts() {
+    return [
+        {
+            /* The cross itself: two floats of corner and one of blade index, built once. */
+            arrayStride: 12,
+            stepMode: 'vertex',
+            attributes: [
+                { shaderLocation: 0, offset: 0, format: 'float32x2' },
+                { shaderLocation: 1, offset: 8, format: 'float32' },
+            ],
+        },
+        {
+            arrayStride: INSTANCE_FLOATS * 4,
+            stepMode: 'instance',
+            attributes: INSTANCE_ATTRIBUTES,
+        },
+    ];
+}
+/**
+ * **Every batch gets its own uniform buffers and bind group, not one shared per material.**
+ *
+ * They used to be shared, cached once per material and reused by every batch that named it —
+ * fine on WebGL2, where `gl.uniform*` and `gl.draw*` run synchronously in call order, so a
+ * shared uniform location always holds the value the draw right after it wrote. WebGPU's
+ * queue has no such guarantee across *two draws in one frame*: every `drawParticles` call here
+ * records into the same open encoder and calls `device.queue.writeBuffer` immediately, but the
+ * encoder is not submitted until `endFrame`, so every `writeBuffer` targeting one shared buffer
+ * completes before the submitted command buffer runs at all — by the time any of that buffer's
+ * draws execute on the GPU, the buffer holds only the *last* JS-side write, not the value each
+ * draw call thought it was setting. Two `'mote'` batches in one frame — a near field left
+ * `fog` unset and a far one at `{ fog: true }`, exactly what this material exists to let a
+ * caller ask for — drew identically, both taking whichever batch's uniforms happened to be
+ * written last. `layout` still comes from the caller and is shared per material: it is
+ * structural, not data, so nothing about sharing it can go stale mid-frame.
+ */
+export function createGpuParticles(device, capacity, material, blend, stretchSec, facing, erosion, coreGain, fog, layout, fragFields, fragSize) {
+    /* The cross, built once: two blades of four corners, interleaved with the blade index. */
+    const corners = new Float32Array(PARTICLE_VERTS * 3);
+    const CORNERS = [
+        [-1, -1],
+        [1, -1],
+        [1, 1],
+        [-1, 1],
+    ];
+    const indices = new Uint32Array(PARTICLE_INDICES);
+    for (let b = 0; b < PARTICLE_BLADES; b++) {
+        for (let c = 0; c < 4; c++) {
+            const v = b * 4 + c;
+            const corner = CORNERS[c];
+            corners[v * 3] = corner[0];
+            corners[v * 3 + 1] = corner[1];
+            corners[v * 3 + 2] = b;
+        }
+        const base = b * 4;
+        const i = b * 6;
+        indices[i] = base;
+        indices[i + 1] = base + 1;
+        indices[i + 2] = base + 2;
+        indices[i + 3] = base;
+        indices[i + 4] = base + 2;
+        indices[i + 5] = base + 3;
+    }
+    const cornerBuffer = device.createBuffer({
+        label: 'particle.corners',
+        size: corners.byteLength,
+        usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(cornerBuffer, 0, corners);
+    const instances = device.createBuffer({
+        label: 'particle.instances',
+        size: Math.max(4, capacity * INSTANCE_FLOATS * 4),
+        usage: USAGE_VERTEX,
+    });
+    const indexBuffer = device.createBuffer({
+        label: 'particle.indices',
+        size: indices.byteLength,
+        usage: USAGE_INDEX,
+    });
+    device.queue.writeBuffer(indexBuffer, 0, indices);
+    /* This batch's own uniform buffers and bind group — see the doc comment above for why they
+       may not be shared with any other batch, including another one of the same material. */
+    const vertUniforms = device.createBuffer({
+        label: `particle.vert:${material}`,
+        size: PARTICLE_VERT_SIZE,
+        usage: USAGE_UNIFORM_DST,
+    });
+    const fragUniforms = device.createBuffer({
+        label: `particle.frag:${material}`,
+        size: fragSize,
+        usage: USAGE_UNIFORM_DST,
+    });
+    const vertStaging = new ArrayBuffer(PARTICLE_VERT_SIZE);
+    const fragStaging = new ArrayBuffer(fragSize);
+    return {
+        corners: cornerBuffer,
+        instances,
+        indexBuffer,
+        capacity,
+        material,
+        blend,
+        stretchSec,
+        facing,
+        erosion,
+        coreGain,
+        fog,
+        staging: new Float32Array(capacity * INSTANCE_FLOATS),
+        vertUniforms,
+        fragUniforms,
+        vertStaging,
+        vertFloats: new Float32Array(vertStaging),
+        fragStaging,
+        fragFloats: new Float32Array(fragStaging),
+        fragInts: new Int32Array(fragStaging),
+        fields: fragFields,
+        bindGroup: createParticleBindGroup(device, layout, vertUniforms, fragUniforms, fragSize),
+        dispose() {
+            cornerBuffer.destroy();
+            instances.destroy();
+            indexBuffer.destroy();
+            vertUniforms.destroy();
+            fragUniforms.destroy();
+        },
+    };
+}
+/**
+ * Interleave the live prefix of eight streams into the batch's own staging array.
+ *
+ * Only `data.count` particles, which is what the pool's compaction guarantees is live, and
+ * into an array allocated with the batch — the frame loop may not allocate.
+ */
+export function packInstances(batch, data) {
+    const n = Math.min(data.count, batch.capacity);
+    const out = batch.staging;
+    for (let i = 0; i < n; i++) {
+        const o = i * INSTANCE_FLOATS;
+        const p = i * 3;
+        out[o] = data.positions[p];
+        out[o + 1] = data.positions[p + 1];
+        out[o + 2] = data.positions[p + 2];
+        out[o + 3] = data.sizes[i];
+        out[o + 4] = data.spins[i];
+        out[o + 5] = data.colors[p];
+        out[o + 6] = data.colors[p + 1];
+        out[o + 7] = data.colors[p + 2];
+        out[o + 8] = data.alphas[i];
+        out[o + 9] = data.ages[i];
+        out[o + 10] = data.seeds[i];
+        out[o + 11] = data.velocities[p];
+        out[o + 12] = data.velocities[p + 1];
+        out[o + 13] = data.velocities[p + 2];
+    }
+    return n;
+}
+export function createParticleBindGroupLayout(device, fragSize) {
+    return device.createBindGroupLayout({
+        label: 'particle.layout',
+        entries: [
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', minBindingSize: PARTICLE_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', minBindingSize: fragSize },
+            },
+        ],
+    });
+}
+export function createParticleBindGroup(device, layout, perDraw, perFrame, fragSize) {
+    return device.createBindGroup({
+        label: 'particle.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: perDraw, size: PARTICLE_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: perFrame, size: fragSize } },
+        ],
+    });
+}
+/**
+ * The pipeline for one material and blend.
+ *
+ * **Neither material writes depth**, which `particleBatch.ts` explains: a soft particle that
+ * did would punch a hole in everything drawn after it. Additive for sparks, over for smoke,
+ * the same pairing the plume pass makes.
+ */
+export function particlePipeline(cache, device, layout, material, blend) {
+    const shaders = particleShaders(material);
+    return cache.get(`particle:${material}:${blend}`, () => ({
+        label: `particle:${material}`,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'particle.vert', code: shaders.vertexWgsl }),
+            entryPoint: 'main',
+            buffers: particleVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, {
+                label: `particle.frag:${material}`,
+                code: shaders.fragmentWgsl,
+            }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: blend === 'additive'
+                        ? {
+                            color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                            alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+                        }
+                        : {
+                            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: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Render pipelines, built once and looked up by name.
+ *
+ * **Pipeline creation is the expensive operation in WebGPU** — it compiles shaders and
+ * validates state — and `AGENTS.md` forbids allocating in a per-frame path. So a pipeline is
+ * built once per distinct state and found by a string key thereafter.
+ *
+ * The key is the caller's to build, and it must be built at construction time rather than
+ * per frame. A key assembled with template interpolation inside a draw call allocates a
+ * string sixty times a second for every draw, which is the allocation this class exists to
+ * avoid, moved rather than removed.
+ */
+export declare class PipelineCache {
+    /**
+     * The colour format every pipeline here targets, which is wherever the *world* lands.
+     *
+     * **Not the swap chain's, and the difference is the whole point.** Under a composite the world
+     * is drawn into the scene target and only the resolve reaches the canvas, so a pipeline built
+     * against the swap chain disagrees with its attachment — which WebGPU raises at `finish`,
+     * dropping the frame's entire command buffer. Carried here for the same reason `sampleCount`
+     * is: one number, read by every `describe` callback, so no pass can disagree with the target
+     * it is about to be used on. `webgpu/renderer.ts` chooses it, once.
+     */
+    readonly format: GPUTextureFormat;
+    /**
+     * How many samples every pipeline here rasterises at.
+     *
+     * **Carried by the cache so no pipeline can disagree with the attachment.** A pipeline's
+     * sample count must equal the colour target's exactly, and WebGPU rejects the mismatch at
+     * draw time with a message about the pipeline rather than about the target — so a pass that
+     * forgot to ask would fail somewhere other than where the mistake was made. One number, read
+     * by every `describe` callback.
+     */
+    readonly sampleCount: number;
+    private readonly device;
+    private readonly pipelines;
+    /**
+     * Builds still compiling, by key, so two asks for one pipeline share a compile.
+     *
+     * **`createRenderPipeline` does not compile, it defers.** It returns in microseconds and
+     * leaves the driver to finish the shader the first time something draws with it, which puts
+     * the cost inside a frame instead of before one. Measured on an S23 Ultra: twelve pipelines
+     * "built" in 3ms, then seven submits in a row each taking 5.2 seconds and all draining
+     * together, with no allocation, no long task and an idle main thread the whole time. The
+     * queue was blocked on compilation nobody had asked for yet.
+     *
+     * `createRenderPipelineAsync` is the API that exists for this. It compiles across the
+     * driver's own threads and resolves when the pipeline is genuinely ready, so a renderer can
+     * wait for readiness rather than discovering it mid-frame.
+     */
+    private readonly compiling;
+    constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number);
+    /** How many distinct pipelines have been built. Read by tests and diagnostics. */
+    get size(): number;
+    /**
+     * The pipeline for this key, compiled off the main thread.
+     *
+     * Preferred wherever the caller is not inside a frame, which `get`'s own contract says is
+     * everywhere: pipelines are built once per distinct state at construction time. The
+     * difference is only *when* the driver does the work, and that difference is the whole bug
+     * this exists for.
+     */
+    getAsync(key: string, describe: () => GPURenderPipelineDescriptor): Promise<GPURenderPipeline>;
+    /**
+     * Resolve once every pipeline asked for so far has finished compiling.
+     *
+     * A renderer awaits this before its first frame, which is what moves the compile out of the
+     * queue and in front of it. A failure is not rethrown: a pipeline that cannot be built will
+     * fail again, loudly, at the draw that needs it, and taking the whole boot down here would
+     * turn one broken material into a blank page.
+     */
+    ready(): Promise<void>;
+    /** The pipeline for this key if it is already built, without building one. */
+    peek(key: string): GPURenderPipeline | undefined;
+    /** How many are still compiling. Read by tests and diagnostics. */
+    get compilingCount(): number;
+    /**
+     * The pipeline for this key, building it on the first ask only.
+     *
+     * `describe` is a callback rather than a value because **building the descriptor allocates
+     * too**: a nested object with vertex buffer layouts and blend state, constructed to be
+     * thrown away on every hit. Passing a function means a hit costs one `Map` lookup.
+     */
+    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+    /**
+     * Drop every pipeline.
+     *
+     * WebGPU has no explicit pipeline release — they are freed when nothing references them —
+     * so this is about not handing out pipelines belonging to a destroyed device rather than
+     * about reclaiming memory here and now.
+     */
+    dispose(): void;
+}