@jgengine/core 0.11.0 → 0.13.0

package/dist/world/buildSockets.js

@@ -0,0 +1,188 @@
+/**
+ * Data-driven modular build-piece snap system: a catalog of piece types, each declaring named
+ * sockets (local position + outward facing + a generic "kind"), plus a connection-rule table saying
+ * which socket kinds may mate. Given a placed piece and a candidate type it resolves every valid
+ * snap — the world transform that lands the candidate's socket exactly on the placed piece's socket,
+ * facing back into it. Genre-agnostic: foundation/wall/ceiling/pillar/edge snapping falls out of the
+ * catalog data, with no game-specific piece names baked in. Pure and serializable; composes with
+ * `world/footprintGrid` occupancy (via an injected `isFree` predicate — never imported) and with
+ * `scene/modelSockets` named attach points (via {@link pieceSocketsFromModel}).
+ */
+/** Length-prefixed composite key (avoids delimiter collisions without any control characters). */
+function pairKey(a, b) {
+    return `${a.length}:${a}:${b}`;
+}
+/** Rotate a local offset about +Y by `yaw` radians (affects X/Z, leaves Y). */
+function rotateY(v, yaw) {
+    if (yaw === 0)
+        return [v[0], v[1], v[2]];
+    const cos = Math.cos(yaw);
+    const sin = Math.sin(yaw);
+    return [v[0] * cos - v[2] * sin, v[1], v[0] * sin + v[2] * cos];
+}
+function cloneSocket(socket) {
+    return {
+        name: socket.name,
+        kind: socket.kind,
+        position: [socket.position[0], socket.position[1], socket.position[2]],
+        ...(socket.yaw === undefined ? {} : { yaw: socket.yaw }),
+    };
+}
+function clonePiece(piece) {
+    return {
+        type: piece.type,
+        sockets: piece.sockets.map(cloneSocket),
+        ...(piece.footprint === undefined ? {} : { footprint: { w: piece.footprint.w, d: piece.footprint.d } }),
+    };
+}
+/**
+ * The grid cells a piece `footprint` centered on `position` (world units) covers, honoring `yaw`
+ * (snapped to the nearest quarter turn). Mirrors `world/footprintGrid`'s `cellsFor` so a game can
+ * feed the result straight into `grid.isFree`/`grid.reserve` after committing a resolved snap —
+ * without this module importing the grid.
+ *
+ * @capability build-footprint-cells grid cells a snapped build piece footprint covers (footprintGrid occupancy bridge)
+ */
+export function footprintCells(position, footprint, yaw = 0, cellSize = 1) {
+    const quarterTurns = Math.round(yaw / (Math.PI / 2));
+    const turned = (((quarterTurns % 2) + 2) % 2) === 1;
+    const cols = Math.max(1, Math.round((turned ? footprint.d : footprint.w) / cellSize));
+    const rows = Math.max(1, Math.round((turned ? footprint.w : footprint.d) / cellSize));
+    const originCol = Math.round(position[0] / cellSize - cols / 2);
+    const originRow = Math.round(position[2] / cellSize - rows / 2);
+    const cells = [];
+    for (let row = 0; row < rows; row += 1) {
+        for (let col = 0; col < cols; col += 1)
+            cells.push({ col: originCol + col, row: originRow + row });
+    }
+    return cells;
+}
+/**
+ * Turn a model's named attach points (from `scene/modelSockets`' `readNamedSockets`) into
+ * {@link SocketDef}s, classifying each into a connection `kind` via `kindOf` and, optionally, an
+ * outward `yaw` via `yawOf`. Lets an artist author snap sockets as empties in a GLB instead of by
+ * hand in the catalog. Pure and structural — no three.js or scene import.
+ *
+ * @capability piece-sockets-from-model derive build-piece snap sockets from a model's named attach points
+ */
+export function pieceSocketsFromModel(sockets, kindOf, yawOf) {
+    return sockets.map((socket) => ({
+        name: socket.name,
+        kind: kindOf(socket.name),
+        position: [socket.offset[0], socket.offset[1], socket.offset[2]],
+        ...(yawOf === undefined ? {} : { yaw: yawOf(socket.name) }),
+    }));
+}
+/**
+ * Build a modular snap catalog from piece definitions and a connection-rule table. Resolves the set
+ * of valid snap transforms when hovering a candidate piece near a placed one: for every compatible
+ * socket pair it computes the world transform that seats the candidate's socket onto the placed
+ * socket, oriented to face back into it. Deterministic ordering (nearest a cursor when given, else
+ * declaration order) and an optional occupancy predicate keep it drop-in for a build-mode controller.
+ *
+ * @capability build-socket-catalog data-driven named-socket snap catalog for modular base building
+ */
+export function createBuildSocketCatalog(config) {
+    const cellSize = config.cellSize ?? 1;
+    const pieces = new Map();
+    const order = [];
+    for (const piece of config.pieces) {
+        const clone = clonePiece(piece);
+        pieces.set(clone.type, clone);
+        order.push(clone.type);
+    }
+    const compatible = new Set();
+    const rules = [];
+    for (const rule of config.rules) {
+        compatible.add(pairKey(rule.a, rule.b));
+        if (rule.mutual !== false)
+            compatible.add(pairKey(rule.b, rule.a));
+        rules.push({ a: rule.a, b: rule.b, ...(rule.mutual === undefined ? {} : { mutual: rule.mutual }) });
+    }
+    const canConnect = (candidateKind, placedKind) => compatible.has(pairKey(candidateKind, placedKind));
+    const worldSockets = (placed) => {
+        const def = pieces.get(placed.type);
+        if (def === undefined)
+            return [];
+        const baseYaw = placed.transform.yaw ?? 0;
+        const origin = placed.transform.position;
+        return def.sockets.map((socket) => {
+            const rotated = rotateY(socket.position, baseYaw);
+            return {
+                name: socket.name,
+                kind: socket.kind,
+                position: [origin[0] + rotated[0], origin[1] + rotated[1], origin[2] + rotated[2]],
+                yaw: baseYaw + (socket.yaw ?? 0),
+            };
+        });
+    };
+    return {
+        cellSize,
+        has(type) {
+            return pieces.has(type);
+        },
+        piece(type) {
+            const def = pieces.get(type);
+            return def === undefined ? null : clonePiece(def);
+        },
+        types() {
+            return order.slice();
+        },
+        canConnect,
+        worldSockets,
+        resolveSnaps(placed, candidateType, options = {}) {
+            const candidateDef = pieces.get(candidateType);
+            if (candidateDef === undefined)
+                return [];
+            const targets = worldSockets(placed);
+            const cursor = options.cursor;
+            const isFree = options.isFree;
+            const out = [];
+            for (const target of targets) {
+                for (const socket of candidateDef.sockets) {
+                    if (!canConnect(socket.kind, target.kind))
+                        continue;
+                    // Seat the candidate socket onto the target: same world point, facing opposite.
+                    const candidateYaw = target.yaw + Math.PI - (socket.yaw ?? 0);
+                    const rotated = rotateY(socket.position, candidateYaw);
+                    const positionX = target.position[0] - rotated[0];
+                    const positionY = target.position[1] - rotated[1];
+                    const positionZ = target.position[2] - rotated[2];
+                    const position = [positionX, positionY, positionZ];
+                    if (isFree !== undefined && candidateDef.footprint !== undefined) {
+                        const cells = footprintCells(position, candidateDef.footprint, candidateYaw, cellSize);
+                        if (!cells.every((cell) => isFree(cell)))
+                            continue;
+                    }
+                    const distance = cursor === undefined
+                        ? 0
+                        : Math.hypot(target.position[0] - cursor[0], target.position[1] - cursor[1], target.position[2] - cursor[2]);
+                    out.push({
+                        candidateType,
+                        targetSocket: target.name,
+                        candidateSocket: socket.name,
+                        transform: { position, yaw: candidateYaw },
+                        point: [target.position[0], target.position[1], target.position[2]],
+                        distance,
+                    });
+                }
+            }
+            // Nearest-first when a cursor is given; Array.sort is stable so equal distances keep
+            // declaration order. Without a cursor the array is already in declaration order.
+            if (cursor !== undefined)
+                out.sort((x, y) => x.distance - y.distance);
+            return out;
+        },
+        toJSON() {
+            return {
+                cellSize,
+                pieces: order.map((type) => clonePiece(pieces.get(type))),
+                rules: rules.map((rule) => ({
+                    a: rule.a,
+                    b: rule.b,
+                    ...(rule.mutual === undefined ? {} : { mutual: rule.mutual }),
+                })),
+            };
+        },
+    };
+}

