@qafka/react-native 2.1.1 → 2.3.0

package/dist/components/Qafka.js

@@ -86,11 +86,12 @@ const { width: SCREEN_WIDTH } = react_native_1.Dimensions.get('window');
  * />
  * ```
  */
-exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlProp, subProjectId, projectId, locale, mode = 'fullscreen', theme: themeName = 'light', customTheme, themeOverride, isAuthenticated, endUserId, endUserData, enableStreaming = true, voiceEnabled: voiceEnabledProp = true, context: userContext, contextDescription, components: customComponents, showTimestamps = true, placeholder = 'Type a message...', maxMessageLength = 500, greetingMessage, onReady, onMessageSent, onResponseReceived, onError, onNavigationSuggest, onNavigationAction, onExternalSuggestion, onCardDeepLink, onCardSuggestMessage, onCardExternalNavigation, onCardShare, onCardCopy, onCardToolTrigger, onCardCTAClick, onToolSuggested, onToolDataRequested, onActionResult, onStepCompleted, onFileUploadRequest, onExtractionResult, onClose, onBack, CloseComponent, BackComponent, navigationLabelFormat, NavigationButtonComponent, voiceComponents, voiceTranscript = 'centered', toolRenderMode, }, ref) {
+exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlProp, devConfig, subProjectId, projectId, locale, mode = 'fullscreen', theme: themeName = 'light', customTheme, themeOverride, isAuthenticated, endUserId, endUserData, enableStreaming = true, voiceEnabled: voiceEnabledProp = true, context: userContext, contextDescription, components: customComponents, showTimestamps = true, placeholder = 'Type a message...', maxMessageLength = 500, greetingMessage, onReady, onMessageSent, onResponseReceived, onError, onNavigationSuggest, onNavigationAction, onExternalSuggestion, onCardDeepLink, onCardSuggestMessage, onCardExternalNavigation, onCardShare, onCardCopy, onCardToolTrigger, onCardCTAClick, onToolSuggested, onToolDataRequested, onActionResult, onStepCompleted, onFileUploadRequest, onExtractionResult, onClose, onBack, CloseComponent, BackComponent, navigationLabelFormat, NavigationButtonComponent, voiceComponents, voiceTranscript = 'centered', toolRenderMode, }, ref) {
     // === ALL HOOKS FIRST (Rules of Hooks compliance) ===
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     const { sdkReady, error: sdkError, resolvedApiKey, resolvedApiUrl } = (0, useSDK_1.useSDK)({
         apiUrl: apiUrlProp,
+        devConfig,
         subProjectId,
         projectId,
         locale,
@@ -143,8 +144,9 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         // grouped with text-mode rows for the same user.
         endUserId: validatedEndUserId,
         endUserData: validatedEndUserData,
+        onNavigationSuggest,
     });
-    const { toolStatus: voiceToolStatus, renderedTools: voiceRenderedTools, transcriptOverrideForTurn, setToolStatusManually, clearRenderedTools, connect: voiceConnect, disconnect: voiceDisconnect, pauseMic: voicePauseMic, resumeMic: voiceResumeMic, isMuted: voiceIsMuted, mute: voiceMute, unmute: voiceUnmute, toggleMute: voiceToggleMute, } = voiceChat;
+    const { toolStatus: voiceToolStatus, renderedTools: voiceRenderedTools, transcriptOverrideForTurn, setToolStatusManually, clearRenderedTools, connect: voiceConnect, disconnect: voiceDisconnect, pauseMic: voicePauseMic, resumeMic: voiceResumeMic, isMuted: voiceIsMuted, mute: voiceMute, unmute: voiceUnmute, toggleMute: voiceToggleMute, navigationSuggestion: voiceNavigationSuggestion, acceptNavigationSuggestion: voiceAcceptNavigation, dismissNavigationSuggestion: voiceDismissNavigation, } = voiceChat;
     const { messages, isTyping, isSending, streamingMessage, toolStatus, flatListRef, handleSend, setMessages, setIsTyping, setStreamingMessage, } = (0, useChatMessages_1.useChatMessages)({
         enableStreaming,
         context: currentContext,
@@ -465,7 +467,7 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
 
  {/* Page 1: Voice — VoicePage paints Background edge-to-edge and
         handles its own internal safe-area padding for orb/transcript. */}
- <VoicePage_1.VoicePage state={voiceChat.state} transcript={voiceChat.transcript} userTranscript={voiceChat.userTranscript} transcriptHistory={voiceChat.transcriptHistory} transcriptMode={voiceTranscript} amplitude={voiceChat.amplitude} theme={theme} voiceComponents={voiceComponents} toolStatus={voiceToolStatus} renderedTools={voiceRenderedTools} registeredComponents={customComponents} transcriptOverrideForTurn={transcriptOverrideForTurn} DataChipListComponent={voiceComponents?.dataChipList} isMuted={voiceIsMuted} onToggleMute={voiceToggleMute}/>
+ <VoicePage_1.VoicePage state={voiceChat.state} transcript={voiceChat.transcript} userTranscript={voiceChat.userTranscript} transcriptHistory={voiceChat.transcriptHistory} transcriptMode={voiceTranscript} amplitude={voiceChat.amplitude} theme={theme} voiceComponents={voiceComponents} toolStatus={voiceToolStatus} renderedTools={voiceRenderedTools} registeredComponents={customComponents} transcriptOverrideForTurn={transcriptOverrideForTurn} DataChipListComponent={voiceComponents?.dataChipList} isMuted={voiceIsMuted} onToggleMute={voiceToggleMute} navigationSuggestion={voiceNavigationSuggestion} onNavigationAccept={voiceAcceptNavigation} onNavigationDismiss={voiceDismissNavigation} NavigationButtonComponent={NavigationButtonComponent}/>
  </react_native_1.ScrollView>
  </react_native_1.View>) : (<ChatPage_1.ChatPage {...chatPageProps}/>);
     return (<react_native_1.View style={[

package/dist/components/Qafka.types.d.ts

@@ -4,6 +4,7 @@ import { ComponentRegistry } from '../types/components';
 import { ExternalSuggestion } from '../types/external-navigation';
 import { NavigationSuggestion } from '../types/navigation';
 import { VoiceChatState } from './VoicePage';
+import type { RuntimeConfig } from '../runtime-config-loader';
 /**
  * Augmentation hook for consumer-side projectId literal types.
  *
@@ -256,6 +257,16 @@ export interface QafkaProps {
     * Backend API URL (OPTIONAL — advanced, leave unset for production).
     */
     apiUrl?: string;
+    /**
+     * Dev-only runtime config the SDK reads for the simulator/emulator
+     * `__DEV__` auth path. Pass the CLI-managed file:
+     *   `devConfig={__DEV__ ? require('../.qafka/qafka-runtime') : undefined}`
+     * Omit on real devices / production — attestation handles auth there, and
+     * `require` under `__DEV__` is dead-code-eliminated from release bundles so
+     * no key reaches the prod build. When omitted, the SDK falls back to the
+     * legacy `node_modules` config (backward compatible).
+     */
+    devConfig?: RuntimeConfig | null;
     /**
     * Sub-Project Identifier (OPTIONAL)
     *

package/dist/components/VoicePage.d.ts

@@ -1,6 +1,7 @@
 import React from 'react';
 import type { ComponentType } from 'react';
-import type { VoiceComponents, VoiceTranscriptMode, VoiceTranscriptTurn } from './Qafka.types';
+import type { VoiceComponents, VoiceTranscriptMode, VoiceTranscriptTurn, NavigationButtonProps } from './Qafka.types';
+import type { NavigationSuggestion } from '../types/navigation';
 export type VoiceChatState = 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking';
 interface VoiceToolStatusShape {
     toolCallId: string;
@@ -43,6 +44,10 @@ interface VoicePageProps {
     }>;
     isMuted?: boolean;
     onToggleMute?: () => void;
+    navigationSuggestion?: NavigationSuggestion | null;
+    onNavigationAccept?: () => void;
+    onNavigationDismiss?: () => void;
+    NavigationButtonComponent?: ComponentType<NavigationButtonProps>;
 }
-export declare function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode, amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn, DataChipListComponent, isMuted, onToggleMute, }: VoicePageProps): React.JSX.Element;
+export declare function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode, amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn, DataChipListComponent, isMuted, onToggleMute, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, }: VoicePageProps): React.JSX.Element;
 export {};

package/dist/components/VoicePage.js

@@ -39,6 +39,7 @@ const react_native_1 = require("react-native");
 const react_native_safe_area_context_1 = require("react-native-safe-area-context");
 const ToolStatusPill_1 = require("./ToolStatusPill");
 const DataChipList_1 = require("./DataChipList");
+const NavigationSuggestion_1 = require("./NavigationSuggestion");
 const { width: SCREEN_WIDTH } = react_native_1.Dimensions.get('window');
 const STATE_LABELS = {
     idle: 'Waiting...', connecting: 'Connecting...', listening: 'Listening...',
@@ -395,7 +396,7 @@ function ChatTranscript({ history, liveAiText, state, primaryTextColor, secondar
  </react_native_1.View>);
 }
 // --- Main component ---
-function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode = 'centered', amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn = false, DataChipListComponent, isMuted = false, onToggleMute, }) {
+function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode = 'centered', amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn = false, DataChipListComponent, isMuted = false, onToggleMute, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, }) {
     const Indicator = voiceComponents?.VoiceIndicator || DefaultVoiceIndicator;
     const Background = voiceComponents?.VoiceBackground || DefaultVoiceBackground;
     const Transcript = voiceComponents?.VoiceTranscript || DefaultVoiceTranscript;
@@ -515,6 +516,8 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  {showTranscript ? (<Transcript transcript={transcript} userTranscript={userTranscript} state={state} theme={theme} mode="centered"/>) : null}
  </react_native_1.View>)}
 
+ {!hasToolUI && navigationSuggestion ? (NavigationButtonComponent ? (<NavigationButtonComponent screenName={navigationSuggestion.screenName} suggestion={navigationSuggestion} onPress={onNavigationAccept ?? (() => { })} theme={theme} style="primary" label={navigationSuggestion.message || `Navigate to ${navigationSuggestion.screenName}`}/>) : (<NavigationSuggestion_1.NavigationSuggestionCard screenName={navigationSuggestion.screenName} message={navigationSuggestion.message} onAccept={onNavigationAccept ?? (() => { })} onDismiss={onNavigationDismiss ?? (() => { })} theme={theme}/>)) : null}
+
  {hasToolUI ? (<react_native_1.ScrollView style={{ flex: 1, width: '100%', alignSelf: 'stretch' }} contentContainerStyle={{
                 paddingHorizontal: 20,
                 paddingTop: 16,
@@ -569,7 +572,9 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
 
  {showMute && !hasToolUI ? (<react_native_1.View style={{
                 position: 'absolute',
-                top: 12,
+                // Absolute children aren't pushed by the parent's safe-area paddingTop,
+                // so add the inset here to keep the button clear of the status bar / notch.
+                top: insets.top + 12,
                 right: 16,
             }}>
  <MuteButton isMuted={isMuted} onToggle={onToggleMute} theme={theme} state={state}/>

package/dist/decide-voice-navigation.d.ts

@@ -0,0 +1,19 @@
+import type { NavigationSuggestion } from './types/navigation';
+export interface VoiceNavigationDecision {
+    action: 'callback' | 'suggest';
+    suggestion: NavigationSuggestion;
+}
+interface IncomingVoiceNavigation {
+    screenName: string;
+    route: string;
+    deeplink?: string | null;
+    message?: string;
+    trigger?: 'user' | 'ai';
+}
+/**
+ * Decide how the voice UI should react to a backend navigation event.
+ * trigger='user' → app developer navigates immediately (callback).
+ * trigger='ai' (or missing) → SDK shows a suggestion button.
+ */
+export declare function decideVoiceNavigation(nav: IncomingVoiceNavigation): VoiceNavigationDecision;
+export {};

package/dist/decide-voice-navigation.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideVoiceNavigation = decideVoiceNavigation;
+/**
+ * Decide how the voice UI should react to a backend navigation event.
+ * trigger='user' → app developer navigates immediately (callback).
+ * trigger='ai' (or missing) → SDK shows a suggestion button.
+ */
+function decideVoiceNavigation(nav) {
+    const suggestion = {
+        screenName: nav.screenName,
+        route: nav.route,
+        deeplink: nav.deeplink ?? null,
+        ...(nav.message ? { message: nav.message } : {}),
+        trigger: nav.trigger === 'user' ? 'user' : 'ai',
+        source: 'voice',
+    };
+    return {
+        action: nav.trigger === 'user' ? 'callback' : 'suggest',
+        suggestion,
+    };
+}

package/dist/hooks/useChatMessages.js

@@ -168,7 +168,11 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                     }
                     // Handle navigation suggestion
                     if (response.navigationSuggestion && onNavigationSuggest) {
-                        onNavigationSuggest(response.navigationSuggestion);
+                        onNavigationSuggest({
+                            ...response.navigationSuggestion,
+                            trigger: response.navigationSuggestion.trigger ?? 'ai',
+                            source: 'text',
+                        });
                     }
                     setIsSending(false);
                 }, 
@@ -458,7 +462,11 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                 setMessages((prev) => [...prev, aiMessage]);
                 onResponseReceived?.(response);
                 if (response.navigationSuggestion && onNavigationSuggest) {
-                    onNavigationSuggest(response.navigationSuggestion);
+                    onNavigationSuggest({
+                        ...response.navigationSuggestion,
+                        trigger: response.navigationSuggestion.trigger ?? 'ai',
+                        source: 'text',
+                    });
                 }
                 scrollToBottom();
                 setIsTyping(false);

package/dist/hooks/useSDK.d.ts

@@ -10,12 +10,15 @@ export interface UseSDKOptions {
     locale?: string;
     onReady?: () => void;
     onError?: (error: Error) => void;
+    devConfig?: unknown;
 }
 export interface UseSDKResult {
     sdkReady: boolean;
     error: string | null;
     /**
-     * Dev-only: the resolved developmentKey from `qafka.config.js`. Null in
+     * Dev-only: the resolved developmentKey from the consumer dev config — the
+     * `devConfig` prop (`.qafka/qafka-runtime.js`) or the legacy node_modules
+     * fallback. Null in
      * production builds (Metro dead-code-eliminates the dev config branch).
      * Used by `useVoiceChat` whose WebSocket auth still relies on apiKey.
      */
@@ -28,4 +31,4 @@ export interface UseSDKResult {
 /**
  * Custom hook for managing SDK initialization and lifecycle
  */
-export declare const useSDK: ({ apiUrl, subProjectId, projectId, locale, onReady, onError, }: UseSDKOptions) => UseSDKResult;
+export declare const useSDK: ({ apiUrl, subProjectId, projectId, locale, onReady, onError, devConfig, }: UseSDKOptions) => UseSDKResult;

package/dist/hooks/useSDK.js

@@ -5,10 +5,11 @@ const react_1 = require("react");
 const QafkaSDK_1 = require("../QafkaSDK");
 const runtime_config_loader_1 = require("../runtime-config-loader");
 const resolve_project_config_1 = require("../resolve-project-config");
+const resolve_runtime_config_source_1 = require("../resolve-runtime-config-source");
 /**
  * Custom hook for managing SDK initialization and lifecycle
  */
-const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, }) => {
+const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, devConfig, }) => {
     const [sdkReady, setSdkReady] = (0, react_1.useState)(false);
     const [error, setError] = (0, react_1.useState)(null);
     const [resolvedApiKey, setResolvedApiKey] = (0, react_1.useState)(null);
@@ -27,18 +28,16 @@ const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, })
         let apiKey = null;
         let resolvedUrl = apiUrl;
         if (__DEV__) {
-            // Dev path: load qafka.config.js, pick developmentKey for the current project.
-            // Metro dead-code elimination removes this branch entirely in production
-            // builds, so qafka.config.js never lands in the prod bundle.
+            // Dev path: prefer the consumer-supplied .qafka/ config, else the legacy
+            // node_modules config. Metro dead-code elimination removes this whole
+            // branch (and both requires) from production builds.
             try {
-                const cfg = (0, resolve_project_config_1.resolveProjectConfig)({ apiUrl, projectId }, (0, runtime_config_loader_1.loadRuntimeConfig)());
+                const cfg = (0, resolve_project_config_1.resolveProjectConfig)({ apiUrl, projectId }, (0, resolve_runtime_config_source_1.resolveRuntimeConfigSource)(devConfig, (0, runtime_config_loader_1.loadRuntimeConfig)()));
                 apiKey = cfg.apiKey;
                 resolvedUrl = cfg.apiUrl;
             }
             catch (err) {
-                if (__DEV__) {
-                    console.warn('[Qafka] Dev config missing or invalid:', err instanceof Error ? err.message : err);
-                }
+                console.warn('[Qafka] Dev config missing or invalid:', err instanceof Error ? err.message : err);
             }
         }
         // Expose resolved values so `useVoiceChat` (WebSocket auth still

package/dist/hooks/useVoiceChat.d.ts

@@ -1,3 +1,4 @@
+import type { NavigationSuggestion } from '../types/navigation';
 export type VoiceChatState = 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking';
 export interface VoiceToolStatus {
     toolCallId: string;
@@ -77,6 +78,12 @@ interface UseVoiceChatOptions {
      */
     endUserId?: string;
     endUserData?: Record<string, unknown>;
+    /**
+     * Callback invoked when the backend suggests navigation.
+     * trigger='user' → fires immediately (no button shown).
+     * trigger='ai' → fires when the user accepts the suggestion button.
+     */
+    onNavigationSuggest?: (suggestion: NavigationSuggestion) => void;
 }
 interface UseVoiceChatResult {
     state: VoiceChatState;
@@ -106,5 +113,11 @@ interface UseVoiceChatResult {
     mute: () => void;
     unmute: () => void;
     toggleMute: () => void;
+    /** Pending navigation suggestion waiting for user acceptance (trigger='ai'). */
+    navigationSuggestion: NavigationSuggestion | null;
+    /** Accept the pending suggestion: fires onNavigationSuggest and clears state. */
+    acceptNavigationSuggestion: () => void;
+    /** Dismiss the pending suggestion without navigating. */
+    dismissNavigationSuggestion: () => void;
 }
-export declare function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, }: UseVoiceChatOptions): UseVoiceChatResult;
+export declare function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, onNavigationSuggest, }: UseVoiceChatOptions): UseVoiceChatResult;

package/dist/hooks/useVoiceChat.js

@@ -5,7 +5,8 @@ const react_1 = require("react");
 const react_native_1 = require("react-native");
 const RealtimeService_1 = require("../services/RealtimeService");
 const QafkaAudio_1 = require("../native/QafkaAudio");
-function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode = 'upsert', getSessionToken, endUserId, endUserData, }) {
+const decide_voice_navigation_1 = require("../decide-voice-navigation");
+function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode = 'upsert', getSessionToken, endUserId, endUserData, onNavigationSuggest, }) {
     const [state, setState] = (0, react_1.useState)('idle');
     const [transcript, setTranscript] = (0, react_1.useState)('');
     const [userTranscript, setUserTranscript] = (0, react_1.useState)('');
@@ -14,6 +15,11 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
     const [toolStatus, setToolStatus] = (0, react_1.useState)(null);
     const [renderedTools, setRenderedTools] = (0, react_1.useState)([]);
     const [transcriptOverrideForTurn, setTranscriptOverrideForTurn] = (0, react_1.useState)(false);
+    const [navigationSuggestion, setNavigationSuggestion] = (0, react_1.useState)(null);
+    const navigationSuggestionRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        navigationSuggestionRef.current = navigationSuggestion;
+    }, [navigationSuggestion]);
     const serviceRef = (0, react_1.useRef)(null);
     // Snapshot of the live AI transcript so `response.done` can push the
     // finished text into history without depending on stale closure state.
@@ -23,6 +29,10 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
     (0, react_1.useEffect)(() => {
         onToolSuggestedRef.current = onToolSuggested;
     }, [onToolSuggested]);
+    const onNavigationSuggestRef = (0, react_1.useRef)(onNavigationSuggest);
+    (0, react_1.useEffect)(() => {
+        onNavigationSuggestRef.current = onNavigationSuggest;
+    }, [onNavigationSuggest]);
     // handleEvent is wrapped in useCallback([]) so we read the live value
     // through a ref to avoid stale closures.
     const toolRenderModeRef = (0, react_1.useRef)(toolRenderMode);
@@ -110,6 +120,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
             }
             case 'session.closed':
                 setState('idle');
+                setNavigationSuggestion(null);
                 return;
             case 'error':
                 setState('idle');
@@ -316,6 +327,16 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
                 setToolStatus((s) => (s?.toolCallId === event.toolCallId ? null : s));
                 systemUnmute();
                 return;
+            case 'navigation': {
+                const decision = (0, decide_voice_navigation_1.decideVoiceNavigation)(event.navigation);
+                if (decision.action === 'callback') {
+                    onNavigationSuggestRef.current?.(decision.suggestion);
+                }
+                else {
+                    setNavigationSuggestion(decision.suggestion);
+                }
+                return;
+            }
         }
     }, []);
     const connect = (0, react_1.useCallback)(async () => {
@@ -369,6 +390,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         setTranscriptHistory([]);
         transcriptRef.current = '';
         setAmplitude(0);
+        setNavigationSuggestion(null);
         // Reset both mute layers so the next session starts clean.
         userMutedRef.current = false;
         systemMutedRef.current = false;
@@ -380,6 +402,15 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
     const resumeMic = (0, react_1.useCallback)(async () => {
         await serviceRef.current?.resumeMic();
     }, []);
+    const acceptNavigationSuggestion = (0, react_1.useCallback)(() => {
+        const current = navigationSuggestionRef.current;
+        setNavigationSuggestion(null);
+        if (current)
+            onNavigationSuggestRef.current?.(current);
+    }, []);
+    const dismissNavigationSuggestion = (0, react_1.useCallback)(() => {
+        setNavigationSuggestion(null);
+    }, []);
     // Disconnect on app background
     (0, react_1.useEffect)(() => {
         const handleAppState = (nextState) => {
@@ -432,5 +463,8 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         mute,
         unmute,
         toggleMute,
+        navigationSuggestion,
+        acceptNavigationSuggestion,
+        dismissNavigationSuggestion,
     };
 }

package/dist/resolve-runtime-config-source.d.ts

@@ -0,0 +1,9 @@
+import { type RuntimeConfig } from './runtime-config-loader';
+/**
+ * Pick the runtime config the SDK should use in dev builds.
+ *
+ * Precedence: a valid `devConfig` (the consumer's `require('../.qafka/qafka-runtime')`,
+ * shape-validated) wins; otherwise the value loaded from the SDK package
+ * (`loadRuntimeConfig()`). Returns null when neither yields a usable config.
+ */
+export declare function resolveRuntimeConfigSource(devConfig: unknown, loaded: RuntimeConfig | null): RuntimeConfig | null;

package/dist/resolve-runtime-config-source.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRuntimeConfigSource = resolveRuntimeConfigSource;
+const runtime_config_loader_1 = require("./runtime-config-loader");
+/**
+ * Pick the runtime config the SDK should use in dev builds.
+ *
+ * Precedence: a valid `devConfig` (the consumer's `require('../.qafka/qafka-runtime')`,
+ * shape-validated) wins; otherwise the value loaded from the SDK package
+ * (`loadRuntimeConfig()`). Returns null when neither yields a usable config.
+ */
+function resolveRuntimeConfigSource(devConfig, loaded) {
+    const provided = devConfig != null ? (0, runtime_config_loader_1.normalizeRuntimeConfig)(devConfig) : null;
+    return provided ?? loaded;
+}

package/dist/services/RealtimeService.d.ts

@@ -31,6 +31,15 @@ export type RealtimeEvent = {
 } | {
     type: 'tool_done';
     toolCallId: string;
+} | {
+    type: 'navigation';
+    navigation: {
+        screenName: string;
+        route: string;
+        deeplink?: string | null;
+        message?: string;
+        trigger?: 'user' | 'ai';
+    };
 };
 export type RealtimeEventHandler = (event: RealtimeEvent) => void;
 export declare class RealtimeService {

package/dist/types/navigation.d.ts

@@ -74,6 +74,10 @@ export interface NavigationSuggestion {
     confirmed?: boolean;
     message?: string;
     reasoning?: string;
+    /** Who triggered this: 'user' = explicit request, 'ai' = proactive suggestion. */
+    trigger?: 'user' | 'ai';
+    /** Which mode produced it. */
+    source?: 'text' | 'voice';
 }
 /**
  * Route matching result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Drop-in AI assistant for React Native: chat, voice, and tool execution with screen-aware navigation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",