@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,62 @@
+/**
+ * The wide register backing for {@link ./chunk_particle_vm.js}: the VM's register file in a storage
+ * buffer, {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} slots deep — every slot the
+ * instruction set can name.
+ *
+ * This is the fallback. It exists so that "the effect is too big for the register file" is not a
+ * thing an author of a particle graph can be told. It is slow, and it is meant to be: it runs when
+ * the alternative is not running at all.
+ *
+ * ## Why it is slow
+ *
+ * Both, and neither is fixable within this shape. Every operand access becomes a memory access —
+ * three sources of up to four lanes each and four write-back lanes, so up to twelve loads and four
+ * stores per instruction where the fast backing has none. And it gives up the scalar register
+ * indexing that the wave-uniform section decode in the simulate pass buys: the fast file is indexed
+ * through M0, this one through a per-lane address. Instruction fetch and the opcode switch stay
+ * scalar, so the loss is narrower than it could be, but it is real.
+ *
+ * ## Slot-major, and why it is not negotiable
+ *
+ * \`vm_registers[slot * PARTICLE_VM_WIDE_LAUNCH_LANES + lane]\`. The slot moves slowly, the lane fast,
+ * so the lanes of one wave reading one slot read consecutive floats — a single coalesced run, and a
+ * whole workgroup's file stays resident in L1.
+ *
+ * Laid out the other way round — \`[lane * SLOTS + slot]\`, which is the way it reads more naturally
+ * — each lane would stride a kilobyte and every operand access would touch a distinct cache line per
+ * lane. That is roughly an order of magnitude, in a shader that is already the slow path, and it is
+ * invisible afterwards. Hence the note.
+ *
+ * ## The file is never cleared
+ *
+ * Nothing zeroes this file, and the buffer backing it is transient — recycled frame to frame,
+ * holding whatever the last user left. Reading a register before writing it is a corrupt program,
+ * not a defined one, and the compiler does not emit them: the graph allocator assigns a value its
+ * register at the instruction that defines it, so every read follows a write.
+ *
+ * This is the one place the two backings are not interchangeable. The fast file zeroes, so a corrupt
+ * program reads 0.0 there and in {@link ./ParticleVMReference.js} — defined, and the same in both.
+ * Here it reads the previous batch. Anything that generates programs without the def-before-use
+ * guarantee (the fuzzer, hand-written test assembly) must not be run against this backing and expect
+ * to match the reference; the parity spec zeroes the buffer to close that gap for tests only.
+ *
+ * Zeroing in production would be its own cost — {@link ../ParticleConstants.js
+ * PARTICLE_VM_REGISTER_SLOTS} stores per particle, before a single instruction runs, on the path
+ * that is already the slow one.
+ *
+ * ## Binding contract
+ *
+ * The enclosing shader must declare a read_write storage buffer named \`vm_registers\` of
+ * \`array<f32>\`, at least \`PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS\` elements, and
+ * must call \`particle_vm_bind_registers(lane)\` once per invocation with a lane index below
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} — which is what the wide passes'
+ * bounded launch guarantees, and why they have one.
+ *
+ * The enclosing shader includes this chunk or the fast one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_wide: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_vm_registers_wide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_vm_registers_wide.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/chunk_particle_vm_registers_wide.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,+CAFU,SAAS,CAyBhB;0BArFuB,oCAAoC"}

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

@@ -0,0 +1,86 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_VM_REGISTER_SLOTS, PARTICLE_VM_WIDE_LAUNCH_LANES } from "../ParticleConstants.js";
+
+/**
+ * The wide register backing for {@link ./chunk_particle_vm.js}: the VM's register file in a storage
+ * buffer, {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} slots deep — every slot the
+ * instruction set can name.
+ *
+ * This is the fallback. It exists so that "the effect is too big for the register file" is not a
+ * thing an author of a particle graph can be told. It is slow, and it is meant to be: it runs when
+ * the alternative is not running at all.
+ *
+ * ## Why it is slow
+ *
+ * Both, and neither is fixable within this shape. Every operand access becomes a memory access —
+ * three sources of up to four lanes each and four write-back lanes, so up to twelve loads and four
+ * stores per instruction where the fast backing has none. And it gives up the scalar register
+ * indexing that the wave-uniform section decode in the simulate pass buys: the fast file is indexed
+ * through M0, this one through a per-lane address. Instruction fetch and the opcode switch stay
+ * scalar, so the loss is narrower than it could be, but it is real.
+ *
+ * ## Slot-major, and why it is not negotiable
+ *
+ * \`vm_registers[slot * PARTICLE_VM_WIDE_LAUNCH_LANES + lane]\`. The slot moves slowly, the lane fast,
+ * so the lanes of one wave reading one slot read consecutive floats — a single coalesced run, and a
+ * whole workgroup's file stays resident in L1.
+ *
+ * Laid out the other way round — \`[lane * SLOTS + slot]\`, which is the way it reads more naturally
+ * — each lane would stride a kilobyte and every operand access would touch a distinct cache line per
+ * lane. That is roughly an order of magnitude, in a shader that is already the slow path, and it is
+ * invisible afterwards. Hence the note.
+ *
+ * ## The file is never cleared
+ *
+ * Nothing zeroes this file, and the buffer backing it is transient — recycled frame to frame,
+ * holding whatever the last user left. Reading a register before writing it is a corrupt program,
+ * not a defined one, and the compiler does not emit them: the graph allocator assigns a value its
+ * register at the instruction that defines it, so every read follows a write.
+ *
+ * This is the one place the two backings are not interchangeable. The fast file zeroes, so a corrupt
+ * program reads 0.0 there and in {@link ./ParticleVMReference.js} — defined, and the same in both.
+ * Here it reads the previous batch. Anything that generates programs without the def-before-use
+ * guarantee (the fuzzer, hand-written test assembly) must not be run against this backing and expect
+ * to match the reference; the parity spec zeroes the buffer to close that gap for tests only.
+ *
+ * Zeroing in production would be its own cost — {@link ../ParticleConstants.js
+ * PARTICLE_VM_REGISTER_SLOTS} stores per particle, before a single instruction runs, on the path
+ * that is already the slow one.
+ *
+ * ## Binding contract
+ *
+ * The enclosing shader must declare a read_write storage buffer named \`vm_registers\` of
+ * \`array<f32>\`, at least \`PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS\` elements, and
+ * must call \`particle_vm_bind_registers(lane)\` once per invocation with a lane index below
+ * {@link ../ParticleConstants.js PARTICLE_VM_WIDE_LAUNCH_LANES} — which is what the wide passes'
+ * bounded launch guarantees, and why they have one.
+ *
+ * The enclosing shader includes this chunk or the fast one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_wide = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_VM_WIDE_LAUNCH_LANES : u32 = ${PARTICLE_VM_WIDE_LAUNCH_LANES}u;
+
+// This invocation's column in the register file. Set once, before any program runs.
+var<private> vm_reg_lane : u32;
+
+fn particle_vm_bind_registers(lane : u32) {
+    vm_reg_lane = lane;
+}
+
+// Slot-major: one slot's lanes are consecutive, so a wave reads a coalesced run. See the note above
+// before changing this.
+fn vm_reg_index(index : u32) -> u32 {
+    return index * PARTICLE_VM_WIDE_LAUNCH_LANES + vm_reg_lane;
+}
+
+fn vm_reg_read(index : u32) -> f32 {
+    return vm_registers[vm_reg_index(index)];
+}
+
+fn vm_reg_write(index : u32, value : f32) {
+    vm_registers[vm_reg_index(index)] = value;
+}
+`);

package/src/shade/renderer/postprocess/denoise/debug/graph_pass_debug_reprojection.d.ts

@@ -5,11 +5,10 @@
  * @param {number} input_previous_depth
  * @param {number} input_current_normal
  * @param {number} input_velocity
- * @param {number} input
  * @param {GPUCameraContext} camera_current
  * @param {GPUCameraContext} camera_previous
  * @param {number[]} jitter
  * @param {number[]} resolution
  */
