zeno-mobile-runner 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.2.14 (2026-06-23)
+
+### Added
+
+- Added a first-class `setLocation` scenario action for simulator/emulator
+  location control. iOS simulators grant the target app location permission and
+  set coordinates through `simctl`; Android emulators best-effort grant runtime
+  location permissions before setting emulator geolocation.
+
+## 0.2.13 (2026-06-23)
+
+### Fixed
+
+- iOS native selector waits now cap each XCTest query to the action timeout,
+  retry one transient native command failure, and then fall back to semantic
+  snapshots with diagnostics. This prevents one stuck XCTest selector query from
+  consuming the whole wait budget while still allowing transient native queries
+  to recover.
+- iOS native selector scrolling now reads the app-frame viewport from the XCTest
+  shim before generating swipe coordinates, so native scrolls use iOS point
+  dimensions instead of Android fallback dimensions.
+- Expo dev-client URL opening now uses URL-aware fallback handling and avoids
+  broad static-text enumeration while accepting deep-link chooser prompts.
+
 ## 0.2.12 (2026-06-22)
 
 ### Fixed

package/FEATURES.md

@@ -142,7 +142,7 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 ## Current Limitations
 
-- Current release status is `0.2.12`, a public developer preview rather than
+- Current release status is `0.2.14`, a public developer preview rather than
   a production-stable `1.0.0`.
 - Physical iOS log capture is still simulator-first. Physical iOS screenshots
   are available when the XCTest/XCUIAutomation shim is configured.

package/README.md

@@ -199,7 +199,7 @@ comparisons against your current E2E tool, and multi-device matrices, see
 Slow CI hardware can extend the generated iOS shim build timeout with
 `ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS`; `ZMR_IOS_SHIM_RESPONSE_TIMEOUT_SECONDS`
 bounds each in-flight request, and `ZMR_IOS_SHIM_TIMEOUT_MS` remains the outer
-process ceiling. Current release: `0.2.12` developer preview.
+process ceiling. Current release: `0.2.14` developer preview.
 Protocol version: `2026-04-28`.
 
 ## Optional protocol clients

package/clients/kotlin/README.md

@@ -27,7 +27,7 @@ gradle -p clients/kotlin runFakeSession \
 ```
 
 ```kotlin
-implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.12.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.14.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "dev.zmr"
-version = "0.2.12"
+version = "0.2.14"
 
 kotlin {
     jvmToolchain(17)

package/clients/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmr-client"
-version = "0.2.12.dev1"
+version = "0.2.14.dev1"
 description = "Python JSON-RPC client for Zeno Mobile Runner."
 requires-python = ">=3.9"
 license = { text = "MIT" }

package/clients/rust/Cargo.lock

@@ -100,7 +100,7 @@ checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
 [[package]]
 name = "zmr-client"
-version = "0.2.12"
+version = "0.2.14"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.2.12"
+version = "0.2.14"
 edition = "2021"
 license = "MIT"
 description = "Rust JSON-RPC client for Zeno Mobile Runner."

package/clients/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmr/client",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",

package/docs/protocol-fixtures/core-session.responses.jsonl

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.12","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.14","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 {"jsonrpc":"2.0","id":2,"result":[{"serial":"fake-device-1","state":"device","ready":true}]}
 {"jsonrpc":"2.0","id":3,"result":{"sessionId":"default"}}
 {"jsonrpc":"2.0","id":4,"result":true}

package/docs/protocol.md

@@ -2,7 +2,7 @@
 
 ZMR exposes newline-delimited JSON-RPC 2.0 over stdio or localhost TCP in v1. Each request is one JSON object followed by `\n`. Each response is one JSON object followed by `\n`.
 
-Current runner version: `0.2.12`.
+Current runner version: `0.2.14`.
 
 Current protocol version: `2026-04-28`.
 
@@ -47,7 +47,7 @@ and protocol versions. The response is covered by
 `schemas/inspect-output.schema.json`:
 
 ```json
-{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
 ```
 
 `zmr discover --from-trace <trace-dir> --out <scenario.json> --validate --json`
@@ -60,7 +60,7 @@ invent credentials, or commit files. The response is covered by
 `schemas/discover-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr explore --from-trace <trace-dir> --out <scenario.json> --goal <goal>
@@ -71,7 +71,7 @@ launch devices, crawl the app, invent missing actions, discover credentials, or
 commit files. The response is covered by `schemas/explore-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --from-trace <trace-dir> --out <scenario.json> --json` is the lower
@@ -84,7 +84,7 @@ into fields, or commit files. The response is covered by
 `schemas/draft-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --include-actions` additionally parses `events.jsonl` and prepends
@@ -214,7 +214,7 @@ installers, setup scripts, and generated clients. The response is covered by
 `schemas/version-output.schema.json`:
 
 ```json
-{"name":"zmr","version":"0.2.12","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.14","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -226,7 +226,7 @@ and method inventory for JSON-RPC clients. The result object is covered by
 iOS simulator, or physical iOS workflows are available.
 
 ```json
-{"name":"zmr","version":"0.2.12","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
+{"name":"zmr","version":"0.2.14","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
 ```
 
 ## Doctor Output Contract
@@ -373,6 +373,7 @@ zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent-session
 - `app.stop`
 - `app.openLink` with `{ "url": "exampleapp://e2e-auth?probe=1" }`
 - `app.clearState`
+- Scenario action `setLocation` with `{ "latitude": 51.5074, "longitude": -0.1278 }` for simulator/emulator geolocation
 - `observe.snapshot`
 - `observe.semanticSnapshot`
 - `ui.tap` with `{ "selector": { "text": "Sign in" } }`
@@ -432,7 +433,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.12","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.14","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 ```
 
 ### `trace.events`
@@ -514,7 +515,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`. Generated
@@ -537,7 +538,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.12","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.14","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`.

package/docs/scenario-authoring.md

@@ -84,6 +84,18 @@ The importer supports the common subset needed for smoke scenarios:
 generated JSON before committing it; native `.zmr/*.json` scenarios remain the
 runtime contract for agents and CI.
 
+Use `setLocation` before location-dependent assertions to set simulator or
+emulator coordinates through the runner instead of shelling out from the app
+test:
+
+```json
+{ "action": "setLocation", "latitude": 51.5074, "longitude": -0.1278 }
+```
+
+On iOS simulators, ZMR grants the target app location permission before setting
+the coordinate. On Android emulators, ZMR grants runtime location permissions
+best-effort and then uses emulator geolocation.
+
 `assertVisible` and `assertNotVisible` accept the same `timeoutMs` field as
 waits when a scenario needs assertion-specific timing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeno-mobile-runner",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Agent-native mobile app test runner for React Native, Expo, Flutter, and native Android/iOS.",
   "main": "npm/index.mjs",
   "repository": {

package/schemas/scenario.schema.json

@@ -40,6 +40,7 @@
             "clearState",
             "snapshot",
             "openLink",
+            "setLocation",
             "tap",
             "typeText",
             "eraseText",
@@ -62,6 +63,8 @@
         },
         "optional": { "type": "boolean" },
         "url": { "type": "string", "minLength": 1 },
+        "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
+        "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
         "selector": { "$ref": "#/$defs/selector" },
         "selectors": {
           "type": "array",
@@ -90,6 +93,10 @@
           "if": { "properties": { "action": { "const": "openLink" } } },
           "then": { "required": ["url"] }
         },
+        {
+          "if": { "properties": { "action": { "const": "setLocation" } } },
+          "then": { "required": ["latitude", "longitude"] }
+        },
         {
           "if": { "properties": { "action": { "enum": ["tap", "waitVisible", "waitNotVisible", "assertVisible", "assertNotVisible", "scrollUntilVisible"] } } },
           "then": { "required": ["selector"] }

package/shims/ios/ZMRShim.swift

@@ -5,6 +5,8 @@ struct ZMRShimCommand: Decodable {
     let cmd: String
     let selector: String?
     let text: String?
+    let url: String?
+    let expoDevClientFallback: Bool?
     let x: Int?
     let y: Int?
     let x1: Int?

package/shims/ios/ZMRShimUITestCase.swift

@@ -116,6 +116,11 @@ final class ZMRShimUITestCase: XCTestCase {
                 "viewport": ZMRShim.viewport(app: app).json,
                 "nodes": ZMRShim.snapshot(app: app).map { $0.json }
             ]
+        case "viewport":
+            return [
+                "status": "ok",
+                "viewport": ZMRShim.viewport(app: app).json
+            ]
         case "screenshot":
             let screenshot = XCUIScreen.main.screenshot()
             return [
@@ -187,7 +192,12 @@ final class ZMRShimUITestCase: XCTestCase {
         case "appState":
             return ["status": "ok", "state": app.state.rawValue]
         case "acceptSystemAlert":
-            return acceptSystemAlert(buttonText: command.text ?? "Open", app: app)
+            return acceptSystemAlert(
+                buttonText: command.text ?? "Open",
+                openedURL: command.url,
+                expoDevClientFallback: command.expoDevClientFallback ?? false,
+                app: app
+            )
         default:
             return error("unknown.command", "unsupported command: \(command.cmd)")
         }
@@ -195,7 +205,7 @@ final class ZMRShimUITestCase: XCTestCase {
 
     private func commandRequiresForeground(_ command: ZMRShimCommand) -> Bool {
         switch command.cmd {
-        case "snapshot", "query", "tap", "type", "eraseText", "hideKeyboard", "swipe", "settle":
+        case "snapshot", "viewport", "query", "tap", "type", "eraseText", "hideKeyboard", "swipe", "settle":
             return true
         default:
             return false
@@ -229,7 +239,12 @@ final class ZMRShimUITestCase: XCTestCase {
         ["status": "error", "code": code, "message": message]
     }
 
-    private func acceptSystemAlert(buttonText: String, app: XCUIApplication) -> [String: Any] {
+    private func acceptSystemAlert(
+        buttonText: String,
+        openedURL: String?,
+        expoDevClientFallback: Bool,
+        app: XCUIApplication
+    ) -> [String: Any] {
         let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
         var labels = [buttonText, "Open", "Allow", "OK", "Continue"]
         labels = labels.reduce(into: [String]()) { unique, label in
@@ -264,7 +279,11 @@ final class ZMRShimUITestCase: XCTestCase {
             }
         }
 
-        let expoDeepLinkSelection = acceptExpoDevClientDeepLink(app: app)
+        let expoDeepLinkSelection = acceptExpoDevClientDeepLink(
+            openedURL: openedURL,
+            expoDevClientFallback: expoDevClientFallback,
+            app: app
+        )
         if expoDeepLinkSelection.accepted {
             acceptedCount += 1
             lastAcceptedLabel = expoDeepLinkSelection.label
@@ -282,27 +301,38 @@ final class ZMRShimUITestCase: XCTestCase {
         return ["status": "ok", "accepted": false, "count": 0]
     }
 
-    private func acceptExpoDevClientDeepLink(app: XCUIApplication) -> (accepted: Bool, label: String) {
-        guard app.staticTexts["Deep link received:"].waitForExistence(timeout: 1) else {
-            return (false, "")
-        }
-
-        let candidateQueries = [
-            app.buttons.allElementsBoundByIndex,
-            app.cells.allElementsBoundByIndex,
-            app.staticTexts.allElementsBoundByIndex
-        ]
+    private func acceptExpoDevClientDeepLink(
+        openedURL: String?,
+        expoDevClientFallback: Bool,
+        app: XCUIApplication
+    ) -> (accepted: Bool, label: String) {
+        let predicate = NSPredicate(
+            format: "label != '' AND label != %@ AND label != %@ AND label != %@ AND NOT label CONTAINS[c] %@ AND NOT label BEGINSWITH[c] %@ AND NOT label CONTAINS[c] %@",
+            "Deep link received:",
+            "Select an app to open it:",
+            "Go back",
+            "://",
+            "Note:",
+            "next app you open"
+        )
 
-        for elements in candidateQueries {
-            for element in elements {
-                let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-                guard isExpoDevClientDeepLinkTarget(label: label), element.isHittable else {
-                    continue
-                }
+        if app.staticTexts["Deep link received:"].waitForExistence(timeout: 1) {
+            if tapFirstMatchingExpoCandidate(
+                queries: [app.buttons, app.cells, app.staticTexts],
+                predicate: predicate
+            ) {
+                return (true, "expo-dev-client-deep-link")
+            }
+        }
 
-                element.tap()
-                Thread.sleep(forTimeInterval: 1.0)
-                return (true, label)
+        if expoDevClientFallback,
+           isCustomSchemeURL(openedURL),
+           !isExpoDevClientURL(openedURL) {
+            if tapExpoDevClientDeepLinkCoordinateFallback(app: app) {
+                return (true, "expo-dev-client-deep-link-coordinate")
+            }
+            if tapExpoDevClientDeepLinkCandidateFallback(app: app, predicate: predicate) {
+                return (true, "expo-dev-client-deep-link-candidate")
             }
         }
 
@@ -335,23 +365,12 @@ final class ZMRShimUITestCase: XCTestCase {
             return (false, "")
         }
 
-        let candidateQueries = [
-            app.buttons.allElementsBoundByIndex,
-            app.cells.allElementsBoundByIndex,
-            app.staticTexts.allElementsBoundByIndex
-        ]
-
-        for elements in candidateQueries {
-            for element in elements {
-                let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
-                guard isExpoDevClientProjectTarget(label: label), element.exists else {
-                    continue
-                }
-
-                element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
-                Thread.sleep(forTimeInterval: 1.0)
-                return (true, label)
-            }
+        let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR label CONTAINS[c] %@", " http://", " https://")
+        if tapFirstMatchingExpoCandidate(
+            queries: [app.buttons, app.cells, app.staticTexts],
+            predicate: predicate
+        ) {
+            return (true, "expo-dev-client-home")
         }
 
         return (false, "")
@@ -379,6 +398,59 @@ final class ZMRShimUITestCase: XCTestCase {
         return label.contains(" http://") || label.contains(" https://")
     }
 
+    private func tapFirstMatchingExpoCandidate(
+        queries: [XCUIElementQuery],
+        predicate: NSPredicate
+    ) -> Bool {
+        for query in queries {
+            let matching = query.matching(predicate)
+            for candidateIndex in 0..<6 {
+                let element = matching.element(boundBy: candidateIndex)
+                guard element.exists else {
+                    break
+                }
+
+                guard element.isHittable else {
+                    continue
+                }
+
+                element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()
+                Thread.sleep(forTimeInterval: 1.0)
+                return true
+            }
+        }
+
+        return false
+    }
+
+    private func isCustomSchemeURL(_ value: String?) -> Bool {
+        guard let value else {
+            return false
+        }
+        return value.contains("://") && !value.hasPrefix("http://") && !value.hasPrefix("https://")
+    }
+
+    private func isExpoDevClientURL(_ value: String?) -> Bool {
+        guard let value else {
+            return false
+        }
+        return value.hasPrefix("exp+") && value.contains("://expo-development-client/")
+    }
+
+    private func tapExpoDevClientDeepLinkCoordinateFallback(app: XCUIApplication) -> Bool {
+        Thread.sleep(forTimeInterval: 1.5)
+        app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.6)).tap()
+        Thread.sleep(forTimeInterval: 1.0)
+        return true
+    }
+
+    private func tapExpoDevClientDeepLinkCandidateFallback(app: XCUIApplication, predicate: NSPredicate) -> Bool {
+        tapFirstMatchingExpoCandidate(
+            queries: [app.buttons, app.cells, app.staticTexts],
+            predicate: predicate
+        )
+    }
+
     private func hideKeyboard(app: XCUIApplication) -> [String: Any] {
         guard app.keyboards.firstMatch.exists else {
             return ok()

package/shims/ios/protocol.md

@@ -6,6 +6,7 @@ Commands are newline-delimited JSON objects:
 
 ```json
 {"cmd":"snapshot"}
+{"cmd":"viewport"}
 {"cmd":"tap","selector":"text=Continue","x":20,"y":40}
 {"cmd":"type","selector":"identifier=email","text":"hello"}
 {"cmd":"eraseText","selector":"identifier=email","maxChars":20}
@@ -43,6 +44,13 @@ that XCTest can evaluate natively. It returns:
 {"status":"ok","format":"png","base64":"..."}
 ```
 
+`viewport` returns the target application frame in XCTest point coordinates
+without crawling the element hierarchy:
+
+```json
+{"status":"ok","viewport":{"width":390,"height":844}}
+```
+
 Snapshot responses return bounded XCTest element data in a shape Zig can map
 into `UiNode`. The shim captures common interactive and readable element
 families and caps the response at 256 nodes so large application trees do not

package/src/android.zig

@@ -100,6 +100,20 @@ pub const AndroidDevice = struct {
         return error.AppDidNotOpen;
     }
 
+    pub fn setLocation(self: *AndroidDevice, latitude: f64, longitude: f64) !void {
+        const latitude_arg = try std.fmt.allocPrint(self.allocator, "{d:.6}", .{latitude});
+        defer self.allocator.free(latitude_arg);
+        const longitude_arg = try std.fmt.allocPrint(self.allocator, "{d:.6}", .{longitude});
+        defer self.allocator.free(longitude_arg);
+
+        try self.grantRuntimePermissionBestEffort("android.permission.ACCESS_FINE_LOCATION");
+        try self.grantRuntimePermissionBestEffort("android.permission.ACCESS_COARSE_LOCATION");
+
+        const result = try self.runAdb(&.{ "emu", "geo", "fix", longitude_arg, latitude_arg }, default_max_output);
+        defer result.deinit(self.allocator);
+        try result.ensureSuccess();
+    }
+
     pub fn tap(self: *AndroidDevice, x: i32, y: i32) !void {
         if (self.shim_path != null) return try self.runShimAction(.{ .kind = .tap, .x = x, .y = y });
         var args = try android_shell.tap(self.allocator, x, y);
@@ -284,6 +298,12 @@ pub const AndroidDevice = struct {
         return try ios_shim.parseSnapshotNodes(self.allocator, response);
     }
 
+    fn grantRuntimePermissionBestEffort(self: *AndroidDevice, permission: []const u8) !void {
+        const result = self.runAdb(&.{ "shell", "pm", "grant", self.app_id, permission }, 64 * 1024) catch return;
+        defer result.deinit(self.allocator);
+        result.ensureSuccess() catch {};
+    }
+
     fn runShimAction(self: *AndroidDevice, shim_command: ios_shim.Command) !void {
         const response = try self.runShim(shim_command);
         defer self.allocator.free(response);

package/src/errors.zig

@@ -45,6 +45,13 @@ pub fn classify(err: anyerror) PublicError {
         error.StepMissingY1,
         error.StepMissingX2,
         error.StepMissingY2,
+        error.StepMissingLatitude,
+        error.StepMissingLongitude,
+        error.StepLatitudeMustBeNumber,
+        error.StepLongitudeMustBeNumber,
+        error.StepLatitudeOutOfRange,
+        error.StepLongitudeOutOfRange,
+        error.RequiredFieldMustBeNumber,
         => .{ .code = "scenario.invalid", .message = "scenario is invalid" },
         error.SelectorMustNotBeEmpty,
         error.MissingSelector,
@@ -59,6 +66,7 @@ pub fn classify(err: anyerror) PublicError {
         error.SelectorNotFound => .{ .code = "runner.selector_not_found", .message = "selector not found" },
         error.CommandFailed => .{ .code = "device.command_failed", .message = "device command failed" },
         error.CommandTimedOut => .{ .code = "device.command_timed_out", .message = "device command timed out" },
+        error.UnsupportedDeviceCapability => .{ .code = "device.unsupported_capability", .message = "device capability is unsupported" },
         error.IosXCTestShimRequired => .{ .code = "ios.xctest_shim_required", .message = "iOS selector interaction requires the XCTest shim" },
         error.IosXCTestShimResponseTimedOut => .{ .code = "ios.xctest_shim_response_timeout", .message = "iOS XCTest shim response timed out" },
         error.IosXCTestShimStartTimedOut => .{ .code = "ios.xctest_shim_start_timeout", .message = "iOS XCTest shim server startup timed out" },