touchpress 0.1.2 → 0.2.0

package/dist/core/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as Tree, A as deviceNameForSlot, B as ProbeResult, C as openSession, D as ResolvedOptions, E as ReadyQuery, F as StepOptions, G as CaptureOptions, H as formatFailure, I as Typed, J as DeviceInfo, K as DeviceDriver, L as renderTitle, M as ActionRecord, N as ActionSink, O as TOUCHPRESS_DEFAULTS, P as EvidenceFile, Q as Settled, R as silentSink, S as SessionState, T as DeviceChoice, U as probe, V as ProbeTarget, W as Binding, X as OpenRequest, Y as DeviceSelection, Z as ScrollDirection, _ as RoleOptions, _t as Screen, a as ExpectedValue, at as Filter, b as DeviceSession, bt as renderScreen, c as ScrollSearch, ct as TextMatch, d as directionToward, dt as textMatch, et as Check, f as ActionOptions, ft as PinnedRef, g as Locator, gt as Resolution, h as FilterOptions, ht as Rect, i as ErrorInfo, it as evaluate, j as parseDeviceOptions, k as TouchpressOptions, l as ScrollTrail, lt as describeQuery, m as FillOptions, mt as RawSnapshot, n as PreflightReport, nt as Verdict, o as TouchpressError, ot as Query, p as Device, pt as Platform, q as DeviceFailure, r as preflight, rt as describeCheck, s as ScrollDevice, st as Role, t as PreflightDevice, tt as CheckName, u as createScrollSearch, ut as normalizeText, v as TextOptions, vt as ScreenNode, w as sessionName, x as OpenSessionInput, xt as resolve, y as createDevice, yt as parseScreen, z as ProbeOptions } from "../preflight-Czhj9QFM.mjs";
+import { $ as DeviceSelection, A as ResolvedOptions, B as renderTitle, C as DeviceSession, Ct as parseScreen, D as sessionName, E as openSession, F as ActionRecord, G as formatFailure, H as ProbeOptions, I as ActionSink, J as Binding, K as probe, L as EvidenceFile, M as TouchpressOptions, N as deviceNameForSlot, O as DeviceChoice, P as parseDeviceOptions, Q as DeviceInfo, R as StepOptions, S as createDevice, St as ScreenNode, T as SessionState, Tt as resolve, U as ProbeResult, V as silentSink, W as ProbeTarget, X as DeviceDriver, Y as CaptureOptions, Z as DeviceFailure, _ as Keyboard, _t as Platform, a as ExpectedValue, at as CheckName, b as TextOptions, bt as Resolution, c as ScrollSearch, ct as evaluate, d as directionToward, dt as Role, et as OpenRequest, f as ActionOptions, ft as TextMatch, g as FilterOptions, gt as PinnedRef, h as FillOptions, ht as textMatch, i as ErrorInfo, it as Check, j as TOUCHPRESS_DEFAULTS, k as ReadyQuery, l as ScrollTrail, lt as Filter, m as Device, mt as normalizeText, n as PreflightReport, nt as Settled, o as TouchpressError, ot as Verdict, p as BackOptions, pt as describeQuery, q as BackMode, r as preflight, rt as Tree, s as ScrollDevice, st as describeCheck, t as PreflightDevice, tt as ScrollDirection, u as createScrollSearch, ut as Query, v as Locator, vt as RawSnapshot, w as OpenSessionInput, wt as renderScreen, x as TypeOptions, xt as Screen, y as RoleOptions, yt as Rect, z as Typed } from "../preflight-CqFFdaAv.mjs";
 //#region src/core/evidence.d.ts
 /**
  * Never throws. A capture that fails records a note and returns, because masking
@@ -70,4 +70,4 @@ declare function toPixelBox(rect: {
 /** Moves a box into the coordinates of a crop taken at `origin`. */
 declare function relativeTo(box: PixelBox, origin: PixelBox): PixelBox;
 //#endregion
