@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_LEDGER.md

@@ -0,0 +1,642 @@
+# AVBOIT — ledger
+
+Companion to [`AVBOIT_PLAN_2026_09_03.md`](./AVBOIT_PLAN_2026_09_03.md). One entry per step of §8, in the
+order they landed, each recording what was built, how it was verified, and what the step found that the plan
+did not predict. Findings that change the plan are noted here and the plan's revision header is bumped, never
+silently edited.
+
+Branch: `claude/avboit-transparency-pipeline-192cff`, worktree
+`.claude/worktrees/avboit-transparency-pipeline-192cff`, from `9ab84a154`.
+
+---
+
+## 0. Survey — 2026-09-03
+
+**Done.** Read the deck (text extraction via `pdftotext`; the page renderer is not installed here) and the
+MBOIT pipeline end to end: orchestrator, three shaders, frame-graph API, resource descriptors, the bucket →
+draw-command prep, the emulator's capabilities, the software device's recording API, and the `Renderer` call
+site and mode-switch precedents.
+
+**Findings that shaped the plan:**
+
+- The sorted meshlet buffer the draws consume has no count header
+  (`shader_sort_meshlets_by_material.js:20` writes a bare `array<MeshletDefinition>`); the collection *before*
+  sorting does, and the prep helper already builds an indirect dispatch command over it. The occupancy pass
+  needs both, so the helper returns two more handles (plan §3.1).
+- No render pipeline in the tree writes a storage buffer from the fragment stage, and the pipeline-layout
+  helper applies one visibility to all groups. The splat pass builds its layout per group (plan §3.11).
+- The emulator models `atomic<T>` as `{ value }` objects and implements `atomicAdd/Min/Max/Or`, `textureStore`
+  on 3D `CPUBitmapData`, `extractBits/insertBits`, `countOneBits`; barriers are no-ops and there is no
+  workgroup-cooperative dispatch. The warp build is therefore a single invocation so it stays
+  emulator-testable (plan §3.4).
+- View-space depth sign: the volumetrics take `-(view_matrix × p).z`, so the camera looks down −Z; the
+  occupancy pass uses the same (plan §3.3).
+- `float32-blendable` is on the device floor purely for MBOIT's `r32float`/`rgba32float` targets; AVBOIT
+  blends `rgba16float` only (plan §3.11).
+- The in-app browser pane cannot run the full renderer (immediate data unsupported there, per memory), so the
+  playground look (step 9) needs a real Chrome tab; module compilation (step 8) works in either.
+
+---
+
+## 1. Skeleton and switch — 2026-09-03
+
+**Done.** `ShadeTransparencyMode` (`MBOIT = 0`, `AVBOIT = 1`), `Renderer.transparency_mode` defaulting to
+MBOIT, a ternary at the single transparency call site selecting the recorder, and
+`graph_prepare_meshlet_draw_commands_by_material` returning `meshlet_collection` and
+`meshlet_iterator_command` beside what it returned before. `Renderer.js` and the prep helper are CRLF files;
+edited byte-exactly.
+
+**Verified.** The rasterize spec tree (14 files, 81 tests) passes with the helper change; the source-level spec
+in `graph_rasterize_meshes_transparent_avboit.spec.js` pins the import, the default and the ternary.
+
+**Found.** Nothing the plan did not predict.
+
+---
+
+## 2. Depth curve, packing, warp — 2026-09-03
+
+**Done.** `chunk_avboit_depth_curve` (t(z), z(t)), `chunk_avboit_pack` (10|10|10, counts ↔ extinction ↔
+transmittance, the overflow predicate), `AVBOIT_WARP_STRUCT`, `chunk_avboit_warp` (φ, and the view-depth →
+virtual → physical composition), each with an emulator spec.
+
+**Found.**
+
+- The emulator hands a `u32` with its top bit set back as a negative JS number (`0xFFFFFF00` reads as
+  `-256`). Specs compare through `>>> 0`. `countOneBits` and the shift operators are unsigned internally, so
+  the shaders themselves are unaffected.
+- `vec3<f32>` values travel as `Float32Array` through the emulator, so round-trip expectations are f32-exact
+  (six digits), not f64.
+
+---
+
+## 3. Occupancy and warp build — 2026-09-03
+
+**Done.** `chunk_avboit_occupancy` (range, word mask, dilate, fold), `shader_avboit_occupancy` (per meshlet,
+indirect over the filtered collection), `shader_avboit_build_warp` (one invocation: dilate → count → halve
+until it fits, then the exclusive-prefix LUT), with specs for the chunk and for the whole build shader
+dispatched through the emulator.
+
+**Found.** The implementation dilates at *every* level it evaluates rather than once at the finest and once at
+the settled level, which is the same thing where it matters (the settled level) and simpler to reason about.
+`AVBOIT_OCCUPANCY_DILATION` at the prepass is therefore only a belt-and-braces one slice. Plan §3.4 describes
+the per-level version.
+
+Specs pin: empty → `V_max` and an all-zero LUT; a run that dilates to exactly `P` does not halve; one over
+halves once and is re-dilated at the coarser level; everywhere-occupied halves down to `V = P`; the prefix is
+exclusive, monotone, and never exceeds `P`.
+
+---
+
+## 4. Splat — 2026-09-03
+
+**Done.** `shader_avboit_splat`: low-resolution render pass, no depth attachment, a `r8unorm` dummy target
+with `writeMask: 0`, per-group pipeline layout with the atomics group fragment-only, linear splat with
+per-channel overflow marks stored inverted under `atomicMax`. `chunk_avboit_tint` factored out so the splat
+and the draw compute the transmission tint from one function.
+
+**Found.** No un-jitter in the splat: `unjitter_uv` is derivative-based and the jitter is in
+internal-resolution pixels, so at 1/8 resolution the correction would be eight times too large. Recorded in
+the shader's docblock; the plan did not mention it.
+
+**Verified.** Validity tier (vertex + fragment) and the tier-3 layout spec: group 3 entries are `FRAGMENT`
+with `buffer.type === "storage"`, groups 0–2 are `VERTEX | FRAGMENT`, the target's `writeMask` is 0, no
+`depthStencil`.
+
+---
+
+## 5. Integrate — 2026-09-03
+
+**Done.** `shader_avboit_integrate`, 8×8 workgroups, exclusive prefix into a `P + 1`-deep `rgba8unorm` 3D
+storage texture, per-channel saturation and overflow pinning. Emulator spec over one column: exclusive
+prefix, independent channels, saturation, a summed field past 255 saturating in one step, an overflow mark
+pinning only its channel, a mark at slice 0.
+
+**Found.** Nothing unpredicted.
+
+---
+
+## 6. Draw and sample — 2026-09-03
+
+**Done.** `chunk_avboit_sample_transmittance` (bias in virtual slices, warp, `(p + 0.5) / (P + 1)` depth
+coordinate, `exp`), `avboit_draw_fragment_body` (one WGSL text shared by the IBL and Brick4 pipelines, where
+the two MBOIT resolve shaders share theirs by duplication), `shader_avboit_draw_ibl`,
+`shader_avboit_draw_brick4`, `AVBOIT_INTEGRAL_SAMPLER_DESCRIPTOR`. Emulator spec of the sample chunk against a
+hand-built integral: run boundaries land on texel centres, an event in front attenuates by `exp(-E × ln 256)`,
+the bias clears a surface's own linear splat, a gap sample reads the previous run's total and none of the
+next run's, beyond the far plane the sample reads the total.
+
+**Found.** The emulator's `null` sampler is the linear clamp-to-edge fallback the spec wants, so no sampler
+object is built there.
+
+---
+
+## 7. Resolve, orchestrator, tier 3 — 2026-09-03
+
+**Done.** `shader_avboit_resolve` (reads the scene, writes a fresh `rgba16float`; RGB total transmittance
+cannot blend in place), the full `graph_rasterize_meshes_transparent_avboit` with its sub-recorders exported
+(`graph_avboit_occupancy`, `_build_warp`, `_splat`, `_integrate`, `_draw`),
+`avboit_shaders_wgsl_validity.spec.js` (10 modules, zero diagnostics),
+`graph_rasterize_meshes_transparent_avboit.spec.js` on the software device.
+
+**Found.**
+
+- `graph_compute_pass` cannot create a `read_write` storage buffer from a descriptor: the helper puts every
+  readable binding through the read path first, so the descriptor arrives at `pass.write` as an object. The
+  warp build is recorded by hand instead, and its `settings` uniform is serialized with
+  `encoder.allocateTransientValueBuffer` — the plain-object convenience only exists inside the graph
+  helpers, not in `ComputeShader.dispatch`. Plan §3.1's table is unchanged; the pass is the same, just not
+  via the helper.
+- No spec builds a `GPUViewContext` over a scene on the mock, so the tier-3 spec pins the exported
+  sub-recorders (warp build: one workgroup into a buffer of the struct's size; integration: the dispatch
+  covers the voxel grid and the texture is `3d`, `P + 1` deep, storage + sampled; resolve: one 3-vertex draw
+  into a fresh target) and the `Renderer` switch at source level. The whole orchestrator's first encode is on
+  a real device (steps 8–9).
+
+**Verified.** 62 tests across the avboit directory; 81 across `rasterize/`; the full `src/shade` suite
+(489 files, 3360 tests) passes; `scripts/check-types.mjs` reports the declaration emit clean and zero
+consumer-visible errors.
+
+---
+
+## 8–9. Real compile and the look — 2026-09-03, handed over
+
+**Done.** `src/shade/playground/avboit/`: the deck's harness in miniature (a stack of cards at a controlled
+spacing, a tinted glass pane, an opaque backdrop), the MBOIT/AVBOIT switch, and a **Compile check** that
+pushes all ten AVBOIT modules through `createShaderModule` on the live device and prints
+`getCompilationInfo`. The README carries the one scripted session (six steps) with what "pass" looks like
+for each.
+
+**Not done here, and why.** The in-app browser pane returned `null` from `requestAdapter()` this session
+(its `wgslLanguageFeatures` are present, the adapter is not — the same state
+`playground-needs-immediate-data` recorded on 2026-09-02), and no Claude-in-Chrome browser was connected.
+So neither the real compile nor the picture happened on this side. What the pane did prove: the page
+loads under the dev server, every import resolves (the ten shader modules assemble at import time, so a
+chunk-dependency or struct error would have thrown there), and `start()` runs up to
+`Renderer.initialize`, which reports `requestAdapter returned null` cleanly. The sources were dumped
+(`scratchpad/wgsl/*.wgsl`, 217 KB) for a pane compile should an adapter come back. What is known: every
+module passes the validator, which has no type checker; the type-level risks are listed below so the first
+compile failure, if any, is quick to place.
+
+**Type-level things the validator could not see** (in the order a compiler would meet them):
+
+- `avboit_warp` takes `ptr<storage, AVBOITWarp, read>`; the splat and draw pass `&warp` where `warp` is
+  declared through `addStorageBuffer(..., false)`. `var<storage>` without an explicit mode is `read`, which
+  matches.
+- `atomicAdd(&extinction_volume[column + u32(s)], …)` indexes an `array<atomic<u32>>` binding from the
+  fragment stage — core WGSL, but the first such pipeline in the tree.
+- `textureStore(integral, vec3<i32>, vec4<f32>)` on `texture_storage_3d<rgba8unorm, write>`.
+- `select(vec3<u32>, vec3<u32>, vec3<bool>)` and `select(vec3<f32>, vec3<f32>, vec3<bool>)` in the
+  integration; both are the component-wise overload.
+- The splat fragment entry has no return type against a pipeline with one colour target at `writeMask: 0`.
+
+---
+
+## 10. Docs — 2026-09-03
+
+**Done.** `RENDERER_CONTRACT.md` §2 says which mode needs `float32-blendable`; §9 lists
+`transparency_mode`. `CHANGELOG.md` carries the entry under the unreleased 4.0.0 "Added". The plan is at
+revision 1; nothing in steps 1–9 required a revision of its design sections.
+
+**Open, for the session in the playground README:** the ten real compiles; the first frame under AVBOIT;
+the stack at the default spacing (does the bar behind it show through?); the spacing at which the cards
+fall into one slice; the red pane's tint on the backdrop. Results go here as entry 11.
+
+---
+
+## 11. Path-traced reference on the playground — 2026-09-03
+
+**Done.** A third mode on the page, "path traced (reference)": `feature_path_tracing_enabled` on, TAA
+forced off while it is, the tracer's running-mean floor lowered from 0.01 to 0.002 so the image keeps
+settling past 100 samples, a **Reset accumulation** button, and a once-a-second readout of how converged
+the image is. That readout needed one small engine addition: `AccumulatingPathTracer.min_sample_count`,
+the sample count of the tile that has had the fewest (the per-tile counters were private, and frames
+elapsed is not a sample count — a frame advances one tile).
+
+**What the reference is good for, and not** (README "The reference"):
+
+- The tracer rolls each transparent hit against alpha and continues the ray, so it converges to the
+  exact order-independent composite of the card stack — the thing both OIT modes approximate. Good.
+- It has no per-channel transmission tint (thin-walled transmission carries only `(1 - F)`), so it
+  cannot confirm AVBOIT's glass tint; the pane is compared with the tint off.
+- Its shadow rays treat geometry as opaque (the tracer's own `TODO`), so the cards cast full shadows
+  there and none under either OIT mode. The stack, not its shadow, is the comparison.
+
+**Verified.** `path_tracer/` has no specs of its own; the getter is a read of a private array. The
+page's module graph was re-loaded in the pane (see entry 8–9 for what the pane can and cannot prove).
+
+---
+
+## 12. First renders on a real device — 2026-09-03
+
+Alex ran the playground and pasted three canvas captures at the default settings (four cards, alpha
+0.85, spacing 1.5, red glass pane): path traced, AVBOIT, MBOIT. Read against the code, not measured.
+
+**The stack — the deck's depth-complexity claim reproduces.** Under MBOIT the green card, two layers
+back, shows through both the red and the blue card as a lighter rectangle inside the red one. Under
+the path tracer and under AVBOIT it does not; the overlap is red with the blue card directly behind
+faintly visible. AVBOIT is the closer of the two to the reference on the stack. Both rasterized modes
+render the cards darker than the tracer, and they agree with each other, so that is a forward-shading
+versus tracer difference and not this pipeline's.
+
+**Also as predicted:** the tracer casts full shadows from the cards (its occlusion query treats
+geometry as opaque), neither OIT mode does.
+
+**The glass pane — the tint is working as written, and is the wrong default.** Under AVBOIT the pane
+is deep red; under the tracer and MBOIT it is clear glass. The material is transmission 1 with a red
+base colour, and `chunk_avboit_tint` multiplies transmitted light by that base colour, so green and
+blue drop to ~14 %. It is not opaque — the horizon shows through as the dark-to-bright step at floor
+level — but it is a material semantic the other paths do not have: the forward shader states there is
+no per-channel transmission tint in the material model, and the tracer's thin-walled transmission
+carries only the Fresnel split. The contract's promise that the two modes take the same inputs and
+are safe to flip per frame does not survive a flip that recolours glass.
+
+Two corrections to what the code says about itself: the chunk docblock calls base-colour-as-tint
+"the OpenPBR default", which it is not (OpenPBR's transmission colour defaults to white; glTF's
+transmission extension is the one that uses the base colour); and plan §4's first row rests on the
+same reading.
+
+**Proposed:** keep the RGB plumbing, default the tint off, expose it as a runtime switch
+(`renderer.avboit.transmission_tint_from_base_color`, carried in the warp header so the splat and
+draw agree per frame), a checkbox on the page, plan to revision 2. The alternative — keep it on and
+document it as an AVBOIT-only semantic — makes one asset mean two things depending on a renderer
+switch. Alex chose the first; entry 14.
+
+**Also closed by these renders:** step 8's real compile, for the IBL variant. An AVBOIT frame on a real
+device means the occupancy, warp, splat, integrate, IBL draw and resolve modules all compiled and the
+pipeline ran end to end. The Brick4 draw variant is not exercised by the page (`indirect_lighting_mode`
+is IBL there) and remains compiled only by the validator.
+
+---
+
+## 13. The deck's opaque-card case on the page — 2026-09-03
+
+**Done.** At Alex's request: a small pale quad, alpha 1 on a `Transparent` material, one unit behind
+the last card and offset so part of it is seen through the stack and part stands against the backdrop
+and the dark bar. Both pipelines clamp its coverage at `OIT_COVERAGE_MAX` (0.997), so it is the "0 %
+transmittance card" of deck slides 35–38: the case where a moment reconstruction cannot hold the
+step, leaks the background through the surface, and tears along the depth discontinuity at its edge.
+A checkbox (`opaque_quad`, default on) and step 8 of the README's session.
+
+**What to expect from AVBOIT here, from the design:** the quad's extinction saturates its slice
+(`-ln(1 - 0.997) / ln 256 ≈ 1.05`, clamped to 1.0), so the integral behind it reads 1.0 and every
+fragment further back is weighted by a transmittance of 1/256. Its edge is a step in the extinction
+volume at 1/8 resolution, softened by the draw's trilinear sample over about one voxel — so a slight
+halo of that width is the expected artefact, not a leak. Anything behind the quad showing through its
+interior would be a finding.
+
+---
+
+## 14. The tint, kept and off by default — 2026-09-03
+
+**Done.** `AVBOITSettings` on `Renderer.avboit` with one switch, `transmission_tint_from_base_color`
+(default false). The orchestrator takes `avboit` beside its other inputs (the MBOIT one ignores it), the
+warp build copies it into a new `tint_from_base_color` header word, and both the splat and the draw
+weight `chunk_avboit_tint` by `transmission_factor × f32(warp.tint_from_base_color)`. The chunk's
+docblock now says whose semantics the mapping is (glTF's, not OpenPBR's). Plan to revision 2 (§3.5,
+§4, §7). Contract §9 lists `avboit`. The page has a checkbox for it, off by default, and step 6 of the
+session turns it on before comparing the pane.
+
+**Why a header word and not a shader constant:** the splat and the draw must agree within a frame, and
+the header is already the one place both read per-frame facts from; a runtime flag lets the page do
+the A/B without a rebuild.
+
+**Verified.** Build-warp emulator spec asserts the header copies the flag; validity tier over the
+edited modules; rasterize spec tree.
+
+---
+
+## 15. Decisions on the open items — 2026-09-03
+
+Alex's answers to the open list, and what each became.
+
+**Slice floor — mine to call; 5 cm is a spacing worth resolving.** Virtual slice thickness is
+`(z0 + z - near) · ln(1 + (far - near) / z0) / V`. At the page's camera (`near 0.1`, `far 200`,
+`z0 = 0.8`) and `V = 1024` that was 5.8 cm at 10 m: one slice, under the two-slice bias, so 5 cm
+blended. `AVBOIT_VIRTUAL_SLICES_MAX` is now 4096 — 1.5 cm at 10 m, 2.8 cm at 20 m, 7 cm at 50 m — so
+5 cm resolves out to about 17 m before the bias eats it, and the adaptive halving still pulls it back
+when more than 128 slices are occupied. The bias stays at 2.0 rather than dropping to the analytic
+1.5: the half-slice margin is what covers the depth difference between a splat fragment (a
+1/8-resolution pixel centre) and a draw fragment on a sloped surface. Cost: 128 occupancy words, a
+16 KB LUT, a longer single-lane loop in the warp build. Specs unchanged in intent (they read the
+constant) and green.
+
+**The opaque quad — fine as is.** Stays on the page.
+
+**Camera.** `OrbitalCameraController` on the page (drag, wheel, right-drag), **Copy camera** to the
+clipboard and a box, **Apply camera** from the box, `camera_state()` / `apply_camera()` /
+`configure({ camera })` from the console. Plan §9 gains the slope risk in its own words: a splat
+fragment carries its low-resolution pixel centre's depth, and on a grazing surface that can exceed
+the bias.
+
+**Brick4 — should land.** The variant exists and is validator-clean; the page now has an
+indirect-lighting select (IBL / Brick4) so the Brick4 draw pipeline compiles and draws on a device.
+The scene has no probes, so the indirect term is black either way; the step is in the session.
+
+**Timings — hook up the profiler.** Done as on `volumetrics_froxel`: **Profile** starts a
+`GPUProfileSession` at `WORKLOAD`, pressing it again drains and downloads
+`avboit-<mode>-<timestamp>.sgpt` for the gpu-inspector-tool, with the mode and the page's settings in
+the note and the adapter in the meta. Same settings, two recordings, one per mode, is the comparison.
+
+**Software device — wrong tool for an end-to-end spec, and that is fine.** Plan §6 tier 3 now says
+so; the full-orchestrator spec is off the list.
+
+**Phase 2 — only clean, unambiguous, non-situational.** Decided item by item in plan §7 revision 3.
+One landed: the draw discards a fragment the volume already calls extinct (`T ≤ 1/256` in every
+channel) *before* forward shading. No new resource or pass; the error is bounded by `1/256` of the
+background (`AVBOIT_EXTINCT_TRANSMITTANCE`), below the 8-bit volume's own resolution. Tile skipping
+(no: sub-millisecond passes), the zero-transmittance depth cull (not now: situational, touches the
+depth other passes read, wants its own plan and a scene that needs it), the monochrome buffer (no:
+two representations for content we do not have), the sparse texture (no: speculative).
+
+**Back-sided materials — ignored for now.** Plan §7 keeps the note.
+
+**AVBOIT is the default.** `Renderer.transparency_mode = ShadeTransparencyMode.AVBOIT`; the enum,
+the contract (§2 keeps `float32-blendable` on the floor while MBOIT is selectable; §9 row), the
+changelog and the page's default select follow. The source-level spec pins the new default.
+
+**Committed** on the branch after this entry.
+
+---
+
+## 16. The page's camera and profile buttons, reported not working — 2026-09-03
+
+Alex: the camera could not be moved, and **Profile** appeared to do nothing with no way to stop it.
+
+**What was verified here.** The page was restructured so the camera, its controller and every control
+are wired *before* the device is requested. That made the input path testable in the in-app pane,
+which has no adapter: a synthetic pointer drag dispatched on the canvas orbited the camera from
+`(0, 2.5, 12)` to `(-7.3, 3.7, 9.4)` and a wheel event zoomed it, read back through `camera_state()`.
+So `OrbitalCameraController` on `document.body`, the pointer device and the transform write are
+correct as wired. What could not be reproduced is the failure in a real session.
+
+**What the restructure found.** Building geometry before `Renderer.initialize` threw
+`Cannot read properties of undefined (reading 'exports')`: the meshlet builder runs on a WASM
+instance (`MeshoptClusterizer`) that instantiates asynchronously at import, and the renderer's own
+initialization had been what gave it time. The page now awaits `MeshoptClusterizer.ready` itself. Not
+the reported fault (the committed order built geometry after the device), but the same class of
+thing: a step that silently depended on another step's timing.
+
+**Made robust, since the fault could not be seen.** Every control handler runs through a guard that
+puts a failure into the report panel (`<what> failed: <message>`) instead of only the console; the
+final settings application is guarded so a settings error cannot stop the frame loop from starting;
+the Profile button carries a `recording` state (label and red border) so a running capture is
+unmistakable and the same button stops it; the controls are spelled out under the canvas. If a real
+session still does not orbit, the report panel now says why.
+
+**Suspicion, unverified.** With HMR off, a reload taken while the page's files were being rewritten
+on disk can pair one version of `index.html` with another of `main.js` or `Renderer.js`; a
+`TypeError` in the settings step then killed `start()` before the frame loop, which is the one
+sequence that leaves the buttons registered, the camera frozen and no picture of the cause. A hard
+reload after this commit is the first thing to try.
+
+---
+
+## 17. First timings — 2026-09-03
+
+Alex ran a short profiling session on the page (the deck's harness in miniature: four cards, the
+glass pane, the opaque quad, 1280x720): **AVBOIT 289.9 us, MBOIT 282.4 us**, averages of the
+transparency work, which he reads as within the noise. Device and capture files not recorded here.
+
+**What that says.** On this scene the two pipelines cost the same. That is the expected shape, not a
+surprise: the deck's cost argument (AVBOIT approaching no-OIT, slides 106-110) comes from VFX content
+with tens of millions of overdrawn transparent pixels, where the 1/8-resolution splat, the saturated
+integral and the early-out remove most of the shading work. Six quads at 720p have almost nothing
+for those to remove, and AVBOIT's fixed costs — the occupancy pass, the warp build, the integration
+over a 160x90x129 volume, the resolve into a fresh target — are of the same order as MBOIT's two
+full-resolution passes over the same few quads. So the number closes the question "does the new path
+cost more on light content" (no), and leaves open the one the deck actually answers, which needs a
+scene with real transparent overdraw. Plan §9's contention risk is unmeasured until then.
+
+**Committed** with this entry.
+
+---
+
+## 18. Review against the engine — 2026-09-03
+
+Alex asked three questions of the code: is anything reinvented, does it follow one function per
+chunk, does it fight the engine. Surveyed and fixed; plan to revision 4.
+
+**Reinvented, now reused.**
+
+- *The depth curve.* `chunk_avboit_depth_curve` (t(z), z(t), a `z0` knob) was a second copy of what the
+  light clusters and the froxels already use: `cluster_depth_to_z_slice` with parameters from
+  `build_light_cluster_parameters`. That builder's `scale` argument is the linearization the deck
+  describes; `avboit_build_depth_curve` chooses it so the curve is pure log from the near offset,
+  because the warp makes near precision free. Gone: the chunk, its inverse, its spec, the
+  `AVBOIT_DEPTH_CURVE_LINEARIZATION` constant, and the camera binding of the warp build (the curve now
+  arrives as three floats in the settings and in the occupancy pass's own settings uniform).
+- *The bit fold.* `avboit_fold_pairs` is the OR of the even bits compacted and the odd bits compacted,
+  which is `decode32_morton2`'s job. Found on the way: for a 32-bit code that function's `.y` is *not*
+  the odd bits — the `<< 31` that separates them in the 16-bit variant (`<< 15`) cannot work in 32
+  bits — and the first reuse trusted it; the warp-build spec caught it as an occupied count of 70
+  against 66. The fold now goes through the correct `.x` half twice, once on `x >> 1`, and has a spec
+  against a bit-by-bit reference. `decode32_morton2` is used nowhere else in the tree; its `.y` is a
+  latent engine defect, noted for whoever reaches for it next.
+- *The sampler.* `AVBOIT_INTEGRAL_SAMPLER_DESCRIPTOR` duplicated `SAMPLER_LINEAR_UPSCALE` (linear,
+  clamped on every axis), which the draw already binds as `sLinear` for the split-sum LUT. The integral
+  samples through that; one binding fewer in the view group.
+- *The draw loop.* `material_draw` existed privately in both orchestrators. It is
+  `rasterize/native/material_draw_indirect.js` now, with the material bind-group layout it needs,
+  imported by both.
+
+**Convention.** 650 of the engine's ~700 chunk files hold exactly one function named after the file;
+mine held two to six. Five chunks became seventeen (`chunk_avboit_pack_counts`, `_unpack_counts`,
+`_transmittance_to_extinction`, `_extinction_to_transmittance`, `_extinction_to_counts`,
+`_counts_to_extinction`, `_overflows`, `_occupancy_range`, `_occupancy_word_mask`, `_dilate_word`,
+`_fold_pairs`, `_warp`, `_view_depth_to_virtual`, `_view_depth_to_physical`,
+`_integral_depth_coordinate`, `_sample_transmittance`, `_transmission_tint`), each with its spec; the
+hand-built warp and the curve's inverse the specs share live in `avboit_spec_support.js`, test-only.
+
+**Kept, on purpose.** `avboit_draw_fragment_body.js` shares one WGSL text between the IBL and Brick4
+draw pipelines where MBOIT duplicates its resolve body. No precedent either way in the tree; two
+45-line bodies drifting apart is the worse failure, and the two files stay concrete modules with no
+conditionals in them.
+
+**Also checked and found conforming:** the manual frame-graph passes match the MBOIT orchestrator's
+shape; `AVBOITSettings` on `Renderer.avboit` matches the other sub-object settings; the settings
+structs defined beside their shaders match `shader_read_out_bucket`; the bit packing uses WGSL's
+`insertBits`/`extractBits` directly, which is what the engine's `bitfield_*` chunks are thin proxies
+for; no `safe_*` math helper was reinvented — the one floor (`max(T, 1e-6)` before a log) has no
+counterpart in `shader/chunk/math/`.
+
+**Verified.** Every spec in `rasterize/` (the avboit directory's now-larger set, MBOIT's, the shared
+bucket code) and the type check.
+
+## 19. Side channels, and particles as the first one — 2026-09-04
+
+Alex: *"let's widen out AVBOIT so we can put particle render in there, that's where particles should
+go. Make sure the extension is clean. No need to bother with MBOIT, it's going to be deprecated...
+I don't think packing particle quads into meshlets is the way to go, so likely a side channel."*
+
+**The seam.** `AVBOITSideChannel.js` is a JSDoc contract, no base class: three methods, called by
+the orchestrator at the three points where the meshlet buckets have just contributed theirs —
+`avboit_occupancy` before the warp is built, `avboit_splat` before integrate, `avboit_draw` before
+resolve. Each takes the handles the orchestrator holds and returns the handles the next reader must
+take, which is the frame graph's own threading rule and nothing new. The orchestrator gained one
+parameter, `side_channels = []`, and one changed condition: it used to return early when no
+transparent material had meshlets, and now returns early only if there are also no channels.
+Integrate and resolve were not touched — they cannot tell a channel's fragment from a meshlet's,
+which is the property that makes this a seam rather than a special case.
+
+**The fourth accumulator.** An additive fragment covers nothing: it writes zero extinction and zero
+norm, so the resolve's renormalization — `(1 - T_total) / Σnorm`, which redistributes exactly the
+light the covering surfaces took from the scene — must not scale it. It cannot share the `color`
+accumulator for that reason. So `emission` joins as a fourth target, added to the resolve outside
+the normalization, holding light the draw already attenuated by the transmittance in front of it.
+The cost is honest and paid whether or not a channel is present: one more `rgba16float` at internal
+resolution, and every transparent mesh fragment writing `vec4(0)` to it. Buying it back would mean a
+three-target draw pipeline beside the four-target one — a variant, which the house rule and the
+plan's §5 both refuse — or a post-resolve additive pass with its own pipeline and bind group. One
+target is the cheaper of the three.
+
+**Shared, not copied.** The splat's voxel write (the two-slice linear split, the overflow mark) came
+out of the meshlet splat into `chunk_avboit_splat_slice`, so the particle splat writes the volume
+through the same code, not a second implementation of it. On the particle side the billboard vertex
+stage came out of the standalone renderer into `chunk_particle_billboard_vertex`, shared by three
+pipelines, and the emitter's world bounds sphere into `chunk_particle_emitter_world_sphere`, shared
+by the tick's frustum cull and the new occupancy.
+
+**What the review found.** Four things, all fixed here:
+
+- *A binding that lied.* The shared vertex chunk read its slot list from a binding named `sorted`.
+  The standalone path binds the depth-sorted list there; the AVBOIT passes bind the alive list,
+  because the volume makes order irrelevant and the sort does not run on that path. Renamed
+  `draw_list` in the chunk and all three pipelines: which list it is, is the caller's choice.
+- *Bounds with new teeth.* The occupancy is per emitter, from the bounds sphere — the field that
+  until now only fed the optional simulation culling and that an emitter not opting in could leave
+  at its default. A particle outside it still draws, but its extinction lands in whatever physical
+  slice the warp put nearest, so it occludes at slightly the wrong depth. Documented on the field
+  and in the particle design, because it is now a rendering input.
+- *One simulation per view.* `simulate` steps the system and hands out handles into the graph it
+  recorded into, so two views of one scene would step it twice. The renderer has one view per
+  `render` call, so it holds today; the fix when that changes is to separate the step from the
+  import. Documented on the method rather than built speculatively.
+- *A teardown that leaked.* `Renderer.destroy` did not destroy the particle systems it creates per
+  scene context. It does now.
+
+**Checked and found sound.** The volume and the accumulators are always created by the meshlet
+passes before a channel is asked, even at zero materials, so a particles-only frame has them; the
+splat's dummy attachment is cleared by the meshlet splat before the particle splat loads it; passes
+that write imported buffers are marked as side effects by `FramePassBuilder`, so the simulation
+still advances in a frame whose transparency pass is off; a fresh `FrameGraph` per frame makes the
+"simulated into this graph" assertion catch a stale handle set loudly; and the depth texture is
+bound as a read-only attachment and a sampled texture in the same pass, which WebGPU allows and the
+soft fade needs.
+
+**Under MBOIT.** Particles simulate and do not draw. MBOIT is the legacy path and gets no new
+sources; `Renderer.feature_particles_enabled` says so where a reader will hit it.
+
+**Verified.** Tiers 1–3: the WGSL validity spec (the three new pipelines parse, validate, and stay
+inside the eight-storage-buffer budget), the occupancy pass on the emulator against the depth
+curve's own arithmetic, the three graph passes on the software device (pass order, attachments,
+indirect draws, the read-only depth), the orchestrator's call order and the renderer's wiring, and
+the whole engine suite — 2321 files, 16119 tests — plus the type check. Not verified: any of it on a
+device. The Browser pane handed out no WebGPU adapter this session, so even the real Tint compile
+that ledger 18's review leaned on is still owed for these three shaders.
+
+## 20. Adversarial review of the side channel — 2026-09-04
+
+Alex ran the playground, said it works, and asked for an adversarial review. A picture that looks
+right is weak evidence for this pipeline: every defect below survives one, because each is either
+a second copy of something small, a disagreement between two passes about the same fragment, or a
+path the scene on screen does not take.
+
+**What the volume and the accumulators disagreed about.** The pipeline's whole contract is that the
+extinction the splat records is the coverage the draw weights its accumulators by
+(`avboit_draw_fragment_body`'s own header says so). Two fragments broke it:
+
+- *The soft fade.* The draw faded a particle's alpha against the scene depth; the splat had no depth
+  binding at all and recorded the unfaded coverage. A smoke card fading out where it meets the floor
+  drew nothing there and still wrote full extinction, so the floor was darkened through a card that
+  was invisible — the seam soft particles exist to remove, one layer down. The splat now samples the
+  same depth (one texel per voxel) and applies the same fade, through
+  `chunk_particle_scene_view_depth`, which the draw took its inline copy of the linearization from.
+  `avboit_splat` therefore takes `depth_texture` — the one contract change.
+- *Additive and the fog.* The draw composited volumetric in-scatter into every fragment and then put
+  additive ones in `emission`, which the resolve adds *outside* the normalization. The scene behind
+  already carries that in-scatter, and nothing subtracts it: a hundred overlapping sparks added a
+  hundred copies of the fog. An emitting fragment is now dimmed by the fog's transmittance and
+  carries none of its light; a covering one still re-adds it, weighted by the coverage it took,
+  because it hides the part of the scene it owes it to.
+
+**Two more in the same fragment.** `PREMULTIPLIED` with zero alpha is the engine's other spelling of
+additive — the billboard pipeline blends it that way — and the draw branched on the blend enum, so
+such a sprite was treated as covering, written to `color` with zero `norm`, and multiplied by a
+normalization of zero: it disappeared. The routing is on coverage now, which is what the splat
+already used, so the two agree by construction. And the coverage ceiling was applied to `norm` and
+`extinction` but not to `color`, unbounded above (a curve can drive alpha past 1) and unguarded
+below (a negative alpha made a negative extinction, and `exp(-sum)` then brightened the scene).
+
+All four are pinned on the emulator: the fragment's decision came out into
+`chunk_particle_avboit_contribution` as its own no-behaviour-change step, then nine tests, four of
+them red against the old code.
+
+**Teardown.** `destroy()` freed the buffers and left every emitter node holding a row of the table it
+had just freed. A renderer rebuilt after a device loss makes a fresh system whose membership sweep
+reads `row !== -1` as "already mine", takes the moved branch rather than the arrived one, and never
+registers the emitter: it stops emitting for good. It retires them now. The default 1×1 atlas was
+also unreachable — only its view was kept — and is held and freed.
+
+**The orchestrator can be run at tier 3 after all.** This file said it could not: it needs a view
+context over meshlet geometry no spec builds. That is true of a frame *with transparent meshes* —
+and the path side channels added is the other one. A scene with no transparent materials and one
+channel reaches for no geometry, so the whole orchestrator now runs on the mock, and the ordering
+contract and the handle threading are pinned from the outside instead of by reading the source for
+call order. The mock gained `indirect-first-instance` for it, on the argument its own header already
+makes for `subgroups`: it permits a field in an indirect draw the mock never reads, issuing a draw it
+never runs, and refusing it left the transparency orchestration untestable for a reason unrelated to
+what the tier asserts.
+
+**Found and left alone, on purpose:**
+
+- *The occupancy marks every emitter*, with no frustum test and no liveness test, where the meshlet
+  occupancy dispatches over the HZB-filtered collection. An idle or off-screen emitter still reserves
+  its depth run, and the warp then fits more occupied virtual slices into the same 128 physical ones.
+  It costs precision, never correctness. A frustum test is the obvious fix and belongs with a scene
+  that shows the cost.
+- *The occupancy sphere bounds particle centres*, not the quads' own depth extent, which for a
+  stretched or world-oriented particle reaches a size (or more) past the centre. Documented on
+  `ParticleEmitter.bounds_radius` rather than inflated by a guess.
+- *Particles have no motion vectors.* The transparency composite happens before TAA, so a fast spark
+  is reprojected with the background's motion and ghosts. Transparent meshes have had this property
+  since before AVBOIT; particles make it easier to see. The playground has a TAA switch.
+- *One system per scene context is never released*, mirroring `SceneManager`'s own map. A per-scene
+  release path is a design addition, not a fix.
+- *`simulate` steps once per view*, so two views of one scene would step it twice. Documented on the
+  method; the renderer has one view per `render` call today.
+
+**Verified.** The whole engine suite and the type check at budget. The playground page was loaded
+from the dev server again — import graph, WASM meshlet build, scene, camera controller under a
+synthetic drag, and every control handler including the two error paths added here. Still no adapter
+in the Browser pane, so still no picture and still no real Tint compile.
+
+## 21. What the device caught and the review did not — 2026-09-04
+
+Alex ran entry 20's work and got:
+
+```
+Binding entry textureView not set.
+ - While validating entries[6] against { binding: 6, ..., texture: {sampleType: UnfilterableFloat, ...} }
+ - While encoding [RenderPassEncoder "Particle AVBOIT Splat"].SetBindGroup(0, ...)
+```
+
+Entry 20 added `scene_depth` to the splat's bindings between the atlas and its sampler, and added
+the depth view to the *end* of the positional array the pass hands to `BindGroupDescriptor.from`.
+Everything after the insertion point slid along by one: binding 6 wanted a texture and got the
+sampler. Nothing on this side of the device could see it. The frame graph does not know what a
+binding means, the mock does not validate an entry against its layout, and both of entry 20's new
+tests looked for the depth view's *presence* in the group rather than its position.
+
+The fix is not the index. Both particle render passes now build their bindings by name, through
+`ShaderResourceSetDescriptor#generateBindings` — the path the standalone billboard pass already
+used, and the reason it never had this bug — so the order a shader declares its bindings in is the
+shader's own business and nothing here mirrors it. `constructRenderPass` sets the pipeline and every
+group from that, which also took the manual `setBindGroup` calls out.
+
+And the tier that missed it can see it now: `expect_bindings_match_layout` walks a recorded pass and
+asserts every entry is the *kind* — buffer, texture or sampler — its pipeline layout declares at that
+binding. It fails against the shipped code. That check is worth copying to any pass built by hand.
+
+**The lesson for this directory:** a positional bind-entry list is a latent version of this defect in
+every pass that has one, and it surfaces only on hardware, only when that pass first encodes. The
+meshlet passes here still build theirs positionally.