@delacour/warden-e2e 0.3.1 → 0.5.0

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

@@ -0,0 +1,56 @@
+import type { Platform } from "../types";
+import { type BuildConfiguration } from "./builds.defaults";
+import type { Project } from "./config";
+import type { AppFramework } from "./native-ids";
+/**
+ * What a cached build is for:
+ * - `dev`: Debug, JS from Metro at runtime.
+ * - `simulator`: Release for a simulator / emulator with no JS bundle embedded; a repack supplies the JS.
+ * - `release`: Release with the JS bundle embedded at build time (the key also covers the JS sources).
+ */
+export type BuildKind = "dev" | "simulator" | "release";
+export declare const BUILD_KINDS: readonly ["dev", "simulator", "release"];
+/** The kind `warden e2e` installs when the suite's `app` names none. */
+export declare const DEFAULT_E2E_KIND: BuildKind;
+/** The kind `warden ui open` / `warden dev` use when no `--kind` is given. */
+export declare const DEFAULT_UI_KIND: BuildKind;
+/** `projects[].kinds.<kind>`: overrides of one kind's built-in defaults. */
+export type KindConfig = {
+    /** replaces the kind's built-in build command, per platform */
+    build?: {
+        ios?: string | undefined;
+        android?: string | undefined;
+    } | undefined;
+    /** env of the build and of the JS bundle step (`EXPO_PUBLIC_*`, `NODE_ENV`…); part of the JS key */
+    env?: Record<string, string> | undefined;
+    /** globs (relative to the project root, `!` excludes) of the JS sources the key covers; `simulator` / `release` only */
+    jsInputs?: string[] | undefined;
+};
+export type ProjectKinds = Partial<Record<BuildKind, KindConfig | undefined>>;
+/** A kind's effective build settings: the built-in defaults with `projects[].kinds.<kind>` applied. */
+export type KindSettings = {
+    kind: BuildKind;
+    build: Record<Platform, string>;
+    buildConfiguration: BuildConfiguration;
+    /** the app binary carries its JS (`release`); false = Metro or a repack supplies it */
+    embedsJs: boolean;
+    /** `native`: the key is the native fingerprint; `native+js`: also the `jsInputs` content */
+    fingerprint: "native" | "native+js";
+    env: Record<string, string>;
+    /** the JS sources the JS key (`simulator`, `release`) covers; undefined for `dev` */
+    jsInputs?: string[];
+};
+/** The built-in build command of `kind` (the default `projects[].kinds.<kind>.build` replaces). */
+export declare function kindBuildCommand(kind: BuildKind, platform: Platform, framework: AppFramework): string;
+/**
+ * `kind`'s settings for `project`. Precedence: `kinds.<kind>.build` > the built-in default. The project's top-level
+ * `build` / `fingerprint.include` / `fingerprint.jsInputs` belong to the kind-less flow and are not read here
+ * (`fingerprint.command`, `build.cache` and `build.prebuiltReactNative` still apply: they are not about the kind).
+ * JS inputs: `kinds.<kind>.jsInputs`, else `DEFAULT_JS_INPUTS` (all tracked files but `ios/`, `android/`, `node_modules`).
+ */
+export declare function resolveKind(project: Project, kind: BuildKind): KindSettings;
+/**
+ * `project` as `kind` builds it: the build commands, configuration and env of `resolveKind`, and `jsInputs` set only
+ * when the kind's cache key covers the JS (`release`), so `runLocalBuild` / `computeCacheKey` run unchanged.
+ */
+export declare function projectForKind(project: Project, kind: BuildKind): Project;

package/types/core/src/builds/native-ids.d.ts

@@ -0,0 +1,14 @@
+import type { Platform } from "../types";
+/** How an app is run: Expo (`expo start`, a dev client) or bare React Native (`react-native start`, the app itself). */
+export type AppFramework = "expo" | "react-native";
+/**
+ * The app's framework from its `package.json`: `expo` when it depends on `expo`, `react-native` when
+ * only on `react-native`; undefined without either (or without a readable `package.json`).
+ */
+export declare function appFramework(root: string): AppFramework | undefined;
+/**
+ * A bare React Native app's ids, read from its native projects: iOS `PRODUCT_BUNDLE_IDENTIFIER`
+ * (the template's `$(PRODUCT_NAME:rfc1034identifier)` filled in with `appName`), Android
+ * `applicationId`. A platform whose id can't be read (no native dir, a build variable) is left out.
+ */
+export declare function nativeBundleIds(root: string, appName: string): Partial<Record<Platform, string>>;

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

