@appium/coresim 1.11.1 → 1.13.0

package/src/commands/permissions.ts

@@ -1,14 +1,34 @@
+import {execFile} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {once} from 'node:events';
+import path from 'node:path';
+import {promisify} from 'node:util';
+
+import {fs, plist} from '@appium/support';
+import {waitForCondition} from 'asyncbox';
+
 import type {NativeSimctl} from '../native-simctl.js';
-import type {SimPermissionService, SimPermissionStatus} from '../types.js';
+import {SimDeviceState, type SimPermissionService, type SimPermissionStatus} from '../types.js';
 import {runCatchingAsync} from '../utils/index.js';
 
+const execFileAsync = promisify(execFile);
+
+const NOTIFICATIONS_SERVICE = 'notifications';
+const SPRINGBOARD_SERVICE = 'com.apple.SpringBoard';
+// The `sectionInfoVersionNumber` of the BulletinBoard stores SpringBoard writes (iOS 18 and 26).
+const BULLETIN_BOARD_STORE_VERSION = 2;
+const SPRINGBOARD_RESTART_TIMEOUT_MS = 30000;
+
+// The last pending notifications update of each BulletinBoard store, see withStoreLock.
+const storeUpdates = new Map<string, Promise<void>>();
+
 declare module '../native-simctl.js' {
   interface NativeSimctl {
     grantPermission(
       udid: string,
       service: SimPermissionService,
       bundleId: string,
-      status?: 'granted' | 'limited',
+      status?: 'granted' | 'limited' | 'critical',
     ): Promise<void>;
     revokePermission(udid: string, service: SimPermissionService, bundleId: string): Promise<void>;
     resetPermission(udid: string, service: SimPermissionService, bundleId: string): Promise<void>;
@@ -21,30 +41,41 @@ declare module '../native-simctl.js' {
  * simulator's own TCC (privacy) database — see CLAUDE.md for why this bypasses CoreSimulator's own
  * privacy API.
  *
+ * `notifications` isn't a TCC row: it is written to SpringBoard's BulletinBoard store instead. On a
+ * booted device SpringBoard is restarted to load it, which terminates every running app; a shut down
+ * device picks it up on its next boot.
+ *
  * @param udid — UDID of the target device
- * @param service — permission to grant, e.g. `"camera"`, `"contacts"`, `"photos"`
+ * @param service — permission to grant, e.g. `"camera"`, `"contacts"`, `"photos"`, `"notifications"`
  * @param bundleId — bundle identifier of the app the permission applies to
  * @param status — defaults to `'granted'`. `'limited'` ("selected photos" access) is only valid
- * for the `photos` service.
+ * for the `photos` service, `'critical'` (critical alerts allowed too) — for `notifications`.
  */
 export async function grantPermission(
   this: NativeSimctl,
   udid: string,
   service: SimPermissionService,
   bundleId: string,
-  status: 'granted' | 'limited' = 'granted',
+  status: 'granted' | 'limited' | 'critical' = 'granted',
 ): Promise<void> {
   return runCatchingAsync(async () => {
     if (status === 'limited' && service !== 'photos') {
       throw new Error(`'limited' is only a valid status for the 'photos' service, not '${service}'`);
     }
+    if (service === NOTIFICATIONS_SERVICE) {
+      return await setNotificationsAccess.call(this, udid, bundleId, status === 'critical' ? 'critical' : 'granted');
+    }
+    if (status === 'critical') {
+      throw new Error(`'critical' is only a valid status for the 'notifications' service, not '${service}'`);
+    }
     const tccIdentifier = toTCCIdentifier(service);
     return (await this._findDevice(udid)).grantPermission(tccIdentifier, bundleId, status);
   });
 }
 
 /**
- * Revokes a previously granted privacy permission from the given app.
+ * Revokes a previously granted privacy permission from the given app. For `notifications`, a booted
+ * device's SpringBoard is restarted, see {@link grantPermission}.
  *
  * @param udid — UDID of the target device
  * @param service — permission to revoke (see {@link grantPermission})
@@ -57,13 +88,18 @@ export async function revokePermission(
   bundleId: string,
 ): Promise<void> {
   return runCatchingAsync(async () => {
+    if (service === NOTIFICATIONS_SERVICE) {
+      return await setNotificationsAccess.call(this, udid, bundleId, 'denied');
+    }
     const tccIdentifier = toTCCIdentifier(service);
     return (await this._findDevice(udid)).revokePermission(tccIdentifier, bundleId);
   });
 }
 
 /**
- * Resets a privacy permission for the given app to its default (unprompted) state.
+ * Resets a privacy permission for the given app to its default (unprompted) state. For
+ * `notifications`, the app's section is removed from SpringBoard's store and a booted device's
+ * SpringBoard is restarted, see {@link grantPermission}.
  *
  * @param udid — UDID of the target device
  * @param service — permission to reset (see {@link grantPermission})
@@ -76,6 +112,9 @@ export async function resetPermission(
   bundleId: string,
 ): Promise<void> {
   return runCatchingAsync(async () => {
+    if (service === NOTIFICATIONS_SERVICE) {
+      return await setNotificationsAccess.call(this, udid, bundleId, 'unset');
+    }
     const tccIdentifier = toTCCIdentifier(service);
     return (await this._findDevice(udid)).resetPermission(tccIdentifier, bundleId);
   });
@@ -90,6 +129,7 @@ export async function resetPermission(
  * @param service — permission to check (see {@link grantPermission})
  * @param bundleId — bundle identifier of the app the permission applies to
  * @returns `'unset'` if the app has never been prompted/decided for this permission
+ * @throws {Error} for `notifications`: reading it isn't supported
  */
 export async function getPermission(
   this: NativeSimctl,
@@ -98,6 +138,9 @@ export async function getPermission(
   bundleId: string,
 ): Promise<SimPermissionStatus> {
   return runCatchingAsync(async () => {
+    if (service === NOTIFICATIONS_SERVICE) {
+      throw new Error(`The status of the '${NOTIFICATIONS_SERVICE}' permission cannot be read`);
+    }
     const tccIdentifier = toTCCIdentifier(service);
     return (await this._findDevice(udid)).getPermission(tccIdentifier, bundleId);
   });
@@ -106,8 +149,8 @@ export async function getPermission(
 // Maps a friendly service name to the internal TCC service identifier its row in the simulator's
 // own TCC.db is keyed on (see native/tcc_privacy.h). `location` is deliberately absent: it isn't a
 // plain TCC row (CoreLocation simulation has its own subsystem), so it isn't supported by this
-// TCC.db-based implementation.
-const SERVICE_TO_TCC_IDENTIFIER: Record<SimPermissionService, string> = {
+// TCC.db-based implementation. `notifications` isn't a TCC row either, see setNotificationsAccess.
+const SERVICE_TO_TCC_IDENTIFIER: Record<Exclude<SimPermissionService, 'notifications'>, string> = {
   calendar: 'kTCCServiceCalendar',
   camera: 'kTCCServiceCamera',
   contacts: 'kTCCServiceAddressBook',
@@ -124,7 +167,7 @@ const SERVICE_TO_TCC_IDENTIFIER: Record<SimPermissionService, string> = {
   usertracking: 'kTCCServiceUserTracking',
 };
 
-function toTCCIdentifier(service: SimPermissionService): string {
+function toTCCIdentifier(service: Exclude<SimPermissionService, 'notifications'>): string {
   const identifier = SERVICE_TO_TCC_IDENTIFIER[service];
   if (!identifier) {
     throw new Error(
@@ -133,3 +176,274 @@ function toTCCIdentifier(service: SimPermissionService): string {
   }
   return identifier;
 }
+
+/**
+ * `notifications` isn't a TCC row: SpringBoard keeps it per app in its BulletinBoard store
+ * (`Library/BulletinBoard/VersionedSectionInfo.plist`), reads that file only on its own start and
+ * rewrites it from memory from time to time (e.g. a few seconds after it starts). So SpringBoard of
+ * a booted device is paused while the app's section is written, then restarted with the store kept
+ * immutable until the old process is gone. The new SpringBoard loads the change and terminates
+ * every running app. A shut down device only gets the file, SpringBoard loads it on boot.
+ */
+async function setNotificationsAccess(
+  this: NativeSimctl,
+  udid: string,
+  bundleId: string,
+  status: 'granted' | 'denied' | 'critical' | 'unset',
+): Promise<void> {
+  const device = await this._findDevice(udid);
+  const storePath = path.join(device.dataPath(), 'Library', 'BulletinBoard', 'VersionedSectionInfo.plist');
+  await withStoreLock(storePath, async () => {
+    const springBoard = device.state() === SimDeviceState.Booted ? new SpringBoard(this, udid) : undefined;
+    await springBoard?.pause();
+    let written = false;
+    try {
+      written = await writeNotificationsSection(storePath, bundleId, status);
+    } finally {
+      if (!written) {
+        springBoard?.resume();
+      }
+    }
+    if (!springBoard || !written) {
+      return;
+    }
+    await setImmutable(storePath, true);
+    try {
+      await springBoard.restart();
+    } finally {
+      await setImmutable(storePath, false);
+    }
+  });
+}
+
+/**
+ * Runs `update` once every earlier update of the same store has settled: concurrent updates for
+ * different apps would otherwise read the same store, and the last write would drop the other app's
+ * section. Only the calls made by this process are serialized.
+ */
+async function withStoreLock(storePath: string, update: () => Promise<void>): Promise<void> {
+  const result = (storeUpdates.get(storePath) ?? Promise.resolve()).then(update);
+  const settled = result.catch(() => {});
+  storeUpdates.set(storePath, settled);
+  try {
+    await result;
+  } finally {
+    if (storeUpdates.get(storePath) === settled) {
+      storeUpdates.delete(storePath);
+    }
+  }
+}
+
+/**
+ * Adds, replaces or (`unset`) removes the app's section. The store is replaced atomically, so a
+ * failed write leaves the previous one intact. A device that has never been booted has no store yet:
+ * it is created with just this section, and SpringBoard adds the rest on boot.
+ *
+ * @returns `false` if there was nothing to write (`unset` without a store)
+ */
+async function writeNotificationsSection(
+  storePath: string,
+  bundleId: string,
+  status: 'granted' | 'denied' | 'critical' | 'unset',
+): Promise<boolean> {
+  let store: {sectionInfoVersionNumber?: number; sectionInfo?: Record<string, Uint8Array>};
+  if (await fs.exists(storePath)) {
+    store = (await plist.parsePlistFile(storePath)) as typeof store;
+  } else if (status === 'unset') {
+    return false;
+  } else {
+    await fs.mkdir(path.dirname(storePath), {recursive: true});
+    store = {sectionInfoVersionNumber: BULLETIN_BOARD_STORE_VERSION};
+  }
+  const sectionInfo = store.sectionInfo ?? {};
+  if (status === 'unset') {
+    delete sectionInfo[bundleId];
+  } else {
+    sectionInfo[bundleId] = buildNotificationsSectionInfo(bundleId, status);
+  }
+  store.sectionInfo = sectionInfo;
+  // In the same directory, so that the rename is atomic.
+  const tmpPath = `${storePath}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmpPath, plist.createPlist(store, false), {flag: 'wx'});
+    await fs.rename(tmpPath, storePath);
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
+  return true;
+}
+
+/**
+ * Builds the NSKeyedArchiver-encoded `BBSectionInfo` of `bundleId`, the same archive
+ * AppleSimulatorUtils writes (SetNotificationsPermission.m). SpringBoard migrates its
+ * `allowsNotifications` flag to the current `authorizationStatus` when it loads the section.
+ */
+function buildNotificationsSectionInfo(bundleId: string, status: 'granted' | 'denied' | 'critical'): Buffer {
+  const nil = {UID: 0};
+  return plist.createBinaryPlist({
+    $version: 100000,
+    $objects: [
+      '$null',
+      {
+        suppressFromSettings: false,
+        suppressedSettings: 0,
+        hideWeeApp: false,
+        sectionID: {UID: 2},
+        displayName: {UID: 5},
+        icon: nil,
+        displaysCriticalBulletins: false,
+        subsections: nil,
+        sectionInfoSettings: {UID: 3},
+        $class: {UID: 7},
+        sectionCategory: 0,
+        subsectionPriority: 0,
+        version: {UID: 6},
+        managedSectionInfoSettings: nil,
+        appName: {UID: 5},
+        sectionType: 0,
+        factorySectionID: nil,
+        dataProviderIDs: nil,
+        subsectionID: nil,
+        filters: nil,
+        pathToWeeAppPluginBundle: nil,
+      },
+      bundleId,
+      {
+        pushSettings: 63,
+        showsInNotificationCenter: true,
+        allowsNotifications: status !== 'denied',
+        showsOnExternalDevices: true,
+        contentPreviewSetting: 0,
+        carPlaySetting: 0,
+        $class: {UID: 4},
+        showsInLockScreen: true,
+        alertType: 1,
+        criticalAlertSetting: status === 'critical' ? 2 : 0,
+      },
+      {$classname: 'BBSectionInfoSettings', $classes: ['BBSectionInfoSettings', 'NSObject']},
+      bundleId,
+      0,
+      {$classname: 'BBSectionInfo', $classes: ['BBSectionInfo', 'NSObject']},
+    ],
+    $archiver: 'NSKeyedArchiver',
+    $top: {root: {UID: 1}},
+  });
+}
+
+async function setImmutable(filePath: string, immutable: boolean): Promise<void> {
+  try {
+    await execFileAsync('chflags', [immutable ? 'uchg' : 'nouchg', filePath]);
+  } catch {}
+}
+
+/**
+ * SpringBoard of a booted device: the process that owns the BulletinBoard store, see
+ * setNotificationsAccess. The simulator shares the host kernel, so it is signalled directly.
+ */
+class SpringBoard {
+  private pausedPid: number | undefined;
+
+  constructor(
+    private readonly simctl: NativeSimctl,
+    private readonly udid: string,
+  ) {}
+
+  /**
+   * Pauses the running SpringBoard so that it cannot rewrite the BulletinBoard store. It can be in
+   * the middle of a restart, hence the retries.
+   */
+  async pause(): Promise<void> {
+    try {
+      await waitForCondition(
+        async () => {
+          const pid = await this.pid().catch(() => undefined);
+          if (pid && sendSignal(pid, 'SIGSTOP')) {
+            this.pausedPid = pid;
+          }
+          return Boolean(this.pausedPid);
+        },
+        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
+      );
+    } catch {}
+    if (!this.pausedPid) {
+      throw new Error(`${SPRINGBOARD_SERVICE} is not running`);
+    }
+  }
+
+  /** Lets the paused SpringBoard run again. */
+  resume(): void {
+    if (this.pausedPid) {
+      sendSignal(this.pausedPid, 'SIGCONT');
+    }
+  }
+
+  /**
+   * Replaces the paused SpringBoard with a new one: asks launchd to stop it (launchd starts a new
+   * one right away), resumes it so that it can exit, then waits for the new process.
+   */
+  async restart(): Promise<void> {
+    const previousPid = this.pausedPid;
+    try {
+      await this.stop();
+    } finally {
+      this.resume();
+      this.pausedPid = undefined;
+    }
+    try {
+      await waitForCondition(
+        async () => {
+          const pid = await this.pid().catch(() => undefined);
+          return Number.isInteger(pid) && pid !== previousPid;
+        },
+        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
+      );
+    } catch {
+      throw new Error(`${SPRINGBOARD_SERVICE} did not restart within ${SPRINGBOARD_RESTART_TIMEOUT_MS}ms`);
+    }
+  }
+
+  private async pid(): Promise<number | undefined> {
+    return (await this.simctl.listProcesses(this.udid)).find(({name}) => name === SPRINGBOARD_SERVICE)?.pid;
+  }
+
+  private async stop(): Promise<void> {
+    // Bare name: resolved against the guest runtime's own bin dirs, like in listProcesses.
+    const proc = await this.simctl.spawnProcess(this.udid, 'launchctl', {
+      arguments: ['launchctl', 'stop', SPRINGBOARD_SERVICE],
+    });
+    let stderr = '';
+    proc.stdout.resume();
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk;
+    });
+    const streamError = Promise.race([once(proc.stdout, 'error'), once(proc.stderr, 'error')]).then(([err]) => {
+      throw err;
+    });
+    const [[code, signal]] = await Promise.race([
+      Promise.all([once(proc, 'exit'), once(proc.stderr, 'end')]),
+      streamError,
+    ]);
+    if (code !== 0) {
+      const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+      throw new Error(
+        `'launchctl stop ${SPRINGBOARD_SERVICE}' failed with ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ''}`,
+      );
+    }
+  }
+}
+
+/**
+ * @returns `false` if the process no longer exists
+ */
+function sendSignal(pid: number, name: NodeJS.Signals): boolean {
+  try {
+    process.kill(pid, name);
+    return true;
+  } catch (err: any) {
+    if (err?.code === 'ESRCH') {
+      return false;
+    }
+    throw err;
+  }
+}

package/src/commands/screenshot.ts

@@ -1,6 +1,6 @@
 import type {NativeSimctl} from '../native-simctl.js';
 import type {ScreenshotOptions, SimDisplayInfo} from '../types.js';
-import {runCatchingAsync} from '../utils/index.js';
+import {resolveDisplayPortId, runCatchingAsync, validateDisplayId} from '../utils/index.js';
 
 declare module '../native-simctl.js' {
   interface NativeSimctl {
@@ -12,11 +12,11 @@ declare module '../native-simctl.js' {
 /**
  * Captures a device display as an image — the native equivalent of `simctl io <udid> screenshot`
  * (see native/sim_screenshot.mm for how this reads the framebuffer directly, with no temp file or
- * subprocess). Rejects if the resolved display has no renderable surface yet (e.g. not booted), or
- * if `options.displayId` doesn't match any display from {@link getDisplays}.
+ * subprocess). Rejects if the resolved display has no renderable surface yet (e.g. not booted).
+ * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
  *
  * @param udid — UDID of the device to capture; must be booted
- * @param options — `format` (defaults to `'png'`), `displayId` (defaults to the primary display),
+ * @param options — `format` (defaults to `'png'`), `displayId`,
  * and `quality` (JPEG only, 0-100 percent)
  * @returns image data encoded as `options.format`
  */
@@ -31,7 +31,12 @@ export async function getScreenshot(
   ) {
     throw new RangeError(`quality must be a number between 0 and 100, got ${options.quality}`);
   }
-  return runCatchingAsync(async () => (await this._findDevice(udid)).screenshot(options));
+  validateDisplayId(options.displayId);
+  return runCatchingAsync(async () => {
+    const device = await this._findDevice(udid);
+    const displayId = await resolveDisplayPortId(device, options.displayId);
+    return await device.screenshot({...options, displayId});
+  });
 }
 
 /**

package/src/commands/video-recording.ts

@@ -4,7 +4,7 @@ import {logger} from '@appium/support';
 
 import type {NativeSimctl} from '../native-simctl.js';
 import type {NativeVideoRecordingHandle, StopVideoRecordingOptions, VideoRecordingOptions} from '../types.js';
-import {runCatchingAsync, toTypedError} from '../utils/index.js';
+import {resolveDisplayPortId, runCatchingAsync, toTypedError, validateDisplayId} from '../utils/index.js';
 
 declare module '../native-simctl.js' {
   interface NativeSimctl {
@@ -48,6 +48,8 @@ const activeRecordings = new Map<string, RecordingState>();
  * 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.
  *
+ * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
+ *
  * @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
@@ -71,18 +73,21 @@ export async function startVideoRecording(
   ) {
     throw new RangeError(`bitrate must be a positive number no greater than ${2 ** 31 - 1}, got ${options.bitrate}`);
   }
+  validateDisplayId(options.displayId);
   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) => {
+  const startPromise = runCatchingAsync(async () => {
+    const device = await this._findDevice(udid);
+    const displayId = await resolveDisplayPortId(device, options.displayId);
+    return device.startVideoRecording(absoluteOutputFile, {...options, displayId}, (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: RecordingState = {start: startPromise};

package/src/commands/video-stream.ts

@@ -4,7 +4,7 @@ import {logger} from '@appium/support';
 
 import type {NativeSimctl} from '../native-simctl.js';
 import type {NativeVideoStreamHandle, VideoAccessUnit, VideoStreamOptions} from '../types.js';
-import {runCatchingAsync, toTypedError} from '../utils/index.js';
+import {resolveDisplayPortId, runCatchingAsync, toTypedError, validateDisplayId} from '../utils/index.js';
 
 declare module '../native-simctl.js' {
   interface NativeSimctl {
@@ -250,6 +250,8 @@ export class VideoStream extends EventEmitter {
  * `startVideoRecording`/`stopVideoRecording` — both, and any number of concurrent streams, can
  * run on the same device at once.
  *
+ * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
+ *
  * @param udid — UDID of the device to stream; must be booted
  * @param options — `displayId`, `codec`, `fps`, `bitrate`, `audio` — see {@link VideoStreamOptions}
  */
@@ -269,11 +271,13 @@ export async function startVideoStream(
   ) {
     throw new RangeError(`bitrate must be a positive number no greater than ${2 ** 31 - 1}, got ${options.bitrate}`);
   }
+  validateDisplayId(options.displayId);
   const device = await runCatchingAsync(() => this._findDevice(udid));
+  const displayId = await runCatchingAsync(() => resolveDisplayPortId(device, options.displayId));
   const stream = new VideoStream(options.codec === 'hevc' ? 'hevc' : 'h264');
   const handle = await runCatchingAsync(() =>
     device.startVideoStream(
-      options,
+      {...options, displayId},
       (unit) => stream._handleAccessUnit(unit),
       (err) => stream._handleError(err),
     ),

package/src/coresim.mm

@@ -619,6 +619,12 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
       return Napi::String::New(info.Env(), coresim::RuntimeRootPath(runtime).UTF8String);
     });
   }
+  Napi::Value DataPath(const Napi::CallbackInfo& info) {
+    return CatchToJs(info.Env(), [&]() -> Napi::Value {
+      NSString* dataPath = coresim::DeviceDataPath(device_);
+      return Napi::String::New(info.Env(), dataPath == nil ? "" : dataPath.UTF8String);
+    });
+  }
 
   // Bridges SimDevice's GCD-completion-block-based bootAsyncWithOptions:completionQueue:
   // completionHandler: — this is what replaces the CLI's bootstatus poll-until-timeout race with
@@ -1724,6 +1730,7 @@ void NativeDevice::Init(Napi::Env env) {
                       InstanceMethod<&NativeDevice::DeviceTypeIdentifier>("deviceTypeIdentifier"),
                       InstanceMethod<&NativeDevice::RuntimeIdentifier>("runtimeIdentifier"),
                       InstanceMethod<&NativeDevice::RuntimeRootPath>("runtimeRootPath"),
+                      InstanceMethod<&NativeDevice::DataPath>("dataPath"),
                       InstanceMethod<&NativeDevice::Boot>("boot"),
                       InstanceMethod<&NativeDevice::GetBootStatus>("getBootStatus"),
                       InstanceMethod<&NativeDevice::Shutdown>("shutdown"),

package/src/index.ts

@@ -15,6 +15,8 @@ export {
   type JpegFrame,
   type JpegStreamOptions,
   type PushNotificationPayload,
+  type DisplayId,
+  type DisplayOptions,
   type ScreenshotOptions,
   type SimBootInfo,
   type SimDeviceInfo,

package/src/native/sim_screenshot.h

@@ -6,11 +6,15 @@
 namespace coresim {
 
 // Enumerates the device's renderable display IO ports — the same information `simctl io <udid>
-// enumerate` reports for its own `--display` selection. Each element has "id" (NSString, a port
-// UUID — pass to CaptureScreenshot's displayId to target it), "displayClass" (NSNumber,
-// unsigned short — 0 is always the primary display), and "isMain" (NSNumber/BOOL). Returns nil
-// (and sets *error) if the device has no IO client at all (e.g. not booted); an empty (non-nil)
-// array means the device has an IO client but no renderable display.
+// enumerate` reports for its own `--display` selection. Each element contains:
+// - "id": NSString port UUID — pass to CaptureScreenshot's displayId to target it.
+// - "displayClass": NSNumber/unsigned short, the raw display class.
+// - "isMain": NSNumber/BOOL, true when displayClass == 0. Multiple integrated displays can
+//   have class 0 (e.g. both Duo displays); this does not identify a unique primary display.
+// - "screenId": optional NSNumber/unsigned int guest screen ID from SimScreenProperties.screenID,
+//   matching XCTest's displayID. Omitted when the required selectors are unavailable.
+// Returns nil (and sets *error) if the device has no IO client at all (e.g. not booted); an empty
+// (non-nil) array means the device has an IO client but no renderable display.
 NSArray<NSDictionary*>* ListDisplays(id device, NSError** error);
 
 // Resolves the display descriptor CaptureScreenshot itself reads from, without capturing a
@@ -40,8 +44,9 @@ NSData* EncodeImage(CGImageRef cgImage, ScreenshotFormat format, NSNumber* jpegQ
 // Captures a display as an image, reading the same in-process framebuffer surface `simctl io
 // <udid> screenshot` itself reads (see sim_screenshot.mm) — no temp file, no subprocess.
 // `displayId`, if non-nil, selects a specific port by its UUID (see ListDisplays); nil selects the
-// primary display (displayClass 0), falling back to the first renderable display found (e.g. for
-// tvOS, which has no class-0 display). `jpegQualityPercent` (0-100, nil for ImageIO's own default)
+// first class-0 display, falling back to the first renderable display if none has class 0 (e.g.
+// tvOS). Native selection does not reject multiple class-0 ports; callers that require a unique
+// target must resolve a UUID first. `jpegQualityPercent` (0-100, nil for ImageIO's own default)
 // only applies when `format` is kJPEG — ignored for kPNG, which is always lossless. Returns nil
 // (and sets *error) if `displayId` doesn't match any port, the resolved display has no renderable
 // surface yet (e.g. not booted), or rendering/encoding failed.

package/src/native/sim_screenshot.mm

@@ -183,11 +183,27 @@ NSArray<NSDictionary*>* ListDisplays(id device, NSError** error) {
   NSMutableArray<NSDictionary*>* result = [NSMutableArray arrayWithCapacity:candidates.count];
   for (NSDictionary* candidate in candidates) {
     unsigned short displayClass = [candidate[kCandidateDisplayClassKey] unsignedShortValue];
-    [result addObject:@{
+    NSMutableDictionary* display = [@{
       @"id" : candidate[kCandidateUUIDKey],
       @"displayClass" : candidate[kCandidateDisplayClassKey],
       @"isMain" : @(displayClass == 0),
-    }];
+    } mutableCopy];
+    // A Duo has multiple class-0 displays. Use the guest screen ID to associate
+    // a port UUID with XCTest's displayID; class or enumeration order is ambiguous.
+    id descriptor = candidate[kCandidateDescriptorKey];
+    SEL propertiesSelector = SelectorNamed("screenProperties");
+    if ([descriptor respondsToSelector:propertiesSelector]) {
+      id properties = IdGetter(descriptor, "screenProperties");
+      SEL screenIDSelector = SelectorNamed("screenID");
+      if ([properties respondsToSelector:screenIDSelector]) {
+        unsigned int screenID = SafeInvoke([&] {
+          using Fn = unsigned int (*)(id, SEL);
+          return ((Fn)objc_msgSend)(properties, screenIDSelector);
+        });
+        display[@"screenId"] = @(screenID);
+      }
+    }
+    [result addObject:display];
   }
   return result;
 }