@woosh/meep-engine 3.14.4 → 3.14.6

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts

@@ -15,10 +15,29 @@ export class ProgramArena {
     instruction_count: number;
     /** @type {number} running vec4 constant index */
     constant_count: number;
+    /** @type {Map<string, object>} content key -> the placement the first identical program got */
+    programs: Map<string, object>;
     /**
-     * Append a program.
+     * Number of distinct programs in the arena — and therefore the number of buckets the
+     * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
+     * @returns {number}
+     */
+    get program_count(): number;
+    /**
+     * Append a program, or hand back the placement an identical one already has.
+     *
+     * Deduplication is by CONTENT, not object identity: two emitters that authored the same graph
+     * separately compile to distinct {@link ParticleProgram} objects holding the same bytecode, and
+     * they should still land in one simulation bucket. Emitters are few and long-lived, so hashing
+     * the words is not a cost worth avoiding.
+     *
+     * The `program_id` it returns is what the emitter record carries and what the coherence pass
+     * buckets on. Keying on the emitter index instead would be simpler but strictly worse: N
+     * emitters running one shared effect would become N buckets, each padded to a whole workgroup,
+     * which both wastes lanes and splits a run that was already program-coherent.
+     *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number}}
+     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program: import("../isa/ParticleProgram.js").ParticleProgram): {
         spawn_offset: number;
@@ -26,6 +45,7 @@ export class ProgramArena {
         update_offset: number;
         update_count: number;
         constant_offset: number;
+        program_id: number;
     };
     /** @returns {Uint32Array} the packed instruction buffer (at least length 1) */
     build_instruction_buffer(): Uint32Array;

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IAEQ,8CAA8C;IAC9C,mBADW,MAAM,EAAE,CACQ;IAC3B,8DAA8D;IAC9D,gBADW,MAAM,EAAE,CACK;IACxB,yFAAyF;IACzF,mBADW,MAAM,CACS;IAC1B,iDAAiD;IACjD,gBADW,MAAM,CACM;IAG3B;;;;OAIG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;sBAClC,MAAM;qBAAe,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;MAmB5H;IAUD,+EAA+E;IAC/E,4BADc,WAAW,CAGxB;IAED,yFAAyF;IACzF,yBADc,WAAW,CAGxB;;CACJ"}
+{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IAEQ,8CAA8C;IAC9C,mBADW,MAAM,EAAE,CACQ;IAC3B,8DAA8D;IAC9D,gBADW,MAAM,EAAE,CACK;IACxB,yFAAyF;IACzF,mBADW,MAAM,CACS;IAC1B,iDAAiD;IACjD,gBADW,MAAM,CACM;IACvB,+FAA+F;IAC/F,UADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACL;IAG7B;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;sBAClC,MAAM;qBAAe,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAgChJ;IAUD,+EAA+E;IAC/E,4BADc,WAAW,CAGxB;IAED,yFAAyF;IACzF,yBADc,WAAW,CAGxB;;CACJ"}

package/src/shade/renderer/particles/runtime/ProgramArena.js

@@ -18,14 +18,43 @@ export class ProgramArena {
         this.instruction_count = 0;
         /** @type {number} running vec4 constant index */
         this.constant_count = 0;
+        /** @type {Map<string, object>} content key -> the placement the first identical program got */
+        this.programs = new Map();
     }
 
     /**
-     * Append a program.
+     * Number of distinct programs in the arena — and therefore the number of buckets the
+     * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
+     * @returns {number}
+     */
+    get program_count() {
+        return this.programs.size;
+    }
+
+    /**
+     * Append a program, or hand back the placement an identical one already has.
+     *
+     * Deduplication is by CONTENT, not object identity: two emitters that authored the same graph
+     * separately compile to distinct {@link ParticleProgram} objects holding the same bytecode, and
+     * they should still land in one simulation bucket. Emitters are few and long-lived, so hashing
+     * the words is not a cost worth avoiding.
+     *
+     * The `program_id` it returns is what the emitter record carries and what the coherence pass
+     * buckets on. Keying on the emitter index instead would be simpler but strictly worse: N
+     * emitters running one shared effect would become N buckets, each padded to a whole workgroup,
+     * which both wastes lanes and splits a run that was already program-coherent.
+     *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number}}
+     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program) {
+        const key = program_content_key(program);
+
+        const existing = this.programs.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+
         const spawn_offset = this.instruction_count;
         this.#append_instructions(program.spawn);
         const spawn_count = program.spawn_instruction_count;
@@ -41,7 +70,13 @@ export class ProgramArena {
         }
         this.constant_count += program.constant_count;
 
-        return { spawn_offset, spawn_count, update_offset, update_count, constant_offset };
+        const placement = {
+            spawn_offset, spawn_count, update_offset, update_count, constant_offset,
+            program_id: this.programs.size,
+        };
+        this.programs.set(key, placement);
+
+        return placement;
     }
 
     /** @param {Uint32Array} words */
@@ -62,3 +97,19 @@ export class ProgramArena {
         return new Uint32Array(this.constant_words.length > 0 ? this.constant_words : [0, 0, 0, 0]);
     }
 }
+
+/**
+ * A key that is equal exactly when two programs would execute identically.
+ *
+ * Constants are keyed by their `u32` bit patterns rather than their float values, so `-0` and `0`
+ * — which stringify the same but differ in the buffer the shader reads — stay distinct.
+ *
+ * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+ * @returns {string}
+ */
+function program_content_key(program) {
+    const constants = program.constants;
+    const constant_u32 = new Uint32Array(constants.buffer, constants.byteOffset, constants.length);
+
+    return `${program.register_count}|${program.spawn.join(",")}|${program.update.join(",")}|${constant_u32.join(",")}`;
+}

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts

@@ -7,14 +7,14 @@
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.spawn]
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.update]
+ * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.update]
  * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
  */
 export function create_particle_effect({ layout, spawn, update }: {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
-    spawn?: import("../graph/ParticleGraph.js").ParticleGraph;
-    update?: import("../graph/ParticleGraph.js").ParticleGraph;
+    spawn?: NodeGraph;
+    update?: NodeGraph;
 }): {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
     program: import("../isa/ParticleProgram.js").ParticleProgram;

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACO,KAAK,GAAhE,OAAO,2BAA2B,EAAE,aAAa;IACU,MAAM,GAAjE,OAAO,2BAA2B,EAAE,aAAa;;YACrC,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,KAAK;IACL,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}

