@ingissa/navcore-simulator 1.0.8 → 1.0.9

package/dist/core/src/route-builder/CustomRouteBuilder.js

@@ -1,160 +0,0 @@
-/**
- * Module 10: CustomRouteBuilder
- * Build custom routes with unlimited waypoints, chunking, and GPX/GeoJSON.
- */
-let _counter = 0;
-function generateId() {
-    return `wp_${Date.now()}_${++_counter}`;
-}
-/**
- * CustomRouteBuilder — builds exam routes from waypoints.
- *
- * Pass a DirectionsProvider to `build()` for routed connections.
- * Without a provider, `build()` returns straight-line geometry.
- */
-export class CustomRouteBuilder {
-    constructor() {
-        this.waypoints = [];
-    }
-    /** Add a waypoint at the end. Returns the generated ID. */
-    addWaypoint(coord, options) {
-        const id = generateId();
-        this.waypoints.push({ id, coord, options });
-        return id;
-    }
-    /** Insert a waypoint after an existing one. Returns the new ID. */
-    insertWaypoint(coord, afterId) {
-        const idx = this.waypoints.findIndex(w => w.id === afterId);
-        if (idx === -1)
-            throw new Error(`Waypoint ${afterId} not found`);
-        const id = generateId();
-        this.waypoints.splice(idx + 1, 0, { id, coord, options: undefined });
-        return id;
-    }
-    /** Remove a waypoint by ID */
-    removeWaypoint(id) {
-        const idx = this.waypoints.findIndex(w => w.id === id);
-        if (idx === -1)
-            throw new Error(`Waypoint ${id} not found`);
-        this.waypoints.splice(idx, 1);
-    }
-    /** Move a waypoint to a new coordinate */
-    moveWaypoint(id, newCoord) {
-        const wp = this.waypoints.find(w => w.id === id);
-        if (!wp)
-            throw new Error(`Waypoint ${id} not found`);
-        wp.coord = newCoord;
-    }
-    /** Get all current waypoints */
-    getWaypoints() {
-        return this.waypoints;
-    }
-    /** Get the number of waypoints */
-    get size() {
-        return this.waypoints.length;
-    }
-    /**
-     * Chunk waypoints for a provider with max waypoint limits.
-     * OVERLAP_1: adjacent chunks share 1 waypoint (last of prev = first of next)
-     * OVERLAP_2: adjacent chunks share 2 waypoints
-     */
-    chunk(strategy = 'OVERLAP_1', maxPerChunk = 25) {
-        const coords = this.waypoints.map(w => w.coord);
-        if (coords.length <= maxPerChunk)
-            return [coords];
-        const overlap = strategy === 'OVERLAP_2' ? 2 : 1;
-        const step = maxPerChunk - overlap;
-        const chunks = [];
-        for (let i = 0; i < coords.length; i += step) {
-            const chunk = coords.slice(i, i + maxPerChunk);
-            chunks.push(chunk);
-            if (i + maxPerChunk >= coords.length)
-                break;
-        }
-        return chunks;
-    }
-    /**
-     * Build straight-line geometry (no provider needed).
-     * For routed geometry, pass chunks to a DirectionsProvider externally.
-     */
-    buildStraightLine() {
-        return {
-            geometry: this.waypoints.map(w => w.coord),
-            waypoints: [...this.waypoints],
-        };
-    }
-    /** Import waypoints from a GPX string */
-    fromGPX(gpx) {
-        this.waypoints = [];
-        // Minimal GPX parser — extract <trkpt> and <wpt> elements
-        const pointRegex = /<(?:trkpt|wpt|rtept)\s+lat="([^"]+)"\s+lon="([^"]+)"/g;
-        let match;
-        while ((match = pointRegex.exec(gpx)) !== null) {
-            const lat = parseFloat(match[1]);
-            const lon = parseFloat(match[2]);
-            if (isFinite(lat) && isFinite(lon)) {
-                this.addWaypoint([lon, lat]);
-            }
-        }
-    }
-    /** Export the current waypoints as a GPX string */
-    toGPX() {
-        const points = this.waypoints.map(w => `    <wpt lat="${w.coord[1]}" lon="${w.coord[0]}">` +
-            (w.options?.name ? `\n      <name>${w.options.name}</name>` : '') +
-            `\n    </wpt>`).join('\n');
-        return `<?xml version="1.0" encoding="UTF-8"?>
-<gpx version="1.1" creator="NavCore SDK">
-${points}
-</gpx>`;
-    }
-    /** Import waypoints from GeoJSON */
-    fromGeoJSON(geojson) {
-        this.waypoints = [];
-        if (geojson.type === 'FeatureCollection' && geojson.features) {
-            for (const feature of geojson.features) {
-                if (feature.geometry.type === 'Point') {
-                    const coord = feature.geometry.coordinates;
-                    this.addWaypoint(coord);
-                }
-                else if (feature.geometry.type === 'LineString') {
-                    const coords = feature.geometry.coordinates;
-                    for (const coord of coords) {
-                        this.addWaypoint(coord);
-                    }
-                }
-            }
-        }
-    }
-    /** Export the current route as GeoJSON FeatureCollection */
-    toGeoJSON() {
-        const pointFeatures = this.waypoints.map((w, i) => ({
-            type: 'Feature',
-            geometry: {
-                type: 'Point',
-                coordinates: w.coord,
-            },
-            properties: {
-                id: w.id,
-                order: i,
-                name: w.options?.name ?? null,
-                silent: w.options?.silent ?? false,
-            },
-        }));
-        const lineFeature = {
-            type: 'Feature',
-            geometry: {
-                type: 'LineString',
-                coordinates: this.waypoints.map(w => w.coord),
-            },
-            properties: { type: 'route' },
-        };
-        return {
-            type: 'FeatureCollection',
-            features: [...pointFeatures, lineFeature],
-        };
-    }
-    /** Clear all waypoints */
-    clear() {
-        this.waypoints = [];
-    }
-}

