@delacour/warden-e2e 0.13.0 → 0.15.0

package/types/e2e/src/driver/ios/simd-protocol.d.ts

@@ -192,6 +192,32 @@ export declare const healthDataSchema: z.ZodObject<{
         unresolvedAgoMs: z.ZodNumber;
         method: z.ZodString;
     }, z.core.$strip>>;
+    bridgeRecycles: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+        exhausted: z.ZodBoolean;
+    }, z.core.$strip>>;
+    axWedge: z.ZodOptional<z.ZodLazy<z.ZodObject<{
+        restarts: z.ZodNumber;
+        maxRestarts: z.ZodNumber;
+        recovering: z.ZodBoolean;
+        checked: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            restarted: "restarted";
+            "not-wedged": "not-wedged";
+        }>>;
+        last: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"restarted">;
+            agoMs: z.ZodNumber;
+            ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>, z.ZodObject<{
+            outcome: z.ZodLiteral<"not-wedged">;
+            agoMs: z.ZodNumber;
+        }, z.core.$loose>, z.ZodObject<{
+            outcome: z.ZodLiteral<"failed">;
+            agoMs: z.ZodNumber;
+            error: z.ZodString;
+        }, z.core.$loose>], "outcome">>;
+    }, z.core.$loose>>>;
     state: z.ZodOptional<z.ZodString>;
     uptimeMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
@@ -214,6 +240,19 @@ export declare const snapshotDataSchema: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         reason: z.ZodString;
+        stall: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodString;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodBoolean;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodNumber;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+            axWedge: z.ZodOptional<z.ZodString>;
+            axWedgeRestarts: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
     }, z.core.$strip>>;
     target: z.ZodOptional<z.ZodObject<{
         pid: z.ZodNumber;
@@ -324,6 +363,34 @@ export declare const orientationDataSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type OrientationData = z.infer<typeof orientationDataSchema>;
+/**
+ * `axWedge{recover?}`: the helper's check for a wedged accessibility service (both readers silent + the marker in the
+ * sim log → backboardd restarted). `recover: true` runs the check now (or joins the one in flight) and answers when it
+ * is over; nothing runs once `restarts` reached `maxRestarts` (`WARDEN_SIMD_AX_WEDGE_RESTARTS`).
+ */
+export declare const axWedgeDataSchema: z.ZodObject<{
+    restarts: z.ZodNumber;
+    maxRestarts: z.ZodNumber;
+    recovering: z.ZodBoolean;
+    checked: z.ZodOptional<z.ZodEnum<{
+        failed: "failed";
+        restarted: "restarted";
+        "not-wedged": "not-wedged";
+    }>>;
+    last: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"restarted">;
+        agoMs: z.ZodNumber;
+        ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>, z.ZodObject<{
+        outcome: z.ZodLiteral<"not-wedged">;
+        agoMs: z.ZodNumber;
+    }, z.core.$loose>, z.ZodObject<{
+        outcome: z.ZodLiteral<"failed">;
+        agoMs: z.ZodNumber;
+        error: z.ZodString;
+    }, z.core.$loose>], "outcome">>;
+}, z.core.$loose>;
+export type AxWedgeData = z.infer<typeof axWedgeDataSchema>;
 /** Ops whose `data` the client validates and types; every other op's data stays `unknown`. */
 export declare const opSchemas: {
     readonly health: z.ZodObject<{
@@ -362,6 +429,32 @@ export declare const opSchemas: {
             unresolvedAgoMs: z.ZodNumber;
             method: z.ZodString;
         }, z.core.$strip>>;
+        bridgeRecycles: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+            exhausted: z.ZodBoolean;
+        }, z.core.$strip>>;
+        axWedge: z.ZodOptional<z.ZodLazy<z.ZodObject<{
+            restarts: z.ZodNumber;
+            maxRestarts: z.ZodNumber;
+            recovering: z.ZodBoolean;
+            checked: z.ZodOptional<z.ZodEnum<{
+                failed: "failed";
+                restarted: "restarted";
+                "not-wedged": "not-wedged";
+            }>>;
+            last: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                outcome: z.ZodLiteral<"restarted">;
+                agoMs: z.ZodNumber;
+                ms: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>, z.ZodObject<{
+                outcome: z.ZodLiteral<"not-wedged">;
+                agoMs: z.ZodNumber;
+            }, z.core.$loose>, z.ZodObject<{
+                outcome: z.ZodLiteral<"failed">;
+                agoMs: z.ZodNumber;
+                error: z.ZodString;
+            }, z.core.$loose>], "outcome">>;
+        }, z.core.$loose>>>;
         state: z.ZodOptional<z.ZodString>;
         uptimeMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>;
