@ingissa/navcore-react-native 1.0.3 → 1.0.7

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

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

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

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

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

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

package/dist/react-native/src/NavCoreProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavCoreProvider.d.ts","sourceRoot":"","sources":["../../../src/NavCoreProvider.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA8C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACnF,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAErE,UAAU,mBAAmB;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,oBAAoB,2CAe1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAMvD"}

package/dist/react-native/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @navcore/react-native — React Native bindings
+ *
+ * Provides hooks for integrating NavCore with React Native apps.
+ */
+export { useNavCore } from './useNavCore';
+export type { UseNavCoreProps, UseNavCoreReturn } from './useNavCore';
+export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
+export { useNavSelector, useNavInstruction, useNavAlert, useNavProgress, useNavIsOffRoute, useNavSpeed, type NavProgressInfo, } from './useNavSelectors';
+//# sourceMappingURL=index.d.ts.map

package/dist/react-native/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/{index.js → react-native/src/index.js}

@@ -5,3 +5,4 @@
  */
 export { useNavCore } from './useNavCore';
 export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
+export { useNavSelector, useNavInstruction, useNavAlert, useNavProgress, useNavIsOffRoute, useNavSpeed, } from './useNavSelectors';

package/dist/{useNavCore.d.ts → react-native/src/useNavCore.d.ts}

@@ -29,11 +29,13 @@ export interface UseNavCoreProps {
     /** Resume navigation at a specific route index (after rejoin) */
     resumeAtIndex?: number | null;
     /** Ref for external camera output (map camera integration) */
-    outputRef?: React.MutableRefObject<{
-        coord: Coordinate;
-        bearing: number;
-        speed: number;
-    } | null>;
+    outputRef?: {
+        current: {
+            coord: Coordinate;
+            bearing: number;
+            speed: number;
+        } | null;
+    };
     /** Called when deviation is confirmed */
     onDeviation?: (event: {
         anchorIndex: number;

package/dist/react-native/src/useNavCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavCore.d.ts","sourceRoot":"","sources":["../../../src/useNavCore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EAEnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAI/B,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,aAAa,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACnC,8BAA8B;IAC9B,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8DAA8D;IAC9D,SAAS,CAAC,EAAE;QACV,OAAO,EAAE;YACP,KAAK,EAAE,UAAU,CAAC;YAClB,OAAO,EAAE,MAAM,CAAC;YAChB,KAAK,EAAE,MAAM,CAAC;SACf,GAAG,IAAI,CAAC;KACV,CAAC;IACF,yCAAyC;IACzC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/E,mCAAmC;IACnC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpD,0CAA0C;IAC1C,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,cAAc,KAAK,IAAI,CAAC;IACtD,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,EACb,SAAS,EACT,UAAe,GAChB,EAAE,eAAe,GAAG,gBAAgB,CAyHpC"}

package/dist/{useNavCore.js → react-native/src/useNavCore.js}

@@ -7,7 +7,7 @@
  * Drop-in replacement for the existing Go4Exams useNavCore hook.
  */
 import { useState, useEffect, useRef, useMemo } from 'react';
-import { NavCore } from '@ingissa/navcore-core';
+import { NavCore, } from '@ingissa/navcore-core';
 // ── Hook ──────────────────────────────────────────────────────
 export function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz = 30, }) {
     // ── 1. Engine singleton ───────────────────────────────────────
@@ -73,63 +73,37 @@ export function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, sp
             speed,
             timestamp: gpsTimestamp ?? Date.now(),
         };
-        engine.update(gpsUpdate);
-    }, [engine, gpsCoord, gpsAccuracy, gpsBearing, gpsTimestamp, speed, isNavigating]);
+        const nextState = engine.update(gpsUpdate);
+        // Synchronous external camera/puck output with ZERO React re-renders
+        if (outputRef) {
+            outputRef.current = {
+                coord: nextState.snappedCoord ?? gpsCoord,
+                bearing: nextState.bearing,
+                speed: nextState.currentSpeed,
+            };
+        }
+    }, [engine, gpsCoord, gpsAccuracy, gpsBearing, gpsTimestamp, speed, isNavigating, outputRef]);
     // ── 6. Start navigation ───────────────────────────────────────
     useEffect(() => {
         if (isNavigating) {
             engine.startNavigation();
         }
     }, [engine, isNavigating]);
