@devicelab/maestro-runner-darwin-x64 1.1.25

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/RunnerTests.swift

@@ -0,0 +1,197 @@
+//
+//  RunnerTests.swift
+//  AgentDeviceRunnerUITests
+//
+//  Created by Michał Pierzchała on 30/01/2026.
+//
+
+import XCTest
+import Network
+#if canImport(UIKit)
+import UIKit
+typealias RunnerImage = UIImage
+#elseif canImport(AppKit)
+import AppKit
+typealias RunnerImage = NSImage
+#endif
+
+final class RunnerTests: XCTestCase {
+  enum RunnerErrorDomain {
+    static let general = "AgentDeviceRunner"
+    static let exception = "AgentDeviceRunner.NSException"
+  }
+
+  enum RunnerErrorCode {
+    static let noResponseFromMainThread = 1
+    static let commandReturnedNoResponse = 2
+    static let mainThreadExecutionTimedOut = 3
+    static let objcException = 1
+  }
+
+  static let springboardBundleId = "com.apple.springboard"
+  static let defaultRecordingFps: Int32 = 15
+  static let maxListenerRetries = 5
+  static let listenerRetryDelay: TimeInterval = 1.0
+  var listener: NWListener?
+  var listenerRetriesRemaining = RunnerTests.maxListenerRetries
+  var doneExpectation: XCTestExpectation?
+  let app = XCUIApplication()
+  lazy var springboard = XCUIApplication(bundleIdentifier: Self.springboardBundleId)
+  var currentApp: XCUIApplication?
+  var currentBundleId: String?
+  let maxRequestBytes = 2 * 1024 * 1024
+  let maxSnapshotElements = 600
+  let fastSnapshotLimit = 300
+  let mainThreadExecutionTimeout: TimeInterval = 30
+  let appExistenceTimeout: TimeInterval = 30
+  let retryCooldown: TimeInterval = 0.2
+  // Local edit (not in upstream agent-device): post-snapshot/post-activate
+  // stabilization windows shortened from 0.2 / 0.25 s. Upstream value gives
+  // an AI-driven runner time for layout to settle between a read and the
+  // next interaction; maestro-runner's snapshot is part of selector
+  // resolution that's immediately followed by an interaction at a known
+  // coordinate, so a 50ms window is enough to absorb any in-flight UIKit
+  // layout pass without paying for hypothetical agent latency.
+  let postSnapshotInteractionDelay: TimeInterval = 0.05
+  let firstInteractionAfterActivateDelay: TimeInterval = 0.1
+  let scrollInteractionIdleTimeoutDefault: TimeInterval = 1.0
+  let tvRemoteDoublePressDelayDefault: TimeInterval = 0.0
+  let minRecordingFps = 1
+  let maxRecordingFps = 120
+  let minRecordingQuality = 5
+  let maxRecordingQuality = 10
+  var needsPostSnapshotInteractionDelay = false
+  var needsFirstInteractionDelay = false
+  // Local extension: cache the most recent idleCheck screenshot so
+  // subsequent calls in the same wait loop only need ONE fresh capture.
+  var lastIdleScreenshot: (image: RunnerImage, capturedAt: Date)?
+  static let idleScreenshotCacheTTL: TimeInterval = 1.0
+  var activeRecording: ScreenRecorder?
+  let interactiveTypes: Set<XCUIElement.ElementType> = [
+    .button,
+    .cell,
+    .checkBox,
+    .collectionView,
+    .link,
+    .menuItem,
+    .picker,
+    .searchField,
+    .segmentedControl,
+    .slider,
+    .stepper,
+    .switch,
+    .tabBar,
+    .textField,
+    .secureTextField,
+    .textView
+  ]
+  // Keep blocker actions narrow to avoid false positives from generic hittable containers.
+  let actionableTypes: Set<XCUIElement.ElementType> = [
+    .button,
+    .cell,
+    .link,
+    .menuItem,
+    .checkBox,
+    .switch
+  ]
+
+  // MARK: - XCTest Entry
+
+  override func setUp() {
+    continueAfterFailure = true
+    // Override XCTest's clipped snapshot request params so element trees are
+    // complete on deep React Native hierarchies (matches WDA / devicekit-ios).
+    DLApplyCompleteSnapshotParams()
+  }
+
+  @MainActor
+  func testCommand() throws {
+    doneExpectation = expectation(description: "agent-device command handled")
+    NSLog("AGENT_DEVICE_RUNNER_HEADLESS_STARTUP=1")
+    let queue = DispatchQueue(label: "agent-device.runner")
+    let desiredPort = RunnerEnv.resolvePort()
+    NSLog("AGENT_DEVICE_RUNNER_DESIRED_PORT=%d", desiredPort)
+    startListener(desiredPort: desiredPort, queue: queue)
+
+    guard let expectation = doneExpectation else {
+      XCTFail("runner expectation was not initialized")
+      return
+    }
+    NSLog("AGENT_DEVICE_RUNNER_WAITING")
+    let result = XCTWaiter.wait(for: [expectation], timeout: 24 * 60 * 60)
+    NSLog("AGENT_DEVICE_RUNNER_WAIT_RESULT=%@", String(describing: result))
+    if result != .completed {
+      XCTFail("runner wait ended with \(result)")
+    }
+  }
+
+  private func startListener(desiredPort: UInt16, queue: DispatchQueue) {
+    do {
+      let newListener = try makeRunnerListener(desiredPort: desiredPort)
+      listener = newListener
+      newListener.stateUpdateHandler = { [weak self] state in
+        switch state {
+        case .ready:
+          NSLog("AGENT_DEVICE_RUNNER_LISTENER_READY")
+          // A working listener proves recovery — restore the full retry
+          // budget so an occasional network-stack hiccup hours apart
+          // never accumulates into an exit.
+          self?.listenerRetriesRemaining = Self.maxListenerRetries
+          if let listenerPort = self?.listener?.port {
+            NSLog("AGENT_DEVICE_RUNNER_PORT=%d", listenerPort.rawValue)
+          } else {
+            NSLog("AGENT_DEVICE_RUNNER_PORT_NOT_SET")
+          }
+        case .failed(let error):
+          self?.handleListenerFailure(error, desiredPort: desiredPort, queue: queue)
+        default:
+          break
+        }
+      }
+      newListener.newConnectionHandler = { [weak self] conn in
+        conn.start(queue: queue)
+        self?.handle(connection: conn)
+      }
+      newListener.start(queue: queue)
+    } catch {
+      handleListenerFailure(error, desiredPort: desiredPort, queue: queue)
+    }
+  }
+
+  // The listener failing used to end the session immediately, so any
+  // transient failure in the sim's network stack (whose daemons are
+  // known to crash-loop on some runtime/Xcode combinations) silently
+  // killed the runner mid-session. Rebind on the same port instead —
+  // the host only knows this port — and exit only once the budget is
+  // exhausted, with the reason in the log for post-mortems.
+  private func handleListenerFailure(_ error: Error, desiredPort: UInt16, queue: DispatchQueue) {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_LISTENER_FAILED=%@ retriesLeft=%d",
+      String(describing: error), listenerRetriesRemaining)
+    listener?.cancel()
+    listener = nil
+    guard listenerRetriesRemaining > 0 else {
+      NSLog("AGENT_DEVICE_RUNNER_EXIT reason=listener_failed error=%@", String(describing: error))
+      doneExpectation?.fulfill()
+      return
+    }
+    listenerRetriesRemaining -= 1
+    queue.asyncAfter(deadline: .now() + Self.listenerRetryDelay) { [weak self] in
+      self?.startListener(desiredPort: desiredPort, queue: queue)
+    }
+  }
+
+  private func makeRunnerListener(desiredPort: UInt16) throws -> NWListener {
+    if desiredPort > 0, let port = NWEndpoint.Port(rawValue: desiredPort) {
+      #if os(macOS)
+        let parameters = NWParameters.tcp
+        parameters.allowLocalEndpointReuse = true
+        parameters.requiredLocalEndpoint = .hostPort(host: "127.0.0.1", port: port)
+        return try NWListener(using: parameters)
+      #else
+        return try NWListener(using: .tcp, on: port)
+      #endif
+    }
+    return try NWListener(using: .tcp)
+  }
+}

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/SnapshotParams.h

