@woosh/meep-engine 3.17.2 → 3.18.0

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

@@ -1,991 +1,1189 @@
-import { assert } from "../../../core/assert.js";
-import { align_4 } from "../../../core/binary/align_4.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { warn_limited } from "../../util/warn_limited.js";
-import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
-import {
-    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_SIMULATE_WORKGROUP_SIZE,
-    PARTICLE_SORT_BUCKET_COUNT,
-    PARTICLE_SPAWN_COMMAND_WORDS,
-    PARTICLE_VM_FAST_REGISTER_SLOTS,
-} from "./ParticleConstants.js";
-import { PARTICLE_COUNTER, PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
-import { graph_particles_simulate } from "./graph_particles.js";
-import {
-    graph_particle_avboit_draw,
-    graph_particle_avboit_occupancy,
-    graph_particle_avboit_splat,
-} from "./graph_particles_avboit.js";
-import { graph_particles_billboard } from "./graph_particles_billboard.js";
-import { ParticleRenderMode } from "./ParticleRenderMode.js";
-import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
-import { graph_particle_sort } from "./sort/graph_particle_sort.js";
-
-const WORD = Uint32Array.BYTES_PER_ELEMENT;
-
-const STORAGE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
-const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
-
-/**
- * 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
- *
- * Every piece of persistent GPU state: the particle pool, the ping-pong alive lists, the dead
- * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) scratch,
- * the emitter database (the emitter table and the GPU-owned state table, one buffer), the packed
- * program buffer, and the spawn-command ring. Buffers that depend on the emitter set — the
- * coherence scratch on the number of distinct programs, the program buffer on the heap, the
- * database on its own pages — are grown inside {@link execute}, the way ReSTIR's reservoirs follow
- * the resolution. The render-order (sort) scratch is not in that list because it is not
- * unconditional: see below.
- *
- * 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 scene nodes
- *
- * There is no `addEmitter`. A {@link ParticleEmitter} is a {@link Node3D}: put it in the scene —
- * on its own or under a joint — and the next {@link execute} finds it in the scene's node list,
- * gives it a row in the emitter table pointed at the `transforms` row the scene context gave the
- * node, and it starts spawning. Take it out of the scene and its row is retired and its particles
- * freed. The sweep runs only when the scene's membership version moves, which is how per-frame
- * upkeep stays 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, and the one thing the mode changes
- *
- * {@link execute} is the whole per-frame call, once per frame. It always records everything that
- * moves particles and leaves the alive list and the indirect draw args as graph handles; what it
- * records after that is the {@link ParticleRenderMode} it was given.
- *
- * `BILLBOARD` sorts the alive list back-to-front and draws it over a colour target, because
- * premultiplied over-blending is order-dependent. `AVBOIT` records neither: under the renderer the
- * system is an `AVBOITSideChannel`, and the transparency 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 same handles
- * and composite into a volume and a set of accumulators that are sums, so an ordering would buy
- * nothing — and the sort is four passes and a scan over every live particle, plus two lists a word
- * per particle each, which is why the mode also decides whether those buffers exist at all.
- *
- * ## 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 nodes the emitters are, 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. Drives the alive-list ping-pong and 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;
-
-    /**
-     * View-depth range the render sort quantises: particles nearer than `[0]` share the front bin,
-     * farther than `[1]` the back one. Read only by {@link ParticleRenderMode.BILLBOARD}.
-     * @type {Float32Array}
-     */
-    sort_depth_range = new Float32Array([0.1, 100]);
-
-    /**
-     * 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 — a harness copying the counters out to display them — never for the frame loop,
-     * which reads nothing back. Entries that grow with the emitter set are replaced in place.
-     *
-     * @type {object}
-     */
-    buffers = {};
-
-    /**
-     * Distinct programs the coherence scratch is currently sized for.
-     * @type {number}
-     */
-    #sim_bucket_capacity = 0;
-
-    /**
-     * 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);
-
-    /**
-     * Emitter node -> the sweep that last saw it in the scene.
-     * @type {Map<import("./runtime/ParticleEmitter.js").ParticleEmitter, number>}
-     */
-    #swept = new Map();
-
-    /** @type {number} */
-    #sweep = 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 {GPUTexture|null}
-     */
-    #default_atlas = null;
-
-    /**
-     * The scene membership version the emitter set was last reconciled against.
-     * @type {number}
-     */
-    #instances_version = -1;
-
-    /** @type {object|null} */
-    #pipeline = null;
-
-    /** @type {string} */
-    #pipeline_key = "";
-
-    /**
-     * 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,
-    };
-
-    /** @type {{capacity: number, group_count: number}} */
-    #emitters = { capacity: 0, group_count: 0 };
-
-    /**
-     * This frame's simulation, for the draw that follows it: 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 };
-
-    /** @type {object} */
-    #render = {
-        atlas: null,
-        atlas_sampler: null,
-        obtain_pipeline: (color_format, depth_format) => this.#obtain_pipeline(color_format, depth_format),
-    };
-
-    /**
-     * @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 = 1 << 16, 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);
-    }
-
-    /**
-     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
-     * @returns {number}
-     */
-    get alive_write_index() {
-        return 1 - (this.frame % 2);
-    }
-
-    /**
-     * 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 in the scene");
-
-        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 simulation half of the 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.
-     * What it leaves as graph handles is what a draw consumes, whichever draw that turns out to be.
-     *
-     * @param {object} params see {@link execute}
-     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
-     * @param {number} params.camera
-     * @param {number} params.scene_database
-     * @param {number} params.dt
-     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
-     */
-    #simulate({ graph, camera, scene_database, dt }) {
-        this.#sync_membership();
-        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;
-
-        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;
-        buffers.alive_write = buffers.alive[this.alive_write_index];
-        // 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 draw that follows, whichever it is, and for nothing past this frame.
-        const current = this.#simulated;
-        current.graph = graph;
-        current.scene_database = scene_database;
-        current.emitter_group_count = emitters.group_count;
-        current.handles = simulated;
-
-        // Consumed: the count was recorded into the graph, the words were uploaded.
-        this.#spawn_command_count = 0;
-
-        this.frame++;
-        this.time += dt;
-
-        return simulated;
-    }
-
-    /**
-     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
-     * it.
-     *
-     * {@link ParticleRenderMode.BILLBOARD} adds the depth sort and one billboard draw over `color`
-     * with fixed-function blending, for a page with no transparency pipeline of its own.
-     * {@link ParticleRenderMode.AVBOIT} adds nothing: the orchestrator draws the particles later in
-     * the frame through {@link avboit_occupancy}, {@link avboit_splat} and {@link avboit_draw}, off
-     * the handles this just produced, and its accumulators are order-independent — so the sort is
-     * skipped and its buffers are never allocated. `color` comes straight back either way, so a
-     * caller can assign the result unconditionally and let the mode be the only difference.
-     *
-     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
-     * emitter node has its `transforms` row, 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
-     * @param {ParticleRenderMode} [params.mode] who draws, and so whether there is a sort
-     * @param {number} [params.color] graph handle of the colour target to draw over. Required by
-     *   `BILLBOARD`; returned untouched by `AVBOIT`
-     * @param {number} [params.depth] graph handle of the scene depth (tested, never written).
-     *   Required by `BILLBOARD`
-     * @returns {number|undefined} the colour handle after the particle draw, or `color` unchanged
-     */
-    execute({ graph, camera, scene_database, color, depth, dt, mode = ParticleRenderMode.BILLBOARD }) {
-        assert.defined(graph, "graph");
-        assert.isNumber(dt, "dt");
-        assert.enum(mode, ParticleRenderMode, "mode");
-
-        const billboard = mode === ParticleRenderMode.BILLBOARD;
-
-        // Checked before the simulation rather than at the draw: the simulation advances `frame` and
-        // `time` and writes the pool, and a throw after that leaves a frame half-stepped.
-        if (billboard) {
-            assert.isNonNegativeInteger(color, "color");
-            assert.isNonNegativeInteger(depth, "depth");
-        }
-
-        const simulated = this.#simulate({ graph, camera, scene_database, dt });
-
-        if (!billboard) {
-            // AVBOIT: the side channels draw these handles later in the frame, and the colour target
-            // is not this call's to touch.
-            return color;
-        }
-
-        // Allocated here rather than in the constructor: they are two words per particle plus the
-        // bins, and only this mode ever reads them. A system the renderer drives never makes them.
-        this.#ensure_sort_buffers();
-
-        // The render order: back-to-front by view depth, so premultiplied transparency composites
-        // correctly. Its two per-particle passes take the dispatch the coherence reset wrote from
-        // the GPU's own alive count.
-        const sorted = graph_particle_sort({
-            graph,
-            gpu: this.buffers,
-            camera,
-            emitter_database: simulated.emitter_database,
-            pool: simulated.pool,
-            alive: simulated.alive,
-            counters: simulated.counters,
-            dispatch_args: simulated.sim_dispatch_args,
-            bucket_count: PARTICLE_SORT_BUCKET_COUNT,
-            near: this.sort_depth_range[0],
-            far: this.sort_depth_range[1],
-        });
-
-        const render = this.#render;
-        render.atlas = this.atlas;
-        render.atlas_sampler = this.atlas_sampler;
-
-        // One instanced billboard draw over the sorted list, sized by the draw args this frame's
-        // build-indirect wrote.
-        return graph_particles_billboard({
-            graph,
-            camera,
-            color,
-            depth,
-            pool: simulated.pool,
-            draw_list: sorted,
-            emitter_database: simulated.emitter_database,
-            draw_args: simulated.draw_args,
-            render,
-        });
-    }
-
-    /**
-     * What this frame's {@link simulate} 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' bounds spheres, 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,
-            scene_database: current.scene_database,
-            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,
-        });
-    }
-
-    /**
-     * Bring the emitter set in line with the scene: emitter nodes that arrived get rows, nodes that
-     * left give theirs back. Runs only when the scene's membership version has moved.
-     *
-     * A node the scene context has not placed yet (no `transforms` row) is left for the next frame,
-     * and the version is not recorded, so the sweep runs again until every emitter is bound.
-     */
-    #sync_membership() {
-        const scene = this.scene_context.scene;
-        const batch = scene.instances;
-
-        if (batch.version === this.#instances_version) {
-            return;
-        }
-
-        const sweep = ++this.#sweep;
-        const nodes = batch.nodes;
-        const node_count = nodes.length;
-        const mapping = this.scene_context.id_mapping;
-        const registry = this.registry;
-        const swept = this.#swept;
-
-        let complete = true;
-
-        for (let i = 0; i < node_count; i++) {
-            const node = nodes[i];
-
-            if (node.isParticleEmitter !== true) {
-                continue;
-            }
-
-            const transform_row = mapping.get(node.id);
-
-            if (transform_row === undefined) {
-                complete = false;
-                continue;
-            }
-
-            if (registry.context(node) === undefined) {
-                registry.add(node, transform_row);
-            } else {
-                registry.set_transform_row(node, transform_row);
-            }
-
-            swept.set(node, sweep);
-        }
-
-        for (const [emitter, seen] of swept) {
-            if (seen !== sweep) {
-                registry.remove(emitter);
-                swept.delete(emitter);
-            }
-        }
-
-        if (complete) {
-            this.#instances_version = batch.version;
-        }
-    }
-
-    /**
-     * 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.#ensure_sim_buffers(this.bucketCount());
-    }
-
-    /**
-     * 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 simulation-order scratch is sized from the number of distinct programs, which only ever
-     * grows (programs are never reclaimed, see {@link EmitterRegistry}). Reallocated when it does;
-     * nothing in these buffers outlives a frame, so nothing is copied.
-     *
-     * @param {number} buckets
-     */
-    #ensure_sim_buffers(buckets) {
-        if (buckets <= this.#sim_bucket_capacity) {
-            return;
-        }
-
-        const device = this.graphics.device;
-        const buffers = this.buffers;
-        const capacity = this.capacity;
-
-        for (const name of ["sim_list", "sim_keys", "sim_histogram", "sim_bucket_counts", "sim_cursor"]) {
-            buffers[name]?.destroy();
-        }
-
-        // 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.
-        buffers.sim_list = device.createBuffer({ label: "particles/sim_list", size: (capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD, usage: STORAGE });
-        buffers.sim_keys = device.createBuffer({ label: "particles/sim_keys", size: capacity * WORD, usage: STORAGE });
-        // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
-        // rounded up to a multiple of four.
-        buffers.sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(buckets)) * WORD, usage: STORAGE });
-        buffers.sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: buckets * WORD, usage: STORAGE });
-        buffers.sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: buckets * WORD, usage: STORAGE });
-
-        this.#sim_bucket_capacity = buckets;
-    }
-
-    /**
-     * The render-order scratch, made on the first frame that actually sorts.
-     *
-     * Only {@link ParticleRenderMode.BILLBOARD} reads any of it, and the two per-particle lists are
-     * a word per particle each — at the renderer's default capacity, half a megabyte that AVBOIT
-     * would never touch. Nothing in them outlives a frame, so there is nothing to carry over and the
-     * first sorted frame is as correct as any later one.
-     */
-    #ensure_sort_buffers() {
-        const buffers = this.buffers;
-
-        if (buffers.sorted !== undefined) {
-            return;
-        }
-
-        const device = this.graphics.device;
-        const capacity = this.capacity;
-
-        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
-        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
-    }
-
-    /**
-     * 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 });
-        buffers.alive = [
-            device.createBuffer({ label: "particles/alive_a", size: capacity * WORD, usage: STORAGE }),
-            device.createBuffer({ label: "particles/alive_b", size: capacity * WORD, usage: STORAGE }),
-        ];
-        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
-        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE });
-
-        // Indirect args, written on-GPU. Zero-initialised (WebGPU spec), so the first frame's
-        // indirect dispatch/draw are no-ops until the first build-indirect has run.
-        buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
-        buffers.draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * WORD, usage: INDIRECT });
-        buffers.sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: 3 * WORD, usage: INDIRECT });
-
-        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE });
-
-        // Every slot free, and the counters saying so.
-        const dead = new Uint32Array(capacity);
-        for (let i = 0; i < capacity; i++) {
-            dead[i] = i;
-        }
-        const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
-        counters[PARTICLE_COUNTER.DEAD] = capacity;
-
-        device.queue.writeBuffer(buffers.dead, 0, dead);
-        device.queue.writeBuffer(buffers.counters, 0, counters);
-    }
-
-    /**
-     * A 1x1 white atlas and a linear sampler, so the system draws before anyone hands it art.
-     */
-    #create_default_atlas() {
-        const device = this.graphics.device;
-
-        const texture = device.createTexture({
-            label: "particles/default_atlas",
-            size: [1, 1],
-            format: "rgba8unorm",
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-        });
-
-        device.queue.writeTexture({ texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
-
-        // kept, not just viewed: a texture nothing holds is a texture nothing can free
-        this.#default_atlas = texture;
-        this.atlas = texture.createView();
-        this.atlas_sampler = device.createSampler({
-            label: "particles/atlas_sampler",
-            magFilter: "linear",
-            minFilter: "linear",
-            addressModeU: "clamp-to-edge",
-            addressModeV: "clamp-to-edge",
-        });
-    }
-
-    /**
-     * @param {string} color_format
-     * @param {string} depth_format
-     * @returns {object} the billboard pipeline descriptor for these attachment formats
-     */
-    #obtain_pipeline(color_format, depth_format) {
-        const key = `${color_format}/${depth_format}`;
-
-        if (this.#pipeline === null || this.#pipeline_key !== key) {
-            this.#pipeline = create_particle_billboard_pipeline({
-                color_format,
-                depth_format,
-                // reverse-Z, the engine convention
-                depth_compare: "greater",
-            });
-            this.#pipeline_key = key;
-        }
-
-        return this.#pipeline;
-    }
-
-    /**
-     * Sizes of the persistent buffers, in bytes, as they stand. Exposed for tests.
-     * @returns {Object<string, number>}
-     */
-    bufferSizes() {
-        const sizes = {};
-
-        for (const [name, buffer] of Object.entries(this.buffers)) {
-            if (Array.isArray(buffer)) {
-                sizes[name] = buffer[0].size;
-            } else if (buffer !== undefined && buffer !== null) {
-                sizes[name] = buffer.size;
-            }
-        }
-
-        return sizes;
-    }
-
-    destroy() {
-        /*
-         The emitters go first, and they matter more than the buffers: they are the scene's nodes,
-         they outlive this system, and each is holding a row of the table about to be freed. A node
-         left holding one is stranded — the next system's membership sweep reads `row !== -1` as
-         "already mine", takes the moved branch rather than the arrived one, and never registers it.
-         Retiring them here puts every emitter back where it was before this system saw it.
-        */
-        for (const emitter of this.registry.emitters.slice()) {
-            this.registry.remove(emitter);
-        }
-        this.#swept.clear();
-        this.#instances_version = -1;
-
-        for (const buffer of Object.values(this.buffers)) {
-            if (Array.isArray(buffer)) {
-                buffer.forEach((b) => b.destroy());
-            } else 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 });
-
-    device.queue.writeBuffer(buffer, 0, data);
-
-    return buffer;
-}
+import { assert } from "../../../core/assert.js";
+import { align_4 } from "../../../core/binary/align_4.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { warn_limited } from "../../util/warn_limited.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.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_SORT_BUCKET_COUNT,
+    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 {
+    graph_particle_avboit_draw,
+    graph_particle_avboit_occupancy,
+    graph_particle_avboit_splat,
+} from "./graph_particles_avboit.js";
+import { graph_particles_billboard } from "./graph_particles_billboard.js";
+import { ParticleRenderMode } from "./ParticleRenderMode.js";
+import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
+import { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
+import { graph_particle_sort } from "./sort/graph_particle_sort.js";
+import { WARMUP_QUEUE } from "./warmup/shader_particle_warmup.js";
+import { warmup_schedule } from "./warmup/warmup_schedule.js";
+import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+
+const WORD = Uint32Array.BYTES_PER_ELEMENT;
+
+const STORAGE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
+
+/**
+ * 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
+ *
+ * Every piece of persistent GPU state: the particle pool, the ping-pong alive lists, the dead
+ * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) scratch,
+ * the emitter database (the emitter table and the GPU-owned state table, one buffer), the packed
+ * program buffer, and the spawn-command ring. Buffers that depend on the emitter set — the
+ * coherence scratch 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. The render-order (sort)
+ * scratch is not in that list because it is not unconditional: see below.
+ *
+ * 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 scene nodes
+ *
+ * There is no `addEmitter`. A {@link ParticleEmitter} is a {@link Node3D}: put it in the scene —
+ * on its own or under a joint — and the next {@link execute} finds it in the scene's node list,
+ * gives it a row in the emitter table pointed at the `transforms` row the scene context gave the
+ * node, and it starts spawning. Take it out of the scene and its row is retired and its particles
+ * freed. The sweep runs only when the scene's membership version moves, which is how per-frame
+ * upkeep stays 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, and the one thing the mode changes
+ *
+ * {@link execute} is the whole per-frame call, once per frame. It always records everything that
+ * moves particles and leaves the alive list and the indirect draw args as graph handles; what it
+ * records after that is the {@link ParticleRenderMode} it was given.
+ *
+ * `BILLBOARD` sorts the alive list back-to-front and draws it over a colour target, because
+ * premultiplied over-blending is order-dependent. `AVBOIT` records neither: under the renderer the
+ * system is an `AVBOITSideChannel`, and the transparency 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 same handles
+ * and composite into a volume and a set of accumulators that are sums, so an ordering would buy
+ * nothing — and the sort is four passes and a scan over every live particle, plus two lists a word
+ * per particle each, which is why the mode also decides whether those buffers exist at all.
+ *
+ * ## 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 nodes the emitters are, 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. Drives the alive-list ping-pong and 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;
+
+    /**
+     * View-depth range the render sort quantises: particles nearer than `[0]` share the front bin,
+     * farther than `[1]` the back one. Read only by {@link ParticleRenderMode.BILLBOARD}.
+     * @type {Float32Array}
+     */
+    sort_depth_range = new Float32Array([0.1, 100]);
+
+    /**
+     * 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 — a harness copying the counters out to display them — never for the frame loop,
+     * which reads nothing back. Entries that grow with the emitter set are replaced in place.
+     *
+     * @type {object}
+     */
+    buffers = {};
+
+    /**
+     * Distinct programs the coherence scratch is currently sized for.
+     * @type {number}
+     */
+    #sim_bucket_capacity = 0;
+
+    /**
+     * 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 sync_membership}), 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);
+
+    /**
+     * Emitter node -> the sweep that last saw it in the scene.
+     * @type {Map<import("./runtime/ParticleEmitter.js").ParticleEmitter, number>}
+     */
+    #swept = new Map();
+
+    /** @type {number} */
+    #sweep = 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;
+
+    /**
+     * The scene membership version the emitter set was last reconciled against.
+     * @type {number}
+     */
+    #instances_version = -1;
+
+    /**
+     * Program assignments used to build the previous frame's coherence list.
+     * @type {number}
+     */
+    #program_assignment_version = 0;
+
+    /** @type {object|null} */
+    #pipeline = null;
+
+    /** @type {string} */
+    #pipeline_key = "";
+
+    /**
+     * 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 draw that follows it: 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 };
+
+    /** @type {object} */
+    #render = {
+        atlas: null,
+        atlas_sampler: null,
+        obtain_pipeline: (color_format, depth_format) => this.#obtain_pipeline(color_format, depth_format),
+    };
+
+    /**
+     * @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 = 1 << 16, 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);
+    }
+
+    /**
+     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
+     * @returns {number}
+     */
+    get alive_write_index() {
+        return 1 - (this.frame % 2);
+    }
+
+    /**
+     * 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 in the scene");
+
+        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 simulation half of the 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.
+     * What it leaves as graph handles is what a draw consumes, whichever draw that turns out to be.
+     *
+     * @param {object} params see {@link execute}
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+     * @param {number} params.camera
+     * @param {number} params.scene_database
+     * @param {number} params.dt
+     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
+     */
+    #simulate({ graph, camera, scene_database, dt }) {
+        this.sync_membership();
+        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;
+        buffers.alive_write = buffers.alive[this.alive_write_index];
+        buffers.alive_read = buffers.alive[1 - this.alive_write_index];
+        // 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 draw that follows, whichever it is, and for nothing past this frame.
+        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;
+    }
+
+    /**
+     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
+     * it.
+     *
+     * {@link ParticleRenderMode.BILLBOARD} adds the depth sort and one billboard draw over `color`
+     * with fixed-function blending, for a page with no transparency pipeline of its own.
+     * {@link ParticleRenderMode.AVBOIT} adds nothing: the orchestrator draws the particles later in
+     * the frame through {@link avboit_occupancy}, {@link avboit_splat} and {@link avboit_draw}, off
+     * the handles this just produced, and its accumulators are order-independent — so the sort is
+     * skipped and its buffers are never allocated. `color` comes straight back either way, so a
+     * caller can assign the result unconditionally and let the mode be the only difference.
+     *
+     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
+     * emitter node has its `transforms` row, 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
+     * @param {ParticleRenderMode} [params.mode] who draws, and so whether there is a sort
+     * @param {number} [params.color] graph handle of the colour target to draw over. Required by
+     *   `BILLBOARD`; returned untouched by `AVBOIT`
+     * @param {number} [params.depth] graph handle of the scene depth (tested, never written).
+     *   Required by `BILLBOARD`
+     * @returns {number|undefined} the colour handle after the particle draw, or `color` unchanged
+     */
+    execute({ graph, camera, scene_database, color, depth, dt, mode = ParticleRenderMode.BILLBOARD }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+        assert.enum(mode, ParticleRenderMode, "mode");
+
+        const billboard = mode === ParticleRenderMode.BILLBOARD;
+
+        // Checked before the simulation rather than at the draw: the simulation advances `frame` and
+        // `time` and writes the pool, and a throw after that leaves a frame half-stepped.
+        if (billboard) {
+            assert.isNonNegativeInteger(color, "color");
+            assert.isNonNegativeInteger(depth, "depth");
+        }
+
+        const simulated = this.#simulate({ graph, camera, scene_database, dt });
+
+        if (!billboard) {
+            // AVBOIT: the side channels draw these handles later in the frame, and the colour target
+            // is not this call's to touch.
+            return color;
+        }
+
+        // Allocated here rather than in the constructor: they are two words per particle plus the
+        // bins, and only this mode ever reads them. A system the renderer drives never makes them.
+        this.#ensure_sort_buffers();
+
+        // The render order: back-to-front by view depth, so premultiplied transparency composites
+        // correctly. Its two per-particle passes take the dispatch the coherence reset wrote from
+        // the GPU's own alive count.
+        const sorted = graph_particle_sort({
+            graph,
+            gpu: this.buffers,
+            camera,
+            emitter_database: simulated.emitter_database,
+            pool: simulated.pool,
+            alive: simulated.alive,
+            counters: simulated.counters,
+            dispatch_args: simulated.sim_dispatch_args,
+            bucket_count: PARTICLE_SORT_BUCKET_COUNT,
+            near: this.sort_depth_range[0],
+            far: this.sort_depth_range[1],
+        });
+
+        const render = this.#render;
+        render.atlas = this.atlas;
+        render.atlas_sampler = this.atlas_sampler;
+
+        // One instanced billboard draw over the sorted list, sized by the draw args this frame's
+        // build-indirect wrote.
+        return graph_particles_billboard({
+            graph,
+            camera,
+            color,
+            depth,
+            pool: simulated.pool,
+            draw_list: sorted,
+            emitter_database: simulated.emitter_database,
+            draw_args: simulated.draw_args,
+            render,
+        });
+    }
+
+    /**
+     * What this frame's {@link simulate} 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,
+        });
+    }
+
+    /**
+     * Bring the emitter set in line with the scene: emitter nodes that arrived get rows, nodes that
+     * left give theirs back. Runs only when the scene's membership version has moved.
+     *
+     * A node the scene context has not placed yet (no `transforms` row) is left for the next frame,
+     * and the version is not recorded, so the sweep runs again until every emitter is bound.
+     * An atlas owner may call this after the scene context builds, before setting row regions.
+     * execute() calls it as well; unchanged membership costs one version comparison.
+     * @returns {void}
+     */
+    sync_membership() {
+        const scene = this.scene_context.scene;
+        const batch = scene.instances;
+
+        if (batch.version === this.#instances_version) {
+            return;
+        }
+
+        const sweep = ++this.#sweep;
+        const nodes = batch.nodes;
+        const node_count = nodes.length;
+        const mapping = this.scene_context.id_mapping;
+        const registry = this.registry;
+        const swept = this.#swept;
+
+        let complete = true;
+
+        for (let i = 0; i < node_count; i++) {
+            const node = nodes[i];
+
+            if (node.isParticleEmitter !== true) {
+                continue;
+            }
+
+            const transform_row = mapping.get(node.id);
+
+            if (transform_row === undefined) {
+                complete = false;
+                continue;
+            }
+
+            if (registry.context(node) === undefined) {
+                registry.add(node, 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 (node.prewarm > 0) {
+                    this.#warmup_queue.push(node);
+                }
+            } else {
+                registry.set_transform_row(node, transform_row);
+            }
+
+            swept.set(node, sweep);
+        }
+
+        for (const [emitter, seen] of swept) {
+            if (seen !== sweep) {
+                registry.remove(emitter);
+                swept.delete(emitter);
+            }
+        }
+
+        if (complete) {
+            this.#instances_version = batch.version;
+        }
+    }
+
+    /**
+     * 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 });
+        }
+
+        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 });
+
+        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;
+    }
+
+    /**
+     * Scratch follows the peak number of program ids. The coherence list itself is persistent:
+     * the next simulate consumes its entries and padding with the previous frame's saved count.
+     *
+     * @param {number} buckets
+     */
+    #ensure_sim_buffers(buckets) {
+        if (buckets <= this.#sim_bucket_capacity) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+        const capacity = this.capacity;
+
+        for (const name of ["sim_keys", "sim_histogram", "sim_bucket_counts", "sim_cursor"]) {
+            buffers[name]?.destroy();
+        }
+
+        // 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: (capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD, usage: STORAGE });
+        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();
+        }
+        buffers.sim_keys = device.createBuffer({ label: "particles/sim_keys", size: capacity * WORD, usage: STORAGE });
+        // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
+        // rounded up to a multiple of four.
+        buffers.sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(buckets)) * WORD, usage: STORAGE });
+        buffers.sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: buckets * WORD, usage: STORAGE });
+        buffers.sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: buckets * WORD, usage: STORAGE });
+
+        this.#sim_bucket_capacity = buckets;
+    }
+
+    /**
+     * The render-order scratch, made on the first frame that actually sorts.
+     *
+     * Only {@link ParticleRenderMode.BILLBOARD} reads any of it, and the two per-particle lists are
+     * a word per particle each — at the renderer's default capacity, half a megabyte that AVBOIT
+     * would never touch. Nothing in them outlives a frame, so there is nothing to carry over and the
+     * first sorted frame is as correct as any later one.
+     */
+    #ensure_sort_buffers() {
+        const buffers = this.buffers;
+
+        if (buffers.sorted !== undefined) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const capacity = this.capacity;
+
+        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
+        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
+    }
+
+    /**
+     * 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 });
+        buffers.alive = [
+            device.createBuffer({ label: "particles/alive_a", size: capacity * WORD, usage: STORAGE }),
+            device.createBuffer({ label: "particles/alive_b", size: capacity * WORD, usage: STORAGE }),
+        ];
+        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 });
+
+        // Indirect args, written on-GPU. Zero-initialised (WebGPU spec), so the first frame's
+        // indirect dispatch/draw are no-ops until the first build-indirect has run.
+        buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
+        buffers.draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * WORD, usage: INDIRECT });
+        buffers.sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: 3 * WORD, usage: INDIRECT });
+
+        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE });
+
+        // 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 });
+
+        // Every slot free, and the counters saying so.
+        const dead = new Uint32Array(capacity);
+        for (let i = 0; i < capacity; i++) {
+            dead[i] = i;
+        }
+        const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
+        counters[PARTICLE_COUNTER.DEAD] = capacity;
+
+        device.queue.writeBuffer(buffers.dead, 0, dead);
+        device.queue.writeBuffer(buffers.counters, 0, counters);
+    }
+
+    /**
+     * 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",
+        });
+    }
+
+    /**
+     * @param {string} color_format
+     * @param {string} depth_format
+     * @returns {object} the billboard pipeline descriptor for these attachment formats
+     */
+    #obtain_pipeline(color_format, depth_format) {
+        const key = `${color_format}/${depth_format}`;
+
+        if (this.#pipeline === null || this.#pipeline_key !== key) {
+            this.#pipeline = create_particle_billboard_pipeline({
+                color_format,
+                depth_format,
+                // reverse-Z, the engine convention
+                depth_compare: "greater",
+            });
+            this.#pipeline_key = key;
+        }
+
+        return this.#pipeline;
+    }
+
+    /**
+     * Sizes of the persistent buffers, in bytes, as they stand. Exposed for tests.
+     * @returns {Object<string, number>}
+     */
+    bufferSizes() {
+        const sizes = {};
+
+        for (const [name, buffer] of Object.entries(this.buffers)) {
+            if (Array.isArray(buffer)) {
+                sizes[name] = buffer[0].size;
+            } else if (buffer !== undefined && buffer !== null) {
+                sizes[name] = buffer.size;
+            }
+        }
+
+        return sizes;
+    }
+
+    destroy() {
+        /*
+         The emitters go first, and they matter more than the buffers: they are the scene's nodes,
+         they outlive this system, and each is holding a row of the table about to be freed. A node
+         left holding one is stranded — the next system's membership sweep reads `row !== -1` as
+         "already mine", takes the moved branch rather than the arrived one, and never registers it.
+         Retiring them here puts every emitter back where it was before this system saw it.
+        */
+        for (const emitter of this.registry.emitters.slice()) {
+            this.registry.remove(emitter);
+        }
+        this.#swept.clear();
+        this.#instances_version = -1;
+
+        for (const buffer of Object.values(this.buffers)) {
+            if (Array.isArray(buffer)) {
+                buffer.forEach((b) => b.destroy());
+            } else 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 });
+
+    device.queue.writeBuffer(buffer, 0, data);
+
+    return buffer;
+}