@ingissa/navcore-react-native 1.0.3 → 1.0.7

package/dist/core/src/directions/ValhallaDirectionsProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ValhallaDirectionsProvider
+ *
+ * Self-hosted Valhalla routing engine adapter.
+ * Supports the `/route` and `/optimized_route` endpoints.
+ * Zero API key for self-hosted. Uses Mapbox-hosted Valhalla with a token.
+ *
+ * @see https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/
+ */
+import type { Coordinate } from '../geo/haversine';
+import type { DirectionsProvider, DirectionsOptions, DirectionsResult } from './DirectionsProvider';
+export type ValhallaCostingModel = 'auto' | 'bicycle' | 'pedestrian' | 'bus' | 'motor_scooter';
+export interface ValhallaConfig {
+    /** Base URL of your Valhalla server or hosted instance */
+    baseUrl: string;
+    /** Routing costing model (default: 'auto') */
+    costing?: ValhallaCostingModel;
+    /** Optional API key (required for hosted Valhalla services) */
+    apiKey?: string;
+    /** Max waypoints per chunk (default: 50) */
+    maxWaypointsPerChunk?: number;
+}
+export declare class ValhallaDirectionsProvider implements DirectionsProvider {
+    private readonly config;
+    constructor(config: ValhallaConfig);
+    getRoute(waypoints: Coordinate[], options?: DirectionsOptions): Promise<DirectionsResult>;
+    private profileToCosting;
+    private fetchRoute;
+    /** Decode Valhalla's encoded polyline6 format */
+    private decodePolyline;
+    private fetchChunked;
+}
+//# sourceMappingURL=ValhallaDirectionsProvider.d.ts.map

package/dist/core/src/directions/ValhallaDirectionsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValhallaDirectionsProvider.d.ts","sourceRoot":"","sources":["../../../../../core/src/directions/ValhallaDirectionsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEpG,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,KAAK,GAAG,eAAe,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,qBAAa,0BAA2B,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAEtC,MAAM,EAAE,cAAc;IAS5B,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAY/F,OAAO,CAAC,gBAAgB;YAQV,UAAU;IA6ExB,iDAAiD;IACjD,OAAO,CAAC,cAAc;YAmCR,YAAY;CA+B3B"}

package/dist/core/src/directions/ValhallaDirectionsProvider.js

