@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -3,71 +3,135 @@
 A specialized, deeply-integrated, GPU-driven particle engine for the v2 renderer.
 Destiny-style: **one** simulation dispatch runs **all** particles of **all** emitters by
 interpreting a compact per-emitter bytecode program (a shader VM). Effects are authored as
-node graphs and lowered to that bytecode by a testable JS compiler.
+node graphs and lowered to that bytecode by a testable JS compiler. Emitters are scene nodes, and
+the decision to spawn is the GPU's.
 
 ## Goals (from the brief)
 
 - Single simulation execution shader (data-driven VM, not one-pipeline-per-effect).
 - Projection modes: camera-facing billboard (+ velocity-stretched, axis-locked, world-oriented).
-- Depth sorting for correct transparency, built on the `csdldf` prefix scan (radix sort).
+- Depth sorting for correct transparency, built on the `csdldf` prefix scan.
 - Node-based composition → shader VM (compile graph → bytecode).
-- Frustum + HiZ occlusion **simulation** culling (optional, flagged, sleep-when-culled + catch-up).
+- Frustum culling of spawning (optional, flagged, sleep-when-culled + bounded catch-up).
 - Flipbooks (atlas sub-rect + frame grid).
 - Texture lookup via atlas (region table; mirrors meep `AtlasPatch` uv offset/scale).
 - Soft-depth fade (flagged).
 - `GPUDatabase` for CPU-managed, low-churn tables (emitters).
-- Scene-node / bone attachment (emitter follows a `Node3D` / bone via the scene transforms table).
+- Scene-node / bone attachment: an emitter **is** a `Node3D`; its world matrix is its row of the
+  scene's `transforms` table, composed by the GPU hierarchy pass.
 - Distinct per-particle lifecycle: **no** built-in age/position — the schema + program define state.
 - Billboard renderer reuses engine shader chunks incl. lighting (forward-shaded, optional per emitter).
 - Blend modes (alpha + additive) via a **single** premultiplied blend setup.
 - `AnimationCurve` sampling during simulation (reuse `chunk_animation_curve_evaluate`).
