agent-device 0.20.9 → 0.21.0

package/apple/snapshot-bridge/SnapshotBridgeRuntime.m

@@ -0,0 +1,382 @@
+/*
+ * The private Simulator AX reader is adapted from Meta Platforms, Inc. idb v1.5.2
+ * SimulatorFrameworkBridge/AccessibilityService.m and AccessibilityRuntime.m.
+ * See LICENSE.idb for the upstream notice and license.
+ */
+
+#import "SnapshotBridgeRuntime.h"
+
+#import <CoreGraphics/CoreGraphics.h>
+#import <objc/message.h>
+#import <objc/runtime.h>
+
+#import <dlfcn.h>
+#import <signal.h>
+#import <unistd.h>
+
+NSString *const kProtocolVersionKey = @"protocolVersion";
+NSString *const kSourceVersionKey = @"sourceVersion";
+NSString *const kRequestIdKey = @"requestId";
+NSString *const kSourceVersion = @"agent-device-simulator-ax-v1.5.3";
+const NSUInteger kProtocolVersion = 1;
+const uint32_t kMaximumFrameBytes = 16 * 1024 * 1024;
+const NSUInteger kMaximumDepth = 128;
+const NSUInteger kMaximumNodes = 10000;
+const NSUInteger kMaximumDurationMs = 120000;
+
+static NSString *const kAttributeElementType = @"XC_kAXXCAttributeElementType";
+static NSString *const kAttributeElementBaseType = @"XC_kAXXCAttributeElementBaseType";
+static NSString *const kAttributeLabel = @"XC_kAXXCAttributeLabel";
+static NSString *const kAttributeValue = @"XC_kAXXCAttributeValue";
+static NSString *const kAttributeIdentifier = @"XC_kAXXCAttributeIdentifier";
+static NSString *const kAttributeFrame = @"XC_kAXXCAttributeFrame";
+static NSString *const kAttributeAutomationType = @"XC_kAXXCAttributeAutomationType";
+static NSString *const kAttributeChildren = @"XC_kAXXCAttributeChildren";
+static NSString *const kSnapshotAttributes = @"UIAccessibilitySnapshotKeyAttributes";
+static NSString *const kSnapshotChildren = @"UIAccessibilitySnapshotKeyChildren";
+static NSString *const kXctAutomationSupportPath =
+    @"/Developer/Library/PrivateFrameworks/XCTAutomationSupport.framework/XCTAutomationSupport";
+static NSString *const kAxRuntimePath =
+    @"/System/Library/PrivateFrameworks/AXRuntime.framework/AXRuntime";
+static NSString *const kAccessibilityErrorKey = @"accessibility-error";
+
+typedef NSDictionary<NSString *, id> *_Nullable (*DefaultSnapshotParametersFn)(void);
+typedef NSArray<NSNumber *> *_Nullable (*AttributeNumbersForNamesFn)(NSArray<NSString *> *names);
+typedef uint32_t (*AXValueGetTypeFn)(const void *value);
+typedef Boolean (*AXValueGetValueFn)(const void *value, uint32_t type, void *out);
+typedef bool (*AutomationEnabledFn)(void);
+
+@interface XCTAccessibilityFramework : NSObject
+- (instancetype)initForRemoteAccess;
+- (nullable id)userTestingSnapshotForElement:(id)element
+                                      options:(NSDictionary<NSString *, id> *)options
+                                        error:(NSError **)error;
+@end
+
+@interface XCAccessibilityElement : NSObject
+- (nullable void *)AXUIElement;
+@end
+
+@protocol XCAccessibilityElementFactory <NSObject>
++ (nullable XCAccessibilityElement *)elementWithProcessIdentifier:(pid_t)pid;
+@end
+
+@protocol AXForegroundElement <NSObject>
++ (nullable id<AXForegroundElement>)primaryApp;
+- (pid_t)pid;
+@end
+
+static NSNumber *finiteNumber(double value)
+{
+  return isfinite(value) ? @(value) : nil;
+}
+
+static NSDictionary *_Nullable rectDictionary(CGRect rect)
+{
+  NSNumber *x = finiteNumber(rect.origin.x);
+  NSNumber *y = finiteNumber(rect.origin.y);
+  NSNumber *width = finiteNumber(rect.size.width);
+  NSNumber *height = finiteNumber(rect.size.height);
+  if (!x || !y || !width || !height) {
+    return nil;
+  }
+  return @{ @"X" : x, @"Y" : y, @"Width" : width, @"Height" : height };
+}
+
+@interface SnapshotWatchdogState : NSObject
+@property(atomic) BOOL completed;
+@end
+
+@implementation SnapshotWatchdogState
+@end
+
+static dispatch_source_t startRequestWatchdog(NSUInteger durationMs, SnapshotWatchdogState *state)
+{
+  dispatch_source_t watchdog = dispatch_source_create(
+      DISPATCH_SOURCE_TYPE_TIMER,
+      0,
+      0,
+      dispatch_get_global_queue(QOS_CLASS_UTILITY, 0));
+  dispatch_source_set_timer(
+      watchdog,
+      dispatch_time(DISPATCH_TIME_NOW, (uint64_t)durationMs * NSEC_PER_MSEC),
+      DISPATCH_TIME_FOREVER,
+      0);
+  dispatch_source_set_event_handler(watchdog, ^{
+    if (!state.completed) kill(getpid(), SIGKILL);
+  });
+  dispatch_resume(watchdog);
+  return watchdog;
+}
+
+static void finishRequestWatchdog(dispatch_source_t watchdog, SnapshotWatchdogState *state)
+{
+  state.completed = YES;
+  dispatch_source_cancel(watchdog);
+}
+
+@implementation BridgeRuntime {
+  XCTAccessibilityFramework *_framework;
+  Class<XCAccessibilityElementFactory> _elementClass;
+  DefaultSnapshotParametersFn _defaultSnapshotParameters;
+  AttributeNumbersForNamesFn _attributeNumbersForNames;
+  AXValueGetTypeFn _valueGetType;
+  AXValueGetValueFn _valueGetValue;
+  AutomationEnabledFn _automationEnabled;
+}
+
+- (nullable instancetype)initWithError:(NSString *_Nullable *_Nullable)error
+{
+  self = [super init];
+  if (!self) return nil;
+
+  dlopen(kAxRuntimePath.UTF8String, RTLD_NOW);
+  dlopen(kXctAutomationSupportPath.UTF8String, RTLD_NOW);
+
+  Class frameworkClass = objc_lookUpClass("XCTAccessibilityFramework");
+  _elementClass = (Class<XCAccessibilityElementFactory>)objc_lookUpClass("XCAccessibilityElement");
+  if (!frameworkClass || !_elementClass) {
+    if (error) *error = @"XCTAutomationSupport accessibility classes are unavailable";
+    return nil;
+  }
+
+  _framework = [(XCTAccessibilityFramework *)[frameworkClass alloc] initForRemoteAccess];
+  if (!_framework || ![_framework respondsToSelector:@selector(userTestingSnapshotForElement:options:error:)]) {
+    if (error) *error = @"XCTAccessibilityFramework snapshot API is unavailable";
+    return nil;
+  }
+
+  _defaultSnapshotParameters = (DefaultSnapshotParametersFn)dlsym(RTLD_DEFAULT, "XCTDefaultSnapshotParameters");
+  _attributeNumbersForNames = (AttributeNumbersForNamesFn)dlsym(
+      RTLD_DEFAULT, "XCAXAccessibilityAttributesForStringAttributes");
+  _valueGetType = (AXValueGetTypeFn)dlsym(RTLD_DEFAULT, "AXValueGetType");
+  _valueGetValue = (AXValueGetValueFn)dlsym(RTLD_DEFAULT, "AXValueGetValue");
+  _automationEnabled = (AutomationEnabledFn)dlsym(RTLD_DEFAULT, "_AXSAutomationEnabled");
+  if (!_defaultSnapshotParameters || !_attributeNumbersForNames || !_valueGetType || !_valueGetValue) {
+    if (error) *error = @"AX snapshot conversion functions are unavailable";
+    return nil;
+  }
+  return self;
+}
+
+- (BOOL)assertAutomationMode:(BOOL)wanted
+{
+  Class settingsClass = NSClassFromString(@"AXSettings");
+  SEL sharedInstance = NSSelectorFromString(@"sharedInstance");
+  SEL setter = NSSelectorFromString(@"setAutomationEnabled:");
+  if (settingsClass && [settingsClass respondsToSelector:sharedInstance]) {
+    id settings = ((id (*)(id, SEL))objc_msgSend)(settingsClass, sharedInstance);
+    if ([settings respondsToSelector:setter]) {
+      ((void (*)(id, SEL, BOOL))objc_msgSend)(settings, setter, wanted);
+    }
+  }
+  return _automationEnabled != NULL && _automationEnabled();
+}
+
+- (BOOL)isPrimaryForegroundProcess:(pid_t)pid
+{
+  Class<AXForegroundElement> elementClass = (Class<AXForegroundElement>)objc_lookUpClass("AXElement");
+  if (![elementClass respondsToSelector:@selector(primaryApp)]) return NO;
+  id<AXForegroundElement> application = [elementClass primaryApp];
+  return [application respondsToSelector:@selector(pid)] && [application pid] == pid;
+}
+
+- (nullable id)jsonValue:(id)value name:(NSString *)name
+{
+  if (!value || value == [NSNull null]) return nil;
+  if ([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class]) return value;
+
+  const void *raw = (__bridge const void *)value;
+  if (_valueGetType(raw) == 3) {
+    CGRect rect = CGRectZero;
+    if (_valueGetValue(raw, 3, &rect)) return rectDictionary(rect);
+  }
+  if ([name isEqualToString:kAttributeFrame]) return nil;
+  return nil;
+}
+
+- (nullable NSDictionary *)nodeFromSnapshot:(id)snapshot
+                              namesByNumber:(NSDictionary<NSNumber *, NSString *> *)namesByNumber
+                                      depth:(NSUInteger)depth
+                                   maxDepth:(NSUInteger)maxDepth
+                                   maxNodes:(NSUInteger)maxNodes
+                                      count:(NSUInteger *)count
+                                  truncated:(BOOL *)truncated
+                                  malformed:(BOOL *)malformed
+{
+  if (![snapshot isKindOfClass:NSDictionary.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  if (*count >= maxNodes) {
+    *truncated = YES;
+    return nil;
+  }
+  (*count)++;
+
+  NSDictionary *attributes = ((NSDictionary *)snapshot)[kSnapshotAttributes];
+  if (![attributes isKindOfClass:NSDictionary.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  NSMutableDictionary *node = [NSMutableDictionary dictionary];
+  for (NSNumber *number in attributes) {
+    NSString *name = namesByNumber[number];
+    if (!name || [name isEqualToString:kAttributeChildren]) continue;
+    id safe = [self jsonValue:attributes[number] name:name];
+    if (safe) node[name] = safe;
+  }
+
+  NSArray *children = ((NSDictionary *)snapshot)[kSnapshotChildren];
+  if (![children isKindOfClass:NSArray.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  NSMutableArray *builtChildren = [NSMutableArray array];
+  if (depth >= maxDepth) {
+    if (children.count > 0) *truncated = YES;
+  } else {
+    for (id child in children) {
+      NSDictionary *built = [self nodeFromSnapshot:child
+                                     namesByNumber:namesByNumber
+                                             depth:depth + 1
+                                          maxDepth:maxDepth
+                                             maxNodes:maxNodes
+                                             count:count
+                                         truncated:truncated
+                                         malformed:malformed];
+      if (built) [builtChildren addObject:built];
+      if (*malformed) return nil;
+      if (*truncated) break;
+      if (*count >= maxNodes) {
+        if (builtChildren.count < children.count) *truncated = YES;
+        break;
+      }
+    }
+  }
+  node[kAttributeChildren] = builtChildren;
+  return node;
+}
+
+- (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
+                                    maxDepth:(NSUInteger)maxDepth
+                                    maxNodes:(NSUInteger)maxNodes
+                                  requestId:(NSString *)requestId
+                                generation:(NSString *)generation
+                              maxDurationMs:(NSUInteger)maxDurationMs
+                                      error:(NSDictionary *_Nullable *_Nonnull)error
+{
+  SnapshotWatchdogState *watchdogState = [SnapshotWatchdogState new];
+  dispatch_source_t watchdog = startRequestWatchdog(maxDurationMs, watchdogState);
+  XCAccessibilityElement *root = [_elementClass elementWithProcessIdentifier:pid];
+  if (!root) {
+    if (error) *error = failureResponse(requestId, @"application_unavailable", @"application-element-missing", @"application element is unavailable");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  void *raw = [root AXUIElement];
+  if (!raw) {
+    if (error) *error = failureResponse(requestId, @"application_unavailable", @"application-element-missing", @"application element is unavailable");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+
+  NSArray<NSString *> *names = @[
+    kAttributeElementType,
+    kAttributeElementBaseType,
+    kAttributeLabel,
+    kAttributeValue,
+    kAttributeIdentifier,
+    kAttributeFrame,
+    kAttributeAutomationType,
+    kAttributeChildren,
+  ];
+  NSArray<NSNumber *> *numbers = _attributeNumbersForNames(names);
+  if (![numbers isKindOfClass:NSArray.class] || numbers.count != names.count) {
+    if (error) *error = failureResponse(requestId, @"reader_unavailable", @"attribute-vocabulary-mismatch", @"AX attribute vocabulary is incompatible");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  NSMutableDictionary<NSNumber *, NSString *> *namesByNumber = [NSMutableDictionary dictionary];
+  [numbers enumerateObjectsUsingBlock:^(NSNumber *number, NSUInteger index, BOOL *stop) {
+    (void)stop;
+    if ([number isKindOfClass:NSNumber.class]) namesByNumber[number] = names[index];
+  }];
+  NSMutableDictionary *options = [_defaultSnapshotParameters() mutableCopy];
+  if (!options) options = [NSMutableDictionary dictionary];
+  options[@"attributes"] = numbers;
+  options[@"maxDepth"] = @(maxDepth);
+  options[@"maxChildren"] = @(maxNodes);
+  options[@"maxArrayCount"] = @(maxNodes);
+  BOOL automationEnabled = [self assertAutomationMode:YES];
+  NSError *runtimeError = nil;
+  id snapshot = nil;
+  @try {
+    if (![self isPrimaryForegroundProcess:pid]) {
+      if (error) *error = failureResponse(requestId, @"unsupported", @"foreground-owner-unverified", @"target app is not the primary foreground accessibility owner");
+      finishRequestWatchdog(watchdog, watchdogState);
+      return nil;
+    }
+    snapshot = [_framework userTestingSnapshotForElement:(__bridge id)raw options:options error:&runtimeError];
+    if (![self isPrimaryForegroundProcess:pid]) {
+      if (error) *error = failureResponse(requestId, @"unsupported", @"foreground-owner-changed", @"foreground accessibility ownership changed during acquisition");
+      finishRequestWatchdog(watchdog, watchdogState);
+      return nil;
+    }
+  } @catch (NSException *exception) {
+    if (error) *error = failureResponse(requestId, @"reader_unavailable", @"private-api-exception", exception.reason ?: @"AX snapshot raised an exception");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  if (!snapshot) {
+    NSNumber *axError = runtimeError.userInfo[kAccessibilityErrorKey];
+    NSInteger code = [axError respondsToSelector:@selector(integerValue)] ? axError.integerValue : runtimeError.code;
+    NSString *kind = code == -25216 ? @"application_not_responding" : @"application_unavailable";
+    NSString *message = runtimeError.localizedDescription ?: @"AX snapshot returned no tree";
+    if (error) *error = failureResponse(requestId, kind, code == -25216 ? @"application-timeout" : @"application-server-unavailable", message);
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  BOOL truncated = NO;
+  BOOL malformed = NO;
+  NSUInteger count = 0;
+  NSDictionary *tree = [self nodeFromSnapshot:snapshot
+                                namesByNumber:namesByNumber
+                                        depth:0
+                                     maxDepth:maxDepth
+                                        maxNodes:maxNodes
+                                        count:&count
+                                    truncated:&truncated
+                                    malformed:&malformed];
+  if (!tree) {
+    if (error) *error = failureResponse(requestId, @"malformed_tree", malformed ? @"snapshot-tree-malformed" : @"snapshot-root-invalid", malformed ? @"AX snapshot contained a malformed node" : @"AX snapshot did not contain a materialized root node");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  finishRequestWatchdog(watchdog, watchdogState);
+  return @{
+    kProtocolVersionKey : @(kProtocolVersion),
+    kSourceVersionKey : kSourceVersion,
+    kRequestIdKey : requestId ?: @"",
+    @"generation" : generation ?: @"",
+    @"ok" : @YES,
+    @"pid" : @(pid),
+    @"tree" : tree,
+    @"truncated" : @(truncated),
+    @"automationEnabled" : @(automationEnabled),
+  };
+}
+@end
+BridgeRuntime *sharedRuntime(NSString **error)
+{
+  static BridgeRuntime *runtime;
+  static dispatch_once_t once;
+  static NSString *setupError;
+  dispatch_once(&once, ^{
+    NSString *localError = nil;
+    runtime = [[BridgeRuntime alloc] initWithError:&localError];
+    setupError = [localError copy];
+  });
+  if (!runtime && error) *error = setupError ?: @"AX bridge runtime is unavailable";
+  return runtime;
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m

@@ -58,10 +58,62 @@ int main(int argc, const char *argv[]) {
 #import <UIKit/UIKit.h>
 
 @interface AgentDeviceRunnerViewController : UIViewController
+@property(nonatomic, strong) UILabel *alertActionStatus;
+@property(nonatomic, assign) NSUInteger firstAlertActions;
+@property(nonatomic, assign) NSUInteger replacementAlertActions;
+@property(nonatomic, assign) BOOL alertFixtureStarted;
 @end
 
 @implementation AgentDeviceRunnerViewController
 
+#if TARGET_OS_IOS
+- (void)updateAlertActionStatus {
+  self.alertActionStatus.text = [NSString stringWithFormat:@"First actions: %lu; replacement actions: %lu",
+                                                         (unsigned long)self.firstAlertActions,
+                                                         (unsigned long)self.replacementAlertActions];
+}
+
+- (void)presentAlertFixtureReplacement:(BOOL)replacement {
+  NSArray<NSString *> *arguments = NSProcessInfo.processInfo.arguments;
+  BOOL sameTitle = [arguments containsObject:@"--agent-device-alert-same-title"];
+  BOOL sameBody = [arguments containsObject:@"--agent-device-alert-same-body"];
+  NSString *title = replacement && !sameTitle ? @"Next confirmation" : @"First confirmation";
+  NSString *body = replacement && !sameBody ? @"Second request" : @"First request";
+  UIAlertController *alert = [UIAlertController alertControllerWithTitle:title
+                                                               message:body
+                                                        preferredStyle:UIAlertControllerStyleAlert];
+  __weak UIAlertController *weakAlert = alert;
+  for (NSString *buttonTitle in @[@"Cancel", @"OK"]) {
+    UIAlertActionStyle style = [buttonTitle isEqualToString:@"Cancel"]
+        ? UIAlertActionStyleCancel : UIAlertActionStyleDefault;
+    [alert addAction:[UIAlertAction actionWithTitle:buttonTitle style:style handler:^(UIAlertAction *action) {
+      (void)action;
+      if (replacement) {
+        self.replacementAlertActions += 1;
+      } else {
+        self.firstAlertActions += 1;
+      }
+      [self updateAlertActionStatus];
+      if (!replacement) {
+        [weakAlert dismissViewControllerAnimated:NO completion:^{
+          [self presentAlertFixtureReplacement:YES];
+        }];
+      }
+    }]];
+  }
+  [self presentViewController:alert animated:NO completion:nil];
+}
+
+- (void)viewDidAppear:(BOOL)animated {
+  [super viewDidAppear:animated];
+  if (!self.alertFixtureStarted &&
+      [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-replacement-regression"]) {
+    self.alertFixtureStarted = YES;
+    [self presentAlertFixtureReplacement:NO];
+  }
+}
+#endif
+
 - (void)agentDeviceTextEntryDidChange:(UITextField *)textField {
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-disappear-after-input"] &&
       textField.text.length > 0) {
@@ -88,6 +140,12 @@ int main(int argc, const char *argv[]) {
 
   // Keep the fixture behind a launch argument so normal runner snapshots remain unchanged.
 #if TARGET_OS_IOS
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-replacement-regression"]) {
+    self.alertActionStatus = label;
+    label.accessibilityIdentifier = @"agent-device-alert-actions";
+    [self updateAlertActionStatus];
+  }
+
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-regression"]) {
     UITextField *textField = [[UITextField alloc] init];
     textField.accessibilityIdentifier = @"agent-device-hardware-keyboard-input";

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj

@@ -113,6 +113,7 @@
 			);
 			name = AgentDeviceRunnerUITests;
 			packageProductDependencies = (
+				A1B2C3D4E5F60718293A4B5D /* AgentDeviceSnapshotPresentation */,
 			);
 			productName = AgentDeviceRunnerUITests;
 			productReference = 20EA2EDD2F2CFC7C001CF0EF /* AgentDeviceRunnerUITests.xctest */;
@@ -146,6 +147,9 @@
 			);
 			mainGroup = 20EA2EBD2F2CFC7B001CF0EF;
 			minimizedProjectReferenceProxies = 1;
+			packageReferences = (
+				A1B2C3D4E5F60718293A4B5C /* XCLocalSwiftPackageReference "snapshot-presentation" */,
+			);
 			preferredProjectObjectVersion = 77;
 			productRefGroup = 20EA2EC72F2CFC7B001CF0EF /* Products */;
 			projectDirPath = "";
@@ -157,6 +161,21 @@
 		};
 /* End PBXProject section */
 
+/* Begin XCLocalSwiftPackageReference section */
+		A1B2C3D4E5F60718293A4B5C /* XCLocalSwiftPackageReference "snapshot-presentation" */ = {
+			isa = XCLocalSwiftPackageReference;
+			relativePath = ../../snapshot-presentation;
+		};
+/* End XCLocalSwiftPackageReference section */
+
+/* Begin XCSwiftPackageProductDependency section */
+		A1B2C3D4E5F60718293A4B5D /* AgentDeviceSnapshotPresentation */ = {
+			isa = XCSwiftPackageProductDependency;
+			package = A1B2C3D4E5F60718293A4B5C /* XCLocalSwiftPackageReference "snapshot-presentation" */;
+			productName = AgentDeviceSnapshotPresentation;
+		};
+/* End XCSwiftPackageProductDependency section */
+
 /* Begin PBXResourcesBuildPhase section */
 		20EA2EC42F2CFC7B001CF0EF /* Resources */ = {
 			isa = PBXResourcesBuildPhase;

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAlertVerification.swift

@@ -0,0 +1,36 @@
+struct RunnerAlertPresentation: Equatable {
+  let title: String
+  let content: [String]
+  let buttons: [String]
+}
+
+enum RunnerAlertObservation {
+  case visible(RunnerAlertPresentation)
+  case absent
+  case unavailable
+  case deadlineExceeded
+}
+
+enum RunnerAlertVerification: Equatable {
+  case disappeared
+  case presentationChanged
+  case stillVisible
+  case unconfirmed
+  case timedOut
+
+  static func verify(
+    original: RunnerAlertPresentation,
+    observation: RunnerAlertObservation
+  ) -> RunnerAlertVerification {
+    switch observation {
+    case .visible(let current):
+      return original == current ? .stillVisible : .presentationChanged
+    case .absent:
+      return .disappeared
+    case .unavailable:
+      return .unconfirmed
+    case .deadlineExceeded:
+      return .timedOut
+    }
+  }
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerStringNormalization.swift

@@ -0,0 +1,8 @@
+import Foundation
+
+extension String {
+  var trimmedNonEmpty: String? {
+    let trimmed = trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+  }
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSynthesizedGesture.h

@@ -2,6 +2,10 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+FOUNDATION_EXPORT NSInteger RunnerContinuousDragFrameCount(double durationMs);
+FOUNDATION_EXPORT NSInteger RunnerControlledScrollFrameCount(double durationMs);
+FOUNDATION_EXPORT double RunnerControlledScrollProgress(double t);
+
 @interface RunnerSynthesizedGesture : NSObject
 
 + (NSString * _Nullable)synthesizeSwipeWithApplication:(id)application
@@ -15,9 +19,16 @@ NS_ASSUME_NONNULL_BEGIN
                                                              x:(double)x
                                                              y:(double)y
                                                             x2:(double)x2
-                                                            y2:(double)y2
+                                                             y2:(double)y2
                                                      durationMs:(double)durationMs;
 
++ (NSString * _Nullable)synthesizeControlledScrollWithApplication:(id)application
+                                                                x:(double)x
+                                                                y:(double)y
+                                                               x2:(double)x2
+                                                                y2:(double)y2
+                                                        durationMs:(double)durationMs;
+
 + (NSString * _Nullable)synthesizeTapWithApplication:(id)application
                                                    x:(double)x
                                                    y:(double)y;