@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/graphics/sh3/path_tracer/REVIEW_001_ACTION_PLAN.md

@@ -1,490 +0,0 @@
-# Path Tracer — Correctness Review 001 & Action Plan
-
-Scope: the CPU (JavaScript) unidirectional path tracer rooted at `PathTracer.js`, plus its
-scene / BVH / material / sampling support code in this directory and the core geom/math
-primitives it depends on.
-
-Goal of this document: catalogue the **major correctness** defects (wrong light transport,
-wrong pixels, crashes) and give a concrete, prioritised remediation plan. Style/perf/feature
-polish is out of scope except where it crosses into correctness.
-
-Method: a multi-agent review fanned out across seven dimensions (integrator math, sampling/PDF,
-geometry/intersection, BVH/traversal/transforms, materials/textures, numerical robustness, and a
-holistic end-to-end pass). Every candidate finding was then **independently re-read and
-adversarially verified** by a separate skeptic before being accepted here. 31 findings were
-confirmed; 10 were checked and dismissed (see [§7](#7-checked-and-dismissed-not-bugs)).
-
-The integrator's intended design is taken as a given (and is correct as a design): cosine-weighted
-hemisphere sampling for a Lambertian lobe + next-event estimation (NEE) for analytic
-directional/point lights; **no MIS, no specular/transmission, no emitter sampling**. The findings
-below are defects *relative to that design*, not requests to change the design — except where a gap
-in the design itself (emissive, environment GI) silently drops energy.
-
----
-
-## 0. Status (applied 2026-06-19)
-
-**Applied:** F1 (RR compensation), F2 (NEE 1/π), F3 (environment on every miss), F4 (UV order),
-F5 (sRGB→linear for textures + tints — `StandardTexture.decode_sRGB` boolean, set from
-`texture.encoding` in `MaterialConverter` so the three.js dependency stays at that boundary), F6
-(transpose-adjugate **normal matrix** — new `core/geom/3d/mat4/m4_compute_normal_matrix3.js`, cached
-on `PathTracedMesh`, used for both shading and geometric normals), F8 (point-light shadow `tMax`),
-F9 (emissive `L_e` on hit; `tmp_0` widened to 9), F10 (coordinate-scaled self-occlusion offset),
-F13 (`occluded` → `false`), F14 (`getBiasedNormalSample` honors `out_offset`).
-
-Regression gate added: `PathTracer.spec.js` (normal-matrix correctness, white-furnace energy
-conservation, primary-miss background). All path-tracer + touched-core specs pass.
-
-**Dropped on review** (defensive guards against conditions that can only mean an upstream bug —
-masking them hides the real defect, so they were reverted; see [§7](#7-checked-and-dismissed-not-bugs)):
-- **F11** (`float_to_uint8` non-finite guard + driver sample rejection) — if the tracer emits
-  NaN/Inf the tracer is buggy; surface it, don't average around it.
-- **F15** (`getCosineDirection` antipode guard) — unreachable for a unit normal and well-behaved RNG.
-- **F18** (orthonormal-basis zero guard) — unreachable for a non-zero input; and a non-unit input
-  produces a broken basis regardless. Replaced with a JSDoc **unit-vector precondition** instead.
-
-**Deferred (with rationale):**
-- **F7** (tone mapping) — driver-only display feature; best done together with exposure re-tuning
-  after the π-scale change settles.
-- **F12** (metallic-roughness BRDF) — a feature, not a bug; the Lambertian path is correct. Wants
-  its own design pass (likely with MIS and a real `scattering_pdf`).
-- **F16** (`aabb3_intersects_ray_segment` `0·Inf`) — shared hot primitive backing physics BVH /
-  determinism gates; broad blast radius, needs its own change + spec. Left untouched here.
-- **F17** (top-level scratch overflow) — proper fix is an explicit-stack traversal or a bounded
-  shared query; a defensive `undefined` guard would be a bandaid. Deferred.
-- **F19** (shading-normal hemisphere guard) — minor approximation refinement, optional.
-
-Note: F2 darkens direct lighting by π and F5 darkens sRGB textures — scene light intensities tuned
-against the old renderer will need re-tuning (and F7 tone mapping helps here).
-
----
-
-## 1. Severity summary
-
-| # | Severity | Area | Issue | Primary location |
-|---|----------|------|-------|------------------|
-| F1 | **High** | Integrator | Russian roulette never re-weights survivors by `1/p_survive` → all indirect GI biased dark | `PathTracer.js:66-75` |
-| F2 | **High** | Integrator | NEE direct lighting omits the Lambertian `1/π` BRDF factor → direct light ~π× too bright vs. indirect | `PathTracedScene.js:542-547,597-602` |
-| F3 | **High** | Integrator | Environment/background is broken: primary-miss does `multiply` against a zero accumulator, and mid-path misses add nothing → sky never contributes | `PathTracer.js:77-83,111-118` |
-| F4 | **High** | Materials | Normal map sampled at the *previous* hit's UV (stale module-static `texture_uv`) | `texture/sample_material.js:91` vs `:113` |
-| F5 | **High** | Materials | sRGB base-color textures & color tints used without sRGB→linear decode → over-bright, compounds per bounce | `material/StandardTexture.js:60-87`, `material/MaterialConverter.js` |
-| F6 | **High→Med** | Geometry | Normals transformed by `M` instead of `(M⁻¹)ᵀ` → wrong under non-uniform scale | `texture/sample_material.js:89`, `ray_hit_apply_transform.js:29` |
-| F7 | **High** *(driver)* | Output | No tone-mapping before the sRGB OETF → HDR clips harshly to white + per-channel hue shift | `prototypePathTracer.js:486-494` |
-| F8 | **Medium** | Lighting | Point-light shadow ray uses `tMax = radius` instead of `distance_to_light` → false shadows from geometry *behind* the light | `PathTracedScene.js:587` |
-| F9 | **Medium** | Integrator | Emissive materials are loaded but never emit (`L_e` term missing, not in NEE) → emitters render black | `PathTracer.js:85-108`, `material/MaterialConverter.js:84` |
-| F10 | **Medium** | Robustness | Fixed `0.00001` self-intersection offset is below Float32 ULP at large scene scale (and is applied along the scatter dir, not the normal) → shadow/contact acne | `PathTracer.js:95` |
-| F11 | **Medium** | Robustness | A single NaN/Inf sample poisons the whole pixel average → black (or white) speckle | `prototypePathTracer.js:478-488`, `core/binary/float_to_uint8.js` |
-| F12 | **Medium** | Materials | `metalness`/`roughness` loaded but ignored — every surface is Lambertian (no Fresnel/GGX) | `material/MaterialConverter.js:80-83`, `material/StandardMaterial.js` |
-| F13 | **Low** | BVH | `BufferedGeometryBVH.occluded` returns `-1` (truthy) for empty geometry → empty mesh reported as an occluder | `BufferedGeometryBVH.js:176` |
-| F14 | **Low** | Sampling | `getBiasedNormalSample` writes to a hardcoded offset `3`, ignoring its `out_offset` param (latent public-API bug) | `sampling/getBiasedNormalSample.js:43` |
-| F15 | **Low** | Sampling | `getCosineDirection` yields NaN when the sampled sphere point is the antipode of the normal | `sampling/getCosineDirection.js:33-41` |
-| F16 | **Low** | Core/BVH | `aabb3_intersects_ray_segment`: `0*Inf = NaN` for an axis-parallel ray whose origin lies on a slab plane → missed hit/occluder | `core/.../aabb3_intersects_ray_segment.js:41-62` |
-| F17 | **Low** | BVH | Top-level candidate scratch array (4096) has no overflow guard → silent corruption / undefined deref crash if a ray crosses >4096 mesh AABBs | `PathTracedScene.js:47,393-408,437-453` |
-| F18 | **Low** | Robustness | Zero-length normal → `1/length(0)` → NaN basis in `v3_orthonormal_matrix_from_normal` (narrow, mostly contained downstream) | `core/geom/vec3/v3_orthonormal_matrix_from_normal.js:26` |
-| F19 | **Low** | Shading | Perturbed (normal-mapped) shading normal has no geometric-normal hemisphere guard → grazing-angle light leak/darkening | `texture/sample_material.js:102-106` |
-
-Library vs. tooling note: per project convention, `prototypePathTracer.js` is an internal
-prototype/driver tool and `PathTracer.js`/`PathTracedScene.js`/etc. are public library surface.
-F7 and the driver half of F11 live in the prototype; everything else is library code. Unreferenced
-exports (e.g. `getCosineDirection`, `make_sky_*`, `raycast`) are still public surface — fix, don't
-delete.
-
----
-
-## 2. The radiometric core (fix these first)
-
-These three are small, surgical edits in the integrator, but they define whether the renderer is
-energy-correct at all. They should be done together and locked with a regression test
-([§6](#6-testing--validation)).
-
-### F1 — Russian roulette has no survival compensation (bias / global GI darkening)
-
-`PathTracer.js:66-75`. For `i >= min_bounce` the path is killed with probability
-`RUSSIAN_ROULETTE_PROBABILITY = 0.5`, but on **survival** the throughput `color_mask` is never
-divided by the survival probability `(1 - 0.5)`. The only write to `color_mask` is the albedo
-multiply at `PathTracer.js:88`.
-
-Why it's wrong: RR is unbiased only if survivors are scaled by `1/p_survive` so that
-`E = p_survive·(value/p_survive) = value`. Without it, every contribution gathered at or after a
-surviving RR step is attenuated by `0.5` per step (bounce 2 → ×0.5, bounce 3 → ×0.25, …). With the
-driver's `min_bounce=1`, directly-visible surfaces' direct light (`i=0`) is correct, but **all
-multi-bounce indirect light converges to a too-dark answer** — a true bias, not noise.
-
-Fix: inside the `if (i >= min_bounce)` block, after the terminate test passes, multiply
-`color_mask` by `1 / (1 - RUSSIAN_ROULETTE_PROBABILITY)` (= 2 for the current constant). Placement
-matters — it must be inside the `i >= min_bounce` guard (only when RR actually ran), before the
-trace/accumulate for that iteration, so both the NEE term and onward throughput carry the factor.
-
-```js
-if (i >= min_bounce) {
-    if (random() < RUSSIAN_ROULETTE_PROBABILITY) {
-        break; // terminate
-    }
-    const inv_survive = 1 / (1 - RUSSIAN_ROULETTE_PROBABILITY);
-    color_mask[0] *= inv_survive;
-    color_mask[1] *= inv_survive;
-    color_mask[2] *= inv_survive;
-}
-```
-
-Optional follow-up (variance, not correctness): make `p_survive` depend on `max(color_mask)`
-(throughput-based RR). Strictly better, but not required to remove the bias. Also note `max_bounce`
-hard-truncates surviving paths at the cap without RR there — a much smaller, separate residual bias.
-
-### F2 — NEE omits the Lambertian `1/π` (direct vs. indirect imbalance of π)
-
-`PathTracedScene.js:542-547` (directional) and `:597-602` (point). The NEE contribution is
-`light_color · dotNL · intensity` (× attenuation for point), accumulated as
-`color_mask · tmp_0` at `PathTracer.js:104-106`. `color_mask` already carries the albedo, so the
-direct term is `albedo · L · cosθ` — but the physical Lambertian result is
-`(albedo/π) · L · cosθ`. The `1/π` is missing.
-
-Why it's wrong, and why it's specifically an *imbalance*: the **indirect** path is already
-self-consistent for `BRDF = albedo/π` — cosine sampling gives `pdf = cosθ/π`, so
-`BRDF·cosθ/pdf = albedo`, exactly what `color_mask *= albedo` (`PathTracer.js:88`) does. The
-indirect path implicitly carries the `1/π`; NEE does not. So direct lighting is π (~3.14×) too
-bright *relative to* bounced lighting that shares the same surface. The engine's own intended
-convention confirms this: `StandardMaterial.scattering_pdf` returns `cosθ · PI_RECIPROCAL` (it's
-just commented out at its call site, `PathTracedScene.js:365-369`).
-
-Fix: fold `PI_RECIPROCAL` (`core/math/PI_RECIPROCAL.js`) into `intensity` in both light branches:
-
-```js
-const intensity = dotNL * light.intensity.getValue() * PI_RECIPROCAL;            // directional
-const intensity = dotNL * light.intensity.getValue() * attenuation * PI_RECIPROCAL; // point
-```
-
-Do **not** touch `PathTracer.js:88` — the indirect throughput already cancels the `1/π`. This will
-darken direct lighting by π, so any light intensities tuned against the buggy renderer will need
-rescaling. Validate with a constant-albedo white-furnace test ([§6](#6-testing--validation)).
-
-### F3 — Environment/background contribution is broken (primary miss + mid-path miss)
-
-Two coupled defects, best fixed together:
-
-1. **Primary miss multiplies against zero** — `PathTracer.js:111-118`. With `min_bounce=1`, the
-   only way to exit the loop with `i === 0` is a primary-ray miss; at that point `irradiance` is
-   still `[0,0,0]`. The branch then does `vec3.multiply(irradiance, irradiance, tmp_0)` =
-   `0 · sky = 0`. The sky radiance sampled into `tmp_0` is discarded — a missed primary ray is
-   always black, for **any** background. The correct op is an **assignment** (radiance along a
-   missed primary ray *equals* the environment radiance).
-2. **Mid-path misses drop the environment entirely** — `PathTracer.js:77-83`. When a bounce ray
-   (`i > 0`) escapes, the loop just `break`s, never adding `color_mask · sky`. So the sky never acts
-   as a light source; surfaces receive only the analytic lights, zero environment GI.
-
-Currently masked: the default `__background_sampler = make_vector3(0,0,0)` (`PathTracedScene.js:103`)
-is black and is never reassigned in shipped code, so `0·0` and `0+0` both look correct today. The
-defect becomes visible the moment a real sky (`make_sky_rtiw` / `make_sky_hosek` — which exist for
-exactly this) is wired into the public `__background_sampler`. It is unambiguously wrong logic and
-should be fixed even though it is currently dormant.
-
-Fix (unifies both): handle the miss inside the loop and delete the `i === 0` post-loop block:
-
-```js
-const hit_distance = scene.trace(trace_result, _ray_0);
-if (hit_distance < 0) {
-    // ray escaped — accumulate throughput-weighted environment radiance
-    scene.sample_background(tmp_0, 0, _ray_0, 3);
-    irradiance[0] += color_mask[0] * tmp_0[0];
-    irradiance[1] += color_mask[1] * tmp_0[1];
-    irradiance[2] += color_mask[2] * tmp_0[2];
-    break;
-}
-```
-
-At `i=0`, `color_mask` is still `[1,1,1]`, so this reduces to assigning the raw sky (fixing the
-multiply-vs-assign); at `i>0` it adds the throughput-weighted environment, restoring sky GI. The
-direction at `_ray_0[3..5]` is the correct escaping direction at the moment of the miss (the bounce
-overwrite at `:91`/`:101` hasn't run yet for this iteration).
-
----
-
-## 3. Material & shading correctness
-
-### F4 — Normal map sampled at stale UV (`high`)
-
-`texture/sample_material.js`. `material.normal.sample(normal, texture_uv[0], texture_uv[1])` runs
-at **line 91**, but `texture_uv` (a module-static `[0,0]`) is only filled with *this* triangle's
-interpolated UV at **lines 109-118**, which execute afterward. So the tangent-space normal is read
-at the *previous* invocation's UV (or `(0,0)` on the first call) — a spatially unrelated texel. The
-diffuse sample (`:129`) correctly uses the freshly-computed UV, so only normal-mapped materials are
-affected (the default flat normal `[127,127,255]` is skipped by the `:93` distance test, so plain
-materials are unaffected). The corrupted shading normal feeds both the NEE cosine term and the
-cosine-lobe bounce, and varies with traversal order.
-
-Fix: move the UV-computation block (current `:109-118`) **above** the normal-map sampling block
-(`:91-107`). No other call site depends on the current ordering.
-
-### F5 — sRGB albedo not linearized (`high`)
-
-The live shading path calls `material.diffuse.sample(...)` → `StandardTexture.sample`
-(`material/StandardTexture.js:60-87`), which converts uint8→float but performs **no** sRGB→linear
-decode and has no `encoding` field at all. `MaterialConverter.#ensure_texture`
-(`material/MaterialConverter.js:43-57`) drops `texture.encoding` at conversion time. (The free
-function `texture/sample_texture.js` *does* branch on encoding, but its sRGB call is commented out
-at `:53` and it is dead code — referenced nowhere.) glTF/three base-color maps are sRGB-authored;
-feeding gamma-encoded texels into a linear integrator over-brightens midtones (`0.5` sRGB ≈ `0.214`
-linear) and the error **compounds multiplicatively per bounce** via `color_mask` (`PathTracer.js:88`).
-Flat `material.color` tints (`MaterialConverter.js:92-100`) are likewise not linearized.
-
-Fix (must be **selective** — only sRGB-authored channels):
-- Add an `encoding` field to `StandardTexture` (default `LinearEncoding`); set it in
-  `MaterialConverter.#ensure_texture` from `texture.encoding`.
-- In `StandardTexture.sample`, apply `sRGB_to_linear` (`core/color/sRGB/sRGB_to_linear.js`) only
-  when `encoding === sRGBEncoding`, after the uint8→float step. **Do not** linearize
-  normal/metalness/roughness — those are data textures and would be corrupted.
-- Linearize `material.color` before `sampler2d_multiply_vector` in the tint path.
-
-### F6 — Normals use `M`, not the inverse-transpose (`high` for shading normal under non-uniform scale)
-
-`texture/sample_material.js:89` rotates the **shading** normal by the forward model matrix
-`mesh.transform`; `ray_hit_apply_transform.js:29` does the same for the **geometric** normal. Both
-funnel into `v3_matrix4_rotate` (applies the upper-left 3×3 of `M`, then renormalizes). A normal is
-a covector and must transform as `(M⁻¹)ᵀ·n`. For rotation + uniform scale + translation these agree
-up to a positive scalar (killed by the renormalize), so the **common case is correct** — but under
-**any non-uniform scale/shear** `M·n` is no longer perpendicular to the transformed surface, and
-renormalization fixes only length, not direction. The skewed shading normal mis-aims both the
-cosine sampling lobe and the NEE `dotNL`; at strong non-uniform scale the skewed *geometric* normal
-can even flip the back-face sign test (`PathTracedScene.js:355-363`), flipping shading to the wrong
-hemisphere (black/wrong shading).
-
-Reachability: `createMesh` accepts an arbitrary `mat4`, and `Transform` supports per-axis scale, so
-non-uniform scale enters through the public API. The shipped prototype scenes happen to use uniform
-scale, so it's latent there but live for library callers.
-
-Fix: cache a normal matrix = transpose of the upper-left 3×3 of `#transform_inverse` (already
-computed via `mat4.invert` in the transform setter, `PathTracedMesh.js:86`) and use it for both
-normal rotations. Add a `v3_array_matrix4_rotate_transpose`-style helper (mind gl-matrix
-column-major indexing). The position transform in `ray_hit_apply_transform` must keep using the
-forward matrix; only the normal line changes. The geometric-normal site (`ray_hit_apply_transform.js`)
-is lower impact (sign test only) but worth fixing for consistency.
-
-### F12 — `metalness`/`roughness` ignored; always Lambertian (`medium`)
-
-`MaterialConverter.js:80-83` assigns these samplers and `StandardMaterial` holds them, but nothing
-in shading reads them — the only BRDF is the cosine diffuse lobe. Metals render as colored diffuse;
-all gloss/specular/Fresnel is absent; energy is mis-distributed for any PBR asset. Note: the
-existing Lambertian path is itself *correct* — this is an unimplemented-feature gap, not a math
-error. The loaded data is currently dead.
-
-Fix (larger): implement a metallic-roughness BRDF (Lambert diffuse scaled by `1-metalness` + GGX/
-Cook-Torrance specular with Fresnel-Schlick, `F0 = mix(0.04, albedo, metalness)`), read
-metalness/roughness in `sample_material`, importance-sample the chosen lobe, and re-enable a real
-`scattering_pdf` division in the integrator. If out of scope now, **document** that only Lambertian
-diffuse is supported so the dead metalness/roughness inputs aren't mistaken for active. See also the
-emitter/MIS gap (F9) — a proper specular path usually wants MIS.
-
-### F19 — Perturbed shading normal lacks a geometric-normal guard (`low`)
-
-`texture/sample_material.js:102-106`. The normal-mapped shading normal becomes the sole normal for
-both sampling and NEE, with no check that it stays in the geometric upper hemisphere. Strong normal
-maps at grazing angles can send bounce/NEE directions below the true surface → localized leak/
-darkening. Standard minor approximation; only matters with real normal maps. Optional: retain the
-geometric normal (`hit[3..5]`) and clamp/guard directions against it.
-
----
-
-## 4. Lighting, geometry & robustness
-
-### F8 — Point-light shadow ray `tMax = radius` (`medium`; production-relevant)
-
-`PathTracedScene.js:587`. The occlusion ray for a point light is bounded by the light's influence
-`radius`, but the surface-to-light distance is `distance_to_light` (`:556`), and the cull at `:560`
-guarantees `radius >= distance_to_light`. So the visibility test searches **past** the light:
-geometry between `distance_to_light` and `radius` (i.e. *behind* the light) is counted as an
-occluder, producing spurious shadows / over-darkening. Point lights are used in the production ECS
-path (`populate_path_traced_scene_from_ecd.js`), so this is not prototype-only.
-
-Fix: `_ray_1.tMax = distance_to_light;` (optionally `- eps`). Keep `radius` strictly for the
-attenuation cutoff. The directional branch (`tMax = Infinity`, `:533`) is already correct.
-
-### F9 — Emissive surfaces never emit (`medium`)
-
-The bounce loop accumulates only NEE + (broken) background; there is no `L_e` term on hits, and NEE
-doesn't sample emitters. Emissive maps are parsed and cached (`MaterialConverter.js:84`,
-`StandardMaterial.js:19`) but read by nothing. Any mesh whose light output is its emissive map
-renders black — common in glTF assets.
-
-Fix: sample `material.emissive` in `sample_material` into **separate** output slots (not the albedo
-slots), plumb it through the `PathTracedScene.sample_material` wrapper, and in `path_trace` add
-`irradiance += color_mask · emissive` **before** `color_mask` is multiplied by this surface's albedo
-(`:88`) — otherwise the emitter's glow gets tinted by its own albedo. Because there's no MIS and no
-emitter NEE, a plain `L_e`-on-hit term is the correct, non-double-counting choice. Note: `tmp_0` is
-`Float32Array(6)` (`PathTracer.js:24`) and must be widened (e.g. to 9) or a separate scratch used.
-
-### F10 — Self-intersection epsilon too small at scale (`medium`)
-
-`PathTracer.js:95` nudges the new origin by a fixed `0.00001` along the **new ray direction**, on a
-Float32 ray (`Ray3` extends `Float32Array`). Float32 ULP at coordinate magnitude `C` is
-≈ `C·1.2e-7`; at `|C|≈1000` that's ≈ `1.2e-4` > `1e-5`, so the nudge rounds away and the secondary/
-shadow ray re-spawns on the surface → acne/leaks. There is no `tMin` backstop anywhere (leaf tests
-use bare `t > 0`). The offset is also applied along the scatter direction (near-tangent for grazing
-cosine samples), shrinking the effective normal-escape further. Large scenes (`prepare_scene_lucy`:
-ground `y=-800`, camera `z=-2300`) hit this; the currently-active `prepare_sponza` (~5 units) does
-not.
-
-Fix (preferred): carry a real `tMin` in the ray and reject `t <= tMin` in the leaf tests
-(`BufferedGeometryBVH.js:260,408`) and the AABB lower bound, with `tMin` scaled to coordinate
-magnitude. This also fixes the NEE shadow ray without depending on origin precision. Alternatively,
-offset along the **geometric normal** by a magnitude-relative amount
-(`max(1e-4, 1e-5·max(|x|,|y|,|z|))`). The offset must be applied in world space (before the
-transform-to-local).
-
-### F11 — One NaN/Inf sample poisons the whole pixel (`medium`)
-
-`prototypePathTracer.js:478-488` accumulates into plain JS arrays with no finiteness guard; one bad
-sample makes the 16-sample average NaN/Inf. `core/binary/float_to_uint8.js` returns `NaN` for `NaN`
-(both range comparisons are false), which coerces to `0` in the `Uint8ClampedArray` → a pure-black
-pixel (`+Inf` → white). NaN is reachable via degenerate normals (F18) and the AABB `0*Inf` case
-(F16); Inf via unbounded radiance.
-
-Fix (two layers): (1) **library** — harden `float_to_uint8` so non-finite input maps to `0`
-explicitly (protects all callers). (2) **driver** — in the sample loop, skip non-finite
-`pixel_color` samples and divide by the count of valid samples (skipping keeps the estimate
-unbiased; clamping-to-zero would bias dark). Deeper root cause is preventing NaN generation (F18).
-
-### F13 — `occluded` returns `-1` for empty geometry (`low`)
-
-`BufferedGeometryBVH.js:176` returns `-1` (truthy) when the BVH root is `NULL_NODE`, despite the
-documented boolean contract. `PathTracedScene.occluded` (`:408`) treats it as occluded, so an
-empty-geometry mesh among the shadow-ray candidates wrongly shadows the point (silent darkening).
-Reachable (no polycount guard in `addMesh`) but practically rare (the empty mesh's degenerate AABB
-usually fails the top-level slab test first). Fix: `return false;`. (Distinct from `raycast2`/
-`raycast`, which use `-1` as a numeric no-hit sentinel — those are fine.)
-
-### F16 — `aabb3_intersects_ray_segment`: `0*Inf = NaN` on slab-coplanar axis-parallel rays (`low`)
-
-`core/geom/3d/aabb/aabb3_intersects_ray_segment.js:41-62`. Callers pass `1/direction`; a zero axis
-gives `±Inf`, and if the origin is exactly on that box face, `(box-origin)*inv = 0*Inf = NaN`.
-`max2` propagates NaN, so the segment test returns a false miss → skipped subtree → missed hit/
-occluder (speckle / missing shadow caster). Shared by all BVH traversal (`bvh_query_*`), so
-engine-wide, but requires two exact-`0.0` coincidences, hence rare and low.
-
-Fix: handle the parallel axis explicitly — branch on `direction_axis === 0` and do a containment
-test (`origin` within `[lo,hi]` → unconstrained interval, else miss), or clamp exactly-zero
-direction components away from zero before reciprocating. **Note:** a plain "NaN-ignoring min/max"
-swap is *insufficient* for the origin-exactly-on-face sub-case (verified) — the surviving non-NaN
-bound is itself degenerate. Add spec cases for origin-on-face × axis-aligned direction (all four
-face/sign combos).
-
-### F17 — Top-level candidate scratch (4096) overflow (`low`)
-
-`PathTracedScene.js:47` + `trace()`/`occluded()`. `bvh_query_user_data_ray_segment` writes
-candidates with no capacity check; a TypedArray write past length is silently dropped while the
-returned count keeps incrementing. If a ray crosses >4096 mesh AABBs, the consuming loop reads stale
-slots and `meshes.get(...)` → `undefined` → crash on `mesh.hit/occluded`. (The **bottom-level**
-active path — `raycast2`/`occluded` — uses an explicit stack and is already overflow-free; the
-unused `raycast()` is latent for external callers.)
-
-Fix: bound the write in `bvh_query_user_data_ray_segment` (protects all callers), or — preferred —
-convert the top-level `trace`/`occluded` to the explicit-stack nearest/any traversal used by
-`raycast2`/`occluded` (neither needs to materialize all candidates).
-
-### F14 / F15 / F18 — small latent sampler/robustness bugs (`low`)
-
-- **F14** `sampling/getBiasedNormalSample.js:43` writes to a literal offset `3` instead of
-  `out_offset`. Harmless today (the only caller passes `3`) but wrong for any other caller of this
-  public function. Fix: `v3_matrix3_rotate(out, out_offset, k0, k1, r_y, mat3)`.
-- **F15** `sampling/getCosineDirection.js:37` divides by the summed-vector length with no zero guard;
-  the antipode (and near-antipode) case yields NaN/garbage. Dead in the integrator but public. Fix:
-  if length `< 1e-6`, fall back to the normal. (Also rename the misleading `len2` → `inv_len`.)
-- **F18** `core/geom/vec3/v3_orthonormal_matrix_from_normal.js:26` does `1/v3_length(o1)` with no
-  zero guard; a `(0,0,0)` input → NaN basis. Largely contained downstream (`v3_matrix4_rotate`
-  zeroes degenerate normals, `v3_matrix3_rotate` has a length guard that yields a zero direction),
-  so worst realistic outcome is a rare prematurely-terminated sample, not NaN pixels. Fix: substitute
-  a fixed fallback axis when `o1` length ≈ 0.
-
----
-
-## 5. Output / display (driver — `prototypePathTracer.js`)
-
-### F7 — No tone mapping before the sRGB OETF (`high`, driver-scope)
-
-`prototypePathTracer.js:486-494`. After averaging, the pipeline is `linear_to_sRGB` →
-`float_to_uint8` with **no** tone-mapping operator. `linear_to_sRGB` is the display transfer
-function (OETF), not a dynamic-range compressor; for input `> 1` it returns `> 1` and
-`float_to_uint8` hard-clamps to 255. Path-traced radiance is unbounded HDR (sponza sun intensity 3,
-plus — until F2 lands — unnormalized diffuse direct light), so bright regions collapse to flat white
-and per-channel clipping skews hue.
-
-Fix: insert a tone map between averaging and the OETF — luminance-based Reinhard or a fitted ACES
-curve, optionally with an exposure control. Driver-only; does not touch the integrator. (Note F2
-will change the lighting scale by π, so add the tone map *after* the radiometric fixes and re-tune
-exposure together.)
-
----
-
-## 6. Testing & validation
-
-Per project conventions: run Jest from the repo root `H:/git/moh` using the root `jest.conf.json`;
-write **black-box** tests (assert observable radiance, never call counts/private paths); use **real**
-objects, not mocks; and follow **correctness-first** (no loosened tolerances to make a test pass).
-`assert.*` is stripped in prod, so don't write rejection tests against asserts.
-
-Recommended new gate (`PathTracer.spec.js` or similar), added as part of Phase 1 so the radiometric
-fixes are locked:
-
-1. **White-furnace / energy-conservation test.** Constant albedo `a`, uniform environment radiance
-   `L` (set `__background_sampler` to a constant), no analytic lights, many samples/bounces with RR
-   on. Expected converged radiance for a Lambertian closed/uniform field is `a·L/(1-a)`-style energy
-   balance; at minimum, **`a=1` must not lose energy** (converges to `L`, not a darkening series).
-   This single test catches F1 (RR bias) and F3 (environment GI) regressions.
-2. **Direct-vs-indirect ratio test.** A lit Lambertian plane: compare the NEE direct term against a
-   path-traced indirect estimate of the same configuration; they must be consistent (catches F2's
-   π imbalance). A furnace test with a single light also surfaces the missing `1/π`.
-3. **Primary-miss background test.** Non-black `__background_sampler`; a ray that misses must return
-   the background color (catches F3's multiply-vs-assign).
-4. **Point-light occlusion test.** Occluder placed *behind* the light within `radius`: the shaded
-   point must remain lit (catches F8).
-5. **AABB slab edge test** (extend `aabb3_intersects_ray_segment.spec.js`): origin exactly on a face
-   plane with an axis-aligned direction transiting the box — must hit (catches F16).
-6. **Non-finite hardening test** for `float_to_uint8(NaN/±Inf)` → defined finite bytes (F11).
-
-Reference-image / scene-level checks (`prepare_scene_rtiw`, `gi_box_01`, sponza) are useful for F4–
-F7 but are harder to assert numerically; treat them as manual visual confirmation after the unit
-gates pass.
-
----
-
-## 7. Checked and dismissed (NOT bugs)
-
-These were raised during review and **verified to be correct** — recorded so they aren't re-flagged:
-
-- **Non-uniform-scale ray distance handling is correct.** `ray3_interval_array_apply_matrix4`
-  normalizes the local direction and rescales `tMax`; `PathTracedMesh.hit` recomputes the world
-  distance via `v3_distance`. Cross-mesh nearest-hit ordering stays consistent under scale.
-- **Interpolated/geometric normals *are* renormalized.** `sample_triangle_attribute` and
-  `construct_ray_hit_from_geometry` produce non-unit normals, but `v3_array_matrix4_rotate`
-  (→`v3_matrix4_rotate`) renormalizes before any consumer reads them (and zeroes degenerate ones).
-  The "missing renormalize" concern is unfounded.
-- **The Lambertian sampling path is radiometrically correct.** Cosine pdf `cosθ/π` cancels the
-  `albedo/π` BRDF, leaving `color_mask *= albedo`. `getBiasedNormalSample` (cos^power lobe) and
-  `random_in_hemisphere` (uniform hemisphere) are both correct.
-- **The `_ray_0[3..5]` overload is load-bearing, not dead.** The normal is copied into the direction
-  slot specifically so NEE's `dotNL` can read it; `getBiasedNormalSample` only overwrites it
-  *after* NEE. Deleting the copy would break direct lighting.
-- **Black default background is an acceptable default**, not a bug (the visible symptom is F3's
-  multiply logic, not the default value).
-- **Point-light windowed inverse-square attenuation is correct** — `radius` is the cutoff/window by
-  design (matches the production forward+ renderer's `pointLight.distance`).
-- **No firefly clamp is by design.** Adding a per-sample radiance clamp would *bias* the estimator;
-  the attenuation denominator is floored (`max(d², 0.01)`), so NEE cannot produce Inf/NaN.
-- **`sample_material` does not read uninitialized albedo** — the `PathTracedScene.sample_material`
-  wrapper sets `out[0..2] = 1` before calling it.
-
----
-
-## 8. Suggested implementation phasing
-
-1. **Phase 1 — radiometric core + regression gate.** F1, F2, F3 together, plus the white-furnace /
-   direct-vs-indirect / primary-miss tests (§6.1–6.3). Small surgical edits; biggest correctness
-   win. Expect a global brightness change (re-tune any scene light intensities afterward).
-2. **Phase 2 — material/shading correctness.** F4 (stale UV), F5 (sRGB linearization), F6 (normal
-   inverse-transpose). Visible quality, scene-dependent.
-3. **Phase 3 — lighting & robustness.** F8 (point-light shadow tMax) + test, F9 (emissive), F10
-   (self-intersection epsilon / tMin), F11 (NaN/Inf hardening).
-4. **Phase 4 — latent / core-primitive hardening.** F13, F14, F15, F16 (+ spec), F17, F18, F19.
-   Low individual impact; cheap and prevent rare crashes/speckle.
-5. **Phase 5 — bigger features (optional / separate).** F12 (metallic-roughness BRDF, likely with
-   MIS and a real `scattering_pdf` path), F7 (tone mapping in the driver). Larger design work; do
-   after the integrator is energy-correct.