@phone-use/sdk 0.1.0

package/src/backend.ts

@@ -0,0 +1,185 @@
+import type { DeviceConfig } from './config.ts';
+import type {
+  AlertAction,
+  BackendAlertResult,
+  Capability,
+  OpenAppResult,
+  PressTarget,
+  ScrollDirection,
+  Snapshot,
+} from './device.ts';
+import { PhoneUseError, UnsupportedCapabilityError } from './errors.ts';
+
+/**
+ * The backend contract (docs/19 §Backend contract): a STRUCTURAL interface —
+ * any object with these methods is a backend — plus an optional
+ * {@link BaseDeviceBackend} class with the plumbing done (Appium BaseDriver
+ * ergonomics). Methods reject only with PhoneUseError subclasses; backends
+ * normalize their transport's errors at the boundary.
+ */
+export interface DeviceBackend {
+  /** Stable backend identifier, e.g. `"agent-device"`. */
+  readonly backendName: string;
+  /** The capabilities this backend actually implements. */
+  readonly capabilities: ReadonlySet<Capability>;
+
+  /** Capture the accessibility tree of the frontmost app. */
+  snapshot(opts?: { interactiveOnly?: boolean | undefined; depth?: number | undefined }): Promise<Snapshot>;
+  /** Save a screenshot to `path` (optionally with `@ref` overlays drawn). */
+  screenshot(opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }>;
+  /** Tap an element ref or raw coordinates. */
+  press(target: PressTarget): Promise<void>;
+  /** Long-press an element ref. */
+  longPress(ref: string, durationMs?: number): Promise<void>;
+  /** Focus an element and replace its text. */
+  fill(ref: string, text: string): Promise<void>;
+  /** Type into whatever currently has keyboard focus. */
+  typeText(text: string): Promise<void>;
+  /** Press a hardware/keyboard key (Return only, this cycle). */
+  pressKey(key: 'return'): Promise<void>;
+  /** Scroll the active scroll view one step. */
+  scroll(direction: ScrollDirection): Promise<void>;
+  /** Coordinate drag: touch down at (x,y), move by (dx,dy). Operates picker wheels, sliders, carousels. */
+  pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void>;
+  /** Block until `text` appears on screen or the timeout elapses. */
+  waitForText(text: string, timeoutMs?: number): Promise<void>;
+  /** Read/accept/dismiss the app's own alert via the transport's alert command. */
+  systemAlert(action: AlertAction): Promise<BackendAlertResult>;
+  /** Go to the home screen. */
+  home(): Promise<void>;
+  /** Navigate back (hardware back / nav-bar back). */
+  back(): Promise<void>;
+  /** Open an app by name/bundle id, or a URL (deep link). */
+  openApp(opts: {
+    app?: string | undefined;
+    url?: string | undefined;
+    relaunch?: boolean | undefined;
+  }): Promise<OpenAppResult>;
+  /** List installed app bundle ids. */
+  listApps(): Promise<string[]>;
+  /** Close the transport session (idempotent; safe when none is open). */
+  closeSession(): Promise<void>;
+}
+
+/**
+ * Optional plumbing base: every method rejects with a typed
+ * UnsupportedCapabilityError until overridden. Subclasses declare their
+ * capability set and override exactly what they support.
+ */
+export abstract class BaseDeviceBackend implements DeviceBackend {
+  readonly backendName: string;
+  readonly capabilities: ReadonlySet<Capability>;
+
+  protected constructor(backendName: string, capabilities: Iterable<Capability>) {
+    this.backendName = backendName;
+    this.capabilities = new Set(capabilities);
+  }
+
+  protected unsupported(capability: Capability): UnsupportedCapabilityError {
+    return new UnsupportedCapabilityError({ backend: this.backendName, capability });
+  }
+
+  /** Throws UnsupportedCapabilityError unless this backend declares `capability`. */
+  requireCapability(capability: Capability): void {
+    if (!this.capabilities.has(capability)) throw this.unsupported(capability);
+  }
+
+  snapshot(_opts?: { interactiveOnly?: boolean | undefined; depth?: number | undefined }): Promise<Snapshot> {
+    return Promise.reject(this.unsupported('snapshot'));
+  }
+  screenshot(_opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }> {
+    return Promise.reject(this.unsupported('screenshot'));
+  }
+  press(_target: PressTarget): Promise<void> {
+    return Promise.reject(this.unsupported('press'));
+  }
+  longPress(_ref: string, _durationMs?: number): Promise<void> {
+    return Promise.reject(this.unsupported('longPress'));
+  }
+  fill(_ref: string, _text: string): Promise<void> {
+    return Promise.reject(this.unsupported('fill'));
+  }
+  typeText(_text: string): Promise<void> {
+    return Promise.reject(this.unsupported('type'));
+  }
+  pressKey(_key: 'return'): Promise<void> {
+    return Promise.reject(this.unsupported('key'));
+  }
+  scroll(_direction: ScrollDirection): Promise<void> {
+    return Promise.reject(this.unsupported('scroll'));
+  }
+  pan(_x: number, _y: number, _dx: number, _dy: number, _durationMs?: number): Promise<void> {
+    return Promise.reject(this.unsupported('pan'));
+  }
+  waitForText(_text: string, _timeoutMs?: number): Promise<void> {
+    return Promise.reject(this.unsupported('waitForText'));
+  }
+  systemAlert(_action: AlertAction): Promise<BackendAlertResult> {
+    return Promise.reject(this.unsupported('alert'));
+  }
+  home(): Promise<void> {
+    return Promise.reject(this.unsupported('home'));
+  }
+  back(): Promise<void> {
+    return Promise.reject(this.unsupported('back'));
+  }
+  openApp(_opts: {
+    app?: string | undefined;
+    url?: string | undefined;
+    relaunch?: boolean | undefined;
+  }): Promise<OpenAppResult> {
+    return Promise.reject(this.unsupported('openApp'));
+  }
+  listApps(): Promise<string[]> {
+    return Promise.reject(this.unsupported('listApps'));
+  }
+  closeSession(): Promise<void> {
+    return Promise.reject(this.unsupported('closeSession'));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Runtime backend registry (registerBackend + phone-backend-* convention,
+// docs/19). A deliberate module-level Map: this IS the registry — mirrored on
+// permissions.ts's documented pattern; the item-2 grep audit is scoped to
+// driver code.
+// ---------------------------------------------------------------------------
+
+/** Builds a backend from an optional {@link DeviceConfig}. */
+export type BackendFactory = (config?: DeviceConfig) => DeviceBackend | Promise<DeviceBackend>;
+
+const factories = new Map<string, BackendFactory>();
+
+/**
+ * Register a backend factory under a unique name (the `phone-backend-*`
+ * convention for third parties). Throws if the name is already taken.
+ */
+export function registerBackend(name: string, factory: BackendFactory): void {
+  if (factories.has(name)) {
+    throw new PhoneUseError(`backend "${name}" is already registered`, {
+      code: 'ACTION_FAILED',
+      retryable: false,
+    });
+  }
+  factories.set(name, factory);
+}
+
+/** Look up a registered factory by name; throws `BACKEND_NOT_FOUND` if absent. */
+export function getBackendFactory(name: string): BackendFactory {
+  const factory = factories.get(name);
+  if (!factory) {
+    throw new PhoneUseError(
+      `no backend named "${name}" — registered: ${[...factories.keys()].join(', ') || '(none)'}`,
+      {
+        code: 'BACKEND_NOT_FOUND',
+        retryable: false,
+      },
+    );
+  }
+  return factory;
+}
+
+/** Names of every registered backend, in registration order. */
+export function listBackends(): string[] {
+  return [...factories.keys()];
+}

package/src/backends/agent-device.ts

@@ -0,0 +1,242 @@
+import { createAgentDeviceClient } from 'agent-device';
+import type { DeviceBackend } from '../backend.ts';
+import { BaseDeviceBackend } from '../backend.ts';
+import type { DeviceConfig } from '../config.ts';
+import type {
+  AlertAction,
+  BackendAlertResult,
+  Capability,
+  OpenAppResult,
+  PressTarget,
+  ScrollDirection,
+  Snapshot,
+} from '../device.ts';
+import { ALL_CAPABILITIES } from '../device.ts';
+import { toPhoneUseError } from '../errors.ts';
+
+// ---------------------------------------------------------------------------
+// The agent-device backend: the ONE place agent-device is called. Device
+// pinning is per-request in agent-device (AgentDeviceSelectionOptions), so a
+// backend holds a selection object and spreads it into every call. With no
+// config, selection is {} and the client is default-constructed — requests are
+// byte-identical to the pre-seam process-global path (booted-sim auto-detect),
+// which is the item-2 backward-compat guarantee (docs/20 risk: default-
+// selection drift).
+//
+// Every method normalizes errors via toPhoneUseError — no agent-device type
+// or error ever escapes this file.
+// ---------------------------------------------------------------------------
+
+type AdClient = ReturnType<typeof createAgentDeviceClient>;
+
+class AgentDeviceBackend extends BaseDeviceBackend {
+  private readonly client: AdClient;
+  private readonly selection: Record<string, unknown>;
+  // Sessions are lazy daemon-side: nothing exists to close until a first real
+  // call is made, and asking the daemon anyway would SPAWN one on hosts where
+  // it isn't running (observed in the Mac verification sweep).
+  private used = false;
+
+  constructor(config?: DeviceConfig) {
+    super('agent-device', ALL_CAPABILITIES);
+    this.client = createAgentDeviceClient(
+      config &&
+        (config.session !== undefined ||
+          config.daemonBaseUrl !== undefined ||
+          config.daemonAuthToken !== undefined)
+        ? {
+            ...(config.session === undefined ? {} : { session: config.session }),
+            ...(config.daemonBaseUrl === undefined ? {} : { daemonBaseUrl: config.daemonBaseUrl }),
+            ...(config.daemonAuthToken === undefined ? {} : { daemonAuthToken: config.daemonAuthToken }),
+          }
+        : undefined,
+    );
+    this.selection = !config
+      ? {}
+      : {
+          platform: config.platform,
+          ...(config.device === undefined ? {} : { device: config.device }),
+          ...(config.platform === 'ios' && config.udid !== undefined ? { udid: config.udid } : {}),
+          ...(config.platform === 'ios' && config.simulatorDeviceSet !== undefined
+            ? { iosSimulatorDeviceSet: config.simulatorDeviceSet }
+            : {}),
+          ...(config.platform === 'android' && config.serial !== undefined ? { serial: config.serial } : {}),
+        };
+  }
+
+  private async guard<T>(capability: Capability, fn: () => Promise<T>): Promise<T> {
+    if (capability !== 'closeSession') this.used = true;
+    try {
+      return await fn();
+    } catch (error) {
+      throw toPhoneUseError(error, { backend: this.backendName, capability });
+    }
+  }
+
+  override snapshot(opts?: {
+    interactiveOnly?: boolean | undefined;
+    depth?: number | undefined;
+  }): Promise<Snapshot> {
+    return this.guard('snapshot', async () => {
+      const snap = await this.client.capture.snapshot({
+        ...this.selection,
+        ...(opts?.interactiveOnly === undefined ? {} : { interactiveOnly: opts.interactiveOnly }),
+        ...(opts?.depth === undefined ? {} : { depth: opts.depth }),
+      });
+      return { nodes: snap.nodes, appName: snap.appName, appBundleId: snap.appBundleId };
+    });
+  }
+
+  override screenshot(opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }> {
+    return this.guard('screenshot', async () => {
+      const result = await this.client.capture.screenshot({
+        ...this.selection,
+        path: opts.path,
+        ...(opts.overlayRefs === undefined ? {} : { overlayRefs: opts.overlayRefs }),
+      });
+      return { path: result.path };
+    });
+  }
+
+  override press(target: PressTarget): Promise<void> {
+    return this.guard('press', async () => {
+      await this.client.interactions.press({ ...this.selection, ...target });
+    });
+  }
+
+  override longPress(ref: string, durationMs?: number): Promise<void> {
+    return this.guard('longPress', async () => {
+      // settle: true preserved exactly from the pre-seam driver.
+      await this.client.interactions.longPress({
+        ...this.selection,
+        ref,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        settle: true,
+      });
+    });
+  }
+
+  override fill(ref: string, text: string): Promise<void> {
+    return this.guard('fill', async () => {
+      await this.client.interactions.fill({ ...this.selection, ref, text });
+    });
+  }
+
+  override typeText(text: string): Promise<void> {
+    return this.guard('type', async () => {
+      await this.client.interactions.type({ ...this.selection, text });
+    });
+  }
+
+  override pressKey(_key: 'return'): Promise<void> {
+    return this.guard('key', async () => {
+      await this.client.command.keyboard({ ...this.selection, action: 'return' });
+    });
+  }
+
+  override scroll(direction: ScrollDirection): Promise<void> {
+    return this.guard('scroll', async () => {
+      const args = { ...this.selection, direction } as Parameters<AdClient['interactions']['scroll']>[0];
+      await this.client.interactions.scroll(args);
+    });
+  }
+
+  override pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void> {
+    return this.guard('pan', async () => {
+      await this.client.interactions.pan({
+        ...this.selection,
+        x,
+        y,
+        dx,
+        dy,
+        ...(durationMs === undefined ? {} : { durationMs }),
+      });
+    });
+  }
+
+  override waitForText(text: string, timeoutMs?: number): Promise<void> {
+    return this.guard('waitForText', async () => {
+      await this.client.command.wait({
+        ...this.selection,
+        text,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      });
+    });
+  }
+
+  override systemAlert(action: AlertAction): Promise<BackendAlertResult> {
+    return this.guard('alert', async () => {
+      const result = (await this.client.command.alert({ ...this.selection, action })) as {
+        alert?: { title?: string; message?: string; buttons?: string[] } | null;
+        handled?: boolean;
+        button?: string;
+      };
+      return { alert: result.alert, handled: result.handled, button: result.button };
+    });
+  }
+
+  override home(): Promise<void> {
+    return this.guard('home', async () => {
+      await this.client.command.home({ ...this.selection });
+    });
+  }
+
+  override back(): Promise<void> {
+    return this.guard('back', async () => {
+      await this.client.command.back({ ...this.selection });
+    });
+  }
+
+  override openApp(opts: {
+    app?: string | undefined;
+    url?: string | undefined;
+    relaunch?: boolean | undefined;
+  }): Promise<OpenAppResult> {
+    return this.guard('openApp', async () => {
+      // Preserve the pre-seam arg branching exactly:
+      //   {app, relaunch} for app launches; {app, url} | {url} for deep links.
+      const args =
+        opts.url === undefined
+          ? { app: opts.app, ...(opts.relaunch === undefined ? {} : { relaunch: opts.relaunch }) }
+          : opts.app !== undefined
+            ? { app: opts.app, url: opts.url }
+            : { url: opts.url };
+      const result = (await this.client.apps.open({ ...this.selection, ...args } as Parameters<
+        AdClient['apps']['open']
+      >[0])) as { appName?: string; appBundleId?: string };
+      return { appName: result.appName, appBundleId: result.appBundleId };
+    });
+  }
+
+  override listApps(): Promise<string[]> {
+    return this.guard('listApps', async () => {
+      const result = (await this.client.apps.list(
+        Object.keys(this.selection).length
+          ? (this.selection as Parameters<AdClient['apps']['list']>[0])
+          : undefined,
+      )) as unknown as string[];
+      return result;
+    });
+  }
+
+  override closeSession(): Promise<void> {
+    if (!this.used) return Promise.resolve();
+    return this.guard('closeSession', async () => {
+      // Pre-seam behavior: close({}) — session override only when pinned.
+      await this.client.sessions.close({ ...this.selection });
+    });
+  }
+}
+
+/**
+ * Build the agent-device backend: the ONE place agent-device is called. Device
+ * pinning is per-request in agent-device, so the backend holds a selection
+ * object and spreads it into every call. With no config, selection is `{}` and
+ * the client is default-constructed — requests are byte-identical to the
+ * pre-seam process-global path (booted-sim auto-detect). Every method
+ * normalizes errors via `toPhoneUseError`; no agent-device type or error ever
+ * escapes this module.
+ */
+export function createAgentDeviceBackend(config?: DeviceConfig): DeviceBackend {
+  return new AgentDeviceBackend(config);
+}

package/src/backends/ios.ts

@@ -0,0 +1,262 @@
+import type { IosDeviceConfig } from '../config.ts';
+import { ActionFailedError, DeviceNotFoundError, TimeoutError, toPhoneUseError } from '../errors.ts';
+import { defaultExecRunner, type ExecRunner, isExecError } from '../exec.ts';
+import { createDeviceHandle, type Device } from '../lifecycle.ts';
+import { createAgentDeviceBackend } from './agent-device.ts';
+
+// ---------------------------------------------------------------------------
+// The iOS engine (docs/19 §Lifecycle, engine-as-object): ios.launch() creates
+// and boots a DEDICATED simulator via simctl — no more "whatever is booted" —
+// and returns a Device whose backend is pinned to that udid. ios.connect()
+// reattaches; its no-arg form is the sole survivor of the old booted-sim
+// auto-detect. Scripts never branch on locality: connect(endpoint) for cloud
+// devices is reserved API (docs/20 kill list — local-only this cycle).
+//
+// Created sims are named `phone-use-<hex>` deliberately: if a process is
+// kill -9'd, the in-process reaper can't run, and the name prefix is how
+// orphans are found (`xcrun simctl list devices -j` | filter the prefix).
+// ---------------------------------------------------------------------------
+
+type CommonIosOptions = {
+  /** Custom simulator device set directory (maps to `simctl --set`). */
+  simulatorDeviceSet?: string | undefined;
+  /** agent-device session/daemon pinning, passed through to the backend. */
+  session?: string | undefined;
+  daemonBaseUrl?: string | undefined;
+  daemonAuthToken?: string | undefined;
+  /** Idle lease window in ms (false disables). Default 180_000 (3 min). */
+  idleTimeoutMs?: number | false | undefined;
+  /** Observer for reaper-initiated closes. */
+  onIdleClose?: ((device: Device) => void) | undefined;
+  /** Initial %name% secret values (see Device.secrets). */
+  secrets?: Record<string, string> | undefined;
+  /** @internal harness seam — supplies the verb core (see createDeviceHandle). */
+  coreFactory?:
+    | ((backend: import('../backend.ts').DeviceBackend) => import('../observe.ts').DeviceCore)
+    | undefined;
+  /**
+   * Probe the agent-device daemon right away (one listApps) so a missing
+   * daemon fails at launch instead of on first use. Default false: sessions
+   * open lazily and a probe requires the daemon to exist.
+   */
+  failFast?: boolean | undefined;
+  /** @internal test seam — DI'd process runner (docs/19 test strategy). */
+  exec?: ExecRunner | undefined;
+};
+
+/** Options for `ios.launch()` — device type, runtime, name, boot ceiling. */
+export type IosLaunchOptions = CommonIosOptions & {
+  /** simctl device type, e.g. "iPhone 16" (the default). */
+  deviceType?: string | undefined;
+  /** simctl runtime id; omitted → newest compatible. */
+  runtime?: string | undefined;
+  /** Simulator name; default `phone-use-<hex>` (the orphan-discovery prefix). */
+  name?: string | undefined;
+  /** Boot wait ceiling for `simctl bootstatus` (default 120_000 ms). */
+  bootTimeoutMs?: number | undefined;
+};
+
+/** Options for `ios.connect()`. */
+export type IosConnectOptions = CommonIosOptions & {
+  /** Boot wait ceiling when connect has to boot a shut-down sim (default 120_000 ms). */
+  bootTimeoutMs?: number | undefined;
+};
+
+const UDID_RE = /^[0-9A-F]{8}(-[0-9A-F]{4}){3}-[0-9A-F]{12}$/i;
+
+type SimctlDeviceRow = { udid: string; state: string; name?: string; isAvailable?: boolean };
+type SimctlList = { devices: Record<string, SimctlDeviceRow[]> };
+
+function simctlArgs(setPath: string | undefined, args: string[]): string[] {
+  return setPath === undefined ? ['simctl', ...args] : ['simctl', '--set', setPath, ...args];
+}
+
+// Exit 149 = "operation not allowed in current state" (already booted /
+// already shut down). Code first, stderr regex as fallback — Apple rewords
+// messages; the numeric code is a Mac-verification item (docs/20 as-built).
+function isAlreadyInState(err: unknown): boolean {
+  if (!isExecError(err)) return false;
+  if (err.code === 149) return true;
+  return /current state.*(Booted|Shutdown)/i.test(err.stderr ?? '');
+}
+
+async function runSimctl(
+  exec: ExecRunner,
+  setPath: string | undefined,
+  args: string[],
+  opts: { timeoutMs?: number | undefined; tolerateState?: boolean | undefined } = {},
+): Promise<string> {
+  try {
+    const r = await exec(
+      'xcrun',
+      simctlArgs(setPath, args),
+      opts.timeoutMs === undefined ? undefined : { timeoutMs: opts.timeoutMs },
+    );
+    return r.stdout;
+  } catch (err) {
+    if (opts.tolerateState && isAlreadyInState(err)) return '';
+    if (isExecError(err)) {
+      if (err.killed || err.signal) {
+        throw new TimeoutError(
+          `simctl ${args[0]} timed out${opts.timeoutMs ? ` after ${opts.timeoutMs}ms` : ''}`,
+          {
+            cause: err,
+          },
+        );
+      }
+      throw new ActionFailedError(
+        `simctl ${args[0]} failed (exit ${String(err.code ?? '?')}): ${(err.stderr ?? err.message).trim()}`,
+        { details: { backendCode: String(err.code ?? 'EXEC') }, cause: err },
+      );
+    }
+    throw toPhoneUseError(err);
+  }
+}
+
+function parseCreatedUdid(stdout: string): string {
+  const lines = stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const last = lines[lines.length - 1] ?? '';
+  if (!UDID_RE.test(last)) {
+    throw new ActionFailedError(
+      `could not parse udid from simctl create output: ${JSON.stringify(stdout.slice(0, 200))}`,
+    );
+  }
+  return last;
+}
+
+function parseList(stdout: string): SimctlDeviceRow[] {
+  let parsed: SimctlList;
+  try {
+    parsed = JSON.parse(stdout) as SimctlList;
+  } catch (err) {
+    throw new ActionFailedError('could not parse simctl list output as JSON', { cause: err });
+  }
+  return Object.values(parsed.devices ?? {}).flat();
+}
+
+function makeBackendConfig(udid: string, opts: CommonIosOptions): IosDeviceConfig {
+  return {
+    platform: 'ios',
+    udid,
+    ...(opts.simulatorDeviceSet === undefined ? {} : { simulatorDeviceSet: opts.simulatorDeviceSet }),
+    // The daemon binds one session to one device: a udid-pinned Device on the
+    // shared "default" session collides with whatever bound it first (live
+    // Mac finding). A udid-derived session name is what makes two Devices
+    // independent; deterministic so reconnects reuse the same session.
+    session: opts.session ?? `phone-use-${udid}`,
+    ...(opts.daemonBaseUrl === undefined ? {} : { daemonBaseUrl: opts.daemonBaseUrl }),
+    ...(opts.daemonAuthToken === undefined ? {} : { daemonAuthToken: opts.daemonAuthToken }),
+  };
+}
+
+async function bootAndWait(
+  exec: ExecRunner,
+  setPath: string | undefined,
+  udid: string,
+  bootTimeoutMs: number,
+): Promise<void> {
+  await runSimctl(exec, setPath, ['boot', udid], { tolerateState: true });
+  // -b boots if needed, closing the boot/bootstatus race; blocks until booted.
+  await runSimctl(exec, setPath, ['bootstatus', udid, '-b'], { timeoutMs: bootTimeoutMs });
+}
+
+async function finishHandle(
+  udid: string,
+  name: string | undefined,
+  createdByUs: boolean,
+  opts: CommonIosOptions,
+  exec: ExecRunner,
+): Promise<Device> {
+  const backend = createAgentDeviceBackend(makeBackendConfig(udid, opts));
+  if (opts.failFast) await backend.listApps();
+  return createDeviceHandle({
+    id: udid,
+    platform: 'ios',
+    name,
+    backend,
+    createdByUs,
+    idleTimeoutMs: opts.idleTimeoutMs,
+    onIdleClose: opts.onIdleClose,
+    secrets: opts.secrets,
+    coreFactory: opts.coreFactory,
+    doClose: async () => {
+      await runSimctl(exec, opts.simulatorDeviceSet, ['shutdown', udid], { tolerateState: true });
+      if (createdByUs) await runSimctl(exec, opts.simulatorDeviceSet, ['delete', udid]);
+    },
+  });
+}
+
+/**
+ * Create and boot a DEDICATED simulator via simctl — no more "whatever is
+ * booted" — and return a {@link Device} pinned to its udid. Created sims are
+ * named `phone-use-<hex>` deliberately: if the process is kill -9'd the
+ * in-process reaper can't run, and the name prefix is how orphans are found.
+ * `close()` shuts the sim down AND deletes it (we created it); a failed boot
+ * best-effort-deletes before rethrowing.
+ */
+async function launch(options: IosLaunchOptions = {}): Promise<Device> {
+  const exec = options.exec ?? defaultExecRunner;
+  const deviceType = options.deviceType ?? 'iPhone 16';
+  const name = options.name ?? `phone-use-${Math.random().toString(16).slice(2, 10)}`;
+  const bootTimeoutMs = options.bootTimeoutMs ?? 120_000;
+
+  const createArgs = [
+    'create',
+    name,
+    deviceType,
+    ...(options.runtime === undefined ? [] : [options.runtime]),
+  ];
+  const udid = parseCreatedUdid(await runSimctl(exec, options.simulatorDeviceSet, createArgs));
+
+  try {
+    await bootAndWait(exec, options.simulatorDeviceSet, udid, bootTimeoutMs);
+  } catch (err) {
+    // We created it and it never booted — best-effort delete so the failure
+    // doesn't leak a sim, then rethrow the original error.
+    await runSimctl(exec, options.simulatorDeviceSet, ['delete', udid]).catch(() => undefined);
+    throw err;
+  }
+
+  return finishHandle(udid, name, true, options, exec);
+}
+
+/**
+ * Reattach to an existing simulator by udid (booting it if shut down). The
+ * no-arg form is the sole survivor of the old booted-sim auto-detect: it
+ * attaches to the first booted, available sim. `close()` on a connected
+ * device shuts it down but never deletes it.
+ */
+async function connect(udid?: string, options: IosConnectOptions = {}): Promise<Device> {
+  const exec = options.exec ?? defaultExecRunner;
+  const bootTimeoutMs = options.bootTimeoutMs ?? 120_000;
+
+  if (udid === undefined) {
+    // The surviving auto-detect: attach to the first booted, available sim.
+    const rows = parseList(
+      await runSimctl(exec, options.simulatorDeviceSet, ['list', 'devices', 'booted', '-j']),
+    );
+    const booted = rows.find((d) => d.state === 'Booted' && d.isAvailable !== false);
+    if (!booted) throw new DeviceNotFoundError('no booted simulator — use ios.launch() or boot one');
+    return finishHandle(booted.udid, booted.name, false, options, exec);
+  }
+
+  const rows = parseList(await runSimctl(exec, options.simulatorDeviceSet, ['list', 'devices', '-j']));
+  const row = rows.find((d) => d.udid.toLowerCase() === udid.toLowerCase());
+  if (!row) throw new DeviceNotFoundError(`no simulator with udid ${udid}`);
+  if (row.state !== 'Booted') await bootAndWait(exec, options.simulatorDeviceSet, row.udid, bootTimeoutMs);
+  return finishHandle(row.udid, row.name, false, options, exec);
+}
+
+/**
+ * The iOS engine object (Playwright-style): `ios.launch()` for a dedicated
+ * simulator, `ios.connect()` to reattach. Both return the same Device type.
+ */
+export const ios = {
+  /** Create + boot a dedicated simulator and return a Device pinned to it. */
+  launch,
+  /** Reattach to an existing simulator (no-arg: first booted sim). */
+  connect,
+} as const;