@ingissa/navcore-simulator 1.0.9 → 1.0.11

package/LICENSE

@@ -1,3 +1,3 @@
-Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved.
-
-No license is granted except by separate written agreement.
+Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved.
+
+No license is granted except by separate written agreement.

package/README.md

@@ -1,66 +1,92 @@
-# @ingissa/navcore-simulator
+# @ingissa/navcore-simulator
 
-[Site officiel](https://navcore-web.vercel.app/)
+[Official Website](https://navcore-web.vercel.app/)
 
 > Headless GPS simulation engine for the NavCore ecosystem.
-> Works in **Node.js** (CI), **React Native**, and any JavaScript environment.
+> Works in **Node.js** (CI/CD), **React Native**, and browser runtimes.
+
+[![npm version](https://img.shields.io/npm/v/@ingissa/navcore-simulator)](https://www.npmjs.com/package/@ingissa/navcore-simulator)
+![License](https://img.shields.io/badge/license-Proprietary-red)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
 ---
 
 ## Contents
 
+- [Overview](#overview)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Core Classes](#core-classes)
-  - [SimulatorEngine](#simulatorengine)
-  - [RouteWalker](#routewalker)
-  - [NoiseEngine](#noiseengine)
-  - [ScenarioInjector](#scenarioinjector)
-  - [GpxParser](#gpxparser)
-  - [SessionRecorder](#sessionrecorder)
-  - [FleetSimulator](#fleetsimulator-phase-2)
-- [React Native](#react-native)
-  - [useSimulator](#usesimulator)
-  - [SimulatorControls](#simulatorcontrols)
+  - [1. SimulatorEngine](#1-simulatorengine)
+  - [2. RouteWalker](#2-routewalker)
+  - [3. NoiseEngine](#3-noiseengine)
+  - [4. ScenarioInjector](#4-scenarioinjector)
+  - [5. GpxParser](#5-gpxparser)
+  - [6. SessionRecorder](#6-sessionrecorder)
+  - [7. FleetSimulator](#7-fleetsimulator)
+- [React Native Integration](#react-native-integration)
 - [Noise Profiles](#noise-profiles)
-- [Scenario Types](#scenario-types)
-- [GPX Round-Trip Loop](#gpx-round-trip-loop)
-- [CI / Regression Testing](#ci--regression-testing)
-- [Migration from useGpsSimulator](#migration-from-usegpssimulator)
+- [CI Regression Testing](#ci-regression-testing)
+- [Licensing](#licensing)
+
+---
+
+## Overview
+
+`@ingissa/navcore-simulator` provides realistic GPS signal simulation for development, UI validation, and automated regression testing. It simulates vehicle movement along route geometry with configurable speeds, bearing interpolation, realistic Gaussian noise, and dynamic scenario faults (such as GPS blackouts, sensor jitter, and temporary deviations).
 
 ---
 
 ## Installation
 
 ```bash
-# Inside the go4exams monorepo — already available via workspace
-# Import directly from the source tree:
-import { SimulatorEngine, NoiseEngine } from '@ingissa/navcore-simulator'
+npm install @ingissa/navcore-simulator @ingissa/navcore-core
 ```
 
-**Peer dependencies:** `@ingissa/navcore-core` (already in monorepo). React Native hooks additionally require `react` and `react-native`, which are optional peer deps (tree-shaken in Node.js CI).
+### Peer Dependencies
+- `@ingissa/navcore-core`: `^1.0.9` (required)
+- `react`: `>=18` (optional, needed only for React Native UI hooks)
+- `react-native`: `>=0.72` (optional, needed only for React Native UI hooks)
+
+### Subpath Exports
+- `@ingissa/navcore-simulator`: Universal export containing engine, utilities, and UI controls.
+- `@ingissa/navcore-simulator/node`: Headless export for Node.js scripts, Vitest/Jest suites, and CI pipelines (zero React/DOM dependencies).
+- `@ingissa/navcore-simulator/react-native`: Mobile export with `useSimulator` and `SimulatorControls`.
 
 ---
 
 ## Quick Start
 
+### Node.js / CI Headless Simulation
+
 ```typescript
-import { SimulatorEngine, NoiseEngine, ScenarioInjector } from '@ingissa/navcore-simulator';
+import { SimulatorEngine, NoiseEngine, ScenarioInjector } from '@ingissa/navcore-simulator/node';
+import type { Coordinate } from '@ingissa/navcore-core';
+
+const routeGeometry: Coordinate[] = [
+  [2.3522, 48.8566],
+  [2.3400, 48.8650],
+  [2.3009, 48.8741],
+];
 
 const engine = new SimulatorEngine({
-  routeGeometry: myRoute,       // Coordinate[] from @ingissa/navcore-core
+  routeGeometry,
   speedKmh: 50,
-  speedMultiplier: 4,           // 4× real-time
+  speedMultiplier: 2,           // 2× real-time playback
   noiseProfile: NoiseEngine.STANDARD,
   loop: false,
   onPositionUpdate: (pos) => {
-    console.log(pos.coord, pos.bearing, pos.speed);
+    console.log(`GPS: [${pos.coord[0].toFixed(5)}, ${pos.coord[1].toFixed(5)}] | Heading: ${Math.round(pos.bearing)}° | Speed: ${pos.speed} m/s`);
+  },
+  onRouteComplete: () => {
+    console.log('Simulation journey finished.');
   },
-  onRouteComplete: () => console.log('Route complete'),
 });
 
-engine.addScenario(ScenarioInjector.gpsBlackout(42, 5000));
-engine.startRecording();
+// Inject a 5-second GPS blackout at geometry segment 10
+engine.addScenario(ScenarioInjector.gpsBlackout(10, 5000));
+
+// Start playback
 engine.start();
 ```
 
@@ -68,361 +94,138 @@ engine.start();
 
 ## Core Classes
 
-### SimulatorEngine
-
-The main orchestrator. Headless — no React, no Expo APIs. Runs in Node.js CI.
-
-```typescript
-const engine = new SimulatorEngine(config: SimulatorConfig);
-
-// Playback
-engine.start()
-engine.stop()
-engine.pause()
-engine.resume()
-engine.seek(geometryIndex: number)    // jump to any route index, recalculates bearing
-engine.setSpeed(1 | 2 | 4 | 8)
-
-// Scenarios
-engine.addScenario(scenario: Scenario)
-engine.removeScenario(name: string)
-engine.clearScenarios()
-
-// State
-engine.state        // 'idle' | 'running' | 'paused' | 'complete'
-engine.position     // SimPosition | null
-engine.progress     // 0–1
-
-// Recording
-engine.startRecording(sessionId?: string)
-engine.stopRecording(): SimSession
-
-// Cleanup
-engine.destroy()    // clears all timers — no leaks
-```
-
-**Timer internals:** `setInterval` at `1000ms / speedMultiplier`. Always cleaned up on `destroy()` and on natural completion.
-
-**Callback safety:** All callbacks (`onPositionUpdate`, `onRouteComplete`, `onScenarioStart`, `onScenarioEnd`) are wrapped in `try/catch` — a throwing callback never crashes the engine.
-
----
-
-### RouteWalker
-
-Manages geometry traversal. Extracted from the engine so it's independently testable.
-
-```typescript
-const walker = new RouteWalker(geometry: Coordinate[], startIndex?: number);
-
-walker.advance(steps: number): WalkerPosition      // fractional steps supported
-walker.seek(index: number): WalkerPosition
-walker.interpolate(index: number, fraction: number): Coordinate
-walker.bearingAt(index: number): number            // forward-looking bearing
-
-walker.totalDistanceM   // total route length in metres
-walker.totalPoints      // geometry.length
-walker.isComplete       // true when at last point
-walker.currentIndex     // current floating-point index
-```
-
----
-
-### NoiseEngine
-
-GPS noise simulation using the Box-Muller transform. Zero external dependencies.
-
-```typescript
-const engine = new NoiseEngine(profile: NoiseProfile);
-
-engine.apply(coord: Coordinate): Coordinate   // returns noisy coord (never mutates input)
-engine.setProfile(profile: NoiseProfile)      // hot-swap mid-simulation
-
-// Static presets
-NoiseEngine.NONE       // stdDevM: 0  — exact coordinates
-NoiseEngine.CLEAN      // stdDevM: 3  — good urban GPS
-NoiseEngine.STANDARD   // stdDevM: 12 — matches the original Go4Exams ±0.00011°
-NoiseEngine.URBAN      // stdDevM: 25 — city canyon
-NoiseEngine.DEGRADED   // stdDevM: 50 — bad conditions
-```
-
-**Seeded mode:** Add `seed: number` to any profile for deterministic output — same seed + same route = identical noise trace (critical for regression tests).
-
-```typescript
-const deterministicProfile = { ...NoiseEngine.STANDARD, seed: 42 };
-```
-
----
-
-### ScenarioInjector
-
-Registers scenarios to fire at geometry indices. Called internally by `SimulatorEngine` on every tick.
-
-```typescript
-const injector = new ScenarioInjector(onStart?, onEnd?);
-
-injector.register(scenario: Scenario)
-injector.remove(name: string)
-injector.clear()
-injector.tick(currentIndex: number): string | undefined  // returns active scenario name
-
-// Static factories
-ScenarioInjector.gpsBlackout(atIndex, durationMs)
-ScenarioInjector.wrongSideRoad(atIndex, offsetM)
-ScenarioInjector.uTurn(atIndex)
-ScenarioInjector.speedSpike(atIndex, spikeKmh, durationMs?)
-ScenarioInjector.accuracyDrop(atIndex, newAccuracyM, durationMs)
-```
-
-**No double-fire:** Each scenario fires exactly once per simulation run, even if `tick()` is called with the same index multiple times.
-
----
-
-### GpxParser
-
-Zero-dependency GPX 1.1 parser. Pure string/regex — no DOMParser, no xml2js.
-
-```typescript
-// Parse GPX string
-const result = GpxParser.parse(gpxString: string): GpxParseResult
-
-// Load from file (Node.js only)
-const result = GpxParser.fromFile('/path/to/route.gpx')
-
-// Load from base64 (React Native file picker)
-const result = GpxParser.fromBase64(base64String)
-```
-
-```typescript
-interface GpxParseResult {
-  coordinates: Coordinate[];      // [lng, lat] — NavCore convention
-  timestamps:  number[];          // ms since epoch per point
-  metadata: {
-    name?:        string;
-    totalPoints:  number;
-    durationMs:   number;
-    distanceM:    number;
-    avgSpeedKmh:  number;
-  };
-}
-```
-
-Supports both `<trkpt>` (track points) and `<wpt>` (waypoints).
+### 1. `SimulatorEngine`
+The central stateful playback controller:
+- `start()`: Begin or resume playback.
+- `pause()`: Suspend playback at the current position.
+- `stop()`: Halt simulation and reset to starting coordinate.
+- `seek(geometryIndex: number)`: Jump directly to any waypoint along the route geometry.
+- `setSpeed(multiplier: 1 | 2 | 4 | 8)`: Adjust playback speed.
+- `addScenario(scenario)`: Schedule a fault or anomaly.
+- `startRecording()` / `stopRecording()`: Capture recorded positions as a `SimSession`.
 
----
-
-### SessionRecorder
-
-Records and exports simulation sessions.
-
-```typescript
-const recorder = new SessionRecorder();
-recorder.start(sessionId?: string)
-recorder.stop(existing?: SimSession): SimSession
-
-// Export formats
-recorder.export('json')   // full SimSession as JSON
-recorder.export('gpx')    // standard GPX 1.1 — re-importable by GpxParser
-recorder.export('csv')    // timestamp,lng,lat,bearing,speed,accuracy
-```
-
-**The GPX export is critical:** a recorded session → GPX → `GpxParser` → `SimulatorEngine` creates a full regression test loop.
-
----
-
-### FleetSimulator (Phase 2)
-
-```typescript
-const fleet = FleetSimulator.spawn(5, {
-  routeGeometry: myRoute,
-  speedKmh: 50,
-  noiseProfile: NoiseEngine.STANDARD,
-  profiles: [
-    { label: 'urban', noiseProfile: NoiseEngine.URBAN },
-    { label: 'clean', noiseProfile: NoiseEngine.CLEAN },
-  ],
-});
+### 2. `RouteWalker`
+Deterministic geometric interpolation engine that moves a virtual point along a polyline at a constant physical speed (metres per second), computing exact distance and forward bearing.
 
-fleet.start();
-// ... wait for completion
-const report = fleet.report();
-// report.comparison.avgScoreByProfile
-// report.comparison.deviationsBySegment (heatmap data)
-```
-
-> **@experimental** — fully typed but not tested in Phase 1.
-
----
+### 3. `NoiseEngine`
+Applies Gaussian noise perturbations to latitude, longitude, and bearing based on configurable standard deviations.
 
-## React Native
+### 4. `ScenarioInjector`
+Factory for simulated road anomalies:
+- `ScenarioInjector.gpsBlackout(index, durationMs)`: Emulates tunnels or signal loss by omitting position updates.
+- `ScenarioInjector.accuracyDegradation(index, durationMs, accuracyM)`: Emulates urban canyons with high accuracy error bounds.
+- `ScenarioInjector.speedSpike(index, durationMs, speedMultiplier)`: Simulates vehicle acceleration bursts.
+- `ScenarioInjector.offRouteDrift(index, driftMeters, durationMs)`: Moves vehicle laterally outside the route corridor to trigger off-route FSMs.
 
-### useSimulator
+### 5. `GpxParser`
+Parses `.gpx` XML tracks into arrays of `[longitude, latitude]` coordinates with elevation and timestamps.
 
-Drop-in replacement for `useGpsSimulator`:
+### 6. `SessionRecorder`
+Records simulation output into JSON sessions for regression testing and replay.
 
-```typescript
-// BEFORE
-const simGps = useGpsSimulator(route, isNavigating, speedMultiplier);
-
-// AFTER
-const { position, controls, session, isRecording } = useSimulator({
-  routeGeometry: route,
-  active: isNavigating,
-  config: {
-    speedKmh: 50,
-    speedMultiplier: 1,
-    noiseProfile: NoiseEngine.STANDARD,
-    loop: false,
-  },
-  scenarios: [
-    ScenarioInjector.gpsBlackout(42, 5000),
-    ScenarioInjector.wrongSideRoad(78, 18),
-  ],
-  onScenarioFired: (s) => console.log('Scenario:', s.name),
-});
-
-// position has the exact same shape as the old SimPosition
-// controls: { pause, resume, seek, setSpeed }
-// session: { start, stop }  — for recording
-```
-
-**The engine is recreated only when `routeGeometry` changes** (identity comparison). Destroyed automatically on unmount.
+### 7. `FleetSimulator`
+Simulates multiple concurrent vehicles along independent routes for backend ingestion testing.
 
 ---
 
-### SimulatorControls
+## React Native Integration
 
-Self-contained control panel. Drop it into any screen:
+In React Native apps, render the built-in control overlay:
 
 ```tsx
-<SimulatorControls
-  simulator={controls}
-  session={session}
-  style="minimal"           // 'minimal' | 'full' | 'floating'
-  showScenarioLog={true}
-  showSessionRecorder={true}
-  currentSpeed={1}
-  engineState="running"
-  isRecording={isRecording}
-  onExportSession={(s) => shareFile(JSON.stringify(s))}
-/>
+import React from 'react';
+import { View } from 'react-native';
+import { useSimulator, SimulatorControls } from '@ingissa/navcore-simulator/react-native';
+import { useNavCoreContext } from '@ingissa/navcore-react-native';
+
+export function SimulationScreen({ routeGeometry }) {
+  const { engine: navCore } = useNavCoreContext();
+
+  const { simulator, session, isRecording, currentSpeed } = useSimulator({
+    routeGeometry,
+    speedKmh: 60,
+    onPositionUpdate: (pos) => {
+      navCore.update({
+        coord: pos.coord,
+        accuracy: pos.accuracy,
+        bearing: pos.bearing,
+        speed: pos.speed,
+        timestamp: Date.now(),
+      });
+    },
+  });
+
+  return (
+    <View style={{ flex: 1 }}>
+      <SimulatorControls
+        simulator={simulator}
+        session={session}
+        currentSpeed={currentSpeed}
+        isRecording={isRecording}
+      />
+    </View>
+  );
+}
 ```
 
-| Style | Description |
-|---|---|
-| `minimal` | Horizontal bar: speed selector (1×/2×/4×/8×) + pause/resume |
-| `full` | Card: speed, pause/resume, scenario log, session recorder |
-| `floating` | Collapsible bottom sheet — does not obscure the map |
-
-Uses Klaroways colour tokens (`#081525`, `#00BF76`, etc.) to match `NavCoreTestScreen`.
-
 ---
 
 ## Noise Profiles
 
-| Profile | stdDevM | Use case |
-|---|---|---|
-| `NONE` | 0 | Exact coordinates — CI tests |
-| `CLEAN` | 3 m | Good open-sky GPS |
-| `STANDARD` | 12 m | Matches original Go4Exams ±0.00011° |
-| `URBAN` | 25 m | Dense city canyon |
-| `DEGRADED` | 50 m | Tunnel exit / bad conditions |
-| `CUSTOM` | any | Provide `customFn(index) → [lngOff, latOff]` |
-
----
-
-## Scenario Types
-
-| Type | Factory | Effect |
+| Profile | Standard Deviation (Metres) | Description |
 |---|---|---|
-| `GPS_BLACKOUT` | `gpsBlackout(idx, ms)` | Pauses noise application (dead reckoning stress test) |
-| `WRONG_SIDE_ROAD` | `wrongSideRoad(idx, offsetM)` | Position offset perpendicular to route |
-| `UTURN` | `uTurn(idx)` | Fires at index — engine handles turn logic |
-| `SPEED_SPIKE` | `speedSpike(idx, kmh)` | Temporarily reports higher speed |
-| `ACCURACY_DROP` | `accuracyDrop(idx, m, ms)` | GPS accuracy degrades to `m` metres for `ms` |
-| `CUSTOM` | — | Provide `params` manually |
-
----
-
-## GPX Round-Trip Loop
-
-```
-real GPS trace
-     ↓
-  .gpx file
-     ↓
- GpxParser.parse()
-     ↓
- SimulatorEngine (replay with noise + scenarios)
-     ↓
- SessionRecorder.export('gpx')
-     ↓
- GpxParser.parse()  ←── CI assertion: reparsed.coordinates.length === session.positions.length
-     ↓
- Next regression run
-```
-
-This loop is the foundation of the CI strategy. Every format change to `SessionRecorder._toGpx()` that breaks `GpxParser.parse()` will fail the integration test immediately.
-
----
-
-## CI / Regression Testing
-
-```bash
-cd packages/navcore-sdk
-npx vitest run --reporter=verbose
-```
-
-Test files:
-- `packages/simulator/src/core/__tests__/RouteWalker.test.ts`
-- `packages/simulator/src/core/__tests__/NoiseEngine.test.ts`
-- `packages/simulator/src/core/__tests__/SimulatorEngine.test.ts`
-- `packages/simulator/src/scenarios/__tests__/ScenarioInjector.test.ts`
-- `packages/simulator/src/replay/__tests__/GpxParser.test.ts`
-- `packages/simulator/src/__tests__/integration/simulator-pipeline.test.ts`
-
-All tests use `vi.useFakeTimers()` — no real waiting, no flakiness.
+| `NONE` | 0 m | Zero jitter; exact mathematical coordinates on the polyline |
+| `LOW` | 4 m | High-quality open-sky dual-frequency GNSS |
+| `STANDARD` | 12 m | Typical smartphone GPS accuracy in suburban conditions |
+| `URBAN_CANYON` | 35 m | Severe multipath reflection and tall building interference |
 
 ---
 
-## Migration from useGpsSimulator
-
-The migration is a **search-and-replace**, not a rewrite.
-
-### 1. Remove the inline hook and local type
-
-Delete `useGpsSimulator` function (lines 114–174 in `NavCoreTestScreen`) and the local `SimPosition` interface.
-
-### 2. Add import
+## CI Regression Testing
 
 ```typescript
-import {
-  useSimulator,
-  SimulatorControls,
-  NoiseEngine,
-  ScenarioInjector,
-} from '../../../../packages/navcore-sdk/packages/simulator/src';
-```
-
-### 3. Replace the hook call
-
-```typescript
-// Before
-const simGps = useGpsSimulator(route, isNavigating, speed);
-
-// After
-const { position: simGps, controls } = useSimulator({
-  routeGeometry: route,
-  active: isNavigating,
-  config: { speedKmh: 50, noiseProfile: NoiseEngine.STANDARD },
+import { describe, it, expect } from 'vitest';
+import { NavCore } from '@ingissa/navcore-core';
+import { SimulatorEngine, NoiseEngine } from '@ingissa/navcore-simulator/node';
+
+describe('Navigation Regression', () => {
+  it('navigates route without spurious off-route alerts under normal noise', () => {
+    const route = [[2.3522, 48.8566], [2.3400, 48.8650], [2.3009, 48.8741]];
+    const nav = new NavCore({ isDev: true });
+    nav.setRoute(route);
+    nav.startNavigation();
+
+    let offRouteFired = false;
+    nav.on('deviation', () => { offRouteFired = true; });
+
+    const sim = new SimulatorEngine({
+      routeGeometry: route,
+      noiseProfile: NoiseEngine.LOW,
+      speedMultiplier: 8,
+      onPositionUpdate: (pos) => {
+        nav.update({
+          coord: pos.coord,
+          accuracy: pos.accuracy,
+          bearing: pos.bearing,
+          speed: pos.speed,
+          timestamp: Date.now(),
+        });
+      },
+    });
+
+    sim.start();
+    // Verify engine state upon completion
+    expect(offRouteFired).toBe(false);
+  });
 });
 ```
 
-### 4. Replace the speed UI
+---
 
-```tsx
-// Before: 40 lines of inline speedRow JSX + speed state
-// After:
-<SimulatorControls simulator={controls} style="minimal" />
-```
+## Licensing
+
+- [Simulator Guide](https://github.com/ingissa/navcore-sdk/blob/main/docs/simulator.md)
+- [API Reference](https://github.com/ingissa/navcore-sdk/blob/main/docs/api-reference/navcore-simulator.md)
+- [Official Website](https://navcore-web.vercel.app/)
 
-The `position` object shape is **identical** to the original `SimPosition` — `coord`, `bearing`, `speed`, `accuracy` are all present.
+Proprietary software. Copyright (c) 2026 Abdelnasser Aitabi. All rights reserved. No license is granted except by separate written agreement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingissa/navcore-simulator",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Headless GPS simulator for NavCore. Works in Node.js, React Native, and CI.",
   "author": "Ingissa <8abnav@gmail.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -43,7 +43,7 @@
     "prepublishOnly": "npm run build --prefix ../.. && node ../../scripts/check-release.mjs"
   },
   "peerDependencies": {
-    "@ingissa/navcore-core": "^1.0.9",
+    "@ingissa/navcore-core": "^1.0.11",
     "react": ">=18",
     "react-native": ">=0.72"
   },