touchpress 0.0.1

package/dist/preflight-C83jCNPs.mjs

@@ -0,0 +1,1865 @@
+import { createAgentDeviceClient, normalizeAgentDeviceError } from "agent-device";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+//#region src/core/errors.ts
+var TangereError = class extends Error {
+	info;
+	constructor(info) {
+		super(formatError(info));
+		this.name = "TangereError";
+		this.info = info;
+	}
+};
+function formatError(info) {
+	switch (info.kind) {
+		case "config": return `Invalid tangere option: use.${info.field} ${info.detail}`;
+		case "device-in-use": return [
+			`Device ${info.device} is held by ${info.owner === null ? "another session" : `session "${info.owner}"`}.`,
+			`Release it with: ${info.releaseCommand}`,
+			...info.canReclaim ? ["Or set use.onDeviceInUse to 'reclaim'."] : []
+		].join("\n");
+		case "launch-failed": return `Could not open ${info.app} on ${info.device}: ${describeFailure(info.failure)}`;
+		case "not-ready": return [
+			`App launched but never became ready.`,
+			`Waited ${String(info.timeoutMs)}ms for readyWhen: ${info.locator}`,
+			``,
+			`Screen:`,
+			info.screen
+		].join("\n");
+		case "session-closed": return `Cannot ${info.command}: the device session is closed.`;
+		case "strict-mode": return [
+			`Locator resolved to ${String(info.matches.length)} nodes but an action needs exactly one.`,
+			``,
+			`Locator: ${info.locator}`,
+			`Matches:`,
+			...info.matches.map((match) => `  ${match}`),
+			``,
+			`Narrow it with getByRole, or take one deliberately with .first() or .nth(n).`,
+			``,
+			`Screen:`,
+			info.screen
+		].join("\n");
+		case "not-found": return [
+			`Locator never resolved to a node within ${String(info.timeoutMs)}ms.`,
+			``,
+			`Locator: ${info.locator}`,
+			...info.scrolled === null ? [] : [`Scrolled: ${describeTrail(info.scrolled)}`],
+			``,
+			`Screen:`,
+			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.`,
+			``,
+			`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)}`,
+			``,
+			`Screen:`,
+			info.screen
+		].join("\n");
+		case "driver": return `${info.command} failed: ${describeFailure(info.failure)}`;
+		default: throw new Error(`unhandled error info ${JSON.stringify(info)}`);
+	}
+}
+function describeTrail(trail) {
+	return `${String(trail.steps)} step${trail.steps === 1 ? "" : "s"} ${trail.direction}`;
+}
+/** A masked value is reported by its length alone, which is all a secure or secret field may disclose. */
+function describeValue(value) {
+	switch (value.kind) {
+		case "exact": return `"${value.value}"`;
+		case "masked": return `${String(value.length)} characters`;
+		default: throw new Error(`unhandled expected value ${JSON.stringify(value)}`);
+	}
+}
+function describeFailure(failure) {
+	switch (failure.kind) {
+		case "device-busy": return `device is in use${failure.owner === null ? "" : ` by session "${failure.owner}"`} (${failure.detail})`;
+		case "device-missing": return `no matching device is booted (${failure.detail})`;
+		case "app-missing": return `the app is not installed on this device (${failure.detail})`;
+		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 "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)}`);
+	}
+}
+//#endregion
+//#region src/core/query.ts
+/** Applied to both sides of every string comparison, so a label wrapped across lines still matches one typed on one line. */
+function normalizeText(raw) {
+	return raw.replace(/\s+/g, " ").trim();
+}
+/**
+* Playwright's default text semantics: case-insensitive substring after
+* whitespace normalization. `exact` is whole-string and case-sensitive, still
+* normalized.
+*/
+function textMatch(value, exact) {
+	if (value instanceof RegExp) return {
+		kind: "regex",
+		value
+	};
+	return exact === true ? {
+		kind: "exact",
+		value: normalizeText(value)
+	} : {
+		kind: "substring",
+		value: normalizeText(value)
+	};
+}
+function matchesText(match, candidate) {
+	if (candidate === null) return false;
+	switch (match.kind) {
+		case "exact": return candidate === match.value;
+		case "substring": return candidate.toLowerCase().includes(match.value.toLowerCase());
+		case "regex": return match.value.test(candidate);
+		default: throw new Error(`unhandled text match ${JSON.stringify(match)}`);
+	}
+}
+/**
+* Renders a query back into the factory call that produces it, so the `Locator:`
+* line of a failure reads like the line the author wrote.
+*/
+function describeQuery(query) {
+	const suffix = `${describeFilters(query.filters)}${describeIndex(query.index)}`;
+	const fields = describeExtraFields(query);
+	const plain = fields.length === 0 && query.value === void 0;
+	if (plain && query.testId !== void 0 && query.name === void 0 && query.role === void 0) return `getByTestId(${describeMatch(query.testId)})${suffix}`;
+	if (plain && query.role !== void 0 && query.testId === void 0) {
+		const name = query.name === void 0 ? "" : `, { name: ${describeMatch(query.name)}${describeExact(query.name)} }`;
+		return `getByRole('${query.role}'${name})${suffix}`;
+	}
+	if (plain && query.name !== void 0 && query.testId === void 0 && query.role === void 0) {
+		const exact = query.name.kind === "exact" ? ", { exact: true }" : "";
+		return `getByText(${describeMatch(query.name)}${exact})${suffix}`;
+	}
+	return `locator({ ${[
+		query.testId === void 0 ? null : `testId: ${describeMatch(query.testId)}`,
+		query.name === void 0 ? null : `name: ${describeMatch(query.name)}`,
+		query.value === void 0 ? null : `value: ${describeMatch(query.value)}`,
+		query.role === void 0 ? null : `role: '${query.role}'`,
+		...fields
+	].filter((part) => part !== null).join(", ")} })${suffix}`;
+}
+function describeExtraFields(query) {
+	return [
+		query.enabled === void 0 ? null : `enabled: ${String(query.enabled)}`,
+		query.selected === void 0 ? null : `selected: ${String(query.selected)}`,
+		query.focused === void 0 ? null : `focused: ${String(query.focused)}`,
+		query.where === void 0 ? null : "where: <predicate>"
+	].filter((part) => part !== null);
+}
+function describeFilters(filters) {
+	if (filters === void 0) return "";
+	return filters.map((filter) => describeFilter(filter)).join("");
+}
+function describeFilter(filter) {
+	const fields = [
+		filter.hasText === void 0 ? null : `hasText: ${describeMatch(filter.hasText)}`,
+		filter.hasNotText === void 0 ? null : `hasNotText: ${describeMatch(filter.hasNotText)}`,
+		filter.has === void 0 ? null : `has: ${describeQuery(filter.has)}`,
+		filter.hasNot === void 0 ? null : `hasNot: ${describeQuery(filter.hasNot)}`
+	].filter((part) => part !== null);
+	return fields.length === 0 ? ".filter({})" : `.filter({ ${fields.join(", ")} })`;
+}
+function describeExact(match) {
+	return match.kind === "exact" ? ", exact: true" : "";
+}
+/** A match rendered back into the literal an author would have typed. */
+function describeMatch(match) {
+	return match.kind === "regex" ? String(match.value) : `'${match.value}'`;
+}
+function describeIndex(index) {
+	if (index === void 0) return "";
+	return index === 0 ? ".first()" : `.nth(${String(index)})`;
+}
+//#endregion
+//#region src/core/config.ts
+/**
+* The option fixtures declare these as their defaults and the parser falls back
+* to the same values, so a caller that reaches the parser without the fixtures,
+* such as `preflight`, resolves identically.
+*/
+const TANGERE_DEFAULTS = {
+	relaunch: "per-test",
+	onDeviceInUse: "fail",
+	settleQuietMs: 500,
+	launchTimeout: 9e4,
+	dismissDevOverlay: false,
+	evidence: "on-failure",
+	sessionPrefix: "tangere"
+};
+const DEFAULT_ACTION_TIMEOUT_MS = 1e4;
+const ROLES = [
+	"application",
+	"window",
+	"button",
+	"text",
+	"text-field",
+	"secure-text-field",
+	"link",
+	"image",
+	"switch",
+	"slider",
+	"tab-bar",
+	"scroll-area",
+	"cell",
+	"alert",
+	"other"
+];
+/**
+* The config boundary. Options arrive as `unknown` because a project can omit
+* any of them, or be written in JavaScript, and because `actionTimeout` rides
+* along from Playwright's own options. Every message names the key to fix.
+*/
+function parseDeviceOptions(raw) {
+	const platform = read(raw, "platform");
+	if (platform !== "ios" && platform !== "android") throw fail("platform", "must be 'ios' or 'android'.");
+	const app = read(raw, "app");
+	if (typeof app !== "string" || app.length === 0) throw fail("app", "must be the bundle id or package name of the app under test.");
+	return {
+		platform,
+		app,
+		readyWhen: parseReadyWhen(read(raw, "readyWhen")),
+		device: parseDeviceChoice(read(raw, "deviceName")),
+		launchUrl: optionalText("launchUrl", read(raw, "launchUrl")),
+		relaunch: oneOf("relaunch", read(raw, "relaunch"), ["per-test", "per-worker"], TANGERE_DEFAULTS.relaunch),
+		onDeviceInUse: oneOf("onDeviceInUse", read(raw, "onDeviceInUse"), ["fail", "reclaim"], TANGERE_DEFAULTS.onDeviceInUse),
+		actionTimeout: parseActionTimeout(read(raw, "actionTimeout")),
+		settleQuietMs: positive("settleQuietMs", read(raw, "settleQuietMs"), TANGERE_DEFAULTS.settleQuietMs),
+		launchTimeout: positive("launchTimeout", read(raw, "launchTimeout"), TANGERE_DEFAULTS.launchTimeout),
+		dismissDevOverlay: flag("dismissDevOverlay", read(raw, "dismissDevOverlay"), TANGERE_DEFAULTS.dismissDevOverlay),
+		evidence: oneOf("evidence", read(raw, "evidence"), [
+			"on-failure",
+			"always",
+			"off"
+		], TANGERE_DEFAULTS.evidence),
+		sessionPrefix: text("sessionPrefix", read(raw, "sessionPrefix"), TANGERE_DEFAULTS.sessionPrefix)
+	};
+}
+/** A non-object source reads as every key unset, so a caller that passes nothing fails on the first required key. */
+function read(source, key) {
+	if (typeof source !== "object" || source === null) return void 0;
+	return key in source ? Reflect.get(source, key) : void 0;
+}
+/**
+* Playwright's own `use.actionTimeout`, not one of tangere's. Playwright defaults
+* it to 0, which means "no timeout" there and would mean "give up at once" here,
+* so 0 falls back the way an unset value does.
+*/
+function parseActionTimeout(value) {
+	if (value === 0) return DEFAULT_ACTION_TIMEOUT_MS;
+	return positive("actionTimeout", value, DEFAULT_ACTION_TIMEOUT_MS);
+}
+function parseReadyWhen(raw) {
+	if (typeof raw !== "object" || raw === null) throw fail("readyWhen", "is required. Name something that only appears once the bundle has loaded, such as { text: 'Welcome' }.");
+	const wanted = read(raw, "text");
+	if (wanted !== void 0) {
+		if (typeof wanted !== "string" || wanted.length === 0) throw fail("readyWhen.text", "must be a non-empty string.");
+		return { name: textMatch(wanted, flag("readyWhen.exact", read(raw, "exact"), false)) };
+	}
+	const testId = read(raw, "testId");
+	if (testId !== void 0) {
+		if (typeof testId !== "string" || testId.length === 0) throw fail("readyWhen.testId", "must be a non-empty string.");
+		return { testId: textMatch(testId, true) };
+	}
+	const wantedRole = read(raw, "role");
+	const role = ROLES.find((candidate) => candidate === wantedRole);
+	if (role === void 0) throw fail("readyWhen", "must be one of { text }, { testId }, or { role, name }.");
+	const name = read(raw, "name");
+	if (name === void 0) return { role };
+	if (typeof name !== "string") throw fail("readyWhen.name", "must be a string.");
+	return {
+		role,
+		name: textMatch(name)
+	};
+}
+function parseDeviceChoice(raw) {
+	if (raw === void 0) return { kind: "first-booted" };
+	if (typeof raw === "string") {
+		if (raw.length === 0) throw fail("deviceName", "must not be empty.");
+		return {
+			kind: "named",
+			name: raw
+		};
+	}
+	if (!isStringArray(raw) || raw.length === 0) throw fail("deviceName", "must be a device name or a non-empty array of device names.");
+	return {
+		kind: "pool",
+		names: raw
+	};
+}
+function isStringArray(raw) {
+	return Array.isArray(raw) && raw.every((entry) => typeof entry === "string");
+}
+/**
+* Anything but a pool serves slot 0 only. Two workers pointed at one device both
+* try to claim it, and because leftovers carrying this library's session prefix
+* are always reclaimed, the second worker would close the first worker's live
+* session mid-test. That has to be a config error, not a race.
+*/
+function deviceNameForSlot(options, slot) {
+	const choice = options.device;
+	switch (choice.kind) {
+		case "first-booted":
+			if (slot > 0) throw tooFewDevices("is unset, so every worker would target the same booted device", slot);
+			return null;
+		case "named":
+			if (slot > 0) throw tooFewDevices(`names one device, "${choice.name}"`, slot);
+			return choice.name;
+		case "pool": {
+			const name = choice.names[slot];
+			if (name === void 0) throw tooFewDevices(`lists ${String(choice.names.length)} devices`, slot);
+			return name;
+		}
+		default: throw new Error(`unhandled device choice ${JSON.stringify(choice)}`);
+	}
+}
+function tooFewDevices(problem, slot) {
+	return fail("deviceName", `${problem}, but Playwright asked for worker slot ${String(slot)}. List one device name per worker, or set \`workers: 1\`.`);
+}
+function oneOf(field, value, allowed, fallback) {
+	if (value === void 0) return fallback;
+	const found = allowed.find((candidate) => candidate === value);
+	if (found === void 0) throw fail(field, `must be one of ${allowed.map((one) => `'${one}'`).join(", ")}.`);
+	return found;
+}
+function positive(field, value, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw fail(field, "must be a positive number of milliseconds.");
+	return value;
+}
+function flag(field, value, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") throw fail(field, "must be true or false.");
+	return value;
+}
+function optionalText(field, value) {
+	if (value === void 0) return null;
+	if (typeof value !== "string" || value.length === 0) throw fail(field, "must be a non-empty string.");
+	return value;
+}
+function text(field, value, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "string" || value.length === 0) throw fail(field, "must be a non-empty string.");
+	return value;
+}
+function fail(field, detail) {
+	return new TangereError({
+		kind: "config",
+		field,
+		detail
+	});
+}
+//#endregion
+//#region src/core/checks.ts
+/**
+* A `many` outcome never passes anything but `toHaveCount`. An ambiguous locator
+* is a strictness violation, and it reports through the same message path as a
+* plain mismatch rather than guessing which node was meant.
+*/
+function evaluate(check, resolution) {
+	if (check.name === "toHaveCount") {
+		const count = countOf(resolution);
+		return {
+			pass: count === check.expected,
+			actual: String(count)
+		};
+	}
+	if (resolution.outcome === "none") return {
+		pass: false,
+		actual: null
+	};
+	if (resolution.outcome === "many") return {
+		pass: false,
+		actual: `${String(resolution.nodes.length)} matching nodes`
+	};
+	const node = resolution.node;
+	switch (check.name) {
+		case "toBeVisible": return {
+			pass: true,
+			actual: describeNode(node)
+		};
+		case "toHaveText": {
+			const text = node.name ?? node.value;
+			return {
+				pass: matchesText(check.expected, text),
+				actual: text === null ? null : `"${text}"`
+			};
+		}
+		case "toHaveValue": return {
+			pass: matchesText(check.expected, node.value),
+			actual: node.value === null ? null : `"${node.value}"`
+		};
+		case "toBeEnabled": return {
+			pass: node.enabled,
+			actual: node.enabled ? "enabled" : "disabled"
+		};
+		case "toBeSelected": return {
+			pass: node.selected,
+			actual: node.selected ? "selected" : "not selected"
+		};
+		case "toBeFocused": return {
+			pass: node.focused,
+			actual: node.focused ? "focused" : "not focused"
+		};
+		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
+	}
+}
+function countOf(resolution) {
+	switch (resolution.outcome) {
+		case "one": return 1;
+		case "none": return 0;
+		case "many": return resolution.nodes.length;
+		default: throw new Error(`unhandled resolution ${JSON.stringify(resolution)}`);
+	}
+}
+/** The `Expected:` line. */
+function describeCheck(check) {
+	switch (check.name) {
+		case "toBeVisible": return "visible";
+		case "toHaveText": return `text ${describeExpected(check.expected)}`;
+		case "toHaveValue": return `value ${describeExpected(check.expected)}`;
+		case "toBeEnabled": return "enabled";
+		case "toBeSelected": return "selected";
+		case "toBeFocused": return "focused";
+		case "toHaveCount": return `count ${String(check.expected)}`;
+		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
+	}
+}
+function describeExpected(match) {
+	return match.kind === "regex" ? String(match.value) : `"${match.value}"`;
+}
+function describeNode(node) {
+	const name = node.name === null ? "" : ` "${node.name}"`;
+	return `${node.ref} [${node.role}]${name}`;
+}
+//#endregion
+//#region src/core/screen.ts
+const IOS_ROLES = {
+	Application: "application",
+	Window: "window",
+	Button: "button",
+	StaticText: "text",
+	TextView: "text",
+	TextField: "text-field",
+	SearchField: "text-field",
+	SecureTextField: "secure-text-field",
+	Link: "link",
+	Image: "image",
+	Icon: "image",
+	Switch: "switch",
+	Toggle: "switch",
+	Slider: "slider",
+	TabBar: "tab-bar",
+	Tab: "button",
+	ScrollView: "scroll-area",
+	ScrollArea: "scroll-area",
+	Table: "scroll-area",
+	CollectionView: "scroll-area",
+	Cell: "cell",
+	Alert: "alert",
+	Sheet: "alert",
+	Other: "other"
+};
+/**
+* Observed on a booted Android emulator (API 36) snapshotting this repo's React
+* Native 0.86 sample app, except the trailing widget block, which this app never
+* renders and stays a plausible guess. `android.view.ViewGroup` is what every
+* React Native `View` reports, testID containers included, so it is stated here
+* rather than left to the `other` fall-through in `roleOf`.
+*/
+const ANDROID_ROLES = {
+	"android.widget.Button": "button",
+	"android.widget.TextView": "text",
+	"android.widget.EditText": "text-field",
+	"android.widget.ImageView": "image",
+	"android.widget.ScrollView": "scroll-area",
+	"android.view.ViewGroup": "other",
+	"android.widget.FrameLayout": "other",
+	"android.widget.LinearLayout": "other",
+	"android.widget.ImageButton": "button",
+	"android.widget.Switch": "switch",
+	"android.widget.CheckBox": "switch",
+	"android.widget.SeekBar": "slider",
+	"android.widget.HorizontalScrollView": "scroll-area",
+	"androidx.recyclerview.widget.RecyclerView": "scroll-area"
+};
+function roleOf(rawType, platform) {
+	const table = platform === "ios" ? IOS_ROLES : ANDROID_ROLES;
+	const direct = table[rawType];
+	if (direct !== void 0) return direct;
+	return table[rawType.slice(rawType.lastIndexOf(".") + 1)] ?? "other";
+}
+/**
+* The parse boundary. Everything past it trusts its types.
+*
+* `inheritsLabel` and `inheritsIdentifier` mean the driver omitted a value that
+* string-equals the nearest ancestor's, so those are restored here rather than
+* leaving a hole a matcher would read as absent.
+*/
+function parseScreen(raw, platform) {
+	const nodes = [];
+	const byIndex = /* @__PURE__ */ new Map();
+	for (const source of raw.nodes) {
+		const parent = source.parentIndex === void 0 ? null : byIndex.get(source.parentIndex) ?? null;
+		const rawType = source.type ?? source.role ?? "Other";
+		const node = {
+			ref: source.ref.startsWith("@") ? source.ref : `@${source.ref}`,
+			index: source.index,
+			parent,
+			depth: source.depth ?? (parent === null ? 0 : parent.depth + 1),
+			role: roleOf(rawType, platform),
+			rawType,
+			name: inherited(source.label, source.inheritsLabel, parent, (a) => a.name),
+			value: parsedValue(source),
+			testId: inherited(source.identifier, source.inheritsIdentifier, parent, (a) => a.testId),
+			rect: source.rect ?? null,
+			enabled: source.enabled ?? true,
+			selected: source.selected ?? false,
+			focused: source.focused ?? false,
+			hiddenContentAbove: source.hiddenContentAbove ?? false,
+			hiddenContentBelow: source.hiddenContentBelow ?? false
+		};
+		nodes.push(node);
+		byIndex.set(node.index, node);
+	}
+	return Object.freeze({
+		nodes: Object.freeze(nodes),
+		generation: raw.refsGeneration ?? null,
+		appId: raw.appBundleId ?? null,
+		truncated: raw.truncated ?? false,
+		capturedAt: Date.now()
+	});
+}
+/**
+* On Android a field showing its hint reports the hint as its `value`, so the
+* flag is the only thing separating an empty field from one a user typed into.
+* agent-device 0.20.10's Android snapshot helper does not emit `hintShowing`
+* yet, which is why no fixture on disk carries it.
+*/
+function parsedValue(source) {
+	if (source.hintShowing === true) return "";
+	return source.value === void 0 ? null : normalizeText(source.value);
+}
+function inherited(own, inherits, parent, read) {
+	if (own !== void 0) return normalizeText(own);
+	if (inherits !== true) return null;
+	for (let ancestor = parent; ancestor !== null; ancestor = ancestor.parent) {
+		const value = read(ancestor);
+		if (value !== null) return value;
+	}
+	return null;
+}
+/**
+* The single resolver, shared by actions and assertions so the two can never
+* disagree about which node was meant. Rule order: match every query field,
+* apply every `.filter()`, absorb ancestors, then `index`.
+*
+* Ancestor absorption drops a match when a descendant match carries the same
+* string the query matched on. On the sample app an `[other]` container and its
+* `[text]` child both carry "Live from the cloud", which is one thing on screen.
+* Matches in disjoint subtrees stay distinct, so "Explore" on the Explore screen
+* is still the heading and the tab button.
+*/
+function resolve(screen, query) {
+	const distinct = matchesOf(screen, query);
+	if (query.index !== void 0) {
+		const picked = distinct.at(query.index);
+		if (picked === void 0) return {
+			outcome: "none",
+			nearest: nearestTo(screen, query)
+		};
+		return {
+			outcome: "one",
+			node: picked
+		};
+	}
+	const first = distinct[0];
+	if (first === void 0) return {
+		outcome: "none",
+		nearest: nearestTo(screen, query)
+	};
+	if (distinct.length > 1) return {
+		outcome: "many",
+		nodes: distinct
+	};
+	return {
+		outcome: "one",
+		node: first
+	};
+}
+/**
+* Everything a query matches, before `index` and before strictness. `resolve`
+* and the `has` filters share it, so an inner query means what the same locator
+* would mean on its own.
+*/
+function matchesOf(screen, query) {
+	return absorbAncestors(screen.nodes.filter((node) => matchesQuery(node, query) && (query.filters ?? []).every((filter) => matchesFilter(screen, node, filter))), query);
+}
+/** `hasText` includes the candidate's own text, while `has` needs a strict descendant. Mirrors Playwright. */
+function matchesFilter(screen, node, filter) {
+	if (filter.hasText !== void 0 && !subtreeHasText(screen, node, filter.hasText)) return false;
+	if (filter.hasNotText !== void 0 && subtreeHasText(screen, node, filter.hasNotText)) return false;
+	if (filter.has !== void 0 && !containsMatch(screen, node, filter.has)) return false;
+	if (filter.hasNot !== void 0 && containsMatch(screen, node, filter.hasNot)) return false;
+	return true;
+}
+function subtreeHasText(screen, candidate, match) {
+	return screen.nodes.some((node) => (node === candidate || isDescendant(node, candidate)) && (matchesText(match, node.name) || matchesText(match, node.value)));
+}
+function containsMatch(screen, candidate, inner) {
+	return matchesOf(screen, inner).some((node) => isDescendant(node, candidate));
+}
+function matchesQuery(node, query) {
+	if (query.role !== void 0 && node.role !== query.role) return false;
+	if (query.testId !== void 0 && !matchesText(query.testId, node.testId)) return false;
+	if (query.value !== void 0 && !matchesText(query.value, node.value)) return false;
+	if (query.name !== void 0 && !matchesText(query.name, node.name) && !matchesText(query.name, node.value)) return false;
+	if (query.enabled !== void 0 && node.enabled !== query.enabled) return false;
+	if (query.selected !== void 0 && node.selected !== query.selected) return false;
+	if (query.focused !== void 0 && node.focused !== query.focused) return false;
+	if (query.where !== void 0 && !query.where(node)) return false;
+	return true;
+}
+/**
+* The string the query matched this node on. Two nodes on one ancestor chain
+* sharing it are one thing on screen. A query that constrains no text falls back
+* to the node's name, so `getByRole('button')` does not collapse two nested
+* buttons that say different things.
+*
+* A `hasText` filter names a string on screen, so it contributes the same
+* pattern to every candidate and collapses a chain to the innermost container
+* holding that text. Almost every React Native container reports role `other`,
+* so without this `getByRole('other').filter({ hasText })` would match every
+* wrapper rather than the row the author meant. `hasNotText`, `has` and `hasNot`
+* name structure or an absence, so they contribute nothing.
+*/
+function matchedText(node, query) {
+	const parts = [];
+	if (query.testId !== void 0) parts.push(node.testId ?? "");
+	if (query.value !== void 0) parts.push(node.value ?? "");
+	if (query.name !== void 0) parts.push(node.name ?? node.value ?? "");
+	for (const filter of query.filters ?? []) if (filter.hasText !== void 0) parts.push(describeMatch(filter.hasText));
+	return parts.length === 0 ? node.name ?? "" : parts.join(" ");
+}
+function absorbAncestors(matched, query) {
+	return matched.filter((candidate) => !matched.some((other) => other !== candidate && isDescendant(other, candidate) && matchedText(other, query) === matchedText(candidate, query)));
+}
+function isDescendant(node, ancestor) {
+	for (let walk = node.parent; walk !== null; walk = walk.parent) if (walk === ancestor) return true;
+	return false;
+}
+/** The named nodes closest to what the query asked for. A miss is usually a wording drift. */
+function nearestTo(screen, query) {
+	const wanted = wantedText(query);
+	const named = screen.nodes.filter((node) => node.name !== null || node.testId !== null);
+	if (wanted === null) return named.slice(0, 5);
+	const target = wanted.toLowerCase();
+	return named.map((node) => ({
+		node,
+		score: overlap(target, (node.name ?? node.testId ?? "").toLowerCase())
+	})).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, 5).map((entry) => entry.node);
+}
+function wantedText(query) {
+	const asked = (query.filters ?? []).map((filter) => filter.hasText);
+	for (const match of [
+		query.name,
+		query.testId,
+		query.value,
+		...asked
+	]) if (match !== void 0 && match.kind !== "regex") return match.value;
+	return null;
+}
+function overlap(wanted, candidate) {
+	const words = wanted.split(" ").filter((word) => word.length > 2);
+	const hits = words.filter((word) => candidate.includes(word)).length;
+	if (hits > 0) return hits / words.length;
+	return candidate.includes(wanted) || wanted.includes(candidate) ? .5 : 0;
+}
+/**
+* With a generation this is the driver's `@e12~s776575` form, which the driver
+* rejects once that generation is superseded. Without one the bare ref is still
+* correct, because the caller acts on the very next command and a frame
+* authorizes the refs it just emitted. Weaker, not wrong, so this cannot fail.
+*/
+function pin(screen, node) {
+	return screen.generation === null ? node.ref : `${node.ref}~s${String(screen.generation)}`;
+}
+/**
+* The one tree renderer, used by failure messages and by the `screen.txt`
+* attachment so terminal and report agree. The vocabulary is the CLI's own
+* `[role] "label"` form.
+*/
+function renderScreen(screen, options) {
+	const max = options?.maxNodes ?? screen.nodes.length;
+	const lines = screen.nodes.slice(0, max).map((node) => renderNode(node));
+	if (screen.nodes.length > max) lines.push(`  ... ${String(screen.nodes.length - max)} more nodes`);
+	return lines.join("\n");
+}
+function renderNode(node) {
+	const indent = "  ".repeat(node.depth);
+	const name = node.name === null ? "" : ` "${node.name}"`;
+	const testId = node.testId === null ? "" : ` #${node.testId}`;
+	const flags = [
+		node.selected ? "selected" : null,
+		node.focused ? "focused" : null,
+		node.enabled ? null : "disabled",
+		node.hiddenContentAbove ? "more above" : null,
+		node.hiddenContentBelow ? "more below" : null
+	].filter((flag) => flag !== null).map((flag) => ` [${flag}]`).join("");
+	return `${indent}${node.ref} [${node.role}]${name}${testId}${flags}`;
+}
+//#endregion
+//#region src/core/report.ts
+const FILL_TEXT_LIMIT = 40;
+/** Rendered here rather than in an adapter so every runner produces the same text. */
+function renderTitle(record) {
+	switch (record.kind) {
+		case "open": return `open ${record.app} on ${record.device} as ${record.session}`;
+		case "tap": return `tap ${describeQuery(record.query)}`;
+		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 "scroll": return `scroll ${record.direction}`;
+		case "scroll-into-view": return `scrollIntoView ${describeQuery(record.query)}`;
+		case "relaunch": return `relaunch ${record.app}`;
+		case "dismiss-overlay": return "dismiss the React Native dev overlay";
+		case "screenshot": return `screenshot ${record.path}`;
+		default: throw new Error(`unhandled action record ${JSON.stringify(record)}`);
+	}
+}
+function renderTyped(typed) {
+	switch (typed.kind) {
+		case "text": return `type "${truncate(typed.value)}"`;
+		case "hidden": return `type ${String(typed.length)} characters`;
+		default: throw new Error(`unhandled typed value ${JSON.stringify(typed)}`);
+	}
+}
+function truncate(text) {
+	return text.length <= FILL_TEXT_LIMIT ? text : `${text.slice(0, FILL_TEXT_LIMIT)}...`;
+}
+/** Discards everything. The default for scripts, unit tests, and runners with no reporting. */
+const silentSink = {
+	step: (_title, body) => body(),
+	attach: () => Promise.resolve(),
+	note: () => {},
+	outputPath: (fileName) => fileName
+};
+//#endregion
+//#region src/core/session.ts
+const READY_POLL_MS = 250;
+const SNAPSHOT_TIMEOUT_MS = 15e3;
+function createQueue() {
+	let tail = Promise.resolve();
+	return { enqueue(body) {
+		const next = tail.then(body);
+		tail = next.catch(() => void 0);
+		return next;
+	} };
+}
+/**
+* Convergent startup. Running it twice settles on one ready session. In order:
+* reclaim a leftover session of the same name, open with the selection carried
+* on that first command, recover once from a device claimed by a leftover or
+* under `onDeviceInUse: 'reclaim'`, recover once from a session bound to another
+* device, then hold until `readyWhen` resolves, because `open` returns while the
+* JavaScript bundle is still loading.
+*/
+async function openSession(input) {
+	const { options, sink } = input;
+	const name = sessionName(options, input.scope, input.slot);
+	const deviceName = deviceNameForSlot(options, input.slot);
+	const driver = input.createDriver(name, {
+		platform: options.platform,
+		name: deviceName
+	});
+	const deadline = Date.now() + options.launchTimeout;
+	await driver.close(name);
+	const binding = await openWithRecovery(driver, options, name, deviceName);
+	sink.note("device", `${binding.deviceLabel} (${binding.platform}) session ${binding.session}`);
+	const session = createSession(driver, options, name, binding);
+	await sink.step(renderTitle({
+		kind: "open",
+		app: options.app,
+		device: binding.deviceLabel,
+		session: name
+	}), async () => {
+		if (options.dismissDevOverlay) await session.dismissDevOverlay();
+		await session.awaitReady(deadline);
+	});
+	return session;
+}
+async function openWithRecovery(driver, options, name, deviceName) {
+	const request = {
+		app: options.app,
+		relaunch: true,
+		url: options.launchUrl
+	};
+	try {
+		return await driver.open(request);
+	} catch (error) {
+		const failure = failureOf(error);
+		if (failure === null) throw error;
+		if (failure.kind === "device-busy") {
+			const owner = failure.owner;
+			if (!(owner !== null && (owner.startsWith(options.sessionPrefix) || options.onDeviceInUse === "reclaim"))) throw new TangereError({
+				kind: "device-in-use",
+				owner,
+				device: deviceName ?? options.platform,
+				releaseCommand: `agent-device close --session ${owner ?? "<owner>"}`,
+				canReclaim: options.onDeviceInUse === "fail"
+			});
+			await driver.close(owner);
+			return await driver.open(request);
+		}
+		if (failure.kind === "session-rebound") {
+			await driver.close(name);
+			return await driver.open(request);
+		}
+		throw new TangereError({
+			kind: "launch-failed",
+			app: options.app,
+			device: deviceName ?? options.platform,
+			failure
+		});
+	}
+}
+function createSession(driver, options, name, binding) {
+	const queue = createQueue();
+	let state = {
+		phase: "ready",
+		binding
+	};
+	const settle = (budgetMs) => ({
+		settleQuietMs: options.settleQuietMs,
+		timeoutMs: Math.max(budgetMs, options.settleQuietMs)
+	});
+	const device = {
+		capture: async () => parseScreen(await driver.capture({
+			timeoutMs: SNAPSHOT_TIMEOUT_MS,
+			tree: "default"
+		}), options.platform),
+		captureRaw: async () => parseScreen(await driver.capture({
+			timeoutMs: SNAPSHOT_TIMEOUT_MS,
+			tree: "raw"
+		}), options.platform),
+		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)),
+		scroll: (direction, budgetMs) => driver.scroll(direction, settle(budgetMs))
+	};
+	function run(body) {
+		return queue.enqueue(async () => {
+			if (state.phase !== "ready") throw unusable(state);
+			try {
+				return await body(device);
+			} catch (error) {
+				const failure = failureOf(error);
+				if (failure !== null && breaksTheSession(failure)) state = {
+					phase: "broken",
+					failure
+				};
+				throw error;
+			}
+		});
+	}
+	async function awaitReady(deadline) {
+		const started = Date.now();
+		let screen;
+		for (;;) {
+			screen = await run((one) => one.capture());
+			if (resolve(screen, options.readyWhen).outcome !== "none") return;
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) break;
+			await sleep(Math.min(READY_POLL_MS, remaining));
+		}
+		throw new TangereError({
+			kind: "not-ready",
+			locator: describeQuery(options.readyWhen),
+			timeoutMs: Date.now() - started,
+			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({
+			kind: "relaunch",
+			app: options.app
+		}), async () => {
+			await run(() => driver.open({
+				app: options.app,
+				relaunch: true,
+				url: options.launchUrl
+			}));
+			if (options.dismissDevOverlay) await run(() => driver.dismissDevOverlay());
+			await awaitReady(Date.now() + options.launchTimeout);
+		}),
+		dismissDevOverlay: () => run(() => driver.dismissDevOverlay()),
+		awaitReady,
+		close: async (reason) => {
+			if (state.phase === "closed") return;
+			try {
+				await driver.close(name);
+			} finally {
+				state = {
+					phase: "closed",
+					reason
+				};
+			}
+		}
+	};
+}
+function unusable(state) {
+	if (state.phase === "broken") return new TangereError({
+		kind: "driver",
+		command: "device command",
+		failure: state.failure
+	});
+	return new TangereError({
+		kind: "session-closed",
+		command: "run a device command"
+	});
+}
+/**
+* Only a failure meaning the device or the session itself is gone breaks the
+* session. A stale ref, an ambiguous match, or one timed-out command is a
+* per-command outcome the caller recovers from.
+*/
+function breaksTheSession(failure) {
+	return failure.kind === "device-busy" || failure.kind === "device-missing" || failure.kind === "session-rebound";
+}
+/** Deterministic, so a worker replaced after a failure reconnects to the session it left behind. */
+function sessionName(options, project, slot) {
+	return `${options.sessionPrefix}-${project === "" ? "default" : project}-${String(slot)}`;
+}
+function failureOf(error) {
+	if (!(error instanceof TangereError)) return null;
+	if (error.info.kind === "driver") return error.info.failure;
+	if (error.info.kind === "launch-failed") return error.info.failure;
+	return null;
+}
+function sleep(ms) {
+	return new Promise((done) => setTimeout(done, ms));
+}
+//#endregion
+//#region src/core/probe.ts
+const POLL_INTERVAL_MS = 250;
+const SCREEN_LISTING_NODES = 60;
+/**
+* Polls a fresh screen until the check agrees with `negate`, the budget runs
+* out, or the session breaks. Never throws for a failed expectation, because the
+* adapter hands `{ pass, message }` to its assertion library.
+*
+* Every early exit reports `pass: options.negate`, the value that fails the
+* assertion whether or not the caller wrote `.not`. An ambiguous locator and a
+* dead session are wrong under `.not` too, so neither may pass by inversion.
+*/
+async function probe(target, check, options) {
+	const interval = options.intervalMs ?? POLL_INTERVAL_MS;
+	const deadline = Date.now() + options.timeoutMs;
+	let screen = null;
+	let resolution = {
+		outcome: "none",
+		nearest: []
+	};
+	let polls = 0;
+	for (;;) {
+		const broken = target.failure();
+		if (broken !== null) return {
+			pass: options.negate,
+			message: `Device session is unusable: ${describeFailure(broken)}`,
+			actual: null,
+			expected: describeCheck(check)
+		};
+		screen = await target.capture();
+		polls += 1;
+		resolution = resolve(screen, target.query);
+		if (resolution.outcome === "many" && check.name !== "toHaveCount") return {
+			pass: options.negate,
+			actual: `${String(resolution.nodes.length)} matching nodes`,
+			expected: describeCheck(check),
+			message: formatFailure({
+				locator: target.description,
+				check,
+				negate: options.negate,
+				resolution,
+				screen,
+				timeoutMs: options.timeoutMs,
+				polls
+			})
+		};
+		const verdict = evaluate(check, resolution);
+		if (verdict.pass !== options.negate) return {
+			pass: !options.negate,
+			message: "",
+			actual: verdict.actual,
+			expected: describeCheck(check)
+		};
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) break;
+		await sleep(Math.min(interval, remaining));
+	}
+	const verdict = evaluate(check, resolution);
+	return {
+		pass: options.negate,
+		actual: verdict.actual,
+		expected: describeCheck(check),
+		message: formatFailure({
+			locator: target.description,
+			check,
+			negate: options.negate,
+			resolution,
+			screen,
+			timeoutMs: options.timeoutMs,
+			polls
+		})
+	};
+}
+/**
+* The screen listing comes from `renderScreen`, the same function that writes
+* `screen.txt`, so terminal and report agree.
+*/
+function formatFailure(input) {
+	return [
+		`Expected ${input.negate ? "not." : ""}${input.check.name} but it never held.`,
+		``,
+		`Locator: ${input.locator}`,
+		`Expected: ${input.negate ? "not " : ""}${describeCheck(input.check)}`,
+		`Received: ${received(input.resolution, input.check)}`,
+		`Timeout: ${String(input.timeoutMs)}ms (${String(input.polls)} snapshot${input.polls === 1 ? "" : "s"})`,
+		``,
+		`Screen:`,
+		input.screen === null ? "  (no screen captured)" : renderScreen(input.screen, { maxNodes: SCREEN_LISTING_NODES }),
+		``,
+		`screen.png and screen.txt are attached to this test in the HTML report.`
+	].join("\n");
+}
+function received(resolution, check) {
+	switch (resolution.outcome) {
+		case "one": return evaluate(check, resolution).actual ?? describeNode(resolution.node);
+		case "many": return [`${String(resolution.nodes.length)} nodes matched, which is ambiguous. Narrow the locator or use .first() / .nth(n).`, ...resolution.nodes.map((node) => `  ${describeNode(node)}`)].join("\n");
+		case "none": return resolution.nearest.length === 0 ? "no node matched" : [`no node matched. Closest names on screen:`, ...resolution.nearest.map((node) => `  ${describeNode(node)}`)].join("\n");
+		default: throw new Error(`unhandled resolution ${JSON.stringify(resolution)}`);
+	}
+}
+//#endregion
+//#region src/core/scroll.ts
+const MAX_SCROLL_STEPS = 20;
+function createScrollSearch(device, maxSteps = MAX_SCROLL_STEPS) {
+	let committed = null;
+	let steps = 0;
+	return {
+		trail: () => committed === null ? null : {
+			steps,
+			direction: committed
+		},
+		step: async (screen, query, budgetMs) => {
+			if (steps >= maxSteps) return false;
+			const next = directionToward(screen, await device.captureRaw(), query);
+			if (next === null || committed !== null && next !== committed) return false;
+			committed = next;
+			await device.scroll(next, budgetMs);
+			steps += 1;
+			return true;
+		}
+	};
+}
+/**
+* Which way the target lies, or null when nothing on screen says.
+*
+* The raw tree places the target itself, so when it carries the node, its rect
+* against the clipping container's rect is an answer rather than a guess. That
+* is the iOS case. Android's raw tree stops at the window, so the only evidence
+* left is the container reporting it holds content out of view.
+*/
+function directionToward(screen, raw, query) {
+	return (raw === null ? null : outsideViewport(raw, query)) ?? hiddenContentIn(screen);
+}
+function outsideViewport(raw, query) {
+	const found = resolve(raw, query);
+	if (found.outcome !== "one") return null;
+	const target = found.node.rect;
+	const viewport = clippingRect(found.node);
+	if (target === null || viewport === null) return null;
+	if (target.y >= viewport.y + viewport.height) return "down";
+	if (target.y + target.height <= viewport.y) return "up";
+	if (target.x >= viewport.x + viewport.width) return "right";
+	if (target.x + target.width <= viewport.x) return "left";
+	return null;
+}
+/**
+* A scroll container reports its own visible rect rather than the rect of
+* everything it holds, so a target beyond that rect is one it scrolled away.
+*/
+function clippingRect(node) {
+	for (let walk = node.parent; walk !== null; walk = walk.parent) if (walk.role === "scroll-area" && walk.rect !== null) return walk.rect;
+	return null;
+}
+function hiddenContentIn(screen) {
+	if (screen.nodes.some((node) => node.hiddenContentBelow)) return "down";
+	if (screen.nodes.some((node) => node.hiddenContentAbove)) return "up";
+	return null;
+}
+//#endregion
+//#region src/core/device.ts
+const ACTION_POLL_MS = 250;
+const DEFAULT_LONG_PRESS_MS = 1e3;
+function createDevice(session, sink) {
+	const build = (query) => createLocator(session, sink, query, device);
+	let screenshots = 0;
+	const device = {
+		getByText: (text, options) => build({ name: textMatch(text, options?.exact) }),
+		getByRole: (role, options) => build(options?.name === void 0 ? { role } : {
+			role,
+			name: textMatch(options.name, options.exact)
+		}),
+		getByTestId: (testId) => build({ testId: textMatch(testId, true) }),
+		locator: build,
+		scroll: (direction) => sink.step(renderTitle({
+			kind: "scroll",
+			direction
+		}), async () => {
+			await session.run((device) => device.scroll(direction, session.options.actionTimeout));
+		}),
+		relaunch: () => session.relaunch(sink),
+		dismissDevOverlay: () => sink.step(renderTitle({ kind: "dismiss-overlay" }), () => session.dismissDevOverlay()),
+		screen: () => session.screen(),
+		screenshot: (options) => {
+			if (options?.path === void 0) screenshots += 1;
+			const path = options?.path ?? sink.outputPath(`screenshot-${String(screenshots)}.png`);
+			return sink.step(renderTitle({
+				kind: "screenshot",
+				path
+			}), () => session.screenshot(path));
+		}
+	};
+	return device;
+}
+function createLocator(session, sink, query, device) {
+	const description = describeQuery(query);
+	const withIndex = (index) => createLocator(session, sink, {
+		...query,
+		index
+	}, device);
+	return {
+		query,
+		device,
+		description,
+		first: () => withIndex(0),
+		nth: (index) => withIndex(index),
+		filter: (options) => createLocator(session, sink, {
+			...query,
+			filters: [...query.filters ?? [], filterOf(options)]
+		}, device),
+		tap: (options) => perform(session, sink, {
+			kind: "tap",
+			query
+		}, options, (device, ref, budget) => device.tap(ref, budget)),
+		fill: (text, options) => perform(session, sink, {
+			kind: "fill",
+			query
+		}, options, (device, ref, budget) => device.fill(ref, text, budget), {
+			text,
+			secret: options?.secret ?? false
+		}),
+		longPress: (durationMs, options) => {
+			const held = durationMs ?? DEFAULT_LONG_PRESS_MS;
+			return perform(session, sink, {
+				kind: "long-press",
+				query,
+				durationMs: held
+			}, options, (device, ref, budget) => device.longPress(ref, held, budget));
+		},
+		scrollIntoView: (options) => scrollIntoView(session, sink, query, options),
+		count: async () => {
+			const resolution = resolve(await session.screen(), query);
+			return resolution.outcome === "many" ? resolution.nodes.length : resolution.outcome === "one" ? 1 : 0;
+		},
+		textContent: async () => {
+			const screen = await session.screen();
+			const resolution = resolve(screen, query);
+			switch (resolution.outcome) {
+				case "many": throw ambiguous(description, resolution.nodes, screen);
+				case "none": return null;
+				case "one": return resolution.node.name ?? resolution.node.value;
+				default: throw new Error(`unhandled resolution ${JSON.stringify(resolution)}`);
+			}
+		},
+		expect: (check, options) => probe({
+			query,
+			description,
+			capture: () => session.screen(),
+			failure: () => session.failure()
+		}, check, options)
+	};
+}
+function filterOf(options) {
+	return {
+		hasText: options.hasText === void 0 ? void 0 : textMatch(options.hasText),
+		hasNotText: options.hasNotText === void 0 ? void 0 : textMatch(options.hasNotText),
+		has: options.has?.query,
+		hasNot: options.hasNot?.query
+	};
+}
+/**
+* One action is one queued unit and one reported step. Ambiguity fails at once,
+* because waiting cannot make a locator less ambiguous. A stale ref retries
+* once, and a second one means the screen is changing faster than an action can
+* land.
+*
+* `write` makes this a write that is read back. A device keyboard drops early
+* keystrokes often enough that a fill can under-deliver and still report
+* success, so fill dispatches again until the field holds what it was given.
+* Re-filling is safe because a fill replaces the field's contents.
+*
+* The read back is two reads. Behind a controlled component the field is
+* written twice, by the driver and then by the app's own render, which can push
+* a stale string over what the driver typed. The second read, after the quiet
+* period, proves the value held. What counts as proof comes from the node's
+* role, because a secure field reports a mask. See `confirmationOf`.
+*/
+function perform(session, sink, record, options, dispatch, write) {
+	const timeout = options?.timeout ?? session.options.actionTimeout;
+	const locator = describeQuery(record.query);
+	return sink.step(renderTitle(record), async () => {
+		await session.run(async (device) => {
+			const deadline = Date.now() + timeout;
+			const search = createScrollSearch(reportingScrolls(device, sink));
+			let retriedStaleRef = false;
+			let attempts = 0;
+			let target = record.query;
+			let lastActual = null;
+			let screen = await device.capture();
+			const unconfirmed = (expected) => new TangereError({
+				kind: "fill-unconfirmed",
+				locator,
+				expected,
+				actual: lastActual === null ? null : disclose(expected, lastActual),
+				attempts,
+				timeoutMs: timeout,
+				screen: renderScreen(screen)
+			});
+			for (;;) {
+				const resolution = resolve(screen, target);
+				if (resolution.outcome === "many") throw ambiguous(locator, resolution.nodes, screen);
+				if (resolution.outcome === "one") {
+					const confirmation = write === void 0 ? null : confirmationOf(resolution.node.role, write);
+					if (confirmation !== null && attempts > 0 && deadline - Date.now() <= session.options.settleQuietMs) throw unconfirmed(expectedOf(confirmation));
+					let settled;
+					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;
+					}
+					attempts += 1;
+					if (!settled.settled) sink.note("settle", `${renderTitle(record)} finished before the screen went quiet`);
+					if (confirmation === null) return;
+					if (attempts === 1) await sink.step(renderTitle({
+						kind: "typed",
+						typed: typedOf(confirmation)
+					}), () => Promise.resolve(), { box: true });
+					target = identityOf(screen, resolution.node);
+					screen = await device.capture();
+					lastActual = valueAt(screen, target);
+					if (lastActual !== null && holds(confirmation, lastActual)) {
+						await sleep(session.options.settleQuietMs);
+						screen = await device.capture();
+						const second = valueAt(screen, target);
+						if (second === null || holds(confirmation, second)) return;
+						lastActual = second;
+					}
+					const left = deadline - Date.now();
+					if (left <= 0) throw unconfirmed(expectedOf(confirmation));
+					await sleep(Math.min(ACTION_POLL_MS, left));
+					screen = await device.capture();
+					continue;
+				}
+				const remaining = deadline - Date.now();
+				if (remaining <= 0) throw new TangereError({
+					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;
+				}
+				await sleep(Math.min(ACTION_POLL_MS, remaining));
+				screen = await device.capture();
+			}
+		});
+	});
+}
+/**
+* The stop condition is the default tree, never the raw one. The raw tree says
+* which way to go, but a node it carries may still be off screen, so stopping
+* on it would hand an action a ref the user cannot reach.
+*/
+function scrollIntoView(session, sink, query, options) {
+	const timeout = options?.timeout ?? session.options.actionTimeout;
+	const locator = describeQuery(query);
+	return sink.step(renderTitle({
+		kind: "scroll-into-view",
+		query
+	}), async () => {
+		await session.run(async (device) => {
+			const deadline = Date.now() + timeout;
+			const search = createScrollSearch(reportingScrolls(device, sink));
+			let screen = await device.capture();
+			for (;;) {
+				const resolution = resolve(screen, query);
+				if (resolution.outcome === "many") throw ambiguous(locator, resolution.nodes, screen);
+				if (resolution.outcome === "one") return;
+				const remaining = deadline - Date.now();
+				if (remaining <= 0 || !await search.step(screen, query, remaining)) throw new TangereError({
+					kind: "not-found",
+					locator,
+					timeoutMs: timeout,
+					screen: renderScreen(screen),
+					scrolled: search.trail()
+				});
+				screen = await device.capture();
+			}
+		});
+	});
+}
+/** Every scroll a search takes is a nested step, so a report shows what an action did to reach its target. */
+function reportingScrolls(device, sink) {
+	return {
+		captureRaw: () => device.captureRaw(),
+		scroll: (direction, budgetMs) => sink.step(renderTitle({
+			kind: "scroll",
+			direction
+		}), () => device.scroll(direction, budgetMs))
+	};
+}
+function ambiguous(locator, nodes, screen) {
+	return new TangereError({
+		kind: "strict-mode",
+		locator,
+		matches: nodes.map((node) => describeNode(node)),
+		screen: renderScreen(screen)
+	});
+}
+function confirmationOf(role, write) {
+	if (role === "secure-text-field") return {
+		kind: "mask",
+		length: write.text.length
+	};
+	return write.secret ? {
+		kind: "secret",
+		value: write.text
+	} : {
+		kind: "open",
+		value: write.text
+	};
+}
+function holds(confirmation, actual) {
+	switch (confirmation.kind) {
+		case "mask": return actual.length === confirmation.length && new Set(actual).size <= 1;
+		case "secret":
+		case "open": return actual === confirmation.value;
+		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
+	}
+}
+function expectedOf(confirmation) {
+	switch (confirmation.kind) {
+		case "mask": return {
+			kind: "masked",
+			length: confirmation.length
+		};
+		case "secret": return {
+			kind: "masked",
+			length: confirmation.value.length
+		};
+		case "open": return {
+			kind: "exact",
+			value: confirmation.value
+		};
+		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
+	}
+}
+function typedOf(confirmation) {
+	switch (confirmation.kind) {
+		case "mask": return {
+			kind: "hidden",
+			length: confirmation.length
+		};
+		case "secret": return {
+			kind: "hidden",
+			length: confirmation.value.length
+		};
+		case "open": return {
+			kind: "text",
+			value: confirmation.value
+		};
+		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
+	}
+}
+/** An actual value may be repeated back only as far as the expected one could be. */
+function disclose(expected, actual) {
+	return expected.kind === "masked" ? {
+		kind: "masked",
+		length: actual.length
+	} : {
+		kind: "exact",
+		value: actual
+	};
+}
+/** The field's current contents, or null once the locator stops resolving to exactly one node. */
+function valueAt(screen, target) {
+	const found = resolve(screen, target);
+	return found.outcome === "one" ? found.node.value ?? "" : null;
+}
+/**
+* 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.
+*/
+function identityOf(screen, node) {
+	if (node.testId !== null) {
+		const byTestId = { 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 };
+}
+//#endregion
+//#region src/core/evidence.ts
+/**
+* Never throws. A capture that fails records a note and returns, because masking
+* the test's real error with a screenshot error is worse than no screenshot.
+*/
+async function captureEvidence(session, sink) {
+	try {
+		const path = await session.screenshot(sink.outputPath("screen.png"));
+		await sink.attach({
+			name: "screen.png",
+			path,
+			contentType: "image/png"
+		});
+	} catch (error) {
+		sink.note("evidence", `screenshot failed: ${messageOf(error)}`);
+	}
+	try {
+		const screen = await session.screen();
+		await sink.attach({
+			name: "screen.txt",
+			body: renderScreen(screen),
+			contentType: "text/plain"
+		});
+	} catch (error) {
+		sink.note("evidence", `screen listing failed: ${messageOf(error)}`);
+	}
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/driver/agent-device.ts
+/** `full` is explicit because a digest-level response omits `nodes`, and the whole library matches on nodes. */
+function createClient() {
+	return createAgentDeviceClient({ responseLevel: "full" });
+}
+/**
+* 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) {
+	const where = {
+		session,
+		platform: selection.platform,
+		...selection.name === null ? {} : { device: selection.name }
+	};
+	async function run(command, body) {
+		try {
+			return await body();
+		} catch (error) {
+			throw new TangereError({
+				kind: "driver",
+				command,
+				failure: classifyError(error)
+			});
+		}
+	}
+	return {
+		listDevices: () => run("listDevices", async () => {
+			return (await client.devices.list({ platform: selection.platform })).map((device) => ({
+				id: device.id,
+				name: device.name,
+				booted: device.booted ?? false
+			}));
+		}),
+		open: (request) => run("open", async () => {
+			const result = await client.apps.open({
+				...where,
+				app: request.app,
+				relaunch: request.relaunch,
+				...request.url === null ? {} : { url: request.url }
+			});
+			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
+			};
+		}),
+		capture: (options) => run("snapshot", () => client.capture.snapshot({
+			...where,
+			forceFull: true,
+			raw: options.tree === "raw",
+			timeoutMs: options.timeoutMs
+		})),
+		screenshot: (path) => run("screenshot", async () => (await client.capture.screenshot({
+			...where,
+			path
+		})).path),
+		tap: (ref, options) => run("tap", async () => toSettled(await client.interactions.press({
+			...where,
+			ref,
+			...settle(options)
+		}))),
+		longPress: (ref, durationMs, options) => run("longPress", async () => toSettled(await client.interactions.longPress({
+			...where,
+			ref,
+			durationMs,
+			...settle(options)
+		}))),
+		fill: (ref, text, options) => run("fill", async () => toSettled(await client.interactions.fill({
+			...where,
+			ref,
+			text,
+			...settle(options)
+		}))),
+		scroll: (direction, options) => run("scroll", async () => {
+			await client.interactions.scroll({
+				...where,
+				direction,
+				...settle(options)
+			});
+		}),
+		dismissDevOverlay: () => run("dismissDevOverlay", async () => {
+			await client.command.reactNative({
+				...where,
+				action: "dismiss-overlay"
+			});
+		}),
+		close: (target) => run("close", async () => {
+			try {
+				await client.sessions.close({ session: target });
+			} catch (error) {
+				if (readNormalized(error).code !== "SESSION_NOT_FOUND") throw error;
+			}
+		})
+	};
+}
+function settle(options) {
+	return {
+		settle: true,
+		settleQuietMs: options.settleQuietMs,
+		timeoutMs: options.timeoutMs
+	};
+}
+/** `settle` is best-effort upstream and never fails an action, so an absent observation is not an error. */
+function toSettled(result) {
+	return {
+		settled: result.settle?.settled ?? false,
+		waitedMs: result.settle?.waitedMs ?? 0
+	};
+}
+function readNormalized(error) {
+	return normalizeAgentDeviceError(error);
+}
+/**
+* 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.
+*/
+function classifyError(error) {
+	const normalized = readNormalized(error);
+	const { code, message } = normalized;
+	const details = normalized.details ?? {};
+	const logPath = normalized.logPath ?? null;
+	switch (code) {
+		case "DEVICE_IN_USE": return {
+			kind: "device-busy",
+			owner: ownerOf(details, message),
+			detail: message
+		};
+		case "DEVICE_NOT_FOUND": return {
+			kind: "device-missing",
+			detail: message
+		};
+		case "APP_NOT_INSTALLED": return {
+			kind: "app-missing",
+			detail: message
+		};
+		case "AMBIGUOUS_MATCH": return {
+			kind: "ambiguous",
+			detail: message
+		};
+		case "INVALID_ARGS": {
+			const bound = /bound to (.+?)(?:[.]|$)/i.exec(message);
+			if (bound !== null) return {
+				kind: "session-rebound",
+				boundTo: bound[1] ?? message,
+				detail: message
+			};
+			return {
+				kind: "unknown",
+				code,
+				detail: message,
+				logPath
+			};
+		}
+		case "COMMAND_FAILED":
+			if (details["reason"] === "ref_generation_mismatch") return {
+				kind: "stale-ref",
+				detail: message
+			};
+			if (/timed out|timeout/i.test(message)) return {
+				kind: "timeout",
+				detail: message
+			};
+			return {
+				kind: "unknown",
+				code,
+				detail: message,
+				logPath
+			};
+		default: return {
+			kind: "unknown",
+			code,
+			detail: message,
+			logPath
+		};
+	}
+}
+/**
+* A device claim made in another workspace does not appear in a session listing
+* run from here, so the owning session name in the error is the only way to name
+* it. It arrives in `details` on some paths and only in the message text
+* (`by session "lex"`) on others.
+*/
+function ownerOf(details, message) {
+	for (const key of [
+		"session",
+		"owner",
+		"ownerSession"
+	]) {
+		const value = details[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return /by session "([^"]+)"/.exec(message)?.[1] ?? null;
+}
+//#endregion
+//#region src/core/screenshot.ts
+/**
+* The ratio is mismatched pixels over the image's own pixel count, so it means
+* the same whether the images are a whole device or one cropped button.
+*/
+function compareScreenshot(expected, actual, options) {
+	const before = PNG.sync.read(expected);
+	const after = PNG.sync.read(actual);
+	if (before.width !== after.width || before.height !== after.height) return {
+		kind: "size-mismatch",
+		expected: {
+			width: before.width,
+			height: before.height
+		},
+		actual: {
+			width: after.width,
+			height: after.height
+		}
+	};
+	for (const box of options.mask) {
+		paintBlack(before, box);
+		paintBlack(after, box);
+	}
+	const diff = new PNG({
+		width: before.width,
+		height: before.height
+	});
+	const ratio = pixelmatch(before.data, after.data, diff.data, before.width, before.height, { threshold: options.threshold }) / (before.width * before.height);
+	if (ratio <= options.maxDiffPixelRatio) return {
+		kind: "match",
+		ratio
+	};
+	return {
+		kind: "mismatch",
+		ratio,
+		diff: PNG.sync.write(diff)
+	};
+}
+/**
+* The box is clamped to the image, because a rect comes from a snapshot and a
+* screenshot is a separate capture. A control flush against the bottom edge can
+* round a pixel past it, and that is not a reason to fail an assertion.
+*/
+function cropScreenshot(source, box) {
+	const image = PNG.sync.read(source);
+	const clamped = clamp(box, {
+		width: image.width,
+		height: image.height
+	});
+	const cut = new PNG({
+		width: clamped.width,
+		height: clamped.height
+	});
+	PNG.bitblt(image, cut, clamped.x, clamped.y, clamped.width, clamped.height, 0, 0);
+	return PNG.sync.write(cut);
+}
+function sizeOf(source) {
+	const image = PNG.sync.read(source);
+	return {
+		width: image.width,
+		height: image.height
+	};
+}
+/** Rounded outward, so a control's own edge is never the thing that gets cut off. */
+function toPixelBox(rect, scale) {
+	const x = Math.floor(rect.x * scale);
+	const y = Math.floor(rect.y * scale);
+	return {
+		x,
+		y,
+		width: Math.ceil((rect.x + rect.width) * scale) - x,
+		height: Math.ceil((rect.y + rect.height) * scale) - y
+	};
+}
+/** Moves a box into the coordinates of a crop taken at `origin`. */
+function relativeTo(box, origin) {
+	return {
+		...box,
+		x: box.x - origin.x,
+		y: box.y - origin.y
+	};
+}
+function clamp(box, size) {
+	const x = Math.min(Math.max(box.x, 0), Math.max(size.width - 1, 0));
+	const y = Math.min(Math.max(box.y, 0), Math.max(size.height - 1, 0));
+	return {
+		x,
+		y,
+		width: Math.max(Math.min(box.width, size.width - x), 1),
+		height: Math.max(Math.min(box.height, size.height - y), 1)
+	};
+}
+function paintBlack(image, box) {
+	const region = clamp(box, {
+		width: image.width,
+		height: image.height
+	});
+	for (let row = region.y; row < region.y + region.height; row += 1) for (let column = region.x; column < region.x + region.width; column += 1) {
+		const at = image.width * row + column << 2;
+		image.data[at] = 0;
+		image.data[at + 1] = 0;
+		image.data[at + 2] = 0;
+		image.data[at + 3] = 255;
+	}
+}
+//#endregion
+//#region src/preflight.ts
+/**
+* Outside `core/` on purpose: this is the one function that needs a concrete
+* driver, and no module under `core/` may import `agent-device`.
+*/
+/**
+* A device that is not booted is reported as problems rather than thrown, so a
+* runner names every one of them at once. A malformed config still throws, the
+* way it does everywhere else. `driver` is the seam tests inject.
+*/
+async function preflight(options, driver) {
+	const resolved = parseDeviceOptions(options);
+	const lister = driver ?? createAgentDeviceDriver(createClient(), `${resolved.sessionPrefix}-preflight`, {
+		platform: resolved.platform,
+		name: null
+	});
+	let devices;
+	try {
+		devices = await lister.listDevices();
+	} catch (error) {
+		return {
+			ok: false,
+			problems: [unreachable(resolved.platform, error)]
+		};
+	}
+	const booted = devices.filter((device) => device.booted);
+	const wanted = namesOf(resolved.device);
+	if (wanted.length === 0) {
+		const picked = booted[0];
+		if (picked === void 0) return {
+			ok: false,
+			problems: [noneBooted(resolved.platform)]
+		};
+		return {
+			ok: true,
+			device: {
+				name: picked.name,
+				id: picked.id
+			}
+		};
+	}
+	const found = [];
+	const problems = [];
+	for (const name of wanted) {
+		const match = booted.find((device) => device.name === name);
+		if (match === void 0) problems.push(notBooted(resolved.platform, name, booted));
+		else found.push(match);
+	}
+	const picked = found[0];
+	if (problems.length > 0 || picked === void 0) return {
+		ok: false,
+		problems
+	};
+	return {
+		ok: true,
+		device: {
+			name: picked.name,
+			id: picked.id
+		}
+	};
+}
+/** The names this choice insists on. Empty means any booted device will do. */
+function namesOf(choice) {
+	switch (choice.kind) {
+		case "first-booted": return [];
+		case "named": return [choice.name];
+		case "pool": return choice.names;
+		default: throw new Error(`unhandled device choice ${JSON.stringify(choice)}`);
+	}
+}
+function unreachable(platform, error) {
+	const failure = failureOf(error);
+	return `Could not list ${platform} devices: ${failure === null ? error instanceof Error ? error.message : String(error) : describeFailure(failure)}. Check that the agent-device daemon is reachable.`;
+}
+function noneBooted(platform) {
+	return `No ${platform} device is booted. Boot one with \`agent-device device boot --platform ${platform}\`.`;
+}
+function notBooted(platform, name, booted) {
+	if (booted.length === 0) return `No booted ${platform} device is named '${name}', because no ${platform} device is booted at all. Boot '${name}'.`;
+	return `No booted ${platform} device is named '${name}'. Booted right now: ${booted.map((device) => `'${device.name}'`).join(", ")}. Set use.deviceName to one of those or boot '${name}'.`;
+}
+//#endregion
+export { textMatch as A, describeCheck as C, parseDeviceOptions as D, deviceNameForSlot as E, describeQuery as O, resolve as S, TANGERE_DEFAULTS as T, sleep as _, sizeOf as a, parseScreen as b, createClient as c, createScrollSearch as d, directionToward as f, sessionName as g, openSession as h, relativeTo as i, TangereError as j, normalizeText as k, captureEvidence as l, probe as m, compareScreenshot as n, toPixelBox as o, formatFailure as p, cropScreenshot as r, createAgentDeviceDriver as s, preflight as t, createDevice as u, renderTitle as v, evaluate as w, renderScreen as x, silentSink as y };