@ingissa/navcore-simulator 1.0.4 → 1.0.7

package/package.json

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

package/src/__tests__/integration/simulator-pipeline.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Integration test: Full simulator pipeline
+ *
+ * GPX file → parse → simulate → record → export GPX → re-parse → verify
+ *
+ * This is the validation test specified in the brief.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { SimulatorEngine } from '../../core/SimulatorEngine';
+import { NoiseEngine } from '../../core/NoiseEngine';
+import { ScenarioInjector } from '../../scenarios/ScenarioInjector';
+import { GpxParser } from '../../replay/GpxParser';
+import { SessionRecorder } from '../../replay/SessionRecorder';
+import type { Coordinate } from '@ingissa/navcore-core';
+import type { SimPosition } from '../../core/types';
+
+// ─── Agadir Circuit — 137 points (as defined in NavCoreTestScreen) ─────────────
+const CIRCUIT_ANCHORS: [number, number][] = [
+  [-9.6271, 30.4112],
+  [-9.6295, 30.4170],
+  [-9.6340, 30.4240],
+  [-9.6371, 30.4310],
+  [-9.6360, 30.4390],
+  [-9.6280, 30.4460],
+  [-9.6150, 30.4530],
+  [-9.5980, 30.4590],
+  [-9.5800, 30.4560],
+  [-9.5640, 30.4490],
+  [-9.5490, 30.4380],
+  [-9.5510, 30.4240],
+  [-9.5620, 30.4130],
+  [-9.5780, 30.4060],
+  [-9.5960, 30.4020],
+  [-9.6100, 30.4040],
+  [-9.6210, 30.4075],
+  [-9.6271, 30.4112],
+];
+
+function interpolate(a: [number, number], b: [number, number], steps: number): Coordinate[] {
+  const pts: Coordinate[] = [];
+  for (let i = 0; i < steps; i++) {
+    const t = i / steps;
+    pts.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+  }
+  return pts;
+}
+
+function buildCircuit(): Coordinate[] {
+  const STEPS = 8; // 17 segments × 8 = 136 + 1 closing = 137
+  const points: Coordinate[] = [];
+  for (let i = 0; i < CIRCUIT_ANCHORS.length - 1; i++) {
+    points.push(...interpolate(CIRCUIT_ANCHORS[i]!, CIRCUIT_ANCHORS[i + 1]!, STEPS));
+  }
+  points.push(CIRCUIT_ANCHORS[CIRCUIT_ANCHORS.length - 1]! as Coordinate);
+  return points;
+}
+
+const AGADIR_CIRCUIT = buildCircuit();
+
+describe('Simulator Integration Pipeline', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('AGADIR_CIRCUIT has 137 points', () => {
+    expect(AGADIR_CIRCUIT.length).toBe(137);
+  });
+
+  it('full validation test from spec: simulate → record → export GPX → re-parse', async () => {
+    vi.useFakeTimers();
+
+    const positions: SimPosition[] = [];
+    let done = false;
+
+    const engine = new SimulatorEngine({
+      routeGeometry: AGADIR_CIRCUIT,
+      speedKmh: 50,
+      speedMultiplier: 4,
+      noiseProfile: NoiseEngine.STANDARD,
+      loop: false,
+      onPositionUpdate: (pos) => positions.push(pos),
+      onRouteComplete: () => { done = true; },
+    });
+
+    engine.addScenario(ScenarioInjector.gpsBlackout(42, 3000));
+    engine.startRecording();
+    engine.start();
+
+    // Drain all timers — at 4× speed, 136 ticks × 250ms = 34000ms of real time
+    await vi.runAllTimersAsync();
+
+    expect(done).toBe(true);
+
+    const session = engine.stopRecording();
+
+    // ── Assert session correctness ──
+    expect(session.positions.length).toBeGreaterThan(0);
+    expect(session.positions.length).toBe(positions.length);
+    expect(session.scenarios).toHaveLength(1);
+    expect(session.scenarios[0]!.scenario.type).toBe('GPS_BLACKOUT');
+    expect(session.stats.scenariosFired).toBe(1);
+    expect(session.stats.distanceTravelledM).toBeGreaterThan(0);
+
+    // ── Export as GPX ──
+    const recorder = new SessionRecorder();
+    recorder.stop(session);
+    const gpx = recorder.export('gpx');
+
+    expect(gpx).toContain('<gpx');
+    expect(gpx).toContain('<trkpt');
+    expect(gpx).toContain('</gpx>');
+
+    // ── Re-parse GPX → verify coordinate count matches ──
+    const reparsed = GpxParser.parse(gpx);
+    expect(reparsed.coordinates.length).toBe(session.positions.length);
+
+    // ── Coordinates are [lng, lat] and within Morocco ──
+    for (const coord of reparsed.coordinates) {
+      expect(coord[0]).toBeLessThan(-9.0);   // lng in Morocco
+      expect(coord[1]).toBeGreaterThan(30.0); // lat in Morocco
+    }
+
+    engine.destroy();
+  });
+
+  it('CSV export produces correct header and row count', async () => {
+    vi.useFakeTimers();
+
+    const engine = new SimulatorEngine({
+      routeGeometry: AGADIR_CIRCUIT.slice(0, 10),
+      speedKmh: 50,
+      speedMultiplier: 4,
+      noiseProfile: NoiseEngine.NONE,
+      loop: false,
+    });
+
+    engine.startRecording();
+    engine.start();
+    await vi.runAllTimersAsync();
+
+    const session = engine.stopRecording();
+    const recorder = new SessionRecorder();
+    recorder.stop(session);
+    const csv = recorder.export('csv');
+
+    const lines = csv.split('\n');
+    expect(lines[0]).toBe('timestamp,lng,lat,bearing,speed,accuracy');
+    expect(lines.length).toBe(session.positions.length + 1); // header + rows
+
+    engine.destroy();
+  });
+
+  it('JSON export is valid and re-parseable', async () => {
+    vi.useFakeTimers();
+
+    const engine = new SimulatorEngine({
+      routeGeometry: AGADIR_CIRCUIT.slice(0, 5),
+      speedKmh: 50,
+      speedMultiplier: 4,
+      noiseProfile: NoiseEngine.NONE,
+      loop: false,
+    });
+
+    engine.startRecording('test-session-123');
+    engine.start();
+    await vi.runAllTimersAsync();
+
+    const session = engine.stopRecording();
+    const recorder = new SessionRecorder();
+    recorder.stop(session);
+    const json = recorder.export('json');
+
+    const parsed = JSON.parse(json);
+    expect(parsed.id).toBe('test-session-123');
+    expect(Array.isArray(parsed.positions)).toBe(true);
+    expect(parsed.stats.scenariosFired).toBe(0);
+
+    engine.destroy();
+  });
+
+  it('GPX round-trip: exported GPX re-parsed has matching coordinate count', async () => {
+    vi.useFakeTimers();
+
+    const route: Coordinate[] = Array.from({ length: 20 }, (_, i) => [i * 0.001, 30.0] as Coordinate);
+
+    const engine = new SimulatorEngine({
+      routeGeometry: route,
+      speedKmh: 50,
+      speedMultiplier: 8,
+      noiseProfile: NoiseEngine.NONE,
+      loop: false,
+    });
+
+    engine.startRecording();
+    engine.start();
+    await vi.runAllTimersAsync();
+
+    const session = engine.stopRecording();
+    const recorder = new SessionRecorder();
+    recorder.stop(session);
+    const gpx = recorder.export('gpx');
+    const reparsed = GpxParser.parse(gpx);
+
+    expect(reparsed.coordinates.length).toBe(session.positions.length);
+    engine.destroy();
+  });
+
+  it('scenario metadata is attached to positions during GPS_BLACKOUT', async () => {
+    vi.useFakeTimers();
+
+    const route: Coordinate[] = Array.from({ length: 20 }, (_, i) => [i * 0.001, 30.0] as Coordinate);
+    const captured: SimPosition[] = [];
+
+    const engine = new SimulatorEngine({
+      routeGeometry: route,
+      speedKmh: 50,
+      speedMultiplier: 8,
+      noiseProfile: NoiseEngine.NONE,
+      loop: false,
+      onPositionUpdate: (p) => captured.push(p),
+    });
+
+    engine.addScenario(ScenarioInjector.gpsBlackout(5, 5000));
+    engine.start();
+    await vi.runAllTimersAsync();
+
+    // At least one position should have metadata.scenarioActive set
+    const scenarioPositions = captured.filter((p) => p.metadata?.scenarioActive);
+    expect(scenarioPositions.length).toBeGreaterThan(0);
+
+    engine.destroy();
+  });
+});

