@devicelab/maestro-runner-darwin-arm64 1.1.27 → 1.1.28

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

@@ -0,0 +1,87 @@
+#ifndef RunnerXCTestTimeouts_h
+#define RunnerXCTestTimeouts_h
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class XCUIApplication;
+
+/// The outcome of +waitForQuiescenceOfApplication:timeout:.
+typedef NS_ENUM(NSInteger, RunnerQuiescence) {
+  /// XCTest saw the app's event loop go idle and its animations finish.
+  RunnerQuiescenceIdle = 0,
+  /// The wait ended (the cap passed) without both signals.
+  RunnerQuiescenceBusy = 1,
+  /// A private symbol is missing, so nothing was waited for and nothing is
+  /// known. Never to be read as idle.
+  RunnerQuiescenceUnavailable = 2,
+};
+
+/**
+ * Scoped overrides of XCTest's process-wide request timeouts.
+ *
+ * XCTest resolves element queries through the target app's automation
+ * session over XPC, and every such request waits up to the XPC request
+ * timeout (30s by default). When the target app leaves the screen while a
+ * query is in flight (Home, the app switcher), iOS suspends it and the reply
+ * never comes, so the query waits the full 30s. The runner executes commands
+ * one at a time on the main thread, so every later command waits too.
+ *
+ * These helpers set a timeout for the duration of a block and restore the
+ * previous value afterwards, even if the block raises. The pattern follows
+ * WebDriverAgent's FBXCAXClientProxy (+withXPCRequestTimeout:do:,
+ * -withAXTimeout:do:).
+ *
+ * A shorter timeout only makes this process stop waiting. The request that
+ * was abandoned keeps running on its channel until the app answers or dies.
+ *
+ * Every private symbol is looked up at runtime. When one is missing the block
+ * runs with XCTest's own timeout, so an XCTest change can make a hang long
+ * again but can never break a snapshot.
+ */
+@interface RunnerXCTestTimeouts : NSObject
+
+/// XCTest's XPC request timeout as it stood before this class first changed
+/// it, or 0 when the private getter is unavailable. The runner uses it to go
+/// back to XCTest's own patience inside a shorter scope.
++ (NSTimeInterval)defaultXPCRequestTimeout;
+
+/// Runs @c block once with XCTest's XPC request timeout (the per-request
+/// limit on element queries answered by an app's automation session) set to
+/// @c timeout seconds. Returns YES if the timeout was applied, NO if the
+/// private setter is unavailable and the block ran with XCTest's own value.
++ (BOOL)withXPCRequestTimeout:(NSTimeInterval)timeout do:(NS_NOESCAPE void (^)(void))block;
+
+/// Runs @c block once with the accessibility client's AXTimeout (the
+/// per-request limit on direct accessibility requests, such as the private
+/// AX snapshot) set to @c timeout seconds. Returns YES if the timeout was
+/// applied, NO if the block ran with the existing value.
++ (BOOL)withAXTimeout:(NSTimeInterval)timeout do:(NS_NOESCAPE void (^)(void))block;
+
+/// Waits up to @c timeout seconds for @c app to go quiescent, animations
+/// included: the wait XCTest runs before and after each synthesized event,
+/// run on demand. Follows WebDriverAgent's -fb_waitUntilStableWithTimeout:,
+/// which bounds XCUIApplicationProcess
+/// -waitForQuiescenceIncludingAnimationsIdle:(isPreEvent:) by setting
+/// XCTest's application-state timeout for the duration of the call.
+///
+/// The answer comes from the process's own eventLoopHasIdled and
+/// animationsHaveFinished flags after the wait, not from how long it took.
+/// XCTest skips the whole check for an app that is not in the foreground
+/// and leaves the flags stale, so callers must only ask about a foreground
+/// app. Must be called on the main thread (XCTest asserts it). Does not
+/// activate the app.
+///
+/// When the event loop fails to idle within the cap, XCTest may take a
+/// spindump of the app before returning, so the call can outlast
+/// @c timeout; callers report the time they actually waited.
++ (RunnerQuiescence)waitForQuiescenceOfApplication:(XCUIApplication *)app
+                                           timeout:(NSTimeInterval)timeout
+    NS_SWIFT_NAME(waitForQuiescence(of:timeout:));
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* RunnerXCTestTimeouts_h */

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

