@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/sound/simulation/probe/AcousticProbeField.js

@@ -1,578 +1,578 @@
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import {
-    bvh_query_user_data_nearest_to_point
-} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point.js";
-import {
-    bvh_query_user_data_intersects_sphere
-} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_sphere.js";
-import {
-    bvh_query_user_data_nearest_to_point_filtered
-} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point_filtered.js";
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { csr_graph_find_shortest_path } from "../../../../core/graph/csr/csr_graph_find_shortest_path.js";
-import { acoustic_probe_transfer, LOBE_STRIDE } from "./acoustic_probe_transfer.js";
-
-// Probe layout in #data: STRIDE float32s per probe — position, per-band reverb RT60, per-band arrival dir.
-const STRIDE = 15;
-const OFFSET_X = 0;
-const OFFSET_Y = 1;
-const OFFSET_Z = 2;
-const OFFSET_REVERB = 3;    // per-band RT60 (seconds): band b at OFFSET_REVERB + b              — 3 floats
-const OFFSET_DIRECTION = 6; // per-band arrival direction (xyz): band b at OFFSET_DIRECTION + b*3 — 9 floats
-
-// passed as the lobe store for a probe with no lobes baked — never indexed (count 0), but keeps a real array
-// off the transfer call rather than null
-const EMPTY_LOBES = new Float32Array(0);
-
-// initial probe capacity of a fresh field's backing array
-const DEFAULT_CAPACITY = 8;
-
-// module scratch for a point-leaf AABB during BVH build
-const LEAF_BOUNDS = new Float32Array(6);
-
-// module scratch — the query→probe line-of-sight ray for nearestVisibleIndex
-const VISIBILITY_RAY = new Ray3();
-
-/**
- * The baked probe volume: the set of acoustic probes covering a scene, plus the connectivity between them.
- * Carries everything an offline bake produces about the field and everything the runtime reads back from
- * it — per-band reverb, BVH nearest-probe lookup, and (optionally) the probe-visibility graph that sound
- * routes through. Serializable (the bake is offline; the field loads as an asset). Pure data + graph
- * search; no WebAudio.
- *
- * Probe data lives in a flat {@link Float32Array} ({@link STRIDE} floats per probe: x, y, z, per-band
- * reverbDecay, per-band arrival direction) indexed by `i*STRIDE` — no per-probe object, no table
- * indirection. The per-band arrival direction is the FOA / first-order anisotropy vector a directional
- * reverb renderer steers the wet field by. Nearest-probe lookup is
- * BVH-accelerated: a {@link BVH} over the probe points (leaf user-data = probe index) is built lazily and
- * queried with {@link bvh_query_user_data_nearest_to_point}, so a per-frame listener query is O(log n)
- * rather than a full scan.
- *
- * Connectivity is an inherent property of the field: once `bakeVisibility` has connected the probes with
- * mutual line-of-sight ({@link setVisibilityGraph}), {@link shortestPath} routes sound around obstacles —
- * through doorways and around corners — independent of walkability (air-visibility, not a navmesh). The
- * mutable, per-listener exit-field solve lives in a separate {@link ProbeFieldPathingSolution} — this baked
- * field stays immutable data + the graph it owns.
- */
-export class AcousticProbeField {
-    /**
-     * Flat probe storage, {@link STRIDE} float32s per probe:
-     * `[x, y, z, reverbLow, reverbMid, reverbHigh, dirLowXYZ, dirMidXYZ, dirHighXYZ]`.
-     * Probe `i` occupies `[i*STRIDE … i*STRIDE + STRIDE)`. Backing length is the capacity, not the size.
-     * @type {Float32Array}
-     */
-    #data = new Float32Array(DEFAULT_CAPACITY * STRIDE);
-
-    /**
-     * Number of probes (distinct from the backing array's length).
-     * @type {number}
-     */
-    #size = 0;
-
-    /**
-     * Nearest-lookup acceleration over the probe points; rebuilt lazily after the field changes.
-     * @type {BVH}
-     */
-    #bvh = new BVH();
-
-    /**
-     * Whether {@link #bvh} reflects the current probes (false after a position change).
-     * @type {boolean}
-     */
-    #bvhValid = false;
-
-    /**
-     * Probe-visibility adjacency for pathing: vertex v = probe v, edge = mutual line-of-sight, edge weight =
-     * inter-probe distance. Baked by `bakeVisibility` and attached via {@link setVisibilityGraph}; null
-     * until then — a field without connectivity still serves reverb and nearest lookup.
-     * @type {CSRGraph|null}
-     */
-    #graph = null;
-
-    /**
-     * Per-probe reflector lobes for the directional TRANSFER (corner-leak gating), in CSR form:
-     * {@link #lobeOffsets}`[v]…[v+1]` is probe v's lobe range in {@link #lobeData} (LOBE_STRIDE floats each).
-     * Baked by `bakeProbeReflectors` and attached via {@link setLobes}; both null until then (a field without
-     * transfer routes with the forward/passthrough term only). Like the visibility graph, a bake product —
-     * NOT serialized; re-bake after load.
-     * @type {Uint32Array|null}
-     */
-    #lobeOffsets = null;
-
-    /**
-     * Flat lobe storage (LOBE_STRIDE floats per lobe), indexed via {@link #lobeOffsets}. Null until baked.
-     * @type {Float32Array|null}
-     */
-    #lobeData = null;
-
-    /**
-     * @returns {number} number of probes
-     */
-    get size() {
-        return this.#size;
-    }
-
-    /**
-     * Whether a visibility graph has been baked into this field (i.e. pathing is available).
-     * @returns {boolean}
-     */
-    get hasVisibility() {
-        return this.#graph !== null;
-    }
-
-    /**
-     * The baked probe-visibility graph, or null if none has been baked. The substrate that
-     * {@link shortestPath} and a {@link ProbeFieldPathingSolution} search.
-     * @returns {CSRGraph|null}
-     */
-    get visibilityGraph() {
-        return this.#graph;
-    }
-
-    /**
-     * Whether reflector lobes (the directional transfer) have been baked into this field.
-     * @returns {boolean}
-     */
-    get hasTransfer() {
-        return this.#lobeOffsets !== null;
-    }
-
-    /**
-     * Number of reflector lobes baked for probe `i` (0 if no transfer is baked, or an open-air probe).
-     * @param {number} i probe index
-     * @returns {number}
-     */
-    probeLobeCount(i) {
-        return this.#lobeOffsets === null ? 0 : this.#lobeOffsets[i + 1] - this.#lobeOffsets[i];
-    }
-
-    /**
-     * Grow {@link #data} so it can hold at least `probeCount` probes, preserving existing contents (the new
-     * tail is zero-initialised). Geometric growth keeps incremental appends amortized O(1).
-     * @param {number} probeCount
-     */
-    #ensureCapacity(probeCount) {
-        const needed = probeCount * STRIDE;
-
-        if (needed <= this.#data.length) {
-            return;
-        }
-
-        let capacity = this.#data.length;
-        do {
-            capacity = Math.max(capacity * 2, DEFAULT_CAPACITY * STRIDE);
-        } while (capacity < needed);
-
-        const grown = new Float32Array(capacity);
-        grown.set(this.#data);
-        this.#data = grown;
-    }
-
-    /**
-     * Set probe `index`'s position. When `index === size` this APPENDS a new probe (zero reverb + zero
-     * direction) — so a field is built by writing indices 0, 1, 2, … in order; when `index < size` it moves
-     * an existing probe. Either way the nearest-lookup BVH is invalidated (positions changed).
-     * PRECONDITION: 0 ≤ index ≤ size.
-     * @param {number} index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setProbePosition(index, x, y, z) {
-        if (index === this.#size) {
-            this.#ensureCapacity(this.#size + 1);
-            this.#size++;
-
-            // a freshly appended probe starts with zero reverb + zero direction (the appended-row contract)
-            const base = index * STRIDE;
-            for (let k = OFFSET_REVERB; k < STRIDE; k++) {
-                this.#data[base + k] = 0;
-            }
-        }
-
-        const base = index * STRIDE;
-        const data = this.#data;
-
-        data[base + OFFSET_X] = x;
-        data[base + OFFSET_Y] = y;
-        data[base + OFFSET_Z] = z;
-
-        this.#bvhValid = false;
-    }
-
-    /**
-     * Set probe `index`'s per-band reverb decay (seconds). Does not move the probe, so the BVH is
-     * untouched.
-     * PRECONDITION: 0 ≤ index < size.
-     * @param {number} index
-     * @param {number} low
-     * @param {number} mid
-     * @param {number} high
-     */
-    setProbeReverbDecay(index, low, mid, high) {
-        const base = index * STRIDE + OFFSET_REVERB;
-        const data = this.#data;
-
-        data[base] = low;
-        data[base + 1] = mid;
-        data[base + 2] = high;
-    }
-
-    /**
-     * Set probe `index`'s per-band arrival direction (the FOA anisotropy vectors, band-major xyz, length 9:
-     * `[lowX,lowY,lowZ, midX,midY,midZ, highX,highY,highZ]`). Each band's magnitude is 0…1 (0 = diffuse,
-     * →1 = strongly directional). Does not move the probe, so the BVH is untouched.
-     * PRECONDITION: 0 ≤ index < size.
-     * @param {number} index
-     * @param {Float32Array|number[]} directions band-major xyz, length 9
-     */
-    setProbeReverbDirections(index, directions) {
-        const base = index * STRIDE + OFFSET_DIRECTION;
-        const data = this.#data;
-
-        for (let k = 0; k < 9; k++) {
-            data[base + k] = directions[k];
-        }
-    }
-
-    /**
-     * @param {number} i probe index
-     * @returns {number}
-     */
-    probeX(i) {
-        return this.#data[i * STRIDE + OFFSET_X];
-    }
-
-    /**
-     * @param {number} i probe index
-     * @returns {number}
-     */
-    probeY(i) {
-        return this.#data[i * STRIDE + OFFSET_Y];
-    }
-
-    /**
-     * @param {number} i probe index
-     * @returns {number}
-     */
-    probeZ(i) {
-        return this.#data[i * STRIDE + OFFSET_Z];
-    }
-
-    /**
-     * Per-band baked RT60 (seconds) of probe `i`.
-     * @param {number} i probe index
-     * @param {number} band 0 = low, 1 = mid, 2 = high
-     * @returns {number}
-     */
-    reverbBand(i, band) {
-        return this.#data[i * STRIDE + OFFSET_REVERB + band];
-    }
-
-    /**
-     * Per-band arrival direction of probe `i` (xyz) written into `out`. Magnitude 0…1 (0 = diffuse, →1 =
-     * the reverb arrives predominantly from this direction).
-     * @param {number} i probe index
-     * @param {number} band 0 = low, 1 = mid, 2 = high
-     * @param {Float32Array|number[]} out at least length 3
-     */
-    reverbDirection(i, band, out) {
-        const base = i * STRIDE + OFFSET_DIRECTION + band * 3;
-        const data = this.#data;
-
-        out[0] = data[base];
-        out[1] = data[base + 1];
-        out[2] = data[base + 2];
-    }
-
-    /**
-     * Broadband baked RT60 (seconds) of probe `i` — the mean of its three bands (the scalar render path).
-     * @param {number} i probe index
-     * @returns {number}
-     */
-    reverbDecay(i) {
-        return (this.reverbBand(i, 0) + this.reverbBand(i, 1) + this.reverbBand(i, 2)) / 3;
-    }
-
-    /**
-     * Index of the nearest probe to a world point, or -1 if the field is empty.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @returns {number}
-     */
-    nearestIndex(x, y, z) {
-        this.#ensureBVH();
-        return bvh_query_user_data_nearest_to_point(this.#bvh, x, y, z);
-    }
-
-    /**
-     * Index of the nearest probe a world point can SEE — line-of-sight unobstructed by `occluderIndex` — or
-     * -1 if the field is empty or NO probe is visible. Unlike {@link nearestIndex} this never snaps to a
-     * probe behind a wall or below a floor (a different acoustic region), which would make a runtime
-     * listener/source route a spurious cross-occluder detour through the visibility graph (or find none). The
-     * runtime pathing snaps with this. Cost: the branch-and-bound nearest search with one visibility raycast
-     * per leaf nearer than the current best — typically one or two, since the nearest probe is usually
-     * visible.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {AcousticOccluderIndex} occluderIndex the scene line-of-sight is tested against
-     * @returns {number} nearest visible probe index, or -1
-     */
-    nearestVisibleIndex(x, y, z, occluderIndex) {
-        this.#ensureBVH();
-
-        const data = this.#data;
-
-        return bvh_query_user_data_nearest_to_point_filtered(this.#bvh, x, y, z, (probeIndex) => {
-            const base = probeIndex * STRIDE;
-            const dx = data[base + OFFSET_X] - x;
-            const dy = data[base + OFFSET_Y] - y;
-            const dz = data[base + OFFSET_Z] - z;
-
-            const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
-            if (d === 0) {
-                return true; // the query point coincides with the probe — trivially visible
-            }
-
-            const inv = 1 / d;
-            VISIBILITY_RAY.setOrigin(x, y, z);
-            VISIBILITY_RAY.setDirection(dx * inv, dy * inv, dz * inv);
-            VISIBILITY_RAY.tMax = d;
-
-            return !occluderIndex.anyHit(VISIBILITY_RAY);
-        });
-    }
-
-    /**
-     * Indices of all probes within `radius` of a world point, written into `result` starting at
-     * `result_offset`; returns how many were written. Built on the same nearest-lookup BVH — used by the
-     * visibility-graph bake to find spatially-local candidate pairs (island bridging, shortcut augmentation)
-     * without an all-pairs scan. The probe leaves are points, so a hit means centre-within-radius (the BVH
-     * may return a few extra near the boundary; re-test the exact distance if you need a hard cutoff).
-     * PRECONDITION: `result` has room for the local probe count near the query (size it to the field's
-     * densest neighbourhood).
-     * @param {number[]|Uint32Array} result
-     * @param {number} result_offset
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} radius
-     * @returns {number} number of probe indices written
-     */
-    probesWithinRadius(result, result_offset, x, y, z, radius) {
-        this.#ensureBVH();
-        return bvh_query_user_data_intersects_sphere(result, result_offset, this.#bvh, x, y, z, radius);
-    }
-
-    /**
-     * Broadband reverb decay (seconds) at a world point — the nearest probe's mean RT60, or 0 if no
-     * probes.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @returns {number}
-     */
-    reverbDecayAt(x, y, z) {
-        const i = this.nearestIndex(x, y, z);
-        return i === -1 ? 0 : this.reverbDecay(i);
-    }
-
-    /**
-     * Per-band reverb decay (seconds) at a world point — the nearest probe's `[low, mid, high]` RT60s
-     * written into `out`, or all-zero if no probes.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {Float32Array|number[]} out at least length 3
-     */
-    reverbBandsAt(x, y, z, out) {
-        const i = this.nearestIndex(x, y, z);
-
-        if (i === -1) {
-            out[0] = 0;
-            out[1] = 0;
-            out[2] = 0;
-            return;
-        }
-
-        out[0] = this.reverbBand(i, 0);
-        out[1] = this.reverbBand(i, 1);
-        out[2] = this.reverbBand(i, 2);
-    }
-
-    /**
-     * Per-band arrival directions at a world point — the nearest probe's 9 floats (band-major xyz) written
-     * into `out`, or all-zero if no probes.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {Float32Array|number[]} out at least length 9
-     */
-    reverbDirectionsAt(x, y, z, out) {
-        const i = this.nearestIndex(x, y, z);
-
-        if (i === -1) {
-            for (let k = 0; k < 9; k++) {
-                out[k] = 0;
-            }
-            return;
-        }
-
-        const base = i * STRIDE + OFFSET_DIRECTION;
-        const data = this.#data;
-
-        for (let k = 0; k < 9; k++) {
-            out[k] = data[base + k];
-        }
-    }
-
-    /**
-     * (Re)build the nearest-lookup BVH from the probes — each probe a point leaf carrying its index as user
-     * data. Lazy: the runtime pays once after a bake/load, not per query.
-     */
-    #ensureBVH() {
-        if (this.#bvhValid) {
-            return;
-        }
-
-        const bvh = new BVH();
-        const data = this.#data;
-        const n = this.#size;
-
-        for (let i = 0; i < n; i++) {
-            const base = i * STRIDE;
-            const x = data[base + OFFSET_X];
-            const y = data[base + OFFSET_Y];
-            const z = data[base + OFFSET_Z];
-
-            LEAF_BOUNDS[0] = LEAF_BOUNDS[3] = x;
-            LEAF_BOUNDS[1] = LEAF_BOUNDS[4] = y;
-            LEAF_BOUNDS[2] = LEAF_BOUNDS[5] = z;
-
-            const node = bvh.allocate_node();
-            bvh.node_set_aabb(node, LEAF_BOUNDS);
-            bvh.node_set_user_data(node, i);
-            bvh.insert_leaf(node);
-        }
-
-        this.#bvh = bvh;
-        this.#bvhValid = true;
-    }
-
-    /**
-     * Attach the baked probe-visibility graph (from `bakeVisibility`), enabling {@link shortestPath} and
-     * {@link ProbeFieldPathingSolution}.
-     * PRECONDITION: the graph's vertex set is this field's probes (vertex v = probe v); bake it AFTER the
-     * field's probes are final.
-     * @param {CSRGraph} graph visibility adjacency over this field's probes
-     */
-    setVisibilityGraph(graph) {
-        this.#graph = graph;
-    }
-
-    /**
-     * Attach the baked reflector lobes (from `bakeProbeReflectors`), enabling {@link probeTransfer}.
-     * PRECONDITION: `offsets` has length `size + 1` (probe v's lobes are `offsets[v]…offsets[v+1]`) and `data`
-     * holds `offsets[size]` lobes (LOBE_STRIDE floats each). Bake AFTER the probes are final.
-     * @param {Uint32Array} offsets per-probe lobe-range offsets (length size+1)
-     * @param {Float32Array} data flat lobe array
-     */
-    setLobes(offsets, data) {
-        this.#lobeOffsets = offsets;
-        this.#lobeData = data;
-    }
-
-    /**
-     * The directional transfer T(ω_in, ω_out) at probe `i`, per band, written into `out[0..2]` (see
-     * {@link acoustic_probe_transfer}). With no lobes baked (or an open-air probe) it is the forward /
-     * passthrough term alone. Directions are unit PROPAGATION directions.
-     * @param {Float32Array|number[]} out length ≥ 3
-     * @param {number} i probe index
-     * @param {number} inx ω_in x
-     * @param {number} iny ω_in y
-     * @param {number} inz ω_in z
-     * @param {number} outx ω_out x
-     * @param {number} outy ω_out y
-     * @param {number} outz ω_out z
-     */
-    probeTransfer(out, i, inx, iny, inz, outx, outy, outz) {
-        const offsets = this.#lobeOffsets;
-        const start = offsets === null ? 0 : offsets[i];
-        const count = offsets === null ? 0 : offsets[i + 1] - start;
-
-        acoustic_probe_transfer(out, this.#lobeData ?? EMPTY_LOBES, start * LOBE_STRIDE, count, inx, iny, inz, outx, outy, outz);
-    }
-
-    /**
-     * Shortest path (Dijkstra) from probe `from` to probe `to`, as a list of probe indices (inclusive of
-     * both ends), or null if they are not connected.
-     * PRECONDITION: a visibility graph is attached ({@link hasVisibility}).
-     * @param {number} from
-     * @param {number} to
-     * @returns {number[]|null}
-     */
-    shortestPath(from, to) {
-        const path = [];
-
-        const count = csr_graph_find_shortest_path(path, 0, this.#graph, from, to);
-
-        return count === -1 ? null : path;
-    }
-
-    toJSON() {
-        const data = this.#data;
-        const probes = [];
-
-        for (let i = 0; i < this.#size; i++) {
-            const base = i * STRIDE;
-
-            const reverbDirection = [];
-            for (let k = 0; k < 9; k++) {
-                reverbDirection.push(data[base + OFFSET_DIRECTION + k]);
-            }
-
-            probes.push({
-                x: data[base + OFFSET_X],
-                y: data[base + OFFSET_Y],
-                z: data[base + OFFSET_Z],
-                reverbDecay: [
-                    data[base + OFFSET_REVERB],
-                    data[base + OFFSET_REVERB + 1],
-                    data[base + OFFSET_REVERB + 2]
-                ],
-                reverbDirection
-            });
-        }
-
-        return { probes };
-    }
-
-    /**
-     * Replace this field's probes from serialized form. The visibility graph is NOT serialized (re-bake it
-     * with `bakeVisibility` after loading), so any prior graph is dropped.
-     * @param {{probes:{x:number,y:number,z:number,reverbDecay:number[],reverbDirection:number[]}[]}} json
-     */
-    fromJSON(json) {
-        const probes = json.probes;
-        const n = probes.length;
-
-        this.#data = new Float32Array(Math.max(n, DEFAULT_CAPACITY) * STRIDE);
-        this.#size = 0;
-        this.#bvhValid = false;
-        this.#graph = null;
-        this.#lobeOffsets = null;
-        this.#lobeData = null;
-
-        for (let i = 0; i < n; i++) {
-            const p = probes[i];
-            const r = p.reverbDecay;
-            this.setProbePosition(i, p.x, p.y, p.z);
-            this.setProbeReverbDecay(i, r[0], r[1], r[2]);
-            this.setProbeReverbDirections(i, p.reverbDirection);
-        }
-    }
-}
-
-AcousticProbeField.typeName = "AcousticProbeField";
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import {
+    bvh_query_user_data_nearest_to_point
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point.js";
+import {
+    bvh_query_user_data_intersects_sphere
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_sphere.js";
+import {
+    bvh_query_user_data_nearest_to_point_filtered
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point_filtered.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { csr_graph_find_shortest_path } from "../../../../core/graph/csr/csr_graph_find_shortest_path.js";
+import { acoustic_probe_transfer, LOBE_STRIDE } from "./acoustic_probe_transfer.js";
+
+// Probe layout in #data: STRIDE float32s per probe — position, per-band reverb RT60, per-band arrival dir.
+const STRIDE = 15;
+const OFFSET_X = 0;
+const OFFSET_Y = 1;
+const OFFSET_Z = 2;
+const OFFSET_REVERB = 3;    // per-band RT60 (seconds): band b at OFFSET_REVERB + b              — 3 floats
+const OFFSET_DIRECTION = 6; // per-band arrival direction (xyz): band b at OFFSET_DIRECTION + b*3 — 9 floats
+
+// passed as the lobe store for a probe with no lobes baked — never indexed (count 0), but keeps a real array
+// off the transfer call rather than null
+const EMPTY_LOBES = new Float32Array(0);
+
+// initial probe capacity of a fresh field's backing array
+const DEFAULT_CAPACITY = 8;
+
+// module scratch for a point-leaf AABB during BVH build
+const LEAF_BOUNDS = new Float32Array(6);
+
+// module scratch — the query→probe line-of-sight ray for nearestVisibleIndex
+const VISIBILITY_RAY = new Ray3();
+
+/**
+ * The baked probe volume: the set of acoustic probes covering a scene, plus the connectivity between them.
+ * Carries everything an offline bake produces about the field and everything the runtime reads back from
+ * it — per-band reverb, BVH nearest-probe lookup, and (optionally) the probe-visibility graph that sound
+ * routes through. Serializable (the bake is offline; the field loads as an asset). Pure data + graph
+ * search; no WebAudio.
+ *
+ * Probe data lives in a flat {@link Float32Array} ({@link STRIDE} floats per probe: x, y, z, per-band
+ * reverbDecay, per-band arrival direction) indexed by `i*STRIDE` — no per-probe object, no table
+ * indirection. The per-band arrival direction is the FOA / first-order anisotropy vector a directional
+ * reverb renderer steers the wet field by. Nearest-probe lookup is
+ * BVH-accelerated: a {@link BVH} over the probe points (leaf user-data = probe index) is built lazily and
+ * queried with {@link bvh_query_user_data_nearest_to_point}, so a per-frame listener query is O(log n)
+ * rather than a full scan.
+ *
+ * Connectivity is an inherent property of the field: once `bakeVisibility` has connected the probes with
+ * mutual line-of-sight ({@link setVisibilityGraph}), {@link shortestPath} routes sound around obstacles —
+ * through doorways and around corners — independent of walkability (air-visibility, not a navmesh). The
+ * mutable, per-listener exit-field solve lives in a separate {@link ProbeFieldPathingSolution} — this baked
+ * field stays immutable data + the graph it owns.
+ */
+export class AcousticProbeField {
+    /**
+     * Flat probe storage, {@link STRIDE} float32s per probe:
+     * `[x, y, z, reverbLow, reverbMid, reverbHigh, dirLowXYZ, dirMidXYZ, dirHighXYZ]`.
+     * Probe `i` occupies `[i*STRIDE … i*STRIDE + STRIDE)`. Backing length is the capacity, not the size.
+     * @type {Float32Array}
+     */
+    #data = new Float32Array(DEFAULT_CAPACITY * STRIDE);
+
+    /**
+     * Number of probes (distinct from the backing array's length).
+     * @type {number}
+     */
+    #size = 0;
+
+    /**
+     * Nearest-lookup acceleration over the probe points; rebuilt lazily after the field changes.
+     * @type {BVH}
+     */
+    #bvh = new BVH();
+
+    /**
+     * Whether {@link #bvh} reflects the current probes (false after a position change).
+     * @type {boolean}
+     */
+    #bvhValid = false;
+
+    /**
+     * Probe-visibility adjacency for pathing: vertex v = probe v, edge = mutual line-of-sight, edge weight =
+     * inter-probe distance. Baked by `bakeVisibility` and attached via {@link setVisibilityGraph}; null
+     * until then — a field without connectivity still serves reverb and nearest lookup.
+     * @type {CSRGraph|null}
+     */
+    #graph = null;
+
+    /**
+     * Per-probe reflector lobes for the directional TRANSFER (corner-leak gating), in CSR form:
+     * {@link #lobeOffsets}`[v]…[v+1]` is probe v's lobe range in {@link #lobeData} (LOBE_STRIDE floats each).
+     * Baked by `bakeProbeReflectors` and attached via {@link setLobes}; both null until then (a field without
+     * transfer routes with the forward/passthrough term only). Like the visibility graph, a bake product —
+     * NOT serialized; re-bake after load.
+     * @type {Uint32Array|null}
+     */
+    #lobeOffsets = null;
+
+    /**
+     * Flat lobe storage (LOBE_STRIDE floats per lobe), indexed via {@link #lobeOffsets}. Null until baked.
+     * @type {Float32Array|null}
+     */
+    #lobeData = null;
+
+    /**
+     * @returns {number} number of probes
+     */
+    get size() {
+        return this.#size;
+    }
+
+    /**
+     * Whether a visibility graph has been baked into this field (i.e. pathing is available).
+     * @returns {boolean}
+     */
+    get hasVisibility() {
+        return this.#graph !== null;
+    }
+
+    /**
+     * The baked probe-visibility graph, or null if none has been baked. The substrate that
+     * {@link shortestPath} and a {@link ProbeFieldPathingSolution} search.
+     * @returns {CSRGraph|null}
+     */
+    get visibilityGraph() {
+        return this.#graph;
+    }
+
+    /**
+     * Whether reflector lobes (the directional transfer) have been baked into this field.
+     * @returns {boolean}
+     */
+    get hasTransfer() {
+        return this.#lobeOffsets !== null;
+    }
+
+    /**
+     * Number of reflector lobes baked for probe `i` (0 if no transfer is baked, or an open-air probe).
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeLobeCount(i) {
+        return this.#lobeOffsets === null ? 0 : this.#lobeOffsets[i + 1] - this.#lobeOffsets[i];
+    }
+
+    /**
+     * Grow {@link #data} so it can hold at least `probeCount` probes, preserving existing contents (the new
+     * tail is zero-initialised). Geometric growth keeps incremental appends amortized O(1).
+     * @param {number} probeCount
+     */
+    #ensureCapacity(probeCount) {
+        const needed = probeCount * STRIDE;
+
+        if (needed <= this.#data.length) {
+            return;
+        }
+
+        let capacity = this.#data.length;
+        do {
+            capacity = Math.max(capacity * 2, DEFAULT_CAPACITY * STRIDE);
+        } while (capacity < needed);
+
+        const grown = new Float32Array(capacity);
+        grown.set(this.#data);
+        this.#data = grown;
+    }
+
+    /**
+     * Set probe `index`'s position. When `index === size` this APPENDS a new probe (zero reverb + zero
+     * direction) — so a field is built by writing indices 0, 1, 2, … in order; when `index < size` it moves
+     * an existing probe. Either way the nearest-lookup BVH is invalidated (positions changed).
+     * PRECONDITION: 0 ≤ index ≤ size.
+     * @param {number} index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setProbePosition(index, x, y, z) {
+        if (index === this.#size) {
+            this.#ensureCapacity(this.#size + 1);
+            this.#size++;
+
+            // a freshly appended probe starts with zero reverb + zero direction (the appended-row contract)
+            const base = index * STRIDE;
+            for (let k = OFFSET_REVERB; k < STRIDE; k++) {
+                this.#data[base + k] = 0;
+            }
+        }
+
+        const base = index * STRIDE;
+        const data = this.#data;
+
+        data[base + OFFSET_X] = x;
+        data[base + OFFSET_Y] = y;
+        data[base + OFFSET_Z] = z;
+
+        this.#bvhValid = false;
+    }
+
+    /**
+     * Set probe `index`'s per-band reverb decay (seconds). Does not move the probe, so the BVH is
+     * untouched.
+     * PRECONDITION: 0 ≤ index < size.
+     * @param {number} index
+     * @param {number} low
+     * @param {number} mid
+     * @param {number} high
+     */
+    setProbeReverbDecay(index, low, mid, high) {
+        const base = index * STRIDE + OFFSET_REVERB;
+        const data = this.#data;
+
+        data[base] = low;
+        data[base + 1] = mid;
+        data[base + 2] = high;
+    }
+
+    /**
+     * Set probe `index`'s per-band arrival direction (the FOA anisotropy vectors, band-major xyz, length 9:
+     * `[lowX,lowY,lowZ, midX,midY,midZ, highX,highY,highZ]`). Each band's magnitude is 0…1 (0 = diffuse,
+     * →1 = strongly directional). Does not move the probe, so the BVH is untouched.
+     * PRECONDITION: 0 ≤ index < size.
+     * @param {number} index
+     * @param {Float32Array|number[]} directions band-major xyz, length 9
+     */
+    setProbeReverbDirections(index, directions) {
+        const base = index * STRIDE + OFFSET_DIRECTION;
+        const data = this.#data;
+
+        for (let k = 0; k < 9; k++) {
+            data[base + k] = directions[k];
+        }
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeX(i) {
+        return this.#data[i * STRIDE + OFFSET_X];
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeY(i) {
+        return this.#data[i * STRIDE + OFFSET_Y];
+    }
+
+    /**
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    probeZ(i) {
+        return this.#data[i * STRIDE + OFFSET_Z];
+    }
+
+    /**
+     * Per-band baked RT60 (seconds) of probe `i`.
+     * @param {number} i probe index
+     * @param {number} band 0 = low, 1 = mid, 2 = high
+     * @returns {number}
+     */
+    reverbBand(i, band) {
+        return this.#data[i * STRIDE + OFFSET_REVERB + band];
+    }
+
+    /**
+     * Per-band arrival direction of probe `i` (xyz) written into `out`. Magnitude 0…1 (0 = diffuse, →1 =
+     * the reverb arrives predominantly from this direction).
+     * @param {number} i probe index
+     * @param {number} band 0 = low, 1 = mid, 2 = high
+     * @param {Float32Array|number[]} out at least length 3
+     */
+    reverbDirection(i, band, out) {
+        const base = i * STRIDE + OFFSET_DIRECTION + band * 3;
+        const data = this.#data;
+
+        out[0] = data[base];
+        out[1] = data[base + 1];
+        out[2] = data[base + 2];
+    }
+
+    /**
+     * Broadband baked RT60 (seconds) of probe `i` — the mean of its three bands (the scalar render path).
+     * @param {number} i probe index
+     * @returns {number}
+     */
+    reverbDecay(i) {
+        return (this.reverbBand(i, 0) + this.reverbBand(i, 1) + this.reverbBand(i, 2)) / 3;
+    }
+
+    /**
+     * Index of the nearest probe to a world point, or -1 if the field is empty.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    nearestIndex(x, y, z) {
+        this.#ensureBVH();
+        return bvh_query_user_data_nearest_to_point(this.#bvh, x, y, z);
+    }
+
+    /**
+     * Index of the nearest probe a world point can SEE — line-of-sight unobstructed by `occluderIndex` — or
+     * -1 if the field is empty or NO probe is visible. Unlike {@link nearestIndex} this never snaps to a
+     * probe behind a wall or below a floor (a different acoustic region), which would make a runtime
+     * listener/source route a spurious cross-occluder detour through the visibility graph (or find none). The
+     * runtime pathing snaps with this. Cost: the branch-and-bound nearest search with one visibility raycast
+     * per leaf nearer than the current best — typically one or two, since the nearest probe is usually
+     * visible.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {AcousticOccluderIndex} occluderIndex the scene line-of-sight is tested against
+     * @returns {number} nearest visible probe index, or -1
+     */
+    nearestVisibleIndex(x, y, z, occluderIndex) {
+        this.#ensureBVH();
+
+        const data = this.#data;
+
+        return bvh_query_user_data_nearest_to_point_filtered(this.#bvh, x, y, z, (probeIndex) => {
+            const base = probeIndex * STRIDE;
+            const dx = data[base + OFFSET_X] - x;
+            const dy = data[base + OFFSET_Y] - y;
+            const dz = data[base + OFFSET_Z] - z;
+
+            const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (d === 0) {
+                return true; // the query point coincides with the probe — trivially visible
+            }
+
+            const inv = 1 / d;
+            VISIBILITY_RAY.setOrigin(x, y, z);
+            VISIBILITY_RAY.setDirection(dx * inv, dy * inv, dz * inv);
+            VISIBILITY_RAY.tMax = d;
+
+            return !occluderIndex.anyHit(VISIBILITY_RAY);
+        });
+    }
+
+    /**
+     * Indices of all probes within `radius` of a world point, written into `result` starting at
+     * `result_offset`; returns how many were written. Built on the same nearest-lookup BVH — used by the
+     * visibility-graph bake to find spatially-local candidate pairs (island bridging, shortcut augmentation)
+     * without an all-pairs scan. The probe leaves are points, so a hit means centre-within-radius (the BVH
+     * may return a few extra near the boundary; re-test the exact distance if you need a hard cutoff).
+     * PRECONDITION: `result` has room for the local probe count near the query (size it to the field's
+     * densest neighbourhood).
+     * @param {number[]|Uint32Array} result
+     * @param {number} result_offset
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} radius
+     * @returns {number} number of probe indices written
+     */
+    probesWithinRadius(result, result_offset, x, y, z, radius) {
+        this.#ensureBVH();
+        return bvh_query_user_data_intersects_sphere(result, result_offset, this.#bvh, x, y, z, radius);
+    }
+
+    /**
+     * Broadband reverb decay (seconds) at a world point — the nearest probe's mean RT60, or 0 if no
+     * probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    reverbDecayAt(x, y, z) {
+        const i = this.nearestIndex(x, y, z);
+        return i === -1 ? 0 : this.reverbDecay(i);
+    }
+
+    /**
+     * Per-band reverb decay (seconds) at a world point — the nearest probe's `[low, mid, high]` RT60s
+     * written into `out`, or all-zero if no probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {Float32Array|number[]} out at least length 3
+     */
+    reverbBandsAt(x, y, z, out) {
+        const i = this.nearestIndex(x, y, z);
+
+        if (i === -1) {
+            out[0] = 0;
+            out[1] = 0;
+            out[2] = 0;
+            return;
+        }
+
+        out[0] = this.reverbBand(i, 0);
+        out[1] = this.reverbBand(i, 1);
+        out[2] = this.reverbBand(i, 2);
+    }
+
+    /**
+     * Per-band arrival directions at a world point — the nearest probe's 9 floats (band-major xyz) written
+     * into `out`, or all-zero if no probes.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {Float32Array|number[]} out at least length 9
+     */
+    reverbDirectionsAt(x, y, z, out) {
+        const i = this.nearestIndex(x, y, z);
+
+        if (i === -1) {
+            for (let k = 0; k < 9; k++) {
+                out[k] = 0;
+            }
+            return;
+        }
+
+        const base = i * STRIDE + OFFSET_DIRECTION;
+        const data = this.#data;
+
+        for (let k = 0; k < 9; k++) {
+            out[k] = data[base + k];
+        }
+    }
+
+    /**
+     * (Re)build the nearest-lookup BVH from the probes — each probe a point leaf carrying its index as user
+     * data. Lazy: the runtime pays once after a bake/load, not per query.
+     */
+    #ensureBVH() {
+        if (this.#bvhValid) {
+            return;
+        }
+
+        const bvh = new BVH();
+        const data = this.#data;
+        const n = this.#size;
+
+        for (let i = 0; i < n; i++) {
+            const base = i * STRIDE;
+            const x = data[base + OFFSET_X];
+            const y = data[base + OFFSET_Y];
+            const z = data[base + OFFSET_Z];
+
+            LEAF_BOUNDS[0] = LEAF_BOUNDS[3] = x;
+            LEAF_BOUNDS[1] = LEAF_BOUNDS[4] = y;
+            LEAF_BOUNDS[2] = LEAF_BOUNDS[5] = z;
+
+            const node = bvh.allocate_node();
+            bvh.node_set_aabb(node, LEAF_BOUNDS);
+            bvh.node_set_user_data(node, i);
+            bvh.insert_leaf(node);
+        }
+
+        this.#bvh = bvh;
+        this.#bvhValid = true;
+    }
+
+    /**
+     * Attach the baked probe-visibility graph (from `bakeVisibility`), enabling {@link shortestPath} and
+     * {@link ProbeFieldPathingSolution}.
+     * PRECONDITION: the graph's vertex set is this field's probes (vertex v = probe v); bake it AFTER the
+     * field's probes are final.
+     * @param {CSRGraph} graph visibility adjacency over this field's probes
+     */
+    setVisibilityGraph(graph) {
+        this.#graph = graph;
+    }
+
+    /**
+     * Attach the baked reflector lobes (from `bakeProbeReflectors`), enabling {@link probeTransfer}.
+     * PRECONDITION: `offsets` has length `size + 1` (probe v's lobes are `offsets[v]…offsets[v+1]`) and `data`
+     * holds `offsets[size]` lobes (LOBE_STRIDE floats each). Bake AFTER the probes are final.
+     * @param {Uint32Array} offsets per-probe lobe-range offsets (length size+1)
+     * @param {Float32Array} data flat lobe array
+     */
+    setLobes(offsets, data) {
+        this.#lobeOffsets = offsets;
+        this.#lobeData = data;
+    }
+
+    /**
+     * The directional transfer T(ω_in, ω_out) at probe `i`, per band, written into `out[0..2]` (see
+     * {@link acoustic_probe_transfer}). With no lobes baked (or an open-air probe) it is the forward /
+     * passthrough term alone. Directions are unit PROPAGATION directions.
+     * @param {Float32Array|number[]} out length ≥ 3
+     * @param {number} i probe index
+     * @param {number} inx ω_in x
+     * @param {number} iny ω_in y
+     * @param {number} inz ω_in z
+     * @param {number} outx ω_out x
+     * @param {number} outy ω_out y
+     * @param {number} outz ω_out z
+     */
+    probeTransfer(out, i, inx, iny, inz, outx, outy, outz) {
+        const offsets = this.#lobeOffsets;
+        const start = offsets === null ? 0 : offsets[i];
+        const count = offsets === null ? 0 : offsets[i + 1] - start;
+
+        acoustic_probe_transfer(out, this.#lobeData ?? EMPTY_LOBES, start * LOBE_STRIDE, count, inx, iny, inz, outx, outy, outz);
+    }
+
+    /**
+     * Shortest path (Dijkstra) from probe `from` to probe `to`, as a list of probe indices (inclusive of
+     * both ends), or null if they are not connected.
+     * PRECONDITION: a visibility graph is attached ({@link hasVisibility}).
+     * @param {number} from
+     * @param {number} to
+     * @returns {number[]|null}
+     */
+    shortestPath(from, to) {
+        const path = [];
+
+        const count = csr_graph_find_shortest_path(path, 0, this.#graph, from, to);
+
+        return count === -1 ? null : path;
+    }
+
+    toJSON() {
+        const data = this.#data;
+        const probes = [];
+
+        for (let i = 0; i < this.#size; i++) {
+            const base = i * STRIDE;
+
+            const reverbDirection = [];
+            for (let k = 0; k < 9; k++) {
+                reverbDirection.push(data[base + OFFSET_DIRECTION + k]);
+            }
+
+            probes.push({
+                x: data[base + OFFSET_X],
+                y: data[base + OFFSET_Y],
+                z: data[base + OFFSET_Z],
+                reverbDecay: [
+                    data[base + OFFSET_REVERB],
+                    data[base + OFFSET_REVERB + 1],
+                    data[base + OFFSET_REVERB + 2]
+                ],
+                reverbDirection
+            });
+        }
+
+        return { probes };
+    }
+
+    /**
+     * Replace this field's probes from serialized form. The visibility graph is NOT serialized (re-bake it
+     * with `bakeVisibility` after loading), so any prior graph is dropped.
+     * @param {{probes:{x:number,y:number,z:number,reverbDecay:number[],reverbDirection:number[]}[]}} json
+     */
+    fromJSON(json) {
+        const probes = json.probes;
+        const n = probes.length;
+
+        this.#data = new Float32Array(Math.max(n, DEFAULT_CAPACITY) * STRIDE);
+        this.#size = 0;
+        this.#bvhValid = false;
+        this.#graph = null;
+        this.#lobeOffsets = null;
+        this.#lobeData = null;
+
+        for (let i = 0; i < n; i++) {
+            const p = probes[i];
+            const r = p.reverbDecay;
+            this.setProbePosition(i, p.x, p.y, p.z);
+            this.setProbeReverbDecay(i, r[0], r[1], r[2]);
+            this.setProbeReverbDirections(i, p.reverbDirection);
+        }
+    }
+}
+
+AcousticProbeField.typeName = "AcousticProbeField";