@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -20,8 +20,9 @@ export const AVBOIT_PHYSICAL_SLICES: number;
  * this value: 1.6 cm at 10 m, 3.2 cm at 20 m, 8 cm at 50 m. The draw's two-slice bias means two
  * surfaces need more than two slices between them, so 5 cm of separation resolves out to roughly
  * 15 m. At 1024 the same numbers were four times coarser and 5 cm at 10 m already blended (ledger
- * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and a longer
- * single-lane loop in the warp build — none of which registers.
+ * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and 4,097 LUT
+ * entries for the warp build to write: 136 µs while the build was a single invocation (ledger entry 27),
+ * 3 µs as a workgroup (entry 28).
  * @type {number}
  */
 export const AVBOIT_VIRTUAL_SLICES_MAX: number;
@@ -55,10 +56,13 @@ export const AVBOIT_EXTINCTION_MAX: number;
 /**
  * Transmittance below which a fragment is fully occluded as far as the volume can tell: the integral
  * saturates at `1.0`, which is `exp(-AVBOIT_EXTINCTION_MAX) = 1/256`. The draw discards a fragment
- * whose sampled transmittance is at or below this in every channel before shading it. What that
- * costs in correctness is bounded: the fragment's own extinction no longer joins the total, so the
- * background is weighted by at most `1/256` instead of something smaller — below what the 8-bit
- * volume resolves anyway.
+ * whose sampled transmittance is at or below this in every channel before shading it. Where the
+ * 1/8-resolution volume is right at the full-resolution pixel, what that costs is bounded: the
+ * fragment's own extinction no longer joins the total, so the background is weighted by at most
+ * `1/256` instead of something smaller — below what the 8-bit volume resolves anyway. Where it is not
+ * — behind a gap narrower than a voxel in a near-opaque layer — the volume calls the pixel extinct and
+ * the surface seen through the gap is discarded, where the resolve's normalization would have drawn
+ * it. The deck's zero-transmittance cull shares the limit (ledger entry 26).
  * @type {number}
  */
 export const AVBOIT_EXTINCT_TRANSMITTANCE: number;
@@ -82,7 +86,9 @@ export const AVBOIT_FIELD_MASK: number;
  * How far toward the camera, in virtual slices, the draw pass samples the integral so that a surface
  * does not occlude itself through its own linear splat. With the exclusive-prefix storage convention
  * the analytic minimum is 1.5; the deck uses 2. Events closer together than this do not occlude each
- * other and degrade to weighted blending.
+ * other and degrade to weighted blending. A surface tilted away from the camera adds its footprint on
+ * top (`avboit_footprint_bias`): the base bias is for a surface splatted at its own depth, and the
+ * draw also reads the neighbouring voxel columns, where a tilted one was splatted nearer.
  * @type {number}
  */
 export const AVBOIT_SAMPLE_BIAS_SLICES: number;

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

@@ -1 +1 @@
-{"version":3,"file":"AVBOIT_CONSTANTS.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,qCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,qCAFU,MAAM,CAEqD;AAErE;;;;GAIG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;;;GAMG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;;;GAMG;AACH,oCAFU,MAAM,CAEmC;AAEnD;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,sCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;GAGG;AACH,gCAFU,MAAM,CAE8C;AAE9D;;;;;;GAMG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;GAIG;AACH,sDAAmD;AAEnD;;;GAGG;AACH,8CAFU,MAAM,CAEiC"}
+{"version":3,"file":"AVBOIT_CONSTANTS.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,qCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,qCAFU,MAAM,CAEqD;AAErE;;;;GAIG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;;;GAMG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;;;GAMG;AACH,oCAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;GAWG;AACH,2CAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,sCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;GAGG;AACH,gCAFU,MAAM,CAE8C;AAE9D;;;;;;;;GAQG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;GAIG;AACH,sDAAmD;AAEnD;;;GAGG;AACH,8CAFU,MAAM,CAEiC"}

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

@@ -22,8 +22,9 @@ export const AVBOIT_PHYSICAL_SLICES = 128;
  * this value: 1.6 cm at 10 m, 3.2 cm at 20 m, 8 cm at 50 m. The draw's two-slice bias means two
  * surfaces need more than two slices between them, so 5 cm of separation resolves out to roughly
  * 15 m. At 1024 the same numbers were four times coarser and 5 cm at 10 m already blended (ledger
- * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and a longer
- * single-lane loop in the warp build — none of which registers.
+ * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and 4,097 LUT
+ * entries for the warp build to write: 136 µs while the build was a single invocation (ledger entry 27),
+ * 3 µs as a workgroup (entry 28).
  * @type {number}
  */
 export const AVBOIT_VIRTUAL_SLICES_MAX = 4096;
@@ -62,10 +63,13 @@ export const AVBOIT_EXTINCTION_MAX = Math.log(256);
 /**
  * Transmittance below which a fragment is fully occluded as far as the volume can tell: the integral
  * saturates at `1.0`, which is `exp(-AVBOIT_EXTINCTION_MAX) = 1/256`. The draw discards a fragment
- * whose sampled transmittance is at or below this in every channel before shading it. What that
- * costs in correctness is bounded: the fragment's own extinction no longer joins the total, so the
- * background is weighted by at most `1/256` instead of something smaller — below what the 8-bit
- * volume resolves anyway.
+ * whose sampled transmittance is at or below this in every channel before shading it. Where the
+ * 1/8-resolution volume is right at the full-resolution pixel, what that costs is bounded: the
+ * fragment's own extinction no longer joins the total, so the background is weighted by at most
+ * `1/256` instead of something smaller — below what the 8-bit volume resolves anyway. Where it is not
+ * — behind a gap narrower than a voxel in a near-opaque layer — the volume calls the pixel extinct and
+ * the surface seen through the gap is discarded, where the resolve's normalization would have drawn
+ * it. The deck's zero-transmittance cull shares the limit (ledger entry 26).
  * @type {number}
  */
 export const AVBOIT_EXTINCT_TRANSMITTANCE = 1 / 256;
@@ -93,7 +97,9 @@ export const AVBOIT_FIELD_MASK = (1 << AVBOIT_FIELD_BITS) - 1;
  * How far toward the camera, in virtual slices, the draw pass samples the integral so that a surface
  * does not occlude itself through its own linear splat. With the exclusive-prefix storage convention
  * the analytic minimum is 1.5; the deck uses 2. Events closer together than this do not occlude each
- * other and degrade to weighted blending.
+ * other and degrade to weighted blending. A surface tilted away from the camera adds its footprint on
+ * top (`avboit_footprint_bias`): the base bias is for a surface splatted at its own depth, and the
+ * draw also reads the neighbouring voxel columns, where a tilted one was splatted nearer.
  * @type {number}
  */
 export const AVBOIT_SAMPLE_BIAS_SLICES = 2.0;

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

@@ -907,3 +907,312 @@ constants from one table, and fails with a draw pass that uploads its own copy (
 `chunk_dynamic_mesh_vertex.spec.js` runs the shared AVBOIT vertex stage on the emulator and checks a
 vertex is carried by the row its draw names. The other half of the item — the emptiness query and the
 gather both walking the first live mesh's triangles — is left as it was.
+
+
+## 26. Review against the deck and the Godot proof of concept — 2026-10-04
+
+Alex asked for the implementation to be checked against the deck and against
+`github.com/IsaacMarovitz/godot-avoit` (*"AVBOIT works and is shipped, but I'm worried there might be
+mistakes"*), then for an adversarial review of the proposal before it was carried out, and for the
+particle off-centre read to be looked at again. The work is on a branch, not on master, for him to look at
+first.
+
+**Checked against the deck and found faithful.** The 10|10|10 packing with two guard bits, and the
+per-channel first-overflow mark the integration pins from (slides 57–60); the exclusive-prefix integral at
+`P + 1` slice boundaries; the continuous piecewise-linear warp, which gets what the deck's "filterable"
+begin/end flags are for (slide 95) without them; the two-slice bias taken in virtual space; halving with a
+fresh dilation per level; the resolve (slides 13–15). Two choices differ from the deck without being
+defects: halving keeps the curve's shape and doubles every slice, where the deck re-adjusts its log curve so
+that precision near the camera holds; and the per-fragment extinct discard stands in for the
+zero-transmittance depth cull.
+
+**The splat's rounding — measured, not a defect.** Meshes, particles and trails split a fragment's float
+extinction between its two slices and round each share; the water rounded once and partitioned the counts.
+Through the shipped chunks: the first makes a faint surface's count depend on where it sits in its slice
+(α 3 %: one count or two) and is right on average over depth; the second is stable over depth and biased
+(α 1.5 %: one count where 0.7 is exact). Either way an event below α ≈ 1.1 % registers nothing — the deck's
+8-bit floor.
+
+**Found and measured.** Items 1 and 3 are fixed, each red then green; item 2 is open.
+
+1. *Tilted surfaces striped* — plan §9's sloped-surface risk, never measured until now. Every voxel column
+   holds a surface at the depth under its centre, and the draw reads the four nearest columns bilinearly; on a
+   surface tilted away from the camera the near-side neighbour holds the same surface nearer by its depth change
+   over up to a voxel, and past the two-slice bias the surface occluded itself by an amount that depended on
+   where the pixel sat in its voxel. A model of two overlapping α 0.5 cards at 1080p, through the shipped warp
+   build, curve, rounding and lookup, put it from about 30° (red −13 %, green +25 % at 45° with the front one
+   tilted). On the RTX 4090, the playground at 720p with a card tilted behind a camera-facing one: a sawtooth
+   locked to `x mod 8`, 52.2–55.5 sRGB codes in red at 45° and 50.5–55.6 at 60°, against a flat 52.3 under
+   MBOIT and a flat camera-facing control. Fixed by `avboit_footprint_bias`: the lookup goes a further
+   `8 × fwidth(v)` virtual slices toward the camera — the bilinear reach — capped at `2 V / P`, the base
+   bias of the coarsest slicing (§3.8). After, on the device: 52.3–52.4 at 45°, flat in the interior at 60°.
+   The cost is the band: a tilted fragment is not occluded by what lies within its own voxel's depth span in
+   front of it. Past the cap — about 85° at 1080p in a sparse volume — the stripes can return.
+2. *The water pinned the warp at its floor.* Its occupancy marked every 8×8 tile's depth range, and a water
+   plane covers every depth from the shore to the horizon, so the warp halved to `V = P` whenever water was on
+   screen — AVBOIT became plain 128-slice VBOIT. Modelled with the shipped warp build: two α 0.5 cards at 10 m
+   separate at 0.25 m without water (V = 4096) and blend into one average at 0.25–0.5 m with a water plane
+   spanning 2–200 m in view, partly at 1 m. **Open.** A fix was built and taken out again: the water
+   moved out of the volume into a full-resolution *transmittance layer* that every other draw compared its
+   depth against. Alex: *"It's Anti-OIT."* It put a water special case into every transparent pipeline —
+   two bindings and a depth comparison per fragment in the mesh, particle and trail draws, a pass every
+   frame without water to bind something, and a contract every channel inherits — where order independence
+   means every source goes through the one volume. The water is in the volume again, exactly as before
+   this entry, and now takes the footprint like every surface that splats (its splat takes the nearest
+   depth over its 8×8 tile, so a voxel's width covers its own column; a neighbour's nearest point can lie
+   further). What bears on the pinning from inside the warp — hysteresis on halving and the deck's curve
+   re-adjustment — is measured in entry 27.
+3. *The particle splat read the soft fade at the voxel's corner*, `8 × voxel`: the top-left pixel, and not
+   the voxel's own footprint at all when the volume does not divide the frame. On a floor the row four pixels
+   up is farther by a good part of the 0.5 m fade range, so a smoke card standing on the floor went into the
+   volume at up to 2.4× the coverage it was drawn with (0.94 against a voxel average of 0.39 at 10 m) — entry
+   20's seam, one layer down again. Fixed by `chunk_particle_avboit_voxel_fade`: four reads at WebGPU's
+   standard 4× multisample positions over the voxel's footprint, through the exact low-to-full mapping.
+
+**The adversarial review of the proposal**, before any of it was built, changed it in four places:
+
+- *The footprint's reach.* A throwaway version at half a voxel cut the device sawtooth to 0.5 and 1.5 codes;
+  the bilinear lookup reaches a full voxel, so the full voxel is what removes it, and the spec holds that to no
+  self-occlusion at all.
+- *The footprint's cap.* Unbounded, it runs away at silhouettes and grazing angles — a sphere's rim would
+  ignore everything in front of it. It is capped at the coarsest slicing's base bias, the separation every
+  surface already has whenever the volume is full: the extra a fragment ignores is never more than that.
+  The whole reach, base bias included, is at most `2 + 2 V / P` virtual slices.
+- *The fade's sampling.* A read at the centre under-records the floor contact (0.24 against 0.39 at 10 m).
+  Over fifteen modelled contacts a 2×2 grid was off the voxel average by 0.05 on average and 0.12 at worst;
+  the rotated grid by 0.05 and 0.08, because its four reads fall on four rows and four columns.
+- *Withdrawn:* the meshlet splat takes glass's Fresnel from the geometric normal where the draw uses the
+  normal-mapped one. At the splat's coarse mip a high-frequency normal map averages back to the geometric
+  normal, and glass's Fresnel at near-normal incidence barely moves (about 0.04 across ±20°), so the two agree
+  well within what the volume resolves.
+
+**Corrected.** `AVBOIT_EXTINCT_TRANSMITTANCE`'s docblock bounded the discard's error by `1/256` of the
+background. That holds where the 1/8-resolution volume is right at the full-resolution pixel; behind a gap
+narrower than a voxel in a near-opaque layer the volume calls the pixel extinct and the surface seen through
+the gap is discarded, where the resolve's normalization would have drawn it. Constructed, not seen on a
+scene; the deck's zero-transmittance cull has the same limit. **Out of date:** entry 20's "the occupancy
+marks every emitter, with no frustum test" — the particles now mark the box their bounds pass measures from
+the quads, and skip additive emitters and unknown bounds.
+
+**The Godot proof of concept** is monochrome and composited over Godot's own transparents; every piece of it
+ports to WGSL. It splats at full resolution weighted by the cell's pixel area (64× the atomics), stores 16.16
+fixed point per slice (no 8-bit floor), reconstructs with a 4×4×4 cubic B-spline (whose wider XY footprint
+would stripe worse on slopes), takes occupancy from rasterized fragments, and keeps hysteresis on halving — it
+refines only once the occupied count drops below three quarters of the budget. That last is the one idea worth
+having here, where the virtual resolution is decided afresh every frame and a scene hovering at the budget
+could flip between two slicings; unmeasured.
+
+**An independent review of the commits**, by a reviewer who had only the diffs, the plan and this
+ledger, found nothing high or medium; it checked `fwidth` before any branch or discard at every call site
+and the spec's splat against the shader's. Taken from it:
+
+- *Additive particles took a footprint.* They write nothing into the volume, so nothing of theirs can
+  occlude them; the derivative is still taken in uniform control flow and selected away.
+- *Wording.* Camera-facing and stretched billboards are built from the camera's right and up, so their
+  footprint is zero (the draw's comment said they were tilted); the cap bounds the band, not the whole
+  reach; the side-channel contract now names the footprint.
+- Its findings about the layer went with the layer.
+- *Left:* the fade's four reads land on pixel boundaries at a scale of 8 and take the pixel past each, half a
+  pixel off the voxel's centre — inside what four reads resolve.
+
+**Verified.** Each fix red, then green, as above. The suites the change reaches (130 files, 1,518 tests
+with the layer gone); the whole engine suite (2,897 files, 22,247 tests, none failing, before the layer
+came out); the type check (declaration emit clean, 18 consumer-visible errors against the budget of 19, as
+before). On the RTX 4090, from the scratchpad and not in the repo: the slope probe; every AVBOIT module
+through `createShaderModule` and a frame under Brick4; the water page with the water back in the volume
+and taking the footprint, the card below the surface filtered by it (red 65 → 2 against the same view
+dry); no WebGPU validation error on any page (the water page's "Worker error" is the image-decoder worker
+bundle the dev server does not build, entry 22). A dev server left running across the revert's
+`git checkout` served the old recorder beside the new shader and threw; restarted, clean.
+
+## 27. Hysteresis and the curve re-adjustment, measured — 2026-10-04
+
+Alex, after entry 26's water layer was taken out: *"Go ahead and try hysteresis and the curve
+re-adjustment, I want you to measure the results."* Both are in the warp build behind two switches on
+`Renderer.avboit`, off by default, so the shipped frame is unchanged until one is turned on.
+
+**The deck's re-adjustment does nothing from a pure-log curve — measured, not built.** When the deck lowers
+its virtual slice count it re-parametrizes its log curve so slices near the camera keep their thickness.
+Searched over the free parameter of the engine's curve family (`build_light_cluster_parameters`:
+`slice = scale · log2(B z + O)`, pinned at the offset plane and the far plane), for each reference depth,
+the thinnest slice any member allows after halving 4096 → 2048 (near 0.1, far 200):
+
+| at | the deck wants | uniform halving | best member |
+|---|---|---|---|
+| 0.5 m | 0.08 cm | 0.16 cm | 0.10 cm — and 1.37× thicker at 50 m |
+| 1 m | 0.16 cm | 0.32 cm | 0.30 cm |
+| 2 m | 0.32 cm | 0.64 cm | 0.64 cm (pure log) |
+| 5 m | 0.79 cm | 1.59 cm | 1.48 cm |
+
+The same ratios hold for every halving. The deck's base curve is linearized and its re-adjustment moves it
+toward log; AVBOIT's curve is pure log at every level, the near-preserving end of the family already.
+
+**What re-adjusting can recover is the octave's waste** (`AVBOITSettings.warp_steps_per_octave`). Halving
+lands the occupied count anywhere from about half the budget to all of it. With four steps per octave the
+build tries `2 L · 2^(-i/4)` between the octave that fits and the one above it, finest first, rewriting the
+finest bits into those slices conservatively, run by run; consumers take any virtual count unchanged.
+
+- *Random scenes* (emulator, the shipped shader; 4–64 objects at 1–150 m log-uniform, extents 0.1–20 % of
+  their depth; 120 scenes per count): where the warp halves, the virtual resolution reached is 1.28–1.43×
+  finer on average (medians 1.19–1.41, at most 1.68), and the share of the 128 slices used goes from
+  72–83 % to 93–95 %.
+- *The bonfire* (`playground/particle_ecs`, `?debug`, 400 stepped frames, RTX 4090, the virtual count read
+  back every frame through a hook on the history buffer, no engine change): octaves sit at **128, the
+  floor, every frame**; four steps at **215**, 1.68× finer.
+- *Cost* (the build dispatched alone on the 4090, warmed, configurations interleaved, medians of 320):
+  12 runs of occupied slices 34 → 54 µs, 40 runs 22.5 → 53 µs, 600 fragmented runs 22.5 → 317 µs — the
+  single-lane run walk, three times per frame at most.
+
+**Hysteresis** (`AVBOITSettings.warp_hysteresis`, `AVBOIT_WARP_RELEASE` = 0.75, Godot's figure). The
+virtual resolution the warp settled on is kept per view in a one-word GPU buffer; a finer one is taken only
+when it fits in three quarters of the budget, coarsening is immediate.
+
+- *Synthetic* (emulator, the shipped shader, 600 frames; a smoke column's extent jittering frame to frame at
+  the extent where the level steps): without hysteresis the level flips about 290 times, every other frame,
+  at 1, 3 and 10 % jitter alike; with it, none — the frames that flipped to the finer level are held at the
+  coarser one instead (2× coarser with octaves, 1.19× with steps). A slow drift through the threshold:
+  25 flips → 1 with octaves, 62 → 2 with steps.
+- *The release* (a replica of the decision, agreeing with the shader on 400 of 400 frames): it sets the
+  jitter tolerated and the precision given up while a scene shrinks. With four steps:
+
+| release | flips at 10 % jitter | at 25 % | budget used, shrinking scene |
+|---|---|---|---|
+| 1 (off) | 314 | 310 | 0.90 |
+| 0.95 | 104 | 259 | 0.87 |
+| 0.9 | 0 | 198 | 0.84 |
+| 0.75 | 0 | 34 | 0.75 |
+
+  With octaves the cost is larger, down to 0.59 of the budget at 0.75: refining needs the next level's count,
+  twice this one's, to fit in three quarters.
+- *The bonfire*: with the camera still, **no flip in 400 frames** at any setting — real particle bounds did
+  not jitter across a threshold here. Orbiting 90°: octaves flipped twice (128 ↔ 256), steps twice
+  (215 ↔ 256), steps with hysteresis never — held at 215 for the 21 frames where 256 was available.
+- *Cost*: one load and one store in a single-invocation pass; nothing measurable.
+
+**Found on the way: the warp build's serial LUT costs 136 µs whenever the volume is sparse.** With the
+occupancy fitting at 4096 virtual slices the build took 136 µs on the 4090, against 22.5 µs at 128: one
+invocation writing 4,097 LUT entries. Entry 15 raised `AVBOIT_VIRTUAL_SLICES_MAX` to 4096 counting "a longer
+single-lane loop in the warp build" among costs that do not register; it registers, against entry 17's
+290 µs for the whole of the transparency work on a page whose occupancy fits at 4096. A workgroup prefix
+sum would take it to a few microseconds, and the steps' run walk with it. Not done here.
+
+**Verified.** Seven new emulator specs on the build: the first step down that fits, the fall-through to the
+octave, a step's slices covering every finest slice they overlap, hysteresis holding without room to spare
+and refining with it, coarsening at once, the history recorded when hysteresis is off. The suites the change
+reaches (132 files, 1,537 tests); the type check at 18 against the budget of 19. On the 4090 the build
+compiles and runs with both switches in the bonfire, no validation error.
+
+**Open:** whether to turn either on — the steps are a measured 1.2–1.7× in over-budget scenes for 20–300 µs
+of single-lane work, hysteresis a guard against a flicker the bonfire did not show; the release, if
+hysteresis goes on (0.9 with steps by the table above); a parallel warp build, which would make the steps
+nearly free and take back the 136 µs.
+
+## 28. The warp build, one workgroup — 2026-10-04
+
+Alex: *"go ahead and parallelize the warp build please, go ahead and use subgroups too if it's relevant"*,
+with a snippet from the IOI Smolder talk — CuteSort, which ranks a lane by `WaveActiveBallot` per key bit
+and `countbits`.
+
+**What it was.** One invocation — §3.4 had it that a 1 K-entry prefix sum is not a workload, and that a single
+lane keeps the shader runnable in the emulator. Entry 27 measured it at 22.5 µs halving to 128 virtual
+slices, 136 µs whenever the occupancy fits at 4096 (the 4,097-entry LUT written serially), and 317 µs with
+four steps over 600 fragmented runs (the run walk).
+
+**What it is.** One workgroup of 128 invocations, one per occupancy word, each holding its finest word in a
+register for the whole build.
+
+- *A resolution tried:* every invocation marks the virtual slices its word's runs touch
+  (`chunk_avboit_warp_marks`) — finest slice `f` touches `floor(f V / V_max)` to `ceil((f + 1) V / V_max) - 1`,
+  division-free because `V_max` is a power of two, and 32 finest slices touch at most two virtual words — and
+  `atomicOr`s them into workgroup memory. Each invocation then dilates its own word of that resolution
+  (`chunk_avboit_warp_level_word`), and a `subgroupAdd` per subgroup and one pass over the partials count
+  them. Octaves are marked by the same rule, so halving is no longer a fold of the level above; where
+  `V_max / V` is a power of two the overlap rule is the fold.
+- *Decisions* are made on that count read back through `workgroupUniformLoad`, which is what lets Tint accept
+  loops with barriers and subgroup operations inside: the octave loop bounded at 13, the steps loop by the
+  uniform setting.
+- *The LUT:* `subgroupExclusiveAdd` over the chosen words' counts plus the earlier subgroups' totals, then 32
+  coalesced writes per invocation (`chunk_avboit_warp_lut_entry`).
+- The marks alternate between two halves of a workgroup array, each try zeroing the half the next will mark,
+  so a try costs three barriers.
+
+A first cut had each invocation compute its virtual word straight from the finest bits — 34 slices, two
+integer divisions each. Bit-exact, and 7 µs at 4096, but slower than the single lane wherever the warp halves
+(26.6 µs against 22.5 at 128): at 128 virtual slices four invocations had a word and 124 waited. Marking from
+the finest side keeps all 128 busy at every resolution.
+
+**The CuteSort snippet.** Its rank — the popcount of a ballot masked to the lower lanes — is what a LUT entry
+already is: `countOneBits(word & ((1u << bit) - 1u))`. An occupancy word is that ballot, 32 slices to a
+word, so within a word no subgroup operation is needed and nothing anywhere needs sorting; subgroups carry the
+counts across words.
+
+**Measured** (RTX 4090, headless Chrome; the build dispatched alone, warm, single-lane and parallel
+interleaved in alternating order, medians of 240):
+
+| occupancy | V | single-lane | one workgroup |
+|---|---|---|---|
+| sparse, fits at 4096 (steps 1 or 4) | 4096 | 136.2 µs | 3.1 µs |
+| 12 runs, steps 1 | 512 | 33.8 µs | 3.1 µs |
+| 12 runs, steps 4 | 724 | 54.3 µs | 4.1 µs |
+| 40 runs (bonfire-like), steps 1 | 128 | 22.5 µs | 4.1 µs |
+| 40 runs, steps 4 | 128 | 53.3 µs | 5.1 µs |
+| 600 fragmented runs, steps 1 | 128 | 22.5 µs | 7.2 µs |
+| 600 fragmented runs, steps 4 | 128 | 317.4 µs | 9.2 µs |
+| occupied everywhere, steps 1 | 128 | 22.5 µs | 4.1 µs |
+| occupied everywhere, steps 4 | 128 | 34.8 µs | 5.1 µs |
+
+A step tried now costs about a microsecond, so the cost half of entry 27's open question is gone.
+
+**Verified.**
+
+- *Bit-exact against the single-lane build on the 4090:* both shaders in one page on the same inputs, every
+  word of the warp and the history word compared. 5,304 cases: 397 occupancy patterns (empty, full, single
+  slices at word edges, runs sized around every octave's budget at seven offsets, trains of runs, 160 random
+  run sets, random bits at seven densities) × physical 128 (96 and 200 on a third of them) × steps 1, 2, 4, 7
+  × hysteresis off and on with assorted previous resolutions. Every level from 64 to 4096 was reached; no
+  word differs. Tint compiles it with no message.
+- *Through the shipped pipeline* (the bonfire, entry 27's probe, 80 frames per setting): 128 virtual slices
+  with octaves, 215 with steps, the same two flips orbiting and none with hysteresis; no validation error.
+- *Not exercised:* subgroup sizes other than the 4090's 32. The scan takes invocations to fill subgroups in
+  index order, as `shader_prefix_scan_csdldf` does.
+- *Specs:* the emulator cannot run the workgroup, so — as with the bucket sorts (entry 22's sort, the
+  rasterization buckets) — the shader's spec holds the assembled source to the parser and the validator, and
+  the five new chunks carry their own: the marks against the overlap definition at octaves and between, runs
+  split across words, a word straddling a virtual word; the dilation and the cut at `V`; the budget; the
+  steps; the LUT entry. Flooring a run's last slice instead of ceiling it fails four of the marks specs. The
+  14 emulator tests of the whole single-lane build went with it; their scenarios are among the device cases.
+  The suites the change reaches: 160 files, 1,619 tests; the type check at 18 against 19.
+
+`chunk_avboit_fold_pairs` has no consumer now; kept.
+
+The water playground got a tickbox for the steps on the way (d915095b2). Its one view sits at 256 virtual
+slices in all six presets with or without them: the water's occupancy fits at 256 and at none of 431, 362
+or 304.
+
+**Open:** entry 27's — whether to turn the steps or hysteresis on, the steps now at about a microsecond per
+resolution tried.
+
+## 29. Four steps per octave by default; hysteresis removed — 2026-10-04
+
+Alex, after the warp, its defaults and entries 27–28 were explained: *"make 4 default, remove hysteresis."*
+
+**Steps.** `AVBOITSettings.warp_steps_per_octave` is 4. What it was measured to buy (entry 27): 1.28–1.43×
+finer virtual slices on average where the warp halves, 1.68× in the bonfire (128 → 215), and smaller level
+changes when the count crosses a threshold (215 ↔ 256 orbiting the bonfire, against 128 ↔ 256). What it
+costs since entry 28: about a microsecond per resolution tried, at most three per view per frame. Where
+halving already lands close to the budget no step fits and the warp is the octave's, as before. The water
+playground's tickbox starts ticked, mirroring the default.
+
+**Hysteresis** is gone: `AVBOITSettings.warp_hysteresis`, `AVBOIT_WARP_RELEASE`, `chunk_avboit_warp_budget`,
+the warp build's `history` binding and the per-view buffer behind it (`graph_avboit_build_warp` no longer
+takes a `history_key`). It guarded against a flicker measured only in synthetic jitter — the bonfire with a
+still camera never changed level — and cost precision whenever a scene shrinks, holding the coarser
+slicing until a quarter of the budget was free.
+
+**Verified.** The build without the history binding against the single-lane build of entry 27 with
+hysteresis off, on the 4090: entry 28's 397 occupancy patterns × physical counts × steps 1, 2, 4, 7, 2,652
+cases, every word of the warp identical; timing unchanged (3.1–9.2 µs). The suites the change reaches; the
+type check.
+
+**Open:** none from this.
+

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 7
+**Status:** implemented, default mode, device tier in progress — revision 8
 **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`
@@ -47,6 +47,22 @@ Games, SIGGRAPH 2025 (talk deck, 60 pages, `AVBOIT_SIG2025_MDROBOT-final.pdf`)
 > 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.
+>
+> **Revision 8** (ledger entry 26) is the review against the deck. The lookup bias grows by the fragment's
+> own footprint (§3.8), which closes §9's sloped-surface risk. The particle splat's soft fade is averaged over
+> the voxel rather than read at its corner. A water plane in view takes the warp's whole budget (§9); taking
+> the water out of the volume was tried and withdrawn as anti-OIT.
+>
+> **Revision 9** (ledger entry 27): the warp build can try virtual resolutions between octaves
+> (`AVBOITSettings.warp_steps_per_octave`) and hold the previous frame's against refining
+> (`warp_hysteresis`), both off by default (§3.4). The deck's curve re-adjustment was measured and gives
+> nothing from a pure-log curve.
+>
+> **Revision 10** (ledger entry 28): the warp build is one workgroup, an invocation per occupancy word, with
+> subgroup reductions and a subgroup scan for the LUT (§3.4); it was one invocation.
+>
+> **Revision 11** (ledger entry 29): four steps per octave is the default, and revision 9's hysteresis is
+> removed.
 
 ---
 
@@ -206,15 +222,19 @@ integration; that is an optimization on passes that cost ~0.25 ms at our resolut
 
 ### 3.4 Warp LUT build
 
-A single-invocation compute shader (`@workgroup_size(1)`) — the work is a few thousand bit operations, and a
-single lane keeps the whole thing runnable in the WGSL emulator, whose barriers are no-ops and which has no
-workgroup-cooperative dispatch. This is not a fallback for a subgroup path; a 1 K-entry prefix sum is not a
-workload.
+*Revision 10:* one workgroup of 128 invocations, one per occupancy word. Revisions 1–9 had a single
+invocation, on the argument that a 1 K-entry prefix sum is not a workload and that a single lane keeps the
+shader runnable in the WGSL emulator; at `V_max = 4096` the serial LUT alone measured 136 µs (ledger entry 27).
+A resolution tried is every invocation marking the virtual slices its finest word's runs touch, at most two
+words, OR-ed into workgroup memory, then every word of it dilated by its own invocation and counted with a
+subgroup reduction; the LUT is a subgroup scan of the chosen words' counts. Each decision is made on a count
+read back through `workgroupUniformLoad`. The emulator cannot run it: the pure parts are chunks with specs,
+and the whole was verified bit-exact against the single-lane build on a device (ledger entry 28).
 
 Per level, in order: dilate the occupancy by one slice each side *at this level* (a fragment on the edge of a
 meshlet's bounds linear-splats half its extinction one slice out, and that slice has to belong to the same run
 — dilating only at the finest level can shrink to nothing after halving), count, and either accept or halve the
-undilated bits and repeat.
+resolution, marked afresh from the finest bits, and repeat.
 
 Output, `AVBOIT_WARP_STRUCT`:
 
@@ -238,6 +258,13 @@ begin/end flags unnecessary here: a sample that falls in a gap lands exactly on
 runs, and with the integral stored at slice *boundaries* (§3.6) that reads the previous run's full total and
 none of the next run's — which is the right answer for empty space.
 
+*Revision 9:* with `warp_steps_per_octave > 1` the build also tries `2 L · 2^(-i / steps)` virtual slices
+between the octave `L` that fits and the one above it, finest first, with the finest bits rewritten into
+those slices conservatively run by run, so the occupied count lands closer to the budget; any virtual count
+works downstream, since the coordinate is the finest one scaled by `V / V_max`. Ledger entry 27 has what it
+buys and costs. *Revision 11:* four steps is the default; the hysteresis revision 9 added beside the steps
+is removed (ledger entry 29).
+
 ### 3.5 Splat
 
 A render pass at `ceil(internal / AVBOIT_VOXEL_DOWNSCALE)` with the shared `vertex_shader_chunk`, no depth
@@ -328,6 +355,14 @@ reads the previous run's total — instead of reading two slices into a run that
 With the splat and storage conventions above the analytic minimum that avoids any self-occlusion is 1.5 slices;
 `AVBOIT_SAMPLE_BIAS_SLICES = 2.0` follows the deck and leaves half a slice of margin.
 
+*Revision 8:* that minimum is for a surface splatted at its own depth, and the draw also reads the
+neighbouring columns, up to a voxel away, where a surface tilted away from the camera was splatted nearer.
+Every draw of a surface that splats adds `avboit_footprint_bias` — `8 × fwidth(v)` virtual slices, a voxel's
+width of its own depth change, capped at `2 V / P`, the base bias of the coarsest slicing — so a tilted
+surface does not occlude itself; additive particles, which write nothing into the volume, add none. A
+tilted fragment is then not occluded by what lies within that band in front of it (ledger entry 26). The
+cap bounds the band; the whole reach is at most `2 + 2 V / P`.
+
 IBL and Brick4 variants are two files, as for MBOIT, sharing the fragment body text; the Brick4 one carries
 the extra `brick4` storage buffer in the view group.
 
@@ -387,7 +422,7 @@ its layout group by group — material, scene and view at `VERTEX | FRAGMENT`, t
 | Storage buffer for the extinction volume | 3D storage texture | WebGPU has no atomic image operations. |
 | Integral as exclusive prefix at slice boundaries, `P + 1` texels | Inclusive prefix at slice centres | Makes a gap sample land exactly on a run boundary and read the right total; costs one extra depth texel. |
 | Sample bias in virtual space before the warp | Bias in physical space after it | Across a gap the physical bias reaches into a different depth region; the virtual one stops at the flat boundary. |
-| Warp LUT built by one invocation | Workgroup prefix sum with subgroup ops | 1 K entries; a single lane is microseconds and the emulator can run it. Not a fallback path. |
+| *Revision 10:* warp built by one workgroup, an invocation per occupancy word, subgroup reductions and scan | One invocation (revisions 1–9) | At 4096 virtual slices the serial LUT alone cost 136 µs on an RTX 4090, and the steps' run walk up to 295 µs more; the workgroup takes 3–9 µs with the same output (ledger entry 28). The emulator cannot run it; its pure parts are chunks with specs. |
 | Occupancy from meshlet AABBs | Conservative software voxelization of quads and boxes (the deck) | The engine already has HZB-filtered meshlet bounds on the GPU; a meshlet is a tighter primitive than a mesh box. |
 | *Revision 4:* the engine's depth slicing, Morton decode, linear-clamp sampler and a shared draw loop | The pipeline's own curve, bit fold, sampler descriptor and a copy of the MBOIT draw loop | Reinventions, found in review. The one thing kept apart from the engine on purpose is the shared draw-fragment body text (`avboit_draw_fragment_body.js`): MBOIT duplicates its resolve body across the IBL and Brick4 files, and two 45-line bodies drifting apart is the worse failure. |
 | No depth test in the splat pass | Low-res depth from the HZB | Correctness does not need it (§3.5); it is a splat-throughput optimization to measure first. |
@@ -422,7 +457,11 @@ src/shade/renderer/rasterize/native/avboit/
     chunk_avboit_occupancy_range.js         slice interval → dilated slice range
     chunk_avboit_occupancy_word_mask.js     bits of one word inside a range
     chunk_avboit_dilate_word.js             one-slice dilation across words
-    chunk_avboit_fold_pairs.js              halve a word's resolution (via decode32_morton2)
+    chunk_avboit_fold_pairs.js              halve a word's resolution (via decode32_morton2); unused since rev 10
+    chunk_avboit_warp_marks.js              the virtual slices a finest word's runs touch (rev 10)
+    chunk_avboit_warp_level_word.js         a resolution's word, dilated and cut at V
+    chunk_avboit_warp_step_count.js         the resolutions between octaves
+    chunk_avboit_warp_lut_entry.js          one LUT entry from its word and the count below it
     chunk_avboit_warp.js                    φ(v_f) over the LUT
     chunk_avboit_view_depth_to_virtual.js   the curve, scaled to the active resolution
     chunk_avboit_view_depth_to_physical.js  curve then warp
@@ -432,7 +471,7 @@ src/shade/renderer/rasterize/native/avboit/
     chunk_avboit_splat_slice.js             the two-slice voxel write, shared with the side channels
     AVBOITSideChannel.js                    the contract for a non-meshlet transparent source (rev 5)
     shader_avboit_occupancy.js              compute, per meshlet
-    shader_avboit_build_warp.js             compute, one invocation
+    shader_avboit_build_warp.js             compute, one workgroup (rev 10)
     shader_avboit_splat.js                  render pass, 1/8 resolution, atomics
     shader_avboit_integrate.js              compute, per column
     avboit_draw_fragment_body.js            shared WGSL text of the draw fragment
@@ -553,3 +592,9 @@ Each step lands with its tests green before the next starts; the ledger records
 - **Sloped surfaces** — a splat fragment carries the depth of its low-resolution pixel centre; on a surface at
   a grazing angle that can differ from the full-resolution fragment's depth by more than the bias. Self-occlusion
   along the slope would be the symptom; the page's copyable camera state is what makes that reproducible.
+  *Revision 8:* measured and closed. It was not only grazing angles: from about 30° at 1080p a tilted surface
+  over another transparent layer striped in an 8-pixel sawtooth, 3–5 sRGB codes on the device at 45–60°. The
+  footprint bias (§3.8) removes it up to its cap, about 85° in a sparse volume (ledger entry 26).
+- **A surface spanning a long depth range** — a water plane above all, from the shore to the horizon —
+  occupies so many virtual slices that the warp halves to `V = P`, and every other transparent surface in
+  the frame is sliced at the coarsest resolution (*revision 8*, measured in ledger entry 26).

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

@@ -1 +1 @@
-{"version":3,"file":"avboit_draw_fragment_body.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/avboit_draw_fragment_body.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAFU,MAAM,CAgEV;AAEN;;;GAGG;AACH,gDAFU,WAAW,CASnB;AAEF;;;GAGG;AACH,kCAFU,qBAAqB,CAiB3B"}
+{"version":3,"file":"avboit_draw_fragment_body.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/avboit_draw_fragment_body.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAFU,MAAM,CAoEV;AAEN;;;GAGG;AACH,gDAFU,WAAW,CAWnB;AAEF;;;GAGG;AACH,kCAFU,qBAAqB,CAiB3B"}

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

@@ -4,6 +4,8 @@ import { chunk_unjitter_uv } from "../../../shader/chunk/texture/chunk_unjitter_
 import { FORWARD_VERTEX_SHADER_STRUCT } from "../../forward/FORWARD_VERTEX_SHADER_STRUCT.js";
 import { OIT_COVERAGE_MAX } from "../oit/OIT_CONSTANTS.js";
 import { AVBOIT_EXTINCT_TRANSMITTANCE } from "./AVBOIT_CONSTANTS.js";
+import { chunk_avboit_view_depth_to_virtual } from "./chunk_avboit_view_depth_to_virtual.js";
+import { chunk_avboit_footprint_bias } from "./chunk_avboit_footprint_bias.js";
 import { chunk_avboit_sample_transmittance } from "./chunk_avboit_sample_transmittance.js";
 import { chunk_avboit_transmission_tint } from "./chunk_avboit_transmission_tint.js";
 
@@ -65,7 +67,11 @@ fn main(
     let frag_view_depth = get_view_space_depth(vert_adjusted.position.z, camera);
     let frag_screen_uv = vert_adjusted.position.xy / vec2<f32>(f32(view.width), f32(view.height));
 
-    let transmittance = avboit_sample_transmittance(&warp, tIntegral, sLinear, frag_screen_uv, frag_view_depth);
+    // how far the surface's own depth runs across a voxel, so it does not occlude itself through the
+    // neighbouring columns; taken here, in uniform control flow, before anything can discard
+    let footprint = avboit_footprint_bias(&warp, fwidth(avboit_view_depth_to_virtual(&warp, frag_view_depth)));
+
+    let transmittance = avboit_sample_transmittance(&warp, tIntegral, sLinear, frag_screen_uv, frag_view_depth, footprint);
 
     if (all(transmittance <= vec3<f32>(${AVBOIT_EXTINCT_TRANSMITTANCE}))) {
         // nothing this fragment contributes survives what is in front of it; skip the shading
@@ -113,6 +119,8 @@ export const AVBOIT_DRAW_FRAGMENT_DEPENDENCIES = [
     chunk_unjitter_uv,
     chunk_get_view_space_depth,
     chunk_sample_volumetrics,
+    chunk_avboit_view_depth_to_virtual,
+    chunk_avboit_footprint_bias,
     chunk_avboit_sample_transmittance,
     chunk_avboit_transmission_tint,
 ];

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

@@ -0,0 +1,33 @@
+/**
+ * How much further toward the camera, in virtual slices, a fragment has to look the integral up so
+ * that its own surface does not occlude it through the neighbouring voxel columns — given
+ * `virtual_fwidth`, the fragment's `fwidth` of its virtual slice coordinate
+ * (`avboit_view_depth_to_virtual`), which the caller takes in the fragment stage.
+ *
+ * The volume is 1/8 resolution and every column holds a surface at the depth under the column's
+ * centre. The draw reads the four nearest columns bilinearly, up to one voxel away. On a surface
+ * tilted away from the camera, the neighbour on its near side holds the same surface nearer by the
+ * surface's depth change over that distance, and once that exceeds the two-slice base bias the
+ * surface occludes itself — by an amount that depends on where the pixel sits in its voxel, so an
+ * overlapping layer showed 8-pixel stripes (ledger entry 26: 3–5 sRGB codes on the device at 45–60°).
+ * A voxel's width of the surface's own depth change, `AVBOIT_VOXEL_DOWNSCALE × fwidth`, covers the
+ * farthest column the lookup reaches. The virtual coordinate is convex along a plane seen in
+ * perspective, so its derivative at the fragment bounds the change toward the near side.
+ *
+ * What it costs: a tilted fragment is not occluded by what lies within that band in front of it, the
+ * depth the volume cannot tell apart from the surface itself at this resolution. The band is capped at
+ * the base bias of the coarsest slicing, `V / P` base biases — the separation every surface already
+ * has whenever the volume is full and the warp halves down to `V = P` — so where the derivative runs
+ * away, at a silhouette or a grazing angle, the extra a fragment ignores is never more than that. The
+ * whole reach is the base bias plus the band: at most `2 + 2 V / P` virtual slices, twice the coarsest
+ * separation when the volume is full, about the coarsest separation at `V = 4096`. Past the cap (about
+ * 85° at 1080p in a sparse volume) the stripes can return.
+ *
+ * A fragment that writes nothing into the volume — an additive particle's — has nothing of its own there
+ * to occlude it and takes no footprint.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_avboit_footprint_bias: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_avboit_footprint_bias.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_avboit_footprint_bias.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/chunk_avboit_footprint_bias.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,0CAFU,SAAS,CAYjB;0BA5CwB,uCAAuC"}