@woosh/meep-engine 3.11.1 → 3.11.3

package/src/shade/renderer/volumetrics/NOTES.md

@@ -1,11 +1,11 @@
-* https://shaderbits.com/blog/creating-volumetric-ray-marcher
-* "Physically Based and Unified Volumetric Rendering in Frostbite" SIGGRAPH 2015
-* "Creating the Atmospheric World of Red Dead Redemption 2: A Complete and Integrated Solution" SIGGRAPH 2019
-* "Volumetric Fog in Enshrouded" GPC 2024 (https://www.youtube.com/watch?v=OR8HbFnQdlk)
-
-
-
-Check out "A Novel Sampling Algorithm for Fast and Stable Real-Time Volume Rendering" SIGGRAPH 2015
+* https://shaderbits.com/blog/creating-volumetric-ray-marcher
+* "Physically Based and Unified Volumetric Rendering in Frostbite" SIGGRAPH 2015
+* "Creating the Atmospheric World of Red Dead Redemption 2: A Complete and Integrated Solution" SIGGRAPH 2019
+* "Volumetric Fog in Enshrouded" GPC 2024 (https://www.youtube.com/watch?v=OR8HbFnQdlk)
+
+
+
+Check out "A Novel Sampling Algorithm for Fast and Stable Real-Time Volume Rendering" SIGGRAPH 2015
  * https://github.com/huwb/volsample/blob/master/src/shadertoy/clouds.shader
 ## Blue noise for the froxel column jitter — measured, 2026-08-29
 
@@ -48,3 +48,882 @@ away, and the obvious fix aggravates the stated mechanism. Genuinely removing it
 XY jitter (the TAA's 3×3×3 Blackman–Harris resample already does spatial reconstruction), not
 changing the noise source. Adopt `stbn_vec1` when cutting `SAMPLE_COUNT` (P-01), where better
 per-pixel temporal distribution is the actual goal — and never `stbn_vec3`, for the reason above.
+
+## Shadowing the clustered lights — measured, 2026-08-29
+
+Q-01. The point and spot loops in `shader_volumetrics_build_lighting` never applied a shadow map, so
+geometry did not occlude a local light in the volume at all; only the medium's own optical depth
+did. The directional loop always had. Fixed by `chunk_volumetrics_local_light_shadow`, one nearest
+atlas tap per light.
+
+Two things about it were expected to be problems and measured not to be. The numbers below came from
+a `local_light_shadow_mode` word on the metadata that switched between off, that tap, and the
+deferred path's filter kernels; it and the two playground checkboxes over it have since been removed,
+which is why nothing in the tree reproduces these rows any more. Restoring the comparison means
+re-adding that switch.
+
+**The cost is nearly nothing, even at 130 shadow-casting lights.** Whole-frame median over 18
+interleaved rounds in the playground scene at 3840x2160 (the froxel grid is 4x the 1080p one, so
+this magnifies any per-froxel cost by 4x):
+
+| sampling | frame (ms) | vs. off |
+|---|---|---|
+| off | 10.29 | — |
+| one atlas tap (what ships) | 10.42 | +0.13 (+1.2%) |
+| deferred kernels (8 cone taps / 9-gather PCF) | 10.71 | +0.42 (+4.0%) |
+
+Scaled back to 1080p that is +0.03 ms and +0.10 ms, both far below the run-to-run spread. Which
+means the thing P-02 exists to make affordable was already affordable — do not reach for a
+pre-filtered ESM/VSM target on Q-01's behalf. It also means the "skip the shadow test for lights
+whose contribution is negligible" idea has nothing left to buy and would only add a popping risk.
+
+**The cheap tap is not a quality compromise here — it is indistinguishable, and marginally
+quieter.** Under the measurement protocol in the playground README (auto exposure off, 45 frames of
+re-convergence, 32-frame average, noise floor from an identical no-op toggle):
+
+| comparison | signed mean | mean abs |
+|---|---|---|
+| noise floor (mode 1 vs itself) | -0.053 | 1.110 |
+| mode 1 vs off | **-0.852** | 1.826 |
+| mode 2 vs off | **-0.853** | 2.010 |
+| mode 1 vs mode 2 | +0.0004 | 1.439 |
+
+The two paths remove the same light to four decimal places — 0.0004 against a floor of 0.05 — and
+their per-pixel difference sits at the floor. Residual noise after the TAA (mean abs of two settled
+captures of the same setting) is 1.100 off, 1.343 for one tap, 1.381 for the kernels: the 8-tap cone
+is *noisier*, because its taps are drawn stochastically per frame. Repeated with a shadow-casting
+spot light added to the scene: mode 1 vs mode 2 signed mean -0.061, mean abs 1.092, against that
+run's floor of +0.016 / 1.124 — below the floor on both statistics.
+
+So the PCF kernel really was filtering something about to be filtered three more times, and the
+deferred path keeps it for surfaces, where it belongs.
+
+One caveat came out of this, recorded because it bit the spec, and since fixed — though not the way
+it first looked. `shadowmap_sample_point` rounds its taps stochastically from
+`uv * face_size - 0.5`, and an axis-aligned light-to-sample direction encodes to an octahedral uv of
+exactly 0 or 1, so some taps land at texel -1 or `face_size`, one texel outside the rect the record
+publishes. Latent in the deferred path (mode 2), not introduced here; mode 1 clamps and never had it.
+Not an exotic input either: the xy axes are the four edge midpoints of the square and the -Z pole is
+its corner, so a lamp above the floor beneath it overshoots on roughly half its taps.
+
+**That overshoot is provided for, and the first read of this was wrong.** `shadow_point` publishes
+the INNER octahedral surface — `make_octahedral_point_shadow_record` subtracts
+`SHADOWMAP_ATLAS_BORDER` (4) from every side of the slot — and the cube → octahedral remap fills the
+ring around it with `inner[texture_octahedral_wrap_texel_coordinates(local)]`, folding each border
+fragment through the wrap before decoding a direction from it. One texel of overshoot therefore
+reads this light's own wrapped data, four texels inside its slot. Nothing was ever reading a
+neighbouring light, and the `face_size` overshoot was never a defect at all.
+
+What *was* wrong is narrower: the sampler reached the skirt through
+`vec2<u32>(rounded_local_texel) + vec2<u32>(atlas_aabb.xy)`, and `vec2<u32>` of `-1.0` is a
+negative-to-`u32` conversion WGSL leaves indeterminate. Land on `0xFFFFFFFF` and the wrapping add
+gets to `inner - 1`, which is right; land on `0`, equally legal, and the tap silently reads the
+opposite edge of the inner surface. Fixed by doing the add in `i32` — exact for an integral `f32` in
+`[-1, size]`, and the inner origin is at least `SHADOWMAP_ATLAS_BORDER`, so the `u32` at the end is
+defined.
+
+`shadow/map/shader/shadowmap_sample_point_seam.spec.js` builds a synthetic atlas with the skirt the
+remap would have written, and drives the shader under *both* legal readings of that conversion,
+requiring the same answer. That is the assertion that failed before; a checkerboard inner surface
+makes the two readings disagree on every affected tap, because the skirt texel at local `(x, -1)`
+holds `inner[size - 1 - x, 0]`, of opposite parity to `inner[x, 0]`.
+
+Worth knowing if the border is ever revisited: `chunk_shadow2d_pcf_multiple_tap_pcf_contact_hardened`,
+the DPCF disk kernel `SHADOWMAP_ATLAS_BORDER`'s doc names as its reason to exist, is imported by no
+shader — `chunk_shadowmap_sample_point2` replaced it with cone sampling. So the skirt's only current
+reader is that one-texel overshoot, and 8 texels per slot (half of a 16-slot) are otherwise idle.
+Cutting the border is therefore possible but not free: the overshoot needs at least one texel of it.
+
+## Amortizing the sun's optical depth into a light-aligned volume — measured, 2026-08-29
+
+> **Superseded in two places by the last section of this file.** What kept this switched off is not
+> the frustum-clipped medium; the field-of-view measurement that argued it was is confounded, because
+> widening the lens also coarsens the box. And the structure is cascaded now, not a single volume.
+
+Q-04. `integrate_optical_depth` marches 16 steps from every froxel toward every light. For two
+froxels on the same light ray the answers differ by one increment, and the pass recomputes the whole
+integral for each: a prefix sum evaluated as N independent sums.
+`shader_volumetrics_build_sun_shadow_volume` computes it once instead, into a voxel grid whose third
+axis is the sun, and `chunk_volumetrics_sun_optical_depth` reads it back in a single fetch.
+`__VOL_SUN_SHADOW` switches between them. **Off by default**, for the one reason recorded at the end.
+
+### What the literature actually does, including a correction
+
+The report this came from credited both RDR2 and Enshrouded with amortizing the per-froxel march
+into a volumetric shadow representation. Read against the released material, one of those is right
+and the other is not.
+
+**Enshrouded (GPC 2024) is doing exactly this, cascaded.** From the talk: "for rendering shadows …
+we are using 3D volumes in a cascaded fashion and align their z-axis to the direction of the primary
+light source, so in a first pass we would just initialize them with participating media properties
+and in a second pass integrate from the light source down … and that gives us information about how
+much shadowing there is from the fog for any position inside those cascades." And on the shipping
+version: "we're initializing that one in one 3D dispatch and then do a 2D dispatch for each cascade
+in the direction of the light … each cascade as an initial shadow value reads the upper cascade, so
+in the end we can just sample the one cascade and with one sample we get the full shadow volume, and
+the outer cascade is initialized with approximate volumetric shadows for clouds." Same structure,
+same build shape — a 2D dispatch walking columns along the light — with cascades on top and the
+outermost seeded from a cloud approximation. Their fog lives in a world-space voxel grid at 1 m per
+voxel, which is why they do not have the caveat below.
+
+**RDR2 (SIGGRAPH 2019) is not.** It does have a *Shadow Volume* — R16F, one of three volumes in a
+160x88x64 frustum grid, temporally filtered — but the slide and its speaker notes say what it holds:
+"the directional light shadow term sampled from the shadow map cascade as well as cloud and terrain
+shadow map". That is the **shadow map** lookup amortized, not the medium's own optical depth. The
+medium's self-shadowing there is a short secondary sample on cloud material ("we also sample
+extinction towards the sun or moon to generate high frequency shadowing") plus the cloud shadow map,
+which is a light-space ESM built by ray-marching the cloudscape from the light — a genuine
+light-space transmittance structure, but for clouds only. The talk's own Future Outlook slide lists
+**"Volumetric shadows"** as work not done. The review document is corrected accordingly.
+
+Costs from that talk, for calibration, on PS4: cloud ESM 0.156 ms, shadow volume 0.204 ms, material
+volume 0.33 ms, scattering volume 0.34 ms, far-field raymarch 1.31 ms.
+
+**Fourier Opacity Mapping is the famous answer and the wrong one here.** FOM (Jansen & Bavoil, I3D
+2010) projects log-transmittance along each light-space texel onto a truncated Fourier basis. It
+exists because the medium usually arrives as *unordered rasterized particles*, where the only thing
+available is a fixed-size, order-independent, additively blendable summary — and it pays for that
+with ringing at sharp density transitions, which is why Adaptive Volumetric Shadow Maps (Salvi et
+al., EGSR 2010) answer the same problem with a variable-error compressed curve instead. This engine's
+medium is already a 3D texture with a defined order along any axis, so the scan is available, exact
+for the piecewise-constant field a voxel grid *is*, and has nothing to ring. In the shadow-map
+taxonomy what is implemented here is an Opacity Shadow Map (Kim & Neumann 2001) with enough slices
+and hardware trilinear reconstruction that the slice artefacts it is remembered for do not appear.
+
+### The structure, and why it does not swim
+
+A cube in sun space, sized from the camera frustum's **bounding sphere** and snapped to whole voxels.
+Both halves matter and neither is decoration:
+
+- The sphere's radius is a function of `fov`, `aspect`, `near` and `far` only, so the extent does not
+  change when the camera turns. A tight fit of the frustum corners in sun space — which is what this
+  engine's CSM deliberately does, for reasons its own comment gives — would breathe under rotation,
+  moving every voxel centre continuously. The CSM can afford that because it is two orders of
+  magnitude denser and its consumer is a filtered depth comparison; this is neither.
+- With a fixed extent, snapping the origin makes the world-space voxel lattice *the same set of
+  points* every frame. Only the indexing changes. `build_volumetrics_sun_shadow_transform.spec.js`
+  asserts that directly: voxel centres generated for one camera pose land on voxel centres of the
+  grid generated for another, under translation, rotation and both together.
+
+Confirmed on the device, with the volumetric TAA off so nothing could hide a discontinuity. Creeping
+the camera across three voxels of translation, and separately across 20 degrees of yaw, the volume
+path's mean absolute second difference of frame luminance is *lower* than the march's — 0.0140 vs
+0.0165 translating, 0.0051 vs 0.0253 rotating. It does not snap.
+
+Six scripted motions (yaw, pitch, forward, backward, strafe, combined), 90 frames each, at two
+viewpoints, comparing the volume against the march on flicker while moving, on flicker and drift
+while settling, and on the converged image after the motion against the converged image from a
+standing start at the same pose. Every pair agrees to within a few percent; the largest gap in
+"flown vs still" is 0.06 mean luminance against a floor of 0.05. The structure adds no temporal
+instability of its own. `playground/volumetrics_froxel/measure.js` is that harness.
+
+### Cost, from the profiler rather than from frame time
+
+Per pass, `WORKLOAD` capture decoded in the page, 50 frames, two runs each:
+
+| pass | 1920x1080, march -> volume | 3840x2160, march -> volume |
+|---|---|---|
+| build sun shadow volume | 0.003 -> **0.048** | 0.003 -> **0.053** |
+| build lighting | 0.675 -> **0.499** | 1.857 -> **1.274** |
+| net | **-0.13 ms** | **-0.53 ms** |
+
+The whole-frame delta at 2160p is -0.55 ms with disjoint spreads over seven interleaved rounds,
+matching the per-pass sum. At 1080p whole-frame timing could not resolve it at all: the run-to-run
+spread is about +-0.5 ms and three interleaved runs read +0.11, +0.31 and +0.37 — the *wrong sign*.
+The README's advice to attribute cost to passes rather than infer it from frame time earned itself
+here.
+
+The shape is the point. The build is fixed at ~0.05 ms, and the same at 64^3 as at 128^3 — it is not
+where the time goes — while what it removes scales with the froxel count. Double the resolution and
+the saving doubles while the cost does not move.
+
+### Why it is off by default
+
+At seven of the nine playground viewpoints the two paths agree to within about four times the noise
+floor (|signed mean| <= 0.20 against a floor of 0.01-0.09). "Under the island" reads -0.73. **"Inside
+the fog" reads +1.92**, and carries a single **+3.8 pop** around 8 degrees into a yaw, which the
+0.95-blend TAA passes straight through rather than absorbing.
+
+That is not resolution, and the measurement that settles it is the field of view. At that same
+viewpoint, widening to 110 degrees brings the disagreement to -0.05 against a floor of -0.06 — gone —
+while *raising* the volume's resolution does not converge at all (32^3 through 192^3 oscillates
+between +7.0 and -1.9). The pop moves when `__VOL_FROXEL_FAR` moves and does not move with the box's
+snapping: the transform is bit-identical either side of it.
+
+> **Read the next section before trusting the paragraph below.** It calls the march "the converged
+> one", on the strength of `STEP_COUNT = 256` moving it by only -0.24 at *that* viewpoint. That is
+> true there and false in general — sixteen steps step clean over a thin fog slab, and there are
+> viewpoints in this same scene where the march is 58 luminance from its own converged answer while
+> the volume is 29 from it. Which of the two is nearer the truth is a property of the geometry, not
+> of the method.
+
+All of which points at the medium rather than the structure. `tParticipatingMedia1` is hard clipped
+to the camera frustum (Q-05), so the field being scanned has an artificial discontinuity in it. The
+march resolves that edge at its own step size, which is anchored at the froxel and shrinks to nothing
+exactly where the exit is near; a world-space lattice resolves it at a fixed 2.3 units. Where the sun
+ray leaves the frustum within a voxel or two of the froxel — inside dense fog, looking toward a low
+sun — that edge *is* the integral, and the two disagree. Widening the FOV pushes it away and they
+agree again. For a reference: the march at `STEP_COUNT = 256` differs from the shipping 16 by only
+-0.24 mean luminance, so the march is the converged one and the volume is the one in error there.
+
+So the fix is not more voxels and not a smarter fit. It is to stop sampling a frustum-shaped medium —
+build the volume from the scene's participating-media volumes directly, which removes the
+discontinuity, closes Q-05, and is the arrangement Enshrouded has. That is one shader's worth of work
+now that the structure and the measurements exist, and flipping the default is a line.
+
+Cascades are the other half of what Enshrouded ships, and this is shaped to take them: an inner
+cascade's scan starts from the outer cascade's value at its entry face instead of from zero. Worth it
+when the near field needs resolution the uniform grid cannot give — which, on this evidence, is not
+the binding constraint yet.
+
+## The sun volume strobed, and the march was not the reference — measured, 2026-08-29
+
+> **Read the last section of this file for what closed this.** The strobe diagnosis here is right
+> and the fix for it stands. The paragraph at the end proposing temporal accumulation is answered
+> there, and the answer is no; so is the claim that the box is thin in two axes.
+
+Reported from the playground: at a camera parked beside one of the small fog boxes, with the sun
+ahead, `__VOL_SUN_SHADOW = true` made the light pulse. Two poses, both reproducible, both with the
+camera *stationary* — which rules out everything the section above establishes about the box moving,
+since a still camera means a bit-identical transform every frame.
+
+Frame-to-frame mean luminance, 24 frames, camera static:
+
+| | march (16 steps) | volume, 1 sample per voxel |
+|---|---|---|
+| mean | 120.19 | 91.59 |
+| mean absolute frame-to-frame step | 0.0023 | 0.131 |
+| largest single-frame step | 0.004 | **0.623** |
+
+At the second pose the largest step was **1.81**. That is a visible pulse, and the temporal filter
+passes it through rather than absorbing it.
+
+### The march was not the reference, and the earlier note leant on it as if it were
+
+Raising `STEP_COUNT` to 512 to get a converged answer at these poses:
+
+| | pose 1 | pose 2 |
+|---|---|---|
+| march, 16 steps (shipping) | 120.18 | 149.47 |
+| **march, 512 steps** | **62.19** | **79.03** |
+| volume, 128^3, 1 sample per voxel | 91.59 | 119.23 |
+| volume, 256^3 | 63.20 | — |
+
+So at these poses the shipping march is 58 luminance from its own converged answer and the volume is
+29 from it: the amortized path is the *more* accurate of the two, and the resolution sweep that
+looked like divergence — 64^3 giving 120.3, 128^3 giving 91.8, 256^3 giving 63.2 — was convergence
+all along, toward a reference the earlier work never computed at this geometry. It read as
+divergence only because the shipping march was being used as ground truth, and here it is nowhere
+near it.
+
+Worth saying plainly, because it inverts the last paragraph of the section above: **the march at 16
+steps is converged when the medium is thick and spread out, and badly wrong when it is thin.** Its
+step is the distance to the frustum exit over sixteen, which at these poses is about 8 units, and
+the fog box it is meant to find is 3 units thick. It steps over it. A stable wrong answer does not
+strobe, which is the only reason the march looks better on the flicker column.
+
+### Why it strobed, and the fix
+
+The fog box here is 10x3x20 and the camera sits about a third of a unit outside its face. The sun
+travels roughly along -X, so what the ray toward the sun has to cross is the 3-unit dimension — and
+the 128^3 volume's voxel is 2.28 units. Walking the column that passes through the camera and asking
+which lattice points fall inside any scene volume: **two of them.** The entire shadow rested on two
+samples, and the froxel grid's per-frame column jitter moves the medium under both.
+
+The fix is to stop conflating the sampling rate with the storage resolution. A voxel has to hold the
+medium's *integral across its slab*, and one point sample at its centre is not that. The build pass
+now takes four sub-steps per voxel along the sun axis and stores the running integral at the voxel
+centre as before — 0.57-unit sample spacing behind a 2.28-unit voxel, one loop rather than 64x the
+memory:
+
+| | 1 sample/voxel | 4 sub-steps/voxel |
+|---|---|---|
+| pose 1, largest frame step | 0.623 | **0.083** |
+| pose 2, largest frame step | 1.81 | **0.151** |
+| pose 1, mean abs step | 0.131 | 0.020 |
+| pose 2, mean abs step | 0.468 | 0.037 |
+
+Six to thirteen times quieter, and it improves the static disagreement at *Inside the fog* as well,
++1.92 -> +1.30. The cost, per pass at `WORKLOAD`:
+
+| | 1920x1080 | 3840x2160 |
+|---|---|---|
+| build sun shadow volume | 0.008 -> 0.115 | 0.003 -> 0.133 |
+| build lighting | 0.427 -> 0.318 | 1.772 -> 1.068 |
+| net | **~0.00 ms** | **-0.57 ms** |
+
+So the strobe fix spends the 1080p win — it is now a wash there — and keeps the 2160p one. The build
+grew 2.7x rather than 4x, the rest being fixed overhead.
+
+### The switch is gone, and what that costs
+
+Q-04 is approved, so the cascades are the sun's only path and the A/B that measured them has been
+removed: the `__VOL_SUN_SHADOW` global, the playground checkbox over it, and the `sun_shadow_mode`
+word in the metadata, along with the branch in `shader_volumetrics_build_lighting` that read it.
+Same treatment Q-01 got, and it has the same consequence — **nothing in the tree reproduces the
+tables above any more.** Restoring the comparison means re-adding that word and its branch.
+
+Restoring the rest of it means more than that, and it is worth writing down while it is fresh:
+
+* the converged reference needs `STEP_COUNT` in `chunk_integrate_optical_depth` raised to 512;
+* the single-box rows need `VOLUMETRICS_SUN_SHADOW_CASCADE_RATIO` set to 1, which makes the three
+  cascades coincide and the structure exactly one box, built by the same code;
+* the resolution ladder needs `VOLUMETRICS_SUN_SHADOW_RESOLUTION` edited. There was a
+  `__VOL_SUN_SHADOW_RESOLUTION` override for it; it went with the rest, because a global that only
+  exists to A/B a constant is the same thing as the switch and it was inconsistent to keep one
+  without the other — the ratio never had one.
+
+What replaces the mode word is one field rather than two. `sun_shadow_light_index` already said
+which directional light the cascades were built for, so that a second sun degrades to the march
+instead of being shadowed by the first one's boxes; it now also carries
+`VOLUMETRICS_SUN_SHADOW_LIGHT_NONE` for the two cases that can place no box at all — a scene with no
+directional light, and a camera with no field of view to derive a bounding sphere from. The sentinel
+matches no index, so those degrade every directional light the same way. "Not built this frame" is a
+property of the light, not a mode to select, and saying it that way removes the failure mode a mode
+word has: left at zero it selects the march, silently, everywhere.
+
+The build passes still run in those cases, collapsed to one voxel per cascade. Not for measurement
+symmetry any more — that argument went with the A/B — but because the lighting pass binds their
+outputs unconditionally and WebGPU has no optional bindings.
+
+### What is left, and it is not more sub-steps
+
+Sub-stepping fixed the *temporal* aliasing and left most of the *magnitude* gap: pose 1 went 91.59 ->
+92.97 against a reference of 62.19. That is because sub-stepping refines one axis and the fog box is
+thin in two of them — perpendicular to the sun its cross-section is the 3x20 face, so the 3-unit
+dimension is under-sampled laterally as well, and only 256^3, which refines all three, converges.
+Lateral sub-sampling would blur the shadow rather than sharpen it, so that is not the answer either.
+
+The answer is *not* what the first draft of this section said, which was to build the volume from
+the scene's media volumes and integrate each box analytically, "since the chord a sun ray cuts
+through a box has a closed form". That assumes the medium inside a box is uniform, and it is not.
+
+`compute_volume_fade_factor` ramps the density near every face:
+`smoothstep(0, fade_distance, d.x) * smoothstep(0, fade_distance, d.y) * smoothstep(0, fade_distance, d.z)`
+over the world-space distance to each face. So a box's interior is a separable cubic-Hermite ramp,
+and `chord_length * sigma` is wrong by whatever the fade profile does along that chord. The volumes
+overlap too, though that half is harmless on its own — optical depth is additive, so
+`tau = integral of sum(sigma_i) = sum of integral of sigma_i`, and each volume could in principle be
+integrated separately. It is the non-uniformity inside each one that kills it.
+
+And there is a worse problem underneath, which is that **the participating-media pass does not
+discretise a field — it evaluates an estimator**. `compute_volume_fade_factor` takes the *froxel's
+frustum*, intersects it with the box, and samples the fade at the midpoint of that intersection
+segment; `frustum_unit_box_coverage` multisamples the froxel/box overlap to get a coverage fraction.
+Both answers depend on the shape of the froxel, not only on where it is. There is therefore no
+`sigma(x)` that the PM grid is sampling and that something else could integrate exactly: an analytic
+sun-volume build would be computing a different quantity from the one the froxel grid holds, and the
+two would disagree by construction, everywhere, for a reason no measurement would attribute
+correctly.
+
+`ParticipatingMediaVolume` also carries `noise_scale`, `noise_amplitude` and `noise_evolution_speed`.
+They are not in `PARTICIPATING_MEDIA_VOLUME_STRUCT`, so nothing reaches the GPU and no noise is
+applied today — but the data model plainly intends it, and an analytic scheme would die the day it is
+wired.
+
+So: sample the medium, do not try to solve it. What makes that affordable is the one property this
+structure already has and the froxel grid does not — **the world-space voxel lattice does not move**,
+which the transform spec asserts and the device measurements confirm. A lattice that does not move
+can be accumulated in place: one *jittered* sample per voxel per frame, a ping-pong pair of volumes,
+and a blend. No reprojection, because there is nothing to reproject; the effective sample count grows
+with the frame count instead of with the per-frame cost, and it converges on the true cell average of
+whatever the medium turns out to be, fade profiles and noise included. The sub-steps this commit adds
+would then drop back toward one.
+
+It is not free of conditions, and they are the usual ones for anything temporal:
+
+* the lattice is invariant to *camera* motion, not to the sun turning (the basis changes) nor to
+  `fov`/`near`/`far` changing (the extent changes) — both need a reset, and both are rare;
+* a volume that moves or animates needs the accumulation invalidated, which `SceneVolumetrics` can
+  now signal since it gained `invalidate`;
+* it buys accuracy with lag, which is the trade the froxel TAA already makes one pass downstream.
+
+What none of this fixes is the *spatial* resolution of the stored shadow: a three-unit box behind a
+2.3-unit voxel gives a blurry shadow no matter how well each voxel's content is estimated. That is
+what cascades are for, and it is a separate axis from this.
+
+## The sun volume needed cascades, and nothing else would do — measured, 2026-08-29
+
+Q-04, third pass. The section above ends by proposing temporal accumulation, and blames the
+frustum-clipped medium (Q-05) for the disagreement that kept the structure switched off. Both are
+wrong, and the measurements that show it also show what the structure actually needed. It now ships
+**on by default**, as three cascades.
+
+Everything below is against a converged reference: `chunk_integrate_optical_depth` with `STEP_COUNT`
+raised to 512, rendered by the same code path as the shipping march so the two differ in nothing but
+the step count. 1280x720, auto exposure off, 45 frames of re-convergence and a 32-frame average,
+noise floor from a repeat of the reference inside the same run — the protocol in the playground
+README. Numbers are signed mean luminance against that reference.
+
+### Where the three paths stand
+
+| viewpoint | reference | march, 16 steps | one box, 128^3 | **cascades, 3 x 96^3** |
+|---|---|---|---|---|
+| beside the fog bank, pose 1 | 62.39 | **+58.2** | +30.5 | **-1.13** |
+| beside the fog bank, pose 2 | 79.05 | **+70.5** | +37.6 | **-0.53** |
+| Inside the fog | 114.68 | +0.29 | +1.51 | +0.04 |
+| Fog bank, wide | 110.22 | +0.01 | 0.00 | -0.02 |
+| Under the island | 92.02 | +0.62 | -0.19 | -0.20 |
+| Dead overview | 100.88 | +0.12 | -0.16 | -0.08 |
+
+Floors 0.01 to 0.16. The amortized path is not a cheaper approximation of the march any more. It is
+the accurate one, by a factor of fifty at the two viewpoints where the two disagree at all, and it
+is also the cheaper one.
+
+### The error was resolution, on one axis, and the axis is not the sun's
+
+Isolating axes at pose 1, one box, four sub-steps throughout so the quadrature is held fixed. The
+sun travels along -X at 12 degrees of elevation; the volume's basis puts `u` horizontal and `v`
+within 12 degrees of vertical, and the fog bank is a slab three units thick in world Y.
+
+| grid | lateral voxel (u, v) | sun voxel | signed |
+|---|---|---|---|
+| `[128,128,128]` | 2.28, 2.28 | 2.28 | +30.5 |
+| `[128,128,256]` — sun axis x2 | 2.28, 2.28 | 1.14 | +30.3 |
+| `[256,128,128]` — u x2 | 1.14, 2.28 | 2.28 | +30.9 |
+| **`[128,256,128]` — v x2** | 2.28, **1.14** | 2.28 | **+6.1** |
+| `[128,512,128]` — v x4 | 2.28, 0.57 | 2.28 | +4.8 |
+| `[256,256,128]` | 1.14, 1.14 | 2.28 | +3.5 |
+
+Doubling the sun axis buys nothing. Doubling the *one* lateral axis that runs across the slab's
+three-unit dimension removes 80% of the error. That is a Nyquist threshold and it sits where one
+would predict: 1.52 units (a `[192,192,*]` grid) still reads +21.9, and 1.14 units reads +6.1.
+
+So the previous section's account — "it refines one axis and the box is thin in two of them", and
+"only 256^3, which refines all three, converges" — is wrong on both counts. As the sun sees it the
+box is thin in *one* axis, and `[256,256,32]` converges at exactly the memory `[128,128,128]` was
+already spending.
+
+### Prefiltering cannot fix it, and neither can temporal accumulation
+
+This is the measurement that closes the proposal the section above ends on. Replace the single
+lateral sample per sub-step with a 4x4 stratified average over the voxel's lateral footprint —
+sixteen taps, deterministic, and therefore the *converged limit* of any scheme that reaches the same
+cell average stochastically over time. Quadrature held at a constant 0.6 unit spacing.
+
+| | 1 lateral sample | 4x4 lateral |
+|---|---|---|
+| `[128,128,128]`, pose 1 | +30.5 | **+25.1** |
+| `[128,128,128]`, pose 2 | +37.5 | **+29.7** |
+| `[256,256,32]`, pose 1 | +0.35 | +4.09 |
+| `[256,256,32]`, pose 2 | +7.59 | +10.05 |
+
+Sixteen times the sampling recovers 18% of the error, and at a resolution that already resolves the
+medium it makes matters *worse*, because there it blurs a shadow that was resolved. That is what a
+prefilter is for and all it is for: it removes aliasing, not the resolution that was aliased away. A
+box filter preserves the integral of `tau` and lowers its peak, and the froxels that carry the image
+sit at the peak.
+
+**One jittered sample per voxel per frame, accumulated in place, converges on that same 4x4 column.**
+The world-space lattice really does not move — that half of the proposal is sound and its spec still
+asserts it — but what it does not move *toward* is the reference. Temporal accumulation would spend
+a settling window, a reset on every sun rotation and projection change, and an invalidation on every
+moving volume, to arrive at +25.1 instead of +30.5. It is the wrong instrument for this defect. It
+stays the right instrument for the residual per-frame noise, which is a different and much smaller
+problem — the stability table below puts that noise at 0.03 to 0.05.
+
+The literature says the same thing from the other end. Optical depth is *linear* in `sigma`, which is
+why every light-space structure in this family stores it: Fourier Opacity Mapping (Jansen & Bavoil,
+I3D 2010) projects absorption along the ray onto a Fourier basis and exponentiates on read, and its
+own framing is that it is for media whose spatial opacity variations are smooth. Deep Shadow Maps
+(Lokovic & Veach, SIGGRAPH 2000) prefilter in *transmittance* instead, because their medium is hair
+and the sub-texel variation is binary. And averaging the extinction of a heterogeneous medium to
+downsample it is known to be wrong in a specific direction — Zhao et al., "Downsampling Scattering
+Parameters for Rendering Anisotropic Media" (SIGGRAPH Asia 2016), put it as linear downsampling
+weakening the object's intrinsic shadowing structures, which is precisely the +25.1 above.
+
+### And the frustum clip is not what kept it switched off
+
+The section above attributes the *Inside the fog* disagreement to Q-05, on the strength of widening
+the field of view to 110 degrees making it vanish while raising the resolution did not. That
+inference does not hold, because **widening the field of view changes the resolution**: the box is
+sized from the frustum's bounding sphere, whose radius runs 93 units at 40 degrees, 141 at 60, 245
+at 90 and 350 at 110. Opening the lens by a factor of 2.5 coarsens every voxel by the same factor.
+The disagreement went away at 110 degrees because the box happened to land on a size that suited
+that geometry, which the next table makes plain.
+
+### Why no single box could ever have been right
+
+Pose 2, against a converged reference computed at each field of view. The cascade ratio is forced to
+1 so the three cascades coincide and the structure is exactly a single box, built by the same code
+with the same sub-steps — the only variable is the shape.
+
+| field of view | reference | one box 96^3 | one box 128^3 | one box `[256,256,32]` | 3 x 64^3 | **3 x 96^3** | 3 x 128^3 |
+|---|---|---|---|---|---|---|---|
+| 40 deg | 84.96 | **+49.97** | +6.43 | +28.09 | -0.61 | **-1.35** | -1.77 |
+| 60 deg | 79.05 | +5.87 | **+37.68** | +2.47 | +1.01 | **-0.53** | -1.14 |
+| 90 deg | 76.21 | +5.13 | +1.43 | **+38.96** | +1.29 | **+0.32** | -0.41 |
+| 110 deg | 74.94 | **+39.46** | +2.07 | **+39.46** | +5.86 | **+1.77** | +0.13 |
+
+Floor ±0.12 throughout. **Every single-box configuration measured has a field of view at which it is
+28 to 50 luminance from the truth, and which one that is moves with the resolution.** That is not
+tuning, it is arithmetic: the box has to contain the frustum under any rotation, so its side is
+proportional to `far` and to `tan(fov/2)`, while a three-unit fog slab is three units whatever the
+camera is doing. The ratio between what the structure can resolve and what it has to resolve is a
+free parameter of the *camera*, and no constant pins it.
+
+Buying the near field uniformly is not an option either. A 0.28 unit voxel over a 283 unit box is
+1024 per axis: 268 MB.
+
+### Cascades, which is what both shipped references do
+
+Three boxes, each sized from the bounding sphere of the sub-frustum out to `far / 3^(2-i)` — 13.3,
+40 and 120 units at the playground's projection, so 0.34, 1.02 and 3.07 unit voxels at 96 per axis.
+7.1 MB each, 21.2 MB in total, against the 16.8 MB the single 128^3 box was already spending.
+
+Every property the single box had transfers, because each cascade is placed by the same call with a
+different `far`: the extent is a function of the projection alone, so it cannot breathe under
+rotation, and the snapped origin makes each cascade's world-space voxel lattice the same set of
+points from frame to frame. `build_volumetrics_sun_shadow_transform.spec.js` now asserts that per
+cascade, along with the containment the seeding depends on.
+
+Enshrouded (GPC 2024) ships exactly this: "each cascade as an initial shadow value reads the upper
+cascade, so in the end we can just sample the one cascade and with one sample we get the full shadow
+volume". So does Frostbite (SIGGRAPH 2015) one level down the stack — its extinction volume is a
+three-level clip-map and its volumetric shadow maps are 32^3 3D textures storing *transmittance*,
+built at 0.04 ms for a spot light and 0.14 ms for a point light on PS4. Both cascade, and neither
+has this engine's problem of a medium that exists only inside the camera frustum.
+
+Three things about the construction are decisions rather than transcription:
+
+- **The seed is one fetch of the outer cascade at the world position where this column enters this
+  box**, not at the box centre and not a re-march of the approach. Everything between the sun and
+  that plane has already been integrated out there. It is what makes an inner cascade a *refinement*
+  of the outer rather than a truncation of the medium — without it every near-field froxel would be
+  lit as if the fog behind it did not exist, and the volume would still come out perfectly smooth,
+  with the correct slope, and wrong.
+- **A texture per cascade, not one texture with the cascades stacked along w.** Stacking puts a
+  pass's own output and its input in the same texture, which WebGPU rejects: a subresource cannot be
+  bound as writable storage and as a sampled texture at once, and a 3D texture has no subresource
+  finer than the whole thing to split it on.
+- **Selection is on view depth, with a blend band over the last 10% of each cascade's range.** The
+  two cascades do not agree where they meet — one is more accurate, which is the reason there are
+  two — so a hard switch is a ring at a fixed view depth, and the 0.95-blend froxel TAA smears such
+  an edge rather than removing it. Depth also makes the branch uniform: the lighting pass dispatches
+  one froxel slice per workgroup in z, and a slice is a surface of constant depth.
+
+The boxes are **cubic**, and that too is measured rather than assumed. `[256,256,32]` is tempting —
+at 60 degrees it beats `[128,128,128]` by an order of magnitude at identical memory, for the good
+reason that this scene's medium is eight times finer across the sun than along it. The table above
+is what that costs at other fields of view. Two axes, two Nyquist limits, and which one is starved
+is a property of the fog and the sun's elevation rather than of the method.
+
+The sub-step count is per cascade — 4, 2, 2 from the outermost inward — so that the *world-space
+sample spacing* is held constant across cascades rather than the count per voxel. It has to be even:
+the build stores its running integral at sub-step `count / 2`, which is the voxel's centre only when
+the halves are equal, and a count of one stores it at the near face, half a slab of missing shadow
+on whichever cascade drew the short straw.
+
+### Cost
+
+Per pass, `WORKLOAD` capture decoded in the page — `measure.js` grew a `profile` for it, so this no
+longer needs a downloaded `.sgpt` — medians over interleaved rounds at pose 1.
+
+| 1920x1080 | build | build lighting | total |
+|---|---|---|---|
+| march, 16 steps | 0.010 | 0.521 | **0.531** |
+| cascades 3 x 64^3 | 0.120 | 0.282 | **0.422** |
+| cascades 3 x 96^3 | 0.187 | 0.190 | **0.370** |
+
+| 3840x2160 | build | build lighting | total |
+|---|---|---|---|
+| march, 16 steps | 0.011 | 1.503 | **1.515** |
+| cascades 3 x 64^3 | 0.131 | 0.866 | **0.997** |
+| cascades 3 x 96^3 | 0.188 | 0.617 | **0.805** |
+
+The single box with four sub-steps was break-even at 1080p; three cascades are 0.16 ms *ahead* of
+the march there and 0.71 ahead at 2160p. Not a paradox: the build is bound by the length of its
+serial dependency chain rather than by its sample count, so splitting one 128-slice column into
+three 96-slice ones with three times as many columns is a better shape for the machine even at 1.7x
+the samples. Measured directly on the single box, `[128,128,128]` and `[256,256,32]` carry the same
+8.4M samples and cost 0.094 ms and 0.032 ms.
+
+One caveat in those tables. The lighting pass does the same work for 64^3 and 96^3 — one fetch
+either way — and reads 0.282 against 0.190. Every round put 64^3 immediately after the march, so
+read that gap as ordering within the round rather than as a property of the change.
+
+### Temporal stability
+
+Static camera, 24 frames, largest single-frame step in mean luminance:
+
+| | pose 1 | pose 2 | Inside the fog |
+|---|---|---|---|
+| march (512 steps) | 0.012 | 0.011 | 0.004 |
+| cascades 3 x 96^3 | 0.051 | 0.033 | 0.003 |
+| cascades 3 x 64^3 | 0.023 | 0.049 | 0.004 |
+| *one box, one sample per voxel — the reported strobe* | *0.595* | *0.636* | — |
+
+An order of magnitude below the pulse that was reported as visible, and three to four times the
+march's own floor.
+
+Six scripted motions — yaw, pitch, forward, backward, strafe, and all three together — 90 frames of
+motion plus 40 of hold, at two viewpoints, comparing the cascades against the march on flicker while
+moving, on flicker and drift while settling, and on the converged image after the motion against the
+converged image from a standing start at the same pose. At pose 1:
+
+| motion | settling flicker, cascades / march | flown vs still, cascades / march |
+|---|---|---|
+| yaw | 0.011 / 0.008 | +0.056 / +0.004 |
+| pitch | 0.005 / 0.003 | -0.007 / +0.013 |
+| forward | 0.043 / 0.042 | +0.037 / +0.013 |
+| backward | 0.007 / 0.008 | -0.047 / -0.043 |
+| strafe | 0.022 / 0.022 | +0.024 / +0.016 |
+| combined | 0.012 / 0.013 | +0.009 / -0.016 |
+
+At *Inside the fog* the two agree to within 0.01 on every motion and every statistic. The forward
+and backward runs are the ones to look at: they sweep the cascade boundaries eight units through the
+fog, which is the one instability this change could have introduced, and they read identically to
+the march. The **+3.8 pop** the section above reports around 8 degrees into a yaw at that viewpoint
+is gone — the largest single-frame step across that motion is 0.233 for the cascades against 0.235
+for the march.
+
+### What is left
+
+- **Q-05 still stands, and is now the largest defect here.** The medium exists only inside the camera
+  frustum, so fog outside it casts no shadow. Both paths have that, so it appears nowhere in the
+  tables above: every one of them compares two readings of the same clipped medium.
+- A systematic **-1.2 luminance** at the higher resolutions, converging rather than shrinking — 64^3
+  reads -0.32 at pose 1, 96^3 -1.13, 112^3 -1.23. Small, and part of it is the reference's own bias
+  (the march's first sample carries 0.9 of a step's weight), but it is not noise.
+- The cascade count is capped at 4 because the per-cascade scalars are packed into a `vec4f`. Past
+  that the metadata wants a real array, whose uniform-space stride is 16 bytes per `f32`.
+- The build is latency-bound, not bandwidth-bound. If it ever has to be cheaper, the lever is the
+  serial chain — fewer slices per cascade, or a cooperative scan — and not fewer samples.
+
+## The lighting workgroup, and a premise that did not survive contact — measured, 2026-08-30
+
+S-01. The pass declared `@workgroup_size(16,16)`, dispatched one workgroup per froxel z slice. The
+study's argument for reshaping it: a froxel is `TILE_SIZE` = 8 pixels, so a 16x16 group covers
+128x128 pixels — sixteen separate 32-pixel light clusters — and every lane of a wave can be walking
+a different light list, which is the worst case for the divergent light-record reads in the point
+and spot loops and for shadow atlas tile locality. 4x4 in xy is exactly one cluster tile.
+
+Mean over the build lighting span:
+
+| shape | invocations | clusters spanned | mean |
+|---|---|---|---|
+| 16x16x1 | 256 | 16 in xy | **247 us** |
+| 8x8x1 | 64 | 4 in xy | 368 us |
+| 4x4x4 | 64 | 1 in xy, 4 in z | 386 us |
+
+**The premise was false.** The shape spanning the most clusters is the fastest by 50%, so
+cross-cluster divergence is not what governs this pass's time — cutting the group's cluster
+footprint from sixteen tiles to one made it *slower*, and the xy alignment the whole finding rested
+on bought nothing. Whatever dominates here, it is group size, not light-list coherence.
+
+**Spanning z is separately wrong, and that part holds.** At equal occupancy, 4x4x4 is slower than
+8x8x1. Lights are binned into 3D clusters and the largest distance between neighbouring clusters is
+along depth, so a group that spans z spans the most unrelated light lists — the axis the study
+picked to grow was the one axis to leave alone. The reshape is 2D for the same reason the pass was
+2D to begin with.
+
+Shipping **8x8x1**: 64 invocations, one wave64 or two warps, flat in z. That is 121 us of measured
+cost against the original, paid deliberately, and the reason is **portability**.
+
+Both numbers above were taken on an RTX 4090. Its register file is unusually large, and a 256-invocation
+group winning there says more about that part than about the shape: the wider the group, the more
+registers it needs live at once, and a 4090 has the headroom to keep 256 of them resident where a
+smaller part would drop occupancy instead. AMD hardware in particular does better with smaller
+groups. So 16x16x1's 247 us is a local result, not a general one, and shipping the shape that wins
+on one machine would be tuning the engine to this desk.
+
+Do not read the table as an instruction to put 16x16x1 back. That would need measurements from more
+than one vendor, and it is a different question from the one measured here.
+
+The shape is now `VOLUMETRICS_LIGHTING_WORKGROUP_RESOLUTION`, read by both the `@workgroup_size` and
+the dispatch, following the sun shadow build. Dead `VOLUMETRICS_WORKGROUP_RESOLUTION` (`[8, 8, 4]`,
+zero importers, matching one pass's literal by coincidence) is deleted.
+
+### Regrouping cannot change the output, and did not
+
+Every invocation computes from `global_invocation_id` alone — no shared memory, no subgroup op, no
+cross-invocation state — so the question reduces to which ids get dispatched. Driven through the
+emulator over both id sets, `tLighting` compared equal byte for byte at grids with a partial group
+on one axis, on all three, and on none, with no voxel left unwritten; coverage at 1080p's 240x135x64
+is exactly once each. That harness was throwaway — it compares against shapes that no longer exist —
+and what stayed is a test pinning `@workgroup_size` to the constant the dispatch divides by.
+
+Two things worth keeping from building its negative controls:
+
+- Under-dispatching fails loudly: a stale divisor drops froxels and the volume comes back holed.
+- **Over-dispatching is invisible.** A `group_count_z` left at the slice count under a 4-deep group
+  still visits every voxel exactly once — `gz * 4 + lz` stays a bijection — so the volume is
+  bit-identical while four times the groups launch to bounds-check and return. Only an assertion
+  about the dispatch being tight catches it.
+
+## Hoisting the local-light shadow test above the march — measured and NOT shipped, 2026-08-30
+
+F-01 and F-03, together, because separately neither is worth doing. Both local-light loops in
+`shader_volumetrics_build_lighting` ran march -> multiscatter -> shadow:
+
+```
+let optical_depth = integrate_optical_depth(shadow_ray);   // up to 16 filtered 3D fetches
+let ms = calculate_multiscattering(...);                   // 6 octaves, pow + exp per octave
+let shadow_term = volumetrics_point_light_shadow(...);     // 1 textureLoad, returns 0 or 1
+inScatteringSum += shadow_term * ms * direct_light.color;
+```
+
+The shadow term is binary by construction — `chunk_volumetrics_local_light_shadow` takes one nearest
+texel with no filter kernel and ends in a `select` between 0.0 and 1.0 — so a zero throws away
+everything above it. Testing it first and `continue`ing on zero skips that work (F-01). And
+`volumetrics_point_light_shadow(database, index, position)` re-read the record
+`get_point_light_info_by_index` had just unmarshalled, *before* its `CASTS_SHADOW_BIT` early-out
+could fire, so the reorder alone would have added a storage read for every non-shadowing light;
+passing the struct instead removes the duplicate and makes the flag test free (F-03).
+
+**The reorder is exact, and that was verified rather than argued.** Both orderings were driven
+through the WGSL emulator over thirteen fixtures — every exit of both loops, plus a case with real
+per-froxel extinction where the old order computed a genuine optical depth and multiscatter and then
+multiplied the pair by zero — and `tLighting` compared **byte for byte**, on the raw bits so that
+`+0`/`-0` and any NaN payload would count as a difference. It is identical everywhere. NaN is the one
+input for which the two are not equivalent (`0 * NaN` propagates, a skipped term does not), so the
+spec fails on any non-finite value in its own right instead of folding it into the comparison.
+
+**It is not faster.** Median of the `Volumetrics / build lighting` span over 18 interleaved rounds at
+3840x2160, ABBA-ordered so neither arm systematically takes the warm half of a round, 48 recorded
+frames per capture after a 40-frame ramp:
+
+| arm | median (ms) |
+|---|---|
+| shadow test first (F-01/F-03) | 1.3573 |
+| march first (shipping) | 1.3471 |
+| **median paired difference** | **+0.0108** |
+
+and the same protocol run with the *same build on both arms*, which is what that number has to beat:
+
+| | median paired difference | median abs difference |
+|---|---|---|
+| A/B, 18 rounds | +0.0108 | 0.0998 |
+| **A/A floor, 10 rounds** | **+0.0092** | 0.0456 |
+
+The measured effect and the noise floor agree to 1.6 us. There is no signal, and the sign is the
+wrong one anyway.
+
+**Why there was nothing to win, which is the part worth keeping.** The local-light loops are not a
+measurable part of this pass in this scene at all. Removing all 130 shadow-casting point lights from
+the playground scene and re-measuring:
+
+| | median (ms) |
+|---|---|
+| 130 shadow-casting point lights | 1.2585 |
+| the same scene with all of them removed | 1.3343 |
+
+Deleting the entire workload the finding proposed to optimize does not make the pass faster — it
+reads a shade slower, which is to say the difference is noise. Whatever the 1.3 ms is spent on, it is
+the per-froxel work outside those loops: the STBN fetch, the two participating-media samples, the
+cluster lookup, and the directional loop's cascade fetch. That also retires the premise the finding
+rested on, the same way S-01's did: 130 shadow-casting lights in the scene does not mean 130 lights
+in the cluster any froxel actually reads.
+
+So this joins Q-01's "the cost is nearly nothing" as a cost claim the profiler refused. Not shipped;
+the tree keeps the march-first order.
+
+What would have to change before it is worth revisiting: a scene where the froxel volume genuinely
+overlaps many clustered lights, shown by that removal test moving the number. Reach for the removal
+test *first* next time — it is three captures and it would have settled this before any code was
+written.
+
+Two things did survive, both about the shipping code rather than the change:
+
+- `shader_volumetrics_build_lighting_local_shadow.spec.js` now covers the exits it did not: a light
+  over an atlas region that was never rendered (`stored == 0`, must not occlude), a froxel behind a
+  spot's apex (`clip_light.w <= 0`), that the optical-depth march still runs and still attenuates
+  when the shadow test passes, and that no NaN or infinity reaches `tLighting` in any fixture. The
+  apex case needs a deliberately inconsistent fixture and says so: in the shipping arrangement a
+  froxel behind the apex is also outside the cone, so the range cull `continue`s before the shadow
+  function is reached, and the branch has to be built rather than found.
+
+- The dev server no longer hot-reloads (`server.hmr: false`). A reload drops the WebGPU device and
+  resets the temporal accumulation, and an edit anywhere in the module graph — including one made by
+  someone else working in the tree at the same time, which is exactly what happened here — destroys
+  an interleaved A/B mid-run.
+
+Measurement conditions, because one of them is unusual: RTX 4090, canvas 1280x720 at pixel ratio 3.
+The pass was confirmed resolution-bound first (0.4618 ms at 1280x720 rising to 1.878 ms at 3840x2160)
+rather than presentation-throttled. Another session was building and running GPU work on the same
+machine throughout, which put occasional 2x outliers in both arms; medians absorb them, and the A/A
+floor was taken under the same conditions so it prices them in.
+
+## The participating-media coverage skip — counted and NOT shipped, 2026-08-30
+
+`shader_volumetrics_build_participating_media` carried a TODO: if a froxel is entirely inside a
+volume, coverage is 1.0 and `frustum_unit_box_coverage` need not run. The TODO proposed getting there
+by replacing `aabb3_intersects_frustum` with something that returns an intersection *degree*.
+
+### The degree answers the other question
+
+`aabb3_intersects_frustum(unit_bounds, local_frustum)` classifies the **volume box** against the
+**froxel's planes**, and `aabb3_intersects_frustum_degree` already returns 0/1/2 for exactly that.
+Its `2` means the box is inside the froxel — the arrangement where the froxel is *larger* than the
+volume, where coverage is a small fraction. Reading it as "coverage is 1.0" would flood the far field
+with fog, which `volumetrics_froxel_containment.spec.js` pins as a test.
+
+What coverage of 1.0 needs is the dual: **froxel ⊆ box**. Both bodies are convex, so it holds exactly
+when the froxel's 8 vertices are inside the box, and `frustum_to_corners` produces the same points
+`frustum_sample_point` reaches at `uvw ∈ {0,1}³` — the sign flips in `plane_convex_intersection`
+cancel, so a plane and its negation give the same corner. The test is exact, not conservative, and
+the same bound gives a second exact skip: if the froxel clears `fade_distance` from every face in
+world units, all three of `compute_volume_fade_factor`'s smoothsteps saturate and the fade is 1.0.
+
+### It is exact and it still loses
+
+Corners cost 8 `plane_convex_intersection` — 3 crosses, a dot and a divide each — which is what
+`frustum_unit_box_coverage` spends on its 4 rays. Deriving them per volume pays for precisely the
+work it skips, so the only arrangement that can win builds them once per froxel in world space and
+maps them into each volume with a matrix multiply.
+
+Hit rates over the playground's six volumes at 240x135x64 (every 4th column in X and Y, every slice
+in Z, froxel extents kept at the true 1/240 and 1/135):
+
+| pose | froxels touching a volume | survivors per froxel | contained | fade saturated |
+|---|---|---|---|---|
+| overview (default) | 100.0% | 1.223 | 7.0% | 3.3% |
+| fog bank, wide | 91.2% | 0.912 | 8.1% | 4.1% |
+| inside the fog | 97.6% | 1.565 | 33.2% | 27.2% |
+
+Per froxel, in three-plane intersections:
+
+| pose | paid | saved | |
+|---|---|---|---|
+| overview | 8.00 | 0.77 | **10.4x loss** |
+| fog bank | 8.00 | 0.67 | **12.0x loss** |
+| inside the fog | 8.00 | 5.00 | **1.6x loss** |
+
+Two refinements do not rescue it. Building the corners **lazily**, on the first volume that survives
+the plane test, saves nothing: the 400x20x400 cloud deck is a huge thin slab that defeats the
+conservative frustum/AABB test almost everywhere, so 91-100% of froxels touch a volume anyway.
+Gating on a **1-intersection necessary condition** — the froxel's own centre must be inside the box,
+or containment is impossible — is very tight (centre-inside is 8.7% against contained's 7.0%) and
+still loses: 2.7x, 2.5x and 1.3x on the three poses.
+
+So the geometry is right and the arithmetic is against it, at every pose measured, including the one
+where a third of froxels qualify. Not shipped. `volumetrics_froxel_containment.spec.js` keeps the
+proof — containment implies coverage of exactly 1.0, and the fade core implies a fade of exactly
+1.0 — alongside `chunk_aabb3_contains_aabb3` and `chunk_aabb3_from_transformed_corners`, so if the
+grid, the volume mix or the estimator's cost moves, restoring the early-out is a few lines rather
+than a rediscovery.
+
+This one was settled by counting rather than by the profiler, which is unusual here. The hit rate is
+a property of the scene's geometry and not of the device, and the cost ratio it implies is 2.5x to
+12x on the two poses that matter — far outside anything a capture would overturn. A GPU A/B is the
+confirmation, not the decision.
+
+### What did ship
+
+The line above the TODO was doing real redundant work. `frustum_transform_m4(froxel_frustum,
+volume.transform_inverse)` derives its plane matrix as `transpose(mat4_inverse(transform))`, so
+handing it `transform_inverse` made it compute `transpose(mat4_inverse(transform_inverse))` — which
+is `transpose(volume.transform)`, a matrix already resident in the struct. Every froxel/volume pair
+was running the 85-line generic cofactor `mat4_inverse` to recover a matrix it had been given: at
+1080p with six volumes, 12.4M of them per frame.
+
+`chunk_frustum_transform_plane_matrix` is that function with the plane matrix passed in, and
+`frustum_transform_m4` is now the wrapper that derives one. The shader calls the former with
+`transpose(volume.transform)`. Strictly less work, and marginally more accurate for dropping an
+inverse round-trip. It is a full 4x4, not a 3x3 normal basis: the last row carries the translation,
+which is what supplies each transformed plane's distance term, and
+`chunk_frustum_transform_plane_matrix.spec.js` asserts both that and the equality with the old route.
+
+`transpose` was missing from the WGSL emulator's language core, which is why `frustum_transform_m4`
+had never been exercised there; it is implemented now for the square matrix sizes, on the same
+footing as `determinant`.