@delacour/warden-e2e 0.6.0 → 0.8.0

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

@@ -0,0 +1,36 @@
+import type { Exec } from "../../../../core/src/exec";
+import type { RunnerSourceFiles } from "../../../../core/src/ios-runner/runner-build.types";
+import { type AsyncResult } from "../../../../types/src/result";
+import type { Logger } from "../driver.types";
+import type { NativeAuditOptions, NativeAuditResult } from "../native-audit";
+import { type SimRunnerDeps } from "./sim-runner";
+/**
+ * The iOS Simulator's XCUITest accessibility audit: the runner build (cached, unsigned), the runner process and the
+ * `audit` op behind `AuditsNatively`. Without runner sources the audit is skipped with the reason.
+ */
+export type IosNativeAudit = {
+    audit(options: NativeAuditOptions): Promise<NativeAuditResult>;
+    close(): Promise<void>;
+};
+export type IosNativeAuditOptions = {
+    udid: string;
+    exec: Exec;
+    /** the app the audit checks when the caller names none */
+    bundleId: () => string | undefined;
+    env?: Record<string, string | undefined>;
+    wardenHome?: string;
+    version?: string;
+    log?: Logger;
+    /** the runner's Xcode project as text files; default: this checkout's `packages/e2e/native` when running from source */
+    runnerSources?: () => AsyncResult<RunnerSourceFiles>;
+    /** test seams */
+    ensureBuild?: SimRunnerDeps["ensureBuild"];
+    spawn?: SimRunnerDeps["spawn"];
+    connect?: SimRunnerDeps["connect"];
+};
+/**
+ * `packages/e2e/native` of the checkout this file runs from; in a bundled install (no checkout beside it) the blob
+ * embedded in the compiled `warden` binary, which a spec process (the same binary) sees too.
+ */
+export declare function checkoutRunnerSources(importDir?: string, embedded?: () => AsyncResult<RunnerSourceFiles>): AsyncResult<RunnerSourceFiles>;
+export declare function createIosNativeAudit(o: IosNativeAuditOptions): IosNativeAudit;

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

@@ -1,9 +1,19 @@
 import type { Exec } from "../../../../core/src/exec";
 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 { ClockRecorder } from "../clock-recorder";
 import type { Driver, DriverResult, KeyName, Logger } from "../driver.types";
+import type { AuditsNatively } from "../native-audit";
+import type { NetworkProxyPort } from "../network-proxy";
 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 IosNetwork } from "./ios-network";
 import { type SwappableClient } from "./ios-session";
+import { type IosSettings, type StagedSettings } from "./ios-settings";
 import { type Simctl } from "./simctl";
 import { type SimdClient } from "./simd-client";
 import type { SimdSpawn } from "./simd-transport";
@@ -16,7 +26,7 @@ import type { SimdSpawn } from "./simd-transport";
  */
 export type IosDriverEnv = Pick<E2eEnv, "simd" | "simdSocket" | "helperDir">;
 /** The iOS driver is a `Driver` plus the optional capabilities of `driver/alerts.ts`. */
