@driftengine/core 4.1.3 → 4.1.4

package/dist/render/textLayout.d.ts

@@ -48,6 +48,64 @@ export declare const DEFAULT_TEXT_STYLE: TextStyle;
 /** Width of a string in pixels at a given cell size, without laying it out. */
 export declare function textWidthPx(text: string, cellSize: number): number;
 export declare function textHeightPx(cellSize: number): number;
+/**
+ * The cell size to draw at, so every cell of a bitmap glyph covers whole device pixels.
+ *
+ * **A 5x7 face draws every stroke exactly one cell wide, so a fractional cell is not a slightly
+ * softer glyph — it is a glyph whose strokes are different widths.** The rasteriser gives one
+ * column of cells four pixels and the next three, and a face carrying its legibility entirely in
+ * uniform strokes comes apart. Reported three times as text "eaten away" in a checkerboard while
+ * larger text in the same frame stayed solid, which is the size dependence this explains: a whole
+ * cell is uniform and a fractional one is not, and nothing about it is a dropped pixel.
+ *
+ * Two doors reach a fractional cell, which is why it was reported as unrelated faults. A caller
+ * asks for one outright, sizing a second line at a fraction of its headline; or asks for a whole
+ * one that the device ratio makes fractional, a 3-pixel cell at a 1.25 ratio being 3.75 on the
+ * grid. `viewportWidth` is whatever units the caller lays out in — CSS pixels for an overlay
+ * sized from `cssWidth`, device pixels for one sized from the canvas — and `bufferWidth` is the
+ * drawing buffer, so the ratio between them is exactly what turns one into the other.
+ *
+ * **What it gives up is the asked size.** The cell drawn is the largest whole number of device
+ * pixels that is not larger than the one asked for, so a string is drawn up to one device pixel
+ * per cell narrower than `textWidthPx` measures it. Down rather than to nearest, because a caller
+ * that fitted a line to a box measured it first: rounding up would draw a line wider than the box
+ * it was fitted to, and rounding down can only leave a gap.
+ *
+ * **`textWidthPx` and `RendererApi.textWidth` are deliberately left unsnapped**, and that is the
+ * cost rather than an oversight. Neither is handed a viewport, so neither can know whether the
+ * caller lays out in CSS pixels or device ones — and this ratio is exactly that question. A width
+ * is therefore an upper bound on what is drawn: a centred line sits up to half the shortfall off
+ * centre, at most half a device pixel per cell. Handing the measurement a viewport would fix it
+ * and is a change to the public surface rather than to a patch.
+ *
+ * **What would make it wrong** is a face whose strokes are not cell-aligned — an SDF atlas, where
+ * the glyph is a distance field and a fractional size is exactly what it is built to serve.
+ * `sdfTextLayout.ts` is that path and does not come through here.
+ */
+export declare function deviceSnappedCellSize(cellSize: number, viewportWidth: number, bufferWidth: number): number;
+/**
+ * The same grid's **phase**, which is the other half of the same defect.
+ *
+ * **A whole pitch on a fractional origin still draws strokes of two widths.** Snapping the cell to
+ * four device pixels puts the boundaries four apart, and starting them at 10.4 puts every boundary
+ * at `.4` — so each stroke covers three whole pixels and two halves, and the rasteriser resolves
+ * that the same ragged way it resolved a fractional cell. The pitch decides how far apart the
+ * boundaries are; this decides where the first one is, and a face of uniform strokes needs both.
+ *
+ * It was found the way the first half was: the cell snap shipped, and the reporter said the text was
+ * still wrong.
+ *
+ * **To nearest rather than down**, which is the opposite of the cell above and for the opposite
+ * reason: this is a position, not a size. Moving a label up to half a device pixel is the smallest
+ * change that puts its grid on the display's, while flooring would shift every label the same way
+ * and bias a centred one off centre.
+ *
+ * **What would make it wrong** is a caller animating an origin sub-pixel on purpose — a label that
+ * slides smoothly now steps by a device pixel. For a face whose strokes are one pixel wide that is
+ * the trade this whole function exists to make, and `sdfTextLayout.ts`, which does not come through
+ * here, is the path for anything that wants the other answer.
+ */
+export declare function deviceSnappedOrigin(value: number, viewportWidth: number, bufferWidth: number): number;
 export declare class TextLayout {
     /** Reused every upload; text changes far too often to allocate per change. */
     readonly cells: Float32Array<ArrayBuffer>;

package/dist/render/textLayout.js

@@ -38,6 +38,89 @@ export function textWidthPx(text, cellSize) {
 export function textHeightPx(cellSize) {
     return GLYPH_HEIGHT * cellSize;
 }
+/**
+ * The cell size to draw at, so every cell of a bitmap glyph covers whole device pixels.
+ *
+ * **A 5x7 face draws every stroke exactly one cell wide, so a fractional cell is not a slightly
+ * softer glyph — it is a glyph whose strokes are different widths.** The rasteriser gives one
+ * column of cells four pixels and the next three, and a face carrying its legibility entirely in
+ * uniform strokes comes apart. Reported three times as text "eaten away" in a checkerboard while
+ * larger text in the same frame stayed solid, which is the size dependence this explains: a whole
+ * cell is uniform and a fractional one is not, and nothing about it is a dropped pixel.
+ *
+ * Two doors reach a fractional cell, which is why it was reported as unrelated faults. A caller
+ * asks for one outright, sizing a second line at a fraction of its headline; or asks for a whole
+ * one that the device ratio makes fractional, a 3-pixel cell at a 1.25 ratio being 3.75 on the
+ * grid. `viewportWidth` is whatever units the caller lays out in — CSS pixels for an overlay
+ * sized from `cssWidth`, device pixels for one sized from the canvas — and `bufferWidth` is the
+ * drawing buffer, so the ratio between them is exactly what turns one into the other.
+ *
+ * **What it gives up is the asked size.** The cell drawn is the largest whole number of device
+ * pixels that is not larger than the one asked for, so a string is drawn up to one device pixel
+ * per cell narrower than `textWidthPx` measures it. Down rather than to nearest, because a caller
+ * that fitted a line to a box measured it first: rounding up would draw a line wider than the box
+ * it was fitted to, and rounding down can only leave a gap.
+ *
+ * **`textWidthPx` and `RendererApi.textWidth` are deliberately left unsnapped**, and that is the
+ * cost rather than an oversight. Neither is handed a viewport, so neither can know whether the
+ * caller lays out in CSS pixels or device ones — and this ratio is exactly that question. A width
+ * is therefore an upper bound on what is drawn: a centred line sits up to half the shortfall off
+ * centre, at most half a device pixel per cell. Handing the measurement a viewport would fix it
+ * and is a change to the public surface rather than to a patch.
+ *
+ * **What would make it wrong** is a face whose strokes are not cell-aligned — an SDF atlas, where
+ * the glyph is a distance field and a fractional size is exactly what it is built to serve.
+ * `sdfTextLayout.ts` is that path and does not come through here.
+ */
+export function deviceSnappedCellSize(cellSize, viewportWidth, bufferWidth) {
+    const ratio = bufferWidth / viewportWidth;
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        return cellSize;
+    const device = cellSize * ratio;
+    if (!Number.isFinite(device))
+        return cellSize;
+    /*
+     * The tolerance is against float error rather than a fudge: a ratio of 1 turns an asked 4 into
+     * 3.9999999999999996 often enough, and flooring that would shrink every whole cell on every
+     * ordinary display by a pixel — the change doing most harm where there was nothing to fix.
+     */
+    const whole = Math.floor(device + 1e-6);
+    /* Below one device pixel there is no whole size to snap to, and flooring would draw nothing. */
+    if (whole < 1)
+        return cellSize;
+    return whole / ratio;
+}
+/**
+ * The same grid's **phase**, which is the other half of the same defect.
+ *
+ * **A whole pitch on a fractional origin still draws strokes of two widths.** Snapping the cell to
+ * four device pixels puts the boundaries four apart, and starting them at 10.4 puts every boundary
+ * at `.4` — so each stroke covers three whole pixels and two halves, and the rasteriser resolves
+ * that the same ragged way it resolved a fractional cell. The pitch decides how far apart the
+ * boundaries are; this decides where the first one is, and a face of uniform strokes needs both.
+ *
+ * It was found the way the first half was: the cell snap shipped, and the reporter said the text was
+ * still wrong.
+ *
+ * **To nearest rather than down**, which is the opposite of the cell above and for the opposite
+ * reason: this is a position, not a size. Moving a label up to half a device pixel is the smallest
+ * change that puts its grid on the display's, while flooring would shift every label the same way
+ * and bias a centred one off centre.
+ *
+ * **What would make it wrong** is a caller animating an origin sub-pixel on purpose — a label that
+ * slides smoothly now steps by a device pixel. For a face whose strokes are one pixel wide that is
+ * the trade this whole function exists to make, and `sdfTextLayout.ts`, which does not come through
+ * here, is the path for anything that wants the other answer.
+ */
+export function deviceSnappedOrigin(value, viewportWidth, bufferWidth) {
+    const ratio = bufferWidth / viewportWidth;
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        return value;
+    const device = value * ratio;
+    if (!Number.isFinite(device))
+        return value;
+    return Math.round(device) / ratio;
+}
 export class TextLayout {
     /** Reused every upload; text changes far too often to allocate per change. */
     cells = new Float32Array(MAX_CELLS * 2);

package/dist/render/textRenderer.js

@@ -1,4 +1,4 @@
-import { MAX_CELLS, TEXT_CUBE, TextLayout } from './textLayout.js';
+import { MAX_CELLS, TEXT_CUBE, TextLayout, deviceSnappedCellSize, deviceSnappedOrigin, } from './textLayout.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { TEXT_FRAG, TEXT_VERT } from './shaders/text.js';
 /**
@@ -100,8 +100,12 @@ export class TextRenderer {
         gl.enable(gl.BLEND);
         gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         setVec2(gl, this.uniforms['uViewport'], viewportWidth, viewportHeight);
-        setVec2(gl, this.uniforms['uOrigin'], originX, originY);
-        setFloat(gl, this.uniforms['uCellSize'], style.cellSize);
+        /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
+           See `deviceSnappedOrigin`. */
+        setVec2(gl, this.uniforms['uOrigin'], deviceSnappedOrigin(originX, viewportWidth, gl.drawingBufferWidth), deviceSnappedOrigin(originY, viewportHeight, gl.drawingBufferHeight));
+        /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
+           decision is shared with WebGPU; only this binding is per-backend. See `textLayout.ts`. */
+        setFloat(gl, this.uniforms['uCellSize'], deviceSnappedCellSize(style.cellSize, viewportWidth, gl.drawingBufferWidth));
         // Far enough that a whole line barely converges, near enough that a rotating character
         // reads as turning rather than shearing.
         setFloat(gl, this.uniforms['uDepth'], Math.max(viewportWidth, 600) * 1.4);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.1.3",
-    "@driftengine/physics": "4.1.3",
+    "@driftengine/drft": "4.1.4",
+    "@driftengine/physics": "4.1.4",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.1.3",
-    "@driftengine/network": "4.1.3",
-    "@driftengine/texture": "4.1.3"
+    "@driftengine/nav": "4.1.4",
+    "@driftengine/network": "4.1.4",
+    "@driftengine/texture": "4.1.4"
   }
 }

package/src/index.ts

@@ -231,8 +231,18 @@ export type {
  * 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,

package/src/render/backend/webgpu/gpuDrivenPass.ts

@@ -737,6 +737,30 @@ export class GpuDrivenPass implements PassDefinition {
    * before the device answers, which nobody sees; the alternative is a frame that draws nothing.
    */
   private 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.
+   */
+  private usable = false;
+  /** Why this pass refused itself, in the words the device used, or null while it has not. */
+  private refusal: string | null = null;
   /** Builds the transparent raster's bindings, held until there is a pipeline worth binding to. */
   private makeBlendGroup: (() => GPUBindGroup) | null = null;
   private blendResolvePipeline: GPURenderPipeline | null = null;
@@ -997,7 +1021,18 @@ export class GpuDrivenPass implements PassDefinition {
       });
     }
     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);
   }
 
