@delacour/warden-e2e 0.6.0 → 0.8.0

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

@@ -1,4 +1,6 @@
+import type { CameraCondition, ClockCondition, HostFault, LocationCondition, NetworkCondition, PermissionName, PermissionState, TextSize } from "../../../core/src/conditions/conditions.types";
 import type { AsyncResult } from "../../../types/src/result";
+import type { ScreenReaderState } from "../a11y/a11y.types";
 /**
  * The device driver contract every layer of warden-e2e builds on: the spec API (`screen`, `device`,
  * `app`), `warden ui`, specs and the devtools facet all talk to a `Driver`. Implementations:
@@ -8,7 +10,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" | "E_CAMERA_DEVICE";
 export type DriverError = {
     code: DriverErrorCode;
     message: string;
@@ -84,9 +86,32 @@ export type Element = {
     /** where to tap: iOS `interactable.actionable.at`, else the frame centre */
     tapPoint?: Point;
     pid?: number;
+    /** screen-reader facts beyond the base tree; absent when the backend can't read them */
+    a11y?: ElementA11y;
     depth: number;
     children: Element[];
 };
+/**
+ * Screen-reader facts. Android: from warden-uiad's `AccessibilityNodeInfo`. iOS: from the ios-inject UIView walk,
+ * merged by identifier / frame when an a11y read asks for it.
+ */
+export type ElementA11y = {
+    /** iOS accessibilityHint / RN accessibilityHint */
+    hint?: string;
+    /** iOS custom action names / Android node action labels (standard actions left out) */
+    actions?: readonly string[];
+    /** reachable by VoiceOver / TalkBack navigation */
+    focusable?: boolean;
+    /** iOS isAccessibilityElement / Android importantForAccessibility; `false` = skipped by screen readers */
+    important?: boolean;
+    /** Android: holds TalkBack's accessibility focus */
+    a11yFocused?: boolean;
+    liveRegion?: "polite" | "assertive";
+    /** iOS: index in the container's `accessibilityElements` order, when the app sets one */
+    order?: number;
+    /** iOS: position in the injected walk, which follows VoiceOver's own traversal across the whole screen */
+    traversal?: number;
+};
 export type SnapshotBackend = "axbridge" | "ax" | "uiautomator";
 export type ScreenInfo = {
     width: number;
@@ -114,6 +139,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 +168,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 +270,203 @@ 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; `null` puts them back. iOS: `simctl ui content_size` / `increase_contrast`, and
+     * `simctl spawn defaults write com.apple.Accessibility <Key>` (live) for reduce motion, bold text, reduce
+     * transparency, button shapes, differentiate without colour, on/off labels and the fake VoiceOver flag.
+     * Android: `font_scale`, `font_weight_adjustment`, `secure high_text_contrast_enabled` /
+     * `accessibility_display_inversion_enabled`, and reduce motion as `transition_animation_scale` 0 (what RN reads;
+     * off by default). No contrast switch on Android, no TalkBack until A11Y-7: `skipped` with the reason.
+     */
+    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>;
+    /**
+     * The simulated camera: `op` is the whole next state (a facing left out has no feed), `null` takes every feed off.
+     * Feeds are staged copies (`stageCameraFeed`). iOS: the injected dylib fakes the AVFoundation capture stack of the
+     * injected app (live; an app launched without the dylib gets it from the next launch, `appliesOnLaunch`). Android
+     * emulator: the emulator's `imagefile:` / `videofile:` camera. Physical devices: `E_UNSUPPORTED`.
+     */
+    camera(op: CameraCondition | null, opts?: SettingOptions): DriverResult<CameraState>;
     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;
+    /** iOS: Reduce Transparency */
+    reduceTransparency?: boolean;
+    /** iOS: Button Shapes */
+    buttonShapes?: boolean;
+    /** iOS: Differentiate Without Color */
+    differentiateWithoutColor?: boolean;
+    /** iOS: On/Off Labels */
+    onOffLabels?: boolean;
+    /** Android: High contrast text */
+    highContrastText?: boolean;
+    /** Android: colour inversion */
+    colorInversion?: boolean;
+    /** iOS: fake VoiceOver flag (`mode: "simulated"`); Android: real TalkBack (A11Y-7) */
+    screenReader?: 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[];
+    /** present when the op asked for `screenReader` and it was applied */
+    screenReader?: ScreenReaderState;
+    /** Android: the accessibility services / master switch the device had before TalkBack was turned on (`null` = unset), for the lease's condition record */
+    screenReaderPrevious?: {
+        services: string | null;
+        enabled: string | null;
+    };
+};
+export type BatteryOp = {
+    level?: number;
+    charging?: boolean;
+};
+export type BatteryState = {
+    level?: number;
+    charging?: boolean;
+    cosmetic: boolean;
+};
+/**
+ * The feeds now playing. `appliesOnLaunch`: no running app has the camera yet, the next launch picks it up (iOS);
+ * `appliesOnCameraOpen`: an open camera keeps the old frames until the app opens the camera again (Android emulator,
+ * which reads the file per camera open); `rebooted`: the emulator restarted to switch its camera source (image ↔ video).
+ */
+export type CameraState = {
+    feeds: CameraCondition;
+    appliesOnLaunch?: boolean;
+    appliesOnCameraOpen?: boolean;
+    rebooted?: 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/element-actions.d.ts

@@ -0,0 +1,16 @@
+import type { Driver, DriverResult, Element } from "./driver.types";
+/** The way content moves for a scroll: `down` reveals what is below (forward), `up` what is above (backward). */
+export type ScrollDirection = "up" | "down" | "left" | "right";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `SetsText`): act on a resolved element through
+ * the platform's accessibility actions instead of touches, for when a touch means something else. Android with
+ * TalkBack on: a tap only moves TalkBack's focus and a one-finger swipe navigates, so a locator `tap` / `swipe` asks
+ * here first. Each answers `true` when it did the action, `false` when the driver is not in that mode and the caller
+ * should send the touch as before. A raw coordinate tap never comes here: it stays a touch.
+ */
+export type ActsOnElements = {
+    pressElement(element: Element): DriverResult<boolean>;
+    /** `within`: the scrolling element; absent = the largest scrollable on screen */
+    scrollElement(direction: ScrollDirection, within?: Element): DriverResult<boolean>;
+};
+export declare function canActOnElements(driver: Driver): driver is Driver & ActsOnElements;

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

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

