@delacour/warden-e2e 0.6.0 → 0.7.0

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

@@ -0,0 +1,110 @@
+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.
+ */
+export type InjectState = {
+    seq: number;
+    offline?: boolean;
+    clockOffsetMs?: number;
+    clockFrozenMs?: number;
+};
+/** What the dylib answers in `<state>.ack` once it applied `seq` (`bundleId`: the app it loaded into). */
+export type InjectAck = {
+    seq: number;
+    pid: number;
+    proxy?: 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;
+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;
+    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 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-driver.d.ts

@@ -1,9 +1,14 @@
 import type { Exec } from "../../../../core/src/exec";
 import type { E2eEnv } from "../../env";
 import type { ProbesFrontmost, ReadsAlertOn } from "../alerts";
+import type { ClockRecorder } from "../clock-recorder";
 import type { Driver, DriverResult, KeyName, Logger } from "../driver.types";
+import type { NetworkProxyPort } from "../network-proxy";
 import type { PastesText, SelectsAll } from "../typing";
+import { type InjectFs } from "./inject";
+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";
@@ -46,6 +51,19 @@ 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;
     /** CoreSimulator devices directory for the host-side `AutomationEnabled` check (default `~/Library/Developer/CoreSimulator/Devices`) */
     devicesRoot?: string;
 };
@@ -56,6 +74,17 @@ 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;
+    /** per-app network conditions (`ios-network.ts`); absent: `network` answers `E_UNSUPPORTED` */
+    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,46 @@
+import type { ClockCondition, HostFault, NetworkCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Result } from "../../../../types/src/result";
+import type { 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>;
+};
+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/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/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/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"];
+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/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. */

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

@@ -1,3 +1,4 @@
+import { type ConditionsConfig } from "../../core/src/conditions/conditions.config";
 import type { Result } from "../../types/src/result";
 /**
  * The env names `warden e2e` writes and the spec process reads (`apps/cli` imports these). `WARDEN_HEADLESS` and
@@ -20,7 +21,16 @@ export declare const ENV_NAMES: {
     readonly helperDir: "WARDEN_HELPER_DIR";
     readonly simd: "WARDEN_SIMD";
     readonly simdSocket: "WARDEN_SIMD_SOCKET";
+    /** unix socket of a physical iPhone's resident runner host (`warden __ios-runner-host`): the iOS device driver connects there instead of to `warden-simd` */
+    readonly iosRunnerSocket: "WARDEN_IOS_RUNNER_SOCKET";
     readonly logTimestamps: "WARDEN_LOG_TIMESTAMPS";
+    /** `physical` when the job's device is a real phone/tablet (set by `warden e2e` / `batch`; absent for a simulator or emulator) */
+    readonly deviceKind: "WARDEN_DEVICE_KIND";
+    /**
+     * JSON argv (`{udid}` is replaced) that restarts a physical iPhone's runner host (`warden __ios-runner-restart`); the
+     * session runs it once when the runner connection is lost, and never reboots the phone
+     */
+    readonly iosRunnerRestart: "WARDEN_IOS_RUNNER_RESTART";
     /**
      * JSON argv (`{udid}` is replaced) the session runs after it rebooted the sim following a lost HID connection;
      * `warden` sets it for non-headless runs so the sim's viewer window comes back (packages/e2e cannot import apps/cli)
@@ -34,6 +44,14 @@ export declare const ENV_NAMES: {
     readonly perf: "WARDEN_PERF";
     /** JSON of the suite's `perf.budgets`; a breach fails the test with `PERF_BUDGET` */
     readonly perfBudgets: "WARDEN_PERF_BUDGETS";
+    /** JSON of the suite's `conditions` (network / location / clock applied before each spec, the rest reported as not applied) */
+    readonly conditions: "WARDEN_CONDITIONS";
+    /** the id of the lease holding `WARDEN_UDID`: conditions a spec sets are recorded on it and its shaping proxy hangs off it */
+    readonly leaseId: "WARDEN_LEASE_ID";
+    /** JSON argv that runs the shaping proxy (`warden __netproxy`) when specs run from a compiled `warden`; the JSON argument is appended */
+    readonly netproxyCommand: "WARDEN_NETPROXY_COMMAND";
+    /** `1` when the suite's devices are biometrics devices: the session enrolls an iOS sim again before the app is installed */
+    readonly biometrics: "WARDEN_BIOMETRICS";
 };
 export declare const DEFAULT_TIMEOUT_MS = 120000;
 export declare const DEFAULT_ACTION_TIMEOUT_MS = 30000;
