@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/playground/basis_textures/main.js

@@ -135,7 +135,7 @@ export async function start() {
 
     const camera = new PerspectiveCamera();
 
-    camera.transform.position.set(0, 2, -5);
+    camera.transform.setTranslation(0, 2, -5);
     camera.transform.lookAt(Vector3.zero);
 
     camera.near = 0.1;

package/src/shade/playground/ground_seam/main.js

@@ -105,7 +105,7 @@ export async function start() {
     camera.near = CAMERA.near;
     camera.far = CAMERA.far;
     camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
-    camera.transform.position.copy(CAMERA.position);
+    camera.transform.setTranslation(CAMERA.position[0], CAMERA.position[1], CAMERA.position[2]);
     camera.transform.lookAt(CAMERA.target);
     camera.transform.updateMatrix();
 

package/src/shade/playground/particle_editor/README.md

@@ -0,0 +1,175 @@
+# Particle effect editor — playground
+
+Both layers of the particle editor over one effect, with the effect running next to them.
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_editor/index.html>.
+
+Unlike `../particle_system/`, this page needs **no WebGPU at all**: the preview runs the effect's
+compiled bytecode on the CPU through the reference VM. It works in any browser that can run modules,
+Claude Code's in-app pane included.
+
+## The two layers
+
+The engine compiles a particle effect from a node graph down to bytecode for a small VM, and this
+edits it at both altitudes.
+
+**Graph** is the authoring layer: two node graphs, one per lifecycle phase.
+
+- **INIT** runs once per particle, when it spawns. **UPDATE** runs once per frame per live particle.
+  Both are kept built, so switching between them does not lose a camera or a selection.
+- **Getting around**: drag with the **right** button — or the middle one — to pan, and the wheel
+  zooms about the cursor. Drag with the **left** button over open canvas and you pull a selection
+  box instead: it takes every node it touches and every wire it holds whole, `Shift` adds to what
+  was selected, `Ctrl` toggles what the box covers, and the box says which of the three it is
+  while you are still holding it. Which button began the press decides which gesture it is, and
+  how far it travelled decides whether it was a press or a drag — so a right press that stays put
+  is the menu below and one that moves is a pan, the way Unreal's Blueprint canvas arranges the
+  same three gestures.
+- **Right-click the canvas** to add a node. The library opens under the cursor with the caret
+  already in a search field and the first match already chosen: type a few letters, press Enter, and
+  the node lands at the point that was clicked with the defaults its type declares, so it compiles
+  the moment it arrives. Arrow keys move the choice; Escape closes. Nodes are listed and headed by
+  what they are called rather than by the mnemonic they compile as — "Divide", not `div` — each with
+  the glyph its type carries; both are searched, so looking for either finds it.
+- **Drop a wire on empty canvas** and the same menu opens, narrowed to the types that have a port
+  which could take it — the ones with an input, when the wire came out of an output — and picking one
+  wires it up as it arrives. The node and the wire are one step on the undo timeline, because they
+  were one gesture.
+- Some nodes are **groups**: a node made of other nodes, drawn with a doubled left edge. Double-click
+  one to open it — the canvas shows the group's own graph and the toolbar grows a breadcrumb back
+  out — and groups nest, so the breadcrumb does. The ones shipped with the editor are locked: one
+  body is shared by every instance in every effect, so they open to be read rather than changed.
+  Groups are flattened away before anything is compiled, so a group costs exactly what its contents
+  cost.
+- **Make one**: select some nodes and press `Ctrl+G`, or the **Group** button. The wires that crossed
+  the selection become the group's ports, named after what they feed and typed by what the graph
+  resolved them to, and the group lands where the selection was with everything re-wired around it —
+  one step on the undo timeline. A group an author makes belongs to the effect: it is saved with it,
+  it is offered in the add-node menu like any other type, and it is unlocked, so opening it and
+  renaming it in the breadcrumb are both allowed. `Ctrl+Shift+G` puts one back.
+  A selection that something *outside* it runs in the middle of cannot become one node — the group
+  would have to run both before and after that thing — and the **Group** button says so rather than
+  letting you find out.
+- A map of the whole graph sits in the bottom-right corner, with a frame around the part on screen.
+  Click or drag it to go somewhere; it draws the wires along the routes they actually take, so the
+  map and the canvas are the same picture. The `-` in its corner folds it away to a button, and both
+  phases fold together.
+- Node parameters are edited in the node: four fields for a vector, a swatch and an alpha field for
+  a colour, a picker for an ISA enum, a picker of the effect's own attributes for an attribute
+  reference, `xyzw` for a swizzle.
+- The strip along the bottom lists every problem with the effect, from **both** phases. Click one to
+  jump to the phase it is in and select the node; the node is outlined in the graph too.
+
+**Code** is the same effect as instructions.
+
+- While the graph is authoritative this is that graph's lowering, read-only, and it re-lowers as the
+  graph changes. Register allocation, constant interning, the order the compiler chose — all of it
+  visible next to the graph that produced it.
+- **Lower to assembly** hands authority to the text. From there the graph is still on screen and
+  still editable, but the program is what is written here. That is the only way to reach an encoding
+  the node library has no node for.
+- Errors are listed with the line they are on, and that line is marked in the gutter.
+
+The syntax is documented at the top of `renderer/particles/isa/particle_assembly.js`.
+
+## The preview
+
+The right-hand panel runs the effect and draws one soft sprite per particle. It is the same bytecode
+a device would run — `execute_particle_vm` is the executor the WGSL interpreter is written to match,
+opcode for opcode and RNG bit for RNG bit — so what you are watching is the simulation, not an
+impression of it.
+
+What it is **not** is the renderer. There is no depth buffer, no lighting, no atlas, no flipbook and
+no transparency pipeline; a billboard is a radial gradient, and order comes from a painter's sort
+rather than from AVBOIT's voxel volume. For the real thing, `../particle_system/` draws the same kind
+of effect through the engine's own `Renderer`. What this preview does show honestly is everything the
+*effect* decides: where particles go, how long they live, how big they are, what colour they are,
+what blend mode they use, and how many are alive at once.
+
+Drag to orbit, wheel to dolly. `Pause` freezes the simulation without freezing the camera; `Restart`
+drops every particle and starts the effect over.
+
+**Editing a broken effect keeps the last program that compiled running**, and the overlay says so. A
+graph is invalid for most of the time anyone spends wiring one, and a preview that blanked out would
+be gone exactly when it is wanted.
+
+## What to try
+
+- Change a `const` node's value in the graph and watch the plume change while you are still typing.
+- Switch to **Code** and read what that graph became. Change the same number there instead — after
+  `Lower to assembly` — and watch the same thing happen from the other end.
+- Break the assembly (misspell a mnemonic). The line is marked, the panel says `does not assemble`,
+  and the preview carries on with the last good program.
+- Add an attribute in the inspector, then bind a render channel to it. Remove one that a channel was
+  bound to: the channel unbinds, and every node that named it is reported against the node.
+- Drag a wire out of an output and let go over open canvas. Only the nodes that could take it are
+  offered; pick one and it arrives already wired.
+- Drag a box around the four or five nodes that build the initial direction and press `Ctrl+G`. The graph gets
+  smaller and the program does not change at all — check it in **Code**. Open the group, rename it in
+  the breadcrumb, and watch the node on the canvas behind it change with it.
+- Add a `Simplex Noise 3D` and open it. Three hundred instructions of arithmetic, drawn — and read
+  only, because it is one of the library's own. `Curl Noise 4D` is twelve of those; the **Code** tab
+  is where to see what that means.
+- Set **blend** to `alpha` and back to `additive`. The preview composites accordingly.
+- `Ctrl+Z` in the graph. Every edit — a wire, a move, a parameter, a node from the menu — is one
+  timeline.
+
+## Driving it without a person
+
+The page is deliberately scriptable, because `requestAnimationFrame` is suspended in a hidden or
+headless tab and the preview would otherwise never advance:
+
+| handle | what it does |
+|---|---|
+| `__step(frames, dt)` | run exactly that many preview frames, return the live particle count |
+| `__export()` | the whole document as JSON |
+| `__import(json)` | replace the document with one |
+| `__reset()` | forget the kept document and reload |
+| `effect`, `view`, `actionProcessor` | the document, the root view, the undo timeline |
+
+The document is kept in `localStorage` between reloads, so an effect survives a refresh.
+
+## Where the pieces live
+
+The page owns almost nothing — it builds a document, mounts one view, and wires the window's size and
+`localStorage`. Everything else is the editor's, and is built to be docked as panels rather than
+used only here:
+
+| what | where |
+|---|---|
+| the document both layers edit | `editor/particles/effect/ParticleEffectDocument.js` |
+| the CPU preview simulation | `editor/particles/effect/ParticleReferenceSimulation.js` |
+| graph layer | `editor/view/particles/effect/ParticleGraphEditorView.js` |
+| what each node type is called and drawn as | `src/shade/renderer/particles/graph/particle_node_presentation.js` |
+| the node library the menu offers | `src/shade/renderer/particles/graph/particle_node_library.js` |
+| what a node group is, and its boundary | `src/shade/renderer/particles/graph/ParticleNodeGroup.js` |
+| making one out of a selection | `src/shade/renderer/particles/graph/make_particle_group.js` |
+| a group in a file | `src/shade/renderer/particles/graph/particle_group_json.js` |
+| the groups the editor ships with | `src/shade/renderer/particles/graph/groups/` |
+| code layer | `editor/view/particles/effect/ParticleCodeEditorView.js` |
+| emitter + attributes | `editor/view/particles/effect/ParticleEmitterInspectorView.js` |
+| preview | `editor/view/particles/effect/ParticlePreviewView.js` |
+| the four assembled | `editor/view/particles/effect/ParticleEffectEditorView.js` |
+
+Each panel takes nothing but the document, so an editor shell docks them individually and skips the
+assembled view. They share one `ActionProcessor`; pass a host editor's own and particle authoring
+lands on the application's undo timeline.
+
+Styling is two plain CSS files — `editor/view/node-graph/node-graph.css` for the graph views and
+`editor/view/particles/effect/particle-editor.css` for these panels — linked by this page's HTML.
+Plain CSS rather than SCSS so a page with no sass toolchain can serve them; a host that compiles
+`editor/style/editor.scss` includes them the same way.
+
+## Verifying it
+
+```bash
+npx vitest run editor/particles/effect editor/view/particles editor/view/node-graph src/shade/renderer/particles/graph src/shade/renderer/particles/isa
+```
+
+Those cover the document, the reference simulation, the four panels under jsdom, the node-graph base
+they are built on, and the assembly language underneath both layers. What no spec here can see is the
+picture, which is this page's job.

package/src/shade/playground/particle_editor/index.html

@@ -0,0 +1,76 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — particle effect editor</title>
+
+    <link rel="stylesheet" href="/editor/view/node-graph/node-graph.css">
+    <link rel="stylesheet" href="/editor/view/particles/effect/particle-editor.css">
+
+    <style>
+        :root {
+            color-scheme: dark;
+
+            /* the editor's own tokens, so the panels theme as they would inside the editor shell */
+            --meep-panel-bg: #1a1e25;
+            --meep-header-bg: #22262e;
+            --meep-divider-color: #10131a;
+            --meep-fg: #d6dae0;
+            --meep-fg-muted: #8b939f;
+            --meep-accent: #2d7dd2;
+            --meep-error: #ff7a7a;
+            --meep-warning: #e2b341;
+            --meep-font: 12px 'Segoe UI', system-ui, sans-serif;
+            --meep-graph-bg: #12151b;
+            --meep-graph-bg-glow: #1a1e26;
+            --meep-graph-node-bg: #232830;
+            --meep-graph-node-header: #2b313b;
+            --meep-graph-node-border: #363c46;
+            --meep-graph-input-bg: #171b21;
+        }
+
+        * { box-sizing: border-box; }
+
+        html, body {
+            height: 100%;
+            margin: 0;
+            overflow: hidden;
+            background: var(--meep-panel-bg);
+            color: var(--meep-fg);
+            font: var(--meep-font);
+        }
+
+        #root {
+            position: relative;
+            width: 100%;
+            height: 100%;
+        }
+
+        #message {
+            position: fixed;
+            inset: 0;
+            display: none;
+            align-items: center;
+            justify-content: center;
+            padding: 32px;
+            text-align: center;
+            background: #0a0d12e6;
+            color: var(--meep-error);
+            font-size: 15px;
+            white-space: pre-wrap;
+            z-index: 100;
+        }
+
+        #message:not(:empty) { display: flex; }
+    </style>
+</head>
+<body>
+
+<div id="root"></div>
+
+<div id="message"></div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/particle_editor/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/particle_editor/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_editor/main.js"],"names":[],"mappings":""}

