@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/world/scatterCoverage.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The shared "how much stuff grows here" contract for scatterable scene kinds
+ * (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances
+ * at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request
+ * can never generate unbounded work. Before this module each kind hand-rolled its own readout and
+ * clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note);
+ * this is the one place that
+ *
+ * 1. names the per-kind unit noun + placement budget ({@link SCATTER_COVERAGE_SPECS}),
+ * 2. turns an area + density into a `requested` / placed `count` / `capped` triple
+ *    ({@link densityCoverage}, {@link placedCoverage}), and
+ * 3. renders the identical clamp-and-warn clause the inspector surfaces —
+ *    `requested N, capped at M (budget)` — via {@link budgetWarning} / {@link describeScatterCoverage}.
+ *
+ * Pure data + string helpers, no rendering. Each kind's `note` and the editor's shared
+ * `CoverageSection` consume it, so grass, scatter, and city tell one coverage story.
+ *
+ * @capability scatter-coverage shared density/budget semantics for scatterable kinds
+ */
+/** The scatterable kinds that share the coverage contract. */
+export type ScatterCoverageKind = "grass_field" | "scatter" | "city";
+/**
+ * Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass
+ * renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never
+ * renders more than this many placements regardless of density × area.
+ */
+export declare const SCATTER_INSTANCE_BUDGET = 250000;
+/** Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap. */
+export declare const CITY_BUILDING_BUDGET = 2600;
+/** Per-kind coverage descriptor: the unit noun, whether density is per-m², and the placement budget. */
+export interface ScatterCoverageSpec {
+    kind: ScatterCoverageKind;
+    /** Plural noun for one placed instance: `blades` | `placements` | `buildings`. */
+    unit: string;
+    /** Density is per-square-meter (grass/scatter). City fills by street fabric, not by a per-m² dial. */
+    perArea: boolean;
+    /** Hard cap on placed instances for one patch/district. */
+    budget: number;
+}
+/** The coverage spec per scatterable kind — the single source for its unit + budget. */
+export declare const SCATTER_COVERAGE_SPECS: Record<ScatterCoverageKind, ScatterCoverageSpec>;
+/** The coverage spec for a scatterable kind, or `null` when the kind is not scatterable. */
+export declare function scatterCoverageSpec(kind: string): ScatterCoverageSpec | null;
+/**
+ * A resolved coverage readout: how many instances an authored patch WANTS (`requested`, when it can
+ * be computed cheaply from geometry × density), how many it will actually place after the budget
+ * clamp (`count`), the `budget` ceiling, and whether the request hit it (`capped`). `requested` is
+ * `null` for kinds whose pre-cap ask is not knowable without running the generator (city, where the
+ * count comes from the resolved street fabric).
+ */
+export interface ScatterCoverage {
+    kind: ScatterCoverageKind;
+    unit: string;
+    /** Footprint area in m² (0 when unknown / not applicable). */
+    area: number;
+    /** Instances the density asks for before the budget clamp; `null` when only the placed count is known. */
+    requested: number | null;
+    /** Instances actually placed: `min(requested, budget)`, or the generator's reported count. */
+    count: number;
+    budget: number;
+    capped: boolean;
+}
+/**
+ * Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box
+ * (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor
+ * volume, or a scatter path without a hard type dependency.
+ */
+export declare function scatterFootprintArea(object: {
+    points?: readonly {
+        x: number;
+        z: number;
+    }[];
+    halfExtents?: {
+        x: number;
+        z: number;
+    };
+    radius?: number;
+}): number;
+/**
+ * Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped
+ * to the kind's budget. `capped` is true when the request exceeds the budget.
+ */
+export declare function densityCoverage(kind: "grass_field" | "scatter", area: number, density: number): ScatterCoverage;
+/**
+ * Coverage for a kind whose placed `count` is already known from its generator (city, from its
+ * resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so
+ * `capped` is inferred from the placed count reaching the ceiling.
+ */
+export declare function placedCoverage(kind: ScatterCoverageKind, area: number, placed: number): ScatterCoverage;
+/**
+ * The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when
+ * under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or
+ * ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent"
+ * budget signal from #1112.
+ */
+export declare function budgetWarning(coverage: ScatterCoverage): string;
+/** The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped. */
+export declare function describeScatterCoverage(coverage: ScatterCoverage): string;

package/dist/world/scatterCoverage.js

