@modelnex/sdk 0.5.24 → 0.5.26

package/README.md

@@ -27,6 +27,7 @@ import { ModelNexProvider, ModelNexChatBubble } from '@modelnex/sdk';
 export default function AppShell() {
   return (
     <ModelNexProvider
+      serverUrl={import.meta.env.DEV ? 'http://localhost:3002' : 'https://api.modelnex.com'}
       websiteId="your-website-id"
       userProfile={{
         type: currentUser.role,
@@ -41,7 +42,7 @@ export default function AppShell() {
 }
 ```
 
-`websiteId` identifies the integration. `userProfile` is used for tour/workflow targeting and completion tracking.
+`websiteId` identifies the integration. `userProfile` is used for tour/workflow targeting and completion tracking. For local development, pass `serverUrl` explicitly so the SDK does not fall back to the hosted API.
 
 ## Tour Start Model
 
@@ -82,6 +83,7 @@ Current behavior:
 
 | Prop | Purpose |
 |------|---------|
+| `serverUrl` | Backend base URL for chat, tags, tours, voice, and recording APIs |
 | `websiteId` | Tenant/integration identifier |
 | `userProfile` | End-user targeting data for tours/workflows |
 | `devMode` | Enables recording/studio tooling for your internal users |

package/dist/index.js

@@ -2461,6 +2461,7 @@ var import_react13 = require("react");
 // src/utils/draftPreview.ts
 var ACTIVE_DRAFT_PREVIEW_STORAGE_KEY = "modelnex:active-draft-preview";
 var PREVIEW_SESSION_SUPPRESSION_STORAGE_KEY = "modelnex:preview-session-suppressed";
+var SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY = "modelnex:suppressed-draft-preview";
 function getPreviewQueryParamName(experienceType) {
   return experienceType === "onboarding" ? "modelnex_test_workflow" : "modelnex_test_tour";
 }
@@ -2510,6 +2511,51 @@ function clearActiveDraftPreview(experienceType) {
   } catch {
   }
 }
+function readSavedDraftPreview(storageKey) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.sessionStorage.getItem(storageKey);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.id !== "string") return null;
+    if (parsed.experienceType !== "tour" && parsed.experienceType !== "onboarding") return null;
+    return {
+      id: parsed.id,
+      experienceType: parsed.experienceType
+    };
+  } catch {
+    return null;
+  }
+}
+function readSuppressedDraftPreview() {
+  return readSavedDraftPreview(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY);
+}
+function persistSuppressedDraftPreview(draft) {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY, JSON.stringify(draft));
+  } catch {
+  }
+}
+function clearSuppressedDraftPreview(draft) {
+  if (typeof window === "undefined") return;
+  try {
+    const suppressedDraft = readSuppressedDraftPreview();
+    if (draft && suppressedDraft) {
+      if (suppressedDraft.id !== draft.id || suppressedDraft.experienceType !== draft.experienceType) {
+        return;
+      }
+    }
+    window.sessionStorage.removeItem(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY);
+  } catch {
+  }
+}
+function isSuppressedDraftPreview(draft) {
+  const suppressedDraft = readSuppressedDraftPreview();
+  return Boolean(
+    suppressedDraft && suppressedDraft.id === draft.id && suppressedDraft.experienceType === draft.experienceType
+  );
+}
 function persistPreviewSessionSuppression() {
   if (typeof window === "undefined") return;
   try {
@@ -4090,7 +4136,13 @@ function useTourPlayback({
       });
     }
     if (reviewModeRef.current) {
-      clearActiveDraftPreview(experienceType);
+      if (tourRef.current?.id) {
+        persistSuppressedDraftPreview({
+          id: tourRef.current.id,
+          experienceType
+        });
+      }
+      clearActiveDraftPreview();
     }
     setIsActive(false);
     setActiveTour(null);
@@ -4139,7 +4191,13 @@ function useTourPlayback({
       });
     }
     if (reviewModeRef.current) {
-      clearActiveDraftPreview(experienceType);
+      if (endingTourId) {
+        persistSuppressedDraftPreview({
+          id: endingTourId,
+          experienceType
+        });
+      }
+      clearActiveDraftPreview();
     }
     onTourEnd?.();
   }, [experienceType, userProfile, serverUrl, voice, onTourEnd, websiteId, releasePlaybackOwnership]);
@@ -4175,6 +4233,10 @@ function useTourPlayback({
     setIsReviewMode(shouldReview);
     reviewModeRef.current = shouldReview;
     if (shouldReview) {
+      clearSuppressedDraftPreview({
+        id: tour.id,
+        experienceType
+      });
       try {
         const previewRun = await createPreviewRun(serverUrl, toursApiBaseRef.current, tour.id, {
           source: "sdk_test_preview",
@@ -4215,14 +4277,23 @@ function useTourPlayback({
     const persistedTourId = activeDraftPreview?.experienceType === experienceType ? activeDraftPreview.id : null;
     const tourId = queryTourId || persistedTourId;
     if (!tourId) return;
+    const draftPreview = { id: tourId, experienceType };
+    if (!queryTourId && isSuppressedDraftPreview(draftPreview)) {
+      clearActiveDraftPreview(experienceType);
+      return;
+    }
     let cancelled = false;
     (async () => {
       try {
-        persistActiveDraftPreview({ id: tourId, experienceType });
+        if (queryTourId) {
+          clearSuppressedDraftPreview(draftPreview);
+        }
+        persistActiveDraftPreview(draftPreview);
         const tour = await fetchTourById(serverUrl, toursApiBase, tourId, experienceType, websiteId);
         if (cancelled) return;
         if (!tour) {
           clearActiveDraftPreview(experienceType);
+          persistSuppressedDraftPreview(draftPreview);
           console.warn("[ModelNex] Tour fetch failed:", tourId, experienceType, "(Check ModelNex server is running and CORS allows this origin)");
           return;
         }
@@ -4476,6 +4547,12 @@ function shouldDiscoverDraftPreview({
 }) {
   return !disabled && !hasPendingPrompt && !isPlaybackActive && !isPreviewDiscoveryInFlight && !isStartingExperience;
 }
+function shouldReplayDraftPreview({
+  hasExplicitQueryParam,
+  isSuppressedPreview
+}) {
+  return hasExplicitQueryParam || !isSuppressedPreview;
+}
 function shouldDiscoverEligibleTours({
   disabled,
   hasPendingPrompt,
@@ -4563,6 +4640,10 @@ function useExperiencePlaybackController({
     pendingPromptRef.current = null;
     if (shouldClearDraftPreviewOnPromptDismiss(prompt)) {
       clearActiveDraftPreview(prompt.experienceType);
+      persistSuppressedDraftPreview({
+        id: prompt.tour.id,
+        experienceType: prompt.experienceType
+      });
     }
     if (!userProfile?.userId) return;
     void markTourDismissed(
@@ -4643,17 +4724,32 @@ function useExperiencePlaybackController({
     }
     const request = previewRequests[0];
     if (!request) return;
+    const draftPreview = {
+      id: request.tourId,
+      experienceType: request.experienceType
+    };
+    if (!shouldReplayDraftPreview({
+      hasExplicitQueryParam: Boolean(request.queryParam),
+      isSuppressedPreview: isSuppressedDraftPreview(draftPreview)
+    })) {
+      clearActiveDraftPreview(request.experienceType);
+      return;
+    }
     let cancelled = false;
     previewDiscoveryInFlightRef.current = true;
     previewSessionRef.current = true;
     persistPreviewSessionSuppression();
     (async () => {
       try {
-        persistActiveDraftPreview({ id: request.tourId, experienceType: request.experienceType });
+        if (request.queryParam) {
+          clearSuppressedDraftPreview(draftPreview);
+        }
+        persistActiveDraftPreview(draftPreview);
         const tour = await fetchTourById(serverUrl, toursApiBase, request.tourId, request.experienceType, websiteId);
         if (cancelled) return;
         if (!tour) {
           clearActiveDraftPreview(request.experienceType);
+          persistSuppressedDraftPreview(draftPreview);
           return;
         }
         if (request.queryParam) {
@@ -8023,7 +8119,7 @@ function getRecordingDraftStatusMessage(phase, experienceType) {
 
 // src/utils/tour-listening.ts
 function canStartTourListening(state) {
-  const hasLiveOrPendingPlayback = state.isTourActive || state.isOnboardingActive || state.hasPendingTour || state.hasPendingOnboarding;
+  const hasLiveOrPendingPlayback = state.isTourActive || state.isOnboardingActive || state.hasPendingTour || state.hasPendingOnboarding || Boolean(state.startingExperienceType);
   return hasLiveOrPendingPlayback && !state.sttActive && state.sttSupported;
 }
 function resolveTourListeningExperience(preferredExperience, state) {
@@ -8937,6 +9033,7 @@ function ModelNexChatBubble({
       isOnboardingActive: onboardingPlayback.isActive,
       hasPendingTour: Boolean(tourPlayback.pendingTour),
       hasPendingOnboarding: Boolean(onboardingPlayback.pendingTour),
+      startingExperienceType,
       sttActive: sttActiveRef.current,
       sttSupported: voice.sttSupported
     };
@@ -8982,6 +9079,7 @@ function ModelNexChatBubble({
     tourPlayback.pendingTour,
     onboardingPlayback.isActive,
     onboardingPlayback.pendingTour,
+    startingExperienceType,
     voice,
     handleVoiceTourInput,
     updateTourListenReady,
@@ -11148,6 +11246,13 @@ var ModelNexProvider = ({
   const serverUrl = serverUrlProp ?? DEFAULT_MODELNEX_SERVER_URL;
   const commandUrl = void 0;
   const disableSocket = false;
+  (0, import_react21.useEffect)(() => {
+    if (process.env.NODE_ENV !== "production" && !serverUrlProp) {
+      console.warn(
+        `[ModelNex SDK] ModelNexProvider is using the default server URL (${DEFAULT_MODELNEX_SERVER_URL}). Pass \`serverUrl\` explicitly in local development to avoid accidentally targeting the hosted backend.`
+      );
+    }
+  }, [serverUrlProp]);
   const renderedChildren = children;
   const [activeAgentActions, setActiveAgentActions] = (0, import_react21.useState)(/* @__PURE__ */ new Set());
   const [stagingFields, setStagingFields] = (0, import_react21.useState)(/* @__PURE__ */ new Set());

