@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,171 +1,171 @@
-import { clamp } from "../../../../core/math/clamp.js";
-import { lerp } from "../../../../core/math/lerp.js";
-import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
-
-// Voxel grid is finer than the spacing hint so it resolves sub-`minSpacing` features (thin corridors).
-export const OVERSAMPLE = 2;
-// Per-axis voxel resolution is capped so the SDF grid stays bounded (256³ f32 ≈ 64 MB).
-export const RESOLUTION_LIMIT = 256;
-// Open halls get probes at most this multiple of `minSpacing` apart (the sparseness ceiling + the SDF query
-// cutoff — beyond it "very open" is good enough).
-export const DEFAULT_SPARSENESS_RATIO = 4;
-
-const ASCENT_ITERATIONS = 5;
-const ASCENT_RATE = 0.2;
-
-/**
- * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
- * ({@link probe_place_sdf_cover}) and portal detection ({@link probe_detect_portals}) so the expensive
- * {@link AcousticOccluderIndex#signedDistanceAt} sweep (up to 256³ queries) is paid once.
- *
- * @typedef {Object} SdfGrid
- * @property {Float32Array} sdf per-voxel signed distance (world units), capped at `maxSpacing`
- * @property {number} rx @property {number} ry @property {number} rz per-axis voxel resolution
- * @property {number} strideZ `rx·ry` @property {number} total `strideZ·rz`
- * @property {number} x0 @property {number} y0 @property {number} z0 region min corner
- * @property {number} x1 @property {number} y1 @property {number} z1 region max corner
- * @property {number} vsX @property {number} vsY @property {number} vsZ per-axis voxel size (0 if degenerate)
- * @property {number} minSpacing @property {number} maxSpacing the spacing hint + sparseness ceiling
- * @property {number} clearanceFloor a voxel above this SDF is "open air" (off any surface)
- */
-
-/**
- * Build a signed distance field on a voxel grid over `bounds` by sampling
- * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
- * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
- *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
- * @param {number} minSpacing the probe spacing hint
- * @param {number} [sparsenessRatio]
- * @returns {SdfGrid}
- */
-export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFAULT_SPARSENESS_RATIO) {
-    const maxSpacing = minSpacing * sparsenessRatio;
-
-    const x0 = bounds[0], y0 = bounds[1], z0 = bounds[2];
-    const x1 = bounds[3], y1 = bounds[4], z1 = bounds[5];
-
-    const extX = x1 - x0, extY = y1 - y0, extZ = z1 - z0;
-
-    const voxel = minSpacing / OVERSAMPLE;
-    const rx = clamp(Math.ceil(extX / voxel) + 1, 2, RESOLUTION_LIMIT);
-    const ry = clamp(Math.ceil(extY / voxel) + 1, 2, RESOLUTION_LIMIT);
-    const rz = clamp(Math.ceil(extZ / voxel) + 1, 2, RESOLUTION_LIMIT);
-
-    // actual per-axis voxel size (probe positions lerp over [0, res-1])
-    const vsX = extX / (rx - 1);
-    const vsY = extY / (ry - 1);
-    const vsZ = extZ / (rz - 1);
-
-    const strideZ = rx * ry;
-    const total = strideZ * rz;
-
-    const sdf = new Float32Array(total);
-    for (let zi = 0; zi < rz; zi++) {
-        const z = lerp(z0, z1, zi / (rz - 1));
-        for (let yi = 0; yi < ry; yi++) {
-            const y = lerp(y0, y1, yi / (ry - 1));
-            for (let xi = 0; xi < rx; xi++) {
-                const x = lerp(x0, x1, xi / (rx - 1));
-                sdf[zi * strideZ + yi * rx + xi] = index.signedDistanceAt(x, y, z, maxSpacing);
-            }
-        }
-    }
-
-    // "open air" = off any surface by ~½ a NOMINAL voxel. Based on the spacing hint, NOT the actual per-axis
-    // voxel size: a degenerate (zero-extent) axis can't zero it, and the resolution cap can't inflate it past
-    // maxSpacing (which would reject every voxel).
-    const clearanceFloor = (minSpacing / OVERSAMPLE) * 0.5;
-
-    return {
-        sdf, rx, ry, rz, strideZ, total,
-        x0, y0, z0, x1, y1, z1,
-        vsX, vsY, vsZ,
-        minSpacing, maxSpacing, clearanceFloor,
-    };
-}
-
-/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
-export function grid_voxel_to_world(grid, out, fx, fy, fz) {
-    out[0] = grid.x0 + fx * grid.vsX;
-    out[1] = grid.y0 + fy * grid.vsY;
-    out[2] = grid.z0 + fz * grid.vsZ;
-}
-
-/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
-export function grid_sample_world(grid, x, y, z) {
-    const fx = grid.vsX > 0 ? (x - grid.x0) / grid.vsX : 0;
-    const fy = grid.vsY > 0 ? (y - grid.y0) / grid.vsY : 0;
-    const fz = grid.vsZ > 0 ? (z - grid.z0) / grid.vsZ : 0;
-    return grid_sample_trilinear(grid, fx, fy, fz);
-}
-
-/**
- * Trilinear sample of the SDF grid at fractional voxel coordinates (edge-clamped).
- *
- * The grid is a plain `z·(rx·ry) + y·rx + x` single-channel Float32 volume — exactly the layout
- * {@link scs3d_sample_linear} samples — so the interpolation is delegated rather than re-derived here.
- * (Same clamp semantics: clamping the COORDINATE into `[0, res-1]` and clamping the two sample INDICES
- * agree on every input, including out-of-range coordinates, where both collapse to the edge voxel.)
- */
-export function grid_sample_trilinear(grid, x, y, z) {
-    return scs3d_sample_linear(grid.sdf, grid.rx, grid.ry, grid.rz, x, y, z);
-}
-
-/**
- * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
- * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
- * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
- */
-export function grid_local_maximum(out, grid, vx, vy, vz) {
-    const minX = vx - 0.4999, maxX = vx + 0.4999;
-    const minY = vy - 0.4999, maxY = vy + 0.4999;
-    const minZ = vz - 0.4999, maxZ = vz + 0.4999;
-
-    let cx = vx, cy = vy, cz = vz;
-    const e = 0.001;
-
-    for (let i = 0; i < ASCENT_ITERATIONS; i++) {
-        const gx = grid_sample_trilinear(grid, cx + e, cy, cz) - grid_sample_trilinear(grid, cx - e, cy, cz);
-        const gy = grid_sample_trilinear(grid, cx, cy + e, cz) - grid_sample_trilinear(grid, cx, cy - e, cz);
-        const gz = grid_sample_trilinear(grid, cx, cy, cz + e) - grid_sample_trilinear(grid, cx, cy, cz - e);
-
-        cx = clamp(cx + gx * ASCENT_RATE, minX, maxX);
-        cy = clamp(cy + gy * ASCENT_RATE, minY, maxY);
-        cz = clamp(cz + gz * ASCENT_RATE, minZ, maxZ);
-    }
-
-    out[0] = cx;
-    out[1] = cy;
-    out[2] = cz;
-}
-
-/**
- * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
- * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
- */
-export function grid_claim_sphere(claimed, grid, px, py, pz, radius) {
-    const { rx, ry, rz, strideZ, x0, y0, z0, vsX, vsY, vsZ } = grid;
-    const r2 = radius * radius;
-
-    const xlo = vsX > 0 ? Math.max(0, Math.floor((px - x0 - radius) / vsX)) : 0;
-    const xhi = vsX > 0 ? Math.min(rx - 1, Math.ceil((px - x0 + radius) / vsX)) : rx - 1;
-    const ylo = vsY > 0 ? Math.max(0, Math.floor((py - y0 - radius) / vsY)) : 0;
-    const yhi = vsY > 0 ? Math.min(ry - 1, Math.ceil((py - y0 + radius) / vsY)) : ry - 1;
-    const zlo = vsZ > 0 ? Math.max(0, Math.floor((pz - z0 - radius) / vsZ)) : 0;
-    const zhi = vsZ > 0 ? Math.min(rz - 1, Math.ceil((pz - z0 + radius) / vsZ)) : rz - 1;
-
-    for (let zi = zlo; zi <= zhi; zi++) {
-        const dz = (vsZ > 0 ? z0 + zi * vsZ : z0) - pz;
-        for (let yi = ylo; yi <= yhi; yi++) {
-            const dy = (vsY > 0 ? y0 + yi * vsY : y0) - py;
-            for (let xi = xlo; xi <= xhi; xi++) {
-                const dx = (vsX > 0 ? x0 + xi * vsX : x0) - px;
-                if (dx * dx + dy * dy + dz * dz <= r2) {
-                    claimed[zi * strideZ + yi * rx + xi] = 1;
-                }
-            }
-        }
-    }
-}
+import { clamp } from "../../../../core/math/clamp.js";
+import { lerp } from "../../../../core/math/lerp.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+
+// Voxel grid is finer than the spacing hint so it resolves sub-`minSpacing` features (thin corridors).
+export const OVERSAMPLE = 2;
+// Per-axis voxel resolution is capped so the SDF grid stays bounded (256³ f32 ≈ 64 MB).
+export const RESOLUTION_LIMIT = 256;
+// Open halls get probes at most this multiple of `minSpacing` apart (the sparseness ceiling + the SDF query
+// cutoff — beyond it "very open" is good enough).
+export const DEFAULT_SPARSENESS_RATIO = 4;
+
+const ASCENT_ITERATIONS = 5;
+const ASCENT_RATE = 0.2;
+
+/**
+ * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
+ * ({@link probe_place_sdf_cover}) and portal detection ({@link probe_detect_portals}) so the expensive
+ * {@link AcousticOccluderIndex#signedDistanceAt} sweep (up to 256³ queries) is paid once.
+ *
+ * @typedef {Object} SdfGrid
+ * @property {Float32Array} sdf per-voxel signed distance (world units), capped at `maxSpacing`
+ * @property {number} rx @property {number} ry @property {number} rz per-axis voxel resolution
+ * @property {number} strideZ `rx·ry` @property {number} total `strideZ·rz`
+ * @property {number} x0 @property {number} y0 @property {number} z0 region min corner
+ * @property {number} x1 @property {number} y1 @property {number} z1 region max corner
+ * @property {number} vsX @property {number} vsY @property {number} vsZ per-axis voxel size (0 if degenerate)
+ * @property {number} minSpacing @property {number} maxSpacing the spacing hint + sparseness ceiling
+ * @property {number} clearanceFloor a voxel above this SDF is "open air" (off any surface)
+ */
+
+/**
+ * Build a signed distance field on a voxel grid over `bounds` by sampling
+ * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
+ * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
+ * @param {number} minSpacing the probe spacing hint
+ * @param {number} [sparsenessRatio]
+ * @returns {SdfGrid}
+ */
+export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFAULT_SPARSENESS_RATIO) {
+    const maxSpacing = minSpacing * sparsenessRatio;
+
+    const x0 = bounds[0], y0 = bounds[1], z0 = bounds[2];
+    const x1 = bounds[3], y1 = bounds[4], z1 = bounds[5];
+
+    const extX = x1 - x0, extY = y1 - y0, extZ = z1 - z0;
+
+    const voxel = minSpacing / OVERSAMPLE;
+    const rx = clamp(Math.ceil(extX / voxel) + 1, 2, RESOLUTION_LIMIT);
+    const ry = clamp(Math.ceil(extY / voxel) + 1, 2, RESOLUTION_LIMIT);
+    const rz = clamp(Math.ceil(extZ / voxel) + 1, 2, RESOLUTION_LIMIT);
+
+    // actual per-axis voxel size (probe positions lerp over [0, res-1])
+    const vsX = extX / (rx - 1);
+    const vsY = extY / (ry - 1);
+    const vsZ = extZ / (rz - 1);
+
+    const strideZ = rx * ry;
+    const total = strideZ * rz;
+
+    const sdf = new Float32Array(total);
+    for (let zi = 0; zi < rz; zi++) {
+        const z = lerp(z0, z1, zi / (rz - 1));
+        for (let yi = 0; yi < ry; yi++) {
+            const y = lerp(y0, y1, yi / (ry - 1));
+            for (let xi = 0; xi < rx; xi++) {
+                const x = lerp(x0, x1, xi / (rx - 1));
+                sdf[zi * strideZ + yi * rx + xi] = index.signedDistanceAt(x, y, z, maxSpacing);
+            }
+        }
+    }
+
+    // "open air" = off any surface by ~½ a NOMINAL voxel. Based on the spacing hint, NOT the actual per-axis
+    // voxel size: a degenerate (zero-extent) axis can't zero it, and the resolution cap can't inflate it past
+    // maxSpacing (which would reject every voxel).
+    const clearanceFloor = (minSpacing / OVERSAMPLE) * 0.5;
+
+    return {
+        sdf, rx, ry, rz, strideZ, total,
+        x0, y0, z0, x1, y1, z1,
+        vsX, vsY, vsZ,
+        minSpacing, maxSpacing, clearanceFloor,
+    };
+}
+
+/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
+export function grid_voxel_to_world(grid, out, fx, fy, fz) {
+    out[0] = grid.x0 + fx * grid.vsX;
+    out[1] = grid.y0 + fy * grid.vsY;
+    out[2] = grid.z0 + fz * grid.vsZ;
+}
+
+/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
+export function grid_sample_world(grid, x, y, z) {
+    const fx = grid.vsX > 0 ? (x - grid.x0) / grid.vsX : 0;
+    const fy = grid.vsY > 0 ? (y - grid.y0) / grid.vsY : 0;
+    const fz = grid.vsZ > 0 ? (z - grid.z0) / grid.vsZ : 0;
+    return grid_sample_trilinear(grid, fx, fy, fz);
+}
+
+/**
+ * Trilinear sample of the SDF grid at fractional voxel coordinates (edge-clamped).
+ *
+ * The grid is a plain `z·(rx·ry) + y·rx + x` single-channel Float32 volume — exactly the layout
+ * {@link scs3d_sample_linear} samples — so the interpolation is delegated rather than re-derived here.
+ * (Same clamp semantics: clamping the COORDINATE into `[0, res-1]` and clamping the two sample INDICES
+ * agree on every input, including out-of-range coordinates, where both collapse to the edge voxel.)
+ */
+export function grid_sample_trilinear(grid, x, y, z) {
+    return scs3d_sample_linear(grid.sdf, grid.rx, grid.ry, grid.rz, x, y, z);
+}
+
+/**
+ * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
+ * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
+ * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
+ */
+export function grid_local_maximum(out, grid, vx, vy, vz) {
+    const minX = vx - 0.4999, maxX = vx + 0.4999;
+    const minY = vy - 0.4999, maxY = vy + 0.4999;
+    const minZ = vz - 0.4999, maxZ = vz + 0.4999;
+
+    let cx = vx, cy = vy, cz = vz;
+    const e = 0.001;
+
+    for (let i = 0; i < ASCENT_ITERATIONS; i++) {
+        const gx = grid_sample_trilinear(grid, cx + e, cy, cz) - grid_sample_trilinear(grid, cx - e, cy, cz);
+        const gy = grid_sample_trilinear(grid, cx, cy + e, cz) - grid_sample_trilinear(grid, cx, cy - e, cz);
+        const gz = grid_sample_trilinear(grid, cx, cy, cz + e) - grid_sample_trilinear(grid, cx, cy, cz - e);
+
+        cx = clamp(cx + gx * ASCENT_RATE, minX, maxX);
+        cy = clamp(cy + gy * ASCENT_RATE, minY, maxY);
+        cz = clamp(cz + gz * ASCENT_RATE, minZ, maxZ);
+    }
+
+    out[0] = cx;
+    out[1] = cy;
+    out[2] = cz;
+}
+
+/**
+ * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
+ * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
+ */
+export function grid_claim_sphere(claimed, grid, px, py, pz, radius) {
+    const { rx, ry, rz, strideZ, x0, y0, z0, vsX, vsY, vsZ } = grid;
+    const r2 = radius * radius;
+
+    const xlo = vsX > 0 ? Math.max(0, Math.floor((px - x0 - radius) / vsX)) : 0;
+    const xhi = vsX > 0 ? Math.min(rx - 1, Math.ceil((px - x0 + radius) / vsX)) : rx - 1;
+    const ylo = vsY > 0 ? Math.max(0, Math.floor((py - y0 - radius) / vsY)) : 0;
+    const yhi = vsY > 0 ? Math.min(ry - 1, Math.ceil((py - y0 + radius) / vsY)) : ry - 1;
+    const zlo = vsZ > 0 ? Math.max(0, Math.floor((pz - z0 - radius) / vsZ)) : 0;
+    const zhi = vsZ > 0 ? Math.min(rz - 1, Math.ceil((pz - z0 + radius) / vsZ)) : rz - 1;
+
+    for (let zi = zlo; zi <= zhi; zi++) {
+        const dz = (vsZ > 0 ? z0 + zi * vsZ : z0) - pz;
+        for (let yi = ylo; yi <= yhi; yi++) {
+            const dy = (vsY > 0 ? y0 + yi * vsY : y0) - py;
+            for (let xi = xlo; xi <= xhi; xi++) {
+                const dx = (vsX > 0 ? x0 + xi * vsX : x0) - px;
+                if (dx * dx + dy * dy + dz * dz <= r2) {
+                    claimed[zi * strideZ + yi * rx + xi] = 1;
+                }
+            }
+        }
+    }
+}

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