package/src/shade/renderer/particles/runtime/create_particle_effect.js

@@ -1,19 +1,19 @@
-import { compile_particle_effect } from "../graph/compile_particle_graph.js";
-
-/**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
- * and UPDATE node graphs, lowered to VM bytecode.
- *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
- *
- * @param {object} params
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.spawn]
- * @param {import("../graph/ParticleGraph.js").ParticleGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
- */
-export function create_particle_effect({ layout, spawn, update }) {
-    const program = compile_particle_effect({ spawn, update, layout });
-    return { layout, program };
-}
+import { compile_particle_effect } from "../graph/compile_particle_graph.js";
+
+/**
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
+ * and UPDATE node graphs, lowered to VM bytecode.
+ *
+ * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
+ * can resolve render-attribute names to record offsets and pack the program into the arena.
+ *
+ * @param {object} params
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.update]
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ */
+export function create_particle_effect({ layout, spawn, update }) {
+    const program = compile_particle_effect({ spawn, update, layout });
+    return { layout, program };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAYG;AAaH,2DA0BG;;8BA7E2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AAoCA,2DAaG;AAaH,2DAmCG;;8BA/F2B,+BAA+B;iDAIZ,+BAA+B"}

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

@@ -9,16 +9,24 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./shader_particle_simulate.js"
 /**
  * Small housekeeping passes that keep the pipeline GPU-driven:
  *
- * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted counters at the top of
- *   the frame (the dead count and the ALIVE_IN snapshot persist across frames).
- * - {@link shader_particle_build_indirect} — read the frame's final alive count and (a) snapshot it
- *   into {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b)
- *   write the indirect dispatch args next frame's simulate consumes, and (c) write the indirect draw
- *   args for THIS frame's billboard render. Nothing round-trips to the CPU. Sizing the dispatch or
- *   draw from a stale CPU readback instead is a correctness bug: when the alive count grows the tail
- *   of the list is never simulated (slots leak into limbo), and when it shrinks stale entries beyond
- *   the written range get re-simulated — a dead slot is pushed to the free list twice and later
- *   popped twice, leaving two live particles sharing one record.
+ * - {@link shader_particle_reset_counters} — zero the alive / spawn / sorted / sim-padded counters
+ *   at the top of the frame (the dead count and the ALIVE_IN snapshot persist across frames).
+ * - {@link shader_particle_build_indirect} — turn the frame's two final counts into next frame's
+ *   input contract: (a) snapshot the coherence pass's padded list length into
+ *   {@link PARTICLE_COUNTER.ALIVE_IN} — the exact input length for NEXT frame's simulate, (b) write
+ *   the indirect dispatch args next frame's simulate consumes, from that SAME value, and (c) write
+ *   the indirect draw args for THIS frame's billboard render, from the alive count. Nothing
+ *   round-trips to the CPU. Sizing the dispatch or draw from a stale CPU readback instead is a
+ *   correctness bug: when the alive count grows the tail of the list is never simulated (slots leak
+ *   into limbo), and when it shrinks stale entries beyond the written range get re-simulated — a
+ *   dead slot is pushed to the free list twice and later popped twice, leaving two live particles
+ *   sharing one record.
+ *
+ * The two lengths are deliberately different quantities and must not be conflated. Simulate consumes
+ * the SIMULATION order: the program-coherent list from `../coherence/`, padded so no wave spans two
+ * VM programs, and therefore longer than the alive count and always a whole number of workgroups.
+ * The billboard draw consumes the RENDER order: one instance per live particle, unpadded — a
+ * padding entry drawn as an instance would read a garbage record.
  */
 
 // --- reset ---
@@ -36,6 +44,7 @@ fn main() {
     atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
     atomicStore(&counters[${PARTICLE_COUNTER.SPAWN}u], 0u);
     atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SIM_PADDED}u], 0u);
 }
 `),
 });
@@ -61,16 +70,25 @@ export const shader_particle_build_indirect = ComputeShader.from({
 fn main() {
     let alive = atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]);
 
-    // Snapshot: this frame's final alive count is next frame's exact simulate input length.
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], alive);
+    // The length of the padded, program-coherent list the coherence pass just built — NOT the alive
+    // count. Padding makes it longer, and a whole number of workgroups.
+    let sim_length = atomicLoad(&counters[${PARTICLE_COUNTER.SIM_PADDED}u]);
+
+    // Snapshot: that list is next frame's simulate input, and this is its exact length.
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], sim_length);
 
-    // Simulate dispatch (consumed NEXT frame): one thread per alive particle, whole workgroups.
-    let groups = (alive + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
+    // Simulate dispatch (consumed NEXT frame): one thread per entry of that same list. Derived from
+    // the same value as the bound above, so thread count and bound agree by construction — and
+    // because a padded length is a whole number of workgroups, they agree exactly: every thread the
+    // dispatch launches has an entry, real or sentinel.
+    let groups = (sim_length + u_workgroup_size - 1u) / max(u_workgroup_size, 1u);
     dispatch_args[0] = groups;
     dispatch_args[1] = 1u;
     dispatch_args[2] = 1u;
 
     // Instanced billboard draw (consumed THIS frame): 6 verts per particle, one instance per alive.
+    // The render list is the unpadded one — an instance per padding entry would read a garbage
+    // record.
     draw_args[0] = 6u;
     draw_args[1] = alive;
     draw_args[2] = 0u;

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

@@ -1,26 +1,5 @@
-/**
- * The particle simulate pass — Destiny-style single execution shader.
- *
- * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
- * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
- * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
- * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
- * because behaviour is data (the bytecode program), not code.
- *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
- *
- * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
- * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
- * animation-database-backed one.
- *
- * @type {ComputeShader}
- */
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE: ComputeShader;
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
 export const shader_particle_simulate: ComputeShader;
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_particle_simulate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AAuEnD,qDAIG;8BA7G2B,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":";AAyIA,qDAIG;iDAjII,yBAAyB;8BATF,+BAA+B"}

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

@@ -7,6 +7,8 @@ import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourc
 import {
     PARTICLE_RECORD_HEADER_EMITTER,
     PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SIM_PAD_SLOT,
     PARTICLE_VM_INSTRUCTION_WORDS,
 } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
@@ -15,18 +17,37 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
 /**
  * The particle simulate pass — Destiny-style single execution shader.
  *
- * One dispatch processes the entire alive list across every emitter. Per particle: read its owning
+ * One dispatch processes every live particle across every emitter. Per particle: read its owning
  * emitter, set up the VM context + RNG, run that emitter's compiled UPDATE program over the record,
  * then compact — killed particles are pushed back to the dead (free) list, survivors are appended to
  * the new alive list. There is exactly one pipeline regardless of how many distinct effects exist,
  * because behaviour is data (the bytecode program), not code.
  *
- * The input length is read from `counters[ALIVE_IN]` — the previous frame's final alive count,
- * snapshotted on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count
- * is inevitably stale (readback latency) and corrupts the pool: under-counting orphans the tail of
- * the alive list (slots leak into limbo), over-counting re-simulates stale entries and double-frees
- * their slots. Dispatch this shader with `dispatchWorkgroupsIndirect` using the args the
- * build-indirect pass wrote last frame, so thread count and bound agree by construction.
+ * ## The input list
+ *
+ * `sim_list` is NOT the raw alive list. It is the program-coherent indirection list the coherence
+ * pass (`../coherence/`) built at the end of last frame: the same pool slots, reordered so that
+ * particles running one VM program sit together, each run padded out to a whole workgroup. That is
+ * what keeps a wave from spanning two programs, which would make the interpreter's opcode `switch`
+ * diverge and multiply the register file's `v_movrels` waterfall by the number of distinct register
+ * indices in the wave.
+ *
+ * Padding entries carry {@link PARTICLE_SIM_PAD_SLOT} and are dropped BEFORE the compaction
+ * atomics, so a padding lane never appends to the alive list and never pushes a slot onto the free
+ * list — pushing the sentinel would put `0xffffffff` on the free list for a later emit to hand out
+ * as a record base. Returning early is safe for the lanes that remain: padding only ever appears in
+ * the tail of a bucket, and every real lane in that wave belongs to that one bucket, so the `switch`
+ * the survivors execute is uniform regardless.
+ *
+ * ## Sizing
+ *
+ * The input length is read from `counters[ALIVE_IN]` — the padded length of that list, snapshotted
+ * on the GPU by the build-indirect pass — NOT from a CPU uniform. A CPU-provided count is inevitably
+ * stale (readback latency) and corrupts the pool: under-counting orphans the tail of the list (slots
+ * leak into limbo), over-counting re-simulates stale entries and double-frees their slots. Dispatch
+ * this shader with `dispatchWorkgroupsIndirect` using the args the build-indirect pass wrote last
+ * frame from that same value, so thread count and bound agree by construction — and, because the
+ * padded length is a whole number of workgroups, agree exactly.
  *
  * All structured reads go through `array<u32>` for emulator-testability. Curve sampling uses the
  * pluggable `particle_vm_sample_curve` — here the no-op provider; the feature swaps in the
@@ -35,7 +56,7 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
  * @type {ComputeShader}
  */
 
-export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE };
 
 /**
  * Per-dispatch, 12 bytes, read-only — see shader_particle_emit for why the three travel
@@ -58,7 +79,7 @@ resources.createGroup()
     .addStorageBuffer("program", WebGPUArray.u32, false)
     .addStorageBuffer("vm_constants", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("alive_in", WebGPUArray.u32, false)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
@@ -71,14 +92,22 @@ const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
 const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 const COUNTER_ALIVE_IN : u32 = ${PARTICLE_COUNTER.ALIVE_IN}u;
+const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
 
 @compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
-    // The exact alive-list length, snapshotted on-GPU last frame — never a stale CPU value.
+    // The exact input length, snapshotted on-GPU last frame — never a stale CPU value.
     if (i >= atomicLoad(&counters[COUNTER_ALIVE_IN])) { return; }
 
-    let slot = alive_in[i];
+    let slot = sim_list[i];
+
+    // A lane the coherence pass padded the bucket out with. Leave BEFORE the compaction atomics
+    // below: appending here would put the sentinel on the alive or the free list, and the free list
+    // would then hand 0xffffffff to an emit as a record base. The lanes that stay all belong to the
+    // one bucket this wave covers, so their program — and the interpreter's switch — is uniform.
+    if (slot == PARTICLE_SIM_PAD_SLOT) { return; }
+
     let record_base = slot * PARTICLE_RECORD_WORDS;
     let emitter_index = pool[record_base + PARTICLE_HEADER_EMITTER];
 

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts

@@ -1,23 +1,12 @@
+export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 /**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
- * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
- *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
- *    `keys`, and atomically bump the per-bucket `histogram`.
- * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
- * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
- *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
- *    into `sorted` at that position.
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
+ * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
+ * and the scan adds them in.
  *
- * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
- * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
- * algorithm.
+ * @type {ComputeShader}
  */
-export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
 export const shader_particle_sort_reset: ComputeShader;
 export const shader_particle_sort_histogram: ComputeShader;
 export const shader_particle_sort_scatter: ComputeShader;

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA+C;AAkC/C,uDAIG;AAyEH,2DAIG;AAqCH,yDAIG;8BAvL2B,+BAA+B"}
+{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAsDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AA0EH,2DAIG;AAyCH,yDAIG;8BA1O2B,+BAA+B"}

package/src/shade/renderer/particles/sort/shader_particle_sort.js

@@ -4,6 +4,7 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
 import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
 import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
 import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
@@ -11,10 +12,11 @@ import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
 /**
  * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
  *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
+ * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count, elements}`
+ *    header (the bucket count the csdldf scan sizes itself from), clear the header padding and the
+ *    bins, and zero the scatter cursor. Without this the scan consumes garbage counts and the
+ *    scatter compounds last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not
+ *    per frame.
  * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
  *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
  *    `keys`, and atomically bump the per-bucket `histogram`.
