@ingissa/navcore-simulator 1.0.7 → 1.0.9

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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,40 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,95 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,120 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,150 +0,0 @@
-/**
- * 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;
-        }
-    }
-}