@ingissa/navcore-core 1.0.3 → 1.0.5

package/dist/pro.d.mts

@@ -1,488 +1,2 @@
-import { C as Coordinate, i as NavInstruction, g as NavCoreState } from './NavCore.d-BuXR5DO7.mjs';
-
-/**
- * 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);
- * ```
- */
-
-interface SnapCandidate {
-    /** Route segment index */
-    segmentIndex: number;
-    /** Projected point on segment */
-    projectedCoord: Coordinate;
-    /** Raw distance to route in metres */
-    distanceMetres: number;
-    /** Start of segment */
-    segA: Coordinate;
-    /** End of segment */
-    segB: Coordinate;
-}
-interface ResolvedCandidate extends SnapCandidate {
-    /** Final score (lower is better) */
-    score: number;
-    /** Bearing delta that triggered U-turn protection (null if not triggered) */
-    bearingDeltaDeg: number | null;
-    /** Whether inertia penalty was applied */
-    inertiaPenaltyApplied: boolean;
-}
-interface ParallelRoadResolverOptions {
-    /**
-     * Penalty added to score when vehicle bearing mismatches segment bearing
-     * beyond `bearingMismatchThresholdDeg`. Default: 80m equivalent.
-     */
-    bearingPenalty?: number;
-    /**
-     * Bearing mismatch threshold in degrees that activates the penalty.
-     * Default: 60°. Higher = more tolerant of U-turns.
-     */
-    bearingMismatchThresholdDeg?: number;
-    /**
-     * Penalty added when the candidate segment is far from the previously
-     * snapped segment, preventing oscillation. Default: 40m equivalent.
-     */
-    inertiaPenalty?: number;
-    /**
-     * Minimum segment jump (in index units) to trigger inertia penalty.
-     * Default: 3.
-     */
-    inertiaSegmentDist?: number;
-}
-declare class ParallelRoadResolver {
-    private readonly options;
-    constructor(options?: ParallelRoadResolverOptions);
-    private warned;
-    /**
-     * 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: SnapCandidate[], vehicleBearing?: number | null, prevSegmentIdx?: number | null): ResolvedCandidate[];
-    /**
-     * Resolve and return only the best candidate.
-     */
-    resolveBest(candidates: SnapCandidate[], vehicleBearing?: number | null, prevSegmentIdx?: number | null): ResolvedCandidate | null;
-    private score;
-    /**
-     * 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: number, segA: Coordinate, segB: Coordinate): boolean;
-}
-
-/**
- * Module 3: DeadReckoning
- * Predicts vehicle position during GPS outages or stale fixes.
- */
-
-interface DRAnchor {
-    coord: Coordinate;
-    idx: number;
-    ts: number;
-}
-interface DRPrediction {
-    predictedCoord: Coordinate;
-    isActive: boolean;
-    ageMs: number;
-}
-/**
- * Given a snapped anchor on the route, extrapolate forward using speed and bearing.
- * Note: This function is a pure utility; license enforcement is in DeadReckoningEngine.predict().
- */
-declare function computeDeadReckoningOnRoute(anchor: DRAnchor | null, speed: number, bearing: number, now: number, maxAgeMs?: number): DRPrediction;
-/**
- * Stateful dead reckoning engine.
- *
- * FEATURE: DEAD_RECKONING (Pro license required)
- * predict() is a no-op and returns isActive=false when no valid Pro license is present.
- */
-declare class DeadReckoningEngine {
-    private anchor;
-    private readonly maxAgeMs;
-    private warned;
-    constructor(maxAgeMs?: number);
-    /** Set the anchor point (called when GPS is available and snapping succeeds) */
-    setAnchor(coord: Coordinate, idx: number, timestamp: number): void;
-    /**
-     * Predict position given current speed and bearing.
-     * Requires a valid Pro license — returns isActive=false without one.
-     */
-    predict(speed: number, bearing: number, now: number): DRPrediction;
-    /** Clear the anchor (GPS restored) */
-    clearAnchor(): void;
-    getAnchor(): DRAnchor | null;
-}
-
-/**
- * Module 4b: DeviationDetector
- * Compound deviation detection using distance, bearing, and movement signals.
- *
- * FEATURE: COMPOUND_DEVIATION (Pro license required)
- * evaluate() returns a neutral "no-deviation" signal without a valid Pro license.
- */
-
-interface DeviationSignals {
-    /** Distance from GPS to nearest route segment (metres) */
-    distanceToRoute: number;
-    /** Whether the distance exceeds the dynamic corridor */
-    outsideCorridor: boolean;
-    /** Whether the vehicle bearing diverges from the route bearing */
-    bearingMismatch: boolean;
-    /** Whether the vehicle is moving away from the next segment */
-    movingAway: boolean;
-    /** Compound confirmed: outsideCorridor AND (bearingMismatch OR movingAway) */
-    confirmed: boolean;
-}
-interface ClosestSegment {
-    segmentIndex: number;
-    distance: number;
-    projection: Coordinate;
-}
-declare class DeviationDetector {
-    private warned;
-    /**
-     * Evaluate deviation signals for the current GPS position.
-     * Requires a valid Pro license — returns a neutral signal without one.
-     */
-    evaluate(gps: Coordinate, gpsBearing: number | null, speedMps: number, closest: ClosestSegment, route: Coordinate[], corridor: number, prevDistToNextSegment: number | null): DeviationSignals;
-}
-
-/**
- * Module 4a: DynamicCorridor
- * Speed-adaptive corridor width calculation.
- */
-/**
- * Compute speed-adaptive corridor width in metres.
- *
- * Corridor widens with speed: BASE + speed * FACTOR, capped at MAX.
- * GPS accuracy optionally widens the corridor further.
- */
-declare function calculateDynamicCorridor(speedMps: number, gpsAccuracy?: number | null, baseMeters?: number, maxMeters?: number, speedFactor?: number, accuracyFactor?: number): number;
-
-/**
- * InstructionEditor — Fluent builder for NavInstruction arrays.
- *
- * Create, edit, and annotate navigation instructions for custom routes.
- * Supports standard turn instructions and exam-specific annotations.
- *
- * @example
- * ```typescript
- * const editor = new InstructionEditor();
- * editor
- *   .addTurn([2.347, 48.859], 'Turn left onto Rue de Rivoli', 42)
- *   .addExamPoint([2.350, 48.860], 'Check mirrors before changing lane', 50)
- *   .addCheckpoint([2.355, 48.861], 65);
- *
- * editor.attachToCumulative(routeGeometry);
- * engine.setRoute(routeGeometry, editor.toArray());
- * ```
- */
-
-type InstructionType = 'turn' | 'exam_point' | 'checkpoint' | 'depart' | 'arrive' | 'custom';
-interface RichInstruction extends NavInstruction {
-    /** Instruction category */
-    type: InstructionType;
-    /** Unique id for referencing in edit operations */
-    id: string;
-    /** Display text (same as NavInstruction.text) */
-    text: string;
-    /** Whether to suppress voice read-out */
-    silent?: boolean;
-    /** Exam-specific severity level */
-    severity?: 'info' | 'warning' | 'critical';
-    /** Custom metadata for integrators */
-    meta?: Record<string, unknown>;
-}
-declare class InstructionEditor {
-    private instructions;
-    /** Add a turn instruction at the given route geometry index */
-    addTurn(location: Coordinate, text: string, geometryIndex: number, opts?: {
-        silent?: boolean;
-        meta?: Record<string, unknown>;
-    }): this;
-    /** Add an exam-specific point (e.g. "Check mirrors", "Yield here") */
-    addExamPoint(location: Coordinate, text: string, geometryIndex: number, opts?: {
-        severity?: RichInstruction['severity'];
-        silent?: boolean;
-        meta?: Record<string, unknown>;
-    }): this;
-    /** Add a silent progress checkpoint (does not trigger voice) */
-    addCheckpoint(location: Coordinate, geometryIndex: number, meta?: Record<string, unknown>): this;
-    /** Add a departure instruction (auto-inserted at index 0) */
-    addDepart(location: Coordinate, text?: string): this;
-    /** Add an arrival instruction */
-    addArrive(location: Coordinate, text?: string): this;
-    /** Update any field of an instruction by id */
-    update(id: string, patch: Partial<Omit<RichInstruction, 'id'>>): this;
-    /** Remove an instruction by id */
-    remove(id: string): this;
-    /** Move an instruction to a new position in the list */
-    reorder(id: string, newIndex: number): this;
-    /** Sort instructions by geometryIndex ascending */
-    sort(): this;
-    /** Remove all instructions */
-    clear(): this;
-    /**
-     * Compute and attach `cumulativeOffset` and `bearingBefore`/`bearingAfter`
-     * from the route geometry. Call this after loading the route but before
-     * passing instructions to the engine.
-     */
-    attachToCumulative(route: Coordinate[]): this;
-    /** Export as plain NavInstruction[] for use with engine.setRoute() */
-    toArray(): NavInstruction[];
-    /** Export rich instructions with all metadata */
-    toRichArray(): ReadonlyArray<RichInstruction>;
-    get size(): number;
-}
-
-/**
- * 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);
- * ```
- */
-
-type VoicePriority = 'low' | 'normal' | 'high' | 'urgent';
-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;
-}
-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;
-}
-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;
-}
-
-/**
- * ETAEngine — Local ETA computation. Zero API calls.
- *
- * Computes Estimated Time of Arrival from current NavCore state using
- * a rolling speed average. No server required — entirely offline.
- *
- * FEATURE: ETA
- *
- * @example
- * ```typescript
- * const eta = new ETAEngine({ speedWindowSize: 8 });
- * engine.on('update', (state) => {
- *   const result = eta.update(state);
- *   console.log(`ETA: ${result.etaSeconds}s, ${result.distanceRemainingM.toFixed(0)}m`);
- * });
- * ```
- */
-
-interface ETAResult {
-    /** ETA in seconds from now */
-    etaSeconds: number;
-    /** ETA as absolute timestamp (Date.now() + etaSeconds * 1000) */
-    etaMs: number;
-    /** Remaining distance in metres */
-    distanceRemainingM: number;
-    /** Rolling average speed in m/s */
-    averageSpeedMs: number;
-    /** Whether the estimate is reliable (enough speed samples + non-zero speed) */
-    isReliable: boolean;
-}
-interface ETAOptions {
-    /**
-     * Number of speed samples in the rolling average window.
-     * More samples = smoother but slower to react. Default: 6.
-     */
-    speedWindowSize?: number;
-    /**
-     * Minimum speed (m/s) below which we use the last reliable speed
-     * rather than 0 (avoids Infinity ETA while stopped). Default: 0.5 m/s (~2 km/h).
-     */
-    minimumSpeedMs?: number;
-    /**
-     * Speed to assume if no reliable samples yet. Default: 8.3 m/s (30 km/h).
-     */
-    fallbackSpeedMs?: number;
-}
-declare class ETAEngine {
-    private readonly options;
-    private speedSamples;
-    private lastReliableSpeed;
-    constructor(options?: ETAOptions);
-    /**
-     * Feed a NavCore state snapshot and receive an ETA estimate.
-     * Call this on every GPS update tick.
-     */
-    update(state: NavCoreState): ETAResult;
-    /** Reset the speed window (call on new route or significant GPS gap) */
-    reset(): void;
-    private rollingAverage;
-}
-
-/**
- * GeofencingEngine
- *
- * Circular and polygon geofences — zero server dependency.
- * Uses haversine distance for circles and ray-casting for polygons.
- *
- * FEATURE: GEOFENCING
- *
- * @example
- * ```typescript
- * const geo = new GeofencingEngine({ dwellThresholdMs: 5000 });
- * geo.addCircle('school-zone', 'School Zone', [2.347, 48.859], 50, { speedLimit: 30 });
- * geo.addPolygon('exam-area', 'Exam District', [[2.34, 48.85], [2.36, 48.85], [2.36, 48.87], [2.34, 48.87]]);
- *
- * engine.on('update', ({ snappedCoord }) => {
- *   const events = geo.update(snappedCoord);
- *   for (const evt of events) {
- *     // evt.name is the human-readable zone name
- *     console.log(`${evt.type}: ${evt.name} (${evt.id})`);
- *   }
- * });
- * ```
- */
-
-type GeofenceType = 'circle' | 'polygon';
-type GeofenceEventType = 'enter' | 'exit' | 'dwell';
-interface GeofenceEvent {
-    /** Geofence ID that triggered the event */
-    id: string;
-    /** Human-readable name of the geofence */
-    name: string;
-    type: GeofenceEventType;
-    /** Coordinate that triggered the event */
-    coord: Coordinate;
-    /** Milliseconds spent inside (for dwell events) */
-    dwellMs?: number;
-    /** Custom metadata passed at creation */
-    meta?: unknown;
-}
-interface ZoneDefinition {
-    id: string;
-    name: string;
-    type: 'circle' | 'polygon';
-    center?: Coordinate;
-    radiusMeters?: number;
-    coords?: Coordinate[];
-    meta?: unknown;
-}
-interface GeofencingOptions {
-    /**
-     * Milliseconds a vehicle must remain inside a geofence before a 'dwell' event fires.
-     * Default: 10000ms (10 seconds).
-     */
-    dwellThresholdMs?: number;
-    /** Initial zones to register on creation */
-    zones?: ZoneDefinition[];
-    /** Callback for all geofence events */
-    onEvent?: (event: GeofenceEvent) => void;
-}
-declare class GeofencingEngine {
-    private fences;
-    private states;
-    private readonly options;
-    constructor(options?: GeofencingOptions);
-    /** Add a circular geofence. Returns the ID. */
-    addCircle(id: string, name: string, center: Coordinate, radiusM: number, meta?: unknown): string;
-    /**
-     * Add a polygon geofence. Coords are [lng, lat] pairs.
-     * The polygon is auto-closed (first == last not required).
-     */
-    addPolygon(id: string, name: string, coords: Coordinate[], meta?: unknown): string;
-    /** Remove a geofence by ID */
-    remove(id: string): void;
-    /** Remove all geofences */
-    clear(): void;
-    /** List all registered geofence IDs */
-    listIds(): string[];
-    /**
-     * Feed the current coordinate and receive a (possibly empty) list of events.
-     * Call this on every NavCore state update.
-     */
-    update(coord: Coordinate): GeofenceEvent[];
-    /** Check if a coordinate is currently inside a named geofence */
-    isInside(id: string, coord: Coordinate): boolean;
-    private contains;
-    /**
-     * Ray-casting point-in-polygon algorithm.
-     * Works in [lng, lat] space (sufficient for small areas; use projected
-     * coords for very large polygons spanning many degrees).
-     */
-    private pointInPolygon;
-}
-
-export { DeadReckoningEngine, DeviationDetector, ETAEngine, type ETAOptions, type ETAResult, type GeofenceEvent, type GeofenceEventType, type GeofenceType, GeofencingEngine, type GeofencingOptions, InstructionEditor, type InstructionType, ParallelRoadResolver, type ParallelRoadResolverOptions, type ResolvedCandidate, type RichInstruction, type SnapCandidate, type VoiceCue, type VoicePriority, VoiceTriggerEngine, type VoiceTriggerOptions, type ZoneDefinition, calculateDynamicCorridor, computeDeadReckoningOnRoute };
+export { D as DeadReckoningEngine, a as DeviationDetector, E as ETAEngine, b as ETAOptions, c as ETAResult, G as GeofenceEvent, d as GeofenceEventType, e as GeofenceType, f as GeofencingEngine, g as GeofencingOptions, I as InstructionEditor, h as InstructionType, P as ParallelRoadResolver, i as ParallelRoadResolverOptions, R as ResolvedCandidate, j as RichInstruction, S as SnapCandidate, V as VoiceCue, k as VoicePriority, l as VoiceTriggerEngine, m as VoiceTriggerOptions, n as advancePredictor, o as applyBearingSmoothing, p as applyGpsCorrection, q as blendBearing, r as calculateDynamicCorridor, s as calculateRobustBearing, t as computeDeadReckoningOnRoute, u as getSpeedAdaptiveAlpha, v as pointAtOffset, w as validateProgressUpdate } from './index.pro-Cg6394f_.mjs';
+export { d as LifecycleContext, e as LifecycleEvent, i as NavInstruction, j as NavLifecycleState, k as NavigationFSM, O as OffRouteContext, l as OffRouteEvent, m as OffRouteFSM, n as OffRouteState, R as RejoinTarget, T as TempRoute, r as resolveNextInstruction } from './NavCore-qf5_0qsR.mjs';