@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/rasterize/native/avboit/AVBOITSideChannel.js

@@ -1,6 +1,7 @@
 /**
  * A source of transparent fragments that is not a meshlet bucket, drawn through the AVBOIT pipeline
- * alongside the transparent meshes: particles today, anything quad- or point-shaped tomorrow.
+ * alongside the transparent meshes: the GPU particles (`GPUParticleSystem`), the dynamic meshes a
+ * system registers (`DynamicMeshAVBOITChannel` — the trails), anything quad- or point-shaped tomorrow.
  *
  * The orchestrator (`graph_rasterize_meshes_transparent_avboit`) collects three things from every
  * transparent surface in the frame, in this order, and a side channel is asked for each at the
@@ -24,6 +25,14 @@
  * the handles the next reader must take — the frame-graph threading rule, unchanged. A channel with
  * nothing to add returns what it was given.
  *
+ * A channel may also say, before the frame records, that it has nothing to add at all
+ * (`avboit_is_empty`). The orchestrator runs whenever it is handed a channel, even with no
+ * transparent material in the scene; a channel that is always registered but usually empty — a
+ * system's, from outside the renderer — would otherwise buy every frame the pipeline's fixed cost.
+ * The renderer leaves a channel that says it is empty out of that frame's list, and asks registered
+ * channels nothing at all with transparency off or under MBOIT, which takes no side channels. A
+ * channel without the method is always asked.
+ *
  * @typedef {object} AVBOITSideChannel
  * @property {(args: {
  *     graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph,
@@ -56,6 +65,9 @@
  *     accumulators: {color: number, norm: number, extinction: number, emission: number},
  * }) => {color: number, norm: number, extinction: number, emission: number}} avboit_draw draw the
  *     channel's fragments into the accumulators; returns their handles after the draw.
+ * @property {() => boolean} [avboit_is_empty] whether the channel would add nothing this frame;
+ *     asked before the orchestrator records, and a channel that answers `true` is not asked for
+ *     anything else in that frame.
  */
 
 export {};

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

@@ -640,3 +640,250 @@ binding. It fails against the shipped code. That check is worth copying to any p
 **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.
