@jgengine/core 0.14.0 → 0.15.0

package/dist/world/buildingLots.js

@@ -1,4 +1,39 @@
+/**
+ * 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 { rectClearsPolyline, rectsSeparated } from "./cityGeometry.js";
+import { seededStreams } from "../random/rng.js";
 const DEFAULT_FOOTPRINT = { w: 12, d: 10 };
+/**
+ * Frontage-fill reference point: at this dial value the compaction is a no-op (legacy spacing/width),
+ * so callers can leave `blockFill` unset for the classic look and this value reproduces it exactly.
+ */
+export const FRONTAGE_FILL_REFERENCE = 0.45;
+/** Modest extra frontage-width growth applied at full fill so consecutive lots touch (edge-to-edge). */
+const FRONTAGE_WIDTH_OVERFILL = 0.1;
+/**
+ * Map a `blockFill` dial to frontage compaction factors. `undefined` ⇒ identity (legacy path stays
+ * byte-identical). At {@link FRONTAGE_FILL_REFERENCE} the factors are exactly `{1, 1}`; toward 1 the
+ * gap collapses and lots widen, toward 0 the gap grows (sparser than default). @internal
+ */
+export function frontageCompaction(blockFill) {
+    if (blockFill === undefined)
+        return { spacingScale: 1, widthScale: 1 };
+    const f = Math.max(0, Math.min(1, blockFill));
+    const spacingScale = (1 - f) / (1 - FRONTAGE_FILL_REFERENCE);
+    const widthScale = 1 + (Math.max(0, f - FRONTAGE_FILL_REFERENCE) / (1 - FRONTAGE_FILL_REFERENCE)) * FRONTAGE_WIDTH_OVERFILL;
+    return { spacingScale, widthScale };
+}
 /** Cumulative arc length of a polyline. */
 function polylineLength(path) {
     let sum = 0;
@@ -45,27 +80,59 @@ 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.
+ * Derive street-aligned building lots (PLOTS) from road frontage. Each side of each road walks the
+ * frontage placing plots at `plot.w + spacing` pitch — rolling the next plot size from the weighted
+ * `footprint` variants when several are given — offset outward by `width / 2 + setback + plot.d / 2`
+ * and turned to face the road. The PLOT CONTRACT is enforced here, exactly: no two plots ever overlap
+ * (true oriented-rect separation with the spacing gap, so corners and curved frontage can't stack
+ * buildings), and no plot footprint ever touches any road corridor in `roads` or `avoid` — not
+ * just its own frontage road. 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 raw = options.footprint ?? DEFAULT_FOOTPRINT;
+    // `blockFill` compaction: widen each lot's frontage and shrink the along-road gap toward a
+    // Manhattan streetwall as the dial rises. Undefined ⇒ identity, so the classic path is untouched.
+    // Compaction composes with plot variants — every variant's frontage widens by the same factor.
+    const { spacingScale, widthScale } = frontageCompaction(options.blockFill);
+    const variants = (Array.isArray(raw) ? raw : [raw])
+        .filter((v) => v.w > 0.5 && v.d > 0.5)
+        .map((v) => ({ w: v.w * widthScale, d: v.d, weight: Math.max(0, v.weight ?? 1) }));
+    if (variants.length === 0)
+        variants.push({ ...DEFAULT_FOOTPRINT, weight: 1 });
+    const totalWeight = variants.reduce((sum, v) => sum + v.weight, 0) || 1;
+    const pickVariant = (roll) => {
+        let cursor = roll * totalWeight;
+        for (const v of variants) {
+            cursor -= v.weight;
+            if (cursor <= 0)
+                return v;
+        }
+        return variants[0];
+    };
+    const spacing = Math.max(0, options.spacing ?? 2) * spacingScale;
     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 streams = seededStreams(`plots:${options.seed ?? ""}`);
     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 corridors = [];
+    for (const road of options.roads)
+        corridors.push({ path: road.path, half: road.width / 2 });
+    for (const road of options.avoid ?? [])
+        corridors.push({ path: road.path, half: road.width / 2 });
     const lots = [];
     const accepted = [];
+    // Gap grown onto the candidate for the plot-vs-plot separation test. Just under half the
+    // spacing keeps same-road neighbours (spaced exactly `spacing` apart) accepted while anything
+    // closer — corner stacking, inside-of-curve pinches — is rejected. At `spacing` 0 the gap goes
+    // slightly NEGATIVE (a shrink), so exactly-touching plots (terraces, rowhouse walls) are legal:
+    // touching is a valid look, overlapping never is.
+    const gap = spacing * 0.45 - 0.05;
+    // Plots may touch the asphalt edge but never intrude into it; the tiny epsilon keeps an exact
+    // setback-0 front face (touching the corridor boundary) legal.
+    const roadClearanceSlack = 0.02;
     for (let r = 0; r < options.roads.length && lots.length < maxLots; r += 1) {
         const road = options.roads[r];
         if (road.path.length < 2)
@@ -74,44 +141,63 @@ export function deriveBuildingLots(options) {
         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)
+        // Each side walks its own seeded cursor so variant runs differ across the street — terraces
+        // can face detached houses. With a single variant the walk degenerates to the fixed pitch.
+        for (const side of sides) {
+            const roll = variants.length > 1 ? streams(`road:${r}:side:${side}`) : null;
+            let cursor = spacing / 2 + 0.5;
+            while (cursor < total && lots.length < maxLots) {
+                const plot = roll === null ? variants[0] : pickVariant(roll());
+                if (cursor + plot.w > total - 0.5)
                     break;
+                const s = cursor + plot.w / 2;
+                cursor += plot.w + spacing;
+                const station = stationAt(road.path, s);
+                const [tx, tz] = station.tangent;
+                // Left normal of the tangent (CCW): (-tz, tx). Right side negates it.
                 const nx = -tz * side;
                 const nz = tx * side;
+                const offset = front + plot.d / 2;
                 const cx = station.p[0] + nx * offset;
                 const cz = station.p[1] + nz * offset;
                 if (!inArea(options.area, cx, cz))
                     continue;
+                const rotationY = facingRotation([nx, nz]);
+                const hw = plot.w / 2;
+                const hd = plot.d / 2;
+                const rect = { x: cx, z: cz, hw, hd, angle: rotationY };
+                // Plot-vs-plot: reject any candidate whose rect (grown by the spacing gap) overlaps an
+                // accepted plot — regardless of which road placed it.
+                const grown = { ...rect, hw: hw + gap, hd: hd + gap };
                 let clash = false;
-                for (const [ax, az] of accepted) {
-                    const dx = ax - cx;
-                    const dz = az - cz;
-                    if (dx * dx + dz * dz < minSep2) {
+                for (const other of accepted) {
+                    if (!rectsSeparated(grown, other)) {
                         clash = true;
                         break;
                     }
                 }
                 if (clash)
                     continue;
+                // Plot-vs-road: the full footprint stays off every corridor (frontage roads AND avoid
+                // corridors), so a plot can never straddle a crossing street.
+                let onRoad = false;
+                for (const corridor of corridors) {
+                    if (!rectClearsPolyline(rect, corridor.path, corridor.half - roadClearanceSlack)) {
+                        onRoad = true;
+                        break;
+                    }
+                }
+                if (onRoad)
+                    continue;
                 lots.push({
                     center: [cx, cz],
-                    rotationY: facingRotation([nx, nz]),
-                    footprint: { w: footprint.w, d: footprint.d },
+                    rotationY,
+                    footprint: { w: plot.w, d: plot.d },
                     road: r,
                     side,
                     frontDistance: front,
                 });
-                accepted.push([cx, cz]);
+                accepted.push(rect);
             }
         }
     }

package/dist/world/cityBlocks.d.ts

@@ -94,6 +94,51 @@ export declare function extractBlocks(streets: readonly FabricStreet[], hx: numb
         width: number;
     }[];
 };
+/** Minimal node/edge shapes {@link extractGraphBlocks} needs (matches `StreetNetwork.nodes`/`edges`). */
+export interface GraphBlockNode {
+    x: number;
+    z: number;
+}
+/** One street-graph edge {@link extractGraphBlocks} traces block faces through. */
+export interface GraphBlockEdge {
+    /** Endpoint node indices. `points[0]` sits exactly on node `a`, the last on node `b`. */
+    a: number;
+    b: number;
+    points: readonly (readonly [number, number])[];
+    width: number;
+    level: FabricStreet["level"];
+    /** Owning street index, carried through to pruned dead-end corridors so callers can line them. */
+    street?: number;
+}
+/** One block from {@link extractGraphBlocks}: the face polygon and its inset land ring. */
+export interface GraphBlockRings {
+    /** Face polygon on road CENTERLINES (as traced, interior faces CCW). */
+    face: Vec2[];
+    /** Land ring: face inset by each bordering edge's half width + curb margin + sidewalk band. */
+    land: Vec2[];
+}
+/**
+ * Extract closed blocks from an EXACT street graph — the `nodes`/`edges` a street network already
+ * carries — instead of re-deriving topology from welded polylines. Half-edges are ordered by true
+ * departure angle at each node, dangling chains are pruned first (returned as `deadEnds` for
+ * corridor carving), interior faces are traced through the rotation system, and each face is inset
+ * to its land ring by the bordering edges' half-widths (+ curb + sidewalk). Robust against wandered
+ * and arc-filleted centerlines, which defeat proximity welding. Pure bounded geometry.
+ *
+ * @capability city-district extract block polygons directly from a street network's exact graph
+ */
+export declare function extractGraphBlocks(nodes: readonly GraphBlockNode[], edges: readonly GraphBlockEdge[], params: {
+    sidewalkBase: number;
+    curbMargin: number;
+}): {
+    blocks: GraphBlockRings[];
+    deadEnds: {
+        pts: Vec2[];
+        width: number;
+        level: FabricStreet["level"];
+        street?: number;
+    }[];
+};
 /** Arc-length station lookup along a closed ring. */
 export declare class RingWalker {
     readonly ring: readonly Vec2[];

package/dist/world/cityBlocks.js

@@ -11,8 +11,20 @@
  * @capability city-district road-derived block polygons, parcel subdivision, buildable footprints
  */
 import { clipHalfPlane, dedupeRing, distanceToRing, ensureCcw, extractSimpleLoop, insetRing, pointInPolygon, polygonArea, polygonMeanWidth, polygonSignedArea, } from "./cityGeometry.js";
+import { isProductionEnvironment } from "../devtools/saveEndpoint.js";
 const MAX_BLOCKS = 420;
 const WELD_RADIUS = 1.4;
+// Proximity welding (WELD_RADIUS) assumes near-collinear / aligned centerlines. Wandered and
+// arc-filleted streets weld into a degenerate face set: a real case went 38 streets → 2 faces
+// with no signal. These constants gate a dev-mode collapse warning. A connected road grid has
+// bounded faces on the order of its street count (Euler: bounded faces = edges − nodes + 1), so
+// faces far below the street count means welding ate the topology, not that the district is sparse.
+// COLLAPSE_MIN_STREETS avoids false positives on genuinely tiny inputs (a handful of crossings
+// legitimately yields few faces); COLLAPSE_RATIO_DIVISOR flags only a gross collapse — with 8
+// streets it fires under 2 faces, with 38 streets under 9 (the 38 → 2 case triggers, a healthy
+// grid where faces ≥ street count never does).
+const COLLAPSE_MIN_STREETS = 8;
+const COLLAPSE_RATIO_DIVISOR = 4;
 const RIM_SNAP = 6;
 /** Sidewalk band width by street hierarchy (base = the district's street-level width). */
 export function sidewalkWidthFor(level, base) {
@@ -346,6 +358,7 @@ function extractFaces(nodes, halves) {
 export function extractBlocks(streets, hx, hz, params) {
     const { nodes, halves, deadEnds } = buildGraph(streets, hx, hz);
     const faces = extractFaces(nodes, halves);
+    warnOnImplausibleCollapse(streets.length, faces.length);
     faces.sort((a, b) => polygonArea(b.polygon) - polygonArea(a.polygon));
     const blocks = [];
     for (const face of faces) {
@@ -391,6 +404,26 @@ export function extractBlocks(streets, hx, hz, params) {
     }
     return { blocks, deadEnds };
 }
+/**
+ * Dev-mode guard: warn when {@link extractBlocks} extracts implausibly few faces for the street
+ * count — the silent-collapse failure mode where proximity welding folds wandered / arc-filleted
+ * centerlines into a degenerate face set (see issue #1502: 38 streets → 2 faces). No-ops in a
+ * production build. Points at {@link extractGraphBlocks}, which traces faces from the exact street
+ * graph and is robust against the centerlines that defeat welding.
+ */
+function warnOnImplausibleCollapse(streetCount, faceCount) {
+    if (isProductionEnvironment() || typeof console === "undefined")
+        return;
+    if (streetCount < COLLAPSE_MIN_STREETS)
+        return;
+    if (faceCount >= streetCount / COLLAPSE_RATIO_DIVISOR)
+        return;
+    console.warn(`[jgengine:extractBlocks] ${streetCount} streets extracted only ${faceCount} block face(s) — ` +
+        "implausibly few, likely a silent proximity-welding collapse on wandered / arc-filleted " +
+        "centerlines (the WELD_RADIUS heuristic assumes near-aligned streets). The fabric will look " +
+        "empty rather than error. Trace blocks from the exact street graph with extractGraphBlocks() " +
+        "instead, which is robust against centerlines that defeat welding.");
+}
 /** Reverse per-edge street labels when a ring got rewound to CCW. */
 function remapReversedEdgeStreets(streetsPerEdge) {
     const n = streetsPerEdge.length;
@@ -400,6 +433,132 @@ function remapReversedEdgeStreets(streetsPerEdge) {
         out[i] = streetsPerEdge[(2 * n - 2 - i) % n];
     return out;
 }
+/**
+ * Extract closed blocks from an EXACT street graph — the `nodes`/`edges` a street network already
+ * carries — instead of re-deriving topology from welded polylines. Half-edges are ordered by true
+ * departure angle at each node, dangling chains are pruned first (returned as `deadEnds` for
+ * corridor carving), interior faces are traced through the rotation system, and each face is inset
+ * to its land ring by the bordering edges' half-widths (+ curb + sidewalk). Robust against wandered
+ * and arc-filleted centerlines, which defeat proximity welding. Pure bounded geometry.
+ *
+ * @capability city-district extract block polygons directly from a street network's exact graph
+ */
+export function extractGraphBlocks(nodes, edges, params) {
+    // --- prune dangling chains: an edge touching a degree-1 node can't border a closed face ---
+    const degree = new Array(nodes.length).fill(0);
+    const alive = edges.map((e) => e.a !== e.b && e.points.length >= 2);
+    edges.forEach((e, i) => {
+        if (!alive[i])
+            return;
+        degree[e.a] += 1;
+        degree[e.b] += 1;
+    });
+    const deadEnds = [];
+    let pruned = true;
+    while (pruned) {
+        pruned = false;
+        for (let i = 0; i < edges.length; i += 1) {
+            if (!alive[i])
+                continue;
+            const e = edges[i];
+            if (degree[e.a] === 1 || degree[e.b] === 1) {
+                alive[i] = false;
+                deadEnds.push({ pts: e.points.map((p) => [p[0], p[1]]), width: e.width, level: e.level, street: e.street });
+                degree[e.a] -= 1;
+                degree[e.b] -= 1;
+                pruned = true;
+            }
+        }
+    }
+    const halves = [];
+    const out = nodes.map(() => []);
+    const departAngle = (pts) => {
+        // First non-degenerate segment sets the true departure direction.
+        for (let i = 1; i < pts.length; i += 1) {
+            const dx = pts[i][0] - pts[0][0];
+            const dz = pts[i][1] - pts[0][1];
+            if (dx * dx + dz * dz > 1e-12)
+                return Math.atan2(dz, dx);
+        }
+        return 0;
+    };
+    const angles = [];
+    edges.forEach((e, ei) => {
+        if (!alive[ei])
+            return;
+        const fwd = e.points.map((p) => [p[0], p[1]]);
+        const rev = [...fwd].reverse();
+        const h0 = halves.length;
+        halves.push({ to: e.b, pts: fwd, twin: h0 + 1, edge: ei, visited: false });
+        halves.push({ to: e.a, pts: rev, twin: h0, edge: ei, visited: false });
+        angles.push(departAngle(fwd), departAngle(rev));
+        out[e.a].push(h0);
+        out[e.b].push(h0 + 1);
+    });
+    for (const list of out)
+        list.sort((a, b) => angles[a] - angles[b]);
+    // --- trace interior faces: at each destination, rotate clockwise from the twin ---
+    const blocks = [];
+    for (let start = 0; start < halves.length && blocks.length < MAX_BLOCKS; start += 1) {
+        if (halves[start].visited)
+            continue;
+        const polygon = [];
+        const segEdge = [];
+        let current = start;
+        let guard = 0;
+        let closed = false;
+        while (guard < halves.length + 4) {
+            guard += 1;
+            const half = halves[current];
+            if (half.visited)
+                break;
+            half.visited = true;
+            for (let i = 0; i + 1 < half.pts.length; i += 1) {
+                polygon.push(half.pts[i]);
+                segEdge.push(half.edge);
+            }
+            const list = out[half.to];
+            const idx = list.indexOf(half.twin);
+            if (idx < 0)
+                break;
+            current = list[(idx - 1 + list.length) % list.length];
+            if (current === start) {
+                closed = true;
+                break;
+            }
+        }
+        if (!closed || polygon.length < 3)
+            continue;
+        if (polygonSignedArea(polygon) <= 1)
+            continue; // outer face (CW) or degenerate sliver
+        // Dedupe near-coincident vertices while keeping each surviving segment's source edge.
+        const ring = [];
+        const ringEdge = [];
+        for (let i = 0; i < polygon.length; i += 1) {
+            const p = polygon[i];
+            const prev = ring[ring.length - 1];
+            if (prev !== undefined && Math.hypot(prev[0] - p[0], prev[1] - p[1]) < 0.02)
+                continue;
+            ring.push(p);
+            ringEdge.push(segEdge[i]);
+        }
+        while (ring.length > 1 && Math.hypot(ring[0][0] - ring[ring.length - 1][0], ring[0][1] - ring[ring.length - 1][1]) < 0.02) {
+            ring.pop();
+            ringEdge.pop();
+        }
+        if (ring.length < 3)
+            continue;
+        const dist = ring.map((_, i) => {
+            const e = edges[ringEdge[i]];
+            const walk = e.level === "lane" ? 0 : sidewalkWidthFor(e.level, params.sidewalkBase);
+            return e.width / 2 + params.curbMargin + walk;
+        });
+        const land = insetRing(ring, dist);
+        blocks.push({ face: ring, land });
+    }
+    blocks.sort((a, b) => polygonArea(b.land) - polygonArea(a.land));
+    return { blocks, deadEnds };
+}
 /** Arc-length station lookup along a closed ring. */
 export class RingWalker {
     ring;

package/dist/world/cityContent.d.ts

@@ -14,6 +14,15 @@ import type { WeightedParamEntry } from "../scene/sceneKinds.js";
 export type CityLotClass = "tower" | "slab" | "shop" | "rowhouse" | "house" | "mansion" | "farmhouse" | "barn" | "silo";
 /** All classes, for schema hints and validation. */
 export declare const CITY_LOT_CLASSES: readonly CityLotClass[];
+/**
+ * Filler classes used ONLY by the block-interior fill pass (`resolveCityLotContent` at a high
+ * `blockFill`). They are deliberately kept OUT of {@link CITY_LOT_CLASSES} so a zone mix can never
+ * weight them onto street frontage — they exist to pack the backs of Manhattan-style blocks with
+ * parking structures and warehouses/depots, mixed in with ordinary zone classes.
+ */
+export type CityFillerClass = "garage" | "depot";
+/** All filler classes, for validation and interior-pass allow-lists. */
+export declare const CITY_FILLER_CLASSES: readonly CityFillerClass[];
 /** Zone band a lot falls in: dense core, middle ring, or the district edge. */
 export type CityZoneBand = "core" | "mid" | "edge";
 /** How the radial zone metric maps to bands. */
@@ -37,6 +46,11 @@ export interface CityLotPiece {
     /** Banded walls receive the window-strip treatment in the renderer. */
     banded: boolean;
 }
+/**
+ * Natural frontage-width range (meters) of a class's massing — what the plot-size class bias reads
+ * so towers land on wide plots and rowhouses on narrow ones. @internal
+ */
+export declare function classWidthRange(cls: string): readonly [number, number] | undefined;
 /** Placement numbers a resolved lot carries out of the class profile. @internal */
 export interface ClassPlacement {
     width: number;
@@ -52,7 +66,16 @@ export interface ClassPlacement {
  * aligned building wall; spacing likewise, so neighbors form rhythmic rows instead of scatter.
  * @internal
  */
-export declare function rollClassPlacement(cls: CityLotClass, rng: () => number, lotScale: number, floorsMin: number, floorsMax: number, setbackBase: number, spacingBase: number): ClassPlacement;
+export declare function rollClassPlacement(cls: CityLotClass | CityFillerClass, rng: () => number, lotScale: number, floorsMin: number, floorsMax: number, setbackBase: number, spacingBase: number, widthStretch?: number): ClassPlacement;
+/**
+ * Weight multiplier favouring classes whose natural frontage fits a plot of width `plotW`: a class
+ * far wider than the plot (a tower profile on a 6 m slice) is heavily downweighted, a class that
+ * would rattle around a much wider plot is mildly downweighted, and anything whose width range
+ * genuinely fits keeps weight 1. Pure data over {@link CLASS_PROFILES} — this is what turns a
+ * mixed-plot frontage into terraces on the slices and detached houses on the wide parcels.
+ * @internal
+ */
+export declare function classPlotFit(cls: CityLotClass, plotW: number): number;
 /**
  * Normalized zone metric for a point in district-local space: 0 at the center line, 1 at the rim,
  * shaped to the district's rectangle (Chebyshev) so bands follow the volume's footprint.
@@ -68,7 +91,28 @@ export declare function pickClass(mix: readonly WeightedParamEntry[], roll: numb
  * floors, and stream always yield the identical silhouette. Sizes are in meters, lot-local.
  * @internal
  */
-export declare function buildLotPieces(cls: CityLotClass, width: number, depth: number, floors: number, floorHeight: number, rng: () => number): CityLotPiece[];
+export declare function buildLotPieces(cls: CityLotClass | CityFillerClass, width: number, depth: number, floors: number, floorHeight: number, rng: () => number): CityLotPiece[];
+/**
+ * A block-scale landmark class. Unlike {@link CityLotClass} these are never weighted into a zone
+ * mix — the landmark pass in `resolveCityLotContent` picks clusters of adjacent lots and stamps one
+ * of these over them. Each expresses with the same four piece shapes (box/gable/cylinder/dome) at a
+ * much larger footprint (~40–90 m).
+ */
+export type CityLandmarkClass = "hall" | "arena" | "market" | "campus";
+/** All landmark classes, for schema hints, validation, and default allow-lists. */
+export declare const CITY_LANDMARK_CLASSES: readonly CityLandmarkClass[];
+/** Minimum depth-into-block factor for a landmark class (the pass grows shallow clusters to this). @internal */
+export declare function landmarkMinDepthFactor(cls: CityLandmarkClass): number;
+/** Roll a landmark's floor count from its profile range. @internal */
+export declare function landmarkFloors(cls: CityLandmarkClass, rng: () => number): number;
+/**
+ * Compose the massing pieces for one landmark parcel, filling the given `width`×`depth` footprint
+ * (lot-local, x along frontage, z into the block). Deterministic per `rng`. Every piece is kept
+ * inside the `[-width/2, width/2] × [-depth/2, depth/2]` box so the reported footprint matches the
+ * merged cluster's AABB. Sizes are in meters.
+ * @internal
+ */
+export declare function buildLandmarkPieces(cls: CityLandmarkClass, width: number, depth: number, floors: number, floorHeight: number, rng: () => number): CityLotPiece[];
 /** Tree species a district's tree mix can weight — the renderer keeps one canopy mesh per species. */
 export type CityTreeSpecies = "broadleaf" | "conifer" | "palm" | "cypress";
 /** All species, for schema hints and validation. */