@ingissa/navcore-react-native 1.0.4 → 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

@@ -0,0 +1,33 @@
+/**
+ * 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 { type ReactNode } from 'react';
+import { NavCore, type NavCoreOptions } from '@ingissa/navcore-core';
+interface NavCoreContextValue {
+    engine: NavCore;
+}
+interface NavCoreProviderProps {
+    children: ReactNode;
+    options?: NavCoreOptions;
+}
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+export declare function NavCoreProvider({ children, options }: NavCoreProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+export declare function useNavCoreContext(): NavCoreContextValue;
+export {};
+//# sourceMappingURL=NavCoreProvider.d.ts.map

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/NavCoreProvider.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 } from 'react';
+import { NavCore } from '@ingissa/navcore-core';
+const NavCoreContext = createContext(null);
+/**
+ * Wraps children with a shared NavCore engine instance.
+ *
+ * ```tsx
+ * <NavCoreProvider options={{ licenseKey: '...' }}>
+ *   <MapScreen />
+ *   <InstructionBanner />
+ * </NavCoreProvider>
+ * ```
+ */
+export function NavCoreProvider({ children, options }) {
+    const engineRef = useRef(null);
+    if (!engineRef.current) {
+        engineRef.current = new NavCore(options);
+    }
+    const value = useMemo(() => ({
+        engine: engineRef.current,
+    }), []);
+    return (_jsx(NavCoreContext.Provider, { value: value, children: children }));
+}
+/**
+ * Access the shared NavCore engine from context.
+ * Must be used within a <NavCoreProvider>.
+ */
+export function useNavCoreContext() {
+    const ctx = useContext(NavCoreContext);
+    if (!ctx) {
+        throw new Error('useNavCoreContext must be used within a <NavCoreProvider>');
+    }
+    return ctx;
+}

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/react-native/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * @navcore/react-native — React Native bindings
+ *
+ * Provides hooks for integrating NavCore with React Native apps.
+ */
+export { useNavCore } from './useNavCore';
+export { NavCoreProvider, useNavCoreContext } from './NavCoreProvider';
+export { useNavSelector, useNavInstruction, useNavAlert, useNavProgress, useNavIsOffRoute, useNavSpeed, } from './useNavSelectors';

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

@@ -1,7 +1,3 @@
-import { Coordinate, NavInstruction, NavCoreOptions, NavCoreState, NavCore } from '@ingissa/navcore-core';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-
 /**
  * useNavCore — React hook for the NavCore navigation engine.
  *
@@ -10,8 +6,8 @@ import { ReactNode } from 'react';
  *
  * Drop-in replacement for the existing Go4Exams useNavCore hook.
  */