@@ -23,11 +25,33 @@ import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
  *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
  *    into `sorted` at that position.
  *
+ * ## The buffer the four passes share
+ *
+ * The histogram IS the scan's `{count: u32, elements: array<vec4u>}`, bound flat here as
+ * `array<atomic<u32>>` because these passes need atomics on it. `elements` is `@align(16)`, so bin
+ * `b` is word {@link PREFIX_SCAN_CSDLDF_HEADER_WORDS}` + b` and words 1..3 are padding the scan
+ * never reads. Every pass below steps over that header by hand; the reset clears whole vec4s of
+ * bins, because whole vec4s is what the scan loads.
+ *
+ * ## This is the render order
+ *
+ * The camera-dependent back-to-front list the billboard draw consumes. `../coherence/` produces the
+ * simulation order from the same three-phase shape — different buffers, different passes, different
+ * counter slots (`PARTICLE_COUNTER.SORTED` against `PARTICLE_COUNTER.SIM_PADDED`), on purpose.
+ *
  * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
  * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
  * algorithm.
  */
 
+/** @type {number} words of `{count, elements}` header in front of the scan's bins */
+const HEADER = PREFIX_SCAN_CSDLDF_HEADER_WORDS;
+
+/** The header stride every pass in this file interpolates. */
+const COMMON = /* wgsl */ `
+const SORT_HEADER_WORDS : u32 = ${HEADER}u;
+`;
+
 export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
 
 // --- reset pass ---
