@jgengine/core 0.11.0 → 0.13.0

package/dist/world/polyline.js

@@ -62,6 +62,10 @@ export function closestPoint(line, query) {
         return { point: points[0], distanceAlong: 0, segment: 0, lateral: distance(points[0], query) };
     }
     let best = { point: points[0], distanceAlong: 0, segment: 0, lateral: Infinity };
+    // Track the unsigned nearest distance separately: `best.lateral` carries a *signed* offset for
+    // the caller, so comparing the next candidate's unsigned distance against it would freeze the
+    // search the moment a negative-side segment lands (unsigned >= 0 never beats a stored negative).
+    let bestDistance = Infinity;
     for (let i = 1; i < points.length; i += 1) {
         const a = points[i - 1];
         const b = points[i];
@@ -71,9 +75,12 @@ export function closestPoint(line, query) {
         const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((query[0] - a[0]) * abx + (query[1] - a[1]) * aby) / segLenSq));
         const point = [a[0] + abx * t, a[1] + aby * t];
         const lateral = distance(point, query);
-        if (lateral < best.lateral) {
+        if (lateral < bestDistance) {
+            bestDistance = lateral;
             const along = cumulative[i - 1] + t * Math.sqrt(segLenSq);
-            const side = Math.sign(perp(normalize([abx, aby]))[0] * (query[0] - point[0]) + perp(normalize([abx, aby]))[1] * (query[1] - point[1]));
+            const unit = normalize([abx, aby]);
+            const normal = perp(unit);
+            const side = Math.sign(normal[0] * (query[0] - point[0]) + normal[1] * (query[1] - point[1]));
             best = { point, distanceAlong: along, segment: i - 1, lateral: lateral * (side === 0 ? 1 : side) };
         }
     }

package/dist/world/resourceNode.d.ts

