@ingissa/navcore-simulator 1.0.4 → 1.0.8

package/dist/simulator/src/react-native/useSimulator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 },
+ *   })
+ */
+import type { SimPosition, SimulatorConfig, SimSession, Scenario, SimLocationObject } from '../core/types';
+import type { Coordinate } from '@ingissa/navcore-core';
+export 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;
+}
+export interface SimulatorControls {
+    pause: () => void;
+    resume: () => void;
+    seek: (geometryIndex: number) => void;
+    setSpeed: (multiplier: 1 | 2 | 4 | 8) => void;
+}
+export interface SessionControls {
+    start: (sessionId?: string) => void;
+    stop: () => SimSession | null;
+}
+export 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;
+    /** Recording controls */
+    session: SessionControls;
+    /** Whether a recording is in progress */
+    isRecording: boolean;
+}
+export declare function useSimulator(options: UseSimulatorOptions): UseSimulatorResult;
+//# sourceMappingURL=useSimulator.d.ts.map

package/dist/simulator/src/react-native/useSimulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSimulator.d.ts","sourceRoot":"","sources":["../../../../src/react-native/useSimulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,aAAa,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACnC,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,eAAe,GAAG,kBAAkB,GAAG,iBAAiB,CAAC,CAAC,CAAC;IAClG,+BAA+B;IAC/B,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,mCAAmC;IACnC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC/C,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,IAAI,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,EAAE,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,IAAI,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,wBAAwB;IACxB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,yBAAyB;IACzB,OAAO,EAAE,eAAe,CAAC;IACzB,yCAAyC;IACzC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAwF7E"}

package/dist/simulator/src/react-native/useSimulator.js

