@driftengine/core 4.1.3 → 4.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 698.4 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 721.2 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/index.js

@@ -102,8 +102,18 @@ export { createRenderer } from './render/backend/createRenderer.js';
  * A consumer who names neither pays nothing: `core-only` is measured with these exported and does
  * not move, because nothing in the forward path reaches them.
  *
- * It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
- * the standard material. `DRAFT_SCENES`, never `SCENES`, until it draws the six published ones.
+ * **It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
+ * the standard material**, and that is the sentence to read before reaching for it. There is no
+ * flag that routes `drawMesh` through this: a consumer packs a scene and contributes the pass, and
+ * `setMaterial`, `setSurfaceGrain`, `setSurfaceRelief` and a skin palette reach none of it. What
+ * would change that is a second copy of the standard material, which `gpuDrivenPass.ts` refuses in
+ * its own header.
+ *
+ * **The line that used to be here said `DRAFT_SCENES`, never `SCENES`, and it went stale the day
+ * the city was published.** `city` is in `SCENES` and says `pipelines: ['gpu-driven']`, so a host
+ * that cannot run the second pipeline reads that from the list rather than from a mount that
+ * refuses. The rule it was standing in for is the one above: what gates a scene is whether this
+ * pass can draw it, not which array it is in.
  */
 export { GPU_DRIVEN_LISTS, GpuDrivenPass, MATERIAL_FLOATS, 
 /*

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

@@ -1066,6 +1066,21 @@ export declare class WebGL2Renderer implements RendererApi {
      * near plane needs the granted answer and not the wished-for one.
      */
     reversedDepth: boolean;
+    /**
+     * What to clear depth to, for the convention this context was actually granted.
+     *
+     * **`DEPTH_CLEAR` is compile-time and this must not be.** That constant is `REVERSED_DEPTH ? 0 :
+     * 1`, and `REVERSED_DEPTH` is what the engine wants rather than what a context gave — so on a
+     * context without `EXT_clip_control` the buffer was cleared to 0 while `depthFunc` was correctly
+     * set to `LEQUAL`, and **nothing in the scene could ever pass**: every fragment is at depth >= 0,
+     * and only depth <= 0 passes. The frame that reaches the screen is the colour clear.
+     *
+     * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**, as every consumer
+     * drawing one flat colour with its interface still on top, at a healthy 60 fps. The compare
+     * beside it was already runtime; this was the half that was not, and the asymmetry is what made
+     * it total rather than subtle.
+     */
+    private get depthClear();
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     private readonly sceneViewProj;
     /**

package/dist/render/backend/webgl2/renderer.js

@@ -1,7 +1,7 @@
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
 import { mat4 } from 'gl-matrix';
-import { DEPTH_CLEAR, DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
+import { DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { PickableSet } from '../../pickable.js';
 import { TEMPORAL_HISTORY_BLEND, TemporalHistory, jitterOffset, jitterProjection, } from '../../temporalAa.js';
 import { DecalPass } from '../../decalPass.js';
@@ -45,7 +45,7 @@ import { packIesAtlas } from '../../iesProfile.js';
 import { MAX_AREA_LIGHTS } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { equirectToCubeFaces } from '../../equirectToCube.js';
-import { SKY_FRAG, SKY_VERT } from '../../shaders/sky.js';
+import { SKY_FRAG, skyVertFor } from '../../shaders/sky.js';
 import { DEPTH_FRAG, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
 import { PointShadowArray } from '../../pointShadowArray.js';
 import { ShadowMap } from '../../shadowMap.js';
@@ -749,6 +749,23 @@ export class WebGL2Renderer {
      * near plane needs the granted answer and not the wished-for one.
      */
     reversedDepth = false;
+    /**
+     * What to clear depth to, for the convention this context was actually granted.
+     *
+     * **`DEPTH_CLEAR` is compile-time and this must not be.** That constant is `REVERSED_DEPTH ? 0 :
+     * 1`, and `REVERSED_DEPTH` is what the engine wants rather than what a context gave — so on a
+     * context without `EXT_clip_control` the buffer was cleared to 0 while `depthFunc` was correctly
+     * set to `LEQUAL`, and **nothing in the scene could ever pass**: every fragment is at depth >= 0,
+     * and only depth <= 0 passes. The frame that reaches the screen is the colour clear.
+     *
+     * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**, as every consumer
+     * drawing one flat colour with its interface still on top, at a healthy 60 fps. The compare
+     * beside it was already runtime; this was the half that was not, and the asymmetry is what made
+     * it total rather than subtle.
+     */
+    get depthClear() {
+        return depthClearFor(this.reversedDepth);
+    }
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     sceneViewProj = new Float32Array(16);
     /**
@@ -1745,7 +1762,10 @@ export class WebGL2Renderer {
             }
         }
         this.filmUniforms = uniformLocations(gl, this.filmProgram, 'film');
-        this.skyProgram = compileProgram(gl, SKY_VERT, SKY_FRAG, 'sky');
+        /* The variant matching what this context was granted, not what the engine wants. See
+           `skyVertFor`: a sky written at the reversed far plane on a conventional context sits in the
+           middle of the depth range and paints over everything behind it. */
+        this.skyProgram = compileProgram(gl, skyVertFor(this.reversedDepth), SKY_FRAG, 'sky');
         this.skyUniforms = uniformLocations(gl, this.skyProgram, 'sky');
         this.scatterProgram = compileProgram(gl, SCATTER_VERT, SCATTER_FRAG, 'scatter');
         this.scatterUniforms = uniformLocations(gl, this.scatterProgram, 'scatter');
@@ -3139,12 +3159,13 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.pointShadowArray?.texture ?? this.emptyTexture2DArray);
         gl.uniform1i(uniforms[POINT_SHADOW_SAMPLER] ?? null, firstUnit);
         gl.uniform1iv(uniforms['uPointShadowLayer[0]'] ?? null, resolved.layers);
