safari-mcp 2.1.8 → 2.3.0

package/README.md

@@ -69,7 +69,12 @@
 npm install -g safari-mcp
 ```
 
-**Option B — from source:**
+**Option B — Homebrew:**
+```bash
+brew install achiya-automation/tap/safari-mcp
+```
+
+**Option C — from source:**
 ```bash
 git clone https://github.com/achiya-automation/safari-mcp.git
 cd safari-mcp
@@ -142,6 +147,29 @@ Add to your MCP client config:
 
 ---
 
+## Usage Workflow
+
+The recommended pattern for AI agents using Safari MCP:
+
+```
+1. safari_snapshot        → Get page state (accessibility tree)
+2. safari_click/fill/...  → Interact with elements by ref
+3. safari_snapshot        → Verify the result
+```
+
+**Element targeting** — tools accept multiple targeting strategies:
+
+| Strategy | Example | Best for |
+|----------|---------|----------|
+| CSS selector | `#login-btn`, `.submit` | Unique elements |
+| Visible text | `"Sign In"`, `"Submit"` | Buttons, links |
+| Coordinates | `x: 100, y: 200` | Canvas, custom widgets |
+| Ref from snapshot | `ref: "e42"` | Any element from accessibility tree |
+
+> **Tip:** Start with `safari_snapshot` to get element refs, then use refs for precise targeting. This is faster and more reliable than CSS selectors.
+
+---
+
 ## Tools (80)
 
 ### Navigation (4)
@@ -317,6 +345,20 @@ Add to your MCP client config:
 
 ---
 
+## Security
+
+Safari MCP runs locally on your Mac with minimal attack surface:
+
+| Aspect | Detail |
+|--------|--------|
+| Network | **No remote connections** — all communication is local (stdio + localhost) |
+| Permissions | macOS system permissions required (Screen Recording for screenshots) |
+| Data | No telemetry, no analytics, no data sent anywhere |
+| Extension | Communicates only with `localhost:9224`, validated by Safari |
+| Code | Fully open source (MIT) — audit every line |
+
+---
+
 ## Safari MCP vs Alternatives
 
 | Feature | Safari MCP | Chrome DevTools MCP | Playwright MCP |
@@ -335,6 +377,23 @@ Add to your MCP client config:
 
 > **Tip:** Use Safari MCP for daily browsing tasks (95% of work) and Chrome DevTools MCP only for Lighthouse/Performance audits.
 
+### Safari MCP Servers Comparison
+
+| Feature | **safari-mcp** | MCPSafari | safari-mcp-server |
+|---------|:--------------:|:---------:|:-----------------:|
+| Tools | **80** | 23 | ~10 |
+| License | **MIT** | None | MIT |
+| Install | npm / Homebrew | Binary | npm |
+| Storage (cookies, localStorage) | **10 tools** | None | None |
+| Data extraction (tables, links) | **5 tools** | None | None |
+| Network mocking | **Yes** | No | No |
+| Device emulation | **Yes** | No | No |
+| File upload (no dialog) | **Yes** | No | No |
+| PDF export | **Yes** | No | No |
+| Console capture | **4 tools** | 1 | No |
+| Performance metrics | **Yes** | No | No |
+| Fallback engine | **Dual (Extension + AppleScript)** | Extension only | WebDriver |
+
 ---
 
 ## Architecture

package/extension/background.js

@@ -957,7 +957,9 @@ async function handleCommand(type, payload) {
       // Learn profile window from newly created tab
       if (!_profileWindowId) { _profileWindowId = updated.windowId; browser.storage.local.set({ mcpProfileWindowId: _profileWindowId }).catch(() => {}); }
       // CRITICAL: Set new tab as the target for this session's subsequent commands
-      _setSessionTab(sessionId, updated.id, updated.url);
+      // Use the requested URL (not updated.url) when page hasn't loaded yet (still about:blank)
+      const trackUrl = (updated.url && updated.url !== "about:blank") ? updated.url : (payload.url || updated.url);
+      _setSessionTab(sessionId, updated.id, trackUrl);
       return { title: updated.title, url: updated.url, tabIndex: updated.index + 1 };
     }
 