-export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost;
+export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost & ReadsA11y & ReadsA11yEvents & AuditsNatively;
 export type OpenIosDriverOptions = {
     udid: string;
     env?: IosDriverEnv;
@@ -46,8 +56,30 @@ export type OpenIosDriverOptions = {
     defaultTimeoutMs?: number;
     /** log each helper op and simctl call with its duration (`WARDEN_E2E_DEBUG=1`) */
     debug?: boolean;
+    /**
+     * The lease's shaping proxy (`leaseNetworkProxy`). Without it `network` / `networkFaults` answer `E_UNSUPPORTED`:
+     * a driver opened by a bare caller has no lease to hang a proxy on.
+     */
+    networkProxy?: NetworkProxyPort;
+    /** told about every successful `clock` op, so the lease records the `clock` area (`leaseClockRecorder`) */
+    clockRecorder?: ClockRecorder;
+    /** the session's app (`WARDEN_BUNDLE_ID`): the default target of permissions, push and locale */
+    bundleId?: string;
+    /** where a staged timezone / locale is kept between processes (default: `<wardenHome>/launch-settings/<udid>.json`) */
+    stagedSettings?: StagedSettings;
+    /** state-file operations of the injected dylib's control channel, injected for tests */
+    injectFs?: InjectFs;
+    /**
+     * Launch apps with the injected library so `readA11y` works (hint, custom actions, order). Default: `WARDEN_A11Y=1`.
+     * Off, a launch pays nothing for it.
+     */
+    a11y?: boolean;
     /** CoreSimulator devices directory for the host-side `AutomationEnabled` check (default `~/Library/Developer/CoreSimulator/Devices`) */
     devicesRoot?: string;
+    /** the runner's Xcode project as text files for the XCUITest audit (default: this checkout when run from source) */
+    runnerSources?: IosNativeAuditOptions["runnerSources"];
+    /** test seams for the XCUITest audit's runner */
+    nativeAudit?: Pick<IosNativeAuditOptions, "ensureBuild" | "spawn" | "connect">;
 };
 /** USB HID keyboard-page usage ids for the keys `Driver.key` offers. */
 export declare const KEY_USAGE: Readonly<Record<KeyName, number>>;
@@ -56,6 +88,23 @@ export declare function createIosDriver(swap: SwappableClient, simctl: Simctl, o
     now: () => number;
     sleep: (ms: number) => Promise<void>;
     log?: Logger;
+    /** told about every successful `clock` op */
+    clockRecorder?: ClockRecorder;
+    /** device settings (`ios-settings.ts`); absent: those ops answer `E_UNSUPPORTED` */
+    settings?: (ctx: {
+        lastBundle: () => string | undefined;
+    }) => IosSettings;
+    /** screen-reader facts from the injected dylib (`ios-a11y.ts`); absent: `readA11y` answers `E_UNSUPPORTED` */
+    a11y?: () => IosA11y;
+    /** 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: {
+        lastBundle: () => string | undefined;
+    }) => IosNativeAudit;
+    network?: (deps: {
+        lastBundle: () => string | undefined;
+        relaunch: (bundleId: string) => DriverResult<void>;
+    }) => IosNetwork;
 }): IosDriver;
 /**
  * Open the iOS driver for `udid`. Writes `AutomationEnabled` (best effort) while the helper starts.

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

@@ -0,0 +1,51 @@
+import type { CameraCondition, ClockCondition, HostFault, NetworkCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Result } from "../../../../types/src/result";
+import type { CameraState, ClockState, DriverError, DriverResult, LaunchOptions, NetworkOptions, NetworkState } from "../driver.types";
+import { type NetworkProxyPort } from "../network-proxy";
+import { type InjectChannel } from "./inject";
+/**
+ * iOS simulator network conditions: a simulator shares the host network, so nothing can shape one device. Instead
+ * the app is launched with `libwarden-inject.dylib` (see `inject.ts`), which routes its NSURLSession traffic
+ * through the lease's shaping proxy; the proxy does latency / bandwidth / loss / faults, and an `offline` flag in
+ * the dylib's state file makes the app's own reachability APIs say so. Presets and offline switch live over the
+ * proxy's control channel and the state file. Only the first enable needs a launch that carries the dylib.
+ */
+/** How long the injected app gets to acknowledge a state write (the dylib applies it on a dispatch source). */
+export declare const INJECT_ACK_MS = 3000;
+/** How long a fresh launch gets to load the dylib and acknowledge its first state. */
+export declare const INJECT_LOAD_MS = 8000;
+export type IosNetworkDeps = {
+    proxy: NetworkProxyPort;
+    channel: InjectChannel;
+    /** the dylib path, resolved on first use so a run without conditions never looks for it */
+    dylib: () => Result<string, DriverError>;
+    /** is `bundleId` running now */
+    isRunning: (bundleId: string) => DriverResult<boolean>;
+    /** the last app this driver launched */
+    lastBundle: () => string | undefined;
+    /** launch `bundleId` again with the dylib (late-bound: the driver's own `app.launch`) */
+    relaunch: (bundleId: string) => DriverResult<void>;
+    debug?: boolean;
+    /** wall time, ms (default `Date.now`); `fixed` clocks are an offset from it */
+    now?: () => number;
+};
+export type IosNetwork = {
+    network(op: NetworkCondition, opts?: NetworkOptions): DriverResult<NetworkState>;
+    networkFaults(faults: readonly HostFault[]): DriverResult<{
+        notes: readonly string[];
+    }>;
+    /** Env to merge into a launch (`undefined`: launch plainly). Stages the state file the dylib reads at load. */
+    launchEnv(opts: LaunchOptions): DriverResult<Record<string, string> | undefined>;
+    /** After a launch that carried the dylib: wait until it loaded, so a missing injection fails here, not as a test that sees the wrong network. */
+    confirmLoaded(): DriverResult<void>;
+    /** Wall-clock offset for the injected app (COND-12). Live when the app is injected, else staged for the next launch. */
+    setClockOffset(ms: number): DriverResult<void>;
+    /** Mock the injected app's wall clock (`Driver.clock`). Live when the app is injected, else staged for the next launch. */
+    clock(op: ClockCondition, opts?: NetworkOptions): DriverResult<ClockState>;
+    /**
+     * The simulated camera (`Driver.camera`): feeds are staged copies. Live on an app launched with the camera on
+     * (`WARDEN_CAMERA=1`), else from the next launch, which loads the dylib for it (`appliesOnLaunch`).
+     */
+    camera(op: CameraCondition | null): DriverResult<CameraState>;
+};
+export declare function createIosNetwork(deps: IosNetworkDeps): IosNetwork;

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

@@ -0,0 +1,44 @@
+import type { PermissionName, PermissionState } from "../../../../core/src/conditions/conditions.types";
+import type { LaunchSettings } from "../../../../core/src/conditions/launch-settings";
+import { type Exec } from "../../../../core/src/exec";
+import type { Driver, LaunchOptions } from "../driver.types";
+/** Permission name to `simctl privacy` service; a name without one is skipped with the reason in `IOS_NO_SERVICE`. */
+export declare const IOS_PRIVACY_SERVICE: Partial<Record<PermissionName, string>>;
+export declare const IOS_NO_SERVICE: Partial<Record<PermissionName, string>>;
+export declare const privacyArgv: (udid: string, state: PermissionState, service: string, bundleId: string) => string[];
+export declare const contentSizeArgv: (udid: string, category: string) => string[];
+export declare const contrastArgv: (udid: string, increased: boolean) => string[];
+export declare const DEFAULT_CONTENT_SIZE = "large";
+export declare function statusBarBatteryArgv(udid: string, op: {
+    level?: number;
+    charging?: boolean;
+}): string[];
+export declare const statusBarClearArgv: (udid: string) => string[];
+/** `simctl push` reads the payload from stdin (`-`); a `sh -c` with positional args keeps it out of the command line quoting. */
+export declare const pushArgv: (udid: string, bundleId: string, payload: unknown) => string[];
+/** The launch env and args a staged timezone / locale becomes. */
+export declare function launchExtras(settings: LaunchSettings): {
+    env: Record<string, string>;
+    args: string[];
+};
+/** `requested` with the staged timezone / locale merged in (the caller's own env and args win on a clash). */
+export declare function withStagedSettings(requested: LaunchOptions | undefined, settings: LaunchSettings): LaunchOptions | undefined;
+export type StagedSettings = {
+    read(): LaunchSettings;
+    write(settings: LaunchSettings): string | undefined;
+};
+export type IosSettingsDeps = {
+    udid: string;
+    exec: Exec;
+    /** the last app this driver launched */
+    lastBundle: () => string | undefined;
+    /** the session's app (`WARDEN_BUNDLE_ID`) when nothing was launched yet */
+    defaultBundle?: string;
+    /** where timezone / locale are staged between processes; absent: kept in this driver only */
+    staged?: StagedSettings;
+};
+export type IosSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push"> & {
+    /** the staged timezone / locale, for `app.launch` to merge into a launch */
+    launchSettings(): LaunchSettings;
+};
+export declare function createIosSettings(deps: IosSettingsDeps): IosSettings;

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

@@ -0,0 +1,41 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError, DriverResult, Logger } from "../driver.types";
+import { type ClientOptions, type RequestOptions, type SimdClient } from "./simd-client";
+import { type SimdSpawn } from "./simd-transport";
+/**
+ * `warden-runner` (the XCUITest server of `native/ios-runner`) on an iOS Simulator, for the ops XCUITest has and the
+ * simulator helper does not: today the accessibility audit (A11Y-4). Started lazily on the first request:
+ *
+ *   build (cached, no signing)  ->  `xcodebuild test-without-building -xctestrun … -destination id=<udid>
+ *   -only-testing:…/testServe`  ->  wait for `WARDEN_RUNNER_READY {json}` (the port)  ->  NDJSON over TCP on this Mac
+ *
+ * The runner outlives the request (the next audit costs the audit only, about 2 s) and is shut down by `close()`.
+ * Anything that stops it from starting is a {@link DriverError} the caller turns into a skipped audit, never a failure.
+ */
+export declare const READY_PREFIX = "WARDEN_RUNNER_READY";
+export declare const TEST_FILTER = "-only-testing:WardenRunnerUITests/RunnerTests/testServe";
+/** The port in a `WARDEN_RUNNER_READY {json}` line, or undefined for any other line. */
+export declare function parseRunnerReady(line: string): number | undefined;
+/** The argv that serves the runner on `udid`; `env` carries the `TEST_RUNNER_*` variables `xcodebuild` forwards. */
+export declare function simRunnerArgv(o: {
+    xctestrun: string;
+    udid: string;
+    idleSeconds?: number;
+}): string[];
+export type SimRunnerDeps = {
+    udid: string;
+    /** a cached simulator runner build (`ensureSimRunnerBuild`), or why there is none */
+    ensureBuild(): Promise<Result<{
+        xctestrun: string;
+    }, string>>;
+    spawn?: SimdSpawn;
+    /** connect to the runner's port (tests inject a fake) */
+    connect?: (port: number, options: ClientOptions) => Promise<Result<SimdClient, DriverError>>;
+    readyTimeoutMs?: number;
+    log?: Logger;
+};
+export type SimRunner = {
+    request(op: string, params?: Record<string, unknown>, opts?: RequestOptions): DriverResult<unknown>;
+    close(): Promise<void>;
+};
+export declare function createSimRunner(deps: SimRunnerDeps): SimRunner;

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

