@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/path_tracer/PATH_TRACED_MEDIA_PLAN_2026_10_02.md

@@ -0,0 +1,520 @@
+# Participating media in the path tracer: design brief
+
+Revision 3, 2026-10-02, against `b0bb299a7`. Paths are relative to `packages/meep-engine/src/shade/renderer/` unless
+they start with `src/`.
+
+**Decisions, settled 2026-10-02 (§8):**
+
+| Fork | Decision |
+|---|---|
+| F1 | IOR on the boundary material (`ior_factor`) |
+| F2 | Without a medium, transmission stays thin-walled |
+| F3 | **(c) Full manifold NEE** with the curvature Jacobian, because waves are coming. Runtime cost is a design constraint (§3.5) |
+| F4 | Later, one shared density chunk |
+| F5 | Shared chunks. Draine already exists and is reused, not rewritten |
+| F6 | Fog volumes become a table in the scene's `GPUDatabase` |
+| F7 | The bakes gain media |
+| F8 | D1–D3 are fixed in separate sessions. Stage 2, which extends the resident material table, starts after D1/D2 land. Stages 1 and 3 are independent of them |
+
+**Status, 2026-10-03.** Stages 0–5 have landed, and an adversarial review after them (below). Stage 6 (glTF volume
+import) is optional.
+
+| Stage | Commits |
+|---|---|
+| 0 | `54d98588a` (D1, D2), `9c2c65836` (D3), in their own sessions |
+| 1 | `6bedc1393` Fresnel, `d62cf6000` Draine sampler, `92e7267da` Fournier–Forand |
+| 2 | `a7cae0ff3` medium model, `ff1bdd259` material medium and resident media, `886a83b45` fog volumes in the scene database (F6) |
+| 3 | `6ce0819e7` transport chunks |
+| 4 | the tracer, the consumers and `playground/path_traced_media/` (§5, §6) |
+| 5 | manifold NEE through one interface (`path_tracer/shader/manifold/`), the water checks, the wave pool |
+
+What stage 5 measured:
+
+- **Through flat water the connection meets the closed form**: the sun at 30° and 60° to 0.04%, a lamp overhead to
+  0.01%, ratios against the same tile dry (§5 check 3, as a small tile so that the floor's light does not come back).
+  Two things had to come out of the check first: the tile's rough diffuse lobe (the sun arrives at 60° dry and 40° wet)
+  and the default normal map's lean — `Color(0.5, 0.5, 1)` in eight bits decodes to a normal 0.3° off the
+  geometric one, +0.38% with the sun from +x and −0.30% from −x; two mirrored suns cancel it. The lean is an engine
+  defect of its own, flagged separately.
+- **The tolerance is 1e-4, not 1e-5.** On the device, for a lamp straight over the receiver, f32 stalled the residual
+  just above 1e-5, and every connection was given up — 26% of the lamp's light lost. In the emulator the same solve
+  reached 3e-6 to 1.3e-5. (Not, as first written here, because the half vector nearly cancels: n_light wi + n_receiver
+  wo is 0.33 long there.) 1e-4 rad moves the vertex a tenth of a millimetre at a metre. Far from the origin the
+  tolerance now widens with what f32 resolves (review, below).
+- **Cost:** in the wave pool, about 11 ms a 256×256 tile with connections and 5–7 ms without — a connection is 2–3
+  Newton casts and two legs where a straight sample is one shadow ray. Limits: 8 steps a connection, 4 connections a
+  path. The tracer reports no per-connection counters (§3.5 planned them); the frame time is the measure.
+- **As built:** the Jacobian of the constraint is by forward differences within the triangle's plane, where the
+  interpolated normal is affine, rather than analytic; the beam's weight is carried by ray differentials (Igehy) from
+  the light across the refraction — curvature from the interpolated normal's derivative — to the receiver, which gives
+  the generalized geometric term without the manifold's block matrices. Both are pinned against tracing in f64.
+
+**Adversarial review, 2026-10-03.** Three reviewers read the work against the code, the emulator and the device. What
+they found, each fix pinned by a spec or a device check that failed before it:
+
+- **Fixed — media and optics.** A path entering a medium of lower priority than the one it was in put it on top of
+  its stack, so the glass-to-water interface of water modelled into a glass wall vanished; the stack now inserts by
+  priority. The origin probe counted media as a set, so a camera inside two overlapping meshes of one water thought
+  itself in air on leaving one; it counts meshes, as the path does. The Draine lobe's Henyey-Greenstein denominator
+  cancelled in f32 — Inf at g 0.9999, 10% low at 0.999 — and phases accepted parameters the GPU or the sampler cannot
+  hold (g rounding to one, Draine alpha < 0, Fournier-Forand backscatter the solve does not reach, a lobe count
+  reached by editing a lobe). A participating-media volume scaled to nothing put the whole world inside it.
+- **Fixed — volumes.** Past 8 pieces a flight took the rest of its ray as one piece whose null collisions grow as the
+  square of the volumes left, and the 64-collision limit cut it: ten separate fog volumes on a line of sight came out
+  dark, twenty black. 64 pieces now; past 32 volumes the cliff remains, stated at the constant.
+- **Fixed — manifold NEE.** Full Newton steps diverged from the straight seed once the sun was about 60° from overhead
+  (57° through glass): a step is now halved in the triangle's plane until the constraint falls, and again if it does
+  not fall on the surface — through flat water to 85°, in 3–7 casts. The Jacobian's difference step was a fraction of
+  the triangle's first edge, wrong for a receiver close under a large triangle and below f32 far from the origin; it
+  is a fraction of the receiver's distance, with an f32 floor, and the tolerance widens with what f32 resolves. A
+  probe meeting any other mesh — an index-matched box in the water — gave the connection up; probes pass such
+  surfaces, within 16 casts a connection. A sphere light's beam and distance window are taken from its centre, as
+  straight NEE takes them.
+- **Fixed — the tracer.** A surface inside a medium chose its light, and gated its shadow ray, by the straight line
+  to it, so an underwater slope facing away from a low sun never saw its refracted light; it now chooses with no
+  receiver cosine and looks for the interface along its horizon. A surface inside a medium reflected as if in air
+  (§3.3 promised the relative index); it reflects by the ratio. And, older than this work: the specular bounce's
+  weight lost the NoL·NoV term of G2 / G1, so every smooth reflection the path tracer followed carried half its light.
+- **New checks:** the sun at 75° and 85°, an underwater slope, an index-matched box in the way, overlapping water
+  around the camera, a glass slab at 45°, a smooth black tile in air and under water, and a sunlit scattering
+  half-space against Chandrasekhar's H-function — the first check of light reaching scattering points.
+- **The checks' noise is the run's own.** A rectangle's standard error came from the spread of its pixels, which
+  counts structure across it — a dark arc where the answer is flat — as noise, widening the tolerance for exactly the
+  error it should find. It now comes from the accumulation read at half the frames and at the end, and a run that
+  accumulated fewer samples than frames fails. With it, the numbers the allowances rested on were stale: the clear
+  sphere's outline holds 0.1% on every side, not 1.4% (its 2% allowance is gone); the scattering glass sphere is 0.5%
+  low in its middle and up to 0.73% at its outline, not 0.27% and 0.4% (still within its 0.6% beyond the noise).
+  Neither moved with the review's changes: the stage-5 code reads the same.
+- **Stated, not fixed.** Four manifold connections a path: light behind an interface reaches no scattering past the
+  fourth (estimated 18–22% of the sunlight scattered in the playground's milky sphere, 31–55% in deep water of albedo
+  0.9–0.99), since every light is reached only by NEE. A spot's cone and a surface outside every medium lit through an
+  interface by a light in one are still judged along the straight line. A shadow ray whose channels' extinctions are
+  20 times apart is cut whole when its strongest channel is. Interfaces are smooth whatever the material's roughness
+  (§3.3's GGX BTDF is not built), alpha on a medium-bounding surface is ignored (§3.3's holes are not built), and
+  `serialize_scene` keeps a material's index but neither its medium nor the scene's volumes.
+
+What stage 4 measured, on an RTX 4090 through headless Chrome, 256×256:
+
+- All nine checks of the playground pass against their closed forms (§5, tier 4).
+- **Every loop has a fixed limit (superseding the next bullet).** The scene to look at took 95 ms a 256×256 tile,
+  long enough to stall the desktop: every table walk read the tables' whole page capacity (4,096 pages, twice per
+  light sample, and once per segment, collision and shadow segment for the volumes), and the limits were safety nets
+  in the hundreds and thousands. Walks now stop at the pages in use — lights are packed from row 0, the volume table
+  is rewritten whole, so the page headers' live counts are the counts — and the limits are 32 scattering events,
+  16 interface events (4 smooth), 8 pass-throughs, 8 probe hits, 8 shadow hits from a scattering point (32 from a
+  surface, as before), 64 collisions and 8 volume pieces a flight. 11 ms a tile; the checks 1.2–4 ms. Cost of the
+  limits: 1.4% at the tessellated outline, 0.3% of the scattering glass sphere (the interface limit).
+- **The interface limit is 64, not 16.** A scattering sphere at n = 1.333 traps light by total internal reflection
+  (a sphere preserves the angle of incidence, so a ray past the critical angle circles until it scatters). The white
+  furnace for it measured 0.60% low at 16 events, 0.13% at 64 and 0.10% at 256, at 48, 60 and 75 ms a frame. At 4096
+  the device was lost: an uncapped path runs past the TDR limit.
+- **What stays below 0.1% is not the stack or the interface.** A clear glass sphere closes exactly in its middle;
+  an index-matched scattering sphere or box closes to 1e-4–3e-4, a few standard errors, the same with Henyey-Greenstein
+  lobes alone.
+- **Tessellation traps light by total internal reflection.** The first furnace regions missed the clear sphere's
+  outline; covering it showed a dark arc on one side, 4.4% low, unchanged at a limit of 256. Light entering near the
+  outline refracts to just under the critical angle, the interpolated normals tip it over at the far side and then
+  hold its angle, so it circles indefinitely. Past 8 interface events a path now takes them about the triangle's own
+  normal (`PATH_INTERFACE_SMOOTH_EVENT_LIMIT`), which lets it out: 1.1% low and 13 ms a frame against 50. A shading
+  normal that would turn an event back across the triangle falls back to the triangle's normal too
+  (`chunk_medium_interface`). Part of the scattering sphere's loss above was this.
+- Two consumers do not compile on the device, for reasons that predate this work: the lightmap viz bakes read
+  `mesh.lightmap_uvs`, which `MESH_INSTANCE_METADATA_STRUCT` does not have, and the deprecated LPV trace declares its
+  own ray-tracing group without `meshlet_data`.
+
+What changed from revision 1:
+
+- glTF no longer argues any decision; volume import is an optional last stage.
+- A survey of the engine replaced assumptions with a reuse map (§1), which found three constraints the first
+  revision missed:
+  - The path tracer's core chunk is shared with the Brick4 and lightmap bakes, and those are at the storage-buffer
+    and bind-group limits.
+  - The resident material table has two defects the medium index would inherit.
+  - One live bake shader cannot link as it stands.
+- The forks are now eight (§8).
+
+## 0. Summary
+
+The accumulating path tracer gets one volume system that water, fog, clouds and glass all use:
+
+1. **A medium is data**: RGB absorption `σ_a` (m⁻¹), a priority, and up to four scattering lobes, each an RGB
+   scattering coefficient `σ_s` (m⁻¹) with a phase function. Water is a molecular lobe plus a Fournier–Forand lobe.
+   Fog is one HG lobe. Glass has no lobes.
+2. **Two kinds of boundary, set by the physics.** Where the index of refraction jumps there is a surface: a closed
+   mesh whose material references a medium, giving a dielectric interface (exact Fresnel, refraction, TIR, n² law).
+   Where it does not jump there is no surface event: a fog volume (`ParticipatingMediaVolume`) contributes by position.
+3. **One overlap rule.** A priority stack picks the one interface-bounded medium at each point. Fog volumes add on top,
+   as the froxel builder already adds them.
+4. **One transport.** Free flight uses the null-scattering formulation with per-channel majorants and hero-channel MIS,
+   so homogeneous media take no null collisions. Shadow rays use residual ratio tracking, which is exact in homogeneous
+   media.
+5. **Everything that calls `render_trace_path` gets media**: the reference tracer and the Brick4 and lightmap bakes,
+   through one chunk, with no second tracer.
+
+Water is declared lobe by lobe through the same API as everything else; the framework contains no water code.
+
+## 1. What exists, and what it means for this work
+
+### 1.1 Reuse map
+
+| Need | Existing code | Use |
+|---|---|---|
+| Analytic phase evaluation | `phase_draine(cos, g, α)` (`shader/chunk/atmosphere/phase/jd/chunk_phase_draine.js`) covers HG (α=0), Cornette–Shanks (α=1), Rayleigh (g=0, α=1) and the molecular water phase (g=0, α=k) | As-is, as the one evaluator. It also sidesteps the `fn phase_mie` collision between the HG and CS chunks. No spec exists: normalization specs added |
+| Phase sampling | `sample_draine_cos` (`jd/chunk_sample_draine_cos.js`), singular at g=0 and α=0, no consumer, no spec | Wrapped: HG inverse at α=0 (new, a few lines); the g=0 cubic by Cardano on `cbrt` (`shader/chunk/math/chunk_cbrt.js`) |
+| Jendersie–d'Eon cloud/fog phase | `get_fog_params_jendersie_deon` (JS) | Encodes on the CPU into two Draine lobes. The LUT texture (`mie_phase_lookup_texture`, no importer) is not needed |
+| Particle optics for presets | `MIE_PARTICLES_STANDARD_PRECOMPUTED` (20 particles) through `VolumetricsParticleSpec.fromMeep`; `compute_mie_particle_properties_rgb` (D65 × CIE spectral integration, returns the host medium's absorption as `extinction_intercept`); `ri_water`, `ri_brine` | Presets come from these rather than invented numbers. The playground's pure-water absorption is `ri_water` through the RGB integrator. Calibrated water RGB stays the water line's fitting tool |
+| Direction from (cos θ, φ) | `build_orthonormal_matrix_n`, `spherical_direction` | As-is |
+| Isotropic direction | `uniform_sample_cone(uv, -1)` | As-is |
+| Microfacet pieces | `D_GGX`, `V_GGX_SmithCorrelated`, `sample_ggx_vndf_hemisphere` (returns H; the tracer's `sample_reflection_vector` hides it), `BSDF_ROUGHNESS_MINIMUM` | The dielectric BTDF is composed from these. The transmission pdf's half-vector Jacobian is new |
+| Refraction | WGSL `refract` (the emulator implements it, TIR → zero vector) | As-is |
+| F0 at a relative IOR | `dielectric_specular_color(ior, …)`: `((n−1)/(n+1))²` holds for relative n | Called with the relative IOR |
+| Fog volume data | `GPUSceneVolumetrics` table and `PARTICIPATING_MEDIA_VOLUME_STRUCT`; `far_sample_volumes` in `volumetrics/shader_volumetrics_build_scattering_lut.js` is a pointwise lookup (inverse transform, unit box, density, no fade) | Same record. How the tracer reaches it is fork F6 |
+| Ray vs box interval | `aabb3_slab_span` (NaN-guarded slab); no oriented-box interval chunk exists | New small chunk on top of it |
+| RNG | `random()` returns [0, 1 − 2⁻²⁴], so `log(1 − random())` is finite | As-is |
+| Russian roulette | `russian_roulette` | As-is, fed `β / mean(r_u)` |
+| Inside test | `scene_point_query_volume_sign` answers "inside any geometry" | Not usable for "inside which medium". The stack uses a probe ray (§3.2) |
+| Statistics, KS, quadrature | None in `core/`; spec-local copies only | Written into each spec that needs them (no shared helper module ships) |
+| CPU mirror of the shader RNG | `pcg_next`, `u32_to_unit_f32` in `particles/vm/ParticleVMReference.js` | CPU oracles that replay the shader's stream |
+| Furnace precedent | CPU tracer `src/engine/graphics/sh3/path_tracer/PathTracer.spec.js` (Lambert only, no media) | Same idea, on the GPU tracer |
+| Constant environment | `make_flat_environment` / `use_flat_environment` (`src/shade/playground/skinned_blas_refit/flat_environment.js`) | Device furnace |
+| Tracer readback | `render_and_read` (`src/shade/playground/skinned_blas_refit/diff_traced_against_rasterized.js`) | Device checks |
+| Spec patterns | Emulator library mode for pure chunks; storage-budget assertion (`geometry/virtual/runtime/cut/vgeo_cut_shaders.compile.spec.js`); software-device view recipe (`volumetrics/gi/graph_build_froxel_gi.spec.js`); resident-row readback (`src/engine/graphics3/terrain/TERRAIN_MATERIAL_TEMPLATE.spec.js`) | Followed |
+
+**Searched for and absent, so new here:**
+
+- Exact dielectric Fresnel, in WGSL or JS.
+- Any BTDF, relative-IOR handling or TIR logic.
+- The Fournier–Forand and molecular water phases.
+- An HG sampler.
+- Any tracking estimator: delta, ratio or residual ratio tracking, majorants, free-flight sampling.
+- A medium stack or nested dielectrics.
+- Light selection without a normal: passing a zero normal yields pdf 0, so NEE silently skips.
+- Refracted shadow connections.
+- Any medium data on materials.
+
+`chunk_screen_space_newton_ray` is screen-space (fixed ray against the G-buffer). It cannot connect a light through an
+interface; only its plane helpers are reusable.
+
+### 1.2 Constraints the design has to respect
+
+| Fact (verified in code) | Consequence |
+|---|---|
+| `render_trace_path` has six importers. Two are live bakes: Brick4 probe bake (`global_illumination/brick4/gpu/bake/shader_brick4_bake_probes.js`) and the lightmap bake (`lightmap/bake/shader_lightmap_viz_to_sh.js`, used by `GPULightMap`). The other four are the accumulating tracer, the unimported `graph_path_trace_scene`, the unimported `shader_lightmap_viz_to_irradiance_flat`, and a deprecated LPV probe trace | Every global the chunk references must be bound by all six; the bakes gain media too (F7) |
+| The Brick4 bake binds 10 storage buffers (7 ray-tracing, `light_data`, `probe_positions`, `output`) in 4 bind groups. The engine requires 10 and never raises `maxBindGroups` from 4 | No new storage binding and no new group inside `render_trace_path`. The media table goes in as a uniform in the existing `materials` group (uniforms are 1–2 of 12) |
+| The software device reports 8 storage buffers and cannot be raised | Tier-3 specs can encode the accumulating tracer only while it stays at 8 |
+| `ray_shaded_query_occluded` also serves the ray-traced shadow shaders (`shadow/ray/`) | It stays boolean and unchanged. The tracer gets a transmittance query built on the same per-hit step, lifted into a shared chunk rather than copied |
+| `sample_material_data` flips normals on back-face hits and drops the flag | The flag is added to `STANDARD_MATERIAL_DATA_STRUCT`: entering vs exiting needs it |
+| No spec covers any tracer module, and no validity spec includes them | Validity coverage of the tracer and its six consumers is new work |
+| `min_accumulation_alpha` turns the running mean into an EMA after 1/α samples; the output is flood-filled from coarser mips where luminance is zero; RR truncates at `bounce_limit − 1`; misses are clamped at luminance 10 | Device checks read the history, set α small, use non-zero backgrounds, and keep environments under the clamp |
+
+### 1.3 Defects found on the way (verified by reading the code, not yet pinned by a failing spec)
+
+- **D1, resident material table, in-place edits.** `GPUResidentMaterialContext` bumps its version only when a material
+  misses its cache (`#pack_material`). Editing `roughness_factor`, `metallic_factor`, `transmission_factor`, `ior_factor`
+  or `emissive_factor` on a resident material never reaches `INDIRECT_MATERIAL_STRUCT`. The tracer, the bakes and the
+  ray-traced shadows keep the old values. A medium edit would be lost the same way.
+- **D2, resident material table, equal materials.** The cache is keyed by `equals()`, but mesh rows store each
+  material's own `id` (`scene/rows/GPUSceneRows.js:923`), and the table is written only at the cached entry's id. A
+  second material equal to the first (a clone, say) leaves its own row zeroed, so its opacity is 0 and rays pass
+  through it. Whether `medium` takes part in `equals()` decides which materials would collapse.
+- **D3, lightmap bake does not link.** `shader_lightmap_viz_to_sh` and `shader_lightmap_viz_to_irradiance_flat` call
+  `get_biased_normal_sample`, whose chunk nothing imports. The live one is a `render_trace_path` consumer this work
+  must keep compiling.
+
+### 1.4 Outside this work (verified in code; consequence not measured)
+
+- **Atmosphere Mie extinction.** `C_MIE_ABSORPTION = 4.4e-6` is Hillaire's Mie *extinction*, and `compute_extinction`
+  adds it to the scattering 3.996e-6, giving 8.396e-6 m⁻¹ against Hillaire's 4.44e-6. The engine's own unused
+  `atmosphere/hillaire/ATMOSPHERE_EARTH.js` has the right split.
+- **LPV probe placement inside test.** `scene_point_query_is_inside_geometry` dots a geometry-space face normal with a
+  world-space ray, so rotated or mirrored instances get the wrong vote.
+- **Brick4 `rand1` bake sampler.** It passes a uniform azimuth into `spherical_to_cartesian`'s polar-angle argument,
+  so its random rotation axes are not uniform.
+
+## 2. Medium model
+
+### 2.1 Medium
+
+```text
+ParticipatingMedium
+  absorption: RGB m⁻¹                 total σ_a
+  priority:   integer, default 0      who wins where interface-bounded media overlap (§3.2)
+  lobes:      ≤ 4 × { scattering: RGB m⁻¹, phase }
+σ_t = σ_a + Σ σ_s,l;   phase per channel = Σ σ_s,l p_l / Σ σ_s,l
+```
+
+Lobes are declared one at a time (`medium.add_lobe(scattering, phase)`), each with one explicit phase object:
+`PhaseHenyeyGreenstein({g})`, `PhaseDraine({g, alpha})`, `PhaseRayleigh()`, `PhaseWaterMolecular({depolarization})`,
+`PhaseFournierForand({backscatter_fraction})`, `PhaseJendersieDeon({diameter_micron})`. On the GPU, these reduce to two
+kinds:
+
+- **Draine (g, α)**: every analytic lobe, and Jendersie–d'Eon, which expands into two Draine lobes.
+- **Fournier–Forand (ν, κ = 4/(3(n−1)²))**: (μ, n) is solved on the CPU from `B_p` on Mobley 2002's line.
+
+The name `ParticipatingMedium` does not collide: the only other "medium" in the engine is `AcousticMedium`.
+
+### 2.2 Interface-bounded media and volume primitives
+
+**Interface-bounded media.** A closed mesh bounds a medium when its material references one
+(`StandardShadeMaterial.medium`). The mesh's outward face normal says which side is inside. The material's transmission
+lobe becomes the dielectric interface into that medium (§3.3).
+
+**Volume primitives.** `ParticipatingMediaVolume` is unchanged.
+
+- **Coefficients.** The tracer maps it to `σ_s = scattering · density · f(x)` and
+  `σ_a = (extinction − scattering) · density · f(x)`, with one HG lobe at the volume's `g`.
+- **The fade `f(x)`.** It is the pointwise smoothstep edge fade, which the froxel builder's midpoint evaluation
+  discretizes.
+- **What both sides share.** The reference and the froxels read the same coefficients, the same fade and the same
+  single-scattering phase. The reference does true multiple scattering where the froxels use Wrenninge octaves, which
+  makes it a check on those octaves.
+
+### 2.3 The consumers, in the API
+
+```js
+// water: §4.1 of the water optics plan; b_w is the water line's fitted RGB, passed in
+water.absorption.set(a_r, a_g, a_b);
+water.add_lobe(b_w, new PhaseWaterMolecular({ depolarization: 0.039 }));
+water.add_lobe(b_minus_b_w, new PhaseFournierForand({ backscatter_fraction: 0.0183 }));
+
+// glass: Beer–Lambert interior, entered through a material with transmission
+tinted_glass.absorption.set(0.9, 0.1, 0.4);
+
+// fog and clouds: a ParticipatingMediaVolume authored from the existing Mie particle table, as today
+```
+
+## 3. Transport
+
+### 3.1 Estimators
+
+**Free flight: null scattering with hero-channel MIS.**
+- **Method.** This is the null-scattering formulation of Miller, Georgiev & Jarosz 2019, as PBRT-v4's
+  `VolPathIntegrator` implements it.
+- **Hero channel.** Each path picks one uniformly. Distances come from the hero's majorant, and absorb/scatter/null is
+  decided with the hero's probabilities.
+- **Per-channel bookkeeping.** Each channel keeps its β and its rescaled path probability `r_u`, and every
+  contribution is divided by `mean(r_u)`.
+- **Homogeneous media.** The majorant equals `σ_t`, so there are no null collisions.
+
+**Why not a scalar majorant.** Spectral tracking (Kutz 2017) uses one majorant for all channels. With illustrative
+clear-water coefficients (σ_a ≈ 0.35/0.067/0.019, σ_s ≈ 0.05 m⁻¹) that majorant is red's 0.40 m⁻¹. Each tentative
+collision then absorbs with p ≈ 0.48, so half the blue paths end every 2.5 m, against blue's own 14.5 m mean free path.
+
+**Shadow-ray transmittance: residual ratio tracking** (Novák et al. 2014).
+- The control is the segment's homogeneous part, `exp(−σ_t d)` per channel.
+- The residual is the fog volumes, ratio-tracked against one scalar majorant, so each per-channel factor stays in
+  [0, 1].
+- With no volumes on the segment it is exact and takes zero iterations.
+- No MIS bookkeeping is needed: lights are delta and reachable only by NEE, while the environment and emissive meshes
+  are reachable only by sampled rays.
+
+**Majorant pieces.** A segment is split at the sorted entry and exit distances of the volume boxes it crosses. Without
+the split, a small dense box would cost null collisions all the way to a distant hit.
+
+**Phase sampling.**
+- The lobe is chosen with channel-independent probability (the mean of its `σ_s`), so `r_u` is untouched.
+- The direction is sampled exactly from that lobe.
+- Each channel is weighted by `Σ σ_s,l p_l / Σ q_l p_l`.
+- Fournier–Forand is sampled by Newton with a bisection fallback on its analytic CDF in `sin²(ψ/2)`. That CDF was
+  checked for this brief: it matches quadrature, and `B_p = 0.0183` lands on n = 1.100, μ = 3.583, Mobley's Petzold
+  fit. It is 0/0 at δ = 1, so the WGSL needs a series branch there.
+
+### 3.2 The medium stack
+
+Each path carries up to three interface-bounded media, packed into a `u32` pair and manipulated with shifts only. At a
+hit on a medium-bounding mesh:
+
+| Hit | Rule |
+|---|---|
+| Entering (front face), new medium's priority lower than the top's | False intersection: record it, no refraction |
+| Entering, priority equal or higher | The interface is `n_top → n_new` |
+| Exiting (back face) a medium on the stack | Pop it. The interface is real only if it was the top |
+| Same medium as the top, or exiting one not on the stack | Index-matched: pass straight through |
+| Depth past 3 | Further entries count as false intersections |
+
+**Stack initialisation.** `render_trace_path` traces one probe ray from each path's origin: a medium whose first
+boundary along the probe is a back face contains the origin. The origin is the camera for the tracer and a probe or
+texel for the bakes. The probe is skipped when no resident material has a medium. Open meshes leave this undefined,
+which is why media must be bounded by closed meshes.
+
+Fog volumes are found by position, so they need no stack.
+
+### 3.3 Surfaces
+
+- **Dielectric interface.** A medium-bounding material's transmission lobe is one dielectric BSDF covering reflection
+  and refraction.
+  - Fresnel is the exact unpolarized form at the relative IOR, with TIR.
+  - Roughness uses the GGX BTDF (Walter et al. 2007), built from the existing D, Smith and VNDF chunks. It falls back
+    to the smooth limit below the engine's `BSDF_ROUGHNESS_MINIMUM`.
+  - In radiance transport the transmitted weight is divided by η². That gives the camera `t/n²` of in-water radiance
+    (water plan §4.2).
+- **The rest of the material.** The `(1 − transmission)` part keeps today's specular and diffuse lobes. Its F0 uses the
+  IOR relative to the current medium, so a stone under water reflects as wet stone.
+- **Holes.** Alpha coverage is a hole, not an interface: the stack is untouched.
+
+### 3.4 NEE
+
+- **Points without a normal.** Light selection gains a receiver with no normal (no cosine in the importance), without
+  copying the two-pass selection loop.
+- **Through media.** Transmittance follows §3.1. Thin-walled glass keeps its stochastic coverage.
+- **Shadow ray reaching a refracting boundary:** fork F3.
+
+### 3.5 Manifold NEE (F3 c), with runtime cost as a constraint
+
+Manifold NEE (Hanika et al. 2015) handles one smooth specular interface between the shading point and the light: the
+water surface, waves included. Chains of two (glass) use the same block-tridiagonal Newton step and are designed in,
+but are not enabled in the first cut.
+
+**The solve.**
+- **Seed.** The first medium-bounding smooth dielectric hit of the straight shadow ray. Nothing else ever invokes MNEE,
+  so a scene without such an interface pays nothing.
+- **Constraint.** The generalized half-vector at the vertex. It is solved by Newton in the hit triangle's tangent
+  plane, using its interpolated normal and that normal's derivative across the triangle.
+- **Re-projection.** Each step re-projects onto the real surface by tracing from the shading point toward the updated
+  vertex: one ray cast per iteration.
+- **Termination.** The iteration cap is a renderer setting, initially 8. A flat interface converges in one step, so it
+  costs one extra cast.
+
+**The estimate.**
+- **Weight.** The generalized geometric term comes from the constraint's derivative. That is what produces caustic
+  focusing, and with a directional light it uses the light-direction form.
+- **Shadowing.** Both legs, shading point to vertex and vertex to light, get medium transmittance and occlusion.
+
+**Cost and bias, stated.**
+- Hanika's MNEE finds one solution per seed, so it is biased where several exist (steep, overlapping waves).
+- Specular manifold sampling (Zeltner et al. 2020) removes that bias with Bernoulli trials, at several more solves per
+  sample. It is the named upgrade if a measured preset needs it, not the default.
+- The per-NEE cost (iterations, casts, convergence failures) is reported by the tracer and measured in the playground,
+  including in the Brick4 bake, which runs the same code.
+
+### 3.6 Budgets
+
+Diffuse and glossy bounces stay at each caller's limit, so references and bakes without media are unchanged.
+Interface events (64, measured — see the status above), medium scattering events (256) and pass-throughs of
+medium-bounding surfaces with no interface (32) get their own limits. Surface bounces and medium scattering use Russian
+roulette on `β / mean(r_u)`; interface events carry weight 1 and are bounded by their limit alone.
+
+Null collisions are capped per segment as a TDR guard: a render pass that runs past ~2 s resets the device.
+`MediumPathState.capped` counts the flights a path cut; nothing reads it out yet.
+
+## 4. GPU layout and bindings
+
+```text
+PHASE_LOBE  { scattering: vec3f, kind: u32, p0: f32, p1: f32 }                               32 B
+MEDIUM      { absorption: vec3f, priority: u32, lobe_count: u32, lobes: array<PHASE_LOBE, 4> } 160 B
+INDIRECT_MATERIAL_STRUCT.medium: u32   in the existing tail padding (still 80 B, 819 materials); 0xFFFFFFFF = none
+STANDARD_MATERIAL_DATA_STRUCT.front_facing
+```
+
+- **Media table.** A 64 KiB uniform array of 409 media, owned by `GPUResidentMaterialContext` beside the material
+  table: media are reached only through materials.
+  - Every `render_trace_path` consumer declares it in its existing `materials` group. That adds no storage buffer and
+    no bind group.
+  - Slots are dense (an `IdPool`, as textures use), not global ids.
+  - Change detection depends on D1.
+- **Fog volumes:** F6.
+
+## 5. Validation
+
+**Tier 1.** One validity spec covers the tracer, all six `render_trace_path` consumers and every new chunk. A
+storage-budget assertion pins the accumulating tracer at 8 and the Brick4 bake at 10.
+
+As built (`chunk_render_trace_path.consumers.spec.js`): five of the six consumers, each valid and binding `media` as a
+uniform within the engine's 10 storage buffers. `graph_path_trace_scene` keeps its shader module-private, so it is
+covered by the shared chunk and the device compile of the accumulating tracer only. The validator caught a reserved
+word (`target`) in the stage-3 phase chunk that no shader had compiled yet.
+
+**Tier 2, emulator, library mode, against CPU oracles.** Transport chunks are pure: segment in, event out. Spec harness
+kernels walk them between analytic planes, with no BVH.
+
+| Item | Oracle |
+|---|---|
+| Phase normalization, every lobe kind including g=0 and α=0 | Quadrature in the spec |
+| Fournier–Forand backscatter | Integral = `B_p` over 0.005–0.05; finite and continuous at δ = 1 ± ε |
+| Samplers | KS test against each analytic CDF (spec-local KS) |
+| Jendersie–d'Eon encoding | Two Draine lobes evaluate equal to `phase_mie_jendersie_deon_evaluate_params` |
+| Exact Fresnel | Independent JS formula; R + T = 1; TIR at the critical angle |
+| Chromatic infinite medium | MIS-weighted scattering count per channel = ϖ_c / (1 − ϖ_c), σ_t spread 10:1 |
+| Homogeneous slab | Ballistic `e^(−τ)` exactly; total transmittance against an f64 analog Monte Carlo in the spec, within combined standard error |
+| Faded fog box | Ratio tracking against quadrature of ∫σ_t |
+| Homogeneous transmittance | Zero iterations, exact |
+| Stack | Every §3.2 rule as a case |
+
+**Tier 3, `SoftwareGPUDevice`.**
+- A material's row carries its medium slot; a material without one carries the sentinel.
+- The media bytes match the encoding, and editing a medium re-uploads them (needs D1).
+- Two equal materials both get rows (D2).
+- The tracer dispatch binds the media uniform and stays at 8 storage buffers.
+
+**Tier 4, headless Chrome.** A playground `src/shade/playground/path_traced_media/` follows the AVBOIT page's pattern.
+It reads values back numerically.
+
+As built: `run_checks()` renders each scene to convergence with the accumulating tracer, reads the radiance before the
+tone map at full precision, and compares rectangles with the closed form — per pixel where the answer depends on the
+view ray's angle, as a ratio against a control render where it depends on units. The nine checks: an index-matched
+absorbing slab, the same behind n = 1.5 glass with every internal reflection summed, an underwater camera (the origin
+probe), white furnaces for a clear glass sphere, an index-matched scattering sphere, a scattering n = 1.333 sphere and
+a fog volume, and the sun through an index-matched absorbing box and through an absorbing fog volume. Check 3 below
+waits for stage 5. As planned:
+
+1. **White furnace.** A lossless scattering sphere at IOR 1 and at IOR 1.333 under a flat environment of 1 should give
+   1 everywhere, within 3 standard errors.
+2. **Beer–Lambert slab.** Over a background of 1, the result should be `(1 − F)² e^(−σ_a d) / (1 − F² e^(−2σ_a d))`.
+3. **Water floor round trip** (after stage 5). Water with b = 0, sun at 30° and 60°, black environment, diffuse-bounce
+   limit 1. The result should be `t(θ_v)/n² · t(θ_s) · (ρ/π) · E cos θ_s · e^(−a(z/cos θ_w + z/cos θ_v,w))`.
+
+The water presets render as references only. Raster water belongs to the water line, which consumes this through
+§2.3.
+
+## 6. Stages
+
+Each stage is committed on its own, with specs red-then-green where they pin behaviour.
+
+| Stage | Work | Gate |
+|---|---|---|
+| 0 (F8) | D1, D2 and D3 fixed, each pinned by a spec that is red first. Validity coverage of the tracer and its consumers | Tier 1, tier 3 |
+| 1. Optics chunks | Exact Fresnel; Draine sampler wrapper (HG at α=0, Cardano on `cbrt` at g=0); Fournier–Forand evaluate/CDF/sample plus the CPU solve | Tier 2 phase and Fresnel rows |
+| 2. Medium model | `ParticipatingMedium`, phase classes and encoding, `StandardShadeMaterial.medium`, media uniform table, material slot, front-facing flag | Unit specs, tier 3 |
+| 3. Transport chunks | Free flight, residual ratio tracking, majorant pieces, phase mixture, volume density, box interval, stack ops | Tier 2 transport rows |
+| 4. Tracer and playground | Medium segments and scattering vertices, dielectric interface, relative-IOR F0, fog volumes (per F6), origin probe, receiver without a normal, budgets and caps; shadow rays block at refracting boundaries | Tier 1, tier 3, tier 4 checks 1–2; mean unchanged for a scene without media |
+| 5. Manifold NEE | One-interface MNEE per §3.5, with cost counters | Tier 2: constraint solve on flat and curved interfaces, the geometric term against finite differences of the irradiance; tier 4: check 3 and a wave-shaped interface; cost measured |
+| 6. (optional) glTF `KHR_materials_volume` import | Absorption from `attenuationColor` and `attenuationDistance` | Importer spec |
+
+## 7. Not in scope, and stated limits
+
+- ~~**Caustic focusing** through curved interfaces (needs the MNEE Jacobian, F3).~~ Built in stage 5.
+- **Delta lights through two or more refracting boundaries.** These leave black shadows, the standard unidirectional
+  limit. Thin-walled glass is unaffected.
+- **Until stage 5, delta lights through any refracting boundary.** A shadow ray blocks at an interface between
+  different indices, so the sun reaches what is under water only as sky light and bounces.
+- **Light trapped past 64 interface events**, which only a smooth curved body that scatters inside produces (status
+  above).
+- **The opaque remainder of a medium-bounding surface** (`transmission_factor` < 1) takes its specular F0 from
+  `ior_factor` against vacuum, not against the medium on its other side.
+- **Environment NEE and volume emission.** For volume emission, `σ_a L_e` at absorption events is the hook.
+- **Spectral rendering and dispersion.**
+- **The raster side of media.** AVBOIT glass does not refract or absorb.
+- **Heterogeneous density beyond the fade** (F4).
+
+## 8. Forks
+
+| # | Question | Options | Recommendation |
+|---|---|---|---|
+| F1 | Where does an interface's IOR live? You described media as "IOR plus scattering and absorption" | **(a) On the boundary material** (`ior_factor`): the medium is coefficients, phase and priority. **(b) On the medium**: then `ior_factor` stops mattering on those materials' transmission lobe | **(a).** Every raster path (forward, AVBOIT, MBOIT) and the tracer's F0 already read `ior_factor`, so one value per surface keeps raster and reference in agreement on reflectance. Under (b) a field's meaning would depend on another field. The cost of (a): two materials could enter one medium at different IORs. Physically IOR belongs to the substance, which is the case for (b) |
+| F2 | A transmissive material without a medium | **(a) Stays thin-walled**, as it is in the tracer, forward, AVBOIT, MBOIT and shadows today. **(b) Becomes a solid** | **(a).** (b) would change every existing scene and require every pane to be a closed mesh: a one-plane window has no inside, and the stack would corrupt. Thin-walled is the correct limit for a sheet thinner than the footprint, and a solid is exactly "transmission + medium" |
+| F3 | NEE through a refracting boundary | **(a)** Straight-line pass-through: in-water path 2z instead of 1.315z for a 60° sun, which mis-validates the downwelling the water plan needs checked. **(b)** Connection through one smooth interface by Newton on the local tangent plane: exact on flat water, no focusing on curved surfaces, directional, point and spot alike. **(c)** Full manifold NEE with the curvature Jacobian: caustics | **(b) now**, in stage 5. **(c) when waves exist and the reference should show caustics.** Raster water has none (water plan §1). Rough interfaces need neither: NEE at the interface vertex goes through the rough BTDF |
+| F4 | Cloud density from noise or a grid | Today neither side has it: the noise fields on `ParticipatingMediaVolume` are never uploaded. **(a) Later**, as one density chunk read by the froxels and the tracer alike (the 3-D `psrdnoise3` chunk exists, unused). **(b) Now**, tracer only | **(a).** The estimators already treat the fade as heterogeneous, so a density source changes no transport code |
+| F5 | Shared chunks with water stage 1b | Exact Fresnel, Fournier–Forand and the molecular phase (a Draine parameter set, no code) land in stage 1 in `shader/chunk/brdf/fresnel/` and `shader/chunk/atmosphere/phase/`, pinned by the specs water §8 asks for | Yes, unless the water line already has its own in flight. Please confirm |
+| F6 | How fog volumes reach `render_trace_path`, given the Brick4 bake has no storage slot left | **(a) A table in the scene's `GPUDatabase`**, which every tracer consumer already binds; `GPUSceneVolumetrics` writes it, and the two froxel passes reading `scene_volumes` read it there instead (net zero bindings). A volume becomes an entity's row, as meshes and lights already are; linking it to its transforms row would later also lift its no-hierarchy limitation. **(b) A second, uniform copy** of the volume table (≈340 volumes in 64 KiB), bound in each consumer's light group | **(a).** One copy of the data, no cap, and the direction the engine has already taken for lights. It is a raster-side change to the volumetrics plumbing, which is why it is your call. The light database would also work; the scene database fits "a volume is a scene record" better |
+| F7 | The bakes gain media too | **(a) Yes**, by sharing `render_trace_path`. Scenes with fog volumes bake differently: fog scatters and attenuates in Brick4 probes and lightmaps, and bakes cost more where fog is. **(b) No**: a second concrete tracer chunk for references only | **(a).** (b) duplicates a 380-line chunk and makes the reference disagree with the bakes it should judge: the exception you asked to avoid |
+| F8 | Stage 0: fix D1, D2 and D3 first | They sit in the table and the shader this work extends | **Yes.** Each starts with a failing spec; if a spec will not go red, that item is dropped and reported |
+
+Decided here, each with what would reverse it:
+
+| Decision | Reversal condition |
+|---|---|
+| RGB with hero-channel MIS | Measured chromatic noise in the presets that it does not remove |
+| Fog keeps the raster's HG phase | Moves to Jendersie–d'Eon only together with the froxels |
+| Priority on the medium | A scene needing two priorities for one medium |
+| Media table uniform in the `materials` group | Media outgrowing 409 |
+| Budgets per §3.6 | A preset hitting a cap |

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,sBAFW,eAAe,EAkBzB;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;;OAOG;IACH;QAJmC,IAAI,EAA5B,cAAc;QACM,KAAK,EAAzB,UAAU;QACR,MAAM,CAyJlB;;CACJ;yBAxcY,OAAO,8DAA8D,EAAE,UAAU;8BAIjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc"}
+{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,sBAFW,eAAe,EAkBzB;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;;OAOG;IACH;QAJmC,IAAI,EAA5B,cAAc;QACM,KAAK,EAAzB,UAAU;QACR,MAAM,CA0JlB;;CACJ;yBAzcY,OAAO,8DAA8D,EAAE,UAAU;8BAIjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc"}

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js

@@ -410,6 +410,7 @@ export class AccumulatingPathTracer {
 
                 bindings: {
                     materials: r_materials.buffer_materials,
+                    media: r_materials.buffer_media,
                     textures: r_materials.textureView,
 
                     tlas: scene_ctx.tlas.buffer,

package/src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAiBA,2DAKG;AA8EH,4DAIG;6BAtG0B,mCAAmC;8BAOlC,+BAA+B"}
+{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAkBA,2DAKG;AA+EH,4DAIG;6BAxG0B,mCAAmC;8BAOlC,+BAA+B"}

package/src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js

@@ -11,6 +11,7 @@ import { ComputeShader } from "../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { sr_create_group_RTX } from "../../geometry/sr_create_group_RTX.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
+import { MEDIA_TABLE_STRUCT } from "../../medium/MEDIA_TABLE_STRUCT.js";
 import { chunk_render_trace_path } from "../shader/chunk_render_trace_path.js";
 
 const resources = new ShaderResourceSetDescriptor();
@@ -30,6 +31,7 @@ sr_create_group_RTX(resources);
 
 resources.createGroup()
     .addUniform("materials", INDIRECT_MATERIAL_ARRAY_TYPE)
+    .addUniform("media", MEDIA_TABLE_STRUCT)
     .addTexture("textures", "unfilterable-float", "2d-array");
 
 resources.createGroup()

package/src/shade/renderer/path_tracer/graph_path_trace_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAgGA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACD,IAAI;IAC1B,MAAM,CAoFlB"}
+{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAkGA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACD,IAAI;IAC1B,MAAM,CAqFlB"}