@ingissa/navcore-react-native 1.0.4 → 1.0.8

package/dist/core/src/constants.js

@@ -0,0 +1,41 @@
+/**
+ * Engine constants — centralized tuning parameters.
+ * Extracted from packages/nav-sdk/src/shared/constants.ts
+ */
+// ── Corridor ──────────────────────────────────────────────────
+export const BASE_CORRIDOR_METERS = 25;
+export const MAX_CORRIDOR_METERS = 60;
+export const SPEED_CORRIDOR_FACTOR = 1.2;
+export const GPS_ACCURACY_FACTOR = 0.5;
+export const TURN_LOOKAHEAD_DISTANCE_METERS = 40;
+export const TURN_CORRIDOR_MULTIPLIER = 1.4;
+// ── Snapping ──────────────────────────────────────────────────
+export const MAX_SNAP_DISTANCE = 80;
+export const BEARING_MISMATCH_THRESHOLD = 90;
+export const BEARING_MISMATCH_PENALTY = 500;
+export const INERTIA_PENALTY = 200;
+export const INERTIA_SEGMENT_DIST = 5;
+export const SNAP_WINDOW_SIZE = 25;
+// ── Bearing ───────────────────────────────────────────────────
+export const BEARING_SMOOTHING_ALPHA = 0.3;
+export const BEARING_MIN_SPEED_MPS = 1.5;
+export const BEARING_ALIGNMENT_THRESHOLD = 55;
+// ── Dead Reckoning ────────────────────────────────────────────
+export const DR_MAX_AGE_MS = 5000;
+// ── Timing ────────────────────────────────────────────────────
+export const OFF_ROUTE_CONFIRM_MS = 2000;
+export const REJOIN_CONFIRM_MS = 1500;
+export const REJOIN_COOLDOWN_MS = 12000;
+export const STARTUP_GRACE_MS = 3000;
+export const DETOUR_COMMIT_MS = 4000;
+export const GPS_STALE_MS = 3000;
+export const GPS_AGE_CAP_SECONDS = 10;
+// ── Instruction ───────────────────────────────────────────────
+export const MANEUVER_TRIGGER_DIST = 25;
+// ── Predictor ─────────────────────────────────────────────────
+export const BETA_CORRECTION = 0.15;
+export const LOOK_AHEAD_SECONDS = 3;
+export const MIN_LOOK_AHEAD_METERS = 20;
+export const MAX_LOOK_AHEAD_METERS = 100;
+// ── Arrival ───────────────────────────────────────────────────
+export const ARRIVAL_THRESHOLD_METERS = 30;

package/dist/core/src/corridor/DeviationDetector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Module 4b: DeviationDetector
+ * Compound deviation detection using distance, bearing, and movement signals.
+ */
+import { type Coordinate } from '../geo/haversine';
+export interface DeviationSignals {
+    /** Distance from GPS to nearest route segment (metres) */
+    distanceToRoute: number;
+    /** Whether the distance exceeds the dynamic corridor */
+    outsideCorridor: boolean;
+    /** Whether the vehicle bearing diverges from the route bearing */
+    bearingMismatch: boolean;
+    /** Whether the vehicle is moving away from the next segment */
+    movingAway: boolean;
+    /** Compound confirmed: outsideCorridor AND (bearingMismatch OR movingAway) */
+    confirmed: boolean;
+}
+export interface ClosestSegment {
+    segmentIndex: number;
+    distance: number;
+    projection: Coordinate;
+}
+/**
+ * Find the closest segment to a GPS point within a search window.
+ */
+export declare function findClosestSegment(gps: Coordinate, route: Coordinate[], startIdx: number, windowSize: number, routeFlowBearing?: number | null): ClosestSegment;
+export declare class DeviationDetector {
+    /**
+     * Evaluate deviation signals for the current GPS position.
+     */
+    evaluate(gps: Coordinate, gpsBearing: number | null, speedMps: number, closest: ClosestSegment, route: Coordinate[], corridor: number, prevDistToNextSegment: number | null): DeviationSignals;
+}
+//# sourceMappingURL=DeviationDetector.d.ts.map

