@jgengine/core 0.14.0 → 0.15.0

package/dist/world/roads.js

@@ -36,6 +36,36 @@ export function roundPathCorners(points, radius, cornerSegments = 5) {
     out.push([points[points.length - 1][0], points[points.length - 1][1]]);
     return out;
 }
+/**
+ * The single owning table of ground-decal Y offsets, in world units above the sampled terrain.
+ *
+ * Contract — the vertical stacking order is `terrain < road < junction < marking < glow`, and every
+ * ground overlay must draw from THIS table rather than picking a local magic epsilon (the old
+ * scatter of `0.08` ribbons, `+0.02` discs, `0.05` markings, `0.055–0.1` playground fudge factors
+ * is exactly the z-fighting this removes).
+ *
+ * - `road` and `junction` deliberately share one layer: {@link buildJunctionSurface} welds its
+ *   boundary vertices onto the exact corner vertices where the trimmed ribbon ends
+ *   ({@link trimPathAtJunctions}), so the two surfaces meet at a shared seam and never stack — they
+ *   must sit at the same height or the seam would tear. Do NOT bump `junction` above `road`.
+ * - `marking` is the ONLY permitted coplanar overlay (lane paint sits on top of asphalt at the same
+ *   XZ). Its Y separation alone is not enough to beat depth precision on sloped ground: consumers
+ *   rendering markings MUST ALSO set a negative `polygonOffset` and/or a higher `renderOrder` on the
+ *   marking material (renderer-side — this table only owns the Y term).
+ * - `glow` sits above markings for emissive decals (crosswalk glow, selection halos).
+ *
+ * Values are chosen with real separation so a small terrain slope can't invert the order.
+ */
+export const GROUND_DECAL_LAYERS = {
+    /** Road ribbons. */
+    road: 0.06,
+    /** Junction surfaces — SAME layer as `road` because they are seam-welded, never stacked. */
+    junction: 0.06,
+    /** Lane markings / crosswalks — the only coplanar overlay; also set polygonOffset/renderOrder. */
+    marking: 0.11,
+    /** Emissive decals above markings (glow, halos). */
+    glow: 0.14,
+};
 function subdividePath(path, maxLength) {
     const out = [];
     for (let i = 0; i < path.length - 1; i += 1) {
@@ -68,30 +98,136 @@ function normalAt(points, index) {
  * into a mesh, and tests can assert on it directly.
  */
 export function buildRoadRibbon(path, width, sampleHeight, options = {}) {
-    const elevation = options.elevation ?? 0.08;
+    const elevation = options.elevation ?? GROUND_DECAL_LAYERS.road;
     const maxSegmentLength = options.maxSegmentLength ?? 4;
     if (path.length < 2 || width <= 0) {
         return { positions: new Float32Array(0), indices: new Uint32Array(0) };
     }
     const points = subdividePath(path, maxSegmentLength);
+    const n = points.length;
     const half = width / 2;
-    const positions = new Float32Array(points.length * 6);
-    for (let i = 0; i < points.length; i += 1) {
+    // Offset boundaries as 2-D points, then draped. The offsetting has to survive bends: a naive
+    // per-vertex perpendicular offset makes the INNER edge of a corner fold back on itself (a bowtie)
+    // whenever the local turn radius drops below the half-width — visible as doubled/overlapping road.
+    //
+    // Two invariants keep downstream welds and the regression suite intact while fixing the fold:
+    //   • Endpoints (i=0, i=n−1) and straight interior vertices use the EXACT naive formula
+    //     (`centre ± normalAt·half`). buildTrimmedIntersections reads terminal cross-sections back
+    //     bitwise, so those floats must never move; straight ribbons stay byte-identical to before.
+    //   • Only genuinely BENT interior vertices change: the inner edge gets a real miter join (the
+    //     intersection of the two adjacent inner offset lines) and a forward-progress weld that
+    //     collapses any residual fold, while the outer edge keeps the smooth naive offset.
+    const left = new Array(n);
+    const right = new Array(n);
+    const turnSign = new Float64Array(n); // >0 left turn (left edge inner), <0 right turn, 0 straight
+    const normX = new Float64Array(n);
+    const normZ = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
         const [x, z] = points[i];
         const [nx, nz] = normalAt(points, i);
-        const lx = x + nx * half;
-        const lz = z + nz * half;
-        const rx = x - nx * half;
-        const rz = z - nz * half;
-        positions[i * 6] = lx;
-        positions[i * 6 + 1] = sampleHeight(lx, lz) + elevation;
-        positions[i * 6 + 2] = lz;
-        positions[i * 6 + 3] = rx;
-        positions[i * 6 + 4] = sampleHeight(rx, rz) + elevation;
-        positions[i * 6 + 5] = rz;
-    }
-    const indices = new Uint32Array((points.length - 1) * 6);
-    for (let i = 0; i < points.length - 1; i += 1) {
+        normX[i] = nx;
+        normZ[i] = nz;
+        let lx = x + nx * half;
+        let lz = z + nz * half;
+        let rx = x - nx * half;
+        let rz = z - nz * half;
+        if (i > 0 && i < n - 1) {
+            const p = points[i - 1];
+            const q = points[i + 1];
+            const inx = x - p[0];
+            const inz = z - p[1];
+            const il = Math.hypot(inx, inz);
+            const oux = q[0] - x;
+            const ouz = q[1] - z;
+            const ol = Math.hypot(oux, ouz);
+            if (il > 1e-12 && ol > 1e-12) {
+                const dix = inx / il;
+                const diz = inz / il;
+                const dox = oux / ol;
+                const doz = ouz / ol;
+                const cross = dix * doz - diz * dox; // >0 left turn (left edge is inner), <0 right turn
+                if (Math.abs(cross) > 1e-9) {
+                    turnSign[i] = cross;
+                    // Left normals of the incoming/outgoing segments; their offset lines intersect at the miter.
+                    const nix = -diz;
+                    const niz = dix;
+                    const nox = -doz;
+                    const noz = dox;
+                    const denom = 1 + (nix * nox + niz * noz); // 1 + cosθ; → 0 only at a ~180° reversal
+                    if (denom > 1e-6) {
+                        const mvx = (nix + nox) / denom;
+                        const mvz = (niz + noz) / denom;
+                        if (cross > 0) {
+                            // Left edge is inner → miter it; right (outer) stays naive.
+                            lx = x + mvx * half;
+                            lz = z + mvz * half;
+                        }
+                        else {
+                            // Right edge is inner → miter it; left (outer) stays naive.
+                            rx = x - mvx * half;
+                            rz = z - mvz * half;
+                        }
+                    }
+                }
+            }
+        }
+        left[i] = [lx, lz];
+        right[i] = [rx, rz];
+    }
+    // Collapse any inner-edge fold. At interior vertices only, weld an INNER-side vertex onto its kept
+    // predecessor when it either (a) fails to advance along the centreline tangent, or (b) has crossed
+    // to the far side of the centreline — both signatures of a fold when the turn radius drops below
+    // the half-width (the offset curve otherwise inverts and self-intersects). Straight runs and the
+    // outer edge of a bend are never inner, so they — and every straight ribbon — stay byte-identical.
+    const weldFolds = (edge, sideSign) => {
+        let kept = edge[0];
+        for (let i = 1; i < n - 1; i += 1) {
+            const inner = sideSign * turnSign[i] > 0;
+            if (!inner) {
+                kept = edge[i];
+                continue;
+            }
+            const p = points[i - 1];
+            const q = points[i + 1];
+            let tx = q[0] - p[0];
+            let tz = q[1] - p[1];
+            const tl = Math.hypot(tx, tz);
+            if (tl <= 1e-12) {
+                kept = edge[i];
+                continue;
+            }
+            tx /= tl;
+            tz /= tl;
+            const cx = points[i][0];
+            const cz = points[i][1];
+            const qx = edge[i][0];
+            const qz = edge[i][1];
+            const forward = (qx - kept[0]) * tx + (qz - kept[1]) * tz;
+            // Signed distance onto this edge's own outward normal — negative means it crossed the centreline.
+            const sideDist = (qx - cx) * (sideSign * normX[i]) + (qz - cz) * (sideSign * normZ[i]);
+            if (forward <= 1e-9 || sideDist <= 1e-9) {
+                edge[i] = [kept[0], kept[1]]; // fold → collapse onto the kept frontier
+            }
+            else {
+                kept = edge[i];
+            }
+        }
+    };
+    weldFolds(left, 1);
+    weldFolds(right, -1);
+    const positions = new Float32Array(n * 6);
+    for (let i = 0; i < n; i += 1) {
+        const l = left[i];
+        const r = right[i];
+        positions[i * 6] = l[0];
+        positions[i * 6 + 1] = sampleHeight(l[0], l[1]) + elevation;
+        positions[i * 6 + 2] = l[1];
+        positions[i * 6 + 3] = r[0];
+        positions[i * 6 + 4] = sampleHeight(r[0], r[1]) + elevation;
+        positions[i * 6 + 5] = r[1];
+    }
+    const indices = new Uint32Array((n - 1) * 6);
+    for (let i = 0; i < n - 1; i += 1) {
         const a = i * 2;
         indices[i * 6] = a;
         indices[i * 6 + 1] = a + 1;
@@ -103,13 +239,17 @@ export function buildRoadRibbon(path, width, sampleHeight, options = {}) {
     return { positions, indices };
 }
 /**
- * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
- * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
- * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
- * Pure geometry; the shell meshes the result with the asphalt material.
+ * Build a flat, ground-draped disc patch centered on `center` — a triangle fan of `segments` sides
+ * (default 16), every vertex draped at `sampleHeight + elevation`.
+ *
+ * @deprecated This floats a disc slightly above the crossing ribbons, which still overlaps and
+ * z-fights them. Prefer {@link buildJunctionSurface} (with {@link trimPathAtJunctions}, or the
+ * all-in-one {@link buildTrimmedIntersections}): it trims the ribbons back to the junction boundary
+ * and welds one seam-shared surface, with no overlap and no floating disc. Kept so existing callers
+ * don't break this round.
  */
 export function buildJunctionPatch(center, radius, sampleHeight, options = {}) {
-    const elevation = options.elevation ?? 0.08;
+    const elevation = options.elevation ?? GROUND_DECAL_LAYERS.junction;
     const segments = Math.max(3, Math.floor(options.segments ?? 16));
     if (radius <= 0)
         return { positions: new Float32Array(0), indices: new Uint32Array(0) };
@@ -239,3 +379,1104 @@ export function pathLength(path) {
     }
     return total;
 }
+/** Outward unit direction of a junction arm under the `atan2(dx, dz)` convention. */
+function armDirection(angle) {
+    return [Math.sin(angle), Math.cos(angle)];
+}
+/**
+ * Apron pull-back for one approach: how far the ribbon must retreat so its mouth sits on the
+ * carriageway-union boundary of the *crossing* arms.
+ *
+ * For each arm that is neither this approach (dot ≈ +1) nor its through-continuation (dot ≈ −1),
+ * the clearance along this centerline is `(arm.width / 2) / sin(φ)` where φ is the angle between
+ * the two directions. Orthogonal equal-width roads therefore trim at half-width; a narrow stub
+ * into a wide boulevard trims farther; the wide boulevard only trims by the stub's half-width.
+ *
+ * The curb-return radius is deliberately **not** part of the apron — returns are exterior corner
+ * arcs only. Including them here was the oversized-plaza failure mode (mouths pushed out by R,
+ * then filleted again).
+ */
+function apronDistance(junction, outward, margin, 
+/** Half-width of the approach being trimmed (for acute-angle mouth clearance). */
+selfHalf = 0) {
+    const arms = junction.arms;
+    if (arms.length === 0)
+        return margin;
+    let crossMax = 0;
+    let anyCrosser = false;
+    let widestHalf = 0;
+    for (let j = 0; j < arms.length; j += 1) {
+        const half = arms[j].width / 2;
+        widestHalf = Math.max(widestHalf, half);
+        const [ax, az] = armDirection(arms[j].angle);
+        const dot = outward[0] * ax + outward[1] * az;
+        // Same-direction arm or opposite through-continuation — not a crosser.
+        if (dot > 0.85 || dot < -0.85)
+            continue;
+        // |sin φ| from the 2-D cross magnitude of unit directions.
+        const sinPhi = Math.abs(outward[0] * az - outward[1] * ax);
+        if (sinPhi < 1e-6)
+            continue;
+        anyCrosser = true;
+        // Clear the crossing carriageway projected along this centerline.
+        let needed = half / sinPhi;
+        // Degree-2 acute turns also need enough pull-back that the two mouth end-caps no longer
+        // properly cross (a 90° cross is fine at half-width; a 45° fork is not). Multi-arm nodes
+        // keep the pure projection so unequal five-ways stay compact.
+        if (arms.length === 2) {
+            const phi = Math.atan2(sinPhi, Math.max(-1, Math.min(1, Math.abs(dot))));
+            if (phi < Math.PI / 2 - 1e-6) {
+                const tanHalf = Math.tan(Math.max(phi / 2, 1e-3));
+                needed = Math.max(needed, (selfHalf + half) / (2 * tanHalf));
+            }
+        }
+        crossMax = Math.max(crossMax, needed);
+    }
+    if (!anyCrosser)
+        crossMax = widestHalf;
+    return crossMax + margin;
+}
+/** Clamp a requested curb-return radius by the two adjacent road widths and the corner chord. */
+function clampCurbReturnRadius(requested, widthA, widthB, chord) {
+    if (requested <= 0 || chord <= 1e-9)
+        return 0;
+    // Ordinary street corners stay well below half the narrower carriageway.
+    const byWidth = 0.35 * Math.min(widthA, widthB);
+    // A circular return cannot exceed half the gap chord (degenerate semicircle).
+    const byChord = chord * 0.45;
+    return Math.max(0, Math.min(requested, byWidth, byChord));
+}
+/** Point + forward tangent at arc-length `dist` from the start of `sub`; used to place a cut. */
+function pointAtArcLength(sub, dist) {
+    let acc = 0;
+    for (let i = 0; i < sub.length - 1; i += 1) {
+        const a = sub[i];
+        const b = sub[i + 1];
+        const dx = b[0] - a[0];
+        const dz = b[1] - a[1];
+        const segLen = Math.hypot(dx, dz);
+        if (acc + segLen >= dist || i === sub.length - 2) {
+            const t = segLen <= 0 ? 0 : Math.max(0, Math.min(1, (dist - acc) / segLen));
+            const len = segLen || 1;
+            return { point: [a[0] + dx * t, a[1] + dz * t], segment: i, tangent: [dx / len, dz / len] };
+        }
+        acc += segLen;
+    }
+    const last = sub[sub.length - 1];
+    return { point: [last[0], last[1]], segment: sub.length - 2, tangent: [1, 0] };
+}
+/** Left/right corners exactly as {@link buildRoadRibbon} would emit them at a cut (center ± half along ⟂tangent). */
+function cornerPair(center, tangent, half) {
+    // Matches buildRoadRibbon's normalAt: normal = [-tangent.z, tangent.x]; left = +normal, right = −normal.
+    const nx = -tangent[1];
+    const nz = tangent[0];
+    return {
+        left: [center[0] + nx * half, center[1] + nz * half],
+        right: [center[0] - nx * half, center[1] - nz * half],
+    };
+}
+/**
+ * Cut a street centerline back from the junctions it passes through so its ribbon ENDS at the
+ * junction boundary instead of ploughing through the node. Junctions are matched to path vertices
+ * within `nodeEpsilon` (endpoints and interior vertices alike); a junction sitting on an interior
+ * vertex SPLITS the path into two independently-trimmed sub-paths. Each cut records the exact
+ * boundary point and the road's left/right edge corners there, so {@link buildJunctionSurface} can
+ * weld its polygon onto the identical vertices with no overlap.
+ *
+ * Pure geometry, allocation-aware, bounded by the vertex and junction counts. Returns one
+ * {@link TrimmedRoad} per surviving sub-path (a mid-polyline junction yields two).
+ */
+export function trimPathAtJunctions(path, width, junctions, options = {}) {
+    if (path.length < 2 || width <= 0)
+        return [];
+    const margin = options.apronMargin ?? 0.25;
+    const eps = options.nodeEpsilon ?? 1e-6;
+    const half = width / 2;
+    const n = path.length;
+    // Map each path vertex to a coincident junction (or -1).
+    const vertJunction = new Array(n).fill(-1);
+    for (let vi = 0; vi < n; vi += 1) {
+        const p = path[vi];
+        for (let ji = 0; ji < junctions.length; ji += 1) {
+            const j = junctions[ji];
+            if (Math.hypot(p[0] - j.x, p[1] - j.z) <= eps) {
+                vertJunction[vi] = ji;
+                break;
+            }
+        }
+    }
+    // Boundaries split the polyline: start, every interior junction vertex, end.
+    const boundaries = [0];
+    for (let vi = 1; vi < n - 1; vi += 1)
+        if (vertJunction[vi] !== -1)
+            boundaries.push(vi);
+    boundaries.push(n - 1);
+    const result = [];
+    for (let r = 0; r < boundaries.length - 1; r += 1) {
+        const a = boundaries[r];
+        const b = boundaries[r + 1];
+        let sub = [];
+        for (let i = a; i <= b; i += 1)
+            sub.push([path[i][0], path[i][1]]);
+        if (sub.length < 2)
+            continue;
+        const startJ = vertJunction[a];
+        const endJ = vertJunction[b];
+        let startApron = 0;
+        let endApron = 0;
+        if (startJ !== -1) {
+            const dx = sub[1][0] - sub[0][0];
+            const dz = sub[1][1] - sub[0][1];
+            const l = Math.hypot(dx, dz) || 1;
+            startApron = apronDistance(junctions[startJ], [dx / l, dz / l], margin, half);
+        }
+        if (endJ !== -1) {
+            const last = sub.length - 1;
+            const dx = sub[last - 1][0] - sub[last][0];
+            const dz = sub[last - 1][1] - sub[last][1];
+            const l = Math.hypot(dx, dz) || 1;
+            endApron = apronDistance(junctions[endJ], [dx / l, dz / l], margin, half);
+        }
+        // Clamp so the two aprons never cross: leave a sliver of ribbon between adjacent junctions.
+        const runLen = pathLength(sub);
+        const avail = Math.max(0, runLen - 1e-4);
+        if (startApron + endApron > avail) {
+            const total = startApron + endApron || 1;
+            startApron = (startApron / total) * avail;
+            endApron = (endApron / total) * avail;
+        }
+        const cuts = [];
+        if (startApron > 1e-9) {
+            const { point, segment, tangent } = pointAtArcLength(sub, startApron);
+            const { left, right } = cornerPair(point, tangent, half);
+            cuts.push({ junctionIndex: startJ, at: "start", center: point, direction: tangent, left, right, apron: startApron });
+            const kept = [point];
+            for (let i = segment + 1; i < sub.length; i += 1)
+                kept.push(sub[i]);
+            sub = kept;
+        }
+        if (endApron > 1e-9 && sub.length >= 2) {
+            const target = pathLength(sub) - endApron;
+            const { point, segment, tangent } = pointAtArcLength(sub, target);
+            const { left, right } = cornerPair(point, tangent, half);
+            cuts.push({
+                junctionIndex: endJ,
+                at: "end",
+                center: point,
+                direction: [-tangent[0], -tangent[1]],
+                left,
+                right,
+                apron: endApron,
+            });
+            const kept = [];
+            for (let i = 0; i <= segment; i += 1)
+                kept.push(sub[i]);
+            kept.push(point);
+            sub = kept;
+        }
+        if (sub.length >= 2 && pathLength(sub) > 1e-6)
+            result.push({ path: sub, cuts });
+    }
+    return result;
+}
+/**
+ * Cut an offset band (a polyline running PARALLEL to a street — e.g. a sidewalk from
+ * `Street.sidewalks.{left,right}`) out of every junction's apron, so the band stops at the crossing
+ * instead of sailing straight through it. Unlike {@link trimPathAtJunctions} the band never passes
+ * through a node, so it is clipped by DISTANCE: each junction contributes a circular apron of radius
+ * `max arm half-width + apronMargin + bandWidth/2 + clearance` (plus a small curb-return allowance),
+ * and any part of the band inside any apron circle is removed, splitting the band into the sub-paths
+ * that survive outside. Entry/exit points land exactly on the apron boundary. A band that never
+ * enters an apron passes through as a single untouched copy.
+ *
+ * Pure geometry, deterministic, bounded by the band-vertex and junction counts.
+ *
+ * @example
+ * ```ts
+ * // Same `junctions` you fed the roads; trim both sidewalks of a street around every node.
+ * const left = trimBandAtJunctions(street.sidewalks.left, street.sidewalkWidth, junctions);
+ * const right = trimBandAtJunctions(street.sidewalks.right, street.sidewalkWidth, junctions);
+ * for (const sub of [...left, ...right]) meshes.push(buildRoadRibbon(sub, street.sidewalkWidth, sampleHeight));
+ * ```
+ *
+ * @capability world-intersections trim offset sidewalk/parallel bands around junction aprons
+ */
+export function trimBandAtJunctions(bandPath, bandWidth, junctions, options = {}) {
+    if (bandPath.length < 2)
+        return [];
+    const curbReturnRadius = options.curbReturnRadius ?? 2;
+    const margin = options.apronMargin ?? 0.25;
+    const clearance = options.clearance ?? 0;
+    const half = Math.max(0, bandWidth) / 2;
+    const circles = [];
+    for (let ji = 0; ji < junctions.length; ji += 1) {
+        const j = junctions[ji];
+        let maxHalf = 0;
+        let minWidth = Infinity;
+        for (let a = 0; a < j.arms.length; a += 1) {
+            maxHalf = Math.max(maxHalf, j.arms[a].width / 2);
+            minWidth = Math.min(minWidth, j.arms[a].width);
+        }
+        // Small curb allowance (not the full return) so parallel bands clear exterior corner arcs.
+        const curbAllow = Math.min(curbReturnRadius, 0.35 * (Number.isFinite(minWidth) ? minWidth : 0));
+        const r = maxHalf + margin + half + clearance + curbAllow;
+        if (r > 0)
+            circles.push({ x: j.x, z: j.z, r2: r * r });
+    }
+    const copy = () => bandPath.map((p) => [p[0], p[1]]);
+    if (circles.length === 0)
+        return [copy()];
+    const insideAny = (x, z) => {
+        for (let c = 0; c < circles.length; c += 1) {
+            const dx = x - circles[c].x;
+            const dz = z - circles[c].z;
+            if (dx * dx + dz * dz < circles[c].r2)
+                return true;
+        }
+        return false;
+    };
+    const result = [];
+    let cur = [];
+    const eps = 1e-9;
+    const pushPoint = (p) => {
+        const last = cur[cur.length - 1];
+        if (last === undefined || Math.hypot(last[0] - p[0], last[1] - p[1]) > eps)
+            cur.push(p);
+    };
+    const closeSub = () => {
+        if (cur.length >= 2 && pathLength(cur) > eps)
+            result.push(cur);
+        cur = [];
+    };
+    for (let i = 0; i < bandPath.length - 1; i += 1) {
+        const a = bandPath[i];
+        const b = bandPath[i + 1];
+        const dx = b[0] - a[0];
+        const dz = b[1] - a[1];
+        // Every boundary crossing t in (0,1) where the segment meets a circle edge.
+        const ts = [0, 1];
+        for (let c = 0; c < circles.length; c += 1) {
+            const circle = circles[c];
+            const fx = a[0] - circle.x;
+            const fz = a[1] - circle.z;
+            const A = dx * dx + dz * dz;
+            if (A < eps)
+                continue;
+            const B = 2 * (fx * dx + fz * dz);
+            const C = fx * fx + fz * fz - circle.r2;
+            const disc = B * B - 4 * A * C;
+            if (disc <= 0)
+                continue;
+            const sq = Math.sqrt(disc);
+            const t0 = (-B - sq) / (2 * A);
+            const t1 = (-B + sq) / (2 * A);
+            if (t0 > eps && t0 < 1 - eps)
+                ts.push(t0);
+            if (t1 > eps && t1 < 1 - eps)
+                ts.push(t1);
+        }
+        ts.sort((p, q) => p - q);
+        for (let s = 0; s < ts.length - 1; s += 1) {
+            const t0 = ts[s];
+            const t1 = ts[s + 1];
+            if (t1 - t0 < eps)
+                continue;
+            const tm = (t0 + t1) / 2;
+            const mx = a[0] + dx * tm;
+            const mz = a[1] + dz * tm;
+            if (insideAny(mx, mz)) {
+                closeSub(); // this piece is inside an apron — drop it and break continuity
+                continue;
+            }
+            const p0 = [a[0] + dx * t0, a[1] + dz * t0];
+            const p1 = [a[0] + dx * t1, a[1] + dz * t1];
+            pushPoint(p0);
+            pushPoint(p1);
+        }
+    }
+    closeSub();
+    return result;
+}
+/**
+ * Build a tangent-continuous centerline through a two-arm junction. This is the shared path for
+ * paint, medians, curbs, or other linear dressing that should follow a bend but stop at crossings.
+ * Returns `null` for anything other than exactly two approaches.
+ * @capability world-intersections connect linear road dressing through two-arm bends
+ */
+export function buildJunctionConnector(junction, approaches, segments = 8) {
+    if (approaches.length !== 2)
+        return null;
+    const a = approaches[0].center;
+    const b = approaches[1].center;
+    const aRadius = Math.hypot(a[0] - junction.x, a[1] - junction.z);
+    const bRadius = Math.hypot(b[0] - junction.x, b[1] - junction.z);
+    let adx = approaches[0].direction?.[0] ?? a[0] - junction.x;
+    let adz = approaches[0].direction?.[1] ?? a[1] - junction.z;
+    let bdx = approaches[1].direction?.[0] ?? b[0] - junction.x;
+    let bdz = approaches[1].direction?.[1] ?? b[1] - junction.z;
+    const al = Math.hypot(adx, adz);
+    const bl = Math.hypot(bdx, bdz);
+    if (al < 1e-6 || bl < 1e-6)
+        return null;
+    adx /= al;
+    adz /= al;
+    bdx /= bl;
+    bdz /= bl;
+    const chord = Math.hypot(b[0] - a[0], b[1] - a[1]);
+    const handle = Math.min(aRadius, bRadius, chord * 0.45);
+    const c1x = a[0] - adx * handle;
+    const c1z = a[1] - adz * handle;
+    const c2x = b[0] - bdx * handle;
+    const c2z = b[1] - bdz * handle;
+    const count = Math.max(2, Math.min(64, Math.floor(Number.isFinite(segments) ? segments : 8)));
+    const path = [];
+    for (let i = 0; i <= count; i += 1) {
+        const t = i / count;
+        const u = 1 - t;
+        path.push([
+            u * u * u * a[0] + 3 * u * u * t * c1x + 3 * u * t * t * c2x + t * t * t * b[0],
+            u * u * u * a[1] + 3 * u * u * t * c1z + 3 * u * t * t * c2z + t * t * t * b[1],
+        ]);
+    }
+    return path;
+}
+/**
+ * Weld one triangulated junction surface onto the corner vertices its incident ribbons END at
+ * (from {@link trimPathAtJunctions}). Corners are grouped by approach (so unequal widths cannot
+ * interleave a neighbour between a mouth pair), ordered around the node, and bridged as follows:
+ *
+ * - **Road mouth** — the straight end-edge of the approach (shared seam with the ribbon).
+ * - **Through edge (~180°)** — straight chord along the continuing curb (T-junction far side).
+ * - **Exterior corner** — a compact circular curb-return of radius ≤ `curbReturnRadius`, clamped by
+ *   adjacent widths and chord length; bows *outward* only, never a plaza disc.
+ * - **Two-arm turn** — both edges get the same compact returns (no diagonal cap, no remote tangent).
+ *
+ * The boundary is ear-clipped so every triangle faces +Y. Draped height matches
+ * {@link buildRoadRibbon}. Mouth corners are the approach corners verbatim.
+ */
+export function buildJunctionSurface(junction, approaches, sampleHeight, options = {}) {
+    if (approaches.length === 0)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const elevation = options.elevation ?? GROUND_DECAL_LAYERS.junction;
+    const curbReturnRadius = options.curbReturnRadius ?? 2;
+    const filletSegments = Math.max(1, Math.floor(options.filletSegments ?? 4));
+    const cx = junction.x;
+    const cz = junction.z;
+    // Wrap an angle difference into (−π, π].
+    const wrapAngle = (a) => {
+        let v = a;
+        while (v <= -Math.PI)
+            v += Math.PI * 2;
+        while (v > Math.PI)
+            v -= Math.PI * 2;
+        return v;
+    };
+    const ordered = [];
+    for (let i = 0; i < approaches.length; i += 1) {
+        const ap = approaches[i];
+        const outAngle = ap.direction === undefined
+            ? Math.atan2(ap.center[1] - cz, ap.center[0] - cx)
+            : Math.atan2(ap.direction[1], ap.direction[0]);
+        const leftC = { x: ap.left[0], y: ap.left[1], z: ap.left[2] };
+        const rightC = { x: ap.right[0], y: ap.right[1], z: ap.right[2] };
+        const leftOff = wrapAngle(Math.atan2(leftC.z - cz, leftC.x - cx) - outAngle);
+        const rightOff = wrapAngle(Math.atan2(rightC.z - cz, rightC.x - cx) - outAngle);
+        // `first` is the CW-most corner, `second` the CCW-most for a CCW walk around the node.
+        const firstIsLeft = leftOff <= rightOff;
+        ordered.push({
+            first: firstIsLeft ? leftC : rightC,
+            second: firstIsLeft ? rightC : leftC,
+            firstAngle: Math.atan2((firstIsLeft ? leftC : rightC).z - cz, (firstIsLeft ? leftC : rightC).x - cx),
+            secondAngle: Math.atan2((firstIsLeft ? rightC : leftC).z - cz, (firstIsLeft ? rightC : leftC).x - cx),
+            outAngle,
+            width: ap.width ?? Math.hypot(ap.left[0] - ap.right[0], ap.left[2] - ap.right[2]),
+        });
+    }
+    ordered.sort((p, q) => p.outAngle - q.outAngle);
+    /**
+     * Compact cubic curb between two mouth corners. Handles follow each approach's edge direction
+     * (parallel to the centerline) and are capped so remote edge intersections cannot recreate the
+     * plaza-sized blob. Samples stay on the outward side of the chord.
+     */
+    const pushCurbCubic = (from, to, outAngleA, outAngleB, handle, into) => {
+        const L = Math.hypot(to.x - from.x, to.z - from.z);
+        if (L < 1e-6 || handle < 1e-6)
+            return;
+        const adx = Math.cos(outAngleA);
+        const adz = Math.sin(outAngleA);
+        const bdx = Math.cos(outAngleB);
+        const bdz = Math.sin(outAngleB);
+        const den = adx * bdz - adz * bdx;
+        let hA = handle;
+        let hB = handle;
+        // Prefer the edge-tangent intersection when it lies a short, finite distance away; otherwise
+        // fall back to equal capped handles along each edge.
+        if (Math.abs(den) > 1e-6) {
+            const qx = to.x - from.x;
+            const qz = to.z - from.z;
+            const alongA = (qx * bdz - qz * bdx) / den;
+            const alongB = (qx * adz - qz * adx) / den;
+            const cap = (v) => Math.max(-handle, Math.min(handle, v));
+            hA = cap(alongA);
+            hB = cap(alongB);
+        }
+        const c1x = from.x + adx * hA;
+        const c1z = from.z + adz * hA;
+        const c2x = to.x + bdx * hB;
+        const c2z = to.z + bdz * hB;
+        // Reject cubics that dive through the junction interior (would look like a diagonal cut).
+        const midT = 0.5;
+        const u = 1 - midT;
+        const mx = u * u * u * from.x + 3 * u * u * midT * c1x + 3 * u * midT * midT * c2x + midT * midT * midT * to.x;
+        const mz = u * u * u * from.z + 3 * u * u * midT * c1z + 3 * u * midT * midT * c2z + midT * midT * midT * to.z;
+        const chordMx = (from.x + to.x) / 2;
+        const chordMz = (from.z + to.z) / 2;
+        // Outward = away from node relative to the chord midpoint.
+        const away = (chordMx - cx) * (mx - chordMx) + (chordMz - cz) * (mz - chordMz);
+        if (away < -1e-6) {
+            // Flip handle signs so the bulge faces outward.
+            const f1x = from.x - adx * hA;
+            const f1z = from.z - adz * hA;
+            const f2x = to.x - bdx * hB;
+            const f2z = to.z - bdz * hB;
+            for (let s = 1; s < filletSegments; s += 1) {
+                const t = s / filletSegments;
+                const uu = 1 - t;
+                const x = uu * uu * uu * from.x + 3 * uu * uu * t * f1x + 3 * uu * t * t * f2x + t * t * t * to.x;
+                const z = uu * uu * uu * from.z + 3 * uu * uu * t * f1z + 3 * uu * t * t * f2z + t * t * t * to.z;
+                into.push({ x, y: sampleHeight(x, z) + elevation, z });
+            }
+            return;
+        }
+        for (let s = 1; s < filletSegments; s += 1) {
+            const t = s / filletSegments;
+            const uu = 1 - t;
+            const x = uu * uu * uu * from.x + 3 * uu * uu * t * c1x + 3 * uu * t * t * c2x + t * t * t * to.x;
+            const z = uu * uu * uu * from.z + 3 * uu * uu * t * c1z + 3 * uu * t * t * c2z + t * t * t * to.z;
+            into.push({ x, y: sampleHeight(x, z) + elevation, z });
+        }
+    };
+    const boundary = [];
+    let angularFallback = false;
+    for (let k = 0; k < ordered.length; k += 1) {
+        const ap = ordered[k];
+        boundary.push(ap.first);
+        boundary.push(ap.second);
+        if (ordered.length < 2)
+            continue;
+        const nxt = ordered[(k + 1) % ordered.length];
+        const cur = ap.second;
+        const to = nxt.first;
+        const L = Math.hypot(to.x - cur.x, to.z - cur.z);
+        if (L < 1e-6)
+            continue;
+        let armGap = wrapAngle(nxt.outAngle - ap.outAngle);
+        if (armGap < 0)
+            armGap += Math.PI * 2;
+        // Near-parallel two-arm fork: keep the four mouth corners as a compact star-shaped polygon.
+        if (ordered.length === 2 && Math.min(armGap, Math.PI * 2 - armGap) < (35 * Math.PI) / 180) {
+            angularFallback = true;
+            continue;
+        }
+        if (ordered.length === 2) {
+            // Degree-2 bend: the pavement is the L-union of the two strips. The short gap is the inside
+            // curb return; the long gap must pass through the outer edge-intersection so the surface is
+            // an L, not a diagonal chord (which under-covers) or an interior cubic (which self-crosses).
+            const minW = Math.min(ap.width, nxt.width);
+            const isOuter = L > minW * 0.75;
+            if (!isOuter) {
+                const handle = Math.min(curbReturnRadius * 0.55, L * 0.4, minW * 0.35);
+                if (handle > 1e-6)
+                    pushCurbCubic(cur, to, ap.outAngle, nxt.outAngle, handle, boundary);
+                continue;
+            }
+            const adx = Math.cos(ap.outAngle);
+            const adz = Math.sin(ap.outAngle);
+            const bdx = Math.cos(nxt.outAngle);
+            const bdz = Math.sin(nxt.outAngle);
+            const den = adx * bdz - adz * bdx;
+            if (Math.abs(den) <= 1e-6)
+                continue;
+            const qx = to.x - cur.x;
+            const qz = to.z - cur.z;
+            const alongA = (qx * bdz - qz * bdx) / den;
+            const alongB = (qx * adz - qz * adx) / den;
+            // Finite outer corner of the two edge lines; reject near-parallel runaway intersections.
+            const maxReach = Math.max(minW * 3, L * 1.5);
+            if (!Number.isFinite(alongA) || !Number.isFinite(alongB))
+                continue;
+            if (Math.abs(alongA) > maxReach || Math.abs(alongB) > maxReach)
+                continue;
+            const ix = cur.x + adx * alongA;
+            const iz = cur.z + adz * alongA;
+            // Must lie on the far side of the chord from the node (true outer corner).
+            const chordMx = (cur.x + to.x) / 2;
+            const chordMz = (cur.z + to.z) / 2;
+            if ((ix - chordMx) * (chordMx - cx) + (iz - chordMz) * (chordMz - cz) > 1e-6)
+                continue;
+            // Sharp L corner (optionally softened by a few samples pulled slightly toward the corner from
+            // each edge so the outer curb is not a single needle vertex on very acute angles).
+            const soft = Math.min(curbReturnRadius, minW * 0.25, Math.abs(alongA) * 0.35, Math.abs(alongB) * 0.35);
+            if (soft > 1e-3 && filletSegments > 1) {
+                for (let s = 1; s < filletSegments; s += 1) {
+                    const t = s / filletSegments;
+                    // Quadratic Bezier cur → outer-corner → to: always simple, always covers the L.
+                    const u = 1 - t;
+                    const x = u * u * cur.x + 2 * u * t * ix + t * t * to.x;
+                    const z = u * u * cur.z + 2 * u * t * iz + t * t * to.z;
+                    boundary.push({ x, y: sampleHeight(x, z) + elevation, z });
+                }
+            }
+            else {
+                boundary.push({ x: ix, y: sampleHeight(ix, iz) + elevation, z: iz });
+            }
+            continue;
+        }
+        // Multi-arm through-road far side (~180°): straight curb along the continuing carriageway.
+        if (armGap > (150 * Math.PI) / 180)
+            continue;
+        // Skip if the next mouth angularly overlaps (would sweep backward across a corner).
+        if (wrapAngle(nxt.firstAngle - ap.secondAngle) <= 1e-9)
+            continue;
+        const R = clampCurbReturnRadius(curbReturnRadius, ap.width, nxt.width, L);
+        if (R < 1e-6)
+            continue;
+        // Cubic quarter-circle uses ~0.55R handles; also never exceed the chord budget.
+        pushCurbCubic(cur, to, ap.outAngle, nxt.outAngle, Math.min(R * 0.55228475, L * 0.4), boundary);
+    }
+    if (angularFallback) {
+        boundary.sort((p, q) => Math.atan2(p.z - cz, p.x - cx) - Math.atan2(q.z - cz, q.x - cx));
+    }
+    const m = boundary.length;
+    const positions = new Float32Array((m + 1) * 3);
+    positions[0] = cx;
+    positions[1] = sampleHeight(cx, cz) + elevation;
+    positions[2] = cz;
+    for (let k = 0; k < m; k += 1) {
+        const p = boundary[k];
+        const base = (k + 1) * 3;
+        positions[base] = p.x;
+        positions[base + 1] = p.y;
+        positions[base + 2] = p.z;
+    }
+    // Ear-clip the grouped ring. A center fan requires a star-shaped polygon and the old global angle
+    // sort made one by separating unequal-width approach corners, destroying the exact mouth seam and
+    // leaving visible triangular holes. Ear clipping keeps every grouped boundary edge intact.
+    const idx = [];
+    const signedCross = (a, b, c) => {
+        const pa = boundary[a];
+        const pb = boundary[b];
+        const pc = boundary[c];
+        return (pb.x - pa.x) * (pc.z - pa.z) - (pb.z - pa.z) * (pc.x - pa.x);
+    };
+    let area = 0;
+    for (let i = 0; i < m; i += 1) {
+        const a = boundary[i];
+        const b = boundary[(i + 1) % m];
+        area += a.x * b.z - b.x * a.z;
+    }
+    const orientation = area >= 0 ? 1 : -1;
+    const pointInTriangle = (p, a, b, c) => {
+        const ab = signedCross(a, b, p) * orientation;
+        const bc = signedCross(b, c, p) * orientation;
+        const ca = signedCross(c, a, p) * orientation;
+        return ab >= -1e-9 && bc >= -1e-9 && ca >= -1e-9;
+    };
+    const remaining = Array.from({ length: m }, (_, i) => i);
+    let guard = 0;
+    while (remaining.length > 3 && guard < m * m) {
+        guard += 1;
+        let clipped = false;
+        for (let i = 0; i < remaining.length; i += 1) {
+            const prev = remaining[(i - 1 + remaining.length) % remaining.length];
+            const ear = remaining[i];
+            const next = remaining[(i + 1) % remaining.length];
+            if (signedCross(prev, ear, next) * orientation <= 1e-9)
+                continue;
+            let contains = false;
+            for (let j = 0; j < remaining.length; j += 1) {
+                const point = remaining[j];
+                if (point === prev || point === ear || point === next)
+                    continue;
+                if (pointInTriangle(point, prev, ear, next)) {
+                    contains = true;
+                    break;
+                }
+            }
+            if (contains)
+                continue;
+            // Standard XZ CCW points down in Three's X/Y/Z winding, so reverse CCW rings for +Y.
+            if (orientation > 0)
+                idx.push(prev + 1, next + 1, ear + 1);
+            else
+                idx.push(prev + 1, ear + 1, next + 1);
+            remaining.splice(i, 1);
+            clipped = true;
+            break;
+        }
+        if (!clipped)
+            break;
+    }
+    if (remaining.length === 3) {
+        if (orientation > 0)
+            idx.push(remaining[0] + 1, remaining[2] + 1, remaining[1] + 1);
+        else
+            idx.push(remaining[0] + 1, remaining[1] + 1, remaining[2] + 1);
+    }
+    return { positions, indices: Uint32Array.from(idx) };
+}
+function offsetPath(path, offset) {
+    const out = new Array(path.length);
+    for (let i = 0; i < path.length; i += 1) {
+        const [nx, nz] = normalAt(path, i);
+        out[i] = [path[i][0] + nx * offset, path[i][1] + nz * offset];
+    }
+    return out;
+}
+function buildRoadSidewalk(road, side, width, sampleHeight, elevation) {
+    const count = road.positions.length / 6;
+    if (count < 2 || width <= 0)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const positions = new Float32Array(count * 6);
+    for (let i = 0; i < count; i += 1) {
+        const leftX = road.positions[i * 6];
+        const leftZ = road.positions[i * 6 + 2];
+        const rightX = road.positions[i * 6 + 3];
+        const rightZ = road.positions[i * 6 + 5];
+        const innerX = side === "left" ? leftX : rightX;
+        const innerZ = side === "left" ? leftZ : rightZ;
+        const otherX = side === "left" ? rightX : leftX;
+        const otherZ = side === "left" ? rightZ : leftZ;
+        const dx = innerX - otherX;
+        const dz = innerZ - otherZ;
+        const length = Math.hypot(dx, dz) || 1;
+        const outerX = innerX + (dx / length) * width;
+        const outerZ = innerZ + (dz / length) * width;
+        positions[i * 6] = innerX;
+        positions[i * 6 + 1] = sampleHeight(innerX, innerZ) + elevation;
+        positions[i * 6 + 2] = innerZ;
+        positions[i * 6 + 3] = outerX;
+        positions[i * 6 + 4] = sampleHeight(outerX, outerZ) + elevation;
+        positions[i * 6 + 5] = outerZ;
+    }
+    const indices = new Uint32Array((count - 1) * 6);
+    const writeUpTriangle = (at, i0, i1, i2) => {
+        const ax = positions[i1 * 3] - positions[i0 * 3];
+        const az = positions[i1 * 3 + 2] - positions[i0 * 3 + 2];
+        const bx = positions[i2 * 3] - positions[i0 * 3];
+        const bz = positions[i2 * 3 + 2] - positions[i0 * 3 + 2];
+        indices[at] = i0;
+        if (az * bx - ax * bz >= 0) {
+            indices[at + 1] = i1;
+            indices[at + 2] = i2;
+        }
+        else {
+            indices[at + 1] = i2;
+            indices[at + 2] = i1;
+        }
+    };
+    for (let i = 0; i < count - 1; i += 1) {
+        const a = i * 2;
+        writeUpTriangle(i * 6, a, a + 1, a + 2);
+        writeUpTriangle(i * 6 + 3, a + 1, a + 3, a + 2);
+    }
+    return { positions, indices };
+}
+function buildSidewalkApron(junction, surface, approaches, sampleHeight, elevation) {
+    const ring = [];
+    for (let v = 1; v * 3 + 2 < surface.positions.length; v += 1) {
+        ring.push([surface.positions[v * 3], surface.positions[v * 3 + 2]]);
+    }
+    if (ring.length < 2)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const corners = [];
+    for (let i = 0; i < approaches.length; i += 1) {
+        const ap = approaches[i];
+        const dx = ap.direction?.[0] ?? ap.center[0] - junction.x;
+        const dz = ap.direction?.[1] ?? ap.center[1] - junction.z;
+        const length = Math.hypot(dx, dz) || 1;
+        const ux = dx / length;
+        const uz = dz / length;
+        // Left normal of the outward approach direction (matches ribbon left/right).
+        const nx = -uz;
+        const nz = ux;
+        const leftWidth = Math.max(0, ap.sidewalkWidths?.left ?? 0);
+        const rightWidth = Math.max(0, ap.sidewalkWidths?.right ?? 0);
+        const sourceDot = (ap.sourceTangent?.[0] ?? ux) * ux + (ap.sourceTangent?.[1] ?? uz) * uz;
+        const left = [ap.left[0], ap.left[2]];
+        const right = [ap.right[0], ap.right[2]];
+        const sourceSign = sourceDot >= 0 ? 1 : -1;
+        corners.push({
+            point: left,
+            outer: [left[0] + nx * leftWidth * sourceSign, left[1] + nz * leftWidth * sourceSign],
+            approach: i,
+            width: leftWidth,
+        });
+        corners.push({
+            point: right,
+            outer: [right[0] - nx * rightWidth * sourceSign, right[1] - nz * rightWidth * sourceSign],
+            approach: i,
+            width: rightWidth,
+        });
+    }
+    if (corners.length === 0)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const nearestCorner = (p) => {
+        let corner = corners[0];
+        let distance = Infinity;
+        for (let i = 0; i < corners.length; i += 1) {
+            const candidate = corners[i];
+            const d = Math.hypot(candidate.point[0] - p[0], candidate.point[1] - p[1]);
+            if (d < distance) {
+                corner = candidate;
+                distance = d;
+            }
+        }
+        return { corner, distance };
+    };
+    /**
+     * Offset a pavement-boundary point outward along the local ring normal by the sidewalk width.
+     * Using the ring normal (not a radial vector from the junction) keeps the apron a constant-width
+     * band around the curb — no giant annular/octagonal pads.
+     */
+    const outerAt = (p, index) => {
+        const nearest = nearestCorner(p);
+        if (nearest.distance < 1e-3)
+            return nearest.corner.outer;
+        const prev = ring[(index - 1 + ring.length) % ring.length];
+        const next = ring[(index + 1) % ring.length];
+        let tx = next[0] - prev[0];
+        let tz = next[1] - prev[1];
+        const tl = Math.hypot(tx, tz);
+        if (tl < 1e-9) {
+            tx = next[0] - p[0];
+            tz = next[1] - p[1];
+        }
+        const tlen = Math.hypot(tx, tz) || 1;
+        tx /= tlen;
+        tz /= tlen;
+        // Outward normal: perpendicular of the tangent pointing away from the node.
+        let nx = -tz;
+        let nz = tx;
+        if ((p[0] - junction.x) * nx + (p[1] - junction.z) * nz < 0) {
+            nx = -nx;
+            nz = -nz;
+        }
+        // Interpolate width from the two nearest mouth corners so unequal sidewalks blend around the arc.
+        let w0 = nearest.corner.width;
+        let w1 = w0;
+        let d1 = Infinity;
+        for (const candidate of corners) {
+            if (candidate === nearest.corner)
+                continue;
+            const d = Math.hypot(candidate.point[0] - p[0], candidate.point[1] - p[1]);
+            if (d < d1) {
+                d1 = d;
+                w1 = candidate.width;
+            }
+        }
+        const t = nearest.distance + d1 > 1e-9 ? d1 / (nearest.distance + d1) : 0.5;
+        const width = Math.max(0, w0 * t + w1 * (1 - t));
+        if (width < 1e-9)
+            return p;
+        return [p[0] + nx * width, p[1] + nz * width];
+    };
+    const positions = [];
+    const indices = [];
+    const vertices = new Map();
+    const vertex = (p) => {
+        const key = `${p[0]},${p[1]}`;
+        const found = vertices.get(key);
+        if (found !== undefined)
+            return found;
+        const index = positions.length / 3;
+        positions.push(p[0], sampleHeight(p[0], p[1]) + elevation, p[1]);
+        vertices.set(key, index);
+        return index;
+    };
+    const pushUpTriangle = (i0, i1, i2) => {
+        const ax = positions[i1 * 3] - positions[i0 * 3];
+        const az = positions[i1 * 3 + 2] - positions[i0 * 3 + 2];
+        const bx = positions[i2 * 3] - positions[i0 * 3];
+        const bz = positions[i2 * 3 + 2] - positions[i0 * 3 + 2];
+        if (az * bx - ax * bz >= 0)
+            indices.push(i0, i1, i2);
+        else
+            indices.push(i0, i2, i1);
+    };
+    for (let i = 0; i < ring.length; i += 1) {
+        const a = ring[i];
+        const b = ring[(i + 1) % ring.length];
+        const ca = nearestCorner(a);
+        const cb = nearestCorner(b);
+        // The paired corners of one approach are a road mouth, not sidewalk: leave it open.
+        if (ca.distance < 1e-3 && cb.distance < 1e-3 && ca.corner.approach === cb.corner.approach)
+            continue;
+        const ao = outerAt(a, i);
+        const bo = outerAt(b, (i + 1) % ring.length);
+        if (Math.hypot(ao[0] - a[0], ao[1] - a[1]) < 1e-9 && Math.hypot(bo[0] - b[0], bo[1] - b[1]) < 1e-9)
+            continue;
+        const ai = vertex(a);
+        const bi = vertex(b);
+        const aoi = vertex(ao);
+        const boi = vertex(bo);
+        pushUpTriangle(ai, bi, aoi);
+        pushUpTriangle(bi, boi, aoi);
+    }
+    return { positions: Float32Array.from(positions), indices: Uint32Array.from(indices) };
+}
+/**
+ * Trim a set of streets against a set of junctions and weld the crossing surfaces in one call — the
+ * ergonomic entry the shell/playground consume for meshing.
+ *
+ * Each street is trimmed by {@link trimPathAtJunctions} (through-streets split in two), each surviving
+ * sub-path is meshed with {@link buildRoadRibbon}, and every junction that any ribbon actually ends
+ * at gets one {@link buildJunctionSurface}. The junction's boundary vertices are read back BITWISE
+ * from the ribbons' terminal cross-sections, so ribbon and surface share the exact same floats at
+ * the seam — no overlap, no z-fighting, no floating disc. Ribbons and surfaces both live on the
+ * seam-shared {@link GROUND_DECAL_LAYERS}.road/.junction layer. Deterministic (junctions emitted in
+ * ascending index order) and bounded by the street/junction counts.
+ *
+ * @capability world-intersections trim streets at junctions and weld curb-return crossing surfaces in one call
+ */
+export function buildTrimmedIntersections(streets, junctions, sampleHeight, options = {}) {
+    const ribbonElevation = options.elevation ?? GROUND_DECAL_LAYERS.road;
+    const ribbons = [];
+    const trimmed = [];
+    const trimmedStreetIndices = [];
+    const trimmedWidths = [];
+    const trimmedMarkings = [];
+    const sidewalks = [];
+    const approachesByJunction = new Map();
+    for (let s = 0; s < streets.length; s += 1) {
+        const street = streets[s];
+        const subs = trimPathAtJunctions(street.path, street.width, junctions, options);
+        for (let r = 0; r < subs.length; r += 1) {
+            const tr = subs[r];
+            const ribbon = buildRoadRibbon(tr.path, street.width, sampleHeight, {
+                elevation: ribbonElevation,
+                maxSegmentLength: options.maxSegmentLength,
+            });
+            if (ribbon.positions.length < 12)
+                continue; // degenerate — no terminal cross-section to weld
+            ribbons.push(ribbon);
+            trimmed.push(tr);
+            const trimmedIndex = trimmed.length - 1;
+            trimmedStreetIndices.push(s);
+            trimmedWidths.push(street.width);
+            trimmedMarkings.push(street.markings);
+            const leftSidewalk = Math.max(0, street.sidewalks?.left ?? 0);
+            const rightSidewalk = Math.max(0, street.sidewalks?.right ?? 0);
+            if (leftSidewalk > 0) {
+                sidewalks.push(buildRoadSidewalk(ribbon, "left", leftSidewalk, sampleHeight, ribbonElevation));
+            }
+            if (rightSidewalk > 0) {
+                sidewalks.push(buildRoadSidewalk(ribbon, "right", rightSidewalk, sampleHeight, ribbonElevation));
+            }
+            const numPoints = ribbon.positions.length / 6;
+            for (let c = 0; c < tr.cuts.length; c += 1) {
+                const cut = tr.cuts[c];
+                const leftVert = cut.at === "start" ? 0 : (numPoints - 1) * 2;
+                const rightVert = leftVert + 1;
+                const approach = {
+                    center: cut.center,
+                    left: [ribbon.positions[leftVert * 3], ribbon.positions[leftVert * 3 + 1], ribbon.positions[leftVert * 3 + 2]],
+                    right: [ribbon.positions[rightVert * 3], ribbon.positions[rightVert * 3 + 1], ribbon.positions[rightVert * 3 + 2]],
+                    direction: cut.direction,
+                    sourceTangent: cut.at === "start" ? cut.direction : [-cut.direction[0], -cut.direction[1]],
+                    streetIndex: s,
+                    trimmedIndex,
+                    cutAt: cut.at,
+                    width: street.width,
+                    sidewalkWidths: street.sidewalks,
+                    markings: street.markings,
+                };
+                const list = approachesByJunction.get(cut.junctionIndex);
+                if (list)
+                    list.push(approach);
+                else
+                    approachesByJunction.set(cut.junctionIndex, [approach]);
+            }
+        }
+    }
+    const junctionSurfaces = [];
+    const junctionIndices = [];
+    const junctionApproaches = [];
+    const sidewalkAprons = [];
+    const sidewalkApronJunctionIndices = [];
+    const sortedIndices = [...approachesByJunction.keys()].sort((p, q) => p - q);
+    for (let i = 0; i < sortedIndices.length; i += 1) {
+        const ji = sortedIndices[i];
+        const j = junctions[ji];
+        const approaches = approachesByJunction.get(ji);
+        const surface = buildJunctionSurface(j, approaches, sampleHeight, options);
+        junctionSurfaces.push(surface);
+        const apron = buildSidewalkApron(j, surface, approaches, sampleHeight, ribbonElevation);
+        if (apron.indices.length > 0) {
+            sidewalkAprons.push(apron);
+            sidewalkApronJunctionIndices.push(ji);
+        }
+        junctionIndices.push(ji);
+        junctionApproaches.push(approaches);
+    }
+    return {
+        ribbons,
+        trimmed,
+        junctions: junctionSurfaces,
+        junctionIndices,
+        junctionApproaches,
+        trimmedStreetIndices,
+        trimmedWidths,
+        trimmedMarkings,
+        sidewalks,
+        sidewalkAprons,
+        sidewalkApronJunctionIndices,
+    };
+}
+function markingPoint(ap, line) {
+    const tangent = ap.sourceTangent ?? ap.direction ?? [1, 0];
+    const offset = Number.isFinite(line.offset) ? line.offset : 0;
+    return [ap.center[0] - tangent[1] * offset, ap.center[1] + tangent[0] * offset];
+}
+function buildOffsetConnector(a, b, aLine, bLine, segments) {
+    const start = markingPoint(a, aLine);
+    const end = markingPoint(b, bLine);
+    const ad = a.direction;
+    const bd = b.direction;
+    if (ad === undefined || bd === undefined)
+        return null;
+    const chord = Math.hypot(end[0] - start[0], end[1] - start[1]);
+    const handle = chord * 0.45;
+    const c1 = [start[0] - ad[0] * handle, start[1] - ad[1] * handle];
+    const c2 = [end[0] - bd[0] * handle, end[1] - bd[1] * handle];
+    const count = Math.max(2, Math.min(64, Math.floor(Number.isFinite(segments) ? segments : 8)));
+    const path = [];
+    for (let i = 0; i <= count; i += 1) {
+        const t = i / count;
+        const u = 1 - t;
+        path.push([
+            u * u * u * start[0] + 3 * u * u * t * c1[0] + 3 * u * t * t * c2[0] + t * t * t * end[0],
+            u * u * u * start[1] + 3 * u * u * t * c1[1] + 3 * u * t * t * c2[1] + t * t * t * end[1],
+        ]);
+    }
+    return path;
+}
+/**
+ * Mesh the paint declared on streets passed to {@link buildTrimmedIntersections}. Longitudinal
+ * ribbons follow the trimmed road paths. At degree-2 nodes corresponding lines are joined by a
+ * tangent-continuous cubic (signed offsets are preserved); at multi-arm nodes lines deliberately
+ * stop short of the mouth and optional transverse stop lines make that termination readable.
+ * @capability world-intersections connect sidewalks and lane guidance through generated intersections
+ */
+export function buildIntersectionMarkings(intersections, sampleHeight, options = {}) {
+    const mouthClearance = Math.max(0, options.mouthClearance ?? 1);
+    const lineWidth = options.lineWidth ?? 0.15;
+    const stopLineWidth = options.stopLineWidth ?? 0.35;
+    const edgeClearance = Math.max(0, options.stopLineEdgeClearance ?? 0.5);
+    const elevation = options.elevation ?? GROUND_DECAL_LAYERS.marking;
+    const requestedStep = options.maxSegmentLength ?? 4;
+    const maxSegmentLength = Number.isFinite(requestedStep)
+        ? Math.max(0.25, Math.min(100, requestedStep))
+        : 4;
+    const ribbons = [];
+    const appendLongitudinal = (path, width) => {
+        const dashLength = options.dashLength ?? 0;
+        const pieces = dashLength > 0 ? dashSegments(path, dashLength, Math.max(0, options.dashGap ?? 3)) : [path];
+        for (const piece of pieces) {
+            const ribbon = buildRoadRibbon(piece, width, sampleHeight, { elevation, maxSegmentLength });
+            if (ribbon.indices.length > 0)
+                ribbons.push(ribbon);
+        }
+    };
+    const approachByTrim = new Map();
+    for (let j = 0; j < intersections.junctionApproaches.length; j += 1) {
+        const approaches = intersections.junctionApproaches[j];
+        for (const ap of approaches) {
+            if (ap.trimmedIndex !== undefined && ap.cutAt !== undefined) {
+                approachByTrim.set(`${ap.trimmedIndex}:${ap.cutAt}`, { approach: ap, degree: approaches.length });
+            }
+        }
+    }
+    for (let i = 0; i < intersections.trimmed.length; i += 1) {
+        const intent = intersections.trimmedMarkings[i];
+        if (intent === undefined)
+            continue;
+        const trimmed = intersections.trimmed[i];
+        for (const line of intent.lines ?? []) {
+            let path = offsetPath(trimmed.path, line.offset ?? 0);
+            let startClearance = 0;
+            let endClearance = 0;
+            for (const cut of trimmed.cuts) {
+                const match = approachByTrim.get(`${i}:${cut.at}`);
+                if (match?.degree !== undefined && match.degree > 2) {
+                    if (cut.at === "start")
+                        startClearance = mouthClearance;
+                    else
+                        endClearance = mouthClearance;
+                }
+            }
+            const length = pathLength(path);
+            if (startClearance + endClearance >= length - 1e-6)
+                continue;
+            if (startClearance > 0) {
+                const cut = pointAtArcLength(path, startClearance);
+                path = [cut.point, ...path.slice(cut.segment + 1)];
+            }
+            if (endClearance > 0) {
+                const cut = pointAtArcLength(path, pathLength(path) - endClearance);
+                path = [...path.slice(0, cut.segment + 1), cut.point];
+            }
+            appendLongitudinal(path, line.width ?? lineWidth);
+        }
+    }
+    for (let j = 0; j < intersections.junctionApproaches.length; j += 1) {
+        const approaches = intersections.junctionApproaches[j];
+        if (approaches.length === 2) {
+            const aLines = approaches[0].markings?.lines ?? [];
+            const bLines = approaches[1].markings?.lines ?? [];
+            const candidates = [];
+            for (let a = 0; a < Math.min(aLines.length, 16); a += 1) {
+                for (let b = 0; b < Math.min(bLines.length, 16); b += 1) {
+                    const ap = markingPoint(approaches[0], aLines[a]);
+                    const bp = markingPoint(approaches[1], bLines[b]);
+                    candidates.push({ a, b, distance: Math.hypot(ap[0] - bp[0], ap[1] - bp[1]) });
+                }
+            }
+            candidates.sort((p, q) => p.distance - q.distance || p.a - q.a || p.b - q.b);
+            const usedA = new Set();
+            const usedB = new Set();
+            for (const pair of candidates) {
+                if (usedA.has(pair.a) || usedB.has(pair.b))
+                    continue;
+                usedA.add(pair.a);
+                usedB.add(pair.b);
+                const aLine = aLines[pair.a];
+                const bLine = bLines[pair.b];
+                const path = buildOffsetConnector(approaches[0], approaches[1], aLine, bLine, options.connectorSegments ?? 8);
+                if (path !== null) {
+                    const aWidth = Number.isFinite(aLine.width) ? aLine.width : lineWidth;
+                    const bWidth = Number.isFinite(bLine.width) ? bLine.width : lineWidth;
+                    const width = Math.max(0.01, Math.min(aWidth, bWidth));
+                    appendLongitudinal(path, width);
+                }
+            }
+            continue;
+        }
+        if (approaches.length < 3)
+            continue;
+        for (const ap of approaches) {
+            if (!ap.markings?.stopLine || ap.direction === undefined || ap.width === undefined)
+                continue;
+            const half = Math.max(0, ap.width / 2 - edgeClearance);
+            if (half <= 0 || stopLineWidth <= 0)
+                continue;
+            const cx = ap.center[0] + ap.direction[0] * mouthClearance;
+            const cz = ap.center[1] + ap.direction[1] * mouthClearance;
+            const nx = -ap.direction[1];
+            const nz = ap.direction[0];
+            const path = [[cx - nx * half, cz - nz * half], [cx + nx * half, cz + nz * half]];
+            ribbons.push(buildRoadRibbon(path, stopLineWidth, sampleHeight, { elevation, maxSegmentLength }));
+        }
+    }
+    return ribbons;
+}