@devicelab/maestro-runner-darwin-arm64 1.1.29 → 1.1.31

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIApplication+FBTouchAction.m

@@ -9,17 +9,67 @@
 
 #import "XCUIApplication+FBTouchAction.h"
 
+#import <dlfcn.h>
+
 #import "FBBaseActionsSynthesizer.h"
 #import "FBConfiguration.h"
+#import "FBErrorBuilder.h"
 #import "FBExceptions.h"
 #import "FBLogger.h"
+#import "FBMathUtils.h"
 #import "FBRunLoopSpinner.h"
 #import "FBW3CActionsSynthesizer.h"
 #import "FBXCTestDaemonsProxy.h"
+#import "XCPointerEventPath.h"
+#import "XCSynthesizedEventRecord.h"
+#import "XCUIElement.h"
 #import "XCUIElement+FBUtilities.h"
 
 #if !TARGET_OS_TV && !TARGET_OS_WATCH
 
+/**
+ Maps a drag XCUIGestureVelocity to the speed XCTest drags at. XCTest calls the result "pixels per
+ second", but divides the distance between the two screen points (which are in points) by it.
+ Prefers XCTest's own (exported, but undeclared) mapping function, so any future change to its
+ presets is picked up; falls back to the values it returns now.
+
+ @throws FBInvalidArgumentException if the velocity is neither one of the XCUIGestureVelocity
+ presets nor a positive finite number
+ */
+static CGFloat FBPointsPerSecondForDragVelocity(XCUIGestureVelocity velocity)
+{
+  BOOL isDefault = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocityDefault, 0);
+  BOOL isSlow = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocitySlow, 0);
+  BOOL isFast = FBFloatFuzzyEqualToFloat(velocity, XCUIGestureVelocityFast, 0);
+  if (!isDefault && !isSlow && !isFast && !(isfinite(velocity) && velocity > 0)) {
+    NSString *reason = [NSString stringWithFormat:@"%@ is an invalid drag velocity. It must be greater than 0", @(velocity)];
+    @throw [NSException exceptionWithName:FBInvalidArgumentException reason:reason userInfo:nil];
+  }
+  static double (*xctestMapping)(double) = NULL;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    xctestMapping = (double (*)(double))dlsym(RTLD_DEFAULT, "XCUIPixelsPerSecondForDragGestureVelocity");
+    if (NULL == xctestMapping) {
+      [FBLogger log:@"Could not find XCUIPixelsPerSecondForDragGestureVelocity. Using built-in drag velocity presets instead"];
+    }
+  });
+  if (NULL != xctestMapping) {
+    return (CGFloat)xctestMapping(velocity);
+  }
+  if (isSlow) {
+    return 250;
+  }
+  if (isFast) {
+    return 750;
+  }
+  return isDefault ? 500 : velocity;
+}
+
+static BOOL FBIsFinitePoint(CGPoint point)
+{
+  return isfinite(point.x) && isfinite(point.y);
+}
+
 @implementation XCUIApplication (FBTouchAction)
 
 + (BOOL)handleEventSynthesWithError:(NSError *)error
@@ -65,6 +115,80 @@
   return YES;
 }
 
