safari-mcp 2.1.7 → 2.2.0

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 },

package/index.js

@@ -81,9 +81,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`);
@@ -170,8 +178,19 @@ function _setupExtensionListener(ws) {
 // ========== HTTP POLLING SERVER (for Safari extensions — WebSocket blocked) ==========
 try {
   const httpServer = createServer((req, res) => {
-    // CORS headers for extension
-    res.setHeader("Access-Control-Allow-Origin", "*");
+    // CORS headers — restricted to browser extension origin only.
+    // Safari extensions use moz-extension:// or safari-web-extension:// origins.
+    // "*" was a security risk: any webpage could POST to localhost:9224 and execute MCP commands.
+    const origin = req.headers.origin || "";
+    const isSafeOrigin = !origin || origin.startsWith("safari-web-extension://") || origin.startsWith("moz-extension://") || origin.startsWith("chrome-extension://");
+    if (isSafeOrigin) {
+      res.setHeader("Access-Control-Allow-Origin", origin || "*");
+    } else {
+      // Block cross-origin requests from web pages
+      res.writeHead(403);
+      res.end("Forbidden: cross-origin request blocked");
+      return;
+    }
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
 
@@ -480,7 +499,7 @@ const _commandTimeouts = {
   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)
@@ -617,8 +636,9 @@ 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 },
+      "snapshot", { selector: args.selector, gen },
       () => safari.takeSnapshot(args)
     );
     return { content: [{ type: "text", text: typeof result === 'string' ? result : JSON.stringify(result) }] };
@@ -1072,20 +1092,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' || cs.pointerEvents === 'none' || 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.7",
+  "version": "2.2.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)
 
@@ -650,7 +651,7 @@ export async function reload(hardReload = false) {
 
 export async function readPage({ selector, maxLength = 50000 } = {}) {
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){
         var el = document.querySelector('${sel}');
@@ -673,7 +674,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;
@@ -1044,14 +1050,14 @@ export async function click({ selector, text, x, y, ref }) {
   }
 
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return clickWithRetry(
       `(function(){var el=mcpQuerySelectorDeep('${sel}');if(!el)return 'Element not found: ${sel}';var target=mcpClickWithReact(el);return 'Clicked: '+target.tagName+((target.innerText||target.textContent)?(' "'+(target.innerText||target.textContent).trim().substring(0,50)+'"'):'');})()`
     );
   }
 
   if (text) {
-    const safeText = text.replace(/'/g, "\\'");
+    const safeText = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return clickWithRetry(
       `(function(){var el=mcpFindText('${safeText}',true)||mcpFindText('${safeText}',false);if(!el)return 'Element not found with text: ${safeText}';var target=mcpClickWithReact(el);return 'Clicked: '+target.tagName+' "'+((target.innerText||target.textContent)||'').trim().substring(0,50)+'"';})()`
     );
@@ -1068,7 +1074,7 @@ export async function click({ selector, text, x, y, ref }) {
 export async function doubleClick({ selector, x, y, ref }) {
   if (ref) selector = refSelector(ref);
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found: ${sel}';el.scrollIntoView({block:'center'});el.dispatchEvent(new MouseEvent('dblclick',{bubbles:true,cancelable:true}));return 'Double-clicked: '+el.tagName;})()`
     );