@@ -0,0 +1,100 @@
+/**
+ * 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 },
+ *   })
+ */
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { SimulatorEngine } from '../core/SimulatorEngine';
+import { NoiseEngine } from '../core/NoiseEngine';
+export function useSimulator(options) {
+    const { routeGeometry, active, config = {}, scenarios = [], onScenarioFired } = options;
+    const [position, setPosition] = useState(null);
+    const [isRecording, setIsRecording] = useState(false);
+    const engineRef = useRef(null);
+    // Keep a stable ref to the latest onScenarioFired callback
+    const onScenarioFiredRef = useRef(onScenarioFired);
+    onScenarioFiredRef.current = onScenarioFired;
+    // Create / recreate the engine whenever the route geometry changes
+    useEffect(() => {
+        if (!routeGeometry || routeGeometry.length < 2) {
+            setPosition(null);
+            return;
+        }
+        const engine = new SimulatorEngine({
+            routeGeometry,
+            speedKmh: config.speedKmh ?? 50,
+            speedMultiplier: config.speedMultiplier ?? 1,
+            noiseProfile: config.noiseProfile ?? NoiseEngine.STANDARD,
+            loop: config.loop ?? false,
+            startIndex: config.startIndex ?? 0,
+            onPositionUpdate: (pos) => setPosition(pos),
+            onRouteComplete: () => {
+                if (options.onRouteComplete) {
+                    options.onRouteComplete();
+                }
+            },
+            onScenarioStart: (s) => {
+                try {
+                    onScenarioFiredRef.current?.(s);
+                }
+                catch (_) { /* noop */ }
+            },
+        });
+        // Register any pre-declared scenarios
+        scenarios.forEach((s) => engine.addScenario(s));
+        engineRef.current = engine;
+        return () => {
+            engine.destroy();
+            engineRef.current = null;
+            setPosition(null);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [routeGeometry]); // intentionally only re-runs when route changes
+    // Start/stop based on `active` prop
+    useEffect(() => {
+        const engine = engineRef.current;
+        if (!engine)
+            return;
+        if (active) {
+            engine.start();
+        }
+        else {
+            engine.stop();
+            setPosition(null);
+        }
+    }, [active]);
+    // ── Controls ────────────────────────────────────────────────────────────────
+    const pause = useCallback(() => engineRef.current?.pause(), []);
+    const resume = useCallback(() => engineRef.current?.resume(), []);
+    const seek = useCallback((index) => engineRef.current?.seek(index), []);
+    const setSpeed = useCallback((m) => engineRef.current?.setSpeed(m), []);
+    const startSession = useCallback((sessionId) => {
+        engineRef.current?.startRecording(sessionId);
+        setIsRecording(true);
+    }, []);
+    const stopSession = useCallback(() => {
+        setIsRecording(false);
+        return engineRef.current?.stopRecording() ?? null;
+    }, []);
+    const location = position?.location ?? (position ? { coords: position.coords, timestamp: position.timestamp } : null);
+    return {
+        position,
+        location,
+        rawLocation: location,
+        controls: { pause, resume, seek, setSpeed },
+        session: { start: startSession, stop: stopSession },
+        isRecording,
+    };
+}

package/dist/simulator/src/replay/GpxParser.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GpxParser — Parse GPX 1.1 files into NavCore coordinate arrays.
+ *
+ * ZERO dependencies. Pure string/regex parsing.
+ * No DOMParser, no xml2js, no cheerio.
+ *
+ * Supports:
+ *   <trkpt> (track points — most common)
+ *   <wpt>   (waypoints)
+ */
+import type { Coordinate } from '@ingissa/navcore-core';
+export interface GpxParseResult {
+    coordinates: Coordinate[];
+    /** Milliseconds since epoch for each coordinate (0 if no time element) */
+    timestamps: number[];
+    metadata: {
+        name?: string;
+        /** Total number of coordinate points */
+        totalPoints: number;
+        /** Duration in ms (first to last timestamp, 0 if no timestamps) */
+        durationMs: number;
+        /** Total route distance in metres */
+        distanceM: number;
+        /** Average speed in km/h (0 if no timestamps) */
+        avgSpeedKmh: number;
+    };
+}
+export declare class GpxParser {
+    /**
+     * Parse a GPX XML string into coordinates and metadata.
+     * Supports both <trkpt> and <wpt> elements.
+     */
+    static parse(gpxString: string): GpxParseResult;
+    /**
+     * Parse a base64-encoded GPX string.
+     * Works in React Native (uses atob) and Node.js (uses Buffer.from).
+     */
+    static fromBase64(base64: string): GpxParseResult;
+}
+//# sourceMappingURL=GpxParser.d.ts.map

package/dist/simulator/src/replay/GpxParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GpxParser.d.ts","sourceRoot":"","sources":["../../../../src/replay/GpxParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,wCAAwC;QACxC,WAAW,EAAE,MAAM,CAAC;QACpB,mEAAmE;QACnE,UAAU,EAAE,MAAM,CAAC;QACnB,qCAAqC;QACrC,SAAS,EAAE,MAAM,CAAC;QAClB,iDAAiD;QACjD,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,qBAAa,SAAS;IACpB;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;IAuE/C;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;CAUlD"}

package/dist/simulator/src/replay/GpxParser.js

@@ -0,0 +1,95 @@
+/**
+ * GpxParser — Parse GPX 1.1 files into NavCore coordinate arrays.
+ *
+ * ZERO dependencies. Pure string/regex parsing.
+ * No DOMParser, no xml2js, no cheerio.
+ *
+ * Supports:
+ *   <trkpt> (track points — most common)
+ *   <wpt>   (waypoints)
+ */
+import { haversineDistance } from '@ingissa/navcore-core';
+export class GpxParser {
+    /**
+     * Parse a GPX XML string into coordinates and metadata.
+     * Supports both <trkpt> and <wpt> elements.
+     */
+    static parse(gpxString) {
+        const coordinates = [];
+        const timestamps = [];
+        // Match both <trkpt> and <wpt> tags
+        const pointRegex = /<(?:trkpt|wpt)\s+([^>]+)>([\s\S]*?)<\/(?:trkpt|wpt)>/g;
+        const latLonRegex = /lat="([^"]+)"/;
+        const lonRegex = /lon="([^"]+)"/;
+        const timeRegex = /<time>([^<]+)<\/time>/;
+        let match;
+        while ((match = pointRegex.exec(gpxString)) !== null) {
+            const attrs = match[1] ?? '';
+            const body = match[2] ?? '';
+            const latMatch = latLonRegex.exec(attrs);
+            const lonMatch = lonRegex.exec(attrs);
+            if (!latMatch || !lonMatch)
+                continue;
+            const lat = parseFloat(latMatch[1] ?? '0');
+            const lon = parseFloat(lonMatch[1] ?? '0');
+            if (isNaN(lat) || isNaN(lon))
+                continue;
+            coordinates.push([lon, lat]);
+            const timeMatch = timeRegex.exec(body);
+            if (timeMatch) {
+                const ms = Date.parse(timeMatch[1] ?? '');
+                timestamps.push(isNaN(ms) ? 0 : ms);
+            }
+            else {
+                timestamps.push(0);
+            }
+        }
+        // Extract track/route name
+        const nameMatch = /<name>([^<]+)<\/name>/.exec(gpxString);
+        const name = nameMatch ? nameMatch[1]?.trim() : undefined;
+        // Compute distance
+        let distanceM = 0;
+        for (let i = 1; i < coordinates.length; i++) {
+            const a = coordinates[i - 1];
+            const b = coordinates[i];
+            distanceM += haversineDistance(a[1], a[0], b[1], b[0]);
+        }
+        // Duration and speed from timestamps
+        const validTs = timestamps.filter((t) => t > 0);
+        let durationMs = 0;
+        let avgSpeedKmh = 0;
+        if (validTs.length >= 2) {
+            durationMs = (validTs[validTs.length - 1] ?? 0) - (validTs[0] ?? 0);
+            if (durationMs > 0) {
+                const speedMs = distanceM / (durationMs / 1000);
+                avgSpeedKmh = speedMs * 3.6;
+            }
+        }
+        return {
+            coordinates,
+            timestamps,
+            metadata: {
+                name,
+                totalPoints: coordinates.length,
+                durationMs,
+                distanceM,
+                avgSpeedKmh,
+            },
+        };
+    }
+    /**
+     * Parse a base64-encoded GPX string.
+     * Works in React Native (uses atob) and Node.js (uses Buffer.from).
+     */
+    static fromBase64(base64) {
+        let decoded;
+        if (typeof atob !== 'undefined') {
+            decoded = atob(base64);
+        }
+        else {
+            // Node.js
+            decoded = Buffer.from(base64, 'base64').toString('utf-8');
+        }
+        return GpxParser.parse(decoded);
+    }
+}