@@ -0,0 +1,155 @@
+/**
+ * ValhallaDirectionsProvider
+ *
+ * Self-hosted Valhalla routing engine adapter.
+ * Supports the `/route` and `/optimized_route` endpoints.
+ * Zero API key for self-hosted. Uses Mapbox-hosted Valhalla with a token.
+ *
+ * @see https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/
+ */
+const DEFAULT_MAX_CHUNK = 50;
+export class ValhallaDirectionsProvider {
+    constructor(config) {
+        this.config = {
+            baseUrl: config.baseUrl.replace(/\/$/, ''),
+            costing: config.costing ?? 'auto',
+            apiKey: config.apiKey ?? '',
+            maxWaypointsPerChunk: config.maxWaypointsPerChunk ?? DEFAULT_MAX_CHUNK,
+        };
+    }
+    async getRoute(waypoints, options) {
+        if (waypoints.length < 2)
+            throw new Error('[Valhalla] At least 2 waypoints required');
+        const costing = this.profileToCosting(options?.profile);
+        if (waypoints.length <= this.config.maxWaypointsPerChunk) {
+            return this.fetchRoute(waypoints, costing, options);
+        }
+        return this.fetchChunked(waypoints, costing, options);
+    }
+    profileToCosting(profile) {
+        switch (profile) {
+            case 'cycling': return 'bicycle';
+            case 'walking': return 'pedestrian';
+            default: return this.config.costing;
+        }
+    }
+    async fetchRoute(waypoints, costing, _options) {
+        const locations = waypoints.map(w => ({ lon: w[0], lat: w[1], type: 'break' }));
+        const body = JSON.stringify({
+            locations,
+            costing,
+            directions_options: { units: 'kilometers' },
+        });
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.config.apiKey)
+            headers['api_key'] = this.config.apiKey;
+        const res = await fetch(`${this.config.baseUrl}/route`, { method: 'POST', headers, body });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`[Valhalla] HTTP ${res.status}: ${err}`);
+        }
+        const data = await res.json();
+        const totalSummary = data.trip?.summary ?? {};
+        const fullGeometry = [];
+        const legs = (data.trip?.legs ?? []).map((leg, legIdx) => {
+            const legGeometry = this.decodePolyline(leg.shape ?? '');
+            if (legIdx === 0) {
+                fullGeometry.push(...legGeometry);
+            }
+            else if (legGeometry.length > 0) {
+                // avoid duplicating the boundary coordinate between consecutive legs
+                fullGeometry.push(...legGeometry.slice(1));
+            }
+            return {
+                distance: (leg.summary?.length ?? 0) * 1000, // km → m
+                duration: leg.summary?.time ?? 0,
+                steps: (leg.maneuvers ?? []).map((m) => {
+                    const beginIdx = typeof m.begin_shape_index === 'number' ? m.begin_shape_index : 0;
+                    const endIdx = typeof m.end_shape_index === 'number' ? m.end_shape_index : beginIdx;
+                    const stepGeometry = legGeometry.slice(beginIdx, endIdx + 1);
+                    const location = legGeometry[beginIdx] ?? waypoints[0];
+                    return {
+                        distance: (m.length ?? 0) * 1000,
+                        duration: m.time ?? 0,
+                        geometry: stepGeometry,
+                        maneuver: {
+                            type: m.type?.toString() ?? 'unknown',
+                            modifier: undefined,
+                            location,
+                            bearingBefore: m.begin_heading ?? 0,
+                            bearingAfter: m.end_heading ?? 0,
+                            instruction: m.instruction,
+                        },
+                        name: m.street_names?.[0],
+                    };
+                }),
+            };
+        });
+        const geometry = fullGeometry.length > 0
+            ? fullGeometry
+            : this.decodePolyline(data.trip?.legs?.[0]?.shape ?? '');
+        return {
+            geometry,
+            distance: (totalSummary.length ?? 0) * 1000,
+            duration: totalSummary.time ?? 0,
+            legs,
+            raw: data,
+        };
+    }
+    /** Decode Valhalla's encoded polyline6 format */
+    decodePolyline(encoded, precision = 6) {
+        const factor = Math.pow(10, precision);
+        const coords = [];
+        let index = 0;
+        let lat = 0;
+        let lng = 0;
+        while (index < encoded.length) {
+            let shift = 0;
+            let result = 0;
+            let byte;
+            do {
+                byte = encoded.charCodeAt(index++) - 63;
+                result |= (byte & 0x1f) << shift;
+                shift += 5;
+            } while (byte >= 0x20);
+            const dLat = (result & 1) !== 0 ? ~(result >> 1) : result >> 1;
+            lat += dLat;
+            shift = 0;
+            result = 0;
+            do {
+                byte = encoded.charCodeAt(index++) - 63;
+                result |= (byte & 0x1f) << shift;
+                shift += 5;
+            } while (byte >= 0x20);
+            const dLng = (result & 1) !== 0 ? ~(result >> 1) : result >> 1;
+            lng += dLng;
+            coords.push([lng / factor, lat / factor]);
+        }
+        return coords;
+    }
+    async fetchChunked(waypoints, costing, options) {
+        const size = this.config.maxWaypointsPerChunk;
+        const chunks = [];
+        for (let i = 0; i < waypoints.length; i += size - 1) {
+            const chunk = waypoints.slice(i, i + size);
+            if (chunk.length < 2)
+                break;
+            chunks.push(chunk);
+            if (i + size >= waypoints.length)
+                break;
+        }
+        const results = await Promise.all(chunks.map(c => this.fetchRoute(c, costing, options)));
+        const geometry = [];
+        let distance = 0;
+        let duration = 0;
+        const legs = [];
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            geometry.push(...(i === 0 ? r.geometry : r.geometry.slice(1)));
+            distance += r.distance;
+            duration += r.duration;
+            legs.push(...r.legs);
+        }
+        return { geometry, distance, duration, legs, raw: results.map(r => r.raw) };
+    }
+}

package/dist/core/src/eta/ETAEngine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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`);
+ * });
+ * ```
+ */
+import type { NavCoreState } from '../NavCore';
+export 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;
+}
+export 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;
+}
+export 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;
+}
+//# sourceMappingURL=ETAEngine.d.ts.map

