@driftengine/core 3.61.0

package/dist/render/drawingBuffer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A ceiling on how many pixels one frame may be, independent of how big the window is.
+ *
+ * `maxDevicePixelRatio` caps *density* — pixels per CSS pixel — which is the right lever
+ * for "is this panel high-DPI" and the wrong one for "how much frame is this". Density
+ * held constant, the cost of a frame is still whatever area the player last dragged their
+ * window to, and the frame is roughly 90% fragment-bound, so window size is an
+ * uncontrolled multiplier on the whole renderer.
+ *
+ * That is fine right up until it isn't, because vsync quantises the consequence. A frame
+ * that fits a 120 Hz slot with 5% to spare and then grows 10% does not run 10% slower; it
+ * misses the slot and is shown at 60. Going fullscreen is exactly such a growth — the
+ * browser's toolbar was the margin — so the symptom arrives as "fullscreen halves the
+ * frame rate", which sounds like a bug in fullscreen and is arithmetic about area.
+ *
+ * A budget makes that cost bounded and, more usefully, *legible*: a player can move it
+ * and watch the frame rate move, which is the same argument that put the resolution lever
+ * on the settings screen. Zero means uncapped, for a machine that would rather have the
+ * pixels.
+ */
+/** Mutable so the caller can own one and keep `resize` allocation-free. */
+export interface BufferSize {
+    width: number;
+    height: number;
+}
+/**
+ * Fit `width` x `height` under `maxPixels`, preserving aspect, into `out`.
+ *
+ * Writes rather than returns, because `Renderer.resize` runs every frame and per-frame
+ * allocation is forbidden (AGENTS.md). Non-positive and non-finite budgets mean uncapped:
+ * this runs in the frame loop, where a corrupt stored setting has to degrade to the old
+ * behaviour rather than throw.
+ *
+ * Scaled by the square root of the ratio, so both axes shrink together and
+ * `Renderer.aspect` still describes the shot the camera composed for. Rounded *down*, so
+ * the budget is a promise rather than an approximation — the whole point is that a number
+ * a player chose is the number they get.
+ */
+export declare function fitToPixelBudget(width: number, height: number, maxPixels: number, out: BufferSize): void;
+/**
+ * The size the next frame is drawn at, into `out`.
+ *
+ * **A locked buffer is handed back exactly, and no cap of any kind touches it.** That is
+ * the one rule in here that is not about performance: a lock is a caller naming a size for
+ * a reason no quality setting can see — a clip is 1080x1920 whatever anybody's frame rate
+ * is, and `Renderer.aspect` follows the lock so the replay's shots are composed for the
+ * *file* rather than for the window it is being written from. A budget applied over the
+ * top would silently write a file that is not the size it claims and re-frame every shot
+ * in it. Pass `dpr` already clamped; unlocked, the CSS box is scaled by it and then fitted
+ * under `maxPixels`.
+ */
+export declare function drawingBufferSize(cssWidth: number, cssHeight: number, dpr: number, lockedWidth: number, lockedHeight: number, maxPixels: number, out: BufferSize): void;

package/dist/render/drawingBuffer.js

