@woosh/meep-engine 3.29.0 → 3.31.0

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

@@ -1,42 +1,40 @@
 import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_cluster_depth_to_z_slice } from "../../light/cluster/chunk_cluster_depth_to_z_slice.js";
-import { AVBOIT_OCCUPANCY_WORDS, AVBOIT_VIRTUAL_SLICES_MAX } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
-import { chunk_avboit_occupancy_range } from "../../rasterize/native/avboit/chunk_avboit_occupancy_range.js";
-import { chunk_avboit_occupancy_word_mask } from "../../rasterize/native/avboit/chunk_avboit_occupancy_word_mask.js";
+import { AVBOIT_OCCUPANCY_WORDS } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { chunk_avboit_occupancy_mark } from "../../rasterize/native/avboit/chunk_avboit_occupancy_mark.js";
 import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../../rasterize/native/avboit/shader_avboit_occupancy.js";
 import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { chunk_aabb3_view_depth_range } from "../../shader/chunk/geometry/aabb3/chunk_aabb3_view_depth_range.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { PARTICLE_EMITTER_TICK_WORKGROUP_SIZE } from "../ParticleConstants.js";
 import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
 import { EMITTER_BLEND } from "../data/PARTICLE_EMITTER_STRUCT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-import { chunk_particle_bounds_unknown } from "../bounds/chunk_particle_bounds_unknown.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_bounds_unknown } from "../bounds/chunk_particle_bounds_unknown.js";
 
 /**
  * The particles' AVBOIT occupancy: one thread per emitter table row, marking the virtual depth
  * slices the emitter's bounding box spans, so the warp keeps resolution where the particles are.
  * The particle counterpart of `shader_avboit_occupancy`, which does the same per meshlet AABB.
  *
- * Per emitter rather than per particle: the box is the one the bounds passes measured from the
- * particles ({@link ../data/PARTICLE_EMITTER_STATE.js}), it is one thread per row instead of one
+ * Per emitter rather than per particle: the box is the one the bounds passes measured from the
+ * particles ({@link ../data/PARTICLE_EMITTER_STATE.js}), it is one thread per row instead of one
  * per live particle contending for the same few words, and a particle that strays past it is not
  * lost — it lands on the boundary of the nearest run, the warp's flat-in-a-gap property. Emitters
  * that only add light (`EMITTER_BLEND.ADDITIVE`) splat no extinction and mark nothing: a slice
  * reserved for them would be a slice the surfaces do not get.
  *
  * The box is already in world space — it was measured from world-space particles, dilated to hold
- * their quads — so all that is left is its view-depth interval, which is its centre's depth plus or
- * minus the box's extent along the view axis. That is a support-function projection, not eight
- * transformed corners: the box is axis-aligned in world space and only its extent along one axis is
- * wanted. The camera looks down −Z, so the interval is clamped at the near plane and mapped through
- * the same depth curve and dilation the meshlet pass uses.
+ * their quads — so all that is left is its view-depth interval (`aabb3_view_depth_range`, a
+ * support-function projection rather than eight transformed corners), clamped at the near plane and
+ * mapped through the same depth curve and dilation the meshlet pass uses (`avboit_occupancy_mark`).
+ * Both are shared with the dynamic meshes' occupancy, which starts from a world-space box too.
  *
- * The box is published by this frame's bounds pass after emit and simulate. The next tick will cull
- * against that same measurement. An infinite box means no measured population and marks nothing.
+ * The box is published by this frame's bounds pass after emit and simulate. The next tick will cull
+ * against that same measurement. An infinite box means no measured population and marks nothing.
  *
  * Walks the table with its page iterator, read-only: the rows are the tick's output of this frame.
  *
@@ -61,27 +59,6 @@ const body = CodeChunk.from(
     `
 const PARTICLE_BLEND_ADDITIVE : u32 = ${EMITTER_BLEND.ADDITIVE}u;
 
-// The view-space depth interval of a world-space box: the centre's depth, plus or minus the box's
-// extent along the view axis. \`view_axis\` is the view matrix's third ROW — read as the z of the
-// transformed basis vectors rather than as matrix columns, the same numbers in the form the WGSL
-// emulator also evaluates.
-fn particle_emitter_view_depth_range(box : ${AABB3_STRUCT.wgsl_ref}, view : mat4x4<f32>) -> vec2<f32> {
-    let center = (box.min + box.max) * 0.5;
-    let half_extent = (box.max - box.min) * 0.5;
-
-    let view_axis = vec3<f32>(
-        (view * vec4<f32>(1.0, 0.0, 0.0, 0.0)).z,
-        (view * vec4<f32>(0.0, 1.0, 0.0, 0.0)).z,
-        (view * vec4<f32>(0.0, 0.0, 1.0, 0.0)).z,
-    );
-
-    // camera looks down -Z, so depth is -z
-    let depth = -(view * vec4<f32>(center, 1.0)).z;
-    let extent = dot(abs(view_axis), half_extent);
-
-    return vec2<f32>(depth - extent, depth + extent);
-}
-
 @compute @workgroup_size(${GROUP_SIZE}, 1, 1)
 fn main(
     @builtin(workgroup_id) wg_id : vec3<u32>,
@@ -105,46 +82,23 @@ fn main(
         return;
     }
 
-    let state = ${STATE.marshalling_method_read}(&emitter_database, ${PG}_slot_to_index(slot_in_page));
-    // Unknown bounds have no live particles to splat; do not reserve the whole depth volume.
-    if (particle_bounds_unknown(state.bounds_min)) { return; }
+    let state = ${STATE.marshalling_method_read}(&emitter_database, ${PG}_slot_to_index(slot_in_page));
+    // Unknown bounds have no live particles to splat; do not reserve the whole depth volume.
+    if (particle_bounds_unknown(state.bounds_min)) { return; }
     let box = ${AABB3_STRUCT.make({ min: "state.bounds_min", max: "state.bounds_max" })};
 
-    let range_view = particle_emitter_view_depth_range(box, camera.view_matrix);
-
-    let depth_min = range_view.x;
-    let depth_max = range_view.y;
+    let range_view = aabb3_view_depth_range(box, camera.view_matrix);
 
-    if (depth_max < camera.clip_near_far.x) {
-        // entirely in front of the near plane
-        return;
-    }
-
-    let limit = ${AVBOIT_VIRTUAL_SLICES_MAX}.0;
-    let slice_near = cluster_depth_to_z_slice(max(depth_min, camera.clip_near_far.x), settings.cluster_parameters, limit);
-    let slice_far = cluster_depth_to_z_slice(depth_max, settings.cluster_parameters, limit);
-
-    let range = avboit_occupancy_range(slice_near, slice_far);
-
-    let word_first = u32(range.x) >> 5u;
-    let word_last = u32(range.y) >> 5u;
-
-    for (var word = word_first; word <= word_last; word++) {
-        let mask = avboit_occupancy_word_mask(word, range.x, range.y);
-        if (mask != 0u) {
-            atomicOr(&occupancy[word], mask);
-        }
-    }
+    avboit_occupancy_mark(range_view.x, range_view.y, camera.clip_near_far.x, settings.cluster_parameters);
 }
     `, [
         PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(GROUP_SIZE),
-        chunk_particle_emitter,
-        chunk_particle_bounds_unknown,
+        chunk_particle_emitter,
+        chunk_particle_bounds_unknown,
         STATE.chunk_read,
         AABB3_STRUCT.declaration_chunk,
-        chunk_cluster_depth_to_z_slice,
-        chunk_avboit_occupancy_range,
-        chunk_avboit_occupancy_word_mask,
+        chunk_aabb3_view_depth_range,
+        chunk_avboit_occupancy_mark,
     ]
 );
 

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAsGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCAlJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}
+{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAwGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCApJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}

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

@@ -3,8 +3,8 @@ import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/Re
 import { atomic_u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { OIT_COVERAGE_MAX } from "../../rasterize/native/oit/OIT_CONSTANTS.js";
 import { AVBOIT_WARP_STRUCT } from "../../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
+import { chunk_avboit_coverage } from "../../rasterize/native/avboit/chunk_avboit_coverage.js";
 import { chunk_avboit_splat_slice } from "../../rasterize/native/avboit/chunk_avboit_splat_slice.js";
 import { chunk_avboit_transmittance_to_extinction } from "../../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
 import { chunk_avboit_view_depth_to_physical } from "../../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
@@ -37,7 +37,7 @@ export const PARTICLE_AVBOIT_SPLAT_BIND_GROUP_VOLUME = 1;
  * Depth is the fragment's own view depth, from the vertex stage, through curve → warp → physical
  * and the two-slice linear splat. No depth attachment, for the reason the meshlet splat has none.
  *
- * The `draw_list` this binds is the alive list as compaction left it. The volume is a sum, so
+ * The `draw_list` this binds is the alive list as compaction left it. The volume is a sum, so
  * there is no order for it to be in.
  */
 