@@ -0,0 +1,124 @@
+import type { CameraCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Result } from "../../../../types/src/result";
+import type { DriverError } from "../driver.types";
+import type { ProxyAddress } from "../network-proxy";
+/**
+ * The injected dylib for iOS simulator apps (`native/ios-inject`): routes NSURLSession through the lease's shaping
+ * proxy and reports offline / a clock offset to the app, live, through a state file the dylib watches. This module is
+ * the host side: where the dylib is, the launch env that loads it, and the state file protocol. COND-12 (mock clock)
+ * reuses all of it and only sets `clockOffsetMs` (shift) or `clockFrozenMs` (hold).
+ */
+export declare const INJECT_DYLIB = "libwarden-inject.dylib";
+export declare const INJECT_DYLIB_ENV = "WARDEN_INJECT_DYLIB";
+/**
+ * The one message of the control channel. `seq` rises with every write (the dylib ignores a state whose `seq` it
+ * already applied); a field left out means "off" (`offline` false, `clockOffsetMs` 0), so a message is always the
+ * whole state, never a delta. `clockFrozenMs` (ms since the epoch) holds the wall clocks at one instant and wins over
+ * `clockOffsetMs`; left out, they run. `camera`: the feeds of an app launched with `WARDEN_CAMERA=1` (a facing left out
+ * has no camera); left out, no feeds.
+ */
+export type InjectState = {
+    seq: number;
+    offline?: boolean;
+    clockOffsetMs?: number;
+    clockFrozenMs?: number;
+    /** one-shot request (A11Y-1): walk the accessibility tree and write `<state>.a11y` before acknowledging this `seq` */
+    a11yRead?: boolean;
+    camera?: CameraCondition;
+};
+/** What the dylib answers in `<state>.ack` once it applied `seq` (`bundleId`: the app it loaded into; `camera`: launched with `WARDEN_CAMERA=1`). */
+export type InjectAck = {
+    seq: number;
+    pid: number;
+    proxy?: boolean;
+    camera?: boolean;
+    bundleId?: string;
+};
+export declare function encodeInjectState(state: InjectState): string;
+export declare function parseInjectState(text: string): InjectState | undefined;
+export declare function parseInjectAck(text: string): InjectAck | undefined;
+/** One directory per device: the dylib watches its directory, so two devices never wake each other's app. Core owns the path (release resets the file). */
+export declare const injectStatePath: (wardenHome: string, udid: string) => string;
+/** Where the dylib writes an accessibility read (`a11yRead`): next to the state file. */
+export declare const injectA11yPath: (statePath: string) => string;
+/** Where the dylib appends accessibility events (A11Y-8): JSON lines next to the state file. */
+export declare const injectEventsPath: (statePath: string) => string;
+export declare const injectAckPath: (statePath: string) => string;
+/**
+ * Launch env that loads the dylib. `proxy` is fixed for the life of the process (the lease's proxy keeps its port
+ * for the whole lease); everything that changes later goes through the state file.
+ */
+export declare function injectLaunchEnv(input: {
+    dylib: string;
+    statePath: string;
+    proxy?: ProxyAddress;
+    clockOffsetMs?: number;
+    clockFrozenMs?: number;
+    /** fake the capture stack from the state file's `camera` feeds (`WARDEN_CAMERA=1`) */
+    camera?: boolean;
+    debug?: boolean;
+}): Record<string, string>;
+/**
+ * Whether a launch loads the dylib. Never without a reason: a run with no condition keeps the plain launch (no
+ * dyld insertion, no watcher thread, no proxy hop).
+ */
+export declare function shouldInject(input: {
+    /** the lease has a live shaping proxy, or a non-trivial network condition was set */
+    networkActive: boolean;
+    /** a clock offset is set (COND-12) */
+    clockActive: boolean;
+    /** the lease has a camera feed: the dylib must be loaded at launch to fake the capture stack */
+    cameraActive?: boolean;
+    /** the caller asked for injection (`LaunchOptions.inject`, a suite that declares `conditions.network`) */
+    requested: boolean;
+}): boolean;
+export type LocateInjectInput = {
+    /** `WARDEN_INJECT_DYLIB` (a file) and `WARDEN_HELPER_DIR` (a directory that also holds the dylib) */
+    env: Readonly<Record<string, string | undefined>>;
+    execPath: string;
+    /** directory of this module (`packages/e2e/src/driver/ios`) */
+    importDir: string;
+    wardenHome: string;
+    version?: string;
+    exists: (path: string) => boolean;
+    realpath?: (path: string) => string;
+};
+/**
+ * Find `libwarden-inject.dylib`. Order mirrors `locateHelper`: `WARDEN_INJECT_DYLIB` → `WARDEN_HELPER_DIR` → next to
+ * the running `warden` → `<packages/e2e>/native/dist` → `$WARDEN_HOME/simd/<version>`. A set variable that points at
+ * nothing is an error.
+ */
+export declare function locateInjectDylib(input: LocateInjectInput): Result<string, DriverError>;
+/** File operations of the state channel, injected. */
+export type InjectFs = {
+    mkdir(path: string): void;
+    /** write `text` to `path` so a reader sees all of it or none (tmp + rename) */
+    writeAtomic(path: string, text: string): void;
+    read(path: string): string | undefined;
+    remove(path: string): void;
+    /** is `pid` a live process */
+    pidAlive(pid: number): boolean;
+};
+export declare const nodeInjectFs: InjectFs;
+/** The host end of the control channel for one device. */
+export type InjectChannel = {
+    readonly statePath: string;
+    /** Last state written (read back from disk, so another warden process's writes count). */
+    current(): InjectState;
+    /** Write the whole next state (`seq` assigned here). */
+    write(next: Omit<InjectState, "seq">): InjectState;
+    /** The injected process that answered last, when it is still alive and is the app under test. */
+    attached(): InjectAck | undefined;
+    /** Wait until the app acknowledged `seq`; `false` on timeout. */
+    acked(seq: number, timeoutMs: number): Promise<boolean>;
+    /** Forget the state and ack of a previous app (before a launch). */
+    reset(): void;
+};
+export declare function createInjectChannel(input: {
+    statePath: string;
+    fs?: InjectFs;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    /** the app under test; an ack from another app (another injected bundle still running) is ignored. None = any */
+    bundleId?: () => string | undefined;
+}): InjectChannel;

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