package/src/shade/playground/particle_editor/main.js

@@ -0,0 +1,139 @@
+import { ActionProcessor } from "../../../core/process/undo/ActionProcessor.js";
+import { NodeDescriptionVisualRegistry } from "../../../core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
+import { PARTICLE_NODE_REGISTRY } from "../../renderer/particles/graph/ParticleNodeRegistry.js";
+import "../../renderer/particles/graph/particle_node_library.js";
+import { make_starter_particle_effect } from "../../../../editor/particles/effect/make_starter_particle_effect.js";
+import { ParticleEffectDocument } from "../../../../editor/particles/effect/ParticleEffectDocument.js";
+import {
+    ParticleEffectEditorView
+} from "../../../../editor/view/particles/effect/ParticleEffectEditorView.js";
+
+/**
+ * The particle effect editor, on a page of its own.
+ *
+ * Both authoring layers and the live preview, over one {@link ParticleEffectDocument} — which is the
+ * whole point of the page: the graph, the instructions it compiles to, the emitter settings and the
+ * effect running are four views of one thing, and an edit in any of them is visible in the rest
+ * before you have finished making it.
+ *
+ * The page owns almost nothing. It builds a document, mounts
+ * {@link ParticleEffectEditorView} over the whole window, and wires the browser-shaped edges the
+ * views deliberately do not have: the window's size, the address bar, and load/save through a file.
+ *
+ * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
+ * `/src/shade/playground/particle_editor/index.html`. See README.md for what to look at.
+ */
+
+/** Key the working document is kept under between reloads. @type {string} */
+const STORAGE_KEY = "meep.particle_editor.document";
+
+const element = id => document.getElementById(id);
+
+function main() {
+    const root = element("root");
+
+    const visualRegistry = new NodeDescriptionVisualRegistry();
+
+    PARTICLE_NODE_REGISTRY.getNodesAsArray().forEach(description => visualRegistry.generate(description));
+
+    const effect = restore(visualRegistry) ?? make_starter_particle_effect();
+
+    const actionProcessor = new ActionProcessor({});
+
+    const view = new ParticleEffectEditorView({ effect, actionProcessor });
+
+    root.appendChild(view.el);
+
+    view.link();
+
+    const resize = () => view.size.set(root.clientWidth, root.clientHeight);
+
+    resize();
+
+    window.addEventListener("resize", resize);
+
+    // The document is kept across reloads, because an editor that loses an effect to a refresh is
+    // one nobody trusts with an effect. Debounced: an edit is a change on every keystroke.
+    let save_timer = 0;
+
+    effect.on.changed.add(() => {
+        clearTimeout(save_timer);
+
+        save_timer = setTimeout(() => {
+            try {
+                localStorage.setItem(STORAGE_KEY, JSON.stringify(effect.toJSON()));
+            } catch (e) {
+                console.warn("could not keep the effect:", e.message);
+            }
+        }, 500);
+    });
+
+    // Everything a session might want to reach for, and the handles a scripted one needs. `__step`
+    // drives the preview by hand where requestAnimationFrame is suspended — a hidden or headless
+    // tab — which is what makes the page verifiable without a person watching it.
+    Object.assign(globalThis, {
+        effect,
+        view,
+        actionProcessor,
+        visualRegistry,
+
+        __step: (frames = 1, dt = 1 / 60) => {
+            for (let i = 0; i < frames; i++) {
+                view.preview.step(dt);
+            }
+
+            return view.preview.simulation.count;
+        },
+
+        __reset: () => {
+            localStorage.removeItem(STORAGE_KEY);
+            location.reload();
+        },
+
+        __export: () => JSON.stringify(effect.toJSON(), null, 2),
+
+        __import: json => {
+            effect.fromJSON(typeof json === "string" ? JSON.parse(json) : json, visualRegistry);
+        },
+    });
+}
+
+/**
+ * The document kept from the last session, if there is one and it still loads.
+ *
+ * A stored document that cannot be read is dropped rather than raised: it is almost always one
+ * written by an older build, and an editor that will not open because of it is worse than one that
+ * opens on the starting effect.
+ *
+ * @param {NodeDescriptionVisualRegistry} visualRegistry
+ * @returns {ParticleEffectDocument|null}
+ */
+function restore(visualRegistry) {
+    let stored;
+
+    try {
+        stored = localStorage.getItem(STORAGE_KEY);
+    } catch (e) {
+        return null;
+    }
+
+    if (stored === null) {
+        return null;
+    }
+
+    try {
+        return new ParticleEffectDocument().fromJSON(JSON.parse(stored), visualRegistry);
+    } catch (e) {
+        console.warn("the kept effect could not be opened, starting fresh:", e.message);
+
+        return null;
+    }
+}
+
+try {
+    main();
+} catch (e) {
+    console.error(e);
+
+    element("message").textContent = "The particle editor failed to start — see the console.\n\n" + e.message;
+}