package/dist/simulator/src/replay/SessionRecorder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SessionRecorder — Record and export simulation sessions.
+ *
+ * Supports JSON, GPX 1.1, and CSV export formats.
+ *
+ * The GPX export is the critical format: a session recorded in the simulator
+ * can be exported as GPX, then replayed via GpxParser on a future run.
+ * This creates a full regression test loop:
+ *   real GPS trace → gpx → GpxParser → SimulatorEngine → CI test
+ */
+import type { SimSession } from '../core/types';
+export type ExportFormat = 'json' | 'gpx' | 'csv';
+export declare class SessionRecorder {
+    private _sessionId;
+    private _startedAt;
+    private _session;
+    /**
+     * Start a new recording.
+     * If the engine already has a session via startRecording(), you can pass
+     * the existing sessionId to keep IDs consistent.
+     */
+    start(sessionId?: string): void;
+    /**
+     * Stop recording and return the captured session.
+     * If called with an existing SimSession (from SimulatorEngine.stopRecording()),
+     * it stores that session for subsequent export() calls.
+     */
+    stop(existing?: SimSession): SimSession;
+    /**
+     * Export the most recent session in the specified format.
+     * Must call stop() first.
+     */
+    export(format: ExportFormat): string;
+    private static _toGpx;
+    private static _toCsv;
+}
+//# sourceMappingURL=SessionRecorder.d.ts.map

package/dist/simulator/src/replay/SessionRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/replay/SessionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,eAAe,CAAC;AAW7D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAA2B;IAE3C;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAM/B;;;;OAIG;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU;IA0BvC;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAkBpC,OAAO,CAAC,MAAM,CAAC,MAAM;IAqCrB,OAAO,CAAC,MAAM,CAAC,MAAM;CAOtB"}

package/dist/simulator/src/replay/SessionRecorder.js

