@ingissa/navcore-core 1.0.2 → 1.0.4

package/README.md

@@ -1,279 +1,136 @@
-# @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)
+# @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.

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

@@ -151,8 +151,12 @@ declare class OffRouteFSM {
 /**
  * Feature flag constants for SDK consumers.
  *
- * CORE features: available to all users (MIT license).
- * PRO  features: require a valid commercial license key.
+ * 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.
  */
 declare const FEATURES: {
     /**
@@ -161,43 +165,45 @@ declare const FEATURES: {
      */
     readonly GPS_SMOOTHING: "gps_smoothing";
     /**
-     * Basic route snapping (nearest-point projection).
-     * Snaps GPS position to the closest route segment.
+     * 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.
      */
     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.
+     * 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.
      */
-    readonly DEAD_RECKONING: "dead_reckoning";
+    readonly PROGRESS_TRACKING: "progress_tracking";
     /**
      * 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";
     /**
-     * Progress anti-regression: prevents route index from jumping backward.
-     * Essential for circuit routes and motorway slip roads.
+     * 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.
      */
-    readonly PROGRESS_TRACKING: "progress_tracking";
+    readonly DEAD_RECKONING: "dead_reckoning";
     /**
      * 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";
     /**
@@ -207,14 +213,17 @@ 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";
     /**
@@ -247,9 +256,25 @@ declare class LicenseManager {
     private payload;
     private enabledFeatures;
     private warnedFeatures;
-    private isDev;
+    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 static PUBLIC_KEY_SPKI;
-    constructor(licenseKey?: string, isDev?: boolean);
+    constructor(licenseKey?: string);
+    private tryValidateSync;
     validate(key: string): Promise<LicenseStatus>;
     private extractFeatures;
     hasFeature(feature: FeatureKey): boolean;
@@ -286,7 +311,6 @@ interface NavGpsUpdate {
 }
 interface NavCoreOptions {
     licenseKey?: string;
-    isDev?: boolean;
     isCircuit?: boolean;
     kalmanQ?: number;
     kalmanRBase?: number;
@@ -347,11 +371,8 @@ declare class NavCore {
     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;
+    /** Internal license check for automatic fallbacks that should not warn Core users every tick. */
+    private canUse;
     /** Load route geometry and instructions */
     setRoute(route: Coordinate[], instructions?: NavInstruction[]): void;
     /** Start navigation */