package/dist/core/src/corridor/DeviationDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeviationDetector.d.ts","sourceRoot":"","sources":["../../../../../core/src/corridor/DeviationDetector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,kBAAkB,CAAC;AAKtE,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,eAAe,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,gBAAgB,GAAE,MAAM,GAAG,IAAW,GACrC,cAAc,CA8ChB;AAED,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,QAAQ,CACN,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,qBAAqB,EAAE,MAAM,GAAG,IAAI,GACnC,gBAAgB;CAiCpB"}

package/dist/core/src/corridor/DeviationDetector.js

@@ -0,0 +1,83 @@
+/**
+ * Module 4b: DeviationDetector
+ * Compound deviation detection using distance, bearing, and movement signals.
+ */
+import { haversineDistance } from '../geo/haversine';
+import { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+import { BEARING_MISMATCH_THRESHOLD } from '../constants';
+/**
+ * Find the closest segment to a GPS point within a search window.
+ */
+export function findClosestSegment(gps, route, startIdx, windowSize, routeFlowBearing = null) {
+    let bestIdx = Math.max(0, startIdx);
+    let bestDist = Infinity;
+    let bestProj = route[bestIdx] ?? [0, 0];
+    const end = Math.min(startIdx + windowSize, route.length - 1);
+    for (let i = Math.max(0, startIdx); i < end; i++) {
+        const a = route[i];
+        const b = route[i + 1];
+        // Simple flat projection for speed (deviation detection doesn't need
+        // sub-metre accuracy — haversine is used for the final distance check)
+        const [px, py] = gps;
+        const [ax, ay] = a;
+        const [bx, by] = b;
+        const dx = bx - ax;
+        const dy = by - ay;
+        const lenSq = dx * dx + dy * dy;
+        let proj;
+        if (lenSq === 0) {
+            proj = a;
+        }
+        else {
+            let t = ((px - ax) * dx + (py - ay) * dy) / lenSq;
+            t = Math.max(0, Math.min(1, t));
+            proj = [ax + t * dx, ay + t * dy];
+        }
+        const d = haversineDistance(gps[1], gps[0], proj[1], proj[0]);
+        // Anti-parallel penalty: if route flow bearing is known, penalize
+        // segments going the opposite direction
+        if (routeFlowBearing !== null && d < bestDist * 1.5) {
+            const segBearing = getBearingBetweenPoints(a, b);
+            const diff = Math.abs(normalizeAngle(routeFlowBearing - segBearing));
+            if (diff > 120)
+                continue; // Very anti-parallel, skip
+        }
+        if (d < bestDist) {
+            bestDist = d;
+            bestIdx = i;
+            bestProj = proj;
+        }
+    }
+    return { segmentIndex: bestIdx, distance: bestDist, projection: bestProj };
+}
+export class DeviationDetector {
+    /**
+     * Evaluate deviation signals for the current GPS position.
+     */
+    evaluate(gps, gpsBearing, speedMps, closest, route, corridor, prevDistToNextSegment) {
+        const outsideCorridor = closest.distance > corridor;
+        // Bearing mismatch
+        let bearingMismatch = false;
+        if (gpsBearing !== null && closest.segmentIndex < route.length - 1) {
+            const segBearing = getBearingBetweenPoints(route[closest.segmentIndex], route[closest.segmentIndex + 1]);
+            const diff = Math.abs(normalizeAngle(gpsBearing - segBearing));
+            bearingMismatch = diff > BEARING_MISMATCH_THRESHOLD;
+        }
+        // Moving away detection
+        let movingAway = false;
+        if (prevDistToNextSegment !== null && speedMps > 1.5) {
+            const nextEnd = route[Math.min(closest.segmentIndex + 2, route.length - 1)];
+            const currentDistToNext = haversineDistance(gps[1], gps[0], nextEnd[1], nextEnd[0]);
+            movingAway = currentDistToNext > prevDistToNextSegment + 5;
+        }
+        // Compound confirmation: outside corridor AND (bearing mismatch OR moving away)
+        const confirmed = outsideCorridor && (bearingMismatch || movingAway);
+        return {
+            distanceToRoute: closest.distance,
+            outsideCorridor,
+            bearingMismatch,
+            movingAway,
+            confirmed,
+        };
+    }
+}

package/dist/core/src/corridor/DynamicCorridor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Module 4a: DynamicCorridor
+ * Speed-adaptive corridor width calculation.
+ */
+/**
+ * Compute speed-adaptive corridor width in metres.
+ *
+ * Corridor widens with speed: BASE + speed * FACTOR, capped at MAX.
+ * GPS accuracy optionally widens the corridor further.
+ * Turn lookahead widens corridor when approaching upcoming maneuvers to prevent false off-route alerts.
+ */
+export declare function calculateDynamicCorridor(speedMps: number, gpsAccuracy?: number | null, baseMeters?: number, maxMeters?: number, speedFactor?: number, accuracyFactor?: number, distanceToTurn?: number | null, turnMultiplier?: number, turnLookaheadDist?: number): number;
+//# sourceMappingURL=DynamicCorridor.d.ts.map

package/dist/core/src/corridor/DynamicCorridor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicCorridor.d.ts","sourceRoot":"","sources":["../../../../../core/src/corridor/DynamicCorridor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,MAAM,GAAG,IAAW,EACjC,UAAU,GAAE,MAA6B,EACzC,SAAS,GAAE,MAA4B,EACvC,WAAW,GAAE,MAA8B,EAC3C,cAAc,GAAE,MAA4B,EAC5C,cAAc,GAAE,MAAM,GAAG,IAAW,EACpC,cAAc,GAAE,MAAiC,EACjD,iBAAiB,GAAE,MAAuC,GACzD,MAAM,CAgBR"}

package/dist/core/src/corridor/DynamicCorridor.js

@@ -0,0 +1,26 @@
+/**
+ * Module 4a: DynamicCorridor
+ * Speed-adaptive corridor width calculation.
+ */
+import { BASE_CORRIDOR_METERS, MAX_CORRIDOR_METERS, SPEED_CORRIDOR_FACTOR, GPS_ACCURACY_FACTOR, TURN_LOOKAHEAD_DISTANCE_METERS, TURN_CORRIDOR_MULTIPLIER, } from '../constants';
+/**
+ * Compute speed-adaptive corridor width in metres.
+ *
+ * Corridor widens with speed: BASE + speed * FACTOR, capped at MAX.
+ * GPS accuracy optionally widens the corridor further.
+ * Turn lookahead widens corridor when approaching upcoming maneuvers to prevent false off-route alerts.
+ */
+export function calculateDynamicCorridor(speedMps, gpsAccuracy = null, baseMeters = BASE_CORRIDOR_METERS, maxMeters = MAX_CORRIDOR_METERS, speedFactor = SPEED_CORRIDOR_FACTOR, accuracyFactor = GPS_ACCURACY_FACTOR, distanceToTurn = null, turnMultiplier = TURN_CORRIDOR_MULTIPLIER, turnLookaheadDist = TURN_LOOKAHEAD_DISTANCE_METERS) {
+    let corridor = baseMeters + speedMps * speedFactor;
+    if (gpsAccuracy !== null && gpsAccuracy > 0) {
+        corridor += gpsAccuracy * accuracyFactor;
+    }
+    let effectiveMax = maxMeters;
+    if (distanceToTurn !== null && distanceToTurn >= 0 && distanceToTurn <= turnLookaheadDist) {
+        const proximity = 1 - Math.max(0, distanceToTurn / turnLookaheadDist);
+        const scale = 1 + (turnMultiplier - 1) * proximity;
+        corridor *= scale;
+        effectiveMax = maxMeters * turnMultiplier;
+    }
+    return Math.min(corridor, effectiveMax);
+}

package/dist/core/src/dead-reckoning/DeadReckoning.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Module 3: DeadReckoning
+ * Predicts vehicle position during GPS outages or stale fixes.
+ */
+import { type Coordinate } from '../geo/haversine';
+export interface DRAnchor {
+    coord: Coordinate;
+    idx: number;
+    ts: number;
+}
+export interface DRPrediction {
+    predictedCoord: Coordinate;
+    isActive: boolean;
+    ageMs: number;
+}
+/**
+ * Given a snapped anchor on the route, extrapolate forward using speed and bearing.
+ */
+export declare function computeDeadReckoningOnRoute(anchor: DRAnchor | null, speed: number, bearing: number, now: number, maxAgeMs?: number): DRPrediction;
+/**
+ * Stateful dead reckoning engine.
+ */
+export declare class DeadReckoningEngine {
+    private anchor;
+    private readonly maxAgeMs;
+    constructor(maxAgeMs?: number);
+    /** Set the anchor point (called when GPS is available and snapping succeeds) */
+    setAnchor(coord: Coordinate, idx: number, timestamp: number): void;
+    /** Predict position given current speed and bearing */
+    predict(speed: number, bearing: number, now: number): DRPrediction;
+    /** Clear the anchor (GPS restored) */
+    clearAnchor(): void;
+    getAnchor(): DRAnchor | null;
+}
+//# sourceMappingURL=DeadReckoning.d.ts.map

package/dist/core/src/dead-reckoning/DeadReckoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeadReckoning.d.ts","sourceRoot":"","sources":["../../../../../core/src/dead-reckoning/DeadReckoning.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAGrE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,UAAU,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,QAAQ,GAAG,IAAI,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAsB,GAC/B,YAAY,CAmBd;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,MAAsB;IAI5C,gFAAgF;IAChF,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIlE,uDAAuD;IACvD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY;IAIlE,sCAAsC;IACtC,WAAW,IAAI,IAAI;IAInB,SAAS,IAAI,QAAQ,GAAG,IAAI;CAG7B"}

package/dist/core/src/dead-reckoning/DeadReckoning.js

@@ -0,0 +1,49 @@
+/**
+ * Module 3: DeadReckoning
+ * Predicts vehicle position during GPS outages or stale fixes.
+ */
+import { destinationPoint } from '../geo/haversine';
+import { DR_MAX_AGE_MS } from '../constants';
+/**
+ * Given a snapped anchor on the route, extrapolate forward using speed and bearing.
+ */
+export function computeDeadReckoningOnRoute(anchor, speed, bearing, now, maxAgeMs = DR_MAX_AGE_MS) {
+    if (!anchor || speed < 0.5) {
+        return { predictedCoord: anchor?.coord ?? [0, 0], isActive: false, ageMs: 0 };
+    }
+    const ageMs = now - anchor.ts;
+    if (ageMs > maxAgeMs || ageMs < 0) {
+        return { predictedCoord: anchor.coord, isActive: false, ageMs };
+    }
+    const distM = speed * (ageMs / 1000);
+    const predicted = destinationPoint(anchor.coord[1], anchor.coord[0], bearing, distM);
+    return {
+        predictedCoord: predicted,
+        isActive: true,
+        ageMs,
+    };
+}
+/**
+ * Stateful dead reckoning engine.
+ */
+export class DeadReckoningEngine {
+    constructor(maxAgeMs = DR_MAX_AGE_MS) {
+        this.anchor = null;
+        this.maxAgeMs = maxAgeMs;
+    }
+    /** Set the anchor point (called when GPS is available and snapping succeeds) */
+    setAnchor(coord, idx, timestamp) {
+        this.anchor = { coord, idx, ts: timestamp };
+    }
+    /** Predict position given current speed and bearing */
+    predict(speed, bearing, now) {
+        return computeDeadReckoningOnRoute(this.anchor, speed, bearing, now, this.maxAgeMs);
+    }
+    /** Clear the anchor (GPS restored) */
+    clearAnchor() {
+        this.anchor = null;
+    }
+    getAnchor() {
+        return this.anchor;
+    }
+}

package/dist/core/src/directions/DirectionsProvider.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DirectionsProvider — Generic interface for route computation.
+ *
+ * All direction adapters (Mapbox, OSRM, Valhalla, ORS…) implement this contract.
+ * NavCore itself only depends on this interface — swap providers with zero engine changes.
+ */
+import type { Coordinate } from '../geo/haversine';
+export interface DirectionsOptions {
+    /** Travel mode */
+    profile?: 'driving' | 'cycling' | 'walking';
+    /** Include step-by-step maneuver data */
+    steps?: boolean;
+    /** Language for instruction text */
+    language?: string;
+    /** Return alternative routes */
+    alternatives?: boolean;
+}
+export interface DirectionsManeuver {
+    type: string;
+    modifier?: string;
+    location: Coordinate;
+    bearingBefore: number;
+    bearingAfter: number;
+    instruction?: string;
+}
+export interface DirectionsStep {
+    distance: number;
+    duration: number;
+    geometry: Coordinate[];
+    maneuver: DirectionsManeuver;
+    name?: string;
+}
+export interface DirectionsLeg {
+    distance: number;
+    duration: number;
+    steps?: DirectionsStep[];
+}
+export interface DirectionsResult {
+    /** Full route geometry as [lng, lat] coordinates */
+    geometry: Coordinate[];
+    /** Total distance in metres */
+    distance: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** Per-leg breakdown */
+    legs: DirectionsLeg[];
+    /** Raw API response for provider-specific access */
+    raw?: unknown;
+}
+/**
+ * Any directions source implements this single method.
+ *
+ * @example
+ * ```typescript
+ * const provider: DirectionsProvider = new OSRMDirectionsProvider({ baseUrl: '...' });
+ * const result = await provider.getRoute([[lng1, lat1], [lng2, lat2]]);
+ * engine.setRoute(result.geometry);
+ * ```
+ */
+export interface DirectionsProvider {
+    /**
+     * Compute a route through the given waypoints.
+     * Implementations MUST handle the case where `waypoints.length > provider limit`
+     * by chunking internally.
+     *
+     * @throws {Error} if fewer than 2 waypoints are given, or the API fails.
+     */
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+}
+//# sourceMappingURL=DirectionsProvider.d.ts.map

package/dist/core/src/directions/DirectionsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectionsProvider.d.ts","sourceRoot":"","sources":["../../../../../core/src/directions/DirectionsProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,UAAU,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,oDAAoD;IACpD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC3F"}

package/dist/core/src/directions/DirectionsProvider.js

@@ -0,0 +1,7 @@
+/**
+ * DirectionsProvider — Generic interface for route computation.
+ *
+ * All direction adapters (Mapbox, OSRM, Valhalla, ORS…) implement this contract.
+ * NavCore itself only depends on this interface — swap providers with zero engine changes.
+ */
+export {};

package/dist/core/src/directions/OSRMDirectionsProvider.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OSRMDirectionsProvider
+ *
+ * Self-hosted OSRM (Open Source Routing Machine) adapter.
+ * Zero API key required. Ideal for self-hosted deployments.
+ *
+ * @see https://project-osrm.org/docs/v5.24.0/api/
+ */
+import type { Coordinate } from '../geo/haversine';
+import type { DirectionsProvider, DirectionsOptions, DirectionsResult } from './DirectionsProvider';
+export interface OSRMConfig {
+    /** Base URL of your OSRM server, e.g. 'http://router.project-osrm.org' */
+    baseUrl: string;
+    /** Routing profile (default: 'driving') */
+    profile?: 'driving' | 'cycling' | 'walking';
+    /** Max waypoints per API request (OSRM supports unlimited, but chunking keeps requests fast) */
+    maxWaypointsPerChunk?: number;
+}
+export declare class OSRMDirectionsProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: OSRMConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private fetchRoute;
+    private fetchChunked;
+}
+//# sourceMappingURL=OSRMDirectionsProvider.d.ts.map

