@modelnex/sdk 0.5.16 → 0.5.18

package/dist/index.js

@@ -2626,7 +2626,6 @@ function isTourEligible(tour, userProfile) {
 
 // src/hooks/useTourPlayback.ts
 var import_react12 = require("react");
-var import_socket2 = require("socket.io-client");
 
 // src/utils/retryLookup.ts
 var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -2649,6 +2648,101 @@ async function retryLookup({
   }
 }
 
+// src/utils/tour-socket-pool.ts
+var import_socket2 = require("socket.io-client");
+function isSocketWritable(socket) {
+  if (!socket?.connected) return false;
+  const engine = socket.io?.engine;
+  if (!engine) return true;
+  if (typeof engine.readyState === "string" && engine.readyState !== "open") return false;
+  if (engine.transport && "writable" in engine.transport && engine.transport.writable === false) return false;
+  return true;
+}
+function emitSocketEvent(socket, event, payload) {
+  if (!isSocketWritable(socket)) return false;
+  socket.emit(event, payload);
+  return true;
+}
+function createTourSocketPool({
+  createSocket = (serverUrl) => (0, import_socket2.io)(serverUrl, {
+    path: "/socket.io",
+    transports: resolveSocketIoTransports(serverUrl, "polling-first"),
+    autoConnect: true,
+    reconnection: true,
+    reconnectionAttempts: 10,
+    reconnectionDelay: 1e3
+  }),
+  releaseDelayMs = 2500,
+  scheduleRelease = (callback, delayMs) => setTimeout(callback, delayMs),
+  cancelRelease = (timer) => clearTimeout(timer)
+} = {}) {
+  const pooledSockets = /* @__PURE__ */ new Map();
+  return {
+    acquire(serverUrl) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (pooled) {
+        if (pooled.releaseTimer) {
+          cancelRelease(pooled.releaseTimer);
+          pooled.releaseTimer = null;
+        }
+        pooled.leases += 1;
+        return pooled.socket;
+      }
+      const socket = createSocket(serverUrl);
+      pooledSockets.set(serverUrl, {
+        socket,
+        leases: 1,
+        releaseTimer: null
+      });
+      return socket;
+    },
+    release(serverUrl, socket) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (!pooled || pooled.socket !== socket) return;
+      pooled.leases = Math.max(0, pooled.leases - 1);
+      if (pooled.leases > 0) return;
+      pooled.releaseTimer = scheduleRelease(() => {
+        const latest = pooledSockets.get(serverUrl);
+        if (!latest || latest !== pooled || latest.leases > 0) return;
+        latest.socket.disconnect();
+        pooledSockets.delete(serverUrl);
+      }, releaseDelayMs);
+    },
+    // Test-only introspection
+    getSnapshot(serverUrl) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (!pooled) return null;
+      return { leases: pooled.leases, socket: pooled.socket };
+    }
+  };
+}
+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;
@@ -3182,14 +3276,17 @@ 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);
+  const websiteIdRef = (0, import_react12.useRef)(websiteId);
   const onStepChangeRef = (0, import_react12.useRef)(onStepChange);
   const isActiveRef = (0, import_react12.useRef)(false);
   const activeCommandBatchIdRef = (0, import_react12.useRef)(null);
   socketIdRef.current = socketId;
   commandUrlRef.current = commandUrl;
+  websiteIdRef.current = websiteId;
   onStepChangeRef.current = onStepChange;
   isActiveRef.current = isActive;
   reviewModeRef.current = isReviewMode;