package/dist/core/src/route-plan/RoutePlan.d.ts

@@ -1,38 +0,0 @@
-/**
- * RoutePlan — the canonical, navigation-ready form of a provider route.
- *
- * Directions providers return vendor-specific steps and geometry. NavCore needs
- * instructions positioned on that geometry. This module owns that conversion so
- * applications do not need provider-specific glue code.
- */
-import type { DirectionsResult } from '../directions/DirectionsProvider';
-import { type Coordinate } from '../geo/haversine';
-import type { NavInstruction } from '../progress/InstructionResolver';
-export interface RoutePlan {
-    /** Validated, immutable route geometry in [lng, lat] order. */
-    geometry: ReadonlyArray<Coordinate>;
-    /** Immutable, route-aligned maneuver instructions. */
-    instructions: ReadonlyArray<NavInstruction>;
-    /** Distance measured along the canonical geometry, in metres. */
-    distanceM: number;
-    /** Duration supplied by the directions provider, in seconds. */
-    durationS: number;
-    /** Original provider-reported distance, when supplied. */
-    providerDistanceM: number;
-    /** Optional identifier useful for diagnostics and analytics. */
-    provider?: string;
-}
-export interface CreateRoutePlanOptions {
-    /** Identifier for the provider that produced the route. */
-    provider?: string;
-}
-/**
- * Converts a generic directions response into NavCore's canonical route model.
- *
- * Each maneuver is projected onto the complete route instead of trusting a
- * provider-specific step index. The resulting `cumulativeOffset` is precise to
- * the point within a segment, which keeps progress and voice timing correct on
- * sparse route geometry.
- */
-export declare function createRoutePlan(result: DirectionsResult, options?: CreateRoutePlanOptions): RoutePlan;
-//# sourceMappingURL=RoutePlan.d.ts.map

package/dist/core/src/route-plan/RoutePlan.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"RoutePlan.d.ts","sourceRoot":"","sources":["../../../../../core/src/route-plan/RoutePlan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,sDAAsD;IACtD,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC5C,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,sBAA2B,GACnC,SAAS,CA4BX"}

package/dist/core/src/route-plan/RoutePlan.js

