@woosh/meep-engine 3.1.0 → 3.2.0

package/src/REVIEW_2026_08_06/gfx-gi.md

@@ -1,143 +1,143 @@
-# Correctness review — `engine/graphics/` (excluding ecs/, render/, texture/, particular/, geometry/)
-
-three.js r136. Verified against `H:/git/moh/node_modules/three/src/renderers/**` where three semantics were load-bearing.
-
----
-
-### GFXG-1 LPV GI vertex injection reads `worldPosition`, which three only declares conditionally
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/sh3/gi/material/space_fragment/build_vertex_shader.js:21` (also `.../sh3/gi/material/space_vertex/build_vertex_shader.js:12`, `:14`, `:23`)
-- **Defect**: Both LPV vertex-shader builders insert code that reads `worldPosition` after `#include <fog_vertex>`. In three r136 `worldpos_vertex.glsl.js` declares `vec4 worldPosition` only inside `#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined ( USE_SHADOWMAP ) || defined ( USE_TRANSMISSION )`. With none of those defines the identifier does not exist.
-- **Failure scenario**: A `MeshStandardMaterial` mesh (no envMap, no transmission) in a scene whose only lights are ambient + a non-shadow-casting directional light, registered with `graphics/sh3/gi/material/MaterialTransformer`. `USE_SHADOWMAP` is not defined, so the injected `vWorldPosition = worldPosition.xyz;` (fragment-space variant) / `lpv_guess_initial_tet( worldPosition.xyz )` (vertex-space variant) hits `'worldPosition' : undeclared identifier`. three logs a shader-compile error and the mesh renders with the fallback program — i.e. the object disappears/renders black. Turning shadows on for one light makes it compile again, which is exactly the kind of "works on my scene" trap this hides behind.
-- **Fix**: Do what the newer LPG builders already do (`sh3/lpg/material/space_fragment/build_vertex_shader.js:20-32` documents this exact hazard): compute the world position locally from the `position` attribute —
-  ```glsl
-  vec4 lpv_world_position = vec4( position, 1.0 );
-  #ifdef USE_INSTANCING
-      lpv_world_position = instanceMatrix * lpv_world_position;
-  #endif
-  lpv_world_position = modelMatrix * lpv_world_position;
-  ```
-  and use that instead of `worldPosition`.
-- **Confidence**: Confirmed
-
----
-
-### GFXG-2 Impostor bake leaves `tNormal` unbound when the source material has no normal map
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/bake/prepare_bake_material.js:100`
-- **Defect**: Every other texture slot gets a 1×1 fallback when the source material lacks it (`tDiffuse` white, `tRoughness` white, `tMetalness` black, `tOcclusion` white, `tEmissive` black), but `texture_normal` is left `null` and assigned straight through. A `null` `sampler2D` uniform binds three's default empty texture, which `WebGLState.createTexture` uploads from `new Uint8Array(4)` — i.e. **black**, not (0.5, 0.5, 1).
-- **Failure scenario**: Bake an octahedral impostor of any `MeshStandardMaterial` without a `normalMap` — the common case for props. In `BakeShaderStandard` the fragment does `normal_sample = texture(tNormal, uv).rgb * 2.0 - 1.0` → `(-1,-1,-1)`, then `normal = normalize(TBN * (-1,-1,-1))` = `normalize(-T - B - N)`. The `gNormal` atlas channel therefore stores a normal ~125° away from the true surface normal, pointing *into* the surface. `ImpostorShaderLitV0` and `ImpostorShaderNormalsV0` then shade the impostor with that normal: a tree impostor lit from above renders dark/inverted, and the whole card shades as if lit from behind.
-- **Fix**: Add the missing fallback next to the others, e.g.
-  ```js
-  if (texture_normal === null) {
-      texture_normal = makeOnePixelTexture([128, 128, 255, 255], cleanup_signal);
-  }
-  ```
-  (before the anisotropy loop, so the `null` skip in that loop becomes unnecessary).
-- **Confidence**: Confirmed
-
----
-
-### GFXG-3 `TerrainShader` uses the pre-r135 fog varying name `fogDepth`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/shaders/TerrainShader.js:361` and `:363`
-- **Defect**: The hand-rolled fog block reads `fogDepth`. three r136 renamed the varying to `vFogDepth` (`fog_pars_fragment.glsl.js:5`, `fog_vertex.glsl.js:4`); `fogDepth` is declared nowhere. The block is guarded by `#ifdef USE_FOG`, so it only bites when fog is actually enabled.
-- **Failure scenario**: `scene.fog = new Fog(0x808080, 10, 200)` on a scene containing terrain. `USE_FOG` becomes defined (ShaderMaterial's `fog` defaults to `true` and `SplatMaterial` does not turn it off), the fragment shader fails to compile with `'fogDepth' : undeclared identifier`, and the entire terrain stops rendering. Removing the fog makes it work again.
-- **Fix**: Rename both uses to `vFogDepth`. Better: replace the whole hand-copied block with `#include <fog_fragment>` (it is byte-identical apart from the name) so the next three bump cannot desync it again.
-- **Confidence**: Confirmed
-
----
-
-### GFXG-4 `MaterialManager` de-duplicates `ShaderMaterial`s without comparing shader source, defines or uniforms
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/material/manager/MaterialManager.js:181` (`__library` lookup; hash/equality supplied at `:14-18`)
-- **Defect**: `__library` is a `HashMap` keyed with `computeMaterialHash` / `computeMaterialEquality`. For `isShaderMaterial` those two only fold in the generic `Material` flags plus `material.lights` — `vertexShader`, `fragmentShader`, `defines` and `uniforms` are never inspected. Two structurally different custom shader materials with matching blend/side/depth/transparent flags therefore compare *equal*, and `obtain()` hands the second caller the first material's managed instance.
-- **Failure scenario**: Two `Trail3D` entities with `TubeXMaterialSpec` `{diffuse: "smoke.png", lit:false, depthWrite:false}` and `{diffuse: "spark.png", lit:false, depthWrite:false}`. `TubeXPlugin` correctly builds two distinct `TubeMaterialX` (its own cache is keyed on the spec), then calls `graphics.getMaterialManager().obtain(material)` for each (`TubeXPlugin.js:84`). The second `obtain` hits the `__library` entry of the first — identical `type` `'ShaderMaterial'`, identical flags, both still carrying the default prototype `onBeforeCompile` — and returns the first material. Both trails render with `smoke.png`. Same collision hits `{diffuse: null}` vs `{diffuse: "x.png"}` (the second trail renders untextured, since `USE_TEXTURE` lives in `defines`), and any two `SplatMaterial`s (two terrains would share one splat/diffuse atlas set).
-- **Fix**: Extend the key for shader materials. In `computeMaterialHash` / `computeMaterialEquality`, when `material.isShaderMaterial`, also fold in `vertexShader`, `fragmentShader` and the `defines` entries (a stable `JSON.stringify` of `defines` plus `computeStringHash` of the two sources is enough), and treat materials whose `uniforms` objects are not identity-equal as distinct.
-- **Confidence**: Confirmed
-
----
-
-### GFXG-5 SH probe visualiser uses the signed real-SH basis while every probe in the engine is projected with the unsigned one
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/sh3/shader/visualize.frag.js:19`, `:21`, `:25`, `:27`
-- **Defect**: `shGetIrradianceAt` in the visualiser subtracts bands 1 (`y`, `x`), 2·(`yz`), 2·(`xz`). Every projection path in the engine writes coefficients with `sh3_basis_at` (`core/geom/3d/sphere/harmonics/sh3_basis_at.js`), which is all-positive, and the two runtime GI evaluators (`sh3/gi/material/chunk_lpv_get_irradiance_at.js`, `sh3/lpg/material/chunk_lpg_get_irradiance_at.js`) and three's own `shGetIrradianceAt` (`lights_pars_begin.glsl.js:18-27`) are all-positive too. The visualiser is the only evaluator using the opposite sign convention.
-- **Failure scenario**: Bake an LPV/LPG probe in a room lit by a single light directly overhead, then call `visualise_spherical_harmonic_sphere({ sh, position })`. Band 1 dominates; flipping its sign mirrors the directional lobe through the origin, so the debug sphere renders **bright on the bottom and dark on the top** — the exact opposite of the probe the renderer is actually using. Anyone using this to debug a GI bake gets sent the wrong way.
-- **Fix**: Change the four `-=` back to `+=` so the visualiser matches `chunk_lpv_get_irradiance_at` / three. (Better still: emit `chunk_lpv_get_irradiance_at` here instead of a third hand-written copy of the same nine lines.)
-- **Confidence**: Confirmed
-
----
-
-### GFXG-6 Lit impostor materials break the Forward+ contract — no `#include <worldpos_vertex>` marker
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/ImpostorShaderLitV0.js:225`; `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/voxel/shader/VoxelImpostorShaderLitV0.js:97`
-- **Defect**: Both are custom **lit** (`lights: true`) `ShaderMaterial`s. Both declare `vec4 worldPosition = ...` inline instead of going through `#include <worldpos_vertex>`. `fp_build_vertex_shader` (`render/forward_plus/materials/fp_build_vertex_shader.js:20`) keys its only vertex-side injection on that exact literal and `insert_after` merely `console.warn`s and returns the source unchanged when the marker is missing. The fragment side still gets `varying vec3 v_world_position;` injected, so the varying exists but is never written.
-- **Failure scenario**: Put a baked tree impostor at world (100, 0, 100) under Forward+ and drop a decal (blood splat, scorch mark) on it. `FP_SHADER_CHUNK_APPLY_DECALS` computes `decal_transform_matrix * vec4(v_world_position, 1.0)` with `v_world_position` never assigned (reads as 0), so the test is evaluated at the world origin: `max3(abs(local_position.xyz)) < 0.5` fails for every decal that is not at the origin, and the impostor never receives any decal. Conversely a decal placed near the origin uniformly floods the whole impostor card. Console shows `Term '#include <worldpos_vertex>' not found in the source`.
-- **Fix**: In both vertex shaders, replace the inline `vec4 worldPosition = ...` with the marker, computing the intermediate through `transformed` so the chunk produces the right value:
-  ```glsl
-  vec3 transformed = pos_OS;          // octahedral variant; centre_world basis for the voxel one
-  #include <worldpos_vertex>
-  #if !( defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) )
-      vec4 worldPosition = modelMatrix * vec4( transformed, 1.0 );
-  #endif
-  ```
-  (the `#if` mirrors what `TerrainShader.js:66-68` already does).
-- **Confidence**: Confirmed
-
----
-
-### GFXG-7 Impostor bake builds the tangent with `tangent.w` as the homogeneous coordinate
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/BakeShaderStandard.js:38`
-- **Defect**: `vec3 T = normalize(vec3(modelViewMatrix * tangent));` — `tangent` is a `vec4` whose `w` is the glTF handedness sign (±1), not a homogeneous coordinate. Multiplying the full `vec4` by `modelViewMatrix` adds `w ×` the model-view **translation** into the tangent. The default attribute value set at `:192` is `[1, 0, 0, 1]`, so `w = 1` even for meshes with no tangents.
-- **Failure scenario**: Bake an impostor of a mesh that *does* have a normal map. The bake camera sits `distance` units from the bounding-sphere centre (`ImpostorBaker.js:216-222`), so `modelViewMatrix[3].xyz ≈ (0, 0, -distance)`. For a 2 m prop, `T = normalize((tangent.xyz) + (0,0,-2))` ≈ `(0,0,-1)`, i.e. almost exactly the view direction and therefore almost anti-parallel to the surface normal `N` for front-facing texels. `B = cross(N, T)` collapses toward zero and `normalize(TBN * normal_sample)` produces a near-random perturbed normal. The impostor's `gNormal` channel is wrong across the whole silhouette, and the lit impostor shades with visible per-frame normal popping as the camera orbits. With a handedness of `w = -1` (mirrored UV islands) the tangent additionally points the wrong way.
-- **Fix**: `vec3 T = normalize( mat3(modelViewMatrix) * tangent.xyz );` and apply the handedness to the bitangent: `vec3 B = cross(N, T) * tangent.w;`. Set `defaultAttributeValues.tangent = [1, 0, 0, 1]` unchanged — with `.xyz` extraction it now means "object-space +X, right-handed", which is a sane default.
-- **Confidence**: Confirmed
-
----
-
-### GFXG-8 `DenoiseShader` never passes `filterSmoothness` to the shader — the bilateral term is inert
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/shaders/DenoiseShader.js:96-98`
-- **Defect**: The shader reads the spatial sigma from `sigmas.x` and the **range** sigma (`bSigma`, the edge-preserving term) from `sigmas.y` (`:31`, `:34`). JS initialises the uniform as `new Vector2(sigma, sigma)`, so `bSigma` gets the spatial sigma. The `filterSmoothness` argument only survives into `bZnorm` (`:71`), which is a constant factor that cancels out against `accumulatedFactor` in the final `accumulatedColor / accumulatedFactor` normalisation. `filterSmoothness` therefore has literally no effect on the output.
-- **Failure scenario**: `heightMap2AOMap` calls `new DenoiseShader(2)` (`engine/ecs/grid/HeightMap2AOMap.js:76`), intending sigma = 2 spatial, 0.2 range. The shader gets `bSigma = 2`, so `normpdf3(rgba.rgb - pixel.rgb, 2.0)` ≈ `0.199 · exp(-Δ²/8)` — for AO values in [0,1] the exponent never drops below `exp(-0.375) ≈ 0.69`, i.e. the range weight is nearly constant. The "edge-preserving bilateral filter" degrades into a plain 15×15 Gaussian blur, and the terrain AO map smears occlusion across cliff bases and ridge lines instead of holding those edges.
-- **Fix**: `sigmas: { type: "v2", value: new Vector2(sigma, filterSmoothness) }`.
-- **Confidence**: Confirmed
-
----
-
-### GFXG-9 Uninitialised accumulator in the impostor bake supersampler
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/BakeShaderStandard.js:95`
-- **Defect**: `vec4 col;` is declared without an initialiser and then accumulated into with `col += texture(...)` four times. GLSL ES 3.00 leaves uninitialised local variables undefined; there is no guarantee of zero-fill and drivers differ (desktop NVIDIA/AMD commonly zero, several mobile/Adreno and ANGLE-on-D3D configurations do not).
-- **Failure scenario**: Run `ImpostorBaker.bake()` on a driver that does not zero-initialise locals. Every call to `texture_supersample_4` returns `garbage + Σ(4 samples) · 0.25`, so the baked atlas's colour, normal+depth and ORM channels are all offset by a per-invocation constant. The impostor comes out with a uniform colour cast, wrong depths (the `.a` channel feeds the parallax and the shadow-caster height) and a shifted normal — and the bake is cached to disk, so the corruption persists.
-- **Fix**: `vec4 col = vec4(0.0);`
-- **Confidence**: Likely (unconditionally undefined per spec; the visible symptom is driver-dependent)
-
----
-
-## Status of the "already known" list
-
-| Item | Status |
-|---|---|
-| LPV GI vertex shader walks the tetrahedral mesh in object space (`gi/material/space_vertex/build_vertex_shader.js:18`) | Still open — `lpv_walk_to_tetrahedron(position, …)` unchanged; note GFXG-1 sits on top of it in the same block |
-| Path-tracer material conversion drops texture wrap mode | Not re-examined (excluded from write-up per brief) |
-| Path-tracer tint linearized twice | Not re-examined (excluded per brief) |
-| Path-tracer emissive colour/intensity dropped | Not re-examined (excluded per brief) |
-| `WaterShader` references r136-removed `ShaderChunk` symbols | Still open — `lights_pars` (×2, `:22`/`:78`) and `linear_to_gamma_fragment` (`:142`) resolve to `undefined` and are `join`ed into the source as the literal text `undefined`; `BRDF_Diffuse_Lambert` (`:112`, `:124`) also no longer exists |
-| Water never disposes its DataTexture/geometry/material | Not re-examined (no `water/` directory in scope; `material/WaterMaterial.js` has no dispose path) |
-| AO `ShaderMaterial` leak on shutdown | Not re-examined (lives under `render/`, out of scope) |
-| Stale `projectionMatrixInverse` after a projection modifier | Not re-examined (out of scope) |
-| `DepthLimitedBlur` dropping `format` | Not re-examined (`render/`, out of scope) |
-| `NormalFrameBuffer` shared-material wrong normals | Not re-examined (`render/`, out of scope) |
-| Lightmap T-junction shading-normal carry | Not re-examined (excluded per brief) |
-| `set_environment_texture` leaking PMREM targets | Still open — `GraphicsEngine.js:401/405/415` dispose the PMREM generator and the previous target, so the specific leak may already be addressed; not investigated further |
-
-## Notes on things deliberately NOT reported
-
-- `sh3/gi/material/MaterialTransformer.js:311` `result.clone();` discards its return value. It is a dead statement, not a behaviour change — the transformer is *supposed* to mutate the source in place (the newer `LightProbeGridMaterialTransformer.transform` does exactly that without the stray clone).
-- `VecToSphereOct` in the impostor shaders uses GLSL `sign()` (returns 0 at 0) where the CPU baker uses `sign_not_zero`. The divergence only manifests for camera directions with an exactly-zero X or Z component *and* negative Y — measure-zero and, for the hemisphere capture mode, unreachable.
-- `HemiOctahedralUvEncoder` does not override `unit_to_uv`, so the inherited `throw new Error('Not implemented')` fires. No caller reaches it and there is no scene that produces a wrong render from it.
-- Uninitialised `LayerCompositer`/`CompositLayer` material disposal and the `DataTexture` allocated in `HeightMap2AOMap` are small one-shot leaks with no visible rendering consequence.
-- `ImageFilter.processTexture` calls `renderer.setSize()` and never restores it, but its only caller drives it through `WebGLRendererPool.global`, i.e. an offscreen renderer, so the main canvas is unaffected.
-- `TubeMaterialX`'s lit branch feeds the `color/255` vertex colour to the light chain as a linear value and then runs `<encodings_fragment>`, whereas the unlit branch writes it raw. This matches three's own vertex-colour convention, so it is a convention choice rather than a defect.
+# Correctness review — `engine/graphics/` (excluding ecs/, render/, texture/, particular/, geometry/)
+
+three.js r136. Verified against `H:/git/moh/node_modules/three/src/renderers/**` where three semantics were load-bearing.
+
+---
+
+### GFXG-1 LPV GI vertex injection reads `worldPosition`, which three only declares conditionally
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/sh3/gi/material/space_fragment/build_vertex_shader.js:21` (also `.../sh3/gi/material/space_vertex/build_vertex_shader.js:12`, `:14`, `:23`)
+- **Defect**: Both LPV vertex-shader builders insert code that reads `worldPosition` after `#include <fog_vertex>`. In three r136 `worldpos_vertex.glsl.js` declares `vec4 worldPosition` only inside `#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined ( USE_SHADOWMAP ) || defined ( USE_TRANSMISSION )`. With none of those defines the identifier does not exist.
+- **Failure scenario**: A `MeshStandardMaterial` mesh (no envMap, no transmission) in a scene whose only lights are ambient + a non-shadow-casting directional light, registered with `graphics/sh3/gi/material/MaterialTransformer`. `USE_SHADOWMAP` is not defined, so the injected `vWorldPosition = worldPosition.xyz;` (fragment-space variant) / `lpv_guess_initial_tet( worldPosition.xyz )` (vertex-space variant) hits `'worldPosition' : undeclared identifier`. three logs a shader-compile error and the mesh renders with the fallback program — i.e. the object disappears/renders black. Turning shadows on for one light makes it compile again, which is exactly the kind of "works on my scene" trap this hides behind.
+- **Fix**: Do what the newer LPG builders already do (`sh3/lpg/material/space_fragment/build_vertex_shader.js:20-32` documents this exact hazard): compute the world position locally from the `position` attribute —
+  ```glsl
+  vec4 lpv_world_position = vec4( position, 1.0 );
+  #ifdef USE_INSTANCING
+      lpv_world_position = instanceMatrix * lpv_world_position;
+  #endif
+  lpv_world_position = modelMatrix * lpv_world_position;
+  ```
+  and use that instead of `worldPosition`.
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-2 Impostor bake leaves `tNormal` unbound when the source material has no normal map
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/bake/prepare_bake_material.js:100`
+- **Defect**: Every other texture slot gets a 1×1 fallback when the source material lacks it (`tDiffuse` white, `tRoughness` white, `tMetalness` black, `tOcclusion` white, `tEmissive` black), but `texture_normal` is left `null` and assigned straight through. A `null` `sampler2D` uniform binds three's default empty texture, which `WebGLState.createTexture` uploads from `new Uint8Array(4)` — i.e. **black**, not (0.5, 0.5, 1).
+- **Failure scenario**: Bake an octahedral impostor of any `MeshStandardMaterial` without a `normalMap` — the common case for props. In `BakeShaderStandard` the fragment does `normal_sample = texture(tNormal, uv).rgb * 2.0 - 1.0` → `(-1,-1,-1)`, then `normal = normalize(TBN * (-1,-1,-1))` = `normalize(-T - B - N)`. The `gNormal` atlas channel therefore stores a normal ~125° away from the true surface normal, pointing *into* the surface. `ImpostorShaderLitV0` and `ImpostorShaderNormalsV0` then shade the impostor with that normal: a tree impostor lit from above renders dark/inverted, and the whole card shades as if lit from behind.
+- **Fix**: Add the missing fallback next to the others, e.g.
+  ```js
+  if (texture_normal === null) {
+      texture_normal = makeOnePixelTexture([128, 128, 255, 255], cleanup_signal);
+  }
+  ```
+  (before the anisotropy loop, so the `null` skip in that loop becomes unnecessary).
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-3 `TerrainShader` uses the pre-r135 fog varying name `fogDepth`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/shaders/TerrainShader.js:361` and `:363`
+- **Defect**: The hand-rolled fog block reads `fogDepth`. three r136 renamed the varying to `vFogDepth` (`fog_pars_fragment.glsl.js:5`, `fog_vertex.glsl.js:4`); `fogDepth` is declared nowhere. The block is guarded by `#ifdef USE_FOG`, so it only bites when fog is actually enabled.
+- **Failure scenario**: `scene.fog = new Fog(0x808080, 10, 200)` on a scene containing terrain. `USE_FOG` becomes defined (ShaderMaterial's `fog` defaults to `true` and `SplatMaterial` does not turn it off), the fragment shader fails to compile with `'fogDepth' : undeclared identifier`, and the entire terrain stops rendering. Removing the fog makes it work again.
+- **Fix**: Rename both uses to `vFogDepth`. Better: replace the whole hand-copied block with `#include <fog_fragment>` (it is byte-identical apart from the name) so the next three bump cannot desync it again.
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-4 `MaterialManager` de-duplicates `ShaderMaterial`s without comparing shader source, defines or uniforms
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/material/manager/MaterialManager.js:181` (`__library` lookup; hash/equality supplied at `:14-18`)
+- **Defect**: `__library` is a `HashMap` keyed with `computeMaterialHash` / `computeMaterialEquality`. For `isShaderMaterial` those two only fold in the generic `Material` flags plus `material.lights` — `vertexShader`, `fragmentShader`, `defines` and `uniforms` are never inspected. Two structurally different custom shader materials with matching blend/side/depth/transparent flags therefore compare *equal*, and `obtain()` hands the second caller the first material's managed instance.
+- **Failure scenario**: Two `Trail3D` entities with `TubeXMaterialSpec` `{diffuse: "smoke.png", lit:false, depthWrite:false}` and `{diffuse: "spark.png", lit:false, depthWrite:false}`. `TubeXPlugin` correctly builds two distinct `TubeMaterialX` (its own cache is keyed on the spec), then calls `graphics.getMaterialManager().obtain(material)` for each (`TubeXPlugin.js:84`). The second `obtain` hits the `__library` entry of the first — identical `type` `'ShaderMaterial'`, identical flags, both still carrying the default prototype `onBeforeCompile` — and returns the first material. Both trails render with `smoke.png`. Same collision hits `{diffuse: null}` vs `{diffuse: "x.png"}` (the second trail renders untextured, since `USE_TEXTURE` lives in `defines`), and any two `SplatMaterial`s (two terrains would share one splat/diffuse atlas set).
+- **Fix**: Extend the key for shader materials. In `computeMaterialHash` / `computeMaterialEquality`, when `material.isShaderMaterial`, also fold in `vertexShader`, `fragmentShader` and the `defines` entries (a stable `JSON.stringify` of `defines` plus `computeStringHash` of the two sources is enough), and treat materials whose `uniforms` objects are not identity-equal as distinct.
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-5 SH probe visualiser uses the signed real-SH basis while every probe in the engine is projected with the unsigned one
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/sh3/shader/visualize.frag.js:19`, `:21`, `:25`, `:27`
+- **Defect**: `shGetIrradianceAt` in the visualiser subtracts bands 1 (`y`, `x`), 2·(`yz`), 2·(`xz`). Every projection path in the engine writes coefficients with `sh3_basis_at` (`core/geom/3d/sphere/harmonics/sh3_basis_at.js`), which is all-positive, and the two runtime GI evaluators (`sh3/gi/material/chunk_lpv_get_irradiance_at.js`, `sh3/lpg/material/chunk_lpg_get_irradiance_at.js`) and three's own `shGetIrradianceAt` (`lights_pars_begin.glsl.js:18-27`) are all-positive too. The visualiser is the only evaluator using the opposite sign convention.
+- **Failure scenario**: Bake an LPV/LPG probe in a room lit by a single light directly overhead, then call `visualise_spherical_harmonic_sphere({ sh, position })`. Band 1 dominates; flipping its sign mirrors the directional lobe through the origin, so the debug sphere renders **bright on the bottom and dark on the top** — the exact opposite of the probe the renderer is actually using. Anyone using this to debug a GI bake gets sent the wrong way.
+- **Fix**: Change the four `-=` back to `+=` so the visualiser matches `chunk_lpv_get_irradiance_at` / three. (Better still: emit `chunk_lpv_get_irradiance_at` here instead of a third hand-written copy of the same nine lines.)
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-6 Lit impostor materials break the Forward+ contract — no `#include <worldpos_vertex>` marker
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/ImpostorShaderLitV0.js:225`; `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/voxel/shader/VoxelImpostorShaderLitV0.js:97`
+- **Defect**: Both are custom **lit** (`lights: true`) `ShaderMaterial`s. Both declare `vec4 worldPosition = ...` inline instead of going through `#include <worldpos_vertex>`. `fp_build_vertex_shader` (`render/forward_plus/materials/fp_build_vertex_shader.js:20`) keys its only vertex-side injection on that exact literal and `insert_after` merely `console.warn`s and returns the source unchanged when the marker is missing. The fragment side still gets `varying vec3 v_world_position;` injected, so the varying exists but is never written.
+- **Failure scenario**: Put a baked tree impostor at world (100, 0, 100) under Forward+ and drop a decal (blood splat, scorch mark) on it. `FP_SHADER_CHUNK_APPLY_DECALS` computes `decal_transform_matrix * vec4(v_world_position, 1.0)` with `v_world_position` never assigned (reads as 0), so the test is evaluated at the world origin: `max3(abs(local_position.xyz)) < 0.5` fails for every decal that is not at the origin, and the impostor never receives any decal. Conversely a decal placed near the origin uniformly floods the whole impostor card. Console shows `Term '#include <worldpos_vertex>' not found in the source`.
+- **Fix**: In both vertex shaders, replace the inline `vec4 worldPosition = ...` with the marker, computing the intermediate through `transformed` so the chunk produces the right value:
+  ```glsl
+  vec3 transformed = pos_OS;          // octahedral variant; centre_world basis for the voxel one
+  #include <worldpos_vertex>
+  #if !( defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) )
+      vec4 worldPosition = modelMatrix * vec4( transformed, 1.0 );
+  #endif
+  ```
+  (the `#if` mirrors what `TerrainShader.js:66-68` already does).
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-7 Impostor bake builds the tangent with `tangent.w` as the homogeneous coordinate
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/BakeShaderStandard.js:38`
+- **Defect**: `vec3 T = normalize(vec3(modelViewMatrix * tangent));` — `tangent` is a `vec4` whose `w` is the glTF handedness sign (±1), not a homogeneous coordinate. Multiplying the full `vec4` by `modelViewMatrix` adds `w ×` the model-view **translation** into the tangent. The default attribute value set at `:192` is `[1, 0, 0, 1]`, so `w = 1` even for meshes with no tangents.
+- **Failure scenario**: Bake an impostor of a mesh that *does* have a normal map. The bake camera sits `distance` units from the bounding-sphere centre (`ImpostorBaker.js:216-222`), so `modelViewMatrix[3].xyz ≈ (0, 0, -distance)`. For a 2 m prop, `T = normalize((tangent.xyz) + (0,0,-2))` ≈ `(0,0,-1)`, i.e. almost exactly the view direction and therefore almost anti-parallel to the surface normal `N` for front-facing texels. `B = cross(N, T)` collapses toward zero and `normalize(TBN * normal_sample)` produces a near-random perturbed normal. The impostor's `gNormal` channel is wrong across the whole silhouette, and the lit impostor shades with visible per-frame normal popping as the camera orbits. With a handedness of `w = -1` (mirrored UV islands) the tangent additionally points the wrong way.
+- **Fix**: `vec3 T = normalize( mat3(modelViewMatrix) * tangent.xyz );` and apply the handedness to the bitangent: `vec3 B = cross(N, T) * tangent.w;`. Set `defaultAttributeValues.tangent = [1, 0, 0, 1]` unchanged — with `.xyz` extraction it now means "object-space +X, right-handed", which is a sane default.
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-8 `DenoiseShader` never passes `filterSmoothness` to the shader — the bilateral term is inert
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/shaders/DenoiseShader.js:96-98`
+- **Defect**: The shader reads the spatial sigma from `sigmas.x` and the **range** sigma (`bSigma`, the edge-preserving term) from `sigmas.y` (`:31`, `:34`). JS initialises the uniform as `new Vector2(sigma, sigma)`, so `bSigma` gets the spatial sigma. The `filterSmoothness` argument only survives into `bZnorm` (`:71`), which is a constant factor that cancels out against `accumulatedFactor` in the final `accumulatedColor / accumulatedFactor` normalisation. `filterSmoothness` therefore has literally no effect on the output.
+- **Failure scenario**: `heightMap2AOMap` calls `new DenoiseShader(2)` (`engine/ecs/grid/HeightMap2AOMap.js:76`), intending sigma = 2 spatial, 0.2 range. The shader gets `bSigma = 2`, so `normpdf3(rgba.rgb - pixel.rgb, 2.0)` ≈ `0.199 · exp(-Δ²/8)` — for AO values in [0,1] the exponent never drops below `exp(-0.375) ≈ 0.69`, i.e. the range weight is nearly constant. The "edge-preserving bilateral filter" degrades into a plain 15×15 Gaussian blur, and the terrain AO map smears occlusion across cliff bases and ridge lines instead of holding those edges.
+- **Fix**: `sigmas: { type: "v2", value: new Vector2(sigma, filterSmoothness) }`.
+- **Confidence**: Confirmed
+
+---
+
+### GFXG-9 Uninitialised accumulator in the impostor bake supersampler
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/graphics/impostors/octahedral/shader/BakeShaderStandard.js:95`
+- **Defect**: `vec4 col;` is declared without an initialiser and then accumulated into with `col += texture(...)` four times. GLSL ES 3.00 leaves uninitialised local variables undefined; there is no guarantee of zero-fill and drivers differ (desktop NVIDIA/AMD commonly zero, several mobile/Adreno and ANGLE-on-D3D configurations do not).
+- **Failure scenario**: Run `ImpostorBaker.bake()` on a driver that does not zero-initialise locals. Every call to `texture_supersample_4` returns `garbage + Σ(4 samples) · 0.25`, so the baked atlas's colour, normal+depth and ORM channels are all offset by a per-invocation constant. The impostor comes out with a uniform colour cast, wrong depths (the `.a` channel feeds the parallax and the shadow-caster height) and a shifted normal — and the bake is cached to disk, so the corruption persists.
+- **Fix**: `vec4 col = vec4(0.0);`
+- **Confidence**: Likely (unconditionally undefined per spec; the visible symptom is driver-dependent)
+
+---
+
+## Status of the "already known" list
+
+| Item | Status |
+|---|---|
+| LPV GI vertex shader walks the tetrahedral mesh in object space (`gi/material/space_vertex/build_vertex_shader.js:18`) | Still open — `lpv_walk_to_tetrahedron(position, …)` unchanged; note GFXG-1 sits on top of it in the same block |
+| Path-tracer material conversion drops texture wrap mode | Not re-examined (excluded from write-up per brief) |
+| Path-tracer tint linearized twice | Not re-examined (excluded per brief) |
+| Path-tracer emissive colour/intensity dropped | Not re-examined (excluded per brief) |
+| `WaterShader` references r136-removed `ShaderChunk` symbols | Still open — `lights_pars` (×2, `:22`/`:78`) and `linear_to_gamma_fragment` (`:142`) resolve to `undefined` and are `join`ed into the source as the literal text `undefined`; `BRDF_Diffuse_Lambert` (`:112`, `:124`) also no longer exists |
+| Water never disposes its DataTexture/geometry/material | Not re-examined (no `water/` directory in scope; `material/WaterMaterial.js` has no dispose path) |
+| AO `ShaderMaterial` leak on shutdown | Not re-examined (lives under `render/`, out of scope) |
+| Stale `projectionMatrixInverse` after a projection modifier | Not re-examined (out of scope) |
+| `DepthLimitedBlur` dropping `format` | Not re-examined (`render/`, out of scope) |
+| `NormalFrameBuffer` shared-material wrong normals | Not re-examined (`render/`, out of scope) |
+| Lightmap T-junction shading-normal carry | Not re-examined (excluded per brief) |
+| `set_environment_texture` leaking PMREM targets | Still open — `GraphicsEngine.js:401/405/415` dispose the PMREM generator and the previous target, so the specific leak may already be addressed; not investigated further |
+
+## Notes on things deliberately NOT reported
+
+- `sh3/gi/material/MaterialTransformer.js:311` `result.clone();` discards its return value. It is a dead statement, not a behaviour change — the transformer is *supposed* to mutate the source in place (the newer `LightProbeGridMaterialTransformer.transform` does exactly that without the stray clone).
+- `VecToSphereOct` in the impostor shaders uses GLSL `sign()` (returns 0 at 0) where the CPU baker uses `sign_not_zero`. The divergence only manifests for camera directions with an exactly-zero X or Z component *and* negative Y — measure-zero and, for the hemisphere capture mode, unreachable.
+- `HemiOctahedralUvEncoder` does not override `unit_to_uv`, so the inherited `throw new Error('Not implemented')` fires. No caller reaches it and there is no scene that produces a wrong render from it.
+- Uninitialised `LayerCompositer`/`CompositLayer` material disposal and the `DataTexture` allocated in `HeightMap2AOMap` are small one-shot leaks with no visible rendering consequence.
+- `ImageFilter.processTexture` calls `renderer.setSize()` and never restores it, but its only caller drives it through `WebGLRendererPool.global`, i.e. an offscreen renderer, so the main canvas is unaffected.
+- `TubeMaterialX`'s lit branch feeds the `color/255` vertex colour to the light chain as a linear value and then runs `<encodings_fragment>`, whereas the unlit branch writes it raw. This matches three's own vertex-colour convention, so it is a convention choice rather than a defect.