@modelnex/sdk 0.5.15 → 0.5.17

package/dist/index.js

@@ -2648,6 +2648,76 @@ 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/hooks/useTourPlayback.ts
 function resolveElement(step) {
   const el = step.element;
@@ -3184,11 +3254,13 @@ function useTourPlayback({
   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;
@@ -3199,646 +3271,646 @@ function useTourPlayback({
   (0, import_react12.useEffect)(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
-    let cancelled = false;
-    let createdSocket = null;
-    import("socket.io-client").then((ioModule) => {
-      if (cancelled) return;
-      const io2 = ioModule.default || ioModule;
-      const socket = io2(serverUrl, {
-        path: "/socket.io",
-        // standard
-        transports: resolveSocketIoTransports(serverUrl, "polling-first")
-      });
-      if (cancelled) {
-        socket.disconnect();
-        return;
+    const socket = tourSocketPool.acquire(serverUrl);
+    socketRef.current = socket;
+    const handleConnect = () => {
+      console.log("[TourClient] Connected to tour agent server:", socket.id);
+      const profile = userProfileRef.current;
+      const currentWebsiteId = websiteIdRef.current;
+      if (currentWebsiteId && profile?.userId) {
+        emitSocketEvent(socket, "tour:init", { websiteId: currentWebsiteId, userId: profile.userId, userType: profile.type });
       }
-      createdSocket = socket;
-      socketRef.current = socket;
-      socket.on("connect", () => {
-        console.log("[TourClient] Connected to tour agent server:", socket.id);
-        const profile = userProfileRef.current;
-        if (websiteId && profile?.userId) {
-          socket.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
-        }
-      });
-      socket.on("tour:server_state", (payload) => {
-        if (typeof payload?.runId === "number") {
-          runIdRef.current = payload.runId;
-        }
-        if (typeof payload?.turnId === "string" || payload?.turnId === null) {
-          turnIdRef.current = payload.turnId ?? null;
+    };
+    const handleServerState = (payload) => {
+      if (typeof payload?.runId === "number") {
+        runIdRef.current = payload.runId;
+      }
+      if (typeof payload?.turnId === "string" || payload?.turnId === null) {
+        turnIdRef.current = payload.turnId ?? null;
+      }
+      setServerState(payload);
+    };
+    const handleCommandCancel = (payload) => {
+      console.log("[TourClient] Received command_cancel:", payload);
+      if (payload.commandBatchId && activeCommandBatchIdRef.current === payload.commandBatchId) {
+        activeCommandBatchIdRef.current = null;
+        activeExecutionTokenRef.current++;
+        commandInFlightRef.current = false;
+        setPlaybackState("idle");
+        if (typeof window !== "undefined" && window.speechSynthesis) {
+          window.speechSynthesis.cancel();
         }
-        setServerState(payload);
-      });
-      socket.on("tour:command_cancel", (payload) => {
-        console.log("[TourClient] Received command_cancel:", payload);
-        if (payload.commandBatchId && activeCommandBatchIdRef.current === payload.commandBatchId) {
+      }
+    };
+    const handleCommand = async (payload) => {
+      const emitIfOpen = (ev, data) => {
+        if (socketRef.current !== socket) return;
+        emitSocketEvent(socket, ev, data);
+      };
+      console.log("[TourClient] Received command batch:", payload.stepIndex, payload.commands);
+      runCleanup(pendingManualWaitCleanupRef.current);
+      pendingManualWaitCleanupRef.current = null;
+      if (voiceInputResolveRef.current) {
+        const resolvePendingVoiceInput = voiceInputResolveRef.current;
+        voiceInputResolveRef.current = null;
+        resolvePendingVoiceInput("");
+      }
+      setPlaybackState("executing");
+      commandInFlightRef.current = true;
+      const commandBatchId = payload.commandBatchId ?? null;
+      turnIdRef.current = payload.turnId ?? turnIdRef.current;
+      const clearCommandBatchId = () => {
+        if (activeCommandBatchIdRef.current === commandBatchId) {
           activeCommandBatchIdRef.current = null;
-          activeExecutionTokenRef.current++;
-          commandInFlightRef.current = false;
-          setPlaybackState("idle");
-          if (typeof window !== "undefined" && window.speechSynthesis) {
-            window.speechSynthesis.cancel();
-          }
-        }
-      });
-      socket.on("tour:command", async (payload) => {
-        const emitIfOpen = (ev, data) => {
-          if (socketRef.current !== socket) return;
-          if (!socket.connected) return;
-          socket.emit(ev, data);
-        };
-        console.log("[TourClient] Received command batch:", payload.stepIndex, payload.commands);
-        runCleanup(pendingManualWaitCleanupRef.current);
-        pendingManualWaitCleanupRef.current = null;
-        if (voiceInputResolveRef.current) {
-          const resolvePendingVoiceInput = voiceInputResolveRef.current;
-          voiceInputResolveRef.current = null;
-          resolvePendingVoiceInput("");
         }
-        setPlaybackState("executing");
-        commandInFlightRef.current = true;
-        const commandBatchId = payload.commandBatchId ?? null;
-        turnIdRef.current = payload.turnId ?? turnIdRef.current;
-        const clearCommandBatchId = () => {
-          if (activeCommandBatchIdRef.current === commandBatchId) {
-            activeCommandBatchIdRef.current = null;
+      };
+      activeCommandBatchIdRef.current = commandBatchId;
+      const executionToken = ++activeExecutionTokenRef.current;
+      const activeTourId = tourRef.current?.id;
+      const activePreviewRunId = previewRunIdRef.current;
+      if (reviewModeRef.current && activeTourId && activePreviewRunId && typeof payload.stepIndex === "number") {
+        void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
+          stepOrder: payload.stepIndex,
+          eventType: "command_batch_received",
+          payload: {
+            commandBatchId,
+            commandTypes: Array.isArray(payload.commands) ? payload.commands.map((command) => command?.type || "unknown") : []
+          },
+          currentStepOrder: payload.stepIndex
+        });
+      }
+      if (typeof payload.stepIndex === "number") {
+        const prevStep = stepIndexRef.current;
+        stepIndexRef.current = payload.stepIndex;
+        setCurrentStepIndex(payload.stepIndex);
+        if (payload.stepIndex !== prevStep) {
+          const tour = tourRef.current;
+          const total = tour?.steps?.length ?? 0;
+          if (tour && total > 0) {
+            onStepChangeRef.current?.(payload.stepIndex, total, tour);
           }
-        };
-        activeCommandBatchIdRef.current = commandBatchId;
-        const executionToken = ++activeExecutionTokenRef.current;
-        const activeTourId = tourRef.current?.id;
-        const activePreviewRunId = previewRunIdRef.current;
-        if (reviewModeRef.current && activeTourId && activePreviewRunId && typeof payload.stepIndex === "number") {
+        }
+        if (reviewModeRef.current && activeTourId && activePreviewRunId) {
           void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
             stepOrder: payload.stepIndex,
-            eventType: "command_batch_received",
+            eventType: "step_started",
             payload: {
-              commandBatchId,
-              commandTypes: Array.isArray(payload.commands) ? payload.commands.map((command) => command?.type || "unknown") : []
+              previousStepOrder: prevStep,
+              stepType: tourRef.current?.steps?.[payload.stepIndex]?.type ?? null
             },
             currentStepOrder: payload.stepIndex
           });
         }
-        if (typeof payload.stepIndex === "number") {
-          const prevStep = stepIndexRef.current;
-          stepIndexRef.current = payload.stepIndex;
-          setCurrentStepIndex(payload.stepIndex);
-          if (payload.stepIndex !== prevStep) {
-            const tour = tourRef.current;
-            const total = tour?.steps?.length ?? 0;
-            if (tour && total > 0) {
-              onStepChangeRef.current?.(payload.stepIndex, total, tour);
-            }
-          }
-          if (reviewModeRef.current && activeTourId && activePreviewRunId) {
-            void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
-              stepOrder: payload.stepIndex,
-              eventType: "step_started",
-              payload: {
-                previousStepOrder: prevStep,
-                stepType: tourRef.current?.steps?.[payload.stepIndex]?.type ?? null
-              },
-              currentStepOrder: payload.stepIndex
-            });
-          }
-        }
-        if (!payload.commands || !Array.isArray(payload.commands)) {
-          console.warn("[TourClient] Payload commands is not an array:", payload);
-          commandInFlightRef.current = false;
-          emitIfOpen("tour:action_result", {
-            success: false,
-            reason: "invalid_commands",
-            commandBatchId,
-            runId: runIdRef.current,
-            turnId: turnIdRef.current
-          });
-          clearCommandBatchId();
-          return;
+      }
+      if (!payload.commands || !Array.isArray(payload.commands)) {
+        console.warn("[TourClient] Payload commands is not an array:", payload);
+        commandInFlightRef.current = false;
+        emitIfOpen("tour:action_result", {
+          success: false,
+          reason: "invalid_commands",
+          commandBatchId,
+          runId: runIdRef.current,
+          turnId: turnIdRef.current
+        });
+        clearCommandBatchId();
+        return;
+      }
+      let shouldWait = false;
+      const results = [];
+      let batchPreferredWaitTarget = null;
+      const assertNotInterrupted = () => {
+        if (executionToken !== activeExecutionTokenRef.current || skipRequestedRef.current) {
+          const error = new Error("interrupted");
+          error.code = "INTERRUPTED";
+          throw error;
         }
-        let shouldWait = false;
-        const results = [];
-        let batchPreferredWaitTarget = null;
-        const assertNotInterrupted = () => {
-          if (executionToken !== activeExecutionTokenRef.current || skipRequestedRef.current) {
-            const error = new Error("interrupted");
-            error.code = "INTERRUPTED";
-            throw error;
-          }
-        };
-        const resolveTargetElement2 = async (params = {}, fallbackStep) => {
-          const fallbackHints = fallbackStep?.element ?? null;
-          return retryLookup({
-            timeoutMs: Math.max(0, Number(params.timeoutMs ?? 1800)),
-            pollMs: Math.max(50, Number(params.pollMs ?? 120)),
-            onRetry: () => {
-              assertNotInterrupted();
-            },
-            resolve: async () => {
-              let targetEl = null;
-              if (params.uid) {
-                const { getElementByUid: getElementByUid2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
-                targetEl = getElementByUid2(params.uid);
-              }
-              if (!targetEl) {
-                targetEl = resolveElementFromHints({
-                  fingerprint: params.fingerprint ?? fallbackHints?.fingerprint,
-                  testId: params.testId ?? fallbackHints?.testId,
-                  textContaining: params.textContaining ?? fallbackHints?.textContaining
-                }, fallbackStep, tagStore);
-              }
-              return targetEl;
-            }
-          });
-        };
-        const executeOne = async (action) => {
-          assertNotInterrupted();
-          console.log("[TourClient] Executing action:", action?.type, action?.params ? JSON.stringify(action.params).slice(0, 120) : "");
-          const currentStep = tourRef.current?.steps?.[stepIndexRef.current] ?? null;
-          const executeTimeline = async (params = {}) => {
-            const segments = Array.isArray(params.segments) ? params.segments : [];
-            for (let index = 0; index < segments.length; index += 1) {
-              assertNotInterrupted();
-              const segment = segments[index];
-              const segmentText = (segment?.text ?? "").trim();
-              const segmentDelayMs = Math.max(0, Number(segment?.delayMs ?? 0));
-              const events = Array.isArray(segment?.events) ? segment.events : [];
-              if (segmentDelayMs > 0) {
-                await new Promise((resolve) => setTimeout(resolve, segmentDelayMs));
-              }
-              if (segment?.gate?.type === "user_action" && segment.gate.target && segment.gate.event) {
-                const gateTarget = await resolveTargetElement2(segment.gate.target, currentStep);
-                if (!gateTarget) {
-                  throw new Error(`timeline gate target not found for ${segment.gate.event}`);
-                }
-                await waitForUserAction(gateTarget, segment.gate.event);
-              }
-              if (segmentText && showCaptionsRef.current && reviewModeRef.current) {
-                showCaption(segmentText);
-              }
-              const nextSegmentText = (segments[index + 1]?.text ?? "").trim();
-              const speechPromise = segmentText ? voice.speak(segmentText, tourRef.current?.voice?.ttsVoice, {
-                prefetchLeadMs: tourRef.current?.voice?.ttsPrefetchLeadMs ?? currentStep?.execution?.ttsPrefetchLeadMs ?? 2e3,
-                onNearEnd: nextSegmentText ? () => {
-                  void voice.prefetchSpeech(nextSegmentText, tourRef.current?.voice?.ttsVoice);
-                } : void 0
-              }) : Promise.resolve();
-              const eventsPromise = (async () => {
-                for (const event of events) {
-                  assertNotInterrupted();
-                  const delayMs = Math.max(0, Number(event?.delayMs ?? 0));
-                  if (delayMs > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, delayMs));
-                  }
-                  if (event?.action) {
-                    await executeOne(event.action);
-                  }
-                }
-              })();
-              await Promise.all([speechPromise, eventsPromise]);
-            }
-            if (params.removeHighlightAtEnd !== false) {
-              removeHighlight();
-            }
-            if (showCaptionsRef.current && reviewModeRef.current) {
-              removeCaption();
-            }
-            return !!params.waitForInput;
-          };
-          if (action.type === "speak") {
-            const text = action.params?.text ?? "";
-            if (!text.trim()) {
-              return { result: null };
+      };
+      const resolveTargetElement2 = async (params = {}, fallbackStep) => {
+        const fallbackHints = fallbackStep?.element ?? null;
+        return retryLookup({
+          timeoutMs: Math.max(0, Number(params.timeoutMs ?? 1800)),
+          pollMs: Math.max(50, Number(params.pollMs ?? 120)),
+          onRetry: () => {
+            assertNotInterrupted();
+          },
+          resolve: async () => {
+            let targetEl = null;
+            if (params.uid) {
+              const { getElementByUid: getElementByUid2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
+              targetEl = getElementByUid2(params.uid);
             }
-            if (showCaptionsRef.current && reviewModeRef.current) {
-              showCaption(text);
+            if (!targetEl) {
+              targetEl = resolveElementFromHints({
+                fingerprint: params.fingerprint ?? fallbackHints?.fingerprint,
+                testId: params.testId ?? fallbackHints?.testId,
+                textContaining: params.textContaining ?? fallbackHints?.textContaining
+              }, fallbackStep, tagStore);
             }
-            const settlePromise = voice.speak(text, tourRef.current?.voice?.ttsVoice, {
-              // Schedule narration immediately so the client keeps its speculative,
-              // low-latency behavior, but defer batch completion until playback settles.
-              waitForCompletion: false,
-              interrupt: action.params?.interrupt
-            });
-            return { result: text, settlePromise };
+            return targetEl;
           }
-          if (action.type === "play_timeline") {
-            const timelineShouldWait = await executeTimeline(action.params);
-            if (timelineShouldWait) shouldWait = true;
-            return { result: "timeline_executed" };
-          }
-          if (action.type === "highlight_element") {
-            const resolvedEl = await resolveTargetElement2(action.params, currentStep);
-            if (resolvedEl) {
-              if (isEditableWaitTarget(resolvedEl)) {
-                batchPreferredWaitTarget = resolveWaitTargetElement(resolvedEl);
+        });
+      };
+      const executeOne = async (action) => {
+        assertNotInterrupted();
+        console.log("[TourClient] Executing action:", action?.type, action?.params ? JSON.stringify(action.params).slice(0, 120) : "");
+        const currentStep = tourRef.current?.steps?.[stepIndexRef.current] ?? null;
+        const executeTimeline = async (params = {}) => {
+          const segments = Array.isArray(params.segments) ? params.segments : [];
+          for (let index = 0; index < segments.length; index += 1) {
+            assertNotInterrupted();
+            const segment = segments[index];
+            const segmentText = (segment?.text ?? "").trim();
+            const segmentDelayMs = Math.max(0, Number(segment?.delayMs ?? 0));
+            const events = Array.isArray(segment?.events) ? segment.events : [];
+            if (segmentDelayMs > 0) {
+              await new Promise((resolve) => setTimeout(resolve, segmentDelayMs));
+            }
+            if (segment?.gate?.type === "user_action" && segment.gate.target && segment.gate.event) {
+              const gateTarget = await resolveTargetElement2(segment.gate.target, currentStep);
+              if (!gateTarget) {
+                throw new Error(`timeline gate target not found for ${segment.gate.event}`);
               }
-              showHighlight(resolvedEl, action.params?.label || action.label);
-              resolvedEl.scrollIntoView({ behavior: "smooth", block: "nearest" });
-              return { result: "highlighted" };
+              await waitForUserAction(gateTarget, segment.gate.event);
             }
-            if (!action.params?.optional) {
-              throw new Error(
-                `highlight_element target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
-              );
+            if (segmentText && showCaptionsRef.current && reviewModeRef.current) {
+              showCaption(segmentText);
             }
-            return { result: "highlight_optional_miss" };
+            const nextSegmentText = (segments[index + 1]?.text ?? "").trim();
+            const speechPromise = segmentText ? voice.speak(segmentText, tourRef.current?.voice?.ttsVoice, {
+              prefetchLeadMs: tourRef.current?.voice?.ttsPrefetchLeadMs ?? currentStep?.execution?.ttsPrefetchLeadMs ?? 2e3,
+              onNearEnd: nextSegmentText ? () => {
+                void voice.prefetchSpeech(nextSegmentText, tourRef.current?.voice?.ttsVoice);
+              } : void 0
+            }) : Promise.resolve();
+            const eventsPromise = (async () => {
+              for (const event of events) {
+                assertNotInterrupted();
+                const delayMs = Math.max(0, Number(event?.delayMs ?? 0));
+                if (delayMs > 0) {
+                  await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+                if (event?.action) {
+                  await executeOne(event.action);
+                }
+              }
+            })();
+            await Promise.all([speechPromise, eventsPromise]);
           }
-          if (action.type === "remove_highlight") {
+          if (params.removeHighlightAtEnd !== false) {
             removeHighlight();
-            return { result: "highlight_removed" };
           }
-          if (action.type === "click_element") {
-            const targetEl = await resolveTargetElement2(action.params, currentStep);
-            if (!targetEl) {
-              if (action.params?.optional) return { result: "click_optional_miss" };
-              throw new Error(
-                `click_element target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
-              );
-            }
-            removeHighlight();
-            await performInteractiveClick(targetEl);
-            const { waitForDomSettle: waitForDomSettleClick } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
-            await waitForDomSettleClick({ timeoutMs: 3e3, debounceMs: 300 });
-            return { result: "clicked" };
+          if (showCaptionsRef.current && reviewModeRef.current) {
+            removeCaption();
           }
-          if (action.type === "fill_input") {
-            const targetEl = await resolveTargetElement2(action.params, currentStep);
-            if (!targetEl) {
-              throw new Error(
-                `fill_input target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
-              );
-            }
-            const value = typeof action.params?.value === "string" ? action.params.value : "";
-            batchPreferredWaitTarget = resolveWaitTargetElement(targetEl);
-            await performInteractiveFill(targetEl, value);
-            return { result: value };
+          return !!params.waitForInput;
+        };
+        if (action.type === "speak") {
+          const text = action.params?.text ?? "";
+          if (!text.trim()) {
+            return { result: null };
           }
-          if (action.type === "take_screenshot") {
-            const html2canvasModule = await import("html2canvas");
-            const html2canvas2 = html2canvasModule.default;
-            const canvas = await html2canvas2(document.body, {
-              useCORS: true,
-              allowTaint: true,
-              scale: Math.min(window.devicePixelRatio, 2),
-              width: window.innerWidth,
-              height: window.innerHeight,
-              x: window.scrollX,
-              y: window.scrollY,
-              logging: false
-            });
-            return { result: canvas.toDataURL("image/png") };
+          if (showCaptionsRef.current && reviewModeRef.current) {
+            showCaption(text);
           }
-          if (action.type === "navigate_to_url") {
-            const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
-            if (!nextUrl) {
-              throw new Error("navigate_to_url missing url");
+          const settlePromise = voice.speak(text, tourRef.current?.voice?.ttsVoice, {
+            // Schedule narration immediately so the client keeps its speculative,
+            // low-latency behavior, but defer batch completion until playback settles.
+            waitForCompletion: false,
+            interrupt: action.params?.interrupt
+          });
+          return { result: text, settlePromise };
+        }
+        if (action.type === "play_timeline") {
+          const timelineShouldWait = await executeTimeline(action.params);
+          if (timelineShouldWait) shouldWait = true;
+          return { result: "timeline_executed" };
+        }
+        if (action.type === "highlight_element") {
+          const resolvedEl = await resolveTargetElement2(action.params, currentStep);
+          if (resolvedEl) {
+            if (isEditableWaitTarget(resolvedEl)) {
+              batchPreferredWaitTarget = resolveWaitTargetElement(resolvedEl);
             }
-            await navigateToTourUrl(nextUrl);
-            const { waitForDomSettle: waitForDomSettleNav } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
-            await waitForDomSettleNav({ timeoutMs: 3e3, debounceMs: 300 });
-            return { result: nextUrl };
+            showHighlight(resolvedEl, action.params?.label || action.label);
+            resolvedEl.scrollIntoView({ behavior: "smooth", block: "nearest" });
+            return { result: "highlighted" };
           }
-          if (action.type === "execute_agent_action") {
-            const agentSocketId = socketIdRef.current ?? socketRef.current?.id;
-            if (!agentSocketId) {
-              throw new Error("No socketId available for execute_agent_action");
-            }
-            const url = getAgentCommandUrl(serverUrl, commandUrlRef.current);
-            const res = await fetch(url, {
-              method: "POST",
-              headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({
-                command: action.params?.command,
-                socketId: agentSocketId
-              })
-            });
-            if (!res.ok) {
-              throw new Error(`execute_agent_action failed: ${await res.text()}`);
-            }
-            if (action.params?.wait !== false) {
-              await res.json();
-            }
-            const { waitForDomSettle: waitForDomSettle2 } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
-            await waitForDomSettle2({ timeoutMs: 3e3, debounceMs: 300 });
-            await syncAOM();
-            return { result: action.params?.command ?? "executed" };
+          if (!action.params?.optional) {
+            throw new Error(
+              `highlight_element target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
+            );
           }
-          if (action.type === "wait_for_user_action") {
-            const targetEl = await resolveTargetElement2(action.params, currentStep);
-            if (!targetEl) {
-              throw new Error("wait_for_user_action target not found");
-            }
-            const eventName = action.params?.event ?? "click";
-            await waitForUserAction(targetEl, eventName);
-            return { result: `waited_for_${eventName}` };
+          return { result: "highlight_optional_miss" };
+        }
+        if (action.type === "remove_highlight") {
+          removeHighlight();
+          return { result: "highlight_removed" };
+        }
+        if (action.type === "click_element") {
+          const targetEl = await resolveTargetElement2(action.params, currentStep);
+          if (!targetEl) {
+            if (action.params?.optional) return { result: "click_optional_miss" };
+            throw new Error(
+              `click_element target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
+            );
           }
-          if (action.type === "wait_for_input") {
-            shouldWait = true;
-            return { result: "waiting_for_input" };
+          removeHighlight();
+          await performInteractiveClick(targetEl);
+          const { waitForDomSettle: waitForDomSettleClick } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
+          await waitForDomSettleClick({ timeoutMs: 3e3, debounceMs: 300 });
+          return { result: "clicked" };
+        }
+        if (action.type === "fill_input") {
+          const targetEl = await resolveTargetElement2(action.params, currentStep);
+          if (!targetEl) {
+            throw new Error(
+              `fill_input target not found (${action.params?.uid || action.params?.testId || action.params?.fingerprint || action.params?.textContaining || currentStep?.element?.testId || currentStep?.element?.fingerprint || currentStep?.element?.textContaining || "unknown target"})`
+            );
           }
-          if (action.type === "end_tour") {
-            handleTourEnd();
-            return { result: "ended" };
+          const value = typeof action.params?.value === "string" ? action.params.value : "";
+          batchPreferredWaitTarget = resolveWaitTargetElement(targetEl);
+          await performInteractiveFill(targetEl, value);
+          return { result: value };
+        }
+        if (action.type === "take_screenshot") {
+          const html2canvasModule = await import("html2canvas");
+          const html2canvas2 = html2canvasModule.default;
+          const canvas = await html2canvas2(document.body, {
+            useCORS: true,
+            allowTaint: true,
+            scale: Math.min(window.devicePixelRatio, 2),
+            width: window.innerWidth,
+            height: window.innerHeight,
+            x: window.scrollX,
+            y: window.scrollY,
+            logging: false
+          });
+          return { result: canvas.toDataURL("image/png") };
+        }
+        if (action.type === "navigate_to_url") {
+          const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
+          if (!nextUrl) {
+            throw new Error("navigate_to_url missing url");
           }
-          console.warn("[TourClient] Unknown action type:", action?.type, "- skipping");
-          return { result: "unknown_action_skipped" };
-        };
-        try {
-          const resultsBuffer = new Array(payload.commands.length);
-          const pendingUIActions = [];
-          for (let commandIndex = 0; commandIndex < payload.commands.length; commandIndex += 1) {
-            const command = payload.commands[commandIndex];
-            assertNotInterrupted();
-            const isTerminal = isTerminalAction(command);
-            if (isTerminal) {
-              await Promise.all(pendingUIActions);
-              pendingUIActions.length = 0;
-            }
-            const executionPromise = (async () => {
-              const execution = await executeOne(command);
-              await execution.settlePromise;
-              resultsBuffer[commandIndex] = { type: command.type, success: true, result: execution.result };
-            })();
-            if (isTerminal) {
-              await executionPromise;
-            } else {
-              pendingUIActions.push(executionPromise);
-            }
+          await navigateToTourUrl(nextUrl);
+          const { waitForDomSettle: waitForDomSettleNav } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
+          await waitForDomSettleNav({ timeoutMs: 3e3, debounceMs: 300 });
+          return { result: nextUrl };
+        }
+        if (action.type === "execute_agent_action") {
+          const agentSocketId = socketIdRef.current ?? socketRef.current?.id;
+          if (!agentSocketId) {
+            throw new Error("No socketId available for execute_agent_action");
           }
-          await Promise.all(pendingUIActions);
-          resultsBuffer.forEach((res) => {
-            if (res) results.push(res);
+          const url = getAgentCommandUrl(serverUrl, commandUrlRef.current);
+          const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              command: action.params?.command,
+              socketId: agentSocketId
+            })
           });
-          await syncAOM();
-        } catch (err) {
-          commandInFlightRef.current = false;
-          const interrupted = err?.code === "INTERRUPTED" || String(err) === "Error: interrupted";
-          if (interrupted) {
-            if (reviewModeRef.current && activeTourId && activePreviewRunId) {
-              void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
-                stepOrder: stepIndexRef.current,
-                eventType: "command_batch_interrupted",
-                payload: {
-                  commandBatchId,
-                  partialResults: results
-                },
-                currentStepOrder: stepIndexRef.current
-              });
-            }
-            emitIfOpen("tour:action_result", {
-              success: true,
-              interrupted: true,
-              results,
-              commandBatchId,
-              runId: runIdRef.current,
-              turnId: turnIdRef.current
-            });
-            clearCommandBatchId();
-            return;
+          if (!res.ok) {
+            throw new Error(`execute_agent_action failed: ${await res.text()}`);
           }
-          console.error("[TourClient] Command batch execution failed:", err);
-          if (reviewModeRef.current && activeTourId && activePreviewRunId) {
-            void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
-              stepOrder: stepIndexRef.current,
-              eventType: "command_batch_failed",
-              payload: {
-                commandBatchId,
-                error: String(err),
-                partialResults: results
-              },
-              status: "active",
-              currentStepOrder: stepIndexRef.current
-            });
+          if (action.params?.wait !== false) {
+            await res.json();
           }
-          emitIfOpen("tour:action_result", {
-            success: false,
-            reason: "execution_error",
-            error: String(err),
-            results,
-            commandBatchId,
-            runId: runIdRef.current,
-            turnId: turnIdRef.current
-          });
-          clearCommandBatchId();
-          return;
+          const { waitForDomSettle: waitForDomSettle2 } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
+          await waitForDomSettle2({ timeoutMs: 3e3, debounceMs: 300 });
+          await syncAOM();
+          return { result: action.params?.command ?? "executed" };
         }
-        commandInFlightRef.current = false;
-        if (shouldWait && !skipRequestedRef.current) {
-          const currentStep = tourRef.current?.steps?.[stepIndexRef.current] ?? null;
-          const waitCondition = currentStep?.onboarding?.waitCondition;
-          const waitTargetHints = waitCondition?.target ?? currentStep?.onboarding?.waitTarget ?? currentStep?.element;
-          const waitEvent = waitCondition?.event ?? currentStep?.onboarding?.expectedUserAction ?? "input";
-          const inputLikeWait = isInputLikeWait(waitEvent, currentStep);
-          let manualWaitPromise = null;
-          let manualWaitKind = null;
-          const highlightedWaitTarget = lastHighlightTarget ? resolveWaitTargetElement(lastHighlightTarget) : null;
-          const preferredWaitTarget = inputLikeWait ? batchPreferredWaitTarget ?? highlightedWaitTarget : highlightedWaitTarget;
-          runCleanup(pendingManualWaitCleanupRef.current);
-          pendingManualWaitCleanupRef.current = null;
-          if (waitTargetHints) {
-            let manualWaitTarget = await resolveTargetElement2(waitTargetHints, currentStep);
-            if (inputLikeWait && preferredWaitTarget && manualWaitTarget && manualWaitTarget !== preferredWaitTarget && !isEditableWaitTarget(manualWaitTarget) && isEditableWaitTarget(preferredWaitTarget)) {
-              manualWaitTarget = preferredWaitTarget;
-              console.log("[TourClient] wait_for_input: preferring current editable target over hinted step target", manualWaitTarget);
-            }
-            if (manualWaitTarget) {
-              const manualWait = createManualWaitForTarget(manualWaitTarget, waitEvent, currentStep);
-              manualWaitPromise = manualWait.promise;
-              manualWaitKind = manualWait.kind;
-              pendingManualWaitCleanupRef.current = manualWait.cleanup;
-            }
+        if (action.type === "wait_for_user_action") {
+          const targetEl = await resolveTargetElement2(action.params, currentStep);
+          if (!targetEl) {
+            throw new Error("wait_for_user_action target not found");
           }
-          if (!manualWaitPromise && preferredWaitTarget) {
-            const manualWait = createManualWaitForTarget(preferredWaitTarget, waitEvent, currentStep);
-            manualWaitPromise = manualWait.promise;
-            manualWaitKind = manualWait.kind;
-            pendingManualWaitCleanupRef.current = manualWait.cleanup;
-            console.log("[TourClient] wait_for_input: using current editable target as fallback wait target", preferredWaitTarget);
+          const eventName = action.params?.event ?? "click";
+          await waitForUserAction(targetEl, eventName);
+          return { result: `waited_for_${eventName}` };
+        }
+        if (action.type === "wait_for_input") {
+          shouldWait = true;
+          return { result: "waiting_for_input" };
+        }
+        if (action.type === "end_tour") {
+          handleTourEnd();
+          return { result: "ended" };
+        }
+        console.warn("[TourClient] Unknown action type:", action?.type, "- skipping");
+        return { result: "unknown_action_skipped" };
+      };
+      try {
+        const resultsBuffer = new Array(payload.commands.length);
+        const pendingUIActions = [];
+        for (let commandIndex = 0; commandIndex < payload.commands.length; commandIndex += 1) {
+          const command = payload.commands[commandIndex];
+          assertNotInterrupted();
+          const isTerminal = isTerminalAction(command);
+          if (isTerminal) {
+            await Promise.all(pendingUIActions);
+            pendingUIActions.length = 0;
           }
-          if (!manualWaitPromise && inputLikeWait) {
-            const firstInput = document.querySelector(
-              'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), [contenteditable="true"], [role="textbox"]'
-            );
-            if (firstInput) {
-              const manualWait = createManualWaitForTarget(firstInput, waitEvent, currentStep);
-              manualWaitPromise = manualWait.promise;
-              manualWaitKind = manualWait.kind;
-              pendingManualWaitCleanupRef.current = manualWait.cleanup;
-              console.log("[TourClient] wait_for_input: no target found, falling back to first visible editable element", firstInput);
-            }
+          const executionPromise = (async () => {
+            const execution = await executeOne(command);
+            await execution.settlePromise;
+            resultsBuffer[commandIndex] = { type: command.type, success: true, result: execution.result };
+          })();
+          if (isTerminal) {
+            await executionPromise;
+          } else {
+            pendingUIActions.push(executionPromise);
           }
-          setPlaybackState(manualWaitKind ? "waiting_input" : "waiting_voice");
+        }
+        await Promise.all(pendingUIActions);
+        resultsBuffer.forEach((res) => {
+          if (res) results.push(res);
+        });
+        await syncAOM();
+      } catch (err) {
+        commandInFlightRef.current = false;
+        const interrupted = err?.code === "INTERRUPTED" || String(err) === "Error: interrupted";
+        if (interrupted) {
           if (reviewModeRef.current && activeTourId && activePreviewRunId) {
             void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
               stepOrder: stepIndexRef.current,
-              eventType: "waiting_for_input",
+              eventType: "command_batch_interrupted",
               payload: {
                 commandBatchId,
-                results
+                partialResults: results
               },
               currentStepOrder: stepIndexRef.current
             });
           }
           emitIfOpen("tour:action_result", {
             success: true,
-            waitingForInput: true,
+            interrupted: true,
             results,
             commandBatchId,
             runId: runIdRef.current,
             turnId: turnIdRef.current
           });
           clearCommandBatchId();
-          const voiceOrTextWaitPromise = new Promise((resolve) => {
-            if (pendingInputBufRef.current) {
-              const flushed = pendingInputBufRef.current;
-              pendingInputBufRef.current = null;
-              resolve(flushed);
-              return;
-            }
-            voiceInputResolveRef.current = (text) => {
-              voiceInputResolveRef.current = null;
-              resolve(text);
-            };
-          });
-          Promise.race([voiceOrTextWaitPromise, manualWaitPromise].filter(Boolean)).then(async (userText) => {
-            runCleanup(pendingManualWaitCleanupRef.current);
-            pendingManualWaitCleanupRef.current = null;
-            voiceInputResolveRef.current = null;
-            setPlaybackState("executing");
-            const transcript = userText.trim();
-            if (!transcript) {
-              return;
-            }
-            const { waitForDomSettle: waitForDomSettle2 } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
-            await waitForDomSettle2({ timeoutMs: 1500, debounceMs: 200 });
-            await syncAOM();
-            emitIfOpen("tour:user_input", {
-              transcript,
-              runId: runIdRef.current,
-              turnId: turnIdRef.current
-            });
-          });
           return;
         }
+        console.error("[TourClient] Command batch execution failed:", err);
         if (reviewModeRef.current && activeTourId && activePreviewRunId) {
           void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
             stepOrder: stepIndexRef.current,
-            eventType: "command_batch_completed",
+            eventType: "command_batch_failed",
             payload: {
               commandBatchId,
-              results
+              error: String(err),
+              partialResults: results
             },
+            status: "active",
             currentStepOrder: stepIndexRef.current
           });
         }
         emitIfOpen("tour:action_result", {
-          success: true,
+          success: false,
+          reason: "execution_error",
+          error: String(err),
           results,
           commandBatchId,
           runId: runIdRef.current,
           turnId: turnIdRef.current
         });
         clearCommandBatchId();
-      });
-      socket.on("tour:start", async (tourData) => {
-        if (isActiveRef.current) return;
-        runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
-        const tour = tourData.tourContext ?? tourRef.current;
-        const expType = experienceTypeRef.current;
-        if (tour?.type && tour.type !== expType) {
-          console.log(`[TourClient] Ignoring ${tour.type} start (this hook is for ${expType})`);
-          return;
+        return;
+      }
+      commandInFlightRef.current = false;
+      if (shouldWait && !skipRequestedRef.current) {
+        const currentStep = tourRef.current?.steps?.[stepIndexRef.current] ?? null;
+        const waitCondition = currentStep?.onboarding?.waitCondition;
+        const waitTargetHints = waitCondition?.target ?? currentStep?.onboarding?.waitTarget ?? currentStep?.element;
+        const waitEvent = waitCondition?.event ?? currentStep?.onboarding?.expectedUserAction ?? "input";
+        const inputLikeWait = isInputLikeWait(waitEvent, currentStep);
+        let manualWaitPromise = null;
+        let manualWaitKind = null;
+        const highlightedWaitTarget = lastHighlightTarget ? resolveWaitTargetElement(lastHighlightTarget) : null;
+        const preferredWaitTarget = inputLikeWait ? batchPreferredWaitTarget ?? highlightedWaitTarget : highlightedWaitTarget;
+        runCleanup(pendingManualWaitCleanupRef.current);
+        pendingManualWaitCleanupRef.current = null;
+        if (waitTargetHints) {
+          let manualWaitTarget = await resolveTargetElement2(waitTargetHints, currentStep);
+          if (inputLikeWait && preferredWaitTarget && manualWaitTarget && manualWaitTarget !== preferredWaitTarget && !isEditableWaitTarget(manualWaitTarget) && isEditableWaitTarget(preferredWaitTarget)) {
+            manualWaitTarget = preferredWaitTarget;
+            console.log("[TourClient] wait_for_input: preferring current editable target over hinted step target", manualWaitTarget);
+          }
+          if (manualWaitTarget) {
+            const manualWait = createManualWaitForTarget(manualWaitTarget, waitEvent, currentStep);
+            manualWaitPromise = manualWait.promise;
+            manualWaitKind = manualWait.kind;
+            pendingManualWaitCleanupRef.current = manualWait.cleanup;
+          }
+        }
+        if (!manualWaitPromise && preferredWaitTarget) {
+          const manualWait = createManualWaitForTarget(preferredWaitTarget, waitEvent, currentStep);
+          manualWaitPromise = manualWait.promise;
+          manualWaitKind = manualWait.kind;
+          pendingManualWaitCleanupRef.current = manualWait.cleanup;
+          console.log("[TourClient] wait_for_input: using current editable target as fallback wait target", preferredWaitTarget);
         }
-        skipRequestedRef.current = false;
-        const total = tourData.totalSteps ?? tour?.steps?.length ?? 0;
-        isActiveRef.current = true;
-        setIsActive(true);
-        setActiveTour(tour ?? null);
-        tourRef.current = tour ?? null;
-        setTotalSteps(total);
-        stepIndexRef.current = 0;
-        setCurrentStepIndex(0);
-        setPlaybackState("intro");
-        if (reviewModeRef.current && tour?.id && previewRunIdRef.current) {
-          void logPreviewEvent(serverUrl, toursApiBaseRef.current, tour.id, previewRunIdRef.current, websiteId, {
-            stepOrder: 0,
-            eventType: "tour_started",
+        if (!manualWaitPromise && inputLikeWait) {
+          const firstInput = document.querySelector(
+            'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), [contenteditable="true"], [role="textbox"]'
+          );
+          if (firstInput) {
+            const manualWait = createManualWaitForTarget(firstInput, waitEvent, currentStep);
+            manualWaitPromise = manualWait.promise;
+            manualWaitKind = manualWait.kind;
+            pendingManualWaitCleanupRef.current = manualWait.cleanup;
+            console.log("[TourClient] wait_for_input: no target found, falling back to first visible editable element", firstInput);
+          }
+        }
+        setPlaybackState(manualWaitKind ? "waiting_input" : "waiting_voice");
+        if (reviewModeRef.current && activeTourId && activePreviewRunId) {
+          void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
+            stepOrder: stepIndexRef.current,
+            eventType: "waiting_for_input",
             payload: {
-              totalSteps: total,
-              source: "sdk_test_preview"
+              commandBatchId,
+              results
             },
-            currentStepOrder: 0
+            currentStepOrder: stepIndexRef.current
           });
         }
-        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", {
-              url: window.location.pathname + window.location.search + window.location.hash,
-              aom: aom.nodes,
-              domSummary: captureDomSummary()
-            });
+        emitIfOpen("tour:action_result", {
+          success: true,
+          waitingForInput: true,
+          results,
+          commandBatchId,
+          runId: runIdRef.current,
+          turnId: turnIdRef.current
+        });
+        clearCommandBatchId();
+        const voiceOrTextWaitPromise = new Promise((resolve) => {
+          if (pendingInputBufRef.current) {
+            const flushed = pendingInputBufRef.current;
+            pendingInputBufRef.current = null;
+            resolve(flushed);
+            return;
           }
-        } catch (e) {
-          console.warn("[TourClient] Initial DOM sync failed:", e);
-        }
+          voiceInputResolveRef.current = (text) => {
+            voiceInputResolveRef.current = null;
+            resolve(text);
+          };
+        });
+        Promise.race([voiceOrTextWaitPromise, manualWaitPromise].filter(Boolean)).then(async (userText) => {
+          runCleanup(pendingManualWaitCleanupRef.current);
+          pendingManualWaitCleanupRef.current = null;
+          voiceInputResolveRef.current = null;
+          setPlaybackState("executing");
+          const transcript = userText.trim();
+          if (!transcript) {
+            return;
+          }
+          const { waitForDomSettle: waitForDomSettle2 } = await Promise.resolve().then(() => (init_dom_sync(), dom_sync_exports));
+          await waitForDomSettle2({ timeoutMs: 1500, debounceMs: 200 });
+          await syncAOM();
+          emitIfOpen("tour:user_input", {
+            transcript,
+            runId: runIdRef.current,
+            turnId: turnIdRef.current
+          });
+        });
+        return;
+      }
+      if (reviewModeRef.current && activeTourId && activePreviewRunId) {
+        void logPreviewEvent(serverUrl, toursApiBaseRef.current, activeTourId, activePreviewRunId, websiteId, {
+          stepOrder: stepIndexRef.current,
+          eventType: "command_batch_completed",
+          payload: {
+            commandBatchId,
+            results
+          },
+          currentStepOrder: stepIndexRef.current
+        });
+      }
+      emitIfOpen("tour:action_result", {
+        success: true,
+        results,
+        commandBatchId,
+        runId: runIdRef.current,
+        turnId: turnIdRef.current
       });
-      socket.on("tour:update", (payload) => {
-        const updatedTour = payload?.tourContext;
-        if (!updatedTour?.id || updatedTour.id !== tourRef.current?.id) {
-          return;
+      clearCommandBatchId();
+    };
+    const handleTourStart = async (tourData) => {
+      if (isActiveRef.current) return;
+      runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
+      const tour = tourData.tourContext ?? tourRef.current;
+      const expType = experienceTypeRef.current;
+      if (tour?.type && tour.type !== expType) {
+        console.log(`[TourClient] Ignoring ${tour.type} start (this hook is for ${expType})`);
+        return;
+      }
+      skipRequestedRef.current = false;
+      const total = tourData.totalSteps ?? tour?.steps?.length ?? 0;
+      isActiveRef.current = true;
+      setIsActive(true);
+      setActiveTour(tour ?? null);
+      tourRef.current = tour ?? null;
+      setTotalSteps(total);
+      stepIndexRef.current = 0;
+      setCurrentStepIndex(0);
+      setPlaybackState("intro");
+      if (reviewModeRef.current && tour?.id && previewRunIdRef.current) {
+        void logPreviewEvent(serverUrl, toursApiBaseRef.current, tour.id, previewRunIdRef.current, websiteId, {
+          stepOrder: 0,
+          eventType: "tour_started",
+          payload: {
+            totalSteps: total,
+            source: "sdk_test_preview"
+          },
+          currentStepOrder: 0
+        });
+      }
+      try {
+        const { generateMinifiedAOM: generateMinifiedAOM2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
+        const aom = generateMinifiedAOM2();
+        if (socketRef.current === socket) {
+          emitSocketEvent(socket, "tour:sync_dom", {
+            url: window.location.pathname + window.location.search + window.location.hash,
+            aom: aom.nodes,
+            domSummary: captureDomSummary()
+          });
         }
-        tourRef.current = updatedTour;
-        setActiveTour(updatedTour);
-        const nextTotal = payload.totalSteps ?? updatedTour.steps?.length ?? 0;
-        setTotalSteps(nextTotal);
-        if (typeof payload.currentStepIndex === "number") {
-          const clampedStepIndex = Math.max(0, Math.min(payload.currentStepIndex, Math.max(0, nextTotal - 1)));
-          stepIndexRef.current = clampedStepIndex;
-          setCurrentStepIndex(clampedStepIndex);
-          if (nextTotal > 0) {
-            onStepChangeRef.current?.(clampedStepIndex, nextTotal, updatedTour);
-          }
+      } catch (e) {
+        console.warn("[TourClient] Initial DOM sync failed:", e);
+      }
+    };
+    const handleTourUpdate = (payload) => {
+      const updatedTour = payload?.tourContext;
+      if (!updatedTour?.id || updatedTour.id !== tourRef.current?.id) {
+        return;
+      }
+      tourRef.current = updatedTour;
+      setActiveTour(updatedTour);
+      const nextTotal = payload.totalSteps ?? updatedTour.steps?.length ?? 0;
+      setTotalSteps(nextTotal);
+      if (typeof payload.currentStepIndex === "number") {
+        const clampedStepIndex = Math.max(0, Math.min(payload.currentStepIndex, Math.max(0, nextTotal - 1)));
+        stepIndexRef.current = clampedStepIndex;
+        setCurrentStepIndex(clampedStepIndex);
+        if (nextTotal > 0) {
+          onStepChangeRef.current?.(clampedStepIndex, nextTotal, updatedTour);
         }
-      });
-      socket.on("tour:end", () => {
-        setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
-        handleTourEnd();
-      });
-      socket.on("tour:debug_log", (entry) => {
-        const isDev = devModeRef.current || process.env.NODE_ENV === "development" || typeof window !== "undefined" && window.MODELNEX_DEBUG;
-        if (isDev) {
-          console.log(`%c[ModelNex Tour] ${entry.type}`, "color: #3b82f6; font-weight: bold", entry);
-          if (typeof window !== "undefined") {
-            window.dispatchEvent(new CustomEvent("modelnex-debug", {
-              detail: { msg: `[Tour Timeline] ${entry.type}`, data: entry }
-            }));
-          }
+      }
+    };
+    const handleTourEndEvent = () => {
+      setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
+      handleTourEnd();
+    };
+    const handleDebugLog = (entry) => {
+      const isDev = devModeRef.current || process.env.NODE_ENV === "development" || typeof window !== "undefined" && window.MODELNEX_DEBUG;
+      if (isDev) {
+        console.log(`%c[ModelNex Tour] ${entry.type}`, "color: #3b82f6; font-weight: bold", entry);
+        if (typeof window !== "undefined") {
+          window.dispatchEvent(new CustomEvent("modelnex-debug", {
+            detail: { msg: `[Tour Timeline] ${entry.type}`, data: entry }
+          }));
         }
-      });
-      console.log("[ModelNex SDK] Tour playback initialized. Debug logs enabled:", devModeRef.current || process.env.NODE_ENV === "development");
-    });
-    return () => {
-      cancelled = true;
-      const toClose = createdSocket ?? socketRef.current;
-      if (toClose) {
-        toClose.disconnect();
       }
-      createdSocket = null;
+    };
+    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 () => {
+      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;
-    s.emit("tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+    if (!websiteId || !profile?.userId) return;
+    const timer = setTimeout(() => {
+      emitSocketEvent(s, "tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+    }, 150);
+    return () => clearTimeout(timer);
   }, [disabled, websiteId, userProfile?.userId, userProfile?.type]);
   (0, import_react12.useEffect)(() => {
     if (!showCaptions || !isReviewMode) {
@@ -3846,8 +3918,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,
@@ -3860,17 +3932,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();
-    socketRef.current.emit("tour:sync_dom", {
+    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;
@@ -3878,21 +3950,22 @@ function useTourPlayback({
     removeHighlight();
     removeCaption();
     voice.stopSpeaking();
-    socketRef.current.emit("tour:action_result", {
+    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", {
-      transcript,
-      interrupted: true,
-      runId: runIdRef.current,
-      turnId: turnIdRef.current
-    });
+    })) {
+      activeCommandBatchIdRef.current = null;
+      emitSocketEvent(socketRef.current, "tour:user_input", {
+        transcript,
+        interrupted: true,
+        runId: runIdRef.current,
+        turnId: turnIdRef.current
+      });
+    }
     setPlaybackState("thinking");
     return true;
   }, [voice]);
@@ -3908,9 +3981,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,
@@ -3982,7 +4053,7 @@ 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;
     }
@@ -4010,7 +4081,7 @@ function useTourPlayback({
       previewRunIdRef.current = null;
     }
     tourRef.current = tour;
-    socketRef.current.emit("tour:request_start", {
+    emitSocketEvent(socketRef.current, "tour:request_start", {
       tourId: tour.id,
       previewRunId: previewRunIdRef.current,
       tourContext: tour
@@ -4158,8 +4229,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) {
@@ -4183,14 +4254,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");
     }
   }, []);
@@ -4212,9 +4283,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
@@ -5462,7 +5533,7 @@ function useVoice(serverUrl) {
       (async () => {
         try {
           const ioModule = await import("socket.io-client");
-          const io2 = ioModule.default || ioModule;
+          const io3 = ioModule.default || ioModule;
           const stream = await navigator.mediaDevices.getUserMedia({
             audio: {
               echoCancellation: true,
@@ -5484,7 +5555,7 @@ function useVoice(serverUrl) {
             audioBitsPerSecond: 128e3
           });
           mediaRecorderRef.current = recorder;
-          const socket = io2(serverUrl, {
+          const socket = io3(serverUrl, {
             path: "/socket.io",
             transports: resolveSocketIoTransports(serverUrl, "websocket-first")
           });
@@ -11005,7 +11076,7 @@ var ModelNexProvider = ({
       socketId,
       devMode
     }),
-    [serverUrl, commandUrl, registerAction, unregisterAction, activeAgentActions, stagingFields, highlightActions, studioMode, recordingMode, extractedElements, tagStore, chatMessages, websiteId, userProfile, toursApiBase, voiceMuted, socketId, devMode]
+    [serverUrl, commandUrl, registerAction, unregisterAction, activeAgentActions, stagingFields, highlightActions, studioMode, recordingMode, extractedElements, tagStore, chatMessages, websiteId, userProfile?.userId, userProfile?.type, userProfile?.isNewUser, toursApiBase, voiceMuted, socketId, devMode]
   );
   return import_react21.default.createElement(
     ModelNexContext.Provider,