@ingissa/navcore-simulator 1.0.7 → 1.0.9

package/src/core/SimulatorEngine.ts

@@ -1,364 +0,0 @@
-/**
- * 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';
-import type { SimPosition, SimulatorConfig, SimSession, Scenario } from './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 EngineState = 'idle' | 'running' | 'paused' | 'complete';
-
-export class SimulatorEngine {
-  // ── Config ──────────────────────────────────────────────────────────────────
-  private readonly config: Required<
-    Omit<SimulatorConfig, 'onPositionUpdate' | 'onRouteComplete' | 'onScenarioStart' | 'onScenarioEnd'>
-  > & Pick<SimulatorConfig, 'onPositionUpdate' | 'onRouteComplete' | 'onScenarioStart' | 'onScenarioEnd'>;
-
-  // ── Internal components ──────────────────────────────────────────────────────
-  private walker: RouteWalker;
-  private noise: NoiseEngine;
-  private injector: ScenarioInjector;
-
-  // ── State ────────────────────────────────────────────────────────────────────
-  private _state: EngineState = 'idle';
-  private _position: SimPosition | null = null;
-  private _speedMultiplier: 1 | 2 | 4 | 8;
-  private _timer: ReturnType<typeof setInterval> | null = null;
-  private _lastTick: number = 0;
-
-  private static readonly TICK_MS = 50; // 20 FPS for smooth movement
-
-  // ── Recording ────────────────────────────────────────────────────────────────
-  private _recording = false;
-  private _recordedPositions: SimPosition[] = [];
-  private _recordedScenarios: Array<{ scenario: Scenario; firedAt: number }> = [];
-  private _sessionId: string | null = null;
-  private _sessionStart: number | null = null;
-  private _noiseSamplesAdded = 0;
-
-  constructor(config: SimulatorConfig) {
-    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(): void {
-    if (this._state === 'running') return;
-    if (this._state === 'complete') return;
-    this._state = 'running';
-    this._startTimer();
-  }
-
-  stop(): void {
-    this._stopTimer();
-    this._state = 'idle';
-    this._position = null;
-  }
-
-  pause(): void {
-    if (this._state !== 'running') return;
-    this._stopTimer();
-    this._state = 'paused';
-  }
-
-  resume(): void {
-    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: number): void {
-    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: 1 | 2 | 4 | 8): void {
-    this._speedMultiplier = multiplier;
-    if (this._state === 'running') {
-      this._stopTimer();
-      this._startTimer();
-    }
-  }
-
-  // ── Scenario management ──────────────────────────────────────────────────────
-
-  addScenario(scenario: Scenario): void {
-    this.injector.register(scenario);
-  }
-
-  removeScenario(name: string): void {
-    this.injector.remove(name);
-  }
-
-  clearScenarios(): void {
-    this.injector.clear();
-  }
-
-  // ── State accessors ──────────────────────────────────────────────────────────
-
-  get state(): EngineState {
-    return this._state;
-  }
-
-  get position(): SimPosition | null {
-    return this._position;
-  }
-
-  get progress(): number {
-    if (this.walker.totalPoints <= 1) return 0;
-    return Math.min(1, this.walker.currentIndex / (this.walker.totalPoints - 1));
-  }
-
-  // ── Session recording ────────────────────────────────────────────────────────
-
-  startRecording(sessionId?: string): void {
-    this._recording = true;
-    this._recordedPositions = [];
-    this._recordedScenarios = [];
-    this._sessionId = sessionId ?? uuidV4();
-    this._sessionStart = Date.now();
-    this._noiseSamplesAdded = 0;
-  }
-
-  stopRecording(): SimSession {
-    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(): void {
-    this._stopTimer();
-    this.injector.destroy();
-    this._state = 'idle';
-    this._position = null;
-    this._recording = false;
-    this._recordedPositions = [];
-  }
-
-  // ── Private ──────────────────────────────────────────────────────────────────
-
-  private _startTimer(): void {
-    this._lastTick = Date.now();
-    const intervalMs = Math.round(1000 / this._speedMultiplier);
-    this._timer = setInterval(() => this._tick(), intervalMs);
-  }
-
-  private _stopTimer(): void {
-    if (this._timer !== null) {
-      clearInterval(this._timer);
-      this._timer = null;
-    }
-  }
-
-  private _tick(): void {
-    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);
-
-    // 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'] as number | undefined) ?? 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'] as number | undefined) ?? 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 */ }
-    }
-  }
-
-  private _buildAndEmitPosition(
-    coord: [number, number],
-    bearing: number,
-    distanceTravelled: number,
-    isNoisy: boolean,
-    opts?: {
-      speedMs?: number;
-      accuracy?: number;
-      activeScenarioName?: string;
-      segmentIndex?: number;
-    },
-  ): void {
-    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: SimPosition = {
-      coord: coord as [number, number],
-      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 (_) { /* never throw */ }
-  }
-}