+- (BOOL)fb_pressAtCoordinate:(XCUICoordinate *)startCoordinate
+                 forDuration:(NSTimeInterval)pressDuration
+        thenDragToCoordinate:(XCUICoordinate *)endCoordinate
+                withVelocity:(XCUIGestureVelocity)velocity
+         thenHoldForDuration:(NSTimeInterval)holdDuration
+                       error:(NSError **)error
+{
+  CGFloat pointsPerSecond = FBPointsPerSecondForDragVelocity(velocity);
+  if (!isfinite(pressDuration) || pressDuration < 0 || !isfinite(holdDuration) || holdDuration < 0) {
+    NSString *reason = [NSString stringWithFormat:@"Drag press and hold durations must be non-negative numbers of seconds. Got %@ and %@", @(pressDuration), @(holdDuration)];
+    @throw [NSException exceptionWithName:FBInvalidArgumentException reason:reason userInfo:nil];
+  }
+
+  // Resolved once, here, so the points validated below are exactly the ones sent. XCTest's own
+  // drag re-resolves them inside its event dispatch instead, after re-snapshotting the application.
+  CGPoint startPoint = startCoordinate.screenPoint;
+  CGPoint endPoint = endCoordinate.screenPoint;
+  if (!FBIsFinitePoint(startPoint) || !FBIsFinitePoint(endPoint)) {
+    return [[[FBErrorBuilder builder]
+             withDescriptionFormat:@"Cannot resolve the on-screen position of the drag gesture (from %@ to %@). "
+             "This usually means '%@' did not deliver a valid accessibility snapshot, e.g. because it is busy "
+             "or still transitioning after an application switch. Make sure it is idle and retry",
+             NSStringFromCGPoint(startPoint), NSStringFromCGPoint(endPoint), self.bundleID]
+            buildError:error];
+  }
+
+  // Like XCTest, target the display of the element the start coordinate belongs to. displayID
+  // only reads the element's last snapshot, which resolving screenPoint above has just refreshed.
+  XCUIElement *referencedElement = startCoordinate.referencedElement;
+  long long displayID = [referencedElement respondsToSelector:@selector(displayID)]
+    ? referencedElement.displayID
+    : 0;
+  XCSynthesizedEventRecord *event = [self.class fb_pressDragEventFromPoint:startPoint
+                                                               forDuration:pressDuration
+                                                                   toPoint:endPoint
+                                                           pointsPerSecond:pointsPerSecond
+                                                       thenHoldForDuration:holdDuration
+                                                                 displayID:displayID
+                                                      interfaceOrientation:self.interfaceOrientation];
+  if (![self fb_synthesizeEvent:event error:error]) {
+    return NO;
+  }
+  [self fb_waitUntilStableWithTimeout:FBConfiguration.sharedInstance.animationCoolOffTimeout];
+  return YES;
+}
+
++ (XCSynthesizedEventRecord *)fb_pressDragEventFromPoint:(CGPoint)startPoint
+                                             forDuration:(NSTimeInterval)pressDuration
+                                                 toPoint:(CGPoint)endPoint
+                                         pointsPerSecond:(CGFloat)pointsPerSecond
+                                     thenHoldForDuration:(NSTimeInterval)holdDuration
+                                               displayID:(long long)displayID
+                                    interfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
+{
+  // Mirrors XCTest's own press-hold-drag event builder
+  XCPointerEventPath *path = [[XCPointerEventPath alloc] initForTouchAtPoint:startPoint offset:0];
+  if (pressDuration > 0) {
+    [path moveToPoint:startPoint atOffset:pressDuration];
+  }
+  CGFloat distance = (CGFloat)hypot(endPoint.x - startPoint.x, endPoint.y - startPoint.y);
+  NSTimeInterval dragEndOffset = pressDuration + distance / pointsPerSecond;
+  [path moveToPoint:endPoint atOffset:dragEndOffset];
+  [path liftUpAtOffset:dragEndOffset + holdDuration];
+
+  NSString *name = @"Press, drag and hold";
+  XCSynthesizedEventRecord *event = [XCSynthesizedEventRecord instancesRespondToSelector:@selector(initWithName:displayID:interfaceOrientation:)]
+    ? [[XCSynthesizedEventRecord alloc] initWithName:name
+                                           displayID:(unsigned long long)displayID
+                                interfaceOrientation:interfaceOrientation]
+    : [[XCSynthesizedEventRecord alloc] initWithName:name interfaceOrientation:interfaceOrientation];
+  [event addPointerEventPath:path];
+  return event;
+}
+
 - (BOOL)fb_synthesizeEvent:(XCSynthesizedEventRecord *)event error:(NSError *__autoreleasing*)error
 {
   return [FBXCTestDaemonsProxy synthesizeEventWithRecord:event error:error];

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.h

@@ -233,4 +233,10 @@ typedef NS_ENUM(NSUInteger, FBUIInterfaceAppearance) {
 
 @end
 
+/**
+ Returns the map of lowercase button names to their XCTest enum values
+ supported on the current platform (cached after the first call).
+ */
+extern NSDictionary<NSString *, NSNumber *> *FBAvailableButtonNames(void);
+
 NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBHelpers.m

@@ -13,6 +13,7 @@
 #include <notify.h>
 #import <objc/runtime.h>
 
+#import "FBHIDOperations.h"
 #import "FBErrorBuilder.h"
 #import "FBImageUtils.h"
 #import "FBMacros.h"
@@ -22,12 +23,17 @@
 #import "FBXCodeCompatibility.h"
 #import "FBXCTestDaemonsProxy.h"
 #import "XCUIDevice.h"
+#import "XCUIApplication.h"
 
 static const NSTimeInterval FBHomeButtonCoolOffTime = 1.;
 static const NSTimeInterval FBScreenLockTimeout = 5.;
 
+#if TARGET_OS_WATCH
+static NSString *const FBClockFaceBundleId = @"com.apple.clockface";
+#endif
+
 #if TARGET_OS_TV
-NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
+NSDictionary<NSString *, NSNumber *> *FBAvailableButtonNames(void) {
   static dispatch_once_t onceToken;
   static NSDictionary *result;
   dispatch_once(&onceToken, ^{
@@ -58,7 +64,7 @@ NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
   return result;
 }
 #else
-NSDictionary<NSString *, NSNumber *> *fb_availableButtonNames(void) {
+NSDictionary<NSString *, NSNumber *> *FBAvailableButtonNames(void) {
   static dispatch_once_t onceToken;
   static NSDictionary *result;
   dispatch_once(&onceToken, ^{
@@ -136,29 +142,90 @@ static bool fb_isLocked;
 
 - (BOOL)fb_goToHomescreenWithError:(NSError **)error
 {
+#if TARGET_OS_TV
+  return [self fb_goToHomescreenOnTVWithError:error];
+#elif TARGET_OS_WATCH
+  return [self fb_goToHomescreenOnWatchWithError:error];
+#else
   return [XCUIApplication fb_switchToSystemApplicationWithError:error];
+#endif
 }
 
+#if TARGET_OS_WATCH
+- (BOOL)fb_goToHomescreenOnWatchWithError:(NSError **)error
+{
+  // Carousel rejects launch/activate requests on watchOS 27.0.
+  XCUIApplication *foregroundApp = XCUIApplication.fb_activeApplication;
+  // The watch face is a separate foreground application from Carousel.
+  if ([foregroundApp.bundleID isEqualToString:FBClockFaceBundleId]
+      || [foregroundApp fb_isSameAppAs:XCUIApplication.fb_systemApplication]) {
+    return YES;
+  }
+  @try {
+    [self pressButton:XCUIDeviceButtonHome];
+  } @catch (NSException *exception) {
+    return [[[FBErrorBuilder alloc] withDescription:exception.reason] buildError:error];
+  }
+  return [[[[FBRunLoopSpinner new] timeout:5]
+           timeoutErrorMessage:@"Timed out while waiting for the home screen"]
+          spinUntilTrue:^BOOL{
+            return foregroundApp.state != XCUIApplicationStateRunningForeground;
+          } error:error];
+}
+#endif
+
+#if TARGET_OS_TV
+- (BOOL)fb_goToHomescreenOnTVWithError:(NSError **)error
+{
+  // PineBoard rejects launch/activate requests on tvOS 26.5 and 27.0.
+  XCUIApplication *foregroundApp = XCUIApplication.fb_activeApplication;
+  if ([foregroundApp fb_isSameAppAs:XCUIApplication.fb_systemApplication]) {
+    return YES;
+  }
+  @try {
+    [XCUIRemote.sharedRemote pressButton:XCUIRemoteButtonHome];
+  } @catch (NSException *exception) {
+    return [[[FBErrorBuilder alloc] withDescription:exception.reason] buildError:error];
+  }
+  return [[[[FBRunLoopSpinner new] timeout:5]
+           timeoutErrorMessage:@"Timed out while waiting for the home screen"]
+          spinUntilTrue:^BOOL{
+            return foregroundApp.state != XCUIApplicationStateRunningForeground;
+          } error:error];
+}
+#endif
+
 - (BOOL)fb_lockScreen:(NSError **)error
 {
   if (fb_isLocked) {
     return YES;
   }
-#if TARGET_OS_SIMULATOR
-  [self pressLockButton];
-#else
-  if (SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(@"27.0")) {
-    // iOS 27: pressLockButton no longer locks; use a direct IOHID Power press (0x0C/0x30, ~0.5s hold).
-    if (![self fb_performIOHIDEventWithPage:0x0C
-                                      usage:0x30
-                                   duration:0.5
-                                      error:error]) {
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  if ([FBHIDOperations appliesToDevice:self]) {
+    if (![FBHIDOperations pressLockWithError:error]) {
       return NO;
     }
-  } else {
+  } else
+#endif
+  {
+#if TARGET_OS_SIMULATOR
     [self pressLockButton];
-  }
+#else
+    if (SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(@"27.0")) {
+      // iOS 27: pressLockButton no longer locks; use a short IOHID Power press.
+      // A 0.5s hold can invoke Siri instead of locking the screen.
+      const NSTimeInterval duration = 0.2;
+      if (![self fb_performIOHIDEventWithPage:0x0C
+                                        usage:0x30
+                                     duration:duration
+                                        error:error]) {
+        return NO;
+      }
+    } else {
+      [self pressLockButton];
+    }
 #endif
+  }
   return [[[[FBRunLoopSpinner new]
             timeout:FBScreenLockTimeout]
            timeoutErrorMessage:@"Timed out while waiting until the screen gets locked"]
@@ -177,14 +244,19 @@ static bool fb_isLocked;
   if (!fb_isLocked) {
     return YES;
   }
-  [self pressButton:XCUIDeviceButtonHome];
-  [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:FBHomeButtonCoolOffTime]];
-#if !TARGET_OS_TV
-  [self pressButton:XCUIDeviceButtonHome];
-#else
-  [self pressButton:XCUIDeviceButtonHome];
+  for (NSUInteger attempt = 0; attempt < 2; attempt++) {
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+    if ([FBHIDOperations appliesToDevice:self]) {
+      if (![FBHIDOperations pressHomeWithError:error]) {
+        return NO;
+      }
+    } else
 #endif
-  [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:FBHomeButtonCoolOffTime]];
+    {
+      [self pressButton:XCUIDeviceButtonHome];
+    }
+    [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:FBHomeButtonCoolOffTime]];
+  }
   return [[[[FBRunLoopSpinner new]
             timeout:FBScreenLockTimeout]
            timeoutErrorMessage:@"Timed out while waiting until the screen gets unlocked"]
@@ -307,7 +379,7 @@ static bool fb_isLocked;
 
 - (BOOL)fb_hasButton:(NSString *)buttonName
 {
-  return fb_availableButtonNames()[buttonName.lowercaseString] != nil;
+  return FBAvailableButtonNames()[buttonName.lowercaseString] != nil;
 }
 
 - (BOOL)fb_pressButton:(NSString *)buttonName
@@ -318,7 +390,7 @@ static bool fb_isLocked;
   return [self fb_pressButton:buttonName error:error];
 #else
 
-  NSDictionary<NSString *, NSNumber *> *availableButtons = fb_availableButtonNames();
+  NSDictionary<NSString *, NSNumber *> *availableButtons = FBAvailableButtonNames();
   NSNumber *buttonValue = availableButtons[buttonName.lowercaseString];
   
   if (!buttonValue) {
@@ -342,7 +414,7 @@ static bool fb_isLocked;
 - (BOOL)fb_pressButton:(NSString *)buttonName
                  error:(NSError **)error
 {
-  NSDictionary<NSString *, NSNumber *> *availableButtons = fb_availableButtonNames();
+  NSDictionary<NSString *, NSNumber *> *availableButtons = FBAvailableButtonNames();
   NSNumber *buttonValue = availableButtons[buttonName.lowercaseString];
   
   if (!buttonValue) {
@@ -351,6 +423,11 @@ static bool fb_isLocked;
              withDescriptionFormat:@"The button '%@' is not supported. The device under test only supports the following buttons: %@", buttonName, sortedKeys]
             buildError:error];
   }
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  if (buttonValue.unsignedIntegerValue == XCUIDeviceButtonHome && [FBHIDOperations appliesToDevice:self]) {
+    return [FBHIDOperations pressHomeWithError:error];
+  }
+#endif
   [self pressButton:(XCUIDeviceButton)[buttonValue unsignedIntegerValue]];
   return YES;
 }

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBHinge.h

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <XCTest/XCTest.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface XCUIDevice (FBHinge)
+
+/** Whether a hinge and the CoreMotion angle-reading APIs are available. */
+- (BOOL)fb_supportsHingeAngleReading;
+
+/**
+ Whether a hinge and the IOKit APIs needed to attempt injection are available.
+ This does not guarantee event acceptance, particularly on physical devices.
+ */
+- (BOOL)fb_canAttemptSimulatedHingeAngleInjection;
+
+/**
+ Reads the current hinge angle in degrees, including changes made outside WDA.
+ Waits up to 5 seconds for a valid reading. Does not change the hinge angle.
+ @return The angle, or nil with an error if unavailable or reading times out.
+ */
+- (nullable NSNumber *)fb_getSimulatedHingeAngle:(NSError **)error;
+
+/**
+ Sends a simulated hinge angle in degrees (0 = closed, 180 = fully open).
+ This dispatches the event; the display transition completes asynchronously.
+ Verified on the iPhone Duo simulator; physical-device behavior is unverified.
+ Does not change currentDisplayId.
+ */
+- (BOOL)fb_setSimulatedHingeAngle:(double)angle error:(NSError **)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBHinge.m

@@ -0,0 +1,215 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "XCUIDevice+FBHinge.h"
+
+#import <dlfcn.h>
+#import <math.h>
+#import <mach/mach_time.h>
+
+#import "FBErrorBuilder.h"
+
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+static const NSTimeInterval FBHingeAngleReadingTimeout = 5.0;
+
+typedef CFDataRef (*FBIOCFSerialize)(CFTypeRef object, CFOptionFlags options);
+typedef CFTypeRef (*FBIOHIDEventCreateVendorDefinedEvent)(CFAllocatorRef allocator,
+                                                       uint64_t timestamp,
+                                                       uint32_t usagePage,
+                                                       uint32_t usage,
+                                                       uint32_t version,
+                                                       uint8_t *data,
+                                                       CFIndex length,
+                                                       uint32_t options);
+typedef CFTypeRef (*FBIOHIDEventSystemClientCreate)(CFAllocatorRef allocator);
+typedef void (*FBIOHIDEventSystemClientDispatchEvent)(CFTypeRef client, CFTypeRef event);
+
+@protocol FBAngle <NSObject>
+- (BOOL)isAngleValid;
+- (float)angleDegrees;
+@end
+
+@protocol FBAngleManager <NSObject>
++ (instancetype)new;
++ (BOOL)isAvailable;
++ (BOOL)instancesRespondToSelector:(SEL)selector;
+- (void)startAngleUpdatesToQueue:(NSOperationQueue *)queue handler:(void (^)(id<FBAngle>))handler;
+- (void)stopAngleUpdates;
+@end
+
+static Class<FBAngleManager> FBAngleManagerClass(void)
+{
+  static Class<FBAngleManager> angleManagerClass;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    // This path also loads on physical devices (verified on an iPad mini).
+    // Framework/class presence does not imply that a hinge sensor is available.
+    if (NULL != dlopen("/System/Library/Frameworks/CoreMotion.framework/CoreMotion", RTLD_LAZY)) {
+      angleManagerClass = NSClassFromString(@"CMAngleManager");
+    }
+  });
+  return angleManagerClass;
+}
+
+static BOOL FBHasAvailableHinge(void)
+{
+  Class<FBAngleManager> managerClass = FBAngleManagerClass();
+  return [managerClass respondsToSelector:@selector(isAvailable)] && [managerClass isAvailable];
+}
+
+typedef struct {
+  FBIOCFSerialize serialize;
+  FBIOHIDEventCreateVendorDefinedEvent createEvent;
+  FBIOHIDEventSystemClientCreate createClient;
+  FBIOHIDEventSystemClientDispatchEvent dispatchEvent;
+} FBHingeInjectionAPI;
+
+// Loads and caches the injection APIs; NULL means at least one is unavailable.
+// Resolving these functions does not dispatch an event or confirm its acceptance.
+static const FBHingeInjectionAPI *FBHingeInjectionFunctions(void)
+{
+  static FBHingeInjectionAPI api;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    void *handle = dlopen("/System/Library/Frameworks/IOKit.framework/IOKit", RTLD_LAZY);
+    if (NULL != handle) {
+      api.serialize = (FBIOCFSerialize)dlsym(handle, "IOCFSerialize");
+      api.createEvent = (FBIOHIDEventCreateVendorDefinedEvent)dlsym(handle, "IOHIDEventCreateVendorDefinedEvent");
+      api.createClient = (FBIOHIDEventSystemClientCreate)dlsym(handle, "IOHIDEventSystemClientCreate");
+      api.dispatchEvent = (FBIOHIDEventSystemClientDispatchEvent)dlsym(handle, "IOHIDEventSystemClientDispatchEvent");
+    }
+  });
+  return NULL != api.serialize && NULL != api.createEvent
+    && NULL != api.createClient && NULL != api.dispatchEvent ? &api : NULL;
+}
+#endif
+
+@implementation XCUIDevice (FBHinge)
+
+- (BOOL)fb_supportsHingeAngleReading
+{
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  Class<FBAngleManager> managerClass = FBAngleManagerClass();
+  return FBHasAvailableHinge()
+    && [managerClass instancesRespondToSelector:@selector(startAngleUpdatesToQueue:handler:)]
+    && [managerClass instancesRespondToSelector:@selector(stopAngleUpdates)];
+#else
+  return NO;
+#endif
+}
+
+- (BOOL)fb_canAttemptSimulatedHingeAngleInjection
+{
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  // Sensor presence and local APIs permit an attempt, not proof that the
+  // device's receiver accepts the vendor event. Physical devices are unverified.
+  return FBHasAvailableHinge() && NULL != FBHingeInjectionFunctions();
+#else
+  return NO;
+#endif
+}
+
+- (nullable NSNumber *)fb_getSimulatedHingeAngle:(NSError **)error
+{
+  if (!self.fb_supportsHingeAngleReading) {
+    [[FBErrorBuilder.builder withDescription:@"Hinge angle reading is unavailable on this device"] buildError:error];
+    return nil;
+  }
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  id<FBAngleManager> manager = [FBAngleManagerClass() new];
+  NSOperationQueue *queue = [NSOperationQueue new];
+  queue.maxConcurrentOperationCount = 1;
+  NSCondition *condition = [NSCondition new];
+  __block NSNumber *reading = nil;
+  NSNumber *result;
+  @try {
+    [manager startAngleUpdatesToQueue:queue handler:^(id<FBAngle> angle) {
+      if (![angle respondsToSelector:@selector(isAngleValid)]
+          || ![angle respondsToSelector:@selector(angleDegrees)] || !angle.isAngleValid) {
+        return;
+      }
+      float degrees = angle.angleDegrees;
+      if (!isfinite(degrees)) {
+        return;
+      }
+      [condition lock];
+      if (nil == reading) {
+        reading = @(degrees);
+        [condition signal];
+      }
+      [condition unlock];
+    }];
+    NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:FBHingeAngleReadingTimeout];
+    [condition lock];
+    while (nil == reading) {
+      if (![condition waitUntilDate:deadline]) {
+        break;
+      }
+    }
+    result = reading;
+    [condition unlock];
+  } @finally {
+    [manager stopAngleUpdates];
+  }
+  if (nil == result) {
+    [[FBErrorBuilder.builder withDescriptionFormat:@"Timed out after %g seconds waiting for a valid hinge angle",
+      FBHingeAngleReadingTimeout] buildError:error];
+  }
+  return result;
+#else
+  return nil;
+#endif
+}
+
+- (BOOL)fb_setSimulatedHingeAngle:(double)angle error:(NSError **)error
+{
+  if (!isfinite(angle) || angle < 0 || angle > 180) {
+    return [[FBErrorBuilder.builder withDescription:@"Hinge angle must be a finite number between 0 and 180 degrees"] buildError:error];
+  }
+  if (!self.fb_canAttemptSimulatedHingeAngleInjection) {
+    return [[FBErrorBuilder.builder withDescription:@"Hinge angle injection requires an available hinge and the IOKit HID APIs"] buildError:error];
+  }
+#if !TARGET_OS_TV && !TARGET_OS_WATCH
+  // WDA's fb_performIOHIDEventWithPage:usage:duration:error: uses XCDeviceEvent
+  // with page, usage, and duration only. The XCDeviceEvent interfaces checked
+  // in Xcode 27.1 provide no way to attach the vendor payload containing the
+  // hinge angle, so this command creates and dispatches an IOKit event directly.
+  const FBHingeInjectionAPI *api = FBHingeInjectionFunctions();
+  // Matches Device Hub's hinge-slider-control payload (Xcode 27.1). It is an
+  // IOCF binary serialization, not an NSPropertyListSerialization binary plist.
+  NSDictionary *payload = @{
+    @"provider": @"com.apple.Virtualization.VirtualMachines",
+    @"source": @"hinge-slider-control",
+    @"type": @"range",
+    @"value": @(angle),
+  };
+  CFDataRef data = api->serialize((__bridge CFTypeRef)payload, 1);
+  if (NULL == data) {
+    return [[FBErrorBuilder.builder withDescription:@"Cannot serialize the simulated hinge event"] buildError:error];
+  }
+  CFTypeRef event = api->createEvent(kCFAllocatorDefault, mach_absolute_time(), 0xff61, 0x5b, 0,
+                                    (uint8_t *)CFDataGetBytePtr(data), CFDataGetLength(data), 0);
+  CFRelease(data);
+  CFTypeRef client = api->createClient(kCFAllocatorDefault);
+  BOOL canDispatch = NULL != event && NULL != client;
+  if (canDispatch) {
+    api->dispatchEvent(client, event);
+  }
+  if (NULL != event) {
+    CFRelease(event);
+  }
+  if (NULL != client) {
+    CFRelease(client);
+  }
+  return canDispatch || [[FBErrorBuilder.builder withDescription:@"Cannot create the simulated hinge HID event or client"] buildError:error];
+#else
+  return NO;
+#endif
+}
+
+@end

package/drivers/ios/WebDriverAgent/WebDriverAgentLib/Categories/XCUIDevice+FBRotation.m

@@ -9,16 +9,23 @@
 #import "XCUIDevice+FBRotation.h"
 
 #import "FBConfiguration.h"
+#import "FBHIDOperations.h"
 #import "XCUIApplication.h"
 #import "XCUIApplication+FBHelpers.h"
 #import "XCUIElement+FBUtilities.h"
 
 # if !TARGET_OS_TV && !TARGET_OS_WATCH
 
+static UIInterfaceOrientation FBInterfaceOrientationFromDeviceOrientation(UIDeviceOrientation orientation);
+
 @implementation XCUIDevice (FBRotation)
 
 - (BOOL)fb_setDeviceInterfaceOrientation:(UIDeviceOrientation)orientation
 {
+  if ([FBHIDOperations appliesToDevice:self]) {
+    return [FBHIDOperations rotateToOrientation:orientation
+                          interfaceOrientation:FBInterfaceOrientationFromDeviceOrientation(orientation)];
+  }
   XCUIApplication *application = XCUIApplication.fb_activeApplication;
   [XCUIDevice sharedDevice].orientation = orientation;
   return [self waitUntilInterfaceIsAtOrientation:orientation application:application];
@@ -31,9 +38,7 @@
     return NO;
   }
   UIDeviceOrientation orientation = (UIDeviceOrientation)keysForRotationObj.firstObject.integerValue;
-  XCUIApplication *application = XCUIApplication.fb_activeApplication;
-  [XCUIDevice sharedDevice].orientation = orientation;
-  return [self waitUntilInterfaceIsAtOrientation:orientation application:application];
+  return [self fb_setDeviceInterfaceOrientation:orientation];
 }
 
 static UIInterfaceOrientation FBInterfaceOrientationFromDeviceOrientation(UIDeviceOrientation orientation)