@@ -0,0 +1,67 @@
+/**
+ * A ceiling on how many pixels one frame may be, independent of how big the window is.
+ *
+ * `maxDevicePixelRatio` caps *density* — pixels per CSS pixel — which is the right lever
+ * for "is this panel high-DPI" and the wrong one for "how much frame is this". Density
+ * held constant, the cost of a frame is still whatever area the player last dragged their
+ * window to, and the frame is roughly 90% fragment-bound, so window size is an
+ * uncontrolled multiplier on the whole renderer.
+ *
+ * That is fine right up until it isn't, because vsync quantises the consequence. A frame
+ * that fits a 120 Hz slot with 5% to spare and then grows 10% does not run 10% slower; it
+ * misses the slot and is shown at 60. Going fullscreen is exactly such a growth — the
+ * browser's toolbar was the margin — so the symptom arrives as "fullscreen halves the
+ * frame rate", which sounds like a bug in fullscreen and is arithmetic about area.
+ *
+ * A budget makes that cost bounded and, more usefully, *legible*: a player can move it
+ * and watch the frame rate move, which is the same argument that put the resolution lever
+ * on the settings screen. Zero means uncapped, for a machine that would rather have the
+ * pixels.
+ */
+/** Smallest drawing buffer worth asking a driver for; zero is a GL error, not a picture. */
+const MIN_SIDE = 2;
+/**
+ * Fit `width` x `height` under `maxPixels`, preserving aspect, into `out`.
+ *
+ * Writes rather than returns, because `Renderer.resize` runs every frame and per-frame
+ * allocation is forbidden (AGENTS.md). Non-positive and non-finite budgets mean uncapped:
+ * this runs in the frame loop, where a corrupt stored setting has to degrade to the old
+ * behaviour rather than throw.
+ *
+ * Scaled by the square root of the ratio, so both axes shrink together and
+ * `Renderer.aspect` still describes the shot the camera composed for. Rounded *down*, so
+ * the budget is a promise rather than an approximation — the whole point is that a number
+ * a player chose is the number they get.
+ */
+export function fitToPixelBudget(width, height, maxPixels, out) {
+    out.width = width;
+    out.height = height;
+    if (!Number.isFinite(maxPixels) || maxPixels <= 0)
+        return;
+    const pixels = width * height;
+    if (pixels <= maxPixels)
+        return;
+    const scale = Math.sqrt(maxPixels / pixels);
+    out.width = Math.max(MIN_SIDE, Math.floor(width * scale));
+    out.height = Math.max(MIN_SIDE, Math.floor(height * scale));
+}
+/**
+ * The size the next frame is drawn at, into `out`.
+ *
+ * **A locked buffer is handed back exactly, and no cap of any kind touches it.** That is
+ * the one rule in here that is not about performance: a lock is a caller naming a size for
+ * a reason no quality setting can see — a clip is 1080x1920 whatever anybody's frame rate
+ * is, and `Renderer.aspect` follows the lock so the replay's shots are composed for the
+ * *file* rather than for the window it is being written from. A budget applied over the
+ * top would silently write a file that is not the size it claims and re-frame every shot
+ * in it. Pass `dpr` already clamped; unlocked, the CSS box is scaled by it and then fitted
+ * under `maxPixels`.
+ */
+export function drawingBufferSize(cssWidth, cssHeight, dpr, lockedWidth, lockedHeight, maxPixels, out) {
+    if (lockedWidth > 0 && lockedHeight > 0) {
+        out.width = lockedWidth;
+        out.height = lockedHeight;
+        return;
+    }
+    fitToPixelBudget(Math.round(cssWidth * dpr), Math.round(cssHeight * dpr), maxPixels, out);
+}

