@woosh/meep-engine 3.14.5 → 3.14.6

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAyEA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CA8OlB;AA3QD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AACH;IAJqC,YAAY;IACrB,QAAQ,GAAzB,MAAM;IACJ,MAAM,CAiUlB;AAjWD;;;;GAIG;AACH,0CAA2C;AAE3C,wGAAwG;AACxG,sCAAuC;;;;;WAOzB,MAAM;;;;UACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE"}

package/src/shade/playground/particle_system/particle_scene.js

@@ -4,7 +4,23 @@ import { m4_look_at } from "../../../core/geom/3d/mat4/m4_look_at.js";
 import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../renderer/camera/CAMERA_UNIFORM_STRUCT.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "../../renderer/particles/ParticleConstants.js";
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+} from "../../renderer/particles/ParticleConstants.js";
+import {
+    PREFIX_SCAN_CSDLDF_HEADER_WORDS,
+    PREFIX_SCAN_CSDLDF_PARTITION_SIZE,
+    shader_prefix_scan_csdldf,
+} from "../../renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { build_indirect_compute_dispatch_command } from "../../renderer/gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    shader_particle_bucket_fill,
+    shader_particle_bucket_histogram,
+    shader_particle_bucket_pad,
+    shader_particle_bucket_reset,
+    shader_particle_bucket_scatter,
+} from "../../renderer/particles/coherence/shader_particle_bucket.js";
 import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js";
 import { NodeGraph } from "../../../core/model/node-graph/NodeGraph.js";
@@ -23,10 +39,7 @@ import {
     shader_particle_build_indirect,
     shader_particle_reset_counters,
 } from "../../renderer/particles/shaders/shader_particle_finalize.js";
-import {
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    shader_particle_simulate,
-} from "../../renderer/particles/shaders/shader_particle_simulate.js";
+import { shader_particle_simulate } from "../../renderer/particles/shaders/shader_particle_simulate.js";
 
 /**
  * The scene the particle playground draws, with every reference to the page removed: it takes a
@@ -50,6 +63,12 @@ import {
  * billboard draw via `drawIndirect`, both from args the build-indirect pass writes on the GPU. No
  * CPU readback participates in sizing anything — a stale CPU count would orphan alive-list entries
  * when the population grows and double-free slots when it shrinks.
+ *
+ * The four emitters run four distinct compiled programs, so this is also where the simulation-order
+ * bucketing has something to do: without it a simulate wave holds fire, smoke, spark and dust
+ * particles side by side, each wanting different opcodes out of the interpreter's switch. The
+ * bucketing passes are encoded directly here rather than through `graph_particles`, which is the
+ * frame-graph wiring of the same sequence.
  */
 
 /** Maximum simultaneous particles across every emitter — they share one pool. */
@@ -75,7 +94,10 @@ const STATS_OFFSET_DRAW_ARGS = 48;
  * @typedef {object} ParticleSceneStats
  * @property {number} alive particles alive at the end of the captured frame
  * @property {number} dead free slots left in the pool
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length
+ * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
+ *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
+ * @property {number} sim_padded length of the program-coherent list the coherence pass built this
+ *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
  * @property {number[]} draw the billboard draw's indirect args, `[vertices, instances]`
  */
@@ -148,6 +170,37 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
     const dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * 4, usage: args_usage });
     const draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * 4, usage: args_usage });
 