@@ -0,0 +1,207 @@
+#import "RunnerXCTestTimeouts.h"
+
+#import <XCTest/XCTest.h>
+#import <dlfcn.h>
+#import <objc/message.h>
+
+// Exported by XCUIAutomation (Xcode 15 through 27); WebDriverAgent declares
+// the same pairs in CDStructures.h. Looked up rather than linked so the
+// runner still builds and runs if a later Xcode drops them.
+typedef double (*RunnerTimeoutGetter)(void);
+typedef void (*RunnerTimeoutSetter)(double);
+
+static RunnerTimeoutGetter RunnerXPCGetter(void) {
+  static RunnerTimeoutGetter getter = NULL;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    getter = (RunnerTimeoutGetter)dlsym(RTLD_DEFAULT, "_XCTXPCRequestTimeout");
+  });
+  return getter;
+}
+
+static RunnerTimeoutSetter RunnerXPCSetter(void) {
+  static RunnerTimeoutSetter setter = NULL;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    setter = (RunnerTimeoutSetter)dlsym(RTLD_DEFAULT, "_XCTSetXPCRequestTimeout");
+  });
+  return setter;
+}
+
+// The limit on XCTest's app-state waits, quiescence among them.
+static RunnerTimeoutGetter RunnerAppStateGetter(void) {
+  static RunnerTimeoutGetter getter = NULL;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    getter = (RunnerTimeoutGetter)dlsym(RTLD_DEFAULT, "_XCTApplicationStateTimeout");
+  });
+  return getter;
+}
+
+static RunnerTimeoutSetter RunnerAppStateSetter(void) {
+  static RunnerTimeoutSetter setter = NULL;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    setter = (RunnerTimeoutSetter)dlsym(RTLD_DEFAULT, "_XCTSetApplicationStateTimeout");
+  });
+  return setter;
+}
+
+// One lock per global, recursive so scopes can nest (a default-timeout retry
+// inside a short scope). Commands run on the main thread, so the lock only
+// guards against a future caller on another thread.
+static NSRecursiveLock *RunnerTimeoutLock(void) {
+  static NSRecursiveLock *lock = nil;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    lock = [NSRecursiveLock new];
+  });
+  return lock;
+}
+
+// Sets a process-wide XCTest timeout for one run of block and restores it
+// afterwards, even if the block raises. Runs block unchanged and returns NO
+// when either symbol is missing.
+static BOOL RunnerWithGlobalTimeout(RunnerTimeoutGetter getter, RunnerTimeoutSetter setter,
+                                    NSTimeInterval timeout, NS_NOESCAPE void (^block)(void)) {
+  if (getter == NULL || setter == NULL || timeout <= 0) {
+    block();
+    return NO;
+  }
+  NSRecursiveLock *lock = RunnerTimeoutLock();
+  [lock lock];
+  double previous = getter();
+  setter(timeout);
+  @try {
+    block();
+  } @finally {
+    setter(previous);
+    [lock unlock];
+  }
+  return YES;
+}
+
+typedef double (*RunnerAXTimeoutGetter)(id, SEL);
+typedef BOOL (*RunnerAXTimeoutSetter)(id, SEL, double, NSError **);
+typedef BOOL (*RunnerBoolGetter)(id, SEL);
+typedef void (*RunnerQuiescenceWait)(id, SEL, BOOL, BOOL);
+typedef void (*RunnerLegacyQuiescenceWait)(id, SEL, BOOL);
+
+// XCUIApplication -> XCUIApplicationImpl -> XCUIApplicationProcess, or nil
+// when any link is missing.
+static id RunnerApplicationProcess(XCUIApplication *app) {
+  SEL implSel = NSSelectorFromString(@"applicationImpl");
+  SEL processSel = NSSelectorFromString(@"currentProcess");
+  if (![app respondsToSelector:implSel]) {
+    return nil;
+  }
+  id impl = ((id (*)(id, SEL))objc_msgSend)(app, implSel);
+  if (![impl respondsToSelector:processSel]) {
+    return nil;
+  }
+  return ((id (*)(id, SEL))objc_msgSend)(impl, processSel);
+}
+
+// Runs XCTest's quiescence wait on process. Returns NO when neither the
+// current nor the pre-Xcode 15 selector exists.
+static BOOL RunnerRunQuiescenceWait(id process) {
+  SEL current = NSSelectorFromString(@"waitForQuiescenceIncludingAnimationsIdle:isPreEvent:");
+  SEL legacy = NSSelectorFromString(@"waitForQuiescenceIncludingAnimationsIdle:");
+  if ([process respondsToSelector:current]) {
+    // Post-event: the pre-event variant is skipped outright under the
+    // skip-pre-event interaction option, which would read as instant idle.
+    ((RunnerQuiescenceWait)objc_msgSend)(process, current, YES, NO);
+    return YES;
+  }
+  if ([process respondsToSelector:legacy]) {
+    ((RunnerLegacyQuiescenceWait)objc_msgSend)(process, legacy, YES);
+    return YES;
+  }
+  return NO;
+}
+
+@implementation RunnerXCTestTimeouts
+
++ (NSTimeInterval)defaultXPCRequestTimeout {
+  static NSTimeInterval initial = 0;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    RunnerTimeoutGetter getter = RunnerXPCGetter();
+    initial = getter != NULL ? getter() : 0;
+  });
+  return initial;
+}
+
++ (BOOL)withXPCRequestTimeout:(NSTimeInterval)timeout do:(NS_NOESCAPE void (^)(void))block {
+  // Capture XCTest's own value before the first override.
+  (void)[self defaultXPCRequestTimeout];
+  return RunnerWithGlobalTimeout(RunnerXPCGetter(), RunnerXPCSetter(), timeout, block);
+}
+
++ (RunnerQuiescence)waitForQuiescenceOfApplication:(XCUIApplication *)app
+                                           timeout:(NSTimeInterval)timeout {
+  id process = RunnerApplicationProcess(app);
+  SEL idledSel = NSSelectorFromString(@"eventLoopHasIdled");
+  SEL finishedSel = NSSelectorFromString(@"animationsHaveFinished");
+  // Without the state-timeout setter the wait would run to XCTest's own
+  // limit, far past any cap, so it is not attempted at all.
+  if (process == nil || ![process respondsToSelector:idledSel] ||
+      ![process respondsToSelector:finishedSel] || RunnerAppStateGetter() == NULL ||
+      RunnerAppStateSetter() == NULL || timeout <= 0) {
+    return RunnerQuiescenceUnavailable;
+  }
+  __block BOOL waited = NO;
+  RunnerWithGlobalTimeout(RunnerAppStateGetter(), RunnerAppStateSetter(), timeout, ^{
+    waited = RunnerRunQuiescenceWait(process);
+  });
+  if (!waited) {
+    return RunnerQuiescenceUnavailable;
+  }
+  RunnerBoolGetter get = (RunnerBoolGetter)objc_msgSend;
+  BOOL idle = get(process, idledSel) && get(process, finishedSel);
+  return idle ? RunnerQuiescenceIdle : RunnerQuiescenceBusy;
+}
+
++ (BOOL)withAXTimeout:(NSTimeInterval)timeout do:(NS_NOESCAPE void (^)(void))block {
+  id client = [self accessibilityClient];
+  SEL getSel = NSSelectorFromString(@"AXTimeout");
+  SEL setSel = NSSelectorFromString(@"_setAXTimeout:error:");
+  if (client == nil || timeout <= 0 || ![client respondsToSelector:getSel] ||
+      ![client respondsToSelector:setSel]) {
+    block();
+    return NO;
+  }
+  RunnerAXTimeoutGetter get = (RunnerAXTimeoutGetter)objc_msgSend;
+  RunnerAXTimeoutSetter set = (RunnerAXTimeoutSetter)objc_msgSend;
+  NSRecursiveLock *lock = RunnerTimeoutLock();
+  [lock lock];
+  double previous = get(client, getSel);
+  NSError *error = nil;
+  if (!set(client, setSel, timeout, &error)) {
+    NSLog(@"DL_AX_TIMEOUT: could not set %.1fs (%@); running unbounded", timeout, error);
+    [lock unlock];
+    block();
+    return NO;
+  }
+  @try {
+    block();
+  } @finally {
+    NSError *restoreError = nil;
+    if (!set(client, setSel, previous, &restoreError)) {
+      NSLog(@"DL_AX_TIMEOUT: could not restore %.1fs (%@)", previous, restoreError);
+    }
+    [lock unlock];
+  }
+  return YES;
+}
+
++ (nullable id)accessibilityClient {
+  SEL selector = NSSelectorFromString(@"accessibilityInterface");
+  XCUIDevice *device = XCUIDevice.sharedDevice;
+  if (![device respondsToSelector:selector]) {
+    return nil;
+  }
+  return ((id (*)(id, SEL))objc_msgSend)(device, selector);
+}
+
+@end

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

