@delacour/warden-e2e 0.6.0 → 0.7.0

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

@@ -1,5 +1,9 @@
 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 Clock } from "./android-device";
 import { type DumpRoute } from "./android-dump";
@@ -23,6 +27,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 +48,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 +61,10 @@ 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;
 };
 /** 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-settings.d.ts

@@ -0,0 +1,34 @@
+import type { PermissionName, PermissionState } from "../../../../core/src/conditions/conditions.types";
+import type { Driver } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+/** 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", 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;
+};
+export type AndroidSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push">;
+export declare function createAndroidSettings(deps: AndroidSettingsDeps): AndroidSettings;

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/clock-recorder.d.ts

@@ -0,0 +1,9 @@
+import type { ClockCondition } from "../../../core/src/conditions/conditions.types";
+import type { Store } from "../../../core/src/store";
+/**
+ * Told about every successful `Driver.clock`, so the lease carries the `clock` area and release / gc undo it
+ * (COND-1). Drivers never touch the lease store: whoever opens the driver builds this (`leaseClockRecorder`).
+ */
+export type ClockRecorder = (condition: ClockCondition) => void;
+/** `ClockRecorder` for one lease: a mocked clock is recorded, `real` forgets the area. */
+export declare function leaseClockRecorder(store: Store, leaseId: string, now?: () => number): ClockRecorder;

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

@@ -0,0 +1,10 @@
+import { resolveTextSize } from "../../../core/src/conditions/text-size";
+/** Checks shared by both platforms' device-setting ops; each returns a message, or undefined when fine. */
+export declare function timezoneProblem(tz: string): string | undefined;
+export declare function localeProblem(tag: string): string | undefined;
+export declare function batteryProblem(level: number | undefined): string | undefined;
+export declare const PUSH_MAX_BYTES = 4096;
+export declare function pushProblem(payload: unknown): string | undefined;
+/** `E_BAD_REQUEST` for a problem message, else undefined. */
+export declare const badRequest: (problem: string | undefined) => import("../../../types/src/result").ErrorResult<import("./driver.types").DriverError> | undefined;
+export { resolveTextSize };

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

@@ -1,3 +1,4 @@
+import type { ClockCondition, HostFault, LocationCondition, NetworkCondition, PermissionName, PermissionState, TextSize } from "../../../core/src/conditions/conditions.types";
 import type { AsyncResult } from "../../../types/src/result";
 /**
  * The device driver contract every layer of warden-e2e builds on: the spec API (`screen`, `device`,
@@ -8,7 +9,7 @@ import type { AsyncResult } from "../../../types/src/result";
  * Frozen interface — change it only together with `docs/plans/wdn-e2e.md`.
  */
 export type Platform = "ios" | "android";
