@appium/coresim 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.15.0](https://github.com/appium/appium-ios/compare/@appium/coresim@1.14.1...@appium/coresim@1.15.0) (2026-11-07)
+
+### Features
+
+* add opt-in boot-scoped screenshot display cache ([#51](https://github.com/appium/appium-ios/issues/51)) ([692a1f7](https://github.com/appium/appium-ios/commit/692a1f77bfbc64a18184a83282a8d2695ffe8d0a))
+
+
+## [1.14.1](https://github.com/appium/appium-ios/compare/@appium/coresim@1.14.0...@appium/coresim@1.14.1) (2026-11-06)
+
+### Bug Fixes
+
+* **coresim:** include the failure reason and underlying errors in operation errors ([#163](https://github.com/appium/appium-ios/issues/163)) ([0032a91](https://github.com/appium/appium-ios/commit/0032a918d11d6d883f2896b907b0fbca2a734353))
+
+
 ## [1.14.0](https://github.com/appium/appium-ios/compare/@appium/coresim@1.13.2...@appium/coresim@1.14.0) (2026-10-24)
 
 ### Features

package/lib/src/commands/screenshot.d.ts

@@ -10,7 +10,8 @@ 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).
- * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
+ * Display selection follows {@link validateDisplayId}; numeric IDs resolve to display port UUIDs.
+ * See {@link ScreenshotOptions.cacheDisplayId} for optional boot-scoped numeric-ID caching.
  *
  * @param udid — UDID of the device to capture; must be booted
  * @param options — `format` (defaults to `'png'`), `displayId`,

package/lib/src/commands/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAGnE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,YAAY;QACpB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;KACtD;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE7F"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../src/commands/screenshot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAC,iBAAiB,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAInE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,YAAY;QACpB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;KACtD;CACF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE7F"}

package/lib/src/commands/screenshot.js

@@ -1,9 +1,12 @@
-import { resolveDisplayPortId, runCatchingAsync, validateDisplayId } from '../utils/index.js';
+import { NativeSimDisplayResolutionError } from '../errors.js';
+import { beginDisplaySelection } from '../utils/display-cache.js';
+import { runCatchingAsync, validateDisplayId } from '../utils/index.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).
- * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
+ * Display selection follows {@link validateDisplayId}; numeric IDs resolve to display port UUIDs.
+ * See {@link ScreenshotOptions.cacheDisplayId} for optional boot-scoped numeric-ID caching.
  *
  * @param udid — UDID of the device to capture; must be booted
  * @param options — `format` (defaults to `'png'`), `displayId`,
@@ -16,11 +19,10 @@ export async function getScreenshot(udid, options = {}) {
         throw new RangeError(`quality must be a number between 0 and 100, got ${options.quality}`);
     }
     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 });
-    });
+    if (options.cacheDisplayId !== undefined && typeof options.cacheDisplayId !== 'boolean') {
+        throw new TypeError('cacheDisplayId must be a boolean');
+    }
+    return runCatchingAsync(async () => await captureScreenshot(this, udid, options));
 }
 /**
  * Lists the device's renderable displays — the same information `simctl io <udid> enumerate`
@@ -32,4 +34,26 @@ export async function getScreenshot(udid, options = {}) {
 export async function getDisplays(udid) {
     return runCatchingAsync(async () => (await this._findDevice(udid)).getDisplays());
 }
+/** Capture policy stays here; display resolution and cache ownership are operation-independent. */
+async function captureScreenshot(client, udid, { cacheDisplayId, ...options }) {
+    const selection = await beginDisplaySelection(client, udid, options.displayId, cacheDisplayId);
+    if (selection.cachedPortId !== undefined) {
+        try {
+            const result = await runCatchingAsync(async () => selection.device.screenshot({ ...options, displayId: selection.cachedPortId }));
+            if (selection.commit(selection.cachedPortId)) {
+                return result;
+            }
+        }
+        catch (err) {
+            if (!(err instanceof NativeSimDisplayResolutionError)) {
+                throw err;
+            }
+        }
+        // Retry a missing cached port or a capture spanning a reboot once, using the same numeric ID.
+    }
+    const displayId = await selection.resolveFresh();
+    const result = await selection.device.screenshot({ ...options, displayId });
+    selection.commit(displayId);
+    return result;
+}
 //# sourceMappingURL=screenshot.js.map

package/lib/src/commands/screenshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../../src/commands/screenshot.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,oBAAoB,EAAE,gBAAgB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAS5F;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAEjC,IAAY,EACZ,UAA6B,EAAE;IAE/B,IACE,OAAO,CAAC,OAAO,KAAK,SAAS;QAC7B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC,EACnF,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,mDAAmD,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,gBAAgB,CAAC,KAAK,IAAI,EAAE;QACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,SAAS,GAAG,MAAM,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACxE,OAAO,MAAM,MAAM,CAAC,UAAU,CAAC,EAAC,GAAG,OAAO,EAAE,SAAS,EAAC,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAqB,IAAY;IAChE,OAAO,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACpF,CAAC"}
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../../src/commands/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,+BAA+B,EAAC,MAAM,cAAc,CAAC;AAG7D,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAStE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAEjC,IAAY,EACZ,UAA6B,EAAE;IAE/B,IACE,OAAO,CAAC,OAAO,KAAK,SAAS;QAC7B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,GAAG,GAAG,CAAC,EACnF,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,mDAAmD,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACxF,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAAC,MAAM,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAqB,IAAY;IAChE,OAAO,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,mGAAmG;AACnG,KAAK,UAAU,iBAAiB,CAC9B,MAAoB,EACpB,IAAY,EACZ,EAAC,cAAc,EAAE,GAAG,OAAO,EAAoB;IAE/C,MAAM,SAAS,GAAG,MAAM,qBAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAC/F,IAAI,SAAS,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,IAAI,EAAE,CAC/C,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAC,GAAG,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,YAAY,EAAC,CAAC,CAC7E,CAAC;YACF,IAAI,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC7C,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,+BAA+B,CAAC,EAAE,CAAC;gBACtD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,8FAA8F;IAChG,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,YAAY,EAAE,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,EAAC,GAAG,OAAO,EAAE,SAAS,EAAC,CAAC,CAAC;IAC1E,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/src/errors.d.ts

