feat: add currentDisplayId setting for screenshots

[jsteinberg7]

On multi-display devices like iPhone Duo, the app can move to a secondary display while /screenshot keeps capturing the main one. Following the UiAutomator2 approach, this adds a currentDisplayId setting that selects the display screenshots capture.

• currentDisplayId takes an integer displayId from /wda/screens. Unknown IDs and non-integer values return invalid argument.
• Setting it to null goes back to the main display. It's also reset for each new session. Reading it returns the display currently in use.
• /screenshot captures the selected display and respects screenshotQuality. If that display goes away (for example when the device is folded), the request fails instead of quietly capturing the main display.

Nothing changes unless the setting is used. The MJPEG stream and screen recording still capture the main display. I can follow up on those separately if that's useful.

W3C actions support is in #1269, which builds on this one. Driver docs and mobile: getScreens are in appium/appium-xcuitest-driver#2988.

Tested with Xcode 27.1 beta:

• FBScreenTests (including the new cases) on iPhone Duo / iOS 27.1 and iPhone 16 Pro / iOS 18.2
• 162 native unit tests
• Generic iOS, tvOS and watchOS runner builds
• New functional check covering setting validation, reset and screenshots, run against a live WDA on iPhone 16 Pro
• Live run through the driver on Duo, selecting the outer or inner display in the closed, open, book and closed poses. Each screenshot came from the selected display.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jsteinberg7 / name: Jason Steinberg (b5a897f)

[KazuCocoa]

Please split changes into multiple PRs - screenshots and actions

[eglitise]

Not sure how feasible this is, but I would instead suggest to follow a similar approach to UiAutomator2 driver - add a setting named currentDisplayId, which allows changing the active display targeted by the common endpoints for retrieving screenshots, app source, etc. This would be a more easily extensible solution, as opposed to adding new endpoints and new optional parameters for largely duplicated functionality.

Check the UiAutomator2 docs for more details: https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/android-multiwindow.md

[eglitise]

Considering the README doesn't list implementation details, I would discourage doing so here. Generally, feature documentation goes in the XCUITest driver's docs.

[mykola-mokhnach]

what this check is for?

[jsteinberg7]

rm'd!

[KazuCocoa]

JSON booleans deserialize as NSNumber, so true and false pass this check as 1 and 0. If that display exists, the request changes the selected display instead of returning invalid argument. Restore the boolean guard removed in the latest commit and retain boolean rejection tests.