package/src/shade/playground/particle_system/README.md

@@ -1,9 +1,18 @@
-# GPU particle system — playground
+# GPU particles, through AVBOIT — playground
 
-The whole GPU particle path running in a real scene: emitters, the VM, the alive/dead lists and the
-billboard renderer, driven end to end by the GPU with no renderer, no assets and no `Renderer`
-dependency. It moved here from `renderer/particles/prototypeParticleSystem.js`, which had no page to
-open it with.
+The GPU particle path where it belongs: inside the engine's own `Renderer`, drawn by the AVBOIT
+transparency pipeline as a side channel of the transparent meshes. The page owns a `Scene` and a
+camera and nothing else — no frame graph, no pass, no pipeline, no camera buffer and no depth
+texture. Two lines turn the particles on:
+
+```js
+renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
+renderer.feature_particles_enabled = true;
+```
+
+`particle_prototype.js` — the worked-example `fire_effect` / `smoke_effect` / `register_campfire` —
+lives here too, and is spec'd here rather than from the engine's own suite so that the dependency
+runs playground → renderer and never back.
 
 ## Running it
 
@@ -14,96 +23,117 @@ npm run dev --workspace @woosh/meep-engine
 then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
 
 It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
-imports from `file://` are blocked by CORS anyway. The page imports nothing but meep's own relative
-ESM, so any static server rooted at the repo also serves it.
-
-**It needs `subgroups`**, and refuses to start without it. The simulate input list is bucketed by VM
-program so no wave spans two programs, and the bucket offsets come from `graph_prefix_scan_csdldf`,
-which is built on subgroup ops.
+imports from `file://` are blocked by CORS anyway.
 