@@ -1,146 +1,146 @@
-import { csr_graph_find_edge } from "../../../../core/graph/csr/csr_graph_find_edge.js";
-import {
-    csr_graph_from_undirected_edge_list
-} from "../../../../core/graph/csr/csr_graph_from_undirected_edge_list.js";
-import { probe_edge_key } from "./probe_edge_key.js";
-import { probe_edge_visible } from "./probe_edge_visible.js";
-
-// A chord is worth adding when the straight line beats the existing 2-hop route through their shared
-// neighbour by at least this factor (a local greedy-spanner stretch test).
-const DEFAULT_STRETCH = 1.06;
-// ...or when the corner at the shared neighbour is sharp: dot(̂(u−w), −̂(v−w)) < this — i.e. the angle u-w-v
-// is acute (a diffraction corner the sound must wrap around). -0.5 ≈ corners sharper than 60°.
-const DEFAULT_KINK = -0.866;
-// Cap added edges at this fraction of the base edge count — a handful of the highest-benefit shortcuts, so
-// the augmentation composes with the base graph rather than densifying it.
-const DEFAULT_BUDGET = 3;
-
-/**
- * Augment a probe-visibility graph with a budgeted handful of shortcut edges that improve path quality.
- * The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear
- * straight line exists. For each 2-ring chord `(u,v)` (sharing a base neighbour `w`, not already adjacent)
- * that is unoccluded, add it when EITHER:
- *  - **length** (greedy spanner): the straight `‖uv‖` beats the 2-hop `‖uw‖+‖wv‖` by ≥ `stretchFactor`, or
- *  - **directionality** (diffraction-angle gate): the corner at `w` is acute — `dot(̂(u−w), −̂(v−w)) < kink`.
- *
- * For a 2-ring chord the two criteria largely coincide (an acute corner is also a big detour), but the
- * explicit angle gate catches sharp corners the length threshold alone would miss. The length test is local
- * (vs the 2-hop, not a global Dijkstra) — cheap and O(n·degree²); acoustically the bends that matter are
- * local corners. Candidates are added highest-detour-first up to `budgetFraction` of the base edge count.
- * Pure geometry; offline (no WebAudio).
- *
- * @param {AcousticProbeField} field
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the current edges (base + bridges)
- * @param {number} [stretchFactor] add a chord when the straight ‖uv‖ beats the 2-hop ‖uw‖+‖wv‖ by ≥ this
- * @param {number} [kinkThreshold] add a chord when the corner at w is acute: dot(̂(u−w), −̂(v−w)) < this
- * @param {number} [budgetFraction] cap added edges at this fraction of the base edge count
- * @returns {{a: number[], b: number[]}} the shortcut edges to add (possibly empty)
- */
-export function probe_visibility_augment(
-    field,
-    index,
-    edges,
-    stretchFactor = DEFAULT_STRETCH,
-    kinkThreshold = DEFAULT_KINK,
-    budgetFraction = DEFAULT_BUDGET
-) {
-    const n = field.size;
-
-    const m = edges.a.length;
-    if (m === 0) {
-        return { a: [], b: [] };
-    }
-
-    // CSR adjacency over the current edges (for 2-ring walks + "already adjacent?" tests). Topology only —
-    // the walk never reads weights, so every edge is given the same (zero) weight.
-    const graph = csr_graph_from_undirected_edge_list(n, edges.a, edges.b, new Float32Array(m));
-    const addr = graph.edge_addresses;
-    const adj = graph.adjacency;
-
-    // eligible chords (allowing duplicates from multiple shared neighbours; deduped at add-time)
-    const candU = [];
-    const candV = [];
-    const candBenefit = [];
-
-    for (let u = 0; u < n; u++) {
-        const ux = field.probeX(u);
-        const uy = field.probeY(u);
-        const uz = field.probeZ(u);
-
-        const edge_count = addr[u + 1];
-
-        for (let ki = addr[u]; ki < edge_count; ki++) {
-            const w = adj[ki];
-
-            const wx = field.probeX(w);
-            const wy = field.probeY(w);
-            const wz = field.probeZ(w);
-
-            const uwx = ux - wx, uwy = uy - wy, uwz = uz - wz;
-            const uw = Math.sqrt(uwx * uwx + uwy * uwy + uwz * uwz);
-
-            for (let kj = addr[w]; kj < addr[w + 1]; kj++) {
-                const v = adj[kj];
-                if (v <= u) {
-                    continue; // canonical u<v (and skips v===u: u is a neighbour of w)
-                }
-                if (csr_graph_find_edge(graph, u, v) !== -1) {
-                    continue; // already connected — a triangle, no shortcut needed
-                }
-
-                const vx = field.probeX(v);
-                const vy = field.probeY(v);
-                const vz = field.probeZ(v);
-
-                const wvx = vx - wx, wvy = vy - wy, wvz = vz - wz;
-                const wv = Math.sqrt(wvx * wvx + wvy * wvy + wvz * wvz);
-
-                const uvx = vx - ux, uvy = vy - uy, uvz = vz - uz;
-                const uv = Math.sqrt(uvx * uvx + uvy * uvy + uvz * uvz);
-
-                const stretchOK = uv * stretchFactor < uw + wv;
-
-                // dot(̂(u−w), −̂(v−w)) = −(uw·wv)/(‖uw‖‖wv‖); acute corner → near −1
-                const kinkVal = -(uwx * wvx + uwy * wvy + uwz * wvz) / (uw * wv);
-                const kinkOK = kinkVal < kinkThreshold;
-
-                if (!stretchOK && !kinkOK) {
-                    continue;
-                }
-
-                if (!probe_edge_visible(field, index, u, v)) {
-                    continue; // a wall blocks the shortcut
-                }
-
-                candU.push(u);
-                candV.push(v);
-                candBenefit.push((uw + wv) / uv); // detour ratio — higher means a better shortcut
-            }
-        }
-    }
-
-    // add highest-detour chords first, up to the budget, deduping repeats
-    const order = candU.map((_, i) => i);
-    order.sort((i, j) => candBenefit[j] - candBenefit[i]);
-
-    const budget = Math.floor(budgetFraction * m);
-    const added = new Set();
-    const outA = [];
-    const outB = [];
-
-    for (let i = 0; i < order.length && outA.length < budget; i++) {
-        const idx = order[i];
-        const u = candU[idx];
-        const v = candV[idx];
-        const key = probe_edge_key(u, v, n);
-        if (added.has(key)) {
-            continue;
-        }
-        added.add(key);
-        outA.push(u);
-        outB.push(v);
-    }
-
-    return { a: outA, b: outB };
-}
+import { csr_graph_find_edge } from "../../../../core/graph/csr/csr_graph_find_edge.js";
+import {
+    csr_graph_from_undirected_edge_list
+} from "../../../../core/graph/csr/csr_graph_from_undirected_edge_list.js";
+import { probe_edge_key } from "./probe_edge_key.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// A chord is worth adding when the straight line beats the existing 2-hop route through their shared
+// neighbour by at least this factor (a local greedy-spanner stretch test).
+const DEFAULT_STRETCH = 1.06;
+// ...or when the corner at the shared neighbour is sharp: dot(̂(u−w), −̂(v−w)) < this — i.e. the angle u-w-v
+// is acute (a diffraction corner the sound must wrap around). -0.5 ≈ corners sharper than 60°.
+const DEFAULT_KINK = -0.866;
+// Cap added edges at this fraction of the base edge count — a handful of the highest-benefit shortcuts, so
+// the augmentation composes with the base graph rather than densifying it.
+const DEFAULT_BUDGET = 3;
+
+/**
+ * Augment a probe-visibility graph with a budgeted handful of shortcut edges that improve path quality.
+ * The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear
+ * straight line exists. For each 2-ring chord `(u,v)` (sharing a base neighbour `w`, not already adjacent)
+ * that is unoccluded, add it when EITHER:
+ *  - **length** (greedy spanner): the straight `‖uv‖` beats the 2-hop `‖uw‖+‖wv‖` by ≥ `stretchFactor`, or
+ *  - **directionality** (diffraction-angle gate): the corner at `w` is acute — `dot(̂(u−w), −̂(v−w)) < kink`.
+ *
+ * For a 2-ring chord the two criteria largely coincide (an acute corner is also a big detour), but the
+ * explicit angle gate catches sharp corners the length threshold alone would miss. The length test is local
+ * (vs the 2-hop, not a global Dijkstra) — cheap and O(n·degree²); acoustically the bends that matter are
+ * local corners. Candidates are added highest-detour-first up to `budgetFraction` of the base edge count.
+ * Pure geometry; offline (no WebAudio).
+ *
+ * @param {AcousticProbeField} field
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the current edges (base + bridges)
+ * @param {number} [stretchFactor] add a chord when the straight ‖uv‖ beats the 2-hop ‖uw‖+‖wv‖ by ≥ this
+ * @param {number} [kinkThreshold] add a chord when the corner at w is acute: dot(̂(u−w), −̂(v−w)) < this
+ * @param {number} [budgetFraction] cap added edges at this fraction of the base edge count
+ * @returns {{a: number[], b: number[]}} the shortcut edges to add (possibly empty)
+ */
+export function probe_visibility_augment(
+    field,
+    index,
+    edges,
+    stretchFactor = DEFAULT_STRETCH,
+    kinkThreshold = DEFAULT_KINK,
+    budgetFraction = DEFAULT_BUDGET
+) {
+    const n = field.size;
+
+    const m = edges.a.length;
+    if (m === 0) {
+        return { a: [], b: [] };
+    }
+
+    // CSR adjacency over the current edges (for 2-ring walks + "already adjacent?" tests). Topology only —
+    // the walk never reads weights, so every edge is given the same (zero) weight.
+    const graph = csr_graph_from_undirected_edge_list(n, edges.a, edges.b, new Float32Array(m));
+    const addr = graph.edge_addresses;
+    const adj = graph.adjacency;
+
+    // eligible chords (allowing duplicates from multiple shared neighbours; deduped at add-time)
+    const candU = [];
+    const candV = [];
+    const candBenefit = [];
+
+    for (let u = 0; u < n; u++) {
+        const ux = field.probeX(u);
+        const uy = field.probeY(u);
+        const uz = field.probeZ(u);
+
+        const edge_count = addr[u + 1];
+
+        for (let ki = addr[u]; ki < edge_count; ki++) {
+            const w = adj[ki];
+
+            const wx = field.probeX(w);
+            const wy = field.probeY(w);
+            const wz = field.probeZ(w);
+
+            const uwx = ux - wx, uwy = uy - wy, uwz = uz - wz;
+            const uw = Math.sqrt(uwx * uwx + uwy * uwy + uwz * uwz);
+
+            for (let kj = addr[w]; kj < addr[w + 1]; kj++) {
+                const v = adj[kj];
+                if (v <= u) {
+                    continue; // canonical u<v (and skips v===u: u is a neighbour of w)
+                }
+                if (csr_graph_find_edge(graph, u, v) !== -1) {
+                    continue; // already connected — a triangle, no shortcut needed
+                }
+
+                const vx = field.probeX(v);
+                const vy = field.probeY(v);
+                const vz = field.probeZ(v);
+
+                const wvx = vx - wx, wvy = vy - wy, wvz = vz - wz;
+                const wv = Math.sqrt(wvx * wvx + wvy * wvy + wvz * wvz);
+
+                const uvx = vx - ux, uvy = vy - uy, uvz = vz - uz;
+                const uv = Math.sqrt(uvx * uvx + uvy * uvy + uvz * uvz);
+
+                const stretchOK = uv * stretchFactor < uw + wv;
+
+                // dot(̂(u−w), −̂(v−w)) = −(uw·wv)/(‖uw‖‖wv‖); acute corner → near −1
+                const kinkVal = -(uwx * wvx + uwy * wvy + uwz * wvz) / (uw * wv);
+                const kinkOK = kinkVal < kinkThreshold;
+
+                if (!stretchOK && !kinkOK) {
+                    continue;
+                }
+
+                if (!probe_edge_visible(field, index, u, v)) {
+                    continue; // a wall blocks the shortcut
+                }
+
+                candU.push(u);
+                candV.push(v);
+                candBenefit.push((uw + wv) / uv); // detour ratio — higher means a better shortcut
+            }
+        }
+    }
+
+    // add highest-detour chords first, up to the budget, deduping repeats
+    const order = candU.map((_, i) => i);
+    order.sort((i, j) => candBenefit[j] - candBenefit[i]);
+
+    const budget = Math.floor(budgetFraction * m);
+    const added = new Set();
+    const outA = [];
+    const outB = [];
+
+    for (let i = 0; i < order.length && outA.length < budget; i++) {
+        const idx = order[i];
+        const u = candU[idx];
+        const v = candV[idx];
+        const key = probe_edge_key(u, v, n);
+        if (added.has(key)) {
+            continue;
+        }
+        added.add(key);
+        outA.push(u);
+        outB.push(v);
+    }
+
+    return { a: outA, b: outB };
+}