@@ -1359,6 +1394,53 @@ export class GpuDrivenPass implements PassDefinition {
     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.
+   */
+  private watchPipelines(device: GPUDevice, scoped: boolean): void {
+    if (!scoped || typeof device.popErrorScope !== 'function') {
+      this.usable = true;
+      return;
+    }
+    let outstanding = 2;
+    const settle = (error: GPUError | null, scope: string): void => {
+      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(): string | null {
+    return this.refusal;
+  }
+
   private buildPipelines(device: GPUDevice, format: GPUTextureFormat, samples: number): void {
     const compute = (label: string, code: string): GPUComputePipeline =>
       device.createComputePipeline({
@@ -2420,6 +2502,8 @@ export class GpuDrivenPass implements PassDefinition {
 
   prepare(ctx: PrepareContext): void {
     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;
     /* Before `writeFrame`, which reads what this took, and before the groups it may invalidate. */
@@ -2658,6 +2742,25 @@ export class GpuDrivenPass implements PassDefinition {
         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: [
@@ -2988,6 +3091,8 @@ export class GpuDrivenPass implements PassDefinition {
 
   draw(ctx: PassContext): void {
     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) {
       this.gradeWarned = true;

package/src/render/backend/webgpu/renderer.ts

@@ -150,6 +150,7 @@ import {
   type GpuTextCube,
 } from './textPass.ts';
 import type { TextStyle } from '../../textLayout.ts';
+import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.ts';
 import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 import {
   createSdfTextBindGroup,
@@ -3178,8 +3179,19 @@ export class WebGPURenderer implements RendererApi {
     const at = (name: string): number => 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);

package/src/render/shaders/flat/main.ts

@@ -793,6 +793,27 @@ export const MAIN_GLSL = `void main() {
      */
     float lightShade = 1.0;
 
+    /*
+     * **The lamps' light twice: once as it arrives, once as their shadows leave it.**
+     *
+     * Every point light's contribution used to go straight into \`lit\`. It is accumulated here
+     * instead, in two sums that differ only by the shadow term, so that after the loop there is
+     * a single number per channel saying how much of the lamps' light survived — and *that* is
+     * the thing the resolve below can average across a pair of pixels without touching albedo,
+     * a highlight, or anything else the frame has in it.
+     *
+     * **The two sums are not an approximation.** \`lampOpen\` multiplied by
+     * \`lampShadowed / lampOpen\` is \`lampShadowed\`, per channel, whatever mixture of lamps
+     * and shadows produced it. With the resolve switched off this is arithmetically the line it
+     * replaces; a lamp that is shadowed and a lamp beside it that is not keep their own shares.
+     *
+     * **What it costs** is two vector adds per light and six floats of live state. **What would
+     * make it wrong** is a term wanting to sit between the lamps and \`lit\` — a per-light
+     * tone map, say — because these two are summed before anything can get between them.
+     */
+    vec3 lampOpen = vec3(0.0);
+    vec3 lampShadowed = vec3(0.0);
+
     /*
      * Which froxel this fragment is in.
      *
@@ -1192,7 +1213,13 @@ export const MAIN_GLSL = `void main() {
        *
        * At metal 0 this is one multiply by 1.0 away from the expression it replaces.
        */
-      lit += albedo * lightColor * ndl * shape * shaded * lightWeight * (1.0 - metal);
+      /*
+       * Held back from \`lit\` until the loop is over, so the shadow can be resolved across a
+       * pair of pixels first. See the block below the loop; nothing else about this term moved.
+       */
+      vec3 lampDiffuse = albedo * lightColor * ndl * shape * lightWeight * (1.0 - metal);
+      lampOpen += lampDiffuse;
+      lampShadowed += lampDiffuse * shaded;
 
       /*
        * A lamp reflected in a polished surface, which point lights could not do at all.
@@ -1222,8 +1249,12 @@ export const MAIN_GLSL = `void main() {
           vec3(1.0),
           pow(1.0 - max(dot(toEyeLamp, lampHalfway), 0.0), 5.0) * metal
         );
-        lit += lightColor * sphereLobe(max(dot(n, lampHalfway), 0.0), surfaceRoughness, lightSourceRadius, dist)
-          * lampSpec * shape * shaded * lightWeight;
+        /* Held back with the diffuse half, and shadowed by the same term it always was. */
+        vec3 lampHighlight =
+          lightColor * sphereLobe(max(dot(n, lampHalfway), 0.0), surfaceRoughness, lightSourceRadius, dist)
+          * lampSpec * shape * lightWeight;
+        lampOpen += lampHighlight;
+        lampShadowed += lampHighlight * shaded;
       }
       /*
        * The most any light in range shadows this point, for the emissive term below —
@@ -1371,7 +1402,10 @@ export const MAIN_GLSL = `void main() {
       }
 #endif
 
-      lit += albedo * uAreaLightColor[a] * form * (1.0 - metal) * areaOccl;
+      /* Held back with the point lamps', and shadowed by the same term it always was. */
+      vec3 areaDiffuse = albedo * uAreaLightColor[a] * form * (1.0 - metal);
+      lampOpen += areaDiffuse;
+      lampShadowed += areaDiffuse * areaOccl;
 
       if (vSpecular > 0.0 || metal > 0.0) {
         /*
@@ -1396,11 +1430,63 @@ export const MAIN_GLSL = `void main() {
         if (coverage > 0.0) {
           vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), surfaceRoughness);
           vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);
-          lit += areaSpec * uAreaLightColor[a] * coverage * areaOccl;
+          vec3 areaHighlight = areaSpec * uAreaLightColor[a] * coverage;
+          lampOpen += areaHighlight;
+          lampShadowed += areaHighlight * areaOccl;
         }
       }
     }
 
+    /*
+     * **The other half of the shadow filter: the two pixels of a column pair, folded together.**
+     *
+     * \`pointShadow\` turns its twelve taps by half a golden angle on every other column, so a
+     * pair of neighbouring pixels holds twenty-four places on the disk between them and neither
+     * holds more than twelve. This is where the pair becomes one filter. \`dFdx\` of a value is
+     * the difference across the pair, and half of it, signed by which of the two this pixel is,
+     * is exactly the average of both — so each pixel ends up shaded by all twenty-four taps
+     * while paying for twelve. It is the pairing \`ambientOcclusion.ts\` describes between its
+     * rotation tile and its blur, at the smallest size that needs no second pass.
+     *
+     * **After both lamp loops rather than beside the taps, and that is why this block exists at
+     * all.** A derivative is only defined where every pixel of the quad reaches it, and neither
+     * loop above reaches anything uniformly: the point loop \`continue\`s on falloff and on
+     * facing, and in the clustered arm its trip count is read from a froxel, so two neighbouring
+     * pixels can be shading different lights with a froxel boundary drawn across the screen
+     * where they stop agreeing. A \`dFdx\` in there is the 2026-08-07 rule's own case, and it
+     * would also invite a compiler to flatten the loop. Measured, too: with the turn taken from
+     * a per-fragment hash instead of the column, the same resolve made the penumbra *worse*
+     * than no resolve at all — 3.14 against 3.00 — because the hardware here answers a coarse
+     * derivative and the second row of a quad then borrows the first row's difference. The
+     * column tile is what makes that borrowing correct, so the two halves are one mechanism.
+     *
+     * Both lamp kinds are in the sums, because a rectangle's shadow is filtered by the same
+     * twelve taps and stippled the same way.
+     *
+     * **Clamped, and the clamp is a guard rather than tidying.** A fragment killed by the
+     * cutout or the clip plane above leaves its lane without a value for its neighbour to
+     * difference against, and GLSL ES says nothing about what comes back. What could reach the
+     * frame is a shadow term outside 0..1 on the pixel beside a cutout hole, which the clamp
+     * turns into a pixel that is merely fully lit or fully shadowed. **What would make this
+     * wrong** is a consumer whose cutout edges are most of the frame — dense foliage drawn as
+     * one alpha-tested sheet — where the honest answer is to resolve in a pass of its own,
+     * against a shadow term written to a target.
+     *
+     * The floor under the divisor costs nothing and answers the case where no lamp reached this
+     * pixel at all: both sums are zero there, so the ratio is zero and multiplying it back by
+     * the floor adds nothing.
+     */
+    vec3 lampOpenFloor = max(lampOpen, vec3(1e-6));
+    vec3 lampShade = lampShadowed / lampOpenFloor;
+#if POINT_SHADOWS
+    lampShade = clamp(
+      lampShade - dFdx(lampShade) * (float(int(gl_FragCoord.x) & 1) - 0.5),
+      0.0,
+      1.0
+    );
+#endif
+    lit += lampOpenFloor * lampShade;
+
     /*
      * Self-illuminated geometry, dimmed where a lamp's shadow crosses it.
      *

package/src/render/shaders/flat/pointShadow.ts

@@ -116,8 +116,8 @@ export const POINTSHADOW_GLSL = `float pointShadow(
   float strength = 1.0 - penumbra * penumbra;
 
   /*
-   * Taps are placed on a disk *perpendicular to the light ray*, rotated per
-   * fragment.
+   * Taps are placed on a disk *perpendicular to the light ray*, turned by half a golden
+   * angle on every other column of pixels.
    *
    * Offsetting the ray by fixed 3D vectors was the earlier approach and it has
    * two faults that only show on a wide filter. The offsets are not
@@ -127,8 +127,33 @@ export const POINTSHADOW_GLSL = `float pointShadow(
    * tap pattern — reported, on a brazier behind a rank of columns, as strange
    * straight lines across the light pool.
    *
-   * A per-fragment rotation turns that banding into a fine dither, which the eye
-   * reads as smooth — the standard cure, and it costs one hash.
+   * **The cure for that was a per-fragment hash, and it is what made the penumbra
+   * stipple.** Twelve taps are a coarse estimate of how much of the emitter this point can
+   * see; turning them by an unrelated angle at every pixel makes each pixel's error
+   * independent of its neighbour's, which is the definition of noise. Something has to
+   * average that back out, and this engine's lit pass is the last thing to touch the frame —
+   * there is no blur and no temporal resolve behind it, so the noise reached the screen. Two
+   * games reported the same coarse cross-hatch across a light pool.
+   *
+   * **So the turn comes from a two-pixel tile instead, and the pair is averaged afterwards.**
+   * A pixel's own x parity picks one of two tap sets half a golden angle apart, and
+   * \`main\` folds the pair together once the light loop is over — see the resolve there. The
+   * pair's twenty-four taps are the filter; each pixel pays for twelve of them.
+   *
+   * **A *column* pair rather than a 2x2 square, and that was measured rather than assumed.**
+   * Four turns on a square tile, resolved with both derivatives, came back at 3.88 against this
+   * pair's 2.46 on the same build — because the second derivative hands the lower row of a quad
+   * the upper row's difference on hardware that answers a coarse derivative, and with four turns
+   * that is the wrong difference. Two turns keyed on the column alone make it the right one,
+   * which is why the tile's shape and the resolve are one decision rather than two.
+   *
+   * **Neither half works alone**, which is the same pairing \`ambientOcclusion.ts\` describes
+   * between its rotation tile and its blur. Measured on \`demo/dev/pointshadow.html\` at
+   * \`?exposure=6\`, as mean absolute luminance difference to the right and down neighbour over
+   * the mover's penumbra, on WebGL2: **4.60** for the per-fragment hash this replaces, **2.88**
+   * for this tile with no resolve — and a one-pixel vertical comb in the picture, which is the
+   * tile itself on screen — against **2.37** for the pair resolved. A frame with the shadow
+   * switched off measures 0.81, and WebGPU answers 4.56 and 2.33 for the same two builds.
    *
    * **Unchanged by the move to an octahedral map, and that is the point.** The offsets are
    * angular perturbations of a direction, so every tap is still a direction and octEncode is
@@ -139,17 +164,19 @@ export const POINTSHADOW_GLSL = `float pointShadow(
   vec3 up = abs(fwd.y) < 0.9 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);
   vec3 tu = normalize(cross(up, fwd));
   vec3 tv = cross(fwd, tu);
-  // Interleaved gradient noise: cheap, and stable enough per pixel that the
-  // dither does not crawl while the camera moves.
-  float angle = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))))
-    * 6.28318530718;
+  /*
+   * Integer arithmetic, because this is a lattice: a shader compiler is free to implement
+   * \`mod(x, 2.0)\` as a multiply by a reciprocal, and a GPU here answers 3 for \`3.0 % 3.0\`.
+   * \`gl_FragCoord.x\` is the pixel's centre, so truncating it is the pixel's own column.
+   */
+  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;
   float ca = cos(angle);
   float sa = sin(angle);
 
   float lit = 0.0;
   for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
     if (i >= uShadowFilterTaps) break;
-    vec2 disk = PCF_OFFSETS[i].xy;
+    vec2 disk = PCF_OFFSETS[i];
     vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);
     // Perpendicular to the ray, and *not* scaled by its length: the offsets are
     // an angular perturbation of a direction, which is what the encoding takes.
@@ -267,20 +294,19 @@ float areaShadow(
   float strength = 1.0 - penumbra * penumbra;
 
   /*
-   * Rotated per fragment inside the unit disk *before* the ellipse maps it, so the dither that
-   * breaks up twelve aligned taps survives the anisotropy. Interleaved gradient noise, one hash;
-   * without it a wide filter bands along the tap pattern — reported on a brazier behind a rank of
-   * columns as straight lines across the light pool.
+   * Turned inside the unit disk *before* the ellipse maps it, so the half-turn that separates
+   * the two halves of a pixel pair survives the anisotropy. The same two-pixel tile the round
+   * filter uses and for the same reasons — see \`pointShadow\`, which carries the measurement;
+   * a rectangle's shadow stippled exactly as a lamp's did, because it is the same twelve taps.
    */
-  float angle = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))))
-    * 6.28318530718;
+  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;
   float ca = cos(angle);
   float sa = sin(angle);
 
   float lit = 0.0;
   for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
     if (i >= uShadowFilterTaps) break;
-    vec2 disk = PCF_OFFSETS[i].xy;
+    vec2 disk = PCF_OFFSETS[i];
     vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);
     vec3 sampleDir = toFrag + alongX * (turned.x * widthX) + alongY * (turned.y * widthY);
     float stored = textureLod(maps, vec3(octEncode(sampleDir), layer), 0.0).r;