appium-webdriveragent 16.13.5 → 16.14.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [16.14.0](https://github.com/appium/WebDriverAgent/compare/v16.13.6...v16.14.0) (2026-10-04)
+
+### Features
+
+* support Duo hinge control and secondary display capture ([#1287](https://github.com/appium/WebDriverAgent/issues/1287)) ([76d6aa0](https://github.com/appium/WebDriverAgent/commit/76d6aa03e2423290bb05c436afc153bd32878ce0))
+
+## [16.13.6](https://github.com/appium/WebDriverAgent/compare/v16.13.5...v16.13.6) (2026-09-30)
+
+### Bug Fixes
+
+* restore stability wait settings when quiescence throws ([#1281](https://github.com/appium/WebDriverAgent/issues/1281)) ([bcc434c](https://github.com/appium/WebDriverAgent/commit/bcc434c08127c370c0cb05ce1dc9f4cea9f98559))
+
 ## [16.13.5](https://github.com/appium/WebDriverAgent/compare/v16.13.4...v16.13.5) (2026-09-30)
 
 ### Performance Improvements

package/README.md

@@ -26,6 +26,14 @@ and start sending [requests](https://github.com/facebook/WebDriverAgent/wiki/Que
 
 More about how to start WebDriverAgent [here](https://github.com/facebook/WebDriverAgent/wiki/Starting-WebDriverAgent).
 
+## Multiple displays
+
+See [Multiple displays](docs/multiple-displays.md) for display selection, capture,
+and active-app detection.
+
+See [Hinge angle](docs/hinge-angle.md) for reading angles, sending simulated hinge
+events, runtime requirements, and physical-device testing feedback.
+
 ## Known Issues
 If you are having some issues please checkout [wiki](https://github.com/facebook/WebDriverAgent/wiki/Common-Issues) first.
 

package/WebDriverAgent.xcodeproj/project.pbxproj

@@ -245,6 +245,7 @@
 		57C72DA18039FED310967F8F /* XCTSourceCodeLocation.h in Headers */ = {isa = PBXBuildFile; fileRef = 81BB54ECBFB5B7B680BB5D4F /* XCTSourceCodeLocation.h */; };
 		57EAF450031647694B6491F8 /* FBConfiguration.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9B76A21CF7A43900275851 /* FBConfiguration.m */; };
 		583AD004FF71CAA305E6DEAF /* XCUIDevice+FBHelpers.m in Sources */ = {isa = PBXBuildFile; fileRef = AD6C26971CF2481700F8B5FF /* XCUIDevice+FBHelpers.m */; };
+		0460879AD6034130AE0A3DEC /* XCUIDevice+FBHinge.m in Sources */ = {isa = PBXBuildFile; fileRef = 8C8E6FD103A84C908F5746EA /* XCUIDevice+FBHinge.m */; };
 		587AA46196BC2C46555C8E44 /* XCUIButtonConsole.h in Headers */ = {isa = PBXBuildFile; fileRef = 1E09842154A44874C4E9CA01 /* XCUIButtonConsole.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		588F51093FD2A5597366C282 /* XCUIElementEventTarget-Protocol.h in Headers */ = {isa = PBXBuildFile; fileRef = 0DC62BF635704E9C72AF533E /* XCUIElementEventTarget-Protocol.h */; };
 		5967912A40E807CDBE87E4B2 /* XCTReportingSessionIssueReporter-Protocol.h in Headers */ = {isa = PBXBuildFile; fileRef = 525D62A58488A52AA1BFE94A /* XCTReportingSessionIssueReporter-Protocol.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -327,6 +328,7 @@
 		641EE60A2240C5CA00173FCB /* FBLogger.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9B76A41CF7A43900275851 /* FBLogger.m */; };
 		641EE60B2240C5CA00173FCB /* FBCustomCommands.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9AB7531CAEDF0C008C271F /* FBCustomCommands.m */; };
 		641EE60C2240C5CA00173FCB /* XCUIDevice+FBHelpers.m in Sources */ = {isa = PBXBuildFile; fileRef = AD6C26971CF2481700F8B5FF /* XCUIDevice+FBHelpers.m */; };
+		181F0DBB6D28418680D52128 /* XCUIDevice+FBHinge.m in Sources */ = {isa = PBXBuildFile; fileRef = 8C8E6FD103A84C908F5746EA /* XCUIDevice+FBHinge.m */; };
 		641EE60D2240C5CA00173FCB /* XCTestPrivateSymbols.m in Sources */ = {isa = PBXBuildFile; fileRef = EE6B64FC1D0F86EF00E85F5D /* XCTestPrivateSymbols.m */; };
 		641EE60E2240C5CA00173FCB /* XCUIElement+FBTyping.m in Sources */ = {isa = PBXBuildFile; fileRef = AD76723C1D6B7CC000610457 /* XCUIElement+FBTyping.m */; };
 		641EE60F2240C5CA00173FCB /* XCUIElement+FBAccessibility.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9AB7461CAEDF0C008C271F /* XCUIElement+FBAccessibility.m */; };
@@ -433,6 +435,7 @@
 		641EE6BF2240C5CA00173FCB /* FBKeyboard.h in Headers */ = {isa = PBXBuildFile; fileRef = EE3A18641CDE734B00DE4205 /* FBKeyboard.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		641EE6C02240C5CA00173FCB /* XCUIApplication+FBHelpers.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C269A1CF2494200F8B5FF /* XCUIApplication+FBHelpers.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		641EE6C22240C5CA00173FCB /* XCUIDevice+FBHelpers.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C26961CF2481700F8B5FF /* XCUIDevice+FBHelpers.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		95EF6989BCBE4C548C26B140 /* XCUIDevice+FBHinge.h in Headers */ = {isa = PBXBuildFile; fileRef = E7536267DE094076A4EEE1D7 /* XCUIDevice+FBHinge.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		641EE6C32240C5CA00173FCB /* FBClassChainQueryParser.h in Headers */ = {isa = PBXBuildFile; fileRef = 71A7EAF71E224648001DA4F2 /* FBClassChainQueryParser.h */; };
 		641EE6C42240C5CA00173FCB /* FBMacros.h in Headers */ = {isa = PBXBuildFile; fileRef = EE9B76A51CF7A43900275851 /* FBMacros.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		641EE6C52240C5CA00173FCB /* XCTestExpectationDelegate-Protocol.h in Headers */ = {isa = PBXBuildFile; fileRef = EE35ACD91E3B77D600A02D78 /* XCTestExpectationDelegate-Protocol.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -887,7 +890,9 @@
 		AD6C26941CF2379700F8B5FF /* FBAlert.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C26921CF2379700F8B5FF /* FBAlert.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		AD6C26951CF2379700F8B5FF /* FBAlert.m in Sources */ = {isa = PBXBuildFile; fileRef = AD6C26931CF2379700F8B5FF /* FBAlert.m */; };
 		AD6C26981CF2481700F8B5FF /* XCUIDevice+FBHelpers.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C26961CF2481700F8B5FF /* XCUIDevice+FBHelpers.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		210AB789D14D40308B764DD0 /* XCUIDevice+FBHinge.h in Headers */ = {isa = PBXBuildFile; fileRef = E7536267DE094076A4EEE1D7 /* XCUIDevice+FBHinge.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		AD6C26991CF2481700F8B5FF /* XCUIDevice+FBHelpers.m in Sources */ = {isa = PBXBuildFile; fileRef = AD6C26971CF2481700F8B5FF /* XCUIDevice+FBHelpers.m */; };
+		25C9BDFC65564D78A70231B4 /* XCUIDevice+FBHinge.m in Sources */ = {isa = PBXBuildFile; fileRef = 8C8E6FD103A84C908F5746EA /* XCUIDevice+FBHinge.m */; };
 		AD6C269C1CF2494200F8B5FF /* XCUIApplication+FBHelpers.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C269A1CF2494200F8B5FF /* XCUIApplication+FBHelpers.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		AD6C269D1CF2494200F8B5FF /* XCUIApplication+FBHelpers.m in Sources */ = {isa = PBXBuildFile; fileRef = AD6C269B1CF2494200F8B5FF /* XCUIApplication+FBHelpers.m */; };
 		AD764F10E2F00090AEB802F2 /* XCUIElement+FBIsVisible.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9AB7481CAEDF0C008C271F /* XCUIElement+FBIsVisible.m */; };
@@ -987,6 +992,7 @@
 		D1172A7F53F89B78D8324A13 /* RouteRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = 374BB11AE4E4243BCA444CF8 /* RouteRequest.m */; };
 		D1212325FDE77754EE503755 /* FBRouteRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = EE9AB7881CAEDF0C008C271F /* FBRouteRequest.m */; };
 		D142183578036F5FD5B9880B /* XCUIDevice+FBHelpers.h in Headers */ = {isa = PBXBuildFile; fileRef = AD6C26961CF2481700F8B5FF /* XCUIDevice+FBHelpers.h */; };
+		2E71304F39B64EDC98EE3974 /* XCUIDevice+FBHinge.h in Headers */ = {isa = PBXBuildFile; fileRef = E7536267DE094076A4EEE1D7 /* XCUIDevice+FBHinge.h */; };
 		D14718959F7D46949859EEE6 /* FBDebugLogDelegateDecorator.m in Sources */ = {isa = PBXBuildFile; fileRef = EE7E27191D06C69F001BEC7B /* FBDebugLogDelegateDecorator.m */; };
 		D1DE06DF54156F744E364B5F /* FBDebugLogDelegateDecorator.h in Headers */ = {isa = PBXBuildFile; fileRef = EE7E27181D06C69F001BEC7B /* FBDebugLogDelegateDecorator.h */; };
 		D203F622C7C0D968F3BD2AAF /* XCUIPlatformApplicationServicesProviding-Protocol.h in Headers */ = {isa = PBXBuildFile; fileRef = 3BA71BCF1FDA482419CA8596 /* XCUIPlatformApplicationServicesProviding-Protocol.h */; };
@@ -1760,7 +1766,9 @@
 		AD6C26921CF2379700F8B5FF /* FBAlert.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = FBAlert.h; path = WebDriverAgentLib/FBAlert.h; sourceTree = SOURCE_ROOT; };
 		AD6C26931CF2379700F8B5FF /* FBAlert.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; lineEnding = 0; name = FBAlert.m; path = WebDriverAgentLib/FBAlert.m; sourceTree = SOURCE_ROOT; xcLanguageSpecificationIdentifier = xcode.lang.objc; };
 		AD6C26961CF2481700F8B5FF /* XCUIDevice+FBHelpers.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "XCUIDevice+FBHelpers.h"; sourceTree = "<group>"; };
+		E7536267DE094076A4EEE1D7 /* XCUIDevice+FBHinge.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "XCUIDevice+FBHinge.h"; sourceTree = "<group>"; };
 		AD6C26971CF2481700F8B5FF /* XCUIDevice+FBHelpers.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "XCUIDevice+FBHelpers.m"; sourceTree = "<group>"; };
+		8C8E6FD103A84C908F5746EA /* XCUIDevice+FBHinge.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "XCUIDevice+FBHinge.m"; sourceTree = "<group>"; };
 		AD6C269A1CF2494200F8B5FF /* XCUIApplication+FBHelpers.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "XCUIApplication+FBHelpers.h"; sourceTree = "<group>"; };
 		AD6C269B1CF2494200F8B5FF /* XCUIApplication+FBHelpers.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "XCUIApplication+FBHelpers.m"; sourceTree = "<group>"; };
 		AD76723B1D6B7CC000610457 /* XCUIElement+FBTyping.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "XCUIElement+FBTyping.h"; sourceTree = "<group>"; };
@@ -2415,7 +2423,9 @@
 				EEDFE11F1D9C06F800E6FFE5 /* XCUIDevice+FBHealthCheck.h */,
 				EEDFE1201D9C06F800E6FFE5 /* XCUIDevice+FBHealthCheck.m */,
 				AD6C26961CF2481700F8B5FF /* XCUIDevice+FBHelpers.h */,
+				E7536267DE094076A4EEE1D7 /* XCUIDevice+FBHinge.h */,
 				AD6C26971CF2481700F8B5FF /* XCUIDevice+FBHelpers.m */,
+				8C8E6FD103A84C908F5746EA /* XCUIDevice+FBHinge.m */,
 				A1B2C3D41F001A00A1B0001 /* XCUIDevice+FBVoiceOver.h */,
 				A1B2C3D41F001A00A1B0002 /* XCUIDevice+FBVoiceOver.m */,
 				EEE3763D1D59F81400ED88DD /* XCUIDevice+FBRotation.h */,
@@ -3178,6 +3188,7 @@
 				641EE6C02240C5CA00173FCB /* XCUIApplication+FBHelpers.h in Headers */,
 				714EAA0E2673FDFE005C5B47 /* FBCapabilities.h in Headers */,
 				641EE6C22240C5CA00173FCB /* XCUIDevice+FBHelpers.h in Headers */,
+				95EF6989BCBE4C548C26B140 /* XCUIDevice+FBHinge.h in Headers */,
 				71D3B3D6267FC7260076473D /* XCUIElement+FBResolve.h in Headers */,
 				641EE6C32240C5CA00173FCB /* FBClassChainQueryParser.h in Headers */,
 				641EE6C42240C5CA00173FCB /* FBMacros.h in Headers */,
@@ -3489,6 +3500,7 @@
 				81231F08969740B0C8C67A30 /* XCUIApplication+FBHelpers.h in Headers */,
 				9AA0E22033281B4EAA78BC51 /* FBCapabilities.h in Headers */,
 				D142183578036F5FD5B9880B /* XCUIDevice+FBHelpers.h in Headers */,
+				2E71304F39B64EDC98EE3974 /* XCUIDevice+FBHinge.h in Headers */,
 				09D97BD46764FD8149747723 /* XCUIElement+FBResolve.h in Headers */,
 				6BF3F57247F59B81B8BCEE7B /* FBClassChainQueryParser.h in Headers */,
 				8AAA33A5B1943B667B0DB05E /* FBMacros.h in Headers */,
@@ -3756,6 +3768,7 @@
 				AD6C269C1CF2494200F8B5FF /* XCUIApplication+FBHelpers.h in Headers */,
 				714D88CC2733FB970074A925 /* FBXMLGenerationOptions.h in Headers */,
 				AD6C26981CF2481700F8B5FF /* XCUIDevice+FBHelpers.h in Headers */,
+				210AB789D14D40308B764DD0 /* XCUIDevice+FBHinge.h in Headers */,
 				71A7EAF91E224648001DA4F2 /* FBClassChainQueryParser.h in Headers */,
 				EE9B76AA1CF7A43900275851 /* FBMacros.h in Headers */,
 				C8FB547922D4C1FC00B69954 /* FBUnattachedAppLauncher.h in Headers */,
@@ -4513,6 +4526,7 @@
 				641EE60B2240C5CA00173FCB /* FBCustomCommands.m in Sources */,
 				71BB58E42B9631F100CB9BFE /* FBScreenRecordingPromise.m in Sources */,
 				641EE60C2240C5CA00173FCB /* XCUIDevice+FBHelpers.m in Sources */,
+				181F0DBB6D28418680D52128 /* XCUIDevice+FBHinge.m in Sources */,
 				641EE60D2240C5CA00173FCB /* XCTestPrivateSymbols.m in Sources */,
 				641EE60E2240C5CA00173FCB /* XCUIElement+FBTyping.m in Sources */,
 				641EE60F2240C5CA00173FCB /* XCUIElement+FBAccessibility.m in Sources */,
@@ -4668,6 +4682,7 @@
 				EDC993E0858F89F73D8E9DF8 /* FBCustomCommands.m in Sources */,
 				45033CF6BD35C16E34BF76CC /* FBScreenRecordingPromise.m in Sources */,
 				583AD004FF71CAA305E6DEAF /* XCUIDevice+FBHelpers.m in Sources */,
+				0460879AD6034130AE0A3DEC /* XCUIDevice+FBHinge.m in Sources */,
 				192CACF49EC3825BA6D2EF4F /* XCTestPrivateSymbols.m in Sources */,
 				53E0F0F38E7847065810FF41 /* XCUIElement+FBTyping.m in Sources */,
 				A5353D849D394BC630839E59 /* XCUIElement+FBAccessibility.m in Sources */,
@@ -4787,6 +4802,7 @@
 				EE9B76A91CF7A43900275851 /* FBLogger.m in Sources */,
 				EE158ABB1CBD456F00A3E3F0 /* FBCustomCommands.m in Sources */,
 				AD6C26991CF2481700F8B5FF /* XCUIDevice+FBHelpers.m in Sources */,
+				25C9BDFC65564D78A70231B4 /* XCUIDevice+FBHinge.m in Sources */,
 				716C9E0227315EFF005AD475 /* XCUIApplication+FBUIInterruptions.m in Sources */,
 				EE6B64FE1D0F86EF00E85F5D /* XCTestPrivateSymbols.m in Sources */,
 				AD76723E1D6B7CC000610457 /* XCUIElement+FBTyping.m in Sources */,

package/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/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/WebDriverAgentLib/Categories/XCUIElement+FBUtilities.m

@@ -141,18 +141,21 @@
     return;
   }
 
-  NSTimeInterval previousTimeout = FBConfiguration.sharedInstance.waitForIdleTimeout;
-  BOOL previousQuiescence = self.application.fb_shouldWaitForQuiescence;
-  FBConfiguration.sharedInstance.waitForIdleTimeout = timeout;
-  if (!previousQuiescence) {
-    self.application.fb_shouldWaitForQuiescence = YES;
-  }
-  [[[self.application applicationImpl] currentProcess]
-   fb_waitForQuiescenceIncludingAnimationsIdle:YES];
-  if (previousQuiescence != self.application.fb_shouldWaitForQuiescence) {
-    self.application.fb_shouldWaitForQuiescence = previousQuiescence;
+  XCUIApplication *application = self.application;
+  // Recursive synchronization also covers nested stability checks on this thread.
+  @synchronized (FBConfiguration.sharedInstance) {
+    NSTimeInterval previousTimeout = FBConfiguration.sharedInstance.waitForIdleTimeout;
+    BOOL previousQuiescence = application.fb_shouldWaitForQuiescence;
+    @try {
+      FBConfiguration.sharedInstance.waitForIdleTimeout = timeout;
+      application.fb_shouldWaitForQuiescence = YES;
+      [[[application applicationImpl] currentProcess]
+        fb_waitForQuiescenceIncludingAnimationsIdle:YES];
+    } @finally {
+      application.fb_shouldWaitForQuiescence = previousQuiescence;
+      FBConfiguration.sharedInstance.waitForIdleTimeout = previousTimeout;
+    }
   }
-  FBConfiguration.sharedInstance.waitForIdleTimeout = previousTimeout;
 }
 
 - (void)fb_raiseStaleElementExceptionWithError:(NSError *)error __attribute__((noreturn))

package/WebDriverAgentLib/Commands/FBCustomCommands.m

@@ -29,6 +29,7 @@
 #import "XCUIApplication.h"
 #import "XCUIApplication+FBHelpers.h"
 #import "XCUIDevice+FBHelpers.h"
+#import "XCUIDevice+FBHinge.h"
 #import "XCUIDevice+FBVoiceOver.h"
 #import "XCUIElement.h"
 #import "XCUIElement+FBIsVisible.h"
@@ -74,6 +75,10 @@
     [[FBRoute POST:@"/wda/expectNotification"] respondWithTarget:self action:@selector(handleExpectNotification:)],
     [[FBRoute POST:@"/wda/siri/activate"] respondWithTarget:self action:@selector(handleActivateSiri:)],
     [[FBRoute POST:@"/wda/apps/launchUnattached"].withoutSession respondWithTarget:self action:@selector(handleLaunchUnattachedApp:)],
+    [[FBRoute GET:@"/wda/device/hingeAngle"] respondWithTarget:self action:@selector(handleGetSimulatedHingeAngle:)],
+    [[FBRoute GET:@"/wda/device/hingeAngle"].withoutSession respondWithTarget:self action:@selector(handleGetSimulatedHingeAngle:)],
+    [[FBRoute POST:@"/wda/device/hingeAngle"] respondWithTarget:self action:@selector(handleSetSimulatedHingeAngle:)],
+    [[FBRoute POST:@"/wda/device/hingeAngle"].withoutSession respondWithTarget:self action:@selector(handleSetSimulatedHingeAngle:)],
     [[FBRoute GET:@"/wda/device/info"] respondWithTarget:self action:@selector(handleGetDeviceInfo:)],
     [[FBRoute POST:@"/wda/resetAppAuth"] respondWithTarget:self action:@selector(handleResetAppAuth:)],
     [[FBRoute GET:@"/wda/device/info"].withoutSession respondWithTarget:self action:@selector(handleGetDeviceInfo:)],
@@ -777,4 +782,35 @@
   return FBResponseWithObject(result);
 }
 
++ (id<FBResponsePayload>)handleGetSimulatedHingeAngle:(FBRouteRequest *)request
+{
+  if (!XCUIDevice.sharedDevice.fb_supportsHingeAngleReading) {
+    return FBResponseWithStatus([FBCommandStatus unsupportedOperationErrorWithMessage:
+      @"Hinge angle reading is unavailable on this device" traceback:nil]);
+  }
+  NSError *error;
+  NSNumber *angle = [XCUIDevice.sharedDevice fb_getSimulatedHingeAngle:&error];
+  return nil == angle ? FBResponseWithUnknownError(error) : FBResponseWithObject(angle);
+}
+
++ (id<FBResponsePayload>)handleSetSimulatedHingeAngle:(FBRouteRequest *)request
+{
+  id angle = request.arguments[@"angle"];
+  if (![angle isKindOfClass:NSNumber.class]
+      || CFGetTypeID((__bridge CFTypeRef)angle) == CFBooleanGetTypeID()
+      || !isfinite([angle doubleValue]) || [angle doubleValue] < 0 || [angle doubleValue] > 180) {
+    return FBResponseWithStatus([FBCommandStatus invalidArgumentErrorWithMessage:
+      @"'angle' must be a finite number between 0 and 180 degrees" traceback:nil]);
+  }
+  if (!XCUIDevice.sharedDevice.fb_canAttemptSimulatedHingeAngleInjection) {
+    return FBResponseWithStatus([FBCommandStatus unsupportedOperationErrorWithMessage:
+      @"Setting a simulated hinge angle requires a compatible foldable device" traceback:nil]);
+  }
+  NSError *error;
+  if (![XCUIDevice.sharedDevice fb_setSimulatedHingeAngle:[angle doubleValue] error:&error]) {
+    return FBResponseWithUnknownError(error);
+  }
+  return FBResponseWithOK();
+}
+
 @end

package/WebDriverAgentLib/Info.plist

@@ -15,11 +15,11 @@
     <key>CFBundlePackageType</key>
     <string>FMWK</string>
     <key>CFBundleShortVersionString</key>
-    <string>16.13.5</string>
+    <string>16.14.0</string>
     <key>CFBundleSignature</key>
     <string>????</string>
     <key>CFBundleVersion</key>
-    <string>16.13.5</string>
+    <string>16.14.0</string>
     <key>NSPrincipalClass</key>
     <string/>
   </dict>

package/WebDriverAgentLib/Routing/FBScreenRecordingRequest.m

@@ -9,6 +9,7 @@
 #import "FBScreenRecordingRequest.h"
 
 #import "FBErrorBuilder.h"
+#import "FBScreen.h"
 #import "XCUIScreen.h"
 
 @implementation FBScreenRecordingRequest
@@ -56,6 +57,10 @@
 
 - (id)toNativeRequestWithError:(NSError **)error
 {
+  XCUIScreen *screen = [FBScreen currentScreenWithError:error];
+  if (nil == screen) {
+    return nil;
+  }
   Class screenRecordingRequestClass = NSClassFromString(@"XCTScreenRecordingRequest");
   if (nil == screenRecordingRequestClass) {
     [[[FBErrorBuilder builder]
@@ -80,8 +85,8 @@
   NSMethodSignature *screenRecordingRequestContructorSignature = [screenRecordingRequestAllocated methodSignatureForSelector:screenRecordingRequestConstructorSelector];
   NSInvocation *screenRecordingRequestInitInvocation = [NSInvocation invocationWithMethodSignature:screenRecordingRequestContructorSignature];
   [screenRecordingRequestInitInvocation setSelector:screenRecordingRequestConstructorSelector];
-  long long mainScreenId = XCUIScreen.mainScreen.displayID;
-  [screenRecordingRequestInitInvocation setArgument:&mainScreenId atIndex:2];
+  long long screenId = screen.displayID;
+  [screenRecordingRequestInitInvocation setArgument:&screenId atIndex:2];
   CGRect fullScreenRect = CGRectNull;
   [screenRecordingRequestInitInvocation setArgument:&fullScreenRect atIndex:3];
   [screenRecordingRequestInitInvocation setArgument:&videoEncoding atIndex:4];

package/WebDriverAgentLib/Utilities/FBActiveAppDetectionPoint.h

@@ -24,14 +24,14 @@ NS_ASSUME_NONNULL_BEGIN
  * Calculates the accessbility element which is located at the given screen coordinates
  *
  * @param point The screen coordinates
- * @returns The retrieved accessbility element or nil if it cannot be detected
+ * @returns The retrieved accessbility element or nil if it cannot be detected or a secondary display is selected
  */
 + (nullable id<FBXCAccessibilityElement>)axElementWithPoint:(CGPoint)point;
 
 /**
  * Retrieves the accessbility element for the current screen point
  *
- * @returns The retrieved accessbility element or nil if it cannot be detected
+ * @returns The retrieved accessbility element or nil if it cannot be detected or a secondary display is selected
  */
 - (nullable id<FBXCAccessibilityElement>)axElement;
 

package/WebDriverAgentLib/Utilities/FBActiveAppDetectionPoint.m

@@ -13,6 +13,10 @@
 #endif
 
 #import "FBErrorBuilder.h"
+#import "FBScreen.h"
+#import "FBConfiguration.h"
+#import "FBExceptions.h"
+#import "XCUIScreen.h"
 #import "FBLogger.h"
 #import "FBXCTestDaemonsProxy.h"
 #import "XCTMessagingChannel_RunnerToDaemon-Protocol.h"
@@ -45,6 +49,22 @@
 
 + (id<FBXCAccessibilityElement>)axElementWithPoint:(CGPoint)point
 {
+  if (nil != FBConfiguration.sharedInstance.currentDisplayId) {
+    NSError *error;
+    XCUIScreen *screen = [FBScreen currentScreenWithError:&error];
+    if (nil == screen) {
+      @throw [NSException exceptionWithName:FBInvalidArgumentException
+                                    reason:error.localizedDescription
+                                  userInfo:nil];
+    }
+    // XCTest's point lookup has no display parameter and always hits the main
+    // display. On Duo this can select the outer SpringBoard while the app is
+    // foreground on the inner display. Let callers use their active-app fallback
+    // instead of treating an element from a different display as authoritative.
+    if (screen.displayID != XCUIScreen.mainScreen.displayID) {
+      return nil;
+    }
+  }
   __block id<FBXCAccessibilityElement> onScreenElement = nil;
   id<XCTMessagingChannel_RunnerToDaemon> proxy = [FBXCTestDaemonsProxy testRunnerProxy];
   dispatch_semaphore_t sem = dispatch_semaphore_create(0);

package/WebDriverAgentLib/Utilities/FBConfiguration.h

@@ -369,7 +369,7 @@ typedef NS_ENUM(NSInteger, FBConfigurationKeyboardPreference) {
 @property (atomic, assign) BOOL enforceCustomSnapshots;
 
 /**
- * The identifier of the display targeted by screenshots.
+ * The identifier of the display targeted by screenshots, MJPEG, and new screen recordings.
  * nil means the main display. Reset to nil for each new session.
  */
 @property (atomic, copy, nullable) NSNumber *currentDisplayId;

package/WebDriverAgentLib/Utilities/FBMjpegServer.m

@@ -16,6 +16,7 @@
 #import "FBConfiguration.h"
 #import "FBLogger.h"
 #import "FBScreenshot.h"
+#import "FBScreen.h"
 #import "FBImageProcessor.h"
 #import "FBImageUtils.h"
 #import "XCUIScreen.h"
@@ -42,7 +43,6 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
 @property (nonatomic, readonly) dispatch_queue_t backgroundQueue;
 @property (nonatomic, readonly) NSMutableArray<nw_connection_t> *listeningClients;
 @property (nonatomic, readonly) FBImageProcessor *imageProcessor;
-@property (nonatomic, readonly) long long mainScreenID;
 @property (nonatomic, assign) NSUInteger consecutiveScreenshotFailures;
 @property (atomic, assign) BOOL isStreaming;
 @property (nonatomic, assign) NSUInteger sentFramesCount;
@@ -67,7 +67,6 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
     _pendingFrameCounts = [NSMapTable mapTableWithKeyOptions:(NSPointerFunctionsOptions)(NSMapTableObjectPointerPersonality | NSMapTableStrongMemory)
                                                 valueOptions:(NSPointerFunctionsOptions)NSMapTableStrongMemory];
     _imageProcessor = [[FBImageProcessor alloc] init];
-    _mainScreenID = [XCUIScreen.mainScreen displayID];
     dispatch_queue_attr_t queueAttributes = dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_UTILITY, 0);
     _backgroundQueue = dispatch_queue_create(QUEUE_NAME, queueAttributes);
     __weak typeof(self) weakSelf = self;
@@ -116,7 +115,8 @@ static NSUInteger FBNormalizedMjpegFramerate(NSUInteger framerate)
   NSError *error;
   CGFloat compressionQuality = MAX(FBMinCompressionQuality,
                                    MIN(FBMaxCompressionQuality, (double)FBConfiguration.sharedInstance.mjpegServerScreenshotQuality / 100.0));
-  NSData *screenshotData = [FBScreenshot takeInOriginalResolutionWithScreenID:self.mainScreenID
+  XCUIScreen *screen = [FBScreen currentScreenWithError:&error];
+  NSData *screenshotData = nil == screen ? nil : [FBScreenshot takeInOriginalResolutionWithScreenID:screen.displayID
                                                            compressionQuality:compressionQuality
                                                                           uti:UTTypeJPEG
                                                                       timeout:FRAME_TIMEOUT

package/WebDriverAgentLib/Utilities/FBScreen.m

@@ -13,12 +13,26 @@
 #import "FBXCodeCompatibility.h"
 #import "XCUIDevice.h"
 #import "XCUIScreen.h"
+#import <objc/message.h>
+
+static NSArray<XCUIScreen *> *FBScreensForDevice(id device, NSError **error)
+{
+  SEL selector = NSSelectorFromString(@"screensOrError:");
+  if ([device respondsToSelector:selector]) {
+    return ((NSArray<XCUIScreen *> *(*)(id, SEL, NSError **))objc_msgSend)(device, selector, error);
+  }
+  // Older XCTest versions expose screens on XCUIScreen instead of XCUIDevice.
+  if ([XCUIScreen respondsToSelector:NSSelectorFromString(@"screens")]) {
+    return XCUIScreen.screens;
+  }
+  return @[XCUIScreen.mainScreen];
+}
 
 @implementation FBScreen
 
 + (nullable NSArray<NSDictionary<NSString *, id> *> *)screensWithError:(NSError **)error
 {
-  NSArray<XCUIScreen *> *screens = [XCUIDevice.sharedDevice screensOrError:error];
+  NSArray<XCUIScreen *> *screens = FBScreensForDevice(XCUIDevice.sharedDevice, error);
   if (nil == screens) {
     return nil;
   }
@@ -42,27 +56,56 @@
   return result.copy;
 }
 
-+ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID error:(NSError **)error
+// Kept separate from sharedDevice so legacy lookup behavior can be tested.
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID
+                                    device:(XCUIDevice *)device
+                                     error:(NSError **)error
 {
-  NSArray<XCUIScreen *> *screens = [XCUIDevice.sharedDevice screensOrError:error];
+  SEL lookupSelector = NSSelectorFromString(@"screenWithDisplayID:orError:");
+  BOOL hasNativeLookup = [device respondsToSelector:lookupSelector];
+  BOOL needsEnumeratedLookup = !hasNativeLookup;
+  NSError *lookupError = nil;
+  if (hasNativeLookup) {
+    XCUIScreen *screen = ((XCUIScreen *(*)(id, SEL, long long, NSError **))objc_msgSend)(
+      device, lookupSelector, displayID, &lookupError);
+    if ([screen respondsToSelector:NSSelectorFromString(@"bounds")] && !CGRectIsEmpty(screen.bounds)) {
+      return screen;
+    }
+    // XCTest may return a zero-sized placeholder for an inactive wireless
+    // display which screensOrError: omits. Confirm its availability by listing.
+    needsEnumeratedLookup = nil != screen;
+  }
+  // Enumerate only for legacy/placeholder lookups or to enrich a lookup error.
+  NSError *enumerationError = nil;
+  NSArray<XCUIScreen *> *screens = FBScreensForDevice(device, &enumerationError);
   if (nil == screens) {
+    if (NULL != error) {
+      *error = lookupError ?: enumerationError;
+    }
     return nil;
   }
+  NSMutableArray<NSNumber *> *availableIDs = [NSMutableArray arrayWithCapacity:screens.count];
   for (XCUIScreen *screen in screens) {
-    if (screen.displayID == displayID) {
+    if (needsEnumeratedLookup && screen.displayID == displayID) {
       return screen;
     }
-  }
-  NSMutableArray<NSNumber *> *availableIDs = [NSMutableArray arrayWithCapacity:screens.count];
-  for (XCUIScreen *screen in screens) {
     [availableIDs addObject:@(screen.displayID)];
   }
-  [[FBErrorBuilder.builder withDescriptionFormat:@"No display with id %lld is available. Available display ids: [%@]",
-    displayID, [availableIDs componentsJoinedByString:@", "]]
-   buildError:error];
+  FBErrorBuilder *builder = [FBErrorBuilder.builder withDescriptionFormat:
+    @"No display with id %lld is available. Available display ids: [%@]",
+    displayID, [availableIDs componentsJoinedByString:@", "]];
+  if (nil != lookupError) {
+    [builder withInnerError:lookupError];
+  }
+  [builder buildError:error];
   return nil;
 }
 
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID error:(NSError **)error
+{
+  return [self screenWithDisplayID:displayID device:XCUIDevice.sharedDevice error:error];
+}
+
 + (nullable XCUIScreen *)currentScreenWithError:(NSError **)error
 {
   NSNumber *displayID = FBConfiguration.sharedInstance.currentDisplayId;

package/WebDriverAgentLib/WebDriverAgentLib.h

@@ -47,6 +47,7 @@ FOUNDATION_EXPORT const unsigned char WebDriverAgentLib_VersionString[];
 #import <WebDriverAgentLib/XCTIssue+FBPatcher.h>
 #import <WebDriverAgentLib/XCUIApplication+FBHelpers.h>
 #import <WebDriverAgentLib/XCUIDevice+FBHelpers.h>
+#import <WebDriverAgentLib/XCUIDevice+FBHinge.h>
 #import <WebDriverAgentLib/XCUIDevice+FBRotation.h>
 #import <WebDriverAgentLib/XCUIDevice+FBVoiceOver.h>
 #import <WebDriverAgentLib/XCUIElement.h>

package/WebDriverAgentTests/IntegrationTests/FBScreenTests.m

@@ -11,9 +11,58 @@
 #import "FBIntegrationTestCase.h"
 #import "FBConfiguration.h"
 #import "FBScreen.h"
+#import "FBActiveAppDetectionPoint.h"
+#import "FBExceptions.h"
+#import "FBScreenRecordingRequest.h"
 #import "FBScreenshot.h"
 #import "XCUIScreen.h"
 
+@interface FBScreen (FBLookupTesting)
++ (nullable XCUIScreen *)screenWithDisplayID:(long long)displayID device:(id)device error:(NSError **)error;
+@end
+
+@interface FBEmptyScreenDouble : NSObject
+@property (nonatomic) CGRect bounds;
+@end
+@implementation FBEmptyScreenDouble
+@end
+
+@interface FBScreenDeviceDouble : NSObject
+@property (nonatomic) BOOL nativeLookupAvailable;
+@property (nonatomic) BOOL enumerationUnavailable;
+@property (nonatomic) NSUInteger enumerationCount;
+@property (nonatomic, strong) XCUIScreen *nativeScreen;
+@property (nonatomic, strong) NSArray<XCUIScreen *> *screens;
+@property (nonatomic, strong) NSError *lookupError;
+@property (nonatomic, strong) NSError *enumerationError;
+@end
+
+@implementation FBScreenDeviceDouble
+- (BOOL)respondsToSelector:(SEL)selector
+{
+  if (selector == NSSelectorFromString(@"screensOrError:") && self.enumerationUnavailable) {
+    return NO;
+  }
+  return selector == @selector(screenWithDisplayID:orError:)
+    ? self.nativeLookupAvailable : [super respondsToSelector:selector];
+}
+- (XCUIScreen *)screenWithDisplayID:(long long)displayID orError:(NSError **)error
+{
+  if (NULL != error) {
+    *error = self.lookupError;
+  }
+  return self.nativeScreen;
+}
+- (NSArray<XCUIScreen *> *)screensOrError:(NSError **)error
+{
+  self.enumerationCount++;
+  if (NULL != error) {
+    *error = self.enumerationError;
+  }
+  return self.screens;
+}
+@end
+
 @interface FBScreenTests : FBIntegrationTestCase
 @end
 
@@ -62,9 +111,13 @@
 - (void)testScreenWithDisplayID
 {
   NSError *error = nil;
-  XCUIScreen *screen = [FBScreen screenWithDisplayID:[FBScreen displayID] error:&error];
-  XCTAssertNil(error);
-  XCTAssertEqual(screen.displayID, [FBScreen displayID]);
+  for (NSDictionary<NSString *, id> *entry in [FBScreen screensWithError:&error]) {
+    long long displayID = [entry[@"displayId"] longLongValue];
+    XCUIScreen *screen = [FBScreen screenWithDisplayID:displayID error:&error];
+    XCTAssertNotNil(screen);
+    XCTAssertNil(error);
+    XCTAssertEqual(screen.displayID, displayID);
+  }
 
   XCTAssertNil([FBScreen screenWithDisplayID:[self unknownDisplayID] error:&error]);
   XCTAssertNotNil(error);
@@ -77,6 +130,84 @@
   XCTAssertTrue([error.localizedDescription containsString:availableDisplays]);
 }
 
+- (void)testNativeScreenLookupDoesNotEnumerateOnSuccess
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.nativeLookupAvailable = YES;
+  device.nativeScreen = XCUIScreen.mainScreen;
+  NSError *error = nil;
+  XCTAssertEqualObjects([FBScreen screenWithDisplayID:device.nativeScreen.displayID device:device error:&error],
+                        device.nativeScreen);
+  XCTAssertNil(error);
+  XCTAssertEqual(device.enumerationCount, 0UL);
+}
+
+- (void)testNativeScreenPlaceholderMustBeAvailable
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.nativeLookupAvailable = YES;
+  device.nativeScreen = (id)[FBEmptyScreenDouble new];
+  device.screens = @[XCUIScreen.mainScreen];
+  NSError *error = nil;
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertNotNil(error);
+  XCTAssertEqual(device.enumerationCount, 1UL);
+}
+
+- (void)testNativeScreenLookupFailureIncludesAvailableIDs
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.nativeLookupAvailable = YES;
+  device.screens = @[XCUIScreen.mainScreen];
+  device.lookupError = [NSError errorWithDomain:@"NativeLookup" code:1 userInfo:nil];
+  NSError *error = nil;
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertEqual(device.enumerationCount, 1UL);
+  XCTAssertTrue([error.localizedDescription containsString:@"Available display ids"]);
+  XCTAssertEqualObjects(error.userInfo[NSUnderlyingErrorKey], device.lookupError);
+}
+
+- (void)testNativeScreenLookupErrorSurvivesEnumerationFailure
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.nativeLookupAvailable = YES;
+  device.lookupError = [NSError errorWithDomain:@"NativeLookup" code:1 userInfo:nil];
+  device.enumerationError = [NSError errorWithDomain:@"Enumeration" code:2 userInfo:nil];
+  NSError *error = nil;
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertEqualObjects(error, device.lookupError);
+}
+
+- (void)testScreenLookupWithoutNativeSelector
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.screens = @[XCUIScreen.mainScreen];
+  NSError *error = nil;
+  XCTAssertEqualObjects([FBScreen screenWithDisplayID:XCUIScreen.mainScreen.displayID device:device error:&error],
+                        XCUIScreen.mainScreen);
+  XCTAssertNil(error);
+  XCTAssertEqual(device.enumerationCount, 1UL);
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertTrue([error.localizedDescription containsString:@"Available display ids"]);
+  device.screens = nil;
+  device.enumerationError = [NSError errorWithDomain:@"Enumeration" code:2 userInfo:nil];
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertEqualObjects(error, device.enumerationError);
+}
+
+- (void)testScreenLookupWithoutDeviceScreenSelectors
+{
+  FBScreenDeviceDouble *device = [FBScreenDeviceDouble new];
+  device.enumerationUnavailable = YES;
+  NSError *error = nil;
+  XCTAssertEqualObjects([FBScreen screenWithDisplayID:XCUIScreen.mainScreen.displayID device:device error:&error],
+                        XCUIScreen.mainScreen);
+  XCTAssertNil(error);
+  XCTAssertNil([FBScreen screenWithDisplayID:-1 device:device error:&error]);
+  XCTAssertNotNil(error);
+  XCTAssertEqual(device.enumerationCount, 0UL);
+}
+
 - (void)testCurrentScreenDefaultsToMainScreen
 {
   NSError *error = nil;
@@ -108,6 +239,52 @@
   XCTAssertNil(FBConfiguration.sharedInstance.currentDisplayId);
 }
 
+- (void)testSecondaryDisplayDoesNotHitTestMainDisplay
+{
+  NSArray<NSDictionary<NSString *, id> *> *screens = [FBScreen screensWithError:nil];
+  BOOL testedSecondaryDisplay = NO;
+  for (NSDictionary<NSString *, id> *screen in screens) {
+    if ([screen[@"isMain"] boolValue]) {
+      continue;
+    }
+    testedSecondaryDisplay = YES;
+    FBConfiguration.sharedInstance.currentDisplayId = screen[@"displayId"];
+    XCTAssertNil(FBActiveAppDetectionPoint.sharedInstance.axElement);
+  }
+  XCTSkipIf(!testedSecondaryDisplay, @"Requires a secondary display");
+}
+
+- (void)testActiveAppDetectionRejectsUnavailableDisplay
+{
+  FBConfiguration.sharedInstance.currentDisplayId = @([self unknownDisplayID]);
+  XCTAssertThrowsSpecificNamed(FBActiveAppDetectionPoint.sharedInstance.axElement,
+                               NSException, FBInvalidArgumentException);
+}
+
+- (void)testRecordingUsesSelectedDisplay
+{
+  XCTSkipIf(nil == NSClassFromString(@"XCTScreenRecordingRequest"), @"Screen recording is unavailable");
+  FBScreenRecordingRequest *request = [[FBScreenRecordingRequest alloc] initWithFps:10 codec:0];
+  NSError *error = nil;
+  id defaultRequest = [request toNativeRequestWithError:&error];
+  XCTAssertNotNil(defaultRequest);
+  XCTAssertNil(error);
+  XCTAssertEqualObjects([defaultRequest valueForKey:@"screenID"], @([FBScreen displayID]));
+
+  for (NSDictionary<NSString *, id> *screen in [FBScreen screensWithError:nil]) {
+    FBConfiguration.sharedInstance.currentDisplayId = screen[@"displayId"];
+    id nativeRequest = [request toNativeRequestWithError:&error];
+    XCTAssertNotNil(nativeRequest);
+    XCTAssertNil(error);
+    XCTAssertEqualObjects([nativeRequest valueForKey:@"screenID"], screen[@"displayId"]);
+  }
+
+  FBConfiguration.sharedInstance.currentDisplayId = @([self unknownDisplayID]);
+  XCTAssertNil([request toNativeRequestWithError:&error]);
+  XCTAssertNotNil(error);
+  XCTAssertTrue([error.localizedDescription containsString:@"Available display ids"]);
+}
+
 - (long long)unknownDisplayID
 {
   long long maxID = 0;

package/WebDriverAgentTests/UnitTests/FBCustomCommandsTests.m

@@ -12,12 +12,17 @@
 #import "FBElementCache.h"
 #import "FBRouteRequest-Private.h"
 #import "FBSession.h"
+#import "FBResponsePayload.h"
+#import "RouteResponse.h"
+#import "XCUIDevice+FBHinge.h"
 #import "Doubles/XCUIElementDouble.h"
 
 #if !TARGET_OS_TV && __clang_major__ >= 15
 
 @interface FBCustomCommands (FBWDATestable)
 + (id<FBResponsePayload>)handleKeyboardInput:(FBRouteRequest *)request;
++ (id<FBResponsePayload>)handleGetSimulatedHingeAngle:(FBRouteRequest *)request;
++ (id<FBResponsePayload>)handleSetSimulatedHingeAngle:(FBRouteRequest *)request;
 @end
 
 @interface FBCustomCommandsTests : XCTestCase
@@ -78,6 +83,62 @@
   XCTAssertEqual(element.lastTypedModifierFlags, 2);
 }
 
+- (NSDictionary *)hingeResponseWithArguments:(NSDictionary *)arguments
+{
+  FBRouteRequest *request = [FBRouteRequest routeRequestWithURL:[NSURL URLWithString:@"http://localhost:8100/"]
+                                                  parameters:@{}
+                                                   arguments:arguments];
+  RouteResponse *response = [RouteResponse new];
+  [[FBCustomCommands handleSetSimulatedHingeAngle:request] dispatchWithResponse:response];
+  return [NSJSONSerialization JSONObjectWithData:response.responseData options:0 error:nil];
+}
+
+- (void)testHingeAngleReading
+{
+  NSError *error = nil;
+  NSNumber *angle = [XCUIDevice.sharedDevice fb_getSimulatedHingeAngle:&error];
+  BOOL available = XCUIDevice.sharedDevice.fb_supportsHingeAngleReading;
+  if (available) {
+    XCTAssertNotNil(angle);
+    XCTAssertNil(error);
+    XCTAssertTrue(isfinite(angle.doubleValue));
+  } else {
+    XCTAssertNil(angle);
+    XCTAssertNotNil(error);
+  }
+
+  FBRouteRequest *request = [FBRouteRequest routeRequestWithURL:[NSURL URLWithString:@"http://localhost:8100/"]
+                                                  parameters:@{}
+                                                   arguments:@{}];
+  RouteResponse *response = [RouteResponse new];
+  [[FBCustomCommands handleGetSimulatedHingeAngle:request] dispatchWithResponse:response];
+  NSDictionary *body = [NSJSONSerialization JSONObjectWithData:response.responseData options:0 error:nil];
+  if (available) {
+    XCTAssertTrue([body[@"value"] isKindOfClass:NSNumber.class]);
+    XCTAssertTrue(isfinite([body[@"value"] doubleValue]));
+  } else {
+    XCTAssertEqualObjects(body[@"value"][@"error"], @"unsupported operation");
+  }
+}
+
+- (void)testHingeAngleRejectsInvalidArguments
+{
+  for (id value in @[@(-1), @181, @YES, @"90", NSNull.null, @(NAN), @(INFINITY)]) {
+    NSDictionary *response = [self hingeResponseWithArguments:@{@"angle": value}];
+    XCTAssertEqualObjects(response[@"value"][@"error"], @"invalid argument");
+  }
+  XCTAssertEqualObjects([self hingeResponseWithArguments:@{}][@"value"][@"error"], @"invalid argument");
+}
+
+- (void)testHingeAngleRejectsUnsupportedDevices
+{
+  XCTSkipIf(XCUIDevice.sharedDevice.fb_canAttemptSimulatedHingeAngleInjection, @"Requires a device without an available hinge");
+  for (NSNumber *angle in @[@0, @90, @180]) {
+    XCTAssertEqualObjects([self hingeResponseWithArguments:@{@"angle": angle}][@"value"][@"error"],
+                          @"unsupported operation");
+  }
+}
+
 @end
 
 #endif

package/WebDriverAgentTests/UnitTests/FBElementUtilitiesTests.m

@@ -12,12 +12,52 @@
 #import "FBElement.h"
 #import "XCUIElementDouble.h"
 #import "FBElementUtils.h"
+#import "FBConfiguration.h"
+#import "XCUIElement+FBUtilities.h"
+#import <objc/runtime.h>
+
+@interface FBQuiescenceApplicationDouble : NSObject
+@property (nonatomic) BOOL fb_shouldWaitForQuiescence;
+@property (nonatomic) NSTimeInterval observedTimeout;
+@end
+@implementation FBQuiescenceApplicationDouble
+- (id)applicationImpl { return self; }
+- (id)currentProcess { return self; }
+- (void)fb_waitForQuiescenceIncludingAnimationsIdle:(BOOL)includingAnimations
+{
+  self.observedTimeout = FBConfiguration.sharedInstance.waitForIdleTimeout;
+  @throw [NSException exceptionWithName:@"QuiescenceFailure" reason:@"test" userInfo:nil];
+}
+@end
 
 @interface FBElementUtilitiesTests : XCTestCase
 @end
 
 @implementation FBElementUtilitiesTests
 
+- (void)testStabilityWaitRestoresSettingsAfterAnException
+{
+  NSTimeInterval originalTimeout = FBConfiguration.sharedInstance.waitForIdleTimeout;
+  FBQuiescenceApplicationDouble *application = [FBQuiescenceApplicationDouble new];
+  XCUIElementDouble *element = [XCUIElementDouble new];
+  element.application = (id)application;
+  SEL selector = @selector(fb_waitUntilStableWithTimeout:);
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wcast-function-type-strict"
+  void (*wait)(id, SEL, NSTimeInterval) = (void (*)(id, SEL, NSTimeInterval))
+    class_getMethodImplementation(XCUIElement.class, selector);
+#pragma clang diagnostic pop
+  @try {
+    FBConfiguration.sharedInstance.waitForIdleTimeout = 17;
+    XCTAssertThrowsSpecificNamed(wait(element, selector, 2), NSException, @"QuiescenceFailure");
+    XCTAssertEqual(application.observedTimeout, 2);
+    XCTAssertFalse(application.fb_shouldWaitForQuiescence);
+    XCTAssertEqual(FBConfiguration.sharedInstance.waitForIdleTimeout, 17);
+  } @finally {
+    FBConfiguration.sharedInstance.waitForIdleTimeout = originalTimeout;
+  }
+}
+
 - (void)testTypesFiltering {
   NSMutableArray *elements = [NSMutableArray new];
   XCUIElementDouble *el1 = [XCUIElementDouble new];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-webdriveragent",
-  "version": "16.13.5",
+  "version": "16.14.0",
   "description": "Package bundling WebDriverAgent",
   "keywords": [
     "Appium",