@woosh/meep-engine 2.163.11 → 2.165.0

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

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

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

@@ -0,0 +1,322 @@
+# Probe directional transfer — analysis & research (v2)
+
+**Problem (Alex):** the probe pathing connects a source on a pillar cap to a listener at the base because a
+visible probe chain runs up the side — but physically that leak should be ~0. More generally: **sound
+travels straight unless something reflects it; a *directional change* at a probe is only physical if a
+reflector is near that probe.** A scalar (distance-only) edge can't express that. The fix is to bake a
+**bidirectional, source-agnostic medium transfer** `T(ω_in, ω_out)` into the probes and gate the path with
+it. A colleague (Gemini) proposed a 4×4 SH transfer matrix.
+
+> **v1 of this note was wrong** and is superseded. It proposed a *unidirectional departure-direction gate*
+> and cited Raghuvanshi/Project Acoustics. Both are wrong here: a single lobe can't express "this in→out
+> turn needs a reflector" (it fails Alex's one-probe-above-the-pillar case — visibility passes, endpoint
+> lobes pass, but the *turn through* the probe must be 0), and the parametric per-(source,listener) encoding
+> is **source-bound** (static sources, dense grid, ~100 MB, hours) — unusable when sources move. The model
+> below is bidirectional and source-agnostic.
+
+---
+
+## 1. Current encoding (carried from v1)
+
+Per probe (`AcousticProbeField`, `STRIDE = 15`): position (3) · per-band RT60 (3) · per-band **arrival**
+direction (9, L1 FOA, reverb-decoder only). Plus the **visibility graph** (`CSRGraph`: mutual-LoS edges,
+weight = distance). The leak gain is `occlusion · attenuation(routed_distance) · (1−transmission)` — the
+edge transfer is **scalar distance**. Nothing knows a bend needs a reflector.
+
+---
+
+## 2. The model: Acoustic Radiance Transfer, relocated onto air probes
+
+The published prior art for a **source-agnostic, bidirectional medium operator** is **Acoustic Radiance
+Transfer** (Siltanen, Lokki, Kiminki, Savioja — *The room acoustic rendering equation*, JASA 2007), the
+acoustic analog of the rendering equation. Its medium operator is `R = V · ρ · g`: a binary visibility `V`,
+a 6-D acoustic **BRDF** `ρ` that owns the in→out directional behavior, and a geometry/delay term `g`. **`ρ`
+depends on surface + medium only — never on source or listener.** The source only sets the initial energy
+vector; a moving listener is a few-ms *final gather*. Antani et al. (*Direct-to-Indirect Acoustic Radiance
+Transfer*, TVCG 2011; *Compact Acoustic Transfer Operators*, TOG 2012) push this into the **moving
+source + listener** regime explicitly, decoupling the transfer operator from source position. ART discretizes
+direction into **solid-angle bins** (e.g. 30°×30° = 36 bins), *not* SH.
+
+**The relocation + the key collapse.** Put the scattering vertices on the **air probes** instead of surface
+patches, and use the **visibility graph edges as the discrete directions**. Then the only directions that
+ever matter at a probe are its incident edges — so the full operator `T(ω_in, ω_out)` **collapses to one
+scalar per ordered `(in-edge, out-edge)` pair per band**:
+
+```
+turn[v][in][out][band]  =  −10·log10( max( forward(in,out),  maxₗ ρ_band · reflect_lobeₗ(in,out) ) )
+```
+
+That scalar is a **turn cost** on the graph. A directional change `in→out` that no local reflector supports
+gets `T≈0` → cost `+∞` → *forbidden*. This is exactly the **road-routing-with-turn-costs** formalism
+(Geisberger & Vetter), so routing stays a near-Dijkstra graph search — **no directional distribution is ever
+propagated at runtime.** Source-/listener-agnostic by construction (the turn table is pure medium); moving
+emitters attach to their nearest visible probe exactly as today.
+
+---
+
+## 3. Representation: structured forward + reflector lobes — **not** an SH matrix
+
+Reject the dense SH×SH transfer matrix, on quantitative grounds. The "forward/passthrough" term is a sharp
+delta (`ω_out ≈ ω_in`); a low-order SH reproducing kernel is broad, so a *free-space* probe would let sound
+turn:
+
+| SH order L | forward-kernel half-width | matrix size (floats/band/probe) |
+|---|---|---|
+| 1 (the 4×4 proposal) | **70.5°** | 16 |
+| 4 | 25.8° | 625 |
+| 8 (≈±15° bend) | 14.2° | **6561** |
+
+So you'd need L≈8 (6561 floats/band) *and* SH still **rings negative** (non-physical oscillating transfer),
+and chaining probes is a ringing matrix multiply. Wrong tool for a delta.
+
+Instead, the **canonical** per-probe bake form is structured and sharp by construction:
+- **Forward term** — 0 stored params. Analytic specular passthrough (`out` aligned with `in`); implied at
+  every probe.
+- **Reflector lobes — SGs in HALF-VECTOR space** (the form that makes reciprocity automatic). SG kernel
+  `G(c;λ)=e^{λ(c−1)}` on a cosine `c` (non-negative, no ringing; products/integrals closed-form — the
+  "convolution" you get *analytically*). The recovery, per band, for in/out **propagation** directions:
+
+  ```
+  ĥ = normalize(ω_out − ω_in)
+  f(ω_in,ω_out) = min( 1,  max( Φ(ω_in·ω_out),                       // forward / passthrough plateau
+                                max_L ρ_L[band] · G( ĥ·n_L ; λ_L ) ) )  // best reflection lobe
+  ```
+  **`max` (not sum), clamped to ≤1** so straight-through is always full regardless of nearby reflectors and
+  a probe can never amplify; it also makes the `ĥ`-undefined point at `ω_out≈ω_in` a non-issue (`max` takes
+  `Φ=1` there).
+
+  **Straight-through invariant (load-bearing).** `Φ(ω_in·ω_out)→1` as `ω_in·ω_out→1`, so the turn cost
+  `−10·log10 f → 0`: a probe does NOT impede a straight pass (a straight corridor pays distance + air only —
+  the model stays a strict superset of today). But `Φ` must be a **PLATEAU** (≈1 up to the graph's typical
+  edge-to-edge angle `θ_graph`, then fall off), **not a sharp Gaussian** — because a straight corridor sampled
+  by a *jittered* probe graph has consecutive edges that zigzag by ~`θ_graph`, and a sharp forward term would
+  bleed loss at *every* hop (e.g. 15° at `λ_fwd=5` ≈ −1.3 dB/hop → ~−5 dB over a 10-hop straight run — spurious
+  attenuation of a lossless corridor). `θ_graph` is a **discretization** parameter (probe spacing/jitter), not
+  physics; only a *real* bend (beyond the plateau, which must then be carried by a reflector lobe or it dies)
+  costs anything. Test from day one: a straight corridor's per-hop turn cost is 0 with no accumulation over
+  length.
+
+  **NOTE — `θ_graph` is a single global magic constant today, and that's the weak point.** The implementation
+  uses one `FORWARD_PLATEAU_COS = cos 40°` + `FORWARD_FALLOFF = 4` for ALL probes — a hand-tuned stand-in for
+  `θ_graph` (picked above a Delaunay-ish graph's incidental per-hop zigzag ~15–25°, below a real corner ~90°;
+  `FALLOFF=4` chosen so a 90° open-air bend → `Φ≈0.05`). It is **not measured**, so it's only right at the
+  density it was tuned at — and the SDF cover is *adaptive* (sparse halls, dense detail), so the true `θ_graph`
+  varies across one scene.
+  - **Improvement (A) — bake the plateau PER PROBE (deferred; accuracy + de-magic only).** Derive each probe's
+    aperture + falloff from its own local graph geometry (e.g. the straightest incident through-pair's turn
+    angle, with margin), so the plateau tracks local density instead of one compromise constant. Two floats/
+    probe; trivial next to the lobes. Low priority: it only fires at the two endpoint probes until interior
+    turns are gated (Phase 0b is what makes a per-hop plateau matter along the corridor). Goal is purely to
+    drive out the magic constant and improve accuracy — NOT to change behaviour.
+  - **Rejected (B) — a per-probe ABSOLUTE forward axis/cone for "aperture directivity."** Pinning a probe's
+    forward to a single world direction is wrong: a probe samples a propagation VOLUME, not a surface, and it
+    has no privileged axis. And the forward term gates the BEND (in·out), not absolute direction, so it cannot
+    express aperture directivity regardless — the graph routes a *smooth* corridor that diffuses an opening's
+    off-axis spread across many sub-plateau hops, each locally straight, so no per-hop bend gate (any plateau,
+    per-probe or not) can catch it. If aperture/source directivity is ever wanted it belongs in a separate
+    mechanism, never the forward term.
+
+  Stored per lobe: the reflector's air-side normal `n` (the SG **axis**, 3f), sharpness `λ` (1f; sharp=flat
+  mirror, broad=rough/curved), per-band reflectivity `ρ[3]` (3f) = **7 floats/lobe**. `λ_fwd` is a global
+  constant. A **sum of K** SGs approximates any non-negative transfer.
+  - **Reciprocity is BUILT IN.** Under `(ω_in,ω_out)→(−ω_out,−ω_in)`: `ω_in·ω_out` is invariant, and the
+    half-vector `ĥ` is invariant (`normalize(−ω_in+ω_out)=ĥ`). So `f(ω_in,ω_out)=f(−ω_out,−ω_in)` for any
+    lobes — no symmetrization pass. (This replaces the earlier non-reciprocal `SG(reflect(p_in),p_out)`.)
+  - **Front-face gate is FREE.** `ĥ·n` can reach `+1` only when `ω_in·n<0` (the in-ray enters the front
+    face) — `ĥ=+n ⇒ ω_out=ω_in+c·n, c>0` has no unit solution unless `ω_in·n<0`. So the lobe cannot fire for
+    a ray hitting the *back* of a surface; no separate reachability gate is needed. Pillar: cap below
+    (`n=+Y`), bad turn `up→down` has `ĥ=−Y`, `ĥ·n=−1`→0 (refused); a dome above (`n=−Y`) gives `ĥ·n=+1`
+    (admitted) — the sign flips with the normal. Numerical edge: weight lobes by the bend `(1−ω_in·ω_out)/2`
+    so the `ĥ`-undefined forward region is the forward term's alone.
+
+**Messy / curved / concave geometry** (a sphere-capped pillar, a dome above the probe — §6). A curved
+reflector *spreads* (a convex sphere is a fish-eye mirror → a broad lobe, not a spike), and a concave pocket
+between two surfaces is a *multi-bounce cavity*. So (a) the bake must trace the **local multi-bounce within
+`r`**, not just first-bounce, to get the true transfer; and (b) that transfer is multi-lobe/smeared →
+represent it as a **sum of K SGs**, *or* — since memory is cheap on a sparse field — non-parametrically as a
+**discretized solid-angle bin table** per probe (≈36×36 in/out bins, ART's actual choice; robust, no
+lobe-fitting failure modes). SGs are the *compression* of the bin table for clean scenes, not the foundation.
+
+The **materialized** form on the graph is the scalar `turn[v][in][out][band]` table for the **interior**
+turns only (graph-edge pairs are fixed → precompute), parallel to the CSR half-edge arrays
+(`turn_addresses[v]` row offsets, a `d²·3` float block per probe; ~192 floats/probe at degree 8 — trivial).
+**The two ENDPOINT turns are NOT precomputable** — the source→its-probe and listener→its-probe attachment
+legs are *runtime* directions (the emitters move), so those two probes' transfer (SG mixture / bin table)
+**must survive to runtime** and be evaluated against the attachment-leg directions. That's two `T`
+evaluations per source (tiny), and the directions are already in hand (`#applyPath` uses source→first-hop for
+directivity and exit→listener for spatialization). [Correction: my earlier "never evaluate the transfer at
+runtime" was wrong — it holds for interior turns, not the endpoints; the one-probe case in §6 is what forces
+this.]
+
+---
+
+## 4. Bake (reuse the existing ray machinery)
+
+`bakeReverbBands` already shoots a per-probe Fibonacci ray sphere, and `acoustic_trace_energy` already does
+`closestHit` + mirror-`reflect` off the surface normal. Add a **reflector harvest** in the same loop:
+
+1. Per probe, the first-bounce `closestHit` (already paid) bounded to a **probe-local radius `r`** (e.g.
+   `k·minSpacing`, or from `signedDistanceAt` clearance) — this radius *is* the "reflector is near the probe"
+   gate that makes a bend local.
+2. For clean (flat) reflectors, cluster hits by normal into patches → one SG lobe each (`μ`=normal, `λ` from
+   angular spread, `ρ[3]` from per-band `1−absorption`). For curved/concave geometry, **continue the trace a
+   few bounces within `r`** (the energy trace already reflects off `HIT.normal`) and accumulate the escaping
+   `(p_in, p_out, energy)` distribution into the probe's transfer (SG-fit or bin table) — this is what
+   captures a sphere's spread and a cavity's multi-bounce that first-bounce-only misses.
+3. **Materialize the turn table** (interior turns): for each probe, over each ordered pair of incident graph
+   edges `(ω_in, ω_out)`, evaluate `T = f(ω_in, ω_out)` (the §3 form — `min(1, max(forward plateau, best
+   reflection lobe at ĥ·n))`) per band → `−10·log10`. A straight edge pair gives `T=1` → turn cost 0.
+   Reciprocity is automatic (the half-vector is swap-invariant), so no symmetrize pass is needed. (Endpoint
+   turns stay as the runtime-evaluable transfer — §3.)
+
+Same rays, same seed, offline, deterministic. The visibility graph is already baked *before* reverb in
+`bakeProbeField`, so the incident-edge set per probe is known at materialize time. Ship the turn table via
+the existing `AcousticProbeFieldSerializationAdapter` (the lobe list is a transient bake artifact, not
+shipped).
+
+---
+
+## 5. Propagation: turn-augmented (edge-based) Dijkstra
+
+`computeExitField` today runs one scalar Dijkstra (`csr_graph_build_distance_field`) from the listener.
+Extend the search state from `node` to `(node, incoming-edge)`; when relaxing edge `k` out of `u` reached via
+incoming local edge `in`, the tentative cost is `dist[u] + edge_weight[k] (distance, dB) + turn[u][in][k][band]`;
+`+∞` turns never relax. Geisberger & Vetter report edge-based query time **"almost the same"** as node-based;
+the state space widens ~degree (~8×) but most turns prune to `+∞`, so live states are far fewer. The
+`dist/next/exit` arrays widen per-`(node,in-edge)` but `#applyPath`'s polyline walk is unchanged in shape.
+
+- **Moving sources + listeners: unchanged.** Listener snaps via `nearestVisibleIndex` and seeds one
+  exit-field pass/frame; each source snaps and reads `dist/next/exit` by index. **Reciprocity** (`T` symmetric,
+  medium at rest) keeps the solve listener-rooted as it is now.
+- **Option A (recommended):** in-node turn-table relaxation (smallest blast radius). **Option B:** materialize
+  the line graph at bake and run the *unmodified* Dijkstra (zero algorithm change, heavier bake).
+- **Band:** drive routing on one representative band (mid, or min-over-bands = most conservative) to keep the
+  per-frame pass flat; the per-band turn costs then tilt the leak send like `pathAirLoss` already does.
+- **Endpoint turns are evaluated at RUNTIME** (not from the interior table): the source→first-hop bend (at
+  the source's probe) and last-hop→listener bend (at the listener's probe) use the runtime attachment-leg
+  directions, evaluated against those two probes' retained transfer (SG mixture / bin table). In the
+  degenerate ONE-probe case both endpoints are the *same* probe and the whole route is that single bend (§6).
+
+---
+
+## 6. The three cases (all correct, source-agnostically)
+
+- **Pillar / ONE probe above the cap — the canonical test (it forced the two corrections above).** Source on
+  the cap `(0,10,0)`, listener set back at the base `(10,0,0)`, the lone probe at `(0,12,0)`; both can see the
+  probe, direct is occluded. Both endpoints snap to the *same* probe, so the route is two attachment legs and
+  a single bend *at the probe*: energy arrives travelling **up** (source→probe) and must leave **down**
+  (probe→listener). `forward(up,down)=0` (opposite). The only nearby reflector is the cap **below** the probe
+  (normal `+Y`); with the **reachability gate** it acts only on energy heading toward it (down) → it supports
+  `down→up`, never `up→down`. Nothing is above the probe (open sky) → `T(up,down)=0` → bend refused, *even
+  though both see the probe*. This case forces: **(1)** the gate fires at the **endpoint** probe on the
+  **runtime attachment-leg** directions (there is no interior graph edge here), and **(2)** the **reachability
+  gate** is essential — without it `reflect(up,+Y)=down` would pass the leak.
+- **Sphere-capped pillar + a sphere/dome ABOVE the probe (concave).** Now a reflector *exists* above → the
+  `up→down` turn becomes physical and the model **admits a faint leak** (correct — a dome bounces a little
+  back down; a cutoff-plane or normal-gate would wrongly hard-refuse). The convex spheres reflect
+  *divergently* (broad lobes) and the pocket between them is a multi-bounce cavity, so the *magnitude* needs
+  the **multi-bounce-within-`r` bake + a multi-lobe (SG-mixture or bin) transfer** (§3–§4); first-bounce + one
+  specular lobe under-energizes it but is correct in sign. This is the case that says "don't assume forward +
+  one clean specular lobe — trace the true local transfer."
+- **Two boxes sandwiching a probe.** Two reflector faces → two lobes + forward. Straight-through passes
+  (forward); a bend off either box passes (its lobe); an out-edge into the **open gap** between them hits
+  neither → `+∞`.
+- **Open door, listener at the back.** Open-air detour probes where the route must *bend* have no reflector →
+  forward-only → those bends are `+∞` → the search rejects the open-air detour and routes through the doorway.
+  (Reflection alone *rejects* the impossible route; *admitting* the doorway bend with correct attenuation
+  needs diffraction lobes — §8 Phase 4.)
+
+---
+
+## 7. Cost & reuse
+- **Storage:** `degree²·3` f32/probe → ~192 floats (~768 B) at degree 8; trivial. No compression needed.
+- **Runtime:** one per-frame exit-field pass, edge-based (≤~8× worst-case states, typically far less);
+  per-source `#applyPath` unchanged. Same order as today's single Dijkstra.
+- **Bake:** one extra first-bounce clustering pass (the `closestHit` is already paid) + a `degree²` SG
+  materialize per probe (offline, cheap).
+- **Reuses:** `acoustic_trace_energy` (closestHit + reflect), `bakeReverbBands` (ray sphere + the
+  `DIRECTION_ACCUM` reciprocity logic seeds/validates lobe axes), `AcousticOccluderIndex.closestHit/signedDistanceAt`,
+  `bakeVisibility`/`CSRGraph` (turn table parallel to the half-edge arrays; float edge weights are already
+  first-class), `computeExitField`/`csr_graph_build_distance_field` (extend state), `AcousticSimulator.apply`
+  (the `nearestVisibleIndex` snap + exit-field split is exactly the moving-emitter model). Almost no new
+  infrastructure.
+
+---
+
+## 8. Phased plan
+- **Phase 0 — zero the pillar with the correct (bidirectional, medium) model.** Bake per-probe reflector
+  lobes (forward + 0..N mirror lobes from `closestHit` within radius `r`) — the §3 half-vector form makes
+  the front-face / refuse-wrong-side behavior intrinsic (`ĥ·n` only fires for a real bounce; no separate
+  reachability gate). Single band, binary-ish gate (scalar band-mean), no SG amplitudes yet. **Strict superset
+  of today** (no reflector lobes anywhere = current behavior).
+  - **Phase 0a — DONE.** The locked transfer (`acoustic_probe_transfer.js` + 8 specs), the bake/harvest
+    (`bakeProbeReflectors.js` + specs), CSR lobe storage on `AcousticProbeField` (`setLobes`/`probeTransfer`/
+    `hasTransfer`), `bakeProbeField` step 4 wiring, and **the two ENDPOINT-bend gates evaluated at runtime** in
+    `AcousticSimulator.#applyPath` (`#turnGain`: source→sourceProbe→firstHop and lastHop→listenerProbe→listener,
+    gated by the source-/listener-probe lobes, `hasTransfer`-guarded). The endpoint eval is what carries the
+    lone-probe pillar — there is no interior edge there, so an interior-only turn table would NOT zero it.
+    Integration spec (`acoustic_transfer_pathing.spec.js`): source-on-cap + listener-at-base ⇒ leak refused
+    (1.0 → 0.0017); a dome lobe above the probe ⇒ leak admitted but attenuated (→ 0.41); no lobes ⇒ unchanged.
+  - **Phase 0b — TODO.** Materialize a binary admissible/forbidden INTERIOR turn per `(in,out)` on the graph
+    and extend `computeExitField` relaxation to state `(node, in-edge)` (edge-based Dijkstra), so a bend at an
+    intermediate probe is gated too (not only the endpoints). Spec: a vertical-corner interior leak unchanged;
+    a straight jittered corridor accrues no per-hop loss.
+- **Phase 1 — graded transfer.** Replace the binary gate with per-band `turn = −10·log10(T)` from SG lobe
+  amplitudes; fold into the dB edge metric so distance+turn shortest path = max-energy route. Specs: two-box
+  (open gaps forbidden), open-door (open-air bend rejected, doorway route survives).
+- **Phase 2 — reciprocity + render.** Symmetrize the turn table at bake (+ a reciprocity spec); wire the
+  per-band turn cost into the leak-send tilt alongside `pathAirLoss`.
+- **Phase 3 — k-best + ASG.** Eppstein top-2..4 routes, energy-summed (the "slightly-occluded straight vs
+  clean single bounce" case); anisotropic SG lobes for long walls/edges.
+- **Phase 4 — diffraction (optional but needed to fully *admit* doorways).** Diffraction lobes at
+  aperture/corner probes (UTD / BEDRF `D(φ_in,φ_out,n)`, per band) so a doorway bend is *admitted* with
+  correct attenuation, not only *rejected* if it's the wrong route.
+
+---
+
+## 9. Open questions
+- Edge-based Dijkstra: in-node turn-table relaxation (**A**) vs materialized line graph (**B**).
+- Routing band: mid / min-over-bands / per-band (3× the pass).
+- Probe-local reflector radius `r` (tie to `minSpacing` vs `signedDistanceAt`) — scene sweep.
+- Lobe clustering thresholds (one flat wall → one lobe, not many).
+- Forward-delta **aliasing** when two out-edges straddle the in-direction on a coarse graph (ART's SH-smooth
+  fallback is the escape hatch).
+- **Transfer representation default:** SG-mixture (compact; clean scenes) vs discretized solid-angle **bin
+  table** (robust to curved/concave geometry; no lobe-fitting; memory cheap on a sparse field). Lean to the
+  bin table as the default and treat SGs as a clean-scene compression — confirm on a messy scene.
+- **Bake bounce depth within `r`:** first-bounce (cheap, under-energizes concave cavities) vs few-bounce
+  (captures the sphere-cap/dome cavity, more bake cost) — how many bounces before the energy threshold, and
+  whether to gate it on local concavity (only trace deeper where `signedDistanceAt` shows an enclosing pocket).
+- Diffraction (Phase 4) is what *admits* the doorway bend; until then v1 only *rejects* the impossible route.
+- Dynamic geometry: the existing `ProbeVisibilityRecheck` disables edge weights; a turn that flips when a door
+  opens needs the turn table rechecked too.
+
+## 10. Risks
+- Edge-based state widening (~degree×) could regress the per-frame pass — re-run the `computeExitField`
+  benchmark (10k nodes, degree 8) with turns on; note most turns prune.
+- First-bounce-only harvest may miss/over-detect reflectors — `r` + clustering are the sensitive knobs.
+- Forward-delta aliasing on a coarse graph could starve straight-through energy.
+- Per-band routing 3× cost if done naively — pick one gate band up front.
+- Reciprocity assumes a medium at rest (breaks under wind/moving volumes — document the precondition).
+- **Diffraction deferral:** until Phase 4 the open-door case *rejects* the open-air detour but does not yet
+  *admit* the doorway with correct attenuation — call this out so it isn't mistaken for a finished door model.
+- Serialization: bake-vs-load turn-block size assertion (degree mismatch would corrupt addressing; asserts
+  are free in prod).
+
+## 11. Sources
+- Siltanen, Lokki, Kiminki, Savioja — *The room acoustic rendering equation* (JASA 122(3):1624–1635, 2007) — https://pubs.aip.org/asa/jasa/article-abstract/122/3/1624/852994 (open PDF: https://aaltodoc.aalto.fi/items/e19246eb-3f21-4d63-89d2-a8fb9f49eea4)
+- Antani, Chandak, Taylor, Manocha — *Direct-to-Indirect Acoustic Radiance Transfer* (IEEE TVCG 18(2), 2011) — https://pubmed.ncbi.nlm.nih.gov/21519103/ (project: http://gamma.cs.unc.edu/Sound/diffuse/)
+- Antani, Chandak, Savioja, Manocha — *Interactive Sound Propagation Using Compact Acoustic Transfer Operators* (ACM TOG 31(1):7, 2012) — https://dl.acm.org/doi/10.1145/2077341.2077348
+- Geisberger, Vetter — *Efficient Routing in Road Networks with Turn Costs* (edge-based contraction hierarchies) — https://ae.iti.kit.edu/download/turn_ch.pdf
+- Eppstein — *Finding the k Shortest Paths* (SIAM J. Comput. 1998) — https://ics.uci.edu/~eppstein/pubs/Epp-SJC-98.pdf
+- *BEDRF: Bidirectional Edge Diffraction Response Function* (diffraction lobes, 2023) — https://arxiv.org/abs/2306.01974
+- MJP — *Spherical Gaussians (SG series)* — https://therealmjp.github.io/posts/sg-series-part-5-approximating-radiance-and-irradiance-with-sgs/
+- (graphics analogs) Radiance Cascades / DDGI directional visibility / light-field probes — directional-radiance-with-distance and depth-gated leakage.
+
+---
+
+### One-line verdict
+Don't bake a per-probe SH transfer **matrix**; bake a per-probe **reflector-lobe set**, materialize it to a
+scalar **`(in-edge,out-edge)` turn cost** on the visibility graph, and route with **turn-augmented Dijkstra**.
+It's Acoustic Radiance Transfer collapsed onto the sparse probe graph — bidirectional, source-agnostic,
+moving-emitter-friendly, and ~today's runtime cost.