@@ -48,20 +72,42 @@ reset_resources.createGroup()
     .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true);
 const reset_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
+
 @compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
+
     if (i == 0u) {
         // The {count, elements} header the csdldf scan sizes itself from.
         atomicStore(&histogram[0], settings.u_bucket_count);
     }
+
+    // Header padding: never read by the scan, but it shares the buffer and the pool may have left
+    // something in it.
+    if (i > 0u && i < SORT_HEADER_WORDS) {
+        atomicStore(&histogram[i], 0u);
+    }
+
+    // The scan reads whole vec4s, so the bins are cleared up to the vec4 the last one lands in.
+    if (i < ((settings.u_bucket_count + 3u) & 0xfffffffcu)) {
+        atomicStore(&histogram[SORT_HEADER_WORDS + i], 0u);
+    }
+
     if (i < settings.u_bucket_count) {
-        atomicStore(&histogram[1u + i], 0u);
         atomicStore(&cursor[i], 0u);
     }
 }
 `);
 
+/**
+ * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count)` threads, not over
+ * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
+ * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
+ * and the scan adds them in.
+ *
+ * @type {ComputeShader}
+ */
 export const shader_particle_sort_reset = ComputeShader.from({
     label: "Particle Sort Reset",
     resources: reset_resources,
@@ -105,6 +151,7 @@ histogram_resources.createGroup()
     .addStorageBuffer("keys", WebGPUArray.u32, true)
     .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true);
 const histogram_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
 const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
@@ -135,7 +182,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let bucket = min(u32(clamped * f32(settings.u_bucket_count)), settings.u_bucket_count - 1u);
 
     keys[i] = bucket;
-    atomicAdd(&histogram[1u + bucket], 1u);
+    atomicAdd(&histogram[SORT_HEADER_WORDS + bucket], 1u);
 }
 `, [chunk_particle_emitter]);
 
@@ -166,15 +213,19 @@ scatter_resources.createGroup()
     .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer("sorted", WebGPUArray.u32, true);
 const scatter_body = CodeChunk.from(/* wgsl */ `