package/dist/index.mjs

@@ -2251,6 +2251,7 @@ import { useCallback as useCallback8, useEffect as useEffect12, useRef as useRef
 // src/utils/draftPreview.ts
 var ACTIVE_DRAFT_PREVIEW_STORAGE_KEY = "modelnex:active-draft-preview";
 var PREVIEW_SESSION_SUPPRESSION_STORAGE_KEY = "modelnex:preview-session-suppressed";
+var SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY = "modelnex:suppressed-draft-preview";
 function getPreviewQueryParamName(experienceType) {
   return experienceType === "onboarding" ? "modelnex_test_workflow" : "modelnex_test_tour";
 }
@@ -2300,6 +2301,51 @@ function clearActiveDraftPreview(experienceType) {
   } catch {
   }
 }
+function readSavedDraftPreview(storageKey) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.sessionStorage.getItem(storageKey);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.id !== "string") return null;
+    if (parsed.experienceType !== "tour" && parsed.experienceType !== "onboarding") return null;
+    return {
+      id: parsed.id,
+      experienceType: parsed.experienceType
+    };
+  } catch {
+    return null;
+  }
+}
+function readSuppressedDraftPreview() {
+  return readSavedDraftPreview(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY);
+}
+function persistSuppressedDraftPreview(draft) {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY, JSON.stringify(draft));
+  } catch {
+  }
+}
+function clearSuppressedDraftPreview(draft) {
+  if (typeof window === "undefined") return;
+  try {
+    const suppressedDraft = readSuppressedDraftPreview();
+    if (draft && suppressedDraft) {
+      if (suppressedDraft.id !== draft.id || suppressedDraft.experienceType !== draft.experienceType) {
+        return;
+      }
+    }
+    window.sessionStorage.removeItem(SUPPRESSED_DRAFT_PREVIEW_STORAGE_KEY);
+  } catch {
+  }
+}
+function isSuppressedDraftPreview(draft) {
+  const suppressedDraft = readSuppressedDraftPreview();
+  return Boolean(
+    suppressedDraft && suppressedDraft.id === draft.id && suppressedDraft.experienceType === draft.experienceType
+  );
+}
 function persistPreviewSessionSuppression() {
   if (typeof window === "undefined") return;
   try {
@@ -3880,7 +3926,13 @@ function useTourPlayback({
       });
     }
     if (reviewModeRef.current) {
-      clearActiveDraftPreview(experienceType);
+      if (tourRef.current?.id) {
+        persistSuppressedDraftPreview({
+          id: tourRef.current.id,
+          experienceType
+        });
+      }
+      clearActiveDraftPreview();
     }
     setIsActive(false);
     setActiveTour(null);
@@ -3929,7 +3981,13 @@ function useTourPlayback({
       });
     }
     if (reviewModeRef.current) {
-      clearActiveDraftPreview(experienceType);
+      if (endingTourId) {
+        persistSuppressedDraftPreview({
+          id: endingTourId,
+          experienceType
+        });
+      }
+      clearActiveDraftPreview();
     }
     onTourEnd?.();
   }, [experienceType, userProfile, serverUrl, voice, onTourEnd, websiteId, releasePlaybackOwnership]);
@@ -3965,6 +4023,10 @@ function useTourPlayback({
     setIsReviewMode(shouldReview);
     reviewModeRef.current = shouldReview;
     if (shouldReview) {
+      clearSuppressedDraftPreview({
+        id: tour.id,
+        experienceType
+      });
       try {
         const previewRun = await createPreviewRun(serverUrl, toursApiBaseRef.current, tour.id, {
           source: "sdk_test_preview",
@@ -4005,14 +4067,23 @@ function useTourPlayback({
     const persistedTourId = activeDraftPreview?.experienceType === experienceType ? activeDraftPreview.id : null;
     const tourId = queryTourId || persistedTourId;
     if (!tourId) return;
+    const draftPreview = { id: tourId, experienceType };
+    if (!queryTourId && isSuppressedDraftPreview(draftPreview)) {
+      clearActiveDraftPreview(experienceType);
+      return;
+    }
     let cancelled = false;
     (async () => {
       try {
-        persistActiveDraftPreview({ id: tourId, experienceType });
+        if (queryTourId) {
+          clearSuppressedDraftPreview(draftPreview);
+        }
+        persistActiveDraftPreview(draftPreview);
         const tour = await fetchTourById(serverUrl, toursApiBase, tourId, experienceType, websiteId);
         if (cancelled) return;
         if (!tour) {
           clearActiveDraftPreview(experienceType);
+          persistSuppressedDraftPreview(draftPreview);
           console.warn("[ModelNex] Tour fetch failed:", tourId, experienceType, "(Check ModelNex server is running and CORS allows this origin)");
           return;
         }
@@ -4266,6 +4337,12 @@ function shouldDiscoverDraftPreview({
 }) {
   return !disabled && !hasPendingPrompt && !isPlaybackActive && !isPreviewDiscoveryInFlight && !isStartingExperience;
 }
+function shouldReplayDraftPreview({
+  hasExplicitQueryParam,
+  isSuppressedPreview
+}) {
+  return hasExplicitQueryParam || !isSuppressedPreview;
+}
 function shouldDiscoverEligibleTours({
   disabled,
   hasPendingPrompt,
@@ -4353,6 +4430,10 @@ function useExperiencePlaybackController({
     pendingPromptRef.current = null;
     if (shouldClearDraftPreviewOnPromptDismiss(prompt)) {
       clearActiveDraftPreview(prompt.experienceType);
+      persistSuppressedDraftPreview({
+        id: prompt.tour.id,
+        experienceType: prompt.experienceType
+      });
     }
     if (!userProfile?.userId) return;
     void markTourDismissed(
@@ -4433,17 +4514,32 @@ function useExperiencePlaybackController({
     }
     const request = previewRequests[0];
     if (!request) return;
+    const draftPreview = {
+      id: request.tourId,
+      experienceType: request.experienceType
+    };
+    if (!shouldReplayDraftPreview({
+      hasExplicitQueryParam: Boolean(request.queryParam),
+      isSuppressedPreview: isSuppressedDraftPreview(draftPreview)
+    })) {
+      clearActiveDraftPreview(request.experienceType);
+      return;
+    }
     let cancelled = false;
     previewDiscoveryInFlightRef.current = true;
     previewSessionRef.current = true;
     persistPreviewSessionSuppression();
     (async () => {
       try {
-        persistActiveDraftPreview({ id: request.tourId, experienceType: request.experienceType });
+        if (request.queryParam) {
+          clearSuppressedDraftPreview(draftPreview);
+        }
+        persistActiveDraftPreview(draftPreview);
         const tour = await fetchTourById(serverUrl, toursApiBase, request.tourId, request.experienceType, websiteId);
         if (cancelled) return;
         if (!tour) {
           clearActiveDraftPreview(request.experienceType);
+          persistSuppressedDraftPreview(draftPreview);
           return;
         }
         if (request.queryParam) {
@@ -7812,7 +7908,7 @@ function getRecordingDraftStatusMessage(phase, experienceType) {
 
 // src/utils/tour-listening.ts
 function canStartTourListening(state) {
-  const hasLiveOrPendingPlayback = state.isTourActive || state.isOnboardingActive || state.hasPendingTour || state.hasPendingOnboarding;
+  const hasLiveOrPendingPlayback = state.isTourActive || state.isOnboardingActive || state.hasPendingTour || state.hasPendingOnboarding || Boolean(state.startingExperienceType);
   return hasLiveOrPendingPlayback && !state.sttActive && state.sttSupported;
 }
 function resolveTourListeningExperience(preferredExperience, state) {
@@ -8726,6 +8822,7 @@ function ModelNexChatBubble({
       isOnboardingActive: onboardingPlayback.isActive,
       hasPendingTour: Boolean(tourPlayback.pendingTour),
       hasPendingOnboarding: Boolean(onboardingPlayback.pendingTour),
+      startingExperienceType,
       sttActive: sttActiveRef.current,
       sttSupported: voice.sttSupported
     };
@@ -8771,6 +8868,7 @@ function ModelNexChatBubble({
     tourPlayback.pendingTour,
     onboardingPlayback.isActive,
     onboardingPlayback.pendingTour,
+    startingExperienceType,
     voice,
     handleVoiceTourInput,
     updateTourListenReady,
@@ -10937,6 +11035,13 @@ var ModelNexProvider = ({
   const serverUrl = serverUrlProp ?? DEFAULT_MODELNEX_SERVER_URL;
   const commandUrl = void 0;
   const disableSocket = false;
+  useEffect19(() => {
+    if (process.env.NODE_ENV !== "production" && !serverUrlProp) {
+      console.warn(
+        `[ModelNex SDK] ModelNexProvider is using the default server URL (${DEFAULT_MODELNEX_SERVER_URL}). Pass \`serverUrl\` explicitly in local development to avoid accidentally targeting the hosted backend.`
+      );
+    }
+  }, [serverUrlProp]);
   const renderedChildren = children;
   const [activeAgentActions, setActiveAgentActions] = useState15(/* @__PURE__ */ new Set());
   const [stagingFields, setStagingFields] = useState15(/* @__PURE__ */ new Set());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelnex/sdk",
-  "version": "0.5.24",
+  "version": "0.5.26",
   "description": "React SDK for natural language control of web apps via AI agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",