+    // --- simulation-order (coherence) buffers -------------------------------------------------
+    //
+    // A separate set from the render-order sort's, on purpose: one list is grouped by VM program and
+    // camera-independent, the other is back-to-front by view depth. Sharing a buffer between them
+    // would couple a camera-driven ordering to a program-driven one.
+    const sizes = system.bufferSizes();
+    const buckets = system.bucketCount();
+    const sim_list = device.createBuffer({ label: "particles/sim_list", size: sizes.sim_list, usage: storage });
+    const sim_keys = device.createBuffer({ label: "particles/sim_keys", size: sizes.sim_keys, usage: storage });
+    const sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: sizes.sim_histogram, usage: storage });
+    const sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: sizes.sim_bucket_counts, usage: storage });
+    const sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: sizes.sim_cursor, usage: storage });
+    const sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: sizes.sim_dispatch_args, usage: args_usage });
+
+    // Scratch the reused CSDLDF scan needs: the indirect command it is dispatched with, and its
+    // decoupled-lookback spine. One partition covers every plausible bucket count.
+    const scan_command = device.createBuffer({
+        label: "particles/sim_scan_command",
+        size: 3 * 4,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+    });
+    // Cleared at the top of every frame, not just on creation: the spine carries per-partition
+    // flags, and a stale FLAG_INCLUSIVE left over from last frame is read as this frame's answer.
+    // The frame-graph wiring gets this for free from `BufferResourceDescriptor.empty`; encoding by
+    // hand has to ask. Rounded to a 256-byte allocation rather than the 8 bytes one partition needs.
+    const scan_spine = device.createBuffer({
+        label: "particles/sim_scan_spine",
+        size: Math.max(256, Math.ceil(buckets / PREFIX_SCAN_CSDLDF_PARTITION_SIZE) * 2 * 4),
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
     const initial = system.initialFreeList();
     device.queue.writeBuffer(dead, 0, initial.dead);
     device.queue.writeBuffer(counters, 0, initial.counters);
@@ -205,7 +258,12 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
         capacity,
 
         /** Buffers a harness may inspect. Not for the frame loop, which never reads them back. */
-        buffers: { pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants, dispatch_args, draw_args },
+        buffers: {
+            pool, alive_a, alive_b, dead, counters, spawn_requests, emitters, program, constants,
+            dispatch_args, draw_args,
+            sim_list, sim_keys, sim_histogram, sim_bucket_counts, sim_cursor, sim_dispatch_args,
+            sim_scan_command: scan_command, sim_scan_spine: scan_spine,
+        },
 
         /**
          * Encode one whole frame: geometry, then emit + simulate + build-indirect, then the
@@ -259,13 +317,59 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
                 encoder: cmd,
                 bindings: {
                     emitters, program, vm_constants: constants, pool,
-                    alive_in: alive_read, alive_out: alive_write, dead, counters,
+                    sim_list, alive_out: alive_write, dead, counters,
                     settings: { u_dt: dt, u_time: time, u_frame: system.frame },
                 },
                 command: dispatch_args,
             });
 
-            // Snapshot the final alive count (next frame's simulate input) + write this frame's draw args.
+            // --- coherence: regroup the finished alive list by VM program for NEXT frame's simulate ---
+            //
+            // Reads the list emit and simulate have both finished appending to, and rewrites
+            // `sim_list` — the buffer simulate read a few lines above. Consecutive dispatches are
+            // ordered, so the read is complete before the write lands.
+            shader_particle_bucket_reset.dispatchThreads({
+                encoder: cmd,
+                bindings: { counters, histogram: sim_histogram, cursor: sim_cursor, sim_dispatch_args, u_bucket_count: buckets },
+                thread_count_x: bucket_reset_thread_count(buckets),
+            });
+
+            shader_particle_bucket_histogram.dispatchIndirect({
+                encoder: cmd,
+                bindings: { emitters, pool, alive: alive_write, keys: sim_keys, histogram: sim_histogram, counters },
+                command: sim_dispatch_args,
+            });
+
+            shader_particle_bucket_pad.dispatchThreads({
+                encoder: cmd,
+                bindings: { histogram: sim_histogram, bucket_counts: sim_bucket_counts, u_bucket_count: buckets },
+                thread_count_x: buckets,
+            });
+
+            // The same scan the radix sort runs its spine through, reused unmodified.
+            cmd.clearBuffer(scan_spine, 0, scan_spine.size);
+            build_indirect_compute_dispatch_command(
+                PREFIX_SCAN_CSDLDF_PARTITION_SIZE, cmd, sim_histogram, 0, scan_command, 0,
+            );
+            shader_prefix_scan_csdldf.dispatchIndirect({
+                encoder: cmd,
+                command: scan_command,
+                bindings: { scan_in: sim_histogram, spine: scan_spine },
+            });
+
+            shader_particle_bucket_scatter.dispatchIndirect({
+                encoder: cmd,
+                bindings: { keys: sim_keys, alive: alive_write, scanned: sim_histogram, cursor: sim_cursor, sim_list, counters },
+                command: sim_dispatch_args,
+            });
+
+            shader_particle_bucket_fill.dispatchThreads({
+                encoder: cmd,
+                bindings: { bucket_counts: sim_bucket_counts, scanned: sim_histogram, sim_list, counters, u_bucket_count: buckets },
+                thread_count_x: buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE,
+            });
+
+            // Snapshot the padded list length (next frame's simulate input) + write this frame's draw args.
             shader_particle_build_indirect.dispatch({
                 encoder: cmd,
                 bindings: { counters, dispatch_args, draw_args, u_workgroup_size: PARTICLE_SIMULATE_WORKGROUP_SIZE },
@@ -320,6 +424,7 @@ export function create_particle_scene(graphics, { color_format, capacity = PARTI
                 alive: words[0],
                 dead: words[1],
                 alive_in: words[4],
+                sim_padded: words[5],
                 dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
                 draw: [words[draw_base], words[draw_base + 1]],
             };
@@ -529,6 +634,18 @@ function translation(x, y, z) {
     return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1];
 }
 
+/**
+ * Threads the bucket reset pass needs: enough to cover the scan's header plus its bins, rounded up
+ * to the whole `vec4` the last bin lands in (the scan reads whole `vec4`s, so the tail has to be
+ * cleared too or garbage joins the sums).
+ *
+ * @param {number} bucket_count
+ * @returns {number}
+ */
+function bucket_reset_thread_count(bucket_count) {
+    return PREFIX_SCAN_CSDLDF_HEADER_WORDS + ((bucket_count + 3) & ~3);
+}
+
 function data_buffer(device, label, data, usage) {
     const buffer = device.createBuffer({ label, size: Math.max(data.byteLength, 4), usage });
     device.queue.writeBuffer(buffer, 0, data);

package/src/shade/renderer/GraphicsContext.d.ts

@@ -118,6 +118,7 @@ export class GraphicsContext {
     readonly isGraphicsContext: boolean;
     #private;
 }
+export type BinaryBuffer = import("../../core/binary/BinaryBuffer.js").BinaryBuffer;
 import { GPUGeometryManager } from "./geometry/GPUGeometryManager.js";
 import { GPUMaterialManager } from "./material/GPUMaterialManager.js";
 import { GPUSamplerManager } from "./GPUSamplerManager.js";

package/src/shade/renderer/GraphicsContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AAwBA;IAoJI,yBA8BC;IAjLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAkCD;;;;;;;;OAQG;IACH,gGALW,oBAAoB,EAAE,cACtB;QAAC,MAAM,eAAe;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,mDAFa,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAcC;IAED,4BAEC;IAED,eAmBC;IAED,gBAcC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;mCA9UkC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAXzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAchD,6BAA6B;sCACtB,4CAA4C;iCAbjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAErC,uCAAuC;oCAO7C,kCAAkC;iCARtB,8BAA8B"}
+{"version":3,"file":"GraphicsContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/GraphicsContext.js"],"names":[],"mappings":"AA4BA;IAoJI,yBA8BC;IAjLD;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAOV;;OAEG;IACH,UAFU,iBAAiB,CAElB;IAET;;;OAGG;IACH,qDAOC;IAOD;;;OAGG;IACH,6CAEC;IAED;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,mBAFU,sBAAsB,CAEd;IAGlB;;OAEG;IACH,gBAFU,oBAAoB,CAEf;IAEf;;OAEG;IACH,UAFU,cAAc,CAEf;IAET;;;;OAIG;IACH,kBAFU,qBAAqB,CAEd;IAEjB;;OAEG;IACH,aAFU,gBAAgB,CAEd;IAQZ;;;OAGG;IACH,uBAFU,kBAAkB,CAEN;IAEtB;;;;OAIG;IACH,yBAFU,wBAAwB,CAEV;IAExB;;;OAGG;IACH,0BAFU,yBAAyB,CAEV;IAEzB;;;OAGG;IACH,oBAFU,mBAAmB,CAEV;IAUnB;;;OAGG;IACH,8BAEC;IAED,uBAMC;IAED;;;OAGG;IACH,wBAEC;IAkCD;;;;;;;;OAQG;IACH,gGALW,oBAAoB,EAAE,cACtB;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,QAmE9D;IAED;;;;OAIG;IACH,mDAFa,gBAAgB,CAI5B;IAED;;OAEG;IACH,+BAcC;IAED,4BAEC;IAED,eAmBC;IAED,gBAcC;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BAtUY,OAAO,mCAAmC,EAAE,YAAY;mCAZlC,kCAAkC;mCAGlC,kCAAkC;kCADnC,wBAAwB;2CAEf,mDAAmD;oCAH1D,2CAA2C;sCAXzC,6CAA6C;sCAC7C,6CAA6C;uCAF5C,8CAA8C;qCAIhD,0CAA0C;+BAchD,6BAA6B;sCACtB,4CAA4C;iCAbjD,+BAA+B;mCAC7B,gCAAgC;yCAC1B,sCAAsC;0CAErC,uCAAuC;oCAO7C,kCAAkC;iCARtB,8BAA8B"}

package/src/shade/renderer/GraphicsContext.js

@@ -20,6 +20,10 @@ import { GPUTextureAllocator } from "./texture/GPUTextureAllocator.js";
 import { TextureManager } from "./texture/TextureManager.js";
 import { VirtualTextureManager } from "./texture/virtual/VirtualTextureManager.js";
 
+
+/**
+ * @typedef {import("../../core/binary/BinaryBuffer.js").BinaryBuffer} BinaryBuffer
+ */
 const DEBUG_LOGGING = false;
 
 export class GraphicsContext {

package/src/shade/renderer/Renderer.d.ts

@@ -11,7 +11,7 @@ export class Renderer {
      *
      * @returns {HTMLCanvasElement|OffscreenCanvas|undefined}
      */
-    get canvas(): OffscreenCanvas | HTMLCanvasElement;
+    get canvas(): HTMLCanvasElement | OffscreenCanvas;
     /**
      * @type {GPUDevice}
      */

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

@@ -1,3 +1,16 @@
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();
     klass: typeof MeshletGeometry;

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

@@ -1 +1 @@
-{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAzFM,uEAAuE;gCAE9C,sBAAsB"}
+{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAtGM,uEAAuE;gCAE9C,sBAAsB"}

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

@@ -4,6 +4,19 @@ import {
 import { blas_from_meshlets } from "./blas_from_meshlets.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter {
 
     version = 0

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

@@ -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
@@ -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
 
@@ -149,6 +186,9 @@ src/webgpu/renderer/particles/
   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)