@@ -7,17 +7,33 @@
 // 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;
+// Bounded generous depth. INT_MAX invites runaway cost on pathological trees.
+// 100 clears the deep native wrapper nesting a React Native (Fabric / New
+// Architecture) screen produces — 60 could still clip content nested inside a
+// ScrollView, the same class of gap WebDriverAgent's default cap of 50 causes
+// (#171). Override with DEVICELAB_SNAPSHOT_MAX_DEPTH for an unusually deep app.
+static int dl_snapshotMaxDepth(void) {
+  static int depth = 0;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    depth = 100;
+    const char *env = getenv("DEVICELAB_SNAPSHOT_MAX_DEPTH");
+    if (env != NULL) {
+      int parsed = atoi(env);
+      if (parsed > 0) {
+        depth = parsed;
+      }
+    }
+  });
+  return depth;
+}
 
 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[@"maxDepth"] = @(dl_snapshotMaxDepth());
   merged[@"maxChildren"] = @(INT_MAX);
   merged[@"maxArrayCount"] = @(INT_MAX);
   // 0 == do NOT honor modal views, i.e. keep elements behind a modal/dialog in
@@ -44,6 +60,6 @@ void DLApplyCompleteSnapshotParams(void) {
     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);
+          dl_snapshotMaxDepth());
   });
 }

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