package/dist/core/src/directions/OSRMDirectionsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OSRMDirectionsProvider.d.ts","sourceRoot":"","sources":["../../../../../core/src/directions/OSRMDirectionsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEpG,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5C,gGAAgG;IAChG,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;gBAElC,MAAM,EAAE,UAAU;IAQxB,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAYjF,UAAU;YA8CV,YAAY;CA+B3B"}

package/dist/core/src/directions/OSRMDirectionsProvider.js

@@ -0,0 +1,90 @@
+/**
+ * OSRMDirectionsProvider
+ *
+ * Self-hosted OSRM (Open Source Routing Machine) adapter.
+ * Zero API key required. Ideal for self-hosted deployments.
+ *
+ * @see https://project-osrm.org/docs/v5.24.0/api/
+ */
+const DEFAULT_MAX_CHUNK = 100;
+export class OSRMDirectionsProvider {
+    constructor(config) {
+        this.config = {
+            baseUrl: config.baseUrl.replace(/\/$/, ''),
+            profile: config.profile ?? 'driving',
+            maxWaypointsPerChunk: config.maxWaypointsPerChunk ?? DEFAULT_MAX_CHUNK,
+        };
+    }
+    async getRoute(waypoints, options) {
+        if (waypoints.length < 2)
+            throw new Error('[OSRM] At least 2 waypoints required');
+        const profile = options?.profile ?? this.config.profile;
+        if (waypoints.length <= this.config.maxWaypointsPerChunk) {
+            return this.fetchRoute(waypoints, profile, options);
+        }
+        return this.fetchChunked(waypoints, profile, options);
+    }
+    async fetchRoute(waypoints, profile, options) {
+        const coords = waypoints.map(w => `${w[0]},${w[1]}`).join(';');
+        const steps = options?.steps !== false ? 'true' : 'false';
+        const url = `${this.config.baseUrl}/route/v1/${profile}/${coords}` +
+            `?overview=full&geometries=geojson&steps=${steps}&annotations=false`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`[OSRM] HTTP ${res.status}: ${res.statusText}`);
+        const data = await res.json();
+        if (data.code !== 'Ok' || !data.routes?.length) {
+            throw new Error(`[OSRM] No route found: ${data.code}`);
+        }
+        const route = data.routes[0];
+        return {
+            geometry: route.geometry.coordinates,
+            distance: route.distance,
+            duration: route.duration,
+            legs: (route.legs ?? []).map((leg) => ({
+                distance: leg.distance,
+                duration: leg.duration,
+                steps: (leg.steps ?? []).map((step) => ({
+                    distance: step.distance,
+                    duration: step.duration,
+                    geometry: step.geometry?.coordinates ?? [],
+                    maneuver: {
+                        type: step.maneuver?.type ?? 'unknown',
+                        modifier: step.maneuver?.modifier,
+                        location: step.maneuver?.location ?? [0, 0],
+                        bearingBefore: step.maneuver?.bearing_before ?? 0,
+                        bearingAfter: step.maneuver?.bearing_after ?? 0,
+                        instruction: step.name ?? undefined,
+                    },
+                    name: step.name,
+                })),
+            })),
+            raw: data,
+        };
+    }
+    async fetchChunked(waypoints, profile, options) {
+        const size = this.config.maxWaypointsPerChunk;
+        const chunks = [];
+        for (let i = 0; i < waypoints.length; i += size - 1) {
+            const chunk = waypoints.slice(i, i + size);
+            if (chunk.length < 2)
+                break;
+            chunks.push(chunk);
+            if (i + size >= waypoints.length)
+                break;
+        }
+        const results = await Promise.all(chunks.map(c => this.fetchRoute(c, profile, options)));
+        const geometry = [];
+        let distance = 0;
+        let duration = 0;
+        const legs = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            geometry.push(...(i === 0 ? r.geometry : r.geometry.slice(1)));
+            distance += r.distance;
+            duration += r.duration;
+            legs.push(...r.legs);
+        }
+        return { geometry, distance, duration, legs, raw: results.map(r => r.raw) };
+    }
+}