@@ -1049,7 +1051,7 @@ async function handleCommand(type, payload) {
 
     // --- Snapshot (accessibility tree with ref IDs) ---
     case "snapshot": {
-      return await execInTab((rootSelector) => {
+      return await execInTab((rootSelector, snapshotGen) => {
         // Clean ALL stale data-mcp-ref attributes from previous snapshots.
         // Without this, old refs remain on DOM and findByRef/CSS selector can target WRONG elements.
         document.querySelectorAll("[data-mcp-ref]").forEach(function(el) { el.removeAttribute("data-mcp-ref"); });
@@ -1099,7 +1101,7 @@ async function handleCommand(type, payload) {
 
           const interactive = isInteractive(el);
           const currentId = id++;
-          const refId = "0_" + currentId;
+          const refId = snapshotGen + "_" + currentId;
 
           let attrs = "";
           if (interactive) {
@@ -1209,7 +1211,7 @@ async function handleCommand(type, payload) {
           tree += "\n[WARNING: Snapshot truncated at " + MAX_ELEMENTS + " elements. Use selector parameter to focus on a specific section.]";
         }
         return tree;
-      }, [payload.selector || null], tabId);
+      }, [payload.selector || null, payload.gen != null ? payload.gen : 0], tabId);
     }
 
     // --- Double Click ---
@@ -1768,15 +1770,26 @@ async function getActiveTab() {
   return tabs[0];
 }
 
+// Track which tabs already have the deep query helpers injected
+const _helpersInjected = new Set();
+// Clean up when tabs are removed or navigated
+browser.tabs.onRemoved.addListener((tabId) => { _helpersInjected.delete(tabId); });
+browser.tabs.onUpdated.addListener((tabId, changeInfo) => {
+  if (changeInfo.status === "loading") _helpersInjected.delete(tabId);
+});
+
 async function execInTab(func, args = [], tabId = null) {
   const id = tabId || (await getActiveTab()).id;
   try {
-    // Auto-inject deep query helpers (idempotent — only defines once per page)
-    await browser.scripting.executeScript({
-      target: { tabId: id },
-      world: "MAIN",
-      func: _deepQueryScript,
-    }).catch(() => {});
+    // Auto-inject deep query helpers — skip if already injected for this tab+page
+    if (!_helpersInjected.has(id)) {
+      await browser.scripting.executeScript({
+        target: { tabId: id },
+        world: "MAIN",
+        func: _deepQueryScript,
+      }).catch(() => {});
+      _helpersInjected.add(id);
+    }
 
     const results = await browser.scripting.executeScript({
       target: { tabId: id },
@@ -1812,7 +1825,13 @@ async function execInAllFrames(func, args = [], tabId = null) {
   }
 }
 
-function waitForTabLoad(tabId, timeout = 30000) {
+async function waitForTabLoad(tabId, timeout = 30000) {
+  // Check if already complete BEFORE registering listeners (prevents missing instant-complete events)
+  try {
+    const tab = await browser.tabs.get(tabId);
+    if (tab.status === "complete") return;
+  } catch { return; } // Tab already gone
+
   return new Promise((resolve) => {
     function cleanup() {
       clearTimeout(timer);

package/index.js

@@ -13,6 +13,9 @@ import { WebSocketServer } from "ws";
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // ========== SINGLETON: kill stale instances from previous sessions ==========
 // NOTE: Claude Code VSCode may start 2 instances simultaneously (~40ms apart).
@@ -66,11 +69,18 @@ function _untrackTab(tabIndex) {
 async function _cleanupTabs() {
   if (_openedTabs.size === 0) return;
   console.error(`[Safari MCP] Cleanup: closing ${_openedTabs.size} MCP-opened tabs`);
-  const indices = [..._openedTabs.keys()].sort((a, b) => b - a);
-  for (const idx of indices) {
+  // Close by URL (not index) — indices shift as tabs are closed
+  const urlsToClose = [..._openedTabs.values()].map(v => v.url).filter(Boolean);
+  for (const url of urlsToClose) {
     try {
-      safari.setActiveTabIndex(idx);
-      await safari.closeTab();
+      // Re-resolve index by URL before each close (indices shift after each closure)
+      const tabs = await safari.listTabs();
+      const parsed = typeof tabs === 'string' ? JSON.parse(tabs) : tabs;
+      const match = parsed.find(t => t.url === url);
+      if (match) {
+        safari.setActiveTabIndex(match.index);
+        await safari.closeTab();
+      }
     } catch {}
   }
   _openedTabs.clear();
@@ -81,9 +91,17 @@ let _memoryCheckTimer = null;
 function _startMemoryMonitor() {
   _memoryCheckTimer = setInterval(async () => {
     try {
-      const psOut = execFileSync("bash", ["-c",
-        "ps aux | grep -i 'WebKit\\|WebContent' | grep -v grep | awk '{sum+=$6} END {print sum/1024}'"
-      ], { encoding: "utf8" }).trim();
+      // Use pgrep + ps directly — avoids spawning bash, grep, awk pipeline
+      let psOut = "0";
+      try {
+        const pids = execFileSync("pgrep", ["-f", "WebKit|WebContent"], { encoding: "utf8" }).trim();
+        if (pids) {
+          const pidList = pids.split("\n").join(",");
+          psOut = execFileSync("ps", ["-p", pidList, "-o", "rss="], { encoding: "utf8" }).trim();
+          const totalKB = psOut.split("\n").reduce((sum, l) => sum + (parseInt(l.trim(), 10) || 0), 0);
+          psOut = String(totalKB / 1024);
+        }
+      } catch { psOut = "0"; }
       const webkitMB = parseFloat(psOut) || 0;
       if (webkitMB > WEBKIT_MEMORY_LIMIT_MB && _openedTabs.size > 1) {
         console.error(`[Safari MCP] ⚠️ WebKit using ${Math.round(webkitMB)}MB (limit: ${WEBKIT_MEMORY_LIMIT_MB}MB) — closing oldest MCP tab`);
@@ -278,8 +296,8 @@ try {
         try {
           const { nonce, expectedProfile } = JSON.parse(body);
           // Use AppleScript to find which window contains the nonce in a tab title
-          const safeNonce = nonce.replace(/"/g, '\\"');
-          const safeProfile = (expectedProfile || "").replace(/"/g, '\\"');
+          const safeNonce = String(nonce).replace(/[^0-9]/g, '');  // nonce is numeric only
+          const safeProfile = (expectedProfile || "").replace(/[^\p{L}\p{N}\s\-_]/gu, '');  // whitelist: letters, numbers, spaces, hyphens, underscores
           // Check via AppleScript — look for the nonce in the profile window
           const { execFile } = await import("node:child_process");
           const { promisify } = await import("node:util");
@@ -486,12 +504,12 @@ function sendToExtension(type, payload = {}, timeoutMs = 30000) {
 // Per-command timeouts — fast commands get short timeouts, nav/screenshot get longer ones
 const _commandTimeouts = {
   click: 10000, fill: 5000, read_page: 30000, get_source: 10000, evaluate: 30000,
-  type_text: 5000, press_key: 5000, scroll: 3000, scroll_to: 3000, scroll_to_element: 3000,
+  type_text: 5000, press_key: 5000, scroll: 3000, scroll_to: 3000, scroll_to_element: 15000,
   hover: 5000, list_tabs: 5000, new_tab: 15000, close_tab: 5000, switch_tab: 30000,
   wait_for: 30000, navigate: 30000, navigate_and_read: 30000, go_back: 10000, go_forward: 10000,
   reload: 15000, screenshot: 15000, snapshot: 30000, click_and_read: 15000,
   double_click: 10000, right_click: 10000, clear_field: 5000, select_option: 5000, fill_form: 10000,
-  get_url: 3000, get_title: 3000,
+  replace_editor: 10000, get_url: 3000, get_title: 3000,
 };
 
 // Commands where null result means failure (should fall back to AppleScript)
@@ -539,9 +557,11 @@ async function extensionOrFallback(extensionType, extensionPayload, fallbackFn)
   return result;
 }
 
+// Read version from package.json to avoid hardcoded mismatch
+const _pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')).version;
 const server = new McpServer({
   name: "safari-mcp",
-  version: "1.0.0",
+  version: _pkgVersion,
   description: "Safari browser automation - lightweight, keeps logins",
 });
 
@@ -628,9 +648,10 @@ server.tool(
   "PREFERRED way to see page state. Returns accessibility tree with ref IDs for every interactive element. Use refs with click/fill/type instead of CSS selectors. Workflow: snapshot → see refs → click({ref:'0_5'}). PREFER THIS over safari_screenshot (cheaper, structured text vs heavy image) and over safari_read_page (includes interactive refs). Use safari_screenshot only when you need to see visual layout/styling.",
   { selector: z.string().optional().describe("CSS selector for subtree (default: full page)") },
   async (args) => {
+    const gen = safari.getNextSnapshotGen();
     const result = await extensionOrFallback(
-      "snapshot", { selector: args.selector },
-      () => safari.takeSnapshot(args)
+      "snapshot", { selector: args.selector, gen },
+      () => safari.takeSnapshot({ ...args, _gen: gen })
     );
     return { content: [{ type: "text", text: typeof result === 'string' ? result : JSON.stringify(result) }] };
   }
@@ -1083,20 +1104,36 @@ server.tool(
     // Get current tab list
     const beforeRaw = await extensionOrFallback("list_tabs", {}, () => safari.listTabs());
     const beforeTabs = typeof beforeRaw === 'string' ? JSON.parse(beforeRaw) : beforeRaw;
-    const beforeUrls = new Set(beforeTabs.map(t => t.url));
+    const beforeIds = new Set(beforeTabs.map(t => `${t.index}:${t.url}`));
+    const beforeCount = beforeTabs.length;
 
-    // Poll for new tab
+    // Poll for new tab — detect by count increase + new entries (handles about:blank tabs)
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       await new Promise(r => setTimeout(r, 500));
       const nowRaw = await extensionOrFallback("list_tabs", {}, () => safari.listTabs());
       const nowTabs = typeof nowRaw === 'string' ? JSON.parse(nowRaw) : nowRaw;
-      for (const tab of nowTabs) {
-        if (!beforeUrls.has(tab.url) && tab.url !== 'about:blank') {
-          if (urlContains && !tab.url.includes(urlContains)) continue;
-          // Switch to new tab
-          await extensionOrFallback("switch_tab", { index: tab.index }, () => safari.switchTab(tab.index));
-          return { content: [{ type: "text", text: `Found new tab: ${tab.title} (${tab.url})` }] };
+      if (nowTabs.length > beforeCount) {
+        // Find the new tab(s) — could be about:blank initially (OAuth popups)
+        for (const tab of nowTabs) {
+          if (!beforeIds.has(`${tab.index}:${tab.url}`)) {
+            // Wait briefly for about:blank to resolve to actual URL
+            if (tab.url === 'about:blank') {
+              await new Promise(r => setTimeout(r, 1000));
+              const refreshed = await extensionOrFallback("list_tabs", {}, () => safari.listTabs());
+              const refreshedTabs = typeof refreshed === 'string' ? JSON.parse(refreshed) : refreshed;
+              const resolved = refreshedTabs.find(t => t.index === tab.index);
+              if (resolved && resolved.url !== 'about:blank') {
+                if (urlContains && !resolved.url.includes(urlContains)) continue;
+                await extensionOrFallback("switch_tab", { index: resolved.index }, () => safari.switchTab(resolved.index));
+                return { content: [{ type: "text", text: `Found new tab: ${resolved.title} (${resolved.url})` }] };
+              }
+              continue;
+            }
+            if (urlContains && !tab.url.includes(urlContains)) continue;
+            await extensionOrFallback("switch_tab", { index: tab.index }, () => safari.switchTab(tab.index));
+            return { content: [{ type: "text", text: `Found new tab: ${tab.title} (${tab.url})` }] };
+          }
         }
       }
     }

package/mcp-helpers.js

@@ -0,0 +1,299 @@
+// MCP Click/Interaction Helpers — injected into every page
+// This file is loaded by safari.js at startup, escaped, and injected via AppleScript `do JavaScript`.
+// It is also used by the extension's execInTab for the AppleScript fallback path.
+// IMPORTANT: Keep this file compatible with all browsers — no ES6+ modules, use var where possible.
+
+if (window.__mcpVersion !== 5) {
+  window.__mcpVersion = 5;
+  window.__mcpRefs = window.__mcpRefs || {};
+  window.__mcpCachedRoots = null;
+  window.__mcpRootsDirty = true;
+  if (!window.__mcpRootsObserver) {
+    window.__mcpRootsObserver = new MutationObserver(function() { window.__mcpRootsDirty = true; });
+    window.__mcpRootsObserver.observe(document.documentElement, { childList: true, subtree: true });
+  }
+  window.mcpCollectRoots = function() {
+    if (!window.__mcpRootsDirty && window.__mcpCachedRoots) return window.__mcpCachedRoots;
+    var roots = [];
+    function collect(root) {
+      roots.push(root);
+      var all = root.querySelectorAll('*');
+      for (var i = 0; i < all.length; i++) {
+        if (all[i].shadowRoot) collect(all[i].shadowRoot);
+      }
+    }
+    collect(document);
+    var iframes = document.querySelectorAll('iframe');
+    for (var i = 0; i < iframes.length; i++) {
+      try { var doc = iframes[i].contentDocument; if (doc) collect(doc); } catch (e) {}
+    }
+    window.__mcpCachedRoots = roots;
+    window.__mcpRootsDirty = false;
+    return roots;
+  };
+  window.mcpQuerySelectorDeep = function(selector) {
+    try {
+      var direct = document.querySelector(selector);
+      if (direct) return direct;
+    } catch (e) { return null; }
+    var roots = window.mcpCollectRoots();
+    for (var i = 1; i < roots.length; i++) {
+      try {
+        var found = roots[i].querySelector(selector);
+        if (found) return found;
+      } catch (e) {}
+    }
+    var iframes = document.querySelectorAll('iframe');
+    for (var i = 0; i < iframes.length; i++) {
+      try {
+        var doc = iframes[i].contentDocument;
+        if (doc) { var found = doc.querySelector(selector); if (found) return found; }
+      } catch (e) {}
+    }
+    return null;
+  };
+  window.mcpElementFromPoint = function(x, y) {
+    var el = document.elementFromPoint(x, y);
+    while (el && el.shadowRoot) {
+      try {
+        if (typeof el.shadowRoot.elementFromPoint !== 'function') break;
+        var inner = el.shadowRoot.elementFromPoint(x, y);
+        if (!inner || inner === el) break;
+        el = inner;
+      } catch (e) { break; }
+    }
+    return el;
+  };
+  window.mcpIsVisible = function(el) {
+    if (!el || el.nodeType !== 1 || !el.isConnected) return false;
+    var cs = window.getComputedStyle(el);
+    if (!cs || cs.display === 'none' || cs.visibility === 'hidden' || cs.visibility === 'collapse' || parseFloat(cs.opacity) === 0) return false;
+    var r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  window.mcpIsActionable = function(el) {
+    if (!window.mcpIsVisible(el)) return false;
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') return false;
+    if (el.matches && el.matches('input[type="hidden"]')) return false;
+    return true;
+  };
+  window.mcpPickActionable = function(el) {
+    var node = el && el.nodeType === 1 ? el : (el && el.parentElement) || null;
+    while (node) {
+      if (window.mcpIsActionable(node) && node.matches && node.matches('a[href],button,input:not([type="hidden"]),textarea,select,summary,label,option,[role],[onclick],[tabindex],[contenteditable=""],[contenteditable="true"]')) return node;
+      node = node.parentElement;
+    }
+    return el && el.nodeType === 1 ? el : null;
+  };
+  window.mcpFindByAttr = function(attr, value, selector) {
+    if (!value) return null;
+    var roots = window.mcpCollectRoots();
+    var sel = selector || ('[' + attr + ']');
+    for (var i = 0; i < roots.length; i++) {
+      var els = roots[i].querySelectorAll(sel);
+      for (var j = 0; j < els.length; j++) {
+        var current = attr === 'href' ? els[j].href : els[j].getAttribute(attr);
+        if (current === value && window.mcpIsVisible(els[j])) return els[j];
+      }
+    }
+    return null;
+  };
+  window.mcpNormalizeText = function(value) {
+    return String(value || '').replace(/\s+/g, ' ').trim();
+  };
+  window.mcpResolveTarget = function(el) {
+    var base = window.mcpPickActionable(el) || el;
+    if (!base) return null;
+    try { base.scrollIntoView({ block: 'center', inline: 'center' }); } catch (e) {}
+    var r = base.getBoundingClientRect();
+    var dx = Math.min(12, Math.max(4, r.width / 4));
+    var dy = Math.min(12, Math.max(4, r.height / 4));
+    var pts = [
+      [r.left + r.width / 2, r.top + r.height / 2],
+      [r.left + dx, r.top + r.height / 2],
+      [r.right - dx, r.top + r.height / 2],
+      [r.left + r.width / 2, r.top + dy],
+      [r.left + r.width / 2, r.bottom - dy]
+    ];
+    for (var i = 0; i < pts.length; i++) {
+      var x = pts[i][0], y = pts[i][1];
+      if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) continue;
+      var hit = window.mcpElementFromPoint(x, y);
+      if (!hit) continue;
+      if (base === hit || base.contains(hit) || hit.contains(base)) return window.mcpPickActionable(hit) || hit;
+      // Overlay pattern: transparent button/link overlays a text label (e.g. dropdown items).
+      // If the hit is an interactive element sharing a nearby common ancestor, prefer it.
+      var hitAction = window.mcpPickActionable(hit);
+      if (hitAction && hitAction !== base && hitAction.matches && hitAction.matches('button,a[href],[role="button"],[role="option"],[role="menuitem"]')) {
+        var p = base.parentElement;
+        for (var k = 0; k < 4 && p; k++) {
+          if (p.contains(hitAction)) return hitAction;
+          p = p.parentElement;
+        }
+      }
+    }
+    return base;
+  };
+  window.mcpClick = function(el) {
+    var target = window.mcpResolveTarget(el);
+    if (!window.mcpIsActionable(target)) return false;
+    var r = target.getBoundingClientRect();
+    var x = r.left + r.width / 2, y = r.top + r.height / 2;
+    var beforeUrl = location.href;
+    var anchor = target.closest ? target.closest('a[href]') : null;
+    var href = anchor && anchor.href && !anchor.href.startsWith('javascript:') ? anchor.href : '';
+    var s = { bubbles: true, cancelable: true, composed: true, view: window, clientX: x, clientY: y, button: 0, detail: 1 };
+    var p = { ...s, pointerId: 1, pointerType: 'mouse', isPrimary: true, width: 1, height: 1, pressure: 0.5 };
+    target.dispatchEvent(new PointerEvent('pointerover', { ...p, buttons: 0 }));
+    target.dispatchEvent(new MouseEvent('mouseover', { ...s, buttons: 0 }));
+    target.dispatchEvent(new PointerEvent('pointerenter', { ...p, buttons: 0 }));
+    target.dispatchEvent(new MouseEvent('mouseenter', { ...s, buttons: 0 }));
+    target.dispatchEvent(new PointerEvent('pointermove', { ...p, buttons: 0 }));
+    target.dispatchEvent(new MouseEvent('mousemove', { ...s, buttons: 0 }));
+    target.dispatchEvent(new PointerEvent('pointerdown', { ...p, buttons: 1 }));
+    target.dispatchEvent(new MouseEvent('mousedown', { ...s, buttons: 1 }));
+    if (target.focus) { try { target.focus({ preventScroll: true }); } catch (e) { try { target.focus(); } catch (_) {} } }
+    target.dispatchEvent(new PointerEvent('pointerup', { ...p, buttons: 0, pressure: 0 }));
+    target.dispatchEvent(new MouseEvent('mouseup', { ...s, buttons: 0 }));
+    try {
+      if (typeof target.click === 'function') {
+        target.click();
+        if (href && href !== beforeUrl) {
+          location.href = href;
+        }
+      }
+    } catch (e) {}
+    target.dispatchEvent(new MouseEvent('click', { ...s, buttons: 0 }));
+    if (href && href !== beforeUrl) {
+      location.href = href;
+    }
+    var form = target.closest ? target.closest('form') : null;
+    if (form && (target.type === 'submit' || (target.tagName === 'BUTTON' && target.type !== 'button' && target.type !== 'reset'))) {
+      try { form.requestSubmit ? form.requestSubmit(target.type === 'submit' ? target : undefined) : form.submit(); } catch (e) {}
+    }
+    return true;
+  };
+  window.mcpReactClick = function(el) {
+    var startNode = window.mcpResolveTarget(el) || el;
+    if (!startNode) return false;
+    function makeSynth(targetNode, type) {
+      var r = targetNode.getBoundingClientRect();
+      return { type: type || 'click', target: targetNode, currentTarget: targetNode,
+        clientX: r.left + r.width / 2, clientY: r.top + r.height / 2, pageX: r.left + r.width / 2 + window.scrollX, pageY: r.top + r.height / 2 + window.scrollY,
+        preventDefault: function() {}, stopPropagation: function() {}, nativeEvent: new MouseEvent(type || 'click'), persist: function() {}, bubbles: true, cancelable: true };
+    }
+    // For React radio/checkbox inputs, onChange is the primary handler (not onClick)
+    var isToggle = startNode.tagName === 'INPUT' && (startNode.type === 'radio' || startNode.type === 'checkbox');
+    function tryOnChange(propsObj, targetNode) {
+      if (!isToggle || !propsObj.onChange) return false;
+      var newChecked = startNode.type === 'radio' ? true : !startNode.checked;
+      propsObj.onChange({ target: { value: startNode.value, checked: newChecked, type: startNode.type, name: startNode.name, id: startNode.id, tagName: 'INPUT' },
+        currentTarget: targetNode, preventDefault: function() {}, stopPropagation: function() {}, nativeEvent: new Event('change'), persist: function() {}, bubbles: true, cancelable: true, type: 'change' });
+      return true;
+    }
+    var node = startNode;
+    for (var depth = 0; depth < 15 && node; depth++) {
+      var pk = Object.keys(node).find(function(k) { return k.startsWith('__reactProps$'); });
+      if (pk && node[pk]) {
+        var props = node[pk];
+        if (tryOnChange(props, node)) return true;
+        if (props.onClick) { props.onClick(makeSynth(node, 'click')); return true; }
+        if (props.onMouseDown) { props.onMouseDown(makeSynth(node, 'mousedown')); return true; }
+        if (props.onPointerDown) { props.onPointerDown(makeSynth(node, 'pointerdown')); return true; }
+      }
+      var fk = Object.keys(node).find(function(k) { return k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'); });
+      if (fk) {
+        var f = node[fk];
+        while (f) {
+          if (f.memoizedProps) {
+            if (tryOnChange(f.memoizedProps, node)) return true;
+            if (f.memoizedProps.onClick) { f.memoizedProps.onClick(makeSynth(node, 'click')); return true; }
+            if (f.memoizedProps.onMouseDown) { f.memoizedProps.onMouseDown(makeSynth(node, 'mousedown')); return true; }
+            if (f.memoizedProps.onPointerDown) { f.memoizedProps.onPointerDown(makeSynth(node, 'pointerdown')); return true; }
+          }
+          f = f.return;
+        }
+      }
+      node = node.parentElement;
+    }
+    return false;
+  };
+  window.mcpClickWithReact = function(el) {
+    var target = window.mcpResolveTarget(el) || el;
+    var reactFired = false;
+    try { reactFired = window.mcpReactClick(target); } catch (e) {}
+    var anchor = target && target.closest ? target.closest('a[href]') : null;
+    if (!reactFired || anchor) window.mcpClick(target);
+    return target;
+  };
+  window.mcpFindRef = function(ref) {
+    var el = window.mcpQuerySelectorDeep('[data-mcp-ref="' + ref + '"]');
+    if (el) return el;
+    if (!window.__mcpRefs || !window.__mcpRefs[ref]) return null;
+    var m = window.__mcpRefs[ref];
+    if (m.id) { el = window.mcpFindByAttr('id', m.id); if (el) return el; }
+    if (m.testid) { el = window.mcpFindByAttr('data-testid', m.testid); if (el) return el; }
+    if (m.nameAttr) { el = window.mcpFindByAttr('name', m.nameAttr); if (el) return el; }
+    if (m.href) { el = window.mcpFindByAttr('href', m.href, 'a[href]'); if (el) return el; }
+    if (m.al) { el = window.mcpFindByAttr('aria-label', m.al); if (el) return el; }
+    if (m.ph) { el = window.mcpFindByAttr('placeholder', m.ph); if (el) return el; }
+    if (m.text) {
+      el = window.mcpFindText(m.text, true) || window.mcpFindText(m.text, false);
+      if (el) return el;
+    }
+    if (m.cx !== undefined && m.cy !== undefined) {
+      try {
+        window.scrollTo(window.scrollX, Math.max(0, m.cy - window.innerHeight / 2));
+      } catch (e) {}
+      el = window.mcpElementFromPoint(m.cx - window.scrollX, m.cy - window.scrollY);
+      if (el) return window.mcpPickActionable(el) || el;
+    }
+    return null;
+  };
+  window.mcpFindText = function(text, exact) {
+    var needle = window.mcpNormalizeText(text);
+    var best = null, bestScore = Infinity;
+    function consider(node) {
+      var target = window.mcpPickActionable(node) || node;
+      if (!window.mcpIsVisible(target)) return;
+      var r = target.getBoundingClientRect();
+      var area = r.width * r.height;
+      var interactive = target.matches && target.matches('a[href],button,input:not([type="hidden"]),textarea,select,summary,label,[role=button],[role=link],[role=tab],[onclick],[tabindex]');
+      var score = area + (interactive ? 0 : 1000000);
+      if (score < bestScore) { best = target; bestScore = score; }
+    }
+    var roots = window.mcpCollectRoots();
+    for (var i = 0; i < roots.length; i++) {
+      var attrEls = roots[i].querySelectorAll('[aria-label],[placeholder],[title],[data-testid],[alt]');
+      for (var j = 0; j < attrEls.length; j++) {
+        var a = attrEls[j];
+        var vals = [a.getAttribute('aria-label'), a.getAttribute('placeholder'), a.getAttribute('title'), a.getAttribute('data-testid'), a.getAttribute('alt')];
+        for (var k = 0; k < vals.length; k++) {
+          var val = vals[k];
+          if (!val) continue;
+          var normalized = window.mcpNormalizeText(val);
+          if (exact ? normalized === needle : normalized.includes(needle)) { consider(a); break; }
+        }
+      }
+      var tw = document.createTreeWalker(roots[i], NodeFilter.SHOW_TEXT, null);
+      while (tw.nextNode()) {
+        var n = tw.currentNode;
+        var t = window.mcpNormalizeText(n.textContent);
+        if (!t) continue;
+        if (exact ? (t !== needle) : !t.includes(needle)) continue;
+        if (n.parentElement) consider(n.parentElement);
+      }
+    }
+    if (!best) {
+      var allEls = document.querySelectorAll('*');
+      for (var i = 0; i < allEls.length; i++) {
+        var el = allEls[i];
+        var it = window.mcpNormalizeText(el.innerText);
+        if (!it) continue;
+        if (exact ? (it !== needle) : !it.includes(needle)) continue;
+        consider(el);
+      }
+    }
+    return best;
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.1.8",
+  "version": "2.3.0",
   "mcpName": "io.github.achiya-automation/safari-mcp",
   "description": "Safari browser automation for AI agents — native macOS, zero Chrome overhead. 80 tools via AppleScript + JavaScript.",
   "type": "module",
@@ -49,6 +49,7 @@
   "files": [
     "index.js",
     "safari.js",
+    "mcp-helpers.js",
     "safari-helper",
     "safari-helper.swift",
     "extension/",

package/safari.js

@@ -8,6 +8,7 @@ import { promisify } from "node:util";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { readFile, writeFile, unlink, appendFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 // Extension bridge is handled by index.js (WebSocket server on port 9223)
 
@@ -18,6 +19,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Persistent process — no subprocess spawn overhead (~5ms vs ~90ms)
 let _helperProc = null;
 const _helperQueue = []; // callbacks waiting for responses
+let _helperConsecutiveTimeouts = 0; // Track consecutive timeouts — only kill after 3
 
 // Reject all pending callbacks when helper crashes
 function _drainHelperQueue(reason) {
@@ -335,9 +337,15 @@ function _osascriptFastHelper(script, timeout) {
       resolved = true;
       const idx = _helperQueue.indexOf(cb);
       if (idx >= 0) _helperQueue.splice(idx, 1);
-      _helperProc?.kill();
-      _helperProc = null;
-      setTimeout(startHelper, 100);
+      _helperConsecutiveTimeouts++;
+      // Only kill the daemon after 3 consecutive timeouts (single slow script shouldn't kill concurrent ops)
+      if (_helperConsecutiveTimeouts >= 3) {
+        console.error(`[Safari MCP] safari-helper: ${_helperConsecutiveTimeouts} consecutive timeouts — killing daemon`);
+        _helperProc?.kill();
+        _helperProc = null;
+        _helperConsecutiveTimeouts = 0;
+        setTimeout(startHelper, 100);
+      }
       reject(new Error("safari-helper timeout"));
     }, timeout);
 
@@ -345,6 +353,7 @@ function _osascriptFastHelper(script, timeout) {
       if (resolved) return;
       resolved = true;
       clearTimeout(timer);
+      _helperConsecutiveTimeouts = 0; // Reset on success
       try {
         const parsed = JSON.parse(line);
         if (parsed.error) reject(new Error(parsed.error));
@@ -354,14 +363,21 @@ function _osascriptFastHelper(script, timeout) {
       }
     }
 
-    _helperQueue.push(cb);
-    if (!_helperProc || !_helperProc.stdin) {
-      // Helper died between the check and write — reject immediately
-      _helperQueue.pop(); // Remove the callback we just pushed
+    // Check process availability BEFORE pushing to queue (prevents dangling callbacks)
+    if (!_helperProc || !_helperProc.stdin || !_helperProc.stdin.writable) {
+      clearTimeout(timer);
       reject(new Error("safari-helper not available"));
       return;
     }
-    _helperProc.stdin.write(JSON.stringify({ script }) + "\n");
+    _helperQueue.push(cb);
+    try {
+      _helperProc.stdin.write(JSON.stringify({ script }) + "\n");
+    } catch (writeErr) {
+      const idx = _helperQueue.indexOf(cb);
+      if (idx >= 0) _helperQueue.splice(idx, 1);
+      clearTimeout(timer);
+      reject(new Error("safari-helper write failed: " + writeErr.message));
+    }
   });
 }
 
@@ -622,17 +638,21 @@ export async function navigate(url) {
 
 export async function goBack() {
   // Navigate back + smart wait: check immediately, then poll only if loading
-  return runJS(
+  const result = await runJS(
     `(async function(){history.back();await new Promise(function(r){setTimeout(r,50)});if(document.readyState!=='complete'){for(var i=0;i<30;i++){await new Promise(function(r){setTimeout(r,150)});if(document.readyState==='complete')break;}}return JSON.stringify({title:document.title,url:location.href});})()`,
     { timeout: 10000 }
   );
+  try { const p = JSON.parse(result); if (p.url) _activeTabURL = p.url; } catch {}
+  return result;
 }
 
 export async function goForward() {
-  return runJS(
+  const result = await runJS(
     `(async function(){history.forward();await new Promise(function(r){setTimeout(r,50)});if(document.readyState!=='complete'){for(var i=0;i<30;i++){await new Promise(function(r){setTimeout(r,150)});if(document.readyState==='complete')break;}}return JSON.stringify({title:document.title,url:location.href});})()`,
     { timeout: 10000 }
   );
+  try { const p = JSON.parse(result); if (p.url) _activeTabURL = p.url; } catch {}
+  return result;
 }
 
 export async function reload(hardReload = false) {
@@ -640,10 +660,12 @@ export async function reload(hardReload = false) {
   await runJS(hardReload ? "location.reload(true)" : "location.reload()");
   await new Promise((r) => setTimeout(r, 100)); // Brief wait for reload to start (was 500ms)
   // Poll readyState in a single call
-  return runJS(
+  const result = await runJS(
     `(async function(){for(var i=0;i<30;i++){if(document.readyState==='complete')break;await new Promise(function(r){setTimeout(r,200)});}return JSON.stringify({title:document.title,url:location.href});})()`,
     { timeout: 10000 }
   );
+  try { const p = JSON.parse(result); if (p.url) _activeTabURL = p.url; } catch {}
+  return result;
 }
 
 // ========== PAGE INFO ==========
@@ -673,7 +695,12 @@ export async function getPageSource({ maxLength = 200000 } = {}) {
 
 // Inject click helpers ONCE per page (cached on window.__mcp)
 // Includes: mcpClick (full event sequence), mcpReactClick (React Fiber), mcpFindText (fast TreeWalker)
-const INJECT_MCP_HELPERS = `if(window.__mcpVersion!==5){window.__mcpVersion=5;
+// Loaded from mcp-helpers.js at startup — enables syntax highlighting, linting, and easier maintenance
+const INJECT_MCP_HELPERS = readFileSync(join(__dirname, 'mcp-helpers.js'), 'utf8');
+
+// NOTE: Helper code previously inlined here (~300 lines) is now in mcp-helpers.js
+/* eslint-disable */
+const _LEGACY_INLINE_START = `if(window.__mcpVersion!==5){window.__mcpVersion=5;
   window.__mcpRefs=window.__mcpRefs||{};
   window.__mcpCachedRoots=null;
   window.__mcpRootsDirty=true;
@@ -1233,7 +1260,7 @@ export async function fill({ selector, value, ref }) {
 
     const fillResult = await runJS(
       `(function(){` +
-      `var el=document.querySelector('${selector.replace(/'/g, "\\'")}');` +
+      `var el=document.querySelector('${selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}');` +
       `if(!el)return 'Element not found';` +
       `el.focus();el.click();` +
       `var sel=window.getSelection();if(sel.rangeCount){var r=document.createRange();r.selectNodeContents(el);r.collapse(false);sel.removeAllRanges();sel.addRange(r);}` +
@@ -1618,15 +1645,19 @@ export async function screenshot({ fullPage = false } = {}) {
           await osascript(
             `tell application "Safari" to set bounds of ${getTargetWindowRef()} to {0, 0, ${Number(w)}, ${Math.min(Number(h) + 100, 5000)}}`
           );
-          await new Promise((r) => setTimeout(r, 500));
-          // Use do shell script to inherit osascript's Screen Recording permission
-          await osascript(
-            `do shell script "screencapture -l${windowId} -o -x '${tmpFile}'"`,
-            { timeout: 15000 }
-          );
-          await osascript(
-            `tell application "Safari" to set bounds of ${getTargetWindowRef()} to {${bounds}}`
-          );
+          try {
+            await new Promise((r) => setTimeout(r, 500));
+            // Use do shell script to inherit osascript's Screen Recording permission
+            await osascript(
+              `do shell script "screencapture -l${windowId} -o -x '${tmpFile}'"`,
+              { timeout: 15000 }
+            );
+          } finally {
+            // Always restore bounds — even if screencapture fails
+            await osascript(
+              `tell application "Safari" to set bounds of ${getTargetWindowRef()} to {${bounds}}`
+            ).catch(() => {});
+          }
         } else {
           // Try direct execFile first (works if VS Code has Screen Recording permission)
           try {
@@ -1773,7 +1804,7 @@ export async function screenshotElement({ selector }) {
       await execFileAsync("screencapture", ["-l" + windowId, "-o", "-x", tmpFile]);
       const { x, y, w, h } = JSON.parse(bounds);
       // Use sips to crop (macOS built-in)
-      const toolbarHeight = 52; // Safari toolbar approximate height
+      const toolbarHeight = 74; // Safari toolbar approximate height (matches _getSafariWindowGeometry)
       const cropFile = join(tmpdir(), `safari-el-crop-${Date.now()}.png`);
       await execFileAsync("sips", [
         "-c", String(h), String(w),
@@ -1861,8 +1892,9 @@ export async function newTab(url = "") {
       else { await osascript('tell application "Safari" to make new document'); }
     }
   }
+  // Get count atomically from the same tell block as tab creation (avoids TOCTOU if user opens tabs concurrently)
   const tabCount = await osascriptFast(`tell application "Safari" to return count of tabs of ${getTargetWindowRef()}`);
-  _activeTabIndex = Number(tabCount);
+  _activeTabIndex = Number(tabCount);  // New tab is always appended as last
   _activeTabURL = url || null;
   _lastResolveTime = Date.now();
   // Wait for page load if URL given
@@ -2052,11 +2084,11 @@ export async function handleDialog({ action = "accept", text }) {
   }
   if (action === "accept") {
     await runJS(
-      "window.__origConfirm=window.confirm;window.confirm=function(){window.confirm=window.__origConfirm;return true;};window.__origAlert=window.alert;window.alert=function(){window.alert=window.__origAlert;};"
+      "window.__origConfirm=window.__origConfirm||window.confirm;window.confirm=function(){window.confirm=window.__origConfirm;return true;};window.__origAlert=window.__origAlert||window.alert;window.alert=function(){window.alert=window.__origAlert;};"
     );
   } else {
     await runJS(
-      "window.__origConfirm=window.confirm;window.confirm=function(){window.confirm=window.__origConfirm;return false;};"
+      "window.__origConfirm=window.__origConfirm||window.confirm;window.confirm=function(){window.confirm=window.__origConfirm;return false;};"
     );
   }
   return `Dialog handler set: ${action}${text ? ' with "' + text + '"' : ""}`;
@@ -2100,19 +2132,23 @@ export async function getNetworkRequests({ limit = 50 } = {}) {
 
 export async function drag({ sourceSelector, targetSelector, sourceX, sourceY, targetX, targetY }) {
   if (sourceSelector && targetSelector) {
-    const srcSel = sourceSelector.replace(/'/g, "\\'");
-    const tgtSel = targetSelector.replace(/'/g, "\\'");
+    const srcSel = sourceSelector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    const tgtSel = targetSelector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){` +
       `var src=document.querySelector('${srcSel}');var tgt=document.querySelector('${tgtSel}');` +
       `if(!src)return 'Source not found: ${srcSel}';if(!tgt)return 'Target not found: ${tgtSel}';` +
       `var sr=src.getBoundingClientRect();var tr=tgt.getBoundingClientRect();` +
       `var sx=sr.x+sr.width/2,sy=sr.y+sr.height/2,tx=tr.x+tr.width/2,ty=tr.y+tr.height/2;` +
+      `var dt=new DataTransfer();` +
+      `src.dispatchEvent(new DragEvent('dragstart',{clientX:sx,clientY:sy,bubbles:true,cancelable:true,dataTransfer:dt}));` +
       `src.dispatchEvent(new MouseEvent('mousedown',{clientX:sx,clientY:sy,bubbles:true}));` +
       `src.dispatchEvent(new MouseEvent('mousemove',{clientX:sx,clientY:sy,bubbles:true}));` +
+      `tgt.dispatchEvent(new DragEvent('dragover',{clientX:tx,clientY:ty,bubbles:true,cancelable:true,dataTransfer:dt}));` +
       `tgt.dispatchEvent(new MouseEvent('mousemove',{clientX:tx,clientY:ty,bubbles:true}));` +
       `tgt.dispatchEvent(new MouseEvent('mouseup',{clientX:tx,clientY:ty,bubbles:true}));` +
-      `tgt.dispatchEvent(new DragEvent('drop',{bubbles:true}));` +
+      `tgt.dispatchEvent(new DragEvent('drop',{clientX:tx,clientY:ty,bubbles:true,cancelable:true,dataTransfer:dt}));` +
+      `src.dispatchEvent(new DragEvent('dragend',{bubbles:true}));` +
       `return 'Dragged from '+src.tagName+' to '+tgt.tagName;})()`
     );
   }
@@ -2131,9 +2167,27 @@ export async function drag({ sourceSelector, targetSelector, sourceX, sourceY, t
   throw new Error("drag requires sourceSelector+targetSelector or sourceX/Y+targetX/Y");
 }
 
+// ========== FILE PATH SAFETY ==========
+// Prevent reading sensitive system files via upload/paste tools
+function _validateFilePath(filePath) {
+  const { resolve } = require("node:path");
+  const resolved = resolve(filePath);
+  if (resolved.includes('..')) throw new Error("Path traversal not allowed: " + filePath);
+  const blocked = ['.ssh', '.gnupg', '.aws', '.config/gcloud', 'credentials', '.env', '.npmrc', '.netrc', 'id_rsa', 'id_ed25519', '.keychain'];
+  const lower = resolved.toLowerCase();
+  for (const b of blocked) {
+    if (lower.includes(b)) throw new Error("Blocked: reading sensitive path " + filePath);
+  }
+  // Must be under /Users/ or /tmp/ or /var/folders/ (macOS temp)
+  if (!resolved.startsWith('/Users/') && !resolved.startsWith('/tmp/') && !resolved.startsWith('/var/folders/') && !resolved.startsWith('/private/tmp/')) {
+    throw new Error("File path must be under /Users/, /tmp/, or /var/folders/: " + filePath);
+  }
+}
+
 // ========== UPLOAD FILE ==========
 
 export async function uploadFile({ selector, filePath }) {
+  _validateFilePath(filePath);
   // Read file in Node.js, send as base64 to Safari JS, create File + DataTransfer
   // NO file dialog, NO System Events, NO focus stealing
 
@@ -2251,6 +2305,7 @@ export async function uploadFile({ selector, filePath }) {
 // ========== PASTE IMAGE FROM FILE ==========
 
 export async function pasteImageFromFile({ filePath }) {
+  _validateFilePath(filePath);
   // Paste image via JS ClipboardEvent — NO clipboard touch, NO System Events, NO focus steal
   const { extname } = await import("node:path");
   const ext = extname(filePath).toLowerCase().replace(".", "");
@@ -2351,9 +2406,9 @@ export async function emulate({ device, width, height, userAgent, scale = 1 }) {
 
 export async function resetEmulation() {
   await refreshTargetWindow();
-  // Reset user agent
+  // Reset user agent — remove the defineProperty override set by emulate()
   await runJS(
-    "delete Object.getOwnPropertyDescriptor(Navigator.prototype,'userAgent')||true"
+    "try{var d=Object.getOwnPropertyDescriptor(Navigator.prototype,'userAgent');if(d){Object.defineProperty(navigator,'userAgent',d);}else{delete navigator.userAgent;}}catch(_){}"
   );
   // Maximize window
   await osascript(
@@ -2439,9 +2494,14 @@ export async function savePDF({ path: pdfPath }) {
 // instead of guessing CSS selectors. Much faster, no hallucination risk.
 
 let _snapshotGen = 0;
-
-export async function takeSnapshot({ selector } = {}) {
-  const gen = _snapshotGen++;
+// getNextSnapshotGen is used by the MCP tool path (index.js) to reserve a gen for the extension.
+// If the extension fails and falls back to takeSnapshot(), takeSnapshot uses _snapshotGen directly
+// (which was already incremented by getNextSnapshotGen) — so no double-increment occurs.
+export function getNextSnapshotGen() { return _snapshotGen++; }
+
+export async function takeSnapshot({ selector, _gen } = {}) {
+  // Use provided gen (from tool path) or allocate a new one (direct call)
+  const gen = _gen != null ? _gen : _snapshotGen++;
   const root = selector ? `document.querySelector('${selector.replace(/'/g, "\\'")}')` : "document.body";
 
   const result = await runJS(
@@ -2793,7 +2853,13 @@ export async function importStorageState({ state }) {
   const parsed = typeof state === "string" ? JSON.parse(state) : state;
   const esc = (s) => String(s).replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "");
   const cmds = [];
-  if (parsed.cookies) cmds.push(`document.cookie='${esc(parsed.cookies)}'`);
+  // Cookies must be set one at a time — document.cookie only accepts one cookie per assignment
+  if (parsed.cookies) {
+    const cookiePairs = String(parsed.cookies).split(/;\s*/);
+    for (const pair of cookiePairs) {
+      if (pair.trim()) cmds.push(`document.cookie='${esc(pair.trim())}'`);
+    }
+  }
   if (parsed.localStorage) {
     for (const [k, v] of Object.entries(parsed.localStorage)) {
       cmds.push(`localStorage.setItem('${esc(k)}','${esc(v)}')`);
@@ -2804,7 +2870,12 @@ export async function importStorageState({ state }) {
       cmds.push(`sessionStorage.setItem('${esc(k)}','${esc(v)}')`);
     }
   }
-  return runJS(cmds.join(";") + "; 'Imported ' + " + cmds.length + " + ' items'");
+  // Use runJSLarge for large sessions (many cookies/localStorage keys can exceed 260KB limit of runJS)
+  const script = cmds.join(";") + "; 'Imported ' + " + cmds.length + " + ' items'";
+  if (script.length > 200000) {
+    return runJSLarge(script, { timeout: 30000 });
+  }
+  return runJS(script);
 }
 
 // ========== CLIPBOARD ==========
@@ -2926,8 +2997,9 @@ export async function clearNetworkMocks() {
 // ========== WAIT FOR TIME ==========
 
 export async function waitForTime({ ms }) {
-  await new Promise((r) => setTimeout(r, Number(ms)));
-  return `Waited ${ms}ms`;
+  const capped = Math.min(Number(ms) || 0, 60000); // Cap at 60 seconds
+  await new Promise((r) => setTimeout(r, capped));
+  return capped < Number(ms) ? `Waited ${capped}ms (capped from ${ms}ms — max 60s)` : `Waited ${ms}ms`;
 }
 
 // ========== NETWORK CAPTURE (Detailed) ==========
@@ -3368,8 +3440,9 @@ export async function navigateAndRead(url, { maxLength = 50000 } = {}) {
   const safeUrl = targetUrl.replace(/"/g, '\\"');
   const navTarget = _activeTabIndex ? `tab ${_activeTabIndex} of ${getTargetWindowRef()}` : getFallbackTarget();
   await osascriptFast(`tell application "Safari" to set URL of ${navTarget} to "${safeUrl}"`);
+  _activeTabURL = targetUrl;
   // Single JS call: poll readyState + return page data — 1 call instead of 30+
-  return runJS(
+  const navResult = await runJS(
     `(async function(){
       for(var i=0;i<60;i++){
         if(document.readyState==='complete')break;
@@ -3379,6 +3452,12 @@ export async function navigateAndRead(url, { maxLength = 50000 } = {}) {
     })()`,
     { timeout: 30000 }
   );
+  // Update _activeTabURL with the actual URL after navigation
+  try {
+    const parsed = JSON.parse(navResult);
+    if (parsed.url && parsed.url !== 'about:blank') _activeTabURL = parsed.url;
+  } catch {}
+  return navResult;
 }
 
 // Click + wait for navigation or element — common after clicking a link/button
@@ -3474,11 +3553,6 @@ export async function analyzePage() {
 }
 
 // ========== GRACEFUL SHUTDOWN ==========
-function cleanup() {
-  if (_helperProc) { try { _helperProc.kill(); } catch {} _helperProc = null; }
-  _drainHelperQueue("shutting down");
-}
-
-process.on("exit", cleanup);
-process.on("SIGINT", () => { cleanup(); process.exit(0); });
-process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+// NOTE: Signal handlers are registered at the top of the file (cleanupHelper + process.exit).
+// _drainHelperQueue is called from cleanupHelper via process.on("exit").
+process.on("exit", () => { _drainHelperQueue("shutting down"); });