@@ -0,0 +1,109 @@
+/** A quantity that is either fixed or a uniformly sampled `[min, max]` range resolved by the field rng. */
+export type Quantity = number | readonly [number, number];
+/** One resource kind a node can yield and its base per-harvest amount (before tool bias and harvester multiplier). */
+export interface ResourceYield {
+    /** Generic resource kind id — "wood", "ore", "fiber", "hide". The field never interprets it. */
+    kind: string;
+    /** Base amount granted per harvest hit; a `[min, max]` range samples deterministic variance from the field rng. */
+    amount: Quantity;
+}
+/** A harvestable node definition: a finite budget, the resources it yields, and how it respawns. */
+export interface ResourceNodeDef {
+    id: string;
+    /** Total harvestable budget (hit points / finite quantity). Each harvest consumes the tool's `power`. */
+    budget: number;
+    /** Resource kinds this node can yield; a tool's bias selects and scales among them. */
+    resources: readonly ResourceYield[];
+    /** Seconds to refill after depletion. Omit for a node that never respawns (a one-shot deposit). */
+    respawn?: number;
+    /** Budget restored on respawn; defaults to `budget`. */
+    respawnBudget?: number;
+}
+/**
+ * How a tool extracts from a node — its per-hit power and per-resource yield bias. Two profiles over the
+ * same multi-resource node return different resources and amounts: the generic pick-vs-hatchet mechanic.
+ */
+export interface ToolProfile {
+    /** Budget consumed per harvest hit; defaults to 1. Clamped to the node's remaining budget. */
+    power?: number;
+    /** Per-resource-kind yield multiplier. A kind absent here falls back to `defaultBias`. */
+    biases?: Readonly<Record<string, number>>;
+    /** Multiplier for resource kinds not listed in `biases`; defaults to 1 (set 0 for a tool that only extracts listed kinds). */
+    defaultBias?: number;
+}
+/** Options for a single harvest. */
+export interface HarvestOptions {
+    /** Scalar applied to every granted amount — a stronger creature/harvester yields more; defaults to 1. */
+    multiplier?: number;
+}
+/** One resource kind granted by a harvest and its resolved amount. */
+export interface ResourceGrant {
+    kind: string;
+    amount: number;
+}
+/** Outcome of one harvest attempt. */
+export interface HarvestResult {
+    nodeId: string;
+    /** Resources granted this harvest; empty when the node was already depleted or the tool extracted nothing. */
+    granted: readonly ResourceGrant[];
+    /** Budget actually consumed (0 when the node was already depleted). */
+    spent: number;
+    /** Whether the node still had budget and produced a harvest. */
+    harvested: boolean;
+    /** Whether this harvest reduced the node to empty. */
+    depleted: boolean;
+}
+/** Serializable per-node runtime state — round-trips through save/load and multiplayer sync. */
+export interface ResourceNodeState {
+    id: string;
+    /** Remaining budget. */
+    budget: number;
+    /** Budget the node refills to on respawn — the nominal "full" value for `fraction`. */
+    maxBudget: number;
+    depleted: boolean;
+    /** Seconds remaining until respawn; 0 when full or when the node never respawns. */
+    respawnTimer: number;
+    /** Explicit respawn-block flag (a structure claimed the spot); OR-ed with the field's suppression predicate. */
+    respawnBlocked: boolean;
+    /** 0..1 remaining fraction of `maxBudget`. */
+    fraction: number;
+}
+/** Construction options for {@link createResourceNodeField}: node definitions and an optional RNG/suppression hook. */
+export interface ResourceNodeFieldConfig {
+    nodes: readonly ResourceNodeDef[];
+    /** Injected [0,1) generator for deterministic yield variance; defaults to `Math.random`. */
+    rng?: () => number;
+    /**
+     * Freeze respawn for a node while this returns true — a structure within radius, a nearby occupant.
+     * Consulted every tick alongside the per-node `respawnBlocked` flag (either one suppresses).
+     */
+    respawnSuppressed?: (state: ResourceNodeState) => boolean;
+}
+/** A set of harvestable nodes: harvest with tool profiles, tick respawn timers, snapshot/hydrate for save-load. */
+export interface ResourceNodeField {
+    /** Apply one harvest hit with `tool`; returns the granted resources and decrements the node's budget. */
+    harvest(nodeId: string, tool: ToolProfile, options?: HarvestOptions): HarvestResult;
+    /** Count down respawn timers by `dt`; refill any node whose timer elapses and is not suppressed. */
+    tick(dt: number): void;
+    state(nodeId: string): ResourceNodeState;
+    isDepleted(nodeId: string): boolean;
+    /** Set the explicit respawn-block flag; persisted in state and honored by `tick`. */
+    setRespawnBlocked(nodeId: string, blocked: boolean): void;
+    ids(): readonly string[];
+    snapshot(): Record<string, ResourceNodeState>;
+    /** Restore mutable per-node state (budget, depletion, timers, block flag) from a {@link snapshot}. */
+    hydrate(snapshot: Record<string, ResourceNodeState>): void;
+}
+/**
+ * A field of depletable, respawning harvest nodes with tool-dependent yields — the generic rock / tree /
+ * bush / vein / corpse. Each node holds a finite budget across one or more resource kinds. A harvest applies
+ * a {@link ToolProfile} whose per-resource biases decide *which* resources and *how much* the same node
+ * returns (pick favors ore, hatchet favors wood), scaled by a creature/harvester multiplier and optional
+ * deterministic rng variance; the budget drops by the tool's power. When a node empties it starts a respawn
+ * timer that `tick(dt)` counts down and refills — unless respawn is suppressed by the per-node flag or the
+ * injected predicate (a structure claimed the spot). All state is plain and serializable for save-load and
+ * multiplayer sync via {@link snapshot}/{@link hydrate}.
+ *
+ * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
+ */
+export declare function createResourceNodeField(config: ResourceNodeFieldConfig): ResourceNodeField;

package/dist/world/resourceNode.js