package/dist/world/buildingLots.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Street-aware building placement: derive building LOTS along ROAD FRONTAGE. Given road segments
+ * (centerline + width) and a district area, walk each road by arc length and emit lots on both
+ * sides at a consistent setback — a curb + sidewalk strip — with each lot carrying the yaw that
+ * makes the building FRONT face its road. Unlike `cityBlocks` (which needs a CLOSED street network
+ * to extract planar block faces), this works on a sparse set of segments — the common authoring
+ * case — so buildings line the streets instead of scattering on plinths around a center point.
+ *
+ * Pure seeded math over `cityGeometry` `Vec2` primitives: no rendering, deterministic from the
+ * inputs, bounded by `maxLots`.
+ *
+ * @capability world-environment lots aligned to and facing road frontage, with a setback sidewalk strip
+ */
+import type { Vec2 } from "./cityGeometry.js";
+import type { WorldBounds } from "./features.js";
+/** One road the frontage placer lines with buildings: a centerline polyline and its full width. */
+export interface RoadFrontage {
+    /** Road centerline vertices in world XZ; at least two points. */
+    path: readonly Vec2[];
+    /** Road full width in world units; lots set back from `width / 2`. */
+    width: number;
+}
+/** Rectangular clip region lots must fall within (world center + half-extents). */
+export interface LotArea {
+    /** World-space center of the region; default `[0, 0]`. */
+    center?: Vec2;
+    /** Half-extents along world x and z. */
+    halfExtents: Vec2;
+}
+/** Options for {@link deriveBuildingLots}. */
+export interface BuildingLotOptions {
+    /** Roads whose frontage is lined with lots. */
+    roads: readonly RoadFrontage[];
+    /** Lot footprint: `w` is frontage width (along the road), `d` is depth (into the block). Default `{ w: 12, d: 10 }`. */
+    footprint?: WorldBounds;
+    /** Gap between neighbouring lots along a frontage, world units. Default 2. */
+    spacing?: number;
+    /** Sidewalk strip between the curb (`width / 2`) and the building front, world units. Default 3. */
+    setback?: number;
+    /** Place lots on both sides of each road. Default true. */
+    bothSides?: boolean;
+    /** Clip region; lots whose center falls outside are dropped. Omit to keep every lot. */
+    area?: LotArea;
+    /**
+     * Seed forwarded by callers for parity with other feature configs. Lot GEOMETRY is fully
+     * determined by the roads and dials (so a layout is identical without it); per-building variation
+     * (floors, massing) is seeded downstream where the lots become buildings.
+     */
+    seed?: string;
+    /** Hard cap on emitted lots so a long network stays bounded. Default 400. */
+    maxLots?: number;
+}
+/** One placed building lot: where a building stands and how it is turned to face its road. */
+export interface PlacedBuildingLot {
+    /** Lot (building footprint) center in world XZ. */
+    center: Vec2;
+    /** Building yaw (radians) so its FRONT (+z local face) points at the road. */
+    rotationY: number;
+    /** Footprint of the lot: `w` along the frontage, `d` into the block. */
+    footprint: WorldBounds;
+    /** Index into the input `roads`. */
+    road: number;
+    /** Which side of the road: +1 = left normal, -1 = right normal. */
+    side: 1 | -1;
+    /** Distance from the lot's front face to the road centerline (= `width / 2 + setback`). */
+    frontDistance: number;
+}
+/**
+ * Yaw that turns the building FRONT (local +z) to face the road. The lot center sits at
+ * `roadPoint + outwardNormal * d`, so the road lies along `-outwardNormal` from the center. In the
+ * engine's Y-rotation convention a local +z of `(0, 1)` maps to world `(sin y, cos y)`; setting
+ * that equal to `-outwardNormal` gives `y = atan2(-nx, -nz)`.
+ * @internal
+ */
+export declare function facingRotation(outwardNormal: Vec2): number;
+/**
+ * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
+ * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
+ * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
+ * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
+ * seed) always yield the identical list.
+ * @capability building-lots derive street-facing building lots from road frontage
+ */
+export declare function deriveBuildingLots(options: BuildingLotOptions): PlacedBuildingLot[];

