@driftengine/core 4.2.1 → 4.4.0

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

@@ -110,18 +110,18 @@ export function createScatterBindGroupLayout(device) {
         label: 'scatter.layout',
         entries: [
             /*
-             * **The vertex block is per draw and the fragment block is not.**
+             * **Both blocks are per draw.**
              *
              * The vertex block carries the gust and the trample field, and both arrive as arguments
              * to `drawScatter` — so a scene bending its grass by one press field and its canopy by
              * another gets whichever was written last for both, from a single buffer. That is not
              * hypothetical elsewhere: the plume pass had exactly this and drew a flame bent by the
-             * smoke's wind response. The demo that exercises this today happens to pass both
-             * batches the same wind and no trample, which is luck rather than a guarantee.
+             * smoke's wind response.
              *
-             * The fragment block holds the camera, the sun, the point lights and the medium, which
-             * are settled per pass rather than per batch. It stops being safe the day something
-             * per-batch is added to it, and that is what would make this a ring too.
+             * The fragment block holds the camera, the sun, the point lights and the medium. It was one
+             * buffer on the argument that those are settled per pass, and a pass is not an encoder: a
+             * probe records six passes in one, a mirror shares the frame's, and queue writes land before
+             * either runs. So every pass drew its blades from the last camera, and it is a ring too.
              */
             {
                 binding: VERT_BINDING,
@@ -131,7 +131,7 @@ export function createScatterBindGroupLayout(device) {
             {
                 binding: FRAG_BINDING,
                 visibility: VISIBILITY_FRAGMENT,
-                buffer: { type: 'uniform', minBindingSize: SCATTER_FRAG_SIZE },
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SCATTER_FRAG_SIZE },
             },
         ],
     });

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -20,4 +20,4 @@
  * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
  * implementations of one decision is why it exists at all.
  */
-export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 5u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 16u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/** Three vec4s a light, in exactly the record order `buildLightClusters` writes. */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = lights[light * LIGHT_TEXELS];\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = lights[light * LIGHT_TEXELS].w;\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/** Three vec4s a light, in exactly the record order `buildLightClusters` writes. */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = lights[light * LIGHT_TEXELS];\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = lights[light * LIGHT_TEXELS].w;\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

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

@@ -53,6 +53,10 @@ export declare class SkinPaletteRing {
      * has just done — including for anything drawn after the previous `endFrame`.
      */
     reset(): void;
+    /** Where the ring stands, to hand back to `rewind`. See `UniformRing.rewind` for when it is safe. */
+    mark(): number;
+    /** Give back every slot taken since `mark`, once the commands reading them are submitted. */
+    rewind(mark: number): void;
     /**
      * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
      *

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

@@ -58,6 +58,15 @@ export class SkinPaletteRing {
     reset() {
         this.used = 0;
     }
+    /** Where the ring stands, to hand back to `rewind`. See `UniformRing.rewind` for when it is safe. */
+    mark() {
+        return this.used;
+    }
+    /** Give back every slot taken since `mark`, once the commands reading them are submitted. */
+    rewind(mark) {
+        if (mark < this.used)
+            this.used = mark;
+    }
     /**
      * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
      *

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

@@ -21,7 +21,11 @@ export function createSkyBindGroupLayout(device) {
             {
                 binding: SKY_BINDING,
                 visibility: VISIBILITY_FRAGMENT,
-                buffer: { type: 'uniform', minBindingSize: SKY_UNIFORM_SIZE },
+                /*
+                 * A dynamic offset, because a frame draws more than one sky — a probe's six faces, a mirror
+                 * and the view — and one buffer rewritten between them hands every draw the last write.
+                 */
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SKY_UNIFORM_SIZE },
             },
         ],
     });

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

