@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/geom-3d.md

@@ -0,0 +1,117 @@
+# Correctness review — `core/geom/3d/`
+
+Scope: everything under `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/`.
+Excluded per brief: `core/geom/2d/`, loose files in `core/geom/`, `editor/`, `prototype*.js`,
+`*.spec.js` (evidence only), and the already-fixed/known-good items listed in the brief.
+
+## Tree survey (what was covered)
+
+~800 `.js` files. Roughly half are thin `@deprecated` re-export shims for the camelCase→snake_case
+rename; those were checked and dismissed.
+
+Directories read in depth (priority order from the brief):
+
+| area | dir | files w/o adjacent spec (sampled/read) |
+|---|---|---|
+| half-edge / topology | `topology/**` (233 files) | `bt_loop_kill`, `bt_mesh_fill_small_holes`, `bt_mesh_from_unindexed_geometry`, `edge/bt_edge_get_or_create`, `edge/bt_edge_kill`, `edge/bt_edge_swap_vertex_slots`, `edge/bt_kill_only_edge`, `face/bt_face_kill`, `face/bt_kill_only_face`, `vertex/bt_vertex_kill`, `vertex/bt_vertex_kill_only`, `query/bt_collect_boundary_segments`, `query/bt_edge_is_boundary`, `query/bt_face_get_edge_adjacent_faces`, `query/bt_face_get_shared_loop`, `query/bt_face_get_vertex_adjacent_faces`, `query/bt_mesh_count_edge_faces`, `query/bt_mesh_is_closed`, `query/bt_mesh_is_manifold`, `query/bt_mesh_build_boundary_euclidean_distance_field`, all of `topology/simplify/**` except 4, all of `topology/query/**`, `topology/three/**`, `topology/util/**` |
+| UV atlas / LSCM / packing | `atlas/**` (39 files) | `atlas_generate`, `atlas_extract_chart`, `Chart`, `atlas_write_chart_uvs`(spec'd), `data/atlas_build_edge_dihedrals`, `data/atlas_build_edge_lengths`, `data/atlas_build_face_areas`, `param/atlas_chart_param_validity`, `param/atlas_chart_parameterize_ortho`, `param/atlas_chart_stretch_metric`, `pack/ChartPlacement`, `segment/RegionGraph`, `segment/atlas_build_region_graph` |
+| triangulation | `polygon/**`, `topology/.../face/bt_face_triangulate`, `bt_mesh_triangulate` | `polygon3_compute_normal`, `bt_mesh_triangulate` |
+| convex hull | no 3D hull constructor exists in this tree — only `shape/ConvexHullShape3D` (already-fixed item) | — |
+| mesh queries / sampling | `triangle/**`, `query/bt_mesh_sample_interior_grid_points`, `shape/util/**` | `tri3_area`, `tri3_compute_normal`, `tri3_compute_plane_side`, `tri3_incenter`, `tri3_intersects_clipping_volume`, `tri3_mesh_compute_signed_volume`, `tri3_ray_intersection_barycentric_edge`, `tri3_ray_intersection_indexed`, `shape/util/shape3_voxelize_to_grid`, `shape/util/compute_signed_distance_gradient_by_sampling` |
+| simplification / welding | `topology/simplify/**`, `io/vertex/bt_merge_vertices_by_distance`, `io/edge/bt_mesh_fuse_duplicate_edges` | `compute_edge_collapse_cost`, `compute_face_normal_change_dot_product`, `build_vertex_quadrics`, `apply_border_penalty_to_vertex_quadrics`, `compute_edge_collapse_cost_quadric`, `deep_copy_vertex_quadrics`, `partial_edge_collapse`, `collapse_edge`, `edge_collapse_quadratic`, `EdgeCollapseCandidate`, `tm_edge_collapse_is_degenerate_flip`, `simplifyTopoMesh`, `simplifyTopoMesh2` |
+| GJK / MPR | `gjk/**` | `minkowski_support` (mpr, gjk, gjk_epa_penetration have specs) |
+| encodings / misc | `normal/**`, `morton/**`, `equirectangular/**`, `SurfacePoint3`, `tetrahedra/delaunay/**` | spot-checked |
+
+Checked and found clean (no finding): `bt_edge_split` (radial + disk rewiring verified end-to-end,
+both halves get one loop per original face), `bt_edge_create`/`bt_disk_edge_add`/`bt_disk_edge_remove`
+self-loop convention, `bt_mesh_compact` (remap/patch/compact/truncate ordering), `bt_face_poke`
+fan wiring, `bt_face_triangulate` ear replay (`_ring_prev` ↔ `loop_read_prev` correspondence holds
+for both the forward and backward ear orderings, and the emitted mesh winding matches the source
+face), `bt_mesh_walk_boundary_loops` + `order_cycle_from` direction seeding (the `edges_at_v[0]`
+tiebreak provably resolves to `cycle[0]`, so the new hole face winds opposite the existing loop),
+`polygon3_triangulate` axis-drop table (all six ±x/±y/±z cases preserve CCW-from-+normal),
+`polygon3_compute_normal`, `tri3_closest_point_barycentric` (all seven Voronoi regions and the
+collinear-degenerate paths traced numerically), `mpr.js` portal discovery (both plane tests
+algebraically identical to libccd's `det[v0,v1,v3] < 0` / `det[v0,v2,v3] > 0` after expanding the
+relative-to-V0 form) and `expandPortal` branch table, `matrix_symmetric_3x3_eigen` column/ascending
+convention used by `fit_plane_basis`, `min_area_rect_2d` angle convention vs
+`rotate_uv_to_min_area_box`, `atlas_pack_charts` rot-1 UV remap (transpose ↔ `(x+tv, y+tu)`
+verified), the skyline/bitmap growth loops, `atlas_segment_charts` vs `atlas_segment_charts_atomic`
+boundary/seam arithmetic (both reduce to `chart_boundary + perimeter − 2·shared`),
+`encode_unit_to_octahedron`/`decode_octahedron_to_unit` fold (pre-fold abs values used on both
+sides), `topo_mesh_to_three_buffer_geometry` index-width thresholds (no Uint16 overflow),
+`Quadric3.optimize` aliasing and symmetric-inverse index layout, `v3_normalize_array` zero guard.
+
+---
+
+## Findings
+
+### GEOM3-1 Edge-collapse flip rejection degenerates into "is the face normal pointing down?"
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/compute_edge_collapse_cost.js:43-54` (with `compute_face_normal_change_dot_product.js:29-47` and `tri3_compute_normal.js:40-46`)
+- **Defect**: The flip test loops over **every** face of the victim, including the 1–2 faces that contain *both* endpoints of the collapsing edge — the faces the collapse deletes. Substituting `victim → target` in those faces produces a triangle with two identical vertices, so `tri3_compute_normal` takes its zero-area branch and writes the documented "arbitrary invalid result" `(0, 1, 0)`. The dot product against the real face normal is therefore just `original_normal.y`, and the whole test collapses to `original_normal.y >= 0`. The sibling helper `tm_edge_collapse_is_degenerate_flip.js:26-29` skips exactly these faces, confirming the intent.
+- **Failure scenario**: A `TopoMesh` quad in the XZ plane facing **down** — A(0,0,0), B(1,0,0), C(1,0,1), D(0,0,1), triangles (A,B,C) and (A,C,D) wound so both normals are `(0,-1,0)`. Call `compute_edge_collapse_cost(A, C, edge_AC, quadrics)`. Face ABC contains both A and C, so substitution gives (C,B,C): `vCB = C−B`, `vAB = C−B`, cross `= 0`, `l_sqr === 0` → normal `(0,1,0)`. `dot((0,1,0), (0,-1,0)) = -1 < 0` → **produced `Number.MAX_VALUE`**; expected the ordinary quadric cost (0 here, plus the border constants). The reverse direction `compute_edge_collapse_cost(C, A, …)` hits the same faces and also returns `MAX_VALUE`, so `EdgeCollapseCandidate.update` (EdgeCollapseCandidate.js:117-140) records `MAX_VALUE` for the edge in both orientations. Flip the same quad to face up (normals `(0,1,0)`) and the dot becomes `+1` and the edge is accepted. Net effect on a real model: `simplifyTopoMesh` refuses to collapse any edge whose adjacent face normal has a negative Y component — on a closed mesh (cube, sphere, rock) that is the entire downward-facing half, which is simply never decimated while the upward-facing half is.
+- **Fix**: In the loop at `compute_edge_collapse_cost.js:43`, skip faces that contain `target` as well as `victim` (they are deleted by the collapse), mirroring `tm_edge_collapse_is_degenerate_flip.js:26-29`:
+  ```js
+  if (face.containsVertex(target)) { continue; }
+  ```
+- **Confidence**: Confirmed
+
+### GEOM3-2 Zero-area faces inject a fabricated `(0,1,0)` plane into vertex quadrics
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js:70-91`; same defect in `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/simplify/quadratic/build_vertex_quadrics.js:12-30`
+- **Defect**: Both quadric builders derive the supporting plane from `tri3_compute_normal`, which for a zero-area triangle writes the sentinel `(0, 1, 0)` (`tri3_compute_normal.js:40-46`, "degenerate triangle, provide arbitrary invalid result"). Neither builder tests for that case, so the sentinel is treated as a genuine plane and accumulated onto all three vertices at full weight. A degenerate face carries no geometric constraint and must contribute a zero quadric. (`build_vertex_quadrics` would be saved by area weighting, but `use_triangle_area` defaults to `false`; `bt_mesh_compute_vertex_quadrics` has no area weighting at all.)
+- **Failure scenario**: A sheet lying in the plane `z = 0` that also contains one collinear triangle `T = (0,0,0), (1,0,0), (2,0,0)` — a routine artifact after `bt_merge_vertices_by_distance` welds colocal points, or from an imported model. For `T`: `vCB = (1,0,0)`, `vAB = (-1,0,0)`, cross `= 0` → normal `(0,1,0)`, `d = -dot((0,1,0),(0,0,0)) = 0`, i.e. the plane `y = 0`, added to the quadrics of `(0,0,0)`, `(1,0,0)`, `(2,0,0)`. Now score the collapse of edge `B=(1,0,0) — E=(1,1,0)` at target `(1, 0.5, 0)` (`evaluate_edge_collapse`, `bt_mesh_simplify.js:110-115`): every real supporting plane is `z = 0` and the target lies in it, so the true cost is **0**; the fabricated plane contributes `0.5² = 0.25`, so the **produced cost is 0.25**. The bogus plane also raises the rank of the combined tensor, so `Quadric3.optimize` succeeds where it should have reported singular and pulls the survivor off the sheet toward `y = 0`.
+- **Fix**: Detect the degeneracy where the plane is built rather than relying on `tri3_compute_normal`'s sentinel — compute the raw cross product and `continue` when its squared length is 0 (`bt_mesh_compute_vertex_quadrics.js` before line 87; `quadric_set_from_face` in `build_vertex_quadrics.js` before line 29).
+- **Confidence**: Confirmed
+
+### GEOM3-3 `bt_vertex_replace` silently rewrites edge 0 when a vertex has more than 1024 incident edges
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/vertex/bt_vertex_replace.js:6,40-42,57-58`
+- **Defect**: The victim's disk cycle is snapshotted into the module-static `const scratch_edges = new Uint32Array(1024)`. The bound is only checked by an `assert` (compiled out in production). Past 1024, `scratch_edges[edges_to_move_count++] = curr_e` is a silently-dropped out-of-range typed-array store while the counter keeps incrementing, so stage 3 reads `scratch_edges[i] === undefined` for `i >= 1024`. That `undefined` then flows into `mesh.edge_read_loop(undefined)` → `element_address(undefined)` = `28 * undefined` = `NaN` → `data_view.getUint32(NaN)`, and `DataView` coerces the index with `ToIndex`, which maps `NaN` to **0**. So every over-budget iteration reads *and rewrites* **edge 0**.
+- **Failure scenario**: Take a vertex `v` with 1200 incident edges and call `bt_vertex_replace(mesh, v, r)` (directly, or via `bt_edge_collapse` → `bt_mesh_simplify`; survivor valence grows monotonically with each collapse, so decimating a ≥200k-triangle mesh down to a few hundred faces reaches this routinely). Produced: edges 0..1023 are correctly re-pointed; for the remaining 176 iterations the code instead sets `edge 0`'s `vertex1`/`vertex2` to `r` and splices edge 0 into `r`'s disk cycle repeatedly, while edges 1024..1199 keep pointing at `v` — which `bt_edge_collapse` then releases via `bt_vertex_kill`, leaving 176 edges referencing a freed vertex. Expected: all 1200 edges re-pointed and edge 0 untouched.
+- **Fix**: Grow `scratch_edges` on demand before the write (`if (edges_to_move_count >= scratch_edges.length) { scratch_edges = grow(...) }` with `let` instead of `const`), or count the disk cycle first and size the buffer to the valence.
+- **Confidence**: Likely (the `NaN → index 0` mechanism is Confirmed; reaching valence > 1024 depends on the input mesh / decimation ratio)
+
+### GEOM3-4 `atlas_extract_chart` marks chart-interior edges as boundary on non-manifold edges
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_extract_chart.js:84-91`
+- **Defect**: The boundary test consults only the single `loop_read_radial_next` neighbour: `is_boundary = opp === li || face_chart[loop_read_face(opp)] !== chart_id`. On an edge with three or more faces the answer depends on where the loop sits in the radial cycle, so an edge that is interior to the chart can be recorded as a chart boundary. The correct predicate is "no *other* loop on the radial cycle belongs to this chart".
+- **Failure scenario**: Edge `e` shared by faces A, B (both in chart 0) and C (chart 1), radial cycle A→B→C→A. For A's loop, `radial_next` is B (chart 0) → not boundary. For B's loop, `radial_next` is C (chart 1) → **boundary**, so `chart.boundary_edges` gains the pair `(vB0, vB1)` for an edge that is interior to chart 0. Downstream: the extra edge gives one of its endpoints two outgoing boundary edges, so `atlas_chart_parameterize_bff` hits `if (succ[a] !== -1) return false` (`atlas_chart_parameterize_bff.js:102`) and rejects a chart that really is a disk; and `atlas_chart_param_validity` tests that interior segment for crossings against the true outline, so a bijective LSCM layout can be reported `self_intersects: true` and be needlessly exploded by `atlas_piecewise_resegment`. Expected: `boundary_edges` contains only edges with no in-chart face across them.
+- **Fix**: Walk the full radial cycle from `li` and treat the edge as boundary only if no other loop's face has `face_chart === chart_id`.
+- **Confidence**: Confirmed (for non-manifold input)
+
+### GEOM3-5 `build_triangle_adjacency` keeps the *last* pairing, not the first, on a non-manifold edge
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/param/atlas_piecewise_resegment.js:26-33`
+- **Defect**: `edge_map` retains the first slot forever, so the third and later triangles on an edge each overwrite `tri_neighbor[first_slot]`. The result is an asymmetric adjacency graph, contradicting the function's own doc ("a non-manifold edge keeps the first pairing").
+- **Failure scenario**: Triangles `t1, t2, t3` share an edge, visited in that order. After `t2`: `tri_neighbor[slot1] = t2`, `tri_neighbor[slot2] = t1`. After `t3`: `tri_neighbor[slot3] = t1` and `tri_neighbor[slot1] = t3` — overwriting `t2`. Now grow a sub-chart containing `{t1, t2}`: `build_subchart` reads `tri_neighbor[slot1] = t3`, which is not in `member`, so it pushes that edge into `sub.boundary_edges` even though `t2` sits across it. Produced: `is_ortho_valid` runs the O(b²) crossing test on an interior edge and can reject a legitimate growth step, splitting the chart into more pieces than necessary; and `t2 → t1` while `t1 → t3` makes the traversal non-symmetric. Expected: `tri_neighbor[slot1] === t2` and `tri_neighbor[slot2] === t1`, with `t3`'s slot left at `-1`.
+- **Fix**: `edge_map.delete(key)` after the first pairing is consumed, so a third triangle on the same edge starts a fresh (or no) pairing instead of clobbering `slot1`.
+- **Confidence**: Confirmed (for non-manifold input)
+
+### GEOM3-6 Mesh edits allocate through the raw pools, bypassing the data-pool capacity sync
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js:53,83`; also `edge/bt_edge_split.js:73,146`, `face/bt_face_triangulate.js:61`, `bt_mesh_close_boundary_holes.js:112`, `bt_mesh_fill_small_holes.js:80`, `bt_mesh_face_decouple.js:85`, `edge/bt_edge_create.js:71`
+- **Defect**: These call `mesh.vertices.allocate()` / `mesh.faces.allocate()` / `mesh.edges.allocate()` directly instead of `mesh.vertex_create()` / `face_create()` / `edge_create()`. The `*_create()` wrappers exist precisely to run `__*_data_pool?.ensure_capacity(id + 1)` (`BinaryTopology.js:635-680`). The same functions *do* use `mesh.loop_create()` for their loops, so the omission is inconsistent within a single function body — this is not the documented "caller keeps `__size` in sync" contract, it is a missing capacity grow that leaves the data buffer physically too short.
+- **Failure scenario**: `topo.create_face_data(4)` on a 100-face mesh → the data pool is sized by `allocate_continuous(100)`, giving `capacity = 128` and a 512-byte buffer (128 words). Call `bt_face_poke` on a 40-gon: it allocates 39 new faces, ids 100…138. `face_data.element_word(138)` is 138, but `face_data.data_uint32.length` is 128. Produced: writes at index 138 are silently discarded and reads return `undefined` (and `NaN` once arithmetic touches them). Expected: the data pool grows so face 138 is addressable, exactly as `mesh.loop_create()` already guarantees for the loops created in the same call.
+- **Fix**: Use `mesh.vertex_create()` / `mesh.face_create()` / `mesh.edge_create()` in these seven sites.
+- **Confidence**: Confirmed
+
+### GEOM3-7 `atlas_generate` reports a `chart_count` that undercounts the charts it returns
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/3d/atlas/atlas_generate.js:36-38` (value originates at `atlas_compute_charts.js:187`)
+- **Defect**: `atlas_compute_charts` returns the *segmentation* chart count alongside `face_chart` — self-consistent there, since `face_chart` holds segmentation ids. `atlas_generate` forwards that number as `chart_count` but does **not** return `face_chart`, so the only array the caller has is `charts`, whose length differs whenever `atlas_piecewise_resegment` fires (each failed chart becomes N sub-charts, all appended).
+- **Failure scenario**: A mesh whose segmentation produces 4 charts, one of which fails ortho, LSCM and BFF and is re-segmented into 7 pieces. `atlas_generate` returns `charts.length === 10` but `chart_count === 4`. A caller sizing a per-chart array from `chart_count` (the obvious reading of the field) under-allocates by 6 and drops six charts' metadata. Expected: `chart_count === charts.length` for the value returned next to `charts`.
+- **Fix**: In `atlas_generate`, return `chart_count: computed.charts.length` (or return `face_chart` too and document the field as the segmentation count).
+- **Confidence**: Confirmed
+
+---
+
+## Notable non-findings (checked, deliberately not reported)
+
+- `tri3_ray_intersection_barycentric_edge` returns `true` for negative `t` (hit behind the origin). Both in-tree BVH callers (`ebvh_geometry_query_nearest_triangle_ray.js:127`, `ebvh_geometry_query_any_triangle_ray.js:129`) and `BufferedGeometryBVH` gate on `t > min_distance`, and the function's contract is "returns the barycentric solution", so this is by design, not a defect.
+- `tri3_ray_intersection` writes an **un-normalised** normal into `result.normal`. Its only in-tree consumer (`bt_mesh_sample_interior_grid_points`) uses the boolean only. Contract ambiguity, no wrong value.
+- `bt_face_is_degenerate` uses an absolute `area² <= 1e-17` threshold, so a valid triangle with ~3e-5 edges is called degenerate. Scale-dependent tolerance rather than a logic error.
+- `compute_edge_collapse_cost.js:29` declares `normal_cost` and never assigns it, so the curvature term of the Melax cost is dead. Incomplete, but it produces no wrong value on its own (the quadric term carries the geometric error) — GEOM3-1 is the actual defect in that file.
+- `BinaryElementPool.copy` leaves `__capacity` stale when `item_size` shrinks and the existing buffer is reused (`BinaryElementPool.js:471-489`). Self-heals on the next `allocate()`; no reachable wrong value found.
+- `tetrahedral_mesh_compute_cavity`'s facet-vertex table (`k0/k1/k2`) yields the correct vertex *sets* for all four facets but the opposite *orientation* to the table in `tetrahedral_mesh_walk_towards_containing_tetrahedron`. The flip is uniform across all four facets, so it is self-consistent; without running `compute_delaunay_tetrahedral_mesh.spec.js` against the mesh's sign convention I could not construct a produced-vs-expected, so it is not reported — but it is the one place in this tree I would re-check first.

package/src/REVIEW_2026_08_06/gfx-gi.md

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