@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,82 +1,82 @@
-import { clamp } from "../../../../core/math/clamp.js";
-import { grid_claim_sphere, grid_local_maximum, grid_sample_world, grid_voxel_to_world } from "./probe_sdf_grid.js";
-
-/**
- * Place acoustic probes over a prebuilt SDF grid ({@link build_sdf_grid}) with a maximal-empty-sphere greedy
- * cover — adaptive density: one big-radius probe fills an open hall, a chain of small-radius probes lines a
- * corridor, and nothing is placed inside solid. Ported from the reference GI placer
- * (`lpv_generate_probe_locations2`) with the acoustic spacing model.
- *
- * Take the voxels in open air (`SDF > clearanceFloor`), sort by openness descending; greedily take the
- * most-open voxel, nudge it to the local SDF maximum (most-open sub-voxel point), emit a probe there, and
- * claim every voxel within its empty-sphere radius so no second probe lands in the same open region. The
- * radius is floored at `minSpacing` and capped at `maxSpacing` — so the INITIAL cover never packs probes
- * closer than the hint (connectivity refinement does that later) and never sparser than the ceiling.
- *
- * PRE-SEEDED PROBES: `options.predefined` (a flat `[x,y,z, …]` placed by an earlier stage — e.g. the portal
- * throats from {@link probe_detect_portals}, which sit in narrow openings the cover would otherwise skip as
- * sub-clearance) are emitted FIRST and carve their empty spheres into the grid, so the greedy cover never
- * packs a redundant probe on top of one. They lead the returned list (indices `[0, K)`), so a caller can
- * recover them by count.
- *
- * Pure geometry; offline (no WebAudio); deterministic for a given grid.
- *
- * @param {import("./probe_sdf_grid.js").SdfGrid} grid prebuilt SDF grid
- * @param {{predefined?: ArrayLike<number>}} [options]
- * @returns {number[]} flat probe positions `[x,y,z, …]`, all in open air; predefined first
- */
-export function probe_place_sdf_cover(grid, options = {}) {
-    const { rx, ry, strideZ, total, minSpacing, maxSpacing, clearanceFloor } = grid;
-    const sdf = grid.sdf;
-
-    const claimed = new Uint8Array(total); // voxels already inside a placed probe's empty sphere
-    const positions = [];
-    const ascended = [0, 0, 0];
-    const world = [0, 0, 0];
-
-    // Pre-seeded probes lead, and carve their empty spheres so the greedy cover fills only what they leave.
-    // Their throat clearance clamps to `minSpacing` (a doorway is narrower than the hint), so a portal claims
-    // a modest sphere — enough that the cover won't drop a duplicate on it, not so much it leaves a gap.
-    const predefined = options.predefined;
-    if (predefined !== undefined) {
-        for (let i = 0; i + 2 < predefined.length; i += 3) {
-            const px = predefined[i], py = predefined[i + 1], pz = predefined[i + 2];
-            positions.push(px, py, pz);
-            const radius = clamp(grid_sample_world(grid, px, py, pz), minSpacing, maxSpacing);
-            grid_claim_sphere(claimed, grid, px, py, pz, radius);
-        }
-    }
-
-    // candidate voxels = in open air, off any surface; most-open first
-    const candidates = [];
-    for (let i = 0; i < total; i++) {
-        if (sdf[i] > clearanceFloor) {
-            candidates.push(i);
-        }
-    }
-    candidates.sort((a, b) => sdf[b] - sdf[a]);
-
-    for (let c = 0; c < candidates.length; c++) {
-        const voxelIndex = candidates[c];
-        if (claimed[voxelIndex] === 1) {
-            continue; // swept up by an earlier, more-open probe (or a pre-seeded portal)
-        }
-
-        const vx = voxelIndex % rx;
-        const vy = Math.floor(voxelIndex / rx) % ry;
-        const vz = Math.floor(voxelIndex / strideZ);
-
-        // nudge to the local SDF maximum (most-open sub-voxel point)
-        grid_local_maximum(ascended, grid, vx, vy, vz);
-        grid_voxel_to_world(grid, world, ascended[0], ascended[1], ascended[2]);
-
-        // empty-sphere radius: the clearance, floored at the hint and capped at the ceiling
-        const radius = clamp(sdf[voxelIndex], minSpacing, maxSpacing);
-
-        grid_claim_sphere(claimed, grid, world[0], world[1], world[2], radius);
-
-        positions.push(world[0], world[1], world[2]);
-    }
-
-    return positions;
-}
+import { clamp } from "../../../../core/math/clamp.js";
+import { grid_claim_sphere, grid_local_maximum, grid_sample_world, grid_voxel_to_world } from "./probe_sdf_grid.js";
+
+/**
+ * Place acoustic probes over a prebuilt SDF grid ({@link build_sdf_grid}) with a maximal-empty-sphere greedy
+ * cover — adaptive density: one big-radius probe fills an open hall, a chain of small-radius probes lines a
+ * corridor, and nothing is placed inside solid. Ported from the reference GI placer
+ * (`lpv_generate_probe_locations2`) with the acoustic spacing model.
+ *
+ * Take the voxels in open air (`SDF > clearanceFloor`), sort by openness descending; greedily take the
+ * most-open voxel, nudge it to the local SDF maximum (most-open sub-voxel point), emit a probe there, and
+ * claim every voxel within its empty-sphere radius so no second probe lands in the same open region. The
+ * radius is floored at `minSpacing` and capped at `maxSpacing` — so the INITIAL cover never packs probes
+ * closer than the hint (connectivity refinement does that later) and never sparser than the ceiling.
+ *
+ * PRE-SEEDED PROBES: `options.predefined` (a flat `[x,y,z, …]` placed by an earlier stage — e.g. the portal
+ * throats from {@link probe_detect_portals}, which sit in narrow openings the cover would otherwise skip as
+ * sub-clearance) are emitted FIRST and carve their empty spheres into the grid, so the greedy cover never
+ * packs a redundant probe on top of one. They lead the returned list (indices `[0, K)`), so a caller can
+ * recover them by count.
+ *
+ * Pure geometry; offline (no WebAudio); deterministic for a given grid.
+ *
+ * @param {import("./probe_sdf_grid.js").SdfGrid} grid prebuilt SDF grid
+ * @param {{predefined?: ArrayLike<number>}} [options]
+ * @returns {number[]} flat probe positions `[x,y,z, …]`, all in open air; predefined first
+ */
+export function probe_place_sdf_cover(grid, options = {}) {
+    const { rx, ry, strideZ, total, minSpacing, maxSpacing, clearanceFloor } = grid;
+    const sdf = grid.sdf;
+
+    const claimed = new Uint8Array(total); // voxels already inside a placed probe's empty sphere
+    const positions = [];
+    const ascended = [0, 0, 0];
+    const world = [0, 0, 0];
+
+    // Pre-seeded probes lead, and carve their empty spheres so the greedy cover fills only what they leave.
+    // Their throat clearance clamps to `minSpacing` (a doorway is narrower than the hint), so a portal claims
+    // a modest sphere — enough that the cover won't drop a duplicate on it, not so much it leaves a gap.
+    const predefined = options.predefined;
+    if (predefined !== undefined) {
+        for (let i = 0; i + 2 < predefined.length; i += 3) {
+            const px = predefined[i], py = predefined[i + 1], pz = predefined[i + 2];
+            positions.push(px, py, pz);
+            const radius = clamp(grid_sample_world(grid, px, py, pz), minSpacing, maxSpacing);
+            grid_claim_sphere(claimed, grid, px, py, pz, radius);
+        }
+    }
+
+    // candidate voxels = in open air, off any surface; most-open first
+    const candidates = [];
+    for (let i = 0; i < total; i++) {
+        if (sdf[i] > clearanceFloor) {
+            candidates.push(i);
+        }
+    }
+    candidates.sort((a, b) => sdf[b] - sdf[a]);
+
+    for (let c = 0; c < candidates.length; c++) {
+        const voxelIndex = candidates[c];
+        if (claimed[voxelIndex] === 1) {
+            continue; // swept up by an earlier, more-open probe (or a pre-seeded portal)
+        }
+
+        const vx = voxelIndex % rx;
+        const vy = Math.floor(voxelIndex / rx) % ry;
+        const vz = Math.floor(voxelIndex / strideZ);
+
+        // nudge to the local SDF maximum (most-open sub-voxel point)
+        grid_local_maximum(ascended, grid, vx, vy, vz);
+        grid_voxel_to_world(grid, world, ascended[0], ascended[1], ascended[2]);
+
+        // empty-sphere radius: the clearance, floored at the hint and capped at the ceiling
+        const radius = clamp(sdf[voxelIndex], minSpacing, maxSpacing);
+
+        grid_claim_sphere(claimed, grid, world[0], world[1], world[2], radius);
+
+        positions.push(world[0], world[1], world[2]);
+    }
+
+    return positions;
+}

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