+- Spawning decided on the GPU, per emitter, with the CPU able to ask for bursts through the same path.
+- No per-frame allocation on the CPU beyond the frame graph's own records.
 
 ## Layered architecture
 
 ```
-authoring:   NodeGraph (nodes+ports)      ──compile──▶  Program (bytecode)
+authoring:   NodeGraph (nodes+ports)      ──compile──▶  Program (bytecode: INIT + UPDATE)
              standard node library                       │
                                                          ▼
-runtime CPU: EmitterDefinition ── GPUDatabase(emitters) ─┤  ProgramArena (packed u32 buffer)
-                                                         │  ParticleAtlas (texture + regions)
+runtime CPU: ParticleEmitter (a Node3D) ── Scene ──▶ GPUSceneContext (transforms table)
+             EmitterRegistry ── GPUDatabase(emitters + emitter_state) ─┤  ProgramHeap ([header][constants][code])
+             GPUParticleSystem (owns every buffer, records the frame)
                                                          ▼
 runtime GPU: particle pool (array<u32>, uniform stride) + alive/dead lists + counters
-             ┌─ 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)
+             emitter state table (GPU-owned: generation, accumulator, age, sleep, pending)
+             ┌─ spawn commands (CPU bursts → pending)
+             ├─ emitter tick  (per row: cull, integrate rate, take from budget → count)
+             ├─ scan (csdldf) → emit dispatch
+             ├─ emit  (VM INIT program)   ── per newborn: find emitter in scan, pop dead → init → append alive_new
+             ├─ simulate (VM UPDATE program) ── update → (kill|orphan→dead | keep→alive_new)
              ├─ bucket (histogram → csdldf scan → scatter)  ── alive → program-coherent sim list
-             ├─ compact/indirect-args
-             ├─ sort  (radix: histogram → csdldf scan → scatter)   [transparent]
+             ├─ build indirect (dispatch + draw args)
+             ├─ sort  (histogram → csdldf scan → scatter)    [render order]
              └─ render (instanced billboard quads, forward + optional lighting + soft depth)
 ```
 
 ### Particle storage — single shared pool, uniform stride
 
 All particles live in one `array<u32>` pool with a fixed `RECORD_WORDS` stride (config, default 32
-words = 128 B). Word 0 is a reserved header holding the owning **emitter index**; user attributes
-occupy words `1..RECORD_WORDS`. A single pool + single alive/dead lists means **one** emit dispatch
-and **one** simulate dispatch cover every emitter — the Destiny single-shader property.
+words = 128 B). Word 0 is a reserved header holding the owning **emitter row** and that row's
+**generation** (`data/particle_header.js`); user attributes occupy words `1..RECORD_WORDS`. A single
+pool + single alive/dead lists means **one** emit dispatch and **one** simulate dispatch cover every
+emitter — the Destiny single-shader property.
 
 Lifecycle uses the canonical GPU dead-list / alive-list ping-pong:
 - `dead_list`: stack of free slot indices (+ atomic count).
 - `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.
+- `counters`: atomics {alive_count, dead_count, spawn budget, …} + derived indirect dispatch/draw args.
 
-Emit: pop dead → run SPAWN → append `alive_new`. Simulate: read the **coherence list** last frame's
+Emit: pop dead → run INIT → 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.
+`alive_new`. Swap lists each frame.
 
 **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
-emit pass's dead-list pop guards against wrapped counters (`old == 0 || old > capacity`), so racing
-an exhausted pool drops spawns cleanly instead of handing out garbage slots.
+snapshot. The sort's per-particle passes take the dispatch the bucket reset writes from the alive
+count. 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 emit pass's dead-list pop guards against wrapped counters
+(`old == 0 || old > capacity`), so racing an exhausted pool drops spawns cleanly instead of handing
+out garbage slots.
+
+### Spawning is the GPU's decision
+
+The CPU never walks the emitters per frame and never counts particles. Per frame:
+
+1. **spawn commands** (`shaders/shader_particle_spawn_commands.js`, only when the host queued any):
+   one thread per `[row, count]` pair the host authored, `atomicAdd` into that row's `PENDING` in
+   the GPU-owned emitter state. This is `GPUParticleSystem#spawn` — the CPU's facade over the GPU
+   path, not a second path: a burst goes through the same budget, expansion and INIT program as the
+   emitter's rate. It is also the channel a VM opcode would use to spawn from the GPU (a sub-emitter
+   or trail would `atomicAdd` its target's `PENDING`).
+2. **emitter tick** (`shaders/shader_particle_emitter_tick.js`): one thread per emitter table row,
+   walked with the table's page iterator so an unallocated page costs one word and a freed row one
+   bit. Per live row: recognise the row by generation (a mismatch starts the state over — new
+   emitter, or a reused row, with nothing for the CPU to clear); take `PENDING`; if the emitter opts
+   into culling, test its bounds sphere in world space (through its node's `global`) against the
+   camera frustum and sleep while culled, paying back a bounded catch-up on wake; integrate
+   `spawn_rate * dt`; turn the whole part of the accumulator into this frame's count, clamped by the
+   **spawn budget** the reset pass seeded from the dead count — so an emitter is only ever debited
+   for particles the pool can hold; write the count to `spawn_counts.elements[row]`.
+3. **scan**: `graph_prefix_scan_csdldf` over the counts — each row's batch ends at its inclusive sum,
+   and the last sum is the number of particles born.
+4. **spawn args**: `shader_prefix_sum_to_command` (the rasteriser's own) turns that total into the
+   emit dispatch.
+5. **emit**: one thread per newborn, locating its emitter by `lower_bound_branchless` over the sums
+   and its batch fraction from the sum before — the meshes-to-meshlets expansion applied to
+   particles. No per-emitter cap, no thread loops over its particles.
+
+The host contributes two numbers to all of that: the emitter table's element capacity (the scan's
+length — static topology) and the length of the command list it wrote itself.
+
+### The emitter state (`data/PARTICLE_EMITTER_STATE.js`)
+
+What the GPU integrates per emitter — generation, accumulator, age, sleep, pending — is the
+`emitter_state` table of the same database, one row per emitter at the emitter's row, **not**
+fields of the emitter record. The record is CPU-shadowed and restaged whole whenever the author
+changes a field, and that restage would overwrite an accumulator the GPU has been adding to for a
+hundred frames. The scene's transforms table mixes CPU fields with a GPU-written `global` only
+because `global` is recomputed from scratch every frame; nothing here is. In its own table the CPU
+touches a row exactly twice — a zero record when the emitter's row is claimed, the table's own
+zero-fill when it is released — and the database's resize copies pages on the GPU, so growth keeps
+what the tick has written. Nothing in it is atomic: each row is one tick thread's, and the
+spawn-command pass is handed one command per row (the system merges bursts on the CPU). The
+emitter's `age` here is the VM's `EMITTER_AGE` builtin.
+
+### Eight storage buffers
+
+A compute stage gets eight storage buffers by default, and the design does not ask for more. Two
+things keep every pass under it: the emitter record and the GPU-owned state are two tables of one
+database buffer, read through one binding; and the VM's constants and code are one packed buffer —
+`[header][constants][code]`, the header's first word saying where the code starts
+(`ParticleConstants.PARTICLE_PROGRAM_HEADER_WORDS`). Emit and simulate bind exactly eight; their
+wide-register variants bind nine, which is the one place the system spends past the default and is
+still inside the ten the engine demands of an adapter. `particle_shaders_wgsl_validity.spec` pins
+the count for every pass.
 
 ### The VM (`ParticleVM`)
 
@@ -75,16 +139,58 @@ Register machine, emulator-safe (bounded instruction loop + big `switch`, no sub
 recursion, no data-dependent jumps — conditionals are predicated via CMP/SELECT, destruction via
 `KILL`).
 
-- Register file: `array<vec4f, REG_COUNT>` (default 16). Scalars use `.x`; vectors use `.xyz(w)`.
-- Instruction: fixed **5×u32** words `[op, dst, s0, s1, s2]`. Operand meaning is per-opcode
-  (register index / const-pool index / attribute word-offset+comp / curve handle / builtin id).
+- Register file: `array<f32>`, a register being one slot and a value of width *w* occupying *w*
+  consecutive ones. The interpreter reaches it through `vm_reg_read` / `vm_reg_write`, which a
+  **backing chunk** supplies, and the two backings are the two interpreters:
+  `vm/chunk_particle_vm_registers_fast.js` puts the file in `var<private>`
+  (`PARTICLE_VM_FAST_REGISTER_SLOTS`, dynamically indexed, so its size is the shader's register
+  footprint), and `vm/chunk_particle_vm_registers_wide.js` puts it in a storage buffer
+  (`PARTICLE_VM_REGISTER_SLOTS` — every slot an 8-bit operand base can name). See **Two
+  interpreters** below.
+- Instruction: fixed **4×u32** words `[op | width << 8 | kinds << 16 | dst << 24, s0, s1, s2]`.
+  Word 0 packs the opcode (bits 0..7), the lane count (8..10), each source's `VM_KIND` (two bits per
+  slot at 16..21) and the destination slot (24..31). A source word means what its kind says: `REG`
+  is a base slot plus a swizzle, `IMM` is an `f32` bit pattern read in every lane, and `NONE` is a
+  raw field the opcode reads for itself (attribute word-offset+comp / curve handle / builtin id /
+  pool index).
 - Constant pool: `array<vec4f>` per program, referenced by `LOAD_CONST`.