@@ -1,4 +1,5 @@
 #import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -14,4 +15,26 @@ NS_ASSUME_NONNULL_BEGIN
 // Returns YES on success. Writes a NSError into *outError on failure.
 BOOL DLSendSyntheticTyping(NSString *text, NSUInteger typingSpeed, NSError * _Nullable * _Nullable outError);
 
+// One finger, in screen points: touch down at `from`, rest there for `hold`,
+// move to `to` over `move`, rest there for `rest`, lift. This is Maestro's
+// swipe shape (hold 0, move 0.1s, rest = the swipe's duration): no stationary
+// press at the start, which a list reads as a tap on the row underneath, and
+// no element lookups or idle waits around the gesture, which XCUICoordinate
+// adds. `interfaceOrientation` is a UIInterfaceOrientation raw value.
+BOOL DLSendSyntheticTouch(CGPoint from,
+                          CGPoint to,
+                          NSTimeInterval hold,
+                          NSTimeInterval move,
+                          NSTimeInterval rest,
+                          long long interfaceOrientation,
+                          NSError * _Nullable * _Nullable outError);
+
+// `count` taps at `point`, each held for `press`, `gap` apart.
+BOOL DLSendSyntheticTaps(CGPoint point,
+                         NSUInteger count,
+                         NSTimeInterval press,
+                         NSTimeInterval gap,
+                         long long interfaceOrientation,
+                         NSError * _Nullable * _Nullable outError);
+
 NS_ASSUME_NONNULL_END

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

