@ingissa/navcore-simulator 1.0.7 → 1.0.9

package/dist/node.d.ts

@@ -0,0 +1,527 @@
+import { Coordinate as Coordinate$1 } from '@ingissa/navcore-core';
+
+/**
+ * @navcore/simulator — Core Types
+ *
+ * These types are the foundation of the entire simulator package.
+ * All other modules build on top of these definitions.
+ */
+/** [longitude, latitude] — Mapbox/GeoJSON order */
+type Coordinate = [number, number];
+/**
+ * Standard coords conforming to expo-location LocationObject['coords']
+ * and @react-native-community/geolocation.
+ */
+interface SimLocationCoords {
+    latitude: number;
+    longitude: number;
+    altitude: number | null;
+    accuracy: number | null;
+    altitudeAccuracy: number | null;
+    heading: number | null;
+    speed: number | null;
+}
+/**
+ * Standard LocationObject conforming to expo-location.
+ */
+interface SimLocationObject {
+    coords: SimLocationCoords;
+    timestamp: number;
+}
+/**
+ * A single simulated GPS position, emitted by SimulatorEngine on every tick.
+ * Shape includes standard LocationObject coords for drop-in Expo/React Native usage.
+ */
+interface SimPosition {
+    /** [longitude, latitude] */
+    coord: Coordinate;
+    /** Heading in degrees 0–360 */
+    bearing: number;
+    /** Speed in metres per second */
+    speed: number;
+    /** Simulated GPS accuracy radius in metres */
+    accuracy: number;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /**
+     * Standard LocationObject coords conforming to expo-location & React Native geolocation.
+     */
+    coords: SimLocationCoords;
+    /**
+     * Full standard LocationObject conforming to expo-location.
+     */
+    location?: SimLocationObject;
+    /** Optional debug metadata */
+    metadata?: {
+        /** Which geometry segment the vehicle is currently on */
+        segmentIndex: number;
+        /** Total metres travelled from route start */
+        distanceTravelled: number;
+        /** Whether noise was applied on this tick */
+        isNoisy: boolean;
+        /** Name of the active scenario, if any */
+        scenarioActive?: string;
+    };
+}
+/**
+ * Noise model applied to simulated GPS coordinates each tick.
+ */
+interface NoiseProfile {
+    /** Noise type */
+    type: 'NONE' | 'GAUSSIAN' | 'URBAN' | 'TUNNEL' | 'CUSTOM';
+    /** Standard deviation of the Gaussian noise in metres (default: 12) */
+    stdDevM: number;
+    /**
+     * Optional seed for deterministic noise generation.
+     * Same seed + same route = identical output (critical for regression tests).
+     */
+    seed?: number;
+    /**
+     * For CUSTOM type: return [lngOffset, latOffset] for each tick.
+     * @param index - current geometry segment index
+     */
+    customFn?: (index: number) => [number, number];
+}
+/**
+ * A scenario that is injected at a specific geometry index during simulation.
+ */
+interface Scenario {
+    /** Unique name for this scenario */
+    name: string;
+    /** Geometry index at which the scenario fires */
+    triggerIndex: number;
+    /** Scenario type */
+    type: 'GPS_BLACKOUT' | 'WRONG_SIDE_ROAD' | 'UTURN' | 'SPEED_SPIKE' | 'ACCURACY_DROP' | 'CUSTOM';
+    /** How long the scenario lasts in milliseconds */
+    durationMs?: number;
+    /** Scenario-specific configuration */
+    params?: Record<string, unknown>;
+}
+/**
+ * Full configuration object passed to SimulatorEngine.
+ * All callback fields are optional — the engine is fully usable without them
+ * (useful for CI/headless tests).
+ */
+interface SimulatorConfig {
+    /** The route geometry to simulate along */
+    routeGeometry: Coordinate[];
+    /** Simulated vehicle speed in km/h (default: 50) */
+    speedKmh?: number;
+    /** Playback speed multiplier: 1×, 2×, 4×, 8× (default: 1) */
+    speedMultiplier?: 1 | 2 | 4 | 8;
+    /** Noise model applied to each position (default: NoiseEngine.STANDARD) */
+    noiseProfile?: NoiseProfile;
+    /** Whether to restart from the beginning when the route ends (default: false) */
+    loop?: boolean;
+    /** Start simulation from this geometry index (default: 0) */
+    startIndex?: number;
+    /** If true, start() is called automatically after construction (default: false) */
+    autoStart?: boolean;
+    /** Called on every tick with the new simulated position */
+    onPositionUpdate?: (pos: SimPosition) => void;
+    /** Called when the route end is reached (or loop restarts) */
+    onRouteComplete?: () => void;
+    /** Called when a scenario begins */
+    onScenarioStart?: (scenario: Scenario) => void;
+    /** Called when a scenario ends */
+    onScenarioEnd?: (scenario: Scenario) => void;
+}
+/**
+ * A complete recorded simulation session.
+ * Produced by SimulatorEngine.stopRecording() / SessionRecorder.stop().
+ */
+interface SimSession {
+    /** UUID v4 session identifier */
+    id: string;
+    /** ISO 8601 start timestamp */
+    startedAt: string;
+    /** ISO 8601 end timestamp */
+    endedAt: string;
+    /** The route geometry used */
+    route: Coordinate[];
+    /** All SimPositions emitted during the session */
+    positions: SimPosition[];
+    /** Scenarios that fired, with their tick timestamps */
+    scenarios: Array<{
+        scenario: Scenario;
+        /** Unix ms when the scenario fired */
+        firedAt: number;
+    }>;
+    /** Aggregate statistics for this session */
+    stats: {
+        durationMs: number;
+        distanceTravelledM: number;
+        avgSpeedKmh: number;
+        noiseSamplesAdded: number;
+        scenariosFired: number;
+    };
+}
+
+/**
+ * SimulatorEngine — The headless GPS simulation core.
+ *
+ * Works in Node.js for CI tests. NO React, NO Expo APIs.
+ * All timers are cleaned up on destroy(). No memory leaks.
+ *
+ * State machine: idle → running ⇄ paused → complete
+ */
+
+type EngineState = 'idle' | 'running' | 'paused' | 'complete';
+declare class SimulatorEngine {
+    private readonly config;
+    private walker;
+    private noise;
+    private injector;
+    private _state;
+    private _position;
+    private _speedMultiplier;
+    private _timer;
+    private _lastTick;
+    private static readonly TICK_MS;
+    private _recording;
+    private _recordedPositions;
+    private _recordedScenarios;
+    private _sessionId;
+    private _sessionStart;
+    private _noiseSamplesAdded;
+    constructor(config: SimulatorConfig);
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    /**
+     * Jump to any geometry index.
+     * Bearing is recalculated from the new segment — seek() is always bearing-safe.
+     */
+    seek(geometryIndex: number): void;
+    setSpeed(multiplier: 1 | 2 | 4 | 8): void;
+    addScenario(scenario: Scenario): void;
+    removeScenario(name: string): void;
+    clearScenarios(): void;
+    get state(): EngineState;
+    get position(): SimPosition | null;
+    get progress(): number;
+    startRecording(sessionId?: string): void;
+    stopRecording(): SimSession;
+    destroy(): void;
+    private _startTimer;
+    private _stopTimer;
+    private _tick;
+    private _buildAndEmitPosition;
+}
+
+/**
+ * RouteWalker — Manages traversal of a route geometry array.
+ *
+ * Extracted from the inline useGpsSimulator hook so the traversal logic
+ * is testable independently of React, timers, or noise.
+ *
+ * ZERO dependencies beyond @navcore/core types.
+ */
+
+interface WalkerPosition {
+    /** Current floating-point index (e.g. 3.75 = between points 3 and 4) */
+    index: number;
+    /** Interpolated coordinate at the current index */
+    coord: Coordinate$1;
+    /** Forward-looking bearing at the current segment */
+    bearing: number;
+    /** Total metres travelled from route start */
+    distanceTravelled: number;
+    /** True if the walker has reached or passed the last point */
+    isComplete: boolean;
+}
+declare class RouteWalker {
+    private readonly geometry;
+    private _index;
+    private _distanceTravelled;
+    private readonly _cumulativeDistances;
+    private _isComplete;
+    constructor(geometry: Coordinate$1[], startIndex?: number);
+    /**
+     * Advance the walker by `steps` geometry points.
+     * Fractional steps are supported for sub-second precision.
+     */
+    advance(steps: number): WalkerPosition;
+    /**
+     * Advance the walker by a physical distance in metres.
+     * This is the preferred way for smooth constant-speed simulation.
+     */
+    advanceByDistance(meters: number): WalkerPosition;
+    private _finalizeAdvance;
+    /**
+     * Seek directly to a geometry index (integer or fractional).
+     * Recalculates bearing from the new position.
+     */
+    seek(index: number): WalkerPosition;
+    /**
+     * Get an interpolated coordinate between geometry[index] and geometry[index+1].
+     * @param index - integer index
+     * @param fraction - 0..1 interpolation factor
+     */
+    interpolate(index: number, fraction: number): Coordinate$1;
+    /**
+     * Compute the forward-looking bearing at a given integer index.
+     * At the last point, returns the bearing of the final segment.
+     */
+    bearingAt(index: number): number;
+    /**
+     * Total haversine distance from the route start to the given index.
+     * Uses the pre-computed cumulative distances (O(1)).
+     */
+    distanceAtIndex(index: number): number;
+    /**
+     * Alias for distanceAtIndex.
+     */
+    distanceToIndex(index: number): number;
+    /**
+     * Convert a distance in metres back to a fractional index.
+     * Uses binary search for O(log N) performance.
+     */
+    private _distanceToIndex;
+    get totalDistanceM(): number;
+    get totalPoints(): number;
+    get isComplete(): boolean;
+    get currentIndex(): number;
+    private _currentPosition;
+    /** Interpolate cumulative distance for fractional index */
+    private _interpolatedDistance;
+}
+
+/**
+ * NoiseEngine — GPS noise simulation.
+ *
+ * Formalises the ±0.00011° noise from the original useGpsSimulator
+ * into a testable, seeded, swappable noise model.
+ *
+ * Box-Muller transform for Gaussian sampling — ZERO external dependencies.
+ *
+ * Degrees-per-metre constants:
+ *   1° latitude  ≈ 110540 m
+ *   1° longitude ≈ 111320 m (at equator; good enough for noise simulation)
+ */
+
+declare class NoiseEngine {
+    private profile;
+    private rng;
+    private _tickIndex;
+    constructor(profile: NoiseProfile);
+    /** No noise — returns the exact coordinate */
+    static readonly NONE: NoiseProfile;
+    /** Good urban GPS — ~3m standard deviation */
+    static readonly CLEAN: NoiseProfile;
+    /** Standard Go4Exams value — ~12m standard deviation (matches original ±0.00011°) */
+    static readonly STANDARD: NoiseProfile;
+    /** Dense city canyon — ~25m standard deviation */
+    static readonly URBAN: NoiseProfile;
+    /** Bad conditions — ~50m standard deviation */
+    static readonly DEGRADED: NoiseProfile;
+    /**
+     * Apply noise to a coordinate.
+     * Returns a new coordinate — never mutates the input.
+     */
+    apply(coord: Coordinate$1): Coordinate$1;
+    /** Hot-swap the noise profile mid-simulation */
+    setProfile(profile: NoiseProfile): void;
+    get currentProfile(): NoiseProfile;
+    /**
+     * Box-Muller transform: produces Gaussian N(0, stdDev²) offset.
+     * Returns [lngOffset, latOffset] in degrees.
+     */
+    private _gaussianOffset;
+    /** Returns a float in [0, 1) — uses seeded RNG if available, else Math.random */
+    private _rand;
+}
+
+/**
+ * ScenarioInjector — Registers and fires Scenario objects at geometry indices.
+ *
+ * Called internally by SimulatorEngine on each tick.
+ * Also provides static factory methods for the built-in scenario types.
+ */
+
+type ScenarioFireCallback = (scenario: Scenario) => void;
+type ScenarioEndCallback = (scenario: Scenario) => void;
+declare class ScenarioInjector {
+    /** Map from triggerIndex → Scenario */
+    private readonly scenarios;
+    /** Tracks which scenarios have already fired (by name) to avoid double-fire */
+    private readonly fired;
+    /** Currently active scenario, if any */
+    private _activeScenario;
+    private _activeEndTimer;
+    private onStart;
+    private onEnd;
+    constructor(onStart?: ScenarioFireCallback, onEnd?: ScenarioEndCallback);
+    register(scenario: Scenario): void;
+    remove(name: string): void;
+    clear(): void;
+    /**
+     * Check and fire any scenario whose triggerIndex matches (or was passed) by
+     * currentIndex. Called by SimulatorEngine on every tick.
+     *
+     * Returns the name of the active scenario (if any), for metadata injection.
+     */
+    tick(currentIndex: number): string | undefined;
+    get activeScenario(): Scenario | null;
+    /** Clean up any pending timers */
+    destroy(): void;
+    /**
+     * GPS blackout: no position updates for `durationMs`.
+     * Engine handles signal loss; this scenario signals the blackout period.
+     */
+    static gpsBlackout(atIndex: number, durationMs: number): Scenario;
+    /**
+     * Wrong-side road: offset the simulated position by `offsetM` metres
+     * perpendicular to the route to stress-test the parallel road resolver.
+     */
+    static wrongSideRoad(atIndex: number, offsetM: number): Scenario;
+    /** U-turn at the given index — stress-tests U-turn protection. */
+    static uTurn(atIndex: number): Scenario;
+    /** Speed spike: briefly report spikeKmh instead of the configured speed. */
+    static speedSpike(atIndex: number, spikeKmh: number, durationMs?: number): Scenario;
+    /**
+     * Accuracy drop: GPS accuracy degrades to newAccuracyM for durationMs.
+     */
+    static accuracyDrop(atIndex: number, newAccuracyM: number, durationMs: number): Scenario;
+    private _fire;
+    private _clearActiveTimer;
+}
+
+/**
+ * GpxParser — Parse GPX 1.1 files into NavCore coordinate arrays.
+ *
+ * ZERO dependencies. Pure string/regex parsing.
+ * No DOMParser, no xml2js, no cheerio.
+ *
+ * Supports:
+ *   <trkpt> (track points — most common)
+ *   <wpt>   (waypoints)
+ */
+
+interface GpxParseResult {
+    coordinates: Coordinate$1[];
+    /** Milliseconds since epoch for each coordinate (0 if no time element) */
+    timestamps: number[];
+    metadata: {
+        name?: string;
+        /** Total number of coordinate points */
+        totalPoints: number;
+        /** Duration in ms (first to last timestamp, 0 if no timestamps) */
+        durationMs: number;
+        /** Total route distance in metres */
+        distanceM: number;
+        /** Average speed in km/h (0 if no timestamps) */
+        avgSpeedKmh: number;
+    };
+}
+declare class GpxParser {
+    /**
+     * Parse a GPX XML string into coordinates and metadata.
+     * Supports both <trkpt> and <wpt> elements.
+     */
+    static parse(gpxString: string): GpxParseResult;
+    /**
+     * Parse a base64-encoded GPX string.
+     * Works in React Native (uses atob) and Node.js (uses Buffer.from).
+     */
+    static fromBase64(base64: string): GpxParseResult;
+}
+
+/**
+ * SessionRecorder — Record and export simulation sessions.
+ *
+ * Supports JSON, GPX 1.1, and CSV export formats.
+ *
+ * The GPX export is the critical format: a session recorded in the simulator
+ * can be exported as GPX, then replayed via GpxParser on a future run.
+ * This creates a full regression test loop:
+ *   real GPS trace → gpx → GpxParser → SimulatorEngine → CI test
+ */
+
+type ExportFormat = 'json' | 'gpx' | 'csv';
+declare class SessionRecorder {
+    private _sessionId;
+    private _startedAt;
+    private _session;
+    /**
+     * Start a new recording.
+     * If the engine already has a session via startRecording(), you can pass
+     * the existing sessionId to keep IDs consistent.
+     */
+    start(sessionId?: string): void;
+    /**
+     * Stop recording and return the captured session.
+     * If called with an existing SimSession (from SimulatorEngine.stopRecording()),
+     * it stores that session for subsequent export() calls.
+     */
+    stop(existing?: SimSession): SimSession;
+    /**
+     * Export the most recent session in the specified format.
+     * Must call stop() first.
+     */
+    export(format: ExportFormat): string;
+    private static _toGpx;
+    private static _toCsv;
+}
+
+/**
+ * FleetSimulator — Phase 2 skeleton.
+ *
+ * Spawns N SimulatorEngine instances with optional per-vehicle profile
+ * overrides, runs them in parallel, and produces aggregate reports.
+ *
+ * @experimental — fully typed but not tested in Phase 1.
+ * Activate in a future iteration once SimulatorEngine is validated in CI.
+ */
+
+interface VehicleProfile extends Partial<SimulatorConfig> {
+    /** Human-readable label for this vehicle profile */
+    label?: string;
+}
+interface FleetReport {
+    vehicles: Array<{
+        id: number;
+        label: string;
+        session: SimSession;
+        profile: VehicleProfile;
+    }>;
+    comparison: {
+        /** Average stats keyed by vehicle label */
+        avgScoreByProfile: Record<string, number>;
+        /** Per-segment noise deviation across all vehicles (heatmap data) */
+        deviationsBySegment: number[];
+    };
+}
+declare class FleetSimulator {
+    private readonly engines;
+    private readonly profiles;
+    private readonly baseConfig;
+    private constructor();
+    /**
+     * Spawn N SimulatorEngine instances.
+     *
+     * @param count - number of vehicles
+     * @param config - base config (onPositionUpdate is per-vehicle, excluded here)
+     */
+    static spawn(count: number, config: Omit<SimulatorConfig, 'onPositionUpdate'> & {
+        profiles?: VehicleProfile[];
+    }): FleetSimulator;
+    /** Start all engines simultaneously */
+    start(): void;
+    /** Stop all engines */
+    stop(): void;
+    /**
+     * Get the engine at the given index.
+     * Use this for per-vehicle control (seek, setSpeed, addScenario, etc.)
+     */
+    vehicle(index: number): SimulatorEngine;
+    /**
+     * Stop all engines, collect sessions, and return an aggregate report.
+     */
+    report(): FleetReport;
+    /** Destroy all engines and clean up */
+    destroy(): void;
+}
+
+export { type Coordinate, type EngineState, type ExportFormat, type FleetReport, FleetSimulator, type GpxParseResult, GpxParser, NoiseEngine, type NoiseProfile, RouteWalker, type Scenario, ScenarioInjector, SessionRecorder, type SimLocationCoords, type SimLocationObject, type SimPosition, type SimSession, type SimulatorConfig, SimulatorEngine, type VehicleProfile, type WalkerPosition };