@ingissa/navcore-simulator 1.0.8 → 1.0.9

package/src/react-native/useSimulator.ts

@@ -1,155 +0,0 @@
-/**
- * useSimulator — React Native hook wrapping SimulatorEngine.
- *
- * Drop-in replacement for useGpsSimulator.
- * All engine logic lives in SimulatorEngine — this hook is purely a thin
- * React adapter with no business logic of its own.
- *
- * BEFORE (current Go4Exams code):
- *   const simGps = useGpsSimulator(route, isNavigating, speedMultiplier)
- *
- * AFTER:
- *   const { position, controls, session, isRecording } = useSimulator({
- *     routeGeometry: route,
- *     active: isNavigating,
- *     config: { speedKmh: 50, noiseProfile: NoiseEngine.STANDARD },
- *   })
- */
-
-import { useEffect, useRef, useState, useCallback } from 'react';
-import { SimulatorEngine } from '../core/SimulatorEngine';
-import { NoiseEngine } from '../core/NoiseEngine';
-import type { SimPosition, SimulatorConfig, SimSession, Scenario, SimLocationObject } from '../core/types';
-import type { Coordinate } from '@ingissa/navcore-core';
-
-export interface UseSimulatorOptions {
-  /** Route geometry to simulate along */
-  routeGeometry: Coordinate[] | null;
-  /** Whether the simulation should be active */
-  active: boolean;
-  /** Engine configuration (all fields optional) */
-  config?: Partial<Omit<SimulatorConfig, 'routeGeometry' | 'onPositionUpdate' | 'onRouteComplete'>>;
-  /** Pre-registered scenarios */
-  scenarios?: Scenario[];
-  /** Called when a scenario fires */
-  onScenarioFired?: (scenario: Scenario) => void;
-  /** Called when the route simulation finishes */
-  onRouteComplete?: () => void;
-}
-
-export interface SimulatorControls {
-  pause: () => void;
-  resume: () => void;
-  seek: (geometryIndex: number) => void;
-  setSpeed: (multiplier: 1 | 2 | 4 | 8) => void;
-}
-
-export interface SessionControls {
-  start: (sessionId?: string) => void;
-  stop: () => SimSession | null;
-}
-
-export interface UseSimulatorResult {
-  /** Current simulated position — null when inactive */
-  position: SimPosition | null;
-  /** Conforms to Expo LocationObject (null when inactive) */
-  location: SimLocationObject | null;
-  /** Alias for location conforming to Expo LocationObject */
-  rawLocation: SimLocationObject | null;
-  /** Playback controls */
-  controls: SimulatorControls;
-  /** Recording controls */
-  session: SessionControls;
-  /** Whether a recording is in progress */
-  isRecording: boolean;
-}
-
-export function useSimulator(options: UseSimulatorOptions): UseSimulatorResult {
-  const { routeGeometry, active, config = {}, scenarios = [], onScenarioFired } = options;
-
-  const [position, setPosition] = useState<SimPosition | null>(null);
-  const [isRecording, setIsRecording] = useState(false);
-  const engineRef = useRef<SimulatorEngine | null>(null);
-  // Keep a stable ref to the latest onScenarioFired callback
-  const onScenarioFiredRef = useRef(onScenarioFired);
-  onScenarioFiredRef.current = onScenarioFired;
-
-  // Create / recreate the engine whenever the route geometry changes
-  useEffect(() => {
-    if (!routeGeometry || routeGeometry.length < 2) {
-      setPosition(null);
-      return;
-    }
-
-    const engine = new SimulatorEngine({
-      routeGeometry,
-      speedKmh: config.speedKmh ?? 50,
-      speedMultiplier: config.speedMultiplier ?? 1,
-      noiseProfile: config.noiseProfile ?? NoiseEngine.STANDARD,
-      loop: config.loop ?? false,
-      startIndex: config.startIndex ?? 0,
-      onPositionUpdate: (pos) => setPosition(pos),
-      onRouteComplete: () => {
-        if (options.onRouteComplete) {
-          options.onRouteComplete();
-        }
-      },
-      onScenarioStart: (s) => {
-        try { onScenarioFiredRef.current?.(s); } catch (_) { /* noop */ }
-      },
-    });
-
-    // Register any pre-declared scenarios
-    scenarios.forEach((s) => engine.addScenario(s));
-
-    engineRef.current = engine;
-
-    return () => {
-      engine.destroy();
-      engineRef.current = null;
-      setPosition(null);
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [routeGeometry]); // intentionally only re-runs when route changes
-
-  // Start/stop based on `active` prop
-  useEffect(() => {
-    const engine = engineRef.current;
-    if (!engine) return;
-
-    if (active) {
-      engine.start();
-    } else {
-      engine.stop();
-      setPosition(null);
-    }
-  }, [active]);
-
-  // ── Controls ────────────────────────────────────────────────────────────────
-
-  const pause = useCallback(() => engineRef.current?.pause(), []);
-  const resume = useCallback(() => engineRef.current?.resume(), []);
-  const seek = useCallback((index: number) => engineRef.current?.seek(index), []);
-  const setSpeed = useCallback((m: 1 | 2 | 4 | 8) => engineRef.current?.setSpeed(m), []);
-
-  const startSession = useCallback((sessionId?: string) => {
-    engineRef.current?.startRecording(sessionId);
-    setIsRecording(true);
-  }, []);
-
-  const stopSession = useCallback((): SimSession | null => {
-    setIsRecording(false);
-    return engineRef.current?.stopRecording() ?? null;
-  }, []);
-
-  const location = position?.location ?? (position ? { coords: position.coords, timestamp: position.timestamp } : null);
-
-  return {
-    position,
-    location,
-    rawLocation: location,
-    controls: { pause, resume, seek, setSpeed },
-    session: { start: startSession, stop: stopSession },
-    isRecording,
-  };
-}

package/src/replay/GpxParser.ts

@@ -1,122 +0,0 @@
-/**
- * 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)
- */
-
-import type { Coordinate } from '@ingissa/navcore-core';
-import { haversineDistance } from '@ingissa/navcore-core';
-
-export interface GpxParseResult {
-  coordinates: Coordinate[];
-  /** 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;
-  };
-}
-
-export class GpxParser {
-  /**
-   * Parse a GPX XML string into coordinates and metadata.
-   * Supports both <trkpt> and <wpt> elements.
-   */
-  static parse(gpxString: string): GpxParseResult {
-    const coordinates: Coordinate[] = [];
-    const timestamps: number[] = [];
-
-    // Match both <trkpt> and <wpt> tags
-    const pointRegex = /<(?:trkpt|wpt)\s+([^>]+)>([\s\S]*?)<\/(?:trkpt|wpt)>/g;
-    const latLonRegex = /lat="([^"]+)"/;
-    const lonRegex = /lon="([^"]+)"/;
-    const timeRegex = /<time>([^<]+)<\/time>/;
-
-    let match: RegExpExecArray | null;
-    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);
-      }
-    }
-
-    // Extract track/route name
-    const nameMatch = /<name>([^<]+)<\/name>/.exec(gpxString);
-    const name = nameMatch ? nameMatch[1]?.trim() : undefined;
-
-    // Compute distance
-    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]);
-    }
-
-    // Duration and speed from timestamps
-    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 / 1000);
-        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: string): GpxParseResult {
-    let decoded: string;
-    if (typeof atob !== 'undefined') {
-      decoded = atob(base64);
-    } else {
-      // Node.js
-      decoded = Buffer.from(base64, 'base64').toString('utf-8');
-    }
-    return GpxParser.parse(decoded);
-  }
-}