package/dist/core/src/eta/ETAEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ETAEngine.d.ts","sourceRoot":"","sources":["../../../../../core/src/eta/ETAEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAQD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,CAAC,EAAE,UAAU;IAKhC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS;IAsCtC,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,cAAc;CAKvB"}

package/dist/core/src/eta/ETAEngine.js

@@ -0,0 +1,74 @@
+/**
+ * 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`);
+ * });
+ * ```
+ */
+const DEFAULTS = {
+    speedWindowSize: 6,
+    minimumSpeedMs: 0.5,
+    fallbackSpeedMs: 8.33, // ~30 km/h
+};
+export class ETAEngine {
+    constructor(options) {
+        this.speedSamples = [];
+        this.options = { ...DEFAULTS, ...options };
+        this.lastReliableSpeed = this.options.fallbackSpeedMs;
+    }
+    /**
+     * Feed a NavCore state snapshot and receive an ETA estimate.
+     * Call this on every GPS update tick.
+     */
+    update(state) {
+        const distanceRemainingM = state.distanceToDestination ?? 0;
+        // Update rolling speed window
+        const speed = state.currentSpeed ?? 0;
+        this.speedSamples.push(speed);
+        if (this.speedSamples.length > this.options.speedWindowSize) {
+            this.speedSamples.shift();
+        }
+        const avgSpeed = this.rollingAverage();
+        // Track last reliable speed (above minimum threshold)
+        if (avgSpeed >= this.options.minimumSpeedMs) {
+            this.lastReliableSpeed = avgSpeed;
+        }
+        const effectiveSpeed = avgSpeed >= this.options.minimumSpeedMs
+            ? avgSpeed
+            : this.lastReliableSpeed;
+        const isReliable = this.speedSamples.length >= Math.ceil(this.options.speedWindowSize / 2)
+            && effectiveSpeed > 0
+            && distanceRemainingM > 0;
+        const etaSeconds = effectiveSpeed > 0
+            ? distanceRemainingM / effectiveSpeed
+            : 0;
+        return {
+            etaSeconds: Math.round(etaSeconds),
+            etaMs: Date.now() + etaSeconds * 1000,
+            distanceRemainingM,
+            averageSpeedMs: avgSpeed,
+            isReliable,
+        };
+    }
+    /** Reset the speed window (call on new route or significant GPS gap) */
+    reset() {
+        this.speedSamples = [];
+        this.lastReliableSpeed = this.options.fallbackSpeedMs;
+    }
+    rollingAverage() {
+        if (this.speedSamples.length === 0)
+            return 0;
+        const sum = this.speedSamples.reduce((a, b) => a + b, 0);
+        return sum / this.speedSamples.length;
+    }
+}

package/dist/core/src/features.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Feature flag constants for SDK consumers.
+ *
+ * CORE features: available to all users (MIT license).
+ * PRO  features: require a valid commercial license key.
+ */
+export declare const FEATURES: {
+    /**
+     * Basic Kalman filter GPS smoothing.
+     * Reduces GPS jitter for stable route snapping.
+     */
+    readonly GPS_SMOOTHING: "gps_smoothing";
+    /**
+     * Basic route snapping (nearest-point projection).
+     * Snaps GPS position to the closest route segment.
+     */
+    readonly BASIC_SNAPPING: "basic_snapping";
+    /**
+     * Advanced route snapping with bearing penalty + inertia.
+     * Prevents incorrect snaps on parallel roads and U-turns.
+     */
+    readonly ADVANCED_SNAPPING: "advanced_snapping";
+    /**
+     * Dead reckoning: continues navigation during GPS signal loss.
+     * Predicts position based on last known speed and bearing.
+     */
+    readonly DEAD_RECKONING: "dead_reckoning";
+    /**
+     * Smooth route offset predictor for jitter-free map rendering.
+     * Advances render position at frame rate between GPS fixes.
+     */
+    readonly ROUTE_OFFSET: "route_offset";
+    /**
+     * Progress anti-regression: prevents route index from jumping backward.
+     * Essential for circuit routes and motorway slip roads.
+     */
+    readonly PROGRESS_TRACKING: "progress_tracking";
+    /**
+     * Advanced bearing engine with look-ahead and speed-adaptive alpha.
+     * Produces stable heading for smooth map camera rotation.
+     */
+    readonly ADVANCED_BEARING: "advanced_bearing";
+    /**
+     * Compound deviation detection: combines distance, bearing, and speed signals.
+     * Eliminates false off-route triggers in tunnels and urban canyons.
+     */
+    readonly COMPOUND_DEVIATION: "compound_deviation";
+    /**
+     * Parallel road disambiguation + U-turn snap protection.
+     * Prevents snapping to the wrong carriageway when bearing mismatches route direction.
+     */
+    readonly PARALLEL_ROAD_RESOLUTION: "parallel_road_resolution";
+    /**
+     * U-turn protection: bearing penalty applied when vehicle heading opposes
+     * route segment direction by more than the configured threshold (default 60°).
+     */
+    readonly U_TURN_PROTECTION: "u_turn_protection";
+    /**
+     * Timed voice instruction cues with deduplication and priority levels.
+     */
+    readonly VOICE_TRIGGERS: "voice_triggers";
+    /**
+     * Local ETA computation using rolling speed average — zero API calls.
+     */
+    readonly ETA: "eta";
+    /**
+     * Circular and polygon geofencing with enter/exit/dwell events.
+     */
+    readonly GEOFENCING: "geofencing";
+    /**
+     * AI-powered navigation stability: oscillation suppression + turn anticipation.
+     */
+    readonly NAV_AI: "nav_ai";
+};
+export type FeatureKey = typeof FEATURES[keyof typeof FEATURES];
+//# sourceMappingURL=features.d.ts.map

