@jgengine/core 0.18.0 → 0.18.1

package/dist/world/raceCircuit.js

@@ -0,0 +1,797 @@
+/**
+ * A race circuit is a SECTION OF A CITY, blocked off — not a separate shape. This module lifts a
+ * closed lap out of an existing {@link StreetNetwork}: pick a cycle through the streets that are
+ * already there, then SEAL every side street leaving it. That is how a street race works in an open
+ * world (drive the city freely, then an instanced event fences a few blocks into a lap) and how a
+ * real street circuit works (Monaco, Detroit, Baku are public roads with barriers dropped in).
+ *
+ * The route is derived, never invented: `centerline`, `widths`, and `heights` are read off the same
+ * {@link StreetEdge}s the open world drives on, so the lap and the city are byte-for-byte the same
+ * asphalt. Everything a race needs comes with it — {@link CircuitSeal}s (the barriers that make it an
+ * instance), ordered {@link CircuitGate}s that hand straight to `raceTrack({ checkpoints })`,
+ * start/finish, a staggered grid, corner analysis, kerbs, and timing sectors.
+ *
+ * Works on either topology family the generator produces. On a `net` (a city) it searches the graph
+ * for the cycle that best matches the requested lap length and arterial bias. On a `circuit` (the
+ * generator's closed-loop mode) the loop edges ARE the cycle, so the same call returns the whole lap
+ * — one API, both slider extremes, no second code path.
+ *
+ * Volume-local XZ coords throughout, matching {@link StreetNetwork}; the caller rotates/translates
+ * into world space. Deterministic: same network + rules ⇒ identical route, with bounded search work.
+ *
+ * @capability race-circuit lift a closed, sealed-off race lap out of an existing city street network
+ */
+import { seededRng } from "../random/rng.js";
+/** Road hierarchy rank — higher is wider/more arterial. Shared with the fabric's ordering. */
+const LEVEL_RANK = { lane: 0, street: 1, avenue: 2, boulevard: 3 };
+/** Sharpest turn a lap takes at a junction (radians). Beyond this it doubles back on itself. */
+const MAX_LAP_TURN = (120 * Math.PI) / 180;
+/**
+ * Worst self-approach of a closed lap, as `gap − required` over every non-adjacent pair of points;
+ * negative means two stretches of the lap are close enough that their road surfaces overlap. The
+ * generator holds the same invariant for its own circuits — an extracted lap needs it too, or a
+ * junction fold hands back a "lap" that drives through itself.
+ */
+function selfClearance(points, widths) {
+    const n = points.length;
+    const { at, total } = arcLengths(points);
+    let worst = Infinity;
+    for (let i = 0; i < n; i += 1) {
+        const a = points[i];
+        for (let j = i + 1; j < n; j += 1) {
+            const required = ((widths[i] ?? 9) + (widths[j] ?? 9)) * 0.5 * 1.15;
+            // Adjacency is measured along the lap, not in indices: two points a whole corner apart may
+            // still be one short edge apart by index, and that pair is not an overlap.
+            const along = at[j] - at[i];
+            if (Math.min(along, total - along) < required * 2.5)
+                continue;
+            const b = points[j];
+            const gap = Math.hypot(a[0] - b[0], a[1] - b[1]) - required;
+            if (gap < worst)
+                worst = gap;
+        }
+    }
+    return worst;
+}
+/** Defaults: a ~2.4 km arterial street lap with 12 gates, 3 laps, and barriered side streets. */
+export const CIRCUIT_ROUTE_DEFAULTS = {
+    seed: "circuit",
+    lapLength: 2400,
+    arterialBias: 0.7,
+    minCornerRadius: 9,
+    checkpoints: 12,
+    laps: 3,
+    gateHeight: 6,
+    gridSlots: 12,
+    sealKind: "barrier",
+    sectors: 3,
+    sampleStep: 2.5,
+    cornerCut: 0.42,
+};
+function edgeLength(points) {
+    let total = 0;
+    for (let i = 0; i + 1 < points.length; i += 1) {
+        const a = points[i];
+        const b = points[i + 1];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return total;
+}
+function buildAdjacency(network) {
+    const links = new Map();
+    const edgeById = new Map();
+    const nodeAt = new Map();
+    for (const node of network.nodes)
+        nodeAt.set(node.id, { x: node.x, z: node.z });
+    for (const edge of network.edges) {
+        if (edge.a === edge.b)
+            continue;
+        edgeById.set(edge.id, edge);
+        const forward = links.get(edge.a) ?? [];
+        forward.push({ edge: edge.id, other: edge.b });
+        links.set(edge.a, forward);
+        const back = links.get(edge.b) ?? [];
+        back.push({ edge: edge.id, other: edge.a });
+        links.set(edge.b, back);
+    }
+    return { links, edgeById, nodeAt };
+}
+/** Direction (radians) leaving `node` along `edge`, read off the edge's first sampled span. */
+function departureHeading(edge, node) {
+    const points = edge.points;
+    if (points.length < 2)
+        return 0;
+    const forward = edge.a === node;
+    const from = forward ? points[0] : points[points.length - 1];
+    const to = forward ? points[1] : points[points.length - 2];
+    return Math.atan2(to[0] - from[0], to[1] - from[1]);
+}
+function angleDelta(a, b) {
+    let d = b - a;
+    while (d > Math.PI)
+        d -= Math.PI * 2;
+    while (d < -Math.PI)
+        d += Math.PI * 2;
+    return d;
+}
+/**
+ * Chain the lap's edges into one continuous centerline, carrying per-point width and height. Each
+ * edge is walked in its traversal direction and its shared endpoint dropped, so the polyline closes
+ * without a duplicated seam vertex.
+ */
+function assembleCenterline(nodes, edges, adjacency) {
+    const centerline = [];
+    const widths = [];
+    const heights = [];
+    let anyHeights = false;
+    for (let i = 0; i < edges.length; i += 1) {
+        const edge = adjacency.edgeById.get(edges[i]);
+        if (edge === undefined)
+            continue;
+        const from = nodes[i];
+        const forward = edge.a === from;
+        const points = forward ? edge.points : [...edge.points].reverse();
+        const edgeHeights = edge.heights === undefined ? null : forward ? edge.heights : [...edge.heights].reverse();
+        if (edgeHeights !== null)
+            anyHeights = true;
+        // Drop the shared endpoint so consecutive edges weld into one polyline.
+        for (let p = 0; p + 1 < points.length; p += 1) {
+            centerline.push(points[p]);
+            widths.push(edge.width);
+            heights.push(edgeHeights?.[p] ?? 0);
+        }
+    }
+    return { centerline, widths, heights: anyHeights ? heights : null };
+}
+/**
+ * Resample a closed lap to a fixed arc-length step, interpolating width and height. City street
+ * polylines are emitted at whatever resolution the road ribbon needed (often 15 m between vertices);
+ * a racing surface, corner analysis, and kerbs all need a dense, evenly spaced line.
+ */
+function resampleClosed(points, widths, heights, step) {
+    const n = points.length;
+    // Cumulative arc length at the START of each of the n closed segments, so the wrap-around segment
+    // from the last vertex back to the first is sampled like any other.
+    const starts = new Array(n + 1).fill(0);
+    for (let i = 0; i < n; i += 1) {
+        const a = points[i];
+        const b = points[(i + 1) % n];
+        starts[i + 1] = starts[i] + Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    const total = starts[n];
+    if (total < 1e-6)
+        return { points: [...points], widths: [...widths], heights: heights === null ? null : [...heights] };
+    const count = Math.max(12, Math.min(4000, Math.round(total / step)));
+    const spacing = total / count;
+    const out = [];
+    const outWidths = [];
+    const outHeights = heights === null ? null : [];
+    let segment = 0;
+    for (let i = 0; i < count; i += 1) {
+        const distance = i * spacing;
+        while (segment + 1 < n && starts[segment + 1] <= distance)
+            segment += 1;
+        const spanStart = starts[segment];
+        const spanLength = starts[segment + 1] - spanStart;
+        const t = spanLength < 1e-9 ? 0 : Math.max(0, Math.min(1, (distance - spanStart) / spanLength));
+        const a = points[segment];
+        const b = points[(segment + 1) % n];
+        out.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+        const wa = widths[segment] ?? 9;
+        const wb = widths[(segment + 1) % widths.length] ?? wa;
+        outWidths.push(wa + (wb - wa) * t);
+        if (outHeights !== null && heights !== null) {
+            const ha = heights[segment] ?? 0;
+            const hb = heights[(segment + 1) % heights.length] ?? ha;
+            outHeights.push(ha + (hb - ha) * t);
+        }
+    }
+    return { points: out, widths: outWidths, heights: outHeights };
+}
+/**
+ * Round the lap's junction corners into a drivable racing line. A city lap turning from one street
+ * onto another inherits the junction's hard ~90° kink; a real street circuit takes that corner on a
+ * curve. Relax every point tighter than `minRadius` toward its neighbours, but cap how far any point
+ * may leave the street centerline so the line never drives off the asphalt it inherited.
+ */
+function roundCorners(points, widths, minRadius, cut) {
+    const n = points.length;
+    if (n < 8 || cut <= 0)
+        return [...points];
+    const origin = points.map((point) => [point[0], point[1]]);
+    const working = origin.map((point) => [point[0], point[1]]);
+    const budget = widths.map((width) => Math.max(0, width * 0.5 * cut));
+    const span = Math.max(minRadius * 0.5, polylineLength(points, true) / n * 3);
+    for (let pass = 0; pass < 24; pass += 1) {
+        const radii = curvatureProfile(working, span);
+        let moved = 0;
+        for (let i = 0; i < n; i += 1) {
+            if (radii[i] >= minRadius)
+                continue;
+            const prev = working[(i - 1 + n) % n];
+            const next = working[(i + 1) % n];
+            const targetX = (prev[0] + next[0]) * 0.5;
+            const targetZ = (prev[1] + next[1]) * 0.5;
+            const here = working[i];
+            let x = here[0] + (targetX - here[0]) * 0.5;
+            let z = here[1] + (targetZ - here[1]) * 0.5;
+            // Clamp back inside the road: the racing line may cut a corner, never leave the street.
+            const base = origin[i];
+            const driftX = x - base[0];
+            const driftZ = z - base[1];
+            const drift = Math.hypot(driftX, driftZ);
+            const limit = budget[i];
+            if (drift > limit && drift > 1e-9) {
+                x = base[0] + (driftX / drift) * limit;
+                z = base[1] + (driftZ / drift) * limit;
+            }
+            moved += Math.hypot(x - here[0], z - here[1]);
+            here[0] = x;
+            here[1] = z;
+        }
+        if (moved < 0.01)
+            break;
+    }
+    return working.map((point) => [point[0], point[1]]);
+}
+function polylineLength(points, closed) {
+    let total = 0;
+    const last = closed ? points.length : points.length - 1;
+    for (let i = 0; i < last; i += 1) {
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return total;
+}
+/** Radius of the circle through three points; Infinity when they are collinear. */
+function circumRadius(a, b, c) {
+    const abx = b[0] - a[0];
+    const abz = b[1] - a[1];
+    const cbx = b[0] - c[0];
+    const cbz = b[1] - c[1];
+    const cross = abx * cbz - abz * cbx;
+    if (Math.abs(cross) < 1e-9)
+        return Infinity;
+    const ab = Math.hypot(abx, abz);
+    const bc = Math.hypot(cbx, cbz);
+    const ca = Math.hypot(c[0] - a[0], c[1] - a[1]);
+    return (ab * bc * ca) / (2 * Math.abs(cross));
+}
+/** Per-point radius of curvature over a closed polyline, measured across a ~`span` meter chord. */
+function curvatureProfile(points, span) {
+    const n = points.length;
+    const radii = new Array(n).fill(Infinity);
+    if (n < 5)
+        return radii;
+    const perPoint = polylineLength(points, true) / n;
+    const step = Math.max(1, Math.round(span / Math.max(0.5, perPoint)));
+    for (let i = 0; i < n; i += 1) {
+        const prev = points[(i - step + n * 2) % n];
+        const here = points[i];
+        const next = points[(i + step) % n];
+        radii[i] = circumRadius(prev, here, next);
+    }
+    return radii;
+}
+/**
+ * Group the sub-threshold stretches of a curvature profile into discrete corners. The profile is
+ * smoothed and short stretches dropped first: raw per-sample curvature on a dense line flickers
+ * across any threshold, which would otherwise report one sweeper as a dozen "corners".
+ */
+function analyzeCorners(points, radii, threshold, minArc, spacing) {
+    const n = points.length;
+    const corners = [];
+    if (n < 8)
+        return corners;
+    const smoothed = radii.map((_, i) => {
+        let sum = 0;
+        for (let k = -2; k <= 2; k += 1)
+            sum += radii[(i + k + n * 3) % n];
+        return sum / 5;
+    });
+    const tight = smoothed.map((r) => r < threshold);
+    // Bridge tiny straights so one flowing corner is not split by a sample of relief.
+    const bridge = Math.max(1, Math.round(minArc / Math.max(0.5, spacing) / 2));
+    for (let i = 0; i < n; i += 1) {
+        if (tight[i])
+            continue;
+        let gap = 0;
+        while (gap < bridge && !tight[(i + gap) % n])
+            gap += 1;
+        if (gap < bridge && tight[(i - 1 + n) % n] && tight[(i + gap) % n]) {
+            for (let k = 0; k < gap; k += 1)
+                tight[(i + k) % n] = true;
+        }
+    }
+    const minSpan = Math.max(3, Math.round(minArc / Math.max(0.5, spacing)));
+    // Rotate the scan so it never starts mid-corner, otherwise one corner splits across the seam.
+    let origin = tight.findIndex((value) => !value);
+    if (origin < 0)
+        origin = 0;
+    let index = 0;
+    while (index < n) {
+        const at = (origin + index) % n;
+        if (!tight[at]) {
+            index += 1;
+            continue;
+        }
+        let span = 0;
+        let apex = at;
+        let best = smoothed[at];
+        while (span < n && tight[(origin + index + span) % n]) {
+            const cursor = (origin + index + span) % n;
+            if (smoothed[cursor] < best) {
+                best = smoothed[cursor];
+                apex = cursor;
+            }
+            span += 1;
+        }
+        if (span < minSpan) {
+            index += span;
+            continue;
+        }
+        const entry = at;
+        const exit = (origin + index + span - 1) % n;
+        const before = points[(entry - 1 + n) % n];
+        const atPoint = points[entry];
+        const afterPoint = points[exit];
+        const after = points[(exit + 1) % n];
+        const headingIn = Math.atan2(atPoint[0] - before[0], atPoint[1] - before[1]);
+        const headingOut = Math.atan2(after[0] - afterPoint[0], after[1] - afterPoint[1]);
+        const turn = angleDelta(headingIn, headingOut);
+        corners.push({
+            apex,
+            radius: best,
+            angle: Math.abs(turn),
+            direction: turn >= 0 ? 1 : -1,
+            entry,
+            exit,
+        });
+        index += span;
+    }
+    return corners;
+}
+/** Cumulative arc length at each point of a closed polyline, plus the total. */
+function arcLengths(points) {
+    const at = new Array(points.length).fill(0);
+    let total = 0;
+    for (let i = 0; i < points.length; i += 1) {
+        at[i] = total;
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1]);
+    }
+    return { at, total };
+}
+/** Index whose arc length is closest to `distance` around the lap. */
+function indexAtDistance(at, total, distance) {
+    const target = ((distance % total) + total) % total;
+    let lo = 0;
+    let hi = at.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (at[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function headingAt(points, index) {
+    const n = points.length;
+    const a = points[index];
+    const b = points[(index + 1) % n];
+    return Math.atan2(b[0] - a[0], b[1] - a[1]);
+}
+/**
+ * Locate the longest low-curvature run — the start/finish straight. Returns the centerline index
+ * two-thirds along it, so the grid has room behind the line and the first corner room ahead.
+ */
+function findStartIndex(radii, at, total, straightRadius) {
+    const n = radii.length;
+    let bestStart = 0;
+    let bestLength = -1;
+    let runStart = -1;
+    // Two passes so a run wrapping the seam is measured whole.
+    for (let i = 0; i < n * 2; i += 1) {
+        const cursor = i % n;
+        const straight = radii[cursor] >= straightRadius;
+        if (straight && runStart < 0)
+            runStart = i;
+        if (!straight && runStart >= 0) {
+            const spanStart = at[runStart % n];
+            const spanEnd = at[(i - 1) % n];
+            const length = spanEnd >= spanStart ? spanEnd - spanStart : total - spanStart + spanEnd;
+            if (length > bestLength) {
+                bestLength = length;
+                bestStart = runStart % n;
+            }
+            runStart = -1;
+            if (i >= n)
+                break;
+        }
+    }
+    if (bestLength <= 0)
+        return 0;
+    return indexAtDistance(at, total, at[bestStart] + bestLength * 0.66);
+}
+/**
+ * Randomized cycle search over the street graph. Each attempt walks node to node without revisiting,
+ * biased toward arterial roads and toward carrying straight on, and closes the loop once the walk is
+ * long enough to reach the target and an edge back to the start exists. Bounded attempts and bounded
+ * walk length keep the work fixed however large the network.
+ */
+function searchCycle(adjacency, rules) {
+    const rng = seededRng(`raceCircuit:${rules.seed}`);
+    // Only nodes with two or more ways out can sit on a cycle; peel the trees off first.
+    const degree = new Map();
+    for (const [node, links] of adjacency.links)
+        degree.set(node, links.length);
+    let peeled = true;
+    while (peeled) {
+        peeled = false;
+        for (const [node, count] of degree) {
+            if (count > 1 || count === 0)
+                continue;
+            degree.set(node, 0);
+            for (const link of adjacency.links.get(node) ?? []) {
+                const other = degree.get(link.other);
+                if (other !== undefined && other > 0)
+                    degree.set(link.other, other - 1);
+            }
+            peeled = true;
+        }
+    }
+    const cyclic = [...degree.entries()].filter(([, count]) => count >= 2).map(([node]) => node);
+    if (cyclic.length < 3)
+        return null;
+    const arterialOf = (edge) => (LEVEL_RANK[edge.level] >= LEVEL_RANK.avenue ? 1 : 0);
+    const maxSteps = Math.min(400, Math.max(24, Math.ceil((rules.lapLength / 40) * 4)));
+    const attempts = 240;
+    let best = null;
+    let bestScore = -Infinity;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const startNode = cyclic[Math.floor(rng() * cyclic.length)];
+        const nodes = [startNode];
+        const edges = [];
+        const visited = new Set([startNode]);
+        let length = 0;
+        let arterial = 0;
+        let heading = null;
+        let closed = false;
+        for (let step = 0; step < maxSteps; step += 1) {
+            const current = nodes[nodes.length - 1];
+            const links = (adjacency.links.get(current) ?? []).filter((link) => {
+                if (degree.get(link.other) === 0)
+                    return false;
+                if (edges.length > 0 && link.edge === edges[edges.length - 1])
+                    return false;
+                return true;
+            });
+            if (links.length === 0)
+                break;
+            // Close as soon as the lap is long enough and the start is one edge away.
+            if (length >= rules.lapLength * 0.7 && nodes.length >= 3) {
+                const home = links.find((link) => link.other === startNode);
+                if (home !== undefined) {
+                    const edge = adjacency.edgeById.get(home.edge);
+                    edges.push(home.edge);
+                    length += edgeLength(edge.points);
+                    arterial += arterialOf(edge) * edgeLength(edge.points);
+                    closed = true;
+                    break;
+                }
+            }
+            const fresh = links.filter((link) => !visited.has(link.other));
+            // A lap that doubles back down the street it arrived on is not raceable; drop reversals
+            // unless the walk would otherwise have nowhere to go.
+            const forward = fresh.filter((link) => {
+                if (heading === null)
+                    return true;
+                const edge = adjacency.edgeById.get(link.edge);
+                return Math.abs(angleDelta(heading, departureHeading(edge, current))) <= MAX_LAP_TURN;
+            });
+            const options = forward.length > 0 ? forward : fresh;
+            if (options.length === 0)
+                break;
+            let total = 0;
+            const weights = options.map((link) => {
+                const edge = adjacency.edgeById.get(link.edge);
+                const rank = LEVEL_RANK[edge.level] / LEVEL_RANK.boulevard;
+                let weight = 0.15 + rank * rules.arterialBias * 2.5;
+                if (heading !== null) {
+                    // Prefer carrying straight on: a lap that zig-zags every junction drives like a maze.
+                    const turn = Math.abs(angleDelta(heading, departureHeading(edge, current)));
+                    weight *= 1.25 - (turn / Math.PI) * 0.85;
+                }
+                // Once long enough, pull back toward the start so the walk can actually close.
+                if (length > rules.lapLength * 0.55) {
+                    const home = adjacency.nodeAt.get(startNode);
+                    const here = adjacency.nodeAt.get(current);
+                    const there = adjacency.nodeAt.get(link.other);
+                    const closer = Math.hypot(home.x - there.x, home.z - there.z) < Math.hypot(home.x - here.x, home.z - here.z);
+                    weight *= closer ? 2.4 : 0.5;
+                }
+                weight = Math.max(0.01, weight);
+                total += weight;
+                return weight;
+            });
+            let roll = rng() * total;
+            let chosen = options.length - 1;
+            for (let i = 0; i < weights.length; i += 1) {
+                roll -= weights[i];
+                if (roll <= 0) {
+                    chosen = i;
+                    break;
+                }
+            }
+            const link = options[chosen];
+            const edge = adjacency.edgeById.get(link.edge);
+            const span = edgeLength(edge.points);
+            nodes.push(link.other);
+            edges.push(link.edge);
+            visited.add(link.other);
+            length += span;
+            arterial += arterialOf(edge) * span;
+            heading = departureHeading(edge, link.other) + Math.PI;
+        }
+        if (!closed || length <= 0)
+            continue;
+        const arterialShare = arterial / length;
+        const lengthError = Math.abs(length - rules.lapLength) / rules.lapLength;
+        const score = arterialShare * rules.arterialBias * 1.5 - lengthError * 2 + Math.min(nodes.length, 24) * 0.01;
+        if (score <= bestScore)
+            continue;
+        const assembled = assembleCenterline(nodes, edges, adjacency);
+        if (assembled.centerline.length < 8)
+            continue;
+        if (selfClearance(assembled.centerline, assembled.widths) < 0)
+            continue;
+        bestScore = score;
+        best = { nodes, edges, length, arterial: arterialShare };
+    }
+    return best;
+}
+/** Order the generator's own `loop` edges into a traversal — the circuit-mode fast path. */
+function loopCandidate(network) {
+    const loopEdges = network.edges.filter((edge) => edge.loop && edge.a !== edge.b);
+    if (loopEdges.length < 3)
+        return null;
+    const byNode = new Map();
+    for (const edge of loopEdges) {
+        for (const node of [edge.a, edge.b]) {
+            const bucket = byNode.get(node) ?? [];
+            bucket.push(edge);
+            byNode.set(node, bucket);
+        }
+    }
+    const first = loopEdges[0];
+    const nodes = [first.a];
+    const edges = [];
+    const used = new Set();
+    let current = first.a;
+    let length = 0;
+    let arterial = 0;
+    for (let guard = 0; guard < loopEdges.length + 2; guard += 1) {
+        const next = (byNode.get(current) ?? []).find((edge) => !used.has(edge.id));
+        if (next === undefined)
+            break;
+        used.add(next.id);
+        const other = next.a === current ? next.b : next.a;
+        const span = edgeLength(next.points);
+        edges.push(next.id);
+        length += span;
+        if (LEVEL_RANK[next.level] >= LEVEL_RANK.avenue)
+            arterial += span;
+        if (other === nodes[0])
+            break;
+        nodes.push(other);
+        current = other;
+    }
+    if (edges.length !== nodes.length || edges.length < 3)
+        return null;
+    return { nodes, edges, length, arterial: length > 0 ? arterial / length : 0 };
+}
+/** Barriers on every street that leaves the lap and is not part of it. */
+function buildSeals(nodes, edges, adjacency, kind) {
+    const onRoute = new Set(edges);
+    const seals = [];
+    // The widest lap road meeting each node sets how far back a barrier must stand.
+    const lapHalfWidth = new Map();
+    for (const id of edges) {
+        const edge = adjacency.edgeById.get(id);
+        if (edge === undefined)
+            continue;
+        for (const node of [edge.a, edge.b]) {
+            lapHalfWidth.set(node, Math.max(lapHalfWidth.get(node) ?? 0, edge.width * 0.5));
+        }
+    }
+    for (const node of nodes) {
+        const at = adjacency.nodeAt.get(node);
+        if (at === undefined)
+            continue;
+        for (const link of adjacency.links.get(node) ?? []) {
+            if (onRoute.has(link.edge))
+                continue;
+            const edge = adjacency.edgeById.get(link.edge);
+            if (edge === undefined)
+                continue;
+            const heading = departureHeading(edge, node);
+            // Stand the barrier past the junction mouth so it never overlaps the racing surface.
+            const offset = (lapHalfWidth.get(node) ?? edge.width * 0.5) + edge.width * 0.5 + 4;
+            seals.push({
+                x: at.x + Math.sin(heading) * offset,
+                z: at.z + Math.cos(heading) * offset,
+                heading,
+                width: edge.width,
+                kind,
+                node,
+            });
+        }
+    }
+    return seals;
+}
+/**
+ * Red/white kerb strips hugging both road edges through each corner. Returns the polylines and
+ * stripe pitch as data; the renderer owns the mesh and the colors.
+ */
+export function circuitKerbs(route, options = {}) {
+    const width = options.width ?? 1.1;
+    const stripe = options.stripe ?? 2.2;
+    const maxRadius = options.maxRadius ?? Infinity;
+    const points = route.centerline;
+    const n = points.length;
+    const kerbs = [];
+    route.corners.forEach((corner, index) => {
+        if (corner.radius > maxRadius)
+            return;
+        const span = [];
+        let cursor = corner.entry;
+        for (let guard = 0; guard < n; guard += 1) {
+            span.push(cursor);
+            if (cursor === corner.exit)
+                break;
+            cursor = (cursor + 1) % n;
+        }
+        if (span.length < 3)
+            return;
+        for (const side of [-1, 1]) {
+            const run = [];
+            for (const at of span) {
+                const here = points[at];
+                // Mitre on the neighbour-to-neighbour tangent: a per-segment normal fans the strip open on
+                // the outside of a corner, which is exactly where a kerb must stay flush to the road edge.
+                const prev = points[(at - 1 + n) % n];
+                const next = points[(at + 1) % n];
+                const dx = next[0] - prev[0];
+                const dz = next[1] - prev[1];
+                const len = Math.hypot(dx, dz);
+                if (len < 1e-6)
+                    continue;
+                const half = (route.widths[at] ?? 8) * 0.5;
+                run.push([here[0] + (dz / len) * half * side, here[1] - (dx / len) * half * side]);
+            }
+            if (run.length >= 2)
+                kerbs.push({ points: run, width, side, stripe, corner: index });
+        }
+    });
+    return kerbs;
+}
+/**
+ * Lift a closed, sealed-off race lap out of an existing street network. Returns `null` when the
+ * network has no drivable cycle (a pure tree of dead-end streets), so callers can fall back or warn
+ * rather than render a broken race.
+ *
+ * On a `circuit`-mode network the generated loop is used directly. On a `net` (a city) the graph is
+ * searched for the cycle closest to `lapLength` that respects `arterialBias` and `minCornerRadius`.
+ */
+export function extractCircuitRoute(network, rules = {}) {
+    const resolved = {
+        ...CIRCUIT_ROUTE_DEFAULTS,
+        ...rules,
+        lapLength: Math.max(80, rules.lapLength ?? CIRCUIT_ROUTE_DEFAULTS.lapLength),
+        arterialBias: Math.max(0, Math.min(1, rules.arterialBias ?? CIRCUIT_ROUTE_DEFAULTS.arterialBias)),
+        minCornerRadius: Math.max(3, rules.minCornerRadius ?? CIRCUIT_ROUTE_DEFAULTS.minCornerRadius),
+        checkpoints: Math.max(2, Math.floor(rules.checkpoints ?? CIRCUIT_ROUTE_DEFAULTS.checkpoints)),
+        laps: Math.max(1, Math.floor(rules.laps ?? CIRCUIT_ROUTE_DEFAULTS.laps)),
+        gridSlots: Math.max(0, Math.floor(rules.gridSlots ?? CIRCUIT_ROUTE_DEFAULTS.gridSlots)),
+        sectors: Math.max(1, Math.floor(rules.sectors ?? CIRCUIT_ROUTE_DEFAULTS.sectors)),
+        sampleStep: Math.max(0.5, rules.sampleStep ?? CIRCUIT_ROUTE_DEFAULTS.sampleStep),
+        cornerCut: Math.max(0, Math.min(0.9, rules.cornerCut ?? CIRCUIT_ROUTE_DEFAULTS.cornerCut)),
+    };
+    const adjacency = buildAdjacency(network);
+    const candidate = network.mode === "circuit"
+        ? loopCandidate(network) ?? searchCycle(adjacency, resolved)
+        : searchCycle(adjacency, resolved) ?? loopCandidate(network);
+    if (candidate === null)
+        return null;
+    const assembled = assembleCenterline(candidate.nodes, candidate.edges, adjacency);
+    if (assembled.centerline.length < 4)
+        return null;
+    // Resample to a racing-surface resolution, then round the junction kinks the city streets carry
+    // into a line a car can actually take — still the same asphalt, just driven properly.
+    const dense = resampleClosed(assembled.centerline, assembled.widths, assembled.heights, resolved.sampleStep);
+    const centerline = roundCorners(dense.points, dense.widths, resolved.minCornerRadius, resolved.cornerCut);
+    const widths = dense.widths;
+    const heights = dense.heights;
+    if (centerline.length < 8)
+        return null;
+    const { at, total } = arcLengths(centerline);
+    const radii = curvatureProfile(centerline, Math.max(6, resolved.minCornerRadius));
+    let tightestRadius = Infinity;
+    for (const radius of radii)
+        if (radius < tightestRadius)
+            tightestRadius = radius;
+    const cornerThreshold = Math.max(resolved.minCornerRadius * 4, 40);
+    const spacing = total / centerline.length;
+    const corners = analyzeCorners(centerline, radii, cornerThreshold, Math.max(8, resolved.minCornerRadius), spacing);
+    const straightRadius = Math.max(cornerThreshold * 3, 200);
+    const startIndex = findStartIndex(radii, at, total, straightRadius);
+    const startPoint = centerline[startIndex];
+    const startHeading = headingAt(centerline, startIndex);
+    const startWidth = widths[startIndex] ?? 10;
+    const across = startHeading + Math.PI / 2;
+    const start = {
+        x: startPoint[0],
+        z: startPoint[1],
+        heading: startHeading,
+        line: [
+            [startPoint[0] + Math.sin(across) * startWidth * 0.5, startPoint[1] + Math.cos(across) * startWidth * 0.5],
+            [startPoint[0] - Math.sin(across) * startWidth * 0.5, startPoint[1] - Math.cos(across) * startWidth * 0.5],
+        ],
+        distance: at[startIndex],
+        width: startWidth,
+    };
+    const grid = [];
+    for (let slot = 0; slot < resolved.gridSlots; slot += 1) {
+        const row = Math.floor(slot / 2);
+        const column = slot % 2 === 0 ? -1 : 1;
+        const back = 8 + row * 9;
+        const index = indexAtDistance(at, total, at[startIndex] - back);
+        const point = centerline[index];
+        const heading = headingAt(centerline, index);
+        const lateral = heading + Math.PI / 2;
+        const offset = (widths[index] ?? startWidth) * 0.22 * column;
+        grid.push({
+            x: point[0] + Math.sin(lateral) * offset,
+            z: point[1] + Math.cos(lateral) * offset,
+            heading,
+        });
+    }
+    // Gates are evenly spaced around the lap with the finish line LAST, so `raceTrack` treats the
+    // start/finish crossing as the lap boundary.
+    const checkpoints = [];
+    const gateSpacing = total / resolved.checkpoints;
+    for (let gate = 1; gate <= resolved.checkpoints; gate += 1) {
+        const index = indexAtDistance(at, total, at[startIndex] + gateSpacing * gate);
+        const point = centerline[index];
+        const height = heights?.[index] ?? 0;
+        const halfWidth = (widths[index] ?? startWidth) * 0.5 + 1.5;
+        checkpoints.push({
+            id: gate === resolved.checkpoints ? "finish" : `cp${gate}`,
+            center: [point[0], height + resolved.gateHeight * 0.5, point[1]],
+            half: [halfWidth, resolved.gateHeight * 0.5, 2.5],
+        });
+    }
+    const sectors = [];
+    for (let sector = 0; sector < resolved.sectors; sector += 1)
+        sectors.push(sector / resolved.sectors);
+    return {
+        centerline,
+        widths,
+        ...(heights === null ? {} : { heights }),
+        length: total,
+        edges: candidate.edges,
+        nodes: candidate.nodes,
+        seals: buildSeals(candidate.nodes, candidate.edges, adjacency, resolved.sealKind),
+        corners,
+        checkpoints,
+        laps: resolved.laps,
+        start,
+        grid,
+        sectors,
+        arterialShare: candidate.arterial,
+        tightestRadius,
+    };
+}