@@ -0,0 +1,101 @@
+/**
+ * The shared "how much stuff grows here" contract for scatterable scene kinds
+ * (`grass_field` / `scatter` / `city`). Every scatterable kind fills an authored AREA with instances
+ * at a DENSITY, and every kind caps the placed count at a bounded BUDGET so a huge or dense request
+ * can never generate unbounded work. Before this module each kind hand-rolled its own readout and
+ * clamp story (grass silently capped in the renderer, scatter never capped, city had no budget note);
+ * this is the one place that
+ *
+ * 1. names the per-kind unit noun + placement budget ({@link SCATTER_COVERAGE_SPECS}),
+ * 2. turns an area + density into a `requested` / placed `count` / `capped` triple
+ *    ({@link densityCoverage}, {@link placedCoverage}), and
+ * 3. renders the identical clamp-and-warn clause the inspector surfaces —
+ *    `requested N, capped at M (budget)` — via {@link budgetWarning} / {@link describeScatterCoverage}.
+ *
+ * Pure data + string helpers, no rendering. Each kind's `note` and the editor's shared
+ * `CoverageSection` consume it, so grass, scatter, and city tell one coverage story.
+ *
+ * @capability scatter-coverage shared density/budget semantics for scatterable kinds
+ */
+/**
+ * Max blade/placement instances a single `grass_field` or `scatter` patch places. Mirrors the grass
+ * renderer's instance-buffer ceiling; the scatter resolver truncates to it too, so a patch never
+ * renders more than this many placements regardless of density × area.
+ */
+export const SCATTER_INSTANCE_BUDGET = 250_000;
+/** Max buildings a single `city` district generates — the block/parcel pipeline's bounded lot cap. */
+export const CITY_BUILDING_BUDGET = 2_600;
+/** The coverage spec per scatterable kind — the single source for its unit + budget. */
+export const SCATTER_COVERAGE_SPECS = {
+    grass_field: { kind: "grass_field", unit: "blades", perArea: true, budget: SCATTER_INSTANCE_BUDGET },
+    scatter: { kind: "scatter", unit: "placements", perArea: true, budget: SCATTER_INSTANCE_BUDGET },
+    city: { kind: "city", unit: "buildings", perArea: false, budget: CITY_BUILDING_BUDGET },
+};
+/** The coverage spec for a scatterable kind, or `null` when the kind is not scatterable. */
+export function scatterCoverageSpec(kind) {
+    return SCATTER_COVERAGE_SPECS[kind] ?? null;
+}
+const nonNegative = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
+/**
+ * Footprint area (m²) of a scatterable object: a closed path polygon (shoelace), a volume box
+ * (`halfExtents`), or a disc (`radius`). Structural so it accepts a `SceneKindObject`, an editor
+ * volume, or a scatter path without a hard type dependency.
+ */
+export function scatterFootprintArea(object) {
+    const points = object.points;
+    if (points !== undefined && points.length >= 3) {
+        let sum = 0;
+        for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+            sum += points[j].x * points[i].z - points[i].x * points[j].z;
+        }
+        return Math.abs(sum) / 2;
+    }
+    const he = object.halfExtents;
+    if (he !== undefined)
+        return nonNegative(Math.abs(he.x) * 2) * nonNegative(Math.abs(he.z) * 2);
+    if (object.radius !== undefined)
+        return Math.PI * nonNegative(object.radius) ** 2;
+    return 0;
+}
+/**
+ * Coverage for a per-m² kind (`grass_field` / `scatter`): `requested = floor(density × area)`, clamped
+ * to the kind's budget. `capped` is true when the request exceeds the budget.
+ */
+export function densityCoverage(kind, area, density) {
+    const spec = SCATTER_COVERAGE_SPECS[kind];
+    const a = nonNegative(area);
+    const requested = Math.floor(nonNegative(density) * a);
+    const count = Math.min(requested, spec.budget);
+    return { kind, unit: spec.unit, area: a, requested, count, budget: spec.budget, capped: requested > spec.budget };
+}
+/**
+ * Coverage for a kind whose placed `count` is already known from its generator (city, from its
+ * resolved lots). No pre-cap `requested` is available — the generator stops at the budget — so
+ * `capped` is inferred from the placed count reaching the ceiling.
+ */
+export function placedCoverage(kind, area, placed) {
+    const spec = SCATTER_COVERAGE_SPECS[kind];
+    const count = Math.max(0, Math.floor(nonNegative(placed)));
+    return { kind, unit: spec.unit, area: nonNegative(area), requested: null, count, budget: spec.budget, capped: count >= spec.budget };
+}
+const fmt = (n) => Math.round(n).toLocaleString();
+/**
+ * The shared clamp-and-warn clause every scatterable kind appends, worded identically: `""` when
+ * under budget, else ` · requested N, capped at M (budget)` when the pre-cap ask is known, or
+ * ` · capped at M (budget)` when only the ceiling is (city). This is the "surfaced, never silent"
+ * budget signal from #1112.
+ */
+export function budgetWarning(coverage) {
+    if (!coverage.capped)
+        return "";
+    if (coverage.requested !== null && coverage.requested > coverage.budget) {
+        return ` · requested ${fmt(coverage.requested)}, capped at ${fmt(coverage.budget)} (budget)`;
+    }
+    return ` · capped at ${fmt(coverage.budget)} (budget)`;
+}
+/** The full one-line coverage readout: `≈ N unit · A m²` plus the {@link budgetWarning} when capped. */
+export function describeScatterCoverage(coverage) {
+    const head = `≈ ${fmt(coverage.count)} ${coverage.unit}`;
+    const area = coverage.area > 0 ? ` · ${fmt(coverage.area)} m²` : "";
+    return `${head}${area}${budgetWarning(coverage)}`;
+}

