@qafka/react-native 2.2.0 → 2.3.1

package/dist/components/Qafka.js

@@ -144,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,
@@ -466,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/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,

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/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,18 @@ 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]);
+    // Set when an explicit (trigger:'user') navigation fires: we navigate
+    // immediately but defer closing the voice session until the AI finishes
+    // its turn (response.done), so the closing remark isn't cut off.
+    const pendingNavDisconnectRef = (0, react_1.useRef)(false);
+    // Ref mirror of `disconnect` so handleEvent (useCallback([])) can close the
+    // session without going stale.
+    const disconnectRef = (0, react_1.useRef)(undefined);
     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 +36,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);
@@ -106,10 +123,18 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
                 transcriptRef.current = '';
                 setTranscript('');
                 setState('listening');
+                // Explicit navigation deferred its session close to here, so the AI's
+                // closing remark could finish first.
+                if (pendingNavDisconnectRef.current) {
+                    pendingNavDisconnectRef.current = false;
+                    disconnectRef.current?.();
+                }
                 return;
             }
             case 'session.closed':
                 setState('idle');
+                setNavigationSuggestion(null);
+                pendingNavDisconnectRef.current = false;
                 return;
             case 'error':
                 setState('idle');
@@ -316,6 +341,20 @@ 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') {
+                    // Explicit request: navigate now, then close the voice session once the
+                    // AI finishes speaking (handled in response.done) so the closing remark
+                    // plays and the session doesn't linger in the background.
+                    onNavigationSuggestRef.current?.(decision.suggestion);
+                    pendingNavDisconnectRef.current = true;
+                }
+                else {
+                    setNavigationSuggestion(decision.suggestion);
+                }
+                return;
+            }
         }
     }, []);
     const connect = (0, react_1.useCallback)(async () => {
@@ -369,17 +408,35 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         setTranscriptHistory([]);
         transcriptRef.current = '';
         setAmplitude(0);
+        setNavigationSuggestion(null);
+        pendingNavDisconnectRef.current = false;
         // Reset both mute layers so the next session starts clean.
         userMutedRef.current = false;
         systemMutedRef.current = false;
         setIsMuted(false);
     }, []);
+    (0, react_1.useEffect)(() => {
+        disconnectRef.current = disconnect;
+    }, [disconnect]);
     const pauseMic = (0, react_1.useCallback)(async () => {
         await serviceRef.current?.pauseMic();
     }, []);
     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);
+        // Consistent with explicit navigation: leaving for a screen ends the
+        // voice session. The AI turn is already finished here (button was shown
+        // after response.done), so close immediately.
+        disconnect();
+    }, [disconnect]);
+    const dismissNavigationSuggestion = (0, react_1.useCallback)(() => {
+        setNavigationSuggestion(null);
+    }, []);
     // Disconnect on app background
     (0, react_1.useEffect)(() => {
         const handleAppState = (nextState) => {
@@ -432,5 +489,8 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         mute,
         unmute,
         toggleMute,
+        navigationSuggestion,
+        acceptNavigationSuggestion,
+        dismissNavigationSuggestion,
     };
 }

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.2.0",
+  "version": "2.3.1",
   "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",