@jgengine/core 0.10.0 → 0.12.0

package/dist/world/cityBlocks.js

@@ -0,0 +1,670 @@
+/**
+ * Block-first city fabric for the `city` studio: turns the synthesized street network into a
+ * planar graph, extracts its faces as CLOSED BLOCK POLYGONS (a curved street yields a curved
+ * block edge, a diagonal one a diagonal edge), insets each block by its bordering roads'
+ * half-widths into curb and land rings (the sidewalk band lives between them), classifies every
+ * block (buildable, park, plaza, field, buffer sliver), subdivides buildable block frontage into
+ * POLYGONAL PARCELS with street references and corner status, and computes per-parcel BUILDABLE
+ * polygons after setbacks. Buildings then derive from parcel geometry instead of nearest-road
+ * guesses. Pure seeded math over `cityGeometry` primitives — no rendering, bounded work.
+ *
+ * @capability city-district road-derived block polygons, parcel subdivision, buildable footprints
+ */
+import { clipHalfPlane, dedupeRing, distanceToRing, ensureCcw, extractSimpleLoop, insetRing, pointInPolygon, polygonArea, polygonMeanWidth, polygonSignedArea, } from "./cityGeometry.js";
+const MAX_BLOCKS = 420;
+const WELD_RADIUS = 1.4;
+const RIM_SNAP = 6;
+/** Sidewalk band width by street hierarchy (base = the district's street-level width). */
+export function sidewalkWidthFor(level, base) {
+    switch (level) {
+        case "boulevard":
+            return base * 1.6;
+        case "avenue":
+            return base * 1.25;
+        case "street":
+            return base;
+        case "lane":
+            return base * 0.75;
+    }
+}
+function segIntersect(a, b, c, d) {
+    const rx = b[0] - a[0];
+    const rz = b[1] - a[1];
+    const sx = d[0] - c[0];
+    const sz = d[1] - c[1];
+    const denom = rx * sz - rz * sx;
+    if (Math.abs(denom) < 1e-12)
+        return null;
+    const t = ((c[0] - a[0]) * sz - (c[1] - a[1]) * sx) / denom;
+    const u = ((c[0] - a[0]) * rz - (c[1] - a[1]) * rx) / denom;
+    if (t < -1e-9 || t > 1 + 1e-9 || u < -1e-9 || u > 1 + 1e-9)
+        return null;
+    return { t: Math.max(0, Math.min(1, t)), u: Math.max(0, Math.min(1, u)), x: a[0] + rx * t, z: a[1] + rz * t };
+}
+/**
+ * Build the planar road graph: split every street polyline at its crossings with other streets,
+ * weld endpoints into shared nodes, extend near-rim ends onto the district boundary, close the
+ * boundary as edges, and prune dangling chains (dead ends can't border a closed face). Returns
+ * the half-edge structure plus the pruned dead-end chains (cul-de-sacs) for corridor carving.
+ */
+function buildGraph(streets, hx, hz) {
+    // --- 1. collect crossings per street segment (spatial hash to bound pair tests) ---
+    const cell = 14;
+    const buckets = new Map();
+    const segsOf = [];
+    for (let s = 0; s < streets.length; s += 1) {
+        const pts = streets[s].points;
+        const segs = [];
+        for (let i = 0; i + 1 < pts.length; i += 1) {
+            const a = [pts[i][0], pts[i][1]];
+            const b = [pts[i + 1][0], pts[i + 1][1]];
+            segs.push({ a, b });
+            const minX = Math.min(a[0], b[0]);
+            const maxX = Math.max(a[0], b[0]);
+            const minZ = Math.min(a[1], b[1]);
+            const maxZ = Math.max(a[1], b[1]);
+            for (let cx = Math.floor(minX / cell); cx <= Math.floor(maxX / cell); cx += 1) {
+                for (let cz = Math.floor(minZ / cell); cz <= Math.floor(maxZ / cell); cz += 1) {
+                    const key = `${cx}:${cz}`;
+                    const bucket = buckets.get(key);
+                    const entry = { street: s, seg: i, a, b };
+                    if (bucket === undefined)
+                        buckets.set(key, [entry]);
+                    else
+                        bucket.push(entry);
+                }
+            }
+        }
+        segsOf.push(segs);
+    }
+    const splits = streets.map(() => []);
+    const seen = new Set();
+    for (const bucket of buckets.values()) {
+        for (let i = 0; i < bucket.length; i += 1) {
+            for (let j = i + 1; j < bucket.length; j += 1) {
+                const p = bucket[i];
+                const q = bucket[j];
+                if (p.street === q.street)
+                    continue;
+                const pairKey = `${p.street}:${p.seg}:${q.street}:${q.seg}`;
+                if (seen.has(pairKey))
+                    continue;
+                seen.add(pairKey);
+                const hit = segIntersect(p.a, p.b, q.a, q.b);
+                if (hit === null)
+                    continue;
+                splits[p.street].push({ seg: p.seg, t: hit.t, x: hit.x, z: hit.z });
+                splits[q.street].push({ seg: q.seg, t: hit.u, x: hit.x, z: hit.z });
+            }
+        }
+    }
+    // --- 2. weld nodes ---
+    const nodes = [];
+    const nodeGrid = new Map();
+    const nodeAt = (x, z) => {
+        const gx = Math.floor(x / 4);
+        const gz = Math.floor(z / 4);
+        for (let i = gx - 1; i <= gx + 1; i += 1) {
+            for (let j = gz - 1; j <= gz + 1; j += 1) {
+                const bucket = nodeGrid.get(`${i}:${j}`);
+                if (bucket === undefined)
+                    continue;
+                for (const id of bucket) {
+                    const node = nodes[id];
+                    if (Math.hypot(node.x - x, node.z - z) <= WELD_RADIUS)
+                        return id;
+                }
+            }
+        }
+        const id = nodes.length;
+        nodes.push({ x, z, out: [] });
+        const key = `${gx}:${gz}`;
+        const bucket = nodeGrid.get(key);
+        if (bucket === undefined)
+            nodeGrid.set(key, [id]);
+        else
+            bucket.push(id);
+        return id;
+    };
+    const chains = [];
+    for (let s = 0; s < streets.length; s += 1) {
+        const pts = streets[s].points;
+        if (pts.length < 2)
+            continue;
+        const cuts = splits[s];
+        cuts.sort((a, b) => (a.seg === b.seg ? a.t - b.t : a.seg - b.seg));
+        let current = [[pts[0][0], pts[0][1]]];
+        let cutIdx = 0;
+        for (let i = 0; i + 1 < pts.length; i += 1) {
+            while (cutIdx < cuts.length && cuts[cutIdx].seg === i) {
+                const cut = cuts[cutIdx];
+                cutIdx += 1;
+                const point = [cut.x, cut.z];
+                const last = current[current.length - 1];
+                if (Math.hypot(last[0] - point[0], last[1] - point[1]) > 0.05)
+                    current.push(point);
+                if (current.length >= 2)
+                    chains.push({ pts: current, street: s });
+                current = [point];
+            }
+            const next = [pts[i + 1][0], pts[i + 1][1]];
+            const last = current[current.length - 1];
+            if (Math.hypot(last[0] - next[0], last[1] - next[1]) > 0.05)
+                current.push(next);
+        }
+        if (current.length >= 2)
+            chains.push({ pts: current, street: s });
+    }
+    // --- 4. snap near-rim chain ends onto the boundary rectangle ---
+    const snapRim = (p) => {
+        const dxs = [Math.abs(p[0] + hx), Math.abs(p[0] - hx), Math.abs(p[1] + hz), Math.abs(p[1] - hz)];
+        const nearest = Math.min(...dxs);
+        if (nearest > RIM_SNAP)
+            return null;
+        if (nearest === dxs[0])
+            return [-hx, Math.max(-hz, Math.min(hz, p[1]))];
+        if (nearest === dxs[1])
+            return [hx, Math.max(-hz, Math.min(hz, p[1]))];
+        if (nearest === dxs[2])
+            return [Math.max(-hx, Math.min(hx, p[0])), -hz];
+        return [Math.max(-hx, Math.min(hx, p[0])), hz];
+    };
+    const edges = [];
+    const rimNodeIds = new Set();
+    for (const chain of chains) {
+        const first = chain.pts[0];
+        const last = chain.pts[chain.pts.length - 1];
+        let start = first;
+        let end = last;
+        const rimStart = snapRim(first);
+        const rimEnd = snapRim(last);
+        const pts = chain.pts.map((p) => p);
+        if (rimStart !== null) {
+            start = rimStart;
+            pts[0] = rimStart;
+        }
+        if (rimEnd !== null) {
+            end = rimEnd;
+            pts[pts.length - 1] = rimEnd;
+        }
+        const from = nodeAt(start[0], start[1]);
+        const to = nodeAt(end[0], end[1]);
+        if (from === to && chain.pts.length < 4)
+            continue;
+        pts[0] = [nodes[from].x, nodes[from].z];
+        pts[pts.length - 1] = [nodes[to].x, nodes[to].z];
+        if (rimStart !== null)
+            rimNodeIds.add(from);
+        if (rimEnd !== null)
+            rimNodeIds.add(to);
+        edges.push({ from, to, pts: dedupePolyline(pts), street: chain.street, width: streets[chain.street].width });
+    }
+    // --- 5. boundary edges: corners + rim nodes, walked around the perimeter ---
+    const corners = [nodeAt(-hx, -hz), nodeAt(hx, -hz), nodeAt(hx, hz), nodeAt(-hx, hz)];
+    rimNodeIds.add(corners[0]);
+    rimNodeIds.add(corners[1]);
+    rimNodeIds.add(corners[2]);
+    rimNodeIds.add(corners[3]);
+    const perimParam = (id) => {
+        const node = nodes[id];
+        const x = node.x;
+        const z = node.z;
+        // Walk: bottom (z=-hz, x -hx→hx), right (x=hx, z -hz→hz), top (z=hz, x hx→-hx), left.
+        if (Math.abs(z + hz) <= RIM_SNAP + 0.01 && Math.abs(x) <= hx + 0.01)
+            return x + hx;
+        if (Math.abs(x - hx) <= RIM_SNAP + 0.01)
+            return 2 * hx + (z + hz);
+        if (Math.abs(z - hz) <= RIM_SNAP + 0.01)
+            return 2 * hx + 2 * hz + (hx - x);
+        return 4 * hx + 2 * hz + (hz - z);
+    };
+    const rimSorted = [...rimNodeIds].sort((a, b) => perimParam(a) - perimParam(b));
+    for (let i = 0; i < rimSorted.length; i += 1) {
+        const from = rimSorted[i];
+        const to = rimSorted[(i + 1) % rimSorted.length];
+        if (from === to)
+            continue;
+        const a = [nodes[from].x, nodes[from].z];
+        const b = [nodes[to].x, nodes[to].z];
+        // Insert the corner(s) the arc passes so boundary edges stay on the rectangle.
+        const pts = [a];
+        const pa = perimParam(from);
+        let pb = perimParam(to);
+        if (pb <= pa)
+            pb += 4 * hx + 4 * hz;
+        const cornerParams = [
+            { p: 2 * hx, at: [hx, -hz] },
+            { p: 2 * hx + 2 * hz, at: [hx, hz] },
+            { p: 4 * hx + 2 * hz, at: [-hx, hz] },
+            { p: 4 * hx + 4 * hz, at: [-hx, -hz] },
+            { p: 6 * hx + 4 * hz, at: [hx, -hz] },
+        ];
+        for (const corner of cornerParams) {
+            if (corner.p > pa + 0.01 && corner.p < pb - 0.01)
+                pts.push(corner.at);
+        }
+        pts.push(b);
+        edges.push({ from, to, pts: dedupePolyline(pts), street: -1, width: 0 });
+    }
+    // --- 6. prune dangling chains (dead ends) so every remaining edge borders two faces ---
+    const degree = new Map();
+    for (const edge of edges) {
+        degree.set(edge.from, (degree.get(edge.from) ?? 0) + 1);
+        degree.set(edge.to, (degree.get(edge.to) ?? 0) + 1);
+    }
+    const alive = edges.map(() => true);
+    let pruned = true;
+    const deadEnds = [];
+    while (pruned) {
+        pruned = false;
+        for (let i = 0; i < edges.length; i += 1) {
+            if (!alive[i])
+                continue;
+            const edge = edges[i];
+            if ((degree.get(edge.from) ?? 0) === 1 || (degree.get(edge.to) ?? 0) === 1) {
+                alive[i] = false;
+                if (edge.street >= 0)
+                    deadEnds.push({ pts: edge.pts, width: edge.width });
+                degree.set(edge.from, (degree.get(edge.from) ?? 1) - 1);
+                degree.set(edge.to, (degree.get(edge.to) ?? 1) - 1);
+                pruned = true;
+            }
+        }
+    }
+    // --- 7. half-edge structure with angular ordering ---
+    const halves = [];
+    for (let i = 0; i < edges.length; i += 1) {
+        if (!alive[i])
+            continue;
+        const edge = edges[i];
+        if (edge.pts.length < 2)
+            continue;
+        const fwdAngle = Math.atan2(edge.pts[1][1] - edge.pts[0][1], edge.pts[1][0] - edge.pts[0][0]);
+        const n = edge.pts.length;
+        const revAngle = Math.atan2(edge.pts[n - 2][1] - edge.pts[n - 1][1], edge.pts[n - 2][0] - edge.pts[n - 1][0]);
+        const a = halves.length;
+        const b = a + 1;
+        halves.push({ from: edge.from, to: edge.to, pts: edge.pts, street: edge.street, twin: b, angle: fwdAngle, visited: false });
+        halves.push({ from: edge.to, to: edge.from, pts: [...edge.pts].reverse(), street: edge.street, twin: a, angle: revAngle, visited: false });
+        nodes[edge.from].out.push(a);
+        nodes[edge.to].out.push(b);
+    }
+    for (const node of nodes)
+        node.out.sort((a, b) => halves[a].angle - halves[b].angle);
+    return { nodes, halves, deadEnds };
+}
+function dedupePolyline(pts) {
+    const out = [];
+    for (const p of pts) {
+        const prev = out[out.length - 1];
+        if (prev !== undefined && Math.hypot(prev[0] - p[0], prev[1] - p[1]) < 0.05)
+            continue;
+        out.push(p);
+    }
+    return out;
+}
+/** Trace interior (CCW) faces of the half-edge graph. */
+function extractFaces(nodes, halves) {
+    const faces = [];
+    for (let start = 0; start < halves.length; start += 1) {
+        if (halves[start].visited)
+            continue;
+        const polygon = [];
+        const streets = [];
+        let current = start;
+        let guard = 0;
+        while (guard < halves.length + 4) {
+            guard += 1;
+            const half = halves[current];
+            if (half.visited)
+                break;
+            half.visited = true;
+            for (let i = 0; i + 1 < half.pts.length; i += 1) {
+                polygon.push(half.pts[i]);
+                streets.push(half.street);
+            }
+            // Next: at the destination node, rotate clockwise from the twin.
+            const node = nodes[half.to];
+            const idx = node.out.indexOf(half.twin);
+            if (idx < 0)
+                break;
+            current = node.out[(idx - 1 + node.out.length) % node.out.length];
+            if (current === start) {
+                if (polygon.length >= 3 && polygonSignedArea(polygon) > 1)
+                    faces.push({ polygon, streets });
+                break;
+            }
+        }
+    }
+    return faces;
+}
+/**
+ * Extract closed blocks from the street network: planar faces of the graph, each inset to its
+ * curb ring (pavement edge) and land ring (behind the sidewalk band). Faces that collapse under
+ * the inset come back with an empty `land` and are the caller's slivers/buffers.
+ */
+export function extractBlocks(streets, hx, hz, params) {
+    const { nodes, halves, deadEnds } = buildGraph(streets, hx, hz);
+    const faces = extractFaces(nodes, halves);
+    faces.sort((a, b) => polygonArea(b.polygon) - polygonArea(a.polygon));
+    const blocks = [];
+    for (const face of faces) {
+        if (blocks.length >= MAX_BLOCKS)
+            break;
+        const ring = dedupeRing(face.polygon, 0.02);
+        if (ring.length < 3)
+            continue;
+        // dedupeRing may drop vertices; rebuild the street map by nearest original vertex.
+        const streetsPerEdge = [];
+        for (let i = 0; i < ring.length; i += 1) {
+            const v = ring[i];
+            let best = 0;
+            let bestDist = Infinity;
+            for (let j = 0; j < face.polygon.length; j += 1) {
+                const o = face.polygon[j];
+                const d = Math.hypot(o[0] - v[0], o[1] - v[1]);
+                if (d < bestDist) {
+                    bestDist = d;
+                    best = j;
+                }
+            }
+            streetsPerEdge.push(face.streets[best] ?? -1);
+        }
+        const ccw = ensureCcw(ring);
+        const flipped = ccw[0] !== ring[0] || ccw[1] !== ring[1];
+        const edgeStreets = flipped ? remapReversedEdgeStreets(streetsPerEdge) : streetsPerEdge;
+        const curbDist = ccw.map((_, i) => {
+            const s = edgeStreets[i] ?? -1;
+            return s >= 0 ? streets[s].width / 2 + params.curbMargin : 0.8;
+        });
+        const landDist = ccw.map((_, i) => {
+            const s = edgeStreets[i] ?? -1;
+            if (s < 0)
+                return 0.8;
+            const street = streets[s];
+            const walk = street.sidewalk ? sidewalkWidthFor(street.level, params.sidewalkBase) : 0;
+            return street.width / 2 + params.curbMargin + walk;
+        });
+        const curb = insetRing(ccw, curbDist);
+        const land = curb.length >= 3 ? insetRing(ccw, landDist) : [];
+        blocks.push({ face: ccw, faceStreets: edgeStreets, curb, land });
+    }
+    return { blocks, deadEnds };
+}
+/** Reverse per-edge street labels when a ring got rewound to CCW. */
+function remapReversedEdgeStreets(streetsPerEdge) {
+    const n = streetsPerEdge.length;
+    const out = new Array(n).fill(-1);
+    // Edge i of the reversed ring (v'_i = v_{n-1-i}) runs v_{n-1-i} → v_{n-2-i}: original edge n-2-i.
+    for (let i = 0; i < n; i += 1)
+        out[i] = streetsPerEdge[(2 * n - 2 - i) % n];
+    return out;
+}
+/** Arc-length station lookup along a closed ring. */
+export class RingWalker {
+    ring;
+    cum;
+    total;
+    constructor(ring) {
+        this.ring = ring;
+        this.cum = [0];
+        let sum = 0;
+        for (let i = 0; i < ring.length; i += 1) {
+            const a = ring[i];
+            const b = ring[(i + 1) % ring.length];
+            sum += Math.hypot(b[0] - a[0], b[1] - a[1]);
+            this.cum.push(sum);
+        }
+        this.total = sum;
+    }
+    /** Point, unit tangent, and inward normal (CCW ring: interior on the left) at arc length `s`. */
+    at(s) {
+        const wrapped = ((s % this.total) + this.total) % this.total;
+        let lo = 0;
+        let hi = this.ring.length;
+        while (lo + 1 < hi) {
+            const mid = (lo + hi) >> 1;
+            if (this.cum[mid] <= wrapped)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        const a = this.ring[lo % this.ring.length];
+        const b = this.ring[(lo + 1) % this.ring.length];
+        const len = this.cum[lo + 1] - this.cum[lo] || 1;
+        const t = (wrapped - this.cum[lo]) / len;
+        const tx = (b[0] - a[0]) / len;
+        const tz = (b[1] - a[1]) / len;
+        return {
+            p: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
+            tangent: [tx, tz],
+            normal: [-tz, tx],
+            edge: lo % this.ring.length,
+        };
+    }
+    /** Ring vertex indices whose arc position lies strictly inside (s0, s1) (wrapping). */
+    verticesBetween(s0, s1) {
+        const out = [];
+        const span = s1 - s0;
+        for (let i = 0; i < this.ring.length; i += 1) {
+            let d = this.cum[i] - s0;
+            d = ((d % this.total) + this.total) % this.total;
+            if (d > 0.01 && d < span - 0.01)
+                out.push(i);
+        }
+        out.sort((a, b) => {
+            const da = (((this.cum[a] - s0) % this.total) + this.total) % this.total;
+            const db = (((this.cum[b] - s0) % this.total) + this.total) % this.total;
+            return da - db;
+        });
+        return out;
+    }
+    /** Interior angle (radians) at ring vertex i — π on straight runs, < π at convex corners. */
+    interiorAngle(i) {
+        const prev = this.ring[(i + this.ring.length - 1) % this.ring.length];
+        const cur = this.ring[i];
+        const next = this.ring[(i + 1) % this.ring.length];
+        const a = Math.atan2(prev[1] - cur[1], prev[0] - cur[0]);
+        const b = Math.atan2(next[1] - cur[1], next[0] - cur[0]);
+        let diff = a - b;
+        while (diff < 0)
+            diff += Math.PI * 2;
+        while (diff >= Math.PI * 2)
+            diff -= Math.PI * 2;
+        return diff;
+    }
+}
+/**
+ * Cut one polygonal parcel out of a block land ring: the frontage arc between two stations,
+ * extruded inward along the station normals, clipped back to the block. Returns null when the
+ * strip collapses (over-tight corner, sliver arc).
+ */
+export function cutParcel(walker, blockRing, cut) {
+    const a = walker.at(cut.s0);
+    const b = walker.at(cut.s1);
+    const outer = [a.p];
+    const inner = [[a.p[0] + a.normal[0] * cut.depth, a.p[1] + a.normal[1] * cut.depth]];
+    for (const vi of walker.verticesBetween(cut.s0, cut.s1)) {
+        const v = walker.ring[vi];
+        outer.push(v);
+        // Vertex normal: bisector of adjacent edge normals.
+        const prev = walker.ring[(vi + walker.ring.length - 1) % walker.ring.length];
+        const next = walker.ring[(vi + 1) % walker.ring.length];
+        const l0 = Math.hypot(v[0] - prev[0], v[1] - prev[1]) || 1;
+        const l1 = Math.hypot(next[0] - v[0], next[1] - v[1]) || 1;
+        const n0 = [-(v[1] - prev[1]) / l0, (v[0] - prev[0]) / l0];
+        const n1 = [-(next[1] - v[1]) / l1, (next[0] - v[0]) / l1];
+        let nx = n0[0] + n1[0];
+        let nz = n0[1] + n1[1];
+        const nl = Math.hypot(nx, nz) || 1;
+        nx /= nl;
+        nz /= nl;
+        inner.push([v[0] + nx * cut.depth, v[1] + nz * cut.depth]);
+    }
+    outer.push(b.p);
+    inner.push([b.p[0] + b.normal[0] * cut.depth, b.p[1] + b.normal[1] * cut.depth]);
+    inner.reverse();
+    const raw = extractSimpleLoop([...outer, ...inner]);
+    if (raw.length < 3)
+        return null;
+    // Conform to the block: deep cuts on thin or concave blocks can push vertices — or whole edge
+    // spans between two near-boundary vertices — across a notch to the outside.
+    const clipped = conformPolygonToRing(raw, blockRing);
+    if (clipped.length < 3 || polygonArea(clipped) < 4)
+        return null;
+    return clipped;
+}
+/**
+ * Conform a polygon to a containing ring: sample every edge (a straight edge can bulge across a
+ * concave notch even when its endpoints hug the boundary), then pull each escaping point to its
+ * nearest boundary point. Callers re-run this after any operation that adds mid-edge vertices.
+ */
+export function conformPolygonToRing(poly, ring) {
+    const refined = [];
+    for (let i = 0; i < poly.length; i += 1) {
+        const a = poly[i];
+        const b = poly[(i + 1) % poly.length];
+        refined.push(a);
+        const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        const steps = Math.min(24, Math.floor(len / 2.5));
+        for (let s = 1; s <= steps; s += 1) {
+            const t = s / (steps + 1);
+            const x = a[0] + (b[0] - a[0]) * t;
+            const z = a[1] + (b[1] - a[1]) * t;
+            if (!pointInPolygon(ring, x, z) && distanceToRing(ring, x, z) > 0.3)
+                refined.push([x, z]);
+        }
+    }
+    const out = [];
+    for (const [x, z] of refined) {
+        if (pointInPolygon(ring, x, z) || distanceToRing(ring, x, z) <= 0.4) {
+            out.push([x, z]);
+            continue;
+        }
+        // Pull the vertex to the nearest point on the ring boundary.
+        let bestX = x;
+        let bestZ = z;
+        let best = Infinity;
+        for (let i = 0; i < ring.length; i += 1) {
+            const a = ring[i];
+            const b = ring[(i + 1) % ring.length];
+            const vx = b[0] - a[0];
+            const vz = b[1] - a[1];
+            const len2 = vx * vx + vz * vz;
+            const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * vx + (z - a[1]) * vz) / len2));
+            const px = a[0] + vx * t;
+            const pz = a[1] + vz * t;
+            const d = Math.hypot(x - px, z - pz);
+            if (d < best) {
+                best = d;
+                bestX = px;
+                bestZ = pz;
+            }
+        }
+        out.push([bestX, bestZ]);
+    }
+    return extractSimpleLoop(out);
+}
+/**
+ * Buildable polygon for a parcel: the parcel clipped by the front setback (a half-plane pushed in
+ * from the frontage chord), side gaps along both cut lines, and a rear margin. Works on any
+ * parcel polygon — no vertex correspondence needed.
+ */
+export function buildablePolygon(parcel, frontA, frontB, frontSetback, sideGap, rearMargin, depth) {
+    const tx = frontB[0] - frontA[0];
+    const tz = frontB[1] - frontA[1];
+    const len = Math.hypot(tx, tz) || 1;
+    const t = [tx / len, tz / len];
+    const n = [-t[1], t[0]]; // inward (CCW ring, interior left of frontage direction)
+    let poly = [...parcel];
+    // Front: keep the side of the chord's inward offset. dot(p, n) >= dot(A, n) + setback.
+    const dFront = frontA[0] * n[0] + frontA[1] * n[1];
+    poly = clipHalfPlane(poly, [-n[0], -n[1]], -(dFront + frontSetback));
+    if (poly.length < 3)
+        return [];
+    // Rear: dot(p, n) <= dFront + depth - rearMargin.
+    poly = clipHalfPlane(poly, n, dFront + Math.max(frontSetback + 1, depth - rearMargin));
+    if (poly.length < 3)
+        return [];
+    // Sides: keep between the two station cut lines pushed in by sideGap.
+    const dA = frontA[0] * t[0] + frontA[1] * t[1];
+    const dB = frontB[0] * t[0] + frontB[1] * t[1];
+    poly = clipHalfPlane(poly, [-t[0], -t[1]], -(dA + sideGap));
+    if (poly.length < 3)
+        return [];
+    poly = clipHalfPlane(poly, t, dB - sideGap);
+    return poly.length >= 3 ? poly : [];
+}
+/**
+ * Carve dead-end road corridors (cul-de-sac lanes pruned from the face graph) out of a polygon:
+ * for every corridor segment crossing it, keep the polygon piece on the side where `keep` lies.
+ */
+export function carveCorridors(poly, keep, corridors, margin) {
+    let current = poly;
+    for (const corridor of corridors) {
+        const half = corridor.width / 2 + margin;
+        for (let i = 0; i + 1 < corridor.pts.length && current.length >= 3; i += 1) {
+            const a = corridor.pts[i];
+            const b = corridor.pts[i + 1];
+            const tx = b[0] - a[0];
+            const tz = b[1] - a[1];
+            const len = Math.hypot(tx, tz);
+            if (len < 0.5)
+                continue;
+            const n = [-tz / len, tx / len];
+            const dKeep = keep[0] * n[0] + keep[1] * n[1];
+            const dLine = a[0] * n[0] + a[1] * n[1];
+            // Quick reject: does the segment's corridor even touch the polygon bbox region?
+            let near = false;
+            for (const [x, z] of current) {
+                const along = ((x - a[0]) * tx + (z - a[1]) * tz) / len;
+                if (along < -half || along > len + half)
+                    continue;
+                if (Math.abs(x * n[0] + z * n[1] - dLine) <= half + 0.5) {
+                    near = true;
+                    break;
+                }
+            }
+            if (!near)
+                continue;
+            if (dKeep >= dLine)
+                current = clipHalfPlane(current, [-n[0], -n[1]], -(dLine + half));
+            else
+                current = clipHalfPlane(current, n, dLine - half);
+        }
+    }
+    return current.length >= 3 ? current : [];
+}
+/** Deterministic sliver verdict shared by classification and tests. */
+export function isSliverBlock(land, minArea, minWidth) {
+    if (land.length < 3)
+        return true;
+    return polygonArea(land) < minArea || polygonMeanWidth(land) < minWidth;
+}
+/** Sample deterministic points inside a polygon by seeded rejection over its bounds. */
+export function pointsInPolygon(ring, count, rng, margin = 1.5) {
+    if (ring.length < 3 || count <= 0)
+        return [];
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const [x, z] of ring) {
+        minX = Math.min(minX, x);
+        minZ = Math.min(minZ, z);
+        maxX = Math.max(maxX, x);
+        maxZ = Math.max(maxZ, z);
+    }
+    const out = [];
+    const maxTries = count * 12;
+    for (let i = 0; i < maxTries && out.length < count; i += 1) {
+        const x = minX + rng() * (maxX - minX);
+        const z = minZ + rng() * (maxZ - minZ);
+        if (!pointInPolygon(ring, x, z))
+            continue;
+        if (margin > 0 && distanceToRing(ring, x, z) < margin)
+            continue;
+        out.push([x, z]);
+    }
+    return out;
+}