-**It needs immediate data**, and refuses to start without it. Emit, simulate and build-indirect each
-carry their per-dispatch state (`u_dt`, `u_time`, `u_frame`, and for emit the request count and the
-pool capacity) as an immediate block rather than as a transient uniform buffer, so an adapter whose
-WGSL lacks the `immediate` address space cannot build any of the three. The refusal names the byte
-counts. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one — it
-reports no adapter at all today, and no `immediate_address_space` in `wgslLanguageFeatures`.
+**It needs `subgroups` and immediate data**, both of which the renderer requires of any device it
+accepts — the prefix scans behind the spawn counts, the coherence bucketing and the scene hierarchy
+are built on subgroup ops, and every particle compute pass carries its per-dispatch state as an
+immediate block. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one
+— it has reported no adapter at all since 2026-09-02, and no `immediate_address_space` in
+`wgslLanguageFeatures` before that.
 
 ## What is on screen
 
-Four emitters sharing one 32k pool, chosen so each renderer path is visible at once:
+A `Scene` with opaque geometry (a floor, a pillar, a block), **one transparent pane** across the
+middle of the set, a sunlight, the default environment, and five emitters sharing one pool:
 
 | emitter | blend | projection | what it is there to show |
 |---|---|---|---|
-| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js`, at the foot of the pillar |
+| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js` next door, at the foot of the pillar |
 | smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
 | sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
