chore: rebase beta onto master

.github/workflows/docs.yml

@@ -27,7 +27,7 @@ jobs:
         with:
           python-version: '3.12'
       - name: Use Node.js LTS
-        uses: actions/setup-node@v7.0.0
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
           check-latest: true

.github/workflows/functional-test.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - master
+      - beta
     paths-ignore:
       - 'docs/**'
       - '*.md'
@@ -70,7 +71,7 @@ jobs:
       - uses: actions/checkout@v7.0.1
 
       - name: Install Node.js
-        uses: actions/setup-node@v7.0.0
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: 'lts/*'
 
@@ -131,15 +132,15 @@ jobs:
           PLATFORM_VERSION: ${{ steps.simTarget.outputs.platformVersion }}
       - name: Prepare simulator
         id: prepareSimulator
-        uses: futureware-tech/simulator-action@v5
+        uses: futureware-tech/simulator-action@v6
         with:
           model: '${{ steps.simTarget.outputs.deviceName }}'
           os: '${{ steps.simTarget.outputs.os }}'
           os_version: '${{ steps.simTarget.outputs.platformVersion }}'
           shutdown_after_job: false
           wait_for_boot: true
-      - name: Finalize simulator boot
-        run: node scripts/ci/wait-for-simulator-idle.mjs "${{ steps.prepareSimulator.outputs.udid }}"
+          settle_timeout_seconds: 150
+          settle_cpu_threshold_percent: 30
 
       - run: |
           appium_ver=$(node -p "require('./package.json').peerDependencies?.appium")
@@ -157,7 +158,7 @@ jobs:
           cd ~
           appium driver install --source=local "$cwd"
           appium driver doctor xcuitest
-          appium driver run xcuitest download-wda -- --platform="$DOWNLOAD_PLATFORM" --outdir=$(dirname "$PREBUILT_WDA_PATH") --kind=sim
+          appium driver run xcuitest download-wda -- --platform="$DOWNLOAD_PLATFORM" --outdir=$(dirname "$PREBUILT_WDA_PATH") --kind=sim --fallback-queue-max-len=10
           echo "Starting Appium server on $APPIUM_TEST_SERVER_HOST:$APPIUM_TEST_SERVER_PORT"
           nohup appium server \
             --port=$APPIUM_TEST_SERVER_PORT \
@@ -168,7 +169,8 @@ jobs:
             --keep-alive-timeout 1200 \
             2>&1 > "$cwd/appium.log" &
 
-          TIMEOUT_SEC=15
+          # Port opens only after the driver is loaded, which is slow on CPU-starved runners
+          TIMEOUT_SEC=60
           INTERVAL_SEC=1
 
           start_time=$(date +%s)
@@ -185,6 +187,7 @@ jobs:
 
             if [[ "$elapsed" -ge "$TIMEOUT_SEC" ]]; then
               echo "${elapsed} seconds timeout reached: Appium server is NOT running"
+              cat "$cwd/appium.log"
               exit 1
             fi
 

.github/workflows/publish-doc.yml

