@jgengine/core 0.10.0 → 0.12.0

package/dist/world/cityKind.js

@@ -0,0 +1,1578 @@
+/**
+ * `city` studio: a procedural district authored as a box volume — drop a volume and sliders tune
+ * the whole synthesis, from a rigid Manhattan grid (`gridness` 1, `curviness` 0) to winding
+ * hillside estates, a two-road crossroads farm town, or — at the loopiness-high / branching-and-
+ * connectivity-low corner — a closed RACE CIRCUIT. Streets come from the unified seed-driven
+ * {@link buildPathNetwork} engine (city and track are the same generator at opposite slider
+ * extremes), carry a visible hierarchy (boulevards with medians, avenues, streets, lanes —
+ * optionally gravel), and connect or deliberately dead-end into cul-de-sac bulbs; water gaps become
+ * styled bridge decks and ridges become tunnel bores, both path features on continuous streets so a
+ * lap stays closed. The block/parcel/building FABRIC is optional (`fabric` off = bare roads or a
+ * plot-free track). Generation is BLOCK-FIRST (`cityBlocks`): the street graph's planar faces become closed
+ * block polygons (a curved street bounds a curved block), each inset to curb and land rings with
+ * the sidewalk band between them, then classified and subdivided into polygonal frontage PARCELS
+ * whose buildable polygons (after setbacks) place every building. Inside the district a ZONE
+ * layer (core/mid/edge bands, invertible or spatially uniform) drives what a parcel carries: a
+ * weighted class mix per band picks the building class (tower, slab, shop, rowhouse, house,
+ * mansion, farmhouse, barn, silo), and each class composes deterministic massing PIECES
+ * (`cityContent`) — setback tower tiers, gabled houses, gambrel barns, domed silos. Blocks left
+ * unbuilt become plazas/greens/meadows by band, or crop-row farm fields; slivers and block
+ * interiors classify as buffers and courtyards, never leftover rectangles. Street
+ * furniture (lights, species-mixed trees, estate hedges, driveways, parking lots) resolves as
+ * bounded, seeded data hooked to the network. Child `cityzone` volumes override the band/mix
+ * locally, so hand-placed intent wins over the profile. Named presets (Manhattan, Los Angeles,
+ * Beverly Hills, rural Ohio…) ship as plain slider bundles on the schema. Pure config + resolver
+ * here; the instanced renderer lives in the `shell`. Everything is deterministic per seed and
+ * persisted in `editor.scene.json`.
+ *
+ * @capability city-district editor-authorable procedural city district (streets, zoning, buildings, furniture)
+ */
+import { seededStreams } from "../random/rng.js";
+import { parseParams, registerSceneKind, } from "../scene/sceneKinds.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_STYLE } from "./buildings.js";
+import { buildLotPieces, pickClass, pickSpecies, rollClassPlacement, zoneBand, zoneMetric, } from "./cityContent.js";
+import { furnitureSpots } from "./streets.js";
+import { buildPathNetwork, pathNetworkMode, } from "./pathNetwork.js";
+import { buildablePolygon, carveCorridors, conformPolygonToRing, cutParcel, extractBlocks, isSliverBlock, pointsInPolygon, RingWalker, } from "./cityBlocks.js";
+import { fitRectInPolygon, rayDistanceToRing, pointInPolygon, polygonArea, polygonCentroid, polygonMeanWidth, polygonsOverlap, insetRingUniform, ringBounds, } from "./cityGeometry.js";
+/** The editor volume kind marking a box as a procedural city district. */
+export const CITY_KIND = "city";
+/** The editor volume kind that locally overrides a city's zone band/mix — a district in a district. */
+export const CITY_ZONE_KIND = "cityzone";
+/** City defaults: a zoned mixed metropolis — towers downtown, slabs mid-ring, houses at the edge. */
+export const CITY_DEFAULTS = {
+    gridness: 0.85,
+    curviness: 0.15,
+    branching: 0.4,
+    loopiness: 0,
+    connectivity: 0.88,
+    deadEnds: 0.35,
+    minCurveRadius: 24,
+    minTurnAngle: 0,
+    maxTurnAngle: 150,
+    fabric: true,
+    tunnels: true,
+    blockSize: 48,
+    blockAspect: 1,
+    openSpace: 0.12,
+    roadsideOccupancy: 0.88,
+    blockDensity: 0.6,
+    buildingRoadSetback: 2.5,
+    buildingSpacing: 1.4,
+    clusterStrength: 0.5,
+    streetWidth: 7,
+    boulevards: 0.35,
+    gravelLanes: false,
+    surface: "auto",
+    profile: "core-out",
+    coreExtent: 0.35,
+    midExtent: 0.7,
+    coreMix: [
+        { item: "tower", weight: 3 },
+        { item: "slab", weight: 1 },
+        { item: "shop", weight: 1 },
+    ],
+    midMix: [
+        { item: "slab", weight: 2 },
+        { item: "rowhouse", weight: 2 },
+        { item: "shop", weight: 1 },
+    ],
+    edgeMix: [
+        { item: "house", weight: 3 },
+        { item: "rowhouse", weight: 1 },
+    ],
+    lotScale: 1,
+    floorsMin: 1,
+    floorsMax: 30,
+    floorHeight: 3,
+    treeDensity: 0.5,
+    treeMix: [
+        { item: "broadleaf", weight: 3 },
+        { item: "conifer", weight: 1 },
+    ],
+    lightDensity: 0.5,
+    hedges: true,
+    driveways: true,
+    parking: true,
+    fields: false,
+    maxSlope: 0.5,
+    minElevation: -2,
+    bridges: true,
+    bridgeStyle: "arch",
+    sidewalks: true,
+    sidewalkWidth: 1.9,
+    style: DEFAULT_BUILDING_STYLE,
+    seed: "",
+};
+/** The city parameter schema — drives the inspector sliders and `meta` parse via the studio seam. */
+export const CITY_SCHEMA = {
+    groups: [
+        { id: "layout", label: "Layout" },
+        { id: "placement", label: "Placement" },
+        { id: "zoning", label: "Zoning" },
+        { id: "buildings", label: "Buildings" },
+        { id: "greenery", label: "Greenery & furniture" },
+    ],
+    fields: [
+        { type: "range", key: "gridness", label: "grid-ness", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.gridness },
+        { type: "range", key: "curviness", label: "curviness", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.curviness },
+        { type: "range", key: "branching", label: "branching", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.branching },
+        { type: "range", key: "loopiness", label: "loopiness", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.loopiness },
+        { type: "range", key: "connectivity", label: "connectivity", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.connectivity },
+        { type: "range", key: "deadEnds", label: "dead ends", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.deadEnds },
+        { type: "range", key: "minCurveRadius", label: "min curve radius", group: "layout", min: 6, max: 120, step: 1, default: CITY_DEFAULTS.minCurveRadius, unit: "m" },
+        { type: "range", key: "minTurnAngle", label: "min turn angle", group: "layout", min: 0, max: 60, step: 1, default: CITY_DEFAULTS.minTurnAngle, unit: "°" },
+        { type: "range", key: "maxTurnAngle", label: "max turn angle", group: "layout", min: 30, max: 180, step: 1, default: CITY_DEFAULTS.maxTurnAngle, unit: "°" },
+        { type: "range", key: "blockSize", label: "block size", group: "layout", min: 20, max: 140, step: 1, default: CITY_DEFAULTS.blockSize, unit: "m" },
+        { type: "range", key: "blockAspect", label: "block aspect", group: "layout", min: 1, max: 3, step: 0.05, default: CITY_DEFAULTS.blockAspect },
+        { type: "range", key: "openSpace", label: "open space", group: "layout", min: 0, max: 0.9, step: 0.01, default: CITY_DEFAULTS.openSpace },
+        { type: "range", key: "streetWidth", label: "street width", group: "layout", min: 3, max: 16, step: 0.5, default: CITY_DEFAULTS.streetWidth, unit: "m" },
+        { type: "range", key: "boulevards", label: "boulevards", group: "layout", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.boulevards },
+        { type: "bool", key: "gravelLanes", label: "gravel lanes", group: "layout", default: CITY_DEFAULTS.gravelLanes },
+        {
+            type: "select",
+            key: "surface",
+            label: "surface",
+            group: "layout",
+            default: CITY_DEFAULTS.surface,
+            options: [{ value: "auto" }, { value: "gravel" }],
+        },
+        { type: "bool", key: "fabric", label: "buildings & parcels", group: "layout", default: CITY_DEFAULTS.fabric },
+        { type: "bool", key: "bridges", label: "bridges over water", group: "layout", default: CITY_DEFAULTS.bridges },
+        { type: "bool", key: "tunnels", label: "tunnels through ridges", group: "layout", default: CITY_DEFAULTS.tunnels },
+        {
+            type: "select",
+            key: "bridgeStyle",
+            label: "bridge style",
+            group: "layout",
+            default: CITY_DEFAULTS.bridgeStyle,
+            options: [{ value: "arch" }, { value: "truss" }, { value: "beam" }],
+        },
+        { type: "bool", key: "sidewalks", label: "sidewalks", group: "layout", default: CITY_DEFAULTS.sidewalks },
+        { type: "range", key: "sidewalkWidth", label: "sidewalk width", group: "layout", min: 1, max: 4, step: 0.1, default: CITY_DEFAULTS.sidewalkWidth, unit: "m" },
+        { type: "action", key: "layoutRandomize", label: "randomize layout", group: "layout", action: "randomize" },
+        {
+            type: "select",
+            key: "profile",
+            label: "zone profile",
+            group: "zoning",
+            default: CITY_DEFAULTS.profile,
+            options: [{ value: "core-out" }, { value: "inverted" }, { value: "uniform" }],
+        },
+        { type: "range", key: "coreExtent", label: "core extent", group: "zoning", min: 0.05, max: 0.9, step: 0.01, default: CITY_DEFAULTS.coreExtent },
+        { type: "range", key: "midExtent", label: "mid extent", group: "zoning", min: 0.1, max: 0.95, step: 0.01, default: CITY_DEFAULTS.midExtent },
+        { type: "weightedList", key: "coreMix", label: "core mix", group: "zoning", itemLabel: "class", default: CITY_DEFAULTS.coreMix },
+        { type: "weightedList", key: "midMix", label: "mid mix", group: "zoning", itemLabel: "class", default: CITY_DEFAULTS.midMix },
+        { type: "weightedList", key: "edgeMix", label: "edge mix", group: "zoning", itemLabel: "class", default: CITY_DEFAULTS.edgeMix },
+        { type: "range", key: "lotScale", label: "lot scale", group: "zoning", min: 0.5, max: 2.5, step: 0.05, default: CITY_DEFAULTS.lotScale },
+        { type: "range", key: "roadsideOccupancy", label: "roadside occupancy", group: "placement", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.roadsideOccupancy },
+        { type: "range", key: "blockDensity", label: "block density", group: "placement", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.blockDensity },
+        { type: "range", key: "buildingRoadSetback", label: "road setback", group: "placement", min: 0, max: 12, step: 0.1, default: CITY_DEFAULTS.buildingRoadSetback, unit: "m" },
+        { type: "range", key: "buildingSpacing", label: "building spacing", group: "placement", min: 0.2, max: 10, step: 0.1, default: CITY_DEFAULTS.buildingSpacing, unit: "m" },
+        { type: "range", key: "clusterStrength", label: "cluster strength", group: "placement", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.clusterStrength },
+        { type: "range", key: "floorsMin", label: "floors min", group: "buildings", min: 1, max: 60, step: 1, default: CITY_DEFAULTS.floorsMin },
+        { type: "range", key: "floorsMax", label: "floors max", group: "buildings", min: 1, max: 60, step: 1, default: CITY_DEFAULTS.floorsMax },
+        { type: "range", key: "floorHeight", label: "floor height", group: "buildings", min: 2, max: 5, step: 0.1, default: CITY_DEFAULTS.floorHeight, unit: "m" },
+        { type: "range", key: "maxSlope", label: "max slope", group: "buildings", min: 0.05, max: 2, step: 0.05, default: CITY_DEFAULTS.maxSlope },
+        { type: "number", key: "minElevation", label: "build above y", group: "buildings", step: 0.5, default: CITY_DEFAULTS.minElevation },
+        {
+            type: "select",
+            key: "style",
+            label: "style",
+            group: "buildings",
+            default: CITY_DEFAULTS.style,
+            options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
+        },
+        { type: "range", key: "treeDensity", label: "tree density", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.treeDensity },
+        { type: "weightedList", key: "treeMix", label: "tree mix", group: "greenery", itemLabel: "species", default: CITY_DEFAULTS.treeMix },
+        { type: "range", key: "lightDensity", label: "street lights", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.lightDensity },
+        { type: "bool", key: "hedges", label: "estate hedges", group: "greenery", default: CITY_DEFAULTS.hedges },
+        { type: "bool", key: "driveways", label: "driveways", group: "greenery", default: CITY_DEFAULTS.driveways },
+        { type: "bool", key: "parking", label: "parking lots", group: "greenery", default: CITY_DEFAULTS.parking },
+        { type: "bool", key: "fields", label: "farm fields", group: "greenery", default: CITY_DEFAULTS.fields },
+        { type: "seed", key: "seed", label: "seed", default: CITY_DEFAULTS.seed },
+    ],
+    presets: [
+        {
+            id: "manhattan",
+            label: "Manhattan",
+            values: {
+                gridness: 1,
+                curviness: 0,
+                branching: 0.05,
+                blockSize: 32,
+                blockAspect: 2.4,
+                openSpace: 0.05,
+                roadsideOccupancy: 0.97,
+                blockDensity: 0.85,
+                buildingRoadSetback: 0.8,
+                buildingSpacing: 0.8,
+                clusterStrength: 0.25,
+                streetWidth: 9,
+                boulevards: 0.5,
+                gravelLanes: false,
+                profile: "core-out",
+                coreExtent: 0.6,
+                midExtent: 0.88,
+                coreMix: [
+                    { item: "tower", weight: 5 },
+                    { item: "slab", weight: 1 },
+                ],
+                midMix: [
+                    { item: "tower", weight: 2 },
+                    { item: "slab", weight: 2 },
+                ],
+                edgeMix: [
+                    { item: "slab", weight: 3 },
+                    { item: "rowhouse", weight: 2 },
+                ],
+                lotScale: 1,
+                floorsMin: 5,
+                floorsMax: 55,
+                treeDensity: 0.3,
+                treeMix: [{ item: "broadleaf", weight: 1 }],
+                lightDensity: 0.8,
+                hedges: false,
+                driveways: false,
+                parking: false,
+                fields: false,
+                sidewalks: true,
+                style: "capital",
+            },
+        },
+        {
+            id: "losangeles",
+            label: "Los Angeles",
+            values: {
+                gridness: 0.7,
+                curviness: 0.25,
+                branching: 0.5,
+                blockSize: 62,
+                blockAspect: 1.2,
+                openSpace: 0.08,
+                roadsideOccupancy: 0.9,
+                blockDensity: 0.55,
+                buildingRoadSetback: 3,
+                buildingSpacing: 1.8,
+                clusterStrength: 0.5,
+                streetWidth: 8,
+                boulevards: 0.45,
+                gravelLanes: false,
+                profile: "core-out",
+                coreExtent: 0.25,
+                midExtent: 0.55,
+                coreMix: [
+                    { item: "tower", weight: 2 },
+                    { item: "slab", weight: 2 },
+                    { item: "shop", weight: 2 },
+                ],
+                midMix: [
+                    { item: "shop", weight: 2 },
+                    { item: "house", weight: 3 },
+                    { item: "slab", weight: 1 },
+                ],
+                edgeMix: [
+                    { item: "house", weight: 5 },
+                    { item: "shop", weight: 1 },
+                ],
+                lotScale: 1.1,
+                floorsMin: 1,
+                floorsMax: 18,
+                treeDensity: 0.55,
+                treeMix: [
+                    { item: "palm", weight: 4 },
+                    { item: "broadleaf", weight: 1 },
+                    { item: "cypress", weight: 1 },
+                ],
+                lightDensity: 0.6,
+                hedges: false,
+                driveways: true,
+                parking: true,
+                fields: false,
+                sidewalks: true,
+                style: "coastal",
+            },
+        },
+        {
+            id: "beverlyhills",
+            label: "Beverly Hills",
+            values: {
+                gridness: 0.2,
+                curviness: 0.8,
+                branching: 0.6,
+                blockSize: 90,
+                blockAspect: 1,
+                openSpace: 0.07,
+                roadsideOccupancy: 0.85,
+                blockDensity: 0.3,
+                buildingRoadSetback: 4.5,
+                buildingSpacing: 2.2,
+                clusterStrength: 0.35,
+                streetWidth: 6.5,
+                boulevards: 0,
+                gravelLanes: false,
+                profile: "uniform",
+                coreExtent: 0.35,
+                midExtent: 0.7,
+                coreMix: [
+                    { item: "mansion", weight: 3 },
+                    { item: "house", weight: 1 },
+                ],
+                midMix: [
+                    { item: "mansion", weight: 3 },
+                    { item: "house", weight: 1 },
+                ],
+                edgeMix: [
+                    { item: "mansion", weight: 2 },
+                    { item: "house", weight: 2 },
+                ],
+                lotScale: 1.5,
+                floorsMin: 1,
+                floorsMax: 3,
+                treeDensity: 0.9,
+                treeMix: [
+                    { item: "palm", weight: 3 },
+                    { item: "cypress", weight: 2 },
+                    { item: "broadleaf", weight: 2 },
+                ],
+                lightDensity: 0.35,
+                hedges: true,
+                driveways: true,
+                parking: false,
+                fields: false,
+                sidewalks: true,
+                style: "coastal",
+            },
+        },
+        {
+            id: "ruralohio",
+            label: "Rural Ohio",
+            values: {
+                gridness: 1,
+                curviness: 0.06,
+                branching: 0.3,
+                blockSize: 120,
+                blockAspect: 1,
+                openSpace: 0.55,
+                roadsideOccupancy: 0.6,
+                blockDensity: 0.25,
+                buildingRoadSetback: 6,
+                buildingSpacing: 5,
+                clusterStrength: 0.8,
+                streetWidth: 5.5,
+                boulevards: 0,
+                gravelLanes: true,
+                profile: "core-out",
+                coreExtent: 0.22,
+                midExtent: 0.55,
+                coreMix: [
+                    { item: "shop", weight: 2 },
+                    { item: "house", weight: 2 },
+                    { item: "rowhouse", weight: 1 },
+                ],
+                midMix: [
+                    { item: "farmhouse", weight: 2 },
+                    { item: "house", weight: 1 },
+                    { item: "barn", weight: 1 },
+                ],
+                edgeMix: [
+                    { item: "farmhouse", weight: 2 },
+                    { item: "barn", weight: 2 },
+                    { item: "silo", weight: 1 },
+                ],
+                lotScale: 1.4,
+                floorsMin: 1,
+                floorsMax: 2,
+                treeDensity: 0.35,
+                treeMix: [
+                    { item: "broadleaf", weight: 3 },
+                    { item: "conifer", weight: 2 },
+                ],
+                lightDensity: 0.1,
+                hedges: false,
+                driveways: true,
+                parking: false,
+                fields: true,
+                sidewalks: false,
+                style: "village",
+            },
+        },
+        {
+            id: "circuit",
+            label: "Race circuit",
+            values: {
+                gridness: 0.4,
+                curviness: 0.55,
+                branching: 0.15,
+                loopiness: 1,
+                connectivity: 0.05,
+                deadEnds: 0,
+                minCurveRadius: 34,
+                minTurnAngle: 0,
+                maxTurnAngle: 95,
+                blockSize: 95,
+                blockAspect: 1,
+                openSpace: 0,
+                streetWidth: 12,
+                boulevards: 0,
+                gravelLanes: false,
+                surface: "auto",
+                fabric: false,
+                bridges: true,
+                tunnels: true,
+                sidewalks: false,
+                treeDensity: 0.2,
+                lightDensity: 0.25,
+                hedges: false,
+                driveways: false,
+                parking: false,
+                fields: false,
+                style: "generic",
+            },
+        },
+        {
+            id: "rally",
+            label: "Rally stage",
+            values: {
+                gridness: 0.1,
+                curviness: 0.95,
+                branching: 0.2,
+                loopiness: 0.15,
+                connectivity: 0.12,
+                deadEnds: 0.3,
+                minCurveRadius: 12,
+                minTurnAngle: 0,
+                maxTurnAngle: 150,
+                blockSize: 72,
+                blockAspect: 1,
+                openSpace: 0,
+                streetWidth: 6,
+                boulevards: 0,
+                gravelLanes: true,
+                surface: "gravel",
+                fabric: false,
+                bridges: true,
+                tunnels: true,
+                sidewalks: false,
+                treeDensity: 0.65,
+                lightDensity: 0.05,
+                hedges: false,
+                driveways: false,
+                parking: false,
+                fields: false,
+                style: "village",
+            },
+        },
+        {
+            id: "metropolis",
+            label: "Zoned metropolis",
+            values: {
+                gridness: 0.85,
+                curviness: 0.15,
+                branching: 0.4,
+                blockSize: 48,
+                blockAspect: 1.3,
+                openSpace: 0.12,
+                roadsideOccupancy: 0.92,
+                blockDensity: 0.7,
+                buildingRoadSetback: 1.5,
+                buildingSpacing: 1.2,
+                clusterStrength: 0.45,
+                streetWidth: 7.5,
+                boulevards: 0.4,
+                profile: "core-out",
+                coreExtent: 0.45,
+                midExtent: 0.75,
+                floorsMin: 1,
+                floorsMax: 34,
+                treeDensity: 0.55,
+                lightDensity: 0.6,
+                style: "generic",
+            },
+        },
+    ],
+};
+/** Zone-override schema for `cityzone` volumes: pin a band and optionally a bespoke class mix. */
+export const CITY_ZONE_SCHEMA = {
+    fields: [
+        {
+            type: "select",
+            key: "band",
+            label: "zone band",
+            default: "core",
+            options: [{ value: "core" }, { value: "mid" }, { value: "edge" }],
+        },
+        { type: "weightedList", key: "mix", label: "class mix", itemLabel: "class", default: [] },
+    ],
+};
+/** Parse a volume's `meta` into fully-defaulted city rules. @internal */
+export function readCityRules(meta) {
+    const params = parseParams(CITY_SCHEMA, meta);
+    const floorsMin = params["floorsMin"];
+    const floorsMax = params["floorsMax"];
+    // Legacy documents tuned `buildingDensity`; honor it as the occupancy dial when the volume
+    // predates the placement params (and only then — presets/authors that set the new keys win).
+    const legacyDensity = meta?.["buildingDensity"];
+    const hasLegacy = typeof legacyDensity === "number" && Number.isFinite(legacyDensity) && meta?.["roadsideOccupancy"] === undefined;
+    return {
+        gridness: params["gridness"],
+        curviness: params["curviness"],
+        branching: params["branching"],
+        loopiness: params["loopiness"],
+        connectivity: params["connectivity"],
+        deadEnds: params["deadEnds"],
+        minCurveRadius: params["minCurveRadius"],
+        minTurnAngle: params["minTurnAngle"],
+        maxTurnAngle: params["maxTurnAngle"],
+        fabric: params["fabric"],
+        tunnels: params["tunnels"],
+        blockSize: params["blockSize"],
+        blockAspect: params["blockAspect"],
+        openSpace: params["openSpace"],
+        roadsideOccupancy: hasLegacy ? Math.max(0, Math.min(1, legacyDensity)) : params["roadsideOccupancy"],
+        blockDensity: hasLegacy ? Math.max(0, Math.min(1, legacyDensity * 0.8)) : params["blockDensity"],
+        buildingRoadSetback: params["buildingRoadSetback"],
+        buildingSpacing: params["buildingSpacing"],
+        clusterStrength: params["clusterStrength"],
+        streetWidth: params["streetWidth"],
+        boulevards: params["boulevards"],
+        gravelLanes: params["gravelLanes"],
+        surface: params["surface"],
+        profile: params["profile"],
+        coreExtent: params["coreExtent"],
+        midExtent: params["midExtent"],
+        coreMix: params["coreMix"],
+        midMix: params["midMix"],
+        edgeMix: params["edgeMix"],
+        lotScale: params["lotScale"],
+        floorsMin: Math.min(floorsMin, floorsMax),
+        floorsMax: Math.max(floorsMin, floorsMax),
+        floorHeight: params["floorHeight"],
+        treeDensity: params["treeDensity"],
+        treeMix: params["treeMix"],
+        lightDensity: params["lightDensity"],
+        hedges: params["hedges"],
+        driveways: params["driveways"],
+        parking: params["parking"],
+        fields: params["fields"],
+        maxSlope: params["maxSlope"],
+        minElevation: params["minElevation"],
+        bridges: params["bridges"],
+        bridgeStyle: params["bridgeStyle"],
+        sidewalks: params["sidewalks"],
+        sidewalkWidth: params["sidewalkWidth"],
+        style: params["style"],
+        seed: params["seed"],
+    };
+}
+/** Bounded-work caps so a huge volume can never generate unbounded content. */
+const MAX_STREETS = 320;
+const MAX_LOTS = 2600;
+const MAX_INTERSECTIONS = 600;
+const MAX_TREES = 3200;
+const MAX_LIGHTS = 1200;
+const MAX_FIELD_ROWS = 2400;
+const MAX_PARKING = 380;
+const TAU = Math.PI * 2;
+function axisValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Smooth two-octave sideways wander along a street, deterministic per street. */
+function makeWander(rng, amplitude, wavelength) {
+    const f1 = TAU / (wavelength * (0.75 + rng() * 0.5));
+    const f2 = f1 * (2.3 + rng() * 0.8);
+    const p1 = rng() * TAU;
+    const p2 = rng() * TAU;
+    return (t) => amplitude * (Math.sin(t * f1 + p1) * 0.65 + Math.sin(t * f2 + p2) * 0.35);
+}
+/**
+ * Spatial hash of dense street centerline samples (with per-sample clearance radius). Serves both
+ * "is this point on/near a road" lot rejection and branch-to-street connection tests without
+ * quadratic polyline scans.
+ */
+class StreetIndex {
+    cells = new Map();
+    cell = 10;
+    key(x, z) {
+        return `${Math.floor(x / this.cell)}:${Math.floor(z / this.cell)}`;
+    }
+    addStreet(index, points, width) {
+        const r = width / 2;
+        for (let i = 0; i + 1 < points.length; i += 1) {
+            const [ax, az] = points[i];
+            const [bx, bz] = points[i + 1];
+            const len = Math.hypot(bx - ax, bz - az);
+            const steps = Math.max(1, Math.ceil(len / 3));
+            for (let s = 0; s <= steps; s += 1) {
+                const t = s / steps;
+                const x = ax + (bx - ax) * t;
+                const z = az + (bz - az) * t;
+                const key = this.key(x, z);
+                const bucket = this.cells.get(key);
+                const sample = { x, z, r, street: index };
+                if (bucket === undefined)
+                    this.cells.set(key, [sample]);
+                else
+                    bucket.push(sample);
+            }
+        }
+    }
+    /** Smallest (distance − clearance) to any street sample near the point; Infinity when clear. */
+    clearance(x, z, margin, excludeStreet = -1) {
+        const cx = Math.floor(x / this.cell);
+        const cz = Math.floor(z / this.cell);
+        let worst = Infinity;
+        for (let i = cx - 1; i <= cx + 1; i += 1) {
+            for (let j = cz - 1; j <= cz + 1; j += 1) {
+                const bucket = this.cells.get(`${i}:${j}`);
+                if (bucket === undefined)
+                    continue;
+                for (const sample of bucket) {
+                    if (sample.street === excludeStreet)
+                        continue;
+                    const d = Math.hypot(sample.x - x, sample.z - z) - sample.r - margin;
+                    if (d < worst)
+                        worst = d;
+                }
+            }
+        }
+        return worst;
+    }
+    /** Nearest centerline sample to a point (expanding ring search), or null when far from roads. */
+    nearest(x, z, maxStreet = Infinity) {
+        const cx = Math.floor(x / this.cell);
+        const cz = Math.floor(z / this.cell);
+        for (let radius = 1; radius <= 4; radius += 1) {
+            let best = null;
+            for (let i = cx - radius; i <= cx + radius; i += 1) {
+                for (let j = cz - radius; j <= cz + radius; j += 1) {
+                    const bucket = this.cells.get(`${i}:${j}`);
+                    if (bucket === undefined)
+                        continue;
+                    for (const sample of bucket) {
+                        if (sample.street >= maxStreet)
+                            continue;
+                        const d = Math.hypot(sample.x - x, sample.z - z);
+                        if (best === null || d < best.dist)
+                            best = { x: sample.x, z: sample.z, street: sample.street, dist: d };
+                    }
+                }
+            }
+            if (best !== null)
+                return best;
+        }
+        return null;
+    }
+}
+/** Separating-axis test for two rotated rectangles (center, half-extents, yaw): true when a gap exists. */
+function rectsSeparated(a, b) {
+    const axes = [];
+    for (const angle of [a.angle, b.angle]) {
+        axes.push([Math.cos(angle), -Math.sin(angle)], [Math.sin(angle), Math.cos(angle)]);
+    }
+    const corners = (r) => {
+        const c = Math.cos(r.angle);
+        const s = Math.sin(r.angle);
+        const out = [];
+        for (const [dx, dz] of [
+            [r.hw, r.hd],
+            [r.hw, -r.hd],
+            [-r.hw, r.hd],
+            [-r.hw, -r.hd],
+        ]) {
+            out.push([r.x + dx * c + dz * s, r.z - dx * s + dz * c]);
+        }
+        return out;
+    };
+    const ca = corners(a);
+    const cb = corners(b);
+    for (const [ax, az] of axes) {
+        let minA = Infinity, maxA = -Infinity, minB = Infinity, maxB = -Infinity;
+        for (const [x, z] of ca) {
+            const p = x * ax + z * az;
+            if (p < minA)
+                minA = p;
+            if (p > maxA)
+                maxA = p;
+        }
+        for (const [x, z] of cb) {
+            const p = x * ax + z * az;
+            if (p < minB)
+                minB = p;
+            if (p > maxB)
+                maxB = p;
+        }
+        if (maxA < minB || maxB < minA)
+            return true; // gap on this axis → no overlap
+    }
+    return false;
+}
+/** Broadphase grid over placed lots so overlap tests only touch neighbors. */
+class LotIndex {
+    cells = new Map();
+    cell = 24;
+    key(x, z) {
+        return `${Math.floor(x / this.cell)}:${Math.floor(z / this.cell)}`;
+    }
+    overlapsAny(lot, gap) {
+        const grown = { ...lot, hw: lot.hw + gap / 2, hd: lot.hd + gap / 2 };
+        const cx = Math.floor(lot.x / this.cell);
+        const cz = Math.floor(lot.z / this.cell);
+        for (let i = cx - 1; i <= cx + 1; i += 1) {
+            for (let j = cz - 1; j <= cz + 1; j += 1) {
+                const bucket = this.cells.get(`${i}:${j}`);
+                if (bucket === undefined)
+                    continue;
+                for (const other of bucket) {
+                    if (!rectsSeparated(grown, other))
+                        return true;
+                }
+            }
+        }
+        return false;
+    }
+    add(lot) {
+        const key = this.key(lot.x, lot.z);
+        const bucket = this.cells.get(key);
+        if (bucket === undefined)
+            this.cells.set(key, [lot]);
+        else
+            bucket.push(lot);
+    }
+}
+const LEVEL_RANK = { boulevard: 3, avenue: 2, street: 1, lane: 0 };
+/**
+ * The block-first fabric: extract closed block polygons from the street graph, classify each
+ * block (park/plaza/field/buffer/buildable), subdivide buildable block frontage into polygonal
+ * parcels, and derive every building from its parcel's buildable polygon. A curved street bounds
+ * a curved block; a diagonal one yields diagonal parcels — placement never guesses from the
+ * nearest road again.
+ */
+function buildFabric(rules, streams, streets, index, hx, hz, slopeAt, heightAt, overrideAt, junctions) {
+    const result = { blocks: [], parcels: [], parks: [], lots: [], placed: new LotIndex(), hedges: [], driveways: [] };
+    const bandMix = { core: rules.coreMix, mid: rules.midMix, edge: rules.edgeMix };
+    const junctionBoost = (x, z) => {
+        let best = Infinity;
+        for (const j of junctions) {
+            const d = Math.hypot(j.x - x, j.z - z);
+            if (d < best)
+                best = d;
+        }
+        return best === Infinity ? 0 : Math.max(0, 1 - best / (rules.blockSize * 0.6));
+    };
+    const commercialCore = rules.coreMix.some((entry) => (entry.item === "tower" || entry.item === "slab" || entry.item === "shop") && entry.weight > 0);
+    const fabric = extractBlocks(streets.map((street) => ({ points: street.points, width: street.width, level: street.level, sidewalk: street.sidewalk })), hx, hz, { streetWidthBase: rules.streetWidth, sidewalkBase: rules.sidewalkWidth, curbMargin: 0.35 });
+    const bandAt = (x, z, roll) => {
+        const override = overrideAt === null ? null : overrideAt(x, z);
+        const band = override !== null ? override.band : zoneBand(zoneMetric(x, z, hx, hz), rules.profile, rules.coreExtent, rules.midExtent, roll);
+        const mix = override !== null && override.mix !== null && override.mix.length > 0 ? override.mix : bandMix[band];
+        return { band, mix };
+    };
+    const parkFromRing = (id, type, ring, jitter) => {
+        const bounds = ringBounds(ring);
+        return {
+            id,
+            center: [(bounds.minX + bounds.maxX) / 2, (bounds.minZ + bounds.maxZ) / 2],
+            size: [Math.max(2, bounds.maxX - bounds.minX), Math.max(2, bounds.maxZ - bounds.minZ)],
+            type,
+            jitter,
+            polygon: ring,
+        };
+    };
+    for (let bi = 0; bi < fabric.blocks.length; bi += 1) {
+        const rings = fabric.blocks[bi];
+        const rng = streams(`block:${bi}`);
+        const bandRoll = rng();
+        const openRoll = rng();
+        const parkJitter = rng();
+        const land = rings.land;
+        const blockId = result.blocks.length;
+        if (land.length < 3) {
+            // The inset consumed the face: whatever pavement-free scrap remains is a landscaped buffer.
+            if (rings.curb.length >= 3 && polygonArea(rings.curb) > 30) {
+                result.blocks.push({ id: `block:${bi}`, kind: "buffer", polygon: rings.curb, curb: rings.curb, area: polygonArea(rings.curb) });
+                result.parks.push(parkFromRing(`park:${bi}`, "buffer", rings.curb, parkJitter));
+            }
+            continue;
+        }
+        const area = polygonArea(land);
+        const [bcx, bcz] = polygonCentroid(land);
+        const { band } = bandAt(bcx, bcz, bandRoll);
+        const sliver = isSliverBlock(land, Math.max(90, rules.blockSize * rules.blockSize * 0.028), Math.max(5.5, rules.streetWidth * 0.75));
+        if (sliver) {
+            result.blocks.push({ id: `block:${bi}`, kind: "buffer", polygon: land, curb: rings.curb, area });
+            result.parks.push(parkFromRing(`park:${bi}`, "buffer", land, parkJitter));
+            continue;
+        }
+        let fieldBlock = false;
+        if (openRoll < rules.openSpace) {
+            // Intentional open-space block. Pocket plazas only in a commercial core, and only pocket-sized.
+            const bounds = ringBounds(land);
+            const pocket = band === "core" && commercialCore && Math.max(bounds.maxX - bounds.minX, bounds.maxZ - bounds.minZ) <= 52;
+            const type = rules.fields && !pocket ? "field" : pocket ? "plaza" : band === "edge" ? "meadow" : "green";
+            result.blocks.push({ id: `block:${bi}`, kind: type === "plaza" ? "plaza" : type === "field" ? "field" : "park", polygon: land, curb: rings.curb, area });
+            result.parks.push(parkFromRing(`park:${bi}`, type, land, parkJitter));
+            // Farm fields never displace homesteads — the farmhouse standing in its own field IS the
+            // look, so field blocks still subdivide their road frontage; other park types stay clear.
+            if (type !== "field")
+                continue;
+            fieldBlock = true;
+        }
+        else {
+            result.blocks.push({ id: `block:${bi}`, kind: "buildable", polygon: land, curb: rings.curb, area });
+        }
+        // --- parcel subdivision along the block's frontage ring ---
+        const walker = new RingWalker(land);
+        const halfW = Math.max(3, polygonMeanWidth(land) / 2);
+        const wave = makeWander(rng, 0.5, rules.blockSize * 2.6);
+        const blockParcels = [];
+        let cursor = rng() * 4;
+        const endStation = walker.total - 2;
+        let prevClass = null;
+        let maxDepthUsed = 0;
+        let guard = 0;
+        while (cursor < endStation && blockParcels.length < 64 && result.lots.length < MAX_LOTS && guard < 220) {
+            guard += 1;
+            const pBandRoll = rng();
+            const classRoll = rng();
+            const stickRoll = rng();
+            const occupancyRoll = rng();
+            const lotJitter = rng();
+            const lotRng = streams(`lot:${bi}:${Math.round(cursor * 10)}`);
+            const mid0 = walker.at(cursor);
+            // Only true street frontage grows parcels: an arc along the district rim (or facing a
+            // pruned dead end) has no road to face, so the cursor slides past it.
+            const curbProbe = [mid0.p[0] - mid0.normal[0] * 2, mid0.p[1] - mid0.normal[1] * 2];
+            const near = index.nearest(curbProbe[0], curbProbe[1], streets.length);
+            if (near === null || near.dist > streets[near.street].width / 2 + rules.sidewalkWidth * 1.6 + 3) {
+                cursor += 6;
+                prevClass = null;
+                continue;
+            }
+            const probe = [mid0.p[0] + mid0.normal[0] * 5, mid0.p[1] + mid0.normal[1] * 5];
+            const { band: pBand, mix } = bandAt(probe[0], probe[1], pBandRoll);
+            let cls = pickClass(mix, classRoll);
+            // Sticky class runs: with clustering, a house is followed by more houses — rows form.
+            if (prevClass !== null && stickRoll < 0.45 + rules.clusterStrength * 0.4 && mix.some((entry) => entry.item === prevClass && entry.weight > 0)) {
+                cls = prevClass;
+            }
+            const placement = rollClassPlacement(cls, lotRng, rules.lotScale, rules.floorsMin, rules.floorsMax, rules.buildingRoadSetback, rules.buildingSpacing);
+            const frontW = placement.width + placement.gap;
+            if (cursor + frontW > walker.total - 0.5)
+                break;
+            // Parcel depth: setback + class depth + rear yard, deepened toward the block spine by
+            // `blockDensity` (dense districts consume their block; loose ones keep green cores). The
+            // hard cap is a per-station ray cast — parcels from opposite frontages meet halfway.
+            const rayOrigin = [mid0.p[0] + mid0.normal[0] * 0.2, mid0.p[1] + mid0.normal[1] * 0.2];
+            const across = rayDistanceToRing(land, rayOrigin, mid0.normal);
+            const depthCap = Number.isFinite(across) ? Math.max(3, across * 0.5 - 0.3) : halfW;
+            const depth = Math.min(depthCap, placement.setback + placement.depth + 2 + rules.blockDensity * Math.max(0, depthCap - placement.depth - placement.setback - 2));
+            const s0 = cursor;
+            const s1 = cursor + frontW;
+            let usedDepth = depth;
+            let poly = cutParcel(walker, land, { s0, s1, depth });
+            const midS = walker.at((s0 + s1) / 2);
+            if (poly !== null && fabric.deadEnds.length > 0) {
+                // Cul-de-sac lanes were pruned from the face graph; carve their corridors out of parcels.
+                const keep = [midS.p[0] + midS.normal[0] * 1.5, midS.p[1] + midS.normal[1] * 1.5];
+                let carved = carveCorridors(poly, keep, fabric.deadEnds.map((d) => ({ pts: d.pts, width: d.width + 1 })), 0.8);
+                // Carve chords can cross a concave notch of the block; conform the result again.
+                if (carved.length >= 3 && carved.length !== poly.length)
+                    carved = conformPolygonToRing(carved, land);
+                poly = carved.length >= 3 ? carved : null;
+            }
+            if (poly !== null) {
+                // Never overlap a neighbor parcel: retry shallower once, then give the arc up as yard.
+                let clash = blockParcels.some((other) => polygonsOverlap(poly, other.polygon, 0.18));
+                if (clash) {
+                    const shallow = cutParcel(walker, land, { s0, s1, depth: depth * 0.55 });
+                    if (shallow !== null && !blockParcels.some((other) => polygonsOverlap(shallow, other.polygon, 0.18))) {
+                        poly = shallow;
+                        usedDepth = depth * 0.55;
+                        clash = false;
+                    }
+                }
+                if (clash)
+                    poly = null;
+            }
+            if (poly === null) {
+                cursor += frontW * 0.6;
+                prevClass = null;
+                continue;
+            }
+            const A = walker.at(s0).p;
+            const B = walker.at(s1).p;
+            const tangent = (() => {
+                const tx = B[0] - A[0];
+                const tz = B[1] - A[1];
+                const l = Math.hypot(tx, tz) || 1;
+                return [tx / l, tz / l];
+            })();
+            let isCorner = false;
+            for (const vi of walker.verticesBetween(s0, s1)) {
+                const angle = walker.interiorAngle(vi);
+                if (angle < 2.53 || angle > Math.PI * 2 - 2.53) {
+                    isCorner = true;
+                    break;
+                }
+            }
+            const frontProbe = [midS.p[0] - midS.normal[0] * 2, midS.p[1] - midS.normal[1] * 2];
+            const nearestStreet = index.nearest(frontProbe[0], frontProbe[1], streets.length);
+            const frontage = nearestStreet === null ? [] : [{ street: nearestStreet.street, a: A, b: B, tangent }];
+            const parcelId = `parcel:${bi}:${blockParcels.length}`;
+            const parcel = {
+                id: parcelId,
+                block: blockId,
+                polygon: poly,
+                buildable: [],
+                frontage,
+                area: polygonArea(poly),
+                depth: usedDepth,
+                isCorner,
+                kind: "vacant",
+            };
+            // Local occupancy: the district dial, drifted by the smooth wave and boosted near
+            // junctions so intersections read as centers of development.
+            const local = rules.roadsideOccupancy * (1 - rules.clusterStrength * 0.3) +
+                rules.clusterStrength * (wave(cursor) + 0.5) * 0.22 +
+                rules.clusterStrength * junctionBoost(midS.p[0], midS.p[1]) * 0.6;
+            if (occupancyRoll > local) {
+                blockParcels.push(parcel);
+                cursor += frontW;
+                prevClass = null;
+                continue;
+            }
+            const sideGap = Math.max(0.3, placement.gap / 2);
+            const buildable = buildablePolygon(poly, A, B, placement.setback, sideGap, 1.2, usedDepth);
+            parcel.buildable = buildable;
+            let placedLot = false;
+            if (buildable.length >= 3) {
+                const outDir = [-midS.normal[0], -midS.normal[1]];
+                const rotationY = Math.atan2(outDir[0], outDir[1]);
+                const maxW = Math.max(3, Math.min(placement.width, frontW - placement.gap));
+                const availDepth = usedDepth - placement.setback - 1.2;
+                const maxD = Math.max(3, Math.min(placement.depth, availDepth));
+                const cx0 = midS.p[0] + midS.normal[0] * (placement.setback + maxD / 2);
+                const cz0 = midS.p[1] + midS.normal[1] * (placement.setback + maxD / 2);
+                const fit = fitRectInPolygon(buildable, cx0, cz0, maxW, maxD, rotationY, 0.45);
+                if (fit !== null && fit.w >= 3 && fit.d >= 2.6) {
+                    const slopeRoll = rng();
+                    const hw = fit.w / 2;
+                    const hd = fit.d / 2;
+                    const ca = Math.cos(rotationY);
+                    const sa = Math.sin(rotationY);
+                    let ok = true;
+                    if (slopeAt !== null && slopeAt(fit.cx, fit.cz) > rules.maxSlope * (0.85 + slopeRoll * 0.3))
+                        ok = false;
+                    if (ok && heightAt !== null && heightAt(fit.cx, fit.cz) < rules.minElevation)
+                        ok = false;
+                    // Belt and braces against pavement (bridge approaches, cul-de-sac bulbs): the footprint
+                    // corners keep clearance to every street centerline.
+                    if (ok && index.clearance(fit.cx, fit.cz, 1) < 0)
+                        ok = false;
+                    if (ok) {
+                        for (const [dx, dz] of [
+                            [hw, hd],
+                            [hw, -hd],
+                            [-hw, hd],
+                            [-hw, -hd],
+                        ]) {
+                            if (index.clearance(fit.cx + dx * ca + dz * sa, fit.cz - dx * sa + dz * ca, 0.4) < 0) {
+                                ok = false;
+                                break;
+                            }
+                        }
+                    }
+                    const candidate = { x: fit.cx, z: fit.cz, hw, hd, angle: rotationY };
+                    if (ok && !result.placed.overlapsAny(candidate, 0.8)) {
+                        result.placed.add(candidate);
+                        const pieces = buildLotPieces(cls, fit.w, fit.d, placement.floors, rules.floorHeight, lotRng);
+                        const anchor = nearestStreet === null ? [frontProbe[0], frontProbe[1]] : [nearestStreet.x, nearestStreet.z];
+                        result.lots.push({
+                            id: `lot:${bi}:${result.lots.length}`,
+                            center: [fit.cx, fit.cz],
+                            size: [fit.w, fit.d],
+                            rotationY,
+                            floors: placement.floors,
+                            jitter: lotJitter,
+                            cls,
+                            zone: pBand,
+                            anchor,
+                            pieces,
+                            parcel: parcelId,
+                        });
+                        parcel.kind = "built";
+                        placedLot = true;
+                        if (rules.driveways && (cls === "house" || cls === "mansion" || cls === "farmhouse" || cls === "barn" || cls === "silo")) {
+                            const dirX = fit.cx - anchor[0];
+                            const dirZ = fit.cz - anchor[1];
+                            const len = Math.hypot(dirX, dirZ) || 1;
+                            const ux = dirX / len;
+                            const uz = dirZ / len;
+                            const streetWidth = nearestStreet === null ? rules.streetWidth : streets[nearestStreet.street].width;
+                            const start = [anchor[0] + ux * (streetWidth / 2 - 0.4), anchor[1] + uz * (streetWidth / 2 - 0.4)];
+                            const end = [fit.cx - ux * (hd - 1), fit.cz - uz * (hd - 1)];
+                            const surface = cls === "farmhouse" || cls === "barn" || cls === "silo" || rules.gravelLanes ? "gravel" : "pavement";
+                            result.driveways.push({ points: [start, end], width: cls === "mansion" ? 3.2 : 2.6, surface });
+                        }
+                        if (rules.hedges && cls === "mansion") {
+                            // Perimeter hedge with a gated gap centered on the driveway mouth (street face).
+                            const m = 2.4;
+                            const hhw = hw + m;
+                            const hhd = hd + m;
+                            const th = 0.7;
+                            const gap = 2.2;
+                            const runs = [
+                                { x: -hhw / 2 - gap / 2, z: hhd, len: hhw - gap, rot: 0 },
+                                { x: hhw / 2 + gap / 2, z: hhd, len: hhw - gap, rot: 0 },
+                                { x: 0, z: -hhd, len: hhw * 2, rot: 0 },
+                                { x: hhw, z: 0, len: hhd * 2, rot: Math.PI / 2 },
+                                { x: -hhw, z: 0, len: hhd * 2, rot: Math.PI / 2 },
+                            ];
+                            for (const run of runs) {
+                                const wx = fit.cx + run.x * ca + run.z * sa;
+                                const wz = fit.cz - run.x * sa + run.z * ca;
+                                result.hedges.push({ center: [wx, wz], size: [run.len, th], rotationY: rotationY + run.rot });
+                            }
+                        }
+                    }
+                }
+            }
+            if (!placedLot && parcel.kind === "vacant")
+                parcel.kind = "yard";
+            blockParcels.push(parcel);
+            if (placedLot)
+                maxDepthUsed = Math.max(maxDepthUsed, usedDepth);
+            // A pushed parcel owns its whole frontage arc — the cursor never re-enters it.
+            cursor += frontW;
+            prevClass = placedLot ? cls : null;
+        }
+        result.parcels.push(...blockParcels);
+        if (fieldBlock)
+            continue; // the field polygon already owns the interior
+        if (blockParcels.length === 0) {
+            // Nothing subdivided (tiny ring): the block is intentional green, not leftover.
+            result.blocks[blockId].kind = "park";
+            result.parks.push(parkFromRing(`park:${bi}`, band === "edge" ? "meadow" : "green", land, parkJitter));
+            continue;
+        }
+        // Block interior left behind the deepest parcels: classify it (courtyard downtown, green
+        // elsewhere) when it is big enough to read as a place rather than back yards.
+        if (maxDepthUsed > 0) {
+            const core = insetRingUniform(land, maxDepthUsed + 0.5);
+            if (core.length >= 3 && polygonArea(core) > 240) {
+                const type = band === "core" ? "courtyard" : band === "mid" ? (parkJitter < 0.5 ? "courtyard" : "green") : "meadow";
+                result.parks.push(parkFromRing(`court:${bi}`, type, core, parkJitter));
+            }
+        }
+    }
+    return result;
+}
+/** Crop rows for field parks, clipped to the park's road-derived polygon and around placed lots. */
+function buildFieldRows(parks, placed, streams) {
+    let total = 0;
+    const rng = streams("fields");
+    for (const park of parks) {
+        if (park.type !== "field")
+            continue;
+        const rows = [];
+        const alongX = park.size[0] >= park.size[1];
+        const runLength = alongX ? park.size[0] : park.size[1];
+        const across = alongX ? park.size[1] : park.size[0];
+        const spacing = 3.2 + rng() * 0.8;
+        const count = Math.floor((across - 3) / spacing);
+        for (let r = 0; r < count && total < MAX_FIELD_ROWS; r += 1) {
+            const offset = -across / 2 + 2 + r * spacing;
+            let current = [];
+            const steps = Math.max(2, Math.ceil(runLength / 4));
+            for (let sIdx = 0; sIdx <= steps; sIdx += 1) {
+                const along = -runLength / 2 + 2 + ((runLength - 4) * sIdx) / steps;
+                const x = park.center[0] + (alongX ? along : offset);
+                const z = park.center[1] + (alongX ? offset : along);
+                // Rows follow the field's road-derived polygon: a curved block edge ends the row early.
+                const outside = park.polygon !== undefined && !pointInPolygon(park.polygon, x, z);
+                const blocked = outside || placed.overlapsAny({ x, z, hw: 1.2, hd: 1.2, angle: 0 }, 1.5);
+                if (blocked) {
+                    if (current.length >= 2)
+                        rows.push(current);
+                    current = [];
+                }
+                else {
+                    current.push([x, z]);
+                }
+            }
+            if (current.length >= 2)
+                rows.push(current);
+            total += 1;
+        }
+        if (rows.length > 0)
+            park.rows = rows;
+    }
+}
+/**
+ * Synthesize the deterministic city plan for one `city` volume: streets → bridges → parks → zoned
+ * frontage lots with massing pieces → furniture, all in the volume's local frame and then
+ * rotated/translated into world space. Same volume (id, footprint, meta) over the same terrain
+ * always resolves to the identical plan. When `context` provides a ground sampler, lots respect
+ * the `maxSlope` cliff rule — hillside and canyon districts keep their steep faces open. When
+ * `context.zoneOverrides` carries sibling `cityzone` volumes, lots inside them adopt the override
+ * band/mix. Returns null without a usable footprint.
+ *
+ * @capability city-district resolve a `city` volume into deterministic streets, zoned lots, parks, and furniture
+ */
+export function resolveCityObject(object, context) {
+    const center = object.center ?? object.position;
+    if (center === undefined)
+        return null;
+    const he = object.halfExtents;
+    const hx = axisValue(he?.x) ?? object.radius ?? 0;
+    const hz = axisValue(he?.z) ?? object.radius ?? 0;
+    const rules = readCityRules(object.meta);
+    const rotationY = object.rotationY ?? 0;
+    const empty = {
+        center: [center.x, center.y, center.z],
+        size: [hx * 2, hz * 2],
+        rotationY,
+        rules,
+        streets: [],
+        intersections: [],
+        bridges: [],
+        tunnels: [],
+        blocks: [],
+        parcels: [],
+        lots: [],
+        parks: [],
+        trees: [],
+        lights: [],
+        hedges: [],
+        driveways: [],
+        parkingLots: [],
+    };
+    if (hx < rules.blockSize * 0.75 || hz < rules.blockSize * 0.75)
+        return empty;
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    const toWorld = (x, z) => [center.x + x * cos + z * sin, center.z - x * sin + z * cos];
+    const sampleHeight = context?.sampleHeight;
+    const heightAt = sampleHeight === undefined
+        ? null
+        : (x, z) => {
+            const [wx, wz] = toWorld(x, z);
+            return sampleHeight(wx, wz);
+        };
+    const slopeAt = sampleHeight === undefined
+        ? null
+        : (x, z) => {
+            const [wx, wz] = toWorld(x, z);
+            const d = 4;
+            const dx = sampleHeight(wx + d, wz) - sampleHeight(wx - d, wz);
+            const dz = sampleHeight(wx, wz + d) - sampleHeight(wx, wz - d);
+            return Math.hypot(dx, dz) / (2 * d);
+        };
+    // Child `cityzone` volumes override the band (and optionally the class mix) for lots inside them.
+    const overrides = (context?.zoneOverrides ?? []).filter((volume) => volume.kind === CITY_ZONE_KIND);
+    const overrideAt = overrides.length === 0
+        ? null
+        : (x, z) => {
+            const [wx, wz] = toWorld(x, z);
+            for (const volume of overrides) {
+                const vc = volume.center ?? volume.position;
+                if (vc === undefined)
+                    continue;
+                const vhx = axisValue(volume.halfExtents?.x) ?? volume.radius ?? 0;
+                const vhz = axisValue(volume.halfExtents?.z) ?? volume.radius ?? 0;
+                if (vhx <= 0 || vhz <= 0)
+                    continue;
+                const yaw = volume.rotationY ?? 0;
+                const dx = wx - vc.x;
+                const dz = wz - vc.z;
+                const lx = dx * Math.cos(yaw) - dz * Math.sin(yaw);
+                const lz = dx * Math.sin(yaw) + dz * Math.cos(yaw);
+                if (Math.abs(lx) > vhx || Math.abs(lz) > vhz)
+                    continue;
+                const params = parseParams(CITY_ZONE_SCHEMA, volume.meta);
+                const mix = params["mix"];
+                return { band: params["band"], mix: mix.length > 0 ? mix : null };
+            }
+            return null;
+        };
+    const streams = seededStreams(`city:${rules.seed.length > 0 ? rules.seed : object.id}`);
+    // The unified path-network engine grows the whole road/track graph from the sliders — a city street
+    // net and a closed race circuit are the SAME generator at opposite slider extremes.
+    const netRules = {
+        seed: rules.seed.length > 0 ? rules.seed : object.id,
+        gridness: rules.gridness,
+        loopiness: rules.loopiness,
+        connectivity: rules.connectivity,
+        branching: rules.branching,
+        deadEnds: rules.deadEnds,
+        segmentLength: rules.blockSize,
+        aspect: rules.blockAspect,
+        winding: rules.curviness,
+        minCurveRadius: rules.minCurveRadius,
+        minTurnAngle: rules.minTurnAngle,
+        maxTurnAngle: rules.maxTurnAngle,
+        width: rules.streetWidth,
+        boulevards: rules.boulevards,
+    };
+    const network = buildPathNetwork(netRules, hx, hz, {
+        heightAt: heightAt ?? undefined,
+        minElevation: rules.minElevation,
+        bridges: rules.bridges,
+        tunnels: rules.tunnels,
+    });
+    // Resolve each generated street's surface + sidewalk from its hierarchy level.
+    const surfaceFor = (level) => rules.surface === "gravel" || (level === "lane" && rules.gravelLanes) ? "gravel" : "asphalt";
+    const local = network.streets.slice(0, MAX_STREETS).map((street) => {
+        const surface = surfaceFor(street.level);
+        return {
+            points: street.points.map(([x, z]) => [x, z]),
+            width: street.width,
+            level: street.level,
+            surface,
+            sidewalk: rules.sidewalks && surface === "asphalt",
+            ...(street.bulb === undefined ? {} : { bulb: [street.bulb[0], street.bulb[1]] }),
+            ...(street.features.length === 0 ? {} : { features: street.features }),
+        };
+    });
+    const index = new StreetIndex();
+    local.forEach((street, i) => index.addStreet(i, street.points, street.width));
+    const intersections = network.junctions
+        .slice(0, MAX_INTERSECTIONS)
+        .map((j) => ({ x: j.x, z: j.z, radius: j.radius, level: j.level, arms: j.arms.map((arm) => ({ ...arm })) }));
+    const localBridges = network.bridges.map((b) => ({
+        points: b.points.map(([x, z]) => [x, z]),
+        width: b.width,
+        bankHeight: b.bankHeight,
+    }));
+    const localTunnels = network.tunnels.map((t) => ({
+        points: t.points.map(([x, z]) => [x, z]),
+        width: t.width,
+        bankHeight: t.bankHeight,
+    }));
+    // Fabric (block/parcel/building subdivision) is optional: a bare road or race track leaves it off,
+    // so a circuit never carries forced-on plots — parcels and buildings appear only when you want it.
+    const emptyFabric = { blocks: [], parcels: [], parks: [], lots: [], placed: new LotIndex(), hedges: [], driveways: [] };
+    const lotResult = rules.fabric
+        ? buildFabric(rules, streams, local, index, hx, hz, slopeAt, heightAt, overrideAt, intersections)
+        : emptyFabric;
+    const parks = lotResult.parks;
+    if (rules.fabric)
+        buildFieldRows(parks, lotResult.placed, streams);
+    // --- Street furniture: bounded, seeded, and hooked to the network. ---
+    const trees = [];
+    const lights = [];
+    const nearIntersection = (x, z, pad) => {
+        for (const cross of intersections) {
+            if (Math.hypot(cross.x - x, cross.z - z) < cross.radius + pad)
+                return true;
+        }
+        return false;
+    };
+    const insideBounds = (x, z) => Math.abs(x) < hx - 1.5 && Math.abs(z) < hz - 1.5;
+    const asDescriptor = (street) => ({
+        kind: "road",
+        path: street.points,
+        width: street.width,
+        color: "",
+        markings: false,
+        markingColor: "",
+        elevation: 0,
+        sidewalk: street.sidewalk ? { width: 1.9, color: "" } : false,
+    });
+    if (rules.lightDensity > 0) {
+        const lightRng = streams("lights");
+        // Density drives pole spacing directly (0.1 → a pole every ~120 m; 1 → every 18 m), and at low
+        // densities only the avenue-and-up hierarchy is lit — a farm road keeps its dark sky.
+        const spacing = Math.min(120, Math.max(14, 18 / rules.lightDensity));
+        for (const street of local) {
+            if (street.level === "lane" || street.surface === "gravel")
+                continue;
+            if (rules.lightDensity < 0.3 && LEVEL_RANK[street.level] < LEVEL_RANK.avenue)
+                continue;
+            const spots = furnitureSpots(asDescriptor(street), { spacing, outset: street.sidewalk ? 0.6 : 0.2 });
+            for (const spot of spots) {
+                if (lights.length >= MAX_LIGHTS)
+                    break;
+                const [x, z] = spot.position;
+                if (!insideBounds(x, z) || nearIntersection(x, z, 1.5))
+                    continue;
+                if (index.clearance(x, z, 1.0) < 0)
+                    continue;
+                if (lightRng() > 0.95)
+                    continue; // occasional missing pole so rows never read stamped
+                // Lamp arm faces back over the road: flip the outward-facing spot heading.
+                lights.push({ x, z, heading: spot.heading + Math.PI });
+            }
+        }
+    }
+    if (rules.treeDensity > 0) {
+        const treeRng = streams("trees");
+        const spacing = 30 - 21 * rules.treeDensity;
+        for (const street of local) {
+            if (street.surface === "gravel" && rules.treeDensity < 0.6)
+                continue;
+            const spots = furnitureSpots(asDescriptor(street), { spacing, stagger: false, outset: street.sidewalk ? 2.6 : 2.0 });
+            for (const spot of spots) {
+                if (trees.length >= MAX_TREES)
+                    break;
+                if (treeRng() > rules.treeDensity * 0.85 + 0.15)
+                    continue;
+                const x = spot.position[0] + (treeRng() - 0.5) * 1.2;
+                const z = spot.position[1] + (treeRng() - 0.5) * 1.2;
+                // Keep canopies out of the crossing sight-triangle and off the carriageway edge.
+                if (!insideBounds(x, z) || nearIntersection(x, z, 5))
+                    continue;
+                if (index.clearance(x, z, 2.6) < 0)
+                    continue;
+                if (lotResult.placed.overlapsAny({ x, z, hw: 0.5, hd: 0.5, angle: 0 }, 0.5))
+                    continue;
+                trees.push({ x, z, species: pickSpecies(rules.treeMix, treeRng()), scale: 0.85 + treeRng() * 0.5, jitter: treeRng() });
+            }
+        }
+        // Park planting: formal corners on plazas, loose clusters on greens/courtyards, sparse
+        // meadows and buffers — all sampled inside the park's road-derived polygon.
+        const parkRng = streams("parkTrees");
+        for (const park of parks) {
+            if (trees.length >= MAX_TREES)
+                break;
+            const parkArea = park.polygon !== undefined ? polygonArea(park.polygon) : park.size[0] * park.size[1];
+            const count = park.type === "plaza"
+                ? 4
+                : park.type === "green" || park.type === "courtyard"
+                    ? Math.min(10, Math.max(3, Math.floor(parkArea / 260)))
+                    : park.type === "meadow"
+                        ? 2 + Math.floor(parkRng() * 4)
+                        : park.type === "buffer"
+                            ? Math.min(4, Math.floor(parkArea / 320))
+                            : 0;
+            if (count <= 0)
+                continue;
+            let spots;
+            if (park.type === "plaza") {
+                spots = [
+                    [park.center[0] - park.size[0] * 0.36, park.center[1] - park.size[1] * 0.36],
+                    [park.center[0] + park.size[0] * 0.36, park.center[1] - park.size[1] * 0.36],
+                    [park.center[0] - park.size[0] * 0.36, park.center[1] + park.size[1] * 0.36],
+                    [park.center[0] + park.size[0] * 0.36, park.center[1] + park.size[1] * 0.36],
+                ].filter(([x, z]) => park.polygon === undefined || pointInPolygon(park.polygon, x, z));
+            }
+            else if (park.polygon !== undefined) {
+                spots = pointsInPolygon(park.polygon, count, parkRng, 1.2);
+            }
+            else {
+                const random = [];
+                for (let i = 0; i < count; i += 1) {
+                    random.push([park.center[0] + (parkRng() - 0.5) * park.size[0] * 0.8, park.center[1] + (parkRng() - 0.5) * park.size[1] * 0.8]);
+                }
+                spots = random;
+            }
+            for (const [x, z] of spots) {
+                if (trees.length >= MAX_TREES)
+                    break;
+                if (!insideBounds(x, z))
+                    continue;
+                if (index.clearance(x, z, 0.4) < 0)
+                    continue;
+                if (lotResult.placed.overlapsAny({ x, z, hw: 0.5, hd: 0.5, angle: 0 }, 0.5))
+                    continue;
+                trees.push({ x, z, species: pickSpecies(rules.treeMix, parkRng()), scale: 0.9 + parkRng() * 0.6, jitter: parkRng() });
+            }
+        }
+    }
+    // Parking pads behind commercial lots, collision-checked against every placed footprint.
+    const parking = [];
+    if (rules.parking) {
+        const parkingRng = streams("parking");
+        const padIndex = new LotIndex();
+        for (const lot of lotResult.lots) {
+            if (parking.length >= MAX_PARKING)
+                break;
+            if (lot.cls !== "shop" && lot.cls !== "slab")
+                continue;
+            if (parkingRng() > 0.6)
+                continue;
+            const depth = 9 + parkingRng() * 5;
+            const ca = Math.cos(lot.rotationY);
+            const sa = Math.sin(lot.rotationY);
+            // Behind the lot: away from the street face (-z in lot-local space).
+            const off = lot.size[1] / 2 + depth / 2 + 1.2;
+            const x = lot.center[0] - sa * off;
+            const z = lot.center[1] - ca * off;
+            const pad = { x, z, hw: (lot.size[0] * 1.05) / 2, hd: depth / 2, angle: lot.rotationY };
+            if (Math.abs(x) > hx - 3 || Math.abs(z) > hz - 3)
+                continue;
+            if (index.clearance(x, z, 0.5) < 0)
+                continue;
+            if (lotResult.placed.overlapsAny(pad, 0.5) || padIndex.overlapsAny(pad, 0.5))
+                continue;
+            padIndex.add(pad);
+            parking.push({ center: [x, z], size: [lot.size[0] * 1.05, depth], rotationY: lot.rotationY });
+        }
+    }
+    return {
+        center: [center.x, center.y, center.z],
+        size: [hx * 2, hz * 2],
+        rotationY,
+        rules,
+        streets: local.map((street, i) => ({
+            id: `street:${i}`,
+            points: street.points.map(([x, z]) => toWorld(x, z)),
+            width: street.width,
+            level: street.level,
+            surface: street.surface,
+            sidewalk: street.sidewalk,
+            ...(street.bulb === undefined ? {} : { bulb: toWorld(street.bulb[0], street.bulb[1]) }),
+            ...(street.features === undefined ? {} : { features: street.features.map((f) => ({ ...f })) }),
+        })),
+        intersections: intersections.map((cross, i) => {
+            const [x, z] = toWorld(cross.x, cross.z);
+            return {
+                id: `cross:${i}`,
+                x,
+                z,
+                radius: cross.radius,
+                level: cross.level,
+                arms: cross.arms.map((arm) => ({ angle: arm.angle - rotationY, width: arm.width })),
+            };
+        }),
+        bridges: localBridges.map((bridge, i) => ({
+            id: `bridge:${i}`,
+            points: bridge.points.map(([x, z]) => toWorld(x, z)),
+            width: bridge.width,
+            style: rules.bridgeStyle,
+            bankHeight: bridge.bankHeight,
+        })),
+        tunnels: localTunnels.map((tunnel, i) => ({
+            id: `tunnel:${i}`,
+            points: tunnel.points.map(([x, z]) => toWorld(x, z)),
+            width: tunnel.width,
+            bankHeight: tunnel.bankHeight,
+        })),
+        blocks: lotResult.blocks.map((block) => ({
+            id: block.id,
+            kind: block.kind,
+            polygon: block.polygon.map(([x, z]) => toWorld(x, z)),
+            curb: block.curb.map(([x, z]) => toWorld(x, z)),
+            area: block.area,
+        })),
+        parcels: lotResult.parcels.map((parcel) => ({
+            id: parcel.id,
+            block: lotResult.blocks[parcel.block]?.id ?? `block:${parcel.block}`,
+            polygon: parcel.polygon.map(([x, z]) => toWorld(x, z)),
+            buildable: parcel.buildable.map(([x, z]) => toWorld(x, z)),
+            frontage: parcel.frontage.map((front) => ({
+                road: `street:${front.street}`,
+                edgeStart: toWorld(front.a[0], front.a[1]),
+                edgeEnd: toWorld(front.b[0], front.b[1]),
+                tangent: [
+                    front.tangent[0] * Math.cos(rotationY) + front.tangent[1] * Math.sin(rotationY),
+                    -front.tangent[0] * Math.sin(rotationY) + front.tangent[1] * Math.cos(rotationY),
+                ],
+            })),
+            area: parcel.area,
+            depth: parcel.depth,
+            isCorner: parcel.isCorner,
+            kind: parcel.kind,
+        })),
+        lots: lotResult.lots.map((lot) => ({
+            id: lot.id,
+            center: toWorld(lot.center[0], lot.center[1]),
+            size: lot.size,
+            rotationY: lot.rotationY - rotationY,
+            floors: lot.floors,
+            jitter: lot.jitter,
+            class: lot.cls,
+            zone: lot.zone,
+            anchor: toWorld(lot.anchor[0], lot.anchor[1]),
+            pieces: lot.pieces,
+            parcel: lot.parcel,
+        })),
+        parks: parks.map((park) => ({
+            id: park.id,
+            center: toWorld(park.center[0], park.center[1]),
+            size: park.size,
+            rotationY: -rotationY,
+            type: park.type,
+            jitter: park.jitter,
+            ...(park.polygon === undefined ? {} : { polygon: park.polygon.map(([x, z]) => toWorld(x, z)) }),
+            ...(park.rows === undefined ? {} : { rows: park.rows.map((row) => row.map(([x, z]) => toWorld(x, z))) }),
+        })),
+        trees: trees.map((tree) => {
+            const [x, z] = toWorld(tree.x, tree.z);
+            return { x, z, species: tree.species, scale: tree.scale, jitter: tree.jitter };
+        }),
+        lights: lights.map((light) => {
+            const [x, z] = toWorld(light.x, light.z);
+            return { x, z, heading: light.heading - rotationY };
+        }),
+        hedges: lotResult.hedges.map((hedge) => {
+            const [x, z] = toWorld(hedge.center[0], hedge.center[1]);
+            return { center: [x, z], size: hedge.size, rotationY: hedge.rotationY - rotationY };
+        }),
+        driveways: lotResult.driveways.map((drive) => ({
+            points: drive.points.map(([x, z]) => toWorld(x, z)),
+            width: drive.width,
+            surface: drive.surface,
+        })),
+        parkingLots: parking.map((pad) => {
+            const [x, z] = toWorld(pad.center[0], pad.center[1]);
+            return { center: [x, z], size: pad.size, rotationY: pad.rotationY - rotationY };
+        }),
+    };
+}
+/** Registers the `city` + `cityzone` scene kinds (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerCityKind() {
+    registerSceneKind({
+        kind: CITY_KIND,
+        target: "volume",
+        label: "City / track",
+        addCategory: "Studios",
+        accent: "#8fa8c9",
+        schema: CITY_SCHEMA,
+        resolve: (object, _params, context) => resolveCityObject(object, context),
+        note: (object) => {
+            const resolved = resolveCityObject(object);
+            if (resolved === null)
+                return "Give the volume a box footprint.";
+            if (resolved.streets.length === 0)
+                return `Footprint too small — needs at least ${Math.ceil(resolved.rules.blockSize * 1.5)} m across.`;
+            const mode = pathNetworkMode({
+                seed: resolved.rules.seed,
+                gridness: resolved.rules.gridness,
+                loopiness: resolved.rules.loopiness,
+                connectivity: resolved.rules.connectivity,
+                branching: resolved.rules.branching,
+                deadEnds: resolved.rules.deadEnds,
+                segmentLength: resolved.rules.blockSize,
+                aspect: resolved.rules.blockAspect,
+                winding: resolved.rules.curviness,
+                minCurveRadius: resolved.rules.minCurveRadius,
+                minTurnAngle: resolved.rules.minTurnAngle,
+                maxTurnAngle: resolved.rules.maxTurnAngle,
+                width: resolved.rules.streetWidth,
+                boulevards: resolved.rules.boulevards,
+            });
+            const feats = [
+                resolved.bridges.length > 0 ? `${resolved.bridges.length} bridges` : "",
+                resolved.tunnels.length > 0 ? `${resolved.tunnels.length} tunnels` : "",
+            ].filter((s) => s.length > 0);
+            const head = mode === "circuit" ? `circuit · ${resolved.streets.length} streets` : `${resolved.streets.length} streets`;
+            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings · ${resolved.parks.length} parks` : " · no fabric";
+            return `${head}${fabric}${feats.length > 0 ? ` · ${feats.join(" · ")}` : ""}`;
+        },
+    });
+    registerSceneKind({
+        kind: CITY_ZONE_KIND,
+        target: "volume",
+        label: "City zone override",
+        addCategory: "Studios",
+        accent: "#c9b88f",
+        schema: CITY_ZONE_SCHEMA,
+        note: (object) => {
+            const params = parseParams(CITY_ZONE_SCHEMA, object.meta);
+            const mix = params["mix"];
+            return `Pins the "${params["band"]}" band${mix.length > 0 ? " with a custom mix" : ""} inside any city district it overlaps.`;
+        },
+    });
+}