@@ -40,6 +40,11 @@ export declare class UniformRing {
     private ints;
     private capacity;
     private used;
+    /**
+     * The byte below which the device already holds what the staging does: the end of the last
+     * flush, lowered by any write under it since. See `flush`.
+     */
+    private clean;
     /**
      * `label` names the buffer on the device, and it is not decoration.
      *
@@ -78,6 +83,20 @@ export declare class UniformRing {
     get count(): number;
     /** Start a frame. Slots are reused; nothing is freed. */
     reset(): void;
+    /** Where the ring stands, to hand back to `rewind`. */
+    mark(): number;
+    /**
+     * Give back every slot taken since `mark`, for a caller that has already submitted the commands
+     * reading them.
+     *
+     * **Safe because the queue is ordered, and only then.** A `writeBuffer` issued after a submit
+     * cannot reach the commands in it, so slots a submitted encoder read may be rewritten by the next
+     * one. A slot taken by an encoder not yet submitted may not be: every draw pointing at it would
+     * read whatever overwrote it, which is the defect this class exists to prevent. What uses it is
+     * work that submits encoders of its own mid-frame — a probe bake — so the frame's rings are not
+     * spent by something the frame never draws.
+     */
+    rewind(mark: number): void;
     /**
      * Take the next slot and return its byte offset, or null when the ring is full.
      *
@@ -127,7 +146,18 @@ export declare class UniformRing {
      * `Int32Array.set` from an `Int32Array` is an exact copy of every bit, whatever the bits mean.
      */
     writeBlock(slot: number, block: Int32Array): void;
-    /** Upload every slot taken this frame, in one write. */
+    /**
+     * Upload every slot taken this frame that the device does not already hold, in one write.
+     *
+     * **From the watermark, not from zero, because a frame flushes more than once.** Every submit in
+     * the middle of a frame flushes first, and a probe bake submits per face: sending the whole used
+     * range each time sent a courtyard's first slots two hundred times over, 2.3 GB in a two-second
+     * grid bake, measured. Queue writes are ordered, so bytes already sent and not written since are
+     * on the device for every command after them, and resending them changed nothing.
+     *
+     * What it gives up is one compare per write. What would make it wrong is a write that reached the
+     * staging without passing a method that lowers `clean` — which is why the staging stays private.
+     */
     flush(): void;
     dispose(): void;
 }

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