package/src/core/__tests__/NoiseEngine.test.ts

@@ -1,131 +0,0 @@
-/**
- * NoiseEngine unit tests
- */
-import { describe, it, expect } from 'vitest';
-import { NoiseEngine } from '@ingissa/navcore-simulator';
-import type { Coordinate } from '@ingissa/navcore-core';
-
-const ORIGIN: Coordinate = [0.0, 0.0];
-const RUNS = 500; // statistical test runs
-
-/** Sample standard deviation of an array */
-function stdDev(values: number[]): number {
-  const mean = values.reduce((a, b) => a + b, 0) / values.length;
-  const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
-  return Math.sqrt(variance);
-}
-
-describe('NoiseEngine', () => {
-  describe('NONE profile', () => {
-    it('returns the exact same coordinate', () => {
-      const engine = new NoiseEngine(NoiseEngine.NONE);
-      const result = engine.apply(ORIGIN);
-      expect(result[0]).toBe(ORIGIN[0]);
-      expect(result[1]).toBe(ORIGIN[1]);
-    });
-
-    it('never mutates the input coordinate', () => {
-      const engine = new NoiseEngine(NoiseEngine.NONE);
-      const coord: Coordinate = [1.234, 5.678];
-      engine.apply(coord);
-      expect(coord[0]).toBe(1.234);
-      expect(coord[1]).toBe(5.678);
-    });
-  });
-
-  describe('STANDARD profile (12m stddev)', () => {
-    it('applies noise that shifts the coordinate', () => {
-      const engine = new NoiseEngine(NoiseEngine.STANDARD);
-      const result = engine.apply(ORIGIN);
-      // There's a tiny probability of hitting exactly 0 — this test is still valid
-      const changed = result[0] !== ORIGIN[0] || result[1] !== ORIGIN[1];
-      expect(changed).toBe(true);
-    });
-
-    it('stddev of longitude offsets is within expected range (~12m ± 50%)', () => {
-      const engine = new NoiseEngine(NoiseEngine.STANDARD);
-      // 1° longitude ≈ 111320m
-      const lngOffsets: number[] = [];
-      for (let i = 0; i < RUNS; i++) {
-        const r = engine.apply(ORIGIN);
-        lngOffsets.push((r[0] - ORIGIN[0]) * 111320);
-      }
-      const sd = stdDev(lngOffsets);
-      // Should be roughly 12m (allow 50% tolerance for statistical variation)
-      expect(sd).toBeGreaterThan(6);
-      expect(sd).toBeLessThan(24);
-    });
-  });
-
-  describe('Seed determinism', () => {
-    it('same seed produces identical sequence', () => {
-      const profile = { ...NoiseEngine.STANDARD, seed: 42 };
-      const engineA = new NoiseEngine(profile);
-      const engineB = new NoiseEngine(profile);
-
-      for (let i = 0; i < 20; i++) {
-        const a = engineA.apply(ORIGIN);
-        const b = engineB.apply(ORIGIN);
-        expect(a[0]).toBe(b[0]);
-        expect(a[1]).toBe(b[1]);
-      }
-    });
-
-    it('different seeds produce different sequences', () => {
-      const engineA = new NoiseEngine({ ...NoiseEngine.STANDARD, seed: 1 });
-      const engineB = new NoiseEngine({ ...NoiseEngine.STANDARD, seed: 2 });
-
-      const resultsA = Array.from({ length: 10 }, () => engineA.apply(ORIGIN));
-      const resultsB = Array.from({ length: 10 }, () => engineB.apply(ORIGIN));
-
-      // At least one result should differ
-      const anyDiff = resultsA.some((a, i) => a[0] !== resultsB[i]![0]);
-      expect(anyDiff).toBe(true);
-    });
-  });
-
-  describe('CUSTOM profile', () => {
-    it('delegates to customFn', () => {
-      let callCount = 0;
-      const engine = new NoiseEngine({
-        type: 'CUSTOM',
-        stdDevM: 0,
-        customFn: (idx) => {
-          callCount++;
-          return [idx * 0.001, idx * 0.0005];
-        },
-      });
-
-      const r0 = engine.apply(ORIGIN);
-      const r1 = engine.apply(ORIGIN);
-
-      expect(callCount).toBe(2);
-      expect(r0[0]).toBeCloseTo(0 * 0.001, 6);
-      expect(r1[0]).toBeCloseTo(1 * 0.001, 6);
-    });
-
-    it('returns original coord if customFn is missing', () => {
-      const engine = new NoiseEngine({ type: 'CUSTOM', stdDevM: 0 });
-      const result = engine.apply(ORIGIN);
-      expect(result[0]).toBe(ORIGIN[0]);
-    });
-  });
-
-  describe('setProfile', () => {
-    it('hot-swaps from STANDARD to NONE mid-simulation', () => {
-      const engine = new NoiseEngine(NoiseEngine.STANDARD);
-      engine.setProfile(NoiseEngine.NONE);
-      const result = engine.apply([1.0, 2.0]);
-      expect(result[0]).toBe(1.0);
-      expect(result[1]).toBe(2.0);
-    });
-  });
-
-  describe('Static presets', () => {
-    it('CLEAN has stdDevM: 3', () => expect(NoiseEngine.CLEAN.stdDevM).toBe(3));
-    it('STANDARD has stdDevM: 12', () => expect(NoiseEngine.STANDARD.stdDevM).toBe(12));
-    it('URBAN has stdDevM: 25', () => expect(NoiseEngine.URBAN.stdDevM).toBe(25));
-    it('DEGRADED has stdDevM: 50', () => expect(NoiseEngine.DEGRADED.stdDevM).toBe(50));
-    it('NONE has stdDevM: 0', () => expect(NoiseEngine.NONE.stdDevM).toBe(0));
-  });
-});