+
+## 22. Trails as the second side channel — 2026-09-24
+
+Alex asked whether `Trail3D` went through AVBOIT (it did not: `Trail3DSystem` drew its tubes with
+`GPUDynamicMeshRenderer` from an `AfterTransparency` extension, straight alpha over the resolved
+frame, depth-tested against the opaque scene only — so a trail behind a transparent card was drawn
+on top of it), then: *"implement this please. Keep within the parameters - AVBOIT for Trails only,
+and refactoring necessary to make it happen."* MBOIT is being deprecated and was out of scope.
+
+**The door.** Side channels could only come from inside the renderer: `#particle_side_channels`
+held the GPU particle system and nothing else, and `RENDER_EXTENSION_DESIGN.md` §9 names "extensions
+cannot participate in OIT" as the phase model's ceiling. `Renderer.add_transparency_channel` /
+`remove_transparency_channel` / `transparency_channel_count` open it, and `GraphicsEngine` holds
+channels across a restart exactly as it holds extensions. The frame's list (now `#side_channels`) is
+the particles, then every registered channel that does not say it is empty — `avboit_is_empty`, an
+optional fourth member of the contract — because the orchestrator runs whenever it is handed a
+channel, and one that is always registered would otherwise buy every frame the pipeline's fixed
+cost. Registering one channel twice is refused: it would draw everything twice.
+
+**The channel.** `DynamicMeshAVBOITChannel` meets the three contracts for a `DynamicMeshBatch`:
+
+- *Liveness is decided once, at occupancy*: a mesh is live when visible, with positive flat alpha,
+  and with a triangle one vertex of which has positive alpha. The splat and the draw take the same
+  list — and refuse a graph the occupancy was not recorded into — so the occupancy, the volume and
+  the accumulators agree about which meshes exist.
+- *Occupancy from CPU boxes.* The vertices are CPU data already, so a box per live mesh is taken
+  there (`dynamic_mesh_live_bounds`), carried to world space by the mesh's transform, uploaded as a
+  transient buffer and marked on the GPU through the particles' own chunks. **Per triangle, not
+  per vertex**: a trail's faint tail is a triangle whose far corners have aged to zero, and bounds
+  over the live vertices would stop a segment short; while an aged-out knot keeps its old position,
+  so bounds over every position would reserve depth for a stopped trail's whole history.
+- *The upload happens in the occupancy pass*, the channel's first to execute; the splat and the draw
+  read the buffers later in the same frame, behind the warp the occupancy feeds.
+- *Splat and draw* are the particle passes' shape with the dynamic-mesh vertex stage: coverage
+  through `avboit_coverage` in both, the draw routed through `avboit_premultiplied_contribution`,
+  fogged and weighted by the transmittance in front. Straight alpha with no coverage carries no
+  light, so the draw masks the emission target rather than blending zeros into it.
+- Group 0 of both pipelines is `DYNAMIC_MESH_RESOURCES`' own group — the same object — so a mesh's
+  bindings are the ones `GPUDynamicMeshResidency.create_bindings` already builds; the pass groups are
+  built by name (entry 21).
+
+**Shared, not copied.** Out of the particle channel into chunks, the particles switched onto them
+with their specs unchanged: `avboit_coverage`, `avboit_premultiplied_contribution` (everything
+`particle_avboit_contribution` did after its premultiply), `aabb3_view_depth_range` and
+`avboit_occupancy_mark`. Out of `GPUDynamicMeshRenderer`: `GPUDynamicMeshResidencyTable` (buffers,
+staging, the once-per-version upload) and `chunk_dynamic_mesh_vertex` (the vertex pull) — pinned by
+a new execute-level spec of the renderer written against the old code first, since there was none.
+Entry 21's layout-kind check is `recorded_binding_kind_mismatches` now, shared by both recorder
+specs. **Left alone on purpose:** the meshlet occupancy and the meshlet splat keep their own copies
+of the slice marking and the two-slice split — this change does not touch the core passes.
+
+**Trails.** `Trail3DSystem` registers its batch's channel with the facade instead of an extension;
+`TrailExtension` is gone (breaking, and its only use was internal). A trail is now occluded and
+tinted by transparent surfaces and particles in front of it, occludes them behind it, and picks up
+the volumetric fog at its depth — it was drawn unfogged over a fogged scene. Under MBOIT, or with
+transparency off, trails are not drawn, as particles are not. Fog of war still covers them: it runs
+at `AfterTransparency`, after the resolve they are now part of.
+
+**Verified.** Tiers 1–3: emulator specs for the four chunks, the dynamic-mesh occupancy pass and the
+live bounds; the WGSL validity tier for every new and changed shader; software-device specs for the
+channel's three passes (order, attachments, per-draw binding kinds, liveness, refusal, residency),
+for `GPUDynamicMeshRenderer`, for registration on the renderer and the facade, and **the whole
+orchestrator run with a real channel and no transparent materials**; `Trail3DSystem`'s specs; the
+type check at budget. Tier 4, on a Metal adapter in the Browser pane — which hands out an adapter
+again: every new and changed module compiles and every pipeline builds with no validation error.
+On the playground page here, a real `Trail3D` driven by `seed_trail_tube` / `advance_trail` /
+`trail_tube_write_geometry` and registered with `renderer.add_transparency_channel`:
+
+- laid in front of the card stack it is drawn over all four cards; laid behind it, it is hidden by
+  them at alpha 0.997 (the old path drew it on top), dimmed card by card at 0.3, and faint at 0.85;
+- behind the red pane with **tint transmitted light by base colour** on, it is filtered to the
+  desaturated tone the resolve predicts, `(0.19, 0.14, 0.14)`-ish against the pane's red, while its
+  head clear of the pane stays cyan;
+- under MBOIT it is absent, and back under AVBOIT it returns.
+
+On `../../playground/particle_ecs/` in `?debug` (frames driven by `__step`, the pane being hidden), a
+real `Trail3DSystem` added to the running `EntityManager` and a `Trail3D` entity circling the fire: the
+stretch behind the plume is dimmed and warmed by the smoke and flames in front of it, the stretch in
+front hides the smoke and embers behind it; removing the system takes its channel out of the live
+renderer and adding it back re-uploads from nothing. **Zero uncaptured device errors** across every
+frame of both sessions. The bonfire's sprites need `build/bundle-worker-image-decoder.js`, which the
+dev server does not build: `npx rollup -c rollup.config.js` first (the output is gitignored).
+
+## 23. Adversarial review of the trail channel — 2026-09-25
+
+Alex asked for an adversarial review, "especially on the blast radius". Three reviewers read
+`master...feature/trail-avboit` independently — blast radius, GPU correctness, lifecycle and API —
+and every finding below was checked against the code before it was acted on. None was critical or
+high. Both reviewers who compared the shared chunks with master found them textually equivalent, the
+dynamic-mesh upload moved without change, and the meshlet passes untouched; the GPU reviewer
+confirmed the splat and the draw agree on coverage, depth and fragments, that emission is
+unreachable from straight alpha, and that the fog is not counted twice.
+
+**Fixed.**
+
+- *Buffers from the old device.* An `Engine` with an external `EntityManager` stops `GraphicsEngine`
+  without shutting its systems down (`Engine.stop`), and a restart then replays the channel into a
+  renderer on a new device while its residency holds buffers made on the old one — written with
+  `queue.writeBuffer` and bound into bind groups on the new device, a validation error that loses the
+  frame's commands. Not new: `GPUDynamicMeshRenderer`'s map did the same for path display and debug
+  draw, and `TrailExtension` was replayed the same way. But entry 22 advertised channels as held across
+  a restart, so `GPUDynamicMeshResidencyTable` now drops everything when the device changes — the
+  pattern `GPUParticleEmitterSystem` already has for its atlas — which fixes all three drawers.
+- *The last frame kept alive.* The channel held `#frame_graph` — the whole frame graph, every pass
+  closure in it, the imported canvas — and its live meshes until it was next asked, which for a
+  channel whose last trail had faded, or whose renderer had been replaced, is never; `Renderer.js`
+  calls exactly that retention a bug in its profiler path. The decision is now a per-frame record,
+  dropped when the draw is recorded; the passes carry their own references to the list and the boxes.
+  Each frame's list and boxes being its own also closes the aliasing the GPU reviewer called fragile
+  (record A, record B, execute A drew B's meshes into A): a spec now records two frames before
+  executing either, and fails against the old code.
+- *Consulted when nothing would draw it.* `avboit_is_empty` ran every frame under MBOIT and with
+  transparency off; registered channels are now consulted only when the pipeline that takes them will
+  run.
+- *An assert that shipped builds strip.* Registering a channel twice was refused by `assert` — gone
+  in a shipped build, where the channel would then be drawn twice — and the facade recorded a
+  registration the renderer had refused. Both are idempotent now; a repeat is a no-op.
+- *The optional method unchecked.* A non-function `avboit_is_empty` passed registration and threw in
+  the middle of every frame; it is refused at the door.
+- *`TrailExtension` removed outright.* meep ships ES modules, and an import that stops linking stops
+  the application loading, not just its trails — the reason `Trail3DSystem3` is kept. It is a
+  deprecated extension again, recording nothing and warning once.
+- *No frustum test in the occupancy.* A live trail behind the camera or off to the side reserved its
+  whole depth run, and the warp fitted the on-screen surfaces into what was left. The dynamic-mesh
+  occupancy now tests each box against `camera.frustum` first. On the device, the real camera's planes
+  keep a visible trail's box and cull one behind the camera. The particles' occupancy still has no
+  such test (entry 20's open item); this change does not touch it.
+- *Nothing pinned "the fog covers trails".* It used to be a declaration in
+  `after_transparency_order.spec.js`; it is construction now — the transparency call site precedes the
+  `AfterTransparency` phase — and a source pin says so.
+
+**Disclosed, not changed** — each is in the CHANGELOG entry too:
+
+- *Draw order at `AfterTransparency`.* Trails were the last content extension there; they are
+  resolved before that phase now, so path display, the selection highlight and the deprecated CPU
+  `ParticleEmitterSystem` draw over a trail whatever its depth, where they drew under it. Neither
+  order was depth-correct; the GPU particles are the ones that now sort against trails.
+- *The fixed cost.* A frame with a live trail runs the transparency pipeline even with nothing else
+  transparent — occupancy, warp, integration, the accumulator clears, the resolve — where it had one
+  blended pass. Of the order of entry 17's 0.3 ms at 720p on light content.
+- *Shared precision.* A trail spanning a deep range marks a long run and the warp halves its virtual
+  resolution to fit: the GPU reviewer's example, a box spanning 10–60 m at near 0.1 / far 200, takes
+  the warp from 4096 to 256 virtual slices, about 1.6 cm to 25 cm at 10 m. Emitter boxes do the same;
+  it is how the adaptive warp shares its 128 slices. Off-screen trails no longer take part.
+- *Thin trails and the 1/8-resolution splat.* A tube narrower than about one voxel reaches the volume
+  only in the columns whose low-resolution pixel centres it covers. The GPU reviewer's numbers: a 0.1 m
+  trail at 20 m, 1080p, 60° is 0.58 voxel wide, and in a missed column a smoke card behind an α 0.8
+  trail comes out 3.5× too strong through it, crawling in 8-pixel blocks as the trail moves. Plan §9's
+  sub-pixel risk, which meshlets and small particles share. The suggested mitigation — widen the
+  splat's triangles by half a voxel — trades the misses for halos wherever the widened footprint falls
+  between two other layers, and is left for a decision rather than taken.
+- *Renderer-wide channels.* A thumbnail rendered through the same renderer includes live trails that
+  fall in its view, as it did when they were an extension — and now brings the pipeline with them on
+  those frames. Particles are per scene; channels, like extensions, are not.
+- *Work done twice.* The emptiness query and the gather both walk the first live mesh's triangles, and
+  each live mesh's group-0 bindings — a transient uniform — are built once for the splat and once for
+  the draw. Small at trail counts; noted, not shaved.
+
+**Verified.** Before the fixes, the whole engine suite: the only failures were
+`VGeoResidency.spec.js`, failing identically on master, and a `PromiseWatcher` timeout under load that
+passes alone. After them, the suites the change reaches (217 files, 2386 tests) and the type check at
+budget. On the device: every new and changed module compiles and its pipeline builds; on the bonfire
+page, the trail through the plume again, with every fix in, and no uncaptured device errors.
+
+## 24. Thin trails: a coverage-weighted splat — 2026-09-25
+
+Alex said *"continue please"*, then *"Try again"*; the open item was entry 23's thin trail, disclosed and
+left for a decision. It is taken here, for the trail channel only — the meshlet and particle splats are
+unchanged.
+
+**Confirmed on the device first.** On the playground page, a dimmed trail at α 0.8, 0.04 wide (about
+3.7 pixels, 0.46 of a voxel), laid across the red card at eight offsets an eighth of a voxel apart —
+one voxel's period — and read at the trail's centre. TAA off:
+
+| offset | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+|---|---|---|---|---|---|---|---|---|
+| before | 107,144 | 107,144 | 77,166 | 76,167 | 73,168 | 72,169 | 111,140 | 111,140 |
+| after | 95,155 | 93,156 | 90,158 | 88,160 | 85,162 | 85,162 | 95,154 | 100,151 |
+
+(red, green; the card alone is 147,77; the same trail 0.3 wide, which covers whole voxels, is 72,169.)
+Before, the trail either crossed a voxel centre and occluded the card fully or missed it and did not
+occlude it at all: two colours and a jump of 39 between neighbouring offsets. With TAA on it was the
+same split (70–111, a jump of 38), so the temporal filter does not hide it: it moves as the trail does.
+
+**The options.**
+
+- *Widen the splat's triangles by half a voxel* (entry 23's suggestion): every voxel the trail touches
+  gets its full extinction — halos wherever the widened footprint falls between two other layers.
+- *Multisample and write the full extinction if any sample is covered*: the same halo, and worse — the
+  triangles of one ribbon sharing a voxel would each add a whole layer.
+- *Multisample and weight by the covered share* — taken. Four samples, the only count above one WebGPU
+  guarantees; the fragment runs where any is covered and scales its extinction by
+  `countOneBits(sample_mask) / 4`. The triangles of one mesh cover disjoint samples, so their shares in
+  a voxel add to at most one layer, and a fully covered voxel is written exactly as before. The voxel
+  gets the trail's extinction averaged over its footprint, which is what a volume that coarse can hold.
+- *More samples* — a raster at twice the volume's resolution, sixteen per voxel. A model of the lookup
+  (a 0.46-voxel band at α 0.8, transmittance behind the trail's centre over every position) says it is
+  not worth four times the fragments: one sample 0.20–1.00, four 0.45–0.78, sixteen 0.45–0.73, and an
+  exact area average 0.48–0.69. What is left at four is mostly the floor: a band thinner than a voxel,
+  box-averaged into voxels and read back through the draw's bilinear lookup, still sees more of itself
+  where it sits on a voxel centre than between two.
+
+**What changed.** `shader_dynamic_mesh_avboit_splat` has `multisample: { count: 4 }` and the weight;
+`graph_dynamic_mesh_avboit_splat` makes its own 4-sample `r8unorm` target at the volume's resolution
+(never written, cleared and discarded — about 130 KB at 1080p, transient) and hands the volume's
+single-sampled one back untouched, since a multisampled pipeline cannot draw into it; the channel passes
+it the `voxel_resolution` the orchestrator already offered. The shared vertex chunk interpolates at the
+**centroid**: a thin triangle covering samples but not the pixel centre would otherwise have its depth
+and alpha extrapolated past its edge, which on a ribbon seen nearly edge-on moves the extinction off the
+ribbon. The draw is single-sampled, where a fragment exists only if the centre is covered and the
+centroid is the centre, so its output does not change.
+
+**After, on the device.** The table's second row, and with TAA on 82–102 with a largest jump of 19. On a
+curved thin trail — the case that beaded — the per-column red at the trail's centre over 225 columns:
+
+| | stdev | range | mean | neighbours ≥ 10 apart |
+|---|---|---|---|---|
+| TAA off, before → after | 13.7 → 4.8 | 67–109 → 78–101 | 85.8 → 85.5 | 6 → 0 |
+| TAA on, before → after | 12.7 → 5.0 | 58–108 → 71–98 | 79.8 → 81.5 | 20 → 5 |
+
+Two and a half to three times steadier, and the same on average, as an area average of point samples
+should be. The wide trail reads 69,170 against 72,169 before.
+
+**What remains, and what it costs.**
+
+- *The average's own bias.* A trail a fraction of a voxel wide occludes what is behind it by about that
+  fraction of its extinction, steadily. The trail itself still draws at full resolution and full
+  opacity; only its occlusion of what is behind it is diluted. That is the resolution the volume has.
+- *Faint trails can round away.* The volume counts 255 steps per `ln 256` of extinction, so a voxel a
+  trail below about α 0.04 only grazes gets nothing, where before a centre it happened to cross got a
+  step. Occlusion of about 2 %.
+- *More fragments.* Every voxel a thin trail crosses runs the fragment, not only those whose centres
+  it covers — two to three times as many along a thin trail, one more row along each edge of a wide
+  one, and never more than four per voxel per layer.
+
+The emulator compiles WGSL to JavaScript and takes names as they are, so a fragment parameter named
+`in` — a JavaScript keyword — failed to load; the splat's is `fragment`.
+
+**Verified.** A new emulator spec runs the splat's fragment with each sample mask and checks the share it
+writes, that four disjoint quarters add to one layer, and that a faded fragment writes nothing; with the
+weight removed it fails five of its eight tests. The channel's recorder spec checks the target is the
+pass's own, has the pipeline's sample count, is cleared and discarded, and that the volume's target
+comes back untouched; with the old recorder it fails exactly those two. Every spec the change can
+reach — the dynamic-mesh directory, the orchestrator run with a real channel, `Trail3DSystem`: 11 files,
+93 tests — passes, and the type check is at budget. On the Metal adapter, `@builtin(sample_mask)` and
+`@interpolate(perspective, centroid)` compile and the multisampled pipeline builds; no uncaptured device
+errors, including 240 frames of a live trail on a moving path, fading in and out.

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

@@ -1,6 +1,6 @@
 # Adaptive voxel-based order-independent transparency (AVBOIT) — implementation plan
 
-**Status:** implemented, default mode, device tier in progress — revision 5
+**Status:** implemented, default mode, device tier in progress — revision 7
 **Date:** 2026-09-03
 **Author:** Alex Goldring / Company Named Limited, with Claude
 **Scope:** `src/shade/renderer/rasterize/native/avboit/` (new), `src/shade/renderer/ShadeTransparencyMode.js`
@@ -33,6 +33,20 @@ Games, SIGGRAPH 2025 (talk deck, 60 pages, `AVBOIT_SIG2025_MDROBOT-final.pdf`)
 > a fourth accumulator, `emission`, for additive fragments: they cover nothing, so the resolve's
 > renormalization must not scale them (§3.8, §3.9). Integrate and resolve are otherwise untouched, and MBOIT,
 > now the legacy path, gets no channel of its own.
+>
+> **Revision 6** (ledger entry 22) adds the second side channel and the door to it. `DynamicMeshAVBOITChannel`
+> draws a `DynamicMeshBatch` — trails, first and only — through the three contracts, and a channel can now come
+> from outside the renderer: `Renderer.add_transparency_channel`, held across restarts by
+> `GraphicsEngine.add_transparency_channel` the way extensions are. A channel may say it is empty
+> (`avboit_is_empty`) and is then left out of the frame, so one that is always registered does not make the
+> orchestrator run on frames with nothing transparent. What the particle channel did privately and a second
+> channel needs — the coverage clamp, the covering/emitting routing, a world box's depth interval and the slice
+> marking — are shared chunks now. The meshlet passes are untouched.
+>
+> **Revision 7** (ledger entry 24): the dynamic meshes' splat is rasterized with four samples and weights each
+> fragment's extinction by the share of the voxel its triangle covers, so a trail thinner than a voxel
+> occludes steadily instead of in the columns whose centres it happens to cross (§9). The meshlet and particle
+> splats are unchanged.
 
 ---
 
@@ -146,7 +160,8 @@ The front and double-sided variants of steps 4 and 6 exist for the same reason a
 `cullMode`, so a different pipeline, threaded through `rp_rewrite_for_primitive_state`.
 
 *Revision 5:* steps 2, 4 and 6 also take contributions from **side channels** — transparent sources that are
-not meshlet buckets, the GPU particles being the first. `graph_rasterize_meshes_transparent_avboit` takes
+not meshlet buckets, the GPU particles being the first (*revision 6:* and the dynamic meshes, for trails, the
+second). `graph_rasterize_meshes_transparent_avboit` takes
 `side_channels`, an array of `AVBOITSideChannel`, and asks each for its occupancy after the meshlet buckets'
 (step 2), its splat after theirs (step 4) and its draw after theirs (step 6), threading the handles the way
 every pass here does. Steps 5 and 7 are unchanged and cannot tell the two apart. Step 6 writes a fourth
@@ -522,6 +537,9 @@ Each step lands with its tests green before the next starts; the ledger records
 - **Sub-pixel geometry at 1/8 resolution** never reaches the extinction volume, so it does not occlude anything
   behind it (it still draws). The deck accepts this for VFX; thin glass edges may show it. The downscale is a
   constant.
+  *Revision 7:* trails are the case where it showed — a moving thin trail occluded in some columns and not
+  others — and the dynamic-mesh splat alone is multisampled and coverage-weighted now (ledger entry 24).
+  Such a trail reaches the volume everywhere, diluted to the share of each voxel it covers.
 - **Meshlet bounds as occupancy** are conservative in depth only as far as the bounds are right; skinned meshes
   with stale bounds would splat outside their run and clamp to its edge. Watch for it on the page.
 - **8-bit integral** — banding in long smooth gradients; the swap to `rgba16float` is one constant.

package/src/shade/renderer/rasterize/native/avboit/avboit_draw_fragment_body.js

@@ -87,7 +87,7 @@ fn main(
     let f_transmission = material_info.transmission_factor;
     if (f_transmission > 0.0) {
         let t_diffuse = textureSample(texture_diffuse, texture_diffuse_sampler, vert_adjusted.uv);
-        let base_color = (t_diffuse.rgb / max(t_diffuse.a, 1e-7)) * vert.color;
+        let base_color = (t_diffuse.rgb / max(t_diffuse.a, 1e-7)) * vert.color * material_info.albedo_color.rgb;
         tint = avboit_transmission_tint(base_color, f_transmission * f32(warp.tint_from_base_color));
     }
 

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_coverage.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The coverage a side channel's fragment of alpha `alpha` takes: clamped to `[0, OIT_COVERAGE_MAX]`.
+ *
+ * Above the ceiling, full opacity would be zero transmittance, whose logarithm breaks the
+ * accumulators; below zero it would be a negative extinction, and the resolve's `exp(-sum)` would
+ * brighten what is behind the fragment instead of dimming it.
+ *
+ * One definition for both halves of a channel, because the pipeline's whole contract is that the
+ * extinction the splat records is the coverage the draw weights its accumulators by — the splat
+ * calls this directly and the draw through `avboit_premultiplied_contribution`, so the two cannot
+ * drift apart.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_coverage: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_avboit_coverage.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_avboit_coverage.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_coverage.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,oCAFU,SAAS,CASjB;0BAxBwB,uCAAuC"}

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_coverage.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { OIT_COVERAGE_MAX } from "../oit/OIT_CONSTANTS.js";
+
+/**
+ * The coverage a side channel's fragment of alpha `alpha` takes: clamped to `[0, OIT_COVERAGE_MAX]`.
+ *
+ * Above the ceiling, full opacity would be zero transmittance, whose logarithm breaks the
+ * accumulators; below zero it would be a negative extinction, and the resolve's `exp(-sum)` would
+ * brighten what is behind the fragment instead of dimming it.
+ *
+ * One definition for both halves of a channel, because the pipeline's whole contract is that the
+ * extinction the splat records is the coverage the draw weights its accumulators by — the splat
+ * calls this directly and the draw through `avboit_premultiplied_contribution`, so the two cannot
+ * drift apart.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_coverage = CodeChunk.from(
+    //language=WGSL
+    `
+fn avboit_coverage(alpha: f32) -> f32 {
+    return clamp(alpha, 0.0, ${OIT_COVERAGE_MAX});
+}
+    `
+);

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_fold_pairs.d.ts

@@ -2,11 +2,10 @@
  * Halve the slice resolution of one occupancy word: bit `j` of the 16-bit result is bit `2j` OR bit
  * `2j + 1` of the input — the even bits compacted, OR the odd bits compacted.
  *
- * Both compactions come from the BVH builder's 2D Morton decode. Only its `.x` is used: for a 32-bit
- * code that function's `.x` is the even bits compacted to 16, while its `.y` is not the odd bits (the
- * `<< 31` that separates the odd bits works in the 16-bit variant, where the shift is 15, and cannot
- * in 32 bits). Shifting the word right by one puts the odd bits on even positions, so the same `.x`
- * serves both halves.
+ * Both compactions come from the BVH builder's 2D Morton decode, which is exactly this pair: `.x` is
+ * the even bits compacted to 16 and `.y` is the odd ones. This used to read `.x` twice, off the word
+ * and off the word shifted right by one, because `.y` did not work — that decode's `<< 31` was
+ * transcribed from the 16-bit variant, where the shift is 15 and has somewhere to go.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_fold_pairs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_avboit_fold_pairs.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_fold_pairs.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,sCAFU,SAAS,CAWjB;0BAvBwB,uCAAuC"}
+{"version":3,"file":"chunk_avboit_fold_pairs.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_fold_pairs.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,sCAFU,SAAS,CAajB;0BAxBwB,uCAAuC"}

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_fold_pairs.js

@@ -5,11 +5,10 @@ import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
  * Halve the slice resolution of one occupancy word: bit `j` of the 16-bit result is bit `2j` OR bit
  * `2j + 1` of the input — the even bits compacted, OR the odd bits compacted.
  *
- * Both compactions come from the BVH builder's 2D Morton decode. Only its `.x` is used: for a 32-bit
- * code that function's `.x` is the even bits compacted to 16, while its `.y` is not the odd bits (the
- * `<< 31` that separates the odd bits works in the 16-bit variant, where the shift is 15, and cannot
- * in 32 bits). Shifting the word right by one puts the odd bits on even positions, so the same `.x`
- * serves both halves.
+ * Both compactions come from the BVH builder's 2D Morton decode, which is exactly this pair: `.x` is
+ * the even bits compacted to 16 and `.y` is the odd ones. This used to read `.x` twice, off the word
+ * and off the word shifted right by one, because `.y` did not work — that decode's `<< 31` was
+ * transcribed from the 16-bit variant, where the shift is 15 and has somewhere to go.
  *
  * @type {CodeChunk}
  */
@@ -17,7 +16,9 @@ export const chunk_avboit_fold_pairs = CodeChunk.from(
     //language=WGSL
     `
 fn avboit_fold_pairs(x: u32) -> u32 {
-    return decode32_morton2(x).x | decode32_morton2(x >> 1u).x;
+    let pair = decode32_morton2(x);
+
+    return pair.x | pair.y;
 }
     `, [
         chunk_decode32_morton2,

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_occupancy_mark.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mark the finest-level virtual slices a view-depth interval spans into the occupancy bits (plan
+ * §3.3): nothing when the interval is entirely in front of the near plane, otherwise the interval
+ * clamped at the near plane, through the depth curve (`cluster_depth_to_z_slice`, limited to
+ * `AVBOIT_VIRTUAL_SLICES_MAX`), dilated one slice each side (`avboit_occupancy_range`), and OR-ed in
+ * a word at a time.
+ *
+ * The enclosing shader binds `occupancy` (`array<atomic<u32>, AVBOIT_OCCUPANCY_WORDS>`, read-write)
+ * under that name — the same arrangement as `avboit_splat_slice` and its volume. This is the write
+ * shared by the side channels' occupancy passes, which start from a world-space box
+ * (`aabb3_view_depth_range`) rather than from a meshlet's bounds.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_occupancy_mark: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_avboit_occupancy_mark.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_occupancy_mark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_avboit_occupancy_mark.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_occupancy_mark.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,0CAFU,SAAS,CAgCjB;0BAjDwB,uCAAuC"}

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_occupancy_mark.js

@@ -0,0 +1,51 @@
+import { chunk_cluster_depth_to_z_slice } from "../../../light/cluster/chunk_cluster_depth_to_z_slice.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { AVBOIT_VIRTUAL_SLICES_MAX } from "./AVBOIT_CONSTANTS.js";
+import { chunk_avboit_occupancy_range } from "./chunk_avboit_occupancy_range.js";
+import { chunk_avboit_occupancy_word_mask } from "./chunk_avboit_occupancy_word_mask.js";
+
+/**
+ * Mark the finest-level virtual slices a view-depth interval spans into the occupancy bits (plan
+ * §3.3): nothing when the interval is entirely in front of the near plane, otherwise the interval
+ * clamped at the near plane, through the depth curve (`cluster_depth_to_z_slice`, limited to
+ * `AVBOIT_VIRTUAL_SLICES_MAX`), dilated one slice each side (`avboit_occupancy_range`), and OR-ed in
+ * a word at a time.
+ *
+ * The enclosing shader binds `occupancy` (`array<atomic<u32>, AVBOIT_OCCUPANCY_WORDS>`, read-write)
+ * under that name — the same arrangement as `avboit_splat_slice` and its volume. This is the write
+ * shared by the side channels' occupancy passes, which start from a world-space box
+ * (`aabb3_view_depth_range`) rather than from a meshlet's bounds.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_occupancy_mark = CodeChunk.from(
+    //language=WGSL
+    `
+fn avboit_occupancy_mark(depth_near: f32, depth_far: f32, clip_near: f32, cluster_parameters: vec3<f32>) {
+    if (depth_far < clip_near) {
+        // entirely in front of the near plane
+        return;
+    }
+
+    let limit = ${AVBOIT_VIRTUAL_SLICES_MAX}.0;
+    let slice_near = cluster_depth_to_z_slice(max(depth_near, clip_near), cluster_parameters, limit);
+    let slice_far = cluster_depth_to_z_slice(depth_far, cluster_parameters, limit);
+
+    let range = avboit_occupancy_range(slice_near, slice_far);
+
+    let word_first = u32(range.x) >> 5u;
+    let word_last = u32(range.y) >> 5u;
+
+    for (var word = word_first; word <= word_last; word++) {
+        let mask = avboit_occupancy_word_mask(word, range.x, range.y);
+        if (mask != 0u) {
+            atomicOr(&occupancy[word], mask);
+        }
+    }
+}
+    `, [
+        chunk_cluster_depth_to_z_slice,
+        chunk_avboit_occupancy_range,
+        chunk_avboit_occupancy_word_mask,
+    ]
+);

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_premultiplied_contribution.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What one side-channel fragment of premultiplied colour contributes to AVBOIT's four accumulators
+ * (plan §3.8, §3.9): which accumulator it belongs in, and with what weight.
+ *
+ * The reference is the mesh draw (`avboit_draw_fragment_body`) and the resolve that reads what both
+ * write: `out = scene × T_total + Σcolor × (1 - T_total) / Σnorm + Σemission`. A **covering**
+ * fragment is normalized, so its three writes have to agree with each other; an **emitting** one is
+ * added as it stands, so anything it writes has to be light nothing else is already accounting for.
+ *
+ * The inputs are the fragment's colour, already premultiplied — `.a` is the coverage it asks for and
+ * `.rgb` the light it carries; the transmittance the voxel volume leaves in front of it, per channel;
+ * and `sample_volumetrics` at the fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * Lifted out of the particle draw (`particle_avboit_contribution`, which is now the particles'
+ * premultiply in front of this) so that every side channel routes its fragments the same way:
+ * ledger entry 20's fixes — the fog on emitting fragments, the ceiling on the colour as well as the
+ * coverage, the floor under a negative alpha — are this function's, not one channel's.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_premultiplied_contribution: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_avboit_premultiplied_contribution.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_premultiplied_contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_avboit_premultiplied_contribution.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_premultiplied_contribution.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sDAFU,SAAS,CAuDjB;0BA5EwB,uCAAuC"}

package/src/shade/renderer/rasterize/native/avboit/chunk_avboit_premultiplied_contribution.js

@@ -0,0 +1,77 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_avboit_coverage } from "./chunk_avboit_coverage.js";
+
+/**
+ * What one side-channel fragment of premultiplied colour contributes to AVBOIT's four accumulators
+ * (plan §3.8, §3.9): which accumulator it belongs in, and with what weight.
+ *
+ * The reference is the mesh draw (`avboit_draw_fragment_body`) and the resolve that reads what both
+ * write: `out = scene × T_total + Σcolor × (1 - T_total) / Σnorm + Σemission`. A **covering**
+ * fragment is normalized, so its three writes have to agree with each other; an **emitting** one is
+ * added as it stands, so anything it writes has to be light nothing else is already accounting for.
+ *
+ * The inputs are the fragment's colour, already premultiplied — `.a` is the coverage it asks for and
+ * `.rgb` the light it carries; the transmittance the voxel volume leaves in front of it, per channel;
+ * and `sample_volumetrics` at the fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * Lifted out of the particle draw (`particle_avboit_contribution`, which is now the particles'
+ * premultiply in front of this) so that every side channel routes its fragments the same way:
+ * ledger entry 20's fixes — the fog on emitting fragments, the ceiling on the colour as well as the
+ * coverage, the floor under a negative alpha — are this function's, not one channel's.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_premultiplied_contribution = CodeChunk.from(
+    //language=WGSL
+    `
+struct AVBOITContribution {
+    color : vec4<f32>,
+    norm : vec4<f32>,
+    extinction : vec4<f32>,
+    emission : vec4<f32>,
+}
+
+fn avboit_premultiplied_contribution(
+    premultiplied : vec4<f32>,
+    transmittance : vec3<f32>,
+    fog : vec4<f32>
+) -> AVBOITContribution {
+    var out : AVBOITContribution;
+
+    let coverage = avboit_coverage(premultiplied.a);
+
+    if (coverage <= 0.0) {
+        /*
+         Covers nothing: an additive emitter, or a premultiplied sprite with no alpha, which the
+         blended billboard pipeline blends the same way. It is dimmed by the fog in front of it,
+         but it does not carry the fog's own in-scatter: the scene it draws over already has that
+         composited in, and the resolve adds emission outside the normalization that would otherwise
+         take the duplicate away. Carrying it would add one copy of the fog per fragment.
+        */
+        out.color = vec4<f32>(0.0);
+        out.norm = vec4<f32>(0.0);
+        out.extinction = vec4<f32>(0.0);
+        out.emission = vec4<f32>(max(premultiplied.rgb * fog.w * transmittance, vec3<f32>(0.0)), 0.0);
+        return out;
+    }
+
+    // the ceiling is on the pair, so the colour is rescaled with the coverage it is weighted by
+    let scale = coverage / premultiplied.a;
+
+    // this one does hide part of the scene, so it owes that part its in-scatter back — and the
+    // resolve's normalization is what keeps the sum to one copy however many fragments there are
+    let color = premultiplied.rgb * scale * fog.w + fog.xyz * coverage;
+
+    let self_transmittance = vec3<f32>(1.0 - coverage);
+
+    out.color = vec4<f32>(color * transmittance, 0.0);
+    out.norm = vec4<f32>((1.0 - self_transmittance) * transmittance, 0.0);
+    out.extinction = vec4<f32>(-log(self_transmittance), 0.0);
+    out.emission = vec4<f32>(0.0);
+
+    return out;
+}
+    `, [
+        chunk_avboit_coverage,
+    ]
+);