package/dist/world/scatterRegion.js

@@ -1,5 +1,6 @@
 import { masksInfluence, } from "./geometry.js";
 import { scatter } from "./scatter.js";
+import { SCATTER_INSTANCE_BUDGET } from "./scatterCoverage.js";
 /** The editor path kind that marks a closed polyline as a foliage/scatter region. */
 export const SCATTER_PATH_KIND = "scatter";
 /** Defaults a bare scatter region fills with: sparse grass, lightly spaced. */
@@ -192,6 +193,11 @@ export function resolveScatterRegion(region, terrain, avoid) {
             scale: rules.minScale + (rules.maxScale - rules.minScale) * scaleRoll,
             ...(normal === undefined ? {} : { normal }),
         });
+        // Bounded work: a single region never emits more than the shared instance budget, matching the
+        // grass patch cap so the inspector's "capped at N (budget)" note is truthful. Placements are
+        // generated in deterministic scatter order, so the truncated set is deterministic too.
+        if (instances.length >= SCATTER_INSTANCE_BUDGET)
+            break;
     }
     return instances;
 }

package/dist/world/sharedAnnotations.d.ts

@@ -0,0 +1,84 @@
+import type { AnnotationLayer } from "./mapAnnotations.js";
+import type { MapLayerTone, MapZoneShape } from "./mapLayers.js";
+import type { WorldXZ } from "./minimap.js";
+/** Feed action shared drawings ride by default (pair with the party feed, like pings). */
+export declare const ANNOTATION_FEED_ACTION = "map.annotation";
+/** A serializable map-annotation edit broadcast to other players. */
+export type AnnotationBroadcast = {
+    op: "stroke";
+    from: string;
+    id: string;
+    points: readonly WorldXZ[];
+    tone?: MapLayerTone;
+    width?: number;
+} | {
+    op: "shape";
+    from: string;
+    id: string;
+    shape: MapZoneShape;
+    tone?: MapLayerTone;
+    label?: string;
+} | {
+    op: "note";
+    from: string;
+    id: string;
+    position: WorldXZ;
+    text: string;
+    tone?: MapLayerTone;
+} | {
+    op: "remove";
+    from: string;
+    id: string;
+} | {
+    op: "clear";
+    from: string;
+};
+/** The feed sink shared annotations push to — an alias of the ping/feed `push` seam. */
+export interface AnnotationFeedSink {
+    push(action: string, entry: unknown): void;
+}
+/** Construction options for {@link createSharedAnnotations}. */
+export interface SharedAnnotationsDeps {
+    /** The local annotation layer edits apply to (and inbound edits mirror into). */
+    layer: AnnotationLayer;
+    /** Feed to broadcast local edits on (typically `ctx.game.feed`). */
+    feed: AnnotationFeedSink;
+    /** This player's id — stamped on broadcasts and used to drop our own echoes. */
+    from: string;
+    /** Feed action to publish/consume. Default {@link ANNOTATION_FEED_ACTION}. */
+    action?: string;
+}
+/**
+ * Local annotation edits that also broadcast, plus `apply` for inbound edits.
+ * `add*`/`remove`/`clear` mirror {@link AnnotationLayer} but return globally-unique
+ * ids so two clients never collide.
+ */
+export interface SharedAnnotations {
+    addStroke(points: readonly WorldXZ[], options?: {
+        tone?: MapLayerTone;
+        width?: number;
+    }): string;
+    addShape(shape: MapZoneShape, options?: {
+        tone?: MapLayerTone;
+        label?: string;
+    }): string;
+    addNote(position: WorldXZ, text: string, options?: {
+        tone?: MapLayerTone;
+    }): string;
+    remove(id: string): boolean;
+    clear(): void;
+    /** Mirror an inbound broadcast from another player; own echoes (matching `from`) are ignored. */
+    apply(payload: AnnotationBroadcast): void;
+    feedAction: string;
+}
+/**
+ * Make a map annotation layer collaborative: local `addStroke`/`addShape`/
+ * `addNote`/`remove`/`clear` apply then broadcast a serializable edit over the
+ * party feed (the same seam `createPingSystem` uses), and `apply` mirrors inbound
+ * edits from other players — dropping our own echoes. Ids are globally unique per
+ * client so two players' strokes never collide. Transport-agnostic: wire `feed`
+ * to any replicated feed and route received entries into `apply`.
+ *
+ * @capability shared-annotations broadcast local map-drawing edits over the party feed and mirror inbound edits — collaborative annotations over any replicated feed
+ */
+export declare function createSharedAnnotations(deps: SharedAnnotationsDeps): SharedAnnotations;