-    // ── 7. Optimized state polling ────────────────────────────────
-    //    Polls at pollRateHz to batch state reads and minimize re-renders.
-    //    Only triggers setState when positional properties actually change.
+    // ── 7. Push-based reactive state subscription ─────────────────
+    //    Eliminates the 30 Hz setInterval loop. Updates state reactively
+    //    only when new engine state is computed.
     useEffect(() => {
         if (!isNavigating)
             return;
-        const lastRef = {
-            snapped: [0, 0],
-            bearing: 0,
-            raw: [0, 0],
+        const handleUpdate = (updatedState) => {
+            setState(updatedState);
         };
-        const intervalMs = Math.round(1000 / pollRateHz);
-        const poll = () => {
-            const live = engine.getState();
-            let changed = false;
-            // Bearing delta
-            if (Math.abs(live.bearing - lastRef.bearing) > 0.1) {
-                lastRef.bearing = live.bearing;
-                changed = true;
-            }
-            // Snapped coordinate delta
-            if (live.snappedCoord &&
-                (live.snappedCoord[0] !== lastRef.snapped[0] ||
-                    live.snappedCoord[1] !== lastRef.snapped[1])) {
-                lastRef.snapped = [live.snappedCoord[0], live.snappedCoord[1]];
-                changed = true;
-            }
-            // Raw GPS delta
-            if (live.rawGpsCoord &&
-                (live.rawGpsCoord[0] !== lastRef.raw[0] ||
-                    live.rawGpsCoord[1] !== lastRef.raw[1])) {
-                lastRef.raw = [live.rawGpsCoord[0], live.rawGpsCoord[1]];
-                changed = true;
-            }
-            if (changed) {
-                setState(live);
-            }
-            // Camera output ref
-            if (outputRef?.current !== undefined) {
-                outputRef.current = {
-                    coord: live.snappedCoord ?? lastRef.snapped,
-                    bearing: live.bearing,
-                    speed: live.currentSpeed,
-                };
-            }
+        engine.on('update', handleUpdate);
+        setState(engine.getState());
+        return () => {
+            engine.off('update', handleUpdate);
         };
-        const id = setInterval(poll, intervalMs);
-        return () => clearInterval(id);
-    }, [engine, isNavigating, pollRateHz, outputRef]);
+    }, [engine, isNavigating]);
     // ── 8. Cleanup ────────────────────────────────────────────────
     useEffect(() => {
         return () => {

package/dist/react-native/src/useNavSelectors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Granular selector hooks for NavCore.
+ *
+ * Built with React 18 `useSyncExternalStore` for flicker-free, tearing-free
+ * state subscriptions. Components only re-render when the selected slice changes.
+ */
+import type { NavCore, NavCoreState, NavInstruction } from '@ingissa/navcore-core';
+/**
+ * Generic reactive selector subscribing to NavCore state updates.
+ * Only triggers re-renders when the selected value actually changes.
+ */
+export declare function useNavSelector<T>(selector: (state: NavCoreState) => T, customEngine?: NavCore, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Hook to select the current upcoming turn-by-turn navigation instruction.
+ * Only re-renders when the instruction changes or triggers.
+ */
+export declare function useNavInstruction(customEngine?: NavCore): NavInstruction | null;
+/**
+ * Hook to select current alert/deviation state ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED').
+ * Only re-renders on alert state transitions.
+ */
+export declare function useNavAlert(customEngine?: NavCore): NavCoreState['alertState'];
+export interface NavProgressInfo {
+    distanceToDestination: number | null;
+    distanceToNextInstruction: number | null;
+    progressIndex: number;
+    routeIndex: number;
+    hasArrived: boolean;
+}
+/**
+ * Hook to select navigation progress and remaining distance metrics.
+ */
+export declare function useNavProgress(customEngine?: NavCore): NavProgressInfo;
+/**
+ * Hook to select whether the vehicle is currently off-route.
+ */
+export declare function useNavIsOffRoute(customEngine?: NavCore): boolean;
+/**
+ * Hook to select current speed in m/s.
+ */
+export declare function useNavSpeed(customEngine?: NavCore): number;
+//# sourceMappingURL=useNavSelectors.d.ts.map

package/dist/react-native/src/useNavSelectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNavSelectors.d.ts","sourceRoot":"","sources":["../../../src/useNavSelectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGnF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,CAAC,EACpC,YAAY,CAAC,EAAE,OAAO,EACtB,OAAO,GAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAmB,GAC3C,CAAC,CAsCH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAe/E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC,YAAY,CAAC,CAM9E;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,eAAe,CAiBtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAMhE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAM1D"}

package/dist/react-native/src/useNavSelectors.js

@@ -0,0 +1,103 @@
+/**
+ * Granular selector hooks for NavCore.
+ *
+ * Built with React 18 `useSyncExternalStore` for flicker-free, tearing-free
+ * state subscriptions. Components only re-render when the selected slice changes.
+ */
+import { useSyncExternalStore, useRef, useCallback } from 'react';
+import { useNavCoreContext } from './NavCoreProvider';
+/**
+ * Generic reactive selector subscribing to NavCore state updates.
+ * Only triggers re-renders when the selected value actually changes.
+ */
+export function useNavSelector(selector, customEngine, isEqual = Object.is) {
+    let contextEngine;
+    try {
+        contextEngine = useNavCoreContext().engine;
+    }
+    catch {
+        contextEngine = undefined;
+    }
+    const engine = customEngine ?? contextEngine;
+    if (!engine) {
+        throw new Error('useNavSelector must be provided an engine or used within a NavCoreProvider');
+    }
+    const lastSelectedRef = useRef(undefined);
+    const lastStateRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const currentState = engine.getState();
+        if (lastStateRef.current === currentState && lastSelectedRef.current !== undefined) {
+            return lastSelectedRef.current;
+        }
+        const nextSelected = selector(currentState);
+        if (lastSelectedRef.current !== undefined && isEqual(lastSelectedRef.current, nextSelected)) {
+            return lastSelectedRef.current;
+        }
+        lastStateRef.current = currentState;
+        lastSelectedRef.current = nextSelected;
+        return nextSelected;
+    }, [engine, selector, isEqual]);
+    const subscribe = useCallback((onStoreChange) => {
+        engine.on('update', onStoreChange);
+        return () => {
+            engine.off('update', onStoreChange);
+        };
+    }, [engine]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Hook to select the current upcoming turn-by-turn navigation instruction.
+ * Only re-renders when the instruction changes or triggers.
+ */
+export function useNavInstruction(customEngine) {
+    return useNavSelector((state) => {
+        if (state.nextInstructionIndex === null)
+            return null;
+        let engine = customEngine;
+        if (!engine) {
+            try {
+                engine = useNavCoreContext().engine;
+            }
+            catch { /* ignore */ }
+        }
+        if (!engine)
+            return null;
+        const list = engine.getInstructions();
+        return list[state.nextInstructionIndex] ?? null;
+    }, customEngine, (a, b) => a === b || (a?.geometryIndex === b?.geometryIndex && a?.instruction === b?.instruction));
+}
+/**
+ * Hook to select current alert/deviation state ('NONE' | 'DEVIATING' | 'RECALCULATING' | 'REJOINING' | 'REJOINED').
+ * Only re-renders on alert state transitions.
+ */
+export function useNavAlert(customEngine) {
+    return useNavSelector((state) => state.alertState, customEngine, Object.is);
+}
+/**
+ * Hook to select navigation progress and remaining distance metrics.
+ */
+export function useNavProgress(customEngine) {
+    return useNavSelector((state) => ({
+        distanceToDestination: state.distanceToDestination,
+        distanceToNextInstruction: state.distanceToNextInstruction,
+        progressIndex: state.progressIndex,
+        routeIndex: state.routeIndex,
+        hasArrived: state.hasArrived,
+    }), customEngine, (a, b) => a.distanceToDestination === b.distanceToDestination &&
+        a.distanceToNextInstruction === b.distanceToNextInstruction &&
+        a.progressIndex === b.progressIndex &&
+        a.routeIndex === b.routeIndex &&
+        a.hasArrived === b.hasArrived);
+}
+/**
+ * Hook to select whether the vehicle is currently off-route.
+ */
+export function useNavIsOffRoute(customEngine) {
+    return useNavSelector((state) => state.isOffRoute, customEngine, Object.is);
+}
+/**
+ * Hook to select current speed in m/s.
+ */
+export function useNavSpeed(customEngine) {
+    return useNavSelector((state) => state.currentSpeed, customEngine, Object.is);
+}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@ingissa/navcore-react-native",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "React Native bindings for the NavCore navigation engine.",
   "author": "Ingissa <8abnav@gmail.com>",
-  "license": "Commercial",
-  "homepage": "https://navcore-web.vercel.app/",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://navcore.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ingissa/ingissa-navcore-examples.git"
+    "url": "git+https://github.com/ingissa/navcore-sdk.git"
   },
   "bugs": {
-    "url": "https://github.com/ingissa/ingissa-navcore-examples/issues"
+    "url": "https://github.com/ingissa/navcore-sdk/issues"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -22,25 +22,33 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=16"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@ingissa/navcore-core": "^1.0.3",
+    "@ingissa/navcore-core": "^1.0.7",
     "react": ">=18.0.0",
     "react-native": ">=0.72.0",
     "react-native-maps": ">=1.0.0"
   },
   "peerDependenciesMeta": {
-    "react-native-maps": { "optional": true }
+    "react-native-maps": {
+      "optional": true
+    }
   },
   "dependencies": {}
 }

package/src/NavCoreProvider.tsx

@@ -0,0 +1,59 @@
+/**
+ * NavCoreProvider — React Context for shared NavCore engine access.
+ *
+ * Use when multiple components need access to the same engine instance
+ * (e.g. map view, instruction banner, debug panel).
+ */
+
+import { createContext, useContext, useRef, useMemo, type ReactNode } from 'react';
+import { NavCore, type NavCoreOptions } from '@ingissa/navcore-core';
+
+interface NavCoreContextValue {
+  engine: NavCore;
+}
+
+const NavCoreContext = createContext<NavCoreContextValue | null>(null);
+
+interface NavCoreProviderProps {
+  children: ReactNode;
+  options?: NavCoreOptions;
+}
+
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+export function NavCoreProvider({ children, options }: NavCoreProviderProps) {
+  const engineRef = useRef<NavCore | null>(null);
+  if (!engineRef.current) {
+    engineRef.current = new NavCore(options);
+  }
+
+  const value = useMemo(() => ({
+    engine: engineRef.current!,
+  }), []);
+
+  return (
+    <NavCoreContext.Provider value={value}>
+      {children}
+    </NavCoreContext.Provider>
+  );
+}
+
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+export function useNavCoreContext(): NavCoreContextValue {
+  const ctx = useContext(NavCoreContext);
+  if (!ctx) {
+    throw new Error('useNavCoreContext must be used within a <NavCoreProvider>');
+  }
+  return ctx;
+}

package/{dist/index.d.ts → src/index.ts}

@@ -1,9 +1,18 @@
-/**
- * @navcore/react-native — React Native bindings
- *
- * Provides hooks for integrating NavCore with React Native apps.
- */
-export { useNavCore } from './useNavCore';
-export type { UseNavCoreProps, UseNavCoreReturn } from './useNavCore';
-export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @navcore/react-native — React Native bindings
+ *
+ * Provides hooks for integrating NavCore with React Native apps.
+ */
+
+export { useNavCore } from './useNavCore';
+export type { UseNavCoreProps, UseNavCoreReturn } from './useNavCore';
+export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
+export {
+  useNavSelector,
+  useNavInstruction,
+  useNavAlert,
+  useNavProgress,
+  useNavIsOffRoute,
+  useNavSpeed,
+  type NavProgressInfo,
+} from './useNavSelectors';