@delacour/warden-e2e 0.2.0 → 0.4.0

package/index.mjs

@@ -31,7 +31,7 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-7ns30pbp.mjs";
+} from "./chunk-3874jt2j.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
@@ -742,60 +742,60 @@ async function runAttemptOnce(session, spec) {
   const bound = attemptSession(session, () => binding ?? { context: ctx, finished: false });
   print(formatConsoleLine({ type: "test-start", test: { file: spec.file, title: [...spec.title], startedAt, device } }, { clock }));
   session.enterAttempt(ctx);
+  const teardowns = [];
+  const state = {};
+  let outcome = await raceDeadline(controller, use.timeoutMs, () => setUpAndRun(bound, spec, use, controller.signal, state, teardowns));
+  outcome = failIf(outcome, ctx.softFailures.length > 0, () => softFailureError(ctx.softFailures));
+  if (outcome.failed)
+    await captureFailureArtifacts(session, ctx, budget, startedAt);
+  const cleanupErrors = await runCleanup(session, spec, ctx, state.bag, teardowns, budget, (context) => {
+    binding = { context, finished: false };
+  });
+  const finished = new E2eError2("SESSION", "attempt finished");
+  if (!controller.signal.aborted)
+    controller.abort(finished);
+  binding = { context: { ...ctx, signal: AbortSignal.abort(finished), depth: 0 }, finished: true };
+  session.leaveAttempt(ctx);
+  trace.flush();
+  outcome = failIf(outcome, cleanupErrors.length > 0, () => cleanupErrors[0]);
+  return concludeAttempt(session, spec, ctx, { startedAt, device }, outcome, print, clock);
+}
+async function raceDeadline(controller, timeoutMs, run) {
   let deadlineHit = false;
   const timer = setTimeout(() => {
     deadlineHit = true;
-    controller.abort(new E2eError2("TIMEOUT", `test timed out after ${use.timeoutMs}ms`));
-  }, use.timeoutMs);
+    controller.abort(new E2eError2("TIMEOUT", `test timed out after ${timeoutMs}ms`));
+  }, timeoutMs);
   const deadline = new Promise((_, reject) => {
     controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true });
   });
   deadline.catch(() => {
     return;
   });
-  const teardowns = [];
-  const state = {};
-  let failed = false;
-  let failure;
   try {
-    await Promise.race([setUpAndRun(bound, spec, use, controller.signal, state, teardowns), deadline]);
+    await Promise.race([run(), deadline]);
+    return { failed: false, failure: undefined, deadlineHit };
   } catch (error) {
-    failed = true;
-    failure = error;
+    return { failed: true, failure: error, deadlineHit };
   } finally {
     clearTimeout(timer);
   }
-  if (!failed && ctx.softFailures.length > 0) {
-    failed = true;
-    failure = softFailureError(ctx.softFailures);
-  }
-  if (failed)
-    await captureFailureArtifacts(session, ctx, budget, startedAt);
-  const cleanupErrors = await runCleanup(session, spec, ctx, state.bag, teardowns, budget, (context) => {
-    binding = { context, finished: false };
-  });
-  const finished = new E2eError2("SESSION", "attempt finished");
-  if (!controller.signal.aborted)
-    controller.abort(finished);
-  binding = { context: { ...ctx, signal: AbortSignal.abort(finished), depth: 0 }, finished: true };
-  session.leaveAttempt(ctx);
-  trace.flush();
-  if (!failed && cleanupErrors.length > 0) {
-    failed = true;
-    failure = cleanupErrors[0];
-  }
-  for (const shot of listScreenshots(dir))
-    files.add(shot);
-  const outcome = failed ? { failed: true, error: failure, timedOut: deadlineHit } : { failed: false };
-  const result = buildResult(spec, ctx, { startedAt, device }, outcome);
+}
+function failIf(outcome, present, failure) {
+  return outcome.failed || !present ? outcome : { ...outcome, failed: true, failure: failure() };
+}
+async function concludeAttempt(session, spec, ctx, run, outcome, print, clock) {
+  for (const shot of listScreenshots(ctx.dir))
+    ctx.files.add(shot);
+  const result = buildResult(spec, ctx, run, outcome.failed ? { failed: true, error: outcome.failure, timedOut: outcome.deadlineHit } : { failed: false });
   print(formatConsoleLine({ type: "test-end", result }, { clock }));
-  if (failed && session.recoverHid !== undefined && isHidLost(failure) && await session.recoverHid()) {
+  if (outcome.failed && session.recoverHid !== undefined && isHidLost(outcome.failure) && await session.recoverHid()) {
     return "again";
   }
-  if (!failed || spec.final)
+  if (!outcome.failed || spec.final)
     session.results.append(result);
-  if (failed)
-    throw failure instanceof Error ? failure : new Error(String(failure));
+  if (outcome.failed)
+    throw outcome.failure instanceof Error ? outcome.failure : new Error(String(outcome.failure));
   return;
 }
 function softFailureError(failures) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TypeScript spec API for `warden e2e`: test, expect, screen, device, app",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@delacour/warden": "0.2.0"
+    "@delacour/warden": "0.4.0"
   },
   "dependencies": {
     "zod": "^4.4.3"

package/preload.mjs

@@ -68,7 +68,7 @@ import {
   onlyWasSeen,
   WORKSPACE_VERSION,
   WARDEN_E2E_VERSION2
-} from "./chunk-7ns30pbp.mjs";
+} from "./chunk-3874jt2j.mjs";
 
 // ../../packages/e2e/src/preload.ts
 import { afterAll, setDefaultTimeout } from "bun:test";