package/dist/core/src/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../../../core/src/features.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,QAAQ;IAGnB;;;OAGG;;IAGH;;;OAGG;;IAKH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEK,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,QAAQ,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC"}

package/dist/core/src/features.js

@@ -0,0 +1,76 @@
+/**
+ * Feature flag constants for SDK consumers.
+ *
+ * CORE features: available to all users (MIT license).
+ * PRO  features: require a valid commercial license key.
+ */
+export const FEATURES = {
+    // ── CORE — available without a license key ──────────────────────────────────
+    /**
+     * Basic Kalman filter GPS smoothing.
+     * Reduces GPS jitter for stable route snapping.
+     */
+    GPS_SMOOTHING: 'gps_smoothing',
+    /**
+     * Basic route snapping (nearest-point projection).
+     * Snaps GPS position to the closest route segment.
+     */
+    BASIC_SNAPPING: 'basic_snapping',
+    // ── PRO — require a valid commercial license key ────────────────────────────
+    /**
+     * Advanced route snapping with bearing penalty + inertia.
+     * Prevents incorrect snaps on parallel roads and U-turns.
+     */
+    ADVANCED_SNAPPING: 'advanced_snapping',
+    /**
+     * Dead reckoning: continues navigation during GPS signal loss.
+     * Predicts position based on last known speed and bearing.
+     */
+    DEAD_RECKONING: 'dead_reckoning',
+    /**
+     * Smooth route offset predictor for jitter-free map rendering.
+     * Advances render position at frame rate between GPS fixes.
+     */
+    ROUTE_OFFSET: 'route_offset',
+    /**
+     * Progress anti-regression: prevents route index from jumping backward.
+     * Essential for circuit routes and motorway slip roads.
+     */
+    PROGRESS_TRACKING: 'progress_tracking',
+    /**
+     * Advanced bearing engine with look-ahead and speed-adaptive alpha.
+     * Produces stable heading for smooth map camera rotation.
+     */
+    ADVANCED_BEARING: 'advanced_bearing',
+    /**
+     * Compound deviation detection: combines distance, bearing, and speed signals.
+     * Eliminates false off-route triggers in tunnels and urban canyons.
+     */
+    COMPOUND_DEVIATION: 'compound_deviation',
+    /**
+     * Parallel road disambiguation + U-turn snap protection.
+     * Prevents snapping to the wrong carriageway when bearing mismatches route direction.
+     */
+    PARALLEL_ROAD_RESOLUTION: 'parallel_road_resolution',
+    /**
+     * U-turn protection: bearing penalty applied when vehicle heading opposes
+     * route segment direction by more than the configured threshold (default 60°).
+     */
+    U_TURN_PROTECTION: 'u_turn_protection',
+    /**
+     * Timed voice instruction cues with deduplication and priority levels.
+     */
+    VOICE_TRIGGERS: 'voice_triggers',
+    /**
+     * Local ETA computation using rolling speed average — zero API calls.
+     */
+    ETA: 'eta',
+    /**
+     * Circular and polygon geofencing with enter/exit/dwell events.
+     */
+    GEOFENCING: 'geofencing',
+    /**
+     * AI-powered navigation stability: oscillation suppression + turn anticipation.
+     */
+    NAV_AI: 'nav_ai',
+};

