@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/generation.md

@@ -0,0 +1,176 @@
+# Correctness review — `meep/src/generation`
+
+Scope: every non-spec source file under
+`H:/git/moh/app/src/mir-engine/meep/src/generation/` (~12.2k LOC, 160 files).
+`REVIEW_01_ACTION_PLAN.md` items and `COORDINATES.md` conventions were read first;
+already-addressed items are not re-reported.
+
+Method: full read of the package. Determinism claims about Mulberry32 were
+verified by executing the generator (`core/math/random/seededRandom_Mulberry32.js`)
+directly under node; the measurements are quoted in the findings.
+
+---
+
+### GEN-1 Theme child seeds are `random()` floats; Mulberry32 collapses them to one stream
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/theme/ThemeEngine.js:212`, `H:/git/moh/app/src/mir-engine/meep/src/generation/theme/TerrainTheme.js:29`
+- **Defect**: Both sites use the *output* of a `seededRandom` stream (a float in `[0,1)`) as the *seed* of a child stream. `seededRandom_Mulberry32` does `_seed += 0x6D2B79F5` and then feeds `_seed` through `Math.imul`/`^`/`>>>`, all of which apply ToInt32/ToUint32 and discard the fractional part. Every seed in `[0,1)` therefore produces a byte-identical sequence — identical to `seededRandom(0)`.
+- **Failure scenario**: `themeEngine.random.setCurrentSeed(12345)` → `initializeThemes` derives theme seed `0.9797282677609473`; with world seed `999` it derives `0.9699058223050088`. Both are passed to `Theme.initialize(grid, ecd, seed)` → `TerrainTheme.initialize` → `seededRandom(seed)`. Verified output of the first three draws for seeds `0.1234`, `0.9876` and `0` is identical: `0.26642920868471265, 0.0003297457005828619, 0.2232720274478197`. Consequently, for the shipped `AlienTheme0` / `SnowyTheme`:
+  - every `CellFilterSimplexNoise` reachable from `Theme.terrain.rules` and `Theme.nodes` (`injectBases.js:101`, `injectEnemies.js:355`, `injectTreasure.js:556`, `injectBuffObjects.js:45`, `injectPlayerCharacter.js:88`) is built from the *same* permutation table, and that table never changes with the world seed;
+  - `MarkerNodeTransformRotateRandom` and `MarkerNodeEntityProcessorRandomRotation` (`theme-1/injectDecor.js`) emit the same rotation sequence for every world seed.
+  Two runs with different world seeds produce identical theme-layer noise and identical decor rotations.
+- **Fix**: derive integer child seeds at both sites, e.g.
+  `const seed = randomIntegerBetween(this.random, 0, 0x7FFFFFFF);` in `ThemeEngine.initializeThemes` and
+  `const ruleSeed = randomIntegerBetween(random, 0, 0x7FFFFFFF);` in `TerrainTheme.initialize`.
+  (Same one-line shape; `(random() * 0x100000000) | 0` also works.)
+- **Confidence**: Confirmed
+
+---
+
+### GEN-2 `GridTaskGenerateRoads` never initializes its `traversable` matcher
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/grid/generation/road/GridTaskGenerateRoads.js:513-608`
+- **Defect**: `build()` creates `tInitializeActions` for `this.actions` but there is no `this.traversable.initialize(grid, seed)` anywhere. `traversable` is a required `from({...})` parameter (phase 5.1) and is used by `tBuildDistanceField` (line 567, wrapped in a fresh `CellMatcherNot` that is also never initialized), by the Dijkstra expansion (lines 213, 276) and by `drawPath` (line 425). Every sibling task in the package that accepts a `CellMatcher` initializes it (`GridTaskConnectRooms.build:469`, `GridTaskBuildSourceDistanceMap.build:117`, `CellSupplierBestN.initialize:97`, `GridCellPlacementRule.initialize:91`).
+- **Failure scenario**:
+  ```js
+  const roads = GridTaskGenerateRoads.from({
+      traversable: CellMatcherLayerBitMaskTest.from(TRAVERSABLE_BIT, 'tags'),
+      actions: [GridCellActionPlaceTags.from(ROAD_BIT, 'tags')]
+  });
+  executeTaskTreeSync(roads.build(grid, ecd, 0));
+  ```
+  `tBuildDistanceField` → `buildUnsignedDistanceField` → `traversable.match(grid, 0, 0, 0)` → `GridLayerCellMatcher.__layer` is still `null` → `TypeError: Cannot read properties of null (reading 'sampler')`. `SampleGenerator0` only survives because it passes the module-level singleton `matcher_tag_traversable`, which `GridTaskConnectRooms` happens to bind first; a per-run matcher factory (the pattern review-01 §3.7 mandates) crashes. `GridTaskGenerateRoads.spec.js` misses it because it passes `CellMatcherAny.INSTANCE`, which needs no initialization.
+- **Fix**: build the negated matcher once and initialize both in an init task that `tBuildDistanceField` / `tBuildPaths` / `tDrawPaths` depend on:
+  ```js
+  const not_traversable = CellMatcherNot.from(traversable);
+  const tInitializeMatchers = actionTask(() => {
+      traversable.initialize(grid, seed);
+      not_traversable.initialize(grid, seed);
+  });
+  // tBuildDistanceField uses not_traversable; add tInitializeMatchers as a dependency of
+  // tBuildDistanceField, tBuildPaths and tDrawPaths.
+  ```
+- **Confidence**: Confirmed
+
+---
+
+### GEN-3 `ThemeEngine.applyNodes` indexes samplers with fractional marker coordinates
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/theme/ThemeEngine.js:166` (`getThemesByPosition`) and `:466`
+- **Defect**: `applyNodes` passes `node.position.x/y` — continuous grid coordinates — straight into `Sampler2D.readChannel`, which computes `index = (y * width + x) * itemSize + channel`. With a fractional coordinate the index is fractional and a typed-array read returns `undefined`, not a value.
+  - `getThemesByPosition:168`: `if (filled === 0) continue;` — `undefined === 0` is `false`, so the mask refinement is skipped entirely and *every* theme whose quadtree bounds contain the point is accepted.
+  - `applyNodes:466-470`: `influenceSum += undefined` → `NaN`, so `influenceSum > 0` is false and the code always takes the "all themes at zero influence" branch (`randomIntegerBetween`), discarding the distance-field weighting.
+  `applyTerrainThemes` and `applyCellRules` are unaffected (they iterate integer cell indices).
+- **Failure scenario**: markers produced by `GridTaskDensityMarkerDistribution` are always at fractional positions (`processArea:225`, `_x = x0 + u * width`), and they are the bulk of the marker set in `AlienGridGenerator`. Given two `AreaTheme`s whose bounds both cover grid cell (12,8) but where only theme A's mask is set there, a marker at (12.37, 8.91) reports `matchingThemeCount === 2` and is then assigned to A or B with 50/50 probability. With a single partially-filled mask, a marker at a fractional position outside the mask is themed as if it were inside. (The shipped game escapes this only because `LevelGenerator.js:169` fills one mask over the entire grid.)
+- **Fix**: quantise to the cell the marker sits in before probing the mask/distance field, e.g. in `applyNodes`
+  ```js
+  const x = Math.round(nodePosition.x);
+  const y = Math.round(nodePosition.y);
+  ```
+  and use those for both `getThemesByPosition` and `areaMask.distanceField.readChannel`. (Rounding matches `COORDINATES.md`: integer grid coordinates are cell centers.)
+- **Confidence**: Confirmed
+
+---
+
+### GEN-4 `GridCellActionPlaceMarkerGroup` never initializes its children
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/markers/GridCellActionPlaceMarkerGroup.js:11-81`
+- **Defect**: the class inherits `GridCellAction.initialize`, which only runs asserts. It never forwards to `this.children`, so the wrapped `GridCellActionPlaceMarker`s (and therefore their `transformers`, which `GridCellActionPlaceMarker.initialize:50` is responsible for) are never initialized. Every other composite in the package forwards (`GridCellActionSequence:31`, `CellActionSelectRandom:41`, `MarkerNodeEmitterFromAction:33`).
+- **Failure scenario**:
+  ```js
+  const group = GridCellActionPlaceMarkerGroup.from([
+      GridCellActionPlaceMarker.from({
+          type: 'town',
+          transformers: [MarkerNodeTransformerRecordUniqueRandomEnum.from('name', ['a', 'b'])]
+      })
+  ]);
+  group.initialize(grid, 0);
+  group.execute(grid, 1, 1, 0);
+  ```
+  `MarkerNodeTransformerRecordUniqueRandomEnum.unused` is still the class-field default `[]` (it is only filled in `initialize`), so `transform` throws `Error('All values used up')` on the very first placement. With a `MarkerNodeTransformerYRotateByFilter(CellFilterSimplexNoise…)` instead, `this.noise` is still `null` and `execute` throws `TypeError: this.noise is not a function`. The two sample call sites (`mir_generator_place_bases.js:78`, `mir_generator_place_buff_objects.js:98`) only escape because their group children carry no transformers.
+- **Fix**:
+  ```js
+  initialize(data, seed) {
+      super.initialize(data, seed);
+      const children = this.children;
+      for (let i = 0; i < children.length; i++) {
+          children[i].initialize(data, seed);
+      }
+  }
+  ```
+- **Confidence**: Confirmed
+
+---
+
+### GEN-5 `CellFilterCache.execute` ignores `scale` when sampling the cache
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/filtering/numeric/CellFilterCache.js:73-75`
+- **Defect**: `initialize` builds a `scale·w × scale·h` cache where texel `(x,y)` holds `source(x/scale, y/scale)` (lines 43-67 — the correct ratio mapping per `COORDINATES.md`). `execute` then reads `this.__cache.sampleChannelBilinear(x, y, 0)` with the raw *grid* coordinate, i.e. it applies `grid_to_texel(v, 1)` instead of `grid_to_texel(v, scale)`.
+- **Failure scenario**: 16×16 grid, `source` = the ramp filter `h(x,y) = x`, `CellFilterCache.from(source, 2)`. Cache is 32×32 with `cache[x] = x/2`. `filter.execute(grid, 10, 0, 0)` returns `5` instead of `10`. Cells `x = 0..15` sample cache texels `0..15`, i.e. only the left half of the grid's value range — the filter is magnified 2× and the right/bottom halves of the map are silently duplicated from the top-left quadrant. Any `scale !== 1` is affected; `scale === 1` is correct, which is why all current call sites (`MohFilterMinorSlope.js:22`, `MohGridFilterTechnology.js:42`, `AlienGridGenerator.js`) are unaffected.
+- **Fix**: `return this.__cache.sampleChannelBilinear(x * this.scale, y * this.scale, 0);` (or `grid_to_texel(x, this.scale)`).
+- **Confidence**: Confirmed
+
+---
+
+### GEN-6 Density-distribution per-tile seeds collapse to ~2048 distinct RNG streams
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/grid/generation/GridTaskDensityMarkerDistribution.js:343`
+- **Defect**: `const seed = Math.floor(random() * Number.MAX_SAFE_INTEGER);`. `random()` returns `k / 2^32` for an integer `k < 2^32`, so the product is `k·2^21` (± 1 ulp) — the low 21 bits are always zero. Mulberry32 then does `_seed += 0x6D2B79F5` and truncates to int32, keeping only `k mod 2^11`. Effective seed space ≈ 2^11.
+- **Failure scenario**: measured — feeding 4096 consecutive draws of `seededRandom(12345)` through this expression yields 4096 distinct raw seeds but only **1776 distinct effective int32 values**, consistent with 2048 buckets. A 128×128 grid is split into 64 tiles of 16×16 (`tile_size = 16`, lines 312/333/338), so the expected number of colliding tile pairs is `C(64,2)/2048 ≈ 0.98` — roughly 63 % of runs have at least one pair of tiles sharing an identical RNG stream. Two such tiles execute `processArea` with the same `(u, v)` sequence, the same density rolls and the same `scale.sampleRandom` draws, so wherever the density filter is locally flat they receive markers at identical intra-tile offsets — a visibly repeated decor cluster. `AlienGridGenerator` / `AlienCombatSceneGenerator` instantiate ~20 of these tasks per generation.
+- **Fix**: `const seed = randomIntegerBetween(random, 0, 0x7FFFFFFF);` (or `(random() * 0x100000000) | 0`) so the full int32 range reaches Mulberry32.
+- **Confidence**: Confirmed (entropy collapse measured; the visual repetition follows from identical streams over identical tile geometry)
+
+---
+
+### GEN-7 `ThemeEngine.apply` never passes a seed to `applyNodes`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/theme/ThemeEngine.js:633` (declaration at `:410`)
+- **Defect**: `applyNodes(grid, ecd, seed = 0)` is called as `this.applyNodes(grid, ecd)`, so its `seededRandom(seed)` is always seeded `0` regardless of `ThemeEngine.seed`. Unlike GEN-1 the stream is well-formed; it is simply constant across world seeds.
+- **Failure scenario**: two `AreaTheme`s with overlapping masks over the same region. Run the same generator with world seed `1` and world seed `2`: every marker inside the overlap is assigned to the same theme in both runs (the marker set differs, but the theme-selection draw sequence is identical), so the theme mix at boundaries never varies with the seed.
+- **Fix**: `const tNodes = this.applyNodes(grid, ecd, randomIntegerBetween(this.random, 0, 0x7FFFFFFF));` (pairs with the GEN-1 fix).
+- **Confidence**: Confirmed
+
+---
+
+### GEN-8 `CellSupplierBestN` throws when `limit === 0`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/grid/generation/grid/select/CellSupplierBestN.js:133-139`
+- **Defect**: the eviction ladder is
+  ```js
+  if (fitness_scratch.length < this.limit) { /* push */ }
+  else if (fitness_scratch[0].score < fitness) { fitness_scratch.shift(); }
+  else { continue; }
+  ```
+  With `limit === 0` the first branch is false on the very first candidate and `fitness_scratch[0]` is `undefined`. `from()` only guards with `assert.isNonNegativeInteger(limit)`, which admits 0 and is stripped in production anyway.
+- **Failure scenario**: `CellSupplierBestN.from({ fitness: CellFilterLiteralFloat.ONE, limit: 0 })` (e.g. a caller computing `limit` from a difficulty budget that evaluates to 0) → `initialize(grid, 0)` on any grid with at least one predicate-matching cell → `TypeError: Cannot read properties of undefined (reading 'score')`. The intended result is an empty selection.
+- **Fix**: make the ladder handle a zero capacity, e.g. start with `if (this.limit === 0) { return; }` before the scan loop, or change the first branch to `if (fitness_scratch.length < this.limit) { … } else if (this.limit > 0 && fitness_scratch[0].score < fitness) { … }`.
+- **Confidence**: Confirmed
+
+---
+
+### GEN-9 `MarkerNodeEmitterPredicated` never initializes its predicate
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/generation/markers/emitter/MarkerNodeEmitterPredicated.js:44-46`
+- **Defect**: `initialize(data, seed)` forwards only to `this.source`; `this.nodePredicate.initialize(grid, seed)` is never called. The `GridDataNodePredicate` interface declares `initialize(grid, seed)` and both combinators implement the recursion (`GridDataNodePredicateBinary:38`, `GridDataNodePredicateNot:34`), so the recursion exists but its root is never driven. `MarkerNodeEmitterPredicated` is the only consumer of predicates in the package.
+- **Failure scenario**: any predicate that binds per-run state on initialize — the same shape as `GridLayerCellMatcher.initialize` (resolve `layerId` → `__layer`) — keeps `__layer === null` and throws `TypeError: Cannot read properties of null` on the first `evaluate`. The two shipped predicates (`…Overlaps`, `…Any`) have empty `initialize` bodies, so no in-repo configuration fails today; the defect is only reachable from library-user predicates.
+- **Fix**:
+  ```js
+  initialize(data, seed) {
+      this.source.initialize(data, seed);
+      this.nodePredicate.initialize(data, seed);
+  }
+  ```
+- **Confidence**: Likely (contract violation confirmed by reading; no in-repo predicate exercises it)
+
+---
+
+## Areas checked and found clean
+
+- **Cellular automata** (`automata/CaveGeneratorCellularAutomata.js`, `grid/generation/discrete/GridTaskCellularAutomata.js`): true double-buffered synchronous step, correct edge/corner neighbour enumeration, OOB = dead as documented, thresholds match the doc comment, `front`/`back` swap read correctly by `tWriteTags`.
+- **Coordinate conventions**: `grid_to_texel`/`texel_to_grid` used consistently by `GridCellActionWriteFilterToLayer`, `CellMatcherLayerBitMaskTest` (OOB → no match), `AbstractCellFilterSampleGridLayer`, `MarkerNodeActionPaintTerrain` (region clamped, symmetric rounding), `populateSampler2DFromCellFilter`. `ContinuousGridCellActionSetTerrainHeight`'s corner mapping is the documented deliberate deviation. Row/column stride (`index % width`, `(index / width) | 0`) is consistent everywhere including non-square grids.
+- **Grid tasks / scheduling**: `GridTaskGroup` sibling-only dependency resolution, `GridTaskSequence` chaining, `TaskGroup.addDependency` group flattening, `countTask`/`randomCountTask` initializer-time limit resolution — all consistent; no task reads a layer written by a task it does not depend on.
+- **Placement / rejection sampling**: `GridTaskExecuteRuleTimes` closes every attempted cell and terminates via `closedCount >= gridSize`; `GridTaskDensityMarkerDistribution.processArea` bounds both the iteration and the rejection budget; `GridTaskConnectRooms.tMain` makes monotone progress in `connected`; `buildPathFromDistanceMap` is strictly decreasing so it cannot loop.
+- **Weighted selection**: `random_pick_weighted_index` cumulative bound and zero-total guard are correct and shared by both selects; the RNG is not consumed on the zero-weight path.
+- **Comparators**: `byScore`/`byIndex` in `CellSupplierBestN`, the priority sort in `applyNodes`, and the layer-descriptor sort in `applyTerrainThemes` are all well-formed numeric comparators.
+- **Module-static scratch**: `GridData.marker_collection`, `CellFilterCurvature`'s normals, `CellFilterAngleToNormal.normal`, `CellFilterLookupTable.sample`, `RoadConnectionNetwork.scratch_paths`, `CellSupplierPathUpHill.scratch_neighbours`, both `evaluatedWeights` arrays — none can be re-entered by the code paths that reach them (`computeFilterSurfaceNormal` writes its result only after all sampling, as documented).
+- **Determinism sources**: no `Math.random`, `Date.now`, `performance.now` or `new Date()` anywhere in the package; every iteration over a `Map`/quadtree is insertion-ordered; `ArrayIteratorRandom` defaults to `seededRandom(0)` rather than an unseeded source.

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

@@ -0,0 +1,434 @@
+# Correctness review — `core/geom/` 2D half + shared primitives
+
+Scope: everything under `core/geom/2d/`, plus the loose files directly in `core/geom/`
+(`Vector1.js`, `Vector2.js`, `Vector3.js`, `Vector4.js`, `Quaternion.js`, `ConicRay.js`,
+`normalize_angle_rad.js`) and the shared sub-packages `vec/`, `vec2/`, `vec4/`, `mat2/`,
+`mat3/`, `packing/`, `random/`.
+`AABB3`, `Ray`, `Plane`, `Sphere`, `Frustum`, `Transform`, `Matrix4` all live under
+`core/geom/3d/` and were **not** reviewed (other reviewer's scope). `vec3/` likewise skipped
+as 3D-specific.
+
+Every finding below was reproduced by executing the real module in node
+(the files are plain ESM and import cleanly with `file:///` URLs, no jest needed).
+
+---
+
+## Files with no adjacent spec (prioritised, in review order)
+
+High-risk (non-trivial logic, no spec):
+`2d/line/ray2_ray2_compute_intersection_array_2d.js`,
+`2d/line/segment2_intersects_segment2_2d.js`,
+`2d/line/segment2_segment_compute_intersection_array_2d.js`,
+`2d/line/line2_segment_intersection_fraction_2d.js`,
+`2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js`,
+`2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js`,
+`2d/quad-tree/qt_collect_by_box.js`, `qt_collect_by_circle.js`,
+`qt_query_closest_to_point.js`, `qt_query_data_raycast.js`, `qt_collect_data_all.js`,
+`2d/triangle/tri2_compute_barycentric.js`, `2d/triangle/tri2_contains_point.js`,
+`2d/aabb/aabb2_intersects_ray.js`, `aabb2_intersects_circle.js`,
+`aabb2_compute_intersection.js`, `aabb2_signed_distance_to_point.js`,
+`2d/polygon/polygon2_triangulation_deviation.js`,
+`packing/max-rect/*` (whole directory), `packing/miniball/*`,
+`mat3/m3_invert.js`, `m3_make_rotation_TBN.js`, `m3_rm_compose_transform.js`,
+`vec/vector_normalize.js` (spec exists but does not cover the zero vector).
+
+Low-risk / trivially correct on read (verified, no findings):
+`2d/aabb/aabb2_area.js`, `aabb2_array_set.js`, `aabb2_contains_point.js`,
+`aabb2_distance_sqr_to_point.js`, `aabb2_union_array.js`,
+`2d/circle/circle_*.js`, `2d/rectangle_to_aabb.js`, `2d/spline2_quadratic_bezier.js`,
+`vec2/*`, `vec4/*`, `mat2/*`, `vec/vector_*`, `random/*`, all the `@deprecated`
+rename shims.
+
+Areas checked and found **clean** (no finding to report):
+- `polygon2_triangulate.js` — faithful earcut port; the sign inversion at `orient()`
+  (line 202-204) is correct and consistently applied through every one of ~20 comparisons
+  (verified against earcut 3.x term by term). 400 random simple polygons + 300
+  hole cases: area deviation `0` in every case. Duplicated-vertex contours agree
+  above and below `HASH_THRESHOLD`. `ensure_node_capacity` bound (`3V + 2C`) is sound.
+- `polygon2_is_counter_clockwise.js` — 20 000 randomised contours at offset (1000,1000),
+  zero disagreements with `polygon2_signed_area`'s sign. The exact-predicate-at-the-lex-min
+  vertex argument is valid (a simple polygon cannot be collinear at its lex-min vertex).
+- `polygon2_signed_area.js` / `tri2_signed_area.js` — the "form differences first"
+  rewrites are algebraically identical to the shoelace/cross reference and correctly
+  handle the repeated-first-as-last point.
+- `v2_morton_encode.js` — `split_by_2` masks to 16 bits, the `<< 1` + `>>> 0` handles
+  bit 31 correctly.
+- `orient2d_indexed.js` — confirmed by execution that `robust-predicates@3.0.2`
+  `orient2d(0,0, 1,0, 0,1) === -1`, i.e. NEGATIVE for CCW. `convex_hull_monotone_2d`
+  (ported from `monotone-convex-hull-2d`, which used `robust-orientation` — same
+  inverted convention) and `convex_hull_jarvis_2d` are both consistent with it.
+- `aabb2_intersects_ray.js` — matches Geometric Tools `IntrRay2Box2::Test` exactly.
+- `aabb2_clip_line_cohen_sutherland.js` — matches the reference Cohen–Sutherland.
+- `aabb2_signed_distance_sqr_to_point.js` — the `-dx * dx` in the penetration branch
+  reads as a precedence bug but is correct (`(-dx)*dx == -(dx*dx)` since `dx < 0` there).
+- `circle_compute_intersection.js` — matches Bourke's circle-circle formula term for term.
+- `tri2_rasterize_conservative.js` — SAT axis set is complete (2 box + 3 edge normals),
+  and touching counts as overlap, which is what "conservative" requires.
+- `packing/skyline.js` — the `count + 2` scratch bound is provably sufficient (at most one
+  segment can straddle both cut edges); `find`'s dead `x < best_x` tie-break is harmless
+  because segments are x-ascending, so first-found is already leftmost.
+- `tri2_contains_point.js` — the `Float32Array` scratch was suspected of losing the
+  `|1-u-v-w| < 1e-7` test; 400 000 fuzz cases (including coordinates at 1e5) produced
+  zero false negatives at triangle centroids. Not a defect.
+- `Vector3.crossVectors` reads all six components before writing, so
+  `m3_make_rotation_TBN`'s `v3_scratch_1.crossVectors(v3_scratch_2, v3_scratch_1)`
+  aliasing is safe.
+- `StaticR2Tree.build()` heap-layout arithmetic, `qt_collect_data_all` cursor arithmetic,
+  `QuadTreeNode` merge/split `treeDataCount` bookkeeping — all verified correct.
+
+---
+
+### GEOM2-1 `polygon2_clip_halfplane` extrapolates the crossing vertex far outside the segment
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/polygon/polygon2_clip_halfplane.js:32-46`
+- **Defect**: `in_a`/`in_b` classify vertices with an epsilon-slacked side test
+  (`sa >= -POINT_EPS`), but the emitted crossing uses the *exact* line parameter
+  `t = sa / (sa - sb)`. When `in_a !== in_b` while `sa` and `sb` have the **same** sign
+  (`sa` inside the slack band, `sb` just outside it) `t` is negative and unbounded as
+  `sa - sb → 0`, so the emitted vertex is extrapolated backwards off the segment.
+  The axis-aligned twin `polygon2_clip_axis_halfplane` has no epsilon and therefore
+  cannot produce this — its `in_a !== in_b` really does imply opposite sides, so
+  `t ∈ [0,1]`.
+- **Failure scenario**:
+  ```js
+  polygon2_clip_halfplane(
+      Float64Array.from([0, -1e-9,  1, -1.0000000001e-9,  1, 5,  0, 5]), 4,
+      out, /*ex*/0, /*ey*/0, /*dx*/1, /*dy*/0, /*keep_left*/true);
+  ```
+  Here `s == y`, so `sa = -1e-9` (inside the slack, `in_a = true`) and
+  `sb = -1.0000000001e-9` (outside it, `in_b = false`), `sa - sb = 1e-19`,
+  `t = -1e10`.
+  Produced: 5 vertices, the second being `(-10000006779.697906, 0)`.
+  Expected: the crossing must lie **on** the segment `(0,-1e-9) → (1,-1e-9)`,
+  i.e. x ∈ [0, 1] (Sutherland–Hodgman, Foley & van Dam §3.14: the emitted point is
+  `A + t(B-A)` with `t ∈ [0,1]` by construction).
+  Every downstream consumer of the clipped polygon (area, containment, further clips)
+  is then wrong by ten orders of magnitude. The mirrored case
+  (`keep_left = false`, `sa ∈ (0, POINT_EPS]`) is identical.
+- **Fix**: clamp the parameter — the crossing is on the segment by construction:
+  `const t = clamp01(sa / (sa - sb));` (`core/math/clamp01.js`). Alternatively decide
+  `in_a`/`in_b` on the exact sign (`sa >= 0`) and use `POINT_EPS` only to snap a
+  near-boundary *vertex* onto the kept side, which is what the comment claims the
+  epsilon is for.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-2 `shg_query_elements_line` skips cells the segment passes through, so it misses elements
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/hash-grid/shg_query_elements_line.js:108-131`
+- **Defect**: the grid walk is not a DDA. It steps to whichever of the two candidate
+  cells has the **cell centre** closest to the segment
+  (`line2_compute_segment_point_distance_sqr(... x+step_x+0.5, y+0.5)` vs
+  `... x+0.5, y+step_y+0.5`). That ordering is not equivalent to the order in which the
+  segment actually crosses cell boundaries, so the 4-connected path can step onto a cell
+  the segment never enters *instead of* one it does. Elements registered only in the
+  skipped cell are never visited — a silent false negative.
+- **Failure scenario**: `new SpatialHashGrid(8, 8, 1)` holding a single element with
+  bounds `(3.0, 3.0)–(3.999, 3.999)` (entirely inside cell `(3,3)`), queried with
+  ```js
+  shg_query_elements_line(result, 0, grid,
+      5.516462491825223, 3.617749162018299,
+      3.8124522920697927, 4.040001254528761);
+  ```
+  Produced: `0` hits.
+  Expected: `1` hit — `aabb2_clip_line_cohen_sutherland` on the same segment and the same
+  box returns `true` (clip `(3.999, 3.9938)–(3.9779, 3.999)`). The segment crosses `y = 4`
+  at `x = 3.9739`, i.e. inside column 3, so the true cell sequence is
+  `(5,3) (4,3) (3,3) (3,4)`; the walk produces `(5,3) (4,3) (4,4) (3,4)`.
+  A 4000-segment fuzz over an 8×8 grid missed at least one truly-crossed cell in
+  **14 cases (0.35 %)**.
+- **Fix**: replace the centre-distance heuristic with the standard Amanatides–Woo
+  voxel traversal (Amanatides & Woo 1987, *A Fast Voxel Traversal Algorithm for Ray
+  Tracing*): precompute `t_max_x`/`t_max_y` to the next cell boundary and
+  `t_delta_x`/`t_delta_y`, then step the axis with the smaller `t_max`. That is exact by
+  construction and no more expensive per step.
+- **Confidence**: Confirmed (executed end-to-end against the real `SpatialHashGrid`).
+
+---
+
+### GEOM2-3 `convex_hull_fixed_count_2d_bruteforce` minimises a SIGNED area, so clockwise input yields the *largest* polygon
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_bruteforce.js:111-116`
+- **Defect**: `const area = polygon2_signed_area(intersections, k); if (area < best_area)`.
+  `polygon2_signed_area` is **signed** — negative for a clockwise loop. The intersection
+  polygon inherits the input's winding, so for clockwise input every candidate area is
+  negative and `area < best_area` selects the *most negative*, i.e. the maximum-area
+  polygon. The function's contract ("such that the area would be minimal") and its input
+  contract ("must be an ordered loop… must form a convex hull") say nothing about winding,
+  and nothing normalises it.
+- **Failure scenario**: regular octagon, circumradius 10, `output_point_count = 4`.
+  - CCW input → produced quad area **341.421**, which is the true minimum
+    (the square on four alternating edge lines, side `2·10·cos 22.5° = 18.478`).
+  - The *same octagon* wound CW → produced quad area **482.843**
+    (`(0,-24.14) (-10,0) (0,24.14) (10,0)`), 41 % larger than the achievable minimum.
+  - 12-gon: CCW → 373.205 (correct minimum, `= (2·10·cos15°)²`); CW → **746.410**, exactly
+    2× the minimum.
+- **Fix**: compare `Math.abs(area)`, or normalise the input winding once at entry
+  (`polygon2_is_counter_clockwise` + reversed iteration) so the objective is unsigned.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-4 `convex_hull_fixed_count_2d_relaxation` uses a signed collapse cost, so clockwise input diverges
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_fixed_count_2d_relaxation.js:161-170`
+- **Defect**: `compute_collapse_cost` returns `tri2_signed_area(v0, target, v1)`, fed
+  straight into `edge_heap` and consumed with `pop_min`. For a counter-clockwise loop the
+  collapse target lies to the right of `v0→v1`, so the signed area is positive and the
+  greedy correctly removes the cheapest (smallest added area) edge. For a clockwise loop
+  every cost is negative, so `pop_min` selects the collapse that adds the **most** area,
+  and the hull runs away. (The commented-out `if (area < 0 || Number.isNaN(area))
+  debugger;` at lines 166-168 shows the non-negative assumption.)
+- **Failure scenario**: regular 12-gon, circumradius 10, `output_point_count = 4`.
+  - CCW input → 4 points, area 402.07 (greedy, documented as suboptimal vs the
+    exact 373.205 — acceptable).
+  - Same 12-gon wound CW → 4 points at
+    `(1790557056.00, 6682451968.00), (8.66,-5.00), (-5.00,-18.66), (-10.00,0)`,
+    area **6.68e10**. Every input point has |coordinate| ≤ 10; a bounding polygon
+    must too, and its area cannot exceed a few hundred.
+- **Fix**: `return Math.abs(area)` in `compute_collapse_cost`, or normalise the input
+  winding at entry (same fix as GEOM2-3, and the two functions should share it).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-5 `ray2_ray2_compute_intersection_array_2d` rejects every intersection with `t < 0.5`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:33-34`
+- **Defect**: `if (t < 0.5) return false; // Intersects on the wrong side`. For a ray,
+  "wrong side" is `t < 0`; `0.5` discards the entire first half of the parameter range.
+  The `t` derivation above it is correct (`t = (dir_b × (o_a - o_b)) / (dir_a × dir_b)`),
+  so the rejection threshold is the only defect. The adjacent spec
+  (`2d/intersect_ray_2d.spec.js`) only exercises `t = 2`, so it does not pin this down.
+- **Failure scenario**: ray A origin `(0,0)` direction `(1,0)`; ray B origin `(0.25,-1)`
+  direction `(0,1)`. The rays cross at `(0.25, 0)` with `t = 0.25 ≥ 0`.
+  Produced: `false`, `result` untouched.
+  Expected: `true`, `result = [0.25, 0]`. (Same call with B at `x = 0.75` → `t = 0.75`
+  → correctly returns `true, [0.75, 0]`, confirming the threshold is what rejects it.)
+- **Fix**: `if (t < 0) return false;`.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-6 `ray2_ray2_compute_intersection_array_2d` uses an absolute parallelism epsilon on an unnormalised cross product
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/ray2_ray2_compute_intersection_array_2d.js:21-26`
+- **Defect**: `if (Math.abs(denominator) < 1e-7) return false;` where
+  `denominator = dir_a × dir_b`. The function's own doc requires the directions to be
+  **unnormalised**, "derived from line length", so the cross product scales as
+  `|dir_a|·|dir_b|·sin θ`. For short edges the magnitude collapses and perfectly
+  perpendicular rays are reported parallel. `convex_hull_fixed_count_2d_bruteforce` and
+  `..._relaxation` build their directions exactly this way from polygon edges, so a
+  small-scale polygon silently loses valid edge intersections.
+- **Failure scenario**: ray A origin `(0,0)` direction `(1e-4, 0)`; ray B origin
+  `(0.5e-4, -1e-4)` direction `(0, 1e-4)`. `denominator = 1e-8 < 1e-7`.
+  Produced: `false` ("parallel").
+  Expected: `true`, `result = [0.5e-4, 0]` — the directions are exactly orthogonal
+  (`sin θ = 1`).
+- **Fix**: make the test scale-relative, e.g. reject when
+  `Math.abs(denominator) <= EPS * Math.hypot(dir_a_x, dir_a_y) * Math.hypot(dir_b_x, dir_b_y)`,
+  or test `denominator === 0` and let the caller filter by the resulting magnitude.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-7 `segment2_intersects_segment2_2d` / `..._compute_intersection_array_2d` report collinear overlapping segments as disjoint
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/line/segment2_intersects_segment2_2d.js:23-28`
+  and `2d/line/segment2_segment_compute_intersection_array_2d.js:33-38`
+- **Defect**: `inv_denom = 1 / (-s2_x*s1_y + s1_x*s2_y)`. For parallel segments the
+  denominator is `0`, so `inv_denom = Infinity`; for *collinear* segments the numerators
+  are also `0`, giving `s = t = 0 * Infinity = NaN`, and every comparison against `NaN`
+  is false. The in-file twin used by the triangulator
+  (`2d/polygon/polygon2_triangulate.js:425-452 segments_intersect`) explicitly handles the
+  collinear-touching case via `on_segment`, so the two "do these segments intersect"
+  predicates in the same package disagree.
+- **Failure scenario**: `segment2_intersects_segment2_2d(0,0, 2,0, 1,0, 3,0)` — the two
+  segments overlap along `x ∈ [1,2]` on the line `y = 0`.
+  Produced: `false`. Expected: `true` (they share infinitely many points).
+  This matters for grid-aligned data, where collinear edges are the common case.
+- **Fix**: branch on `denominator === 0` and, when the segments are also collinear
+  (`cross(b0 - a0, s1) === 0`), decide by 1D interval overlap along the dominant axis —
+  the same structure `polygon2_triangulate.segments_intersect` already uses. If the
+  exclusion is deliberate, document it on both functions.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-8 `min_area_rect_2d` returns `area: Infinity` alongside `width: 0, height: 0`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/oriented-box/min_area_rect_2d.js:26,38-40,68`
+- **Defect**: `best_area` is seeded to `Infinity` and only ever lowered inside the loop.
+  When every hull edge is shorter than the `1e-12` guard the loop body is `continue`d for
+  all of them and the seed is returned, while `best_width`/`best_height` keep their `0`
+  seeds. The `h < 2` early-out at line 22-24 does not cover this: `convex_hull_monotone_2d`
+  returns two indices for three coincident points.
+- **Failure scenario**: `min_area_rect_2d([1,1, 1,1, 1,1], 3)`
+  Produced: `{ angle: 0, width: 0, height: 0, area: Infinity }`.
+  Expected: `{ angle: 0, width: 0, height: 0, area: 0 }` — the object is internally
+  inconsistent as returned (`area !== width * height`), and a caller ranking candidate
+  boxes by `area` will rank a degenerate cluster as the worst possible instead of the best.
+  Also reachable with two near-coincident points: `min_area_rect_2d([0,0, 1e-13,0], 2)`.
+- **Fix**: after the loop, `if (best_area === Infinity) { return { angle: 0, width: 0,
+  height: 0, area: 0 }; }` — or derive the returned `area` from `best_width * best_height`
+  so the three fields cannot disagree.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-9 `convex_hull_monotone_2d` and `convex_hull_jarvis_2d` return opposite windings
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/convex-hull/convex_hull_monotone_2d.js:103-114`
+  vs `2d/convex-hull/convex_hull_jarvis_2d.js:64-87`
+- **Defect**: both are correct hulls, but they traverse in opposite directions and neither
+  documents its winding. `convex_hull_jarvis_2d`'s doc says only "ordered to form a closed
+  loop around the hull"; `convex_hull_monotone_2d` says nothing. A caller that swaps one
+  for the other (they are drop-in compatible by signature and return type — flat xy in,
+  index array out) silently inverts every downstream orientation test.
+- **Failure scenario**: `points = [0,0, 4,0, 4,4, 0,4, 2,2]`, `point_count = 5`.
+  - `convex_hull_jarvis_2d` → `[0, 1, 2, 3]` = `(0,0) (4,0) (4,4) (0,4)`,
+    signed area `+16` (counter-clockwise).
+  - `convex_hull_monotone_2d` → `[0, 3, 2, 1]` = `(0,0) (0,4) (4,4) (4,0)`,
+    signed area `−16` (clockwise).
+  Existing consumers happen to be winding-insensitive (`min_area_rect_2d` takes
+  min/max projections), so nothing is broken today — but the contract gap is a live trap.
+- **Fix**: document the winding on both, and make them agree (reverse the merge order in
+  `convex_hull_monotone_2d`'s `result` assembly, lines 107-113, is the smaller change).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-10 `qt_match_data_by_circle` / `qt_query_data_raycast` throw when the documented-optional `predicate` is omitted
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/quad-tree/qt_match_data_by_circle.js:17,56`
+  and `2d/quad-tree/qt_query_data_raycast.js:18,76`
+- **Defect**: both declare `@param {function(...)} [predicate]` and
+  `@param {*} [predicateContext]` — square brackets, i.e. optional — but call
+  `predicate.call(predicateContext, ...)` unconditionally for every candidate datum.
+- **Failure scenario**:
+  ```js
+  const tree = new QuadTreeNode(0, 0, 100, 100);
+  tree.add("a", 1, 1, 2, 2);
+  qt_match_data_by_circle([], 0, tree, 1.5, 1.5, 5);   // predicate omitted
+  ```
+  Produced: `TypeError: Cannot read properties of undefined (reading 'call')`.
+  Expected: `1` (the datum is inside the circle), per the JSDoc.
+  Note the throw only happens once a candidate is found, so an empty tree passes and the
+  bug hides until there is data.
+- **Fix**: either drop the brackets in the JSDoc (making `predicate` required — the
+  no-predicate case is already served by `qt_collect_by_circle`), or guard:
+  `if (d2_to_datum <= r2 && (predicate === undefined || predicate.call(...)))`.
+  Given the codebase preference for uniform control flow, the JSDoc fix is the better one.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-11 `StaticR2Tree.sort_morton` seeds the shared scratch stack at absolute index 0, but reads from `stack.pointer`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/r-tree/StaticR2Tree.js:219-245`
+- **Defect**:
+  ```js
+  const stack_top = stack.pointer;
+  let stackPointer = stack_top + 2;
+  stack[0] = 0;                              // <- absolute 0
+  stack[1] = this.__node_count_leaf - 1;     // <- absolute 1
+  ...
+  while (stackPointer > stack_top) {
+      stackPointer -= 2;
+      const right = stack[stackPointer + 1]; // <- reads stack_top+1
+      const left  = stack[stackPointer];     // <- reads stack_top
+  ```
+  The seed is written at absolute indices 0/1 while the first pop reads
+  `stack_top`/`stack_top + 1`. This is only correct when `stack.pointer === 0`.
+  `SCRATCH_UINT32_TRAVERSAL_STACK` is a module-level singleton shared with
+  `bvh2d_query_all_data_by_circle` and the other traversals.
+- **Failure scenario**: with `SCRATCH_UINT32_TRAVERSAL_STACK.pointer === 4` on entry
+  (a BVH traversal in progress, e.g. `sort_morton` called from a query callback), the
+  first iteration reads `stack[4]`/`stack[5]` — stale node indices from that traversal —
+  as the quicksort range. With those being arbitrary node ids, `__swap_leaves` writes
+  outside the leaf block or the sort silently does nothing; the tree is then built from
+  unsorted leaves. Expected: the sort range is always `[0, leaf_count-1]`.
+  Also note `sort_morton` never claims or releases `stack.pointer`, so it corrupts the
+  in-flight traversal's stack regardless.
+- **Fix**: write the seed relative to the claimed region —
+  `stack[stack_top] = 0; stack[stack_top + 1] = this.__node_count_leaf - 1;` — and
+  advance/restore `stack.pointer` around the sort the way the query functions do
+  (`stack.pointer = stackPointer` on entry, `stack.pointer = stack_top` on exit).
+- **Confidence**: Likely (the index mismatch is unambiguous; the reachability depends on
+  a nested call, which the file's own "mostly untested" note does not exclude).
+
+---
+
+### GEOM2-12 `vector_normalize` produces NaN for a zero vector while its 2D twin returns zero
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/vec/vector_normalize.js:19-23`
+- **Defect**: `const magnitude_inv = 1 / Math.sqrt(magnitude2);` with no zero check.
+  Every sibling normalise in the package guards: `vec2/v2_array_normalize.js:24`
+  (`length_sqr !== 0 ? 1/sqrt(...) : 1`), `Vector2.normalize():621`,
+  `Vector3.normalize():560`. The N-dimensional one is the odd one out, and its spec
+  (`vec/vector_normalize.spec.js`) does not cover the case.
+- **Failure scenario**: `const r = [0,0,0]; vector_normalize(r, [0,0,0], 3);`
+  Produced: `r === [NaN, NaN, NaN]`.
+  Expected (per the behaviour of every twin in this package): `[0, 0, 0]` — the result is
+  left unscaled rather than poisoned. A NaN written into a solver's basis vector then
+  propagates silently through every subsequent dot product.
+- **Fix**: `const magnitude_inv = magnitude2 !== 0 ? 1 / Math.sqrt(magnitude2) : 1;`
+  (exactly the form `v2_array_normalize` already uses).
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-13 `Vector2`/`Vector3`/`Quaternion` shadow the typed-array `length` property with a `length()` method
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/Vector2.js:605-607`
+  (same shape at `Vector3.js:543` and `Quaternion.js`)
+- **Defect**: these classes `extend Float64Array` and also define a prototype method named
+  `length`. `Vector2.prototype.length` sits between the instance and
+  `%TypedArray%.prototype`'s `length` getter, so `instance.length` resolves to the
+  **function**, not the element count. The class doc at `Vector2.js:25` claims instances
+  are "usable directly as typed-array views"; that claim does not hold for any generic
+  consumer that reads `.length`. The `normalize()` comment at lines 614-618 documents that
+  V8 sometimes resolves `this.length` to the number instead — i.e. the property is not
+  merely wrong, it is *inconsistently* wrong depending on JIT state, which is why
+  `normalize()` had to be rewritten to call `v2_length` directly.
+- **Failure scenario**: `const v = new Vector2(3, 4);`
+  - `typeof v.length` → `"function"` (expected `"number"`, value `2`).
+  - `Array.prototype.slice.call(v)` → `[]` (`ToLength(function) === 0`);
+    expected `[3, 4]`.
+  - `Array.prototype.indexOf.call(v, 3)` → `-1`; expected `0`.
+  (Internal typed-array methods and `Array.from(v)` still work, because they use the
+  internal `[[ArrayLength]]` slot / the iterator rather than the property.)
+- **Fix**: rename the method (`magnitude()`), keeping `length()` as a deprecated alias
+  on a differently-named prototype slot is not possible — the name is the problem. If the
+  method name must be preserved for compatibility, stop extending `Float64Array` and hold
+  the buffer as a field instead.
+- **Confidence**: Confirmed (executed).
+
+---
+
+### GEOM2-14 `AABB2.computeArea()` on the canonical empty box returns `+Infinity`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/geom/2d/aabb/AABB2.js:392-399, 405-415, 360-386, 675-677`
+- **Defect**: `setNegativelyInfiniteBounds()` is the package's "empty box" representation
+  (`x0=y0=+∞, x1=y1=−∞`) and is used as an accumulator seed in ~15 call sites. None of the
+  size/cost accessors handle it: `aabb2_area(∞,∞,−∞,−∞)` computes
+  `(−∞ − ∞) * (−∞ − ∞) = (−∞)·(−∞) = +∞`.
+- **Failure scenario**: `const b = new AABB2(); b.setNegativelyInfiniteBounds();`
+  - `b.computeArea()` → `Infinity`; expected `0` (an empty box encloses nothing).
+  - `b.computeSurfaceArea()` → `-Infinity`; expected `0`.
+  - `b.costForInclusion(new AABB2(0,0,1,1))` → `-Infinity`; expected a finite
+    non-negative growth cost. A BVH/packing insertion loop ranking candidates by
+    `costForInclusion` will always pick a not-yet-initialised (empty) node, because
+    `-Infinity` beats every real candidate.
+  This is reachable whenever an accumulator loop turns out to be empty — e.g.
+  `entity_node_compute_bounding_box.js:37` or `View.js:505` seed an `AABB2` this way and
+  then only `_expandToFit` inside a loop over children.
+- **Fix**: give the three accessors an emptiness early-out — `if (this.x1 < this.x0 ||
+  this.y1 < this.y0) return 0;` in `computeArea`/`computeSurfaceArea`, and make
+  `_costForInclusion` fall back to the area of the *other* box when `this` is empty.
+  Note `_costForInclusion` also drops the second-order term of the true area growth
+  (`x*dy + y*dx`, missing `x*y`), so `AABB2(0,0,1,1).costForInclusion(AABB2(2,2,3,3))`
+  returns `4` where the actual area increase is `8`; worth deciding whether the function
+  is meant to be an exact growth or a first-order heuristic, and documenting it.
+- **Confidence**: Confirmed (executed).