@@ -0,0 +1,140 @@
+import { clamp } from "../math/scalar.js";
+function resolveQuantity(quantity, rng) {
+    if (typeof quantity === "number")
+        return quantity;
+    const [lo, hi] = quantity;
+    return lo + rng() * (hi - lo);
+}
+function toState(node) {
+    return {
+        id: node.def.id,
+        budget: node.budget,
+        maxBudget: node.maxBudget,
+        depleted: node.depleted,
+        respawnTimer: node.respawnTimer,
+        respawnBlocked: node.respawnBlocked,
+        fraction: node.maxBudget > 0 ? clamp(node.budget / node.maxBudget, 0, 1) : 0,
+    };
+}
+/**
+ * A field of depletable, respawning harvest nodes with tool-dependent yields — the generic rock / tree /
+ * bush / vein / corpse. Each node holds a finite budget across one or more resource kinds. A harvest applies
+ * a {@link ToolProfile} whose per-resource biases decide *which* resources and *how much* the same node
+ * returns (pick favors ore, hatchet favors wood), scaled by a creature/harvester multiplier and optional
+ * deterministic rng variance; the budget drops by the tool's power. When a node empties it starts a respawn
+ * timer that `tick(dt)` counts down and refills — unless respawn is suppressed by the per-node flag or the
+ * injected predicate (a structure claimed the spot). All state is plain and serializable for save-load and
+ * multiplayer sync via {@link snapshot}/{@link hydrate}.
+ *
+ * @capability resource-node depletable, respawning harvest nodes with tool-dependent yields
+ */
+export function createResourceNodeField(config) {
+    const rng = config.rng ?? Math.random;
+    const nodes = new Map();
+    const order = [];
+    for (const def of config.nodes) {
+        if (nodes.has(def.id))
+            throw new Error(`duplicate resource node "${def.id}"`);
+        const respawnBudget = def.respawnBudget ?? def.budget;
+        nodes.set(def.id, {
+            def,
+            budget: def.budget,
+            maxBudget: def.budget,
+            respawnBudget,
+            depleted: def.budget <= 0,
+            respawnTimer: 0,
+            respawnBlocked: false,
+        });
+        order.push(def.id);
+    }
+    const getNode = (id) => {
+        const node = nodes.get(id);
+        if (node === undefined)
+            throw new Error(`unknown resource node "${id}"`);
+        return node;
+    };
+    const isSuppressed = (node) => {
+        if (node.respawnBlocked)
+            return true;
+        if (config.respawnSuppressed === undefined)
+            return false;
+        return config.respawnSuppressed(toState(node));
+    };
+    return {
+        harvest(nodeId, tool, options = {}) {
+            const node = getNode(nodeId);
+            if (node.depleted || node.budget <= 0) {
+                return { nodeId, granted: [], spent: 0, harvested: false, depleted: node.depleted };
+            }
+            const power = tool.power !== undefined && tool.power > 0 ? tool.power : 1;
+            const spent = Math.min(power, node.budget);
+            const multiplier = options.multiplier ?? 1;
+            const defaultBias = tool.defaultBias ?? 1;
+            const granted = [];
+            for (const resource of node.def.resources) {
+                // Resolve variance for every resource so the rng stream stays independent of tool choice.
+                const base = resolveQuantity(resource.amount, rng);
+                const bias = tool.biases?.[resource.kind] ?? defaultBias;
+                const amount = base * bias * multiplier;
+                if (amount > 0)
+                    granted.push({ kind: resource.kind, amount });
+            }
+            node.budget -= spent;
+            let depleted = false;
+            if (node.budget <= 0) {
+                node.budget = 0;
+                node.depleted = true;
+                depleted = true;
+                node.respawnTimer = node.def.respawn ?? 0;
+            }
+            return { nodeId, granted, spent, harvested: true, depleted };
+        },
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            for (const id of order) {
+                const node = nodes.get(id);
+                if (!node.depleted || node.def.respawn === undefined)
+                    continue;
+                if (isSuppressed(node))
+                    continue;
+                node.respawnTimer -= dt;
+                if (node.respawnTimer <= 0) {
+                    node.budget = node.respawnBudget;
+                    node.depleted = false;
+                    node.respawnTimer = 0;
+                }
+            }
+        },
+        state(nodeId) {
+            return toState(getNode(nodeId));
+        },
+        isDepleted(nodeId) {
+            return getNode(nodeId).depleted;
+        },
+        setRespawnBlocked(nodeId, blocked) {
+            getNode(nodeId).respawnBlocked = blocked;
+        },
+        ids() {
+            return order;
+        },
+        snapshot() {
+            const out = {};
+            for (const id of order)
+                out[id] = toState(nodes.get(id));
+            return out;
+        },
+        hydrate(snapshot) {
+            for (const id of order) {
+                const saved = snapshot[id];
+                if (saved === undefined)
+                    continue;
+                const node = nodes.get(id);
+                node.budget = saved.budget;
+                node.depleted = saved.depleted;
+                node.respawnTimer = saved.respawnTimer;
+                node.respawnBlocked = saved.respawnBlocked;
+            }
+        },
+    };
+}

package/dist/world/roads.d.ts

