@woosh/meep-engine 3.29.0 → 3.30.0

package/src/shade/renderer/particles/optimizer/pass_fold_constants.js

@@ -284,7 +284,12 @@ export function evaluate_particle_operation(op, a, b, c) {
         // the whole of what the option trades; anything an executor could disagree about by more
         // than a rounding is refused below rather than folded.
         case VM_OP.MAD: return Math.fround(a * b + c);
-        case VM_OP.MIX: return Math.fround(a + (b - a) * c);
+        case VM_OP.MIX: {
+            const from = Math.fround(a * Math.fround(1 - c));
+            const to = Math.fround(b * c);
+
+            return Math.fround(from + to);
+        }
         case VM_OP.SIN: return Math.fround(Math.sin(a));
         case VM_OP.COS: return Math.fround(Math.cos(a));
         case VM_OP.TAN: return Math.fround(Math.tan(a));
@@ -294,7 +299,7 @@ export function evaluate_particle_operation(op, a, b, c) {
         case VM_OP.LOG: return Math.fround(Math.log(a));
         // `1 / sqrt(a)` for `a <= 0` is an infinity or a `NaN`, and `finite` drops both — the same
         // rule that keeps `SQRT` next door out of trouble, so there is nothing to say here.
-        case VM_OP.RSQRT: return Math.fround(1 / Math.sqrt(a));
+        case VM_OP.RSQRT: return Math.fround(1 / Math.fround(Math.sqrt(a)));
         // WGSL's `pow` is `exp2(e2 * log2(e1))`, which is a `NaN` for every base at or below zero
         // — including `pow(0, 0)`, where JS says 1. A fold that turned the hardware's `NaN` into a
         // number would not be a rounding, so the non-positive bases are not folded at all.
@@ -306,9 +311,10 @@ export function evaluate_particle_operation(op, a, b, c) {
                 return NaN;
             }
 
-            const t = Math.min(Math.max((c - a) / (b - a), 0), 1);
+            const span = Math.fround(b - a);
+            const t = Math.min(Math.max(Math.fround(Math.fround(c - a) / span), 0), 1);
 
-            return Math.fround(t * t * (3 - 2 * t));
+            return Math.fround(Math.fround(t * t) * Math.fround(3 - Math.fround(2 * t)));
         }
         // `atan2(0, 0)` is 0 in JS and left to the implementation in WGSL. Every other pair is an
         // angle both agree on to a rounding.

package/src/shade/renderer/particles/shaders/shader_particle_init_free_list.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The free list as a fresh pool leaves it: every slot free, `dead[i] = i`, bottom to top.
+ *
+ * It is a stack of slot indices — the emit pass pops `dead[--DEAD]` — so the order within it is
+ * arbitrary and identity is simply the cheapest arrangement to write. What matters is that every
+ * slot appears exactly once: a repeat hands two particles one record, and a gap strands a slot for
+ * the lifetime of the system.
+ *
+ * ## Why this is a pass and not a host write
+ *
+ * Zero is not a valid free list — `dead[i] = 0` for every `i` is the same slot half a million times
+ * over — so the buffer WebGPU hands back has to be written before the first emit. Writing it from
+ * the host means a typed array the size of the list (2 MiB at the default capacity), a loop over
+ * every element of it, and a staged upload, all on the frame the system is constructed. Here it is
+ * one store per slot with no host memory involved at all, and it leaves the free list `STORAGE`
+ * only: nothing else ever writes it from the host, so it needs no `COPY_DST` and stays off the
+ * driver's upload-friendly — and slower — path.
+ *
+ * ## Bounded launch, strided loop
+ *
+ * The pool capacity belongs to whoever constructs the system, and `capacity / workgroup_size` can
+ * pass `maxComputeWorkgroupsPerDimension` — a validation error for a direct dispatch, and worse
+ * than that for the indirect ones elsewhere in the engine, which simply do not run. So the caller
+ * clamps the launch and every lane strides through the list by the whole grid: the fill covers any
+ * capacity, and a grid that happens to cover it in one pass costs one comparison to find out.
+ */
+/** Lanes per workgroup. One store each, so this is sized for occupancy and nothing else. */
+export const PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE: 256;
+export const shader_particle_init_free_list: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_init_free_list.d.ts.map

package/src/shade/renderer/particles/shaders/shader_particle_init_free_list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_init_free_list.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_init_free_list.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,4FAA4F;AAC5F,yDAA0D;AAQ1D,2DAmBG;8BA3D2B,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_init_free_list.js

@@ -0,0 +1,62 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+
+/**
+ * The free list as a fresh pool leaves it: every slot free, `dead[i] = i`, bottom to top.
+ *
+ * It is a stack of slot indices — the emit pass pops `dead[--DEAD]` — so the order within it is
+ * arbitrary and identity is simply the cheapest arrangement to write. What matters is that every
+ * slot appears exactly once: a repeat hands two particles one record, and a gap strands a slot for
+ * the lifetime of the system.
+ *
+ * ## Why this is a pass and not a host write
+ *
+ * Zero is not a valid free list — `dead[i] = 0` for every `i` is the same slot half a million times
+ * over — so the buffer WebGPU hands back has to be written before the first emit. Writing it from
+ * the host means a typed array the size of the list (2 MiB at the default capacity), a loop over
+ * every element of it, and a staged upload, all on the frame the system is constructed. Here it is
+ * one store per slot with no host memory involved at all, and it leaves the free list `STORAGE`
+ * only: nothing else ever writes it from the host, so it needs no `COPY_DST` and stays off the
+ * driver's upload-friendly — and slower — path.
+ *
+ * ## Bounded launch, strided loop
+ *
+ * The pool capacity belongs to whoever constructs the system, and `capacity / workgroup_size` can
+ * pass `maxComputeWorkgroupsPerDimension` — a validation error for a direct dispatch, and worse
+ * than that for the indirect ones elsewhere in the engine, which simply do not run. So the caller
+ * clamps the launch and every lane strides through the list by the whole grid: the fill covers any
+ * capacity, and a grid that happens to cover it in one pass costs one comparison to find out.
+ */
+
+/** Lanes per workgroup. One store each, so this is sized for occupancy and nothing else. */
+export const PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE = 256;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+resources.setImmediate("u_capacity", u32);
+resources.createGroup().addStorageBuffer("dead", WebGPUArray.u32, true);
+
+export const shader_particle_init_free_list = ComputeShader.from({
+    label: "Particle Init Free List",
+    resources,
+    body: CodeChunk.from(
+        /* language=wgsl */
+        `
+@compute @workgroup_size(${PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(global_invocation_id) global_id : vec3<u32>,
+    @builtin(num_workgroups) group_count : vec3<u32>,
+) {
+    // The grid may be smaller than the list; every lane keeps taking the next slot a whole grid on.
+    let stride = group_count.x * ${PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE}u;
+
+    for (var slot = global_id.x; slot < u_capacity; slot += stride) {
+        dead[slot] = slot;
+    }
+}
+`),
+});

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts

@@ -29,6 +29,19 @@ export function u32_to_unit_f32(u: number): number;
  * so a source may overlap the destination in any way and still mean what it held before the
  * instruction.
  *
+ * ## Every step is an f32 step
+ *
+ * The register file is `f32`, and so is the shader's. An opcode that takes more than one arithmetic
+ * step to reach its result therefore rounds at every one of them, through `Math.fround`, rather
+ * than computing wide and rounding on the way out. Rounding only at the end gives f32 RESULTS
+ * without f32 RANGE, and the range is where the two executors part company: a product that is
+ * `inf` on the device is an ordinary number in `f64`, a difference that saturates there is finite
+ * here, and neither is a rounding apart. `CROSS` answered 0 where the device answers NaN, and
+ * `SMOOTHSTEP` answered the midpoint where the device answers the near edge.
+ *
+ * Two opcodes are deliberately outside that rule, and each says why where it is written: `MAD`,
+ * which models the fused product, and `FRACT`, whose subtraction cannot round twice.
+ *
  * @param {object} params
  * @param {Uint32Array} params.words instruction words for the section (SPAWN or UPDATE)
  * @param {Float32Array} params.constants constant pool, one float per word

package/src/shade/renderer/particles/vm/ParticleVMReference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,gCAHW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA8DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAR+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IACS,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACM,SAAS,GAAzB,MAAM;IACJ;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAuRlD"}
+{"version":3,"file":"ParticleVMReference.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/ParticleVMReference.js"],"names":[],"mappings":"AA0BA;;;;;;;GAOG;AACH,gCAHW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAW5C;AAED;;;;;GAKG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAR+B,KAAK,EAAzB,WAAW;IACU,SAAS,EAA9B,YAAY;IACG,cAAc,EAA7B,MAAM;IACc,MAAM,EAA1B,WAAW;IACS,QAAQ,GAA5B,MAAM,EAAE,EAAE;IACM,SAAS,GAAzB,MAAM;IACJ;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAyUlD"}

