@jgengine/core 0.12.0 → 0.13.0

package/dist/ui/panelModel.js

@@ -0,0 +1,168 @@
+/**
+ * Headless, serializable model for a set of player-toggled windows/panels — the data layer behind a
+ * WoW-style UI where B opens the bag, C the character sheet, and ESC closes the topmost window. It
+ * carries *which panels are open*, their focus/z stacking order, per-panel position overrides, and
+ * exclusive-group membership, with zero rendering opinion. The React chrome in
+ * `@jgengine/react/panels` consumes this; a game keeps layout, skin, keybinds, and window content
+ * caller-owned. Pure and immutable: every reducer returns a new state and never mutates its input.
+ */
+/**
+ * Build the initial {@link PanelState} from the panel defs: panels flagged `initial` start open (in
+ * declaration order, respecting group exclusivity), and every def's group/closable is captured into
+ * the state so later reducers need no defs.
+ *
+ * @capability panel-state serializable open/z/position state for a set of toggleable game windows
+ */
+export function createPanelState(defs) {
+    const meta = {};
+    for (const def of defs) {
+        const entry = {};
+        if (def.group !== undefined)
+            entry.group = def.group;
+        if (def.closable !== undefined)
+            entry.closable = def.closable;
+        meta[def.id] = entry;
+    }
+    let state = { open: {}, z: {}, pos: {}, meta, nextZ: 1 };
+    for (const def of defs) {
+        if (def.initial === true)
+            state = openPanel(state, def.id);
+    }
+    return state;
+}
+/** Whether panel `id` is currently open. */
+export function isOpen(state, id) {
+    return state.open[id] === true;
+}
+/** @internal Whether panel `id` may be closed by the player (default true). */
+function isClosable(state, id) {
+    return state.meta[id]?.closable !== false;
+}
+/**
+ * Open panel `id`, raising it to the top of the focus stack. If it belongs to a `group`, the other
+ * open panels in that group are closed (exclusive windows). Opening an already-open panel just
+ * refocuses it. Position overrides are preserved.
+ *
+ * @capability panel-open open a window, raise its z, and enforce exclusive-group membership
+ */
+export function openPanel(state, id) {
+    const group = state.meta[id]?.group;
+    const open = { ...state.open };
+    const z = { ...state.z };
+    let nextZ = state.nextZ;
+    if (group !== undefined) {
+        for (const otherId of Object.keys(open)) {
+            if (otherId !== id && state.meta[otherId]?.group === group) {
+                delete open[otherId];
+                delete z[otherId];
+            }
+        }
+    }
+    open[id] = true;
+    z[id] = nextZ++;
+    return { ...state, open, z, nextZ };
+}
+/**
+ * Close panel `id`. No-op if it is already closed. Its position override is kept so reopening restores
+ * the last placement.
+ *
+ * @capability panel-close close a window while remembering its last position
+ */
+export function closePanel(state, id) {
+    if (state.open[id] !== true)
+        return state;
+    const open = { ...state.open };
+    const z = { ...state.z };
+    delete open[id];
+    delete z[id];
+    return { ...state, open, z };
+}
+/**
+ * Toggle panel `id` — open it (with group exclusivity) if closed, close it if open. The one-key
+ * behavior behind a keybind like `B` for the bag.
+ *
+ * @capability panel-toggle toggle a window open/closed from a single keybind
+ */
+export function togglePanel(state, id) {
+    return isOpen(state, id) ? closePanel(state, id) : openPanel(state, id);
+}
+/**
+ * Raise open panel `id` to the top of the focus stack (assign it the highest z). No-op if it is
+ * closed or already on top, so a pointer-down that refocuses the top window returns the same state.
+ *
+ * @capability panel-focus raise a window to the top of the focus/z stack
+ */
+export function focusPanel(state, id) {
+    if (state.open[id] !== true)
+        return state;
+    if (topPanel(state) === id)
+        return state;
+    return { ...state, z: { ...state.z, [id]: state.nextZ }, nextZ: state.nextZ + 1 };
+}
+/** @internal The id of the top (highest-z) open panel, or null when none are open. */
+function topPanel(state) {
+    let top = null;
+    let topZ = -Infinity;
+    for (const id of Object.keys(state.open)) {
+        const value = state.z[id] ?? 0;
+        if (value > topZ) {
+            topZ = value;
+            top = id;
+        }
+    }
+    return top;
+}
+/**
+ * Close the topmost closable open panel — the ESC handler. Skips panels pinned with `closable: false`
+ * and returns the same state when nothing closable is open.
+ *
+ * @capability panel-close-top close the focused (topmost) closable window — the ESC behavior
+ */
+export function closeTopPanel(state) {
+    const ordered = orderedOpenIds(state);
+    for (let i = ordered.length - 1; i >= 0; i--) {
+        const id = ordered[i];
+        if (isClosable(state, id))
+            return closePanel(state, id);
+    }
+    return state;
+}
+/** @internal Open panel ids sorted ascending by z (render order — last is on top). */
+function orderedOpenIds(state) {
+    return Object.keys(state.open).sort((a, b) => (state.z[a] ?? 0) - (state.z[b] ?? 0));
+}
+/**
+ * Find the panel whose `hotkey` matches `code`, case-insensitively — the keybind router. `code` may be
+ * a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`); it is compared verbatim to each def's `hotkey`, so
+ * author the hotkey in whichever form the caller feeds in. Returns the first match's id, or null.
+ *
+ * @capability panel-hotkey resolve a keybind (code or key) to the panel id it toggles
+ */
+export function panelByHotkey(defs, code) {
+    const needle = code.toLowerCase();
+    for (const def of defs) {
+        if (def.hotkey !== undefined && def.hotkey.toLowerCase() === needle)
+            return def.id;
+    }
+    return null;
+}
+/**
+ * Set panel `id`'s position override — the drag commit. Does not require the panel to be open, so a
+ * caller can pre-place a window before it is shown.
+ *
+ * @capability panel-move override a window's on-surface position (the drag commit)
+ */
+export function movePanel(state, id, pos) {
+    return { ...state, pos: { ...state.pos, [id]: { x: pos.x, y: pos.y } } };
+}
+/**
+ * The open panels' defs sorted ascending by z — the render order for a window host (map to elements
+ * so the last, highest-z window paints on top). Defs unknown to the state are skipped.
+ *
+ * @capability panel-ordered-open open panels' defs in z/render order for a window host
+ */
+export function orderedOpen(state, defs) {
+    return defs
+        .filter((def) => state.open[def.id] === true)
+        .sort((a, b) => (state.z[a.id] ?? 0) - (state.z[b.id] ?? 0));
+}

