@woosh/meep-engine 2.163.11 → 2.165.0

package/src/engine/graphics/render/forward_plus/query/point_light_inside_volume.js

@@ -1,28 +1,28 @@
-import { detailed_sphere_frustum_intersection_test } from "./detailed_sphere_frustum_intersection_test.js";
-
 /**
+ * Conservative sphere-vs-convex-cell test: the sphere is considered to intersect the cell
+ * unless it lies entirely beyond one of the six bounding planes.
+ *
+ * NOTE: a previous version refined the "near a corner/edge" cases by measuring the distance
+ * to the cell's nearest corner/edge (an Arvo-style nearest-feature test). That refinement is
+ * only correct for AXIS-ALIGNED boxes. Froxels are oblique hexahedra, and there the assumed
+ * nearest feature can be farther than the cell's true nearest point, so the test rejected
+ * spheres that actually reach into the cell. Those false rejections culled real lights from
+ * peripheral / far froxels and showed up as hard-edged "blocky" lighting. The plane-only test
+ * never under-includes; the only cost is mild over-inclusion near corners, which is harmless
+ * because out-of-range lights attenuate to zero in the shader.
  *
  * @param {number} light_x
  * @param {number} light_y
  * @param {number} light_z
  * @param {number} radius
- * @param {number[]|Float32Array} points
  * @param {number[]|Float32Array|Float64Array} planes
  * @returns {boolean}
  */
 export function point_light_inside_volume(
     light_x, light_y, light_z, radius,
-    points, planes
+    planes
 ) {
-    let j = 0;
-    let outside_plane_count = 0;
-    let outside_plane_bitfield = 0;
-
-    // validate if the sphere intersects the plane-bound space
-
-    // query_bvh_frustum_from_objects.checks_sphere++;
-
-    for (; j < 6; j++) {
+    for (let j = 0; j < 6; j++) {
 
         const plane_address = j * 4;
 
@@ -31,44 +31,14 @@ export function point_light_inside_volume(
         const plane_normal_z = planes[plane_address + 2];
         const plane_constant = planes[plane_address + 3];
 
-        /*
-         compute distance from the center of the sphere to the plane
-         NOTE: inlined computation of distance from point to plane
-         */
+        // signed distance from the sphere centre to the plane (inlined point-to-plane)
         const distance = (plane_normal_x * light_x + plane_normal_y * light_y + plane_normal_z * light_z) + plane_constant;
 
-        // query_bvh_frustum_from_objects.checks_sphere_plane++;
-
-        if (distance < 0) {
-            // center of the sphere is below the plane
-
-            if (distance >= -radius) {
-
-                // sphere intersects the plane
-
-                outside_plane_count++;
-
-                const plane_bit_mask = 1 << j;
-
-                outside_plane_bitfield |= plane_bit_mask;
-            } else {
-                // sphere is entirely below the plane
-
-                // query_bvh_frustum_from_objects.rejection_sphere_count++;
-
-                return false;
-            }
+        if (distance < -radius) {
+            // sphere is entirely beyond this plane -> cannot intersect the cell
+            return false;
         }
-
     }
 
-    if (outside_plane_count < 2) {
-        return true;
-    } else {
-        return detailed_sphere_frustum_intersection_test(
-            radius, light_x, light_y, light_z,
-            outside_plane_count, outside_plane_bitfield,
-            points
-        );
-    }
+    return true;
 }

package/src/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.d.ts

@@ -5,8 +5,7 @@
  * @param {BinaryUint32BVH} bvh
  * @param {number[]|Uint8ClampedArray} source_data
  * @param {number[]|Float32Array|Float64Array} planes
- * @param {number[]|Float32Array|Float64Array} points
  * @returns {number} number of items added to the destination, non-negative integer
  */
-export function query_bvh_frustum_from_texture(destination: number[], destination_offset: number, bvh: BinaryUint32BVH, source_data: number[] | Uint8ClampedArray, planes: number[] | Float32Array | Float64Array, points: number[] | Float32Array | Float64Array): number;
+export function query_bvh_frustum_from_texture(destination: number[], destination_offset: number, bvh: BinaryUint32BVH, source_data: number[] | Uint8ClampedArray, planes: number[] | Float32Array | Float64Array): number;
 //# sourceMappingURL=query_bvh_frustum_from_texture.d.ts.map

package/src/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query_bvh_frustum_from_texture.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.js"],"names":[],"mappings":"AAoDA;;;;;;;;;GASG;AACH,4DARW,MAAM,EAAE,sBACR,MAAM,qCAEN,MAAM,EAAE,GAAC,iBAAiB,UAC1B,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UAClC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CA6GlB"}
+{"version":3,"file":"query_bvh_frustum_from_texture.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.js"],"names":[],"mappings":"AAoDA;;;;;;;;GAQG;AACH,4DAPW,MAAM,EAAE,sBACR,MAAM,qCAEN,MAAM,EAAE,GAAC,iBAAiB,UAC1B,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CA6GlB"}

package/src/engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.js

@@ -57,7 +57,6 @@ function frustum_check(data, address, planes) {
  * @param {BinaryUint32BVH} bvh
  * @param {number[]|Uint8ClampedArray} source_data
  * @param {number[]|Float32Array|Float64Array} planes
- * @param {number[]|Float32Array|Float64Array} points
  * @returns {number} number of items added to the destination, non-negative integer
  */
 export function query_bvh_frustum_from_texture(
@@ -65,7 +64,7 @@ export function query_bvh_frustum_from_texture(
     destination_offset,
     bvh,
     source_data,
-    planes, points
+    planes
 ) {
     let result = 0;
 
@@ -142,7 +141,7 @@ export function query_bvh_frustum_from_texture(
 
                 const radius = source_data[light_address + 3];
 
-                if (!point_light_inside_volume(light_x, light_y, light_z, radius, points, planes)) {
+                if (!point_light_inside_volume(light_x, light_y, light_z, radius, planes)) {
                     // cull
                     continue;
                 }

package/src/engine/graphics/render/forward_plus/query/spot_light_inside_volume.js

@@ -1,4 +1,4 @@
-import { computeConePlaneSide } from "../../../../../core/geom/3d/cone/computeConePlaneSide.js";
+import { cone_compute_plane_side } from "../../../../../core/geom/3d/cone/cone_compute_plane_side.js";
 
 /**
  *
@@ -17,7 +17,7 @@ export function spot_light_inside_volume(light, points, planes) {
         const plane_normal_z = planes[plane_address + 2];
         const plane_constant = planes[plane_address + 3];
 
-        const side = computeConePlaneSide(
+        const side = cone_compute_plane_side(
             plane_normal_x, plane_normal_y, plane_normal_z, plane_constant,
             light.position.x, light.position.y, light.position.z,
             light.direction.x, light.direction.y, light.direction.z,

package/src/engine/graphics/render/forward_plus/testClusterEquality.js

@@ -11,7 +11,7 @@ export function testClusterEquality(light_data, count, light_lookup_texture_data
 
         const existing_light_address = light_lookup_texture_data[address + i];
 
-        const datum = light_data[i] * 2;
+        const datum = light_data[i];
 
         if (datum !== existing_light_address) {
             return false;

package/src/engine/graphics/render/gizmo/GizmoShapeRenderingInterface.js

@@ -3,7 +3,7 @@ import { makeHelperBoxGeometry } from "../../../../../editor/process/symbolic/ma
 import { makeHelperSphereGeometry } from "../../../../../editor/process/symbolic/makeHelperSphereGeometry.js";
 import { assert } from "../../../../core/assert.js";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
-import { compose_matrix4_array } from "../../../../core/geom/3d/mat4/compose_matrix4_array.js";
+import { m4_compose } from "../../../../core/geom/3d/mat4/m4_compose.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { DrawMode } from "../../ecs/mesh-v2/DrawMode.js";
@@ -130,7 +130,7 @@ export class GizmoShapeRenderingInterface {
      * @param {number[]} size
      */
     draw_solid_cube(center, size) {
-        compose_matrix4_array(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromArray(size));
+        m4_compose(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromArray(size));
         add_instance(this.__boxes_solid, scratch_m4, this.__color);
     }
 
@@ -140,7 +140,7 @@ export class GizmoShapeRenderingInterface {
      * @param {number[]} size
      */
     draw_wire_cube(center, size) {
-        compose_matrix4_array(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromArray(size));
+        m4_compose(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromArray(size));
         add_instance(this.__boxes_wire, scratch_m4, this.__color);
     }
 
@@ -160,7 +160,7 @@ export class GizmoShapeRenderingInterface {
      * @param {number} radius
      */
     draw_solid_sphere(center, radius) {
-        compose_matrix4_array(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromScalar(radius));
+        m4_compose(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromScalar(radius));
         add_instance(this.__sphere_solid, scratch_m4, this.__color);
     }
 
@@ -170,7 +170,7 @@ export class GizmoShapeRenderingInterface {
      * @param {number} radius
      */
     draw_wire_sphere(center, radius) {
-        compose_matrix4_array(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromScalar(radius));
+        m4_compose(scratch_m4, Vector3.fromArray(center), Quaternion.identity, Vector3.fromScalar(radius));
         add_instance(this.__sphere_wire, scratch_m4, this.__color);
     }
 }

package/src/engine/graphics/render/layers/RenderLayerUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderLayerUtils.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/layers/RenderLayerUtils.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,6HAHW,MAAM,YAgGhB"}
+{"version":3,"file":"RenderLayerUtils.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/layers/RenderLayerUtils.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,6HAHW,MAAM,YAgGhB"}

package/src/engine/graphics/render/layers/RenderLayerUtils.js

@@ -1,7 +1,5 @@
 import { v3_distance_above_plane } from "../../../../core/geom/vec3/v3_distance_above_plane.js";
-import {
-    plane3_three_compute_convex_3_plane_intersection
-} from "../../../../core/geom/3d/plane/plane3_three_compute_convex_3_plane_intersection.js";
+import { plane3_compute_3_plane_intersection_from_three } from "../../../../core/geom/3d/plane/plane3_compute_3_plane_intersection_from_three.js";
 
 /**
  *
@@ -43,7 +41,7 @@ export function buildPlanarRenderLayerClipPlaneComputationMethod(traversePlanes,
             const p0 = pair[0];
             const p1 = pair[1];
 
-            const planeIntersection = plane3_three_compute_convex_3_plane_intersection(p, 0, p0, p1, objectPlane);
+            const planeIntersection = plane3_compute_3_plane_intersection_from_three(p, 0, p0, p1, objectPlane);
 
             if (!planeIntersection) {
                 //no intersection

package/src/engine/graphics/render/make_bvh_visibility_builder.js

@@ -1,7 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import {
-    bvh_query_user_data_overlaps_frustum
-} from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_frustum.js";
+    bvh_query_user_data_intersects_frustum
+} from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_frustum.js";
 
 /**
  * Assumes that BVH stored entity IDs
@@ -37,7 +37,7 @@ export function make_bvh_visibility_builder(em, bvh, extract, extract_context) {
             return 0;
         }
 
-        const matches = bvh_query_user_data_overlaps_frustum(
+        const matches = bvh_query_user_data_intersects_frustum(
             scratch_array, 0,
             bvh, view.frustum
         );

package/src/engine/graphics/render/view/CameraView.js

@@ -3,7 +3,7 @@ import { array_copy } from "../../../../core/collection/array/array_copy.js";
 import { array_remove_first } from "../../../../core/collection/array/array_remove_first.js";
 import Signal from "../../../../core/events/signal/Signal.js";
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
-import { read_three_planes_to_array } from "../../../../core/geom/3d/frustum/read_three_planes_to_array.js";
+import { frustum3_planes_to_flat_from_three } from "../../../../core/geom/3d/frustum/frustum3_planes_to_flat_from_three.js";
 import { frustum_from_camera } from "../../ecs/camera/frustum_from_camera.js";
 import { compare_three_objects } from "../../three/compare_three_objects.js";
 import { IncrementalDeltaSet } from "../visibility/IncrementalDeltaSet.js";
@@ -97,7 +97,7 @@ export class CameraView {
         frustum_from_camera(camera, scratch_frustum, false);
 
         // update view definition
-        read_three_planes_to_array(scratch_frustum.planes, this.frustum);
+        frustum3_planes_to_flat_from_three(scratch_frustum.planes, this.frustum);
 
         // read projection matrix
         // TODO

package/src/engine/graphics/render/visibility/hiz/prototypeHiZ.js

@@ -1,4 +1,6 @@
-import { mat4 } from "gl-matrix";
+import { m4_allocate } from "../../../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_multiply } from "../../../../../core/geom/3d/mat4/m4_multiply.js";
+import { array_copy } from "../../../../../core/collection/array/array_copy.js";
 import FacingDirectionSystem from "../../../../../../../model/game/ecs/system/FacingDirectionSystem.js";
 import { initializeEditor } from "../../../../../../../model/game/initializeEditor.js";
 import { makeEngineOptionsModel } from "../../../../../../../model/game/options/makeEngineOptionsModel.js";
@@ -208,12 +210,12 @@ function prepare_query_test(hiz, graphics, ecd) {
 
         const camera = graphics.camera;
 
-        const projection = mat4.create();
+        const projection = m4_allocate();
         const world_inverse = camera.matrixWorldInverse.elements;
         const camera_projection = camera.projectionMatrix.elements;
 
-        mat4.copy(projection, world_inverse);
-        mat4.multiply(projection, camera_projection, projection);
+        array_copy(world_inverse, 0, projection, 0, 16);
+        m4_multiply(projection, camera_projection, projection);
         const aabb = new AABB3();
 
         const query_size = query.getSize();

package/src/engine/graphics/sh3/fromCubeRenderTarget.js

@@ -1,7 +1,7 @@
 import { sh3_basis_at } from "../../../core/geom/3d/sphere/harmonics/sh3_basis_at.js";
 import { sh3_dering_optimize_positive } from "../../../core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js";
 import { sh3_vector_accumulate } from "../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
-import { vector_scale_array } from "../../../core/geom/vec/vector_scale_array.js";
+import { vector_scale_offset } from "../../../core/geom/vec/vector_scale_offset.js";
 import { v3_length_sqr } from "../../../core/geom/vec3/v3_length_sqr.js";
 
 const scratch_color = new Float32Array(3);
@@ -133,7 +133,7 @@ export function fromCubeRenderTarget(
     // normalize
     const norm = (4 * Math.PI) / total_weight;
 
-    vector_scale_array(coefficients, 0, coefficients, 0, 27, norm);
+    vector_scale_offset(coefficients, 0, coefficients, 0, 27, norm);
 
     sh3_dering_optimize_positive(coefficients, 0, coefficients, 0, 3);
 

package/src/engine/graphics/sh3/gi/prototypeSHGI.js

@@ -1,4 +1,4 @@
-import { make_justified_point_grid } from "../../../../core/geom/3d/util/make_justified_point_grid.js";
+import { aabb3_emit_point_grid } from "../../../../core/geom/3d/util/aabb3_emit_point_grid.js";
 import Vector2 from "../../../../core/geom/Vector2.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { GameAssetType } from "../../../asset/GameAssetType.js";
@@ -23,7 +23,7 @@ import { ShadedGeometrySystem } from "../../ecs/mesh-v2/ShadedGeometrySystem.js"
 function buildProbeGrid(bounds, spacing = 1) {
     const positions = [];
 
-    make_justified_point_grid(bounds, spacing, (x, y, z) => {
+    aabb3_emit_point_grid(bounds, spacing, (x, y, z) => {
         positions.push(x, y, z);
     })
 

package/src/engine/graphics/sh3/lightmap/ARTIFACTS_PLAN.md

@@ -0,0 +1,146 @@
+# Plan: fixing seams & contact leaks
+
+Driven by two observed artifacts plus the Bakery author's article
+"Baking artifact-free lightmaps" (https://ndotl.wordpress.com/2018/08/29/baking-artifact-free-lightmaps/).
+
+## Status (2026-06): implemented
+
+- **P0 carry original normals** — `lightmap_build_geometry.js` now accumulates the SOURCE
+  mesh's per-corner normals via `tri_face` (continuous across seams, hard edges preserved),
+  falling back to the geometric recompute. Fixes sphere faceting. ✅
+- **P0 sample-position push** — `lightmap_push_sample.js`; the bake relocates contact/buried
+  samples (tangential backface probe → push out) instead of discarding. Fixes the contact
+  black line. ✅
+- **P1 supersampling** — `lightmap_gather.js` jitters each ray ORIGIN within the texel
+  footprint (`supersample` option), antialiasing contacts/silhouettes; directions stay
+  independent per texel. ✅
+- **P1 graded adaptive sampling** — smooth interior texels take a reduced *real* sample count
+  (`min_sample_fraction`, default 0.25) instead of a pure lerp (which is now opt-in via
+  `min_sample_fraction = 0`). Edges still full-sampled. ✅
+- **P1 UV seam stitching** — `lightmap_seam_fix.js` pairs chart boundary edges by source vertex
+  and blends both atlas sides; runs after dilation (`seam_fix_iterations`). ✅
+- Post order now: bake (push + supersample) → variance denoise → dilate → seam-fix.
+- Specs: +`lightmap_push_sample.spec.js`, +`lightmap_seam_fix.spec.js`, +carry-normals case;
+  24 tests across 8 suites green; webpack build clean.
+
+### P2 bicubic — SKIPPED for now (user decision)
+The lightmap is sampled inside three's unexpanded `#include <lights_fragment_maps>`, so a clean
+4-tap bicubic needs either a global `THREE.ShaderChunk.lights_fragment_maps` override (affects
+every lit material) or hard-coding three's chunk text in a per-material `onBeforeCompile`
+(brittle across three versions), and it must compose with the FP+ fragment rebuild. It's
+cosmetic polish (masks low resolution) on top of fixes that already address the root artifacts,
+so it was deliberately skipped. Revisit only if the lightmap still reads low-res after the P0/P1
+fixes; the two viable approaches are recorded above.
+
+---
+
+## Original analysis
+
+## The two artifacts, diagnosed against our code
+
+### A. Seams on the smooth sphere
+Two independent causes stack here:
+
+1. **Shading faceting (the dominant one).** `lightmap_build_geometry.js` *recomputes* normals
+   per concatenated chart (`geometry_compute_vertex_normals_indexed`). A seam vertex is
+   duplicated per chart and not shared, so each side averages only its own chart's triangles →
+   the shading normal is **discontinuous at every chart boundary** → hard facets on a surface
+   that should be smooth. This is a regression we flagged ("normals recomputed, not original").
+
+2. **Lighting value step across the UV seam.** The two sides of a seam are the same 3D edge but
+   live in different atlas locations, sampled independently → slightly different indirect values →
+   a faint step. Denoise/dilate never bridge it (the two sides are far apart in the atlas).
+
+### B. Black line where the box meets the floor (contact leak)
+The contact texels — floor texels whose footprint straddles the box base, and the box's
+bottom-edge texels — are getting near-zero indirect. Likely contributors:
+- Our **confidence mask discards** over-occluded contact texels (`coverage = 0`) and lets
+  dilation fill them — but dilation pulls from the *adjacent dark contact texels*, so the line
+  stays dark instead of getting a proper value.
+- **No spatial anti-aliasing**: every sample for a texel originates from the *same* texel-center
+  point, so a texel half in shadow / half lit resolves to one hard value → a one-texel hard line
+  rather than a soft gradient.
+- Bilinear reaching toward the chart silhouette / gutter at the contact.
+
+## Bakery techniques and how they map to us
+
+| Bakery technique | Our adaptation |
+|---|---|
+| **Shadow-leak prevention**: trace 4+ **tangential** rays of length `0.5 × worldTexelSize`; if one hits a **backface**, *push* the sample out (`pos += rayDir·hitDist + faceNormal·bias`) | Replace our *discard-on-low-confidence* with **relocate**: keep the texel, move its sample to a valid spot. Directly targets artifact B. |
+| **Supersampling**: 25 sub-texel UV taps | **Jitter the ray ORIGIN within the texel footprint** (surface tangent plane), not just the direction. Antialiases the contact line and silhouettes (artifact B). |
+| **Seam fixing**: detect seam edge pairs (same pos+normal, different UV), draw lines blending both sides until they match (iterative, ping-pong) | CPU equivalent: pair `chart.boundary_edges` across charts by original vertex id, walk both sides in atlas space, average a few iterations. Targets artifact A.2. |
+| **Dilation** (8-neighbour fill) | We have `lightmap_dilate`. Keep; fix ordering. |
+| **Bicubic read-time filtering** ("0 reasons not to") | Optional three.js lightmap shader patch — hides low-res, softens lines. Bigger lift (custom material). |
+| **Phong-tessellated smooth sample position** (shadow terminator on low-poly) | Defer — our content is either smooth-normalled (sphere) or genuinely flat (boxes). |
+| Post order: bake-push → dilate → denoise → seam-fix | Adopt: currently denoise → dilate, no seam-fix. |
+
+Note: the Bakery seam detection uses pos<ε, normal<ε, **uv>ε** — exactly the seam definition we
+can derive from `vertex_of_local` + `chart.uv`.
+
+## Prioritized next steps
+
+### P0 — Carry original smooth normals (fixes sphere faceting, A.1)
+- `lightmap_build_geometry.js`: take the source geometry's `normal` attribute; set each
+  chart-local vertex normal to `original_normal[chart.vertex_of_local[lv]]` instead of
+  recomputing. For a smooth mesh welding is a no-op, so this reproduces the original normals
+  exactly; for welded hard edges it's the representative's normal (fine — those are hard anyway).
+  Fall back to the current recompute when `vertex_of_local[lv] >= original_vertex_count`
+  (T-junction-added vertices) or the geometry has no normals.
+- `bake_lightmap_for_scene.js`: pass `geometry.getAttribute('normal')?.array` (captured before
+  the geometry is swapped) into `lightmap_build_geometry`.
+- Smallest change, biggest visible win on the sphere.
+
+### P0 — Sample-position PUSH instead of discard (fixes contact black line, B)
+- New `lightmap_push_sample.js`: given world pos + normal + tangent basis + `texel_world_size`,
+  trace 4 tangential rays (length `0.5 × texel_world_size`); if any hits a backface, push the
+  origin out (`pos += rayDir·hitDist + hitFaceNormal·bias`); repeat until clear or a cap.
+- `bake_lightmap_for_scene.js` `prepare()`: run the push when generating each job; store the
+  corrected position. Drop the confidence-discard path in `lightmap_gather` (keep a cheap
+  "still buried after push" → mark hole only as a last resort).
+- Reuses `scene.trace` (already used by the confidence probe).
+
+### P1 — Supersampling: jitter the ray origin in the texel footprint (antialias B, general AA)
+- `lightmap_gather.js`: build a tangent basis from the normal; offset each sample's origin by a
+  random sub-texel amount (`±0.5 × texel_world_size`) in the tangent plane (keep directions
+  independent per sample — no shared set). A contact texel then averages lit/shadowed
+  sub-positions → soft edge instead of a hard line.
+- Pass `texel_world_size` (already available) + reuse `v3_orthonormal_matrix_from_normal`.
+
+### P1 — Graded adaptive sampling (your note: CPU isn't all-or-nothing)
+- `bake_lightmap_for_scene.js`: replace the binary interpolate-vs-full fine path with a
+  **floor of samples** on "smooth" texels: take e.g. `max(samples/4, k)` rays and blend with the
+  bilinear prediction (or accept the samples if they deviate from the prediction beyond
+  `interpolation_threshold`). Keeps a real estimate everywhere — pure lerp can erase small
+  features — while still cutting cost on flats. `adaptive_step`/threshold stay the controls.
+
+### P1 — UV seam stitching (residual sphere value step, A.2)
+- New `lightmap_seam_fix.js`: from each entry's charts, pair `boundary_edges` across charts by
+  `vertex_of_local` (same original edge, different `uv`); for each pair, walk both atlas-space
+  edges and average the texels over a few iterations (Bakery's line-blend, done on the CPU
+  buffer). Run after dilation.
+- Most involved item; do it only if P0-normals + AA leave a visible step.
+
+### P2 — Bicubic lightmap sampling at read time (optional, global softening)
+- Patch the forward-plus lightmap sampling to 4-tap bicubic (`vUv2`). Hides low resolution and
+  softens any remaining jagged lines. Larger change (touches the material/shader); evaluate after
+  the above.
+
+### Post-process order to converge on
+`bake (with push + supersample)` → `variance denoise` → `dilate` → `seam-fix`.
+
+## Verification
+- Sphere: after P0-normals, no facet creases across chart boundaries; after seam-fix, no value
+  step. Add a spec asserting `lightmap_build_geometry` reproduces input normals for a smooth mesh
+  (sphere) within tolerance.
+- Contact: after push + supersample, the box/floor contact is a soft darkening, not a black line.
+  Add a gather/push spec: a texel wedged at a contact gets relocated to a non-buried position
+  (its post-push confidence is high) and bakes > 0.
+- Keep the existing 18 specs green; re-run the webpack build.
+
+## Effort / impact summary
+1. P0 original normals — small, high impact (sphere). **Do first.**
+2. P0 sample push — medium, high impact (contact). **Do first.**
+3. P1 supersample — small/medium, high impact (contact softness + AA).
+4. P1 graded adaptive — small, quality/robustness.
+5. P1 seam stitching — larger, medium impact (only if needed after 1).
+6. P2 bicubic — larger, polish.

package/src/engine/graphics/sh3/lightmap/CODE_REVIEW.md

@@ -0,0 +1,121 @@
+# Lightmap baker — first-principles code review
+
+Multi-agent review (6 dimensions × adversarial verification of every finding). 20 raw
+findings → 13 verified-real, 7 dismissed. **No high-severity correctness bugs.** The
+items below are refinements, ordered by impact.
+
+## Resolved (this pass)
+
+- **Off-surface bias is now a small WORLD-SPACE offset, decoupled from lightmap
+  resolution** (`surface_bias × max(1,|coord|)`, default 0.001). A texel-scaled offset
+  over-pushes on low-res (clip/leak), under-pushes on dense (acne), and varies per-triangle
+  under UV distortion — wrong tool. The texel-footprint **`lightmap_push_sample` relocation
+  was removed entirely** (it was built on the same "move by a fraction of a texel" premise);
+  buried samples are handled by the confidence mask + dilation. This also dissolves #5, #6
+  (push-related) and #10 (the tangent-frame duplication was between gather and push).
+- #1 `ray_batch` now budgets against the adaptive **worst case** (`max(samples_per_texel,
+  max_samples)`), so a noisy batch can't blow the per-cycle ray budget.
+- #3 adaptive stop / denoise variance now uses the **unbiased** estimator (÷(n−1)).
+- #4 normal-carry fallback is now **per-triangle** (one bad face no longer drops authored
+  normals for the whole mesh).
+- #9 deleted the `lightmap_pack_charts` passthrough; the baker calls `atlas_pack_charts`.
+- #12 fixed the `padding` JSDoc (4). #13 added `lightmap_dilate.spec.js`.
+
+Remaining open (low): #7 isotropic world-area scaling, #8 pure-lerp confidence gate,
+#11 job-array preallocation. The notes below are the original review for reference.
+
+---
+
+## Verdict
+
+The architecture is sound from first principles:
+- **Light transport** — cosine-importance Monte-Carlo with the arithmetic mean of
+  `path_trace` results is the unbiased `E/π` estimator (pdf = cosθ/π). The stored `E/π`
+  is correctly reconstructed by three r136's lightmap chunk (`× lightMapIntensity × PI ×
+  albedo/PI = texel·albedo`) — valid while the engine stays on the default
+  (non-physically-correct) lighting path.
+- **Mixed mode** — indirect-only is genuinely achieved (no direct term; bounced direct
+  light at hit surfaces correctly represents indirect).
+- **Geometry/UV** — chart → shared atlas → `uv2`, source-normal carry, conservative
+  rasterization, texel-relative bias + push; the baked positions/normals match the
+  swapped render geometry.
+- **Post-process** — normal- + variance- + boundary-aware denoise, dilation, normal-aware
+  seam-fix. The seam-across-crease and contact-darkening bugs found earlier are addressed.
+
+Gap vs the references: we are CPU Monte-Carlo (noisy, mitigated by adaptive sampling +
+denoise) where ands is a noise-free hemicube; missing techniques are bicubic read-time
+filtering (deferred), Phong-tessellated smooth sample position (shadow terminator), and
+stratified/hierarchical-multilevel sampling.
+
+## Medium
+
+1. **`ray_batch` is budgeted against the minimum sample count, not the adaptive worst
+   case** (`bake_lightmap_for_scene.js`, `rays_per_texel = samples_per_texel * …`). Full
+   texels can grow to `max_samples` (default 128 = 4× `samples_per_texel`), so a cycle that
+   lands on a noisy batch (contacts/edges) can cast ~4× the nominal rays → the frame hitch
+   the parameter exists to prevent. *Deliberate trade-off I flagged when adding it; given
+   the "no hitches" goal, switch to* `max(samples_per_texel, max_samples) * avg_bounces +
+   confidence_probes`.
+
+2. **Supersample AA is a single un-stratified origin jitter sharing the RNG stream with
+   direction sampling** (`lightmap_gather.js`). Bakery uses a 5×5 stratified tap grid; we
+   draw one white-noise origin offset per axis. Higher variance on shadow boundaries than a
+   stratified set would give. *Note: stratified directions were previously declined for
+   inter-texel coupling; the reconciliation is per-texel-rotated stratification (decorrelated
+   per texel), if revisited.*
+
+## Low — correctness / robustness
+
+3. **Adaptive stop uses population variance (÷n), not sample variance (÷(n−1))**
+   (`lightmap_gather.js:132`) → ~3% underestimate at `n≈min_samples`, so the loop can stop a
+   touch early and the denoiser sees slightly low variance. Trivial fix; negligible visually.
+4. **Normal-carry fallback is all-or-nothing per mesh** (`lightmap_build_geometry.js`,
+   `accumulate_source_normals` returns `false` on the first bad triangle → the whole mesh
+   reverts to recomputed geometric normals). One T-junction-split face degrades smooth
+   shading everywhere. Fall back **per triangle** instead.
+5. **Supersample jitter is not re-pushed off geometry** (`lightmap_gather.js`): ±0.5-texel
+   tangential jitter vs ~0.5-texel normal nudge can place a jittered origin inside adjacent
+   geometry near concave edges/curvature → spurious dark first-hit. Couples `supersample`
+   with `surface_bias`; at least document, or scale the nudge to dominate.
+6. **`lightmap_push_sample` reuses the original tangent basis across relocation steps** —
+   after stepping onto a differently-oriented face the probes stay in the old tangent plane.
+   Only matters for deep non-parallel contact pockets; rebuild the basis per step.
+7. **World-area density scaling is isotropic** (`mat4_mean_scale = cbrt(sx·sy·sz)`): under
+   anisotropic instance scale, true per-triangle world area depends on orientation. Sum real
+   world triangle areas (already computed in the rasterize loop) if anisotropic instances matter.
+8. **Pure-lerp fine texels skip the confidence/backface gate** (`interpolate()` commits
+   `coverage=1` unconditionally) — only in `min_sample_fraction = 0` mode (off by default),
+   so buried texels could leak there. Document the mode's trade-off or probe before committing.
+
+## Low — reuse / efficiency / API / tests
+
+9. **`lightmap_pack_charts` is a zero-value passthrough** now that `atlas_pack_charts` is
+   mesh-free (`return atlas_pack_charts(charts, options)`). Delete it (+ its spec) and call
+   `atlas_pack_charts` directly.
+10. **Tangent-frame construction is duplicated** in `lightmap_gather` and
+    `lightmap_push_sample` (same `v3_orthonormal_matrix_from_normal` + two `v3_matrix3_rotate`).
+    Extract one helper next to `v3_orthonormal_matrix_from_normal`.
+11. **Job list is built as boxed JS arrays then copied to typed arrays** (`prepare()`:
+    `jx/jy/jp/jn/jt`). At 2048² this is millions of boxed pushes + a double-held peak.
+    Count-then-preallocate, or write a cursor directly.
+12. **`padding` JSDoc says default 2 but the code is `padding = 4`** — fix the doc. Also the
+    24-option surface is large, and the pure-bilinear branch is dead under defaults
+    (`min_sample_fraction = 0.25`) — document the mode switch or group the adaptive knobs.
+13. **`lightmap_dilate` has no spec** (every sibling does). Add a small black-box test
+    (one-ring growth per pass, hole→neighbour-average, coverage flips to 1).
+
+## Notes (accepted / by design)
+
+- **Memory** ~137 MB of persistent buffers at 2048² (atlas RGBA-f32 67 MB + normals 50 MB +
+  variance 16 MB + coverage 4 MB), +50 MB `world_pos` only under `debug`. Inherent to a dense
+  float atlas; fine, worth knowing before raising resolution.
+- **Denoise boundary-aware `alpha`** uses a binary contributing-count, not a weight-sum, so
+  near-zero-weight neighbours count as full support — a minor over-count (could weight by Σw).
+- The **MC noise vs hemicube** gap and the **residual low-contrast contact AO gradient**
+  (documented in the skipped `lightmap_edge_leak` test) are fundamental to CPU MC + spatial
+  denoise; mitigated, not eliminated, by adaptive sampling.
+
+## Suggested quick wins
+Safe, low-risk: #3 (unbiased variance), #4 (per-triangle normal fallback), #9 (delete
+passthrough), #10 (dedup tangent helper), #12 (padding doc), #13 (dilate spec). Decision
+needed: #1 (`ray_batch` → worst-case bound) given the no-hitch priority.