@@ -1083,7 +1089,7 @@ export async function doubleClick({ selector, x, y, ref }) {
 
 export async function rightClick({ selector, x, y }) {
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found: ${sel}';el.scrollIntoView({block:'center'});el.dispatchEvent(new MouseEvent('contextmenu',{bubbles:true,cancelable:true,button:2}));return 'Right-clicked: '+el.tagName;})()`
     );
@@ -1122,7 +1128,7 @@ export async function nativeClick({ selector, text, x, y, ref, doubleClick = fal
         });
       })()`;
     } else if (selector) {
-      const sel = selector.replace(/'/g, "\\'");
+      const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
       jsExpr = `(function(){
         var el = document.querySelector('${sel}');
         if (!el) return JSON.stringify({error: 'Element not found: ${sel}'});
@@ -1136,7 +1142,7 @@ export async function nativeClick({ selector, text, x, y, ref, doubleClick = fal
         });
       })()`;
     } else {
-      const safeText = text.replace(/'/g, "\\'");
+      const safeText = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
       jsExpr = `(function(){
         var el = mcpFindText('${safeText}', true) || mcpFindText('${safeText}', false);
         if (!el) return JSON.stringify({error: 'Element not found with text: ${safeText}'});
@@ -1194,7 +1200,7 @@ export async function nativeClick({ selector, text, x, y, ref, doubleClick = fal
 
 export async function fill({ selector, value, ref }) {
   if (ref) selector = refSelector(ref);
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   // Proper escaping order: backslashes first, then quotes
   const val = value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "");
   const result = await runJS(
@@ -1248,14 +1254,14 @@ export async function fill({ selector, value, ref }) {
 }
 
 export async function clearField({ selector }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   return runJS(
     `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found: ${sel}';if(el.isContentEditable){el.focus();document.execCommand('selectAll');document.execCommand('delete');el.dispatchEvent(new Event('input',{bubbles:true}));return 'Cleared (contenteditable)';}var t=el._valueTracker;if(t)t.setValue('x');var p=el.tagName==='TEXTAREA'?HTMLTextAreaElement.prototype:HTMLInputElement.prototype;var d=Object.getOwnPropertyDescriptor(p,'value');if(d&&d.set)d.set.call(el,'');else el.value='';el.dispatchEvent(new Event('input',{bubbles:true}));el.dispatchEvent(new Event('change',{bubbles:true}));el.dispatchEvent(new Event('blur',{bubbles:true}));return 'Cleared';})()`
   );
 }
 
 export async function selectOption({ selector, value }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   const val = value.replace(/'/g, "\\'");
   return runJS(
     `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found';el.focus();var t=el._valueTracker;if(t)t.setValue('');var d=Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype,'value');if(d&&d.set){d.set.call(el,'${val}');}else{el.value='${val}';}var m=false;for(var i=0;i<el.options.length;i++){if(el.options[i].value==='${val}'){el.selectedIndex=i;m=true;break;}}if(!m||el.value!=='${val}'){var norm=function(s){return s.replace(/[\\u200B-\\u200F\\u202A-\\u202E\\u2066-\\u2069\\uFEFF]/g,'').replace(/[\\u2010-\\u2015\\u2212\\uFE58\\uFE63\\uFF0D]/g,'-').replace(/\\s*-\\s*/g,'-').replace(/\\s+/g,' ').trim();};var cv=norm('${val}');for(var i=0;i<el.options.length;i++){if(norm(el.options[i].value)===cv||norm(el.options[i].text)===cv){el.selectedIndex=i;if(d&&d.set){d.set.call(el,el.options[i].value);}else{el.value=el.options[i].value;}m=true;break;}}if(!m){for(var i=0;i<el.options.length;i++){var nv=norm(el.options[i].value),nt=norm(el.options[i].text);if(nv.indexOf(cv)>=0||nt.indexOf(cv)>=0||cv.indexOf(nv)>=0||cv.indexOf(nt)>=0){if(i===0&&el.options.length>1)continue;el.selectedIndex=i;if(d&&d.set){d.set.call(el,el.options[i].value);}else{el.value=el.options[i].value;}m=true;break;}}}}el.dispatchEvent(new Event('input',{bubbles:true}));el.dispatchEvent(new Event('change',{bubbles:true}));el.dispatchEvent(new Event('blur',{bubbles:true}));return 'Selected: '+el.value+' (index '+el.selectedIndex+')';})()`
@@ -1423,7 +1429,7 @@ export async function pressKey({ key, modifiers = [] }) {
 export async function typeText({ text, selector, ref }) {
   if (ref) selector = refSelector(ref);
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     await runJS(`document.querySelector('${sel}')?.focus()`);
     // Quick poll for focus to settle (was 200ms fixed sleep)
     await new Promise((r) => setTimeout(r, 30));
@@ -1706,7 +1712,7 @@ export async function screenshot({ fullPage = false } = {}) {
 // ========== ELEMENT SCREENSHOT ==========
 
 export async function screenshotElement({ selector }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   // Use html2canvas-like approach: capture element via SVG foreignObject
   const result = await runJS(
     `(async function(){
@@ -1773,7 +1779,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),
@@ -2010,14 +2016,14 @@ export async function evaluate({ script }) {
 // ========== ELEMENT INFO ==========
 
 export async function getElementInfo({ selector }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   return runJS(
     `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found';var r=el.getBoundingClientRect();return JSON.stringify({tag:el.tagName,text:el.textContent.trim().substring(0,200),href:el.href||'',value:el.value||'',visible:r.width>0&&r.height>0,rect:{x:Math.round(r.x),y:Math.round(r.y),w:Math.round(r.width),h:Math.round(r.height)},attrs:Object.fromEntries([...el.attributes].map(function(a){return[a.name,a.value.substring(0,100)]}))})})()`
   );
 }
 
 export async function querySelectorAll({ selector, limit = 20 }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   return runJS(
     `JSON.stringify([...document.querySelectorAll('${sel}')].slice(0,${Number(limit)}).map(function(el,i){return{index:i,tag:el.tagName,text:el.textContent.trim().substring(0,100),href:el.href||undefined,value:el.value||undefined}}))`
   );
@@ -2028,7 +2034,7 @@ export async function querySelectorAll({ selector, limit = 20 }) {
 export async function hover({ selector, x, y, ref }) {
   if (ref) selector = refSelector(ref);
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found';el.scrollIntoView({block:'center'});el.dispatchEvent(new MouseEvent('mouseover',{bubbles:true}));el.dispatchEvent(new MouseEvent('mouseenter',{bubbles:true}));return 'Hovered: '+el.tagName;})()`
     );
@@ -2045,7 +2051,7 @@ export async function hover({ selector, x, y, ref }) {
 
 export async function handleDialog({ action = "accept", text }) {
   if (text !== undefined) {
-    const safeText = text.replace(/'/g, "\\'");
+    const safeText = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     await runJS(
       `window.__mcp_dialog_response='${safeText}';window.__origPrompt=window.prompt;window.prompt=function(){var r=window.__mcp_dialog_response;window.prompt=window.__origPrompt;return r;}`
     );
@@ -2159,7 +2165,7 @@ export async function uploadFile({ selector, filePath }) {
     end tell`
   ).catch(() => {}); // Ignore if no dialog open
 
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   const { basename, extname } = await import("node:path");
   const fileName = basename(filePath);
   const ext = extname(filePath).toLowerCase().replace(".", "");
@@ -2439,6 +2445,7 @@ export async function savePDF({ path: pdfPath }) {
 // instead of guessing CSS selectors. Much faster, no hallucination risk.
 
 let _snapshotGen = 0;
+export function getNextSnapshotGen() { return _snapshotGen++; }
 
 export async function takeSnapshot({ selector } = {}) {
   const gen = _snapshotGen++;
@@ -2793,7 +2800,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)}')`);
@@ -3181,7 +3194,7 @@ export async function overrideGeolocation({ latitude, longitude, accuracy = 100
 // ========== COMPUTED STYLES ==========
 
 export async function getComputedStyles({ selector, properties }) {
-  const sel = selector.replace(/'/g, "\\'");
+  const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
   const propsFilter = properties
     ? `.filter(function(p){return [${properties.map((p) => `'${p}'`).join(",")}].includes(p)})`
     : "";
@@ -3320,14 +3333,14 @@ export async function detectForms() {
 
 export async function scrollToElement({ selector, text, block = "center", timeout = 10000 }) {
   if (selector) {
-    const sel = selector.replace(/'/g, "\\'");
+    const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(function(){var el=document.querySelector('${sel}');if(!el)return 'Element not found: ${sel}';el.scrollIntoView({behavior:'smooth',block:'${block}'});var r=el.getBoundingClientRect();return 'Scrolled to: '+el.tagName+' at y='+Math.round(r.y);})()`
     );
   }
   if (text) {
     // Virtual DOM scroll: scroll down repeatedly until text appears (for Airtable, etc.)
-    const safeText = text.replace(/'/g, "\\'");
+    const safeText = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
     return runJS(
       `(async function(){
         var deadline = Date.now() + ${Number(timeout)};
@@ -3368,8 +3381,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 +3393,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 +3494,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"); });