feat: add mobile support

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 
 # Build output
 dist/
+ios-runner-derived-data/
 
 # Test coverage
 coverage/
@@ -45,4 +46,7 @@ yalc.lock
 # This entry would keep track of the yarn binaries tarball generated by corepack
 !.yarn/yarn-corepack.tgz
 
-docs/
+docs/
+
+ios-runner/AxSnapshot/.build
+**/xcuserdata/

README.md

@@ -1454,6 +1454,96 @@ yarn build && yalc publish
 yalc add @metamask/client-mcp-core
 ```
 
+## iOS Simulator Support
+
+### Overview
+
+This package supports MetaMask Mobile automation on iOS simulators through the
+same MCP tool surface used by browser workflows (`mm_click`, `mm_type`,
+`mm_wait_for`, `mm_describe_screen`, etc.).
+
+Under the hood, iOS uses a dual-backend discovery architecture:
+
+- XCUITest runner for command execution and primary discovery.
+- AXSnapshot fallback for resilient post-transition discovery when XCTest
+  accessibility snapshots degrade.
+
+### iOS Architecture
+
+```
+MCP tool call
+  -> IOSPlatformDriver
+    -> XCUITestClient
+      -> AgentDeviceRunner (XCUITest host)
+        -> snapshot / interaction command
+          -> (if snapshot degraded) AXSnapshot fallback
+            -> normalized discovery tree
+```
+
+Core components:
+
+- `IPlatformDriver`: platform abstraction shared by browser + iOS.
+- `PlaywrightPlatformDriver`: browser implementation.
+- `IOSPlatformDriver`: iOS implementation with discovery backend strategy.
+- `XCUITestClient`: transport for runner command API.
+- `runner-lifecycle`: boot, health, restart, and rebind behavior.
+- `ax-snapshot`: binary invocation and output normalization.
+
+Default snapshot backend is `xctest-with-ax-fallback`.
+
+### Reliability Behaviors
+
+- Health checks use `ping` to avoid snapshot-triggered UI side effects.
+- Runner bind step is separate from snapshot requests (`bind` command).
+- Discovery avoids clearing ref maps when a snapshot is empty.
+- Interaction polling retries through transient recovery windows.
+- Recovery and discovery issues are surfaced with explicit error codes:
+  - `MM_IOS_EMPTY_SNAPSHOT`
+  - `MM_IOS_RUNNER_RECOVERING`
+  - `MM_IOS_AX_PERMISSION_REQUIRED`
+  - `MM_IOS_AX_BINARY_MISSING`
+  - `MM_IOS_AX_SNAPSHOT_FAILED`
+
+### Prerequisites
+
+- iOS setup guide: [docs/ios-setup.md](docs/ios-setup.md)
+- Runner architecture and command details:
+  [ios-runner/README.md](ios-runner/README.md)
+
+### Platform Support Matrix
+
+| Tool                      | Browser         | iOS             |
+| ------------------------- | --------------- | --------------- |
+| mm_click                  | ✅              | ✅              |
+| mm_type                   | ✅              | ✅              |
+| mm_wait_for               | ✅              | ✅              |
+| mm_screenshot             | ✅              | ✅              |
+| mm_accessibility_snapshot | ✅              | ✅              |
+| mm_list_testids           | ✅              | ✅              |
+| mm_describe_screen        | ✅              | ✅              |
+| mm_get_state              | ✅              | ✅              |
+| mm_build                  | ✅ (capability) | ✅ (capability) |
+| mm_seed_contract          | ✅ (capability) | ✅ (capability) |
+| mm_clipboard              | ✅              | ❌ (CDP)        |
+| mm_switch_to_tab          | ✅              | ❌ (tabs)       |
+| mm_close_tab              | ✅              | ❌ (tabs)       |
+| mm_wait_for_notification  | ✅              | ❌ (tabs)       |
+
+### Usage
+
+To launch an iOS session, set `platform: 'ios'` in the launch input:
+
+```typescript
+{ platform: 'ios', simulatorDeviceId: '<UDID>', appBundlePath: '/path/to/MetaMask.app' }
+```
+
+### Runner Diagnostics
+
+- XCUITest runner startup and runtime logs are written to
+  `test-artifacts/ios-runner-logs`.
+- Startup failures include log paths and recent stdout/stderr tails to speed up
+  triage.
+
 ## License
 
 MIT