package/src/replay/SessionRecorder.ts

@@ -1,138 +0,0 @@
-/**
- * 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
- */
-
-import type { SimSession, SimPosition } from '../core/types';
-
-/** Generate a UUID v4 without external dependencies */
-function uuidV4(): string {
-  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 type ExportFormat = 'json' | 'gpx' | 'csv';
-
-export class SessionRecorder {
-  private _sessionId: string | null = null;
-  private _startedAt: number | null = null;
-  private _session: SimSession | null = 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?: string): void {
-    this._sessionId = sessionId ?? uuidV4();
-    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?: SimSession): SimSession {
-    if (existing) {
-      this._session = existing;
-      return existing;
-    }
-
-    // Minimal empty session if stop() is called without an engine session
-    const session: SimSession = {
-      id: this._sessionId ?? uuidV4(),
-      startedAt: new Date(this._startedAt ?? Date.now()).toISOString(),
-      endedAt: 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: ExportFormat): string {
-    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 ───────────────────────────────────────────────────
-
-  private static _toGpx(session: SimSession): string {
-    const trkpts = session.positions
-      .map((p: SimPosition) => {
-        const time = new Date(p.timestamp).toISOString();
-        return (
-          `    <trkpt lat="${p.coord[1]}" lon="${p.coord[0]}">\n` +
-          `      <time>${time}</time>\n` +
-          `      <extensions>\n` +
-          `        <speed>${p.speed.toFixed(4)}</speed>\n` +
-          `        <bearing>${p.bearing.toFixed(4)}</bearing>\n` +
-          `        <accuracy>${p.accuracy.toFixed(2)}</accuracy>\n` +
-          `      </extensions>\n` +
-          `    </trkpt>`
-        );
-      })
-      .join('\n');
-
-    return (
-      `<?xml version="1.0" encoding="UTF-8"?>\n` +
-      `<gpx version="1.1" creator="@ingissa/navcore-simulator"\n` +
-      `     xmlns="http://www.topografix.com/GPX/1/1"\n` +
-      `     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\n` +
-      `     xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">\n` +
-      `  <metadata>\n` +
-      `    <name>${session.id}</name>\n` +
-      `    <time>${session.startedAt}</time>\n` +
-      `  </metadata>\n` +
-      `  <trk>\n` +
-      `    <name>${session.id}</name>\n` +
-      `    <trkseg>\n` +
-      trkpts + '\n' +
-      `    </trkseg>\n` +
-      `  </trk>\n` +
-      `</gpx>`
-    );
-  }
-
-  private static _toCsv(session: SimSession): string {
-    const header = 'timestamp,lng,lat,bearing,speed,accuracy';
-    const rows = session.positions.map((p: SimPosition) =>
-      `${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');
-  }
-}

package/src/replay/__tests__/GpxParser.test.ts

@@ -1,136 +0,0 @@
-/**
- * GpxParser unit tests
- */
-import { describe, it, expect } from 'vitest';
-import { GpxParser } from '@ingissa/navcore-simulator';
-
-const MINIMAL_GPX = `<?xml version="1.0"?>
-<gpx version="1.1" xmlns="http://www.topografix.com/GPX/1/1">
-  <trk>
-    <name>Test Route</name>
-    <trkseg>
-      <trkpt lat="30.4278" lon="-9.5981">
-        <time>2024-01-01T10:00:00Z</time>
-      </trkpt>
-      <trkpt lat="30.4300" lon="-9.5960">
-        <time>2024-01-01T10:00:30Z</time>
-      </trkpt>
-      <trkpt lat="30.4320" lon="-9.5940">
-        <time>2024-01-01T10:01:00Z</time>
-      </trkpt>
-    </trkseg>
-  </trk>
-</gpx>`;
-
-const WAYPOINT_GPX = `<?xml version="1.0"?>
-<gpx version="1.1" xmlns="http://www.topografix.com/GPX/1/1">
-  <wpt lat="51.5074" lon="-0.1278"></wpt>
-  <wpt lat="51.5080" lon="-0.1270"></wpt>
-</gpx>`;
-
-const NO_TIMESTAMPS_GPX = `<?xml version="1.0"?>
-<gpx version="1.1">
-  <trk><trkseg>
-    <trkpt lat="0.0" lon="0.0"></trkpt>
-    <trkpt lat="0.001" lon="0.001"></trkpt>
-  </trkseg></trk>
-</gpx>`;
-
-describe('GpxParser', () => {
-  describe('parse — basic trkpt', () => {
-    it('parses 3 track points', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.coordinates).toHaveLength(3);
-    });
-
-    it('coordinates are [lng, lat] tuples', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      // First point: lat=30.4278, lon=-9.5981 → [lon, lat]
-      expect(result.coordinates[0]![0]).toBeCloseTo(-9.5981, 4);
-      expect(result.coordinates[0]![1]).toBeCloseTo(30.4278, 4);
-    });
-
-    it('parses timestamps correctly', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.timestamps).toHaveLength(3);
-      expect(result.timestamps[0]).toBeGreaterThan(0);
-    });
-
-    it('computes duration from first to last timestamp', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      // 10:00:00 to 10:01:00 = 60000ms
-      expect(result.metadata.durationMs).toBe(60000);
-    });
-
-    it('computes positive distance', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.metadata.distanceM).toBeGreaterThan(0);
-    });
-
-    it('extracts track name', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.metadata.name).toBe('Test Route');
-    });
-
-    it('totalPoints matches coordinate count', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.metadata.totalPoints).toBe(3);
-    });
-
-    it('computes positive avgSpeedKmh', () => {
-      const result = GpxParser.parse(MINIMAL_GPX);
-      expect(result.metadata.avgSpeedKmh).toBeGreaterThan(0);
-    });
-  });
-
-  describe('parse — waypoints', () => {
-    it('parses <wpt> elements', () => {
-      const result = GpxParser.parse(WAYPOINT_GPX);
-      expect(result.coordinates).toHaveLength(2);
-      expect(result.coordinates[0]![0]).toBeCloseTo(-0.1278, 4);
-      expect(result.coordinates[0]![1]).toBeCloseTo(51.5074, 4);
-    });
-  });
-
-  describe('parse — no timestamps', () => {
-    it('returns zero durationMs and zero avgSpeedKmh', () => {
-      const result = GpxParser.parse(NO_TIMESTAMPS_GPX);
-      expect(result.metadata.durationMs).toBe(0);
-      expect(result.metadata.avgSpeedKmh).toBe(0);
-    });
-
-    it('still computes distance', () => {
-      const result = GpxParser.parse(NO_TIMESTAMPS_GPX);
-      expect(result.metadata.distanceM).toBeGreaterThan(0);
-    });
-  });
-
-  describe('parse — empty GPX', () => {
-    it('returns empty arrays for empty GPX', () => {
-      const result = GpxParser.parse('<gpx></gpx>');
-      expect(result.coordinates).toHaveLength(0);
-      expect(result.timestamps).toHaveLength(0);
-      expect(result.metadata.totalPoints).toBe(0);
-    });
-  });
-
-  describe('fromBase64', () => {
-    it('round-trips a GPX string via base64', () => {
-      const b64 = Buffer.from(MINIMAL_GPX).toString('base64');
-      const result = GpxParser.fromBase64(b64);
-      expect(result.coordinates).toHaveLength(3);
-      expect(result.coordinates[0]![0]).toBeCloseTo(-9.5981, 4);
-    });
-  });
-
-  describe('parse — malformed attributes', () => {
-    it('skips points with invalid lat/lon', () => {
-      const gpx = `<gpx><trk><trkseg>
-        <trkpt lat="not-a-number" lon="-9.5981"></trkpt>
-        <trkpt lat="30.0" lon="-9.0"></trkpt>
-      </trkseg></trk></gpx>`;
-      const result = GpxParser.parse(gpx);
-      expect(result.coordinates).toHaveLength(1);
-    });
-  });
-});