@ingissa/navcore-simulator 1.0.3

package/dist/core/RouteWalker.js

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ */
+import { getBearingBetweenPoints, haversineDistance, } from '@ingissa/navcore-core';
+export class RouteWalker {
+    constructor(geometry, startIndex = 0) {
+        if (geometry.length < 2) {
+            throw new Error('RouteWalker requires at least 2 geometry points');
+        }
+        this.geometry = geometry;
+        this._index = Math.max(0, Math.min(startIndex, geometry.length - 1));
+        this._isComplete = false;
+        // Pre-compute cumulative distances for O(1) distanceToIndex()
+        this._cumulativeDistances = new Array(geometry.length).fill(0);
+        for (let i = 1; i < geometry.length; i++) {
+            const a = geometry[i - 1];
+            const b = geometry[i];
+            this._cumulativeDistances[i] =
+                (this._cumulativeDistances[i - 1] ?? 0) +
+                    haversineDistance(a[1], a[0], b[1], b[0]);
+        }
+        this._distanceTravelled = this._cumulativeDistances[this._index] ?? 0;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Advance the walker by `steps` geometry points.
+     * Fractional steps are supported for sub-second precision.
+     */
+    advance(steps) {
+        if (this._isComplete)
+            return this._currentPosition();
+        this._index += steps;
+        return this._finalizeAdvance();
+    }
+    /**
+     * Advance the walker by a physical distance in metres.
+     * This is the preferred way for smooth constant-speed simulation.
+     */
+    advanceByDistance(meters) {
+        if (this._isComplete)
+            return this._currentPosition();
+        this._distanceTravelled += meters;
+        if (this._distanceTravelled >= this.totalDistanceM) {
+            this._distanceTravelled = this.totalDistanceM;
+            this._index = this.geometry.length - 1;
+            this._isComplete = true;
+        }
+        else {
+            this._index = this._distanceToIndex(this._distanceTravelled);
+        }
+        return this._currentPosition();
+    }
+    _finalizeAdvance() {
+        if (this._index >= this.geometry.length - 1) {
+            this._index = this.geometry.length - 1;
+            this._isComplete = true;
+        }
+        this._distanceTravelled = this._interpolatedDistance(this._index);
+        return this._currentPosition();
+    }
+    /**
+     * Seek directly to a geometry index (integer or fractional).
+     * Recalculates bearing from the new position.
+     */
+    seek(index) {
+        this._index = Math.max(0, Math.min(index, this.geometry.length - 1));
+        this._isComplete = this._index >= this.geometry.length - 1;
+        this._distanceTravelled = this._interpolatedDistance(this._index);
+        return this._currentPosition();
+    }
+    /**
+     * Get an interpolated coordinate between geometry[index] and geometry[index+1].
+     * @param index - integer index
+     * @param fraction - 0..1 interpolation factor
+     */
+    interpolate(index, fraction) {
+        const clampedIdx = Math.max(0, Math.min(index, this.geometry.length - 2));
+        const a = this.geometry[clampedIdx];
+        const b = this.geometry[clampedIdx + 1];
+        const f = Math.max(0, Math.min(1, fraction));
+        return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
+    }
+    /**
+     * Compute the forward-looking bearing at a given integer index.
+     * At the last point, returns the bearing of the final segment.
+     */
+    bearingAt(index) {
+        const clampedIdx = Math.max(0, Math.min(Math.floor(index), this.geometry.length - 2));
+        const a = this.geometry[clampedIdx];
+        const b = this.geometry[clampedIdx + 1];
+        return getBearingBetweenPoints(a, b);
+    }
+    /**
+     * Total haversine distance from the route start to the given index.
+     * Uses the pre-computed cumulative distances (O(1)).
+     */
+    distanceAtIndex(index) {
+        const clampedIdx = Math.max(0, Math.min(Math.floor(index), this.geometry.length - 1));
+        return this._cumulativeDistances[clampedIdx] ?? 0;
+    }
+    distanceToIndex(index) {
+        return this.distanceAtIndex(index);
+    }
+    /**
+     * Convert a distance in metres back to a fractional index.
+     * Uses binary search for O(log N) performance.
+     */
+    _distanceToIndex(targetDistance) {
+        if (targetDistance <= 0)
+            return 0;
+        if (targetDistance >= this.totalDistanceM)
+            return this.geometry.length - 1;
+        // Binary search for the segment [i, i+1] containing targetDistance
+        let low = 0;
+        let high = this._cumulativeDistances.length - 1;
+        let i = 0;
+        while (low <= high) {
+            const mid = Math.floor((low + high) / 2);
+            if (this._cumulativeDistances[mid] <= targetDistance) {
+                i = mid;
+                low = mid + 1;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        // Now targetDistance is between i and i+1
+        const dStart = this._cumulativeDistances[i];
+        const dEnd = this._cumulativeDistances[i + 1];
+        const segmentDist = dEnd - dStart;
+        if (segmentDist <= 0)
+            return i;
+        const fraction = (targetDistance - dStart) / segmentDist;
+        return i + fraction;
+    }
+    // ── Readonly state ──────────────────────────────────────────────────────────
+    get totalDistanceM() {
+        return this._cumulativeDistances[this.geometry.length - 1] ?? 0;
+    }
+    get totalPoints() {
+        return this.geometry.length;
+    }
+    get isComplete() {
+        return this._isComplete;
+    }
+    get currentIndex() {
+        return this._index;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    _currentPosition() {
+        const floorIdx = Math.min(Math.floor(this._index), this.geometry.length - 2);
+        const fraction = this._index - floorIdx;
+        const coord = this.interpolate(floorIdx, fraction);
+        const bearing = this.bearingAt(floorIdx);
+        return {
+            index: this._index,
+            coord,
+            bearing,
+            distanceTravelled: this._distanceTravelled,
+            isComplete: this._isComplete,
+        };
+    }
+    /** Interpolate cumulative distance for fractional index */
+    _interpolatedDistance(index) {
+        const floor = Math.min(Math.floor(index), this.geometry.length - 1);
+        const ceil = Math.min(floor + 1, this.geometry.length - 1);
+        const fraction = index - floor;
+        const dFloor = this._cumulativeDistances[floor] ?? 0;
+        const dCeil = this._cumulativeDistances[ceil] ?? 0;
+        return dFloor + (dCeil - dFloor) * fraction;
+    }
+}

package/dist/core/SimulatorEngine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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
+ */
+import type { SimPosition, SimulatorConfig, SimSession, Scenario } from './types';
+export type EngineState = 'idle' | 'running' | 'paused' | 'complete';
+export 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;
+}
+//# sourceMappingURL=SimulatorEngine.d.ts.map

package/dist/core/SimulatorEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimulatorEngine.d.ts","sourceRoot":"","sources":["../../src/core/SimulatorEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAWlF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErE,qBAAa,eAAe;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAEiF;IAGxG,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,QAAQ,CAAmB;IAGnC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,SAAS,CAAa;IAE9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAM;IAGrC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,kBAAkB,CAAsD;IAChF,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,MAAM,EAAE,eAAe;IA4CnC,KAAK,IAAI,IAAI;IAOb,IAAI,IAAI,IAAI;IAMZ,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IAMd;;;OAGG;IACH,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAkBjC,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI;IAOzC,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAIrC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC,cAAc,IAAI,IAAI;IAMtB,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,IAAI,QAAQ,IAAI,WAAW,GAAG,IAAI,CAEjC;IAED,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAID,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IASxC,aAAa,IAAI,UAAU;IAqC3B,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,KAAK;IA+Db,OAAO,CAAC,qBAAqB;CAqC9B"}

package/dist/core/SimulatorEngine.js

@@ -0,0 +1,283 @@
+/**
+ * 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
+ */
+import { NoiseEngine } from './NoiseEngine';
+import { RouteWalker } from './RouteWalker';
+import { ScenarioInjector } from '../scenarios/ScenarioInjector';
+/** Generate a UUID v4 without external dependencies */
+function uuidV4() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export class SimulatorEngine {
+    constructor(config) {
+        // ── State ────────────────────────────────────────────────────────────────────
+        this._state = 'idle';
+        this._position = null;
+        this._timer = null;
+        this._lastTick = 0;
+        // ── Recording ────────────────────────────────────────────────────────────────
+        this._recording = false;
+        this._recordedPositions = [];
+        this._recordedScenarios = [];
+        this._sessionId = null;
+        this._sessionStart = null;
+        this._noiseSamplesAdded = 0;
+        const geometry = config.routeGeometry;
+        if (!geometry || geometry.length < 2) {
+            throw new Error('SimulatorEngine: routeGeometry must have at least 2 points');
+        }
+        this._speedMultiplier = config.speedMultiplier ?? 1;
+        this.config = {
+            routeGeometry: geometry,
+            speedKmh: config.speedKmh ?? 50,
+            speedMultiplier: this._speedMultiplier,
+            noiseProfile: config.noiseProfile ?? NoiseEngine.STANDARD,
+            loop: config.loop ?? false,
+            startIndex: config.startIndex ?? 0,
+            autoStart: config.autoStart ?? false,
+            onPositionUpdate: config.onPositionUpdate,
+            onRouteComplete: config.onRouteComplete,
+            onScenarioStart: config.onScenarioStart,
+            onScenarioEnd: config.onScenarioEnd,
+        };
+        this.walker = new RouteWalker(geometry, this.config.startIndex);
+        this.noise = new NoiseEngine(this.config.noiseProfile);
+        this.injector = new ScenarioInjector((s) => {
+            if (this._recording) {
+                this._recordedScenarios.push({ scenario: s, firedAt: Date.now() });
+            }
+            try {
+                this.config.onScenarioStart?.(s);
+            }
+            catch (_) { /* never throw */ }
+        }, (s) => {
+            try {
+                this.config.onScenarioEnd?.(s);
+            }
+            catch (_) { /* never throw */ }
+        });
+        if (this.config.autoStart) {
+            this.start();
+        }
+    }
+    // ── Playback controls ────────────────────────────────────────────────────────
+    start() {
+        if (this._state === 'running')
+            return;
+        if (this._state === 'complete')
+            return;
+        this._state = 'running';
+        this._startTimer();
+    }
+    stop() {
+        this._stopTimer();
+        this._state = 'idle';
+        this._position = null;
+    }
+    pause() {
+        if (this._state !== 'running')
+            return;
+        this._stopTimer();
+        this._state = 'paused';
+    }
+    resume() {
+        if (this._state !== 'paused')
+            return;
+        this._state = 'running';
+        this._startTimer();
+    }
+    /**
+     * Jump to any geometry index.
+     * Bearing is recalculated from the new segment — seek() is always bearing-safe.
+     */
+    seek(geometryIndex) {
+        const wasRunning = this._state === 'running';
+        if (wasRunning)
+            this._stopTimer();
+        const pos = this.walker.seek(geometryIndex);
+        this._buildAndEmitPosition(pos.coord, pos.bearing, pos.distanceTravelled, false);
+        // Reset the completion flag so simulation can continue from the new index
+        if (this._state === 'complete' && !pos.isComplete) {
+            this._state = 'idle';
+        }
+        if (wasRunning && !pos.isComplete) {
+            this._state = 'running';
+            this._startTimer();
+        }
+    }
+    setSpeed(multiplier) {
+        this._speedMultiplier = multiplier;
+        // No need to restart timer anymore as it's a fixed frequency
+    }
+    // ── Scenario management ──────────────────────────────────────────────────────
+    addScenario(scenario) {
+        this.injector.register(scenario);
+    }
+    removeScenario(name) {
+        this.injector.remove(name);
+    }
+    clearScenarios() {
+        this.injector.clear();
+    }
+    // ── State accessors ──────────────────────────────────────────────────────────
+    get state() {
+        return this._state;
+    }
+    get position() {
+        return this._position;
+    }
+    get progress() {
+        if (this.walker.totalPoints <= 1)
+            return 0;
+        return Math.min(1, this.walker.currentIndex / (this.walker.totalPoints - 1));
+    }
+    // ── Session recording ────────────────────────────────────────────────────────
+    startRecording(sessionId) {
+        this._recording = true;
+        this._recordedPositions = [];
+        this._recordedScenarios = [];
+        this._sessionId = sessionId ?? uuidV4();
+        this._sessionStart = Date.now();
+        this._noiseSamplesAdded = 0;
+    }
+    stopRecording() {
+        this._recording = false;
+        const endedAt = Date.now();
+        const startedAt = this._sessionStart ?? endedAt;
+        const positions = this._recordedPositions;
+        const durationMs = endedAt - startedAt;
+        let distanceTravelledM = 0;
+        if (positions.length > 0) {
+            distanceTravelledM = positions[positions.length - 1]?.metadata?.distanceTravelled ?? 0;
+        }
+        const avgSpeedKmh = durationMs > 0
+            ? ((distanceTravelledM / (durationMs / 1000)) * 3.6)
+            : 0;
+        return {
+            id: this._sessionId ?? uuidV4(),
+            startedAt: new Date(startedAt).toISOString(),
+            endedAt: new Date(endedAt).toISOString(),
+            route: this.config.routeGeometry,
+            positions,
+            scenarios: this._recordedScenarios,
+            stats: {
+                durationMs,
+                distanceTravelledM,
+                avgSpeedKmh,
+                noiseSamplesAdded: this._noiseSamplesAdded,
+                scenariosFired: this._recordedScenarios.length,
+            },
+        };
+    }
+    // ── Destroy ──────────────────────────────────────────────────────────────────
+    destroy() {
+        this._stopTimer();
+        this.injector.destroy();
+        this._state = 'idle';
+        this._position = null;
+        this._recording = false;
+        this._recordedPositions = [];
+    }
+    // ── Private ──────────────────────────────────────────────────────────────────
+    _startTimer() {
+        this._lastTick = Date.now();
+        this._timer = setInterval(() => this._tick(), SimulatorEngine.TICK_MS);
+    }
+    _stopTimer() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+    _tick() {
+        if (this._state !== 'running')
+            return;
+        const now = Date.now();
+        const deltaMs = now - this._lastTick;
+        this._lastTick = now;
+        // Calculate physical distance to move in this tick
+        // meters = (km/h / 3.6) * seconds * multiplier
+        const speedMs = (this.config.speedKmh / 3.6);
+        const distanceToMove = speedMs * (deltaMs / 1000) * this._speedMultiplier;
+        const walkerPos = this.walker.advanceByDistance(distanceToMove);
+        // Fire any scenarios at this index
+        const activeScenarioName = this.injector.tick(walkerPos.index);
+        // Apply noise (skip if GPS_BLACKOUT scenario is active)
+        const activeScenario = this.injector.activeScenario;
+        let coord = walkerPos.coord;
+        let isNoisy = false;
+        if (activeScenario?.type !== 'GPS_BLACKOUT') {
+            coord = this.noise.apply(walkerPos.coord);
+            isNoisy = this.noise.currentProfile.stdDevM > 0;
+            if (isNoisy)
+                this._noiseSamplesAdded++;
+        }
+        // Compute speed — apply speed spike if active
+        //let speedMs = (this.config.speedKmh / 3.6);
+        if (activeScenario?.type === 'SPEED_SPIKE') {
+            const spikeKmh = activeScenario.params?.['spikeKmh'] ?? this.config.speedKmh;
+            //speedMs = spikeKmh / 3.6;
+        }
+        // Compute accuracy — degrade if ACCURACY_DROP scenario is active
+        let accuracy = 8 + Math.random() * 6;
+        if (activeScenario?.type === 'ACCURACY_DROP') {
+            accuracy = activeScenario.params?.['newAccuracyM'] ?? accuracy;
+        }
+        this._buildAndEmitPosition(coord, walkerPos.bearing, walkerPos.distanceTravelled, isNoisy, {
+            speedMs,
+            accuracy,
+            activeScenarioName,
+            segmentIndex: Math.floor(walkerPos.index),
+        });
+        if (walkerPos.isComplete) {
+            this._stopTimer();
+            if (this.config.loop) {
+                // Restart from the beginning
+                this.walker = new RouteWalker(this.config.routeGeometry, 0);
+                this._startTimer();
+            }
+            else {
+                this._state = 'complete';
+            }
+            try {
+                this.config.onRouteComplete?.();
+            }
+            catch (_) { /* never throw */ }
+        }
+    }
+    _buildAndEmitPosition(coord, bearing, distanceTravelled, isNoisy, opts) {
+        const speedMs = opts?.speedMs ?? (this.config.speedKmh / 3.6);
+        const accuracy = opts?.accuracy ?? 8;
+        const pos = {
+            coord: coord,
+            bearing,
+            speed: speedMs,
+            accuracy,
+            timestamp: Date.now(),
+            metadata: {
+                segmentIndex: opts?.segmentIndex ?? Math.floor(this.walker.currentIndex),
+                distanceTravelled,
+                isNoisy,
+                scenarioActive: opts?.activeScenarioName,
+            },
+        };
+        this._position = pos;
+        if (this._recording) {
+            this._recordedPositions.push(pos);
+        }
+        try {
+            this.config.onPositionUpdate?.(pos);
+        }
+        catch (_) { /* never throw */ }
+    }
+}
+SimulatorEngine.TICK_MS = 50; // 20 FPS for smooth movement

package/dist/core/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @navcore/simulator — Core Types
+ *
+ * These types are the foundation of the entire simulator package.
+ * All other modules build on top of these definitions.
+ */
+export type Coordinate = [number, number];
+/**
+ * A single simulated GPS position, emitted by SimulatorEngine on every tick.
+ * Shape is intentionally identical to the current inline SimPosition in
+ * NavCoreTestScreen so that migration is a search-and-replace.
+ */
+export 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;
+    /** 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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().
+ */
+export 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;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAI1C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE;QACT,yDAAyD;QACzD,YAAY,EAAE,MAAM,CAAC;QACrB,8CAA8C;QAC9C,iBAAiB,EAAE,MAAM,CAAC;QAC1B,6CAA6C;QAC7C,OAAO,EAAE,OAAO,CAAC;QACjB,0CAA0C;QAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAID;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1D,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAID;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,IAAI,EACA,cAAc,GACd,iBAAiB,GACjB,OAAO,GACP,aAAa,GACb,eAAe,GACf,QAAQ,CAAC;IACb,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAID;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAE9B,2CAA2C;IAC3C,aAAa,EAAE,UAAU,EAAE,CAAC;IAG5B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAGhC,2EAA2E;IAC3E,YAAY,CAAC,EAAE,YAAY,CAAC;IAG5B,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IAGpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IAC9C,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B,oCAAoC;IACpC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC/C,kCAAkC;IAClC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CAC9C;AAID;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,uDAAuD;IACvD,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,QAAQ,CAAC;QACnB,sCAAsC;QACtC,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,4CAA4C;IAC5C,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH"}

package/dist/core/types.js

@@ -0,0 +1,7 @@
+/**
+ * @navcore/simulator — Core Types
+ *
+ * These types are the foundation of the entire simulator package.
+ * All other modules build on top of these definitions.
+ */
+export {};