@woosh/meep-engine 3.34.0 → 3.36.0

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

@@ -1,1244 +1,1247 @@
-import { assert } from "../../../core/assert.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
-import { warn_limited } from "../../util/warn_limited.js";
-import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
-import {
-    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    PARTICLE_SPAWN_COMMAND_WORDS,
-    PARTICLE_VM_FAST_REGISTER_SLOTS,
-    PARTICLE_WARMUP_EMITTER_JITTER,
-    PARTICLE_WARMUP_QUEUE_WORDS,
-} from "./ParticleConstants.js";
-import {
-    PARTICLE_BOUNDS_WORDS,
-    PARTICLE_COUNTER,
-    PARTICLE_COUNTER_COUNT,
-    particle_bounds_empty_words,
-    particle_counters_word_count,
-} from "./data/PARTICLE_COUNTERS.js";
-import { graph_particles_simulate } from "./graph_particles.js";
-import {
-    PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE,
-    shader_particle_init_free_list,
-} from "./shaders/shader_particle_init_free_list.js";
-import {
-    graph_particle_avboit_draw,
-    graph_particle_avboit_occupancy,
-    graph_particle_avboit_splat,
-} from "./graph_particles_avboit.js";
-import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { WARMUP_QUEUE } from "./warmup/shader_particle_warmup.js";
-import { warmup_schedule } from "./warmup/warmup_schedule.js";
-import { GPUTextureContext } from "../texture/GPUTextureContext.js";
-import { inspect_gpu_buffer } from "../buffer/inspect_gpu_buffer.js";
-
-const WORD = Uint32Array.BYTES_PER_ELEMENT;
-
-/*
- A wide usage mask costs bandwidth: the driver places a buffer by what it was told the buffer might
- have to do, and the flags below are what each one actually does. `pool` and the alive lists are the
- big ones and are touched by nothing but shaders. Adding a flag "just in case" moves 64 MiB onto a
- slower path for a copy nobody makes — see `BufferResourceDescriptor`.
-*/
-/** Written only by shaders. The free list is one of these: `init_free_list` fills it on-device. */
-const STORAGE = GPUBufferUsage.STORAGE;
-/** Seeded or refilled from the host with `writeBuffer`. */
-const STORAGE_UPLOAD = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
-/** Uploaded, and copied forward into its replacement when the emitter set outgrows it. */
-const STORAGE_GROWABLE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
-/**
- * An indirect command the GPU writes and the GPU consumes. COPY_SRC is for {@link
- * GPUParticleSystem#read_stats}, which reads the args back to show that the dispatch really is
- * sized on-device — twelve bytes.
- */
-const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
-
-const DEFAULT_CAPACITY = 524288;
-
-/**
- * What {@link GPUParticleSystem#read_stats} decodes: the counts the GPU keeps between frames, named.
- *
- * @typedef {object} ParticleSystemStats
- * @property {number} alive live particles the frame ended with
- * @property {number} dead length of the free list
- * @property {number} spawn_budget free slots the frame never promised to a spawn — its headroom
- * @property {number} alive_in entries the frame's simulate consumed — the padded, program-coherent
- *   list the frame before it built, so never fewer than that frame's `alive`
- * @property {number} sim_padded length of the padded, program-coherent simulate list built this
- *   frame; the gap to `alive` is what keeping each wave on one VM program costs in lanes
- * @property {number} sim_workgroups workgroups the NEXT simulate will dispatch — read out of the
- *   indirect args rather than derived, so it is what the GPU will actually launch
- */
-
-/**
- * The GPU particle system: a feature of a scene, in the mould of `ReSTIRDI` — construct once
- * against a {@link GPUSceneContext}, and contribute the frame's passes through
- * {@link execute}.
- *
- * ## What it owns
- *
- * Persistent GPU state, and only that: a buffer is reserved here if and only if its contents have
- * to survive to the next frame. That is the particle pool, the alive list, the dead
- * free-list, the counters, the simulation-order (coherence) list, simulate's indirect dispatch args
- * (written at the end of one frame, read by the next), the emitter database (the emitter table and
- * the GPU-owned state table, one buffer), the packed program buffer, and the two CPU-uploaded
- * queues — the spawn-command ring and the warm-up queue. Buffers that depend on the emitter set —
- * the coherence list on the number of distinct programs, the program buffer on the heap, the
- * database on its own pages, the counters on the emitter table's element capacity (they carry the
- * per-emitter bounds accumulator, see `bounds/`) — are grown inside {@link execute}, the way
- * ReSTIR's reservoirs follow the resolution.
- *
- * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
- * draw args, the spawn counts and the VM's wide register file are produced and consumed inside one
- * graph, so the pass that first writes each one declares it and the graph allocates it just in time
- * and releases it after its last reader — into the pool the rest of the renderer allocates from.
- * Reserving them here instead would be megabytes at the default capacity that no other feature
- * could ever borrow, and most of them are cleared by a reset pass every frame regardless.
- *
- * ## The alive list is borrowed, not reserved
- *
- * The alive list crosses the frame boundary and so cannot be the graph's — but it does not have to
- * be the feature's either. It is taken from the graphics context's buffer allocator and given back
- * every frame ({@link #swap_alive_list}), which is the difference between one list and two.
- *
- * Two was the obvious reading of the ping-pong: the frame builds a new list while the previous one
- * is still there to be read. But nothing reads the previous one. Emit and simulate append to the
- * new list from a counter the frame resets to zero, the draws walk that same new list, and the only
- * pass that ever looks at the one before it is the bucketing rebuild on a frame whose program
- * assignments changed — a live program edit, not a frame. So on an ordinary frame the previous list
- * goes back to the pool BEFORE the new one is asked for, the pool answers with the same memory, and
- * the feature's reserved footprint is one list rather than two. On the rare frame that does rebuild,
- * the old list is held one frame longer — until the graph recorded around it has been submitted —
- * and the feature briefly costs what it used to cost always.
- *
- * Every pass stays within the eight storage buffers a stage gets by default: the emitter record
- * and the GPU-owned state are two tables of one database buffer, and the VM's constants and code
- * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
- * simulate passes bind a ninth for the register file — inside the ten the engine already demands of
- * an adapter, but past the default.
- *
- * ## Two interpreters
- *
- * The VM's register file normally lives in shader registers, and is therefore small — see
- * {@link ./ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}. An effect whose compiled program
- * needs more than it holds does not fail: the whole system swaps emit and simulate for variants
- * that keep the file in a storage buffer, which is far slower and effectively unbounded. The choice
- * is per-frame, whole-system, and made here — the registry reports `max_register_count` over the
- * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
- * a register ceiling.
- *
- * ## Emitters are registered at rows
- *
- * {@link add_emitter} gives a {@link ParticleEmitter} a row in the emitter table pointed at a
- * `transforms` row — an entity's, one on, held through the scene context's rows by whoever owns
- * the entity — and it starts spawning on the next {@link execute}; under a joint's row it moves
- * with the joint. {@link remove_emitter} retires the row and frees its particles. Nothing here
- * walks the scene: an emitter is where its owner says it is, and per-frame upkeep is proportional
- * to what changed rather than to how many emitters there are.
- *
- * ## Spawning is the GPU's decision
- *
- * The CPU never counts particles or walks emitters per frame. The emitter tick pass integrates
- * every emitter's rate on the GPU, and the emit dispatch is sized by a prefix scan of what it
- * decided. The host's one way to ask for particles is {@link spawn}: a burst queued into a small
- * command list that a pass adds to the emitter's pending spawns, on the same path as everything
- * else. See `graph_particles.js` for the frame.
- *
- * ## Drawing
- *
- * {@link execute} is the whole per-frame call, once per frame, and it records only the simulation:
- * everything that moves particles, leaving the alive list and the indirect draw args as graph
- * handles. It draws nothing.
- *
- * The drawing is the transparency pipeline's. The system is an `AVBOITSideChannel`, and the AVBOIT
- * orchestrator asks it for its occupancy, its extinction and its draw at the three points where the
- * transparent meshes have contributed theirs ({@link avboit_occupancy}, {@link avboit_splat},
- * {@link avboit_draw}). Those read the handles `execute` produced and composite into a voxel volume
- * and a set of accumulators that are sums — so the particles need no depth ordering at all, and
- * none is ever built.
- *
- * ## Allocation
- *
- * The per-frame path allocates the frame graph's records and nothing else: emitter rows are
- * staged through one shared record, spawn commands go into a preallocated ring, and the
- * per-dispatch settings are reused objects. A command context is opened only on frames that have
- * something to upload.
- */
-export class GPUParticleSystem {
-
-    /**
-     * Engine GraphicsContext.
-     * @type {object}
-     */
-    graphics;
-
-    /**
-     * The scene whose rows the emitters are placed at, and whose database their world matrices
-     * come from.
-     * @type {import("../scene/GPUSceneContext.js").GPUSceneContext}
-     */
-    scene_context;
-
-    /**
-     * Maximum number of simultaneously live particles.
-     * @type {number}
-     */
-    capacity;
-
-    /**
-     * @type {EmitterRegistry}
-     */
-    registry;
-
-    /**
-     * Frames elapsed. The VM's frame builtin.
-     * @type {number}
-     */
-    frame = 0;
-
-    /**
-     * Seconds since start, the VM's `TIME` builtin. Advanced by `dt` each {@link execute}.
-     * @type {number}
-     */
-    time = 0;
-
-    /**
-     * Cap on how much missed time a culled emitter makes up for when it comes back into view.
-     * @type {number}
-     */
-    max_catchup_seconds = 1;
-
-    /**
-     * Sprite atlas the billboards sample, and the sampler they sample it with. A 1x1 white texel by
-     * default, so an emitter with no art draws as a plain quad rather than nothing.
-     * @type {GPUTextureView}
-     */
-    atlas;
-
-    /** @type {GPUSampler} */
-    atlas_sampler;
-
-    /**
-     * The persistent GPU buffers, by the names the graph functions bind them under. Exposed for
-     * inspection — {@link bufferSizes} measures them, {@link read_stats} reads the counts out of
-     * them — never for the frame loop, which reads nothing back. Entries that grow with the
-     * emitter set are replaced in place.
-     *
-     * `alive` and `alive_write` are one buffer under two names — what the feature holds, and what
-     * the frame writes — and `alive_read` is the previous frame's list, present only on the frames
-     * that read one. The list itself belongs to the allocator, not here; see {@link #swap_alive_list}.
-     *
-     * @type {object}
-     */
-    buffers = {};
-
-    /**
-     * Distinct programs the coherence scratch is currently sized for.
-     * @type {number}
-     */
-    #sim_bucket_capacity = 0;
-
-    /**
-     * What the alive list is asked for under: one `u32` per pool slot, touched by nothing but
-     * shaders, and deliberately not cleared — every entry a reader sees was appended this frame,
-     * from a counter the frame's first pass resets to zero, so whatever the last borrower left in
-     * it is unreadable by construction. One instance, reused: the pool reads a descriptor and does
-     * not keep it.
-     *
-     * @type {BufferResourceDescriptor}
-     */
-    #alive_descriptor;
-
-    /**
-     * The alive list the last recorded frame built — the next frame's `alive_read`. Borrowed from
-     * `graphics.buffer_allocator_main`, so it is released rather than destroyed.
-     * @type {GPUBuffer|null}
-     */
-    #alive = null;
-
-    /**
-     * An alive list a recorded frame still reads: the bucketing rebuild's input on a frame whose
-     * program assignments changed. Handed back on the next {@link execute}, by which point that
-     * frame's graph has been executed and submitted.
-     * @type {GPUBuffer|null}
-     */
-    #alive_retired = null;
-
-    /**
-     * The spawn-command ring: `[row, count]` pairs, filled by {@link spawn}, merged and uploaded on
-     * the next {@link execute}.
-     * @type {Uint32Array}
-     */
-    #spawn_commands;
-
-    /**
-     * The emitter each ring entry was issued for, so an entry whose emitter has since left the
-     * scene — or whose row has gone to somebody else — is dropped at upload rather than delivered
-     * to the row's next tenant.
-     * @type {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
-     */
-    #spawn_command_emitters;
-
-    /** @type {number} */
-    #spawn_command_count = 0;
-
-    /**
-     * Scratch for merging the ring: pending count by row. Grown with the emitter table, never per
-     * frame.
-     * @type {Uint32Array}
-     */
-    #spawn_by_row = new Uint32Array(0);
-
-    /**
-     * Emitters registered since the last frame with a pre-warm to run — the input of the warm-up
-     * pipeline (`warmup/`), consumed by the frame that records it. Filled where the emitter is
-     * registered ({@link add_emitter}), which is the one moment the host knows an emitter is
-     * new: the GPU decides everything else about spawning, but "this one has just arrived and asks
-     * to arrive warm" is a host-side fact.
-     *
-     * @type {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
-     */
-    #warmup_queue = [];
-
-    /**
-     * The queue as the GPU reads it, `PARTICLE_WARMUP_QUEUE_WORDS` per entry — see
-     * `warmup/shader_particle_warmup.js`. Grown to fit, never per frame.
-     * @type {Uint32Array}
-     */
-    #warmup_words = new Uint32Array(0);
-
-
-    /**
-     * The 1x1 white texture {@link atlas} points at until a caller replaces it. Held so
-     * {@link destroy} can free it; a caller that assigns its own atlas owns that one.
-     * @type {GPUTextureContext|null}
-     */
-    #default_atlas = null;
-
-
-    /**
-     * Program assignments used to build the previous frame's coherence list.
-     * @type {number}
-     */
-    #program_assignment_version = 0;
-
-    /**
-     * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
-     * @type {object}
-     */
-    #frame = {
-        dt: 0, time: 0, index: 0, max_catchup: 1, spawn_command_count: 0,
-        warmup_count: 0, warmup_capacity: 0, warmup_schedule: null,
-        rebucket: false,
-    };
-
-    /** @type {{capacity: number, group_count: number}} */
-    #emitters = { capacity: 0, group_count: 0 };
-
-    /**
-     * This frame's simulation, for the side channels that draw it later in the frame: the graph it
-     * was recorded into, the scene database handle it read, and the handles it produced. Reused,
-     * never reallocated.
-     * @type {{graph: object|null, scene_database: number, emitter_group_count: number, handles: object|null}}
-     */
-    #simulated = { graph: null, scene_database: -1, emitter_group_count: 0, handles: null };
-
-    /**
-     * @param {object} graphics engine GraphicsContext (has `.device`)
-     * @param {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
-     * @param {object} [options]
-     * @param {number} [options.capacity] max simultaneous particles
-     * @param {number} [options.spawn_command_capacity] most {@link spawn} calls one frame keeps
-     */
-    constructor(graphics, scene_context, { capacity = DEFAULT_CAPACITY, spawn_command_capacity = 256 } = {}) {
-        assert.defined(graphics, "graphics");
-        assert.defined(scene_context, "scene_context");
-        assert.equal(scene_context.isGPUSceneContext, true, "scene_context.isGPUSceneContext !== true");
-        assert.isPositiveInteger(capacity, "capacity");
-        assert.isPositiveInteger(spawn_command_capacity, "spawn_command_capacity");
-
-        this.graphics = graphics;
-        this.scene_context = scene_context;
-        this.capacity = capacity;
-
-        this.registry = new EmitterRegistry(graphics.device);
-
-        this.#spawn_commands = new Uint32Array(spawn_command_capacity * PARTICLE_SPAWN_COMMAND_WORDS);
-        this.#spawn_command_emitters = new Array(spawn_command_capacity).fill(null);
-
-        this.#create_buffers();
-        this.#create_default_atlas();
-    }
-
-    /**
-     * The buffer the emitter table lives in — what every emitter-reading pass binds.
-     * @returns {GPUBuffer}
-     */
-    get emitter_database() {
-        return this.registry.database.buffer;
-    }
-
-    /**
-     * The live emitters, in no particular order.
-     * @returns {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
-     */
-    get emitters() {
-        return this.registry.emitters;
-    }
-
-    /**
-     * Number of simulation-order buckets — one per program id the registry can hand out, which is
-     * its peak number of distinct compiled programs rather than its current one.
-     *
-     * This is the coherence pass's only host-provided number, and it is static topology rather than
-     * per-frame state: it changes when an effect the set has never held is registered, not as
-     * particles are born and die. Everything the pass measures per frame stays on the GPU. Sizing it
-     * from the peak rather than the live count is what keeps it from moving every time an effect is
-     * unregistered — the bins of released ids are empty, and an empty bin rounds up to zero
-     * workgroups and shifts nothing after it.
-     *
-     * @returns {number}
-     */
-    bucketCount() {
-        return Math.max(1, this.registry.program_id_capacity);
-    }
-
-    /**
-     * Ask for `count` particles from an emitter, on top of its rate, on the next frame. Goes
-     * through the GPU path — the tick pass folds it into the emitter's accumulator, the budget and
-     * the culling apply — so it is a request, not a guarantee.
-     *
-     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter a registered emitter
-     * @param {number} count
-     */
-    spawn(emitter, count) {
-        assert.defined(emitter, "emitter");
-        assert.isNonNegativeInteger(count, "count");
-
-        const context = this.registry.context(emitter);
-
-        assert.defined(context, "emitter is not registered");
-
-        const ring = this.#spawn_commands;
-        const base = this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS;
-
-        if (base >= ring.length) {
-            // the text is the key warn_limited counts on, so it carries no burst size: one message
-            // per ring size, not one per number a caller happens to ask for
-            warn_limited(`GPUParticleSystem: spawn command ring is full (${ring.length / PARTICLE_SPAWN_COMMAND_WORDS} per frame); dropping this frame's remaining bursts`);
-            return;
-        }
-
-        ring[base] = context.row;
-        ring[base + 1] = count;
-        this.#spawn_command_emitters[this.#spawn_command_count] = emitter;
-        this.#spawn_command_count++;
-    }
-
-    /**
-     * The system's whole contribution to the frame, once per frame: reconcile the emitter set with
-     * the scene, push what changed to the GPU, and record every pass that moves particles — through
-     * to the indirect draw args.
-     *
-     * It draws nothing and touches no colour target. The handles it returns are what the AVBOIT
-     * side channels ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}) consume
-     * later in the same frame, off this same graph, once the transparent meshes have contributed
-     * theirs.
-     *
-     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
-     * emitter's `transforms` row is uploaded, and after the hierarchy pass has run, so the rows'
-     * `global` matrices are this frame's.
-     *
-     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
-     * handles into the graph it recorded into; a second view of the same scene records a second
-     * graph and would step the simulation twice. The renderer has one view per `render` call today,
-     * so this holds by construction; a second view of one scene needs the step and the handles
-     * separated — record the passes for the first graph, import the same buffers into the rest.
-     *
-     * @param {object} params
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
-     * @param {number} params.camera graph handle of the camera uniform buffer
-     * @param {number} params.scene_database graph handle of the scene database — the one the
-     *   hierarchy pass returned, so this reads the matrices it composed
-     * @param {number} params.dt seconds since the previous frame
-     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
-     */
-    execute({ graph, camera, scene_database, dt }) {
-        assert.defined(graph, "graph");
-        assert.isNumber(dt, "dt");
-
-        this.#upload();
-
-        const frame = this.#frame;
-        frame.dt = dt;
-        frame.time = this.time;
-        frame.index = this.frame;
-        frame.max_catchup = this.max_catchup_seconds;
-        frame.spawn_command_count = this.#spawn_command_count;
-        frame.rebucket = this.#program_assignment_version !== this.registry.program_assignment_version;
-        this.#program_assignment_version = this.registry.program_assignment_version;
-
-        const table = this.registry.table;
-        const emitters = this.#emitters;
-        emitters.capacity = table.element_capacity;
-        emitters.group_count = table.dispatch_group_count(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE);
-
-        const buffers = this.buffers;
-
-        this.#swap_alive_list(frame.rebucket);
-
-        // The table's database owns and grows its own buffer; it is re-read every frame for that
-        // reason.
-        buffers.emitter_database = this.registry.database.buffer;
-
-        const simulated = graph_particles_simulate({
-            graph,
-            camera,
-            scene_database,
-            gpu: buffers,
-            emitters,
-            capacity: this.capacity,
-            bucket_count: this.bucketCount(),
-            // Whose register file the VM runs on is decided here, once, for the whole system: the
-            // registry reports what the hungriest registered effect needs and this compares it
-            // against what the fast file holds. Re-read every frame because registering an emitter —
-            // or unregistering the one hungry effect — can flip it either way.
-            wide_registers: this.registry.max_register_count > PARTICLE_VM_FAST_REGISTER_SLOTS,
-            frame,
-        });
-
-        // Kept for the side channels that draw later in this frame, and for nothing past it.
-        const current = this.#simulated;
-        current.graph = graph;
-        current.scene_database = scene_database;
-        current.emitter_group_count = emitters.group_count;
-        current.handles = simulated;
-
-        // Consumed: the counts were recorded into the graph, the words were uploaded.
-        this.#spawn_command_count = 0;
-        this.#warmup_queue.length = 0;
-
-        this.frame++;
-        this.time += dt;
-
-        return simulated;
-    }
-
-    /**
-     * What this frame's {@link execute} left, checked against the graph a side-channel call names:
-     * the AVBOIT orchestrator records its passes into the same graph, later in the same frame.
-     *
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
-     * @returns {{graph: object, scene_database: number, emitter_group_count: number, handles: import("./graph_particles.js").ParticleSimulationHandles}}
-     */
-    #simulated_for(graph) {
-        const current = this.#simulated;
-
-        assert.equal(current.graph, graph, "the particles were not simulated into this graph this frame — call execute() before the transparency pipeline records");
-
-        return current;
-    }
-
-    /**
-     * `AVBOITSideChannel#avboit_occupancy`: the emitters' measured bounding boxes, as depth slices.
-     *
-     * @param {object} args see `AVBOITSideChannel`
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
-     * @param {number} args.camera graph handle of the camera uniform buffer
-     * @param {ArrayLike<number>} args.cluster_parameters the frame's depth curve
-     * @param {number} args.occupancy graph handle of the occupancy bits
-     * @returns {number} the occupancy handle after the write
-     */
-    avboit_occupancy({ graph, camera, cluster_parameters, occupancy }) {
-        const current = this.#simulated_for(graph);
-
-        return graph_particle_avboit_occupancy({
-            graph,
-            camera,
-            cluster_parameters,
-            occupancy,
-            emitter_database: current.handles.emitter_database,
-            emitter_group_count: current.emitter_group_count,
-        });
-    }
-
-    /**
-     * `AVBOITSideChannel#avboit_splat`: the live particles' extinction, into the volume.
-     *
-     * @param {object} args see `AVBOITSideChannel`
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
-     * @param {number} args.camera graph handle of the camera uniform buffer
-     * @param {number} args.warp graph handle of the warp LUT
-     * @param {number} args.depth_texture graph handle of the scene depth
-     * @param {{extinction: number, overflow: number, dummy: number}} args.volume the voxel volume
-     * @returns {{extinction: number, overflow: number, dummy: number}} the volume after the write
-     */
-    avboit_splat({ graph, camera, warp, depth_texture, volume }) {
-        const { handles } = this.#simulated_for(graph);
-
-        return graph_particle_avboit_splat({
-            graph,
-            camera,
-            warp,
-            depth_texture,
-            volume,
-            atlas: this.atlas,
-            atlas_sampler: this.atlas_sampler,
-            pool: handles.pool,
-            alive: handles.alive,
-            emitter_database: handles.emitter_database,
-            draw_args: handles.draw_args,
-        });
-    }
-
-    /**
-     * `AVBOITSideChannel#avboit_draw`: the live particles, into the accumulators.
-     *
-     * @param {object} args see `AVBOITSideChannel`
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
-     * @param {import("../view/GPUViewContext.js").GPUViewContext} args.view_ctx
-     * @param {number} args.camera graph handle of the camera uniform buffer
-     * @param {number} args.depth_texture graph handle of the scene depth
-     * @param {number} args.warp graph handle of the warp LUT
-     * @param {number} args.integral graph handle of the integral texture
-     * @param {number} args.volumetrics_lut graph handle
-     * @param {number} args.volumetrics_metadata graph handle
-     * @param {{color: number, norm: number, extinction: number, emission: number}} args.accumulators
-     * @returns {{color: number, norm: number, extinction: number, emission: number}} after the draw
-     */
-    avboit_draw({ graph, view_ctx, camera, depth_texture, warp, integral, volumetrics_lut, volumetrics_metadata, accumulators }) {
-        const { handles } = this.#simulated_for(graph);
-
-        return graph_particle_avboit_draw({
-            graph,
-            view_ctx,
-            camera,
-            depth_texture,
-            warp,
-            integral,
-            volumetrics_lut,
-            volumetrics_metadata,
-            accumulators,
-            atlas: this.atlas,
-            atlas_sampler: this.atlas_sampler,
-            pool: handles.pool,
-            alive: handles.alive,
-            emitter_database: handles.emitter_database,
-            draw_args: handles.draw_args,
-        });
-    }
-
-    /**
-     * Register an emitter at a `transforms` row, and if it asks, warm it up before its first frame.
-     *
-     * The row is an entity's, one on (`row_of_entity`), and whoever owns the entity holds it through
-     * the scene context's rows for as long as the emitter is registered; this only records which
-     * row the emitter's particles are born at. Nothing is uploaded until the next {@link execute}.
-     *
-     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
-     * @param {number} transform_row
-     */
-    add_emitter(emitter, transform_row) {
-        assert.defined(emitter, 'emitter');
-        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
-        assert.isNonNegativeInteger(transform_row, 'transform_row');
-
-        this.registry.add(emitter, transform_row);
-
-        // Just arrived, and asked to arrive warm: the warm-up pipeline runs its simulation forward
-        // this frame, before it is first drawn. A reused row is a new emitter as far as this is
-        // concerned — it is the emitter that asks, not the row.
-        if (emitter.prewarm > 0) {
-            this.#warmup_queue.push(emitter);
-        }
-    }
-
-    /**
-     * Retire an emitter's row; its particles go within a frame, carrying the row's generation.
-     *
-     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
-     */
-    remove_emitter(emitter) {
-        assert.defined(emitter, 'emitter');
-
-        this.registry.remove(emitter);
-    }
-
-    /**
-     * Point a registered emitter at another row.
-     *
-     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
-     * @param {number} transform_row
-     */
-    set_transform_row(emitter, transform_row) {
-        assert.isNonNegativeInteger(transform_row, 'transform_row');
-
-        this.registry.set_transform_row(emitter, transform_row);
-    }
-
-    /**
-     * Push everything the CPU changed to the GPU: dirty emitter rows, the state buffer's growth,
-     * rebuilt program buffers, the spawn-command ring, and the coherence scratch's growth. A
-     * command context is opened only if something needs one.
-     */
-    #upload() {
-        const registry = this.registry;
-        const device = this.graphics.device;
-
-        registry.flush();
-
-        // Both tables stage into the one database: the emitter rows the author changed, and the
-        // state rows claimed or released with them.
-        const rows_staged = registry.table.element_upload_buffer.position > 0
-            || registry.state_table.element_upload_buffer.position > 0;
-
-        if (rows_staged) {
-            const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/upload");
-
-            registry.database.update(cmd);
-
-            cmd.finish();
-        }
-
-        if (registry.programs_dirty) {
-            this.buffers.program = replace_data_buffer(device, this.buffers.program, "particles/program", registry.build_program());
-        }
-
-        this.#merge_spawn_commands();
-
-        if (this.#spawn_command_count > 0) {
-            device.queue.writeBuffer(
-                this.buffers.spawn_commands, 0,
-                this.#spawn_commands.buffer, 0,
-                this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS * WORD,
-            );
-        }
-
-        this.#upload_warmup_queue();
-
-        this.#ensure_sim_buffers(this.bucketCount());
-        this.#ensure_counters(registry.table.element_capacity);
-    }
-
-    /**
-     * Turn the emitters queued for a warm-up into the words the warm-up tick reads, and the numbers
-     * the frame graph sizes the loop by; upload the words. Nothing when nothing is queued, which is
-     * nearly every frame.
-     *
-     * Two per-emitter numbers are hashed here rather than left at zero, both to keep emitters warmed
-     * in one batch off each other's beat: the accumulator's starting fraction, so their first whole
-     * particles fall on different ticks, and the clock each one's tick runs at. See
-     * `warmup/shader_particle_warmup.js`.
-     *
-     * The transient pool is sized by what the batch can spawn in all — every emitter's rate over its
-     * own pre-warm, plus one each for the rounding — and no larger than the main pool it is bound
-     * for: what would not fit there is dropped at migration anyway.
-     */
-    #upload_warmup_queue() {
-        const queue = this.#warmup_queue;
-        const frame = this.#frame;
-
-        // A queued emitter that has since left the scene has no row to warm; drop it here.
-        let count = 0;
-
-        for (let i = 0; i < queue.length; i++) {
-            const emitter = queue[i];
-
-            if (this.registry.context(emitter) !== undefined) {
-                queue[count++] = emitter;
-            }
-        }
-
-        queue.length = count;
-
-        if (count === 0) {
-            frame.warmup_count = 0;
-            frame.warmup_capacity = 0;
-            frame.warmup_schedule = null;
-            return;
-        }
-
-        let words = this.#warmup_words;
-        const needed = count * PARTICLE_WARMUP_QUEUE_WORDS;
-
-        if (words.length < needed) {
-            words = new Uint32Array(Math.max(needed, words.length * 2));
-            this.#warmup_words = words;
-        }
-
-        const floats = new Float32Array(words.buffer, words.byteOffset, words.length);
-
-        let max_prewarm = 0;
-        let spawned = 0;
-
-        for (let i = 0; i < count; i++) {
-            const emitter = queue[i];
-            const context = this.registry.context(emitter);
-            const base = i * PARTICLE_WARMUP_QUEUE_WORDS;
-
-            // Two unit fractions from one hash of the row and the emitter's seed: the same emitter
-            // in the same row warms the same way twice, and two emitters do not.
-            const hash = hash_mix2(context.row, context.generation) >>> 0;
-            const phase = (hash >>> 8) / 16777216;
-            const beat = ((hash & 0xff) / 255) - 0.5;
-
-            words[base + WARMUP_QUEUE.ROW] = context.row;
-            floats[base + WARMUP_QUEUE.PREWARM] = emitter.prewarm;
-            floats[base + WARMUP_QUEUE.ACCUMULATOR] = phase;
-            floats[base + WARMUP_QUEUE.CLOCK] = 1 + PARTICLE_WARMUP_EMITTER_JITTER * beat;
-
-            max_prewarm = Math.max(max_prewarm, emitter.prewarm);
-            spawned += Math.ceil(emitter.spawn_rate * emitter.prewarm) + 1;
-        }
-
-        const device = this.graphics.device;
-        const bytes = needed * WORD;
-
-        if (this.buffers.warmup_queue.size < bytes) {
-            this.buffers.warmup_queue.destroy();
-            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE_UPLOAD });
-        }
-
-        device.queue.writeBuffer(this.buffers.warmup_queue, 0, words.buffer, words.byteOffset, bytes);
-
-        frame.warmup_count = count;
-        frame.warmup_capacity = Math.max(1, Math.min(this.capacity, spawned));
-        frame.warmup_schedule = warmup_schedule(max_prewarm);
-    }
-
-    /**
-     * Fold the ring down to one entry per row, dropping entries whose emitter no longer holds the
-     * row it was issued against.
-     *
-     * The spawn-command pass adds to a state row with a plain read-modify-write, so two entries
-     * naming one row would lose one; and a burst issued to an emitter that left the scene this
-     * frame must not land on the row's next tenant. Both are settled here, in place, over a few
-     * dozen entries at most.
-     */
-    #merge_spawn_commands() {
-        const count = this.#spawn_command_count;
-
-        if (count === 0) {
-            return;
-        }
-
-        const ring = this.#spawn_commands;
-        const emitters = this.#spawn_command_emitters;
-
-        let rows = this.#spawn_by_row;
-        const needed = Math.max(1, this.registry.table.element_capacity);
-
-        if (rows.length < needed) {
-            rows = new Uint32Array(needed);
-            this.#spawn_by_row = rows;
-        }
-
-        for (let i = 0; i < count; i++) {
-            const emitter = emitters[i];
-            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
-            const context = this.registry.context(emitter);
-
-            if (context !== undefined && context.row === row) {
-                rows[row] += ring[i * PARTICLE_SPAWN_COMMAND_WORDS + 1];
-            }
-
-            emitters[i] = null;
-        }
-
-        let merged = 0;
-
-        for (let i = 0; i < count; i++) {
-            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
-            const pending = rows[row];
-
-            if (pending === 0) {
-                continue;
-            }
-
-            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS] = row;
-            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS + 1] = pending;
-            rows[row] = 0;
-            merged++;
-        }
-
-        this.#spawn_command_count = merged;
-    }
-
-    /**
-     * The counters buffer holds the per-emitter bounds accumulators after the counters themselves
-     * (`data/PARTICLE_COUNTERS.js`), so it follows the emitter table's element capacity.
-     *
-     * Grown by copy, not by reallocation: the counters at the head of it are live GPU state — the
-     * free-list length above all, which no CPU value can reconstruct — and the accumulators are this
-     * frame's measurements of emitters that have not moved. A fresh buffer would zero the free list
-     * and strand the whole pool.
-     *
-     * The rows past the old end are the only ones the copy does not answer for, and zero is the
-     * wrong answer for them: a zero accumulator reads back as a degenerate box at the world origin
-     * rather than as an absence, and the first box measured for such a row would be stretched to
-     * include the origin. They get the empty interval written over them instead — the same two words
-     * the publish pass resets a row to.
-     *
-     * @param {number} emitter_capacity element capacity of the emitter table
-     */
-    #ensure_counters(emitter_capacity) {
-        const size = particle_counters_word_count(emitter_capacity) * WORD;
-        const existing = this.buffers.counters;
-
-        if (existing.size >= size) {
-            return;
-        }
-
-        const device = this.graphics.device;
-        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE_GROWABLE });
-
-        const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/counters grow");
-
-        cmd.gpu_encoder.copyBufferToBuffer(existing, 0, grown, 0, existing.size);
-
-        cmd.finish();
-
-        // The new region is a whole number of accumulators: the counters are the head of the buffer
-        // and every growth adds rows behind them.
-        const added_rows = (size - existing.size) / (PARTICLE_BOUNDS_WORDS * WORD);
-
-        device.queue.writeBuffer(grown, existing.size, particle_bounds_empty_words(added_rows));
-
-        existing.destroy();
-
-        this.buffers.counters = grown;
-    }
-
-    /**
-     * The coherence list follows the peak number of program ids. It is the one thing the bucketing
-     * leaves behind: the next simulate consumes its entries and padding with the previous frame's
-     * saved count, so it cannot be a transient and it cannot be reallocated empty. Growth copies it
-     * forward; the old count and dispatch stay valid because the entries keep their places.
-     *
-     * The bins, cursors, keys and dispatch args the bucketing needs alongside it live and die inside
-     * one frame graph, so `coherence/` declares them on the passes that write them and the graph
-     * owns them.
-     *
-     * @param {number} buckets
-     */
-    #ensure_sim_buffers(buckets) {
-        if (buckets <= this.#sim_bucket_capacity) {
-            return;
-        }
-
-        const device = this.graphics.device;
-        const buffers = this.buffers;
-
-        // Padding rounds each bucket up to a whole workgroup, so it can add at most `workgroup - 1`
-        // entries per bucket; one whole workgroup per bucket is the bound.
-        const previous = buffers.sim_list;
-        buffers.sim_list = device.createBuffer({
-            label: "particles/sim_list",
-            size: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD,
-            usage: STORAGE_GROWABLE,
-        });
-
-        if (previous !== undefined) {
-            const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/coherence grow");
-            cmd.gpu_encoder.copyBufferToBuffer(previous, 0, buffers.sim_list, 0, previous.size);
-            cmd.finish();
-            previous.destroy();
-        }
-
-        this.#sim_bucket_capacity = buckets;
-    }
-
-    /**
-     * Give this frame its alive list, and hand back the ones nothing reads any more.
-     *
-     * The list is the allocator's memory on loan rather than a pair of buffers reserved here — see
-     * the class doc. Three things happen, in this order:
-     *
-     *  1. A list an earlier frame retired goes back. That frame's graph has been recorded, executed
-     *     and submitted since, so the bucketing pass that was reading it is done.
-     *  2. The previous frame's list goes back too — BEFORE the new one is asked for, so that the
-     *     pool can answer with the same memory and the steady-state footprint is one list. Skipped
-     *     when this frame rebuilds the buckets, because that pass reads it; it is retired instead
-     *     and goes back on the next call, one step behind.
-     *  3. The new list is taken. Uncleared: the frame appends to it from a counter its first pass
-     *     zeroes, so no reader can reach what the last borrower left.
-     *
-     * The pool may answer with a larger buffer than asked for, which changes nothing — every
-     * reader is bounded by a count, never by the buffer's length.
-     *
-     * @param {boolean} rebucket whether this frame's bucketing rebuild reads the previous list
-     */
-    #swap_alive_list(rebucket) {
-        const allocator = this.graphics.buffer_allocator_main;
-        const buffers = this.buffers;
-        const previous = this.#alive;
-
-        // One is taken at construction and none is ever let go without another taking its place, so
-        // there is always a previous list — including on the first frame, which can already be a
-        // rebucket if a program was edited before it.
-        assert.notNull(previous, "the previous alive list");
-
-        if (this.#alive_retired !== null) {
-            allocator.release(this.#alive_retired);
-            this.#alive_retired = null;
-        }
-
-        if (rebucket) {
-            this.#alive_retired = previous;
-        } else {
-            allocator.release(previous);
-        }
-
-        const alive = allocator.get(this.#alive_descriptor);
-
-        this.#alive = alive;
-
-        buffers.alive = alive;
-        buffers.alive_write = alive;
-        // Named only on the frames that read one: on every other frame `previous` has already gone
-        // back to the pool, and may be somebody else's by the time the graph runs.
-        buffers.alive_read = rebucket ? previous : undefined;
-    }
-
-    /**
-     * Hand every alive list back to the allocator and stop naming them.
-     *
-     * {@link destroy} cannot simply destroy them with the rest: the memory is the pool's, and a
-     * pooled buffer destroyed behind the pool's back is a handle it will hand to the next caller.
-     */
-    #release_alive_lists() {
-        const allocator = this.graphics.buffer_allocator_main;
-
-        if (this.#alive !== null) {
-            allocator.release(this.#alive);
-            this.#alive = null;
-        }
-
-        if (this.#alive_retired !== null) {
-            allocator.release(this.#alive_retired);
-            this.#alive_retired = null;
-        }
-
-        delete this.buffers.alive;
-        delete this.buffers.alive_write;
-        delete this.buffers.alive_read;
-    }
-
-    /**
-     * Fill the free list with every slot, on the GPU — see `shaders/shader_particle_init_free_list.js`
-     * for why this is a dispatch and not a host write.
-     *
-     * The launch is clamped to what a dispatch dimension holds and the shader strides through the
-     * rest: at the default capacity this is a couple of thousand workgroups, but the capacity is
-     * the caller's to choose and a dispatch past `maxComputeWorkgroupsPerDimension` is refused.
-     */
-    #init_free_list() {
-        const device = this.graphics.device;
-
-        const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/free list init");
-
-        shader_particle_init_free_list.dispatch({
-            encoder: cmd,
-            group_count_x: Math.min(
-                Math.ceil(this.capacity / PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE),
-                device.limits.maxComputeWorkgroupsPerDimension,
-            ),
-            bindings: { dead: this.buffers.dead, u_capacity: this.capacity },
-        });
-
-        cmd.finish();
-    }
-
-    /**
-     * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
-     */
-    #create_buffers() {
-        const device = this.graphics.device;
-        const capacity = this.capacity;
-        const buffers = this.buffers;
-
-        buffers.pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * WORD, usage: STORAGE });
-
-        this.#alive_descriptor = BufferResourceDescriptor.from(capacity * WORD, STORAGE);
-        this.#alive = this.graphics.buffer_allocator_main.get(this.#alive_descriptor);
-        buffers.alive = this.#alive;
-
-        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
-        // Just the counters to begin with. The per-emitter bounds accumulator that shares this
-        // buffer follows the emitter table's capacity, and there is no table yet.
-        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE_GROWABLE });
-
-        // Simulate's workgroup count, written by the END of one frame's build-indirect and read by
-        // the NEXT frame's dispatch — the one indirect buffer that crosses the boundary, and so the
-        // one the graph cannot own. Zero-initialised (WebGPU spec), so the first frame's indirect
-        // dispatch is a no-op until the first build-indirect has run.
-        buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
-
-        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE_UPLOAD });
-
-        // The warm-up queue: one entry to start with, grown on upload to what a frame registers.
-        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE_UPLOAD });
-
-        // The counters say every slot is free; the pass below makes it so. A handful of words is
-        // the whole of what the host ever writes into either — the list itself is the GPU's.
-        const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
-        counters[PARTICLE_COUNTER.DEAD] = capacity;
-
-        device.queue.writeBuffer(buffers.counters, 0, counters);
-
-        this.#init_free_list();
-    }
-
-    /**
-     * A 1x1 white atlas and a linear sampler, so the system draws before anyone hands it art.
-     * @returns {void}
-     */
-    #create_default_atlas() {
-        const device = this.graphics.device;
-
-        const texture = new GPUTextureContext(device);
-        texture.descriptor.label = "particles/default_atlas";
-        texture.descriptor.size = [1, 1];
-        texture.descriptor.format = "rgba8unorm";
-        texture.descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
-
-        device.queue.writeTexture({ texture: texture.gpu_texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
-        texture.incrementVersion();
-
-        // kept, not just viewed: a texture nothing holds is a texture nothing can free
-        this.#default_atlas = texture;
-        this.atlas = texture.obtainView();
-        this.atlas_sampler = device.createSampler({
-            label: "particles/atlas_sampler",
-            magFilter: "linear",
-            minFilter: "linear",
-            addressModeU: "clamp-to-edge",
-            addressModeV: "clamp-to-edge",
-        });
-    }
-
-    /**
-     * Sizes of the persistent buffers, in bytes, as they stand — one entry per distinct buffer, so
-     * this is the feature's footprint and not a list of the names it binds them under.
-     * `alive_write` is `alive` under the frame's name for it and would otherwise be counted twice;
-     * `alive_read` is a second list, and appears only on the frames that hold one. Exposed for tests.
-     *
-     * @returns {Object<string, number>}
-     */
-    bufferSizes() {
-        const sizes = {};
-        const counted = new Set();
-
-        for (const [name, buffer] of Object.entries(this.buffers)) {
-            if (buffer === undefined || buffer === null || counted.has(buffer)) {
-                continue;
-            }
-
-            counted.add(buffer);
-            sizes[name] = buffer.size;
-        }
-
-        return sizes;
-    }
-
-    /**
-     * Copy the counts the GPU keeps back to the host and decode them, for display and diagnostics.
-     *
-     * Read back to *look at*: nothing here may size a pass. Every number describes a frame that has
-     * already been submitted, so by the time one arrives it is at best one frame stale — and sizing
-     * a dispatch or a draw from a stale count is a correctness bug, not an inaccuracy, for the
-     * reasons `shader_particle_build_indirect` sets out. This is the whole of what the feature ever
-     * reads back, and the only reason {@link INDIRECT} carries `COPY_SRC` at all.
-     *
-     * The draw args are not here and cannot be: they never leave the frame graph, which allocates
-     * them at the build-indirect pass and releases them after the last draw that reads them. Their
-     * instance count is {@link ParticleSystemStats#alive}, which the counters carry anyway.
-     *
-     * Two copies, two submissions and a map round trip, so a caller polling this for an overlay
-     * wants to rate-limit itself and to hold off while a previous read is still outstanding.
-     *
-     * @returns {Promise<ParticleSystemStats>}
-     */
-    async read_stats() {
-        const device = this.graphics.device;
-        const buffers = this.buffers;
-
-        const read = (buffer, words) => inspect_gpu_buffer({
-            device,
-            buffer,
-            buffer_size: words * WORD,
-            // The mapped range is only valid for the length of the callback, so the decode either
-            // happens inside it or takes a copy. A copy, so one `Promise.all` sees both buffers.
-            callback: bytes => new Uint32Array(bytes.slice(0)),
-        });
-
-        const [counters, dispatch] = await Promise.all([
-            // The head of the buffer only: what follows the counters is the per-emitter bounds
-            // accumulator, which is boxes rather than counts and grows with the emitter table.
-            read(buffers.counters, PARTICLE_COUNTER_COUNT),
-            read(buffers.dispatch_args, 3),
-        ]);
-
-        return {
-            alive: counters[PARTICLE_COUNTER.ALIVE],
-            dead: counters[PARTICLE_COUNTER.DEAD],
-            spawn_budget: counters[PARTICLE_COUNTER.SPAWN_BUDGET],
-            alive_in: counters[PARTICLE_COUNTER.ALIVE_IN],
-            sim_padded: counters[PARTICLE_COUNTER.SIM_PADDED],
-            sim_workgroups: dispatch[0],
-        };
-    }
-
-    destroy() {
-        /*
-         The emitters go first, and they matter more than the buffers: they belong to their owners,
-         they outlive this system, and each is holding a row of the table about to be freed.
-         Retiring them here puts every emitter back where it was before this system saw it, so its
-         owner can register it with the next system.
-        */
-        for (const emitter of this.registry.emitters.slice()) {
-            this.registry.remove(emitter);
-        }
-
-        // Before the loop below, and not in it: the alive lists are the allocator's and go back to
-        // it. Destroying one would leave the pool holding a handle it will hand to the next caller.
-        this.#release_alive_lists();
-
-        for (const buffer of Object.values(this.buffers)) {
-            if (buffer !== undefined && buffer !== null) {
-                buffer.destroy();
-            }
-        }
-
-        this.buffers = {};
-        this.registry.database.destroy();
-
-        // the default atlas is this system's own; a page that replaced it owns what it put there
-        this.#default_atlas?.destroy();
-        this.#default_atlas = null;
-    }
-}
-
-/**
- * A storage buffer holding `data`, replacing `previous` (destroyed) if it exists. The program
- * buffer is monolithic — a program is variable-length, so there is no table to page it into — and
- * is rebuilt whole on the rare frame the program heap changes.
- *
- * @param {GPUDevice} device
- * @param {GPUBuffer|undefined} previous
- * @param {string} label
- * @param {Uint32Array} data
- * @returns {GPUBuffer}
- */
-function replace_data_buffer(device, previous, label, data) {
-    previous?.destroy();
-
-    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE_UPLOAD });
-
-    device.queue.writeBuffer(buffer, 0, data);
-
-    return buffer;
-}
+import { assert } from "../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { warn_limited } from "../../util/warn_limited.js";
+import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
+import {
+    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SPAWN_COMMAND_WORDS,
+    PARTICLE_VM_FAST_REGISTER_SLOTS,
+    PARTICLE_WARMUP_EMITTER_JITTER,
+    PARTICLE_WARMUP_QUEUE_WORDS,
+} from "./ParticleConstants.js";
+import {
+    PARTICLE_BOUNDS_WORDS,
+    PARTICLE_COUNTER,
+    PARTICLE_COUNTER_COUNT,
+    particle_bounds_empty_words,
+    particle_counters_word_count,
+} from "./data/PARTICLE_COUNTERS.js";
+import { graph_particles_simulate } from "./graph_particles.js";
+import {
+    PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE,
+    shader_particle_init_free_list,
+} from "./shaders/shader_particle_init_free_list.js";
+import {
+    graph_particle_avboit_draw,
+    graph_particle_avboit_occupancy,
+    graph_particle_avboit_splat,
+} from "./graph_particles_avboit.js";
+import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
+import { WARMUP_QUEUE } from "./warmup/shader_particle_warmup.js";
+import { warmup_schedule } from "./warmup/warmup_schedule.js";
+import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { inspect_gpu_buffer } from "../buffer/inspect_gpu_buffer.js";
+
+const WORD = Uint32Array.BYTES_PER_ELEMENT;
+
+/*
+ A wide usage mask costs bandwidth: the driver places a buffer by what it was told the buffer might
+ have to do, and the flags below are what each one actually does. `pool` and the alive lists are the
+ big ones and are touched by nothing but shaders. Adding a flag "just in case" moves 64 MiB onto a
+ slower path for a copy nobody makes — see `BufferResourceDescriptor`.
+*/
+/** Written only by shaders. The free list is one of these: `init_free_list` fills it on-device. */
+const STORAGE = GPUBufferUsage.STORAGE;
+/** Seeded or refilled from the host with `writeBuffer`. */
+const STORAGE_UPLOAD = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+/** Uploaded, and copied forward into its replacement when the emitter set outgrows it. */
+const STORAGE_GROWABLE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+/**
+ * An indirect command the GPU writes and the GPU consumes. COPY_SRC is for {@link
+ * GPUParticleSystem#read_stats}, which reads the args back to show that the dispatch really is
+ * sized on-device — twelve bytes.
+ */
+const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
+
+const DEFAULT_CAPACITY = 524288;
+
+/**
+ * What {@link GPUParticleSystem#read_stats} decodes: the counts the GPU keeps between frames, named.
+ *
+ * @typedef {object} ParticleSystemStats
+ * @property {number} alive live particles the frame ended with
+ * @property {number} dead length of the free list
+ * @property {number} spawn_budget free slots the frame never promised to a spawn — its headroom
+ * @property {number} alive_in entries the frame's simulate consumed — the padded, program-coherent
+ *   list the frame before it built, so never fewer than that frame's `alive`
+ * @property {number} sim_padded length of the padded, program-coherent simulate list built this
+ *   frame; the gap to `alive` is what keeping each wave on one VM program costs in lanes
+ * @property {number} sim_workgroups workgroups the NEXT simulate will dispatch — read out of the
+ *   indirect args rather than derived, so it is what the GPU will actually launch
+ */
+
+/**
+ * The GPU particle system: a feature of a scene, in the mould of `ReSTIRDI` — construct once
+ * against a {@link GPUSceneContext}, and contribute the frame's passes through
+ * {@link execute}.
+ *
+ * ## What it owns
+ *
+ * Persistent GPU state, and only that: a buffer is reserved here if and only if its contents have
+ * to survive to the next frame. That is the particle pool, the alive list, the dead
+ * free-list, the counters, the simulation-order (coherence) list, simulate's indirect dispatch args
+ * (written at the end of one frame, read by the next), the emitter database (the emitter table and
+ * the GPU-owned state table, one buffer), the packed program buffer, and the two CPU-uploaded
+ * queues — the spawn-command ring and the warm-up queue. Buffers that depend on the emitter set —
+ * the coherence list on the number of distinct programs, the program buffer on the heap, the
+ * database on its own pages, the counters on the emitter table's element capacity (they carry the
+ * per-emitter bounds accumulator, see `bounds/`) — are grown inside {@link execute}, the way
+ * ReSTIR's reservoirs follow the resolution.
+ *
+ * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
+ * draw args, the spawn counts and the VM's wide register file are produced and consumed inside one
+ * graph, so the pass that first writes each one declares it and the graph allocates it just in time
+ * and releases it after its last reader — into the pool the rest of the renderer allocates from.
+ * Reserving them here instead would be megabytes at the default capacity that no other feature
+ * could ever borrow, and most of them are cleared by a reset pass every frame regardless.
+ *
+ * ## The alive list is borrowed, not reserved
+ *
+ * The alive list crosses the frame boundary and so cannot be the graph's — but it does not have to
+ * be the feature's either. It is taken from the graphics context's buffer allocator and given back
+ * every frame ({@link #swap_alive_list}), which is the difference between one list and two.
+ *
+ * Two was the obvious reading of the ping-pong: the frame builds a new list while the previous one
+ * is still there to be read. But nothing reads the previous one. Emit and simulate append to the
+ * new list from a counter the frame resets to zero, the draws walk that same new list, and the only
+ * pass that ever looks at the one before it is the bucketing rebuild on a frame whose program
+ * assignments changed — a live program edit, not a frame. So on an ordinary frame the previous list
+ * goes back to the pool BEFORE the new one is asked for, the pool answers with the same memory, and
+ * the feature's reserved footprint is one list rather than two. On the rare frame that does rebuild,
+ * the old list is held one frame longer — until the graph recorded around it has been submitted —
+ * and the feature briefly costs what it used to cost always.
+ *
+ * Every pass stays within the eight storage buffers a stage gets by default: the emitter record
+ * and the GPU-owned state are two tables of one database buffer, and the VM's constants and code
+ * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
+ * simulate passes bind a ninth for the register file — inside the ten the engine already demands of
+ * an adapter, but past the default.
+ *
+ * ## Two interpreters
+ *
+ * The VM's register file normally lives in shader registers, and is therefore small — see
+ * {@link ./ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}. An effect whose compiled program
+ * needs more than it holds does not fail: the whole system swaps emit and simulate for variants
+ * that keep the file in a storage buffer, which is far slower and effectively unbounded. The choice
+ * is per-frame, whole-system, and made here — the registry reports `max_register_count` over the
+ * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
+ * a register ceiling.
+ *
+ * ## Emitters are registered at rows
+ *
+ * {@link add_emitter} gives a {@link ParticleEmitter} a row in the emitter table pointed at a
+ * `transforms` row — an entity's, one on, held through the scene context's rows by whoever owns
+ * the entity — and it starts spawning on the next {@link execute}; under a joint's row it moves
+ * with the joint. {@link remove_emitter} retires the row and frees its particles. Nothing here
+ * walks the scene: an emitter is where its owner says it is, and per-frame upkeep is proportional
+ * to what changed rather than to how many emitters there are.
+ *
+ * ## Spawning is the GPU's decision
+ *
+ * The CPU never counts particles or walks emitters per frame. The emitter tick pass integrates
+ * every emitter's rate on the GPU, and the emit dispatch is sized by a prefix scan of what it
+ * decided. The host's one way to ask for particles is {@link spawn}: a burst queued into a small
+ * command list that a pass adds to the emitter's pending spawns, on the same path as everything
+ * else. See `graph_particles.js` for the frame.
+ *
+ * ## Drawing
+ *
+ * {@link execute} is the whole per-frame call, once per frame, and it records only the simulation:
+ * everything that moves particles, leaving the alive list and the indirect draw args as graph
+ * handles. It draws nothing.
+ *
+ * The drawing is the transparency pipeline's. The system is an `AVBOITSideChannel`, and the AVBOIT
+ * orchestrator asks it for its occupancy, its extinction and its draw at the three points where the
+ * transparent meshes have contributed theirs ({@link avboit_occupancy}, {@link avboit_splat},
+ * {@link avboit_draw}). Those read the handles `execute` produced and composite into a voxel volume
+ * and a set of accumulators that are sums — so the particles need no depth ordering at all, and
+ * none is ever built.
+ *
+ * ## Allocation
+ *
+ * The per-frame path allocates the frame graph's records and nothing else: emitter rows are
+ * staged through one shared record, spawn commands go into a preallocated ring, and the
+ * per-dispatch settings are reused objects. A command context is opened only on frames that have
+ * something to upload.
+ */
+export class GPUParticleSystem {
+
+    /**
+     * Engine GraphicsContext.
+     * @type {object}
+     */
+    graphics;
+
+    /**
+     * The scene whose rows the emitters are placed at, and whose database their world matrices
+     * come from.
+     * @type {import("../scene/GPUSceneContext.js").GPUSceneContext}
+     */
+    scene_context;
+
+    /**
+     * Maximum number of simultaneously live particles.
+     * @type {number}
+     */
+    capacity;
+
+    /**
+     * @type {EmitterRegistry}
+     */
+    registry;
+
+    /**
+     * Frames elapsed. The VM's frame builtin.
+     * @type {number}
+     */
+    frame = 0;
+
+    /**
+     * Seconds since start, the VM's `TIME` builtin. Advanced by `dt` each {@link execute}.
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * Cap on how much missed time a culled emitter makes up for when it comes back into view.
+     * @type {number}
+     */
+    max_catchup_seconds = 1;
+
+    /**
+     * Sprite atlas the billboards sample, and the sampler they sample it with. A 1x1 white texel by
+     * default, so an emitter with no art draws as a plain quad rather than nothing.
+     * @type {GPUTextureView}
+     */
+    atlas;
+
+    /** @type {GPUSampler} */
+    atlas_sampler;
+
+    /**
+     * The persistent GPU buffers, by the names the graph functions bind them under. Exposed for
+     * inspection — {@link bufferSizes} measures them, {@link read_stats} reads the counts out of
+     * them — never for the frame loop, which reads nothing back. Entries that grow with the
+     * emitter set are replaced in place.
+     *
+     * `alive` and `alive_write` are one buffer under two names — what the feature holds, and what
+     * the frame writes — and `alive_read` is the previous frame's list, present only on the frames
+     * that read one. The list itself belongs to the allocator, not here; see {@link #swap_alive_list}.
+     *
+     * @type {object}
+     */
+    buffers = {};
+
+    /**
+     * Distinct programs the coherence scratch is currently sized for.
+     * @type {number}
+     */
+    #sim_bucket_capacity = 0;
+
+    /**
+     * What the alive list is asked for under: one `u32` per pool slot, touched by nothing but
+     * shaders, and deliberately not cleared — every entry a reader sees was appended this frame,
+     * from a counter the frame's first pass resets to zero, so whatever the last borrower left in
+     * it is unreadable by construction. One instance, reused: the pool reads a descriptor and does
+     * not keep it.
+     *
+     * @type {BufferResourceDescriptor}
+     */
+    #alive_descriptor;
+
+    /**
+     * The alive list the last recorded frame built — the next frame's `alive_read`. Borrowed from
+     * `graphics.buffer_allocator_main`, so it is released rather than destroyed.
+     * @type {GPUBuffer|null}
+     */
+    #alive = null;
+
+    /**
+     * An alive list a recorded frame still reads: the bucketing rebuild's input on a frame whose
+     * program assignments changed. Handed back on the next {@link execute}, by which point that
+     * frame's graph has been executed and submitted.
+     * @type {GPUBuffer|null}
+     */
+    #alive_retired = null;
+
+    /**
+     * The spawn-command ring: `[row, count]` pairs, filled by {@link spawn}, merged and uploaded on
+     * the next {@link execute}.
+     * @type {Uint32Array}
+     */
+    #spawn_commands;
+
+    /**
+     * The emitter each ring entry was issued for, so an entry whose emitter has since left the
+     * scene — or whose row has gone to somebody else — is dropped at upload rather than delivered
+     * to the row's next tenant.
+     * @type {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
+     */
+    #spawn_command_emitters;
+
+    /** @type {number} */
+    #spawn_command_count = 0;
+
+    /**
+     * Scratch for merging the ring: pending count by row. Grown with the emitter table, never per
+     * frame.
+     * @type {Uint32Array}
+     */
+    #spawn_by_row = new Uint32Array(0);
+
+    /**
+     * Emitters registered since the last frame with a pre-warm to run — the input of the warm-up
+     * pipeline (`warmup/`), consumed by the frame that records it. Filled where the emitter is
+     * registered ({@link add_emitter}), which is the one moment the host knows an emitter is
+     * new: the GPU decides everything else about spawning, but "this one has just arrived and asks
+     * to arrive warm" is a host-side fact.
+     *
+     * @type {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
+     */
+    #warmup_queue = [];
+
+    /**
+     * The queue as the GPU reads it, `PARTICLE_WARMUP_QUEUE_WORDS` per entry — see
+     * `warmup/shader_particle_warmup.js`. Grown to fit, never per frame.
+     * @type {Uint32Array}
+     */
+    #warmup_words = new Uint32Array(0);
+
+
+    /**
+     * The 1x1 white texture {@link atlas} points at until a caller replaces it. Held so
+     * {@link destroy} can free it; a caller that assigns its own atlas owns that one.
+     * @type {GPUTextureContext|null}
+     */
+    #default_atlas = null;
+
+
+    /**
+     * Program assignments used to build the previous frame's coherence list.
+     * @type {number}
+     */
+    #program_assignment_version = 0;
+
+    /**
+     * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
+     * @type {object}
+     */
+    #frame = {
+        dt: 0, time: 0, index: 0, max_catchup: 1, spawn_command_count: 0,
+        warmup_count: 0, warmup_capacity: 0, warmup_schedule: null,
+        rebucket: false,
+    };
+
+    /** @type {{capacity: number, group_count: number}} */
+    #emitters = { capacity: 0, group_count: 0 };
+
+    /**
+     * This frame's simulation, for the side channels that draw it later in the frame: the graph it
+     * was recorded into, the scene database handle it read, and the handles it produced. Reused,
+     * never reallocated.
+     * @type {{graph: object|null, scene_database: number, emitter_group_count: number, handles: object|null}}
+     */
+    #simulated = { graph: null, scene_database: -1, emitter_group_count: 0, handles: null };
+
+    /**
+     * @param {object} graphics engine GraphicsContext (has `.device`)
+     * @param {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
+     * @param {object} [options]
+     * @param {number} [options.capacity] max simultaneous particles
+     * @param {number} [options.spawn_command_capacity] most {@link spawn} calls one frame keeps
+     */
+    constructor(graphics, scene_context, { capacity = DEFAULT_CAPACITY, spawn_command_capacity = 256 } = {}) {
+        assert.defined(graphics, "graphics");
+        assert.defined(scene_context, "scene_context");
+        assert.equal(scene_context.isGPUSceneContext, true, "scene_context.isGPUSceneContext !== true");
+        assert.isPositiveInteger(capacity, "capacity");
+        assert.isPositiveInteger(spawn_command_capacity, "spawn_command_capacity");
+
+        this.graphics = graphics;
+        this.scene_context = scene_context;
+        this.capacity = capacity;
+
+        this.registry = new EmitterRegistry(graphics.device);
+
+        this.#spawn_commands = new Uint32Array(spawn_command_capacity * PARTICLE_SPAWN_COMMAND_WORDS);
+        this.#spawn_command_emitters = new Array(spawn_command_capacity).fill(null);
+
+        this.#create_buffers();
+        this.#create_default_atlas();
+    }
+
+    /**
+     * The buffer the emitter table lives in — what every emitter-reading pass binds.
+     * @returns {GPUBuffer}
+     */
+    get emitter_database() {
+        return this.registry.database.buffer;
+    }
+
+    /**
+     * The live emitters, in no particular order.
+     * @returns {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
+     */
+    get emitters() {
+        return this.registry.emitters;
+    }
+
+    /**
+     * Number of simulation-order buckets — one per program id the registry can hand out, which is
+     * its peak number of distinct compiled programs rather than its current one.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when an effect the set has never held is registered, not as
+     * particles are born and die. Everything the pass measures per frame stays on the GPU. Sizing it
+     * from the peak rather than the live count is what keeps it from moving every time an effect is
+     * unregistered — the bins of released ids are empty, and an empty bin rounds up to zero
+     * workgroups and shifts nothing after it.
+     *
+     * @returns {number}
+     */
+    bucketCount() {
+        return Math.max(1, this.registry.program_id_capacity);
+    }
+
+    /**
+     * Ask for `count` particles from an emitter, on top of its rate, on the next frame. Goes
+     * through the GPU path — the tick pass folds it into the emitter's accumulator, the budget and
+     * the culling apply — so it is a request, not a guarantee.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter a registered emitter
+     * @param {number} count
+     */
+    spawn(emitter, count) {
+        assert.defined(emitter, "emitter");
+        assert.isNonNegativeInteger(count, "count");
+
+        const context = this.registry.context(emitter);
+
+        assert.defined(context, "emitter is not registered");
+
+        const ring = this.#spawn_commands;
+        const base = this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS;
+
+        if (base >= ring.length) {
+            // the text is the key warn_limited counts on, so it carries no burst size: one message
+            // per ring size, not one per number a caller happens to ask for
+            warn_limited(`GPUParticleSystem: spawn command ring is full (${ring.length / PARTICLE_SPAWN_COMMAND_WORDS} per frame); dropping this frame's remaining bursts`);
+            return;
+        }
+
+        ring[base] = context.row;
+        ring[base + 1] = count;
+        this.#spawn_command_emitters[this.#spawn_command_count] = emitter;
+        this.#spawn_command_count++;
+    }
+
+    /**
+     * The system's whole contribution to the frame, once per frame: reconcile the emitter set with
+     * the scene, push what changed to the GPU, and record every pass that moves particles — through
+     * to the indirect draw args.
+     *
+     * It draws nothing and touches no colour target. The handles it returns are what the AVBOIT
+     * side channels ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}) consume
+     * later in the same frame, off this same graph, once the transparent meshes have contributed
+     * theirs.
+     *
+     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
+     * emitter's `transforms` row is uploaded, and after the hierarchy pass has run, so the rows'
+     * `global` matrices are this frame's.
+     *
+     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
+     * handles into the graph it recorded into; a second view of the same scene records a second
+     * graph and would step the simulation twice. The renderer has one view per `render` call today,
+     * so this holds by construction; a second view of one scene needs the step and the handles
+     * separated — record the passes for the first graph, import the same buffers into the rest.
+     *
+     * @param {object} params
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+     * @param {number} params.camera graph handle of the camera uniform buffer
+     * @param {number} params.scene_database graph handle of the scene database — the one the
+     *   hierarchy pass returned, so this reads the matrices it composed
+     * @param {number} params.dt seconds since the previous frame
+     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
+     */
+    execute({ graph, camera, scene_database, dt }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+
+        this.#upload();
+
+        const frame = this.#frame;
+        frame.dt = dt;
+        frame.time = this.time;
+        frame.index = this.frame;
+        frame.max_catchup = this.max_catchup_seconds;
+        frame.spawn_command_count = this.#spawn_command_count;
+        frame.rebucket = this.#program_assignment_version !== this.registry.program_assignment_version;
+        this.#program_assignment_version = this.registry.program_assignment_version;
+
+        const table = this.registry.table;
+        const emitters = this.#emitters;
+        emitters.capacity = table.element_capacity;
+        emitters.group_count = table.dispatch_group_count(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE);
+
+        const buffers = this.buffers;
+
+        this.#swap_alive_list(frame.rebucket);
+
+        // The table's database owns and grows its own buffer; it is re-read every frame for that
+        // reason.
+        buffers.emitter_database = this.registry.database.buffer;
+
+        const simulated = graph_particles_simulate({
+            graph,
+            camera,
+            scene_database,
+            gpu: buffers,
+            emitters,
+            capacity: this.capacity,
+            bucket_count: this.bucketCount(),
+            // Whose register file the VM runs on is decided here, once, for the whole system: the
+            // registry reports what the hungriest registered effect needs and this compares it
+            // against what the fast file holds. Re-read every frame because registering an emitter —
+            // or unregistering the one hungry effect — can flip it either way.
+            wide_registers: this.registry.max_register_count > PARTICLE_VM_FAST_REGISTER_SLOTS,
+            frame,
+        });
+
+        // Kept for the side channels that draw later in this frame, and for nothing past it.
+        const current = this.#simulated;
+        current.graph = graph;
+        current.scene_database = scene_database;
+        current.emitter_group_count = emitters.group_count;
+        current.handles = simulated;
+
+        // Consumed: the counts were recorded into the graph, the words were uploaded.
+        this.#spawn_command_count = 0;
+        this.#warmup_queue.length = 0;
+
+        this.frame++;
+        this.time += dt;
+
+        return simulated;
+    }
+
+    /**
+     * What this frame's {@link execute} left, checked against the graph a side-channel call names:
+     * the AVBOIT orchestrator records its passes into the same graph, later in the same frame.
+     *
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @returns {{graph: object, scene_database: number, emitter_group_count: number, handles: import("./graph_particles.js").ParticleSimulationHandles}}
+     */
+    #simulated_for(graph) {
+        const current = this.#simulated;
+
+        assert.equal(current.graph, graph, "the particles were not simulated into this graph this frame — call execute() before the transparency pipeline records");
+
+        return current;
+    }
+
+    /**
+     * `AVBOITSideChannel#avboit_occupancy`: the emitters' measured bounding boxes, as depth slices.
+     *
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {ArrayLike<number>} args.cluster_parameters the frame's depth curve
+     * @param {number} args.occupancy graph handle of the occupancy bits
+     * @returns {number} the occupancy handle after the write
+     */
+    avboit_occupancy({ graph, camera, cluster_parameters, occupancy }) {
+        const current = this.#simulated_for(graph);
+
+        return graph_particle_avboit_occupancy({
+            graph,
+            camera,
+            cluster_parameters,
+            occupancy,
+            emitter_database: current.handles.emitter_database,
+            emitter_group_count: current.emitter_group_count,
+        });
+    }
+
+    /**
+     * `AVBOITSideChannel#avboit_splat`: the live particles' extinction, into the volume.
+     *
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {number} args.warp graph handle of the warp LUT
+     * @param {number} args.depth_texture graph handle of the scene depth
+     * @param {{extinction: number, overflow: number, dummy: number}} args.volume the voxel volume
+     * @returns {{extinction: number, overflow: number, dummy: number}} the volume after the write
+     */
+    avboit_splat({ graph, camera, warp, depth_texture, volume }) {
+        const { handles } = this.#simulated_for(graph);
+
+        return graph_particle_avboit_splat({
+            graph,
+            camera,
+            warp,
+            depth_texture,
+            volume,
+            atlas: this.atlas,
+            atlas_sampler: this.atlas_sampler,
+            pool: handles.pool,
+            alive: handles.alive,
+            emitter_database: handles.emitter_database,
+            draw_args: handles.draw_args,
+        });
+    }
+
+    /**
+     * `AVBOITSideChannel#avboit_draw`: the live particles, into the accumulators.
+     *
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {import("../view/GPUViewContext.js").GPUViewContext} args.view_ctx
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {number} args.depth_texture graph handle of the scene depth
+     * @param {number} args.warp graph handle of the warp LUT
+     * @param {number} args.integral graph handle of the integral texture
+     * @param {number} args.volumetrics_lut graph handle
+     * @param {number} args.volumetrics_metadata graph handle
+     * @param {{Y: number, CoCg: number}} args.volumetrics_irradiance graph handles of the froxel
+     *   irradiance volume, what an emitter flagged `EMITTER_FLAG.LIGHTING` is lit by
+     * @param {{color: number, norm: number, extinction: number, emission: number}} args.accumulators
+     * @returns {{color: number, norm: number, extinction: number, emission: number}} after the draw
+     */
+    avboit_draw({ graph, view_ctx, camera, depth_texture, warp, integral, volumetrics_lut, volumetrics_metadata, volumetrics_irradiance, accumulators }) {
+        const { handles } = this.#simulated_for(graph);
+
+        return graph_particle_avboit_draw({
+            graph,
+            view_ctx,
+            camera,
+            depth_texture,
+            warp,
+            integral,
+            volumetrics_lut,
+            volumetrics_metadata,
+            volumetrics_irradiance,
+            accumulators,
+            atlas: this.atlas,
+            atlas_sampler: this.atlas_sampler,
+            pool: handles.pool,
+            alive: handles.alive,
+            emitter_database: handles.emitter_database,
+            draw_args: handles.draw_args,
+        });
+    }
+
+    /**
+     * Register an emitter at a `transforms` row, and if it asks, warm it up before its first frame.
+     *
+     * The row is an entity's, one on (`row_of_entity`), and whoever owns the entity holds it through
+     * the scene context's rows for as long as the emitter is registered; this only records which
+     * row the emitter's particles are born at. Nothing is uploaded until the next {@link execute}.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    add_emitter(emitter, transform_row) {
+        assert.defined(emitter, 'emitter');
+        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        this.registry.add(emitter, transform_row);
+
+        // Just arrived, and asked to arrive warm: the warm-up pipeline runs its simulation forward
+        // this frame, before it is first drawn. A reused row is a new emitter as far as this is
+        // concerned — it is the emitter that asks, not the row.
+        if (emitter.prewarm > 0) {
+            this.#warmup_queue.push(emitter);
+        }
+    }
+
+    /**
+     * Retire an emitter's row; its particles go within a frame, carrying the row's generation.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     */
+    remove_emitter(emitter) {
+        assert.defined(emitter, 'emitter');
+
+        this.registry.remove(emitter);
+    }
+
+    /**
+     * Point a registered emitter at another row.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    set_transform_row(emitter, transform_row) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        this.registry.set_transform_row(emitter, transform_row);
+    }
+
+    /**
+     * Push everything the CPU changed to the GPU: dirty emitter rows, the state buffer's growth,
+     * rebuilt program buffers, the spawn-command ring, and the coherence scratch's growth. A
+     * command context is opened only if something needs one.
+     */
+    #upload() {
+        const registry = this.registry;
+        const device = this.graphics.device;
+
+        registry.flush();
+
+        // Both tables stage into the one database: the emitter rows the author changed, and the
+        // state rows claimed or released with them.
+        const rows_staged = registry.table.element_upload_buffer.position > 0
+            || registry.state_table.element_upload_buffer.position > 0;
+
+        if (rows_staged) {
+            const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/upload");
+
+            registry.database.update(cmd);
+
+            cmd.finish();
+        }
+
+        if (registry.programs_dirty) {
+            this.buffers.program = replace_data_buffer(device, this.buffers.program, "particles/program", registry.build_program());
+        }
+
+        this.#merge_spawn_commands();
+
+        if (this.#spawn_command_count > 0) {
+            device.queue.writeBuffer(
+                this.buffers.spawn_commands, 0,
+                this.#spawn_commands.buffer, 0,
+                this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS * WORD,
+            );
+        }
+
+        this.#upload_warmup_queue();
+
+        this.#ensure_sim_buffers(this.bucketCount());
+        this.#ensure_counters(registry.table.element_capacity);
+    }
+
+    /**
+     * Turn the emitters queued for a warm-up into the words the warm-up tick reads, and the numbers
+     * the frame graph sizes the loop by; upload the words. Nothing when nothing is queued, which is
+     * nearly every frame.
+     *
+     * Two per-emitter numbers are hashed here rather than left at zero, both to keep emitters warmed
+     * in one batch off each other's beat: the accumulator's starting fraction, so their first whole
+     * particles fall on different ticks, and the clock each one's tick runs at. See
+     * `warmup/shader_particle_warmup.js`.
+     *
+     * The transient pool is sized by what the batch can spawn in all — every emitter's rate over its
+     * own pre-warm, plus one each for the rounding — and no larger than the main pool it is bound
+     * for: what would not fit there is dropped at migration anyway.
+     */
+    #upload_warmup_queue() {
+        const queue = this.#warmup_queue;
+        const frame = this.#frame;
+
+        // A queued emitter that has since left the scene has no row to warm; drop it here.
+        let count = 0;
+
+        for (let i = 0; i < queue.length; i++) {
+            const emitter = queue[i];
+
+            if (this.registry.context(emitter) !== undefined) {
+                queue[count++] = emitter;
+            }
+        }
+
+        queue.length = count;
+
+        if (count === 0) {
+            frame.warmup_count = 0;
+            frame.warmup_capacity = 0;
+            frame.warmup_schedule = null;
+            return;
+        }
+
+        let words = this.#warmup_words;
+        const needed = count * PARTICLE_WARMUP_QUEUE_WORDS;
+
+        if (words.length < needed) {
+            words = new Uint32Array(Math.max(needed, words.length * 2));
+            this.#warmup_words = words;
+        }
+
+        const floats = new Float32Array(words.buffer, words.byteOffset, words.length);
+
+        let max_prewarm = 0;
+        let spawned = 0;
+
+        for (let i = 0; i < count; i++) {
+            const emitter = queue[i];
+            const context = this.registry.context(emitter);
+            const base = i * PARTICLE_WARMUP_QUEUE_WORDS;
+
+            // Two unit fractions from one hash of the row and the emitter's seed: the same emitter
+            // in the same row warms the same way twice, and two emitters do not.
+            const hash = hash_mix2(context.row, context.generation) >>> 0;
+            const phase = (hash >>> 8) / 16777216;
+            const beat = ((hash & 0xff) / 255) - 0.5;
+
+            words[base + WARMUP_QUEUE.ROW] = context.row;
+            floats[base + WARMUP_QUEUE.PREWARM] = emitter.prewarm;
+            floats[base + WARMUP_QUEUE.ACCUMULATOR] = phase;
+            floats[base + WARMUP_QUEUE.CLOCK] = 1 + PARTICLE_WARMUP_EMITTER_JITTER * beat;
+
+            max_prewarm = Math.max(max_prewarm, emitter.prewarm);
+            spawned += Math.ceil(emitter.spawn_rate * emitter.prewarm) + 1;
+        }
+
+        const device = this.graphics.device;
+        const bytes = needed * WORD;
+
+        if (this.buffers.warmup_queue.size < bytes) {
+            this.buffers.warmup_queue.destroy();
+            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE_UPLOAD });
+        }
+
+        device.queue.writeBuffer(this.buffers.warmup_queue, 0, words.buffer, words.byteOffset, bytes);
+
+        frame.warmup_count = count;
+        frame.warmup_capacity = Math.max(1, Math.min(this.capacity, spawned));
+        frame.warmup_schedule = warmup_schedule(max_prewarm);
+    }
+
+    /**
+     * Fold the ring down to one entry per row, dropping entries whose emitter no longer holds the
+     * row it was issued against.
+     *
+     * The spawn-command pass adds to a state row with a plain read-modify-write, so two entries
+     * naming one row would lose one; and a burst issued to an emitter that left the scene this
+     * frame must not land on the row's next tenant. Both are settled here, in place, over a few
+     * dozen entries at most.
+     */
+    #merge_spawn_commands() {
+        const count = this.#spawn_command_count;
+
+        if (count === 0) {
+            return;
+        }
+
+        const ring = this.#spawn_commands;
+        const emitters = this.#spawn_command_emitters;
+
+        let rows = this.#spawn_by_row;
+        const needed = Math.max(1, this.registry.table.element_capacity);
+
+        if (rows.length < needed) {
+            rows = new Uint32Array(needed);
+            this.#spawn_by_row = rows;
+        }
+
+        for (let i = 0; i < count; i++) {
+            const emitter = emitters[i];
+            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
+            const context = this.registry.context(emitter);
+
+            if (context !== undefined && context.row === row) {
+                rows[row] += ring[i * PARTICLE_SPAWN_COMMAND_WORDS + 1];
+            }
+
+            emitters[i] = null;
+        }
+
+        let merged = 0;
+
+        for (let i = 0; i < count; i++) {
+            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
+            const pending = rows[row];
+
+            if (pending === 0) {
+                continue;
+            }
+
+            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS] = row;
+            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS + 1] = pending;
+            rows[row] = 0;
+            merged++;
+        }
+
+        this.#spawn_command_count = merged;
+    }
+
+    /**
+     * The counters buffer holds the per-emitter bounds accumulators after the counters themselves
+     * (`data/PARTICLE_COUNTERS.js`), so it follows the emitter table's element capacity.
+     *
+     * Grown by copy, not by reallocation: the counters at the head of it are live GPU state — the
+     * free-list length above all, which no CPU value can reconstruct — and the accumulators are this
+     * frame's measurements of emitters that have not moved. A fresh buffer would zero the free list
+     * and strand the whole pool.
+     *
+     * The rows past the old end are the only ones the copy does not answer for, and zero is the
+     * wrong answer for them: a zero accumulator reads back as a degenerate box at the world origin
+     * rather than as an absence, and the first box measured for such a row would be stretched to
+     * include the origin. They get the empty interval written over them instead — the same two words
+     * the publish pass resets a row to.
+     *
+     * @param {number} emitter_capacity element capacity of the emitter table
+     */
+    #ensure_counters(emitter_capacity) {
+        const size = particle_counters_word_count(emitter_capacity) * WORD;
+        const existing = this.buffers.counters;
+
+        if (existing.size >= size) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE_GROWABLE });
+
+        const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/counters grow");
+
+        cmd.gpu_encoder.copyBufferToBuffer(existing, 0, grown, 0, existing.size);
+
+        cmd.finish();
+
+        // The new region is a whole number of accumulators: the counters are the head of the buffer
+        // and every growth adds rows behind them.
+        const added_rows = (size - existing.size) / (PARTICLE_BOUNDS_WORDS * WORD);
+
+        device.queue.writeBuffer(grown, existing.size, particle_bounds_empty_words(added_rows));
+
+        existing.destroy();
+
+        this.buffers.counters = grown;
+    }
+
+    /**
+     * The coherence list follows the peak number of program ids. It is the one thing the bucketing
+     * leaves behind: the next simulate consumes its entries and padding with the previous frame's
+     * saved count, so it cannot be a transient and it cannot be reallocated empty. Growth copies it
+     * forward; the old count and dispatch stay valid because the entries keep their places.
+     *
+     * The bins, cursors, keys and dispatch args the bucketing needs alongside it live and die inside
+     * one frame graph, so `coherence/` declares them on the passes that write them and the graph
+     * owns them.
+     *
+     * @param {number} buckets
+     */
+    #ensure_sim_buffers(buckets) {
+        if (buckets <= this.#sim_bucket_capacity) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+
+        // Padding rounds each bucket up to a whole workgroup, so it can add at most `workgroup - 1`
+        // entries per bucket; one whole workgroup per bucket is the bound.
+        const previous = buffers.sim_list;
+        buffers.sim_list = device.createBuffer({
+            label: "particles/sim_list",
+            size: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD,
+            usage: STORAGE_GROWABLE,
+        });
+
+        if (previous !== undefined) {
+            const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/coherence grow");
+            cmd.gpu_encoder.copyBufferToBuffer(previous, 0, buffers.sim_list, 0, previous.size);
+            cmd.finish();
+            previous.destroy();
+        }
+
+        this.#sim_bucket_capacity = buckets;
+    }
+
+    /**
+     * Give this frame its alive list, and hand back the ones nothing reads any more.
+     *
+     * The list is the allocator's memory on loan rather than a pair of buffers reserved here — see
+     * the class doc. Three things happen, in this order:
+     *
+     *  1. A list an earlier frame retired goes back. That frame's graph has been recorded, executed
+     *     and submitted since, so the bucketing pass that was reading it is done.
+     *  2. The previous frame's list goes back too — BEFORE the new one is asked for, so that the
+     *     pool can answer with the same memory and the steady-state footprint is one list. Skipped
+     *     when this frame rebuilds the buckets, because that pass reads it; it is retired instead
+     *     and goes back on the next call, one step behind.
+     *  3. The new list is taken. Uncleared: the frame appends to it from a counter its first pass
+     *     zeroes, so no reader can reach what the last borrower left.
+     *
+     * The pool may answer with a larger buffer than asked for, which changes nothing — every
+     * reader is bounded by a count, never by the buffer's length.
+     *
+     * @param {boolean} rebucket whether this frame's bucketing rebuild reads the previous list
+     */
+    #swap_alive_list(rebucket) {
+        const allocator = this.graphics.buffer_allocator_main;
+        const buffers = this.buffers;
+        const previous = this.#alive;
+
+        // One is taken at construction and none is ever let go without another taking its place, so
+        // there is always a previous list — including on the first frame, which can already be a
+        // rebucket if a program was edited before it.
+        assert.notNull(previous, "the previous alive list");
+
+        if (this.#alive_retired !== null) {
+            allocator.release(this.#alive_retired);
+            this.#alive_retired = null;
+        }
+
+        if (rebucket) {
+            this.#alive_retired = previous;
+        } else {
+            allocator.release(previous);
+        }
+
+        const alive = allocator.get(this.#alive_descriptor);
+
+        this.#alive = alive;
+
+        buffers.alive = alive;
+        buffers.alive_write = alive;
+        // Named only on the frames that read one: on every other frame `previous` has already gone
+        // back to the pool, and may be somebody else's by the time the graph runs.
+        buffers.alive_read = rebucket ? previous : undefined;
+    }
+
+    /**
+     * Hand every alive list back to the allocator and stop naming them.
+     *
+     * {@link destroy} cannot simply destroy them with the rest: the memory is the pool's, and a
+     * pooled buffer destroyed behind the pool's back is a handle it will hand to the next caller.
+     */
+    #release_alive_lists() {
+        const allocator = this.graphics.buffer_allocator_main;
+
+        if (this.#alive !== null) {
+            allocator.release(this.#alive);
+            this.#alive = null;
+        }
+
+        if (this.#alive_retired !== null) {
+            allocator.release(this.#alive_retired);
+            this.#alive_retired = null;
+        }
+
+        delete this.buffers.alive;
+        delete this.buffers.alive_write;
+        delete this.buffers.alive_read;
+    }
+
+    /**
+     * Fill the free list with every slot, on the GPU — see `shaders/shader_particle_init_free_list.js`
+     * for why this is a dispatch and not a host write.
+     *
+     * The launch is clamped to what a dispatch dimension holds and the shader strides through the
+     * rest: at the default capacity this is a couple of thousand workgroups, but the capacity is
+     * the caller's to choose and a dispatch past `maxComputeWorkgroupsPerDimension` is refused.
+     */
+    #init_free_list() {
+        const device = this.graphics.device;
+
+        const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/free list init");
+
+        shader_particle_init_free_list.dispatch({
+            encoder: cmd,
+            group_count_x: Math.min(
+                Math.ceil(this.capacity / PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE),
+                device.limits.maxComputeWorkgroupsPerDimension,
+            ),
+            bindings: { dead: this.buffers.dead, u_capacity: this.capacity },
+        });
+
+        cmd.finish();
+    }
+
+    /**
+     * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
+     */
+    #create_buffers() {
+        const device = this.graphics.device;
+        const capacity = this.capacity;
+        const buffers = this.buffers;
+
+        buffers.pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * WORD, usage: STORAGE });
+
+        this.#alive_descriptor = BufferResourceDescriptor.from(capacity * WORD, STORAGE);
+        this.#alive = this.graphics.buffer_allocator_main.get(this.#alive_descriptor);
+        buffers.alive = this.#alive;
+
+        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
+        // Just the counters to begin with. The per-emitter bounds accumulator that shares this
+        // buffer follows the emitter table's capacity, and there is no table yet.
+        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE_GROWABLE });
+
+        // Simulate's workgroup count, written by the END of one frame's build-indirect and read by
+        // the NEXT frame's dispatch — the one indirect buffer that crosses the boundary, and so the
+        // one the graph cannot own. Zero-initialised (WebGPU spec), so the first frame's indirect
+        // dispatch is a no-op until the first build-indirect has run.
+        buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
+
+        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE_UPLOAD });
+
+        // The warm-up queue: one entry to start with, grown on upload to what a frame registers.
+        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE_UPLOAD });
+
+        // The counters say every slot is free; the pass below makes it so. A handful of words is
+        // the whole of what the host ever writes into either — the list itself is the GPU's.
+        const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
+        counters[PARTICLE_COUNTER.DEAD] = capacity;
+
+        device.queue.writeBuffer(buffers.counters, 0, counters);
+
+        this.#init_free_list();
+    }
+
+    /**
+     * A 1x1 white atlas and a linear sampler, so the system draws before anyone hands it art.
+     * @returns {void}
+     */
+    #create_default_atlas() {
+        const device = this.graphics.device;
+
+        const texture = new GPUTextureContext(device);
+        texture.descriptor.label = "particles/default_atlas";
+        texture.descriptor.size = [1, 1];
+        texture.descriptor.format = "rgba8unorm";
+        texture.descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
+
+        device.queue.writeTexture({ texture: texture.gpu_texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
+        texture.incrementVersion();
+
+        // kept, not just viewed: a texture nothing holds is a texture nothing can free
+        this.#default_atlas = texture;
+        this.atlas = texture.obtainView();
+        this.atlas_sampler = device.createSampler({
+            label: "particles/atlas_sampler",
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+    }
+
+    /**
+     * Sizes of the persistent buffers, in bytes, as they stand — one entry per distinct buffer, so
+     * this is the feature's footprint and not a list of the names it binds them under.
+     * `alive_write` is `alive` under the frame's name for it and would otherwise be counted twice;
+     * `alive_read` is a second list, and appears only on the frames that hold one. Exposed for tests.
+     *
+     * @returns {Object<string, number>}
+     */
+    bufferSizes() {
+        const sizes = {};
+        const counted = new Set();
+
+        for (const [name, buffer] of Object.entries(this.buffers)) {
+            if (buffer === undefined || buffer === null || counted.has(buffer)) {
+                continue;
+            }
+
+            counted.add(buffer);
+            sizes[name] = buffer.size;
+        }
+
+        return sizes;
+    }
+
+    /**
+     * Copy the counts the GPU keeps back to the host and decode them, for display and diagnostics.
+     *
+     * Read back to *look at*: nothing here may size a pass. Every number describes a frame that has
+     * already been submitted, so by the time one arrives it is at best one frame stale — and sizing
+     * a dispatch or a draw from a stale count is a correctness bug, not an inaccuracy, for the
+     * reasons `shader_particle_build_indirect` sets out. This is the whole of what the feature ever
+     * reads back, and the only reason {@link INDIRECT} carries `COPY_SRC` at all.
+     *
+     * The draw args are not here and cannot be: they never leave the frame graph, which allocates
+     * them at the build-indirect pass and releases them after the last draw that reads them. Their
+     * instance count is {@link ParticleSystemStats#alive}, which the counters carry anyway.
+     *
+     * Two copies, two submissions and a map round trip, so a caller polling this for an overlay
+     * wants to rate-limit itself and to hold off while a previous read is still outstanding.
+     *
+     * @returns {Promise<ParticleSystemStats>}
+     */
+    async read_stats() {
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+
+        const read = (buffer, words) => inspect_gpu_buffer({
+            device,
+            buffer,
+            buffer_size: words * WORD,
+            // The mapped range is only valid for the length of the callback, so the decode either
+            // happens inside it or takes a copy. A copy, so one `Promise.all` sees both buffers.
+            callback: bytes => new Uint32Array(bytes.slice(0)),
+        });
+
+        const [counters, dispatch] = await Promise.all([
+            // The head of the buffer only: what follows the counters is the per-emitter bounds
+            // accumulator, which is boxes rather than counts and grows with the emitter table.
+            read(buffers.counters, PARTICLE_COUNTER_COUNT),
+            read(buffers.dispatch_args, 3),
+        ]);
+
+        return {
+            alive: counters[PARTICLE_COUNTER.ALIVE],
+            dead: counters[PARTICLE_COUNTER.DEAD],
+            spawn_budget: counters[PARTICLE_COUNTER.SPAWN_BUDGET],
+            alive_in: counters[PARTICLE_COUNTER.ALIVE_IN],
+            sim_padded: counters[PARTICLE_COUNTER.SIM_PADDED],
+            sim_workgroups: dispatch[0],
+        };
+    }
+
+    destroy() {
+        /*
+         The emitters go first, and they matter more than the buffers: they belong to their owners,
+         they outlive this system, and each is holding a row of the table about to be freed.
+         Retiring them here puts every emitter back where it was before this system saw it, so its
+         owner can register it with the next system.
+        */
+        for (const emitter of this.registry.emitters.slice()) {
+            this.registry.remove(emitter);
+        }
+
+        // Before the loop below, and not in it: the alive lists are the allocator's and go back to
+        // it. Destroying one would leave the pool holding a handle it will hand to the next caller.
+        this.#release_alive_lists();
+
+        for (const buffer of Object.values(this.buffers)) {
+            if (buffer !== undefined && buffer !== null) {
+                buffer.destroy();
+            }
+        }
+
+        this.buffers = {};
+        this.registry.database.destroy();
+
+        // the default atlas is this system's own; a page that replaced it owns what it put there
+        this.#default_atlas?.destroy();
+        this.#default_atlas = null;
+    }
+}
+
+/**
+ * A storage buffer holding `data`, replacing `previous` (destroyed) if it exists. The program
+ * buffer is monolithic — a program is variable-length, so there is no table to page it into — and
+ * is rebuilt whole on the rare frame the program heap changes.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer|undefined} previous
+ * @param {string} label
+ * @param {Uint32Array} data
+ * @returns {GPUBuffer}
+ */
+function replace_data_buffer(device, previous, label, data) {
+    previous?.destroy();
+
+    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE_UPLOAD });
+
+    device.queue.writeBuffer(buffer, 0, data);
+
+    return buffer;
+}