@modelnex/sdk 0.5.42 → 0.5.44

package/dist/index.js

@@ -2041,7 +2041,18 @@ var import_zod2 = require("zod");
 
 // src/utils/screenshot.ts
 var import_html2canvas = __toESM(require("html2canvas"));
-async function captureScreenshot(selector) {
+var SCREENSHOT_SCALE_BY_RESOLUTION = {
+  low: 0.75,
+  medium: 1.25,
+  high: 2
+};
+function normalizeScreenshotResolution(resolution) {
+  return resolution === "low" || resolution === "high" || resolution === "medium" ? resolution : "medium";
+}
+function resolveScreenshotScale(resolution) {
+  return SCREENSHOT_SCALE_BY_RESOLUTION[normalizeScreenshotResolution(resolution)];
+}
+async function captureScreenshot(selector, resolution) {
   const target = selector ? document.querySelector(selector) : document.documentElement;
   if (!target || !(target instanceof HTMLElement)) {
     throw new Error(`Screenshot target not found: ${selector ?? "document"}`);
@@ -2049,7 +2060,7 @@ async function captureScreenshot(selector) {
   const canvas = await (0, import_html2canvas.default)(target, {
     useCORS: true,
     allowTaint: true,
-    scale: Math.min(window.devicePixelRatio, 2),
+    scale: resolveScreenshotScale(resolution),
     width: window.innerWidth,
     height: window.innerHeight,
     x: window.scrollX,
@@ -2512,14 +2523,15 @@ async function resolveWorkflowFromInput(getters, params) {
   return { workflow: ranked[0].workflow };
 }
 var screenshotSchema = import_zod2.z.object({
-  selector: import_zod2.z.string().optional().describe("Optional CSS selector to capture a specific element. Omit to capture the full viewport.")
+  selector: import_zod2.z.string().optional().describe("Optional CSS selector to capture a specific element. Omit to capture the full viewport."),
+  resolution: import_zod2.z.enum(["low", "medium", "high"]).optional().describe("Optional screenshot resolution. Use low for smaller/faster captures, medium for the default balance, or high for extra detail.")
 });
 var BUILTIN_SCREENSHOT_ACTION = {
   id: "take_screenshot",
   description: "Take a screenshot of the current page (or a specific element via CSS selector). Returns a base64 PNG image. Use when you need to see the current UI state, verify a visual change, or when the user asks you to look at the screen.",
   schema: screenshotSchema,
   execute: async (params) => {
-    return await captureScreenshot(params.selector);
+    return await captureScreenshot(params.selector, params.resolution);
   }
 };
 var clickElementSchema = import_zod2.z.object({
@@ -3529,6 +3541,54 @@ function compactTourForTransport(tour) {
   };
 }
 
+// src/utils/tourSessionPersistence.ts
+var ACTIVE_TOUR_SESSION_STORAGE_KEY = "modelnex-active-tour-session";
+var ACTIVE_TOUR_SESSION_VERSION = 1;
+var ACTIVE_TOUR_SESSION_MAX_AGE_MS = 10 * 60 * 1e3;
+function canUseSessionStorage2() {
+  return typeof window !== "undefined" && typeof window.sessionStorage !== "undefined";
+}
+function persistActiveTourSession(runId) {
+  if (!canUseSessionStorage2() || !Number.isFinite(runId)) return;
+  const session = {
+    version: ACTIVE_TOUR_SESSION_VERSION,
+    runId,
+    savedAt: Date.now()
+  };
+  try {
+    window.sessionStorage.setItem(ACTIVE_TOUR_SESSION_STORAGE_KEY, JSON.stringify(session));
+  } catch {
+  }
+}
+function clearPersistedActiveTourSession() {
+  if (!canUseSessionStorage2()) return;
+  try {
+    window.sessionStorage.removeItem(ACTIVE_TOUR_SESSION_STORAGE_KEY);
+  } catch {
+  }
+}
+function readPersistedActiveTourSession() {
+  if (!canUseSessionStorage2()) return null;
+  try {
+    const raw = window.sessionStorage.getItem(ACTIVE_TOUR_SESSION_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    const isValid = parsed && parsed.version === ACTIVE_TOUR_SESSION_VERSION && typeof parsed.runId === "number" && Number.isFinite(parsed.runId) && typeof parsed.savedAt === "number" && Number.isFinite(parsed.savedAt);
+    if (!isValid) {
+      clearPersistedActiveTourSession();
+      return null;
+    }
+    if (Date.now() - parsed.savedAt > ACTIVE_TOUR_SESSION_MAX_AGE_MS) {
+      clearPersistedActiveTourSession();
+      return null;
+    }
+    return parsed;
+  } catch {
+    clearPersistedActiveTourSession();
+    return null;
+  }
+}
+
 // src/hooks/useTourPlayback.ts
 init_editable_controls();
 
@@ -4143,7 +4203,8 @@ function useTourPlayback({
   const pendingTourRef = (0, import_react12.useRef)(null);
   const pendingTourOptionsRef = (0, import_react12.useRef)(null);
   const showCaptionsRef = (0, import_react12.useRef)(showCaptions);
-  const runIdRef = (0, import_react12.useRef)(null);
+  const initialPersistedTourSessionRef = (0, import_react12.useRef)(readPersistedActiveTourSession());
+  const runIdRef = (0, import_react12.useRef)(initialPersistedTourSessionRef.current?.runId ?? null);
   const turnIdRef = (0, import_react12.useRef)(null);
   const startRequestedRef = (0, import_react12.useRef)(false);
   const playbackOwnerIdRef = (0, import_react12.useRef)(`playback-owner-${Math.random().toString(36).slice(2, 10)}`);
@@ -4171,6 +4232,19 @@ function useTourPlayback({
     releaseTourPlaybackOwnership(claimedKey, playbackOwnerIdRef.current);
     claimedPlaybackOwnerKeyRef.current = null;
   }, []);
+  const emitTourInit = (0, import_react12.useCallback)((socket, currentWebsiteId, profile) => {
+    if (!currentWebsiteId || !profile?.type) return;
+    const persistedRunId = runIdRef.current ?? readPersistedActiveTourSession()?.runId ?? null;
+    const payload = {
+      websiteId: currentWebsiteId,
+      userId: profile.userId,
+      userType: profile.type
+    };
+    if (typeof persistedRunId === "number") {
+      payload.resumeRunId = persistedRunId;
+    }
+    emitSocketEvent(socket, "tour:init", payload);
+  }, []);
   (0, import_react12.useEffect)(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
@@ -4182,9 +4256,7 @@ function useTourPlayback({
       }, { devMode: devModeRef.current });
       const profile = userProfileRef.current;
       const currentWebsiteId = websiteIdRef.current;
-      if (currentWebsiteId && profile?.userId) {
-        emitSocketEvent(socket, "tour:init", { websiteId: currentWebsiteId, userId: profile.userId, userType: profile.type });
-      }
+      emitTourInit(socket, currentWebsiteId, profile);
     };
     const handleServerState = (payload) => {
       if (typeof payload?.runId === "number") {
@@ -4193,6 +4265,11 @@ function useTourPlayback({
       if (typeof payload?.turnId === "string" || payload?.turnId === null) {
         turnIdRef.current = payload.turnId ?? null;
       }
+      if (payload?.isActive && typeof payload?.runId === "number") {
+        persistActiveTourSession(payload.runId);
+      } else if (payload?.isActive === false) {
+        clearPersistedActiveTourSession();
+      }
       setServerState(payload);
     };
     const handleCommandCancel = (payload) => {
@@ -4456,19 +4533,9 @@ function useTourPlayback({
           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") };
+          const selector = typeof action.params?.selector === "string" ? action.params.selector : void 0;
+          const resolution = typeof action.params?.resolution === "string" ? action.params.resolution : void 0;
+          return { result: await captureScreenshot(selector, resolution) };
         }
         if (action.type === "navigate_to_url") {
           const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
@@ -4760,6 +4827,9 @@ function useTourPlayback({
     const handleTourStart = async (tourData) => {
       if (isActiveRef.current) return;
       runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
+      if (typeof runIdRef.current === "number") {
+        persistActiveTourSession(runIdRef.current);
+      }
       const tour = tourData.tourContext ?? tourRef.current;
       const expType = experienceTypeRef.current;
       if (tour?.type && tour.type !== expType) {
@@ -4835,6 +4905,7 @@ function useTourPlayback({
       }
     };
     const handleTourEndEvent = () => {
+      clearPersistedActiveTourSession();
       setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
       handleTourEnd();
     };
@@ -4884,17 +4955,17 @@ function useTourPlayback({
       releasePlaybackOwnership();
       tourSocketPool.release(serverUrl, toClose);
     };
-  }, [serverUrl, disabled, releasePlaybackOwnership]);
+  }, [serverUrl, disabled, emitTourInit, releasePlaybackOwnership]);
   (0, import_react12.useEffect)(() => {
     if (disabled) return;
     const s = socketRef.current;
     const profile = userProfile;
-    if (!websiteId || !profile?.userId) return;
+    if (!websiteId || !profile?.type) return;
     const timer = setTimeout(() => {
-      emitSocketEvent(s, "tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+      emitTourInit(s, websiteId, profile);
     }, 150);
     return () => clearTimeout(timer);
-  }, [disabled, websiteId, userProfile?.userId, userProfile?.type]);
+  }, [disabled, emitTourInit, websiteId, userProfile?.userId, userProfile?.type]);
   (0, import_react12.useEffect)(() => {
     if (!showCaptions || !isReviewMode) {
       removeCaption();
@@ -5013,6 +5084,7 @@ function useTourPlayback({
     tourRef.current = null;
     setPlaybackState("idle");
     setServerState(null);
+    clearPersistedActiveTourSession();
     runIdRef.current = null;
     turnIdRef.current = null;
     setPreviewRunId(null);
@@ -5042,6 +5114,7 @@ function useTourPlayback({
     tourRef.current = null;
     setPlaybackState("idle");
     setServerState(null);
+    clearPersistedActiveTourSession();
     runIdRef.current = null;
     turnIdRef.current = null;
     setPreviewRunId(null);

package/dist/index.mjs

@@ -1667,7 +1667,18 @@ import { z as z2 } from "zod";
 
 // src/utils/screenshot.ts
 import html2canvas from "html2canvas";
-async function captureScreenshot(selector) {
+var SCREENSHOT_SCALE_BY_RESOLUTION = {
+  low: 0.75,
+  medium: 1.25,
+  high: 2
+};
+function normalizeScreenshotResolution(resolution) {
+  return resolution === "low" || resolution === "high" || resolution === "medium" ? resolution : "medium";
+}
+function resolveScreenshotScale(resolution) {
+  return SCREENSHOT_SCALE_BY_RESOLUTION[normalizeScreenshotResolution(resolution)];
+}
+async function captureScreenshot(selector, resolution) {
   const target = selector ? document.querySelector(selector) : document.documentElement;
   if (!target || !(target instanceof HTMLElement)) {
     throw new Error(`Screenshot target not found: ${selector ?? "document"}`);
@@ -1675,7 +1686,7 @@ async function captureScreenshot(selector) {
   const canvas = await html2canvas(target, {
     useCORS: true,
     allowTaint: true,
-    scale: Math.min(window.devicePixelRatio, 2),
+    scale: resolveScreenshotScale(resolution),
     width: window.innerWidth,
     height: window.innerHeight,
     x: window.scrollX,
@@ -2138,14 +2149,15 @@ async function resolveWorkflowFromInput(getters, params) {
   return { workflow: ranked[0].workflow };
 }
 var screenshotSchema = z2.object({
-  selector: z2.string().optional().describe("Optional CSS selector to capture a specific element. Omit to capture the full viewport.")
+  selector: z2.string().optional().describe("Optional CSS selector to capture a specific element. Omit to capture the full viewport."),
+  resolution: z2.enum(["low", "medium", "high"]).optional().describe("Optional screenshot resolution. Use low for smaller/faster captures, medium for the default balance, or high for extra detail.")
 });
 var BUILTIN_SCREENSHOT_ACTION = {
   id: "take_screenshot",
   description: "Take a screenshot of the current page (or a specific element via CSS selector). Returns a base64 PNG image. Use when you need to see the current UI state, verify a visual change, or when the user asks you to look at the screen.",
   schema: screenshotSchema,
   execute: async (params) => {
-    return await captureScreenshot(params.selector);
+    return await captureScreenshot(params.selector, params.resolution);
   }
 };
 var clickElementSchema = z2.object({
@@ -3155,6 +3167,54 @@ function compactTourForTransport(tour) {
   };
 }
 
+// src/utils/tourSessionPersistence.ts
+var ACTIVE_TOUR_SESSION_STORAGE_KEY = "modelnex-active-tour-session";
+var ACTIVE_TOUR_SESSION_VERSION = 1;
+var ACTIVE_TOUR_SESSION_MAX_AGE_MS = 10 * 60 * 1e3;
+function canUseSessionStorage2() {
+  return typeof window !== "undefined" && typeof window.sessionStorage !== "undefined";
+}
+function persistActiveTourSession(runId) {
+  if (!canUseSessionStorage2() || !Number.isFinite(runId)) return;
+  const session = {
+    version: ACTIVE_TOUR_SESSION_VERSION,
+    runId,
+    savedAt: Date.now()
+  };
+  try {
+    window.sessionStorage.setItem(ACTIVE_TOUR_SESSION_STORAGE_KEY, JSON.stringify(session));
+  } catch {
+  }
+}
+function clearPersistedActiveTourSession() {
+  if (!canUseSessionStorage2()) return;
+  try {
+    window.sessionStorage.removeItem(ACTIVE_TOUR_SESSION_STORAGE_KEY);
+  } catch {
+  }
+}
+function readPersistedActiveTourSession() {
+  if (!canUseSessionStorage2()) return null;
+  try {
+    const raw = window.sessionStorage.getItem(ACTIVE_TOUR_SESSION_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    const isValid = parsed && parsed.version === ACTIVE_TOUR_SESSION_VERSION && typeof parsed.runId === "number" && Number.isFinite(parsed.runId) && typeof parsed.savedAt === "number" && Number.isFinite(parsed.savedAt);
+    if (!isValid) {
+      clearPersistedActiveTourSession();
+      return null;
+    }
+    if (Date.now() - parsed.savedAt > ACTIVE_TOUR_SESSION_MAX_AGE_MS) {
+      clearPersistedActiveTourSession();
+      return null;
+    }
+    return parsed;
+  } catch {
+    clearPersistedActiveTourSession();
+    return null;
+  }
+}
+
 // src/utils/tour-playback-guards.ts
 var playbackOwners = /* @__PURE__ */ new Map();
 function shouldExecuteTourCommandBatch(isPlaybackActive) {
@@ -3766,7 +3826,8 @@ function useTourPlayback({
   const pendingTourRef = useRef8(null);
   const pendingTourOptionsRef = useRef8(null);
   const showCaptionsRef = useRef8(showCaptions);
-  const runIdRef = useRef8(null);
+  const initialPersistedTourSessionRef = useRef8(readPersistedActiveTourSession());
+  const runIdRef = useRef8(initialPersistedTourSessionRef.current?.runId ?? null);
   const turnIdRef = useRef8(null);
   const startRequestedRef = useRef8(false);
   const playbackOwnerIdRef = useRef8(`playback-owner-${Math.random().toString(36).slice(2, 10)}`);
@@ -3794,6 +3855,19 @@ function useTourPlayback({
     releaseTourPlaybackOwnership(claimedKey, playbackOwnerIdRef.current);
     claimedPlaybackOwnerKeyRef.current = null;
   }, []);
+  const emitTourInit = useCallback7((socket, currentWebsiteId, profile) => {
+    if (!currentWebsiteId || !profile?.type) return;
+    const persistedRunId = runIdRef.current ?? readPersistedActiveTourSession()?.runId ?? null;
+    const payload = {
+      websiteId: currentWebsiteId,
+      userId: profile.userId,
+      userType: profile.type
+    };
+    if (typeof persistedRunId === "number") {
+      payload.resumeRunId = persistedRunId;
+    }
+    emitSocketEvent(socket, "tour:init", payload);
+  }, []);
   useEffect11(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
@@ -3805,9 +3879,7 @@ function useTourPlayback({
       }, { devMode: devModeRef.current });
       const profile = userProfileRef.current;
       const currentWebsiteId = websiteIdRef.current;
-      if (currentWebsiteId && profile?.userId) {
-        emitSocketEvent(socket, "tour:init", { websiteId: currentWebsiteId, userId: profile.userId, userType: profile.type });
-      }
+      emitTourInit(socket, currentWebsiteId, profile);
     };
     const handleServerState = (payload) => {
       if (typeof payload?.runId === "number") {
@@ -3816,6 +3888,11 @@ function useTourPlayback({
       if (typeof payload?.turnId === "string" || payload?.turnId === null) {
         turnIdRef.current = payload.turnId ?? null;
       }
+      if (payload?.isActive && typeof payload?.runId === "number") {
+        persistActiveTourSession(payload.runId);
+      } else if (payload?.isActive === false) {
+        clearPersistedActiveTourSession();
+      }
       setServerState(payload);
     };
     const handleCommandCancel = (payload) => {
@@ -4079,19 +4156,9 @@ function useTourPlayback({
           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") };
+          const selector = typeof action.params?.selector === "string" ? action.params.selector : void 0;
+          const resolution = typeof action.params?.resolution === "string" ? action.params.resolution : void 0;
+          return { result: await captureScreenshot(selector, resolution) };
         }
         if (action.type === "navigate_to_url") {
           const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
@@ -4383,6 +4450,9 @@ function useTourPlayback({
     const handleTourStart = async (tourData) => {
       if (isActiveRef.current) return;
       runIdRef.current = typeof tourData.runId === "number" ? tourData.runId : runIdRef.current;
+      if (typeof runIdRef.current === "number") {
+        persistActiveTourSession(runIdRef.current);
+      }
       const tour = tourData.tourContext ?? tourRef.current;
       const expType = experienceTypeRef.current;
       if (tour?.type && tour.type !== expType) {
@@ -4458,6 +4528,7 @@ function useTourPlayback({
       }
     };
     const handleTourEndEvent = () => {
+      clearPersistedActiveTourSession();
       setServerState((prev) => prev ? { ...prev, isActive: false, phase: "completed" } : prev);
       handleTourEnd();
     };
@@ -4507,17 +4578,17 @@ function useTourPlayback({
       releasePlaybackOwnership();
       tourSocketPool.release(serverUrl, toClose);
     };
-  }, [serverUrl, disabled, releasePlaybackOwnership]);
+  }, [serverUrl, disabled, emitTourInit, releasePlaybackOwnership]);
   useEffect11(() => {
     if (disabled) return;
     const s = socketRef.current;
     const profile = userProfile;
-    if (!websiteId || !profile?.userId) return;
+    if (!websiteId || !profile?.type) return;
     const timer = setTimeout(() => {
-      emitSocketEvent(s, "tour:init", { websiteId, userId: profile.userId, userType: profile.type });
+      emitTourInit(s, websiteId, profile);
     }, 150);
     return () => clearTimeout(timer);
-  }, [disabled, websiteId, userProfile?.userId, userProfile?.type]);
+  }, [disabled, emitTourInit, websiteId, userProfile?.userId, userProfile?.type]);
   useEffect11(() => {
     if (!showCaptions || !isReviewMode) {
       removeCaption();
@@ -4636,6 +4707,7 @@ function useTourPlayback({
     tourRef.current = null;
     setPlaybackState("idle");
     setServerState(null);
+    clearPersistedActiveTourSession();
     runIdRef.current = null;
     turnIdRef.current = null;
     setPreviewRunId(null);
@@ -4665,6 +4737,7 @@ function useTourPlayback({
     tourRef.current = null;
     setPlaybackState("idle");
     setServerState(null);
+    clearPersistedActiveTourSession();
     runIdRef.current = null;
     turnIdRef.current = null;
     setPreviewRunId(null);

package/package.json

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