@@ -1,102 +0,0 @@
-/**
- * RoutePlan — the canonical, navigation-ready form of a provider route.
- *
- * Directions providers return vendor-specific steps and geometry. NavCore needs
- * instructions positioned on that geometry. This module owns that conversion so
- * applications do not need provider-specific glue code.
- */
-import { buildForwardCumulativeDistances } from '../geo/cumulative';
-import { haversineDistance } from '../geo/haversine';
-import { projectPointOnSegment } from '../geo/projection';
-/**
- * Converts a generic directions response into NavCore's canonical route model.
- *
- * Each maneuver is projected onto the complete route instead of trusting a
- * provider-specific step index. The resulting `cumulativeOffset` is precise to
- * the point within a segment, which keeps progress and voice timing correct on
- * sparse route geometry.
- */
-export function createRoutePlan(result, options = {}) {
-    const geometry = copyAndValidateGeometry(result.geometry);
-    const cumulative = buildForwardCumulativeDistances(geometry);
-    const instructions = result.legs
-        .flatMap((leg) => leg.steps ?? [])
-        .map((step) => {
-        const position = locateOnRoute(step.maneuver.location, geometry, cumulative);
-        const text = step.maneuver.instruction ?? step.name;
-        return freezeInstruction({
-            location: position.coordinate,
-            geometryIndex: position.geometryIndex,
-            cumulativeOffset: position.cumulativeOffset,
-            bearingBefore: step.maneuver.bearingBefore,
-            bearingAfter: step.maneuver.bearingAfter,
-            ...(text ? { text, instruction: text } : {}),
-        });
-    })
-        .sort((a, b) => a.cumulativeOffset - b.cumulativeOffset);
-    return Object.freeze({
-        geometry: Object.freeze(geometry),
-        instructions: Object.freeze(instructions),
-        distanceM: cumulative[cumulative.length - 1] ?? 0,
-        durationS: requireFiniteNonNegative(result.duration, 'duration'),
-        providerDistanceM: requireFiniteNonNegative(result.distance, 'distance'),
-        ...(options.provider ? { provider: options.provider } : {}),
-    });
-}
-function copyAndValidateGeometry(input) {
-    if (input.length < 2) {
-        throw new Error('[RoutePlan] A route requires at least two coordinates');
-    }
-    return input.map((coord, index) => {
-        if (!isValidCoordinate(coord)) {
-            throw new Error(`[RoutePlan] Invalid coordinate at geometry index ${index}`);
-        }
-        return Object.freeze([coord[0], coord[1]]);
-    });
-}
-function locateOnRoute(target, geometry, cumulative) {
-    if (!isValidCoordinate(target)) {
-        throw new Error('[RoutePlan] Invalid maneuver coordinate');
-    }
-    let best = null;
-    let bestDistance = Infinity;
-    for (let index = 0; index < geometry.length - 1; index++) {
-        const start = geometry[index];
-        const end = geometry[index + 1];
-        const projected = projectPointOnSegment(target, start, end);
-        const distance = haversineDistance(target[1], target[0], projected[1], projected[0]);
-        if (distance >= bestDistance)
-            continue;
-        const segmentLength = haversineDistance(start[1], start[0], end[1], end[0]);
-        const fraction = segmentFraction(projected, start, end);
-        bestDistance = distance;
-        best = {
-            geometryIndex: index,
-            cumulativeOffset: (cumulative[index] ?? 0) + segmentLength * fraction,
-            coordinate: Object.freeze([projected[0], projected[1]]),
-        };
-    }
-    // Geometry has already been checked for at least two points.
-    return best;
-}
-function segmentFraction(point, start, end) {
-    const dx = end[0] - start[0];
-    const dy = end[1] - start[1];
-    const lengthSquared = dx * dx + dy * dy;
-    if (lengthSquared === 0)
-        return 0;
-    return Math.max(0, Math.min(1, ((point[0] - start[0]) * dx + (point[1] - start[1]) * dy) / lengthSquared));
-}
-function freezeInstruction(instruction) {
-    return Object.freeze(instruction);
-}
-function isValidCoordinate(coord) {
-    return Number.isFinite(coord[0]) && Number.isFinite(coord[1]) &&
-        coord[0] >= -180 && coord[0] <= 180 && coord[1] >= -90 && coord[1] <= 90;
-}
-function requireFiniteNonNegative(value, name) {
-    if (!Number.isFinite(value) || value < 0) {
-        throw new Error(`[RoutePlan] Invalid ${name}`);
-    }
-    return value;
-}

package/dist/core/src/session/NavigationSession.d.ts

