@woosh/meep-engine 3.14.4 → 3.14.6

package/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.d.ts

@@ -3,9 +3,27 @@
  * to fill an existing instance (e.g. a subclass of `MeshletGeometry`)
  * in place; otherwise a fresh instance is created and returned.
  *
+ * **This is synchronous, single-threaded, and it is not cheap — so at load time it belongs
+ * OFFLINE, not on the frame loop.** Measured converting one level's meshes: 3.3k triangles across
+ * 23 meshes took 53 ms, 7.5k across 30 took 74 ms, and **199k across 45 took 1,246 ms** — an
+ * unbroken second and a quarter of main thread, scaling linearly, on a level that is small.
+ * Reported from a port as GAP-008.
+ *
+ * **The offline route already exists and is the intended pipeline.**
+ * {@link MeshletGeometrySerializationAdapter} round-trips a `MeshletGeometry` to and from a
+ * `BinaryBuffer` losslessly, so an asset build can call this once, serialize the result beside the
+ * source mesh, and leave the runtime with a deserialize and an upload. Nothing about this function
+ * needs to run in a browser. If you are calling it from a level loader, that is the thing to change
+ * first — before reaching for a worker, which only moves the cost.
+ *
+ * A pooled worker-backed geometry service, with meshlet construction as one of the things it
+ * serves, is where this is going; it is not here yet, and it would not remove the reason to build
+ * offline.
+ *
  * @param {Geometry} geometry
  * @param {MeshletGeometry} [out]
  * @returns {MeshletGeometry}
+ * @see MeshletGeometrySerializationAdapter for the offline format
  */
 export function meshlet_geometry_build_from_geometry(geometry: Geometry, out?: MeshletGeometry): MeshletGeometry;
 import { MeshletGeometry } from "./MeshletGeometry.js";

package/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meshlet_geometry_build_from_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,+EAHW,eAAe,GACb,eAAe,CAoC3B;gCA7C+B,sBAAsB"}
+{"version":3,"file":"meshlet_geometry_build_from_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+EAJW,eAAe,GACb,eAAe,CAqC3B;gCA/D+B,sBAAsB"}

package/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js

@@ -7,9 +7,27 @@ import { MeshletGeometry } from "./MeshletGeometry.js";
  * to fill an existing instance (e.g. a subclass of `MeshletGeometry`)
  * in place; otherwise a fresh instance is created and returned.
  *
+ * **This is synchronous, single-threaded, and it is not cheap — so at load time it belongs
+ * OFFLINE, not on the frame loop.** Measured converting one level's meshes: 3.3k triangles across
+ * 23 meshes took 53 ms, 7.5k across 30 took 74 ms, and **199k across 45 took 1,246 ms** — an
+ * unbroken second and a quarter of main thread, scaling linearly, on a level that is small.
+ * Reported from a port as GAP-008.
+ *
+ * **The offline route already exists and is the intended pipeline.**
+ * {@link MeshletGeometrySerializationAdapter} round-trips a `MeshletGeometry` to and from a
+ * `BinaryBuffer` losslessly, so an asset build can call this once, serialize the result beside the
+ * source mesh, and leave the runtime with a deserialize and an upload. Nothing about this function
+ * needs to run in a browser. If you are calling it from a level loader, that is the thing to change
+ * first — before reaching for a worker, which only moves the cost.
+ *
+ * A pooled worker-backed geometry service, with meshlet construction as one of the things it
+ * serves, is where this is going; it is not here yet, and it would not remove the reason to build
+ * offline.
+ *
  * @param {Geometry} geometry
  * @param {MeshletGeometry} [out]
  * @returns {MeshletGeometry}
