safari-mcp 2.7.3 → 2.7.4

package/README.md

@@ -31,6 +31,8 @@
 
 </div>
 
+> **If Safari MCP saves you from running Chrome, consider giving it a star!** It helps others discover this project.
+
 ---
 
 > **TL;DR:** Use your real Safari with all your logins, cookies, and sessions. No headless browsers, no Chrome, no Puppeteer. Just pure AppleScript + JavaScript running natively on macOS — 60% less CPU/heat on Apple Silicon.
@@ -545,9 +547,26 @@ Your support funds:
 
 ---
 
+## Community
+
+Safari MCP is used by developers building AI agents on macOS. [Share your use case in Discussions](https://github.com/achiya-automation/safari-mcp/discussions)
+
+---
+
+## Spread the Word
+
+If you find Safari MCP useful, help others discover it:
+
+- [Star this repo](https://github.com/achiya-automation/safari-mcp)
+- [Share on Twitter/X](https://twitter.com/intent/tweet?text=Safari%20MCP%20%E2%80%94%20Stop%20running%20Chrome%20just%20so%20your%20AI%20agent%20can%20browse.%2080%20tools%2C%20native%20Safari%2C%2060%25%20less%20CPU.&url=https%3A%2F%2Fgithub.com%2Fachiya-automation%2Fsafari-mcp)
+- [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fachiya-automation%2Fsafari-mcp)
+- Write about it on dev.to or your blog
+
+---
+
 ## Star History
 
-If Safari MCP saved you from Chrome overhead, consider giving it a ⭐
+If Safari MCP saved you from Chrome overhead, consider giving it a star!
 
 [![Star History Chart](https://api.star-history.com/svg?repos=achiya-automation/safari-mcp&type=Date)](https://star-history.com/#achiya-automation/safari-mcp&Date)
 

package/extension/manifest.json

@@ -20,6 +20,12 @@
   "host_permissions": ["<all_urls>"],
   "content_scripts": [{
     "matches": ["<all_urls>"],
+    "exclude_matches": [
+      "*://*.linkedin.com/*",
+      "*://*.x.com/*",
+      "*://*.twitter.com/*",
+      "*://*.producthunt.com/*"
+    ],
     "js": ["content.js"],
     "run_at": "document_start",
     "world": "MAIN"

package/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Safari MCP — TypeScript type declarations
+ * Covers all ~83 registered tools and the MCP server export.
+ */
+
+// ========== CORE TYPES ==========
+
+export type MCPContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
+
+export interface MCPToolResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+export interface MCPToolInputSchema {
+  type: "object";
+  properties: Record<string, { type: string; description?: string; enum?: string[] }>;
+  required?: string[];
+}
+
+export interface MCPTool<TInput extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  description: string;
+  inputSchema: MCPToolInputSchema;
+  handler: (input: TInput) => Promise<MCPToolResult>;
+}
+
+
+// ========== TOOL INPUT TYPES ==========
+
+// Navigation
+export interface SafariNavigateInput { url: string }
+export interface SafariGoBackInput {}
+export interface SafariGoForwardInput {}
+export interface SafariReloadInput { hard?: boolean }
+export interface SafariNavigateAndReadInput { url: string; maxLength?: number; timeout?: number }
+
+// Page Info
+export interface SafariReadPageInput { selector?: string; maxLength?: number }
+export interface SafariGetSourceInput { maxLength?: number }
+export interface SafariSnapshotInput { selector?: string }
+
+// Click
+export interface SafariClickInput { ref?: string; selector?: string; text?: string; x?: number; y?: number }
+export interface SafariClickAndReadInput { text?: string; selector?: string; x?: number; y?: number; wait?: number; maxLength?: number }
+export interface SafariDoubleClickInput { selector?: string; x?: number; y?: number }
+export interface SafariRightClickInput { selector?: string; x?: number; y?: number }
+export interface SafariNativeClickInput { ref?: string; selector?: string; text?: string; x?: number; y?: number; doubleClick?: boolean }
+
+// Form Input
+export interface SafariFillInput { ref?: string; selector?: string; value: string }
+export interface SafariClearFieldInput { selector: string }
+export interface SafariSelectOptionInput { selector: string; value: string }
+export interface SafariFillFormField { selector: string; value: string }
+export interface SafariFillFormInput { fields: SafariFillFormField[] }
+
+// Keyboard
+export interface SafariPressKeyInput { key: string; modifiers?: string[] }
+export interface SafariTypeTextInput { text: string; ref?: string; selector?: string }
+
+// Code Editor
+export interface SafariReplaceEditorInput { text: string }
+
+// Screenshot
+export interface SafariScreenshotInput { fullPage?: boolean }
+export interface SafariScreenshotElementInput { selector: string }
+
+// Scroll
+export interface SafariScrollInput { direction?: "up" | "down"; amount?: number }
+export interface SafariScrollToInput { x?: number; y?: number }
+export interface SafariScrollToElementInput {
+  selector?: string;
+  text?: string;
+  block?: "start" | "center" | "end" | "nearest";
+  timeout?: number;
+}
+
+// Tab Management
+export interface SafariListTabsInput {}
+export interface SafariNewTabInput { url?: string }
+export interface SafariCloseTabInput {}
+export interface SafariSwitchTabInput { index: number }
+export interface SafariWaitForNewTabInput { timeout?: number; urlContains?: string }
+
+// Wait
+export interface SafariWaitForInput { selector?: string; text?: string; timeout?: number }
+export interface SafariWaitInput { ms: number }
+
+// Evaluate
+export interface SafariEvaluateInput { script: string }
+
+// Element Info
+export interface SafariGetElementInput { selector: string }
+export interface SafariQueryAllInput { selector: string; limit?: number }
+
+// Hover
+export interface SafariHoverInput { ref?: string; selector?: string; x?: number; y?: number }
+
+// Dialog
+export interface SafariHandleDialogInput { action?: "accept" | "dismiss"; text?: string }
+
+// Window
+export interface SafariResizeInput { width: number; height: number }
+
+// Drag
+export interface SafariDragInput {
+  sourceSelector?: string;
+  targetSelector?: string;
+  sourceX?: number;
+  sourceY?: number;
+  targetX?: number;
+  targetY?: number;
+}
+
+// File / Image
+export interface SafariUploadFileInput { selector: string; filePath: string }
+export interface SafariPasteImageInput { filePath: string }
+
+// Emulation
+export interface SafariEmulateInput { device?: string; width?: number; height?: number; userAgent?: string; scale?: number }
+export interface SafariResetEmulationInput {}
+
+// Cookies & Storage
+export interface SafariGetCookiesInput {}
+export interface SafariLocalStorageInput { key?: string }
+export interface SafariSetCookieInput {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: string;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+export interface SafariDeleteCookiesInput { name?: string; all?: boolean }
+export interface SafariSessionStorageInput { key?: string }
+export interface SafariSetSessionStorageInput { key: string; value: string }
+export interface SafariSetLocalStorageInput { key: string; value: string }
+export interface SafariDeleteLocalStorageInput { key?: string }
+export interface SafariDeleteSessionStorageInput { key?: string }
+export interface SafariExportStorageInput {}
+export interface SafariImportStorageInput { state: string }
+
+// Clipboard
+export interface SafariClipboardReadInput {}
+export interface SafariClipboardWriteInput { text: string }
+
+// Network
+export interface SafariNetworkInput { limit?: number }
+export interface SafariMockRouteResponse { status?: number; body?: string; contentType?: string }
+export interface SafariMockRouteInput { urlPattern: string; response: SafariMockRouteResponse }
+export interface SafariClearMocksInput {}
+export interface SafariStartNetworkCaptureInput {}
+export interface SafariNetworkDetailsInput { limit?: number; filter?: string }
+export interface SafariClearNetworkInput {}
+export interface SafariThrottleNetworkInput { profile?: string; latency?: number; downloadKbps?: number }
+
+// Console
+export interface SafariStartConsoleInput {}
+export interface SafariGetConsoleInput {}
+export interface SafariClearConsoleInput {}
+export interface SafariConsoleFilterInput { level: "log" | "warn" | "error" | "info" }
+
+// PDF
+export interface SafariSavePDFInput { path: string }
+
+// Accessibility
+export interface SafariAccessibilitySnapshotInput { selector?: string; maxDepth?: number }
+
+// Performance
+export interface SafariPerformanceMetricsInput {}
+export interface SafariCSSCoverageInput {}
+
+// Data Extraction
+export interface SafariExtractTablesInput { selector?: string; limit?: number }
+export interface SafariExtractMetaInput {}
+export interface SafariExtractImagesInput { limit?: number }
+export interface SafariExtractLinksInput { limit?: number; filter?: string }
+
+// Geolocation
+export interface SafariOverrideGeolocationInput { latitude: number; longitude: number; accuracy?: number }
+
+// Computed Styles
+export interface SafariGetComputedStyleInput { selector: string; properties?: string[] }
+
+// IndexedDB
+export interface SafariListIndexedDBsInput {}
+export interface SafariGetIndexedDBInput { dbName: string; storeName: string; limit?: number }
+
+// Form Detection
+export interface SafariDetectFormsInput {}
+
+// Batch / Combo Tools
+export interface SafariRunScriptStep { action: string; args?: Record<string, unknown> }
+export interface SafariRunScriptInput { steps: SafariRunScriptStep[] }
+export interface SafariClickAndWaitInput { selector?: string; text?: string; waitFor?: string; timeout?: number }
+export interface SafariFillAndSubmitInput { fields: SafariFillFormField[]; submitSelector?: string }
+export interface SafariAnalyzePageInput {}
+
+// ========== TAB INFO ==========
+
+export interface SafariTab {
+  index: number;
+  title: string;
+  url: string;
+}
+
+// ========== MODULE DECLARATION ==========
+export interface McpServer {
+  connect(transport: unknown): Promise<void>;
+  tool(name: string, description: string, schema: unknown, handler: (input: unknown) => Promise<MCPToolResult>): unknown;
+  close(): Promise<void>;
+}
+
+declare const server: McpServer;
+export default server;

package/index.js

@@ -526,11 +526,11 @@ async function _proxyToExtension(type, payload, timeoutMs = 30000) {
 }
 
 let _extensionLastPollTime = 0;
-// Detect stale HTTP connection (no poll in 10s = disconnected)
+// Detect stale HTTP connection (no poll in 30s = disconnected)
 // Only applies to primary instance (extension host) — not proxy mode
 setInterval(() => {
   if (_isExtensionHost && _extensionConnected && !_extensionWs && _extensionLastPollTime > 0) {
-    if (Date.now() - _extensionLastPollTime > 10000) {
+    if (Date.now() - _extensionLastPollTime > 30000) {
       _extensionConnected = false;
       _drainOnDisconnect("HTTP poll timeout");
       console.error("[Safari MCP] Extension disconnected (HTTP poll timeout)");
@@ -665,33 +665,53 @@ async function extensionOrFallback(extensionType, extensionPayload, fallbackFn)
       }
     }
   }
-  if (_extensionConnected && !_preferAppleScript) {
-    try {
-      const t0 = Date.now();
-      const tabUrl = safari.getActiveTabURL();
-      const payload = { ...extensionPayload, sessionId: SESSION_ID, ...(tabUrl ? { tabUrl } : {}) };
-      const timeout = _commandTimeouts[extensionType] || 30000;
-      const result = await sendToExtension(extensionType, payload, timeout);
-      const isCspError = typeof result === 'string' && (result.includes('unsafe-eval') || result.includes('trusted-types') || result.includes('Trusted Type') || result.includes('Content Security Policy'));
-      const isPermissionDenied = typeof result === 'string' && result.includes('__SCREENSHOT_PERMISSION_DENIED__');
-      const isFailed = result === null || (typeof result === 'string' && result.startsWith('Element not found'));
-      if (isPermissionDenied) {
-        console.error(`[Safari MCP] ${extensionType} permission denied (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else if (isCspError) {
-        console.error(`[Safari MCP] ${extensionType} CSP blocked: ${result?.substring(0, 100)} (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else if (isFailed && _nullMeansFailure.has(extensionType)) {
-        console.error(`[Safari MCP] ${extensionType} extension failed: ${result} (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else {
-        console.error(`[Safari MCP] ${extensionType} via extension (${Date.now() - t0}ms)`);
-        return result;
+
+  // ========== FOCUS PRESERVATION ==========
+  // Safari AppleScript/extension can steal focus (bring Safari window to front).
+  // Save the frontmost app before the operation and restore it after if Safari stole focus.
+  // Set focusGuard flag so inner osascript/runJSLarge calls skip their own focus logic.
+  const savedApp = await safari.saveFrontmostApp();
+  safari.setFocusGuard(true);
+
+  let result;
+  let usedExtension = false;
+  try {
+    if (_extensionConnected && !_preferAppleScript) {
+      try {
+        const t0 = Date.now();
+        const tabUrl = safari.getActiveTabURL();
+        const payload = { ...extensionPayload, sessionId: SESSION_ID, ...(tabUrl ? { tabUrl } : {}) };
+        const timeout = _commandTimeouts[extensionType] || 30000;
+        result = await sendToExtension(extensionType, payload, timeout);
+        const isCspError = typeof result === 'string' && (result.includes('unsafe-eval') || result.includes('trusted-types') || result.includes('Trusted Type') || result.includes('Content Security Policy'));
+        const isPermissionDenied = typeof result === 'string' && result.includes('__SCREENSHOT_PERMISSION_DENIED__');
+        const isFailed = result === null || (typeof result === 'string' && result.startsWith('Element not found'));
+        if (isPermissionDenied) {
+          console.error(`[Safari MCP] ${extensionType} permission denied (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else if (isCspError) {
+          console.error(`[Safari MCP] ${extensionType} CSP blocked: ${result?.substring(0, 100)} (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else if (isFailed && _nullMeansFailure.has(extensionType)) {
+          console.error(`[Safari MCP] ${extensionType} extension failed: ${result} (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else {
+          console.error(`[Safari MCP] ${extensionType} via extension (${Date.now() - t0}ms)`);
+          usedExtension = true;
+        }
+      } catch (err) {
+        console.error(`[Safari MCP] ${extensionType} extension failed: ${err.message} — falling back to AppleScript`);
       }
-    } catch (err) {
-      console.error(`[Safari MCP] ${extensionType} extension failed: ${err.message} — falling back to AppleScript`);
     }
+    if (!usedExtension) {
+      const t0 = Date.now();
+      result = await fallbackFn();
+      console.error(`[Safari MCP] ${extensionType} via AppleScript (${Date.now() - t0}ms)`);
+    }
+  } finally {
+    safari.setFocusGuard(false);
   }
-  const t0 = Date.now();
-  const result = await fallbackFn();
-  console.error(`[Safari MCP] ${extensionType} via AppleScript (${Date.now() - t0}ms)`);
+
+  // Restore focus if Safari stole it
+  await safari.restoreFocusIfStolen(savedApp);
+
   return result;
 }
 
@@ -1094,7 +1114,10 @@ server.tool(
   "Take a screenshot of a specific element (by CSS selector). Returns base64 PNG image.",
   { selector: z.string().describe("CSS selector of the element to capture") },
   async ({ selector }) => {
-    const base64 = await safari.screenshotElement({ selector });
+    const base64 = await extensionOrFallback(
+      "screenshot_element", { selector },
+      () => safari.screenshotElement({ selector })
+    );
     return {
       content: [{ type: "image", data: base64, mimeType: "image/jpeg" }],
     };
@@ -1582,7 +1605,7 @@ server.tool(
 
 server.tool(
   "safari_save_pdf",
-  "Save the current page as a PDF file. Uses Safari's native Export as PDF. WARNING: This STEALS FOCUS — Safari comes to foreground briefly for the Export menu.",
+  "Save the current page as a PDF file. Uses screencapture + PDF rendering (no Safari UI interaction needed).",
   { path: z.string().describe("Absolute file path to save the PDF (e.g. /Users/am/Downloads/page.pdf)") },
   async (args) => {
     const result = await safari.savePDF(args);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "safari-mcp",
-  "version": "2.7.3",
+  "version": "2.7.4",
   "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",
+  "types": "index.d.ts",
   "main": "index.js",
   "bin": {
     "safari-mcp": "index.js"
@@ -64,7 +65,8 @@
     "extension/",
     "glama.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/safari-helper.swift

@@ -278,12 +278,52 @@ while let line = readLine(strippingNewline: true) {
     continue
   }
 
+  // Handle getFrontApp — returns frontmost application bundle ID (native, ~0.1ms)
+  if json["getFrontApp"] != nil {
+    let frontApp = NSWorkspace.shared.frontmostApplication
+    respond(["result": frontApp?.localizedName ?? "", "bundleId": frontApp?.bundleIdentifier ?? ""])
+    continue
+  }
+
+  // Handle activateApp — activate a specific app by bundle ID (native, ~1ms)
+  // Used to restore focus to previous app instead of hiding Safari (less jarring)
+  if let bundleId = json["activateApp"] as? String {
+    if let app = NSRunningApplication.runningApplications(withBundleIdentifier: bundleId).first {
+      app.activate()
+      respond(["result": "activated"])
+    } else {
+      respond(["error": "app not found: \(bundleId)"])
+    }
+    continue
+  }
+
+  // Handle hideSafari — hide Safari to prevent focus stealing (native, ~1ms)
+  if json["hideSafari"] != nil {
+    if let safariApp = NSRunningApplication.runningApplications(withBundleIdentifier: "com.apple.Safari").first {
+      safariApp.hide()
+      respond(["result": "hidden"])
+    } else {
+      respond(["error": "Safari not running"])
+    }
+    continue
+  }
+
   // Handle AppleScript command
   guard let script = json["script"] as? String else {
-    respond(["error": "invalid input — expected 'script', 'click', or 'keyboard'"])
+    respond(["error": "invalid input — expected 'script', 'click', 'keyboard', 'getFrontApp', or 'hideSafari'"])
     continue
   }
 
+  // ========== FOCUS PRESERVATION ==========
+  // Save the frontmost app BEFORE executing AppleScript.
+  // Safari AppleScript can steal focus — we re-activate the previous app immediately after.
+  // Re-activating is better than hiding Safari because:
+  // 1. No jarring hide animation on Safari windows
+  // 2. User's Safari windows stay visible (just not in front)
+  // 3. Almost instantaneous — previous app just comes back to foreground
+  let savedBundleId = NSWorkspace.shared.frontmostApplication?.bundleIdentifier
+  let wasSafari = savedBundleId == "com.apple.Safari"
+
   guard let nsScript = NSAppleScript(source: script) else {
     respond(["error": "failed to compile AppleScript"])
     continue
@@ -292,6 +332,15 @@ while let line = readLine(strippingNewline: true) {
   var errorDict: NSDictionary?
   let result = nsScript.executeAndReturnError(&errorDict)
 
+  // Restore focus to previous app if Safari stole it (only if caller wasn't already in Safari)
+  if !wasSafari,
+     NSWorkspace.shared.frontmostApplication?.bundleIdentifier == "com.apple.Safari" {
+    if let savedId = savedBundleId,
+       let previousApp = NSRunningApplication.runningApplications(withBundleIdentifier: savedId).first {
+      previousApp.activate()
+    }
+  }
+
   if let error = errorDict {
     let msg = (error["NSAppleScriptErrorMessage"] as? String) ?? "AppleScript error"
     respond(["error": msg])

package/safari.js

@@ -177,6 +177,7 @@ let _targetWindowId = null;  // Numeric window ID (for CGEvent window targeting)
 let _targetWindowCacheTime = 0;
 const TARGET_WINDOW_CACHE_MS = 1000; // Short cache — fast detection of window changes
 let _profileWindowMissing = false; // True when profile window is not found
+let _focusGuardActive = false; // True when an outer caller already handles focus save/restore
 
 // Get the target window ref, falling back to 'front window' ONLY when no profile is configured
 function getTargetWindowRef() {
@@ -273,6 +274,56 @@ function getFallbackTarget() {
 // Quick JS execution — exposed for smart-wait checks in index.js
 export async function runJSQuick(js) { return runJS(js); }
 
+// ========== FOCUS PRESERVATION ==========
+// Safari AppleScript can steal focus (bring Safari window to front).
+// We hide Safari instead of activating the previous app — prevents ANY Safari window from flashing.
+export async function saveFrontmostApp() {
+  const app = await _helperGetFrontApp();
+  return app?.bundleId || null;
+}
+export async function restoreFocusIfStolen(savedBundleId) {
+  if (!savedBundleId || savedBundleId === "com.apple.Safari") return;
+  const current = await _helperGetFrontApp();
+  if (current?.bundleId === "com.apple.Safari") {
+    await _helperActivateApp(savedBundleId);
+  }
+}
+
+function _helperHideSafari(timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(); } }, timeout);
+    function cb() {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve();
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write('{"hideSafari":true}\n'); }
+    catch { clearTimeout(timer); resolve(); }
+  });
+}
+
+function _helperActivateApp(bundleId, timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(); } }, timeout);
+    function cb() {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve();
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write(JSON.stringify({ activateApp: bundleId }) + '\n'); }
+    catch { clearTimeout(timer); resolve(); }
+  });
+}
+
+export function setFocusGuard(active) { _focusGuardActive = active; }
 export function getActiveTabIndex() { return _activeTabIndex; }
 export function setActiveTabIndex(idx) { _activeTabIndex = idx; }
 export function getActiveTabURL() { return _activeTabURL; }
@@ -342,6 +393,10 @@ async function resolveActiveTab() {
 // Run AppleScript — uses execFile (safe, isolated, for complex scripts)
 async function osascript(script, { timeout = 10000 } = {}) {
   if (!(await isSafariRunning())) throw safariNotRunningError();
+  // Save frontmost app via daemon BEFORE subprocess (~0.1ms)
+  // Skip if an outer caller (extensionOrFallback) already handles focus
+  const shouldGuardFocus = !_focusGuardActive;
+  const frontApp = shouldGuardFocus ? await _helperGetFrontApp() : null;
   try {
     const { stdout } = await execFileAsync("osascript", ["-e", script], {
       timeout,
@@ -360,6 +415,14 @@ async function osascript(script, { timeout = 10000 } = {}) {
       }
     }
     throw new Error(`AppleScript error: ${err.stderr || err.message}`);
+  } finally {
+    // Re-activate previous app if Safari stole focus (~1ms)
+    if (shouldGuardFocus && frontApp?.bundleId && frontApp.bundleId !== 'com.apple.Safari') {
+      const current = await _helperGetFrontApp();
+      if (current?.bundleId === 'com.apple.Safari') {
+        _helperActivateApp(frontApp.bundleId).catch(() => {});
+      }
+    }
   }
 }
 
@@ -520,6 +583,26 @@ function _helperNativeKeyboard(keyCode, flags = [], windowId = 0, timeout = 5000
   });
 }
 
+// ========== NATIVE FOCUS OPERATIONS VIA DAEMON ==========
+// Uses NSRunningApplication — ~0.1ms for get, ~1ms for activate (vs ~90ms AppleScript)
+
+function _helperGetFrontApp(timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(null); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(null); } }, timeout);
+    function cb(line) {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      try { resolve(JSON.parse(line)); } catch { resolve(null); }
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write('{"getFrontApp":true}\n'); }
+    catch { clearTimeout(timer); resolve(null); }
+  });
+}
+
 // Get Safari window bounds, toolbar height, and window ID for coordinate calculation
 async function _getSafariWindowGeometry() {
   await refreshTargetWindow();
@@ -632,6 +715,10 @@ async function runJSLarge(js, { tabIndex, timeout = 30000 } = {}) {
   const appleScript = `tell application "Safari" to do JavaScript "${escaped}" in ${target}`;
   const tmpFile = join(tmpdir(), `safari-mcp-${Date.now()}.scpt`);
   await writeFile(tmpFile, appleScript, "utf8");
+  // Save frontmost app via daemon before subprocess execution
+  // Skip if outer caller already handles focus
+  const shouldGuard = !_focusGuardActive;
+  const frontApp = shouldGuard ? await _helperGetFrontApp() : null;
   try {
     const { stdout } = await execFileAsync("osascript", [tmpFile], {
       timeout,
@@ -640,6 +727,13 @@ async function runJSLarge(js, { tabIndex, timeout = 30000 } = {}) {
     return stdout.trim();
   } finally {
     unlink(tmpFile).catch(() => {});
+    // Re-activate previous app if Safari stole focus (~1ms)
+    if (shouldGuard && frontApp?.bundleId && frontApp.bundleId !== 'com.apple.Safari') {
+      const current = await _helperGetFrontApp();
+      if (current?.bundleId === 'com.apple.Safari') {
+        _helperActivateApp(frontApp.bundleId).catch(() => {});
+      }
+    }
   }
 }
 
@@ -1504,15 +1598,11 @@ export async function screenshot({ fullPage = false } = {}) {
     ).catch(() => null) : null;
 
     // On macOS Tahoe, screencapture -l may briefly steal focus.
-    // Save frontmost app so we can detect if focus was stolen and restore it.
-    let previousApp = null;
+    // Save frontmost app via daemon so we can hide Safari if it stole focus.
+    let previousBundleId = null;
     if (windowId) {
-      try {
-        // Use NSWorkspace via AppleScript (lighter than System Events — no AX needed)
-        previousApp = (await osascriptFast(
-          `tell application "System Events" to return name of first application process whose frontmost is true`
-        )).trim();
-      } catch (_) {}
+      const fa = await _helperGetFrontApp();
+      previousBundleId = fa?.bundleId || null;
     }
 
     if (windowId) {
@@ -1553,11 +1643,12 @@ export async function screenshot({ fullPage = false } = {}) {
             );
           }
         }
-        // Restore focus if screencapture stole it (common on macOS Tahoe)
-        if (previousApp && previousApp !== "Safari") {
-          await osascriptFast(
-            `tell application "${previousApp}" to activate`
-          ).catch(() => {});
+        // Re-activate previous app if screencapture stole focus (common on macOS Tahoe)
+        if (previousBundleId && previousBundleId !== "com.apple.Safari") {
+          const cur = await _helperGetFrontApp();
+          if (cur?.bundleId === "com.apple.Safari") {
+            await _helperActivateApp(previousBundleId).catch(() => {});
+          }
         }
         // Compress: convert PNG to JPEG (50% quality) + resize to max 1200px width
         // Cuts ~600KB PNG → ~60KB JPEG — critical for staying under 20MB context limit