@modelnex/sdk 0.5.17 → 0.5.18

package/dist/index.js

@@ -2718,6 +2718,31 @@ function createTourSocketPool({
 }
 var tourSocketPool = createTourSocketPool();
 
+// src/utils/tour-playback-guards.ts
+function shouldExecuteTourCommandBatch(isPlaybackActive) {
+  return isPlaybackActive;
+}
+function shouldAcceptTourStart(state) {
+  return !state.isPlaybackActive && !state.startRequested;
+}
+function shouldRunTourAutoDiscovery(state) {
+  return state.enableAutoDiscovery && !state.disabled && !state.isPlaybackActive && !state.startRequested && !state.hasPendingTour;
+}
+function shouldLogTourDebugEntry(state) {
+  if (!state.isPlaybackActive) {
+    if (state.entryType !== "tour_start") {
+      return false;
+    }
+    if (state.entryTourType && state.entryTourType !== state.experienceType) {
+      return false;
+    }
+  }
+  if (state.entryTourType && state.entryTourType !== state.experienceType) {
+    return false;
+  }
+  return true;
+}
+
 // src/hooks/useTourPlayback.ts
 function resolveElement(step) {
   const el = step.element;
@@ -3251,6 +3276,7 @@ function useTourPlayback({
   const showCaptionsRef = (0, import_react12.useRef)(showCaptions);
   const runIdRef = (0, import_react12.useRef)(null);
   const turnIdRef = (0, import_react12.useRef)(null);
+  const startRequestedRef = (0, import_react12.useRef)(false);
   const socketRef = (0, import_react12.useRef)(null);
   const socketIdRef = (0, import_react12.useRef)(socketId);
   const commandUrlRef = (0, import_react12.useRef)(commandUrl);
@@ -3303,6 +3329,11 @@ function useTourPlayback({
       }
     };
     const handleCommand = async (payload) => {
+      if (!shouldExecuteTourCommandBatch(isActiveRef.current)) {
+        const activeType = experienceTypeRef.current;
+        console.log("[TourClient] Ignoring command batch for inactive playback hook:", activeType, payload.stepIndex);
+        return;
+      }
       const emitIfOpen = (ev, data) => {
         if (socketRef.current !== socket) return;
         emitSocketEvent(socket, ev, data);
@@ -3809,6 +3840,7 @@ function useTourPlayback({
         return;
       }
       skipRequestedRef.current = false;
+      startRequestedRef.current = false;
       const total = tourData.totalSteps ?? tour?.steps?.length ?? 0;
       isActiveRef.current = true;
       setIsActive(true);
@@ -3867,6 +3899,15 @@ function useTourPlayback({
     };
     const handleDebugLog = (entry) => {
       const isDev = devModeRef.current || process.env.NODE_ENV === "development" || typeof window !== "undefined" && window.MODELNEX_DEBUG;
+      const entryTourType = entry?.data?.tourContext?.type ?? tourRef.current?.type ?? null;
+      if (!shouldLogTourDebugEntry({
+        isPlaybackActive: isActiveRef.current,
+        entryType: entry?.type,
+        entryTourType,
+        experienceType: experienceTypeRef.current
+      })) {
+        return;
+      }
       if (isDev) {
         console.log(`%c[ModelNex Tour] ${entry.type}`, "color: #3b82f6; font-weight: bold", entry);
         if (typeof window !== "undefined") {
@@ -3972,6 +4013,7 @@ function useTourPlayback({
   const stopTour = (0, import_react12.useCallback)(() => {
     skipRequestedRef.current = true;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     activeExecutionTokenRef.current += 1;
     commandInFlightRef.current = false;
     activeCommandBatchIdRef.current = null;
@@ -4013,6 +4055,7 @@ function useTourPlayback({
     const endingPreviewRunId = previewRunIdRef.current;
     const endingStepOrder = stepIndexRef.current;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     setPlaybackState("complete");
     removeHighlight();
     removeCaption();
@@ -4046,6 +4089,13 @@ function useTourPlayback({
     onTourEnd?.();
   }, [experienceType, userProfile, serverUrl, voice, onTourEnd, websiteId]);
   const runTour = (0, import_react12.useCallback)(async (tour, options) => {
+    if (!shouldAcceptTourStart({
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current
+    })) {
+      console.log("[TourClient] Ignoring duplicate start request while playback is already active or starting:", tour.id);
+      return;
+    }
     setPendingTour(null);
     pendingTourRef.current = null;
     let retries = 0;
@@ -4057,6 +4107,7 @@ function useTourPlayback({
       console.warn("[TourClient] Cannot run tour, socket not connected.");
       return;
     }
+    startRequestedRef.current = true;
     const shouldReview = Boolean(options?.reviewMode);
     resetCaptionSuppression();
     setReviewStatusMessage(null);
@@ -4088,8 +4139,13 @@ function useTourPlayback({
     });
   }, [serverUrl, websiteId]);
   (0, import_react12.useEffect)(() => {
-    if (!enableAutoDiscovery) return;
-    if (disabled) return;
+    if (!shouldRunTourAutoDiscovery({
+      enableAutoDiscovery,
+      disabled,
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current,
+      hasPendingTour: Boolean(pendingTourRef.current)
+    })) return;
     if (typeof window === "undefined") return;
     const params = new URLSearchParams(window.location.search);
     const queryParam = experienceType === "onboarding" ? "modelnex_test_workflow" : "modelnex_test_tour";
@@ -4137,8 +4193,13 @@ function useTourPlayback({
     };
   }, [serverUrl, toursApiBase, disabled, websiteId, experienceType, enableAutoDiscovery]);
   (0, import_react12.useEffect)(() => {
-    if (!enableAutoDiscovery) return;
-    if (disabled) return;
+    if (!shouldRunTourAutoDiscovery({
+      enableAutoDiscovery,
+      disabled,
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current,
+      hasPendingTour: Boolean(pendingTourRef.current)
+    })) return;
     if (!websiteId || !userProfile) return;
     if (typeof window !== "undefined") {
       const params = new URLSearchParams(window.location.search);
@@ -4177,7 +4238,7 @@ function useTourPlayback({
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [websiteId, serverUrl, toursApiBase, disabled, experienceType, userProfile, enableAutoDiscovery]);
+  }, [websiteId, serverUrl, toursApiBase, disabled, experienceType, userProfile?.userId, userProfile?.type, userProfile?.isNewUser, enableAutoDiscovery]);
   (0, import_react12.useEffect)(() => {
     if (!disabled || !isActiveRef.current) return;
     stopTour();

package/dist/index.mjs

@@ -2508,6 +2508,31 @@ function createTourSocketPool({
 }
 var tourSocketPool = createTourSocketPool();
 
+// src/utils/tour-playback-guards.ts
+function shouldExecuteTourCommandBatch(isPlaybackActive) {
+  return isPlaybackActive;
+}
+function shouldAcceptTourStart(state) {
+  return !state.isPlaybackActive && !state.startRequested;
+}
+function shouldRunTourAutoDiscovery(state) {
+  return state.enableAutoDiscovery && !state.disabled && !state.isPlaybackActive && !state.startRequested && !state.hasPendingTour;
+}
+function shouldLogTourDebugEntry(state) {
+  if (!state.isPlaybackActive) {
+    if (state.entryType !== "tour_start") {
+      return false;
+    }
+    if (state.entryTourType && state.entryTourType !== state.experienceType) {
+      return false;
+    }
+  }
+  if (state.entryTourType && state.entryTourType !== state.experienceType) {
+    return false;
+  }
+  return true;
+}
+
 // src/hooks/useTourPlayback.ts
 function resolveElement(step) {
   const el = step.element;
@@ -3041,6 +3066,7 @@ function useTourPlayback({
   const showCaptionsRef = useRef8(showCaptions);
   const runIdRef = useRef8(null);
   const turnIdRef = useRef8(null);
+  const startRequestedRef = useRef8(false);
   const socketRef = useRef8(null);
   const socketIdRef = useRef8(socketId);
   const commandUrlRef = useRef8(commandUrl);
@@ -3093,6 +3119,11 @@ function useTourPlayback({
       }
     };
     const handleCommand = async (payload) => {
+      if (!shouldExecuteTourCommandBatch(isActiveRef.current)) {
+        const activeType = experienceTypeRef.current;
+        console.log("[TourClient] Ignoring command batch for inactive playback hook:", activeType, payload.stepIndex);
+        return;
+      }
       const emitIfOpen = (ev, data) => {
         if (socketRef.current !== socket) return;
         emitSocketEvent(socket, ev, data);
@@ -3599,6 +3630,7 @@ function useTourPlayback({
         return;
       }
       skipRequestedRef.current = false;
+      startRequestedRef.current = false;
       const total = tourData.totalSteps ?? tour?.steps?.length ?? 0;
       isActiveRef.current = true;
       setIsActive(true);
@@ -3657,6 +3689,15 @@ function useTourPlayback({
     };
     const handleDebugLog = (entry) => {
       const isDev = devModeRef.current || process.env.NODE_ENV === "development" || typeof window !== "undefined" && window.MODELNEX_DEBUG;
+      const entryTourType = entry?.data?.tourContext?.type ?? tourRef.current?.type ?? null;
+      if (!shouldLogTourDebugEntry({
+        isPlaybackActive: isActiveRef.current,
+        entryType: entry?.type,
+        entryTourType,
+        experienceType: experienceTypeRef.current
+      })) {
+        return;
+      }
       if (isDev) {
         console.log(`%c[ModelNex Tour] ${entry.type}`, "color: #3b82f6; font-weight: bold", entry);
         if (typeof window !== "undefined") {
@@ -3762,6 +3803,7 @@ function useTourPlayback({
   const stopTour = useCallback7(() => {
     skipRequestedRef.current = true;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     activeExecutionTokenRef.current += 1;
     commandInFlightRef.current = false;
     activeCommandBatchIdRef.current = null;
@@ -3803,6 +3845,7 @@ function useTourPlayback({
     const endingPreviewRunId = previewRunIdRef.current;
     const endingStepOrder = stepIndexRef.current;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     setPlaybackState("complete");
     removeHighlight();
     removeCaption();
@@ -3836,6 +3879,13 @@ function useTourPlayback({
     onTourEnd?.();
   }, [experienceType, userProfile, serverUrl, voice, onTourEnd, websiteId]);
   const runTour = useCallback7(async (tour, options) => {
+    if (!shouldAcceptTourStart({
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current
+    })) {
+      console.log("[TourClient] Ignoring duplicate start request while playback is already active or starting:", tour.id);
+      return;
+    }
     setPendingTour(null);
     pendingTourRef.current = null;
     let retries = 0;
@@ -3847,6 +3897,7 @@ function useTourPlayback({
       console.warn("[TourClient] Cannot run tour, socket not connected.");
       return;
     }
+    startRequestedRef.current = true;
     const shouldReview = Boolean(options?.reviewMode);
     resetCaptionSuppression();
     setReviewStatusMessage(null);
@@ -3878,8 +3929,13 @@ function useTourPlayback({
     });
   }, [serverUrl, websiteId]);
   useEffect11(() => {
-    if (!enableAutoDiscovery) return;
-    if (disabled) return;
+    if (!shouldRunTourAutoDiscovery({
+      enableAutoDiscovery,
+      disabled,
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current,
+      hasPendingTour: Boolean(pendingTourRef.current)
+    })) return;
     if (typeof window === "undefined") return;
     const params = new URLSearchParams(window.location.search);
     const queryParam = experienceType === "onboarding" ? "modelnex_test_workflow" : "modelnex_test_tour";
@@ -3927,8 +3983,13 @@ function useTourPlayback({
     };
   }, [serverUrl, toursApiBase, disabled, websiteId, experienceType, enableAutoDiscovery]);
   useEffect11(() => {
-    if (!enableAutoDiscovery) return;
-    if (disabled) return;
+    if (!shouldRunTourAutoDiscovery({
+      enableAutoDiscovery,
+      disabled,
+      isPlaybackActive: isActiveRef.current,
+      startRequested: startRequestedRef.current,
+      hasPendingTour: Boolean(pendingTourRef.current)
+    })) return;
     if (!websiteId || !userProfile) return;
     if (typeof window !== "undefined") {
       const params = new URLSearchParams(window.location.search);
@@ -3967,7 +4028,7 @@ function useTourPlayback({
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [websiteId, serverUrl, toursApiBase, disabled, experienceType, userProfile, enableAutoDiscovery]);
+  }, [websiteId, serverUrl, toursApiBase, disabled, experienceType, userProfile?.userId, userProfile?.type, userProfile?.isNewUser, enableAutoDiscovery]);
   useEffect11(() => {
     if (!disabled || !isActiveRef.current) return;
     stopTour();

package/package.json

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