appium-xcuitest-driver 12.13.0 → 12.13.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **opts:** pass `ActivateSuspended: true` to host opts for backgrounding WDA ([#2980](https://github.com/appium/appium-xcuitest-driver/issues/2980)) ([78361a2](https://github.com/appium/appium-xcuitest-driver/commit/78361a2cad2e66a34f64272113f519a35ce24407))
+
 ## [12.13.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.12.6...v12.13.0) (2026-09-20)
 
 ### Features

package/build/lib/device/log/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../lib/device/log/helpers.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,yBAAyB,CAAC;AAEtD,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,MAA0B,GAAG,QAAQ,CAM1G;AAED,6DAA6D;AAC7D,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBtG"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../lib/device/log/helpers.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,yBAAyB,CAAC;AAEtD,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,MAA0B,GAAG,QAAQ,CAM1G;AAED,6DAA6D;AAC7D,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiBtG"}

package/build/lib/device/log/helpers.js

@@ -17,6 +17,7 @@ export async function grepFile(fullPath, str, opts = {}) {
     const rl = createInterface({ input });
     return await new Promise((resolve, reject) => {
         input.once('error', reject);
+        rl.once('error', reject);
         rl.on('line', (line) => {
             if ((opts.caseInsensitive && line.toLowerCase().includes(String(str).toLowerCase())) ||
                 (!opts.caseInsensitive && line.includes(str))) {

package/build/lib/device/log/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../lib/device/log/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAC,EAAE,EAAC,MAAM,mBAAmB,CAAC;AAIrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAM9C,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,SAAiB,EAAE,QAAgB,iBAAiB;IAC9F,OAAO;QACL,SAAS;QACT,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,GAAW,EAAE,OAAoB,EAAE;IAClF,MAAM,KAAK,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,EAAE,GAAG,eAAe,CAAC,EAAC,KAAK,EAAC,CAAC,CAAC;IACpC,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACrB,IACE,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;gBAChF,CAAC,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC7C,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../lib/device/log/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAC,EAAE,EAAC,MAAM,mBAAmB,CAAC;AAIrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAM9C,wEAAwE;AACxE,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,SAAiB,EAAE,QAAgB,iBAAiB;IAC9F,OAAO;QACL,SAAS;QACT,KAAK;QACL,OAAO;KACR,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB,EAAE,GAAW,EAAE,OAAoB,EAAE;IAClF,MAAM,KAAK,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,EAAE,GAAG,eAAe,CAAC,EAAC,KAAK,EAAC,CAAC,CAAC;IACpC,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzB,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACrB,IACE,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;gBAChF,CAAC,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC7C,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/build/lib/device/wda-host-ops.js

@@ -105,11 +105,13 @@ function createSimulatorHostOps(driver) {
     };
 }
 /**
- * `devicectl device process launch` starts the XCTest runner as a plain app process, without the
- * testmanagerd/DVT test-session handshake that RemoteXPC's process control provides. Starting with
- * the iOS/tvOS 27 DDI/XCTest stack, the runner launched that way fails to background itself and
- * never starts its HTTP server, so devicectl is no longer a reliable launch fallback there (see
- * appium/appium#22636). It remains a reasonable fallback for older platforms.
+ * An XCTest runner started in the foreground has to press the Home button to background itself
+ * before running UI tests. With the Xcode 27 DDI/XCTest stack that synthesized press is ignored on
+ * older iOS versions, so the runner exits with "Failed to background test runner" and never starts
+ * its HTTP server (see appium/appium#22636 and #2978). RemoteXPC's process control launches the
+ * runner directly in the background, like Xcode does, which skips that step. `devicectl` always
+ * brings the runner to the foreground, so it is no longer a reliable launch fallback on
+ * iOS/tvOS 27+. It remains a reasonable fallback for older platforms.
  */
 function createRealDevicePreinstalledHostOps(driver) {
     return {
@@ -121,6 +123,7 @@ function createRealDevicePreinstalledHostOps(driver) {
                         bundleId,
                         environment: stringifyLaunchEnvironment(env),
                         killExisting: true,
+                        extraOptions: { ActivateSuspended: true },
                     });
                 }
                 finally {

package/build/lib/device/wda-host-ops.js.map

@@ -1 +1 @@
-{"version":3,"file":"wda-host-ops.js","sourceRoot":"","sources":["../../../lib/device/wda-host-ops.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wda-host-ops.js","sourceRoot":"","sources":["../../../lib/device/wda-host-ops.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,kBAAkB,EAAE,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAGzE,MAAM,eAAe,GAAG;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,kBAAkB;IAClB,qCAAqC;IACrC,kBAAkB;CACV,CAAC;AAUX;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAsB,EAAE,WAA4B,OAAO,CAAC,QAAQ;IAC1G,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,kBAAkB,CAAC,CAAC;AAC7F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iCAAiC,CAC/C,IAAsB,EACtB,WAA4B,OAAO,CAAC,QAAQ;IAE5C,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE;YAClE,mFAAmF;YACnF,2CAA2C,QAAQ,IAAI,CAC1D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,0BAA0B,QAAQ,yDAAyD;YACzF,kFAAkF,CACrF,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CACb,6CAA6C,QAAQ,sCAAsC;YACzF,wFAAwF,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClF,IAAI,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CACb,6EAA6E;YAC3E,sDAAsD,QAAQ,KAAK;YACnE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAC3B,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACrD,OAAO;QACL,SAAS,EAAE,sBAAsB,CAAC,MAAM,CAAC;QACzC,sBAAsB,EAAE,mCAAmC,CAAC,MAAM,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAAsB;IACnE,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO;IACT,CAAC;IAED,iCAAiC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE/C,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAClC,OAAO;IACT,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,wDAAwD;YACtD,2FAA2F;YAC3F,gBAAgB,OAAO,CAAC,QAAQ,IAAI,CACvC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,qFAAqF;YACnF,mFAAmF;YACnF,2CAA2C,OAAO,CAAC,QAAQ,IAAI,CAClE,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9G,MAAM,IAAI,KAAK,CACb,6CAA6C,OAAO,CAAC,QAAQ,2BAA2B;YACtF,gEAAgE;YAChE,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,4CAA4C;YAC3E,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,qEAAqE,OAAO,CAAC,QAAQ,KAAK;YACxF,iDAAiD,CACpD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,0BAA0B,CAAC,GAAyB;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAyB,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC9E,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC,EAAE,EAAE,CAAC,CAAC;AACT,CAAC;AAED,SAAS,sBAAsB,CAAC,MAAsB;IACpD,OAAO;QACL,KAAK,CAAC,kBAAkB,CAAC,EAAC,QAAQ,EAAE,GAAG,EAAC;YACtC,MAAO,MAAM,CAAC,MAAoB,CAAC,SAAS,CAAC,QAAQ,EAAE;gBACrD,WAAW,EAAE,0BAA0B,CAAC,GAAG,CAAC;gBAC5C,iBAAiB,EAAE,IAAI;aACxB,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,EAAC,QAAQ,EAAC;YACxB,MAAO,MAAM,CAAC,MAAoB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC5D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,mCAAmC,CAAC,MAAsB;IACjE,OAAO;QACL,KAAK,CAAC,kBAAkB,CAAC,EAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,oCAAoC,EAAE,CAAC,QAAQ,EAAE,EAAE,CACzG,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAC/B,CAAC;gBACF,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC;wBAC9B,QAAQ;wBACR,WAAW,EAAE,0BAA0B,CAAC,GAAG,CAAC;wBAC5C,YAAY,EAAE,IAAI;wBAClB,YAAY,EAAE,EAAC,iBAAiB,EAAE,IAAI,EAAC;qBACxC,CAAC,CAAC;gBACL,CAAC;wBAAS,CAAC;oBACT,MAAM,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC/B,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;oBACpD,MAAM,IAAI,KAAK,CAAC,mEAAoE,GAAa,CAAC,OAAO,EAAE,EAAE;wBAC3G,KAAK,EAAE,GAAG;qBACX,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBAClC,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,CAAC,GAAG,CAAC,IAAI,CACb,8DAA8D;oBAC5D,8CAA+C,GAAa,CAAC,OAAO,EAAE,CACzE,CAAC;gBACF,MAAM,EAAC,SAAS,EAAC,GAAG,MAAM,CAAC,MAAoB,CAAC;gBAChD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE;oBAClC,GAAG;oBACH,iBAAiB,EAAE,IAAI;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,EAAC,IAAI,EAAE,QAAQ,EAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,uCAAuC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAC5G,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAC/B,CAAC;gBACF,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC;oBACzE,IAAI,CAAC,GAAG,EAAE,CAAC;wBACT,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,4CAA4C,QAAQ,mBAAmB,CAAC,CAAC;wBACzF,OAAO;oBACT,CAAC;oBACD,MAAM,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACrC,CAAC;wBAAS,CAAC;oBACT,MAAM,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC/B,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBAClC,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,CAAC,GAAG,CAAC,IAAI,CACb,iEAAiE;oBAC/D,8CAA+C,GAAa,CAAC,OAAO,EAAE,CACzE,CAAC;gBACF,MAAM,EAAC,SAAS,EAAC,GAAG,MAAM,CAAC,MAAoB,CAAC;gBAChD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,MAAM,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/device/log/helpers.ts

@@ -27,6 +27,7 @@ export async function grepFile(fullPath: string, str: string, opts: GrepOptions
   const rl = createInterface({input});
   return await new Promise((resolve, reject) => {
     input.once('error', reject);
+    rl.once('error', reject);
     rl.on('line', (line) => {
       if (
         (opts.caseInsensitive && line.toLowerCase().includes(String(str).toLowerCase())) ||

package/lib/device/wda-host-ops.ts

@@ -161,11 +161,13 @@ function createSimulatorHostOps(driver: XCUITestDriver): SimulatorHostOps {
 }
 
 /**
- * `devicectl device process launch` starts the XCTest runner as a plain app process, without the
- * testmanagerd/DVT test-session handshake that RemoteXPC's process control provides. Starting with
- * the iOS/tvOS 27 DDI/XCTest stack, the runner launched that way fails to background itself and
- * never starts its HTTP server, so devicectl is no longer a reliable launch fallback there (see
- * appium/appium#22636). It remains a reasonable fallback for older platforms.
+ * An XCTest runner started in the foreground has to press the Home button to background itself
+ * before running UI tests. With the Xcode 27 DDI/XCTest stack that synthesized press is ignored on
+ * older iOS versions, so the runner exits with "Failed to background test runner" and never starts
+ * its HTTP server (see appium/appium#22636 and #2978). RemoteXPC's process control launches the
+ * runner directly in the background, like Xcode does, which skips that step. `devicectl` always
+ * brings the runner to the foreground, so it is no longer a reliable launch fallback on
+ * iOS/tvOS 27+. It remains a reasonable fallback for older platforms.
  */
 function createRealDevicePreinstalledHostOps(driver: XCUITestDriver): RealDevicePreinstalledHostOps {
   return {
@@ -179,6 +181,7 @@ function createRealDevicePreinstalledHostOps(driver: XCUITestDriver): RealDevice
             bundleId,
             environment: stringifyLaunchEnvironment(env),
             killExisting: true,
+            extraOptions: {ActivateSuspended: true},
           });
         } finally {
           await dvt.dvtService.close();

package/node_modules/@appium/coresim/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [1.7.0](https://github.com/appium/coresim/compare/v1.6.0...v1.7.0) (2026-09-23)
+
+### Features
+
+* add force option to stopVideoRecording ([#19](https://github.com/appium/coresim/issues/19)) ([1b756ce](https://github.com/appium/coresim/commit/1b756ce3d41ad35dca0f7448de82715570e6ce60))
+
+## [1.6.0](https://github.com/appium/coresim/compare/v1.5.0...v1.6.0) (2026-09-23)
+
+### Features
+
+* add optional audio capture to video recording and streaming  ([#18](https://github.com/appium/coresim/issues/18)) ([e634078](https://github.com/appium/coresim/commit/e634078669db724a676bf95fa074a89d3ac5a9c8))
+
+## [1.5.0](https://github.com/appium/coresim/compare/v1.4.0...v1.5.0) (2026-09-22)
+
+### Features
+
+* Add video recording API ([#17](https://github.com/appium/coresim/issues/17)) ([d399403](https://github.com/appium/coresim/commit/d399403c1d329f303ab51726fa382313cf09ad0f))
+
 ## [1.4.0](https://github.com/appium/coresim/compare/v1.3.0...v1.4.0) (2026-09-19)
 
 ### Features

package/node_modules/@appium/coresim/README.md

@@ -54,6 +54,20 @@ await sim.deleteDevice(device.udid);
   readiness with `getBootStatus()`/`waitForBoot()`.
 - **Apps** — install, remove, launch, terminate, and inspect apps.
 - **Processes** — spawn a process on the simulator and stream its stdout/stderr live.
+- **Screen capture** — screenshots, video recording to a file, and a real-time encoded video
+  stream — optionally with the device's own audio, muxed into the recording or interleaved into
+  the stream (`audio: true` on `startVideoRecording`/`startVideoStream`). Audio capture requires:
+  - **macOS 14.2+** on the host (Core Audio process taps).
+  - The host's **"System Audio Recording Only"** privacy permission (System Settings > Privacy &
+    Security > Screen & System Audio Recording). This can't be granted programmatically, and a
+    denial isn't a thrown error — it silently produces an audio-less/near-silent track.
+  - A default audio output device on the host, and a booted simulator that has produced audio at
+    least once (e.g. a foreground app that plays sound) — an empty guest process set throws.
+  - Uses a host-side Core Audio API, not anything iOS-version-specific, so it's expected to work
+    on any simulator runtime; only Xcode 26.x has actually been exercised so far.
+
+  On some CI/headless hosts, starting an audio capture can block for a while before failing —
+  see [`CLAUDE.md`](./CLAUDE.md) for the known root cause and current workaround.
 - **Simulator settings** — appearance (light/dark), accessibility (increase contrast, content
   size), location, and permissions.
 - **Extras** — keychain certificates, push notifications, and Darwin notifications.

package/node_modules/@appium/coresim/binding.gyp

@@ -13,7 +13,14 @@
         "src/native/tcc_privacy.mm",
         "src/native/sim_pasteboard.mm",
         "src/native/sim_process.mm",
-        "src/native/sim_screenshot.mm"
+        "src/native/sim_audio_tap.mm",
+        "src/native/audio_encoder.mm",
+        "src/native/av_recording.mm",
+        "src/native/av_stream.mm",
+        "src/native/sim_screenshot.mm",
+        "src/native/sim_video_recording.mm",
+        "src/native/video_encoder.mm",
+        "src/native/sim_video_stream.mm"
       ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")"
@@ -42,9 +49,15 @@
         "OTHER_LDFLAGS": [
           "-framework", "Foundation",
           "-framework", "AppKit",
+          "-framework", "AudioToolbox",
+          "-framework", "AVFoundation",
+          "-framework", "CoreAudio",
           "-framework", "CoreImage",
+          "-framework", "CoreMedia",
+          "-framework", "CoreVideo",
           "-framework", "ImageIO",
           "-framework", "IOSurface",
+          "-framework", "VideoToolbox",
           "-lsqlite3"
         ]
       }

package/node_modules/@appium/coresim/lib/src/commands/video-recording.d.ts

@@ -0,0 +1,66 @@
+import type { NativeSimctl } from '../native-simctl.js';
+import type { StopVideoRecordingOptions, VideoRecordingOptions } from '../types.js';
+declare module '../native-simctl.js' {
+    interface NativeSimctl {
+        startVideoRecording(udid: string, outputFile: string, options?: VideoRecordingOptions): Promise<void>;
+        stopVideoRecording(udid: string, options?: StopVideoRecordingOptions): Promise<void>;
+        isVideoRecording(udid: string): Promise<boolean>;
+    }
+}
+/**
+ * Starts recording the device's display (and, with `options.audio`, its audio too, muxed as a
+ * second track) to `outputFile` — the native equivalent of `simctl io <udid> recordVideo` when
+ * both `audio` and `fps` are unset. Resolves once the first frame has actually been recorded, so
+ * it's always safe to call {@link stopVideoRecording} immediately after. Only one recording may be
+ * active per device at a time; starting a second one while the first is still running rejects.
+ *
+ * Without `audio`/`fps`, rejects with `NativeSimUnavailableError` if this CoreSimulator predates
+ * the private capture API — confirmed missing on Xcode 16.4's, present on Xcode 26.5+ (Apple
+ * documents no exact version floor). With either set, see {@link VideoRecordingOptions.audio}'s
+ * own doc comment for the host-permission requirement that applies specifically to `audio`; a
+ * failure *after* this call has already resolved (e.g. the audio tap's guest process set vanishing
+ * mid-recording) doesn't reject it — it's logged here instead — call {@link stopVideoRecording} to
+ * observe it as a rejection and release the recording's resources.
+ *
+ * @param udid — UDID of the device to record; must be booted
+ * @param outputFile — filesystem path to write the video to; resolved against `process.cwd()` if
+ *   relative, since the native layer requires an absolute path
+ * @param options — `displayId`, `codec`, `mask`, `audio`, `fps`, `bitrate` — see {@link VideoRecordingOptions}
+ * @throws {Error} if a recording is already in progress for this device
+ */
+export declare function startVideoRecording(this: NativeSimctl, udid: string, outputFile: string, options?: VideoRecordingOptions): Promise<void>;
+/**
+ * Stops a recording previously started by {@link startVideoRecording} on the same device.
+ * Resolves once the video file has been finalized on disk and is safe to read. If `start` is still
+ * in flight (e.g. a concurrent caller stopping as soon as {@link isVideoRecording} turns `true`),
+ * waits for it to settle first — issuing the native stop call any earlier is a silent CoreSimulator
+ * race (see CLAUDE.md).
+ *
+ * Safe to call concurrently or to retry after a failure: every concurrent call for the same
+ * recording shares a single in-flight native stop call rather than each issuing its own (which
+ * could otherwise stop whatever *new* recording has since started on this device instead), and a
+ * failed stop — even one that failed before ever reaching the native recorder, e.g. a transient
+ * device-lookup error — leaves the recording tracked as still active so a retry can reach the
+ * native call rather than the caller losing the ability to stop it at all.
+ *
+ * That retryability is a liability if nothing ever *does* retry — e.g. a best-effort teardown path
+ * that must not throw, so it logs a failed stop and moves on — since without `options.force` there
+ * is no other way to release the entry, permanently blocking a new `startVideoRecording` for this
+ * device. Pass `options.force: true` in that situation: it still attempts the native stop (so the
+ * encoder/file gets a chance to finalize cleanly) but releases the entry unconditionally afterward
+ * and never rejects, even if that attempt failed — understand that this can leave a native
+ * resource dangling if the stop genuinely never lands.
+ *
+ * @param udid — UDID of the device to stop recording
+ * @param options — `force` (see above)
+ * @throws {Error} if no recording is currently in progress for this device
+ */
+export declare function stopVideoRecording(this: NativeSimctl, udid: string, options?: StopVideoRecordingOptions): Promise<void>;
+/**
+ * Whether a recording started by {@link startVideoRecording} is currently active for this device.
+ * Pure local state — no CoreSimulator dispatch — so this never rejects with a native error.
+ *
+ * @param udid — UDID of the device to check
+ */
+export declare function isVideoRecording(this: NativeSimctl, udid: string): Promise<boolean>;
+//# sourceMappingURL=video-recording.d.ts.map

package/node_modules/@appium/coresim/lib/src/commands/video-recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-recording.d.ts","sourceRoot":"","sources":["../../../src/commands/video-recording.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAA6B,yBAAyB,EAAE,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAG9G,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,YAAY;QACpB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACtG,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACrF,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KAClD;CACF;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF"}

package/node_modules/@appium/coresim/lib/src/commands/video-recording.js

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import { logger } from '@appium/support';
+import { runCatchingAsync, toTypedError } from '../utils/index.js';
+const log = logger.getLogger('CoreSim');
+// Tracks which devices currently have an active recording — module-level since the constraint (at
+// most one per device) is CoreSimulator's own, not per-NativeSimctl-instance.
+const activeRecordings = new Map();
+/**
+ * Starts recording the device's display (and, with `options.audio`, its audio too, muxed as a
+ * second track) to `outputFile` — the native equivalent of `simctl io <udid> recordVideo` when
+ * both `audio` and `fps` are unset. Resolves once the first frame has actually been recorded, so
+ * it's always safe to call {@link stopVideoRecording} immediately after. Only one recording may be
+ * active per device at a time; starting a second one while the first is still running rejects.
+ *
+ * Without `audio`/`fps`, rejects with `NativeSimUnavailableError` if this CoreSimulator predates
+ * the private capture API — confirmed missing on Xcode 16.4's, present on Xcode 26.5+ (Apple
+ * documents no exact version floor). With either set, see {@link VideoRecordingOptions.audio}'s
+ * own doc comment for the host-permission requirement that applies specifically to `audio`; a
+ * failure *after* this call has already resolved (e.g. the audio tap's guest process set vanishing
+ * mid-recording) doesn't reject it — it's logged here instead — call {@link stopVideoRecording} to
+ * observe it as a rejection and release the recording's resources.
+ *
+ * @param udid — UDID of the device to record; must be booted
+ * @param outputFile — filesystem path to write the video to; resolved against `process.cwd()` if
+ *   relative, since the native layer requires an absolute path
+ * @param options — `displayId`, `codec`, `mask`, `audio`, `fps`, `bitrate` — see {@link VideoRecordingOptions}
+ * @throws {Error} if a recording is already in progress for this device
+ */
+export async function startVideoRecording(udid, outputFile, options = {}) {
+    // Mirrors startVideoStream's identical validation — both reach the same native encoder path,
+    // which otherwise silently truncates an out-of-range value instead of rejecting it.
+    if (options.fps !== undefined && (!Number.isFinite(options.fps) || options.fps < 1)) {
+        throw new RangeError(`fps must be a finite number >= 1, got ${options.fps}`);
+    }
+    if (options.bitrate !== undefined &&
+        (!Number.isFinite(options.bitrate) || options.bitrate <= 0 || options.bitrate > 2 ** 31 - 1)) {
+        throw new RangeError(`bitrate must be a positive number no greater than ${2 ** 31 - 1}, got ${options.bitrate}`);
+    }
+    const key = udid.toLowerCase();
+    if (activeRecordings.has(key)) {
+        throw new Error(`A video recording is already in progress for device '${udid}'`);
+    }
+    const absoluteOutputFile = path.resolve(outputFile);
+    const startPromise = runCatchingAsync(async () => (await this._findDevice(udid)).startVideoRecording(absoluteOutputFile, options, (err) => {
+        // Only ever invoked on the `audio`/`fps` (own-encoder) path — see its own doc comment above.
+        // No live consumer to report to (this call already resolved), so logged instead of lost.
+        log.error(`Unhandled video recording error for device '${udid}': ${toTypedError(err).stack ?? err}`);
+    }));
+    // Marked before the native call resolves, not after, so a concurrent startVideoRecording for the
+    // same device is rejected immediately instead of racing this one — rolled back below on failure.
+    const state = { start: startPromise };
+    activeRecordings.set(key, state);
+    try {
+        await startPromise;
+    }
+    catch (e) {
+        // Only clear our own entry — a concurrent stopVideoRecording (see below) may already have.
+        if (activeRecordings.get(key) === state) {
+            activeRecordings.delete(key);
+        }
+        throw e;
+    }
+}
+/**
+ * Stops a recording previously started by {@link startVideoRecording} on the same device.
+ * Resolves once the video file has been finalized on disk and is safe to read. If `start` is still
+ * in flight (e.g. a concurrent caller stopping as soon as {@link isVideoRecording} turns `true`),
+ * waits for it to settle first — issuing the native stop call any earlier is a silent CoreSimulator
+ * race (see CLAUDE.md).
+ *
+ * Safe to call concurrently or to retry after a failure: every concurrent call for the same
+ * recording shares a single in-flight native stop call rather than each issuing its own (which
+ * could otherwise stop whatever *new* recording has since started on this device instead), and a
+ * failed stop — even one that failed before ever reaching the native recorder, e.g. a transient
+ * device-lookup error — leaves the recording tracked as still active so a retry can reach the
+ * native call rather than the caller losing the ability to stop it at all.
+ *
+ * That retryability is a liability if nothing ever *does* retry — e.g. a best-effort teardown path
+ * that must not throw, so it logs a failed stop and moves on — since without `options.force` there
+ * is no other way to release the entry, permanently blocking a new `startVideoRecording` for this
+ * device. Pass `options.force: true` in that situation: it still attempts the native stop (so the
+ * encoder/file gets a chance to finalize cleanly) but releases the entry unconditionally afterward
+ * and never rejects, even if that attempt failed — understand that this can leave a native
+ * resource dangling if the stop genuinely never lands.
+ *
+ * @param udid — UDID of the device to stop recording
+ * @param options — `force` (see above)
+ * @throws {Error} if no recording is currently in progress for this device
+ */
+export async function stopVideoRecording(udid, options = {}) {
+    const key = udid.toLowerCase();
+    const state = activeRecordings.get(key);
+    if (!state) {
+        throw new Error(`No video recording is in progress for device '${udid}'`);
+    }
+    let handle;
+    try {
+        handle = await state.start;
+    }
+    catch {
+        // start itself failed — its own catch already cleaned up activeRecordings; nothing to stop.
+        throw new Error(`No video recording is in progress for device '${udid}'`);
+    }
+    const stopPromise = (state.stop ??= runCatchingAsync(async () => {
+        await handle.stop();
+    }));
+    try {
+        await stopPromise;
+    }
+    catch (e) {
+        // Only clear our own attempt, and only if it's still the current one — a future (non-forced)
+        // call must be able to retry the native stop rather than replaying this same rejection
+        // forever, but must not clobber a newer attempt another concurrent caller may have already
+        // started instead.
+        if (state.stop === stopPromise) {
+            state.stop = undefined;
+        }
+        if (!options.force) {
+            throw e;
+        }
+        log.warn(`Force-releasing video recording bookkeeping for device '${udid}' despite a failed native stop: ` +
+            `${toTypedError(e).stack ?? e}`);
+    }
+    if (activeRecordings.get(key) === state) {
+        activeRecordings.delete(key);
+    }
+}
+/**
+ * Whether a recording started by {@link startVideoRecording} is currently active for this device.
+ * Pure local state — no CoreSimulator dispatch — so this never rejects with a native error.
+ *
+ * @param udid — UDID of the device to check
+ */
+export async function isVideoRecording(udid) {
+    return activeRecordings.has(udid.toLowerCase());
+}
+//# sourceMappingURL=video-recording.js.map

package/node_modules/@appium/coresim/lib/src/commands/video-recording.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-recording.js","sourceRoot":"","sources":["../../../src/commands/video-recording.ts"],"names":[],"mappings":"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"}

package/node_modules/@appium/coresim/lib/src/commands/video-stream.d.ts

@@ -0,0 +1,92 @@
+import { EventEmitter } from 'node:events';
+import type { NativeSimctl } from '../native-simctl.js';
+import type { VideoAccessUnit, VideoStreamOptions } from '../types.js';
+declare module '../native-simctl.js' {
+    interface NativeSimctl {
+        startVideoStream(udid: string, options?: VideoStreamOptions): Promise<VideoStream>;
+    }
+}
+export declare const MAX_BUFFERED_UNITS = 60;
+/**
+ * Single-consumer FIFO between native's per-frame callback and `accessUnits()`. Unlike routing
+ * through `EventEmitter`, a unit pushed before any consumer has started iterating is retained
+ * (fixing the encoder's own first-frame/keyframe otherwise being lost to a startup race) rather
+ * than silently dropped.
+ *
+ * Bounded at `MAX_BUFFERED_UNITS`, but resync-aware about *how* it sheds load once a slow consumer
+ * falls behind: since interframes only reference earlier frames they were encoded against (no
+ * `AllowFrameReordering`), dropping an arbitrary one would orphan every later one from its
+ * reference chain, corrupting decode from that point on even though delivery looks unbroken.
+ * Overflow instead clears the backlog entirely and enters a resync state — `dropsDuringResync`
+ * decides which further units to discard (not buffer) until `endsResync` sees a self-decodable
+ * point to resume clean delivery from. Generic (not hardcoded to video's own reference-chain
+ * concern) so `VideoStream` can reuse this same machinery when it's carrying interleaved audio
+ * too (`VideoStreamOptions.audio`) — an audio unit is always independently decodable, so it's
+ * configured to never be dropped and never itself end a resync; only video interframes are.
+ */
+export declare class AccessUnitQueue<T> {
+    private readonly opts;
+    private readonly buffer;
+    private waiter;
+    private ended;
+    private error;
+    private resyncing;
+    constructor(opts: {
+        /** Whether `unit` should be discarded (not buffered) while resyncing. */
+        dropsDuringResync: (unit: T) => boolean;
+        /** Whether `unit` is a self-decodable point resync can resume clean delivery from. */
+        endsResync: (unit: T) => boolean;
+        /** Called once when overflow first forces a resync, e.g. to request a fresh keyframe. */
+        onOverflow?: () => void;
+    });
+    push(unit: T): void;
+    /** Ends the queue with an error — any pending or future `next()` rejects with it. */
+    fail(err: unknown): void;
+    /** Ends the queue cleanly — any pending or future `next()` resolves `done`. */
+    end(): void;
+    /**
+     * Resolves `done` (not rejects) if `signal` aborts while waiting, mirroring `events.on()`.
+     * Checks cancellation/end *before* dequeuing, so an already-aborted signal or an already-ended
+     * queue never hands out a stale buffered unit — an aborted consumer, or a fresh iterator started
+     * after `stop()`, must see the boundary immediately rather than draining leftovers first.
+     */
+    next(signal: AbortSignal): Promise<IteratorResult<T>>;
+}
+/**
+ * A live video stream from `NativeSimctl.startVideoStream` — encodes the device's display (and,
+ * with `options.audio`, its audio too — see {@link VideoStreamOptions}) in real time via
+ * VideoToolbox/Core Audio, unlike `startVideoRecording`, which drives CoreSimulator's own private,
+ * file-only recorder. Mirrors `appium-ios-remotexpc`'s `ScreenStreamCapture` shape
+ * (`accessUnits()`/`stop()`) for API consistency; the transport is otherwise unrelated.
+ */
+export declare class VideoStream extends EventEmitter {
+    readonly codec: 'h264' | 'hevc';
+    private handle;
+    private readonly stopController;
+    private stopPromise;
+    private readonly queue;
+    private activeConsumers;
+    /**
+     * Yields each encoded access unit as it's produced, until {@link stop} is called or the stream
+     * errors (in which case the error is thrown out of the loop). Pass `signal` to stop iterating
+     * without treating that as an error. Mirrors `ScreenStreamCapture.accessUnits()`'s shape.
+     *
+     * Only one active consumer is supported at a time — a second concurrent call rejects rather
+     * than silently sharing (and corrupting) the first one's single internal waiter slot.
+     */
+    accessUnits(signal?: AbortSignal): AsyncGenerator<VideoAccessUnit>;
+    /** Stops the stream and releases the underlying encoder. Idempotent, including concurrently. */
+    stop(): Promise<void>;
+}
+/**
+ * Starts encoding the device's display (and, with `options.audio`, its audio) in real time.
+ * Resolves once the encoder(s) have actually started; the returned {@link VideoStream}'s
+ * `accessUnits()` then yields each unit as it arrives. Independent of
+ * `startVideoRecording`/`stopVideoRecording` — both, and any number of concurrent streams, can
+ * run on the same device at once.
+ *
+ * @param udid — UDID of the device to stream; must be booted
+ * @param options — `displayId`, `codec`, `fps`, `bitrate`, `audio` — see {@link VideoStreamOptions}
+ */
+export declare function startVideoStream(this: NativeSimctl, udid: string, options?: VideoStreamOptions): Promise<VideoStream>;
+//# sourceMappingURL=video-stream.d.ts.map

package/node_modules/@appium/coresim/lib/src/commands/video-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stream.d.ts","sourceRoot":"","sources":["../../../src/commands/video-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAIzC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAA0B,eAAe,EAAE,kBAAkB,EAAC,MAAM,aAAa,CAAC;AAG9F,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,YAAY;QACpB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;KACpF;CACF;AASD,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAKrC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe,CAAC,CAAC;IAQ1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,MAAM,CAA6F;IAC3G,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,SAAS,CAAS;gBAGP,IAAI,EAAE;QACrB,yEAAyE;QACzE,iBAAiB,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;QACxC,sFAAsF;QACtF,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;QACjC,yFAAyF;QACzF,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;KACzB;IAGH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IA0BnB,qFAAqF;IACrF,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAcxB,+EAA+E;IAC/E,GAAG,IAAI,IAAI;IAaX;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;CA6BtD;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,YAAY;aAiBf,KAAK,EAAE,MAAM,GAAG,MAAM;IAhBlD,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,WAAW,CAA4B;IAM/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAInB;IACH,OAAO,CAAC,eAAe,CAAK;IAiC5B;;;;;;;OAOG;IACI,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,eAAe,CAAC;IAmBzE,gGAAgG;IAC1F,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAuBtB"}