@@ -0,0 +1,28 @@
+#ifndef SnapshotParams_h
+#define SnapshotParams_h
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Overrides XCTest's accessibility-snapshot request parameters so
+ * `XCUIElement.snapshot()` returns a complete tree instead of XCTest's
+ * silently-clipped default.
+ *
+ * XCTest's `-[XCAXClient_iOS defaultParameters]` nominally defaults maxDepth /
+ * maxChildren / maxArrayCount to INT_MAX, but in practice the tree is clipped
+ * and elements behind modal views are dropped. This swizzles defaultParameters
+ * to re-assert generous limits and set `snapshotKeyHonorModalViews=0`, which is
+ * exactly what WebDriverAgent and mobile-next/devicekit-ios do. It is the fix
+ * for deep React Native trees where native shadow views and modal-obscured
+ * content were missing from our snapshot.
+ *
+ * Idempotent and safe: a no-op if XCAXClient_iOS is unavailable. Call once at
+ * runner startup, before the first snapshot.
+ */
+void DLApplyCompleteSnapshotParams(void);
+
+NS_ASSUME_NONNULL_END
+
+#endif /* SnapshotParams_h */

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/SnapshotParams.m

@@ -0,0 +1,49 @@
+#import "SnapshotParams.h"
+
+#import <objc/runtime.h>
+
+// Original implementation of -[XCAXClient_iOS defaultParameters], captured when
+// we swap in our own so we can start from XCTest's real defaults and only
+// override the keys we care about.
+static NSDictionary *(*dl_original_defaultParameters)(id, SEL) = NULL;
+
+// Bounded generous depth. INT_MAX invites runaway cost on pathological trees;
+// 60 matches devicekit-ios and is deep enough for real React Native hierarchies
+// while still defeating XCTest's default clipping.
+static const int kDLSnapshotMaxDepth = 60;
+
+static id dl_swizzled_defaultParameters(id self, SEL _cmd) {
+  NSDictionary *original =
+      dl_original_defaultParameters ? dl_original_defaultParameters(self, _cmd) : @{};
+  NSMutableDictionary *merged =
+      [NSMutableDictionary dictionaryWithDictionary:(original ?: @{})];
+  merged[@"maxDepth"] = @(kDLSnapshotMaxDepth);
+  merged[@"maxChildren"] = @(INT_MAX);
+  merged[@"maxArrayCount"] = @(INT_MAX);
+  // 0 == do NOT honor modal views, i.e. keep elements behind a modal/dialog in
+  // the snapshot. Our own hittable/occlusion pass still marks obscured elements
+  // as non-hittable, so this only adds completeness.
+  merged[@"snapshotKeyHonorModalViews"] = @0;
+  return [merged copy];
+}
+
+void DLApplyCompleteSnapshotParams(void) {
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    Class cls = NSClassFromString(@"XCAXClient_iOS");
+    if (cls == Nil) {
+      NSLog(@"DL_SNAPSHOT_PARAMS: XCAXClient_iOS unavailable; snapshot params unchanged");
+      return;
+    }
+    Method method =
+        class_getInstanceMethod(cls, NSSelectorFromString(@"defaultParameters"));
+    if (method == NULL) {
+      NSLog(@"DL_SNAPSHOT_PARAMS: -defaultParameters unavailable; snapshot params unchanged");
+      return;
+    }
+    dl_original_defaultParameters = (NSDictionary * (*)(id, SEL))
+        method_setImplementation(method, (IMP)dl_swizzled_defaultParameters);
+    NSLog(@"DL_SNAPSHOT_PARAMS: applied (maxDepth=%d, maxChildren=INT_MAX, honorModalViews=0)",
+          kDLSnapshotMaxDepth);
+  });
+}

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/SyntheticTyping.h