@@ -1,81 +0,0 @@
-/**
- * NavigationSession — the ergonomic application-facing NavCore API.
- *
- * It owns the route-provider → RoutePlan → NavCore handoff and offers typed
- * subscriptions. `coordinates` are ordered routing waypoints; use `loadRoute`
- * for a route that has already been normalized into a RoutePlan.
- */
-import type { DirectionsOptions, DirectionsProvider } from '../directions/DirectionsProvider';
-import { NavCore, type NavCoreOptions, type NavCoreState, type NavGpsUpdate } from '../NavCore';
-import type { NavInstruction } from '../progress/InstructionResolver';
-import { type RoutePlan } from '../route-plan/RoutePlan';
-import type { Coordinate } from '../geo/haversine';
-export interface OriginDestinationNavigationRequest {
-    origin: Coordinate;
-    destination: Coordinate;
-    /** Optional stops, traversed in the supplied order. */
-    waypoints?: ReadonlyArray<Coordinate>;
-    coordinates?: never;
-    directions?: DirectionsOptions;
-}
-export interface CoordinatesNavigationRequest {
-    /** Ordered routing waypoints. At least two are required. */
-    coordinates: ReadonlyArray<Coordinate>;
-    origin?: never;
-    destination?: never;
-    waypoints?: never;
-    directions?: DirectionsOptions;
-}
-export type NavigationRequest = OriginDestinationNavigationRequest | CoordinatesNavigationRequest;
-export interface NavigationSessionOptions {
-    provider: DirectionsProvider;
-    /** Optional provider label retained on created RoutePlans. */
-    providerName?: string;
-    /** Reuse an existing engine; the caller retains responsibility for it. */
-    engine?: NavCore;
-    /** Options used only when the session creates its own engine. */
-    engineOptions?: NavCoreOptions;
-}
-export interface NavigationSessionEventMap {
-    state: NavCoreState;
-    routeLoaded: RoutePlan;
-    navigationStarted: undefined;
-    instruction: NavInstruction;
-    deviation: {
-        anchorIndex: number;
-        ghostCoord: Coordinate;
-    };
-    rejoined: {
-        resumeIndex: number;
-    };
-    arrival: undefined;
-}
-type EventName = keyof NavigationSessionEventMap;
-type EventHandler<K extends EventName> = (payload: NavigationSessionEventMap[K]) => void;
-export declare class NavigationSession {
-    readonly engine: NavCore;
-    private readonly provider;
-    private readonly providerName?;
-    private readonly ownsEngine;
-    private readonly listeners;
-    private readonly engineListeners;
-    private destroyed;
-    private currentPlan;
-    constructor(options: NavigationSessionOptions);
-    /** Fetch, normalize, load, and start a route from either supported input form. */
-    navigate(request: NavigationRequest): Promise<RoutePlan>;
-    /** Load a route that was previously normalized, optionally starting navigation. */
-    loadRoute(plan: RoutePlan, start?: boolean): void;
-    update(gps: NavGpsUpdate): NavCoreState;
-    tick(nowMs: number): NavCoreState;
-    getState(): NavCoreState;
-    getRoutePlan(): RoutePlan | null;
-    /** Subscribe to a typed event. Returns an unsubscribe function. */
-    subscribe<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
-    destroy(): void;
-    private emit;
-    private assertActive;
-}
-export declare function createNavigationSession(options: NavigationSessionOptions): NavigationSession;
-export {};
-//# sourceMappingURL=NavigationSession.d.ts.map

package/dist/core/src/session/NavigationSession.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"NavigationSession.d.ts","sourceRoot":"","sources":["../../../../../core/src/session/NavigationSession.ts"],"names":[],"mappings":"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"}

package/dist/core/src/session/NavigationSession.js

