@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +1,490 @@
+# 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.

package/src/engine/graphics/sh3/path_tracer/make_sky_hosek.js

@@ -2,8 +2,8 @@ import {
     sky_hosek_compute_irradiance_by_direction,
     sky_hosek_precompute
 } from "../sky/hosek/sky_hosek_compute_irradiance_by_direction.js";
-import { v3_array_scale } from "../../../../core/geom/vec3/v3_array_scale.js";
-import { v3_array_normalize } from "../../../../core/geom/vec3/v3_array_normalize.js";
+import { v3_scale_array } from "../../../../core/geom/vec3/v3_scale_array.js";
+import { v3_normalize_array } from "../../../../core/geom/vec3/v3_normalize_array.js";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
 import { max2 } from "../../../../core/math/max2.js";
 
@@ -12,7 +12,7 @@ export function make_sky_hosek(sun = [0, 1, 0], turbidity = 1, overcast = 0, alb
     const rad = new Float32Array([1, 1, 1]);
     const sun_position = new Float32Array([sun[0], sun[1], sun[2]]);
 
-    v3_array_normalize(sun_position, 0, sun_position, 0);
+    v3_normalize_array(sun_position, 0, sun_position, 0);
 
     sky_hosek_precompute(coeffs, rad, sun_position, turbidity, albedo, overcast);
 
@@ -32,7 +32,7 @@ export function make_sky_hosek(sun = [0, 1, 0], turbidity = 1, overcast = 0, alb
             d_z,
         );
 
-        v3_array_scale(v3, 0, v3, 0, value_scale);
+        v3_scale_array(v3, 0, v3, 0, value_scale);
 
         // clamp sky contribution
         v3[0] = max2(0, v3[0]);

package/src/engine/graphics/sh3/path_tracer/material/MaterialConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MaterialConverter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/material/MaterialConverter.js"],"names":[],"mappings":"AA8BA;IA4BI;;;;OAIG;IACH,kBAHW,MAAM,QAAQ,GACZ,gBAAgB,CAyC5B;;CAEJ;iCApGgC,uBAAuB"}
+{"version":3,"file":"MaterialConverter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/material/MaterialConverter.js"],"names":[],"mappings":"AA+BA;IA+BI;;;;OAIG;IACH,kBAHW,MAAM,QAAQ,GACZ,gBAAgB,CA6C5B;;CAEJ;iCA3GgC,uBAAuB"}

package/src/engine/graphics/sh3/path_tracer/material/MaterialConverter.js

@@ -1,4 +1,5 @@
-import { Color } from "three";
+import { Color, sRGBEncoding } from "three";
+import { sRGB_to_linear } from "../../../../../core/color/sRGB/sRGB_to_linear.js";
 import { convertTexture2Sampler2D } from "../../../texture/sampler/convertTexture2Sampler2D.js";
 import { sampler2d_multiply_vector } from "../../../texture/sampler/sampler2d_multiply_vector.js";
 import { iterate_three_material_textures } from "../../../three/material/iterate_three_material_textures.js";
