@ingissa/navcore-simulator 1.0.4 → 1.0.7

package/dist/core/src/snapper/ParallelRoadResolver.js

@@ -0,0 +1,83 @@
+/**
+ * ParallelRoadResolver
+ *
+ * First-class feature: resolve GPS ambiguity on parallel roads (e.g. dual carriageways,
+ * motorway + service road) and prevent U-turn snap.
+ *
+ * Extracts and extends the bearing penalty + inertia logic from RouteSnapper
+ * into a standalone, composable API that can be used independently.
+ *
+ * FEATURE: PARALLEL_ROAD_RESOLUTION + U_TURN_PROTECTION
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ParallelRoadResolver({ bearingPenalty: 80, inertiaPenalty: 40 });
+ * const best = resolver.resolve(candidates, vehicleBearing, prevSegmentIndex);
+ * ```
+ */
+import { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+const DEFAULTS = {
+    bearingPenalty: 80,
+    bearingMismatchThresholdDeg: 60,
+    inertiaPenalty: 40,
+    inertiaSegmentDist: 3,
+};
+export class ParallelRoadResolver {
+    constructor(options) {
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /**
+     * Score and sort snap candidates — lowest score wins.
+     *
+     * @param candidates   Raw snap candidates (distance-sorted or unsorted)
+     * @param vehicleBearing  Current vehicle heading in degrees (null disables bearing check)
+     * @param prevSegmentIdx  Previously snapped segment index (null disables inertia)
+     * @returns Candidates sorted by score ascending, with debug metadata attached
+     */
+    resolve(candidates, vehicleBearing = null, prevSegmentIdx = null) {
+        return candidates
+            .map(c => this.score(c, vehicleBearing, prevSegmentIdx))
+            .sort((a, b) => a.score - b.score);
+    }
+    /**
+     * Resolve and return only the best candidate.
+     */
+    resolveBest(candidates, vehicleBearing = null, prevSegmentIdx = null) {
+        if (candidates.length === 0)
+            return null;
+        const resolved = this.resolve(candidates, vehicleBearing, prevSegmentIdx);
+        return resolved[0] ?? null;
+    }
+    score(c, vehicleBearing, prevSegmentIdx) {
+        let score = c.distanceMetres;
+        let bearingDeltaDeg = null;
+        let inertiaPenaltyApplied = false;
+        // ── U-turn / parallel road bearing penalty ───────────────────────────────
+        if (vehicleBearing !== null) {
+            const segBearing = getBearingBetweenPoints(c.segA, c.segB);
+            const delta = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+            bearingDeltaDeg = delta;
+            if (delta > this.options.bearingMismatchThresholdDeg) {
+                score += this.options.bearingPenalty;
+            }
+        }
+        // ── Inertia penalty (anti-oscillation) ───────────────────────────────────
+        if (prevSegmentIdx !== null &&
+            Math.abs(c.segmentIndex - prevSegmentIdx) >= this.options.inertiaSegmentDist) {
+            score += this.options.inertiaPenalty;
+            inertiaPenaltyApplied = true;
+        }
+        return { ...c, score, bearingDeltaDeg, inertiaPenaltyApplied };
+    }
+    /**
+     * Quick utility: detect if the vehicle is likely performing a U-turn
+     * based on the difference between current bearing and route segment bearing.
+     *
+     * @returns true if the bearing difference exceeds the configured threshold
+     */
+    isLikelyUTurn(vehicleBearing, segA, segB) {
+        const segBearing = getBearingBetweenPoints(segA, segB);
+        const delta = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+        return delta > this.options.bearingMismatchThresholdDeg;
+    }
+}

package/dist/core/src/snapper/RouteSnapper.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Module 2: RouteSnapper
+ * Projects GPS coordinates onto the route with anti-oscillation and U-turn protection.
+ * Merges BasicSnapper + AdvancedSnapper from nav-sdk into a single module.
+ */
+import { type Coordinate } from '../geo/haversine';
+export interface SnapResult {
+    idx: number;
+    dist: number;
+    proj: Coordinate;
+}
+export interface SnapperOptions {
+    /** Enable bearing-based U-turn anti-snap penalty */
+    useBearingPenalty?: boolean;
+    /** Enable inertia penalty to prevent oscillation between segments */
+    useInertiaPenalty?: boolean;
+    /** Max search distance hard cutoff (metres) */
+    maxSnapDistance?: number;
+}
+export declare class RouteSnapper {
+    private readonly options;
+    constructor(options?: SnapperOptions);
+    /**
+     * Find the nearest projection of a GPS point onto the route.
+     *
+     * @param gps             Current GPS coordinate [lng, lat]
+     * @param route           Route geometry
+     * @param startIdx        Search window start
+     * @param windowSize      Number of segments to scan
+     * @param isCircuit       Whether the route is a closed circuit
+     * @param maxProgressIdx  Highest index ever reached (for circuit wrap detection)
+     * @param fallbackIdx     Fallback index if no match found
+     * @param vehicleBearing  Current vehicle bearing (null disables bearing penalty)
+     * @param prevSegment     Previous snapped segment index (null disables inertia)
+     */
+    snap(gps: Coordinate, route: Coordinate[], startIdx: number, windowSize: number, isCircuit: boolean, maxProgressIdx: number, fallbackIdx: number, vehicleBearing?: number | null, prevSegment?: number | null): SnapResult;
+}
+//# sourceMappingURL=RouteSnapper.d.ts.map

package/dist/core/src/snapper/RouteSnapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteSnapper.d.ts","sourceRoot":"","sources":["../../../../../core/src/snapper/RouteSnapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,kBAAkB,CAAC;AAWtE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAQD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,OAAO,CAAC,EAAE,cAAc;IAIpC;;;;;;;;;;;;OAYG;IACH,IAAI,CACF,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,EAClB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,MAAM,GAAG,IAAW,EACpC,WAAW,GAAE,MAAM,GAAG,IAAW,GAChC,UAAU;CAuDd"}

package/dist/core/src/snapper/RouteSnapper.js

@@ -0,0 +1,80 @@
+/**
+ * Module 2: RouteSnapper
+ * Projects GPS coordinates onto the route with anti-oscillation and U-turn protection.
+ * Merges BasicSnapper + AdvancedSnapper from nav-sdk into a single module.
+ */
+import { haversineDistance } from '../geo/haversine';
+import { projectPointOnSegment } from '../geo/projection';
+import { getBearingBetweenPoints, normalizeAngle } from '../geo/bearing';
+import { MAX_SNAP_DISTANCE, BEARING_MISMATCH_THRESHOLD, BEARING_MISMATCH_PENALTY, INERTIA_PENALTY, INERTIA_SEGMENT_DIST } from '../constants';
+const DEFAULT_OPTIONS = {
+    useBearingPenalty: true,
+    useInertiaPenalty: true,
+    maxSnapDistance: MAX_SNAP_DISTANCE,
+};
+export class RouteSnapper {
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Find the nearest projection of a GPS point onto the route.
+     *
+     * @param gps             Current GPS coordinate [lng, lat]
+     * @param route           Route geometry
+     * @param startIdx        Search window start
+     * @param windowSize      Number of segments to scan
+     * @param isCircuit       Whether the route is a closed circuit
+     * @param maxProgressIdx  Highest index ever reached (for circuit wrap detection)
+     * @param fallbackIdx     Fallback index if no match found
+     * @param vehicleBearing  Current vehicle bearing (null disables bearing penalty)
+     * @param prevSegment     Previous snapped segment index (null disables inertia)
+     */
+    snap(gps, route, startIdx, windowSize, isCircuit, maxProgressIdx, fallbackIdx, vehicleBearing = null, prevSegment = null) {
+        const routeLength = route.length;
+        let bestIdx = fallbackIdx;
+        let bestScore = Infinity;
+        let bestDist = Infinity;
+        let bestProj = route[fallbackIdx] ?? [0, 0];
+        for (let step = 0; step <= windowSize; step++) {
+            let i = startIdx + step;
+            if (i > routeLength - 2) {
+                if (isCircuit && maxProgressIdx > routeLength * 0.7) {
+                    i = i % (routeLength - 1);
+                }
+                else {
+                    break;
+                }
+            }
+            if (i < 0 || i >= routeLength - 1)
+                continue;
+            const segA = route[i];
+            const segB = route[i + 1];
+            const p = projectPointOnSegment(gps, segA, segB);
+            const d = haversineDistance(gps[1], gps[0], p[1], p[0]);
+            // Hard cutoff
+            if (d > this.options.maxSnapDistance * 2)
+                continue;
+            let score = d;
+            // ── Bearing penalty (U-turn anti-snap) ──────────────────────────────
+            if (this.options.useBearingPenalty && vehicleBearing !== null) {
+                const segBearing = getBearingBetweenPoints(segA, segB);
+                const bearingDiff = Math.abs(normalizeAngle(vehicleBearing - segBearing));
+                if (bearingDiff > BEARING_MISMATCH_THRESHOLD) {
+                    score += BEARING_MISMATCH_PENALTY;
+                }
+            }
+            // ── Inertia penalty ─────────────────────────────────────────────────
+            if (this.options.useInertiaPenalty && prevSegment !== null &&
+                Math.abs(i - prevSegment) >= INERTIA_SEGMENT_DIST) {
+                score += INERTIA_PENALTY;
+            }
+            if (score < bestScore) {
+                bestScore = score;
+                bestDist = d;
+                bestIdx = i;
+                bestProj = p;
+            }
+        }
+        return { idx: bestIdx, dist: bestDist, proj: bestProj };
+    }
+}

package/dist/core/src/voice/VoiceTriggerEngine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * VoiceTriggerEngine
+ *
+ * Converts NavCore instruction events into timed voice cues.
+ * Handles deduplication, look-ahead windows, and priority levels.
+ * Consumer calls TTS — this engine only computes WHEN to speak.
+ *
+ * FEATURE: VOICE_TRIGGERS
+ *
+ * @example
+ * ```typescript
+ * const voice = new VoiceTriggerEngine({ earlyTriggerMeters: 150 });
+ * voice.setInstructions(instructions);
+ *
+ * engine.on('instruction', (instr) => {
+ *   const cue = voice.onInstruction(instr, state);
+ *   if (cue) speakText(cue.text);
+ * });
+ *
+ * // Or poll each GPS tick:
+ * const cue = voice.update(state);
+ * if (cue) speakText(cue.text);
+ * ```
+ */
+import type { NavInstruction } from '../progress/InstructionResolver';
+import type { NavCoreState } from '../NavCore';
+export type VoicePriority = 'low' | 'normal' | 'high' | 'urgent';
+export interface VoiceCue {
+    /** The instruction that triggered this cue */
+    instruction: NavInstruction;
+    /** Text to pass to TTS */
+    text: string;
+    /** Distance to the instruction point in metres */
+    distanceMetres: number;
+    /** Priority hint for TTS queue management */
+    priority: VoicePriority;
+    /** Monotonic trigger ID — use this to deduplicate */
+    triggerId: string;
+}
+export interface VoiceTriggerOptions {
+    /**
+     * Trigger voice this many metres before the instruction point.
+     * Default: 120m (comfortable at 50 km/h).
+     */
+    earlyTriggerMeters?: number;
+    /**
+     * Stop trying to trigger if vehicle is already past this many metres.
+     * Default: 20m.
+     */
+    lateTriggerMeters?: number;
+    /**
+     * Re-announce if user is still approaching after this distance.
+     * Set to 0 to disable re-announcement.  Default: 300m.
+     */
+    reannounceMeters?: number;
+}
+export declare class VoiceTriggerEngine {
+    private instructions;
+    private triggeredIds;
+    private reannouncedIds;
+    private readonly options;
+    constructor(options?: VoiceTriggerOptions);
+    /** Load the instruction set (call after engine.setRoute) */
+    setInstructions(instructions: NavInstruction[]): void;
+    /**
+     * Poll on every GPS state update.
+     * Returns a `VoiceCue` when an instruction should be spoken, or null.
+     */
+    update(state: NavCoreState): VoiceCue | null;
+    /**
+     * Called directly from engine's 'instruction' event.
+     * Always fires immediately regardless of distance window.
+     */
+    onInstruction(instr: NavInstruction, state: NavCoreState): VoiceCue;
+    /** Reset triggered state (call on setRoute / new journey) */
+    reset(): void;
+    private instrId;
+    private makeCue;
+}
+//# sourceMappingURL=VoiceTriggerEngine.d.ts.map

package/dist/core/src/voice/VoiceTriggerEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoiceTriggerEngine.d.ts","sourceRoot":"","sources":["../../../../../core/src/voice/VoiceTriggerEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,QAAQ;IACvB,8CAA8C;IAC9C,WAAW,EAAE,cAAc,CAAC;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,EAAE,aAAa,CAAC;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAQD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;gBAE5C,OAAO,CAAC,EAAE,mBAAmB;IAIzC,4DAA4D;IAC5D,eAAe,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,IAAI;IAMrD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,GAAG,IAAI;IA6C5C;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,GAAG,QAAQ;IAKnE,6DAA6D;IAC7D,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,OAAO;CAShB"}

package/dist/core/src/voice/VoiceTriggerEngine.js

@@ -0,0 +1,108 @@
+/**
+ * VoiceTriggerEngine
+ *
+ * Converts NavCore instruction events into timed voice cues.
+ * Handles deduplication, look-ahead windows, and priority levels.
+ * Consumer calls TTS — this engine only computes WHEN to speak.
+ *
+ * FEATURE: VOICE_TRIGGERS
+ *
+ * @example
+ * ```typescript
+ * const voice = new VoiceTriggerEngine({ earlyTriggerMeters: 150 });
+ * voice.setInstructions(instructions);
+ *
+ * engine.on('instruction', (instr) => {
+ *   const cue = voice.onInstruction(instr, state);
+ *   if (cue) speakText(cue.text);
+ * });
+ *
+ * // Or poll each GPS tick:
+ * const cue = voice.update(state);
+ * if (cue) speakText(cue.text);
+ * ```
+ */
+const DEFAULTS = {
+    earlyTriggerMeters: 120,
+    lateTriggerMeters: 20,
+    reannounceMeters: 300,
+};
+export class VoiceTriggerEngine {
+    constructor(options) {
+        this.instructions = [];
+        this.triggeredIds = new Set();
+        this.reannouncedIds = new Set();
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /** Load the instruction set (call after engine.setRoute) */
+    setInstructions(instructions) {
+        this.instructions = [...instructions];
+        this.triggeredIds.clear();
+        this.reannouncedIds.clear();
+    }
+    /**
+     * Poll on every GPS state update.
+     * Returns a `VoiceCue` when an instruction should be spoken, or null.
+     */
+    update(state) {
+        const { distanceToNextInstruction, nextInstructionIndex } = state;
+        if (nextInstructionIndex === null ||
+            distanceToNextInstruction === null ||
+            nextInstructionIndex >= this.instructions.length) {
+            return null;
+        }
+        const instr = this.instructions[nextInstructionIndex];
+        const id = this.instrId(nextInstructionIndex);
+        const dist = distanceToNextInstruction;
+        // Already fully triggered — don't repeat
+        if (this.triggeredIds.has(id)) {
+            // Check re-announce window
+            if (this.options.reannounceMeters > 0 &&
+                !this.reannouncedIds.has(id) &&
+                dist <= this.options.reannounceMeters &&
+                dist > this.options.earlyTriggerMeters) {
+                this.reannouncedIds.add(id);
+                return this.makeCue(instr, dist, 'low');
+            }
+            return null;
+        }
+        // Too far — not yet
+        if (dist > this.options.earlyTriggerMeters)
+            return null;
+        // Already passed — too late
+        if (dist < -this.options.lateTriggerMeters) {
+            this.triggeredIds.add(id); // mark so we skip
+            return null;
+        }
+        // In the trigger window — fire!
+        this.triggeredIds.add(id);
+        const priority = dist < 30 ? 'urgent' : dist < 60 ? 'high' : 'normal';
+        return this.makeCue(instr, dist, priority);
+    }
+    /**
+     * Called directly from engine's 'instruction' event.
+     * Always fires immediately regardless of distance window.
+     */
+    onInstruction(instr, state) {
+        const dist = state.distanceToNextInstruction ?? 0;
+        return this.makeCue(instr, dist, 'high');
+    }
+    /** Reset triggered state (call on setRoute / new journey) */
+    reset() {
+        this.triggeredIds.clear();
+        this.reannouncedIds.clear();
+    }
+    instrId(index) {
+        const instr = this.instructions[index];
+        return `${index}_${instr?.geometryIndex ?? 0}`;
+    }
+    makeCue(instr, dist, priority) {
+        return {
+            instruction: instr,
+            text: instr.text ?? instr.instruction ?? '',
+            distanceMetres: Math.max(0, dist),
+            priority,
+            triggerId: `${instr.geometryIndex}_${dist.toFixed(0)}`,
+        };
+    }
+}

package/dist/simulator/src/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 '@ingissa/navcore-core';
+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/simulator/src/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,uBAAuB,CAAC;AACxD,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/simulator/src/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/simulator/src/core/RouteWalker.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 '@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 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;
+    /**
+     * Alias for distanceAtIndex.
+     */
+    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/simulator/src/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,uBAAuB,CAAC;AAExD,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;;OAEG;IACH,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"}