@woosh/meep-engine 3.56.0 → 3.58.0

package/src/engine/navigation/mesh/build/clip_soup_against_overhangs.js

@@ -1,628 +1,628 @@
-/**
- * Exact obstacle carving at the triangle-soup level, with a faithful agent-radius offset.
- *
- * Each overhead obstacle's footprint is DILATED by the agent radius (Minkowski sum with a disc: edges
- * pushed out by r, convex corners replaced by a rounded arc), and that dilated polygon is subtracted
- * from the walkable triangles. The resulting hole boundary is therefore the true offset of the
- * obstacle - straight along edges, a clean arc at corners - rather than a wavy/mitred contour produced
- * by sampling-then-eroding. (Run AFTER the outer boundary has been eroded by r, so the obstacle holes
- * are not eroded a second time.)
- *
- * Overhead obstacles are the DOWNWARD-facing source faces; a face carves a walkable triangle only where
- * it sits above it, within `agent_height`.
- *
- * An obstacle is a group of overhead faces that share a vertex. A group is carved as its convex hull
- * when its triangles TILE that hull, and triangle by triangle when they do not - a concave or holed
- * obstacle (an L, a doorway frame), or two obstacles that merely touch. Both routes carve the same
- * ground wherever the hull is valid, because dilation by a disc distributes over union; the hull is
- * kept only because it is the cheaper of the two.
- *
- * The subtraction uses the disjoint half-plane decomposition of a convex-polygon difference:
- *     T \ F = U_i ( T ∩ inside(e_0..e_{i-1}) ∩ outside(e_i) )
- * each term convex, the terms disjoint, the union exactly T minus the convex (dilated) footprint F.
- * Each term is cut against the LINE of e_i rather than the edge itself, so its cut edge overshoots that
- * edge's endpoints; splitting it back at them (see {@link push_outside_piece}) keeps the pieces
- * conforming, so the seams fuse into shared edges instead of leaving T-junctions.
- *
- * Everything is data-oriented: clipping happens in the 2D plane perpendicular to `up`, with polygons
- * held as flat `Float64Array`s of (u,v) pairs and a small set of reused scratch buffers. World XYZ is
- * recovered for each surviving vertex by barycentric reconstruction on its (planar) source triangle, so
- * kept pieces stay exactly on the original - possibly tilted - walkable plane. Degenerate triangles are
- * dropped, and triangles that no footprint overlaps are copied straight through without allocation.
- *
- * The footprints are indexed in a BVH (keyed by their (u,v) extent and carve height band), so each soup
- * triangle only tests the footprints that can actually overlap it - O(m log k) rather than O(m k) for m
- * soup triangles and k footprints.
- */
-
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import { bvh_query_user_data_intersects_aabb } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
-import { v3_dot } from "../../../../core/geom/vec3/v3_dot.js";
-import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
-import { convex_hull_monotone_2d } from "../../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
-import { compute_polygon_area_2d } from "../../../../core/geom/2d/compute_polygon_area_2d.js";
-import { polygon2_clip_halfplane } from "../../../../core/geom/2d/polygon/polygon2_clip_halfplane.js";
-
-const POINT_EPS = 1e-9;
-const AREA_EPS = 1e-9;
-const HEIGHT_EPS = 1e-3;
-const CORNER_SEGMENT_ANGLE = Math.PI / 6; // ~30 deg per rounded-corner segment
-// How closely a group's triangles must add up to the area of their own convex hull before that hull
-// is accepted as the group's footprint (see the footprint build). Relative, so it means the same thing
-// at any obstacle size.
-//
-// Loose on purpose. The quantity it has to resolve is a real concavity - a notch, a ring's hole, the
-// space between two obstacles that touch - which is a substantial fraction of the hull, never one part
-// in a million of it. Meanwhile the shoelace sums it compares lose absolute precision as the geometry
-// moves away from the origin (~1e-8 at 10,000 units), and a threshold down at that level would start
-// reading noise as concavity. Erring loose only ever sends a group to the hull, which is what it
-// always used; erring tight sends convex groups down the slower per-triangle route for nothing.
-const HULL_TILING_RELATIVE_EPS = 1e-6;
-
-// Vertex coincidence key. Quantize each projected coordinate to QUANTIZE (1mm) and pack the two integer
-// coordinates into one safe-integer key: cheaper than a string and with no per-probe allocation. Each
-// axis occupies a biased 26-bit field, so the key stays unique while |u|,|v| < 2^25 / QUANTIZE
-// (~33,000 units). A 16-bit-per-axis pack would only reach ~3.3 units and silently collide - navmesh
-// coordinates routinely exceed that (e.g. geometry built 10,000 units from the origin). Coincident
-// vertices are the same source vertex projected identically, so they match at any quantization; the
-// precision only needs to keep genuinely distinct obstacle corners apart (the smallest is ~0.3 units).
-const QUANTIZE = 1e3;
-const KEY_BIAS = 1 << 25;   // 33,554,432
-const KEY_STRIDE = 1 << 26; // 67,108,864
-
-// Reused clip scratch (stride 2: u,v). Grown on demand so a single allocation serves the whole soup.
-let _cur = new Float64Array(64);
-let _tmp = new Float64Array(64);
-let _side = new Float64Array(64);
-
-/**
- * Ensure `buf` can hold `vertex_count` (u,v) pairs, returning a large-enough buffer (the same one when
- * it already fits). Contents are not preserved - callers grow before writing.
- *
- * @param {Float64Array} buf
- * @param {number} vertex_count
- * @returns {Float64Array}
- */
-function ensure_capacity(buf, vertex_count) {
-    const needed = vertex_count * 2;
-    if (buf.length >= needed) return buf;
-    let size = buf.length;
-    while (size < needed) size *= 2;
-    return new Float64Array(size);
-}
-
-/**
- * Outward Minkowski-with-disc offset of a convex CCW polygon by `r`: each edge is pushed out by `r` and
- * each convex corner is replaced by a rounded arc. Input/output are flat (u,v) pairs.
- *
- * @param {Float64Array} pts convex CCW polygon (stride 2)
- * @param {number} n vertex count
- * @param {number} r offset radius (> 0)
- * @returns {Float64Array} the offset polygon (CCW, stride 2)
- */
-function offset_convex_ccw(pts, n, r) {
-    // outward edge normals (right of each CCW edge)
-    const enx = new Float64Array(n);
-    const enz = new Float64Array(n);
-    for (let i = 0; i < n; i++) {
-        const j = (i + 1) % n;
-        let dx = pts[j * 2] - pts[i * 2];
-        let dz = pts[j * 2 + 1] - pts[i * 2 + 1];
-        const len = Math.hypot(dx, dz) || 1;
-        dx /= len; dz /= len;
-        enx[i] = dz;    // (dir.v, -dir.u) = right/outward of a CCW edge
-        enz[i] = -dx;
-    }
-
-    const out = [];
-    for (let i = 0; i < n; i++) {
-        const prev_edge = (i - 1 + n) % n; // edge ending at vertex i
-        const next_edge = i;               // edge starting at vertex i
-        const vu = pts[i * 2], vv = pts[i * 2 + 1];
-
-        const a1 = Math.atan2(enz[prev_edge], enx[prev_edge]);
-        const a2 = Math.atan2(enz[next_edge], enx[next_edge]);
-        let da = a2 - a1;
-        while (da < 0) da += 2 * Math.PI;
-        while (da > 2 * Math.PI) da -= 2 * Math.PI;
-
-        const steps = Math.max(1, Math.ceil(da / CORNER_SEGMENT_ANGLE));
-        for (let s = 0; s <= steps; s++) {
-            const a = a1 + da * (s / steps);
-            out.push(vu + r * Math.cos(a), vv + r * Math.sin(a));
-        }
-    }
-
-    return Float64Array.from(out);
-}
-
-/**
- * Normalise `pts` to CCW, dilate it by `r`, and append it to the footprint lists.
- *
- * Footprints with no area are dropped: they carve nothing, and the subtraction needs a real polygon.
- * `pts` is taken over rather than copied, so callers pass a buffer they will not reuse.
- *
- * @param {Float64Array} pts convex polygon (stride 2)
- * @param {number} n vertex count
- * @param {number} height the height this footprint carves from
- * @param {number} r dilation radius
- * @param {Float64Array[]} out_poly
- * @param {number[]} out_h
- */
-function push_footprint(pts, n, height, r, out_poly, out_h) {
-    const area = compute_polygon_area_2d(pts, n);
-
-    // A polygon with no area has no reliable winding either, and `offset_convex_ccw` turns a mis-wound
-    // one inside out - so these are dropped rather than dilated, even though a positive radius would
-    // otherwise give a degenerate footprint a real disc to carve. Only sub-AREA_EPS input reaches this:
-    // at 1e-9 that is an obstacle tens of micrometres across, which is not one.
-    if (Math.abs(area) <= AREA_EPS) {
-        return;
-    }
-
-    let poly = pts;
-
-    // CCW - interior to the left of each edge - is what the subtraction expects
-    if (area < 0) {
-        poly = new Float64Array(n * 2);
-
-        for (let i = 0; i < n; i++) {
-            poly[i * 2] = pts[(n - 1 - i) * 2];
-            poly[i * 2 + 1] = pts[(n - 1 - i) * 2 + 1];
-        }
-    }
-
-    if (r > 0) {
-        poly = offset_convex_ccw(poly, n, r);
-    }
-
-    out_poly.push(poly);
-    out_h.push(height);
-}
-
-/**
- * Append the piece that survives outside one footprint edge, made SEAM-CONFORMING with the pieces on
- * the other side of that edge.
- *
- * Each piece is cut against the LINE of a footprint edge, so its cut edge runs the full width of the
- * piece - past the edge's own endpoints. The other side of that line is subdivided AT those endpoints:
- * the obstacle hole ends where the corner arc begins, and the next piece takes over from there. One
- * edge meeting two is a T-junction, so the faces never fuse into a shared edge and the seam survives
- * into the navmesh as a crack. It bites hardest at a footprint corner that lands a hair inside a source
- * triangle: the piece above the edge is then cut short at the triangle's own boundary, microns from the
- * corner where the pieces below it start - close enough that the T-junction resolver dismisses the
- * corner as that edge's endpoint, far enough that vertex welding leaves the two distinct.
- *
- * Splitting the cut edge at the footprint edge's own endpoints - inserted with their exact coordinates,
- * so both sides of the seam name the same vertex - removes the T-junction at the source.
- *
- * @param {Float64Array} pts piece vertices (stride 2)
- * @param {number} n piece vertex count
- * @param {number} ex
- * @param {number} ez the footprint edge's start
- * @param {number} dx
- * @param {number} dz the footprint edge's extent (end = start + extent)
- * @param {Float64Array[]} out_pieces destination list
- */
-function push_outside_piece(pts, n, ex, ez, dx, dz, out_pieces) {
-    // Distance to the cut line is measured in the clipper's own unnormalized (cross-product) units, so
-    // "on the line" here means exactly what the clip took it to mean.
-    const off_line = (k) => Math.abs(dx * (pts[k * 2 + 1] - ez) - dz * (pts[k * 2] - ex)) > POINT_EPS;
-
-    // the piece edge lying along the cut line - the seam
-    let seam = -1;
-    for (let k = 0; k < n; k++) {
-        if (!off_line(k) && !off_line((k + 1) % n)) { seam = k; break; }
-    }
-
-    if (seam < 0) {
-        // the clip did not cut this piece (it already lay wholly outside), so there is no seam to conform
-        out_pieces.push(pts.slice(0, n * 2));
-        return;
-    }
-
-    // The fan triangulation downstream runs from vertex 0, and a seam vertex inserted below is collinear
-    // with the seam's ends - so with vertex 0 on the seam line its fan triangle is degenerate and gets
-    // dropped, restoring the T-junction. Emit the piece starting from a vertex off the line instead; the
-    // caller only pushes pieces of non-zero area, so one exists.
-    let start = 0;
-    for (let k = 0; k < n; k++) {
-        if (off_line(k)) { start = k; break; }
-    }
-
-    // which of the footprint edge's endpoints fall strictly inside the seam
-    const a_u = pts[seam * 2], a_v = pts[seam * 2 + 1];
-    const b = (seam + 1) % n;
-    const eu = pts[b * 2] - a_u, ev = pts[b * 2 + 1] - a_v;
-    const seam_sq = eu * eu + ev * ev;
-
-    // `along` projects onto the seam scaled by its length, so both endpoint tests compare squared
-    // distances against POINT_EPS without a square root
-    const along_start = (ex - a_u) * eu + (ez - a_v) * ev;
-    const along_end = along_start + dx * eu + dz * ev;
-    const inside = (along) => along > 0 && along < seam_sq
-        && along * along > POINT_EPS * POINT_EPS * seam_sq
-        && (seam_sq - along) * (seam_sq - along) > POINT_EPS * POINT_EPS * seam_sq;
-
-    const take_start = inside(along_start);
-    const take_end = inside(along_end);
-
-    // seam and footprint edge are the same line, so which endpoint comes first along the seam is just
-    // whether the two run the same way
-    const forward = dx * eu + dz * ev > 0;
-    const first_u = forward ? ex : ex + dx, first_v = forward ? ez : ez + dz;
-    const last_u = forward ? ex + dx : ex, last_v = forward ? ez + dz : ez;
-    const take_first = forward ? take_start : take_end;
-    const take_last = forward ? take_end : take_start;
-
-    const out = new Float64Array((n + (take_first ? 1 : 0) + (take_last ? 1 : 0)) * 2);
-    let w = 0;
-    for (let k = 0; k < n; k++) {
-        const v = (start + k) % n;
-        out[w++] = pts[v * 2];
-        out[w++] = pts[v * 2 + 1];
-
-        if (v !== seam) continue;
-
-        if (take_first) { out[w++] = first_u; out[w++] = first_v; }
-        if (take_last) { out[w++] = last_u; out[w++] = last_v; }
-    }
-
-    out_pieces.push(out);
-}
-
-/**
- * Subtract convex footprint `fp` from a single convex polygon, appending the convex, disjoint pieces of
- * (polygon \ fp) to `out_pieces` as right-sized `Float64Array`s. `fp` must be CCW (interior on the left
- * of each edge). The polygon's interior remainder (the part inside `fp`) is discarded.
- *
- * @param {Float64Array} poly polygon vertices (stride 2)
- * @param {number} poly_n polygon vertex count
- * @param {Float64Array} fp footprint vertices (stride 2, CCW)
- * @param {number} fp_n footprint vertex count
- * @param {Float64Array[]} out_pieces destination list; surviving outside pieces are pushed
- */
-function subtract_footprint(poly, poly_n, fp, fp_n, out_pieces) {
-    // current = the running intersection with the inside half-planes processed so far
-    _cur = ensure_capacity(_cur, poly_n + fp_n);
-    _tmp = ensure_capacity(_tmp, poly_n + fp_n);
-    _side = ensure_capacity(_side, poly_n + fp_n);
-
-    let cur = _cur;
-    let tmp = _tmp;
-    for (let i = 0; i < poly_n * 2; i++) cur[i] = poly[i];
-    let cur_n = poly_n;
-
-    for (let i = 0; i < fp_n; i++) {
-        if (cur_n < 3) return; // fully consumed - nothing outside remains
-
-        const j = (i + 1) % fp_n;
-        const ex = fp[i * 2], ez = fp[i * 2 + 1];
-        const dx = fp[j * 2] - ex;
-        const dz = fp[j * 2 + 1] - ez;
-        if (Math.abs(dx) < POINT_EPS && Math.abs(dz) < POINT_EPS) continue; // degenerate edge
-
-        // piece outside this edge (and inside all earlier edges) leaves the footprint here -> it survives
-        const side_n = polygon2_clip_halfplane(cur, cur_n, _side, ex, ez, dx, dz, false);
-        if (side_n >= 3 && Math.abs(compute_polygon_area_2d(_side, side_n)) > AREA_EPS) {
-            push_outside_piece(_side, side_n, ex, ez, dx, dz, out_pieces);
-        }
-
-        // keep marching with the part still inside this edge
-        cur_n = polygon2_clip_halfplane(cur, cur_n, tmp, ex, ez, dx, dz, true);
-        const swap = cur; cur = tmp; tmp = swap;
-    }
-}
-
-/**
- * @param {number[]} soup flat XYZ triangle soup (9 floats per triangle)
- * @param {number} triangle_count
- * @param {BinaryTopology} source source mesh (face normals must be populated)
- * @param {number} agent_height
- * @param {number} agent_radius dilation applied to each footprint
- * @param {Vector3} up
- * @returns {number[]} new soup with (dilated) obstacle footprints removed
- */
-export function clip_soup_against_overhangs(soup, triangle_count, source, agent_height, agent_radius, up) {
-    let upx = up.x, upy = up.y, upz = up.z;
-    const ul = Math.hypot(upx, upy, upz);
-    if (ul === 0) return soup.slice(0, triangle_count * 9);
-    upx /= ul; upy /= ul; upz /= ul;
-
-    // orthonormal basis: rows 0,1 span the plane perpendicular to up (our u,v axes), row 2 is up itself
-    const basis = new Float64Array(9);
-    v3_orthonormal_matrix_from_normal(basis, 0, upx, upy, upz);
-    const u_x = basis[0], u_y = basis[1], u_z = basis[2];
-    const v_x = basis[3], v_y = basis[4], v_z = basis[5];
-
-    // collect downward-facing (overhead) source triangles as flat (u,v) triples plus their mean height
-    const overhead_uv = []; // stride 6: u0,v0,u1,v1,u2,v2
-    const overhead_h = [];
-    const fn = new Float32Array(3);
-    const fc = new Float32Array(3);
-    const face_count = source.faces.size;
-    for (let f = 0; f < face_count; f++) {
-        if (!source.faces.is_allocated(f)) continue;
-        source.face_read_normal(fn, 0, f);
-        if (fn[0] * upx + fn[1] * upy + fn[2] * upz >= -HEIGHT_EPS) continue; // not downward-facing
-
-        let l = source.face_read_loop(f);
-        let hsum = 0;
-        for (let k = 0; k < 3; k++) {
-            source.vertex_read_coordinate(fc, 0, source.loop_read_vertex(l));
-            const x = fc[0], y = fc[1], z = fc[2];
-            overhead_uv.push(v3_dot(x, y, z, u_x, u_y, u_z), v3_dot(x, y, z, v_x, v_y, v_z));
-            hsum += v3_dot(x, y, z, upx, upy, upz);
-            l = source.loop_read_next(l);
-        }
-        overhead_h.push(hsum / 3);
-    }
-
-    const overhead_count = overhead_h.length;
-    if (overhead_count === 0) return soup.slice(0, triangle_count * 9);
-
-    // Group overhead triangles that share a (coincident) vertex into one obstacle. Each obstacle's
-    // footprint is the convex hull of its vertices, dilated by the agent radius. Treating the obstacle
-    // as one polygon (rather than per-triangle) avoids self-touching/pinched union boundaries.
-    const parent = new Int32Array(overhead_count);
-    for (let i = 0; i < overhead_count; i++) parent[i] = i;
-    const find = (a) => { while (parent[a] !== a) { parent[a] = parent[parent[a]]; a = parent[a]; } return a; };
-
-    const key_to_tri = new Map();
-    for (let i = 0; i < overhead_count; i++) {
-        for (let k = 0; k < 3; k++) {
-            const ku = Math.round(overhead_uv[i * 6 + k * 2] * QUANTIZE);
-            const kv = Math.round(overhead_uv[i * 6 + k * 2 + 1] * QUANTIZE);
-            const key = (ku + KEY_BIAS) * KEY_STRIDE + (kv + KEY_BIAS);
-            const seen = key_to_tri.get(key);
-            if (seen !== undefined) parent[find(i)] = find(seen); else key_to_tri.set(key, i);
-        }
-    }
-
-    /** @type {Map<number, {pts: number[], members: number[], hsum: number}>} */
-    const groups = new Map();
-    for (let i = 0; i < overhead_count; i++) {
-        const root = find(i);
-        let g = groups.get(root);
-        if (g === undefined) { g = { pts: [], members: [], hsum: 0 }; groups.set(root, g); }
-        for (let k = 0; k < 6; k++) g.pts.push(overhead_uv[i * 6 + k]);
-        g.members.push(i);
-        g.hsum += overhead_h[i];
-    }
-
-    // Each footprint: a CCW (dilated) convex polygon in (u,v) plus the height it carves from.
-    //
-    // A group's convex hull is its footprint only when the group's triangles TILE that hull. An L, a
-    // ring, or two obstacles that merely touch do not, and their hull spans ground nothing is above -
-    // carving it takes away walkable area no obstacle covers. A doorway frame is a ring, and hulling
-    // one fills in the doorway. Comparing the hull's area against the triangles' own tells the two
-    // cases apart: a tiling leaves no slack, and the hull is then used exactly as before.
-    //
-    // Matching areas is the safe direction to be wrong in. Any duplicated or overlapping overhead area
-    // pushes a group off the hull and onto the per-triangle route, which is correct either way. The one
-    // input that defeats it is duplicate area equal to the hull's slack to within the epsilon, and what
-    // that costs is the hull carve this has always done.
-    //
-    // Where they do not tile it, each triangle is carved on its own. That is exact, not merely safer:
-    // dilation by a disc distributes over union - (A u B) (+) D = (A (+) D) u (B (+) D) - so
-    // subtracting each triangle's own dilated footprint in turn removes precisely the dilated union,
-    // which is the true offset of an arbitrarily concave obstacle. The carve loop below subtracts
-    // footprints sequentially from a running set of pieces, so the result stays a partition of the
-    // soup triangle and the footprints never cut across one another.
-    /** @type {Float64Array[]} */
-    const footprint_poly = [];
-    const footprint_h = [];
-    for (const g of groups.values()) {
-        const member_count = g.members.length;
-        const hull = convex_hull_monotone_2d(g.pts, g.pts.length / 2);
-
-        if (hull.length >= 3) {
-            const hull_poly = new Float64Array(hull.length * 2);
-            for (let i = 0; i < hull.length; i++) {
-                hull_poly[i * 2] = g.pts[hull[i] * 2];
-                hull_poly[i * 2 + 1] = g.pts[hull[i] * 2 + 1];
-            }
-
-            const hull_area = Math.abs(compute_polygon_area_2d(hull_poly, hull.length));
-
-            let member_area = 0;
-            for (let m = 0; m < member_count; m++) {
-                const b = g.members[m] * 6;
-                member_area += Math.abs(
-                    (overhead_uv[b + 2] - overhead_uv[b]) * (overhead_uv[b + 5] - overhead_uv[b + 1])
-                    - (overhead_uv[b + 4] - overhead_uv[b]) * (overhead_uv[b + 3] - overhead_uv[b + 1])
-                ) * 0.5;
-            }
-
-            // `member_area` at zero means every triangle in the group is degenerate. The hull is then
-            // all there is to go on, and it is what this has always carved - leave that alone.
-            const tiles_hull = member_area <= AREA_EPS
-                || Math.abs(hull_area - member_area) <= Math.max(AREA_EPS, hull_area * HULL_TILING_RELATIVE_EPS);
-
-            if (tiles_hull) {
-                push_footprint(
-                    hull_poly, hull.length, g.hsum / member_count,
-                    agent_radius, footprint_poly, footprint_h
-                );
-
-                continue;
-            }
-        }
-
-        for (let m = 0; m < member_count; m++) {
-            const i = g.members[m];
-            const b = i * 6;
-
-            push_footprint(
-                Float64Array.of(
-                    overhead_uv[b], overhead_uv[b + 1],
-                    overhead_uv[b + 2], overhead_uv[b + 3],
-                    overhead_uv[b + 4], overhead_uv[b + 5]
-                ),
-                3, overhead_h[i],
-                agent_radius, footprint_poly, footprint_h
-            );
-        }
-    }
-
-    const footprint_count = footprint_poly.length;
-    if (footprint_count === 0) return soup.slice(0, triangle_count * 9);
-
-    // Broad-phase index: one leaf per footprint, in (u, v, height) space. The first two axes are the
-    // dilated footprint's (u,v) extent; the third is the band of soup heights it can carve - a triangle
-    // at mean height `th` is carved by an obstacle at height `h` iff 0 < h - th <= agent_height. A soup
-    // triangle then queries this BVH with its own (u,v) extent at `th` to get just the candidate
-    // obstacles, instead of scanning all of them.
-    const footprint_bvh = new BVH();
-    footprint_bvh.release_all();
-    for (let fi = 0; fi < footprint_count; fi++) {
-        const poly = footprint_poly[fi];
-        let min_u = Infinity, min_v = Infinity, max_u = -Infinity, max_v = -Infinity;
-        for (let i = 0; i < poly.length; i += 2) {
-            const u = poly[i], v = poly[i + 1];
-            if (u < min_u) min_u = u;
-            if (u > max_u) max_u = u;
-            if (v < min_v) min_v = v;
-            if (v > max_v) max_v = v;
-        }
-        const h = footprint_h[fi];
-        const node = footprint_bvh.allocate_node();
-        footprint_bvh.node_set_user_data(node, fi);
-        footprint_bvh.node_set_aabb_primitive(
-            node,
-            min_u, min_v, h - agent_height - HEIGHT_EPS,
-            max_u, max_v, h - HEIGHT_EPS
-        );
-        footprint_bvh.insert_leaf(node);
-    }
-
-    const out = [];
-
-    // per-triangle reusable storage
-    const tri_uv = new Float64Array(6);          // u0,v0,u1,v1,u2,v2 of the source triangle
-    const px = new Float64Array(3), py = new Float64Array(3), pz = new Float64Array(3);
-    const query_aabb = new Float64Array(6);
-    const query_hits = new Int32Array(footprint_count);
-    /** @type {Float64Array[]} */
-    let pieces = [];
-    /** @type {Float64Array[]} */
-    let next_pieces = [];
-
-    for (let t = 0; t < triangle_count; t++) {
-        const o = t * 9;
-
-        let th = 0;
-        for (let k = 0; k < 3; k++) {
-            const x = soup[o + k * 3], y = soup[o + k * 3 + 1], z = soup[o + k * 3 + 2];
-            px[k] = x; py[k] = y; pz[k] = z;
-            tri_uv[k * 2] = v3_dot(x, y, z, u_x, u_y, u_z);
-            tri_uv[k * 2 + 1] = v3_dot(x, y, z, v_x, v_y, v_z);
-            th += v3_dot(x, y, z, upx, upy, upz);
-        }
-        th /= 3;
-
-        // barycentric denominator (twice the signed uv area of the triangle)
-        const e1u = tri_uv[2] - tri_uv[0], e1v = tri_uv[3] - tri_uv[1];
-        const e2u = tri_uv[4] - tri_uv[0], e2v = tri_uv[5] - tri_uv[1];
-        const det = e1u * e2v - e2u * e1v;
-
-        if (Math.abs(det) <= AREA_EPS) {
-            // degenerate in (u,v) (a near-vertical triangle): cannot carve meaningfully, pass through
-            for (let i = 0; i < 9; i++) out.push(soup[o + i]);
-            continue;
-        }
-
-        // broad-phase: only the obstacles whose (u,v) extent and height band overlap this triangle
-        let min_u = tri_uv[0], max_u = tri_uv[0], min_v = tri_uv[1], max_v = tri_uv[1];
-        for (let k = 1; k < 3; k++) {
-            const u = tri_uv[k * 2], v = tri_uv[k * 2 + 1];
-            if (u < min_u) min_u = u;
-            if (u > max_u) max_u = u;
-            if (v < min_v) min_v = v;
-            if (v > max_v) max_v = v;
-        }
-        query_aabb[0] = min_u; query_aabb[1] = min_v; query_aabb[2] = th;
-        query_aabb[3] = max_u; query_aabb[4] = max_v; query_aabb[5] = th;
-
-        const hit_count = bvh_query_user_data_intersects_aabb(query_hits, 0, footprint_bvh, query_aabb);
-        if (hit_count === 0) {
-            // no obstacle overlaps here - copy straight through
-            for (let i = 0; i < 9; i++) out.push(soup[o + i]);
-            continue;
-        }
-
-        // start with the whole triangle as one piece, then subtract each overlapping footprint
-        pieces.length = 0;
-        pieces.push(Float64Array.of(tri_uv[0], tri_uv[1], tri_uv[2], tri_uv[3], tri_uv[4], tri_uv[5]));
-
-        for (let qi = 0; qi < hit_count; qi++) {
-            const fi = query_hits[qi];
-            const dh = footprint_h[fi] - th;
-            if (dh <= HEIGHT_EPS || dh > agent_height + HEIGHT_EPS) continue; // exact band test
-
-            const fp = footprint_poly[fi];
-            const fp_n = fp.length / 2;
-
-            next_pieces.length = 0;
-            for (let pi = 0; pi < pieces.length; pi++) {
-                subtract_footprint(pieces[pi], pieces[pi].length / 2, fp, fp_n, next_pieces);
-            }
-
-            const swap = pieces; pieces = next_pieces; next_pieces = swap;
-            if (pieces.length === 0) break;
-        }
-
-        const inv_det = 1 / det;
-        for (let pi = 0; pi < pieces.length; pi++) {
-            const poly = pieces[pi];
-            const poly_n = poly.length / 2;
-
-            // fan-triangulate the surviving piece and reconstruct world XYZ per vertex
-            for (let i = 1; i + 1 < poly_n; i++) {
-                const u0 = poly[0], v0 = poly[1];
-                const u1 = poly[i * 2], v1 = poly[i * 2 + 1];
-                const u2 = poly[(i + 1) * 2], v2 = poly[(i + 1) * 2 + 1];
-
-                const area2 = Math.abs((u1 - u0) * (v2 - v0) - (u2 - u0) * (v1 - v0));
-                if (area2 < 2 * AREA_EPS) continue;
-
-                emit_xyz(out, u0, v0, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
-                emit_xyz(out, u1, v1, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
-                emit_xyz(out, u2, v2, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
-            }
-        }
-    }
-
-    return out;
-}
-
-/**
- * Reconstruct the world XYZ of a (u,v) point lying in a source triangle (barycentric on the triangle's
- * planar uv coordinates) and append it to `out`.
- *
- * @param {number[]} out destination soup
- * @param {number} u
- * @param {number} v the point in (u,v)
- * @param {Float64Array} tri_uv the triangle's uv corners (stride 2, vertex 0 is the origin)
- * @param {Float64Array} px
- * @param {Float64Array} py
- * @param {Float64Array} pz the triangle's world corners
- * @param {number} e1u
- * @param {number} e1v edge (v1 - v0) in uv
- * @param {number} e2u
- * @param {number} e2v edge (v2 - v0) in uv
- * @param {number} inv_det reciprocal of the uv area determinant
- */
-function emit_xyz(out, u, v, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det) {
-    const du = u - tri_uv[0];
-    const dv = v - tri_uv[1];
-    const w1 = (du * e2v - e2u * dv) * inv_det;
-    const w2 = (e1u * dv - du * e1v) * inv_det;
-    const w0 = 1 - w1 - w2;
-
-    out.push(
-        w0 * px[0] + w1 * px[1] + w2 * px[2],
-        w0 * py[0] + w1 * py[1] + w2 * py[2],
-        w0 * pz[0] + w1 * pz[1] + w2 * pz[2]
-    );
-}
+/**
+ * Exact obstacle carving at the triangle-soup level, with a faithful agent-radius offset.
+ *
+ * Each overhead obstacle's footprint is DILATED by the agent radius (Minkowski sum with a disc: edges
+ * pushed out by r, convex corners replaced by a rounded arc), and that dilated polygon is subtracted
+ * from the walkable triangles. The resulting hole boundary is therefore the true offset of the
+ * obstacle - straight along edges, a clean arc at corners - rather than a wavy/mitred contour produced
+ * by sampling-then-eroding. (Run AFTER the outer boundary has been eroded by r, so the obstacle holes
+ * are not eroded a second time.)
+ *
+ * Overhead obstacles are the DOWNWARD-facing source faces; a face carves a walkable triangle only where
+ * it sits above it, within `agent_height`.
+ *
+ * An obstacle is a group of overhead faces that share a vertex. A group is carved as its convex hull
+ * when its triangles TILE that hull, and triangle by triangle when they do not - a concave or holed
+ * obstacle (an L, a doorway frame), or two obstacles that merely touch. Both routes carve the same
+ * ground wherever the hull is valid, because dilation by a disc distributes over union; the hull is
+ * kept only because it is the cheaper of the two.
+ *
+ * The subtraction uses the disjoint half-plane decomposition of a convex-polygon difference:
+ *     T \ F = U_i ( T ∩ inside(e_0..e_{i-1}) ∩ outside(e_i) )
+ * each term convex, the terms disjoint, the union exactly T minus the convex (dilated) footprint F.
+ * Each term is cut against the LINE of e_i rather than the edge itself, so its cut edge overshoots that
+ * edge's endpoints; splitting it back at them (see {@link push_outside_piece}) keeps the pieces
+ * conforming, so the seams fuse into shared edges instead of leaving T-junctions.
+ *
+ * Everything is data-oriented: clipping happens in the 2D plane perpendicular to `up`, with polygons
+ * held as flat `Float64Array`s of (u,v) pairs and a small set of reused scratch buffers. World XYZ is
+ * recovered for each surviving vertex by barycentric reconstruction on its (planar) source triangle, so
+ * kept pieces stay exactly on the original - possibly tilted - walkable plane. Degenerate triangles are
+ * dropped, and triangles that no footprint overlaps are copied straight through without allocation.
+ *
+ * The footprints are indexed in a BVH (keyed by their (u,v) extent and carve height band), so each soup
+ * triangle only tests the footprints that can actually overlap it - O(m log k) rather than O(m k) for m
+ * soup triangles and k footprints.
+ */
+
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import { bvh_query_user_data_intersects_aabb } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
+import { v3_dot } from "../../../../core/geom/vec3/v3_dot.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+import { convex_hull_monotone_2d } from "../../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
+import { polygon2_signed_area } from "../../../../core/geom/2d/polygon/polygon2_signed_area.js";
+import { polygon2_clip_halfplane } from "../../../../core/geom/2d/polygon/polygon2_clip_halfplane.js";
+
+const POINT_EPS = 1e-9;
+const AREA_EPS = 1e-9;
+const HEIGHT_EPS = 1e-3;
+const CORNER_SEGMENT_ANGLE = Math.PI / 6; // ~30 deg per rounded-corner segment
+// How closely a group's triangles must add up to the area of their own convex hull before that hull
+// is accepted as the group's footprint (see the footprint build). Relative, so it means the same thing
+// at any obstacle size.
+//
+// Loose on purpose. The quantity it has to resolve is a real concavity - a notch, a ring's hole, the
+// space between two obstacles that touch - which is a substantial fraction of the hull, never one part
+// in a million of it. Meanwhile the shoelace sums it compares lose absolute precision as the geometry
+// moves away from the origin (~1e-8 at 10,000 units), and a threshold down at that level would start
+// reading noise as concavity. Erring loose only ever sends a group to the hull, which is what it
+// always used; erring tight sends convex groups down the slower per-triangle route for nothing.
+const HULL_TILING_RELATIVE_EPS = 1e-6;
+
+// Vertex coincidence key. Quantize each projected coordinate to QUANTIZE (1mm) and pack the two integer
+// coordinates into one safe-integer key: cheaper than a string and with no per-probe allocation. Each
+// axis occupies a biased 26-bit field, so the key stays unique while |u|,|v| < 2^25 / QUANTIZE
+// (~33,000 units). A 16-bit-per-axis pack would only reach ~3.3 units and silently collide - navmesh
+// coordinates routinely exceed that (e.g. geometry built 10,000 units from the origin). Coincident
+// vertices are the same source vertex projected identically, so they match at any quantization; the
+// precision only needs to keep genuinely distinct obstacle corners apart (the smallest is ~0.3 units).
+const QUANTIZE = 1e3;
+const KEY_BIAS = 1 << 25;   // 33,554,432
+const KEY_STRIDE = 1 << 26; // 67,108,864
+
+// Reused clip scratch (stride 2: u,v). Grown on demand so a single allocation serves the whole soup.
+let _cur = new Float64Array(64);
+let _tmp = new Float64Array(64);
+let _side = new Float64Array(64);
+
+/**
+ * Ensure `buf` can hold `vertex_count` (u,v) pairs, returning a large-enough buffer (the same one when
+ * it already fits). Contents are not preserved - callers grow before writing.
+ *
+ * @param {Float64Array} buf
+ * @param {number} vertex_count
+ * @returns {Float64Array}
+ */
+function ensure_capacity(buf, vertex_count) {
+    const needed = vertex_count * 2;
+    if (buf.length >= needed) return buf;
+    let size = buf.length;
+    while (size < needed) size *= 2;
+    return new Float64Array(size);
+}
+
+/**
+ * Outward Minkowski-with-disc offset of a convex CCW polygon by `r`: each edge is pushed out by `r` and
+ * each convex corner is replaced by a rounded arc. Input/output are flat (u,v) pairs.
+ *
+ * @param {Float64Array} pts convex CCW polygon (stride 2)
+ * @param {number} n vertex count
+ * @param {number} r offset radius (> 0)
+ * @returns {Float64Array} the offset polygon (CCW, stride 2)
+ */
+function offset_convex_ccw(pts, n, r) {
+    // outward edge normals (right of each CCW edge)
+    const enx = new Float64Array(n);
+    const enz = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const j = (i + 1) % n;
+        let dx = pts[j * 2] - pts[i * 2];
+        let dz = pts[j * 2 + 1] - pts[i * 2 + 1];
+        const len = Math.hypot(dx, dz) || 1;
+        dx /= len; dz /= len;
+        enx[i] = dz;    // (dir.v, -dir.u) = right/outward of a CCW edge
+        enz[i] = -dx;
+    }
+
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const prev_edge = (i - 1 + n) % n; // edge ending at vertex i
+        const next_edge = i;               // edge starting at vertex i
+        const vu = pts[i * 2], vv = pts[i * 2 + 1];
+
+        const a1 = Math.atan2(enz[prev_edge], enx[prev_edge]);
+        const a2 = Math.atan2(enz[next_edge], enx[next_edge]);
+        let da = a2 - a1;
+        while (da < 0) da += 2 * Math.PI;
+        while (da > 2 * Math.PI) da -= 2 * Math.PI;
+
+        const steps = Math.max(1, Math.ceil(da / CORNER_SEGMENT_ANGLE));
+        for (let s = 0; s <= steps; s++) {
+            const a = a1 + da * (s / steps);
+            out.push(vu + r * Math.cos(a), vv + r * Math.sin(a));
+        }
+    }
+
+    return Float64Array.from(out);
+}
+
+/**
+ * Normalise `pts` to CCW, dilate it by `r`, and append it to the footprint lists.
+ *
+ * Footprints with no area are dropped: they carve nothing, and the subtraction needs a real polygon.
+ * `pts` is taken over rather than copied, so callers pass a buffer they will not reuse.
+ *
+ * @param {Float64Array} pts convex polygon (stride 2)
+ * @param {number} n vertex count
+ * @param {number} height the height this footprint carves from
+ * @param {number} r dilation radius
+ * @param {Float64Array[]} out_poly
+ * @param {number[]} out_h
+ */
+function push_footprint(pts, n, height, r, out_poly, out_h) {
+    const area = polygon2_signed_area(pts, n);
+
+    // A polygon with no area has no reliable winding either, and `offset_convex_ccw` turns a mis-wound
+    // one inside out - so these are dropped rather than dilated, even though a positive radius would
+    // otherwise give a degenerate footprint a real disc to carve. Only sub-AREA_EPS input reaches this:
+    // at 1e-9 that is an obstacle tens of micrometres across, which is not one.
+    if (Math.abs(area) <= AREA_EPS) {
+        return;
+    }
+
+    let poly = pts;
+
+    // CCW - interior to the left of each edge - is what the subtraction expects
+    if (area < 0) {
+        poly = new Float64Array(n * 2);
+
+        for (let i = 0; i < n; i++) {
+            poly[i * 2] = pts[(n - 1 - i) * 2];
+            poly[i * 2 + 1] = pts[(n - 1 - i) * 2 + 1];
+        }
+    }
+
+    if (r > 0) {
+        poly = offset_convex_ccw(poly, n, r);
+    }
+
+    out_poly.push(poly);
+    out_h.push(height);
+}
+
+/**
+ * Append the piece that survives outside one footprint edge, made SEAM-CONFORMING with the pieces on
+ * the other side of that edge.
+ *
+ * Each piece is cut against the LINE of a footprint edge, so its cut edge runs the full width of the
+ * piece - past the edge's own endpoints. The other side of that line is subdivided AT those endpoints:
+ * the obstacle hole ends where the corner arc begins, and the next piece takes over from there. One
+ * edge meeting two is a T-junction, so the faces never fuse into a shared edge and the seam survives
+ * into the navmesh as a crack. It bites hardest at a footprint corner that lands a hair inside a source
+ * triangle: the piece above the edge is then cut short at the triangle's own boundary, microns from the
+ * corner where the pieces below it start - close enough that the T-junction resolver dismisses the
+ * corner as that edge's endpoint, far enough that vertex welding leaves the two distinct.
+ *
+ * Splitting the cut edge at the footprint edge's own endpoints - inserted with their exact coordinates,
+ * so both sides of the seam name the same vertex - removes the T-junction at the source.
+ *
+ * @param {Float64Array} pts piece vertices (stride 2)
+ * @param {number} n piece vertex count
+ * @param {number} ex
+ * @param {number} ez the footprint edge's start
+ * @param {number} dx
+ * @param {number} dz the footprint edge's extent (end = start + extent)
+ * @param {Float64Array[]} out_pieces destination list
+ */
+function push_outside_piece(pts, n, ex, ez, dx, dz, out_pieces) {
+    // Distance to the cut line is measured in the clipper's own unnormalized (cross-product) units, so
+    // "on the line" here means exactly what the clip took it to mean.
+    const off_line = (k) => Math.abs(dx * (pts[k * 2 + 1] - ez) - dz * (pts[k * 2] - ex)) > POINT_EPS;
+
+    // the piece edge lying along the cut line - the seam
+    let seam = -1;
+    for (let k = 0; k < n; k++) {
+        if (!off_line(k) && !off_line((k + 1) % n)) { seam = k; break; }
+    }
+
+    if (seam < 0) {
+        // the clip did not cut this piece (it already lay wholly outside), so there is no seam to conform
+        out_pieces.push(pts.slice(0, n * 2));
+        return;
+    }
+
+    // The fan triangulation downstream runs from vertex 0, and a seam vertex inserted below is collinear
+    // with the seam's ends - so with vertex 0 on the seam line its fan triangle is degenerate and gets
+    // dropped, restoring the T-junction. Emit the piece starting from a vertex off the line instead; the
+    // caller only pushes pieces of non-zero area, so one exists.
+    let start = 0;
+    for (let k = 0; k < n; k++) {
+        if (off_line(k)) { start = k; break; }
+    }
+
+    // which of the footprint edge's endpoints fall strictly inside the seam
+    const a_u = pts[seam * 2], a_v = pts[seam * 2 + 1];
+    const b = (seam + 1) % n;
+    const eu = pts[b * 2] - a_u, ev = pts[b * 2 + 1] - a_v;
+    const seam_sq = eu * eu + ev * ev;
+
+    // `along` projects onto the seam scaled by its length, so both endpoint tests compare squared
+    // distances against POINT_EPS without a square root
+    const along_start = (ex - a_u) * eu + (ez - a_v) * ev;
+    const along_end = along_start + dx * eu + dz * ev;
+    const inside = (along) => along > 0 && along < seam_sq
+        && along * along > POINT_EPS * POINT_EPS * seam_sq
+        && (seam_sq - along) * (seam_sq - along) > POINT_EPS * POINT_EPS * seam_sq;
+
+    const take_start = inside(along_start);
+    const take_end = inside(along_end);
+
+    // seam and footprint edge are the same line, so which endpoint comes first along the seam is just
+    // whether the two run the same way
+    const forward = dx * eu + dz * ev > 0;
+    const first_u = forward ? ex : ex + dx, first_v = forward ? ez : ez + dz;
+    const last_u = forward ? ex + dx : ex, last_v = forward ? ez + dz : ez;
+    const take_first = forward ? take_start : take_end;
+    const take_last = forward ? take_end : take_start;
+
+    const out = new Float64Array((n + (take_first ? 1 : 0) + (take_last ? 1 : 0)) * 2);
+    let w = 0;
+    for (let k = 0; k < n; k++) {
+        const v = (start + k) % n;
+        out[w++] = pts[v * 2];
+        out[w++] = pts[v * 2 + 1];
+
+        if (v !== seam) continue;
+
+        if (take_first) { out[w++] = first_u; out[w++] = first_v; }
+        if (take_last) { out[w++] = last_u; out[w++] = last_v; }
+    }
+
+    out_pieces.push(out);
+}
+
+/**
+ * Subtract convex footprint `fp` from a single convex polygon, appending the convex, disjoint pieces of
+ * (polygon \ fp) to `out_pieces` as right-sized `Float64Array`s. `fp` must be CCW (interior on the left
+ * of each edge). The polygon's interior remainder (the part inside `fp`) is discarded.
+ *
+ * @param {Float64Array} poly polygon vertices (stride 2)
+ * @param {number} poly_n polygon vertex count
+ * @param {Float64Array} fp footprint vertices (stride 2, CCW)
+ * @param {number} fp_n footprint vertex count
+ * @param {Float64Array[]} out_pieces destination list; surviving outside pieces are pushed
+ */
+function subtract_footprint(poly, poly_n, fp, fp_n, out_pieces) {
+    // current = the running intersection with the inside half-planes processed so far
+    _cur = ensure_capacity(_cur, poly_n + fp_n);
+    _tmp = ensure_capacity(_tmp, poly_n + fp_n);
+    _side = ensure_capacity(_side, poly_n + fp_n);
+
+    let cur = _cur;
+    let tmp = _tmp;
+    for (let i = 0; i < poly_n * 2; i++) cur[i] = poly[i];
+    let cur_n = poly_n;
+
+    for (let i = 0; i < fp_n; i++) {
+        if (cur_n < 3) return; // fully consumed - nothing outside remains
+
+        const j = (i + 1) % fp_n;
+        const ex = fp[i * 2], ez = fp[i * 2 + 1];
+        const dx = fp[j * 2] - ex;
+        const dz = fp[j * 2 + 1] - ez;
+        if (Math.abs(dx) < POINT_EPS && Math.abs(dz) < POINT_EPS) continue; // degenerate edge
+
+        // piece outside this edge (and inside all earlier edges) leaves the footprint here -> it survives
+        const side_n = polygon2_clip_halfplane(cur, cur_n, _side, ex, ez, dx, dz, false);
+        if (side_n >= 3 && Math.abs(polygon2_signed_area(_side, side_n)) > AREA_EPS) {
+            push_outside_piece(_side, side_n, ex, ez, dx, dz, out_pieces);
+        }
+
+        // keep marching with the part still inside this edge
+        cur_n = polygon2_clip_halfplane(cur, cur_n, tmp, ex, ez, dx, dz, true);
+        const swap = cur; cur = tmp; tmp = swap;
+    }
+}
+
+/**
+ * @param {number[]} soup flat XYZ triangle soup (9 floats per triangle)
+ * @param {number} triangle_count
+ * @param {BinaryTopology} source source mesh (face normals must be populated)
+ * @param {number} agent_height
+ * @param {number} agent_radius dilation applied to each footprint
+ * @param {Vector3} up
+ * @returns {number[]} new soup with (dilated) obstacle footprints removed
+ */
+export function clip_soup_against_overhangs(soup, triangle_count, source, agent_height, agent_radius, up) {
+    let upx = up.x, upy = up.y, upz = up.z;
+    const ul = Math.hypot(upx, upy, upz);
+    if (ul === 0) return soup.slice(0, triangle_count * 9);
+    upx /= ul; upy /= ul; upz /= ul;
+
+    // orthonormal basis: rows 0,1 span the plane perpendicular to up (our u,v axes), row 2 is up itself
+    const basis = new Float64Array(9);
+    v3_orthonormal_matrix_from_normal(basis, 0, upx, upy, upz);
+    const u_x = basis[0], u_y = basis[1], u_z = basis[2];
+    const v_x = basis[3], v_y = basis[4], v_z = basis[5];
+
+    // collect downward-facing (overhead) source triangles as flat (u,v) triples plus their mean height
+    const overhead_uv = []; // stride 6: u0,v0,u1,v1,u2,v2
+    const overhead_h = [];
+    const fn = new Float32Array(3);
+    const fc = new Float32Array(3);
+    const face_count = source.faces.size;
+    for (let f = 0; f < face_count; f++) {
+        if (!source.faces.is_allocated(f)) continue;
+        source.face_read_normal(fn, 0, f);
+        if (fn[0] * upx + fn[1] * upy + fn[2] * upz >= -HEIGHT_EPS) continue; // not downward-facing
+
+        let l = source.face_read_loop(f);
+        let hsum = 0;
+        for (let k = 0; k < 3; k++) {
+            source.vertex_read_coordinate(fc, 0, source.loop_read_vertex(l));
+            const x = fc[0], y = fc[1], z = fc[2];
+            overhead_uv.push(v3_dot(x, y, z, u_x, u_y, u_z), v3_dot(x, y, z, v_x, v_y, v_z));
+            hsum += v3_dot(x, y, z, upx, upy, upz);
+            l = source.loop_read_next(l);
+        }
+        overhead_h.push(hsum / 3);
+    }
+
+    const overhead_count = overhead_h.length;
+    if (overhead_count === 0) return soup.slice(0, triangle_count * 9);
+
+    // Group overhead triangles that share a (coincident) vertex into one obstacle. Each obstacle's
+    // footprint is the convex hull of its vertices, dilated by the agent radius. Treating the obstacle
+    // as one polygon (rather than per-triangle) avoids self-touching/pinched union boundaries.
+    const parent = new Int32Array(overhead_count);
+    for (let i = 0; i < overhead_count; i++) parent[i] = i;
+    const find = (a) => { while (parent[a] !== a) { parent[a] = parent[parent[a]]; a = parent[a]; } return a; };
+
+    const key_to_tri = new Map();
+    for (let i = 0; i < overhead_count; i++) {
+        for (let k = 0; k < 3; k++) {
+            const ku = Math.round(overhead_uv[i * 6 + k * 2] * QUANTIZE);
+            const kv = Math.round(overhead_uv[i * 6 + k * 2 + 1] * QUANTIZE);
+            const key = (ku + KEY_BIAS) * KEY_STRIDE + (kv + KEY_BIAS);
+            const seen = key_to_tri.get(key);
+            if (seen !== undefined) parent[find(i)] = find(seen); else key_to_tri.set(key, i);
+        }
+    }
+
+    /** @type {Map<number, {pts: number[], members: number[], hsum: number}>} */
+    const groups = new Map();
+    for (let i = 0; i < overhead_count; i++) {
+        const root = find(i);
+        let g = groups.get(root);
+        if (g === undefined) { g = { pts: [], members: [], hsum: 0 }; groups.set(root, g); }
+        for (let k = 0; k < 6; k++) g.pts.push(overhead_uv[i * 6 + k]);
+        g.members.push(i);
+        g.hsum += overhead_h[i];
+    }
+
+    // Each footprint: a CCW (dilated) convex polygon in (u,v) plus the height it carves from.
+    //
+    // A group's convex hull is its footprint only when the group's triangles TILE that hull. An L, a
+    // ring, or two obstacles that merely touch do not, and their hull spans ground nothing is above -
+    // carving it takes away walkable area no obstacle covers. A doorway frame is a ring, and hulling
+    // one fills in the doorway. Comparing the hull's area against the triangles' own tells the two
+    // cases apart: a tiling leaves no slack, and the hull is then used exactly as before.
+    //
+    // Matching areas is the safe direction to be wrong in. Any duplicated or overlapping overhead area
+    // pushes a group off the hull and onto the per-triangle route, which is correct either way. The one
+    // input that defeats it is duplicate area equal to the hull's slack to within the epsilon, and what
+    // that costs is the hull carve this has always done.
+    //
+    // Where they do not tile it, each triangle is carved on its own. That is exact, not merely safer:
+    // dilation by a disc distributes over union - (A u B) (+) D = (A (+) D) u (B (+) D) - so
+    // subtracting each triangle's own dilated footprint in turn removes precisely the dilated union,
+    // which is the true offset of an arbitrarily concave obstacle. The carve loop below subtracts
+    // footprints sequentially from a running set of pieces, so the result stays a partition of the
+    // soup triangle and the footprints never cut across one another.
+    /** @type {Float64Array[]} */
+    const footprint_poly = [];
+    const footprint_h = [];
+    for (const g of groups.values()) {
+        const member_count = g.members.length;
+        const hull = convex_hull_monotone_2d(g.pts, g.pts.length / 2);
+
+        if (hull.length >= 3) {
+            const hull_poly = new Float64Array(hull.length * 2);
+            for (let i = 0; i < hull.length; i++) {
+                hull_poly[i * 2] = g.pts[hull[i] * 2];
+                hull_poly[i * 2 + 1] = g.pts[hull[i] * 2 + 1];
+            }
+
+            const hull_area = Math.abs(polygon2_signed_area(hull_poly, hull.length));
+
+            let member_area = 0;
+            for (let m = 0; m < member_count; m++) {
+                const b = g.members[m] * 6;
+                member_area += Math.abs(
+                    (overhead_uv[b + 2] - overhead_uv[b]) * (overhead_uv[b + 5] - overhead_uv[b + 1])
+                    - (overhead_uv[b + 4] - overhead_uv[b]) * (overhead_uv[b + 3] - overhead_uv[b + 1])
+                ) * 0.5;
+            }
+
+            // `member_area` at zero means every triangle in the group is degenerate. The hull is then
+            // all there is to go on, and it is what this has always carved - leave that alone.
+            const tiles_hull = member_area <= AREA_EPS
+                || Math.abs(hull_area - member_area) <= Math.max(AREA_EPS, hull_area * HULL_TILING_RELATIVE_EPS);
+
+            if (tiles_hull) {
+                push_footprint(
+                    hull_poly, hull.length, g.hsum / member_count,
+                    agent_radius, footprint_poly, footprint_h
+                );
+
+                continue;
+            }
+        }
+
+        for (let m = 0; m < member_count; m++) {
+            const i = g.members[m];
+            const b = i * 6;
+
+            push_footprint(
+                Float64Array.of(
+                    overhead_uv[b], overhead_uv[b + 1],
+                    overhead_uv[b + 2], overhead_uv[b + 3],
+                    overhead_uv[b + 4], overhead_uv[b + 5]
+                ),
+                3, overhead_h[i],
+                agent_radius, footprint_poly, footprint_h
+            );
+        }
+    }
+
+    const footprint_count = footprint_poly.length;
+    if (footprint_count === 0) return soup.slice(0, triangle_count * 9);
+
+    // Broad-phase index: one leaf per footprint, in (u, v, height) space. The first two axes are the
+    // dilated footprint's (u,v) extent; the third is the band of soup heights it can carve - a triangle
+    // at mean height `th` is carved by an obstacle at height `h` iff 0 < h - th <= agent_height. A soup
+    // triangle then queries this BVH with its own (u,v) extent at `th` to get just the candidate
+    // obstacles, instead of scanning all of them.
+    const footprint_bvh = new BVH();
+    footprint_bvh.release_all();
+    for (let fi = 0; fi < footprint_count; fi++) {
+        const poly = footprint_poly[fi];
+        let min_u = Infinity, min_v = Infinity, max_u = -Infinity, max_v = -Infinity;
+        for (let i = 0; i < poly.length; i += 2) {
+            const u = poly[i], v = poly[i + 1];
+            if (u < min_u) min_u = u;
+            if (u > max_u) max_u = u;
+            if (v < min_v) min_v = v;
+            if (v > max_v) max_v = v;
+        }
+        const h = footprint_h[fi];
+        const node = footprint_bvh.allocate_node();
+        footprint_bvh.node_set_user_data(node, fi);
+        footprint_bvh.node_set_aabb_primitive(
+            node,
+            min_u, min_v, h - agent_height - HEIGHT_EPS,
+            max_u, max_v, h - HEIGHT_EPS
+        );
+        footprint_bvh.insert_leaf(node);
+    }
+
+    const out = [];
+
+    // per-triangle reusable storage
+    const tri_uv = new Float64Array(6);          // u0,v0,u1,v1,u2,v2 of the source triangle
+    const px = new Float64Array(3), py = new Float64Array(3), pz = new Float64Array(3);
+    const query_aabb = new Float64Array(6);
+    const query_hits = new Int32Array(footprint_count);
+    /** @type {Float64Array[]} */
+    let pieces = [];
+    /** @type {Float64Array[]} */
+    let next_pieces = [];
+
+    for (let t = 0; t < triangle_count; t++) {
+        const o = t * 9;
+
+        let th = 0;
+        for (let k = 0; k < 3; k++) {
+            const x = soup[o + k * 3], y = soup[o + k * 3 + 1], z = soup[o + k * 3 + 2];
+            px[k] = x; py[k] = y; pz[k] = z;
+            tri_uv[k * 2] = v3_dot(x, y, z, u_x, u_y, u_z);
+            tri_uv[k * 2 + 1] = v3_dot(x, y, z, v_x, v_y, v_z);
+            th += v3_dot(x, y, z, upx, upy, upz);
+        }
+        th /= 3;
+
+        // barycentric denominator (twice the signed uv area of the triangle)
+        const e1u = tri_uv[2] - tri_uv[0], e1v = tri_uv[3] - tri_uv[1];
+        const e2u = tri_uv[4] - tri_uv[0], e2v = tri_uv[5] - tri_uv[1];
+        const det = e1u * e2v - e2u * e1v;
+
+        if (Math.abs(det) <= AREA_EPS) {
+            // degenerate in (u,v) (a near-vertical triangle): cannot carve meaningfully, pass through
+            for (let i = 0; i < 9; i++) out.push(soup[o + i]);
+            continue;
+        }
+
+        // broad-phase: only the obstacles whose (u,v) extent and height band overlap this triangle
+        let min_u = tri_uv[0], max_u = tri_uv[0], min_v = tri_uv[1], max_v = tri_uv[1];
+        for (let k = 1; k < 3; k++) {
+            const u = tri_uv[k * 2], v = tri_uv[k * 2 + 1];
+            if (u < min_u) min_u = u;
+            if (u > max_u) max_u = u;
+            if (v < min_v) min_v = v;
+            if (v > max_v) max_v = v;
+        }
+        query_aabb[0] = min_u; query_aabb[1] = min_v; query_aabb[2] = th;
+        query_aabb[3] = max_u; query_aabb[4] = max_v; query_aabb[5] = th;
+
+        const hit_count = bvh_query_user_data_intersects_aabb(query_hits, 0, footprint_bvh, query_aabb);
+        if (hit_count === 0) {
+            // no obstacle overlaps here - copy straight through
+            for (let i = 0; i < 9; i++) out.push(soup[o + i]);
+            continue;
+        }
+
+        // start with the whole triangle as one piece, then subtract each overlapping footprint
+        pieces.length = 0;
+        pieces.push(Float64Array.of(tri_uv[0], tri_uv[1], tri_uv[2], tri_uv[3], tri_uv[4], tri_uv[5]));
+
+        for (let qi = 0; qi < hit_count; qi++) {
+            const fi = query_hits[qi];
+            const dh = footprint_h[fi] - th;
+            if (dh <= HEIGHT_EPS || dh > agent_height + HEIGHT_EPS) continue; // exact band test
+
+            const fp = footprint_poly[fi];
+            const fp_n = fp.length / 2;
+
+            next_pieces.length = 0;
+            for (let pi = 0; pi < pieces.length; pi++) {
+                subtract_footprint(pieces[pi], pieces[pi].length / 2, fp, fp_n, next_pieces);
+            }
+
+            const swap = pieces; pieces = next_pieces; next_pieces = swap;
+            if (pieces.length === 0) break;
+        }
+
+        const inv_det = 1 / det;
+        for (let pi = 0; pi < pieces.length; pi++) {
+            const poly = pieces[pi];
+            const poly_n = poly.length / 2;
+
+            // fan-triangulate the surviving piece and reconstruct world XYZ per vertex
+            for (let i = 1; i + 1 < poly_n; i++) {
+                const u0 = poly[0], v0 = poly[1];
+                const u1 = poly[i * 2], v1 = poly[i * 2 + 1];
+                const u2 = poly[(i + 1) * 2], v2 = poly[(i + 1) * 2 + 1];
+
+                const area2 = Math.abs((u1 - u0) * (v2 - v0) - (u2 - u0) * (v1 - v0));
+                if (area2 < 2 * AREA_EPS) continue;
+
+                emit_xyz(out, u0, v0, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
+                emit_xyz(out, u1, v1, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
+                emit_xyz(out, u2, v2, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det);
+            }
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Reconstruct the world XYZ of a (u,v) point lying in a source triangle (barycentric on the triangle's
+ * planar uv coordinates) and append it to `out`.
+ *
+ * @param {number[]} out destination soup
+ * @param {number} u
+ * @param {number} v the point in (u,v)
+ * @param {Float64Array} tri_uv the triangle's uv corners (stride 2, vertex 0 is the origin)
+ * @param {Float64Array} px
+ * @param {Float64Array} py
+ * @param {Float64Array} pz the triangle's world corners
+ * @param {number} e1u
+ * @param {number} e1v edge (v1 - v0) in uv
+ * @param {number} e2u
+ * @param {number} e2v edge (v2 - v0) in uv
+ * @param {number} inv_det reciprocal of the uv area determinant
+ */
+function emit_xyz(out, u, v, tri_uv, px, py, pz, e1u, e1v, e2u, e2v, inv_det) {
+    const du = u - tri_uv[0];
+    const dv = v - tri_uv[1];
+    const w1 = (du * e2v - e2u * dv) * inv_det;
+    const w2 = (e1u * dv - du * e1v) * inv_det;
+    const w0 = 1 - w1 - w2;
+
+    out.push(
+        w0 * px[0] + w1 * px[1] + w2 * px[2],
+        w0 * py[0] + w1 * py[1] + w2 * py[2],
+        w0 * pz[0] + w1 * pz[1] + w2 * pz[2]
+    );
+}