package/dist/render/emptyTexture.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 1x1 placeholders for sampler slots a pass declares but does not use.
+ *
+ * A shader's sampler uniforms exist whether or not the feature behind them is switched
+ * on: the flat pass declares three directional shadow maps and twelve cubemaps, and a
+ * quality profile with shadows off still compiles every one of them. The obvious way to
+ * say "there is nothing here" is to bind `null` to the unit, and it is wrong.
+ *
+ * A sampler bound to no texture is *incomplete*. The GL spec says sampling one yields
+ * zero, which sounds like a safe default and is only safe if the sample never executes.
+ * The guards in this engine are runtime values — `uShadowStrength <= 0.0`, an index
+ * compared against -1 — so a driver is free to fetch the descriptor before it evaluates
+ * the branch that would have skipped it. Descriptor fetches are scalar loads, and a
+ * descriptor for a texture that does not exist is not guaranteed to point anywhere.
+ *
+ * On a Radeon RX 9070 XT (RDNA4, Mesa 25.2.8) that read lands outside the process's GPU
+ * address space and faults:
+ *
+ *   amdgpu: [gfxhub] page fault ... Faulty UTCL2 client ID: SQC (data)
+ *   amdgpu: ring gfx_0.0.0 timeout -> Ring gfx_0.0.0 reset -> device wedged
+ *
+ * The context dies, the compositor stalls for a second or two while the driver resets the
+ * card, and nothing in the API reports an error — the page simply loses its context a few
+ * seconds in. Binding a real texture costs one 1x1 upload per renderer and removes the
+ * question: every declared sampler has something complete behind it, whether the pass
+ * reads it or not. three.js keeps an empty texture per target for the same reason.
+ *
+ * Not a workaround for one card. An incomplete sampler is undefined territory that
+ * happens to be survivable on most drivers, and this makes the engine stop relying on
+ * that.
+ */
+/**
+ * A complete 1x1 texture for any unused `sampler2D` slot.
+ *
+ * `NEAREST` and `CLAMP_TO_EDGE` because a single texel has no mip chain: leaving the
+ * default `LINEAR_MIPMAP_LINEAR` minification filter on a texture with only level 0 makes
+ * it incomplete again, which is the exact state this exists to avoid.
+ */
+export declare function createEmptyTexture2D(gl: WebGL2RenderingContext): WebGLTexture;
+/**
+ * The same for an unused `sampler2DArray` slot: one layer, one texel.
+ *
+ * The point-shadow array exists only once a world has said how many lights it has, and a scene is
+ * free to draw before it does. One layer rather than the full pool's worth, because nothing reads
+ * it: `uPointShadowLayer` is −1 for every light while this is bound, and the layer index never
+ * reaches a fetch. It is here to be *complete*, which is the whole subject of this file.
+ *
+ * White rather than black, matching the one-texel cube the WebGPU side keeps and for its reason:
+ * a full-depth texel reads as an occluder at the far plane, so the worst a lookup that should not
+ * have happened can do is find nothing in the way. Zeroes would mean an occluder pressed against
+ * every lamp, and every surface in the scene in shadow.
+ */
+export declare function createEmptyTexture2DArray(gl: WebGL2RenderingContext): WebGLTexture;
+/**
+ * The same for an unused `samplerCube` slot.
+ *
+ * All six faces are supplied: a cubemap missing any one of them is incomplete however
+ * complete the other five are.
+ */
+export declare function createEmptyTextureCube(gl: WebGL2RenderingContext): WebGLTexture;

package/dist/render/emptyTexture.js