package/dist/world/sharedAnnotations.js

@@ -0,0 +1,76 @@
+/** Feed action shared drawings ride by default (pair with the party feed, like pings). */
+export const ANNOTATION_FEED_ACTION = "map.annotation";
+/**
+ * Make a map annotation layer collaborative: local `addStroke`/`addShape`/
+ * `addNote`/`remove`/`clear` apply then broadcast a serializable edit over the
+ * party feed (the same seam `createPingSystem` uses), and `apply` mirrors inbound
+ * edits from other players — dropping our own echoes. Ids are globally unique per
+ * client so two players' strokes never collide. Transport-agnostic: wire `feed`
+ * to any replicated feed and route received entries into `apply`.
+ *
+ * @capability shared-annotations broadcast local map-drawing edits over the party feed and mirror inbound edits — collaborative annotations over any replicated feed
+ */
+export function createSharedAnnotations(deps) {
+    const { layer, feed, from } = deps;
+    const action = deps.action ?? ANNOTATION_FEED_ACTION;
+    let counter = 0;
+    function nextId() {
+        counter += 1;
+        return `${from}:${counter}`;
+    }
+    function broadcast(payload) {
+        feed.push(action, payload);
+    }
+    return {
+        feedAction: action,
+        addStroke(points, options = {}) {
+            const id = nextId();
+            layer.addStroke(points, { id, ...options });
+            broadcast({ op: "stroke", from, id, points: points.map((p) => [p[0], p[1]]), ...options });
+            return id;
+        },
+        addShape(shape, options = {}) {
+            const id = nextId();
+            layer.addShape(shape, { id, ...options });
+            broadcast({ op: "shape", from, id, shape, ...options });
+            return id;
+        },
+        addNote(position, text, options = {}) {
+            const id = nextId();
+            layer.addNote(position, text, { id, ...options });
+            broadcast({ op: "note", from, id, position: [position[0], position[1]], text, ...options });
+            return id;
+        },
+        remove(id) {
+            const existed = layer.remove(id);
+            if (existed)
+                broadcast({ op: "remove", from, id });
+            return existed;
+        },
+        clear() {
+            layer.clear();
+            broadcast({ op: "clear", from });
+        },
+        apply(payload) {
+            if (payload.from === from)
+                return; // ignore our own echo
+            switch (payload.op) {
+                case "stroke":
+                    layer.addStroke(payload.points, { id: payload.id, tone: payload.tone, width: payload.width });
+                    return;
+                case "shape":
+                    layer.addShape(payload.shape, { id: payload.id, tone: payload.tone, label: payload.label });
+                    return;
+                case "note":
+                    layer.addNote(payload.position, payload.text, { id: payload.id, tone: payload.tone });
+                    return;
+                case "remove":
+                    layer.remove(payload.id);
+                    return;
+                case "clear":
+                    layer.clear();
+                    return;
+            }
+        },
+    };
+}