package/src/shade/renderer/particles/vm/ParticleVMReference.js

@@ -125,6 +125,19 @@ const LITERAL_U32 = new Uint32Array(LITERAL_F32.buffer);
  * so a source may overlap the destination in any way and still mean what it held before the
  * instruction.
  *
+ * ## Every step is an f32 step
+ *
+ * The register file is `f32`, and so is the shader's. An opcode that takes more than one arithmetic
+ * step to reach its result therefore rounds at every one of them, through `Math.fround`, rather
+ * than computing wide and rounding on the way out. Rounding only at the end gives f32 RESULTS
+ * without f32 RANGE, and the range is where the two executors part company: a product that is
+ * `inf` on the device is an ordinary number in `f64`, a difference that saturates there is finite
+ * here, and neither is a rounding apart. `CROSS` answered 0 where the device answers NaN, and
+ * `SMOOTHSTEP` answered the midpoint where the device answers the near edge.
+ *
+ * Two opcodes are deliberately outside that rule, and each says why where it is written: `MAD`,
+ * which models the fused product, and `FRACT`, whose subtraction cannot round twice.
+ *
  * @param {object} params
  * @param {Uint32Array} params.words instruction words for the section (SPAWN or UPDATE)
  * @param {Float32Array} params.constants constant pool, one float per word
