@world-engines/spatial-authoring 0.1.0-alpha.0

package/dist/road-parcels.js

@@ -0,0 +1,1584 @@
+const EPSILON = 0.000001;
+/**
+ * Point2D 会量化到 EPSILON 网格；两条量化后的平移线交点相对原法向可能
+ * 向道路回退数个微米。v10 在退界时额外向地块内侧收 4ε：两个端点各最多
+ * 0.5ε/轴的舍入，叠加法向与 miter 的投影误差后仍有余量。验收侧的道路
+ * clearance 门不放宽，frontage 线同步移动，避免把量化误差伪装成临街。
+ */
+const V10_INSET_QUANTIZATION_GUARD = 4 * EPSILON;
+/**
+ * 递归裁切的两侧都会经过坐标量化；若共享同一 cut，独立量化可把 sibling
+ * 推到对方一侧并制造极小正面积交叠。仅 v10 在 cut 两侧各退 4ε，留下
+ * 对称 8ε 缝隙；这比放宽全局 overlap 判定更局部，且不改变真实道路 frontage。
+ */
+const V10_SPLIT_QUANTIZATION_GAP = 4 * EPSILON;
+const DEFAULT_MAX_FACE_AREA = 22_500;
+const DEFAULT_MIN_PARCEL_AREA = 36;
+const DEFAULT_MAX_SLOPE = 0.22;
+const MAX_TERRAIN_GRID_SIDE = 257;
+const MIN_SAFE_BUILDING_DIMENSION = 10;
+const DEFAULT_MAX_ASPECT_RATIO = 4;
+const DEFAULT_MIN_SHORT_SIDE_METERS = 26;
+function metric(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+function point(x, y) {
+    return Object.freeze({ x: metric(x), y: metric(y) });
+}
+function bounds(x, y, width, height) {
+    return Object.freeze({ x: metric(x), y: metric(y), width: metric(width), height: metric(height) });
+}
+function stableHash(parts) {
+    const input = parts.join("\u001f");
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x7feb352d);
+    hash ^= hash >>> 15;
+    hash = Math.imul(hash, 0x846ca68b);
+    return (hash ^ (hash >>> 16)) >>> 0;
+}
+function stableId(parts) {
+    const first = stableHash(["parcel-a", ...parts]).toString(16).padStart(8, "0");
+    const second = stableHash(["parcel-b", ...parts]).toString(16).padStart(8, "0");
+    return `parcel_${first}${second}`;
+}
+function unit(parts) {
+    return stableHash(parts) / 0x1_0000_0000;
+}
+function assertFinite(value, label) {
+    if (!Number.isFinite(value))
+        throw new TypeError(`${label} 必须是有限数`);
+}
+function coordinateKey(value) {
+    return `${metric(value.x)},${metric(value.y)}`;
+}
+function polygonArea(polygon) {
+    let twiceArea = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const current = polygon[index];
+        const next = polygon[(index + 1) % polygon.length];
+        if (current === undefined || next === undefined)
+            continue;
+        twiceArea += current.x * next.y - next.x * current.y;
+    }
+    return twiceArea / 2;
+}
+function polygonBounds(polygon) {
+    const xs = polygon.map((candidate) => candidate.x);
+    const ys = polygon.map((candidate) => candidate.y);
+    const left = Math.min(...xs);
+    const top = Math.min(...ys);
+    return bounds(left, top, Math.max(...xs) - left, Math.max(...ys) - top);
+}
+function signedCross(a, b, c) {
+    return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+function pointInPolygon(candidate, polygon) {
+    let inside = false;
+    for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index, index += 1) {
+        const a = polygon[index];
+        const b = polygon[previous];
+        if (a === undefined || b === undefined)
+            continue;
+        const onEdge = Math.abs(signedCross(b, a, candidate)) <= EPSILON
+            && candidate.x >= Math.min(a.x, b.x) - EPSILON && candidate.x <= Math.max(a.x, b.x) + EPSILON
+            && candidate.y >= Math.min(a.y, b.y) - EPSILON && candidate.y <= Math.max(a.y, b.y) + EPSILON;
+        if (onEdge)
+            return true;
+        const crosses = (a.y > candidate.y) !== (b.y > candidate.y)
+            && candidate.x < (b.x - a.x) * (candidate.y - a.y) / (b.y - a.y) + a.x;
+        if (crosses)
+            inside = !inside;
+    }
+    return inside;
+}
+function pointInBounds(candidate, candidateBounds) {
+    return candidate.x >= candidateBounds.x - EPSILON && candidate.x <= candidateBounds.x + candidateBounds.width + EPSILON
+        && candidate.y >= candidateBounds.y - EPSILON && candidate.y <= candidateBounds.y + candidateBounds.height + EPSILON;
+}
+function orientation(a, b, c) {
+    const value = signedCross(a, b, c);
+    return Math.abs(value) <= EPSILON ? 0 : value > 0 ? 1 : -1;
+}
+function pointOnSegment(candidate, a, b) {
+    return orientation(a, b, candidate) === 0
+        && candidate.x >= Math.min(a.x, b.x) - EPSILON && candidate.x <= Math.max(a.x, b.x) + EPSILON
+        && candidate.y >= Math.min(a.y, b.y) - EPSILON && candidate.y <= Math.max(a.y, b.y) + EPSILON;
+}
+function segmentsIntersect(a, b, c, d) {
+    const first = orientation(a, b, c);
+    const second = orientation(a, b, d);
+    const third = orientation(c, d, a);
+    const fourth = orientation(c, d, b);
+    if (first !== second && third !== fourth)
+        return true;
+    return (first === 0 && pointOnSegment(c, a, b)) || (second === 0 && pointOnSegment(d, a, b))
+        || (third === 0 && pointOnSegment(a, c, d)) || (fourth === 0 && pointOnSegment(b, c, d));
+}
+/** 包含边界接触；terrain cell 只要接触 parcel 就必须参与水/坡度判定。 */
+function polygonIntersectsBounds(polygon, candidateBounds) {
+    const corners = [
+        point(candidateBounds.x, candidateBounds.y),
+        point(candidateBounds.x + candidateBounds.width, candidateBounds.y),
+        point(candidateBounds.x + candidateBounds.width, candidateBounds.y + candidateBounds.height),
+        point(candidateBounds.x, candidateBounds.y + candidateBounds.height),
+    ];
+    if (corners.some((corner) => pointInPolygon(corner, polygon)) || polygon.some((candidate) => pointInBounds(candidate, candidateBounds)))
+        return true;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        for (let edge = 0; edge < corners.length; edge += 1) {
+            const a = corners[edge];
+            const b = corners[(edge + 1) % corners.length];
+            if (a !== undefined && b !== undefined && segmentsIntersect(from, to, a, b))
+                return true;
+        }
+    }
+    return false;
+}
+function distancePointToSegment(candidate, a, b) {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const denominator = dx * dx + dy * dy;
+    if (denominator <= EPSILON)
+        return Math.hypot(candidate.x - a.x, candidate.y - a.y);
+    const ratio = Math.max(0, Math.min(1, ((candidate.x - a.x) * dx + (candidate.y - a.y) * dy) / denominator));
+    return Math.hypot(candidate.x - (a.x + ratio * dx), candidate.y - (a.y + ratio * dy));
+}
+function segmentDistance(a, b, c, d) {
+    if (segmentsIntersect(a, b, c, d))
+        return 0;
+    return Math.min(distancePointToSegment(a, c, d), distancePointToSegment(b, c, d), distancePointToSegment(c, a, b), distancePointToSegment(d, a, b));
+}
+function polygonCentroid(polygon) {
+    const area = polygonArea(polygon);
+    if (Math.abs(area) <= EPSILON) {
+        const total = polygon.reduce((sum, candidate) => ({ x: sum.x + candidate.x, y: sum.y + candidate.y }), { x: 0, y: 0 });
+        return point(total.x / polygon.length, total.y / polygon.length);
+    }
+    let x = 0;
+    let y = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const current = polygon[index];
+        const next = polygon[(index + 1) % polygon.length];
+        if (current === undefined || next === undefined)
+            continue;
+        const cross = current.x * next.y - next.x * current.y;
+        x += (current.x + next.x) * cross;
+        y += (current.y + next.y) * cross;
+    }
+    return point(x / (6 * area), y / (6 * area));
+}
+/** 保守地把 block 边界向中心收缩，保留曲线/斜边拓扑同时清出道路走廊。 */
+function insetPolygon(polygon, margin) {
+    const center = polygonCentroid(polygon);
+    if (!pointInPolygon(center, polygon))
+        return undefined;
+    let nearest = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        if (a !== undefined && b !== undefined)
+            nearest = Math.min(nearest, distancePointToSegment(center, a, b));
+    }
+    if (!Number.isFinite(nearest) || nearest <= margin + EPSILON)
+        return undefined;
+    const factor = Math.max(0.05, 1 - (margin / nearest) * 1.35);
+    const result = polygon.map((candidate) => point(center.x + (candidate.x - center.x) * factor, center.y + (candidate.y - center.y) * factor));
+    return Math.abs(polygonArea(result)) > EPSILON ? Object.freeze(result) : undefined;
+}
+/** 仅 structured-v8 使用：凸的道路闭合面按每条道路边的内侧半平面退让。
+ * legacy-v6 的 centroid 缩放保持原样，凹面不尝试猜测 offset 拓扑。 */
+function insetConvexFace(face, setback) {
+    const source = canonicalRing(face.polygon);
+    const simplified = source.filter((candidate, index) => {
+        const previous = source[(index + source.length - 1) % source.length];
+        const next = source[(index + 1) % source.length];
+        if (previous === undefined || next === undefined)
+            return false;
+        const tolerance = EPSILON * Math.max(1, Math.hypot(candidate.x - previous.x, candidate.y - previous.y), Math.hypot(next.x - candidate.x, next.y - candidate.y)) ** 2;
+        return Math.abs(signedCross(previous, candidate, next)) > tolerance;
+    });
+    const polygon = canonicalRing(simplified.length >= 3 ? simplified : source);
+    const turns = [];
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        const c = polygon[(index + 2) % polygon.length];
+        if (a === undefined || b === undefined || c === undefined)
+            return undefined;
+        const turn = signedCross(a, b, c);
+        if (Math.abs(turn) <= EPSILON)
+            continue;
+        turns.push(turn);
+    }
+    if (turns.length === 0 || turns.some((turn) => turn < -EPSILON))
+        return undefined;
+    const shifted = [];
+    const frontageEdges = [];
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        if (a === undefined || b === undefined)
+            return undefined;
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const length = Math.hypot(dx, dy);
+        if (length <= EPSILON)
+            return undefined;
+        const normal = { x: -dy / length, y: dx / length };
+        const matching = [];
+        for (const sourceEdge of face.frontageEdges) {
+            const tolerance = EPSILON * Math.max(1, length, Math.hypot(sourceEdge.b.x - sourceEdge.a.x, sourceEdge.b.y - sourceEdge.a.y)) ** 2;
+            if (Math.abs(signedCross(a, b, sourceEdge.a)) <= tolerance && Math.abs(signedCross(a, b, sourceEdge.b)) <= tolerance)
+                matching.push(sourceEdge);
+        }
+        if (matching.length === 0)
+            return undefined;
+        const margin = Math.max(...matching.map((edge) => edge.widthMeters / 2 + setback));
+        const from = point(a.x + normal.x * margin, a.y + normal.y * margin);
+        const to = point(b.x + normal.x * margin, b.y + normal.y * margin);
+        shifted.push([from, to]);
+        for (const sourceEdge of matching) {
+            frontageEdges.push(Object.freeze({
+                ...sourceEdge,
+                a: point(sourceEdge.a.x + normal.x * margin, sourceEdge.a.y + normal.y * margin),
+                b: point(sourceEdge.b.x + normal.x * margin, sourceEdge.b.y + normal.y * margin),
+            }));
+        }
+    }
+    const result = [];
+    for (let index = 0; index < shifted.length; index += 1) {
+        const previous = shifted[(index + shifted.length - 1) % shifted.length];
+        const current = shifted[index];
+        if (previous === undefined || current === undefined)
+            return undefined;
+        const [a, b] = previous;
+        const [c, d] = current;
+        if (a === undefined || b === undefined || c === undefined || d === undefined)
+            return undefined;
+        const r = { x: b.x - a.x, y: b.y - a.y }, s = { x: d.x - c.x, y: d.y - c.y };
+        const denominator = r.x * s.y - r.y * s.x;
+        if (Math.abs(denominator) <= EPSILON)
+            return undefined;
+        const t = ((c.x - a.x) * s.y - (c.y - a.y) * s.x) / denominator;
+        result.push(point(a.x + r.x * t, a.y + r.y * t));
+    }
+    const inset = canonicalRing(result);
+    return Math.abs(polygonArea(inset)) > EPSILON && inset.every((candidate) => pointInPolygon(candidate, polygon))
+        ? Object.freeze({ ...face, polygon: inset, frontageEdges: Object.freeze(frontageEdges) }) : undefined;
+}
+/**
+ * DCEL 环会保留路由器的采样点。对同一直线上的相邻采样点归并，避免两条
+ * 平行的退界线没有唯一交点；后续仍按原 GraphEdge 计算最大道路宽度，不能
+ * 因为归并而降低任何道路走廊。
+ */
+function simplifyCollinearRing(polygon) {
+    const source = canonicalRing(polygon);
+    const simplified = source.filter((candidate, index) => {
+        const previous = source[(index + source.length - 1) % source.length];
+        const next = source[(index + 1) % source.length];
+        if (previous === undefined || next === undefined)
+            return false;
+        const tolerance = EPSILON * Math.max(1, Math.hypot(candidate.x - previous.x, candidate.y - previous.y), Math.hypot(next.x - candidate.x, next.y - candidate.y)) ** 2;
+        return Math.abs(signedCross(previous, candidate, next)) > tolerance;
+    });
+    return canonicalRing(simplified.length >= 3 ? simplified : source);
+}
+function collinearOverlappingEdges(a, b, edge) {
+    const length = Math.hypot(b.x - a.x, b.y - a.y);
+    const edgeLength = Math.hypot(edge.b.x - edge.a.x, edge.b.y - edge.a.y);
+    if (length <= EPSILON || edgeLength <= EPSILON)
+        return false;
+    const tolerance = EPSILON * Math.max(1, length, edgeLength) ** 2;
+    if (Math.abs(signedCross(a, b, edge.a)) > tolerance || Math.abs(signedCross(a, b, edge.b)) > tolerance)
+        return false;
+    const unitX = (b.x - a.x) / length;
+    const unitY = (b.y - a.y) / length;
+    const first = (edge.a.x - a.x) * unitX + (edge.a.y - a.y) * unitY;
+    const second = (edge.b.x - a.x) * unitX + (edge.b.y - a.y) * unitY;
+    return Math.min(Math.max(first, second), length) - Math.max(Math.min(first, second), 0) > EPSILON;
+}
+/** inset 边不能在凹口跨越外环，也不能侵入任何真实道路走廊。 */
+function insetKeepsFaceAndRoadClearance(inset, source, frontageEdges, setback) {
+    if (!polygonWithinBoundary(inset, source))
+        return false;
+    for (const edge of frontageEdges) {
+        const clearance = edge.widthMeters / 2 + setback;
+        for (let index = 0; index < inset.length; index += 1) {
+            const from = inset[index];
+            const to = inset[(index + 1) % inset.length];
+            if (from === undefined || to === undefined || segmentDistance(from, to, edge.a, edge.b) < clearance - EPSILON)
+                return false;
+        }
+    }
+    return true;
+}
+/** shape-filled-v10 的 simple 单环凹面路径：先在真实外街环上退界，
+ * 再分解已经退界的轮廓。内部 chord 不在这里出现，因而没有退界或 frontage。 */
+function insetSimpleFace(face, setback) {
+    const source = canonicalRing(face.polygon);
+    const polygon = simplifyCollinearRing(source);
+    const shifted = [];
+    const frontageEdges = [];
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        if (a === undefined || b === undefined)
+            return undefined;
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const length = Math.hypot(dx, dy);
+        if (length <= EPSILON)
+            return undefined;
+        const matching = face.frontageEdges.filter((edge) => collinearOverlappingEdges(a, b, edge));
+        if (matching.length === 0)
+            return undefined;
+        const margin = Math.max(...matching.map((edge) => edge.widthMeters / 2 + setback)) + V10_INSET_QUANTIZATION_GUARD;
+        const normal = { x: -dy / length, y: dx / length };
+        shifted.push([point(a.x + normal.x * margin, a.y + normal.y * margin), point(b.x + normal.x * margin, b.y + normal.y * margin)]);
+        for (const edge of matching)
+            frontageEdges.push(Object.freeze({
+                ...edge,
+                a: point(edge.a.x + normal.x * margin, edge.a.y + normal.y * margin),
+                b: point(edge.b.x + normal.x * margin, edge.b.y + normal.y * margin),
+            }));
+    }
+    const result = [];
+    for (let index = 0; index < shifted.length; index += 1) {
+        const previous = shifted[(index + shifted.length - 1) % shifted.length];
+        const current = shifted[index];
+        if (previous === undefined || current === undefined)
+            return undefined;
+        const [a, b] = previous;
+        const [c, d] = current;
+        if (a === undefined || b === undefined || c === undefined || d === undefined)
+            return undefined;
+        const r = { x: b.x - a.x, y: b.y - a.y }, s = { x: d.x - c.x, y: d.y - c.y };
+        const denominator = r.x * s.y - r.y * s.x;
+        if (Math.abs(denominator) <= EPSILON)
+            return undefined;
+        const t = ((c.x - a.x) * s.y - (c.y - a.y) * s.x) / denominator;
+        result.push(point(a.x + r.x * t, a.y + r.y * t));
+    }
+    const inset = canonicalRing(result);
+    if (Math.abs(polygonArea(inset)) <= EPSILON || !insetKeepsFaceAndRoadClearance(inset, source, face.frontageEdges, setback))
+        return undefined;
+    for (let index = 0; index < inset.length; index += 1)
+        for (let other = index + 1; other < inset.length; other += 1) {
+            if (other === index || other === (index + 1) % inset.length || index === (other + 1) % inset.length)
+                continue;
+            const a = inset[index];
+            const b = inset[(index + 1) % inset.length];
+            const c = inset[other];
+            const d = inset[(other + 1) % inset.length];
+            if (a !== undefined && b !== undefined && c !== undefined && d !== undefined && segmentsCrossWithArea(a, b, c, d))
+                return undefined;
+        }
+    return Object.freeze({ ...face, polygon: inset, frontageEdges: Object.freeze(frontageEdges) });
+}
+function facePiecesAfterInset(face) {
+    const turns = face.polygon.map((candidate, index) => {
+        const previous = face.polygon[(index + face.polygon.length - 1) % face.polygon.length];
+        const next = face.polygon[(index + 1) % face.polygon.length];
+        return previous === undefined || next === undefined ? 0 : signedCross(previous, candidate, next);
+    }).filter((turn) => Math.abs(turn) > EPSILON);
+    if (turns.length > 0 && turns.every((turn) => turn > 0))
+        return Object.freeze([face]);
+    const pieces = [...triangulate(face.polygon)];
+    if (pieces.length === 0)
+        return Object.freeze([]);
+    const isConvex = (polygon) => {
+        const turns = polygon.map((candidate, index) => {
+            const previous = polygon[(index + polygon.length - 1) % polygon.length];
+            const next = polygon[(index + 1) % polygon.length];
+            return previous === undefined || next === undefined ? 0 : signedCross(previous, candidate, next);
+        }).filter((turn) => Math.abs(turn) > EPSILON);
+        return turns.length > 0 && turns.every((turn) => turn > 0);
+    };
+    const merge = (first, second) => {
+        const edges = new Map();
+        for (const polygon of [first, second])
+            for (let index = 0; index < polygon.length; index += 1) {
+                const from = polygon[index];
+                const to = polygon[(index + 1) % polygon.length];
+                if (from === undefined || to === undefined)
+                    return undefined;
+                const key = `${coordinateKey(from)}>${coordinateKey(to)}`;
+                const reverse = `${coordinateKey(to)}>${coordinateKey(from)}`;
+                if (edges.has(reverse))
+                    edges.delete(reverse);
+                else
+                    edges.set(key, { from, to });
+            }
+        if (edges.size < 3)
+            return undefined;
+        const firstEdge = edges.values().next().value;
+        if (firstEdge === undefined)
+            return undefined;
+        const ring = [firstEdge.from];
+        let cursor = firstEdge.to;
+        edges.delete(`${coordinateKey(firstEdge.from)}>${coordinateKey(firstEdge.to)}`);
+        while (coordinateKey(cursor) !== coordinateKey(ring[0])) {
+            ring.push(cursor);
+            const next = [...edges.values()].find((edge) => coordinateKey(edge.from) === coordinateKey(cursor));
+            if (next === undefined)
+                return undefined;
+            edges.delete(`${coordinateKey(next.from)}>${coordinateKey(next.to)}`);
+            cursor = next.to;
+            if (ring.length > first.length + second.length)
+                return undefined;
+        }
+        const output = canonicalRing(ring);
+        const tolerance = EPSILON * Math.max(1, Math.abs(polygonArea(first)), Math.abs(polygonArea(second)));
+        return edges.size === 0 && Math.abs(Math.abs(polygonArea(output)) - Math.abs(polygonArea(first)) - Math.abs(polygonArea(second))) <= tolerance && isConvex(output)
+            ? output : undefined;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        outer: for (let first = 0; first < pieces.length; first += 1)
+            for (let second = first + 1; second < pieces.length; second += 1) {
+                const merged = merge(pieces[first], pieces[second]);
+                if (merged === undefined)
+                    continue;
+                pieces.splice(second, 1);
+                pieces.splice(first, 1, merged);
+                changed = true;
+                break outer;
+            }
+    }
+    return Object.freeze(pieces.map((polygon) => {
+        const frontageEdges = face.frontageEdges.filter((edge) => polygon.some((from, index) => {
+            const to = polygon[(index + 1) % polygon.length];
+            if (to === undefined)
+                return false;
+            const length = Math.hypot(to.x - from.x, to.y - from.y);
+            const tolerance = EPSILON * Math.max(1, length, Math.hypot(edge.b.x - edge.a.x, edge.b.y - edge.a.y)) ** 2;
+            return Math.abs(signedCross(from, to, edge.a)) <= tolerance && Math.abs(signedCross(from, to, edge.b)) <= tolerance;
+        }));
+        return Object.freeze({
+            polygon: canonicalRing(polygon),
+            boundaryIds: face.boundaryIds,
+            frontageEdges: Object.freeze(frontageEdges),
+            widestRoadMeters: frontageEdges.length ? Math.max(...frontageEdges.map((edge) => edge.widthMeters)) : face.widestRoadMeters,
+        });
+    }));
+}
+function canonicalRing(polygon) {
+    const ring = polygonArea(polygon) < 0 ? [...polygon].reverse() : [...polygon];
+    let start = 0;
+    for (let index = 1; index < ring.length; index += 1) {
+        const candidate = ring[index];
+        const current = ring[start];
+        if (candidate !== undefined && current !== undefined
+            && (candidate.x < current.x || (candidate.x === current.x && candidate.y < current.y)))
+            start = index;
+    }
+    return Object.freeze(Array.from({ length: ring.length }, (_, index) => ring[(start + index) % ring.length]));
+}
+function clipPolygon(polygon, normal, limit, keepLower) {
+    const result = [];
+    const projection = (candidate) => candidate.x * normal.x + candidate.y * normal.y;
+    const isInside = (candidate) => keepLower
+        ? projection(candidate) <= limit + EPSILON
+        : projection(candidate) >= limit - EPSILON;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        const fromInside = isInside(from);
+        const toInside = isInside(to);
+        if (fromInside)
+            result.push(from);
+        if (fromInside !== toInside) {
+            const divisor = projection(to) - projection(from);
+            if (Math.abs(divisor) > EPSILON) {
+                const ratio = (limit - projection(from)) / divisor;
+                result.push(point(from.x + (to.x - from.x) * ratio, from.y + (to.y - from.y) * ratio));
+            }
+        }
+    }
+    const unique = result.filter((candidate, index) => index === 0 || coordinateKey(candidate) !== coordinateKey(result[index - 1]));
+    return unique.length >= 3 ? Object.freeze(unique) : Object.freeze([]);
+}
+/**
+ * 取 face 边方向的稳定主轴：长边/整体路网走向优先，近似各向同性时以 canonical 首长边打破平局。
+ * 这避免 oversized block 固定沿世界 X/Y 切成棋盘。
+ */
+function faceSplitDirection(polygon) {
+    let xx = 0;
+    let xy = 0;
+    let yy = 0;
+    let longest;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const length = Math.hypot(dx, dy);
+        if (length <= EPSILON)
+            continue;
+        const ux = dx / length;
+        const uy = dy / length;
+        xx += length * ux * ux;
+        xy += length * ux * uy;
+        yy += length * uy * uy;
+        if (longest === undefined || length > longest.length + EPSILON)
+            longest = { dx: ux, dy: uy, length };
+    }
+    if (longest === undefined)
+        return point(1, 0);
+    const difference = xx - yy;
+    const magnitude = Math.hypot(difference, 2 * xy);
+    let x;
+    let y;
+    if (magnitude <= EPSILON) {
+        x = longest.dx;
+        y = longest.dy;
+    }
+    else {
+        const angle = Math.atan2(2 * xy, difference) / 2;
+        x = Math.cos(angle);
+        y = Math.sin(angle);
+    }
+    if (x < -EPSILON || (Math.abs(x) <= EPSILON && y < 0)) {
+        x = -x;
+        y = -y;
+    }
+    return point(x, y);
+}
+function shapeOptions(settings) {
+    const maxAspectRatio = settings?.maxAspectRatio ?? DEFAULT_MAX_ASPECT_RATIO;
+    const minShortSideMeters = settings?.minShortSideMeters ?? DEFAULT_MIN_SHORT_SIDE_METERS;
+    if (!Number.isFinite(maxAspectRatio) || maxAspectRatio < 1 || !Number.isFinite(minShortSideMeters) || minShortSideMeters < DEFAULT_MIN_SHORT_SIDE_METERS) {
+        throw new RangeError("地块 shape 参数必须为正有限数");
+    }
+    return Object.freeze({ maxAspectRatio, minShortSideMeters });
+}
+function convexHull(points) {
+    const unique = [...new Map(points.map((candidate) => [coordinateKey(candidate), candidate])).values()]
+        .sort((a, b) => a.x - b.x || a.y - b.y);
+    if (unique.length <= 2)
+        return Object.freeze(unique);
+    const build = (input) => {
+        const output = [];
+        for (const candidate of input) {
+            while (output.length >= 2 && signedCross(output[output.length - 2], output[output.length - 1], candidate) <= EPSILON)
+                output.pop();
+            output.push(candidate);
+        }
+        return output;
+    };
+    const lower = build(unique);
+    const upper = build([...unique].reverse());
+    return Object.freeze([...lower.slice(0, -1), ...upper.slice(0, -1)]);
+}
+function rotatedBounds(polygon) {
+    const hull = convexHull(polygon);
+    if (hull.length < 3)
+        return undefined;
+    let best;
+    for (let index = 0; index < hull.length; index += 1) {
+        const from = hull[index];
+        const to = hull[(index + 1) % hull.length];
+        if (from === undefined || to === undefined)
+            continue;
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const length = Math.hypot(dx, dy);
+        if (length <= EPSILON)
+            continue;
+        const ux = dx / length;
+        const uy = dy / length;
+        const along = hull.map((candidate) => candidate.x * ux + candidate.y * uy);
+        const across = hull.map((candidate) => -candidate.x * uy + candidate.y * ux);
+        const width = Math.max(...along) - Math.min(...along);
+        const height = Math.max(...across) - Math.min(...across);
+        const shortSideMeters = Math.min(width, height);
+        const longSideMeters = Math.max(width, height);
+        const longAxis = width >= height ? point(ux, uy) : point(-uy, ux);
+        const area = width * height;
+        if (best === undefined || area < best.area - EPSILON
+            || (Math.abs(area - best.area) <= EPSILON && coordinateKey(longAxis).localeCompare(coordinateKey(best.longAxis)) < 0)) {
+            best = { shortSideMeters, longSideMeters, area, longAxis };
+        }
+    }
+    return best === undefined ? undefined : Object.freeze(best);
+}
+function hasValidShape(polygon, options) {
+    const boundsValue = rotatedBounds(polygon);
+    return boundsValue !== undefined && boundsValue.shortSideMeters + EPSILON >= options.minShortSideMeters
+        && boundsValue.longSideMeters <= boundsValue.shortSideMeters * options.maxAspectRatio + EPSILON;
+}
+function shapePolygonBuildable(polygon, context) {
+    if (!shapePartitionNodeBuildable(polygon, context) || !hasValidShape(polygon, context.options))
+        return false;
+    return true;
+}
+function shapePartitionNodeBuildable(polygon, context) {
+    if (Math.abs(polygonArea(polygon)) < context.minimumArea)
+        return false;
+    if (!polygonWithinBoundary(polygon, context.boundary) || !polygonClearOfEdges(polygon, context.forbiddenEdges, context.setback))
+        return false;
+    const safeBounds = safeBoundsInsidePolygon(polygon);
+    if (safeBounds === undefined || safeBounds.width < context.options.minShortSideMeters || safeBounds.height < context.options.minShortSideMeters)
+        return false;
+    return polygonTerrainBuildable(context.terrain, polygon, context.maxSlope);
+}
+function frontageLength(polygon, edges) {
+    let longest = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        const dx = to.x - from.x;
+        const dy = to.y - from.y;
+        const length = Math.hypot(dx, dy);
+        if (length <= EPSILON)
+            continue;
+        const intervals = [];
+        for (const edge of edges) {
+            const edgeLength = Math.hypot(edge.b.x - edge.a.x, edge.b.y - edge.a.y);
+            const tolerance = EPSILON * Math.max(1, length, edgeLength) ** 2;
+            if (Math.abs(signedCross(from, to, edge.a)) > tolerance || Math.abs(signedCross(from, to, edge.b)) > tolerance)
+                continue;
+            const first = ((edge.a.x - from.x) * dx + (edge.a.y - from.y) * dy) / (length * length);
+            const second = ((edge.b.x - from.x) * dx + (edge.b.y - from.y) * dy) / (length * length);
+            const low = Math.max(0, Math.min(first, second));
+            const high = Math.min(1, Math.max(first, second));
+            if (high - low > EPSILON)
+                intervals.push([low, high]);
+        }
+        intervals.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+        let start;
+        let end;
+        for (const [low, high] of intervals) {
+            if (start === undefined || end === undefined || low > end + EPSILON) {
+                if (start !== undefined && end !== undefined)
+                    longest = Math.max(longest, (end - start) * length);
+                start = low;
+                end = high;
+            }
+            else
+                end = Math.max(end, high);
+        }
+        if (start !== undefined && end !== undefined)
+            longest = Math.max(longest, (end - start) * length);
+    }
+    return longest;
+}
+function frontageBalancedCuts(polygon, edges) {
+    const candidates = [];
+    for (const edge of edges) {
+        const edgeDx = edge.b.x - edge.a.x;
+        const edgeDy = edge.b.y - edge.a.y;
+        const edgeLength = Math.hypot(edgeDx, edgeDy);
+        if (edgeLength <= EPSILON)
+            continue;
+        for (let index = 0; index < polygon.length; index += 1) {
+            const from = polygon[index];
+            const to = polygon[(index + 1) % polygon.length];
+            if (from === undefined || to === undefined)
+                continue;
+            const polygonLength = Math.hypot(to.x - from.x, to.y - from.y);
+            const tolerance = EPSILON * Math.max(1, edgeLength, polygonLength) ** 2;
+            if (Math.abs(signedCross(edge.a, edge.b, from)) > tolerance || Math.abs(signedCross(edge.a, edge.b, to)) > tolerance)
+                continue;
+            const first = ((from.x - edge.a.x) * edgeDx + (from.y - edge.a.y) * edgeDy) / (edgeLength * edgeLength);
+            const second = ((to.x - edge.a.x) * edgeDx + (to.y - edge.a.y) * edgeDy) / (edgeLength * edgeLength);
+            const low = Math.max(0, Math.min(first, second));
+            const high = Math.min(1, Math.max(first, second));
+            if (high - low <= EPSILON)
+                continue;
+            let normal = point(edgeDx / edgeLength, edgeDy / edgeLength);
+            if (normal.x < -EPSILON || (Math.abs(normal.x) <= EPSILON && normal.y < 0))
+                normal = point(-normal.x, -normal.y);
+            const midpoint = point(edge.a.x + edgeDx * (low + high) / 2, edge.a.y + edgeDy * (low + high) / 2);
+            candidates.push(Object.freeze({ normal, cut: midpoint.x * normal.x + midpoint.y * normal.y, length: (high - low) * edgeLength, id: edge.id }));
+        }
+    }
+    return Object.freeze(candidates.sort((a, b) => b.length - a.length || a.id.localeCompare(b.id) || coordinateKey(a.normal).localeCompare(coordinateKey(b.normal))));
+}
+function splitFaceCandidate(face, normal, cut, maximumArea, minimumArea, structured, frontageBalanced, shapeContext, depth) {
+    const lower = clipPolygon(face.polygon, normal, shapeContext === undefined ? cut : cut - V10_SPLIT_QUANTIZATION_GAP, true);
+    const upper = clipPolygon(face.polygon, normal, shapeContext === undefined ? cut : cut + V10_SPLIT_QUANTIZATION_GAP, false);
+    if (lower.length < 3 || upper.length < 3 || Math.abs(polygonArea(lower)) < minimumArea || Math.abs(polygonArea(upper)) < minimumArea)
+        return undefined;
+    const minimumFrontage = Math.max(10, Math.min(20, face.widestRoadMeters));
+    if (structured && (frontageLength(lower, face.frontageEdges) + EPSILON < minimumFrontage
+        || frontageLength(upper, face.frontageEdges) + EPSILON < minimumFrontage))
+        return undefined;
+    if (shapeContext !== undefined && (!shapePartitionNodeBuildable(lower, shapeContext) || !shapePartitionNodeBuildable(upper, shapeContext)))
+        return undefined;
+    const directionKey = `${metric(normal.x)},${metric(normal.y)}`;
+    const lowerPartition = splitFace({ ...face, polygon: canonicalRing(lower), split: `${face.split}/d${directionKey}0` }, maximumArea, minimumArea, structured, frontageBalanced, shapeContext, depth + 1);
+    const upperPartition = splitFace({ ...face, polygon: canonicalRing(upper), split: `${face.split}/d${directionKey}1` }, maximumArea, minimumArea, structured, frontageBalanced, shapeContext, depth + 1);
+    if (shapeContext !== undefined && (lowerPartition.length === 0 || upperPartition.length === 0))
+        return undefined;
+    return Object.freeze([...lowerPartition, ...upperPartition]);
+}
+function splitFace(face, maximumArea, minimumArea, structured, frontageBalanced, shapeContext, depth = 0) {
+    const area = Math.abs(polygonArea(face.polygon));
+    const shapeValid = shapeContext === undefined || hasValidShape(face.polygon, shapeContext.options);
+    if (area <= maximumArea && shapeValid && (shapeContext === undefined || shapePolygonBuildable(face.polygon, shapeContext)))
+        return Object.freeze([face]);
+    if (depth >= 8)
+        return shapeValid && (shapeContext === undefined || shapePolygonBuildable(face.polygon, shapeContext)) ? Object.freeze([face]) : Object.freeze([]);
+    const directions = [];
+    const shapeBounds = shapeContext === undefined ? undefined : rotatedBounds(face.polygon);
+    if (shapeBounds !== undefined)
+        directions.push(shapeBounds.longAxis);
+    directions.push(faceSplitDirection(face.polygon));
+    const triedPrimary = new Set();
+    let primary;
+    for (const direction of directions) {
+        const key = coordinateKey(direction);
+        if (triedPrimary.has(key))
+            continue;
+        triedPrimary.add(key);
+        const projections = face.polygon.map((candidate) => candidate.x * direction.x + candidate.y * direction.y);
+        const cut = (Math.min(...projections) + Math.max(...projections)) / 2;
+        primary = splitFaceCandidate(face, direction, cut, maximumArea, minimumArea, structured, frontageBalanced, shapeContext, depth);
+        if (primary !== undefined && primary.length > 0)
+            return primary;
+    }
+    if (!structured || (!frontageBalanced && shapeContext === undefined))
+        return shapeValid ? Object.freeze([face]) : Object.freeze([]);
+    // PCA 中线无法让两侧均保留 frontage 时，沿最长且稳定排序的真实
+    // frontage 切线投影平分。这样 cut 横穿 frontage，而不是把唯一街边
+    // 完整留给一侧；仍复用同一面积、terrain、走廊与递归 hard gate。
+    const candidates = frontageBalancedCuts(face.polygon, face.frontageEdges);
+    const tried = new Set();
+    for (const { normal, cut: edgeCut } of candidates) {
+        const key = `${coordinateKey(normal)}|${metric(edgeCut)}`;
+        if (tried.has(key))
+            continue;
+        tried.add(key);
+        const balanced = splitFaceCandidate(face, normal, edgeCut, maximumArea, minimumArea, true, true, shapeContext, depth);
+        if (balanced !== undefined && balanced.length > 0)
+            return balanced;
+    }
+    return shapeValid ? Object.freeze([face]) : Object.freeze([]);
+}
+function pointInTriangle(candidate, triangle) {
+    const [a, b, c] = triangle;
+    if (a === undefined || b === undefined || c === undefined)
+        return false;
+    const signs = [signedCross(a, b, candidate), signedCross(b, c, candidate), signedCross(c, a, candidate)];
+    return signs.every((value) => value >= -EPSILON) || signs.every((value) => value <= EPSILON);
+}
+function squareInsidePolygon(center, half, polygon) {
+    const square = [
+        point(center.x - half, center.y - half), point(center.x + half, center.y - half),
+        point(center.x + half, center.y + half), point(center.x - half, center.y + half),
+    ];
+    if (!square.every((candidate) => pointInPolygon(candidate, polygon)))
+        return false;
+    for (let polygonIndex = 0; polygonIndex < polygon.length; polygonIndex += 1) {
+        const a = polygon[polygonIndex];
+        const b = polygon[(polygonIndex + 1) % polygon.length];
+        if (a === undefined || b === undefined)
+            continue;
+        for (let squareIndex = 0; squareIndex < square.length; squareIndex += 1) {
+            const c = square[squareIndex];
+            const d = square[(squareIndex + 1) % square.length];
+            if (c !== undefined && d !== undefined && segmentsIntersect(a, b, c, d))
+                return false;
+        }
+    }
+    return true;
+}
+function triangulate(polygon) {
+    const ring = canonicalRing(polygon);
+    const vertices = ring.map((_, index) => index);
+    const triangles = [];
+    while (vertices.length > 3) {
+        let clipped = false;
+        for (let index = 0; index < vertices.length; index += 1) {
+            const previous = vertices[(index + vertices.length - 1) % vertices.length];
+            const current = vertices[index];
+            const next = vertices[(index + 1) % vertices.length];
+            const a = ring[previous];
+            const b = ring[current];
+            const c = ring[next];
+            if (a === undefined || b === undefined || c === undefined || signedCross(a, b, c) <= EPSILON)
+                continue;
+            const triangle = [a, b, c];
+            const hasInteriorVertex = vertices.some((vertex) => vertex !== previous && vertex !== current && vertex !== next
+                && pointInTriangle(ring[vertex], triangle));
+            if (hasInteriorVertex)
+                continue;
+            triangles.push(triangle);
+            vertices.splice(index, 1);
+            clipped = true;
+            break;
+        }
+        if (!clipped)
+            return Object.freeze([]);
+    }
+    if (vertices.length === 3) {
+        const triangle = vertices.map((index) => ring[index]);
+        if (Math.abs(polygonArea(triangle)) > EPSILON)
+            triangles.push(triangle);
+    }
+    return Object.freeze(triangles.map((triangle) => Object.freeze(triangle)));
+}
+function safeBoundsInsidePolygon(polygon) {
+    let best;
+    const envelope = polygonBounds(polygon);
+    const centers = [
+        polygonCentroid(polygon),
+        point(envelope.x + envelope.width / 2, envelope.y + envelope.height / 2),
+        ...triangulate(polygon).map((triangle) => point(((triangle[0]?.x ?? 0) + (triangle[1]?.x ?? 0) + (triangle[2]?.x ?? 0)) / 3, ((triangle[0]?.y ?? 0) + (triangle[1]?.y ?? 0) + (triangle[2]?.y ?? 0)) / 3)),
+    ];
+    for (const center of centers) {
+        if (!pointInPolygon(center, polygon))
+            continue;
+        let low = 0;
+        let high = Math.min(envelope.width, envelope.height) / 2;
+        for (let iteration = 0; iteration < 30; iteration += 1) {
+            const half = (low + high) / 2;
+            if (squareInsidePolygon(center, half, polygon))
+                low = half;
+            else
+                high = half;
+        }
+        if (low <= EPSILON)
+            continue;
+        const inset = Math.min(0.0001, low / 2);
+        const candidate = bounds(center.x - low + inset, center.y - low + inset, (low - inset) * 2, (low - inset) * 2);
+        if (best === undefined || candidate.width * candidate.height > best.width * best.height)
+            best = candidate;
+    }
+    return best;
+}
+function weightedLandUse(worldSeed, city, boundaryIds, split) {
+    const weights = city.parameters.landUseWeights;
+    const kinds = ["residential", "commercial", "industrial", "civic", "park"];
+    const total = kinds.reduce((sum, kind) => sum + weights[kind], 0);
+    let cursor = unit(["road-land-use", worldSeed, city.seed, city.id, ...boundaryIds, split]) * total;
+    for (const kind of kinds) {
+        cursor -= weights[kind];
+        if (cursor < 0)
+            return kind;
+    }
+    return "park";
+}
+function validBoundary(boundary) {
+    if (boundary?.status !== "bounded")
+        return false;
+    const points = boundary.points;
+    if (points.length < 3 || !points.every((candidate) => Number.isFinite(candidate.x) && Number.isFinite(candidate.y)))
+        return false;
+    if (coordinateKey(points[0]) === coordinateKey(points[points.length - 1]))
+        return false;
+    if (points.some((candidate, index) => index > 0 && coordinateKey(candidate) === coordinateKey(points[index - 1])))
+        return false;
+    return polygonArea(points) > EPSILON;
+}
+function polygonWithinBoundary(polygon, boundary) {
+    if (!polygon.every((candidate) => pointInPolygon(candidate, boundary)))
+        return false;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        if (!pointInPolygon(point((from.x + to.x) / 2, (from.y + to.y) / 2), boundary))
+            return false;
+        for (let boundaryIndex = 0; boundaryIndex < boundary.length; boundaryIndex += 1) {
+            const boundaryFrom = boundary[boundaryIndex];
+            const boundaryTo = boundary[(boundaryIndex + 1) % boundary.length];
+            if (boundaryFrom !== undefined && boundaryTo !== undefined && segmentsCrossWithArea(from, to, boundaryFrom, boundaryTo))
+                return false;
+        }
+    }
+    return true;
+}
+function isBuildableStreet(road, city) {
+    return road.cityId === city.id && (road.kind === "local" || road.kind === "arterial") && road.roadClass !== "motorway";
+}
+function citySurfaceRoads(city, roads) {
+    return Object.freeze([...roads]
+        .filter((road) => isBuildableStreet(road, city))
+        .sort((a, b) => a.id.localeCompare(b.id)));
+}
+function collectSurfaceGraph(city, roads) {
+    const points = new Map();
+    const edges = [];
+    for (const road of citySurfaceRoads(city, roads)) {
+        // 地块只由本城的 at-grade arterial/local 道路围合。城际 road 即使穿过
+        // city bbox 也只是连接基础设施，不能改变城市 parcel topology。
+        assertFinite(road.widthMeters, `road ${road.id}.widthMeters`);
+        for (let segmentIndex = 0; segmentIndex < road.segments.length; segmentIndex += 1) {
+            const segment = road.segments[segmentIndex];
+            if (segment === undefined || segment.kind !== "surface")
+                continue;
+            for (let pointIndex = 0; pointIndex < segment.points.length - 1; pointIndex += 1) {
+                const fromRaw = segment.points[pointIndex];
+                const toRaw = segment.points[pointIndex + 1];
+                if (fromRaw === undefined || toRaw === undefined)
+                    continue;
+                assertFinite(fromRaw.x, `road ${road.id}.point.x`);
+                assertFinite(fromRaw.y, `road ${road.id}.point.y`);
+                assertFinite(toRaw.x, `road ${road.id}.point.x`);
+                assertFinite(toRaw.y, `road ${road.id}.point.y`);
+                const from = point(fromRaw.x, fromRaw.y);
+                const to = point(toRaw.x, toRaw.y);
+                if (coordinateKey(from) === coordinateKey(to))
+                    continue;
+                const fromKey = coordinateKey(from);
+                const toKey = coordinateKey(to);
+                points.set(fromKey, from);
+                points.set(toKey, to);
+                edges.push(Object.freeze({
+                    id: `${road.id}:${segmentIndex}:${pointIndex}`,
+                    roadId: road.id,
+                    widthMeters: road.widthMeters,
+                    from: fromKey,
+                    to: toKey,
+                    a: from,
+                    b: to,
+                }));
+            }
+        }
+    }
+    return Object.freeze({ points, edges: Object.freeze(edges) });
+}
+function collectSurfaceRuns(city, roads) {
+    const runs = [];
+    for (const road of citySurfaceRoads(city, roads))
+        for (let segmentIndex = 0; segmentIndex < road.segments.length; segmentIndex += 1) {
+            const segment = road.segments[segmentIndex];
+            if (segment === undefined || segment.kind !== "surface" || segment.points.length < 2)
+                continue;
+            const points = segment.points.map((candidate) => point(candidate.x, candidate.y));
+            if (points.some((candidate, index) => index > 0 && coordinateKey(candidate) === coordinateKey(points[index - 1])))
+                continue;
+            runs.push(Object.freeze({ id: `${road.id}:${segmentIndex}`, widthMeters: road.widthMeters, points: Object.freeze(points) }));
+        }
+    return Object.freeze(runs);
+}
+/**
+ * 高速/城际与本城未知等级道路不能围地，但其 surface 中心线仍是不可建走廊。
+ * 这同时防御带有伪造 cityId 的 intercity 输入与遗留缺 kind 输入。
+ */
+function collectForbiddenCorridorEdges(city, roads) {
+    const edges = [];
+    for (const road of [...roads].sort((a, b) => a.id.localeCompare(b.id))) {
+        const forbidden = road.kind === "intercity" || road.roadClass === "motorway"
+            || (road.cityId === city.id && !isBuildableStreet(road, city));
+        if (!forbidden)
+            continue;
+        assertFinite(road.widthMeters, `road ${road.id}.widthMeters`);
+        for (let segmentIndex = 0; segmentIndex < road.segments.length; segmentIndex += 1) {
+            const segment = road.segments[segmentIndex];
+            if (segment === undefined || segment.kind !== "surface")
+                continue;
+            for (let pointIndex = 0; pointIndex < segment.points.length - 1; pointIndex += 1) {
+                const fromRaw = segment.points[pointIndex];
+                const toRaw = segment.points[pointIndex + 1];
+                if (fromRaw === undefined || toRaw === undefined)
+                    continue;
+                const from = point(fromRaw.x, fromRaw.y);
+                const to = point(toRaw.x, toRaw.y);
+                if (coordinateKey(from) === coordinateKey(to))
+                    continue;
+                edges.push(Object.freeze({
+                    id: `forbidden:${road.id}:${segmentIndex}:${pointIndex}`,
+                    roadId: road.id,
+                    widthMeters: road.widthMeters,
+                    from: coordinateKey(from), to: coordinateKey(to), a: from, b: to,
+                }));
+            }
+        }
+    }
+    return Object.freeze(edges);
+}
+/** 只切严格内部 XY 交点；端点本来已由 canonical coordinate key 连接。 */
+function strictIntersection(a, b, c, d) {
+    const abX = b.x - a.x;
+    const abY = b.y - a.y;
+    const cdX = d.x - c.x;
+    const cdY = d.y - c.y;
+    const denominator = abX * cdY - abY * cdX;
+    if (Math.abs(denominator) <= EPSILON)
+        return undefined;
+    const acX = c.x - a.x;
+    const acY = c.y - a.y;
+    const first = (acX * cdY - acY * cdX) / denominator;
+    const second = (acX * abY - acY * abX) / denominator;
+    if (first <= EPSILON || first >= 1 - EPSILON || second <= EPSILON || second >= 1 - EPSILON)
+        return undefined;
+    return Object.freeze({ first, second });
+}
+/**
+ * terrain router 的采样线可在 XY 上相交而不共享同一采样点。DCEL 前必须切分，
+ * 否则会把实际 junction 当成两条穿越线，遗漏可闭合 block。
+ */
+function planarizeGraph(city, graph) {
+    const splits = new Map();
+    for (const edge of graph.edges)
+        splits.set(edge.id, [0, 1]);
+    const buckets = new Map();
+    const cellSize = Math.max(16, city.parameters.blockSizeMeters);
+    for (let index = 0; index < graph.edges.length; index += 1) {
+        const edge = graph.edges[index];
+        if (edge === undefined)
+            continue;
+        const minColumn = Math.floor(Math.min(edge.a.x, edge.b.x) / cellSize);
+        const maxColumn = Math.floor(Math.max(edge.a.x, edge.b.x) / cellSize);
+        const minRow = Math.floor(Math.min(edge.a.y, edge.b.y) / cellSize);
+        const maxRow = Math.floor(Math.max(edge.a.y, edge.b.y) / cellSize);
+        for (let column = minColumn; column <= maxColumn; column += 1)
+            for (let row = minRow; row <= maxRow; row += 1) {
+                const key = `${column}:${row}`;
+                const current = buckets.get(key) ?? [];
+                current.push(index);
+                buckets.set(key, current);
+            }
+    }
+    const checked = new Set();
+    for (const entries of buckets.values()) {
+        for (let firstIndex = 0; firstIndex < entries.length; firstIndex += 1)
+            for (let secondIndex = firstIndex + 1; secondIndex < entries.length; secondIndex += 1) {
+                const first = entries[firstIndex];
+                const second = entries[secondIndex];
+                if (first === undefined || second === undefined)
+                    continue;
+                const key = first < second ? `${first}:${second}` : `${second}:${first}`;
+                if (checked.has(key))
+                    continue;
+                checked.add(key);
+                const a = graph.edges[first];
+                const b = graph.edges[second];
+                if (a === undefined || b === undefined)
+                    continue;
+                const intersection = strictIntersection(a.a, a.b, b.a, b.b);
+                if (intersection === undefined)
+                    continue;
+                splits.get(a.id)?.push(intersection.first);
+                splits.get(b.id)?.push(intersection.second);
+            }
+    }
+    const points = new Map();
+    const edges = [];
+    for (const edge of graph.edges) {
+        const parameters = [...new Set((splits.get(edge.id) ?? [0, 1]).map((value) => metric(value)))].sort((a, b) => a - b);
+        for (let index = 0; index < parameters.length - 1; index += 1) {
+            const fromParameter = parameters[index];
+            const toParameter = parameters[index + 1];
+            if (fromParameter === undefined || toParameter === undefined || toParameter - fromParameter <= EPSILON)
+                continue;
+            const from = point(edge.a.x + (edge.b.x - edge.a.x) * fromParameter, edge.a.y + (edge.b.y - edge.a.y) * fromParameter);
+            const to = point(edge.a.x + (edge.b.x - edge.a.x) * toParameter, edge.a.y + (edge.b.y - edge.a.y) * toParameter);
+            const fromKey = coordinateKey(from);
+            const toKey = coordinateKey(to);
+            if (fromKey === toKey)
+                continue;
+            points.set(fromKey, from);
+            points.set(toKey, to);
+            edges.push(Object.freeze({ ...edge, id: `${edge.id}@${index}`, from: fromKey, to: toKey, a: from, b: to }));
+        }
+    }
+    return Object.freeze({ points, edges: Object.freeze(edges) });
+}
+function extractFaces(city, boundary, roads) {
+    const graph = planarizeGraph(city, collectSurfaceGraph(city, roads));
+    const adjacency = new Map();
+    for (const edge of graph.edges) {
+        const from = adjacency.get(edge.from) ?? [];
+        from.push(Object.freeze({ edge, to: edge.to }));
+        adjacency.set(edge.from, from);
+        const to = adjacency.get(edge.to) ?? [];
+        to.push(Object.freeze({ edge, to: edge.from }));
+        adjacency.set(edge.to, to);
+    }
+    for (const [key, entries] of adjacency) {
+        const origin = graph.points.get(key);
+        if (origin === undefined)
+            continue;
+        entries.sort((a, b) => {
+            const aPoint = graph.points.get(a.to);
+            const bPoint = graph.points.get(b.to);
+            const angleA = Math.atan2((aPoint?.y ?? 0) - origin.y, (aPoint?.x ?? 0) - origin.x);
+            const angleB = Math.atan2((bPoint?.y ?? 0) - origin.y, (bPoint?.x ?? 0) - origin.x);
+            return angleA - angleB || a.edge.id.localeCompare(b.edge.id) || a.to.localeCompare(b.to);
+        });
+    }
+    const directed = [...graph.edges].flatMap((edge) => [
+        Object.freeze({ edge, from: edge.from, to: edge.to }), Object.freeze({ edge, from: edge.to, to: edge.from }),
+    ]);
+    const visited = new Set();
+    const faces = [];
+    for (const start of directed) {
+        const startKey = `${start.edge.id}|${start.from}|${start.to}`;
+        if (visited.has(startKey))
+            continue;
+        const ring = [];
+        const boundaryEdgeIds = [];
+        let current = start;
+        for (let guard = 0; guard <= directed.length + 1; guard += 1) {
+            const currentKey = `${current.edge.id}|${current.from}|${current.to}`;
+            if (visited.has(currentKey))
+                break;
+            visited.add(currentKey);
+            const currentPoint = graph.points.get(current.from);
+            if (currentPoint === undefined)
+                break;
+            ring.push(currentPoint);
+            boundaryEdgeIds.push(current.edge.id);
+            const nextEntries = adjacency.get(current.to);
+            if (nextEntries === undefined)
+                break;
+            const reverseIndex = nextEntries.findIndex((entry) => entry.edge.id === current.edge.id && entry.to === current.from);
+            if (reverseIndex < 0)
+                break;
+            const next = nextEntries[(reverseIndex + nextEntries.length - 1) % nextEntries.length];
+            if (next === undefined)
+                break;
+            current = Object.freeze({ edge: next.edge, from: current.to, to: next.to });
+            if (current.edge.id === start.edge.id && current.from === start.from && current.to === start.to)
+                break;
+        }
+        const clean = ring.filter((candidate, index) => index === 0 || coordinateKey(candidate) !== coordinateKey(ring[index - 1]));
+        const area = polygonArea(clean);
+        if (clean.length < 3 || area <= EPSILON)
+            continue; // 负面积为外部无限 face。
+        if (!polygonWithinBoundary(clean, boundary))
+            continue;
+        const byId = new Map(graph.edges.map((edge) => [edge.id, edge]));
+        const frontageEdges = boundaryEdgeIds.map((id) => byId.get(id)).filter((edge) => edge !== undefined);
+        const widestRoadMeters = Math.max(...frontageEdges.map((edge) => edge.widthMeters));
+        faces.push(Object.freeze({
+            polygon: canonicalRing(clean),
+            boundaryIds: Object.freeze([...new Set(boundaryEdgeIds)].sort()),
+            frontageEdges: Object.freeze(frontageEdges),
+            widestRoadMeters,
+        }));
+    }
+    return Object.freeze(faces);
+}
+function polygonClearOfEdges(polygon, edges, setback) {
+    for (const edge of edges) {
+        const clearance = edge.widthMeters / 2 + setback;
+        if (pointInPolygon(edge.a, polygon) || pointInPolygon(edge.b, polygon))
+            return false;
+        for (let index = 0; index < polygon.length; index += 1) {
+            const from = polygon[index];
+            const to = polygon[(index + 1) % polygon.length];
+            if (from === undefined || to === undefined)
+                continue;
+            if (segmentDistance(from, to, edge.a, edge.b) <= clearance + EPSILON)
+                return false;
+        }
+    }
+    return true;
+}
+function polygonClearOfRoadCorridors(polygon, sourceRunId, streetEdges, forbiddenEdges, setback) {
+    const otherStreets = streetEdges.filter((edge) => !edge.id.startsWith(`${sourceRunId}:`));
+    return polygonClearOfEdges(polygon, otherStreets, setback) && polygonClearOfEdges(polygon, forbiddenEdges, setback);
+}
+function strictlyInsidePolygon(candidate, polygon) {
+    if (!pointInPolygon(candidate, polygon))
+        return false;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = polygon[index];
+        const b = polygon[(index + 1) % polygon.length];
+        if (a !== undefined && b !== undefined && pointOnSegment(candidate, a, b))
+            return false;
+    }
+    return true;
+}
+function segmentsCrossWithArea(a, b, c, d) {
+    const first = signedCross(a, b, c);
+    const second = signedCross(a, b, d);
+    const third = signedCross(c, d, a);
+    const fourth = signedCross(c, d, b);
+    return (first > EPSILON && second < -EPSILON || first < -EPSILON && second > EPSILON)
+        && (third > EPSILON && fourth < -EPSILON || third < -EPSILON && fourth > EPSILON);
+}
+/**
+ * 边界 touch 可共存；只要外轮廓有正面积交集即为冲突。
+ * 绝不能以内部 building safe bounds 作早退，因为两个外轮廓可相交而两个 safe square 分离。
+ */
+export function roadParcelPolygonsOverlapWithArea(a, b) {
+    if (a.length < 3 || b.length < 3)
+        return false;
+    const firstEnvelope = polygonBounds(a);
+    const secondEnvelope = polygonBounds(b);
+    if (firstEnvelope.x + firstEnvelope.width <= secondEnvelope.x + EPSILON || secondEnvelope.x + secondEnvelope.width <= firstEnvelope.x + EPSILON
+        || firstEnvelope.y + firstEnvelope.height <= secondEnvelope.y + EPSILON || secondEnvelope.y + secondEnvelope.height <= firstEnvelope.y + EPSILON)
+        return false;
+    if (a.some((candidate) => strictlyInsidePolygon(candidate, b)) || b.some((candidate) => strictlyInsidePolygon(candidate, a)))
+        return true;
+    for (let index = 0; index < a.length; index += 1) {
+        const from = a[index];
+        const to = a[(index + 1) % a.length];
+        if (from === undefined || to === undefined)
+            continue;
+        for (let otherIndex = 0; otherIndex < b.length; otherIndex += 1) {
+            const otherFrom = b[otherIndex];
+            const otherTo = b[(otherIndex + 1) % b.length];
+            if (otherFrom !== undefined && otherTo !== undefined && segmentsCrossWithArea(from, to, otherFrom, otherTo))
+                return true;
+        }
+    }
+    return false;
+}
+function parcelsOverlapWithArea(first, second) {
+    const a = first.polygon;
+    const b = second.polygon;
+    return a !== undefined && b !== undefined && roadParcelPolygonsOverlapWithArea(a, b);
+}
+function withoutParcelOverlaps(parcels) {
+    const accepted = [];
+    for (const parcel of [...parcels].sort((a, b) => a.id.localeCompare(b.id))) {
+        if (!accepted.some((candidate) => parcelsOverlapWithArea(candidate, parcel)))
+            accepted.push(parcel);
+    }
+    return Object.freeze(accepted);
+}
+/**
+ * 已验收的 block face 优先保留；frontage 仅填补其外部未覆盖的普通街带。
+ * 不允许按 ID 让 later frontage 淘汰 face，也不允许通过该合并绕过正面积无交门。
+ */
+function appendUncoveredFrontage(acceptedFaces, frontageCandidates) {
+    const accepted = [...acceptedFaces].sort((a, b) => a.id.localeCompare(b.id));
+    for (const frontage of [...frontageCandidates].sort((a, b) => a.id.localeCompare(b.id))) {
+        if (!accepted.some((candidate) => parcelsOverlapWithArea(candidate, frontage)))
+            accepted.push(frontage);
+    }
+    accepted.sort((a, b) => a.id.localeCompare(b.id));
+    return Object.freeze(accepted);
+}
+function polylineLength(points) {
+    let total = 0;
+    for (let index = 1; index < points.length; index += 1) {
+        const previous = points[index - 1];
+        const current = points[index];
+        if (previous !== undefined && current !== undefined)
+            total += Math.hypot(current.x - previous.x, current.y - previous.y);
+    }
+    return total;
+}
+/** 将长 route segment 分为固定上限的连续采样段；不按世界坐标切格。 */
+function frontageSlices(run, maxLength = 42, minimumLength = 16) {
+    const slices = [];
+    let start = 0;
+    let ordinal = 0;
+    while (start < run.points.length - 1) {
+        const points = [run.points[start]];
+        let length = 0;
+        let end = start + 1;
+        for (; end < run.points.length; end += 1) {
+            const previous = run.points[end - 1];
+            const current = run.points[end];
+            if (previous === undefined || current === undefined)
+                continue;
+            const nextLength = length + Math.hypot(current.x - previous.x, current.y - previous.y);
+            if (points.length > 1 && nextLength > maxLength)
+                break;
+            points.push(current);
+            length = nextLength;
+        }
+        if (points.length >= 2 && length >= minimumLength)
+            slices.push(Object.freeze({ id: `${run.id}:frontage:${ordinal}`, points: Object.freeze(points) }));
+        if (end >= run.points.length)
+            break;
+        start = Math.max(start + 1, end - 1);
+        ordinal += 1;
+    }
+    return Object.freeze(slices);
+}
+function subdividePolyline(points, maximumStep) {
+    const output = [];
+    for (let index = 1; index < points.length; index += 1) {
+        const from = points[index - 1];
+        const to = points[index];
+        if (from === undefined || to === undefined)
+            continue;
+        if (output.length === 0)
+            output.push(from);
+        const length = Math.hypot(to.x - from.x, to.y - from.y);
+        const steps = Math.max(1, Math.ceil(length / maximumStep));
+        for (let step = 1; step <= steps; step += 1)
+            output.push(point(from.x + (to.x - from.x) * step / steps, from.y + (to.y - from.y) * step / steps));
+    }
+    return Object.freeze(output);
+}
+function frontagePolygon(points, side, inner, outer) {
+    if (points.length < 2 || polylineLength(points) <= EPSILON)
+        return undefined;
+    const offset = (index, distance) => {
+        const current = points[index];
+        const previous = points[Math.max(0, index - 1)];
+        const next = points[Math.min(points.length - 1, index + 1)];
+        if (current === undefined || previous === undefined || next === undefined)
+            return undefined;
+        const beforeLength = Math.hypot(current.x - previous.x, current.y - previous.y);
+        const afterLength = Math.hypot(next.x - current.x, next.y - current.y);
+        const beforeX = beforeLength <= EPSILON ? 0 : (current.x - previous.x) / beforeLength;
+        const beforeY = beforeLength <= EPSILON ? 0 : (current.y - previous.y) / beforeLength;
+        const afterX = afterLength <= EPSILON ? beforeX : (next.x - current.x) / afterLength;
+        const afterY = afterLength <= EPSILON ? beforeY : (next.y - current.y) / afterLength;
+        const tangentLength = Math.hypot(beforeX + afterX, beforeY + afterY);
+        const tangentX = tangentLength <= EPSILON ? afterX : (beforeX + afterX) / tangentLength;
+        const tangentY = tangentLength <= EPSILON ? afterY : (beforeY + afterY) / tangentLength;
+        if (Math.hypot(tangentX, tangentY) <= EPSILON)
+            return undefined;
+        return point(current.x - tangentY * side * distance, current.y + tangentX * side * distance);
+    };
+    const innerLine = points.map((_, index) => offset(index, inner));
+    const outerLine = points.map((_, index) => offset(index, outer));
+    if (innerLine.some((candidate) => candidate === undefined) || outerLine.some((candidate) => candidate === undefined))
+        return undefined;
+    const polygon = canonicalRing([...innerLine, ...outerLine.reverse()]);
+    return Math.abs(polygonArea(polygon)) > EPSILON ? polygon : undefined;
+}
+function polygonClearOfSourceRun(polygon, sourceRunId, edges, clearance) {
+    const sourceEdges = edges.filter((edge) => edge.id.startsWith(`${sourceRunId}:`));
+    if (sourceEdges.length === 0)
+        return false;
+    for (const candidate of polygon) {
+        if (sourceEdges.some((edge) => distancePointToSegment(candidate, edge.a, edge.b) < clearance - 0.2))
+            return false;
+    }
+    for (let index = 0; index < polygon.length; index += 1) {
+        const from = polygon[index];
+        const to = polygon[(index + 1) % polygon.length];
+        if (from === undefined || to === undefined)
+            continue;
+        if (sourceEdges.some((edge) => segmentsIntersect(from, to, edge.a, edge.b)))
+            return false;
+    }
+    return true;
+}
+/**
+ * 没有可建 block 时才使用：沿真实 surface elementary edge 的两侧生成少量 frontage，
+ * 不做坐标网格分块，也不会跨越其他 road corridor、水面或陡坡。
+ */
+function extractFrontageParcels(worldSeed, city, terrain, boundary, roads, minimumArea, maxSlope, setback, shape) {
+    const graph = planarizeGraph(city, collectSurfaceGraph(city, roads));
+    const forbiddenEdges = collectForbiddenCorridorEdges(city, roads);
+    const parcels = [];
+    const requiredStripDimension = shape === undefined ? 0 : shape.minShortSideMeters * Math.SQRT2 + 1;
+    const depth = shape === undefined
+        ? Math.max(10, Math.min(20, city.parameters.blockSizeMeters * 0.18))
+        : Math.max(city.parameters.blockSizeMeters * 0.18, requiredStripDimension);
+    // 高最短边约束会让 10m 取样后的累计长度错过刚好合格的临街段，预留一个取样步长。
+    const maximumSliceLength = shape === undefined
+        ? 42
+        : Math.max(requiredStripDimension + (requiredStripDimension > 42 ? 10 : 0), Math.min(42, shape.maxAspectRatio * depth));
+    for (const run of collectSurfaceRuns(city, roads)) {
+        const slicedRun = shape === undefined ? run : Object.freeze({ ...run, points: subdividePolyline(run.points, Math.max(1, Math.min(10, maximumSliceLength))) });
+        for (const slice of frontageSlices(slicedRun, maximumSliceLength, shape === undefined ? 16 : requiredStripDimension)) {
+            const clearance = run.widthMeters / 2 + setback;
+            for (const side of [-1, 1]) {
+                const polygon = frontagePolygon(slice.points, side, clearance + 0.01, clearance + depth);
+                if (polygon === undefined)
+                    continue;
+                if (shape !== undefined && !hasValidShape(polygon, shape))
+                    continue;
+                if (!polygonWithinBoundary(polygon, boundary))
+                    continue;
+                if (!polygonClearOfSourceRun(polygon, run.id, graph.edges, clearance))
+                    continue;
+                if (!polygonClearOfRoadCorridors(polygon, run.id, graph.edges, forbiddenEdges, setback))
+                    continue;
+                if (!polygonTerrainBuildable(terrain, polygon, maxSlope))
+                    continue;
+                const safeBounds = safeBoundsInsidePolygon(polygon);
+                const minimumSafeDimension = shape?.minShortSideMeters ?? MIN_SAFE_BUILDING_DIMENSION;
+                if (safeBounds === undefined || safeBounds.width < minimumSafeDimension || safeBounds.height < minimumSafeDimension
+                    || safeBounds.width * safeBounds.height < minimumArea)
+                    continue;
+                const split = `frontage-v1:${side < 0 ? "left" : "right"}`;
+                const boundaryIds = Object.freeze([slice.id]);
+                parcels.push(Object.freeze({
+                    id: stableId([worldSeed, city.seed, city.id, ...boundaryIds, split]),
+                    cityId: city.id,
+                    landUse: weightedLandUse(worldSeed, city, boundaryIds, split),
+                    bounds: safeBounds,
+                    polygon: Object.freeze(polygon.map((candidate) => Object.freeze(candidate))),
+                }));
+            }
+        }
+    }
+    return withoutParcelOverlaps(parcels);
+}
+function validTerrainGrid(grid, maxSlope) {
+    return Number.isInteger(grid.width) && Number.isInteger(grid.height)
+        && grid.width >= 2 && grid.height >= 2 && grid.width <= MAX_TERRAIN_GRID_SIDE && grid.height <= MAX_TERRAIN_GRID_SIDE
+        && grid.elevationsMeters.length === grid.width * grid.height && grid.waterMask.length === grid.width * grid.height
+        && Number.isFinite(grid.widthMeters) && Number.isFinite(grid.heightMeters) && grid.widthMeters > 0 && grid.heightMeters > 0
+        && Number.isFinite(grid.originX) && Number.isFinite(grid.originY) && Number.isFinite(maxSlope) && maxSlope >= 0;
+}
+function terrainCellBuildable(grid, column, row, maxSlope) {
+    if (!validTerrainGrid(grid, maxSlope) || column < 0 || row < 0 || column >= grid.width || row >= grid.height)
+        return false;
+    const cellWidth = grid.widthMeters / (grid.width - 1);
+    const cellHeight = grid.heightMeters / (grid.height - 1);
+    const index = row * grid.width + column;
+    if (Boolean(grid.waterMask[index]))
+        return false;
+    const elevation = grid.elevationsMeters[index];
+    return Number.isFinite(elevation) && cellWidth > 0 && cellHeight > 0;
+}
+function terrainCellBounds(grid, column, row) {
+    const stepX = grid.widthMeters / (grid.width - 1);
+    const stepY = grid.heightMeters / (grid.height - 1);
+    const centerX = grid.originX + column * stepX;
+    const centerY = grid.originY + row * stepY;
+    const minX = Math.max(grid.originX, centerX - stepX / 2);
+    const minY = Math.max(grid.originY, centerY - stepY / 2);
+    const maxX = Math.min(grid.originX + grid.widthMeters, centerX + stepX / 2);
+    const maxY = Math.min(grid.originY + grid.heightMeters, centerY + stepY / 2);
+    return bounds(minX, minY, maxX - minX, maxY - minY);
+}
+/** 固定 city bbox grid 的最近点采样；水和过陡的 cell 均不可建。 */
+export function sampleRoadParcelTerrain(grid, candidate, maxSlope = DEFAULT_MAX_SLOPE) {
+    if (!validTerrainGrid(grid, maxSlope))
+        return false;
+    const cellWidth = grid.widthMeters / (grid.width - 1);
+    const cellHeight = grid.heightMeters / (grid.height - 1);
+    const column = Math.round((candidate.x - grid.originX) / cellWidth);
+    const row = Math.round((candidate.y - grid.originY) / cellHeight);
+    return terrainCellBuildable(grid, column, row, maxSlope);
+}
+/**
+ * 不仅采样 center/corners：扫描所有与 polygon 接触的 terrain cells。
+ * 这让内部小湖、沿边的细水带和孤立坡度尖峰都成为硬排除条件。
+ */
+function polygonTerrainBuildable(grid, polygon, maxSlope) {
+    if (!validTerrainGrid(grid, maxSlope))
+        return false;
+    const terrainBounds = bounds(grid.originX, grid.originY, grid.widthMeters, grid.heightMeters);
+    if (polygon.some((candidate) => !pointInBounds(candidate, terrainBounds)))
+        return false;
+    const envelope = polygonBounds(polygon);
+    const stepX = grid.widthMeters / (grid.width - 1);
+    const stepY = grid.heightMeters / (grid.height - 1);
+    const firstColumn = Math.max(0, Math.ceil((envelope.x - grid.originX) / stepX - 0.5 - EPSILON));
+    const lastColumn = Math.min(grid.width - 1, Math.floor((envelope.x + envelope.width - grid.originX) / stepX + 0.5 + EPSILON));
+    const firstRow = Math.max(0, Math.ceil((envelope.y - grid.originY) / stepY - 0.5 - EPSILON));
+    const lastRow = Math.min(grid.height - 1, Math.floor((envelope.y + envelope.height - grid.originY) / stepY + 0.5 + EPSILON));
+    const touched = new Set();
+    for (let row = firstRow; row <= lastRow; row += 1) {
+        for (let column = firstColumn; column <= lastColumn; column += 1) {
+            if (!polygonIntersectsBounds(polygon, terrainCellBounds(grid, column, row)))
+                continue;
+            if (!terrainCellBuildable(grid, column, row, maxSlope))
+                return false;
+            touched.add(row * grid.width + column);
+        }
+    }
+    for (const index of touched) {
+        const column = index % grid.width;
+        const row = Math.floor(index / grid.width);
+        const elevation = grid.elevationsMeters[index];
+        for (const [nextColumn, nextRow, distance] of [[column + 1, row, stepX], [column, row + 1, stepY]]) {
+            if (nextColumn >= grid.width || nextRow >= grid.height)
+                continue;
+            const nextIndex = nextRow * grid.width + nextColumn;
+            if (!touched.has(nextIndex))
+                continue;
+            const nextElevation = grid.elevationsMeters[nextIndex];
+            if (!Number.isFinite(elevation) || !Number.isFinite(nextElevation)
+                || Math.abs(nextElevation - elevation) / distance > maxSlope + EPSILON)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * 从 surface road 的 planar faces 生成可重建的真实地块。缺少可采样 terrain 时有意返回空，
+ * 而非退回矩形棋盘或猜测水面；建筑需在角色进入 gate 后再以 parcel.bounds 生成。
+ */
+export function generateRoadParcels(worldSeed, city, input) {
+    if (!Number.isInteger(worldSeed) || worldSeed < 0 || worldSeed > 0xffff_ffff)
+        throw new RangeError("worldSeed 必须是 uint32");
+    if (input.algorithm !== undefined && input.algorithm !== "legacy-v6" && input.algorithm !== "structured-v8" && input.algorithm !== "frontage-balanced-v9" && input.algorithm !== "shape-filled-v10") {
+        throw new TypeError("road parcel algorithm 非法");
+    }
+    if (input.terrain === undefined || !validBoundary(input.boundary))
+        return Object.freeze({ parcels: Object.freeze([]) });
+    const maximumArea = input.settings?.maxFaceAreaMeters ?? DEFAULT_MAX_FACE_AREA;
+    const minimumArea = input.settings?.minParcelAreaMeters ?? DEFAULT_MIN_PARCEL_AREA;
+    const maxSlope = input.settings?.maxSlope ?? DEFAULT_MAX_SLOPE;
+    const requestedSetback = input.settings?.setbackMeters ?? 0;
+    const setback = Math.max(0, requestedSetback);
+    if (!Number.isFinite(maximumArea) || maximumArea < minimumArea || minimumArea <= 0)
+        throw new RangeError("地块面积设置非法");
+    if (!Number.isFinite(maxSlope) || maxSlope < 0 || !Number.isFinite(requestedSetback))
+        throw new RangeError("地块地形设置非法");
+    const boundary = input.boundary.points;
+    const forbiddenEdges = collectForbiddenCorridorEdges(city, input.roads);
+    const faces = extractFaces(city, boundary, input.roads);
+    const shapeFilled = input.algorithm === "shape-filled-v10";
+    const shapeContext = shapeFilled ? Object.freeze({
+        boundary,
+        forbiddenEdges,
+        terrain: input.terrain,
+        maxSlope,
+        setback,
+        minimumArea,
+        options: shapeOptions(input.settings),
+    }) : undefined;
+    const structured = input.algorithm === "structured-v8" || input.algorithm === "frontage-balanced-v9" || shapeFilled;
+    const frontageBalanced = input.algorithm === "frontage-balanced-v9";
+    const candidates = faces
+        .flatMap((face) => {
+        if (!structured)
+            return splitFace({ ...face, split: "root" }, maximumArea, minimumArea, false, false, undefined);
+        if (shapeFilled) {
+            const inset = insetSimpleFace(face, setback);
+            return inset === undefined ? [] : facePiecesAfterInset(inset)
+                .flatMap((piece, index) => splitFace({ ...piece, split: `root/c${index}` }, maximumArea, minimumArea, true, true, shapeContext));
+        }
+        const inset = insetConvexFace(face, setback);
+        return inset === undefined ? [] : splitFace({ ...inset, split: "root" }, maximumArea, minimumArea, true, frontageBalanced, shapeContext);
+    });
+    const parcels = [];
+    for (const face of candidates) {
+        const polygon = structured ? face.polygon : insetPolygon(face.polygon, face.widestRoadMeters / 2 + setback);
+        if (polygon === undefined || Math.abs(polygonArea(polygon)) < minimumArea)
+            continue;
+        if (!polygonWithinBoundary(polygon, boundary) || !polygonClearOfEdges(polygon, forbiddenEdges, setback))
+            continue;
+        const safeBounds = safeBoundsInsidePolygon(polygon);
+        const minimumSafeDimension = shapeContext?.options.minShortSideMeters ?? MIN_SAFE_BUILDING_DIMENSION;
+        if (safeBounds === undefined || safeBounds.width < minimumSafeDimension || safeBounds.height < minimumSafeDimension
+            || safeBounds.width * safeBounds.height < Math.min(4, minimumArea))
+            continue;
+        if (!polygonTerrainBuildable(input.terrain, polygon, maxSlope))
+            continue;
+        const boundaryIds = face.boundaryIds;
+        parcels.push(Object.freeze({
+            id: stableId([worldSeed, city.seed, city.id, ...boundaryIds, face.split]),
+            cityId: city.id,
+            landUse: weightedLandUse(worldSeed, city, boundaryIds, face.split),
+            bounds: safeBounds,
+            polygon: Object.freeze(polygon.map((candidate) => Object.freeze(candidate))),
+        }));
+    }
+    const nonOverlappingFaces = withoutParcelOverlaps(parcels);
+    // face 只覆盖闭合 block；同城剩余 open-street 区域可追加经过相同 hard gate 的 frontage。
+    // 这不是网格回退：frontage 仍只沿 qualifying street polyline，且只能填补 face 未覆盖区域。
+    const frontage = extractFrontageParcels(worldSeed, city, input.terrain, boundary, input.roads, minimumArea, maxSlope, setback, shapeContext?.options);
+    return Object.freeze({
+        parcels: appendUncoveredFrontage(nonOverlappingFaces, frontage),
+    });
+}