@ingissa/navcore-simulator 1.0.8 → 1.0.10

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,64 +1,92 @@
-# @ingissa/navcore-simulator
+# @ingissa/navcore-simulator
+
+[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();
 ```
 
@@ -66,361 +94,138 @@ engine.start();
 
 ## Core Classes
 
-### SimulatorEngine
-
-The main orchestrator. Headless — no React, no Expo APIs. Runs in Node.js CI.
+### 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`.
 
-```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
-```
+### 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.
 
-**Timer internals:** `setInterval` at `1000ms / speedMultiplier`. Always cleaned up on `destroy()` and on natural completion.
+### 3. `NoiseEngine`
+Applies Gaussian noise perturbations to latitude, longitude, and bearing based on configurable standard deviations.
 
-**Callback safety:** All callbacks (`onPositionUpdate`, `onRouteComplete`, `onScenarioStart`, `onScenarioEnd`) are wrapped in `try/catch` — a throwing callback never crashes the engine.
+### 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.
 
----
+### 5. `GpxParser`
+Parses `.gpx` XML tracks into arrays of `[longitude, latitude]` coordinates with elevation and timestamps.
 
-### RouteWalker
+### 6. `SessionRecorder`
+Records simulation output into JSON sessions for regression testing and replay.
 
-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
-```
+### 7. `FleetSimulator`
+Simulates multiple concurrent vehicles along independent routes for backend ingestion testing.
 
 ---
 
-### 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
+## React Native Integration
 
-// 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).
-
----
-
-### 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 },
-  ],
-});
-
-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.
-
----
-
-## React Native
-
-### useSimulator
-
-Drop-in replacement for `useGpsSimulator`:
-
-```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.
-
----
-
-### SimulatorControls
-
-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](../../docs/simulator.md)
+- [API Reference](../../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/dist/index.d.mts

@@ -0,0 +1,87 @@
+import { SimSession, SimulatorConfig, Scenario, SimPosition, SimLocationObject } from './node.mjs';
+export { Coordinate, EngineState, ExportFormat, FleetReport, FleetSimulator, GpxParseResult, GpxParser, NoiseEngine, NoiseProfile, RouteWalker, ScenarioInjector, SessionRecorder, SimLocationCoords, SimulatorEngine, VehicleProfile, WalkerPosition } from './node.mjs';
+import { Coordinate } from '@ingissa/navcore-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 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 },
+ *   })
+ */
+
+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;
+}
+interface SimulatorControls$1 {
+    pause: () => void;
+    resume: () => void;
+    seek: (geometryIndex: number) => void;
+    setSpeed: (multiplier: 1 | 2 | 4 | 8) => void;
+}
+interface SessionControls {
+    start: (sessionId?: string) => void;
+    stop: () => SimSession | null;
+}
+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$1;
+    /** Recording controls */
+    session: SessionControls;
+    /** Whether a recording is in progress */
+    isRecording: boolean;
+}
+declare function useSimulator(options: UseSimulatorOptions): UseSimulatorResult;
+
+interface ScenarioLogEntry {
+    ts: number;
+    name: string;
+    type: string;
+}
+interface SimulatorControlsProps {
+    simulator: SimulatorControls$1;
+    session?: SessionControls;
+    style?: 'minimal' | 'full' | 'floating';
+    showScenarioLog?: boolean;
+    showSessionRecorder?: boolean;
+    scenarioLog?: ScenarioLogEntry[];
+    /** Current speed multiplier (controlled externally) */
+    currentSpeed?: 1 | 2 | 4 | 8;
+    /** Current engine state */
+    engineState?: 'idle' | 'running' | 'paused' | 'complete';
+    isRecording?: boolean;
+    onExportSession?: (session: SimSession) => void;
+    /** Additional style for the root container */
+    containerStyle?: object;
+}
+declare function SimulatorControls({ simulator, session, style, showScenarioLog, showSessionRecorder, scenarioLog, currentSpeed, engineState, isRecording, onExportSession, containerStyle, }: SimulatorControlsProps): react_jsx_runtime.JSX.Element;
+
+export { Scenario, type ScenarioLogEntry, SimLocationObject, SimPosition, SimSession, SimulatorConfig, SimulatorControls, useSimulator };