@ingissa/navcore-simulator 1.0.8 → 1.0.10

package/dist/node.mjs

@@ -0,0 +1,949 @@
+import { haversineDistance, getBearingBetweenPoints } from '@ingissa/navcore-core';
+
+// src/core/NoiseEngine.ts
+var LAT_DEG_PER_M = 1 / 110540;
+var LNG_DEG_PER_M = 1 / 111320;
+var SeededRandom = class {
+  constructor(seed) {
+    this.state = seed >>> 0;
+  }
+  /** Returns a float in [0, 1) */
+  next() {
+    this.state = Math.imul(1664525, this.state) + 1013904223 >>> 0;
+    return this.state / 4294967296;
+  }
+};
+var NoiseEngine = class {
+  constructor(profile) {
+    this._tickIndex = 0;
+    this.profile = profile;
+    this.rng = profile.seed !== void 0 ? new SeededRandom(profile.seed) : null;
+  }
+  // ── Public API ─────────────────────────────────────────────────────────────
+  /**
+   * Apply noise to a coordinate.
+   * Returns a new coordinate — never mutates the input.
+   */
+  apply(coord) {
+    const idx = this._tickIndex++;
+    switch (this.profile.type) {
+      case "NONE":
+        return coord;
+      case "GAUSSIAN":
+      case "URBAN": {
+        const [dLng, dLat] = this._gaussianOffset(this.profile.stdDevM);
+        return [coord[0] + dLng, coord[1] + dLat];
+      }
+      case "TUNNEL":
+        return coord;
+      case "CUSTOM": {
+        if (!this.profile.customFn) return coord;
+        const [lngOff, latOff] = this.profile.customFn(idx);
+        return [coord[0] + lngOff, coord[1] + latOff];
+      }
+      default:
+        return coord;
+    }
+  }
+  /** Hot-swap the noise profile mid-simulation */
+  setProfile(profile) {
+    this.profile = profile;
+    this.rng = profile.seed !== void 0 ? new SeededRandom(profile.seed) : null;
+    this._tickIndex = 0;
+  }
+  get currentProfile() {
+    return this.profile;
+  }
+  // ── Private helpers ─────────────────────────────────────────────────────────
+  /**
+   * Box-Muller transform: produces Gaussian N(0, stdDev²) offset.
+   * Returns [lngOffset, latOffset] in degrees.
+   */
+  _gaussianOffset(stdDevM) {
+    if (stdDevM === 0) return [0, 0];
+    const u1 = this._rand();
+    const u2 = this._rand();
+    const mag = stdDevM * Math.sqrt(-2 * Math.log(Math.max(u1, 1e-10)));
+    const z0 = mag * Math.cos(2 * Math.PI * u2);
+    const z1 = mag * Math.sin(2 * Math.PI * u2);
+    return [z0 * LNG_DEG_PER_M, z1 * LAT_DEG_PER_M];
+  }
+  /** Returns a float in [0, 1) — uses seeded RNG if available, else Math.random */
+  _rand() {
+    return this.rng ? this.rng.next() : Math.random();
+  }
+};
+// ── Static presets ─────────────────────────────────────────────────────────
+/** No noise — returns the exact coordinate */
+NoiseEngine.NONE = { type: "NONE", stdDevM: 0 };
+/** Good urban GPS — ~3m standard deviation */
+NoiseEngine.CLEAN = { type: "GAUSSIAN", stdDevM: 3 };
+/** Standard Go4Exams value — ~12m standard deviation (matches original ±0.00011°) */
+NoiseEngine.STANDARD = { type: "GAUSSIAN", stdDevM: 12 };
+/** Dense city canyon — ~25m standard deviation */
+NoiseEngine.URBAN = { type: "URBAN", stdDevM: 25 };
+/** Bad conditions — ~50m standard deviation */
+NoiseEngine.DEGRADED = { type: "GAUSSIAN", stdDevM: 50 };
+var RouteWalker = class {
+  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;
+    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;
+  }
+  /**
+   * Alias for distanceAtIndex.
+   */
+  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;
+    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;
+      }
+    }
+    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;
+  }
+};
+
+// src/scenarios/ScenarioInjector.ts
+var ScenarioInjector = class {
+  constructor(onStart, onEnd) {
+    /** Map from triggerIndex → Scenario */
+    this.scenarios = /* @__PURE__ */ new Map();
+    /** Tracks which scenarios have already fired (by name) to avoid double-fire */
+    this.fired = /* @__PURE__ */ new Set();
+    /** Currently active scenario, if any */
+    this._activeScenario = null;
+    this._activeEndTimer = null;
+    this.onStart = onStart ?? (() => void 0);
+    this.onEnd = onEnd ?? (() => void 0);
+  }
+  // ── Registration ────────────────────────────────────────────────────────────
+  register(scenario) {
+    this.scenarios.set(scenario.triggerIndex, scenario);
+  }
+  remove(name) {
+    for (const [idx, s] of this.scenarios) {
+      if (s.name === name) {
+        this.scenarios.delete(idx);
+        break;
+      }
+    }
+  }
+  clear() {
+    this.scenarios.clear();
+    this.fired.clear();
+    this._clearActiveTimer();
+    this._activeScenario = null;
+  }
+  // ── Tick ────────────────────────────────────────────────────────────────────
+  /**
+   * 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) {
+    const floorIdx = Math.floor(currentIndex);
+    for (const [triggerIdx, scenario] of this.scenarios) {
+      if (floorIdx >= triggerIdx && !this.fired.has(scenario.name)) {
+        this.fired.add(scenario.name);
+        this._fire(scenario);
+      }
+    }
+    return this._activeScenario?.name;
+  }
+  get activeScenario() {
+    return this._activeScenario;
+  }
+  /** Clean up any pending timers */
+  destroy() {
+    this._clearActiveTimer();
+  }
+  // ── Static factories ────────────────────────────────────────────────────────
+  /**
+   * GPS blackout: no position updates for `durationMs`.
+   * Engine handles signal loss; this scenario signals the blackout period.
+   */
+  static gpsBlackout(atIndex, durationMs) {
+    return {
+      name: `gps-blackout-@${atIndex}`,
+      triggerIndex: atIndex,
+      type: "GPS_BLACKOUT",
+      durationMs,
+      params: { durationMs }
+    };
+  }
+  /**
+   * Wrong-side road: offset the simulated position by `offsetM` metres
+   * perpendicular to the route to stress-test the parallel road resolver.
+   */
+  static wrongSideRoad(atIndex, offsetM) {
+    return {
+      name: `wrong-side-@${atIndex}`,
+      triggerIndex: atIndex,
+      type: "WRONG_SIDE_ROAD",
+      params: { offsetM }
+    };
+  }
+  /** U-turn at the given index — stress-tests U-turn protection. */
+  static uTurn(atIndex) {
+    return {
+      name: `uturn-@${atIndex}`,
+      triggerIndex: atIndex,
+      type: "UTURN",
+      params: {}
+    };
+  }
+  /** Speed spike: briefly report spikeKmh instead of the configured speed. */
+  static speedSpike(atIndex, spikeKmh, durationMs = 2e3) {
+    return {
+      name: `speed-spike-@${atIndex}`,
+      triggerIndex: atIndex,
+      type: "SPEED_SPIKE",
+      durationMs,
+      params: { spikeKmh }
+    };
+  }
+  /**
+   * Accuracy drop: GPS accuracy degrades to newAccuracyM for durationMs.
+   */
+  static accuracyDrop(atIndex, newAccuracyM, durationMs) {
+    return {
+      name: `accuracy-drop-@${atIndex}`,
+      triggerIndex: atIndex,
+      type: "ACCURACY_DROP",
+      durationMs,
+      params: { newAccuracyM }
+    };
+  }
+  // ── Private ─────────────────────────────────────────────────────────────────
+  _fire(scenario) {
+    this._activeScenario = scenario;
+    try {
+      this.onStart(scenario);
+    } catch (_) {
+    }
+    if (scenario.durationMs != null && scenario.durationMs > 0) {
+      this._clearActiveTimer();
+      this._activeEndTimer = setTimeout(() => {
+        this._activeScenario = null;
+        try {
+          this.onEnd(scenario);
+        } catch (_) {
+        }
+      }, scenario.durationMs);
+    } else {
+      this._activeScenario = null;
+      try {
+        this.onEnd(scenario);
+      } catch (_) {
+      }
+    }
+  }
+  _clearActiveTimer() {
+    if (this._activeEndTimer !== null) {
+      clearTimeout(this._activeEndTimer);
+      this._activeEndTimer = null;
+    }
+  }
+};
+
+// src/core/SimulatorEngine.ts
+function uuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var SimulatorEngine = class {
+  constructor(config) {
+    // ── State ────────────────────────────────────────────────────────────────────
+    this._state = "idle";
+    this._position = null;
+    this._timer = null;
+    this._lastTick = 0;
+    // 20 FPS for smooth movement
+    // ── 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 (_) {
+        }
+      },
+      (s) => {
+        try {
+          this.config.onScenarioEnd?.(s);
+        } catch (_) {
+        }
+      }
+    );
+    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);
+    if (this._state === "complete" && !pos.isComplete) {
+      this._state = "idle";
+    }
+    if (wasRunning && !pos.isComplete) {
+      this._state = "running";
+      this._startTimer();
+    }
+  }
+  setSpeed(multiplier) {
+    this._speedMultiplier = multiplier;
+    if (this._state === "running") {
+      this._stopTimer();
+      this._startTimer();
+    }
+  }
+  // ── 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 / 1e3) * 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();
+    const intervalMs = Math.round(1e3 / this._speedMultiplier);
+    this._timer = setInterval(() => this._tick(), intervalMs);
+  }
+  _stopTimer() {
+    if (this._timer !== null) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+  _tick() {
+    if (this._state !== "running") return;
+    const now = Date.now();
+    this._lastTick = now;
+    const speedMs = this.config.speedKmh / 3.6;
+    const walkerPos = this.walker.advance(1);
+    const activeScenarioName = this.injector.tick(walkerPos.index);
+    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++;
+    }
+    if (activeScenario?.type === "SPEED_SPIKE") {
+      activeScenario.params?.["spikeKmh"] ?? this.config.speedKmh;
+    }
+    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) {
+        this.walker = new RouteWalker(this.config.routeGeometry, 0);
+        this._startTimer();
+      } else {
+        this._state = "complete";
+      }
+      try {
+        this.config.onRouteComplete?.();
+      } catch (_) {
+      }
+    }
+  }
+  _buildAndEmitPosition(coord, bearing, distanceTravelled, isNoisy, opts) {
+    const speedMs = opts?.speedMs ?? this.config.speedKmh / 3.6;
+    const accuracy = opts?.accuracy ?? 8;
+    const ts = Date.now();
+    const locationCoords = {
+      latitude: coord[1],
+      longitude: coord[0],
+      altitude: 0,
+      accuracy,
+      altitudeAccuracy: null,
+      heading: bearing,
+      speed: speedMs
+    };
+    const pos = {
+      coord,
+      bearing,
+      speed: speedMs,
+      accuracy,
+      timestamp: ts,
+      coords: locationCoords,
+      location: {
+        coords: locationCoords,
+        timestamp: ts
+      },
+      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 (_) {
+    }
+  }
+};
+SimulatorEngine.TICK_MS = 50;
+var GpxParser = class _GpxParser {
+  /**
+   * Parse a GPX XML string into coordinates and metadata.
+   * Supports both <trkpt> and <wpt> elements.
+   */
+  static parse(gpxString) {
+    const coordinates = [];
+    const timestamps = [];
+    const pointRegex = /<(?:trkpt|wpt)\s+([^>]+)>([\s\S]*?)<\/(?:trkpt|wpt)>/g;
+    const latLonRegex = /lat="([^"]+)"/;
+    const lonRegex = /lon="([^"]+)"/;
+    const timeRegex = /<time>([^<]+)<\/time>/;
+    let match;
+    while ((match = pointRegex.exec(gpxString)) !== null) {
+      const attrs = match[1] ?? "";
+      const body = match[2] ?? "";
+      const latMatch = latLonRegex.exec(attrs);
+      const lonMatch = lonRegex.exec(attrs);
+      if (!latMatch || !lonMatch) continue;
+      const lat = parseFloat(latMatch[1] ?? "0");
+      const lon = parseFloat(lonMatch[1] ?? "0");
+      if (isNaN(lat) || isNaN(lon)) continue;
+      coordinates.push([lon, lat]);
+      const timeMatch = timeRegex.exec(body);
+      if (timeMatch) {
+        const ms = Date.parse(timeMatch[1] ?? "");
+        timestamps.push(isNaN(ms) ? 0 : ms);
+      } else {
+        timestamps.push(0);
+      }
+    }
+    const nameMatch = /<name>([^<]+)<\/name>/.exec(gpxString);
+    const name = nameMatch ? nameMatch[1]?.trim() : void 0;
+    let distanceM = 0;
+    for (let i = 1; i < coordinates.length; i++) {
+      const a = coordinates[i - 1];
+      const b = coordinates[i];
+      distanceM += haversineDistance(a[1], a[0], b[1], b[0]);
+    }
+    const validTs = timestamps.filter((t) => t > 0);
+    let durationMs = 0;
+    let avgSpeedKmh = 0;
+    if (validTs.length >= 2) {
+      durationMs = (validTs[validTs.length - 1] ?? 0) - (validTs[0] ?? 0);
+      if (durationMs > 0) {
+        const speedMs = distanceM / (durationMs / 1e3);
+        avgSpeedKmh = speedMs * 3.6;
+      }
+    }
+    return {
+      coordinates,
+      timestamps,
+      metadata: {
+        name,
+        totalPoints: coordinates.length,
+        durationMs,
+        distanceM,
+        avgSpeedKmh
+      }
+    };
+  }
+  /**
+   * Parse a base64-encoded GPX string.
+   * Works in React Native (uses atob) and Node.js (uses Buffer.from).
+   */
+  static fromBase64(base64) {
+    let decoded;
+    if (typeof atob !== "undefined") {
+      decoded = atob(base64);
+    } else {
+      decoded = Buffer.from(base64, "base64").toString("utf-8");
+    }
+    return _GpxParser.parse(decoded);
+  }
+};
+
+// src/replay/SessionRecorder.ts
+function uuidV42() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var SessionRecorder = class _SessionRecorder {
+  constructor() {
+    this._sessionId = null;
+    this._startedAt = null;
+    this._session = null;
+  }
+  /**
+   * 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) {
+    this._sessionId = sessionId ?? uuidV42();
+    this._startedAt = Date.now();
+    this._session = null;
+  }
+  /**
+   * 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) {
+    if (existing) {
+      this._session = existing;
+      return existing;
+    }
+    const session = {
+      id: this._sessionId ?? uuidV42(),
+      startedAt: new Date(this._startedAt ?? Date.now()).toISOString(),
+      endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      route: [],
+      positions: [],
+      scenarios: [],
+      stats: {
+        durationMs: Date.now() - (this._startedAt ?? Date.now()),
+        distanceTravelledM: 0,
+        avgSpeedKmh: 0,
+        noiseSamplesAdded: 0,
+        scenariosFired: 0
+      }
+    };
+    this._session = session;
+    return session;
+  }
+  /**
+   * Export the most recent session in the specified format.
+   * Must call stop() first.
+   */
+  export(format) {
+    const session = this._session;
+    if (!session) throw new Error("SessionRecorder: call stop() before export()");
+    switch (format) {
+      case "json":
+        return JSON.stringify(session, null, 2);
+      case "gpx":
+        return _SessionRecorder._toGpx(session);
+      case "csv":
+        return _SessionRecorder._toCsv(session);
+      default:
+        throw new Error(`SessionRecorder: unknown format "${format}"`);
+    }
+  }
+  // ── Static export helpers ───────────────────────────────────────────────────
+  static _toGpx(session) {
+    const trkpts = session.positions.map((p) => {
+      const time = new Date(p.timestamp).toISOString();
+      return `    <trkpt lat="${p.coord[1]}" lon="${p.coord[0]}">
+      <time>${time}</time>
+      <extensions>
+        <speed>${p.speed.toFixed(4)}</speed>
+        <bearing>${p.bearing.toFixed(4)}</bearing>
+        <accuracy>${p.accuracy.toFixed(2)}</accuracy>
+      </extensions>
+    </trkpt>`;
+    }).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<gpx version="1.1" creator="@ingissa/navcore-simulator"
+     xmlns="http://www.topografix.com/GPX/1/1"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
+  <metadata>
+    <name>${session.id}</name>
+    <time>${session.startedAt}</time>
+  </metadata>
+  <trk>
+    <name>${session.id}</name>
+    <trkseg>
+` + trkpts + `
+    </trkseg>
+  </trk>
+</gpx>`;
+  }
+  static _toCsv(session) {
+    const header = "timestamp,lng,lat,bearing,speed,accuracy";
+    const rows = session.positions.map(
+      (p) => `${p.timestamp},${p.coord[0]},${p.coord[1]},${p.bearing.toFixed(4)},${p.speed.toFixed(4)},${p.accuracy.toFixed(2)}`
+    );
+    return [header, ...rows].join("\n");
+  }
+};
+
+// src/fleet/FleetSimulator.ts
+var FleetSimulator = class _FleetSimulator {
+  constructor(engines, profiles, baseConfig) {
+    this.engines = engines;
+    this.profiles = profiles;
+    this.baseConfig = baseConfig;
+  }
+  /**
+   * Spawn N SimulatorEngine instances.
+   *
+   * @param count - number of vehicles
+   * @param config - base config (onPositionUpdate is per-vehicle, excluded here)
+   */
+  static spawn(count, config) {
+    const { profiles = [], ...baseConfig } = config;
+    const engines = [];
+    const resolvedProfiles = [];
+    for (let i = 0; i < count; i++) {
+      const profile = profiles[i] ?? {};
+      resolvedProfiles.push(profile);
+      const engine = new SimulatorEngine({
+        ...baseConfig,
+        ...profile,
+        onPositionUpdate: void 0
+      });
+      engines.push(engine);
+    }
+    return new _FleetSimulator(engines, resolvedProfiles, baseConfig);
+  }
+  /** Start all engines simultaneously */
+  start() {
+    for (const engine of this.engines) {
+      engine.startRecording();
+      engine.start();
+    }
+  }
+  /** Stop all engines */
+  stop() {
+    for (const engine of this.engines) {
+      engine.stop();
+    }
+  }
+  /**
+   * Get the engine at the given index.
+   * Use this for per-vehicle control (seek, setSpeed, addScenario, etc.)
+   */
+  vehicle(index) {
+    const engine = this.engines[index];
+    if (!engine) throw new Error(`FleetSimulator: no vehicle at index ${index}`);
+    return engine;
+  }
+  /**
+   * Stop all engines, collect sessions, and return an aggregate report.
+   */
+  report() {
+    const vehicleReports = this.engines.map((engine, i) => {
+      const session = engine.stopRecording();
+      const profile = this.profiles[i] ?? {};
+      return {
+        id: i,
+        label: profile.label ?? `vehicle-${i}`,
+        session,
+        profile
+      };
+    });
+    const avgScoreByProfile = {};
+    for (const v of vehicleReports) {
+      const key = v.label;
+      const existing = avgScoreByProfile[key];
+      if (existing === void 0) {
+        avgScoreByProfile[key] = v.session.stats.avgSpeedKmh;
+      } else {
+        avgScoreByProfile[key] = (existing + v.session.stats.avgSpeedKmh) / 2;
+      }
+    }
+    const segmentCount = this.baseConfig.routeGeometry.length;
+    const deviationsBySegment = new Array(segmentCount).fill(0);
+    for (const v of vehicleReports) {
+      for (const pos of v.session.positions) {
+        const segIdx = pos.metadata?.segmentIndex ?? 0;
+        if (segIdx < segmentCount) {
+          deviationsBySegment[segIdx] = (deviationsBySegment[segIdx] ?? 0) + pos.accuracy;
+        }
+      }
+    }
+    for (let i = 0; i < deviationsBySegment.length; i++) {
+      deviationsBySegment[i] = (deviationsBySegment[i] ?? 0) / Math.max(1, vehicleReports.length);
+    }
+    return {
+      vehicles: vehicleReports,
+      comparison: { avgScoreByProfile, deviationsBySegment }
+    };
+  }
+  /** Destroy all engines and clean up */
+  destroy() {
+    for (const engine of this.engines) {
+      engine.destroy();
+    }
+  }
+};
+
+export { FleetSimulator, GpxParser, NoiseEngine, RouteWalker, ScenarioInjector, SessionRecorder, SimulatorEngine };