package/dist/world/spawnOverride.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-session player-spawn override — a capture-harness ergonomics seam that lets a single
+ * screenshot or drive run place the player somewhere other than the authored `player_spawn`
+ * marker *without mutating `editor.scene.json`*. The runner installs one from the `?spawn=` URL
+ * overlay (mirroring `?cam=`); {@link authoredSpawnPosition} consults it for the default
+ * player-spawn resolution only, so authored content is untouched and the override evaporates the
+ * moment the page reloads without the param.
+ *
+ * Genre-agnostic: it moves whatever a game treats as its player spawn. It never changes markers of
+ * other kinds or an explicit marker `id`, so an override taken for a close-up cannot perturb enemy
+ * or prop placement queries that share {@link authoredSpawnPosition}.
+ *
+ * Install-style module state is the established runner pattern here (`installAssetBase`,
+ * `installEditorHost`, `installSaveEndpoint`); the default is `null`, so nothing changes and every
+ * pure query stays deterministic until a runner explicitly installs an override.
+ */
+/** A spawn point that replaces the authored player spawn for one capture session. */
+export interface SpawnOverride {
+    x: number;
+    y: number;
+    z: number;
+    /** Optional facing (yaw radians); when omitted the authored/`0` rotation is kept. */
+    rotationY?: number;
+}
+/** Install (or, with `null`, clear) the active player-spawn override. Idempotent; last write wins. */
+export declare function installSpawnOverride(override: SpawnOverride | null): void;
+/** Clear any installed player-spawn override. */
+export declare function clearSpawnOverride(): void;
+/** The currently installed player-spawn override, or `null` when none is active. */
+export declare function readSpawnOverride(): SpawnOverride | null;
+/**
+ * Parse a `?spawn=` / `--spawn` value into a {@link SpawnOverride}, or `null` when it is absent or
+ * malformed. Accepts `"x,y,z"` and `"x,y,z,yaw"` (yaw in radians); whitespace around components is
+ * tolerated. A non-finite or short tuple yields `null` so a typo never silently teleports the
+ * player to `NaN`.
+ */
+export declare function parseSpawnOverride(raw: string | null | undefined): SpawnOverride | null;

package/dist/world/spawnOverride.js

@@ -0,0 +1,50 @@
+/**
+ * Per-session player-spawn override — a capture-harness ergonomics seam that lets a single
+ * screenshot or drive run place the player somewhere other than the authored `player_spawn`
+ * marker *without mutating `editor.scene.json`*. The runner installs one from the `?spawn=` URL
+ * overlay (mirroring `?cam=`); {@link authoredSpawnPosition} consults it for the default
+ * player-spawn resolution only, so authored content is untouched and the override evaporates the
+ * moment the page reloads without the param.
+ *
+ * Genre-agnostic: it moves whatever a game treats as its player spawn. It never changes markers of
+ * other kinds or an explicit marker `id`, so an override taken for a close-up cannot perturb enemy
+ * or prop placement queries that share {@link authoredSpawnPosition}.
+ *
+ * Install-style module state is the established runner pattern here (`installAssetBase`,
+ * `installEditorHost`, `installSaveEndpoint`); the default is `null`, so nothing changes and every
+ * pure query stays deterministic until a runner explicitly installs an override.
+ */
+let installed = null;
+/** Install (or, with `null`, clear) the active player-spawn override. Idempotent; last write wins. */
+export function installSpawnOverride(override) {
+    installed = override;
+}
+/** Clear any installed player-spawn override. */
+export function clearSpawnOverride() {
+    installed = null;
+}
+/** The currently installed player-spawn override, or `null` when none is active. */
+export function readSpawnOverride() {
+    return installed;
+}
+/**
+ * Parse a `?spawn=` / `--spawn` value into a {@link SpawnOverride}, or `null` when it is absent or
+ * malformed. Accepts `"x,y,z"` and `"x,y,z,yaw"` (yaw in radians); whitespace around components is
+ * tolerated. A non-finite or short tuple yields `null` so a typo never silently teleports the
+ * player to `NaN`.
+ */
+export function parseSpawnOverride(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const parts = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length < 3 || parts.length > 4)
+        return null;
+    const nums = parts.map((part) => Number(part));
+    if (nums.some((value) => !Number.isFinite(value)))
+        return null;
+    const [x, y, z, rotationY] = nums;
+    return rotationY === undefined ? { x, y, z } : { x, y, z, rotationY };
+}