package/src/core/NoiseEngine.ts

@@ -0,0 +1,137 @@
+/**
+ * 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)
+ */
+
+import type { Coordinate } from '@ingissa/navcore-core';
+import type { NoiseProfile } from './types';
+
+// Conversion factors
+const LAT_DEG_PER_M = 1 / 110540;
+const LNG_DEG_PER_M = 1 / 111320;
+
+/**
+ * Simple seeded LCG (Linear Congruential Generator).
+ * Same seed guarantees identical noise sequences — critical for CI regression.
+ */
+class SeededRandom {
+  private state: number;
+
+  constructor(seed: number) {
+    this.state = seed >>> 0; // ensure unsigned 32-bit
+  }
+
+  /** Returns a float in [0, 1) */
+  next(): number {
+    // LCG parameters from Numerical Recipes
+    this.state = (Math.imul(1664525, this.state) + 1013904223) >>> 0;
+    return this.state / 0x100000000;
+  }
+}
+
+export class NoiseEngine {
+  private profile: NoiseProfile;
+  private rng: SeededRandom | null;
+  private _tickIndex = 0;
+
+  constructor(profile: NoiseProfile) {
+    this.profile = profile;
+    this.rng = profile.seed !== undefined ? new SeededRandom(profile.seed) : null;
+  }
+
+  // ── Static presets ─────────────────────────────────────────────────────────
+
+  /** No noise — returns the exact coordinate */
+  static readonly NONE: NoiseProfile = { type: 'NONE', stdDevM: 0 };
+
+  /** Good urban GPS — ~3m standard deviation */
+  static readonly CLEAN: NoiseProfile = { type: 'GAUSSIAN', stdDevM: 3 };
+
+  /** Standard Go4Exams value — ~12m standard deviation (matches original ±0.00011°) */
+  static readonly STANDARD: NoiseProfile = { type: 'GAUSSIAN', stdDevM: 12 };
+
+  /** Dense city canyon — ~25m standard deviation */
+  static readonly URBAN: NoiseProfile = { type: 'URBAN', stdDevM: 25 };
+
+  /** Bad conditions — ~50m standard deviation */
+  static readonly DEGRADED: NoiseProfile = { type: 'GAUSSIAN', stdDevM: 50 };
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Apply noise to a coordinate.
+   * Returns a new coordinate — never mutates the input.
+   */
+  apply(coord: Coordinate): Coordinate {
+    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':
+        // Signal loss: return a fixed position (last known would be handled by engine)
+        // Here we just return the exact coord (engine handles blackout via scenario)
+        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: NoiseProfile): void {
+    this.profile = profile;
+    this.rng = profile.seed !== undefined ? new SeededRandom(profile.seed) : null;
+    this._tickIndex = 0;
+  }
+
+  get currentProfile(): NoiseProfile {
+    return this.profile;
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Box-Muller transform: produces Gaussian N(0, stdDev²) offset.
+   * Returns [lngOffset, latOffset] in degrees.
+   */
+  private _gaussianOffset(stdDevM: number): [number, number] {
+    if (stdDevM === 0) return [0, 0];
+
+    const u1 = this._rand();
+    const u2 = this._rand();
+
+    // Box-Muller
+    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 */
+  private _rand(): number {
+    return this.rng ? this.rng.next() : Math.random();
+  }
+}

package/src/core/RouteWalker.ts

@@ -0,0 +1,227 @@
+/**
+ * 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';
+import type { Coordinate } from '@ingissa/navcore-core';
+
+export 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;
+  /** 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;
+}
+
+export class RouteWalker {
+  private readonly geometry: Coordinate[];
+  private _index: number;
+  private _distanceTravelled: number;
+  private readonly _cumulativeDistances: number[]; // length = geometry.length
+  private _isComplete: boolean;
+
+  constructor(geometry: Coordinate[], 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<number>(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: number): WalkerPosition {
+    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: number): WalkerPosition {
+    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();
+  }
+
+  private _finalizeAdvance(): WalkerPosition {
+    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: number): WalkerPosition {
+    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: number, fraction: number): Coordinate {
+    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: number): number {
+    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: number): number {
+    const clampedIdx = Math.max(0, Math.min(Math.floor(index), this.geometry.length - 1));
+    return this._cumulativeDistances[clampedIdx] ?? 0;
+  }
+
+  /**
+   * Alias for distanceAtIndex.
+   */
+  distanceToIndex(index: number): number {
+    return this.distanceAtIndex(index);
+  }
+
+  /**
+   * Convert a distance in metres back to a fractional index.
+   * Uses binary search for O(log N) performance.
+   */
+  private _distanceToIndex(targetDistance: number): number {
+    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(): number {
+    return this._cumulativeDistances[this.geometry.length - 1] ?? 0;
+  }
+
+  get totalPoints(): number {
+    return this.geometry.length;
+  }
+
+  get isComplete(): boolean {
+    return this._isComplete;
+  }
+
+  get currentIndex(): number {
+    return this._index;
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────────────
+
+  private _currentPosition(): WalkerPosition {
+    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 */
+  private _interpolatedDistance(index: number): number {
+    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;
+  }
+}