@ingissa/navcore-core 1.0.0

package/dist/core.d.mts

@@ -0,0 +1,488 @@
+import { C as Coordinate, g as NavCoreState } from './NavCore-Bjl5fTea.mjs';
+export { F as FEATURES, a as FeatureKey, L as LicenseManager, b as LicensePayload, c as LicenseStatus, o as destinationPoint, p as geoGetBearing, q as haversineDistance } from './NavCore-Bjl5fTea.mjs';
+
+/**
+ * Bearing and angular math utilities.
+ */
+
+/** Normalise an angle to (−180, 180] */
+declare function normalizeAngle(angle: number): number;
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+declare function getBearingBetweenPoints(start: Coordinate, end: Coordinate): number;
+/** Linear interpolation between two coordinates */
+declare function interpolatePoint(a: Coordinate, b: Coordinate, t: number): Coordinate;
+
+/**
+ * Vector projection utilities for coordinate snapping.
+ */
+
+/** Project point p onto line segment [a, b]. Returns the projected coordinate. */
+declare function projectPointOnSegment(p: Coordinate, a: Coordinate, b: Coordinate): Coordinate;
+
+/**
+ * Pre-calculated cumulative distance caches.
+ */
+
+/** Forward cumulative distances: result[i] = metres from route[0] to route[i]. O(n) build. */
+declare function buildForwardCumulativeDistances(route: Coordinate[]): Float64Array;
+/** Reverse cumulative distances: result[i] = metres from vertex i to the end. O(1) reads. */
+declare function buildReverseCumulativeDistances(route: Coordinate[]): Float64Array;
+
+/**
+ * Module 1: KalmanFilter2D
+ * GPS noise reduction using a 2D Kalman filter.
+ * ZERO dependencies — pure math.
+ */
+interface Kalman2DState {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    P: number;
+}
+/**
+ * Perform a single Kalman update step.
+ *
+ * @param state   Current state (mutated in place for perf)
+ * @param measX   Measured longitude
+ * @param measY   Measured latitude
+ * @param accuracy GPS accuracy in metres (used to scale R)
+ * @param dt      Time delta in seconds
+ * @param Q       Process noise (default 0.00001)
+ * @param rBase   Measurement noise base (default 0.00005)
+ * @returns Updated state
+ */
+declare function kalmanUpdate2D(state: Kalman2DState, measX: number, measY: number, accuracy: number, dt: number, Q?: number, rBase?: number): Kalman2DState;
+/**
+ * KalmanFilter2D class wrapper for stateful usage.
+ */
+declare class KalmanFilter2D {
+    private state;
+    private readonly Q;
+    private readonly rBase;
+    private lastTimestamp;
+    constructor(Q?: number, rBase?: number);
+    /** Initialize with a known position */
+    init(lng: number, lat: number, timestamp: number): void;
+    /** Process a GPS measurement, returns filtered [lng, lat] */
+    update(lng: number, lat: number, accuracy: number, timestamp: number): [number, number];
+    /** Get current filtered position */
+    getPosition(): [number, number];
+    /** Get the internal state for inspection/serialization */
+    getState(): Kalman2DState;
+    /** Reset the filter */
+    reset(): void;
+}
+
+/**
+ * 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.
+ */
+
+interface SnapResult {
+    idx: number;
+    dist: number;
+    proj: Coordinate;
+}
+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;
+}
+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;
+}
+
+/**
+ * Module 10: CustomRouteBuilder
+ * Build custom routes with unlimited waypoints, chunking, and GPX/GeoJSON.
+ */
+
+interface WaypointOptions {
+    silent?: boolean;
+    name?: string;
+}
+interface BuildOptions {
+    connectionMode?: 'ROUTED' | 'STRAIGHT';
+    chunkStrategy?: 'OVERLAP_1' | 'OVERLAP_2';
+    maxWaypointsPerChunk?: number;
+}
+interface CustomWaypoint {
+    id: string;
+    coord: Coordinate;
+    options?: WaypointOptions;
+}
+/**
+ * CustomRouteBuilder — builds exam routes from waypoints.
+ *
+ * Pass a DirectionsProvider to `build()` for routed connections.
+ * Without a provider, `build()` returns straight-line geometry.
+ */
+declare class CustomRouteBuilder {
+    private waypoints;
+    /** Add a waypoint at the end. Returns the generated ID. */
+    addWaypoint(coord: Coordinate, options?: WaypointOptions): string;
+    /** Insert a waypoint after an existing one. Returns the new ID. */
+    insertWaypoint(coord: Coordinate, afterId: string): string;
+    /** Remove a waypoint by ID */
+    removeWaypoint(id: string): void;
+    /** Move a waypoint to a new coordinate */
+    moveWaypoint(id: string, newCoord: Coordinate): void;
+    /** Get all current waypoints */
+    getWaypoints(): ReadonlyArray<CustomWaypoint>;
+    /** Get the number of waypoints */
+    get size(): number;
+    /**
+     * 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' | 'OVERLAP_2', maxPerChunk?: number): Coordinate[][];
+    /**
+     * Build straight-line geometry (no provider needed).
+     * For routed geometry, pass chunks to a DirectionsProvider externally.
+     */
+    buildStraightLine(): {
+        geometry: Coordinate[];
+        waypoints: CustomWaypoint[];
+    };
+    /** Import waypoints from a GPX string */
+    fromGPX(gpx: string): void;
+    /** Export the current waypoints as a GPX string */
+    toGPX(): string;
+    /** Import waypoints from GeoJSON */
+    fromGeoJSON(geojson: {
+        type: string;
+        features?: Array<{
+            geometry: {
+                type: string;
+                coordinates: unknown;
+            };
+        }>;
+    }): void;
+    /** Export the current route as GeoJSON FeatureCollection */
+    toGeoJSON(): {
+        type: 'FeatureCollection';
+        features: Array<{
+            type: 'Feature';
+            geometry: {
+                type: string;
+                coordinates: Coordinate | Coordinate[];
+            };
+            properties: Record<string, unknown>;
+        }>;
+    };
+    /** Clear all waypoints */
+    clear(): void;
+}
+
+/**
+ * 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.
+ */
+
+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;
+}
+interface DirectionsManeuver {
+    type: string;
+    modifier?: string;
+    location: Coordinate;
+    bearingBefore: number;
+    bearingAfter: number;
+    instruction?: string;
+}
+interface DirectionsStep {
+    distance: number;
+    duration: number;
+    geometry: Coordinate[];
+    maneuver: DirectionsManeuver;
+    name?: string;
+}
+interface DirectionsLeg {
+    distance: number;
+    duration: number;
+    steps?: DirectionsStep[];
+}
+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);
+ * ```
+ */
+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>;
+}
+
+/**
+ * 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/
+ */
+
+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;
+}
+declare class OSRMDirectionsProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: OSRMConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private fetchRoute;
+    private fetchChunked;
+}
+
+/**
+ * ValhallaDirectionsProvider
+ *
+ * Self-hosted Valhalla routing engine adapter.
+ * Supports the `/route` and `/optimized_route` endpoints.
+ * Zero API key for self-hosted. Uses Mapbox-hosted Valhalla with a token.
+ *
+ * @see https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/
+ */
+
+type ValhallaCostingModel = 'auto' | 'bicycle' | 'pedestrian' | 'bus' | 'motor_scooter';
+interface ValhallaConfig {
+    /** Base URL of your Valhalla server or hosted instance */
+    baseUrl: string;
+    /** Routing costing model (default: 'auto') */
+    costing?: ValhallaCostingModel;
+    /** Optional API key (required for hosted Valhalla services) */
+    apiKey?: string;
+    /** Max waypoints per chunk (default: 50) */
+    maxWaypointsPerChunk?: number;
+}
+declare class ValhallaDirectionsProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: ValhallaConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private profileToCosting;
+    private fetchRoute;
+    /** Decode Valhalla's encoded polyline6 format */
+    private decodePolyline;
+    private fetchChunked;
+}
+
+/**
+ * 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
+ */
+
+type ORSProfile = 'driving-car' | 'driving-hgv' | 'cycling-regular' | 'cycling-road' | 'cycling-mountain' | 'foot-walking' | 'foot-hiking' | 'wheelchair';
+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;
+}
+declare class OpenRouteServiceProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: ORSConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private profileFromOptions;
+    private fetchRoute;
+    private fetchChunked;
+}
+
+/**
+ * MapRendererAdapter — Interface for map renderer integrations.
+ *
+ * Implement this interface to connect NavCore's navigation state
+ * to any map library (MapLibre, Leaflet, Google Maps, etc.).
+ *
+ * NavCore itself never depends on a renderer — adapters live
+ * in separate packages and are optionally wired up by the consumer.
+ *
+ * @example
+ * ```typescript
+ * import { MapLibreAdapter } from '@ingissa/navcore-maplibre';
+ *
+ * const adapter = new MapLibreAdapter(mapInstance);
+ * engine.on('stateUpdate', (state) => adapter.updateVehicle(state.snappedCoord, state.bearing, state));
+ * adapter.drawRoute(routeGeometry);
+ * ```
+ */
+
+interface RouteStyle {
+    /** Line color as CSS color string. Default: '#7c3aed' */
+    color?: string;
+    /** Line width in pixels. Default: 4 */
+    width?: number;
+    /** Line opacity 0–1. Default: 0.9 */
+    opacity?: number;
+    /** Dash array pattern (pixels). Undefined = solid. */
+    dashArray?: number[];
+}
+interface VehicleStyle {
+    /** Icon size multiplier. Default: 1.0 */
+    scale?: number;
+    /** Custom icon URL (if undefined, adapter uses its default icon) */
+    iconUrl?: string;
+}
+interface CameraOptions {
+    /** Zoom level (map-library specific). Default: adapter decides. */
+    zoom?: number;
+    /** Pitch/tilt in degrees. Default: 0. */
+    pitch?: number;
+    /** Whether to animate the camera transition. Default: true. */
+    animate?: boolean;
+    /** Animation duration in ms. Default: 300. */
+    animationDurationMs?: number;
+}
+interface MapRendererAdapter {
+    /**
+     * Update the vehicle marker position and rotation.
+     * Called on every NavCore state update.
+     */
+    updateVehicle(coord: Coordinate, bearing: number, state: NavCoreState, style?: VehicleStyle): void;
+    /**
+     * Draw or update the route polyline on the map.
+     * Replaces any previously drawn route.
+     */
+    drawRoute(coords: Coordinate[], style?: RouteStyle): void;
+    /**
+     * Remove the route polyline and vehicle marker from the map.
+     */
+    clearRoute(): void;
+    /**
+     * Pan (and optionally rotate/tilt) the camera to follow the vehicle.
+     */
+    panCamera(coord: Coordinate, bearing: number, options?: CameraOptions): void;
+    /**
+     * Clean up all map layers, markers, and event listeners created by this adapter.
+     * Call when navigation ends or the component unmounts.
+     */
+    destroy(): void;
+}
+
+/**
+ * Engine constants — centralized tuning parameters.
+ * Extracted from packages/nav-sdk/src/shared/constants.ts
+ */
+declare const BASE_CORRIDOR_METERS = 25;
+declare const MAX_CORRIDOR_METERS = 60;
+declare const SPEED_CORRIDOR_FACTOR = 1.2;
+declare const GPS_ACCURACY_FACTOR = 0.5;
+declare const MAX_SNAP_DISTANCE = 80;
+declare const BEARING_MISMATCH_THRESHOLD = 90;
+declare const BEARING_MISMATCH_PENALTY = 500;
+declare const INERTIA_PENALTY = 200;
+declare const INERTIA_SEGMENT_DIST = 5;
+declare const SNAP_WINDOW_SIZE = 25;
+declare const BEARING_SMOOTHING_ALPHA = 0.3;
+declare const BEARING_MIN_SPEED_MPS = 1.5;
+declare const BEARING_ALIGNMENT_THRESHOLD = 55;
+declare const DR_MAX_AGE_MS = 5000;
+declare const OFF_ROUTE_CONFIRM_MS = 2000;
+declare const REJOIN_CONFIRM_MS = 1500;
+declare const REJOIN_COOLDOWN_MS = 12000;
+declare const STARTUP_GRACE_MS = 3000;
+declare const DETOUR_COMMIT_MS = 4000;
+declare const GPS_STALE_MS = 3000;
+declare const GPS_AGE_CAP_SECONDS = 10;
+declare const MANEUVER_TRIGGER_DIST = 25;
+declare const BETA_CORRECTION = 0.15;
+declare const LOOK_AHEAD_SECONDS = 3;
+declare const MIN_LOOK_AHEAD_METERS = 20;
+declare const MAX_LOOK_AHEAD_METERS = 100;
+declare const ARRIVAL_THRESHOLD_METERS = 30;
+
+declare const constants_ARRIVAL_THRESHOLD_METERS: typeof ARRIVAL_THRESHOLD_METERS;
+declare const constants_BASE_CORRIDOR_METERS: typeof BASE_CORRIDOR_METERS;
+declare const constants_BEARING_ALIGNMENT_THRESHOLD: typeof BEARING_ALIGNMENT_THRESHOLD;
+declare const constants_BEARING_MIN_SPEED_MPS: typeof BEARING_MIN_SPEED_MPS;
+declare const constants_BEARING_MISMATCH_PENALTY: typeof BEARING_MISMATCH_PENALTY;
+declare const constants_BEARING_MISMATCH_THRESHOLD: typeof BEARING_MISMATCH_THRESHOLD;
+declare const constants_BEARING_SMOOTHING_ALPHA: typeof BEARING_SMOOTHING_ALPHA;
+declare const constants_BETA_CORRECTION: typeof BETA_CORRECTION;
+declare const constants_DETOUR_COMMIT_MS: typeof DETOUR_COMMIT_MS;
+declare const constants_DR_MAX_AGE_MS: typeof DR_MAX_AGE_MS;
+declare const constants_GPS_ACCURACY_FACTOR: typeof GPS_ACCURACY_FACTOR;
+declare const constants_GPS_AGE_CAP_SECONDS: typeof GPS_AGE_CAP_SECONDS;
+declare const constants_GPS_STALE_MS: typeof GPS_STALE_MS;
+declare const constants_INERTIA_PENALTY: typeof INERTIA_PENALTY;
+declare const constants_INERTIA_SEGMENT_DIST: typeof INERTIA_SEGMENT_DIST;
+declare const constants_LOOK_AHEAD_SECONDS: typeof LOOK_AHEAD_SECONDS;
+declare const constants_MANEUVER_TRIGGER_DIST: typeof MANEUVER_TRIGGER_DIST;
+declare const constants_MAX_CORRIDOR_METERS: typeof MAX_CORRIDOR_METERS;
+declare const constants_MAX_LOOK_AHEAD_METERS: typeof MAX_LOOK_AHEAD_METERS;
+declare const constants_MAX_SNAP_DISTANCE: typeof MAX_SNAP_DISTANCE;
+declare const constants_MIN_LOOK_AHEAD_METERS: typeof MIN_LOOK_AHEAD_METERS;
+declare const constants_OFF_ROUTE_CONFIRM_MS: typeof OFF_ROUTE_CONFIRM_MS;
+declare const constants_REJOIN_CONFIRM_MS: typeof REJOIN_CONFIRM_MS;
+declare const constants_REJOIN_COOLDOWN_MS: typeof REJOIN_COOLDOWN_MS;
+declare const constants_SNAP_WINDOW_SIZE: typeof SNAP_WINDOW_SIZE;
+declare const constants_SPEED_CORRIDOR_FACTOR: typeof SPEED_CORRIDOR_FACTOR;
+declare const constants_STARTUP_GRACE_MS: typeof STARTUP_GRACE_MS;
+declare namespace constants {
+  export { constants_ARRIVAL_THRESHOLD_METERS as ARRIVAL_THRESHOLD_METERS, constants_BASE_CORRIDOR_METERS as BASE_CORRIDOR_METERS, constants_BEARING_ALIGNMENT_THRESHOLD as BEARING_ALIGNMENT_THRESHOLD, constants_BEARING_MIN_SPEED_MPS as BEARING_MIN_SPEED_MPS, constants_BEARING_MISMATCH_PENALTY as BEARING_MISMATCH_PENALTY, constants_BEARING_MISMATCH_THRESHOLD as BEARING_MISMATCH_THRESHOLD, constants_BEARING_SMOOTHING_ALPHA as BEARING_SMOOTHING_ALPHA, constants_BETA_CORRECTION as BETA_CORRECTION, constants_DETOUR_COMMIT_MS as DETOUR_COMMIT_MS, constants_DR_MAX_AGE_MS as DR_MAX_AGE_MS, constants_GPS_ACCURACY_FACTOR as GPS_ACCURACY_FACTOR, constants_GPS_AGE_CAP_SECONDS as GPS_AGE_CAP_SECONDS, constants_GPS_STALE_MS as GPS_STALE_MS, constants_INERTIA_PENALTY as INERTIA_PENALTY, constants_INERTIA_SEGMENT_DIST as INERTIA_SEGMENT_DIST, constants_LOOK_AHEAD_SECONDS as LOOK_AHEAD_SECONDS, constants_MANEUVER_TRIGGER_DIST as MANEUVER_TRIGGER_DIST, constants_MAX_CORRIDOR_METERS as MAX_CORRIDOR_METERS, constants_MAX_LOOK_AHEAD_METERS as MAX_LOOK_AHEAD_METERS, constants_MAX_SNAP_DISTANCE as MAX_SNAP_DISTANCE, constants_MIN_LOOK_AHEAD_METERS as MIN_LOOK_AHEAD_METERS, constants_OFF_ROUTE_CONFIRM_MS as OFF_ROUTE_CONFIRM_MS, constants_REJOIN_CONFIRM_MS as REJOIN_CONFIRM_MS, constants_REJOIN_COOLDOWN_MS as REJOIN_COOLDOWN_MS, constants_SNAP_WINDOW_SIZE as SNAP_WINDOW_SIZE, constants_SPEED_CORRIDOR_FACTOR as SPEED_CORRIDOR_FACTOR, constants_STARTUP_GRACE_MS as STARTUP_GRACE_MS };
+}
+
+export { type BuildOptions, type CameraOptions, constants as Constants, Coordinate, CustomRouteBuilder, type CustomWaypoint, type DirectionsLeg, type DirectionsManeuver, type DirectionsOptions, type DirectionsProvider, type DirectionsResult, type DirectionsStep, type Kalman2DState, KalmanFilter2D, type MapRendererAdapter, type ORSConfig, type ORSProfile, type OSRMConfig, OSRMDirectionsProvider, OpenRouteServiceProvider, RouteSnapper, type RouteStyle, type SnapResult, type SnapperOptions, type ValhallaConfig, type ValhallaCostingModel, ValhallaDirectionsProvider, type VehicleStyle, type WaypointOptions, buildForwardCumulativeDistances, buildReverseCumulativeDistances, getBearingBetweenPoints, interpolatePoint, kalmanUpdate2D, normalizeAngle, projectPointOnSegment };