-- Two entry sections per program: **SPAWN** and **UPDATE** (offsets in the emitter record).
-- Builtins (`LOAD_BUILTIN`): DT, EMITTER_AGE, EMITTER_POSITION, EMITTER_DIRECTION, EMITTER_SEED,
-  PARTICLE_INDEX, SPAWN_FRACTION, … assembled per-invocation by the host shader.
+- Two entry sections per program: **INIT** and **UPDATE** (offsets in the emitter record). INIT
+  gives an already-allocated record its state; it has no say in whether the particle exists.
+- Builtins (`LOAD_BUILTIN`): DT, EMITTER_AGE, EMITTER_POSITION, EMITTER_DIRECTION, EMITTER_UP,
+  PARTICLE_INDEX, SPAWN_FRACTION, TIME … assembled per-invocation by the host shader. The emitter's
+  position and axes are its node's `global` out of the scene database.
 - `CURVE dst, handle, s0`: `dst.x = animation_curve_evaluate(curves[handle], s0.x)` — reuses the
   engine's GPU AnimationCurve chunk + database.
 
+#### Two interpreters
+
+The register file normally lives in shader registers, which is what makes it fast and what makes it
+small. An effect whose compiled program wants more slots than it holds is not an error and not an
+authoring ceiling: the whole system swaps emit and simulate for variants whose file is a storage
+buffer, and everything runs, slowly.
+
+- **The trigger is the set, not the program.** `ProgramHeap` reports `max_register_count` over the
+  programs it holds, and `GPUParticleSystem` is where that number is compared against
+  `PARTICLE_VM_FAST_REGISTER_SLOTS` — the store has no opinion about what a register budget means,
+  and which backing a pass is compiled against is the VM's business. One hungry effect moves every
+  emitter onto the wide pair; there is one pipeline per pass and it is chosen once, per frame, in
+  `graph_particles`. It moves back when that effect is unregistered: the heap knows what it holds,
+  so the number is a maximum over the live set rather than a high-water mark.
+- **The launch is bounded.** The wide passes need a register file per invocation in flight, so they
+  do not run one lane per particle — that would size the buffer by pool capacity. They launch
+  `PARTICLE_VM_WIDE_LAUNCH_LANES` lanes whatever the workload and walk their input with a grid-stride
+  loop, so the file is `LANES * SLOTS * 4` bytes and nothing else. The stride is a whole number of
+  workgroups, which is what keeps a wave inside one coherence bucket and the wave-uniform section
+  decode sound.
+- **Slot-major, and never cleared.** `vm_registers[slot * LANES + lane]`, so a wave reading one slot
+  reads a coalesced run. The buffer is transient and no pass zeroes it: a register is undefined until
+  written, and a program that reads one first is corrupt. That is the one place the two backings are
+  not interchangeable — the fast file zeroes, so the reference executor and the fast VM agree on a
+  value the wide VM has no opinion about.
+- **Held to the same bar.** `vm/chunk_particle_vm.spec.js` runs every parity case, fuzz included,
+  against BOTH backings; `shaders/particle_wide_register_passes.spec.js` runs the wide passes against
+  the fast ones under the emulator and exercises the grid-stride loop.
+
 **Parity strategy.** The opcode numbers + operand semantics live in one source of truth
 (`isa/ParticleVMISA.js`). Two executors implement it: a JS reference VM (`vm/ParticleVMReference.js`)
 and a hand-written WGSL interpreter (`vm/chunk_particle_vm.js`). A spec runs identical programs