@@ -84,7 +84,8 @@ fn fs_main(in : ParticleVertexOut) {
         alpha = alpha * particle_soft_fade(scene_vd, in.view_depth, ${PARTICLE_SOFT_FADE_RANGE});
     }
 
-    let coverage = clamp(alpha, 0.0, ${OIT_COVERAGE_MAX});
+    // the coverage the draw weights this fragment by, through the same function
+    let coverage = avboit_coverage(alpha);
 
     if (coverage <= 0.0) {
         // additive, faded out against the surface behind it, or fully transparent: occludes nothing
@@ -110,6 +111,7 @@ fn fs_main(in : ParticleVertexOut) {
 `, [
     chunk_particle_billboard_vertex,
     chunk_particle_scene_view_depth,
+    chunk_avboit_coverage,
     chunk_avboit_transmittance_to_extinction,
     chunk_avboit_view_depth_to_physical,
     chunk_avboit_splat_slice,

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":"AA4BA;;;;;;;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,CAuVlD"}

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

@@ -3,6 +3,8 @@ import {
     PARTICLE_VM_MAX_INSTRUCTIONS,
 } from "../ParticleConstants.js";
 import {
+    VM_BUILTIN_COMPONENTS,
+    VM_BUILTIN_PADDING,
     VM_DEST,
     VM_DST_MASK,
     VM_DST_SHIFT,
@@ -125,6 +127,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
@@ -242,8 +257,22 @@ export function execute_particle_vm({
                 break;
 
             case LOAD_BUILTIN: {
+                /*
+                 The host supplies the builtin's OWN lanes; the ISA supplies the rest.
+
+                 This used to read `v[i] ?? 0` for every lane, so the padding an over-wide load sees
+                 was the host's decision — and the two executors already disagreed, because
+                 `vm_load_builtin` in the WGSL fixes its own. The editor's host fills the scalars in
+                 all four lanes and gives the position a `w` of 0, so LOAD_BUILTIN.3 DELTA_TIME read
+                 (dt, dt, dt) in the preview and (dt, 0, 0) on the GPU. The parity spec could not
+                 catch it: it hard-codes the shader's padding into the reference's fixture, so the
+                 two were compared against one host's answer.
+                */
                 const v = builtins[s0] ?? [0, 0, 0, 0];
-                for (let i = 0; i < w; i++) d[i] = v[i] ?? 0;
+                const components = VM_BUILTIN_COMPONENTS[s0] ?? 0;
+                const padding = VM_BUILTIN_PADDING[s0] ?? 0;
+
+                for (let i = 0; i < w; i++) d[i] = i < components ? (v[i] ?? 0) : padding;
                 break;
             }
 
@@ -263,6 +292,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 +313,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 +342,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 +376,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 +400,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 +493,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 +512,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/path_tracer/shader/chunk_sample_material_data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sample_material_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js"],"names":[],"mappings":"AAiCA;;;GAGG;AACH,0CAFU,SAAS,CA8FlB;AAED,mDA+HC;0BAxOyB,oCAAoC"}
+{"version":3,"file":"chunk_sample_material_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,0CAFU,SAAS,CA+FlB;AAED,mDAuIC;0BAjPyB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js

@@ -4,6 +4,7 @@ import {
 } from "../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
 import { chunk_decode_tangent_normal } from "../../shader/chunk/geometry/normal/chunk_decode_tangent_normal.js";
 import { chunk_F_Hauber } from "../../shader/chunk/brdf/fresnel/chunk_F_Hauber.js";
+import { chunk_albedo_unpremultiply } from "../../shader/chunk/material/chunk_albedo_unpremultiply.js";
 import {
     chunk_build_orthonormal_matrix_nt
 } from "../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_nt.js";
@@ -85,7 +86,7 @@ fn sample_material_alpha(
     // head-on".
     var opacity = surface_alpha;
     if (material.transmission_factor > 0.0) {
-        let albedo = texture_sample_diffuse.rgb * material.color_albedo.rgb;
+        let albedo = albedo_unpremultiply(texture_sample_diffuse) * material.color_albedo.rgb;
         let f_metalness = material.metallic_factor; // ORM texture not sampled in alpha path; metallic_factor is enough for typical glass (metalness = 0)
         let specular_f0 = dielectric_specular_color(material.ior_factor, f_metalness, albedo);
         let nov = saturate(abs(dot(world_face_normal, ray_direction)));
@@ -125,6 +126,7 @@ fn sample_material_alpha(
         chunk_interpolate_attribute_3f32,
         chunk_interpolate_attribute_2f32,
         chunk_dielectric_specular_color,
+        chunk_albedo_unpremultiply,
         chunk_F_Hauber,
     ]
 )
@@ -227,7 +229,14 @@ fn sample_material_data(
     const bit_step = 1.0 / 255.0;
     
     // dither to prevent banding    
-    let dithered_diffuse_sample = max(vec3(0.0), texture_sample_diffuse.rgb + (random_vec3() - 0.5 ) * bit_step);
+    /*
+     The albedo texture is stored premultiplied, and this used to multiply the raw .rgb straight
+     into the output while separately taking .a as the opacity — so a leaf card at rgb=(0.3,0.5,0.2)
+     a=0.5 shaded at (0.15,0.25,0.1) AND was treated as half covered, counting the same number
+     twice. The deferred G-buffer divided it back out all along; the two renderers disagreed about
+     the encoding of one texture, and this is the renderer the other is compared against.
+    */
+    let dithered_diffuse_sample = max(vec3(0.0), albedo_unpremultiply(texture_sample_diffuse) + (random_vec3() - 0.5 ) * bit_step);
     let texture_sample_emissive = max(vec3(0.0), indirect_sample_texture(material.texture_emissive, material.sampler_emissive, uv).rgb + (random_vec3() - 0.5 ) * bit_step);
 
 
@@ -254,6 +263,7 @@ fn sample_material_data(
         chunk_decode_tangent_normal,
         chunk_compute_triangle_face_normal,
         chunk_indirect_sample_texture,
+        chunk_albedo_unpremultiply,
         chunk_random_vec3,
     ]
 )

package/src/shade/renderer/postprocess/TemporalJitterSequence.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The sub-pixel offset a temporal technique jitters the projection by, and how far it moved since the
+ * last frame.
+ *
+ * A Halton (2, 3) sequence centred on zero, cycled by frame index. Both {@link TAA} and {@link NSS}
+ * compose one of these; they used to carry a line-for-line copy of it each, which is why `Renderer` can
+ * pick either object as "the jitter source" — the call site already treated them as one interface.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class TemporalJitterSequence {
+    /**
+     * @param {number} [size] number of phases before the sequence repeats
+     */
+    constructor(size?: number);
+    /**
+     * Offset for the current frame, in pixels, in `[-0.5, 0.5]` on each axis.
+     * @type {number[]}
+     */
+    Jitter: number[];
+    /**
+     * Frame-to-frame delta of {@link Jitter}.
+     * @type {number[]}
+     */
+    JitterDelta: number[];
+    /**
+     * Number of phases before the sequence repeats. Rebuilds the sequence.
+     * @param {number} size
+     */
+    set size(size: number);
+    /**
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Advance to a frame, which is what moves {@link Jitter} and computes {@link JitterDelta}.
+     *
+     * @param {number} i
+     */
+    set frame_index(i: number);
+    #private;
+}
+//# sourceMappingURL=TemporalJitterSequence.d.ts.map

package/src/shade/renderer/postprocess/TemporalJitterSequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalJitterSequence.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/postprocess/TemporalJitterSequence.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH;IAmBI;;OAEG;IACH,mBAFW,MAAM,EAQhB;IA3BD;;;OAGG;IACH,QAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEG;IAiCrB;;;OAGG;IACH,uBAMC;IAED;;OAEG;IACH,mBAEC;IAED;;;;OAIG;IACH,2BAoBC;;CACJ"}