@delacour/warden-e2e 0.13.0 → 0.15.0

package/types/core/src/affected/affected.schema.d.ts

@@ -167,6 +167,7 @@ export declare const e2eSuiteSchema: z.ZodObject<{
         except: z.ZodOptional<z.ZodArray<z.ZodString>>;
         keep: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>]>>;
+    golden: z.ZodOptional<z.ZodBoolean>;
     biometrics: z.ZodOptional<z.ZodBoolean>;
     reclaim: z.ZodOptional<z.ZodEnum<{
         none: "none";
@@ -262,6 +263,10 @@ export declare const e2eSuiteSchema: z.ZodObject<{
             }>>;
             reduceMotion: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        keyboard: z.ZodOptional<z.ZodEnum<{
+            software: "software";
+            hardware: "hardware";
+        }>>;
     }, z.core.$strict>>;
     a11y: z.ZodOptional<z.ZodObject<{
         ignore: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/types/core/src/builds/builds.defaults.d.ts

@@ -12,6 +12,12 @@ export type BuildConfiguration = "Debug" | "Release";
 export declare const IOS_NATIVE_PREPARE: string;
 /** Local build command (run in the project root) when `build.<platform>` is not configured. */
 export declare function defaultBuildCommand(platform: Platform, configuration: BuildConfiguration, framework?: AppFramework): string;
+/**
+ * Android build: prebuild a CNG checkout that has no `android/`, then Gradle alone. Never `expo run:android`: it has no
+ * build-only mode (its `--no-install` skips dependency install, not the app's) and installs the APK on whichever
+ * emulator is booted, warden's or not. warden installs the cached build itself.
+ */
+export declare function androidGradleCommand(configuration: BuildConfiguration, framework?: AppFramework): string;
 /** What an iOS device build is signed with: the team (always) and, when set, the bundle id that replaces the project's. */
 export type IosDeviceBuild = {
     team: string;
@@ -55,6 +61,8 @@ export declare const EAS_TIMEOUT_MS: number;
 export declare const EAS_TRIGGER_GRACE_MS: number;
 /** Local native build timeout. */
 export declare const LOCAL_BUILD_TIMEOUT_MS: number;
+/** How often a local build nobody watches says it is still running (`still building ios (6m 0s): …`). */
+export declare const BUILD_HEARTBEAT_MS = 60000;
 /** Fingerprint command timeout. */
 export declare const FINGERPRINT_TIMEOUT_MS: number;
 /** Build-lock lease ttl; the lease also carries the holder's pid so it lives as long as the process. */

package/types/core/src/builds/config.schema.d.ts

@@ -358,6 +358,7 @@ export declare const wardenConfigSchema: z.ZodObject<{
             except: z.ZodOptional<z.ZodArray<z.ZodString>>;
             keep: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>]>>;
+        golden: z.ZodOptional<z.ZodBoolean>;
         biometrics: z.ZodOptional<z.ZodBoolean>;
         reclaim: z.ZodOptional<z.ZodEnum<{
             none: "none";
@@ -453,6 +454,10 @@ export declare const wardenConfigSchema: z.ZodObject<{
                 }>>;
                 reduceMotion: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
+            keyboard: z.ZodOptional<z.ZodEnum<{
+                software: "software";
+                hardware: "hardware";
+            }>>;
         }, z.core.$strict>>;
         a11y: z.ZodOptional<z.ZodObject<{
             ignore: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -606,6 +611,10 @@ export declare const wardenConfigSchema: z.ZodObject<{
             }>>;
             reduceMotion: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        keyboard: z.ZodOptional<z.ZodEnum<{
+            software: "software";
+            hardware: "hardware";
+        }>>;
     }, z.core.$strict>>;
     a11y: z.ZodOptional<z.ZodObject<{
         ignore: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/types/core/src/builds/define-config.d.ts

@@ -579,7 +579,7 @@ export interface WardenE2eSuite {
      * `"idle"`: leave them booted, so the next run skips the 10-30 s boot, and let `warden gc` shut
      * them down once they have sat idle. A failed run always leaves them up. `--no-shutdown` wins.
      *
-     * @default "always"
+     * @default "always" locally, "idle" under `CI` / `GITHUB_ACTIONS` (the runner is thrown away)
      */
     shutdown?: "always" | "idle" | undefined;
     /**
@@ -734,6 +734,14 @@ export interface WardenE2eSuite {
      * `biometrics`. Default false.
      */
     biometrics?: boolean | undefined;
+    /**
+     * iOS: simulators the run creates are cloned from a golden image (a first-booted, settled simulator built once
+     * per profile and runtime). Off: each is a fresh `simctl create` and first boot, and `warden ci cache --suite`
+     * prints no golden group. Existing pool devices are reused either way; `WARDEN_GOLDEN=0` turns it off everywhere.
+     *
+     * @default false
+     */
+    golden?: boolean | undefined;
     /**
      * What happens to the state of the devices of this run when they are released: `"erase"` (iOS: shutdown +
      * `simctl erase`; Android: uninstalls the third-party apps), `"uninstall"` (removes the user-installed apps) or

package/types/core/src/conditions/conditions.config.d.ts

@@ -1,6 +1,6 @@
 import { type Result } from "../../../types/src/result";
 import { z } from "zod";
-import { type A11yCondition, type ClockCondition, type LocationCondition, type NetworkCondition, type NetworkPreset, type PermissionName, type PermissionState } from "./conditions.types";
+import { type A11yCondition, type ClockCondition, type KeyboardCondition, type LocationCondition, type NetworkCondition, type NetworkPreset, type PermissionName, type PermissionState } from "./conditions.types";
 /** `network: { latencyMs, ... }`: the same fields as a `custom` network condition, without its `kind`. */
 declare const customNetworkSchema: z.ZodObject<{
     latencyMs: z.ZodOptional<z.ZodNumber>;
@@ -91,6 +91,10 @@ export declare const conditionsConfigSchema: z.ZodObject<{
         }>>;
         reduceMotion: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    keyboard: z.ZodOptional<z.ZodEnum<{
+        software: "software";
+        hardware: "hardware";
+    }>>;
 }, z.core.$strict>;
 export type ConditionsConfig = z.input<typeof conditionsConfigSchema>;
 /**
@@ -129,6 +133,7 @@ export type SuiteConditions = {
     locale?: string;
     timezone?: string;
     a11y?: A11yCondition;
+    keyboard?: KeyboardCondition;
 };
 /** A config as conditions: shaped values, with a text size resolved. */
 export declare function normalizeConditions(config: ConditionsConfig): Result<{

package/types/core/src/conditions/conditions.types.d.ts

@@ -127,6 +127,26 @@ export type BatteryCondition = {
     charging?: boolean;
     cosmetic?: boolean;
 };
+export type KeyboardMode = "software" | "hardware";
+export declare const KEYBOARD_MODES: readonly KeyboardMode[];
+/** What every warden-leased device starts on and what release restores: the on-screen keyboard shows. */
+export declare const DEFAULT_KEYBOARD_MODE: KeyboardMode;
+/** `software`: the on-screen keyboard shows; `hardware`: it is hidden, input arrives as from a connected keyboard. */
+export type KeyboardCondition = {
+    mode: KeyboardMode;
+    previousIme?: ImeState;
+};
+/** Global settings holding the IME state `hardware` mode switched off (survives the driver process). */
+export declare const IME_STASH_ENABLED = "warden_ime_enabled";
+export declare const IME_STASH_DEFAULT = "warden_ime_default";
+/**
+ * Android only: the input methods `hardware` mode switched off, recorded so release puts them back exactly.
+ * `enabled` is `settings secure enabled_input_methods` and `default` is `default_input_method` (empty = none).
+ */
+export type ImeState = {
+    enabled: string;
+    default: string;
+};
 export type CameraFacing = "back" | "front";
 export declare const CAMERA_FACINGS: readonly CameraFacing[];
 /** A staged asset the simulated camera plays; `path` is the staged copy under the device's camera dir. */
@@ -150,6 +170,7 @@ export type ConditionValues = {
     a11y: A11yCondition;
     battery: BatteryCondition;
     camera: CameraCondition;
+    keyboard: KeyboardCondition;
 };
 export type ConditionArea = keyof ConditionValues;
 /** Display/iteration order; also the order undo resets areas in. */

package/types/core/src/conditions/inject-state.d.ts

@@ -1,3 +1,4 @@
+import { type ConditionArea } from "./conditions.types";
 /**
  * The state file an iOS app launched with `libwarden-inject.dylib` watches (offline flag, wall-clock offset /
  * freeze). The e2e driver owns the full format (`packages/e2e/src/driver/ios/inject.ts`); core only knows where it
@@ -7,7 +8,7 @@
 export declare function injectStatePath(wardenHome: string, udid: string): string;
 /**
  * Write `{ seq: previous + 1, offline: false, clockOffsetMs: 0, camera: {} }` (no freeze, no camera feeds) when a state file exists; the dylib
- * applies any higher `seq`. No file = no injected app was ever launched on the device: nothing to do.
+ * applies any higher `seq`. `keyboard` stays what the file had, except when `area` is `keyboard`: then it goes back to the default. No file = no injected app was ever launched on the device: nothing to do.
  * Returns an error message, or undefined.
  */
-export declare function neutralizeInjectState(path: string): string | undefined;
+export declare function neutralizeInjectState(path: string, area?: ConditionArea): string | undefined;

package/types/e2e/src/a11y/a11y-target.d.ts

@@ -13,6 +13,8 @@ export type A11yTarget = {
     }): Promise<Result<AnnouncementMatch, DriverError>>;
     /** the current screen as text with the `--a11y` columns (failure evidence); undefined when it cannot be read */
     a11yScreen(): Promise<string | undefined>;
+    /** whether the on-screen keyboard is up right now (one fresh read) */
+    keyboardVisible(): Promise<boolean>;
     /** the assertion timeout in ms */
     assertionTimeout(): number;
     /** one reported step */

package/types/e2e/src/conditions/condition-events.d.ts

@@ -1,4 +1,4 @@
-import type { A11yCondition, BatteryCondition, CameraCondition, ClockCondition, HostFault, LocaleCondition, LocationCondition, NetworkCondition, PermissionCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yCondition, BatteryCondition, CameraCondition, ClockCondition, HostFault, KeyboardCondition, LocaleCondition, LocationCondition, NetworkCondition, PermissionCondition } from "../../../core/src/conditions/conditions.types";
 /**
  * One applied condition transition, the evidence line that lets a failure show which network/location was
  * active. Written to `results.jsonl` beside the test results (`readResults` skips lines that are not a
@@ -39,6 +39,11 @@ export type ConditionEvent = {
     area: "battery";
     value: BatteryCondition;
     at: number;
+} | {
+    type: "condition";
+    area: "keyboard";
+    value: KeyboardCondition;
+    at: number;
 } | {
     type: "condition";
     area: "camera";

package/types/e2e/src/conditions/device-conditions.d.ts

@@ -1,6 +1,6 @@
 import { type NetworkInput } from "../../../core/src/conditions/conditions.config";
-import type { CameraFacing, ClockCondition, HostFault, LatLon, LocationCondition, LocationScenario, NetworkCondition } from "../../../core/src/conditions/conditions.types";
-import type { A11yOp, A11yState, BatteryOp, BatteryState, CameraState, Driver, LocaleState, NetworkState, PermissionGrants, PermissionsState, PushPayload, SettingOptions, TimezoneState } from "../driver/driver.types";
+import { type CameraFacing, type ClockCondition, type HostFault, type KeyboardMode, type LatLon, type LocationCondition, type LocationScenario, type NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yOp, A11yState, BatteryOp, BatteryState, CameraState, Driver, KeyboardResult, LocaleState, NetworkState, PermissionGrants, PermissionsState, PushPayload, SettingOptions, TimezoneState } from "../driver/driver.types";
 import type { E2eEnv } from "../env";
 import { type ConditionSink } from "./condition-events";
 import type { ConditionRecorder } from "./lease-recorder";
@@ -160,6 +160,12 @@ export type DeviceConditions = {
     a11y(op: A11yOp | null): Promise<A11yState>;
     /** Battery level and charging. Android emulators: real. iOS: the status bar only (`cosmetic: true`). `null` resets. */
     battery(op: BatteryOp | null): Promise<BatteryState>;
+    /**
+     * The on-screen keyboard: `software` (the default) keeps it up while the spec types, `hardware` hides it (input as from
+     * a connected keyboard), `toggle` flips the mode this spec has in place. Live, no relaunch. Put back to the suite's
+     * `conditions.keyboard` (else `software`) when the test ends.
+     */
+    keyboard(mode: KeyboardMode | "toggle"): Promise<KeyboardResult>;
     /** Android: a critical trim-memory signal to the running app. iOS: `E_UNSUPPORTED` (no delivery mechanism works). */
     memoryWarning(options?: SettingOptions): Promise<void>;
     /** iOS: delivers an APNs payload (`{ aps: { alert: ... } }`) to the app. Android: `E_UNSUPPORTED`. */

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

@@ -81,8 +81,8 @@ export type Device = DeviceA11y & {
     clipboard(): Promise<string>;
     setClipboard(text: string): Promise<void>;
     /**
-     * Dismisses the soft keyboard when the snapshot shows one, else does nothing. iOS presses Enter
-     * (which may submit the focused field); Android presses back.
+     * Dismisses the soft keyboard when the snapshot shows one, else does nothing. iOS resigns the first responder
+     * (an app launched without the injected library gets Enter, which may submit the field); Android presses back.
      */
     hideKeyboard(): Promise<void>;
     /** Saves `<attemptDir>/screenshots/NNN-<name>.png` and returns the path. */
@@ -125,6 +125,14 @@ export type Device = DeviceA11y & {
     a11y: DeviceConditions["a11y"];
     /** Battery level and charging: real on Android emulators, status bar only on iOS (`cosmetic: true`). */
     battery: DeviceConditions["battery"];
+    /**
+     * The on-screen keyboard mode: `"software"` (the default: it stays up while the spec types), `"hardware"` (hidden,
+     * as with a connected keyboard) or `"toggle"`. Live. Put back to the suite's `conditions.keyboard` when the test
+     * ends. Physical iPhones: `E_UNSUPPORTED`.
+     */
+    keyboard: DeviceConditions["keyboard"];
+    /** Whether the on-screen keyboard is up now, read from the accessibility tree. `expect(device).toHaveKeyboard()` polls it. */
+    keyboardVisible(): Promise<boolean>;
     /**
      * Simulated camera: `set("fixtures/qr.png", { facing })`, `clear`, `status`. The asset (png, jpg, heic, mp4, mov; path relative
      * to the spec file) plays in the app's real camera. iOS: live in an app launched with the camera, else from the next launch.

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

@@ -1,4 +1,4 @@
-import type { PermissionName, PermissionState } from "../../../../core/src/conditions/conditions.types";
+import { type KeyboardMode, type PermissionName, type PermissionState } from "../../../../core/src/conditions/conditions.types";
 import type { Driver } from "../driver.types";
 import type { AdbSession } from "./adb-session";
 import { type TalkBackControl } from "./android-talkback";
@@ -35,7 +35,14 @@ export type AndroidSettingsDeps = {
     /** is `warden-uiad` how this driver reads the screen (TalkBack mode needs it: the dump fallback unbinds TalkBack); default false */
     uiadAvailable?: () => boolean;
 };
-export type AndroidSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push">;
+export type AndroidSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push" | "keyboard" | "keyboardState">;
+/**
+ * Whether the IME window is up: `dumpsys window InputMethod` says `isVisible=true` while it is (the uiautomator dump
+ * carries the app's window only, so the keyboard is never in the snapshot on Android).
+ */
+export declare function imeVisibleIn(dump: string): boolean;
 export declare function createAndroidSettings(deps: AndroidSettingsDeps): AndroidSettings & {
     talkback: TalkBackControl;
+    keyboardMode(): Promise<KeyboardMode>;
+    keyboardVisible(): Promise<boolean>;
 };

package/types/e2e/src/driver/ax-wedge.d.ts

@@ -0,0 +1,38 @@
+import type { Driver, DriverResult } from "./driver.types";
+/**
+ * The iOS helper's check for a wedged accessibility service (`warden-simd` `AXWedgeRecovery`): when both AX readers
+ * stay silent and the sim log names the wedge, it restarts backboardd (which quits the foreground app), ends its stale
+ * guests and reads on. `last` is the latest check; `agoMs` counts from its end.
+ */
+export type AxWedgeState = {
+    restarts: number;
+    maxRestarts: number;
+    recovering: boolean;
+    /** `recover: true` only: what the check that ask ran (or joined) found; absent when none ran (budget spent) */
+    checked?: "restarted" | "not-wedged" | "failed";
+    last?: {
+        outcome: "restarted";
+        agoMs: number;
+        ms?: number;
+    } | {
+        outcome: "not-wedged";
+        agoMs: number;
+    } | {
+        outcome: "failed";
+        agoMs: number;
+        error: string;
+    };
+};
+/**
+ * Optional capability next to the frozen `Driver` (iOS simulators): read the helper's wedge state, or with
+ * `recover: true` run the check now and answer once it is over. A helper built before it answers `E_UNSUPPORTED`
+ * `detail.reason: "helper_outdated"`.
+ */
+export type RecoversAxWedge = {
+    axWedge(opts?: {
+        recover?: boolean;
+    }): DriverResult<AxWedgeState>;
+};
+export declare function canRecoverAxWedge(driver: Driver): driver is Driver & RecoversAxWedge;
+/** Whether the helper restarted backboardd within the last `windowMs` (e.g. during the test that just failed). */
+export declare function restartedWithin(state: AxWedgeState, windowMs: number): boolean;

package/types/e2e/src/driver/bridge-stall.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { type SpanDetail } from "./span-detail";
+/**
+ * What one iOS `axbridge` fallback or stall looked like, as `warden-simd` reports it (`fallback.stall` on a snapshot,
+ * `detail.stall` on a failed read). Recorded in `trace.jsonl` (the `stall*` span fields), `results.jsonl` (`bridge`)
+ * and under the header of `screen-at-failure.txt`.
+ */
+export declare const bridgeStallSchema: z.ZodObject<{
+    stage: z.ZodString;
+    readMs: z.ZodOptional<z.ZodNumber>;
+    deadlineMs: z.ZodOptional<z.ZodNumber>;
+    guestAgeMs: z.ZodOptional<z.ZodNumber>;
+    cold: z.ZodBoolean;
+    cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+    probes: z.ZodNumber;
+    recycles: z.ZodOptional<z.ZodNumber>;
+    recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+    axWedge: z.ZodOptional<z.ZodString>;
+    axWedgeRestarts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type BridgeStall = {
+    stage: string;
+    readMs?: number;
+    deadlineMs?: number;
+    guestAgeMs?: number;
+    cold: boolean;
+    cooldownRemainingMs?: number;
+    probes: number;
+    recycles?: number;
+    recyclesExhausted?: boolean;
+    axWedge?: string;
+    axWedgeRestarts?: number;
+};
+/** Only the fields of the schema, so a newer helper's extra keys stay off the span and out of the results. */
+export declare function toBridgeStall(wire: z.infer<typeof bridgeStallSchema>): BridgeStall;
+/** Leaves the stall on the span timing the read (`stallStage`, `stallReadMs`, …). */
+export declare function noteBridgeStall(stall: BridgeStall): void;
+/** The stall a span recorded, or undefined when it has none. */
+export declare function bridgeStallFromSpan(detail: SpanDetail | undefined): BridgeStall | undefined;
+/** One line for a log or a report: `stage read · read 4012 ms of a 4000 ms deadline · warm · …`. */
+export declare function formatBridgeStall(stall: BridgeStall): string;

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

@@ -1,6 +1,7 @@
-import type { CameraCondition, ClockCondition, HostFault, LocationCondition, NetworkCondition, PermissionName, PermissionState, TextSize } from "../../../core/src/conditions/conditions.types";
+import type { CameraCondition, ClockCondition, HostFault, ImeState, KeyboardMode, 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";
+import type { BridgeStall } from "./bridge-stall";
 /**
  * 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:
@@ -136,9 +137,12 @@ export type Snapshot = {
     modal?: ModalInfo;
     /**
      * Set when `backend` answered because this reader failed or was skipped first (iOS: `axbridge` stalled, `ax` read in
-     * its place). The fallback reader can lack what the first one has, so a missing node on such a snapshot is not final.
+     * its place). The fallback reader can lack what the first one has, so a missing node on such a snapshot is not final:
+     * the iOS helper probes the first reader in the background, and a later read is back on it once it answers.
      */
     fellBackFrom?: SnapshotBackend;
+    /** iOS: what the bridge failure behind `fellBackFrom` looked like, when the helper reported it */
+    bridgeStall?: BridgeStall;
 };
 export type Orientation = "portrait" | "portraitUpsideDown" | "landscapeLeft" | "landscapeRight";
 export type HardwareButton = "home" | "back" | "lock" | "volumeUp" | "volumeDown" | "shake";
@@ -340,6 +344,21 @@ export interface Driver {
      * OS and the app. iOS: status bar override only (`cosmetic: true`): the app still reads the real battery.
      */
     battery(op: BatteryOp | null): DriverResult<BatteryState>;
+    /**
+     * The on-screen keyboard mode (KBD-2): `software` keeps it up while warden types, `hardware` hides it (input as from
+     * a connected keyboard). Live, no relaunch. iOS simulator: the injected dylib (`appliesOnLaunch` when the running
+     * app was launched without it). Android: disables the soft IMEs (stashed on the device, restored by `software` and on release). Physical iOS:
+     * `E_UNSUPPORTED`.
+     */
+    keyboard(mode: KeyboardMode): DriverResult<KeyboardResult>;
+    /** The mode in force and whether a keyboard is on screen now (a `keyboard` element in the accessibility tree). */
+    keyboardState(): DriverResult<KeyboardState>;
+    /**
+     * Takes the on-screen keyboard down without a keystroke that could submit a form. iOS simulator: the injected
+     * dylib resigns the first responder (`via: "resign"`); an app launched without it falls back to Enter (`via:
+     * "key"`, with a warning in the log). Android: back. Physical iPhone: Enter.
+     */
+    dismissKeyboard(): DriverResult<DismissKeyboardResult>;
     /** 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`. */
@@ -439,6 +458,20 @@ export type A11yState = {
         enabled: string | null;
     };
 };
+/** `previousIme` (Android `hardware`): the input methods switched off, for the lease record. */
+export type KeyboardResult = {
+    mode: KeyboardMode;
+    appliesOnLaunch?: boolean;
+    previousIme?: ImeState;
+};
+/** `via`: how the keyboard was dismissed; `key` (Enter) can submit the focused field. */
+export type DismissKeyboardResult = {
+    via: "resign" | "key" | "back";
+};
+export type KeyboardState = {
+    mode: KeyboardMode;
+    visible: boolean;
+};
 export type BatteryOp = {
     level?: number;
     charging?: boolean;

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

@@ -1,4 +1,4 @@
-import type { CameraCondition } from "../../../../core/src/conditions/conditions.types";
+import { type CameraCondition, type KeyboardMode } 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";
@@ -25,6 +25,17 @@ export type InjectState = {
     /** one-shot request (A11Y-1): walk the accessibility tree and write `<state>.a11y` before acknowledging this `seq` */
     a11yRead?: boolean;
     camera?: CameraCondition;
+    /**
+     * The on-screen keyboard (KBD-2): `software` keeps it up while warden types, `hardware` lets iOS minimise it. Unlike
+     * the other fields a message that leaves it out keeps what the file had (see `createInjectChannel`), so a network or
+     * a11y write never undoes it.
+     */
+    keyboard?: KeyboardMode;
+    /**
+     * one-shot request: resign the first responder (the keyboard goes away without a Return that could submit the form)
+     * before acknowledging this `seq`. Written, never read back, so a later write cannot repeat it.
+     */
+    dismissKeyboard?: boolean;
 };
 /** 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 = {
@@ -56,6 +67,8 @@ export declare function injectLaunchEnv(input: {
     clockFrozenMs?: number;
     /** fake the capture stack from the state file's `camera` feeds (`WARDEN_CAMERA=1`) */
     camera?: boolean;
+    /** the keyboard mode the app starts in (`WARDEN_KEYBOARD`); the state file's `keyboard` overrides it live */
+    keyboard?: KeyboardMode;
     debug?: boolean;
 }): Record<string, string>;
 /**
@@ -69,6 +82,8 @@ export declare function shouldInject(input: {
     clockActive: boolean;
     /** the lease has a camera feed: the dylib must be loaded at launch to fake the capture stack */
     cameraActive?: boolean;
+    /** the lease's keyboard mode is `software` (the default): the dylib keeps the on-screen keyboard up while warden types */
+    keyboardActive?: boolean;
     /** the caller asked for injection (`LaunchOptions.inject`, a suite that declares `conditions.network`) */
     requested: boolean;
 }): boolean;
@@ -111,7 +126,7 @@ export type InjectChannel = {
     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). */
+    /** Forget the state and ack of a previous app (before a launch); the keyboard mode is the lease's, so it stays. */
     reset(): void;
 };
 export declare function createInjectChannel(input: {

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

@@ -3,6 +3,7 @@ import type { E2eEnv } from "../../env";
 import type { ReadsA11yEvents } from "../a11y-events";
 import type { ReadsA11y } from "../a11y-read";
 import type { ProbesFrontmost, ReadsAlertOn } from "../alerts";
+import type { RecoversAxWedge } from "../ax-wedge";
 import type { ClockRecorder } from "../clock-recorder";
 import type { Driver, DriverResult, KeyName, Logger } from "../driver.types";
 import type { AuditsNatively } from "../native-audit";
@@ -11,6 +12,7 @@ import type { PastesText, SelectsAll } from "../typing";
 import { type InjectFs } from "./inject";
 import { type IosA11y } from "./ios-a11y";
 import { type IosNativeAudit, type IosNativeAuditOptions } from "./ios-audit";
+import { type IosKeyboard } from "./ios-keyboard";
 import { type IosNetwork } from "./ios-network";
 import { type SwappableClient } from "./ios-session";
 import { type IosSettings, type StagedSettings } from "./ios-settings";
@@ -27,7 +29,7 @@ import type { SimdSpawn } from "./simd-transport";
  */
 export type IosDriverEnv = Pick<E2eEnv, "simd" | "simdSocket" | "helperDir"> & Partial<Pick<E2eEnv, "wardenVersion">>;
 /** The iOS driver is a `Driver` plus the optional capabilities of `driver/alerts.ts`. */
-export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost & ReadsA11y & ReadsA11yEvents & AuditsNatively;
+export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost & RecoversAxWedge & ReadsA11y & ReadsA11yEvents & AuditsNatively;
 export type OpenIosDriverOptions = {
     udid: string;
     env?: IosDriverEnv;
@@ -88,9 +90,20 @@ export type OpenIosDriverOptions = {
  * How long the first snapshot of a session waits for an in-sim bridge that is up but silent. A freshly cloned
  * simulator on a loaded host can take longer than one read's budget (axbridge 4 s + AX fallback 5 s) to answer the
  * first time, and every read after it is fast, so the first one retries while the failure says "not ready yet".
- * Once a read or a rebind has succeeded the normal per-call budgets apply.
+ * Once a read has succeeded the normal per-call budgets apply. Inside a screen-layer poll (`withReadDeadline`) the
+ * wait also ends at that poll's deadline, so a 5 s assertion is not held for the whole budget.
  */
 export declare const COLD_BRIDGE_BUDGET_MS = 60000;
+/**
+ * warden-simd's deadline for the first `axbridge` read of a cold guest (helper start, a recycled guest, an app just
+ * launched): `BridgeDeadline.defaultColdReadMs`, or `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS`. On a 3-vCPU runner that
+ * first read takes 4-11 s; warm reads keep the 4 s deadline.
+ */
+export declare const BRIDGE_COLD_DEADLINE_MS = 12000;
+/** The request timeout of a read while the bridge is cold, so the client never gives up before the helper's deadline. */
+export declare const COLD_READ_TIMEOUT_MS: number;
+/** {@link COLD_READ_TIMEOUT_MS}, following a `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS` the helper also reads. */
+export declare function coldReadTimeoutMs(env?: Readonly<Record<string, string | undefined>>): number;
 /** USB HID keyboard-page usage ids for the keys `Driver.key` offers. */
 export declare const KEY_USAGE: Readonly<Record<KeyName, number>>;
 /** The fields of a failed snapshot's `detail` the helper sets (which reader, why, both readers' errors), on its span. */
@@ -112,6 +125,8 @@ export declare function createIosDriver(swap: SwappableClient, simctl: Simctl, o
     }) => IosSettings;
     /** screen-reader facts from the injected dylib (`ios-a11y.ts`); absent: `readA11y` answers `E_UNSUPPORTED` */
     a11y?: () => IosA11y;
+    /** the on-screen keyboard mode (`ios-keyboard.ts`); absent: `keyboard` answers `E_UNSUPPORTED` */
+    keyboard?: () => IosKeyboard;
     /** per-app network conditions (`ios-network.ts`); absent: `network` answers `E_UNSUPPORTED` */
     /** the XCUITest audit (`ios-audit.ts`); absent: `auditNatively` skips with a reason */
     nativeAudit?: (ctx: {

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

@@ -0,0 +1,39 @@
+import { type KeyboardMode } from "../../../../core/src/conditions/conditions.types";
+import type { Result } from "../../../../types/src/result";
+import type { Driver, DriverError, DriverResult } from "../driver.types";
+import { type InjectChannel } from "./inject";
+/**
+ * The on-screen keyboard of an iOS simulator app (KBD-2). HID typing makes iOS treat a hardware keyboard as attached
+ * and minimise the software keyboard; the injected dylib answers `-[UIKeyboardImpl isMinimized]` with NO while the mode
+ * is `software`, and re-lays the input views on every change. The mode lives in the state file's `keyboard` field (the
+ * lease's, so it survives an app relaunch) and in `WARDEN_KEYBOARD` at launch.
+ */
+export type IosKeyboardDeps = {
+    channel: InjectChannel;
+    /** where `libwarden-inject.dylib` is */
+    dylib: () => Result<string, DriverError>;
+    debug?: boolean;
+};
+export type IosKeyboard = {
+    /** the mode in force: the state file's, else the default */
+    mode(): KeyboardMode;
+    /**
+     * Env that loads the dylib with the keyboard mode, for a launch no other layer already injects (`undefined`: those
+     * layers carry the dylib; `WARDEN_KEYBOARD` goes through `launchMode`). A dylib that cannot be found is no launch
+     * failure: the app runs plain, with the keyboard as iOS decides.
+     */
+    launchEnv(): Record<string, string> | undefined;
+    /** `WARDEN_KEYBOARD` to merge into the env of a launch that carries the dylib already */
+    launchMode(): Record<string, string>;
+    /** after a launch that carried the dylib on its own: wait until it loaded */
+    confirmLoaded(): DriverResult<void>;
+    keyboard: Driver["keyboard"];
+    /**
+     * Resign the first responder in the app (the dylib, on the main thread), acknowledged through the channel.
+     * `attached: false`: no app with the dylib is running, nothing was written and the caller falls back.
+     */
+    dismiss(): DriverResult<{
+        attached: boolean;
+    }>;
+};
+export declare function createIosKeyboard(deps: IosKeyboardDeps): IosKeyboard;

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

@@ -21,6 +21,8 @@ export type SimdEventMap = {
 };
 export type RequestOptions = {
     timeoutMs?: number;
+    /** a floor for this request's timeout (a cold bridge read): raises the default or `timeoutMs`, never lowers it */
+    minTimeoutMs?: number;
 };
 export type SimdClient = {
     /** the handshake of the current helper process (refreshed after a respawn) */