@modelnex/sdk 0.1.2 → 0.5.3

package/README.md

@@ -8,10 +8,21 @@ React SDK for ModelNex agent chat, tours, and guided onboarding.
 npm install @modelnex/sdk react react-dom zod
 ```
 
+## Unit Tests
+
+Run the SDK unit tests from the `sdk` package directory:
+
+```bash
+cd sdk
+npm test
+```
+
+The SDK test script builds `dist/` first, then runs the unit tests.
+
 ## Quick Start
 
 ```tsx
-import { ModelNexProvider, ModelNexChatBubble, ModelNexOnboardingPanel } from '@modelnex/sdk';
+import { ModelNexProvider, ModelNexChatBubble } from '@modelnex/sdk';
 
 export default function AppShell() {
   return (
@@ -28,7 +39,6 @@ export default function AppShell() {
     >
       <App />
       <ModelNexChatBubble appName="My Product" />
-      <ModelNexOnboardingPanel appName="My Product" />
     </ModelNexProvider>
   );
 }
@@ -36,13 +46,32 @@ export default function AppShell() {
 
 `websiteId` identifies the integration. `userProfile` is used for tour/onboarding targeting and completion tracking. `tourFacts.features` is used for `feature_unlocked` experiences.
 
+## Tour Start Model
+
+ModelNex currently supports these automatic trigger types:
+
+- `first_visit`
+- `feature_unlocked`
+- `manual`
+
+Each tour or onboarding flow can also configure:
+
+- `startPolicy`: `immediate_start` | `prompt_only` | `manual_only`
+- `notificationType`: `bubble_card` | `modal`
+
+Current behavior:
+
+- `prompt_only + bubble_card` shows an in-bubble prompt
+- `prompt_only + modal` shows a centered modal
+- `immediate_start` starts playback immediately
+- `manual_only` never auto-surfaces
+
 ## Main Exports
 
 | Export | Purpose |
 |--------|---------|
 | `ModelNexProvider` | Root provider for server connection, chat state, dev tools, tours, and onboarding |
-| `ModelNexChatBubble` | General-purpose assistant UI plus recording/review tools |
-| `ModelNexOnboardingPanel` | Dedicated customer-facing UI for `type: 'onboarding'` flows |
+| `ModelNexChatBubble` | Unified assistant UI for chat, voice tours, and guided onboarding |
 | `useRunCommand` | Run agent commands from custom UI |
 | `useRegisterAction` | Register app actions the agent can execute |
 | `useTourPlayback` | Low-level playback hook for tours and shared experience runtime |

package/dist/aom-HDYNCIOY.mjs

@@ -0,0 +1,10 @@
+import {
+  clearAOMMap,
+  generateMinifiedAOM,
+  getElementByUid
+} from "./chunk-N65UEB6X.mjs";
+export {
+  clearAOMMap,
+  generateMinifiedAOM,
+  getElementByUid
+};

package/dist/{aom-J6NYMGDW.mjs → chunk-N65UEB6X.mjs}

@@ -62,8 +62,9 @@ function clearAOMMap() {
   uidMap.clear();
   nextUid = 1;
 }
+
 export {
-  clearAOMMap,
   generateMinifiedAOM,
-  getElementByUid
+  getElementByUid,
+  clearAOMMap
 };

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type ExperienceType = 'tour' | 'onboarding';
-type TourStepType = 'narrate' | 'act' | 'ask_and_fill' | 'user_input' | 'ask_or_fill';
+type TourStepType = 'narrate' | 'act' | 'input' | 'ask_and_fill' | 'user_input' | 'ask_or_fill' | 'wait_then_act';
 type TourUserActionEvent = 'click' | 'input' | 'change' | 'blur';
 interface TourActionTarget {
     uid?: string;
@@ -58,7 +58,7 @@ interface TourRecordedClick {
     /** Visible text or placeholder captured at record time */
     textContaining: string;
 }
-type TourCaptureEventType = 'session_start' | 'route' | 'click' | 'input' | 'note';
+type TourCaptureEventType = 'session_start' | 'route' | 'hover' | 'click' | 'input' | 'note';
 interface TourCaptureEvent {
     id: string;
     type: TourCaptureEventType;
@@ -134,7 +134,7 @@ interface TourStep {
     /** Optional onboarding-specific step metadata */
     onboarding?: OnboardingStepMetadata;
 }
-type TourTrigger = 'first_visit' | 'feature_unlocked' | 'feature_unlock' | 'idle_on_empty_state' | 'return_visit' | 'new_feature' | 'manual';
+type TourTrigger = 'first_visit' | 'feature_launch' | 'feature_unlocked' | 'feature_unlock' | 'new_feature' | 'manual';
 type TourStartPolicy = 'immediate_start' | 'prompt_only' | 'manual_only';
 type TourNotificationType = 'bubble_card' | 'modal';
 interface TourVoiceConfig {
@@ -142,13 +142,21 @@ interface TourVoiceConfig {
     ttsVoice?: string;
     ttsPrefetchLeadMs?: number;
 }
+interface ExperienceModalConfig {
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    cancelButtonText?: string;
+    backgroundColor?: string;
+    textColor?: string;
+}
 interface ExperiencePresentation {
-    launcher?: 'tour_bubble' | 'onboarding_bubble' | 'checklist' | 'none';
     theme?: {
         tone?: 'guide' | 'coach' | 'operator';
         accentColor?: string;
         icon?: string;
     };
+    modalConfig?: ExperienceModalConfig;
 }
 interface ExperienceGoal {
     primaryAction?: string;
@@ -171,6 +179,11 @@ interface Tour {
     goal?: ExperienceGoal;
     capture?: {
         experienceType?: ExperienceType;
+        instructions?: {
+            transcript?: string;
+            noteEvents?: TourCaptureEvent[];
+        };
+        notes?: RecordingStep[];
         onboardingHints?: {
             inferredWaitTargets?: number;
             inferredCompletionSignals?: number;
@@ -196,7 +209,7 @@ interface TourFacts {
     features?: string[];
 }
 /** Playback state machine states */
-type TourPlaybackState = 'idle' | 'intro' | 'executing' | 'thinking' | 'waiting_voice' | 'waiting_input' | 'complete';
+type TourPlaybackState = 'idle' | 'intro' | 'executing' | 'thinking' | 'waiting_voice' | 'waiting_input' | 'paused' | 'complete';
 /** Internal recording step being built */
 interface RecordingStep {
     order: number;
@@ -468,23 +481,36 @@ interface ModelNexChatBubbleProps {
     }>;
     /** Welcome message when chat is empty */
     welcomeMessage?: string;
+    /** Name of the AI agent displayed in the header */
+    agentName?: string;
     /** Display name of the app — used in tour intro narration */
     appName?: string;
     /** Save recorded flows as tours or onboarding without changing the recorder UX */
     recordingExperienceType?: ExperienceType;
+    /** Custom theme overrides */
+    theme?: {
+        accentColor?: string;
+        accentForeground?: string;
+        panelWidth?: string;
+        panelMaxHeight?: string;
+        bubbleSize?: string;
+        bubbleIconSize?: string;
+        borderRadius?: string;
+        zIndex?: number;
+    };
 }
 /**
  * Chat interface for natural language commands.
  * Shows conversation history; on exit, the agent summarizes what it did and suggests next steps.
  * Use within ModelNexProvider. Omit to use your own UI with useRunCommand.
  */
-declare function ModelNexChatBubble({ placeholder, defaultCommand, className, onCommand, welcomeMessage, appName, recordingExperienceType, }: ModelNexChatBubbleProps): react_jsx_runtime.JSX.Element;
+declare function ModelNexChatBubble({ placeholder, defaultCommand, className, onCommand, welcomeMessage, agentName, appName, recordingExperienceType, theme, }: ModelNexChatBubbleProps): React$1.ReactPortal | null;
 
 interface ModelNexOnboardingPanelProps {
     appName?: string;
     title?: string;
 }
-declare function ModelNexOnboardingPanel({ appName, title, }: ModelNexOnboardingPanelProps): react_jsx_runtime.JSX.Element | null;
+declare function ModelNexOnboardingPanel({ appName, title, }: ModelNexOnboardingPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Toggle and read the action-highlight overlay state.
@@ -543,10 +569,14 @@ declare global {
     }
 }
 interface VoiceHook {
-    /** Speak text via Deepgram TTS (proxied through server). Uses WebRTC loopback for AEC when available. */
+    /** Speak text via Deepgram TTS (proxied through server). Uses WebRTC loopback for AEC when available.
+     * The returned promise always settles when the scheduled playback settles; callers can choose whether to await it.
+     */
     speak: (text: string, voiceId?: string, options?: {
         onNearEnd?: () => void;
         prefetchLeadMs?: number;
+        waitForCompletion?: boolean;
+        interrupt?: boolean;
     }) => Promise<void>;
     /** Stop any in-progress TTS playback immediately */
     stopSpeaking: () => void;
@@ -556,6 +586,8 @@ interface VoiceHook {
     startListening: (onResult: (transcript: string) => void, onInterruption?: (transcript: string) => void, onError?: (err: string) => void, options?: {
         continuous?: boolean;
         lang?: string;
+        onSpeechStarted?: () => void;
+        onInterimResult?: (transcript: string) => void;
     }) => void;
     /** Stop STT listening */
     stopListening: () => void;
@@ -569,6 +601,10 @@ interface VoiceHook {
 }
 declare function useVoice(serverUrl: string): VoiceHook;
 
+interface StartTourOptions {
+    reviewMode?: boolean;
+    reviewMetadata?: Record<string, unknown>;
+}
 interface TourPlaybackHook {
     /** Whether a tour is currently running */
     isActive: boolean;
@@ -590,8 +626,10 @@ interface TourPlaybackHook {
     reviewStatusMessage: string | null;
     /** Prompted tour awaiting user confirmation */
     pendingTour: Tour | null;
+    /** Latest server-authored state snapshot for this experience */
+    serverState: TourServerState | null;
     /** Start a specific tour manually */
-    startTour: (tour: Tour) => void;
+    startTour: (tour: Tour, options?: StartTourOptions) => void;
     /** Accept the currently pending prompt and start playback */
     acceptPendingTour: () => void;
     /** Dismiss the currently pending prompt */
@@ -600,6 +638,10 @@ interface TourPlaybackHook {
     advanceStep: () => void;
     /** Skip the entire tour */
     skipTour: () => void;
+    /** Explicitly pause the tour agent (for feedback/review) */
+    pauseTour: () => void;
+    /** Resume the tour agent after a pause */
+    resumeTour: () => void;
     /** Repeat current step narration */
     repeatStep: () => void;
     /** Handle a voice input during the tour */
@@ -609,6 +651,23 @@ interface TourPlaybackHook {
     /** Save a correction against the current preview step */
     submitReviewFeedback: (utterance: string, apply?: boolean) => Promise<void>;
 }
+interface TourServerState {
+    runId: number | null;
+    turnId: string | null;
+    stepIndex: number;
+    phase: string;
+    isActive: boolean;
+    isPaused: boolean;
+    awaitingUserInput: boolean;
+    pendingCommandId: string | null;
+    pendingCommandBatch: {
+        commandBatchId: string | null;
+        stepIndex: number | null;
+        turnId: string | null;
+    } | null;
+    currentUrl?: string | null;
+    reason?: string;
+}
 interface UseTourPlaybackOptions {
     serverUrl: string;
     /** Base URL for agent commands (e.g. /api/modelnex for same-origin). Default: serverUrl */
@@ -634,8 +693,12 @@ interface UseTourPlaybackOptions {
     disabled?: boolean;
     /** Shared runtime, but allow a distinct product surface such as onboarding */
     experienceType?: ExperienceType;
+    /** Whether to show global floating captions (usually true when bubble is minimized, false when expanded) */
+    showCaptions?: boolean;
+    /** Disable internal pending prompt/query discovery when a higher-level controller owns it */
+    enableAutoDiscovery?: boolean;
 }
-declare function useTourPlayback({ serverUrl, commandUrl, toursApiBase, socketId, websiteId, userProfile, tourFacts, voice, appName, extractedElements, tagStore, onStepChange, onTourEnd, disabled, experienceType, }: UseTourPlaybackOptions): TourPlaybackHook;
+declare function useTourPlayback({ serverUrl, commandUrl, toursApiBase, socketId, websiteId, userProfile, tourFacts, voice, appName, extractedElements, tagStore, onStepChange, onTourEnd, disabled, experienceType, showCaptions, enableAutoDiscovery, }: UseTourPlaybackOptions): TourPlaybackHook;
 
 type ExperiencePlaybackHook = TourPlaybackHook;
 declare function useExperiencePlayback(...args: Parameters<typeof useTourPlayback>): TourPlaybackHook;
@@ -680,6 +743,7 @@ interface RecordingModeHook {
     continueRecording: () => void;
     undoLastStep: () => void;
     previewSteps: () => void;
+    prepareToStopRecording: () => void;
     stopRecording: (tourName: string, targetUserTypes: string[]) => Promise<string | null>;
     toggleVoiceCapture: () => void;
     /** Abandon recording — discard all steps and exit recording mode */
@@ -694,6 +758,27 @@ interface UseRecordingModeOptions {
     onPreview?: (steps: RecordingStep[]) => void;
     experienceType?: ExperienceType;
 }
+declare function buildRecordingCapturePayload({ experienceType, steps, captureEvents, capturedTranscript, }: {
+    experienceType?: ExperienceType;
+    steps?: RecordingStep[];
+    captureEvents?: TourCaptureEvent[];
+    capturedTranscript?: string;
+}): {
+    generation: {
+        mode: "capture_v1";
+        generatedAt: string;
+        eventCount: number;
+        noteCount: number;
+        generatedStepCount: number;
+    };
+    instructions?: {
+        noteEvents?: TourCaptureEvent[] | undefined;
+        transcript?: string | undefined;
+    } | undefined;
+    experienceType: ExperienceType;
+    events: TourCaptureEvent[];
+    notes: RecordingStep[];
+};
 declare function useRecordingMode({ serverUrl, toursApiBase, websiteId, voice, onPreview, experienceType, }: UseRecordingModeOptions): RecordingModeHook;
 
 interface TourProgressPanelProps {
@@ -734,11 +819,41 @@ interface RecordingOverlayProps {
 }
 declare function RecordingOverlay({ stepIndex, stepCount, captureEventCount, capturedTranscript, isVoiceCaptureActive, phase, pendingNarration, polishedNarration, isListening, onMarkStep, onToggleVoiceCapture, onElementSelected, onPageLevelStep, onStepTypeConfirmed, onStartNarration, onSubmitTextNarration, onNarrationApprove, onNarrationRedo, onNarrationEdit, onAddNextStep, onDoneRecording, onCancel, onCancelRecording, onStopRecording, }: RecordingOverlayProps): react_jsx_runtime.JSX.Element;
 
+declare function isAskDrivenInputStepType(stepType?: string | null): boolean;
+declare function isInteractiveInputStepType(stepType?: string | null): boolean;
+declare function isManualOnboardingStep(step?: Pick<TourStep, 'type' | 'onboarding'> | null): boolean;
+declare function buildRecordingStepGoal(stepType: TourStepType, selectedElement: {
+    label?: string;
+    textContaining?: string;
+} | null, recordedClicks?: Array<{
+    label?: string;
+}>): string | undefined;
+declare function inferOnboardingMetadataForStep(step: Pick<TourStep, 'type' | 'element' | 'goal' | 'ask'>): OnboardingStepMetadata | undefined;
+
+declare function shouldShowRecordingOverlay(phase: RecordingPhase): boolean;
+declare function isRecordingDraftGenerating(phase: RecordingPhase): boolean;
+declare function getRecordingDraftActionLabel(phase: RecordingPhase): string;
+declare function getRecordingDraftStatusMessage(phase: RecordingPhase, experienceType: ExperienceType): string;
+
+interface SavedDraftPreview {
+    id: string;
+    experienceType: ExperienceType;
+}
+type PreviewLaunchSource = 'standard' | 'query_param';
+declare function getPreviewQueryParamName(experienceType: ExperienceType): 'modelnex_test_tour' | 'modelnex_test_onboarding';
+declare function buildDraftPreviewUrl(currentUrl: string, draft: SavedDraftPreview): string;
+declare function shouldPromptForPreviewStart(notificationType: TourNotificationType | undefined, _source: PreviewLaunchSource): boolean;
+declare function persistActiveDraftPreview(draft: SavedDraftPreview): void;
+declare function readActiveDraftPreview(): SavedDraftPreview | null;
+declare function clearActiveDraftPreview(experienceType?: ExperienceType): void;
+
 interface ModelNexProviderProps {
-    children: React$1.ReactNode;
+    children?: unknown;
     serverUrl?: string;
     /** Base URL for agent commands. Use same-origin path (e.g. /api/modelnex) to avoid CORS. Default: serverUrl */
     commandUrl?: string;
+    /** Disable the realtime socket connection while still rendering the SDK UI */
+    disableSocket?: boolean;
     /** Identifier for the integrated website, for multi-tenancy */
     websiteId?: string;
     /**
@@ -762,4 +877,4 @@ interface ModelNexProviderProps {
 }
 declare const ModelNexProvider: React$1.FC<ModelNexProviderProps>;
 
-export { type AgentDebug, type AgentTraceLlmInput, type AgentTraceStep, type ChatMessage, type ExperienceGoal, type ExperiencePlaybackHook, type ExperiencePresentation, type ExperienceType, type ExtractedElement, ModelNexChatBubble, type ModelNexChatBubbleProps, ModelNexOnboardingPanel, type ModelNexOnboardingPanelProps, ModelNexProvider, type ModelNexProviderProps, type OnboardingPlaybackHook, type OnboardingStepMetadata, type RecordingModeHook, RecordingOverlay, type RunCommandResult, StudioOverlay, type TagData, type TagStore, type Tour, type TourFacts, type TourNotificationType, type TourPlaybackHook, type TourPlaybackState, TourProgressPanel, type TourStartPolicy, type TourStep, type TourStepType, type TourTrigger, UIStateProvider, type UseRegisterActionOptions, type UserProfile, type VoiceHook, extractInteractiveElements, generateFingerprint, useActionHighlight, useAgentViewport, useAutoExtract, useExperiencePlayback, useOnboardingPlayback, useRecordingMode, useRegisterAction, useRunCommand, useTagStore, useTourPlayback, useUIState, useViewportTrack, useVisibleIds, useVoice };
+export { type AgentDebug, type AgentTraceLlmInput, type AgentTraceStep, type ChatMessage, type ExperienceGoal, type ExperiencePlaybackHook, type ExperiencePresentation, type ExperienceType, type ExtractedElement, ModelNexChatBubble, type ModelNexChatBubbleProps, ModelNexOnboardingPanel, type ModelNexOnboardingPanelProps, ModelNexProvider, type ModelNexProviderProps, type OnboardingPlaybackHook, type OnboardingStepMetadata, type PreviewLaunchSource, type RecordingModeHook, RecordingOverlay, type RunCommandResult, type SavedDraftPreview, StudioOverlay, type TagData, type TagStore, type Tour, type TourFacts, type TourNotificationType, type TourPlaybackHook, type TourPlaybackState, TourProgressPanel, type TourStartPolicy, type TourStep, type TourStepType, type TourTrigger, UIStateProvider, type UseRegisterActionOptions, type UserProfile, type VoiceHook, buildDraftPreviewUrl, buildRecordingCapturePayload, buildRecordingStepGoal, clearActiveDraftPreview, extractInteractiveElements, generateFingerprint, getPreviewQueryParamName, getRecordingDraftActionLabel, getRecordingDraftStatusMessage, inferOnboardingMetadataForStep, isAskDrivenInputStepType, isInteractiveInputStepType, isManualOnboardingStep, isRecordingDraftGenerating, persistActiveDraftPreview, readActiveDraftPreview, shouldPromptForPreviewStart, shouldShowRecordingOverlay, useActionHighlight, useAgentViewport, useAutoExtract, useExperiencePlayback, useOnboardingPlayback, useRecordingMode, useRegisterAction, useRunCommand, useTagStore, useTourPlayback, useUIState, useViewportTrack, useVisibleIds, useVoice };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type ExperienceType = 'tour' | 'onboarding';
-type TourStepType = 'narrate' | 'act' | 'ask_and_fill' | 'user_input' | 'ask_or_fill';
+type TourStepType = 'narrate' | 'act' | 'input' | 'ask_and_fill' | 'user_input' | 'ask_or_fill' | 'wait_then_act';
 type TourUserActionEvent = 'click' | 'input' | 'change' | 'blur';
 interface TourActionTarget {
     uid?: string;
@@ -58,7 +58,7 @@ interface TourRecordedClick {
     /** Visible text or placeholder captured at record time */
     textContaining: string;
 }
-type TourCaptureEventType = 'session_start' | 'route' | 'click' | 'input' | 'note';
+type TourCaptureEventType = 'session_start' | 'route' | 'hover' | 'click' | 'input' | 'note';
 interface TourCaptureEvent {
     id: string;
     type: TourCaptureEventType;
@@ -134,7 +134,7 @@ interface TourStep {
     /** Optional onboarding-specific step metadata */
     onboarding?: OnboardingStepMetadata;
 }
-type TourTrigger = 'first_visit' | 'feature_unlocked' | 'feature_unlock' | 'idle_on_empty_state' | 'return_visit' | 'new_feature' | 'manual';
+type TourTrigger = 'first_visit' | 'feature_launch' | 'feature_unlocked' | 'feature_unlock' | 'new_feature' | 'manual';
 type TourStartPolicy = 'immediate_start' | 'prompt_only' | 'manual_only';
 type TourNotificationType = 'bubble_card' | 'modal';
 interface TourVoiceConfig {
@@ -142,13 +142,21 @@ interface TourVoiceConfig {
     ttsVoice?: string;
     ttsPrefetchLeadMs?: number;
 }
+interface ExperienceModalConfig {
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    cancelButtonText?: string;
+    backgroundColor?: string;
+    textColor?: string;
+}
 interface ExperiencePresentation {
-    launcher?: 'tour_bubble' | 'onboarding_bubble' | 'checklist' | 'none';
     theme?: {
         tone?: 'guide' | 'coach' | 'operator';
         accentColor?: string;
         icon?: string;
     };
+    modalConfig?: ExperienceModalConfig;
 }
 interface ExperienceGoal {
     primaryAction?: string;
@@ -171,6 +179,11 @@ interface Tour {
     goal?: ExperienceGoal;
     capture?: {
         experienceType?: ExperienceType;
+        instructions?: {
+            transcript?: string;
+            noteEvents?: TourCaptureEvent[];
+        };
+        notes?: RecordingStep[];
         onboardingHints?: {
             inferredWaitTargets?: number;
             inferredCompletionSignals?: number;
@@ -196,7 +209,7 @@ interface TourFacts {
     features?: string[];
 }
 /** Playback state machine states */
-type TourPlaybackState = 'idle' | 'intro' | 'executing' | 'thinking' | 'waiting_voice' | 'waiting_input' | 'complete';
+type TourPlaybackState = 'idle' | 'intro' | 'executing' | 'thinking' | 'waiting_voice' | 'waiting_input' | 'paused' | 'complete';
 /** Internal recording step being built */
 interface RecordingStep {
     order: number;
@@ -468,23 +481,36 @@ interface ModelNexChatBubbleProps {
     }>;
     /** Welcome message when chat is empty */
     welcomeMessage?: string;
+    /** Name of the AI agent displayed in the header */
+    agentName?: string;
     /** Display name of the app — used in tour intro narration */
     appName?: string;
     /** Save recorded flows as tours or onboarding without changing the recorder UX */
     recordingExperienceType?: ExperienceType;
+    /** Custom theme overrides */
+    theme?: {
+        accentColor?: string;
+        accentForeground?: string;
+        panelWidth?: string;
+        panelMaxHeight?: string;
+        bubbleSize?: string;
+        bubbleIconSize?: string;
+        borderRadius?: string;
+        zIndex?: number;
+    };
 }
 /**
  * Chat interface for natural language commands.
  * Shows conversation history; on exit, the agent summarizes what it did and suggests next steps.
  * Use within ModelNexProvider. Omit to use your own UI with useRunCommand.
  */
-declare function ModelNexChatBubble({ placeholder, defaultCommand, className, onCommand, welcomeMessage, appName, recordingExperienceType, }: ModelNexChatBubbleProps): react_jsx_runtime.JSX.Element;
+declare function ModelNexChatBubble({ placeholder, defaultCommand, className, onCommand, welcomeMessage, agentName, appName, recordingExperienceType, theme, }: ModelNexChatBubbleProps): React$1.ReactPortal | null;
 
 interface ModelNexOnboardingPanelProps {
     appName?: string;
     title?: string;
 }
-declare function ModelNexOnboardingPanel({ appName, title, }: ModelNexOnboardingPanelProps): react_jsx_runtime.JSX.Element | null;
+declare function ModelNexOnboardingPanel({ appName, title, }: ModelNexOnboardingPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Toggle and read the action-highlight overlay state.
@@ -543,10 +569,14 @@ declare global {
     }
 }
 interface VoiceHook {
-    /** Speak text via Deepgram TTS (proxied through server). Uses WebRTC loopback for AEC when available. */
+    /** Speak text via Deepgram TTS (proxied through server). Uses WebRTC loopback for AEC when available.
+     * The returned promise always settles when the scheduled playback settles; callers can choose whether to await it.
+     */
     speak: (text: string, voiceId?: string, options?: {
         onNearEnd?: () => void;
         prefetchLeadMs?: number;
+        waitForCompletion?: boolean;
+        interrupt?: boolean;
     }) => Promise<void>;
     /** Stop any in-progress TTS playback immediately */
     stopSpeaking: () => void;
@@ -556,6 +586,8 @@ interface VoiceHook {
     startListening: (onResult: (transcript: string) => void, onInterruption?: (transcript: string) => void, onError?: (err: string) => void, options?: {
         continuous?: boolean;
         lang?: string;
+        onSpeechStarted?: () => void;
+        onInterimResult?: (transcript: string) => void;
     }) => void;
     /** Stop STT listening */
     stopListening: () => void;
@@ -569,6 +601,10 @@ interface VoiceHook {
 }
 declare function useVoice(serverUrl: string): VoiceHook;
 
+interface StartTourOptions {
+    reviewMode?: boolean;
+    reviewMetadata?: Record<string, unknown>;
+}
 interface TourPlaybackHook {
     /** Whether a tour is currently running */
     isActive: boolean;
@@ -590,8 +626,10 @@ interface TourPlaybackHook {
     reviewStatusMessage: string | null;
     /** Prompted tour awaiting user confirmation */
     pendingTour: Tour | null;
+    /** Latest server-authored state snapshot for this experience */
+    serverState: TourServerState | null;
     /** Start a specific tour manually */
-    startTour: (tour: Tour) => void;
+    startTour: (tour: Tour, options?: StartTourOptions) => void;
     /** Accept the currently pending prompt and start playback */
     acceptPendingTour: () => void;
     /** Dismiss the currently pending prompt */
@@ -600,6 +638,10 @@ interface TourPlaybackHook {
     advanceStep: () => void;
     /** Skip the entire tour */
     skipTour: () => void;
+    /** Explicitly pause the tour agent (for feedback/review) */
+    pauseTour: () => void;
+    /** Resume the tour agent after a pause */
+    resumeTour: () => void;
     /** Repeat current step narration */
     repeatStep: () => void;
     /** Handle a voice input during the tour */
@@ -609,6 +651,23 @@ interface TourPlaybackHook {
     /** Save a correction against the current preview step */
     submitReviewFeedback: (utterance: string, apply?: boolean) => Promise<void>;
 }
+interface TourServerState {
+    runId: number | null;
+    turnId: string | null;
+    stepIndex: number;
+    phase: string;
+    isActive: boolean;
+    isPaused: boolean;
+    awaitingUserInput: boolean;
+    pendingCommandId: string | null;
+    pendingCommandBatch: {
+        commandBatchId: string | null;
+        stepIndex: number | null;
+        turnId: string | null;
+    } | null;
+    currentUrl?: string | null;
+    reason?: string;
+}
 interface UseTourPlaybackOptions {
     serverUrl: string;
     /** Base URL for agent commands (e.g. /api/modelnex for same-origin). Default: serverUrl */
@@ -634,8 +693,12 @@ interface UseTourPlaybackOptions {
     disabled?: boolean;
     /** Shared runtime, but allow a distinct product surface such as onboarding */
     experienceType?: ExperienceType;
+    /** Whether to show global floating captions (usually true when bubble is minimized, false when expanded) */
+    showCaptions?: boolean;
+    /** Disable internal pending prompt/query discovery when a higher-level controller owns it */
+    enableAutoDiscovery?: boolean;
 }
-declare function useTourPlayback({ serverUrl, commandUrl, toursApiBase, socketId, websiteId, userProfile, tourFacts, voice, appName, extractedElements, tagStore, onStepChange, onTourEnd, disabled, experienceType, }: UseTourPlaybackOptions): TourPlaybackHook;
+declare function useTourPlayback({ serverUrl, commandUrl, toursApiBase, socketId, websiteId, userProfile, tourFacts, voice, appName, extractedElements, tagStore, onStepChange, onTourEnd, disabled, experienceType, showCaptions, enableAutoDiscovery, }: UseTourPlaybackOptions): TourPlaybackHook;
 
 type ExperiencePlaybackHook = TourPlaybackHook;
 declare function useExperiencePlayback(...args: Parameters<typeof useTourPlayback>): TourPlaybackHook;
@@ -680,6 +743,7 @@ interface RecordingModeHook {
     continueRecording: () => void;
     undoLastStep: () => void;
     previewSteps: () => void;
+    prepareToStopRecording: () => void;
     stopRecording: (tourName: string, targetUserTypes: string[]) => Promise<string | null>;
     toggleVoiceCapture: () => void;
     /** Abandon recording — discard all steps and exit recording mode */
@@ -694,6 +758,27 @@ interface UseRecordingModeOptions {
     onPreview?: (steps: RecordingStep[]) => void;
     experienceType?: ExperienceType;
 }
+declare function buildRecordingCapturePayload({ experienceType, steps, captureEvents, capturedTranscript, }: {
+    experienceType?: ExperienceType;
+    steps?: RecordingStep[];
+    captureEvents?: TourCaptureEvent[];
+    capturedTranscript?: string;
+}): {
+    generation: {
+        mode: "capture_v1";
+        generatedAt: string;
+        eventCount: number;
+        noteCount: number;
+        generatedStepCount: number;
+    };
+    instructions?: {
+        noteEvents?: TourCaptureEvent[] | undefined;
+        transcript?: string | undefined;
+    } | undefined;
+    experienceType: ExperienceType;
+    events: TourCaptureEvent[];
+    notes: RecordingStep[];
+};
 declare function useRecordingMode({ serverUrl, toursApiBase, websiteId, voice, onPreview, experienceType, }: UseRecordingModeOptions): RecordingModeHook;
 
 interface TourProgressPanelProps {
@@ -734,11 +819,41 @@ interface RecordingOverlayProps {
 }
 declare function RecordingOverlay({ stepIndex, stepCount, captureEventCount, capturedTranscript, isVoiceCaptureActive, phase, pendingNarration, polishedNarration, isListening, onMarkStep, onToggleVoiceCapture, onElementSelected, onPageLevelStep, onStepTypeConfirmed, onStartNarration, onSubmitTextNarration, onNarrationApprove, onNarrationRedo, onNarrationEdit, onAddNextStep, onDoneRecording, onCancel, onCancelRecording, onStopRecording, }: RecordingOverlayProps): react_jsx_runtime.JSX.Element;
 
+declare function isAskDrivenInputStepType(stepType?: string | null): boolean;
+declare function isInteractiveInputStepType(stepType?: string | null): boolean;
+declare function isManualOnboardingStep(step?: Pick<TourStep, 'type' | 'onboarding'> | null): boolean;
+declare function buildRecordingStepGoal(stepType: TourStepType, selectedElement: {
+    label?: string;
+    textContaining?: string;
+} | null, recordedClicks?: Array<{
+    label?: string;
+}>): string | undefined;
+declare function inferOnboardingMetadataForStep(step: Pick<TourStep, 'type' | 'element' | 'goal' | 'ask'>): OnboardingStepMetadata | undefined;
+
+declare function shouldShowRecordingOverlay(phase: RecordingPhase): boolean;
+declare function isRecordingDraftGenerating(phase: RecordingPhase): boolean;
+declare function getRecordingDraftActionLabel(phase: RecordingPhase): string;
+declare function getRecordingDraftStatusMessage(phase: RecordingPhase, experienceType: ExperienceType): string;
+
+interface SavedDraftPreview {
+    id: string;
+    experienceType: ExperienceType;
+}
+type PreviewLaunchSource = 'standard' | 'query_param';
+declare function getPreviewQueryParamName(experienceType: ExperienceType): 'modelnex_test_tour' | 'modelnex_test_onboarding';
+declare function buildDraftPreviewUrl(currentUrl: string, draft: SavedDraftPreview): string;
+declare function shouldPromptForPreviewStart(notificationType: TourNotificationType | undefined, _source: PreviewLaunchSource): boolean;
+declare function persistActiveDraftPreview(draft: SavedDraftPreview): void;
+declare function readActiveDraftPreview(): SavedDraftPreview | null;
+declare function clearActiveDraftPreview(experienceType?: ExperienceType): void;
+
 interface ModelNexProviderProps {
-    children: React$1.ReactNode;
+    children?: unknown;
     serverUrl?: string;
     /** Base URL for agent commands. Use same-origin path (e.g. /api/modelnex) to avoid CORS. Default: serverUrl */
     commandUrl?: string;
+    /** Disable the realtime socket connection while still rendering the SDK UI */
+    disableSocket?: boolean;
     /** Identifier for the integrated website, for multi-tenancy */
     websiteId?: string;
     /**
@@ -762,4 +877,4 @@ interface ModelNexProviderProps {
 }
 declare const ModelNexProvider: React$1.FC<ModelNexProviderProps>;
 
-export { type AgentDebug, type AgentTraceLlmInput, type AgentTraceStep, type ChatMessage, type ExperienceGoal, type ExperiencePlaybackHook, type ExperiencePresentation, type ExperienceType, type ExtractedElement, ModelNexChatBubble, type ModelNexChatBubbleProps, ModelNexOnboardingPanel, type ModelNexOnboardingPanelProps, ModelNexProvider, type ModelNexProviderProps, type OnboardingPlaybackHook, type OnboardingStepMetadata, type RecordingModeHook, RecordingOverlay, type RunCommandResult, StudioOverlay, type TagData, type TagStore, type Tour, type TourFacts, type TourNotificationType, type TourPlaybackHook, type TourPlaybackState, TourProgressPanel, type TourStartPolicy, type TourStep, type TourStepType, type TourTrigger, UIStateProvider, type UseRegisterActionOptions, type UserProfile, type VoiceHook, extractInteractiveElements, generateFingerprint, useActionHighlight, useAgentViewport, useAutoExtract, useExperiencePlayback, useOnboardingPlayback, useRecordingMode, useRegisterAction, useRunCommand, useTagStore, useTourPlayback, useUIState, useViewportTrack, useVisibleIds, useVoice };
+export { type AgentDebug, type AgentTraceLlmInput, type AgentTraceStep, type ChatMessage, type ExperienceGoal, type ExperiencePlaybackHook, type ExperiencePresentation, type ExperienceType, type ExtractedElement, ModelNexChatBubble, type ModelNexChatBubbleProps, ModelNexOnboardingPanel, type ModelNexOnboardingPanelProps, ModelNexProvider, type ModelNexProviderProps, type OnboardingPlaybackHook, type OnboardingStepMetadata, type PreviewLaunchSource, type RecordingModeHook, RecordingOverlay, type RunCommandResult, type SavedDraftPreview, StudioOverlay, type TagData, type TagStore, type Tour, type TourFacts, type TourNotificationType, type TourPlaybackHook, type TourPlaybackState, TourProgressPanel, type TourStartPolicy, type TourStep, type TourStepType, type TourTrigger, UIStateProvider, type UseRegisterActionOptions, type UserProfile, type VoiceHook, buildDraftPreviewUrl, buildRecordingCapturePayload, buildRecordingStepGoal, clearActiveDraftPreview, extractInteractiveElements, generateFingerprint, getPreviewQueryParamName, getRecordingDraftActionLabel, getRecordingDraftStatusMessage, inferOnboardingMetadataForStep, isAskDrivenInputStepType, isInteractiveInputStepType, isManualOnboardingStep, isRecordingDraftGenerating, persistActiveDraftPreview, readActiveDraftPreview, shouldPromptForPreviewStart, shouldShowRecordingOverlay, useActionHighlight, useAgentViewport, useAutoExtract, useExperiencePlayback, useOnboardingPlayback, useRecordingMode, useRegisterAction, useRunCommand, useTagStore, useTourPlayback, useUIState, useViewportTrack, useVisibleIds, useVoice };