@ingissa/navcore-core 1.0.0

package/dist/NavCore-Bjl5fTea.d.mts

@@ -0,0 +1,377 @@
+/**
+ * Haversine geographic math utilities.
+ * ZERO dependencies — pure math.
+ */
+/** [longitude, latitude] coordinate */
+type Coordinate = [number, number];
+/** Haversine distance between two points in metres */
+declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/** Forward Haversine: compute destination given start, bearing (°), distance (m) */
+declare function destinationPoint(lat: number, lon: number, brng: number, dist: number): Coordinate;
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+declare function getBearingBetweenPoints(c1: Coordinate, c2: Coordinate): number;
+
+/**
+ * Module 7: InstructionResolver
+ * Resolves the next upcoming instruction and determines if it should be triggered.
+ */
+
+/** Navigation instruction (mirrors @navcore/types NavInstruction) */
+interface NavInstruction {
+    location: Coordinate;
+    geometryIndex: number;
+    text?: string;
+    instruction?: string;
+    cumulativeOffset?: number;
+    bearingBefore?: number;
+    bearingAfter?: number;
+}
+interface InstructionResult {
+    nextIdx: number;
+    instruction: NavInstruction | null;
+    wasTriggered: boolean;
+}
+/**
+ * Resolve which instruction is next and whether it should trigger now.
+ */
+declare function resolveNextInstruction(currentGeometryIdx: number, instructions: NavInstruction[], currentInstrIdx: number, route: Coordinate[], currentCoord: Coordinate, vehicleBearing: number | null, vehicleDistance: number, speed?: number): InstructionResult;
+
+/**
+ * Module 9a: NavigationFSM
+ * Navigation lifecycle state machine. Pure deterministic transitions.
+ */
+type NavLifecycleState = 'IDLE' | 'OVERVIEW' | 'APPROACHING_ROUTE' | 'ON_ROUTE';
+type LifecycleEvent = {
+    type: 'ROUTE_LOADED';
+} | {
+    type: 'USER_START_NAVIGATION';
+} | {
+    type: 'ROUTE_JOINED';
+    data: {
+        index: number;
+    };
+} | {
+    type: 'NAVIGATION_FINISHED';
+} | {
+    type: 'CANCEL_NAVIGATION';
+} | {
+    type: 'RESET';
+};
+interface LifecycleContext {
+    resumeIndex: number | null;
+}
+interface LifecycleOutput {
+    state: NavLifecycleState;
+    context: LifecycleContext;
+}
+/**
+ * Pure lifecycle FSM — no React, no side effects.
+ */
+declare class NavigationFSM {
+    private _state;
+    private _context;
+    get state(): NavLifecycleState;
+    get context(): LifecycleContext;
+    /** Dispatch an event and return the new output */
+    dispatch(event: LifecycleEvent): LifecycleOutput;
+    /** Reset to initial state */
+    reset(): void;
+}
+
+/**
+ * Module 9b: OffRouteFSM
+ * Deviation → Reroute → Rejoin state machine. Pure deterministic transitions.
+ * Extracted from useOffRouteSystem / NavigationStateManager (stripped of React).
+ */
+
+type OffRouteState = 'ON_ROUTE' | 'DEVIATING' | 'OFF_ROUTE' | 'REROUTING' | 'REJOINING' | 'REJOINED' | 'FAILED';
+interface TempRoute {
+    geometry: Coordinate[];
+    distance: number;
+    duration: number;
+}
+interface RejoinTarget {
+    coordinates: Coordinate;
+    index: number;
+}
+interface OffRouteContext {
+    deviationSegmentIdx: number | null;
+    deviationStartMs: number | null;
+    tempRoute: TempRoute | null;
+    rejoinTarget: RejoinTarget | null;
+    lastRerouteMs: number | null;
+    rejoinedAtMs: number | null;
+    rejoinDwellFrames: number;
+    failureReason: string | null;
+}
+type OffRouteEvent = {
+    type: 'DEVIATION_SUSPECTED';
+    deviationSegmentIdx: number;
+} | {
+    type: 'DEVIATION_CONFIRMED';
+    deviationSegmentIdx: number;
+} | {
+    type: 'REROUTE_STARTED';
+} | {
+    type: 'REROUTE_SUCCESS';
+    tempRoute: TempRoute;
+    rejoinTarget: RejoinTarget;
+} | {
+    type: 'REROUTE_FAILED';
+    reason: string;
+} | {
+    type: 'REJOIN_DETECTED';
+} | {
+    type: 'REJOIN_CONFIRMED';
+} | {
+    type: 'RESUME';
+} | {
+    type: 'RESET';
+};
+interface OffRouteOutput {
+    state: OffRouteState;
+    context: OffRouteContext;
+}
+/**
+ * Pure off-route FSM — no React, no side effects.
+ */
+declare class OffRouteFSM {
+    private _state;
+    private _context;
+    get state(): OffRouteState;
+    get context(): OffRouteContext;
+    /** Dispatch an event and return the new output */
+    dispatch(event: OffRouteEvent, nowMs?: number): OffRouteOutput;
+    /** Full reset */
+    reset(): void;
+    /** Check if deviation confirmation time has elapsed */
+    isDeviationConfirmed(nowMs?: number): boolean;
+}
+
+/**
+ * Feature flag constants for SDK consumers.
+ *
+ * CORE features: available to all users (MIT license).
+ * PRO  features: require a valid commercial license key.
+ */
+declare const FEATURES: {
+    /**
+     * Basic Kalman filter GPS smoothing.
+     * Reduces GPS jitter for stable route snapping.
+     */
+    readonly GPS_SMOOTHING: "gps_smoothing";
+    /**
+     * Basic route snapping (nearest-point projection).
+     * Snaps GPS position to the closest route segment.
+     */
+    readonly BASIC_SNAPPING: "basic_snapping";
+    /**
+     * Advanced route snapping with bearing penalty + inertia.
+     * Prevents incorrect snaps on parallel roads and U-turns.
+     */
+    readonly ADVANCED_SNAPPING: "advanced_snapping";
+    /**
+     * Dead reckoning: continues navigation during GPS signal loss.
+     * Predicts position based on last known speed and bearing.
+     */
+    readonly DEAD_RECKONING: "dead_reckoning";
+    /**
+     * Smooth route offset predictor for jitter-free map rendering.
+     * Advances render position at frame rate between GPS fixes.
+     */
+    readonly ROUTE_OFFSET: "route_offset";
+    /**
+     * Progress anti-regression: prevents route index from jumping backward.
+     * Essential for circuit routes and motorway slip roads.
+     */
+    readonly PROGRESS_TRACKING: "progress_tracking";
+    /**
+     * Advanced bearing engine with look-ahead and speed-adaptive alpha.
+     * Produces stable heading for smooth map camera rotation.
+     */
+    readonly ADVANCED_BEARING: "advanced_bearing";
+    /**
+     * Compound deviation detection: combines distance, bearing, and speed signals.
+     * Eliminates false off-route triggers in tunnels and urban canyons.
+     */
+    readonly COMPOUND_DEVIATION: "compound_deviation";
+    /**
+     * Parallel road disambiguation + U-turn snap protection.
+     * Prevents snapping to the wrong carriageway when bearing mismatches route direction.
+     */
+    readonly PARALLEL_ROAD_RESOLUTION: "parallel_road_resolution";
+    /**
+     * U-turn protection: bearing penalty applied when vehicle heading opposes
+     * route segment direction by more than the configured threshold (default 60°).
+     */
+    readonly U_TURN_PROTECTION: "u_turn_protection";
+    /**
+     * Timed voice instruction cues with deduplication and priority levels.
+     */
+    readonly VOICE_TRIGGERS: "voice_triggers";
+    /**
+     * Local ETA computation using rolling speed average — zero API calls.
+     */
+    readonly ETA: "eta";
+    /**
+     * Circular and polygon geofencing with enter/exit/dwell events.
+     */
+    readonly GEOFENCING: "geofencing";
+    /**
+     * AI-powered navigation stability: oscillation suppression + turn anticipation.
+     */
+    readonly NAV_AI: "nav_ai";
+};
+type FeatureKey = typeof FEATURES[keyof typeof FEATURES];
+
+/**
+ * LicenseManager — Handles offline asymmetric license verification
+ * using WebCrypto + granular feature licensing.
+ *
+ * Matching nav-sdk/src/shared/LicenseManager.ts contract exactly.
+ */
+
+type LicenseStatus = 'VALID' | 'INVALID' | 'EXPIRED' | 'MISSING';
+interface LicensePayload {
+    /** Legacy tier — 'pro' grants all features ('*') */
+    t?: 'core' | 'pro';
+    /** Expiration timestamp (ms since epoch) */
+    exp: number;
+    /** Bundle ID / domain */
+    bid: string;
+    /** Granular feature flags */
+    f?: string[];
+}
+declare class LicenseManager {
+    private status;
+    private payload;
+    private enabledFeatures;
+    private warnedFeatures;
+    private isDev;
+    private static PUBLIC_KEY_SPKI;
+    constructor(licenseKey?: string, isDev?: boolean);
+    validate(key: string): Promise<LicenseStatus>;
+    private extractFeatures;
+    hasFeature(feature: FeatureKey): boolean;
+    /** Warn once per feature when a consumer tries to use a gated feature. */
+    warnOnce(feature: FeatureKey): void;
+    /** Returns true if the license grants the full Pro tier (all features). */
+    isProEnabled(): boolean;
+    isAIEnabled(): boolean;
+    getStatus(): LicenseStatus;
+    getPayload(): LicensePayload | null;
+    getEnabledFeatures(): string[];
+    private verifySignature;
+}
+
+/**
+ * NavCore — Main Orchestrator
+ *
+ * Fuses all extracted modules into a single engine class.
+ * ZERO runtime dependencies. Framework-agnostic.
+ *
+ * Usage:
+ *   const engine = new NavCore({ licenseKey: '...' });
+ *   engine.setRoute(routeCoords, instructions);
+ *   engine.update(gpsUpdate);
+ *   const state = engine.getState();
+ */
+
+interface NavGpsUpdate {
+    coord: Coordinate;
+    accuracy: number | null;
+    bearing: number | null;
+    speed: number;
+    timestamp: number;
+}
+interface NavCoreOptions {
+    licenseKey?: string;
+    isDev?: boolean;
+    isCircuit?: boolean;
+    kalmanQ?: number;
+    kalmanRBase?: number;
+    baseCorridorMeters?: number;
+    maxCorridorMeters?: number;
+    arrivalThresholdMeters?: number;
+    bearingSmoothingAlpha?: number;
+}
+interface NavCoreState {
+    snappedCoord: Coordinate | null;
+    rawGpsCoord: Coordinate | null;
+    bearing: number;
+    rawGpsBearing: number | null;
+    routeIndex: number;
+    distanceToRoute: number;
+    corridor: number;
+    isOffRoute: boolean;
+    progressIndex: number;
+    hasArrived: boolean;
+    offRouteState: string;
+    lifecycleState: string;
+    distanceToDestination: number | null;
+    distanceToNextInstruction: number | null;
+    nextInstructionIndex: number | null;
+    currentSpeed: number;
+    isGpsStale: boolean;
+    gpsAgeMs: number;
+    licenseStatus: string;
+}
+type EventHandler = (...args: unknown[]) => void;
+declare class NavCore {
+    private kalman;
+    private snapper;
+    private deadReckoning;
+    private deviationDetector;
+    private lifecycleFSM;
+    private offRouteFSM;
+    private license;
+    private route;
+    private instructions;
+    private forwardCum;
+    private reverseCum;
+    private snappedCoord;
+    private rawGpsCoord;
+    private bearing;
+    private rawGpsBearing;
+    private routeIndex;
+    private maxProgressIdx;
+    private prevSegment;
+    private distanceToRoute;
+    private corridor;
+    private prevDistToNext;
+    private currentSpeed;
+    private lastGpsTimestamp;
+    private instrIdx;
+    private linearOffset;
+    private hasArrived;
+    private readonly options;
+    private listeners;
+    constructor(options?: NavCoreOptions);
+    /**
+     * Returns true if the feature is unlocked (dev mode OR valid license).
+     * Emits a one-time console warning when a Pro feature is blocked.
+     */
+    private has;
+    /** Load route geometry and instructions */
+    setRoute(route: Coordinate[], instructions?: NavInstruction[]): void;
+    /** Start navigation */
+    startNavigation(): void;
+    /** Process a GPS update — the main engine tick */
+    update(gps: NavGpsUpdate): NavCoreState;
+    /** Time-advance tick for dead reckoning (call at RAF rate) */
+    tick(nowMs: number): NavCoreState;
+    /** Get the current engine state snapshot */
+    getState(): NavCoreState;
+    /** Destroy the engine */
+    destroy(): void;
+    on(event: string, handler: EventHandler): void;
+    off(event: string, handler: EventHandler): void;
+    private emit;
+    getLicenseManager(): LicenseManager;
+    getRoute(): ReadonlyArray<Coordinate>;
+    getInstructions(): ReadonlyArray<NavInstruction>;
+    getOffRouteFSM(): OffRouteFSM;
+    getLifecycleFSM(): NavigationFSM;
+}
+
+export { type Coordinate as C, FEATURES as F, LicenseManager as L, NavCore as N, type OffRouteContext as O, type RejoinTarget as R, type TempRoute as T, type FeatureKey as a, type LicensePayload as b, type LicenseStatus as c, type LifecycleContext as d, type LifecycleEvent as e, type NavCoreOptions as f, type NavCoreState as g, type NavGpsUpdate as h, type NavInstruction as i, type NavLifecycleState as j, NavigationFSM as k, type OffRouteEvent as l, OffRouteFSM as m, type OffRouteState as n, destinationPoint as o, getBearingBetweenPoints as p, haversineDistance as q, resolveNextInstruction as r };