@@ -263,6 +276,18 @@ export function execute_particle_vm({
             case DIV:
                 for (let i = 0; i < w; i++) d[i] = a[i] / b[i];
                 break;
+            // The exception to the rule above, and the only one that is a choice. `MAD` models the
+            // FUSED form: the product reaches the addition unrounded, which is what makes it more
+            // than `MUL` then `ADD`. {@link ../optimizer/pass_peephole.js} refuses to fuse that
+            // pair into a `MAD` by default for exactly this reason, and
+            // {@link ../optimizer/particle_integer_bounds.js} exists only to prove the cases where
+            // the product needs no rounding and the two forms therefore agree; rounding it here
+            // would make both of those dead weight.
+            //
+            // The shader spells this `a * b + c`, which a driver is free to contract into an FMA
+            // or not, so it is a reading rather than a certainty — `VM_OP.MAD` is INEXACT in
+            // {@link ../optimizer/particle_vm_semantics.js} to say so. Spelling the shader
+            // `fma(a, b, c)` would settle it in this reading's favour on every device.
             case MAD:
                 for (let i = 0; i < w; i++) d[i] = a[i] * b[i] + c[i];
                 break;
@@ -272,8 +297,21 @@ export function execute_particle_vm({
             case MAX:
                 for (let i = 0; i < w; i++) d[i] = Math.max(a[i], b[i]);
                 break;
+            // WGSL defines `mix(e1, e2, e3)` as `e1 * (1 - e3) + e2 * e3`, and this used to spell
+            // it as the lerp `a + (b - a) * c`. The two are the same number only where the span
+            // `b - a` loses nothing, and at the ends of the f32 range it loses everything:
+            // `mix(1e20, 1, 1)` is 1 on the device and was 0 here, because `1 - 1e20` IS `-1e20`
+            // in f32. Rounding the lerp's steps without changing its shape would have made it
+            // worse — the span of (3e38, -3e38) is not an f32 at all, so a blend both of whose
+            // ends are finite would have come out infinite. Scaling each end on its own is what
+            // the shader does and it cannot overflow where the result does not.
             case MIX:
-                for (let i = 0; i < w; i++) d[i] = a[i] + (b[i] - a[i]) * c[i];
+                for (let i = 0; i < w; i++) {
+                    const from = Math.fround(a[i] * Math.fround(1 - c[i]));
+                    const to = Math.fround(b[i] * c[i]);
+
+                    d[i] = Math.fround(from + to);
+                }
                 break;
             case CLAMP:
                 for (let i = 0; i < w; i++) d[i] = Math.min(Math.max(a[i], b[i]), c[i]);
@@ -288,6 +326,12 @@ export function execute_particle_vm({
             case FLOOR:
                 for (let i = 0; i < w; i++) d[i] = Math.floor(a[i]);
                 break;
+            // The other exception, and this one is free: `a - floor(a)` cannot round twice. For
+            // |a| >= 1 the fractional part is a run of at most 23 of a's own mantissa bits and is
+            // an f32 exactly; for |a| < 1 it is a itself, or `1 + a`, which only becomes inexact
+            // in f64 once |a| falls below about 2^-29 — by which point it is far inside the last
+            // f32 step below 1 and rounds to 1.0 either way. The two conditions a double rounding
+            // would need cannot hold at once, which the spec checks rather than assumes.
             case FRACT:
                 for (let i = 0; i < w; i++) d[i] = a[i] - Math.floor(a[i]);
                 break;
@@ -316,9 +360,13 @@ export function execute_particle_vm({
                 for (let i = 0; i < w; i++) d[i] = smoothstep(a[i], b[i], c[i]);
                 break;
             // WGSL's `inverseSqrt`. Spelled as the reciprocal of a root rather than approximated,
-            // because the reference is the definition the hardware's estimate is measured against.
+            // because the reference is the definition the hardware's estimate is measured against
+            // — which is also why the root is rounded before the division reads it. A definition
+            // carried out in f64 is not the thing `inverseSqrt` is allowed to be 2 ULP away from:
+            // 1 / sqrt(0.0009) is 33.33333206176758 taken wide and 33.333335876464844 taken the
+            // way the device takes it, and the slack is measured from the second.
             case RSQRT:
-                for (let i = 0; i < w; i++) d[i] = 1 / Math.sqrt(a[i]);
+                for (let i = 0; i < w; i++) d[i] = Math.fround(1 / Math.fround(Math.sqrt(a[i])));
                 break;
             case TAN:
                 for (let i = 0; i < w; i++) d[i] = Math.tan(a[i]);
@@ -336,40 +384,55 @@ export function execute_particle_vm({
 
             // The reductions write a single lane; whatever wants the result wider reads it through
             // an `.xxxx` swizzle.
+            //
+            // Every step goes through `Math.fround`, because a plain `let sum = 0` is an f64
+            // accumulator and only the store into the register file rounds — which gives f32
+            // RESULTS without f32 RANGE, and the range is not recovered at the end. The shader
+            // computes `dot(a, a)` entirely in f32, where 1e20 squared is already `inf` and
+            // 1e-25 squared is already zero, so the two sides answered `inf` against 1.00000002e20
+            // and, through NORMALIZE's `len > 0`, the zero vector against a unit one.
             case DOT: {
                 let dp = 0;
-                for (let i = 0; i < w; i++) dp += a[i] * b[i];
+                for (let i = 0; i < w; i++) dp = Math.fround(dp + Math.fround(a[i] * b[i]));
                 d[0] = dp;
                 break;
             }
+            // Six products and three differences, every one of them in f32. Taken wide, a lane
+            // whose two products both overflow cancelled to exactly 0 — the mathematically right
+            // answer for a vector crossed with itself — where the device subtracts `inf - inf` and
+            // gets NaN. a = b = (0, 1e20, 1e20) is the shortest witness, and a NaN that exists
+            // only on the GPU is the worst shape this takes: invisible in the editor preview, and
+            // loose in a position attribute from the first frame it appears.
             case CROSS:
-                d[0] = a[1] * b[2] - a[2] * b[1];
-                d[1] = a[2] * b[0] - a[0] * b[2];
-                d[2] = a[0] * b[1] - a[1] * b[0];
+                d[0] = Math.fround(Math.fround(a[1] * b[2]) - Math.fround(a[2] * b[1]));
+                d[1] = Math.fround(Math.fround(a[2] * b[0]) - Math.fround(a[0] * b[2]));
+                d[2] = Math.fround(Math.fround(a[0] * b[1]) - Math.fround(a[1] * b[0]));
                 // A fourth lane, if asked for, is the zero the opcode used to append.
                 d[3] = 0;
                 break;
             case LENGTH: {
                 let sum = 0;
-                for (let i = 0; i < w; i++) sum += a[i] * a[i];
-                d[0] = Math.sqrt(sum);
+                for (let i = 0; i < w; i++) sum = Math.fround(sum + Math.fround(a[i] * a[i]));
+                d[0] = Math.fround(Math.sqrt(sum));
                 break;
             }
             case NORMALIZE: {
                 let sum = 0;
-                for (let i = 0; i < w; i++) sum += a[i] * a[i];
-                const len = Math.sqrt(sum);
-                const inv = len > 0 ? 1 / len : 0;
+                for (let i = 0; i < w; i++) sum = Math.fround(sum + Math.fround(a[i] * a[i]));
+                const len = Math.fround(Math.sqrt(sum));
+                // the shader's `select(0.0, 1.0 / len, len > 0.0)` — the same test, over a length
+                // that has now underflowed on the same inputs
+                const inv = len > 0 ? Math.fround(1 / len) : 0;
                 for (let i = 0; i < w; i++) d[i] = a[i] * inv;
                 break;
             }
             case DISTANCE: {
                 let sum = 0;
                 for (let i = 0; i < w; i++) {
-                    const e = a[i] - b[i];
-                    sum += e * e;
+                    const e = Math.fround(a[i] - b[i]);
+                    sum = Math.fround(sum + Math.fround(e * e));
                 }
-                d[0] = Math.sqrt(sum);
+                d[0] = Math.fround(Math.sqrt(sum));
                 break;
             }
 
@@ -414,6 +477,18 @@ export function execute_particle_vm({
 }
 
 /**
+ * WGSL's `smoothstep`, which is `t * t * (3 - 2t)` over `t = clamp((x - low) / (high - low), 0, 1)`.
+ *
+ * Every step is an f32 step, for the reason the executor's docblock gives, and here it is the SPAN
+ * that carries it: with the edges at ±3e38 the divisor is 6e38, which is `inf` in f32, so the
+ * device divides by an infinity, gets 0, and returns the near edge. Taken wide the divisor is
+ * finite and the answer was the midpoint — a ramp authored across a range wider than f32 reaches
+ * read as half-way in the editor preview and as not started at all in the game.
+ *
+ * The equal-edges guard stands in for a division by zero the device would do instead. It is the one
+ * place this function is not the shader's arithmetic, and it only differs from it at `x === edge0`,
+ * where the device's `0 / 0` is a NaN that WGSL does not define the clamp of.
+ *
  * @param {number} edge0
  * @param {number} edge1
  * @param {number} x
@@ -421,6 +496,9 @@ export function execute_particle_vm({
  */
 function smoothstep(edge0, edge1, x) {
     if (edge0 === edge1) return x < edge0 ? 0 : 1;
-    const t = Math.min(Math.max((x - edge0) / (edge1 - edge0), 0), 1);
-    return t * t * (3 - 2 * t);
+
+    const span = Math.fround(edge1 - edge0);
+    const t = Math.min(Math.max(Math.fround(Math.fround(x - edge0) / span), 0), 1);
+
+    return Math.fround(Math.fround(t * t) * Math.fround(3 - Math.fround(2 * t)));
 }

package/src/shade/renderer/rasterize/bucket/rasterization_has_opaque_bucket.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether the scene has anything in an opaque rasterization bucket.
+ *
+ * The opaque path clears the visibility-buffer colour attachments and the depth attachment on its
+ * first draw, and it is the only thing that does — every later pass is recorded with `load`. So a
+ * scene whose materials are all alpha-tested or transparent, which is an ordinary thing (a
+ * foliage-only vegetation view, a glass preview, a point light whose only casters are billboards),
+ * used to draw over the previous frame's contents: geometry depth-tested against stale occluders,
+ * and every pixel the alpha-tested pass did not cover keeping last frame's mesh and triangle ids for
+ * the deferred shading to resolve as real surfaces.
+ *
+ * This is what lets the composer hand the clear to the first pass that will actually run.
+ *
+ * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function rasterization_has_opaque_bucket(active_buckets: Set<number>): boolean;
+//# sourceMappingURL=rasterization_has_opaque_bucket.d.ts.map

package/src/shade/renderer/rasterize/bucket/rasterization_has_opaque_bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rasterization_has_opaque_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/rasterization_has_opaque_bucket.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gEANW,IAAI,MAAM,CAAC,GACT,OAAO,CAWnB"}

package/src/shade/renderer/rasterize/bucket/rasterization_has_opaque_bucket.js

@@ -0,0 +1,28 @@
+import { rasterization_opaque_buckets } from "./rasterization_opaque_buckets.js";
+
+/**
+ * Whether the scene has anything in an opaque rasterization bucket.
+ *
+ * The opaque path clears the visibility-buffer colour attachments and the depth attachment on its
+ * first draw, and it is the only thing that does — every later pass is recorded with `load`. So a
+ * scene whose materials are all alpha-tested or transparent, which is an ordinary thing (a
+ * foliage-only vegetation view, a glass preview, a point light whose only casters are billboards),
+ * used to draw over the previous frame's contents: geometry depth-tested against stale occluders,
+ * and every pixel the alpha-tested pass did not cover keeping last frame's mesh and triangle ids for
+ * the deferred shading to resolve as real surfaces.
+ *
+ * This is what lets the composer hand the clear to the first pass that will actually run.
+ *
+ * @param {Set<number>} active_buckets bucket ids any material in the scene asks for
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function rasterization_has_opaque_bucket(active_buckets) {
+    for (const _bucket of rasterization_opaque_buckets(active_buckets)) {
+        return true;
+    }
+
+    return false;
+}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0I3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}
+{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0J3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js

@@ -13,6 +13,7 @@ import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/gra
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state } from "../bucket/construct_primitive_state.js";
 import { rasterization_opaque_buckets } from "../bucket/rasterization_opaque_buckets.js";
+import { rasterization_has_opaque_bucket } from "../bucket/rasterization_has_opaque_bucket.js";
 import { graph_mesh_frustum_cull } from "../compute/graph_mesh_frustum_cull.js";
 import { graph_rasterize_meshes_alpha_tested } from "../native/graph_rasterize_meshes_alpha_tested.js";
 import { graph_extract_meshes_from_bucket } from "./graph_extract_meshes_from_bucket.js";
@@ -123,13 +124,27 @@ export function graph_rasterize_scene_fast_raw({
 
     // alpha-tested: reuse the existing native pass but skip HZB filtering by passing hzb=-1
     if (job.alpha_tested_pass !== undefined) {
+        /**
+         * The opaque path's first draw is the only thing that clears the visibility-buffer colour
+         * attachments and the depth attachment — the clear values live on the opaque pass descriptor
+         * and reach the targets through its `loadOp`, and every pass after it is recorded with
+         * `load`. When the scene has no opaque bucket that draw never happens, so the first pass that
+         * does run owns the clear. The alpha-tested descriptor carries the same clear values
+         * (`[0,0,0,0]`, VIZ_BUFFER_INVALID_MESH_VALUE, DEPTH_BACKGROUND_VALUE), so handing it over
+         * changes nothing about what the targets are cleared to.
+         *
+         * Wherever an opaque bucket exists — nearly every scene — this starts true and every call
+         * below asks for `false`, exactly as before.
+         */
+        let targets_cleared = rasterization_has_opaque_bucket(active_buckets);
+
 
         const alpha_tested_front = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx: view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Front,
             cull_policy: job.cull_policy,
             limits,
@@ -142,13 +157,14 @@ export function graph_rasterize_scene_fast_raw({
 
         target_depth = alpha_tested_front.depth;
         targets_color = alpha_tested_front.color_targets;
+        targets_cleared = targets_cleared || alpha_tested_front.executed;
 
         const alpha_tested_double = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx: view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Double,
             cull_policy: job.cull_policy,
             limits,
@@ -161,6 +177,7 @@ export function graph_rasterize_scene_fast_raw({
 
         target_depth = alpha_tested_double.depth;
         targets_color = alpha_tested_double.color_targets;
+        targets_cleared = targets_cleared || alpha_tested_double.executed;
     }
 
     return {target_depth, targets_color};

package/src/shade/renderer/rasterize/standard/graph_rasterize_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_scene.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;AACH;IAN+B,KAAK;IACC,GAAG;IACA,MAAM;IACjC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0MrE"}
+{"version":3,"file":"graph_rasterize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_scene.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH;IAN+B,KAAK;IACC,GAAG;IACA,MAAM;IACjC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0NrE"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_scene.js

@@ -11,6 +11,7 @@ import { RasterizationCollectionType } from "../expand/RasterizationCollectionTy
 import { graph_rasterize_meshes_alpha_tested } from "../native/graph_rasterize_meshes_alpha_tested.js";
 import { graph_rasterize_partial_opaque } from "./graph_rasterize_partial_opaque.js";
 import { graph_rasterize_remaining_opaque } from "./graph_rasterize_remaining_opaque.js";
+import { rasterization_has_opaque_bucket } from "../bucket/rasterization_has_opaque_bucket.js";
 
 /**
  * TODO:
@@ -155,13 +156,27 @@ export function graph_rasterize_scene({
 
 
     if (job.alpha_tested_pass !== undefined) {
+        /**
+         * The opaque path's first draw is the only thing that clears the visibility-buffer colour
+         * attachments and the depth attachment — the clear values live on the opaque pass descriptor
+         * and reach the targets through its `loadOp`, and every pass after it is recorded with
+         * `load`. When the scene has no opaque bucket that draw never happens, so the first pass that
+         * does run owns the clear. The alpha-tested descriptor carries the same clear values
+         * (`[0,0,0,0]`, VIZ_BUFFER_INVALID_MESH_VALUE, DEPTH_BACKGROUND_VALUE), so handing it over
+         * changes nothing about what the targets are cleared to.
+         *
+         * Wherever an opaque bucket exists — nearly every scene — this starts true and every call
+         * below asks for `false`, exactly as before.
+         */
+        let targets_cleared = rasterization_has_opaque_bucket(active_buckets);
+
 
         const alpha_tested_front = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Front,
             cull_policy: job.cull_policy,
             limits,
@@ -174,13 +189,14 @@ export function graph_rasterize_scene({
 
         gr_texture_depth = alpha_tested_front.depth;
         raster_color_targets = alpha_tested_front.color_targets;
+        targets_cleared = targets_cleared || alpha_tested_front.executed;
 
         const alpha_tested_double = graph_rasterize_meshes_alpha_tested({
             graph,
             buckets: gr_render_buckets,
             view_ctx,
             render_pass_descriptor: job.alpha_tested_pass,
-            clear_target: false,
+            clear_target: !targets_cleared,
             side: ShadeDrawSide.Double,
             cull_policy: job.cull_policy,
             limits,
@@ -193,6 +209,7 @@ export function graph_rasterize_scene({
 
         gr_texture_depth = alpha_tested_double.depth;
         raster_color_targets = alpha_tested_double.color_targets;
+        targets_cleared = targets_cleared || alpha_tested_double.executed;
 
         if (alpha_tested_front.executed || alpha_tested_double.executed) {
 

package/src/shade/renderer/shader/type/WebGPUStruct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebGPUStruct.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/type/WebGPUStruct.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH;IAqMI;;;;;;;;;;;;;;OAcG;IACH,8BAHW,MAAM,GACL,YAAY,CAiCvB;IAED;;;;OAIG;IACH,6BAHc,eAAe,KACjB,YAAY,CAiBvB;IA9PD;;;OAGG;IACH,uBAEC;IAVD,kBAEC;IAUD;;;OAGG;IACH,iBAFU,eAAe,EAAE,CAEf;IAmBZ;;;;OAIG;IACH,YAHW,YAAY,GACV,IAAI,CAYhB;IAED;;;OAGG;IACH,SAFY,YAAY,CAUvB;IAED;;;;;;;;OAQG;IACH,kBAJa,MAAM,CA+BlB;IAED;;;;;;OAMG;IACH,QAFa,IAAI,CAoChB;IAED,4BAYC;IAqGD;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAGD;;;;;OAKG;IACH,gBAJW,MAAM,GACL,eAAe,CAa1B;IA8GL;;;OAGG;IACH,mBAFU,OAAO,CAEc;;CAN9B;2BAza0B,iBAAiB;gCAEZ,sBAAsB"}
+{"version":3,"file":"WebGPUStruct.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/type/WebGPUStruct.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH;IAiNI;;;;;;;;;;;;;;OAcG;IACH,8BAHW,MAAM,GACL,YAAY,CAiCvB;IAED;;;;OAIG;IACH,6BAHc,eAAe,KACjB,YAAY,CAiBvB;IA1QD;;;OAGG;IACH,uBAEC;IAVD,kBAEC;IAUD;;;OAGG;IACH,iBAFU,eAAe,EAAE,CAEf;IAmBZ;;;;OAIG;IACH,YAHW,YAAY,GACV,IAAI,CAwBhB;IAED;;;OAGG;IACH,SAFY,YAAY,CAUvB;IAED;;;;;;;;OAQG;IACH,kBAJa,MAAM,CA+BlB;IAED;;;;;;OAMG;IACH,QAFa,IAAI,CAoChB;IAED,4BAYC;IAqGD;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAGD;;;;;OAKG;IACH,gBAJW,MAAM,GACL,eAAe,CAa1B;IA8GL;;;OAGG;IACH,mBAFU,OAAO,CAEc;;CAN9B;2BArb0B,iBAAiB;gCAEZ,sBAAsB"}

package/src/shade/renderer/shader/type/WebGPUStruct.js

@@ -83,6 +83,18 @@ export class WebGPUStruct extends WebGPUType {
         this.#size = other.#size;
         this.#align = other.#align;
 
+        /**
+         * Carried with the layout it describes. Without it a clone claimed a size and per-field
+         * offsets while reading as unbuilt, and `pack()` — which reorders the fields and then
+         * rebuilds only `if (this.#is_built)` — left the declaration in the packed order and the
+         * offsets in the unpacked one. WGSL would lay a field out at one address and
+         * `write_struct_value` seek to another, with no error anywhere.
+         */
+        this.#is_built = other.#is_built;
+
+        //the cached WGSL text belongs to the struct that built it
+        this.#declaration_chunk = undefined;
+
         this.fields = other.fields.map(f => f.clone());
 
         return this;

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.d.ts

@@ -47,10 +47,16 @@ export class WebGPUMipmapGenerator {
      * @param {GPUTexture} texture - Texture to generate mipmaps for.
      * @param {GPUTextureDescriptor} texture_descriptor - GPUTextureDescriptor the texture was created with.
      * @param {TextureFilterType} [filter]
-     * @param {GPUCommandEncoder} [commandEncoder]
+     * @param {GPUCommandEncoder} [commandEncoder] when supplied, the commands are recorded rather
+     *   than submitted, so the scratch resources outlive this call and `release_after_submit` is
+     *   required
+     * @param {{destroy: function():void}[]} [release_after_submit] where the scratch buffer and
+     *   textures go when the encoder is the caller's; destroy them once it has submitted
      * @returns {GPUTexture} - The originally passed texture
      */
-    generateMipmap(texture: GPUTexture, texture_descriptor: GPUTextureDescriptor, filter?: TextureFilterType, commandEncoder?: GPUCommandEncoder): GPUTexture;
+    generateMipmap(texture: GPUTexture, texture_descriptor: GPUTextureDescriptor, filter?: TextureFilterType, commandEncoder?: GPUCommandEncoder, release_after_submit?: {
+        destroy: () => void;
+    }[]): GPUTexture;
     #private;
 }
 import { HashMap } from "../../../../core/collection/map/HashMap.js";

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebGPUMipmapGenerator.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js"],"names":[],"mappings":"AAkMA;;;GAGG;AACH;IAqDI;;;OAGG;IACH,+BAWC;IAnED;;OAEG;IACH,kBAAM;IAEN;;;;OAIG;IACH,oBAFU,QAAQ,eAAe,oBAAoB,CAE3B;IAE1B;;OAEG;IACH,oBAAQ;IAgCR,gBAGC;IA6DD;;;;;OAKG;IACH,yEAFW,iBAAiB,QAY3B;IAED;;;OAGG;IACH,wBAFW,MAAM,QAyBhB;IAED;;OAEG;IACH,cAEC;IAmGG,qBAiBE;IAEF,oBAGE;IAGN;;;;;;;;OAQG;IACH,uFAJW,iBAAiB,kDA0X3B;;CACJ;wBAl2BuB,4CAA4C;AA2CpE;IAEI;;OAEG;IACH,yBAAO;IAEP;;OAEG;IACH;;;;QA1BA;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;;;MAgBI;IAEP;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;CAEJ;kCAjEiC,yBAAyB"}
+{"version":3,"file":"WebGPUMipmapGenerator.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js"],"names":[],"mappings":"AAkMA;;;GAGG;AACH;IAqDI;;;OAGG;IACH,+BAWC;IAnED;;OAEG;IACH,kBAAM;IAEN;;;;OAIG;IACH,oBAFU,QAAQ,eAAe,oBAAoB,CAE3B;IAE1B;;OAEG;IACH,oBAAQ;IAgCR,gBAGC;IA6DD;;;;;OAKG;IACH,yEAFW,iBAAiB,QAY3B;IAED;;;OAGG;IACH,wBAFW,MAAM,QAyBhB;IAED;;OAEG;IACH,cAEC;IAmGG,qBAiBE;IAEF,oBAGE;IAGN;;;;;;;;;;;;OAYG;IACH,uFARW,iBAAiB,6DAIjB;QAAC,OAAO,QAAa,IAAI,CAAA;KAAC,EAAE,cAyZtC;;CACJ;wBAr4BuB,4CAA4C;AA2CpE;IAEI;;OAEG;IACH,yBAAO;IAEP;;OAEG;IACH;;;;QA1BA;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;;;MAgBI;IAEP;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAMlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAOjB;CAEJ;kCAjEiC,yBAAyB"}