@@ -0,0 +1,103 @@
+/**
+ * 1x1 placeholders for sampler slots a pass declares but does not use.
+ *
+ * A shader's sampler uniforms exist whether or not the feature behind them is switched
+ * on: the flat pass declares three directional shadow maps and twelve cubemaps, and a
+ * quality profile with shadows off still compiles every one of them. The obvious way to
+ * say "there is nothing here" is to bind `null` to the unit, and it is wrong.
+ *
+ * A sampler bound to no texture is *incomplete*. The GL spec says sampling one yields
+ * zero, which sounds like a safe default and is only safe if the sample never executes.
+ * The guards in this engine are runtime values — `uShadowStrength <= 0.0`, an index
+ * compared against -1 — so a driver is free to fetch the descriptor before it evaluates
+ * the branch that would have skipped it. Descriptor fetches are scalar loads, and a
+ * descriptor for a texture that does not exist is not guaranteed to point anywhere.
+ *
+ * On a Radeon RX 9070 XT (RDNA4, Mesa 25.2.8) that read lands outside the process's GPU
+ * address space and faults:
+ *
+ *   amdgpu: [gfxhub] page fault ... Faulty UTCL2 client ID: SQC (data)
+ *   amdgpu: ring gfx_0.0.0 timeout -> Ring gfx_0.0.0 reset -> device wedged
+ *
+ * The context dies, the compositor stalls for a second or two while the driver resets the
+ * card, and nothing in the API reports an error — the page simply loses its context a few
+ * seconds in. Binding a real texture costs one 1x1 upload per renderer and removes the
+ * question: every declared sampler has something complete behind it, whether the pass
+ * reads it or not. three.js keeps an empty texture per target for the same reason.
+ *
+ * Not a workaround for one card. An incomplete sampler is undefined territory that
+ * happens to be survivable on most drivers, and this makes the engine stop relying on
+ * that.
+ */
+/** Opaque black, which is what a shadow lookup should read where nothing occludes. */
+const ONE_BLACK_TEXEL = new Uint8Array([0, 0, 0, 255]);
+/** Full depth, which is the far plane: an occluder as far away as the light reaches. */
+const ONE_WHITE_TEXEL = new Uint8Array([255]);
+function allocate(gl, label) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error(`${label}: createTexture failed`);
+    return texture;
+}
+/**
+ * A complete 1x1 texture for any unused `sampler2D` slot.
+ *
+ * `NEAREST` and `CLAMP_TO_EDGE` because a single texel has no mip chain: leaving the
+ * default `LINEAR_MIPMAP_LINEAR` minification filter on a texture with only level 0 makes
+ * it incomplete again, which is the exact state this exists to avoid.
+ */
+export function createEmptyTexture2D(gl) {
+    const texture = allocate(gl, 'emptyTexture2D');
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, ONE_BLACK_TEXEL);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return texture;
+}
+/**
+ * The same for an unused `sampler2DArray` slot: one layer, one texel.
+ *
+ * The point-shadow array exists only once a world has said how many lights it has, and a scene is
+ * free to draw before it does. One layer rather than the full pool's worth, because nothing reads
+ * it: `uPointShadowLayer` is −1 for every light while this is bound, and the layer index never
+ * reaches a fetch. It is here to be *complete*, which is the whole subject of this file.
+ *
+ * White rather than black, matching the one-texel cube the WebGPU side keeps and for its reason:
+ * a full-depth texel reads as an occluder at the far plane, so the worst a lookup that should not
+ * have happened can do is find nothing in the way. Zeroes would mean an occluder pressed against
+ * every lamp, and every surface in the scene in shadow.
+ */
+export function createEmptyTexture2DArray(gl) {
+    const texture = allocate(gl, 'emptyTexture2DArray');
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.R8, 1, 1, 1);
+    gl.texSubImage3D(gl.TEXTURE_2D_ARRAY, 0, 0, 0, 0, 1, 1, 1, gl.RED, gl.UNSIGNED_BYTE, ONE_WHITE_TEXEL);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+    return texture;
+}
+/**
+ * The same for an unused `samplerCube` slot.
+ *
+ * All six faces are supplied: a cubemap missing any one of them is incomplete however
+ * complete the other five are.
+ */
+export function createEmptyTextureCube(gl) {
+    const texture = allocate(gl, 'emptyTextureCube');
+    gl.bindTexture(gl.TEXTURE_CUBE_MAP, texture);
+    for (let face = 0; face < 6; face++) {
+        gl.texImage2D(gl.TEXTURE_CUBE_MAP_POSITIVE_X + face, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, ONE_BLACK_TEXEL);
+    }
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_CUBE_MAP, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_CUBE_MAP, null);
+    return texture;
+}

package/dist/render/envProbeArray.d.ts

