@driftengine/core 3.61.0

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

@@ -0,0 +1,3082 @@
+import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Vec3 } from '../../../math/color.ts';
+import { Camera } from '../../camera.ts';
+import type { PickHit, PickableSource } from '../../pickable.ts';
+import type { RendererApi } from '../api.ts';
+import { GpuTimestamps } from './gpuTimestamps.ts';
+import type { Environment, FilmOptions, InsetRect, LightVolumeDrawOptions, SkyColors, TranslucentMeshOptions } from '../webgl2/renderer.ts';
+import type { IncrementalMeshHandle, MeshOptions } from '../api.ts';
+import type { WaterBody } from '../../waterRenderer.ts';
+import type { WindStreakOptions } from '../../windStreakRenderer.ts';
+import type { WindField } from '../../windField.ts';
+import type { FlockParams } from '../../flockRenderer.ts';
+import type { ProbeGridOptions } from '../../probeGrid.ts';
+import type { PhotometricProfile } from '../../iesProfile.ts';
+import { type AreaLightSource } from '../../areaLights.ts';
+import { type ShadowLight } from '../../pointShadowSystem.ts';
+import { GpuText } from './textPass.ts';
+import type { TextStyle } from '../../textLayout.ts';
+import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
+import { GpuSdfText } from './sdfTextPass.ts';
+import type { SdfFont } from '../../sdfFont.ts';
+import type { SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import type { RenderBackend } from '../api.ts';
+import { type ColourGradeLut } from '../../colourGrade.ts';
+import type { CausticSheet } from '../../causticsRenderer.ts';
+import { type GpuCaustics } from './causticsPass.ts';
+import type { BoltSegments } from '../../boltPool.ts';
+import type { LineSegments } from '../../linePoints.ts';
+import type { ParticleBatchOptions } from '../../particleBatch.ts';
+import type { ParticleInstances } from '../../particlePool.ts';
+import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
+import type { InstanceData } from '../../instancedMesh.ts';
+import { type RenderQuality } from '../../renderQuality.ts';
+import type { MeshData } from '../../mesh.ts';
+import type { ShadowCasters } from '../../shadowCasters.ts';
+import { type GpuMesh } from './buffers.ts';
+import type { GpuSurface } from './device.ts';
+import { type GpuScatter } from './scatterPass.ts';
+import { type GpuWater } from './waterPass.ts';
+import { type GpuPlumes } from './plumePass.ts';
+import { type GpuParticles } from './particlePass.ts';
+import { type GpuWindStreaks } from './windStreakPass.ts';
+import { type GpuFlock } from './flockPass.ts';
+import { type GpuBolts } from './boltPass.ts';
+import { type GpuLines } from './linePass.ts';
+import { FrameBudget } from '../budget.ts';
+import type { ReflectiveSurface } from '../../screenSpaceReflection.ts';
+import type { DecalProjector } from '../../decalProjector.ts';
+import type { Bounds } from '../../../math/bounds.ts';
+import { type ComputeDefinition, type ComputeHandle } from '../../compute.ts';
+import type { PassDefinition, PassHandle } from '../../pass.ts';
+import { GpuInstancedBatch } from './instanced.ts';
+import type { MeshInstances } from '../../instances.ts';
+/** Which directional shadow map a pass is filling, matching `renderer.ts`. */
+type ShadowLayer = 'static' | 'static-peel' | 'dynamic';
+/**
+ * The WebGPU backend.
+ *
+ * **`RendererApi`, in full, with no `Partial` and no cast.** It implemented
+ * `Partial<RendererApi>` for as long as its passes were being written, and the `Partial` was
+ * the schedule: every member still missing was a row of work, and `createRenderer` needed a
+ * cast to hand an incomplete backend back behind the complete surface.
+ *
+ * That is over. The derived type now does the job it exists for — add a method to `Renderer`
+ * and this class stops compiling until it has one too, which is the compile-time form of the
+ * failure the 2026-08-02 design spec named as the real risk: a fallback that rots because only
+ * the developer's own backend is ever exercised.
+ *
+ * **Present is not the same as honoured, and the reverse is a trap of its own.** `setBloom`,
+ * `setSpeedRush` and `setCameraMotionBlur` warned that the composite did not exist here, which
+ * was true when they were written and stopped being true when it landed — so the backend spent
+ * a while telling consumers that working effects did nothing. All three are read by
+ * `composite()` now, and each has been compared against WebGL2 on `demo/dev/probe.html`.
+ */
+export declare class WebGPURenderer implements RendererApi {
+    /**
+     * Real timestamp queries, where the adapter offers them.
+     *
+     * Typed as the concrete class rather than as `FrameTimer` because this file needs the two
+     * methods the interface has no room for: `writesFor`, which every `beginRenderPass` below
+     * passes into its descriptor, and `resolve`, which rides the frame's last encoder. A
+     * consumer still sees only `FrameTimer` through `RendererApi`.
+     */
+    readonly gpuTimer: GpuTimestamps;
+    /** What drew the frame, for the meter and for bug reports. */
+    readonly rendererName: string;
+    /**
+     * See `RendererApi.reversedDepth`. Always the engine's own setting on this backend: WebGPU's
+     * clip space is `[0, 1]` already, so reversing costs an extension nothing and cannot be refused.
+     */
+    readonly reversedDepth = true;
+    /** Which backend is drawing. See `Renderer.backend` for why this is asked rather than guessed. */
+    readonly backend: RenderBackend;
+    /**
+     * The profile this renderer was built against, resolved once.
+     *
+     * **Resolved by the caller and held, rather than defaulted per use.** Every shadow term
+     * below reads it, and the constants they replaced were `DEFAULT_RENDER_QUALITY` copies —
+     * which measured wrong the moment a scene overrode one. `demo/dayClock` resolves
+     * `directionalShadowMaxSlope` to 9 where the default is 3.
+     */
+    readonly quality: Readonly<RenderQuality>;
+    /** Whether `endFrame` put an image on the canvas. Read by the recorder and the harness. */
+    framePresented: boolean;
+    /**
+     * How many frames this renderer has actually presented, monotonic for its whole lifetime.
+     *
+     * **Incremented in `swapView`, at the one line that calls `getCurrentTexture`** — the real
+     * acquisition, guarded there to fire at most once per frame no matter how many callers ask
+     * for the view. Deliberately not `beginFrame` or `endFrame`: a frame that dies before
+     * drawing anything never reaches `swapView` at all — see the comment on `frameSwapView` in
+     * `beginFrame` — so it correctly never counts, while a frame drawn through the eager
+     * `deferFramePass: false` path counts the moment it takes the swap chain rather than
+     * waiting for `endFrame` to say so after the fact. A consumer compositing an offline export
+     * reads this after `endFrame` and compares it with what it read last, which is how it
+     * tells a frame that drew something from one that repeated the canvas it already had —
+     * see `ExportTarget`.
+     */
+    get presentedFrames(): number;
+    /**
+     * Resolve once every pipeline asked for so far has finished compiling.
+     *
+     * **Await this before the first frame.** A pipeline is not ready when `createRenderPipeline`
+     * returns: the driver compiles the shader at the first draw that uses it, inside the frame,
+     * with the queue stalled behind. Measured on an S23 Ultra, that was a 5.2 second frame with
+     * an idle main thread, no allocation and nothing on any CPU-side timer — the queue simply
+     * did not drain. Compiling asynchronously and waiting here moves that work in front of the
+     * first frame, where it can be waited on honestly instead of appearing as a hang.
+     *
+     * Safe to call at any point and safe to call more than once: it waits for whatever is in
+     * flight at the time, so a consumer that builds more meshes later can wait again.
+     */
+    ready(): Promise<void>;
+    private presentedFrameCount;
+    /**
+     * The joint palettes this frame has set, one slot each. The WebGL2 field of this name is a
+     * single texture, and `SkinPaletteRing` carries why the two differ.
+     *
+     * Held rather than passed, like every other per-draw state here: `setSkinPalette` chooses and
+     * the following draws use it, which is the shape `setMaterial` already has.
+     */
+    private readonly skinPalettes;
+    private readonly skinnedBindGroupLayout;
+    private readonly morphedBindGroupLayout;
+    private readonly bothBindGroupLayout;
+    /** The morph weights the following draws use, or null for none. */
+    private morphWeights;
+    /**
+     * One cached bind group per palette slot, at `slot + 1`, with index 0 for a morphed draw that
+     * is not skinned.
+     *
+     * **An array and not a field, because the palette is a ring now.** A single cached group was
+     * correct while every skinned draw in a frame bound the same texture; with a slot per character
+     * the view changes between them, so one field would miss on every character and build a bind
+     * group per character per frame — an allocation in the frame loop, which `AGENTS.md` forbids.
+     * Keyed by slot instead, the groups are built once and reused for the life of the renderer.
+     */
+    private readonly skinnedGroups;
+    /** The unskinned group each was built beside, for identity-based invalidation. */
+    private readonly skinnedGroupsBeside;
+    private readonly skinnedGroupsPalette;
+    private readonly skinnedGroupsDeltas;
+    /**
+     * Which palette slot the following draws skin by, or -1 for none.
+     *
+     * The slot rather than a flag: two characters in one frame hold two slots at once, and a draw
+     * has to name the one that was uploaded for it. Cleared by `beginFrame`, so a frame that draws a
+     * rigged mesh without setting a palette takes the plain pipeline — the same defined fallback a
+     * caller who passed null gets — rather than reading a slot this frame has already re-let.
+     */
+    private skinPaletteSlot;
+    private readonly surface;
+    /** The encoder for the frame in flight, or null between frames. */
+    private encoder;
+    /** Which optional attributes each mesh key supplied. See the fallback in `submitMesh`. */
+    private readonly meshPresent;
+    private pass;
+    private readonly pipelines;
+    /**
+     * The same pipelines again, built for the canvas, for anything drawn after `endFrame`.
+     *
+     * **A second cache rather than a second key in the first one**, because `PipelineCache` carries
+     * the format and the sample count as the *authority* for every pipeline it holds — that is the
+     * 2026-08-14 rule, and it is what stops a pass disagreeing with the attachment it is about to
+     * be used on. A cache holding pipelines that disagree with its own `format` would give that up
+     * and put the check back in each caller.
+     *
+     * So there are two target states and two caches: the world's, wherever the world lands, and the
+     * overlay's, which is the canvas at one sample. `ensurePass` reopens on the canvas because the
+     * composite has already run — see `overlayDepth` — and a pipeline built against the scene target
+     * is rejected there. Measured on `overlay.html?after=1&samples=4`: the whole overlay was dropped,
+     * with *"Attachment state of [RenderPipeline "inset|color"] is not compatible with
+     * [RenderPassEncoder "overlay"]"* the only evidence anywhere.
+     *
+     * **The same object as `pipelines` when the two states already agree**, which is the common case
+     * of a profile with no composite at one sample — nothing is built twice for a target that is the
+     * same target. `pipelineTargets` is what `createMesh` walks so it cannot build one and forget
+     * the other.
+     */
+    private readonly overlayPipelines;
+    /** Every distinct cache above, so a mesh's pipelines are built for each. One entry when aliased. */
+    private readonly pipelineTargets;
+    private readonly bindGroupLayout;
+    /** One slot per draw, uploaded once a frame. See `UniformRing`. */
+    private readonly perDraw;
+    /** The lights, fog and camera, settled once per frame by `bindMeshPass`. */
+    private readonly perFrame;
+    /**
+     * The material block as the CPU holds it, patched by the setters and copied into a slot.
+     *
+     * Authoritative between draws: a setter changes one field here and marks the block dirty, and
+     * the next `drawMesh` takes a slot and copies the whole thing in. That keeps a setter free of
+     * any knowledge of slots, which is what lets it be called anywhere a scene wants.
+     */
+    private readonly perFrameStaging;
+    private readonly perFrameFloats;
+    private readonly perFrameInts;
+    /** The slot the open material occupies, or -1 when the next draw must take a new one. */
+    private materialSlot;
+    /**
+     * What this frame asked for against the ceilings above, reported rather than only warned about.
+     *
+     * **Declared here, before the rings, because a ring takes its line at construction.** Every
+     * ceiling in this file already wrote one `console.warn` per renderer lifetime and nothing else,
+     * which cannot be asserted on, cannot be read from a headless check and is gone by the time
+     * anybody looks. The order below is the order a report reads in, so the two that lose world
+     * geometry come first.
+     */
+    private readonly budget;
+    private readonly drawBudget;
+    private readonly materialBudget;
+    /**
+     * Native bind groups built this frame, which is the one cost a consumer could not see.
+     *
+     * **No ceiling, because the honest number is nought.** Every other line here counts something
+     * rationed; this counts something cached, so a steady scene settles at zero and any standing
+     * figure is a cache missing. The measurement that found the albedo-keyed cache had to be taken
+     * from outside, by reading a consumer's baked models and replaying this state machine over them
+     * in draw order, precisely because the frame reported draws and material changes and never this.
+     */
+    private readonly bindGroupBudget;
+    private readonly shadowDrawBudget;
+    private readonly scatterDepthBudget;
+    private readonly waterBudget;
+    private readonly lightVolumeBudget;
+    private readonly windStreakBudget;
+    private readonly flockBudget;
+    private readonly boltBudget;
+    private readonly causticsBudget;
+    private readonly textBudget;
+    private readonly sdfTextBudget;
+    private readonly lineBudget;
+    /**
+     * What the frame just drawn asked for, and what it was refused.
+     *
+     * The same object every frame, updated in place — see `budget.ts` for why a number rather than
+     * a log, and why `dropped` is the one field a consumer's own check should fail on.
+     */
+    get frameBudget(): FrameBudget;
+    private readonly arena;
+    /**
+     * Node indices the last schedule kept.
+     *
+     * **Sized from the arena at replay, which this used to only claim.** It was allocated at
+     * `MAX_DRAWS_PER_FRAME` and never grown, while the arena beside it reallocates at twice its
+     * capacity — so a frame recording more nodes than this holds had the tail of its passes
+     * dropped by `keptNodes`, silently. A node is one per *verb*, not per draw, so overlays,
+     * scatter, plumes and text reached it long before the draw ring was full.
+     */
+    private replayScratch;
+    private readonly scheduledPasses;
+    private readonly commands;
+    /** Guards `ensurePass` against re-entering the flush that is already running. */
+    private flushing;
+    /** Starts near the verb count; reaching zero is what says the migration is done. */
+    private flushesThisFrame;
+    private verbFlushesThisFrame;
+    /** Passes the last flush scheduled. Zero when nothing has flushed this frame. */
+    private passesLastFlush;
+    /** Every resource the last flush derived a discard for, as one mask. */
+    private discardsLastFlush;
+    /** Every resource the last flush derived a clear for, as one mask. */
+    private clearsLastFlush;
+    /**
+     * What still owes a clear this frame.
+     *
+     * **Owed by attachment rather than by frame**, which `frameNeedsClear` could not express. The
+     * rule it carried is that a scene opening the mirror before it draws anything still owes the
+     * frame its clear afterwards, and a scene that drew first does not — a rule that lived inside
+     * one branch and could not be asked about. Bits are removed by the open that performs them.
+     */
+    private pendingClearMask;
+    /**
+     * What the next frame pass to open may discard.
+     *
+     * Held rather than passed, because the open happens inside `openPass`, which the direct path
+     * uses too — threading a graph concept through its signature would put the graph in the one
+     * method that exists to have nothing to do with it. Cleared on use, so a pass opened outside a
+     * flush gets zero, which is the conservative answer and the right one.
+     */
+    private pendingDiscard;
+    /**
+     * Every flush this frame, of either kind.
+     *
+     * Exposed because the plan gates narrowing `liveOut` on a flush count, and a private counter
+     * no caller can read is a claim rather than a measurement. Reading it costs a field access,
+     * so a scene can print it every frame without paying for the privilege.
+     */
+    get graphFlushes(): number;
+    /**
+     * Flushes caused by a verb about to draw directly, which is what must reach zero.
+     *
+     * **The plan asks for `flushesThisFrame` to reach zero and that number cannot.** A boundary
+     * flush is inherent: the mirror gets a different encoder and its own submit, the overlay is
+     * closed on a microtask, the depth snapshot ends the pass to copy the attachment out, and an
+     * inset changes the viewport. The design says as much about the reopens — all three are
+     * inherent and removing them was never the point — so a frame that reflects will always
+     * flush at least twice however complete the migration is.
+     *
+     * What the migration is actually measured by is the *other* kind: a verb reaching
+     * `ensurePass` because it is about to issue commands itself. That is the number that starts
+     * near the verb count and goes to zero, and it is the one the gate belongs on.
+     */
+    get graphVerbFlushes(): number;
+    /**
+     * Passes the last flush scheduled, which is how a write-set declaration becomes observable.
+     *
+     * A node declaring a target it does not write is invisible in the picture — the executor
+     * replays into whatever pass is open regardless — and shows up here as a pass count that does
+     * not match the boundaries the frame actually has.
+     */
+    get graphPasses(): number;
+    /**
+     * Everything the last flush derived a discard for, as one mask.
+     *
+     * **Derived, and not yet acted on.** The executor replays every node into the pass `openPass`
+     * gives it, so this changes no bytes on any device. It is the derivation `resolvedStoreOp`
+     * takes from a person today, in a form a test can read — which is the whole difference the
+     * design claimed for itself, and the only part of it verifiable without a tiler.
+     */
+    get graphDiscards(): number;
+    /**
+     * Everything the last flush derived a clear for.
+     *
+     * The scheduler and `pendingClearMask` compute the same thing, and the mask is what the open
+     * acts on — see `openPass` for why it has to be, since a pass can be opened where no schedule
+     * describes it. This is the scheduler's answer, exposed so the two can be held against each
+     * other rather than assumed to agree.
+     */
+    get graphClears(): number;
+    /**
+     * What the last flush's discards are worth, in attachment bytes a frame.
+     *
+     * The figure the design is arguing about, computed from the schedule and the sizes this
+     * renderer allocated rather than estimated from a viewport somebody quoted. Only the two
+     * depth attachments can appear in it, because they are the only resources the derivation
+     * finds dead — see `liveOutMidFrame`.
+     *
+     * **A byte here is a byte a tiler would not write.** An immediate-mode GPU has nowhere else
+     * to put the data and writes it regardless, which is exactly why this number cannot be
+     * confirmed on the machines available here however carefully it is computed.
+     *
+     * `depth24plus` is counted at four bytes a sample. The format is implementation-defined and
+     * a driver may use more; four is the floor, so this number is a floor too.
+     */
+    get graphDiscardBytes(): number;
+    private bindGroup;
+    /** Kept so the flat bind group can be rebuilt when a cubemap changes hands. */
+    private readonly flatTextures;
+    /**
+     * Which permutation of the fragment shader this renderer draws with.
+     *
+     * **Chosen from the resolved profile, which is what `renderer.ts` does — and it does it
+     * once, not per material.** `flatFrag` is compiled at construction there from the same four
+     * flags, so a world with shadows off compiles none of the shadow path on either backend.
+     * This was pinned to `directionalShadows` while the point-shadow samplers had nowhere to
+     * come from, which meant the two backends could be running different programs for one
+     * profile and nothing said so.
+     *
+     * `environmentProbe` is false because `bakeReflectionProbe` is not on this class at all, so
+     * a scene that wants one gets a named `TypeError` rather than a shader compiled around a
+     * probe that will never be filled. That is the loud failure the 2026-08-13 rule asks for.
+     *
+     * It was `none` for a day, because turning it on drew the scene uniformly black. That was
+     * not the shadow path: `shadowMapSize` was missing from this class, so the light matrix
+     * every scene builds from it was NaN. See the accessor for what that cost and how it hid.
+     */
+    private readonly variant;
+    /** Whether this profile compiled the point-shadow path, and so has sentinels to write. */
+    private readonly pointShadowsCompiled;
+    /** What the generator recorded about that permutation: sizes, offsets and bindings. */
+    private readonly fragment;
+    private depth;
+    private depthView;
+    /**
+     * The pass a draw arriving *after* `endFrame` goes into, and the depth it needs.
+     *
+     * **An application is allowed to draw its interface after the frame resolves, and one does.**
+     * One consumer puts its announcements, its portraits and its item cases after `endFrame`
+     * deliberately, so the interface is not inside the off-screen target and is not blurred by the
+     * screen-space effects that sample it. WebGL2 allows that for free: its commands run eagerly
+     * against the canvas, so a draw after the resolve simply lands on top of it.
+     *
+     * This backend records into an encoder that `endFrame` has already submitted, so every one of
+     * those calls found `this.pass === null` and returned — no text, and a portrait box holding
+     * whatever the canvas had, which through a transparent canvas is nothing at all. It reported
+     * none of it, which is the failure this whole backend keeps producing.
+     *
+     * So the pass is reopened on demand, on the canvas itself rather than on the scene target: the
+     * composite has already run and this content is meant to sit over its output, untouched by it.
+     * Its depth is its own and single-sampled, because the frame's depth carries the scene's sample
+     * count and WebGPU requires every attachment in a pass to agree.
+     */
+    private overlayDepth;
+    private overlayDepthView;
+    /** Whether the open pass is one reopened after the frame was submitted. */
+    private overlayActive;
+    /** Whether a flush is already queued, so a hundred overlay draws queue one. */
+    private overlayFlushQueued;
+    /**
+     * The multisampled colour target, when the profile asked for one.
+     *
+     * Null at one sample, where the swap chain texture is drawn into directly and there is
+     * nothing to resolve. Above one it is the *render* target and the swap chain becomes the
+     * `resolveTarget`, which is where the averaging happens — the whole reason this exists.
+     */
+    private colorMsaa;
+    private colorMsaaView;
+    /** This frame's swap-chain view, taken once so the mirror pass can reopen onto the same one. */
+    private frameSwapView;
+    /**
+     * Where the frame lands when there is a composite to resolve it.
+     *
+     * Null where `screenEffects` is off, and then every pass writes straight to the swap chain
+     * exactly as it did before this existed — which is also what makes `bindMeshPass` grade in
+     * the mesh pass in that case, because that pass is then the last one.
+     */
+    private sceneColor;
+    /**
+     * The colour the frame had already drawn when the first refracting draw arrived.
+     *
+     * **A copy, because no shader can read what the pass is writing.** `post.sceneColorMsaa` is
+     * created `RENDER_ATTACHMENT` with no `TEXTURE_BINDING` and `post.sceneColor` is the pass's own
+     * resolve target, so the only readable thing is a texture nothing is currently attached to.
+     * `takeRefractSnapshot` ends the pass, which resolves, copies, and reopens.
+     */
+    private refractSnapshot;
+    private refractSnapshotView;
+    /** Whether this frame has taken it. One snapshot serves every refracting draw. */
+    private refractSnapshotTaken;
+    private sceneColorView;
+    /** The multisampled twin, when the profile asks for samples. Resolved into `sceneColor`. */
+    private sceneColorMsaa;
+    private sceneColorMsaaView;
+    /** Sample zero of the depth, as something the generated shaders can read. See `postPass.ts`. */
+    private resolvedDepth;
+    private resolvedDepthView;
+    private aoTarget;
+    private aoTargetView;
+    /**
+     * Where the blur's first axis lands, so the second can read it.
+     *
+     * **The blur is not a polish step on this estimate, it is half of the algorithm.**
+     * `ambientOcclusion.ts` says so at the top: the estimate turns its twelve taps by a rotation
+     * that repeats over a 4×4 tile, and the four-wide blur is what averages all sixteen rotations
+     * back into one answer. Twelve taps are only enough *because* the blur completes the kernel.
+     *
+     * Without it the estimate is what that file calls salt and pepper over every surface, and that
+     * is exactly what shipped here: `AO_BLUR_FRAG_WGSL` was imported into this file and never
+     * called, while `runOcclusion`'s own comment said "then a blur across it". Reported from both
+     * consumers as a fine grain — white on one's pillars, dark on the ground under
+     * the other's character — and measured on `gilded-chamber` under the first's grade at 41,106
+     * speckled pixels against WebGL2's 28,107.
+     *
+     * Separable, so it is two passes over a half-resolution target rather than one wide one:
+     * across into here, then down and back into `aoTarget`, which is what the composite samples.
+     */
+    private aoScratch;
+    private aoScratchView;
+    /**
+     * The bloom pyramid, level 0 at half the frame and each one after it half again.
+     *
+     * A list rather than one target, because bloom *is* the pyramid: the frame is thresholded into
+     * level 0, halved down the chain, and added back up so level 0 holds every octave at once.
+     * This backend had the first of those eleven draws and nothing else, which drew a thresholded
+     * image with no blur in it — see `bloomChain.ts` for what that measured.
+     */
+    private bloomLevels;
+    /**
+     * One bind group per distinct *source*: the scene first, then each level.
+     *
+     * Built on resize rather than per stage, because `AGENTS.md` forbids allocating in the frame
+     * loop and eleven `createBindGroup` calls a frame is exactly that. What differs between stages
+     * beyond the source is the uniform block, and that rides on a dynamic offset instead, which is
+     * what the layout already declares.
+     */
+    private bloomGroups;
+    private frameWidth;
+    private frameHeight;
+    /** The view-projection this frame was drawn with, for the reprojection motion blur needs. */
+    private readonly previousViewProj;
+    private readonly reprojection;
+    private hasPreviousView;
+    /** The projection, for occlusion. Null until a mesh pass has settled one. */
+    private frameProjection;
+    private readonly aoInvProjection;
+    private readonly aoProjScale;
+    /**
+     * Whether this frame has already taken the depth snapshot a light volume clamps against.
+     *
+     * One per frame, not one per volume: every volume in a frame reads the same opaque scene, and
+     * a second snapshot would cost a pass break and a full-screen resolve to produce identical
+     * texels. Reset by `beginFrame`.
+     */
+    private volumeDepthTaken;
+    /** Scratch for `uDepthToLocal`, built per volume draw and never allocated in the frame loop. */
+    private readonly volumeDepthToLocal;
+    private readonly volumeDepthScratch;
+    private readonly pickables;
+    private readonly pickOrigin;
+    private readonly pickDirection;
+    private readonly depthResolveLayout;
+    private readonly rushLayout;
+    private readonly rushUniforms;
+    private readonly rushStaging;
+    private readonly rushFloats;
+    private readonly rushInts;
+    private rushBindGroup;
+    /**
+     * The colour grade, as a 3D texture, and the table it was built from.
+     *
+     * The source is kept to compare identities rather than to read: a consumer setting a grade
+     * every frame would otherwise re-upload 131 kilobytes sixty times a second for bytes that did
+     * not change. See `SceneTarget.setColourGrade`, which keeps the same pair for the same reason.
+     */
+    private gradeTexture;
+    private gradeView;
+    private gradeSource;
+    private gradeSize;
+    private gradeStrength;
+    /** So the refusal in `setColourGrade` is once per renderer rather than once per frame. */
+    private warnedGradeWithoutComposite;
+    private readonly aoLayout;
+    private readonly aoUniforms;
+    /**
+     * The global medium: one half-res march and one composite, each with a block of its own.
+     *
+     * **Two layouts rather than one, because they read different things.** The march reads the
+     * depth and the three shadow maps; the composite reads the depth and what the march wrote.
+     * The march's target is `rgba16float` — scattered light has no reason to sit in 0 to 1 against
+     * an HDR scene, and transmittance wants more than eight bits near 1, where a thin fog lives and
+     * where banding would therefore show first.
+     */
+    private readonly mediumLayout;
+    private readonly mediumUniforms;
+    private readonly mediumStaging;
+    private readonly mediumFloats;
+    private readonly mediumInts;
+    private mediumTarget;
+    private mediumTargetView;
+    private mediumBindGroup;
+    private readonly mediumUpsampleLayout;
+    private readonly mediumUpsampleUniforms;
+    private readonly mediumUpsampleStaging;
+    private readonly mediumUpsampleFloats;
+    private mediumUpsampleGroup;
+    /** The inverse projection the composite linearises a depth with, built once per frame. */
+    private readonly mediumInvProjection;
+    /** This frame's medium. Off until a caller says otherwise. See `setGlobalMedium`. */
+    private mediumOptions;
+    /**
+     * The temporal resolve: its block, its ping-pong pair, and the jitter state.
+     *
+     * **`correctedViewProj` stays unjittered and `viewProj` is what draws.** The reprojection is
+     * built from the former, because the history holds a resolved picture standing for the
+     * *unjittered* scene — reprojecting through a jittered matrix would look every sample up half a
+     * pixel from where it is and cancel the accumulation.
+     */
+    private readonly taaStaging;
+    private readonly taaFloats;
+    private taaLayout;
+    private taaUniforms;
+    private taaTextures;
+    private taaViews;
+    /** Group `i` reads history `i` and the pass writes into the other one. */
+    private taaBindGroups;
+    private taaWrite;
+    private readonly temporalHistory;
+    private readonly jitteredViewProj;
+    private temporalJitterX;
+    private temporalJitterY;
+    private temporalJittering;
+    private temporalHistoryUsable;
+    private readonly aoStaging;
+    private readonly aoFloats;
+    private aoBindGroup;
+    private readonly aoBlurLayout;
+    /**
+     * Both blur axes' blocks in one buffer, a slot each, reached by dynamic offset.
+     *
+     * The same shape the bloom chain uses and for the same reason: the two passes differ only in
+     * `uStep`, and a buffer holding one block would give the second pass the first one's axis —
+     * which is a blur run twice across and never down, and looks like a blur that half worked.
+     */
+    private readonly aoBlurUniforms;
+    private readonly aoBlurStaging;
+    private readonly aoBlurFloats;
+    /** One group per source: the estimate for the across pass, the scratch for the down pass. */
+    private aoBlurAcrossGroup;
+    private aoBlurDownGroup;
+    private readonly bloomLayout;
+    private readonly bloomUniforms;
+    /**
+     * Every stage's block at once, one aligned slot each, written on resize and not per frame.
+     *
+     * **Nothing in these blocks changes between frames.** A texel size is a function of the
+     * target, the threshold is construction-time on the profile, and the tent radius is a
+     * constant — so a per-frame upload would rewrite the same bytes sixty times a second. Written
+     * together also sidesteps the hazard this file has met twice: `queue.writeBuffer` does not
+     * interleave with recorded commands, so one buffer rewritten between two passes gives both
+     * passes the last write.
+     */
+    private readonly bloomStaging;
+    private readonly bloomFloats;
+    private readonly postSampler;
+    private readonly postDepthSampler;
+    /** Whether the profile asked for a composite at all. Everything below is null when it did not. */
+    private get hasComposite();
+    /** What a frame pass writes into: the scene target where there is one, the swap chain else. */
+    /**
+     * This frame's swap-chain view, taken on first use rather than at `beginFrame`.
+     *
+     * `getCurrentTexture` is an acquisition and not a read: the texture it hands back is what the
+     * browser presents when the task ends, whether or not anything drew into it. Taking it only
+     * when something is about to draw is what keeps a frame that fails from blanking the screen.
+     */
+    private swapView;
+    private compositeTarget;
+    /** Its multisampled twin, or null at one sample. */
+    private compositeMsaa;
+    /** Samples per pixel, settled at construction. See `supportedSampleCount`. */
+    private readonly samples;
+    /** The camera the frame is being drawn with, copied into every draw's slot. */
+    private viewProj;
+    /**
+     * The frame's camera as the caller built it, uncorrected and unjittered.
+     *
+     * **`viewProj` is not this**, and a decal wants this one. That matrix carries `CLIP_CORRECTION`
+     * and the frame's sub-pixel jitter; the generated vertex stages then negate Y a second time, so
+     * the Y the rasteriser actually used is *this* matrix's. `DEPTH_01_TO_CLIP_Y_DOWN` carries the
+     * derivation and what one missing negation costs.
+     */
+    private readonly frameRawViewProj;
+    private frameCameraSeen;
+    /** Where the frame's camera stands, which gives a reconstructed normal its sign. */
+    private readonly frameEye;
+    /** The environment the frame was drawn with. See `bindMeshPass`. */
+    private frameEnv;
+    /** That matrix with the clip-space correction folded in, rebuilt once a frame. */
+    private readonly correctedViewProj;
+    private readonly skyLayout;
+    private readonly skyUniforms;
+    private readonly skyStaging;
+    private readonly skyFloats;
+    private readonly skyBindGroup;
+    /** The camera's inverse with the clip correction undone, rebuilt once a frame. */
+    private readonly skyInvViewProj;
+    /**
+     * The reflection target, or null where the profile has no use for one.
+     *
+     * Allocated on the same condition `renderer.ts` allocates its own: water with reflections
+     * on, or `planarReflections` asked for outright by a scene whose mirror is not water.
+     */
+    /**
+     * Whether this profile has any use for a mirror, on the same condition `renderer.ts` uses:
+     * water with reflections on, or a scene that asked for one outright because its mirror is
+     * not water. A profile with neither never pays for the target.
+     */
+    private readonly wantsReflection;
+    private reflection;
+    /** Refilled on resize rather than allocated; see `reflectionTargetSize`. */
+    private readonly reflectionSize;
+    /**
+     * Order-independent transparency: the recorded set, the two buffers, and which one is open.
+     *
+     * **Recorded rather than drawn**, because the accumulation and the revealage are two blend
+     * states over the same geometry — and on this backend a blend state is baked into a pipeline, so
+     * they are two pipelines as well. `TranslucentQueue` is what lets the set be submitted twice.
+     */
+    private readonly translucentQueue;
+    private oitActive;
+    /** Said once for the whole renderer. See `refuseOitMultisampled`. */
+    private oitMultisampleRefused;
+    private oitReplaying;
+    /** Which buffer the replay is filling, which the pipeline key must carry. */
+    private oitMode;
+    /**
+     * The pass the replay draws into.
+     *
+     * **While this is set, `openPass` hands it back and `recordDraw` refuses.** The frame graph
+     * records draws to replay them into the frame's own passes; these draws belong to a pass of
+     * their own, opened here and closed before anything else runs.
+     */
+    private oitEncoder;
+    private oitAccum;
+    private oitAccumView;
+    private oitReveal;
+    private oitRevealView;
+    /**
+     * The frame's drawn decals, their block per mark, and the group that reads the resolved depth.
+     *
+     * Recorded rather than drawn where the call is made: a projected mark is decided from the depth
+     * the frame has drawn, so it cannot run until the opaque world is finished. See `DecalQueue`.
+     */
+    private readonly decalQueue;
+    private decalLayout;
+    private decalUniforms;
+    private readonly decalStaging;
+    private readonly decalFloats;
+    private decalBindGroup;
+    /** Said once where a mark cannot be drawn at all, rather than dropped in silence. */
+    private decalsRefused;
+    /**
+     * The frame's reflective surfaces, their block per surface, and the buffer the trace writes into.
+     *
+     * Recorded rather than traced where the call is made, because a march reads the *finished*
+     * picture: what a ray finds is a pixel of the scene the frame has already drawn.
+     */
+    private readonly reflectionQueue;
+    private ssrLayout;
+    private ssrResolveLayout;
+    private ssrUniforms;
+    private readonly ssrStaging;
+    private readonly ssrFloats;
+    private ssrReflection;
+    private ssrReflectionView;
+    private ssrBindGroup;
+    private ssrResolveGroup;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP_Y_DOWN`, rebuilt once a frame. */
+    private readonly ssrDepthToWorld;
+    /** `CLIP_Y_FLIP * viewProjection`, the matrix the trace projects its samples back through. */
+    private readonly ssrViewProj;
+    private readonly ssrScissor;
+    /** Said once where a reflection cannot be traced at all. */
+    private reflectionsRefused;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP_Y_DOWN`, rebuilt once a frame and not per mark. */
+    private readonly decalDepthToWorld;
+    private readonly decalScissorRect;
+    private oitResolveLayout;
+    private oitResolveGroup;
+    /** Reused, because the frame loop may not allocate. Mirrors the WebGL2 backend's own. */
+    private readonly oitReplayOptions;
+    private reflectionPassActive;
+    /** Said once: a mirror asked for outside a frame is a call-order fault, not a device limit. */
+    private saidMirrorOutsideFrame;
+    /**
+     * Whether the target holds this frame's mirror yet.
+     *
+     * Cleared when the pass opens and set when it closes, so water drawn *before* the mirror
+     * finished samples nothing rather than last frame's. `PlanarReflection.isReadyFor` is the
+     * same guard on the other backend, with the plane's height in it as well.
+     */
+    private reflectionReady;
+    /** The plane the ready target was drawn for, so water at a different height does not use it. */
+    private reflectionPlaneY;
+    /**
+     * The height the medium is resolved at while the mirror is being drawn.
+     *
+     * **The source camera's, not the mirrored one's.** Fog is a property of where the *viewer*
+     * stands, and a mirrored camera stands as far below the water as the viewer stands above it —
+     * so resolving the medium from it puts the reflection underwater whenever the viewer is not.
+     * `renderer.ts` keeps the same value for the same reason.
+     */
+    private reflectionAtmosphereY;
+    /**
+     * Open the mirror pass: the world about to be drawn from behind the water.
+     *
+     * **The frame's pass is ended and reopened, which is the shape WebGPU makes explicit.** A
+     * caller calls this *after* `beginFrame`, so there is a pass open on the swap chain; WebGL2
+     * answers by rebinding a framebuffer, and here the only way to draw somewhere else is a
+     * second render pass. `endPlanarReflection` reopens the frame's with `load`, so the clear and
+     * anything drawn before the mirror survive it.
+     *
+     * **Declining is a supported state rather than a stub**, and is what a device that refuses
+     * the allocation gets: every caller already branches on `null` — `demo/nightCourt` draws the
+     * world once instead of twice — and `WaterRenderer` has a complete path for water with
+     * nothing to sample.
+     */
+    beginPlanarReflection(source: Camera, planeY: number, clearColor: Vec3): Camera | null;
+    /** The mirrored viewProjection under the clip correction, rebuilt per water draw. */
+    private readonly correctedReflectionViewProj;
+    /**
+     * Push every ring's slots up before the commands that read them are submitted.
+     *
+     * That ordering is the whole thing a ring depends on — writes land on the queue timeline
+     * ahead of the pass that reads them — and it has to happen once per *submission* rather than
+     * once per frame, because a frame with a mirror in it submits three times. Re-flushing a
+     * prefix that has already been uploaded costs one write of unchanged bytes and cannot be
+     * wrong: a ring only ever appends within a frame.
+     */
+    private flushRings;
+    private readonly filmLayout;
+    private readonly filmVerts;
+    private readonly filmFrags;
+    private filmBindGroup;
+    /** The film's group with the blank in the mirror's slot; see where it is built. */
+    private readonly filmBindGroupBlank;
+    /**
+     * A thin wet layer over the world: an oil slick, a puddle, a wet patch.
+     *
+     * `renderer.ts` carries the argument about what `sheen` is and is not, and about why the
+     * caller does not restate the plane the mirror was rendered for. The one thing this backend
+     * adds is that the mirror's matrix is corrected, for the reason `drawWater` gives: the
+     * reflection texture holds a frame in WebGPU's clip space, so a lookup projecting a world
+     * point has to be in that same space or the film samples its own mirror image.
+     */
+    drawFilm(mesh: GpuMesh, camera: Camera, timeSeconds: number, env: Environment, sheen: number, options?: FilmOptions): void;
+    /** Scratch for the film's fragment block, filled then copied into a slot. */
+    private readonly filmFragStaging;
+    private readonly filmFragFloats;
+    private readonly filmFragInts;
+    /**
+     * The image the following draws sample, and the bind group that carries it.
+     *
+     * **A bind group per texture, cached, rather than one rebuilt per material.** `createBindGroup`
+     * is an allocation, and a scene like `night-street` switches texture once per textured part of
+     * a loaded model — so rebuilding on every switch is exactly the per-frame allocation the house
+     * rules forbid, and the same trap `rebindPointShadowsIfMoved` avoids by dirty-checking. The
+     * map is keyed by the texture object, so a material switched away from and back to costs a
+     * lookup.
+     */
+    private albedo;
+    /**
+     * The material's normal map, or null for the stand-in.
+     *
+     * Not cached per texture the way albedo is: a material changes its albedo far more often than
+     * its normal map, and a second cache keyed on a second texture is a product of the two.
+     */
+    private normalMap;
+    private ormMap;
+    /** The caller's emissive map, or null for the stand-in. See `setMaterial`. */
+    private emissiveMap;
+    /**
+     * The flat group for a material, keyed on **all four** of its maps.
+     *
+     * **It used to be keyed on the albedo alone, and that is why it was emptied so often.** Every
+     * group it holds carries the normal, ORM and emissive views that were current when it was built,
+     * so a cache keyed on one of the four could only stay correct by being thrown away whenever any
+     * of the other three moved. `setMaterial` did that once per changed map, then missed the cache it
+     * had just cleared, so a material differing from the one before it in a single map cost up to
+     * four `createBindGroup` calls and destroyed every entry a later material would have hit.
+     *
+     * A consumer measured what that cost over the materials its cars merge to: 476 groups a pass for
+     * seven models with 247 distinct signatures between them, drawn a second time for the water's
+     * mirror, so about 950 a frame that should have been nought after the first. It scaled with
+     * distinct models rather than with cars, because identical cars share a batch, which is why it
+     * read from the outside as the frame rate falling off when a second kind of car appeared.
+     *
+     * **Nested rather than one map under a composite key**, because a key built per lookup is an
+     * allocation on a path that runs per material change, and the number of material changes in a
+     * frame is exactly the number this is trying to stop being expensive. Four `Map.get` calls
+     * allocate nothing. What a miss costs is up to three empty `Map`s, which is bounded by the
+     * distinct signatures a scene has and is zero once it has been seen.
+     *
+     * The four texture invalidations that remain are in `rebuildFlatBindGroup`, and they are the
+     * ones that move something *every* group holds: the shadow cubemaps, the probe fence, the cookie
+     * atlas and the IES rows. None of those is a frame path.
+     */
+    private readonly flatBindGroups;
+    /** The group holding the one-pixel stand-in, for every draw with no texture set. */
+    private blankAlbedoBindGroup;
+    /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
+    private readonly uvScale;
+    createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): GpuSurfaceTexture;
+    updateSurfaceTexture(texture: GpuSurfaceTexture, source: TexImageSource): void;
+    disposeSurfaceTexture(texture: GpuSurfaceTexture): void;
+    /**
+     * Choose the surface texture the following `drawMesh` calls sample, or null for none.
+     *
+     * State rather than an argument to `drawMesh`, for the two reasons `renderer.ts` gives: a
+     * texture belongs to a material and a material covers many draws, and `drawMesh` already
+     * carries a model, a layer and a tint. `bindMeshPass` resets this to none, so a pass cannot
+     * inherit a material from the one before it.
+     */
+    /**
+     * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
+     *
+     * The twin of the WebGL2 method, answering the same way — a value-typed member of the shared
+     * surface must be answered by every backend, and answered honestly, per the 2026-08-13 rule.
+     */
+    setSkinPalette(palette: Float32Array | null): void;
+    /**
+     * Choose the morph weights the following `drawMesh` calls deform by, or null for none.
+     *
+     * The twin of the WebGL2 method: the weights are per draw and the deltas are per mesh, so two
+     * characters sharing one head mesh wear different expressions without a second copy of it.
+     */
+    setMorphWeights(weights: Float32Array | null): void;
+    setMaterial(material: SurfaceMaterial<GpuSurfaceTexture> | null): void;
+    /**
+     * @deprecated Use `setMaterial`. See `renderer.ts` for why this stays: 56 call sites across four
+     * repositories, three of which deploy on push, so removing it is a major version rather than a
+     * side effect. Both renderers implement the same public surface, and a divergence here is a
+     * consumer that works on one backend and not the other.
+     */
+    setSurfaceTexture(texture: GpuSurfaceTexture | null, uScale?: number, vScale?: number, cutout?: number): void;
+    /**
+     * The group for this exact set of four maps, built on the first ask and kept.
+     *
+     * **All four null is the stand-in's group**, which stays a field of its own rather than an entry
+     * here: it is what a pass starts from and what `disposeSurfaceTexture` and the ring rebuild have
+     * to refresh directly, and giving it two homes would be two things to keep in step.
+     *
+     * `buildFlatBindGroup` reads the live material fields, so every caller assigns all four before
+     * asking. Passing them in as well is deliberate: it is what makes the key and the group agree by
+     * construction rather than by the caller having remembered.
+     */
+    private flatGroupForMaps;
+    /**
+     * Patch one field of the open material and make the next draw take a new slot.
+     *
+     * The block is the CPU's until a draw copies it, so a setter is free to be called between
+     * draws, several times, or never — which is what "pass state" means on the other backend too.
+     */
+    private material;
+    private materialField;
+    /**
+     * Kept as a no-op that says so once. See `renderer.ts` for the whole argument; in one line, it
+     * was the stand-in for a term that now exists, and it is deprecated rather than removed because
+     * it is on the public surface and removing it would break four repositories to save a method.
+     */
+    setEnvironmentAmbient(_amount: number): void;
+    /** How reflective the surfaces drawn next are. Clamped, as `renderer.ts` clamps it. */
+    setSurfaceReflectivity(amount: number): void;
+    /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
+    setEnvironmentGain(gain: number): void;
+    setSurfaceGrain(amount: number): void;
+    /**
+     * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
+     *
+     * The 60 that `renderer.ts` defaults to is repeated there and here; the two must move
+     * together, and that file says why the number is what it is.
+     */
+    setSurfaceRelief(amount: number, cyclesPerMetre?: number): void;
+    /**
+     * How hard the bound surface texture's own luminance turns the shading normal.
+     *
+     * See `Renderer.setSurfaceTextureRelief` for what this is for, why the colour image serves as
+     * the height field rather than a second sampler being added, and why this one is not clamped
+     * to 0..1 the way its neighbours are.
+     */
+    setSurfaceTextureRelief(scale: number): void;
+    /** Scale the emissive of the following draws. See `Renderer.setEmissiveGain` for why. */
+    setEmissiveGain(gain: number): void;
+    /**
+     * The plain surface an overlay is read against. See `Renderer.fillPanel` for the argument
+     * about why neither an inset nor a plate of glyph cubes can stand in for it.
+     *
+     * **Reopens the pass, like the rest of this section.** A panel is the backdrop a caption or a
+     * plate is read against, so it is drawn wherever they are — and they are drawn after `endFrame`
+     * by the consumer that has one, to keep the interface out of the screen-space chain. Held to
+     * `this.pass`, it was the only member of `-- Overlays --` that still went silently nowhere in
+     * that order, which is the shape of failure the 2026-08-13 rule is about.
+     */
+    fillPanel(rect: InsetRect, color: Vec3, alpha: number): void;
+    /** A 3D text object. See `textPass.ts`; the layout it holds is shared with WebGL2. */
+    createText(): GpuText;
+    setText(text: GpuText, content: string): void;
+    setPlate(text: GpuText, widthCells: number, heightCells: number, bottomCell: number): void;
+    textWidth(text: GpuText, cellSize: number): number;
+    disposeText(text: GpuText): void;
+    /** A text label from an SDF font. See `sdfTextPass.ts`; the layout it holds is shared with WebGL2. */
+    createSdfText(): GpuSdfText;
+    setSdfText(text: GpuSdfText, font: SdfFont, atlas: GpuSurfaceTexture, content: string, style: SdfTextStyle): void;
+    disposeSdfText(text: GpuSdfText): void;
+    /** The bind group for this atlas, built on the first ask and kept. See `sdfTextBindGroups`. */
+    private sdfTextBindGroupFor;
+    /**
+     * Draw a laid-out SDF string into the scene, at `model`.
+     *
+     * **Inside whatever pass is already open, against `this.viewProj` — not a pass of its own.**
+     * `drawText` calls `openTextPass` because the pixel font's cubes need their own cleared depth
+     * buffer to sort against themselves; SDF text is a flat, blended quad with depth *testing*
+     * left at the pass's own ambient state, the same assumption `drawTranslucentMesh` makes, so
+     * reopening the pass here would do nothing but discard whatever the frame had drawn before
+     * it — see `openTextPass`'s own comment for the failure that shape caused once already.
+     * `this.viewProj` is `bindMeshPass`'s corrected matrix, the same one `submitMesh` reads; a
+     * no-op before the first `bindMeshPass` of a session, same as every other pass that reads it.
+     */
+    drawSdfText(text: GpuSdfText, model: Float32Array, color: Vec3, opacity: number): void;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedSdfTextFull;
+    private warnedTextFull;
+    /**
+     * Draw a laid-out string over the scene.
+     *
+     * **A pass of its own, because the depth buffer has to be cleared and WebGPU cannot clear one
+     * in the middle of a pass.** `TextRenderer` calls `gl.clear(DEPTH_BUFFER_BIT)` here and the
+     * reason is in its comment: the cubes are solid, so text drawn with no depth test renders as
+     * one flat facet, and text drawn against the scene's depth disappears into it. Reopening with
+     * `depthLoadOp: 'clear'` and `loadOp: 'load'` on colour is the same statement in this API.
+     *
+     * One pass per string rather than one per frame, which is what WebGL2 does by clearing on
+     * every `draw` — two strings do not sort against each other on either backend.
+     */
+    drawText(text: GpuText, viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): void;
+    /**
+     * End the frame's pass and reopen it with the depth buffer cleared.
+     *
+     * The colour attachment loads, so everything drawn so far survives; only depth is thrown
+     * away. `this.pass` is replaced, so whatever a scene draws after its text carries on into
+     * the reopened pass and against the cleared depth — which is exactly what happens on WebGL2
+     * after its `gl.clear`.
+     */
+    private openTextPass;
+    /**
+     * The mirror to sample for water resting at `planeY`, or null.
+     *
+     * **Three conditions, not one.** There has to be a target; this frame has to have drawn into
+     * it, or the pool shows the frame before; and it has to have been drawn for *this* plane, or
+     * a scene with two bodies of water at different heights reflects one into the other.
+     * `PlanarReflection.isReadyFor` is the same test on the other backend.
+     */
+    private reflectionFor;
+    /** Close the mirror and put the frame's own pass back, keeping what it already held. */
+    endPlanarReflection(): void;
+    /**
+     * The frame's own render pass, opened to clear or to resume.
+     *
+     * One place, because `beginFrame` and `endPlanarReflection` have to agree about which view is
+     * the attachment and which is the resolve target — and at four samples those are two
+     * different textures, so a second copy of the rule is a mirror pass that quietly redirects
+     * the rest of the frame to the wrong one.
+     */
+    /**
+     * The mirror's pass: the world about to be drawn from behind the water.
+     *
+     * `beginPlanarReflection`'s descriptor, moved here so the mirror is opened through the same
+     * door as everything else and takes its load and store from the same two masks.
+     */
+    private openMirrorPass;
+    private openFramePass;
+    /**
+     * Build a particle pool: the shared cross, instance storage sized to its capacity, and this
+     * batch's own uniform buffers and bind group — see the doc comment on `createGpuParticles`
+     * for why those may not be shared with another batch of the same material. The bind group
+     * *layout* is the one thing still shared per material, resolved here and handed down: it is
+     * structural (what the shader binds, not what value is in it), so sharing it carries none of
+     * the same risk.
+     */
+    createParticles(capacity: number, options: ParticleBatchOptions): GpuParticles;
+    disposeParticles(batch: GpuParticles): void;
+    /**
+     * Draw a pool's live particles.
+     *
+     * **The instance streams are interleaved here rather than uploaded separately**, because
+     * ten attributes will not fit in eight vertex-buffer slots. `packInstances` writes into an
+     * array allocated with the batch, so the frame loop still allocates nothing.
+     */
+    /**
+     * The output transform a forward pass should apply, and the exposure it should apply it at.
+     *
+     * The WebGPU half of `Renderer.gradeCode`, and it has to agree with it draw for draw: this is
+     * one verb with two implementations, and a frame that grades on one backend and not the other
+     * is the silent kind of disagreement. See that method for what the gate is protecting.
+     */
+    private gradeCode;
+    private gradeExposure;
+    drawParticles(batch: GpuParticles, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /**
+     * The bind group layout for one particle material, built on first use.
+     *
+     * Per material rather than shared across all three, because the fragment blocks are
+     * different sizes (`'spark'`'s is 560 bytes, `'mote'`'s is 80) and a bind group whose
+     * `minBindingSize` came from another material's block is rejected at bind time. Safe to
+     * share *within* a material — unlike the uniform buffers and bind group `createGpuParticles`
+     * now builds per batch — because a layout describes what a shader binds, never a value, so
+     * nothing about handing the same one to two batches can go stale mid-frame.
+     */
+    private particleLayoutFor;
+    /** Build a plume batch: crossed quads per placement, and the material's own pipeline. */
+    createPlumes(plumes: readonly PlumePlacement[], options: PlumeOptions): GpuPlumes;
+    disposePlumes(plumes: GpuPlumes): void;
+    /**
+     * Draw a plume batch after the opaque scene.
+     *
+     * **`uClipEnabled` is zero and stays zero until planar reflections land.** `renderer.ts`
+     * passes the reflection's clip plane here so a plume is cut at the water line while the
+     * mirror pass draws it; with no reflection pass there is nothing to clip against, which is
+     * the same state a world with reflections switched off is in.
+     */
+    drawPlumes(plumes: GpuPlumes, camera: Camera, timeSeconds: number, env: Environment, windX?: number, windZ?: number, originX?: number, originY?: number, originZ?: number): void;
+    /**
+     * Build a body of water: the ocean's two sheets and a unit patch for bounded bodies.
+     *
+     * The grid's own numbers — cell size and the two extents — travel with the handle, because
+     * `resolveWater` needs them and they belong to this body rather than to the renderer.
+     */
+    createWater(resolution?: number, nearExtent?: number, farHalfExtent?: number): GpuWater;
+    /** Release a body of water. */
+    disposeWater(water: GpuWater): void;
+    /**
+     * Draw a body of water, after the opaque scene.
+     *
+     * **A mirror is used only if this frame drew one for this water plane.** `reflectionFor`
+     * answers that; where it says no, the binding takes the one-pixel stand-in and
+     * `uReflectionEnabled` is zero, which is the shader's own "no reflection" path and exactly
+     * what `renderer.ts` binds for a world with reflections switched off.
+     */
+    drawWater(water: GpuWater, camera: Camera, timeSeconds: number, settings: WaterBody, env: Environment, windX?: number, windZ?: number): void;
+    /**
+     * Chosen from the profile rather than pinned, because there are two of it and both are
+     * generated. `renderer.ts` compiles `lightVolumeFrag({ directionalShadows })` from the same
+     * field, so a profile with the sun's shadows off gets a shader with no map to read on either
+     * backend. The flat pass is still pinned to one of its sixteen; that is its own row.
+     */
+    private readonly lightVolumeVariant;
+    private readonly lightVolumeFragment;
+    private readonly lightVolumeLayout;
+    private readonly lightVolumeVertices;
+    private readonly lightVolumeFragments;
+    /**
+     * Not `readonly`, because one of the views it holds is allocated with the drawing buffer.
+     *
+     * A bind group holds views, and the depth snapshot a volume clamps against is created and
+     * destroyed by `ensureComposite` — so this is rebuilt there for the same reason `rushBindGroup`
+     * and the water's are. Built once at construction it would hold the stand-in for ever, which
+     * is a beam that still draws and never clamps.
+     */
+    private lightVolumeBindGroup;
+    /** The two things `buildLightVolumeBindGroup` needs that are settled in the constructor. */
+    private readonly volumeShadowSampler;
+    private readonly volumeBlank;
+    /** Where the camera stands in the volume, filled per draw into an object this class owns. */
+    private readonly volume;
+    /**
+     * Draw a volume of light: a closed hull, and the air inside it integrated along the view ray.
+     *
+     * **Two things are decided on the CPU and both are `resolveLightVolume`'s**: the camera in the
+     * volume's own space, which is the frame the march runs in, and whether the camera is inside
+     * the cone, which decides which half of the hull to keep. Neither is a binding, so neither is
+     * written twice — see that module.
+     *
+     * Everything else here is one draw's uniforms, and **every field is written every draw**. A
+     * ring slot holds whatever the volume that used it last frame put there, so a field left out
+     * on the grounds that the shader will not reach it is a stale value waiting for the frame
+     * where it does.
+     */
+    drawLightVolume(mesh: GpuMesh, model: ReadonlyMat4, camera: Camera, strength: number, length: number, spread: number, options?: LightVolumeDrawOptions): void;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedVolumesFull;
+    private readonly windStreakLayout;
+    /** A slot per batch, for the reason `windStreakPass.ts`'s layout gives. */
+    private readonly windStreakVerts;
+    private readonly windStreakFrags;
+    private readonly windStreakVertStaging;
+    private readonly windStreakVertFloats;
+    /** The same bytes as an `i32` view, which is what a ring slot is copied through. */
+    private readonly windStreakVertBlock;
+    private readonly windStreakFragStaging;
+    private readonly windStreakFragFloats;
+    private readonly windStreakFragBlock;
+    private readonly windStreakBindGroup;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedStreaksFull;
+    /** Refilled per call rather than allocated; see `createResolvedWindStreaks`. */
+    private readonly streaks;
+    /**
+     * Build a lattice of wind-borne debris.
+     *
+     * The thresholds are resolved here rather than left on the handle, because
+     * `windStreakDraw.ts` owns the defaults and a second copy of an onset speed is debris that
+     * appears at a different wind on one backend.
+     */
+    createWindStreaks(options?: WindStreakOptions): GpuWindStreaks;
+    disposeWindStreaks(streaks: GpuWindStreaks): void;
+    /**
+     * Draw the wind, after the opaque scene.
+     *
+     * **Whether the camera is under water is the engine's question, not the caller's**, exactly as
+     * `renderer.ts` argues: every pass already knows where the waterline is, and leaving it to
+     * each call site is how one of them ends up raining dust into the sea.
+     */
+    drawWindStreaks(streaks: GpuWindStreaks, camera: Camera, wind: WindField, timeSeconds: number, tint: Vec3, env: Environment): void;
+    private readonly flockLayout;
+    /** A slot per batch, for the reason `flockPass.ts`'s layout gives. */
+    private readonly flockVerts;
+    private readonly flockFrags;
+    private readonly flockVertStaging;
+    private readonly flockVertFloats;
+    /** The same bytes as an `i32` view, which is what a ring slot is copied through. */
+    private readonly flockVertBlock;
+    private readonly flockFragStaging;
+    private readonly flockFragFloats;
+    private readonly flockFragBlock;
+    private readonly flockBindGroup;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedFlockFull;
+    createFlock(count: number): GpuFlock;
+    disposeFlock(flock: GpuFlock): void;
+    /**
+     * Draw a flock.
+     *
+     * **No `uCameraPos`, because the shader no longer declares one.** It fed a banking term that
+     * turned a wing plane toward the viewer, reverted with the rest of the flock work when the
+     * shape being reported turned out to be a lighthouse beam; see `AGENTS.md` 2026-08-10 and the
+     * comment in `flockRenderer.ts`. Binding one here would be reintroducing it on one backend.
+     */
+    drawFlock(flock: GpuFlock, camera: Camera, timeSeconds: number, params: FlockParams, tint: Vec3, windX?: number, windZ?: number): void;
+    private readonly boltLayout;
+    /** A slot per batch, for the reason `boltPass.ts`'s layout gives. */
+    private readonly boltVerts;
+    private readonly boltFrags;
+    private readonly boltVertStaging;
+    private readonly boltVertFloats;
+    /** The same bytes as an `i32` view, which is what a ring slot is copied through. */
+    private readonly boltVertBlock;
+    private readonly boltFragStaging;
+    private readonly boltFragFloats;
+    private readonly boltFragInts;
+    private readonly boltBindGroup;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedBoltsFull;
+    createBolts(segmentCapacity: number, label?: string): GpuBolts;
+    disposeBolts(batch: GpuBolts): void;
+    /**
+     * Draw a pool of arcs.
+     *
+     * The per-frame streams are expanded by `expandBoltSegments` and written whole: three writes
+     * of the live prefix rather than one per segment, into staging allocated with the batch.
+     */
+    drawBolts(batch: GpuBolts, data: BoltSegments, camera: Camera, env: Environment, timeSeconds: number, core: Vec3, edge: Vec3, widthM: number, coreGain: number, minWidthPerMetre?: number): void;
+    private readonly lineLayout;
+    /** One slot per draw, not one block like `boltBindGroup` — see `linePass.ts`'s own comment. */
+    private readonly lineVerts;
+    private readonly lineFrags;
+    private readonly lineBindGroup;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedLinesFull;
+    /** Build a batch for a polyline. `capacity` is in segments, not points. See `boltPass.ts`'s
+     * `createBolts` for the shape; a line's batch carries two dynamic streams instead of three. */
+    createLines(segmentCapacity: number, label?: string): GpuLines;
+    disposeLines(lines: GpuLines): void;
+    /**
+     * Draw a polyline.
+     *
+     * The per-frame streams are expanded by `expandLineSegments` and written whole, the same
+     * shape `drawBolts` uses for its own three. `uModel` is the one field `LINE_VERT` carries
+     * that `BOLT_VERT` does not — see `linePass.ts`'s own comment for why: an arc has no model
+     * transform and a line, usually attached to something that moves, does.
+     *
+     * Takes a slot from `lineVerts`/`lineFrags` rather than writing a single shared block —
+     * `MAX_OVERLAYS` draws a frame, the same ceiling `drawSdfText` uses, because a caller drawing
+     * more than one polyline a frame (several trails, a waveform split into pieces) is the normal
+     * case here rather than the exception a single bolt pool is.
+     *
+     * **The uniforms are ringed; `lines.fromBuffer`/`.toBuffer` are not.** See `createLines`'s own
+     * comment for the contract that protects them instead: this handle's geometry must not change
+     * between two draws of it inside one frame, because these two buffers get exactly one write
+     * each here, and a second write before the frame's command buffer submits silently replaces
+     * the first for every draw already recorded against it.
+     */
+    drawLines(lines: GpuLines, data: LineSegments, model: ReadonlyMat4, camera: Camera, env: Environment, color: Vec3, widthM: number, opacity: number, softness?: number, minWidthPerMetre?: number, additive?: boolean): void;
+    /** Built on first use per material, because the three fragment blocks are different sizes. */
+    private readonly particleLayoutByMaterial;
+    private readonly plumeLayout;
+    /** One slot per batch, because `sizePulse` and `windResponse` belong to the batch. */
+    private readonly plumeVerts;
+    private readonly plumeFrags;
+    private readonly plumeBindGroup;
+    private readonly waterLayout;
+    /** The one-pixel stand-in, kept so the water bind group can be rebuilt without one. */
+    private readonly blankView;
+    private readonly blankSampler;
+    /**
+     * A slot per body, not one buffer rewritten before each draw.
+     *
+     * **A frame draws more than one body of water.** A ditch at its own level, a basin in a
+     * courtyard and the sea behind them are three draws off one pass, and from a single buffer the
+     * last write won all three: every body then wore the last one's extents, level, colours and
+     * direction. `UniformRing`'s header describes the hazard in general and `AGENTS.md` records it
+     * on 2026-08-27 as a hard rule; water was the pass still holding it, and it was invisible for
+     * as long as nothing drew two — the same reason a single character hid the joint palette's
+     * copy of this for eight releases.
+     */
+    private readonly waterVerts;
+    private readonly waterFrags;
+    private readonly waterVertStaging;
+    private readonly waterVertFloats;
+    private readonly waterVertBlock;
+    private readonly waterFragStaging;
+    private readonly waterFragFloats;
+    private readonly waterFragInts;
+    /** Said once when a frame asks for more bodies than the ring holds. */
+    private warnedWaterFull;
+    /**
+     * Rebuilt whenever the reflection target is, because a bind group holds the *view* and a
+     * resized target is a new texture. Not readonly for that reason alone.
+     */
+    private waterBindGroup;
+    /** Refilled per draw rather than allocated; see `createResolvedWater`. */
+    private readonly resolvedWater;
+    private readonly scatterLayout;
+    /** One slot per batch: the gust and the trample field belong to the batch, not the frame. */
+    private readonly scatterVerts;
+    private readonly scatterFragUniforms;
+    private readonly scatterFragStaging;
+    private readonly scatterFragFloats;
+    private readonly scatterFragInts;
+    private readonly scatterBindGroup;
+    private readonly scatterDepthLayout;
+    /**
+     * A slot per scatter draw, not one buffer rewritten before each of them.
+     *
+     * **The point light's bake is what makes this load-bearing.** Six cube faces are recorded on
+     * one encoder and submitted once, so a `queue.writeBuffer` between two of them lands ahead of
+     * all six — every scatter batch in every face then draws under the *last* face's
+     * `uLightViewProj`. Five sixths of a field of grass therefore went into the octahedral map at
+     * directions the grass does not occupy, and what the shader read back out of them is an
+     * occluder standing beside a lamp with nothing above it. The reported symptom was a
+     * hard-edged patch of shadow near a brazier, on this backend only, gone the moment lamp
+     * shadows were switched off — the other backend sets a uniform and draws, in that order,
+     * so it never had it.
+     *
+     * `UniformRing`'s own header describes this failure in general and `scatterVerts` already
+     * carried the fix for the *visible* scatter pass; only the depth half was left behind.
+     */
+    private readonly scatterDepthDraws;
+    private readonly scatterDepthStaging;
+    private readonly scatterDepthFloats;
+    /** The same bytes as an integer view, so a whole block copies into a slot bit for bit. */
+    private readonly scatterDepthBlock;
+    private readonly scatterDepthBindGroup;
+    /** Refilled per draw rather than allocated; see `createScatterDeform`. */
+    private readonly deform;
+    /**
+     * The frame's wind, as the mesh and depth programs read it.
+     *
+     * A second target from `deform` above and one conversion between them, for the reason the
+     * WebGL2 backend gives at the same field: the scatter batch takes its wind as arguments to its
+     * own draw call and cannot share a target without that signature changing, but both go through
+     * `resolveScatterDeform`, which is where every number is actually decided.
+     */
+    private readonly frameWind;
+    /**
+     * The frame's wind, sampled once by the caller and handed down.
+     *
+     * Every mesh carrying a per-vertex channel bends to this, in the colour pass and in the depth
+     * pass, so a canopy and its own shadow move together. A caller that never calls it gets a still
+     * world, which is what every scene drew before the channel existed.
+     */
+    setWind(windX: number, windZ: number, windGust: number, timeSeconds: number): void;
+    /**
+     * The five wind fields of one shadow-draw slot.
+     *
+     * The rigid and skinned depth variants declare these; the instanced one does not, and nothing
+     * writes this for it. A canopy that bends in the picture and stands still in the shadow map
+     * slides its shade off the ground, which is the defect scatter.ts records having fixed between
+     * its own two programs.
+     */
+    private writeShadowWind;
+    /**
+     * The five wind fields of one per-draw slot.
+     *
+     * **Never called for an instanced draw.** That variant declares none of these, and
+     * `flatPass.ts` records what writing a field a variant does not declare costs: the block is
+     * shorter, so the write lands on whatever occupies that offset instead.
+     */
+    private writeWind;
+    /** Refilled per frame rather than allocated; see `resolvePointLights`. */
+    private readonly lights;
+    /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
+    private readonly medium;
+    private readonly panelLayout;
+    private readonly panelCorners;
+    private readonly panelVerts;
+    private readonly panelFrags;
+    private readonly panelBindGroup;
+    private readonly textLayout;
+    private readonly textCube;
+    private readonly textVerts;
+    private readonly textFrags;
+    private readonly textBindGroup;
+    /**
+     * SDF text, world geometry rather than an overlay — see `drawSdfText`.
+     *
+     * **A bind group per atlas, cached, matching `flatBindGroups`' own reasoning.** A scene
+     * reuses one font's atlas across every label built from it, so building a fresh bind group
+     * per draw would be exactly the per-frame allocation `AGENTS.md` forbids for the common case
+     * of two labels sharing a font.
+     */
+    private readonly sdfTextLayout;
+    private readonly sdfTextVerts;
+    private readonly sdfTextFrags;
+    private readonly sdfTextBindGroups;
+    private readonly shadowMap;
+    private readonly shadowView;
+    private readonly shadowLayout;
+    /** The same layout plus the joint palette. See `createDepthBindGroupLayout`. */
+    private readonly shadowSkinnedLayout;
+    /**
+     * The skinned shadow bind groups, one per palette slot, cached against what can invalidate them.
+     *
+     * The same argument `flatBindGroupFor` makes, and per slot for the same reason: the group it was
+     * built beside, and the palette view, which now differs between two characters casting into one
+     * bake. Comparing object identity makes a missed invalidation impossible rather than unlikely.
+     */
+    private readonly shadowSkinnedGroups;
+    private readonly shadowSkinnedGroupsBeside;
+    private readonly shadowSkinnedGroupsPalette;
+    /** Held from construction so the skinned group can be rebuilt without them being threaded. */
+    private shadowBlankView;
+    private shadowBlankSampler;
+    private shadowPassUniforms;
+    private readonly shadowBindGroup;
+    /**
+     * The second static layer, or null where the profile asks for one depth layer.
+     *
+     * Null on the same condition `renderer.ts` builds its `peeledShadowMap` on — one decision,
+     * read twice — so a profile that switches peeling off gets no map and no pass on either
+     * backend rather than a map nothing writes.
+     */
+    private readonly peelMap;
+    private readonly peelView;
+    /**
+     * The movers' own layer: the character, the rope it swings on, and anything else that walks.
+     *
+     * **Its own map rather than more geometry in the static one**, which is the decision
+     * `renderer.ts` made and states: where a moving and a static caster overlap, two independent
+     * layers keep each one's own distance fade and multiply their transmissions, where a single
+     * depth buffer would keep whichever is nearer and throw the other away. It is also what lets
+     * the static layer be drawn from geometry that does not change while this one is redrawn per
+     * frame.
+     *
+     * Null on the same condition `renderer.ts` builds its `dynamicShadowMap` on — directional
+     * shadows at all — so one decision is read twice rather than restated.
+     *
+     * **This backend had no such map and `beginShadowPass('dynamic')` returned false**, so every
+     * mover's shadow was silently absent while every static one was drawn. Reported from a consumer
+     * exactly that way: *"sun shadow works for other than the character itself"*. It degraded
+     * honestly — `uDynamicShadowMap` resolved to the white stand-in, which reads as the far plane
+     * and therefore as lit — so nothing looked broken, only empty, which is why it survived the
+     * port and every gate in it.
+     */
+    private readonly dynamicMap;
+    private readonly dynamicView;
+    /** The peel's own bind groups: `uPeelShadowLayer` at 1, and the static map to peel against. */
+    private readonly shadowPeelBindGroup;
+    private readonly scatterDepthPeelBindGroup;
+    /** Which layer the open pass is writing, so the sink picks the bindings that match it. */
+    private shadowLayerIsPeel;
+    /**
+     * Whether a peel pass has filled the map, which is what the frame may sample it on.
+     *
+     * **Not whether the map exists.** `renderer.ts` can ask that question because a GL texture is
+     * born cleared; a WebGPU texture no pass has written holds undefined contents, so a scene
+     * that builds a peel map and never opens the layer would sample garbage. Cleared when the
+     * static layer opens and set when a peel pass ends, which is per frame because both demo
+     * scenes that peel do so every frame.
+     */
+    private peelFilled;
+    /** One slot per caster, the same trick `perDraw` uses and for the same reason. */
+    private readonly shadowDraws;
+    private shadowEncoder;
+    private shadowPass;
+    /**
+     * Which faces the depth pass culls, because the two shadow passes want different answers.
+     *
+     * The directional map culls `back`, matching the frame. A cubemap face culls nothing, and
+     * `pointShadowMap.ts` gives the reason: back faces only stores the far side of every caster,
+     * and for a character's limbs the two sides are centimetres apart, so the caster effectively
+     * vanishes from the map. It is on the key as well as on the pipeline, or the second pass
+     * would get the first one's.
+     */
+    private depthCullMode;
+    /**
+     * The light's matrix under `SHADOW_CLIP_CORRECTION`, once per pass rather than once per
+     * caster. Depth remapped to [0, 1]; **Y deliberately not flipped** — see that constant for
+     * the texel-for-texel comparison that settled it.
+     */
+    private readonly correctedLightViewProj;
+    /**
+     * The same matrix *uncorrected*, which is what the flat shader must project with.
+     *
+     * **The two differ on purpose and getting it wrong mirrors every shadow**, which is not a
+     * figure of speech: it happened, and the two maps were measured as exact mirrors. The lookup
+     * in `flat.ts` is `p = p * 0.5 + 0.5` on all three axes, the OpenGL convention, and it
+     * expects `vLightPos` in GL clip space.
+     *
+     * The map is rendered with the depth half of the correction and not the Y half, and the
+     * depth halves are what make the pair agree: the render stores 0.5·z + 0.5 and the lookup
+     * computes 0.5·z + 0.5, so a receiver and its occluder are on one scale.
+     */
+    private readonly lightViewProj;
+    /**
+     * The bindings for the layer currently open — the peel's where one is, the static pass's
+     * otherwise. A lookup rather than a rebind, because a `createBindGroup` per draw is the
+     * per-frame allocation the house rules forbid; both groups are built once at init.
+     */
+    private shadowGroup;
+    /**
+     * The skinned shadow bind group for the current layer, rebuilt only when it must be.
+     *
+     * **The peel layer is not served here and casts rigidly**, deliberately: the peel exists so a
+     * second independently fading occluder can be recorded, and a character is not one — it is the
+     * thing in front. Serving it would mean a second cached group for a case nothing produces.
+     */
+    private shadowSkinnedGroup;
+    private scatterDepthGroup;
+    /**
+     * Where a caster is drawn from, given to `drawShadowCasters` as the engine's own sink.
+     *
+     * Built once and held, rather than made per call: it closes over `this` and a fresh one
+     * every frame would be an allocation in a per-frame path.
+     */
+    private readonly casterSink;
+    /** Said once rather than every frame, because a full ring is a flood otherwise. */
+    private warnedFull;
+    /** The same, for the shadow round's scatter ring. See `scatterDepthDraws`. */
+    private warnedScatterDepthFull;
+    /** The density ceiling a governor has asked for, applied on the next resize. */
+    private scale;
+    /** The density ceiling in effect, matching the WebGL2 renderer's accessor. */
+    get resolutionScale(): number;
+    /**
+     * Side of the directional shadow map, in texels.
+     *
+     * **A scene divides by this, so its absence is not an absence — it is a NaN.** Every caller
+     * reaches `computeLightMatrix`, which computes `texelWorldSize = radius * 2 / shadowMapSize`
+     * to snap the light frustum to the texel grid. `undefined` there makes the snap NaN, and the
+     * NaN reaches all sixteen entries of the light matrix through `mat4.ortho`.
+     *
+     * That is what "the whole scene comes out uniformly occluded" was. Both halves of the shadow
+     * path were poisoned by it and neither of them was wrong: the depth pass drew a caster whose
+     * every vertex was NaN, so nothing rasterised and the map stayed at its clear value — read
+     * back on hardware as 4,194,304 texels of exactly 1.0 — while the flat pass projected the
+     * receiver with the same NaN, and `shadowFactor` compares with `<=`, which is false against
+     * a NaN, so every fragment fell past the four early returns into the filter loop and out of
+     * it as NaN.
+     *
+     * **It was diagnosed as the shadow *sample* returning a constant, and that was wrong.** The
+     * evidence was that substituting the clip-corrected light matrix for the uncorrected one
+     * changed not one pixel, which looked like proof the lookup ignored its projection. Both
+     * matrices were NaN; a correction applied to a NaN is a NaN, so the test could not have
+     * distinguished them.
+     *
+     * **The general hazard, which is worth more than this accessor.** A missing *method* on this
+     * class throws — `renderer.createMesh is not a function` is how the backend announced itself
+     * reaching a browser at all. A missing *property* returns `undefined`, and `undefined` in
+     * arithmetic is a picture rather than an error. The rest of that group is below, and they
+     * are grouped deliberately: the hazard is the class, not this one member of it.
+     */
+    get shadowMapSize(): number;
+    /** Viewport in CSS pixels, which is what a screen-space overlay lays out against. */
+    get cssWidth(): number;
+    get cssHeight(): number;
+    /** Drawing-buffer aspect, guarded against a zero-height canvas exactly as WebGL2 guards it. */
+    get aspect(): number;
+    /** The canvas being drawn into, for a consumer that needs to measure or place against it. */
+    get canvas(): HTMLCanvasElement;
+    /**
+     * Whether the device has gone.
+     *
+     * Named for the WebGL concept because that is what the shared surface calls it, and the two
+     * failures are the same event to a consumer: `device.lost` here, `webglcontextlost` there.
+     * `device.ts` already absorbed the difference in shape.
+     */
+    get contextLost(): boolean;
+    /**
+     * Whether a part this backend recognises as weak had its pixel terms lowered at construction.
+     *
+     * **This used to be a hardcoded `false`**, because `rendererName` was the literal string
+     * `WebGPU` and `isWeakGpuFamily` had nothing to match — so the clamp that rescued an
+     * Adreno 619 on WebGL2 was dead on the backend that replaced it, and `capabilityClamp: true`
+     * from a consumer silently did nothing. `select.ts` now builds the name from `adapter.info`,
+     * so the same predicate over the same table answers on both backends.
+     *
+     * Only the pixel terms move, exactly as in `renderer.ts`: the shadow and water switches are
+     * what a preset *means*, and drawing a different scene than the settings screen describes is
+     * worse than drawing the right one at fewer pixels.
+     */
+    readonly capabilityClamped: boolean;
+    /** Zero until row 3 ports the point-shadow cube maps, and zero is what WebGL2 reports then too. */
+    get sampledShadowLights(): number;
+    /**
+     * The full budget, always, and that is a fact about the backend rather than a stub.
+     *
+     * WebGL2 sizes these arrays to what the part's fragment uniform grid will hold — see
+     * `uniformVectorBudget.ts` — because a shader declaring more rows than the device offers does
+     * not link. WebGPU has no such ceiling to be short of: the lit block is about 7 KB against a
+     * guaranteed 64 KB binding size, and the generated WGSL is built and committed at the full
+     * budget either way. So a consumer who lowered `maxLights` for a phone's WebGL2 path and lands
+     * on WebGPU gets all sixteen, which is the better picture and one this device can afford.
+     */
+    get shadedLights(): number;
+    /** All four, for the reason `shadedLights` gives. */
+    get shadedAreaLights(): number;
+    /**
+     * **True from the first presented frame, which is weaker than what WebGL2 means by it.**
+     *
+     * There it is a fence: `clientWaitSync` on the first frame's commands, so it turns true when
+     * the driver has actually finished the first frame's compiles and uploads, which is what a
+     * loading screen wants to wait for. The equivalent here is `onSubmittedWorkDone`, and wiring
+     * it is row 24's business alongside the timestamp queries.
+     *
+     * Reported as "a frame has been presented" until then. A consumer polling this gets a true
+     * that is early rather than one that never arrives, and early is the failure that shows a
+     * loading screen dismissed a little too soon rather than one that hangs forever.
+     */
+    get firstFrameSettled(): boolean;
+    private presentedAnyFrame;
+    /** Whether the loss below has already been said. Said once, never once per frame. */
+    private reportedLost;
+    /**
+     * Say, exactly once, that this renderer is drawing nothing and why.
+     *
+     * **A lost device is silent here, and that silence is the defect.** Every entry point guards
+     * on `surface.lost` and returns, so a frame loop goes on calling forty of them at full rate
+     * and produces a black canvas with no error, no exception and no warning. A host that is not
+     * already listening to `onContextLost` has no way to tell that apart from a rendering bug —
+     * which is what happened: a demos page showed a black frame indefinitely and reported it as a
+     * broken renderer.
+     *
+     * WebGPU cannot restore a device, only replace one, so the recovery is a consumer's to
+     * perform. This makes sure the consumer at least knows there is something to recover from,
+     * and names the call that does it.
+     */
+    private reportLostOnce;
+    /**
+     * The colour this frame clears to, held until the frame's pass is actually opened.
+     *
+     * A preallocated tuple rather than the caller's, because `beginFrame` runs every frame and
+     * keeping a reference to a consumer's array would let them mutate it under us.
+     */
+    private readonly pendingClearColor;
+    /** What `beginPlanarReflection` was asked to clear the mirror to, held until it opens. */
+    private readonly mirrorClearColor;
+    /** Whether the frame's pass still owes its clear. False from the first open onwards. */
+    constructor(surface: GpuSurface, quality?: Readonly<RenderQuality>, rendererName?: string);
+    /**
+     * The height the medium is resolved at, which is the *viewer's* and not the camera's.
+     *
+     * They are the same except inside the mirror pass, where the camera stands as far below the
+     * water as the viewer stands above it. Resolving fog from that puts the whole reflection
+     * underwater whenever the viewer is not, and the result is a pool that reads as filled with
+     * the wrong medium rather than as a camera in the wrong place. `renderer.ts` keeps
+     * `reflectionAtmosphereY` for exactly this and passes it to four binders.
+     */
+    private atmosphereHeight;
+    /**
+     * One array of the block, at the stride the generator declared.
+     *
+     * Element by element rather than `set`, for the reason `scatterInto` gives: an array element
+     * in one of these blocks has its own slot, and a straight fill would lay ten answers across
+     * the first two and a half.
+     */
+    private writeShadowParams;
+    /** The index and the weight of one selection array, which are always written together. */
+    private writeShadowSelection;
+    /**
+     * Say that no light in one selection array owns a cubemap.
+     *
+     * Written per element at the block's declared stride rather than filled, for the reason
+     * `scatterInto` gives: an array element in one of these blocks has its own sixteen-byte slot
+     * and a straight fill would lay ten answers across the first two and a half.
+     */
+    private clearShadowSelection;
+    /** Which optional attributes a mesh supplied, recovered from its buffers for the depth pass. */
+    private presentOf;
+    /**
+     * Open the frame and clear to the sky.
+     *
+     * **Every entry point returns early on a lost device rather than throwing.** A consumer's
+     * `requestAnimationFrame` loop keeps calling after a driver reset, and `AGENTS.md`'s rule
+     * that the frame loop never throws is what stops that turning one GPU fault into sixty
+     * uncaught exceptions a second in somebody's error reporting.
+     */
+    beginFrame(clearColor: Vec3): void;
+    /**
+     * The depth buffer, rebuilt only when the drawing buffer changes size.
+     *
+     * WebGPU has no depth attachment of its own the way a default framebuffer does, so one is
+     * owned here. Rebuilding it every frame would allocate in the frame loop; rebuilding it
+     * never would mean a resized canvas draws against a depth buffer of the old size, which is
+     * a validation error rather than a wrong picture.
+     */
+    private ensureDepth;
+    /**
+     * Upload the frame's geometry, build one mesh's buffers, and hand back a handle.
+     *
+     * Construction time, never per frame: `MeshData` arrays are the caller's and are uploaded
+     * once. The pipeline is built here too, for the same reason — which attributes a mesh
+     * supplied decides the vertex layout, so it is known now and never recomputed.
+     */
+    /**
+     * Compile every pipeline this mesh can be drawn with, and say which key it draws under.
+     *
+     * Shared by the two `createMesh` entry points, because warming is decided by the *data* and
+     * neither the pipeline set nor the key depends on whether the geometry lands in one call or
+     * over six frames.
+     */
+    private warmFlatPipelines;
+    /**
+     * The pipeline key stapled to a mesh, on the mesh itself.
+     *
+     * **Not a spread**, which is what this was. `{ ...mesh, key }` copies the value a getter held
+     * at that instant, so `complete` would have been frozen at whatever it was when the mesh was
+     * made — false, for every incremental mesh, for ever, and nothing spread would ever have been
+     * drawn. It also handed the caller a different object from the one the upload was filling.
+     */
+    private keyed;
+    createMesh(data: MeshData, options?: MeshOptions): GpuMesh;
+    /**
+     * Geometry in, handle out — but the geometry lands over as many frames as the caller gives it.
+     *
+     * See `RendererApi.createMeshIncremental` for what this is for and what a caller may do with a
+     * mesh that has not finished arriving. The iterator here adds the one thing the buffer code
+     * cannot know about: **a lost device ends the upload.** An upload that spans frames can
+     * straddle one, and going on writing to a dead device would raise validation errors a consumer
+     * can do nothing about. Done with `complete` still false is the signal that it was abandoned.
+     */
+    createMeshIncremental(data: MeshData, options?: MeshOptions): IncrementalMeshHandle;
+    /**
+     * Rewrite a mesh's positions, and its normals where the caller has them.
+     *
+     * Refused in words on a mesh that did not declare itself dynamic, because the thing that makes
+     * an update possible on this backend — the interleaved array the vertex data was built from —
+     * is only kept when a consumer asked for it. See `GpuMesh.update`.
+     */
+    updateMesh(mesh: GpuMesh, positions: Float32Array, normals?: Float32Array): void;
+    /**
+     * Settle everything the frame shares: the camera, the lights and the fog.
+     *
+     * Written into the fragment block at the offsets the generator computed, which is the one
+     * place these numbers are stated. The vertex block's `uViewProj` is copied into every
+     * draw's slot instead, because a dynamic-offset binding cannot mix per-frame and per-draw
+     * data in one buffer.
+     */
+    bindMeshPass(camera: Camera, env: Environment): void;
+    /**
+     * The slot the next draw's material lives in, taking a new one when something dirtied it.
+     *
+     * **A copy per material change, not per draw.** A scene drawing a hundred meshes of one
+     * material spends one slot and one copy; a scene switching material every draw spends one
+     * each, which is what it asked for.
+     */
+    private materialSlotForDraw;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedMaterialsFull;
+    /**
+     * Draw one mesh.
+     *
+     * Takes a slot from the ring for its own model matrix and tint, so that draws do not
+     * overwrite each other's uniforms — see `UniformRing` for why a single buffer cannot work.
+     */
+    /**
+     * `depthLayer` reaches a pipeline here, where it used to be accepted and dropped.
+     *
+     * It was `_depthLayer` for as long as this backend has existed: the parameter was on the
+     * interface, the other backend honoured it, and a consumer that declared which of two fused
+     * surfaces should win got the answer on WebGL2 and a per-pixel coin toss here — with nothing
+     * failing and nothing in the parity ledger saying so.
+     */
+    drawMesh(mesh: GpuMesh, model: ArrayLike<number>, depthLayer?: number, tint?: Vec3 | null): void;
+    /**
+     * Draw a mesh that lets the world through, at `opacity`.
+     *
+     * Its own pipeline rather than a blend toggle, because WebGPU bakes blend state into one —
+     * see `flatPipeline`. `uOpacity` is material state like every other term the shader reads per
+     * draw, so it takes a material slot and is put back afterwards; `renderer.ts` restores it to
+     * 1 for the same reason.
+     *
+     * `options` turns lighting and fog off independently, without a second pipeline: see
+     * `TranslucentMeshOptions` and `submitMesh` for how each rides the same material slot
+     * `uOpacity` already uses. Both default to `true`, so this reads identically for every call
+     * site that predates the parameter.
+     */
+    /**
+     * Mark whatever the depth buffer holds inside a projector's box.
+     *
+     * The WebGL2 renderer's own `drawDecal` carries what this is for and what it costs; the two
+     * record the same thing and draw it in the same place in the frame. Silently nothing where the
+     * profile has no screen effects, since there is then no resolved depth to read.
+     */
+    drawDecal(projector: DecalProjector): void;
+    /**
+     * Reflect what the frame drew, in the surfaces inside a box.
+     *
+     * The WebGL2 renderer's own `drawReflection` carries what this is for and what it cannot do; the
+     * two record the same thing and trace it in the same place in the frame.
+     */
+    drawReflection(surface: ReflectiveSurface): void;
+    /** Said once, not per frame, where this renderer cannot read the picture a march samples. */
+    private refuseReflections;
+    /**
+     * Said once, not per frame, where this renderer cannot read the depth a mark is decided from.
+     *
+     * **Called from `endFrame` as well as from the pass, and that is not belt and braces.** A
+     * profile with no screen effects never opens a composite at all, so `runDecals` is never reached
+     * and the marks would be dropped in silence — while the other backend, whose decal block sits in
+     * its own `endFrame`, says so. One backend explaining itself and the other not is the
+     * disagreement the parity rule exists to prevent, and it is what the first run of
+     * `scripts/decal-check.mjs` caught here.
+     */
+    private refuseDecals;
+    /**
+     * Said once, not per frame, where multisampling excludes the effect a profile asked for.
+     *
+     * **The comment above the decision has claimed since the effect shipped that it "says so once",
+     * and for two releases nothing did.** Both are switches on a graphics screen, so a player
+     * turning antialiasing on turns this off — and a quality setting that is enabled and does
+     * nothing is the fault this engine has now shipped under three other names. `refuseDecals`
+     * carries the argument for why the *other* backend saying it and this one not is worse than
+     * neither saying it; the words are `OIT_MULTISAMPLE_REFUSAL`, which both backends read rather
+     * than each keeping a copy.
+     */
+    private refuseOitMultisampled;
+    drawTranslucentMesh(mesh: GpuMesh, model: ReadonlyMat4, opacity: number, options?: TranslucentMeshOptions): void;
+    /**
+     * @param blend Which of the two entry points above this came through, and **not** something to
+     * infer from `opacity`.
+     *
+     * `outColor.a` is `uOpacity * coverage`, and `coverage` is the bound texture's own alpha. So a
+     * caller passing an opacity of 1 to `drawTranslucentMesh` is not saying *opaque*, it is saying
+     * *the shape is in the image*: a caption, a decal, a painted shadow, a glow. Reading that as
+     * opaque takes the unblended pipeline, and then every texel the cutout kept is written at full
+     * strength — the soft edge of a blurred shadow lands as a solid slab bounded by the cutout's
+     * iso-contour. One consumer's cover visualiser drew its caption that way: a hard black outline
+     * around every letter, and none in the same frame on `?backend=webgl2`.
+     *
+     * The other backend has no way to make this mistake, and that is the parity being kept rather
+     * than a new rule: `renderer.ts` enables `BLEND` on the way into `drawTranslucentMesh` and
+     * disables it on the way out, without ever consulting the number.
+     *
+     * @param options `drawMesh` passes only `depthLayer` and takes the `bindMeshPass` default of
+     * lit and fogged for the rest. `uLightingEnabled`/`uFogEnabled` are material
+     * state exactly like `uOpacity` above them — dirtied while they differ from the default and
+     * restored unconditionally afterward, whether or not a material slot was available for this
+     * particular draw to use them. Never a pipeline permutation.
+     */
+    private submitMesh;
+    /** Release geometry. */
+    disposeMesh(mesh: GpuMesh): void;
+    /**
+     * Attach per-instance placement to a mesh already on the device.
+     *
+     * One batch per mesh is not enforced here — this backend could hold several, since the
+     * instance buffer is bound per draw rather than baked into a vertex array — but it is refused
+     * anyway, because WebGL2 *cannot* and a capability one backend has and the other does not is
+     * the shape this repository spent a week removing.
+     */
+    createInstanced(mesh: GpuMesh, capacity: number): GpuInstancedBatch;
+    /** Which meshes already carry a batch, so a second is refused rather than silently shared. */
+    private readonly instanced;
+    /** Push placement and colour. Only the live prefix; see `GpuInstancedBatch.upload`. */
+    uploadInstanced(batch: GpuInstancedBatch, data: MeshInstances): void;
+    /** Draw every live instance, opaque. */
+    drawInstanced(batch: GpuInstancedBatch, data: MeshInstances): void;
+    /** Draw every live instance, blended. See `drawTranslucentMesh` for what the options mean. */
+    drawTranslucentInstanced(batch: GpuInstancedBatch, data: MeshInstances, opacity: number, options?: TranslucentMeshOptions): void;
+    /** Release the placement. The mesh is the caller's and is not released. */
+    disposeInstanced(batch: GpuInstancedBatch): void;
+    /**
+     * One draw, one material slot, one uniform slot, however many instances.
+     *
+     * **The uniform slot carries only what the instanced block declares.** That variant has no
+     * `uModel` and no `uTint` — they arrive as attributes — so this writes the four fields the two
+     * variants share and nothing else. Their offsets are identical by construction and
+     * `flatPass.ts` asserts it; writing `uModel`'s plain offset here would land in a part of the
+     * slot the shader does not read, which is harmless and still wrong to do.
+     *
+     * **What it gives up** against `drawMesh` is skinning and morphing, refused where the variant
+     * is built, and a per-instance opacity: `opacity` here dims the whole batch.
+     */
+    private submitInstanced;
+    /** Upload a base mesh and size its per-instance buffers. See `createGpuScatter`. */
+    createScatter(base: MeshData, data: InstanceData): GpuScatter;
+    /**
+     * Push placement to the device.
+     *
+     * Returns the batch so `createScatter` can upload in one expression. Only the live prefix
+     * is written — `data.count` instances of a buffer sized for `capacity` — because the rest
+     * is not drawn and uploading it would be the per-frame waste `uploadScatter` exists to
+     * make visible.
+     */
+    uploadScatter(scatter: GpuScatter, data: InstanceData): GpuScatter;
+    /** Release a batch. */
+    disposeScatter(scatter: GpuScatter): void;
+    /**
+     * Draw every live instance of a batch, in one call.
+     *
+     * **Its own uniform buffers rather than the flat pass's**, because it is a different
+     * program with a different block: the vertex stage here carries the wind and the trample
+     * ring, and the fragment stage carries lighting and the medium and nothing else.
+     */
+    drawScatter(scatter: GpuScatter, data: InstanceData, camera: Camera, env: Environment, windX: number, windZ: number, windGust: number, timeSeconds: number, trample?: Float32Array | null): void;
+    /**
+     * Move the drawing-buffer density ceiling, as a governor does to hold a frame budget.
+     *
+     * Stored and applied on the next `resize`, which is where the WebGL2 path applies it too.
+     */
+    applyResolutionScale(scale: number): void;
+    /**
+     * Open the shadow pass: the world about to be drawn from the light's point of view.
+     *
+     * **Its own encoder, because a scene calls this before `beginFrame`.** The ordering is the
+     * scene's — shadows are baked, then the frame is drawn against them — and this backend
+     * follows it rather than reorganising it.
+     *
+     * All three layers, which is what the shader multiplies together. The `dynamic` one used to
+     * return false here — see `dynamicMap` for what that cost and why nothing caught it.
+     */
+    beginShadowPass(lightViewProj: ReadonlyMat4, layer?: ShadowLayer): boolean;
+    /** Submit everything that casts into the layer `beginShadowPass` opened. */
+    /**
+     * The same enumeration, replayed into the colour pass that is open.
+     *
+     * See `SceneCasters` in `shadowCasters.ts` for why this exists and why scatter is declined. The
+     * sink is built once and held, because a caster enumeration runs per pass and a sink allocated
+     * per call would allocate per pass.
+     */
+    private readonly sceneCasterSink;
+    /**
+     * The material the open replay has bound, or `undefined` before its first entry.
+     *
+     * `ShadowCasterSink`'s material is optional and omitting it means *no material* rather than
+     * *unchanged*, so a run of entries sharing one material has no shorter spelling and the sink
+     * bound once per entry. On this backend that is a cliff rather than a slope: `setMaterial`
+     * dirties `materialSlot`, so a bind per entry is a **slot per draw** out of
+     * `MAX_MATERIALS_PER_FRAME` — and past the ring `materialSlotForDraw` returns null and the draw
+     * is skipped, which is the world that appears and disappears that constant's own comment
+     * describes. A consumer measured 82 materials a model over two to four draws each, and a
+     * reflection replaying the frame shares the ring with the pass that recorded it.
+     *
+     * **Reference identity, not a deep compare.** A caster list holds the material objects its draws
+     * bound, so a run from one surface is literally one object; two structurally equal materials from
+     * different surfaces are rare and cost exactly what they cost today.
+     *
+     * `undefined` rather than `null` for "nothing bound yet", because `null` is a material an entry
+     * can legitimately ask for — it is what an entry carrying no material means.
+     */
+    private sceneCasterMaterial;
+    /** Bind one replay entry's material, unless it is the one already standing. */
+    private bindSceneCasterMaterial;
+    /**
+     * Draw everything a caster enumeration contains into the open colour pass, with its materials.
+     *
+     * The colour counterpart of `drawShadowCasters`, so one closure answers "what is in this frame"
+     * for the shadow cascade, every cubemap face, and a second viewpoint such as a mirror or a probe
+     * face. What it replaces is a consumer re-entering its whole draw path with a second camera.
+     */
+    drawSceneCasters(casters: ShadowCasters): void;
+    drawShadowCasters(casters: ShadowCasters): void;
+    /** Close the shadow pass and submit it, so the frame can sample what it wrote. */
+    endShadowPass(): void;
+    /**
+     * The pool, or null where the profile switched cube shadows off.
+     *
+     * `PointShadowSystem` over `GpuPointShadowMap`: the pooling, the staleness and the crossfade
+     * are the same code the WebGL2 path runs, and only the cubemap is this backend's. See
+     * `PointShadowSource`.
+     */
+    private readonly pointShadows;
+    /** A world's casting rectangles, on layers above the pool in the same array. See `renderer.ts`. */
+    private readonly areaShadows;
+    private readonly resolvedAreaShadows;
+    private readonly areaBakeScratch;
+    private warnedAreaShadowRange;
+    private warnedAreaShadowsOff;
+    private warnedAreaShadowLayers;
+    /** How many point lights the array was last sized for; see the other backend's copy. */
+    private preparedPointLightCount;
+    /** See `renderer.ts`: built when a world reports its lights, and rebuilt only to grow. */
+    private pointShadowArray;
+    private readonly bakeScratch;
+    /** Said once per renderer; see `updatePointShadows`. */
+    private warnedNoPointShadowArray;
+    /** Said once, for the retired ambient dial. */
+    private warnedEnvironmentAmbient;
+    private readonly castingWorldIndices;
+    private readonly resolvedPointShadows;
+    /** One face's view-projection, rebuilt per face rather than allocated. */
+    private readonly faceViewProj;
+    /** The corrected copy the vertex stage is handed. See `SHADOW_CLIP_CORRECTION`. */
+    private readonly correctedFaceViewProj;
+    /** Size the pool once the world reports its light count. Nothing is baked here. */
+    prepareStaticPointShadows(lights: readonly ShadowLight[], 
+    /** The world's rectangles, so the casting ones get layers. See `renderer.ts`. */
+    areaLights?: readonly AreaLightSource[]): void;
+    /** Say once that a rectangle asked to cast and named no range. See `renderer.ts`. */
+    private warnAreaShadowRange;
+    /**
+     * Say once that a rectangle wants layers the array was not sized for.
+     *
+     * **This is the area-light shape of the failure `updatePointShadows` warns about above**, and it
+     * is just as quiet: `prepareStaticPointShadows` sizes the array — `texStorage3D` and
+     * `createTexture` are both immutable — so a consumer that passes its rectangles here and not
+     * there gets an array with no room above the pool. Every declaration is then honoured except the
+     * storage, the set holds no maps, every layer publishes -1, and the frame is indistinguishable
+     * from one whose rectangles declined to cast.
+     */
+    private warnAreaShadowLayers;
+    /** Say once that a rectangle asked to cast while the array it would read is off. */
+    private warnAreaShadowsOff;
+    /**
+     * Refresh the cubemaps this frame's budget allows, and settle what the shader will sample.
+     *
+     * Every decision here is shared: `selectCastingLights` keeps a light that declined to cast
+     * out of the pool, `sync` hands out slots, `updateLiveSelection` runs the crossfade, and
+     * `runPointShadowBakes` spends the face budget in the order a measured frame chose. What is
+     * this backend's is one callback — a render pass per face — and the bind group.
+     */
+    updatePointShadows(lights: readonly ShadowLight[], activeWorldIndices: Int32Array, activeCount: number, liveX: number, liveY: number, liveZ: number, frameDt: number, staticCasters: ShadowCasters, dynamicCasters: ShadowCasters, warmWorldIndices?: Int32Array, warmCount?: number, 
+    /** The rectangles this frame shades, in `selectAreaLights` order. See `renderer.ts`. */
+    areaLights?: readonly AreaLightSource[]): void;
+    /**
+     * The rectangles' round, inside the shadow encoder this backend already opened.
+     *
+     * Every decision — which layers, when they re-bake, what the shader is told — is
+     * `AreaShadowSet`'s and is shared with the other backend. What is this one's is the callback:
+     * a render pass per face and a resolve into the layer.
+     */
+    private updateAreaShadows;
+    /**
+     * One cubemap face: a depth pass, the casters, done.
+     *
+     * **Corrected by `SHADOW_CLIP_CORRECTION`, not `CLIP_CORRECTION`.** This map is sampled and
+     * never presented, so it wants the depth remap without the Y flip, exactly as the directional
+     * map does — see that constant for the texel-for-texel comparison that settled it. The
+     * lookup is `flat.ts`'s `pointShadow`, which normalises a direction and reads the cube; a
+     * flipped face would mirror every shadow about its own axis and still look like shadows.
+     */
+    private bakeFace;
+    /**
+     * One rendered face into its region of the light's octahedral layer.
+     *
+     * On the bake's own encoder, between two face passes, which is what lets one scratch texture
+     * serve every light: the face is consumed before the next one is drawn. See
+     * `pointShadowArray.ts` for why the regions are disjoint.
+     */
+    private resolveFace;
+    private buildFlatBindGroup;
+    /**
+     * The bind group a draw uses, skinned or not.
+     *
+     * **The skinned twin is cached against the two things that can invalidate it**, rather than
+     * against a flag somebody has to remember to clear at six call sites: the unskinned group it was
+     * built beside — which is rebuilt whenever the material or a shadow slot moves — and the palette
+     * view, which changes only when the texture is reallocated. Comparing object identity means a
+     * missed invalidation is not possible rather than merely unlikely, and it is why
+     * `SkinPaletteTexture.view()` caches: a fresh view every call never compares equal and would
+     * rebuild this every draw.
+     */
+    private flatBindGroupFor;
+    /** The layout matching a pair of vertex flags. A pipeline and its bind group must agree. */
+    private flatLayoutFor;
+    /**
+     * Give a ring that ran out last frame the room to draw this one whole.
+     *
+     * **Here and nowhere else.** `flushOverlay` above has submitted everything outstanding and the
+     * frame's encoder has not been replaced yet, so no command references the buffer about to be
+     * destroyed and nothing has been written into the staging that discarding it would lose.
+     * `UniformRing.allocate` still refuses to grow where it runs out, for the reason it gives: that
+     * would stall the frame to make room.
+     *
+     * **Only the two rings that scale with the scene.** A frame that switches material 1,267 times
+     * has 1,267 materials' worth of world in it and the honest answer is to draw them; a frame
+     * asking for a ninth simultaneous flock has hit a ceiling that means something else, and those
+     * keep skipping and reporting. The two here are also the two whose staleness has an answer
+     * already written — every flat bind group is reachable from `flatBindGroups`, the blank, and
+     * the skinned twins, and nothing else holds either buffer.
+     *
+     * **What it costs is one frame.** A scene that grows past a ceiling loses geometry for the frame
+     * that discovers it and is whole from the next, where before it lost that geometry for as long
+     * as the scene stayed big. What would make it wrong is a consumer whose frame legitimately
+     * oscillates across a ceiling: the ring keeps the larger size, so that settles rather than
+     * thrashing.
+     */
+    private growRings;
+    /**
+     * Every flat bind group, rebuilt against buffers that have just been replaced.
+     *
+     * **The blank is built with the maps forced to null rather than with whatever the last frame
+     * left set**, which is the one thing here that is not obvious. `blankAlbedoBindGroup` is what a
+     * pass starts from and it means *no maps at all*; `buildFlatBindGroup` reads the live material
+     * fields through `flatTextures`, so building it at frame start with a normal map still held from
+     * the last frame would produce a "blank" group that quietly carries one. The fields are put back
+     * immediately, because they are the material a caller set and this is not a material change.
+     *
+     * The skinned twins invalidate themselves off `bindGroup`'s identity and are cleared anyway:
+     * they hold `perDraw.buffer` directly, and a cache that is only *probably* invalid is the kind
+     * that is wrong once.
+     */
+    private rebuildFlatGroupsForNewRings;
+    /**
+     * Rebuild the group for the open material, and drop every cached one.
+     *
+     * **The cache is keyed by albedo and every entry also holds the shadow cubemaps**, so when a
+     * cubemap moves slot the entries are all stale in a way nothing about the albedo reveals. A
+     * scene that switched back to an earlier texture would get a group pointing at the pool's
+     * previous occupant — a shadow from another light, on the right surface, which reads as a
+     * lighting bug rather than as a stale binding.
+     */
+    private rebuildFlatBindGroup;
+    /**
+     * The sky, as one triangle covering the screen with the world reconstructed per fragment.
+     *
+     * `sky.sunDir` and the rest go in at the offsets the generator computed, and **so does the
+     * medium the camera is standing in**, which for a fortnight they did not.
+     *
+     * The block declares `uUnderwaterColor` and `uUnderwaterFactor` and this method never wrote
+     * either, so both held the zero a `Float32Array` is born with for the life of the session.
+     * Zero factor means "not submerged", so the shader's last line —
+     * `col = mix(col, uUnderwaterColor * waterLight, uUnderwaterFactor)` — was a mix that never
+     * moved: **a camera under the sea drew the sunset it would have seen from above it**, sun,
+     * stars, clouds and all, while every other pass in the frame correctly went green. The
+     * comment that stood here called the atmosphere uniforms a later task's, which is how a
+     * missing bind reads as a scheduled one.
+     *
+     * `resolveAtmosphere` through `atmosphereHeight`, matching `renderer.ts`'s `bindAtmosphere`
+     * call in its own `drawSky` exactly — including the mirror's eye height, or a reflection
+     * renders its sky from the camera's side of the surface.
+     */
+    drawSky(camera: Camera, sky: SkyColors, env: Environment): void;
+    /** Close the pass and present. A no-op when no frame was begun. */
+    /**
+     * The scene from its off-screen target onto the canvas, with everything that happens on the way.
+     *
+     * One pass does the lot, because every effect here reads the same resolved image: the speed
+     * blur, the camera motion blur, the occlusion it multiplies in, the bloom it adds and the tone
+     * curve it ends on. The stages before it exist only to produce the two textures that pass
+     * consumes.
+     *
+     * `sceneTarget.ts` is the same order on the other backend, including *why* the grade lands
+     * here rather than in the mesh pass: with a target, the resolve is the last pass, and grading
+     * twice is a curve applied to its own output.
+     */
+    private composite;
+    /**
+     * The composite's bind group, rebuilt from whatever views exist now.
+     *
+     * **Extracted from `ensureComposite` because a colour grade also invalidates it.** A bind group
+     * holds the *views* it was built with, so a resized target and a replaced lookup table are the
+     * same problem — and having two places build one group is how the two would come to disagree
+     * about which bindings it carries.
+     *
+     * A null scene view means the composite has not been sized yet, and `ensureComposite` will call
+     * this when it is. Doing nothing here is correct rather than a deferral: there is nothing to
+     * bind and no frame in flight to break.
+     */
+    private rebuildRushBindGroup;
+    /** The composite's group over one scene source. See `rebuildRushBindGroup`. */
+    private buildRushBindGroup;
+    /**
+     * A field's offset in a post-chain block, or a throw.
+     *
+     * **Loud, like the flat pass's own, and for a reason this file proved the hard way.** These
+     * blocks are small and their names are easy to guess wrong: the occlusion block has no
+     * `uTexelSize` and the bloom block calls it `uTexel` and has no `uStrength` at all. A lookup
+     * returning −1 writes to index −1 of a typed array, which is *silently discarded* — so a
+     * mistyped name is an effect that runs with an unset uniform and draws a plausible picture.
+     * Both of those were written here and neither raised anything.
+     */
+    private postField;
+    /** Sample zero of the depth, into something the generated shaders can sample. */
+    private resolveDepth;
+    /**
+     * Occlusion from the depth the resolve produced, then a blur across it.
+     *
+     * The projection is what turns a radius in metres into a radius in UV, and it is null until a
+     * mesh pass has settled one — the honest guard `renderer.ts` uses, because occlusion built on
+     * an identity projection samples the depth of a scene nobody drew.
+     */
+    /**
+     * This frame resolved against the history, into the half of the pair it did not read.
+     *
+     * **A blend of zero still runs the pass.** The first frame, the frame after a resize and the
+     * frame after a cut have nothing to sample and the shader exits early on that — but the pass
+     * must still write, or the history it leaves for the next frame is whatever was in the texture.
+     */
+    private temporalResolve;
+    /**
+     * The frame's reflective surfaces, marched against the picture and composited over it.
+     *
+     * **Two passes, and the first cannot write where it reads.** The trace samples the scene colour
+     * to find out what a ray hit, so it writes into a buffer of its own; the resolve then hands those
+     * premultiplied texels to an `over` blend. Either half writing into the texture the other reads
+     * would be a validation failure here and a feedback loop on the other backend, which is the same
+     * argument `runOit` makes about its own resolve.
+     *
+     * **Excluded while multisampling**, which is not timidity: the other backend cannot sample a
+     * multisampled colour attachment at all, and a reflection that appears on one backend and not the
+     * other is the disagreement the parity rule exists to prevent. Said once rather than dropped.
+     */
+    private runReflections;
+    /**
+     * The frame's marks, multiplied into the finished scene.
+     *
+     * **One scissored triangle each and no geometry at all.** The mark is decided per pixel from the
+     * resolved depth, so the rasteriser is only asked for coverage of the part of the screen the
+     * projector box can reach — `decalScissor` computes that from the box's eight corners, and
+     * argues there why a rectangle stands in for drawing the box as a mesh.
+     *
+     * **Every block is written before the pass opens.** `queue.writeBuffer` is ordered on the queue
+     * timeline and does not interleave with recorded commands, so writing one block between two
+     * draws would give both draws the last write — every mark wearing the last projector's pose.
+     * That is the hazard `bloomStaging` records, met by a pass that runs many times in one frame.
+     */
+    private runDecals;
+    /**
+     * The recorded translucent set, accumulated and revealed, then composited over the scene.
+     *
+     * **Two passes over the same geometry**, because the two buffers are two blend states and a
+     * blend state is baked into a pipeline here. The accumulation sums weighted colour; the revealage
+     * multiplies what each layer let through. Both commute, which is the whole property — the frame
+     * stops depending on which surface was submitted first.
+     *
+     * **Depth is attached read-only.** They test against the opaque world so a pane behind a wall is
+     * rejected at the wall, and neither writes, so nothing hides anything else and there is something
+     * left to blend.
+     */
+    private runOit;
+    /**
+     * The global medium: a half-res march, then one composite blended over the scene.
+     *
+     * **After the glass and before the post chain**, which is where the other backend puts it and
+     * for the same reasons: it is the air *in front of* the finished picture, so fog over a
+     * reflective floor dims the reflection; and bloom should see a lit fog bank as brightness.
+     *
+     * Nothing here runs at density 0 — the caller's guard is `mediumActive`, which both backends
+     * share so that "identical to the pass being absent" cannot become true on one of them only.
+     */
+    private runMedium;
+    /** `inverse(viewProj) * DEPTH_01_TO_CLIP_Y_DOWN`, rebuilt once a frame rather than per pass. */
+    private readonly mediumDepthToWorld;
+    /** Sixteen real numbers for a frame that never set a light matrix. */
+    private readonly mediumIdentity;
+    private runOcclusion;
+    /**
+     * The other half of the estimate: across, then down.
+     *
+     * **Not a smoothing pass over a finished answer.** `ambientOcclusion.ts` designs the two
+     * together — twelve taps turned by a rotation that repeats over a 4×4 tile, and a four-wide
+     * blur that averages all sixteen turns back into one number — so the estimate on its own is
+     * not a rougher occlusion, it is a quarter of one, and it reads as salt and pepper. Skipped
+     * entirely here until now; see `aoScratch`.
+     *
+     * Depth-aware, which is what keeps it a blur rather than a smear: an ordinary gaussian over
+     * this estimate draws a dark halo around every silhouette, and that is more obviously wrong
+     * than the noise it removes. The shader weights each tap by how close its view-space depth is
+     * to the centre's, which is why both passes bind the depth as well as the estimate.
+     */
+    private blurOcclusion;
+    /**
+     * The bright part of the frame, blurred, for the composite to add back.
+     *
+     * **The pyramid, which is what bloom is.** Threshold the frame into level 0, halve it down the
+     * chain, then add each level back into the one above it, so level 0 ends up holding every
+     * octave at once and the falloff is their sum rather than one kernel's. `bloomPass.ts` runs
+     * exactly this on the other backend, and `bloomChain.ts` holds the three numbers that decide
+     * the pyramid's shape so neither side can build a different one.
+     *
+     * **This was the prefilter alone**, and how that survived is the part worth keeping: it
+     * compiled, it validated, and it drew a picture. A thresholded frame at half resolution read
+     * bilinearly is entirely plausible-looking and has no glare in it at all, and no scene turns
+     * bloom on — so nothing compared it against anything until the format defect above made the
+     * effect measurable. Six of this port's bugs are that shape.
+     *
+     * Nothing is uploaded here. Every block these stages read was written on resize; see
+     * `bloomStaging` for why that is not merely an optimisation.
+     */
+    private runBloom;
+    /**
+     * Snapshot the opaque scene's depth, so a volume can clamp its march to it.
+     *
+     * **Neither backend may sample the depth it is testing against**, so this is a copy and not
+     * the attachment: WebGL2 calls that undefined and WebGPU rejects the pass outright. The copy
+     * already exists here — `resolveDepth` writes sample zero into a single-sample float target
+     * for occlusion and motion blur — so what this adds is taking it *earlier*, at the moment a
+     * volume first needs it, rather than in the composite.
+     *
+     * The pass has to be broken to do it, because the depth is an attachment of the open one. That
+     * is the same end-and-reopen `openTextPass` performs, with one difference that decides whether
+     * the frame survives: **both attachments load**. Text reopens with the depth *cleared*, which
+     * is what puts a message in front of the scene; a volume is in the scene and still has to sort
+     * against it, so clearing here would let every beam draw straight through the world.
+     *
+     * Returns false where there is no copy to take — a profile with no composite has no target for
+     * one — and the caller then leaves the clamp switched off rather than sampling something else.
+     * WebGL2 reaches the same answer for the same profile, which is the parity that matters: the
+     * two backends agree about *when* a beam is clamped, not merely about how.
+     */
+    /**
+     * Everything a volume samples: the three shadow layers, and the frame's own depth.
+     *
+     * All three layers because `lightVolume.ts` samples all three — a shaft is interrupted by
+     * whatever stands in it, and a mover standing in it is the case the dynamic layer exists for.
+     * Bound here as well as in the mesh group, matching `renderer.ts`, which binds its
+     * `dynamicShadowMap` to both.
+     *
+     * A method rather than a constructor expression because the depth snapshot is allocated with
+     * the drawing buffer: `ensureComposite` calls this again whenever it rebuilds that target.
+     */
+    private buildLightVolumeBindGroup;
+    /**
+     * Copy the colour the frame has drawn so far, so a refracting draw can read it.
+     *
+     * **Neither backend can read what it is writing, and this one cannot even resolve on demand.**
+     * `post.sceneColorMsaa` is `RENDER_ATTACHMENT` with no `TEXTURE_BINDING`, so the only readable
+     * copy of the frame is what ending the pass resolves into `post.sceneColor` — and that is the
+     * pass's own attachment, which a bind group may not sample while it is attached. So: end the
+     * pass, copy the resolved texture aside, reopen with `loadOp: 'load'`.
+     *
+     * **A fourth instance of a boundary this backend already runs three times** — the mirror, the
+     * light volume's depth snapshot and text — rather than a new mechanism. It is modelled on
+     * `takeVolumeDepth` line for line, including its two refusals, which hold here for the same
+     * reasons: ending the mirror's pass would throw away what the mirror had drawn and send the rest
+     * of the scene into the frame instead, invisibly on an immediate-mode GPU and not at all on a
+     * tile-based one.
+     *
+     * Latched, so one copy serves every refracting draw in a frame: glass does not refract other
+     * glass, and a frame that refracts nothing breaks no pass at all.
+     */
+    private takeRefractSnapshot;
+    private takeVolumeDepth;
+    /**
+     * The pass to record into, reopening one on the canvas if the frame has already gone.
+     *
+     * Returns null only where there is genuinely nowhere to draw: a lost surface, or a call before
+     * any frame has begun. See `overlayDepth` for why this exists at all.
+     */
+    /**
+     * Schedule and replay whatever the graph has recorded, then empty it.
+     *
+     * The schedule is computed and its pass count asserted in development, but **it does not yet
+     * drive pass creation**: every node recorded so far is a mesh draw writing the scene target,
+     * so the schedule is one pass and `ensurePass` already opens exactly that. Letting the
+     * schedule open passes is the next plan's work, and doing it here would change pass
+     * boundaries in the same commit that introduces recording — two things to bisect instead of
+     * one.
+     */
+    private flushGraph;
+    /**
+     * What must survive a flush that is not the frame's last.
+     *
+     * **The plan said this becomes `maskOf('canvas')` once every verb records, and it does not.**
+     * Tried, and a frame of three scene draws schedules zero passes: the composite reads the
+     * scene's colour and the composite is not a graph node, so the scheduler sees a write nothing
+     * reads and drops the whole frame. Nothing else in this programme could have found that — the
+     * executor replays every node regardless of the schedule, so the picture is identical either
+     * way — which is exactly the failure mode the plan warned a wrong `reads` would have.
+     *
+     * The honest set is therefore everything the graph cannot see a reader for, minus what is
+     * provably dead. Expressed as a subtraction rather than a list on purpose: a resource added
+     * to the table later defaults to surviving, which is the safe direction to be wrong in.
+     *
+     * **Only one thing is dead here.** Nothing samples the mirror's depth and nothing loads it
+     * back — it sorts the mirror against itself and is never looked at again. The frame's own
+     * depth is not dead mid-frame, because `openFramePass` resumes with `depthLoadOp: 'load'` so
+     * that geometry drawn after the mirror depth-tests against geometry drawn before it, and a
+     * load is a read.
+     */
+    private liveOutMidFrame;
+    /** What a registered pass has claimed it samples, which the frame therefore keeps. */
+    private liveOutForPasses;
+    /**
+     * What must survive the frame's last flush, which is where the depth prize is.
+     *
+     * **Nothing loads the frame's depth after this point**, so it is stored every frame for a
+     * reader that does not exist — the case the design named as the one that pays. The exception
+     * is a composite that resolves it, for camera motion blur or ambient occlusion, and the test
+     * here is the same expression `composite` applies a few lines later so the two cannot drift
+     * apart without both being wrong.
+     *
+     * Conservative on the first frame of a run: `hasPreviousView` is false then and the composite
+     * blurs nothing, but this keeps depth live anyway rather than encode a second copy of that
+     * rule. One stored attachment on one frame is not worth a second place for it to be wrong.
+     */
+    private liveOutFinalFlush;
+    /**
+     * Whether the composite is going to resolve the frame's depth out.
+     *
+     * **One expression, called from both places, because the two copies drifted the first time
+     * anybody added a third reader.** The comment above used to say "the test here is the same
+     * expression `composite` applies a few lines later so the two cannot drift apart without both
+     * being wrong", and depth of field was added to `composite`'s copy and not to this one — so the
+     * effect ran against a depth attachment the scheduler had discarded, read zero everywhere, and
+     * produced a *plausible* picture: every pixel at the near plane, so every pixel at full blur,
+     * blurred correctly and focused on nothing. It responded to the blur radius and not to the focus
+     * distance, which is what made it findable. Same expression now means the same call.
+     *
+     * Conservative where `composite` could be exact: the motion term is the raw ceiling and dial,
+     * where the composite also requires a previous view to reproject through. That costs one
+     * unused depth resolve on the first frame of a run and buys the property this comment is about.
+     */
+    private compositeWantsDepth;
+    /**
+     * What the pass `ensurePass` hands back actually writes.
+     *
+     * A verb can draw either side of `endFrame` — a consumer puts its interface after it on
+     * purpose, so the interface escapes the post chain — and after that the target is the canvas
+     * rather than the scene. Declaring one or the other unconditionally would be wrong half the
+     * time, and wrong in a way nothing notices until `liveOut` narrows.
+     */
+    private currentTarget;
+    /**
+     * Take a command to record this draw into, or `null` to draw directly.
+     *
+     * **Returns the command rather than taking a callback**, which the plan first proposed: a
+     * closure per draw is an allocation, and this is the hottest path in the renderer. A call
+     * site reads as one `if` either way.
+     */
+    private recordDraw;
+    /** Replay one recorded draw into an open pass. */
+    private replayNode;
+    private ensurePass;
+    /**
+     * The pass a verb will draw into, without flushing what is already recorded.
+     *
+     * For a verb that records: its draw goes into the arena *behind* everything already there, so
+     * there is nothing to get out of the way first. It still opens the pass, because the caller's
+     * guard needs to know there is somewhere to draw at all, and because the replay needs one.
+     *
+     * With the switch off nothing ever reaches the arena, so a recording verb's direct path is
+     * reached with the arena empty and the two entry points do the same thing.
+     */
+    /**
+     * Whether there is somewhere to draw, without opening it.
+     *
+     * `openPass` answers the same question by doing the thing, which is what a verb needed while it
+     * drew directly and is exactly wrong while it records: **the schedule cannot describe a pass
+     * that is already open.** Every recording verb asks this instead, and the pass itself is
+     * obtained only where it is used, which is the direct branch.
+     *
+     * The conditions are `openPass`'s own with the opening removed, in the same order.
+     */
+    private canDraw;
+    private openPass;
+    /**
+     * The cache whose pipelines match the pass this draw will land in.
+     *
+     * Read at the draw rather than settled once, because the same call draws into either: `drawText`
+     * is an announcement over the canvas in one frame and a label inside the world in the next. The
+     * lookup is a field read and a branch — `PipelineCache` exists so the pipeline itself is a `Map`
+     * hit — so this stays inside the per-frame budget.
+     *
+     * **`framePresented` is read beside `overlayActive`, and that is the whole of a bug that kept
+     * `frameGraph` off by default.** The question is which pass the draw *ends up in*, and
+     * `overlayActive` only answers which one is open *now*. Those differ whenever a verb resolves its
+     * pipeline before the pass exists, which is every recorded draw: recording defers the draw to a
+     * flush, and the flush is what calls `openPass` and sets `overlayActive`. So a mesh drawn after
+     * `endFrame` took a scene pipeline at 4 samples into an overlay pass at 1, and WebGPU reported it
+     * at `finish` — dropping the whole command buffer and the frame with it.
+     *
+     * These two conditions are `openPass`'s own, in its order: past `framePresented` it builds the
+     * overlay. Reading the same field here is what makes the pipeline and the pass agree by
+     * construction rather than by timing.
+     *
+     * **Two things do legitimately want the scene's pipeline after the frame is presented**, and this
+     * clause once said nothing did — which was wrong and was caught by a device rather than by
+     * reading. A probe bake and a planar reflection both draw into targets of their own, built at the
+     * scene's sample count and format, and a scene is entitled to bake either one after `endFrame`.
+     * The showroom does exactly that, and routing its bake to the overlay cache put a one-sample
+     * pipeline into a four-sample face — the same fault as the original, inverted.
+     *
+     * So the order here is `openPass`'s order: its own two early branches first, then the overlay.
+     * That is not a coincidence to be tidied away — the two functions answer the same question, and
+     * any future branch added to one belongs in the other.
+     */
+    private targetPipelines;
+    /** End and submit a reopened pass. Safe to call when there is none. */
+    private flushOverlay;
+    endFrame(): void;
+    /**
+     * Match the drawing buffer to the canvas, taking no arguments.
+     *
+     * **The signature is the WebGL2 renderer's, and the derived surface is what enforced it.**
+     * This was written taking a width and a height, which is the natural shape for
+     * `GPUCanvasContext.configure`, and `tsc` rejected it against `RendererApi` before it
+     * could reach a consumer. `Renderer.resize()` reads the canvas and the device pixel ratio
+     * itself, so a caller never passes a size and must not have to learn which backend it
+     * holds in order to know that.
+     *
+     * **The sizing policy is `drawingBufferSize`'s, not this file's.** Locked dimensions, the
+     * pixel ceiling and the density a governor moves are one set of rules, and a second copy of
+     * them here would be a frame that is a different size on each backend for reasons nobody
+     * could see. The budget is deliberately not applied to a *locked* buffer, for the reason
+     * `renderer.ts` gives: a lock is a caller naming an exact size for a reason no quality
+     * setting knows about, and quietly returning a different one writes a file that is not the
+     * size it claims.
+     */
+    resize(): void;
+    /**
+     * Move the drawing-buffer area cap, in pixels. Zero is uncapped.
+     *
+     * Live, unlike every other quality lever, and `renderer.ts` explains why that is the feature:
+     * everything sized *from* the drawing buffer re-fits itself, so this changes how many pixels
+     * the next frame covers and nothing else. A player hunting their own frame rate can move it
+     * and see the answer.
+     */
+    setMaxDrawingBufferPixels(pixels: number): void;
+    /**
+     * Told when the device is lost, immediately if it already has been.
+     *
+     * **The lateness is the interesting half and `device.ts` owns it.** WebGL fires
+     * `webglcontextlost` once and a listener that arrives afterwards hears nothing; a WebGPU
+     * device's loss is a promise that stays resolved, so a renderer built after a driver reset
+     * can still be told. `GpuSurface.onLost` latches it and this hands the listener straight
+     * through, which is why there is no list of listeners here to keep.
+     */
+    onContextLost(listener: () => void): void;
+    /** Rebuilt once per `bindMeshPass`, never per draw. */
+    private readonly frustum;
+    /**
+     * Whether a mesh placed by this matrix is anywhere in the frame.
+     *
+     * Valid between `bindMeshPass` and `endFrame`, because that is when a camera has been given.
+     * **A consumer is better placed to use this than `cullDraws` is**: it can skip the model
+     * matrix, the animation update and the material switch as well, none of which the renderer can
+     * avoid once `drawMesh` has been called.
+     */
+    visible(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * The occlusion buffer, or null where the profile did not ask for one.
+     *
+     * **Built at the first `bindMeshPass` rather than at construction**, because a field initialiser
+     * runs before the constructor body and `quality` is not resolved yet there. Resized when the
+     * drawing buffer's aspect changes and cleared at every pass — which is also where the
+     * view-projection it projects through comes from.
+     */
+    private occlusion;
+    /**
+     * Declare a box that things behind it may safely be hidden by.
+     *
+     * **Between `bindMeshPass` and the first `drawMesh`**, because the pass is what supplies the
+     * camera and the first test is what freezes the pyramid. A no-op when the profile asked for no
+     * occlusion buffer, so a consumer may call it unconditionally.
+     *
+     * The box is in the model matrix's own space, and it is the box you may be *hidden by* rather
+     * than the one you occupy — an occluder larger than the solid it stands for culls things that are
+     * visible, which is a hole in the world. `OcclusionBuffer` carries the rest of the reasoning.
+     */
+    addOccluder(min: ArrayLike<number>, max: ArrayLike<number>, model: ReadonlyMat4): void;
+    /**
+     * Whether a mesh is entirely behind the occluders declared this frame.
+     *
+     * **False whenever anything is uncertain**, including when no occluders were declared and when
+     * the profile asked for no buffer — so a consumer may call it unconditionally and a scene that
+     * declares nothing behaves exactly as it did before. Read it beside `visible`, which answers the
+     * other half of the same question.
+     */
+    occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    private readonly passes;
+    /** Each registered pass's declared reads, as a mask, resolved once at registration. */
+    private readonly passReads;
+    /**
+     * Everything any registered pass says it samples, unioned.
+     *
+     * **This reaches `liveOut` and not the node's reads, and the difference took a failing test to
+     * see.** A read declared on a node only protects an attachment from work *later in the same
+     * arena*, because that is what `storeOp` is about — what happens after the pass ends. A
+     * package drawing into the frame cannot sample the frame's own depth at all while it is an
+     * attachment, so a read declared there would be meaningless.
+     *
+     * What a contributor actually means by `reads` is "I sample this somewhere", and the renderer
+     * has no idea when. So it is treated as the conservative thing it is: the frame keeps it.
+     */
+    private passReadsUnion;
+    /**
+     * Mutated in place rather than rebuilt, because `draw` is a per-frame path.
+     *
+     * A fresh object per invocation is an allocation per registered pass per frame, which is the
+     * thing the house rule about hot paths forbids. The contract in `PassDefinition.draw` says the
+     * context is valid for the duration of the call for exactly this reason.
+     */
+    private readonly passContext;
+    /**
+     * Let something outside this file draw into the frame. See `Renderer.registerPass`.
+     *
+     * The format and the sample count travel with the device because a render pipeline cannot be
+     * built without them and a package has no other way to learn what the frame is.
+     */
+    registerPass(definition: PassDefinition): PassHandle;
+    /**
+     * How many registered passes declare `prepare`, so a frame with none walks nothing.
+     *
+     * The registry is a slot table and enumerating it every frame to discover that nobody wants a
+     * step is exactly the per-frame work the house rules are about.
+     */
+    private preparingPasses;
+    /** Mutated in place, because `beginFrame` is a per-frame path. See `PassDefinition.prepare`. */
+    private readonly prepareContext;
+    /**
+     * Give every pass that owns a target its chance to fill it, before the frame's own opens.
+     *
+     * **The ordering is a property of the encoder rather than of a schedule.** Commands recorded on
+     * one `GPUCommandEncoder` execute in recording order, and this runs after `beginFrame` created
+     * the frame's encoder and before anything opens the frame's render pass — so a target filled
+     * here has completed by the time any frame pass could sample it. Nothing in the graph learns
+     * about it and nothing is reordered, which is what keeps gate 1.2's withdrawal of dependency
+     * ordering intact.
+     */
+    private runPreparePasses;
+    /**
+     * Record one, to be run where the caller put it.
+     *
+     * With the graph off there is nothing to record into, so it runs at once against the pass the
+     * caller is drawing into — which is what every verb's direct path does, and is why the two
+     * behave identically from outside.
+     */
+    drawPass(handle: PassHandle): void;
+    /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
+    unregisterPass(handle: PassHandle): void;
+    /** Whether this backend can run a compute definition. See `Renderer.computeSupported`. */
+    readonly computeSupported = true;
+    private readonly computes;
+    /**
+     * The binner, held only when the profile asked for clustering.
+     *
+     * **Registered through the public seam rather than called directly**, which is not ceremony: it
+     * is the only consumer of `registerCompute` inside the engine, so if the seam were wrong for its
+     * first real user that is worth finding here rather than in a package that does not exist yet.
+     */
+    private clusterBinner;
+    private clusterHandle;
+    /** The one-texel stand-in bound when there is no table. Assigned in the constructor. */
+    private blankTableView;
+    /** near, far, tan(fovY/2), aspect. Written per frame into the fragment block. */
+    private readonly clusterFrustum;
+    /** Refilled per frame; holds references and allocates nothing. */
+    private readonly clusterLights;
+    /**
+     * Reused per dispatch rather than allocated, for the reason `passContext` gives beside it: a
+     * fresh object per dispatch is an allocation on a per-frame path. The contract in
+     * `ComputeDefinition.dispatch` says the context is valid for the duration of the call for
+     * exactly this reason.
+     */
+    private readonly computeContext;
+    /** Let something outside this file compute. See `Renderer.registerCompute`. */
+    registerCompute(definition: ComputeDefinition): ComputeHandle;
+    /**
+     * Run one, now, on an encoder of its own.
+     *
+     * **Its own encoder, and that is the whole of the design.** `beginComputePass` cannot be opened
+     * while a render pass is open, and this frame's render pass is opened late and then deliberately
+     * kept open — closing and reopening it was measured at 92 MB a frame at 824x1830, which is what
+     * `beginFrame` stopped paying. A dispatch that closed it would spend that again on every frame
+     * that computed, which is the largest single cost this backend has ever removed.
+     *
+     * **Submitted here rather than deferred to `endFrame`**, because submission order is execution
+     * order and a frame with a mirror in it submits three times before `endFrame` runs. Deferring
+     * would land the compute *after* the reflection's submit and quietly starve the pass most likely
+     * to want it. One submit per dispatch is what that costs; batching several into one compute pass
+     * is a measured optimisation and would bring the ordering question back with it.
+     *
+     * **`flushRings` first**, for the reason `endPlanarReflection` calls it before its own submit: a
+     * ring's writes have to land on the queue ahead of the commands that read them. A ring with
+     * nothing in it returns immediately, so a dispatch early in the frame pays almost nothing for
+     * the guarantee — and a ring in neither `flushRings` nor `beginFrame`'s reset is exactly how the
+     * probe's mip chain came to read a buffer nobody uploaded.
+     */
+    dispatchCompute(handle: ComputeHandle): void;
+    /** Let go of a definition. A handle kept past this dispatches nothing; see `ComputeHandle`. */
+    unregisterCompute(handle: ComputeHandle): void;
+    /**
+     * Fill the froxel table for this frame, and write the four numbers that address it.
+     *
+     * **Dispatched here rather than at `beginFrame`**, because this is the one place a camera and an
+     * environment arrive together, and a froxel grid is defined by the camera's frustum. It is also
+     * before any draw the table feeds, and `dispatchCompute` submits where it is issued, so the
+     * ordering the lit pass depends on holds without anything having to reason about it.
+     *
+     * The frustum is read off the projection rather than taken as a parameter, for the reason
+     * `renderer.ts` gives at its own copy: derived numbers cannot disagree with the matrix the world
+     * was actually drawn with, and a caller-supplied field of view can.
+     */
+    private bindClusters;
+    /** Allocates, and may: registration and disposal are init-time, exactly as `passDevice` is. */
+    private computeDevice;
+    private passDevice;
+    /**
+     * Told when the drawing context comes back — which, on this backend, it does not.
+     *
+     * **A device is not restored, it is replaced.** WebGL2 has a `webglcontextrestored` event
+     * and `renderer.ts` reports it while saying plainly that it rebuilds nothing, because every
+     * resource field there is `readonly` and set in the constructor. WebGPU does not even offer
+     * the event: recovering means requesting a new device and building a new renderer on it,
+     * which is a decision for whatever owns the canvas.
+     *
+     * So this registers a listener that will not fire, and that is the honest shape rather than
+     * an omission — the alternative is a missing method, which throws and takes the frame with
+     * it. A consumer wanting to survive a reset listens to `onContextLost` and remounts.
+     */
+    onContextRestored(_listener: () => void): void;
+    private readonly insetLayout;
+    private readonly insetUniforms;
+    private readonly insetBindGroup;
+    /**
+     * Draw the next thing into a rectangle of the canvas, and give the rest back with `endInset`.
+     *
+     * `rect` is viewport-relative — a measured DOM element — which is why the canvas's own
+     * bounding box is subtracted here. `renderer.ts` makes the argument for doing that arithmetic
+     * in the renderer: a caller converting CSS pixels into drawing-buffer pixels *and* flipping
+     * the origin is a caller with two chances to be wrong about somebody else's state.
+     *
+     * **The clear is a drawn quad rather than a clear**, because WebGPU clears whole attachments
+     * and cannot confine one to a scissor. See `insetPass.ts`.
+     *
+     * Returns the drawing-buffer height of the inset, as the other backend does.
+     */
+    beginInset(rect: InsetRect, clearColor: Vec3 | null): number;
+    /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
+    endInset(): void;
+    /**
+     * Copy a rectangle of the frame into a 2D canvas, pixel for pixel.
+     *
+     * **Backend-agnostic, and the same code on both.** `drawImage` takes the canvas element,
+     * which is the canvas whichever API drew into it, so nothing here touches a device. Sized to
+     * the source so the copy is never resampled, and written only when it changes because
+     * assigning width or height clears the target.
+     */
+    copyRegionTo(rect: InsetRect, target: HTMLCanvasElement): void;
+    /**
+     * How far into the tone curve this frame is exposed.
+     *
+     * Live, and it reaches the picture here rather than through a composite: this backend grades
+     * in the mesh pass because that is the last pass it has. See `bindMeshPass`.
+     */
+    setOutputExposure(exposure: number): void;
+    /** This frame's exposure into the tone curve. Starts at the profile's own. */
+    private exposure;
+    private bloomScale;
+    private rushStrength;
+    private motionBlurScale;
+    /**
+     * This frame's veil colour, and how much of it to composite. See `Renderer.setFrameVeil`.
+     *
+     * Reset to zero alpha at the end of every `endFrame`, unlike the three fields above: a
+     * forgotten veil is a stuck white or black frame, which is worse than one that has to ask
+     * again.
+     */
+    private readonly veilColor;
+    private veilAlpha;
+    /** How much of the frame's bloom to apply, 0 to 1. Scales the profile's `bloom`. */
+    /**
+     * The colour grade this and every later frame applies, until it is set again.
+     *
+     * The same contract `Renderer.setColourGrade` states and the same refusal: it needs a
+     * composite, because without one every forward pass grades itself and there is nowhere to
+     * apply a look once. Said out loud rather than silently ignored — this backend spent a while
+     * telling consumers that working effects did nothing, and the correction was to make present
+     * and honoured the same thing rather than to stop saying anything.
+     *
+     * **The bind group holds the view, so a new table rebuilds it.** A bind group is built with
+     * the view it was given and cannot be handed another, which is the rule `ensureComposite`
+     * already records about resized targets — and the reason the upload is gated on the object
+     * changing rather than done every frame.
+     */
+    setColourGrade(lut: ColourGradeLut | null, strength?: number): void;
+    /** The grade's view, building the identity placeholder the first time anything asks. */
+    private ensureGradeView;
+    /**
+     * Put a table on the device, replacing whatever was there.
+     *
+     * `rgba8unorm` and a filtering sampler, which is what makes a 32-lattice table smooth rather
+     * than banded. `bytesPerRow` is the lattice times four and `rowsPerImage` the lattice, because
+     * a 3D write needs both and a wrong one silently shears the cube.
+     */
+    private uploadGrade;
+    setBloom(scale: number): void;
+    /**
+     * How thick the air is, this frame: a global participating medium filling the whole frustum.
+     *
+     * The dial beside `globalMediumSteps`' ceiling. `renderer.ts` carries the full note; the short
+     * version is that `density` is extinction per metre, 0 is a real off that allocates nothing and
+     * draws nothing, and the three optional arguments are held until changed.
+     */
+    setGlobalMedium(density: number, albedo?: number, anisotropy?: number, maxDistance?: number): void;
+    /** How much speed blur the frame should resolve with, 0 to 1. */
+    setSpeedRush(strength: number): void;
+    /** How much of the frame's camera motion blur to apply, 0 to 1. */
+    setCameraMotionBlur(scale: number): void;
+    /**
+     * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
+     * to take. **The other backend's `setDepthOfField` carries the reasoning**, whole: the
+     * ceiling-and-dial split, why racking focus is the caller's, and why `range` is clamped above
+     * zero. This is the same setter over the same state.
+     */
+    setDepthOfField(distance: number, range: number, scale?: number): void;
+    /** Where the lens is focused and how deep the sharp zone is, in metres. See `setDepthOfField`. */
+    private focusDistance;
+    private focusRange;
+    /** How much of `depthOfField` this frame takes. See `setDepthOfField`. */
+    private dofScale;
+    /** The inverse projection, and the four elements of it a depth-to-distance needs. */
+    private readonly dofInvProjection;
+    private readonly dofDepthToView;
+    /**
+     * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
+     *
+     * See `Renderer.setFrameVeil` for the full ruling on where this sits: after the tone map,
+     * before grain and vignette, upstream of nothing bloom reads. Both backends draw it from the
+     * same generated `rush.ts` shader, so there is one place that reasoning has to be written.
+     */
+    setFrameVeil(r: number, g: number, b: number, alpha: number): void;
+    private readonly causticsLayout;
+    /** A slot per batch, for the reason `causticsPass.ts`'s layout gives. */
+    private readonly causticsVerts;
+    private readonly causticsFrags;
+    private readonly causticsBindGroup;
+    private readonly causticsVertStaging;
+    private readonly causticsVertFloats;
+    /** The same bytes as an `i32` view, which is what a ring slot is copied through. */
+    private readonly causticsVertBlock;
+    private readonly causticsFragStaging;
+    private readonly causticsFragFloats;
+    private readonly causticsFragInts;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedCausticsFull;
+    /** The light's tint, refilled per draw rather than allocated. See `causticsRenderer.ts`. */
+    private readonly causticsTint;
+    /**
+     * A surface lit by nearby water: a pool floor, a soffit, the mouth of a cave.
+     *
+     * Null on a profile with water off or with no sheets, exactly as `renderer.ts` returns null,
+     * so a scene's own `drawCaustics(null, …)` guard works the same on both.
+     */
+    createCaustics(sheets: readonly CausticSheet[]): GpuCaustics | null;
+    disposeCaustics(caustics: GpuCaustics | null): void;
+    /** Add the water's light to an already-shaded scene. Draw after the opaque pass. */
+    drawCaustics(caustics: GpuCaustics | null, camera: Camera, timeSeconds: number, env: Environment, windX?: number, windZ?: number, strength?: number): void;
+    /** Scale one plume in a batch, 0 to hide it. See `GpuPlumes.setScale`. */
+    setPlumeScale(plumes: GpuPlumes, index: number, scale: number): void;
+    /** Scratch for `drawingBufferSize`, which fills a caller's object rather than allocating. */
+    private readonly budgeted;
+    private maxDrawingBufferPixels;
+    /** A caller's exact size, or zero for "follow the CSS box". */
+    private lockedWidth;
+    private lockedHeight;
+    /**
+     * Pin the drawing buffer to an exact size, whatever the page is doing.
+     *
+     * For an export: a clip is 1080x1920 whatever anybody's frame rate or device ratio is. The
+     * pixel budget deliberately does not apply to a locked buffer — see `resize` — because
+     * quietly returning a different size writes a file that is not the size it claims.
+     */
+    lockDrawingBuffer(width: number, height: number): void;
+    /** Back to following the CSS box. The next `resize` restores it. */
+    unlockDrawingBuffer(): void;
+    /** Whether this device and profile have an environment probe at all. See the constructor. */
+    private readonly probeEnabled;
+    /**
+     * The captured cube: what the bake draws into, and the source the convolution reads.
+     *
+     * **Not what the lit pass samples.** It carries a box-filtered chain, which is a filter the
+     * specular integral does not want and only ever wanted as a stand-in. It stays because filtered
+     * importance sampling needs a chain to select a level from, and because the spherical-harmonic
+     * projection reads it — the irradiance term is an integral over the capture and would be wrong
+     * over a lobe-convolved one.
+     */
+    private readonly probe;
+    /**
+     * The prefiltered cube: what the lit pass samples, one GGX-convolved level per roughness.
+     *
+     * **A second texture rather than the capture written in place**, and the cost is one cube of
+     * memory. What it buys: no level is ever convolved from a level that was already convolved,
+     * which applies the lobe twice and compounds up the chain; and the capture survives for the
+     * projection above. **What would make it wrong** is a probe large enough that a second cube is
+     * the memory decision — at 128 with a chain this is about a megabyte at half float.
+     */
+    /**
+     * Every probe of the grid as one array texture, octahedral, gutter included.
+     *
+     * **Recreated when a grid's layer count changes**, and the flat bind groups are rebuilt with it:
+     * a group built at construction holds the texture that existed then, so a larger array created
+     * later would never be read and the picture would keep the one-probe grid it started with.
+     */
+    private probeArray;
+    /** Where the probes stand. A single baked probe is a grid of one at that probe's own origin. */
+    private probes;
+    /** Whether the grid supplies the scene's ambient. `ProbeBakeOptions.irradiance`, at grid scope. */
+    private probeAmbient;
+    /** Where the probe being baked stands. Reused, so a bake allocates nothing. */
+    private readonly probeOrigin;
+    /** Texels across one probe's map at level 0. Twice the capture's face; see `octahedralEdgeFor`. */
+    private readonly probeEdge;
+    /** The view bound as `uEnvironment`: the prefilter's, never the capture's. */
+    private probeView;
+    private readonly probeSize;
+    private readonly probeMipLayout;
+    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
+    private iesTexture;
+    private iesView;
+    private cookieTexture;
+    private cookieView;
+    /** Tiles in the cookie atlas. 0 is the white placeholder and the whole off path. */
+    private cookieTiles;
+    /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
+    private iesRows;
+    /** Horizontal planes each profile occupies. 1 unless something asymmetric was loaded. */
+    private iesPlanes;
+    /** The convolution's own layout: the generator's binding numbers, not the mip blit's. */
+    private readonly probePrefilterLayout;
+    private readonly probeMipUniforms;
+    private readonly probeSampler;
+    /** The camera each face is drawn with. Reused, so a bake allocates nothing. */
+    private readonly probeCamera;
+    /** Whether anything has been rendered into it. The shader must not sample an unfilled cube. */
+    /**
+     * One flag a layer, because a grid may be baked a probe at a time across frames.
+     *
+     * **The gate is the whole grid rather than any part of it.** A fragment blending eight corners
+     * would read whatever the device left in the layers that have not been filled, and a car
+     * mirroring uninitialised memory is worse than a car mirroring a gradient — the rule one probe
+     * already had, unchanged by there being more of them.
+     */
+    private probeFilled;
+    private probeFilledCount;
+    /**
+     * Whether a bake is running, which is when the cube may be neither sampled nor bound.
+     *
+     * `renderer.ts` carries the same flag under the same name and for the same reason. Here it is
+     * load-bearing rather than defensive: WebGPU rejects a pass that holds the texture it writes.
+     */
+    private probePassActive;
+    /** How many mip levels the roughness blur has to work with. `flat.ts` reads this. */
+    private get probeMaxLod();
+    /** Whether every layer of the grid has been convolved. See `probeFilled`. */
+    private get probeBaked();
+    /** Record that one layer now holds a convolution, without counting a rebake twice. */
+    private markProbeFilled;
+    /**
+     * The array every probe is a layer of, sized for a grid.
+     *
+     * Separate from the constructor because a grid is declared after it, and the flat bind groups
+     * hold whatever texture existed when they were built — which is why the caller rebuilds them.
+     */
+    private allocateProbeArray;
+    /**
+     * Declare where a grid's probes stand, and allocate the layers for them.
+     *
+     * **The flat bind groups are rebuilt when the array is replaced**, and that is the trap this
+     * backend documents elsewhere: a group is built once and cached, so a texture created later
+     * resolves to whatever the group was built with, forever, with no error anywhere.
+     */
+    setProbeGrid(options: ProbeGridOptions): boolean;
+    /** Bake every probe of the declared grid, in one call. See the other backend's own note. */
+    bakeProbeGrid(clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * Capture the room into a cubemap, once, so reflective surfaces can mirror it.
+     *
+     * `drawFace` is handed a camera already aimed and submits the scene exactly as it would to the
+     * screen. Six passes, one submission, at the moment a caller says the room is finished — then
+     * a cubemap fetch per reflective pixel for ever after.
+     *
+     * **The chain afterwards is the roughness**, not a nicety: a polished surface samples level 0
+     * and a satin one samples further up. WebGPU has no `generateMipmap`, so it is built here by
+     * rendering each level from the one above, sampling the cube by direction so the blur crosses
+     * face edges instead of seaming along them.
+     *
+     * Returns whether the bake happened, as `renderer.ts` does: false means a caller carries on
+     * with the sky-and-ground gradient `flat.ts` had before probes existed.
+     */
+    bakeReflectionProbe(origin: Vec3, clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * Bake one probe of the declared grid: six faces into the scratch cube, then one convolution.
+     *
+     * One probe per call, so a grid can be paced across frames. See the other backend's own note on
+     * why a bake is the budget question a grid raises rather than the texture units.
+     */
+    bakeProbe(layer: number, clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * The room's diffuse light, projected once — started here and deliberately not awaited.
+     *
+     * **The caller is drawing a frame around this call**, and where a bake sits inside a frame is the
+     * scene's decision rather than this backend's, so `bakeReflectionProbe` cannot become
+     * asynchronous to hide the fact that this is. `uEnvIrradianceEnabled` stays 0 until the promise
+     * resolves, a frame or two later, and until then the picture is exactly what it was.
+     *
+     * **A refusal is not a failed bake.** The reflection is already in the cube and is unaffected, so
+     * this is a missing improvement rather than a fault, and it says so once: a device that refuses
+     * one readback refuses every one and a warning per scene is a flood.
+     */
+    /**
+     * Light the scene from an environment it did not photograph.
+     *
+     * **Downstream of the cube this is exactly a bake**, which is the design rather than a
+     * convenience: the faces are written into the same texture a bake fills, `buildProbeChain` runs
+     * the same box chain and the same convolution over them, and `projectProbeIrradiance` reads them
+     * back the same way. A loaded sky is therefore not a second lighting path that can be wrong on
+     * its own.
+     *
+     * **Its own encoder, submitted here.** A bake has a frame's encoder to borrow; this can be
+     * called before `beginFrame` has opened one, and recording into a null encoder is the shape of
+     * defect `beginPlanarReflection` already paid for — it answered null before a frame existed and
+     * a consumer read that as "no target" on every frame.
+     */
+    setEnvironmentImage(image: {
+        readonly width: number;
+        readonly height: number;
+        readonly data: Float32Array;
+    }, options?: ProbeBakeOptions): boolean;
+    /**
+     * Upload the photometric profiles a consumer loaded, and rebuild the bind group that holds them.
+     *
+     * **Once per set rather than per frame**, because a fixture's distribution is an asset and does
+     * not change while the game runs. Passing an empty list clears them back to the single row of
+     * ones, which is the multiplicative identity — a scene that drops its profiles goes back to
+     * plain lights rather than going black.
+     */
+    /**
+     * Upload the cookies a consumer loaded, and bind the atlas.
+     *
+     * The same contract `Renderer.setSpotCookies` states: one row of square tiles, `COOKIE_TILE` a
+     * side, an empty list clearing back to the white texel that is the multiplicative identity.
+     *
+     * **`copyExternalImageToTexture` per tile**, which is what puts a decoded image on the device
+     * here — the same call `createSurfaceTexture` makes, and it takes a destination origin, so one
+     * call a tile fills the row without a canvas in between.
+     */
+    setSpotCookies(images: readonly TexImageSource[]): void;
+    setIesProfiles(profiles: readonly PhotometricProfile[]): void;
+    /** Each level from the one above it, six faces at a time. See `probePass.ts`. */
+    private buildProbeChain;
+    /**
+     * Allocate the mirror at the size the frame is about to be, and rebind the water to it.
+     *
+     * **From `resize` rather than from the first frame that shows water**, which is the reason
+     * `planarReflection.ts` gives on the other side: allocated lazily it lands in whichever frame
+     * first puts water on screen, measured there as 28% of a 62 ms frame — a stall in the middle
+     * of play rather than during a load.
+     *
+     * Rebuilding the water bind group is not optional. A bind group holds a *view*, and a resized
+     * target is a different texture; keeping the old group would sample a destroyed one.
+     */
+    /**
+     * The composite's targets, sized with the drawing buffer.
+     *
+     * Allocated from `resize` rather than from the first frame that needs one, which is the
+     * argument `planarReflection.ts` makes and the same cost: a full-size colour target paid for
+     * in the middle of play is a stall a player feels, and paid here it lands where the rest of
+     * the frame's memory is paid.
+     *
+     * The occlusion and bloom targets are half size. Both are blurs read back at full size, so a
+     * full-resolution intermediate buys nothing a bilinear fetch does not already give.
+     */
+    private ensureComposite;
+    /**
+     * Every bloom stage's uniform block, written once per size rather than once per frame.
+     *
+     * **By name off each stage's own layout**, and that is not ceremony: the three blocks are all
+     * sixteen bytes and hold different things — a texel and a threshold, a texel, a radius — so a
+     * field read off the wrong one lands at a plausible offset and writes a plausible number.
+     * `postField` throws on a name a block does not have, which is what turns that into a crash at
+     * init rather than an effect that quietly runs on somebody else's uniform.
+     */
+    private writeBloomBlocks;
+    private ensureReflection;
+    /** What is under a pixel. See `Renderer.registerPickable` in `renderer.ts` for why this answers only *what* and dispatches no events. */
+    registerPickable(source: PickableSource, model: Float32Array): number;
+    updatePickable(handle: number, model: Float32Array): void;
+    unregisterPickable(handle: number): void;
+    pickAt(camera: Camera, cssX: number, cssY: number): PickHit | null;
+    /**
+     * Give the device back, and everything registered against it first.
+     *
+     * **The registries are drained before `surface.dispose()`, and the order is the whole of it.**
+     * That call ends in `device.destroy()` — see `device.ts` — and a definition releasing a buffer
+     * against a destroyed device is the one way this goes wrong. Nothing released them at all until
+     * now: `unregisterPass` and `unregisterCompute` always have, and neither was called on teardown,
+     * so every pipeline and bind group a contributor built outlived the renderer that asked for it.
+     *
+     * Unconditional here where the WebGL2 side asks whether it still has a context, because the two
+     * backends fail differently: a lost GL context makes deleting its objects an error, and a lost
+     * WebGPU device swallows the call instead. Each backend does what is true of it, which is what
+     * the 2026-08-13 rule asks for — one decision, bound twice.
+     */
+    dispose(): void;
+}
+export {};