-        gl.uniform1fv(uniforms['uPointShadowFar[0]'] ?? null, resolved.far);
+        /* Origin and far plane in one row; see `uPointShadowProjection` in the preamble. */
+        gl.uniform4fv(uniforms['uPointShadowProjection[0]'] ?? null, resolved.projections);
         gl.uniform1fv(uniforms['uPointShadowNear[0]'] ?? null, resolved.near);
         gl.uniform1fv(uniforms['uPointShadowSize[0]'] ?? null, resolved.sourceRadius);
         gl.uniform1fv(uniforms['uPointShadowWeight[0]'] ?? null, resolved.presence);
         gl.uniform1iv(uniforms['uLivePointShadowLayer[0]'] ?? null, resolved.liveLayers);
-        gl.uniform1fv(uniforms['uLivePointShadowFar[0]'] ?? null, resolved.liveFar);
+        gl.uniform4fv(uniforms['uLivePointShadowProjection[0]'] ?? null, resolved.liveProjections);
         gl.uniform1fv(uniforms['uLivePointShadowNear[0]'] ?? null, resolved.liveNear);
         gl.uniform1fv(uniforms['uLivePointShadowSize[0]'] ?? null, resolved.liveSourceRadius);
         gl.uniform1fv(uniforms['uLivePointShadowWeight[0]'] ?? null, resolved.liveWeights);
