@ingissa/navcore-core 1.0.1 → 1.0.3

package/README.md

@@ -1,279 +1,279 @@
-# @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)](https://navcore.dev/pricing)
-[![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 navcore.dev/pricing](https://navcore.dev/pricing)
-
----
-
-## 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 — [navcore.dev/pricing](https://navcore.dev/pricing)
-
----
-
-© Ingissa · [navcore.dev](https://navcore.dev) · [contact@navcore.dev](mailto:contact@navcore.dev)
+# @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)