@@ -1,115 +0,0 @@
-/**
- * NavigationSession — the ergonomic application-facing NavCore API.
- *
- * It owns the route-provider → RoutePlan → NavCore handoff and offers typed
- * subscriptions. `coordinates` are ordered routing waypoints; use `loadRoute`
- * for a route that has already been normalized into a RoutePlan.
- */
-import { NavCore } from '../NavCore';
-import { createRoutePlan } from '../route-plan/RoutePlan';
-export class NavigationSession {
-    constructor(options) {
-        this.listeners = new Map();
-        this.destroyed = false;
-        this.currentPlan = null;
-        this.provider = options.provider;
-        this.providerName = options.providerName;
-        this.ownsEngine = !options.engine;
-        this.engine = options.engine ?? new NavCore(options.engineOptions);
-        this.engineListeners = [
-            { event: 'update', handler: (state) => this.emit('state', state) },
-            { event: 'instruction', handler: (instruction) => this.emit('instruction', instruction) },
-            { event: 'deviation', handler: (event) => this.emit('deviation', event) },
-            { event: 'rejoined', handler: (event) => this.emit('rejoined', event) },
-            { event: 'arrival', handler: () => this.emit('arrival', undefined) },
-        ];
-        for (const { event, handler } of this.engineListeners) {
-            this.engine.on(event, handler);
-        }
-    }
-    /** Fetch, normalize, load, and start a route from either supported input form. */
-    async navigate(request) {
-        this.assertActive();
-        const result = await this.provider.getRoute(resolveWaypoints(request), request.directions);
-        const plan = createRoutePlan(result, { provider: this.providerName });
-        this.loadRoute(plan, true);
-        return plan;
-    }
-    /** Load a route that was previously normalized, optionally starting navigation. */
-    loadRoute(plan, start = false) {
-        this.assertActive();
-        this.currentPlan = plan;
-        this.engine.loadRoute(plan);
-        this.emit('routeLoaded', plan);
-        if (start) {
-            this.engine.startNavigation();
-            this.emit('navigationStarted', undefined);
-        }
-    }
-    update(gps) {
-        this.assertActive();
-        return this.engine.update(gps);
-    }
-    tick(nowMs) {
-        this.assertActive();
-        return this.engine.tick(nowMs);
-    }
-    getState() {
-        return this.engine.getState();
-    }
-    getRoutePlan() {
-        return this.currentPlan;
-    }
-    /** Subscribe to a typed event. Returns an unsubscribe function. */
-    subscribe(event, handler) {
-        this.assertActive();
-        const handlers = this.listeners.get(event) ?? new Set();
-        const untypedHandler = handler;
-        handlers.add(untypedHandler);
-        this.listeners.set(event, handlers);
-        return () => {
-            handlers.delete(untypedHandler);
-            if (handlers.size === 0)
-                this.listeners.delete(event);
-        };
-    }
-    destroy() {
-        if (this.destroyed)
-            return;
-        this.destroyed = true;
-        for (const { event, handler } of this.engineListeners) {
-            this.engine.off(event, handler);
-        }
-        this.listeners.clear();
-        this.currentPlan = null;
-        if (this.ownsEngine)
-            this.engine.destroy();
-    }
-    emit(event, payload) {
-        for (const handler of this.listeners.get(event) ?? []) {
-            handler(payload);
-        }
-    }
-    assertActive() {
-        if (this.destroyed)
-            throw new Error('[NavigationSession] Session has been destroyed');
-    }
-}
-export function createNavigationSession(options) {
-    return new NavigationSession(options);
-}
-function resolveWaypoints(request) {
-    const coordinates = request.coordinates !== undefined
-        ? request.coordinates
-        : [request.origin, ...(request.waypoints ?? []), request.destination];
-    if (coordinates.length < 2) {
-        throw new Error('[NavigationSession] At least two routing coordinates are required');
-    }
-    return coordinates.map((coordinate, index) => {
-        if (!Number.isFinite(coordinate[0]) || !Number.isFinite(coordinate[1]) ||
-            coordinate[0] < -180 || coordinate[0] > 180 || coordinate[1] < -90 || coordinate[1] > 90) {
-            throw new Error(`[NavigationSession] Invalid routing coordinate at index ${index}`);
-        }
-        return [coordinate[0], coordinate[1]];
-    });
-}

package/dist/core/src/snapper/ParallelRoadResolver.d.ts

