safari-mcp 2.21.6 → 2.21.7

package/README.md

@@ -43,7 +43,7 @@ Native WebKit. ~60% less CPU. Background operation. 98 tools. One `npx` command.
 
 > 📰 **Featured on freeCodeCamp:** [How to Connect Your AI Coding Agent to a Browser on macOS](https://www.freecodecamp.org/news/how-to-connect-your-ai-coding-agent-to-a-browser-on-macos/) · [HackerNoon: Reverse-Engineering React, Shadow DOM, and CSP](https://hackernoon.com/i-had-to-reverse-engineer-react-shadow-dom-and-csp-to-automate-safari-without-chrome)
 
-> 🍎 **Apple shipped an official Safari MCP** (July 2026 — Safari Technology Preview 247+ and the Safari 27 beta). It's built on `safaridriver` for isolated debugging sessions. safari-mcp drives the **real Safari you're already logged into** — on the stable Safari that ships with macOS today, with 98 tools. See the full comparison below.
+> 🍎 **Apple ships an official Safari MCP** — `safaridriver --mcp`, first in Safari Technology Preview 247 (July 2026) and in stable Safari since 27.0. It drives an isolated automation session for debugging. safari-mcp drives the **real Safari you're already logged into** — your cookies and sessions, in the background, with 98 tools. See the full comparison below.
 
 ---
 
@@ -81,7 +81,7 @@ Not solicited testimonials — quotes lifted from the public issue tracker, each
 - macOS (any version with Safari)
 - Node.js 20+
 - Safari → Settings → Advanced → **Show features for web developers** ✓
-- Safari → Develop → **Allow JavaScript from Apple Events** ✓
+- Safari → Settings → Developer → **Allow JavaScript from Apple Events** ✓
 
 ### Install (one command)
 
@@ -631,23 +631,25 @@ Safari MCP runs locally on your Mac with minimal attack surface:
 
 ### vs Apple's Official Safari MCP (safaridriver)
 
-In July 2026 Apple shipped an **official** Safari MCP server built on `safaridriver` — first in Safari Technology Preview 247, and now also in the Safari 27 beta. That's great validation for the category — and it's built for a different job. Apple's server drives an **isolated WebDriver automation session** for debugging; safari-mcp drives the **real Safari you're already logged into**.
+In July 2026 Apple shipped an **official** Safari MCP server built on `safaridriver` — first in Safari Technology Preview 247, and in stable Safari since 27.0. That's great validation for the category — and it's built for a different job. Apple's server drives an **isolated WebDriver automation session** for debugging; safari-mcp drives the **real Safari you're already logged into**.
 
-It has not reached a stable Safari release yet: on macOS 26.5.2 with Safari 26.5.2, `safaridriver --help` lists `--port`, `--bidi`, `--enable` and `--diagnose`, and no `--mcp` (verified 2026-07-23). Check your own machine with `safaridriver --help | grep mcp` before assuming either way.
+On macOS 27.0 with Safari 27.0, `safaridriver --help` lists `--mcp` and its `tools/list` answers with 17 entries (verified 2026-09-15); Safari 26.5.2 had no `--mcp` (verified 2026-07-23). Check your own machine with `safaridriver --help | grep mcp`.
+
+> **Running both?** Apple's setup guide registers its server under the name `safari-mcp` (`claude mcp add safari-mcp -- /usr/bin/safaridriver --mcp`) — the same name as this package. Give one of them a different name, e.g. `claude mcp add safari-webdriver -- /usr/bin/safaridriver --mcp`, so your client doesn't overwrite one with the other or leave you guessing which server answered.
 
 | | 🦁 safari-mcp *(this repo)* | Apple `safaridriver --mcp` |
 |---|:---:|:---:|
 | **Your real logins / cookies** | ✅ Your actual Safari | ⚠️ Isolated automation session — no access to AutoFill or browsing activity |
-| **Runs on** | ✅ Stable Safari, every Mac | ⚠️ Safari Technology Preview 247+ or the Safari 27 beta — not in stable Safari 26.5 |
+| **Runs on** | ✅ Stable Safari, every Mac | ⚠️ Safari 27 or later, or Safari Technology Preview 247+ |
 | **Background (no focus steal)** | ✅ Yes | ❌ Dedicated window with a "controlled by automation" banner |
-| **Tools** | **98** | ~17 |
+| **Tools** | **98** | 17 |
 | **Storage** (cookies, localStorage, IndexedDB) | ✅ 10 tools | ❌ |
 | **Network mocking + throttling** | ✅ Yes | ❌ Read-only network inspection |
 | **Device emulation** (iPhone, iPad) | ✅ Yes | ⚠️ Viewport + media type only |
-| **Setup** | `npx safari-mcp` | Enable "remote automation and external agents", then point your client at that build's `safaridriver --mcp` |
+| **Setup** | `npx safari-mcp` | Enable "Allow remote automation and external agents" in Safari's Developer settings, then point your client at `safaridriver --mcp` |
 | **Official Apple support** | ❌ Community (MIT) | ✅ Apple, WebDriver-standard |
 
-> **When Apple's server is the right pick:** you specifically want a clean-room, WebDriver-standard session for compatibility debugging and you already run a preview or beta build. **For everything else — daily automation on the browser you're already signed into, on the Safari that shipped with your Mac — safari-mcp is built for exactly that.**
+> **When Apple's server is the right pick:** you specifically want a clean-room, WebDriver-standard session for compatibility debugging on Safari 27 or later. **For everything else — daily automation on the browser you're already signed into, in the background — safari-mcp is built for exactly that.**
 
 ### Why Safari MCP and Not the Other Safari MCP Projects?
 
@@ -759,12 +761,12 @@ Alternatively, open `xcode/Safari MCP/Safari MCP.xcodeproj` directly in Xcode, s
 
 Then in Safari:
 1. Safari → Settings → Advanced → enable **Show features for web developers**
-2. Safari → Develop → **Allow Unsigned Extensions** (required each Safari restart)
+2. Safari → Settings → Developer → **Allow unsigned extensions** (required each Safari restart)
 3. Safari → Settings → Extensions → enable **Safari MCP Bridge**
 
 The extension connects automatically to the first local bridge whose declared Safari profile matches its own. The default bridge ports are `9224`, `9228`, `9232`, and `9236`; a single-profile setup normally uses `9224`.
 
-> **Note:** "Allow Unsigned Extensions" resets every time Safari restarts. You'll need to re-enable it in the Develop menu after each restart. The extension itself stays installed.
+> **Note:** "Allow unsigned extensions" resets every time Safari restarts. You'll need to re-enable it in Safari → Settings → Developer after each restart. The extension itself stays installed.
 
 **Toolbar icon status:**
 - **ON** — connected to MCP server
@@ -779,16 +781,16 @@ Safari MCP needs these one-time permissions:
 
 | Permission | Where | Why |
 |-----------|-------|-----|
-| JavaScript from Apple Events | Safari → Develop menu | Required for `do JavaScript` |
+| JavaScript from Apple Events | Safari → Settings → Developer | Required for `do JavaScript` |
 | Automation → Safari | System Settings → Privacy & Security → Automation | Required for all AppleScript-backed tools |
-| Screen Recording | System Settings → Privacy & Security → Screen Recording | Required for `safari_screenshot` |
-| Accessibility (safari-helper) | System Settings → Privacy & Security → Accessibility | Required for `safari_native_click`, `safari_native_keyboard`, `safari_native_hover` and `safari_save_pdf` |
+| Screen Recording | System Settings → Privacy & Security → Screen & System Audio Recording | Required for `safari_screenshot` without the extension, and for `safari_save_pdf` |
+| Accessibility (safari-helper) | System Settings → Privacy & Security → Accessibility (named **Device Control and Data Access** on macOS 27) | Required for `safari_native_click`, `safari_native_keyboard`, `safari_native_hover` and `safari_save_pdf` |
 
 ### Granting Accessibility to safari-helper (required for `safari_native_*`)
 
 The `safari_native_click`, `safari_native_keyboard` and `safari_native_hover` tools inject OS-level `CGEvent` events into Safari without stealing focus. macOS requires the underlying helper binary to be approved in **Accessibility** before those events can reach a non-frontmost window.
 
-1. Open **System Settings → Privacy & Security → Accessibility**.
+1. Open **System Settings → Privacy & Security → Accessibility** (on macOS 27 the pane is named **Device Control and Data Access**).
 2. Click `+` (unlock with your password if needed).
 3. Navigate to the helper binary and add it:
    - npm global install: `$(npm root -g)/safari-mcp/safari-helper`
@@ -818,11 +820,12 @@ That call registers the Terminal app in the Automation database and then trigger
 
 | Issue | Fix |
 |-------|-----|
-| "AppleScript error" | Enable "Allow JavaScript from Apple Events" in Safari → Develop |
+| "AppleScript error" | Enable "Allow JavaScript from Apple Events" in Safari → Settings → Developer |
 | "Not authorized to send Apple events to Safari" | Grant Automation → Safari to your IDE (see above) |
 | "Not authorized" after `npm update` | Updating changes the binary's cdhash — macOS silently revokes Automation permission. Re-run the `osascript` one-liner above to re-grant it |
 | `safari_native_click` reports success but page doesn't react | Add `safari-helper` to **System Settings → Privacy & Security → Accessibility** (see [Granting Accessibility](#granting-accessibility-to-safari-helper-required-for-safari_native_) above). Confirm by attaching a `click` listener with `{capture:true}` in the page console — without the grant, no `isTrusted: true` event fires |
-| Screenshots empty | Grant Screen Recording permission to Terminal/VS Code |
+| Screenshots empty | Grant Screen & System Audio Recording to Terminal/VS Code — or, when safari-mcp runs as a LaunchAgent, to the `node` binary itself (a Homebrew node upgrade changes its path, so re-grant after upgrading). `safari_doctor` names the exact binary |
+| Extension missing after enabling "Allow unsigned extensions" (macOS 27) | Known macOS 27.0 issue (183044008): with the setting on, rebuild the extension app (see [Installing the Extension](#installing-the-extension)) and it appears |
 | Tab not found | Call `safari_list_tabs` to refresh tab indices |
 | Hebrew keyboard issues | All typing uses JS events — immune to keyboard layout |
 | HTTPS blocked | `safari_navigate` auto-tries HTTPS first, falls back to HTTP |

package/extension/background.js

@@ -1260,44 +1260,50 @@ async function handleCommand(type, payload) {
       // Strategy: try captureVisibleTab WITHOUT focusing the window first.
       // If it fails, fall back to AppleScript screencapture -l (which also doesn't steal focus).
       // NEVER use browser.windows.update({ focused: true }) — it steals user's keyboard/mouse.
-      let captureWindowId = _profileWindowId || null;
-      // captureVisibleTab only sees the window's selected tab, so ours must be selected for
-      // the capture — but the selection belongs to the user when they browse this window.
-      // Remember what they had selected and put it back (the AppleScript path already does
-      // this via _withTargetTabFronted; this path used to leave our tab in front).
-      let restoreTabId = null;
-      if (tabId) {
+      return _withTabSelected(tabId, async (windowId) => {
+        // Use JPEG with quality 50 to reduce size (~600KB PNG → ~60KB JPEG)
         try {
-          const tabInfo = await browser.tabs.get(tabId);
-          captureWindowId = tabInfo.windowId;
-          if (!tabInfo.active) {
-            const [selected] = await browser.tabs.query({ active: true, windowId: tabInfo.windowId });
-            if (selected && selected.id !== tabId) restoreTabId = selected.id;
-            // Only selects the tab — does NOT bring the Safari window to the foreground
-            await browser.tabs.update(tabId, { active: true });
-            await new Promise(r => setTimeout(r, 150));
-          }
-        } catch (_) {}
-      }
-      // Use JPEG with quality 50 to reduce size (~600KB PNG → ~60KB JPEG)
-      try {
-        const dataUrl = await browser.tabs.captureVisibleTab(captureWindowId, {
-          format: "jpeg",
-          quality: 50,
-        });
-        return dataUrl.split(",")[1];
-      } catch (screenshotErr) {
-        // Permission lost or window not visible — signal MCP to use AppleScript fallback
-        // AppleScript uses screencapture -l<windowId> which captures without stealing focus
-        const msg = screenshotErr.message || "";
-        if (msg.includes("permission") || msg.includes("screencapture") || msg.includes("Screen Recording") || msg.includes("visible")) {
+          const dataUrl = await browser.tabs.captureVisibleTab(windowId, {
+            format: "jpeg",
+            quality: 50,
+          });
+          return dataUrl.split(",")[1];
+        } catch (_) {
+          // Permission lost or window not visible — signal MCP to use AppleScript fallback
+          // AppleScript uses screencapture -l<windowId> which captures without stealing focus
           return "__SCREENSHOT_PERMISSION_DENIED__";
         }
-        // Any other error also falls back — better than stealing focus
-        return "__SCREENSHOT_PERMISSION_DENIED__";
-      } finally {
-        if (restoreTabId !== null) browser.tabs.update(restoreTabId, { active: true }).catch(() => {});
-      }
+      });
+    }
+
+    case "screenshot_element": {
+      // A profile session refuses the AppleScript crop, so crop here: capture the tab as
+      // "screenshot" does and cut out the element, measured while the tab is selected.
+      let box = null;
+      const dataUrl = await _withTabSelected(tabId, async (windowId) => {
+        box = await execInTab(async (selector) => {
+          const el = (window.__mcpDeepQuery || document.querySelector.bind(document))(selector);
+          if (!el) return null;
+          el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          const r = el.getBoundingClientRect();
+          let left = r.left, top = r.top;
+          // A same-origin iframe match is measured in its frame's viewport: add the frame's
+          // position and border to get the page viewport the capture shows.
+          for (let view = el.ownerDocument.defaultView; view.frameElement; view = view.parent) {
+            const frame = view.frameElement.getBoundingClientRect();
+            left += frame.left + view.frameElement.clientLeft;
+            top += frame.top + view.frameElement.clientTop;
+          }
+          return { left, top, width: r.width, height: r.height, viewportWidth: window.innerWidth };
+        }, [payload.selector], tabId);
+        if (!box) return null;
+        return browser.tabs.captureVisibleTab(windowId, { format: "png" }).catch(() => null);
+      });
+      if (!box) return "Element not found: " + payload.selector;
+      // Same signal as "screenshot": outside a profile the AppleScript crop can still try.
+      if (!dataUrl) return "__SCREENSHOT_PERMISSION_DENIED__";
+      return (await _cropCapture(dataUrl, box)) || "Element has no visible area: " + payload.selector;
     }
 
     // --- Click & Input ---
@@ -1437,11 +1443,11 @@ async function handleCommand(type, payload) {
             }
             el = exactBest || partialBest;
           }
-        } else if (x !== undefined && y !== undefined) {
+        } else if (x != null && y != null) {
           el = document.elementFromPoint(x, y);
         }
 
-        if (!el) return "Element not found" + (ref ? " ref=" + ref : "") + (selector ? " selector=" + selector : "") + (text ? ' text="' + text + '"' : "") + (x !== undefined ? " x=" + x + " y=" + y : "");
+        if (!el) return "Element not found" + (ref ? " ref=" + ref : "") + (selector ? " selector=" + selector : "") + (text ? ' text="' + text + '"' : "") + (x != null ? " x=" + x + " y=" + y : "");
 
         // --- Visibility check ---
         const cs = window.getComputedStyle(el);
@@ -1562,69 +1568,16 @@ async function handleCommand(type, payload) {
         return "Navigated to: " + href;
       }
 
-      // Fallback: if element not found in main frame, try all frames (cross-origin iframes)
+      // Fallback: the content bridge runs in the top frame's ISOLATED world, so it misses
+      // child documents and closed shadow roots. Probe every frame read-only, then click
+      // once in the one frame (and the one world) that can reach the target.
       if (result && (result.startsWith("Element not found") || result === "No click target")) {
-        const iframeArgs = [payload.selector, payload.text, payload.ref];
-        const iframeResult = await execInFirstMatchingFrameMutating((selector, text, ref) => {
-          const deepQuery = (query, root = document) => {
-            const direct = root.querySelector(query);
-            if (direct) return direct;
-            for (const host of root.querySelectorAll("*")) {
-              if (!host.shadowRoot) continue;
-              const nested = deepQuery(query, host.shadowRoot);
-              if (nested) return nested;
-            }
-            return null;
-          };
-          if (ref) {
-            const safeRef = String(ref).replace(/["\\]/g, "\\$&");
-            return !!deepQuery('[data-mcp-ref="' + safeRef + '"]');
-          }
-          if (selector) return !!deepQuery(selector);
-          if (!text) return false;
-          const candidates = document.querySelectorAll("button, a, [role='button'], input[type='submit']");
-          for (let i = 0; i < candidates.length; i++) {
-            const value = (candidates[i].innerText || candidates[i].textContent || "").trim();
-            if (value && (value === text || value.includes(text) || text.includes(value))) return true;
-          }
-          return false;
-        }, iframeArgs, (selector, text, ref) => {
-          const deepQuery = (query, root = document) => {
-            const direct = root.querySelector(query);
-            if (direct) return direct;
-            for (const host of root.querySelectorAll("*")) {
-              if (!host.shadowRoot) continue;
-              const nested = deepQuery(query, host.shadowRoot);
-              if (nested) return nested;
-            }
-            return null;
-          };
-          let el = null;
-          if (ref) {
-            const safeRef = String(ref).replace(/["\\]/g, "\\$&");
-            el = deepQuery('[data-mcp-ref="' + safeRef + '"]');
-          } else if (selector) {
-            el = deepQuery(selector);
-          } else if (text) {
-            // Search interactive elements by text
-            const candidates = document.querySelectorAll("button, a, [role='button'], input[type='submit']");
-            for (let i = 0; i < candidates.length; i++) {
-              const t = (candidates[i].innerText || candidates[i].textContent || "").trim();
-              if (t === text) { el = candidates[i]; break; }
-            }
-            // Fuzzy: contains match
-            if (!el) {
-              for (let i = 0; i < candidates.length; i++) {
-                const t = (candidates[i].innerText || candidates[i].textContent || "").trim();
-                if (t && (t.includes(text) || text.includes(t))) { el = candidates[i]; break; }
-              }
-            }
-          }
-          if (!el) return null;
-          el.scrollIntoView({ block: "center", behavior: "instant" });
-          el.click();
-          return "Clicked (iframe): " + el.tagName + (el.textContent ? ' "' + el.textContent.trim().substring(0, 50) + '"' : "");
-        }, iframeArgs, tabId);
+        const target = [payload.selector, payload.text, payload.ref];
+        const iframeResult = await execInFirstMatchingFrameMutating(
+          _clickFrameAction, [...target, "probe"],
+          _clickFrameAction, [...target, "click"],
+          tabId
+        );
         if (iframeResult) return iframeResult;
       }
       return result;
@@ -1905,7 +1858,10 @@ async function handleCommand(type, payload) {
       const result = await execInTab((text, selector) => {
         if (selector) {
           const el = (window.__mcpDeepQuery || document.querySelector.bind(document))(selector);
-          if (!el) return "Element not found: " + selector;
+          // __mcpDeepQuery also returns fields from same-origin iframes, but every strategy
+          // below types through THIS document (execCommand, activeElement) — into whichever
+          // top-frame field last had focus. A miss sends the frame fallback to type there.
+          if (!el || el.ownerDocument !== document) return "Element not found: " + selector;
           el.focus();
         }
 
@@ -2420,7 +2376,7 @@ async function handleCommand(type, payload) {
         const dq = window.__mcpDeepQuery || document.querySelector.bind(document);
         let el = null;
         if (selector) el = dq(selector);
-        else if (x !== undefined && y !== undefined) el = document.elementFromPoint(x, y);
+        else if (x != null && y != null) el = document.elementFromPoint(x, y);
         if (!el) return "Element not found: " + (selector || "x=" + x + ",y=" + y);
         el.scrollIntoView({ block: "center" });
         const r = el.getBoundingClientRect();
@@ -2443,7 +2399,7 @@ async function handleCommand(type, payload) {
         const dq = window.__mcpDeepQuery || document.querySelector.bind(document);
         let el = null;
         if (selector) el = dq(selector);
-        else if (x !== undefined && y !== undefined) el = document.elementFromPoint(x, y);
+        else if (x != null && y != null) el = document.elementFromPoint(x, y);
         if (!el) return "Element not found: " + (selector || "x=" + x + ",y=" + y);
         el.scrollIntoView({ block: "center" });
         const r = el.getBoundingClientRect();
@@ -3742,6 +3698,9 @@ async function sendContentCommand(tabId, type, payload, timeoutMs = 1500) {
     // injected into such a tab. Schedule a small, self-contained DOM action and
     // return BEFORE it runs: page-listener exceptions then cannot be misreported as
     // an executeScript failure, and a filled form survives an extension repair.
+    // The target is resolved before returning, though: this lookup sees only the top
+    // document, so a miss must reach the caller's frame / closed-shadow fallback
+    // instead of reporting "Scheduled" for an action that can never find its element.
     const scheduled = await browser.scripting.executeScript({
       target: { tabId },
       world: "ISOLATED",
@@ -3765,10 +3724,10 @@ async function sendContentCommand(tabId, type, payload, timeoutMs = 1500) {
           }
           return null;
         };
+        const el = find();
+        if (!el) return { ok: false, result: "Element not found" };
         setTimeout(() => {
           try {
-            const el = find();
-            if (!el) return;
             if (commandType === "mcp-content-fill") {
               const value = String(commandPayload.value ?? "");
               el.focus();
@@ -3822,16 +3781,25 @@ const _INJECTION_BLOCK_TTL_MS = 6 * 60 * 60 * 1000;
 function _originKey(url) {
   try { return new URL(String(url || "")).origin; } catch { return ""; }
 }
-function _withInjectionDeadline(promise, ms = MAIN_WORLD_INJECT_MS) {
+function _withInjectionDeadline(promise, ms = MAIN_WORLD_INJECT_MS, message = "MAIN world injection stalled") {
   let timer;
   return Promise.race([
     promise.finally(() => clearTimeout(timer)),
     new Promise((_, reject) => {
-      timer = setTimeout(() => reject(new Error("MAIN world injection stalled")), ms);
+      timer = setTimeout(() => reject(new Error(message)), ms);
     }),
   ]);
 }
 
+// Safari's scripting.executeScript drops `undefined` entries from `args` and shifts every
+// later argument left: a ref-only click probe `(selector, text, ref)` received the ref as
+// its selector, and wait_for by text received its text as a selector. Every executor
+// sends args through here; injected functions test these values with truthiness or
+// `!= null`, so null carries the same meaning and keeps each argument in its position.
+function _scriptArgs(args) {
+  return Array.from(args || [], (value) => (value === undefined ? null : value));
+}
+
 async function execInTab(func, args = [], tabId = null) {
   const id = tabId || (await getActiveTab()).id;
   try {
@@ -3856,13 +3824,13 @@ async function execInTab(func, args = [], tabId = null) {
     let results;
     try {
       results = await _withInjectionDeadline(
-        browser.scripting.executeScript({ target: { tabId: id }, world: "MAIN", func, args })
+        browser.scripting.executeScript({ target: { tabId: id }, world: "MAIN", func, args: _scriptArgs(args) })
       );
     } catch (mainErr) {
       if (!/injection stalled/.test(mainErr?.message || "")) throw mainErr;
       console.warn("Safari MCP: MAIN world stalled, retrying ISOLATED on tabId=" + id);
       results = await _withInjectionDeadline(
-        browser.scripting.executeScript({ target: { tabId: id }, world: "ISOLATED", func, args })
+        browser.scripting.executeScript({ target: { tabId: id }, world: "ISOLATED", func, args: _scriptArgs(args) })
       );
       // If ISOLATED stalls too the page blocks injection outright, and there is nothing
       // generic left to try — execInTab relays a FUNCTION, which the content bridge
@@ -3892,7 +3860,7 @@ async function execInTabIsolated(func, args = [], tabId = null) {
     target: { tabId: id },
     world: "ISOLATED",
     func,
-    args,
+    args: _scriptArgs(args),
   });
   try {
     let results;
@@ -3932,7 +3900,7 @@ async function _executeAllFrames(func, args = [], tabId = null) {
     target: { tabId: id, allFrames: true },
     world,
     func,
-    args,
+    args: _scriptArgs(args),
   }));
 
   try {
@@ -3949,12 +3917,14 @@ async function _executeAllFrames(func, args = [], tabId = null) {
 
 // Mutating fallbacks must never broadcast an action to every frame or retry it after
 // an ambiguous executeScript rejection. First locate one frame with a read-only probe,
-// then dispatch once to that concrete frame in ISOLATED world. If the one dispatch has
-// an unknown outcome, fail terminally so a caller can verify state before retrying.
+// then dispatch once to that concrete frame in ISOLATED world — or in MAIN when the probe
+// answers "MAIN", because its match sits in a closed shadow root ISOLATED cannot reach.
+// If the one dispatch has an unknown outcome, fail terminally so a caller can verify
+// state before retrying.
 async function execInFirstMatchingFrameMutating(matchFunc, matchArgs, func, args, tabId = null) {
   const id = tabId || (await getActiveTab()).id;
   const matches = await _executeAllFrames(matchFunc, matchArgs, id);
-  const match = matches.find((entry) => !entry?.error && entry?.result === true);
+  const match = matches.find((entry) => !entry?.error && (entry?.result === true || entry?.result === "MAIN"));
   if (!match) return null;
   if (!Number.isInteger(match.frameId)) {
     throw new Error("Matched frame has no stable frameId; refusing mutating iframe fallback");
@@ -3963,9 +3933,9 @@ async function execInFirstMatchingFrameMutating(matchFunc, matchArgs, func, args
   try {
     const results = await _withInjectionDeadline(browser.scripting.executeScript({
       target: { tabId: id, frameIds: [match.frameId] },
-      world: "ISOLATED",
+      world: match.result === "MAIN" ? "MAIN" : "ISOLATED",
       func,
-      args,
+      args: _scriptArgs(args),
     }));
     const first = results[0];
     if (first?.error) throw new Error(first.error);
@@ -3975,6 +3945,53 @@ async function execInFirstMatchingFrameMutating(matchFunc, matchArgs, func, args
   }
 }
 
+// Click fallback for targets the top-frame content bridge cannot see: child documents and
+// closed shadow roots. Safari serializes it into each frame, so it stays self-contained.
+// Probe mode is read-only and names the world that can reach the match — a closed shadow
+// root is visible only to MAIN, through the getter content.js installs at document_start.
+function _clickFrameAction(selector, text, ref, mode) {
+  const getShadowRoot = window.__mcpGetShadowRoot || ((host) => host.shadowRoot);
+  const roots = [];
+  const collect = (root) => {
+    roots.push(root);
+    for (const host of root.querySelectorAll("*")) {
+      const shadow = getShadowRoot(host);
+      if (shadow) collect(shadow);
+    }
+  };
+  collect(document);
+
+  let el = null;
+  const query = ref ? '[data-mcp-ref="' + String(ref).replace(/["\\]/g, "\\$&") + '"]' : selector;
+  if (query) {
+    for (const root of roots) {
+      el = root.querySelector(query);
+      if (el) break;
+    }
+  } else if (text) {
+    const label = (candidate) => (candidate.innerText || candidate.textContent || "").trim();
+    const candidates = roots.flatMap((root) => [...root.querySelectorAll("button, a, [role='button'], input[type='submit']")]);
+    el = candidates.find((candidate) => label(candidate) === text) ||
+      candidates.find((candidate) => {
+        const value = label(candidate);
+        return value && (value.includes(text) || text.includes(value));
+      });
+  }
+
+  if (mode === "probe") {
+    if (!el) return false;
+    for (let root = el.getRootNode(); root instanceof ShadowRoot; root = root.host.getRootNode()) {
+      if (root.mode === "closed") return "MAIN";
+    }
+    return true;
+  }
+  if (!el) return null;
+  el.scrollIntoView({ block: "center", behavior: "instant" });
+  el.click();
+  return "Clicked" + (window === top ? "" : " (iframe)") + ": " + el.tagName +
+    (el.textContent ? ' "' + el.textContent.trim().substring(0, 50) + '"' : "");
+}
+
 // Shared exact-frame probe and MAIN-world one-shot popup capture. It stays
 // self-contained because Safari serializes it into each frame; closure references
 // are unavailable there. Probe mode is read-only. Capture mode dispatches one click,
@@ -4187,7 +4204,7 @@ async function execInExactMatchingFrameMainOnce(matchFunc, matchArgs, func, args
       target: { tabId: id, frameIds: [matches[0].frameId] },
       world: "MAIN",
       func,
-      args,
+      args: _scriptArgs(args),
     }));
     const first = results[0];
     if (first?.error) throw new Error(first.error);
@@ -4376,6 +4393,60 @@ async function waitForTabLoad(tabId, timeout = 30000) {
   });
 }
 
+// captureVisibleTab only sees the window's selected tab, so ours must be selected for
+// the capture — but the selection belongs to the user when they browse this window.
+// Remember what they had selected and put it back (the AppleScript path already does
+// this via _withTargetTabFronted; the extension path used to leave our tab in front).
+// `capture(windowId)` runs while the tab is selected.
+async function _withTabSelected(tabId, capture) {
+  let windowId = _profileWindowId || null;
+  let restoreTabId = null;
+  if (tabId) {
+    try {
+      const tabInfo = await browser.tabs.get(tabId);
+      windowId = tabInfo.windowId;
+      if (!tabInfo.active) {
+        const [selected] = await browser.tabs.query({ active: true, windowId: tabInfo.windowId });
+        if (selected && selected.id !== tabId) restoreTabId = selected.id;
+        // Only selects the tab — does NOT bring the Safari window to the foreground
+        await browser.tabs.update(tabId, { active: true });
+        await new Promise(r => setTimeout(r, 150));
+      }
+    } catch (_) {}
+  }
+  try {
+    return await capture(windowId);
+  } finally {
+    if (restoreTabId !== null) browser.tabs.update(restoreTabId, { active: true }).catch(() => {});
+  }
+}
+
+// Cuts a viewport box (CSS pixels) out of a captureVisibleTab data URL, clipped to what
+// the capture shows. Returns JPEG base64, or null when nothing of the box is on screen.
+async function _cropCapture(dataUrl, box) {
+  // Not through an <img>: in Safari's extension background page it never finished loading
+  // the capture, and the command hung until the worker's 330s guard with every later
+  // command queued behind it. Decode the bytes directly, and bound the decode so a stall
+  // fails this command instead of the worker.
+  const bytes = Uint8Array.from(atob(dataUrl.slice(dataUrl.indexOf(",") + 1)), (c) => c.charCodeAt(0));
+  const image = await _withInjectionDeadline(
+    createImageBitmap(new Blob([bytes])), 10000, "screenshot_element: decoding the tab capture stalled"
+  );
+  // Scale from the capture itself rather than devicePixelRatio, so the crop follows the
+  // resolution Safari actually rendered.
+  const scale = image.width / box.viewportWidth;
+  const left = Math.max(0, Math.round(box.left * scale));
+  const top = Math.max(0, Math.round(box.top * scale));
+  const width = Math.min(image.width, Math.round((box.left + box.width) * scale)) - left;
+  const height = Math.min(image.height, Math.round((box.top + box.height) * scale)) - top;
+  if (width <= 0 || height <= 0) return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  canvas.getContext("2d").drawImage(image, left, top, width, height, 0, 0, width, height);
+  return canvas.toDataURL("image/jpeg", 0.8).split(",")[1];
+}
+
 function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }

package/extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "Safari MCP Bridge",
   "description": "Connects AI agents to Safari — fast JS execution, screenshots, clicks with your real cookies/logins",
-  "version": "2.10.12",
+  "version": "2.10.15",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",

package/glama.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "Safari MCP Server",
-  "description": "Native Safari browser automation for AI agents. 97 tools via AppleScript — zero overhead, keeps logins, runs silently in background.",
+  "description": "Native Safari browser automation for AI agents. 98 tools via AppleScript — zero overhead, keeps logins, runs silently in background.",
   "repository": "https://github.com/achiya-automation/safari-mcp",
   "homepage": "https://github.com/achiya-automation/safari-mcp",
   "author": "achiya-automation",

package/index.js

@@ -2608,16 +2608,14 @@ server.tool(
 
 server.tool(
   "safari_screenshot_element",
-  "Take a screenshot of a specific element (by CSS selector). Returns base64 PNG image.",
+  "Take a screenshot of a specific element (by CSS selector). Returns a base64 image.",
   { selector: z.string().describe("CSS selector of the element to capture"), receipt: z.string().optional().describe("Tab receipt from safari_new_tab — pins this call to that tab (survives reconnects/subagents)"), },
   async ({ selector, receipt }) => {
-    const base64 = await extensionOrFallback(
+    // The extension crops to JPEG, the AppleScript path to PNG; a miss comes back as text.
+    return imageResult(await extensionOrFallback(
       "screenshot_element", { selector, ..._explicitReceipt({ receipt }) },
       () => safari.screenshotElement({ selector })
-    );
-    return {
-      content: [{ type: "image", data: base64, mimeType: "image/jpeg" }],
-    };
+    ));
   }
 );
 
@@ -3168,13 +3166,12 @@ server.tool(
 
 server.tool(
   "safari_emulate",
-  "Emulate a mobile device by resizing window and setting user agent. Devices: iphone-14, iphone-14-pro-max, ipad, ipad-pro, pixel-7, galaxy-s24. Or use custom width/height.",
+  `Emulate a mobile device: sizes the Safari window to the device's CSS viewport and overrides navigator.userAgent/platform/maxTouchPoints (iOS/iPadOS 27 values) in the current page — JavaScript only: the HTTP User-Agent header is unchanged and a reload or navigation clears it. Devices: ${Object.keys(safari.EMULATION_DEVICES).join(", ")}. Or pass width/height (and userAgent).`,
   {
-    device: z.string().optional().describe("Device name: iphone-14, ipad, pixel-7, galaxy-s24, etc."),
+    device: z.string().optional().describe("Device name from the list in the description, e.g. iphone-18-pro, iphone-air, ipad-pro-11"),
     width: z.coerce.number().optional().describe("Custom viewport width"),
     height: z.coerce.number().optional().describe("Custom viewport height"),
     userAgent: z.string().optional().describe("Custom user agent string"),
-    scale: z.coerce.number().optional().describe("Initial scale (default: 1)"),
   },
   async (args) => {
     _assertTabOwnership("emulate");
@@ -3185,7 +3182,7 @@ server.tool(
 
 server.tool(
   "safari_reset_emulation",
-  "Reset device emulation back to desktop mode",
+  "Reset device emulation: restores the window size from before safari_emulate and removes its navigator overrides (no reload)",
   {},
   async () => {
     _assertTabOwnership("reset_emulation");

package/injected-validators.js

@@ -32,7 +32,13 @@ export const VIEWPORT_SCRIPT = `(function(){
       return JSON.stringify({viewport: content, attrs: attrs, ok: issues.length===0, errors: errors, warnings: warnings, issues: issues});
     })()`;
 
+// Safari 27 stopped listing constructable (adopted) style sheets in document.styleSheets, per
+// the CSSOM spec (Safari 27.0 release notes, 174583340). Stylesheet scans append them
+// explicitly, skipping any an older engine still lists, so they see the same rules on both.
+export const ALL_SHEETS_FN = `function allSheets(){var out=[].slice.call(document.styleSheets);var ad=document.adoptedStyleSheets||[];for(var a=0;a<ad.length;a++){if(out.indexOf(ad[a])===-1)out.push(ad[a]);}return out;}`;
+
 export const SAFE_AREA_SCRIPT = `(function(){
+      ${ALL_SHEETS_FN}
       if (!document.body) return JSON.stringify({error:'No document.body yet'});
       var probe = document.createElement('div');
       probe.style.cssText = 'position:fixed;top:env(safe-area-inset-top,0px);right:env(safe-area-inset-right,0px);bottom:env(safe-area-inset-bottom,0px);left:env(safe-area-inset-left,0px);pointer-events:none;visibility:hidden;';
@@ -44,7 +50,7 @@ export const SAFE_AREA_SCRIPT = `(function(){
       var viewportFitCover = meta ? ((meta.getAttribute('content')||'').indexOf('viewport-fit=cover') !== -1) : false;
       var usedInCSS = false;
       try {
-        var sheets = document.styleSheets;
+        var sheets = allSheets();
         for (var i=0; i<sheets.length; i++) {
           try {
             var rules = sheets[i].cssRules;
@@ -68,17 +74,18 @@ export const PWA_SCRIPT = `(function(){
       var manifest = getLink('manifest');
       var has180 = touchIcons.some(function(i){return i.sizes==='180x180';});
       var checks = [];
-      checks.push({pass: capable==='yes', label:'apple-mobile-web-app-capable', detail: capable==='yes' ? 'standalone mode enabled' : 'not set to yes — opens in Safari, not standalone'});
+      checks.push({pass: capable==='yes' || manifest!==null, label:'standalone launch (apple-mobile-web-app-capable or manifest)', detail: capable==='yes' ? 'apple-mobile-web-app-capable=yes' : (manifest!==null ? 'manifest linked — its display member sets standalone' : 'neither set — iOS/iPadOS 26+ still open any Home Screen site as a web app by default; iOS 18 and older open it in Safari')});
       checks.push({pass: touchIcons.length>0, label:'apple-touch-icon', detail: touchIcons.length>0 ? (touchIcons.length+' icon(s): '+touchIcons.map(function(i){return i.sizes;}).join(', ')+(has180?'':' (missing 180x180 for iPhone)')) : 'none — iOS uses a screenshot as the icon'});
-      checks.push({pass: themeColor!==null, label:'theme-color', detail: themeColor!==null ? ('set to '+themeColor) : 'not set — Safari 15+ tints the tab bar with it'});
+      checks.push({pass: themeColor!==null, label:'theme-color', detail: (themeColor!==null ? ('set to '+themeColor) : 'not set') + ' — Chrome and Android color their UI with it; Safari 26+ ignores it and tints its bars from the page background'});
       checks.push({pass: statusBar!==null, label:'apple-mobile-web-app-status-bar-style', detail: statusBar!==null ? ('set to '+statusBar) : 'not set — defaults to black-on-white'});
-      checks.push({pass: manifest!==null, label:'web app manifest', detail: manifest!==null ? ('found: '+manifest) : 'no manifest link — required for PWA install prompts'});
+      checks.push({pass: manifest!==null, label:'web app manifest', detail: manifest!==null ? ('found: '+manifest) : 'no manifest link — the Home Screen web app gets no name, id, scope or display mode of its own (Safari has no install prompt to trigger)'});
       checks.push({pass: splash>0, label:'apple-touch-startup-image', detail: splash>0 ? (splash+' splash screen(s)') : 'none — white screen while the app loads'});
       var passed = checks.filter(function(c){return c.pass;}).length;
       return JSON.stringify({passed: passed, total: checks.length, checks: checks});
     })()`;
 
 export const WEBKIT_COMPAT_SCRIPT = `(function(){
+      ${ALL_SHEETS_FN}
       var seen = {};
       function collectFromStyle(style){
         for (var k=0; k<style.length; k++){
@@ -96,7 +103,7 @@ export const WEBKIT_COMPAT_SCRIPT = `(function(){
           if (rule.cssRules){ try { processRules(rule.cssRules); } catch(e){} }
         }
       }
-      var sheets = document.styleSheets;
+      var sheets = allSheets();
       for (var i=0; i<sheets.length; i++){ try { processRules(sheets[i].cssRules); } catch(e){} }
       var inline = document.querySelectorAll('[style]');
       for (var n=0; n<inline.length; n++) collectFromStyle(inline[n].style);

package/mcp-helpers.js

@@ -15,11 +15,15 @@ if (window.__mcpVersion !== 6) {
   window.mcpCollectRoots = function() {
     if (!window.__mcpRootsDirty && window.__mcpCachedRoots) return window.__mcpCachedRoots;
     var roots = [];
+    // Closed roots come from the getter the extension's content.js installs at
+    // document_start; without it mcpFindRef fell back to coordinates and returned the host.
+    var getShadowRoot = window.__mcpGetShadowRoot || function(el) { return el.shadowRoot; };
     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);
+        var shadow = getShadowRoot(all[i]);
+        if (shadow) collect(shadow);
       }
     }
     collect(document);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "safari-mcp",
-  "version": "2.21.6",
+  "version": "2.21.7",
   "mcpName": "io.github.achiya-automation/safari-mcp",
-  "description": "Safari browser automation for AI agents \u2014 native macOS, zero Chrome overhead. 97 tools via AppleScript + JavaScript.",
+  "description": "Safari browser automation for AI agents \u2014 native macOS, zero Chrome overhead. 98 tools via AppleScript + JavaScript.",
   "type": "module",
   "main": "index.js",
   "bin": {

package/response.js

@@ -18,10 +18,16 @@ export const jsonResult = (r) => ({
   content: [{ type: "text", text: JSON.stringify(r, null, 2) }],
 });
 
-/** Image response (base64 + mime type). */
-export const imageResult = (data, mimeType = "image/jpeg") => ({
-  content: [{ type: "image", data, mimeType }],
-});
+/**
+ * Image response for base64 JPEG or PNG, labelled by the data's own magic bytes. Anything
+ * else is a message ("Element not found: …"): sent as image bytes the client cannot decode
+ * it and the reason is lost, so it is raised as the tool's error instead.
+ */
+export const imageResult = (data) => {
+  const mimeType = /^\/9j\//.test(data) ? "image/jpeg" : /^iVBORw0KGgo/.test(data) ? "image/png" : null;
+  if (!mimeType) throw new Error(String(data || "no image data returned"));
+  return { content: [{ type: "image", data, mimeType }] };
+};
 
 /** Error response — sets `isError` so the MCP client renders it as a failure. */
 export const errorResult = (msg) => ({

package/safari.js

@@ -11,7 +11,7 @@ import { readFile, writeFile, unlink, appendFile, mkdir } from "node:fs/promises
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
-import { VIEWPORT_SCRIPT, SAFE_AREA_SCRIPT, PWA_SCRIPT, WEBKIT_COMPAT_SCRIPT } from "./injected-validators.js";
+import { VIEWPORT_SCRIPT, SAFE_AREA_SCRIPT, PWA_SCRIPT, WEBKIT_COMPAT_SCRIPT, ALL_SHEETS_FN } from "./injected-validators.js";
 import { escJsSingleQuote, escAppleScriptString } from "./injected-escape.js";
 import { currentSessionId } from "./session-context.js";
 import { allowUserTabs } from "./ownership-state.js";
@@ -3595,7 +3595,7 @@ async function _screenshotFronted({ fullPage }) {
     }
 
     // Final fallback: throw with clear message for the retry logic in index.js
-    throw new Error("screencapture failed — Screen Recording permission may have been lost. Grant permission in System Settings → Privacy & Security → Screen Recording, then restart Safari.");
+    throw new Error("screencapture failed — Screen Recording permission may have been lost. Grant permission in System Settings → Privacy & Security → Screen & System Audio Recording, then restart Safari.");
   } finally {
     await unlink(tmpFile).catch(() => {});
   }
@@ -4600,70 +4600,118 @@ export async function pasteImageFromFile({ filePath }) {
 
 // ========== EMULATE (VIEWPORT) ==========
 
-export async function emulate({ device, width, height, userAgent, scale = 1 }) {
-  await refreshTargetWindow();
-  const devices = {
-    "iphone-14": { width: 390, height: 844, ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" },
-    "iphone-14-pro-max": { width: 430, height: 932, ua: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" },
-    "ipad": { width: 820, height: 1180, ua: "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" },
-    "ipad-pro": { width: 1024, height: 1366, ua: "Mozilla/5.0 (iPad; CPU OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" },
-    "pixel-7": { width: 412, height: 915, ua: "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36" },
-    "galaxy-s24": { width: 412, height: 915, ua: "Mozilla/5.0 (Linux; Android 14; SM-S921B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36" },
-  };
-
-  const d = device ? devices[device.toLowerCase()] : null;
-  const w = d ? d.width : (width || 375);
-  const h = d ? d.height : (height || 812);
-  const ua = d ? d.ua : (userAgent || "");
-
-  // Resize Safari window to match device
-  await osascript(
-    `tell application "Safari" to set bounds of ${getTargetWindowRef()} to {0, 0, ${w}, ${h + 100}}`
-  );
+// Captured from Mobile Safari on the iOS/iPadOS 27.0 simulator (Xcode 27, 2026-09-15). Since
+// iOS 26 Safari freezes the OS token (18_6 at 26.0, 18_7 from 26.2) and only Version/ moves.
+// iPadOS requests desktop sites, so an iPad sends the Mac UA and platform "MacIntel"; pages tell
+// it apart by navigator.maxTouchPoints, which the override sets too.
+const UA_IOS_27 = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/27.0 Mobile/15E148 Safari/604.1";
+const UA_IPADOS_27 = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/27.0 Safari/605.1.15";
+const _iphone = (width, height) => ({ width, height, ua: UA_IOS_27, platform: "iPhone", touchPoints: 5 });
+const _ipad = (width, height) => ({ width, height, ua: UA_IPADOS_27, touchPoints: 5 });
+
+// Portrait CSS viewport (screen points). The iphone-14* / ipad / ipad-pro names predate iOS 27
+// and stay so existing callers keep working.
+export const EMULATION_DEVICES = {
+  "iphone-18-pro": _iphone(402, 874),
+  "iphone-18-pro-max": _iphone(440, 956),
+  "iphone-air": _iphone(420, 912),
+  "iphone-17": _iphone(402, 874),
+  "iphone-17e": _iphone(390, 844),
+  "iphone-16": _iphone(393, 852),
+  "iphone-14": _iphone(390, 844),
+  "iphone-14-pro-max": _iphone(430, 932),
+  "ipad": _ipad(820, 1180),
+  "ipad-air-11": _ipad(820, 1180),
+  "ipad-air-13": _ipad(1024, 1366),
+  "ipad-pro-11": _ipad(834, 1210),
+  "ipad-pro-13": _ipad(1032, 1376),
+  "ipad-pro": _ipad(1024, 1366),
+  "pixel-7": { width: 412, height: 915, ua: "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36" },
+  "galaxy-s24": { width: 412, height: 915, ua: "Mozilla/5.0 (Linux; Android 14; SM-S921B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36" },
+};
 
-  // Override viewport meta and user agent if specified
-  if (ua) {
-    await runJS(
-      `Object.defineProperty(navigator,'userAgent',{get:function(){return '${ua.replace(/'/g, "\\'")}'},configurable:true})`
-    );
+// Pure. An unknown name used to fall through to a bare 375×812 window with no UA while the
+// result still echoed the requested device — refuse it instead.
+export function resolveEmulation({ device, width, height, userAgent } = {}) {
+  if (device) {
+    const name = String(device).trim().toLowerCase();
+    if (!Object.hasOwn(EMULATION_DEVICES, name)) {
+      throw new Error(`Unknown device "${device}". Available: ${Object.keys(EMULATION_DEVICES).join(", ")} — or pass width/height (and userAgent).`);
+    }
+    return { name, ...EMULATION_DEVICES[name] };
   }
+  const size = (v, fallback) => (Number(v) > 0 ? Math.round(Number(v)) : fallback);
+  return { name: "custom", width: size(width, 375), height: size(height, 812), ua: userAgent || "" };
+}
 
-  // Set viewport meta tag
-  await runJS(
-    `(function(){var m=document.querySelector('meta[name=viewport]');if(!m){m=document.createElement('meta');m.name='viewport';document.head.appendChild(m);}m.content='width=${w},initial-scale=${scale}';})()`
-  );
+// Pure. The getters carry a marker so resetEmulation() removes only what emulate() added.
+export function buildNavigatorOverrideJS({ ua, platform, touchPoints } = {}) {
+  const props = [];
+  if (ua) props.push(`['userAgent','${escJsSingleQuote(ua)}']`);
+  if (platform) props.push(`['platform','${escJsSingleQuote(platform)}']`);
+  if (touchPoints != null) props.push(`['maxTouchPoints',${Number(touchPoints)}]`);
+  if (!props.length) return "";
+  return `(function(){[${props.join(",")}].forEach(function(p){var g=function(){return p[1]};g.__mcpEmulated=true;Object.defineProperty(navigator,p[0],{get:g,configurable:true})});return navigator.userAgent})()`;
+}
 
-  // Reload to apply changes, then wait for load — polled from Node (`do JavaScript`
-  // can't await an in-page loop).
-  const navIndex = _st().activeTabIndex;
-  await runJS("location.reload()", { tabIndex: navIndex });
-  await new Promise(r => setTimeout(r, 200));
-  await _pollReadyAndRead(navIndex);
-
-  return JSON.stringify({
-    device: device || "custom",
-    width: w,
-    height: h,
-    userAgent: ua ? ua.substring(0, 60) + "..." : "(default)",
+export const RESET_NAVIGATOR_JS = "(function(){['userAgent','platform','maxTouchPoints'].forEach(function(k){var d=Object.getOwnPropertyDescriptor(navigator,k);if(d&&d.get&&d.get.__mcpEmulated)delete navigator[k]});return navigator.userAgent})()";
+
+export async function emulate(args) {
+  const target = resolveEmulation(args);
+  await refreshTargetWindow();
+  const winRef = getTargetWindowRef();
+  const st = _st();
+  // Remember the user's window once, so reset_emulation puts it back instead of forcing 1440×900.
+  // Comma-joined explicitly: the helper daemon returns "" for an AppleScript list.
+  if (!st.preEmulationBounds) {
+    const b = String(await osascriptFast(
+      `tell application "Safari"\n  set b to bounds of ${winRef}\n  return (item 1 of b as text) & "," & (item 2 of b as text) & "," & (item 3 of b as text) & "," & (item 4 of b as text)\nend tell`
+    ).catch(() => "")).trim();
+    if (/^-?\d+,-?\d+,-?\d+,-?\d+$/.test(b)) st.preEmulationBounds = b;
+  }
+  // Size from the measured browser chrome, so the page viewport — not the window — matches.
+  let chrome = 90;
+  try {
+    const c = Number(await runJS("(window.outerHeight - window.innerHeight) + ''"));
+    if (Number.isFinite(c) && c >= 50 && c <= 200) chrome = c;
+  } catch (_e) { /* keep the Safari 26/27 default */ }
+  await osascriptFast(`tell application "Safari" to set bounds of ${winRef} to {0, 0, ${target.width}, ${target.height + chrome}}`);
+
+  // No reload after this: a reload gives the page a fresh navigator and silently drops the
+  // override — which is what the old reload-to-apply step did to every emulation.
+  const overrideJS = buildNavigatorOverrideJS(target);
+  if (overrideJS) await runJS(overrideJS);
+
+  const actual = await _relayoutAndMeasure();
+  const notes = [];
+  if (overrideJS) notes.push("navigator.userAgent/platform/maxTouchPoints are overridden for this page's JavaScript only: the HTTP User-Agent header is unchanged, and a reload or navigation clears the override — call safari_emulate again after navigating.");
+  if (actual && actual[0] > target.width) notes.push(`Safari kept the window wider than ${target.width}px (page viewport ${actual[0]}px).`);
+  if (actual && actual[1] < target.height) notes.push(`The screen is too short for a ${target.height}px viewport — the page gets ${actual[1]}px.`);
+  return JSON.stringify({ device: target.name, viewport: { requested: [target.width, target.height], actual }, userAgent: target.ua || "(unchanged)", notes });
+}
+
+// A background tab keeps its old layout — innerWidth, media queries, even outerWidth — until
+// it is shown (seen on Safari 27: 1512px after a resize to 402 until the tab was fronted). Show
+// ours for a moment (selection restored, Safari never activated) so the new size sticks.
+async function _relayoutAndMeasure() {
+  let size = null;
+  await _withTargetTabFronted(async () => {
+    await new Promise((r) => setTimeout(r, 250));
+    try { size = JSON.parse(await runJS("JSON.stringify([window.innerWidth, window.innerHeight])")); } catch (_e) { /* reported as null */ }
   });
+  return size;
 }
 
 export async function resetEmulation() {
   await refreshTargetWindow();
-  // Reset user agent — remove the defineProperty override set by emulate()
-  await runJS(
-    "try{var d=Object.getOwnPropertyDescriptor(Navigator.prototype,'userAgent');if(d){Object.defineProperty(navigator,'userAgent',d);}else{delete navigator.userAgent;}}catch(_){}"
-  );
-  // Maximize window
-  await osascript(
-    `tell application "Safari" to set bounds of ${getTargetWindowRef()} to {0, 0, 1440, 900}`
-  );
-  // Reload + wait for load — polled from Node (`do JavaScript` can't await an in-page loop).
-  const navIndex = _st().activeTabIndex;
-  await runJS("location.reload()", { tabIndex: navIndex });
-  await new Promise(r => setTimeout(r, 200));
-  await _pollReadyAndRead(navIndex);
-  return "Emulation reset to desktop";
+  const st = _st();
+  const bounds = st.preEmulationBounds || "0,0,1440,900";
+  st.preEmulationBounds = null;
+  await osascriptFast(`tell application "Safari" to set bounds of ${getTargetWindowRef()} to {${bounds}}`);
+  // Deleting the marked getters restores Navigator.prototype's — no reload, so page state survives.
+  await runJS(RESET_NAVIGATOR_JS);
+  const viewport = await _relayoutAndMeasure();
+  return `Emulation reset: window bounds {${bounds}}, viewport ${viewport ? viewport.join("×") : "unknown"}, navigator overrides removed`;
 }
 
 // ========== CONSOLE CAPTURE ==========
@@ -5619,10 +5667,12 @@ export async function listIndexedDBs() {
 export async function getCSSCoverage() {
   return evalReturningJSON(
     `
+      ${ALL_SHEETS_FN}
       var results = [];
-      for (var i = 0; i < document.styleSheets.length; i++) {
+      var sheets = allSheets();
+      for (var i = 0; i < sheets.length; i++) {
+        var sheet = sheets[i];
         try {
-          var sheet = document.styleSheets[i];
           var rules = sheet.cssRules || sheet.rules;
           var total = rules.length;
           var used = 0;
@@ -5637,7 +5687,7 @@ export async function getCSSCoverage() {
             } else { used++; }
           }
           results.push({
-            href: sheet.href || '(inline)',
+            href: sheet.href || (sheet.ownerNode ? '(inline)' : '(adopted)'),
             totalRules: total,
             usedRules: used,
             unusedRules: total - used,
@@ -5645,7 +5695,7 @@ export async function getCSSCoverage() {
             unusedSelectors: unused.slice(0, 20),
           });
         } catch(e) {
-          results.push({ href: sheet.href || '(inline)', error: 'CORS blocked' });
+          results.push({ href: sheet.href || (sheet.ownerNode ? '(inline)' : '(adopted)'), error: 'CORS blocked' });
         }
       }
       return JSON.stringify(results);
@@ -5735,7 +5785,7 @@ export async function doctor() {
     else aeDetail = m.slice(0, 80);
   }
   add(aeOk, "Apple Events / Automation", aeDetail,
-    "System Settings > Privacy & Security > Automation → enable Safari for your terminal/host app; and Safari > Develop > Allow JavaScript from Apple Events.");
+    "System Settings > Privacy & Security > Automation → enable Safari for your terminal/host app; and Safari > Settings > Developer > Allow JavaScript from Apple Events.");
 
   // 3-5. Native helper daemon + Accessibility + Screen Recording (one preflight round-trip)
   let pf = null, pfErr = "";
@@ -5751,10 +5801,13 @@ export async function doctor() {
     "It auto-restarts; if this persists, reinstall safari-mcp.");
   add(!!pf && pf.accessibility === true, "Accessibility (native clicks)",
     pf ? (pf.accessibility ? "CGEvent posting permitted" : "NOT permitted — native clicks silently no-op (the #29 root cause)") : "unknown (helper not responding)",
-    "System Settings > Privacy & Security > Accessibility → enable safari-helper, then retry.");
+    "System Settings > Privacy & Security > Accessibility (named \"Device Control and Data Access\" on macOS 27) → enable safari-helper, then retry.");
+  // macOS attributes the capture to whoever launched this process: the terminal/IDE for a
+  // stdio server, but node itself under launchd (a LaunchAgent daemon has ppid 1) — and a
+  // Homebrew node upgrade changes that path, so the grant has to follow the new binary.
   add(!!pf && pf.screenRecording === true, "Screen Recording (screenshots)",
-    pf ? (pf.screenRecording ? "permitted" : "NOT permitted — screenshots will be blank/blocked") : "unknown (helper not responding)",
-    "System Settings > Privacy & Security > Screen Recording → enable your terminal/host app.");
+    pf ? (pf.screenRecording ? "permitted" : "NOT permitted — screenshots taken through AppleScript and safari_save_pdf fail (extension screenshots don't need it)") : "unknown (helper not responding)",
+    `System Settings > Privacy & Security > Screen & System Audio Recording → enable ${process.ppid === 1 ? `node at ${process.execPath} (this server runs under launchd)` : "the terminal/IDE that launched this server"}.`);
 
   // 6. Helper codesign identity — a stale/ad-hoc id breaks the Accessibility grant on reinstall
   let idOk = false, idDetail = "";

package/scripts/postinstall.cjs

@@ -77,14 +77,14 @@ ensureCodesign();
 if (process.env.CI || process.env.SAFARI_MCP_SILENT_INSTALL === "1") process.exit(0);
 
 const msg = `
-${c.bold}${c.cyan}🦁 Safari MCP installed${c.reset} ${c.dim}— 96 native browser tools for AI agents${c.reset}
+${c.bold}${c.cyan}🦁 Safari MCP installed${c.reset} ${c.dim}— native browser tools for AI agents${c.reset}
 
 ${c.bold}Next steps:${c.reset}
-  1. Enable Safari → Develop → ${c.yellow}Allow JavaScript from Apple Events${c.reset}
+  1. Enable Safari → Settings → Developer → ${c.yellow}Allow JavaScript from Apple Events${c.reset}
   2. Add to your MCP client config:
      ${c.dim}{ "mcpServers": { "safari": { "command": "npx", "args": ["safari-mcp"] } } }${c.reset}
   3. ${c.bold}For native_click / native_keyboard${c.reset} (no focus stealing):
-     System Settings → Privacy & Security → ${c.yellow}Accessibility${c.reset} → add
+     System Settings → Privacy & Security → ${c.yellow}Accessibility${c.reset} ${c.dim}(macOS 27: Device Control and Data Access)${c.reset} → add
      ${c.dim}node_modules/safari-mcp/safari-helper${c.reset} ${c.dim}(or the global install path)${c.reset}
 
 ${c.bold}${c.magenta}⭐ Found this useful?${c.reset} A star helps others discover it: