touchpress 0.1.2 → 0.1.3

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 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";
 //#region src/core/evidence.d.ts
 /**
  * Never throws. A capture that fails records a note and returns, because masking

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-BHYloK0j.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 { 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 { ExpectMatcherState } from "@playwright/test";
 //#region src/ai/options.d.ts
 /**

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-BHYloK0j.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-CWeJYtS7.mjs → preflight-BHYloK0j.mjs}

@@ -58,6 +58,17 @@ 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 "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 +122,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 +612,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,6 +738,7 @@ 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}`;
@@ -1297,10 +1360,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 +1453,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",
@@ -1681,6 +1780,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/dist/{preflight-Czhj9QFM.d.mts → preflight-DJH10uBo.d.mts}

@@ -291,6 +291,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;
@@ -434,6 +442,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;
@@ -833,6 +846,10 @@ type ErrorInfo = {
   readonly attempts: number;
   readonly timeoutMs: number;
   readonly screen: string;
+} | {
+  readonly kind: 'untappable';
+  readonly locator: string;
+  readonly screen: string;
 } | {
   readonly kind: 'driver';
   readonly command: string;

package/package.json

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