@@ -22,7 +22,7 @@ jobs:
           git config user.name github-actions
           git config user.email github-actions@github.com
       - name: Use Node.js LTS
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v3
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v3
         with:
           node-version: lts/*
       - run: npm install

.github/workflows/publish.js.yml

@@ -31,7 +31,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@v7.0.0
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
       - run: npm install --no-package-lock

.github/workflows/unit-test.yml

@@ -1,13 +1,13 @@
 name: Unit Tests
 on:
   pull_request:
-    branches: [master]
+    branches: [master, beta]
     paths-ignore:
       - 'docs/**'
       - '*.md'
       - 'mkdocs.yml'
   push:
-    branches: [master]
+    branches: [master, beta]
     paths-ignore:
       - 'docs/**'
       - '*.md'
@@ -28,7 +28,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v3
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v3
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v3
         with:
           node-version: ${{ matrix.node-version }}
       - uses: SocketDev/action@v1

CHANGELOG.md

@@ -1,3 +1,193 @@
+## [12.22.8](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.7...v12.22.8) (2026-10-31)
+
+### Miscellaneous Chores
+
+* remove wrong docstring comment ([#3108](https://github.com/appium/appium-xcuitest-driver/issues/3108)) ([6df7cff](https://github.com/appium/appium-xcuitest-driver/commit/6df7cff8f8fb6602231e9910be6707a10f4ffe93))
+
+## [12.22.7](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.6...v12.22.7) (2026-10-30)
+
+### Bug Fixes
+
+* move withoutImplicitWait to utils ([#3103](https://github.com/appium/appium-xcuitest-driver/issues/3103)) ([24d1285](https://github.com/appium/appium-xcuitest-driver/commit/24d1285588d5e6584a9187b397bf53781dc6f669))
+
+## [12.22.6](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.5...v12.22.6) (2026-10-30)
+
+### Bug Fixes
+
+* don't wait for implicit timeout on internal native lookups ([#3101](https://github.com/appium/appium-xcuitest-driver/issues/3101)) ([c1e611e](https://github.com/appium/appium-xcuitest-driver/commit/c1e611e91ac22cbc4d3f824e87caf167c6fe2625))
+
+## [12.22.5](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.4...v12.22.5) (2026-10-29)
+
+### Performance Improvements
+
+* find first visible child with a single class chain query ([#3100](https://github.com/appium/appium-xcuitest-driver/issues/3100)) ([768b2af](https://github.com/appium/appium-xcuitest-driver/commit/768b2af5c6ea01afb2ce0f0e0f887e6f6d395f3a))
+
+## [12.22.4](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.3...v12.22.4) (2026-10-29)
+
+### Bug Fixes
+
+* make WDA the source of truth for its settings ([#3097](https://github.com/appium/appium-xcuitest-driver/issues/3097)) ([ce5a997](https://github.com/appium/appium-xcuitest-driver/commit/ce5a99708c06edce87db87b117cebbac9b58b02a))
+
+## [12.22.3](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.2...v12.22.3) (2026-10-28)
+
+### Bug Fixes
+
+* remove perf recording temp files when start or upload fails ([#3092](https://github.com/appium/appium-xcuitest-driver/issues/3092)) ([edc9a19](https://github.com/appium/appium-xcuitest-driver/commit/edc9a192397db0343858cb5b4e0b4defbaede681))
+
+## [12.22.2](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.1...v12.22.2) (2026-10-28)
+
+### Bug Fixes
+
+* stop stale remote debugger listeners when switching webview contexts ([#3089](https://github.com/appium/appium-xcuitest-driver/issues/3089)) ([e963398](https://github.com/appium/appium-xcuitest-driver/commit/e96339839225581647e0f90ea0d98d0a825db2dd))
+
+## [12.22.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.22.0...v12.22.1) (2026-10-28)
+
+### Miscellaneous Chores
+
+* release to bump the dependency for shell quote ([6d988f1](https://github.com/appium/appium-xcuitest-driver/commit/6d988f1df3a6388545458bc55da75efb5309fb30))
+
+## [12.22.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.21.0...v12.22.0) (2026-10-27)
+
+### Features
+
+* route Duo simulator HID controls through the host ([#3077](https://github.com/appium/appium-xcuitest-driver/issues/3077)) ([32dae67](https://github.com/appium/appium-xcuitest-driver/commit/32dae673c5b93bdee2fc5c3fe57a45c02a0295b2))
+
+## [12.21.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.20.0...v12.21.0) (2026-10-26)
+
+### Features
+
+* add keyboardWaitTimeout setting ([#3073](https://github.com/appium/appium-xcuitest-driver/issues/3073)) ([7f4bcbd](https://github.com/appium/appium-xcuitest-driver/commit/7f4bcbd27209dcdad2300cd285274a8fac61f0da))
+
+## [12.20.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.19.1...v12.20.0) (2026-10-22)
+
+### Features
+
+* add execute method for retrieving pressable buttons ([#3071](https://github.com/appium/appium-xcuitest-driver/issues/3071)) ([10553a0](https://github.com/appium/appium-xcuitest-driver/commit/10553a02810736493aea868d5570b39637f74ec6))
+
+## [12.19.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.19.0...v12.19.1) (2026-10-19)
+
+### Bug Fixes
+
+* preserve iOS 27 webview interaction history ([#3063](https://github.com/appium/appium-xcuitest-driver/issues/3063)) ([bf36e32](https://github.com/appium/appium-xcuitest-driver/commit/bf36e32e4bcc3b78d4b0f6696d7a21b8299135bc))
+
+## [12.19.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.18.3...v12.19.0) (2026-10-18)
+
+### Features
+
+* capture selected simulator displays through CoreSim fallback ([#3030](https://github.com/appium/appium-xcuitest-driver/issues/3030)) ([80b341c](https://github.com/appium/appium-xcuitest-driver/commit/80b341c929b26a3ac278089a5fd1c3af8ca9a943))
+
+### Bug Fixes
+
+* preserve recording padding when MJPEG frame geometry changes ([#3048](https://github.com/appium/appium-xcuitest-driver/issues/3048)) ([c860f30](https://github.com/appium/appium-xcuitest-driver/commit/c860f308b23c29e33d2bfa37773e691045c15c4c))
+* retain and clean up screen recorder after stop failure ([#3049](https://github.com/appium/appium-xcuitest-driver/issues/3049)) ([a4b262a](https://github.com/appium/appium-xcuitest-driver/commit/a4b262a642da4e5f9a6a83a99959bdba9f7dce8c))
+
+## [12.18.3](https://github.com/appium/appium-xcuitest-driver/compare/v12.18.2...v12.18.3) (2026-10-18)
+
+### Bug Fixes
+
+* preserve calibrated scale and viewport origin for native web taps ([#3046](https://github.com/appium/appium-xcuitest-driver/issues/3046)) ([e62b338](https://github.com/appium/appium-xcuitest-driver/commit/e62b338a21f6f8ce401d93c81801e42e26047a45))
+
+## [12.18.2](https://github.com/appium/appium-xcuitest-driver/compare/v12.18.1...v12.18.2) (2026-10-18)
+
+### Bug Fixes
+
+* resolve WDA downloads from the monorepo release ([#3050](https://github.com/appium/appium-xcuitest-driver/issues/3050)) ([0e990dc](https://github.com/appium/appium-xcuitest-driver/commit/0e990dcf45fddcb2b635bd9dad7cd278c066f735))
+
+## [12.18.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.18.0...v12.18.1) (2026-10-13)
+
+### Bug Fixes
+
+* capture the whole element in web element screenshots ([#3040](https://github.com/appium/appium-xcuitest-driver/issues/3040)) ([5614339](https://github.com/appium/appium-xcuitest-driver/commit/561433953b5bfa940702917c9089bc1a5a6e1db8))
+
+## [12.18.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.17.3...v12.18.0) (2026-10-13)
+
+### Features
+
+* add asAppUnderTest flag in mobile: launchApp command ([#3004](https://github.com/appium/appium-xcuitest-driver/issues/3004)) ([7d1d611](https://github.com/appium/appium-xcuitest-driver/commit/7d1d6115cc1bb046071c792f47997d0deeb389cb))
+
+## [12.17.3](https://github.com/appium/appium-xcuitest-driver/compare/v12.17.2...v12.17.3) (2026-10-12)
+
+### Bug Fixes
+
+* make tunnel-creation exit on Ctrl+C ([#3033](https://github.com/appium/appium-xcuitest-driver/issues/3033)) ([1dde1ec](https://github.com/appium/appium-xcuitest-driver/commit/1dde1ec4589b416205729d943c7cf5ab9d286617))
+
+## [12.17.2](https://github.com/appium/appium-xcuitest-driver/compare/v12.17.1...v12.17.2) (2026-10-12)
+
+### Bug Fixes
+
+* track Apple TV tunnels by pair record UDID ([#3032](https://github.com/appium/appium-xcuitest-driver/issues/3032)) ([10e7d17](https://github.com/appium/appium-xcuitest-driver/commit/10e7d17f8eddc0ab9915987a8ebee75644e799bd))
+
+## [12.17.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.17.0...v12.17.1) (2026-10-10)
+
+### Bug Fixes
+
+* preserve recording aspect ratio and input frame rate ([#3010](https://github.com/appium/appium-xcuitest-driver/issues/3010)) ([caabeb3](https://github.com/appium/appium-xcuitest-driver/commit/caabeb39658bc9e7e13c6378cf76167e30b8e473))
+
+## [12.17.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.16.1...v12.17.0) (2026-10-10)
+
+### Features
+
+* add multi-display discovery and safe screenshot routing for Duo support ([#3013](https://github.com/appium/appium-xcuitest-driver/issues/3013)) ([0fac1ec](https://github.com/appium/appium-xcuitest-driver/commit/0fac1ecfcf3f1b11775d2a0785571caf26817eb1))
+
+## [12.16.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.16.0...v12.16.1) (2026-10-10)
+
+### Bug Fixes
+
+* pass value and maxAttempts of mobile selectPickerWheelValue to WDA ([#3017](https://github.com/appium/appium-xcuitest-driver/issues/3017)) ([ba9e634](https://github.com/appium/appium-xcuitest-driver/commit/ba9e6340b7a29b6430a9a2efc5260494cce20d62))
+
+## [12.16.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.15.2...v12.16.0) (2026-10-08)
+
+### Features
+
+* add simulated Duo hinge angle command ([#3001](https://github.com/appium/appium-xcuitest-driver/issues/3001)) ([3f4d513](https://github.com/appium/appium-xcuitest-driver/commit/3f4d513737d2583e333b27127a67c98c586b17fe))
+
+### Bug Fixes
+
+* refresh display geometry for viewport screenshots ([#3007](https://github.com/appium/appium-xcuitest-driver/issues/3007)) ([68d3103](https://github.com/appium/appium-xcuitest-driver/commit/68d3103bdfd892123922a506a4e6d6d125125b3a))
+
+## [12.15.2](https://github.com/appium/appium-xcuitest-driver/compare/v12.15.1...v12.15.2) (2026-10-07)
+
+### Bug Fixes
+
+* preserve app iframe selection after native tap calibration ([#3015](https://github.com/appium/appium-xcuitest-driver/issues/3015)) ([9de5422](https://github.com/appium/appium-xcuitest-driver/commit/9de5422ec99291e04566eba39b28a4f968721f8b))
+
+## [12.15.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.15.0...v12.15.1) (2026-10-07)
+
+### Bug Fixes
+
+* honor explicit MJPEG screenshot orientation correction ([#3008](https://github.com/appium/appium-xcuitest-driver/issues/3008)) ([4205137](https://github.com/appium/appium-xcuitest-driver/commit/42051377b3420655dc0f9b3b762df84bcf0e4c66))
+* include native geometry in web calibration cache ([#3009](https://github.com/appium/appium-xcuitest-driver/issues/3009)) ([c73578f](https://github.com/appium/appium-xcuitest-driver/commit/c73578fac918e8e3e1dadff8f0d62b8f3404a761))
+
+## [12.15.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.14.1...v12.15.0) (2026-10-03)
+
+### Features
+
+* support launching WDA on Duo ([#3000](https://github.com/appium/appium-xcuitest-driver/issues/3000)) ([a097de0](https://github.com/appium/appium-xcuitest-driver/commit/a097de0798995ffff1ee40882bab6a0e6eb430dd))
+
+## [12.14.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.14.0...v12.14.1) (2026-10-03)
+
+### Bug Fixes
+
+* merge tunnel and legacy device discovery ([#2991](https://github.com/appium/appium-xcuitest-driver/issues/2991)) ([77b451f](https://github.com/appium/appium-xcuitest-driver/commit/77b451fe482cf383b802ffde5068ee01f50e1cfd))
+
+## [12.14.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.13.3...v12.14.0) (2026-10-03)
+
+### Features
+
+* support simulatorPasteboardAutomaticSync and connect hardware preference for Device Hub ([#2999](https://github.com/appium/appium-xcuitest-driver/issues/2999)) ([3cda6b2](https://github.com/appium/appium-xcuitest-driver/commit/3cda6b203eaa9e497bc998748506ba75bc9e51f3))
+
+## [12.13.3](https://github.com/appium/appium-xcuitest-driver/compare/v12.13.2...v12.13.3) (2026-09-28)
+
+### Bug Fixes
+
+* bump WDA for package creation with Xcode 26+ ([#2996](https://github.com/appium/appium-xcuitest-driver/issues/2996)) ([b9750ba](https://github.com/appium/appium-xcuitest-driver/commit/b9750ba58bb490895bc0e1f5f0f9c027617c30b2))
+
+## [12.13.2](https://github.com/appium/appium-xcuitest-driver/compare/v12.13.1...v12.13.2) (2026-09-23)
+
+### Bug Fixes
+
+* grepFile error handling ([#2989](https://github.com/appium/appium-xcuitest-driver/issues/2989)) ([79b387b](https://github.com/appium/appium-xcuitest-driver/commit/79b387bbd9c8e265851fae91d555b798b528eb3e))
+
 ## [12.13.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.13.0...v12.13.1) (2026-09-20)
 
 ### Bug Fixes

docs/endpoints.md

@@ -16,7 +16,6 @@
 | GET    | /:sessionId                              | | |
 | DELETE | /:sessionId                              | | |
 | POST   | /timeouts                                | type, ms | |
-| POST   | /timeouts/async_script                   | ms | |
 | POST   | /timeouts/implicit_wait                  | ms | |
 | GET    | /window_handle                           | | |
 | GET    | /window_handles                          | | |
@@ -88,8 +87,6 @@
 | POST   | /appium/device/pull_file                 | path | |
 | POST   | /appium/device/pull_folder               | path | |
 | POST   | /appium/simulator/touch_id               | match | |
-| POST   | /appium/app/launch                       | none | |
-| POST   | /appium/app/close                        | none | |
 | POST   | /appium/app/background                   | seconds | |
 | POST   | /appium/app/strings                      | | language, stringFile |
 | POST   | /appium/element/:elementId/value         | value | |

docs/getting-started/provisioning-profile/generic-device-config.md

@@ -34,7 +34,7 @@ codesigning was not correct, the installation will fail.
 ## Using Appium-Provided Prebuilt WDA
 
 The Appium team distributes generic builds with `CODE_SIGNING_ALLOWED=NO` at
-[WebDriverAgent package releases](https://github.com/appium/WebDriverAgent/releases). These builds
+[WebDriverAgent package releases](../../guides/run-prebuilt-wda.md#download-prebuilt-wda-and-run-them-with-appiumprebuiltwdapath-and-appiumusepreinstalledwda). These builds
 must be codesigned first, after which they can be installed as described in the previous section.
 
 ## Signing WDA