package/dist/core/src/directions/OpenRouteServiceProvider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OpenRouteServiceProvider
+ *
+ * OpenRouteService (ORS) API adapter. Free tier: 2000 req/day.
+ * Requires an API key from https://openrouteservice.org/
+ *
+ * @see https://openrouteservice.org/dev/#/api-docs/v2/directions
+ */
+import type { Coordinate } from '../geo/haversine';
+import type { DirectionsProvider, DirectionsOptions, DirectionsResult } from './DirectionsProvider';
+export type ORSProfile = 'driving-car' | 'driving-hgv' | 'cycling-regular' | 'cycling-road' | 'cycling-mountain' | 'foot-walking' | 'foot-hiking' | 'wheelchair';
+export interface ORSConfig {
+    /** ORS API key */
+    apiKey: string;
+    /** Routing profile (default: 'driving-car') */
+    profile?: ORSProfile;
+    /** API base URL (default: ORS public API) */
+    baseUrl?: string;
+    /** Max waypoints per request (ORS limit: 50) */
+    maxWaypointsPerChunk?: number;
+}
+export declare class OpenRouteServiceProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: ORSConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private profileFromOptions;
+    private fetchRoute;
+    private fetchChunked;
+}
+//# sourceMappingURL=OpenRouteServiceProvider.d.ts.map