@@ -4,10 +4,8 @@ export declare class NativeSimError extends Error {
     constructor(message: string);
 }
 /**
- * The class/selector a call needed doesn't exist on the currently loaded CoreSimulator.framework,
- * or a dynamic dispatch raised an NSException that got caught instead of crashing the process.
- * Distinct from {@link NativeSimOperationError}: this means "not supported on this simulator
- * runtime", not "the call ran and Apple's own code rejected it".
+ * A required class, selector, or framework is unavailable.
+ * Objective-C exceptions use {@link NativeSimDispatchError} instead.
  */
 export declare class NativeSimUnavailableError extends NativeSimError {
     readonly kind: string;
@@ -34,18 +32,28 @@ export declare class NativeSimDispatchError extends NativeSimError {
      */
     constructor(message: string, exceptionName: string, reason: string);
 }
-/** The call reached CoreSimulator and Apple's own code rejected it (a structured `NSError`). */
+/** A structured `NSError` from CoreSimulator or the native addon, preserving its domain and code. */
 export declare class NativeSimOperationError extends NativeSimError {
     readonly domain: string;
     readonly code: number;
     name: string;
     /**
-     * @param message — `NSError.localizedDescription`
+     * @param message — `NSError.localizedDescription`, followed by its failure reason and underlying errors
      * @param domain — `NSError.domain`
      * @param code — `NSError.code`
      */
     constructor(message: string, domain: string, code: number);
 }
-/** Re-throws a raw error surfaced by the native addon as the matching typed {@link NativeSimError}. */
+/**
+ * A requested display port is missing or no renderable port exists.
+ * Classified by native/nserror_bridge.mm using native/screenshot_errors.h.
+ */
+export declare class NativeSimDisplayResolutionError extends NativeSimOperationError {
+    name: string;
+}
+/**
+ * Converts native bridge error names to typed errors; domain/code remain diagnostic metadata.
+ * Already-typed errors pass through unchanged.
+ */
 export declare function wrapNativeError(err: unknown): never;
 //# sourceMappingURL=errors.d.ts.map

package/lib/src/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,qBAAa,cAAe,SAAQ,KAAK;IACvB,IAAI,SAAoB;gBAE5B,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;aAWzC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;aACf,gBAAgB,EAAE,MAAM;IAZ1B,IAAI,SAA+B;IAEnD;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM;CAI3C;AAED,iGAAiG;AACjG,qBAAa,sBAAuB,SAAQ,cAAc;aAUtC,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,MAAM;IAVhB,IAAI,SAA4B;IAEhD;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;CAIjC;AAED,gGAAgG;AAChG,qBAAa,uBAAwB,SAAQ,cAAc;aAUvC,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;IAVd,IAAI,SAA6B;IAEjD;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAI/B;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAqBnD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,qBAAa,cAAe,SAAQ,KAAK;IACvB,IAAI,SAAoB;gBAE5B,OAAO,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;aAWzC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;aACf,gBAAgB,EAAE,MAAM;IAZ1B,IAAI,SAA+B;IAEnD;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM;CAI3C;AAED,iGAAiG;AACjG,qBAAa,sBAAuB,SAAQ,cAAc;aAUtC,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,MAAM;IAVhB,IAAI,SAA4B;IAEhD;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM;CAIjC;AAED,qGAAqG;AACrG,qBAAa,uBAAwB,SAAQ,cAAc;aAUvC,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;IAVd,IAAI,SAA6B;IAEjD;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAI/B;AAED;;;GAGG;AACH,qBAAa,+BAAgC,SAAQ,uBAAuB;IAC1D,IAAI,SAAqC;CAC1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAuBnD"}

package/lib/src/errors.js

@@ -6,10 +6,8 @@ export class NativeSimError extends Error {
     }
 }
 /**
- * The class/selector a call needed doesn't exist on the currently loaded CoreSimulator.framework,
- * or a dynamic dispatch raised an NSException that got caught instead of crashing the process.
- * Distinct from {@link NativeSimOperationError}: this means "not supported on this simulator
- * runtime", not "the call ran and Apple's own code rejected it".
+ * A required class, selector, or framework is unavailable.
+ * Objective-C exceptions use {@link NativeSimDispatchError} instead.
  */
 export class NativeSimUnavailableError extends NativeSimError {
     kind;
@@ -45,13 +43,13 @@ export class NativeSimDispatchError extends NativeSimError {
         this.reason = reason;
     }
 }
-/** The call reached CoreSimulator and Apple's own code rejected it (a structured `NSError`). */
+/** A structured `NSError` from CoreSimulator or the native addon, preserving its domain and code. */
 export class NativeSimOperationError extends NativeSimError {
     domain;
     code;
     name = 'NativeSimOperationError';
     /**
-     * @param message — `NSError.localizedDescription`
+     * @param message — `NSError.localizedDescription`, followed by its failure reason and underlying errors
      * @param domain — `NSError.domain`
      * @param code — `NSError.code`
      */
@@ -61,7 +59,17 @@ export class NativeSimOperationError extends NativeSimError {
         this.code = code;
     }
 }