@@ -1,4 +1,5 @@
 import { type AsyncResult } from "../../../types/src/result";
+import type { Platform } from "../types";
 import type { InstallMode } from "./app-option.schema";
 /** Where `ensure` found the app. */
 export type ResolveSource = "installed" | "cache" | "eas" | "build";
@@ -10,6 +11,29 @@ export type EnsureResult = {
     /** the app is on the device at `hash` (false when no device was given) */
     installed: boolean;
 };
+/**
+ * What a resolve is doing right now, for a progress display: `fetching` the EAS build, `waiting` on another device's
+ * (or process's) fetch / build of the same hash, `building` locally, `repacking` JS into the simulator base,
+ * `installing` on a device (only while an install really runs), `ready` when the resolve is done.
+ */
+export type AppPhase = {
+    phase: "fetching";
+    source: "eas";
+} | {
+    phase: "waiting";
+} | {
+    phase: "building";
+    platform: Platform;
+    hash: string;
+} | {
+    phase: "repacking";
+    platform: Platform;
+    jsKey: string;
+} | {
+    phase: "installing";
+} | {
+    phase: "ready";
+};
 export type EasStepOutcome = {
     kind: "hit";
     path: string;
@@ -63,6 +87,8 @@ export type ResolveSteps = {
     /** local build into the cache; path */
     build?: () => AsyncResult<string>;
     log: (line: string) => void;
+    /** progress: where this resolve is (see `AppPhase`) */
+    onPhase?: (phase: AppPhase) => void;
 };
 /**
  * The 5-step resolver, first hit wins: (1) already installed at this hash → nothing to do;

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

@@ -0,0 +1,5 @@
+import type { Result } from "../../types/src/result";
+/** `10m` / `30s` / `2h` / `500ms` / bare seconds → milliseconds. */
+export declare function parseDuration(input: string): Result<number>;
+/** 125000 → `2m5s`. */
+export declare function formatDuration(ms: number): string;

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

@@ -9,6 +9,8 @@ export type ExecOptions = {
     timeoutMs?: number;
     /** aborting kills the command (SIGTERM), like a timeout */
     signal?: AbortSignal;
+    /** each line of stdout and stderr as it arrives (no trailing newline); the result still carries the whole output */
+    onLine?: (line: string) => void;
 };
 /** Injectable process runner — providers take this so tests can fake `simctl`/`adb`. */
 export type Exec = (cmd: readonly string[], opts?: ExecOptions) => Promise<ExecResult>;

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

@@ -0,0 +1,76 @@
+import type { AsyncResult, Result } from "../../types/src/result";
+import { type PidAlive } from "./liveness";
+import type { Store } from "./store";
+import type { Lease, Owner } from "./types";
+/** Span used when a spec has no `:span` (mirrors salient's `pickPort` 20-port scan). */
+export declare const DEFAULT_PORT_SPAN = 20;
+export type PortRange = {
+    from: number;
+    span: number;
+};
+/** `8091:20` → `{ from: 8091, span: 20 }`; bare `8091` → span `DEFAULT_PORT_SPAN`. */
+export declare function parsePortSpec(spec: string): Result<PortRange>;
+export type ProbeOutcome = "free" | "busy" | "unsupported";
+/**
+ * A failed probe bind → outcome. In use / forbidden is busy anywhere; a missing address or family is
+ * unsupported; any other error on the IPv6 wildcard is unsupported too (Bun reports a code-less
+ * "Failed to listen at ::" on hosts without IPv6), while on an IPv4 host it stays busy.
+ */
+export declare function classifyBindError(error: {
+    code?: string;
+}, host: string): Exclude<ProbeOutcome, "free">;
+/**
+ * Bind probe: listen on `port` and close immediately. With `host`, probes only that address;
+ * otherwise the port must bind on 127.0.0.1, 0.0.0.0 and `::` (hosts without IPv6 are skipped).
+ */
+export declare function isPortFree(port: number, host?: string): Promise<boolean>;
+export type ClaimPortsRequest = {
+    owner: Owner;
+    from: number;
+    span: number;
+    /** ports wanted (default 1) */
+    count?: number;
+    /** candidate stride inside the range (default 1; 2 for emulator console ports) */
+    step?: number;
+    ttlMs: number;
+    label?: string;
+    pid?: number;
+};
+export type ClaimPortsDeps = {
+    now: () => number;
+    pidAlive: PidAlive;
+    isPortFree: (port: number) => Promise<boolean>;
+};
+/**
+ * Lease `count` ports from `[from, from + span)` (stride `step`). Bind probes run outside the
+ * transaction (async); then, under `BEGIN IMMEDIATE`: reclaim stale leases, pick the first probed-free
+ * ports with no live lease, insert them. Retries when another process wins the race.
+ */
+export declare function claimPorts(store: Store, req: ClaimPortsRequest, deps: ClaimPortsDeps): AsyncResult<Lease[]>;
+/** Which port leases to release. */
+export type PortReleaseSelector = {
+    by: "port";
+    ports: readonly number[];
+} | {
+    by: "lease";
+    ids: readonly string[];
+} | {
+    by: "owner";
+    owner: Owner;
+};
+export type PortReleaseResult = {
+    released: Lease[];
+    /** matched but held by someone other than `onlyOwner` — left in place */
+    denied: Lease[];
+    /** ports / lease ids with no matching port lease */
+    missing: string[];
+};
+/**
+ * Release port leases by port number, lease id, or owner. With `onlyOwner`, leases held by anyone
+ * else are reported in `denied` and kept. Non-port lease ids count as `missing` (never deleted here).
+ */
+export declare function releasePorts(store: Store, selector: PortReleaseSelector, opts?: {
+    onlyOwner?: Owner;
+}): PortReleaseResult;
+/** All port leases (live or stale), ordered by port. */
+export declare function listPortLeases(store: Store): Lease[];

package/types/core/src/providers/provider.types.d.ts

@@ -31,6 +31,13 @@ export interface DeviceProvider {
     bootReady?(id: string, timeoutMs: number): Promise<BootReady>;
     /** Probe for a device `bootReady` just booted and saw ready. Absent = `probe`. */
     probeBooted?(id: string): AsyncResult<void>;
+    /**
+     * Best effort, called for a device this claim is about to boot from shutdown (after a create, or a
+     * shutdown reuse), never for an already-booted one. A failure is logged by the provider, never fatal.
+     */
+    prepareBoot?(id: string): Promise<void>;
+    /** Called once the device is ready, before the health probe. Best effort. */
+    afterReady?(id: string): Promise<void>;
 }
 /** `bootReady`: a boot failure is an error; a device that booted but never got ready is unhealthy. */
 export type BootReady = {

package/types/core/src/sims/slim.profile.d.ts

@@ -0,0 +1,54 @@
+import { type Result } from "../../../types/src/result";
+/**
+ * What `warden sim slim` may switch off inside an iOS simulator: 15 categories of `launchd_sim`
+ * jobs, each a coherent feature area (widgets, Siri, iCloud…) so a suite can keep one with
+ * `slim: { except: ["store"] }`. Labels the e2e stack depends on live in `slim.ts` `NEVER_DISABLE`
+ * and are left out here; labels that break boot are in `FORBIDDEN_LABELS` and never touched.
+ */
+/** A label a category must leave enabled because something common breaks without it. */
+export type AlwaysEnabled = {
+    label: string;
+    reason: string;
+};
+export type SlimCategory = {
+    id: string;
+    name: string;
+    labels: readonly string[];
+    alwaysEnabled?: readonly AlwaysEnabled[];
+};
+export declare const SLIM_CATEGORIES: readonly SlimCategory[];
+/** Jobs whose absence breaks boot or the home screen (observed): never disabled, whatever a profile says. */
+export declare const FORBIDDEN_LABELS: readonly string[];
+/**
+ * Which categories stay on (`except`, by id) and which single labels stay on (`keep`, full launchd
+ * labels). A label listed by any excepted category stays on even when another category lists it too.
+ */
+export type SlimProfile = {
+    except: readonly string[];
+    keep: readonly string[];
+};
+export declare const DEFAULT_SLIM_PROFILE: SlimProfile;
+/** Every label some category may switch off. */
+export declare function slimmableSet(): Set<string>;
+/** Slimmable labels plus the `alwaysEnabled` ones: the labels warden is allowed to write an override for. */
+export declare function managedSet(): Set<string>;
+/** The labels to have disabled under `profile`, in category order. */
+export declare function desiredLabels(profile: SlimProfile): Set<string>;
+/**
+ * What to change to reach `desired`: disable the wanted labels not yet disabled, enable the managed
+ * labels that are disabled but not wanted. A disabled label outside `managed` is not ours, so it is
+ * never re-enabled. `current` is `print-disabled` (label → disabled) or just the disabled labels.
+ */
+export declare function delta(current: ReadonlyMap<string, boolean> | ReadonlySet<string>, desired: ReadonlySet<string>, managed: ReadonlySet<string>): {
+    toDisable: string[];
+    toEnable: string[];
+};
+/** Reject category ids that do not exist and `keep` labels warden does not manage; messages name the culprit. */
+export declare function validateProfile(profile: SlimProfile): Result<SlimProfile>;
+/** The categories for `warden sim profiles`. */
+export declare function describeCategories(): {
+    id: string;
+    name: string;
+    labelCount: number;
+    labels: readonly string[];
+}[];

package/types/e2e/src/devtools/cdp.d.ts

@@ -6,6 +6,11 @@ export type CdpOptions = {
     /** connect timeout and the default per-request timeout */
     timeoutMs?: number;
 };
+/** How a socket closed: the WebSocket close code and reason (Metro's proxy puts a `[TAG]` in the reason). */
+export type CloseInfo = {
+    code: number;
+    reason: string;
+};
 export type CdpClient = {
     /** `Runtime.evaluate`-style JSON-RPC call; resolves with the reply's `result`. */
     send: (method: string, params?: Record<string, unknown>, options?: {
@@ -13,8 +18,8 @@ export type CdpClient = {
     }) => Promise<DevtoolsResult<unknown>>;
     /** Subscribe to a CDP event by method name; returns the unsubscribe function. */
     on: (event: string, handler: (params: unknown) => void) => () => void;
-    /** Called when the socket closes on its own (not after `close()`). */
-    onClose: (handler: () => void) => () => void;
+    /** Called when the socket closes on its own (not after `close()`), with the close code and reason Metro sent. */
+    onClose: (handler: (info: CloseInfo) => void) => () => void;
     /** Every event of every method, in arrival order (a wildcard `on`). */
     onAny: (handler: (method: string, params: unknown) => void) => () => void;
     /**

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

@@ -54,6 +54,15 @@ export type CdpTapEvent = {
 };
 export type CdpTap = (event: CdpTapEvent) => void;
 export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+/** One stack frame; `line`/`col` are 1-based. Raw frames carry the bundle URL, symbolicated ones the source file. */
+export type StackFrame = {
+    file: string;
+    line: number;
+    col: number;
+    fn?: string;
+    /** library / runtime internals Metro marks collapsible */
+    collapsed?: boolean;
+};
 /** One captured console message (`console`), uncaught exception (`exception`) or `mark()` (`note`). */
 export type ConsoleLine = {
     /** epoch ms (the runtime's own timestamp when it sent one) */
@@ -67,6 +76,10 @@ export type ConsoleLine = {
         line: number;
         col: number;
     };
+    /** the runtime's stack when it sent one; the broker rewrites it to original files (symbolication) */
+    stack?: StackFrame[];
+    /** Metro's code frame around the first app frame (symbolication) */
+    codeFrame?: string;
     /** each console argument rendered on its own (console messages only) */
     args?: string[];
 };

package/types/e2e/src/devtools/facet.d.ts

@@ -19,6 +19,8 @@ export type OpenDevtoolsFacetOptions = {
     /** called with each console line / network entry as it is recorded (the collector's files) */
     consoleSink?: (line: ConsoleLine) => void;
     networkSink?: (entry: NetworkEntry) => void;
+    /** keep React Native's LogBox (toasts and the error inspector) off in the app, across reloads (default false) */
+    muteLogBox?: boolean;
 };
 /**
  * Attach to the running dev client and start capturing its console and `fetch` traffic. This is what

package/types/e2e/src/devtools/logbox.d.ts

@@ -0,0 +1,27 @@
+import type { Sleep } from "./devtools.types";
+import type { DevtoolsSession } from "./session";
+/** What {@link muteLogBox} needs of a devtools session (or facet). */
+export type LogBoxSession = {
+    evaluate: DevtoolsSession["evaluate"];
+    on: (event: "reconnected", handler: () => void) => () => void;
+};
+export type MuteLogBoxOptions = {
+    /** injectable for tests; defaults to a timer */
+    sleep?: Sleep;
+    /** pause between tries while the bundle is still loading (default 250 ms) */
+    intervalMs?: number;
+    /** tries per JS context before LogBox is left on (default 80: 20 s at the default interval) */
+    attempts?: number;
+    log?: (line: string) => void;
+};
+export type LogBoxMute = {
+    /** resolves when the current JS context's tries end (LogBox off, given up, or stopped) */
+    readonly settled: Promise<void>;
+    stop(): void;
+};
+/**
+ * Keeps React Native's LogBox off in the attached app (see `logbox.script.ts`): now, and again in every new JS context
+ * (`reconnected` after a relaunch or JS reload). A context whose bundle has not run yet is tried again every
+ * `intervalMs`; a newer context or `stop()` ends the older context's tries.
+ */
+export declare function muteLogBox(session: LogBoxSession, options?: MuteLogBoxOptions): LogBoxMute;

package/types/e2e/src/devtools/logbox.script.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Page-side expression that turns React Native's LogBox off for good in this JS context: no warning/error toasts and
+ * no full-screen inspector, even for a fatal error. Every log still reaches the console (and so `console.jsonl` and
+ * Metro's terminal); only the overlay that covers the app and steals taps is gone.
+ *
+ * LogBox is not on a global: the script finds `react-native/Libraries/LogBox/Data/LogBoxData.js` in Metro's dev
+ * module registry (`__r.getModules()`, a `Map` of id → module with a `verboseName` path) and, once it is initialized,
+ * adds an ignore pattern that matches every message (`appendNewLog` drops ignored logs before they are stored, which
+ * is what keeps a fatal's inspector shut too, and the logs already shown are filtered out), disables notifications
+ * (`LogBox.ignoreAllLogs()`) and closes an open inspector. Re-running it is harmless (the pattern is de-duplicated).
+ *
+ * Synchronous: `"off"`, `"no-require"` (no dev Metro require yet: the bundle has not run, or a release build) or
+ * `"not-ready"` (LogBoxData not loaded yet). Plain ES5 (Hermes), no backticks or interpolation.
+ */
+export declare const LOGBOX_SCRIPT = "function (g) {\n  var req = g.__r;\n  if (typeof req !== \"function\" || typeof req.getModules !== \"function\") return \"no-require\";\n  var modules = req.getModules();\n  if (!modules || typeof modules.forEach !== \"function\") return \"no-require\";\n  var data = null;\n  modules.forEach(function (mod) {\n    if (data || !mod || typeof mod.verboseName !== \"string\" || !mod.isInitialized) return;\n    var name = mod.verboseName.replace(/\\\\/g, \"/\");\n    if (!/(^|\\/)react-native\\/Libraries\\/LogBox\\/Data\\/LogBoxData\\.js$/.test(name)) return;\n    var exports = mod.publicModule && mod.publicModule.exports;\n    if (exports && typeof exports.addIgnorePatterns === \"function\") data = exports;\n  });\n  if (!data) return \"not-ready\";\n  data.addIgnorePatterns([/[\\s\\S]*/]);\n  if (typeof data.setDisabled === \"function\") data.setDisabled(true);\n  if (typeof data.setSelectedLog === \"function\") data.setSelectedLog(-1);\n  return \"off\";\n}";
+/** Expression that runs `LOGBOX_SCRIPT` against the page's global object. */
+export declare const LOGBOX_EXPRESSION = "(function (g) {\n  var req = g.__r;\n  if (typeof req !== \"function\" || typeof req.getModules !== \"function\") return \"no-require\";\n  var modules = req.getModules();\n  if (!modules || typeof modules.forEach !== \"function\") return \"no-require\";\n  var data = null;\n  modules.forEach(function (mod) {\n    if (data || !mod || typeof mod.verboseName !== \"string\" || !mod.isInitialized) return;\n    var name = mod.verboseName.replace(/\\\\/g, \"/\");\n    if (!/(^|\\/)react-native\\/Libraries\\/LogBox\\/Data\\/LogBoxData\\.js$/.test(name)) return;\n    var exports = mod.publicModule && mod.publicModule.exports;\n    if (exports && typeof exports.addIgnorePatterns === \"function\") data = exports;\n  });\n  if (!data) return \"not-ready\";\n  data.addIgnorePatterns([/[\\s\\S]*/]);\n  if (typeof data.setDisabled === \"function\") data.setDisabled(true);\n  if (typeof data.setSelectedLog === \"function\") data.setSelectedLog(-1);\n  return \"off\";\n})(typeof globalThis !== \"undefined\" ? globalThis : (typeof global !== \"undefined\" ? global : this))";

package/types/e2e/src/devtools/session.d.ts

@@ -1,4 +1,5 @@
 import { type Result } from "../../../types/src/result";
+import { type CloseInfo } from "./cdp";
 import { type CdpTap, type DevtoolsError, type DevtoolsResult, type EvaluateError, type Fetch, type Sleep } from "./devtools.types";
 import { type SelectedTarget } from "./inspector";
 /** The one binding warden installs; scripts call `__warden_cb(JSON.stringify({ requestId, … }))`. */
@@ -35,6 +36,11 @@ export type ConnectDevtoolsOptions = {
     taps?: readonly CdpTap[];
     /** how long `reloadJs` waits for the app to start tearing its JS context down (default 5 s) */
     reloadWaitMs?: number;
+    /**
+     * Asked when the socket closes on its own. `true` = another debugger took the page: do not reconnect (that would
+     * kick it in turn), close the session and emit `yielded`. Default: always reconnect.
+     */
+    yieldOnClose?: (info: CloseInfo) => boolean;
 };
 export type DevtoolsSession = {
     /** `Runtime.evaluate` by value. A thrown JS error fails with `exceptionDetails`. Waits out a reconnect. */
@@ -64,7 +70,7 @@ export type DevtoolsSession = {
     /** Tap on every CDP event, handshake events flagged `replay`; survives reconnects. */
     onEvent: (tap: CdpTap) => () => void;
     evaluateWithBinding: (script: string, requestId: string, timeoutMs?: number) => Promise<DevtoolsResult<unknown>>;
-    /** `reconnected` (new target attached) and `lost` (gave up reconnecting) */
+    /** `reconnected` (new target attached), `lost` (gave up reconnecting), `yielded` (`yieldOnClose` said stop) */
     on: <E extends keyof SessionEvents>(event: E, handler: (arg: SessionEvents[E]) => void) => () => void;
     close: () => void;
 };
@@ -72,6 +78,7 @@ export type ReloadMethod = "expo" | "devsettings" | "http";
 export type SessionEvents = {
     reconnected: SelectedTarget;
     lost: DevtoolsError;
+    yielded: CloseInfo;
 };
 /**
  * Attach to the app's Hermes runtime through Metro's inspector proxy. Connect sequence (same as Chrome's Fusebox

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

@@ -2,20 +2,21 @@ import type { Exec } from "../../../../core/src/exec";
 import type { E2eEnv } from "../../env";
 import type { ProbesFrontmost, ReadsAlertOn } from "../alerts";
 import type { Driver, DriverResult, KeyName, Logger } from "../driver.types";
-import type { SelectsAll } from "../typing";
+import type { PastesText, SelectsAll } from "../typing";
 import { type SwappableClient } from "./ios-session";
 import { type Simctl } from "./simctl";
 import { type SimdClient } from "./simd-client";
 import type { SimdSpawn } from "./simd-transport";
 /**
- * The iOS `Driver`: input and AX through `warden-simd` (socket when `WARDEN_SIMD_SOCKET` is set, else a
- * helper spawned on stdio), app lifecycle / clipboard / appearance through `xcrun simctl`. Fallbacks:
- * `typeText` pastes what the HID keyboard map cannot type, `settle` polls snapshot hashes when the
- * helper has no native quiescence, `screenshot` uses `simctl io` when the helper cannot.
+ * The iOS `Driver`: input, AX and app launch / terminate / openUrl through `warden-simd` (socket when
+ * `WARDEN_SIMD_SOCKET` is set, else a helper spawned on stdio); install / uninstall / isRunning / clearData,
+ * clipboard and appearance through `xcrun simctl`. Fallbacks: `typeText` pastes what the HID keyboard map
+ * cannot type, `settle` polls snapshot hashes when the helper has no native quiescence, `screenshot` uses
+ * `simctl io` when the helper cannot, and a helper built before the app ops leaves app lifecycle to `simctl`.
  */
 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 & ReadsAlertOn & ProbesFrontmost;
+export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost;
 export type OpenIosDriverOptions = {
     udid: string;
     env?: IosDriverEnv;

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

@@ -275,6 +275,21 @@ export declare const frontmostDataSchema: z.ZodObject<{
     frontmostPid: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 export type FrontmostData = z.infer<typeof frontmostDataSchema>;
+/**
+ * `launch{bundleId, args?, env?, terminateRunning?}`: the helper starts the app in the process that already holds
+ * CoreSimulator (no `simctl` process per launch). `args` follow the executable, `env` reaches the app as given, and
+ * `terminateRunning` (default true) ends a running instance first; false brings a running app to the front instead.
+ * `pid` is the process that is running when the op answers.
+ */
+export declare const launchDataSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+}, z.core.$loose>;
+export type LaunchData = z.infer<typeof launchDataSchema>;
+/** `terminate{bundleId}`: `terminated: false` says nothing was running, which is the wanted state, not an error. */
+export declare const terminateDataSchema: z.ZodObject<{
+    terminated: z.ZodBoolean;
+}, z.core.$loose>;
+export type TerminateData = z.infer<typeof terminateDataSchema>;
 /**
  * `orientation`: a real read may also say `faceUp` / `faceDown` / `unknown` (flat device); `source` tells
  * whether the value was read from the device, is the last one this helper wrote, or is an assumed portrait.
@@ -401,6 +416,12 @@ export declare const opSchemas: {
             assumed: "assumed";
         }>>;
     }, z.core.$strip>;
+    readonly launch: z.ZodObject<{
+        pid: z.ZodNumber;
+    }, z.core.$loose>;
+    readonly terminate: z.ZodObject<{
+        terminated: z.ZodBoolean;
+    }, z.core.$loose>;
 };
 export type OpDataMap = {
     health: HealthData;
@@ -412,6 +433,8 @@ export type OpDataMap = {
     alertButtons: AlertButtonsData;
     frontmost: FrontmostData;
     orientation: OrientationData;
+    launch: LaunchData;
+    terminate: TerminateData;
 };
 export type OpData<Op extends string> = Op extends keyof OpDataMap ? OpDataMap[Op] : unknown;
 export declare function hasOpSchema(op: string): op is keyof typeof opSchemas;

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

@@ -1,6 +1,10 @@
-/** Per-request budget for the helper's `typeText`: it holds, paces and (for a repeated key) waits per character. */
+/**
+ * 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.
+ */
 export declare const TYPE_BASE_MS = 10000;
-export declare const TYPE_PER_CHAR_MS = 70;
-export declare const TYPE_PER_REPEAT_MS = 300;
-/** Base + ~70 ms per character + 300 ms per character equal to the one before it. */
+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;

package/types/e2e/src/driver/observation-cache.d.ts

@@ -8,7 +8,9 @@ import type { AlertInfo, Driver, DriverResult, Platform, Snapshot } from "./driv
  * the one driver: whatever calls it, an input moves the *generation* on and the kept snapshot dies with the old one.
  * A snapshot is also dropped once it is older than the platform's max age, input or not (the app can change by itself).
  * Which reads may reuse one is the caller's call (`observe({ reuse })`): only the first look of a wait does, so a
- * poll never spins on a tree that stopped being true.
+ * poll never spins on a tree that stopped being true. A `settle` is a wait, not an input: the kept snapshot predates
+ * it and is dropped, but nothing was pressed, so `previous().sinceInputMs` still counts from the last real input; one
+ * that reports `quiet` is the app's word that the input has landed, and then no input is recent at all.
  */
 /** How old a kept snapshot may be and still answer a read. iOS reads cost ~100-300 ms; an Android dump takes ~1.9 s. */
 export declare const OBSERVATION_MAX_AGE_MS: Record<Platform, number>;

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

@@ -42,6 +42,16 @@ export type SetsText = {
     setText(text: string): DriverResult<void>;
 };
 export declare function canSetText(driver: Driver): driver is Driver & SetsText;
+/**
+ * Optional fast path next to the frozen `Driver`: put `text` on the device pasteboard and paste it into the focused
+ * field with one Cmd+V (iOS `simctl.pbcopy` then `warden-simd` `paste`), replacing the selection. Cost is flat (~400 ms)
+ * where typing is 70-260 ms per character. A pasteboard write that cannot be confirmed is an error (nothing was
+ * pasted) and the caller types the old way.
+ */
+export type PastesText = {
+    pasteText(text: string): DriverResult<void>;
+};
+export declare function canPasteText(driver: Driver): driver is Driver & PastesText;
 /** Types `text` at the caret. Android types the whole string in one call. */
 export declare function typeText(driver: Driver, sleep: Sleep, text: string): DriverResult<void>;
 /** Presses `key` `times` times, paced like typed characters. */

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

@@ -27,3 +27,8 @@ export declare function isCi(env: Readonly<Record<string, string | undefined>>):
  * session eagerly and, in `afterAll`, closes it and (under `CI`) fails the run if a `.only` was collected.
  */
 export declare function installPreload(deps: PreloadDeps): void;
+/**
+ * `warden e2e` may run this process as a compiled warden with `BUN_BE_BUN=1`; drop it so a `warden` the spec spawns
+ * (`WARDEN_BIN`, `device.perf`) runs as warden, not bun.
+ */
+export declare function scrubRunnerEnv(env: Record<string, string | undefined>): void;

package/types/e2e/src/screen/field.d.ts

@@ -101,6 +101,12 @@ export type ClearMethod = "auto" | "counted" | "setText";
 export declare const SETTEXT_ENV = "WARDEN_ANDROID_SETTEXT";
 /** Whether `env` opts `auto` fills into `setText` (`SETTEXT_ENV`). */
 export declare function setTextOptedIn(env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * How `focusClearType` puts text in. `paste` writes it to the pasteboard and sends one Cmd+V on a driver that offers
+ * `pasteText` (iOS: ~400 ms flat against 70-260 ms per typed character), and types when it does not or when the paste
+ * fails; `type` always types.
+ */
+export type FillVia = "paste" | "type";
 /**
  * Taps `point` and empties what `entry` shows: select-all and one Backspace when the driver offers it, else one
  * Backspace per character (see `focusAndSelect`). The clear routine behind the spec `clear` and `warden ui clear`.
@@ -117,5 +123,9 @@ export declare function focusAndClear(driver: Driver, sleep: Sleep, point: Point
  * select-all then typing; the read-back after a `fill` checks it took, and the counted retry types. An empty field gains
  * nothing from it, and a secure one cannot be read back, so both are typed as before. A `setText` that fails falls back
  * to select-all and typing, without a second tap.
+ *
+ * With `via: "paste"` (the default) on a driver with `pasteText` (iOS), the text replaces the selection with one paste,
+ * secure fields included (they keep their Backspace-per-dot clearing). A paste that fails (pasteboard write not
+ * confirmed) is typed in the same attempt; nothing was pasted, so the selection is still there to be replaced.
  */
-export declare function focusClearType(driver: Driver, sleep: Sleep, point: Point, entry: NodeEntry | undefined, text: string, method?: ClearMethod, env?: Readonly<Record<string, string | undefined>>): DriverResult<void>;
+export declare function focusClearType(driver: Driver, sleep: Sleep, point: Point, entry: NodeEntry | undefined, text: string, method?: ClearMethod, env?: Readonly<Record<string, string | undefined>>, via?: FillVia): DriverResult<void>;