package/dist/world/buildingLots.js

@@ -0,0 +1,119 @@
+const DEFAULT_FOOTPRINT = { w: 12, d: 10 };
+/** Cumulative arc length of a polyline. */
+function polylineLength(path) {
+    let sum = 0;
+    for (let i = 0; i + 1 < path.length; i += 1) {
+        sum += Math.hypot(path[i + 1][0] - path[i][0], path[i + 1][1] - path[i][1]);
+    }
+    return sum;
+}
+/** Point + unit tangent at arc length `s` along a polyline (clamped to its ends). */
+function stationAt(path, s) {
+    let acc = 0;
+    for (let i = 0; i + 1 < path.length; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        if (len < 1e-9)
+            continue;
+        if (acc + len >= s || i + 2 === path.length) {
+            const t = Math.max(0, Math.min(1, (s - acc) / len));
+            return {
+                p: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
+                tangent: [(b[0] - a[0]) / len, (b[1] - a[1]) / len],
+            };
+        }
+        acc += len;
+    }
+    const a = path[0];
+    return { p: [a[0], a[1]], tangent: [1, 0] };
+}
+function inArea(area, x, z) {
+    if (area === undefined)
+        return true;
+    const [cx, cz] = area.center ?? [0, 0];
+    return Math.abs(x - cx) <= area.halfExtents[0] && Math.abs(z - cz) <= area.halfExtents[1];
+}
+/**
+ * Yaw that turns the building FRONT (local +z) to face the road. The lot center sits at
+ * `roadPoint + outwardNormal * d`, so the road lies along `-outwardNormal` from the center. In the
+ * engine's Y-rotation convention a local +z of `(0, 1)` maps to world `(sin y, cos y)`; setting
+ * that equal to `-outwardNormal` gives `y = atan2(-nx, -nz)`.
+ * @internal
+ */
+export function facingRotation(outwardNormal) {
+    return Math.atan2(-outwardNormal[0], -outwardNormal[1]);
+}
+/**
+ * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
+ * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
+ * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
+ * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
+ * seed) always yield the identical list.
+ * @capability building-lots derive street-facing building lots from road frontage
+ */
+export function deriveBuildingLots(options) {
+    const footprint = options.footprint ?? DEFAULT_FOOTPRINT;
+    const spacing = Math.max(0, options.spacing ?? 2);
+    const setback = Math.max(0, options.setback ?? 3);
+    const bothSides = options.bothSides ?? true;
+    const maxLots = Math.max(0, Math.floor(options.maxLots ?? 400));
+    const step = Math.max(1, footprint.w + spacing);
+    const sides = bothSides ? [1, -1] : [1];
+    // Minimum center separation for cross-road de-dup: half the footprint diagonal, a touch under
+    // the along-road step so same-road neighbours are never rejected.
+    const minSep = Math.min(step * 0.95, Math.hypot(footprint.w, footprint.d) * 0.5);
+    const minSep2 = minSep * minSep;
+    const lots = [];
+    const accepted = [];
+    for (let r = 0; r < options.roads.length && lots.length < maxLots; r += 1) {
+        const road = options.roads[r];
+        if (road.path.length < 2)
+            continue;
+        const total = polylineLength(road.path);
+        if (total < 1e-6)
+            continue;
+        const front = road.width / 2 + setback;
+        const offset = front + footprint.d / 2;
+        // Center the run so lots sit symmetrically and endpoints keep a half-step margin.
+        const count = Math.max(1, Math.floor(total / step));
+        const startS = (total - (count - 1) * step) / 2;
+        for (let i = 0; i < count && lots.length < maxLots; i += 1) {
+            const s = startS + i * step;
+            const station = stationAt(road.path, s);
+            const [tx, tz] = station.tangent;
+            // Left normal of the tangent (CCW): (-tz, tx). Right side negates it.
+            for (const side of sides) {
+                if (lots.length >= maxLots)
+                    break;
+                const nx = -tz * side;
+                const nz = tx * side;
+                const cx = station.p[0] + nx * offset;
+                const cz = station.p[1] + nz * offset;
+                if (!inArea(options.area, cx, cz))
+                    continue;
+                let clash = false;
+                for (const [ax, az] of accepted) {
+                    const dx = ax - cx;
+                    const dz = az - cz;
+                    if (dx * dx + dz * dz < minSep2) {
+                        clash = true;
+                        break;
+                    }
+                }
+                if (clash)
+                    continue;
+                lots.push({
+                    center: [cx, cz],
+                    rotationY: facingRotation([nx, nz]),
+                    footprint: { w: footprint.w, d: footprint.d },
+                    road: r,
+                    side,
+                    frontDistance: front,
+                });
+                accepted.push([cx, cz]);
+            }
+        }
+    }
+    return lots;
+}

