@delacour/warden-e2e 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,29 @@
+import type { Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import { type AnimationValues } from "./android-argv";
+import { type AndroidStateStore } from "./android-state";
+/**
+ * Animations off for the run (a flake source in e2e) and back on afterwards. The three scales are global
+ * settings that outlive the driver, so whatever warden changes it puts back when the driver closes, and the
+ * values it will put back are saved with the device's state (`android-state.ts`) before anything can go wrong:
+ * a process that dies without closing leaves the originals in the file, and the next driver opened on that
+ * emulator restores them when it closes.
+ */
+export type AnimationGuard = {
+    /** put the scales back (once); a restore that fails leaves the saved originals for the next driver */
+    restore(): Promise<void>;
+};
+export type AnimationDeps = {
+    session: AdbSession;
+    serial: string;
+    sdk: number | undefined;
+    /** originals a process that died left in the state file, if any */
+    pending: AnimationValues | undefined;
+    state?: AndroidStateStore;
+    log?: Logger;
+};
+/**
+ * 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.
+ */
+export declare function disableAnimations(deps: AnimationDeps): Promise<AnimationGuard>;

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

@@ -0,0 +1,32 @@
+import type { Exec } from "../../../../core/src/exec";
+import type { AppCommands, Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+export type AppDeps = {
+    session: AdbSession;
+    exec: Exec;
+    adb: string;
+    serial: string;
+    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;
+    /** 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 */
+    startProbeTimeoutMs?: number;
+};
+/** The component on the last non-empty line of `cmd package resolve-activity --brief`; undefined when there is none. */
+export declare function parseLauncherComponent(stdout: string): string | undefined;
+export type StartWait = {
+    status?: string;
+    launchState?: string;
+    totalTimeMs?: number;
+    error?: string;
+};
+/** What `am start -W` printed: `Status: ok`, `LaunchState: COLD` (API 29+), `TotalTime: 812`, or an `Error:` line. */
+export declare function parseStartWait(stdout: string): StartWait;
+/**
+ * `AppCommands` over `am` / `pm` (and `monkey` when the launcher cannot be resolved) in the session and host
+ * `adb install|uninstall` through `exec`. A launch is one `am start -W -S -a MAIN -c LAUNCHER -n <launcher>`: a binder call (no JVM start,
+ * where `monkey` is an `app_process` program) that returns once the first frame is drawn.
+ */
+export declare function createAppCommands(deps: AppDeps): AppCommands;

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

@@ -0,0 +1,122 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError, HardwareButton, KeyName, Point } from "../driver.types";
+import type { GesturePlan } from "../gesture-geometry";
+/** POSIX single-quote a word for the device shell (`'` becomes `'\''`). Safe words stay bare. */
+export declare function shellQuote(word: string): string;
+/** One shell command line from an argv. */
+export declare function shellCommand(argv: readonly string[]): string;
+export declare function tapArgv(point: Point): string[];
+export declare const DEFAULT_SWIPE_MS = 300;
+export declare const DEFAULT_LONG_PRESS_MS = 600;
+export declare function swipeArgv(from: Point, to: Point, durationMs?: number): string[];
+export type MotionAction = "DOWN" | "MOVE" | "UP" | "CANCEL";
+/** `input motionevent <action> x y` (Android 8 / sdk 26+): one touch event of a held gesture. */
+export declare function motionEventArgv(action: MotionAction, point: Point): string[];
+/** Lowest sdk with `input motionevent` (Android 8.0). */
+export declare const MOTIONEVENT_MIN_SDK = 26;
+/** `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;
+/** Fractional seconds for toybox `sleep` (`0.500`). */
+export declare function sleepArgv(ms: number): string[];
+export type DragTiming = {
+    pressMs: number;
+    durationMs: number;
+    releaseMs: number;
+    steps?: number;
+};
+/**
+ * One shell line for a hold-then-move drag: DOWN at `from`, sleep `pressMs`, `steps` MOVEs interpolated over
+ * `durationMs`, sleep `releaseMs`, UP at `to`. Chained with `&&`; if anything fails after DOWN the finger is
+ * lifted with CANCEL and the line exits 1. Each `input` is a process start, so the sleeps are lower bounds.
+ */
+export declare function dragMotionCommand(from: Point, to: Point, timing: DragTiming): string;
+/** Most MOVEs a one-finger gesture line sends: each `input motionevent` is a process start (~100+ ms). */
+export declare const GESTURE_LINE_MAX_MOVES = 12;
+/**
+ * One shell line for a one-finger `GesturePlan` (the fallback when `warden-uiad` is not there): DOWN at the first
+ * frame, sleep `holdMs`, at most `maxMoves` MOVEs at evenly spaced frame indices (the last frame always among
+ * them, the sleeps between sum to the plan's travel time), sleep `releaseMs`, UP at the last frame. Like
+ * `dragMotionCommand`, a failure after DOWN lifts the finger with CANCEL and exits 1. Needs one path.
+ */
+export declare function gestureMotionCommand(plan: GesturePlan, maxMoves?: number): string;
+/** `input` has no long-press verb: a swipe that stays in place for the duration. */
+export declare function longPressArgv(point: Point, durationMs?: number): string[];
+export declare function keyeventArgv(keycode: number): string[];
+/** Keycodes per `input keyevent` call; more are chunked into further calls. */
+export declare const KEYEVENT_CHUNK = 32;
+/** `times` presses of one keycode as `input keyevent` argvs (one process start per chunk instead of per key). */
+export declare function keyRepeatArgvs(keycode: number, times: number): string[][];
+/** `HardwareButton` to Android keycode; `shake` has no keycode. */
+export declare function buttonKeycode(button: HardwareButton): number | undefined;
+export declare function keyNameKeycode(key: KeyName): number;
+/**
+ * `input text` argvs for `text`: printable ASCII only, anything else is `E_UNSUPPORTED_TEXT` (no unicode path
+ * without an IME or app helper). Spaces become `%s` (the one escape `input` understands) and a literal `%`
+ * before a space or `s` is typed by splitting into separate calls (see {@link splitForInputText}); quoting
+ * for the shell is {@link shellCommand}'s job. Empty text yields no argv.
+ */
+export declare function textArgvs(text: string): Result<string[][], DriverError>;
+/** `am start` a VIEW intent for `url`; `packageName` (`-p`) pins it to the app under test instead of any handler. */
+export declare function startUrlArgv(url: string, packageName?: string): string[];
+/** Launch a package's launcher activity without knowing its activity name. */
+export declare function monkeyLaunchArgv(packageName: string): string[];
+/** The launcher activity of a package; `--brief` prints the component (`pkg/.Activity`) on its last line. */
+export declare function resolveLauncherArgv(packageName: string): string[];
+/**
+ * Start a known component and wait (`-W`) until its first frame is drawn; `stop` (`-S`) force-stops the app first, so
+ * a relaunch is one round trip. Prints `Status`, `LaunchState` and `TotalTime`. The intent is the launcher's own
+ * (MAIN + LAUNCHER, what `monkey` sends): it matches a running task's root, so without `-S` the app is brought to the
+ * front with its state, where a bare `-n` intent can stack a second instance on top.
+ */
+export declare function startComponentArgv(component: string, options: {
+    stop: boolean;
+}): string[];
+export declare function forceStopArgv(packageName: string): string[];
+export declare function pmClearArgv(packageName: string): string[];
+/** The three global settings that scale animations (flake source in e2e), in the order they are read and saved. */
+export declare const ANIMATION_SETTINGS: readonly ["window_animation_scale", "transition_animation_scale", "animator_duration_scale"];
+export type AnimationSetting = (typeof ANIMATION_SETTINGS)[number];
+/** A value per animation setting as `settings get global` prints it: a number, or `null` when never set. */
+export type AnimationValues = Record<AnimationSetting, string>;
+/** Turn all three animation scales off. */
+export declare function animationScaleArgvs(): string[][];
+/** Read all three animation scales, one value per output line. */
+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[][];
+/** 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). */
+export declare function getpropArgv(key: string): string[];
+export declare const WM_SIZE_ARGV: readonly string[];
+export declare const WM_DENSITY_ARGV: readonly string[];
+export declare const DUMP_FILE_PATH = "/sdcard/warden-ui.xml";
+/** Route 1: dump straight to the session's stdout. */
+export declare function dumpStdoutArgv(): string[];
+/** Route 2 (host argv): `exec-out` gives uiautomator a tty-less stdout it accepts as `/dev/tty`. */
+export declare function dumpTtyHostArgv(adb: string, serial: string): string[];
+/**
+ * Route 3: dump to a file on the device then `cat` it (works on every image). The file is removed first so a
+ * failed dump can never hand back the previous screen; uiautomator's own message (`ERROR: null root node…`)
+ * is echoed when no file appears.
+ */
+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[];
+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[];
+/** Exit 0 and the pids when running (API 24+). */
+export declare function pidofArgv(packageName: string): string[];
+export type RotationValue = 0 | 1 | 2 | 3;
+/** Lock auto-rotate off, then pin the rotation. */
+export declare function rotationArgvs(rotation: RotationValue): string[][];
+export declare function userRotationArgv(): string[];
+export declare function uimodeGetArgv(): string[];
+export declare function uimodeSetArgv(dark: boolean): string[];
+/** `input keycombination` (API 33+): modifiers first, the key last. */
+export declare function keycombinationArgv(keycodes: readonly number[]): string[];
+/** Ctrl+A: select the whole text of the focused field (API 33+, see `SELECT_ALL_MIN_SDK`). */
+export declare function selectAllArgv(): string[];
+export declare function modifierKeycode(modifier: "shift" | "cmd" | "alt" | "ctrl"): number;

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

@@ -0,0 +1,44 @@
+import type { DriverResult, Logger, Orientation, ScreenInfo } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import { type RotationValue } from "./android-argv";
+/** 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 = {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+};
+export declare const realClock: Clock;
+/** `wm size` prints `Physical size: WxH` and, when overridden, `Override size: WxH` (which wins). */
+export declare function parseWmSize(text: string): {
+    width: number;
+    height: number;
+} | undefined;
+/** `wm density`: `Physical density: 420` / `Override density: 320`; scale = dpi / 160. */
+export declare function parseWmDensity(text: string): number | undefined;
+/** The sdk level on the probe's second line, if numeric. */
+export declare function sdkFromProbe(stdout: string): number | undefined;
+export type BootInfo = {
+    screen: ScreenInfo | undefined;
+    sdk: number | undefined;
+};
+/** The screen out of a boot probe's output, if `wm` answered. */
+export declare function screenFromProbe(stdout: string): ScreenInfo | undefined;
+/**
+ * Poll the boot probe until `sys.boot_completed` is `1`; `E_NOT_BOOTED` after `timeoutMs`. Returns the screen
+ * and sdk level from the same round trip (screen undefined when `wm` printed nothing parseable; use {@link readScreen}).
+ */
+export declare function waitForBoot(session: AdbSession, serial: string, clock: Clock, opts?: {
+    timeoutMs?: number;
+    log?: Logger;
+}): DriverResult<BootInfo>;
+/** Screen size + scale from `wm size` / `wm density`. */
+export declare function readScreen(session: AdbSession, serial: string): DriverResult<ScreenInfo>;
+/** Rotation reported by `<hierarchy rotation="N">` (0 when absent). */
+export declare function hierarchyRotation(xml: string): number;
+/** The screen as drawn: width/height swap on 90/270 degree rotations. */
+export declare function rotatedScreen(base: ScreenInfo, rotation: number): ScreenInfo;
+/** Android `user_rotation` to `Orientation` (0 portrait, 1 landscapeLeft, 2 upside down, 3 landscapeRight). */
+export declare function rotationToOrientation(rotation: number): Orientation;
+export declare function orientationToRotation(orientation: Orientation): RotationValue;
+/** Run one argv inside the session; a non-zero exit becomes `failure` (default `E_HID`) with the output as message. */
+export declare function runChecked(session: AdbSession, cmd: string, failure?: "E_HID" | "E_IO" | "E_APP_UNAVAILABLE" | "E_UNSUPPORTED" | "E_BAD_REQUEST", timeoutMs?: number): DriverResult<string>;

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

@@ -0,0 +1,60 @@
+import type { Exec } from "../../../../core/src/exec";
+import type { Driver, DriverResult, Element, Logger, Point, ScreenInfo } from "../driver.types";
+import { type SpawnAdb } from "./adb-session";
+import { type Clock } from "./android-device";
+import { type DumpRoute } from "./android-dump";
+import { type AndroidStateStore } from "./android-state";
+import { type UiadOptions } from "./uiad-backend";
+/** Binary-safe host process runner (screenshots); `Exec` is text-only. */
+export type ExecBinary = (argv: readonly string[], opts?: {
+    timeoutMs?: number;
+}) => Promise<{
+    exitCode: number;
+    stdout: Uint8Array;
+}>;
+/** Default {@link ExecBinary}: `Bun.spawn`, stderr dropped, never throws (a spawn failure is exit 127). */
+export declare const bunExecBinary: ExecBinary;
+export type AndroidDriverOptions = {
+    serial: string;
+    /** path of the `adb` binary (`androidTools(env).adb`) */
+    adb: string;
+    /** text-only host runner (`bunExec` in production): `adb install`, the `exec-out` dump route */
+    exec: Exec;
+    /** override how the resident shell is spawned (tests) */
+    spawn?: SpawnAdb;
+    log?: Logger;
+    /** skip `wm size`/`wm density` */
+    screen?: ScreenInfo;
+    /** binary runner for screenshots, default {@link bunExecBinary} */
+    execBinary?: ExecBinary;
+    /** injectable clock for boot polling and settle (default real time) */
+    clock?: Clock;
+    /** the dump route that worked last time (a `warden ui` call is a fresh process; skips probing the others) */
+    dumpRoute?: DumpRoute;
+    /** told when a dump route is first found to work or changes (`state`, when given, saves it too) */
+    onDumpRoute?: (route: DumpRoute) => void;
+    /**
+     * What warden remembers about this device between processes (`$WARDEN_HOME/android/<serial>.json`): the dump
+     * route that worked, and the animation scales to put back when the driver closes. Omit it and nothing is saved.
+     */
+    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;
+    /** how long to wait for `sys.boot_completed`, default 30 s */
+    bootTimeoutMs?: number;
+    /**
+     * Use the resident UiAutomation server (`warden-uiad`) for snapshots, settle and input, with `uiautomator dump`
+     * and `input` as the fallback for any call it cannot do. Off unless given: `true` for the defaults, or the seams
+     * (a fake spawn, a fake dex push) a test replaces. API 26 and up only.
+     */
+    uiad?: boolean | UiadOptions;
+};
+/** 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;
+/**
+ * Android `Driver`: one resident `adb shell` (inputs, `am`, `pm`, dumps), host `adb` for install and
+ * `exec-out` (binary screenshots never touch the session). `settle` is implemented here over snapshots (one dump,
+ * or `settleByHash` for a long quiet window), so the TS layer needs no fallback (`nativeSettle: false`). The
+ * animation scales it turns off on open are put back by `close`.
+ */
+export declare function openAndroidDriver(options: AndroidDriverOptions): DriverResult<Driver>;

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

@@ -0,0 +1,46 @@
+import type { Exec } from "../../../../core/src/exec";
+import type { DriverResult, Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+/**
+ * Fetching a `uiautomator dump`. Images disagree on where the XML may go (on the Pixel 10 AVD
+ * `dump /dev/stdout` prints only the trailer, `exec-out … dump /dev/tty` works), so three routes are
+ * tried in order and the first that yields a `<hierarchy>` is remembered and tried first next time. A
+ * failed probe is a whole dump (~2 s), so the order is a guess worth getting right: see {@link routeOrder}.
+ */
+export type DumpRoute = "stdout" | "tty" | "file";
+export declare const DUMP_ROUTES: readonly DumpRoute[];
+/**
+ * From this API level `tty` is tried before `stdout` when nothing is remembered. Measured on the API 36 and 37
+ * emulator images, where `/dev/stdout` returns only the trailer; the cut-off at 30 is WDN-PERF's guess for the
+ * levels in between (a wrong guess costs one failed dump, once per device, then the route is remembered).
+ */
+export declare const TTY_FIRST_SDK = 30;
+/**
+ * The order to try the routes in: `known` (a route that worked before) first, else `tty` first from
+ * {@link TTY_FIRST_SDK}, else `stdout`; the rest follow in that order.
+ */
+export declare function routeOrder(sdk: number | undefined, known?: DumpRoute): DumpRoute[];
+export declare const DUMP_TIMEOUT_MS = 20000;
+export type DumpDeps = {
+    session: AdbSession;
+    exec: Exec;
+    adb: string;
+    serial: string;
+    log?: Logger;
+    /** the device's API level: decides which route is tried first when none is remembered */
+    sdk?: number;
+    /** route to try first (remembered from an earlier process) */
+    initialRoute?: DumpRoute;
+    /** called whenever the working route changes (including the first discovery) */
+    onRoute?: (route: DumpRoute) => void;
+};
+export type Dumper = {
+    /** raw XML plus the route that produced it; `E_AX_UNAVAILABLE` when no route yields a hierarchy */
+    dump(): DriverResult<{
+        xml: string;
+        route: DumpRoute;
+    }>;
+    /** the route that last worked, if any */
+    route(): DumpRoute | undefined;
+};
+export declare function createDumper(deps: DumpDeps): Dumper;

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

@@ -0,0 +1,69 @@
+import type { Logger } from "../driver.types";
+import { type AnimationValues } from "./android-argv";
+import type { DumpRoute } from "./android-dump";
+/**
+ * What warden remembers about one Android device between processes (`$WARDEN_HOME/android/<serial>.json`):
+ * - the API level it was learned on (a serial is reused by whatever image the emulator runs next, so the other
+ *   fields are trusted only on the same level);
+ * - the `uiautomator dump` route that worked (probing the wrong ones costs a whole dump each, ~2 s);
+ * - the build of `warden-uiad` that could not run here (an API level it does not support), so later processes go
+ *   straight to the dump instead of paying a failed start each time;
+ * - the animation scales warden found before it turned them off, so a process that died without closing its
+ *   driver does not leave the emulator animation-less for whatever runs next.
+ *
+ * Best effort throughout: a missing, unreadable or hand-edited file reads as empty and a failed write is logged,
+ * never thrown. The file is read back into shell commands, so every field is validated down to a number-shaped value.
+ */
+export type AndroidDeviceState = {
+    sdk?: number | undefined;
+    dumpRoute?: DumpRoute | undefined;
+    /** `uiadBuildId()` of a `warden-uiad` build that failed to start here for a reason that will not change */
+    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;
+};
+/** The slice of `node:fs/promises` the store uses (injected in tests). */
+export type StateFs = {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** create the directory and its parents */
+    mkdir(path: string): Promise<void>;
+};
+export declare const nodeStateFs: StateFs;
+export type AndroidStateStore = {
+    /** the saved state of `serial`; `{}` when there is none or it cannot be read */
+    read(serial: string): Promise<AndroidDeviceState>;
+    /** replace the state with `change(what is on disk now)`; never rejects, and writes nothing when nothing changed */
+    update(serial: string, change: (state: AndroidDeviceState) => AndroidDeviceState): Promise<void>;
+};
+/** `$WARDEN_HOME/android`. */
+export declare function androidStateDir(home?: string): string;
+/** `<dir>/<serial>.json`; anything in a serial that is not a plain file-name character becomes `_`. */
+export declare function androidStateFile(dir: string, serial: string): string;
+export type AndroidStateStoreOptions = {
+    dir: string;
+    fs?: StateFs;
+    log?: Logger;
+};
+export declare function createAndroidStateStore(options: AndroidStateStoreOptions): AndroidStateStore;
+/** A store that lives in memory (tests, and callers that want no file). */
+export declare function memoryAndroidState(): AndroidStateStore;
+/** `state` when it was learned on this API level (`undefined` = unknown matches unknown), else nothing is known. */
+export declare function forSdk(state: AndroidDeviceState, sdk: number | undefined): AndroidDeviceState;
+/** An `update` callback: keep what was learned on this API level, record the level, apply `patch` (`undefined` removes a field). */
+export declare function patchFor(sdk: number | undefined, patch: Omit<AndroidDeviceState, "sdk">): (state: AndroidDeviceState) => AndroidDeviceState;
+/**
+ * The three values `settings get global` printed, one per line in {@link ANIMATION_SETTINGS} order. Lines that are
+ * not a value (an error message) are skipped; anything but exactly three values is unreadable (`undefined`).
+ */
+export declare function parseAnimationValues(stdout: string): AnimationValues | undefined;
+/**
+ * What to put back when the driver closes, given the scales as found now (just before warden turns them off) and
+ * the originals a previous process saved and never restored (`pending`).
+ *
+ * A scale that reads `0` while `pending` has a value for it is warden's own leftover, so the saved value is the
+ * original; any other value was set by someone else since, and is kept as it is. `undefined` when every original is
+ * already `0` (animations were off before warden came: nothing to restore).
+ */
+export declare function planAnimations(current: AnimationValues, pending: AnimationValues | undefined): AnimationValues | undefined;

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

@@ -0,0 +1,63 @@
+import type { DriverError, Logger } from "../driver.types";
+import type { SimdSpawn } from "../ios/simd-transport";
+import type { AdbSession } from "./adb-session";
+import type { Clock } from "./android-device";
+import { type UiadClient } from "./uiad-client";
+import { launchUiad, type PushDex } from "./uiad-device";
+/**
+ * The driver's hold on `warden-uiad`: started when the first call that can use it arrives (a spec that only opens
+ * links never pays for it), reused for every call after, and given up on, for this driver, when it cannot be made to
+ * work. "Given up" means the driver goes on with `uiautomator dump` and `input`: the server is an accelerator, never a
+ * requirement. The one failure that is not answered with a fallback is a busy UiAutomation slot, because the dump needs
+ * the same slot and would die with a bare "Killed": that is reported as what it is.
+ */
+/** Seams and switches for the resident server, from `AndroidDriverOptions.uiad`. */
+export type UiadOptions = {
+    /** how the server's `adb shell` is spawned (tests); default a real `adb` child */
+    spawn?: SimdSpawn;
+    /** how the dex is written to the device (tests); default `adb shell cat > file` with the bytes on stdin */
+    push?: PushDex;
+    /** how long to wait for the server's `ready`, default 5 s */
+    readyTimeoutMs?: number;
+    /** how long a request may take before the server is judged hung, default 10 s */
+    requestTimeoutMs?: number;
+};
+export type UiadBackend = {
+    /** the server is switched on and has not been given up on */
+    wanted(): boolean;
+    /** the running server, started if need be; undefined means "use the dump and `input`" for this call */
+    server(): Promise<UiadClient | undefined>;
+    /** why UiAutomation is unavailable when something else holds it (the dump would fail the same way) */
+    blocked(): DriverError | undefined;
+    /** a call to the server failed: stop it so the dump can run; it is started again by the next `server()` unless it keeps failing */
+    failed(error: DriverError): Promise<void>;
+    /** stop the server, if there is one */
+    stop(): Promise<void>;
+    /** for `health`: "up", "idle", or why it is off */
+    status(): string;
+};
+export type UiadBackendDeps = {
+    session: AdbSession;
+    adb: string;
+    serial: string;
+    clock: Clock;
+    log?: Logger;
+    options: UiadOptions;
+    /** a build that this device is known not to run: the server is off from the start */
+    unsupportedBuild?: string;
+    /** told when a start failed for a reason that will not change, so the next process need not try */
+    onUnsupported?: (buildId: string) => void;
+    /** `launchUiad` (tests replace it) */
+    launch?: typeof launchUiad;
+};
+/** `WARDEN_ANDROID_UIAD=0` keeps the driver on `uiautomator dump` and `input` (the server is on otherwise). */
+export declare const UIAD_ENV = "WARDEN_ANDROID_UIAD";
+/** What a caller puts in `AndroidDriverOptions.uiad` for the environment it runs in: the server unless it is switched off. */
+export declare function uiadFromEnv(env: Readonly<Record<string, string | undefined>>): true | undefined;
+/**
+ * A start failure that retrying will not fix: the hidden API is missing, or the server cannot even load. An
+ * `E_UNSUPPORTED` is written down at once; a `connect_failed` only when {@link CONNECT_FAILURES_TO_PERSIST} starts in a
+ * row end with it, since the server cannot yet tell a missing API from a transient connect error.
+ */
+export declare function isPersistentStartFailure(error: DriverError): boolean;
+export declare function createUiadBackend(deps: UiadBackendDeps): UiadBackend;

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

@@ -0,0 +1,60 @@
+import type { DriverError, DriverResult, Logger } from "../driver.types";
+import { type SimdSpawn, type TransportClose } from "../ios/simd-transport";
+import { type UiadHealth, type UiadSettleData, type UiadSnapshotData, type UiadTextData } from "./uiad-protocol";
+/**
+ * Client of `warden-uiad`, the resident UiAutomation server (`native/android/`), over the stdio of an `adb shell`
+ * that runs it. Starts it and waits for `ready`, sends one request at a time per op in order (the server answers in
+ * order), enforces a timeout per request, forwards `log` events, and maps `fatal`, a crash and a protocol mismatch to
+ * a `DriverError`. A timed-out request kills the server (what it was doing is unknowable); the driver starts a new one.
+ */
+export type UiadClient = {
+    /** what the server said about itself in `ready` */
+    readonly health: UiadHealth;
+    /** false once the server has exited, been killed, or timed out */
+    alive(): boolean;
+    request(op: string, params?: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }): DriverResult<unknown>;
+    snapshot(params?: SnapshotParams, opts?: {
+        timeoutMs?: number;
+    }): DriverResult<UiadSnapshotData>;
+    settle(params: {
+        quietMs: number;
+        timeoutMs: number;
+    }): DriverResult<UiadSettleData>;
+    typeText(text: string): DriverResult<UiadTextData>;
+    /** called once, if the server dies without `close()` having been asked for */
+    onDeath(handler: (info: TransportClose) => void): void;
+    /** `shutdown`, then close stdin, then kill when it lingers. Safe to call twice. */
+    close(): Promise<void>;
+};
+export type SnapshotParams = {
+    scope?: "active" | "all";
+    maxNodes?: number;
+    /** wait for this long without accessibility events before reading (the dump's built-in idle wait) */
+    idleMs?: number;
+    rootWaitMs?: number;
+    /** false keeps nodes the user cannot see, flagged `invisible` */
+    skipInvisible?: boolean;
+    /** false may answer from the server's node cache (2-3 ms), which can lag the app by an event */
+    fresh?: boolean;
+    windows?: boolean;
+};
+export type UiadStartOptions = {
+    /** the host command that runs the server on the device (`adb -s <serial> shell exec env CLASSPATH=... app_process / ...`) */
+    cmd: readonly string[];
+    spawn?: SimdSpawn;
+    log?: Logger;
+    /** how long to wait for `ready`, default 5 s (a start takes 80-450 ms, the long end on a busy host) */
+    readyTimeoutMs?: number;
+    /** default per-request timeout, default 10 s */
+    requestTimeoutMs?: number;
+    /** how long `close()` waits for the server to exit after closing stdin, default 1 s */
+    graceMs?: number;
+};
+/** Start the server and wait for `ready`; the failure says why (busy slot, protocol, crash, timeout). */
+export declare function startUiad(options: UiadStartOptions): DriverResult<UiadClient>;
+/** True when the request never reached the server (it was already gone), so the call can be made again without doubling its effect. */
+export declare function neverSent(error: DriverError): boolean;
+/** True when `error` is the server saying another UiAutomation client holds the device. */
+export declare function isBusy(error: DriverError): boolean;

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

@@ -0,0 +1,70 @@
+import type { DriverError, DriverResult, Logger } from "../driver.types";
+import type { SimdSpawn } from "../ios/simd-transport";
+import type { AdbSession } from "./adb-session";
+import { type UiadClient } from "./uiad-client";
+import { UIAD_DEX } from "./uiad-dex.generated";
+/**
+ * Getting `warden-uiad` running on one device: the dex is written to `/data/local/tmp` (once per build, named by its
+ * hash), the server is started as the shell user with `app_process`, and a busy UiAutomation slot is dealt with: a
+ * stale server of ours is killed, anything else is named in the error and left alone. Everything here is argv and
+ * parsing around injected seams (`AdbSession`, `PushDex`, `SimdSpawn`), so it is tested without adb.
+ */
+export declare const UIAD_DEVICE_DIR = "/data/local/tmp";
+/** The server is built for API 26 and up (`d8 --min-api 26`); an older device keeps the dump and `input`. */
+export declare const UIAD_MIN_SDK = 26;
+export type UiadDex = Pick<typeof UIAD_DEX, "bytes" | "dexSha256" | "base64">;
+/** `/data/local/tmp/warden-uiad-<hash8>.dex`: a new build is a new file, so an old build is never started by mistake. */
+export declare function uiadDevicePath(dex?: Pick<UiadDex, "dexSha256">): string;
+/** The first eight characters of the dex hash: what the saved state keys "this build does not work here" on. */
+export declare function uiadBuildId(dex?: Pick<UiadDex, "dexSha256">): string;
+/** `exec env CLASSPATH=<dex> app_process / <Main>`: `exec` keeps the pipe on the server rather than on a wrapper shell. */
+export declare function uiadLaunchCommand(devicePath: string): string;
+/** The host command that runs the server and carries its stdio. */
+export declare function uiadLaunchArgv(adb: string, serial: string, devicePath: string): string[];
+/** Writes stdin to a temp name, makes it read-only, renames it into place: a half-written file is never `present`. */
+export declare function uiadInstallCommand(devicePath: string): string;
+export declare function uiadInstallArgv(adb: string, serial: string, devicePath: string): string[];
+/** Prints `present` when the dex is on the device with the size it should have. */
+export declare function uiadPresentCommand(devicePath: string, bytes: number): string;
+/** Runs a host command with `bytes` on its stdin (`adb shell cat > file`). */
+export type PushDex = (argv: readonly string[], bytes: Uint8Array) => Promise<{
+    exitCode: number;
+    output: string;
+}>;
+export declare const bunPushDex: PushDex;
+export type EnsureDexDeps = {
+    session: AdbSession;
+    adb: string;
+    serial: string;
+    push?: PushDex;
+    dex?: UiadDex;
+    log?: Logger;
+};
+/** The dex is on the device (written now if it was not); the result is its path. */
+export declare function ensureUiadDex(deps: EnsureDexDeps): DriverResult<string>;
+export type Holder = {
+    pid: number;
+    args: string;
+    /** a `warden-uiad` process: a server of ours that nobody is talking to any more */
+    ours: boolean;
+};
+export declare const HOLDERS_COMMAND = "ps -A -o PID,ARGS";
+/**
+ * The processes in `ps -A -o PID,ARGS` output that can hold the one UiAutomation slot: a `warden-uiad` server (ours),
+ * an `am instrument` run (Maestro's driver, agent-device's helper, any test runner) or a `uiautomator` command.
+ */
+export declare function parseHolders(ps: string): Holder[];
+/** What the failure says when the slot is taken by something that is not ours. */
+export declare function busyError(serial: string, holders: readonly Holder[], cause: DriverError): DriverError;
+export type LaunchDeps = EnsureDexDeps & {
+    spawn?: SimdSpawn;
+    readyTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Start `warden-uiad` on `serial` and wait for it to be ready. A busy slot is the one failure handled here: servers of
+ * ours still running (a host that died without its pipe closing, a second warden process on the same device) are
+ * killed and the start retried once; a foreign holder is named in the error and left alone.
+ */
+export declare function launchUiad(deps: LaunchDeps): DriverResult<UiadClient>;