@driftengine/core 4.1.2 → 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.2",
+  "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.2",
-    "@driftengine/physics": "4.1.2",
+    "@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.2",
-    "@driftengine/network": "4.1.2",
-    "@driftengine/texture": "4.1.2"
+    "@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

@@ -723,6 +723,46 @@ export class GpuDrivenPass implements PassDefinition {
   private oitAccumView: GPUTextureView | null = null;
   private oitRevealView: GPUTextureView | null = null;
   private blendPipeline: GPURenderPipeline | null = 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.
+   */
+  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;
   private blendLodGroup: GPUBindGroup | null = null;
   private blendCompactGroup: GPUBindGroup | null = null;
@@ -981,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);
   }
 
@@ -1311,17 +1362,83 @@ export class GpuDrivenPass implements PassDefinition {
    * this came from was five errors that were all the same one.
    */
   private watchBlendPipeline(device: GPUDevice): void {
-    const refused = (error: GPUError | null, scope: string): void => {
-      if (error === null || 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}`,
-      );
+    /*
+     * **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: GPUError | null, scope: string): void => {
+      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.blendUsable = true;
+      if (this.makeBlendGroup !== null) this.blendRasterGroup = this.makeBlendGroup();
+    };
+    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.
+   */
+  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) => 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'));
+  }
+
+  /**
+   * 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 {
@@ -1449,8 +1566,11 @@ export class GpuDrivenPass implements PassDefinition {
      * 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',
@@ -2059,41 +2179,45 @@ export class GpuDrivenPass implements PassDefinition {
 
     /* 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 as GPUBuffer } },
-              { binding: 1, resource: { buffer: this.blendList as GPUBuffer } },
-              { binding: 2, resource: { buffer: this.clusterMeta as GPUBuffer } },
-              { binding: 3, resource: { buffer: this.indices as GPUBuffer } },
-              { binding: 4, resource: { buffer: this.vertices as GPUBuffer } },
-              { binding: 5, resource: { buffer: this.transformBuffer as GPUBuffer } },
-              { binding: 6, resource: { buffer: this.materialOf as GPUBuffer } },
-              { binding: 7, resource: { buffer: this.materialTable as GPUBuffer } },
-              { binding: 8, resource: { buffer: this.frameBuffer as GPUBuffer } },
-              {
-                binding: 9,
-                resource: this.environmentView ?? (this.emptyEnvironmentView as GPUTextureView),
-              },
-              {
-                binding: 10,
-                resource: this.environmentSampler ?? (this.emptySampler as GPUSampler),
-              },
-              { binding: 11, resource: this.latentsView as GPUTextureView },
-              { binding: 12, resource: this.latentClamp as GPUSampler },
-              { binding: 13, resource: this.latentRepeat as GPUSampler },
-              { binding: 14, resource: { buffer: this.decodeNodes as GPUBuffer } },
-              { binding: 15, resource: { buffer: this.decodeWeights as GPUBuffer } },
-            ],
-          });
+    this.makeBlendGroup = (): GPUBindGroup =>
+      device.createBindGroup({
+        layout: (this.blendPipeline as GPURenderPipeline).getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: { buffer: this.viewProjBuffer as GPUBuffer } },
+          { binding: 1, resource: { buffer: this.blendList as GPUBuffer } },
+          { binding: 2, resource: { buffer: this.clusterMeta as GPUBuffer } },
+          { binding: 3, resource: { buffer: this.indices as GPUBuffer } },
+          { binding: 4, resource: { buffer: this.vertices as GPUBuffer } },
+          { binding: 5, resource: { buffer: this.transformBuffer as GPUBuffer } },
+          { binding: 6, resource: { buffer: this.materialOf as GPUBuffer } },
+          { binding: 7, resource: { buffer: this.materialTable as GPUBuffer } },
+          { binding: 8, resource: { buffer: this.frameBuffer as GPUBuffer } },
+          {
+            binding: 9,
+            resource: this.environmentView ?? (this.emptyEnvironmentView as GPUTextureView),
+          },
+          {
+            binding: 10,
+            resource: this.environmentSampler ?? (this.emptySampler as GPUSampler),
+          },
+          { binding: 11, resource: this.latentsView as GPUTextureView },
+          { binding: 12, resource: this.latentClamp as GPUSampler },
+          { binding: 13, resource: this.latentRepeat as GPUSampler },
+          { binding: 14, resource: { buffer: this.decodeNodes as GPUBuffer } },
+          { binding: 15, resource: { buffer: this.decodeWeights as GPUBuffer } },
+        ],
+      });
+
+    /*
+     * 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 as GPURenderPipeline).getBindGroupLayout(0),
       entries: [
@@ -2378,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. */
@@ -2579,7 +2705,8 @@ export class GpuDrivenPass implements PassDefinition {
          * 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) return;
+        if (!this.blendUsable || this.blendPipeline === null || this.blendRasterGroup === null)
+          return;
         const pass = encoder.beginRenderPass({
           label: 'gpu-driven blend draw',
           colorAttachments: [
@@ -2615,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: [
@@ -2945,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);