@@ -1,6 +1,7 @@
 import { type ResetFs } from "../../../../core/src/builds/install";
+import type { LatLon, LocationCondition } from "../../../../core/src/conditions/conditions.types";
 import { type Exec, type ExecResult } from "../../../../core/src/exec";
-import type { DriverError, DriverResult, LaunchOptions } from "../driver.types";
+import type { BiometricOp, BiometricState, DriverError, DriverResult, LaunchOptions } from "../driver.types";
 export declare const SIMCTL_CHILD_PREFIX = "SIMCTL_CHILD_";
 /** `xcrun simctl launch [--terminate-running-process] <udid> <bundle> <args…>` (env goes through `SIMCTL_CHILD_*`, see {@link launchEnv}). */
 export declare function launchArgv(udid: string, bundleId: string, opts?: LaunchOptions): string[];
@@ -16,6 +17,22 @@ export declare const appContainerArgv: (udid: string, bundleId: string) => strin
 export declare const launchctlListArgv: (udid: string) => string[];
 export declare const pbpasteArgv: (udid: string) => string[];
 export declare const appearanceArgv: (udid: string, set?: "light" | "dark") => string[];
+/** Sets the enrollment state, then posts the change (`notifyutil -s <name> <state>` before `-p <name>`). */
+export declare const biometricEnrollArgvs: (udid: string, enrolled: boolean) => string[][];
+/** Prints `com.apple.BiometricKit.enrollmentChanged <0|1>`. */
+export declare const biometricStateArgv: (udid: string) => string[];
+/** The Face ID (`pearl`) or Touch ID (`fingerTouch`) match / nomatch notification the simulator's BiometricKit listens for. */
+export declare const biometricEventArgv: (udid: string, modality: BiometricState["modality"], event: "match" | "nomatch") => string[];
+/** The notifications one op posts, in order; `status` posts nothing. */
+export declare function biometricArgvs(udid: string, modality: BiometricState["modality"], op: BiometricOp): string[][];
+/** Model identifier (`iPhone14,7`) of a booted sim. */
+export declare const modelIdentifierArgv: (udid: string) => string[];
+/**
+ * Touch ID models by identifier: iPhone SE and everything up to the 8 (`iPhone10,1|2|4|5`; the X, `10,3|6`, has Face ID),
+ * and the iPads with a home or power-button sensor. Face ID iPads are the Pros from 2018 (`iPad8,*`, `iPad13,4-11`,
+ * `iPad14,3-6`, `iPad16,3-6`, `iPad17,*`). Unknown or empty falls back to Face ID.
+ */
+export declare function biometricModalityOf(model: string): BiometricState["modality"];
 export declare const screenshotArgv: (udid: string, path: string) => string[];
 /** `AutomationEnabled` lets the AX bridge attach without the runner app; written once per open. */
 export declare const automationArgv: (udid: string) => string[];