package/src/core/__tests__/RouteWalker.test.ts

@@ -1,139 +0,0 @@
-/**
- * RouteWalker unit tests
- */
-import { describe, it, expect, beforeEach } from 'vitest';
-import { RouteWalker } from '@ingissa/navcore-simulator';
-import type { Coordinate } from '@ingissa/navcore-core';
-
-// Simple 5-point straight line going east
-// Each point is ~111m apart (1 second at 400 km/h, but fine for geometry tests)
-const STRAIGHT: Coordinate[] = [
-  [0.000, 0.000],
-  [0.001, 0.000],
-  [0.002, 0.000],
-  [0.003, 0.000],
-  [0.004, 0.000],
-];
-
-describe('RouteWalker', () => {
-  let walker: RouteWalker;
-
-  beforeEach(() => {
-    walker = new RouteWalker(STRAIGHT);
-  });
-
-  it('throws with fewer than 2 points', () => {
-    expect(() => new RouteWalker([[0, 0]])).toThrow();
-    expect(() => new RouteWalker([])).toThrow();
-  });
-
-  it('initialises at index 0 and is not complete', () => {
-    expect(walker.currentIndex).toBe(0);
-    expect(walker.isComplete).toBe(false);
-  });
-
-  it('advance(1) moves to index 1', () => {
-    const pos = walker.advance(1);
-    expect(pos.index).toBe(1);
-    expect(walker.currentIndex).toBe(1);
-    expect(pos.isComplete).toBe(false);
-  });
-
-  it('advance(N) reaches the last point and marks complete', () => {
-    const pos = walker.advance(STRAIGHT.length - 1);
-    expect(pos.isComplete).toBe(true);
-    expect(walker.isComplete).toBe(true);
-  });
-
-  it('advance beyond end clamps to last point', () => {
-    walker.advance(100);
-    expect(walker.currentIndex).toBe(STRAIGHT.length - 1);
-    expect(walker.isComplete).toBe(true);
-  });
-
-  it('advance does nothing after completion', () => {
-    walker.advance(100);
-    const pos = walker.advance(1);
-    expect(pos.index).toBe(STRAIGHT.length - 1);
-  });
-
-  it('interpolate returns midpoint correctly', () => {
-    const mid = walker.interpolate(0, 0.5);
-    expect(mid[0]).toBeCloseTo(0.0005, 5);
-    expect(mid[1]).toBeCloseTo(0.0, 5);
-  });
-
-  it('interpolate clamps fraction to [0, 1]', () => {
-    const start = walker.interpolate(0, -0.5);
-    const startExpected = STRAIGHT[0]!;
-    expect(start[0]).toBeCloseTo(startExpected[0], 5);
-
-    const end = walker.interpolate(0, 1.5);
-    const endExpected = STRAIGHT[1]!;
-    expect(end[0]).toBeCloseTo(endExpected[0], 5);
-  });
-
-  it('bearingAt returns ~90° for eastward segment', () => {
-    const bearing = walker.bearingAt(0);
-    // Should be roughly east (90°)
-    expect(bearing).toBeGreaterThan(85);
-    expect(bearing).toBeLessThan(95);
-  });
-
-  it('bearingAt on last index returns bearing of last segment', () => {
-    const bearing = walker.bearingAt(STRAIGHT.length - 1);
-    expect(bearing).toBeGreaterThan(85);
-    expect(bearing).toBeLessThan(95);
-  });
-
-  it('distanceToIndex(0) is 0', () => {
-    expect(walker.distanceToIndex(0)).toBe(0);
-  });
-
-  it('distanceToIndex increases monotonically', () => {
-    for (let i = 1; i < STRAIGHT.length; i++) {
-      expect(walker.distanceToIndex(i)).toBeGreaterThan(walker.distanceToIndex(i - 1));
-    }
-  });
-
-  it('totalDistanceM is positive and equals distanceToIndex(last)', () => {
-    const total = walker.totalDistanceM;
-    expect(total).toBeGreaterThan(0);
-    expect(total).toBeCloseTo(walker.distanceToIndex(STRAIGHT.length - 1), 1);
-  });
-
-  it('totalPoints equals geometry length', () => {
-    expect(walker.totalPoints).toBe(STRAIGHT.length);
-  });
-
-  it('seek jumps to the correct index', () => {
-    const pos = walker.seek(3);
-    expect(pos.index).toBe(3);
-    expect(walker.currentIndex).toBe(3);
-    expect(pos.isComplete).toBe(false);
-  });
-
-  it('seek recalculates bearing at new position', () => {
-    const pos = walker.seek(2);
-    // Eastward segment → bearing ~90°
-    expect(pos.bearing).toBeGreaterThan(85);
-    expect(pos.bearing).toBeLessThan(95);
-  });
-
-  it('seek to last index marks complete', () => {
-    const pos = walker.seek(STRAIGHT.length - 1);
-    expect(pos.isComplete).toBe(true);
-  });
-
-  it('startIndex constructor param positions correctly', () => {
-    const w = new RouteWalker(STRAIGHT, 2);
-    expect(w.currentIndex).toBe(2);
-    expect(w.distanceToIndex(2)).toBeGreaterThan(0);
-  });
-
-  it('advance with fractional steps interpolates coord', () => {
-    const pos = walker.advance(0.5);
-    // Should be halfway between point 0 and 1
-    expect(pos.coord[0]).toBeCloseTo(0.0005, 4);
-  });
-});