@@ -3200,25 +3297,17 @@ function useTourPlayback({
   (0, import_react12.useEffect)(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
-    let createdSocket = null;
-    const socket = (0, import_socket2.io)(serverUrl, {
-      path: "/socket.io",
-      transports: resolveSocketIoTransports(serverUrl, "polling-first"),
-      autoConnect: true,
-      reconnection: true,
-      reconnectionAttempts: 10,
-      reconnectionDelay: 1e3
-    });
-    createdSocket = socket;
+    const socket = tourSocketPool.acquire(serverUrl);
     socketRef.current = socket;
-    socket.on("connect", () => {
+    const handleConnect = () => {
       console.log("[TourClient] Connected to tour agent server:", socket.id);
       const profile = userProfileRef.current;
-      if (websiteId && profile?.userId && socket.connected) {
-        socket.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+      const currentWebsiteId = websiteIdRef.current;
+      if (currentWebsiteId && profile?.userId) {
+        emitSocketEvent(socket, "tour:init", { websiteId: currentWebsiteId, userId: profile.userId, userType: profile.type });
       }
-    });
-    socket.on("tour:server_state", (payload) => {
+    };
+    const handleServerState = (payload) => {
       if (typeof payload?.runId === "number") {
         runIdRef.current = payload.runId;
       }
@@ -3226,8 +3315,8 @@ function useTourPlayback({
         turnIdRef.current = payload.turnId ?? null;
       }
       setServerState(payload);
-    });
-    socket.on("tour:command_cancel", (payload) => {
+    };
+    const handleCommandCancel = (payload) => {
       console.log("[TourClient] Received command_cancel:", payload);
       if (payload.commandBatchId && activeCommandBatchIdRef.current === payload.commandBatchId) {
         activeCommandBatchIdRef.current = null;
@@ -3238,12 +3327,16 @@ function useTourPlayback({
           window.speechSynthesis.cancel();
         }
       }
-    });
-    socket.on("tour:command", async (payload) => {
+    };
+    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;
-        if (!socket.connected) return;
-        socket.emit(ev, data);
+        emitSocketEvent(socket, ev, data);
       };
       console.log("[TourClient] Received command batch:", payload.stepIndex, payload.commands);
       runCleanup(pendingManualWaitCleanupRef.current);
@@ -3736,8 +3829,8 @@ function useTourPlayback({
         turnId: turnIdRef.current
       });
       clearCommandBatchId();
-    });
-    socket.on("tour:start", async (tourData) => {
+    };
+    const handleTourStart = async (tourData) => {
       if (isActiveRef.current) return;
       runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
       const tour = tourData.tourContext ?? tourRef.current;
@@ -3747,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);
@@ -3770,8 +3864,8 @@ function useTourPlayback({
       try {
         const { generateMinifiedAOM: generateMinifiedAOM2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
         const aom = generateMinifiedAOM2();
-        if (socketRef.current === socket && socket.connected) {
-          socket.emit("tour:sync_dom", {
+        if (socketRef.current === socket) {
+          emitSocketEvent(socket, "tour:sync_dom", {
             url: window.location.pathname + window.location.search + window.location.hash,
             aom: aom.nodes,
             domSummary: captureDomSummary()
@@ -3780,8 +3874,8 @@ function useTourPlayback({
       } catch (e) {
         console.warn("[TourClient] Initial DOM sync failed:", e);
       }
-    });
-    socket.on("tour:update", (payload) => {
+    };
+    const handleTourUpdate = (payload) => {
       const updatedTour = payload?.tourContext;
       if (!updatedTour?.id || updatedTour.id !== tourRef.current?.id) {
         return;
@@ -3798,13 +3892,22 @@ function useTourPlayback({
           onStepChangeRef.current?.(clampedStepIndex, nextTotal, updatedTour);
         }
       }
-    });
-    socket.on("tour:end", () => {
+    };
+    const handleTourEndEvent = () => {
       setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
       handleTourEnd();
-    });
-    socket.on("tour:debug_log", (entry) => {
+    };
+    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") {
@@ -3813,29 +3916,40 @@ function useTourPlayback({
           }));
         }
       }
-    });
+    };
+    socket.on("connect", handleConnect);
+    socket.on("tour:server_state", handleServerState);
+    socket.on("tour:command_cancel", handleCommandCancel);
+    socket.on("tour:command", handleCommand);
+    socket.on("tour:start", handleTourStart);
+    socket.on("tour:update", handleTourUpdate);
+    socket.on("tour:end", handleTourEndEvent);
+    socket.on("tour:debug_log", handleDebugLog);
     console.log("[ModelNex SDK] Tour playback initialized. Debug logs enabled:", devModeRef.current || process.env.NODE_ENV === "development");
     return () => {
-      const toClose = createdSocket ?? socketRef.current;
-      if (toClose) {
-        toClose.disconnect();
-      }
-      createdSocket = null;
+      socket.off("connect", handleConnect);
+      socket.off("tour:server_state", handleServerState);
+      socket.off("tour:command_cancel", handleCommandCancel);
+      socket.off("tour:command", handleCommand);
+      socket.off("tour:start", handleTourStart);
+      socket.off("tour:update", handleTourUpdate);
+      socket.off("tour:end", handleTourEndEvent);
+      socket.off("tour:debug_log", handleDebugLog);
+      const toClose = socket;
       socketRef.current = null;
       setServerState(null);
       runIdRef.current = null;
       turnIdRef.current = null;
+      tourSocketPool.release(serverUrl, toClose);
     };
-  }, [serverUrl, websiteId, disabled]);
+  }, [serverUrl, disabled]);
   (0, import_react12.useEffect)(() => {
     if (disabled) return;
     const s = socketRef.current;
     const profile = userProfile;
-    if (!s?.connected || !websiteId || !profile?.userId) return;
+    if (!websiteId || !profile?.userId) return;
     const timer = setTimeout(() => {
-      if (s.connected) {
-        s.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
-      }
+      emitSocketEvent(s, "tour:init", { websiteId, userId: profile.userId, userType: profile.type });
     }, 150);
     return () => clearTimeout(timer);
   }, [disabled, websiteId, userProfile?.userId, userProfile?.type]);
@@ -3845,8 +3959,8 @@ function useTourPlayback({
     }
   }, [showCaptions, isReviewMode]);
   (0, import_react12.useEffect)(() => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return;
-    socketRef.current.emit("tour:client_state", {
+    if (!isActiveRef.current) return;
+    emitSocketEvent(socketRef.current, "tour:client_state", {
       runId: runIdRef.current,
       turnId: turnIdRef.current,
       commandBatchId: activeCommandBatchIdRef.current,
@@ -3859,19 +3973,17 @@ function useTourPlayback({
     });
   }, [isActive, playbackState, voice.isListening, voice.isSpeaking]);
   const syncAOM = (0, import_react12.useCallback)(async () => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return;
+    if (!isActiveRef.current) return;
     const { generateMinifiedAOM: generateMinifiedAOM2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
     const aom = generateMinifiedAOM2();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:sync_dom", {
-        url: window.location.pathname + window.location.search + window.location.hash,
-        aom: aom.nodes,
-        domSummary: captureDomSummary()
-      });
-    }
+    emitSocketEvent(socketRef.current, "tour:sync_dom", {
+      url: window.location.pathname + window.location.search + window.location.hash,
+      aom: aom.nodes,
+      domSummary: captureDomSummary()
+    });
   }, []);
   const interruptExecution = (0, import_react12.useCallback)((transcript) => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return false;
+    if (!isSocketWritable(socketRef.current) || !isActiveRef.current) return false;
     if (!commandInFlightRef.current && !voice.isSpeaking) return false;
     interruptedForQuestionRef.current = true;
     activeExecutionTokenRef.current += 1;
@@ -3879,17 +3991,16 @@ function useTourPlayback({
     removeHighlight();
     removeCaption();
     voice.stopSpeaking();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:action_result", {
-        success: true,
-        interrupted: true,
-        transcript,
-        commandBatchId: activeCommandBatchIdRef.current,
-        runId: runIdRef.current,
-        turnId: turnIdRef.current
-      });
+    if (emitSocketEvent(socketRef.current, "tour:action_result", {
+      success: true,
+      interrupted: true,
+      transcript,
+      commandBatchId: activeCommandBatchIdRef.current,
+      runId: runIdRef.current,
+      turnId: turnIdRef.current
+    })) {
       activeCommandBatchIdRef.current = null;
-      socketRef.current.emit("tour:user_input", {
+      emitSocketEvent(socketRef.current, "tour:user_input", {
         transcript,
         interrupted: true,
         runId: runIdRef.current,
@@ -3902,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;
@@ -3911,9 +4023,7 @@ function useTourPlayback({
     removeCaption();
     voice.stopSpeaking();
     voice.stopListening();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:abort");
-    }
+    emitSocketEvent(socketRef.current, "tour:abort");
     if (reviewModeRef.current && tourRef.current?.id && previewRunIdRef.current) {
       void logPreviewEvent(serverUrl, toursApiBaseRef.current, tourRef.current.id, previewRunIdRef.current, websiteId, {
         stepOrder: stepIndexRef.current,
@@ -3945,6 +4055,7 @@ function useTourPlayback({
     const endingPreviewRunId = previewRunIdRef.current;
     const endingStepOrder = stepIndexRef.current;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     setPlaybackState("complete");
     removeHighlight();
     removeCaption();
@@ -3978,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;
@@ -3985,10 +4103,11 @@ function useTourPlayback({
       await new Promise((r) => setTimeout(r, 200));
       retries++;
     }
-    if (!socketRef.current?.connected) {
+    if (!isSocketWritable(socketRef.current)) {
       console.warn("[TourClient] Cannot run tour, socket not connected.");
       return;
     }
+    startRequestedRef.current = true;
     const shouldReview = Boolean(options?.reviewMode);
     resetCaptionSuppression();
     setReviewStatusMessage(null);
@@ -4013,17 +4132,20 @@ function useTourPlayback({
       previewRunIdRef.current = null;
     }
     tourRef.current = tour;
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:request_start", {
-        tourId: tour.id,
-        previewRunId: previewRunIdRef.current,
-        tourContext: tour
-      });
-    }
+    emitSocketEvent(socketRef.current, "tour:request_start", {
+      tourId: tour.id,
+      previewRunId: previewRunIdRef.current,
+      tourContext: tour
+    });
   }, [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";
@@ -4071,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);
@@ -4111,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();
@@ -4163,8 +4290,8 @@ function useTourPlayback({
       const revisionVersion = Number(response?.revision?.versionNumber);
       const appliedMessage = Number.isFinite(revisionVersion) && revisionVersion > 0 ? `Applied to the draft as version ${revisionVersion}.` : "Correction applied to the draft.";
       setReviewStatusMessage(apply ? appliedMessage : "Correction saved for review.");
-      if (apply && playbackState === "paused" && socketRef.current?.connected && isActiveRef.current) {
-        socketRef.current.emit("tour:resume");
+      if (apply && playbackState === "paused" && isActiveRef.current) {
+        emitSocketEvent(socketRef.current, "tour:resume");
         setPlaybackState("executing");
       }
     } catch (err) {
@@ -4188,14 +4315,14 @@ function useTourPlayback({
     stopTour();
   }, [stopTour]);
   const pauseTour = (0, import_react12.useCallback)(() => {
-    if (socketRef.current?.connected && isActiveRef.current) {
-      socketRef.current.emit("tour:pause");
+    if (isSocketWritable(socketRef.current) && isActiveRef.current) {
+      emitSocketEvent(socketRef.current, "tour:pause");
       setPlaybackState("paused");
     }
   }, []);
   const resumeTour = (0, import_react12.useCallback)(() => {
-    if (socketRef.current?.connected && isActiveRef.current) {
-      socketRef.current.emit("tour:resume");
+    if (isSocketWritable(socketRef.current) && isActiveRef.current) {
+      emitSocketEvent(socketRef.current, "tour:resume");
       setPlaybackState("executing");
     }
   }, []);
@@ -4217,9 +4344,9 @@ function useTourPlayback({
     if (voiceInputResolveRef.current) {
       console.log("[TourAgent] Resolving loop waiting_voice with text:", text);
       voiceInputResolveRef.current(text);
-    } else if (socketRef.current?.connected) {
+    } else if (isSocketWritable(socketRef.current)) {
       console.log("[TourAgent] Forwarding ambient voice to server:", text);
-      socketRef.current.emit("tour:user_input", {
+      emitSocketEvent(socketRef.current, "tour:user_input", {
         transcript: text,
         runId: runIdRef.current,
         turnId: turnIdRef.current

package/dist/index.mjs

@@ -2416,7 +2416,6 @@ function isTourEligible(tour, userProfile) {
 
 // src/hooks/useTourPlayback.ts
 import { useState as useState7, useRef as useRef8, useCallback as useCallback7, useEffect as useEffect11, useContext as useContext4 } from "react";
-import { io as io2 } from "socket.io-client";
 
 // src/utils/retryLookup.ts
 var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -2439,6 +2438,101 @@ async function retryLookup({
   }
 }
 
+// src/utils/tour-socket-pool.ts
+import { io as io2 } from "socket.io-client";
+function isSocketWritable(socket) {
+  if (!socket?.connected) return false;
+  const engine = socket.io?.engine;
+  if (!engine) return true;
+  if (typeof engine.readyState === "string" && engine.readyState !== "open") return false;
+  if (engine.transport && "writable" in engine.transport && engine.transport.writable === false) return false;
+  return true;
+}
+function emitSocketEvent(socket, event, payload) {
+  if (!isSocketWritable(socket)) return false;
+  socket.emit(event, payload);
+  return true;
+}
+function createTourSocketPool({
+  createSocket = (serverUrl) => io2(serverUrl, {
+    path: "/socket.io",
+    transports: resolveSocketIoTransports(serverUrl, "polling-first"),
+    autoConnect: true,
+    reconnection: true,
+    reconnectionAttempts: 10,
+    reconnectionDelay: 1e3
+  }),
+  releaseDelayMs = 2500,
+  scheduleRelease = (callback, delayMs) => setTimeout(callback, delayMs),
+  cancelRelease = (timer) => clearTimeout(timer)
+} = {}) {
+  const pooledSockets = /* @__PURE__ */ new Map();
+  return {
+    acquire(serverUrl) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (pooled) {
+        if (pooled.releaseTimer) {
+          cancelRelease(pooled.releaseTimer);
+          pooled.releaseTimer = null;
+        }
+        pooled.leases += 1;
+        return pooled.socket;
+      }
+      const socket = createSocket(serverUrl);
+      pooledSockets.set(serverUrl, {
+        socket,
+        leases: 1,
+        releaseTimer: null
+      });
+      return socket;
+    },
+    release(serverUrl, socket) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (!pooled || pooled.socket !== socket) return;
+      pooled.leases = Math.max(0, pooled.leases - 1);
+      if (pooled.leases > 0) return;
+      pooled.releaseTimer = scheduleRelease(() => {
+        const latest = pooledSockets.get(serverUrl);
+        if (!latest || latest !== pooled || latest.leases > 0) return;
+        latest.socket.disconnect();
+        pooledSockets.delete(serverUrl);
+      }, releaseDelayMs);
+    },
+    // Test-only introspection
+    getSnapshot(serverUrl) {
+      const pooled = pooledSockets.get(serverUrl);
+      if (!pooled) return null;
+      return { leases: pooled.leases, socket: pooled.socket };
+    }
+  };
+}
+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;
@@ -2972,14 +3066,17 @@ 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);
+  const websiteIdRef = useRef8(websiteId);
   const onStepChangeRef = useRef8(onStepChange);
   const isActiveRef = useRef8(false);
   const activeCommandBatchIdRef = useRef8(null);
   socketIdRef.current = socketId;
   commandUrlRef.current = commandUrl;
+  websiteIdRef.current = websiteId;
   onStepChangeRef.current = onStepChange;
   isActiveRef.current = isActive;
   reviewModeRef.current = isReviewMode;
@@ -2990,25 +3087,17 @@ function useTourPlayback({
   useEffect11(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
-    let createdSocket = null;
-    const socket = io2(serverUrl, {
-      path: "/socket.io",
-      transports: resolveSocketIoTransports(serverUrl, "polling-first"),
-      autoConnect: true,
-      reconnection: true,
-      reconnectionAttempts: 10,
-      reconnectionDelay: 1e3
-    });
-    createdSocket = socket;
+    const socket = tourSocketPool.acquire(serverUrl);
     socketRef.current = socket;
-    socket.on("connect", () => {
+    const handleConnect = () => {
       console.log("[TourClient] Connected to tour agent server:", socket.id);
       const profile = userProfileRef.current;
-      if (websiteId && profile?.userId && socket.connected) {
-        socket.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+      const currentWebsiteId = websiteIdRef.current;
+      if (currentWebsiteId && profile?.userId) {
+        emitSocketEvent(socket, "tour:init", { websiteId: currentWebsiteId, userId: profile.userId, userType: profile.type });
       }
-    });
-    socket.on("tour:server_state", (payload) => {
+    };
+    const handleServerState = (payload) => {
       if (typeof payload?.runId === "number") {
         runIdRef.current = payload.runId;
       }
@@ -3016,8 +3105,8 @@ function useTourPlayback({
         turnIdRef.current = payload.turnId ?? null;
       }
       setServerState(payload);
-    });
-    socket.on("tour:command_cancel", (payload) => {
+    };
+    const handleCommandCancel = (payload) => {
       console.log("[TourClient] Received command_cancel:", payload);
       if (payload.commandBatchId && activeCommandBatchIdRef.current === payload.commandBatchId) {
         activeCommandBatchIdRef.current = null;
@@ -3028,12 +3117,16 @@ function useTourPlayback({
           window.speechSynthesis.cancel();
         }
       }
-    });
-    socket.on("tour:command", async (payload) => {
+    };
+    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;
-        if (!socket.connected) return;
-        socket.emit(ev, data);
+        emitSocketEvent(socket, ev, data);
       };
       console.log("[TourClient] Received command batch:", payload.stepIndex, payload.commands);
       runCleanup(pendingManualWaitCleanupRef.current);
@@ -3526,8 +3619,8 @@ function useTourPlayback({
         turnId: turnIdRef.current
       });
       clearCommandBatchId();
-    });
-    socket.on("tour:start", async (tourData) => {
+    };
+    const handleTourStart = async (tourData) => {
       if (isActiveRef.current) return;
       runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
       const tour = tourData.tourContext ?? tourRef.current;
@@ -3537,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);
@@ -3560,8 +3654,8 @@ function useTourPlayback({
       try {
         const { generateMinifiedAOM: generateMinifiedAOM2 } = await import("./aom-HDYNCIOY.mjs");
         const aom = generateMinifiedAOM2();
-        if (socketRef.current === socket && socket.connected) {
-          socket.emit("tour:sync_dom", {
+        if (socketRef.current === socket) {
+          emitSocketEvent(socket, "tour:sync_dom", {
             url: window.location.pathname + window.location.search + window.location.hash,
             aom: aom.nodes,
             domSummary: captureDomSummary()
@@ -3570,8 +3664,8 @@ function useTourPlayback({
       } catch (e) {
         console.warn("[TourClient] Initial DOM sync failed:", e);
       }
-    });
-    socket.on("tour:update", (payload) => {
+    };
+    const handleTourUpdate = (payload) => {
       const updatedTour = payload?.tourContext;
       if (!updatedTour?.id || updatedTour.id !== tourRef.current?.id) {
         return;
@@ -3588,13 +3682,22 @@ function useTourPlayback({
           onStepChangeRef.current?.(clampedStepIndex, nextTotal, updatedTour);
         }
       }
-    });
-    socket.on("tour:end", () => {
+    };
+    const handleTourEndEvent = () => {
       setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
       handleTourEnd();
-    });
-    socket.on("tour:debug_log", (entry) => {
+    };
+    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") {
@@ -3603,29 +3706,40 @@ function useTourPlayback({
           }));
         }
       }
-    });
+    };
+    socket.on("connect", handleConnect);
+    socket.on("tour:server_state", handleServerState);
+    socket.on("tour:command_cancel", handleCommandCancel);
+    socket.on("tour:command", handleCommand);
+    socket.on("tour:start", handleTourStart);
+    socket.on("tour:update", handleTourUpdate);
+    socket.on("tour:end", handleTourEndEvent);
+    socket.on("tour:debug_log", handleDebugLog);
     console.log("[ModelNex SDK] Tour playback initialized. Debug logs enabled:", devModeRef.current || process.env.NODE_ENV === "development");
     return () => {
-      const toClose = createdSocket ?? socketRef.current;
-      if (toClose) {
-        toClose.disconnect();
-      }
-      createdSocket = null;
+      socket.off("connect", handleConnect);
+      socket.off("tour:server_state", handleServerState);
+      socket.off("tour:command_cancel", handleCommandCancel);
+      socket.off("tour:command", handleCommand);
+      socket.off("tour:start", handleTourStart);
+      socket.off("tour:update", handleTourUpdate);
+      socket.off("tour:end", handleTourEndEvent);
+      socket.off("tour:debug_log", handleDebugLog);
+      const toClose = socket;
       socketRef.current = null;
       setServerState(null);
       runIdRef.current = null;
       turnIdRef.current = null;
+      tourSocketPool.release(serverUrl, toClose);
     };
-  }, [serverUrl, websiteId, disabled]);
+  }, [serverUrl, disabled]);
   useEffect11(() => {
     if (disabled) return;
     const s = socketRef.current;
     const profile = userProfile;
-    if (!s?.connected || !websiteId || !profile?.userId) return;
+    if (!websiteId || !profile?.userId) return;
     const timer = setTimeout(() => {
-      if (s.connected) {
-        s.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
-      }
+      emitSocketEvent(s, "tour:init", { websiteId, userId: profile.userId, userType: profile.type });
     }, 150);
     return () => clearTimeout(timer);
   }, [disabled, websiteId, userProfile?.userId, userProfile?.type]);
@@ -3635,8 +3749,8 @@ function useTourPlayback({
     }
   }, [showCaptions, isReviewMode]);
   useEffect11(() => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return;
-    socketRef.current.emit("tour:client_state", {
+    if (!isActiveRef.current) return;
+    emitSocketEvent(socketRef.current, "tour:client_state", {
       runId: runIdRef.current,
       turnId: turnIdRef.current,
       commandBatchId: activeCommandBatchIdRef.current,
@@ -3649,19 +3763,17 @@ function useTourPlayback({
     });
   }, [isActive, playbackState, voice.isListening, voice.isSpeaking]);
   const syncAOM = useCallback7(async () => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return;
+    if (!isActiveRef.current) return;
     const { generateMinifiedAOM: generateMinifiedAOM2 } = await import("./aom-HDYNCIOY.mjs");
     const aom = generateMinifiedAOM2();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:sync_dom", {
-        url: window.location.pathname + window.location.search + window.location.hash,
-        aom: aom.nodes,
-        domSummary: captureDomSummary()
-      });
-    }
+    emitSocketEvent(socketRef.current, "tour:sync_dom", {
+      url: window.location.pathname + window.location.search + window.location.hash,
+      aom: aom.nodes,
+      domSummary: captureDomSummary()
+    });
   }, []);
   const interruptExecution = useCallback7((transcript) => {
-    if (!socketRef.current?.connected || !isActiveRef.current) return false;
+    if (!isSocketWritable(socketRef.current) || !isActiveRef.current) return false;
     if (!commandInFlightRef.current && !voice.isSpeaking) return false;
     interruptedForQuestionRef.current = true;
     activeExecutionTokenRef.current += 1;
@@ -3669,17 +3781,16 @@ function useTourPlayback({
     removeHighlight();
     removeCaption();
     voice.stopSpeaking();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:action_result", {
-        success: true,
-        interrupted: true,
-        transcript,
-        commandBatchId: activeCommandBatchIdRef.current,
-        runId: runIdRef.current,
-        turnId: turnIdRef.current
-      });
+    if (emitSocketEvent(socketRef.current, "tour:action_result", {
+      success: true,
+      interrupted: true,
+      transcript,
+      commandBatchId: activeCommandBatchIdRef.current,
+      runId: runIdRef.current,
+      turnId: turnIdRef.current
+    })) {
       activeCommandBatchIdRef.current = null;
-      socketRef.current.emit("tour:user_input", {
+      emitSocketEvent(socketRef.current, "tour:user_input", {
         transcript,
         interrupted: true,
         runId: runIdRef.current,
@@ -3692,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;
@@ -3701,9 +3813,7 @@ function useTourPlayback({
     removeCaption();
     voice.stopSpeaking();
     voice.stopListening();
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:abort");
-    }
+    emitSocketEvent(socketRef.current, "tour:abort");
     if (reviewModeRef.current && tourRef.current?.id && previewRunIdRef.current) {
       void logPreviewEvent(serverUrl, toursApiBaseRef.current, tourRef.current.id, previewRunIdRef.current, websiteId, {
         stepOrder: stepIndexRef.current,
@@ -3735,6 +3845,7 @@ function useTourPlayback({
     const endingPreviewRunId = previewRunIdRef.current;
     const endingStepOrder = stepIndexRef.current;
     isActiveRef.current = false;
+    startRequestedRef.current = false;
     setPlaybackState("complete");
     removeHighlight();
     removeCaption();
@@ -3768,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;
@@ -3775,10 +3893,11 @@ function useTourPlayback({
       await new Promise((r) => setTimeout(r, 200));
       retries++;
     }
-    if (!socketRef.current?.connected) {
+    if (!isSocketWritable(socketRef.current)) {
       console.warn("[TourClient] Cannot run tour, socket not connected.");
       return;
     }
+    startRequestedRef.current = true;
     const shouldReview = Boolean(options?.reviewMode);
     resetCaptionSuppression();
     setReviewStatusMessage(null);
@@ -3803,17 +3922,20 @@ function useTourPlayback({
       previewRunIdRef.current = null;
     }
     tourRef.current = tour;
-    if (socketRef.current?.connected) {
-      socketRef.current.emit("tour:request_start", {
-        tourId: tour.id,
-        previewRunId: previewRunIdRef.current,
-        tourContext: tour
-      });
-    }
+    emitSocketEvent(socketRef.current, "tour:request_start", {
+      tourId: tour.id,
+      previewRunId: previewRunIdRef.current,
+      tourContext: tour
+    });
   }, [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";
@@ -3861,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);
@@ -3901,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();
@@ -3953,8 +4080,8 @@ function useTourPlayback({
       const revisionVersion = Number(response?.revision?.versionNumber);
       const appliedMessage = Number.isFinite(revisionVersion) && revisionVersion > 0 ? `Applied to the draft as version ${revisionVersion}.` : "Correction applied to the draft.";
       setReviewStatusMessage(apply ? appliedMessage : "Correction saved for review.");
-      if (apply && playbackState === "paused" && socketRef.current?.connected && isActiveRef.current) {
-        socketRef.current.emit("tour:resume");
+      if (apply && playbackState === "paused" && isActiveRef.current) {
+        emitSocketEvent(socketRef.current, "tour:resume");
         setPlaybackState("executing");
       }
     } catch (err) {
@@ -3978,14 +4105,14 @@ function useTourPlayback({
     stopTour();
   }, [stopTour]);
   const pauseTour = useCallback7(() => {
-    if (socketRef.current?.connected && isActiveRef.current) {
-      socketRef.current.emit("tour:pause");
+    if (isSocketWritable(socketRef.current) && isActiveRef.current) {
+      emitSocketEvent(socketRef.current, "tour:pause");
       setPlaybackState("paused");
     }
   }, []);
   const resumeTour = useCallback7(() => {
-    if (socketRef.current?.connected && isActiveRef.current) {
-      socketRef.current.emit("tour:resume");
+    if (isSocketWritable(socketRef.current) && isActiveRef.current) {
+      emitSocketEvent(socketRef.current, "tour:resume");
       setPlaybackState("executing");
     }
   }, []);
@@ -4007,9 +4134,9 @@ function useTourPlayback({
     if (voiceInputResolveRef.current) {
       console.log("[TourAgent] Resolving loop waiting_voice with text:", text);
       voiceInputResolveRef.current(text);
-    } else if (socketRef.current?.connected) {
+    } else if (isSocketWritable(socketRef.current)) {
       console.log("[TourAgent] Forwarding ambient voice to server:", text);
-      socketRef.current.emit("tour:user_input", {
+      emitSocketEvent(socketRef.current, "tour:user_input", {
         transcript: text,
         runId: runIdRef.current,
         turnId: turnIdRef.current

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelnex/sdk",
-  "version": "0.5.16",
+  "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",