agent-device 0.20.9 → 0.20.10

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

@@ -23,6 +23,127 @@ type DeviceInfo = {
   iosPhysicalDeviceBackend?: 'coredevice' | 'xctest';
 };
 //#endregion
+//#region packages/kernel/src/errors.d.ts
+/**
+ * The known error codes as a value, so gates can enumerate them: every code
+ * here must resolve a hint through `defaultHintForCode`, and every code
+ * `retriableForErrorCode` classifies must have a recovery quiz in the help
+ * benchmark (scripts/__tests__/help-conformance-error-recovery-coverage.test.ts).
+ * `KnownAppErrorCode` is derived from this array, so a new code cannot be added
+ * to the type without entering the enumeration.
+ */
+declare const KNOWN_APP_ERROR_CODES: readonly ['INVALID_ARGS', 'DEVICE_NOT_FOUND', 'DEVICE_IN_USE', 'TOOL_MISSING', 'APP_NOT_INSTALLED', 'UNSUPPORTED_PLATFORM', 'UNSUPPORTED_OPERATION', 'NOT_IMPLEMENTED', 'COMMAND_FAILED', 'SESSION_NOT_FOUND', 'UNAUTHORIZED', 'AMBIGUOUS_MATCH', 'REPLAY_DIVERGENCE', 'REPAIR_SESSION_EXPIRED', 'REPAIR_COMMIT_FAILED', 'UNKNOWN'];
+type KnownAppErrorCode = (typeof KNOWN_APP_ERROR_CODES)[number];
+type AppErrorCode = KnownAppErrorCode | (string & {});
+/**
+ * Locator for one request's diagnostics record on the daemon host, in the
+ * daemon's own vocabulary rather than as a filesystem path: `logPath` names
+ * that same record as a path, which only a caller on the daemon host can read.
+ * A remote caller fetches the record by this locator instead
+ * (`GET /sessions/<session>/requests/<requestId>/diagnostics`).
+ */
+type DiagnosticsRecordRef = {
+  session: string;
+  requestId: string;
+};
+/**
+ * Details bag for AppError. Free-form context is allowed, but these keys carry
+ * meaning at normalize/render time and must keep their types:
+ * - `hint` — overrides `defaultHintForCode`; re-wraps preserve an existing hint.
+ * - `diagnosticId` / `logPath` / `logPathUnavailable` / `diagnosticsRecord` —
+ *   lifted onto the normalized error, stripped from details.
+ * - `processExitError` + `stdout`/`stderr`/`exitCode` — marks a wrap of a real
+ *   process exit so normalizeError can surface the first meaningful stderr line;
+ *   build these via `execFailureDetails`/`requireExecSuccess` in src/utils/exec.ts
+ *   rather than by hand.
+ * - `retriable` — typed retry signal hoisted to the wire error shape.
+ * - `reason` — machine-dispatchable sub-classification within a code.
+ */
+type AppErrorDetails = Record<string, unknown> & {
+  hint?: string;
+  diagnosticId?: string;
+  logPath?: string;
+  logPathUnavailable?: string;
+  diagnosticsRecord?: DiagnosticsRecordRef;
+  retriable?: boolean;
+  supportedOn?: string;
+  processExitError?: boolean;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  reason?: string;
+};
+type NormalizedError = {
+  code: string;
+  message: string;
+  hint?: string;
+  diagnosticId?: string;
+  /**
+   * Diagnostics record path **the reader of this error can open**. A daemon
+   * renders its own host path here; a client talking to a REMOTE daemon
+   * replaces it with the caller-local copy it fetched, or drops it and sets
+   * `logPathUnavailable` (see `localizeRemoteDaemonError`). A path the reader
+   * cannot open never belongs in this field (#1801).
+   */
+  logPath?: string;
+  /**
+   * Why no readable `logPath` could be produced, e.g.
+   * `remote daemon https://host, request 8f2c: 404`. Set only in place of
+   * `logPath`, and never carries a daemon-host path.
+   */
+  logPathUnavailable?: string;
+  /** Locator the record can be fetched by when it lives on a remote daemon. */
+  diagnosticsRecord?: DiagnosticsRecordRef;
+  /**
+   * Lifted from `details.retriable` when a throw site classified the failure as
+   * clearly transient (or clearly not). Included only when set, so the default
+   * error wire shape is unchanged.
+   */
+  retriable?: boolean;
+  supportedOn?: string;
+  details?: Record<string, unknown>;
+};
+/**
+ * Error payload returned by the daemon transport. It is kept beside the local
+ * error representation because clients immediately rehydrate this wire shape
+ * into `AppError` before rendering or handling it.
+ */
+type DaemonError = {
+  code: string;
+  message: string;
+  hint?: string;
+  diagnosticId?: string;
+  /** Path on the DAEMON host. Meaningful to a local caller only (#1801). */
+  logPath?: string;
+  /** Why no readable path is named; set by the client, never by the daemon. */
+  logPathUnavailable?: string;
+  /**
+   * Additive locator (#1801) for the request diagnostics record `logPath`
+   * names, so a remote caller can fetch it over the daemon API instead of
+   * being handed a path on a filesystem it cannot read.
+   */
+  diagnosticsRecord?: DiagnosticsRecordRef;
+  details?: Record<string, unknown>;
+  /** Additive retry and platform-support signals; absent when not derivable. */
+  retriable?: boolean;
+  supportedOn?: string;
+};
+declare class AppError extends Error {
+  code: AppErrorCode;
+  details?: AppErrorDetails;
+  cause?: unknown;
+  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
+}
+declare function isAgentDeviceError(err: unknown): err is AppError;
+type NormalizeErrorContext = {
+  diagnosticId?: string;
+  logPath?: string;
+  diagnosticsRecord?: DiagnosticsRecordRef;
+};
+declare function normalizeAgentDeviceError(err: unknown, context?: NormalizeErrorContext): NormalizedError;
+declare function normalizeError(err: unknown, context?: NormalizeErrorContext): NormalizedError;
+declare function defaultHintForCode(code: string): string | undefined;
+//#endregion
 //#region packages/kernel/src/snapshot.d.ts
 /**
  * Structured quality verdict computed once by the iOS runner's snapshot capture plan.
@@ -172,90 +293,6 @@ type ScreenshotOverlayRef = {
 };
 declare function centerOfRect(rect: Rect): Point;
 //#endregion
-//#region packages/kernel/src/errors.d.ts
-/**
- * The known error codes as a value, so gates can enumerate them: every code
- * here must resolve a hint through `defaultHintForCode`, and every code
- * `retriableForErrorCode` classifies must have a recovery quiz in the help
- * benchmark (scripts/__tests__/help-conformance-error-recovery-coverage.test.ts).
- * `KnownAppErrorCode` is derived from this array, so a new code cannot be added
- * to the type without entering the enumeration.
- */
-declare const KNOWN_APP_ERROR_CODES: readonly ['INVALID_ARGS', 'DEVICE_NOT_FOUND', 'DEVICE_IN_USE', 'TOOL_MISSING', 'APP_NOT_INSTALLED', 'UNSUPPORTED_PLATFORM', 'UNSUPPORTED_OPERATION', 'NOT_IMPLEMENTED', 'COMMAND_FAILED', 'SESSION_NOT_FOUND', 'UNAUTHORIZED', 'AMBIGUOUS_MATCH', 'REPLAY_DIVERGENCE', 'REPAIR_SESSION_EXPIRED', 'REPAIR_COMMIT_FAILED', 'UNKNOWN'];
-type KnownAppErrorCode = (typeof KNOWN_APP_ERROR_CODES)[number];
-type AppErrorCode = KnownAppErrorCode | (string & {});
-/**
- * Details bag for AppError. Free-form context is allowed, but these keys carry
- * meaning at normalize/render time and must keep their types:
- * - `hint` — overrides `defaultHintForCode`; re-wraps preserve an existing hint.
- * - `diagnosticId` / `logPath` — lifted onto the normalized error, stripped from details.
- * - `processExitError` + `stdout`/`stderr`/`exitCode` — marks a wrap of a real
- *   process exit so normalizeError can surface the first meaningful stderr line;
- *   build these via `execFailureDetails`/`requireExecSuccess` in src/utils/exec.ts
- *   rather than by hand.
- * - `retriable` — typed retry signal hoisted to the wire error shape.
- * - `reason` — machine-dispatchable sub-classification within a code.
- */
-type AppErrorDetails = Record<string, unknown> & {
-  hint?: string;
-  diagnosticId?: string;
-  logPath?: string;
-  retriable?: boolean;
-  supportedOn?: string;
-  processExitError?: boolean;
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number | null;
-  reason?: string;
-};
-type NormalizedError = {
-  code: string;
-  message: string;
-  hint?: string;
-  diagnosticId?: string;
-  logPath?: string;
-  /**
-   * Lifted from `details.retriable` when a throw site classified the failure as
-   * clearly transient (or clearly not). Included only when set, so the default
-   * error wire shape is unchanged.
-   */
-  retriable?: boolean;
-  supportedOn?: string;
-  details?: Record<string, unknown>;
-};
-/**
- * Error payload returned by the daemon transport. It is kept beside the local
- * error representation because clients immediately rehydrate this wire shape
- * into `AppError` before rendering or handling it.
- */
-type DaemonError = {
-  code: string;
-  message: string;
-  hint?: string;
-  diagnosticId?: string;
-  logPath?: string;
-  details?: Record<string, unknown>;
-  /** Additive retry and platform-support signals; absent when not derivable. */
-  retriable?: boolean;
-  supportedOn?: string;
-};
-declare class AppError extends Error {
-  code: AppErrorCode;
-  details?: AppErrorDetails;
-  cause?: unknown;
-  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
-}
-declare function isAgentDeviceError(err: unknown): err is AppError;
-declare function normalizeAgentDeviceError(err: unknown, context?: {
-  diagnosticId?: string;
-  logPath?: string;
-}): NormalizedError;
-declare function normalizeError(err: unknown, context?: {
-  diagnosticId?: string;
-  logPath?: string;
-}): NormalizedError;
-declare function defaultHintForCode(code: string): string | undefined;
-//#endregion
 //#region packages/kernel/src/contracts.d.ts
 type SessionRuntimeHints = {
   platform?: 'ios' | 'android';
@@ -367,4 +404,4 @@ type JsonRpcRequestEnvelope<TParams = unknown> = {
   params?: TParams;
 };
 //#endregion
-export { SnapshotNode as A, DeviceTarget as B, normalizeAgentDeviceError as C, Rect as D, RawSnapshotNode as E, SnapshotVisibility as F, PlatformSelector as H, centerOfRect as I, AppleOS as L, SnapshotQualityVerdict as M, SnapshotState as N, ScreenshotOverlayRef as O, SnapshotUnchanged as P, DeviceInfo as R, isAgentDeviceError as S, Point as T, PublicPlatform as U, Platform as V, SessionRuntimeHints as _, DaemonRequest as a, NormalizedError as b, DaemonServerMode as c, JsonRpcRequestEnvelope as d, LeaseBackend as f, SessionIsolationMode as g, ResponseLevel as h, DaemonLockPolicy as i, SnapshotOptions as j, SnapshotBackend as k, DaemonTransportPreference as l, ResponseCost as m, DaemonArtifactType as n, DaemonResponse as o, NetworkIncludeMode as p, DaemonInstallSource as r, DaemonResponseData as s, DaemonArtifact as t, JsonRpcId as u, AppError as v, normalizeError as w, defaultHintForCode as x, DaemonError as y, DeviceKind as z };
+export { AppError as A, DeviceTarget as B, SnapshotNode as C, SnapshotUnchanged as D, SnapshotState as E, normalizeAgentDeviceError as F, PlatformSelector as H, normalizeError as I, AppleOS as L, NormalizedError as M, defaultHintForCode as N, SnapshotVisibility as O, isAgentDeviceError as P, DeviceInfo as R, SnapshotBackend as S, SnapshotQualityVerdict as T, PublicPlatform as U, Platform as V, SessionRuntimeHints as _, DaemonRequest as a, Rect as b, DaemonServerMode as c, JsonRpcRequestEnvelope as d, LeaseBackend as f, SessionIsolationMode as g, ResponseLevel as h, DaemonLockPolicy as i, DaemonError as j, centerOfRect as k, DaemonTransportPreference as l, ResponseCost as m, DaemonArtifactType as n, DaemonResponse as o, NetworkIncludeMode as p, DaemonInstallSource as r, DaemonResponseData as s, DaemonArtifact as t, JsonRpcId as u, Point as v, SnapshotOptions as w, ScreenshotOverlayRef as x, RawSnapshotNode as y, DeviceKind as z };

package/dist/src/sdk-contracts.js

@@ -1,2 +1,2 @@
-import{n as e}from"./rolldown-runtime.js";const t=/(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key|user[_-]?code|device[_-]?code|refresh[_-]?credential)/i,n=/\b(?:bearer\s+[a-z0-9._-]+|adc_(?:agent|live|refresh|cli)_[a-z0-9._-]+)\b/gi,r=/\b([a-z0-9_-]*(?:api[_-]?key|token|secret|password|user[_-]?code|device[_-]?code|refresh[_-]?credential)[a-z0-9_-]*)(\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gi,i=/https?:\/\/[^\s"'<>]+/gi;function a(e){return o(e,new WeakSet)}function o(e,n,r){if(e==null)return e;if(typeof e==`string`)return s(e,r);if(typeof e!=`object`)return e;if(n.has(e))return`[Circular]`;if(n.add(e),Array.isArray(e))return e.map(e=>o(e,n));let i={};for(let[r,a]of Object.entries(e)){if(t.test(r)){i[r]=`[REDACTED]`;continue}i[r]=o(a,n,r)}return i}function s(e,i){let a=e.trim();if(!a)return e;if(i&&t.test(i))return`[REDACTED]`;let o=c(a);return o=o.replace(n,`[REDACTED]`),o=o.replace(r,(e,t,n,r,i,a)=>u({key:t,separator:n,rawValue:r,offset:i,input:a})||l(r)?e:`${t}${n}[REDACTED]`),o===a?a.length>400?`${a.slice(0,200)}...<truncated>`:a:o}function c(e){return e.replace(i,e=>d(e)??e)}function l(e){return/^adc_(?:agent|live|refresh|cli)_\.\.\.$/i.test(e)}function u(e){if(e.key.toLowerCase()!==`token`||!e.separator.includes(`:`))return!1;try{return new URL(e.rawValue).pathname.replace(/\/+$/,``)===`/api-keys`?/(?:^|\b)(?:service\/)?api\s+$/i.test(e.input.slice(0,e.offset)):!1}catch{return!1}}function d(e){try{let t=new URL(e);return t.search&&=`?REDACTED`,(t.username||t.password)&&(t.username=`REDACTED`,t.password=`REDACTED`),t.toString()}catch{return null}}var f=e({AppError:()=>h,KNOWN_APP_ERROR_CODES:()=>p,asAppError:()=>_,defaultHintForCode:()=>j,isAgentDeviceError:()=>v,normalizeAgentDeviceError:()=>y,normalizeError:()=>b,retriableForErrorCode:()=>A,throwDaemonError:()=>g,toAppErrorCode:()=>m});const p=[`INVALID_ARGS`,`DEVICE_NOT_FOUND`,`DEVICE_IN_USE`,`TOOL_MISSING`,`APP_NOT_INSTALLED`,`UNSUPPORTED_PLATFORM`,`UNSUPPORTED_OPERATION`,`NOT_IMPLEMENTED`,`COMMAND_FAILED`,`SESSION_NOT_FOUND`,`UNAUTHORIZED`,`AMBIGUOUS_MATCH`,`REPLAY_DIVERGENCE`,`REPAIR_SESSION_EXPIRED`,`REPAIR_COMMIT_FAILED`,`UNKNOWN`];function m(e,t=`COMMAND_FAILED`){return typeof e==`string`&&e.length>0?e:t}var h=class extends Error{code;details;cause;constructor(e,t,n,r){super(t),this.code=e,this.details=n,this.cause=r}};function g(e){throw new h(m(e.code),e.message,{...e.details??{},hint:e.hint,diagnosticId:e.diagnosticId,logPath:e.logPath,retriable:e.retriable,supportedOn:e.supportedOn})}function _(e,t=`UNKNOWN`){return e instanceof h?e:e instanceof Error?new h(t,e.message,void 0,e):new h(t,`Unknown error`,{err:e})}function v(e){return e instanceof h}function y(e,t={}){return b(e,t)}function b(e,t={}){let n=_(e),r=n.details?a(n.details):void 0,i=T(r,`diagnosticId`)??t.diagnosticId,o=T(r,`logPath`)??t.logPath,s=T(r,`hint`)??j(n.code),c=E(r,`retriable`)??A(n.code),l=T(r,`supportedOn`),u=D(r),d=ee(n.code,n.message,r);return{code:n.code,message:d,hint:s,diagnosticId:i,logPath:o,...c===void 0?{}:{retriable:c},...l===void 0?{}:{supportedOn:l},details:u}}const x=/^\S+ exited with code -?\d+$/;function ee(e,t,n){if(e!==`COMMAND_FAILED`||n?.processExitError!==!0)return t;let r=w(typeof n?.stderr==`string`?n.stderr:``);return r?x.test(t)?r:t.includes(r)?t:`${t}: ${r}`:t}const S=[/^an error was encountered processing the command/i,/^underlying error\b/i,/^simulator device failed to complete the requested operation/i],C=/^(?:(?:adb|xcrun|simctl):\s*)?(?:error:\s*)?/i;function w(e){for(let t of e.split(`
-`)){let e=t.trim();if(!e||S.some(t=>t.test(e)))continue;let n=e.replace(C,``).trim();if(n)return n.length>200?`${n.slice(0,200)}...`:n}return null}function T(e,t){let n=e?.[t];return typeof n==`string`?n:void 0}function E(e,t){let n=e?.[t];return typeof n==`boolean`?n:void 0}function D(e){if(!e)return;let t={...e};return delete t.hint,delete t.diagnosticId,delete t.logPath,delete t.retriable,delete t.supportedOn,Object.keys(t).length>0?t:void 0}const O={DEVICE_IN_USE:!0};function k(e){return p.includes(e)}function A(e){return k(e)?O[e]:void 0}function j(e){switch(e){case`INVALID_ARGS`:return`Check command arguments and run --help for usage examples.`;case`SESSION_NOT_FOUND`:return`Run open first or pass an explicit device selector.`;case`TOOL_MISSING`:return`Install required platform tooling and ensure it is available in PATH.`;case`DEVICE_NOT_FOUND`:return`Verify the target device is booted/connected and selectors match.`;case`APP_NOT_INSTALLED`:return`Run apps to discover the exact installed package or bundle id, or install the app before open.`;case`UNSUPPORTED_OPERATION`:return`This command is not available for the selected platform/device.`;case`UNSUPPORTED_PLATFORM`:return`This platform is not supported for the requested operation; run devices to inspect available targets.`;case`AMBIGUOUS_MATCH`:return`Multiple candidates matched. Narrow the query or pass an exact identifier.`;case`DEVICE_IN_USE`:return`The device is busy with another agent-device request; retry once it frees up.`;case`REPLAY_DIVERGENCE`:return`Read details.divergence (screen/suggestions) for repair context, or rerun with --json for the full report.`;case`REPAIR_SESSION_EXPIRED`:return`The --save-script repair session was reaped before it was finalized; re-run replay <script> --save-script from the start.`;case`REPAIR_COMMIT_FAILED`:return`The repair transaction completed, but committing its healed script failed at teardown (no-clobber refusal or a filesystem error); inspect the target path/permissions, then re-run replay <script> --save-script to retry.`;case`NOT_IMPLEMENTED`:return`This command is part of the planned API but is not implemented yet.`;case`COMMAND_FAILED`:return`Retry with --debug and inspect diagnostics log for details.`;case`UNAUTHORIZED`:return`Refresh daemon metadata and retry the command.`;case`UNKNOWN`:return`Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.`;default:return`Retry with --debug and inspect diagnostics log for details.`}}function M(e){return e===`xctest`||e===`android`||e===`harmonyos-arkui`||e===`macos-helper`||e===`linux-atspi`||e===`web`}function N(e){return e===void 0||e===`xctest`||e===`android`||e===`harmonyos-arkui`}function P(e){return e.map((e,t)=>({...e,ref:`e${t+1}`}))}const F=/^~s(\d+)$/,I=`Refs look like @e12, optionally pinned to the snapshot generation that minted them: @e12~s3 (the ref, then "~s" and the refsGeneration reported by the issuing snapshot/find response).`;function L(e){let t=e.trim(),n=t.indexOf(`~`);if(n===-1)return{base:t};let r=F.exec(t.slice(n));return!r||n===0?null:{base:t.slice(0,n),generation:Number(r[1])}}function R(e){let t=L(e);if(!t)return null;let n=t.base;return n.startsWith(`@`)?n.slice(1)||null:n.startsWith(`e`)?n:null}function z(e,t){return e.find(e=>e.ref===t)??null}function B(e){return JSON.stringify({interactiveOnly:e?.interactiveOnly===!0,depth:typeof e?.depth==`number`?e.depth:null,scope:e?.scope?.trim()||null,raw:e?.raw===!0,customActions:e?.customActions===!0})}function V(e){if(e)return{depth:e.snapshotDepth,interactiveOnly:e.snapshotInteractiveOnly,raw:e.snapshotRaw,scope:e.snapshotScope,customActions:e.snapshotCustomActions}}function H(e){return{x:Math.round(e.x+e.width/2),y:Math.round(e.y+e.height/2)}}const U=[`summary`,`headers`,`body`,`all`],W=[`digest`,`default`,`full`];function G(e){return e!==void 0&&e!=="default"}function K(e){return{parse(t){return e(t,`$`)}}}function q(e,t){throw Error(`${e}: ${t}`)}function J(e,t){return(!e||typeof e!=`object`||Array.isArray(e))&&q(t,`Expected an object`),e}function Y(e,t){return typeof e!=`string`&&q(t,`Expected a string`),e}function X(e,t){return Number.isInteger(e)||q(t,`Expected an integer`),e}function Z(e,t){return Array.isArray(e)||q(t,`Expected an array`),e}function Q(e,t,n){let r=e[t];return r===void 0?void 0:Y(r,`${n}.${t}`)}function te(e,t,n){let r=e[t];if(r!==void 0)return Z(r,`${n}.${t}`).map((e,r)=>Y(e,`${n}.${t}[${String(r)}]`))}function ne(e,t,n){let r=e[t];return r===void 0?void 0:X(r,`${n}.${t}`)}function $(e,t,n){let r=e[t];return r===void 0?void 0:J(r,`${n}.${t}`)}function re(e,t,n,r){let i=e[t];if(i!==void 0)return(typeof i!=`string`||!n.includes(i))&&q(`${r}.${t}`,`Expected one of: ${n.join(`, `)}`),i}const ie=K((e,t)=>{let n=J(e,t);return{platform:re(n,`platform`,[`ios`,`android`],t),metroHost:Q(n,`metroHost`,t),metroPort:ne(n,`metroPort`,t),bundleUrl:Q(n,`bundleUrl`,t),launchUrl:Q(n,`launchUrl`,t)}});function ae(e,t){let n=e.id;return n==null||typeof n!=`string`&&typeof n!=`number`&&q(`${t}.id`,`Expected a string, number, or null`),n}const oe=K((e,t)=>{let n=J(e,t);return{jsonrpc:Q(n,`jsonrpc`,t),id:ae(n,t),method:Q(n,`method`,t),params:n.params}}),se=K((e,t)=>{let n=J(e,t);return{token:Q(n,`token`,t),session:Q(n,`session`,t),command:Q(n,`command`,t),positionals:te(n,`positionals`,t),input:$(n,`input`,t),flags:$(n,`flags`,t),runtime:$(n,`runtime`,t),meta:$(n,`meta`,t)}});export{b as C,a as D,m as E,y as S,g as T,h as _,G as a,f as b,P as c,z as d,M as f,N as g,L as h,ie as i,B as l,V as m,W as n,oe as o,R as p,se as r,I as s,U as t,H as u,_ as v,A as w,v as x,j as y};
+import{n as e}from"./rolldown-runtime.js";const t=/(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key|user[_-]?code|device[_-]?code|refresh[_-]?credential)/i,n=/\b(?:bearer\s+[a-z0-9._-]+|adc_(?:agent|live|refresh|cli)_[a-z0-9._-]+)\b/gi,r=/\b([a-z0-9_-]*(?:api[_-]?key|token|secret|password|user[_-]?code|device[_-]?code|refresh[_-]?credential)[a-z0-9_-]*)(\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gi,i=/https?:\/\/[^\s"'<>]+/gi;function a(e){return o(e,new WeakSet)}function o(e,n,r){if(e==null)return e;if(typeof e==`string`)return s(e,r);if(typeof e!=`object`)return e;if(n.has(e))return`[Circular]`;if(n.add(e),Array.isArray(e))return e.map(e=>o(e,n));let i={};for(let[r,a]of Object.entries(e)){if(t.test(r)){i[r]=`[REDACTED]`;continue}i[r]=o(a,n,r)}return i}function s(e,i){let a=e.trim();if(!a)return e;if(i&&t.test(i))return`[REDACTED]`;let o=c(a);return o=o.replace(n,`[REDACTED]`),o=o.replace(r,(e,t,n,r,i,a)=>u({key:t,separator:n,rawValue:r,offset:i,input:a})||l(r)?e:`${t}${n}[REDACTED]`),o===a?a.length>400?`${a.slice(0,200)}...<truncated>`:a:o}function c(e){return e.replace(i,e=>d(e)??e)}function l(e){return/^adc_(?:agent|live|refresh|cli)_\.\.\.$/i.test(e)}function u(e){if(e.key.toLowerCase()!==`token`||!e.separator.includes(`:`))return!1;try{return new URL(e.rawValue).pathname.replace(/\/+$/,``)===`/api-keys`?/(?:^|\b)(?:service\/)?api\s+$/i.test(e.input.slice(0,e.offset)):!1}catch{return!1}}function d(e){try{let t=new URL(e);return t.search&&=`?REDACTED`,(t.username||t.password)&&(t.username=`REDACTED`,t.password=`REDACTED`),t.toString()}catch{return null}}var f=e({AppError:()=>h,KNOWN_APP_ERROR_CODES:()=>p,asAppError:()=>S,createRequestCanceledError:()=>y,defaultHintForCode:()=>M,errorMessage:()=>x,isAgentDeviceError:()=>C,isRequestCanceledError:()=>b,normalizeAgentDeviceError:()=>w,normalizeError:()=>T,readDiagnosticsRecordRef:()=>A,retriableForErrorCode:()=>j,throwDaemonError:()=>g,toAppErrorCode:()=>m});const p=[`INVALID_ARGS`,`DEVICE_NOT_FOUND`,`DEVICE_IN_USE`,`TOOL_MISSING`,`APP_NOT_INSTALLED`,`UNSUPPORTED_PLATFORM`,`UNSUPPORTED_OPERATION`,`NOT_IMPLEMENTED`,`COMMAND_FAILED`,`SESSION_NOT_FOUND`,`UNAUTHORIZED`,`AMBIGUOUS_MATCH`,`REPLAY_DIVERGENCE`,`REPAIR_SESSION_EXPIRED`,`REPAIR_COMMIT_FAILED`,`UNKNOWN`];function m(e,t=`COMMAND_FAILED`){return typeof e==`string`&&e.length>0?e:t}var h=class extends Error{code;details;cause;constructor(e,t,n,r){super(t),this.code=e,this.details=n,this.cause=r}};function g(e){throw new h(m(e.code),e.message,{...e.details??{},hint:e.hint,diagnosticId:e.diagnosticId,logPath:e.logPath,logPathUnavailable:e.logPathUnavailable,diagnosticsRecord:e.diagnosticsRecord,retriable:e.retriable,supportedOn:e.supportedOn})}const _=`request_canceled`,v=`request canceled`;function y(e,t){return new h(`COMMAND_FAILED`,v,{hint:`The request was canceled intentionally (explicit cancel or client disconnect) — no retry is needed unless the cancellation was unintended.`,...e,reason:_},t)}function b(e){return!(e instanceof h)||e.code!==`COMMAND_FAILED`?!1:e.details?.reason===_?!0:e.message===v}function x(e){return e instanceof Error?e.message:String(e)}function S(e,t=`UNKNOWN`){return e instanceof h?e:e instanceof Error?new h(t,e.message,void 0,e):new h(t,`Unknown error`,{err:e})}function C(e){return e instanceof h}function w(e,t={}){return T(e,t)}function T(e,t={}){let n=S(e),r=n.details?a(n.details):void 0,i=k(r,`diagnosticId`)??t.diagnosticId,o=k(r,`logPath`)??t.logPath,s=k(r,`logPathUnavailable`),c=A(r?.diagnosticsRecord)??t.diagnosticsRecord,l=k(r,`hint`)??M(n.code),u=ne(r,`retriable`)??j(n.code),d=k(r,`supportedOn`),f=re(r),p=ee(n.code,n.message,r);return{code:n.code,message:p,hint:l,diagnosticId:i,logPath:o,...s===void 0?{}:{logPathUnavailable:s},...c===void 0?{}:{diagnosticsRecord:c},...u===void 0?{}:{retriable:u},...d===void 0?{}:{supportedOn:d},details:f}}const E=/^\S+ exited with code -?\d+$/;function ee(e,t,n){if(e!==`COMMAND_FAILED`||n?.processExitError!==!0)return t;let r=O(typeof n?.stderr==`string`?n.stderr:``);return r?E.test(t)?r:t.includes(r)?t:`${t}: ${r}`:t}const te=[/^an error was encountered processing the command/i,/^underlying error\b/i,/^simulator device failed to complete the requested operation/i],D=/^(?:(?:adb|xcrun|simctl):\s*)?(?:error:\s*)?/i;function O(e){for(let t of e.split(`
+`)){let e=t.trim();if(!e||te.some(t=>t.test(e)))continue;let n=e.replace(D,``).trim();if(n)return n.length>200?`${n.slice(0,200)}...`:n}return null}function k(e,t){let n=e?.[t];return typeof n==`string`?n:void 0}function A(e){if(!e||typeof e!=`object`)return;let{session:t,requestId:n}=e;if(!(typeof t!=`string`||typeof n!=`string`)&&!(t.length===0||n.length===0))return{session:t,requestId:n}}function ne(e,t){let n=e?.[t];return typeof n==`boolean`?n:void 0}function re(e){if(!e)return;let t={...e};return delete t.hint,delete t.diagnosticId,delete t.logPath,delete t.logPathUnavailable,delete t.diagnosticsRecord,delete t.retriable,delete t.supportedOn,Object.keys(t).length>0?t:void 0}const ie={DEVICE_IN_USE:!0};function ae(e){return p.includes(e)}function j(e){return ae(e)?ie[e]:void 0}function M(e){switch(e){case`INVALID_ARGS`:return`Check command arguments and run --help for usage examples.`;case`SESSION_NOT_FOUND`:return`Run open first or pass an explicit device selector.`;case`TOOL_MISSING`:return`Install required platform tooling and ensure it is available in PATH.`;case`DEVICE_NOT_FOUND`:return`Verify the target device is booted/connected and selectors match.`;case`APP_NOT_INSTALLED`:return`Run apps to discover the exact installed package or bundle id, or install the app before open.`;case`UNSUPPORTED_OPERATION`:return`This command is not available for the selected platform/device.`;case`UNSUPPORTED_PLATFORM`:return`This platform is not supported for the requested operation; run devices to inspect available targets.`;case`AMBIGUOUS_MATCH`:return`Multiple candidates matched. Narrow the query or pass an exact identifier.`;case`DEVICE_IN_USE`:return`The device is busy with another agent-device request; retry once it frees up.`;case`REPLAY_DIVERGENCE`:return`Read details.divergence (screen/suggestions) for repair context, or rerun with --json for the full report.`;case`REPAIR_SESSION_EXPIRED`:return`The --save-script repair session was reaped before it was finalized; re-run replay <script> --save-script from the start.`;case`REPAIR_COMMIT_FAILED`:return`The repair transaction completed, but committing its healed script failed at teardown (no-clobber refusal or a filesystem error); inspect the target path/permissions, then re-run replay <script> --save-script to retry.`;case`NOT_IMPLEMENTED`:return`This command is part of the planned API but is not implemented yet.`;case`COMMAND_FAILED`:return`Retry with --debug and inspect diagnostics log for details.`;case`UNAUTHORIZED`:return`Refresh daemon metadata and retry the command.`;case`UNKNOWN`:return`Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.`;default:return`Retry with --debug and inspect diagnostics log for details.`}}function N(e){return e===`xctest`||e===`android`||e===`harmonyos-arkui`||e===`macos-helper`||e===`linux-atspi`||e===`web`}function P(e){return e===void 0||e===`xctest`||e===`android`||e===`harmonyos-arkui`}function F(e){return e.map((e,t)=>({...e,ref:`e${t+1}`}))}const I=/^~s(\d+)$/,L=`Refs look like @e12, optionally pinned to the snapshot generation that minted them: @e12~s3 (the ref, then "~s" and the refsGeneration reported by the issuing snapshot/find response).`;function R(e){let t=e.trim(),n=t.indexOf(`~`);if(n===-1)return{base:t};let r=I.exec(t.slice(n));return!r||n===0?null:{base:t.slice(0,n),generation:Number(r[1])}}function z(e){let t=R(e);if(!t)return null;let n=t.base;return n.startsWith(`@`)?n.slice(1)||null:n.startsWith(`e`)?n:null}function B(e,t){return e.find(e=>e.ref===t)??null}function V(e){return JSON.stringify({interactiveOnly:e?.interactiveOnly===!0,depth:typeof e?.depth==`number`?e.depth:null,scope:e?.scope?.trim()||null,raw:e?.raw===!0,customActions:e?.customActions===!0})}function H(e){if(e)return{depth:e.snapshotDepth,interactiveOnly:e.snapshotInteractiveOnly,raw:e.snapshotRaw,scope:e.snapshotScope,customActions:e.snapshotCustomActions}}function U(e){return{x:Math.round(e.x+e.width/2),y:Math.round(e.y+e.height/2)}}const W=[`summary`,`headers`,`body`,`all`],G=[`digest`,`default`,`full`];function K(e){return e!==void 0&&e!=="default"}function q(e){return{parse(t){return e(t,`$`)}}}function J(e,t){throw Error(`${e}: ${t}`)}function Y(e,t){return(!e||typeof e!=`object`||Array.isArray(e))&&J(t,`Expected an object`),e}function X(e,t){return typeof e!=`string`&&J(t,`Expected a string`),e}function oe(e,t){return Number.isInteger(e)||J(t,`Expected an integer`),e}function se(e,t){return Array.isArray(e)||J(t,`Expected an array`),e}function Z(e,t,n){let r=e[t];return r===void 0?void 0:X(r,`${n}.${t}`)}function ce(e,t,n){let r=e[t];if(r!==void 0)return se(r,`${n}.${t}`).map((e,r)=>X(e,`${n}.${t}[${String(r)}]`))}function le(e,t,n){let r=e[t];return r===void 0?void 0:oe(r,`${n}.${t}`)}function Q(e,t,n){let r=e[t];return r===void 0?void 0:Y(r,`${n}.${t}`)}function $(e,t,n,r){let i=e[t];if(i!==void 0)return(typeof i!=`string`||!n.includes(i))&&J(`${r}.${t}`,`Expected one of: ${n.join(`, `)}`),i}const ue=q((e,t)=>{let n=Y(e,t);return{platform:$(n,`platform`,[`ios`,`android`],t),metroHost:Z(n,`metroHost`,t),metroPort:le(n,`metroPort`,t),bundleUrl:Z(n,`bundleUrl`,t),launchUrl:Z(n,`launchUrl`,t)}});function de(e,t){let n=e.id;return n==null||typeof n!=`string`&&typeof n!=`number`&&J(`${t}.id`,`Expected a string, number, or null`),n}const fe=q((e,t)=>{let n=Y(e,t);return{jsonrpc:Z(n,`jsonrpc`,t),id:de(n,t),method:Z(n,`method`,t),params:n.params}}),pe=q((e,t)=>{let n=Y(e,t);return{token:Z(n,`token`,t),session:Z(n,`session`,t),command:Z(n,`command`,t),positionals:ce(n,`positionals`,t),input:Q(n,`input`,t),flags:Q(n,`flags`,t),runtime:Q(n,`runtime`,t),meta:Q(n,`meta`,t)}});export{m as A,C,A as D,T as E,j as O,f as S,w as T,h as _,K as a,M as b,F as c,B as d,N as f,P as g,R as h,ue as i,a as j,g as k,V as l,H as m,G as n,fe as o,z as p,pe as r,L as s,W as t,U as u,S as v,b as w,x,y};

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

@@ -1,4 +1,4 @@
-import { A as SnapshotNode } from "./sdk-contracts.js";
+import { C as SnapshotNode } from "./sdk-contracts.js";
 //#region packages/selectors/src/internal/find.d.ts
 declare const FIND_LOCATORS: readonly ['any', 'text', 'label', 'value', 'role', 'id'];
 type FindLocator = (typeof FIND_LOCATORS)[number];

package/dist/src/sdk-finders.js

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

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

@@ -1,79 +1,5 @@
-import { A as SnapshotNode, D as Rect, E as RawSnapshotNode, M as SnapshotQualityVerdict, N as SnapshotState, O as ScreenshotOverlayRef, T as Point, U as PublicPlatform, V as Platform, j as SnapshotOptions$1, k as SnapshotBackend, m as ResponseCost } from "./sdk-contracts.js";
+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";
-//#region packages/contracts/src/back-mode.d.ts
-declare const BACK_MODES: readonly ['in-app', 'system'];
-type BackMode = (typeof BACK_MODES)[number];
-//#endregion
-//#region packages/contracts/src/click-button.d.ts
-declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
-type ClickButton = (typeof CLICK_BUTTONS)[number];
-//#endregion
-//#region packages/contracts/src/device-rotation.d.ts
-declare const DEVICE_ROTATIONS: readonly ['portrait', 'portrait-upside-down', 'landscape-left', 'landscape-right'];
-type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
-//#endregion
-//#region packages/contracts/src/tv-remote.d.ts
-declare const TV_REMOTE_BUTTON_DEFINITIONS: {
-  readonly up: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_UP';
-    readonly appleRemoteButton: 'up';
-    readonly vegaKey: 'KEY_UP';
-  };
-  readonly down: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_DOWN';
-    readonly appleRemoteButton: 'down';
-    readonly vegaKey: 'KEY_DOWN';
-  };
-  readonly left: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_LEFT';
-    readonly appleRemoteButton: 'left';
-    readonly vegaKey: 'KEY_LEFT';
-  };
-  readonly right: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_DPAD_RIGHT';
-    readonly appleRemoteButton: 'right';
-    readonly vegaKey: 'KEY_RIGHT';
-  };
-  readonly select: {
-    readonly aliases: readonly ["ok", "center", "enter"];
-    readonly androidKeyevent: 'KEYCODE_DPAD_CENTER';
-    readonly appleRemoteButton: 'select';
-    readonly vegaKey: 'KEY_ENTER';
-  };
-  readonly menu: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_MENU';
-    readonly appleRemoteButton: 'menu';
-    readonly vegaKey: 'KEY_MENU';
-  };
-  readonly home: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_HOME';
-    readonly appleRemoteButton: 'home';
-    readonly vegaKey: 'KEY_HOMEPAGE';
-  };
-  readonly back: {
-    readonly aliases: readonly [];
-    readonly androidKeyevent: 'KEYCODE_BACK';
-    readonly appleRemoteButton: 'menu';
-    readonly vegaKey: 'KEY_BACK';
-  };
-};
-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/session-surface.d.ts
 declare const SESSION_SURFACES: readonly ['app', 'frontmost-app', 'desktop', 'menubar'];
 type SessionSurface = (typeof SESSION_SURFACES)[number];
@@ -144,9 +70,85 @@ type AndroidSnapshotBackendMetadata = {
   nodeCount?: number;
   helperTruncated?: boolean;
   elapsedMs?: number;
+  /** API 23 helper output carries no `drawing-order`; covered same-window surfaces are not pruned. */
+  occlusionScanUnavailable?: boolean;
 };
 type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
 //#endregion
+//#region packages/contracts/src/click-button.d.ts
+declare const CLICK_BUTTONS: readonly ['primary', 'secondary', 'middle'];
+type ClickButton = (typeof CLICK_BUTTONS)[number];
+//#endregion
+//#region packages/contracts/src/back-mode.d.ts
+declare const BACK_MODES: readonly ['in-app', 'system'];
+type BackMode = (typeof BACK_MODES)[number];
+//#endregion
+//#region packages/contracts/src/device-rotation.d.ts
+declare const DEVICE_ROTATIONS: readonly ['portrait', 'portrait-upside-down', 'landscape-left', 'landscape-right'];
+type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
+//#endregion
+//#region packages/contracts/src/tv-remote.d.ts
+declare const TV_REMOTE_BUTTON_DEFINITIONS: {
+  readonly up: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_DPAD_UP';
+    readonly appleRemoteButton: 'up';
+    readonly vegaKey: 'KEY_UP';
+  };
+  readonly down: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_DPAD_DOWN';
+    readonly appleRemoteButton: 'down';
+    readonly vegaKey: 'KEY_DOWN';
+  };
+  readonly left: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_DPAD_LEFT';
+    readonly appleRemoteButton: 'left';
+    readonly vegaKey: 'KEY_LEFT';
+  };
+  readonly right: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_DPAD_RIGHT';
+    readonly appleRemoteButton: 'right';
+    readonly vegaKey: 'KEY_RIGHT';
+  };
+  readonly select: {
+    readonly aliases: readonly ["ok", "center", "enter"];
+    readonly androidKeyevent: 'KEYCODE_DPAD_CENTER';
+    readonly appleRemoteButton: 'select';
+    readonly vegaKey: 'KEY_ENTER';
+  };
+  readonly menu: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_MENU';
+    readonly appleRemoteButton: 'menu';
+    readonly vegaKey: 'KEY_MENU';
+  };
+  readonly home: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_HOME';
+    readonly appleRemoteButton: 'home';
+    readonly vegaKey: 'KEY_HOMEPAGE';
+  };
+  readonly back: {
+    readonly aliases: readonly [];
+    readonly androidKeyevent: 'KEYCODE_BACK';
+    readonly appleRemoteButton: 'menu';
+    readonly vegaKey: 'KEY_BACK';
+  };
+};
+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;
@@ -228,7 +230,7 @@ type SnapshotOptions = SnapshotOptions$1 & {
 };
 type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
   nodes?: RawSnapshotNode[];
-  backend: Extract<SnapshotBackend, 'android' | 'harmonyos-arkui' | 'xctest' | 'linux-atspi' | 'web'>;
+  backend: Extract<SnapshotBackend, 'android' | 'harmonyos-arkui' | 'xctest' | 'linux-atspi' | 'macos-helper' | 'web'>;
 };
 type Interactor = {
   open(app: string, options?: {
@@ -245,6 +247,12 @@ type Interactor = {
   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>;
@@ -479,6 +487,10 @@ type TouchLongPressExtras = {
   gesture: 'longpress';
 };
 type LongPressCommandResponseData = (TouchResponsePoint & TouchLongPressExtras) | (TouchResponseRef & TouchLongPressExtras) | (TouchResponseSelector & TouchLongPressExtras);
+type TouchHoverExtras = {
+  gesture: 'hover';
+};
+type HoverCommandResponseData = (TouchResponsePoint & TouchHoverExtras) | (TouchResponseRef & TouchHoverExtras) | (TouchResponseSelector & TouchHoverExtras);
 /**
  * Daemon response data for the `find` command. Read-only actions (`exists`,
  * `wait`, `get_text`, `get_attrs`) may issue a pinnable ref with
@@ -602,4 +614,4 @@ declare function formatSelectorFailure(chain: SelectorChain | string, diagnostic
   unique?: boolean;
 }): string;
 //#endregion
-export { SessionSurface as C, BackMode as D, ClickButton as E, SnapshotDiagnosticsSummary as S, DeviceRotation as T, Interactor as _, resolveSelectorChain as a, FindLocator as b, isSelectorToken as c, ClickCommandResponseData as d, FillCommandResponseData as f, SettleObservation as g, PressCommandResponseData as h, findSelectorChainMatch as i, parseSelectorChain as l, LongPressCommandResponseData as m, isNodeEditable as n, SelectorDiagnostics as o, FindCommandResponseData as p, isNodeVisible as r, SelectorChain as s, formatSelectorFailure as t, tryParseSelectorChain as u, RunnerContext as v, TvRemoteButton as w, ScreenshotResultData as x, AndroidSnapshotBackendMetadata as y };
+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 };

package/dist/src/sdk-selectors.js

@@ -1 +1 @@
-import{an 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{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};

package/dist/src/selector-runtime.js

@@ -1 +1 @@
-import{C as e,_ as t,h as n,l as r,m as i,s as a,v as o}from"./sdk-contracts.js";import{Gn as s,Hn as c,Jt as l,Pt as u,Un as d,Ut as f,Wn as p,fn as m,hr as ee,mn as te,qn as ne}from"./sdk-batch-runner.js";import{_ as re,c as h,l as ie,s as ae}from"./sdk-device.js";import{Q as oe,R as se,bt as ce,c as g,yt as le}from"./prepare-kind.js";import{t as ue}from"./interaction.js";import{X as _,j as de}from"./screenshot-result.js";import{i as fe}from"./session-target-evidence.js";import{t as pe}from"./verdict.js";import{a as me,t as he}from"./runtime.js";import{A as ge}from"./sdk-android-adb.js";import{r as _e}from"./app-lifecycle.js";import{a as v}from"./snapshot.js";import{i as ve}from"./cancel.js";import{o as y}from"./interactors.js";import{a as b,o as ye,p as be,s as x,t as xe}from"./dispatch.js";import{n as S}from"./runner-client.js";import{At as C,Et as Se,Gt as Ce,Ht as w,Kt as T,Ot as we,Rt as E,kt as D}from"./internal/daemon.js";import{a as Te,i as Ee,r as De}from"./snapshot-session.js";import{t as Oe}from"./device-ready.js";import{t as ke}from"./backend-snapshot-options.js";const Ae=[[`snapshotDepth`,`--depth`],[`snapshotScope`,`--scope`],[`snapshotRaw`,`--raw`]];function O(e,t){let n=je(t);return n.length===0?null:b(`INVALID_ARGS`,`${e} @ref does not support ${n.join(`, `)}.`)}function je(e){if(!e)return[];let t=[];for(let[n,r]of Ae)e[n]!==void 0&&t.push(r);return t}function Me(e,t){if(!t||t.settle===!0)return null;let n=[];return t.settleQuietMs!==void 0&&n.push(`--settle-quiet`),n.length===0?null:b(`INVALID_ARGS`,`${e}: ${n.join(`, `)} require${n.length===1?`s`:``} --settle.`)}function Ne(e){if(e?.settle===!0)return{...e.settleQuietMs===void 0?{}:{quietMs:e.settleQuietMs},...e.timeoutMs===void 0?{}:{timeoutMs:e.timeoutMs}}}function k(e){if(e.length<2)return null;let t=Number(e[0]),n=Number(e[1]);return!Number.isFinite(t)||!Number.isFinite(n)?null:{x:t,y:n}}function A(e){let t=n(e);return t?{ok:!0,ref:t.base,generation:t.generation}:{ok:!1,response:b(`INVALID_ARGS`,`Invalid ref "${e}" — malformed generation suffix.`,{hint:a})}}function j(e,t){let n=k(e);if(n)return{ok:!0,target:{kind:`point`,x:n.x,y:n.y}};let r=e[0]??``;if(r.startsWith(`@`)){let t=A(r);return t.ok?{ok:!0,target:{kind:`ref`,ref:t.ref,fallbackLabel:e.slice(1).join(` `).trim()},refGeneration:t.generation}:{ok:!1,response:t.response}}let i=e.join(` `).trim();return i?{ok:!0,target:{kind:`selector`,selector:i}}:{ok:!1,response:b(`INVALID_ARGS`,`${t} requires @ref, selector expression, or x y coordinates`)}}function Pe(e){let t=k(e);if(t)return{ok:!0,target:{kind:`point`,x:t.x,y:t.y},...Ve(e[2])};let n=Be(e),r=j(n.targetPositionals,`longpress`);return r.ok?{ok:!0,target:r.target,refGeneration:r.refGeneration,...n.duration}:r}function Fe(e){let t=e[0]??``;if(t.startsWith(`@`)){let n=A(t);if(!n.ok)return{ok:!1,response:n.response};let r=g(e).text;return r?{ok:!0,target:{kind:`ref`,ref:n.ref,fallbackLabel:ze(e)},refGeneration:n.generation,text:r}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after ref`)}}let n=k(e);if(n){let t=e.slice(2).join(` `);return t?{ok:!0,target:{kind:`point`,x:n.x,y:n.y},text:t}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after coordinates`)}}let r=Ie(e);return!r||r.kind!==`selector`?{ok:!1,response:b(`INVALID_ARGS`,`fill requires x y text, @ref text, or selector text`)}:r.text.trim()?{ok:!0,target:{kind:`selector`,selector:r.target.selector},text:r.text}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after selector`)}}function Ie(e){try{return g(e)}catch{return null}}function Le(e){let t=`evidence`in e?e.evidence:void 0,n=e.settle;return e.kind===`ref`?{ref:M(e.target?.kind===`ref`?e.target.ref:void 0),refLabel:e.refLabel,selectorChain:e.selectorChain,targetHittable:e.targetHittable,hint:e.hint,evidence:t,settle:n,resolution:e.resolution}:e.kind===`selector`?{selector:e.target?.kind===`selector`?e.target.selector:void 0,selectorChain:e.selectorChain,refLabel:e.refLabel,targetHittable:e.targetHittable,hint:e.hint,evidence:t,settle:n,resolution:e.resolution}:{evidence:t,settle:n}}function Re(e,t){return e.kind===`point`?`coordinate tap`:t.kind===`ref`&&t.target?.kind===`ref`?t.target.ref:t.kind===`selector`&&t.target?.kind===`selector`?t.target.selector:`target`}function M(e){return e?.startsWith(`@`)?e.slice(1):e}function ze(e){return e.length>=3&&e[1]?.trim()||``}function Be(e){let t=e.at(-1);return e.length>1&&He(t)?{targetPositionals:e.slice(0,-1),duration:{durationMs:Number(t)}}:{targetPositionals:e,duration:{}}}function Ve(e){return e===void 0?{}:{durationMs:Number(e)}}function He(e){return e===void 0||e.trim()===``?!1:Number.isFinite(Number(e))}function N(e){let{req:t,logPath:n,traceLogPath:r}=e;return{verbose:t.flags?.verbose,logPath:n,traceLogPath:r,requestId:t.meta?.requestId,iosXctestrunFile:t.flags?.iosXctestrunFile,iosXctestDerivedDataPath:t.flags?.iosXctestDerivedDataPath,iosXctestEnvDir:t.flags?.iosXctestEnvDir}}function P(e,t){return!(!e||!h(e.device)||y(e.device)||t.skipPendingPostGestureStabilization&&w(e))}function F(e){let{session:t,selectorExpression:n}=e;return P(t,{skipPendingPostGestureStabilization:!0})?l(n):null}function Ue(e){let t=e.identifier?.trim();if(t)return{key:`id`,value:t};let n=e.label?.trim();return n?{key:`label`,value:n}:null}function I(e,t={}){let n=o(e);if(n.code===`ELEMENT_NOT_FOUND`)return t.delegateSemanticFailures===!0||t.allowElementNotFound===!0;if(n.code===`AMBIGUOUS_MATCH`)return t.delegateSemanticFailures===!0;if(n.code===`ELEMENT_OFFSCREEN`)return t.delegateSemanticFailures!==!1;if(n.code!==`COMMAND_FAILED`)return!1;let r=n.message.toLowerCase();return r.includes(`fetch failed`)||r.includes(`timed out`)||r.includes(`timeout`)||r.includes(`runner did not accept connection`)||r.includes(`invalid runner response`)}async function We(e,n){let r=await L(e);if(r){if(v(r.foregroundPackage))return`press ${n} opened an Android permission dialog (${r.foregroundPackage}) over ${r.expectedPackage}. ${r.hint}`;throw new t(`COMMAND_FAILED`,`press ${n} left ${e.appBundleId} and foregrounded ${r.foregroundPackage}. The tap likely escaped the app.`,r)}}async function L(e){if(e.device.platform!==`android`||!e.appBundleId)return null;let t=await _e(e.device),n=t.package?.trim();return!n||n===e.appBundleId||!Je(n)?null:{expectedPackage:e.appBundleId,foregroundPackage:n,activity:t.activity,hint:qe(n)}}function Ge(e){return v(e.foregroundPackage)?`Android permission dialog is blocking ${e.expectedPackage}`:`${e.foregroundPackage} is foreground instead of ${e.expectedPackage}`}function Ke(e){return e.code===`COMMAND_FAILED`&&typeof e.details?.expectedPackage==`string`&&typeof e.details?.foregroundPackage==`string`}function qe(e){return v(e)?`Use "alert get" to inspect it, then "alert accept" or "alert dismiss" to respond.`:`Use screenshot as visual truth, then take a fresh snapshot -i before retrying.`}function Je(e){return e===`com.android.settings`||e===`com.android.systemui`||v(e)||e.includes(`launcher`)}function Ye(e,t){if(t===`exists`)return{found:!0};if(t===`wait`)return{found:!0,waitedMs:e.waitedMs};if(t===`list`)return{action:`list`,matches:Array.isArray(e.matches)?e.matches.length:0};let n=typeof e.ref==`string`?e.ref:void 0;return t===`get_attrs`?{ref:n,action:`get attrs`}:{ref:n,action:`get text`,text:typeof e.text==`string`?e.text:``}}function Xe(e){return e.kind===`found`?{found:!0,...typeof e.waitedMs==`number`?{waitedMs:e.waitedMs}:{}}:e.kind===`list`?{matches:e.matches.map(e=>({ref:e.ref,node:u(e.node)}))}:{ref:e.ref,...e.kind===`text`?{text:e.text}:{},node:u(e.node)}}function Ze(e,t){let n=Array.isArray(e.selectorChain)?e.selectorChain:void 0,r=et(e),i=r?.kind===`ref`?H(r.ref):void 0,a=r?.kind===`selector`?r.selector:void 0,o={...i?{ref:i}:{},...a?{selector:a}:{},...n?{selectorChain:n}:{}};if(t===`attrs`)return o;let s=typeof e.text==`string`?e.text:``;return{...o,text:s,refLabel:$e(s)}}function R(e){let{target:t}=e;return{...t.kind===`ref`?{ref:H(t.ref)}:{},...t.kind===`selector`?{selector:t.selector}:{},...typeof e.text==`string`?{text:e.text}:{},node:u(e.node)}}function z(e){let{node:t,preActionNodes:n,...r}=e;return r}function Qe(e){return{waitedMs:e.waitedMs,...typeof e.text==`string`?{text:e.text}:{},...typeof e.selector==`string`?{selector:e.selector}:{},...typeof e.captures==`number`?{captures:e.captures}:{},...typeof e.nodeCount==`number`?{nodeCount:e.nodeCount}:{},...typeof e.hint==`string`?{hint:e.hint}:{}}}function B(e){let{selectorChain:t,...n}=e;return n}function V(e,t,n,r,i,a){let o=e.get(t);if(!o)return;let s=_(o)&&i?fe(i,{mode:a}):void 0;e.recordAction(o,{command:n.command,positionals:n.positionals??[],flags:n.flags??{},result:r,interactiveObservation:de(n),...s?{targetEvidence:s}:{}})}function $e(e){let t=e.trim();if(!(!t||t.length>80||/[\r\n]/.test(t)))return t}function et(e){let t=e.target;if(!t||typeof t!=`object`)return;let n=t;if(n.kind===`ref`&&typeof n.ref==`string`)return{kind:`ref`,ref:n.ref};if(n.kind===`selector`&&typeof n.selector==`string`)return{kind:`selector`,selector:n.selector}}function H(e){return e.startsWith(`@`)?e.slice(1):e}const tt=[`application`,`window`,`tabbar`,`scrollbar`,`image`],nt=new Set([`tab bar`]);async function U(e,t){if(t.ok||!rt(t.error.details?.reason)||t.error.details?.captureStalled===!0||t.error.details?.captureTruncated===!0)return t;let n=await it(e).catch(()=>null);return n?b(t.error.code,`${t.error.message}. Current surface: ${n.summary}.`,{...t.error.details??{},currentSurface:n.details}):t}function rt(e){return e===ue.targetAbsent||e===ue.stableTimeout}async function it(e){let t=[...(await E({device:e.device,session:e.session,flags:{...e.req.flags,snapshotInteractiveOnly:!0},logPath:e.logPath??``})).snapshot.nodes].sort(at),n=W(t,6,{includeIdentifiers:!0});if(n.length===0)return null;let r=W(t.filter(e=>!lt(e)),4,{includeIdentifiers:!1}),i=W(t.filter(ut),4,{includeIdentifiers:!0});return{summary:(r.length>0?r:n.slice(0,4)).join(`, `),details:{labels:n,...i.length>0?{buttons:i}:{}}}}function W(e,t,n){let r=new Set,i=[];for(let a of e){let e=ct(a,n);if(!(!e||r.has(e))&&(r.add(e),i.push(e),i.length>=t))break}return i}function at(e,t){return ot(e)-ot(t)||st(e,t)}function ot(e){let t=!!ct(e,{includeIdentifiers:!1});return(lt(e)?2:0)+ +!t}function st(e,t){return e.rect&&t.rect?e.rect.y-t.rect.y||e.rect.x-t.rect.x:e.rect?-1:t.rect?1:(e.depth??0)-(t.depth??0)||e.index-t.index}function ct(e,t){let n=(t.includeIdentifiers?[e.label,e.value,e.identifier]:[e.label,e.value]).map(e=>typeof e==`string`?e.trim():``).find(e=>e.length>0);return n?n.replace(/\s+/g,` `).slice(0,80):``}function lt(e){let t=ee(`${e.type??``} ${e.role??``} ${e.subrole??``}`),n=`${e.label??``} ${e.value??``}`.trim().toLowerCase();return tt.some(e=>t.includes(e))||nt.has(n)||n.endsWith(`.fill`)}function ut(e){return ee(`${e.type??``} ${e.role??``} ${e.subrole??``}`).includes(`button`)}function G(e,t){let n=me(t);if(!n)return e;if(e.ok){let t=dt(e.data?.warning,n);return{...e,data:{...e.data,warning:t}}}let r=e.error.details??{};return{...e,error:{...e.error,details:{...r,hint:dt(r.hint,n)}}}}function dt(e,t){return typeof e==`string`&&e.trim()!==``?`${e}\n${t}`:t}async function ft(e){let{device:t,node:n,flags:r,appBundleId:i,traceOutPath:a,surface:o,contextFromFlags:s}=e,c=le(n),l=oe(n.rect);if(!l||h(t)&&c&&!ce(n.type??``))return c;try{let e=await xe(t,`read`,[String(l.x),String(l.y)],void 0,{...s(r,i,a),surface:o}),u=e&&typeof e==`object`?e:void 0,d=typeof u?.text==`string`?u.text:``;return d.trim()?d:(ge({level:`warn`,phase:`interaction_read_fallback`,data:{reason:`empty_backend_text`,nodeRef:n.ref,surface:o,platform:t.platform}}),c)}catch(e){return ge({level:`warn`,phase:`interaction_read_fallback`,data:{reason:`backend_read_failed`,nodeRef:n.ref,surface:o,platform:t.platform,error:e instanceof Error?e.message:String(e)}}),c}}function K(e){let{session:t,sessionStore:n,sessionName:r}=e,i=0,a,o,s=t=>(e.consumedSnapshot&&(e.consumedSnapshot.state=t.snapshot),t);return{capture:async c=>{let l=Date.now(),u=St(c,e.req.flags?.out),d=gt({timestamp:l,lastSnapshotAt:i,lastSnapshotResult:a,lastSnapshotCacheKey:o,session:t,request:c,cacheKey:u});if(d)return s(d);let f=_t({session:t,timestamp:l,request:c});if(f)return i=f.createdAt,a={snapshot:f},o=u,s(a);let p=await pt({params:e,request:c});c.signal?.throwIfAborted();let m={snapshot:p};return wt({session:t,sessionStore:n,sessionName:r,snapshot:p}),i=l,a=m,o=u,s(m)}}}async function pt(e){let{params:t,request:n}=e,r=await q(t,n,n.snapshotScope);return n.recovery?.legacyIosSparse&&Tt(r)?await mt({runtimeParams:t,request:n,policy:n.recovery.legacyIosSparse}):n.recovery?.sparseVerdictQueryScope?.shouldScope&&pe(r.snapshotQuality)?await ht({runtimeParams:t,request:n,policy:n.recovery.sparseVerdictQueryScope,snapshot:r}):r}async function mt(e){let{runtimeParams:t,request:n,policy:r}=e;try{return await q(t,n,void 0,!1)}catch(e){if(!r.shouldScope)throw e;return await q(t,n,r.query,!1)}}async function ht(e){let{runtimeParams:t,request:n,policy:r,snapshot:i}=e;try{return await q(t,n,r.query,!1)}catch{return i}}async function q(e,t,n,r=t.flags?.snapshotInteractiveOnly){return(await E({device:e.device,session:e.session,flags:{...t.flags,snapshotInteractiveOnly:r},outPath:t.outPath??e.req.flags?.out,logPath:e.logPath??``,snapshotScope:n,includeRects:t.includeRects,signal:t.signal})).snapshot}function gt(e){let{timestamp:t,lastSnapshotAt:n,lastSnapshotResult:r,lastSnapshotCacheKey:i,session:a,request:o,cacheKey:s}=e;if(o.cache?.forceFresh!==!0&&r&&i===s&&!(t-n>=750)&&!T(a)&&!bt(a,o))return r}function _t(e){let{session:t,timestamp:n,request:r}=e,i=t?.snapshot;if(i&&vt(t,r)&&yt(i,n)&&i.presentationKey===xt(r))return i}function vt(e,t){return!(t.cache?.forceFresh===!0||t.cache?.useSessionSnapshot!==!0||T(e)||bt(e,t))}function yt(e,t){return t-e.createdAt<750}function bt(e,t){return t.cache?.bypassForPostGestureStabilization===!0&&w(e)}function xt(e){return r(i(Ct(e)))}function St(e,t){return JSON.stringify({presentationKey:xt(e),includeRects:e.includeRects===!0,outPath:e.outPath??t??null})}function Ct(e){return e.snapshotScope===void 0?e.flags:{...e.flags,snapshotScope:e.snapshotScope}}function wt(e){let{session:t,sessionStore:n,sessionName:r,snapshot:i}=e;!t||pe(i.snapshotQuality)||(C(t,i),n.set(r,t))}function Tt(e){return e.snapshotQuality||e.backend!==`xctest`||e.nodes.length!==1?!1:e.nodes[0]?.type===`Application`}function Et(e){return he({backend:Dt(e),...Te(`selector commands`,{plural:!0}),sessions:Se({sessionName:e.sessionName,getSession:()=>e.session,recordOptions:{includeSnapshot:!0},setRecord:t=>{!e.session||!t.snapshot||(C(e.session,t.snapshot),e.sessionStore.set(e.sessionName,e.session))}}),signal:e.signal??ve(e.req.meta?.requestId)})}async function J(e,t){e.consumedSnapshot??={};let n=e.sessionStore.get(e.sessionName);if(!n&&t.requireSession)return{ok:!1,response:ye()};let r=n?.device??await be(e.req.flags??{});n||await Oe(r);let i=x(t.capability,r);return i?{ok:!1,response:i}:{ok:!0,runtime:Et({...e,session:n,device:r})}}function Dt(e){let{req:t,session:n,device:r,logPath:i,sessionName:a,sessionStore:o}=e,s=K({device:r,session:n,sessionStore:o,sessionName:a,req:t,consumedSnapshot:e.consumedSnapshot,logPath:i});return{platform:re(r),captureSnapshot:async(e,n)=>{let i={...t.flags,...ke(n)},a=n?.includeRects===!0,o=n?.scope??t.flags?.snapshotScope,c=t.command===`wait`||t.command===`find`||a&&r.platform===`web`;return await s.capture({flags:i,signal:e.signal,snapshotScope:o,includeRects:a,cache:{forceFresh:c,useSessionSnapshot:!0,bypassForPostGestureStabilization:!0}})},readText:async(a,o)=>({text:await ft({device:r,node:o,flags:t.flags,appBundleId:n?.appBundleId,traceOutPath:n?.trace?.outPath,surface:n?.surface,contextFromFlags:e.contextFromFlags??((e,t,n)=>Ce(i??``,e,t,n))})}),findText:async(t,n)=>({found:await Ot(e,n,t.signal)})}}async function Ot(e,t,n){let r=await kt(e,t,n);return r===null?await At(e,t,n)===!0?!0:await Nt(e,t,n):r}async function kt(e,t,n){return!ie(e.device)||!e.session?.surface||e.session.surface===`app`?null:await Nt(e,t,n)}async function At(e,t,n){let r=jt(e);return r?(await S(r.device,{command:`findText`,text:t,appBundleId:r.appBundleId},{...Mt(e,r),signal:n}))?.found===!0:null}function jt(e){return!ae(e.device.platform)||y(e.device)||!e.session?.appBundleId?null:{device:e.device,appBundleId:e.session.appBundleId,traceLogPath:e.session.trace?.outPath}}function Mt(e,t){return N({req:e.req,logPath:e.logPath,traceLogPath:t.traceLogPath})}async function Nt(e,t,n){return!!se((await Pt(e,n)).nodes,t)}async function Pt(e,t){let{snapshot:n}=await K({device:e.device,session:e.session,sessionStore:e.sessionStore,sessionName:e.sessionName,req:e.req,logPath:e.logPath,consumedSnapshot:e.consumedSnapshot}).capture({flags:{...e.req.flags,snapshotInteractiveOnly:!1,snapshotIncludeHiddenContentHints:!1},signal:t,cache:{forceFresh:!0,bypassForPostGestureStabilization:!0}});return n}async function Ft(e){let{req:t}=e;if(t.command!==`find`)return null;let n=m(t.positionals??[],t.flags);if(!n.ok)return b(n.code,n.message);let r=n.parsed,i=r.action;if(!te(i))return null;let a=await J(e,{requireSession:!1,capability:`find`});return a.ok?G(await Q(async()=>{let n=await a.runtime.selectors.find({session:e.sessionName,requestId:t.meta?.requestId,locator:r.locator,query:r.query,action:i,timeoutMs:r.timeoutMs});V(e.sessionStore,e.sessionName,t,Ye(n,i));let o=Xe(n),s=typeof o.ref==`string`?[o.ref]:Array.isArray(o.matches)?o.matches.map(e=>e.ref).filter(e=>typeof e==`string`):[];if(s.length>0){let t=e.sessionStore.get(e.sessionName);if(t&&(we(t,s),e.sessionStore.set(e.sessionName,t),t.snapshotGeneration!==void 0))return{...o,refsGeneration:t.snapshotGeneration}}return o}),Y(e)):a.response}function Y(e){return e.consumedSnapshot?.state??e.sessionStore.get(e.sessionName)?.snapshot}async function It(e){let{req:t}=e;if(t.command!==`get`)return null;let n=d(t.positionals?.[0]);if(!n.ok)return b(n.code,n.message);let r=n.format,i=Yt(t);if(!i.ok)return i.response;if(i.target.kind===`ref`){let e=O(`get`,t.flags);if(e)return e}let a=t.internal?.replayTargetGuard;if(i.target.kind===`selector`&&!a){let t=await Vt(e,r,i.target.selector);if(t)return t}let o=await J(e,{requireSession:!0,capability:`get`});if(!o.ok)return o.response;let s=i.target.kind===`ref`?D({session:e.sessionStore.get(e.sessionName),ref:i.target.ref,mintedGeneration:i.refGeneration}):void 0;return G(await Q(async()=>{let n=await o.runtime.selectors.get({session:e.sessionName,requestId:t.meta?.requestId,property:r,target:i.target,expectedResolvedTarget:a});V(e.sessionStore,e.sessionName,t,Ze(n,r),{node:n.node,preActionNodes:n.preActionNodes});let c=R(n);return s?{...c,warning:s}:c}),Y(e))}async function Lt(e){let{req:t}=e;if(t.command!==`is`)return null;let n=p(t.positionals??[]);if(!n.ok)return b(n.code,n.message,n.hint?{hint:n.hint}:void 0);let{predicate:r,expectedText:i}=n,a={selectorExpression:n.selectorExpression},o=t.internal?.replayTargetGuard,s=_(e.sessionStore.get(e.sessionName));if(!o&&!s){let t=await Ht(e,r,a.selectorExpression,i);if(t)return t}let c=await J(e,{requireSession:!0,capability:`is`});return c.ok?G(await $(e,await Q(async()=>{let n=await c.runtime.selectors.is({session:e.sessionName,requestId:t.meta?.requestId,predicate:r,selector:a.selectorExpression,expectedText:i,expectedResolvedTarget:o}),s=zt(n),l=z(n);return V(e.sessionStore,e.sessionName,t,l,s),B(l)}),`is ${r}`),Y(e)):c.response}async function Rt(e){let{req:t,sessionName:n,sessionStore:r}=e,i=f(t.positionals??[]);if(!i)return b(`INVALID_ARGS`,`wait requires a duration or text`);let{session:a,device:o}=await De(r,n,t.flags);if(i.kind!==`sleep`){let e=x(`wait`,o);if(e)return e}let s=t.internal?.replayLandmarkGuard;if(i.kind===`selector`&&!s&&!_(a)){let t=await Ut({...e,session:a,device:o,selectorExpression:i.selectorExpression,timeoutMs:i.timeoutMs});if(t)return t}let c=i,l;if(i.kind===`ref`){let e=A(i.rawRef);if(!e.ok)return e.response;c={...i,rawRef:e.ref},l=D({session:a,ref:e.ref,mintedGeneration:e.generation})}e.consumedSnapshot??={};let u=async()=>{let i=Et({...e,session:a,device:o}),u=await Q(async()=>{let e=await i.selectors.wait({session:n,requestId:t.meta?.requestId,target:Xt(c,a,s)}),o=zt(e);V(r,n,t,z(e),o,`landmark`);let u=Qe(e);return l?{...u,warning:l}:u});return await $(e,await U({req:t,logPath:e.logPath,session:a,device:o},u),`wait`)};return i.kind===`sleep`?await u():G(await Ee(a,o,u),Y(e))}function zt(e){let t=e.node,n=e.preActionNodes;if(!(!t||typeof t!=`object`||!Array.isArray(n)))return{node:t,preActionNodes:n}}function Bt(e,t,n){if(!e||_(e))return null;let r=F({session:e,selectorExpression:n});return t===`text`&&r?.key!==`id`?null:r}async function Vt(e,t,n){let r=e.sessionStore.get(e.sessionName),i=Bt(r,t,n);if(!r||!i)return null;let a=await X(e,r,i);if(Z(a))return a.response;if(!a)return null;let o=Kt(t,i.raw,a);return o?(V(e.sessionStore,e.sessionName,e.req,Ze(o,t)),{ok:!0,data:R(o)}):null}async function Ht(e,t,n,r){if(t===`hidden`)return null;let i=await Wt(e,n);if(Z(i))return i.response;if(!i?.result.found||!i.result.node)return null;let a=t===`exists`?{predicate:t,pass:!0,selector:i.selector.raw,matches:1,selectorChain:[i.selector.raw]}:qt(t,r,i.selector.raw,i.session,i.result.node);return a?(V(e.sessionStore,e.sessionName,e.req,a),{ok:!0,data:B(a)}):null}async function Ut(e){let t=F({session:e.session,selectorExpression:e.selectorExpression});if(!e.session||!t)return null;let n=Date.now(),r=await X(e,e.session,t);if(Z(r))return r.response;if(!r?.found)return null;let i={kind:`selector`,selector:t.raw,waitedMs:Date.now()-n,selectorChain:[t.raw]};V(e.sessionStore,e.sessionName,e.req,i);let a={ok:!0,data:B(i)};return await U({req:e.req,logPath:e.logPath,session:e.session,device:e.device},a)}async function Wt(e,t){let n=e.sessionStore.get(e.sessionName),r=F({session:n,selectorExpression:t});if(!n||!r)return null;let i=await X(e,n,r);return Z(i)?i:i?{session:n,selector:r,result:i}:null}async function Gt(e,t,n){let r=await S(e.device,{command:`querySelector`,selectorKey:t.key,selectorValue:t.value,appBundleId:e.appBundleId},n),i=r.found===!0,a=Jt(r);return{found:i,...typeof r.text==`string`?{text:r.text}:{},...a?{node:a}:{}}}async function X(t,n,r){try{return await Gt(n,r,N({req:t.req,logPath:t.logPath,traceLogPath:n.trace?.outPath}))}catch(t){return I(t,{allowElementNotFound:!0})?null:{kind:`error`,response:{ok:!1,error:e(t)}}}}function Z(e){return e!==null&&`kind`in e&&e.kind===`error`}function Kt(e,t,n){if(!n.found||!n.node)return null;let r={target:{kind:`selector`,selector:t},node:n.node,selectorChain:[t]};return e===`attrs`?{kind:`attrs`,...r}:typeof n.text==`string`?{kind:`text`,...r,text:n.text}:null}function qt(e,t,n,r,i){let a=ne({predicate:e,node:i,nodes:[i],expectedText:t,platform:r.device.platform});return{predicate:e,pass:a.pass,selector:n,...e===`text`?{text:a.actualText}:{},selectorChain:[n]}}function Jt(e){let t=e.nodes;if(!Array.isArray(t))return;let n=t[0];if(!(!n||typeof n!=`object`))return n}function Yt(e){let t=e.positionals?.[1]??``;if(t.startsWith(`@`)){let n=A(t);return n.ok?{ok:!0,target:{kind:`ref`,ref:n.ref,fallbackLabel:e.positionals.length>2?e.positionals.slice(2).join(` `).trim():``},refGeneration:n.generation}:{ok:!1,response:n.response}}let n=c(e.positionals?.slice(1)??[]);return n.ok?{ok:!0,target:{kind:`selector`,selector:`selector`in n?n.selector:``}}:{ok:!1,response:b(n.code,n.message)}}function Xt(e,n,r){if(e.kind===`sleep`)return{kind:`sleep`,durationMs:e.durationMs};if(e.kind===`selector`)return{kind:`selector`,selector:e.selectorExpression,timeoutMs:e.timeoutMs,...r?{recordedLandmark:r}:{}};if(e.kind===`ref`){if(!n?.snapshot)throw new t(`INVALID_ARGS`,`Ref wait requires an existing snapshot in session.`);return{kind:`ref`,ref:e.rawRef,timeoutMs:e.timeoutMs}}if(e.kind===`stable`)return{kind:`stable`,quietMs:e.quietMs,timeoutMs:e.timeoutMs};let i=s(e.text);if(!i.ok)throw new t(i.code,i.message);return{kind:`text`,text:i.text,timeoutMs:e.timeoutMs}}async function Q(e){try{return{ok:!0,data:await e()}}catch(e){let t=o(e);return b(t.code,t.message,t.details)}}async function $(e,t,n){if(t.ok)return t;let r=e.sessionStore.get(e.sessionName);if(!r)return t;let i;try{i=await L(r)}catch{return t}return i?b(t.error.code,`${n} failed because ${Ge(i)}.`,{...t.error.details??{},...i,blockedBy:`android_foreground_surface`,originalMessage:t.error.message}):t}export{Me as C,O as S,Fe as _,Gt as a,M as b,We as c,I as d,P as f,Le as g,Re as h,Rt as i,Ke as l,N as m,It as n,K as o,F as p,Lt as r,G as s,Ft as t,Ue as u,Pe as v,Ne as x,j as y};
+import{E as e,_ as t,h as n,l as r,m as i,s as a,v as o}from"./sdk-contracts.js";import{$n as s,Bt as c,Cr as l,Qn as u,Sn as d,Xn as f,Zn as p,Zt as m,bn as ee,nn as te,tr as ne}from"./sdk-batch-runner.js";import{_ as re,c as h,l as ie,s as ae}from"./sdk-device.js";import{Dt as oe,G as se,Ot as ce,m as g,ot as le}from"./script-source-bundle.js";import{t as ue}from"./interaction.js";import{N as de,Q as _}from"./screenshot-result.js";import{i as fe}from"./session-target-evidence.js";import{t as pe}from"./verdict.js";import{a as me,t as he}from"./runtime.js";import{A as ge}from"./sdk-android-adb.js";import{r as _e}from"./app-lifecycle.js";import{a as v}from"./snapshot.js";import{j as ve}from"./runner-disposal.js";import{o as y}from"./interactors.js";import{a as b,o as ye,p as be,s as x,t as xe}from"./dispatch.js";import{n as S}from"./runner-client.js";import{Mt as C,Ot as w,ft as Se,gt as T,ht as E,jt as Ce,mt as we,wt as D}from"./internal/daemon.js";import{a as Te,i as Ee,r as De}from"./snapshot-session.js";import{t as Oe}from"./device-ready.js";import{t as ke}from"./backend-snapshot-options.js";const Ae=[[`snapshotDepth`,`--depth`],[`snapshotScope`,`--scope`],[`snapshotRaw`,`--raw`]];function O(e,t){let n=je(t);return n.length===0?null:b(`INVALID_ARGS`,`${e} @ref does not support ${n.join(`, `)}.`)}function je(e){if(!e)return[];let t=[];for(let[n,r]of Ae)e[n]!==void 0&&t.push(r);return t}function Me(e,t){if(!t||t.settle===!0)return null;let n=[];return t.settleQuietMs!==void 0&&n.push(`--settle-quiet`),n.length===0?null:b(`INVALID_ARGS`,`${e}: ${n.join(`, `)} require${n.length===1?`s`:``} --settle.`)}function Ne(e){if(e?.settle===!0)return{...e.settleQuietMs===void 0?{}:{quietMs:e.settleQuietMs},...e.timeoutMs===void 0?{}:{timeoutMs:e.timeoutMs}}}function k(e){if(e.length<2)return null;let t=Number(e[0]),n=Number(e[1]);return!Number.isFinite(t)||!Number.isFinite(n)?null:{x:t,y:n}}function A(e){let t=n(e);return t?{ok:!0,ref:t.base,generation:t.generation}:{ok:!1,response:b(`INVALID_ARGS`,`Invalid ref "${e}" — malformed generation suffix.`,{hint:a})}}function j(e,t){let n=k(e);if(n)return{ok:!0,target:{kind:`point`,x:n.x,y:n.y}};let r=e[0]??``;if(r.startsWith(`@`)){let t=A(r);return t.ok?{ok:!0,target:{kind:`ref`,ref:t.ref,fallbackLabel:e.slice(1).join(` `).trim()},refGeneration:t.generation}:{ok:!1,response:t.response}}let i=e.join(` `).trim();return i?{ok:!0,target:{kind:`selector`,selector:i}}:{ok:!1,response:b(`INVALID_ARGS`,`${t} requires @ref, selector expression, or x y coordinates`)}}function Pe(e){let t=k(e);if(t)return{ok:!0,target:{kind:`point`,x:t.x,y:t.y},...Ve(e[2])};let n=Be(e),r=j(n.targetPositionals,`longpress`);return r.ok?{ok:!0,target:r.target,refGeneration:r.refGeneration,...n.duration}:r}function Fe(e){let t=e[0]??``;if(t.startsWith(`@`)){let n=A(t);if(!n.ok)return{ok:!1,response:n.response};let r=g(e).text;return r?{ok:!0,target:{kind:`ref`,ref:n.ref,fallbackLabel:ze(e)},refGeneration:n.generation,text:r}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after ref`)}}let n=k(e);if(n){let t=e.slice(2).join(` `);return t?{ok:!0,target:{kind:`point`,x:n.x,y:n.y},text:t}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after coordinates`)}}let r=Ie(e);return!r||r.kind!==`selector`?{ok:!1,response:b(`INVALID_ARGS`,`fill requires x y text, @ref text, or selector text`)}:r.text.trim()?{ok:!0,target:{kind:`selector`,selector:r.target.selector},text:r.text}:{ok:!1,response:b(`INVALID_ARGS`,`fill requires text after selector`)}}function Ie(e){try{return g(e)}catch{return null}}function Le(e){let t=`evidence`in e?e.evidence:void 0,n=e.settle;return e.kind===`ref`?{ref:M(e.target?.kind===`ref`?e.target.ref:void 0),refLabel:e.refLabel,selectorChain:e.selectorChain,targetHittable:e.targetHittable,hint:e.hint,evidence:t,settle:n,resolution:e.resolution}:e.kind===`selector`?{selector:e.target?.kind===`selector`?e.target.selector:void 0,selectorChain:e.selectorChain,refLabel:e.refLabel,targetHittable:e.targetHittable,hint:e.hint,evidence:t,settle:n,resolution:e.resolution}:{evidence:t,settle:n}}function Re(e,t){return e.kind===`point`?`coordinate tap`:t.kind===`ref`&&t.target?.kind===`ref`?t.target.ref:t.kind===`selector`&&t.target?.kind===`selector`?t.target.selector:`target`}function M(e){return e?.startsWith(`@`)?e.slice(1):e}function ze(e){return e.length>=3&&e[1]?.trim()||``}function Be(e){let t=e.at(-1);return e.length>1&&He(t)?{targetPositionals:e.slice(0,-1),duration:{durationMs:Number(t)}}:{targetPositionals:e,duration:{}}}function Ve(e){return e===void 0?{}:{durationMs:Number(e)}}function He(e){return e===void 0||e.trim()===``?!1:Number.isFinite(Number(e))}function N(e){let{req:t,logPath:n,traceLogPath:r}=e;return{verbose:t.flags?.verbose,logPath:n,traceLogPath:r,requestId:t.meta?.requestId,iosXctestrunFile:t.flags?.iosXctestrunFile,iosXctestDerivedDataPath:t.flags?.iosXctestDerivedDataPath,iosXctestEnvDir:t.flags?.iosXctestEnvDir}}function P(e,t){return!(!e||!h(e.device)||y(e.device)||t.skipPendingPostGestureStabilization&&w(e))}function F(e){let{session:t,selectorExpression:n}=e;return P(t,{skipPendingPostGestureStabilization:!0})?te(n):null}function Ue(e){let t=e.identifier?.trim();if(t)return{key:`id`,value:t};let n=e.label?.trim();return n?{key:`label`,value:n}:null}function I(e,t={}){let n=o(e);if(n.code===`ELEMENT_NOT_FOUND`)return t.delegateSemanticFailures===!0||t.allowElementNotFound===!0;if(n.code===`AMBIGUOUS_MATCH`)return t.delegateSemanticFailures===!0;if(n.code===`ELEMENT_OFFSCREEN`)return t.delegateSemanticFailures!==!1;if(n.code!==`COMMAND_FAILED`)return!1;let r=n.message.toLowerCase();return r.includes(`fetch failed`)||r.includes(`timed out`)||r.includes(`timeout`)||r.includes(`runner did not accept connection`)||r.includes(`invalid runner response`)}async function We(e,n){let r=await L(e);if(r){if(v(r.foregroundPackage))return`press ${n} opened an Android permission dialog (${r.foregroundPackage}) over ${r.expectedPackage}. ${r.hint}`;throw new t(`COMMAND_FAILED`,`press ${n} left ${e.appBundleId} and foregrounded ${r.foregroundPackage}. The tap likely escaped the app.`,r)}}async function L(e){if(e.device.platform!==`android`||!e.appBundleId)return null;let t=await _e(e.device),n=t.package?.trim();return!n||n===e.appBundleId||!Je(n)?null:{expectedPackage:e.appBundleId,foregroundPackage:n,activity:t.activity,hint:qe(n)}}function Ge(e){return v(e.foregroundPackage)?`Android permission dialog is blocking ${e.expectedPackage}`:`${e.foregroundPackage} is foreground instead of ${e.expectedPackage}`}function Ke(e){return e.code===`COMMAND_FAILED`&&typeof e.details?.expectedPackage==`string`&&typeof e.details?.foregroundPackage==`string`}function qe(e){return v(e)?`Use "alert get" to inspect it, then "alert accept" or "alert dismiss" to respond.`:`Use screenshot as visual truth, then take a fresh snapshot -i before retrying.`}function Je(e){return e===`com.android.settings`||e===`com.android.systemui`||v(e)||e.includes(`launcher`)}function Ye(e,t){if(t===`exists`)return{found:!0};if(t===`wait`)return{found:!0,waitedMs:e.waitedMs};if(t===`list`)return{action:`list`,matches:Array.isArray(e.matches)?e.matches.length:0};let n=typeof e.ref==`string`?e.ref:void 0;return t===`get_attrs`?{ref:n,action:`get attrs`}:{ref:n,action:`get text`,text:typeof e.text==`string`?e.text:``}}function Xe(e){return e.kind===`found`?{found:!0,...typeof e.waitedMs==`number`?{waitedMs:e.waitedMs}:{}}:e.kind===`list`?{matches:e.matches.map(e=>({ref:e.ref,node:c(e.node)}))}:{ref:e.ref,...e.kind===`text`?{text:e.text}:{},node:c(e.node)}}function Ze(e,t){let n=Array.isArray(e.selectorChain)?e.selectorChain:void 0,r=et(e),i=r?.kind===`ref`?H(r.ref):void 0,a=r?.kind===`selector`?r.selector:void 0,o={...i?{ref:i}:{},...a?{selector:a}:{},...n?{selectorChain:n}:{}};if(t===`attrs`)return o;let s=typeof e.text==`string`?e.text:``;return{...o,text:s,refLabel:$e(s)}}function R(e){let{target:t}=e;return{...t.kind===`ref`?{ref:H(t.ref)}:{},...t.kind===`selector`?{selector:t.selector}:{},...typeof e.text==`string`?{text:e.text}:{},node:c(e.node)}}function z(e){let{node:t,preActionNodes:n,...r}=e;return r}function Qe(e){return{waitedMs:e.waitedMs,...typeof e.text==`string`?{text:e.text}:{},...typeof e.selector==`string`?{selector:e.selector}:{},...typeof e.captures==`number`?{captures:e.captures}:{},...typeof e.nodeCount==`number`?{nodeCount:e.nodeCount}:{},...typeof e.hint==`string`?{hint:e.hint}:{}}}function B(e){let{selectorChain:t,...n}=e;return n}function V(e,t,n,r,i,a){let o=e.get(t);if(!o)return;let s=_(o)&&i?fe(i,{mode:a}):void 0;e.recordAction(o,{command:n.command,positionals:n.positionals??[],flags:n.flags??{},result:r,interactiveObservation:de(n),...s?{targetEvidence:s}:{}})}function $e(e){let t=e.trim();if(!(!t||t.length>80||/[\r\n]/.test(t)))return t}function et(e){let t=e.target;if(!t||typeof t!=`object`)return;let n=t;if(n.kind===`ref`&&typeof n.ref==`string`)return{kind:`ref`,ref:n.ref};if(n.kind===`selector`&&typeof n.selector==`string`)return{kind:`selector`,selector:n.selector}}function H(e){return e.startsWith(`@`)?e.slice(1):e}const tt=[`application`,`window`,`tabbar`,`scrollbar`,`image`],nt=new Set([`tab bar`]);async function U(e,t){if(t.ok||!rt(t.error.details?.reason)||t.error.details?.captureStalled===!0||t.error.details?.captureTruncated===!0)return t;let n=await it(e).catch(()=>null);return n?b(t.error.code,`${t.error.message}. Current surface: ${n.summary}.`,{...t.error.details??{},currentSurface:n.details}):t}function rt(e){return e===ue.targetAbsent||e===ue.stableTimeout}async function it(e){let t=[...(await D({device:e.device,session:e.session,flags:{...e.req.flags,snapshotInteractiveOnly:!0},logPath:e.logPath??``})).snapshot.nodes].sort(at),n=W(t,6,{includeIdentifiers:!0});if(n.length===0)return null;let r=W(t.filter(e=>!lt(e)),4,{includeIdentifiers:!1}),i=W(t.filter(ut),4,{includeIdentifiers:!0});return{summary:(r.length>0?r:n.slice(0,4)).join(`, `),details:{labels:n,...i.length>0?{buttons:i}:{}}}}function W(e,t,n){let r=new Set,i=[];for(let a of e){let e=ct(a,n);if(!(!e||r.has(e))&&(r.add(e),i.push(e),i.length>=t))break}return i}function at(e,t){return ot(e)-ot(t)||st(e,t)}function ot(e){let t=!!ct(e,{includeIdentifiers:!1});return(lt(e)?2:0)+ +!t}function st(e,t){return e.rect&&t.rect?e.rect.y-t.rect.y||e.rect.x-t.rect.x:e.rect?-1:t.rect?1:(e.depth??0)-(t.depth??0)||e.index-t.index}function ct(e,t){let n=(t.includeIdentifiers?[e.label,e.value,e.identifier]:[e.label,e.value]).map(e=>typeof e==`string`?e.trim():``).find(e=>e.length>0);return n?n.replace(/\s+/g,` `).slice(0,80):``}function lt(e){let t=l(`${e.type??``} ${e.role??``} ${e.subrole??``}`),n=`${e.label??``} ${e.value??``}`.trim().toLowerCase();return tt.some(e=>t.includes(e))||nt.has(n)||n.endsWith(`.fill`)}function ut(e){return l(`${e.type??``} ${e.role??``} ${e.subrole??``}`).includes(`button`)}function G(e,t){let n=me(t);if(!n)return e;if(e.ok){let t=dt(e.data?.warning,n);return{...e,data:{...e.data,warning:t}}}let r=e.error.details??{};return{...e,error:{...e.error,details:{...r,hint:dt(r.hint,n)}}}}function dt(e,t){return typeof e==`string`&&e.trim()!==``?`${e}\n${t}`:t}async function ft(e){let{device:t,node:n,flags:r,appBundleId:i,traceOutPath:a,surface:o,contextFromFlags:s}=e,c=oe(n),l=le(n.rect);if(!l||h(t)&&c&&!ce(n.type??``))return c;try{let e=await xe(t,`read`,[String(l.x),String(l.y)],void 0,{...s(r,i,a),surface:o}),u=e&&typeof e==`object`?e:void 0,d=typeof u?.text==`string`?u.text:``;return d.trim()?d:(ge({level:`warn`,phase:`interaction_read_fallback`,data:{reason:`empty_backend_text`,nodeRef:n.ref,surface:o,platform:t.platform}}),c)}catch(e){return ge({level:`warn`,phase:`interaction_read_fallback`,data:{reason:`backend_read_failed`,nodeRef:n.ref,surface:o,platform:t.platform,error:e instanceof Error?e.message:String(e)}}),c}}function K(e){let{session:t,sessionStore:n,sessionName:r}=e,i=0,a,o,s=t=>(e.consumedSnapshot&&(e.consumedSnapshot.state=t.snapshot),t);return{capture:async c=>{let l=Date.now(),u=St(c,e.req.flags?.out),d=gt({timestamp:l,lastSnapshotAt:i,lastSnapshotResult:a,lastSnapshotCacheKey:o,session:t,request:c,cacheKey:u});if(d)return s(d);let f=_t({session:t,timestamp:l,request:c});if(f)return i=f.createdAt,a={snapshot:f},o=u,s(a);let p=await pt({params:e,request:c});c.signal?.throwIfAborted();let m={snapshot:p};return wt({session:t,sessionStore:n,sessionName:r,snapshot:p}),i=l,a=m,o=u,s(m)}}}async function pt(e){let{params:t,request:n}=e,r=await q(t,n,n.snapshotScope);return n.recovery?.legacyIosSparse&&Tt(r)?await mt({runtimeParams:t,request:n,policy:n.recovery.legacyIosSparse}):n.recovery?.sparseVerdictQueryScope?.shouldScope&&pe(r.snapshotQuality)?await ht({runtimeParams:t,request:n,policy:n.recovery.sparseVerdictQueryScope,snapshot:r}):r}async function mt(e){let{runtimeParams:t,request:n,policy:r}=e;try{return await q(t,n,void 0,!1)}catch(e){if(!r.shouldScope)throw e;return await q(t,n,r.query,!1)}}async function ht(e){let{runtimeParams:t,request:n,policy:r,snapshot:i}=e;try{return await q(t,n,r.query,!1)}catch{return i}}async function q(e,t,n,r=t.flags?.snapshotInteractiveOnly){return(await D({device:e.device,session:e.session,flags:{...t.flags,snapshotInteractiveOnly:r},outPath:t.outPath??e.req.flags?.out,logPath:e.logPath??``,snapshotScope:n,includeRects:t.includeRects,signal:t.signal})).snapshot}function gt(e){let{timestamp:t,lastSnapshotAt:n,lastSnapshotResult:r,lastSnapshotCacheKey:i,session:a,request:o,cacheKey:s}=e;if(o.cache?.forceFresh!==!0&&r&&i===s&&!(t-n>=750)&&!C(a)&&!bt(a,o))return r}function _t(e){let{session:t,timestamp:n,request:r}=e,i=t?.snapshot;if(i&&vt(t,r)&&yt(i,n)&&i.presentationKey===xt(r))return i}function vt(e,t){return!(t.cache?.forceFresh===!0||t.cache?.useSessionSnapshot!==!0||C(e)||bt(e,t))}function yt(e,t){return t-e.createdAt<750}function bt(e,t){return t.cache?.bypassForPostGestureStabilization===!0&&w(e)}function xt(e){return r(i(Ct(e)))}function St(e,t){return JSON.stringify({presentationKey:xt(e),includeRects:e.includeRects===!0,outPath:e.outPath??t??null})}function Ct(e){return e.snapshotScope===void 0?e.flags:{...e.flags,snapshotScope:e.snapshotScope}}function wt(e){let{session:t,sessionStore:n,sessionName:r,snapshot:i}=e;!t||pe(i.snapshotQuality)||(T(t,i),n.set(r,t))}function Tt(e){return e.snapshotQuality||e.backend!==`xctest`||e.nodes.length!==1?!1:e.nodes[0]?.type===`Application`}function Et(e){return he({backend:Dt(e),...Te(`selector commands`,{plural:!0}),sessions:Se({sessionName:e.sessionName,getSession:()=>e.session,recordOptions:{includeSnapshot:!0},setRecord:t=>{!e.session||!t.snapshot||(T(e.session,t.snapshot),e.sessionStore.set(e.sessionName,e.session))}}),signal:e.signal??ve(e.req.meta?.requestId)})}async function J(e,t){e.consumedSnapshot??={};let n=e.sessionStore.get(e.sessionName);if(!n&&t.requireSession)return{ok:!1,response:ye()};let r=n?.device??await be(e.req.flags??{});n||await Oe(r);let i=x(t.capability,r);return i?{ok:!1,response:i}:{ok:!0,runtime:Et({...e,session:n,device:r})}}function Dt(e){let{req:t,session:n,device:r,logPath:i,sessionName:a,sessionStore:o}=e,s=K({device:r,session:n,sessionStore:o,sessionName:a,req:t,consumedSnapshot:e.consumedSnapshot,logPath:i});return{platform:re(r),captureSnapshot:async(e,n)=>{let i={...t.flags,...ke(n)},a=n?.includeRects===!0,o=n?.scope??t.flags?.snapshotScope,c=t.command===`wait`||t.command===`find`||a&&r.platform===`web`;return await s.capture({flags:i,signal:e.signal,snapshotScope:o,includeRects:a,cache:{forceFresh:c,useSessionSnapshot:!0,bypassForPostGestureStabilization:!0}})},readText:async(a,o)=>({text:await ft({device:r,node:o,flags:t.flags,appBundleId:n?.appBundleId,traceOutPath:n?.trace?.outPath,surface:n?.surface,contextFromFlags:e.contextFromFlags??((e,t,n)=>Ce(i??``,e,t,n))})}),findText:async(t,n)=>({found:await Ot(e,n,t.signal)})}}async function Ot(e,t,n){let r=await kt(e,t,n);return r===null?await At(e,t,n)===!0?!0:await Nt(e,t,n):r}async function kt(e,t,n){return!ie(e.device)||!e.session?.surface||e.session.surface===`app`?null:await Nt(e,t,n)}async function At(e,t,n){let r=jt(e);return r?(await S(r.device,{command:`findText`,text:t,appBundleId:r.appBundleId},{...Mt(e,r),signal:n}))?.found===!0:null}function jt(e){return!ae(e.device.platform)||y(e.device)||!e.session?.appBundleId?null:{device:e.device,appBundleId:e.session.appBundleId,traceLogPath:e.session.trace?.outPath}}function Mt(e,t){return N({req:e.req,logPath:e.logPath,traceLogPath:t.traceLogPath})}async function Nt(e,t,n){return!!se((await Pt(e,n)).nodes,t)}async function Pt(e,t){let{snapshot:n}=await K({device:e.device,session:e.session,sessionStore:e.sessionStore,sessionName:e.sessionName,req:e.req,logPath:e.logPath,consumedSnapshot:e.consumedSnapshot}).capture({flags:{...e.req.flags,snapshotInteractiveOnly:!1,snapshotIncludeHiddenContentHints:!1},signal:t,cache:{forceFresh:!0,bypassForPostGestureStabilization:!0}});return n}async function Ft(e){let{req:t}=e;if(t.command!==`find`)return null;let n=ee(t.positionals??[],t.flags);if(!n.ok)return b(n.code,n.message);let r=n.parsed,i=r.action;if(!d(i))return null;let a=await J(e,{requireSession:!1,capability:`find`});return a.ok?G(await Q(async()=>{let n=await a.runtime.selectors.find({session:e.sessionName,requestId:t.meta?.requestId,locator:r.locator,query:r.query,action:i,timeoutMs:r.timeoutMs});V(e.sessionStore,e.sessionName,t,Ye(n,i));let o=Xe(n),s=typeof o.ref==`string`?[o.ref]:Array.isArray(o.matches)?o.matches.map(e=>e.ref).filter(e=>typeof e==`string`):[];if(s.length>0){let t=e.sessionStore.get(e.sessionName);if(t&&(we(t,s),e.sessionStore.set(e.sessionName,t),t.snapshotGeneration!==void 0))return{...o,refsGeneration:t.snapshotGeneration}}return o}),Y(e)):a.response}function Y(e){return e.consumedSnapshot?.state??e.sessionStore.get(e.sessionName)?.snapshot}async function It(e){let{req:t}=e;if(t.command!==`get`)return null;let n=p(t.positionals?.[0]);if(!n.ok)return b(n.code,n.message);let r=n.format,i=Yt(t);if(!i.ok)return i.response;if(i.target.kind===`ref`){let e=O(`get`,t.flags);if(e)return e}let a=t.internal?.replayTargetGuard;if(i.target.kind===`selector`&&!a){let t=await Vt(e,r,i.target.selector);if(t)return t}let o=await J(e,{requireSession:!0,capability:`get`});if(!o.ok)return o.response;let s=i.target.kind===`ref`?E({session:e.sessionStore.get(e.sessionName),ref:i.target.ref,mintedGeneration:i.refGeneration}):void 0;return G(await Q(async()=>{let n=await o.runtime.selectors.get({session:e.sessionName,requestId:t.meta?.requestId,property:r,target:i.target,expectedResolvedTarget:a});V(e.sessionStore,e.sessionName,t,Ze(n,r),{node:n.node,preActionNodes:n.preActionNodes});let c=R(n);return s?{...c,warning:s}:c}),Y(e))}async function Lt(e){let{req:t}=e;if(t.command!==`is`)return null;let n=u(t.positionals??[]);if(!n.ok)return b(n.code,n.message,n.hint?{hint:n.hint}:void 0);let{predicate:r,expectedText:i}=n,a={selectorExpression:n.selectorExpression},o=t.internal?.replayTargetGuard,s=_(e.sessionStore.get(e.sessionName));if(!o&&!s){let t=await Ht(e,r,a.selectorExpression,i);if(t)return t}let c=await J(e,{requireSession:!0,capability:`is`});return c.ok?G(await $(e,await Q(async()=>{let n=await c.runtime.selectors.is({session:e.sessionName,requestId:t.meta?.requestId,predicate:r,selector:a.selectorExpression,expectedText:i,expectedResolvedTarget:o}),s=zt(n),l=z(n);return V(e.sessionStore,e.sessionName,t,l,s),B(l)}),`is ${r}`),Y(e)):c.response}async function Rt(e){let{req:t,sessionName:n,sessionStore:r}=e,i=m(t.positionals??[]);if(!i)return b(`INVALID_ARGS`,`wait requires a duration or text`);if(i.kind===`invalid`)return b(`INVALID_ARGS`,i.message);let{session:a,device:o}=await De(r,n,t.flags);if(i.kind!==`sleep`){let e=x(`wait`,o);if(e)return e}let s=t.internal?.replayLandmarkGuard;if(i.kind===`selector`&&!s&&!_(a)){let t=await Ut({...e,session:a,device:o,selectorExpression:i.selectorExpression,timeoutMs:i.timeoutMs});if(t)return t}let c=i,l;if(i.kind===`ref`){let e=A(i.rawRef);if(!e.ok)return e.response;c={...i,rawRef:e.ref},l=E({session:a,ref:e.ref,mintedGeneration:e.generation})}e.consumedSnapshot??={};let u=async()=>{let i=Et({...e,session:a,device:o}),u=await Q(async()=>{let e=await i.selectors.wait({session:n,requestId:t.meta?.requestId,target:Xt(c,a,s)}),o=zt(e);V(r,n,t,z(e),o,`landmark`);let u=Qe(e);return l?{...u,warning:l}:u});return await $(e,await U({req:t,logPath:e.logPath,session:a,device:o},u),`wait`)};return i.kind===`sleep`?await u():G(await Ee(a,o,u),Y(e))}function zt(e){let t=e.node,n=e.preActionNodes;if(!(!t||typeof t!=`object`||!Array.isArray(n)))return{node:t,preActionNodes:n}}function Bt(e,t,n){if(!e||_(e))return null;let r=F({session:e,selectorExpression:n});return t===`text`&&r?.key!==`id`?null:r}async function Vt(e,t,n){let r=e.sessionStore.get(e.sessionName),i=Bt(r,t,n);if(!r||!i)return null;let a=await X(e,r,i);if(Z(a))return a.response;if(!a)return null;let o=Kt(t,i.raw,a);return o?(V(e.sessionStore,e.sessionName,e.req,Ze(o,t)),{ok:!0,data:R(o)}):null}async function Ht(e,t,n,r){if(t===`hidden`)return null;let i=await Wt(e,n);if(Z(i))return i.response;if(!i?.result.found||!i.result.node)return null;let a=t===`exists`?{predicate:t,pass:!0,selector:i.selector.raw,matches:1,selectorChain:[i.selector.raw]}:qt(t,r,i.selector.raw,i.session,i.result.node);return a?(V(e.sessionStore,e.sessionName,e.req,a),{ok:!0,data:B(a)}):null}async function Ut(e){let t=F({session:e.session,selectorExpression:e.selectorExpression});if(!e.session||!t)return null;let n=Date.now(),r=await X(e,e.session,t);if(Z(r))return r.response;if(!r?.found)return null;let i={kind:`selector`,selector:t.raw,waitedMs:Date.now()-n,selectorChain:[t.raw]};V(e.sessionStore,e.sessionName,e.req,i);let a={ok:!0,data:B(i)};return await U({req:e.req,logPath:e.logPath,session:e.session,device:e.device},a)}async function Wt(e,t){let n=e.sessionStore.get(e.sessionName),r=F({session:n,selectorExpression:t});if(!n||!r)return null;let i=await X(e,n,r);return Z(i)?i:i?{session:n,selector:r,result:i}:null}async function Gt(e,t,n){let r=await S(e.device,{command:`querySelector`,selectorKey:t.key,selectorValue:t.value,appBundleId:e.appBundleId},n),i=r.found===!0,a=Jt(r);return{found:i,...typeof r.text==`string`?{text:r.text}:{},...a?{node:a}:{}}}async function X(t,n,r){try{return await Gt(n,r,N({req:t.req,logPath:t.logPath,traceLogPath:n.trace?.outPath}))}catch(t){return I(t,{allowElementNotFound:!0})?null:{kind:`error`,response:{ok:!1,error:e(t)}}}}function Z(e){return e!==null&&`kind`in e&&e.kind===`error`}function Kt(e,t,n){if(!n.found||!n.node)return null;let r={target:{kind:`selector`,selector:t},node:n.node,selectorChain:[t]};return e===`attrs`?{kind:`attrs`,...r}:typeof n.text==`string`?{kind:`text`,...r,text:n.text}:null}function qt(e,t,n,r,i){let a=ne({predicate:e,node:i,nodes:[i],expectedText:t,platform:r.device.platform});return{predicate:e,pass:a.pass,selector:n,...e===`text`?{text:a.actualText}:{},selectorChain:[n]}}function Jt(e){let t=e.nodes;if(!Array.isArray(t))return;let n=t[0];if(!(!n||typeof n!=`object`))return n}function Yt(e){let t=e.positionals?.[1]??``;if(t.startsWith(`@`)){let n=A(t);return n.ok?{ok:!0,target:{kind:`ref`,ref:n.ref,fallbackLabel:e.positionals.length>2?e.positionals.slice(2).join(` `).trim():``},refGeneration:n.generation}:{ok:!1,response:n.response}}let n=f(e.positionals?.slice(1)??[]);return n.ok?{ok:!0,target:{kind:`selector`,selector:`selector`in n?n.selector:``}}:{ok:!1,response:b(n.code,n.message)}}function Xt(e,n,r){if(e.kind===`sleep`)return{kind:`sleep`,durationMs:e.durationMs};if(e.kind===`selector`)return{kind:`selector`,selector:e.selectorExpression,timeoutMs:e.timeoutMs,...r?{recordedLandmark:r}:{}};if(e.kind===`ref`){if(!n?.snapshot)throw new t(`INVALID_ARGS`,`Ref wait requires an existing snapshot in session.`);return{kind:`ref`,ref:e.rawRef,timeoutMs:e.timeoutMs}}if(e.kind===`stable`)return{kind:`stable`,quietMs:e.quietMs,timeoutMs:e.timeoutMs};let i=s(e.text);if(!i.ok)throw new t(i.code,i.message);return{kind:`text`,text:i.text,timeoutMs:e.timeoutMs}}async function Q(e){try{return{ok:!0,data:await e()}}catch(e){let t=o(e);return b(t.code,t.message,t.details)}}async function $(e,t,n){if(t.ok)return t;let r=e.sessionStore.get(e.sessionName);if(!r)return t;let i;try{i=await L(r)}catch{return t}return i?b(t.error.code,`${n} failed because ${Ge(i)}.`,{...t.error.details??{},...i,blockedBy:`android_foreground_surface`,originalMessage:t.error.message}):t}export{Me as C,O as S,Fe as _,Gt as a,M as b,We as c,I as d,P as f,Le as g,Re as h,Rt as i,Ke as l,N as m,It as n,K as o,F as p,Lt as r,G as s,Ft as t,Ue as u,Pe as v,Ne as x,j as y};

package/dist/src/selectors.js

@@ -1 +1 @@
-import{$n as e,Qn as t,in as n,nr as r,rr as i,sn as a,tr as o}from"./sdk-batch-runner.js";import{t as s}from"./sdk-selectors.js";export{n as findSelectorChainMatch,s as formatSelectorFailure,r as isNodeEditable,i as isNodeVisible,t as isSelectorToken,e as parseSelectorChain,a as resolveSelectorChain,o as tryParseSelectorChain};
+import{dr as e,fn as t,hn as n,lr as r,or as i,sr as a,ur as o}from"./sdk-batch-runner.js";import{t as s}from"./sdk-selectors.js";export{t as findSelectorChainMatch,s as formatSelectorFailure,o as isNodeEditable,e as isNodeVisible,i as isSelectorToken,a as parseSelectorChain,n as resolveSelectorChain,r as tryParseSelectorChain};