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.11Navigation 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.11Shared TypeScript interfaces, navigation types, directions contracts, and state interfaces across the NavCore ecosystem.
@ingissa/navcore-mapboxv1.0.11Mapbox Directions API adapter with automatic waypoint chunking, step parsing, and seamless RoutePlan integration.
@ingissa/navcore-react-nativev1.0.11React Native bindings with NavCoreProvider and granular, tearing-free selectors powered by useSyncExternalStore.
@ingissa/navcore-simulatorv1.0.11Headless GPS simulator for Node.js, React Native, and CI with Gaussian/urban noise models, scenario injection, and GPX replay.
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
| Provider | Package | Typical use |
|---|---|---|
| OSRM | @ingissa/navcore-core | Self-hosted or public OSRM routing server |
| Valhalla | @ingissa/navcore-core | Self-hosted Valhalla routing with custom costing |
| OpenRouteService | @ingissa/navcore-core | Hosted ORS routing with token authentication |
| Mapbox Directions | @ingissa/navcore-mapbox | Mapbox 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
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:
Basic Navigation
createNavigationSession with OSRM and typed events
Custom Route Builder
Manual route assembly, GPX, GeoJSON export
Instruction Editor
Maneuver editing, exam annotations, checkpoints
Directions Providers
Comparison of OSRM, Valhalla, ORS, Mapbox
Voice Triggers
VoiceTriggerEngine cue scheduling and TTS
ETA Engine
Rolling-window speed calculation and stop detection
Geofencing
Circular & polygon boundaries with enter/dwell/exit
Parallel Road Resolver
Dual-carriageway resolution and U-turn protection
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.