@driftengine/core 3.62.0 → 4.0.0

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

@@ -46,6 +46,8 @@ 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 { ComposedField } from './fieldCompose.ts';
+import type { FieldSource } from '../../gi/globalField.ts';
 import type { ReflectiveSurface } from '../../screenSpaceReflection.ts';
 import type { DecalProjector } from '../../decalProjector.ts';
 import type { Bounds } from '../../../math/bounds.ts';
@@ -55,25 +57,6 @@ 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.
@@ -217,8 +200,8 @@ export declare class WebGPURenderer implements RendererApi {
     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;
+    /** The slot the open material occupies, and whether the next draw must take a new one. */
+    private readonly materials;
     /**
      * What this frame asked for against the ceilings above, reported rather than only warned about.
      *
@@ -252,6 +235,7 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly textBudget;
     private readonly sdfTextBudget;
     private readonly lineBudget;
+    private readonly panelBudget;
     /**
      * What the frame just drawn asked for, and what it was refused.
      *
@@ -270,6 +254,12 @@ export declare class WebGPURenderer implements RendererApi {
      * scatter, plumes and text reached it long before the draw ring was full.
      */
     private replayScratch;
+    /**
+     * The identifier graph's working set, where `quality.identifierGraph` asks for it and not
+     * otherwise: a renderer scheduling by masks carries none of it. Sized with the arena, and grown
+     * by `scheduleFlush` the way the arena grows.
+     */
+    private readonly flushSchedule;
     private readonly scheduledPasses;
     private readonly commands;
     /** Guards `ensurePass` against re-entering the flush that is already running. */
@@ -499,6 +489,26 @@ export declare class WebGPURenderer implements RendererApi {
     private bloomGroups;
     private frameWidth;
     private frameHeight;
+    /**
+     * What the scene is drawn at, which is the drawing buffer unless a reconstruction is enlarging it.
+     *
+     * **Everything before the resolve is this size and everything after it is the drawing buffer's.**
+     * The scene colour and its multisampled twin, the depth, the refraction snapshot, the resolved
+     * depth, the occlusion pair, the medium, the translucent buffers, the reflection march, the
+     * decals, the temporal history and the frame pass's own viewport are all before it; the composite
+     * and the overlay are after it, and they are what the viewer's pixels are counted in.
+     *
+     * **The composite is what enlarges the picture, and it does so by existing.** It draws a
+     * full-screen triangle into the swap chain sampling the scene by `uv` through a linear sampler, so
+     * a smaller scene target is magnified by that sample and nothing else changes — which is why this
+     * needs `screenEffects` and is refused without it: with no composite the world draws straight into
+     * the swap chain and there is nothing to enlarge from.
+     *
+     * Equal to the drawing buffer whenever `quality.reconstruction` is 0, which is the default, and
+     * `recon/frameSizes.ts` is the one place the two are related.
+     */
+    private renderWidth;
+    private renderHeight;
     /** The view-projection this frame was drawn with, for the reprojection motion blur needs. */
     private readonly previousViewProj;
     private readonly reprojection;
@@ -592,6 +602,94 @@ export declare class WebGPURenderer implements RendererApi {
     private temporalJitterX;
     private temporalJitterY;
     private temporalJittering;
+    /**
+     * Whether this frame is being reconstructed, settled once in `bindMeshPass`.
+     *
+     * It is not `quality.reconstruction > 0` on its own: a mirror pass is skipped for the same reason
+     * the temporal jitter skips one — a reflection is not the picture the history holds — and without
+     * a composite there is nothing to enlarge the render from.
+     */
+    private reconstructing;
+    /** Said once rather than every frame, as the translucent set's own refusal is. */
+    private reconMultisampleSaid;
+    private reconFrameIndex;
+    private readonly reconJitter;
+    private readonly reconPreviousJitter;
+    /**
+     * `reconJitter` as a fraction of the clip square, which is what a contributed pass is handed.
+     * See `PrepareContext.jitter`; zero on a frame that is not reconstructed.
+     */
+    private readonly passJitter;
+    /**
+     * The reconstruction's own targets, allocated only while a consumer asks for one.
+     *
+     * **Two histories rather than one**, for the reason the temporal resolve keeps two: a dispatch
+     * cannot read the texture it is writing. The shown picture is a third, because the history holds
+     * the *unsharpened* result — sharpening into the history would sharpen a sharpened picture every
+     * frame, which is the halo the reference's own clamp exists to prevent, compounded.
+     *
+     * The motion target is render size and carries a drawn object's own motion where something wrote
+     * one. **Nothing writes it yet**, so it is cleared every frame and every pixel takes the camera's
+     * motion, which the resolve derives from the depth and the reprojection. Static geometry is
+     * exact that way and a moving object ghosts until the motion pass lands.
+     */
+    private reconHistories;
+    private reconHistoryViews;
+    private reconWrite;
+    private reconHasHistory;
+    private reconShown;
+    private reconShownView;
+    private reconMotion;
+    private reconMotionView;
+    private reconPreviousDepth;
+    private reconPreviousDepthView;
+    private reconParams;
+    private readonly reconStaging;
+    private readonly reconFloats;
+    private readonly reconInts;
+    private reconLayout;
+    private reconResolvePipeline;
+    private reconSharpenPipeline;
+    private reconGroups;
+    private reconSharpenGroups;
+    private reconRushGroup;
+    /**
+     * What the motion pass will draw, recorded by `drawMesh` and spent once a frame.
+     *
+     * A parallel array of meshes and one flat matrix buffer rather than an array of objects, because
+     * this is written on the frame's hot path and the house rule about allocating there binds it: the
+     * matrices are copied into a buffer that only ever grows, and the count is what resets.
+     */
+    private readonly motionMeshes;
+    private motionMatrices;
+    private motionCount;
+    private motionLayout;
+    /**
+     * One pipeline per vertex stride, because a stride is a property of the *mesh*.
+     *
+     * Which optional attributes a mesh supplied decides how far apart its positions are, and this
+     * pass reads nothing but positions — so two meshes drawn by the same shader still need two
+     * vertex layouts. A map rather than a cache key on the pipeline cache: there is one shader here
+     * and a handful of strides in any scene.
+     */
+    private readonly motionPipelines;
+    private motionModule;
+    private motionPipelineLayout;
+    private motionFrameBuffer;
+    private motionDrawBuffer;
+    private motionDrawCapacity;
+    private motionGroup;
+    private readonly motionFrameStaging;
+    private motionDrawStaging;
+    /** The scene's own clip transform with the generated shaders' y negation folded in. */
+    private readonly motionRaster;
+    private reconSizeKey;
+    /** Last frame's raw view-projection and its inverse, and the two eyes. */
+    private readonly reconPreviousRawViewProj;
+    private readonly reconInverseViewProj;
+    private readonly reconPreviousInverseViewProj;
+    private readonly reconEye;
+    private readonly reconPreviousEye;
     private temporalHistoryUsable;
     private readonly aoStaging;
     private readonly aoFloats;
@@ -628,6 +726,20 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly postDepthSampler;
     /** Whether the profile asked for a composite at all. Everything below is null when it did not. */
     private get hasComposite();
+    /**
+     * Whether this renderer is set up to reconstruct, asked in one place by everything that cares.
+     *
+     * **One condition and not three**, which §3 row 132 is the lesson of: the frame's flag, the size
+     * the targets are built at and the size the world is drawn at all turn on the same question, and
+     * three copies of it are three lines no test can fail — each covering the others, so breaking any
+     * one of them changes nothing anybody can see.
+     *
+     * A composite, because the composite is what enlarges the render; one sample, because the motion
+     * pass draws against the depth the scene left and every attachment in a pass must agree about its
+     * sample count — `RECONSTRUCTION_MULTISAMPLE_REFUSAL` says the rest. Whether a *frame* is
+     * reconstructed adds one more question, the mirror's, and that one belongs to the frame.
+     */
+    private get reconstructionWanted();
     /** 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`.
@@ -715,6 +827,31 @@ export declare class WebGPURenderer implements RendererApi {
      * the frame has drawn, so it cannot run until the opaque world is finished. See `DecalQueue`.
      */
     private readonly decalQueue;
+    /** The fields this frame declared, composed at `endFrame`. See `addDistanceField`. */
+    private readonly distanceFields;
+    /**
+     * The composition of them, built at the first frame that has both the flag and a field.
+     *
+     * **Not at construction**, because it is 1.4 MB of device buffers and a compute pipeline, and a
+     * profile with `indirectLight` on is entitled to declare no fields at all — a scene that lights
+     * itself entirely from a baked probe grid, for one. Nothing is allocated until something would
+     * be composed.
+     */
+    private fieldComposer;
+    /**
+     * The probes' own bake, built at the first frame that has the flag, a field and an array.
+     *
+     * Not at construction, for `fieldComposer`'s reason: it is two compute pipelines, a render
+     * pipeline and a handful of buffers, and a profile with the flag on may never declare a field.
+     */
+    private probeBaker;
+    /** Which array the baker's views were built against, so a replacement is noticed. */
+    private bakerArray;
+    /** Reused, because deriving a grid from the declared fields runs in the frame path. */
+    private readonly fieldBoundsMin;
+    private readonly fieldBoundsMax;
+    /** Said once rather than every frame, as the other refusals are. */
+    private indirectGridRefused;
     private decalLayout;
     private decalUniforms;
     private readonly decalStaging;
@@ -750,7 +887,10 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly decalScissorRect;
     private oitResolveLayout;
     private oitResolveGroup;
-    /** Reused, because the frame loop may not allocate. Mirrors the WebGL2 backend's own. */
+    /**
+     * Reused, because the frame loop may not allocate. Mirrors the WebGL2 backend's own, which it
+     * had stopped doing: the other one carried a pane's refraction and this one did not.
+     */
     private readonly oitReplayOptions;
     private reflectionPassActive;
     /** Said once: a mirror asked for outside a frame is a call-order fault, not a device limit. */
@@ -874,8 +1014,23 @@ export declare class WebGPURenderer implements RendererApi {
     /** 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;
+    /**
+     * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
+     *
+     * Not at once, because a draw recorded earlier in the frame the update landed in may still read
+     * one, and a destroyed texture in a submit loses the whole command buffer. Every encoder a frame
+     * opens is submitted by the time the next one begins.
+     */
+    private readonly retiredTextures;
     updateSurfaceTexture(texture: GpuSurfaceTexture, source: TexImageSource): void;
     disposeSurfaceTexture(texture: GpuSurfaceTexture): void;
+    /**
+     * Drop every bind group that may hold `texture`'s view, and rebuild the ones bound now.
+     *
+     * For a texture going away and for one whose view has been replaced, which are the same problem:
+     * a group holding the old view hands a destroyed texture to the next draw that asks.
+     */
+    private forgetBindingsOf;
     /**
      * Choose the surface texture the following `drawMesh` calls sample, or null for none.
      *
@@ -965,6 +1120,8 @@ export declare class WebGPURenderer implements RendererApi {
      * that order, which is the shape of failure the 2026-08-13 rule is about.
      */
     fillPanel(rect: InsetRect, color: Vec3, alpha: number): void;
+    /** Said once rather than every frame, for the reason `warnedFull` gives. */
+    private warnedPanelsFull;
     /** A 3D text object. See `textPass.ts`; the layout it holds is shared with WebGL2. */
     createText(): GpuText;
     setText(text: GpuText, content: string): void;
@@ -1560,6 +1717,32 @@ export declare class WebGPURenderer implements RendererApi {
     get aspect(): number;
     /** The canvas being drawn into, for a consumer that needs to measure or place against it. */
     get canvas(): HTMLCanvasElement;
+    /**
+     * The size the world is drawn at this frame, which is **not** the canvas when a reconstruction
+     * is enlarging it.
+     *
+     * **A contributed pass that fills a target of its own must size it from here.** The GPU-driven
+     * rig sized its own targets from `canvas.width` and drew a full drawing-buffer picture into a
+     * scene target two thirds as wide: the frame pass clipped it to the top-left corner and the
+     * composite magnified that corner back over the screen, which is a plausible-looking picture of
+     * the wrong part of the world. The device raises nothing — a viewport smaller than the thing
+     * drawn is legal — so there is no failure to see, only a scene that has moved.
+     *
+     * Valid from `beginFrame`; before the first frame it is the canvas, which is what a pass sizing
+     * itself at registration wants.
+     */
+    get sceneWidth(): number;
+    get sceneHeight(): number;
+    /**
+     * The render size this frame will use, computed rather than remembered.
+     *
+     * **Computed, because a pass asks before the frame it is asking about.** `GpuDrivenPass.resize`
+     * runs before `beginFrame` — that is when `prepare` records the pipeline — so a stored field
+     * would answer with the previous frame's size, which is right every frame but the one where it
+     * changed. The first frame after a reconstruction is switched on is exactly the frame that
+     * matters.
+     */
+    private sceneSize;
     /**
      * Whether the device has gone.
      *
@@ -1763,7 +1946,9 @@ export declare class WebGPURenderer implements RendererApi {
      * 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;
+    drawMesh(mesh: GpuMesh, model: ArrayLike<number>, depthLayer?: number, tint?: Vec3 | null, 
+    /** Where it was last frame. See `RendererApi.drawMesh`, and `runMotion` for what reads it. */
+    previousModel?: ArrayLike<number> | null): void;
     /**
      * Draw a mesh that lets the world through, at `opacity`.
      *
@@ -2165,6 +2350,64 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private postField;
     /** Sample zero of the depth, into something the generated shaders can sample. */
+    /**
+     * Allocate what a reconstruction needs, and release it when nobody is asking.
+     *
+     * Sized by a key rather than by comparing four numbers, because three of the six targets are the
+     * output's size and three are the render's, and a comparison that checked one pair would rebuild
+     * half of them on a resize and keep the other half at the old size — which the device accepts,
+     * a bind group holding views of two different sizes being perfectly legal, and which draws a
+     * picture with a piece of it at the wrong scale.
+     */
+    private ensureReconstruction;
+    /**
+     * The two dispatches, over one explicit layout.
+     *
+     * **Explicit and not `layout: 'auto'`**, which §3 row 51 is about: an inferred layout names only
+     * the bindings its own entry point reads, and these two read different subsets of one module —
+     * the sharpen touches nothing but the history and the target. Two inferred layouts cannot share
+     * a bind group, and building two groups over the same resources is two things to keep in step.
+     */
+    private buildReconPipelines;
+    /**
+     * The four groups, one a direction of the ping-pong and one a dispatch.
+     *
+     * The resolve reads history `1 - write` and writes history `write`; the sharpen reads history
+     * `write` and writes the shown picture. A group holds the views it was built with, so this is
+     * called whenever any of them is replaced.
+     */
+    private rebuildReconGroups;
+    /**
+     * Remember that this mesh moved, so the motion pass can draw where it was.
+     *
+     * Silent unless a reconstruction is running: a scene that always states its previous transforms
+     * — which is the right thing for a scene to do, the alternative being to know what the renderer
+     * is configured as — must cost nothing at all when nobody is going to read them.
+     */
+    private recordMotion;
+    /**
+     * The pipeline the motion pass draws with, built once.
+     *
+     * **The position buffer alone**, because that is all the shader reads and a mesh keeps one buffer
+     * an attribute — so this binds buffer zero and nothing else, whatever else the mesh carries.
+     */
+    private buildMotionPipeline;
+    /** The pipeline for one vertex stride, built on first sight of it. */
+    private motionPipelineFor;
+    /**
+     * Where every mover was last frame, into the motion target.
+     *
+     * **After everything that draws and before the resolve reads it.** The frame's depth has to be
+     * finished for the equality test to mean anything, and the resolve is what consumes the result.
+     */
+    private runMotion;
+    /**
+     * DriftTR tier 0: the jittered render at the render size into the picture at the output size.
+     *
+     * `recon/resolve.ts` is the reference this is held to and `scripts/recon-parity.mjs` compares the
+     * two; nothing here decides anything the reference does not.
+     */
+    private runReconstruction;
     private resolveDepth;
     /**
      * Occlusion from the depth the resolve produced, then a blur across it.
@@ -2543,6 +2786,81 @@ export declare class WebGPURenderer implements RendererApi {
      * 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;
+    /**
+     * Declare a baked distance field that indirect light may be traced against.
+     *
+     * **The seam is `addOccluder`'s, and for `addOccluder`'s reason.** A distance field is the shape
+     * of a thing it is safe to be *traced against*, and only a consumer knows which of its objects
+     * that is true of — the walls and the terrain, not the leaves, not the water, not the thing it
+     * is about to delete. A renderer that derived the field from whatever was drawn would trace
+     * against the foliage and light the room with a hedge.
+     *
+     * **Declared anywhere in the frame and composed at its end**, which is the one window where
+     * every declaration is in and the encoder has no render pass open. Cleared at `beginFrame` with
+     * the decal and reflection queues, so a consumer redeclares every frame and a field it stops
+     * declaring stops lighting.
+     *
+     * The field is in the model matrix's own space and the matrix must carry uniform scale only —
+     * `composeGlobalField` gives the reason: a distance is not preserved by a non-uniform scale, and
+     * the factor to correct by depends on the direction to the nearest surface, which is exactly
+     * what a distance field does not record.
+     *
+     * **`albedo` is what colour this placement's surface is, and it decides what the bounce carries.**
+     * What leaves a surface is the light arriving times its albedo, so a ray that lands on a wall
+     * and does not know its colour returns the same answer for a red wall and a white one — measured
+     * on `demo/dev/bounce.html` before this argument existed. It is a placement's rather than a
+     * field's, because the same baked shape is placed many times and two pillars cut from one mould
+     * may be painted differently. White where it is left out, so every existing caller is unchanged.
+     */
+    addDistanceField(field: FieldSource, model: ReadonlyMat4, albedo?: ArrayLike<number>): void;
+    /** Forget the fields declared this frame, for a consumer that rebuilds its list mid-frame. */
+    clearDistanceFields(): void;
+    /**
+     * Compose what the frame declared, or nothing at all.
+     *
+     * **Nothing at all is the ordinary case and must cost nothing.** `quality.indirectLight` is off
+     * by default and a frame that declared no fields has nothing to compose, so both are answered
+     * before the composer exists — which is what keeps the eighteen scenes byte-identical with the
+     * flag off rather than merely close.
+     */
+    private runIndirectLight;
+    private composeDistanceField;
+    /** The world field this frame composed, or null where none was. For a pass that marches it. */
+    get distanceField(): ComposedField | null;
+    /**
+     * Refresh this frame's share of the probe grid from the world field, or do nothing at all.
+     *
+     * **Doing nothing is the ordinary case and must cost nothing**, which is why every condition is
+     * answered before the baker exists: a frame may have composed no field — including a frame that
+     * declared none after a frame that did, where the composer exists and holds nothing — and a
+     * profile may have asked for no probe array. With either false this returns having allocated
+     * nothing and recorded nothing, which is what keeps the scenes byte-identical.
+     *
+     * **The grid is the declared one, or one fitted to the fields themselves.** A consumer that
+     * placed its probes always wins. One that did not gets a grid around whatever it said its light
+     * may be traced against — which is the right extent rather than a convenient one, because a grid
+     * sized to everything drawn would spend its probes on the inside of the sky.
+     */
+    private bakeIndirectProbes;
+    /** The declared grid, or one fitted to this frame's fields, or null where neither is possible. */
+    private indirectGrid;
+    /**
+     * The device milliseconds the last composed field took, or null where nothing measured it.
+     *
+     * One frame behind, because a timestamp is read back and a readback that blocked would be the
+     * measurement changing what it measures. Null also where no field has ever been composed, and
+     * where the device was not asked for `timestamp-query`.
+     */
+    get distanceFieldMs(): number | null;
+    /**
+     * The device milliseconds the last traced probe refresh took, or null where nothing measured it.
+     *
+     * **A refresh rather than a grid**, which is `PROBES_PER_FRAME` probes and is what a frame
+     * actually pays. One frame behind, for the reason `distanceFieldMs` gives.
+     */
+    get indirectBakeMs(): number | null;
+    /** Ask for the last frame's figures, once the frame that recorded them has been submitted. */
+    readDistanceFieldTimings(): void;
     /**
      * Whether a mesh is entirely behind the occluders declared this frame.
      *
@@ -2592,6 +2910,28 @@ export declare class WebGPURenderer implements RendererApi {
     private preparingPasses;
     /** Mutated in place, because `beginFrame` is a per-frame path. See `PassDefinition.prepare`. */
     private readonly prepareContext;
+    /**
+     * The object handed to a pass as `PrepareContext.environment`, rebuilt only when it changes.
+     *
+     * **Mutated in place for the reason the context above is**: this runs once a frame for every
+     * registered pass, and the house rule about per-frame allocation binds the seam as much as the
+     * verbs. The view is the only field that can change identity, and it changes when the grid's
+     * layer count does.
+     */
+    private readonly passEnvironment;
+    /**
+     * The frame's reconstruction jitter: one step of the sequence a frame, taken before any pass
+     * prepares.
+     *
+     * **Here and not in `bindMeshPass`, for two reasons that were both defects.** A registered pass
+     * prepares at `beginFrame`, before any mesh pass is bound, so a jitter chosen there could not
+     * reach it — and the GPU-driven pipeline draws its whole world in `prepare`, unjittered, into a
+     * resolve that un-jitters everything. And a frame that bound its mesh pass twice took two steps
+     * of the sequence and resolved against the second.
+     *
+     * The sizes are the frame's by now: `ensureReconstruction` has run.
+     */
+    private settleReconJitter;
     /**
      * Give every pass that owns a target its chance to fill it, before the frame's own opens.
      *
@@ -2929,7 +3269,22 @@ export declare class WebGPURenderer implements RendererApi {
     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. */
+    /**
+     * Record that one layer now holds a convolution, without counting a rebake twice.
+     *
+     * **And rebuild the flat groups on the last one**, which is the third time this backend has paid
+     * for a bind group holding whatever texture existed when it was built. `flatTextures` resolves
+     * `uEnvironment` to a one-texel **white** stand-in while `probeBaked` is false, so a grid filled
+     * by the trace rather than by `bakeProbeGrid` — which runs before any frame and therefore before
+     * any group — leaves every flat group holding that white for the life of the renderer. The
+     * uniform beside it flips to "use the grid" and the grid the shader reads is pure white.
+     *
+     * Measured on `demo/dev/bounce.html?seed=0`: every surface came back at exactly its own albedo
+     * times 255, with the sun switched off and the trace pinned to a constant. It had been recorded
+     * as undefined memory in the probe array; it is a deliberate white texture, read on purpose.
+     * The refraction snapshot's own note two hundred lines below says the same thing about the same
+     * mistake, and `setProbeGrid` says it about the array being replaced.
+     */
     private markProbeFilled;
     /**
      * The array every probe is a layer of, sized for a grid.