@ingissa/navcore-react-native 1.0.4 → 1.0.8

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

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,102 @@
+/**
+ * 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

@@ -0,0 +1,81 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,115 @@
+/**
+ * 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

@@ -0,0 +1,86 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}

package/dist/core/src/snapper/ParallelRoadResolver.js

@@ -0,0 +1,83 @@
+/**
+ * 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 { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+const DEFAULTS = {
+    bearingPenalty: 80,
+    bearingMismatchThresholdDeg: 60,
+    inertiaPenalty: 40,
+    inertiaSegmentDist: 3,
+};
+export class ParallelRoadResolver {
+    constructor(options) {
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /**
+     * 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, vehicleBearing = null, prevSegmentIdx = null) {
+        return candidates
+            .map(c => this.score(c, vehicleBearing, prevSegmentIdx))
+            .sort((a, b) => a.score - b.score);
+    }
+    /**
+     * Resolve and return only the best candidate.
+     */
+    resolveBest(candidates, vehicleBearing = null, prevSegmentIdx = null) {
+        if (candidates.length === 0)
+            return null;
+        const resolved = this.resolve(candidates, vehicleBearing, prevSegmentIdx);
+        return resolved[0] ?? null;
+    }
+    score(c, vehicleBearing, prevSegmentIdx) {
+        let score = c.distanceMetres;
+        let bearingDeltaDeg = null;
+        let inertiaPenaltyApplied = false;
+        // ── U-turn / parallel road bearing penalty ───────────────────────────────
+        if (vehicleBearing !== null) {
+            const segBearing = getBearingBetweenPoints(c.segA, c.segB);
+            const delta = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+            bearingDeltaDeg = delta;
+            if (delta > this.options.bearingMismatchThresholdDeg) {
+                score += this.options.bearingPenalty;
+            }
+        }
+        // ── Inertia penalty (anti-oscillation) ───────────────────────────────────
+        if (prevSegmentIdx !== null &&
+            Math.abs(c.segmentIndex - prevSegmentIdx) >= this.options.inertiaSegmentDist) {
+            score += this.options.inertiaPenalty;
+            inertiaPenaltyApplied = true;
+        }
+        return { ...c, score, bearingDeltaDeg, inertiaPenaltyApplied };
+    }
+    /**
+     * 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, segA, segB) {
+        const segBearing = getBearingBetweenPoints(segA, segB);
+        const delta = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+        return delta > this.options.bearingMismatchThresholdDeg;
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Module 2: RouteSnapper
+ * Projects GPS coordinates onto the route with anti-oscillation and U-turn protection.
+ * Merges BasicSnapper + AdvancedSnapper from nav-sdk into a single module.
+ */
+import { type Coordinate } from '../geo/haversine';
+export interface SnapResult {
+    idx: number;
+    dist: number;
+    proj: Coordinate;
+}
+export interface SnapperOptions {
+    /** Enable bearing-based U-turn anti-snap penalty */
+    useBearingPenalty?: boolean;
+    /** Enable inertia penalty to prevent oscillation between segments */
+    useInertiaPenalty?: boolean;
+    /** Max search distance hard cutoff (metres) */
+    maxSnapDistance?: number;
+}
+export declare class RouteSnapper {
+    private readonly options;
+    constructor(options?: SnapperOptions);
+    /**
+     * Find the nearest projection of a GPS point onto the route.
+     *
+     * @param gps             Current GPS coordinate [lng, lat]
+     * @param route           Route geometry
+     * @param startIdx        Search window start
+     * @param windowSize      Number of segments to scan
+     * @param isCircuit       Whether the route is a closed circuit
+     * @param maxProgressIdx  Highest index ever reached (for circuit wrap detection)
+     * @param fallbackIdx     Fallback index if no match found
+     * @param vehicleBearing  Current vehicle bearing (null disables bearing penalty)
+     * @param prevSegment     Previous snapped segment index (null disables inertia)
+     */
+    snap(gps: Coordinate, route: Coordinate[], startIdx: number, windowSize: number, isCircuit: boolean, maxProgressIdx: number, fallbackIdx: number, vehicleBearing?: number | null, prevSegment?: number | null): SnapResult;
+}
+//# sourceMappingURL=RouteSnapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RouteSnapper.d.ts","sourceRoot":"","sources":["../../../../../core/src/snapper/RouteSnapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,kBAAkB,CAAC;AAWtE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAQD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,OAAO,CAAC,EAAE,cAAc;IAIpC;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,EAClB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,MAAM,GAAG,IAAW,EACpC,WAAW,GAAE,MAAM,GAAG,IAAW,GAChC,UAAU;CAuDd"}