@@ -38,6 +55,22 @@ export type StatusBarOverrides = {
 /** Clean 9:41 status bar by default (stable screenshots); pass `undefined` fields to drop them. */
 export declare function statusBarOverrideArgv(udid: string, o?: StatusBarOverrides): string[];
 export declare const statusBarClearArgv: (udid: string) => string[];
+export declare const locationSetArgv: (udid: string, point: LatLon) => string[];
+export declare const locationClearArgv: (udid: string) => string[];
+/** `name` is Apple's scenario name (`City Run`), see {@link IOS_SCENARIO_NAMES}. */
+export declare const locationRunArgv: (udid: string, name: string) => string[];
+/** A route with more waypoints than this goes through stdin (`-`) instead of the argument list. */
+export declare const LOCATION_ARGV_MAX_POINTS = 100;
+export type LocationStartOptions = {
+    speedMps?: number;
+    intervalS?: number;
+};
+/**
+ * `simctl location <udid> start [--speed=] [--interval=] <lat,lon>…`. The sim plays the path itself
+ * after the command returns. Past {@link LOCATION_ARGV_MAX_POINTS} the waypoints ride stdin of a tiny
+ * `sh -c` (one `lat,lon` per line, never interpolated into the script) with the `-` operand.
+ */
+export declare function locationStartArgv(udid: string, points: readonly LatLon[], o?: LocationStartOptions): string[];
 /**
  * `simctl pbcopy` reads stdin and `Exec` has none, so the text rides as `$1` of a tiny `sh -c`
  * (never interpolated into the script): `printf %s "$1" | xcrun simctl pbcopy "$2"`.
@@ -91,6 +124,13 @@ export type Simctl = {
     pbpaste(): DriverResult<string>;
     appearance(set?: "light" | "dark"): DriverResult<"light" | "dark">;
     statusBar(overrides?: StatusBarOverrides | "clear"): DriverResult<void>;
+    /** `simctl location`: point, route (also from a GPX file), Apple scenario, or clear. Loop is not supported. */
+    location(op: LocationCondition): DriverResult<void>;
+    /**
+     * Face ID / Touch ID through BiometricKit notifications inside the sim. Modality comes from the booted sim's
+     * `SIMULATOR_MODEL_IDENTIFIER` (read once; unreadable = Face ID); the answer is the state after the op.
+     */
+    biometrics(op: BiometricOp): DriverResult<BiometricState>;
     /** `simctl io screenshot` to `path`, or (no path) to a scratch file read back as PNG bytes */
     screenshot(path?: string): DriverResult<{
         path?: string;

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

@@ -38,6 +38,15 @@ export declare function stdioTransport(opts: {
     /** how long `close()` waits for the helper to exit after closing stdin before killing it */
     graceMs?: number;
 }): TransportFactory;
-export declare function socketTransport(opts: {
+/** Where a socket transport connects: the daemon's unix socket, or a TCP port on this Mac (the Simulator runner). */
+export type SocketTarget = {
     socketPath: string;
-}): TransportFactory;
+    tcp?: undefined;
+} | {
+    tcp: {
+        hostname: string;
+        port: number;
+    };
+    socketPath?: undefined;
+};
+export declare function socketTransport(opts: SocketTarget): TransportFactory;

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

@@ -1,10 +1,15 @@
 /**
  * Per-request budget for the helper's `typeText`: it holds, paces and (for a repeated key) waits per character.
  * The helper's defaults (pace 5, hold 20, repeat gap 50) cost ~38 ms per character on a quiet local simulator; the
- * budget allows ~100 ms (the EAS VirtualMac ran ~3.7x the nominal sleeps) and 200 ms per repeated key.
+ * budget allows ~100 ms (the EAS VirtualMac ran ~3.7x the nominal sleeps) and 200 ms per repeated key. The one
+ * lead-in pause after the first key (60 ms) fits in the base.
  */
 export declare const TYPE_BASE_MS = 10000;
 export declare const TYPE_PER_CHAR_MS = 100;
 export declare const TYPE_PER_REPEAT_MS = 200;
 /** Base + ~100 ms per character + 200 ms per character equal to the one before it. */
 export declare function typeTextBudgetMs(text: string): number;
+/** The XCUITest runner on a real device types one character per `typeText` call, each waiting for the app to go idle. */
+export declare const DEVICE_TYPE_PER_CHAR_MS = 600;
+/** Base + ~600 ms per character: the runner's per-character typing on a real device. */
+export declare function deviceTypeTextBudgetMs(text: string): number;

package/types/e2e/src/driver/native-audit.d.ts

@@ -0,0 +1,26 @@
+import type { A11yIssue } from "../a11y/a11y.types";
+import type { Driver } from "./driver.types";
+/** What a platform's own audit engine found, or why it did not run (never an error: a missing engine only skips it). */
+export type NativeAuditResult = {
+    issues: A11yIssue[];
+    skipped?: {
+        source: A11yIssue["source"];
+        reason: string;
+    };
+};
+export type NativeAuditOptions = {
+    /** iOS: the app whose accessibility the XCUITest audit checks (required there; the audit needs it running) */
+    bundleId?: string;
+    /** Android: let ATF's contrast checks read a screenshot (default true) */
+    contrast?: boolean;
+};
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `ReadsA11y` in `a11y-read.ts`): run the
+ * platform's own accessibility audit on the screen now. iOS simulator: XCUITest `performAccessibilityAudit` through
+ * the runner (`a11y/native/xcuitest.ts`). Android: the Accessibility Test Framework inside `warden-uiad`
+ * (`a11y/native/atf.ts`). Resolves with `skipped` and a reason when the engine cannot run.
+ */
+export type AuditsNatively = {
+    auditNatively(options?: NativeAuditOptions): Promise<NativeAuditResult>;
+};
+export declare function canAuditNatively(driver: Driver): driver is Driver & AuditsNatively;

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

@@ -0,0 +1,52 @@
+import type { HostFault, NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { ConditionsUpdate } from "../../../core/src/netproxy/control";
+import { type LeaseProxyDeps } from "../../../core/src/netproxy/lease-proxy";
+import { type ProxyConditions } from "../../../core/src/netproxy/shaping";
+import type { Store } from "../../../core/src/store";
+import type { Lease } from "../../../core/src/types";
+import { type AsyncResult, type Result } from "../../../types/src/result";
+/** Where a lease's shaping proxy listens (always loopback on the host). */
+export type ProxyAddress = {
+    host: string;
+    port: number;
+};
+/**
+ * What a driver needs from the lease's shaping proxy (COND-4). The drivers never touch the lease store: whoever
+ * opens the driver builds this (`leaseNetworkProxy`) or passes a fake in tests.
+ */
+export type NetworkProxyPort = {
+    /** The live proxy's address, `undefined` when this lease has none. */
+    current(): Promise<ProxyAddress | undefined>;
+    /** Start the proxy (or reuse the live one) with `conditions` applied; records `condition` as the lease's network condition. */
+    ensure(condition: NetworkCondition, conditions: ProxyConditions): AsyncResult<ProxyAddress>;
+    /** Reconfigure the live proxy without dropping connections. Fails when there is none. */
+    update(update: ConditionsUpdate): AsyncResult<void>;
+    /** Stop the proxy and free its port. */
+    stop(): Promise<void>;
+};
+/** `NetworkProxyPort` for one lease over the real store and the detached `netproxy` process. */
+export declare function leaseNetworkProxy(deps: LeaseProxyDeps, lease: Pick<Lease, "id" | "owner" | "ttlMs">): NetworkProxyPort;
+/** The proxy parameters for `condition` plus the faults to keep. Offline is `refuse`: connections close at accept. */
+export declare function proxyConditionsFor(condition: NetworkCondition, faults: readonly HostFault[]): ProxyConditions;
+/**
+ * Faults the proxy cannot honour as written. An HTTPS request is a CONNECT tunnel the proxy never reads inside
+ * (no MITM), so a `status` fault on a host reaches an https:// request as a reset, not a status code.
+ */
+export declare function faultNotes(faults: readonly HostFault[]): string[];
+export type LazyLeaseProxyOptions = {
+    leaseId: string;
+    env: Record<string, string | undefined>;
+    now: () => number;
+    /** opens the lease store; called only when the proxy has to be started or stopped */
+    openStore: () => Result<Store>;
+    /** argv that runs the proxy process (`WARDEN_NETPROXY_COMMAND`); default: `bun netproxy.main.ts` from source */
+    command?: readonly string[] | undefined;
+    /** test seams passed through to `ensureLeaseProxy` (spawn, pid liveness, port range…) */
+    proxyDeps?: Partial<Omit<LeaseProxyDeps, "store" | "env" | "now" | "command">>;
+};
+/**
+ * `NetworkProxyPort` for a spec's lease that touches nothing until a network condition needs it: the store is not
+ * opened (nor the lease read) before `ensure`, so a spec that never shapes the network costs no store access or
+ * proxy. `current` / `update` / `stop` work from the lease's handle file and stay off the store while there is none.
+ */
+export declare function lazyLeaseNetworkProxy(o: LazyLeaseProxyOptions): NetworkProxyPort;

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

@@ -1,19 +1,37 @@
 import { type Exec } from "../../../core/src/exec";
+import { type StoreOpener } from "../conditions/lease-store";
 import type { E2eEnv } from "../env";
 import type { DriverFactory } from "../session";
 import { type AndroidDriverOptions } from "./android/android-driver";
+import { type ClockRecorder } from "./clock-recorder";
 import type { Driver, DriverResult } from "./driver.types";
+import { type OpenIosDeviceDriverOptions } from "./ios/device/device-driver";
 import { type OpenIosDriverOptions } from "./ios/ios-driver";
+import { type NetworkProxyPort } from "./network-proxy";
 /**
  * Test seams for {@link openDriver}: everything the platform openers inject except what the env supplies.
  * `android` carries the Android-only seams (`adb` path, resident-shell spawn, binary runner, clock).
  */
 export type OpenDriverDeps = Omit<OpenIosDriverOptions, "udid" | "env" | "exec"> & {
     exec?: Exec;
+    /** bundle ids warden installed on a physical iPhone earlier (the `installs` table): the only others `app.uninstall` may touch */
+    ownedBundles?: readonly string[];
     android?: Omit<AndroidDriverOptions, "serial" | "exec" | "log" | "adb"> & {
         adb?: string;
     };
+    /** opens the lease store for the shaping proxy; default: the spec process's shared connection */
+    openStore?: StoreOpener;
 };
+/**
+ * The shaping proxy of the spec's lease (`WARDEN_LEASE_ID`), built lazily: nothing opens the store or starts a
+ * process until a network condition asks for it. None without a lease id, so `network` answers `E_UNSUPPORTED`.
+ */
+export declare function leaseProxyFor(env: E2eEnv, deps?: OpenDriverDeps): NetworkProxyPort | undefined;
+/**
+ * Records the clock the driver sets on the spec's lease (`leaseClockRecorder`), opening the store on the first
+ * change. Best effort: a store that fails is logged and never fails the clock call. None without a lease id.
+ */
+export declare function leaseClockRecorderFor(env: E2eEnv, deps?: OpenDriverDeps): ClockRecorder | undefined;
 /** `WARDEN_E2E_DEBUG=1` logs every helper op and simctl call with its duration to stderr. */
 export declare const DEBUG_ENV = "WARDEN_E2E_DEBUG";
 /**
@@ -23,6 +41,8 @@ export declare const DEBUG_ENV = "WARDEN_E2E_DEBUG";
  * shell `spawn`, which is a test that must never reach a real `adb`), and the injected seams.
  */
 export declare function androidOptions(env: E2eEnv, deps: OpenDriverDeps, debug: boolean): AndroidDriverOptions;
+/** The physical iPhone opener's options: the env's udid, runner socket, app and bundle id, and the injected seams. */
+export declare function deviceOptions(env: E2eEnv, deps: OpenDriverDeps, debug: boolean): OpenIosDeviceDriverOptions;
 /** Open the `Driver` for the device in `env`, by platform. Android deep links go to `env.bundleId` only. */
 export declare function openDriver(env: E2eEnv, deps?: OpenDriverDeps): DriverResult<Driver>;
 /** What the session uses when no factory is passed; `preload.ts` registers it with `setDefaultDriverFactory`. */

package/types/e2e/src/driver/physical-conditions.d.ts

@@ -0,0 +1,11 @@
+import type { Driver } from "./driver.types";
+/** The condition and setting ops of a `Driver`: each changes the device (or an app's grants) beyond driving its UI. */
+export declare const PHYSICAL_CONDITION_OPS: readonly ["network", "networkFaults", "location", "clock", "permissions", "timezone", "locale", "a11y", "battery", "memoryWarning", "push", "camera"];
+type PhysicalConditionOps = Pick<Driver, (typeof PHYSICAL_CONDITION_OPS)[number]>;
+/**
+ * The condition ops for a physical phone: all `E_UNSUPPORTED`. On a phone they would flip airplane mode (cutting
+ * wireless adb), set the system clock, timezone or font scale, or proxy the network of somebody's device; the
+ * mechanisms behind them (`simctl`, the emulator console, the injected dylib) are simulator / emulator only.
+ */
+export declare function physicalConditionOps(device: string): PhysicalConditionOps;
+export {};

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

@@ -0,0 +1,14 @@
+import type { Platform } from "./driver.types";
+/**
+ * What a spec can ask of its device with `test(title, { requires: [...] })`:
+ * - `pinch`: two-finger `pinch` / `rotate` (`capabilities.pinch`)
+ * - `multiTouch`: a gesture path with more than one finger (`capabilities.maxPointers` of 2)
+ */
+export type Requirement = "pinch" | "multiTouch";
+/** The device a spec was collected for, as the env says (`WARDEN_PLATFORM`, `WARDEN_DEVICE_KIND`). */
+export type RequirementTarget = {
+    platform: Platform | undefined;
+    deviceKind?: "physical" | undefined;
+};
+/** The `requires` the target's driver is known to lack: a spec with any of them is skipped when collected. */
+export declare function missingRequirements(target: RequirementTarget, requires: readonly Requirement[] | undefined): Requirement[];

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

@@ -0,0 +1,26 @@
+import type { ScreenReaderState, SpokenLine } from "../a11y/a11y.types";
+import type { Driver, DriverResult, Element } from "./driver.types";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `ReadsA11yEvents`): drive a real screen reader
+ * the way a user's swipes and double-taps would. Only Android offers it, and only while TalkBack is on through
+ * `a11y({ screenReader: true })`; any call with TalkBack off answers `E_UNSUPPORTED`.
+ *
+ * `next` / `prev` move TalkBack's accessibility focus one step in its traversal order and answer the node that holds
+ * it afterwards (`undefined` at either end). `activate` clicks the focused node (`ACTION_CLICK` on it or its clickable
+ * ancestor). `focused` reads the node holding accessibility focus. `spoken` answers what TalkBack said since `since`
+ * (opaque cursor, as for `a11yEvents`): from its verbose log when that is on (`source: "talkback"`), else composed
+ * from the focus events by the speech model (`source: "simulated"`).
+ */
+export type SpokenRead = {
+    lines: SpokenLine[];
+    cursor: number;
+};
+export type DrivesScreenReader = {
+    screenReaderState(): DriverResult<ScreenReaderState>;
+    screenReaderNext(): DriverResult<Element | undefined>;
+    screenReaderPrev(): DriverResult<Element | undefined>;
+    screenReaderActivate(): DriverResult<void>;
+    screenReaderFocused(): DriverResult<Element | undefined>;
+    screenReaderSpoken(since?: number): DriverResult<SpokenRead>;
+};
+export declare function canDriveScreenReader(driver: Driver): driver is Driver & DrivesScreenReader;

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

@@ -4,7 +4,7 @@ import type { Driver, DriverResult, KeyName } from "./driver.types";
  * fill`/`type` all go through it).
  *
  * iOS: `warden-simd` holds, paces and spaces repeated keys itself (`WARDEN_SIMD_PACE_MS`, `WARDEN_SIMD_HOLD_MS`,
- * `WARDEN_SIMD_REPEAT_GAP_MS`), so the whole string goes in one request and the client adds no gap. Before that
+ * `WARDEN_SIMD_REPEAT_GAP_MS`, `WARDEN_SIMD_LEAD_MS`), so the whole string goes in one request and the client adds no gap. Before that
  * the client sent one grapheme per request, 25 ms apart (set `KEY_PACE_MS` 25 and `SPLIT_TEXT` true to go back).
  */
 /** Gap after each key on iOS. */