@@ -0,0 +1,85 @@
+/** Every probe in a grid as one array texture, and the scratch a bake fills it through. */
+/**
+ * What one level of one layer is for, since the chain carries two different integrals.
+ *
+ * Levels up to `ggxMaxLevel` are the reflection, convolved against the GGX lobe at the roughness
+ * `roughnessForLevel` gives them. The level above that is the diffuse ambient, convolved against
+ * the cosine. They are the same pass with a different weight, and telling them apart is a uniform.
+ */
+export type ProbeLevelKind = 'radiance' | 'irradiance';
+/**
+ * Every probe of a grid as one `TEXTURE_2D_ARRAY` of octahedral maps.
+ *
+ * **One binding for any number of probes, which is the whole design.** GLSL ES cannot index a
+ * sampler array with a non-constant expression, so a grid of cubes would need a `samplerCube` each
+ * and a branch chain over them — the shape twelve point-shadow cubemaps had before
+ * `pointShadowArray.ts`, and the reason that file exists. A layer index has no such limit.
+ *
+ * **It replaces the `samplerCube` rather than joining it.** Fifteen of WebGL2's guaranteed sixteen
+ * texture units are spent, and `REFRACT_SCENE_TEXTURE_UNIT`'s comment says what the next sampler
+ * has to do about that: fold into an existing binding. This binds where the probe cube used to,
+ * and the irradiance level folds the diffuse term in beside the reflection, so the grid costs no
+ * units at all and unit 15 stays free.
+ *
+ * **The chain stops at the irradiance level.** `texStorage3D` may allocate fewer levels than a
+ * full chain, so there is nothing above it — a 256 edge is six levels rather than nine, and the
+ * levels that would have held one, four and sixteen texels are not allocated at all.
+ */
+export declare class EnvProbeArray {
+    /** The array the lit pass samples. Octahedral, one layer a probe, gutter included. */
+    readonly texture: WebGLTexture;
+    /** Texels a side, including the one-texel gutter `octInsetUv` insets past. */
+    readonly edge: number;
+    readonly layers: number;
+    /** The coarsest level the reflection reaches, which is `uEnvironmentMaxLod`. */
+    readonly ggxMaxLevel: number;
+    /** The level holding the cosine convolution, one above the reflection's coarsest. */
+    readonly irradianceLevel: number;
+    private readonly framebuffer;
+    /** One flag a layer, because a grid may be baked a probe at a time across frames. */
+    private readonly baked;
+    private bakedCount;
+    /**
+     * Set once if the allocation is refused, and never cleared.
+     *
+     * A grid is an improvement to an appearance rather than a requirement, exactly as one probe was:
+     * a device that cannot afford the layers keeps the sky-and-ground gradient and loses nothing
+     * else. Sixty-four layers at the default edge is 43.7 MB, which is affordable on the parts this
+     * engine targets and is not affordable everywhere.
+     */
+    private unusable;
+    constructor(gl: WebGL2RenderingContext, edge: number, layers: number, floatColor: boolean);
+    /**
+     * Convolve one probe's captured cube into one layer, every level of it.
+     *
+     * **The caller draws, and this owns the target**, which is the split `ReflectionProbe.prefilter`
+     * already makes with the pass that convolves: a probe has no business knowing what a shader is,
+     * and a pass has no business knowing which layer it is filling.
+     *
+     * **One draw a level rather than six.** A cube's convolution runs the triangle once per face per
+     * level; an octahedral map has no faces, so a level is one draw and a probe's convolution is six
+     * times fewer of them than the cube it replaces.
+     *
+     * **The source is a different texture object from the target and that is not tidiness.** WebGL2's
+     * rendering-feedback-loop check is per texture object rather than per image, so a draw that
+     * samples the array while any layer of it is attached is `INVALID_OPERATION` — on a layer it does
+     * not even write. `pointShadowArray.ts` records paying for this on a probe before that file
+     * existed. Here the source is the scratch cube and the target is the array, so it cannot arise.
+     */
+    convolve(gl: WebGL2RenderingContext, layer: number, run: (level: number, roughness: number, kind: ProbeLevelKind) => void): void;
+    /**
+     * Whether the shader may sample this, which needs **every** layer filled.
+     *
+     * A grid baked a probe a frame passes through a state where some layers hold whatever the driver
+     * left in them, and a fragment blending eight corners reads four of those. The gate is therefore
+     * the whole grid rather than any part of it — the same rule one probe already had, where
+     * `uEnvironmentEnabled` stayed at zero until a bake finished, for the same reason: a car
+     * mirroring uninitialised memory is worse than a car mirroring a gradient.
+     */
+    get ready(): boolean;
+    /** How many layers have been convolved, for a caller pacing a bake across frames. */
+    get filled(): number;
+    /** Whether this allocated at all. False means the scene renders without a grid. */
+    get usable(): boolean;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/envProbeArray.js

@@ -0,0 +1,164 @@
+/** Every probe in a grid as one array texture, and the scratch a bake fills it through. */
+import { ggxMaxLevelFor, irradianceLevelFor, roughnessForLevel } from './prefilterEnvMap.js';
+/**
+ * Every probe of a grid as one `TEXTURE_2D_ARRAY` of octahedral maps.
+ *
+ * **One binding for any number of probes, which is the whole design.** GLSL ES cannot index a
+ * sampler array with a non-constant expression, so a grid of cubes would need a `samplerCube` each
+ * and a branch chain over them — the shape twelve point-shadow cubemaps had before
+ * `pointShadowArray.ts`, and the reason that file exists. A layer index has no such limit.
+ *
+ * **It replaces the `samplerCube` rather than joining it.** Fifteen of WebGL2's guaranteed sixteen
+ * texture units are spent, and `REFRACT_SCENE_TEXTURE_UNIT`'s comment says what the next sampler
+ * has to do about that: fold into an existing binding. This binds where the probe cube used to,
+ * and the irradiance level folds the diffuse term in beside the reflection, so the grid costs no
+ * units at all and unit 15 stays free.
+ *
+ * **The chain stops at the irradiance level.** `texStorage3D` may allocate fewer levels than a
+ * full chain, so there is nothing above it — a 256 edge is six levels rather than nine, and the
+ * levels that would have held one, four and sixteen texels are not allocated at all.
+ */
+export class EnvProbeArray {
+    /** The array the lit pass samples. Octahedral, one layer a probe, gutter included. */
+    texture;
+    /** Texels a side, including the one-texel gutter `octInsetUv` insets past. */
+    edge;
+    layers;
+    /** The coarsest level the reflection reaches, which is `uEnvironmentMaxLod`. */
+    ggxMaxLevel;
+    /** The level holding the cosine convolution, one above the reflection's coarsest. */
+    irradianceLevel;
+    framebuffer;
+    /** One flag a layer, because a grid may be baked a probe at a time across frames. */
+    baked;
+    bakedCount = 0;
+    /**
+     * Set once if the allocation is refused, and never cleared.
+     *
+     * A grid is an improvement to an appearance rather than a requirement, exactly as one probe was:
+     * a device that cannot afford the layers keeps the sky-and-ground gradient and loses nothing
+     * else. Sixty-four layers at the default edge is 43.7 MB, which is affordable on the parts this
+     * engine targets and is not affordable everywhere.
+     */
+    unusable = false;
+    constructor(gl, edge, layers, floatColor) {
+        this.edge = edge;
+        this.layers = Math.max(1, Math.trunc(layers));
+        this.ggxMaxLevel = ggxMaxLevelFor(edge);
+        this.irradianceLevel = irradianceLevelFor(edge);
+        this.baked = new Uint8Array(this.layers);
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('EnvProbeArray: createTexture failed');
+        this.texture = texture;
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+        /*
+         * **Drained once before the allocation, because `getError` reports and clears.** Without this
+         * the check below answers for whatever happened earlier in the frame, and a grid would stand
+         * down over somebody else's mistake. One call rather than a loop: a context that answers an
+         * error forever is a context this would never leave.
+         */
+        gl.getError();
+        gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 
+        /* Up to and including the irradiance level, and nothing above it. */
+        this.irradianceLevel + 1, floatColor ? gl.RGBA16F : gl.RGBA8, edge, edge, this.layers);
+        /*
+         * **`LINEAR_MIPMAP_NEAREST`, and the choice is a statement rather than a saving.** A level's
+         * gutter is one texel wide, so its inset in normalised coordinates is `1 / edge` and differs
+         * between levels; hardware trilinear applies one coordinate to both levels it blends, so one
+         * of the two would be read at the wrong inset — by a thirty-second of the map at the top of
+         * the chain. The shader fetches two levels at their own insets and mixes them, so the only
+         * filtering asked of the hardware is bilinear inside one level.
+         */
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        /*
+         * Clamped, and the gutter is what makes that correct. An octahedral map's border is a fold
+         * rather than an edge, so `CLAMP_TO_EDGE` repeating the last real texel would be wrong by
+         * 4.6e-2 in direction; the gutter holds the folded texel and the inset keeps every sample
+         * inside it, which is measured in `octahedral.test.ts`.
+         */
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+        if (gl.getError() !== gl.NO_ERROR) {
+            this.unusable = true;
+            console.warn(`[driftengine] this device would not allocate ${this.layers} environment probe layers at ` +
+                `${edge}x${edge}. Reflective surfaces keep the sky-and-ground gradient and diffuse ` +
+                'ambient stays whatever the scene set. Nothing else is affected.');
+        }
+        const framebuffer = gl.createFramebuffer();
+        if (framebuffer === null)
+            throw new Error('EnvProbeArray: createFramebuffer failed');
+        this.framebuffer = framebuffer;
+    }
+    /**
+     * Convolve one probe's captured cube into one layer, every level of it.
+     *
+     * **The caller draws, and this owns the target**, which is the split `ReflectionProbe.prefilter`
+     * already makes with the pass that convolves: a probe has no business knowing what a shader is,
+     * and a pass has no business knowing which layer it is filling.
+     *
+     * **One draw a level rather than six.** A cube's convolution runs the triangle once per face per
+     * level; an octahedral map has no faces, so a level is one draw and a probe's convolution is six
+     * times fewer of them than the cube it replaces.
+     *
+     * **The source is a different texture object from the target and that is not tidiness.** WebGL2's
+     * rendering-feedback-loop check is per texture object rather than per image, so a draw that
+     * samples the array while any layer of it is attached is `INVALID_OPERATION` — on a layer it does
+     * not even write. `pointShadowArray.ts` records paying for this on a probe before that file
+     * existed. Here the source is the scratch cube and the target is the array, so it cannot arise.
+     */
+    convolve(gl, layer, run) {
+        if (this.unusable)
+            return;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        for (let level = 0; level <= this.irradianceLevel; level++) {
+            /* A level is half the width of the one below it, and the viewport has to say so or the
+               triangle covers a quarter of the target and leaves the rest at whatever was there. */
+            const size = Math.max(1, this.edge >> level);
+            gl.viewport(0, 0, size, size);
+            gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, level, layer);
+            if (level === 0 && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+                this.unusable = true;
+                gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+                console.warn('[driftengine] this driver will not render into an environment probe layer, so ' +
+                    'reflective surfaces keep the sky-and-ground approximation. Nothing else is affected.');
+                return;
+            }
+            const irradiance = level === this.irradianceLevel;
+            run(level, irradiance ? 1 : roughnessForLevel(level, this.ggxMaxLevel), irradiance ? 'irradiance' : 'radiance');
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        if (this.baked[layer] !== 1) {
+            this.baked[layer] = 1;
+            this.bakedCount++;
+        }
+    }
+    /**
+     * Whether the shader may sample this, which needs **every** layer filled.
+     *
+     * A grid baked a probe a frame passes through a state where some layers hold whatever the driver
+     * left in them, and a fragment blending eight corners reads four of those. The gate is therefore
+     * the whole grid rather than any part of it — the same rule one probe already had, where
+     * `uEnvironmentEnabled` stayed at zero until a bake finished, for the same reason: a car
+     * mirroring uninitialised memory is worse than a car mirroring a gradient.
+     */
+    get ready() {
+        return !this.unusable && this.bakedCount === this.layers;
+    }
+    /** How many layers have been convolved, for a caller pacing a bake across frames. */
+    get filled() {
+        return this.bakedCount;
+    }
+    /** Whether this allocated at all. False means the scene renders without a grid. */
+    get usable() {
+        return !this.unusable;
+    }
+    dispose(gl) {
+        gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteTexture(this.texture);
+        this.baked.fill(0);
+        this.bakedCount = 0;
+    }
+}