@@ -1,181 +1,181 @@
-import { uf_find, uf_init, uf_union } from "../../../../core/collection/union-find/union_find.js";
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
-
-// Connectivity refinement may place probes finer than the spacing hint, down to minSpacing / this factor.
-const DEFAULT_MAX_REFINE_FACTOR = 4;
-// Two components are candidates to thread only if probes come within this multiple of minSpacing — beyond it
-// we assume they're genuinely sealed (a closed wall, not a bend). Also the SDF / waypoint search radius.
-const DEFAULT_CORRIDOR_REACH_FACTOR = 4;
-// Per-step waypoint search: directions on a Fibonacci sphere × these fractions of the segment length.
-const SAMPLE_DIRECTIONS = 24;
-const SAMPLE_RADII = [0.5, 0.25, 0.125];
-// Bound the greedy walk so a hopeless gap can't recurse forever.
-const MAX_THREAD_DEPTH = 12;
-
-// module-static scratch
-const RAY = new Ray3();
-const DIR = [0, 0, 0];
-
-/**
- * Connectivity refinement — the acoustic stage the reference GI placer lacks. After the SDF cover + a
- * provisional {@link bakeVisibility}, the graph may have islands a bend/throat separates even though sound
- * routes between them: `bakeVisibility` only links probes with STRAIGHT line of sight, so a corridor that
- * bends sharper than the cover's spacing leaves its two ends in different components. This inserts the
- * minimum extra probes so a chain of mutually-visible probes spans every such path — "ray bounces between
- * probes", as a bounded greedy walk through open air.
- *
- * For each pair of nearby components (within `corridorReachFactor · minSpacing`), it walks from one side
- * toward the other: at each step it samples open-air waypoints around the segment (a Fibonacci sphere × a
- * few radii), keeps those visible from the current point, and steps to the one nearest the target — until a
- * waypoint sees the target (chain complete) or no progress is possible (give up — a genuinely sealed wall
- * stays disconnected, correctly). It never subdivides below `minSpacing / maxRefineFactor`. The waypoints
- * are returned for the caller to append; the FINAL `bakeVisibility` then links them.
- *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {AcousticProbeField} field cover probes WITH a baked visibility graph (defines the components)
- * @param {number} minSpacing the placement spacing hint
- * @param {{maxRefineFactor?: number, corridorReachFactor?: number}} [options]
- * @returns {number[]} flat extra probe positions `[x,y,z, …]` (possibly empty)
- */
-export function probe_refine_connectivity(index, field, minSpacing, options = {}) {
-    const maxRefineFactor = options.maxRefineFactor ?? DEFAULT_MAX_REFINE_FACTOR;
-    const reach = (options.corridorReachFactor ?? DEFAULT_CORRIDOR_REACH_FACTOR) * minSpacing;
-    const floor = minSpacing / maxRefineFactor;
-
-    const n = field.size;
-    const graph = field.visibilityGraph;
-
-    // connected components of the provisional visibility graph
-    const parent = new Uint32Array(n);
-    uf_init(parent, n);
-    for (let v = 0; v < n; v++) {
-        for (let k = graph.edge_addresses[v]; k < graph.edge_addresses[v + 1]; k++) {
-            uf_union(parent, v, graph.adjacency[k]);
-        }
-    }
-
-    const waypoints = [];
-    const hits = [];
-
-    for (let i = 0; i < n; i++) {
-        const ix = field.probeX(i), iy = field.probeY(i), iz = field.probeZ(i);
-
-        const count = field.probesWithinRadius(hits, 0, ix, iy, iz, reach);
-
-        for (let h = 0; h < count; h++) {
-            const j = hits[h];
-            if (j <= i) {
-                continue;
-            }
-            // re-read roots each time — an earlier successful thread may have merged these components, directly
-            // or transitively (so we don't thread a redundant chain across 3+ mutually-near components)
-            if (uf_find(parent, i) === uf_find(parent, j)) {
-                continue;
-            }
-
-            const chain = thread(index, ix, iy, iz, field.probeX(j), field.probeY(j), field.probeZ(j), floor, reach, 0);
-            if (chain !== null) {
-                uf_union(parent, i, j); // merge → later pairs across these now-connected components are skipped
-                for (let w = 0; w < chain.length; w++) {
-                    waypoints.push(chain[w]);
-                }
-            }
-        }
-    }
-
-    return waypoints;
-}
-
-/**
- * Greedily walk from (ax,ay,az) toward (bx,by,bz) through open air, inserting waypoints, until a waypoint
- * sees the target. Returns the flat waypoint list `[x,y,z, …]`, or `null` if no open chain was found.
- */
-function thread(index, ax, ay, az, bx, by, bz, floor, reach, depth) {
-    if (segment_clear(index, ax, ay, az, bx, by, bz)) {
-        return []; // already mutually visible
-    }
-    if (depth >= MAX_THREAD_DEPTH) {
-        return null;
-    }
-
-    const w = open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach);
-    if (w === null) {
-        return null; // no visible open point makes progress → sealed
-    }
-
-    const dx = w[0] - ax, dy = w[1] - ay, dz = w[2] - az;
-    if (Math.sqrt(dx * dx + dy * dy + dz * dz) < floor) {
-        return null; // would need probes finer than the refine floor
-    }
-
-    const rest = thread(index, w[0], w[1], w[2], bx, by, bz, floor, reach, depth + 1);
-    if (rest === null) {
-        return null;
-    }
-
-    return [w[0], w[1], w[2], ...rest];
-}
-
-/**
- * Among open-air points sampled around the (a→b) segment that are VISIBLE from `a`, return the one nearest
- * `b` that makes progress (closer to `b` than `a` is), or `null`. Sampled on a Fibonacci sphere around the
- * segment midpoint at a few fractions of the segment length, so both perpendicular detours (over a baffle)
- * and along-segment steps are covered.
- * @returns {number[]|null} `[x,y,z]` or null
- */
-function open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach) {
-    const mx = (ax + bx) * 0.5, my = (ay + by) * 0.5, mz = (az + bz) * 0.5;
-    const segLen = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
-
-    let best = null;
-    // must improve on a's own distance to b (strict progress → the walk terminates)
-    let bestDistB = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
-
-    for (let d = 0; d < SAMPLE_DIRECTIONS; d++) {
-        sphere_fibonacci_point(DIR, 0, d, SAMPLE_DIRECTIONS);
-
-        for (let r = 0; r < SAMPLE_RADII.length; r++) {
-            const radius = segLen * SAMPLE_RADII[r];
-            const sx = mx + DIR[0] * radius;
-            const sy = my + DIR[1] * radius;
-            const sz = mz + DIR[2] * radius;
-
-            // must be in open air (clearance > a small margin so the reverb bake + visibility are valid)
-            if (index.signedDistanceAt(sx, sy, sz, reach) <= 1e-3) {
-                continue;
-            }
-
-            const distB = Math.sqrt((bx - sx) * (bx - sx) + (by - sy) * (by - sy) + (bz - sz) * (bz - sz));
-            if (distB >= bestDistB) {
-                continue; // no progress toward b
-            }
-
-            if (!segment_clear(index, ax, ay, az, sx, sy, sz)) {
-                continue; // a can't see this waypoint
-            }
-
-            bestDistB = distB;
-            best = best === null ? [sx, sy, sz] : best;
-            best[0] = sx; best[1] = sy; best[2] = sz;
-        }
-    }
-
-    return best;
-}
-
-/** Whether the open segment a→b is clear of occluders (one shadow ray; mirrors probe_edge_visible). */
-function segment_clear(index, ax, ay, az, bx, by, bz) {
-    const dx = bx - ax, dy = by - ay, dz = bz - az;
-    const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
-    if (d === 0) {
-        return true;
-    }
-
-    const inv = 1 / d;
-    RAY.setOrigin(ax, ay, az);
-    RAY.setDirection(dx * inv, dy * inv, dz * inv);
-    RAY.tMax = d;
-
-    return !index.anyHit(RAY);
-}
+import { uf_find, uf_init, uf_union } from "../../../../core/collection/union-find/union_find.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+
+// Connectivity refinement may place probes finer than the spacing hint, down to minSpacing / this factor.
+const DEFAULT_MAX_REFINE_FACTOR = 4;
+// Two components are candidates to thread only if probes come within this multiple of minSpacing — beyond it
+// we assume they're genuinely sealed (a closed wall, not a bend). Also the SDF / waypoint search radius.
+const DEFAULT_CORRIDOR_REACH_FACTOR = 4;
+// Per-step waypoint search: directions on a Fibonacci sphere × these fractions of the segment length.
+const SAMPLE_DIRECTIONS = 24;
+const SAMPLE_RADII = [0.5, 0.25, 0.125];
+// Bound the greedy walk so a hopeless gap can't recurse forever.
+const MAX_THREAD_DEPTH = 12;
+
+// module-static scratch
+const RAY = new Ray3();
+const DIR = [0, 0, 0];
+
+/**
+ * Connectivity refinement — the acoustic stage the reference GI placer lacks. After the SDF cover + a
+ * provisional {@link bakeVisibility}, the graph may have islands a bend/throat separates even though sound
+ * routes between them: `bakeVisibility` only links probes with STRAIGHT line of sight, so a corridor that
+ * bends sharper than the cover's spacing leaves its two ends in different components. This inserts the
+ * minimum extra probes so a chain of mutually-visible probes spans every such path — "ray bounces between
+ * probes", as a bounded greedy walk through open air.
+ *
+ * For each pair of nearby components (within `corridorReachFactor · minSpacing`), it walks from one side
+ * toward the other: at each step it samples open-air waypoints around the segment (a Fibonacci sphere × a
+ * few radii), keeps those visible from the current point, and steps to the one nearest the target — until a
+ * waypoint sees the target (chain complete) or no progress is possible (give up — a genuinely sealed wall
+ * stays disconnected, correctly). It never subdivides below `minSpacing / maxRefineFactor`. The waypoints
+ * are returned for the caller to append; the FINAL `bakeVisibility` then links them.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {AcousticProbeField} field cover probes WITH a baked visibility graph (defines the components)
+ * @param {number} minSpacing the placement spacing hint
+ * @param {{maxRefineFactor?: number, corridorReachFactor?: number}} [options]
+ * @returns {number[]} flat extra probe positions `[x,y,z, …]` (possibly empty)
+ */
+export function probe_refine_connectivity(index, field, minSpacing, options = {}) {
+    const maxRefineFactor = options.maxRefineFactor ?? DEFAULT_MAX_REFINE_FACTOR;
+    const reach = (options.corridorReachFactor ?? DEFAULT_CORRIDOR_REACH_FACTOR) * minSpacing;
+    const floor = minSpacing / maxRefineFactor;
+
+    const n = field.size;
+    const graph = field.visibilityGraph;
+
+    // connected components of the provisional visibility graph
+    const parent = new Uint32Array(n);
+    uf_init(parent, n);
+    for (let v = 0; v < n; v++) {
+        for (let k = graph.edge_addresses[v]; k < graph.edge_addresses[v + 1]; k++) {
+            uf_union(parent, v, graph.adjacency[k]);
+        }
+    }
+
+    const waypoints = [];
+    const hits = [];
+
+    for (let i = 0; i < n; i++) {
+        const ix = field.probeX(i), iy = field.probeY(i), iz = field.probeZ(i);
+
+        const count = field.probesWithinRadius(hits, 0, ix, iy, iz, reach);
+
+        for (let h = 0; h < count; h++) {
+            const j = hits[h];
+            if (j <= i) {
+                continue;
+            }
+            // re-read roots each time — an earlier successful thread may have merged these components, directly
+            // or transitively (so we don't thread a redundant chain across 3+ mutually-near components)
+            if (uf_find(parent, i) === uf_find(parent, j)) {
+                continue;
+            }
+
+            const chain = thread(index, ix, iy, iz, field.probeX(j), field.probeY(j), field.probeZ(j), floor, reach, 0);
+            if (chain !== null) {
+                uf_union(parent, i, j); // merge → later pairs across these now-connected components are skipped
+                for (let w = 0; w < chain.length; w++) {
+                    waypoints.push(chain[w]);
+                }
+            }
+        }
+    }
+
+    return waypoints;
+}
+
+/**
+ * Greedily walk from (ax,ay,az) toward (bx,by,bz) through open air, inserting waypoints, until a waypoint
+ * sees the target. Returns the flat waypoint list `[x,y,z, …]`, or `null` if no open chain was found.
+ */
+function thread(index, ax, ay, az, bx, by, bz, floor, reach, depth) {
+    if (segment_clear(index, ax, ay, az, bx, by, bz)) {
+        return []; // already mutually visible
+    }
+    if (depth >= MAX_THREAD_DEPTH) {
+        return null;
+    }
+
+    const w = open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach);
+    if (w === null) {
+        return null; // no visible open point makes progress → sealed
+    }
+
+    const dx = w[0] - ax, dy = w[1] - ay, dz = w[2] - az;
+    if (Math.sqrt(dx * dx + dy * dy + dz * dz) < floor) {
+        return null; // would need probes finer than the refine floor
+    }
+
+    const rest = thread(index, w[0], w[1], w[2], bx, by, bz, floor, reach, depth + 1);
+    if (rest === null) {
+        return null;
+    }
+
+    return [w[0], w[1], w[2], ...rest];
+}
+
+/**
+ * Among open-air points sampled around the (a→b) segment that are VISIBLE from `a`, return the one nearest
+ * `b` that makes progress (closer to `b` than `a` is), or `null`. Sampled on a Fibonacci sphere around the
+ * segment midpoint at a few fractions of the segment length, so both perpendicular detours (over a baffle)
+ * and along-segment steps are covered.
+ * @returns {number[]|null} `[x,y,z]` or null
+ */
+function open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach) {
+    const mx = (ax + bx) * 0.5, my = (ay + by) * 0.5, mz = (az + bz) * 0.5;
+    const segLen = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
+
+    let best = null;
+    // must improve on a's own distance to b (strict progress → the walk terminates)
+    let bestDistB = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
+
+    for (let d = 0; d < SAMPLE_DIRECTIONS; d++) {
+        sphere_fibonacci_point(DIR, 0, d, SAMPLE_DIRECTIONS);
+
+        for (let r = 0; r < SAMPLE_RADII.length; r++) {
+            const radius = segLen * SAMPLE_RADII[r];
+            const sx = mx + DIR[0] * radius;
+            const sy = my + DIR[1] * radius;
+            const sz = mz + DIR[2] * radius;
+
+            // must be in open air (clearance > a small margin so the reverb bake + visibility are valid)
+            if (index.signedDistanceAt(sx, sy, sz, reach) <= 1e-3) {
+                continue;
+            }
+
+            const distB = Math.sqrt((bx - sx) * (bx - sx) + (by - sy) * (by - sy) + (bz - sz) * (bz - sz));
+            if (distB >= bestDistB) {
+                continue; // no progress toward b
+            }
+
+            if (!segment_clear(index, ax, ay, az, sx, sy, sz)) {
+                continue; // a can't see this waypoint
+            }
+
+            bestDistB = distB;
+            best = best === null ? [sx, sy, sz] : best;
+            best[0] = sx; best[1] = sy; best[2] = sz;
+        }
+    }
+
+    return best;
+}
+
+/** Whether the open segment a→b is clear of occluders (one shadow ray; mirrors probe_edge_visible). */
+function segment_clear(index, ax, ay, az, bx, by, bz) {
+    const dx = bx - ax, dy = by - ay, dz = bz - az;
+    const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (d === 0) {
+        return true;
+    }
+
+    const inv = 1 / d;
+    RAY.setOrigin(ax, ay, az);
+    RAY.setDirection(dx * inv, dy * inv, dz * inv);
+    RAY.tMax = d;
+
+    return !index.anyHit(RAY);
+}