@ingissa/navcore-simulator 1.0.4 → 1.0.7

package/LICENSE

@@ -0,0 +1,3 @@
+Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved.
+
+No license is granted except by separate written agreement.

package/README.md

@@ -36,7 +36,7 @@
 import { SimulatorEngine, NoiseEngine } from '@ingissa/navcore-simulator'
 ```
 
-**Peer dependencies:** `@ingissa/navcore-core` (already in monorepo). React Native hooks additionally require `react` and `react-native`, and are exported from `@ingissa/navcore-simulator/react-native` so Node.js CI never loads React Native runtime files.
+**Peer dependencies:** `@ingissa/navcore-core` (already in monorepo). React Native hooks additionally require `react` and `react-native`, which are optional peer deps (tree-shaken in Node.js CI).
 
 ---
 
@@ -255,17 +255,11 @@ const report = fleet.report();
 
 ### useSimulator
 
-Drop-in replacement for `useGpsSimulator`:
-
-```typescript
-import {
-  NoiseEngine,
-  ScenarioInjector,
-  useSimulator,
-} from '@ingissa/navcore-simulator/react-native';
-
-// BEFORE
-const simGps = useGpsSimulator(route, isNavigating, speedMultiplier);
+Drop-in replacement for `useGpsSimulator`:
+
+```typescript
+// BEFORE
+const simGps = useGpsSimulator(route, isNavigating, speedMultiplier);
 
 // AFTER
 const { position, controls, session, isRecording } = useSimulator({
@@ -295,12 +289,10 @@ const { position, controls, session, isRecording } = useSimulator({
 
 ### SimulatorControls
 
-Self-contained control panel. Drop it into any screen:
-
-```tsx
-import { SimulatorControls } from '@ingissa/navcore-simulator/react-native';
-
-<SimulatorControls
+Self-contained control panel. Drop it into any screen:
+
+```tsx
+<SimulatorControls
   simulator={controls}
   session={session}
   style="minimal"           // 'minimal' | 'full' | 'floating'

package/dist/core/src/NavCore.d.ts

@@ -0,0 +1,142 @@
+/**
+ * NavCore — Main Orchestrator
+ *
+ * Fuses all extracted modules into a single engine class.
+ * Framework-agnostic; license verification does not require platform crypto APIs.
+ *
+ * Usage:
+ *   const engine = new NavCore({ licenseKey: '...' });
+ *   engine.setRoute(routeCoords, instructions);
+ *   engine.update(gpsUpdate);
+ *   const state = engine.getState();
+ */
+import type { Coordinate } from './geo/haversine';
+import { type NavInstruction } from './progress/InstructionResolver';
+import { NavigationFSM } from './off-route/NavigationFSM';
+import { OffRouteFSM } from './off-route/OffRouteFSM';
+import { LicenseManager } from './license/LicenseManager';
+import type { RoutePlan } from './route-plan/RoutePlan';
+export interface NavGpsUpdate {
+    coord: Coordinate;
+    accuracy: number | null;
+    bearing: number | null;
+    speed: number;
+    timestamp: number;
+}
+export interface NavCoreOptions {
+    licenseKey?: string;
+    isDev?: boolean;
+    isCircuit?: boolean;
+    kalmanQ?: number;
+    kalmanRBase?: number;
+    baseCorridorMeters?: number;
+    maxCorridorMeters?: number;
+    arrivalThresholdMeters?: number;
+    bearingSmoothingAlpha?: number;
+}
+export 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;
+    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;
+export declare class NavCore {
+    private kalman;
+    private snapper;
+    private deadReckoning;
+    private deviationDetector;
+    private lifecycleFSM;
+    private offRouteFSM;
+    private license;
+    private route;
+    private instructions;
+    private forwardCum;
+    private reverseCum;
+    private snappedCoord;
+    private ghostCoord;
+    private rawGpsCoord;
+    private bearing;
+    private rawGpsBearing;
+    private routeIndex;
+    private maxProgressIdx;
+    private prevSegment;
+    private distanceToRoute;
+    private corridor;
+    private prevDistToNext;
+    private currentSpeed;
+    private lastGpsTimestamp;
+    private instrIdx;
+    private linearOffset;
+    private hasArrived;
+    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;
+    /** Load route geometry and instructions */
+    setRoute(route: ReadonlyArray<Coordinate>, instructions?: ReadonlyArray<NavInstruction>): void;
+    /** Load a provider-normalized route plan without exposing mutable route state. */
+    loadRoute(plan: RoutePlan): void;
+    /** Start navigation */
+    startNavigation(): void;
+    /** Process a GPS update — the main engine tick */
+    update(gps: NavGpsUpdate): NavCoreState;
+    /** Time-advance tick for dead reckoning (call at RAF rate) */
+    tick(nowMs: number): NavCoreState;
+    /** Get the current engine state snapshot */
+    getState(): NavCoreState;
+    /** Destroy the engine */
+    destroy(): void;
+    on(event: string, handler: EventHandler): void;
+    off(event: string, handler: EventHandler): void;
+    private emit;
+    getLicenseManager(): LicenseManager;
+    getRoute(): ReadonlyArray<Coordinate>;
+    getInstructions(): ReadonlyArray<NavInstruction>;
+    getOffRouteFSM(): OffRouteFSM;
+    getLifecycleFSM(): NavigationFSM;
+}
+export {};
+//# sourceMappingURL=NavCore.d.ts.map

package/dist/core/src/NavCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavCore.d.ts","sourceRoot":"","sources":["../../../../core/src/NavCore.ts"],"names":[],"mappings":"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"}

package/dist/core/src/NavCore.js

@@ -0,0 +1,390 @@
+/**
+ * NavCore — Main Orchestrator
+ *
+ * Fuses all extracted modules into a single engine class.
+ * Framework-agnostic; license verification does not require platform crypto APIs.
+ *
+ * Usage:
+ *   const engine = new NavCore({ licenseKey: '...' });
+ *   engine.setRoute(routeCoords, instructions);
+ *   engine.update(gpsUpdate);
+ *   const state = engine.getState();
+ */
+import { haversineDistance } from './geo/haversine';
+import { buildForwardCumulativeDistances, buildReverseCumulativeDistances } from './geo/cumulative';
+import { KalmanFilter2D } from './kalman/KalmanFilter2D';
+import { RouteSnapper } from './snapper/RouteSnapper';
+import { DeadReckoningEngine } from './dead-reckoning/DeadReckoning';
+import { calculateDynamicCorridor } from './corridor/DynamicCorridor';
+import { DeviationDetector, findClosestSegment } from './corridor/DeviationDetector';
+import { applyBearingSmoothing } from './bearing/BearingEngine';
+import { validateProgressUpdate } from './progress/ProgressTracker';
+import { resolveNextInstruction } from './progress/InstructionResolver';
+import { advancePredictor, applyGpsCorrection } from './predictor/RouteOffsetPredictor';
+import { NavigationFSM } from './off-route/NavigationFSM';
+import { OffRouteFSM } from './off-route/OffRouteFSM';
+import { LicenseManager } from './license/LicenseManager';
+import * as C from './constants';
+import { FEATURES } from './features';
+// ── NavCore class ─────────────────────────────────────────────
+export class NavCore {
+    constructor(options) {
+        // ── Route data ───────────────────────────────────────────────
+        this.route = [];
+        this.instructions = [];
+        this.forwardCum = new Float64Array(0);
+        this.reverseCum = new Float64Array(0);
+        // ── State ────────────────────────────────────────────────────
+        this.snappedCoord = null;
+        this.ghostCoord = null;
+        this.rawGpsCoord = null;
+        this.bearing = 0;
+        this.rawGpsBearing = null;
+        this.routeIndex = 0;
+        this.maxProgressIdx = 0;
+        this.prevSegment = null;
+        this.distanceToRoute = 0;
+        this.corridor = C.BASE_CORRIDOR_METERS;
+        this.prevDistToNext = null;
+        this.currentSpeed = 0;
+        this.lastGpsTimestamp = 0;
+        this.instrIdx = 0;
+        this.linearOffset = 0;
+        this.hasArrived = false;
+        // ── Events ───────────────────────────────────────────────────
+        this.listeners = new Map();
+        this.options = {
+            licenseKey: options?.licenseKey ?? '',
+            isDev: options?.isDev ?? false,
+            isCircuit: options?.isCircuit ?? false,
+            kalmanQ: options?.kalmanQ ?? 0.00001,
+            kalmanRBase: options?.kalmanRBase ?? 0.00005,
+            baseCorridorMeters: options?.baseCorridorMeters ?? C.BASE_CORRIDOR_METERS,
+            maxCorridorMeters: options?.maxCorridorMeters ?? C.MAX_CORRIDOR_METERS,
+            arrivalThresholdMeters: options?.arrivalThresholdMeters ?? C.ARRIVAL_THRESHOLD_METERS,
+            bearingSmoothingAlpha: options?.bearingSmoothingAlpha ?? C.BEARING_SMOOTHING_ALPHA,
+        };
+        this.kalman = new KalmanFilter2D(this.options.kalmanQ, this.options.kalmanRBase);
+        this.snapper = new RouteSnapper({ useBearingPenalty: true, useInertiaPenalty: true });
+        this.deadReckoning = new DeadReckoningEngine();
+        this.deviationDetector = new DeviationDetector();
+        this.lifecycleFSM = new NavigationFSM();
+        this.offRouteFSM = new OffRouteFSM();
+        this.license = new LicenseManager(this.options.licenseKey, this.options.isDev);
+    }
+    // ── License gate helper ──────────────────────────────────────
+    /**
+     * Returns true if the feature is unlocked (dev mode OR valid license).
+     * Emits a one-time console warning when a Pro feature is blocked.
+     */
+    has(feature) {
+        const ok = this.license.hasFeature(feature);
+        if (!ok)
+            this.license.warnOnce(feature);
+        return ok;
+    }
+    // ── Public API ───────────────────────────────────────────────
+    /** Load route geometry and instructions */
+    setRoute(route, instructions) {
+        // Keep engine state isolated from consumer-owned provider responses.
+        this.route = route.map((coord) => [coord[0], coord[1]]);
+        this.instructions = (instructions ?? []).map((instruction) => ({
+            ...instruction,
+            location: [instruction.location[0], instruction.location[1]],
+        }));
+        this.forwardCum = buildForwardCumulativeDistances(this.route);
+        this.reverseCum = buildReverseCumulativeDistances(this.route);
+        this.routeIndex = 0;
+        this.maxProgressIdx = 0;
+        this.prevSegment = null;
+        this.instrIdx = 0;
+        this.linearOffset = 0;
+        this.hasArrived = false;
+        this.snappedCoord = null;
+        this.prevDistToNext = null;
+        this.lifecycleFSM.dispatch({ type: 'ROUTE_LOADED' });
+        // Auto-fill missing cumulative offsets for instructions
+        for (const instr of this.instructions) {
+            if (instr.cumulativeOffset === undefined && instr.geometryIndex < this.forwardCum.length) {
+                instr.cumulativeOffset = this.forwardCum[instr.geometryIndex];
+            }
+        }
+        this.emit('routeLoaded', { routeLength: this.route.length });
+    }
+    /** Load a provider-normalized route plan without exposing mutable route state. */
+    loadRoute(plan) {
+        this.setRoute(plan.geometry, plan.instructions);
+    }
+    /** Start navigation */
+    startNavigation() {
+        this.lifecycleFSM.dispatch({ type: 'USER_START_NAVIGATION' });
+        this.emit('navigationStarted');
+    }
+    /** Process a GPS update — the main engine tick */
+    update(gps) {
+        this.rawGpsCoord = gps.coord;
+        this.rawGpsBearing = gps.bearing;
+        this.currentSpeed = gps.speed;
+        this.lastGpsTimestamp = gps.timestamp;
+        if (this.route.length < 2)
+            return this.getState();
+        // 1. Kalman filter
+        const [filteredLng, filteredLat] = this.kalman.update(gps.coord[0], gps.coord[1], gps.accuracy ?? 10, gps.timestamp);
+        const filteredCoord = [filteredLng, filteredLat];
+        // 2. Snap to route
+        const startIdx = Math.max(0, this.routeIndex - 2);
+        const snap = this.snapper.snap(filteredCoord, this.route, startIdx, C.SNAP_WINDOW_SIZE, this.options.isCircuit, this.maxProgressIdx, this.routeIndex, gps.bearing, this.prevSegment);
+        this.ghostCoord = snap.proj;
+        // Look ahead to upcoming maneuver for dynamic corridor widening
+        let distToUpcomingManeuver = null;
+        if (this.instructions.length > 0 && this.instrIdx < this.instructions.length) {
+            const upcoming = this.instructions[this.instrIdx];
+            distToUpcomingManeuver = upcoming.cumulativeOffset !== undefined
+                ? Math.max(0, upcoming.cumulativeOffset - this.linearOffset)
+                : haversineDistance(filteredCoord[1], filteredCoord[0], upcoming.location[1], upcoming.location[0]);
+        }
+        // 3. Dynamic corridor
+        this.corridor = calculateDynamicCorridor(gps.speed, gps.accuracy, this.options.baseCorridorMeters, this.options.maxCorridorMeters, C.SPEED_CORRIDOR_FACTOR, C.GPS_ACCURACY_FACTOR, distToUpcomingManeuver);
+        // 4. Progress validation
+        const validatedIdx = validateProgressUpdate(this.routeIndex, snap.idx, this.route, snap.dist, C.MAX_SNAP_DISTANCE);
+        this.prevSegment = this.routeIndex;
+        this.routeIndex = validatedIdx;
+        this.maxProgressIdx = Math.max(this.maxProgressIdx, validatedIdx);
+        this.snappedCoord = snap.proj;
+        this.distanceToRoute = snap.dist;
+        // 5. Linear offset update
+        if (this.forwardCum.length > validatedIdx) {
+            const measuredOffset = this.forwardCum[validatedIdx] ?? 0;
+            this.linearOffset = applyGpsCorrection(this.linearOffset, measuredOffset, C.BETA_CORRECTION);
+        }
+        // 6. Bearing smoothing (PRO: ADVANCED_BEARING)
+        if (this.has(FEATURES.ADVANCED_BEARING)) {
+            this.bearing = applyBearingSmoothing(this.bearing, this.route, this.routeIndex, gps.speed, gps.bearing, this.options.bearingSmoothingAlpha);
+        }
+        else if (gps.bearing !== null) {
+            this.bearing = gps.bearing;
+        }
+        // 7. Deviation detection & Route Rejoin Handling
+        const isProDeviation = this.has(FEATURES.COMPOUND_DEVIATION);
+        if (this.offRouteFSM.state === 'ON_ROUTE' || this.offRouteFSM.state === 'DEVIATING') {
+            if (isProDeviation) {
+                const closest = findClosestSegment(filteredCoord, this.route, startIdx, C.SNAP_WINDOW_SIZE);
+                const signals = this.deviationDetector.evaluate(filteredCoord, gps.bearing, gps.speed, closest, this.route, this.corridor, this.prevDistToNext);
+                // Update moving-away tracker
+                if (closest.segmentIndex < this.route.length - 1) {
+                    const nextEnd = this.route[Math.min(closest.segmentIndex + 2, this.route.length - 1)];
+                    this.prevDistToNext = haversineDistance(filteredCoord[1], filteredCoord[0], nextEnd[1], nextEnd[0]);
+                }
+                if (signals.confirmed) {
+                    if (this.offRouteFSM.state === 'ON_ROUTE') {
+                        this.offRouteFSM.dispatch({
+                            type: 'DEVIATION_SUSPECTED',
+                            deviationSegmentIdx: closest.segmentIndex
+                        });
+                    }
+                    else if (this.offRouteFSM.isDeviationConfirmed()) {
+                        this.offRouteFSM.dispatch({
+                            type: 'DEVIATION_CONFIRMED',
+                            deviationSegmentIdx: closest.segmentIndex
+                        });
+                        this.emit('deviation', {
+                            anchorIndex: closest.segmentIndex,
+                            ghostCoord: snap.proj,
+                        });
+                    }
+                }
+                else if (this.offRouteFSM.state === 'DEVIATING') {
+                    this.offRouteFSM.dispatch({ type: 'RESUME' });
+                }
+            }
+            else {
+                // Core fallback: simple distance-based off-route check
+                if (snap.dist > this.corridor && this.offRouteFSM.state === 'ON_ROUTE') {
+                    this.offRouteFSM.dispatch({ type: 'DEVIATION_SUSPECTED', deviationSegmentIdx: snap.idx });
+                    this.emit('deviation', { anchorIndex: snap.idx, ghostCoord: snap.proj });
+                }
+                else if (snap.dist <= this.corridor && this.offRouteFSM.state === 'DEVIATING') {
+                    this.offRouteFSM.dispatch({ type: 'RESUME' });
+                }
+            }
+        }
+        else {
+            // Vehicle is in OFF_ROUTE, REJOINING, or REJOINED state.
+            // If the vehicle re-enters the valid corridor, resume ON_ROUTE and emit 'rejoined'.
+            if (snap.dist <= this.corridor) {
+                const wasOffRoute = this.offRouteFSM.state === 'OFF_ROUTE' ||
+                    this.offRouteFSM.state === 'REJOINING' ||
+                    this.offRouteFSM.state === 'REJOINED';
+                this.offRouteFSM.dispatch({ type: 'RESUME' });
+                if (wasOffRoute) {
+                    this.emit('rejoined', { resumeIndex: snap.idx });
+                }
+            }
+        }
+        // 8. Lifecycle join detection
+        if (this.lifecycleFSM.state === 'APPROACHING_ROUTE' && snap.dist < this.corridor) {
+            this.lifecycleFSM.dispatch({ type: 'ROUTE_JOINED', data: { index: snap.idx } });
+        }
+        // 9. Instruction resolution
+        if (this.instructions.length > 0) {
+            const instrResult = resolveNextInstruction(this.routeIndex, this.instructions, this.instrIdx, this.route, filteredCoord, gps.bearing, this.linearOffset, gps.speed, this.options.isCircuit);
+            if (instrResult.nextIdx !== this.instrIdx) {
+                this.instrIdx = instrResult.nextIdx;
+            }
+            if (instrResult.wasTriggered && instrResult.instruction) {
+                this.emit('instruction', instrResult.instruction);
+                this.instrIdx = instrResult.nextIdx + 1;
+            }
+        }
+        // 10. Arrival detection
+        if (!this.hasArrived && this.route.length > 0) {
+            const dest = this.route[this.route.length - 1];
+            const distToDest = haversineDistance(filteredCoord[1], filteredCoord[0], dest[1], dest[0]);
+            // Prevent immediate arrival on circuits by ensuring we've traversed at least 80% of the waypoints
+            const hasTraveledFarEnough = this.options.isCircuit ?
+                (this.routeIndex >= this.route.length * 0.8) : true;
+            if (distToDest < this.options.arrivalThresholdMeters && hasTraveledFarEnough) {
+                this.hasArrived = true;
+                this.lifecycleFSM.dispatch({ type: 'NAVIGATION_FINISHED' });
+                this.emit('arrival');
+            }
+        }
+        // 11. Dead reckoning anchor (PRO: DEAD_RECKONING)
+        if (this.has(FEATURES.DEAD_RECKONING)) {
+            this.deadReckoning.setAnchor(snap.proj, snap.idx, gps.timestamp);
+        }
+        const state = this.getState();
+        this.emit('update', state);
+        return state;
+    }
+    /** Time-advance tick for dead reckoning (call at RAF rate) */
+    tick(nowMs) {
+        if (this.has(FEATURES.DEAD_RECKONING)) {
+            const dr = this.deadReckoning.predict(this.currentSpeed, this.bearing, nowMs);
+            if (dr.isActive) {
+                this.snappedCoord = dr.predictedCoord;
+            }
+        }
+        // Advance linear offset predictor
+        if (this.lastGpsTimestamp > 0) {
+            const dt = (nowMs - this.lastGpsTimestamp) / 1000;
+            if (dt > 0 && dt < C.GPS_AGE_CAP_SECONDS) {
+                this.linearOffset = advancePredictor(this.linearOffset, this.currentSpeed, dt);
+            }
+        }
+        const state = this.getState();
+        this.emit('update', state);
+        return state;
+    }
+    /** Get the current engine state snapshot */
+    getState() {
+        const distToDest = this.route.length > 0 && this.reverseCum.length > this.routeIndex
+            ? (this.reverseCum[this.routeIndex] ?? null)
+            : null;
+        const distToNextInstr = this.instrIdx < this.instructions.length
+            ? (() => {
+                const instr = this.instructions[this.instrIdx];
+                return instr.cumulativeOffset !== undefined
+                    ? Math.max(0, instr.cumulativeOffset - this.linearOffset)
+                    : null;
+            })()
+            : null;
+        const gpsAgeMs = this.lastGpsTimestamp > 0 ? Date.now() - this.lastGpsTimestamp : 0;
+        const confidence = Math.max(0, Math.min(1, 1 - (this.distanceToRoute / Math.max(1, this.corridor))));
+        const alertState = this.offRouteFSM.state === 'DEVIATING' ? 'DEVIATING' :
+            this.offRouteFSM.state === 'OFF_ROUTE' || this.offRouteFSM.state === 'REROUTING' ? 'RECALCULATING' :
+                this.offRouteFSM.state === 'REJOINING' ? 'REJOINING' :
+                    this.offRouteFSM.state === 'REJOINED' ? 'REJOINED' : 'NONE';
+        const isOff = this.offRouteFSM.state !== 'ON_ROUTE' && this.offRouteFSM.state !== 'DEVIATING';
+        const detourMode = this.offRouteFSM.state === 'OFF_ROUTE' || this.offRouteFSM.state === 'REROUTING' ? 'FREE' : 'NONE';
+        const detourCommitProgress = this.offRouteFSM.state === 'OFF_ROUTE' ? 1.0 : 0.0;
+        const rejoinCandidate = this.offRouteFSM.context.rejoinTarget
+            ? {
+                coord: this.offRouteFSM.context.rejoinTarget.coordinates,
+                index: this.offRouteFSM.context.rejoinTarget.index,
+            }
+            : null;
+        const confidenceCone = this.snappedCoord
+            ? {
+                center: this.snappedCoord,
+                bearing: this.bearing,
+                angle: 30,
+                length: Math.max(10, Math.min(50, this.currentSpeed * 3)),
+            }
+            : null;
+        const nextIdx = this.instrIdx < this.instructions.length ? this.instrIdx : null;
+        return {
+            snappedCoord: this.snappedCoord,
+            ghostCoord: this.ghostCoord ?? this.snappedCoord,
+            rawGpsCoord: this.rawGpsCoord,
+            bearing: this.bearing,
+            rawGpsBearing: this.rawGpsBearing,
+            routeIndex: this.routeIndex,
+            anchorRouteIndex: this.prevSegment ?? this.routeIndex,
+            distanceToRoute: this.distanceToRoute,
+            corridor: this.corridor,
+            confidence,
+            isOffRoute: isOff,
+            navFsmState: this.lifecycleFSM.state,
+            progressIndex: this.routeIndex,
+            hasArrived: this.hasArrived,
+            rejoinCandidate,
+            confidenceCone,
+            alertState,
+            detourMode,
+            detourCommitProgress,
+            distanceToDestination: distToDest,
+            distanceToNextInstruction: distToNextInstr,
+            nextInstrIdx: nextIdx,
+            nextInstructionIndex: nextIdx,
+            currentSpeed: this.currentSpeed,
+            isGpsStale: gpsAgeMs > C.GPS_STALE_MS,
+            gpsAgeMs,
+            licenseStatus: this.license.getStatus(),
+            offRouteState: this.offRouteFSM.state,
+            lifecycleState: this.lifecycleFSM.state,
+        };
+    }
+    /** Destroy the engine */
+    destroy() {
+        this.listeners.clear();
+        this.route = [];
+        this.instructions = [];
+        this.snappedCoord = null;
+        this.ghostCoord = null;
+        this.rawGpsCoord = null;
+        this.kalman.reset();
+        this.deadReckoning.clearAnchor();
+        this.lifecycleFSM.reset();
+        this.offRouteFSM.reset();
+    }
+    // ── Event system ─────────────────────────────────────────────
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        this.listeners.get(event).push(handler);
+    }
+    off(event, handler) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            const idx = handlers.indexOf(handler);
+            if (idx >= 0)
+                handlers.splice(idx, 1);
+        }
+    }
+    emit(event, ...args) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(...args);
+            }
+        }
+    }
+    // ── Getters ──────────────────────────────────────────────────
+    getLicenseManager() { return this.license; }
+    getRoute() { return this.route; }
+    getInstructions() { return this.instructions; }
+    getOffRouteFSM() { return this.offRouteFSM; }
+    getLifecycleFSM() { return this.lifecycleFSM; }
+}

package/dist/core/src/bearing/BearingEngine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Module 5: BearingEngine
+ * Speed-adaptive IIR bearing smoothing.
+ */
+import { type Coordinate } from '../geo/haversine';
+/**
+ * Calculate speed-adaptive smoothing factor.
+ * Higher speed → less smoothing (alpha closer to 1).
+ * Lower speed → more smoothing (alpha closer to base value).
+ */
+export declare function getSpeedAdaptiveAlpha(speedMps: number, baseAlpha?: number): number;
+/**
+ * Compute bearing from the route geometry at the current segment.
+ */
+export declare function calculateRobustBearing(route: Coordinate[], currentIdx: number, lookAhead?: number): number;
+/**
+ * Blend two bearings using the shortest angular path.
+ */
+export declare function blendBearing(current: number, target: number, alpha: number): number;
+/**
+ * Full bearing smoothing pipeline: route bearing → IIR blend → output.
+ */
+export declare function applyBearingSmoothing(currentBearing: number, route: Coordinate[], routeIdx: number, speedMps: number, gpsBearing: number | null, baseAlpha?: number): number;
+//# sourceMappingURL=BearingEngine.d.ts.map

package/dist/core/src/bearing/BearingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BearingEngine.d.ts","sourceRoot":"","sources":["../../../../../core/src/bearing/BearingEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOnD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAgC,GAC1C,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EAAE,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAU,GACpB,MAAM,CAQR;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,GAAE,MAAgC,GAC1C,MAAM,CAWR"}

package/dist/core/src/bearing/BearingEngine.js

@@ -0,0 +1,50 @@
+/**
+ * Module 5: BearingEngine
+ * Speed-adaptive IIR bearing smoothing.
+ */
+import { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+import { BEARING_SMOOTHING_ALPHA, BEARING_MIN_SPEED_MPS, } from '../constants';
+/**
+ * Calculate speed-adaptive smoothing factor.
+ * Higher speed → less smoothing (alpha closer to 1).
+ * Lower speed → more smoothing (alpha closer to base value).
+ */
+export function getSpeedAdaptiveAlpha(speedMps, baseAlpha = BEARING_SMOOTHING_ALPHA) {
+    if (speedMps < BEARING_MIN_SPEED_MPS)
+        return baseAlpha * 0.5;
+    if (speedMps > 20)
+        return Math.min(0.9, baseAlpha * 2);
+    return baseAlpha;
+}
+/**
+ * Compute bearing from the route geometry at the current segment.
+ */
+export function calculateRobustBearing(route, currentIdx, lookAhead = 3) {
+    const endIdx = Math.min(currentIdx + lookAhead, route.length - 1);
+    if (currentIdx >= route.length - 1 || currentIdx === endIdx) {
+        return currentIdx > 0
+            ? getBearingBetweenPoints(route[currentIdx - 1], route[currentIdx])
+            : 0;
+    }
+    return getBearingBetweenPoints(route[currentIdx], route[endIdx]);
+}
+/**
+ * Blend two bearings using the shortest angular path.
+ */
+export function blendBearing(current, target, alpha) {
+    const diff = normalizeAngle(target - current);
+    return (current + alpha * diff + 360) % 360;
+}
+/**
+ * Full bearing smoothing pipeline: route bearing → IIR blend → output.
+ */
+export function applyBearingSmoothing(currentBearing, route, routeIdx, speedMps, gpsBearing, baseAlpha = BEARING_SMOOTHING_ALPHA) {
+    const alpha = getSpeedAdaptiveAlpha(speedMps, baseAlpha);
+    const routeBearing = calculateRobustBearing(route, routeIdx);
+    // Use GPS bearing if available and speed is sufficient, blend with route bearing
+    if (gpsBearing !== null && speedMps > BEARING_MIN_SPEED_MPS) {
+        const gpsBlended = blendBearing(currentBearing, gpsBearing, alpha * 0.3);
+        return blendBearing(gpsBlended, routeBearing, alpha);
+    }
+    return blendBearing(currentBearing, routeBearing, alpha);
+}