@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/sound/simulation/REFLECTION_IR_PLAN.md

@@ -1,261 +0,0 @@
-# Plan — Ray-traced reflection IR (probe-baked geometry reverb)
-
-> The keystone upgrade: replace `bakeReverb`'s single-hit mean-free-path heuristic with a true
-> ray-traced, time-binned, **per-band** reflection IR, reusing the engine's Monte-Carlo path tracer.
-> Closes the Steam-Audio *reflections* gap (early reflections + room timbre), replaces the hand-tuned
-> `DECAY_PER_METRE` constant with measured per-band RT60, and makes `scattering` / `absorption[3]` live
-> data.
->
-> **Status (2026-06-20): COMPLETE — the keystone is LANDED + committed + green.** The foundation
-> (**P1a/P1b** shape-raycast index, the **§0.5** `RowFirstTable`/`CSRGraph`/BVH data structures, the **P4
-> TLAS**) and now the reflection-IR bake itself — **P1c → P2 → P3** — are all in. `bakeReverb`'s single-hit
-> heuristic + `DECAY_PER_METRE` are gone; reverb RT60 is now *measured* per band from multi-bounce ray
-> tracing, validated against an analytic Sabine box, and rendered as a per-band decaying-noise IR.
->
-> **One deviation from this plan, for correctness:** the trace terminates by ENERGY THRESHOLD, **not**
-> Russian roulette (§1 step 5 / §4 said RR). Fixed-probability RR is the wrong estimator for acoustic
-> reflectance — a survivor at bounce *n* carries energy `(1−α)^n` but is scaled by `2^n`, so for a live
-> room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and rare deep survivors swamp exactly the
-> late bins the RT60 slope is fitted to. Deterministic decay-to-floor is unbiased for the fit window and
-> far lower variance.
-
-The structural blueprint is **`engine/graphics/sh3/lpv/LightProbeVolumeBaker.js`** + its
-`PathTracerProbeRenderer` — a near-1:1 analogue (probe-volume baking against scene geometry via the path
-tracer). We mirror its baker ↔ probe-renderer split and `TaskGroup` orchestration; we swap the
-accumulator from SH-of-radiance to **energy-over-time per band**.
-
----
-
-## 0. What is baked vs. runtime — the source-agnostic guarantee (answers the dynamic-sources question)
-
-**The bake NEVER encodes sound sources. It encodes SPACE: (a) per-region reverberation profile and
-(b) region connectivity.** Sources are 100% runtime. There is no restriction to static/fixed sources.
-
-| Concern | Baked? | What's baked | Source / geometry dynamics |
-|---|---|---|---|
-| Direct path: occlusion, transmission, air, distance | **never** — real-time ray-trace every frame against the live `AcousticOccluderIndex` | nothing | **sources AND moving occluders fully dynamic** |
-| Reverb (reflection IR / per-band RT60) | yes, per **probe** | the SPACE's reverberation response at that point (room geometry + materials), source-agnostic | **sources fully dynamic** — any source routes into the reverb selected by the **listener's** position; geometry assumed mostly-static |
-| Pathing (corner-leakage) | yes | inter-probe **visibility graph** (the space's connectivity), source-agnostic | **sources fully dynamic** — the path source↔listener is solved at runtime from live positions; geometry static-assumed (+ live recheck below) |
-
-**Why reverb is source-agnostic** — "reverb = reflections with the source at the listener." The
-late/diffuse reverberant field of a room is approximately uniform and a property of the room (volume +
-surface absorption), not of where the source is. So one **listener-centric** reverb per probe serves
-every source in that room: `ProbeReverbRenderer` already selects by the *listener's* nearest probe, and
-all sources send into that one shared reverb bus. A source can move anywhere — it never indexes the bake.
-
-**Early reflections are the one source-position-dependent part.** The per-probe envelope bakes them
-listener-centric (correct when source ≈ listener; and when the source is far, the position-independent
-late tail dominates anyway). True per-source early reflections would be a separate real-time pass —
-deferred; the direct-path occlusion machinery already does per-source real-time work, and the late tail
-is the dominant reverb cue.
-
-**Moving objects (dynamic geometry):**
-- **Occlusion / transmission — fully live.** The occluder index is dynamic (O(1) `setTransform`), so a
-  closing door / moving platform correctly blocks the *direct* path in real-time. No bake involved.
-- **Baked reverb + baked visibility — encode bake-time geometry.** A mover that changes acoustic
-  *topology* (a door sealing a room) is not in the bake. Policy, in order of cost:
-  1. Most reverb-affecting geometry is static (walls/floors); small movers barely shift RT60 → accept.
-  2. **Pathing live recheck** (cheap, from the review): re-verify the chosen exit edge with a single
-     `anyHit` ray each frame against live geometry — a closed door re-blocks the leak instantly even
-     though the baked graph still has the edge. One ray per pathed source.
-  3. **Opt-in door variants** for big dynamic dividers (vault door, portcullis gating a whole area's
-     reverb): bake open/closed variants for the affected probes and blend on door state (Steam Audio's
-     "dynamic geometry" approach) — per set-piece, not the default.
-  4. **Re-bake affected probes** on major static-set changes (level streaming) — offline, rare.
-
-This is the standard **real-time-direct / baked-indirect** split (Steam Audio's exact model): live where
-source + geometry move, baked where it is expensive and mostly-static, with targeted live rechecks for
-the dynamic cases that matter.
-
----
-
-## 0.5 Foundation data structures (owner-directed, resolved)
-
-These replace the v1 POJO/array structures across the existing + new probe code with the engine's
-binary-backed primitives.
-
-1. **ProbeField store → `RowFirstTable`** (`core/collection/table/`), **not** `BinaryElementPool`. Probes
-   are baked **write-once** and read by integer row index, so a fixed-schema columnar binary table fits
-   exactly: one allocation, cache-friendly, no per-probe JS object. (`BinaryElementPool`'s alloc/free
-   pool semantics are for churny dynamic elements — unneeded here.) Schema via `RowFirstTableSpec`:
-   `x, y, z` (f32) · `reverbDecayLow/Mid/High` (f32, widened from the v1 scalar) · `bvhLeaf` (u32). The
-   `AcousticProbe` class becomes a thin row cursor/accessor (or is dropped for row-index access).
-
-2. **Pathing connectivity → `CSRGraph`** (`core/graph/csr/`), replacing `AcousticPathGraph.#adjacency`
-   (array-of-arrays). Baked once ⇒ CSR is the ideal static-graph form — `edge_addresses` (row pointers) +
-   `adjacency` + `edge_weights` in one buffer, with the cache-friendly `for (k=xadj[v]; k<xadj[v+1]; k++)`
-   walk that `computeExitField`/Dijkstra want. `edge_weights` is **`Float32Array`** (owner-updated — its
-   doc now cites "acoustic coupling"), so path distances go in **directly**, no quantization.
-   `bakeVisibility` builds it two-pass (count degrees → prefix-sum `edge_addresses` → fill) or via
-   `CSRGraph.fromArrays`.
-
-3. **Probe nearest → BVH + `bvh_query_user_data_nearest_to_point`** (`core/bvh2/bvh3/query/`), replacing
-   `ProbeField.nearest`'s linear scan. `ProbeField` builds a `BVH` of probe point-AABBs (leaf `user_data`
-   = row index) once after baking (the `SpatialAudioIndex` precedent); `nearest(x,y,z)` = one query →
-   row index, O(log n). This matters under the bake (`bakeVisibility` is O(probes²) nearest-style work)
-   and per-frame (`computeExitField` snaps listener + every pathed source to a probe).
-
-4. **`AcousticOccluderIndex` body → class** (replacing the `#bodies` POJO): a real `OccluderBody` holding
-   `shape, material, matrix, inverse, localAABB, worldAABB` (the triangle `blas/indices/positions` of this
-   v1 sketch are gone — §0.6 below raycasts the `shape` directly, so only meshes carry an internal BLAS).
-   `matrix` (the **forward** world transform) maps the local hit position + normal back to world space.
-
-5. **`body.inverse` mandatory — no `null` polymorphism.** `addBody`'s matrix defaults to `M4_IDENTITY`
-   and the inverse is **always** computed; `#localizeRay` always transforms (drop the `inverse === null`
-   fast-path). Uniform flow per [[feedback_uniform_flow]]. Production cost is nil — real occluder bodies
-   always carry a `Transform` matrix anyway; the identity fast-path was a test-only convenience.
-
-**Landing:** (4)+(5)+the stored forward matrix = the foundation of **P1a/P1b**. (1)+(3) = part of the
-**P2** probe refactor (the probe schema widens for per-band decay there regardless). (2) = a pathing
-refactor that can ride with P2 or land standalone first.
-
----
-
-## 0.6 Raycast shapes directly — drop the triangulation (owner-directed)
-
-The v1 `acoustic_geometry_from_shape` triangulates collider shapes (box → 12 tris, …) into mesh soup —
-counter-productive: lossy for primitives, more triangles, a per-body BLAS for a 2-tri wall. **Replace it
-with a first-class `AbstractShape3D.raycast`**, so the occluder index stores **shapes** and raycasts them
-exactly (closed-form for primitives, an internal BLAS only for meshes).
-
-**Contract:** `AbstractShape3D.raycast(hit: Float32Array, ray: Ray3) → boolean`, shape at its LOCAL
-origin (the caller localises the ray), `hit = [px, py, pz, nx, ny, nz]` (local surface point + unit
-normal). The hit distance `t` is recovered by the caller as `(hitPoint − origin)·dir` (unit dir).
-
-**It is mostly glue** — the narrowphase already factored the local math into core functions that
-`refine_ray_hit` dispatches to:
-- `SphereShape3D` → `core/geom/3d/sphere/sphere_raycast.js`
-- `BoxShape3D` → `core/geom/3d/box/box3_raycast.js`
-- `CapsuleShape3D` → `core/geom/3d/capsule/capsule_raycast.js`
-- `MeshShape3D` → an **internal lazy ebvh BLAS** (`ebvh_build_for_geometry_morton` +
-  `ebvh_geometry_query_nearest_triangle_ray` + `construct_ray_hit_from_geometry`); the normal is
-  normalised and flipped to face the incoming ray. (Owner-approved: MeshShape3D gains an internal BLAS.)
-
-`AcousticOccluderIndex` then holds `shape + material + matrix + inverse` per body; `closestHit`/`anyHit`
-localise the world ray into body space and call `shape.raycast`, transforming the hit point (by the
-forward matrix) and normal (by the rotation) back to world. **`acoustic_geometry_from_shape` is deleted**;
-`AcousticBody`/`AcousticSimulationSystem` pass the `Collider.shape` straight through. (Could later let
-the physics `refine_ray_concave` share `MeshShape3D.raycast` — out of scope.)
-
----
-
-## 1. Model — acoustic ray-tracing energy histogram
-
-From a probe (source = listener), shoot N rays over the sphere. Each ray carries a **per-band energy
-throughput** `[low, mid, high]`, init `1`. Bounce loop (modeled on `PathTracer.path_trace`):
-
-1. `index.closestHit` → `t`, world hit position + **normal** (P1a).
-2. `pathLength += t`; deposit current energy into `histogram[band][bin]`, `bin = floor(pathLength / c / binSeconds)` (`c` = speed of sound).
-3. fold absorption: `energy[band] *= (1 − material.absorption[band])`.
-4. scatter: with prob `material.scattering` → diffuse (`getBiasedNormalSample`, cosine lobe about the normal); else specular (reflect direction about the normal).
-5. `shiftForward(SELF_OCCLUSION_OFFSET · max(1,|origin|))`; Russian-roulette terminate (unbiased survivor scaling) after `min_bounce`.
-6. miss (escaped to open sky) → stop.
-
-Per probe: the per-band histogram (the **reflectogram**) → **per-band RT60** (decay slope, via Schroeder
-integration) + the early bins (room signature). This is the classic CATT/ODEON statistical method, and
-the same energy model Steam Audio's baked reflections use.
-
----
-
-## 2. Phases
-
-**P1 — Foundation (geometry-only tests).**
-- **✓ LANDED — P1a — `AbstractShape3D.raycast(hit, ray)`** (§0.6) on Sphere / Box / Capsule / Mesh — glue over the
-  narrowphase `*_raycast` core functions + an internal mesh BLAS. Engine-wide, generally useful, purely
-  additive to the shape classes. Test: known ray-vs-sphere/box/capsule/mesh hits (position + normal) and
-  misses, in the shape's local frame.
-- **✓ LANDED — P1b — `OccluderBody` class + occluder-index refactor to shapes** (§0.5 (4)(5), §0.6). Bodies hold
-  `shape + material + matrix + inverse` (inverse mandatory, identity default); `closestHit`/`anyHit`
-  localise the ray + `shape.raycast`, transform hit point (forward matrix) + normal (rotation) to world,
-  recover `t` for cross-body ordering; world-AABB broadphase from `shape.compute_bounding_box`. **Delete
-  `acoustic_geometry_from_shape`**; `AcousticBody`/`AcousticSimulationSystem` pass `Collider.shape`
-  through; `RayHit` gains world position + normal. Update the dependent specs (they currently feed
-  triangle soup). Test: occlusion/ray behaviour unchanged on shape colliders; hit normal correct.
-- **✓ LANDED — P1c — scatter + offset primitives**: `v3_reflect` (core, new) for the specular bounce;
-  the cosine-diffuse scatter reuses `getBiasedNormalSample` and the magnitude-scaled self-occlusion offset
-  reuses `Ray3.shiftForward` directly (both already existed — no wrappers needed). Tested: reflection law
-  (angle in = angle out, parallel-to-surface unchanged, unit-length preserved).
-
-**✓ LANDED — P2 — Bake core (no WebAudio).** `acoustic_trace_energy` (one ray's multi-bounce per-band
-deposit into a time-binned echogram — energy-threshold termination, not RR; see the deviation note up
-top) + `echogram_band_rt60` (Schroeder + ISO 3382 T30 slope) + `bakeReverbBands` (N rays → per-band
-RT60); `AcousticProbe` widened to `reverbDecay[3]` (scalar kept as the derived mean) + `ProbeField`
-table widened. **Sabine box gate passes** (baked cube RT60 ≈ 0.161·V/(S·α)). `bakeReverb` deleted.
-- `acoustic_trace_energy(index, origin, dir, …, histogram)` — one ray's multi-bounce energy deposit
-  (allocation-free, seeded).
-- `ReflectionProbeRenderer.bake(pos, probe)` — N rays → per-band histogram → per-band RT60 + early
-  envelope (mirrors `PathTracerProbeRenderer.bake`).
-- `AcousticReverbBaker.bake(probeField, ecd)` → `TaskGroup` (chunked over probes via `countTask`, like the
-  LPV baker; logs ms/probe).
-- **Widen `AcousticProbe`**: `reverbDecaySeconds` scalar → `reverbDecay[3]` (per-band) + optionally a short
-  early-reflection envelope; **keep the scalar derived from the bands** so the existing
-  `reverbImpulseResponse` / `ProbeReverbRenderer` path stays valid as a regression gate until the new path
-  is proven. Update `toJSON`/`fromJSON` + `bakeProbeField`.
-- **Validation gate — analytic Sabine box:** a closed box with known absorption has a known
-  RT60 (`0.161·V/(S·α)`); assert the baked late-slope matches within tolerance. Plus: per-band absorption
-  → per-band RT60 differs; open scene → ~no tail.
-
-**✓ LANDED — P3 — Render upgrade.**
-- `reverbImpulseResponse` shapes **per-band** decaying noise from `reverbDecay[3]` (each band's tail =
-  its RT60), summed → a geometry-derived IR with room *timbre*. `ProbeReverbRenderer` consumes the
-  widened probe. Test (`MockAudioContext`): IR band content reflects the per-band decays; crossfade still
-  click-safe.
-
-**P4 — Optional, measure-first (not the keystone).**
-- NEE-to-source (deposit `source→wall→listener` paths for a cleaner early-reflection IR at lower ray
-  count) — only if random-bounce variance is shown to be a problem.
-- **✓ LANDED — Body-level TLAS** over `AcousticOccluderIndex` — a dynamic BVH over the bodies' world AABBs,
-  gather via `bvh_query_user_data_ray_segment` (leaf user-data = handle, `BvhClient` refit on
-  `setTransform`). Landed early on owner request rather than waiting on the bake bench; `closestHit` /
-  `anyHit` are now O(log n + hits).
-
----
-
-## 3. Reuse map
-
-| Lifted **verbatim** (engine primitives) | Adapted / new (acoustic) |
-|---|---|
-| `getBiasedNormalSample` (cosine scatter), `construct_ray_hit_from_geometry` (hit normal), `random_point_on_sphere`, `Ray3.shiftForward` + scale-aware offset, the RR survivor-scaling pattern, `TaskGroup`/`countTask`, the baker ↔ probe-renderer split | the bounce loop (energy-time histogram vs radiance/SH), absorption-throughput fold, specular/diffuse split by `scattering`, Schroeder → RT60 reduction, per-band IR shaping |
-
-Keep the binary **`ebvh`** as the BLAS leaf (do not fork `BufferedGeometryBVH`'s inlined raycast). **Skip
-BVH8** (no CPU traversal kernel; lost to `ebvh` for 2-tri walls).
-
----
-
-## 4. Key decisions
-
-- **Dx — source-agnostic space bake (see §0).** The bake = per-region reverb profile + connectivity;
-  sources are fully runtime; reverb is selected by the *listener*; pathing is solved at runtime. Moving
-  geometry is live for occlusion, static-assumed for baked indirect, with a live path-edge `anyHit`
-  recheck + opt-in door variants. **No restriction to static sources, ever.**
-- **Statistical (energy-histogram) reverb**, one shared listener-centric IR per probe — affordable for
-  WebAudio; not per-source convolution.
-- **Per-band throughout** (collapsing to a scalar is the regression we are fixing).
-- **Unbiased & leak-free**: RR survivor scaling is mandatory; the scale-aware self-occlusion offset is
-  mandatory (a fixed epsilon silently leaks energy through walls at large world coords).
-- **Back-compat scalar path kept as the regression gate** until the per-band path validates against
-  Sabine — *correctness-first, no bandaid*.
-- **Skip wetness/humidity** (owner-agreed) and the wet-JCA physics.
-
----
-
-## 5. Testing
-
-Core (`core/` + `probe/`) is WebAudio-free → geometry-only tests, no audio mock. The Sabine box is the
-correctness gate for P2. The render (P3) uses `MockAudioContext`. Bench the bake ray cost before any
-TLAS. Run from the repo root: `npx jest --config jest.conf.json engine/sound/simulation`.
-
-## 6. Risks
-
-- **Probe-contract widening** (scalar → per-band) ripples through `AcousticProbe` serialization,
-  `bakeProbeField`, `reverbImpulseResponse`, `ProbeReverbRenderer` — hence P2 is the L item. Land P1
-  first (both S, self-contained), keep the scalar path behind the new curve.
-- **Bake cost** (rays × bounces × probes) is real but offline; `TaskGroup` chunking keeps it
-  non-blocking. Don't reach for the TLAS until the bench says so.
-- **Validation honesty**: trust the bake to replace `DECAY_PER_METRE` only after the Sabine-box RT60
-  matches analytics.
-
-## 7. Sequence
-
-P1a + P1b (S each, zero behavior change) → P2 (bake + Sabine gate) → P3 (render). P4 stays
-measured/optional.

package/src/engine/sound/simulation/VISIBILITY_GRAPH_PLAN.md

@@ -1,121 +0,0 @@
-# Topologically-aware probe-visibility graph
-
-## The cliff
-
-`bakeVisibility` connects every mutually-visible probe pair via an all-pairs `for i, for j<i` loop.
-With no occluders that is the **complete graph** — `n(n-1)/2` edges, O(n²) time *and* memory. A 128³ probe
-field (2,097,152 probes) would try to materialise **2.199e12 edges** → OOM. (Bench:
-`probe/bakeVisibility.bench.spec.js`.)
-
-Pruning a distance cutoff into that loop does **not** fix it — it still *enumerates* all pairs (O(n²) time),
-and the scheme is topologically blind. The fix is to never enumerate the complete graph: generate candidate
-edges from the **spatial topology** of the probe cloud, so we only ever touch O(n) of them.
-
-This is, in the literature, a **sparse geometric spanner** built like a **sparse roadmap spanner (SPARS2)**:
-a base graph + connectivity bridges + path-quality shortcuts. References that map 1:1 onto the three stages:
-SPARS/SPARS2 (Dobson & Bekris 2014 — names stage B a *"bridge"*, stage C a *"shortcut"*); the greedy
-geometric spanner (Bose et al. — stage C's length test `dist_G(u,v) > t·‖uv‖`); PRM* component-connection
-(stage B). Steam Audio, by contrast, keeps the all-pairs loop and just places **few** probes (5 m floor grid)
-— a placement lever we deliberately treat separately.
-
-## Decisions (locked)
-
-- **Base = Delaunay, no jitter.** `compute_delaunay_tetrahedral_mesh` on the probe positions. (Grid fields
-  have a clean dedicated tessellator, `tetrahedral_mesh_build_from_grid`, but wiring it by grid-structure is
-  part of the *placement* workstream — not conflated here.)
-- **Full A + B + C** in this change.
-- **Dense probe fields stay.** This is purely a graph-construction fix; placement is a separate workstream.
-- Caveat we are buying with B+C: **3D Delaunay is not a proven constant-stretch spanner** (2D is, ≤1.998;
-  3D has no such bound — Erickson, Xia). So the base graph *can* detour badly and *can* be fragmented by
-  walls; B repairs connectivity and C repairs path quality. They are mandatory, not optional.
-
-## Stage A — Delaunay base graph  (`probe_delaunay_edges.js`)
-
-1. Copy probe positions into a packed `[x,y,z]*n`; `compute_delaunay_tetrahedral_mesh(mesh, points, n)`.
-2. Extract the **unique undirected edges** of the live tets — 6 per tet (`getVertexIndex` pairs), deduped
-   (materialise the freed-tet skip set once; do **not** call `exists()` per tet — it is O(free)). The tet
-   mesh triangulates the convex hull, so this is a single connected graph of **≈6–7·n** edges.
-3. Drop edges that fail `probe_edge_visible(field, index, a, b)`; keep survivors weighted by distance.
-
-Result: a sparse, occlusion-respecting base graph. **O(n)** edges, **O(n)** shadow rays. (2.1M probes →
-~13M edges / rays vs 2.2e12 — ~150,000× fewer.) Dropping occluded edges is what fragments the graph into
-**islands** (rooms), which stage B repairs.
-
-## Stage B — bridge the islands  (`probe_visibility_bridge_components.js`)
-
-A door the Delaunay edge happened to miss leaves two acoustically-connected rooms as separate components.
-
-1. `uf_init` + `uf_union` over the surviving base edges → connected components (canonical root = min member).
-2. For each probe, **radius-query the probe BVH** (`bvh_query_user_data_intersects_sphere`, radius = k× the
-   median base-edge length) for nearby probes in a **different** component; among the **visible** ones keep
-   the **shortest** edge per unordered component-pair (the PRM/SPARS bridge heuristic).
-3. Add those bridges, re-`uf_union`, repeat until the component count stops dropping. Genuinely sealed
-   regions stay separate (correct — a closed vault should not leak).
-
-**O(n · |radius neighbours|)**, no all-pairs. Bridges are the only edges that can exceed the local Delaunay
-length, so they are also the place corner-leak pathing will most want.
-
-## Stage C — augment for path quality  (`probe_visibility_augment.js`)
-
-The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear straight
-line exists. Add a **budgeted fraction** of extra edges (cap ≤ ~30% of base) on two criteria:
-
-- **C1 length (greedy spanner).** Candidate chords `(u,v)` from the 2-ring (a shared base neighbour `w`) and
-  short BVH-radius pairs. Add iff `(u,v)` is visible **and** `dist_G(u,v) > t·‖uv‖` — the current graph route
-  is ≥ t× the straight line. `dist_G` is evaluated with a **distance-bounded Dijkstra capped at `t·‖uv‖`**
-  (reuse the heap Dijkstra; stop early once the cap is exceeded), so it is cheap, not a full SSSP per pair.
-- **C2 directionality (diffraction-angle gate).** For a 2-ring kink `u–w–v`, with `d0 = ̂(u−w)`, `d1 = ̂(v−w)`,
-  add the chord iff visible **and** `dot(d0, −d1) < X` — the angle at `w` is acute, a sharp corner the sound
-  must wrap around. Acoustically a bend is a diffraction point whose HF loss grows with angle (UTD/Maekawa),
-  so straightening it is worth an edge even when it barely shortens the route. This is an acoustic heuristic,
-  **not** a spanner property — hence the budget cap, so it composes with C1 rather than overrunning it.
-
-**O(n · degree²)** candidates from the 2-ring; each gated test is local/bounded. Process shortest-first,
-stop at the budget.
-
-## Assembly — `bakeVisibility` rewrite
-
-`A (delaunay edges → visible) → B (bridge) → C (augment) → CSRGraph (both half-edges) → field.setVisibilityGraph`.
-The CSR build, the `EDGE_WEIGHT_BLOCKED` runtime recheck, and `findAcousticPath` are unchanged downstream —
-this only changes which edges exist, not their representation. Weights remain inter-probe distance so the
-recheck restores them identically.
-
-## New primitives that may be needed
-
-- Tet → unique-edge extraction with an O(tets) freed-skip (helper in `probe_delaunay_edges.js`).
-- A median base-edge-length helper to set the stage-B radius and the stage-C candidate radius.
-- (If 2-ring proves insufficient at scale) WSPD candidate pairs — deferred unless measured to be needed.
-
-## Test plan
-
-- `probe_delaunay_edges.spec.js`: a small grid tetrahedralises to the expected adjacency; coincident/degenerate
-  inputs; edge uniqueness.
-- `bakeVisibility.spec.js` (extend): empty scene is now **sparse** (≈O(n), assert ≪ n²) yet still **connected**
-  (one component) and every kept edge is visible; a wall fragments then B re-bridges through a gap; the
-  existing two-rooms-corridor integration test still passes (reachability + direction + per-band).
-- Re-point `bakeVisibility.bench.spec.js`: the complete-graph assertion becomes a **sparsity + connectivity**
-  assertion; the 128³ case should now *complete* (sweep added to confirm ~linear edges/time).
-- Stage C: a deliberate kink (L-shaped corridor with a clear diagonal) gains the shortcut; budget cap honoured.
-
-## Open knobs (defaults to pick during implementation, document in code)
-
-- stage-B radius multiplier `k` (× median edge length); stage-C stretch `t`; stage-C angle `X`; stage-C budget
-  fraction. All bake-time constants with JSDoc rationale (per the project's no-magic / uniform-flow style).
-
-## As-built notes (landed)
-
-- **Defaults chosen:** stage-B radius `2.5×` median edge length; stage-C stretch `1.3`, kink `dot < −0.5`
-  (~corners <60°), budget `0.2×` base edges.
-- **Coplanar degeneracy is handled, not avoided:** a valid 3D Delaunay 1-skeleton is connected, so
-  `probe_delaunay_edges` checks connectivity and falls back to the complete graph when the extraction is
-  disconnected (a near-coplanar/degenerate field — e.g. the y=0 test scenes). Dense 3D fields never hit it.
-- **Stage B is boundary-driven:** it searches only from the endpoints of dropped (occluded) edges (`sources`),
-  not all `n` probes — an interior probe with all-visible neighbours can't be a missed-door near side. An
-  empty scene drops nothing, so stage B is a no-op (measured: 10 s → 20 ms at 13.8k probes).
-- **Spatial sort:** `probe_delaunay_edges` Morton-sorts the points before the incremental tetrahedralisation
-  (the core's own TODO) and maps tet vertices back through the permutation. ~25% off the build.
-- **Result:** edges are O(n) (measured 6.7–8.0 per probe across 8³–32³, always 1 component); the old all-pairs
-  O(n²)/OOM is gone. The 128³ case no longer OOMs and completes.
-- **Remaining bottleneck = the core incremental Delaunay BUILD** (~98% of bake time, super-linear). Follow-ups
-  (out of scope here): wire `tetrahedral_mesh_build_from_grid` for grid fields (O(n) — the placement
-  workstream), and/or speed up core's Delaunay (BRIO/spatial-sort insertion is its standing TODO).