@@ -0,0 +1,17 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Local extension (not in upstream agent-device). Synthesizes typing events
+// via the private XCSynthesizedEventRecord + XCPointerEventPath +
+// XCUIDevice.eventSynthesizer pathway — the same mechanism WebDriverAgent
+// uses for FBTypeText. Unlike XCUIElement.typeText / XCUIApplication.typeText,
+// this does NOT require XCUIElement.hasKeyboardFocus to be true. That is
+// what makes it work for RN SecureTextField on iOS Simulator, where the
+// keyboard appears visually but hasKeyboardFocus stays false and the public
+// typeText APIs silently drop characters.
+//
+// Returns YES on success. Writes a NSError into *outError on failure.
+BOOL DLSendSyntheticTyping(NSString *text, NSUInteger typingSpeed, NSError * _Nullable * _Nullable outError);
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/DevicelabIOSRunner/DevicelabIOSRunnerUITests/SyntheticTyping.m

@@ -0,0 +1,86 @@
+#import "SyntheticTyping.h"
+#import <UIKit/UIKit.h>
+#import "PrivateHeaders/XCTest/XCSynthesizedEventRecord.h"
+#import "PrivateHeaders/XCTest/XCPointerEventPath.h"
+#import "PrivateHeaders/XCTest/XCUIDevice.h"
+
+BOOL DLSendSyntheticTyping(NSString *text, NSUInteger typingSpeed, NSError * _Nullable * _Nullable outError) {
+  if (text.length == 0) {
+    return YES;
+  }
+  if (typingSpeed == 0) {
+    typingSpeed = 60; // matches WDA default
+  }
+
+  XCSynthesizedEventRecord *record =
+    [[XCSynthesizedEventRecord alloc] initWithName:@"DLSyntheticTyping"];
+  XCPointerEventPath *path = [[XCPointerEventPath alloc] initForTextInput];
+  [path typeText:text atOffset:0.0 typingSpeed:typingSpeed shouldRedact:NO];
+  [record addPointerEventPath:path];
+
+  id device = [XCUIDevice sharedDevice];
+  id synthesizer = [device valueForKey:@"eventSynthesizer"];
+  if (synthesizer == nil) {
+    if (outError) {
+      *outError = [NSError errorWithDomain:@"DevicelabIOSRunner"
+                                       code:1
+                                   userInfo:@{NSLocalizedDescriptionKey:
+                                              @"XCUIDevice.eventSynthesizer unavailable"}];
+    }
+    return NO;
+  }
+
+  __block BOOL done = NO;
+  __block NSError *innerError = nil;
+
+  SEL sel = NSSelectorFromString(@"synthesizeEvent:completion:");
+  if (![synthesizer respondsToSelector:sel]) {
+    if (outError) {
+      *outError = [NSError errorWithDomain:@"DevicelabIOSRunner"
+                                       code:2
+                                   userInfo:@{NSLocalizedDescriptionKey:
+                                              @"eventSynthesizer does not support synthesizeEvent:completion:"}];
+    }
+    return NO;
+  }
+
+  NSMethodSignature *sig = [synthesizer methodSignatureForSelector:sel];
+  NSInvocation *inv = [NSInvocation invocationWithMethodSignature:sig];
+  inv.target = synthesizer;
+  inv.selector = sel;
+  XCSynthesizedEventRecord *recordArg = record;
+  [inv setArgument:&recordArg atIndex:2];
+  void (^completion)(BOOL, NSError *) = ^(BOOL success, NSError *invokeError) {
+    if (invokeError != nil) {
+      innerError = invokeError;
+    }
+    done = YES;
+  };
+  [inv setArgument:&completion atIndex:3];
+  [inv invoke];
+
+  // Spin the run loop until the completion handler fires.
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:30.0];
+  while (!done && [deadline timeIntervalSinceNow] > 0) {
+    [[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode
+                             beforeDate:[NSDate dateWithTimeIntervalSinceNow:0.05]];
+  }
+
+  if (!done) {
+    if (outError) {
+      *outError = [NSError errorWithDomain:@"DevicelabIOSRunner"
+                                       code:3
+                                   userInfo:@{NSLocalizedDescriptionKey:
+                                              @"synthesizeEvent timed out"}];
+    }
+    return NO;
+  }
+
+  if (innerError != nil) {
+    if (outError) {
+      *outError = innerError;
+    }
+    return NO;
+  }
+  return YES;
+}

