screenhand 0.4.5 → 0.4.7

package/dist/mcp-desktop.js

@@ -164,6 +164,48 @@ Docs: https://github.com/manushi4/Screenhand
 `);
     process.exit(0);
 }
+// ── Startup cleanup: remove corrupt/empty state files ──
+{
+    const stateDir = path.join(os.homedir(), ".screenhand", "state");
+    if (fs.existsSync(stateDir)) {
+        try {
+            const files = fs.readdirSync(stateDir).filter(f => f.endsWith(".json"));
+            let removed = 0;
+            for (const file of files) {
+                const filePath = path.join(stateDir, file);
+                try {
+                    const stat = fs.statSync(filePath);
+                    // Remove empty files
+                    if (stat.size === 0) {
+                        fs.unlinkSync(filePath);
+                        removed++;
+                        continue;
+                    }
+                    // Remove files older than 7 days
+                    if (Date.now() - stat.mtimeMs > 7 * 24 * 60 * 60 * 1000) {
+                        fs.unlinkSync(filePath);
+                        removed++;
+                        continue;
+                    }
+                    // Remove corrupt JSON (can't parse)
+                    const content = fs.readFileSync(filePath, "utf-8");
+                    JSON.parse(content);
+                }
+                catch {
+                    try {
+                        fs.unlinkSync(filePath);
+                        removed++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            if (removed > 0) {
+                console.error(`[screenhand] Cleaned up ${removed} stale/corrupt state files from ${stateDir}`);
+            }
+        }
+        catch { /* ignore if dir can't be read */ }
+    }
+}
 // ── Audit logging for dangerous tools ──
 const AUDIT_LOG_PATH = path.resolve(__dirname, ".audit-log.jsonl");
 function auditLog(tool, params) {

package/dist/src/native/bridge-client.js

@@ -251,13 +251,28 @@ export class BridgeClient extends EventEmitter {
         return [...this.recentStderr];
     }
     async spawn() {
+        // Check binary exists before spawning — give actionable error instead of cryptic ENOENT
+        if (!fs.existsSync(this.binaryPath)) {
+            const platform = process.platform;
+            const hint = platform === "darwin"
+                ? `Run: npm run build:native (requires Xcode + Swift)`
+                : platform === "win32"
+                    ? `Run: npm run build:native:windows (requires .NET 8 SDK)`
+                    : `Native bridge is only available on macOS and Windows.`;
+            throw new Error(`ScreenHand native bridge not found at: ${this.binaryPath}\n` +
+                `${hint}\n` +
+                `If installed via npm, try: npm rebuild screenhand`);
+        }
         const child = spawn(this.binaryPath, [], {
             stdio: ["pipe", "pipe", "pipe"],
         });
         // Track which process this is so stale event handlers don't trigger restarts
         const spawnedProcess = child;
         child.on("error", (err) => {
-            this.emit("error", err);
+            const msg = err.code === "ENOENT"
+                ? new Error(`ScreenHand native bridge binary not found: ${this.binaryPath}. Run: npm run build:native`)
+                : err;
+            this.emit("error", msg);
             // Only auto-restart if this is still the active process
             if (this.started && this.process === spawnedProcess) {
                 this.restart().catch(() => { });

package/dist-app-maps/com.apple.iphonesimulator.json

@@ -20,7 +20,7 @@
     "consistency": 6
   },
   "confidence": 0.13111111111111112,
-  "lastValidated": "2026-03-25T10:10:16.511Z",
+  "lastValidated": "2026-03-25T10:15:29.651Z",
   "mapVersion": 1,
   "uiArchitecture": {
     "type": "other",
@@ -2849,7 +2849,7 @@
   "shortcutsUsed": 20,
   "playbooksExported": 0,
   "edgeCasesHandled": 2,
-  "lastRecomputed": "2026-03-25T10:10:09.981Z",
+  "lastRecomputed": "2026-03-25T10:15:18.462Z",
   "visibilityConditions": [
     {
       "elementLabel": "iPhone 16 Plus",
@@ -2861,10 +2861,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 50,
-      "checkCount": 50,
+      "seenCount": 51,
+      "checkCount": 51,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T05:44:52.135Z"
     },
     {
@@ -2921,10 +2921,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 18,
-      "checkCount": 18,
+      "seenCount": 19,
+      "checkCount": 19,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T05:44:52.135Z"
     },
     {
@@ -4141,10 +4141,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 24,
-      "checkCount": 24,
+      "seenCount": 25,
+      "checkCount": 25,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T05:51:50.429Z"
     },
     {
@@ -4184,10 +4184,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4199,10 +4199,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4214,10 +4214,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4229,10 +4229,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4244,10 +4244,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4259,10 +4259,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4288,10 +4288,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -4303,10 +4303,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 8,
-      "checkCount": 8,
+      "seenCount": 9,
+      "checkCount": 9,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T09:43:33.566Z"
     },
     {
@@ -5101,10 +5101,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5115,10 +5115,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5129,10 +5129,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5143,10 +5143,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5157,10 +5157,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5185,10 +5185,10 @@
         "Simulator"
       ],
       "absentOnPages": [],
-      "seenCount": 2,
-      "checkCount": 2,
+      "seenCount": 3,
+      "checkCount": 3,
       "visibilityRate": 1,
-      "lastSeen": "2026-03-25T10:06:30.136Z",
+      "lastSeen": "2026-03-25T10:15:29.651Z",
       "firstSeen": "2026-03-25T10:01:02.431Z"
     },
     {
@@ -5204,6 +5204,34 @@
       "visibilityRate": 1,
       "lastSeen": "2026-03-25T10:06:30.136Z",
       "firstSeen": "2026-03-25T10:06:30.136Z"
+    },
+    {
+      "elementLabel": "3:45",
+      "conditionType": "unknown",
+      "description": "Visibility rate: 100%",
+      "seenOnPages": [
+        "Simulator"
+      ],
+      "absentOnPages": [],
+      "seenCount": 2,
+      "checkCount": 2,
+      "visibilityRate": 1,
+      "lastSeen": "2026-03-25T10:15:29.651Z",
+      "firstSeen": "2026-03-25T10:15:29.651Z"
+    },
+    {
+      "elementLabel": "6 PM",
+      "conditionType": "unknown",
+      "description": "Visibility rate: 100%",
+      "seenOnPages": [
+        "Simulator"
+      ],
+      "absentOnPages": [],
+      "seenCount": 1,
+      "checkCount": 1,
+      "visibilityRate": 1,
+      "lastSeen": "2026-03-25T10:15:29.651Z",
+      "firstSeen": "2026-03-25T10:15:29.651Z"
     }
   ]
 }

package/dist-playbooks/simulator-add-media.json

@@ -0,0 +1,18 @@
+{
+  "id": "simulator-add-media",
+  "name": "Add Photos/Videos to Simulator",
+  "description": "Import photos or videos into the simulator's Photos library",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "photos", "media", "import"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl addmedia booted '{file_path}'\"",
+      "description": "Add photo/video to simulator Photos (replace {file_path} with /path/to/image.jpg or video.mp4)"
+    }
+  ],
+  "notes": "Supports: .jpg, .png, .heic, .mp4, .mov. Multiple files: xcrun simctl addmedia booted file1.jpg file2.png"
+}

package/dist-playbooks/simulator-dark-mode.json

@@ -0,0 +1,22 @@
+{
+  "id": "simulator-dark-mode",
+  "name": "Toggle Dark Mode",
+  "description": "Switch between light and dark appearance in iOS Simulator",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "dark-mode", "appearance"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "key",
+      "key": "shift+cmd+a",
+      "description": "Toggle between light and dark appearance"
+    }
+  ]
+}

package/dist-playbooks/simulator-device-controls.json

@@ -0,0 +1,38 @@
+{
+  "id": "simulator-device-controls",
+  "name": "Device Controls",
+  "description": "Home, lock, unlock, rotate, app switcher, shake — all Simulator hardware button actions",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "device", "controls"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "key",
+      "key": "shift+cmd+h",
+      "description": "Home — return to home screen"
+    },
+    {
+      "action": "key",
+      "key": "cmd+l",
+      "description": "Lock device"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl spawn booted notifyutil -p com.apple.springboard.unlockdevice\"",
+      "description": "Unlock device (simctl method — most reliable)"
+    },
+    {
+      "action": "key",
+      "key": "shift+cmd+h",
+      "description": "Press Home after unlock to reach home screen"
+    }
+  ],
+  "notes": "Rotate: menu_click('Device/Rotate Left') or menu_click('Device/Rotate Right'). App Switcher: key('ctrl+shift+cmd+h'). Shake: key('ctrl+cmd+z'). Siri: key('option+shift+cmd+h')."
+}

package/dist-playbooks/simulator-erase-device.json

@@ -0,0 +1,28 @@
+{
+  "id": "simulator-erase-device",
+  "name": "Erase Device (Factory Reset)",
+  "description": "Factory reset the simulator — erases all content and settings",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "erase", "reset"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl list devices booted -j\" ",
+      "description": "Get booted device UDID first"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl shutdown booted && xcrun simctl erase {udid}\"",
+      "description": "Shutdown then erase device (replace {udid})"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl boot {udid}\"",
+      "description": "Boot device back up after erase"
+    }
+  ],
+  "notes": "Device must be shut down before erase. Alternative: menu_click('Device/Erase All Content and Settings…') then confirm dialog."
+}

package/dist-playbooks/simulator-face-id.json

@@ -0,0 +1,28 @@
+{
+  "id": "simulator-face-id",
+  "name": "Test Face ID",
+  "description": "Simulate Face ID matching and non-matching scans for testing biometric flows",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "face-id", "biometrics", "testing"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "menu_click",
+      "path": "Features/Face ID/Enrolled",
+      "description": "Ensure Face ID is enrolled (must be checked first)"
+    },
+    {
+      "action": "key",
+      "key": "option+cmd+m",
+      "description": "Matching Face — triggers successful Face ID authentication"
+    }
+  ],
+  "notes": "For failed scan: key('option+cmd+n'). For Apple Pay: key('option+cmd+a'). Must enroll Face ID first via Features > Face ID > Enrolled."
+}

package/dist-playbooks/simulator-grant-permissions.json

@@ -0,0 +1,18 @@
+{
+  "id": "simulator-grant-permissions",
+  "name": "Grant App Permissions",
+  "description": "Grant privacy permissions (camera, photos, location, etc.) to an iOS app without UI prompts",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "permissions", "privacy", "testing"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl privacy booted grant all {bundleId}\"",
+      "description": "Grant ALL permissions to app (replace {bundleId}). Or use specific: camera, photos, location, microphone, contacts, calendars, reminders, health, homekit, speech-recognition"
+    }
+  ],
+  "notes": "To revoke: xcrun simctl privacy booted revoke all {bundleId}. To reset: xcrun simctl privacy booted reset all {bundleId}"
+}

package/dist-playbooks/simulator-install-app.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-install-app",
+  "name": "Install & Uninstall App",
+  "description": "Install a .app bundle or uninstall an app by bundle ID",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "install", "uninstall", "app"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl install booted '{path_to_app}'\"",
+      "description": "Install app (replace {path_to_app} with /path/to/MyApp.app)"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl launch booted '{bundleId}'\"",
+      "description": "Launch the installed app"
+    }
+  ],
+  "notes": "To uninstall: xcrun simctl uninstall booted '{bundleId}'. To find app container: xcrun simctl get_app_container booted '{bundleId}'. To terminate: xcrun simctl terminate booted '{bundleId}'."
+}

package/dist-playbooks/simulator-launch-app.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-launch-app",
+  "name": "Launch iOS App in Simulator",
+  "description": "Launch any installed iOS app by bundle ID using simctl — fastest and most reliable method",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "launch", "simctl"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl launch booted {bundleId}\"",
+      "description": "Launch iOS app via simctl (replace {bundleId} with e.g. com.apple.mobilesafari)"
+    }
+  ],
+  "notes": "Common bundle IDs: Safari=com.apple.mobilesafari, Settings=com.apple.Preferences, Maps=com.apple.Maps, Photos=com.apple.mobileslideshow, Health=com.apple.Health, Messages=com.apple.MobileSMS, Files=com.apple.DocumentsApp"
+}

package/dist-playbooks/simulator-location.json

@@ -0,0 +1,18 @@
+{
+  "id": "simulator-location",
+  "name": "Simulate GPS Location",
+  "description": "Set custom GPS coordinates or simulate movement (city run, freeway drive)",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "location", "gps", "testing"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl location booted set {latitude},{longitude}\"",
+      "description": "Set custom GPS location (replace {latitude},{longitude} e.g. 37.7749,-122.4194 for San Francisco)"
+    }
+  ],
+  "notes": "Presets via menu: menu_click('Features/Location/City Run') for moving GPS, menu_click('Features/Location/Freeway Drive') for highway speed. menu_click('Features/Location/Custom Location…') for dialog input. menu_click('Features/Location/None') to clear."
+}

package/dist-playbooks/simulator-memory-warning.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-memory-warning",
+  "name": "Simulate Memory Warning",
+  "description": "Send a memory pressure warning to the running iOS app for testing memory handling",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "memory", "debug", "testing"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "key",
+      "key": "shift+cmd+m",
+      "description": "Send memory warning to foreground app"
+    }
+  ],
+  "notes": "Use to test didReceiveMemoryWarning handlers. Also: menu_click('Debug/Slow Animations') to debug animation issues. key('cmd+/') to open system log."
+}

package/dist-playbooks/simulator-navigate-url.json

@@ -0,0 +1,18 @@
+{
+  "id": "simulator-navigate-url",
+  "name": "Navigate to URL in Safari",
+  "description": "Open a URL in iOS Safari — uses simctl openurl, never type URLs manually",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "safari", "url", "navigation"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl openurl booted '{url}'\"",
+      "description": "Open URL in Safari (replace {url}). This is the ONLY reliable way — type_text is broken in Simulator"
+    }
+  ],
+  "notes": "Works for any URL scheme: https://, tel:, mailto:, maps:, shortcuts://, custom deep links"
+}

package/dist-playbooks/simulator-push-notification.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-push-notification",
+  "name": "Send Push Notification",
+  "description": "Send a test push notification to an iOS app in the Simulator via simctl",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "push", "notification", "testing"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "applescript",
+      "script": "do shell script \"echo '{\\\"aps\\\":{\\\"alert\\\":{\\\"title\\\":\\\"{title}\\\",\\\"body\\\":\\\"{body}\\\"},\\\"sound\\\":\\\"default\\\"}}' > /tmp/screenhand-push.json\"",
+      "description": "Create push notification payload (replace {title} and {body})"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl push booted {bundleId} /tmp/screenhand-push.json\"",
+      "description": "Send push notification to app (replace {bundleId})"
+    }
+  ],
+  "notes": "App must be installed and have push notification capability. Common test: bundleId=com.apple.mobilesafari"
+}

package/dist-playbooks/simulator-record-screen.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-record-screen",
+  "name": "Record Screen Video",
+  "description": "Start/stop screen recording or save programmatically via simctl",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "recording", "video", "screen"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "key",
+      "key": "cmd+r",
+      "description": "Toggle screen recording (press again to stop)"
+    }
+  ],
+  "notes": "For programmatic recording: xcrun simctl io booted recordVideo /path/to/output.mp4 (Ctrl+C to stop). For screenshot: xcrun simctl io booted screenshot /path/to/output.png"
+}

package/dist-playbooks/simulator-rotate-device.json

@@ -0,0 +1,23 @@
+{
+  "id": "simulator-rotate-device",
+  "name": "Rotate Device",
+  "description": "Rotate between portrait and landscape orientations",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "rotate", "orientation"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "menu_click",
+      "path": "Device/Rotate Right",
+      "description": "Rotate to landscape (use menu — keyboard shortcut is unreliable)"
+    }
+  ],
+  "notes": "Rotate back: menu_click('Device/Rotate Left'). Keyboard shortcuts cmd+← and cmd+→ exist but are unreliable — always use menu_click."
+}

package/dist-playbooks/simulator-screenshot-appstore.json

@@ -0,0 +1,33 @@
+{
+  "id": "simulator-screenshot-appstore",
+  "name": "App Store Screenshot",
+  "description": "Take a clean App Store screenshot with perfect status bar (9:41, full battery, full signal)",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "screenshot", "app-store"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl status_bar booted override --time '9:41' --batteryLevel 100 --cellularBars 4 --wifiBars 3\"",
+      "description": "Override status bar to App Store standard (9:41, full battery/signal)"
+    },
+    {
+      "action": "key",
+      "key": "cmd+s",
+      "description": "Save screenshot to Desktop"
+    },
+    {
+      "action": "applescript",
+      "script": "do shell script \"xcrun simctl status_bar booted clear\"",
+      "description": "Clear status bar override back to normal"
+    }
+  ],
+  "notes": "Screenshot saves to ~/Desktop. For programmatic saving: xcrun simctl io booted screenshot /path/to/output.png"
+}

package/dist-playbooks/simulator-type-text.json

@@ -0,0 +1,24 @@
+{
+  "id": "simulator-type-text",
+  "name": "Type Text in iOS Field",
+  "description": "Type text into iOS text fields using ui_set_value — the ONLY reliable method (type_text and clipboard are both broken)",
+  "platform": "simulator",
+  "version": "1.0.0",
+  "tags": ["simulator", "ios", "type", "text", "input"],
+  "successCount": 1,
+  "failCount": 0,
+  "steps": [
+    {
+      "action": "focus",
+      "bundleId": "com.apple.iphonesimulator",
+      "description": "Bring Simulator to front"
+    },
+    {
+      "action": "ui_set_value",
+      "identifier": "{field_title}",
+      "value": "{your text}",
+      "description": "Set text via AX directly — BEST METHOD. Replace {field_title} with the AX title of the text field"
+    }
+  ],
+  "notes": "BROKEN methods: type_text produces garbled chars (e.g. 'aaaaaa' instead of 'apple.com'). Clipboard cmd+v is unreliable. For URLs use simctl openurl instead. Ensure Connect Hardware Keyboard is ON: key('shift+cmd+k')."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screenhand",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "mcpName": "io.github.manushi4/screenhand",
   "description": "Give AI eyes and hands on your desktop. ScreenHand is an open-source MCP server that lets Claude and other AI agents see your screen, click buttons, type text, and control any app on macOS and Windows.",
   "homepage": "https://screenhand.com",
@@ -70,6 +70,9 @@
     "ocr",
     "computer-use"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.27.1",