@@ -4,46 +4,36 @@
 #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];
+static NSError *DLSynthesisError(NSInteger code, NSString *message) {
+  return [NSError errorWithDomain:@"DevicelabIOSRunner"
+                             code:code
+                         userInfo:@{NSLocalizedDescriptionKey: message}];
+}
 
+// Sends a built event record through XCUIDevice's event synthesizer and waits
+// for it to be delivered. No element lookup and no wait for the app to go
+// idle happen here: the event goes straight to the screen, the way Maestro's
+// runner and WebDriverAgent's W3C actions send theirs.
+static BOOL DLSynthesize(XCSynthesizedEventRecord *record, NSError * _Nullable * _Nullable outError) {
   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"}];
+      *outError = DLSynthesisError(1, @"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:"}];
+      *outError = DLSynthesisError(2, @"eventSynthesizer does not support synthesizeEvent:completion:");
     }
     return NO;
   }
 
+  __block BOOL done = NO;
+  __block NSError *innerError = nil;
   NSMethodSignature *sig = [synthesizer methodSignatureForSelector:sel];
   NSInvocation *inv = [NSInvocation invocationWithMethodSignature:sig];
   inv.target = synthesizer;
@@ -63,19 +53,15 @@ BOOL DLSendSyntheticTyping(NSString *text, NSUInteger typingSpeed, NSError * _Nu
   NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:30.0];
   while (!done && [deadline timeIntervalSinceNow] > 0) {
     [[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode
-                             beforeDate:[NSDate dateWithTimeIntervalSinceNow:0.05]];
+                             beforeDate:[NSDate dateWithTimeIntervalSinceNow:0.01]];
   }
 
   if (!done) {
     if (outError) {
-      *outError = [NSError errorWithDomain:@"DevicelabIOSRunner"
-                                       code:3
-                                   userInfo:@{NSLocalizedDescriptionKey:
-                                              @"synthesizeEvent timed out"}];
+      *outError = DLSynthesisError(3, @"synthesizeEvent timed out");
     }
     return NO;
   }
-
   if (innerError != nil) {
     if (outError) {
       *outError = innerError;
@@ -84,3 +70,64 @@ BOOL DLSendSyntheticTyping(NSString *text, NSUInteger typingSpeed, NSError * _Nu
   }
   return YES;
 }
+
+static XCSynthesizedEventRecord *DLNewRecord(NSString *name, long long interfaceOrientation) {
+  XCSynthesizedEventRecord *record = [XCSynthesizedEventRecord alloc];
+  if ([record respondsToSelector:@selector(initWithName:interfaceOrientation:)]) {
+    return [record initWithName:name interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation];
+  }
+  return [record initWithName:name];
+}
+
+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];
+  return DLSynthesize(record, outError);
+}
+
+BOOL DLSendSyntheticTouch(CGPoint from,
+                          CGPoint to,
+                          NSTimeInterval hold,
+                          NSTimeInterval move,
+                          NSTimeInterval rest,
+                          long long interfaceOrientation,
+                          NSError * _Nullable * _Nullable outError) {
+  XCSynthesizedEventRecord *record = DLNewRecord(@"DLSyntheticTouch", interfaceOrientation);
+  XCPointerEventPath *path = [[XCPointerEventPath alloc] initForTouchAtPoint:from offset:0.0];
+  NSTimeInterval offset = MAX(hold, 0.0);
+  if (!CGPointEqualToPoint(from, to)) {
+    offset += MAX(move, 0.0);
+    [path moveToPoint:to atOffset:offset];
+  }
+  offset += MAX(rest, 0.0);
+  [path liftUpAtOffset:offset];
+  [record addPointerEventPath:path];
+  return DLSynthesize(record, outError);
+}
+
+BOOL DLSendSyntheticTaps(CGPoint point,
+                         NSUInteger count,
+                         NSTimeInterval press,
+                         NSTimeInterval gap,
+                         long long interfaceOrientation,
+                         NSError * _Nullable * _Nullable outError) {
+  XCSynthesizedEventRecord *record = DLNewRecord(@"DLSyntheticTaps", interfaceOrientation);
+  NSTimeInterval offset = 0.0;
+  for (NSUInteger i = 0; i < MAX(count, (NSUInteger)1); i++) {
+    XCPointerEventPath *path = [[XCPointerEventPath alloc] initForTouchAtPoint:point offset:offset];
+    [path liftUpAtOffset:offset + press];
+    [record addPointerEventPath:path];
+    offset += press + gap;
+  }
+  return DLSynthesize(record, outError);
+}