-export type DriverErrorCode = "E_HELPER_MISSING" | "E_HELPER_CRASHED" | "E_TIMEOUT" | "E_NOT_BOOTED" | "E_UNKNOWN_DEVICE" | "E_AX_UNAVAILABLE" | "E_APP_UNAVAILABLE" | "E_APP_NOT_RESPONDING" | "E_NO_ELEMENT" | "E_STALE_REF" | "E_UNSUPPORTED" | "E_UNSUPPORTED_TEXT" | "E_HID" | "E_IO" | "E_BAD_REQUEST" | "E_INTERNAL";
+export type DriverErrorCode = "E_HELPER_MISSING" | "E_HELPER_CRASHED" | "E_TIMEOUT" | "E_NOT_BOOTED" | "E_UNKNOWN_DEVICE" | "E_AX_UNAVAILABLE" | "E_APP_UNAVAILABLE" | "E_APP_NOT_RESPONDING" | "E_NO_ELEMENT" | "E_STALE_REF" | "E_UNSUPPORTED" | "E_UNSUPPORTED_TEXT" | "E_HID" | "E_IO" | "E_BAD_REQUEST" | "E_INTERNAL" | "E_DEVICE_LOCKED" | "E_REFUSED" | "E_NETWORK_RELAUNCH";
 export type DriverError = {
     code: DriverErrorCode;
     message: string;
@@ -114,6 +115,13 @@ export type Orientation = "portrait" | "portraitUpsideDown" | "landscapeLeft" |
 export type HardwareButton = "home" | "back" | "lock" | "volumeUp" | "volumeDown" | "shake";
 export type KeyName = "Enter" | "Backspace" | "Tab" | "Space" | "Escape" | "Delete" | "Up" | "Down" | "Left" | "Right";
 export type Modifier = "shift" | "cmd" | "alt" | "ctrl";
+/** What `Driver.biometrics` does: read the enrollment, (un)enroll, or present a matching / non-matching biometric. */
+export type BiometricOp = "status" | "enroll" | "unenroll" | "match" | "fail";
+/** `modality`: what the device scans, iOS Face ID (`face`) or Touch ID and Android (`fingerprint`). */
+export type BiometricState = {
+    enrolled: boolean;
+    modality: "face" | "fingerprint";
+};
 export type AlertInfo = {
     title?: string;
     message?: string;
@@ -136,6 +144,19 @@ export type LaunchOptions = {
     env?: Record<string, string>;
     /** iOS: `--terminate-running-process`; Android: `am force-stop` first. Default true. */
     relaunch?: boolean;
+    /**
+     * iOS: load the warden network dylib even though no condition is set yet, so `network()` can take effect later
+     * without a relaunch (a suite that declares `conditions.network` launches this way). Conditions set before the
+     * launch inject on their own, a plain launch pays nothing. Ignored on Android.
+     */
+    inject?: boolean;
+};
+/** Options of `Driver.network`. */
+export type NetworkOptions = {
+    /** iOS: the app to check for the dylib (default: the last app this driver launched) */
+    bundleId?: string;
+    /** iOS: relaunch a running app that lacks the dylib instead of failing with `E_NETWORK_RELAUNCH` */
+    relaunch?: boolean;
 };
 export type DriverCapabilities = {
     /** two-finger `pinch` and `rotate` */
@@ -225,7 +246,161 @@ export interface Driver {
     alert(): DriverResult<AlertInfo | null>;
     appearance(set?: "light" | "dark"): DriverResult<"light" | "dark">;
     clipboard(set?: string): DriverResult<string>;
+    /**
+     * Put the device's network into `op` (offline / online / a preset / custom speed and latency) and return what
+     * is now in effect. Android emulator: native, verified through `dumpsys connectivity`. iOS: per app, the app
+     * is launched with a dylib that routes it through the lease proxy (`E_NETWORK_RELAUNCH` when it runs without).
+     * `flap` alternates the base with offline in this process (`conditions/scheduler.ts`) until the next network op
+     * or `close()` (Android; iOS goes through the scheduler directly).
+     */
+    network(op: NetworkCondition, opts?: NetworkOptions): DriverResult<NetworkState>;
+    /**
+     * Replace the per-host faults (status / reset / delay / blackhole by host glob). Both platforms route the app
+     * through the lease's shaping proxy for this. `notes` carries what the proxy cannot do as written (an https://
+     * request matching a `status` fault is reset, the proxy does not decrypt TLS). `[]` clears them.
+     */
+    networkFaults(faults: readonly HostFault[]): DriverResult<{
+        notes: readonly string[];
+    }>;
+    /**
+     * Simulated location: a point, a route (waypoints or GPX, played at `speedMps`), a bundled scenario, or clear.
+     * iOS: `simctl location` (the sim plays routes itself, no loop). Android: emulator `geo fix`, routes ticked by
+     * warden until the next op or `close()`; `clear` keeps the last fix. Physical devices: `E_UNSUPPORTED`.
+     */
+    location(op: LocationCondition): DriverResult<void>;
+    /**
+     * Mock the device's wall clock (monotonic clocks are never touched). `offset` shifts it from the real time,
+     * `fixed` sets it to an instant and lets it run, `frozen` holds it there, `real` puts it back. Android emulator:
+     * system time (`settings put global auto_time 0` + `cmd alarm set-time`), device-wide; no `frozen`
+     * (`E_UNSUPPORTED`). iOS: the injected dylib shifts or holds the clocks of the injected app only (live, no
+     * relaunch); an app without the dylib gets it from the next launch (`appliesOnLaunch`), or from a relaunch with
+     * `relaunch: true`. Large offsets break TLS validity (HTTPS fails once the clock passes a certificate's dates).
+     */
+    clock(op: ClockCondition, opts?: NetworkOptions): DriverResult<ClockState>;
+    /**
+     * Set runtime permissions of an app, per name (`location`, `camera`, `photos`, `notifications`, ...): `granted`,
+     * `denied` (revoked) or `unset` (back to asking). Names a platform has no service for are listed in `skipped`;
+     * when none applies it is `E_UNSUPPORTED`. iOS: `simctl privacy` (terminates a running app). Android: `pm
+     * grant|revoke` of the permissions the app declares. Apply before the first launch.
+     */
+    permissions(grants: PermissionGrants, opts?: SettingOptions): DriverResult<PermissionsState>;
+    /**
+     * Device timezone (IANA name); `null` puts it back. Android: `cmd alarm set-timezone`, device-wide, live. iOS: a
+     * simulator has none per device, so it is staged and the app launched next gets it as `TZ` (`appliesOnLaunch`).
+     * `previous` is the Android timezone to restore on `null` (default: the host's).
+     */
+    timezone(tz: string | null, opts?: {
+        previous?: string;
+    }): DriverResult<TimezoneState>;
+    /**
+     * Locale of an app (BCP 47, `fr-FR`); `null` puts it back. Android 13+: per-app locale (`cmd locale
+     * set-app-locales`), live. iOS: staged for the next launch as `-AppleLanguages` / `-AppleLocale`.
+     */
+    locale(tag: string | null, opts?: SettingOptions): DriverResult<LocaleState>;
+    /**
+     * Accessibility settings: text size, bold text, contrast, reduce motion; `null` puts them back. iOS: `simctl ui
+     * content_size` / `increase_contrast` (no bold text or reduce motion: `skipped`). Android: `font_scale`,
+     * `font_weight_adjustment` (no contrast or reduce motion: `skipped`).
+     */
+    a11y(op: A11yOp | null): DriverResult<A11yState>;
+    /**
+     * Battery level and charging; `null` puts the real battery back. Android emulator: `dumpsys battery`, seen by the
+     * OS and the app. iOS: status bar override only (`cosmetic: true`): the app still reads the real battery.
+     */
+    battery(op: BatteryOp | null): DriverResult<BatteryState>;
+    /** Android: `am send-trim-memory RUNNING_CRITICAL` to the running app. iOS: `E_UNSUPPORTED` (no way verified to reach an app). */
+    memoryWarning(opts?: SettingOptions): DriverResult<void>;
+    /** iOS: `simctl push` of an APNs payload (needs `aps`) to the app. Android: `E_UNSUPPORTED`. */
+    push(payload: PushPayload, opts?: SettingOptions): DriverResult<void>;
+    /** Simulated biometrics (simulators / emulators only, else `E_UNSUPPORTED`); answers the state after the op. */
+    biometrics(op: BiometricOp): DriverResult<BiometricState>;
     readonly app: AppCommands;
     close(): Promise<void>;
 }
+/** Parts of a network condition no native mechanism does; the per-lease shaping proxy (COND-4) carries them. */
+export type NetworkProxyFeature = "loss";
+/**
+ * What `Driver.network` left on the device. `online` is what the OS reports (verified, not assumed);
+ * `needsProxy` lists the asked-for parts that were NOT applied because they need the shaping proxy.
+ */
+export type NetworkState = {
+    online: boolean;
+    condition: NetworkCondition;
+    needsProxy: readonly NetworkProxyFeature[];
+    /**
+     * iOS: the condition is staged (proxy configured, state written) but no running app carries the dylib yet; it
+     * reaches the app launched next. Absent = in effect now.
+     */
+    appliesOnLaunch?: true;
+};
+/** The app a setting is for (default: the last app this driver launched, else the one the session names). */
+export type SettingOptions = {
+    bundleId?: string;
+};
+export type PermissionGrants = Partial<Record<PermissionName, PermissionState>>;
+export type PermissionsState = {
+    bundleId: string;
+    applied: readonly {
+        permission: PermissionName;
+        state: PermissionState;
+    }[];
+    /** names this platform has no service for, with why */
+    skipped: readonly {
+        permission: PermissionName;
+        reason: string;
+    }[];
+};
+export type TimezoneState = {
+    /** the timezone in effect (or staged), absent after a reset on iOS */
+    timezone?: string;
+    /** Android: the timezone before this change */
+    previous?: string;
+    /** iOS: staged for the next launch */
+    appliesOnLaunch?: true;
+};
+export type LocaleState = {
+    locale?: string;
+    bundleId?: string;
+    appliesOnLaunch?: true;
+};
+export type A11yOp = {
+    textSize?: TextSize;
+    boldText?: boolean;
+    contrast?: "increased" | "normal";
+    reduceMotion?: boolean;
+};
+export type A11yState = {
+    applied: readonly string[];
+    /** asked for but this platform has no mechanism that works, with why */
+    skipped: readonly {
+        setting: string;
+        reason: string;
+    }[];
+    /** the Android font scale was clamped to the platform's range */
+    notes: readonly string[];
+};
+export type BatteryOp = {
+    level?: number;
+    charging?: boolean;
+};
+export type BatteryState = {
+    level?: number;
+    charging?: boolean;
+    cosmetic: boolean;
+};
+/** An APNs payload: an object with an `aps` key (4096 bytes at most). */
+export type PushPayload = {
+    aps: Record<string, unknown>;
+} & Record<string, unknown>;
+/** What `Driver.clock` left on the device. */
+export type ClockState = {
+    condition: ClockCondition;
+    /** wall clock minus the host's, ms (0 for `real` and `frozen`) */
+    offsetMs: number;
+    frozen: boolean;
+    /** what the device's wall clock read when the op returned, ms since the epoch */
+    nowMs: number;
+    /** iOS: staged for the next launch of the app; absent = in effect now */
+    appliesOnLaunch?: true;
+};
 export type Logger = (line: string) => void;

package/types/e2e/src/driver/ios/device/capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { DriverCapabilities } from "../../driver.types";
+/** Capabilities exactly as the plan fixes them (WDN-PHY-6). */
+export declare const IOS_DEVICE_CAPABILITIES: DriverCapabilities;

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

@@ -0,0 +1,49 @@
+import type { Exec } from "../../../../../core/src/exec";
+import type { E2eEnv } from "../../../env";
+import type { ProbesFrontmost, ReadsAlertOn } from "../../alerts";
+import type { Driver, DriverResult, Logger } from "../../driver.types";
+import { type SimdClient } from "../simd-client";
+import { type Devicectl } from "./devicectl";
+/**
+ * The `Driver` for a physical iPhone / iPad: input, accessibility and app lifecycle through `warden-runner` (the
+ * XCUITest server `warden __ios-runner-host` keeps running on the phone, spoken to over the host's unix socket in the
+ * `warden-simd` protocol, so the client, normalizer and alert reader are simd's), and `xcrun devicectl` for what the
+ * runner cannot do: install / uninstall / probe, orientation changes, appearance and pasteboard reads, the screenshot
+ * fallback. There is no select-all or paste (a field is cleared with counted Backspace), no native settle (snapshot
+ * hashes), no multi-touch, and nothing that changes a phone beyond the app under test: an uninstall or data wipe of
+ * a bundle warden did not install is `E_REFUSED`.
+ */
+export type IosDeviceEnv = Pick<E2eEnv, "iosRunnerSocket" | "appPath" | "bundleId">;
+export type OpenIosDeviceDriverOptions = {
+    udid: string;
+    exec: Exec;
+    env?: Partial<IosDeviceEnv>;
+    /** the runner host's socket (wins over `env.iosRunnerSocket`) */
+    socketPath?: string;
+    /** an already connected client: used instead of connecting; the driver owns it from here */
+    client?: SimdClient;
+    /** `WARDEN_BUNDLE_ID`: the app under test, always allowed to be uninstalled / wiped */
+    bundleId?: string;
+    /** `WARDEN_APP_PATH`: what `clearData` reinstalls */
+    appPath?: string;
+    /** bundles warden installed on this phone earlier (the `installs` table) */
+    ownedBundles?: readonly string[];
+    log?: Logger;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    defaultTimeoutMs?: number;
+    /** test seams */
+    devicectl?: Devicectl;
+    writeFile?: (path: string, bytes: Uint8Array) => Promise<void>;
+};
+export type IosDeviceDriver = Driver & ReadsAlertOn & ProbesFrontmost;
+export declare function createIosDeviceDriver(client: SimdClient, devicectl: Devicectl, opts: Omit<OpenIosDeviceDriverOptions, "client" | "exec" | "devicectl" | "env" | "socketPath"> & {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    write: (path: string, bytes: Uint8Array) => Promise<void>;
+}): IosDeviceDriver;
+/**
+ * Open the driver for the phone `udid` against its runner host's socket (`socketPath` / `env.iosRunnerSocket` /
+ * `client`). `E_HELPER_MISSING` without any: the host is started by `warden ui` / `warden e2e`, never by the driver.
+ */
+export declare function openIosDeviceDriver(o: OpenIosDeviceDriverOptions): DriverResult<Driver>;

package/types/e2e/src/driver/ios/device/devicectl.d.ts

@@ -0,0 +1,38 @@
+import type { Exec, ExecResult } from "../../../../../core/src/exec";
+import type { DriverError, DriverResult, Orientation } from "../../driver.types";
+export declare const installArgv: (udid: string, appPath: string, json: string) => string[];
+export declare const uninstallArgv: (udid: string, bundleId: string, json: string) => string[];
+/** `--include-default-apps`: system apps (Settings) are listed too, so a probe of one is not a false negative. */
+export declare const appsArgv: (udid: string, bundleId: string, json: string) => string[];
+export declare const appearanceArgv: (udid: string, json: string) => string[];
+export declare const orientationArgv: (udid: string, orientation: Orientation) => string[];
+export declare const screenshotArgv: (udid: string, destination: string) => string[];
+export declare const pasteArgv: (udid: string) => string[];
+export type DevicectlOptions = {
+    udid: string;
+    exec: Exec;
+    /** a fresh private directory for `--json-output` files and screenshots */
+    makeDir?: () => Promise<string>;
+    read?: (path: string) => Promise<string>;
+    readBytes?: (path: string) => Promise<Uint8Array>;
+    remove?: (dir: string) => Promise<void>;
+};
+export type Devicectl = {
+    install(appPath: string): DriverResult<{
+        bundleIds: string[];
+    }>;
+    uninstall(bundleId: string): DriverResult<void>;
+    isInstalled(bundleId: string): DriverResult<boolean>;
+    appearance(): DriverResult<"light" | "dark">;
+    setOrientation(orientation: Orientation): DriverResult<void>;
+    /** to `path` when given, else the PNG bytes */
+    screenshot(path?: string): DriverResult<{
+        path?: string;
+        png?: Uint8Array;
+    }>;
+    pasteboardCopy(text: string): DriverResult<void>;
+    pasteboardPaste(): DriverResult<string>;
+};
+/** A failed devicectl call: a locked phone cannot be retried, anything else is an I/O failure with devicectl's own words. */
+export declare function devicectlError(what: string, result: ExecResult): DriverError;
+export declare function createDevicectl(o: DevicectlOptions): Devicectl;

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * What the `warden-runner` (XCUITest) wire adds to the `warden-simd` protocol of `simd-protocol.ts` (the shared
+ * schemas and `SimdClient` are reused unchanged): the `appState` op, and the facts about the runner the driver acts on.
+ * The runner's own contract is `native/ios-runner/AGENTS.md`.
+ */
+export declare const appStateSchema: z.ZodEnum<{
+    unknown: "unknown";
+    notRunning: "notRunning";
+    runningBackgroundSuspended: "runningBackgroundSuspended";
+    runningBackground: "runningBackground";
+    runningForeground: "runningForeground";
+}>;
+export type AppState = z.infer<typeof appStateSchema>;
+export declare const appStateDataSchema: z.ZodObject<{
+    state: z.ZodString;
+}, z.core.$loose>;
+/** `appState` reply data, or undefined when it is not shaped like one. */
+export declare function parseAppState(data: unknown): AppState | undefined;
+/** The app is alive in some form (a suspended background app still has its process). */
+export declare function isRunning(state: AppState): boolean;

package/types/e2e/src/driver/ios/hid-recovery.d.ts

@@ -23,6 +23,21 @@ export declare function stopResidentHelper(deps: HidRecoveryDeps, socketPath: st
  * the next call then fails `E_NOT_BOOTED`.
  */
 export declare function isHidLost(error: unknown): boolean;
+/**
+ * The error of a call on a physical iPhone whose runner host is gone (the host or the runner exited, or the socket
+ * closed): the driver's `E_HELPER_CRASHED`, however the error was wrapped.
+ */
+export declare function isRunnerLost(error: unknown): boolean;
+/**
+ * Whether a failed attempt is worth one recovery and the test running again: a simulator that lost its HID connection
+ * (reboot), or a physical iPhone that lost its runner host (restart the host; the phone is never rebooted).
+ */
+export declare function isRecoverableLoss(error: unknown, deviceKind: "physical" | undefined): boolean;
+/**
+ * Restarts a physical iPhone's runner host (`WARDEN_IOS_RUNNER_RESTART`, `{udid}` replaced): stop the host, start a
+ * new one on the same socket and wait until it answers. Never touches the phone itself (no reboot, no `simctl`).
+ */
+export declare function restartRunnerHost(deps: HidRecoveryDeps, argv: readonly string[] | undefined, udid: string): AsyncResult<void>;
 /**
  * Shuts the sim down and boots it again: `bootstatus -b` boots a shut-down sim itself and waits for it, and opens
  * no Simulator.app window (the same windowless path warden claims use). The caller reconnects the helper and