-| dust | alpha | billboard, soft-depth | a wide slow drift, so the ground plane and the low wall both get a soft intersection |
+| dust | alpha | billboard, soft-depth | a wide slow drift, so the floor gets a soft intersection |
+| torch | additive | billboard | a child of a node that orbits — the emitter never moves, its parent does, and the GPU hierarchy pass composes the two |
+
+The torch is the point of the scene-node design. Its record holds a row of the scene's
+`transforms` table, not a matrix; the page writes its parent's translation once a frame the way it
+would for any node, and the emitter's world position comes out of the same hierarchy pass that
+places every mesh. An emitter parented to an animated joint works the same way, with nothing copied
+through the CPU.
 
 Four distinct compiled programs, so this is also where the simulation-order bucketing has something
 to do: without it a simulate wave holds fire, smoke, spark and dust particles side by side, each
-wanting different opcodes out of the interpreter's `switch` and different registers out of its
-dynamically-indexed file. Nothing on screen changes when it is on — it is a coherence change, not a
-visual one — which is why it is pinned by specs rather than by looking.
+wanting different opcodes out of the interpreter's `switch`. Nothing on screen changes when it is on
+— it is a coherence change, not a visual one — which is why it is pinned by specs rather than by
+looking.
+
+## The property the page exists to demonstrate
 