@@ -3573,7 +3594,7 @@ export class WebGL2Renderer {
         shadowMap.end(this.gl);
         /* Back to the frame's sense; see `beginShadowPass` for why it left it. */
         this.gl.depthFunc(glDepthFuncEqual(this.gl));
-        this.gl.clearDepth(DEPTH_CLEAR);
+        this.gl.clearDepth(this.depthClear);
         this.gpuTimer.end();
         this.shadowPassActive = false;
         this.activeShadowMap = null;
@@ -3949,7 +3970,7 @@ export class WebGL2Renderer {
         finally {
             /* Back to the frame's sense, which `beginShadowPass` leaves the same way. */
             gl.depthFunc(glDepthFuncEqual(gl));
-            gl.clearDepth(DEPTH_CLEAR);
+            gl.clearDepth(this.depthClear);
             this.pointShadowCasters = null;
             this.depthPassCullsFaces = true;
         }

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

@@ -470,6 +470,30 @@ export declare class GpuDrivenPass implements PassDefinition {
      * before the device answers, which nobody sees; the alternative is a frame that draws nothing.
      */
     private blendUsable;
+    /**
+     * The same question about *every other* pipeline in this pass, and the reason it exists is that
+     * 4.1.3 asked it about one.
+     *
+     * **The guard above was written from a log that named `gpu-driven blend`, and the four render
+     * pipelines and eight compute pipelines beside it were left with the shape that caused the
+     * report.** Reported again from an Android handset once that fix shipped: the transparent pass
+     * now skips itself correctly, the overlay still draws and the frame counter still counts — and
+     * the world is black, which is what an invalid *opaque* pipeline looks like once the blended one
+     * has stopped taking the command buffer with it.
+     *
+     * So the whole of `buildPipelines` is built inside one pair of scopes and nothing this pass
+     * encodes runs until they come back clean. The blend pipeline pushes its own pair *inside* that
+     * region, so the two verdicts stay separate: a device that refuses only the transparent pipeline
+     * still draws everything opaque, and a device that refuses anything else turns this pass off
+     * rather than encoding against a handle the driver has already rejected.
+     *
+     * **What it gives up** is the first frames, which draw nothing while the device is still
+     * answering. **What would make it wrong** is a device that never resolves an error scope; the
+     * `popErrorScope` check below is the same concession the blend guard makes, for the same reason.
+     */
+    private usable;
+    /** Why this pass refused itself, in the words the device used, or null while it has not. */
+    private refusal;
     /** Builds the transparent raster's bindings, held until there is a pipeline worth binding to. */
     private makeBlendGroup;
     private blendResolvePipeline;
@@ -641,6 +665,28 @@ export declare class GpuDrivenPass implements PassDefinition {
      * this came from was five errors that were all the same one.
      */
     private watchBlendPipeline;
+    /**
+     * Close the scopes every other pipeline was built in, and refuse the pass where one came back.
+     *
+     * **This is `watchBlendPipeline` widened to the rest of the pass**, and the reason it is separate
+     * is that the two refusals mean different things: a blend pipeline nobody can compile costs the
+     * glass, and a raster, shadow, blit or compute pipeline nobody can compile costs the world. The
+     * first degrades; the second has nothing to degrade to, so it says so and draws nothing rather
+     * than encoding a command buffer the driver will reject whole.
+     *
+     * A device with no scopes is taken at its word, exactly as the blend guard takes it: refusing to
+     * draw on hardware that never said no is the worse of the two failures.
+     */
+    private watchPipelines;
+    /**
+     * Why this pass is drawing nothing, in the words the device used, or null where it is not.
+     *
+     * **Exposed because a black frame that says nothing is the bug this was reported as, twice.** A
+     * pipeline refusal arrives asynchronously, long after `createRenderer` has decided the backend
+     * can run this at all, so there is no earlier place to throw — and a scene that can read this can
+     * tell somebody what happened instead of presenting an empty picture.
+     */
+    refusedBecause(): string | null;
     private buildPipelines;
     /**
      * The groups that name `history` and `drawn`, rebuilt when the two swap.

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

@@ -445,6 +445,30 @@ export class GpuDrivenPass {
      * before the device answers, which nobody sees; the alternative is a frame that draws nothing.
      */
     blendUsable = false;
+    /**
+     * The same question about *every other* pipeline in this pass, and the reason it exists is that
+     * 4.1.3 asked it about one.
+     *
+     * **The guard above was written from a log that named `gpu-driven blend`, and the four render
+     * pipelines and eight compute pipelines beside it were left with the shape that caused the
+     * report.** Reported again from an Android handset once that fix shipped: the transparent pass
+     * now skips itself correctly, the overlay still draws and the frame counter still counts — and
+     * the world is black, which is what an invalid *opaque* pipeline looks like once the blended one
+     * has stopped taking the command buffer with it.
+     *
+     * So the whole of `buildPipelines` is built inside one pair of scopes and nothing this pass
+     * encodes runs until they come back clean. The blend pipeline pushes its own pair *inside* that
+     * region, so the two verdicts stay separate: a device that refuses only the transparent pipeline
+     * still draws everything opaque, and a device that refuses anything else turns this pass off
+     * rather than encoding against a handle the driver has already rejected.
+     *
+     * **What it gives up** is the first frames, which draw nothing while the device is still
+     * answering. **What would make it wrong** is a device that never resolves an error scope; the
+     * `popErrorScope` check below is the same concession the blend guard makes, for the same reason.
+     */
+    usable = false;
+    /** Why this pass refused itself, in the words the device used, or null while it has not. */
+    refusal = null;
     /** Builds the transparent raster's bindings, held until there is a pipeline worth binding to. */
     makeBlendGroup = null;
     blendResolvePipeline = null;
@@ -687,7 +711,18 @@ export class GpuDrivenPass {
             });
         }
         this.buildBuffers(device.device);
+        /*
+         * **Every pipeline this pass owns, inside one pair of scopes.** See `usable`: the blend
+         * pipeline pushes its own pair within this region, so its refusal stays its own and any other
+         * refusal is caught here and turns the pass off instead of reaching an encoder.
+         */
+        const scoped = typeof device.device.pushErrorScope === 'function';
+        if (scoped) {
+            device.device.pushErrorScope('validation');
+            device.device.pushErrorScope('internal');
+        }
         this.buildPipelines(device.device, device.format, device.samples);
+        this.watchPipelines(device.device, scoped);
         if (this.width > 0)
             this.buildTargets(device.device);
     }
@@ -1000,6 +1035,50 @@ export class GpuDrivenPass {
         void device.popErrorScope().then((error) => settle(error, 'internal'));
         void device.popErrorScope().then((error) => settle(error, 'validation'));
     }
+    /**
+     * Close the scopes every other pipeline was built in, and refuse the pass where one came back.
+     *
+     * **This is `watchBlendPipeline` widened to the rest of the pass**, and the reason it is separate
+     * is that the two refusals mean different things: a blend pipeline nobody can compile costs the
+     * glass, and a raster, shadow, blit or compute pipeline nobody can compile costs the world. The
+     * first degrades; the second has nothing to degrade to, so it says so and draws nothing rather
+     * than encoding a command buffer the driver will reject whole.
+     *
+     * A device with no scopes is taken at its word, exactly as the blend guard takes it: refusing to
+     * draw on hardware that never said no is the worse of the two failures.
+     */
+    watchPipelines(device, scoped) {
+        if (!scoped || typeof device.popErrorScope !== 'function') {
+            this.usable = true;
+            return;
+        }
+        let outstanding = 2;
+        const settle = (error, scope) => {
+            outstanding -= 1;
+            if (error !== null && this.refusal === null) {
+                this.refusal = error.message;
+                console.warn(`[driftengine] this device refused a gpu-driven pipeline (${scope}), so this pass draws ` +
+                    `nothing and the rest of the frame is unaffected: ${error.message}`);
+            }
+            /* Usable only once both have come back clean, which is what keeps an invalid handle out. */
+            if (outstanding > 0 || this.refusal !== null)
+                return;
+            this.usable = true;
+        };
+        void device.popErrorScope().then((error) => settle(error, 'internal'));
+        void device.popErrorScope().then((error) => settle(error, 'validation'));
+    }
+    /**
+     * Why this pass is drawing nothing, in the words the device used, or null where it is not.
+     *
+     * **Exposed because a black frame that says nothing is the bug this was reported as, twice.** A
+     * pipeline refusal arrives asynchronously, long after `createRenderer` has decided the backend
+     * can run this at all, so there is no earlier place to throw — and a scene that can read this can
+     * tell somebody what happened instead of presenting an empty picture.
+     */
+    refusedBecause() {
+        return this.refusal;
+    }
     buildPipelines(device, format, samples) {
         const compute = (label, code) => device.createComputePipeline({
             label: `gpu-driven ${label}`,
@@ -1935,6 +2014,9 @@ export class GpuDrivenPass {
     prepare(ctx) {
         if (ctx.backend !== 'webgpu')
             return;
+        /* Nothing is encoded until the device has answered for the pipelines. See `usable`. */
+        if (!this.usable)
+            return;
         const device = this.device;
         if (device === null || this.levels.length === 0)
             return;
@@ -2165,6 +2247,26 @@ export class GpuDrivenPass {
                 return;
             }
             case 'blendResolve': {
+                /*
+                 * **Skipped on the same verdict as the draw, because the draw is what clears what this
+                 * reads.** This is the whole of the reported black frame, and the line above it predicted
+                 * it: the blend pass clears reveal to one, meaning nothing has covered this pixel yet, and
+                 * says in as many words that cleared to zero "the resolve would show no scene anywhere the
+                 * pass ran, which is a black frame that looks like the blend working".
+                 *
+                 * 4.1.2 skipped the draw and took its clear with it, and left this running against textures
+                 * nothing had written — a reveal of zero over every pixel, which is exactly "fully covered".
+                 * Reported from a Galaxy S23 Ultra and then an Adreno 740, both of which refuse only
+                 * `gpu-driven blend` and both of which drew the city into a buffer this then wiped: the
+                 * page's own readout said 43 fps and 1,087 clusters drawn while the screen was black.
+                 *
+                 * There is nothing to composite when nothing was rasterised, so the honest answer is not to
+                 * composite. **What would make it wrong** is a caller that expects this pass to have run for
+                 * some other reason; nothing does, and the opaque image is already in `colourView` before
+                 * this would load it.
+                 */
+                if (!this.blendUsable)
+                    return;
                 const pass = encoder.beginRenderPass({
                     label: 'gpu-driven blend resolve',
                     colorAttachments: [
@@ -2468,6 +2570,9 @@ export class GpuDrivenPass {
     draw(ctx) {
         if (ctx.backend !== 'webgpu')
             return;
+        /* The same gate as `prepare`: an unanswered or refused pipeline set encodes nothing at all. */
+        if (!this.usable)
+            return;
         if (this.blitPipeline === null || this.blitGroup === null)
             return;
         if (ctx.outputTransform !== 0 && !this.gradeWarned) {

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

@@ -67,6 +67,10 @@ export declare class GpuPointShadowMap implements PointShadowSource {
     get far(): number;
     get near(): number;
     get sourceRadius(): number;
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX(): number;
+    get originY(): number;
+    get originZ(): number;
     get hasBaked(): boolean;
     get presence(): number;
     matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius?: number, tolerance?: number): boolean;

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

@@ -229,6 +229,16 @@ export class GpuPointShadowMap {
     get sourceRadius() {
         return this.image.sourceRadius;
     }
+    /** Where the image was rendered from, not where the light is now. See the image. */
+    get originX() {
+        return this.image.originX;
+    }
+    get originY() {
+        return this.image.originY;
+    }
+    get originZ() {
+        return this.image.originZ;
+    }
     get hasBaked() {
         return this.image.hasBaked;
     }

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

@@ -38,6 +38,7 @@ import { POINT_SHADOW_SAMPLER, PointShadowSystem, } from '../../pointShadowSyste
 import { GpuPointShadowArray, GpuPointShadowMap } from './pointShadowPass.js';
 import { createPanelBindGroup, createPanelBindGroupLayout, createPanelCorners, panelPipeline, PANEL_FRAG_FIELDS, PANEL_FRAG_SIZE, PANEL_VERTEX_COUNT, PANEL_VERT_FIELDS, PANEL_VERT_SIZE, } from './panelPass.js';
 import { createGpuTextCube, createTextBindGroup, createTextBindGroupLayout, GpuText, textPipeline, TEXT_FRAG_FIELDS, TEXT_FRAG_SIZE, TEXT_VERT_FIELDS, TEXT_VERT_SIZE, } from './textPass.js';
+import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.js';
 import { GpuSurfaceTexture } from './surfaceTexturePass.js';
 import { createSdfTextBindGroup, createSdfTextBindGroupLayout, GpuSdfText, sdfTextPipeline, SDF_TEXT_FRAG_FIELDS, SDF_TEXT_FRAG_SIZE, SDF_TEXT_VERT_FIELDS, SDF_TEXT_VERT_SIZE, } from './sdfTextPass.js';
 import { createFilmBindGroup, createFilmBindGroupLayout, filmPipeline, FILM_FRAG_FIELDS, FILM_FRAG_SIZE, FILM_VERT_FIELDS, FILM_VERT_SIZE, } from './filmPass.js';
@@ -2485,8 +2486,15 @@ export class WebGPURenderer {
         const at = (name) => TEXT_VERT_FIELDS[name]?.offset ?? 0;
         const v = this.textVerts;
         v.writeFloats(vertexSlot, at('uViewport'), [viewportWidth, viewportHeight]);
-        v.writeFloats(vertexSlot, at('uOrigin'), [originX, originY]);
-        v.writeFloat(vertexSlot, at('uCellSize'), style.cellSize);
+        /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
+           See `deviceSnappedOrigin`. */
+        v.writeFloats(vertexSlot, at('uOrigin'), [
+            deviceSnappedOrigin(originX, viewportWidth, this.surface.canvas.width),
+            deviceSnappedOrigin(originY, viewportHeight, this.surface.canvas.height),
+        ]);
+        /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
+           decision is shared with WebGL2; only this binding is per-backend. See `textLayout.ts`. */
+        v.writeFloat(vertexSlot, at('uCellSize'), deviceSnappedCellSize(style.cellSize, viewportWidth, this.surface.canvas.width));
         /* Far enough that a whole line barely converges, near enough that a turn reads as a turn. */
         v.writeFloat(vertexSlot, at('uDepth'), Math.max(viewportWidth, 600) * 1.4);
         v.writeFloat(vertexSlot, at('uReveal'), style.reveal);
@@ -6225,11 +6233,16 @@ export class WebGPURenderer {
             }
             else {
                 this.writeShadowSelection(f, i, 'uPointShadow', resolved.layers, resolved.presence);
-                this.writeShadowParams(f, 'uPointShadowFar', resolved.far);
+                /*
+                 * A `vec4` row carrying the bake origin and the far plane, so `scatterInto` rather than
+                 * `writeShadowParams` — it reads the stride out of the generated layout instead of
+                 * counting rows, which is what AGENTS.md's 2026-09-20 alignment rule asks for.
+                 */
+                scatterInto(f, this.fragment.fields['uPointShadowProjection'], resolved.projections, 4);
                 this.writeShadowParams(f, 'uPointShadowNear', resolved.near);
                 this.writeShadowParams(f, 'uPointShadowSize', resolved.sourceRadius);
                 this.writeShadowSelection(f, i, 'uLivePointShadow', resolved.liveLayers, resolved.liveWeights);
-                this.writeShadowParams(f, 'uLivePointShadowFar', resolved.liveFar);
+                scatterInto(f, this.fragment.fields['uLivePointShadowProjection'], resolved.liveProjections, 4);
                 this.writeShadowParams(f, 'uLivePointShadowNear', resolved.liveNear);
                 this.writeShadowParams(f, 'uLivePointShadowSize', resolved.liveSourceRadius);
             }

package/dist/render/depthConvention.d.ts

@@ -101,6 +101,25 @@
 export declare const REVERSED_DEPTH = true;
 /** What a scene depth attachment is cleared to: the far plane. */
 export declare const DEPTH_CLEAR: number;
+/**
+ * The same value for a backend that learned its convention at runtime rather than at compile time.
+ *
+ * **`DEPTH_CLEAR` above says what the engine wants; this says what a context got.** Reversed depth
+ * on WebGL2 needs `EXT_clip_control`, and a context not granted it runs conventional depth while
+ * the constant still reads 0. Clearing to 0 with a `LEQUAL` compare rejects every fragment in the
+ * scene — every one sits at depth >= 0 and only depth <= 0 is admitted — so the frame that reaches
+ * the screen is the colour clear and nothing else.
+ *
+ * Reported from Firefox on Linux, which exposes no `EXT_clip_control`: every consumer drew one flat
+ * colour with its interface still on top, at a healthy sixty frames a second. The depth *compare*
+ * beside it was already chosen at runtime, and that asymmetry is what made this total rather than
+ * subtle — two halves of one convention would still have drawn a picture.
+ *
+ * **Here rather than in the backend** for the 2026-08-13 rule's first clause: the decision is
+ * backend-neutral and only the binding is per-backend. It is also what lets a test hold the clear
+ * and the compare to each other, which a private field on a renderer could not.
+ */
+export declare function depthClearFor(reversed: boolean): number;
 /** The WebGPU compare for "nearer than what is there". */
 export declare const DEPTH_COMPARE: GPUCompareFunction;
 /**

package/dist/render/depthConvention.js

@@ -101,6 +101,27 @@
 export const REVERSED_DEPTH = true;
 /** What a scene depth attachment is cleared to: the far plane. */
 export const DEPTH_CLEAR = REVERSED_DEPTH ? 0 : 1;
+/**
+ * The same value for a backend that learned its convention at runtime rather than at compile time.
+ *
+ * **`DEPTH_CLEAR` above says what the engine wants; this says what a context got.** Reversed depth
+ * on WebGL2 needs `EXT_clip_control`, and a context not granted it runs conventional depth while
+ * the constant still reads 0. Clearing to 0 with a `LEQUAL` compare rejects every fragment in the
+ * scene — every one sits at depth >= 0 and only depth <= 0 is admitted — so the frame that reaches
+ * the screen is the colour clear and nothing else.
+ *
+ * Reported from Firefox on Linux, which exposes no `EXT_clip_control`: every consumer drew one flat
+ * colour with its interface still on top, at a healthy sixty frames a second. The depth *compare*
+ * beside it was already chosen at runtime, and that asymmetry is what made this total rather than
+ * subtle — two halves of one convention would still have drawn a picture.
+ *
+ * **Here rather than in the backend** for the 2026-08-13 rule's first clause: the decision is
+ * backend-neutral and only the binding is per-backend. It is also what lets a test hold the clear
+ * and the compare to each other, which a private field on a renderer could not.
+ */
+export function depthClearFor(reversed) {
+    return reversed ? 0 : 1;
+}
 /** The WebGPU compare for "nearer than what is there". */
 export const DEPTH_COMPARE = REVERSED_DEPTH ? 'greater' : 'less';
 /**

package/dist/render/livePointShadowSet.js

@@ -155,6 +155,9 @@ export class LivePointShadowSet {
         out.liveFar.fill(1);
         out.liveNear.fill(0.01);
         out.liveSourceRadius.fill(0);
+        out.liveProjections.fill(0);
+        for (let k = 0; k < out.liveLayers.length; k++)
+            out.liveProjections[k * 4 + 3] = 1;
         /*
          * Zero, then written under the owning light below. The weights used to be a straight copy of
          * this set's own two, because the arrays were addressed by live slot; they are addressed by
@@ -188,6 +191,11 @@ export class LivePointShadowSet {
             out.liveFar[shaderSlot] = map.far;
             out.liveNear[shaderSlot] = map.near;
             out.liveSourceRadius[shaderSlot] = map.sourceRadius;
+            /* Where the image was rendered from, not where the light is now. See `projections`. */
+            out.liveProjections[shaderSlot * 4] = map.originX;
+            out.liveProjections[shaderSlot * 4 + 1] = map.originY;
+            out.liveProjections[shaderSlot * 4 + 2] = map.originZ;
+            out.liveProjections[shaderSlot * 4 + 3] = map.far;
             /*
              * The handover weight *and* the image's own arrival, multiplied.
              *

package/dist/render/pointShadowBudget.js

@@ -167,13 +167,62 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
             scratch.staleOwner[slot] = lightIndex;
             scratch.staleRun[slot] = 0;
         }
-        const run = stale ? Math.min((scratch.staleRun[slot] ?? 0) + 1, CHRONIC_STALE_FRAMES) : 0;
+        /*
+         * **The run decays rather than resetting, and it climbs past the threshold before it stops.**
+         *
+         * A light that wanders on a curve is not stale on *every* frame — near the turning points of
+         * its travel it moves less in a frame than the rebake tolerance, so a run that reset to zero
+         * lost the tracking allowance there and the map dropped back to two faces a frame. The shadow
+         * then travelled smoothly through the fast part of the wander and stepped through the slow
+         * part, which is not motion and not stillness: it reads as a vibration. Reported that way,
+         * against a brazier, once the tracking allowance was in.
+         *
+         * So the run is hysteresis. It climbs to twice the threshold, which buys a light that has
+         * earned the allowance three quiet frames before it loses it, and decays one frame at a time
+         * so a light that genuinely settles stops re-baking rather than holding a budget for ever.
+         */
+        const previous = scratch.staleRun[slot] ?? 0;
+        const run = stale
+            ? Math.min(previous + 1, CHRONIC_STALE_FRAMES * 2)
+            : Math.max(previous - 1, 0);
         scratch.staleRun[slot] = run;
         scratch.chronic[slot] = run >= CHRONIC_STALE_FRAMES ? 1 : 0;
     }
     const planned = planPointShadowBakes(scratch.stale, scratch.ready, count, scratch.order, scratch.chronic);
     let faces = facesPerFrame;
     let urgentSpent = false;
+    /*
+     * **One wandering light finishes its cube in the frame it started it**, the same allowance a
+     * light with no image at all gets, and for a reason that turns out to be the same one: a map
+     * dribbled out at two faces a frame is a map nobody can sample correctly until it lands.
+     *
+     * A cold light cannot be sampled *at all* until its six faces are in, so it takes the whole
+     * cube at once. A chronically stale one can be sampled throughout and is wrong in a quieter
+     * way: `planBake` pins the origin for the whole of a resumed bake, so six faces spread over
+     * three frames means the published origin steps once every third frame. The shader shoots from
+     * that origin, so the shadow it draws steps with it — reported on a brazier as motion that was
+     * "really fast, not smooth, snappy, and unrealistic", which is a 20 Hz sample of a flame that
+     * wanders about once a second.
+     *
+     * Given the cube in one frame the origin moves every frame and the shadow travels instead.
+     *
+     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
+     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. One is the light being shaded
+     * that most recently went stale, which is the one somebody is standing next to; the rest keep
+     * dribbling under the ordinary budget, and their shadows step rather than travel. That is the
+     * right way round: a shadow you are looking at moves, and a shadow across the square does not
+     * cost the frame.
+     *
+     * It is spent *after* the cold and settling groups, because `planPointShadowBakes` orders the
+     * chronic ones last — so a light arriving in range still gets its first image ahead of a flame
+     * refining one it already has.
+     *
+     * **What would make it wrong** is a caster set heavy enough that six passes over it does not
+     * fit the frame. Measured against a game whose whole static world is about 8,500 triangles in
+     * a handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
+     * raised or this given up, and `gpuTiming` is how to tell which.
+     */
+    let trackingSpent = false;
     for (let i = 0; i < planned && faces > 0; i++) {
         const slot = scratch.order[i] ?? -1;
         /*
@@ -185,11 +234,16 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
         const map = lightIndex >= 0 ? pool.mapForLight(lightIndex) : undefined;
         if (light === undefined || map === undefined)
             continue;
-        const cold = slot < pool.sampledCount && scratch.ready[slot] === 0;
-        const budget = cold && !urgentSpent ? faceCount : faces;
-        if (cold && !urgentSpent)
+        const sampled = slot < pool.sampledCount;
+        const cold = sampled && scratch.ready[slot] === 0;
+        const urgent = cold && !urgentSpent;
+        /* A light being shaded whose map will be stale again next frame however it is served. */
+        const tracking = !cold && sampled && scratch.chronic[slot] === 1 && !trackingSpent;
+        if (urgent)
             urgentSpent = true;
-        faces -= bake(map, light, staticCasters, budget);
+        if (tracking)
+            trackingSpent = true;
+        faces -= bake(map, light, staticCasters, urgent || tracking ? faceCount : faces);
     }
     /*
      * Live maps contain movers only and are composed with the static maps in the shader. A second