@@ -1,86 +0,0 @@
-/**
- * ParallelRoadResolver
- *
- * First-class feature: resolve GPS ambiguity on parallel roads (e.g. dual carriageways,
- * motorway + service road) and prevent U-turn snap.
- *
- * Extracts and extends the bearing penalty + inertia logic from RouteSnapper
- * into a standalone, composable API that can be used independently.
- *
- * FEATURE: PARALLEL_ROAD_RESOLUTION + U_TURN_PROTECTION
- *
- * @example
- * ```typescript
- * const resolver = new ParallelRoadResolver({ bearingPenalty: 80, inertiaPenalty: 40 });
- * const best = resolver.resolve(candidates, vehicleBearing, prevSegmentIndex);
- * ```
- */
-import type { Coordinate } from '../geo/haversine';
-export interface SnapCandidate {
-    /** Route segment index */
-    segmentIndex: number;
-    /** Projected point on segment */
-    projectedCoord: Coordinate;
-    /** Raw distance to route in metres */
-    distanceMetres: number;
-    /** Start of segment */
-    segA: Coordinate;
-    /** End of segment */
-    segB: Coordinate;
-}
-export interface ResolvedCandidate extends SnapCandidate {
-    /** Final score (lower is better) */
-    score: number;
-    /** Bearing delta that triggered U-turn protection (null if not triggered) */
-    bearingDeltaDeg: number | null;
-    /** Whether inertia penalty was applied */
-    inertiaPenaltyApplied: boolean;
-}
-export interface ParallelRoadResolverOptions {
-    /**
-     * Penalty added to score when vehicle bearing mismatches segment bearing
-     * beyond `bearingMismatchThresholdDeg`. Default: 80m equivalent.
-     */
-    bearingPenalty?: number;
-    /**
-     * Bearing mismatch threshold in degrees that activates the penalty.
-     * Default: 60°. Higher = more tolerant of U-turns.
-     */
-    bearingMismatchThresholdDeg?: number;
-    /**
-     * Penalty added when the candidate segment is far from the previously
-     * snapped segment, preventing oscillation. Default: 40m equivalent.
-     */
-    inertiaPenalty?: number;
-    /**
-     * Minimum segment jump (in index units) to trigger inertia penalty.
-     * Default: 3.
-     */
-    inertiaSegmentDist?: number;
-}
-export declare class ParallelRoadResolver {
-    private readonly options;
-    constructor(options?: ParallelRoadResolverOptions);
-    /**
-     * Score and sort snap candidates — lowest score wins.
-     *
-     * @param candidates   Raw snap candidates (distance-sorted or unsorted)
-     * @param vehicleBearing  Current vehicle heading in degrees (null disables bearing check)
-     * @param prevSegmentIdx  Previously snapped segment index (null disables inertia)
-     * @returns Candidates sorted by score ascending, with debug metadata attached
-     */
-    resolve(candidates: SnapCandidate[], vehicleBearing?: number | null, prevSegmentIdx?: number | null): ResolvedCandidate[];
-    /**
-     * Resolve and return only the best candidate.
-     */
-    resolveBest(candidates: SnapCandidate[], vehicleBearing?: number | null, prevSegmentIdx?: number | null): ResolvedCandidate | null;
-    private score;
-    /**
-     * Quick utility: detect if the vehicle is likely performing a U-turn
-     * based on the difference between current bearing and route segment bearing.
-     *
-     * @returns true if the bearing difference exceeds the configured threshold
-     */
-    isLikelyUTurn(vehicleBearing: number, segA: Coordinate, segB: Coordinate): boolean;
-}
-//# sourceMappingURL=ParallelRoadResolver.d.ts.map

package/dist/core/src/snapper/ParallelRoadResolver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ParallelRoadResolver.d.ts","sourceRoot":"","sources":["../../../../../core/src/snapper/ParallelRoadResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,cAAc,EAAE,UAAU,CAAC;IAC3B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,qBAAqB;IACrB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0CAA0C;IAC1C,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AASD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;gBAEpD,OAAO,CAAC,EAAE,2BAA2B;IAIjD;;;;;;;OAOG;IACH,OAAO,CACL,UAAU,EAAE,aAAa,EAAE,EAC3B,cAAc,GAAE,MAAM,GAAG,IAAW,EACpC,cAAc,GAAE,MAAM,GAAG,IAAW,GACnC,iBAAiB,EAAE;IAMtB;;OAEG;IACH,WAAW,CACT,UAAU,EAAE,aAAa,EAAE,EAC3B,cAAc,GAAE,MAAM,GAAG,IAAW,EACpC,cAAc,GAAE,MAAM,GAAG,IAAW,GACnC,iBAAiB,GAAG,IAAI;IAM3B,OAAO,CAAC,KAAK;IA+Bb;;;;;OAKG;IACH,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO;CAKnF"}