@driftengine/core 4.1.3 → 4.1.5

package/dist/render/shaders/sky.d.ts

@@ -1,10 +1,14 @@
 /**
- * Procedural gradient sky drawn as a single attribute-less fullscreen triangle.
- * Ray direction is reconstructed per-fragment from the inverse view-projection,
- * so the sky is correct under any camera. Drawn last at the far plane, so early-z wins —
- * and the far plane is 0 under reversed depth and 1 otherwise, which is why the value is
- * interpolated rather than written. A sky that says 1.0 in a reversed engine is drawn at the
- * *near* plane and covers the world; measured, that was 743,669 changed pixels of 921,600.
+ * The engine's own convention, which is what WebGPU always gets and what the WGSL is generated
+ * from. `scripts/wgsl.ts` reads this constant, so it stays a constant.
  */
 export declare const SKY_VERT: string;
+/**
+ * The same shader for a context that may not have been granted reversed depth.
+ *
+ * WebGL2 compiles GLSL directly and is the only backend that can run either way, so it asks for
+ * the one matching what it got. WebGPU never calls this: it uses the generated WGSL, where the far
+ * plane is reversed by construction.
+ */
+export declare function skyVertFor(reversed: boolean): string;
 export declare const SKY_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vNdc;\n\nuniform mat4 uInvViewProj;\nuniform vec3 uCameraPos;\nuniform vec3 uTopColor;\nuniform vec3 uHorizonColor;\nuniform vec3 uDeepColor;\nuniform vec3 uSunDir;\nuniform vec3 uSunColor;\nuniform float uSunDiscExponent;\nuniform vec3 uMoonDir;\nuniform vec3 uMoonColor;\nuniform float uMoonAngularRadius;\nuniform float uMoonPhase;\nuniform float uNightFactor;\nuniform vec2 uCloudOffset;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFactor;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = hash21(i);\n  float b = hash21(i + vec2(1.0, 0.0));\n  float c = hash21(i + vec2(0.0, 1.0));\n  float d = hash21(i + vec2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\n/** Three octaves is the ceiling \u2014 drop to two before cutting anything else. */\nfloat fbm(vec2 p) {\n  float v = valueNoise(p) * 0.5;\n  v += valueNoise(p * 2.03) * 0.3;\n  v += valueNoise(p * 4.01) * 0.2;\n  return v;\n}\n\nvoid main() {\n  vec4 world = uInvViewProj * vec4(vNdc, 1.0, 1.0);\n  vec3 dir = normalize(world.xyz / world.w - uCameraPos);\n\n  float t = dir.y;\n  vec3 col = t >= 0.0\n    ? mix(uHorizonColor, uTopColor, pow(min(t, 1.0), 0.55))\n    : mix(uHorizonColor, uDeepColor, min(-t * 1.8, 1.0));\n\n  // Celestial bodies belong to the sky, not to the void underneath. Seeing the\n  // sun below the horizon made the world read as unbounded in every direction;\n  // fading them out at the horizon leaves the deep reading as depth instead.\n  float aboveHorizon = smoothstep(-0.04, 0.06, dir.y);\n\n  /*\n   * Sunset.\n   *\n   * Low sunlight crosses far more atmosphere than high sunlight, and that path\n   * scatters the blue out of it \u2014 which is why the sun reddens as it drops and\n   * why the glow around it spreads into a band rather than staying a disc. Both\n   * effects peak right at the horizon and are gone within a few degrees of it,\n   * so they are driven by the sun's own elevation rather than by the clock.\n   *\n   * TWO EDGES, BECAUSE A SUNSET ENDS. This shipped with only the upper one, so every\n   * sun below the horizon read as maximum sunset and stayed there all the way to\n   * straight down \u2014 and a sun direction of (0, -1, 0) is what a night world writes to\n   * mean \"there is no sun in this sky\". A consumer measured the result on a black\n   * sun: 87% more red in the sky than the same frame with the sun pointing up, a warm\n   * band over a third of the picture in an arctic snowfield, and the world's own\n   * blue-grey horizon arriving with its channel order reversed. Four night worlds were\n   * not started over it, and this repository's own storm sea shipped it. The lower\n   * edge is where astronomical twilight ends, near -0.31, so the term now fades out\n   * over the same range the sky it models does.\n   *\n   * What it gives up: the glow is a function of the sun's elevation and nothing else,\n   * so a caller cannot place one where its own sun is not. That is deliberate \u2014 a knob\n   * here would let a world disagree with itself \u2014 but it is also what makes this wrong\n   * for a body that is not our sun in our atmosphere. A world lit by something that\n   * scatters differently needs its own term, not a wider edge here.\n   *\n   * Written ascending-and-inverted rather than as a descending smoothstep, whose\n   * result GLSL ES leaves undefined when edge0 >= edge1. Every implementation seen so\n   * far computes the ramp anybody would expect, which is why the descending form\n   * survived this long, but the spec does not owe us that.\n   */\n  float sunset = (1.0 - smoothstep(-0.03, 0.30, uSunDir.y)) *\n    smoothstep(-0.35, -0.05, uSunDir.y);\n  vec3 ember = vec3(1.0, 0.36, 0.13);\n\n  float s = max(dot(dir, uSunDir), 0.0);\n  // The disc itself reddens; the last sliver above the horizon is nearly blood\n  // orange, which is the moment the whole effect is remembered for.\n  vec3 discColor = mix(uSunColor, uSunColor * ember, sunset * 0.85);\n  col += discColor * (\n    pow(s, uSunDiscExponent) * 1.2 +\n    pow(s, max(uSunDiscExponent / 75.0, 1.0)) * 0.12\n  ) * aboveHorizon;\n\n  /*\n   * The band. Brightest toward the sun's bearing and hugging the horizon,\n   * falling off both with angle around the compass and with height \u2014 a sunset\n   * is a direction, not a uniform warm wash, and washing the whole dome is what\n   * makes a fake one look like a colour filter.\n   */\n  vec2 sunBearing = normalize(uSunDir.xz + vec2(1e-5));\n  vec2 viewBearing = normalize(dir.xz + vec2(1e-5));\n  float toward = max(dot(viewBearing, sunBearing), 0.0);\n  /*\n   * Measured from the horizon, and falling three times faster below it than above.\n   *\n   * This was abs(dir.y), which is symmetric, so the band was mirrored twenty-seven\n   * degrees down into the deep \u2014 visible in any world whose ground does not cover\n   * the lower half of the frame, and captured in the -Y face of every environment\n   * probe, where it tinted reflections warm. Nothing in the sky mirrors a sunset\n   * below the horizon; what is down there is ground, and the ground is drawn by\n   * somebody else.\n   *\n   * Not gated by aboveHorizon like the sun disc and the moon are: that factor is\n   * only 0.4 at a dir.y of zero, which is exactly where this term is brightest, so\n   * multiplying by it would cut the band's core to a third and change every sunset\n   * to fix a night. Falling faster below instead leaves everything at or above the\n   * horizon bit-for-bit as it was, and the horizon line itself unbroken. What it\n   * gives up: a camera under the world, or above a planet seen from outside its\n   * atmosphere, sees the glow end sooner than the geometry does.\n   */\n  float fromHorizon = dir.y >= 0.0 ? dir.y : -dir.y * 3.0;\n  float band = pow(1.0 - min(fromHorizon * 2.2, 1.0), 2.6);\n  col += ember * sunset * band * (0.18 + 0.75 * pow(toward, 2.2));\n\n  /*\n   * Belt of Venus: the sky opposite a setting sun takes a cool pink-violet from\n   * light already reddened on its way past. Subtle, but its absence is why an\n   * artificial sunset feels like it is only happening on one side.\n   */\n  float away = max(-dot(viewBearing, sunBearing), 0.0);\n  col += vec3(0.42, 0.28, 0.45) * sunset * band * away * 0.22;\n\n  /*\n   * Moon: a shaded procedural sphere-disc, not one dot subtracted from another.\n   * The local sphere normal gives a curved terminator and limb; lunar phase\n   * supplies the light direction around that sphere. Low-frequency noise adds\n   * maria without a texture file, while a faint earthshine keeps the dark limb\n   * just legible instead of cutting a mathematically black hole in the sky.\n   */\n  vec3 moonReference = abs(uMoonDir.y) < 0.98\n    ? vec3(0.0, 1.0, 0.0)\n    : vec3(1.0, 0.0, 0.0);\n  vec3 moonRight = normalize(cross(moonReference, uMoonDir));\n  vec3 moonUp = cross(uMoonDir, moonRight);\n  float moonRadius = clamp(uMoonAngularRadius, 0.001, 0.5);\n  vec2 moonUv = vec2(dot(dir, moonRight), dot(dir, moonUp)) / moonRadius;\n  float moonRadiusSq = dot(moonUv, moonUv);\n  float moonFacing = step(0.0, dot(dir, uMoonDir));\n  float moonDisc = (1.0 - smoothstep(0.90, 1.0, moonRadiusSq)) * moonFacing;\n  if (moonDisc > 0.0) {\n    float sphereZ = sqrt(max(1.0 - moonRadiusSq, 0.0));\n    vec3 surfaceNormal = normalize(vec3(moonUv, sphereZ));\n    float phaseAngle = uMoonPhase * 6.28318530718;\n    vec3 phaseLight = vec3(sin(phaseAngle), 0.0, -cos(phaseAngle));\n    float phaseShade = max(dot(surfaceNormal, phaseLight), 0.0);\n    float maria = valueNoise(moonUv * 3.2 + vec2(4.7, 9.1)) * 0.68 +\n      valueNoise(moonUv * 9.3 - vec2(7.4, 2.6)) * 0.32;\n    float albedo = mix(0.56, 1.02, maria);\n    float limb = mix(0.72, 1.0, sphereZ);\n    float earthshine = 0.035;\n    float lunarLight = earthshine + (1.0 - earthshine) * phaseShade;\n    col += uMoonColor * albedo * limb * lunarLight * moonDisc *\n      1.35 * uNightFactor * aboveHorizon;\n  }\n  float phaseIllumination = 0.5 - cos(uMoonPhase * 6.28318530718) * 0.5;\n  float moonHalo = (1.0 - smoothstep(1.0, 3.0, length(moonUv))) * moonFacing;\n  col += uMoonColor * moonHalo * 0.08 * phaseIllumination *\n    uNightFactor * aboveHorizon;\n\n  if (dir.y > 0.0) {\n    // Stars. Stereographic projection: unlike dir.xz/dir.y it stays finite and\n    // near-uniform all the way to the horizon, so stars don't smear into grain.\n    // Each cell holds one jittered *point* \u2014 lighting the whole cell would draw\n    // square blocks, which is what \"random pixels\" looks like.\n    if (uNightFactor > 0.0) {\n      vec2 p = dir.xz / (1.0 + dir.y) * 26.0;\n      vec2 cell = floor(p);\n      float h = hash21(cell);\n      if (h > 0.93) {\n        vec2 jitter = vec2(hash21(cell + 17.3), hash21(cell + 41.7));\n        float d = length(fract(p) - jitter);\n        float star = smoothstep(0.10, 0.0, d) * (0.4 + h * 0.6);\n        // Fade out near the horizon, where haze would swallow them anyway.\n        col += vec3(0.86, 0.91, 1.0) * star * uNightFactor * smoothstep(0.03, 0.3, dir.y);\n      }\n    }\n\n    // Clouds: banded value noise on a layer above the camera, carried by the\n    // world's wind \u2014 the same signal the smoke and the grass answer to, so the\n    // largest moving thing in frame agrees with the smallest.\n    // The floor on dir.y bounds the perspective stretch near the horizon.\n    if (dir.y > 0.02) {\n      vec2 uv = dir.xz / max(dir.y, 0.16) * 0.09 + uCloudOffset * 0.012;\n      float band = smoothstep(0.46, 0.60, fbm(uv));\n      float fade = smoothstep(0.02, 0.30, dir.y);\n      vec3 cloudCol = mix(uHorizonColor, vec3(1.0), 0.45) * mix(1.0, 0.32, uNightFactor);\n      col = mix(col, cloudCol, band * fade * 0.8);\n    }\n  }\n\n  // There is no outdoor sky inside a water column. Retain a little vertical\n  // gradient so the surface remains legible above and depth reads darker\n  // below, while celestial bodies and clouds disappear with the same smooth\n  // surface transition used by the geometry passes.\n  float waterLight = mix(0.62, 1.08, clamp(dir.y * 0.5 + 0.5, 0.0, 1.0));\n  col = mix(col, uUnderwaterColor * waterLight, uUnderwaterFactor);\n\n  outColor = vec4(col, 1.0);\n}\n";

package/dist/render/shaders/sky.js

@@ -7,7 +7,24 @@ import { glslFarDepth } from '../depthConvention.js';
  * interpolated rather than written. A sky that says 1.0 in a reversed engine is drawn at the
  * *near* plane and covers the world; measured, that was 743,669 changed pixels of 921,600.
  */
-export const SKY_VERT = `#version 300 es
+/**
+ * The source, as a function of which way depth actually runs.
+ *
+ * **Because on WebGL2 that is a runtime fact and this file is imported once.** Reversed depth there
+ * needs `EXT_clip_control`; a context that is not granted it runs conventional depth, and the
+ * renderer has a `reversedDepth` field saying so precisely because the two can disagree. This
+ * template used to bake `glslFarDepth()` at import, which reads the compile-time `REVERSED_DEPTH` —
+ * so on such a context the sky was written at `0.0` while the depth test ran conventionally, where
+ * `0.0` is the middle of the range rather than the far plane. The sky then beat everything in the
+ * far half of the scene.
+ *
+ * **Reported from Firefox on Linux, which exposes no `EXT_clip_control`**: the voxel sandbox drew
+ * only sky, the gilded chamber a single orange frame, and a consumer's world one flat colour with
+ * its interface still on top. Three symptoms, one cause, and the docstring above already named the
+ * mechanism in the other direction.
+ */
+function skySource(farDepth) {
+    return `#version 300 es
 const vec2 POS[3] = vec2[3](vec2(-1., -1.), vec2(3., -1.), vec2(-1., 3.));
 
 out vec2 vNdc;
@@ -15,9 +32,25 @@ out vec2 vNdc;
 void main() {
   vNdc = POS[gl_VertexID];
   /* The far plane, whichever way depth runs: see glslFarDepth. */
-  gl_Position = vec4(vNdc, ${glslFarDepth()}, 1.0);
+  gl_Position = vec4(vNdc, ${farDepth}, 1.0);
 }
 `;
+}
+/**
+ * The engine's own convention, which is what WebGPU always gets and what the WGSL is generated
+ * from. `scripts/wgsl.ts` reads this constant, so it stays a constant.
+ */
+export const SKY_VERT = skySource(glslFarDepth());
+/**
+ * The same shader for a context that may not have been granted reversed depth.
+ *
+ * WebGL2 compiles GLSL directly and is the only backend that can run either way, so it asks for
+ * the one matching what it got. WebGPU never calls this: it uses the generated WGSL, where the far
+ * plane is reversed by construction.
+ */
+export function skyVertFor(reversed) {
+    return reversed ? SKY_VERT : skySource('1.0');
+}
 export const SKY_FRAG = `#version 300 es
 precision highp float;
 

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.5",
   "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.5",
+    "@driftengine/physics": "4.1.5",
     "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.5",
+    "@driftengine/network": "4.1.5",
+    "@driftengine/texture": "4.1.5"
   }
 }

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/webgl2/renderer.ts

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