package/dist/world/buildings.d.ts

@@ -72,6 +72,12 @@ export interface GeneratedBuilding {
     floorHeight: number;
     bounds: Aabb;
     parts: readonly BuildingPartPlacement[];
+    /**
+     * Optional building yaw (radians) about `center`, applied by the renderer to the whole massing —
+     * used by street-aware placement to turn a building's front to face its road. Absent/0 keeps the
+     * axis-aligned grid orientation.
+     */
+    rotationY?: number;
 }
 export interface BuildingLot {
     id: string;

package/dist/world/cityBlocks.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { type Vec2 } from "./cityGeometry.js";
+/** How a block (a face of the road graph) is used. */
+export type CityBlockKind = "buildable" | "park" | "plaza" | "field" | "buffer";
+/** One closed block: a face of the road network, inset to its curb and land boundaries. */
+export interface CityBlockLocal {
+    id: string;
+    /** Face polygon on road CENTERLINES (CCW) — the raw graph face. */
+    face: Vec2[];
+    /** Street index bordering each face edge (edge i = face[i]→face[i+1]); -1 = district boundary. */
+    faceStreets: number[];
+    /** Pavement edge: face inset by each bordering road's half width (+ curb margin). */
+    curb: Vec2[];
+    /** Land edge: curb inset further by the sidewalk band where the bordering street has one. */
+    polygon: Vec2[];
+    kind: CityBlockKind;
+    area: number;
+}
+/** One street-frontage reference of a parcel. */
+export interface CityParcelFrontage {
+    /** Index into the resolved city's street list. */
+    street: number;
+    /** Frontage chord endpoints on the parcel boundary. */
+    edgeStart: Vec2;
+    edgeEnd: Vec2;
+    /** Unit tangent along the frontage chord. */
+    tangent: Vec2;
+}
+/** How a parcel is used after occupancy/fitting rolls. */
+export type CityParcelKind = "built" | "vacant" | "yard";
+/** One polygonal parcel subdivided out of a block's street frontage. */
+export interface CityParcelLocal {
+    id: string;
+    block: number;
+    polygon: Vec2[];
+    /** Buildable polygon after front/side/rear setbacks; [] when setbacks consume the parcel. */
+    buildable: Vec2[];
+    frontage: CityParcelFrontage[];
+    area: number;
+    /** Usable depth from the frontage chord to the parcel rear. */
+    depth: number;
+    isCorner: boolean;
+    kind: CityParcelKind;
+}
+/** Minimal street shape the fabric needs (matches cityKind's LocalStreet). */
+export interface FabricStreet {
+    points: readonly (readonly [number, number])[];
+    width: number;
+    level: "boulevard" | "avenue" | "street" | "lane";
+    sidewalk: boolean;
+}
+/** Sidewalk band width by street hierarchy (base = the district's street-level width). */
+export declare function sidewalkWidthFor(level: FabricStreet["level"], base: number): number;
+/** One extracted face: closed centerline polygon + the street index along each polygon edge. */
+export interface GraphFace {
+    polygon: Vec2[];
+    streets: number[];
+}
+/** Everything block extraction needs from the district rules. */
+export interface FabricParams {
+    streetWidthBase: number;
+    /** Base sidewalk band width in meters at "street" hierarchy level. */
+    sidewalkBase: number;
+    /** Curb strip between pavement edge and sidewalk, meters. */
+    curbMargin: number;
+}
+/** A block's derived rings plus the sidewalk band (outer = curb line, inner = land line). */
+export interface BlockRings {
+    face: Vec2[];
+    faceStreets: number[];
+    curb: Vec2[];
+    land: Vec2[];
+}
+/**
+ * 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 declare function extractBlocks(streets: readonly FabricStreet[], hx: number, hz: number, params: FabricParams): {
+    blocks: BlockRings[];
+    deadEnds: {
+        pts: Vec2[];
+        width: number;
+    }[];
+};
+/** Arc-length station lookup along a closed ring. */
+export declare class RingWalker {
+    readonly ring: readonly Vec2[];
+    readonly cum: number[];
+    readonly total: number;
+    constructor(ring: readonly Vec2[]);
+    /** Point, unit tangent, and inward normal (CCW ring: interior on the left) at arc length `s`. */
+    at(s: number): {
+        p: Vec2;
+        tangent: Vec2;
+        normal: Vec2;
+        edge: number;
+    };
+    /** Ring vertex indices whose arc position lies strictly inside (s0, s1) (wrapping). */
+    verticesBetween(s0: number, s1: number): number[];
+    /** Interior angle (radians) at ring vertex i — π on straight runs, < π at convex corners. */
+    interiorAngle(i: number): number;
+}
+/** Inputs for one parcel strip cut from a block ring. */
+export interface ParcelCut {
+    /** Arc-length start/end stations along the block's land ring. */
+    s0: number;
+    s1: number;
+    /** Strip depth from the frontage inward. */
+    depth: number;
+}
+/**
+ * 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 declare function cutParcel(walker: RingWalker, blockRing: readonly Vec2[], cut: ParcelCut): Vec2[] | null;
+/**
+ * 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 declare function conformPolygonToRing(poly: readonly Vec2[], ring: readonly Vec2[]): Vec2[];
+/**
+ * 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 declare function buildablePolygon(parcel: readonly Vec2[], frontA: Vec2, frontB: Vec2, frontSetback: number, sideGap: number, rearMargin: number, depth: number): Vec2[];
+/**
+ * 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 declare function carveCorridors(poly: Vec2[], keep: Vec2, corridors: readonly {
+    pts: readonly Vec2[];
+    width: number;
+}[], margin: number): Vec2[];
+/** Deterministic sliver verdict shared by classification and tests. */
+export declare function isSliverBlock(land: readonly Vec2[], minArea: number, minWidth: number): boolean;
+/** Sample deterministic points inside a polygon by seeded rejection over its bounds. */
+export declare function pointsInPolygon(ring: readonly Vec2[], count: number, rng: () => number, margin?: number): Vec2[];