package/dist/ui.d.ts

@@ -10,6 +10,7 @@ export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPan
 export { HUD_ANCHOR_FRACTIONS, type HudAnchor, type HudLayoutStore, type HudPlacement, type HudSize, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, type HudPlatform, type HudViewportConfig, } from "./ui/hudScale.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, type LayoutOrientation, } from "./ui/orientation.js";
+export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, type PanelDef, type PanelPosition, type PanelState, } from "./ui/panelModel.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, type EntitySummaryDef, type EntityVital, type SelectionFocusDirection, type SelectionGroup, type SelectionView, type SelectionWindow, type SummarizeSelectionOptions, } from "./ui/selectionModel.js";
 export { swingTimerState, type SwingTargetInput } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, type PopoverOptions, type PopoverPlacement, type PopoverSide, type TooltipContent, type UiRect, type UiSize, } from "./ui/tooltipModel.js";

package/dist/ui.js

@@ -10,6 +10,7 @@ export { listHudPanelTypes, registerHudPanelType, resizePanelSize, resolveHudPan
 export { HUD_ANCHOR_FRACTIONS, } from "./ui/hudLayout.js";
 export { hudScaleForViewport, overflowingPanels, resolveHudFit, } from "./ui/hudScale.js";
 export { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "./ui/orientation.js";
+export { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen, movePanel, openPanel, orderedOpen, panelByHotkey, togglePanel, } from "./ui/panelModel.js";
 export { moveSelectionFocus, selectionWindow, summarizeSelection, } from "./ui/selectionModel.js";
 export { swingTimerState } from "./ui/swingTimer.js";
 export { actionTooltip, placePopover, } from "./ui/tooltipModel.js";

package/dist/world/buildingLots.d.ts

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

package/dist/world/buildingLots.js

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

package/dist/world/buildings.d.ts

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

package/dist/world/cityGenerator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The seed-driven procedural CITY GENERATOR — the composition seam over the two fabric engines:
+ * {@link generateStreets} grows the street network, and {@link deriveBuildingLots} lines its
+ * frontage with street-facing building lots. One call, one seed, one deterministic city: same rules
+ * ⇒ identical streets and identical lots, with both engines' bounded-work caps intact. Local
+ * (volume-centered) coords, same as the street generator; the caller translates into world space.
+ *
+ * Street dials default to a dense, gently-varied city net (high gridness/connectivity, light
+ * winding); pass any subset of {@link StreetNetworkRules} to override, and lot options pass through
+ * to the frontage engine untouched. Lanes are skipped as lot frontage by default — buildings line
+ * boulevards, avenues, and streets — so alleys stay service alleys; opt lanes in via
+ * `lots.laneFrontage`.
+ *
+ * @capability city-generator compose a deterministic city — street network plus street-facing building lots — from one seed
+ */
+import { type BuildingLotOptions, type PlacedBuildingLot } from "./buildingLots.js";
+import { type StreetNetwork, type StreetNetworkContext, type StreetNetworkRules } from "./streetGenerator.js";
+/** Options for {@link generateCity}: a seed, street-dial overrides, and lot pass-through options. */
+export interface CityGeneratorOptions {
+    /** Drives both the street network and downstream lot/floor variation. */
+    seed: string;
+    /** Street-dial overrides; anything omitted takes the city defaults above. */
+    streets?: Partial<Omit<StreetNetworkRules, "seed">>;
+    /** Frontage-lot options, minus `roads` (the generated streets are the roads). */
+    lots?: Omit<BuildingLotOptions, "roads" | "seed"> & {
+        /** Also line `lane`-level streets (alleys) with lots. Default false. */
+        laneFrontage?: boolean;
+    };
+    /** Ground sampler + bridge/tunnel toggles forwarded to the street generator. */
+    context?: StreetNetworkContext;
+}
+/** A generated city: the street network and the building lots lining its frontage. */
+export interface GeneratedCity {
+    network: StreetNetwork;
+    lots: PlacedBuildingLot[];
+}
+/**
+ * Grow a street network inside the `hx`/`hz` half-extents and line its frontage with building lots.
+ * Deterministic: identical options ⇒ identical city.
+ */
+export declare function generateCity(options: CityGeneratorOptions, hx: number, hz: number): GeneratedCity;

package/dist/world/cityGenerator.js

@@ -0,0 +1,58 @@
+/**
+ * The seed-driven procedural CITY GENERATOR — the composition seam over the two fabric engines:
+ * {@link generateStreets} grows the street network, and {@link deriveBuildingLots} lines its
+ * frontage with street-facing building lots. One call, one seed, one deterministic city: same rules
+ * ⇒ identical streets and identical lots, with both engines' bounded-work caps intact. Local
+ * (volume-centered) coords, same as the street generator; the caller translates into world space.
+ *
+ * Street dials default to a dense, gently-varied city net (high gridness/connectivity, light
+ * winding); pass any subset of {@link StreetNetworkRules} to override, and lot options pass through
+ * to the frontage engine untouched. Lanes are skipped as lot frontage by default — buildings line
+ * boulevards, avenues, and streets — so alleys stay service alleys; opt lanes in via
+ * `lots.laneFrontage`.
+ *
+ * @capability city-generator compose a deterministic city — street network plus street-facing building lots — from one seed
+ */
+import { deriveBuildingLots } from "./buildingLots.js";
+import { isOnRoad } from "./roads.js";
+import { generateStreets, } from "./streetGenerator.js";
+/** City-shaped defaults for every street dial except the seed. */
+const CITY_STREET_DEFAULTS = {
+    gridness: 0.85,
+    loopiness: 0.35,
+    connectivity: 0.6,
+    branching: 0.25,
+    deadEnds: 0.15,
+    segmentLength: 90,
+    aspect: 1.4,
+    winding: 0.15,
+    minCurveRadius: 18,
+    minTurnAngle: 12,
+    maxTurnAngle: 110,
+    width: 9,
+    boulevards: 0.2,
+};
+/**
+ * Grow a street network inside the `hx`/`hz` half-extents and line its frontage with building lots.
+ * Deterministic: identical options ⇒ identical city.
+ */
+export function generateCity(options, hx, hz) {
+    const { seed, streets: streetOverrides, lots: lotOptions, context } = options;
+    const rules = { seed, ...CITY_STREET_DEFAULTS, ...streetOverrides };
+    const network = generateStreets(rules, hx, hz, context ?? {});
+    const { laneFrontage = false, ...lotRest } = lotOptions ?? {};
+    const frontage = network.streets
+        .filter((street) => laneFrontage || street.level !== "lane")
+        .map((street) => ({ path: street.points, width: street.width }));
+    const candidates = deriveBuildingLots({
+        ...lotRest,
+        roads: frontage,
+        seed,
+        area: lotRest.area ?? { center: [0, 0], halfExtents: [hx, hz] },
+    });
+    // The frontage engine only avoids the roads it lines; streets excluded from frontage (lanes by
+    // default) are still pavement, so drop any lot whose footprint would straddle one.
+    const clearance = Math.min(lotRest.footprint?.w ?? 12, lotRest.footprint?.d ?? 10);
+    const lots = candidates.filter((lot) => network.streets.every((street) => !isOnRoad(street.points, street.width + clearance, lot.center[0], lot.center[1])));
+    return { network, lots };
+}

package/dist/world/cityKind.d.ts

@@ -2,7 +2,7 @@ import { type ParamSchema, type SceneKindObject, type SceneKindResolveContext, t
 import { type BuildingStyle } from "./buildings.js";
 import { type CityLotClass, type CityLotPiece, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile } from "./cityContent.js";
 import type { RoadPoint } from "./roads.js";
-import { type PathFeatureKind } from "./pathNetwork.js";
+import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
 /** The editor volume kind marking a box as a procedural city district. */
 export declare const CITY_KIND = "city";
@@ -130,7 +130,7 @@ export interface CityStreet {
     bulb?: RoadPoint;
     /** Bridge/tunnel spans along this street as `[from, to]` index windows into `points`. */
     features?: readonly {
-        kind: PathFeatureKind;
+        kind: StreetFeatureKind;
         from: number;
         to: number;
         bankHeight: number;

package/dist/world/cityKind.js

@@ -3,7 +3,7 @@
  * 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
+ * {@link generateStreets} 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
@@ -32,7 +32,7 @@ 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 { generateStreets, streetNetworkMode, } from "./streetGenerator.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. */
@@ -1215,7 +1215,7 @@ export function resolveCityObject(object, context) {
         width: rules.streetWidth,
         boulevards: rules.boulevards,
     };
-    const network = buildPathNetwork(netRules, hx, hz, {
+    const network = generateStreets(netRules, hx, hz, {
         heightAt: heightAt ?? undefined,
         minElevation: rules.minElevation,
         bridges: rules.bridges,
@@ -1537,7 +1537,7 @@ export function registerCityKind() {
                 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({
+            const mode = streetNetworkMode({
                 seed: resolved.rules.seed,
                 gridness: resolved.rules.gridness,
                 loopiness: resolved.rules.loopiness,

package/dist/world/environmentSummary.js

@@ -1,7 +1,11 @@
-import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { deriveBuildingLots } from "./buildingLots.js";
 import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
+    if (descriptor.along !== undefined) {
+        return resolveFrontageBuildings(descriptor, descriptor.along);
+    }
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
     const rows = Math.max(1, Math.ceil(descriptor.count / columns));
     const spacing = descriptor.spacing;
@@ -21,6 +25,58 @@ export function resolveStructureBuildings(descriptor) {
         ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
     }).slice(0, descriptor.count);
 }
+function hashU32(input) {
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 2246822507);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 3266489909);
+    hash ^= hash >>> 16;
+    return hash >>> 0;
+}
+/**
+ * Build one street-aware building per road-frontage lot: massed at the lot center, its `rotationY`
+ * set so the front faces the road (the renderer turns the whole building about `center`), floors
+ * rolled deterministically from the descriptor's `stories` and the lot's road/side/index.
+ */
+function resolveFrontageBuildings(descriptor, along) {
+    const seed = descriptor.seed ?? "buildings";
+    const lots = deriveBuildingLots({
+        roads: along.roads,
+        footprint: descriptor.footprint,
+        spacing: descriptor.spacing,
+        maxLots: descriptor.count,
+        seed: `${seed}:lots`,
+        ...(along.setback === undefined ? {} : { setback: along.setback }),
+        ...(along.bothSides === undefined ? {} : { bothSides: along.bothSides }),
+        ...(along.area === undefined ? {} : { area: along.area }),
+    });
+    const [floorsMin, floorsMax] = descriptor.stories;
+    const bayWidth = DEFAULT_BUILDING_CONFIG.bayWidth;
+    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight));
+}
+function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight) {
+    const lo = Math.min(floorsMin, floorsMax);
+    const hi = Math.max(floorsMin, floorsMax);
+    const floors = lo + Math.floor((hashU32(`${seed}:floors:${index}`) / 4294967296) * (hi - lo + 1));
+    const baysWide = Math.max(1, Math.floor(lot.footprint.w / bayWidth));
+    const baysDeep = Math.max(1, Math.floor(lot.footprint.d / bayWidth));
+    const building = generateBuilding({
+        id: `frontage-${index}`,
+        seed: `${seed}:${index}`,
+        center: lot.center,
+        floors,
+        baysWide,
+        baysDeep,
+        bayWidth,
+        floorHeight: storyHeight,
+    });
+    return { ...building, rotationY: lot.rotationY };
+}
 const TERRAIN_SAMPLE_RESOLUTION = 16;
 function sampleTerrainHeights(descriptor) {
     const field = resolveTerrainField(descriptor);