-export { type ActionOptions, type ActionRecord, type ActionSink, type Binding, type CaptureOptions, type Check, type CheckName, type CompareOptions, type Comparison, type Device, type DeviceChoice, type DeviceDriver, type DeviceFailure, type DeviceInfo, type DeviceSelection, type DeviceSession, type ErrorInfo, type EvidenceFile, type ExpectedValue, type FillOptions, type Filter, type FilterOptions, type Locator, type OpenRequest, type OpenSessionInput, type PinnedRef, type PixelBox, type Platform, type PreflightDevice, type PreflightReport, type ProbeOptions, type ProbeResult, type ProbeTarget, type Query, type RawSnapshot, type ReadyQuery, type Rect, type Resolution, type ResolvedOptions, type Role, type RoleOptions, type Screen, type ScreenNode, type ScrollDevice, type ScrollDirection, type ScrollSearch, type ScrollTrail, type SessionState, type Settled, type Size, type StepOptions, TOUCHPRESS_DEFAULTS, type TextMatch, type TextOptions, TouchpressError, type TouchpressOptions, type Tree, type Typed, type Verdict, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };
+export { type ActionOptions, type ActionRecord, type ActionSink, type BackMode, type BackOptions, type Binding, type CaptureOptions, type Check, type CheckName, type CompareOptions, type Comparison, type Device, type DeviceChoice, type DeviceDriver, type DeviceFailure, type DeviceInfo, type DeviceSelection, type DeviceSession, type ErrorInfo, type EvidenceFile, type ExpectedValue, type FillOptions, type Filter, type FilterOptions, type Keyboard, type Locator, type OpenRequest, type OpenSessionInput, type PinnedRef, type PixelBox, type Platform, type PreflightDevice, type PreflightReport, type ProbeOptions, type ProbeResult, type ProbeTarget, type Query, type RawSnapshot, type ReadyQuery, type Rect, type Resolution, type ResolvedOptions, type Role, type RoleOptions, type Screen, type ScreenNode, type ScrollDevice, type ScrollDirection, type ScrollSearch, type ScrollTrail, type SessionState, type Settled, type Size, type StepOptions, TOUCHPRESS_DEFAULTS, type TextMatch, type TextOptions, TouchpressError, type TouchpressOptions, type Tree, type TypeOptions, type Typed, type Verdict, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };

package/dist/core/index.mjs

