appium-xcuitest-driver 12.13.1 → 12.13.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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/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/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"}