@@ -0,0 +1,120 @@
+/**
+ * SessionRecorder — Record and export simulation sessions.
+ *
+ * Supports JSON, GPX 1.1, and CSV export formats.
+ *
+ * The GPX export is the critical format: a session recorded in the simulator
+ * can be exported as GPX, then replayed via GpxParser on a future run.
+ * This creates a full regression test loop:
+ *   real GPS trace → gpx → GpxParser → SimulatorEngine → CI test
+ */
+/** Generate a UUID v4 without external dependencies */
+function uuidV4() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+export class SessionRecorder {
+    constructor() {
+        this._sessionId = null;
+        this._startedAt = null;
+        this._session = null;
+    }
+    /**
+     * Start a new recording.
+     * If the engine already has a session via startRecording(), you can pass
+     * the existing sessionId to keep IDs consistent.
+     */
+    start(sessionId) {
+        this._sessionId = sessionId ?? uuidV4();
+        this._startedAt = Date.now();
+        this._session = null;
+    }
+    /**
+     * Stop recording and return the captured session.
+     * If called with an existing SimSession (from SimulatorEngine.stopRecording()),
+     * it stores that session for subsequent export() calls.
+     */
+    stop(existing) {
+        if (existing) {
+            this._session = existing;
+            return existing;
+        }
+        // Minimal empty session if stop() is called without an engine session
+        const session = {
+            id: this._sessionId ?? uuidV4(),
+            startedAt: new Date(this._startedAt ?? Date.now()).toISOString(),
+            endedAt: new Date().toISOString(),
+            route: [],
+            positions: [],
+            scenarios: [],
+            stats: {
+                durationMs: Date.now() - (this._startedAt ?? Date.now()),
+                distanceTravelledM: 0,
+                avgSpeedKmh: 0,
+                noiseSamplesAdded: 0,
+                scenariosFired: 0,
+            },
+        };
+        this._session = session;
+        return session;
+    }
+    /**
+     * Export the most recent session in the specified format.
+     * Must call stop() first.
+     */
+    export(format) {
+        const session = this._session;
+        if (!session)
+            throw new Error('SessionRecorder: call stop() before export()');
+        switch (format) {
+            case 'json':
+                return JSON.stringify(session, null, 2);
+            case 'gpx':
+                return SessionRecorder._toGpx(session);
+            case 'csv':
+                return SessionRecorder._toCsv(session);
+            default:
+                throw new Error(`SessionRecorder: unknown format "${format}"`);
+        }
+    }
+    // ── Static export helpers ───────────────────────────────────────────────────
+    static _toGpx(session) {
+        const trkpts = session.positions
+            .map((p) => {
+            const time = new Date(p.timestamp).toISOString();
+            return (`    <trkpt lat="${p.coord[1]}" lon="${p.coord[0]}">\n` +
+                `      <time>${time}</time>\n` +
+                `      <extensions>\n` +
+                `        <speed>${p.speed.toFixed(4)}</speed>\n` +
+                `        <bearing>${p.bearing.toFixed(4)}</bearing>\n` +
+                `        <accuracy>${p.accuracy.toFixed(2)}</accuracy>\n` +
+                `      </extensions>\n` +
+                `    </trkpt>`);
+        })
+            .join('\n');
+        return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
+            `<gpx version="1.1" creator="@ingissa/navcore-simulator"\n` +
+            `     xmlns="http://www.topografix.com/GPX/1/1"\n` +
+            `     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\n` +
+            `     xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">\n` +
+            `  <metadata>\n` +
+            `    <name>${session.id}</name>\n` +
+            `    <time>${session.startedAt}</time>\n` +
+            `  </metadata>\n` +
+            `  <trk>\n` +
+            `    <name>${session.id}</name>\n` +
+            `    <trkseg>\n` +
+            trkpts + '\n' +
+            `    </trkseg>\n` +
+            `  </trk>\n` +
+            `</gpx>`);
+    }
+    static _toCsv(session) {
+        const header = 'timestamp,lng,lat,bearing,speed,accuracy';
+        const rows = session.positions.map((p) => `${p.timestamp},${p.coord[0]},${p.coord[1]},${p.bearing.toFixed(4)},${p.speed.toFixed(4)},${p.accuracy.toFixed(2)}`);
+        return [header, ...rows].join('\n');
+    }
+}

