@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +1,432 @@
+# Acoustic Simulation — Implementation Plan
+
+> A geometry-driven acoustic **simulation** layer for meep that feeds the **sopra** sound engine.
+> Steam-Audio-equivalent in *role* (occlusion, transmission, medium, later reflections / reverb /
+> pathing), built ECS-first and almost entirely in JS for **real-time, in-browser** use. The simulation
+> computes scalars / IRs against meep geometry; **sopra renders them through WebAudio**. The two never
+> blur: this folder produces data, sopra turns data into sound.
+>
+> Status: **P0–P6 BUILT + GREEN, all render paths wired** (full `engine/sound` suite 360 pass / 0
+> regressions). The simulation engine + the occlusion/transmission/medium RENDER seam + the **probe-baked
+> reverb RENDER** + the **corner-leakage (pathing) RENDER** are complete and wired into sopra + the ECS
+> (`AudioEmitterSystem`). Reverb render uses **option B** — a new acoustic-owned `ProbeReverbRenderer`
+> (its own double-buffered ConvolverNode crossfade, IR from the nearest probe's baked decay), leaving
+> sopra's static `ReverbEffect` untouched. Pathing render is an **engine-wide `AcousticSimulator.pathing`
+> toggle** (off by default, zero cost when off): one single-source Dijkstra from the listener per frame
+> (`AcousticPathGraph.computeExitField`) gives every probe its exit point; each occluded source routes a
+> second exit-spatialized send (`EventInstance` path branch). No per-source flag — threaded from the
+> engine config like `acoustic`. **ECS WIRING HELPER LANDED (2026-06-20):** `configureAcousticSimulation`
+> (`simulation/configureAcousticSimulation.js`) — one call from a config builds/reuses the shared
+> `AcousticSimulator`, adds `AcousticSimulationSystem` + `AcousticVolumeSystem` (via `addManySystems`),
+> and injects the simulator (+ optional `ProbeReverbRenderer`) into the `AudioEmitterSystem`. So the only
+> meep-internal integration is done; **Remaining:** the EXTERNAL config call (`makeMirEngineConfig`, in moh
+> — out of meep scope) + save/load serialization registration, both gated on the sopra strangler
+> migration. Serialization adapters are deliberately NOT built yet — they mirror `AudioEmitter`, which has
+> none either (the new sound stack defers binary save integration); the acoustic components carry JSON
+> `toJSON`/`fromJSON` + `typeName` for when the migration lands. To wire reverb: connect a sopra bus send →
+> `ProbeReverbRenderer.input`, pass `probeReverb` to `configureAcousticSimulation` (or set
+> `system.probeReverb`) + `renderer.setProbeField(bakedField)`. To wire pathing: `sim.pathing = true` +
+> `sim.setPathGraph(bakeVisibility(probeField, sim.occluderIndex))`.
+>
+> **What landed per phase:**
+> - **P0** — `AcousticMaterial`, `RayHit`, `AcousticOccluderIndex` (per-body local ebvh BLAS, O(1) `setTransform`).
+> - **P1** — `OcclusionSolver` (volumetric fibonacci rays + seeded jitter + EMA), `VolumeField`, `AcousticMedium`/`AcousticSolution`/`AcousticSourceState`.
+> - **P2** — `AcousticBody` + `AcousticSimulationSystem` (reactive); `AcousticSimulator`; occluder shapes raycast directly via `AbstractShape3D.raycast` (no triangulation).
+> - **P3** — `EventInstance.setAcoustic` + node insert (occlusion gain + lowpass + transmission); `AudioEmitter.acoustic`; `AudioEmitterSystem` apply + `LiveEmitterSet` acoustic threading. **First audible occlusion — wired.**
+> - **P4** — `AcousticVolume` + `AcousticVolumeSystem` (medium, blended, live-tracked).
+> - **P5** — world-AABB broadphase (measurement-driven via `bench/occlusion.bench.spec.js`); temporal amortization proven.
+> - **P6** — `AcousticProbe` + `bakeReverb` + `ProbeField` + `bakeProbeField` (geometry-derived reverb, density knob, serialized); `AcousticPathGraph` + `bakeVisibility` + `findAcousticPath` (probe-visibility routing around obstacles).
+>
+> **Post-P6 cleanup + accel pass (2026-06-20, all committed, `engine/sound` 373 pass):** the occluder
+> index now **raycasts shapes directly** via `AbstractShape3D.raycast` (no triangulation;
+> `acoustic_geometry_from_shape` deleted) and sits behind a **TLAS** — a dynamic BVH over the bodies'
+> world AABBs (P5's deferred TLAS, landed early). `RayHit` carries the world hit **point + normal** (no
+> `hit` flag, no `triangleIndex`). Per-source state is **pooled** in a `BinaryElementPool`
+> (`Map<EventInstance, id>`, flyweight cursor) instead of a `Map<…, AcousticSourceState>`. The probe
+> substrate moved to **`RowFirstTable` + a probe BVH** (nearest via `bvh_query_user_data_nearest_to_point`)
+> and **`CSRGraph`** connectivity. `sourceRadius` moved onto `AudioEmitter`/`EventInstance`;
+> `pathMaxDistance` was removed (path falloff now derives from the source's authored attenuation curve);
+> `AcousticSolution.exit` is a vector. Below, §3.1 / §4 / D5 / P5 describe the v1 triangle-BLAS +
+> linear-scan design that this pass superseded — read them as history. The remaining headline work is the
+> ray-traced reflection IR (see `REFLECTION_IR_PLAN.md`).
+>
+> **FOA directional reverb LANDED (2026-06-20):** the first of P6's two premium tiers — the **FOA
+> (first-order ambisonic / B-format) directional reverb field**. The bake now captures, per band, the
+> energy-weighted **arrival direction** (a 0..1 anisotropy vector) by reciprocity — a ray's reverberant
+> energy arrives from its launch direction (`acoustic_trace_energy` accumulates it, `bakeReverbBands`
+> normalises it). `ProbeField` widened stride 6→15 to store the three per-band direction vectors (JSON
+> round-trips them). Render: a new `render/FoaProbeReverbRenderer` convolves the mono send into a B-format
+> set (`foaReverbImpulseResponse` — `W` omni + `X/Y/Z` steered by the baked direction, one-factor W-energy
+> normalised) and decodes to stereo by **rotating the decoder, not the soundfield** (two virtual cardioids
+> whose look dirs are rotated into world space by the listener orientation — six decode gains/frame, the IR
+> re-baked only on probe-cell change). `AudioEmitterSystem` now threads the listener rotation to
+> `probeReverb.update()` (the scalar `ProbeReverbRenderer` ignores it). Stereo decode is isolated so a
+> binaural/HRTF (SOFA) decoder can replace it later.
+>
+> **Source directivity LANDED (2026-06-20):** the second of P6's premium tiers. `AcousticDirectivity`
+> (`simulation/definition/`) is the Steam-Audio dipole model — `gain = |(1−w) + w·cosθ|^p`
+> (`w` = `dipoleWeight` 0=omni/0.5=cardioid/1=dipole, `p` = `dipolePower`), `cosθ` = source forward · the
+> source→listener direction. Authored on `AudioEmitter.directivity` (default omni → zero cost; `isOmni`
+> short-circuits). The simulator's `apply` computes it per non-omni source (forward = `Vector3.forward`
+> rotated by the source's orientation) into `AcousticSolution.directivityGain`, which `EventInstance.setAcoustic`
+> multiplies into the direct-path gain. Orientation (shared `Transform.rotation` ref) + the directivity ref
+> plumb through `playEvent`/`LiveEmitterSet` exactly like `sourceRadius`/`position`. **P6 premium tiers now
+> both done;** the only remaining acoustic work is the external `makeMirEngineConfig` activation + save/load
+> serialization (gated on the sopra strangler migration) and the deferred optional refinements (NEE early
+> reflections, pathing live-recheck, door variants, binaural/SOFA decode).
+>
+> **DISTANCE AIR ABSORPTION LANDED (2026-06-20):** "low frequencies travel further." `AcousticMedium.airAbsorption`
+> is now **dB/metre**; `VolumeField.integrateAbsorption` line-integrates it over the source→listener path
+> (`∫ α ds`; no-region case is closed-form `ambient·distance`, else 8-midpoint march reusing `sample`) into the
+> new `AcousticSolution.airLoss[3]` (per-band total dB). The point-sampled `AcousticSolution.medium` was
+> REMOVED (superseding §6's `airAbsLP.frequency ← solution.medium.airAbsorption` — air is now path-integrated,
+> not point-sampled). Render (`EventInstance.setAcoustic`) anchors the tilt at the LOW band — only
+> `airLoss[high] − airLoss[low]` darkens the cutoff (`OPEN·2^(−tilt/6dB-oct)`, floored), so a uniform loss (the
+> distance **attenuation curve's** job, a windowed/irradiance falloff — *not* physical) causes no darkening:
+> the curve owns loudness, air owns the spectral tilt, and the two compose via separate series nodes. Default
+> ambient = a small low-anchored atmosphere (`DEFAULT_AIR_ABSORPTION [0, 0.03, 0.1] dB/m`, tunable). Applied to
+> the DIRECT path only (the leak send's longer path is a deferred refinement, like directivity-on-leak).
+>
+> **CORNER-LEAK REFINEMENTS + DYNAMIC RECHECK + SERIALIZATION LANDED (2026-06-21):** the three corner-leak
+> gaps are closed, plus the acoustic binary adapters. (1) **Leak now carries directivity + air.**
+> `AcousticSimulator.#applyPath` walks the leaked polyline ONCE (source→…→listener via
+> `ProbeFieldPathingSolution.next`) and does three things: integrates air per leg
+> (`VolumeField.integrateAbsorption`) into the new `AcousticSolution.pathAirLoss[3]`; folds **directivity toward
+> the FIRST hop** (the corner the source radiates into, not the blocked listener — `#directivityGainToward`)
+> into `pathGain`; and marks each traversed edge for the recheck. `EventInstance`'s leak branch renders through
+> its own 3-band crossover (`#leak3Band`), gained per band by `(1 − transmission[b])` × the `pathAirLoss`
+> low-anchored tilt (so a longer routed leak darkens more, and a band-selective wall leaks only its blocked
+> bands around the corner — consistent with the direct path's 3-band render).
+> (2) **Budgeted dynamic-geometry recheck** (`AcousticSimulator.pathingRecheck` + `recheckBudget`, off by
+> default): `ProbeVisibilityRecheck` re-verifies (within budget, FIFO round-robin) the edges leaks traverse
+> against live geometry (`probe_edge_visible`, extracted + shared with `bakeVisibility`); a now-blocked edge →
+> `EDGE_WEIGHT_BLOCKED` (Float32 max — finite, no topology change, blows the path distance past audibility),
+> restored to the inter-probe distance when it re-opens. No structural mutation; the baked graph self-heals.
+> (3) **Binary serialization** adapters for `AcousticMaterial`/`AcousticMedium`/`AcousticDirectivity` (value
+> types) + `AcousticBody`/`AcousticVolume` (components, delegating; shape omitted like `toJSON`), with
+> `populateAcousticSerializationRegistry`. (`AudioEmitter`'s own adapter — needing the full sopra
+> `EventDescription` clip-graph chain — is still deferred.) Plus a **two-rooms-and-a-corridor integration
+> test** (`two_rooms_corridor.spec.js`) verifying bake (per-band reverb), reachability, leak direction
+> (emerges from the corridor, not through the wall), routed-vs-straight attenuation, and a sealed-divider
+> disconnection control. **Remaining deferred** (optional/premium): NEE early reflections, binaural/SOFA
+> decode, opt-in door variants + re-bake-on-streaming, region-aware air over the leak polyline, the full
+> external `makeMirEngineConfig` activation (gated on the sopra strangler migration).
+
+---
+
+## 0. The one rule: simulation vs. render
+
+```
+  SIMULATION (this folder — engine geometry, JS, no WebAudio)        RENDER (sopra — WebAudio)
+  ───────────────────────────────────────────────────────────       ─────────────────────────
+  AcousticBody   (occluder shapes + material) ─┐
+  AcousticVolume (medium)                      ├─► AcousticSolution ─► EventInstance.setAcoustic()
+  ebvh rays + Ray3 + sphere_fibonacci_point ───┘    (a class)            (gain + biquad insert)
+```
+
+`simulation/core` and `simulation/ecs` import **no WebAudio**. The *only* WebAudio touch is the seam
+where `AudioEmitterSystem` hands an `AcousticSolution` to `EventInstance.setAcoustic(...)` (that method
+lives in sopra, where the node chain already lives). Consequence: the whole simulation is unit-testable
+on real geometry with **zero `MockAudioContext`** — only the one render seam needs it.
+
+We do **not** put medium on `EventDescription`. An event is a recipe for *a source*; the medium (air,
+room) is a property of *the world*. Medium lives on `AcousticVolume` components; a source merely **opts
+in** to simulation via one flag (`AudioEmitter.acoustic`). No god-object `AcousticScene` — the occluder
+set is just the entities that have an `AcousticBody`, indexed by a system-owned acceleration structure.
+This is an ECS engine at the top level; the data model is components.
+
+---
+
+## 1. Layout
+
+```
+sound/simulation/
+  IMPLEMENTATION_PLAN.md
+  definition/                          authored, immutable, serializable (sopra/definition style)
+    AcousticMaterial.js                value class: absorption[3], scattering, transmission[3]
+    AcousticMaterialSerializationAdapter.js
+  core/                                ECS-agnostic AND WebAudio-agnostic — the testable heart
+    RayHit.js                          result class: t / material / bodyHandle / world position + normal
+    AcousticOccluderIndex.js           OccluderBody shapes + world transform behind a TLAS BVH; closestHit / anyHit
+    AcousticMedium.js                  value class: airAbsorption (per-band)
+    AcousticSolution.js                result class the render seam consumes: occlusion, transmission[3], medium
+    AcousticSourceState.js             transient per-source accumulation (rolling occlusion, smoothing)
+    OcclusionSolver.js                 solve(listener, source, index, rayCount, state, out) — explicit args, out-param
+    VolumeField.js                     sample(volumes, x, y, z, out) — out-param, no allocation
+    sampleDirections.js                sphere_fibonacci_point set + per-tick seededRandom rotation
+  ecs/                                 thin ECS binding (real-component tested)
+    AcousticBody.js                    component: AcousticMaterial + "is occluder"; pairs with Collider + Transform
+    AcousticBodySerializationAdapter.js
+    AcousticVolume.js                  component: AbstractShape3D + AcousticMedium + transition band
+    AcousticVolumeSerializationAdapter.js
+    AcousticSimulationSystem.js        System: maintain index + volume set (reactive); apply(liveInstances, listener)
+  probe/                               P6 — the baked substrate for reverb + pathing (see D6)
+  bench/
+    occlusion.bench.spec.js            rays/tick + ms/tick calibration (raycast.bench methodology)
+```
+
+The render-side additions (`EventInstance.setAcoustic`, the node insert, `AudioEmitter.acoustic`) live in
+**sopra**, not here — see §6.
+
+---
+
+## 2. Reused meep primitives (verified to exist)
+
+| Primitive | Path | Used for |
+|---|---|---|
+| `ebvh_geometry_query_nearest_triangle_ray` | `core/bvh2/bvh3/` | closest-hit ray → `[triangleIndex,u,v,t]` |
+| `ebvh_build_for_geometry_morton` | `core/bvh2/bvh3/` | build a body's BLAS from its triangle soup |
+| `BVH` | `core/bvh2/bvh3/BVH.js` | the per-body tree (`new BVH()`, `release_all`, `allocate_linear`, `root`) |
+| `Ray3` (`Float32Array(7)`: o,d,tMax) | `core/geom/3d/ray/Ray3.js` | the ray type; slots into the ebvh query as-is; `applyMatrix4` for local transform |
+| `m4_invert` / `m4_inverse_rotation_translation` | `core/geom/3d/mat4/` | per-body world→local inverse |
+| `sphere_fibonacci_point` | `core/geom/3d/sphere/` | even source-sphere / hemisphere sampling |
+| `v3_orthonormal_matrix_from_normal` + `v3_matrix3_rotate` | `core/geom/vec3/` | hemisphere sampling around a normal (P6) |
+| `seededRandom` (Mulberry32) | `core/math/random/` | per-tick ray jitter; **never `Math.random`** |
+| `AbstractShape3D.signed_distance_at_point` / `contains_point` | `core/geom/3d/shape/` | `AcousticVolume` boundary blend |
+| `AnimationCurve` | `engine/animation/curve/` | distance→cutoff curves (reuse, don't invent) |
+| `BinarySerializationRegistry` + adapter pattern | `ecs/storage/binary/` | serialize materials/bodies/volumes |
+| SH toolkit (`sh3_rotate_bl`, `sh3_sample_by_direction`, `sh3_add`) | `core/geom/3d/sphere/harmonics/` | ambisonic field (P6) |
+| `AssetManager` + `OfflineAudioContext` | `engine/asset/` / browser | baked probe data + offline IR (P6) |
+
+---
+
+## 3. Encapsulation (the clean core)
+
+**Two non-negotiables, applied everywhere below:**
+- **No opaque config bags.** Tunables (`rayCount`, …) are passed as explicit arguments. Configuration
+  objects rot — a function that needs a ray count takes a ray count.
+- **No magic structs / `@typedef`.** Every result/value shape is a real **class** (`RayHit`,
+  `AcousticSolution`, `AcousticMedium`, `AcousticSourceState`, `AcousticMaterial`). Hot-path queries are
+  **allocation-free**: the caller allocates the result and passes it in; the function writes into it.
+
+### 3.1 `AcousticOccluderIndex.js` — the (internal) acceleration structure, fully dynamic
+Not a public "scene". Owns a list of **bodies**, each a *local-space* triangle BLAS (`BVH` built once via
+`ebvh_build_for_geometry_morton`) plus a world transform (and its cached inverse) and one
+`AcousticMaterial`. API:
+
+```js
+addBody(positions, indices, material, matrix?) → handle   // BLAS built once from local triangles
+setTransform(handle, matrix)                              // O(1): store matrix + recompute inverse
+removeBody(handle)
+closestHit(ray /* Ray3 */, out /* RayHit */) → boolean    // nearest hit across all bodies, into `out`
+anyHit(ray /* Ray3 */) → boolean                          // early-out
+```
+
+`closestHit` transforms the world ray into each body's local frame (a module-static `Ray3` scratch +
+`applyMatrix4(inverse)`), runs the ebvh query against that body's BLAS bounded by the running best-`t`,
+and keeps the nearest; `out` receives `{ t, material, bodyHandle, triangleIndex }`. **Fully dynamic**:
+a moving body is just `setTransform` (O(1), no rebuild) — the ECS layer drives it from
+`Transform.position.onChanged`. Material is **per body** (a wall has one material); per-triangle
+materials are a later refinement, not a v1 need. *Precondition: rigid transforms (no scale), so local
+`t` equals world `t`* (documented, not guarded — see house rules). A body-level BVH (TLAS) over the bodies
+is the **P5** scaling step; v1 linear-scans the (few) bodies, BLAS does the real work.
+
+### 3.2 `OcclusionSolver.js` — the per-source solve (pure, explicit args, out-param)
+```js
+solve(listenerPose, sourceX, sourceY, sourceZ, sourceRadius, index, rayCount, state, out) → void
+```
+Shoots `rayCount` rays from the listener toward a `sphere_fibonacci_point` set over the source's sphere
+(`sourceRadius`), rotated per tick by a `seededRandom` orientation (so accumulation covers the sphere).
+Each ray is bounded (`tMax` = listener→sample distance) so far subtrees prune. Blocked-ray fraction →
+instantaneous occlusion; blocked rays' materials accumulate the transmission 3-band. Folded into `state`
+(`AcousticSourceState`, a rolling window) and smoothed; written into `out` (`AcousticSolution`).
+**Pure function of geometry + state**, deterministic for a seed; no ECS, no WebAudio, no allocation.
+
+### 3.3 `VolumeField.js` — medium zones (pure, out-param)
+```js
+sample(volumes, x, y, z, out /* AcousticMedium */) → void
+```
+Each `AcousticVolume` has an `AbstractShape3D` and a `transition` band. Weight =
+`smooth(-signed_distance / transition)` clamped to `[0,1]` (1 deep inside, 0 outside, smooth across the
+boundary). Normalize weights over overlapping volumes; blend the medium into `out`. A few
+`signed_distance_at_point` evals per query — cheap. Queried at the listener every tick; at sources
+optionally. **Pure**, allocation-free.
+
+### 3.4 result + state classes
+`RayHit`, `AcousticSolution`, `AcousticMedium`, `AcousticSourceState`, `AcousticMaterial` are all real
+classes with named fields and a `reset()`/`clear()` where they are reused. The system owns a
+`Map<EventInstance, AcousticSourceState>`, dropped on `instance.onEnded` — so `EventInstance` stays
+ignorant of solver internals.
+
+---
+
+## 4. The component model (ECS)
+
+### `AcousticBody` (occluder) — pairs with `Collider` + `Transform`
+Serializable component carrying an `AcousticMaterial` and the "this entity occludes audio" semantic. The
+**shape** comes from the entity's existing `Collider`/mesh; `AcousticBody` contributes the acoustic
+*properties*. The system triangulates the body's collider shape once into the occluder index (local
+space) and drives its transform reactively. Tagging a wall = adding the component; nothing
+acoustically-inert occludes unless tagged — that closes the "physics BVH contains everything" problem the
+ECS way.
+
+### `AcousticVolume` (medium) — pairs with `Transform`
+Serializable component: an `AbstractShape3D` (its region), a `transition` distance (boundary blend band),
+and an `AcousticMedium` (air-absorption coefficients). Volumes overlap and blend (§3.3). **Medium only —
+no reverb here.** (Authored "reverb zones" are the wrong primitive; real reverb is the geometry-traced /
+baked output of the probe volume in P6. Until then, sopra's existing reverb stands unchanged.)
+
+### `AcousticSimulationSystem` — the binding
+`extends System`, `dependencies` covering `AcousticBody`/`AcousticVolume`:
+- `link/unlink AcousticBody` → `index.addBody/removeBody` + subscribe `transform.position.onChanged`
+  (and rotation) → `index.setTransform`. **Reactive, no per-tick refit loop** (mirrors
+  `SpatialAudioIndex`).
+- `link/unlink AcousticVolume` → add/remove from the volume list.
+- `apply(liveInstances, listenerPose)` — **called by `AudioEmitterSystem`** between `liveSet.refresh`
+  and `sopra.update`. Samples the listener medium once, then for each **live 3D** instance opted into
+  acoustics: `OcclusionSolver.solve(...)` (+ optional per-source `VolumeField.sample`) into a pooled
+  `AcousticSolution` → `instance.setAcoustic(solution)`. Bounded to ≤ budget (consumes the live set,
+  never iterates all registered emitters).
+
+`AudioEmitterSystem` takes an **optional injected** `acousticSim` collaborator (default none → behaviour
+identical to today). Feature is off-by-default and testable in isolation.
+
+---
+
+## 5. Key decisions
+
+- **D1 — Event carries no medium; one opt-in flag.** `AudioEmitter.acoustic` (default `false`) plumbs to
+  the instance; `EventInstance` builds the acoustic nodes only when set; `setAcoustic` is a no-op
+  otherwise. `EventDescription` stays medium-free. (Owner-directed.)
+- **D2 — No `AcousticScene`; geometry is `AcousticBody` components, indexed internally.**
+- **D3 — `AcousticVolume` is medium-only.** No authored reverb zones. Reverb is the P6 traced/baked
+  output; sopra's existing reverb stands until then.
+- **D4 — `simulation/` imports no WebAudio.** It emits `AcousticSolution`s; sopra renders. The whole
+  simulation is testable without `MockAudioContext`.
+- **D5 — Occluders are fully dynamic.** No static merge. Per-body local BLAS + an O(1) `setTransform`;
+  the ECS layer refits reactively via `Transform.onChanged` (meep is reactive end-to-end — there is no
+  static/dynamic flag and no per-tick iteration). A body-level TLAS is the P5 scaling step, not a
+  correctness requirement.
+- **D6 — Using the sim requires a built probe volume; the bake is automatic.** When acoustics is enabled
+  for a scene, a **probe volume** must be built (it is the substrate for reverb + pathing). The bake is
+  **fully automatic** save for a few knobs (chiefly **maximum probe density**): it places probes across
+  the playable space, computes their data (reflection/reverb IR + inter-probe visibility for pathing),
+  and **serializes** the result. Triggering the bake is the user's responsibility (an explicit call /
+  editor action — it is not free), but the user authors no probes by hand. Runtime then just loads and
+  selects/blends baked probe data. (This is why pathing/reverb are P6: they consume the probe volume.)
+- **D7 — No opaque config bags; explicit args.** Tunables are parameters, not config objects.
+- **D8 — No magic structs; classes + caller-allocated out-params.** Hot-path queries allocate nothing.
+- **D9 — Cosmetic-only, so no determinism gate.** Rays use `seededRandom` (reproducible tests, clean
+  jitter), but there is no lockstep/networking requirement. If acoustics ever become gameplay-affecting
+  (AI hearing), that is a different project with a different bar.
+- **D10 — Bounded, amortized, allocation-free.** Work is capped to the ≤ budget (64) live voices;
+  `rayCount` is amortized across frames into `AcousticSourceState`; apply is throttleable; results +
+  scratch are pooled. JS constant factors are accepted; the budget is the contract.
+
+---
+
+## 6. Render seam (in sopra — the only WebAudio change)
+
+`EventInstance.#buildOutputChain` (today `voices → instanceGain → attenuationGain → panner → bus`) gains,
+**only when the instance is acoustic**, an insert + a parallel transmission branch:
+
+```
+voices → instanceGain → attenuationGain → airAbsLP → occlusionGain → occlusionLP → panner → bus
+                                                    └→ transmission 3-band (parallel GainNodes) ─┘
+```
+
+`EventInstance.setAcoustic(solution)` ramps those `AudioParam`s (smoothing — no zipper):
+`occlusionGain ← 1-occlusion`, `occlusionLP.frequency ← f(occlusion)`, the three transmission band gains
+← `(1-occlusion) + occlusion·transmission[band]` (**parallel crossover, not series shelves** — band gains
+are independent and linear), `airAbsLP.frequency ← solution.medium.airAbsorption`. All nodes default to
+unity / open → an acoustics-off or 2D event is byte-identical to today. (Reverb is untouched here; it is
+the P6 probe-driven concern.)
+
+---
+
+## 7. Phased plan
+
+Each phase ships behind black-box `*.spec.js` run from `H:/git/moh` root
+(`npx jest --config jest.conf.json engine/sound/simulation`). Real objects per house rules; the WebAudio
+boundary (only P3+) uses `MockAudioContext`.
+
+- **P0 — Core occluder substrate (no ECS, no WebAudio). ← building now.** `AcousticMaterial` class +
+  adapter; `RayHit` class; `AcousticOccluderIndex` (per-body local BLAS via `ebvh_build_for_geometry_morton`,
+  `Ray3`-based `closestHit`/`anyHit` into a caller `RayHit`, O(1) `setTransform`).
+  *Exit:* a hand-built box room answers closest-hit + per-body material correctly; a ray through an
+  opening misses; moving a body via `setTransform` changes the result; `anyHit` early-outs; material
+  round-trips. Zero ECS/WebAudio.
+- **P1 — `OcclusionSolver` + `VolumeField` + state (still no ECS/WebAudio).** Volumetric sampling
+  (`sphere_fibonacci_point` + `seededRandom` rotation), temporal accumulation in `AcousticSourceState`,
+  smoothing; `VolumeField` blend with `AcousticMedium`.
+  *Exit:* occlusion monotonic vs. wall coverage; fully walled → 1 with the wall's material in
+  transmission; open → 0; frame-stable; deterministic for a seed; volume blend + boundary interpolation
+  correct. Pure functions on geometry, allocation-free.
+- **P2 — ECS binding for occlusion.** `AcousticBody` + adapter; `AcousticSimulationSystem`
+  (reactive link/unlink + `setTransform`; `apply` loops live 3D instances → solver; owns the per-instance
+  state map).
+  *Exit:* real `EntityManager` + real `AcousticBody`/`Transform`/`Collider`; add/remove/move a body
+  changes the solution; cost bounded to ≤ budget. No WebAudio (assert on returned solutions).
+- **P3 — Render seam (first audible occlusion + transmission).** `EventInstance.setAcoustic` + the
+  no-op-default node insert; `AudioEmitter.acoustic` flag; `AudioEmitterSystem` calls `acousticSim.apply`
+  between `refresh` and `sopra.update`.
+  *Exit (MockAudioContext):* occlusion moves the gain + lowpass; transmission bands respond to material;
+  acoustics-off events identical to today; off-by-default.
+- **P4 — `AcousticVolume` (medium).** Component + adapter; `VolumeField` wired so air-absorption follows
+  the listener's blended volume.
+  *Exit:* blend weights + boundary interpolation correct; air absorption follows the listener's volume;
+  no pop crossing a boundary.
+- **P5 — Perf hardening + occluder TLAS.** Amortization/throttle knobs; scratch-pool audit (zero
+  per-frame alloc); a body-level BVH (TLAS) so `closestHit` is O(log bodies); `bench/` calibrating
+  ms/tick + rays/tick at budget=64.
+  *Exit:* measured ≤ target ms/tick; no GC churn; many-body scenes scale.
+- **P6 — Probe volume + premium tiers (gated).** The automatic probe-volume **bake** (D6: density-knobbed
+  probe placement over the playable space, per-probe reflection/reverb IR + inter-probe visibility,
+  serialized via the registry, user-triggered) → **reverb** (probe IR into a double-buffered
+  `ConvolverNode` on sopra's reverb send bus, crossfaded as the listener crosses probe cells) and
+  **pathing** (baked probe-visibility graph — **NOT** navmesh; navmesh connectivity ≠ acoustic
+  connectivity: a window/cliff/ramp carries sound with no navmesh edge). Plus **FOA directional reverb
+  field** (✓ LANDED 2026-06-20 — per-band baked arrival direction + B-format `FoaProbeReverbRenderer`; see
+  the dated note up top) and **source directivity** (✓ LANDED 2026-06-20 — `AcousticDirectivity`
+  monopole/dipole on `AudioEmitter`, solved into `directivityGain`; see the dated note up top).
+
+---
+
+## 8. Runtime cost (the contract)
+
+Bounded by the ≤ 64 live voices, **world-size-independent**. Calibration constant `c` = per-ray ebvh
+closest-hit (≈1 µs occlusion in JS — measure with `bench/`). Occlusion+transmission =
+`liveVoices × rayCount × c`: 8 rays/voice ≈ 0.5 ms, 16 ≈ 1.0 ms; temporal amortization (rayCount spread
+over F frames) + throttle (15–20 Hz) cut it 3–4×. Medium (air absorption) + volume blend are closed-form
+(< 0.05 ms). Realistic v1 (occlusion + transmission + medium, reverb still sopra's existing) ≈
+**0.3–1.0 ms/tick** main-thread, dominated by occlusion ray count. Render adds ~5 native nodes per
+acoustic voice on the **separate** audio thread. The lever is `liveVoices × rayCount`; the only spike
+(traced reflections, P6) is precomputed into the probe volume and never on the per-frame path.
+
+---
+
+## 9. Integration & blast radius
+
+| Touch | Change | Risk |
+|---|---|---|
+| `AudioEmitterSystem` | optional injected `acousticSim`; one `apply()` call between refresh & tick; read `listenerTransform.rotation` | low |
+| `LiveEmitterSet` | +1 accessor to enumerate live instances (bounded) | low |
+| `EventInstance` (sopra) | `setAcoustic` + no-op-default node insert in `#buildOutputChain` | **med** (hot chain — unity default, re-run `spatialization.spec`) |
+| `AudioEmitter` | `acoustic` opt-in flag (+ later `directivity`) | low |
+| `ReverbEffect`/`BusGraph` (sopra) | double-buffered convolver for probe reverb (**P6 only**) | med (reverb path, deferred) |
+| **New** | all of `sound/simulation/**` | n/a (self-contained) |
+
+**Untouched:** `SopraEngine` public API, the clip graph / containers / parameters / `VoiceManager` /
+voice-stealing / bus tree / snapshots / ducking, the `SpatialAudioIndex`/`LiveEmitterSet` cull+budget
+logic, the legacy `SoundEmitter` path, save-format back-compat. The simulation **consumes** the live set;
+it never alters culling, polyphony, or the mixer graph. `EventDescription` carries no medium.
+
+**Gate:** lands on the `AudioEmitter`/`AudioEmitterSystem` path, not yet in `makeMirEngineConfig`. Nothing
+here is observable in-game until the sopra strangler cut-over completes.
+
+---
+
+## ECS wiring notes (probe field + regions)
+
+**`AcousticProbeFieldSystem` — single field (v1).** The baked `AcousticProbeField` is an ECS component
+(`typeName` + `toJSON`/`fromJSON` + `AcousticProbeFieldSerializationAdapter`); the system links it and wires
+it into the simulator (`setProbeField`) for pathing + probe reverb. **Only one field is supported for now:**
+the FIRST linked field is wired, any others are silently ignored (no error). TODO — **multiple probe fields**:
+e.g. per-region / streamed fields with the active field selected by listener position, or merged into one
+graph. Needs a field registry + a selection rule on the simulator (today `setProbeField` holds exactly one).
+Until then a scene has exactly one probe field.
+
+**Region index refit.** `AcousticRegionIndex` is BVH-backed (O(log n) blend queries); regions track
+`Transform.position` by reference, so the simulator re-fits ALL region leaves once per frame in `apply()`.
+TODO — refit only the regions that actually moved (needs move tracking on `AcousticVolumeSystem`, like the
+occluder system's `onChanged` subscription); fine while region counts are small.