-
-interface UseNavCoreProps {
+import { NavCore, type NavCoreOptions, type NavCoreState, type NavInstruction, type Coordinate } from '@ingissa/navcore-core';
+export interface UseNavCoreProps {
     /** Current GPS coordinate [lng, lat] */
     gpsCoord: Coordinate | null;
     /** GPS bearing in degrees */
@@ -33,11 +29,13 @@ 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;
@@ -54,34 +52,9 @@ interface UseNavCoreProps {
     /** UI polling rate in Hz (default 30) */
     pollRateHz?: number;
 }
-interface UseNavCoreReturn extends NavCoreState {
+export interface UseNavCoreReturn extends NavCoreState {
     /** The raw NavCore engine instance (for advanced usage) */
     engine: NavCore;
 }
-declare function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz, }: UseNavCoreProps): UseNavCoreReturn;
-
-interface NavCoreContextValue {
-    engine: NavCore;
-}
-interface NavCoreProviderProps {
-    children: ReactNode;
-    options?: NavCoreOptions;
-}
-/**
- * Wraps children with a shared NavCore engine instance.
- *
- * ```tsx
- * <NavCoreProvider options={{ licenseKey: '...' }}>
- *   <MapScreen />
- *   <InstructionBanner />
- * </NavCoreProvider>
- * ```
- */
-declare function NavCoreProvider({ children, options }: NavCoreProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Access the shared NavCore engine from context.
- * Must be used within a <NavCoreProvider>.
- */
-declare function useNavCoreContext(): NavCoreContextValue;
-
-export { NavCoreProvider, type UseNavCoreProps, type UseNavCoreReturn, useNavCore, useNavCoreContext };
+export declare function useNavCore({ gpsCoord, gpsBearing, gpsAccuracy, gpsTimestamp, speed, routeGeometry, instructions, isNavigating, options, resumeAtIndex, outputRef, onDeviation, onRejoin, onInstruction, onArrival, pollRateHz, }: UseNavCoreProps): UseNavCoreReturn;
+//# sourceMappingURL=useNavCore.d.ts.map

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/react-native/src/useNavCore.js

@@ -0,0 +1,119 @@
+/**
+ * useNavCore — React hook for the NavCore navigation engine.
+ *
+ * Manages engine lifecycle, GPS → engine → state pipeline,
+ * event wiring, and optimized re-render batching.
+ *
+ * Drop-in replacement for the existing Go4Exams useNavCore hook.
+ */
+import { useState, useEffect, useRef, useMemo } from 'react';
+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 ───────────────────────────────────────
+    const navRef = useRef(null);
+    if (!navRef.current) {
+        navRef.current = new NavCore(options);
+    }
+    const engine = navRef.current;
+    const [state, setState] = useState(() => engine.getState());
+    // ── 2. Event wiring ───────────────────────────────────────────
+    // 2a. Deviation
+    useEffect(() => {
+        if (!onDeviation)
+            return;
+        const handler = (data) => onDeviation(data);
+        engine.on('deviation', handler);
+        return () => { engine.off('deviation', handler); };
+    }, [engine, onDeviation]);
+    // 2b. Rejoin
+    useEffect(() => {
+        if (!onRejoin)
+            return;
+        const handler = (data) => onRejoin(data);
+        engine.on('rejoined', handler);
+        return () => { engine.off('rejoined', handler); };
+    }, [engine, onRejoin]);
+    // 2c. Instruction
+    useEffect(() => {
+        if (!onInstruction)
+            return;
+        const handler = (data) => onInstruction(data);
+        engine.on('instruction', handler);
+        return () => { engine.off('instruction', handler); };
+    }, [engine, onInstruction]);
+    // 2d. Arrival
+    useEffect(() => {
+        if (!onArrival)
+            return;
+        const handler = () => onArrival();
+        engine.on('arrival', handler);
+        return () => { engine.off('arrival', handler); };
+    }, [engine, onArrival]);
+    // ── 3. Route sync ────────────────────────────────────────────
+    useEffect(() => {
+        if (routeGeometry && routeGeometry.length >= 2) {
+            engine.setRoute(routeGeometry, instructions);
+        }
+    }, [engine, routeGeometry]);
+    // ── 4. Instructions sync (can change independently of route) ──
+    useEffect(() => {
+        if (instructions && instructions.length > 0 && routeGeometry && routeGeometry.length >= 2) {
+            engine.setRoute(routeGeometry, instructions);
+        }
+    }, [engine, instructions]);
+    // ── 5. GPS → engine pipeline ──────────────────────────────────
+    useEffect(() => {
+        if (!gpsCoord || !isNavigating)
+            return;
+        const gpsUpdate = {
+            coord: gpsCoord,
+            accuracy: gpsAccuracy ?? null,
+            bearing: gpsBearing ?? null,
+            speed,
+            timestamp: gpsTimestamp ?? Date.now(),
+        };
+        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. 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 handleUpdate = (updatedState) => {
+            setState(updatedState);
+        };
+        engine.on('update', handleUpdate);
+        setState(engine.getState());
+        return () => {
+            engine.off('update', handleUpdate);
+        };
+    }, [engine, isNavigating]);
+    // ── 8. Cleanup ────────────────────────────────────────────────
+    useEffect(() => {
+        return () => {
+            engine.destroy();
+            navRef.current = null;
+        };
+    }, [engine]);
+    // ── 9. Stable return ──────────────────────────────────────────
+    return useMemo(() => ({
+        ...state,
+        engine,
+    }), [state, engine]);
+}

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);
+}