@ingissa/navcore-simulator 1.0.3

package/README.md

@@ -0,0 +1,426 @@
+# @ingissa/navcore-simulator
+
+> Headless GPS simulation engine for the NavCore ecosystem.
+> Works in **Node.js** (CI), **React Native**, and any JavaScript environment.
+
+---
+
+## Contents
+
+- [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)
+- [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)
+
+---
+
+## Installation
+
+```bash
+# Inside the go4exams monorepo — already available via workspace
+# Import directly from the source tree:
+import { SimulatorEngine, NoiseEngine } from '@ingissa/navcore-simulator'
+```
+
+**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).
+
+---
+
+## Quick Start
+
+```typescript
+import { SimulatorEngine, NoiseEngine, ScenarioInjector } from '@ingissa/navcore-simulator';
+
+const engine = new SimulatorEngine({
+  routeGeometry: myRoute,       // Coordinate[] from @ingissa/navcore-core
+  speedKmh: 50,
+  speedMultiplier: 4,           // 4× real-time
+  noiseProfile: NoiseEngine.STANDARD,
+  loop: false,
+  onPositionUpdate: (pos) => {
+    console.log(pos.coord, pos.bearing, pos.speed);
+  },
+  onRouteComplete: () => console.log('Route complete'),
+});
+
+engine.addScenario(ScenarioInjector.gpsBlackout(42, 5000));
+engine.startRecording();
+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).
+
+---
+
+### 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:
+
+```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))}
+/>
+```
+
+| 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 |
+|---|---|---|
+| `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.
+
+---
+
+## 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
+
+```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 },
+});
+```
+
+### 4. Replace the speed UI
+
+```tsx
+// Before: 40 lines of inline speedRow JSX + speed state
+// After:
+<SimulatorControls simulator={controls} style="minimal" />
+```
+
+The `position` object shape is **identical** to the original `SimPosition` — `coord`, `bearing`, `speed`, `accuracy` are all present.

package/dist/core/NoiseEngine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 './types';
+import type { NoiseProfile } from './types';
+export declare class NoiseEngine {
+    private profile;
+    private rng;
+    private _tickIndex;
+    constructor(profile: NoiseProfile);
+    /** No noise — returns the exact coordinate */
+    static readonly NONE: NoiseProfile;
+    /** Good urban GPS — ~3m standard deviation */
+    static readonly CLEAN: NoiseProfile;
+    /** Standard Go4Exams value — ~12m standard deviation (matches original ±0.00011°) */
+    static readonly STANDARD: NoiseProfile;
+    /** Dense city canyon — ~25m standard deviation */
+    static readonly URBAN: NoiseProfile;
+    /** Bad conditions — ~50m standard deviation */
+    static readonly DEGRADED: NoiseProfile;
+    /**
+     * Apply noise to a coordinate.
+     * Returns a new coordinate — never mutates the input.
+     */
+    apply(coord: Coordinate): Coordinate;
+    /** Hot-swap the noise profile mid-simulation */
+    setProfile(profile: NoiseProfile): void;
+    get currentProfile(): NoiseProfile;
+    /**
+     * Box-Muller transform: produces Gaussian N(0, stdDev²) offset.
+     * Returns [lngOffset, latOffset] in degrees.
+     */
+    private _gaussianOffset;
+    /** Returns a float in [0, 1) — uses seeded RNG if available, else Math.random */
+    private _rand;
+}
+//# sourceMappingURL=NoiseEngine.d.ts.map

package/dist/core/NoiseEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoiseEngine.d.ts","sourceRoot":"","sources":["../../src/core/NoiseEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAyB5C,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,UAAU,CAAK;gBAEX,OAAO,EAAE,YAAY;IAOjC,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAgC;IAElE,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAoC;IAEvE,qFAAqF;IACrF,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAqC;IAE3E,kDAAkD;IAClD,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAkC;IAErE,+CAA+C;IAC/C,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAqC;IAI3E;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IA6BpC,gDAAgD;IAChD,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAMvC,IAAI,cAAc,IAAI,YAAY,CAEjC;IAID;;;OAGG;IACH,OAAO,CAAC,eAAe;IAcvB,iFAAiF;IACjF,OAAO,CAAC,KAAK;CAGd"}

package/dist/core/NoiseEngine.js