@@ -56,6 +74,12 @@ export type E2eEnv = {
     helperDir?: string;
     simd?: string;
     simdSocket?: string;
+    /** `WARDEN_IOS_RUNNER_SOCKET`: the runner host's socket for a physical iPhone */
+    iosRunnerSocket?: string;
+    /** `WARDEN_DEVICE_KIND`: `physical` for a real phone/tablet, absent for a simulator or emulator */
+    deviceKind?: "physical";
+    /** `WARDEN_IOS_RUNNER_RESTART`: argv that restarts the iPhone's runner host, `{udid}` not yet replaced */
+    iosRunnerRestart?: string[];
     /** warden already stamps the log lines: the spec reporter prints no clock of its own */
     logTimestamps: boolean;
     /** `WARDEN_AFTER_REBOOT`: argv run after a HID-loss reboot, `{udid}` not yet replaced (see `runAfterReboot`) */
@@ -68,6 +92,14 @@ export type E2eEnv = {
     perf?: string[];
     /** `WARDEN_PERF_BUDGETS`: raw JSON of the suite's budgets */
     perfBudgets?: string;
+    /** `WARDEN_CONDITIONS`: what every spec starts from (`conditions/suite-conditions.ts` applies it) */
+    conditions?: ConditionsConfig;
+    /** `WARDEN_LEASE_ID`: the device's lease; absent under a bare `bun test`, where network shaping is unsupported */
+    leaseId?: string;
+    /** `WARDEN_NETPROXY_COMMAND`: argv that starts the shaping proxy; absent from source (`bun netproxy.main.ts`) */
+    netproxyCommand?: string[];
+    /** `WARDEN_BIOMETRICS`: this is a biometrics device (profile `<p>+bio`); iOS enrollment does not survive a reboot or a spec's `unenroll` */
+    biometrics?: boolean;
 };
 /**
  * Reads the spec env contract. `undefined` data = not running under warden (no `WARDEN_UDID`); an

package/types/e2e/src/fixture-session.d.ts

@@ -9,6 +9,10 @@ import type { TraceEvent } from "./runner/trace";
 export type FixtureSession = {
     /** absolute `WARDEN_E2E_OUT` (screenshot fallback when no attempt is running) */
     readonly out: string;
+    /** the process's `results.jsonl`; `device.network` / `location` / `clock` append condition events to it */
+    readonly results?: {
+        readonly path: string;
+    };
     /** the running attempt's deadline / cancel signal; every driver call honours it */
     readonly signal?: AbortSignal;
     /** `<out>/<specId>/<title-slug>-<hash6>` of the running attempt */

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

@@ -1,6 +1,11 @@
-import { type Device } from "./device";
+import { type AlertAction, type Device } from "./device";
 import type { BaseFixtures, FixtureContext } from "./runner/fixtures.types";
 import type { ScreenHost } from "./screen/context";
+/**
+ * `device.alert(action)` for a read that answers sheets on the side: a sheet that stays up after every press
+ * (`ACTION_FAILED`) is left for the read to go on with, not thrown out of an unrelated `isVisible()`.
+ */
+export declare function answerAlertQuietly(device: Pick<Device, "alert">, action: AlertAction): Promise<boolean>;
 /**
  * What `screen` needs from one attempt: the live driver, its timeouts and deadline, and reported steps. With
  * `systemAlerts` set (`test.use`) and a `device` to press with, reads and waits answer the alerts they see.

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

@@ -1,4 +1,6 @@
 export type { OpenOptions, OpenWaitUntil } from "./app";
+export type { ClockInput, ConditionRun, DeviceClock, DeviceLocation, DeviceNetwork, DevicePermissions, Duration, FlapOptions, LocationPoint, NetworkSetOptions, NetworkStatus, RouteOptions, TimelineStepInput, } from "./conditions/device-conditions";
+export type { BiometricState, DeviceBiometrics } from "./device";
 export { E2eError } from "./errors";
 export { expect } from "./expect/expect";
 export type { PerfBreach, PerfBudgets } from "./perf/budgets";

package/types/e2e/src/runner/scope.d.ts

@@ -57,6 +57,7 @@ export declare function registrationDefaults(env?: Readonly<Record<string, strin
     actionTimeoutMs: number;
     assertionTimeoutMs: number;
     platform: "ios" | "android" | undefined;
+    deviceKind: "physical" | undefined;
 };
 /** Records that a `.only` was collected (kept on `globalThis`: the preload and the specs may be separate bundles). */
 export declare function markOnly(): void;

package/types/e2e/src/runner/test.d.ts

@@ -1,4 +1,5 @@
 import type { Platform } from "../driver/driver.types";
+import { type Requirement } from "../driver/requirements";
 import { type BaseFixtures } from "./fixtures.types";
 import { type Hook, type UseOptions } from "./scope";
 export type TestOptions = {
@@ -8,6 +9,11 @@ export type TestOptions = {
     only?: boolean;
     /** run only on these platforms (decided at collection time from `WARDEN_PLATFORM`) */
     platforms?: readonly Platform[];
+    /**
+     * driver capabilities the test needs (`pinch`, `multiTouch`). The test is skipped, when collected, on a device whose
+     * driver is known to lack one: a physical iPhone has neither. Elsewhere the driver decides at run time.
+     */
+    requires?: readonly Requirement[];
     /** extra attempts after a failure; only the last attempt writes to `results.jsonl` */
     retry?: number;
 };

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

@@ -2,7 +2,8 @@ import type { Device } from "./device";
 import type { SpanRunner } from "./runner/span";
 /**
  * `device` with every call timed as a `device.<name>` span in the attempt's `trace.jsonl` (trace only: no console
- * line, since a settle or an alert is not a step). The driver calls a device call makes are `driver.*` spans of
+ * line, since a settle or an alert is not a step). The condition calls are `device.network.<call>`,
+ * `device.location.<call>`, `device.clock.<call>` and `device.timeline`. The driver calls a device call makes are `driver.*` spans of
  * their own, so a slow `device.openLink` shows what it spent its time on. Without a span runner (a bare
  * `FixtureSession`) the device is returned unchanged.
  */