package/dist/render/equirectToCube.d.ts

@@ -0,0 +1,54 @@
+/** An equirectangular image resampled onto the six faces of a cube. */
+/**
+ * The direction a texel stands for, per face.
+ *
+ * `forward` is the face centre, `basisX` steps across a row and `basisY` down a column, matching
+ * `webgpu/probePass.ts`'s `PROBE_FACE_BASIS` exactly — the same table, and it is the same table
+ * because getting one sign wrong mirrors a single face, which projects to a plausible-looking
+ * wrong answer rather than to an error.
+ *
+ * **It lived in `irradianceSh.ts` until the spherical-harmonic path was retired**, and it moved
+ * here rather than being deleted with it: the capture is still a cube, so a loaded environment
+ * still has to know which direction each of its texels stands for. The prefilter's own copy went
+ * with the six-face loop, since an octahedral target has no faces at all.
+ */
+export declare const FACE_BASIS: readonly {
+    readonly forward: readonly [number, number, number];
+    readonly basisX: readonly [number, number, number];
+    readonly basisY: readonly [number, number, number];
+}[];
+/** What a decoded `.hdr` looks like, restated structurally so this imports no package. */
+export interface EquirectSource {
+    readonly width: number;
+    readonly height: number;
+    /** `width * height * 3` linear values, row-major from the top. */
+    readonly data: Float32Array;
+}
+/**
+ * Resample an equirectangular environment onto six cube faces.
+ *
+ * **Backend-neutral, and it produces exactly what the projection already takes.** The output is the
+ * shape a bake produces — six `size * size * 4` arrays of linear RGBA in
+ * cubemap order — so a loaded environment joins the captured path at the same place a bake does,
+ * and everything downstream of the cube is one implementation rather than two.
+ *
+ * **The face basis is imported rather than restated.** This is the fourth place that table would
+ * have appeared, and its failure mode is the one the 2026-08-17 rule is about: a mirrored face
+ * projects perfectly well onto a wrong answer, and the last time two copies disagreed it took
+ * projecting both backends' cubes onto one shared basis to find a sign in the linear Z band.
+ *
+ * ## The convention, stated because there is no universal one
+ *
+ * - **Row 0 is the zenith.** `v = acos(y) / pi`, so the top of the image is `+Y`. Inverting this
+ *   puts the sky underfoot, and every surface is then lit from below with nothing in the picture
+ *   to say why.
+ * - **The centre column is `-Z`.** `u = 0.5 + atan2(x, -z) / 2pi`, which is the engine's own camera
+ *   convention — yaw 0 looks toward `-Z` and positive yaw turns toward `+X` — so `+X` lands three
+ *   quarters of the way across. Choosing the mirror of this passes every brightness check and
+ *   every sky-is-up check, and shows only as a reflection that turns the wrong way.
+ *
+ * **What it costs** is bilinear sampling per texel of the destination, once, at load. **What would
+ * make it wrong** is a source small enough that the cube is upsampling it — at that point the faces
+ * carry interpolation rather than image, and the honest answer is a smaller cube.
+ */
+export declare function equirectToCubeFaces(source: EquirectSource, size: number): Float32Array[];