@phone-use/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,689 @@
+import { A as Snapshot, C as AlertAction, D as PressTarget, E as OpenAppResult, O as Rect, S as ALL_CAPABILITIES, T as Capability, _ as PhoneUseErrorDetails, a as listBackends, b as UnsupportedCapabilityError, c as CommonDeviceConfig, d as AbortedError, f as ActionFailedError, g as PhoneUseErrorCode, h as PhoneUseError, i as getBackendFactory, j as SnapshotNode, k as ScrollDirection, l as DeviceConfig, m as DeviceNotFoundError, n as BaseDeviceBackend, o as registerBackend, p as DeviceInUseError, r as DeviceBackend, s as AndroidDeviceConfig, t as BackendFactory, u as IosDeviceConfig, v as SessionNotFoundError, w as BackendAlertResult, x as toPhoneUseError, y as TimeoutError } from "./backend-Cbr2tIN-.mjs";
+//#region src/observe.d.ts
+/** One compressed observation: the frontmost app plus the rendered element list. */
+type Observation = {
+  /** Frontmost app name, when known. */
+  app?: string | undefined;
+  /** Frontmost app bundle id, when known. */
+  bundleId?: string | undefined;
+  /** Whether the element list was truncated. */
+  truncated: boolean;
+  /** The compressed, human/LLM-readable element listing. */
+  elements: string;
+};
+/**
+ * Post-action evidence from the driver's verify pass: whether the
+ * accessibility tree changed, without paying for a full follow-up snapshot.
+ */
+type ActionEvidence = {
+  /** Did the tree fingerprint change across the action. */
+  changed?: boolean | undefined;
+  /** Human-readable verdict detail. */
+  detail?: string | undefined;
+};
+/** The delta renderer's baseline: last rendered app, element keys, and lines. */
+type RenderState = {
+  app?: string | undefined;
+  keys: string[];
+  lineByKey: Map<string, string>;
+};
+/** A structured interactive element extracted from the snapshot cache. */
+type UiElement = {
+  /** Snapshot-scoped element ref (normalized to the `@N` form). */
+  ref: string;
+  /** Visible label (or accessibility identifier when the label is empty). */
+  label: string;
+  /** Semantic role, e.g. "Button", "Cell", "Switch". */
+  role: string;
+  /** Current value ("1"/"0" for switches, field contents, ...). */
+  value?: string | undefined;
+  /** On-screen geometry when known. */
+  rect?: Rect | undefined;
+  /** Accessibility identifier when the app exposes one. */
+  id?: string | undefined;
+  /** false when the element is disabled. */
+  enabled?: boolean | undefined;
+  /** Reason interaction is blocked, when the tree reports one. */
+  blocked?: string | undefined;
+};
+/**
+ * Does a label match a query — by substring, or a strict punctuation/spacing-
+ * tolerant fuzzy match? Shared by the task layer's cached-map lookups so
+ * ask/toggle tolerate rewording the same way findElement does.
+ */
+declare function labelMatches(label: string, query: string): boolean;
+/**
+ * Outcome of the resolution ladder. Exactly one of: a match (`el` set, `via`
+ * reporting the winning rung), an ambiguity (`el` null + `candidates` listing
+ * the distinct matches — the caller disambiguates with role/near), or a miss
+ * (`el` null, no candidates).
+ */
+type Resolution = {
+  /** The winning element, or null on ambiguity/miss. */
+  el: UiElement | null;
+  /** Match provenance — which rung won (id, exact label, substring, fuzzy). */
+  via?: string | undefined;
+  /** On ambiguity: the distinct elements that tied. */
+  candidates?: UiElement[] | undefined;
+};
+/** Disambiguators accepted by the resolution ladder. */
+type ResolveOpts = {
+  /** Restrict matches to this role (case-insensitive). */
+  role?: string | undefined;
+  /** Label of another element; pick the candidate geometrically closest to it. */
+  near?: string | undefined;
+};
+/**
+ * One screen's worth of the resolution ladder: id exact → exact label →
+ * substring → fuzzy above a strict bar. This is the per-iteration body of
+ * resolveElement's scroll loop, extracted so callers holding a fresh cache
+ * (item-4 auto-wait) can match without scrolling. Returns `{ el: null }` with
+ * no candidates when no rung matched at all.
+ */
+declare function matchInElements(els: UiElement[], query: string, opts: ResolveOpts): Resolution;
+/** Outcome of a system-alert interaction (see `DeviceCore.handleAlert`). */
+type AlertOutcome = {
+  /** Was an alert showing at all. */
+  present: boolean;
+  /** Was it cleared (accept/dismiss actions only). */
+  handled?: boolean | undefined;
+  /** The button that was tapped, when handled. */
+  button?: string | undefined;
+  /** Title/message/buttons summary of the alert. */
+  description?: string | undefined;
+};
+/** Render any thrown value as a one-line message (appends `details.hint` when present). */
+declare function describeError(error: unknown): string;
+/**
+ * The device core: one instance = one device's observe/resolve/act state,
+ * driving one {@link DeviceBackend}. Everything here is portable — no
+ * runtime-specific globals and no image libraries — so it runs under Node.
+ * The harness's DeviceContext subclasses this and adds the cursor +
+ * live-viewer layer via the onCacheUpdated hook.
+ */
+declare class DeviceCore {
+  /** The backend this core drives. */
+  readonly backend: DeviceBackend;
+  protected cachedNodes: SnapshotNode[];
+  protected cachedViewport: {
+    width: number;
+    height: number;
+  };
+  protected lastApp: {
+    app?: string | undefined;
+    bundleId?: string | undefined;
+  };
+  private lastRender;
+  protected cacheAt: number;
+  constructor(backend: DeviceBackend);
+  protected onCacheUpdated(): void;
+  /**
+   * Canonical post-action report for LLM tool results, shared by every tool
+   * surface (agent tools + MCP): verdict from the action's own evidence, then a
+   * delta-rendered view of the screen it left behind.
+   */
+  renderActionResult(prefix: string, evidence?: ActionEvidence, refresh?: boolean): Promise<string>;
+  /**
+   * Render the current cached screen for the LLM. full=true (or a structural
+   * change since last render) yields the complete compressed tree; otherwise a
+   * compact delta. Always updates the baseline.
+   */
+  renderObservation(full?: boolean): string;
+  private cacheSnapshot;
+  private refreshCache;
+  private cacheSignature;
+  /** Milliseconds since the cache was last refreshed (Infinity before first). */
+  cacheAgeMs(): number;
+  /** Public fingerprint of the cached tree — the settle/verify signal. */
+  stateSignature(): string;
+  /** The cached screen as a compressed {@link Observation} (no new snapshot). */
+  currentElements(): Observation;
+  /**
+   * The frontmost app name from the last snapshot — cheap label without paying
+   * the full tree compression (used by the delta renderer's callers).
+   */
+  currentApp(): string | undefined;
+  /**
+   * Structured interactive elements from the current cache — the crawler taps
+   * these by label (refs are only valid within one snapshot).
+   */
+  interactiveElements(): UiElement[];
+  /**
+   * Editable text inputs from the current cache. These roles are deliberately
+   * excluded from interactiveElements() (they aren't "tap" targets), so the
+   * input primitive needs its own accessor to find a search bar / text field to
+   * focus. includeMultiline adds TextView bodies for form/compose filling.
+   */
+  inputFields(includeMultiline?: boolean): UiElement[];
+  /**
+   * Run the resolution ladder against the current cache only — no scrolling,
+   * no fresh snapshot. resolveElement drives this per scroll step.
+   */
+  resolveInCache(query: string, opts?: ResolveOpts): Resolution;
+  /** The full ladder: scroll to top, then match + scroll down until found or stable. */
+  resolveElement(query: string, opts?: ResolveOpts): Promise<Resolution>;
+  /**
+   * Compatibility wrapper: single best element or null (read paths — ask/read a
+   * value — where picking the first match is low-risk). Tap paths use
+   * resolveElement directly and honor the ambiguity contract.
+   */
+  findElement(labelSubstring: string): Promise<UiElement | null>;
+  /**
+   * Read a labeled value. iOS list rows fold the value into the label
+   * ("iOS Version, 26.1") or expose it as a Switch value ("1"/"0"); handle both.
+   */
+  readField(labelSubstring: string): Promise<string | null>;
+  /**
+   * A structural fingerprint of the current screen that is stable across
+   * dynamic content (times, battery, values) — it keys the crawler's graph
+   * nodes so the same screen is recognized regardless of transient text.
+   */
+  screenSignature(): string;
+  /** Navigation-bar title of the cached screen ('' when absent). */
+  screenTitle(): string;
+  /** Take one fresh snapshot into the cache and return the compressed observation. */
+  observe(): Promise<Observation>;
+  /**
+   * Open an app by name/bundle id. relaunch forces a fresh launch (clean
+   * initial screen) instead of just foregrounding — iOS keeps an app's
+   * navigation state across foregrounding, so primitives that need a known
+   * starting screen pass relaunch=true.
+   */
+  openApp(app: string, relaunch?: boolean): Promise<string>;
+  /**
+   * Level-2 of the action ladder: deep links beat tap sequences when a URL route
+   * exists (maps://, app schemes, https:// universal links). XCTest sessions are
+   * app-scoped, so a link that opens a different app must re-scope the session
+   * to that app or observations keep tracking the old one.
+   */
+  openUrl(url: string, app?: string): Promise<string>;
+  private currentBundleId;
+  /** List installed app bundle ids. */
+  listApps(): Promise<string[]>;
+  private tapAndDiff;
+  /** Tap an element ref, self-diffing the cache to report whether the screen changed. */
+  press(ref: string): Promise<ActionEvidence>;
+  private visibleMidpoint;
+  protected onScreen(rect?: Rect): boolean;
+  /**
+   * Open an app and walk its nav stack back to the root (dismissing modals), so
+   * map-based navigation always starts from a known origin.
+   */
+  goToRoot(app: string): Promise<void>;
+  /** Height of the cached viewport in points. */
+  viewportHeight(): number;
+  /**
+   * Vertical span of interactive content in the current cache. Used to decide
+   * whether scrolling is even necessary — scroll gestures cost ~2s each, so
+   * skipping them on screens that already fit is the single biggest crawl
+   * speedup.
+   */
+  contentBounds(): {
+    minY: number;
+    maxY: number;
+  };
+  /**
+   * Tapping the status bar scrolls the active scroll view to the top — native
+   * iOS behavior, one fast tap instead of multiple ~2s scroll gestures. Falls
+   * back to gesture scrolling if the tap doesn't take.
+   */
+  scrollToTop(): Promise<void>;
+  /**
+   * Tap an element by its label, scrolling it into view first if it's
+   * off-screen. The crawler and the map navigator use this so a target below
+   * the fold (a long Settings list) is still reachable. Re-resolves the ref
+   * after each scroll.
+   */
+  tapLabel(label: string): Promise<boolean>;
+  /**
+   * Vision-path fallback: tap raw coordinates when the accessibility tree is
+   * missing or wrong (canvas, games, custom controls). Coordinates are in the
+   * same space as observe()'s rects and the screenshot pixels (@1x points).
+   */
+  pressAt(x: number, y: number): Promise<ActionEvidence>;
+  /**
+   * Coordinate drag: touch down at (x,y), move by (dx,dy). The primitive for
+   * controls a tap can't operate — picker wheels (drag vertically on the wheel
+   * column), sliders, and custom carousels. Same coordinate space as rects.
+   */
+  pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void>;
+  /**
+   * Set-of-Marks visual observation: screenshot with `@ref` labels drawn on the
+   * elements, so a vision model can ground itself in pixels and still act by ref.
+   */
+  screenshotWithRefs(path: string): Promise<string>;
+  protected currentViewport(): Promise<{
+    width: number;
+    height: number;
+  }>;
+  /** Long-press an element ref. */
+  longPress(ref: string, durationMs?: number): Promise<void>;
+  /** Focus a field and replace its text, self-diffing the cache for evidence. */
+  fill(ref: string, text: string): Promise<ActionEvidence>;
+  /** Type into whatever currently has keyboard focus. */
+  typeText(text: string): Promise<void>;
+  /**
+   * Press the keyboard's return/go key. Submits a search bar that acts on
+   * Return (Safari's address bar, web forms) rather than filtering results as
+   * you type.
+   */
+  pressReturn(): Promise<void>;
+  /** Scroll the active scroll view one step. */
+  scroll(direction: 'up' | 'down' | 'left' | 'right'): Promise<void>;
+  /** Block until `text` appears on screen; returns a confirmation note. */
+  waitForText(text: string, timeoutMs?: number): Promise<string>;
+  private alertFromCache;
+  /**
+   * System dialogs (permissions, sign-in prompts) block everything else; the
+   * driver exposes them as a first-class action instead of hoping a tap lands.
+   */
+  handleAlert(action: 'get' | 'accept' | 'dismiss'): Promise<AlertOutcome>;
+  /**
+   * Clear the launch permission gauntlet — real apps stack location /
+   * notification / tracking prompts on first open, each blocking the app.
+   * Grants by default so the crawl sees the most surface. Returns the buttons
+   * tapped. Bounded so a non-clearing dialog can't loop forever.
+   */
+  clearBlockingAlerts(action?: 'accept' | 'dismiss', max?: number): Promise<string[]>;
+  /** Go to the home screen. */
+  goHome(): Promise<void>;
+  /** Navigate back (nav-bar back / hardware back). */
+  goBack(): Promise<void>;
+  /** Save a screenshot to `path`; returns the written path. */
+  screenshot(path: string): Promise<string>;
+  /** Close the backend's transport session. */
+  closeSession(): Promise<void>;
+  protected findNode(ref: string): SnapshotNode | undefined;
+  protected ensureCache(): Promise<void>;
+}
+//#endregion
+//#region src/secrets.d.ts
+/**
+ * `%variable%` secret substitution (docs/19 §API shape, Stagehand's pattern):
+ * the model/caller plans against NAMES; values are injected at the last moment
+ * before backend.fill/typeText and never rendered into Actions, results,
+ * observations, or traces. Redaction is best-effort belt-and-braces; the hard
+ * guarantee is at the substitution point — values never enter stored Actions
+ * by construction.
+ */
+declare class SecretStore {
+  private readonly values;
+  constructor(values?: Record<string, string>);
+  /**
+   * Store a secret under `name`. Rejects values shorter than 4 chars — a
+   * 2-char secret would redact innocent UI text everywhere.
+   */
+  set(name: string, value: string): void;
+  /** The stored secret NAMES (never the values). */
+  names(): string[];
+  /** %name% → value. Unknown %x% stays literal. */
+  substitute(text: string): string;
+  /** value → %name% across outbound text (messages, rendered observations). */
+  redact(text: string): string;
+  /** Per-call vars layered over the store (call-scoped, never persisted). */
+  withOverrides(vars?: Record<string, string>): SecretStore;
+}
+//#endregion
+//#region src/actions.d.ts
+/**
+ * A RE-RESOLVABLE element query — how a portable {@link Action} names its
+ * target. Resolved against the live tree by the resolution ladder at act()
+ * time; no stale handles.
+ */
+type ElementQuery = {
+  /** Label to match (exact → substring → fuzzy, the ladder's rungs). */
+  label?: string | undefined;
+  /** Accessibility identifier — rung 0 of the ladder, wins when present. */
+  id?: string | undefined;
+  /** Disambiguator: restrict matches to this role (e.g. "Button"). */
+  role?: string | undefined;
+  /** Disambiguator: label of another element; pick the geometrically closest match. */
+  near?: string | undefined;
+};
+/** Verbs a portable {@link Action} can carry. */
+type ActionVerb = 'tap' | 'longPress' | 'fill' | 'type' | 'pressKey' | 'scroll' | 'openApp' | 'openUrl' | 'back' | 'home' | 'alert' | 'waitForText';
+/**
+ * The observe→act seam (docs/19 §API shape; docs/20 item 4): a portable action
+ * descriptor carrying a re-resolvable {@link ElementQuery}. `observe()` returns
+ * these; `act()` re-resolves against the live tree and executes with no
+ * re-inference. A compiled skill is a stored `Action[]`.
+ */
+type Action = {
+  /** Versioned, documented UNSTABLE pre-1.0 (docs/20 open-question 3). */
+  formatVersion: 0;
+  /** What to do. */
+  verb: ActionVerb;
+  /** Target query for element-directed verbs (tap/longPress/fill). */
+  target?: ElementQuery | undefined;
+  /** Verb parameters (text, direction, app, url, ...). */
+  params?: {
+    /** fill/type text — may contain %name% secret references. */
+    text?: string | undefined;
+    direction?: ScrollDirection | undefined;
+    app?: string | undefined;
+    url?: string | undefined;
+    durationMs?: number | undefined;
+    key?: 'return' | undefined;
+    alertAction?: 'accept' | 'dismiss' | undefined;
+    submit?: boolean | undefined;
+    relaunch?: boolean | undefined;
+  } | undefined;
+  /**
+   * Provenance from observe/record time. ADVISORY ONLY — act() always
+   * re-resolves; this exists for traces, drift diagnosis, and human review.
+   */
+  observed?: {
+    via?: string | undefined;
+    label?: string | undefined;
+    role?: string | undefined;
+    rect?: Rect | undefined;
+    app?: string | undefined;
+    screenTitle?: string | undefined;
+  } | undefined;
+};
+/** The stored-Action[] artifact (public TYPE, unstable FORMAT — see docs/20). */
+type CompiledSkill = {
+  formatVersion: 0;
+  name: string;
+  description?: string | undefined;
+  params?: string[] | undefined;
+  precondition?: string | undefined;
+  actions: Action[];
+};
+/** An interactive element as surfaced by `observe()` (alias of {@link UiElement}). */
+type ObservedElement = UiElement;
+/** What `observe()` returns: elements, rendered text, and portable actions. */
+type ObserveResult = {
+  /** Always true for a completed observation. */
+  success: boolean;
+  /** Human-readable summary of the observation. */
+  message: string;
+  /** Frontmost app name, when known. */
+  app?: string | undefined;
+  /** Frontmost app bundle id, when known. */
+  bundleId?: string | undefined;
+  /** Navigation-bar title of the current screen, when present. */
+  screenTitle?: string | undefined;
+  /** Structured channel (secret-redacted values). */
+  elements: ObservedElement[];
+  /** Compressed text channel (secret-redacted). */
+  rendered: string;
+  /** Portable descriptors: a tap per tappable, a fill per input field. */
+  actions: Action[];
+};
+/**
+ * Structured outcome of every action verb. Never-throw contract: device-legible
+ * failures (not found, ambiguous, wait deadline, gesture failure) come back as
+ * `{success: false, ...}`; only infrastructure errors (abort, closed session,
+ * unsupported capability) throw PhoneUseError subclasses.
+ */
+type ActionResult = {
+  /** Did the action execute as intended. */
+  success: boolean;
+  /** Human-readable outcome (secret-redacted). */
+  message: string;
+  /** tapAndDiff verdict where applicable: did the screen actually change. */
+  changed?: boolean | undefined;
+  /** How the target resolved (match provenance, ref, label, role, rect). */
+  resolved?: {
+    via: string;
+    ref: string;
+    label: string;
+    role: string;
+    rect?: Rect | undefined;
+  } | undefined;
+  /** The ambiguity contract, surfaced structurally. */
+  candidates?: ObservedElement[] | undefined;
+  /** Auto-wait cost when the slow path ran (elapsed ms, poll count). */
+  waited?: {
+    ms: number;
+    polls: number;
+  } | undefined;
+  /** Set on structured failures with an error flavor (e.g. TIMEOUT). */
+  code?: PhoneUseErrorCode | undefined;
+};
+/** Per-call options accepted by every action verb. */
+type ActOptions = {
+  /** Abort the call; the in-flight gesture may still land (state indeterminate). */
+  signal?: AbortSignal | undefined;
+  /** Auto-wait deadline (default 5000 ms). */
+  timeoutMs?: number | undefined;
+  /** Per-call secret overrides, layered on the device store. */
+  vars?: Record<string, string> | undefined;
+};
+/** Synthesize portable actions from the CURRENT cache (observe-time). */
+declare function toActions(core: DeviceCore): Action[];
+/**
+ * Take one fresh snapshot and assemble the full {@link ObserveResult}:
+ * deduped element channel, secret-redacted rendered text, and a portable
+ * Action per tappable / input field.
+ */
+declare function buildObserveResult(core: DeviceCore, secrets?: SecretStore): Promise<ObserveResult>;
+/**
+ * THE dispatcher: resolve → auto-wait → execute → diff. One brain — used by
+ * device.tap/type/act, and (items 5-6) by the harness and the skill runner.
+ */
+declare function executeAction(core: DeviceCore, action: Action, opts?: ActOptions, secrets?: SecretStore): Promise<ActionResult>;
+//#endregion
+//#region src/backends/agent-device.d.ts
+/**
+ * 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.
+ */
+declare function createAgentDeviceBackend(config?: DeviceConfig): DeviceBackend;
+//#endregion
+//#region src/lifecycle.d.ts
+/** The platform a {@link Device} runs on. */
+type DevicePlatform = 'ios' | 'android';
+/** Lifecycle state of a {@link Device} handle. */
+type DeviceStatus = 'running' | 'closed';
+/**
+ * The Device lifecycle handle (docs/20 item 3; docs/19 §Lifecycle): id, pinned
+ * backend, close/dispose, idle lease + reaper — plus the action verb surface
+ * (item 4) layered onto the same type. `ios.launch()` and `ios.connect()`
+ * return it; the android engine (item 7b) will share `createDeviceHandle`.
+ */
+interface Device {
+  /** udid (iOS) / serial (Android). */
+  readonly id: string;
+  /** Which platform this device runs. */
+  readonly platform: DevicePlatform;
+  /** Simulator/device name when known. */
+  readonly name?: string | undefined;
+  /** Name of the backend driving this device. */
+  readonly backendName: string;
+  /** The backend's declared capability set. */
+  readonly capabilities: ReadonlySet<Capability>;
+  /**
+   * The pinned backend — `new DeviceContext(device.backend)` works today.
+   * Backend calls through this handle count as activity for the idle lease.
+   */
+  readonly backend: DeviceBackend;
+  /** true when launch() created the device — close() then also deletes it. */
+  readonly createdByUs: boolean;
+  /** Current lifecycle state. */
+  readonly status: DeviceStatus;
+  /** Sugar for `status === 'closed'`. */
+  readonly isClosed: boolean;
+  /** Re-arm the idle lease (ms overrides the configured window for this arm only). */
+  extendLease(ms?: number): void;
+  /** Canonical, idempotent shutdown. `await using` is sugar over this. */
+  close(): Promise<void>;
+  /** `await using` support — delegates to {@link Device.close}. */
+  [Symbol.asyncDispose](): Promise<void>;
+  /** Look at the screen: elements + rendered text + portable Action[]. */
+  observe(opts?: {
+    signal?: AbortSignal | undefined;
+  }): Promise<ObserveResult>;
+  /** Tap by label/id query. Auto-waits; never throws for normal outcomes. */
+  tap(target: string | ElementQuery, opts?: ActOptions): Promise<ActionResult>;
+  /** Type text (optionally into a field resolved by query); %name% secrets substituted. */
+  type(text: string, opts?: ActOptions & {
+    field?: string | ElementQuery | undefined;
+    submit?: boolean | undefined;
+  }): Promise<ActionResult>;
+  /** Execute a portable Action deterministically — no re-inference. */
+  act(action: Action, opts?: ActOptions): Promise<ActionResult>;
+  /** App management: open by name/deep link, list installed, current app. */
+  readonly apps: {
+    /** Open an app by name/bundle id, or a deep link when `url` is set. */
+    open(app: string, opts?: {
+      relaunch?: boolean | undefined;
+      url?: string | undefined;
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+    /** List installed app bundle ids. */
+    list(opts?: {
+      signal?: AbortSignal | undefined;
+    }): Promise<string[]>;
+    /** The frontmost app name from the last observation (no new snapshot). */
+    current(): string | undefined;
+  };
+  /** Screen-level verbs: scroll, screenshot, waitForText, alert, back, home. */
+  readonly screen: {
+    /** Scroll the active scroll view one step. */
+    scroll(direction: ScrollDirection, opts?: {
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+    /** Save a screenshot to `path`. */
+    screenshot(opts: {
+      path: string;
+      signal?: AbortSignal | undefined;
+    }): Promise<{
+      success: boolean;
+      message: string;
+      path?: string | undefined;
+    }>;
+    /** Block until `text` appears on screen or the timeout elapses. */
+    waitForText(text: string, opts?: {
+      timeoutMs?: number | undefined;
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+    /** Read ('get'), accept, or dismiss a blocking system alert. */
+    alert(action: 'get' | 'accept' | 'dismiss', opts?: {
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+    /** Navigate back. */
+    back(opts?: {
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+    /** Go to the home screen. */
+    home(opts?: {
+      signal?: AbortSignal | undefined;
+    }): Promise<ActionResult>;
+  };
+  /** %name% secret store — values substituted at execution, redacted everywhere else. */
+  readonly secrets: SecretStore;
+}
+/** Inputs to {@link createDeviceHandle} — what an engine supplies per device. */
+type CreateDeviceHandleOptions = {
+  /** udid (iOS) / serial (Android). */
+  id: string;
+  /** Which platform the device runs. */
+  platform: DevicePlatform;
+  /** Simulator/device name when known. */
+  name?: string | undefined;
+  /** The backend pinned to this device. */
+  backend: DeviceBackend;
+  /** true when the engine created the device (close() then also deletes it). */
+  createdByUs: boolean;
+  /** Idle window in ms; false disables the lease. Default 180_000 (3m). */
+  idleTimeoutMs?: number | false | undefined;
+  /** Observer for reaper-initiated closes (the SDK never logs). */
+  onIdleClose?: ((device: Device) => void) | undefined;
+  /** Initial %name% secret values. */
+  secrets?: Record<string, string> | undefined;
+  /** Platform teardown: shutdown (+ delete when createdByUs). */
+  doClose: () => Promise<void>;
+};
+/**
+ * Assemble a Device handle over a backend: lease/reaper, verb surface,
+ * close/dispose semantics. Engine authors (ios here, android in item 7b,
+ * phone-backend-* third parties) build on this; tests fabricate devices with
+ * it over a FakeBackend.
+ */
+declare function createDeviceHandle(opts: CreateDeviceHandleOptions): Device;
+//#endregion
+//#region src/backends/ios.d.ts
+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;
+  /**
+   * 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;
+};
+/** Options for `ios.launch()` — device type, runtime, name, boot ceiling. */
+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()`. */
+type IosConnectOptions = CommonIosOptions & {
+  /** Boot wait ceiling when connect has to boot a shut-down sim (default 120_000 ms). */
+  bootTimeoutMs?: number | undefined;
+};
+/**
+ * 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.
+ */
+declare function launch(options?: IosLaunchOptions): Promise<Device>;
+/**
+ * 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.
+ */
+declare function connect(udid?: string, options?: IosConnectOptions): Promise<Device>;
+/**
+ * The iOS engine object (Playwright-style): `ios.launch()` for a dedicated
+ * simulator, `ios.connect()` to reattach. Both return the same Device type.
+ */
+declare const ios: {
+  /** Create + boot a dedicated simulator and return a Device pinned to it. */
+  readonly launch: typeof launch;
+  /** Reattach to an existing simulator (no-arg: first booted sim). */
+  readonly connect: typeof connect;
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
+ * (ios.launch/connect → Device), Device backends, config, errors, capabilities
+ * (docs/20-runtime-sdk-v1-plan.md items 2-3; action verbs land in item 4).
+ *
+ * The test double (FakeBackend) lives on the "@phone-use/sdk/testing" subpath,
+ * deliberately not re-exported here.
+ */
+/** The published package version (kept in sync with package.json by the release flow). */
+declare const VERSION = "0.1.0";
+//#endregion
+export { ALL_CAPABILITIES, AbortedError, type ActOptions, type Action, type ActionEvidence, ActionFailedError, type ActionResult, type ActionVerb, type AlertAction, type AlertOutcome, type AndroidDeviceConfig, type BackendAlertResult, type BackendFactory, BaseDeviceBackend, type Capability, type CommonDeviceConfig, type CompiledSkill, type CreateDeviceHandleOptions, type Device, type DeviceBackend, type DeviceConfig, DeviceCore, DeviceInUseError, DeviceNotFoundError, type DevicePlatform, type DeviceStatus, type ElementQuery, type IosConnectOptions, type IosDeviceConfig, type IosLaunchOptions, type Observation, type ObserveResult, type ObservedElement, type OpenAppResult, PhoneUseError, type PhoneUseErrorCode, type PhoneUseErrorDetails, type PressTarget, type Rect, type RenderState, type Resolution, type ResolveOpts, type ScrollDirection, SecretStore, SessionNotFoundError, type Snapshot, type SnapshotNode, TimeoutError, type UiElement, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createDeviceHandle, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
+//# sourceMappingURL=index.d.mts.map