@appium/coresim 1.0.0

package/lib/src/types.d.ts

@@ -0,0 +1,267 @@
+/** Raw `SimDeviceState` enum values, as returned by `SimDevice.state`. */
+export declare enum SimDeviceState {
+    Creating = 0,
+    Shutdown = 1,
+    Booting = 2,
+    Booted = 3,
+    ShuttingDown = 4
+}
+/** A device in the default device set, as returned by `NativeSimctl.getDevices()`/`createDevice()`. */
+export interface SimDeviceInfo {
+    /** e.g. `"D768CB90-CBB4-4557-82F6-B89E1CD0E80B"`. */
+    udid: string;
+    /** Display name, e.g. `"iPhone 17"`. */
+    name: string;
+    state: SimDeviceState;
+    /** e.g. `com.apple.CoreSimulator.SimDeviceType.iPhone-15` — `""` if that device type is no longer installed. */
+    deviceTypeIdentifier: string;
+    /** e.g. `com.apple.CoreSimulator.SimRuntime.iOS-17-4` — `""` if that runtime is no longer installed. */
+    runtimeIdentifier: string;
+}
+/** A simulator device type this CoreSimulator install supports, as returned by `getSupportedDeviceTypes()`. */
+export interface SimDeviceTypeInfo {
+    /** e.g. `com.apple.CoreSimulator.SimDeviceType.iPhone-15`. */
+    identifier: string;
+    /** Display name, e.g. `"iPhone 15"`. */
+    name: string;
+}
+/** A simulator runtime this CoreSimulator install supports, as returned by `getSupportedRuntimes()`. */
+export interface SimRuntimeInfo {
+    /** e.g. `com.apple.CoreSimulator.SimRuntime.iOS-17-4`. */
+    identifier: string;
+    /** Display name, e.g. `"iOS 17.4"`. */
+    name: string;
+    /** e.g. `"17.4"`. */
+    versionString: string;
+}
+/**
+ * Raw `SimDeviceBootInfo.status` values — a separate, more granular boot-progress signal than
+ * {@link SimDeviceState}, and the one `simctl bootstatus` itself actually monitors (see CLAUDE.md
+ * for how this was confirmed: runtime introspection against the loaded framework, and empirical
+ * polling during a real boot). `SimDeviceState` reaching `Booted`
+ * only means the OS kernel/launchd has started — data migration and system-app (SpringBoard)
+ * startup, which these values track, can still take **20+ seconds longer** after that.
+ * `simctl bootstatus`'s own output also names a `WaitingOnBackboard` phase whose numeric value
+ * wasn't observed in testing (not every boot passes through it) — a `status` outside this enum's
+ * values should be treated as "not yet terminal, keep waiting", not as an error.
+ */
+export declare enum SimBootStatus {
+    Booting = 0,
+    WaitingOnDataMigration = 2,
+    WaitingOnSystemApp = 4,
+    /** The only terminal value observed — `0xFFFFFFFF`. */
+    Finished = 4294967295
+}
+/** What `NativeSimctl.getBootStatus()` resolves with when the device has been booted at least once. */
+export interface SimBootInfo {
+    /** One of {@link SimBootStatus}'s values, or an unrecognized/undocumented one — see there. */
+    status: number;
+    /**
+     * Whether this boot attempt has fully settled (success or failure). Confirmed empirically to
+     * **stay `true` after shutdown**, reflecting the *previous* boot session — this alone does not
+     * mean "currently booted"; check `SimDeviceState` too (see `getBootStatus()`).
+     */
+    isTerminal: boolean;
+}
+/**
+ * Result of `NativeSimctl.getPermission` — mirrors the TCC database's own auth states rather than
+ * a plain boolean, since `'unset'` (never prompted/decided) and `'denied'` (explicitly refused)
+ * are different states with different UI implications. `'limited'` only applies to `photos`
+ * ("selected photos" access) and is never produced by `grantPermission` itself, but can already be
+ * present if something else set it.
+ */
+export type SimPermissionStatus = 'unset' | 'denied' | 'granted' | 'limited';
+/**
+ * A privacy permission grantable via `NativeSimctl.grantPermission`/`revokePermission`/
+ * `resetPermission`. Each is backed by a row in the simulator's own TCC (privacy) database —
+ * `location` isn't included since CoreLocation simulation has its own subsystem, not a plain TCC
+ * row (see CLAUDE.md).
+ */
+export type SimPermissionService = 'calendar' | 'camera' | 'contacts' | 'health' | 'homekit' | 'medialibrary' | 'microphone' | 'motion' | 'photos' | 'reminders' | 'siri' | 'speech';
+/**
+ * A device's renderable display, as returned by `NativeSimctl.getDisplays()`.
+ */
+export interface SimDisplayInfo {
+    /** Port UUID identifying this display — pass as `getScreenshot`'s `displayId` option to target it. */
+    id: string;
+    /** Raw `SimDisplayDescriptorState.displayClass` — 0 is always the primary display. */
+    displayClass: number;
+    /** Whether this is the primary display (`displayClass === 0`). */
+    isMain: boolean;
+}
+/** Options for `NativeSimctl.getScreenshot`. */
+export interface ScreenshotOptions {
+    /** Image encoding — defaults to `'png'`. */
+    format?: 'png' | 'jpeg';
+    /**
+     * Which display to capture, by `id` from `getDisplays()`. Defaults to the primary display
+     * (falling back to the first renderable display if none is primary, e.g. tvOS).
+     */
+    displayId?: string;
+    /**
+     * JPEG quality as a percentage (0 = smallest/most compressed, 100 = largest/least compressed).
+     * Only meaningful with `format: 'jpeg'` — ignored for `'png'`, which is always lossless.
+     * Defaults to ImageIO's own default (near-lossless) when omitted.
+     */
+    quality?: number;
+}
+/**
+ * Options for `NativeSimctl.spawnProcess`, passed through to CoreSimulator's
+ * `spawnWithPath:options:terminationQueue:terminationHandler:error:`. Only keys confirmed
+ * empirically (see CLAUDE.md) are typed here. CoreSimulator also recognizes
+ * `binpref`/`standalone`/`wait_for_debugger`/`enableCheckedAllocations`/`stdin`/`stdout`/`stderr`,
+ * but the latter three's expected value shape (`NSFileHandle`/XPC file descriptor/`NSNumber`,
+ * never a path string) isn't yet confirmed safe — passing the wrong type crashes the whole process
+ * instead of throwing a catchable error (see CLAUDE.md) — so they're deliberately omitted here.
+ */
+export interface SpawnOptions {
+    /** Fully replaces argv, including argv[0] — `path` only selects the executable. */
+    arguments?: string[];
+    /** Merged additively into the spawned process's environment. */
+    environment?: Record<string, string>;
+}
+/** One running process/launchd job inside a device, as reported by `NativeSimctl.listProcesses`. */
+export interface SimProcessInfo {
+    /** The process's real host OS pid (the simulator shares the host kernel). */
+    pid: number;
+    /** The launchd job's group, parsed from a label like `UIKitApplication:com.apple.app[...]` — `null` if the label has no group prefix. */
+    group: string | null;
+    /** The launchd job's name — a bundle identifier for an app process. */
+    name: string;
+}
+/** The `alert` field of {@link ApnsPayload}, when it's a dictionary rather than a plain string. */
+export interface ApnsAlert {
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    'title-loc-key'?: string;
+    'title-loc-args'?: string[];
+    'subtitle-loc-key'?: string;
+    'subtitle-loc-args'?: string[];
+    'loc-key'?: string;
+    'loc-args'?: string[];
+    'action-loc-key'?: string;
+    'launch-image'?: string;
+}
+/** The `sound` field of {@link ApnsPayload}, when it's a dictionary rather than a plain string. */
+export interface ApnsSound {
+    critical?: 0 | 1;
+    name?: string;
+    volume?: number;
+}
+/**
+ * The `aps` dictionary of a simulated push notification payload — see Apple's
+ * {@link https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification | Generating a Remote Notification}.
+ * Only the commonly used fields are typed; `[key: string]: unknown` covers newer/less common ones
+ * (e.g. Live Activity fields like `event`/`content-state`/`attributes-type`) without blocking them.
+ */
+export interface ApnsPayload {
+    alert?: string | ApnsAlert;
+    badge?: number;
+    sound?: string | ApnsSound;
+    'thread-id'?: string;
+    category?: string;
+    'content-available'?: 0 | 1;
+    'mutable-content'?: 0 | 1;
+    'target-content-id'?: string;
+    'interruption-level'?: 'passive' | 'active' | 'time-sensitive' | 'critical';
+    'relevance-score'?: number;
+    'filter-criteria'?: string;
+    [key: string]: unknown;
+}
+/**
+ * Payload for `NativeSimctl.pushNotification` — an `aps` key with valid Apple Push Notification
+ * content is required; a top-level `"Simulator Target Bundle"` key is not (the separate `bundleId`
+ * argument covers it). Additional top-level keys are allowed — APNs delivers them to the app as
+ * custom data alongside `aps`.
+ */
+export interface PushNotificationPayload {
+    aps: ApnsPayload;
+    [key: string]: unknown;
+}
+/**
+ * What `NativeDeviceHandle.spawn()` resolves with once the process has started — `stdoutFd`/
+ * `stderrFd` are raw, already-`dup()`'d file descriptors (see coresim.mm) ready to be wrapped in a
+ * `net.Socket({fd, readable: true, writable: false})` (not `fs.createReadStream`, which would
+ * block a shared libuv threadpool worker for as long as the pipe stays quiet — see
+ * commands/spawn.ts); `pid` is a real host OS process id, killable directly.
+ */
+export interface NativeSpawnResult {
+    pid: number;
+    stdoutFd: number;
+    stderrFd: number;
+}
+/**
+ * Decoded wait(2)-style exit status (see CLAUDE.md for how the raw status was confirmed),
+ * mirroring Node's own `ChildProcess` `'exit'` event — exactly one of `code`/`signal` is set.
+ */
+export type NativeSpawnExitCallback = (code: number | null, signal: number | null) => void;
+/** A `SimDevice`, wrapped by `coresim.mm`'s `NativeDevice` — what `NativeSimctl`'s `_findDevice()` resolves to. */
+export interface NativeDeviceHandle {
+    udid(): string;
+    name(): string;
+    state(): number;
+    deviceTypeIdentifier(): string;
+    runtimeIdentifier(): string;
+    boot(options?: Record<string, unknown>): Promise<void>;
+    getBootStatus(): Promise<SimBootInfo | null>;
+    shutdown(): Promise<void>;
+    erase(): Promise<void>;
+    getenv(name: string): Promise<string>;
+    installApp(path: string, options?: Record<string, unknown>): Promise<void>;
+    uninstallApp(bundleId: string, options?: Record<string, unknown>): Promise<void>;
+    launchApp(bundleId: string, options?: Record<string, unknown>): Promise<number>;
+    terminateApp(bundleId: string): Promise<void>;
+    propertiesOfApplication(bundleId: string): Promise<Record<string, unknown>>;
+    installedApps(): Promise<Record<string, unknown>>;
+    openUrl(url: string): Promise<void>;
+    setLocation(latitude: number, longitude: number): Promise<void>;
+    clearLocation(): Promise<void>;
+    sendPushNotification(bundleId: string, payload: PushNotificationPayload): Promise<void>;
+    addCertificate(path: string, trustAsRoot: boolean): Promise<void>;
+    resetKeychain(): Promise<void>;
+    getUIAppearance(): Promise<number>;
+    setUIAppearance(style: number): Promise<void>;
+    getIncreaseContrast(): Promise<number>;
+    setIncreaseContrast(enabled: boolean): Promise<void>;
+    getContentSize(): Promise<number>;
+    setContentSize(category: number): Promise<void>;
+    grantPermission(service: string, bundleId: string): Promise<void>;
+    revokePermission(service: string, bundleId: string): Promise<void>;
+    resetPermission(service: string, bundleId: string): Promise<void>;
+    getPermission(service: string, bundleId: string): Promise<SimPermissionStatus>;
+    darwinNotificationGetState(name: string): Promise<bigint>;
+    darwinNotificationSetState(name: string, state: bigint): Promise<void>;
+    postDarwinNotification(name: string): Promise<void>;
+    addMedia(filePaths: string[]): Promise<void>;
+    addPhoto(filePath: string): Promise<void>;
+    addVideo(filePath: string): Promise<void>;
+    getPasteboard(): Promise<string>;
+    setPasteboard(content: string): Promise<void>;
+    getWebInspectorSocket(): Promise<string>;
+    screenshot(options?: {
+        format?: 'png' | 'jpeg';
+        displayId?: string;
+        quality?: number;
+    }): Promise<Buffer>;
+    getDisplays(): Promise<SimDisplayInfo[]>;
+    spawn(path: string, options: SpawnOptions | undefined, onExit: NativeSpawnExitCallback): Promise<NativeSpawnResult>;
+}
+/** A `SimDeviceSet`, wrapped by `coresim.mm`'s `NativeDeviceSet`. */
+export interface NativeDeviceSetHandle {
+    devices(): Promise<NativeDeviceHandle[]>;
+    createDevice(deviceTypeIdentifier: string, runtimeIdentifier: string, name: string): Promise<NativeDeviceHandle>;
+    deleteDevice(device: NativeDeviceHandle): Promise<void>;
+}
+/** A `SimServiceContext`, wrapped by `coresim.mm`'s `NativeServiceContext`. */
+export interface NativeServiceContextHandle {
+    defaultDeviceSet(): Promise<NativeDeviceSetHandle>;
+    supportedDeviceTypes(): Promise<SimDeviceTypeInfo[]>;
+    supportedRuntimes(): Promise<SimRuntimeInfo[]>;
+}
+/** The addon's module-level exports (`coresim.mm`'s `Init`) — the return value of `require('node-gyp-build')(...)`. */
+export interface NativeCoreSimModule {
+    sharedServiceContext(developerDir: string): Promise<NativeServiceContextHandle>;
+    frameworkVersion(): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/lib/src/types.js

@@ -0,0 +1,29 @@
+/** Raw `SimDeviceState` enum values, as returned by `SimDevice.state`. */
+export var SimDeviceState;
+(function (SimDeviceState) {
+    SimDeviceState[SimDeviceState["Creating"] = 0] = "Creating";
+    SimDeviceState[SimDeviceState["Shutdown"] = 1] = "Shutdown";
+    SimDeviceState[SimDeviceState["Booting"] = 2] = "Booting";
+    SimDeviceState[SimDeviceState["Booted"] = 3] = "Booted";
+    SimDeviceState[SimDeviceState["ShuttingDown"] = 4] = "ShuttingDown";
+})(SimDeviceState || (SimDeviceState = {}));
+/**
+ * Raw `SimDeviceBootInfo.status` values — a separate, more granular boot-progress signal than
+ * {@link SimDeviceState}, and the one `simctl bootstatus` itself actually monitors (see CLAUDE.md
+ * for how this was confirmed: runtime introspection against the loaded framework, and empirical
+ * polling during a real boot). `SimDeviceState` reaching `Booted`
+ * only means the OS kernel/launchd has started — data migration and system-app (SpringBoard)
+ * startup, which these values track, can still take **20+ seconds longer** after that.
+ * `simctl bootstatus`'s own output also names a `WaitingOnBackboard` phase whose numeric value
+ * wasn't observed in testing (not every boot passes through it) — a `status` outside this enum's
+ * values should be treated as "not yet terminal, keep waiting", not as an error.
+ */
+export var SimBootStatus;
+(function (SimBootStatus) {
+    SimBootStatus[SimBootStatus["Booting"] = 0] = "Booting";
+    SimBootStatus[SimBootStatus["WaitingOnDataMigration"] = 2] = "WaitingOnDataMigration";
+    SimBootStatus[SimBootStatus["WaitingOnSystemApp"] = 4] = "WaitingOnSystemApp";
+    /** The only terminal value observed — `0xFFFFFFFF`. */
+    SimBootStatus[SimBootStatus["Finished"] = 4294967295] = "Finished";
+})(SimBootStatus || (SimBootStatus = {}));
+//# sourceMappingURL=types.js.map

package/lib/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,CAAN,IAAY,cAMX;AAND,WAAY,cAAc;IACxB,2DAAY,CAAA;IACZ,2DAAY,CAAA;IACZ,yDAAW,CAAA;IACX,uDAAU,CAAA;IACV,mEAAgB,CAAA;AAClB,CAAC,EANW,cAAc,KAAd,cAAc,QAMzB;AAiCD;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,aAMX;AAND,WAAY,aAAa;IACvB,uDAAW,CAAA;IACX,qFAA0B,CAAA;IAC1B,6EAAsB,CAAA;IACtB,uDAAuD;IACvD,kEAAqB,CAAA;AACvB,CAAC,EANW,aAAa,KAAb,aAAa,QAMxB"}

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

@@ -0,0 +1,3 @@
+export { getPkgRoot, PACKAGE_NAME } from './pkg-root.js';
+export { runCatchingAsync } from './run-catching.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AACvD,OAAO,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC"}

package/lib/src/utils/index.js

@@ -0,0 +1,3 @@
+export { getPkgRoot, PACKAGE_NAME } from './pkg-root.js';
+export { runCatchingAsync } from './run-catching.js';
+//# sourceMappingURL=index.js.map

package/lib/src/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AACvD,OAAO,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAC"}

package/lib/src/utils/pkg-root.d.ts

@@ -0,0 +1,6 @@
+export declare const PACKAGE_NAME = "@appium/coresim";
+/** Package root (contains binding.gyp, prebuilds/, or build/ after compile). */
+export declare const getPkgRoot: (() => string) & {
+    cache: Map<unknown, string>;
+};
+//# sourceMappingURL=pkg-root.d.ts.map

package/lib/src/utils/pkg-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkg-root.d.ts","sourceRoot":"","sources":["../../../src/utils/pkg-root.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,gFAAgF;AAChF,eAAO,MAAM,UAAU,SAA2C,MAAM;;CAMtE,CAAC"}

package/lib/src/utils/pkg-root.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from 'node:url';
+import { node, util } from '@appium/support';
+export const PACKAGE_NAME = '@appium/coresim';
+/** Package root (contains binding.gyp, prebuilds/, or build/ after compile). */
+export const getPkgRoot = util.memoize(function resolvePkgRoot() {
+    const root = node.getModuleRootSync(PACKAGE_NAME, fileURLToPath(import.meta.url));
+    if (!root) {
+        throw new Error(`Could not locate the root of the '${PACKAGE_NAME}' package`);
+    }
+    return root;
+});
+//# sourceMappingURL=pkg-root.js.map

package/lib/src/utils/pkg-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkg-root.js","sourceRoot":"","sources":["../../../src/utils/pkg-root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAC,IAAI,EAAE,IAAI,EAAC,MAAM,iBAAiB,CAAC;AAE3C,MAAM,CAAC,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAE9C,gFAAgF;AAChF,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,cAAc;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,qCAAqC,YAAY,WAAW,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC,CAAC"}

package/lib/src/utils/run-catching.d.ts

@@ -0,0 +1,3 @@
+/** Shared by NativeSimctl and every `src/commands/*.ts` mixin — maps a raw error surfaced by the addon to a typed one. */
+export declare function runCatchingAsync<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=run-catching.d.ts.map

package/lib/src/utils/run-catching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-catching.d.ts","sourceRoot":"","sources":["../../../src/utils/run-catching.ts"],"names":[],"mappings":"AAEA,0HAA0H;AAC1H,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1E"}

package/lib/src/utils/run-catching.js

@@ -0,0 +1,11 @@
+import { wrapNativeError } from '../errors.js';
+/** Shared by NativeSimctl and every `src/commands/*.ts` mixin — maps a raw error surfaced by the addon to a typed one. */
+export async function runCatchingAsync(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        wrapNativeError(err);
+    }
+}
+//# sourceMappingURL=run-catching.js.map

