@driftengine/core 4.1.2 → 4.1.4

package/CHANGELOG.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "4.1.4",
+    "date": "2026-09-21",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "A lamp casts a smooth penumbra. Twelve filter taps were asking eight questions, because the offsets were a cube flattened onto a plane and four pairs of them landed on each other.",
+        "text": "**Reported as grainy, stippled shadows in two unrelated games on this engine**, at a desktop profile with the full twelve taps. The approved repair was a rotation tile and a resolve, and underneath it was a second cause nobody had measured.\n\n**`PCF_OFFSETS` declared twelve taps and asked eight questions.** It was a cube's eight corners and six faces, carried as `vec3` from the era when a tap offset a direction by a 3D vector. Both filters have read only `.xy` since the map became octahedral, and flattening a cube's corners onto a plane makes four pairs coincide: four taps were answered twice and the closest pair sat at a distance of **zero**. The eight distinct places were all on the rim, at radius 1 or 1.414, with nothing in between — so a coverage estimate moved in steps of two twelfths as the penumbra swept a doubled pair across it, which is the size of the speckle.\n\n**A golden-angle disk of twelve distinct places replaces it**, the construction `ambientOcclusion.ts` already uses, with the radii dealt round rather than taken in spiral order: `shadowFilterTaps` is 4, 8 or 12 and the loop stops early, so in spiral order a low profile would quietly have received the four innermost taps and a third of the width it asked for. The outermost tap is 1.384 against the old 1.414, so the filter's reach does not move.\n\n**The turn and the resolve are one mechanism.** Two tap sets half a golden angle apart, chosen by the fragment's column parity, folded together after both lamp loops. The resolve cannot sit beside the taps: that loop continues on falloff and on facing and reads its trip count from a froxel, so neighbouring pixels can be shading different lights, and a derivative there is the 2026-08-07 rule's own case. After the loops the control flow has reconverged. Each pixel is shaded by the pair's twenty-four places and pays for twelve.\n\nMeasured on the mover's penumbra, mean absolute difference to the right and down neighbour: **4.563 to 2.327 on WebGPU and 4.595 to 2.372 on WebGL2**, against a floor of 0.805 with the shadow off. The area-light path is included, because it uses the same taps and stippled the same way. Cost is nothing measurable: five capture pairs on `night-court` put the before-and-after difference at most 0.08 ms against a round-to-round spread of 0.53.\n\n**The banding the turn was added to cure has not returned**, checked on the control it was reported from: with the turn deleted the post's long shadow terraces, and the shipped build is smooth with no straight edge."
+      },
+      {
+        "kind": "fixed",
+        "short": "A bitmap glyph draws strokes of one width. A cell that is a fractional number of device pixels gives one column four pixels and the next three, and nothing is ever dropped.",
+        "text": "**Reported as pixelated text across three unrelated surfaces** — a game's world label, a wordmark, and this repository's own voxel sandbox. It is not about missing pixels, which is why a hole count found none: a 5x7 face draws every stroke exactly one cell wide, so when a cell is a fractional number of device pixels the rasteriser gives one column of cells four pixels and the next three, and a face whose whole legibility is uniform strokes comes apart.\n\n**Two doors reach a fractional cell**, which is why it arrived as three unrelated faults. A caller can ask for one outright — a consumer sizing a detail line at 0.52 of a headline of 9 asks for 4.68, which needs no unusual display at all. Or a caller can ask for a whole cell that the ratio makes fractional, by laying out in CSS pixels at a device ratio of 1.25. A pixel budget that scales the drawing buffer by a square root and floors it is a third route, and a player can reach it from a settings screen.\n\nThe tell is that **cell 3.75 carries more ink than cell 4.00** — more lit pixels from a smaller cell, which is impossible if the face were merely small.\n\n**`deviceSnappedCellSize` draws the largest whole number of device pixels not larger than the one asked for**, decided in shared code with only the binding per backend. Down rather than to nearest, because a caller that fitted a line to a box measured it first: rounding up draws wider than the box, rounding down can only leave a gap.\n\n**And the grid has a phase as well as a pitch**, which the first half of this fix left alone and the reporter caught: a whole four-pixel cell starting at 10.4 puts every boundary at four tenths and splits the strokes again. `deviceSnappedOrigin` snaps that too, to nearest rather than down, because a cell is a size and an origin is a position.\n\n**What it costs**: `textWidth` is not snapped, because it is handed no viewport and so cannot know the ratio, which makes a measured width an upper bound and a centred line sit up to half a device pixel per cell off centre. And a label animating its position sub-pixel now steps by a device pixel rather than sliding. SDF text does not come through this path."
+      },
+      {
+        "kind": "fixed",
+        "short": "A device that refuses any GPU-driven pipeline loses that pass and not the frame. 4.1.3 guarded one pipeline of thirteen, and the next handset reported the half that was left.",
+        "text": "**4.1.3 was written from a log that named `gpu-driven blend`**, and it wrapped that pipeline alone. The four other render pipelines and the eight compute pipelines beside it kept the shape that caused the report, and the next device reported what was left of it: the transparent pass correctly skipping itself, the overlay still drawing, the frame counter still counting, and **the world black** — which is what an invalid opaque pipeline looks like once the blended one has stopped taking the command buffer with it.\n\n**The whole of `buildPipelines` is built inside one pair of error scopes now**, with the blend pipeline's own pair nested inside. 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 the pass off rather than encoding against a handle the driver has already rejected. Nothing this pass encodes runs until the scopes come back clean.\n\n**And a scene can say why it is black.** `refusedBecause` reports the refusal in the device's own words, and `DemoHandle.refused` carries it to a host — the same shape as the `lost` flag beside it, one cause along. A pipeline refusal arrives asynchronously, long after `createRenderer` has decided the backend can run the pass at all, so there is no earlier place to throw and nothing for a host to catch.\n\n**The fixture had to be corrected before the test meant anything.** It stubbed `popErrorScope` without `pushErrorScope`, which is a device that reports errors nobody asked it to collect. No device is that, and the guard correctly took such a device at its word and never ran — a green test over an unexercised guard."
+      },
+      {
+        "kind": "fixed",
+        "short": "The offline hierarchical-detail bake is reachable. It was tested, sized and licensed, and its only importer in the repository was its own test, so no consumer following the barrel could call it.",
+        "text": "`bake/hlod.ts` builds the proxies and impostors `docs/CAPABILITIES.md` lists as shipping. It is tested, it is sized, it carries the licence, and until now nothing outside its own test imported it — so a consumer following this engine's own rule that the barrel is the contract could read the capability map, believe the row, and find no way to call it.\n\nThe assets barrel already carries that paragraph twice, for the cluster bakers and for the object SDF. What is new is that a demo boundary test caught those two and nothing caught this one, because no scene tries to bake an impostor. **A module reached only by its own test is not shipped**, and no gate here asks.\n\nFound by censusing what three consumers could adopt and what they could not."
+      },
+      {
+        "kind": "fixed",
+        "short": "A device that refuses only the transparent pipeline draws the city again. Skipping that pass took its clear with it, and the resolve then composited an untouched target over the whole frame.",
+        "text": "**Reported from a Galaxy S23 Ultra and then an Adreno 740, and 4.1.2 caused it.** Both refuse `gpu-driven blend` with `VK_ERROR_UNKNOWN` and nothing else, and both drew the whole city and showed black: the page's own readout said 43 fps, 1,087 clusters drawn and 27,167 in the sun's map while the screen was empty.\n\n**The blend pass is what clears the two weighted-transparency targets** — accumulation to zero and reveal to one, meaning nothing has covered this pixel yet. 4.1.2 skipped that pass where the device refused its pipeline, which was right, and took the clear with it, which was not. The resolve was left running against targets nothing had written, and a reveal of zero is *fully covered*, over every pixel, so it composited the opaque image away.\n\n**The comment beside that clear had already predicted it**, in as many words: cleared to zero \"the resolve would show no scene anywhere the pass ran, which is a black frame that looks like the blend working\". It was describing the clear value, and it turned out to describe the missing clear too.\n\nThe resolve now skips on the same verdict as the draw. There is nothing to composite when nothing was rasterised, and the opaque image is already in place before the resolve would load it.\n\n**What is still not fixed is why those drivers refuse the pipeline.** Its targets are `rgba16float` and `r8unorm` under `layout: auto`, and diagnosing `VK_ERROR_UNKNOWN` needs the part that produces it. This is the containment working as intended: a refusal costs the glass it is about."
+      }
+    ]
+  },
+  {
+    "version": "4.1.3",
+    "date": "2026-09-20",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "An imported model draws as it did before 4.0.0. Decoding images with straight alpha let the bytes under a transparent texel reach the frame, and on an opaque draw nothing discards them.",
+        "text": "**Reported as a car whose interior, grille, mirrors and lamps came through as hard black and white shards, where the published build of the same game was correct.** 4.0.0 changed how a `.drft` decodes its images, from premultiplied to straight alpha.\n\n**The argument for straight alpha was measured and is still true.** `createImageBitmap` premultiplies unless told not to, the upload into a straight-alpha texture divides back out, and on a PNG holding every colour at every alpha, 98,463 of 196,608 channel values came back changed. None did with `premultiplyAlpha: none`. Every cutout and emblem was losing the colour its author padded past its edge.\n\n**What it did not measure is content.** An imported material routinely carries arbitrary bytes under its fully transparent texels, and premultiplying is what kept them out of the frame. Straight alpha let them through, and an opaque draw discards nothing, so the shader takes the colour whatever the alpha beside it says.\n\n**Isolated in the showroom on held frames**, which is the part worth keeping. A model with 41 images drew clean and two with 64 and 65 drew shards, on both backends, with the old container and the new alike, fully streamed. The count only decides how likely a model is to carry a masked texture at all. Restoring the one option drew the car correctly.\n\nSo the faithful choice per texel was the wrong choice per model. `colorSpaceConversion` is unchanged and stays off."
+      },
+      {
+        "kind": "fixed",
+        "short": "A tested material stating a zero alpha reference takes the shader default rather than discarding nothing. A grille's holes and a seat's stitching were coming through filled in.",
+        "text": "**`ksAlphaRef` of zero means the shader's own threshold, not discard nothing.** The `.kn5` reader read it literally, and the first car to set the flag set it on eleven materials with a reference of zero on every one: `int_net`, `int_stitching`, `grille_a`, `hood_labels`. A threshold of zero discards nothing, so a grille's holes and a seat's stitching were drawn solid.\n\nA material that says it is alpha tested has already said something is meant to go, so a reference of zero cannot be read literally without contradicting the flag beside it. Half, because that is the convention those shaders were authored against, and because these masks are two valued.\n\nThe comment this replaces said the path was carried on the format's word rather than on evidence. This is the evidence arriving."
+      },
+      {
+        "kind": "fixed",
+        "short": "A device that refuses the transparent pipeline now really does lose only the glass. The guard added in 4.1.2 warned correctly and did not prevent a single one of the errors it was written for.",
+        "text": "**4.1.2 had this the wrong way round, and the reporter proved it on the next run.** That version built the pipeline, bound a group against its layout, encoded the pass, and disowned the handle when the error scope came back. A scope comes back on a microtask, after all three. The log carried the new warning and then every error it was meant to prevent: `GetBindGroupLayout` on an invalid pipeline, a bind group against an invalid layout, a `SetPipeline` with it, and a refused submit.\n\n**Nothing touches the handle until the device has answered now.** The bindings are held as a closure rather than built, and run once, either where the verdict has already landed or when it does. What that costs is no transparency for the frames before the answer, which nobody sees.\n\n**A device offering no error scopes is taken at its word**, because refusing transparency forever on hardware that never said no would be the worse failure of the two."
+      }
+    ]
+  },
   {
     "version": "4.1.2",
     "date": "2026-09-20",

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/webgpu/gpuDrivenPass.d.ts

@@ -456,6 +456,46 @@ export declare class GpuDrivenPass implements PassDefinition {
     private oitAccumView;
     private oitRevealView;
     private blendPipeline;
+    /**
+     * Whether the device has actually accepted the blend pipeline.
+     *
+     * **False until it says so, and 4.1.2 had this the wrong way round.** That version built the
+     * pipeline, bound a group against its layout, encoded the pass, and disowned the handle when the
+     * error scope came back — but a scope comes back on a microtask, after all three. The reporter's
+     * next run carried the new warning *and* every error it was meant to prevent: `GetBindGroupLayout`
+     * on an invalid pipeline, a bind group against an invalid layout, a `SetPipeline` with it, and a
+     * refused submit.
+     *
+     * Nothing touches the handle until this is true. The cost is no transparency for the frames
+     * 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;
     private blendLodGroup;
     private blendCompactGroup;
@@ -625,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

@@ -431,6 +431,46 @@ export class GpuDrivenPass {
     oitAccumView = null;
     oitRevealView = null;
     blendPipeline = null;
+    /**
+     * Whether the device has actually accepted the blend pipeline.
+     *
+     * **False until it says so, and 4.1.2 had this the wrong way round.** That version built the
+     * pipeline, bound a group against its layout, encoded the pass, and disowned the handle when the
+     * error scope came back — but a scope comes back on a microtask, after all three. The reporter's
+     * next run carried the new warning *and* every error it was meant to prevent: `GetBindGroupLayout`
+     * on an invalid pipeline, a bind group against an invalid layout, a `SetPipeline` with it, and a
+     * refused submit.
+     *
+     * Nothing touches the handle until this is true. The cost is no transparency for the frames
+     * 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;
     blendLodGroup = null;
     blendCompactGroup = null;
@@ -671,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);
     }
@@ -953,16 +1004,80 @@ export class GpuDrivenPass {
      * this came from was five errors that were all the same one.
      */
     watchBlendPipeline(device) {
-        const refused = (error, scope) => {
-            if (error === null || this.blendPipeline === null)
+        /*
+         * **A device with no error scopes is taken at its word.** Nothing can be asked of it, and
+         * refusing transparency forever on a device that never said no would be a worse failure than
+         * the one this guards: a frame that quietly loses its glass on hardware that could draw it.
+         */
+        if (typeof device.popErrorScope !== 'function') {
+            this.blendUsable = true;
+            if (this.makeBlendGroup !== null)
+                this.blendRasterGroup = this.makeBlendGroup();
+            return;
+        }
+        let outstanding = 2;
+        const settle = (error, scope) => {
+            outstanding -= 1;
+            if (error !== null && this.blendPipeline !== null) {
+                this.blendPipeline = null;
+                this.blendRasterGroup = null;
+                this.makeBlendGroup = null;
+                console.warn(`[driftengine] this device refused the gpu-driven blend pipeline (${scope}), so the ` +
+                    `transparent pass is off and everything opaque still draws: ${error.message}`);
+            }
+            /* Usable only once both scopes have come back clean, and only then is anything bound. */
+            if (outstanding > 0 || this.blendPipeline === null)
                 return;
-            this.blendPipeline = null;
-            this.blendRasterGroup = null;
-            console.warn(`[driftengine] this device refused the gpu-driven blend pipeline (${scope}), so the ` +
-                `transparent pass is off and everything opaque still draws: ${error.message}`);
+            this.blendUsable = true;
+            if (this.makeBlendGroup !== null)
+                this.blendRasterGroup = this.makeBlendGroup();
         };
-        void device.popErrorScope().then((error) => refused(error, 'internal'));
-        void device.popErrorScope().then((error) => refused(error, 'validation'));
+        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({
@@ -1083,8 +1198,11 @@ export class GpuDrivenPass {
          * backends and as validation on others, and this is exactly the case where guessing which
          * costs the whole frame.
          */
-        device.pushErrorScope('validation');
-        device.pushErrorScope('internal');
+        /* Only where the device offers them: see `watchBlendPipeline` for the case where it does not. */
+        if (typeof device.pushErrorScope === 'function') {
+            device.pushErrorScope('validation');
+            device.pushErrorScope('internal');
+        }
         this.blendPipeline = device.createRenderPipeline({
             label: 'gpu-driven blend',
             layout: 'auto',
@@ -1627,41 +1745,44 @@ export class GpuDrivenPass {
         });
         /* Everything the transparent raster reads: the same scene, the same frame, its own list. */
         /*
-         * Nothing to bind against where the device refused the pipeline, and the resolve below still
-         * wants building — it is a different pipeline and this one's absence is not its problem. An
-         * early return here would have taken it with us, which is the same shape of mistake as the
-         * cascade this guard exists to stop.
+         * Held rather than built, because whether the pipeline is usable is not known yet: the error
+         * scopes settle on a microtask and this runs synchronously. `watchBlendPipeline` runs it once
+         * the device has answered, and never if the answer was no.
          */
-        this.blendRasterGroup =
-            this.blendPipeline === null
-                ? null
-                : device.createBindGroup({
-                    layout: this.blendPipeline.getBindGroupLayout(0),
-                    entries: [
-                        { binding: 0, resource: { buffer: this.viewProjBuffer } },
-                        { binding: 1, resource: { buffer: this.blendList } },
-                        { binding: 2, resource: { buffer: this.clusterMeta } },
-                        { binding: 3, resource: { buffer: this.indices } },
-                        { binding: 4, resource: { buffer: this.vertices } },
-                        { binding: 5, resource: { buffer: this.transformBuffer } },
-                        { binding: 6, resource: { buffer: this.materialOf } },
-                        { binding: 7, resource: { buffer: this.materialTable } },
-                        { binding: 8, resource: { buffer: this.frameBuffer } },
-                        {
-                            binding: 9,
-                            resource: this.environmentView ?? this.emptyEnvironmentView,
-                        },
-                        {
-                            binding: 10,
-                            resource: this.environmentSampler ?? this.emptySampler,
-                        },
-                        { binding: 11, resource: this.latentsView },
-                        { binding: 12, resource: this.latentClamp },
-                        { binding: 13, resource: this.latentRepeat },
-                        { binding: 14, resource: { buffer: this.decodeNodes } },
-                        { binding: 15, resource: { buffer: this.decodeWeights } },
-                    ],
-                });
+        this.makeBlendGroup = () => device.createBindGroup({
+            layout: this.blendPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: this.viewProjBuffer } },
+                { binding: 1, resource: { buffer: this.blendList } },
+                { binding: 2, resource: { buffer: this.clusterMeta } },
+                { binding: 3, resource: { buffer: this.indices } },
+                { binding: 4, resource: { buffer: this.vertices } },
+                { binding: 5, resource: { buffer: this.transformBuffer } },
+                { binding: 6, resource: { buffer: this.materialOf } },
+                { binding: 7, resource: { buffer: this.materialTable } },
+                { binding: 8, resource: { buffer: this.frameBuffer } },
+                {
+                    binding: 9,
+                    resource: this.environmentView ?? this.emptyEnvironmentView,
+                },
+                {
+                    binding: 10,
+                    resource: this.environmentSampler ?? this.emptySampler,
+                },
+                { binding: 11, resource: this.latentsView },
+                { binding: 12, resource: this.latentClamp },
+                { binding: 13, resource: this.latentRepeat },
+                { binding: 14, resource: { buffer: this.decodeNodes } },
+                { binding: 15, resource: { buffer: this.decodeWeights } },
+            ],
+        });
+        /*
+         * And build it now where the device has already answered, which is the ordinary case: the
+         * verdict lands before this runs on a device with no error scopes, and after it on one that
+         * has them. Whichever order, exactly one of the two places builds the group.
+         */
+        if (this.blendUsable)
+            this.blendRasterGroup = this.makeBlendGroup();
         this.blendResolveGroup = device.createBindGroup({
             layout: this.blendResolvePipeline.getBindGroupLayout(0),
             entries: [
@@ -1893,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;
@@ -2086,7 +2210,7 @@ export class GpuDrivenPass {
                  * Everything opaque has already been drawn by the time this runs, so what is lost is the
                  * glass and not the city. See `watchBlendPipeline`.
                  */
-                if (this.blendPipeline === null || this.blendRasterGroup === null)
+                if (!this.blendUsable || this.blendPipeline === null || this.blendRasterGroup === null)
                     return;
                 const pass = encoder.beginRenderPass({
                     label: 'gpu-driven blend draw',
@@ -2123,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: [
@@ -2426,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/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);