@@ -0,0 +1,106 @@
+/**
+ * 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)
+ */
+// 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 {
+    constructor(seed) {
+        this.state = seed >>> 0; // ensure unsigned 32-bit
+    }
+    /** Returns a float in [0, 1) */
+    next() {
+        // LCG parameters from Numerical Recipes
+        this.state = (Math.imul(1664525, this.state) + 1013904223) >>> 0;
+        return this.state / 0x100000000;
+    }
+}
+export class NoiseEngine {
+    constructor(profile) {
+        this._tickIndex = 0;
+        this.profile = profile;
+        this.rng = profile.seed !== undefined ? new SeededRandom(profile.seed) : null;
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Apply noise to a coordinate.
+     * Returns a new coordinate — never mutates the input.
+     */
+    apply(coord) {
+        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) {
+        this.profile = profile;
+        this.rng = profile.seed !== undefined ? new SeededRandom(profile.seed) : null;
+        this._tickIndex = 0;
+    }
+    get currentProfile() {
+        return this.profile;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    /**
+     * Box-Muller transform: produces Gaussian N(0, stdDev²) offset.
+     * Returns [lngOffset, latOffset] in degrees.
+     */
+    _gaussianOffset(stdDevM) {
+        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 */
+    _rand() {
+        return this.rng ? this.rng.next() : Math.random();
+    }
+}
+// ── Static presets ─────────────────────────────────────────────────────────
+/** No noise — returns the exact coordinate */
+NoiseEngine.NONE = { type: 'NONE', stdDevM: 0 };
+/** Good urban GPS — ~3m standard deviation */
+NoiseEngine.CLEAN = { type: 'GAUSSIAN', stdDevM: 3 };
+/** Standard Go4Exams value — ~12m standard deviation (matches original ±0.00011°) */
+NoiseEngine.STANDARD = { type: 'GAUSSIAN', stdDevM: 12 };
+/** Dense city canyon — ~25m standard deviation */
+NoiseEngine.URBAN = { type: 'URBAN', stdDevM: 25 };
+/** Bad conditions — ~50m standard deviation */
+NoiseEngine.DEGRADED = { type: 'GAUSSIAN', stdDevM: 50 };

package/dist/core/RouteWalker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 type { Coordinate } from './types';
+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 declare class RouteWalker {
+    private readonly geometry;
+    private _index;
+    private _distanceTravelled;
+    private readonly _cumulativeDistances;
+    private _isComplete;
+    constructor(geometry: Coordinate[], startIndex?: number);
+    /**
+     * Advance the walker by `steps` geometry points.
+     * Fractional steps are supported for sub-second precision.
+     */
+    advance(steps: number): WalkerPosition;
+    /**
+     * Advance the walker by a physical distance in metres.
+     * This is the preferred way for smooth constant-speed simulation.
+     */
+    advanceByDistance(meters: number): WalkerPosition;
+    private _finalizeAdvance;
+    /**
+     * Seek directly to a geometry index (integer or fractional).
+     * Recalculates bearing from the new position.
+     */
+    seek(index: number): WalkerPosition;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Total haversine distance from the route start to the given index.
+     * Uses the pre-computed cumulative distances (O(1)).
+     */
+    distanceAtIndex(index: number): number;
+    distanceToIndex(index: number): number;
+    /**
+     * Convert a distance in metres back to a fractional index.
+     * Uses binary search for O(log N) performance.
+     */
+    private _distanceToIndex;
+    get totalDistanceM(): number;
+    get totalPoints(): number;
+    get isComplete(): boolean;
+    get currentIndex(): number;
+    private _currentPosition;
+    /** Interpolate cumulative distance for fractional index */
+    private _interpolatedDistance;
+}
+//# sourceMappingURL=RouteWalker.d.ts.map

package/dist/core/RouteWalker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteWalker.d.ts","sourceRoot":"","sources":["../../src/core/RouteWalker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,KAAK,EAAE,UAAU,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAW;IAChD,OAAO,CAAC,WAAW,CAAU;gBAEjB,QAAQ,EAAE,UAAU,EAAE,EAAE,UAAU,SAAI;IAuBlD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAMtC;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;IAejD,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAOnC;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAQxD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOhC;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAKtC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAItC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAgCxB,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAID,OAAO,CAAC,gBAAgB;IAexB,2DAA2D;IAC3D,OAAO,CAAC,qBAAqB;CAQ9B"}