@@ -93,32 +199,110 @@ executors cover every opcode in the ISA table.
 
 ### Node graph → bytecode
 
-A core `NodeGraph` holds particle nodes (ports + parameters) for SPAWN and UPDATE. `compile()`:
+A core `NodeGraph` holds particle nodes (ports + parameters) for INIT 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,
 4. interns constants into the pool,
 5. resolves curve/attribute references,
-6. emits `Program { spawn, update, constants, reg_count, attributes, curves }`.
+6. emits `Program { init, update, constants, reg_count, attributes, curves }`.
 
 Standard node library: constants, attribute get/set, arithmetic/vector/math, random (uniform/sphere/
 disk/cone), curve-sample, noise (curl), integrate, gravity, emit-shapes, compare/select, kill-if.
 
+### Emitters are scene nodes
+
+`ParticleEmitter extends Node3D`. Add one to a `Scene` — on its own or under a joint — and the
+scene context's membership sweep gives it a `transforms` row like any node; the GPU hierarchy pass
+composes its `global` from its own transform and its parents' every frame, animation included.
+`GPUParticleSystem` sweeps the scene's node list when the scene's membership version moves, gives
+each emitter node a row in the emitter table pointed at its `transforms` row, and retires the row
+when the node leaves. Attaching an emitter to a bone is `joint.addChild(emitter)`; there is no
+per-frame transform copy, and an emitter under a GPU-animated joint follows it — which the old
+CPU-side copy of `transform_global` could not do, since the CPU never updates that matrix for a
+node the GPU owns.
+
+**The node knows nothing about the GPU.** A `ParticleEmitter` is a transform, an attribute
+`layout`, a compiled `program`, a `texture` URL, and the emission parameters — all of it the
+author's, all of it meaning the same thing with no device present, all of it what a saved effect is
+made of. Everything the system assigns is a `GPUParticleEmitterContext`, held by the
+`EmitterRegistry` against the emitter and reached through `registry.context(emitter)`: the table
+row, the generation, the program placement, the node's `transforms` row, the atlas patch. So an
+emitter cannot be saved with a row in it, cannot be given one by hand, and "is this emitter live?"
+is asked of the registry rather than read off a `-1` that anything could have written. The record
+writer is where the two meet — `write_emitter_record(record, emitter, context)`, next to the struct
+it fills.
+
+Restaging is driven by `Node3D#version`, the node's own change counter, which the renderer already
+reads to decide whether a transform needs re-uploading; the context remembers the version its row
+was staged from. An author who edits an emitter says so the way they say it for any node —
+`needsUpdate = true` — and there is no second flag to forget. A change to the context itself (a
+`transforms` row, a repacked atlas patch) moves no version, so the context marks itself instead.
+
 ### Emitter table (`GPUDatabase`)
 