@@ -51,6 +52,9 @@ export class MaterialConverter {
 
         const st = StandardTexture.from(sampler2D);
 
+        // base-color/emissive maps are sRGB-authored and must be decoded to linear at sample time
+        st.decode_sRGB = texture.encoding === sRGBEncoding;
+
         this.#textures.set(texture.id, st);
 
         return st;
@@ -94,7 +98,11 @@ export class MaterialConverter {
 
             tinted_diffuse.sampler = tinted_diffuse.sampler.clone();
 
-            sampler2d_multiply_vector(tinted_diffuse.sampler, result.diffuse.sampler, material.color.toArray());
+            // the tint colour is sRGB-authored; linearize it to match the linear renderer
+            const tint = material.color.toArray();
+            sRGB_to_linear(tint, 0, tint, 0);
+
+            sampler2d_multiply_vector(tinted_diffuse.sampler, result.diffuse.sampler, tint);
 
             result.diffuse = tinted_diffuse;
         }

package/src/engine/graphics/sh3/path_tracer/material/StandardTexture.d.ts

@@ -14,6 +14,12 @@ export class StandardTexture {
     type: BinaryDataType;
     wrapS: number;
     wrapT: number;
+    /**
+     * When true, the sampler holds sRGB-authored data (base color / emissive) that is decoded to
+     * linear at sample time. Data channels (normal/roughness/metalness) leave this false.
+     * @type {boolean}
+     */
+    decode_sRGB: boolean;
     /**
      *
      * @param {StandardTexture} other

package/src/engine/graphics/sh3/path_tracer/material/StandardTexture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StandardTexture.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/material/StandardTexture.js"],"names":[],"mappings":"AAQA;IAgCI;;;;OAIG;IACH,iCAFa,eAAe,CAQ3B;IA1CD,WAAkB;IAElB;;OAEG;IACH,mBAAO;IACP,kBAAsC;IACtC,qBAA2B;IAC3B,cAA2C;IAC3C,cAA2C;IAE3C;;;OAGG;IACH,YAFW,eAAe,QAQzB;IAED,yBAMC;IAeD;;;;;OAKG;IACH,YAJW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,KACN,MAAM,QA6BhB;CACJ;+BAvF8B,mDAAmD"}
+{"version":3,"file":"StandardTexture.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/material/StandardTexture.js"],"names":[],"mappings":"AASA;IAwCI;;;;OAIG;IACH,iCAFa,eAAe,CAQ3B;IAlDD,WAAkB;IAElB;;OAEG;IACH,mBAAO;IACP,kBAAsC;IACtC,qBAA2B;IAC3B,cAA2C;IAC3C,cAA2C;IAE3C;;;;OAIG;IACH,aAFU,OAAO,CAEE;IAEnB;;;OAGG;IACH,YAFW,eAAe,QASzB;IAED,yBAMC;IAeD;;;;;OAKG;IACH,YAJW,MAAM,EAAE,GAAC,YAAY,KACrB,MAAM,KACN,MAAM,QAkChB;CACJ;+BArG8B,mDAAmD"}

package/src/engine/graphics/sh3/path_tracer/material/StandardTexture.js

@@ -1,4 +1,5 @@
 import { BinaryDataType } from "../../../../../core/binary/type/BinaryDataType.js";
+import { sRGB_to_linear } from "../../../../../core/color/sRGB/sRGB_to_linear.js";
 import { apply_texture_clamping_to_coordinate } from "../texture/apply_texture_clamping_to_coordinate.js";
 import { vec3_uint8_to_float } from "../vec3_uint8_to_float.js";
 import { TextureFilter } from "./TextureFilter.js";
@@ -18,6 +19,13 @@ export class StandardTexture {
     wrapS = TextureWrapping.ClampToEdgeWrapping
     wrapT = TextureWrapping.ClampToEdgeWrapping
 
+    /**
+     * When true, the sampler holds sRGB-authored data (base color / emissive) that is decoded to
+     * linear at sample time. Data channels (normal/roughness/metalness) leave this false.
+     * @type {boolean}
+     */
+    decode_sRGB = false
+
     /**
      *
      * @param {StandardTexture} other
@@ -28,6 +36,7 @@ export class StandardTexture {
         this.type = other.type
         this.wrapS = other.wrapS
         this.wrapT = other.wrapT
+        this.decode_sRGB = other.decode_sRGB
     }
 
     clone() {
@@ -84,5 +93,10 @@ export class StandardTexture {
         if (this.type === BinaryDataType.Uint8) {
             vec3_uint8_to_float(out, out);
         }
+
+        if (this.decode_sRGB) {
+            // decode sRGB-authored color into the linear space the renderer integrates in
+            sRGB_to_linear(out, 0, out, 0);
+        }
     }
 }

package/src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare_scene_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js"],"names":[],"mappings":"AAaA;;;;;qBAyBC;AAaD;;;;;;;;;;GAUG;AACH,mHAFY,QAAQ,IAAI,CAAC,CA8CxB;oBAnGmB,kCAAkC;iCAErB,qDAAqD"}
+{"version":3,"file":"prepare_scene_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js"],"names":[],"mappings":"AAeA;;;;;qBAyBC;AAaD;;;;;;;;;;GAUG;AACH,mHAFY,QAAQ,IAAI,CAAC,CA8CxB;oBAnGmB,kCAAkC;iCAErB,qDAAqD"}

package/src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js

@@ -1,9 +1,11 @@
-import { vec3 } from "gl-matrix";
 import { Box3, MeshStandardMaterial, PlaneBufferGeometry, Sphere } from "three";
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { v3_scale } from "../../../../core/geom/vec3/v3_scale.js";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { Color } from "../../../../core/color/Color.js";
 import { kelvin_to_rgb } from "../../../../core/color/kelvin/kelvin_to_rgb.js";
 import { noop } from "../../../../core/function/noop.js";
+import { v3_multiply } from "../../../../core/geom/vec3/v3_multiply.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { Transform } from "../../../ecs/transform/Transform.js";
@@ -25,10 +27,10 @@ export function make_sun({
     const light = new DirectionalLight();
 
     light.color.parse(color);
-    vec3.multiply(light.color, light.color, temp_c);
+    v3_multiply(light.color, 0, light.color[0], light.color[1], light.color[2], temp_c[0], temp_c[1], temp_c[2]);
 
-    const n = vec3.length(light.color);
-    vec3.scale(light.color, light.color, 1 / n); // normalize color vector
+    const n = v3_length(light.color[0], light.color[1], light.color[2]);
+    v3_scale(light.color, 0, light.color[0], light.color[1], light.color[2], 1 / n); // normalize color vector
 
     light.intensity.set(intensity * n);
     light.direction.copy(direction);