@@ -383,6 +476,19 @@ export declare const opSchemas: {
             from: z.ZodString;
             to: z.ZodString;
             reason: z.ZodString;
+            stall: z.ZodOptional<z.ZodObject<{
+                stage: z.ZodString;
+                readMs: z.ZodOptional<z.ZodNumber>;
+                deadlineMs: z.ZodOptional<z.ZodNumber>;
+                guestAgeMs: z.ZodOptional<z.ZodNumber>;
+                cold: z.ZodBoolean;
+                cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+                probes: z.ZodNumber;
+                recycles: z.ZodOptional<z.ZodNumber>;
+                recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+                axWedge: z.ZodOptional<z.ZodString>;
+                axWedgeRestarts: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
         }, z.core.$strip>>;
         target: z.ZodOptional<z.ZodObject<{
             pid: z.ZodNumber;
@@ -448,6 +554,28 @@ export declare const opSchemas: {
     readonly terminate: z.ZodObject<{
         terminated: z.ZodBoolean;
     }, z.core.$loose>;
+    readonly axWedge: z.ZodObject<{
+        restarts: z.ZodNumber;
+        maxRestarts: z.ZodNumber;
+        recovering: z.ZodBoolean;
+        checked: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            restarted: "restarted";
+            "not-wedged": "not-wedged";
+        }>>;
+        last: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"restarted">;
+            agoMs: z.ZodNumber;
+            ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>, z.ZodObject<{
+            outcome: z.ZodLiteral<"not-wedged">;
+            agoMs: z.ZodNumber;
+        }, z.core.$loose>, z.ZodObject<{
+            outcome: z.ZodLiteral<"failed">;
+            agoMs: z.ZodNumber;
+            error: z.ZodString;
+        }, z.core.$loose>], "outcome">>;
+    }, z.core.$loose>;
 };
 export type OpDataMap = {
     health: HealthData;
@@ -461,6 +589,7 @@ export type OpDataMap = {
     orientation: OrientationData;
     launch: LaunchData;
     terminate: TerminateData;
+    axWedge: AxWedgeData;
 };
 export type OpData<Op extends string> = Op extends keyof OpDataMap ? OpDataMap[Op] : unknown;
 export declare function hasOpSchema(op: string): op is keyof typeof opSchemas;

package/types/e2e/src/driver/keyboard-state.d.ts

@@ -0,0 +1,9 @@
+import type { Element, Rect, Snapshot } from "./driver.types";
+/**
+ * The on-screen keyboard of a snapshot: the largest `keyboard` element with a frame on the screen. A keyboard slid
+ * off the bottom (iOS keeps the hidden one in the tree) is not on screen.
+ */
+export declare function keyboardElement(snapshot: Snapshot): Element | undefined;
+export declare function keyboardVisible(snapshot: Snapshot): boolean;
+/** The keyboard's frame, or `undefined` when none shows. */
+export declare function keyboardFrame(snapshot: Snapshot): Rect | undefined;

package/types/e2e/src/driver/physical-conditions.d.ts

@@ -1,6 +1,6 @@
 import type { Driver } from "./driver.types";
 /** The condition and setting ops of a `Driver`: each changes the device (or an app's grants) beyond driving its UI. */
-export declare const PHYSICAL_CONDITION_OPS: readonly ["network", "networkFaults", "location", "clock", "permissions", "timezone", "locale", "a11y", "battery", "memoryWarning", "push", "camera"];
+export declare const PHYSICAL_CONDITION_OPS: readonly ["network", "networkFaults", "location", "clock", "permissions", "timezone", "locale", "a11y", "battery", "keyboard", "keyboardState", "memoryWarning", "push", "camera"];
 type PhysicalConditionOps = Pick<Driver, (typeof PHYSICAL_CONDITION_OPS)[number]>;
 /**
  * The condition ops for a physical phone: all `E_UNSUPPORTED`. On a phone they would flip airplane mode (cutting

package/types/e2e/src/driver/read-deadline.d.ts

@@ -0,0 +1,4 @@
+/** Runs `fn` with `remaining` as the deadline of every read made inside it, awaits included. */
+export declare function withReadDeadline<T>(remaining: () => number, fn: () => T): T;
+/** How long the innermost read deadline has left (never negative), or undefined outside one. */
+export declare function readDeadlineRemaining(): number | undefined;

package/types/e2e/src/driver/settle.d.ts

@@ -1,4 +1,4 @@
-import type { Snapshot } from "./driver.types";
+import type { Element, Snapshot } from "./driver.types";
 export type SettleDeps = {
     quietMs: number;
     timeoutMs: number;
@@ -33,11 +33,21 @@ export declare function settleDetailOf(outcome: SettleOutcome): SettleDetail;
 export declare const DEFAULT_SETTLE_QUIET_MS = 250;
 /** How long a settle waits for quiet before it gives up. */
 export declare const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+/**
+ * The shortest window a snapshot-hash settle fallback waits (iOS, and `device.settle` on a driver without one). A navigation push exposes both screens at their final
+ * frames for 300-460 ms before the old one leaves the tree, so two equal reads 250 ms apart can settle on that mixed
+ * tree. The helper's own snapshot fallback (`FrameStability.minQuietMs`) uses the same floor.
+ */
+export declare const HASH_FALLBACK_MIN_QUIET_MS = 500;
+/** The quiet window a hash fallback uses for a caller's `quietMs`. */
+export declare function hashFallbackQuietMs(quietMs: number): number;
 /**
  * Snapshot-hash settle: poll a UI fingerprint until it stays unchanged for `quietMs`
  * (two consecutive equal hashes and ≥ quietMs since the last change), or give up at `timeoutMs`.
  * Side effects are injected so tests drive a fake clock.
  */
 export declare function settleByHash(poll: () => Promise<string>, deps: SettleDeps): Promise<SettleOutcome>;
+/** One element as `(role, identifier, label, value, frame to 1 pt)`: what `snapshotHash` hashes, per node. */
+export declare function elementKey(element: Element): string;
 /** Stable fingerprint over `(role, identifier, label, value, frame)` of every node in preorder. */
 export declare function snapshotHash(snapshot: Pick<Snapshot, "flat">): string;

package/types/e2e/src/errors.d.ts

@@ -1,5 +1,7 @@
 import type { ErrorResult } from "../../types/src/result";
-export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET" | "RUN_FAILED";
+export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET" | "RUN_FAILED"
+/** a read that fell back from its first reader (or came back an empty root) could not confirm the locator either way */
+ | "READ_DEGRADED";
 /** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
 export type E2eErrorShape = {
     code: E2eErrorCode;

package/types/e2e/src/expect/a11y-matchers.d.ts

@@ -28,6 +28,13 @@ export declare class DeviceAssertions {
     toPassA11yAudit(options?: PassA11yAuditOptions): Promise<void>;
     /** An announcement or live-region change whose text contains the string or matches the RegExp arrived (`.not`: none did within the timeout). */
     toHaveAnnounced(expected: TextMatch, options?: AnnouncedOptions): Promise<void>;
+    /**
+     * The on-screen keyboard is up (`.not`: it is gone), read from the accessibility tree. Polls until it holds or
+     * `timeout` (default: the assertion timeout) passes. Under `hardware` mode the keyboard never shows.
+     */
+    toHaveKeyboard(options?: {
+        timeout?: number;
+    }): Promise<void>;
     private failure;
     private run;
 }

package/types/e2e/src/expect/matchers.d.ts

@@ -81,6 +81,11 @@ export declare class LocatorAssertions {
     toHaveCount(expected: number, options?: AssertionOptions): Promise<void>;
     private assert;
     private poll;
+    /**
+     * What one look says about `spec`: a judgement (from the accessibility tree, or from the React tree for a degraded
+     * read it answered), or `unsettled` when the read was degraded and nothing could say whether the locator is there.
+     */
+    private judgeLook;
     /** The screen is rendered here, from the last snapshot read, because only a failure needs the text. */
     private failure;
 }

package/types/e2e/src/index.d.ts

@@ -1,9 +1,10 @@
+export type { KeyboardMode } from "../../core/src/conditions/conditions.types";
 export type { A11yAuditOptions, A11yAuditResult, A11yEvent, A11yEventKind, A11yEventSource, A11yIgnore, A11yIssue, A11yRuleId, A11ySeverity, A11ySource, Announcement, ScreenReaderState, SpokenLine, } from "./a11y/a11y.types";
 export type { OpenOptions, OpenWaitUntil } from "./app";
 export type { CameraFacingChoice, CameraSetOptions, ClockInput, ConditionRun, DeviceCamera, DeviceClock, DeviceLocation, DeviceNetwork, DevicePermissions, Duration, FlapOptions, LocationPoint, NetworkSetOptions, NetworkStatus, RouteOptions, TimelineStepInput, } from "./conditions/device-conditions";
 export type { BiometricState, DeviceBiometrics } from "./device";
 export type { A11yAnnouncement, A11yAnnouncements, A11yAnnouncementsOptions, DeviceA11y, DeviceA11yAuditOptions, DeviceScreenReader, ScreenReaderSpokenOptions, } from "./device-a11y";
-export type { A11yOp, A11yState, CameraState } from "./driver/driver.types";
+export type { A11yOp, A11yState, CameraState, KeyboardResult, KeyboardState } from "./driver/driver.types";
 export { E2eError } from "./errors";
 export type { AnnouncedOptions, PassA11yAuditOptions } from "./expect/a11y-matchers";
 export { expect } from "./expect/expect";

package/types/e2e/src/runner/bridge-evidence.d.ts

@@ -0,0 +1,12 @@
+import type { TestResult } from "./results";
+import type { TraceEvent } from "./trace";
+export type BridgeEvidence = NonNullable<TestResult["bridge"]>;
+/**
+ * Collects an attempt's iOS bridge fallbacks from its spans for `results.jsonl` (`bridge`): reads answered by `ax`
+ * in place of `axbridge`, and failed reads that carried a stall report. A read the bridge answered by pid (frontmost
+ * unresolved) is not one.
+ */
+export declare function bridgeEvidence(): {
+    observe(event: TraceEvent): void;
+    summary(): BridgeEvidence | undefined;
+};

package/types/e2e/src/runner/results.d.ts

@@ -26,6 +26,35 @@ export declare const testResultSchema: z.ZodObject<{
         dir: z.ZodString;
         files: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        fallbacks: z.ZodNumber;
+        first: z.ZodObject<{
+            reason: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            stage: z.ZodOptional<z.ZodString>;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodOptional<z.ZodBoolean>;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodOptional<z.ZodNumber>;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        last: z.ZodObject<{
+            reason: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            stage: z.ZodOptional<z.ZodString>;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodOptional<z.ZodBoolean>;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodOptional<z.ZodNumber>;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
     device: z.ZodObject<{
         udid: z.ZodString;
         platform: z.ZodEnum<{

package/types/e2e/src/screen/actions.d.ts

@@ -39,6 +39,8 @@ export declare function isOnScreen(point: Point, screen: ScreenInfo): boolean;
  * field; Android keeps an input's text in `text`.
  */
 export declare function fieldValue(entry: NodeEntry): string;
+/** User-perceived characters in `text` (what a secure field shows one bullet for). */
+export declare function graphemes(text: string): number;
 /** What one read says a field holds: nothing, text, or (secure fields) a number of hidden characters. */
 export type FieldContent = {
     kind: "empty";
@@ -55,6 +57,11 @@ export type FieldContent = {
  * plain field showing its placeholder cannot be told from one holding that text and reads as `text`.
  */
 export declare function fieldContent(entry: NodeEntry): FieldContent;
+/**
+ * What a fill read-back of a secure field says it holds, given the typed `text`: `text` when it shows one bullet per
+ * character of it (the only check a masked field allows), else its bullets (never the typed text, in a message).
+ */
+export declare function maskedReading(entry: NodeEntry, text: string): string;
 /**
  * Backspaces that empty a field once the caret is at its end: one per character plus a spare. Secure fields are
  * counted by their dots. The fallback for a driver without select-all, and the retry when select-all did not empty

package/types/e2e/src/screen/context.d.ts

@@ -4,7 +4,7 @@ import { E2eError } from "../errors";
 import type { SpanOptions, SpanRunner } from "../runner/span";
 import { type NodeIndex } from "./nodes";
 import { type Clock, type PollResult, type PollStep } from "./poll";
-import { type ReactMatch } from "./react-locator";
+import { type ReactLookup, type ReactMatch } from "./react-locator";
 import type { TextMatch } from "./text";
 /**
  * What `screen` and `Locator` need from the test session. `Session` satisfies it as is; the optional members are
@@ -78,8 +78,6 @@ export declare class Runtime {
     private reactCache;
     /** the index of each snapshot, so a snapshot that several reads share is indexed once */
     private readonly indexed;
-    /** the time before which a degraded look is not retried on its first reader, after that reader failed to answer */
-    private firstReaderRetryAt;
     constructor(host: ScreenHost);
     get clock(): Clock;
     actionTimeout(): number;
@@ -97,14 +95,6 @@ export declare class Runtime {
      * `systemAlerts` on, an alert the screen shows is answered and the screen looked at again.
      */
     tryObserve(options?: ObserveOptions): Promise<Observation>;
-    /**
-     * A snapshot the driver answered from a fallback reader (`Snapshot.fellBackFrom`, iOS `ax` after `axbridge` stalled)
-     * can lack what the first reader has: React Native testIDs on static text. Such a look is read once more on the
-     * first reader, and that read replaces it when it answers. When it does not (the guest is still silent) the
-     * fallback snapshot stands and the first reader is left alone for `FIRST_READER_RETRY_MS`, so a dead guest costs a
-     * poll one deadline, not one per attempt. Every locator and matcher looks through here, so none needs its own rule.
-     */
-    private restoreDegraded;
     /** What came before `look`, given the cache's answer from just before it was taken. */
     private earlierThan;
     /** Whether `snapshot` showed an alert that has now been answered. A screen without one costs no extra read. */
@@ -124,6 +114,13 @@ export declare class Runtime {
      * Empty without devtools. Reads are throttled: inside the window the previous answer for the same query is reused.
      */
     reactMatches(testId: TextMatch, observed: Observed): Promise<ReactMatch[]>;
+    /** Whether the host has devtools to ask the React tree through. */
+    hasReactTree(): boolean;
+    /**
+     * `reactMatches`, keeping "the React tree could not be read" (`answered: false`, also without devtools) apart from
+     * "it has no such component", for a degraded read that must not take the first for the second.
+     */
+    reactLookup(testId: TextMatch, observed: Observed): Promise<ReactLookup>;
     /**
      * The interactive part of the tree as text, for failure messages. It indexes the snapshot again and renders up to
      * `EXCERPT_LINES` lines, so call it only once an error is certain; keep the snapshot, not this text, while polling.
@@ -131,7 +128,9 @@ export declare class Runtime {
     excerpt(snapshot: Snapshot): string;
     /**
      * `poll` on this runtime's clock and abort signal; an abort throws instead of returning. `intervalMs` is a fixed gap
-     * between attempts instead of the back-off schedule.
+     * between attempts instead of the back-off schedule. The poll's deadline is the read deadline of every driver read
+     * made inside it (`withReadDeadline`), so a read that waits for the device (the cold iOS bridge) stops with it; a
+     * poll inside another keeps the nearer deadline.
      */
     poll<T, S>(step: (attempt: number) => Promise<PollStep<T, S>> | PollStep<T, S>, timeoutMs: number, options?: {
         intervalMs?: number;

package/types/e2e/src/screen/degraded-read.d.ts

@@ -0,0 +1,23 @@
+import type { Snapshot, SnapshotBackend } from "../driver/driver.types";
+import { E2eError } from "../errors";
+/**
+ * Why a snapshot cannot say a node is absent: it was answered by a fallback reader (`Snapshot.fellBackFrom`, iOS `ax`
+ * after `axbridge` stalled, which drops React Native testIDs on static text), or it is one childless root with no
+ * area (the reader could not see into the app). A match found on such a snapshot is real; a missing one is unknown.
+ */
+export type DegradedRead = {
+    kind: "fallback";
+    from: SnapshotBackend;
+    backend: SnapshotBackend;
+} | {
+    kind: "emptyRoot";
+    backend: SnapshotBackend;
+};
+/** What makes `snapshot` inconclusive about absence; undefined for a whole read. */
+export declare function degradedRead(snapshot: Snapshot): DegradedRead | undefined;
+/** One phrase naming what was degraded, with the fallback and read backend. */
+export declare function describeDegraded(read: DegradedRead): string;
+/** Why the React tree did not settle it. */
+export type ReactNote = "unanswered" | "no-devtools" | "not-testid";
+/** `READ_DEGRADED`: the bridge is degraded and `locator` could be confirmed neither present nor absent in `waitedMs`. */
+export declare function degradedFailure(locator: string, read: DegradedRead, waitedMs: number, react: ReactNote, screen?: string): E2eError;

package/types/e2e/src/screen/keyboard-cover.d.ts

@@ -0,0 +1,26 @@
+import type { Driver, DriverResult, Point, Rect, Snapshot } from "../driver/driver.types";
+import type { NodeEntry } from "./nodes";
+export type Cover = {
+    /** the keyboard's top edge */
+    top: number;
+    /** the free part of the nearest scroll container (its frame down to the keyboard), when the target sits in one */
+    scroller?: Rect;
+    /** points the content has to move up to clear the keyboard with a margin */
+    shift: number;
+};
+/** Whether `point` is under the keyboard of `snapshot`, and how to get clear of it; undefined when it is not. */
+export declare function coverOf(entry: NodeEntry, point: Point, snapshot: Snapshot): Cover | undefined;
+/**
+ * The finger path that moves the content of `scroller` up by about `shift` points (a shorter one when the free part
+ * is not that tall: the caller looks again and swipes again).
+ */
+export declare function scrollPath(scroller: Rect, shift: number): {
+    from: Point;
+    to: Point;
+};
+export declare const COVER_SCROLL_SWIPE: {
+    durationMs: number;
+    momentum: boolean;
+};
+/** Dismisses the keyboard the way `device.hideKeyboard()` does: iOS resigns the first responder (no Return), Android presses back. */
+export declare function dismissKeyboard(driver: Driver): DriverResult<void>;

package/types/e2e/src/screen/locator.d.ts

@@ -1,10 +1,13 @@
 import type { KeyName, Modifier, Point, Rect } from "../driver/driver.types";
+import { E2eError } from "../errors";
 import { type Momentum, type SwipeDirection } from "./actions";
 import type { Observed, Runtime } from "./context";
+import { type DegradedRead, type ReactNote } from "./degraded-read";
 import { type FillVia } from "./field";
 import type { NodeEntry } from "./nodes";
 import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
 import { type LocatorExpression } from "./query";
+import { type ReactMatch } from "./react-locator";
 import type { QueryRole } from "./roles";
 import { type TextMatch } from "./text";
 export type ActionOptions = {
@@ -69,6 +72,21 @@ export type WaitState = "attached" | "detached" | "visible" | "hidden";
 export type WaitForOptions = ActionOptions & {
     state?: WaitState;
 };
+/**
+ * What one look says about a locator. `nodes`: the accessibility tree's answer (none included, when the read was whole
+ * or the React tree confirmed the absence). `react`: the read was degraded and the React tree has the component(s).
+ * `unknown`: the read was degraded (`screen/degraded-read.ts`) and nothing could confirm the locator either way.
+ */
+export type Resolved = {
+    kind: "nodes";
+    entries: NodeEntry[];
+} | {
+    kind: "react";
+    matches: ReactMatch[];
+} | {
+    kind: "unknown";
+    read: DegradedRead;
+};
 declare const LOCATOR_BRAND: unique symbol;
 /** Whether `value` is a `Locator` (also across duplicated copies of this module, e.g. the bundled entry and the preload). */
 export declare function isLocator(value: unknown): value is Locator;
@@ -102,7 +120,29 @@ export declare class Locator {
         entries: NodeEntry[];
         observed: Observed;
     }>;
+    /**
+     * What `observed` says about this locator. A whole read, or one with matches, is the accessibility tree's answer. A
+     * degraded read with no match is asked of the React tree (plain `getByTestId` with devtools): it answers presence or
+     * absence; otherwise the look is `unknown`, and no caller may take it as "absent". A component whose rect is an
+     * accessibility node's (the fallback reader kept the node, dropped the testID) resolves to that node, so text,
+     * visibility and actions read it like any match; one with no such node stays a React-only match.
+     */
+    resolveIn(observed: Observed): Promise<Resolved>;
+    /** Why the React tree did not settle a degraded look, for the `READ_DEGRADED` message. */
+    reactNote(): ReactNote;
+    /** `READ_DEGRADED` for this locator after `waitedMs`, with the screen of the last degraded look. */
+    degradedFailure(read: DegradedRead, waitedMs: number, snapshot: Observed["snapshot"] | undefined): E2eError;
+    /**
+     * One look that settles this locator. A whole read answers at once (never waits); a degraded one that cannot say
+     * whether the locator is there is looked at again until one can, within the action timeout (`quick`: within
+     * `QUICK_CHECK_WINDOW_MS`, for checks a spec branches on), then `READ_DEGRADED`.
+     */
+    private conclusive;
+    /** The conclusive answer of `observed`, or undefined while it is `unknown`. */
+    private settled;
     private matches;
+    /** The one React match a read of a component the accessibility tree lacks stands for; several are ambiguous. */
+    private reactOnly;
     private single;
     /** Components of the React tree that this locator names, when it is a plain `getByTestId` and the app has devtools. */
     private reactCandidates;
@@ -113,6 +153,8 @@ export declare class Locator {
     all(): Promise<Locator[]>;
     text(): Promise<string>;
     allTexts(): Promise<string[]>;
+    /** The text the React tree reported for a component of a degraded read that no accessibility node stands for. */
+    private reactText;
     value(): Promise<string>;
     isVisible(): Promise<boolean>;
     /**
@@ -124,7 +166,11 @@ export declare class Locator {
      */
     read(): Promise<LocatorReading>;
     /** Whether this locator's one match is visible in `observed`; no match is not visible, several matches throw. */
-    visibleIn(observed: Observed): boolean;
+    /**
+     * Whether `observed` shows this locator, without waiting: a degraded read is resolved like `resolveIn` (the React
+     * tree's node or rect), and one nothing could settle counts as not shown yet.
+     */
+    shownIn(observed: Observed): Promise<boolean>;
     isHidden(): Promise<boolean>;
     isEnabled(): Promise<boolean>;
     isChecked(): Promise<boolean>;
@@ -174,6 +220,13 @@ export declare class Locator {
      * the kept snapshot sits outside the app, where the app-scoped hit-test may not see it, and the fresh look answers it.
      */
     private aimFromKept;
+    /**
+     * A target under the on-screen keyboard (the default `software` mode keeps it up) would get the touch on a key. In a
+     * scroll container it is scrolled into the free part of the screen (at most `MAX_COVER_SCROLLS` swipes, each looked at
+     * fresh); otherwise, or when scrolling does not clear it, the keyboard is dismissed once (`dismissKeyboard`). Either way
+     * the match is looked at again, and whatever that look shows is what the action uses: no retry.
+     */
+    private clearOfKeyboard;
     /**
      * Taps the one visible, enabled match. With `until` it is also the retrying tap: the press on a tab bar or a list row
      * right after a navigation is sometimes dropped with nothing on screen to tell, so it checks that `until` shows
@@ -181,9 +234,10 @@ export declare class Locator {
      */
     tap(options?: TapOptions): Promise<void>;
     /**
-     * One press; resolves to the snapshot it aimed from (the screen just before the press). A plain tap may aim from the
-     * kept snapshot (`aimFromKept`); a tap with `until` takes a fresh look, since the screen it aimed from is what the
-     * checks compare against to tell the press landed, and an older one could differ only because it was older.
+     * One press; resolves to the snapshot it aimed from (the screen just before the press) and the element pressed (none
+     * for a match only the React tree knows). A plain tap may aim from the kept snapshot (`aimFromKept`); a tap with
+     * `until` takes a fresh look, since the screen it aimed from is what the checks compare against to tell the press
+     * landed, and an older one could differ only because it was older.
      */
     private tapOnce;
     /**
@@ -191,9 +245,9 @@ export declare class Locator {
      * (`driver.tap` returns once the HID press is over, ~85 ms, and an AX read queues behind the app's main thread, so
      * that look usually already shows the screen the press made; measured: holding it back to `pollMs` saved no read
      * and cost 250 ms a press). A locator is checked on the snapshot of
-     * the poll itself, which is also compared with `pressedOn` (the hash of the screen the press aimed from): once the
-     * screen changed the press landed, so it is never sent again (`landed`, even when `until` is late); a screen still
-     * unchanged on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
+     * the poll itself, which is also compared with the screen the press aimed from (`reacted`): once the screen reacted
+     * the press landed, so it is never sent again (`landed`, even when `until` is late); a screen that has not reacted
+     * on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
      * is called with the kept snapshot forgotten (after the first check), so its own reads take one new snapshot
      * between them rather than the previous check's; it gets the whole window.
      */

package/types/e2e/src/screen/react-locator.d.ts

@@ -11,17 +11,32 @@ export type ReactMatch = {
     testId: string;
     /** the component's name (`View`, `Button`, ...) */
     name: string;
+    /** the strings rendered inside it, when the React tree reported any */
+    text?: string;
 };
 export type ReactView = {
     platform: Platform;
     screen: ScreenInfo;
 };
+/** What the React tree said: `answered: false` when it could not be read (no devtools, a failed or timed-out read). */
+export type ReactLookup = {
+    answered: true;
+    matches: ReactMatch[];
+} | {
+    answered: false;
+};
 /**
  * Components of the running app whose `testID` matches, with rects in the driver's pixels. This is the fallback for
  * `getByTestId` when the platform hides the view from accessibility (React Native only exposes `testID` to
- * accessibility on some views). Any devtools failure means "nothing found", so callers keep their own not-found
- * error. Android measures in dp but the driver taps in px: `view.screen.scale` converts.
+ * accessibility on some views), and the second opinion on a degraded read. A devtools failure is `answered: false`,
+ * kept apart from an empty answer so a caller can tell "absent" from "cannot tell". Android measures in dp but the
+ * driver taps in px: `view.screen.scale` converts.
  */
+export declare function lookUpTestIdViaReact(facet: Pick<DevtoolsFacet, "tree">, testId: TextMatch, view: ReactView, options?: {
+    screenName?: string;
+    timeoutMs?: number;
+}): Promise<ReactLookup>;
+/** `lookUpTestIdViaReact` where any failure means "nothing found", so callers keep their own not-found error. */
 export declare function locateByTestIdViaReact(facet: Pick<DevtoolsFacet, "tree">, testId: TextMatch, view: ReactView, options?: {
     screenName?: string;
     timeoutMs?: number;

package/types/e2e/src/screen/react-merge.d.ts

@@ -0,0 +1,10 @@
+import type { NodeEntry, NodeIndex } from "./nodes";
+import type { ReactMatch } from "./react-locator";
+/**
+ * The accessibility node a React component stands for on a degraded read: a fallback reader (iOS host `ax`) keeps the
+ * node but drops its testID, so the component's rect is what ties the two. Never a node that carries another testID,
+ * never an area-less rect. Several nodes with the rect: the one whose own text is the component's, else the deepest.
+ */
+export declare function nodeOfReactMatch(match: ReactMatch, index: NodeIndex): NodeEntry | undefined;
+/** The node of every match, each a different node; undefined when one of them has none (the React tree answers alone). */
+export declare function mergeReactMatches(matches: readonly ReactMatch[], index: NodeIndex): NodeEntry[] | undefined;