package/drivers/ios/DevicelabIOSRunner/PROTOCOL.md

@@ -84,6 +84,9 @@ Unknown fields are ignored. Missing required fields produce `INVALID_ARGUMENT`.
 | `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) |
+| `SNAPSHOT_FAILED` | No accessibility tree could be read (query failed or timed out); `data.appState` says why, usually a suspended app |
+| `NO_TARGET_APP` | A read-only command named no app and the frontmost app could not be resolved |
+| `NO_TEXT_INPUT` | A replace-mode `type` (a clear, or `eraseText`) found no text input at the coordinates, or none focused |
 | `RUNNER_INTERNAL` | Bug in the runner |
 
 ## Versioning
@@ -111,10 +114,24 @@ Unknown fields are ignored. Missing required fields produce `INVALID_ARGUMENT`.
 
 | Command | Inputs | Returns |
 |---|---|---|
-| `snapshot` | `appBundleId?` | `{ nodes: [SnapshotNode] }` |
+| `snapshot` | `appBundleId?`, `visibleOnly?` | `{ nodes: [SnapshotNode], truncated }` |
 | `screenSize` | `appBundleId?` | `{ width, height, scale }` |
+| `idle` | `appBundleId?`, `timeoutMs?` (default 1000, max 10000, `0` = do not wait) | `{ idle, waitedMs, appState, message }` |
+| `settle` | `timeoutMs?` (default 3000, max 10000) | `{ idle, waitedMs, message }` |
 
-`snapshot` always returns the full tree. If `appBundleId` is omitted, snapshots the currently foregrounded app via `XCUIApplication()`. **No filtering, no caps, no occlusion computation.**
+`visibleOnly` (local addition) returns only elements at least 10% on screen — Maestro's `filterOutOfBounds` rule — plus no element under a wholly off-screen ancestor, whose frame is clipped to the viewport. The runner still walks the whole tree; off-screen elements are skipped without being evaluated and their on-screen children attach to the nearest included ancestor. The host uses it for every lookup, and the full tree only for reports. The node budget is 3000 on-screen nodes (1500 for a full tree); `truncated` says when it was hit.
+
+`settle` (local addition) waits until two consecutive 48×104 grayscale thumbnails of the screen agree (at most 0.2% of pixels moving by more than 6 gray levels), Maestro's static-screen test done on the device. `idle` is `true` when the screen settled within the cap. It never activates the app.
+
+Every response carries `serverMs`, the runner's own time on the command; the runner also logs `DL_CMD cmd= ms= bytes= ok=` per command.
+
+`snapshot` always returns the full tree. If `appBundleId` is omitted, snapshots the frontmost app; if that cannot be resolved the call fails with `NO_TARGET_APP` rather than launching the runner's host app. **No filtering, no caps, no occlusion computation.**
+
+`idle` waits, capped by `timeoutMs`, for the app to go quiescent including animations — XCTest's `waitForQuiescenceIncludingAnimationsIdle:isPreEvent:`, bounded by setting XCTest's application-state timeout for the call (WebDriverAgent's approach). `idle` is `true` only when the app's `eventLoopHasIdled` and `animationsHaveFinished` flags are both set afterwards; it is `false` when the cap passed first, the app is not in the foreground (XCTest skips the check for it), `timeoutMs` was 0, or the private API is missing. `waitedMs` is the real time spent and can exceed the cap if XCTest spindumps an app that never idled. Like `snapshot`, it never activates the app.
+
+`snapshot` is read-only: it never activates, launches or waits for the app. A named app that is backgrounded is read as it is; one that is suspended or not running is not queried at all (`SNAPSHOT_FAILED` with its `appState`), since it cannot answer.
+
+`snapshot` data also carries `appState` (the target's `XCUIApplication.state`) and `source`: `"xctest"` for XCTest's public snapshot, `"privateAX"` when the tree came from the private accessibility fallback (the public path failed or returned only the root). When no tree can be read at all the response is `ok: false` with `SNAPSHOT_FAILED`, and `data.appState` is still set — an unreadable screen is never reported as an empty one.
 
 #### SnapshotNode
 
@@ -165,7 +182,9 @@ All gestures accept `appBundleId` so the runner can target the right `XCUIApplic
 | `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 |
+| `drag` | `x, y, x2, y2, durationMs` (press-before-move hold), `moveDurationMs?` (movement time), `restMs?` (rest at the end point before lifting — local addition) | gesture timings + path |
+
+Taps, double taps, long presses and drags with a hold of 50ms or less are sent as synthesized touch events (`XCSynthesizedEventRecord` + `XCPointerEventPath`) in screen points, with no element lookups and no idle waits: touch at `x, y`, rest `durationMs`, move to `x2, y2` over `moveDurationMs` (default 100), rest `restMs` (default 0, or 250 when a `moveDurationMs` is given), lift. The host sends Maestro's swipe shape: hold 0, move 100ms, rest = the swipe's duration. A longer hold (a dragAndDrop lift) and any gesture on a rotated screen use `XCUICoordinate`'s `press(forDuration:thenDragTo:withVelocity:thenHoldForDuration:)`, as does any gesture whose synthesis fails.
 | `pinch` | `x, y, scale, durationMs` | gesture timings |
 | `pressButton` | `button: "home"|"lock"|"volumeUp"|"volumeDown"|"appSwitcher"` | `{ pressed: true }` |
 | `rotate` | `orientation: "portrait"|"landscapeLeft"|"landscapeRight"|"portraitUpsideDown"` | `{ orientation }` |
@@ -186,6 +205,8 @@ All gestures accept `appBundleId` so the runner can target the right `XCUIApplic
 
 `type` sends keys to the currently focused element (caller is responsible for tapping to focus first — same as WDA today).
 