package/dist/core/src/geo/bearing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bearing and angular math utilities.
+ */
+import type { Coordinate } from './haversine';
+/** Normalise an angle to (−180, 180] */
+export declare function normalizeAngle(angle: number): number;
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+export declare function getBearingBetweenPoints(start: Coordinate, end: Coordinate): number;
+/** Linear interpolation between two coordinates */
+export declare function interpolatePoint(a: Coordinate, b: Coordinate, t: number): Coordinate;
+//# sourceMappingURL=bearing.d.ts.map

package/dist/core/src/geo/bearing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearing.d.ts","sourceRoot":"","sources":["../../../../../core/src/geo/bearing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,wCAAwC;AACxC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAWlF;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAGpF"}

package/dist/core/src/geo/bearing.js

@@ -0,0 +1,25 @@
+/**
+ * Bearing and angular math utilities.
+ */
+/** Normalise an angle to (−180, 180] */
+export function normalizeAngle(angle) {
+    const a = angle % 360;
+    return a > 180 ? a - 360 : a < -180 ? a + 360 : a;
+}
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+export function getBearingBetweenPoints(start, end) {
+    const lat1 = start[1] * (Math.PI / 180);
+    const lon1 = start[0] * (Math.PI / 180);
+    const lat2 = end[1] * (Math.PI / 180);
+    const lon2 = end[0] * (Math.PI / 180);
+    const y = Math.sin(lon2 - lon1) * Math.cos(lat2);
+    const x = Math.cos(lat1) * Math.sin(lat2) -
+        Math.sin(lat1) * Math.cos(lat2) * Math.cos(lon2 - lon1);
+    const brng = Math.atan2(y, x);
+    return (brng * 180 / Math.PI + 360) % 360;
+}
+/** Linear interpolation between two coordinates */
+export function interpolatePoint(a, b, t) {
+    const lerp = (s, e, t) => s + (e - s) * t;
+    return [lerp(a[0], b[0], t), lerp(a[1], b[1], t)];
+}

package/dist/core/src/geo/cumulative.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pre-calculated cumulative distance caches.
+ */
+import { type Coordinate } from './haversine';
+/** Forward cumulative distances: result[i] = metres from route[0] to route[i]. O(n) build. */
+export declare function buildForwardCumulativeDistances(route: Coordinate[]): Float64Array;
+/** Reverse cumulative distances: result[i] = metres from vertex i to the end. O(1) reads. */
+export declare function buildReverseCumulativeDistances(route: Coordinate[]): Float64Array;
+//# sourceMappingURL=cumulative.d.ts.map

package/dist/core/src/geo/cumulative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cumulative.d.ts","sourceRoot":"","sources":["../../../../../core/src/geo/cumulative.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,aAAa,CAAC;AAEjE,8FAA8F;AAC9F,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,YAAY,CASjF;AAED,6FAA6F;AAC7F,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,YAAY,CASjF"}

package/dist/core/src/geo/cumulative.js

@@ -0,0 +1,20 @@
+/**
+ * Pre-calculated cumulative distance caches.
+ */
+import { haversineDistance } from './haversine';
+/** Forward cumulative distances: result[i] = metres from route[0] to route[i]. O(n) build. */
+export function buildForwardCumulativeDistances(route) {
+    const cum = new Float64Array(route.length);
+    for (let i = 1; i < route.length; i++) {
+        cum[i] = cum[i - 1] + haversineDistance(route[i - 1][1], route[i - 1][0], route[i][1], route[i][0]);
+    }
+    return cum;
+}
+/** Reverse cumulative distances: result[i] = metres from vertex i to the end. O(1) reads. */
+export function buildReverseCumulativeDistances(route) {
+    const cum = new Float64Array(route.length);
+    for (let i = route.length - 2; i >= 0; i--) {
+        cum[i] = cum[i + 1] + haversineDistance(route[i][1], route[i][0], route[i + 1][1], route[i + 1][0]);
+    }
+    return cum;
+}