package/dist/core/src/directions/OpenRouteServiceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouteServiceProvider.d.ts","sourceRoot":"","sources":["../../../../../core/src/directions/OpenRouteServiceProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEpG,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,YAAY,CAAC;AAEjB,MAAM,WAAW,SAAS;IACxB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAKD,qBAAa,wBAAyB,YAAW,kBAAkB;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAEjC,MAAM,EAAE,SAAS;IASvB,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAY/F,OAAO,CAAC,kBAAkB;YAQZ,UAAU;YA4DV,YAAY;CA+B3B"}

package/dist/core/src/directions/OpenRouteServiceProvider.js

@@ -0,0 +1,111 @@
+/**
+ * OpenRouteServiceProvider
+ *
+ * OpenRouteService (ORS) API adapter. Free tier: 2000 req/day.
+ * Requires an API key from https://openrouteservice.org/
+ *
+ * @see https://openrouteservice.org/dev/#/api-docs/v2/directions
+ */
+const DEFAULT_BASE_URL = 'https://api.openrouteservice.org/v2/directions';
+const DEFAULT_MAX_CHUNK = 50;
+export class OpenRouteServiceProvider {
+    constructor(config) {
+        this.config = {
+            apiKey: config.apiKey,
+            profile: config.profile ?? 'driving-car',
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            maxWaypointsPerChunk: config.maxWaypointsPerChunk ?? DEFAULT_MAX_CHUNK,
+        };
+    }
+    async getRoute(waypoints, options) {
+        if (waypoints.length < 2)
+            throw new Error('[ORS] At least 2 waypoints required');
+        const profile = this.profileFromOptions(options);
+        if (waypoints.length <= this.config.maxWaypointsPerChunk) {
+            return this.fetchRoute(waypoints, profile, options);
+        }
+        return this.fetchChunked(waypoints, profile, options);
+    }
+    profileFromOptions(options) {
+        switch (options?.profile) {
+            case 'cycling': return 'cycling-regular';
+            case 'walking': return 'foot-walking';
+            default: return this.config.profile;
+        }
+    }
+    async fetchRoute(waypoints, profile, options) {
+        const body = JSON.stringify({
+            coordinates: waypoints, // ORS uses [lng, lat] natively
+            instructions: options?.steps !== false,
+            language: options?.language ?? 'en',
+        });
+        const res = await fetch(`${this.config.baseUrl}/${profile}/geojson`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': this.config.apiKey,
+            },
+            body,
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`[ORS] HTTP ${res.status}: ${errText}`);
+        }
+        const data = await res.json();
+        const feature = data.features?.[0];
+        if (!feature)
+            throw new Error('[ORS] No route returned');
+        const summary = feature.properties?.summary ?? {};
+        const segments = feature.properties?.segments ?? [];
+        const legs = segments.map((seg) => ({
+            distance: seg.distance ?? 0,
+            duration: seg.duration ?? 0,
+            steps: (seg.steps ?? []).map((step) => ({
+                distance: step.distance ?? 0,
+                duration: step.duration ?? 0,
+                geometry: [],
+                maneuver: {
+                    type: step.type?.toString() ?? 'unknown',
+                    modifier: undefined,
+                    location: waypoints[0],
+                    bearingBefore: 0,
+                    bearingAfter: 0,
+                    instruction: step.instruction,
+                },
+                name: step.name,
+            })),
+        }));
+        return {
+            geometry: (feature.geometry?.coordinates ?? []),
+            distance: summary.distance ?? 0,
+            duration: summary.duration ?? 0,
+            legs,
+            raw: data,
+        };
+    }
+    async fetchChunked(waypoints, profile, options) {
+        const size = this.config.maxWaypointsPerChunk;
+        const chunks = [];
+        for (let i = 0; i < waypoints.length; i += size - 1) {
+            const chunk = waypoints.slice(i, i + size);
+            if (chunk.length < 2)
+                break;
+            chunks.push(chunk);
+            if (i + size >= waypoints.length)
+                break;
+        }
+        const results = await Promise.all(chunks.map(c => this.fetchRoute(c, profile, options)));
+        const geometry = [];
+        let distance = 0;
+        let duration = 0;
+        const legs = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            geometry.push(...(i === 0 ? r.geometry : r.geometry.slice(1)));
+            distance += r.distance;
+            duration += r.duration;
+            legs.push(...r.legs);
+        }
+        return { geometry, distance, duration, legs, raw: results.map(r => r.raw) };
+    }
+}