package/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

@@ -0,0 +1,258 @@
+# devicelab-ios-runner — Wire Protocol v1
+
+Internal HTTP+JSON protocol between maestro-runner's Go consumer (`pkg/driver/devicelab_ios/`) and the on-device XCUITest runner.
+
+**Status:** v1 draft, no consumers yet. Free to evolve.
+**Owners:** maestro-runner team.
+**Stability:** owned outright. The protocol bumps on breaking change; see [Versioning](#versioning).
+
+## Design rules
+
+These are non-negotiable. If a change conflicts with one of these, the change is wrong.
+
+1. **Stateless app binding.** Every command carries `appBundleId`. Runner caches `XCUIApplication(bundleIdentifier:)` until it changes. No session lifecycle.
+2. **No element IDs / element handles.** Operations target either coordinates or fresh selectors. Eliminates stale-element bugs and WebDriver session state entirely.
+3. **Full hierarchy, no filtering.** Snapshot returns every node with every accessibility attribute. No `interactiveOnly` / `compact` / occlusion / element caps. Flow selectors run on the Go side against the full tree.
+4. **Inline binary payloads.** Screenshots and recordings return base64 bytes in the JSON envelope. No file-on-device + fetch-back round trips.
+5. **Caller-chosen port.** Go side picks the port and injects via env var. Runner never picks a random port.
+6. **Both path and direction gestures.** Swipe / scroll accept either `(x, y, x2, y2, durationMs)` or `(direction, percent)`.
+7. **Every command times out.** Hard 30s ceiling enforced server-side. Hung commands cannot wedge the runner.
+
+## Transport
+
+| Field | Value |
+|---|---|
+| Protocol | HTTP/1.1 over TCP |
+| Host | `127.0.0.1` (simulator) or tunneled device port |
+| Port | Caller-injected via `DEVICELAB_IOS_RUNNER_PORT` env var |
+| Path | `POST /command` |
+| Content-Type | `application/json; charset=utf-8` |
+| Max request size | 4 MB (covers any reasonable `type` text payload) |
+| Connection | Keep-alive supported; runner is single-threaded so requests serialize |
+
+The runner also exposes `GET /health` (no JSON body, returns `200` once ready) for the Go side to await readiness without sending a command.
+
+## Port allocation
+
+- Go side picks a free ephemeral port (`net.Listen("tcp", "127.0.0.1:0")`, immediately close, reuse port number).
+- Inject the port into the runner via the `.xctestrun` `EnvironmentVariables.DEVICELAB_IOS_RUNNER_PORT` before invoking `xcodebuild test-without-building`.
+- For real devices: same port on device, plus `iproxy <hostPort>:<devicePort>` (or equivalent via `pymobiledevice3`) so `127.0.0.1:<hostPort>` reaches the runner.
+
+## Request envelope
+
+```jsonc
+{
+  "command": "<commandType>",
+  "appBundleId": "<bundle-id>",          // required for app-targeted commands
+  // ... command-specific fields
+}
+```
+
+Unknown fields are ignored. Missing required fields produce `INVALID_ARGUMENT`.
+
+## Response envelope
+
+```jsonc
+{
+  "ok": true,
+  "data": { /* command-specific */ }
+}
+```
+
+```jsonc
+{
+  "ok": false,
+  "error": {
+    "code": "ELEMENT_NOT_FOUND",
+    "message": "human-readable",
+    "details": { /* optional structured context */ }
+  }
+}
+```
+
+`data` is always an object (never an array or scalar). `error` is present iff `ok === false`.
+
+### Error codes
+
+| Code | When |
+|---|---|
+| `INVALID_ARGUMENT` | Missing/invalid request field |
+| `UNSUPPORTED_OPERATION` | Command exists but is not available in this build/platform |
+| `APP_NOT_RUNNING` | `appBundleId` not foregrounded and could not be activated |
+| `ELEMENT_NOT_FOUND` | Selector returned zero matches |
+| `ELEMENT_NOT_INTERACTABLE` | Element matched but is not visible / enabled / hittable |
+| `ALERT_PRESENT` | A system alert blocked the operation |
+| `TIMEOUT` | Server-side 30s ceiling exceeded |
+| `XCUI_EXCEPTION` | Underlying XCUITest threw an ObjC exception (retried once before this) |
+| `RUNNER_INTERNAL` | Bug in the runner |
+
+## Versioning
+
+- Protocol version is `1`. Single integer. Bumped on any breaking change to existing command shapes or response semantics.
+- `GET /version` returns `{"protocolVersion": 1, "runnerBuild": "<sha-or-tag>"}`.
+- The Go client asserts on connect that `protocolVersion` matches the version it was built against. Mismatch = hard error, no version negotiation.
+- Adding new optional fields or new commands does not bump the version.
+
+## Command surface
+
+### Lifecycle
+
+| Command | Inputs | Returns | Notes |
+|---|---|---|---|
+| `appLaunch` | `appBundleId`, `arguments[]?`, `environment{}?` | `{ pid, launched: true }` | `XCUIApplication(bundleIdentifier:).launch()`. Replaces cached `currentApp`. |
+| `appActivate` | `appBundleId` | `{ pid, activated: true }` | Foreground without relaunch. |
+| `appTerminate` | `appBundleId` | `{ terminated: true }` | |
+| `appState` | `appBundleId` | `{ state: "running"|"notRunning"|"runningBackground" }` | |
+| `appCurrent` | (none) | `{ appBundleId?, pid? }` | Returns currently foregrounded app. |
+| `shutdown` | (none) | `{ shuttingDown: true }` | Runner exits cleanly. |
+| `ping` | (none) | `{ uptimeMs }` | Round-trip baseline. |
+
+### Snapshot
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `snapshot` | `appBundleId?` | `{ nodes: [SnapshotNode] }` |
+| `screenSize` | `appBundleId?` | `{ width, height, scale }` |
+
+`snapshot` always returns the full tree. If `appBundleId` is omitted, snapshots the currently foregrounded app via `XCUIApplication()`. **No filtering, no caps, no occlusion computation.**
+
+#### SnapshotNode
+
+Flat array; tree reconstructed via `parentIndex`. Every node carries every available accessibility field — Go-side selectors decide what to match on.
+
+```jsonc
+{
+  "index": 12,
+  "parentIndex": 5,        // omitted for root
+  "depth": 3,
+  "type": "XCUIElementTypeButton",   // raw XCUIElementType string
+  "identifier": "login-button",      // .identifier — accessibility ID
+  "label": "Sign In",                // .label
+  "value": "",                       // .value (e.g. text field contents)
+  "placeholderValue": "",            // .placeholderValue
+  "rect": { "x": 32.0, "y": 624.6, "width": 338.0, "height": 50.0 },
+  "enabled": false,
+  "displayed": true,                 // visible in the viewport (rect inside screen bounds, not occluded by parent clipping)
+  "selected": false,
+  "focused": false,
+  "hittable": true                   // .isHittable
+}
+```
+
+**Deltas from agent-device's runner:** adds `identifier`, `value`, `placeholderValue`, `selected`, `focused`, `displayed`. Drops `interactiveOnly`/`compact`/occlusion logic.
+
+### Find
+
+These are conveniences when the Go side already knows what it wants and does not need the full snapshot. They return one or more `SnapshotNode`s. **No element ID is retained** — the returned bounds are the caller's only handle.
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `findByIdentifier` | `appBundleId`, `identifier` | `{ found: bool, node?: SnapshotNode }` |
+| `findByLabel` | `appBundleId`, `label`, `exact?: bool` | `{ found: bool, node?: SnapshotNode }` |
+| `findByPredicate` | `appBundleId`, `predicate` | `{ found: bool, nodes: [SnapshotNode] }` |
+| `findByClassChain` | `appBundleId`, `query` | `{ found: bool, nodes: [SnapshotNode] }` |
+
+Selector strategies match WDA's: predicate strings and class chains map directly to `XCUIElement.matching(NSPredicate(...))` and the XCUIElementQuery class-chain syntax.
+
+### Gestures
+
+All gestures accept `appBundleId` so the runner can target the right `XCUIApplication` for coordinate-space resolution.
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `tap` | `x, y` | `{ gestureStartMs, gestureEndMs, referenceWidth, referenceHeight }` |
+| `doubleTap` | `x, y` | gesture timings |
+| `longPress` | `x, y, durationMs` | gesture timings |
+| `swipe` | EITHER `x, y, x2, y2, durationMs` OR `direction, percent` | gesture timings + `path: [{x,y},...]` |
+| `scroll` | EITHER coordinate path OR `direction, percent` (same as swipe but with slower default duration) | gesture timings |
+| `drag` | `x, y, x2, y2, durationMs` (press-before-move hold), `moveDurationMs?` (movement time — local addition; when set, drags via `press(forDuration:thenDragTo:withVelocity:thenHoldForDuration:)` with a 250ms settle before release, for dragAndDrop reorder semantics) | gesture timings + path |
+| `pinch` | `x, y, scale, durationMs` | gesture timings |
+| `pressButton` | `button: "home"|"lock"|"volumeUp"|"volumeDown"|"appSwitcher"` | `{ pressed: true }` |
+| `rotate` | `orientation: "portrait"|"landscapeLeft"|"landscapeRight"|"portraitUpsideDown"` | `{ orientation }` |
+| `appearance` | — | `{ appearance: "dark"|"light" }` |
+| `setAppearance` | `appearance: "dark"|"light"` | `{ appearance }` — the appearance that took effect, re-read after setting, not the request echoed back |
+
+**Delta from agent-device:** swipe + scroll accept coordinate paths AND direction. drag, pinch, pressButton, rotate kept; tapSeries / dragSeries / interactionFrame dropped (LLM-shaped, not needed for flows). `appearance` / `setAppearance` are local additions wrapping `XCUIDevice.appearance` (iOS 15+); they exist because `simctl ui appearance` covers only simulators, so this is what makes dark mode work on physical devices. `unspecified` is reported as `light` — nothing is being forced, and that is how it renders.
+
+### Text
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `type` | `text`, `typingFrequency?` | `{ typed }` |
+| `eraseText` | `count` (number of chars to delete) | `{ erased }` |
+| `keyPress` | `key: "enter"|"tab"|"backspace"|"escape"` | `{ pressed }` |
+| `clipboardGet` | (none) | `{ text }` |
+| `clipboardSet` | `text` | `{ set: true }` |
+
+`type` sends keys to the currently focused element (caller is responsible for tapping to focus first — same as WDA today).
+
+### Alerts
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `alertVisible` | (none) | `{ visible: bool, button1Label?, button2Label? }` |
+| `alertAccept` | (none) | `{ dismissed: true }` |
+| `alertDismiss` | (none) | `{ dismissed: true }` |
+
+### URLs
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `openURL` | `url` | `{ opened: true }` |
+
+Uses `XCUIDevice.shared.system.open(URL)` (iOS 15+) or SpringBoard tap path as fallback.
+
+### Settings (runtime)
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `setIdleTimeout` | `timeoutMs` (0 disables) | `{ set }` |
+| `setTypingFrequency` | `freq` (chars/sec) | `{ set }` |
+| `setFindTimeout` | `timeoutMs` | `{ set }` |
+
+Cover `core.SetWaitForIdleTimeout`, `TypingFrequencyConfigurer`, `core.SetFindTimeout`.
+
+### Recording (Phase 5+; not in v1 minimum)
+
+| Command | Inputs | Returns |
+|---|---|---|
+| `recordStart` | `outPath` (host path), `fps?`, `quality?` | `{ recording: true }` |
+| `recordStop` | (none) | `{ bytes: <base64> }` or `{ outPath }` |
+
+Deferred — `core.Driver` doesn't expose recording today; can add in Phase 6.
+
+## Out of scope for v1
+
+These exist in maestro-runner today but stay on the **Go side** via `xcrun simctl` / `xcrun devicectl`, not in the runner:
+
+- App install / uninstall (`simctl install` / `devicectl install`)
+- Clear app data (uninstall + reinstall)
+- Permission grants (`simctl privacy`, `devicectl set-permission`)
+- Reset keychain (`simctl keychain reset`)
+- Airplane mode (open Settings app, find toggle, tap — uses regular runner commands)
+- Reading app container files
+
+This split mirrors how the current `pkg/driver/wda/` and `pkg/driver/devicelab/` (Android) drivers do these via shell calls, not in-process.
+
+## Deltas from agent-device's protocol (with rationale)
+
+| Item | agent-device | devicelab-ios-runner | Why |
+|---|---|---|---|
+| Element refs | `@e1`/`@e2` computed on TS side, used in tap | None | Stale-element risk; no benefit for flows that re-snapshot anyway |
+| Snapshot filtering | `interactiveOnly`, `compact`, occlusion | None | LLM-shaped; flows need full tree for selector matching |
+| Snapshot caps | 600 elements / 2 MB | None | Caps cause silent flow failures when the screen is busy |
+| Screenshot return | File path on simulator | Inline base64 bytes | One round trip instead of two; works the same on real devices |
+| Swipe | Direction only | Path OR direction | maestro-runner flows often use coordinate swipes for trackpads/sliders |
+| Snapshot fields | `index/depth/type/label/rect/hittable/enabled` | + `identifier`, `value`, `placeholderValue`, `selected`, `focused`, `displayed` | Required by `id=` / `value=` / focus-aware selectors |
+| Port allocation | Random if env unset | Always caller-injected | Real-device tunneling needs the port before launch |
+| `readText` | Point-based (`x, y` required) | Use `findByIdentifier` or `snapshot` and read `label`/`value` directly | Single way to get text |
+| App lifecycle | TS-side only (`simctl launch`) | Either runner (via `XCUIApplication.launch()`) or Go-side (`simctl`) | Runner-side is faster for warm flows; Go-side stays available |
+| Recording | First-class command | Deferred to Phase 5+ | Not in `core.Driver` today |
+| Protocol stability | "Maintainer document, can change" | Versioned, breaking changes bump version | We are the only consumer; cheap to be strict |
+
+## Open questions to revisit before Phase 3 implementation
+
+- **`type` without a tap-to-focus first.** WDA's `SendKeys` works against the global keyboard. Should we require a focused element, or accept silent no-op? Current call sites all tap first — keep WDA semantics.
+- **`displayed` semantics.** WDA's `isDisplayed` differs from XCUI's `isHittable`. We compute `displayed` as "rect intersects screen bounds AND parent clip path", `hittable` as raw `.isHittable`. Validate with TestHive flows.
+- **Predicate string compatibility.** WDA supports a specific NSPredicate dialect via Appium. We should support the same dialect so existing flow selectors keep working — verify against `pkg/driver/wda/driver.go:findElementByWDA`.
+- **`scroll` vs `swipe` duration defaults.** WDA scrolls slower than it swipes. Per react-navigation PR #13027, swipe duration tuning is touchy. Pick defaults that match upstream Maestro out of the gate.

package/drivers/ios/DevicelabIOSRunner/README.md

@@ -0,0 +1,38 @@
+# devicelab-ios-runner
+
+XCUITest-based iOS automation runner for the `devicelab` driver in [maestro-runner](https://github.com/devicelab-dev/maestro-runner). On-device counterpart to [`devicelab-android-driver`](../devicelab-android-driver).
+
+## Goal
+
+Replace `pkg/driver/wda/` in maestro-runner with a self-contained, owned XCUITest runner. Fix the two iOS blockers from react-navigation PR #13027:
+
+1. **No runtime third-party download** — runner is bundled in `maestro-runner` release artifacts; no fetch over the network at test time.
+2. **Local parity with upstream Maestro** — flows that pass under `maestro` must also pass under `maestro-runner` locally, with the same retry profile.
+
+## Status
+
+**Phase 0 — Reference validation.** Building `callstackincubator/agent-device`'s XCUITest runner as a black-box sanity check that the architectural design (XCUITest + `Network.framework` HTTP + JSON command protocol) actually works for our flows before committing to a fresh Swift rewrite.
+
+See [PLAN.md](./PLAN.md).
+
+## Layout (planned)
+
+```
+devicelab-ios-runner/
+├── README.md
+├── PLAN.md                       # phased plan and acceptance criteria
+├── PROTOCOL.md                   # wire protocol spec (written after Phase 0)
+├── .gitignore
+├── DevicelabIOSRunner.xcodeproj/ # Xcode project (Phase 2+)
+├── DevicelabIOSRunner/           # UI test target sources (fresh Swift)
+└── scripts/
+    └── build.sh                  # standalone build pipeline
+```
+
+Built artifact will be vendored into `maestro-runner` at `drivers/ios/devicelab-ios-runner/` and bundled by `build-release.sh`.
+
+## References
+
+- Architecture inspiration: [agent-device findings doc](../../temp/test/agent-device/findings-ios-android.md)
+- Cloned agent-device repo (reference only): `/Users/omnarayan/work/temp/test/agent-device/`
+- Android counterpart pattern: `/Users/omnarayan/work/support-tools/devicelab-android-driver`