package/dist/world/streetGenerator.d.ts

@@ -25,6 +25,10 @@ export interface StreetEdge {
     level: StreetLevel;
     /** True when this edge belongs to the main closed loop (circuit mode). */
     loop: boolean;
+    /** Per-point road-surface height (one per `points`), present only when `elevation > 0`. Raw
+     *  (uncapped) samples of {@link StreetNetwork.elevationAt}; the grade-limited profile lives on the
+     *  owning {@link Street.heights}. */
+    heights?: number[];
 }
 /** A feature span carried by a street: a `[from, to]` index window into the street's `points`. */
 export interface StreetFeatureSpan {
@@ -34,12 +38,19 @@ export interface StreetFeatureSpan {
     /** Ground height at each bank/portal — the deck/floor reference the renderer drapes to. */
     bankHeight: number;
 }
+/** Left/right pedestrian bands flanking a street's asphalt, as offset polylines. */
+export interface StreetSidewalks {
+    /** Polyline offset to the left of travel (parallel to `points`). */
+    left: StreetVec2[];
+    /** Polyline offset to the right of travel. */
+    right: StreetVec2[];
+}
 /** One chained through-street: a maximal run of edges through degree-2 nodes, for rendering + furniture. */
 export interface Street {
     id: number;
     /** Ordered node ids the chain visits; first === last when `loop`. */
     nodes: number[];
-    /** Smoothed, turn-clamped centerline. */
+    /** Smoothed, arc-filleted centerline. */
     points: StreetVec2[];
     width: number;
     level: StreetLevel;
@@ -49,6 +60,12 @@ export interface Street {
     bulb?: StreetVec2;
     /** Bridge/tunnel spans along this street, if any. */
     features: StreetFeatureSpan[];
+    /** Flanking pedestrian bands, present on boulevard/avenue/street levels (not lanes). */
+    sidewalks?: StreetSidewalks;
+    /** Per-point road-surface height (one per `points`), present only when `elevation > 0`. Grade-limited
+     *  so no consecutive pair exceeds `maxGrade`; a loop stays continuous (`heights[0] === heights.at(-1)`).
+     *  This is ROAD elevation, not the `context.heightAt` terrain that drives bridges/tunnels. */
+    heights?: number[];
 }
 /** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
 export interface StreetJunction {
@@ -92,36 +109,60 @@ export interface StreetNetwork {
     tunnels: StreetFeature[];
     /** Independent cycle count (E − V + components): 0 = pure tree, ≥1 = has loops. */
     loops: number;
+    /** The shared road-surface height FIELD (volume-local), present only when `elevation > 0`. Sample it
+     *  to drape junction welds, sidewalks, and building bases so every surface meets the road continuously
+     *  — the streets/edges sample this exact field. Distinct from the `context.heightAt` terrain sampler. */
+    elevationAt?: (x: number, z: number) => number;
 }
 /** Fully-defaulted slider set the generator reads. */
 export interface StreetNetworkRules {
     seed: string;
+    /** Organic boundary clipping amount, when supported by the caller. */
+    outline?: number;
     /** 1 = regular lattice nodes; 0 = organic scatter. */
     gridness: number;
     /** 0 = tree (dead-ends); 1 = a single closed circuit. */
     loopiness: number;
     /** Extra chord edges between neighbors → mesh density. */
     connectivity: number;
-    /** Spur-lane density forking off the mains. */
+    /** Spur-lane density forking off the mains (and, in a circuit, the pit-lane trigger). */
     branching: number;
+    /** Share of branch streets that use residential side-street rules. */
+    residentialBranches?: number;
     /** Fraction of dangling ends kept as cul-de-sacs (vs reconnected). */
     deadEnds: number;
     /** Target node spacing / block size, world units. */
     segmentLength: number;
     /** Cross-axis spacing multiplier (≥1 = long skinny Manhattan blocks). */
     aspect: number;
-    /** Sideways wander amplitude, 0..1. */
+    /** Sideways wander amplitude, 0..1 (and circuit corner-template density). */
     winding: number;
-    /** Minimum curve radius (m) — caps wander curvature and corner tightness. */
+    /** Minimum curve radius (m) — caps wander curvature and sets the corner-fillet radius. */
     minCurveRadius: number;
     /** Shallowest corner (degrees) a street keeps — gentler bends are straightened. */
     minTurnAngle: number;
-    /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
+    /** Sharpest corner (degrees) between consecutive centerline samples — sharper corners are filleted. */
     maxTurnAngle: number;
     /** Base street width; the hierarchy scales off it. */
     width: number;
     /** Share of avenues upgraded to boulevards, 0..1. */
     boulevards: number;
+    /** Pedestrian band width paved on each side of boulevard/avenue/street levels. Default ~2. */
+    sidewalkWidth?: number;
+    /** Road-surface relief amplitude, 0..1. 0 (default) = dead flat and byte-identical to a pre-elevation
+     *  network; 1 ≈ 22 m of relief across a ~520 m volume (scaled to the footprint). */
+    elevation?: number;
+    /** Maximum road slope (rise/run) the grade cap enforces on every street's height sequence. Default 0.07. */
+    maxGrade?: number;
+    /** SPACE-FILLING circuit layout dial, 0..1. 0 (default) = the hull construction (a flowing loop around
+     *  an empty middle), BYTE-IDENTICAL to a pre-compactness network. Rising values switch the circuit
+     *  LAYOUT stage to a grid spanning-tree CYCLE that folds back through its own interior: parallel
+     *  adjacent runs one corridor pitch apart, switchback esses, consecutive hairpins, and long straights
+     *  from straight tree branches, with footprint coverage rising with the dial (~45% of grid cells at
+     *  0.5, ~85% at 1). Everything downstream — spline fit, curvature floor, straight designation,
+     *  self-clearance, edge distribution, elevation, pit lane — is reused unchanged. Only meaningful in
+     *  circuit mode; ignored by the street net. */
+    compactness?: number;
 }
 /** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
 export interface StreetNetworkContext {
@@ -137,13 +178,21 @@ export interface StreetNetworkContext {
     tunnelClearance?: number;
 }
 /**
- * Hard turn-angle clamp on a polyline with fixed endpoints: interior corners gentler than `minRad`
- * are straightened away (deliberate winding only, no micro-wiggle) and corners sharper than `maxRad`
- * are beveled — the corner vertex is replaced by two points pulled back along each leg, which
- * strictly reduces the angle. Endpoints never move, so a graph node stays welded.
+ * Replace every real corner of a polyline with a sampled **circular-arc fillet** so bends read as
+ * smooth curves instead of polygonal notches, while enforcing two hard limits with fixed endpoints:
+ * interior corners gentler than `minRad` are straightened away (deliberate winding only, no
+ * micro-wiggle), and each remaining corner is rounded with an arc of radius `curveRadius` (clamped to
+ * half the shorter adjacent leg) sampled finely enough that no discrete turn between consecutive
+ * samples exceeds `maxRad` — a corner sharper than the ceiling is still reduced, now to a fillet
+ * rather than a bevel. Open-chain endpoints never move (a graph node stays welded); pass `closed` for
+ * a ring (first === last) so its wrap corner is filleted too and the loop stays closed.
+ *
+ * Pass `radiusFor` to vary the fillet radius PER CORNER (returning the target radius from the corner's
+ * deflection and adjacent leg lengths) instead of the single `curveRadius` — the circuit loop uses this
+ * to mix hairpins, standard corners, and sweepers; every other caller keeps the scalar radius.
  * @internal
  */
-export declare function clampTurns(points: readonly StreetVec2[], minRad: number, maxRad: number): StreetVec2[];
+export declare function clampTurns(points: readonly StreetVec2[], minRad: number, maxRad: number, curveRadius?: number, closed?: boolean, radiusFor?: (deflection: number, la: number, lb: number) => number): StreetVec2[];
 /** Decide which topology family the sliders call for. Circuit wins when loops dominate and both
  *  branching and mesh connectivity are low — exactly the "race track" corner of the slider space.
  *  @internal */
@@ -154,6 +203,6 @@ export declare function streetNetworkMode(rules: StreetNetworkRules): StreetNetw
  * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
  * world space.
  *
- * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, sidewalks, bridges, tunnels) from sliders
  */
 export declare function generateStreets(rules: StreetNetworkRules, hx: number, hz: number, context?: StreetNetworkContext): StreetNetwork;