@jgengine/core 0.10.0 → 0.12.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/buildingGenerator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { type GeneratedAsset } from "../scene/assetGenerator.js";
+import type { ParamSchema, ParsedParams } from "../scene/sceneKinds.js";
+/** The generator id a catalog entry / placed marker references. */
+export declare const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export declare const BUILDING_GENERATOR_SCHEMA: ParamSchema;
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export declare function generateBuildingAsset(params: ParsedParams, seed: string): GeneratedAsset;
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerBuildingGenerator(): void;

package/dist/world/buildingGenerator.js

@@ -0,0 +1,62 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { registerAssetGenerator, partsBounds } from "../scene/assetGenerator.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, generateBuilding, resolveBuildingPalette } from "./buildings.js";
+/** The generator id a catalog entry / placed marker references. */
+export const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export const BUILDING_GENERATOR_SCHEMA = {
+    fields: [
+        { type: "range", key: "floors", label: "floors", min: 1, max: 20, step: 1, default: DEFAULT_BUILDING_CONFIG.floors },
+        { type: "range", key: "baysWide", label: "bays wide", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysWide },
+        { type: "range", key: "baysDeep", label: "bays deep", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysDeep },
+        { type: "range", key: "bayWidth", label: "bay width", min: 1, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.bayWidth, unit: "m" },
+        { type: "range", key: "floorHeight", label: "floor height", min: 2, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.floorHeight, unit: "m" },
+        {
+            type: "select",
+            key: "style",
+            label: "style",
+            default: "generic",
+            options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
+        },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export function generateBuildingAsset(params, seed) {
+    const style = params["style"];
+    const palette = resolveBuildingPalette(style);
+    const building = generateBuilding({
+        seed,
+        center: [0, 0],
+        floors: params["floors"],
+        baysWide: params["baysWide"],
+        baysDeep: params["baysDeep"],
+        bayWidth: params["bayWidth"],
+        floorHeight: params["floorHeight"],
+    });
+    const parts = building.parts.map((part) => ({
+        id: part.id,
+        kind: part.kind,
+        position: part.position,
+        size: part.scale,
+        rotationY: part.rotationY,
+        color: palette[part.kind],
+    }));
+    return { parts, bounds: partsBounds(parts) };
+}
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerBuildingGenerator() {
+    registerAssetGenerator({
+        id: BUILDING_GENERATOR_ID,
+        label: "Building",
+        schema: BUILDING_GENERATOR_SCHEMA,
+        generate: generateBuildingAsset,
+    });
+}

package/dist/world/buildings.d.ts

@@ -97,8 +97,13 @@ export type BuildingPaletteOverrides = Partial<BuildingPalette>;
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
+/** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
+/** @internal */
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
+/** @internal */
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
+/** @internal */
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
+/** @internal */
 export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -176,6 +176,7 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
     if (preset === undefined) {
@@ -228,6 +229,7 @@ function rangeInt(seed, key, min, max) {
     const hi = Math.max(min, max);
     return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
 }
+/** @internal */
 export function createBuildingConfig(input = {}) {
     return {
         id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
@@ -406,6 +408,7 @@ function pushCorners(parts, config, width, depth) {
         parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
     });
 }
+/** @internal */
 export function generateBuilding(input = {}) {
     const config = createBuildingConfig(input);
     const width = config.baysWide * config.bayWidth;
@@ -429,6 +432,7 @@ export function generateBuilding(input = {}) {
         parts,
     };
 }
+/** @internal */
 export function createBuildingGrid(config) {
     const rows = positiveInt(config.rows, 1);
     const columns = positiveInt(config.columns, 1);
@@ -467,6 +471,7 @@ export function createBuildingGrid(config) {
     }
     return lots;
 }
+/** @internal */
 export function generateBuildingDistrict(config) {
     return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
 }

package/dist/world/catenary.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+export type { Vec3 } from "./geometry.js";
+import type { Vec3 } from "./geometry.js";
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export declare function sagCurve(a: Vec3, b: Vec3, sag: number, segments: number): Vec3[];
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export declare function catenaryCurve(a: Vec3, b: Vec3, slack: number, segments: number): Vec3[];

package/dist/world/catenary.js

@@ -0,0 +1,69 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export function sagCurve(a, b, sag, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const cx = (a[0] + b[0]) / 2;
+    const cy = (a[1] + b[1]) / 2 - 2 * sag;
+    const cz = (a[2] + b[2]) / 2;
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const u = 1 - t;
+        const w0 = u * u;
+        const w1 = 2 * u * t;
+        const w2 = t * t;
+        points.push([w0 * a[0] + w1 * cx + w2 * b[0], w0 * a[1] + w1 * cy + w2 * b[1], w0 * a[2] + w1 * cz + w2 * b[2]]);
+    }
+    return points;
+}
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export function catenaryCurve(a, b, slack, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const dx = b[0] - a[0];
+    const dz = b[2] - a[2];
+    const horizontal = Math.hypot(dx, dz);
+    if (horizontal < 1e-4 || slack <= 0)
+        return sagCurve(a, b, Math.max(0, slack) * horizontal * 0.5, steps);
+    const length = horizontal * (1 + slack);
+    // Solve the catenary parameter `p` (= a in y=p·cosh(x/p)) for the required arc length via bisection.
+    const targetRatio = length / horizontal;
+    let lo = 1e-3;
+    let hi = 1e6;
+    for (let i = 0; i < 48; i += 1) {
+        const mid = (lo + hi) / 2;
+        const ratio = (2 * mid * Math.sinh(horizontal / (2 * mid))) / horizontal;
+        if (ratio > targetRatio)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const p = (lo + hi) / 2;
+    const edge = p * Math.cosh(horizontal / (2 * p));
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const x = a[0] + dx * t;
+        const z = a[2] + dz * t;
+        // Local horizontal coordinate centered at mid-span → catenary drop below the chord (0 at ends).
+        const local = (t - 0.5) * horizontal;
+        const drop = p * Math.cosh(local / p) - edge;
+        const chordY = a[1] + (b[1] - a[1]) * t;
+        points.push([x, chordY + drop, z]);
+    }
+    return points;
+}

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[];