NavCore SDK v1.0.11

NavCore SDK Documentation

Vendor-neutral, zero-runtime-dependency navigation engine for Expo, React Native, browsers, Node.js, and CI/CD. Features a deterministic 11-stage pipeline, offline P-256 license verification, and modular packages.

Installation

NavCore publishes 5 official packages to npm. Install @ingissa/navcore-core first, then add the platform adapter, simulator, or types definition package your application requires.

# Core engine (zero runtime dependencies)
npm install @ingissa/navcore-core

# React Native & Expo integration
npm install @ingissa/navcore-core @ingissa/navcore-react-native

# GPS simulation, noise models, and replay
npm install @ingissa/navcore-core @ingissa/navcore-simulator

# Mapbox Directions API provider adapter
npm install @ingissa/navcore-core @ingissa/navcore-mapbox

# TypeScript shared types
npm install -D @ingissa/navcore-types
@ingissa/navcore-corev1.0.11

Navigation engine, Kalman filter, snapper, FSMs, route planning, dead reckoning, and built-in OSRM, Valhalla, and ORS providers with zero runtime dependencies.

@ingissa/navcore-typesv1.0.11

Shared TypeScript interfaces, navigation types, directions contracts, and state interfaces across the NavCore ecosystem.

@ingissa/navcore-mapboxv1.0.11

Mapbox Directions API adapter with automatic waypoint chunking, step parsing, and seamless RoutePlan integration.

@ingissa/navcore-react-nativev1.0.11

React Native bindings with NavCoreProvider and granular, tearing-free selectors powered by useSyncExternalStore.

@ingissa/navcore-simulatorv1.0.11

Headless GPS simulator for Node.js, React Native, and CI with Gaussian/urban noise models, scenario injection, and GPX replay.

All packages export flat distribution builds supporting standard ESM, CommonJS, and TypeScript definitions.

Runtime State (NavCoreState)

On every GPS tick, NavCore computes and returns a consolidated, typed state snapshot:

export interface NavCoreState {
  /** Snapped coordinate [lon, lat] on route geometry, or raw fix if off-route */
  snappedCoord: Coordinate | null;
  /** Raw un-snapped coordinate from the last GPS fix */
  rawCoord: Coordinate | null;
  /** Filtered and smoothed heading in degrees (0-360) */
  bearing: number;
  /** Raw heading reported directly by device GPS */
  rawBearing: number | null;
  /** Filtered ground speed in metres per second */
  speed: number;
  /** Current active vertex index on the loaded route geometry */
  routeIndex: number;
  /** Remaining distance to destination in metres */
  distanceToDestination: number | null;
  /** Remaining distance to the next upcoming maneuver in metres */
  distanceToNextInstruction: number | null;
  /** Next upcoming navigation instruction object */
  nextInstruction: NavInstruction | null;
  /** Flag set to true when distanceToDestination <= arrivalThresholdMeters */
  hasArrived: boolean;
  /** True when the vehicle is confirmed off-route */
  isOffRoute: boolean;
  /** Current state of the off-route state machine */
  alertState: 'ON_ROUTE' | 'DEVIATING' | 'OFF_ROUTE' | 'REROUTING' | 'REJOINING' | 'REJOINED' | 'FAILED';
  /** High-level navigation lifecycle state */
  lifecycleState: 'IDLE' | 'OVERVIEW' | 'APPROACHING_ROUTE' | 'ON_ROUTE';
  /** Orthogonal distance in metres from raw fix to nearest route segment */
  distanceToRoute: number;
  /** Current dynamic corridor width in metres */
  corridor: number;
  /** True when GPS updates have ceased for longer than gpsStaleMs */
  isGpsStale: boolean;
  /** Offline license validity */
  licenseStatus: 'VALID' | 'INVALID' | 'EXPIRED' | 'MISSING';
}

Quick Start: NavigationSession API

The recommended high-level entrypoint is createNavigationSession, which binds routing, turn-by-turn navigation, and event subscriptions:

import {
  createNavigationSession,
  OSRMDirectionsProvider,
} from '@ingissa/navcore-core';

// 1. Initialize directions provider
const provider = new OSRMDirectionsProvider({
  baseUrl: 'https://router.project-osrm.org',
});

// 2. Create the navigation session
const nav = createNavigationSession({
  provider,
  providerName: 'osrm',
  engineOptions: { isDev: true }, // Unlocks all features during development
});

// 3. Subscribe to navigation events
nav.subscribe('instruction', (instr) => {
  console.log('Turn maneuver:', instr.text);
});

nav.subscribe('arrival', () => {
  console.log('Destination reached!');
});

nav.subscribe('deviation', ({ anchorIndex }) => {
  console.warn('Vehicle off-route near segment:', anchorIndex);
});

// 4. Request route and start navigation
await nav.navigate({
  origin: [2.3522, 48.8566],
  destination: [2.3009, 48.8741],
});

// 5. Update engine with incoming GPS fixes
nav.update({
  coord: [2.3522, 48.8566],
  accuracy: 5,
  bearing: 180,
  speed: 12.5,
  timestamp: Date.now(),
});

Engine API (NavCore)

For granular control over route plans, snapping parameters, and the lifecycle loop, instantiate NavCore directly:

import { NavCore, createRoutePlan, OSRMDirectionsProvider } from '@ingissa/navcore-core';

const provider = new OSRMDirectionsProvider({ baseUrl: 'https://router.project-osrm.org' });
const rawRoute = await provider.getRoute([[2.3522, 48.8566], [2.3009, 48.8741]]);

// Normalize route into an immutable RoutePlan
const plan = createRoutePlan(rawRoute, { provider: 'osrm' });