-One `emitters` table (CPU-managed, low churn). Row = `EMITTER_STRUCT`: program offsets+lengths,
-constant-pool offset, spawn rate/burst, world transform + attach row, bounds sphere, flags
-(lighting/soft/sort/cull/blend/projection), render binding (attr offsets for position/size/color/
-rotation/frame), atlas region + flipbook grid, curve handle bank base. Programs+constants live in a
-packed `ProgramArena` buffer (variable length → not a fixed-stride table).
+One `emitters` table (CPU-managed, low churn). Row = `PARTICLE_EMITTER_STRUCT`: program
+offsets+lengths, constant-pool offset, seed, spawn rate, **node** (transforms row), **generation**,
+bounds sphere, flags (lighting/soft/sort/cull/blend/projection), render binding (attr offsets for
+position/size/color/rotation/frame/velocity), atlas region + flipbook grid, and the program id
+the coherence pass buckets on. The atlas region is resolved, not authored: the emitter names an
+image and the system packs it, the way `ShaderManager` packs the old engine's sprites, so a repack
+moves every patch without any emitter changing. The seed is resolved too — an emitter left at 0 gets
+its registration's generation, which no other emitter of the registry shares, rather than being
+written to. Programs+constants live in a packed `ProgramHeap` buffer
+(variable length → not a fixed-stride table).
+
+The struct is the ONLY statement of that layout. The JS writer is the database's
+`write_wgsl_type_value`, and the WGSL reader — the `ParticleEmitter` struct declaration plus
+`database_read_..._element` — is generated from the same struct by the table descriptor. There is no
+hand-packed word offset table to drift out of step with the shaders, and no hand-written reader.
+The bucket histogram, which runs once per live particle and wants only `program_id`, reads it
+through `chunk_read_field` rather than decoding a whole row.
+
+**Editing the set at runtime is the point of using a table.** `EmitterRegistry.add` stages one
+record and `remove` frees one row; neither touches the others. Rows are stable for an emitter's
+lifetime because a live particle's record header holds the row of the emitter that spawned it —
+renumbering a survivor would re-point its particles at somebody else. A removed row is handed back
+to the next `add`, so the id space does not grow without bound.
+
+**Generations make that reuse safe.** Every add takes the next value of one running counter, never
+zero, and the particles of an emitter carry its generation in their header. The simulate pass kills
+any particle whose generation is not its row's current one — the row is zero-filled (generation 0)
+or a later tenant's — so a hard removal frees the emitter's particles within a frame, and a reused
+row cannot adopt a stranger's. Graceful retirement (rate to zero, remove once the tail has died)
+remains an author's choice rather than a correctness rule.
+
+**Programs are edited the same way.** `ProgramHeap` is a pair of range allocators
+(`OffsetAllocator`) over the two sections of the packed buffer, keyed by a `HashMap` on the bytecode
+itself — `ParticleProgram` answers `equals`/`hash`, so content deduplication is the map's doing
+rather than a stringified key's. `acquire` takes a reference and `release` gives one back, so the
+last emitter of an effect is what unpacks it, and `EmitterRegistry.set_program` swaps an emitter onto
+different bytecode while it is live. What makes that possible is that a program is **relocatable**:
+instructions carry no absolute addresses and constant references are program-local, so the heap can
+move one by copying its words and rewriting the placement.
+
+Two things are deliberately NOT reclaimed. **Program ids** are reused rather than renumbered — they
+are baked into every emitter record, so compacting them would mean rewriting the whole table — and
+`bucketCount()` is sized from the id capacity, the set's peak, so it does not move every time an
+effect comes or goes. An id below the peak with nothing in it is an empty bin, which rounds up to
+zero workgroups and shifts nothing after it. **Section capacity** only rises: a repack (which happens
+when a section has no contiguous run long enough) compacts what is live and grows only if it must,
+so a set that peaked at a hundred effects does not pay for a resize every time it returns to three.
+
+A repack is the one change no emitter announces, since it is not an edit to any of them.
+`EmitterRegistry.flush` asks the heap once per frame — `placement_version` — and restages every row
+when it has moved.
+
+Every row of a frame is staged through one module-static record (`EmitterRegistry`), so a flush
+allocates nothing however many rows it restages.
 
 ### Culling & attach
 
-Optional pass tests each emitter's bounds sphere vs. camera frustum, then HiZ occlusion (mirrors
-`chunk_query_depth_from_screen_space_bb`). Culled emitters skip emit/simulate and accumulate sleep
-time; on wake, spawn-count is caught up (bounded steps, like meep's `ParticularEngine`). Emitters
-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.
+An emitter that sets `EMITTER_FLAG.CULL` has its bounds sphere — centre through its node's matrix,
+radius scaled by the matrix's largest axis scale — tested against the camera frustum by the tick
+pass, with the renderer's shared `chunk_sphere_intersects_frustum`. Culled emitters spawn nothing
+and accrue sleep; on wake the tick adds a catch-up of at most `max_catchup_seconds` of rate. Live
+particles keep simulating while their emitter is culled. HiZ occlusion is not written.
 
 ### Two orderings, and why they are separate
 
@@ -134,8 +318,15 @@ diverges, so a wave serially executes the union of the opcodes its lanes want; a
 `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
+The grouping is also **load-bearing**: the simulate shader reads its section parameters (code offset,
+instruction count, constant offset) from the wave's first lane through `subgroupBroadcastFirst`
+(`particle_wave_uniform`), which is what lets the driver fetch instruction words through the scalar
+unit, branch the opcode switch on a scalar and index the register file through M0 without a
+waterfall. A wave holding two programs would run one over the other's particles, so the coherence
+pass is part of simulate's correctness. Emit keeps a per-lane decode: its waves span emitters.
+
+The bucket key is the **program**, not the emitter: `ProgramHeap` deduplicates by content and hands
+back a `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
@@ -151,10 +342,12 @@ whose only cross-workgroup wait is CSDLDF's bounded spin-then-fallback) → scat
 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.
+**Render order** (`sort/`) — per-frame, particles sorted back-to-front by view depth so
+premultiplied transparency composites correctly. Counting sort on a quantised view depth
+(`PARTICLE_SORT_BUCKET_COUNT` bins over `GPUParticleSystem#sort_depth_range`): histogram from the
+camera uniform's view matrix, `graph_prefix_scan_csdldf` the bin counts to offsets, scatter (index
+payload). The sorted index list feeds the instanced draw. Both per-particle passes are bounded by
+the alive counter and dispatched by the args the bucket reset wrote from it.
 
 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 —