package/dist/core/src/snapper/RouteSnapper.js

@@ -0,0 +1,80 @@
+/**
+ * Module 2: RouteSnapper
+ * Projects GPS coordinates onto the route with anti-oscillation and U-turn protection.
+ * Merges BasicSnapper + AdvancedSnapper from nav-sdk into a single module.
+ */
+import { haversineDistance } from '../geo/haversine';
+import { projectPointOnSegment } from '../geo/projection';
+import { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+import { MAX_SNAP_DISTANCE, BEARING_MISMATCH_THRESHOLD, BEARING_MISMATCH_PENALTY, INERTIA_PENALTY, INERTIA_SEGMENT_DIST } from '../constants';
+const DEFAULT_OPTIONS = {
+    useBearingPenalty: true,
+    useInertiaPenalty: true,
+    maxSnapDistance: MAX_SNAP_DISTANCE,
+};
+export class RouteSnapper {
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Find the nearest projection of a GPS point onto the route.
+     *
+     * @param gps             Current GPS coordinate [lng, lat]
+     * @param route           Route geometry
+     * @param startIdx        Search window start
+     * @param windowSize      Number of segments to scan
+     * @param isCircuit       Whether the route is a closed circuit
+     * @param maxProgressIdx  Highest index ever reached (for circuit wrap detection)
+     * @param fallbackIdx     Fallback index if no match found
+     * @param vehicleBearing  Current vehicle bearing (null disables bearing penalty)
+     * @param prevSegment     Previous snapped segment index (null disables inertia)
+     */
+    snap(gps, route, startIdx, windowSize, isCircuit, maxProgressIdx, fallbackIdx, vehicleBearing = null, prevSegment = null) {
+        const routeLength = route.length;
+        let bestIdx = fallbackIdx;
+        let bestScore = Infinity;
+        let bestDist = Infinity;
+        let bestProj = route[fallbackIdx] ?? [0, 0];
+        for (let step = 0; step <= windowSize; step++) {
+            let i = startIdx + step;
+            if (i > routeLength - 2) {
+                if (isCircuit && maxProgressIdx > routeLength * 0.7) {
+                    i = i % (routeLength - 1);
+                }
+                else {
+                    break;
+                }
+            }
+            if (i < 0 || i >= routeLength - 1)
+                continue;
+            const segA = route[i];
+            const segB = route[i + 1];
+            const p = projectPointOnSegment(gps, segA, segB);
+            const d = haversineDistance(gps[1], gps[0], p[1], p[0]);
+            // Hard cutoff
+            if (d > this.options.maxSnapDistance * 2)
+                continue;
+            let score = d;
+            // ── Bearing penalty (U-turn anti-snap) ──────────────────────────────
+            if (this.options.useBearingPenalty && vehicleBearing !== null) {
+                const segBearing = getBearingBetweenPoints(segA, segB);
+                const bearingDiff = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+                if (bearingDiff > BEARING_MISMATCH_THRESHOLD) {
+                    score += BEARING_MISMATCH_PENALTY;
+                }
+            }
+            // ── Inertia penalty ─────────────────────────────────────────────────
+            if (this.options.useInertiaPenalty && prevSegment !== null &&
+                Math.abs(i - prevSegment) >= INERTIA_SEGMENT_DIST) {
+                score += INERTIA_PENALTY;
+            }
+            if (score < bestScore) {
+                bestScore = score;
+                bestDist = d;
+                bestIdx = i;
+                bestProj = p;
+            }
+        }
+        return { idx: bestIdx, dist: bestDist, proj: bestProj };
+    }
+}