@@ -3238,8 +3238,8 @@ function createSimctl(deps) {
 
 // ../../packages/e2e/src/driver/ios/type-budget.ts
 var TYPE_BASE_MS = 1e4;
-var TYPE_PER_CHAR_MS = 70;
-var TYPE_PER_REPEAT_MS = 300;
+var TYPE_PER_CHAR_MS = 100;
+var TYPE_PER_REPEAT_MS = 200;
 function typeTextBudgetMs(text) {
   const characters = Array.from(text);
   let repeats = 0;
@@ -3257,6 +3257,8 @@ var SETTLE_MARGIN_MS = 2000;
 var REBIND_TIMEOUT_MS = 3000;
 var GESTURE_MARGIN_MS = 5000;
 var FRONTMOST_TIMEOUT_MS = 3000;
+var LAUNCH_TIMEOUT_MS = 30000;
+var APP_OP_TIMEOUT_MS = 15000;
 var KEY_USAGE = {
   Enter: 40,
   Escape: 41,
@@ -3311,6 +3313,25 @@ function nativeDetail(data) {
     noteSpanDetail("frontmostPid", frontmostPid);
   return detail;
 }
+function noteRebind(data) {
+  noteSpanDetail("rebind", data.bound ? "bound" : data.reason ?? "unbound");
+  noteSpanDetail("rebindMs", data.waitedMs);
+  if (data.restarts !== undefined && data.restarts > 0)
+    noteSpanDetail("rebindRestarts", data.restarts);
+  if (data.recycled === true)
+    noteSpanDetail("rebindRecycled", true);
+}
+function healthDetail(d) {
+  return {
+    axDefault: d.ax.default,
+    ...d.ax.bridge === "degraded" ? { axBridge: "degraded" } : {},
+    ...d.ax.lastError ? { axLastError: d.ax.lastError } : {},
+    ...d.ax.error !== undefined ? { axError: d.ax.error } : {},
+    ...d.socket ? { socket: d.socket } : {},
+    ...d.xcode ? { xcode: d.xcode } : {},
+    ...d.state ? { state: d.state } : {}
+  };
+}
 
 class DriverFailure extends Error {
   error;
@@ -3329,6 +3350,9 @@ function restOf(error, text) {
 function decodeBase64(png) {
   return new Uint8Array(Buffer.from(png, "base64"));
 }
+function predatesOp(error) {
+  return error.code === "E_UNSUPPORTED" || error.code === "E_BAD_REQUEST" && /unknown (input )?op/.test(error.message);
+}
 function createIosDriver(swap, simctl, opts) {
   const { udid, now, sleep } = opts;
   const { client } = swap;
@@ -3340,6 +3364,7 @@ function createIosDriver(swap, simctl, opts) {
   let settleUnsupported = !nativeSettle;
   let rebindUnsupported = false;
   let gestureUnsupported = false;
+  let appOpsOutdated = false;
   const capabilities = {
     pinch: true,
     maxPointers: 2,
@@ -3407,6 +3432,30 @@ function createIosDriver(swap, simctl, opts) {
     }
     return result;
   };
+  async function appOp(op, p, timeoutMs) {
+    if (appOpsOutdated) {
+      noteSpanDetail("via", "simctl");
+      return;
+    }
+    const result = await request(op, p, { timeoutMs });
+    if (!result.success && predatesOp(result.error)) {
+      appOpsOutdated = true;
+      noteSpanDetail("via", "simctl");
+      noteSpanDetail("reason", "helper_outdated");
+      opts.log?.(`[ios] this warden-simd predates the \`${op}\` op (${result.error.code}: ${result.error.message}); app lifecycle goes through simctl until the helper is restarted (warden ui close --udid ${udid}) or rebuilt (bun run --cwd packages/e2e native:build)`);
+      return;
+    }
+    noteSpanDetail("via", "simd");
+    return result;
+  }
+  async function appOutcome(viaHelper, fallback, note) {
+    if (viaHelper === undefined)
+      return fallback();
+    if (!viaHelper.success)
+      return viaHelper;
+    note(viaHelper.data);
+    return okVoid;
+  }
   const fetchSnapshot = async (o) => {
     const result = await request("snapshot", params({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }));
     if (!result.success)
@@ -3444,11 +3493,17 @@ function createIosDriver(swap, simctl, opts) {
     const rest = restOf(typed.error, text);
     if (rest === undefined)
       return typed;
-    const copied = await simctl.pbcopy(rest);
-    if (!copied.success)
-      return copied;
     opts.log?.(`[ios] typeText: pasting ${rest.length} unmappable character(s)`);
-    return sendVoid("paste");
+    return pasteText(rest);
+  }
+  async function pasteText(text) {
+    if (text === "")
+      return ok(undefined);
+    const copied = await simctl.pbcopy(text);
+    const result = copied.success ? await sendVoid("paste") : copied;
+    if (!result.success)
+      opts.log?.(`[ios] pasteText failed (${result.error.code}): ${result.error.message}`);
+    return result;
   }
   async function hashSettle(o) {
     try {
@@ -3477,36 +3532,37 @@ function createIosDriver(swap, simctl, opts) {
       opts.log?.(`[ios] rebind after launch failed (${reply.error.code}): ${reply.error.message}`);
       return false;
     }
-    noteSpanDetail("rebind", reply.data.bound ? "bound" : reply.data.reason ?? "unbound");
-    noteSpanDetail("rebindMs", reply.data.waitedMs);
-    if (reply.data.restarts !== undefined && reply.data.restarts > 0)
-      noteSpanDetail("rebindRestarts", reply.data.restarts);
-    if (reply.data.recycled === true)
-      noteSpanDetail("rebindRecycled", true);
+    noteRebind(reply.data);
     return reply.data.bound;
   }
+  async function settleViaHelper(quietMs, timeoutMs) {
+    const expected = launchedBundle;
+    const native = await request("settle", { quietMs, settleTimeoutMs: timeoutMs, ...expected === undefined ? {} : { bundleId: expected } }, { timeoutMs: timeoutMs + SETTLE_MARGIN_MS });
+    if (native.success) {
+      if (expected !== undefined && native.data.reason !== "frontmost_mismatch")
+        launchedBundle = undefined;
+      return { success: true, data: nativeDetail(native.data) };
+    }
+    if (native.error.code === "E_TIMEOUT") {
+      noteSpanDetail("reason", "helper_timeout");
+      return {
+        success: true,
+        data: { quiet: false, waitedMs: timeoutMs + SETTLE_MARGIN_MS, reason: "helper_timeout" }
+      };
+    }
+    if (native.error.code !== "E_UNSUPPORTED")
+      return native;
+    settleUnsupported = true;
+    opts.log?.("[ios] native settle unsupported, polling snapshot hashes");
+    return;
+  }
   async function settle(o = {}) {
     const quietMs = o.quietMs ?? DEFAULT_QUIET_MS;
     const timeoutMs = o.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS2;
     if (!settleUnsupported) {
-      const expected = launchedBundle;
-      const native = await request("settle", { quietMs, settleTimeoutMs: timeoutMs, ...expected === undefined ? {} : { bundleId: expected } }, { timeoutMs: timeoutMs + SETTLE_MARGIN_MS });
-      if (native.success) {
-        if (expected !== undefined && native.data.reason !== "frontmost_mismatch")
-          launchedBundle = undefined;
-        return { success: true, data: nativeDetail(native.data) };
-      }
-      if (native.error.code === "E_TIMEOUT") {
-        noteSpanDetail("reason", "helper_timeout");
-        return {
-          success: true,
-          data: { quiet: false, waitedMs: timeoutMs + SETTLE_MARGIN_MS, reason: "helper_timeout" }
-        };
-      }
-      if (native.error.code !== "E_UNSUPPORTED")
+      const native = await settleViaHelper(quietMs, timeoutMs);
+      if (native)
         return native;
-      settleUnsupported = true;
-      opts.log?.("[ios] native settle unsupported, polling snapshot hashes");
     }
     return hashSettle({ quietMs, timeoutMs });
   }
@@ -3564,15 +3620,7 @@ function createIosDriver(swap, simctl, opts) {
         transport: d.hid.transport,
         bridge: d.ax.bridge === "degraded" ? "available" : d.ax.bridge,
         screen: d.screen,
-        detail: {
-          axDefault: d.ax.default,
-          ...d.ax.bridge === "degraded" ? { axBridge: "degraded" } : {},
-          ...d.ax.lastError ? { axLastError: d.ax.lastError } : {},
-          ...d.ax.error !== undefined ? { axError: d.ax.error } : {},
-          ...d.socket ? { socket: d.socket } : {},
-          ...d.xcode ? { xcode: d.xcode } : {},
-          ...d.state ? { state: d.state } : {}
-        }
+        detail: healthDetail(d)
       }
     };
   }
@@ -3619,6 +3667,7 @@ function createIosDriver(swap, simctl, opts) {
     typeText,
     key: (key, modifiers) => sendVoid("key", params({ usage: KEY_USAGE[key], modifiers: modifiers && [...modifiers] })),
     selectAll: () => sendVoid("selectAll"),
+    pasteText,
     pressButton,
     screenshot,
     orientation,
@@ -3635,7 +3684,8 @@ function createIosDriver(swap, simctl, opts) {
     },
     app: {
       launch: async (bundleId, o) => {
-        const launched = await simctl.launch(bundleId, o);
+        const viaHelper = await appOp("launch", params({ bundleId, args: o?.args && [...o.args], env: o?.env, terminateRunning: o?.relaunch !== false }), LAUNCH_TIMEOUT_MS);
+        const launched = await appOutcome(viaHelper, () => simctl.launch(bundleId, o), (data) => noteSpanDetail("pid", data.pid));
         if (launched.success) {
           launchedBundle = bundleId;
           if (await rebind(bundleId))
@@ -3644,12 +3694,18 @@ function createIosDriver(swap, simctl, opts) {
         return launched;
       },
       terminate: async (bundleId) => {
-        const terminated = await simctl.terminate(bundleId);
+        const viaHelper = await appOp("terminate", { bundleId }, APP_OP_TIMEOUT_MS);
+        const terminated = await appOutcome(viaHelper, () => simctl.terminate(bundleId), (data) => noteSpanDetail("terminated", data.terminated));
         if (terminated.success && launchedBundle === bundleId)
           launchedBundle = undefined;
         return terminated;
       },
-      openUrl: (url) => simctl.openUrl(url),
+      openUrl: async (url) => {
+        const viaHelper = await appOp("openUrl", { url }, APP_OP_TIMEOUT_MS);
+        return appOutcome(viaHelper, () => simctl.openUrl(url), () => {
+          return;
+        });
+      },
       install: (path) => simctl.install(path),
       uninstall: (bundleId) => simctl.uninstall(bundleId),
       isInstalled: (bundleId) => simctl.isInstalled(bundleId),
@@ -4761,6 +4817,10 @@ ${read.error}
     }
   });
 }
+function scrubRunnerEnv(env) {
+  delete env.BUN_BE_BUN;
+}
+scrubRunnerEnv(process.env);
 if (!hasDefaultDriverFactory()) {
   setDefaultDriverFactory(defaultDriverFactory);
   setDefaultNativeLog(realNativeLogDeps(bunExec, androidTools(process.env).adb));
@@ -4784,5 +4844,6 @@ export {
   BUN_TIMEOUT_MARGIN_MS2 as BUN_TIMEOUT_MARGIN_MS,
   installPreload,
   isCi,
+  scrubRunnerEnv,
   versionMismatch
 };

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/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/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/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>;