+`type` reports its read-back: `verified` is `true` when the field read back as typed, `false` on a mismatch (the response is then `ok: false` with `TEXT_ENTRY_MISMATCH`, and `data` still carries `verified`/`repaired`), and absent when the value could not be read (secure fields) — unchecked typing is never reported as verified. `repaired: true` means the first attempt read back wrong and the runner cleared the field and typed again.
+
 ### Alerts
 
 | Command | Inputs | Returns |
@@ -256,3 +277,5 @@ This split mirrors how the current `pkg/driver/wda/` and `pkg/driver/devicelab/`
 - **`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.
+
+`type` with `text: ""` and `textEntryMode: "replace"` clears the resolved input. An optional `deleteCount` (local extension, used by `eraseText`) deletes that many characters from the end instead; a count of at least the field's length clears the whole field through the same verified path.

package/drivers/ios/WebDriverAgent/.editorconfig

@@ -0,0 +1,11 @@
+# editorconfig.org
+root = true
+
+[*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,json,jsonc}]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120

package/drivers/ios/WebDriverAgent/.github/dependabot.yml

@@ -18,5 +18,5 @@ updates:
     day: "tuesday"
   open-pull-requests-limit: 5
   commit-message:
-    prefix: "chore"
+    prefix: "ci"
     include: "scope"