@@ -169,102 +362,153 @@ expanded per instance (billboard/velocity-stretch/axis-lock/world modes). Fragme
 (region + flipbook frame), optional forward lighting via `chunk_shade_standard_material_direct` +
 IBL, optional soft-depth fade. Depth-tested, no depth write. Draws into the HDR color target.
 
+### Drawing under the renderer: an AVBOIT side channel
+
+Under `Renderer` the particles are not drawn by the billboard pass above. They go through the AVBOIT
+transparency pipeline (`rasterize/native/avboit/`) as a **side channel** — the contract in
+`AVBOITSideChannel.js` — so they composite order-independently with the transparent meshes and
+against the opaque scene, through the same volume and the same accumulators. Quads are not packed
+into meshlets; the orchestrator asks the channel for its contribution at the three points where the
+meshlet buckets have just made theirs:
+
+1. **occupancy** (`shader_particle_avboit_occupancy`): one thread per emitter row, the emitter's
+   bounds sphere (the culling sphere, through its node's `global`) as a view-depth interval, dilated
+   and OR-ed into the occupancy bits. Per emitter, not per particle — no contention, and a particle
+   that strays lands on a run boundary rather than anywhere wrong. Additive emitters mark nothing.
+   This gives `bounds_radius` teeth on an emitter that never opted into culling: a particle outside
+   the sphere still draws, but its extinction lands in whatever physical slice the warp put nearest,
+   so it occludes at slightly the wrong depth. The sphere should hold the effect.
+2. **splat** (`shader_particle_avboit_splat`): the billboard quads rasterized at the volume's
+   resolution, coverage from the atlas alpha, extinction through `avboit_splat_slice` — the same
+   write path as a surface. Additive particles write nothing. A soft-depth particle is faded here
+   against the same scene depth the draw fades it against, one sample per voxel: what the volume
+   records has to be the coverage the accumulators are weighted by, or a card that fades out where
+   it meets the floor goes on darkening the floor through itself.
+3. **draw** (`shader_particle_avboit_draw`): the quads at internal resolution, depth-tested read-only
+   against the scene (which lets the soft fade read the same depth), fog composited, transmittance
+   from the integral. Which of the two it is, is decided by coverage rather than by the blend enum,
+   so an additive emitter and a premultiplied sprite with no alpha take the same path — as they do
+   in the splat. A covering particle writes `color / norm / extinction` as a surface does, in-scatter
+   included, weighted by the coverage it took. An emitting one writes the fourth accumulator,
+   **emission**: light attenuated by the fog and by the volume in front of it, and carrying none of
+   the fog's own in-scatter, because the resolve adds emission outside the normalization and the
+   scene behind already has it. That accumulator is the one addition to AVBOIT's resolve for this.
+   The whole decision is `chunk_particle_avboit_contribution`, and it is spec'd on the emulator.
+
+No sort: the volume makes order irrelevant, so this path reads the alive list and the draw args
+straight from `simulate`. The billboard vertex stage is one chunk
+(`chunk_particle_billboard_vertex`) shared by the standalone renderer and both AVBOIT passes.
+`GPUParticleSystem` implements the three methods; `Renderer.feature_particles_enabled` runs
+`simulate` before the transparency pass and hands the system to the orchestrator. MBOIT is legacy
+and gets no particle path.
+
+### Ownership: `GPUParticleSystem`
+
+Constructed once against a `GPUSceneContext`, in the mould of `ReSTIRDI`. It owns every persistent
+buffer — pool, alive lists, dead list, counters, both indirect-args buffers, the coherence and sort
+scratch, the emitter database (both tables), the packed program buffer, the spawn-command ring — and grows the ones that depend on the emitter set inside `execute`. The
+default atlas is a 1x1 white texel. `execute({graph, camera, scene_database, color, depth, dt})`
+sweeps the scene, pushes what changed (on a command context opened only when something needs
+one), and records the whole frame through `graph_particles`, returning the colour handle after
+the draw. An integrator does not encode a particle pass by hand.
+
 ## File layout
 
 ```
-src/webgpu/renderer/particles/
+src/shade/renderer/particles/
   DESIGN.md
-  ParticleConstants.js               pool stride, reg count, limits
+  ParticleConstants.js               pool stride, reg count, workgroup sizes, limits
   isa/ParticleVMISA.js               opcode table (single source of truth)
   isa/ParticleProgram.js             Program value type + (de)serialization to u32
   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)
+  vm/chunk_particle_vm_registers_fast.js  register file in var<private> — the interpreter that runs
+  vm/chunk_particle_vm_registers_wide.js  register file in storage — the fallback
+  shaders/chunk_particle_simulate_step.js one particle's simulate, shared by both simulate shaders
+  shaders/chunk_particle_emit_step.js     one newborn's emit, shared by both emit shaders
   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
+  data/PARTICLE_EMITTER_STRUCT.js    the emitter row + flag/blend/projection encoding
+  data/particle_emitter_record.js    emitter + context -> one row of that struct
+  data/PARTICLE_EMITTER_STATE.js     the GPU-owned per-emitter state row (second table of the database)
+  data/PARTICLE_DATABASE_SPEC.js     the GPUDatabase schema, and the emitter table's descriptor
+  data/PARTICLE_COUNTERS.js          counter slot indices
+  data/particle_header.js            record header encoding (row + generation), JS + WGSL
   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
-  runtime/EmitterRegistry.js         GPUDatabase(emitters) + CPU emitter defs
-  shaders/*                          emit / simulate / indirect-args / sort / render
-  cull/*                             frustum + HiZ emitter culling
-  GPUParticleSystem.js               feature class (persistent buffers, execute())
-  graph_particles.js                 per-frame frame-graph wiring
-  *.spec.js                          co-located tests (JS + emulator)
+  runtime/ProgramHeap.js             the one packed [header][constants][code] buffer, allocator-backed
+  runtime/ProgramPlacement.js        where one program sits in it — what an emitter record carries
+  runtime/ParticleEmitter.js         one emitter — a Node3D and an effect, with no GPU in it
+  runtime/GPUParticleEmitterContext.js  what a registry assigns one: row, generation, placement, patch
+  runtime/EmitterRegistry.js         GPUDatabase(emitters) + the live emitters + their contexts + the program heap
+  runtime/create_particle_effect.js  layout + INIT/UPDATE graphs → compiled effect
+  shaders/shader_particle_spawn_commands.js  CPU bursts → pending spawns
+  shaders/shader_particle_emitter_tick.js    per-emitter spawn decision
+  shaders/shader_particle_emit.js            per-newborn INIT, sized by the scan
+  shaders/shader_particle_simulate.js        per-particle UPDATE + compaction + orphan kill
+  shaders/shader_particle_finalize.js        reset counters (+ budget) / build indirect args
+  shaders/shader_particle_render.js          billboard pipeline
+  shaders/chunk_particle_setup_context.js    VM builtins from the emitter's node, + the RNG seed
+  shaders/chunk_particle_emitter_age.js      the tick pass's running age, off the emitter_state table
+  shaders/chunk_particle_curve_disabled.js   the no-curves-bound CURVE provider
+  shaders/chunk_particle_billboard_vertex.js the billboard vertex stage, shared by every draw
+  shaders/chunk_particle_emitter_world_sphere.js the culling / occupancy sphere
+  shaders/shader_particle_avboit_*.js        occupancy / splat / draw through AVBOIT
+  sort/*                             render-order depth sort
+  graph_particles.js                 simulate (to the draw args) + the standalone sort and draw
+  graph_particles_avboit.js          the AVBOIT side channel: occupancy, splat, draw
+  GPUParticleSystem.js               the feature: owns the buffers, sweeps the scene, execute()
+  particle_test_fixtures.js          scene + registry + database words, for the emulator specs
+  *.spec.js                          co-located tests (JS + emulator + software device)
 ```
 
 ## Testing
 
-- Pure JS: layout packing, assembler, register allocator, node compiler, pool/list/arena/emitter
-  bookkeeping (via `SoftwareGPUDevice`).
+- Pure JS: layout packing, assembler, register allocator, node compiler, heap/emitter/registry
+  bookkeeping (via `SoftwareGPUDevice`), the header encoding.
 - WGSL via emulator: VM opcode parity (JS vs WGSL), curve sampling, sort key/depth, atlas+flipbook
-  UV math, billboard expansion, soft-depth fade, emit/simulate kernels on small fixtures.
+  UV math, billboard expansion, soft-depth fade, and every compute pass on small fixtures — the tick
+  (rate integration, generations, pending, budget, culling, page-group walk), emit (expansion over
+  the scan, node position, orphans), simulate, spawn commands, finalize, bucket, sort. Fixtures
+  (`particle_test_fixtures.js`) build a real scene with a `GPUSceneContext` and a real registry, and
+  `gpu_database_words` lays both databases out the way the GPU holds them, so the shaders read rows
+  the real writers wrote.
+- Multi-frame capstone (`particle_lifecycle.spec`): reset → commands → tick → (JS scan) → emit →
+  simulate across frames, with the GPU deciding to spawn, a CPU burst, the budget, and death.
+- Orchestration on `SoftwareGPUDevice`: `GPUParticleSystem.spec` (scene sweep, growth, uploads only
+  when needed, the ring), `graph_particles.spec` (pass sequence, indirect sizing, the two orderings,
+  every persistent buffer imported exactly once), and the playground's `particle_scene.spec` (the
+  integration: geometry → hierarchy → particles → draw).
 - Cross-parity meta-tests: every ISA opcode implemented by both executors.
 
 End-to-end GPU is out of scope for node (no binary GPU dep); emulator + JS references give the
 coverage the brief asks for.
 