-Ground plane and three boxes are drawn first into a reverse-Z `depth32float` buffer. The billboard
-pass loads that colour target and depth-tests against the same buffer read-only, so particles are
-**occluded** by the boxes and the soft-depth emitters sample the depth they were occluded by.
+**Particles and transparent surfaces composite against each other with no order between them.**
+Orbit around the pane. From in front, the particles behind it are dimmed by it; from behind, the
+pane is dimmed by the smoke in front of it — and neither was sorted against the other, because both
+wrote their extinction into the same voxel volume and both were resolved out of the same
+accumulators. That is what a side channel buys, and what a blended pass bolted on after the
+transparency pipeline cannot do at any price.
 
-Things worth looking at:
+Two more things are visible from the same seat:
 
-- particles disappearing behind the pillar as the camera orbits — that is the depth test,
-- smoke and dust softening where they touch a surface instead of showing a hard intersection line —
-  that is `PARTICLE_FLAG_SOFT_DEPTH` and the reverse-Z linearisation,
+- **the additive emitters do not darken what is behind them.** Fire, sparks and the torch write the
+  emission accumulator, which the resolve adds outside the coverage normalization, so they light
+  the frame without taking coverage from it.
+- **switch the mode to MBOIT and the particles vanish while the pane stays.** MBOIT is the legacy
+  path and has no particle channel. The simulation keeps running — turn AVBOIT back on and the
+  effects are where they would have been, not restarted — which is the honest way to see which
+  pipeline the particles now live in.
+
+Also worth looking at, from the path itself:
+
+- particles disappearing behind the pillar as the camera orbits — the depth test, read-only, on the
+  same buffer the soft fade samples,
+- smoke and dust softening where they touch a surface instead of showing a hard intersection line,
 - sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
-- both blend modes in **one** draw with one pipeline: `particle_premultiply` picks per particle, so
-  there is no additive pass and no alpha pass.
+- the torch's trail following its carrier.
+
+The frame is GPU-driven end to end, spawning included. The host walks no emitters and counts no
+particles: the emitter tick pass integrates every emitter's rate on the GPU, a prefix scan of its
+counts sizes the emit dispatch, and `shader_particle_build_indirect` writes the simulate dispatch
+args and the draw args. The "Burst 4000 sparks" button is the one thing the CPU asks for, and it
+asks through the same path — a command list a pass adds to that emitter's pending spawns.
 
 The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
-indirect arg buffers. Those are read back **to look at**. Nothing on the CPU sizes a pass.
+indirect arg buffers. Those are read back **to look at**, on a command buffer of their own after the
+renderer's. Nothing on the CPU sizes a pass.
 