package/dist/simulator/src/scenarios/ScenarioInjector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ScenarioInjector — Registers and fires Scenario objects at geometry indices.
+ *
+ * Called internally by SimulatorEngine on each tick.
+ * Also provides static factory methods for the built-in scenario types.
+ */
+import type { Scenario } from '../core/types';
+export type ScenarioFireCallback = (scenario: Scenario) => void;
+export type ScenarioEndCallback = (scenario: Scenario) => void;
+export declare class ScenarioInjector {
+    /** Map from triggerIndex → Scenario */
+    private readonly scenarios;
+    /** Tracks which scenarios have already fired (by name) to avoid double-fire */
+    private readonly fired;
+    /** Currently active scenario, if any */
+    private _activeScenario;
+    private _activeEndTimer;
+    private onStart;
+    private onEnd;
+    constructor(onStart?: ScenarioFireCallback, onEnd?: ScenarioEndCallback);
+    register(scenario: Scenario): void;
+    remove(name: string): void;
+    clear(): void;
+    /**
+     * Check and fire any scenario whose triggerIndex matches (or was passed) by
+     * currentIndex. Called by SimulatorEngine on every tick.
+     *
+     * Returns the name of the active scenario (if any), for metadata injection.
+     */
+    tick(currentIndex: number): string | undefined;
+    get activeScenario(): Scenario | null;
+    /** Clean up any pending timers */
+    destroy(): void;
+    /**
+     * GPS blackout: no position updates for `durationMs`.
+     * Engine handles signal loss; this scenario signals the blackout period.
+     */
+    static gpsBlackout(atIndex: number, durationMs: number): Scenario;
+    /**
+     * Wrong-side road: offset the simulated position by `offsetM` metres
+     * perpendicular to the route to stress-test the parallel road resolver.
+     */
+    static wrongSideRoad(atIndex: number, offsetM: number): Scenario;
+    /** U-turn at the given index — stress-tests U-turn protection. */
+    static uTurn(atIndex: number): Scenario;
+    /** Speed spike: briefly report spikeKmh instead of the configured speed. */
+    static speedSpike(atIndex: number, spikeKmh: number, durationMs?: number): Scenario;
+    /**
+     * Accuracy drop: GPS accuracy degrades to newAccuracyM for durationMs.
+     */
+    static accuracyDrop(atIndex: number, newAccuracyM: number, durationMs: number): Scenario;
+    private _fire;
+    private _clearActiveTimer;
+}
+//# sourceMappingURL=ScenarioInjector.d.ts.map

package/dist/simulator/src/scenarios/ScenarioInjector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScenarioInjector.d.ts","sourceRoot":"","sources":["../../../../src/scenarios/ScenarioInjector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;AAE/D,qBAAa,gBAAgB;IAC3B,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,wCAAwC;IACxC,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,eAAe,CAA8C;IAErE,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,KAAK,CAAsB;gBAEvB,OAAO,CAAC,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,mBAAmB;IAOvE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAIlC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAS1B,KAAK,IAAI,IAAI;IASb;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAa9C,IAAI,cAAc,IAAI,QAAQ,GAAG,IAAI,CAEpC;IAED,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAMf;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ;IAUjE;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;IAShE,kEAAkE;IAClE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IASvC,4EAA4E;IAC5E,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,SAAO,GAAG,QAAQ;IAUjF;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ;IAYxF,OAAO,CAAC,KAAK;IAiBb,OAAO,CAAC,iBAAiB;CAM1B"}

package/dist/simulator/src/scenarios/ScenarioInjector.js

