@jgengine/core 0.9.0 → 0.11.0

package/dist/world/spatialSample.js

@@ -0,0 +1,465 @@
+import { pointInAabb } from "./geometry.js";
+import { pointInPolygon, polygonBounds } from "./scatterRegion.js";
+const DEFAULT_MAX_ATTEMPTS = 30;
+const TWO_PI = Math.PI * 2;
+function distanceSq(a, b) {
+    const n = a.length < b.length ? a.length : b.length;
+    let sum = 0;
+    for (let i = 0; i < n; i += 1) {
+        const d = a[i] - b[i];
+        sum += d * d;
+    }
+    return sum;
+}
+/**
+ * A uniform spatial hash over cells of `cellSize`, used to enforce minimum separation in O(1)
+ * neighborhood checks instead of an O(n²) scan — the allocation-aware index behind batch spacing.
+ * @internal
+ */
+class SeparationIndex {
+    cellSize;
+    dimensions;
+    buckets = new Map();
+    minSq;
+    constructor(cellSize, dimensions) {
+        this.cellSize = cellSize;
+        this.dimensions = dimensions;
+        this.minSq = cellSize * cellSize;
+    }
+    key(cell) {
+        return cell.join(":");
+    }
+    cellOf(point) {
+        const cell = [];
+        for (let i = 0; i < this.dimensions; i += 1)
+            cell.push(Math.floor(point[i] / this.cellSize));
+        return cell;
+    }
+    /** True when `point` sits within `cellSize` of any inserted point. */
+    tooClose(point) {
+        const base = this.cellOf(point);
+        const dims = this.dimensions;
+        const stack = [];
+        const walk = (axis) => {
+            if (axis === dims) {
+                const bucket = this.buckets.get(this.key(stack));
+                if (bucket !== undefined)
+                    for (const other of bucket)
+                        if (distanceSq(point, other) < this.minSq)
+                            return true;
+                return false;
+            }
+            for (let d = -1; d <= 1; d += 1) {
+                stack[axis] = base[axis] + d;
+                if (walk(axis + 1))
+                    return true;
+            }
+            return false;
+        };
+        return walk(0);
+    }
+    insert(point) {
+        const key = this.key(this.cellOf(point));
+        const bucket = this.buckets.get(key);
+        if (bucket !== undefined)
+            bucket.push(point);
+        else
+            this.buckets.set(key, [point]);
+    }
+}
+function passesConstraints(point, constraints, index) {
+    if (constraints === undefined)
+        return index === null || !index.tooClose(point);
+    if (constraints.include !== undefined)
+        for (const region of constraints.include)
+            if (!region.contains(point))
+                return false;
+    if (constraints.exclude !== undefined)
+        for (const region of constraints.exclude)
+            if (region.contains(point))
+                return false;
+    if (index !== null && index.tooClose(point))
+        return false;
+    if (constraints.accept !== undefined && !constraints.accept(point))
+        return false;
+    return true;
+}
+function resolveFallback(fallback, last, attempts, reason) {
+    if (fallback !== undefined && fallback !== "none") {
+        if (fallback === "last-candidate") {
+            if (last !== null)
+                return { ok: false, point: last, attempts, reason, usedFallback: true };
+        }
+        else {
+            return { ok: false, point: fallback.point, attempts, reason, usedFallback: true };
+        }
+    }
+    return { ok: false, point: null, attempts, reason, usedFallback: false };
+}
+/**
+ * Draw one point from `region` that clears every constraint, retrying up to `maxAttempts` times with
+ * the injected `rng`, then apply the `fallback` policy. Returns a structured {@link SampleResult} —
+ * a clean hit is `ok: true`; exhaustion or a degenerate region is reported with the attempt count and
+ * an explicit fallback flag, never a silently-accepted bad point.
+ *
+ * @capability spatial-sample draw one deterministic position from a region under include/exclude/distance constraints
+ */
+export function samplePoint(options) {
+    const { region, rng, constraints } = options;
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    if (region.isEmpty)
+        return resolveFallback(options.fallback, null, 0, "empty-region");
+    let index = null;
+    const minSeparation = constraints?.minSeparation ?? 0;
+    const placed = options.placed ?? [];
+    if (minSeparation > 0 && placed.length > 0) {
+        index = new SeparationIndex(minSeparation, region.dimensions);
+        for (const point of placed)
+            index.insert(point);
+    }
+    let last = null;
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+        attempts += 1;
+        let candidate = region.sample(rng);
+        if (constraints?.project !== undefined)
+            candidate = constraints.project(candidate);
+        if (candidate === null)
+            continue;
+        last = candidate;
+        if (passesConstraints(candidate, constraints, index)) {
+            return { ok: true, point: candidate, attempts, reason: "accepted", usedFallback: false };
+        }
+    }
+    return resolveFallback(options.fallback, last, attempts, "exhausted");
+}
+/**
+ * Place up to `count` points from `region`, each clearing the shared constraints and honoring
+ * `minSeparation` against every point already placed in this batch (via a spatial hash, not an
+ * O(n²) scan). Order is deterministic for a given `rng` stream. Batches never silently under-fill:
+ * the result reports `placed`, `complete`, and the total attempt count.
+ *
+ * @capability spatial-sample-batch place many deterministic spaced points from a region with minimum separation
+ */
+export function sampleBatch(options) {
+    const { region, rng, constraints } = options;
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const requested = Math.max(0, Math.floor(options.count));
+    const points = [];
+    if (requested === 0 || region.isEmpty) {
+        return { points, requested, placed: 0, complete: requested === 0, attempts: 0 };
+    }
+    const minSeparation = constraints?.minSeparation ?? 0;
+    const index = minSeparation > 0 ? new SeparationIndex(minSeparation, region.dimensions) : null;
+    let attempts = 0;
+    for (let i = 0; i < requested; i += 1) {
+        let placed = null;
+        let tries = 0;
+        while (tries < maxAttempts) {
+            tries += 1;
+            attempts += 1;
+            let candidate = region.sample(rng);
+            if (constraints?.project !== undefined)
+                candidate = constraints.project(candidate);
+            if (candidate === null)
+                continue;
+            if (passesConstraints(candidate, constraints, index)) {
+                placed = candidate;
+                break;
+            }
+        }
+        if (placed === null)
+            break;
+        points.push(placed);
+        if (index !== null)
+            index.insert(placed);
+    }
+    return { points, requested, placed: points.length, complete: points.length === requested, attempts };
+}
+/**
+ * A fixed set of candidate points sampled by (optionally weighted) selection — the "spawn point
+ * table" region. `contains` is exact membership. Empty when the set is empty.
+ *
+ * @capability spatial-region-point-set sample from a fixed, optionally weighted candidate point table
+ */
+export function pointSetRegion(points, options = {}) {
+    const pool = points.map((p) => [p[0], p[1]]);
+    const weights = options.weights;
+    const total = weights === undefined ? pool.length : weights.reduce((sum, w) => sum + Math.max(0, w), 0);
+    return {
+        dimensions: 2,
+        isEmpty: pool.length === 0 || total <= 0,
+        sample(rng) {
+            if (weights === undefined)
+                return pool[Math.min(pool.length - 1, Math.floor(rng() * pool.length))];
+            let roll = rng() * total;
+            for (let i = 0; i < pool.length; i += 1) {
+                roll -= Math.max(0, weights[i] ?? 0);
+                if (roll <= 0)
+                    return pool[i];
+            }
+            return pool[pool.length - 1];
+        },
+        contains(point) {
+            return pool.some((p) => p[0] === point[0] && p[1] === point[1]);
+        },
+    };
+}
+/**
+ * An axis-aligned rectangle on the XZ plane. `"uniform"` spreads evenly (draws x then z);
+ * `"edge"` biases onto a boundary band of `edgeThickness` meters (perimeter-weighted side, then
+ * inward depth) — the two are never conflated, the caller opts in.
+ */
+export function rectRegion(area, options = {}) {
+    const width = area.maxX - area.minX;
+    const depth = area.maxZ - area.minZ;
+    const distribution = options.distribution ?? "uniform";
+    const edgeThickness = Math.max(0, options.edgeThickness ?? Math.min(width, depth) * 0.25);
+    return {
+        dimensions: 2,
+        isEmpty: !(width > 0) || !(depth > 0),
+        sample(rng) {
+            if (distribution === "edge") {
+                const perim = 2 * (width + depth);
+                const sidePick = rng() * perim;
+                const t = rng();
+                const inset = Math.min(edgeThickness, Math.min(width, depth) / 2) * rng();
+                if (sidePick < width)
+                    return [area.minX + t * width, area.minZ + inset];
+                if (sidePick < width + depth)
+                    return [area.maxX - inset, area.minZ + t * depth];
+                if (sidePick < 2 * width + depth)
+                    return [area.minX + t * width, area.maxZ - inset];
+                return [area.minX + inset, area.minZ + t * depth];
+            }
+            const x = area.minX + rng() * width;
+            const z = area.minZ + rng() * depth;
+            return [x, z];
+        },
+        contains(point) {
+            return pointInAabb(point, area);
+        },
+    };
+}
+function radialRadius(rng, inner, outer, distribution) {
+    const u = rng();
+    if (distribution === "area")
+        return Math.sqrt(inner * inner + u * (outer * outer - inner * inner));
+    return inner + u * (outer - inner);
+}
+/**
+ * A filled circle. `"area"` is area-uniform (√-corrected radius, even density); `"radial"` is
+ * radius-uniform (clumps toward the center). Angle is drawn first, then radius — matching the common
+ * `angle = rng()·2π; r = rng()·R` idiom so migrations keep their stream.
+ */
+export function discRegion(center, radius, options = {}) {
+    const distribution = options.distribution ?? "area";
+    const r = Math.max(0, radius);
+    return {
+        dimensions: 2,
+        isEmpty: !(r > 0),
+        sample(rng) {
+            const angle = rng() * TWO_PI;
+            const dist = radialRadius(rng, 0, r, distribution);
+            return [center[0] + Math.cos(angle) * dist, center[1] + Math.sin(angle) * dist];
+        },
+        contains(point) {
+            return distanceSq(point, center) <= r * r;
+        },
+    };
+}
+/**
+ * A ring (annulus) between `innerRadius` and `outerRadius`. `"area"` fills the band with even
+ * density; `"radial"` spreads uniformly in radius. Angle first, then radius.
+ */
+export function annulusRegion(center, innerRadius, outerRadius, options = {}) {
+    const distribution = options.distribution ?? "area";
+    const inner = Math.max(0, Math.min(innerRadius, outerRadius));
+    const outer = Math.max(innerRadius, outerRadius, 0);
+    return {
+        dimensions: 2,
+        isEmpty: !(outer > 0) || outer <= inner,
+        sample(rng) {
+            const angle = rng() * TWO_PI;
+            const dist = radialRadius(rng, inner, outer, distribution);
+            return [center[0] + Math.cos(angle) * dist, center[1] + Math.sin(angle) * dist];
+        },
+        contains(point) {
+            const d2 = distanceSq(point, center);
+            return d2 >= inner * inner && d2 <= outer * outer;
+        },
+    };
+}
+/**
+ * An arbitrary closed polygon on the XZ plane. Candidates are drawn uniformly from the polygon's
+ * bounding box and gated by point-in-polygon `contains`, so a run's draw count stays fixed (the
+ * sampler's attempt budget bounds the rejection, not a hidden inner loop).
+ *
+ * @capability spatial-region-polygon sample within an arbitrary closed polygon on the XZ plane
+ */
+export function polygonRegion(polygon) {
+    const bounds = polygonBounds(polygon);
+    const width = bounds === null ? 0 : bounds.maxX - bounds.minX;
+    const depth = bounds === null ? 0 : bounds.maxZ - bounds.minZ;
+    return {
+        dimensions: 2,
+        isEmpty: bounds === null || polygon.length < 3 || !(width > 0) || !(depth > 0),
+        sample(rng) {
+            const b = bounds ?? { minX: 0, minZ: 0, maxX: 0, maxZ: 0 };
+            return [b.minX + rng() * width, b.minZ + rng() * depth];
+        },
+        contains(point) {
+            return pointInPolygon(point, polygon);
+        },
+    };
+}
+/**
+ * A composite that first picks one member by weight, then delegates to its sampler — the
+ * "weighted subregions" distribution policy. `contains` is true when any member contains the point.
+ *
+ * @capability spatial-region-weighted compose sub-regions behind a weighted selection policy
+ */
+export function weightedRegion(entries) {
+    const usable = entries.filter((e) => e.weight > 0 && !e.region.isEmpty);
+    const total = usable.reduce((sum, e) => sum + e.weight, 0);
+    const dimensions = entries[0]?.region.dimensions ?? 2;
+    return {
+        dimensions,
+        isEmpty: usable.length === 0,
+        sample(rng) {
+            let roll = rng() * total;
+            for (const entry of usable) {
+                roll -= entry.weight;
+                if (roll <= 0)
+                    return entry.region.sample(rng);
+            }
+            return usable[usable.length - 1].region.sample(rng);
+        },
+        contains(point) {
+            return entries.some((e) => e.region.contains(point));
+        },
+    };
+}
+/**
+ * Wrap a caller-defined sampler and bounds test as a {@link SampleRegion} — the escape hatch for
+ * regions the built-ins do not cover (a navmesh cell, a heightfield mask, a spline tube).
+ *
+ * @capability spatial-region-custom wrap a caller-defined sampler and bounds test as a region
+ */
+export function customRegion(spec) {
+    return {
+        dimensions: spec.dimensions,
+        isEmpty: spec.isEmpty ?? false,
+        sample: spec.sample,
+        contains: spec.contains,
+    };
+}
+// ---------------------------------------------------------------------------
+// 3D region builders
+// ---------------------------------------------------------------------------
+/**
+ * An axis-aligned box `[min..max]` in 3D. Uniform density; draws x, y, z in order.
+ *
+ * @capability spatial-region-box sample uniformly within an axis-aligned 3D box
+ */
+export function boxRegion(min, max) {
+    const size = [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
+    return {
+        dimensions: 3,
+        isEmpty: !(size[0] > 0) || !(size[1] > 0) || !(size[2] > 0),
+        sample(rng) {
+            return [min[0] + rng() * size[0], min[1] + rng() * size[1], min[2] + rng() * size[2]];
+        },
+        contains(point) {
+            return (point[0] >= min[0] && point[0] <= max[0] &&
+                point[1] >= min[1] && point[1] <= max[1] &&
+                point[2] >= min[2] && point[2] <= max[2]);
+        },
+    };
+}
+function sphereDirection(rng) {
+    const cosTheta = 1 - 2 * rng();
+    const sinTheta = Math.sqrt(Math.max(0, 1 - cosTheta * cosTheta));
+    const phi = rng() * TWO_PI;
+    return [sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), cosTheta];
+}
+function volumeRadius(rng, inner, outer, distribution) {
+    const u = rng();
+    if (distribution === "volume")
+        return Math.cbrt(inner ** 3 + u * (outer ** 3 - inner ** 3));
+    return inner + u * (outer - inner);
+}
+/**
+ * A filled ball. `"volume"` is volume-uniform (∛-corrected radius); `"radial"` is radius-uniform.
+ * Direction is drawn first (two draws), then radius.
+ *
+ * @capability spatial-region-sphere sample within a filled 3D ball, volume- or radius-uniform
+ */
+export function sphereRegion(center, radius, options = {}) {
+    const distribution = options.distribution ?? "volume";
+    const r = Math.max(0, radius);
+    return {
+        dimensions: 3,
+        isEmpty: !(r > 0),
+        sample(rng) {
+            const dir = sphereDirection(rng);
+            const dist = volumeRadius(rng, 0, r, distribution);
+            return [center[0] + dir[0] * dist, center[1] + dir[1] * dist, center[2] + dir[2] * dist];
+        },
+        contains(point) {
+            return distanceSq(point, center) <= r * r;
+        },
+    };
+}
+/**
+ * A spherical shell between `innerRadius` and `outerRadius`. `"volume"` fills the shell with even
+ * density; `"radial"` spreads uniformly in radius. Direction first, then radius.
+ *
+ * @capability spatial-region-shell sample within a 3D spherical shell, volume- or radius-uniform
+ */
+export function shellRegion(center, innerRadius, outerRadius, options = {}) {
+    const distribution = options.distribution ?? "volume";
+    const inner = Math.max(0, Math.min(innerRadius, outerRadius));
+    const outer = Math.max(innerRadius, outerRadius, 0);
+    return {
+        dimensions: 3,
+        isEmpty: !(outer > 0) || outer <= inner,
+        sample(rng) {
+            const dir = sphereDirection(rng);
+            const dist = volumeRadius(rng, inner, outer, distribution);
+            return [center[0] + dir[0] * dist, center[1] + dir[1] * dist, center[2] + dir[2] * dist];
+        },
+        contains(point) {
+            const d2 = distanceSq(point, center);
+            return d2 >= inner * inner && d2 <= outer * outer;
+        },
+    };
+}
+/**
+ * Stratified 2D sampling: one jittered point per grid cell over `area`, in deterministic row-major
+ * order. Unlike pure rejection sampling this guarantees even coverage (no clumps, no gaps) — the
+ * distinct "stratified" distribution policy, kept separate from area-uniform draws.
+ *
+ * @capability spatial-sample-stratified evenly cover an area with one jittered point per grid cell, deterministic
+ */
+export function sampleStratified(options) {
+    const { area, rng } = options;
+    const cols = Math.max(0, Math.floor(options.cols));
+    const rows = Math.max(0, Math.floor(options.rows));
+    const width = area.maxX - area.minX;
+    const depth = area.maxZ - area.minZ;
+    if (cols === 0 || rows === 0 || !(width > 0) || !(depth > 0))
+        return [];
+    const jitter = Math.min(1, Math.max(0, options.jitter ?? 1));
+    const cellW = width / cols;
+    const cellD = depth / rows;
+    const points = [];
+    for (let row = 0; row < rows; row += 1) {
+        for (let col = 0; col < cols; col += 1) {
+            const jx = 0.5 + jitter * (rng() - 0.5);
+            const jz = 0.5 + jitter * (rng() - 0.5);
+            points.push([area.minX + (col + jx) * cellW, area.minZ + (row + jz) * cellD]);
+        }
+    }
+    return points;
+}

