touchpress 0.1.3 → 0.2.1

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-DJH10uBo.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-BHYloK0j.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-D1aux7ic.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-DJH10uBo.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-BHYloK0j.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-D1aux7ic.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-DJH10uBo.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;
@@ -342,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>;
@@ -456,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';
 } | {
@@ -635,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 = {
@@ -649,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. */
@@ -704,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;
@@ -712,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. */
@@ -850,6 +932,10 @@ type ErrorInfo = {
   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;
@@ -899,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-BHYloK0j.mjs → preflight-D1aux7ic.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";
@@ -49,11 +51,11 @@ function formatError(info) {
 			info.screen
 		].join("\n");
 		case "fill-unconfirmed": return [
-			`fill left the field holding something else after ${String(info.attempts)} attempts in ${String(info.timeoutMs)}ms.`,
+			info.actual === null ? `fill lost the field after ${String(info.attempts)} attempts in ${String(info.timeoutMs)}ms.` : `fill left the field holding something else after ${String(info.attempts)} attempts in ${String(info.timeoutMs)}ms.`,
 			``,
 			`Locator: ${info.locator}`,
 			`Expected value: ${describeValue(info.expected)}${info.expected.kind === "masked" ? " (a secure field reports a mask, not its contents)" : ""}`,
-			`Actual value: ${info.actual === null ? "the locator stopped resolving" : describeValue(info.actual)}`,
+			`Actual value: ${info.actual === null ? "unknown, the field no longer resolved after the write" : describeValue(info.actual)}`,
 			``,
 			`Screen:`,
 			info.screen
@@ -69,6 +71,13 @@ function formatError(info) {
 			`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");
@@ -742,6 +751,9 @@ function renderTitle(record) {
 		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)}"`;
@@ -868,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) {
@@ -902,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 () => {
@@ -921,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,
@@ -1232,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(),
@@ -1339,6 +1388,7 @@ function perform(session, sink, record, options, dispatch, write) {
 			let retriedStaleRef = false;
 			let attempts = 0;
 			let target = record.query;
+			let written = null;
 			let lastActual = null;
 			let screen = await device.capture();
 			const unconfirmed = (expected) => new TouchpressError({
@@ -1377,6 +1427,7 @@ function perform(session, sink, record, options, dispatch, write) {
 						typed: typedOf(resolution.node.role, write)
 					}), () => Promise.resolve(), { box: true });
 					target = identityOf(screen, resolution.node);
+					written = confirmation;
 					screen = await device.capture();
 					lastActual = valueAt(screen, target);
 					if (lastActual !== null && holds(confirmation, lastActual)) {
@@ -1393,13 +1444,16 @@ function perform(session, sink, record, options, dispatch, write) {
 					continue;
 				}
 				const remaining = deadline - Date.now();
-				if (remaining <= 0) throw new TouchpressError({
-					kind: "not-found",
-					locator,
-					timeoutMs: timeout,
-					screen: renderScreen(screen),
-					scrolled: search.trail()
-				});
+				if (remaining <= 0) {
+					if (written !== null) throw unconfirmed(expectedOf(written));
+					throw new TouchpressError({
+						kind: "not-found",
+						locator,
+						timeoutMs: timeout,
+						screen: renderScreen(screen),
+						scrolled: search.trail()
+					});
+				}
 				if (attempts === 0 && await search.step(screen, target, remaining)) {
 					screen = await device.capture();
 					continue;
@@ -1542,6 +1596,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 {
@@ -1571,18 +1635,29 @@ function valueAt(screen, target) {
 /**
 * How the written node is found again on the next snapshot.
 *
-* The driver copies an ancestor's identifier onto every descendant that
-* inherits it, so a testId names this node alone only when it resolves to this
-* node alone. Two inheriting siblings would otherwise turn a landed fill into a
-* strict-mode failure. Position in the tree is the fallback.
+* A testId rarely names one node. SwiftUI puts one identifier on a field, its
+* placeholder, and the button under it, and the driver copies an ancestor's
+* identifier onto every inheriting descendant. The role narrows those to the
+* field, and failing that the field's position among nodes of its role stands
+* in. Never the raw tree index: the software keyboard inserts its windows at the
+* top of the tree, which shifts every index but adds no text field.
 */
 function identityOf(screen, node) {
 	if (node.testId !== null) {
-		const byTestId = { testId: textMatch(node.testId, true) };
+		const byTestId = {
+			role: node.role,
+			testId: textMatch(node.testId, true)
+		};
 		const resolution = resolve(screen, byTestId);
 		if (resolution.outcome === "one" && resolution.node === node) return byTestId;
 	}
-	return { where: (other) => other.index === node.index };
+	const byRole = { role: node.role };
+	const index = matchesOf(screen, byRole).indexOf(node);
+	if (index === -1) throw new Error(`${node.ref} does not resolve under its own role`);
+	return {
+		...byRole,
+		index
+	};
 }
 //#endregion
 //#region src/core/evidence.ts
@@ -1621,18 +1696,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();
@@ -1659,12 +1739,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({
@@ -1694,6 +1776,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,
@@ -1734,6 +1866,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.

package/package.json

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