-/** Re-throws a raw error surfaced by the native addon as the matching typed {@link NativeSimError}. */
+/**
+ * A requested display port is missing or no renderable port exists.
+ * Classified by native/nserror_bridge.mm using native/screenshot_errors.h.
+ */
+export class NativeSimDisplayResolutionError extends NativeSimOperationError {
+    name = 'NativeSimDisplayResolutionError';
+}
+/**
+ * Converts native bridge error names to typed errors; domain/code remain diagnostic metadata.
+ * Already-typed errors pass through unchanged.
+ */
 export function wrapNativeError(err) {
     if (err instanceof NativeSimError) {
         throw err;
@@ -73,6 +81,8 @@ export function wrapNativeError(err) {
             throw new NativeSimUnavailableError(message, String(error.kind ?? ''), String(error.missing ?? ''), String(error.frameworkVersion ?? ''));
         case 'NativeSimDispatchError':
             throw new NativeSimDispatchError(message, String(error.exceptionName ?? ''), String(error.reason ?? ''));
+        case 'NativeSimDisplayResolutionError':
+            throw new NativeSimDisplayResolutionError(message, String(error.domain ?? ''), Number(error.code ?? 0));
         case 'NativeSimOperationError':
             throw new NativeSimOperationError(message, String(error.domain ?? ''), Number(error.code ?? 0));
         default:

package/lib/src/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvB,IAAI,GAAG,gBAAgB,CAAC;IAExC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,cAAc;IAWzC;IACA;IACA;IAZF,IAAI,GAAG,2BAA2B,CAAC;IAEnD;;;;;OAKG;IACH,YACE,OAAe,EACC,IAAY,EACZ,OAAe,EACf,gBAAwB;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,qBAAgB,GAAhB,gBAAgB,CAAQ;IAG1C,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IAUtC;IACA;IAVF,IAAI,GAAG,wBAAwB,CAAC;IAEhD;;;;OAIG;IACH,YACE,OAAe,EACC,aAAqB,EACrB,MAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAQ;IAGhC,CAAC;CACF;AAED,gGAAgG;AAChG,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IAUvC;IACA;IAVF,IAAI,GAAG,yBAAyB,CAAC;IAEjD;;;;OAIG;IACH,YACE,OAAe,EACC,MAAc,EACd,IAAY;QAE5B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;IAG9B,CAAC;CACF;AAED,uGAAuG;AACvG,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAG,GAAsC,CAAC;IACrD,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9C,QAAQ,KAAK,EAAE,IAAI,EAAE,CAAC;QACpB,KAAK,2BAA2B;YAC9B,MAAM,IAAI,yBAAyB,CACjC,OAAO,EACP,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EACxB,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,EAC3B,MAAM,CAAC,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC,CACrC,CAAC;QACJ,KAAK,wBAAwB;YAC3B,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3G,KAAK,yBAAyB;YAC5B,MAAM,IAAI,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QAClG;YACE,MAAM,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvB,IAAI,GAAG,gBAAgB,CAAC;IAExC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,cAAc;IAWzC;IACA;IACA;IAZF,IAAI,GAAG,2BAA2B,CAAC;IAEnD;;;;;OAKG;IACH,YACE,OAAe,EACC,IAAY,EACZ,OAAe,EACf,gBAAwB;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,qBAAgB,GAAhB,gBAAgB,CAAQ;IAG1C,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IAUtC;IACA;IAVF,IAAI,GAAG,wBAAwB,CAAC;IAEhD;;;;OAIG;IACH,YACE,OAAe,EACC,aAAqB,EACrB,MAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAQ;IAGhC,CAAC;CACF;AAED,qGAAqG;AACrG,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IAUvC;IACA;IAVF,IAAI,GAAG,yBAAyB,CAAC;IAEjD;;;;OAIG;IACH,YACE,OAAe,EACC,MAAc,EACd,IAAY;QAE5B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;IAG9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,+BAAgC,SAAQ,uBAAuB;IAC1D,IAAI,GAAG,iCAAiC,CAAC;CAC1D;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAG,GAAsC,CAAC;IACrD,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9C,QAAQ,KAAK,EAAE,IAAI,EAAE,CAAC;QACpB,KAAK,2BAA2B;YAC9B,MAAM,IAAI,yBAAyB,CACjC,OAAO,EACP,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EACxB,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,EAC3B,MAAM,CAAC,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC,CACrC,CAAC;QACJ,KAAK,wBAAwB;YAC3B,MAAM,IAAI,sBAAsB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3G,KAAK,iCAAiC;YACpC,MAAM,IAAI,+BAA+B,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1G,KAAK,yBAAyB;YAC5B,MAAM,IAAI,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QAClG;YACE,MAAM,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC"}

package/lib/src/index.d.ts

@@ -1,4 +1,4 @@
-export { NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError } from './errors.js';
+export { NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError, NativeSimDisplayResolutionError, } from './errors.js';
 export { NativeSimctl, type NativeSimctlOptions } from './native-simctl.js';
 export { SpawnedProcess } from './commands/spawn.js';
 export { VideoStream } from './commands/video-stream.js';

package/lib/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,uBAAuB,EAAC,MAAM,aAAa,CAAC;AACvH,OAAO,EAAC,YAAY,EAAE,KAAK,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AACrD,YAAY,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAC,aAAa,EAAC,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,YAAY,EAAE,KAAK,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AACrD,YAAY,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAC,aAAa,EAAC,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}

package/lib/src/index.js

@@ -1,4 +1,4 @@
-export { NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError } from './errors.js';
+export { NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError, NativeSimDisplayResolutionError, } from './errors.js';
 export { NativeSimctl } from './native-simctl.js';
 export { SpawnedProcess } from './commands/spawn.js';
 export { VideoStream } from './commands/video-stream.js';

package/lib/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,uBAAuB,EAAC,MAAM,aAAa,CAAC;AACvH,OAAO,EAAC,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AAGrD,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,GAuBf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAC,WAAW,EAAC,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AAGrD,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,GAuBf,MAAM,YAAY,CAAC"}

package/lib/src/types.d.ts

@@ -110,6 +110,13 @@ export interface DisplayOptions {
 }
 /** Options for `NativeSimctl.getScreenshot`. */
 export interface ScreenshotOptions extends DisplayOptions {
+    /**
+     * Cache numeric display-ID lookups per client/device while the observed boot marker is unchanged.
+     * Defaults to `false`, which clears the selection. Missing boot metadata disables caching.
+     * Missing cached ports retry once with fresh resolution. Disable during display-topology changes.
+     * @see https://github.com/appium/appium-ios/pull/51 for boot-marker limitations and validation.
+     */
+    cacheDisplayId?: boolean;
     /** Image encoding — defaults to `'png'`. */
     format?: 'png' | 'jpeg';
     /**
@@ -369,6 +376,8 @@ export interface NativeDeviceHandle {
     udid(): string;
     name(): string;
     state(): number;
+    /** Last boot's Unix timestamp in milliseconds, or null if never booted; may throw if unsupported. */
+    lastBootedAt(): number | null;
     deviceTypeIdentifier(): string;
     runtimeIdentifier(): string;
     runtimeRootPath(): string;

package/lib/src/types.d.ts.map

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

package/lib/src/utils/display-cache.d.ts

@@ -0,0 +1,13 @@
+import type { NativeSimctl } from '../native-simctl.js';
+import { type DisplayId, type NativeDeviceHandle } from '../types.js';
+/** One operation's display selection. Call commit only after the operation succeeds. */
+export interface DisplaySelection {
+    device: NativeDeviceHandle;
+    cachedPortId?: string;
+    resolveFresh(): Promise<string | undefined>;
+    /** Returns whether the observed boot is unchanged, even if another operation owns the cache. */
+    commit(portId: string | undefined): boolean;
+}
+/** Reserves write ownership while retaining the mapping; uncached selections invalidate it. */
+export declare function beginDisplaySelection(client: NativeSimctl, udid: string, displayId: DisplayId | undefined, useCache?: boolean): Promise<DisplaySelection>;
+//# sourceMappingURL=display-cache.d.ts.map

package/lib/src/utils/display-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-cache.d.ts","sourceRoot":"","sources":["../../../src/utils/display-cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,kBAAkB,EAAC,MAAM,aAAa,CAAC;AAkBpF,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC5C,gGAAgG;IAChG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;CAC7C;AAED,+FAA+F;AAC/F,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAoE3B"}

package/lib/src/utils/display-cache.js

@@ -0,0 +1,92 @@
+import { LRUCache } from 'lru-cache';
+import { SimDeviceState } from '../types.js';
+import { resolveDisplayPortId } from './display.js';
+const MAX_CACHED_DEVICES = 32;
+const displayCaches = new WeakMap();
+/** Reserves write ownership while retaining the mapping; uncached selections invalidate it. */
+export async function beginDisplaySelection(client, udid, displayId, useCache = false) {
+    const key = udid.toLowerCase();
+    let cache = displayCaches.get(client);
+    const cacheable = useCache && typeof displayId === 'number';
+    let cached;
+    const owner = Symbol('display-cache-owner');
+    let entry;
+    if (cacheable) {
+        if (!cache) {
+            cache = new LRUCache({ max: MAX_CACHED_DEVICES });
+            displayCaches.set(client, cache);
+        }
+        entry = cache.get(key) ?? { owner, generation: Symbol('display-cache-generation') };
+        cached = entry.display;
+        entry.owner = owner;
+        cache.set(key, entry);
+    }
+    else {
+        cache?.delete(key);
+    }
+    let generation = entry?.generation;
+    const invalidateCached = () => {
+        if (entry && cached && cache?.peek(key) === entry && entry.display === cached) {
+            entry.display = undefined;
+            entry.generation = Symbol('display-cache-generation');
+            if (entry.owner === owner) {
+                generation = entry.generation;
+            }
+        }
+    };
+    const device = await client._findDevice(udid);
+    let bootMarker = cacheable ? readBootMarker(device) : null;
+    const cachedPortId = bootMarker !== null && cached && cached.screenId === displayId && cached.bootMarker === bootMarker
+        ? cached.portId
+        : undefined;
+    if (cached && (bootMarker === null || cached.bootMarker !== bootMarker)) {
+        invalidateCached();
+    }
+    return {
+        device,
+        cachedPortId,
+        async resolveFresh() {
+            if (cachedPortId !== undefined) {
+                invalidateCached();
+            }
+            bootMarker = cacheable ? readBootMarker(device) : null;
+            return await resolveDisplayPortId(device, displayId);
+        },
+        commit(portId) {
+            const sameBoot = bootMarker !== null && readBootMarker(device) === bootMarker;
+            if (!sameBoot) {
+                invalidateCached();
+            }
+            if (sameBoot &&
+                bootMarker !== null &&
+                cacheable &&
+                portId &&
+                entry &&
+                cache?.peek(key) === entry &&
+                entry.owner === owner &&
+                entry.generation === generation) {
+                entry.display = { screenId: displayId, portId, bootMarker };
+            }
+            return sameBoot;
+        },
+    };
+}
+/**
+ * Returns a boot marker only while the device is Booted. Unsupported or unreadable metadata
+ * disables caching. The timestamp persists after shutdown and is not a guaranteed unique UUID.
+ */
+function readBootMarker(device) {
+    try {
+        if (device.state() !== SimDeviceState.Booted) {
+            return null;
+        }
+        const marker = device.lastBootedAt();
+        return marker !== null && Number.isFinite(marker) && marker > 0 && device.state() === SimDeviceState.Booted
+            ? marker
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=display-cache.js.map

package/lib/src/utils/display-cache.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/coresim",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Native bindings to CoreSimulator.framework for Apple platform simulator control",
   "bugs": {
     "url": "https://github.com/appium/appium-ios/issues"
@@ -49,6 +49,7 @@
   "dependencies": {
     "@appium/support": "^7.2.0",
     "asyncbox": "^6.5.0",
+    "lru-cache": "^11.5.3",
     "node-addon-api": "^8.5.0",
     "node-gyp-build": "^4.8.4"
   },
@@ -62,5 +63,5 @@
     "npm": ">=10"
   },
   "gypfile": true,
-  "gitHead": "1e3ecf666350a1868a196e84bf09cc1fe116cc4a"
+  "gitHead": "943e2efdb5d8b26a704d0cef58cb5eec0f37076c"
 }

package/src/commands/screenshot.ts

@@ -1,6 +1,8 @@
+import {NativeSimDisplayResolutionError} from '../errors.js';
 import type {NativeSimctl} from '../native-simctl.js';
 import type {ScreenshotOptions, SimDisplayInfo} from '../types.js';
-import {resolveDisplayPortId, runCatchingAsync, validateDisplayId} from '../utils/index.js';
+import {beginDisplaySelection} from '../utils/display-cache.js';
+import {runCatchingAsync, validateDisplayId} from '../utils/index.js';
 
 declare module '../native-simctl.js' {
   interface NativeSimctl {
@@ -13,7 +15,8 @@ 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).
- * Display selection follows {@link validateDisplayId} and {@link resolveDisplayPortId}.
+ * Display selection follows {@link validateDisplayId}; numeric IDs resolve to display port UUIDs.
+ * See {@link ScreenshotOptions.cacheDisplayId} for optional boot-scoped numeric-ID caching.
  *
  * @param udid — UDID of the device to capture; must be booted
  * @param options — `format` (defaults to `'png'`), `displayId`,
@@ -32,11 +35,10 @@ export async function getScreenshot(
     throw new RangeError(`quality must be a number between 0 and 100, got ${options.quality}`);
   }
   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});
-  });
+  if (options.cacheDisplayId !== undefined && typeof options.cacheDisplayId !== 'boolean') {
+    throw new TypeError('cacheDisplayId must be a boolean');
+  }
+  return runCatchingAsync(async () => await captureScreenshot(this, udid, options));
 }
 
 /**
@@ -49,3 +51,31 @@ export async function getScreenshot(
 export async function getDisplays(this: NativeSimctl, udid: string): Promise<SimDisplayInfo[]> {
   return runCatchingAsync(async () => (await this._findDevice(udid)).getDisplays());
 }
+
+/** Capture policy stays here; display resolution and cache ownership are operation-independent. */
+async function captureScreenshot(
+  client: NativeSimctl,
+  udid: string,
+  {cacheDisplayId, ...options}: ScreenshotOptions,
+): Promise<Buffer> {
+  const selection = await beginDisplaySelection(client, udid, options.displayId, cacheDisplayId);
+  if (selection.cachedPortId !== undefined) {
+    try {
+      const result = await runCatchingAsync(async () =>
+        selection.device.screenshot({...options, displayId: selection.cachedPortId}),
+      );
+      if (selection.commit(selection.cachedPortId)) {
+        return result;
+      }
+    } catch (err) {
+      if (!(err instanceof NativeSimDisplayResolutionError)) {
+        throw err;
+      }
+    }
+    // Retry a missing cached port or a capture spanning a reboot once, using the same numeric ID.
+  }
+  const displayId = await selection.resolveFresh();
+  const result = await selection.device.screenshot({...options, displayId});
+  selection.commit(displayId);
+  return result;
+}