-## The property the page exists to demonstrate
+## Bounds spheres matter here
 
-The frame is GPU-driven end to end. `shader_particle_build_indirect` writes both the simulate
-dispatch args and the billboard draw args on the GPU; the next frame's simulate runs through
-`dispatchWorkgroupsIndirect` and this frame's draw through `drawIndirect`. The host's only sizing
-decision is how many *new* particles to spawn, which is a per-emitter rate times `dt` and has
-nothing to do with how many are already alive.
+Every emitter carries one, and under AVBOIT it is not only the culling test it used to be: the
+occupancy pass marks the depth slices an emitter may occlude in from that sphere, once per emitter
+rather than once per particle. A sphere that does not hold its effect leaves particles occluding at
+slightly the wrong depth. `PARTICLE_EMITTER_MOTION` in `particle_scene.js` is the motion each effect
+is built from, and `particle_scene.spec.js` checks the spheres against it.
 
-Sizing either from a CPU readback instead would be a correctness bug rather than a latency one: a
-stale count that is too small leaves the tail of the alive list unsimulated, so those slots are
-never freed, and one that is too large re-simulates entries past the end, pushing a dead slot onto
-the free list twice — it is then popped twice and two live particles share one record.
+They are sized to hold where the effect actually goes, not the last corner its jitter could reach:
+a sphere big enough for the worst case would mark most of the depth range and cost the adaptive
+slicing the very thing it is for.
 
 ## Verifying it
 
-`particle_scene.js` holds the scene with every reference to the page removed, so
-`particle_scene.spec.js` can encode the same frames against `SoftwareGPUDevice`:
-
 ```bash
-npx vitest run src/shade/playground/particle_system/particle_scene.spec.js
+npx vitest run src/shade/playground/particle_system
 ```
 
-That mock runs no shaders, so the spec asserts nothing about what a pass computed. What it does
-assert is that the frame is legal and wired the way the design requires — pass order and
-attachments, no frame reading the list it appends to, the immediate blocks written before every
-dispatch that declares them, simulate and the draw both taking their counts from the indirect
-buffers, and the two orderings staying in separate buffers: simulate reads the program-coherent
-list, the billboard draw reads the alive list. Any WebGPU validation failure anywhere in the frame arrives as an
-uncaptured error, which every test fails on.
+`particle_scene.js` holds the scene and the configuration with every reference to the page removed,
+so the spec builds the real scene — meshlets, materials, emitters — with no device, and checks what
+is the page's to get wrong: the emitters are the scene's nodes, the torch hangs off the carrier, the
+pane is transparent while the rest is opaque, the bounds spheres hold their effects, and
+`configure_particles` turns the feature on, selects AVBOIT and hands the system its sprite.
+
+What a particle *frame* encodes is not this page's business any more. It is pinned next to the code,
+against `SoftwareGPUDevice`, in `renderer/particles/graph_particles.spec.js` (the simulation, pass
+by pass, and every dispatch sized by GPU-written args) and `graph_particles_avboit.spec.js` (the
+three side-channel passes, their attachments and their indirect draws).
 
-The picture is the browser's job; the spec cannot see it.
+The picture is the browser's job; no spec here can see it.
 
 ### Stepping frames by hand
 
 Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
 runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
-hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot.
+hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot,
+and `camera_state()` / `apply_camera(...)` copy a view between sessions.
 
 ## What this page does not cover
 
-Depth sorting. `EMITTER_FLAG.SORT` and the bucketed depth sort in `particles/sort/` (histogram →
-csdldf scan → scatter) are not wired in here: the billboard pass draws the alive list directly, so
-alpha-blended emitters are in emission order rather than back-to-front. The two soft-depth emitters are faint and diffuse enough that it
-does not read as wrong, which is exactly why it should not be taken as evidence that sorting works.
-Lighting is the unlit hook, too — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one
-the renderer feature swaps in.
+Lighting is the unlit hook — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one a
+lit-emitter variant would swap in. No emitter opts into simulation culling, so the frustum test in
+the tick pass is never taken here; the bounds spheres are read by the occupancy pass all the same.