package/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/pointShadowPass.ts

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

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);
@@ -7708,7 +7720,12 @@ export class WebGPURenderer implements RendererApi {
         this.clearShadowSelection(f, i, 'uLivePointShadowLayer', 'uLivePointShadowWeight');
       } else {
         this.writeShadowSelection(f, i, 'uPointShadow', resolved.layers, resolved.presence);
-        this.writeShadowParams(f, 'uPointShadowFar', resolved.far);
+        /*
+         * A `vec4` row carrying the bake origin and the far plane, so `scatterInto` rather than
+         * `writeShadowParams` — it reads the stride out of the generated layout instead of
+         * counting rows, which is what AGENTS.md's 2026-09-20 alignment rule asks for.
+         */
+        scatterInto(f, this.fragment.fields['uPointShadowProjection'], resolved.projections, 4);
         this.writeShadowParams(f, 'uPointShadowNear', resolved.near);
         this.writeShadowParams(f, 'uPointShadowSize', resolved.sourceRadius);
         this.writeShadowSelection(
@@ -7718,7 +7735,12 @@ export class WebGPURenderer implements RendererApi {
           resolved.liveLayers,
           resolved.liveWeights,
         );
-        this.writeShadowParams(f, 'uLivePointShadowFar', resolved.liveFar);
+        scatterInto(
+          f,
+          this.fragment.fields['uLivePointShadowProjection'],
+          resolved.liveProjections,
+          4,
+        );
         this.writeShadowParams(f, 'uLivePointShadowNear', resolved.liveNear);
         this.writeShadowParams(f, 'uLivePointShadowSize', resolved.liveSourceRadius);
       }