package/lib/src/utils/run-catching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-catching.js","sourceRoot":"","sources":["../../../src/utils/run-catching.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAE7C,0HAA0H;AAC1H,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,EAAoB;IAC5D,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,eAAe,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@appium/coresim",
+  "version": "1.0.0",
+  "description": "Native bindings to CoreSimulator.framework for Apple platform simulator control",
+  "bugs": {
+    "url": "https://github.com/appium/coresim/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Appium Contributors",
+    "url": "https://github.com/appium/coresim"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appium/coresim.git"
+  },
+  "files": [
+    "src",
+    "lib/src",
+    "prebuilds",
+    "scripts/install.mjs",
+    "binding.gyp",
+    "package.json",
+    "README.md",
+    "!.DS_Store",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "lib/src/index.js",
+  "types": "lib/src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf build node_modules lib",
+    "build": "tsc -b",
+    "build:addon": "node-gyp rebuild",
+    "build:addon:xcodebuild": "node-gyp configure -- -f xcode && xcodebuild -project build/binding.xcodeproj -target coresim -configuration Release build",
+    "build:prebuilds": "prebuildify --napi --strip",
+    "lint": "oxlint -c oxlint.config.mjs .",
+    "lint:fix": "oxlint -c oxlint.config.mjs --fix .",
+    "lint:cpp": "npm run build:compile-commands && bash scripts/ci/lint-cpp.sh",
+    "format": "oxfmt -c oxfmt.config.mjs .",
+    "format:check": "oxfmt -c oxfmt.config.mjs --check .",
+    "format:cpp": "clang-format -i src/coresim.mm src/native/*.mm src/native/*.h",
+    "format:cpp:check": "clang-format --dry-run --Werror src/coresim.mm src/native/*.mm src/native/*.h",
+    "build:compile-commands": "node-gyp configure -- -f compile_commands_json",
+    "install": "node scripts/install.mjs",
+    "prepare": "npm run build",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "node --enable-source-maps --test --test-force-exit --test-timeout=15000 \"lib/test/unit/**/*.spec.js\"",
+    "test:integration": "node --enable-source-maps --test --test-force-exit --test-concurrency=1 --test-timeout=1200000 \"lib/test/integration/**/*.spec.js\""
+  },
+  "dependencies": {
+    "@appium/support": "^7.2.0",
+    "asyncbox": "^6.4.3",
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@appium/oxc-config": "^1.1.0",
+    "@appium/semantic-release-config": "^1.1.0",
+    "@appium/tsconfig": "^1.2.0",
+    "@types/node": "^26.1.2",
+    "prebuildify": "^6.0.1"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+    "npm": ">=10"
+  },
+  "gypfile": true
+}

package/scripts/install.mjs

@@ -0,0 +1,22 @@
+import {execFileSync} from 'node:child_process';
+
+// Overridable only for test/unit/install-script.spec.ts, which spawns this file as a real
+// subprocess to verify the skip branch without needing to fake process.platform themselves.
+const platform = process.env.CORESIM_TEST_PLATFORM ?? process.platform;
+
+// CoreSimulator.framework only exists on macOS — there's nothing to build or load anywhere else.
+// Skip straight to a no-op there so `npm install` always succeeds regardless of platform; the
+// package still installs fine (its TS/error-class surface is plain JS), it just throws a clear,
+// typed error the first time native functionality is actually used (see native-simctl.ts's
+// loadNative()). Any macOS arch is fine here — an Intel Mac just compiles from source instead of
+// using the darwin-arm64 prebuild.
+if (platform !== 'darwin') {
+  process.stdout.write(
+    `[@appium/coresim] Skipping native addon build: CoreSimulator.framework requires macOS ` +
+      `(current platform: ${platform}). This package will throw a NativeSimUnavailableError at ` +
+      'runtime if used here.\n',
+  );
+  process.exit(0);
+}
+
+execFileSync('node-gyp-build', {stdio: 'inherit', shell: true});