@ingissa/navcore-core 1.0.4 → 1.0.5

package/README.md

@@ -1,136 +1,279 @@
-# @ingissa/navcore-core
-
-Framework-agnostic TypeScript navigation engine for browser, React Native,
-Node.js, and CI environments.
-
-[![npm version](https://img.shields.io/npm/v/@ingissa/navcore-core)](https://www.npmjs.com/package/@ingissa/navcore-core)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
-[![Pricing](https://img.shields.io/badge/licence_key-pricing-green)](https://navcore-web.vercel.app/pricing)
-
-## Install
-
-```bash
-npm install @ingissa/navcore-core
-```
-
-## Quick Start
-
-```typescript
-import { NavCore, OSRMDirectionsProvider } from '@ingissa/navcore-core';
-
-const provider = new OSRMDirectionsProvider({
-  baseUrl: 'http://router.project-osrm.org',
-});
-
-const route = await provider.getRoute([
-  [2.3522, 48.8566],
-  [2.3400, 48.8700],
-]);
-
-const engine = new NavCore({
-  licenseKey: process.env.NAVCORE_LICENSE_KEY,
-});
-
-engine.setRoute(route.geometry);
-engine.startNavigation();
-
-const state = engine.update({
-  coord: [2.3522, 48.8566],
-  accuracy: 8,
-  bearing: 90,
-  speed: 9,
-  timestamp: Date.now(),
-});
-
-console.log(state.snappedCoord, state.distanceToDestination);
-```
-
-## What Is Included
-
-Core runtime behavior works without a licence key:
-
-| Area | APIs |
-|---|---|
-| Geo utilities | `haversineDistance`, `getBearingBetweenPoints`, cumulative distance helpers |
-| GPS smoothing | `KalmanFilter2D` |
-| Route snapping | `RouteSnapper` |
-| Route building | `CustomRouteBuilder` |
-| Directions | `OSRMDirectionsProvider`, `ValhallaDirectionsProvider`, `OpenRouteServiceProvider` |
-| Renderer contract | `MapRendererAdapter` types |
-| Licence status | `LicenseManager` |
-
-Pro behavior unlocks with a signed licence key:
-
-| Area | APIs |
-|---|---|
-| Advanced route matching | `ParallelRoadResolver`, bearing and inertia scoring |
-| Deviation handling | `DeviationDetector`, `OffRouteFSM`, `NavigationFSM` |
-| Dead reckoning | `DeadReckoningEngine` |
-| Turn guidance | `InstructionEditor`, voice trigger helpers |
-| Driver UX | `ETAEngine`, `GeofencingEngine` |
-
-Get a licence key:
-
-https://navcore-web.vercel.app/pricing
-
-## Direction Providers
-
-```typescript
-import {
-  OSRMDirectionsProvider,
-  ValhallaDirectionsProvider,
-  OpenRouteServiceProvider,
-} from '@ingissa/navcore-core';
-```
-
-All providers implement:
-
-```typescript
-interface DirectionsProvider {
-  getRoute(
-    waypoints: Coordinate[],
-    options?: DirectionsOptions
-  ): Promise<DirectionsResult>;
-}
-```
-
-Provider options include:
-
-| Option | Purpose |
-|---|---|
-| `profile` | Driving, cycling, or walking route mode |
-| `steps` | Include maneuver data |
-| `language` | Instruction language when supported |
-| `fetchFn` | Custom fetch implementation for tests or runtimes |
-| `timeoutMs` | Abort slow requests |
-
-## Public Subpaths
-
-```typescript
-// Full engine and all public APIs
-import { NavCore } from '@ingissa/navcore-core';
-
-// Core-oriented subpath
-import { RouteSnapper } from '@ingissa/navcore-core/core';
-
-// Pro-oriented subpath
-import { DeadReckoningEngine } from '@ingissa/navcore-core/pro';
-```
-
-## Licence Model
-
-`@ingissa/navcore-core` is published publicly on npm and uses a commercial
-licence model.
-
-| Condition | Result |
-|---|---|
-| No licence key | Core behavior works with Core fallbacks. |
-| Valid licence key | Pro features unlock according to the signed key. |
-| Expired or invalid key | Pro features are blocked and status is reported. |
-| Development key | Accepted only in local development/test environments. |
-
-Pricing and licence keys:
-
-https://navcore-web.vercel.app/pricing
-
-Copyright Ingissa. All rights reserved.
+# @ingissa/navcore-core
+
+> **The navigation layer you own.** A framework-agnostic, zero-dependency navigation engine that runs everywhere — browsers, React Native, Node.js, and CI/CD.
+
+[![npm version](https://img.shields.io/npm/v/@ingissa/navcore-core)](https://www.npmjs.com/package/@ingissa/navcore-core)
+[![License](https://img.shields.io/badge/license-MIT%20%2F%20Commercial-purple)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+[![Zero deps](https://img.shields.io/badge/runtime_deps-0-brightgreen)](https://www.npmjs.com/package/@ingissa/navcore-core)
+
+---
+
+## Why NavCore?
+
+| Feature | NavCore | Mapbox Nav SDK | Google Maps |
+|---|---|---|---|
+| **Framework** | Any (pure TS) | React Native only | Platform-locked |
+| **Runtime deps** | 0 | 50+ | N/A |
+| **Map renderer** | BYO (adapter) | Mapbox GL only | Google Maps only |
+| **Directions** | BYO (adapter) | Mapbox API only | Google API only |
+| **Off-route detection** | Built-in FSM | Basic | Basic |
+| **U-turn protection** | ✅ Bearing penalty | ❌ | ❌ |
+| **Parallel road resolver** | ✅ Built-in | ❌ | ❌ |
+| **Dead reckoning** | ✅ Built-in | ❌ | ❌ |
+| **Geofencing** | ✅ Built-in | ❌ | Paid API |
+| **ETA** | ✅ Offline | API only | API only |
+| **Voice triggers** | ✅ Built-in | SDK only | ❌ |
+| **Headless testing** | ✅ Full pipeline | ❌ | ❌ |
+| **Custom routes** | ✅ GPX/GeoJSON/Builder | ❌ | ❌ |
+| **License** | Core MIT / Pro commercial | Commercial | Commercial |
+
+---
+
+## Tier Model
+
+NavCore uses a two-tier model controlled by a signed license key:
+
+| Tier | Import | License | Includes |
+|---|---|---|---|
+| **Core** | `@ingissa/navcore-core/core` | MIT — free forever | Geo utils, Kalman filter, route snapping, directions adapters, route builder |
+| **Pro** | `@ingissa/navcore-core/pro` | Commercial key required | Dead reckoning, advanced bearing, deviation detection, FSMs, voice, ETA, geofencing |
+| **Engine** | `@ingissa/navcore-core` | Gated internally at runtime | Full `NavCore` orchestrator (license key unlocks Pro features) |
+
+---
+
+## Installation
+
+```bash
+npm install @ingissa/navcore-core
+```
+
+---
+
+## Quick Start
+
+### Core tier (no license needed)
+
+```typescript
+import { NavCore } from '@ingissa/navcore-core';
+import { OSRMDirectionsProvider } from '@ingissa/navcore-core/core';
+
+// 1. Get a route from your self-hosted OSRM (free)
+const provider = new OSRMDirectionsProvider({ baseUrl: 'http://router.project-osrm.org' });
+const route = await provider.getRoute([[2.3522, 48.8566], [2.3400, 48.8700]]);
+
+// 2. Create engine (Core features work without a key)
+const engine = new NavCore();
+engine.setRoute(route.geometry);
+engine.startNavigation();
+
+// 3. Feed GPS updates
+engine.on('arrival', () => console.log('Arrived!'));
+
+navigator.geolocation.watchPosition(({ coords }) => {
+  const state = engine.update({
+    coord: [coords.longitude, coords.latitude],
+    accuracy: coords.accuracy,
+    bearing: coords.heading,
+    speed: coords.speed ?? 0,
+    timestamp: Date.now(),
+  });
+
+  console.log('Distance remaining:', state.distanceToDestination, 'm');
+});
+```
+
+### Pro tier (with license key)
+
+```typescript
+import { NavCore } from '@ingissa/navcore-core';
+
+// Pro features unlock automatically with a valid key
+const engine = new NavCore({ licenseKey: 'your-signed-license-key' });
+engine.setRoute(routeCoords, instructions);
+engine.startNavigation();
+
+engine.on('instruction', (instr) => speak(instr.text));  // voice cues (PRO)
+engine.on('deviation', ({ anchorIndex }) => recalculate(anchorIndex));
+engine.on('arrival', () => console.log('Arrived!'));
+```
+
+### Using subpath imports directly
+
+```typescript
+// Free MIT tier
+import { KalmanFilter2D } from '@ingissa/navcore-core/core';
+import { OSRMDirectionsProvider } from '@ingissa/navcore-core/core';
+import { CustomRouteBuilder } from '@ingissa/navcore-core/core';
+
+// Commercial Pro tier
+import { DeadReckoningEngine } from '@ingissa/navcore-core/pro';
+import { VoiceTriggerEngine } from '@ingissa/navcore-core/pro';
+import { ETAEngine } from '@ingissa/navcore-core/pro';
+import { GeofencingEngine } from '@ingissa/navcore-core/pro';
+```
+
+---
+
+## Directions Providers (built-in, no extra install)
+
+```typescript
+import {
+  OSRMDirectionsProvider,        // Self-hosted OSRM (recommended, free)
+  ValhallaDirectionsProvider,    // Self-hosted Valhalla (free)
+  OpenRouteServiceProvider,      // openrouteservice.org (free tier)
+} from '@ingissa/navcore-core/core';
+
+// OSRM
+const osrm = new OSRMDirectionsProvider({ baseUrl: 'http://router.project-osrm.org' });
+const route = await osrm.getRoute([[lng1, lat1], [lng2, lat2]]);
+
+// Valhalla
+const valhalla = new ValhallaDirectionsProvider({ baseUrl: 'https://valhalla1.openstreetmap.de' });
+const route = await valhalla.getRoute([[lng1, lat1], [lng2, lat2]], { costing: 'auto' });
+```
+
+---
+
+## Renderer Adapters (separate packages)
+
+```bash
+npm install @ingissa/navcore-maplibre      # Web + MapLibre GL
+npm install @ingissa/navcore-leaflet       # Web + Leaflet.js
+npm install @ingissa/navcore-google-maps   # Google Maps JS API
+npm install @ingissa/navcore-mapbox        # React Native + @rnmapbox/maps
+npm install @ingissa/navcore-react-native  # React Native bindings
+npm install @ingissa/navcore-headless      # Node.js / CI testing
+```
+
+> ⚠️ Renderer adapter packages require a commercial license. [Get yours at Not yet available]()
+
+---
+
+## Feature Reference
+
+### CORE — free, MIT
+
+| Feature | API |
+|---|---|
+| GPS smoothing | `KalmanFilter2D` |
+| Route snapping | `RouteSnapper` |
+| Haversine & bearing | `haversineDistance`, `getBearingBetweenPoints` |
+| Cumulative distances | `buildForwardCumulativeDistances` |
+| Route builder | `CustomRouteBuilder` |
+| Directions — OSRM | `OSRMDirectionsProvider` |
+| Directions — Valhalla | `ValhallaDirectionsProvider` |
+| Directions — ORS | `OpenRouteServiceProvider` |
+| Renderer interface | `MapRendererAdapter` |
+| License verification | `LicenseManager` |
+
+### PRO — commercial license required
+
+| Feature | API | FEATURES key |
+|---|---|---|
+| Advanced snapping (bearing + inertia) | `RouteSnapper` options | `ADVANCED_SNAPPING` |
+| Parallel road resolver | `ParallelRoadResolver` | `PARALLEL_ROAD_RESOLUTION` |
+| Dead reckoning | `DeadReckoningEngine` | `DEAD_RECKONING` |
+| Compound deviation detection | `DeviationDetector` | `COMPOUND_DEVIATION` |
+| Advanced bearing engine | `BearingEngine` | `ADVANCED_BEARING` |
+| Progress anti-regression | `ProgressTracker` | `PROGRESS_TRACKING` |
+| Route offset predictor | `RouteOffsetPredictor` | `ROUTE_OFFSET` |
+| Navigation lifecycle FSM | `NavigationFSM` | — |
+| Off-route FSM | `OffRouteFSM` | — |
+| Instruction editor | `InstructionEditor` | — |
+| Voice trigger engine | `VoiceTriggerEngine` | `VOICE_TRIGGERS` |
+| ETA engine (offline) | `ETAEngine` | `ETA` |
+| Geofencing engine | `GeofencingEngine` | `GEOFENCING` |
+
+---
+
+## License Gate Behaviour
+
+| Condition | Result |
+|---|---|
+| No `licenseKey` | Core features work; Pro features blocked with `console.warn` |
+| Valid Pro key | All features unlocked; `🔑 [NavCore] License validation complete. Plan: pro` logged |
+| `isDev: true` | All features bypassed (development mode) |
+| Expired / tampered key | Pro features blocked; status: `EXPIRED` / `INVALID` |
+
+License keys are verified **offline** using ECDSA P-256 — no network calls, no tracking.
+
+---
+
+## NavCore Engine API
+
+```typescript
+const engine = new NavCore(options?: NavCoreOptions);
+
+// Setup
+engine.setRoute(coords: Coordinate[], instructions?: NavInstruction[]);
+engine.startNavigation();
+
+// GPS update (returns state snapshot)
+const state: NavCoreState = engine.update(gpsUpdate: NavGpsUpdate);
+
+// Render tick (call at ~60fps between GPS updates)
+engine.tick(nowMs: number);
+
+// Events
+engine.on('instruction', (instr: NavInstruction) => void);
+engine.on('deviation',   ({ anchorIndex, ghostCoord }) => void);
+engine.on('arrival',     () => void);
+engine.on('routeLoaded', ({ routeLength }) => void);
+engine.off(event, handler);
+
+// State & introspection
+engine.getState(): NavCoreState;
+engine.getLicenseManager(): LicenseManager;
+engine.getRoute(): ReadonlyArray<Coordinate>;
+engine.destroy();
+```
+
+### NavCoreState
+
+```typescript
+interface NavCoreState {
+  snappedCoord: Coordinate | null;    // GPS-snapped position on route
+  rawGpsCoord: Coordinate | null;     // Raw GPS position
+  bearing: number;                    // Smoothed heading (degrees)
+  routeIndex: number;                 // Current segment index
+  distanceToRoute: number;            // Distance from route (metres)
+  corridor: number;                   // Dynamic off-route threshold (metres)
+  isOffRoute: boolean;                // True when deviation confirmed
+  hasArrived: boolean;
+  distanceToDestination: number | null;         // Remaining distance (metres)
+  distanceToNextInstruction: number | null;     // Distance to next turn
+  nextInstructionIndex: number | null;
+  currentSpeed: number;               // m/s
+  isGpsStale: boolean;
+  gpsAgeMs: number;
+  licenseStatus: string;              // 'VALID' | 'INVALID' | 'EXPIRED' | 'MISSING'
+}
+```
+
+---
+
+## Documentation
+
+| Guide | Link |
+|---|---|
+| Architecture | [docs/architecture.md](./docs/architecture.md) |
+| Getting Started | [docs/getting-started.md](./docs/getting-started.md) |
+| Directions Providers | [docs/directions-providers.md](./docs/directions-providers.md) |
+| Renderer Adapters | [docs/renderer-adapters.md](./docs/renderer-adapters.md) |
+| API Reference | [docs/api-reference.md](./docs/api-reference.md) |
+| Custom Routes | [docs/custom-routes.md](./docs/custom-routes.md) |
+| Instructions & Voice | [docs/instructions.md](./docs/instructions.md) |
+| Pro Features | [docs/p3-features.md](./docs/p3-features.md) |
+| Testing Guide | [docs/testing.md](./docs/testing.md) |
+
+---
+
+## License
+
+- **Core engine** (`@ingissa/navcore-core`): [MIT](./LICENSE) for open-source projects
+- **Pro features & adapters**: Commercial license required — [Not yet available]()
+
+---
+
+© Ingissa · [8abnav@gmail.com](mailto:8abnav@gmail.com)

package/dist/{NavCore-DzTPBxIc.d.mts → NavCore-qf5_0qsR.d.mts}

@@ -34,7 +34,7 @@ interface InstructionResult {
 /**
  * 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;
+declare function resolveNextInstruction(currentGeometryIdx: number, instructions: NavInstruction[], currentInstrIdx: number, route: Coordinate[], currentCoord: Coordinate, vehicleBearing: number | null, vehicleDistance: number, speed?: number, isCircuit?: boolean): InstructionResult;
 
 /**
  * Module 9a: NavigationFSM
@@ -151,12 +151,8 @@ declare class OffRouteFSM {
 /**
  * Feature flag constants for SDK consumers.
  *
- * CORE features: available to all users without a license key.
- *   - GPS smoothing, basic snapping, route building, directions providers,
- *     progress tracking, and route offset prediction are all free.
- *
- * PRO features: require a valid commercial license key.
- *   Each PRO engine checks the license at runtime and gracefully degrades.
+ * CORE features: available to all users (MIT license).
+ * PRO  features: require a valid commercial license key.
  */
 declare const FEATURES: {
     /**
@@ -165,45 +161,43 @@ declare const FEATURES: {
      */
     readonly GPS_SMOOTHING: "gps_smoothing";
     /**
-     * Basic route snapping (nearest-point projection) with bearing and inertia
-     * penalties to prevent U-turn snaps and oscillation.
-     * Both basic and advanced snapping quality are available in the free tier.
+     * Basic route snapping (nearest-point projection).
+     * Snaps GPS position to the closest route segment.
      */
     readonly BASIC_SNAPPING: "basic_snapping";
     /**
-     * Progress anti-regression: prevents route index from jumping backward.
-     * Essential for circuit routes and motorway slip roads.
-     * Used unconditionally inside NavCore — available in the free tier.
+     * Advanced route snapping with bearing penalty + inertia.
+     * Prevents incorrect snaps on parallel roads and U-turns.
      */
-    readonly PROGRESS_TRACKING: "progress_tracking";
+    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.
-     * Used unconditionally inside NavCore — available in the free tier.
      */
     readonly ROUTE_OFFSET: "route_offset";
     /**
-     * Dead reckoning: continues navigation during GPS signal loss.
-     * Predicts position based on last known speed and bearing.
-     * DeadReckoningEngine.predict() is a no-op without a Pro license.
+     * Progress anti-regression: prevents route index from jumping backward.
+     * Essential for circuit routes and motorway slip roads.
      */
-    readonly DEAD_RECKONING: "dead_reckoning";
+    readonly PROGRESS_TRACKING: "progress_tracking";
     /**
      * Advanced bearing engine with look-ahead and speed-adaptive alpha.
      * Produces stable heading for smooth map camera rotation.
-     * Gated inside NavCore.update() via this.has(FEATURES.ADVANCED_BEARING).
      */
     readonly ADVANCED_BEARING: "advanced_bearing";
     /**
      * Compound deviation detection: combines distance, bearing, and speed signals.
      * Eliminates false off-route triggers in tunnels and urban canyons.
-     * DeviationDetector.evaluate() returns a neutral signal without a Pro license.
      */
     readonly COMPOUND_DEVIATION: "compound_deviation";
     /**
      * Parallel road disambiguation + U-turn snap protection.
      * Prevents snapping to the wrong carriageway when bearing mismatches route direction.
-     * ParallelRoadResolver falls back to pure distance sorting without a Pro license.
      */
     readonly PARALLEL_ROAD_RESOLUTION: "parallel_road_resolution";
     /**
@@ -213,17 +207,14 @@ declare const FEATURES: {
     readonly U_TURN_PROTECTION: "u_turn_protection";
     /**
      * Timed voice instruction cues with deduplication and priority levels.
-     * VoiceTriggerEngine.update() returns null without a Pro license.
      */
     readonly VOICE_TRIGGERS: "voice_triggers";
     /**
      * Local ETA computation using rolling speed average — zero API calls.
-     * ETAEngine.update() returns isReliable=false without a Pro license.
      */
     readonly ETA: "eta";
     /**
      * Circular and polygon geofencing with enter/exit/dwell events.
-     * GeofencingEngine.update() returns [] without a Pro license.
      */
     readonly GEOFENCING: "geofencing";
     /**
@@ -256,25 +247,9 @@ declare class LicenseManager {
     private payload;
     private enabledFeatures;
     private warnedFeatures;
-    private static activeManager;
-    static getActive(): LicenseManager | null;
-    /**
-     * Clear the active manager reference.
-     * Intended for test teardown only — not for production use.
-     */
-    static clearActive(): void;
-    /**
-     * Promote this instance to the global active manager.
-     *
-     * Security rule: A VALID license context cannot be overwritten by an
-     * INVALID / MISSING / EXPIRED one. Once a valid license is registered,
-     * it holds the slot until explicitly cleared or replaced by another
-     * valid license.
-     */
-    private promoteToActive;
+    private isDev;
     private static PUBLIC_KEY_SPKI;
-    constructor(licenseKey?: string);
-    private tryValidateSync;
+    constructor(licenseKey?: string, isDev?: boolean);
     validate(key: string): Promise<LicenseStatus>;
     private extractFeatures;
     hasFeature(feature: FeatureKey): boolean;
@@ -311,6 +286,7 @@ interface NavGpsUpdate {
 }
 interface NavCoreOptions {
     licenseKey?: string;
+    isDev?: boolean;
     isCircuit?: boolean;
     kalmanQ?: number;
     kalmanRBase?: number;
@@ -321,24 +297,47 @@ interface NavCoreOptions {
 }
 interface NavCoreState {
     snappedCoord: Coordinate | null;
+    ghostCoord: Coordinate | null;
     rawGpsCoord: Coordinate | null;
     bearing: number;
     rawGpsBearing: number | null;
     routeIndex: number;
+    anchorRouteIndex: number | null;
     distanceToRoute: number;
     corridor: number;
+    confidence: number;
     isOffRoute: boolean;
+    navFsmState: string;
     progressIndex: number;
     hasArrived: boolean;
-    offRouteState: string;
-    lifecycleState: string;
+    rejoinCandidate: {
+        coord: Coordinate;
+        index: number;
+    } | null;
+    confidenceCone: {
+        center: Coordinate;
+        bearing: number;
+        angle: number;
+        length: number;
+    } | null;
+    alertState: 'NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED';
+    detourMode: 'NONE' | 'FREE' | 'COMMITTED';
+    detourCommitProgress: number;
     distanceToDestination: number | null;
     distanceToNextInstruction: number | null;
+    nextInstrIdx: number | null;
     nextInstructionIndex: number | null;
     currentSpeed: number;
     isGpsStale: boolean;
     gpsAgeMs: number;
     licenseStatus: string;
+    offRouteState: string;
+    lifecycleState: string;
+    stability?: {
+        oscillation: number;
+        drift: number;
+        jump: number;
+    };
 }
 type EventHandler = (...args: unknown[]) => void;
 declare class NavCore {
@@ -354,6 +353,7 @@ declare class NavCore {
     private forwardCum;
     private reverseCum;
     private snappedCoord;
+    private ghostCoord;
     private rawGpsCoord;
     private bearing;
     private rawGpsBearing;
@@ -371,8 +371,11 @@ declare class NavCore {
     private readonly options;
     private listeners;
     constructor(options?: NavCoreOptions);
-    /** Internal license check for automatic fallbacks that should not warn Core users every tick. */
-    private canUse;
+    /**
+     * 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 */