+ * @see MeshletGeometrySerializationAdapter for the offline format
  */
 export function meshlet_geometry_build_from_geometry(geometry, out = new MeshletGeometry()) {
     assert.defined(geometry, 'geometry');

package/src/shade/renderer/global_illumination/lpv/LightProbeVolume.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../../../../core/geom/3d/aabb/AABB3.js").AABB3} AABB3
+ */
 export class LightProbeVolume {
     /**
      *
@@ -51,5 +54,6 @@ export class LightProbeVolume {
     }): void;
     #private;
 }
+export type AABB3 = import("../../../../core/geom/3d/aabb/AABB3.js").AABB3;
 import { TetrahedralMesh } from "../../../../core/geom/3d/tetrahedra/TetrahedralMesh.js";
 //# sourceMappingURL=LightProbeVolume.d.ts.map

package/src/shade/renderer/global_illumination/lpv/LightProbeVolume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LightProbeVolume.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/lpv/LightProbeVolume.js"],"names":[],"mappings":"AASA;IASI;;;OAGG;IACH,iCAEC;IAKD;;;OAGG;IACH,4BAEC;IAUD,iCAMC;IAdD;;;OAGG;IACH,8BAEC;IAUD;;;OAGG;IACH,0BAEC;IAID;;;OAGG;IACH,sBAEC;IAED,eAEC;IAED;;;;;OAKG;IACH,aAJW,MAAM,KACN,MAAM,KACN,MAAM,UAehB;IAED;;;OAGG;IACH,oBAFW,MAAM,QAiBhB;IAuBD,mBAUC;IAED;;;;OAIG;IACH,sCAFW,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAA;KAAC,QAchD;;CACJ;gCAjK+B,wDAAwD"}
+{"version":3,"file":"LightProbeVolume.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/lpv/LightProbeVolume.js"],"names":[],"mappings":"AAUA;;GAEG;AACH;IASI;;;OAGG;IACH,iCAEC;IAKD;;;OAGG;IACH,4BAEC;IAUD,iCAMC;IAdD;;;OAGG;IACH,8BAEC;IAUD;;;OAGG;IACH,0BAEC;IAID;;;OAGG;IACH,sBAEC;IAED,eAEC;IAED;;;;;OAKG;IACH,aAJW,MAAM,KACN,MAAM,KACN,MAAM,UAehB;IAED;;;OAGG;IACH,oBAFW,MAAM,QAiBhB;IAuBD,mBAUC;IAED;;;;OAIG;IACH,mBAHW,KAAK,cACL,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAC,CAAC,EAAC,MAAM,CAAA;KAAC,QAchD;;CACJ;oBAjKY,OAAO,wCAAwC,EAAE,KAAK;gCAJnC,wDAAwD"}

package/src/shade/renderer/global_illumination/lpv/LightProbeVolume.js

@@ -7,6 +7,10 @@ import {
 } from "../../../../core/geom/3d/tetrahedra/delaunay/grid/tetrahedral_mesh_build_from_grid.js";
 import { TetrahedralMesh } from "../../../../core/geom/3d/tetrahedra/TetrahedralMesh.js";
 
+
+/**
+ * @typedef {import("../../../../core/geom/3d/aabb/AABB3.js").AABB3} AABB3
+ */
 export class LightProbeVolume {
     #mesh = new TetrahedralMesh();
     #positions = new Float32Array(0);

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.d.ts

@@ -4,6 +4,18 @@
  * @type {number}
  */
 export const PREFIX_SCAN_CSDLDF_PARTITION_SIZE: number;
+/**
+ * `u32` words of header that sit in front of the scanned elements.
+ *
+ * The scan reads its element count from word 0 and its `elements` member is `@align(16)`, so the
+ * first element lands at word 4 and words 1..3 are padding the scan never reads. A caller that
+ * binds the same buffer flat as an `array<u32>` — every producer of a histogram this scan consumes
+ * does — has to step over the header by hand, and this is the number to step by. Derived from the
+ * struct so the two cannot drift apart.
+ *
+ * @type {number}
+ */
+export const PREFIX_SCAN_CSDLDF_HEADER_WORDS: number;
 /**
  * Chained Scan with Decoupled Lookback Decoupled Fallback
  * @see https://escholarship.org/content/qt0bk9z4bt/qt0bk9z4bt.pdf

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,gDAFU,MAAM,CAEsC;AA+StD;;;;;GAKG;AACH,wCAFU,aAAa,CAMpB;8BAjU2B,kCAAkC"}
+{"version":3,"file":"shader_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,gDAFU,MAAM,CAEsC;AAOtD;;;;;;;;;;GAUG;AACH,8CAFU,MAAM,CAE6E;AA0S7F;;;;;GAKG;AACH,wCAFU,aAAa,CAMpB;8BA9U2B,kCAAkC"}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js

@@ -19,6 +19,19 @@ const DATA_STRUCT = WebGPUStruct.from({
     elements: WebGPUArray.from(vec4u),
 });
 
+/**
+ * `u32` words of header that sit in front of the scanned elements.
+ *
+ * The scan reads its element count from word 0 and its `elements` member is `@align(16)`, so the
+ * first element lands at word 4 and words 1..3 are padding the scan never reads. A caller that
+ * binds the same buffer flat as an `array<u32>` — every producer of a histogram this scan consumes
+ * does — has to step over the header by hand, and this is the number to step by. Derived from the
+ * struct so the two cannot drift apart.
+ *
+ * @type {number}
+ */
+export const PREFIX_SCAN_CSDLDF_HEADER_WORDS = DATA_STRUCT.get("elements").offset / u32.size;
+
 const resources = new ShaderResourceSetDescriptor();
 resources.createGroup()
     .addStorageBuffer("scan_in", DATA_STRUCT, true)

package/src/shade/renderer/light/environment/rgbe/parse_rgbe.d.ts

@@ -8,7 +8,7 @@
 export function parse_rgbe(buffer: ArrayBuffer, type?: BinaryDataType.Float16 | BinaryDataType.Float32): {
     width: number;
     height: number;
-    data: Uint16Array | Float32Array;
+    data: Float32Array | Uint16Array;
     header: string;
     gamma: number;
     exposure: number;

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#221@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#222@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/particles/DESIGN.md

@@ -25,7 +25,7 @@ node graphs and lowered to that bytecode by a testable JS compiler.
 ## Layered architecture
 
 ```
-authoring:   ParticleGraph (nodes+ports)  ──compile──▶  Program (bytecode)
+authoring:   NodeGraph (nodes+ports)      ──compile──▶  Program (bytecode)
              standard node library                       │
                                                          ▼
 runtime CPU: EmitterDefinition ── GPUDatabase(emitters) ─┤  ProgramArena (packed u32 buffer)
@@ -35,6 +35,7 @@ runtime GPU: particle pool (array<u32>, uniform stride) + alive/dead lists + cou
              ┌─ resolve emitter transforms (bone attach)
              ├─ emit  (VM SPAWN program)   ── pop dead → init → append alive_new
              ├─ simulate (VM UPDATE program) ── update → (kill→dead | keep→alive_new + depth key)
+             ├─ bucket (histogram → csdldf scan → scatter)  ── alive → program-coherent sim list
              ├─ compact/indirect-args
              ├─ sort  (radix: histogram → csdldf scan → scatter)   [transparent]
              └─ render (instanced billboard quads, forward + optional lighting + soft depth)
@@ -52,14 +53,16 @@ Lifecycle uses the canonical GPU dead-list / alive-list ping-pong:
 - `alive_list[2]`: ping-pong compact lists of live slot indices (+ counts).
 - `counters`: atomics {alive_count, dead_count, spawn cursor…} + derived indirect dispatch/draw args.
 
-Emit: pop dead → run SPAWN → append `alive_new`. Simulate: read `alive_current` → run UPDATE →
-kill pushes to `dead`, survival appends to `alive_new` and writes a depth sort key. Swap lists each
-frame.
+Emit: pop dead → run SPAWN → append `alive_new`. Simulate: read the **coherence list** last frame's
+bucketing pass built from `alive_current` → run UPDATE → kill pushes to `dead`, survival appends to
+`alive_new` and writes a depth sort key. Swap lists each frame.
 
-**The loop is strictly GPU-driven.** The build-indirect pass snapshots the frame's final alive count
-into `counters[ALIVE_IN]` and writes the indirect dispatch args next frame's simulate consumes
-(`dispatchWorkgroupsIndirect`) plus the indirect draw args this frame's render consumes
-(`drawIndirect`); simulate bound-checks against the ALIVE_IN snapshot. Sizing any of this from a CPU
+**The loop is strictly GPU-driven.** The build-indirect pass snapshots the padded length of the
+coherence list into `counters[ALIVE_IN]` and writes the indirect dispatch args next frame's simulate
+consumes (`dispatchWorkgroupsIndirect`) plus the indirect draw args this frame's render consumes
+(`drawIndirect`, sized by the *unpadded* alive count); simulate bound-checks against the ALIVE_IN
+snapshot. Because both come from one value and a padded length is a whole number of workgroups, the
+dispatch's thread count and the shader's bound agree exactly. Sizing any of this from a CPU
 readback is a correctness bug, not a shortcut: the readback is inevitably stale, so a growing
 population orphans the tail of the alive list (slots leak into limbo) and a shrinking one
 re-simulates stale entries — double-freeing slots so two live particles later share one record. The
@@ -90,7 +93,7 @@ executors cover every opcode in the ISA table.
 
 ### Node graph → bytecode
 
-`ParticleGraph` holds typed nodes (ports + params) for SPAWN and UPDATE. `compile()`:
+A core `NodeGraph` holds particle nodes (ports + parameters) for SPAWN and UPDATE. `compile()`:
 1. topologically orders reachable nodes,
 2. lowers each node to VM ops (nodes emit via a small builder that allocates result registers),
 3. linear-scan register allocation with liveness,
@@ -117,11 +120,45 @@ time; on wake, spawn-count is caught up (bounded steps, like meep's `ParticularE
 attached to a bone read `node.global` from the scene transforms table (GPU-side) each frame to derive
 their world transform, after `graph_scene_update_transform_hierarchy` has run.
 
-### Sorting
-
-Per-frame, transparent emitters' particles are sorted back-to-front by view depth. LSD radix sort on
-a 32-bit key (quantized view depth): per digit — build histogram, `graph_prefix_scan_csdldf` the bin
-counts to offsets, scatter (index payload). Sorted index list feeds the instanced draw.
+### Two orderings, and why they are separate
+
+There are two independent permutations of the live particles each frame. They are produced by
+different passes into different buffers and must not be conflated or derived from one another.
+
+**Simulation order** (`coherence/`) — camera-independent, changes only when emitters or their
+programs change. The alive list comes out of compaction (`atomicAdd(&counters[ALIVE])`), so its
+order says nothing about which emitter a particle belongs to and a wave routinely holds particles
+running different VM programs. That costs twice: the interpreter's ~40-case opcode `switch`
+diverges, so a wave serially executes the union of the opcodes its lanes want; and `vm_reg[dst]` /
+`vm_reg[s0]` index a VGPR-resident register file dynamically, which AMD reaches with
+`v_movrels`/`v_movreld` behind a waterfall loop whose trip count is the number of *distinct*
+register indices live in the wave. Grouping the wave by program collapses both at once.
+
+The bucket key is the **program**, not the emitter: `ProgramArena` deduplicates by content and hands
+back a dense `program_id` the emitter record carries, so emitters compiled from the same graph share
+one bucket. Each bucket is padded out to `PARTICLE_SIMULATE_WORKGROUP_SIZE` (64 — a multiple of both
+plausible subgroup widths, so no shader needs to query `subgroup_size`), which is what makes the
+grouping hold at wave granularity: an unpadded boundary lands mid-wave and that wave spans two
+programs again. Padding entries carry `PARTICLE_SIM_PAD_SLOT` and the simulate shader drops them
+*before* the compaction atomics, so they never enter the alive or dead list.
+
+It is an **indirection** list. Particle records never move: slots are referenced by the dead list and
+across frames, so relocating a record would leave both pointing at the wrong particle.
+
+The three-phase shape is the depth sort's, with the padding added: histogram (atomic per bucket) →
+round each bin up to a whole workgroup → `graph_prefix_scan_csdldf` (reused as-is — the one scan here
+whose only cross-workgroup wait is CSDLDF's bounded spin-then-fallback) → scatter → fill the tails
+with the sentinel. Nothing reads back to the CPU; the only host-supplied number is the bucket count,
+which is static topology.
+
+**Render order** (`sort/`) — per-frame, transparent emitters' particles sorted back-to-front by view
+depth so premultiplied transparency composites correctly. LSD radix sort on a 32-bit key (quantized
+view depth): per digit — build histogram, `graph_prefix_scan_csdldf` the bin counts to offsets,
+scatter (index payload). Sorted index list feeds the instanced draw.
+
+Reordering the render list for program coherence would break transparency; depth-sorting the
+simulation list would destroy the coherence. They share no buffer and no counter slot —
+`PARTICLE_COUNTER.SORTED` belongs to the render order, `SIM_PADDED` to the simulation order.
 
 ### Rendering
 
@@ -143,12 +180,15 @@ src/webgpu/renderer/particles/
   isa/ParticleAssembler.js           tiny assembler (build programs in tests/library)
   vm/ParticleVMReference.js          JS reference executor
   vm/chunk_particle_vm.js            WGSL interpreter CodeChunk (parity target)
-  graph/ParticleGraph.js             node graph
-  graph/ParticleNode.js              node base + ports
-  graph/nodes/*                      standard node library
+  graph/ParticleNodeDescription.js   node type base (ports + lowering)
+  graph/ParticleNodeRegistry.js      standard node library (a NodeRegistry)
+  graph/particle_graph_authoring.js  authoring sugar over core/model/node-graph
   graph/compile_particle_graph.js    graph → Program (register alloc, const intern)
   layout/ParticleLayout.js           attribute schema ↔ record word offsets
   data/*_STRUCT.js                   EMITTER_STRUCT, counters, render binding, sort key
+  coherence/particle_program_buckets.js  CPU reference for the simulation-order bucketing
+  coherence/shader_particle_bucket.js    reset / histogram / pad / scatter / fill
+  coherence/graph_particle_bucket.js     frame-graph wiring, around graph_prefix_scan_csdldf
   runtime/ParticlePool.js            pool + alive/dead lists + counters (buffers)
   runtime/ProgramArena.js            packed program+const buffer
   runtime/ParticleAtlas.js           sprite atlas texture + region table
@@ -186,6 +226,13 @@ Built and tested (80 tests, 16 files):
 - **Runtime** — ProgramArena, EmitterRegistry, ParticleSpawnScheduler (sleep-when-culled), the
   GPUParticleSystem CPU model (bone-attach transform patching, free list, ping-pong).
 - **Sort** — counting sort reference + histogram/scatter shaders bracketing `graph_prefix_scan_csdldf`.
+- **Coherence** — CPU reference plus the five bucketing shaders, on the emulator and validated as
+  WGSL; the whole chain is run end to end against the reference, pinning that bucket boundaries land
+  on multiples of 64, that no workgroup of the result spans two programs, and that every input slot
+  survives exactly once. Orchestration is pinned twice on `SoftwareGPUDevice`: `graph_particles.spec`
+  records the real frame graph (pass order, indirect sizing, the two orderings in separate buffers,
+  and every persistent buffer imported exactly once — two imports of one buffer are two resource
+  entries the graph cannot tell apart), and the playground spec covers the hand-encoded equivalent.
 - **Render math** — billboard modes, atlas/flipbook UV, soft fade, premultiplied blend.
 - **Finalize** — reset + build-indirect passes.
 - **Culling** — frustum sphere test.
@@ -197,11 +244,15 @@ the **prototype** effects.
 
 ### Emulator caveats discovered (all correct on real hardware)
 
-The in-repo WGSL emulator (unit-test tool, not GPU parity) has three limitations the shaders are
+The in-repo WGSL emulator (unit-test tool, not GPU parity) has four limitations the shaders are
 written around, documented in the memory note: `switch` case bodies are dropped (use if/else);
 repeated read-modify-write of one location across a loop is corrupted (RNG is verified in isolation,
-not through the interpreter loop); and u32 multiply is imprecise for large operands (PCG can't be
-checked through it). `array<atomic<u32>>` bindings are modeled as `{value}` objects in tests.
+not through the interpreter loop); u32 multiply is imprecise for large operands (PCG can't be
+checked through it); and `/` is FLOAT division, so integer division only truncates where the result
+is stored straight into a typed array — `(n + 63u) / 64u * 64u` reads as 66 there and 64 on a
+device. The coherence pass's round-up is a mask (`(n + 63u) & 0xffffffc0u`) for exactly that reason,
+and the fill pass splits its thread id with `>>` and `&` rather than `/` and `%`.
+`array<atomic<u32>>` bindings are modeled as `{value}` objects in tests.
 
 ### Renderer integration (remaining hook-up)
 

package/src/shade/renderer/particles/GPUParticleSystem.d.ts

@@ -12,11 +12,18 @@
  * 1. reset counters (snapshot the previous alive count as this frame's simulate input, zero the new
  *    alive count)
  * 2. emit — run SPAWN for each scheduled spawn request (pop dead -> init -> append alive)
- * 3. simulate — one dispatch runs every emitter's UPDATE over the previous alive list, compacting
- *    survivors into the new alive list and freed slots into the dead list
- * 4. build indirect — derive the render draw's instance count from the new alive count
- * 5. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
- * 6. render — one instanced billboard draw over the sorted list
+ * 3. simulate — one dispatch runs every emitter's UPDATE over the coherence list built last frame,
+ *    compacting survivors into the new alive list and freed slots into the dead list
+ * 4. bucket — regroup the new alive list by VM program, padded to whole workgroups, into the list
+ *    NEXT frame's simulate consumes (`coherence/`)
+ * 5. build indirect — derive next frame's simulate dispatch from the padded list length and this
+ *    frame's render draw instance count from the alive count
+ * 6. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
+ * 7. render — one instanced billboard draw over the sorted list
+ *
+ * Steps 4 and 6 are two different orderings of the same particles and share nothing: the
+ * simulation order is program-coherent and camera-independent, the render order is back-to-front
+ * and changes with the camera. Separate buffers, separate passes, separate counter slots.
  *
  * The alive lists ping-pong by frame parity, exactly like the ReSTIR reservoirs.
  *
@@ -49,6 +56,13 @@ export class GPUParticleSystem {
     /** CPU shadow of the packed emitter buffer (for in-place transform patching) */
     emitter_cpu: Uint32Array;
     emitters_dirty: boolean;
+    /**
+     * Distinct compiled programs across the emitter set — the number of buckets the coherence
+     * pass sorts into. Known only after {@link buildEmitterData}; until then the emitter count
+     * is a safe upper bound (programs can be shared, never invented).
+     * @type {number|undefined}
+     */
+    program_count: number | undefined;
     /**
      * Register an emitter.
      * @param {object} config see {@link EmitterRegistry#add}
@@ -82,6 +96,16 @@ export class GPUParticleSystem {
         program: Uint32Array;
         constants: Uint32Array;
     };
+    /**
+     * Number of simulation-order buckets — one per distinct compiled program.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when the emitter set changes, not as particles are born and die.
+     * Everything the pass measures per frame stays on the GPU.
+     *
+     * @returns {number}
+     */
+    bucketCount(): number;
     /**
      * Sizes of the persistent buffers, in bytes. Exposed for tests and allocation.
      * @returns {object}

package/src/shade/renderer/particles/GPUParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACI;;;;OAIG;IACH,sBAJW,MAAM;QAEW,QAAQ,GAAzB,MAAM;OAuBhB;IAjBG,cAAwB;IACxB,iBAAwB;IAExB,0BAAqC;IACrC,kCAA6C;IAE7C,gEAAgE;IAChE,aADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACF;IAE5B,qBAAqB;IACrB,OADW,MAAM,CACH;IAEd,mCAAmC;IACnC,aAAwB;IACxB,gFAAgF;IAChF,yBAA4B;IAC5B,wBAA0B;IAG9B;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,QACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,WALW,MAAM;oCAES,MAAM,KAAK,OAAO;QAC/B,WAAW,CAiBvB;IAED;;;OAGG;IACH,oBAFa;QAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,WAAW,CAAA;KAAC,CAOjF;IAED;;;OAGG;IACH,eAFa,MAAM,CAalB;IAED;;;OAGG;IACH;cAFoB,WAAW;kBAAY,WAAW;MAUrD;IAED;;;OAGG;IACH;cAFoB,MAAM;eAAS,MAAM;MAKxC;CACJ;gCA7J+B,8BAA8B;uCACvB,qCAAqC"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;IACI;;;;OAIG;IACH,sBAJW,MAAM;QAEW,QAAQ,GAAzB,MAAM;OA8BhB;IAxBG,cAAwB;IACxB,iBAAwB;IAExB,0BAAqC;IACrC,kCAA6C;IAE7C,gEAAgE;IAChE,aADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACF;IAE5B,qBAAqB;IACrB,OADW,MAAM,CACH;IAEd,mCAAmC;IACnC,aAAwB;IACxB,gFAAgF;IAChF,yBAA4B;IAC5B,wBAA0B;IAC1B;;;;;OAKG;IACH,eAFU,MAAM,GAAC,SAAS,CAEI;IAGlC;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,QACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,WALW,MAAM;oCAES,MAAM,KAAK,OAAO;QAC/B,WAAW,CAiBvB;IAED;;;OAGG;IACH,oBAFa;QAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,WAAW,CAAA;KAAC,CAQjF;IAED;;;;;;;;OAQG;IACH,eAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,eAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH;cAFoB,WAAW;kBAAY,WAAW;MAUrD;IAED;;;OAGG;IACH;cAFoB,MAAM;eAAS,MAAM;MAKxC;CACJ;gCA3M+B,8BAA8B;uCACvB,qCAAqC"}

package/src/shade/renderer/particles/GPUParticleSystem.js

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "./ParticleConstants.js";
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./ParticleConstants.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
 import { EMITTER_STRIDE, write_emitter_transform } from "./data/PARTICLE_EMITTER_LAYOUT.js";
 import { PARTICLE_COUNTER, PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
@@ -19,11 +20,18 @@ import { ParticleSpawnScheduler } from "./runtime/ParticleSpawnScheduler.js";
  * 1. reset counters (snapshot the previous alive count as this frame's simulate input, zero the new
  *    alive count)
  * 2. emit — run SPAWN for each scheduled spawn request (pop dead -> init -> append alive)
- * 3. simulate — one dispatch runs every emitter's UPDATE over the previous alive list, compacting
- *    survivors into the new alive list and freed slots into the dead list
- * 4. build indirect — derive the render draw's instance count from the new alive count
- * 5. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
- * 6. render — one instanced billboard draw over the sorted list
+ * 3. simulate — one dispatch runs every emitter's UPDATE over the coherence list built last frame,
+ *    compacting survivors into the new alive list and freed slots into the dead list
+ * 4. bucket — regroup the new alive list by VM program, padded to whole workgroups, into the list
+ *    NEXT frame's simulate consumes (`coherence/`)
+ * 5. build indirect — derive next frame's simulate dispatch from the padded list length and this
+ *    frame's render draw instance count from the alive count
+ * 6. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
+ * 7. render — one instanced billboard draw over the sorted list
+ *
+ * Steps 4 and 6 are two different orderings of the same particles and share nothing: the
+ * simulation order is program-coherent and camera-independent, the render order is back-to-front
+ * and changes with the camera. Separate buffers, separate passes, separate counter slots.
  *
  * The alive lists ping-pong by frame parity, exactly like the ReSTIR reservoirs.
  *
@@ -61,6 +69,13 @@ export class GPUParticleSystem {
         /** CPU shadow of the packed emitter buffer (for in-place transform patching) */
         this.emitter_cpu = undefined;
         this.emitters_dirty = true;
+        /**
+         * Distinct compiled programs across the emitter set — the number of buckets the coherence
+         * pass sorts into. Known only after {@link buildEmitterData}; until then the emitter count
+         * is a safe upper bound (programs can be shared, never invented).
+         * @type {number|undefined}
+         */
+        this.program_count = undefined;
     }
 
     /**
@@ -116,24 +131,56 @@ export class GPUParticleSystem {
     buildEmitterData() {
         const built = this.registry.build();
         this.emitter_cpu = built.emitters;
+        this.program_count = built.program_count;
         this.emitters_dirty = false;
         return built;
     }
 
+    /**
+     * Number of simulation-order buckets — one per distinct compiled program.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when the emitter set changes, not as particles are born and die.
+     * Everything the pass measures per frame stays on the GPU.
+     *
+     * @returns {number}
+     */
+    bucketCount() {
+        return Math.max(1, this.program_count ?? this.registry.count);
+    }
+
     /**
      * Sizes of the persistent buffers, in bytes. Exposed for tests and allocation.
      * @returns {object}
      */
     bufferSizes() {
         const u32 = 4;
+        const buckets = this.bucketCount();
+
         return {
             pool: this.capacity * PARTICLE_RECORD_WORD_COUNT * u32,
             alive_list: this.capacity * u32,
             dead_list: this.capacity * u32,
             counters: PARTICLE_COUNTER_COUNT * u32,
+            // render order (sort/)
             sorted: this.capacity * u32,
             keys: this.capacity * u32,
             emitter_record: EMITTER_STRIDE * u32,
+
+            // simulation order (coherence/) — a separate set of buffers on purpose; sharing any of
+            // them with the render order would couple a camera-driven ordering to a program-driven
+            // one.
+            //
+            // Padding rounds each bucket up to a whole workgroup, so it can add at most
+            // `workgroup - 1` entries per bucket; one whole workgroup per bucket is the bound.
+            sim_list: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * u32,
+            sim_keys: this.capacity * u32,
+            // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
+            // rounded up to a multiple of four.
+            sim_histogram: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(buckets)) * u32,
+            sim_bucket_counts: buckets * u32,
+            sim_cursor: buckets * u32,
+            sim_dispatch_args: 3 * u32,
         };
     }
 
@@ -160,3 +207,11 @@ export class GPUParticleSystem {
         return { read, write: 1 - read };
     }
 }
+
+/**
+ * @param {number} value
+ * @returns {number} `value` rounded up to a multiple of four
+ */
+function round_up_4(value) {
+    return (value + 3) & ~3;
+}

package/src/shade/renderer/particles/ParticleConstants.d.ts

@@ -42,4 +42,35 @@ export const PARTICLE_VM_INSTRUCTION_WORDS: number;
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS: number;
+/**
+ * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
+ * list is bucketed to (see `coherence/`).
+ *
+ * 64 is a multiple of both subgroup widths a WebGPU implementation plausibly reports (32 on NVIDIA
+ * and RDNA wave32, 64 on GCN wave64), so aligning a bucket to it aligns it to a wave without the
+ * shader ever having to query `subgroup_size`. It is also a power of two, which is what lets the
+ * round-up be a mask rather than a divide — the WGSL emulator's `/` is float division, so an
+ * integer-truncating round-up would read differently there than on a device.
+ *
+ * Lives here rather than in the simulate shader because the bucketing passes, the CPU reference and
+ * the indirect-args pass all have to agree on it; `shaders/shader_particle_simulate.js` re-exports
+ * it for callers that think of it as that pass's property.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WORKGROUP_SIZE: number;
+/**
+ * Slot value carried by a padding entry in the simulate input list.
+ *
+ * Bucketing pads each program's run out to {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} so no wave ever
+ * spans two VM programs; the entries that padding adds name no particle. The simulate shader must
+ * recognise this and return BEFORE the compaction atomics, so a padding lane never appends to the
+ * alive list and never pushes a slot onto the dead (free) list.
+ *
+ * `0xffffffff` is not a reachable slot index: a slot index addresses `pool` at
+ * `slot * PARTICLE_RECORD_WORD_COUNT`, so a pool with 2^32-1 slots would need 512 GiB.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIM_PAD_SLOT: number;
 //# sourceMappingURL=ParticleConstants.d.ts.map

package/src/shade/renderer/particles/ParticleConstants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC"}

package/src/shade/renderer/particles/ParticleConstants.js

@@ -48,3 +48,36 @@ export const PARTICLE_VM_INSTRUCTION_WORDS = 5;
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS = 256;
+
+/**
+ * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
+ * list is bucketed to (see `coherence/`).
+ *
+ * 64 is a multiple of both subgroup widths a WebGPU implementation plausibly reports (32 on NVIDIA
+ * and RDNA wave32, 64 on GCN wave64), so aligning a bucket to it aligns it to a wave without the
+ * shader ever having to query `subgroup_size`. It is also a power of two, which is what lets the
+ * round-up be a mask rather than a divide — the WGSL emulator's `/` is float division, so an
+ * integer-truncating round-up would read differently there than on a device.
+ *
+ * Lives here rather than in the simulate shader because the bucketing passes, the CPU reference and
+ * the indirect-args pass all have to agree on it; `shaders/shader_particle_simulate.js` re-exports
+ * it for callers that think of it as that pass's property.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+
+/**
+ * Slot value carried by a padding entry in the simulate input list.
+ *
+ * Bucketing pads each program's run out to {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} so no wave ever
+ * spans two VM programs; the entries that padding adds name no particle. The simulate shader must
+ * recognise this and return BEFORE the compaction atomics, so a padding lane never appends to the
+ * alive list and never pushes a slot onto the dead (free) list.
+ *
+ * `0xffffffff` is not a reachable slot index: a slot index addresses `pool` at
+ * `slot * PARTICLE_RECORD_WORD_COUNT`, so a pool with 2^32-1 slots would need 512 GiB.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;

package/src/shade/renderer/particles/coherence/graph_particle_bucket.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
+ * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and before the build-indirect pass, which reads the padded length this produces
+ * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
+ *
+ * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
+ * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
+ * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
+ * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
+ * a second place to get that wrong.
+ *
+ * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
+ * that is static topology — it changes when the emitter set does, never as particles are born and
+ * die. The per-frame quantities (the alive count, the bin sizes, the padded total) are produced and
+ * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
+ * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
+ * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
+ * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
+ * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
+ * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
+ * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
+ * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.alive graph handle of this frame's compacted alive list
+ * @param {number} params.counters graph handle of the atomic counters
+ * @param {number} params.sim_list graph handle of the list this rewrites. Passed in rather than
+ *   imported here because the simulate pass reads it earlier in the same frame: importing the same
+ *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
+ *   and the write end up on separate dependency chains
+ * @param {number} params.bucket_count number of distinct compiled programs
+ * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    gpu: {
+        sim_list: GPUBuffer;
+        sim_keys: GPUBuffer;
+        sim_histogram: GPUBuffer;
+        sim_bucket_counts: GPUBuffer;
+        sim_cursor: GPUBuffer;
+        sim_dispatch_args: GPUBuffer;
+    };
+    emitters: number;
+    pool: number;
+    alive: number;
+    counters: number;
+    sim_list: number;
+    bucket_count: number;
+}): {
+    counters: number;
+    sim_list: number;
+};
+//# sourceMappingURL=graph_particle_bucket.d.ts.map