// Initialize engine with custom thresholds
const engine = new NavCore({
  isDev: true,
  baseCorridorMeters: 25,
  maxCorridorMeters: 60,
  arrivalThresholdMeters: 30,
});

engine.loadRoute(plan);
engine.startNavigation();

// In location callback:
const state = engine.update({
  coord: [2.3523, 48.8567],
  accuracy: 6,
  bearing: 90,
  speed: 10,
  timestamp: Date.now(),
});

console.log('Snapped position:', state.snappedCoord);
console.log('Remaining distance (m):', state.distanceToDestination);

Typed Events

Listen to discrete navigation milestones using engine.on():

import { NavCore } from '@ingissa/navcore-core';

const engine = new NavCore({ isDev: true });

engine.on('routeLoaded', ({ routeLength }) => {
  console.log('Route loaded, waypoints:', routeLength);
});

engine.on('navigationStarted', () => {
  console.log('Turn-by-turn guidance active');
});

engine.on('instruction', (instruction) => {
  console.log('Next turn:', instruction.text);
});

engine.on('arrival', () => {
  console.log('Vehicle arrived at destination');
});

engine.on('deviation', ({ anchorIndex, ghostCoord }) => {
  console.warn('Off-route deviation at segment', anchorIndex);
});

engine.on('offRouteChanged', ({ isOffRoute, state }) => {
  console.log('Off route state:', isOffRoute, state.alertState);
});

engine.on('stateUpdate', (state) => {
  console.log('Progress index:', state.routeIndex);
});

React Native & Expo

@ingissa/navcore-react-native uses useSyncExternalStore to subscribe to granular state slices without unnecessary re-renders:

import React from 'react';
import { View, Text } from 'react-native';
import {
  NavCoreProvider,
  useNavSelector,
  useNavInstruction,
  useNavAlert,
  useNavSpeed,
} from '@ingissa/navcore-react-native';

export function NavigationDashboard() {
  const instruction = useNavInstruction();
  const alertState = useNavAlert();
  const speed = useNavSpeed();
  const distanceLeft = useNavSelector((s) => s.distanceToDestination);

  return (
    <View className="p-4 bg-white rounded-xl shadow">
      <Text className="text-xl font-bold">{instruction?.text ?? 'Proceed along route'}</Text>
      <Text className="text-slate-500">Remaining: {Math.round(distanceLeft ?? 0)} m</Text>
      <Text className="text-slate-500">Speed: {Math.round((speed ?? 0) * 3.6)} km/h</Text>
      {alertState === 'OFF_ROUTE' && (
        <Text className="text-red-600 font-bold">Off Route — Recalculating...</Text>
      )}
    </View>
  );
}

Directions Providers

ProviderPackageTypical use
OSRM@ingissa/navcore-coreSelf-hosted or public OSRM routing server
Valhalla@ingissa/navcore-coreSelf-hosted Valhalla routing with custom costing
OpenRouteService@ingissa/navcore-coreHosted ORS routing with token authentication
Mapbox Directions@ingissa/navcore-mapboxMapbox Directions API with automatic waypoint chunking
import {
  OSRMDirectionsProvider,
  ValhallaDirectionsProvider,
  OpenRouteServiceProvider,
} from '@ingissa/navcore-core';
import { MapboxDirectionsProvider } from '@ingissa/navcore-mapbox';

const osrm = new OSRMDirectionsProvider({ baseUrl: 'https://router.project-osrm.org' });
const valhalla = new ValhallaDirectionsProvider({ baseUrl: 'http://localhost:8002' });
const ors = new OpenRouteServiceProvider({ apiKey: 'YOUR_ORS_KEY' });
const mapbox = new MapboxDirectionsProvider({ accessToken: 'YOUR_MAPBOX_TOKEN' });

Pro Modules & Licensing

Pro features verify offline cryptographic signatures (ECDSA P-256). In local testing and CI, setting isDev: true unlocks all features without requiring a key.
import {
  NavCore,
  ETAEngine,
  GeofencingEngine,
  VoiceTriggerEngine,
} from '@ingissa/navcore-core';

const engine = new NavCore({
  licenseKey: process.env.NAVCORE_LICENSE_KEY,
});

// ETA rolling average engine
const eta = new ETAEngine({ speedWindowSize: 6 });

// Voice cue trigger scheduler (Early: 120m, Late: 20m)
const voice = new VoiceTriggerEngine({ earlyTriggerMeters: 120 });

// Circular and polygonal geofencing
const geofencing = new GeofencingEngine({ dwellThresholdMs: 5000 });
geofencing.addCircle('school-zone', 'School Zone', [2.3522, 48.8566], 150);

engine.on('instruction', (instruction) => {
  const cue = voice.onInstruction(instruction, engine.getState());
  if (cue) {
    console.log('Voice Cue:', cue.text); // Connect to your TTS engine
  }
});

Runnable Examples Suite

Full, standalone runnable examples are available in our public GitHub repository:

GitHub Examples Repository

Clone the repo and run any example with npx tsx:

👉 github.com/ingissa/ingissa-navcore-examples →
01

Basic Navigation

createNavigationSession with OSRM and typed events

02

Custom Route Builder

Manual route assembly, GPX, GeoJSON export

03

Instruction Editor

Maneuver editing, exam annotations, checkpoints

06

Directions Providers

Comparison of OSRM, Valhalla, ORS, Mapbox

07

Voice Triggers

VoiceTriggerEngine cue scheduling and TTS

08

ETA Engine

Rolling-window speed calculation and stop detection

09

Geofencing

Circular & polygon boundaries with enter/dwell/exit

10

Parallel Road Resolver

Dual-carriageway resolution and U-turn protection

11

Headless Testing

Automated in-memory route simulation for CI pipelines

Ready to integrate?

Start with Core, then add licensed Pro modules when your app needs production navigation intelligence.