@@ -0,0 +1,73 @@
+import type { Result } from "../../../../types/src/result";
+import { type A11yEventsRead } from "../a11y-events";
+import type { DriverError, DriverResult, LaunchOptions, Rect, Snapshot } from "../driver.types";
+import { type InjectChannel, type InjectFs } from "./inject";
+/**
+ * iOS screen-reader facts (WDN-A11Y, A11Y-1). `warden-simd` (idb) has no hint, custom actions, `isAccessibilityElement`
+ * or order, so they come from the injected dylib's UIKit walk (`native/ios-inject`, op `a11yRead` on the state/ack file
+ * channel of `inject.ts`) and are merged into a snapshot's elements. The dylib is loaded only when asked for (the
+ * driver option `a11y` or `WARDEN_A11Y=1`); an app launched without it answers `E_UNSUPPORTED` with that hint, never a
+ * fabricated value.
+ */
+/** One entry of the dylib's walk, traversal order. */
+export type IosA11yNode = {
+    cls: string;
+    /** `isAccessibilityElement`: VoiceOver stops on it */
+    element: boolean;
+    label?: string;
+    hint?: string;
+    value?: string;
+    identifier?: string;
+    /** `UIAccessibilityTraits` bitmask (a hex string on the wire: bits above 2^53 do not survive JSON numbers) */
+    traits: bigint;
+    /** screen points */
+    frame: Rect;
+    /** `accessibilityCustomActions` names */
+    actions: readonly string[];
+    /** index in the container's `accessibilityElements`, only when the app set that array */
+    order?: number;
+};
+/** The dylib's `<state>.a11y` for request `req`, or why it is unusable (the message is for the user). */
+export declare function parseA11yDump(text: string, req: number): Result<IosA11yNode[], string>;
+/** Frames overlapping less than this (intersection over union) are not the same node. */
+export declare const MIN_FRAME_OVERLAP = 0.6;
+export type MergedA11y = {
+    snapshot: Snapshot;
+    matched: number;
+    unmatched: number;
+};
+/**
+ * Merge a walk into a snapshot (a new snapshot; the input is not touched). Rule, applied once per element in
+ * document order:
+ *  1. identifier: an element with an `identifier` takes the unused node with the same `id` (several: the larger frame
+ *     overlap wins);
+ *  2. frame: every element still without a node takes the unused node with the largest frame overlap of at least
+ *     {@link MIN_FRAME_OVERLAP}, greedily from the best pair down. A node whose `id` is set but different from the
+ *     element's identifier never matches by frame.
+ * Each node serves one element. Elements with no node keep `a11y` as it was (never invented).
+ */
+export declare function mergeA11y(snapshot: Snapshot, nodes: readonly IosA11yNode[]): MergedA11y;
+export type IosA11yDeps = {
+    channel: InjectChannel;
+    fs?: InjectFs;
+    /** the dylib path, resolved on first use so a run that never asks does not look for it */
+    dylib: () => Result<string, DriverError>;
+    /** was an a11y read asked for (driver option `a11y`, `WARDEN_A11Y=1`) */
+    requested: () => boolean;
+    debug?: boolean;
+    /** how long the app gets to answer a read (default {@link INJECT_ACK_MS}) */
+    timeoutMs?: number;
+    /** how long a launch gets to load the dylib (default {@link INJECT_LOAD_MS}) */
+    loadMs?: number;
+};
+export type IosA11y = {
+    /** Env that loads the dylib (no proxy) when an a11y read was asked for; `undefined`: launch plainly. */
+    launchEnv(opts: LaunchOptions): Promise<Result<Record<string, string> | undefined, DriverError>>;
+    /** After a launch that carried the dylib: wait until it loaded. */
+    confirmLoaded(): DriverResult<void>;
+    /** Read the app's UIKit accessibility tree now and merge it into `snapshot`. */
+    read(snapshot: Snapshot): DriverResult<Snapshot>;
+    /** Announcements and screen/layout notifications the app posted since byte offset `since` (A11Y-8). */
+    events(since?: number): DriverResult<A11yEventsRead>;
+};
+export declare function createIosA11y(deps: IosA11yDeps): IosA11y;