@delacour/warden-e2e 0.6.0 → 0.8.0

package/types/e2e/src/driver/a11y-events.d.ts

@@ -0,0 +1,30 @@
+import type { Result } from "../../../types/src/result";
+import type { A11yEvent, A11yEventSource } from "../a11y/a11y.types";
+import type { Driver, DriverResult } from "./driver.types";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `ReadsA11y`): the announcements, live-region
+ * changes and screen/layout notifications an app emitted since `since`. `cursor` is opaque to callers: pass the last
+ * one back to get only what is new (Android: the server's sequence number; iOS: a byte offset into the inject events
+ * file). `since` omitted reads from the start. `lost` is set when the Android ring overwrote events the caller never saw.
+ * iOS needs the app launched with the injected library (`WARDEN_A11Y=1` / the `a11y` option) and answers
+ * `E_UNSUPPORTED` otherwise.
+ */
+export type A11yEventsRead = {
+    events: A11yEvent[];
+    cursor: number;
+    lost?: boolean;
+};
+export type ReadsA11yEvents = {
+    a11yEvents(since?: number): DriverResult<A11yEventsRead>;
+};
+export declare function canReadA11yEvents(driver: Driver): driver is Driver & ReadsA11yEvents;
+export declare function parseA11yEvent(value: unknown, source: A11yEventSource): A11yEvent | undefined;
+/** The `a11yEvents` reply of `warden-uiad`: `{events:[{kind,text,at}], cursor, lost?}`. */
+export declare function parseUiadA11yEvents(data: unknown): Result<A11yEventsRead, string>;
+/**
+ * The injected library's `<state>.events` file (JSON lines, append-only) from byte offset `since`. Only lines that end
+ * in a newline count: a half-written tail stays unread and the returned cursor stops before it, so the next read
+ * starts there. A malformed complete line is skipped (the cursor moves past it). A `since` beyond the file (the file
+ * was reset by a relaunch) restarts from 0.
+ */
+export declare function parseInjectEvents(text: string, since?: number): A11yEventsRead;

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

@@ -0,0 +1,12 @@
+import type { Driver, DriverResult, Snapshot } from "./driver.types";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `RepeatingKeys` in `typing.ts`): read the
+ * screen-reader facts a plain snapshot lacks and return the snapshot with `Element.a11y` filled in. iOS: the injected
+ * dylib's UIKit walk merged by identifier / frame (`ios/ios-a11y.ts`); needs the app launched with the dylib
+ * (`WARDEN_A11Y=1` or the `a11y` driver option) and answers `E_UNSUPPORTED` otherwise. Android has no such driver
+ * method: `warden-uiad` snapshots carry `a11y` already.
+ */
+export type ReadsA11y = {
+    readA11y(snapshot: Snapshot): DriverResult<Snapshot>;
+};
+export declare function canReadA11y(driver: Driver): driver is Driver & ReadsA11y;

package/types/e2e/src/driver/android/android-animations.d.ts

