@jgengine/core 0.12.0 → 0.14.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/{pathNetwork.d.ts → streetGenerator.d.ts}

@@ -1,61 +1,61 @@
 /** A path vertex in the volume-local XZ frame. */
-export type PathVec2 = readonly [number, number];
+export type StreetVec2 = readonly [number, number];
 /** Road hierarchy, widest to narrowest — shared by the city fabric and the renderer. */
-export type PathLevel = "boulevard" | "avenue" | "street" | "lane";
+export type StreetLevel = "boulevard" | "avenue" | "street" | "lane";
 /** A path feature spanning part of an edge/street: a bridge deck over a gap or a tunnel bore under a ridge. */
-export type PathFeatureKind = "bridge" | "tunnel";
+export type StreetFeatureKind = "bridge" | "tunnel";
 /** The generator's chosen topology family: an open street `net`, or a closed `circuit` loop. */
-export type PathNetworkMode = "net" | "circuit";
+export type StreetNetworkMode = "net" | "circuit";
 /** One graph node: a junction, a dead end, or a mid-street bend, with its connection count. */
-export interface PathNode {
+export interface StreetNode {
     id: number;
     x: number;
     z: number;
     degree: number;
 }
 /** One atomic node-to-node edge — the fabric graph consumes these (welds at shared node coords). */
-export interface PathEdge {
+export interface StreetEdge {
     id: number;
     /** Endpoint node ids. */
     a: number;
     b: number;
     /** Sampled centerline; `points[0]` sits exactly on node `a`, the last on node `b`. */
-    points: PathVec2[];
+    points: StreetVec2[];
     width: number;
-    level: PathLevel;
+    level: StreetLevel;
     /** True when this edge belongs to the main closed loop (circuit mode). */
     loop: boolean;
 }
 /** A feature span carried by a street: a `[from, to]` index window into the street's `points`. */
-export interface PathFeatureSpan {
-    kind: PathFeatureKind;
+export interface StreetFeatureSpan {
+    kind: StreetFeatureKind;
     from: number;
     to: number;
     /** Ground height at each bank/portal — the deck/floor reference the renderer drapes to. */
     bankHeight: number;
 }
 /** One chained through-street: a maximal run of edges through degree-2 nodes, for rendering + furniture. */
-export interface PathStreet {
+export interface Street {
     id: number;
     /** Ordered node ids the chain visits; first === last when `loop`. */
     nodes: number[];
     /** Smoothed, turn-clamped centerline. */
-    points: PathVec2[];
+    points: StreetVec2[];
     width: number;
-    level: PathLevel;
+    level: StreetLevel;
     /** Closed chain (a circuit lap or an inner ring). */
     loop: boolean;
     /** Cul-de-sac turning bulb when the street ends at a dangling node. */
-    bulb?: PathVec2;
+    bulb?: StreetVec2;
     /** Bridge/tunnel spans along this street, if any. */
-    features: PathFeatureSpan[];
+    features: StreetFeatureSpan[];
 }
 /** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
-export interface PathJunction {
+export interface StreetJunction {
     x: number;
     z: number;
     radius: number;
-    level: PathLevel;
+    level: StreetLevel;
     /** Outgoing arm directions (radians) with the crossing street width, for crosswalks/patches. */
     arms: {
         angle: number;
@@ -63,7 +63,7 @@ export interface PathJunction {
     }[];
 }
 /** One dangling street end kept as a cul-de-sac: node position plus the heading pointing off the road. */
-export interface PathDeadEnd {
+export interface StreetDeadEnd {
     node: number;
     x: number;
     z: number;
@@ -72,29 +72,29 @@ export interface PathDeadEnd {
     width: number;
 }
 /** A resolved path feature in world-of-the-volume space: a bridge deck or tunnel bore centerline. */
-export interface PathFeature {
-    kind: PathFeatureKind;
-    points: PathVec2[];
+export interface StreetFeature {
+    kind: StreetFeatureKind;
+    points: StreetVec2[];
     width: number;
     bankHeight: number;
 }
 /** The fully-resolved network in volume-local coords. */
-export interface PathNetwork {
-    mode: PathNetworkMode;
-    nodes: PathNode[];
+export interface StreetNetwork {
+    mode: StreetNetworkMode;
+    nodes: StreetNode[];
     /** Atomic edges — feed to the block/parcel fabric. */
-    edges: PathEdge[];
+    edges: StreetEdge[];
     /** Chained through-streets — feed to the renderer, furniture, and analysis. */
-    streets: PathStreet[];
-    junctions: PathJunction[];
-    deadEnds: PathDeadEnd[];
-    bridges: PathFeature[];
-    tunnels: PathFeature[];
+    streets: Street[];
+    junctions: StreetJunction[];
+    deadEnds: StreetDeadEnd[];
+    bridges: StreetFeature[];
+    tunnels: StreetFeature[];
     /** Independent cycle count (E − V + components): 0 = pure tree, ≥1 = has loops. */
     loops: number;
 }
 /** Fully-defaulted slider set the generator reads. */
-export interface PathNetworkRules {
+export interface StreetNetworkRules {
     seed: string;
     /** 1 = regular lattice nodes; 0 = organic scatter. */
     gridness: number;
@@ -124,7 +124,7 @@ export interface PathNetworkRules {
     boulevards: number;
 }
 /** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
-export interface PathNetworkContext {
+export interface StreetNetworkContext {
     /** Volume-local ground height sampler. */
     heightAt?: (x: number, z: number) => number;
     /** Ground below this (local) height is a gap streets bridge over. */
@@ -143,17 +143,17 @@ export interface PathNetworkContext {
  * strictly reduces the angle. Endpoints never move, so a graph node stays welded.
  * @internal
  */
-export declare function clampTurns(points: readonly PathVec2[], minRad: number, maxRad: number): PathVec2[];
+export declare function clampTurns(points: readonly StreetVec2[], minRad: number, maxRad: 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 */
-export declare function pathNetworkMode(rules: PathNetworkRules): PathNetworkMode;
+export declare function streetNetworkMode(rules: StreetNetworkRules): StreetNetworkMode;
 /**
  * Resolve a full path network from its rules inside a volume of half-extents `hx`×`hz`. Deterministic
- * per `(rules.seed, hx, hz, context)`. Pass a {@link PathNetworkContext} with a ground sampler to turn
+ * per `(rules.seed, hx, hz, context)`. Pass a {@link StreetNetworkContext} with a ground sampler to turn
  * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
  * world space.
  *
- * @capability path-network build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
  */
-export declare function buildPathNetwork(rules: PathNetworkRules, hx: number, hz: number, context?: PathNetworkContext): PathNetwork;
+export declare function generateStreets(rules: StreetNetworkRules, hx: number, hz: number, context?: StreetNetworkContext): StreetNetwork;

package/dist/world/{pathNetwork.js → streetGenerator.js}

@@ -1,5 +1,5 @@
 /**
- * The unified, seed-driven procedural PATH NETWORK — one generator that grows an entire road/track
+ * The unified, seed-driven procedural STREET GENERATOR — one engine that grows an entire street/track
  * graph inside a box volume and answers to sliders instead of hardcoded geometry. It is deliberately
  * genre-agnostic: a city street net and a closed race circuit are the *same* engine at opposite
  * slider extremes, not two code paths. Drop a volume, pick a seed, and turn the dials:
@@ -16,14 +16,14 @@
  *   BRIDGE deck; a span buried under a ridge becomes a TUNNEL bore. Both are path FEATURES on a
  *   continuous edge, so a circuit stays closed as it crosses water or pierces a hill.
  *
- * Output is two coupled views of the graph: atomic node-to-node {@link PathEdge}s (fed straight into
+ * Output is two coupled views of the graph: atomic node-to-node {@link StreetEdge}s (fed straight into
  * the block/parcel fabric — a race circuit is many edges between distinct nodes, never one fragile
- * self-loop) and chained {@link PathStreet}s (through-streets for rendering, furniture, and
+ * self-loop) and chained {@link Street}s (through-streets for rendering, furniture, and
  * junctions). Pure deterministic math — same rules + seed + volume ⇒ identical network — with bounded
  * work caps so a huge volume can never generate unbounded content. Local (volume-centered) coords;
  * the caller rotates/translates into world space.
  *
- * @capability path-network seed-driven procedural roads and race circuits from one slider-driven engine
+ * @capability street-generator seed-driven procedural streets and race circuits from one slider-driven engine
  */
 import { seededStreams } from "../random/rng.js";
 const TAU = Math.PI * 2;
@@ -369,7 +369,7 @@ function buildCircuit(rules, hx, hz, streams) {
 /** 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 */
-export function pathNetworkMode(rules) {
+export function streetNetworkMode(rules) {
     const score = rules.loopiness * (1 - rules.branching * 0.7) * (1 - rules.connectivity * 0.7);
     return score >= 0.45 ? "circuit" : "net";
 }
@@ -396,15 +396,15 @@ function levelForStreets(chains, rules, rng) {
 }
 /**
  * Resolve a full path network from its rules inside a volume of half-extents `hx`×`hz`. Deterministic
- * per `(rules.seed, hx, hz, context)`. Pass a {@link PathNetworkContext} with a ground sampler to turn
+ * per `(rules.seed, hx, hz, context)`. Pass a {@link StreetNetworkContext} with a ground sampler to turn
  * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
  * world space.
  *
- * @capability path-network build a deterministic road/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
  */
-export function buildPathNetwork(rules, hx, hz, context = {}) {
+export function generateStreets(rules, hx, hz, context = {}) {
     const streams = seededStreams(`pathnet:${rules.seed}:${Math.round(hx)}:${Math.round(hz)}`);
-    const mode = pathNetworkMode(rules);
+    const mode = streetNetworkMode(rules);
     const raw = mode === "circuit" ? buildCircuit(rules, hx, hz, streams) : buildNet(rules, hx, hz, streams);
     const rawNodes = raw.nodes;
     const rawEdges = raw.edges.filter((e) => e.a !== e.b);

package/dist/world/streets.d.ts

@@ -1,5 +1,5 @@
 import type { RoadEnvironmentDescriptor } from "./features.js";
-import { type RoadPoint } from "./roads.js";
+import { type DashExclusion, type RoadPoint } from "./roads.js";
 /**
  * Offset a centerline sideways by a signed distance along its local perpendicular — the
  * building block for lanes, curb lines, and sidewalk paths. Positive offsets fall on the
@@ -107,3 +107,76 @@ export declare function roadSurfaceSampler(roads: readonly RoadEnvironmentDescri
  * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.
  */
 export declare function sidewalkPoint(road: RoadEnvironmentDescriptor, side: "left" | "right", fraction: number): RoadPoint | null;
+/**
+ * The two curb lines of a road — offset polylines running along the outer edge of the asphalt on
+ * each side. Mesh these with a thin darker ribbon to give the road a curb/edge strip instead of a
+ * hard asphalt-to-terrain seam. `inset` (default 0) nudges the line inward off the raw edge so the
+ * strip straddles the border.
+ */
+export declare function curbPaths(road: RoadEnvironmentDescriptor, inset?: number): readonly [readonly RoadPoint[], readonly RoadPoint[]];
+/** A single arm of a junction: the road width plus the outward direction the road leaves the center. */
+export interface RoadApproach {
+    /** Unit vector pointing from the junction center outward along the road arm. */
+    direction: readonly [number, number];
+    /** Drivable width of the road on this arm. */
+    width: number;
+}
+/** A welded road intersection: a patch center/radius plus the arms that feed it. */
+export interface RoadJunction {
+    /** World XZ center of the intersection. */
+    center: RoadPoint;
+    /** Radius of the covering patch (covers the crossing ribbons). */
+    radius: number;
+    /** Representative surface elevation (max of the participating roads). */
+    elevation: number;
+    /** Representative asphalt color (the widest participating road's color). */
+    color: string;
+    /** Outward arms leaving the junction — one per road direction that continues past the center. */
+    approaches: readonly RoadApproach[];
+}
+/** Options for {@link findRoadJunctions}. */
+export interface RoadJunctionOptions {
+    /** Roads weld only when their elevations differ by at most this much. Default 0.12. */
+    elevationBand?: number;
+    /** Crossing points closer than this merge into a single junction. Default 6. */
+    mergeDistance?: number;
+    /** Hard cap on junctions returned so detection stays bounded. Default 256. */
+    maxJunctions?: number;
+    /** Extra scale on the patch radius past the widest arm's half-width. Default 1.15. */
+    radiusScale?: number;
+}
+/**
+ * Detect welded intersections across a set of roads: wherever two road centerlines cross (or a road
+ * terminates on another) within the same elevation band, emit a {@link RoadJunction} whose patch
+ * covers the crossing ribbons. Nearby crossings merge into one junction. Deterministic and bounded —
+ * O(roads² · segments²) with a `maxJunctions` cap — so a scene builds its intersections once.
+ */
+export declare function findRoadJunctions(roads: readonly RoadEnvironmentDescriptor[], options?: RoadJunctionOptions): readonly RoadJunction[];
+/** Circular marking-exclusion zones for the junctions, sized to hide the center line under each patch. */
+export declare function junctionExclusions(junctions: readonly RoadJunction[], pad?: number): readonly DashExclusion[];
+/** Options for {@link junctionMarkings}. */
+export interface JunctionMarkingOptions {
+    /** Emit a stop-line bar across each approach. Default true. */
+    stopLines?: boolean;
+    /** Emit crosswalk bars at each approach. Default true. */
+    crosswalks?: boolean;
+    /** Number of zebra bars per crosswalk. Default 5. */
+    crosswalkBars?: number;
+    /** Clear gap outside the patch before markings start. Default 0.6. */
+    gap?: number;
+    /** Depth (along travel) of the crosswalk band. Default 2.4. */
+    crosswalkDepth?: number;
+}
+/** Thin marking polylines for a junction: stop-line bars and crosswalk bars, ready for {@link buildRoadRibbon}. */
+export interface JunctionMarkings {
+    /** One bar per approach, perpendicular to travel just outside the patch. */
+    stopLines: readonly (readonly RoadPoint[])[];
+    /** Continental (parallel-to-travel) zebra bars, `crosswalkBars` per approach. */
+    crosswalkBars: readonly (readonly RoadPoint[])[];
+}
+/**
+ * Data-driven junction entry markings: a stop-line bar across each approach and a band of crosswalk
+ * bars just outside the welded patch. Each returned polyline is a thin centerline meant to be meshed
+ * with {@link buildRoadRibbon} at a small width. Fully skippable per-feature via the options.
+ */
+export declare function junctionMarkings(junction: RoadJunction, options?: JunctionMarkingOptions): JunctionMarkings;