preflight-ios-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,406 @@
+# Preflight MCP
+
+The most comprehensive MCP (Model Context Protocol) server for iOS Simulator automation. Gives AI agents like Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible tool full control over iOS Simulators — tap, swipe, type, read accessibility trees, inspect app data, capture screenshots, record video, manage devices, and debug apps in real time.
+
+**57 tools** across 10 categories. Zero cursor interference — works silently in the background while you use your Mac.
+
+Inspired by [Playwright MCP](https://github.com/anthropics/mcp-server-playwright) for web automation — Preflight brings the same structured accessibility-first approach to iOS.
+
+[![npm version](https://img.shields.io/npm/v/preflight-ios-mcp)](https://www.npmjs.com/package/preflight-ios-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why Preflight?
+
+- **No disk clutter** — Screenshots and video frames return directly in chat. No folders filling up.
+- **AI-optimized** — Images compressed for minimal token usage. Video → key frames (most AI models can't view video files).
+- **Accessibility-first** — Like Playwright's `browser_snapshot`, use `simulator_snapshot` to understand the screen without vision models.
+- **Cursor-free** — Touch injection via idb (IndigoHID) — your Mac cursor stays put.
+- **57 tools** — From basic tap/swipe to Dynamic Type testing, biometric enrollment, crash log analysis.
+
+## Quick Start
+
+### Prerequisites
+
+- macOS with Xcode and iOS Simulator installed
+- Node.js 18+
+- [Facebook idb](https://fbidb.io/) (recommended for cursor-free operation)
+
+### Install idb (recommended)
+
+```bash
+brew tap facebook/fb
+brew install idb-companion
+pip3 install fb-idb
+```
+
+> Without idb, the server falls back to CGEvent mouse injection (works but briefly moves your cursor).
+
+### Install via npm (recommended)
+
+```bash
+npm install -g preflight-ios-mcp
+```
+
+### Build from Source
+
+```bash
+git clone https://github.com/EthanAckerman-git/Preflight.git
+cd Preflight
+npm install
+npm run build
+```
+
+## Setup by IDE / AI Tool
+
+> Add your Python bin directory to `PATH` if idb was installed via pip (e.g., `~/Library/Python/3.x/bin`).
+
+### Claude Code
+
+```bash
+claude mcp add preflight -- npx preflight-ios-mcp
+```
+
+Or add to **.mcp.json** in your project root:
+
+```json
+{
+  "mcpServers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["preflight-ios-mcp"],
+      "env": {
+        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to **~/.cursor/mcp.json** (global) or **.cursor/mcp.json** (per-project):
+
+```json
+{
+  "mcpServers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["preflight-ios-mcp"],
+      "env": {
+        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Then in Cursor: **Settings → MCP** — verify "preflight" shows as connected.
+
+### Windsurf
+
+Add to **~/.codeium/windsurf/mcp_config.json**:
+
+```json
+{
+  "mcpServers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["preflight-ios-mcp"],
+      "env": {
+        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Then in Windsurf: **Settings → Cascade → MCP** — verify "preflight" appears.
+
+### VS Code (Copilot / Cline / Continue)
+
+Add to **.vscode/mcp.json** in your project:
+
+```json
+{
+  "servers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["preflight-ios-mcp"],
+      "env": {
+        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+For **Cline** (VS Code extension), add to **~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json**:
+
+```json
+{
+  "mcpServers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["preflight-ios-mcp"],
+      "env": {
+        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+### Zed
+
+Add to **~/.config/zed/settings.json**:
+
+```json
+{
+  "context_servers": {
+    "preflight": {
+      "command": {
+        "path": "npx",
+        "args": ["preflight-ios-mcp"],
+        "env": {
+          "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+        }
+      }
+    }
+  }
+}
+```
+
+### Any MCP-Compatible Client
+
+Preflight uses the standard MCP stdio transport. Configure your client to run:
+
+```bash
+npx preflight-ios-mcp
+```
+
+Set the `PATH` environment variable to include idb's location for cursor-free touch injection.
+
+## Tools Reference
+
+### Observation (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_screenshot` | Take a JPEG screenshot optimized for AI chat (~200-400KB). Returns image inline. |
+| `simulator_list_devices` | List simulators with name, UDID, state, runtime. Filter: `booted`, `available`, `all`. |
+| `simulator_list_apps` | List installed apps with bundle IDs. Toggle `includeSystem` for system apps. |
+| `simulator_app_info` | Get app metadata: name, version, bundle path, data path, type. |
+| `simulator_get_clipboard` | Read the simulator's clipboard text. |
+| `simulator_get_screen_info` | Window geometry, coordinate mapping, scale factor. Debug tap accuracy. |
+
+### User Interaction (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_tap` | Tap at (x, y) in simulator screen points. Cursor-free via idb. |
+| `simulator_swipe` | Swipe between two points. Supports edge-swipe-back from x=1. |
+| `simulator_long_press` | Long press with configurable duration. Context menus, drag initiation. |
+| `simulator_type_text` | Type text into the focused field. |
+| `simulator_press_key` | Press special keys (return, escape, arrows, F-keys) with modifiers. |
+| `simulator_navigate_back` | Navigate back via Cmd+[. Workaround for edge-swipe limitations. |
+
+### Playwright-Inspired (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_snapshot` | **Preferred over screenshots.** Structured accessibility tree — roles, labels, values, positions. No vision model needed. Like Playwright's `browser_snapshot`. |
+| `simulator_wait_for_element` | Wait for an element to appear (by label, role, or text). Polls with configurable timeout. Like Playwright's `browser_wait_for`. |
+| `simulator_element_exists` | Quick boolean check: does an element matching criteria exist on screen right now? |
+
+### Device Management (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_boot` | Boot a device by name or UDID. Optional `waitForBoot` polling. |
+| `simulator_shutdown` | Shut down a running simulator. |
+| `simulator_erase` | Factory reset — erases all content and settings. |
+| `simulator_open_url` | Open URLs or deep links (e.g., `myapp://screen`). |
+| `simulator_open_simulator` | Open the Simulator.app application. |
+| `simulator_get_booted_sim_id` | Get the UDID of the currently booted simulator. |
+
+### App Management (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_launch_app` | Launch by bundle ID with optional args and env vars. |
+| `simulator_terminate_app` | Force-terminate a running app. |
+| `simulator_install_app` | Install a .app bundle or .ipa from a local path. |
+| `simulator_uninstall_app` | Uninstall by bundle ID. |
+
+### Debugging & Diagnostics (9 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_get_logs` | Query device logs. Filter by process, subsystem, level, time range, message content. |
+| `simulator_stream_logs` | Live log streaming with start/read/stop lifecycle. Configurable buffer. |
+| `simulator_get_app_container` | Get filesystem path to app's bundle, data, or shared group container. |
+| `simulator_list_app_files` | Browse an app's Documents/, Library/, Caches/, tmp/ directories. |
+| `simulator_read_app_file` | Read plists (→JSON), SQLite (→schema), and text files from app data. |
+| `simulator_get_crash_logs` | Retrieve crash reports with stack traces and thread states. |
+| `simulator_diagnose` | Xcode version, disk usage, booted devices, system info. |
+| `simulator_accessibility_audit` | Full iOS accessibility tree — real UIButton/UILabel elements with labels, frames, roles. |
+| `simulator_describe_point` | Returns the accessibility element at given coordinates. |
+
+### System Simulation (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_set_location` | Set GPS coordinates (lat/lng). Test location-based features. |
+| `simulator_send_push` | Send push notifications with full APNs payload JSON. |
+| `simulator_set_clipboard` | Set the simulator clipboard text. |
+| `simulator_add_media` | Add photos/videos to the camera roll from local files. |
+| `simulator_grant_permission` | Grant, revoke, or reset permissions (camera, location, photos, contacts, microphone, etc.). |
+
+### UI Configuration (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_set_appearance` | Switch between light and dark mode. |
+| `simulator_override_status_bar` | Set time, battery, signal, carrier, network type. |
+| `simulator_record_video` | Start screen recording. On stop, key frames are extracted as images for AI chat. |
+| `simulator_stop_recording` | Stop recording. Returns key frames inline (no disk clutter). Optional `savePath` to keep the video. |
+
+### Advanced Debugging & Testing (14 tools)
+
+| Tool | Description |
+|------|-------------|
+| `simulator_set_content_size` | Set Dynamic Type preferred size (13 categories from extra-small to accessibility-XXXL). |
+| `simulator_set_increase_contrast` | Toggle Increase Contrast accessibility setting. |
+| `simulator_location_scenario` | Run predefined GPS routes: Freeway Drive, City Run, City Bicycle Ride. |
+| `simulator_location_route` | Simulate movement along custom waypoints with configurable speed. |
+| `simulator_memory_warning` | Trigger simulated memory warning (didReceiveMemoryWarning). |
+| `simulator_keychain` | Add root certificates, add certificates, or reset the device keychain. |
+| `simulator_icloud_sync` | Trigger iCloud synchronization on the device. |
+| `simulator_verbose_logging` | Enable/disable verbose device logging for deep debugging. |
+| `simulator_install_app_data` | Install .xcappdata packages to restore test data snapshots. |
+| `simulator_get_env` | Read environment variables from the running simulator. |
+| `simulator_biometric` | Set Face ID / Touch ID enrollment state for auth testing. |
+| `simulator_network_status` | Get network configuration — DNS, interfaces, connectivity status. |
+| `simulator_defaults_read` | Read UserDefaults from inside the simulator (inspect app prefs, feature flags). |
+| `simulator_defaults_write` | Write UserDefaults inside the simulator (set flags, inject test config). |
+
+## Architecture
+
+```
+src/
+├── index.ts                    # MCP server entry, 57 tool registrations
+├── helpers/
+│   ├── idb.ts                  # Facebook idb CLI wrapper (cursor-free touch)
+│   ├── simctl.ts               # xcrun simctl command wrapper
+│   ├── applescript.ts          # Keyboard input + CGEvent fallback
+│   ├── coordinate-mapper.ts    # Simulator points → macOS screen coords
+│   ├── mouse-events.swift      # Native Swift CGEvent binary (fallback)
+│   └── logger.ts               # Structured stderr logging
+└── tools/
+    ├── screenshot.ts           # JPEG capture optimized for AI chat
+    ├── interaction.ts          # Tap, swipe, long press, type, key
+    ├── device.ts               # Boot, shutdown, erase, open URL
+    ├── app.ts                  # Install, launch, terminate, list
+    ├── system.ts               # Location, push, clipboard, media, permissions
+    ├── ui.ts                   # Appearance, status bar, video recording, navigate back
+    ├── debug.ts                # Logs, files, crash reports, accessibility
+    ├── advanced.ts             # Dynamic Type, keychain, iCloud, biometric, defaults
+    └── playwright.ts           # Snapshot, wait_for_element, element_exists
+```
+
+### Design Philosophy
+
+**Accessibility-first, like Playwright MCP:**
+1. Use `simulator_snapshot` to understand the screen (structured text, no vision model)
+2. Use coordinates from the snapshot to `simulator_tap`, `simulator_swipe`, etc.
+3. Use `simulator_screenshot` when you need visual verification
+4. Use `simulator_wait_for_element` before interacting with elements that appear after transitions
+
+**No disk clutter:**
+- Screenshots return as base64 in chat — no folders filling up your Desktop
+- Video recordings extract key frames as inline images on stop
+- Optional `savePath` parameter if you actually need files on disk
+
+### Touch Injection Pipeline
+
+```
+simulator_tap(x=200, y=400)
+    │
+    ├─ idb available? ──YES──► idb ui tap --udid <UDID> 200 400
+    │                           (IndigoHID → real iOS touch event)
+    │                           (zero cursor movement)
+    │
+    └─ idb unavailable? ──► coordinate mapper → macOS screen coords
+                             → Swift CGEvent binary → mouse down/up
+```
+
+## Demo App
+
+A SwiftUI demo app is included in `demo-app/` for testing all MCP features:
+
+```bash
+cd demo-app
+xcodebuild -project MCPDemo.xcodeproj -scheme MCPDemo \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+  build
+```
+
+The demo app has 4 tabs exercising every tool category:
+- **Interactions**: Buttons, text fields, long-press zones, navigation stack, scrollable lists
+- **Location**: Live GPS display for testing `simulator_set_location`
+- **Notifications**: Push notification display for testing `simulator_send_push`
+- **Settings**: Clipboard, file I/O, accessibility toggles, UserDefaults
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOG_LEVEL` | `info` | Logging level: `debug`, `info`, `warn`, `error` |
+| `PREFLIGHT_FILTERED_TOOLS` | (none) | Comma-separated list of tool names to disable |
+| `PREFLIGHT_IDB_PATH` | (auto-detect) | Custom path to idb binary |
+| `PATH` | System PATH | Must include idb binary location |
+
+## Example Prompts
+
+### QA Testing
+> "Boot the iPhone 16 Pro simulator, install my app at ./build/MyApp.app, launch it, and take a screenshot of the home screen. Then tap the login button, type test@email.com in the email field, and verify the form validation works."
+
+### Accessibility-First Workflow (Playwright-style)
+> "Take a snapshot of the current screen to see what elements are available. Then tap the button labeled 'Sign In' and wait for the email text field to appear."
+
+### Debugging
+> "My app is crashing on launch. Check the crash logs for MyApp, then get the last 5 minutes of device logs filtered to the MyApp process."
+
+### Dark Mode Testing
+> "Switch to dark mode, take a screenshot, then switch to light mode and screenshot again."
+
+## Troubleshooting
+
+### idb not detected
+If tools show `[CGEvent fallback]` instead of `[cursor-free]`:
+
+1. Verify idb is installed: `which idb` or check `~/Library/Python/3.x/bin/idb`
+2. Add the idb path to your MCP config's `PATH` env var
+3. Or set `PREFLIGHT_IDB_PATH` directly
+
+### Simulator not found
+1. Open Simulator.app: `open -a Simulator`
+2. Boot a device: use `simulator_boot` or `xcrun simctl boot "iPhone 16 Pro"`
+
+### Accessibility permission errors
+1. Go to System Settings → Privacy & Security → Accessibility
+2. Add your terminal app (Terminal.app, iTerm, Claude Code, Cursor, Windsurf, etc.)
+
+## Development
+
+```bash
+npm run dev    # Watch mode (TypeScript only)
+npm run build  # Full rebuild (TypeScript + Swift binary)
+node dist/index.js  # Run directly
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/dist/helpers/applescript.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bring Simulator.app to the foreground.
+ */
+export declare function activateSimulator(): Promise<void>;
+/**
+ * Tap at absolute macOS screen coordinates using the compiled Swift mouse-events helper.
+ */
+export declare function tap(macX: number, macY: number): Promise<void>;
+/**
+ * Long press at absolute macOS screen coordinates.
+ */
+export declare function longPress(macX: number, macY: number, durationMs?: number): Promise<void>;
+/**
+ * Swipe from one point to another using the compiled Swift mouse-events helper.
+ */
+export declare function swipe(startMacX: number, startMacY: number, endMacX: number, endMacY: number, durationMs?: number, steps?: number): Promise<void>;
+/**
+ * Type text into the currently focused field in Simulator.
+ */
+export declare function typeText(text: string): Promise<void>;
+/**
+ * Press a special key with optional modifiers.
+ */
+export declare function pressKey(keyName: string, modifiers?: string[]): Promise<void>;

package/dist/helpers/applescript.js

@@ -0,0 +1,116 @@
+import { execCommand, runAppleScript } from './simctl.js';
+import * as logger from './logger.js';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MOUSE_HELPER = path.join(__dirname, '..', 'mouse-events');
+/**
+ * Bring Simulator.app to the foreground.
+ */
+export async function activateSimulator() {
+    await runAppleScript('tell application "Simulator" to activate', 'applescript');
+    // Small delay for window to come to front
+    await new Promise(resolve => setTimeout(resolve, 200));
+}
+/**
+ * Tap at absolute macOS screen coordinates using the compiled Swift mouse-events helper.
+ */
+export async function tap(macX, macY) {
+    const x = Math.round(macX);
+    const y = Math.round(macY);
+    logger.debug('applescript', `Tap at mac(${x},${y})`);
+    await activateSimulator();
+    await execCommand(MOUSE_HELPER, ['tap', String(x), String(y)], 'applescript:tap');
+}
+/**
+ * Long press at absolute macOS screen coordinates.
+ */
+export async function longPress(macX, macY, durationMs = 1000) {
+    const x = Math.round(macX);
+    const y = Math.round(macY);
+    logger.debug('applescript', `Long press at mac(${x},${y}) for ${durationMs}ms`);
+    await activateSimulator();
+    await execCommand(MOUSE_HELPER, ['longpress', String(x), String(y), String(durationMs)], 'applescript:longPress');
+}
+/**
+ * Swipe from one point to another using the compiled Swift mouse-events helper.
+ */
+export async function swipe(startMacX, startMacY, endMacX, endMacY, durationMs = 300, steps = 20) {
+    logger.debug('applescript', `Swipe from mac(${Math.round(startMacX)},${Math.round(startMacY)}) to mac(${Math.round(endMacX)},${Math.round(endMacY)}) in ${durationMs}ms`);
+    await activateSimulator();
+    await execCommand(MOUSE_HELPER, ['swipe', String(Math.round(startMacX)), String(Math.round(startMacY)), String(Math.round(endMacX)), String(Math.round(endMacY)), String(steps), String(durationMs)], 'applescript:swipe');
+}
+/**
+ * Type text into the currently focused field in Simulator.
+ */
+export async function typeText(text) {
+    logger.debug('applescript', `Typing text: "${text.slice(0, 50)}${text.length > 50 ? '...' : ''}"`);
+    await activateSimulator();
+    // Escape for AppleScript string
+    const escaped = text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const script = `
+tell application "System Events"
+  keystroke "${escaped}"
+end tell
+`;
+    await runAppleScript(script, 'applescript:type');
+}
+/**
+ * Press a special key with optional modifiers.
+ */
+export async function pressKey(keyName, modifiers = []) {
+    logger.debug('applescript', `Press key: ${keyName}`, { modifiers });
+    await activateSimulator();
+    const keyCodeMap = {
+        return: 36,
+        enter: 76,
+        escape: 53,
+        delete: 51,
+        forwarddelete: 117,
+        tab: 48,
+        space: 49,
+        up: 126,
+        down: 125,
+        left: 123,
+        right: 124,
+        home: 115,
+        end: 119,
+        pageup: 116,
+        pagedown: 121,
+        f1: 122, f2: 120, f3: 99, f4: 118, f5: 96,
+        f6: 97, f7: 98, f8: 100, f9: 101, f10: 109,
+        f11: 103, f12: 111,
+        volumeup: 72,
+        volumedown: 73,
+        mute: 74,
+        // Browser/editor navigation
+        '[': 33, ']': 30,
+        '-': 27, '=': 24,
+        ',': 43, '.': 47, '/': 44,
+        ';': 41, "'": 39, '`': 50,
+        '\\': 42,
+    };
+    const code = keyCodeMap[keyName.toLowerCase()];
+    if (code === undefined) {
+        throw new Error(`Unknown key: "${keyName}". Valid keys: ${Object.keys(keyCodeMap).join(', ')}`);
+    }
+    const modParts = modifiers.map(m => {
+        switch (m.toLowerCase()) {
+            case 'command':
+            case 'cmd': return 'command down';
+            case 'shift': return 'shift down';
+            case 'option':
+            case 'alt': return 'option down';
+            case 'control':
+            case 'ctrl': return 'control down';
+            default: throw new Error(`Unknown modifier: "${m}". Valid: command, shift, option, control`);
+        }
+    });
+    const modStr = modParts.length > 0 ? ` using {${modParts.join(', ')}}` : '';
+    const script = `
+tell application "System Events"
+  key code ${code}${modStr}
+end tell
+`;
+    await runAppleScript(script, 'applescript:pressKey');
+}

package/dist/helpers/coordinate-mapper.d.ts

@@ -0,0 +1,44 @@
+export interface WindowGeometry {
+    windowX: number;
+    windowY: number;
+    windowWidth: number;
+    windowHeight: number;
+}
+export interface ScreenMapping {
+    windowGeometry: WindowGeometry;
+    devicePointWidth: number;
+    devicePointHeight: number;
+    scaleFactor: number;
+    titleBarHeight: number;
+    contentWidth: number;
+    contentHeight: number;
+    scaleX: number;
+    scaleY: number;
+}
+/**
+ * Get the Simulator.app front window position and size using AppleScript.
+ */
+export declare function getSimulatorWindowGeometry(): Promise<WindowGeometry>;
+/**
+ * Get the device screen dimensions in points by taking a screenshot and reading its pixel dimensions.
+ * Returns { pointWidth, pointHeight, scaleFactor }.
+ */
+export declare function getDeviceScreenDimensions(device: string): Promise<{
+    pointWidth: number;
+    pointHeight: number;
+    scaleFactor: number;
+    pixelWidth: number;
+    pixelHeight: number;
+}>;
+/**
+ * Compute the full screen mapping from simulator points to macOS screen coordinates.
+ * Cached for 10 seconds to improve performance during rapid interactions.
+ */
+export declare function getScreenMapping(device: string): Promise<ScreenMapping>;
+/**
+ * Convert simulator screen point coordinates to macOS absolute screen coordinates.
+ */
+export declare function simToMac(simX: number, simY: number, mapping: ScreenMapping): {
+    macX: number;
+    macY: number;
+};