+${COMMON}
+
 @compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
     if (i >= settings.u_count) { return; }
 
     let bucket = keys[i];
-    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
-    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
-    let exclusive = select(0u, scanned[bucket], bucket > 0u);
+
+    // The scan is inclusive, so bucket b's exclusive offset is bucket b-1's inclusive value, one
+    // word earlier. For bucket 0 the index lands on the last header word — in bounds, and unused,
+    // because select() takes the 0 branch there.
+    let exclusive = select(0u, scanned[SORT_HEADER_WORDS + bucket - 1u], bucket > 0u);
     let rank = atomicAdd(&cursor[bucket], 1u);
     sorted[exclusive + rank] = alive[i];
 }

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

@@ -33,7 +33,7 @@ import { VM_BUILTIN, VM_OP, VM_RANDOM_MODE } from "../isa/ParticleVMISA.js";
 
 const R = PARTICLE_VM_REGISTER_COUNT;
 
-const source = /* wgsl */ `
+const source = /* language=wgsl */ `
 const PARTICLE_VM_REGISTER_COUNT : u32 = ${R}u;
 const PARTICLE_VM_MAX_INSTRUCTIONS : u32 = ${PARTICLE_VM_MAX_INSTRUCTIONS}u;
 const PARTICLE_VM_TWO_PI : f32 = 6.28318530717958647692;

package/src/shade/renderer/scene/SkinnedMesh.d.ts

@@ -28,6 +28,17 @@
  * see {@link chunk_skin_blend_mesh_local} for why it goes into each
  * matrix rather than onto the blended position.
  *
+ * **`transform_global` on a skinned mesh is the engine's, not the
+ * asset's.** It cancels out of the rendered position, so glTF declares
+ * it meaningless — and the one meaning it does have is the frame the
+ * clone's vertices are written in, which the fold above requires to be
+ * rigid against the skin. {@link GPUAnimationManager#register_skin}
+ * therefore overwrites it, by way of
+ * {@link skin_normalize_mesh_frame}, with the skin's own bind
+ * transform. Whatever the file put there is discarded, and anything
+ * reading this expecting the file's value is reading the wrong thing.
+ * See `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
  * The mesh's **skin id** — a row in a GPU table — lives in
  * {@link GPUMeshSkinningContext} and nowhere else. The CPU-side
  * {@link Skin} it was registered with is a different thing, pure data

package/src/shade/renderer/scene/SkinnedMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBAnJoB,WAAW"}
+{"version":3,"file":"SkinnedMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/SkinnedMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;IAEI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAFU,OAAK,IAAI,CAEP;IAEZ;;OAEG;IACH,SAFa,WAAW,CAMvB;IAED;;OAEG;IACH,YAFW,WAAW,QAYrB;IA4CL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;qBA9JoB,WAAW"}