@woosh/meep-engine 2.163.10 → 2.164.0

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

@@ -0,0 +1,277 @@
+# Acoustic Simulation
+
+Geometry-driven acoustics for meep — occlusion, transmission, propagation medium, geometry-derived
+reverb, and pathing — that **feeds the [sopra](../sopra/README.md) sound engine**. This layer is the
+meep equivalent of what Steam Audio is to FMOD/Wwise: it *simulates* how sound interacts with the world,
+and sopra *renders* the result through WebAudio.
+
+> One rule above all: **this layer computes, sopra renders.** `simulation/core`, `simulation/ecs`, and
+> `simulation/probe` import **no WebAudio**. They turn scene geometry into an `AcousticSolution` (a few
+> numbers per source) and baked data (reverb probes, a visibility graph). Only the thin `simulation/render`
+> folder and the `EventInstance.setAcoustic` seam touch WebAudio. Because of that the whole simulation is
+> unit-testable on bare geometry with no audio mock.
+
+---
+
+## The idea: simulator vs. renderer
+
+```
+  SIMULATION (this folder — geometry, JS, no WebAudio)            RENDER (sopra — WebAudio)
+  ─────────────────────────────────────────────────────          ─────────────────────────
+  AcousticBody   (occluder shapes + material) ─┐
+  AcousticVolume (medium regions)              ├─► AcousticSolution ─► EventInstance.setAcoustic()
+  ray queries (BVH over shapes) + fibonacci ───┘    {occlusion,           (gain + lowpass + transmission)
+                                                     transmission[3],
+  AcousticProbeField (baked per-band reverb) ──────────────► medium,      ─► ProbeReverbRenderer (convolver)
+   + probe-visibility graph (pathing) ─────────────►  exit, path} ─► exit-point send (EventInstance)
+```
+
+WebAudio is a **renderer, not a simulator** — it has no geometry/ray/scene API. So every acoustic
+feature is "compute a factor / IR / path against meep geometry, then drive native nodes with it." The
+render primitives (`GainNode`, `BiquadFilterNode`, `ConvolverNode`) already exist; this layer supplies
+their *inputs*.
+
+A source **opts in** with one flag (`AudioEmitter.acoustic = true`). Medium and occlusion are properties
+of the **world** (`AcousticVolume` / `AcousticBody` components), never of the event.
+
+---
+
+## Directory map
+
+```
+simulation/
+  AcousticSimulator.js          the engine: owns the occluder index + medium regions + solvers; solveFor / apply
+  configureAcousticSimulation.js one-call ECS wiring (build the simulator, add the systems, inject the emitter)
+  definition/                   authored value types (serializable)
+    AcousticMaterial.js           3-band absorption / scattering / transmission of a surface
+    AcousticDirectivity.js        source radiation pattern (monopole→dipole) — how a source "points" its sound
+  core/                         ECS-agnostic AND WebAudio-agnostic — the testable heart
+    AcousticOccluderIndex.js      dynamic ray index — a TLAS BVH over OccluderBody shapes (exact shape.raycast)
+    OccluderBody.js               one occluder: shape + material + world transform (+ cached inverse / AABB)
+    RayHit.js                     reusable closest-hit result (caller-allocated): point + normal + t + material
+    OcclusionSolver.js            volumetric occlusion + transmission for one source (temporally smoothed)
+    VolumeField.js                blends AcousticVolume regions into a medium at a point + integrates air
+                                  absorption along the source→listener path (distance-dependent, per band)
+    AcousticVolumeRegion.js       a shape + medium + transition band (boundary blend)
+    AcousticMedium.js             propagation medium (air absorption per band, dB/metre)
+    AcousticSolution.js           the per-source result the render seam consumes
+    AcousticSourceState.js        transient per-source temporal accumulation (pool-backed cursor)
+  ecs/                          thin ECS binding (real-component tested)
+    AcousticBody.js / AcousticSimulationSystem.js     occluders (pair with Collider + Transform)
+    AcousticVolume.js / AcousticVolumeSystem.js       medium regions (pair with Transform)
+  probe/                        the baked substrate (offline; no WebAudio)
+    bakeProbeField.js             place a grid of probes (density knob) and bake each
+    AcousticProbeField.js                 the baked probe volume — flat Float32Array storage (per-band RT60 +
+                                  per-band arrival direction) + BVH nearest-probe lookup + visibility graph
+    acoustic_trace_energy.js      one ray's multi-bounce per-band energy deposit into a time-binned echogram,
+                                  + the energy-weighted launch direction (FOA arrival vector) per band
+    echogram_band_rt60.js         reduce one band's echogram to RT60 (Schroeder + ISO-3382 T30 slope)
+    bakeReverbBands.js            N rays → echogram → per-band RT60 + per-band arrival direction for a probe
+    bakeVisibility.js             connect probes by line-of-sight into the field's graph + findAcousticPath
+    probe_edge_visible.js         the one shadow-ray edge test shared by the bake and the runtime recheck
+    ProbeFieldPathingSolution.js  per-frame, per-listener exit-field solve (public dist/next/exit buffers)
+    ProbeVisibilityRecheck.js     budgeted dynamic-geometry recheck — disables/restores edges vs live geometry
+  serialization/                binary save/load adapters (registered via populateAcousticSerializationRegistry)
+  render/                       the ONLY WebAudio code in this layer
+    ProbeReverbRenderer.js        scalar acoustic-owned reverb bus (double-buffered convolver crossfade)
+    reverbImpulseResponse.js      per-band decaying-noise IR from [low, mid, high] RT60 (band-split, seeded)
+    FoaProbeReverbRenderer.js     directional (FOA / B-format) reverb bus — rotate-the-decoder stereo decode
+    foaReverbImpulseResponse.js   per-band W,X,Y,Z B-format IR steered by the baked arrival direction
+  bench/                        perf calibration
+```
+
+The render seam (`EventInstance.setAcoustic` + the inserted nodes, the `AudioEmitter.acoustic` flag, the
+`AudioEmitterSystem` driving) lives in **sopra / the ECS audio layer**, not here.
+
+---
+
+## Quick start
+
+### 1. Wire it into the engine
+
+`configureAcousticSimulation` does the whole runtime wiring in one call — it builds (or reuses) the
+shared simulator, registers the two ECS systems against it, and injects the simulator into the
+`AudioEmitterSystem` whose per-frame `update()` drives it:
+
+```js
+import { configureAcousticSimulation } from "./configureAcousticSimulation.js";
+
+// `audioEmitterSystem` is constructed without an acousticSim; this injects it.
+// args: (configuration, audioEmitterSystem, simulator?, probeReverb?)
+const sim = configureAcousticSimulation(configuration, audioEmitterSystem, undefined, probeReverb);
+
+sim.random_seed = 1;   // optional — deterministic ray jitter (default 1)
+sim.rayCount = 16;     // rays per source per tick (amortized over frames)
+sim.smoothing = 0.4;   // temporal EMA
+```
+
+Under the hood that adds `AcousticSimulationSystem` (`AcousticBody` + `Collider` + `Transform` →
+occluders) and `AcousticVolumeSystem` (`AcousticVolume` + `Transform` → medium regions), both feeding the
+one returned simulator.
+
+Tag scene geometry as an occluder by adding an `AcousticBody` (with an `AcousticMaterial`) to an entity
+that already has a `Collider` + `Transform`. Add an `AcousticVolume` (a shape + `AcousticMedium`) to mark
+a region of different air.
+
+### 2. Opt sources in
+
+```js
+emitter.acoustic = true;     // 3D events with this set get occlusion / transmission / medium
+emitter.sourceRadius = 0.5;  // apparent source size, for volumetric (fractional) occlusion
+
+// optional: source DIRECTIVITY — radiate more toward where the entity faces (its Transform rotation).
+emitter.directivity.dipoleWeight = 0.5;  // 0 = omni (default), 0.5 = cardioid, 1 = dipole / figure-8
+emitter.directivity.dipolePower = 1;     // sharpen the lobe (> 1 narrows it)
+```
+
+Each frame the `AudioEmitterSystem` solves occlusion + transmission (ray-traced against the
+`AcousticBody` geometry), the medium (blended `AcousticVolume`s), and — for a non-omni source — the
+radiation **directivity** (the angle between where the source faces and the listener) for every live
+acoustic 3D instance, and pushes the result to `EventInstance.setAcoustic`, which drives an occlusion gain
+(scaled by directivity) + lowpass + transmission filter inserted in that instance's chain. All
+off-by-default: a non-acoustic event renders exactly as before, and an omni source pays nothing for
+directivity.
+
+### 3. Bake + wire reverb (offline once, render at runtime)
+
+```js
+import { bakeProbeField } from "./probe/bakeProbeField.js";
+import { ProbeReverbRenderer } from "./render/ProbeReverbRenderer.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+
+// OFFLINE: place probes over the scene (the bake region is derived from the occluder hull) and bake each
+// probe's per-band RT60. minSpacing is the density knob (smaller = denser).
+const probes = bakeProbeField(sim.occluderIndex, /*minSpacing*/ 8, /*rayCount*/ 256, seededRandom(1));
+const json = probes.toJSON();   // serialize, ship as an asset
+
+// RUNTIME: an acoustic-owned reverb bus driven by the listener's nearest probe
+const reverb = new ProbeReverbRenderer(audioContext, masterDestination);
+reverb.setProbeField(probes);
+sopraBusOutput.connect(reverb.input);   // send a copy of the dry signal in
+// pass `reverb` as options.probeReverb to configureAcousticSimulation, or assign it directly:
+audioSystem.probeReverb = reverb;       // driven once per frame from the listener
+```
+
+(`sim.occluderIndex` exposes the live occluder geometry so the bake runs against the same scene the
+runtime occludes with.)
+
+For **directional** reverb, drop in `FoaProbeReverbRenderer` instead — same bake, same wiring, but it
+renders the probe's per-band **arrival direction** (baked alongside the RT60) as a first-order ambisonic
+(B-format) field decoded to stereo, and steered by the listener's orientation so the reverb leans toward
+the open door / off the near wall and stays world-anchored as the head turns. It is driven the same way;
+`AudioEmitterSystem` passes the listener rotation to `update()` (the scalar renderer ignores it):
+
+```js
+import { FoaProbeReverbRenderer } from "./render/FoaProbeReverbRenderer.js";
+
+const reverb = new FoaProbeReverbRenderer(audioContext, masterDestination);
+reverb.setProbeField(probes);           // the SAME baked field — directions ride along
+sopraBusOutput.connect(reverb.input);
+audioSystem.probeReverb = reverb;        // driven from the listener pose (position + orientation)
+```
+
+The stereo decode is isolated so a binaural/HRTF (SOFA) decoder can replace it later without touching the
+encode/rotate path.
+
+### 4. Pathing (corner-leakage), optional
+
+```js
+import { bakeVisibility } from "./probe/bakeVisibility.js";
+
+bakeVisibility(probes, sim.occluderIndex); // bake the inter-probe visibility graph into the field
+sim.setProbeField(probes);                 // the field whose visibility graph pathing routes through
+sim.pathing = true;                        // engine-wide toggle (off by default)
+
+sim.pathingRecheck = true;                 // optional: re-verify traversed edges against LIVE geometry
+sim.recheckBudget = 8;                     //   (a closing door re-blocks the leak; budgeted, off by default)
+```
+
+The leak send carries the same acoustics as the direct path, but along the *routed* polyline: it is scaled
+by the source's **directivity toward the corner it leaks through** (not the blocked listener) and darkened by
+**air absorption over the longer leaked distance**. With `pathingRecheck`, the edges leaks traverse are
+re-tested each tick (within `recheckBudget`); an edge a mover has since blocked is disabled by weight
+(`EDGE_WEIGHT_BLOCKED`, no topology change) and restored when it re-opens — the cheap real-time half of the
+real-time-direct / baked-indirect split.
+
+---
+
+## The simulation, in one paragraph each
+
+**Occlusion + transmission.** For each live source, `OcclusionSolver` shoots `rayCount` rays from the
+listener toward points spread over the source's sphere (Fibonacci distribution, randomly re-oriented per
+tick). The fraction blocked is the occlusion; the blocked rays' material `transmission` (3 bands) is what
+leaks through. The result is folded into a temporal EMA, so a low ray count integrates over frames and
+the output never flickers. Rendered as a broadband gain (occluded → quieter, floored by transmission)
+plus a lowpass (occluded → muffled).
+
+**Medium / air absorption.** `AcousticVolume` regions carry an `AcousticMedium` whose `airAbsorption` is in
+**dB per metre**, per band. `VolumeField.integrateAbsorption` line-integrates it along the source→listener
+path (`∫ α ds`, blending regions + ambient air at each step) into `AcousticSolution.airLoss` — the per-band
+total dB lost over the path. So highs, which absorb faster, die over distance while the low end carries
+(distance-dependent atmospheric absorption); a thicker painted region adds extra loss where the path crosses
+it. Open air uses a small default atmosphere (tunable via the simulator's `defaultMedium`).
+
+It is rendered as a **low-anchored spectral tilt**: only the high‑vs‑low *excess* loss
+(`airLoss[high] − airLoss[low]`) drops the lowpass cutoff, so a uniform loss — which the authored distance
+**attenuation curve** already owns as broadband loudness — causes no darkening. The air filter is a separate
+series node from the attenuation gain, so the two compose (multiply) rather than fight: the curve owns *how
+loud*, air absorption owns *how bright*.
+
+**Reverb.** Offline, `bakeProbeField` bakes each probe's **per-band** reverberation. For a probe,
+`acoustic_trace_energy` shoots rays that bounce multiply through the scene ("source at the listener"),
+depositing per-band energy into a time-binned echogram; `echogram_band_rt60` reduces each band's decay to
+an RT60 (Schroeder backward integration + the ISO-3382 T30 slope). The bake is validated against the
+analytic **Sabine** reverberation time of a closed box. At runtime the listener's nearest probe sets the
+per-band RT60, which `reverbImpulseResponse` turns into a band-split decaying-noise convolution IR (so a
+bright room's tail rings longer in the highs), crossfaded by `ProbeReverbRenderer` as you cross probe
+cells.
+
+**Pathing (corner-leakage).** Offline, `bakeVisibility` connects probes with mutual line-of-sight into
+the `AcousticProbeField`'s visibility graph (a `CSRGraph` adjacency — connectivity is an inherent property of the
+field). At runtime, when the engine-wide `AcousticSimulator.pathing` toggle is on, one single-source
+Dijkstra from the listener (`ProbeFieldPathingSolution.computeExitField`, a per-frame solver the simulator
+owns) gives every probe its **exit point** — the probe adjacent to the listener on its
+path. Each occluded source then routes a second, exit-spatialized send, so a sound blocked by a wall is
+heard coming from the *doorway it leaks through*, not through the wall. Engine-wide toggle, **off by
+default (zero cost when off)** — no per-source flag.
+
+---
+
+## Performance
+
+Per-frame cost is bounded by the **live voice budget** (≤ 64), not the world size — the sim only touches
+promoted instances. Each source costs `rayCount` rays; a top-level BVH (TLAS) over the occluder bodies
+means a ray pays only for the few occluders near it, not every registered body. Tune `rayCount` down +
+lean on the temporal smoothing to amortize. The reverb/visibility bakes are offline (no frame budget).
+See `bench/occlusion.bench.spec.js` (remove `.skip` on the sweep to read µs/ray for your scene).
+
+---
+
+## Testing
+
+Everything except `render/` is WebAudio-free, so tests use real geometry and real ECS components — no
+audio mock. The render seam + reverb renderer use sopra's `MockAudioContext`.
+
+```
+npx jest --config jest.conf.json engine/sound/simulation     # from the repo root H:/git/moh
+```
+
+---
+
+## Status
+
+**Built + tested:** the whole simulation engine (P0–P6) + the **ray-traced per-band reflection-IR reverb**
+(the keystone: multi-bounce energy trace → per-band RT60, Sabine-validated → band-split IR render) + the
+occlusion / transmission / medium render seam + the corner-leakage (pathing) render. All wired into sopra
++ `AudioEmitterSystem` (one call via `configureAcousticSimulation`), additive and off-by-default.
+
+**Not yet wired (gated on the sopra strangler migration, all outside this folder):** production
+registration in `makeMirEngineConfig` (the legacy `SoundEmitter` path is still the live one) + save/load
+**binary serialization adapters** for `AcousticBody`/`AcousticVolume` — deliberately deferred to match
+`AudioEmitter`, which has none either (the components carry JSON `toJSON`/`fromJSON` for when it lands).
+
+**Optional / on-demand (not v1):** NEE-to-source early reflections, pathing live-recheck + door variants,
+FOA ambisonics, SOFA HRTF, source directivity.
+
+See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) and [REFLECTION_IR_PLAN.md](./REFLECTION_IR_PLAN.md)
+for the full phase-by-phase record and decisions.

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

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