package/src/coresim.mm

@@ -606,6 +606,17 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
       return Napi::Number::New(info.Env(), static_cast<double>(DeviceState(device_)));
     });
   }
+  // The observed boot timestamp is local metadata, like state. Missing/unsupported metadata
+  // disables the optional JS cache; callers must not treat it as a unique session UUID.
+  Napi::Value LastBootedAt(const Napi::CallbackInfo& info) {
+    return CatchToJs(info.Env(), [&]() -> Napi::Value {
+      NSDate* date = DeviceLastBootedAt(device_);
+      if (date == nil) {
+        return info.Env().Null();
+      }
+      return Napi::Number::New(info.Env(), date.timeIntervalSince1970 * 1000.0);
+    });
+  }
   // deviceType/runtime are legitimately nil for a device whose runtime profile is no longer
   // installed (shows as "unavailable" in `simctl list devices`) — not an error, just unknown.
   Napi::Value DeviceTypeIdentifier(const Napi::CallbackInfo& info) {
@@ -1773,6 +1784,7 @@ void NativeDevice::Init(Napi::Env env) {
                       InstanceMethod<&NativeDevice::Udid>("udid"),
                       InstanceMethod<&NativeDevice::Name>("name"),
                       InstanceMethod<&NativeDevice::State>("state"),
+                      InstanceMethod<&NativeDevice::LastBootedAt>("lastBootedAt"),
                       InstanceMethod<&NativeDevice::DeviceTypeIdentifier>("deviceTypeIdentifier"),
                       InstanceMethod<&NativeDevice::RuntimeIdentifier>("runtimeIdentifier"),
                       InstanceMethod<&NativeDevice::RuntimeRootPath>("runtimeRootPath"),

package/src/errors.ts

@@ -8,10 +8,8 @@ export class NativeSimError extends Error {
 }
 
 /**
- * The class/selector a call needed doesn't exist on the currently loaded CoreSimulator.framework,
- * or a dynamic dispatch raised an NSException that got caught instead of crashing the process.
- * Distinct from {@link NativeSimOperationError}: this means "not supported on this simulator
- * runtime", not "the call ran and Apple's own code rejected it".
+ * A required class, selector, or framework is unavailable.
+ * Objective-C exceptions use {@link NativeSimDispatchError} instead.
  */
 export class NativeSimUnavailableError extends NativeSimError {
   public override name = 'NativeSimUnavailableError';
@@ -50,12 +48,12 @@ export class NativeSimDispatchError extends NativeSimError {
   }
 }
 
-/** The call reached CoreSimulator and Apple's own code rejected it (a structured `NSError`). */
+/** A structured `NSError` from CoreSimulator or the native addon, preserving its domain and code. */
 export class NativeSimOperationError extends NativeSimError {
   public override name = 'NativeSimOperationError';
 
   /**
-   * @param message — `NSError.localizedDescription`
+   * @param message — `NSError.localizedDescription`, followed by its failure reason and underlying errors
    * @param domain — `NSError.domain`
    * @param code — `NSError.code`
    */
@@ -68,7 +66,18 @@ export class NativeSimOperationError extends NativeSimError {
   }
 }
 
-/** Re-throws a raw error surfaced by the native addon as the matching typed {@link NativeSimError}. */
+/**
+ * A requested display port is missing or no renderable port exists.
+ * Classified by native/nserror_bridge.mm using native/screenshot_errors.h.
+ */
+export class NativeSimDisplayResolutionError extends NativeSimOperationError {
+  public override name = 'NativeSimDisplayResolutionError';
+}
+
+/**
+ * Converts native bridge error names to typed errors; domain/code remain diagnostic metadata.
+ * Already-typed errors pass through unchanged.
+ */
 export function wrapNativeError(err: unknown): never {
   if (err instanceof NativeSimError) {
     throw err;
@@ -85,6 +94,8 @@ export function wrapNativeError(err: unknown): never {
       );
     case 'NativeSimDispatchError':
       throw new NativeSimDispatchError(message, String(error.exceptionName ?? ''), String(error.reason ?? ''));
+    case 'NativeSimDisplayResolutionError':
+      throw new NativeSimDisplayResolutionError(message, String(error.domain ?? ''), Number(error.code ?? 0));
     case 'NativeSimOperationError':
       throw new NativeSimOperationError(message, String(error.domain ?? ''), Number(error.code ?? 0));
     default:

package/src/index.ts

@@ -1,4 +1,10 @@
-export {NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError} from './errors.js';
+export {
+  NativeSimError,
+  NativeSimUnavailableError,
+  NativeSimDispatchError,
+  NativeSimOperationError,
+  NativeSimDisplayResolutionError,
+} from './errors.js';
 export {NativeSimctl, type NativeSimctlOptions} from './native-simctl.js';
 export {SpawnedProcess} from './commands/spawn.js';
 export {VideoStream} from './commands/video-stream.js';

package/src/native/nserror_bridge.h

@@ -11,6 +11,10 @@
 
 namespace coresim {
 
+// localizedDescription is often generic ("Simulator device failed to install the application."), so
+// the failure reason and the NSUnderlyingErrorKey chain are appended.
+std::string DescribeNSError(NSError* error);
+
 // Thrown by async work lambdas (see async_bridge.h) when a native call fails via an NSError**
 // out-param rather than raising. domain/code/message are captured immediately at throw time
 // (never the NSError* itself), since this only ever needs to survive within the same background
@@ -18,7 +22,7 @@ namespace coresim {
 class NSErrorException : public std::runtime_error {
  public:
   explicit NSErrorException(NSError* error)
-      : std::runtime_error(error.localizedDescription ? error.localizedDescription.UTF8String : "Operation failed"),
+      : std::runtime_error(DescribeNSError(error)),
         domain(error.domain ? error.domain.UTF8String : ""),
         code(error.code) {}
 
@@ -26,8 +30,9 @@ class NSErrorException : public std::runtime_error {
   long long code;
 };
 
-// Converts an NSError into a JS Error with {name: 'NativeSimOperationError', domain, code,
-// message} — errors.ts wraps this into NativeSimError. Built from an already-caught
+// Converts an NSError into a named JS Error with domain/code/message. Display resolution
+// failures use NativeSimDisplayResolutionError; other failures use NativeSimOperationError.
+// errors.ts wraps the name into the matching class. Built from an already-caught
 // NSErrorException's extracted fields, never a live NSError*: this only ever runs in OnOK (main
 // thread), after the exception already crossed out of the background thread's try/catch.
 Napi::Error NSErrorExceptionToJsError(Napi::Env env, const NSErrorException& error);

package/src/native/nserror_bridge.mm

@@ -1,10 +1,45 @@
 #include "nserror_bridge.h"
 
+#include "screenshot_errors.h"
+
 namespace coresim {
 
+std::string DescribeNSError(NSError* error) {
+  constexpr NSUInteger kMaxErrorDepth = 10;
+  NSMutableArray<NSString*>* parts = [NSMutableArray array];
+  NSError* current = error;
+  for (NSUInteger depth = 0; current != nil && depth < kMaxErrorDepth; ++depth) {
+    for (NSString* text in @[ current.localizedDescription ?: @"", current.localizedFailureReason ?: @"" ]) {
+      NSString* trimmed = [text stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
+      NSUInteger known = [parts indexOfObjectPassingTest:^BOOL(NSString* part, NSUInteger, BOOL*) {
+        return [part containsString:trimmed];
+      }];
+      if (trimmed.length == 0 || known != NSNotFound) {
+        continue;
+      }
+      NSIndexSet* covered = [parts indexesOfObjectsPassingTest:^BOOL(NSString* part, NSUInteger, BOOL*) {
+        return [trimmed containsString:part];
+      }];
+      [parts removeObjectsAtIndexes:covered];
+      [parts addObject:trimmed];
+    }
+    id underlying = current.userInfo[NSUnderlyingErrorKey];
+    current = [underlying isKindOfClass:NSError.class] ? underlying : nil;
+  }
+  NSMutableArray<NSString*>* sentences = [NSMutableArray arrayWithCapacity:parts.count];
+  for (NSString* part in parts) {
+    BOOL terminated = [part hasSuffix:@"."] || [part hasSuffix:@"!"] || [part hasSuffix:@"?"];
+    [sentences addObject:terminated ? part : [part stringByAppendingString:@"."]];
+  }
+  return sentences.count > 0 ? [sentences componentsJoinedByString:@" "].UTF8String : "Operation failed";
+}
+
 Napi::Error NSErrorExceptionToJsError(Napi::Env env, const NSErrorException& error) {
   Napi::Error jsError = Napi::Error::New(env, error.what());
-  jsError.Set("name", "NativeSimOperationError");
+  const bool isDisplayResolutionError =
+      error.domain == kScreenshotErrorDomain &&
+      (error.code == kScreenshotDisplayNotFound || error.code == kScreenshotNoRenderableDisplay);
+  jsError.Set("name", isDisplayResolutionError ? "NativeSimDisplayResolutionError" : "NativeSimOperationError");
   jsError.Set("domain", error.domain);
   jsError.Set("code", static_cast<double>(error.code));
   return jsError;

package/src/native/screenshot_errors.h

@@ -0,0 +1,19 @@
+#pragma once
+
+namespace coresim {
+
+inline constexpr const char* kScreenshotErrorDomain = "io.appium.coresim.Screenshot";
+
+enum ScreenshotErrorCode {
+  kScreenshotNoIOClient = 1,
+  kScreenshotDisplayNotFound = 2,
+  kScreenshotNoRenderableDisplay = 3,
+  kScreenshotSurfaceUnavailable = 4,
+  kScreenshotImageCreationFailed = 5,
+  kScreenshotRenderingFailed = 6,
+  kScreenshotEncoderCreationFailed = 7,
+  kScreenshotEncodingFailed = 8,
+  kScreenshotNoCaptureServiceIOClient = 11,
+};
+
+}  // namespace coresim

package/src/native/sim_screenshot.mm

@@ -7,15 +7,14 @@
 
 #include "objc_runtime.h"
 #include "safe_dispatch.h"
+#include "screenshot_errors.h"
 
 namespace coresim {
 
 namespace {
 
-NSString* const kScreenshotErrorDomain = @"io.appium.coresim.Screenshot";
-
-NSError* MakeError(NSInteger code, NSString* message) {
-  return [NSError errorWithDomain:kScreenshotErrorDomain code:code userInfo:@{NSLocalizedDescriptionKey : message}];
+NSError* MakeError(ScreenshotErrorCode code, NSString* message) {
+  return [NSError errorWithDomain:@(kScreenshotErrorDomain) code:code userInfo:@{NSLocalizedDescriptionKey : message}];
 }
 
 id IdGetter(id target, const std::string& selectorName) {
@@ -56,7 +55,7 @@ NSString* const kCandidateDescriptorKey = @"descriptor";
 NSArray<NSDictionary*>* RenderableDisplayCandidates(id device, NSError** error) {
   id ioClient = IdGetter(device, "io");
   if (ioClient == nil) {
-    *error = MakeError(1, @"Device has no IO client available — is it booted?");
+    *error = MakeError(kScreenshotNoIOClient, @"Device has no IO client available — is it booted?");
     return nil;
   }
 
@@ -97,7 +96,8 @@ id ResolveDisplayDescriptor(NSArray<NSDictionary*>* candidates, NSString* displa
         return candidate[kCandidateDescriptorKey];
       }
     }
-    *error = MakeError(2, [NSString stringWithFormat:@"No display with id '%@' was found on this device", displayId]);
+    *error = MakeError(kScreenshotDisplayNotFound,
+                       [NSString stringWithFormat:@"No display with id '%@' was found on this device", displayId]);
     return nil;
   }
   id fallback = nil;
@@ -110,7 +110,7 @@ id ResolveDisplayDescriptor(NSArray<NSDictionary*>* candidates, NSString* displa
     }
   }
   if (fallback == nil) {
-    *error = MakeError(3, @"No renderable display port was found on this device");
+    *error = MakeError(kScreenshotNoRenderableDisplay, @"No renderable display port was found on this device");
   }
   return fallback;
 }
@@ -159,7 +159,7 @@ id ResolveScreenCaptureService(id device, NSError** error) {
       "startRecordingFromScreen:maskPolicy:assetWriterOutputSettings:outputFile:completionQueue:completionHandler:";
   id ioClient = IdGetter(device, "io");
   if (ioClient == nil) {
-    *error = MakeError(11, @"Device has no IO client available — is it booted?");
+    *error = MakeError(kScreenshotNoCaptureServiceIOClient, @"Device has no IO client available — is it booted?");
     return nil;
   }
   NSArray* ports = IdGetter(ioClient, "ioPorts");
@@ -214,7 +214,7 @@ NSData* EncodeImage(CGImageRef cgImage, ScreenshotFormat format, NSNumber* jpegQ
   CGImageDestinationRef destination =
       CGImageDestinationCreateWithData((__bridge CFMutableDataRef)imageData, (__bridge CFStringRef)uti, 1, NULL);
   if (destination == nullptr) {
-    *error = MakeError(7, @"Failed to create an image encoder");
+    *error = MakeError(kScreenshotEncoderCreationFailed, @"Failed to create an image encoder");
     return nil;
   }
   // kCGImageDestinationLossyCompressionQuality is meaningless for PNG (always lossless) — ImageIO
@@ -228,7 +228,7 @@ NSData* EncodeImage(CGImageRef cgImage, ScreenshotFormat format, NSNumber* jpegQ
   BOOL ok = CGImageDestinationFinalize(destination);
   CFRelease(destination);
   if (!ok) {
-    *error = MakeError(8, @"Failed to encode the image");
+    *error = MakeError(kScreenshotEncodingFailed, @"Failed to encode the image");
     return nil;
   }
   return imageData;
@@ -243,14 +243,14 @@ NSData* CaptureScreenshot(id device, NSString* displayId, ScreenshotFormat forma
 
   id surfaceObj = RenderableSurface(descriptor);
   if (surfaceObj == nil) {
-    *error = MakeError(4, @"The device's display surface is not available yet");
+    *error = MakeError(kScreenshotSurfaceUnavailable, @"The device's display surface is not available yet");
     return nil;
   }
 
   IOSurfaceRef surfaceRef = (__bridge IOSurfaceRef)surfaceObj;
   CIImage* ciImage = [CIImage imageWithIOSurface:surfaceRef];
   if (ciImage == nil) {
-    *error = MakeError(5, @"Failed to wrap the device's display surface as an image");
+    *error = MakeError(kScreenshotImageCreationFailed, @"Failed to wrap the device's display surface as an image");
     return nil;
   }
 
@@ -260,7 +260,7 @@ NSData* CaptureScreenshot(id device, NSString* displayId, ScreenshotFormat forma
   static CIContext* context = [CIContext contextWithOptions:nil];
   CGImageRef cgImage = [context createCGImage:ciImage fromRect:ciImage.extent];
   if (cgImage == nil) {
-    *error = MakeError(6, @"Failed to render the device's display surface");
+    *error = MakeError(kScreenshotRenderingFailed, @"Failed to render the device's display surface");
     return nil;
   }
 

package/src/types.ts

@@ -137,6 +137,13 @@ export interface DisplayOptions {
 
 /** Options for `NativeSimctl.getScreenshot`. */
 export interface ScreenshotOptions extends DisplayOptions {
+  /**
+   * Cache numeric display-ID lookups per client/device while the observed boot marker is unchanged.
+   * Defaults to `false`, which clears the selection. Missing boot metadata disables caching.
+   * Missing cached ports retry once with fresh resolution. Disable during display-topology changes.
+   * @see https://github.com/appium/appium-ios/pull/51 for boot-marker limitations and validation.
+   */
+  cacheDisplayId?: boolean;
   /** Image encoding — defaults to `'png'`. */
   format?: 'png' | 'jpeg';
   /**
@@ -423,6 +430,8 @@ export interface NativeDeviceHandle {
   udid(): string;
   name(): string;
   state(): number;
+  /** Last boot's Unix timestamp in milliseconds, or null if never booted; may throw if unsupported. */
+  lastBootedAt(): number | null;
   deviceTypeIdentifier(): string;
   runtimeIdentifier(): string;
   runtimeRootPath(): string;

package/src/utils/display-cache.ts

@@ -0,0 +1,123 @@
+import {LRUCache} from 'lru-cache';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import {SimDeviceState, type DisplayId, type NativeDeviceHandle} from '../types.js';
+import {resolveDisplayPortId} from './display.js';
+
+const MAX_CACHED_DEVICES = 32;
+interface CachedDisplay {
+  screenId: number;
+  portId: string;
+  bootMarker: number;
+}
+interface DisplayCacheEntry {
+  display?: CachedDisplay;
+  // New operations supersede writers without discarding the mapping.
+  owner: symbol;
+  // Invalidation also revokes pending writers that observed the old mapping.
+  generation: symbol;
+}
+const displayCaches = new WeakMap<NativeSimctl, LRUCache<string, DisplayCacheEntry>>();
+
+/** One operation's display selection. Call commit only after the operation succeeds. */
+export interface DisplaySelection {
+  device: NativeDeviceHandle;
+  cachedPortId?: string;
+  resolveFresh(): Promise<string | undefined>;
+  /** Returns whether the observed boot is unchanged, even if another operation owns the cache. */
+  commit(portId: string | undefined): boolean;
+}
+
+/** Reserves write ownership while retaining the mapping; uncached selections invalidate it. */
+export async function beginDisplaySelection(
+  client: NativeSimctl,
+  udid: string,
+  displayId: DisplayId | undefined,
+  useCache: boolean = false,
+): Promise<DisplaySelection> {
+  const key = udid.toLowerCase();
+  let cache = displayCaches.get(client);
+  const cacheable = useCache && typeof displayId === 'number';
+  let cached: CachedDisplay | undefined;
+  const owner = Symbol('display-cache-owner');
+  let entry: DisplayCacheEntry | undefined;
+  if (cacheable) {
+    if (!cache) {
+      cache = new LRUCache<string, DisplayCacheEntry>({max: MAX_CACHED_DEVICES});
+      displayCaches.set(client, cache);
+    }
+    entry = cache.get(key) ?? {owner, generation: Symbol('display-cache-generation')};
+    cached = entry.display;
+    entry.owner = owner;
+    cache.set(key, entry);
+  } else {
+    cache?.delete(key);
+  }
+  let generation = entry?.generation;
+  const invalidateCached = () => {
+    if (entry && cached && cache?.peek(key) === entry && entry.display === cached) {
+      entry.display = undefined;
+      entry.generation = Symbol('display-cache-generation');
+      if (entry.owner === owner) {
+        generation = entry.generation;
+      }
+    }
+  };
+  const device = await client._findDevice(udid);
+  let bootMarker = cacheable ? readBootMarker(device) : null;
+  const cachedPortId =
+    bootMarker !== null && cached && cached.screenId === displayId && cached.bootMarker === bootMarker
+      ? cached.portId
+      : undefined;
+  if (cached && (bootMarker === null || cached.bootMarker !== bootMarker)) {
+    invalidateCached();
+  }
+  return {
+    device,
+    cachedPortId,
+    async resolveFresh() {
+      if (cachedPortId !== undefined) {
+        invalidateCached();
+      }
+      bootMarker = cacheable ? readBootMarker(device) : null;
+      return await resolveDisplayPortId(device, displayId);
+    },
+    commit(portId) {
+      const sameBoot = bootMarker !== null && readBootMarker(device) === bootMarker;
+      if (!sameBoot) {
+        invalidateCached();
+      }
+      if (
+        sameBoot &&
+        bootMarker !== null &&
+        cacheable &&
+        portId &&
+        entry &&
+        cache?.peek(key) === entry &&
+        entry.owner === owner &&
+        entry.generation === generation
+      ) {
+        entry.display = {screenId: displayId, portId, bootMarker};
+      }
+      return sameBoot;
+    },
+  };
+}
+
+/**
+ * Returns a boot marker only while the device is Booted. Unsupported or unreadable metadata
+ * disables caching. The timestamp persists after shutdown and is not a guaranteed unique UUID.
+ */
+function readBootMarker(device: NativeDeviceHandle): number | null {
+  try {
+    if (device.state() !== SimDeviceState.Booted) {
+      return null;
+    }
+    const marker = device.lastBootedAt();
+    return marker !== null && Number.isFinite(marker) && marker > 0 && device.state() === SimDeviceState.Booted
+      ? marker
+      : null;
+  } catch {
+    return null;
+  }
+}