@@ -54,6 +54,11 @@ export class UniformRing {
     ints;
     capacity;
     used = 0;
+    /**
+     * The byte below which the device already holds what the staging does: the end of the last
+     * flush, lowered by any write under it since. See `flush`.
+     */
+    clean = 0;
     /**
      * `label` names the buffer on the device, and it is not decoration.
      *
@@ -112,6 +117,7 @@ export class UniformRing {
             return false;
         this.buffer.destroy();
         this.capacity = slots;
+        this.clean = 0;
         this.staging = new ArrayBuffer(bytes);
         this.floats = new Float32Array(this.staging);
         this.ints = new Int32Array(this.staging);
@@ -129,6 +135,28 @@ export class UniformRing {
     /** Start a frame. Slots are reused; nothing is freed. */
     reset() {
         this.used = 0;
+        this.clean = 0;
+    }
+    /** Where the ring stands, to hand back to `rewind`. */
+    mark() {
+        return this.used;
+    }
+    /**
+     * Give back every slot taken since `mark`, for a caller that has already submitted the commands
+     * reading them.
+     *
+     * **Safe because the queue is ordered, and only then.** A `writeBuffer` issued after a submit
+     * cannot reach the commands in it, so slots a submitted encoder read may be rewritten by the next
+     * one. A slot taken by an encoder not yet submitted may not be: every draw pointing at it would
+     * read whatever overwrote it, which is the defect this class exists to prevent. What uses it is
+     * work that submits encoders of its own mid-frame — a probe bake — so the frame's rings are not
+     * spent by something the frame never draws.
+     */
+    rewind(mark) {
+        if (mark < this.used)
+            this.used = mark;
+        if (this.used * this.slotSize < this.clean)
+            this.clean = this.used * this.slotSize;
     }
     /**
      * Take the next slot and return its byte offset, or null when the ring is full.
@@ -164,6 +192,8 @@ export class UniformRing {
     }
     /** Write floats into a slot, at a byte offset within it. */
     writeFloats(slot, byteOffset, values) {
+        if (slot < this.clean)
+            this.clean = slot;
         this.floats.set(values, (slot + byteOffset) / 4);
     }
     /**
@@ -175,10 +205,14 @@ export class UniformRing {
      * buffer being reused.
      */
     writeFloat(slot, byteOffset, value) {
+        if (slot < this.clean)
+            this.clean = slot;
         this.floats[(slot + byteOffset) / 4] = value;
     }
     /** Write one integer into a slot. Separate because a `Float32Array` cannot hold an `i32`. */
     writeInt(slot, byteOffset, value) {
+        if (slot < this.clean)
+            this.clean = slot;
         this.ints[(slot + byteOffset) / 4] = value;
     }
     /**
@@ -194,13 +228,29 @@ export class UniformRing {
      * `Int32Array.set` from an `Int32Array` is an exact copy of every bit, whatever the bits mean.
      */
     writeBlock(slot, block) {
+        if (slot < this.clean)
+            this.clean = slot;
         this.ints.set(block, slot / 4);
     }
-    /** Upload every slot taken this frame, in one write. */
+    /**
+     * Upload every slot taken this frame that the device does not already hold, in one write.
+     *
+     * **From the watermark, not from zero, because a frame flushes more than once.** Every submit in
+     * the middle of a frame flushes first, and a probe bake submits per face: sending the whole used
+     * range each time sent a courtyard's first slots two hundred times over, 2.3 GB in a two-second
+     * grid bake, measured. Queue writes are ordered, so bytes already sent and not written since are
+     * on the device for every command after them, and resending them changed nothing.
+     *
+     * What it gives up is one compare per write. What would make it wrong is a write that reached the
+     * staging without passing a method that lowers `clean` — which is why the staging stays private.
+     */
     flush() {
-        if (this.used === 0)
+        const end = this.used * this.slotSize;
+        if (end <= this.clean)
             return;
-        this.device.queue.writeBuffer(this.buffer, 0, this.staging, 0, this.used * this.slotSize);
+        const from = this.clean;
+        this.device.queue.writeBuffer(this.buffer, from, this.staging, from, end - from);
+        this.clean = end;
     }
     dispose() {
         this.buffer.destroy();

package/dist/render/bloomChain.d.ts

@@ -45,6 +45,12 @@ export declare const BLOOM_FILTER_RADIUS_UV = 0.005;
  * an exposure with no curve to be exposed into — where everything is switched on, nothing is
  * wrong, and nothing happens.
  */
+/**
+ * A threshold a frame asked for through `setBloom`, made safe: at least a thousandth of a scene
+ * unit, because zero blooms the whole frame including what is meant to be dark, and a
+ * non-number would reach the shader as one. Decided here so both backends answer the same.
+ */
+export declare function bloomThresholdOf(threshold: number): number;
 export declare function bloomProfileWarning(quality: {
     readonly bloom: number;
     readonly screenEffects: boolean;

package/dist/render/bloomChain.js

@@ -45,6 +45,14 @@ export const BLOOM_FILTER_RADIUS_UV = 0.005;
  * an exposure with no curve to be exposed into — where everything is switched on, nothing is
  * wrong, and nothing happens.
  */
+/**
+ * A threshold a frame asked for through `setBloom`, made safe: at least a thousandth of a scene
+ * unit, because zero blooms the whole frame including what is meant to be dark, and a
+ * non-number would reach the shader as one. Decided here so both backends answer the same.
+ */
+export function bloomThresholdOf(threshold) {
+    return Number.isFinite(threshold) ? Math.max(threshold, 1e-3) : 1e-3;
+}
 export function bloomProfileWarning(quality) {
     if (quality.bloom <= 0)
         return null;

package/dist/render/clusteredLights.d.ts

@@ -21,26 +21,34 @@ export declare const CLUSTER_Y = 9;
 export declare const CLUSTER_Z = 24;
 export declare const CLUSTER_COUNT: number;
 /**
- * Texels a cluster occupies: one for its count, seven holding four light indices each.
+ * Texels a cluster occupies: one for its count, nineteen holding four light indices each.
  *
  * **Fixed rather than packed, and that is what removes the atomics.** One invocation owns one
  * cluster and writes only its own run, so nothing is appended to a shared list, there is no
  * counter to increment atomically and no compaction pass. That is also what lets the GPU binner
  * write through a *write-only* storage texture, which is all core WGSL gives.
  */
-export declare const CLUSTER_TEXELS = 5;
+export declare const CLUSTER_TEXELS = 20;
 /**
- * How many lights one cluster can hold. Four index texels at four indices each.
+ * How many lights one cluster can hold: nineteen index texels at four indices each, 76.
  *
- * **Sixteen because that is `MAX_POINT_LIGHTS`, and the equality is the point.** The light loop's
- * bound has to be a constant and there is only one loop, so a larger cap here would raise it for
- * the fixed path too — a scene that never asks for froxels would carry a loop bound of 28 where it
- * carries 16 today, which on the driver that faulted under the full shader is precisely the sort
- * of change nobody would attribute to clustering. Equal bounds mean the fixed path is untouched.
+ * **Sixteen until a candlelit interior drew its froxels as rectangles.** The cap was pinned to
+ * `MAX_POINT_LIGHTS` so the one light loop kept one bound. Then a courtyard of candles, lanterns
+ * and braziers asked 461 of its 3,456 froxels for more than sixteen, and up to fifty. A full froxel
+ * keeps its nearest and drops the rest, and its neighbour keeps a different set, so the step
+ * between them drew as hard-edged, screen-aligned rectangles on every vault, on both backends.
+ *
+ * Seventy-six because it is the next cap the table's shape allows above what was measured: a run
+ * must divide the 320-texel row, and the two regions must end on one. What it costs is the table,
+ * 292 KB to 1.1 MB, and the loop's bound. The bound is the clustered arm's alone in effect: the
+ * fixed arm still leaves at its own count and never passes `MAX_LIGHTS`, so a consumer that does
+ * not cluster iterates what it did. What would make 76 wrong is content that asks more of one
+ * froxel, and the answer then is the next cap rather than a softer overflow: any overflow rule
+ * draws the cluster's edge.
  *
  * **It is not the old limit wearing a new hat.** Sixteen was a budget for the *whole scene*, chosen
- * by distance with a contention band because somebody always had to be last. Sixteen per froxel is
- * a different sixteen in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
+ * by distance with a contention band because somebody always had to be last. This is a different
+ * set in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
  */
 export declare const MAX_LIGHTS_PER_CLUSTER: number;
 /**
@@ -149,7 +157,7 @@ export declare const LIGHT_REGION_TEXELS: number;
  * beginning of a row.
  */
 export declare const TABLE_WIDTH = 320;
-/** Rows: three of light records and 54 of cluster runs. 292 KB of `RGBA32UI`, allocated once. */
+/** Rows: five of light records and 216 of cluster runs. 1.1 MB of `RGBA32UI`, allocated once. */
 export declare const TABLE_HEIGHT: number;
 /** The table, as the `Uint32Array` both a texture upload and a readback comparison want. */
 export declare function createClusterTable(): Uint32Array;

package/dist/render/clusteredLights.js

@@ -21,26 +21,34 @@ export const CLUSTER_Y = 9;
 export const CLUSTER_Z = 24;
 export const CLUSTER_COUNT = CLUSTER_X * CLUSTER_Y * CLUSTER_Z;
 /**
- * Texels a cluster occupies: one for its count, seven holding four light indices each.
+ * Texels a cluster occupies: one for its count, nineteen holding four light indices each.
  *
  * **Fixed rather than packed, and that is what removes the atomics.** One invocation owns one
  * cluster and writes only its own run, so nothing is appended to a shared list, there is no
  * counter to increment atomically and no compaction pass. That is also what lets the GPU binner
  * write through a *write-only* storage texture, which is all core WGSL gives.
  */
-export const CLUSTER_TEXELS = 5;
+export const CLUSTER_TEXELS = 20;
 /**
- * How many lights one cluster can hold. Four index texels at four indices each.
+ * How many lights one cluster can hold: nineteen index texels at four indices each, 76.
  *
- * **Sixteen because that is `MAX_POINT_LIGHTS`, and the equality is the point.** The light loop's
- * bound has to be a constant and there is only one loop, so a larger cap here would raise it for
- * the fixed path too — a scene that never asks for froxels would carry a loop bound of 28 where it
- * carries 16 today, which on the driver that faulted under the full shader is precisely the sort
- * of change nobody would attribute to clustering. Equal bounds mean the fixed path is untouched.
+ * **Sixteen until a candlelit interior drew its froxels as rectangles.** The cap was pinned to
+ * `MAX_POINT_LIGHTS` so the one light loop kept one bound. Then a courtyard of candles, lanterns
+ * and braziers asked 461 of its 3,456 froxels for more than sixteen, and up to fifty. A full froxel
+ * keeps its nearest and drops the rest, and its neighbour keeps a different set, so the step
+ * between them drew as hard-edged, screen-aligned rectangles on every vault, on both backends.
+ *
+ * Seventy-six because it is the next cap the table's shape allows above what was measured: a run
+ * must divide the 320-texel row, and the two regions must end on one. What it costs is the table,
+ * 292 KB to 1.1 MB, and the loop's bound. The bound is the clustered arm's alone in effect: the
+ * fixed arm still leaves at its own count and never passes `MAX_LIGHTS`, so a consumer that does
+ * not cluster iterates what it did. What would make 76 wrong is content that asks more of one
+ * froxel, and the answer then is the next cap rather than a softer overflow: any overflow rule
+ * draws the cluster's edge.
  *
  * **It is not the old limit wearing a new hat.** Sixteen was a budget for the *whole scene*, chosen
- * by distance with a contention band because somebody always had to be last. Sixteen per froxel is
- * a different sixteen in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
+ * by distance with a contention band because somebody always had to be last. This is a different
+ * set in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
  */
 export const MAX_LIGHTS_PER_CLUSTER = (CLUSTER_TEXELS - 1) * 4;
 /**
@@ -149,7 +157,7 @@ export const LIGHT_REGION_TEXELS = MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS;
  * beginning of a row.
  */
 export const TABLE_WIDTH = 320;
-/** Rows: three of light records and 54 of cluster runs. 292 KB of `RGBA32UI`, allocated once. */
+/** Rows: five of light records and 216 of cluster runs. 1.1 MB of `RGBA32UI`, allocated once. */
 export const TABLE_HEIGHT = (LIGHT_REGION_TEXELS + CLUSTER_COUNT * CLUSTER_TEXELS) / TABLE_WIDTH;
 /** The table, as the `Uint32Array` both a texture upload and a readback comparison want. */
 export function createClusterTable() {
@@ -216,11 +224,37 @@ export function clusterViewBounds(i, j, k, near, far, tanHalfFovY, aspect, out)
     out[2] = zNear;
     out[5] = zFar;
 }
+/**
+ * `clusterViewBounds` for a slice whose depths and half extents the caller already has. The same
+ * arithmetic in the same order, so the same box to the bit; the binner's inner loop uses this.
+ */
+function sliceBounds(i, j, zNear, zFar, halfWNear, halfWFar, halfHNear, halfHFar, out) {
+    const xLo = -1 + (2 * i) / CLUSTER_X;
+    const xHi = -1 + (2 * (i + 1)) / CLUSTER_X;
+    const yLo = -1 + (2 * j) / CLUSTER_Y;
+    const yHi = -1 + (2 * (j + 1)) / CLUSTER_Y;
+    out[0] = Math.min(xLo * halfWNear, xLo * halfWFar, xHi * halfWNear, xHi * halfWFar);
+    out[3] = Math.max(xLo * halfWNear, xLo * halfWFar, xHi * halfWNear, xHi * halfWFar);
+    out[1] = Math.min(yLo * halfHNear, yLo * halfHFar, yHi * halfHNear, yHi * halfHFar);
+    out[4] = Math.max(yLo * halfHNear, yLo * halfHFar, yHi * halfHNear, yHi * halfHFar);
+    out[2] = zNear;
+    out[5] = zFar;
+}
 /*
  * Scratch, at module scope, because `buildLightClusters` runs per frame on WebGL2 and the house
  * rule forbids allocating there.
  */
 const bounds = new Float32Array(6);
+/**
+ * Where each slice begins, for the frame being binned: `sliceNearDepth` for every slice and the
+ * far plane, computed once. The same expression as a call per cluster, so the same numbers.
+ *
+ * **Once a binning rather than once a cluster**, which was two `pow` for every light and every
+ * cluster it might touch. A courtyard of candles within a few metres of the camera is 640,000 of
+ * those pairs, and the binning took 47 ms of a frame. On WebGL2 it runs every `bindMeshPass`, so a
+ * probe grid baked at night binned for a minute.
+ */
+const sliceDepths = new Float64Array(CLUSTER_Z + 1);
 /** View-space light centres, kept for the overflow rule, which needs them after the fact. */
 const viewX = new Float32Array(MAX_CLUSTERED_LIGHTS);
 const viewY = new Float32Array(MAX_CLUSTERED_LIGHTS);
@@ -247,18 +281,6 @@ function distanceSqToBounds(x, y, z, b) {
     const dz = z < (b[2] ?? 0) ? (b[2] ?? 0) - z : z > (b[5] ?? 0) ? z - (b[5] ?? 0) : 0;
     return dx * dx + dy * dy + dz * dz;
 }
-/** Insertion sort over a cluster's index slots. At most 28 integers, so this is not a hot loop. */
-function sortIndices(table, base, count) {
-    for (let n = 1; n < count; n++) {
-        const value = table[base + 4 + n] ?? 0;
-        let m = n - 1;
-        while (m >= 0 && (table[base + 4 + m] ?? 0) > value) {
-            table[base + 4 + m + 1] = table[base + 4 + m] ?? 0;
-            m--;
-        }
-        table[base + 4 + m + 1] = value;
-    }
-}
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -317,6 +339,8 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
      * replaces; agreeing about the invisible bytes is what keeps the comparison exact.
      */
     table.fill(0, LIGHT_REGION_TEXELS * 4);
+    for (let k = 0; k <= CLUSTER_Z; k++)
+        sliceDepths[k] = sliceNearDepth(k, near, far);
     for (let light = 0; light < count; light++) {
         const x = lights.positions[light * 3] ?? 0;
         const y = lights.positions[light * 3 + 1] ?? 0;
@@ -404,8 +428,10 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
         const radiusSq = radius * radius;
         for (let k = kLo; k <= kHi; k++) {
             /* The same two depths `clusterViewBounds` builds this slice's box from. */
-            const halfHNear = sliceNearDepth(k, near, far) * tanHalfFovY;
-            const halfHFar = sliceNearDepth(k + 1, near, far) * tanHalfFovY;
+            const zNear = sliceDepths[k] ?? 0;
+            const zFar = sliceDepths[k + 1] ?? 0;
+            const halfHNear = zNear * tanHalfFovY;
+            const halfHFar = zFar * tanHalfFovY;
             const halfWNear = halfHNear * aspect;
             const halfWFar = halfHFar * aspect;
             const iLo = tileOf(Math.min(xLo / halfWNear, xLo / halfWFar, xHi / halfWNear, xHi / halfWFar), CLUSTER_X);
@@ -414,10 +440,10 @@ export function buildLightClusters(lights, view, near, far, tanHalfFovY, aspect,
             const jHi = tileOf(Math.max(yLo / halfHNear, yLo / halfHFar, yHi / halfHNear, yHi / halfHFar), CLUSTER_Y);
             for (let j = jLo; j <= jHi; j++) {
                 for (let i = iLo; i <= iHi; i++) {
-                    clusterViewBounds(i, j, k, near, far, tanHalfFovY, aspect, bounds);
+                    sliceBounds(i, j, zNear, zFar, halfWNear, halfWFar, halfHNear, halfHFar, bounds);
                     if (distanceSqToBounds(vx, vy, depth, bounds) > radiusSq)
                         continue;
-                    insert(table, i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y, light, near, far, tanHalfFovY, aspect);
+                    insert(table, i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y, light, bounds);
                 }
             }
         }
@@ -430,37 +456,43 @@ function tileOf(ndc, tiles) {
     return tile < 0 ? 0 : tile > tiles - 1 ? tiles - 1 : tile;
 }
 /**
- * Put a light into a cluster, applying the overflow rule.
+ * Each member's squared distance from its cluster's centre, slot for slot with the table, for the
+ * frame being binned. Allocated on the first binning, so a consumer that never clusters pays nothing.
+ *
+ * **Measured rather than assumed rare.** The overflow rule used to recompute the cluster's box and
+ * all sixteen members' distances on every insert into a full cluster, on the argument that full
+ * clusters are rare. Three hundred candles within a few metres of the camera fill 2,152 of the
+ * 3,456, and the binning spent 47 ms a frame there. Each distance is the same number whenever it is
+ * computed, so it is computed once, at the insert that placed the member.
+ */
+let memberDistance = null;
+/**
+ * Put a light into a cluster, applying the overflow rule. `box` is the cluster's bounds, which the
+ * caller has just tested the light against.
  *
  * Lights arrive in increasing index, so the common path appends and the list is already sorted.
  * The sort only runs on the rare path where a replacement broke that order.
  */
-function insert(table, cluster, light, near, far, tanHalfFovY, aspect) {
+function insert(table, cluster, light, box) {
     const base = clusterBase(cluster);
     const count = table[base] ?? 0;
+    const distances = (memberDistance ??= new Float64Array(CLUSTER_COUNT * MAX_LIGHTS_PER_CLUSTER));
+    const at = cluster * MAX_LIGHTS_PER_CLUSTER;
+    const cx = ((box[0] ?? 0) + (box[3] ?? 0)) * 0.5;
+    const cy = ((box[1] ?? 0) + (box[4] ?? 0)) * 0.5;
+    const cz = ((box[2] ?? 0) + (box[5] ?? 0)) * 0.5;
+    const mine = centreDistanceSq(light, cx, cy, cz);
     if (count < MAX_LIGHTS_PER_CLUSTER) {
         table[base + 4 + count] = light;
+        distances[at + count] = mine;
         table[base] = count + 1;
         return;
     }
-    /*
-     * Full. Drop the farthest member if this one is nearer, measured from the cluster's own centre.
-     * Rare enough that recomputing the members' distances beats carrying 96,768 floats of scratch
-     * for a case most frames never reach.
-     */
-    const k = Math.floor(cluster / (CLUSTER_X * CLUSTER_Y));
-    const j = Math.floor((cluster - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X);
-    const i = cluster - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;
-    clusterViewBounds(i, j, k, near, far, tanHalfFovY, aspect, bounds);
-    const cx = ((bounds[0] ?? 0) + (bounds[3] ?? 0)) * 0.5;
-    const cy = ((bounds[1] ?? 0) + (bounds[4] ?? 0)) * 0.5;
-    const cz = ((bounds[2] ?? 0) + (bounds[5] ?? 0)) * 0.5;
-    const mine = centreDistanceSq(light, cx, cy, cz);
+    /* Full. Drop the farthest member if this one is nearer, measured from the cluster's own centre. */
     let worstSlot = -1;
     let worst = mine;
     for (let n = 0; n < MAX_LIGHTS_PER_CLUSTER; n++) {
-        const held = table[base + 4 + n] ?? 0;
-        const d = centreDistanceSq(held, cx, cy, cz);
+        const d = distances[at + n] ?? 0;
         if (d > worst) {
             worst = d;
             worstSlot = n;
@@ -469,7 +501,26 @@ function insert(table, cluster, light, near, far, tanHalfFovY, aspect) {
     if (worstSlot < 0)
         return;
     table[base + 4 + worstSlot] = light;
-    sortIndices(table, base, MAX_LIGHTS_PER_CLUSTER);
+    distances[at + worstSlot] = mine;
+    sortMembers(table, base, distances, at);
+}
+/**
+ * Sort a full cluster's index slots ascending, carrying each member's distance with it. An insertion
+ * sort: sixteen integers, so this is not a hot loop.
+ */
+function sortMembers(table, base, distances, at) {
+    for (let n = 1; n < MAX_LIGHTS_PER_CLUSTER; n++) {
+        const value = table[base + 4 + n] ?? 0;
+        const distance = distances[at + n] ?? 0;
+        let m = n - 1;
+        while (m >= 0 && (table[base + 4 + m] ?? 0) > value) {
+            table[base + 4 + m + 1] = table[base + 4 + m] ?? 0;
+            distances[at + m + 1] = distances[at + m] ?? 0;
+            m--;
+        }
+        table[base + 4 + m + 1] = value;
+        distances[at + m + 1] = distance;
+    }
 }
 function centreDistanceSq(light, cx, cy, cz) {
     const dx = (viewX[light] ?? 0) - cx;

package/dist/render/cutoutCaster.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which shadow casters cut their shadow out of their texture's alpha, decided once for both backends.
+ *
+ * **A caster with an albedo and a cutoff above zero is a cutout**: a leaf card, a chain link, a
+ * fence, whose shape is in its alpha and not in its geometry. The same test the colour pass makes
+ * when it discards, so a surface that is a hole in the picture is a hole in its shadow. Written once,
+ * here, because two backends deciding it separately is how they come to disagree about a leaf
+ * (AGENTS.md, 2026-08-13).
+ *
+ * Called per draw, so the answer is written into one object and returned again: a draw allocates
+ * nothing. What that gives up is holding two answers at once, which no caller does; the depth pass
+ * reads it and binds before it asks again.
+ */
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+/** A cutout caster's texture, its cutoff and its UV scale. */
+export interface CutoutCaster<Texture> {
+    readonly albedo: Texture;
+    readonly cutoff: number;
+    readonly u: number;
+    readonly v: number;
+}
+/** The cutout `material` casts, or null for an ordinary caster. */
+export declare function cutoutOf<Texture>(material: SurfaceMaterial<Texture> | null | undefined): CutoutCaster<Texture> | null;

package/dist/render/cutoutCaster.js

@@ -0,0 +1,20 @@
+const answer = {
+    albedo: null,
+    cutoff: 0,
+    u: 1,
+    v: 1,
+};
+/** The cutout `material` casts, or null for an ordinary caster. */
+export function cutoutOf(material) {
+    if (material === null || material === undefined)
+        return null;
+    const albedo = material.albedo ?? null;
+    const cutoff = material.cutout ?? 0;
+    if (albedo === null || !(cutoff > 0))
+        return null;
+    answer.albedo = albedo;
+    answer.cutoff = cutoff;
+    answer.u = material.uScale ?? 1;
+    answer.v = material.vScale ?? 1;
+    return answer;
+}