@@ -0,0 +1,150 @@
+/**
+ * ScenarioInjector — Registers and fires Scenario objects at geometry indices.
+ *
+ * Called internally by SimulatorEngine on each tick.
+ * Also provides static factory methods for the built-in scenario types.
+ */
+export class ScenarioInjector {
+    constructor(onStart, onEnd) {
+        /** Map from triggerIndex → Scenario */
+        this.scenarios = new Map();
+        /** Tracks which scenarios have already fired (by name) to avoid double-fire */
+        this.fired = new Set();
+        /** Currently active scenario, if any */
+        this._activeScenario = null;
+        this._activeEndTimer = null;
+        this.onStart = onStart ?? (() => undefined);
+        this.onEnd = onEnd ?? (() => undefined);
+    }
+    // ── Registration ────────────────────────────────────────────────────────────
+    register(scenario) {
+        this.scenarios.set(scenario.triggerIndex, scenario);
+    }
+    remove(name) {
+        for (const [idx, s] of this.scenarios) {
+            if (s.name === name) {
+                this.scenarios.delete(idx);
+                break;
+            }
+        }
+    }
+    clear() {
+        this.scenarios.clear();
+        this.fired.clear();
+        this._clearActiveTimer();
+        this._activeScenario = null;
+    }
+    // ── Tick ────────────────────────────────────────────────────────────────────
+    /**
+     * Check and fire any scenario whose triggerIndex matches (or was passed) by
+     * currentIndex. Called by SimulatorEngine on every tick.
+     *
+     * Returns the name of the active scenario (if any), for metadata injection.
+     */
+    tick(currentIndex) {
+        const floorIdx = Math.floor(currentIndex);
+        for (const [triggerIdx, scenario] of this.scenarios) {
+            if (floorIdx >= triggerIdx && !this.fired.has(scenario.name)) {
+                this.fired.add(scenario.name);
+                this._fire(scenario);
+            }
+        }
+        return this._activeScenario?.name;
+    }
+    get activeScenario() {
+        return this._activeScenario;
+    }
+    /** Clean up any pending timers */
+    destroy() {
+        this._clearActiveTimer();
+    }
+    // ── Static factories ────────────────────────────────────────────────────────
+    /**
+     * GPS blackout: no position updates for `durationMs`.
+     * Engine handles signal loss; this scenario signals the blackout period.
+     */
+    static gpsBlackout(atIndex, durationMs) {
+        return {
+            name: `gps-blackout-@${atIndex}`,
+            triggerIndex: atIndex,
+            type: 'GPS_BLACKOUT',
+            durationMs,
+            params: { durationMs },
+        };
+    }
+    /**
+     * Wrong-side road: offset the simulated position by `offsetM` metres
+     * perpendicular to the route to stress-test the parallel road resolver.
+     */
+    static wrongSideRoad(atIndex, offsetM) {
+        return {
+            name: `wrong-side-@${atIndex}`,
+            triggerIndex: atIndex,
+            type: 'WRONG_SIDE_ROAD',
+            params: { offsetM },
+        };
+    }
+    /** U-turn at the given index — stress-tests U-turn protection. */
+    static uTurn(atIndex) {
+        return {
+            name: `uturn-@${atIndex}`,
+            triggerIndex: atIndex,
+            type: 'UTURN',
+            params: {},
+        };
+    }
+    /** Speed spike: briefly report spikeKmh instead of the configured speed. */
+    static speedSpike(atIndex, spikeKmh, durationMs = 2000) {
+        return {
+            name: `speed-spike-@${atIndex}`,
+            triggerIndex: atIndex,
+            type: 'SPEED_SPIKE',
+            durationMs,
+            params: { spikeKmh },
+        };
+    }
+    /**
+     * Accuracy drop: GPS accuracy degrades to newAccuracyM for durationMs.
+     */
+    static accuracyDrop(atIndex, newAccuracyM, durationMs) {
+        return {
+            name: `accuracy-drop-@${atIndex}`,
+            triggerIndex: atIndex,
+            type: 'ACCURACY_DROP',
+            durationMs,
+            params: { newAccuracyM },
+        };
+    }
+    // ── Private ─────────────────────────────────────────────────────────────────
+    _fire(scenario) {
+        this._activeScenario = scenario;
+        try {
+            this.onStart(scenario);
+        }
+        catch (_) { /* never throw from callback */ }
+        if (scenario.durationMs != null && scenario.durationMs > 0) {
+            this._clearActiveTimer();
+            this._activeEndTimer = setTimeout(() => {
+                this._activeScenario = null;
+                try {
+                    this.onEnd(scenario);
+                }
+                catch (_) { /* never throw */ }
+            }, scenario.durationMs);
+        }
+        else {
+            // Instantaneous scenario — end immediately
+            this._activeScenario = null;
+            try {
+                this.onEnd(scenario);
+            }
+            catch (_) { /* never throw */ }
+        }
+    }
+    _clearActiveTimer() {
+        if (this._activeEndTimer !== null) {
+            clearTimeout(this._activeEndTimer);
+            this._activeEndTimer = null;
+        }
+    }
+}