package/dist/world/streets.d.ts

@@ -0,0 +1,80 @@
+import type { RoadEnvironmentDescriptor } from "./features.js";
+import { 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
+ * left of the direction of travel, negative on the right.
+ */
+export declare function offsetPath(path: readonly RoadPoint[], offset: number): readonly RoadPoint[];
+/** A directed lane derived from a road: an offset centerline plus its direction of travel. */
+export interface StreetLane {
+    /** Lane centerline, ordered in the direction of travel. */
+    path: readonly RoadPoint[];
+    /** "forward" runs with the road's declared path order; "reverse" runs against it. */
+    direction: "forward" | "reverse";
+}
+/**
+ * Two right-hand-traffic lane centerlines for a road — each offset a quarter of the drivable
+ * width from the center and ordered in its direction of travel. Feed a lane's `path` straight
+ * into `nav/pathFollow` for traffic AI, or use its endpoints as directed car spawn points.
+ */
+export declare function laneCenters(road: RoadEnvironmentDescriptor): readonly [StreetLane, StreetLane];
+/** Resolved sidewalk band widths for a road; zero when the road declares no sidewalk. */
+export declare function sidewalkWidthOf(road: RoadEnvironmentDescriptor): number;
+/**
+ * The two sidewalk walking paths of a road — offset polylines running down the middle of each
+ * sidewalk band. Pedestrians spawn and route along these instead of the asphalt.
+ */
+export declare function sidewalkPaths(road: RoadEnvironmentDescriptor): readonly (readonly RoadPoint[])[];
+/** A placement anchor on the curb line: position, outward-facing heading, and which side it sits on. */
+export interface FurnitureSpot {
+    position: RoadPoint;
+    /** Yaw (radians, engine `rotationY` convention) facing away from the road. */
+    heading: number;
+    side: "left" | "right";
+    /** Arc-length distance along the road at this spot. */
+    along: number;
+}
+/** Options for {@link furnitureSpots}. */
+export interface FurnitureSpotOptions {
+    /** Distance between consecutive spots along the road. Default 24. */
+    spacing?: number;
+    /** Which curb lines to populate. Default "both". */
+    sides?: "both" | "left" | "right";
+    /** Alternate sides spot-by-spot instead of mirroring every spot. Default true. */
+    stagger?: boolean;
+    /** Extra outward shift past the curb line (e.g. to center furniture in the sidewalk). Default 0. */
+    outset?: number;
+}
+/**
+ * Evenly spaced street-furniture anchors along a road's curb lines — streetlights, palms, signs,
+ * hydrants, benches. Each spot sits just outside the asphalt (plus `outset`), faces away from
+ * the street, and alternates sides by default so lights stagger like a real avenue. This is the
+ * answer to "where do I put it": furniture is an asset of the street, never a hand-typed coordinate.
+ */
+export declare function furnitureSpots(road: RoadEnvironmentDescriptor, options?: FurnitureSpotOptions): readonly FurnitureSpot[];
+/** Options for {@link parkingSpots}. */
+export interface ParkingSpotOptions {
+    /** Distance between consecutive parked-car anchors. Default 18. */
+    spacing?: number;
+    /** Which side(s) of the street to line with parking. Default "both". */
+    sides?: "both" | "left" | "right";
+}
+/** A curbside parking anchor: position at the road edge and a heading parallel to the street. */
+export interface ParkingSpot {
+    position: RoadPoint;
+    /** Yaw (radians) aligned with the direction of travel on that side (right-hand traffic). */
+    heading: number;
+    side: "left" | "right";
+}
+/**
+ * Curbside parking anchors along a road: hugging the edge of the asphalt, headed parallel to the
+ * street in that side's direction of travel. Spawn parked vehicles here instead of eyeballing
+ * coordinates in the middle of the carriageway.
+ */
+export declare function parkingSpots(road: RoadEnvironmentDescriptor, options?: ParkingSpotOptions): readonly ParkingSpot[];
+/**
+ * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
+ * 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;

package/dist/world/streets.js

@@ -0,0 +1,144 @@
+import { pathLength } from "./roads.js";
+function normalAt(path, index) {
+    const prev = path[Math.max(0, index - 1)];
+    const next = path[Math.min(path.length - 1, index + 1)];
+    const dx = next[0] - prev[0];
+    const dz = next[1] - prev[1];
+    const length = Math.hypot(dx, dz) || 1;
+    return [-dz / length, dx / length];
+}
+/**
+ * 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
+ * left of the direction of travel, negative on the right.
+ */
+export function offsetPath(path, offset) {
+    return path.map((point, index) => {
+        const [nx, nz] = normalAt(path, index);
+        return [point[0] + nx * offset, point[1] + nz * offset];
+    });
+}
+/**
+ * Two right-hand-traffic lane centerlines for a road — each offset a quarter of the drivable
+ * width from the center and ordered in its direction of travel. Feed a lane's `path` straight
+ * into `nav/pathFollow` for traffic AI, or use its endpoints as directed car spawn points.
+ */
+export function laneCenters(road) {
+    const laneOffset = road.width / 4;
+    const forward = offsetPath(road.path, -laneOffset);
+    const reverse = offsetPath(road.path, laneOffset);
+    return [
+        { path: forward, direction: "forward" },
+        { path: [...reverse].reverse(), direction: "reverse" },
+    ];
+}
+/** Resolved sidewalk band widths for a road; zero when the road declares no sidewalk. */
+export function sidewalkWidthOf(road) {
+    return road.sidewalk === false ? 0 : road.sidewalk.width;
+}
+/**
+ * The two sidewalk walking paths of a road — offset polylines running down the middle of each
+ * sidewalk band. Pedestrians spawn and route along these instead of the asphalt.
+ */
+export function sidewalkPaths(road) {
+    const width = sidewalkWidthOf(road);
+    if (width <= 0)
+        return [];
+    const offset = road.width / 2 + width / 2;
+    return [offsetPath(road.path, offset), offsetPath(road.path, -offset)];
+}
+function pointAlong(path, along) {
+    let remaining = along;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const segLength = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        if (remaining <= segLength || i === path.length - 2) {
+            const t = segLength <= 0 ? 0 : Math.min(1, remaining / segLength);
+            const length = segLength || 1;
+            return {
+                point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
+                tangent: [(b[0] - a[0]) / length, (b[1] - a[1]) / length],
+            };
+        }
+        remaining -= segLength;
+    }
+    const first = path[0] ?? [0, 0];
+    return { point: first, tangent: [0, 1] };
+}
+/**
+ * Evenly spaced street-furniture anchors along a road's curb lines — streetlights, palms, signs,
+ * hydrants, benches. Each spot sits just outside the asphalt (plus `outset`), faces away from
+ * the street, and alternates sides by default so lights stagger like a real avenue. This is the
+ * answer to "where do I put it": furniture is an asset of the street, never a hand-typed coordinate.
+ */
+export function furnitureSpots(road, options = {}) {
+    const spacing = options.spacing ?? 24;
+    const sides = options.sides ?? "both";
+    const stagger = options.stagger ?? true;
+    const outset = options.outset ?? 0;
+    if (spacing <= 0)
+        return [];
+    const total = pathLength(road.path);
+    const curbOffset = road.width / 2 + 0.6 + outset;
+    const spots = [];
+    let index = 0;
+    for (let along = spacing / 2; along < total; along += spacing) {
+        const { point, tangent } = pointAlong(road.path, along);
+        const normal = [-tangent[1], tangent[0]];
+        const wanted = sides === "both" ? (stagger ? [index % 2 === 0 ? "left" : "right"] : ["left", "right"]) : [sides];
+        for (const side of wanted) {
+            const sign = side === "left" ? 1 : -1;
+            const position = [point[0] + normal[0] * curbOffset * sign, point[1] + normal[1] * curbOffset * sign];
+            spots.push({
+                position,
+                heading: Math.atan2(normal[0] * sign, normal[1] * sign),
+                side,
+                along,
+            });
+        }
+        index += 1;
+    }
+    return spots;
+}
+/**
+ * Curbside parking anchors along a road: hugging the edge of the asphalt, headed parallel to the
+ * street in that side's direction of travel. Spawn parked vehicles here instead of eyeballing
+ * coordinates in the middle of the carriageway.
+ */
+export function parkingSpots(road, options = {}) {
+    const spacing = options.spacing ?? 18;
+    const sides = options.sides ?? "both";
+    if (spacing <= 0)
+        return [];
+    const total = pathLength(road.path);
+    const edgeOffset = road.width / 2 - 1.2;
+    const spots = [];
+    for (let along = spacing; along < total - spacing / 2; along += spacing) {
+        const { point, tangent } = pointAlong(road.path, along);
+        const normal = [-tangent[1], tangent[0]];
+        const wanted = sides === "both" ? ["left", "right"] : [sides];
+        for (const side of wanted) {
+            const sign = side === "left" ? 1 : -1;
+            const dir = side === "left" ? 1 : -1;
+            spots.push({
+                position: [point[0] + normal[0] * edgeOffset * sign, point[1] + normal[1] * edgeOffset * sign],
+                heading: Math.atan2(tangent[0] * dir, tangent[1] * dir),
+                side,
+            });
+        }
+    }
+    return spots;
+}
+/**
+ * A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the
+ * band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.
+ */
+export function sidewalkPoint(road, side, fraction) {
+    const paths = sidewalkPaths(road);
+    const path = side === "left" ? paths[0] : paths[1];
+    if (path === undefined)
+        return null;
+    const along = Math.max(0, Math.min(1, fraction)) * pathLength(path);
+    return pointAlong(path, along).point;
+}