package/dist/core/src/geo/haversine.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Haversine geographic math utilities.
+ * ZERO dependencies — pure math.
+ */
+/** [longitude, latitude] coordinate */
+export type Coordinate = [number, number];
+/** Haversine distance between two points in metres */
+export declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/** Forward Haversine: compute destination given start, bearing (°), distance (m) */
+export declare function destinationPoint(lat: number, lon: number, brng: number, dist: number): Coordinate;
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+export declare function getBearingBetweenPoints(c1: Coordinate, c2: Coordinate): number;
+//# sourceMappingURL=haversine.d.ts.map

package/dist/core/src/geo/haversine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"haversine.d.ts","sourceRoot":"","sources":["../../../../../core/src/geo/haversine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAI1C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAShG;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAgBjG;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,MAAM,CAa9E"}

package/dist/core/src/geo/haversine.js

@@ -0,0 +1,39 @@
+/**
+ * Haversine geographic math utilities.
+ * ZERO dependencies — pure math.
+ */
+const R_EARTH = 6371000;
+/** Haversine distance between two points in metres */
+export function haversineDistance(lat1, lon1, lat2, lon2) {
+    const dLat = (lat2 - lat1) * (Math.PI / 180);
+    const dLon = (lon2 - lon1) * (Math.PI / 180);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(lat1 * (Math.PI / 180)) * Math.cos(lat2 * (Math.PI / 180)) *
+            Math.sin(dLon / 2) * Math.sin(dLon / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R_EARTH * c;
+}
+/** Forward Haversine: compute destination given start, bearing (°), distance (m) */
+export function destinationPoint(lat, lon, brng, dist) {
+    const angularDist = dist / R_EARTH;
+    const brngRad = brng * (Math.PI / 180);
+    const latRad = lat * (Math.PI / 180);
+    const lonRad = lon * (Math.PI / 180);
+    const destLatRad = Math.asin(Math.sin(latRad) * Math.cos(angularDist) +
+        Math.cos(latRad) * Math.sin(angularDist) * Math.cos(brngRad));
+    const destLonRad = lonRad + Math.atan2(Math.sin(brngRad) * Math.sin(angularDist) * Math.cos(latRad), Math.cos(angularDist) - Math.sin(latRad) * Math.sin(destLatRad));
+    return [((destLonRad * 180 / Math.PI) + 540) % 360 - 180, destLatRad * 180 / Math.PI];
+}
+/** Bearing between two [lng, lat] coordinates in degrees [0, 360) */
+export function getBearingBetweenPoints(c1, c2) {
+    const lat1 = c1[1] * (Math.PI / 180);
+    const lon1 = c1[0] * (Math.PI / 180);
+    const lat2 = c2[1] * (Math.PI / 180);
+    const lon2 = c2[0] * (Math.PI / 180);
+    const y = Math.sin(lon2 - lon1) * Math.cos(lat2);
+    const x = Math.cos(lat1) * Math.sin(lat2) -
+        Math.sin(lat1) * Math.cos(lat2) * Math.cos(lon2 - lon1);
+    let brng = Math.atan2(y, x) * (180 / Math.PI);
+    brng = (brng + 360) % 360;
+    return brng;
+}

package/dist/core/src/geo/projection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vector projection utilities for coordinate snapping.
+ */
+import type { Coordinate } from './haversine';
+/** Project point p onto line segment [a, b]. Returns the projected coordinate. */
+export declare function projectPointOnSegment(p: Coordinate, a: Coordinate, b: Coordinate): Coordinate;
+//# sourceMappingURL=projection.d.ts.map

package/dist/core/src/geo/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../../core/src/geo/projection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAe7F"}

package/dist/core/src/geo/projection.js

@@ -0,0 +1,17 @@
+/**
+ * Vector projection utilities for coordinate snapping.
+ */
+/** Project point p onto line segment [a, b]. Returns the projected coordinate. */
+export function projectPointOnSegment(p, a, b) {
+    const [px, py] = p;
+    const [ax, ay] = a;
+    const [bx, by] = b;
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lenSq = dx * dx + dy * dy;
+    if (lenSq === 0)
+        return a;
+    let t = ((px - ax) * dx + (py - ay) * dy) / lenSq;
+    t = Math.max(0, Math.min(1, t));
+    return [ax + t * dx, ay + t * dy];
+}