@@ -29,12 +29,29 @@ export interface RoadRibbonOptions {
  * into a mesh, and tests can assert on it directly.
  */
 export declare function buildRoadRibbon(path: readonly RoadPoint[], width: number, sampleHeight: (x: number, z: number) => number, options?: RoadRibbonOptions): RoadRibbon;
+/** A circular exclusion zone: dashes whose midpoint falls inside are dropped (e.g. junction patches). */
+export interface DashExclusion {
+    center: RoadPoint;
+    radius: number;
+}
+/**
+ * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
+ * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
+ * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
+ * Pure geometry; the shell meshes the result with the asphalt material.
+ */
+export declare function buildJunctionPatch(center: RoadPoint, radius: number, sampleHeight: (x: number, z: number) => number, options?: {
+    elevation?: number;
+    segments?: number;
+}): RoadRibbon;
 /**
  * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
  * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
- * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes. Pass `exclude` circles
+ * (junction patches) to interrupt the center line through intersections — any dash whose midpoint
+ * lands inside an exclusion is dropped.
  */
-export declare function dashSegments(path: readonly RoadPoint[], dashLength?: number, gapLength?: number): readonly (readonly RoadPoint[])[];
+export declare function dashSegments(path: readonly RoadPoint[], dashLength?: number, gapLength?: number, exclude?: readonly DashExclusion[]): readonly (readonly RoadPoint[])[];
 /** Result of {@link nearestOnPath}: closest point on the centerline plus distance and tangent. */
 export interface RoadSample {
     /** Closest point on the centerline. */

package/dist/world/roads.js

@@ -102,12 +102,48 @@ export function buildRoadRibbon(path, width, sampleHeight, options = {}) {
     }
     return { positions, indices };
 }
+/**
+ * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
+ * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
+ * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
+ * Pure geometry; the shell meshes the result with the asphalt material.
+ */
+export function buildJunctionPatch(center, radius, sampleHeight, options = {}) {
+    const elevation = options.elevation ?? 0.08;
+    const segments = Math.max(3, Math.floor(options.segments ?? 16));
+    if (radius <= 0)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const [cx, cz] = center;
+    // Center vertex + one ring vertex per segment.
+    const positions = new Float32Array((segments + 1) * 3);
+    positions[0] = cx;
+    positions[1] = sampleHeight(cx, cz) + elevation;
+    positions[2] = cz;
+    for (let i = 0; i < segments; i += 1) {
+        const angle = (i / segments) * Math.PI * 2;
+        const x = cx + Math.cos(angle) * radius;
+        const z = cz + Math.sin(angle) * radius;
+        const base = (i + 1) * 3;
+        positions[base] = x;
+        positions[base + 1] = sampleHeight(x, z) + elevation;
+        positions[base + 2] = z;
+    }
+    const indices = new Uint32Array(segments * 3);
+    for (let i = 0; i < segments; i += 1) {
+        indices[i * 3] = 0;
+        indices[i * 3 + 1] = i + 1;
+        indices[i * 3 + 2] = ((i + 1) % segments) + 1;
+    }
+    return { positions, indices };
+}
 /**
  * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
  * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
- * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes. Pass `exclude` circles
+ * (junction patches) to interrupt the center line through intersections — any dash whose midpoint
+ * lands inside an exclusion is dropped.
  */
-export function dashSegments(path, dashLength = 3, gapLength = 3) {
+export function dashSegments(path, dashLength = 3, gapLength = 3, exclude = []) {
     if (path.length < 2 || dashLength <= 0 || gapLength < 0)
         return [];
     const cumulative = [0];
@@ -136,7 +172,28 @@ export function dashSegments(path, dashLength = 3, gapLength = 3) {
         const end = Math.min(total, start + dashLength);
         if (end - start < 1e-6)
             break;
-        dashes.push([pointAt(start), pointAt(end)]);
+        const a = pointAt(start);
+        const b = pointAt(end);
+        if (exclude.length > 0) {
+            const mx = (a[0] + b[0]) / 2;
+            const mz = (a[1] + b[1]) / 2;
+            let excluded = false;
+            for (let e = 0; e < exclude.length; e += 1) {
+                const zone = exclude[e];
+                const dx = mx - zone.center[0];
+                const dz = mz - zone.center[1];
+                if (dx * dx + dz * dz <= zone.radius * zone.radius) {
+                    excluded = true;
+                    break;
+                }
+            }
+            if (excluded) {
+                if (period <= 0)
+                    break;
+                continue;
+            }
+        }
+        dashes.push([a, b]);
         if (period <= 0)
             break;
     }

package/dist/world/scatter.js

@@ -1,4 +1,5 @@
 import { expandAabb, pointInAabb } from "./geometry.js";
+import { seededRng } from "../random/rng.js";
 function isAabb(area) {
     return (typeof area.minX === "number" &&
         typeof area.minZ === "number" &&
@@ -15,25 +16,6 @@ export function scatterAabb(area) {
     const halfD = area.d / 2;
     return { minX: cx - halfW, minZ: cz - halfD, maxX: cx + halfW, maxZ: cz + halfD };
 }
-function hashSeed(seed) {
-    const text = typeof seed === "number" ? seed.toString() : seed;
-    let h = 2166136261 >>> 0;
-    for (let i = 0; i < text.length; i++) {
-        h ^= text.charCodeAt(i);
-        h = Math.imul(h, 16777619);
-    }
-    return h >>> 0;
-}
-function mulberry32(state) {
-    let a = state >>> 0;
-    return () => {
-        a = (a + 0x6d2b79f5) >>> 0;
-        let t = a;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
 export function scatter(config) {
     const aabb = scatterAabb(config.area);
     const width = aabb.maxX - aabb.minX;
@@ -47,7 +29,7 @@ export function scatter(config) {
     const jitter = config.jitter ?? 1;
     const maxAttempts = config.maxAttempts ?? target * 30;
     const avoid = (config.avoid ?? []).map((a) => (avoidMargin !== 0 ? expandAabb(a, avoidMargin) : a));
-    const rng = mulberry32(hashSeed(config.seed ?? "scatter"));
+    const rng = seededRng(config.seed ?? "scatter");
     const useDistance = minDistance > 0;
     const buckets = new Map();
     const bucketKey = (x, z) => `${Math.floor(x / minDistance)}:${Math.floor(z / minDistance)}`;

package/dist/world/streetGenerator.d.ts

@@ -0,0 +1,159 @@
+/** A path vertex in the volume-local XZ frame. */
+export type StreetVec2 = readonly [number, number];
+/** Road hierarchy, widest to narrowest — shared by the city fabric and the renderer. */
+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 StreetFeatureKind = "bridge" | "tunnel";
+/** The generator's chosen topology family: an open street `net`, or a closed `circuit` loop. */
+export type StreetNetworkMode = "net" | "circuit";
+/** One graph node: a junction, a dead end, or a mid-street bend, with its connection count. */
+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 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: StreetVec2[];
+    width: number;
+    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 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 Street {
+    id: number;
+    /** Ordered node ids the chain visits; first === last when `loop`. */
+    nodes: number[];
+    /** Smoothed, turn-clamped centerline. */
+    points: StreetVec2[];
+    width: number;
+    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?: StreetVec2;
+    /** Bridge/tunnel spans along this street, if any. */
+    features: StreetFeatureSpan[];
+}
+/** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
+export interface StreetJunction {
+    x: number;
+    z: number;
+    radius: number;
+    level: StreetLevel;
+    /** Outgoing arm directions (radians) with the crossing street width, for crosswalks/patches. */
+    arms: {
+        angle: number;
+        width: number;
+    }[];
+}
+/** One dangling street end kept as a cul-de-sac: node position plus the heading pointing off the road. */
+export interface StreetDeadEnd {
+    node: number;
+    x: number;
+    z: number;
+    /** Yaw (radians) facing outward, away from the network. */
+    heading: number;
+    width: number;
+}
+/** A resolved path feature in world-of-the-volume space: a bridge deck or tunnel bore centerline. */
+export interface StreetFeature {
+    kind: StreetFeatureKind;
+    points: StreetVec2[];
+    width: number;
+    bankHeight: number;
+}
+/** The fully-resolved network in volume-local coords. */
+export interface StreetNetwork {
+    mode: StreetNetworkMode;
+    nodes: StreetNode[];
+    /** Atomic edges — feed to the block/parcel fabric. */
+    edges: StreetEdge[];
+    /** Chained through-streets — feed to the renderer, furniture, and analysis. */
+    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 StreetNetworkRules {
+    seed: string;
+    /** 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. */
+    branching: 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. */
+    winding: number;
+    /** Minimum curve radius (m) — caps wander curvature and corner tightness. */
+    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. */
+    maxTurnAngle: number;
+    /** Base street width; the hierarchy scales off it. */
+    width: number;
+    /** Share of avenues upgraded to boulevards, 0..1. */
+    boulevards: number;
+}
+/** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
+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. */
+    minElevation?: number;
+    /** Emit bridge decks over sub-`minElevation` gaps. */
+    bridges?: boolean;
+    /** Emit tunnel bores where the ground rises this far above a span's banks. */
+    tunnels?: boolean;
+    /** Ridge height above the banks that triggers a tunnel. Default 6. */
+    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.
+ * @internal
+ */
+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 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 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 street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ */
+export declare function generateStreets(rules: StreetNetworkRules, hx: number, hz: number, context?: StreetNetworkContext): StreetNetwork;