@ingissa/navcore-simulator 1.0.8 → 1.0.10

package/package.json

@@ -1,58 +1,61 @@
-{
-  "name": "@ingissa/navcore-simulator",
-  "version": "1.0.8",
-  "description": "Headless GPS simulator for NavCore. Works in Node.js, React Native, and CI.",
-  "author": "Ingissa <8abnav@gmail.com>",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://navcore.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ingissa/navcore-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ingissa/navcore-sdk/issues"
-  },
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=16"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
-  "peerDependencies": {
-    "@ingissa/navcore-core": "^1.0.8",
-    "react": ">=18",
-    "react-native": ">=0.72"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-native": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^25.8.0"
-  }
-}
+{
+  "name": "@ingissa/navcore-simulator",
+  "version": "1.0.10",
+  "description": "Headless GPS simulator for NavCore. Works in Node.js, React Native, and CI.",
+  "author": "Ingissa <8abnav@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://navcore-web.vercel.app/",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs",
+      "require": "./dist/node.js"
+    },
+    "./react-native": {
+      "types": "./dist/react-native.d.ts",
+      "import": "./dist/react-native.mjs",
+      "require": "./dist/react-native.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build --prefix ../.. && node ../../scripts/check-release.mjs"
+  },
+  "peerDependencies": {
+    "@ingissa/navcore-core": "^1.0.10",
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0"
+  }
+}

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

@@ -1,142 +0,0 @@
-/**
- * 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

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

package/dist/core/src/NavCore.js

@@ -1,390 +0,0 @@
-/**
- * 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; }
-}