@@ -1,2 +1,2 @@
-import { A as normalizeText, C as parseScreen, D as deviceNameForSlot, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, a as sizeOf, d as createScrollSearch, f as directionToward, g as evaluate, h as describeCheck, i as relativeTo, j as textMatch, k as describeQuery, l as captureEvidence, m as probe, n as compareScreenshot, o as toPixelBox, p as formatFailure, r as cropScreenshot, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle, y as sessionName } from "../preflight-CWeJYtS7.mjs";
+import { A as normalizeText, C as parseScreen, D as deviceNameForSlot, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, a as sizeOf, d as createScrollSearch, f as directionToward, g as evaluate, h as describeCheck, i as relativeTo, j as textMatch, k as describeQuery, l as captureEvidence, m as probe, n as compareScreenshot, o as toPixelBox, p as formatFailure, r as cropScreenshot, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle, y as sessionName } from "../preflight-sFz236o3.mjs";
 export { TOUCHPRESS_DEFAULTS, TouchpressError, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { E as ReadyQuery, _t as Screen, a as ExpectedValue, at as Filter, b as DeviceSession, ct as TextMatch, g as Locator, h as FilterOptions, ht as Rect, i as ErrorInfo, k as TouchpressOptions$1, n as PreflightReport, o as TouchpressError, ot as Query, p as Device$1, pt as Platform, r as preflight, st as Role, t as PreflightDevice, vt as ScreenNode } from "./preflight-Czhj9QFM.mjs";
+import { C as DeviceSession, M as TouchpressOptions$1, St as ScreenNode, _ as Keyboard, _t as Platform, a as ExpectedValue, dt as Role, ft as TextMatch, g as FilterOptions, i as ErrorInfo, k as ReadyQuery, lt as Filter, m as Device$1, n as PreflightReport, o as TouchpressError, p as BackOptions, r as preflight, t as PreflightDevice, ut as Query, v as Locator, x as TypeOptions, xt as Screen, yt as Rect } from "./preflight-CqFFdaAv.mjs";
 import { ExpectMatcherState } from "@playwright/test";
 //#region src/ai/options.d.ts
 /**
@@ -143,4 +143,4 @@ declare const expect: import("@playwright/test").Expect<{
 type TouchpressOptions = TouchpressOptions$1 & AiOptions;
 type Device = Device$1 & AiDevice;
 //#endregion
-export { type ActOptions, type AiDevice, type AiModel, type AiOptions, Device, type ErrorInfo, type ExpectedValue, type ExtractOptions, type ExtractSchema, type Filter, type FilterOptions, type Locator, type Platform, type PreflightDevice, type PreflightReport, type Query, type ReadyQuery, type Rect, type Role, type Screen, type ScreenNode, type ScreenshotOptions, type TextMatch, TouchpressError, TouchpressOptions, expect, preflight, setupTest, test };
+export { type ActOptions, type AiDevice, type AiModel, type AiOptions, type BackOptions, Device, type ErrorInfo, type ExpectedValue, type ExtractOptions, type ExtractSchema, type Filter, type FilterOptions, type Keyboard, type Locator, type Platform, type PreflightDevice, type PreflightReport, type Query, type ReadyQuery, type Rect, type Role, type Screen, type ScreenNode, type ScreenshotOptions, type TextMatch, TouchpressError, TouchpressOptions, type TypeOptions, expect, preflight, setupTest, test };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { C as parseScreen, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, _ as createQueue, a as sizeOf, b as sleep, c as createClient, i as relativeTo, j as textMatch, l as captureEvidence, n as compareScreenshot, o as toPixelBox, r as cropScreenshot, s as createAgentDeviceDriver, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle } from "./preflight-CWeJYtS7.mjs";
+import { C as parseScreen, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, _ as createQueue, a as sizeOf, b as sleep, c as createClient, i as relativeTo, j as textMatch, l as captureEvidence, n as compareScreenshot, o as toPixelBox, r as cropScreenshot, s as createAgentDeviceDriver, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle } from "./preflight-sFz236o3.mjs";
 import { expect as expect$1, test as test$1 } from "@playwright/test";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";

package/dist/{preflight-Czhj9QFM.d.mts → preflight-CqFFdaAv.d.mts}

@@ -233,6 +233,11 @@ declare function describeCheck(check: Check): string;
 //#endregion
 //#region src/core/driver.d.ts
 type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+/**
+ * `in-app` is the navigation control the app draws. `system` is the platform
+ * gesture or key, which iOS does not have.
+ */
+type BackMode = 'in-app' | 'system';
 /**
  * A session binds on its first command, so this rides on `open` and on every
  * command after it. A call sent without selection lands on whichever device the
@@ -262,6 +267,8 @@ type Binding = {
   readonly deviceLabel: string;
   readonly appId: string;
   readonly stateDir: string | null;
+  /** What lets a driver reach the device with a tool of its own. Null when the open response named none. */
+  readonly udid: string | null;
 };
 type Settled = {
   readonly settled: boolean;
@@ -291,6 +298,14 @@ type DeviceFailure = {
 } | {
   readonly kind: 'ambiguous';
   readonly detail: string;
+} |
+/**
+ * The pinned node owns no touch point outside the interactive nodes drawn
+ * over it, so the driver refused rather than guess which one was meant.
+ */
+{
+  readonly kind: 'covered';
+  readonly detail: string;
 } | {
   readonly kind: 'timeout';
   readonly detail: string;
@@ -334,6 +349,24 @@ type DeviceDriver = {
   tap(ref: PinnedRef, options: SettleOptions): Promise<Settled>;
   longPress(ref: PinnedRef, durationMs: number, options: SettleOptions): Promise<Settled>;
   fill(ref: PinnedRef, text: string, options: SettleOptions): Promise<Settled>;
+  /** Takes no target, because the platform decides what goes back. */
+  back(mode: BackMode, options: SettleOptions): Promise<Settled>;
+  /**
+   * Types into whatever holds focus. The one mutation with no `PinnedRef`,
+   * because a field the app focused for itself may carry nothing to select on.
+   */
+  type(text: string, options: SettleOptions): Promise<Settled>;
+  /**
+   * Discards the app's stored state. Whether that reaches every store the app
+   * writes to is the driver's problem, not the core's.
+   */
+  clearAppState(app: string): Promise<void>;
+  /**
+   * Resets the device's keychain, which on an iOS simulator is shared by every
+   * app on it. Kept apart from `clearAppState` for that reason. A no-op on a
+   * platform whose app data clear already covers the app's secure store.
+   */
+  resetKeychain(): Promise<void>;
   /** Returns nothing because the driver's scroll response carries no settle observation. */
   scroll(direction: ScrollDirection, options: SettleOptions): Promise<void>;
   dismissDevOverlay(): Promise<void>;
@@ -434,6 +467,11 @@ type ActionRecord = {
 } | {
   readonly kind: 'typed';
   readonly typed: Typed;
+} |
+/** Where an action landed after the driver refused the node the locator matched. */
+{
+  readonly kind: 'retarget';
+  readonly target: string;
 } | {
   readonly kind: 'scroll';
   readonly direction: ScrollDirection;
@@ -443,6 +481,14 @@ type ActionRecord = {
 } | {
   readonly kind: 'relaunch';
   readonly app: string;
+} | {
+  readonly kind: 'back';
+  readonly mode: BackMode;
+} | {
+  readonly kind: 'clear-state';
+  readonly app: string;
+} | {
+  readonly kind: 'clear-keychain';
 } | {
   readonly kind: 'dismiss-overlay';
 } | {
@@ -622,6 +668,10 @@ type SessionDevice = {
   tap(ref: PinnedRef, budgetMs: number): Promise<Settled>;
   longPress(ref: PinnedRef, durationMs: number, budgetMs: number): Promise<Settled>;
   fill(ref: PinnedRef, text: string, budgetMs: number): Promise<Settled>;
+  back(mode: BackMode, budgetMs: number): Promise<Settled>;
+  type(text: string, budgetMs: number): Promise<Settled>;
+  clearAppState(app: string): Promise<void>;
+  resetKeychain(): Promise<void>;
   scroll(direction: ScrollDirection, budgetMs: number): Promise<void>;
 };
 type DeviceSession = {
@@ -636,6 +686,18 @@ type DeviceSession = {
   screenshot(path: string): Promise<string>;
   /** Relaunches the app and re-runs the ready gate. Reported as one step. */
   relaunch(sink: ActionSink): Promise<void>;
+  /**
+   * Discards the app's stored state, then relaunches and re-runs the ready
+   * gate, because an app holding a cleared session in memory has not been
+   * cleared. Reported as one step with the relaunch nested under it.
+   */
+  clearState(sink: ActionSink): Promise<void>;
+  /**
+   * Resets the simulator's keychain, which every app on it shares. Separate
+   * from `clearState` so an app-scoped clear never wipes another app's store.
+   * Reported as one step, with a note on Android where there is nothing to reset.
+   */
+  clearKeychain(sink: ActionSink): Promise<void>;
   dismissDevOverlay(): Promise<void>;
   awaitReady(deadline: number): Promise<void>;
   /** Idempotent. Never shuts the simulator down, and reaches `closed` even when the driver call fails. */
@@ -691,6 +753,25 @@ type FilterOptions = {
 type FillOptions = ActionOptions & {
   secret?: boolean;
 };
+type BackOptions = ActionOptions & {
+  mode?: BackMode;
+};
+/** `secret` reports a character count instead of the text, the way `fill`'s does. */
+type TypeOptions = ActionOptions & {
+  secret?: boolean;
+};
+/**
+ * Playwright's `page.keyboard`, cut down to what a device keyboard can do with
+ * no target. Everything else touchpress offers needs a locator.
+ */
+type Keyboard = {
+  /**
+   * Types into whatever holds focus, for a field with nothing to select on,
+   * such as a one-time-code input the app focused for itself. Nothing is read
+   * back, because there is no target to read.
+   */
+  type(text: string, options?: TypeOptions): Promise<void>;
+};
 type Device = {
   /** Matches a node's accessibility name or its value. */
   getByText(text: string | RegExp, options?: TextOptions): Locator;
@@ -699,6 +780,20 @@ type Device = {
   getByTestId(testId: string): Locator;
   locator(query: Query): Locator;
   scroll(direction: ScrollDirection): Promise<void>;
+  /**
+   * Goes back. Defaults to the platform gesture on Android and to the app's own
+   * navigation control on iOS, which has no system back to press.
+   */
+  goBack(options?: BackOptions): Promise<void>;
+  readonly keyboard: Keyboard;
+  /** Discards the app's stored state, then relaunches and waits for the ready gate again. */
+  clearState(): Promise<void>;
+  /**
+   * Resets the simulator's keychain, which is shared by every app on it, so
+   * it is not part of `clearState`. A no-op on Android, where clearing state
+   * already removes the app's keystore entries.
+   */
+  clearKeychain(): Promise<void>;
   /** Relaunches the app and waits for the ready gate again. */
   relaunch(): Promise<void>;
   /** Never automatic, because hiding the overlay would suppress a warning a test might want to see. */
@@ -833,6 +928,14 @@ type ErrorInfo = {
   readonly attempts: number;
   readonly timeoutMs: number;
   readonly screen: string;
+} | {
+  readonly kind: 'untappable';
+  readonly locator: string;
+  readonly screen: string;
+} |
+/** Carries no field, because the rejected text is the one thing this error may not hold. */
+{
+  readonly kind: 'type-rejected';
 } | {
   readonly kind: 'driver';
   readonly command: string;
@@ -882,4 +985,4 @@ type PreflightReport = {
  */
 declare function preflight(options: Partial<TouchpressOptions>, driver?: DeviceDriver): Promise<PreflightReport>;
 //#endregion
-export { Tree as $, deviceNameForSlot as A, ProbeResult as B, openSession as C, ResolvedOptions as D, ReadyQuery as E, StepOptions as F, CaptureOptions as G, formatFailure as H, Typed as I, DeviceInfo as J, DeviceDriver as K, renderTitle as L, ActionRecord as M, ActionSink as N, TOUCHPRESS_DEFAULTS as O, EvidenceFile as P, Settled as Q, silentSink as R, SessionState as S, DeviceChoice as T, probe as U, ProbeTarget as V, Binding as W, OpenRequest as X, DeviceSelection as Y, ScrollDirection as Z, RoleOptions as _, Screen as _t, ExpectedValue as a, Filter as at, DeviceSession as b, renderScreen as bt, ScrollSearch as c, TextMatch as ct, directionToward as d, textMatch as dt, Check as et, ActionOptions as f, PinnedRef as ft, Locator as g, Resolution as gt, FilterOptions as h, Rect as ht, ErrorInfo as i, evaluate as it, parseDeviceOptions as j, TouchpressOptions as k, ScrollTrail as l, describeQuery as lt, FillOptions as m, RawSnapshot as mt, PreflightReport as n, Verdict as nt, TouchpressError as o, Query as ot, Device as p, Platform as pt, DeviceFailure as q, preflight as r, describeCheck as rt, ScrollDevice as s, Role as st, PreflightDevice as t, CheckName as tt, createScrollSearch as u, normalizeText as ut, TextOptions as v, ScreenNode as vt, sessionName as w, OpenSessionInput as x, resolve as xt, createDevice as y, parseScreen as yt, ProbeOptions as z };
+export { DeviceSelection as $, ResolvedOptions as A, renderTitle as B, DeviceSession as C, parseScreen as Ct, sessionName as D, openSession as E, ActionRecord as F, formatFailure as G, ProbeOptions as H, ActionSink as I, Binding as J, probe as K, EvidenceFile as L, TouchpressOptions as M, deviceNameForSlot as N, DeviceChoice as O, parseDeviceOptions as P, DeviceInfo as Q, StepOptions as R, createDevice as S, ScreenNode as St, SessionState as T, resolve as Tt, ProbeResult as U, silentSink as V, ProbeTarget as W, DeviceDriver as X, CaptureOptions as Y, DeviceFailure as Z, Keyboard as _, Platform as _t, ExpectedValue as a, CheckName as at, TextOptions as b, Resolution as bt, ScrollSearch as c, evaluate as ct, directionToward as d, Role as dt, OpenRequest as et, ActionOptions as f, TextMatch as ft, FilterOptions as g, PinnedRef as gt, FillOptions as h, textMatch as ht, ErrorInfo as i, Check as it, TOUCHPRESS_DEFAULTS as j, ReadyQuery as k, ScrollTrail as l, Filter as lt, Device as m, normalizeText as mt, PreflightReport as n, Settled as nt, TouchpressError as o, Verdict as ot, BackOptions as p, describeQuery as pt, BackMode as q, preflight as r, Tree as rt, ScrollDevice as s, describeCheck as st, PreflightDevice as t, ScrollDirection as tt, createScrollSearch as u, Query as ut, Locator as v, RawSnapshot as vt, OpenSessionInput as w, renderScreen as wt, TypeOptions as x, Screen as xt, RoleOptions as y, Rect as yt, Typed as z };

package/dist/{preflight-CWeJYtS7.mjs → preflight-sFz236o3.mjs}

@@ -1,3 +1,5 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { createAgentDeviceClient, normalizeAgentDeviceError } from "agent-device";
 import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
@@ -58,6 +60,24 @@ function formatError(info) {
 			`Screen:`,
 			info.screen
 		].join("\n");
+		case "untappable": return [
+			`The matched node has no touch point of its own, and no enclosing control was found.`,
+			``,
+			`Locator: ${info.locator}`,
+			``,
+			`Name the control that receives the touch, with getByRole, or with`,
+			`locator({ role: 'button', where: (node) => ... }).`,
+			``,
+			`Screen:`,
+			info.screen
+		].join("\n");
+		case "type-rejected": return [
+			"The driver cannot type text whose first word looks like a node reference.",
+			"It reads a leading @ followed by a name with a digit in it, or by ref, node,",
+			"element or el, as a ref to resolve rather than as characters to send.",
+			"",
+			"Type it through the field instead, with fill on a locator for that field."
+		].join("\n");
 		case "driver": return `${info.command} failed: ${describeFailure(info.failure)}`;
 		case "ai-not-configured": return ["device.act and device.extract need a model.", "Set use.aiModel to a gateway model id, such as 'anthropic/claude-sonnet-5', or to a provider model instance."].join("\n");
 		case "ai-missing-peer": return ["device.act and device.extract need the optional peer dependency 'ai'.", "Install it with: pnpm add -D ai"].join("\n");
@@ -111,6 +131,7 @@ function describeFailure(failure) {
 		case "session-rebound": return `the session is already bound to ${failure.boundTo} (${failure.detail})`;
 		case "stale-ref": return `the screen changed before the action reached it (${failure.detail})`;
 		case "ambiguous": return `the driver matched more than one element (${failure.detail})`;
+		case "covered": return `the node owns no touch point of its own (${failure.detail})`;
 		case "timeout": return `the driver timed out (${failure.detail})`;
 		case "unknown": return `${failure.code}: ${failure.detail}${failure.logPath === null ? "" : `\nDiagnostics: ${failure.logPath}`}`;
 		default: throw new Error(`unhandled failure ${JSON.stringify(failure)}`);
@@ -600,6 +621,56 @@ function matchedText(node, query) {
 function absorbAncestors(matched, query) {
 	return matched.filter((candidate) => !matched.some((other) => other !== candidate && isDescendant(other, candidate) && matchedText(other, query) === matchedText(candidate, query)));
 }
+/** `tab-bar` is left out because it is a container of buttons rather than a control that takes the touch. */
+const INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+	"button",
+	"link",
+	"switch",
+	"slider",
+	"text-field",
+	"secure-text-field",
+	"cell"
+]);
+/**
+* The control a tap on `node` would really land on, or null when the screen
+* offers none.
+*
+* A React Native pressable puts the accessible name on one node and the touch
+* handler on another. On Android the two are siblings, so a locator that
+* matched the label pins a ref that owns no touch point of its own. The button
+* drawn under the label is the thing a finger hits, and its rect is what says
+* so.
+*
+* A descendant wins over an enclosing node, because a control inside the
+* matched node is what that node was labelling. Among several, the smallest
+* wins, so a row of buttons inside one card does not hand back the card.
+*/
+function touchTargetFor(screen, node) {
+	const candidates = [];
+	for (const other of screen.nodes) {
+		if (other === node || !other.enabled || !INTERACTIVE_ROLES.has(other.role)) continue;
+		if (other.rect !== null) candidates.push({
+			node: other,
+			rect: other.rect
+		});
+	}
+	const inside = smallest(candidates.filter((candidate) => isDescendant(candidate.node, node)));
+	if (inside !== null) return inside;
+	const own = node.rect;
+	if (own === null) return null;
+	return smallest(candidates.filter((candidate) => encloses(candidate.rect, own)));
+}
+function encloses(outer, inner) {
+	return outer.x <= inner.x && outer.y <= inner.y && outer.x + outer.width >= inner.x + inner.width && outer.y + outer.height >= inner.y + inner.height;
+}
+function smallest(candidates) {
+	let best = null;
+	for (const candidate of candidates) if (best === null || areaOf(candidate.rect) < areaOf(best.rect)) best = candidate;
+	return best === null ? null : best.node;
+}
+function areaOf(rect) {
+	return rect.width * rect.height;
+}
 function isDescendant(node, ancestor) {
 	for (let walk = node.parent; walk !== null; walk = walk.parent) if (walk === ancestor) return true;
 	return false;
@@ -676,9 +747,13 @@ function renderTitle(record) {
 		case "long-press": return `longPress ${describeQuery(record.query)} for ${String(record.durationMs)}ms`;
 		case "fill": return `fill ${describeQuery(record.query)}`;
 		case "typed": return renderTyped(record.typed);
+		case "retarget": return `retarget to ${record.target}`;
 		case "scroll": return `scroll ${record.direction}`;
 		case "scroll-into-view": return `scrollIntoView ${describeQuery(record.query)}`;
 		case "relaunch": return `relaunch ${record.app}`;
+		case "back": return `back (${record.mode})`;
+		case "clear-state": return `clear state of ${record.app}`;
+		case "clear-keychain": return "clear keychain";
 		case "dismiss-overlay": return "dismiss the React Native dev overlay";
 		case "screenshot": return `screenshot ${record.path}`;
 		case "act": return `act "${truncate(record.instruction, PROMPT_LIMIT)}"`;
@@ -805,6 +880,10 @@ function createSession(driver, options, name, binding) {
 		tap: (ref, budgetMs) => driver.tap(ref, settle(budgetMs)),
 		longPress: (ref, durationMs, budgetMs) => driver.longPress(ref, durationMs, settle(budgetMs)),
 		fill: (ref, text, budgetMs) => driver.fill(ref, text, settle(budgetMs)),
+		back: (mode, budgetMs) => driver.back(mode, settle(budgetMs)),
+		type: (text, budgetMs) => driver.type(text, settle(budgetMs)),
+		clearAppState: (app) => driver.clearAppState(app),
+		resetKeychain: () => driver.resetKeychain(),
 		scroll: (direction, budgetMs) => driver.scroll(direction, settle(budgetMs))
 	};
 	function run(body) {
@@ -839,15 +918,8 @@ function createSession(driver, options, name, binding) {
 			screen: renderScreen(screen)
 		});
 	}
-	return {
-		name,
-		options,
-		state: () => state,
-		failure: () => state.phase === "broken" ? state.failure : null,
-		run,
-		screen: () => run((one) => one.capture()),
-		screenshot: (path) => queue.enqueue(() => driver.screenshot(path)),
-		relaunch: (sink) => sink.step(renderTitle({
+	function relaunch(sink) {
+		return sink.step(renderTitle({
 			kind: "relaunch",
 			app: options.app
 		}), async () => {
@@ -858,6 +930,27 @@ function createSession(driver, options, name, binding) {
 			}));
 			if (options.dismissDevOverlay) await run(() => driver.dismissDevOverlay());
 			await awaitReady(Date.now() + options.launchTimeout);
+		});
+	}
+	return {
+		name,
+		options,
+		state: () => state,
+		failure: () => state.phase === "broken" ? state.failure : null,
+		run,
+		screen: () => run((one) => one.capture()),
+		screenshot: (path) => queue.enqueue(() => driver.screenshot(path)),
+		relaunch,
+		clearState: (sink) => sink.step(renderTitle({
+			kind: "clear-state",
+			app: options.app
+		}), async () => {
+			await run((one) => one.clearAppState(options.app));
+			await relaunch(sink);
+		}),
+		clearKeychain: (sink) => sink.step(renderTitle({ kind: "clear-keychain" }), async () => {
+			if (options.platform === "android") sink.note("keychain", "nothing to reset on Android, clearing state covers the keystore");
+			await run((one) => one.resetKeychain());
 		}),
 		dismissDevOverlay: () => run(() => driver.dismissDevOverlay()),
 		awaitReady,
@@ -1169,6 +1262,25 @@ function createDevice(session, sink) {
 		}), async () => {
 			await session.run((device) => device.scroll(direction, session.options.actionTimeout));
 		}),
+		goBack: (options) => {
+			const mode = options?.mode ?? (session.options.platform === "android" ? "system" : "in-app");
+			return sink.step(renderTitle({
+				kind: "back",
+				mode
+			}), async () => {
+				const budget = options?.timeout ?? session.options.actionTimeout;
+				await session.run((device) => device.back(mode, budget));
+			});
+		},
+		keyboard: { type: (text, options) => sink.step(renderTitle({
+			kind: "typed",
+			typed: typedText(text, options)
+		}), async () => {
+			const budget = options?.timeout ?? session.options.actionTimeout;
+			await session.run((device) => device.type(text, budget));
+		}) },
+		clearState: () => session.clearState(sink),
+		clearKeychain: () => session.clearKeychain(sink),
 		relaunch: () => session.relaunch(sink),
 		dismissDevOverlay: () => sink.step(renderTitle({ kind: "dismiss-overlay" }), () => session.dismissDevOverlay()),
 		screen: () => session.screen(),
@@ -1297,10 +1409,14 @@ function perform(session, sink, record, options, dispatch, write) {
 					try {
 						settled = await dispatch(device, pin(screen, resolution.node), deadline - Date.now());
 					} catch (error) {
-						if (failureOf(error)?.kind !== "stale-ref" || retriedStaleRef) throw error;
-						retriedStaleRef = true;
-						screen = await device.capture();
-						continue;
+						const failure = failureOf(error);
+						if (failure?.kind === "stale-ref" && !retriedStaleRef) {
+							retriedStaleRef = true;
+							screen = await device.capture();
+							continue;
+						}
+						if (failure?.kind !== "covered" || record.kind === "fill") throw error;
+						settled = await retarget(device, sink, dispatch, locator, screen, resolution.node, deadline - Date.now());
 					}
 					attempts += 1;
 					if (!settled.settled) sink.note("settle", `${renderTitle(record)} finished before the screen went quiet`);
@@ -1386,6 +1502,38 @@ function reportingScrolls(device, sink) {
 		}), () => device.scroll(direction, budgetMs))
 	};
 }
+/**
+* A React Native pressable splits the accessible name off the touch handler, so
+* a locator naming what a user reads can pin a node the driver refuses. The
+* control covering that node is what the finger would have hit, so the action
+* goes there and the report names it, rather than asking the author to describe
+* a node they cannot see.
+*
+* One hop only. A second refusal means the retarget was the wrong reading of
+* the screen, and repeating it would only walk further from what was asked for.
+*/
+async function retarget(device, sink, dispatch, locator, screen, matched, budgetMs) {
+	const target = touchTargetFor(screen, matched);
+	if (target === null) throw untappable(locator, screen);
+	return await sink.step(renderTitle({
+		kind: "retarget",
+		target: describeNode(target)
+	}), async () => {
+		try {
+			return await dispatch(device, pin(screen, target), budgetMs);
+		} catch (error) {
+			if (failureOf(error)?.kind !== "covered") throw error;
+			throw untappable(locator, screen);
+		}
+	}, { box: true });
+}
+function untappable(locator, screen) {
+	return new TouchpressError({
+		kind: "untappable",
+		locator,
+		screen: renderScreen(screen)
+	});
+}
 function ambiguous(locator, nodes, screen) {
 	return new TouchpressError({
 		kind: "strict-mode",
@@ -1443,6 +1591,16 @@ function expectedOf(confirmation) {
 		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
 	}
 }
+/** A blind type has no node to ask about secrecy, so only the caller can say. */
+function typedText(text, options) {
+	return options?.secret === true ? {
+		kind: "hidden",
+		length: text.length
+	} : {
+		kind: "text",
+		value: text
+	};
+}
 /** What the report says was typed, verbatim, which the normalized confirmation no longer holds. */
 function typedOf(role, write) {
 	if (role === "secure-text-field" || write.secret) return {
@@ -1522,18 +1680,23 @@ function messageOf(error) {
 function createClient() {
 	return createAgentDeviceClient({ responseLevel: "full" });
 }
+const execFileAsync = promisify(execFile);
+const spawnCommand = async (file, args) => {
+	await execFileAsync(file, [...args]);
+};
 /**
 * The only file that imports `agent-device`. Two jobs: translate domain requests
 * into client calls carrying the session and device selection, and translate the
 * driver's error codes into `DeviceFailure`. Snapshot parsing is not one of
 * them, because role normalization and label rules live in `core/screen.ts`.
 */
-function createAgentDeviceDriver(client, session, selection) {
+function createAgentDeviceDriver(client, session, selection, runCommand = spawnCommand) {
 	const where = {
 		session,
 		platform: selection.platform,
 		...selection.name === null ? {} : { device: selection.name }
 	};
+	let udid = null;
 	async function run(command, body) {
 		try {
 			return await body();
@@ -1560,12 +1723,14 @@ function createAgentDeviceDriver(client, session, selection) {
 				relaunch: request.relaunch,
 				...request.url === null ? {} : { url: request.url }
 			});
+			udid = result.identifiers.udid ?? result.identifiers.deviceId ?? null;
 			return {
 				session: result.session,
 				platform: selection.platform,
 				deviceLabel: result.device?.name ?? result.identifiers.deviceName ?? selection.name ?? selection.platform,
 				appId: result.appBundleId ?? result.appId ?? request.app,
-				stateDir: result.sessionStateDir ?? null
+				stateDir: result.sessionStateDir ?? null,
+				udid
 			};
 		}),
 		capture: (options) => run("snapshot", () => client.capture.snapshot({
@@ -1595,6 +1760,56 @@ function createAgentDeviceDriver(client, session, selection) {
 			text,
 			...settle(options)
 		}))),
+		back: (mode, options) => run("back", async () => toSettled(await client.command.back({
+			...where,
+			mode,
+			...settle(options)
+		}))),
+		/**
+		* Scrubbed rather than run through `run`, because agent-device echoes the
+		* text it rejected and a password has no business in a report.
+		*/
+		type: async (text, _options) => {
+			if (looksLikeRef(text)) throw new TouchpressError({ kind: "type-rejected" });
+			try {
+				await client.interactions.type({
+					...where,
+					text
+				});
+				return {
+					settled: false,
+					waitedMs: 0
+				};
+			} catch (error) {
+				throw new TouchpressError({
+					kind: "driver",
+					command: "type",
+					failure: withoutText(classifyError(error), text)
+				});
+			}
+		},
+		clearAppState: (app) => run("clearAppState", async () => {
+			await client.settings.update({
+				...where,
+				setting: "clear-app-state",
+				state: "clear",
+				app
+			});
+		}),
+		/**
+		* agent-device has no keychain command, and the simulator keychain is where
+		* clerk-ios and expo-secure-store keep a session. Lives in the driver
+		* because it needs the udid and a process, neither of which the core has.
+		*/
+		resetKeychain: () => run("resetKeychain", async () => {
+			if (selection.platform !== "ios") return;
+			await runCommand("xcrun", [
+				"simctl",
+				"keychain",
+				udid ?? "booted",
+				"reset"
+			]);
+		}),
 		scroll: (direction, options) => run("scroll", async () => {
 			await client.interactions.scroll({
 				...where,
@@ -1635,6 +1850,25 @@ function readNormalized(error) {
 	return normalizeAgentDeviceError(error);
 }
 /**
+* agent-device 0.20.10's own check, copied rather than approximated so the two
+* agree on what it will refuse. `@e12` and `@ref-x` are refs, while `@word` and
+* `@ home` are text.
+*/
+function looksLikeRef(text) {
+	const word = text.trim().split(/\s+/, 1)[0];
+	if (word === void 0 || !word.startsWith("@") || word.length < 3) return false;
+	const rest = word.slice(1);
+	return /^[A-Za-z_-]*\d[\w-]*$/i.test(rest) || /^(?:ref|node|element|el)[\w-]*$/i.test(rest);
+}
+/** Every failure kind carries a `detail`, and the driver puts what it was given into it. */
+function withoutText(failure, text) {
+	if (text === "") return failure;
+	return {
+		...failure,
+		detail: failure.detail.split(text).join("<typed text>")
+	};
+}
+/**
 * Timeouts and transport faults both arrive as `COMMAND_FAILED`, so the message
 * and `details.reason` separate them. That matches against upstream text, and it
 * is confined to this function for exactly that reason.
@@ -1681,6 +1915,10 @@ function classifyError(error) {
 				kind: "stale-ref",
 				detail: message
 			};
+			if (details["reason"] === "covered_by_interactive_descendants") return {
+				kind: "covered",
+				detail: message
+			};
 			if (/timed out|timeout/i.test(message)) return {
 				kind: "timeout",
 				detail: message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "touchpress",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "End-to-end testing for mobile apps.",
   "homepage": "https://github.com/wobsoriano/touchpress#readme",
   "bugs": {