-export function graph_pass_debug_reprojection({ graph, input_current_depth, input_previous_depth, input_current_normal, input_velocity, input, camera_current, camera_previous, jitter, resolution }: FrameGraph): any;
+export function graph_pass_debug_reprojection({ graph, input_current_depth, input_previous_depth, input_current_normal, input_velocity, camera_current, camera_previous, jitter, resolution }: FrameGraph): any;
 //# sourceMappingURL=graph_pass_debug_reprojection.d.ts.map

package/src/shade/renderer/postprocess/denoise/debug/graph_pass_debug_reprojection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_pass_debug_reprojection.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/postprocess/denoise/debug/graph_pass_debug_reprojection.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;GAYG;AACH,uNAyGC"}
+{"version":3,"file":"graph_pass_debug_reprojection.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/postprocess/denoise/debug/graph_pass_debug_reprojection.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;GAWG;AACH,gNAuGC"}

package/src/shade/renderer/postprocess/denoise/debug/graph_pass_debug_reprojection.js

@@ -95,7 +95,6 @@ const pipeline_descriptor = ComputePipelineDescriptor.simplified({
  * @param {number} input_previous_depth
  * @param {number} input_current_normal
  * @param {number} input_velocity
- * @param {number} input
  * @param {GPUCameraContext} camera_current
  * @param {GPUCameraContext} camera_previous
  * @param {number[]} jitter
@@ -107,7 +106,6 @@ export function graph_pass_debug_reprojection({
                                                   input_previous_depth,
                                                   input_current_normal,
                                                   input_velocity,
-                                                  input,
                                                   camera_current,
                                                   camera_previous,
                                                   jitter = [0, 0],
@@ -166,7 +164,6 @@ export function graph_pass_debug_reprojection({
 
     const reprojection_builder = graph.add("debug reprojection", reprojection_data, execute_reproject);
 
-    reprojection_data.input = reprojection_builder.read(input);
     reprojection_data.depth_current = reprojection_builder.read(input_current_depth);
     reprojection_data.velocity = reprojection_builder.read(input_velocity);
     reprojection_data.depth_previous = reprojection_builder.read(input_previous_depth);

package/src/shade/renderer/postprocess/dof/gather/DepthOfFieldU.js

@@ -256,7 +256,7 @@ export class DepthOfFieldU {
         // Autofocus inputs. Explicit modes (manual / world-point) are projected
         // onto the camera forward axis on the CPU; auto / nearest / point are
         // resolved on the GPU from the depth buffer.
-        const m = camera.transform.matrix;
+        const m = camera.transform;
         const autofocus_params = compute_dof_autofocus_params(
             this.focus,
             [m[12], m[13], m[14]],   // camera world position

package/src/shade/renderer/postprocess/dof/raymarch/DepthOfField.js

@@ -261,7 +261,7 @@ export class DepthOfField {
         // Autofocus inputs. Explicit modes (manual / world-point) are
         // projected onto the camera forward axis on the CPU; auto / nearest
         // / point are resolved on the GPU from the depth buffer.
-        const m = camera.transform.matrix;
+        const m = camera.transform;
         const autofocus_params = compute_dof_autofocus_params(
             this.focus,
             [m[12], m[13], m[14]],   // camera world position

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -49,7 +49,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#131@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#130@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/postprocess/nss/NSS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NSS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/nss/NSS.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAgaI;;;;;;OAMG;IACH,uDAHW,MAAM,GACJ,MAAM,CAKlB;IA2CD,uGAQC;IAlSD;;OAEG;IACH,uCAwCC;IApOD;;;;OAIG;IACH,QAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEG;IAErB;;;;;OAKG;IACH,eAFU,OAAO,CAEI;IAErB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;;;;OAMG;IACH,gBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;;;;;;OASG;IACH,eAFU,MAAM,CAEI;IACpB,wCAAwC;IACxC,eAD8B,MAAM,CAChB;IAyKpB;;;;;OAKG;IACH,6BAyHC;IAED,wCAAwC;IACxC,0BAEC;IArKD;;OAEG;IACH,gBA4BC;IAkJD,sCAIC;IACD,mCAAiE;IAcjE,0BASC;IA4CD,6BAAkF;IAClF,0BAA+C;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAf4B,KAAK;QACT,qBAAqB,EAAlC,MAAM;QACO,qBAAqB,EAAlC,MAAM;QACO,gBAAgB,EAA7B,MAAM;QACO,+BAA+B,EAA5C,MAAM;QAKO,qBAAqB,EAAlC,MAAM;QACO,cAAc,EAA3B,MAAM;QACS,iBAAiB,EAAhC,MAAM,EAAE;QACO,iBAAiB,EAAhC,MAAM,EAAE;QACN,MAAM,CA0NlB;;CACJ;2BAjwB0B,iBAAiB;0CAtBF,oDAAoD"}
+{"version":3,"file":"NSS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/postprocess/nss/NSS.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAgaI;;;;;;OAMG;IACH,uDAHW,MAAM,GACJ,MAAM,CAKlB;IA2CD,uGAQC;IAlSD;;OAEG;IACH,uCAwCC;IApOD;;;;OAIG;IACH,QAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,aAFU,MAAM,EAAE,CAEG;IAErB;;;;;OAKG;IACH,eAFU,OAAO,CAEI;IAErB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;;;;OAMG;IACH,gBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;;;;;;OASG;IACH,eAFU,MAAM,CAEI;IACpB,wCAAwC;IACxC,eAD8B,MAAM,CAChB;IAyKpB;;;;;OAKG;IACH,6BAyHC;IAED,wCAAwC;IACxC,0BAEC;IArKD;;OAEG;IACH,gBA4BC;IAkJD,sCAIC;IACD,mCAAiE;IAcjE,0BASC;IA4CD,6BAAkF;IAClF,0BAA+C;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAf4B,KAAK;QACT,qBAAqB,EAAlC,MAAM;QACO,qBAAqB,EAAlC,MAAM;QACO,gBAAgB,EAA7B,MAAM;QACO,+BAA+B,EAA5C,MAAM;QAKO,qBAAqB,EAAlC,MAAM;QACO,cAAc,EAA3B,MAAM;QACS,iBAAiB,EAAhC,MAAM,EAAE;QACO,iBAAiB,EAAhC,MAAM,EAAE;QACN,MAAM,CA0NlB;;CACJ;2BAjwB0B,iBAAiB;0CAtBF,oDAAoD"}

package/src/shade/renderer/postprocess/nss/NSS.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { align_4 } from "../../../../core/binary/align_4.js";
 import { halton_sequence } from "../../../../core/math/statistics/halton_sequence.js";
 import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
 import { GPUTypedBuffer } from "../../buffer/GPUTypedBuffer.js";
@@ -380,7 +381,7 @@ export class NSS {
 
         // ── Upload weights (packed int8 as u32 array) ──
         const packed_weights = value.pack_weights();
-        const weights_byte_size = (packed_weights.byteLength + 3) & ~3;
+        const weights_byte_size = align_4(packed_weights.byteLength);
         this.#weights_buffer = this.#device.createBuffer({
             label: "NSS / weights (packed int8)",
             size: weights_byte_size,
@@ -416,7 +417,7 @@ export class NSS {
 
         // ── Upload per-head transfer LUTs (packed int8 as u32 array) ──
         const packed_luts = value.pack_luts();
-        const luts_byte_size = Math.max(4, (packed_luts.byteLength + 3) & ~3);
+        const luts_byte_size = Math.max(4, align_4(packed_luts.byteLength));
         this.#luts_buffer = this.#device.createBuffer({
             label: "NSS / LUTs (packed int8)",
             size: luts_byte_size,

package/src/shade/renderer/postprocess/nss/generate_NSS_WEIGHTS_ACTUAL.js

@@ -45,6 +45,7 @@
 // Then they sum naturally with fp_acc before the rescale.
 
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { align_4 } from "../../../../core/binary/align_4.js";
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -233,8 +234,8 @@ for (const r of records) {
     total_rescale_floats += r.rescales_f32.length;
     if (r.lut_int8 !== null) total_lut_bytes += r.lut_int8.length;
 }
-const aligned_weight_bytes = (total_weight_bytes + 3) & ~3;
-const aligned_lut_bytes = (total_lut_bytes + 3) & ~3;
+const aligned_weight_bytes = align_4(total_weight_bytes);
+const aligned_lut_bytes = align_4(total_lut_bytes);
 
 // Activation enum (mirrors NSS_LAYER_CONFIG_STRUCT.js)
 const ACT = { identity: 0, relu: 1, leaky_relu: 2 };

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A source of transparent fragments that is not a meshlet bucket, drawn through the AVBOIT pipeline
+ * alongside the transparent meshes: particles today, anything quad- or point-shaped tomorrow.
+ *
+ * The orchestrator (`graph_rasterize_meshes_transparent_avboit`) collects three things from every
+ * transparent surface in the frame, in this order, and a side channel is asked for each at the
+ * point where the meshlet buckets have just contributed theirs:
+ *
+ * 1. **occupancy** — which virtual depth slices the channel's fragments can land in, OR-ed into the
+ *    occupancy bits before the warp is built. Conservative bounds are fine; a fragment outside the
+ *    slices its channel marked lands on the boundary of the nearest run rather than anywhere wrong,
+ *    but marking what will be splatted is what keeps it sharp.
+ * 2. **splat** — each fragment's RGB extinction, added into the voxel volume at the volume's
+ *    resolution, through `avboit_splat_slice`, after the meshlets' extinction is in.
+ * 3. **draw** — each fragment's shaded contribution into the four accumulators
+ *    (`avboit_draw_fragment_body`), at internal resolution, depth-tested against the opaque scene,
+ *    after the meshlets have drawn.
+ *
+ * The integrate and resolve passes see no difference between a meshlet's fragment and a channel's:
+ * a channel that follows the three contracts below composites exactly as a transparent mesh does,
+ * order-independently, against it and against every other channel.
+ *
+ * Every method takes the frame graph and the handles the orchestrator currently holds, and returns
+ * the handles the next reader must take — the frame-graph threading rule, unchanged. A channel with
+ * nothing to add returns what it was given.
+ */
+export type AVBOITSideChannel = {
+    /**
+     * add the channel's slices to the occupancy bits; returns the bits'
+     * handle after the write. `cluster_parameters` is the frame's depth curve (`avboit_build_depth_curve`).
+     */
+    avboit_occupancy: (args: {
+        graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        camera: number;
+        cluster_parameters: ArrayLike<number>;
+        occupancy: number;
+    }) => number;
+    /**
+     * add the channel's
+     * extinction to the volume; returns the volume's handles after the write. `depth_texture` is
+     * the opaque scene's depth, for a channel whose coverage depends on it — whatever it records
+     * here has to be the coverage its draw weights the accumulators by, or the volume occludes
+     * with a surface the accumulators never drew.
+     */
+    avboit_splat: (args: {
+        graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        camera: number;
+        warp: number;
+        depth_texture: number;
+        voxel_resolution: number[];
+        volume: {
+            extinction: number;
+            overflow: number;
+            dummy: number;
+        };
+    }) => {
+        extinction: number;
+        overflow: number;
+        dummy: number;
+    };
+    /**
+     * draw the
+     * channel's fragments into the accumulators; returns their handles after the draw.
+     */
+    avboit_draw: (args: {
+        graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        view_ctx: import("../../../view/GPUViewContext.js").GPUViewContext;
+        camera: number;
+        depth_texture: number;
+        warp: number;
+        integral: number;
+        volumetrics_lut: number;
+        volumetrics_metadata: number;
+        accumulators: {
+            color: number;
+            norm: number;
+            extinction: number;
+            emission: number;
+        };
+    }) => {
+        color: number;
+        norm: number;
+        extinction: number;
+        emission: number;
+    };
+};
+//# sourceMappingURL=AVBOITSideChannel.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AVBOITSideChannel.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BA2BqB;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,kBAAwB,EAAE,UAAU,MAAM,CAAC,CAAC;QAC5C,SAAe,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM;;;;;;;;yBAEM;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,MAAY,EAAE,MAAM,CAAC;QACrB,IAAU,EAAE,MAAM,CAAC;QACnB,aAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,MAAY,EAAE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,CAAC;KACjE,KAAK;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;;;;;wBAKzC;QACpB,KAAW,EAAE,OAAO,iEAAiE,EAAE,UAAU,CAAC;QAClG,QAAc,EAAE,OAAO,iCAAiC,EAAE,cAAc,CAAC;QACzE,MAAY,EAAE,MAAM,CAAC;QACrB,aAAmB,EAAE,MAAM,CAAC;QAC5B,IAAU,EAAE,MAAM,CAAC;QACnB,QAAc,EAAE,MAAM,CAAC;QACvB,eAAqB,EAAE,MAAM,CAAC;QAC9B,oBAA0B,EAAE,MAAM,CAAC;QACnC,YAAkB,EAAE;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC,CAAC;KACrF,KAAK;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC"}

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js

@@ -0,0 +1,61 @@
+/**
+ * A source of transparent fragments that is not a meshlet bucket, drawn through the AVBOIT pipeline
+ * alongside the transparent meshes: particles today, anything quad- or point-shaped tomorrow.
+ *
+ * The orchestrator (`graph_rasterize_meshes_transparent_avboit`) collects three things from every
+ * transparent surface in the frame, in this order, and a side channel is asked for each at the
+ * point where the meshlet buckets have just contributed theirs:
+ *
+ * 1. **occupancy** — which virtual depth slices the channel's fragments can land in, OR-ed into the
+ *    occupancy bits before the warp is built. Conservative bounds are fine; a fragment outside the
+ *    slices its channel marked lands on the boundary of the nearest run rather than anywhere wrong,
+ *    but marking what will be splatted is what keeps it sharp.
+ * 2. **splat** — each fragment's RGB extinction, added into the voxel volume at the volume's
+ *    resolution, through `avboit_splat_slice`, after the meshlets' extinction is in.
+ * 3. **draw** — each fragment's shaded contribution into the four accumulators
+ *    (`avboit_draw_fragment_body`), at internal resolution, depth-tested against the opaque scene,
+ *    after the meshlets have drawn.
+ *
+ * The integrate and resolve passes see no difference between a meshlet's fragment and a channel's:
+ * a channel that follows the three contracts below composites exactly as a transparent mesh does,
+ * order-independently, against it and against every other channel.
+ *
+ * Every method takes the frame graph and the handles the orchestrator currently holds, and returns
+ * the handles the next reader must take — the frame-graph threading rule, unchanged. A channel with
+ * nothing to add returns what it was given.
+ *
+ * @typedef {object} AVBOITSideChannel
+ * @property {(args: {
+ *     graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph,
+ *     camera: number,
+ *     cluster_parameters: ArrayLike<number>,
+ *     occupancy: number,
+ * }) => number} avboit_occupancy add the channel's slices to the occupancy bits; returns the bits'
+ *     handle after the write. `cluster_parameters` is the frame's depth curve (`avboit_build_depth_curve`).
+ * @property {(args: {
+ *     graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph,
+ *     camera: number,
+ *     warp: number,
+ *     depth_texture: number,
+ *     voxel_resolution: number[],
+ *     volume: {extinction: number, overflow: number, dummy: number},
+ * }) => {extinction: number, overflow: number, dummy: number}} avboit_splat add the channel's
+ *     extinction to the volume; returns the volume's handles after the write. `depth_texture` is
+ *     the opaque scene's depth, for a channel whose coverage depends on it — whatever it records
+ *     here has to be the coverage its draw weights the accumulators by, or the volume occludes
+ *     with a surface the accumulators never drew.
+ * @property {(args: {
+ *     graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph,
+ *     view_ctx: import("../../../view/GPUViewContext.js").GPUViewContext,
+ *     camera: number,
+ *     depth_texture: number,
+ *     warp: number,
+ *     integral: number,
+ *     volumetrics_lut: number,
+ *     volumetrics_metadata: number,
+ *     accumulators: {color: number, norm: number, extinction: number, emission: number},
+ * }) => {color: number, norm: number, extinction: number, emission: number}} avboit_draw draw the
+ *     channel's fragments into the accumulators; returns their handles after the draw.
+ */
+
+export {};

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_LEDGER.md

@@ -461,3 +461,182 @@ counterpart in `shader/chunk/math/`.
 
 **Verified.** Every spec in `rasterize/` (the avboit directory's now-larger set, MBOIT's, the shared
 bucket code) and the type check.
+
+## 19. Side channels, and particles as the first one — 2026-09-04
+
+Alex: *"let's widen out AVBOIT so we can put particle render in there, that's where particles should
+go. Make sure the extension is clean. No need to bother with MBOIT, it's going to be deprecated...
+I don't think packing particle quads into meshlets is the way to go, so likely a side channel."*
+
+**The seam.** `AVBOITSideChannel.js` is a JSDoc contract, no base class: three methods, called by
+the orchestrator at the three points where the meshlet buckets have just contributed theirs —
+`avboit_occupancy` before the warp is built, `avboit_splat` before integrate, `avboit_draw` before
+resolve. Each takes the handles the orchestrator holds and returns the handles the next reader must
+take, which is the frame graph's own threading rule and nothing new. The orchestrator gained one
+parameter, `side_channels = []`, and one changed condition: it used to return early when no
+transparent material had meshlets, and now returns early only if there are also no channels.
+Integrate and resolve were not touched — they cannot tell a channel's fragment from a meshlet's,
+which is the property that makes this a seam rather than a special case.
+
+**The fourth accumulator.** An additive fragment covers nothing: it writes zero extinction and zero
+norm, so the resolve's renormalization — `(1 - T_total) / Σnorm`, which redistributes exactly the
+light the covering surfaces took from the scene — must not scale it. It cannot share the `color`
+accumulator for that reason. So `emission` joins as a fourth target, added to the resolve outside
+the normalization, holding light the draw already attenuated by the transmittance in front of it.
+The cost is honest and paid whether or not a channel is present: one more `rgba16float` at internal
+resolution, and every transparent mesh fragment writing `vec4(0)` to it. Buying it back would mean a
+three-target draw pipeline beside the four-target one — a variant, which the house rule and the
+plan's §5 both refuse — or a post-resolve additive pass with its own pipeline and bind group. One
+target is the cheaper of the three.
+
+**Shared, not copied.** The splat's voxel write (the two-slice linear split, the overflow mark) came
+out of the meshlet splat into `chunk_avboit_splat_slice`, so the particle splat writes the volume
+through the same code, not a second implementation of it. On the particle side the billboard vertex
+stage came out of the standalone renderer into `chunk_particle_billboard_vertex`, shared by three
+pipelines, and the emitter's world bounds sphere into `chunk_particle_emitter_world_sphere`, shared
+by the tick's frustum cull and the new occupancy.
+
+**What the review found.** Four things, all fixed here:
+
+- *A binding that lied.* The shared vertex chunk read its slot list from a binding named `sorted`.
+  The standalone path binds the depth-sorted list there; the AVBOIT passes bind the alive list,
+  because the volume makes order irrelevant and the sort does not run on that path. Renamed
+  `draw_list` in the chunk and all three pipelines: which list it is, is the caller's choice.
+- *Bounds with new teeth.* The occupancy is per emitter, from the bounds sphere — the field that
+  until now only fed the optional simulation culling and that an emitter not opting in could leave
+  at its default. A particle outside it still draws, but its extinction lands in whatever physical
+  slice the warp put nearest, so it occludes at slightly the wrong depth. Documented on the field
+  and in the particle design, because it is now a rendering input.
+- *One simulation per view.* `simulate` steps the system and hands out handles into the graph it
+  recorded into, so two views of one scene would step it twice. The renderer has one view per
+  `render` call, so it holds today; the fix when that changes is to separate the step from the
+  import. Documented on the method rather than built speculatively.
+- *A teardown that leaked.* `Renderer.destroy` did not destroy the particle systems it creates per
+  scene context. It does now.
+
+**Checked and found sound.** The volume and the accumulators are always created by the meshlet
+passes before a channel is asked, even at zero materials, so a particles-only frame has them; the
+splat's dummy attachment is cleared by the meshlet splat before the particle splat loads it; passes
+that write imported buffers are marked as side effects by `FramePassBuilder`, so the simulation
+still advances in a frame whose transparency pass is off; a fresh `FrameGraph` per frame makes the
+"simulated into this graph" assertion catch a stale handle set loudly; and the depth texture is
+bound as a read-only attachment and a sampled texture in the same pass, which WebGPU allows and the
+soft fade needs.
+
+**Under MBOIT.** Particles simulate and do not draw. MBOIT is the legacy path and gets no new
+sources; `Renderer.feature_particles_enabled` says so where a reader will hit it.
+
+**Verified.** Tiers 1–3: the WGSL validity spec (the three new pipelines parse, validate, and stay
+inside the eight-storage-buffer budget), the occupancy pass on the emulator against the depth
+curve's own arithmetic, the three graph passes on the software device (pass order, attachments,
+indirect draws, the read-only depth), the orchestrator's call order and the renderer's wiring, and
+the whole engine suite — 2321 files, 16119 tests — plus the type check. Not verified: any of it on a
+device. The Browser pane handed out no WebGPU adapter this session, so even the real Tint compile
+that ledger 18's review leaned on is still owed for these three shaders.
+
+## 20. Adversarial review of the side channel — 2026-09-04
+
+Alex ran the playground, said it works, and asked for an adversarial review. A picture that looks
+right is weak evidence for this pipeline: every defect below survives one, because each is either
+a second copy of something small, a disagreement between two passes about the same fragment, or a
+path the scene on screen does not take.
+
+**What the volume and the accumulators disagreed about.** The pipeline's whole contract is that the
+extinction the splat records is the coverage the draw weights its accumulators by
+(`avboit_draw_fragment_body`'s own header says so). Two fragments broke it:
+
+- *The soft fade.* The draw faded a particle's alpha against the scene depth; the splat had no depth
+  binding at all and recorded the unfaded coverage. A smoke card fading out where it meets the floor
+  drew nothing there and still wrote full extinction, so the floor was darkened through a card that
+  was invisible — the seam soft particles exist to remove, one layer down. The splat now samples the
+  same depth (one texel per voxel) and applies the same fade, through
+  `chunk_particle_scene_view_depth`, which the draw took its inline copy of the linearization from.
+  `avboit_splat` therefore takes `depth_texture` — the one contract change.
+- *Additive and the fog.* The draw composited volumetric in-scatter into every fragment and then put
+  additive ones in `emission`, which the resolve adds *outside* the normalization. The scene behind
+  already carries that in-scatter, and nothing subtracts it: a hundred overlapping sparks added a
+  hundred copies of the fog. An emitting fragment is now dimmed by the fog's transmittance and
+  carries none of its light; a covering one still re-adds it, weighted by the coverage it took,
+  because it hides the part of the scene it owes it to.
+
+**Two more in the same fragment.** `PREMULTIPLIED` with zero alpha is the engine's other spelling of
+additive — the billboard pipeline blends it that way — and the draw branched on the blend enum, so
+such a sprite was treated as covering, written to `color` with zero `norm`, and multiplied by a
+normalization of zero: it disappeared. The routing is on coverage now, which is what the splat
+already used, so the two agree by construction. And the coverage ceiling was applied to `norm` and
+`extinction` but not to `color`, unbounded above (a curve can drive alpha past 1) and unguarded
+below (a negative alpha made a negative extinction, and `exp(-sum)` then brightened the scene).
+
+All four are pinned on the emulator: the fragment's decision came out into
+`chunk_particle_avboit_contribution` as its own no-behaviour-change step, then nine tests, four of
+them red against the old code.
+
+**Teardown.** `destroy()` freed the buffers and left every emitter node holding a row of the table it
+had just freed. A renderer rebuilt after a device loss makes a fresh system whose membership sweep
+reads `row !== -1` as "already mine", takes the moved branch rather than the arrived one, and never
+registers the emitter: it stops emitting for good. It retires them now. The default 1×1 atlas was
+also unreachable — only its view was kept — and is held and freed.
+
+**The orchestrator can be run at tier 3 after all.** This file said it could not: it needs a view
+context over meshlet geometry no spec builds. That is true of a frame *with transparent meshes* —
+and the path side channels added is the other one. A scene with no transparent materials and one
+channel reaches for no geometry, so the whole orchestrator now runs on the mock, and the ordering
+contract and the handle threading are pinned from the outside instead of by reading the source for
+call order. The mock gained `indirect-first-instance` for it, on the argument its own header already
+makes for `subgroups`: it permits a field in an indirect draw the mock never reads, issuing a draw it
+never runs, and refusing it left the transparency orchestration untestable for a reason unrelated to
+what the tier asserts.
+
+**Found and left alone, on purpose:**
+
+- *The occupancy marks every emitter*, with no frustum test and no liveness test, where the meshlet
+  occupancy dispatches over the HZB-filtered collection. An idle or off-screen emitter still reserves
+  its depth run, and the warp then fits more occupied virtual slices into the same 128 physical ones.
+  It costs precision, never correctness. A frustum test is the obvious fix and belongs with a scene
+  that shows the cost.
+- *The occupancy sphere bounds particle centres*, not the quads' own depth extent, which for a
+  stretched or world-oriented particle reaches a size (or more) past the centre. Documented on
+  `ParticleEmitter.bounds_radius` rather than inflated by a guess.
+- *Particles have no motion vectors.* The transparency composite happens before TAA, so a fast spark
+  is reprojected with the background's motion and ghosts. Transparent meshes have had this property
+  since before AVBOIT; particles make it easier to see. The playground has a TAA switch.
+- *One system per scene context is never released*, mirroring `SceneManager`'s own map. A per-scene
+  release path is a design addition, not a fix.
+- *`simulate` steps once per view*, so two views of one scene would step it twice. Documented on the
+  method; the renderer has one view per `render` call today.
+
+**Verified.** The whole engine suite and the type check at budget. The playground page was loaded
+from the dev server again — import graph, WASM meshlet build, scene, camera controller under a
+synthetic drag, and every control handler including the two error paths added here. Still no adapter
+in the Browser pane, so still no picture and still no real Tint compile.
+
+## 21. What the device caught and the review did not — 2026-09-04
+
+Alex ran entry 20's work and got:
+
+```
+Binding entry textureView not set.
+ - While validating entries[6] against { binding: 6, ..., texture: {sampleType: UnfilterableFloat, ...} }
+ - While encoding [RenderPassEncoder "Particle AVBOIT Splat"].SetBindGroup(0, ...)
+```
+
+Entry 20 added `scene_depth` to the splat's bindings between the atlas and its sampler, and added
+the depth view to the *end* of the positional array the pass hands to `BindGroupDescriptor.from`.
+Everything after the insertion point slid along by one: binding 6 wanted a texture and got the
+sampler. Nothing on this side of the device could see it. The frame graph does not know what a
+binding means, the mock does not validate an entry against its layout, and both of entry 20's new
+tests looked for the depth view's *presence* in the group rather than its position.
+
+The fix is not the index. Both particle render passes now build their bindings by name, through
+`ShaderResourceSetDescriptor#generateBindings` — the path the standalone billboard pass already
+used, and the reason it never had this bug — so the order a shader declares its bindings in is the
+shader's own business and nothing here mirrors it. `constructRenderPass` sets the pipeline and every
+group from that, which also took the manual `setBindGroup` calls out.
+
+And the tier that missed it can see it now: `expect_bindings_match_layout` walks a recorded pass and
+asserts every entry is the *kind* — buffer, texture or sampler — its pipeline layout declares at that
+binding. It fails against the shipped code. That check is worth copying to any pass built by hand.
+
+**The lesson for this directory:** a positional bind-entry list is a latent version of this defect in
+every pass that has one, and it surfaces only on hardware, only when that pass first encodes. The
+meshlet passes here still build theirs positionally.