@@ -12,6 +12,8 @@ import { type AndroidStateStore } from "./android-state";
 export type AnimationGuard = {
     /** put the scales back (once); a restore that fails leaves the saved originals for the next driver */
     restore(): Promise<void>;
+    /** the transition scale the device had before it was zeroed (`"null"` = never set); undefined when it was off already */
+    transitionOriginal(): string | undefined;
 };
 export type AnimationDeps = {
     session: AdbSession;
@@ -25,5 +27,10 @@ export type AnimationDeps = {
 /**
  * One shell round trip that reads the three scales and sets them to 0, then (when something has to be put
  * back) saves the originals. Never fails the open: a device that refuses just keeps its animations.
+ *
+ * The transition scale is the exception: RN (0.86) reads it as "reduce motion", and zero would make every app
+ * under test report reduce-motion on. It goes straight back to the device's own value, so only the window and
+ * animator scales stay at 0 (those are what makes the run fast and stable); `a11y({ reduceMotion: true })` zeroes it
+ * on request.
  */
 export declare function disableAnimations(deps: AnimationDeps): Promise<AnimationGuard>;

package/types/e2e/src/driver/android/android-app.d.ts

@@ -9,6 +9,10 @@ export type AppDeps = {
     log?: Logger;
     /** the app under test: `openUrl` is addressed to it (`am start -p`) so no other handler or chooser can take the link */
     appPackage?: string;
+    /** a real phone: `uninstall` and `clearData` only touch `appPackage` and `ownedPackages` (`E_REFUSED` otherwise) */
+    physical?: boolean;
+    /** packages warden installed on this device besides `appPackage` */
+    ownedPackages?: readonly string[];
     /** how long `am start -W` may wait for the first frame (default `START_WAIT_TIMEOUT_MS`); tests shorten it */
     startWaitTimeoutMs?: number;
     /** how long the `pidof` after a timed-out start may take (default `START_PROBE_TIMEOUT_MS`); tests shorten it */

package/types/e2e/src/driver/android/android-argv.d.ts

@@ -1,3 +1,4 @@
+import type { LatLon } from "../../../../core/src/conditions/conditions.types";
 import type { Result } from "../../../../types/src/result";
 import type { DriverError, HardwareButton, KeyName, Point } from "../driver.types";
 import type { GesturePlan } from "../gesture-geometry";
@@ -14,6 +15,13 @@ export type MotionAction = "DOWN" | "MOVE" | "UP" | "CANCEL";
 export declare function motionEventArgv(action: MotionAction, point: Point): string[];
 /** Lowest sdk with `input motionevent` (Android 8.0). */
 export declare const MOTIONEVENT_MIN_SDK = 26;
+/** Host-side `adb -s <serial> emu finger touch <id>`: the emulator console presents fingerprint `id` to the sensor. */
+export declare function emuFingerTouchArgv(adb: string, serial: string, fingerId: number): string[];
+/** An id no enrollment holds: the emulator reports a non-matching touch. */
+export declare const UNENROLLED_FINGER_ID = 99;
+export declare function dumpsysFingerprintArgv(): string[];
+/** Emulator serials (`emulator-5554`); the console commands exist nowhere else. */
+export declare const isEmulatorSerial: (serial: string) => boolean;
 /** `input keycombination` (and so select-all by Ctrl+A) exists from Android 13. */
 export declare const SELECT_ALL_MIN_SDK = 33;
 export declare const DRAG_STEPS = 8;
@@ -85,6 +93,8 @@ export declare function animationScaleArgvs(): string[][];
 export declare function animationReadArgvs(): string[][];
 /** Put saved scales back: a value is `put` again, a setting that was never set (`null`) is deleted. */
 export declare function animationRestoreArgvs(values: AnimationValues): string[][];
+/** Put just the transition scale back (a setting that was never set, `null`, is deleted). */
+export declare function transitionRestoreArgv(value: string): string[];
 /** Host argv: `adb -s <serial> exec-out screencap -p` (binary PNG on stdout). */
 export declare function screencapArgv(adb: string, serial: string): string[];
 /** `getprop <key>` (boot flag, sdk level, model). */
@@ -104,6 +114,17 @@ export declare function dumpTtyHostArgv(adb: string, serial: string): string[];
 export declare function dumpFileCommand(path?: string): string;
 /** Host argv: `adb -s <serial> install -r <apk>`. */
 export declare function installArgv(adb: string, serial: string, apkPath: string): string[];
+/**
+ * Host argv: `adb -s <serial> emu geo fix <lon> <lat> [alt]`. The emulator console takes LONGITUDE first,
+ * the reverse of `simctl location set lat,lon` and of everything else here.
+ */
+export declare function geoFixArgv(adb: string, serial: string, point: LatLon, altM?: number): string[];
+/** `adb emu` exits 0 even when the console answers `KO: …`; the reason, or undefined when it took. */
+export declare function geoFixFailure(res: {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}): string | undefined;
 export declare function uninstallArgv(adb: string, serial: string, packageName: string): string[];
 /** Exit 0 and `package:/…` when installed, exit 1 and nothing otherwise. */
 export declare function pmPathArgv(packageName: string): string[];

package/types/e2e/src/driver/android/android-camera-host.d.ts

@@ -0,0 +1,23 @@
+import { type Exec } from "../../../../core/src/exec";
+import type { DeviceProvider } from "../../../../core/src/providers/provider.types";
+import type { Store } from "../../../../core/src/store";
+import { type Result } from "../../../../types/src/result";
+import type { AndroidCameraDeps } from "./android-camera";
+export type AndroidCameraHostOptions = {
+    serial: string;
+    env?: Record<string, string | undefined>;
+    exec?: Exec;
+    now?: () => number;
+    /** the lease store (default: the process's shared connection) */
+    store?: () => Result<Store>;
+    /** the Android provider (default: a real one on `adb` / `emulator`) */
+    provider?: (store: Store) => DeviceProvider;
+};
+/** What `createAndroidCamera` needs from warden's state: the device's recorded profile, a restart, the lease record. */
+export type AndroidCameraHost = Pick<AndroidCameraDeps, "profile" | "relaunch"> & Required<Pick<AndroidCameraDeps, "record">>;
+/**
+ * The camera driver's view of warden's store and provider, opened lazily: a run that never touches the camera never
+ * opens either. The profile (`<avd>+cam`) is what the claim recorded for the serial; a restart goes through the same
+ * provider that launched the emulator, so the serial, console port, device record and lease stay.
+ */
+export declare function createAndroidCameraHost(options: AndroidCameraHostOptions): AndroidCameraHost;

package/types/e2e/src/driver/android/android-camera.d.ts

@@ -0,0 +1,28 @@
+import { type CameraCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Exec } from "../../../../core/src/exec";
+import type { Driver } from "../driver.types";
+export type AndroidCameraDeps = {
+    serial: string;
+    wardenHome: string;
+    /** host process runner: `sips` re-encodes images to PNG */
+    exec: Exec;
+    /** the profile warden recorded for this device (`pixel-10+cam`); undefined = not a warden device */
+    profile: () => string | undefined;
+    /** restart the emulator on its own serial through the provider and wait until it is ready */
+    relaunch: () => Promise<{
+        success: true;
+        data: undefined;
+    } | {
+        success: false;
+        error: string;
+    }>;
+    /** told the feeds now playing, so the lease carries the `camera` area and release undoes it */
+    record?: (feeds: CameraCondition) => void;
+};
+/**
+ * The Android emulator camera. `-camera-back` / `-camera-front` name a file the emulator re-reads whenever an app
+ * opens the camera, so an image swap is an atomic file replace (`appliesOnCameraOpen`). Only PNG renders, so every
+ * other image is re-encoded with `sips`. The source TYPE (image or video) is fixed at launch: a change of it is
+ * recorded in `mode.json` and the emulator is restarted on the same serial (`rebooted`).
+ */
+export declare function createAndroidCamera(deps: AndroidCameraDeps): Driver["camera"];

package/types/e2e/src/driver/android/android-clock.d.ts

@@ -0,0 +1,28 @@
+import type { ClockCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Exec } from "../../../../core/src/exec";
+import type { ClockState, DriverResult } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+/**
+ * Android mock clock: system time, device-wide. `settings put global auto_time 0` stops the network time sync from
+ * undoing it, `cmd alarm set-time <epoch ms>` sets it (a shell-uid command on emulator images, verified on the
+ * device's own `date`); where that does not take, `adb root` + `date -s @<secs>`. `real` is the undo in
+ * `core/conditions/undo.ts`: `auto_time 1` then the host's time. There is no way to freeze Android's clock, so
+ * `frozen` is `E_UNSUPPORTED`. Monotonic clocks are not affected by a wall-clock set.
+ */
+export declare const AUTO_TIME_OFF_ARGV: readonly string[];
+export declare const AUTO_TIME_ON_ARGV: readonly string[];
+export declare const DATE_ARGV: readonly string[];
+export declare const setTimeArgv: (epochMs: number) => string[];
+/** How far the device's `date` may be from the target (it only reports whole seconds, and a call takes time). */
+export declare const CLOCK_TOLERANCE_MS = 5000;
+export type AndroidClockDeps = {
+    session: AdbSession;
+    /** host runner for the `adb root` fallback */
+    exec: Exec;
+    adb: string;
+    serial: string;
+    /** host wall time, ms (default `Date.now`) */
+    wallNow?: () => number;
+};
+/** Put the emulator's wall clock at `condition`; reads it back and fails with `E_IO` when it did not move. */
+export declare function applyAndroidClock(deps: AndroidClockDeps, condition: ClockCondition): DriverResult<ClockState>;

package/types/e2e/src/driver/android/android-device.d.ts

@@ -1,6 +1,7 @@
 import type { DriverResult, Logger, Orientation, ScreenInfo } from "../driver.types";
 import type { AdbSession } from "./adb-session";
 import { type RotationValue } from "./android-argv";
+import { type PhoneFacts } from "./android-phone";
 /** Device facts read once at open: boot flag, screen size/density. Pure parsers + small session helpers. */
 export declare const BOOT_TIMEOUT_MS = 30000;
 export type Clock = {
@@ -15,11 +16,18 @@ export declare function parseWmSize(text: string): {
 } | undefined;
 /** `wm density`: `Physical density: 420` / `Override density: 320`; scale = dpi / 160. */
 export declare function parseWmDensity(text: string): number | undefined;
+/**
+ * The probe for `serial`. A console `emulator-N` is an emulator by construction. Anything else (a phone, or a
+ * network emulator) also reads the qemu props, wakefulness and keyguard, in the same round trip.
+ */
+export declare function bootProbeFor(serial: string): string;
 /** The sdk level on the probe's second line, if numeric. */
 export declare function sdkFromProbe(stdout: string): number | undefined;
+/** `physical`: set only for a real phone (its qemu props are empty); an emulator, or an unprobed serial, has none. */
 export type BootInfo = {
     screen: ScreenInfo | undefined;
     sdk: number | undefined;
+    physical: PhoneFacts | undefined;
 };
 /** The screen out of a boot probe's output, if `wm` answered. */
 export declare function screenFromProbe(stdout: string): ScreenInfo | undefined;

package/types/e2e/src/driver/android/android-driver.d.ts

@@ -1,6 +1,11 @@
 import type { Exec } from "../../../../core/src/exec";
+import type { ConditionSink } from "../../conditions/condition-events";
+import { type TickerClock } from "../../conditions/route-ticker";
+import type { ClockRecorder } from "../clock-recorder";
 import type { Driver, DriverResult, Element, Logger, Point, ScreenInfo } from "../driver.types";
+import type { NetworkProxyPort } from "../network-proxy";
 import { type SpawnAdb } from "./adb-session";
+import { type AndroidCameraHost } from "./android-camera-host";
 import { type Clock } from "./android-device";
 import { type DumpRoute } from "./android-dump";
 import { type AndroidStateStore } from "./android-state";
@@ -23,6 +28,10 @@ export type AndroidDriverOptions = {
     /** override how the resident shell is spawned (tests) */
     spawn?: SpawnAdb;
     log?: Logger;
+    /** the lease's shaping proxy: loss and per-host faults route through it (`createAndroidNetwork`); without it loss stays in `needsProxy` */
+    networkProxy?: NetworkProxyPort;
+    /** told about every successful `clock` op, so the lease records the `clock` area (`leaseClockRecorder`) */
+    clockRecorder?: ClockRecorder;
     /** skip `wm size`/`wm density` */
     screen?: ScreenInfo;
     /** binary runner for screenshots, default {@link bunExecBinary} */
@@ -40,6 +49,11 @@ export type AndroidDriverOptions = {
     state?: AndroidStateStore;
     /** the app under test: `app.openUrl` is addressed to it (`am start -p`), so no other app or chooser takes the link */
     appPackage?: string;
+    /**
+     * Packages besides `appPackage` that warden installed on this device (the `installs` table). On a physical phone
+     * only these may be uninstalled or have their data cleared; anything else is `E_REFUSED` (`physical_protected`).
+     */
+    ownedPackages?: readonly string[];
     /** how long to wait for `sys.boot_completed`, default 30 s */
     bootTimeoutMs?: number;
     /**
@@ -48,6 +62,14 @@ export type AndroidDriverOptions = {
      * (a fake spawn, a fake dex push) a test replaces. API 26 and up only.
      */
     uiad?: boolean | UiadOptions;
+    /** pacing of in-process location routes (default real time); tests pass a fake */
+    tickerClock?: TickerClock;
+    /** told about every network flap transition (the `condition` events of `results.jsonl`) */
+    conditionSink?: ConditionSink;
+    /** warden's home, where a camera emulator's feeds live (default `$WARDEN_HOME`, else `~/.warden`) */
+    wardenHome?: string;
+    /** the camera op's view of warden's store and provider (default: the real ones, opened on first use) */
+    cameraHost?: AndroidCameraHost;
 };
 /** Deepest hittable element containing `point` (later in preorder wins ties: drawn on top); else deepest any. */
 export declare function elementAt(flat: readonly Element[], point: Point): Element | null;

package/types/e2e/src/driver/android/android-network.d.ts

@@ -0,0 +1,66 @@
+import type { NetworkCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Exec } from "../../../../core/src/exec";
+import type { Driver, DriverResult, NetworkState } from "../driver.types";
+import { type NetworkProxyPort } from "../network-proxy";
+import type { AdbSession } from "./adb-session";
+import type { Clock } from "./android-device";
+/**
+ * Android native network conditions. Speed and delay go to the emulator console (`adb emu network ...`, host
+ * side); online/offline is airplane mode (`cmd connectivity`, falling back to `svc wifi|data`). Every switch is
+ * verified against what `dumpsys connectivity` reports, polled on the injected clock, before it returns.
+ * Loss, per-host faults and flapping are not native: loss is reported in `needsProxy` (COND-4), the rest never
+ * reach this driver.
+ */
+/** Longest wait for the OS to agree with one switch. */
+export declare const NETWORK_VERIFY_MS = 10000;
+export declare const DUMPSYS_CONNECTIVITY_ARGV: readonly string[];
+/** Host argv: `adb -s <serial> emu network speed|delay <value>`. */
+export declare function emuNetworkArgv(adb: string, serial: string, what: "speed" | "delay", value: string): string[];
+/** Device shell argv. */
+export declare function airplaneArgv(enable: boolean): string[];
+/** Device shell argvs: the radios by hand, for images whose `cmd connectivity` has no airplane-mode. */
+export declare function svcArgvs(enable: boolean): string[][];
+/** The emulator console answers `KO: ...` with exit code 0 on a bad argument. */
+export declare function emuReplyError(stdout: string): string | undefined;
+/**
+ * The default network out of `dumpsys connectivity`: its header line is `Active default network: 101` while a
+ * network is up and `Active default network: none` when airplane mode or disabled radios took it away. Anything
+ * else (a service that is not there, truncated output) is unreadable.
+ */
+export declare function parseActiveNetwork(dump: string): {
+    online: boolean;
+    netId?: number;
+} | undefined;
+export type AndroidNetworkDeps = {
+    session: AdbSession;
+    /** host runner for `adb emu` */
+    exec: Exec;
+    adb: string;
+    serial: string;
+    clock: Clock;
+};
+/**
+ * Put the emulator's network into `condition`. Offline: airplane mode (radios off by `svc` where the image has no
+ * airplane command). Anything else: back online first, then the preset's / custom speed and delay on the console.
+ * Physical devices have no console. `flap` is the scheduler's: the driver wraps this.
+ */
+export declare function applyAndroidNetwork(deps: AndroidNetworkDeps, condition: NetworkCondition): DriverResult<NetworkState>;
+/** The emulator's alias for the host's loopback: a proxy bound to 127.0.0.1 on the host answers here. */
+export declare const EMULATOR_HOST_ALIAS = "10.0.2.2";
+/** Device shell argv: point the system HTTP(S) proxy at `value` (`host:port`, or `:0` to clear). */
+export declare function httpProxyPutArgv(value: string): string[];
+export declare const HTTP_PROXY_GET_ARGV: readonly string[];
+/**
+ * Android network conditions, native first: speed, delay and offline stay on the emulator (`applyAndroidNetwork`).
+ * What the console cannot do, packet loss and per-host faults, goes through the lease's shaping proxy: the system
+ * `http_proxy` setting points at it (`10.0.2.2:<port>`) and the proxy applies only `lossPct` and the faults, so the
+ * native delay and bandwidth are not applied twice. Apps that honour the system proxy (OkHttp, HttpURLConnection,
+ * Chromium WebView, therefore React Native fetch) are covered; raw sockets and apps that set `Proxy.NO_PROXY` are not.
+ * Without a proxy port a loss stays in `needsProxy`.
+ */
+export declare function createAndroidNetwork(deps: AndroidNetworkDeps & {
+    proxy?: NetworkProxyPort;
+}): {
+    network: Driver["network"];
+    networkFaults: Driver["networkFaults"];
+};

package/types/e2e/src/driver/android/android-phone.d.ts

@@ -0,0 +1,47 @@
+import type { DriverResult, Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import type { Clock } from "./android-device";
+import { type AndroidDeviceState, type AndroidStateStore } from "./android-state";
+/** `ro.boot.qemu` / `ro.kernel.qemu` joined (empty on hardware), the power state and the keyguard, as the tail of the boot probe. */
+export declare const PHONE_PROBE_TAIL: string;
+/** `dumpsys window policy`'s keyguard lines: `showing=true`, `secure=true`. */
+export declare const KEYGUARD_COMMAND = "dumpsys window policy | grep -E 'showing=|secure='";
+/** What the phone-probe tail found out; every field is `undefined` when `dumpsys` printed nothing parseable. */
+export type PhoneFacts = {
+    awake?: boolean;
+    keyguardShowing?: boolean;
+    keyguardSecure?: boolean;
+};
+/**
+ * The phone facts in a boot probe's output, or `undefined` when the probe had no phone tail (a console emulator)
+ * or the qemu props say this is an emulator (`localhost:5555`, Genymotion): not a phone.
+ */
+export declare function parsePhoneFacts(stdout: string): PhoneFacts | undefined;
+/**
+ * Make an attached phone usable, never unlock it: a sleeping one gets `KEYCODE_WAKEUP`; a keyguard without a
+ * credential is dismissed (`wm dismiss-keyguard`); a secure keyguard is `E_DEVICE_LOCKED` (no swipe, no PIN).
+ */
+export declare function preparePhone(session: AdbSession, clock: Pick<Clock, "sleep">, facts: PhoneFacts, log?: Logger): DriverResult<void>;
+export type SettingsGuard = {
+    /** before the first rotation write: save the current rotation settings (once); an error means do not write */
+    beforeRotate(): DriverResult<void>;
+    /** before the first `cmd uimode night` write: save the current mode (once) */
+    beforeAppearance(): DriverResult<void>;
+    /** put everything saved back (once); a failed restore leaves the originals in the state file for the next driver */
+    restore(): Promise<void>;
+};
+export type SettingsGuardDeps = {
+    session: AdbSession;
+    serial: string;
+    sdk: number | undefined;
+    /** originals a process that died left in the state file */
+    pending: Pick<AndroidDeviceState, "rotation" | "uimode">;
+    state?: AndroidStateStore;
+    log?: Logger;
+};
+/**
+ * Rotation (`accelerometer_rotation`, `user_rotation`) and dark mode (`cmd uimode night`) are settings that
+ * outlive the driver. On a phone the originals are read and written to the state file BEFORE the first change
+ * (so a crash cannot lose them) and restored when the driver closes, the way animation scales are.
+ */
+export declare function createSettingsGuard(deps: SettingsGuardDeps): Promise<SettingsGuard>;

package/types/e2e/src/driver/android/android-screen-reader.d.ts

@@ -0,0 +1,23 @@
+import type { Driver } from "../driver.types";
+import type { ActsOnElements } from "../element-actions";
+import type { DrivesScreenReader } from "../screen-reader";
+import type { AdbSession } from "./adb-session";
+import type { Clock } from "./android-device";
+import type { TalkBackControl } from "./android-talkback";
+import type { UiadOps } from "./uiad-ops";
+/**
+ * The Android driver while TalkBack is on (WDN-A11Y, A11Y-7): the `DrivesScreenReader` calls, and the element actions
+ * that replace touches. With TalkBack on a tap only moves its focus and a one-finger swipe navigates, so a locator tap
+ * is `ACTION_CLICK` on the node and a locator scroll is `ACTION_SCROLL_*` on its scrollable (server ops, no touch).
+ * Raw coordinate taps never come through here and stay touches: with TalkBack on they move its focus, and whether that
+ * also activates depends on its "single-tap to activate" setting.
+ */
+export type ScreenReaderDeps = {
+    uiad: UiadOps | undefined;
+    talkback: TalkBackControl;
+    session: AdbSession;
+    clock: Clock;
+    /** a touch, for the focus-then-double-tap fallback */
+    tap: Driver["tap"];
+};
+export declare function createScreenReaderOps(deps: ScreenReaderDeps): DrivesScreenReader & ActsOnElements;

package/types/e2e/src/driver/android/android-settings.d.ts

@@ -0,0 +1,41 @@
+import type { PermissionName, PermissionState } from "../../../../core/src/conditions/conditions.types";
+import type { Driver } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import { type TalkBackControl } from "./android-talkback";
+/** Permission name to the manifest permissions it covers; a name absent here is skipped with the reason in `ANDROID_NO_PERMISSION`. */
+export declare const ANDROID_PERMISSIONS: Partial<Record<PermissionName, readonly string[]>>;
+export declare const ANDROID_NO_PERMISSION: Partial<Record<PermissionName, string>>;
+export declare const permissionArgv: (state: PermissionState, pkg: string, permission: string) => string[];
+/** `unset` also clears the flags a user choice sets, so the app is asked again. */
+export declare const clearPermissionFlagsArgv: (pkg: string, permission: string) => string[];
+export declare const setTimezoneArgv: (tz: string) => string[];
+export declare const TIMEZONE_PROP_ARGV: readonly string[];
+export declare const setAppLocaleArgv: (pkg: string, tag: string | null) => string[];
+export declare const getAppLocaleArgv: (pkg: string) => string[];
+export declare const settingGetArgv: (table: "system" | "secure" | "global", key: string) => string[];
+export declare const BOLD_TEXT_ADJUSTMENT = 300;
+export declare const trimMemoryArgv: (pkg: string) => string[];
+export declare const BATTERY_RESET_ARGV: readonly string[];
+export declare function batteryArgvs(op: {
+    level?: number;
+    charging?: boolean;
+}): string[][];
+export declare const APP_LOCALES_MIN_SDK = 33;
+export type AndroidSettingsDeps = {
+    session: AdbSession;
+    serial: string;
+    /** the session's app package, used when an op names none */
+    appPackage?: string;
+    /** wait between a settings write and its read-back (default `Bun.sleep`) */
+    sleep?: (ms: number) => Promise<void>;
+    /** the host's timezone, restored on `timezone(null)` when no previous one is given (default: `Intl`) */
+    hostTimezone?: () => string;
+    /** the transition animation scale the device had before the driver zeroed it (what `reduceMotion: false` restores); `"null"` / absent = none known */
+    transitionOriginal?: () => string | undefined;
+    /** is `warden-uiad` how this driver reads the screen (TalkBack mode needs it: the dump fallback unbinds TalkBack); default false */
+    uiadAvailable?: () => boolean;
+};
+export type AndroidSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push">;
+export declare function createAndroidSettings(deps: AndroidSettingsDeps): AndroidSettings & {
+    talkback: TalkBackControl;
+};

package/types/e2e/src/driver/android/android-spoken.d.ts

@@ -0,0 +1,18 @@
+import type { DriverResult } from "../driver.types";
+import type { SpokenRead } from "../screen-reader";
+import type { SrEventsRead } from "./uiad-screen-reader";
+/**
+ * What TalkBack said since a cursor (`DrivesScreenReader.screenReaderSpoken`). The cursor is the device epoch ms of the
+ * last line returned, whichever source it came from. Real speech needs TalkBack's verbose log (a developer setting
+ * only its UI can change); without it the lines are composed by the speech model from the focus events the
+ * screen-reader stream saw, labelled `simulated`. Whichever the log allows is used for the whole read, never a mix.
+ */
+export type SpokenDeps = {
+    /** TalkBack's log, epoch timestamps (`TALKBACK_LOGCAT_ARGV`); undefined when it cannot be read */
+    readLog(): Promise<string | undefined>;
+    /** focus moves since 0 (the ring is small) */
+    focusEvents(): DriverResult<SrEventsRead>;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare function readSpoken(deps: SpokenDeps, since?: number): DriverResult<SpokenRead>;

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

@@ -21,7 +21,17 @@ export type AndroidDeviceState = {
     uiadUnsupported?: string | undefined;
     /** the scales to put back (what they were before warden set them to 0), while warden's zeros are in place */
     animations?: AnimationValues | undefined;
+    /** physical phones: the rotation settings to put back, while warden's pinned rotation is in place */
+    rotation?: RotationValues | undefined;
+    /** physical phones: the `cmd uimode night` mode to put back, while warden's override is in place */
+    uimode?: UimodeValue | undefined;
 };
+/** `settings get system` values as printed: a digit, or `null` when never set. */
+export type RotationValues = {
+    accelerometer_rotation: string;
+    user_rotation: string;
+};
+export type UimodeValue = "yes" | "no" | "auto";
 /** The slice of `node:fs/promises` the store uses (injected in tests). */
 export type StateFs = {
     readFile(path: string): Promise<string>;

package/types/e2e/src/driver/android/android-talkback.d.ts

@@ -0,0 +1,57 @@
+import type { ScreenReaderState } from "../../a11y/a11y.types";
+import type { DriverResult } from "../driver.types";
+/**
+ * TalkBack as the screen reader of an Android emulator (WDN-A11Y, A11Y-7). Everything is shell: the two secure settings
+ * that switch an accessibility service on, `pm` for presence and the notification grant, `dumpsys accessibility` to
+ * see that the service is bound (enabled in settings is not running: a UiAutomation client connected without
+ * `FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES` unbinds it). The previous values of both settings are kept so turning
+ * TalkBack off, or the lease's undo, puts back exactly what was there.
+ */
+export declare const TALKBACK_PACKAGE = "com.google.android.marvin.talkback";
+export declare const TALKBACK_SERVICE = "com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService";
+export declare const POST_NOTIFICATIONS = "android.permission.POST_NOTIFICATIONS";
+export declare const talkbackPathArgv: readonly string[];
+export declare const talkbackGrantArgv: readonly string[];
+export declare const accessibilityDumpArgv: readonly string[];
+export declare const secureGetArgv: (key: string) => string[];
+/** Set a secure key, or delete it when `value` is null (it was unset). The driver's shell quotes each argument. */
+export declare const secureWriteArgv: (key: string, value: string | null) => string[];
+/** `settings get` answers the text `null` for an unset key. */
+export declare function settingValue(stdout: string): string | null;
+/** `services` with the TalkBack component added after whatever is there (`:` separated, once). */
+export declare function withTalkBack(services: string | null): string;
+/** Is a TalkBack service among the bound ones in `dumpsys accessibility`? */
+export declare function talkbackBound(dump: string): boolean;
+export type Previous = {
+    services: string | null;
+    enabled: string | null;
+};
+type Shelled = {
+    ok: boolean;
+    stdout: string;
+    failure: string | undefined;
+};
+export type TalkBackDeps = {
+    serial: string;
+    shell(argv: readonly string[]): Promise<Shelled>;
+    must(argv: readonly string[]): DriverResult<string>;
+    /** is `warden-uiad` the way this driver reads the screen (the dump unbinds TalkBack) */
+    uiadAvailable(): boolean;
+    sleep(ms: number): Promise<void>;
+};
+export type TalkBackControl = {
+    /** warden turned TalkBack on and has not turned it off */
+    active(): boolean;
+    /** TalkBack is the screen reader now: warden's doing, or found already on and bound by `detect` */
+    on(): boolean;
+    /** read the device once (`fresh`: again, for a TalkBack another process turned on since) for a TalkBack that was on before warden touched anything (a crashed run, a person) */
+    detect(fresh?: boolean): Promise<boolean>;
+    state(): ScreenReaderState;
+    previous(): Previous | undefined;
+    enable(): DriverResult<ScreenReaderState>;
+    disable(): DriverResult<ScreenReaderState>;
+    /** is the service bound right now */
+    bound(): Promise<boolean>;
+};
+export declare function createTalkBack(deps: TalkBackDeps): TalkBackControl;
+export {};

package/types/e2e/src/driver/android/atf-device.d.ts

@@ -0,0 +1,23 @@
+import type { DriverResult, Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import { type PushDex } from "./uiad-device";
+/**
+ * `warden-atf.jar` (the Accessibility Test Framework, ~180 KB) goes to the device on the first audit only, named by its
+ * hash like the uiad dex, so a new build is a new file and the always-pushed uiad dex stays small.
+ */
+export type AtfJar = {
+    bytes: number;
+    jarSha256: string;
+    base64: string;
+};
+export declare function atfDevicePath(jar?: Pick<AtfJar, "jarSha256">): string;
+export type EnsureAtfDeps = {
+    session: AdbSession;
+    adb: string;
+    serial: string;
+    push?: PushDex;
+    jar?: AtfJar;
+    log?: Logger;
+};
+/** The jar is on the device (written now if it was not); the result is its path. */
+export declare function ensureAtfJar(deps: EnsureAtfDeps): DriverResult<string>;