@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,250 +1,250 @@
-# Acoustic probe placement — coverage + sparseness, connectivity-aware
-
-## The problem with the current placer
-
-`bakeProbeField` places probes on a **blind uniform lattice** (`x0 + (x1−x0)·ix/(nx−1)`, …). Three failures:
-
-1. **Probes land inside walls / solid.** A probe inside geometry traces a sealed cavity → garbage RT60; the
-   grid has no air test. (`bakeReverbBands` of an open-air point bakes all-zero bands; of an interior point,
-   nonsense.)
-2. **Density is uniform — wrong everywhere.** A big open hall is over-sampled (hundreds of near-identical
-   reverb probes) while a thin twisted corridor is under-sampled or skipped (a probe only every `maxSpacing`,
-   regardless of whether sound can route through).
-3. **No coverage/connectivity guarantee.** Whether two rooms end up connected in `bakeVisibility` is an
-   accident of where the lattice happens to drop probes relative to a doorway.
-
-We want the opposite: **few probes in open volume, more where geometry is detailed, and *guaranteed* probe
-chains through every real acoustic path** (doorways, bent corridors) so `bakeVisibility`'s straight-line LoS
-can route. Good **coverage** (every listener-reachable point has a near probe) **and sparseness** (no wasted
-probes in big empty space) — adaptive to the geometry.
-
-## The reference technique (what to draw from)
-
-From the WebGPU GI engine (`H:/git/meep-renderer-deferred-algo/src/webgpu/v2/global_illumination/`):
-
-- **`lpv/placement/software/lpv_generate_probe_locations2.js` — the SDF maximal-empty-sphere greedy cover.**
-  This is the sparse placement we want. Build a signed distance field on a voxel grid; take the free voxels
-  (`SDF > halfVoxel`); sort by openness (SDF) **descending**; greedily, take the most-open remaining voxel,
-  gradient-ascend it to the local SDF maximum (`sdf_find_local_maxima.js` — the most-open sub-voxel point),
-  place a probe, set its radius = `SDF + moveDistance + ½voxel`, and **erase every voxel within that radius**
-  from the candidate set. Repeat. Result: probes at the centres of maximal empty spheres, **density adapting
-  to local feature size for free** — one big-radius probe fills a hall, many small-radius probes line a
-  corridor.
-- **`brick4/cpu/brick4_optimize_probe_placement.js` + `lpv/placement/chunk_refine_probe_placement.js` — the
-  validity refine.** Single-probe repositioning: push a probe that's behind/at a surface out along the normal
-  to a safe standoff, box-clamped, with a raycast tunnel-check and an inside-geometry reject. This is how they
-  keep probes off/out of geometry.
-- **`brick4/cpu/brick4_generate_tree_from_scene.js` — adaptive octree + probe reuse.** Subdivide a cell only
-  where it overlaps geometry (`query_aabb_intersection_exists`), down to a feature-size floor, under a memory
-  budget; dedup probes by quantised position (shared cell-boundary probes cost nothing). An *alternative*
-  adaptive scheme — but it's tuned for GPU trilinear-interpolation bricks (4×4×4, 27-way), not a navigation
-  graph, so we take the **ideas** (geometry-driven density, dedup, budget) not the structure.
-
-**The decisive gap:** *none of the reference placement reasons about probe-to-probe visibility.* The "refine"
-step is purely single-probe surface standoff. Connectivity through a twisted corridor is NOT a placement
-concern there — it's handled (if at all) by a later visibility bake. **So the connectivity-refinement stage
-the user asked for (ray bounces between probes) is novel work, not a port.**
-
-## What meep already has vs. what's missing
-
-| Need | Status | meep path |
-|---|---|---|
-| Signed distance from a point to a shape | ✅ closed-form (sphere/box/capsule/cyl/hull), O(tris) mesh | `core/geom/3d/shape/AbstractShape3D.js::signed_distance_at_point` (+ `signed_distance_gradient_at_point`, `nearest_point_on_surface`) |
-| SDF gradient by finite difference | ✅ | `core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js` |
-| Voxelize a shape to a grid | ✅ | `core/geom/3d/shape/util/shape3_voxelize_to_grid.js` |
-| Trilinear sample a 3-channel grid | ✅ | `engine/graphics/texture/3d/scs3d_sample_linear3.js` |
-| lerp / clamp / seededRandom / randomFloatBetween | ✅ | `core/math/…` |
-| **Point → nearest-surface distance / inside-test on the acoustic scene** | ❌ **ray-only** | `engine/sound/simulation/core/AcousticOccluderIndex.js` exposes only `closestHit`/`anyHit`/`addBody`. Bodies (`OccluderBody{shape,matrix,inverse,worldAABB,material}`) carry `signed_distance_at_point`, but no point query is wired up. |
-| Poisson-disk / blue-noise point sampler | ❌ | substitute: Halton / jittered grid (`tetrahedral_mesh_build_from_grid` pattern) |
-| Existing acoustic-aware placement | ❌ | meep LPV baker (`engine/graphics/sh3/lpv/build_probes_for_scene.js`) is a blind uniform grid too |
-
-**Keystone primitive to add (Stage 0):** `AcousticOccluderIndex.signedDistanceAt(x, y, z) → number` — negative
-inside solid, positive in air, magnitude = distance to the nearest occluder surface. It already owns a BVH over
-body world-AABBs (the TLAS from the reflection-IR work); descend it by AABB distance to find candidate bodies,
-localize the point through each body's `inverse`, take `min` of `shape.signed_distance_at_point`. This single
-query unlocks everything below: the SDF cover, the air test (`> 0`), surface clearance, and the local-maxima
-nudge (gradient via central differences of the same query). It is the acoustic analogue of the GI engine's
-`StaticSceneBVH.query_point_distance_to_nearest`.
-
-## Acoustic constraints that change the design
-
-1. **Air only.** Probes must sit where a listener/source can be. The SDF cover gives this intrinsically (free
-   voxels are `SDF > 0`), but the floor and the inside-test must use the *signed* distance.
-2. **Coverage = listener-reachable volume, not surface density.** Unlike GI (which densifies *at* surfaces),
-   we want probes in the *open volume between* surfaces — exactly what the maximal-empty-sphere cover does.
-   (Optional later refinement: restrict to a floor-relative band / navmesh volume so we don't probe
-   unreachable voids — deferred, a placement-policy question.)
-3. **Connectivity is a hard requirement, not a nicety.** `bakeVisibility` connects only probes with **straight
-   LoS** (`probe_edge_visible` = one `anyHit` ray). A bent corridor must be populated densely enough that
-   consecutive probes see each other. The cover handles gentle bends; sharp bends / thin throats need the
-   dedicated connectivity stage (below).
-4. **Determinism** (seeded `random`), and the result is **serialized positions-only** — connectivity is always
-   re-baked, so placement just has to produce a good, final position set.
-
-## Staged design
-
-```
-Stage 0  signedDistanceAt(x,y,z)            NEW primitive on AcousticOccluderIndex (BVH + per-body SDF)
-Stage 1  sparse SDF cover                   port of lpv_generate_probe_locations2 → candidate probe positions
-Stage 2  air-validity + clearance refine    keep probes in air, off surfaces (port of the refine gauntlet)
-Stage 3  CONNECTIVITY refinement            <-- the user's "ray bounces": guarantee LoS chains through paths
-Stage 4  integrate                          feed final positions → bakeReverbBands → bakeVisibility
-```
-
-### Stage 0 — `signedDistanceAt` (the keystone primitive)
-
-`AcousticOccluderIndex.signedDistanceAt(x,y,z)`: BVH-descend body AABBs nearest-first (reuse the
-`bvh_query_user_data_*` machinery already there), for each candidate body localize the point (`body.inverse`)
-and evaluate `body.shape.signed_distance_at_point`, keep the signed value of smallest magnitude. Sign convention
-= negative inside. Add a sibling `clearance(x,y,z) = max(0, signedDistanceAt)` for the cover, and reuse
-`compute_signed_distance_gradient_by_sampling`-style central differences over it for the local-maxima nudge.
-(Mesh occluders are O(tris) per query — flag the same way meep's `MeshShape3D` does; for big meshes a
-surface-triangle BVH is the eventual accelerator, but primitives/convex hulls are closed-form and cheap.)
-
-### Stage 1 — sparse SDF cover (`probe_place_sdf_cover.js`, new)
-
-Direct port of `lpv_generate_probe_locations2`, acoustic-flavoured:
-1. Voxel grid over `bounds` at resolution `≈ extent / frequency` (the new density knob, replacing
-   `maxSpacing`), capped (e.g. 256³) to bound memory.
-2. Fill the SDF via `signedDistanceAt` per voxel (or `shape3_voxelize_to_grid` + a distance pass — decide by
-   cost; the per-voxel SDF is simplest and exact).
-3. Candidate voxels = `SDF > clearanceFloor` (in open air, off the walls). Sort by SDF descending.
-4. Greedy cover: take the most-open voxel, gradient-ascend to the local SDF maximum, emit a probe, radius =
-   `SDF + moveDist + ½voxel`, erase covered voxels. Repeat until none remain.
-
-Output: a sparse, adaptive position set — sparse in halls, dense in detail, **all in air**.
-
-### Stage 2 — air-validity + clearance refine
-
-The cover already yields `SDF > floor` probes, so most are valid. Belt-and-suspenders, per probe: if
-`signedDistanceAt < clearanceMin`, push out along the SDF gradient to the clearance standoff (the reference's
-`refine_probe_placement`), and drop any probe that can't reach air (a fully-enclosed void). This is cheap and
-guarantees the air invariant `bakeReverbBands` relies on.
-
-### Stage 3 — connectivity refinement (the keystone NEW stage)
-
-**Goal:** for every pair of regions a real acoustic path connects, guarantee a chain of mutually-visible probes
-spans it — so `bakeVisibility` (straight-LoS Delaunay + bridge) actually links them. The cover can leave two
-gaps: (a) a corridor thinner than `clearanceFloor` gets *no* candidate voxels → no probes; (b) a sharp bend
-where two cover probes are close but **occluded** by the corner.
-
-**Detection.** Run a *provisional* `bakeVisibility` on the Stage-2 probes, then look for **near-but-unconnected**
-probe pairs: pairs within a corridor-scale radius (a few × the local probe spacing) that are in **different
-graph components** (or whose graph distance ≫ their Euclidean distance) yet are **not** straight-visible. Each
-such pair brackets a bend/throat that needs an intermediate probe.
-
-**Repair — "ray bounces between probes."** For an unconnected near pair `(A, B)`:
-1. Cast `A → B`; it hits a wall at `H` (the bend/corner). The open path bends around `H`.
-2. Find an **open waypoint** `W` past the corner: search the air around `H` (slide along the SDF ridge — the
-   medial axis where clearance is locally maximal — toward `B`, or sample directions off `H.normal`) for a
-   point that is visible from `A`. Insert a probe at the local SDF maximum near `W`.
-3. Recurse on `(A, W)` and `(W, B)` until each segment is straight-visible or a depth/budget cap is hit.
-
-This populates exactly the bends and throats the cover missed, with the *minimum* probes needed for a visible
-chain — it's a visibility-guided binary subdivision along the medial axis, seeded by the ray-hit corner. After
-insertion, re-bake visibility (the final `bakeVisibility` pass). Bound it: only refine pairs within a max
-corridor radius and cap inserted probes per pair, so a genuinely sealed wall (no open detour) is left
-disconnected (correct — `bakeVisibility` Stage B already leaves sealed vaults split).
-
-> Note the synergy with `bakeVisibility` Stage B (island bridging): Stage B adds an **edge** when a visible
-> cross-component probe pair already exists; Stage 3 here adds the **probes** when none exists in the connecting
-> region. Together they guarantee connectivity wherever an acoustic path physically exists.
-
-### Stage 4 — integration
-
-`bakeProbeField` becomes: `Stage 0–3 → final positions → existing per-probe bakeReverbBands loop → bakeVisibility`.
-The `AcousticProbeField` write API is unchanged (`setProbePosition` append, `setProbeReverbDecay/Directions`); only the
-*source* of positions changes from the lattice to the cover. `maxSpacing` → `frequency` (voxel/feature size);
-keep a back-compat shim or migrate callers. Serialization (positions-only) is unaffected.
-
-## Decisions to confirm before building
-
-1. **SDF source:** add `AcousticOccluderIndex.signedDistanceAt` (per-body closed-form, BVH-pruned) — vs. a
-   voxelize-then-distance-transform pass. Recommendation: the per-body query (exact, reuses existing shape SDFs,
-   no second index).
-2. **Coverage scope:** probe the *whole* air volume in `bounds`, or restrict to a floor-relative / reachable
-   band (skip unreachable voids)? Recommendation: whole air volume for v1; reachability is a separate policy
-   layer (ties into navmesh — `project_navmesh_cleanup`).
-3. **Connectivity-refinement waypoint search:** SDF-ridge (medial-axis) march vs. ray-bounce-off-corner
-   sampling for finding `W`. Recommendation: ray-to-corner to *seed*, then SDF-gradient slide to the local
-   max — cheapest that's robust.
-4. **Density knob + caps:** `frequency` (voxel size), `clearanceFloor`, max probes, connectivity max-corridor
-   radius + per-pair insert budget. All bake-time constants with JSDoc rationale.
-
-## Test plan
-
-- `signedDistanceAt`: sign + magnitude against a box/sphere occluder (inside negative, outside positive, exact
-  distance); gradient points outward.
-- SDF cover: a hall + a corridor scene → few large-radius probes in the hall, a chain of small-radius probes
-  in the corridor; **every** probe has `signedDistanceAt > 0` (in air); no probe inside a wall.
-- Connectivity: an **L-bend / S-bend corridor** where the cover leaves the two ends unconnected → after Stage 3
-  the ends are one component and `findAcousticPath` returns a route that stays in air; a **sealed** variant
-  stays disconnected (no false bridge).
-- Sparseness: a big empty room yields far fewer probes than the old uniform grid at the same `frequency`
-  (assert ratio); coverage: `nearestIndex` for sampled listener points is always within ~probe radius.
-- Determinism: same seed → identical positions.
-
-## As-built (landed)
-
-All four stages shipped; `bakeProbeField(index, minSpacing, rayCount, random, options)` now runs
-**SDF grid → portal discovery → cover (portals pre-seeded) → connectivity refinement → reverb** instead of the
-blind grid. The bake REGION is derived from the scene — the occluder hull
-(`AcousticOccluderIndex.computeWorldBounds`) inflated by `2 × minSpacing` on every side — not a caller
-parameter; a caller wanting a hand-picked region drops to `build_sdf_grid` + `probe_place_sdf_cover` directly.
-
-- **Stage 0** `AcousticOccluderIndex.signedDistanceAt(x,y,z,maxDistance)` — union SDF via the body-AABB BVH +
-  per-body `shape.signed_distance_at_point` (negative inside, clamped to `+maxDistance`).
-- **Grid** `build_sdf_grid(index, bounds, minSpacing, sparsenessRatio)` (`probe_sdf_grid.js`) — the SDF voxel
-  grid (oversampled 2× below `minSpacing`, capped 256³) is built ONCE and shared by the cover and (implicitly,
-  via the same `signedDistanceAt`) portal detection, so the expensive up-to-256³ SDF sweep is paid once. The
-  trilinear sampler, gradient-ascent local-max, and claim-sphere helpers live here too.
-- **Stage 1** `probe_place_sdf_cover(grid, {predefined})` — SDF maximal-empty-sphere greedy cover. Erase radius
-  `clamp(clearance, minSpacing, minSpacing·sparsenessRatio)`: the initial cover never packs closer than the
-  hint, halls sparser up to the ceiling (`sparsenessRatio`, default 4). `predefined` probes (the portal
-  throats) are emitted FIRST and carve their empty spheres, so the cover never drops a redundant probe on one,
-  and they lead the probe list (indices `[0, K)`).
-- **Stage 2** (air-validity) is folded into Stage 1: candidates are `SDF > ½voxel`, so the cover never emits a
-  probe inside (or hugging) a solid — no separate pushout pass needed.
-- **Stage 3** `probe_refine_connectivity(index, field, minSpacing, {maxRefineFactor, corridorReachFactor})` —
-  for each pair of nearby components, a **bounded greedy best-first walk through open air** inserts waypoints
-  until a chain of mutually-visible probes spans the gap; floored at `minSpacing/maxRefineFactor` (default 4).
-  **Decision changed from the plan:** the midpoint-SDF-ascend sketched in §Stage 3 was rejected — it fails on
-  baffle/divider geometry where the gap is *perpendicular* to the SDF gradient. The directed open-air search
-  (sample around the segment, keep points visible from the current side, step to the nearest-to-target) handles
-  it. The provisional/final `bakeVisibility` re-bakes between rounds (default ≤3).
-- **Portals** (`probe_detect_portals.js` + `probe_densify_portals.js`, `detectPortals` default on) — fixes
-  *symmetry*, not connectivity. A provisional cover discovers the openings (door frames / windows / arches),
-  then the bake re-covers with their throats pre-seeded:
-  - **Detect** — over every nearby MUTUALLY-VISIBLE probe pair (BVH gather within `maxSpacing`, NOT just baked
-    edges, so an opening is found regardless of where the sparse cover dropped edges), keep the ones whose line
-    threads a CONSTRICTION (narrowest point, by the *exact* `signedDistanceAt` — the cover grid is far too
-    coarse to resolve a doorway) **that is a genuine APERTURE** — bounded by solid on opposing sides
-    perpendicular to the passage (a doorway's jambs). The aperture gate is the real selectivity (it rejected a
-    one-sided pillar graze and the open region boundary; on the demo house: 77 raw constrictions → the 2 real
-    openings); dedup to one throat per opening (widest crossing).
-  - **Carve** — the throats feed `probe_place_sdf_cover` `predefined` (Stage 1), so a probe sits IN each opening.
-  - **Densify** — `bakeVisibility` stage D fans extra cross-opening CHORDS around each portal: the mutually-
-    visible pairs among its nearest neighbours whose line passes PAST the throat (point-to-segment bias). A fan
-    of chords gives Dijkstra direct, mirror-symmetric routes through the opening instead of funnelling every
-    cross-door path through the one off-centre probe the cover happened to place (which gave a listener on the
-    left and one on the right very different routed lengths). Purely a bake-time concept — adds only edges; no
-    runtime object, nothing serialized.
-- **`minSpacing` semantics (per owner):** the hint sizes the initial cover/fit; only connectivity refinement
-  may go finer (down to `minSpacing/maxRefineFactor`). Open regions are *sparser* than the hint (up to the
-  ceiling) — the cover's adaptive sparseness.
-- **The grid jitter** added to the old `bakeProbeField` is now moot (no grid) and was removed in the rewrite;
-  the cover's gradient-ascended points are already general-position for the Delaunay base.
-
-Knobs (all in `options`, JSDoc'd): `sparsenessRatio`, `maxRefineFactor`, `corridorReachFactor`,
-`maxRefineRounds`, `detectPortals` (default true), `constrictionFactor`, `portalFloorRatio`. Tests:
-`core/signedDistanceAt.spec.js`, `probe/probe_place_sdf_cover.spec.js`, `probe/probe_refine_connectivity.spec.js`,
-`probe/probe_detect_portals.spec.js`, `probe/probe_densify_portals.spec.js`, the end-to-end
-`probe/bakeProbeField_pipeline.spec.js` (divider-with-gap → air-only, connected over the top, reverb tails), and
-`probe/bakeProbeField_portals.spec.js` (a doorway → a centred portal + mirror-symmetric routing).
-
-## Out of scope (follow-ups)
-
-- Floor-relative / navmesh-restricted coverage policy.
-- Surface-triangle BVH to make mesh `signedDistanceAt` sub-linear (only matters for high-poly occluders).
-- Probe-reuse/dedup across separately-baked regions (brick4-style), if we ever stream/tile the bake.
-- Perf at scale: the SDF voxel build is O(res³ · nearby-bodies); a bench + the grid fast-path are unmeasured.
+# Acoustic probe placement — coverage + sparseness, connectivity-aware
+
+## The problem with the current placer
+
+`bakeProbeField` places probes on a **blind uniform lattice** (`x0 + (x1−x0)·ix/(nx−1)`, …). Three failures:
+
+1. **Probes land inside walls / solid.** A probe inside geometry traces a sealed cavity → garbage RT60; the
+   grid has no air test. (`bakeReverbBands` of an open-air point bakes all-zero bands; of an interior point,
+   nonsense.)
+2. **Density is uniform — wrong everywhere.** A big open hall is over-sampled (hundreds of near-identical
+   reverb probes) while a thin twisted corridor is under-sampled or skipped (a probe only every `maxSpacing`,
+   regardless of whether sound can route through).
+3. **No coverage/connectivity guarantee.** Whether two rooms end up connected in `bakeVisibility` is an
+   accident of where the lattice happens to drop probes relative to a doorway.
+
+We want the opposite: **few probes in open volume, more where geometry is detailed, and *guaranteed* probe
+chains through every real acoustic path** (doorways, bent corridors) so `bakeVisibility`'s straight-line LoS
+can route. Good **coverage** (every listener-reachable point has a near probe) **and sparseness** (no wasted
+probes in big empty space) — adaptive to the geometry.
+
+## The reference technique (what to draw from)
+
+From the WebGPU GI engine (`H:/git/meep-renderer-deferred-algo/src/webgpu/v2/global_illumination/`):
+
+- **`lpv/placement/software/lpv_generate_probe_locations2.js` — the SDF maximal-empty-sphere greedy cover.**
+  This is the sparse placement we want. Build a signed distance field on a voxel grid; take the free voxels
+  (`SDF > halfVoxel`); sort by openness (SDF) **descending**; greedily, take the most-open remaining voxel,
+  gradient-ascend it to the local SDF maximum (`sdf_find_local_maxima.js` — the most-open sub-voxel point),
+  place a probe, set its radius = `SDF + moveDistance + ½voxel`, and **erase every voxel within that radius**
+  from the candidate set. Repeat. Result: probes at the centres of maximal empty spheres, **density adapting
+  to local feature size for free** — one big-radius probe fills a hall, many small-radius probes line a
+  corridor.
+- **`brick4/cpu/brick4_optimize_probe_placement.js` + `lpv/placement/chunk_refine_probe_placement.js` — the
+  validity refine.** Single-probe repositioning: push a probe that's behind/at a surface out along the normal
+  to a safe standoff, box-clamped, with a raycast tunnel-check and an inside-geometry reject. This is how they
+  keep probes off/out of geometry.
+- **`brick4/cpu/brick4_generate_tree_from_scene.js` — adaptive octree + probe reuse.** Subdivide a cell only
+  where it overlaps geometry (`query_aabb_intersection_exists`), down to a feature-size floor, under a memory
+  budget; dedup probes by quantised position (shared cell-boundary probes cost nothing). An *alternative*
+  adaptive scheme — but it's tuned for GPU trilinear-interpolation bricks (4×4×4, 27-way), not a navigation
+  graph, so we take the **ideas** (geometry-driven density, dedup, budget) not the structure.
+
+**The decisive gap:** *none of the reference placement reasons about probe-to-probe visibility.* The "refine"
+step is purely single-probe surface standoff. Connectivity through a twisted corridor is NOT a placement
+concern there — it's handled (if at all) by a later visibility bake. **So the connectivity-refinement stage
+the user asked for (ray bounces between probes) is novel work, not a port.**
+
+## What meep already has vs. what's missing
+
+| Need | Status | meep path |
+|---|---|---|
+| Signed distance from a point to a shape | ✅ closed-form (sphere/box/capsule/cyl/hull), O(tris) mesh | `core/geom/3d/shape/AbstractShape3D.js::signed_distance_at_point` (+ `signed_distance_gradient_at_point`, `nearest_point_on_surface`) |
+| SDF gradient by finite difference | ✅ | `core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js` |
+| Voxelize a shape to a grid | ✅ | `core/geom/3d/shape/util/shape3_voxelize_to_grid.js` |
+| Trilinear sample a 3-channel grid | ✅ | `engine/graphics/texture/3d/scs3d_sample_linear3.js` |
+| lerp / clamp / seededRandom / randomFloatBetween | ✅ | `core/math/…` |
+| **Point → nearest-surface distance / inside-test on the acoustic scene** | ❌ **ray-only** | `engine/sound/simulation/core/AcousticOccluderIndex.js` exposes only `closestHit`/`anyHit`/`addBody`. Bodies (`OccluderBody{shape,matrix,inverse,worldAABB,material}`) carry `signed_distance_at_point`, but no point query is wired up. |
+| Poisson-disk / blue-noise point sampler | ❌ | substitute: Halton / jittered grid (`tetrahedral_mesh_build_from_grid` pattern) |
+| Existing acoustic-aware placement | ❌ | meep LPV baker (`engine/graphics/sh3/lpv/build_probes_for_scene.js`) is a blind uniform grid too |
+
+**Keystone primitive to add (Stage 0):** `AcousticOccluderIndex.signedDistanceAt(x, y, z) → number` — negative
+inside solid, positive in air, magnitude = distance to the nearest occluder surface. It already owns a BVH over
+body world-AABBs (the TLAS from the reflection-IR work); descend it by AABB distance to find candidate bodies,
+localize the point through each body's `inverse`, take `min` of `shape.signed_distance_at_point`. This single
+query unlocks everything below: the SDF cover, the air test (`> 0`), surface clearance, and the local-maxima
+nudge (gradient via central differences of the same query). It is the acoustic analogue of the GI engine's
+`StaticSceneBVH.query_point_distance_to_nearest`.
+
+## Acoustic constraints that change the design
+
+1. **Air only.** Probes must sit where a listener/source can be. The SDF cover gives this intrinsically (free
+   voxels are `SDF > 0`), but the floor and the inside-test must use the *signed* distance.
+2. **Coverage = listener-reachable volume, not surface density.** Unlike GI (which densifies *at* surfaces),
+   we want probes in the *open volume between* surfaces — exactly what the maximal-empty-sphere cover does.
+   (Optional later refinement: restrict to a floor-relative band / navmesh volume so we don't probe
+   unreachable voids — deferred, a placement-policy question.)
+3. **Connectivity is a hard requirement, not a nicety.** `bakeVisibility` connects only probes with **straight
+   LoS** (`probe_edge_visible` = one `anyHit` ray). A bent corridor must be populated densely enough that
+   consecutive probes see each other. The cover handles gentle bends; sharp bends / thin throats need the
+   dedicated connectivity stage (below).
+4. **Determinism** (seeded `random`), and the result is **serialized positions-only** — connectivity is always
+   re-baked, so placement just has to produce a good, final position set.
+
+## Staged design
+
+```
+Stage 0  signedDistanceAt(x,y,z)            NEW primitive on AcousticOccluderIndex (BVH + per-body SDF)
+Stage 1  sparse SDF cover                   port of lpv_generate_probe_locations2 → candidate probe positions
+Stage 2  air-validity + clearance refine    keep probes in air, off surfaces (port of the refine gauntlet)
+Stage 3  CONNECTIVITY refinement            <-- the user's "ray bounces": guarantee LoS chains through paths
+Stage 4  integrate                          feed final positions → bakeReverbBands → bakeVisibility
+```
+
+### Stage 0 — `signedDistanceAt` (the keystone primitive)
+
+`AcousticOccluderIndex.signedDistanceAt(x,y,z)`: BVH-descend body AABBs nearest-first (reuse the
+`bvh_query_user_data_*` machinery already there), for each candidate body localize the point (`body.inverse`)
+and evaluate `body.shape.signed_distance_at_point`, keep the signed value of smallest magnitude. Sign convention
+= negative inside. Add a sibling `clearance(x,y,z) = max(0, signedDistanceAt)` for the cover, and reuse
+`compute_signed_distance_gradient_by_sampling`-style central differences over it for the local-maxima nudge.
+(Mesh occluders are O(tris) per query — flag the same way meep's `MeshShape3D` does; for big meshes a
+surface-triangle BVH is the eventual accelerator, but primitives/convex hulls are closed-form and cheap.)
+
+### Stage 1 — sparse SDF cover (`probe_place_sdf_cover.js`, new)
+
+Direct port of `lpv_generate_probe_locations2`, acoustic-flavoured:
+1. Voxel grid over `bounds` at resolution `≈ extent / frequency` (the new density knob, replacing
+   `maxSpacing`), capped (e.g. 256³) to bound memory.
+2. Fill the SDF via `signedDistanceAt` per voxel (or `shape3_voxelize_to_grid` + a distance pass — decide by
+   cost; the per-voxel SDF is simplest and exact).
+3. Candidate voxels = `SDF > clearanceFloor` (in open air, off the walls). Sort by SDF descending.
+4. Greedy cover: take the most-open voxel, gradient-ascend to the local SDF maximum, emit a probe, radius =
+   `SDF + moveDist + ½voxel`, erase covered voxels. Repeat until none remain.
+
+Output: a sparse, adaptive position set — sparse in halls, dense in detail, **all in air**.
+
+### Stage 2 — air-validity + clearance refine
+
+The cover already yields `SDF > floor` probes, so most are valid. Belt-and-suspenders, per probe: if
+`signedDistanceAt < clearanceMin`, push out along the SDF gradient to the clearance standoff (the reference's
+`refine_probe_placement`), and drop any probe that can't reach air (a fully-enclosed void). This is cheap and
+guarantees the air invariant `bakeReverbBands` relies on.
+
+### Stage 3 — connectivity refinement (the keystone NEW stage)
+
+**Goal:** for every pair of regions a real acoustic path connects, guarantee a chain of mutually-visible probes
+spans it — so `bakeVisibility` (straight-LoS Delaunay + bridge) actually links them. The cover can leave two
+gaps: (a) a corridor thinner than `clearanceFloor` gets *no* candidate voxels → no probes; (b) a sharp bend
+where two cover probes are close but **occluded** by the corner.
+
+**Detection.** Run a *provisional* `bakeVisibility` on the Stage-2 probes, then look for **near-but-unconnected**
+probe pairs: pairs within a corridor-scale radius (a few × the local probe spacing) that are in **different
+graph components** (or whose graph distance ≫ their Euclidean distance) yet are **not** straight-visible. Each
+such pair brackets a bend/throat that needs an intermediate probe.
+
+**Repair — "ray bounces between probes."** For an unconnected near pair `(A, B)`:
+1. Cast `A → B`; it hits a wall at `H` (the bend/corner). The open path bends around `H`.
+2. Find an **open waypoint** `W` past the corner: search the air around `H` (slide along the SDF ridge — the
+   medial axis where clearance is locally maximal — toward `B`, or sample directions off `H.normal`) for a
+   point that is visible from `A`. Insert a probe at the local SDF maximum near `W`.
+3. Recurse on `(A, W)` and `(W, B)` until each segment is straight-visible or a depth/budget cap is hit.
+
+This populates exactly the bends and throats the cover missed, with the *minimum* probes needed for a visible
+chain — it's a visibility-guided binary subdivision along the medial axis, seeded by the ray-hit corner. After
+insertion, re-bake visibility (the final `bakeVisibility` pass). Bound it: only refine pairs within a max
+corridor radius and cap inserted probes per pair, so a genuinely sealed wall (no open detour) is left
+disconnected (correct — `bakeVisibility` Stage B already leaves sealed vaults split).
+
+> Note the synergy with `bakeVisibility` Stage B (island bridging): Stage B adds an **edge** when a visible
+> cross-component probe pair already exists; Stage 3 here adds the **probes** when none exists in the connecting
+> region. Together they guarantee connectivity wherever an acoustic path physically exists.
+
+### Stage 4 — integration
+
+`bakeProbeField` becomes: `Stage 0–3 → final positions → existing per-probe bakeReverbBands loop → bakeVisibility`.
+The `AcousticProbeField` write API is unchanged (`setProbePosition` append, `setProbeReverbDecay/Directions`); only the
+*source* of positions changes from the lattice to the cover. `maxSpacing` → `frequency` (voxel/feature size);
+keep a back-compat shim or migrate callers. Serialization (positions-only) is unaffected.
+
+## Decisions to confirm before building
+
+1. **SDF source:** add `AcousticOccluderIndex.signedDistanceAt` (per-body closed-form, BVH-pruned) — vs. a
+   voxelize-then-distance-transform pass. Recommendation: the per-body query (exact, reuses existing shape SDFs,
+   no second index).
+2. **Coverage scope:** probe the *whole* air volume in `bounds`, or restrict to a floor-relative / reachable
+   band (skip unreachable voids)? Recommendation: whole air volume for v1; reachability is a separate policy
+   layer (ties into navmesh — `project_navmesh_cleanup`).
+3. **Connectivity-refinement waypoint search:** SDF-ridge (medial-axis) march vs. ray-bounce-off-corner
+   sampling for finding `W`. Recommendation: ray-to-corner to *seed*, then SDF-gradient slide to the local
+   max — cheapest that's robust.
+4. **Density knob + caps:** `frequency` (voxel size), `clearanceFloor`, max probes, connectivity max-corridor
+   radius + per-pair insert budget. All bake-time constants with JSDoc rationale.
+
+## Test plan
+
+- `signedDistanceAt`: sign + magnitude against a box/sphere occluder (inside negative, outside positive, exact
+  distance); gradient points outward.
+- SDF cover: a hall + a corridor scene → few large-radius probes in the hall, a chain of small-radius probes
+  in the corridor; **every** probe has `signedDistanceAt > 0` (in air); no probe inside a wall.
+- Connectivity: an **L-bend / S-bend corridor** where the cover leaves the two ends unconnected → after Stage 3
+  the ends are one component and `findAcousticPath` returns a route that stays in air; a **sealed** variant
+  stays disconnected (no false bridge).
+- Sparseness: a big empty room yields far fewer probes than the old uniform grid at the same `frequency`
+  (assert ratio); coverage: `nearestIndex` for sampled listener points is always within ~probe radius.
+- Determinism: same seed → identical positions.
+
+## As-built (landed)
+
+All four stages shipped; `bakeProbeField(index, minSpacing, rayCount, random, options)` now runs
+**SDF grid → portal discovery → cover (portals pre-seeded) → connectivity refinement → reverb** instead of the
+blind grid. The bake REGION is derived from the scene — the occluder hull
+(`AcousticOccluderIndex.computeWorldBounds`) inflated by `2 × minSpacing` on every side — not a caller
+parameter; a caller wanting a hand-picked region drops to `build_sdf_grid` + `probe_place_sdf_cover` directly.
+
+- **Stage 0** `AcousticOccluderIndex.signedDistanceAt(x,y,z,maxDistance)` — union SDF via the body-AABB BVH +
+  per-body `shape.signed_distance_at_point` (negative inside, clamped to `+maxDistance`).
+- **Grid** `build_sdf_grid(index, bounds, minSpacing, sparsenessRatio)` (`probe_sdf_grid.js`) — the SDF voxel
+  grid (oversampled 2× below `minSpacing`, capped 256³) is built ONCE and shared by the cover and (implicitly,
+  via the same `signedDistanceAt`) portal detection, so the expensive up-to-256³ SDF sweep is paid once. The
+  trilinear sampler, gradient-ascent local-max, and claim-sphere helpers live here too.
+- **Stage 1** `probe_place_sdf_cover(grid, {predefined})` — SDF maximal-empty-sphere greedy cover. Erase radius
+  `clamp(clearance, minSpacing, minSpacing·sparsenessRatio)`: the initial cover never packs closer than the
+  hint, halls sparser up to the ceiling (`sparsenessRatio`, default 4). `predefined` probes (the portal
+  throats) are emitted FIRST and carve their empty spheres, so the cover never drops a redundant probe on one,
+  and they lead the probe list (indices `[0, K)`).
+- **Stage 2** (air-validity) is folded into Stage 1: candidates are `SDF > ½voxel`, so the cover never emits a
+  probe inside (or hugging) a solid — no separate pushout pass needed.
+- **Stage 3** `probe_refine_connectivity(index, field, minSpacing, {maxRefineFactor, corridorReachFactor})` —
+  for each pair of nearby components, a **bounded greedy best-first walk through open air** inserts waypoints
+  until a chain of mutually-visible probes spans the gap; floored at `minSpacing/maxRefineFactor` (default 4).
+  **Decision changed from the plan:** the midpoint-SDF-ascend sketched in §Stage 3 was rejected — it fails on
+  baffle/divider geometry where the gap is *perpendicular* to the SDF gradient. The directed open-air search
+  (sample around the segment, keep points visible from the current side, step to the nearest-to-target) handles
+  it. The provisional/final `bakeVisibility` re-bakes between rounds (default ≤3).
+- **Portals** (`probe_detect_portals.js` + `probe_densify_portals.js`, `detectPortals` default on) — fixes
+  *symmetry*, not connectivity. A provisional cover discovers the openings (door frames / windows / arches),
+  then the bake re-covers with their throats pre-seeded:
+  - **Detect** — over every nearby MUTUALLY-VISIBLE probe pair (BVH gather within `maxSpacing`, NOT just baked
+    edges, so an opening is found regardless of where the sparse cover dropped edges), keep the ones whose line
+    threads a CONSTRICTION (narrowest point, by the *exact* `signedDistanceAt` — the cover grid is far too
+    coarse to resolve a doorway) **that is a genuine APERTURE** — bounded by solid on opposing sides
+    perpendicular to the passage (a doorway's jambs). The aperture gate is the real selectivity (it rejected a
+    one-sided pillar graze and the open region boundary; on the demo house: 77 raw constrictions → the 2 real
+    openings); dedup to one throat per opening (widest crossing).
+  - **Carve** — the throats feed `probe_place_sdf_cover` `predefined` (Stage 1), so a probe sits IN each opening.
+  - **Densify** — `bakeVisibility` stage D fans extra cross-opening CHORDS around each portal: the mutually-
+    visible pairs among its nearest neighbours whose line passes PAST the throat (point-to-segment bias). A fan
+    of chords gives Dijkstra direct, mirror-symmetric routes through the opening instead of funnelling every
+    cross-door path through the one off-centre probe the cover happened to place (which gave a listener on the
+    left and one on the right very different routed lengths). Purely a bake-time concept — adds only edges; no
+    runtime object, nothing serialized.
+- **`minSpacing` semantics (per owner):** the hint sizes the initial cover/fit; only connectivity refinement
+  may go finer (down to `minSpacing/maxRefineFactor`). Open regions are *sparser* than the hint (up to the
+  ceiling) — the cover's adaptive sparseness.
+- **The grid jitter** added to the old `bakeProbeField` is now moot (no grid) and was removed in the rewrite;
+  the cover's gradient-ascended points are already general-position for the Delaunay base.
+
+Knobs (all in `options`, JSDoc'd): `sparsenessRatio`, `maxRefineFactor`, `corridorReachFactor`,
+`maxRefineRounds`, `detectPortals` (default true), `constrictionFactor`, `portalFloorRatio`. Tests:
+`core/signedDistanceAt.spec.js`, `probe/probe_place_sdf_cover.spec.js`, `probe/probe_refine_connectivity.spec.js`,
+`probe/probe_detect_portals.spec.js`, `probe/probe_densify_portals.spec.js`, the end-to-end
+`probe/bakeProbeField_pipeline.spec.js` (divider-with-gap → air-only, connected over the top, reverb tails), and
+`probe/bakeProbeField_portals.spec.js` (a doorway → a centred portal + mirror-symmetric routing).
+
+## Out of scope (follow-ups)
+
+- Floor-relative / navmesh-restricted coverage policy.
+- Surface-triangle BVH to make mesh `signedDistanceAt` sub-linear (only matters for high-poly occluders).
+- Probe-reuse/dedup across separately-baked regions (brick4-style), if we ever stream/tile the bake.
+- Perf at scale: the SDF voxel build is O(res³ · nearby-bodies); a bench + the grid fast-path are unmeasured.