@woosh/meep-engine 3.17.1 → 3.18.0

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

@@ -1,514 +1,703 @@
-# GPU-Driven Particle System — Design
-
-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. 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.
-- Node-based composition → shader VM (compile graph → bytecode).
-- 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: 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: INIT + UPDATE)
-             standard node library                       │
-                                                         ▼
-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
-             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
-             ├─ 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 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 budget, …} + derived indirect dispatch/draw args.
-
-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`. 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. 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`)
-
-Register machine, emulator-safe (bounded instruction loop + big `switch`, no subgroup ops, no
-recursion, no data-dependent jumps — conditionals are predicated via CMP/SELECT, destruction via
-`KILL`).
-
-- 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: **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
-through both (WGSL via the emulator) and asserts bit-for-bit-close equality. A meta-test asserts both
-executors cover every opcode in the ISA table.
-
-### Node graph → bytecode
-
-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 { 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 = `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
-
-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
-
-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 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
-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, 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 —
-`PARTICLE_COUNTER.SORTED` belongs to the render order, `SIM_PADDED` to the simulation order.
-
-### Rendering
-
-One render pipeline, one blend state = premultiplied: `color: (one, one-minus-src-alpha)`,
-`alpha: (one, one-minus-src-alpha)`. Additive vs. alpha is chosen by the shader emitting premultiplied
-RGB with alpha 0 (additive) vs. alpha a (normal) — GPU-driven, no pipeline switch. A 6-vertex quad is
-expanded per instance (billboard/velocity-stretch/axis-lock/world modes). Fragment: sample atlas
-(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/shade/renderer/particles/
-  DESIGN.md
-  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/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/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, 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, 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.
-
-### Emulator caveats discovered (all correct on real hardware)
-
-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`).
+# GPU-Driven Particle System — Design
+
+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. 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.
+- Node-based composition → shader VM (compile graph → bytecode).
+- 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: 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: INIT + UPDATE)
+             standard node library                       │
+                                                         ▼
+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
+             emitter state table (GPU-owned: generation, accumulator, age, sleep, pending)
+             ┌─ spawn commands (CPU bursts → pending)
+             ├─ emitter tick  (per row: cull on the published box, integrate rate, take 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
+             ├─ bounds (per particle → per emitter box, published to the state row)
+             ├─ 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 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 budget, …} + derived indirect dispatch/draw args.
+
+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`. 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. 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`; publish the
+   bounding box emit and simulate measured last frame into the state row and reset the accumulator
+   (see **Bounds**); if the emitter opts into culling, test that box 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.
+
+On a frame that registered emitters with a `prewarm`, and only then, a loop of the warm-up pipeline
+(`warmup/`) runs after the frame's own simulate: the same decision-scan-emit shape per tick over a
+transient population, plus an advance of its own, then a migration into the main pool. See
+**Pre-warm**.
+
+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 — and the one field the warm-up pipeline
+writes, as it runs an emitter's clock forward (see **Pre-warm**).
+
+### 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`)
+
+Register machine, emulator-safe (bounded instruction loop + big `switch`, no subgroup ops, no
+recursion, no data-dependent jumps — conditionals are predicated via CMP/SELECT, destruction via
+`KILL`).
+
+- 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: **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
+through both (WGSL via the emulator) and asserts bit-for-bit-close equality. A meta-test asserts both
+executors cover every opcode in the ISA table.
+
+### Node graph → bytecode
+
+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 { 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 = `PARTICLE_EMITTER_STRUCT`: program
+offsets+lengths, constant-pool offset, seed, spawn rate, **node** (transforms row), **generation**,
+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.
+
+Programs are immutable after compilation. Both `registry.set_program(emitter, program)` and replacing
+`emitter.program` followed by `needsUpdate = true` are supported. Flush reconciles replacements
+before inspecting heap relocation, since acquiring a replacement may move other programs too.
+The layout must remain compatible with particles already in flight.
+
+A live program assignment increments `program_assignment_version`. On the next frame, before reset
+or simulation, the previous compact alive list is bucketed again and its padded count and dispatch
+are rebuilt. This prevents a previously shared wave from executing one emitter's newly edited program
+over another emitter's particles. Ordinary frames keep the existing end-of-frame bucketing only;
+content-identical replacements need no repair. Both bucket runs on an edit frame reuse the latest
+graph handles for their scratch buffers, so each persistent buffer is imported once.
+
+The coherence list is persistent GPU state, including its padding. Growing the bucket capacity copies
+it to the replacement buffer before destroying the old one. The old count and indirect dispatch
+remain valid across growth; only the per-frame histogram/cursor/key scratch may be discarded.
+
+Every row of a frame is staged through one module-static record (`EmitterRegistry`), so a flush
+allocates nothing however many rows it restages.
+
+### Bounds
+
+An emitter has no bounds it could declare. Its particles are simulated in world space by arbitrary
+bytecode: they go where the program sends them, at whatever size it gives them, for as long as it
+keeps them alive. The only bound an author could write down and still be right is an infinite one,
+which culls nothing and reserves every depth slice. So the box is **measured**, on the GPU, every
+frame.
+
+Two passes of its own (`bounds/`), at the end of the frame, after emit and simulate have both
+finished appending to the alive list:
+
+- **accumulate** — one thread per live particle: read where its quad is and merge it into its
+  emitter's accumulator. The centre is the record's `render_position`; the dilation is
+  `particle_billboard_radius`, the largest offset `particle_billboard_offset` can produce for that
+  size, velocity and projection, over every corner, every roll and any camera. The box has to hold
+  the *quads*, not the centres, and it has to be camera-independent, because it is read on a later
+  frame. The merge is `aabb_atomic_min_f32` / `aabb_atomic_max_f32`, the same CAS-spin the
+  skinned-mesh bounds refresh uses; both load first and return without a CAS once the box holds the
+  contribution, so what survives is load traffic, not exchanges. Dispatched indirectly from
+  `sim_dispatch_args`, the args the coherence reset wrote from the GPU's own alive count.
+- **publish** — one thread per emitter row: write the accumulation to `bounds_min` / `bounds_max` of
+  the state row (`data/PARTICLE_EMITTER_STATE.js` — measured state is GPU-owned state, and on the
+  record it would be clobbered by the next restage), and reset the accumulator. The reset is
+  unconditional, which is what lets a row that changes hands start clean.
+
+**Why a pass and not a tail on emit and simulate.** It was that first. Booking from inside those two
+measures no single population — simulate sees last frame's survivors and emit sees this frame's
+newborns, so the union spans two frames and is looser than either — and it pays six atomics per
+particle inside the pass whose register pressure decides the system's occupancy, to compute
+something that needs none of the VM, none of the scene, and five words of the record. Over the alive
+list instead, the measurement is of exactly the set that is alive and about to be drawn.
+
+**Where the accumulator lives.** Six words per emitter row, in the **counters** buffer, after the
+counters themselves (`data/PARTICLE_COUNTERS.js`). It has to be an `array<atomic<u32>>` binding, and
+the emitter database cannot be it — the passes that read a record read it out of an `array<u32>`
+binding, and one buffer under two access types is aliasing. The counters buffer is already bound in
+both bounds passes, already atomic, already the system's cross-pass scratch, so a buffer of its own
+would add a binding and a growth path to say the same thing. It therefore grows with the emitter
+table, by copy — the free-list length in it is GPU-owned and unreconstructable — and the rows the
+growth adds are written to the empty interval, because a zeroed accumulator reads back as a
+degenerate box at the world origin rather than as an absence.
+
+**The empty case.** An emitter with no measured particles has infinite, unknown bounds:
+`bounds_min = [-Infinity, -Infinity, -Infinity]`, `bounds_max = [Infinity, Infinity, Infinity]`.
+The CPU stages this on registration and the publish pass restores it whenever the population is
+empty. The tick treats unknown bounds as visible, so a slow emitter can accumulate its first spawn
+without prewarm even when its node is offscreen. A depleted population can restart the same way.
+AVBOIT occupancy skips unknown bounds because there are no live particles to splat. Both readers
+test the sentinel before geometric arithmetic, avoiding NaNs from operations on infinities.
+The sentinel check compares integer bits. The publish pass swaps the empty accumulator's loaded
+endpoints; neither path constructs an infinite floating-point constant, which WGSL rejects at
+shader creation time.
+Measured, nonempty populations continue to use their finite bounds for culling. No bounds are authored.
+Prewarm controls the initial age distribution only; it is not required for culling correctness.
+
+### Pre-warm
+
+A continuous effect that starts empty grows into its steady state over one particle lifetime, in
+front of whoever is watching. `ParticleEmitter.prewarm` — seconds, `0` for off — buys that lifetime
+back: an emitter registered with one is run forward by that long before it is first drawn.
+
+**A warm-up is the ordinary loop, run over a population of its own.** Spawn, init, advance, per
+tick, until every emitter in the batch has been running for its own `prewarm`. It is *not* a batch
+of particles dumped in one tick and aged: the emitter keeps spawning throughout, what dies is
+replaced as it is in a live scene, and whatever drives the rate — a spawn curve, `EMITTER_AGE`, the
+program itself — drives it here, because it is the same program being run. What the loop leaves is
+the population the emitter would have had.
+
+**It is a pipeline apart from the main one** (`warmup/`), because the main one is tuned and must not
+pay for this. Emit and simulate are the passes whose register pressure sets the system's occupancy,
+and their waves are kept program-uniform by the bucketing; a warm-up folded into either would spend
+registers on every frame for work that happens on one, and a loop inside a lane would break the
+uniform flow across a wave. So the warm-up shares code with the main frame and integrates nothing
+into it: the main **emit pass is reused unchanged**, bound to the warm-up's buffers; the tick is a
+pass of the warm-up's own over a host-written queue (`shader_particle_warmup_tick`) rather than over
+the emitter table; the **advance** is a pass of the warm-up's own (`chunk_particle_warmup_step.js`),
+decoding the program section per lane — it reads the raw alive list, so it cannot lean on the
+bucketing's wave-uniformity, and its occupancy is its own business. The main passes' compiled code
+is byte-identical whether `warmup/` exists or not.
+
+**The population is transient.** Pool, both alive lists, free list and counters are frame-graph
+transients that exist for the loop and are then moved, record by record, into the main pool by the
+**migrate** pass — a pop from the main free list per particle, and never a push, so it is the one
+point of contact and it is safe by construction. The loop's own free-list traffic never touches the
+main list, and the main passes never see a half-warmed particle.
+
+**Bounded.** `warmup/warmup_schedule.js`: at most `PARTICLE_WARMUP_MAX_TICKS` ticks, no shorter than
+`PARTICLE_WARMUP_TICK_SECONDS`, the tick *length* stretching to cover the longest pre-warm in the
+batch rather than the count growing to cover it — the count is what the frame pays for, at six or
+seven dispatches a tick. An emitter takes part in a tick once the loop's clock is within its own
+pre-warm of now, so two emitters queued with different durations each end having run for exactly
+their own; the shorter one sat out the start.
+
+**Jittered, so it does not arrive in bands.** Every particle born in one tick would otherwise reach
+the end with exactly that tick's age, and N ticks would read as N cohorts. The advance jitters the
+tick per particle (`PARTICLE_WARMUP_DT_JITTER`, hashed from slot and tick — a hash, not a draw, so
+the program's own random stream is untouched), and the host jitters each emitter's clock and starting
+accumulator (`PARTICLE_WARMUP_EMITTER_JITTER`), so emitters in one batch do not spawn on the same
+beat either. A program does not care what `DELTA_TIME` it is handed; the smear is free.
+
+**Where it sits.** After the frame's own emit and simulate, before the bucketing. Migrate appends to
+the same alive list they did, so the bucketing puts the warmed particles in next frame's simulate
+list, the bounds pass measures them into their emitter's box this frame, and the draw draws them
+this frame. The tick also writes the emitter's
+`age` into its state row as it goes, so `EMITTER_AGE` reads as it would have, and the next real tick
+adds its `dt` to a row that says `prewarm`.
+
+**Only on the frame that needs it.** The host knows: an emitter is queued when it is registered with
+a `prewarm` (`GPUParticleSystem#sync_membership`), the queue is uploaded and consumed by the frame
+that records the loop, and an ordinary frame records nothing of this.
+
+The editor's CPU preview (`editor/particles/effect/ParticleReferenceSimulation.js`) runs the same
+loop over the same schedule before its first frame, and restarts the effect when the duration
+changes: a pre-warm is a statement about how an effect starts, so the only way to show one is to
+start it.
+
+### Culling & attach
+
+An emitter that sets `EMITTER_FLAG.CULL` has the box on its state row tested against the camera
+frustum by the tick pass, with the renderer's shared `chunk_aabb3_intersects_frustum`. The tick does
+not measure it — it reads what the bounds passes published at the end of the previous frame — so all
+that is in the spawn path is one frustum test. Because the box is where the particles are rather
+than where the node is, an effect whose particles have drifted on screen keeps spawning even when
+its emitter has not. 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, so its box keeps moving and keeps being published. HiZ occlusion is not
+written.
+
+### 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 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
+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, 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 —
+`PARTICLE_COUNTER.SORTED` belongs to the render order, `SIM_PADDED` to the simulation order.
+
+### Rendering
+
+One render pipeline, one blend state = premultiplied: `color: (one, one-minus-src-alpha)`,
+`alpha: (one, one-minus-src-alpha)`. Additive vs. alpha is chosen by the shader emitting premultiplied
+RGB with alpha 0 (additive) vs. alpha a (normal) — GPU-driven, no pipeline switch. A 6-vertex quad is
+expanded per instance (billboard/velocity-stretch/axis-lock/world modes). Fragment: sample atlas
+(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.
+Soft-depth fading scales both RGB and alpha for premultiplied inputs; straight-alpha and additive
+inputs have alpha scaled before premultiplication. Both draw paths share `particle_fade_color`.
+
+### 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
+   measured box (the culling box, off the state row) as a view-depth interval, dilated and OR-ed
+   into the occupancy bits. The interval is the box's centre depth plus or minus its extent along
+   the view axis — a support projection, not eight transformed corners. 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. The box matters here even for an emitter that never opted
+   into culling, which is the second reason it is measured for every emitter rather than only for
+   the ones that cull.
+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.
+
+### Texture ownership: ECS
+
+`engine/graphics3/GPUParticleEmitterSystem.js` owns the sprite atlas for one Shade scene. Construct it
+with `(graphicsEngine, scene, assetManager)` and add it to the EntityManager. It observes the scene's
+existing `ParticleEmitter` nodes; there is no second component or transform to synchronize. It is
+opt-in and can coexist with the legacy CPU `ParticleEmitterSystem`.
+
+```js
+entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager));
+```
+
+The system loads image URLs through `AssetManager` (`GameAssetType.Image`) and shares one patch per
+URL. It reuses `TextureAtlas`, whose packer is `MaxRectanglesPacker`. When the last emitter releases
+an image, its patch is removed. Loads completing after a URL change, removal or shutdown are ignored.
+Failed images are reported and remain transparent until the URL changes or the emitter is re-added.
+Untextured emitters use a white texel; pending images use a transparent texel.
+
+At `FrameStart`, after the scene context has established transform rows, the system calls
+`GPUParticleSystem.sync_membership()`, uploads changed atlas pixels, and refreshes all patch regions.
+This occurs before particle simulation stages emitter rows. Every repack or resize therefore updates
+existing emitters too. The extension enables the renderer's GPU particle feature for its scene;
+rendering uses the existing AVBOIT path. The system owns a `GPUTextureContext` for the atlas, using
+its resize and cached-view handling and advancing its version after each pixel upload. Shutdown
+restores the default atlas and destroys the owned context. A replacement device gets a fresh upload
+from the retained CPU atlas.
+
+`GPUParticleSystem` itself does no asset loading or packing. Standalone callers can still supply
+`atlas`/`atlas_sampler` and call `registry.set_atlas_region()` themselves. The `atlas` binding remains
+a `GPUTextureView`, obtained from its owner's context; the default white texture is also owned
+through `GPUTextureContext`.
+
+### 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/shade/renderer/particles/
+  DESIGN.md
+  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/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/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_spawn_budget.js     take from the frame's spawn budget; both ticks spend it
+  warmup/warmup_schedule.js                  ticks and tick length for a batch of pre-warms
+  warmup/shader_particle_warmup.js           init / reset / tick over the host's queue / migrate
+  warmup/chunk_particle_warmup_step.js       one particle's advance: per-lane decode, jittered tick
+  warmup/shader_particle_warmup_advance.js   the advance over the fast file (+ _wide.js)
+  warmup/graph_particle_warmup.js            the loop, recorded on a frame that registered a pre-warm
+  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/shader_particle_avboit_*.js        occupancy / splat / draw through AVBOIT
+  bounds/*                           the measured emitter box: accumulate, publish
+  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()
+  *.spec.js                          co-located tests (JS + emulator + software device)
+```
+
+## Testing
+
+- 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, 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. Each such spec
+  carries its own copy of the scaffolding: a real scene with a `GPUSceneContext` and a real registry,
+  laid out by `gpu_database_words` the way the GPU holds both databases, 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.
+
+Regression checks use the existing tools: seeded software-device buffer copies for list growth,
+recorded pass ordering for program edits, emulator math for blend/fade and unknown bounds, and real
+AssetManager/TextureAtlas bookkeeping with a stub image loader for asynchronous atlas lifetimes.
+No full software WebGPU implementation or cross-frame shader simulator is added. The emulator's
+`subgroupBroadcastFirst` is identity, so grouping correctness is checked at its input contract.
+
+End-to-end GPU is out of scope for node (no binary GPU dep); emulator + JS references give the
+coverage the brief asks for.
+
+### Emulator caveats discovered (all correct on real hardware)
+
+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`).