-## Implementation status
-
-Built and tested (80 tests, 16 files):
-
-- **VM** — ISA, program, assembler, JS reference executor, WGSL interpreter with full deterministic-
-  opcode parity (fuzz + hand-written) and known-answer RNG.
-- **Node graph → bytecode** — layout, graph, node library, compiler (DAG-share, linear-scan register
-  alloc, error cases), verified on the reference VM.
-- **Emitter data** — packed u32 layout + WGSL reader, flag/blend/projection encoding, transform
-  writer.
-- **Simulate** (single execution shader) and **emit** (spawn) passes — verified through the emulator,
-  including a multi-effect run and the multi-frame lifecycle capstone (`particle_lifecycle.spec`).
-- **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.
-
-Structural (production-patterned, not emulator-runnable — need a real device / framegraph execution):
-the billboard **render pipeline** (`shader_particle_render`, assembly-verified), the **frame-graph
-wiring** (`graph_particles`), the **animation-curve provider** (reuses the engine's curve chunk), and
-the **prototype** effects.
-
 ### Emulator caveats discovered (all correct on real hardware)
 
-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); 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)
-
-To light up in `Renderer.render`, mirroring `feature_restir_di_enabled`/`ReSTIRDI`:
-1. `feature_particles_enabled` flag + `#particles = new GPUParticleSystem(graphics)` in
-   `initialize()`, `get particles()` accessor.
-2. Create the persistent GPU buffers from `GPUParticleSystem.bufferSizes()` /
-   `initialFreeList()`; upload emitter/program/constant buffers from `registry.build()` when dirty.
-3. Each frame: `const requests = system.update(dt, {is_visible})`; upload requests;
-   `graph_particles({graph, gpu, frame})`; append the sort (`sort/shader_particle_sort` +
-   `graph_prefix_scan_csdldf`) and the billboard render pass (into the HDR colour + scene depth
-   attachments) — depth test on, no write, premultiplied blend.
-4. For lit emitters, compile a simulate/render variant that swaps the disabled curve/lighting hooks
+The in-repo WGSL emulator (unit-test tool, not GPU parity) has 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); u32 multiply is imprecise for large operands (PCG can't be checked
+through it); `/` 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, and a
+binary search's `mid` is a shift, not a divide; matrix column indexing (`m[0]`) is not evaluated,
+so an axis scale is read as `m * vec4(1,0,0,0)`. `array<atomic<u32>>` bindings are modeled as
+`{value}` objects in tests; a pass that binds the same buffer as plain `array<u32>` gets a
+`Uint32Array`. The scene context writes a row's `global` one publish behind (the hierarchy pass
+recomposes it on a device), so a node's matrix under the emulator is the one it had when its row
+was seeded.
+
+### Renderer integration
+
+Done: `Renderer.feature_particles_enabled` (off by default), `Renderer.particles(scene_ctx)` creating
+one system per scene context on first use, `simulate` recorded before the transparency pass and the
+system passed to the AVBOIT orchestrator as its side channel. Remaining:
+1. For lit emitters, compile a simulate/render variant that swaps the disabled curve/lighting hooks
    for `chunk_particle_curve_animation` (+ bind `GPUAnimationManager.database.buffer`) and a
    shading-chunk-backed lighting hook (+ the `SHADING_LIGHT_RESOURCE_GROUP`).