agent-device 0.20.10 → 0.21.0

package/dist/src/sdk-selectors.d.ts

@@ -1,5 +1,4 @@
-import { C as SnapshotNode, E as SnapshotState, S as SnapshotBackend, T as SnapshotQualityVerdict, U as PublicPlatform, V as Platform, b as Rect, m as ResponseCost, v as Point, w as SnapshotOptions$1, x as ScreenshotOverlayRef, y as RawSnapshotNode } from "./sdk-contracts.js";
-import { c as ScrollDirection, o as GesturePlan } from "./sdk-android-adb.js";
+import { C as SnapshotNode, D as SnapshotState, E as SnapshotQualityVerdict, F as Platform, L as PublicPlatform, S as ScreenshotOverlayRef, T as SnapshotProvenance, b as RawSnapshotNode, h as ResponseCost, w as SnapshotOptions$1, x as Rect, y as Point } from "./sdk-contracts.js";
 //#region packages/contracts/src/session-surface.d.ts
 declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
 type SessionSurface = (typeof SESSION_SURFACES)[number];
@@ -28,6 +27,7 @@ type ScreenshotResultData = {
   logicalHeight?: number;
   pixelDensity?: number;
   overlayRefs?: ScreenshotOverlayRef[];
+  warnings?: string[];
 };
 type BackendSnapshotResult = {
   nodes?: SnapshotNode[];
@@ -70,7 +70,12 @@ type AndroidSnapshotBackendMetadata = {
   nodeCount?: number;
   helperTruncated?: boolean;
   elapsedMs?: number;
-  /** API 23 helper output carries no `drawing-order`; covered same-window surfaces are not pruned. */
+  presentationFailure?: {
+    phase: 'deadline' | 'complexity' | 'regular-invariant';
+    workUnits: number;
+    maxWorkUnits?: number;
+  };
+  /** API 23 exposes no sibling drawing order, so same-window occlusion fails conservative. */
   occlusionScanUnavailable?: boolean;
 };
 type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
@@ -79,6 +84,58 @@ type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
 declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
 type ClickButton = (typeof CLICK_BUTTONS)[number];
 //#endregion
+//#region packages/contracts/src/scroll-gesture.d.ts
+declare const SCROLL_INPUT_DIRECTIONS: readonly ['up', 'down', 'left', 'right', 'top', 'bottom'];
+type ScrollInputDirection = (typeof SCROLL_INPUT_DIRECTIONS)[number];
+declare const SCROLL_DIRECTIONS: readonly ['up', 'down', 'left', 'right'];
+type ScrollDirection = (typeof SCROLL_DIRECTIONS)[number];
+declare const SWIPE_PRESETS: readonly ['left', 'right', 'left-edge', 'right-edge'];
+type SwipePreset = (typeof SWIPE_PRESETS)[number];
+declare const SWIPE_PATTERNS: readonly ['one-way', 'ping-pong'];
+type SwipePattern = (typeof SWIPE_PATTERNS)[number];
+type TransformGestureParams = {
+  x: number;
+  y: number;
+  dx: number;
+  dy: number;
+  scale: number;
+  degrees: number;
+  durationMs?: number;
+};
+//#endregion
+//#region packages/contracts/src/gesture-plan-types.d.ts
+type GesturePointerCount = 1 | 2;
+/** Selects one-pointer release timing without changing semantic gesture intent. */
+type GestureExecutionProfile = 'endpoint-hold' | 'timed-pan';
+type PointerTrajectorySample = {
+  offsetMs: number;
+  point: Point;
+};
+type PointerTrajectory = {
+  pointerId: 0 | 1;
+  samples: readonly PointerTrajectorySample[];
+};
+type SinglePointerTrajectory = {
+  pointerId: 0;
+  samples: readonly [PointerTrajectorySample, PointerTrajectorySample, ...PointerTrajectorySample[]];
+};
+type SinglePointerGesturePlan = {
+  topology: 'single';
+  intent: 'fling' | 'pan';
+  executionProfile: GestureExecutionProfile;
+  durationMs: number;
+  viewport: Rect;
+  pointers: readonly [SinglePointerTrajectory];
+};
+type MultiTouchGesturePlan = {
+  topology: 'two';
+  intent: 'pan' | 'pinch' | 'rotate' | 'transform';
+  durationMs: number;
+  viewport: Rect;
+  pointers: readonly [PointerTrajectory, PointerTrajectory];
+};
+type GesturePlan = SinglePointerGesturePlan | MultiTouchGesturePlan;
+//#endregion
 //#region packages/contracts/src/back-mode.d.ts
 declare const BACK_MODES: readonly ['in-app', 'system'];
 type BackMode = (typeof BACK_MODES)[number];
@@ -141,146 +198,6 @@ declare const TV_REMOTE_BUTTON_DEFINITIONS: {
 declare const TV_REMOTE_BUTTONS: (keyof typeof TV_REMOTE_BUTTON_DEFINITIONS)[];
 type TvRemoteButton = (typeof TV_REMOTE_BUTTONS)[number];
 //#endregion
-//#region packages/contracts/src/settings.d.ts
-type SettingOptions = {
-  permissionTarget?: string;
-  permissionMode?: string;
-  latitude?: number;
-  longitude?: number;
-};
-//#endregion
-//#region packages/contracts/src/runner-lease-context.d.ts
-type RunnerLogicalLeaseContext = {
-  leaseId?: string;
-  clientId?: string;
-  tenantId?: string;
-  runId?: string;
-  leaseProvider?: string;
-  deviceKey?: string;
-};
-//#endregion
-//#region packages/contracts/src/interactor-types.d.ts
-type RunnerContext = {
-  requestId?: string;
-  signal?: AbortSignal;
-  appBundleId?: string;
-  verbose?: boolean;
-  logPath?: string;
-  traceLogPath?: string;
-  iosXctestrunFile?: string;
-  iosXctestDerivedDataPath?: string;
-  iosXctestEnvDir?: string;
-  runnerLeaseContext?: RunnerLogicalLeaseContext;
-};
-type ScreenshotOptions = {
-  appBundleId?: string;
-  pixelDensity?: number;
-  fullscreen?: boolean;
-  normalizeStatusBar?: boolean;
-  stabilize?: boolean;
-  surface?: SessionSurface;
-  skipIosSimulatorBootCheck?: boolean;
-  captureBackend?: 'runner';
-};
-type ElementSelectorKey = 'id' | 'label' | 'text' | 'value';
-type ElementSelectorTapOptions = {
-  key: ElementSelectorKey;
-  value: string;
-  allowNonHittableCoordinateFallback?: boolean;
-  expectedPoint?: Point;
-};
-/**
- * The channel the XCTest runner actually entered text through — the Swift
- * `TextEntryResult.textEntryRoute` (RunnerTests+TextTyping.swift,
- * RunnerTests+SynthesizedTextEntry.swift). Closed set, because the runner is
- * its only producer and the boundary that narrows it
- * (readTypeTextBackendResult, src/platforms/apple/interactions.ts) drops a
- * route it cannot name — so a Swift-side addition would silently vanish. The
- * route-parity test in src/platforms/apple/core/__tests__/interactions.test.ts
- * reads the Swift sources and fails instead.
- */
-declare const TEXT_ENTRY_ROUTES: readonly ['xctest-element', 'synthesized-first-responder', 'synthesized-first-responder-replacement', 'xctest-application-fallback'];
-type TextEntryRoute = (typeof TEXT_ENTRY_ROUTES)[number];
-/**
- * What `Interactor.type` reports back about the entry it performed. Only the
- * Apple runner populates it; every other platform types blind and returns void.
- */
-type TypeTextBackendResult = {
-  textEntryRoute?: TextEntryRoute;
-};
-type FillVerificationTarget = {
-  resourceId: string | null;
-  className: string | null;
-  packageName: string | null;
-  rect: Rect;
-};
-type FillUnconfirmedVerification = {
-  verification: 'unconfirmed';
-  requested: string;
-  before: string | null;
-  after: string | null;
-  target: FillVerificationTarget;
-};
-type SnapshotOptions = SnapshotOptions$1 & {
-  appBundleId?: string;
-  signal?: AbortSignal;
-  includeRects?: boolean;
-  includeHiddenContentHints?: boolean;
-  surface?: SessionSurface;
-};
-type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
-  nodes?: RawSnapshotNode[];
-  backend: Extract<SnapshotBackend, 'android' | 'harmonyos-arkui' | 'xctest' | 'linux-atspi' | 'macos-helper' | 'web'>;
-};
-type Interactor = {
-  open(app: string, options?: {
-    activity?: string;
-    appBundleId?: string;
-    launchConsole?: string;
-    launchArgs?: string[];
-    terminateRunningApp?: boolean;
-    url?: string;
-  }): Promise<void>;
-  openDevice(): Promise<void>;
-  close(app: string): Promise<void>;
-  tap(x: number, y: number): Promise<Record<string, unknown> | void>;
-  tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
-  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
-  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
-  /**
-   * Move the pointer to a point without pressing. Only pointer-driven
-   * platforms (web today) implement it; touch platforms have no hover state
-   * and leave it undefined, which the `hover` command reports as unsupported.
-   */
-  hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
-  focus(x: number, y: number): Promise<Record<string, unknown> | void>;
-  type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
-  fillElementSelector?(selector: ElementSelectorTapOptions, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
-  fill(x: number, y: number, text: string, delayMs?: number, options?: {
-    allowNonHittableCoordinateFallback?: boolean;
-  }): Promise<Record<string, unknown> | void>;
-  scroll(direction: ScrollDirection, options?: {
-    amount?: number;
-    pixels?: number;
-    durationMs?: number;
-  }): Promise<Record<string, unknown> | void>;
-  screenshot(outPath: string, options?: ScreenshotOptions): Promise<void>;
-  setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
-  snapshot(options?: SnapshotOptions): Promise<SnapshotResult>;
-  gestureViewport?(): Promise<Rect>;
-  back(mode?: BackMode): Promise<void>;
-  home(): Promise<void>;
-  setOrientation(orientation: DeviceRotation): Promise<{
-    orientation?: DeviceRotation;
-  } | void>;
-  performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
-  appSwitcher(): Promise<void>;
-  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
-  readClipboard(): Promise<string>;
-  writeClipboard(text: string): Promise<void>;
-  setSetting(setting: string, state: string, appId?: string, options?: SettingOptions): Promise<Record<string, unknown> | void>;
-};
-//#endregion
 //#region packages/contracts/src/interaction.d.ts
 /** The decisive criterion separating a resolveSelectorChain winner from its strongest runner-up (ADR 0012). */
 type DisambiguationTiebreak = 'visible' | 'deepest' | 'smallest-area' | 'structural-equivalence';
@@ -520,6 +437,417 @@ type FindCommandResponseData = {
   cost?: ResponseCost;
 };
 //#endregion
+//#region packages/contracts/src/scroll-command.d.ts
+type ScrollReleaseBehavior = 'controlled' | 'inertial';
+type ScrollDistanceOptions = {
+  amount?: number;
+  pixels?: number;
+};
+type ScrollTimingOptions = {
+  durationMs?: number;
+};
+type ScrollCommandOptions = ScrollDistanceOptions & ScrollTimingOptions;
+type ScrollExecutionOptions = ScrollCommandOptions & {
+  releaseBehavior?: ScrollReleaseBehavior;
+};
+/**
+ * `scroll` — the generic-route result built by `buildDispatchedScrollResult`
+ * (src/core/dispatch-scroll.ts): the resolved direction, the edge-pass
+ * bookkeeping for `top`/`bottom` scrolls, the honored distance/timing echo,
+ * and the success message. Platform leaves add gesture-plan coordinates
+ * (`x1`/`y1`/`x2`/`y2`, reference frame) on top; the output schema stays
+ * non-strict so those additive fields validate. The one field the dispatcher
+ * itself may add: `settle`, the opt-in `--settle` observation (#1638),
+ * attached after the command — same shape as `BackCommandResult`.
+ */
+type ScrollCommandResult = {
+  direction: ScrollDirection;
+  /** Set for `top`/`bottom` requests: the extreme being scrolled to. */
+  edge?: 'top' | 'bottom';
+  /** Edge scrolls only: how many scroll-and-check passes ran. */
+  passes?: number;
+  amount?: number;
+  pixels?: number;
+  durationMs?: number;
+  message?: string;
+  settle?: SettleObservation;
+};
+//#endregion
+//#region packages/contracts/src/settings.d.ts
+type SettingOptions = {
+  permissionTarget?: string;
+  permissionMode?: string;
+  latitude?: number;
+  longitude?: number;
+};
+//#endregion
+//#region packages/contracts/src/runner-lease-context.d.ts
+type RunnerLogicalLeaseContext = {
+  leaseId?: string;
+  clientId?: string;
+  tenantId?: string;
+  runId?: string;
+  leaseProvider?: string;
+  deviceKey?: string;
+};
+//#endregion
+//#region packages/contracts/src/ios-snapshot.d.ts
+type IosSnapshotProducer = 'apple-runner' | 'simulator-ax-bridge' | 'appium-source' | 'limrun-ios-tree';
+type IosAcquisitionProducer = Exclude<IosSnapshotProducer, 'apple-runner'>;
+type IosAcquisitionIntent = 'full' | 'surface-observation';
+type IosSnapshotProjection = 'regular' | 'raw';
+type IosSnapshotGeneration = string;
+type IosSnapshotLineage = Readonly<{
+  targetId?: string;
+  generation?: IosSnapshotGeneration;
+}>;
+type IosSnapshotPresentationKey = Readonly<{
+  projection: IosSnapshotProjection;
+  interactiveOnly: boolean;
+  depth: number | null;
+  scope: string | null;
+  customActions: boolean;
+}>;
+type CaptureHint = Readonly<{
+  projection: IosSnapshotProjection;
+  rawTraversalDepth: number | null;
+  regularPresentedDepth: number | null;
+  interactiveOnly: boolean;
+  customActions: boolean;
+  acquisitionIntent: IosAcquisitionIntent;
+}>;
+type IosSnapshotFact = 'acquisition-depth' | 'scope' | 'interactive-query' | 'viewport' | 'hittability' | 'generation' | 'truncation';
+type IosViewportEvidence = Readonly<{
+  kind: 'reported';
+  rect: Rect;
+}> | Readonly<{
+  kind: 'derived';
+  rect: Rect;
+}> | Readonly<{
+  kind: 'missing';
+  reason: 'not-provided' | 'not-supported' | 'invalid';
+}>;
+type IosProviderPrunedField = 'nodes' | 'depth' | 'scope' | 'interactive-only';
+type IosTruncationDimension = 'nodes' | 'depth' | 'payload';
+type IosAcquisitionResidue = Readonly<{
+  kind: 'provider-pruned';
+  fields: readonly IosProviderPrunedField[];
+}> | Readonly<{
+  kind: 'missing-viewport';
+  reason: 'not-provided' | 'not-supported' | 'invalid';
+}> | Readonly<{
+  kind: 'truncated';
+  dimension: IosTruncationDimension;
+  limit?: number;
+}> | Readonly<{
+  kind: 'stale-generation';
+  expected?: IosSnapshotGeneration;
+  observed?: IosSnapshotGeneration;
+}> | Readonly<{
+  kind: 'unknown-generation';
+  captureId: string;
+}> | Readonly<{
+  kind: 'unavailable-fact';
+  fact: IosSnapshotFact;
+}> | Readonly<{
+  kind: 'fallback-source';
+  producer: IosSnapshotProducer;
+}>;
+type IosSnapshotAcquisitionForIntent<Intent extends IosAcquisitionIntent> = Readonly<{
+  producer: IosAcquisitionProducer;
+  intent: Intent;
+  hint: CaptureHint & Readonly<{
+    acquisitionIntent: Intent;
+  }>;
+  nodes: readonly RawSnapshotNode[];
+  truncated?: boolean;
+  viewport: IosViewportEvidence;
+  lineage: IosSnapshotLineage;
+  residue: readonly IosAcquisitionResidue[];
+}>;
+type IosSnapshotAcquisition = IosSnapshotAcquisitionForIntent<'full'> | IosSnapshotAcquisitionForIntent<'surface-observation'>;
+type IosSnapshotAcquisitionFacts = Omit<IosSnapshotAcquisition, 'hint'>;
+type IosSnapshotComparisonIdentity = Readonly<{
+  producer: IosSnapshotProducer;
+  intent: IosAcquisitionIntent;
+  lineage: IosSnapshotLineage;
+  presentationKey: IosSnapshotPresentationKey;
+  residue: readonly IosAcquisitionResidue[];
+}>;
+//#endregion
+//#region packages/contracts/src/interactor-types.d.ts
+type RunnerContext = {
+  requestId?: string;
+  signal?: AbortSignal;
+  appBundleId?: string;
+  verbose?: boolean;
+  logPath?: string;
+  traceLogPath?: string;
+  iosXctestrunFile?: string;
+  iosXctestDerivedDataPath?: string;
+  iosXctestEnvDir?: string;
+  runnerLeaseContext?: RunnerLogicalLeaseContext;
+};
+type ScreenshotOptions = {
+  appBundleId?: string;
+  pixelDensity?: number;
+  fullscreen?: boolean;
+  normalizeStatusBar?: boolean;
+  stabilize?: boolean;
+  surface?: SessionSurface;
+  skipIosSimulatorBootCheck?: boolean;
+  captureBackend?: 'runner';
+};
+type ElementSelectorKey = 'id' | 'label' | 'text' | 'value';
+type ElementSelectorTapOptions = {
+  key: ElementSelectorKey;
+  value: string;
+  allowNonHittableCoordinateFallback?: boolean;
+  expectedPoint?: Point;
+};
+type PressPointOptions = Readonly<{
+  button: 'primary' | 'secondary' | 'middle';
+  count: number;
+  intervalMs: number;
+  holdMs: number;
+  jitterPx: number;
+  doubleTap: boolean;
+  surface?: SessionSurface;
+}>;
+/**
+ * The channel the XCTest runner actually entered text through — the Swift
+ * `TextEntryResult.textEntryRoute` (RunnerTests+TextTyping.swift,
+ * RunnerTests+SynthesizedTextEntry.swift). Closed set, because the runner is
+ * its only producer and the boundary that narrows it
+ * (readTypeTextBackendResult, packages/platform-apple/src/interactions.ts) drops a
+ * route it cannot name — so a Swift-side addition would silently vanish. The
+ * route-parity test in packages/platform-apple/src/core/__tests__/interactions.test.ts
+ * reads the Swift sources and fails instead.
+ */
+declare const TEXT_ENTRY_ROUTES: readonly ['xctest-element', 'synthesized-first-responder', 'synthesized-first-responder-replacement', 'xctest-application-fallback'];
+type TextEntryRoute = (typeof TEXT_ENTRY_ROUTES)[number];
+/**
+ * What `Interactor.type` reports back about the entry it performed. Only the
+ * Apple runner populates it; every other platform types blind and returns void.
+ */
+type TypeTextBackendResult = {
+  textEntryRoute?: TextEntryRoute;
+};
+type FillVerificationTarget = {
+  resourceId: string | null;
+  className: string | null;
+  packageName: string | null;
+  rect: Rect;
+};
+type FillUnconfirmedVerification = {
+  verification: 'unconfirmed';
+  requested: string;
+  before: string | null;
+  after: string | null;
+  target: FillVerificationTarget;
+};
+type SnapshotOptions = SnapshotOptions$1 & {
+  appBundleId?: string;
+  signal?: AbortSignal;
+  includeRects?: boolean;
+  includeHiddenContentHints?: boolean;
+  surface?: SessionSurface;
+  /** Internal capture purpose; action outcomes always require the full tree. */
+  acquisitionIntent?: 'full' | 'surface-observation';
+};
+/**
+ * Android's live IME status read. Optional on {@link Interactor}: parity with the retired leaf,
+ * which refused `status`/`get` on every other family (no other platform's runner exposes one).
+ * A single-member discriminated union rather than a bare object so the daemon can derive its wire
+ * `platform` label from `kind` the same way it does for dismiss and enter — an owner can only ever
+ * produce its own result shape.
+ */
+type KeyboardStatusResult = Readonly<{
+  kind: 'ime-probe';
+  visible: boolean;
+  inputType?: string;
+  type?: string;
+  inputMethodPackage?: string;
+  focusedPackage?: string;
+  focusedResourceId?: string;
+  inputOwner?: string;
+}>;
+/**
+ * Owner-shaped dismiss evidence, discriminated by which owner produced it: Android's IME probe
+ * fields, or iOS's `mechanism` disclosure (#1598), or HarmonyOS's bare acknowledgment (its HDC
+ * key press reports nothing beyond success). The daemon derives the wire `platform` label from
+ * `kind` rather than re-deriving it from the device, so an owner can only ever produce its own
+ * result shape — an android-probe result under an `ios` label is unrepresentable.
+ */
+type KeyboardDismissResult = Readonly<{
+  kind: 'ime-probe';
+  attempts?: number;
+  wasVisible?: boolean;
+  dismissed?: boolean;
+  visible?: boolean;
+  inputType?: string;
+  type?: string;
+  inputMethodPackage?: string;
+  focusedPackage?: string;
+  focusedResourceId?: string;
+  inputOwner?: string;
+}> | Readonly<{
+  kind: 'mechanism';
+  wasVisible?: boolean;
+  dismissed?: boolean;
+  visible?: boolean;
+  mechanism?: string;
+}> | Readonly<{
+  kind: 'acknowledged';
+}>;
+/**
+ * Only the Apple runner echoes visibility around the return-key press; Android and HarmonyOS
+ * acknowledge with no fields beyond success. Kind is owner-specific, not just content-shaped —
+ * Android's and HarmonyOS's acknowledgments are structurally identical, so only the discriminant
+ * itself tells the daemon which owner actually pressed enter.
+ */
+type KeyboardEnterResult = Readonly<{
+  kind: 'visibility-echo';
+  visible?: boolean;
+  wasVisible?: boolean;
+}> | Readonly<{
+  kind: 'android-acknowledged';
+}> | Readonly<{
+  kind: 'harmonyos-acknowledged';
+}>;
+/**
+ * Every acquisition carries its provenance pair atomically: the channel alone cannot say who
+ * acquired the tree or which guarantees it carries, and `SnapshotProvenance`
+ * (`@agent-device/kernel/snapshot`) makes a cross-channel `backend`/`producer` combination
+ * fail to compile.
+ */
+type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
+  nodes?: RawSnapshotNode[];
+  comparisonIdentity?: IosSnapshotComparisonIdentity;
+} & SnapshotProvenance;
+type SnapshotRuntimeAcquiredResult = Readonly<{
+  stage: 'acquired';
+  acquisition: IosSnapshotAcquisitionFacts & Readonly<{
+    producer: IosAcquisitionProducer;
+  }>;
+}>;
+type SnapshotRuntimeResult = SnapshotResult | SnapshotRuntimeAcquiredResult;
+type Interactor = {
+  open(app: string, options?: {
+    activity?: string;
+    appBundleId?: string;
+    launchConsole?: string;
+    launchArgs?: string[];
+    terminateRunningApp?: boolean;
+    url?: string;
+  }): Promise<void>;
+  openDevice(): Promise<void>;
+  close(app: string): Promise<void>;
+  tap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
+  pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
+  /** Alternate mouse buttons for owners that otherwise use the shared point-press series. */
+  alternateClick?(point: Point, button: 'secondary' | 'middle'): Promise<Record<string, unknown> | void>;
+  /** Owner-native ref routes; currently the managed web runtime is their only local owner. */
+  tapRef?(ref: string): Promise<Record<string, unknown> | void>;
+  tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
+  doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
+  /**
+   * Move the pointer to a point without pressing. Only pointer-driven
+   * platforms (web today) implement it; touch platforms have no hover state
+   * and leave it undefined, which the `hover` command reports as unsupported.
+   */
+  hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
+  hoverRef?(ref: string): Promise<Record<string, unknown> | void>;
+  focus(x: number, y: number): Promise<Record<string, unknown> | void>;
+  type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
+  /**
+   * Replace the target's text with `text`. The empty string is the clear request (#2063), not a
+   * no-op: an implementation must empty the field or fail — never report success over an
+   * untouched value. A backend with no clear mechanism refuses the empty text up front (see the
+   * webdriver interactor).
+   */
+  fill(x: number, y: number, text: string, delayMs?: number, options?: {
+    allowNonHittableCoordinateFallback?: boolean;
+  }): Promise<Record<string, unknown> | void>;
+  fillRef?(ref: string, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
+  scroll(direction: ScrollDirection, options?: ScrollExecutionOptions): Promise<Record<string, unknown> | void>;
+  screenshot(outPath: string, options?: ScreenshotOptions): Promise<void>;
+  setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
+  snapshot(options?: SnapshotOptions): Promise<SnapshotRuntimeResult>;
+  /**
+   * Native reading of the live text at a point, when the backend has one. Answers the text the
+   * owner can see right now, which can exceed what an already-captured node carries (an editable
+   * field whose value is longer than its label). Optional: a backend without it leaves the
+   * captured tree as the complete answer.
+   */
+  readTextAtPoint?(point: Point, options?: {
+    appBundleId?: string;
+    surface?: SessionSurface;
+    signal?: AbortSignal;
+  }): Promise<string | undefined>;
+  /**
+   * Native text-presence reading, when the backend has one that does not require a tree capture.
+   * A `true` answer is authoritative; anything else means "not proven here" and the caller
+   * consults the canonical tree (see `FindTextResult`).
+   */
+  findText?(text: string, options?: {
+    appBundleId?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    found: boolean;
+  }>;
+  /** Native one-sided observation for a simple selector; false defers to canonical capture. */
+  findSelector?(selector: Readonly<{
+    key: ElementSelectorKey;
+    value: string;
+  }>, options?: {
+    appBundleId?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    found: boolean;
+  }>;
+  gestureViewport?(): Promise<Rect>;
+  back(mode?: BackMode): Promise<void>;
+  home(): Promise<void>;
+  setOrientation(orientation: DeviceRotation): Promise<{
+    orientation?: DeviceRotation;
+  } | void>;
+  performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
+  appSwitcher(): Promise<void>;
+  tvRemote(button: TvRemoteButton, durationMs?: number): Promise<void>;
+  /** Optional: only Android implements a live status read (see {@link KeyboardStatusResult}). */
+  keyboardStatus?(): Promise<KeyboardStatusResult>;
+  /** Optional: platforms with no keyboard-dismiss concept leave it undefined. */
+  keyboardDismiss?(): Promise<KeyboardDismissResult>;
+  /** Optional: platforms with no keyboard-return concept leave it undefined. */
+  keyboardEnter?(): Promise<KeyboardEnterResult>;
+  readClipboard(): Promise<string>;
+  writeClipboard(text: string): Promise<void>;
+  setSetting(setting: string, state: string, appId?: string, options?: SettingOptions): Promise<Record<string, unknown> | void>;
+  /**
+   * The four alert legs. Each owner runs its own observation and, where it needs one, its own
+   * poll: an alert is a transient device surface, and how long to look for it — and how to press
+   * its buttons — is family mechanics, not something a caller can supply. `timeoutMs` is the
+   * whole window the caller allows; the owner spends it however its backend requires.
+   */
+  readAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  awaitAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  acceptAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+  dismissAlert(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
+};
+/**
+ * The session-derived target one alert leg acts on. `appBundleId` is separate from the runner
+ * context's because the macOS helper reads a frontmost-app surface with no bundle at all, and
+ * the two must not collapse into one field that means both.
+ */
+type AlertInteractorOptions = {
+  timeoutMs?: number;
+  appBundleId?: string;
+  surface?: SessionSurface;
+};
+//#endregion
 //#region packages/selectors/src/internal/parse.d.ts
 type SelectorKey = 'id' | 'role' | 'text' | 'label' | 'value' | 'appname' | 'windowtitle' | 'visible' | 'hidden' | 'editable' | 'selected' | 'focused' | 'enabled' | 'hittable';
 type SelectorTerm = {
@@ -614,4 +942,4 @@ declare function formatSelectorFailure(chain: SelectorChain | string, diagnostic
   unique?: boolean;
 }): string;
 //#endregion
-export { ClickButton as C, SnapshotDiagnosticsSummary as D, ScreenshotResultData as E, SessionSurface as O, BackMode as S, FindLocator as T, SettleObservation as _, resolveSelectorChain as a, TvRemoteButton as b, isSelectorToken as c, ClickCommandResponseData as d, FillCommandResponseData as f, PressCommandResponseData as g, LongPressCommandResponseData as h, findSelectorChainMatch as i, parseSelectorChain as l, HoverCommandResponseData as m, isNodeEditable as n, SelectorDiagnostics as o, FindCommandResponseData as p, isNodeVisible as r, SelectorChain as s, formatSelectorFailure as t, tryParseSelectorChain as u, Interactor as v, AndroidSnapshotBackendMetadata as w, DeviceRotation as x, RunnerContext as y };
+export { ScrollInputDirection as A, BackMode as C, PointerTrajectorySample as D, PointerTrajectory as E, AndroidSnapshotBackendMetadata as F, FindLocator as I, ScreenshotResultData as L, SwipePreset as M, TransformGestureParams as N, SinglePointerGesturePlan as O, ClickButton as P, SnapshotDiagnosticsSummary as R, DeviceRotation as S, MultiTouchGesturePlan as T, HoverCommandResponseData as _, resolveSelectorChain as a, SettleObservation as b, isSelectorToken as c, Interactor as d, RunnerContext as f, FindCommandResponseData as g, FillCommandResponseData as h, findSelectorChainMatch as i, SwipePattern as j, ScrollDirection as k, parseSelectorChain as l, ClickCommandResponseData as m, isNodeEditable as n, SelectorDiagnostics as o, ScrollCommandResult as p, isNodeVisible as r, SelectorChain as s, formatSelectorFailure as t, tryParseSelectorChain as u, LongPressCommandResponseData as v, GesturePointerCount as w, TvRemoteButton as x, PressCommandResponseData as y, SessionSurface as z };

package/dist/src/sdk-selectors.js

@@ -1 +1 @@
-import{pn as e}from"./sdk-batch-runner.js";function t(t,n,r){return e(typeof t==`string`?t:t.raw,n,r)}export{t};
+import{yn as e}from"./sdk-batch.js";function t(t,n,r){return e(typeof t==`string`?t:t.raw,n,r)}export{t};

package/dist/src/selection.js

@@ -0,0 +1 @@
+import{Fr as e,Tr as t,xr as n}from"./sdk-batch.js";import{r}from"./mobile-snapshot-semantics.js";function i(e,t,n={}){let i=a(e);if(i.length===0)return{canScroll:!1,emptySnapshot:!0};let s=r(i),c=o(i,s,t,n);return c?{canScroll:d(c,s.get(c.index),t),emptySnapshot:!1,scope:f(c,i)}:{canScroll:!1,emptySnapshot:!1}}function a(e){return e.map((e,t)=>({...e,ref:`ref`in e&&e.ref?e.ref:`e${t+1}`}))}function o(t,r,i,a){let o=n(t),d=t.filter(t=>e(t)&&v(t.rect));if(d.length===0)return null;let f=u(a.nodeIndex,o.nodeByIndex);if(f)return f;let p=a.point;if(p)return c(d,r,i,p)||s(d,r,i,o);let m=l(t);if(m){let e=c(d,r,i,m);if(e)return e}return s(d,r,i,o)}function s(e,t,n,r){let i=e.filter(e=>d(e,t.get(e.index),n)).sort((e,t)=>h(t,e));return i.length>0?i[0]??null:e.filter(r.isVisibleInEffectiveViewport).sort((e,t)=>h(t,e))[0]??e.sort((e,t)=>h(t,e))[0]??null}function c(e,t,n,r){let i=e.filter(e=>e.rect&&_(e.rect,r)).sort(h);return i.find(e=>d(e,t.get(e.index),n))??i[0]??null}function l(e){let n=e.filter(e=>t(e)&&v(e.rect)).sort((e,t)=>h(t,e))[0]?.rect;if(n)return{x:n.x+n.width/2,y:n.y+n.height/2}}function u(t,n){if(t===void 0)return null;let r=n.get(t);for(;r;){if(e(r)&&v(r.rect))return r;r=r.parentIndex===void 0?void 0:n.get(r.parentIndex)}return null}function d(e,t,n){return n===`bottom`?e.hiddenContentBelow===!0||t?.hiddenContentBelow===!0:e.hiddenContentAbove===!0||t?.hiddenContentAbove===!0}function f(e,t){return[e.identifier,e.label].filter(e=>typeof e==`string`).map(e=>e.trim()).find(n=>m(n)&&p(n,e,t))}function p(e,t,n){let r=e.toLowerCase(),i=n.filter(e=>[e.identifier,e.label,e.value].some(e=>typeof e==`string`&&e.trim().toLowerCase().includes(r)));return i.length===1&&i[0]?.index===t.index}function m(e){return e.length>0&&e.length<=80&&!/^(true|false)$/i.test(e)&&!/^\d+$/.test(e)&&!/^\d+%$/.test(e)}function h(e,t){return g(e.rect)-g(t.rect)}function g(e){return e?e.width*e.height:0}function _(e,t){return t.x>=e.x&&t.x<=e.x+e.width&&t.y>=e.y&&t.y<=e.y+e.height}function v(e){return!!(e&&e.width>0&&e.height>0)}export{i as analyzeScrollEdgeState};