@delacour/warden-e2e 0.3.1 → 0.4.0

package/{chunk-8em9kgsk.mjs → chunk-3874jt2j.mjs}

@@ -64,10 +64,17 @@ var READS = new Set([
   "previous",
   "peek"
 ]);
+var WAITS = new Set(["settle"]);
 var READS_WITHOUT_ARGUMENT = new Set(["orientation", "appearance", "clipboard"]);
 function isCall(value) {
   return typeof value === "function";
 }
+function reportsQuiet(result) {
+  if (typeof result !== "object" || result === null || !("success" in result) || result.success !== true)
+    return false;
+  const data = "data" in result ? result.data : undefined;
+  return typeof data === "object" && data !== null && "quiet" in data && data.quiet === true;
+}
 function isThenable(value) {
   return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
@@ -137,21 +144,31 @@ function cacheObservations(driver, options = {}) {
       return { success: true, data: reader.alertIn(taken.data) };
     };
   };
-  const asInput = (fn, target) => {
+  const edged = (fn, target, edge) => {
     return (...args) => {
-      inputEdge();
+      edge();
       let result;
       try {
         result = Reflect.apply(fn, target, args);
       } catch (error) {
-        inputEdge();
+        edge();
         throw error;
       }
       if (!isThenable(result)) {
-        inputEdge();
+        edge();
         return result;
       }
-      return Promise.resolve(result).finally(inputEdge);
+      return Promise.resolve(result).finally(edge);
+    };
+  };
+  const asInput = (fn, target) => edged(fn, target, inputEdge);
+  const asWait = (fn, target) => {
+    const waited = edged(fn, target, moveOn);
+    return async (...args) => {
+      const result = await waited(...args);
+      if (reportsQuiet(result))
+        lastInputAt = undefined;
+      return result;
     };
   };
   const wrapMember = (name, value, target) => {
@@ -159,6 +176,8 @@ function cacheObservations(driver, options = {}) {
       return wrap(value, {});
     if (!isCall(value) || READS.has(name))
       return value;
+    if (WAITS.has(name))
+      return asWait(value, target);
     const input = asInput(value, target);
     if (!READS_WITHOUT_ARGUMENT.has(name))
       return input;
@@ -271,6 +290,9 @@ function canSelectAll(driver) {
 function canSetText(driver) {
   return typeof driver.setText === "function";
 }
+function canPasteText(driver) {
+  return typeof driver.pasteText === "function";
+}
 var segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 function graphemesOf(text) {
   return Array.from(segmenter.segment(text), (part) => part.segment);
@@ -921,7 +943,7 @@ async function focusAndClear(driver, sleep, point, entry, method = "auto") {
     return prepared;
   return prepared.data.pending === "selection" ? pressKeys(driver, sleep, "Backspace", 1) : ok(undefined);
 }
-async function focusClearType(driver, sleep, point, entry, text, method = "auto", env = process.env) {
+async function focusClearType(driver, sleep, point, entry, text, method = "auto", env = process.env, via = "paste") {
   const wantsSetText = method === "setText" || method === "auto" && setTextOptedIn(env);
   if (wantsSetText && entry !== undefined && fieldContent(entry).kind === "text" && canSetText(driver)) {
     const focused = await driver.tap(point);
@@ -930,15 +952,20 @@ async function focusClearType(driver, sleep, point, entry, text, method = "auto"
     const replaced = await driver.setText(text);
     if (replaced.success)
       return replaced;
-    return typeOver(driver, sleep, await prepareFocused(driver, sleep, entry, method), text);
+    return typeOver(driver, sleep, await prepareFocused(driver, sleep, entry, method), text, "type");
   }
-  return typeOver(driver, sleep, await focusAndSelect(driver, sleep, point, entry, method), text);
+  return typeOver(driver, sleep, await focusAndSelect(driver, sleep, point, entry, method), text, via);
 }
-async function typeOver(driver, sleep, prepared, text) {
+async function typeOver(driver, sleep, prepared, text, via) {
   if (!prepared.success)
     return prepared;
   if (text === "")
     return prepared.data.pending === "selection" ? pressKeys(driver, sleep, "Backspace", 1) : ok(undefined);
+  if (via === "paste" && canPasteText(driver)) {
+    const pasted = await driver.pasteText(text);
+    if (pasted.success)
+      return pasted;
+  }
   return typeText(driver, sleep, text);
 }
 
@@ -1750,10 +1777,20 @@ class Locator {
     const reason = blockedReason(entry, spec, observed);
     if (reason !== undefined)
       return { done: false, state: { kind: "blocked", reason, snapshot: observed.snapshot } };
-    if (!anyFrame && !this.heldStill(entry, observation.earlier))
-      return "moving";
+    if (!anyFrame && !this.heldStill(entry, observation.earlier)) {
+      const compared = observation.earlier?.previous !== undefined;
+      if (compared || !await this.stillByHitTest(entry, observed))
+        return "moving";
+    }
     return { done: true, value: { entry, observed } };
   }
+  async stillByHitTest(entry, observed) {
+    const { driver } = observed;
+    if (driver.capabilities.cheapHitTest !== true || this.rt.host.answerSystemAlert !== undefined)
+      return false;
+    const hit = await driver.elementAtPoint(tapPointOf(entry));
+    return hit.success && hit.data !== null && sameElement(hit.data, entry.element);
+  }
   heldStill(entry, earlier) {
     if (earlier === undefined)
       return true;
@@ -1851,14 +1888,15 @@ class Locator {
     });
   }
   async fill(text, options = {}) {
-    assertOptions("fill", options, ["timeout"]);
+    assertOptions("fill", options, ["via", "timeout"]);
+    const via = fillViaOf(this, options.via);
     return this.act("fill", async () => {
       const budget = this.rt.budget(options.timeout);
       let target = await this.actionable({ enabled: true, tapPointOnScreen: false }, budget.remaining());
       let firstHeld;
       for (let attempt = 1;; attempt += 1) {
         const point = focusPoint(target.entry.element.frame);
-        this.rt.drive("fill", await focusClearType(target.observed.driver, this.pause, point, target.entry, text, clearMethodFor(attempt)));
+        this.rt.drive("fill", await focusClearType(target.observed.driver, this.pause, point, target.entry, text, clearMethodFor(attempt), process.env, viaFor(attempt, via)));
         if (target.entry.secure)
           return;
         const outcome = await this.confirm(target, text, budget);
@@ -2067,6 +2105,14 @@ function retryPlan(options) {
 function describeUntil(until) {
   return typeof until === "function" ? "check" : String(until);
 }
+function fillViaOf(locator, via) {
+  if (via === undefined || via === "paste" || via === "type")
+    return via ?? "paste";
+  throw new E2eError2("INVALID_ARGUMENT", `${locator}: fill via must be "paste" or "type", got ${JSON.stringify(via)}`);
+}
+function viaFor(attempt, via) {
+  return attempt === 1 ? via : "type";
+}
 function clearMethodFor(attempt) {
   return attempt === 1 ? "auto" : "counted";
 }
@@ -2313,7 +2359,7 @@ async function openCdp(wsUrl, options = {}) {
     if (method)
       dispatch(method, params);
   });
-  ws.addEventListener("close", () => {
+  ws.addEventListener("close", (event) => {
     if (closed)
       return;
     closed = true;
@@ -2326,7 +2372,7 @@ async function openCdp(wsUrl, options = {}) {
       binding.settle(devtoolsErr("cdp_closed", "CDP connection closed"));
     if (!intentional)
       for (const handler of [...closeHandlers])
-        handler();
+        handler({ code: event.code, reason: event.reason });
   });
   const subscribe = (set, handler) => {
     set.add(handler);
@@ -2427,7 +2473,8 @@ var stackTraceSchema = z2.looseObject({
   callFrames: z2.array(z2.looseObject({
     url: z2.string().optional(),
     lineNumber: z2.number().optional(),
-    columnNumber: z2.number().optional()
+    columnNumber: z2.number().optional(),
+    functionName: z2.string().optional()
   }))
 });
 var consoleCalledSchema = z2.looseObject({
@@ -2438,7 +2485,7 @@ var consoleCalledSchema = z2.looseObject({
 });
 var exceptionThrownSchema = z2.looseObject({
   timestamp: z2.number().optional(),
-  exceptionDetails: exceptionDetailsSchema
+  exceptionDetails: exceptionDetailsSchema.extend({ stackTrace: stackTraceSchema.optional() })
 });
 var LEVELS = {
   log: "log",
@@ -2529,6 +2576,20 @@ function sourceOf(url, line, col) {
     return;
   return { url, line: (line ?? 0) + 1, col: (col ?? 0) + 1 };
 }
+function framesOf(trace) {
+  const frames = [];
+  for (const frame of trace?.callFrames ?? []) {
+    if (!frame.url)
+      continue;
+    frames.push({
+      file: frame.url,
+      line: (frame.lineNumber ?? 0) + 1,
+      col: (frame.columnNumber ?? 0) + 1,
+      ...frame.functionName ? { fn: frame.functionName } : {}
+    });
+  }
+  return frames.length > 0 ? frames : undefined;
+}
 var lineKey = (ts, text) => `${ts}\x00${text}`;
 function createConsoleCapture(options = {}) {
   const ring = options.ring ?? DEFAULT_RING;
@@ -2576,13 +2637,15 @@ function createConsoleCapture(options = {}) {
     const formatted = formatConsoleArgs(args);
     const frame = stackTrace?.callFrames[0];
     const source = sourceOf(frame?.url, frame?.lineNumber, frame?.columnNumber);
+    const stack = framesOf(stackTrace);
     return {
       ts: timestamp ?? now(),
       level: LEVELS[type] ?? "log",
       kind: "console",
       text: formatted.text,
       args: formatted.args,
-      ...source ? { source } : {}
+      ...source ? { source } : {},
+      ...stack ? { stack } : {}
     };
   };
   const fromException = (params) => {
@@ -2591,12 +2654,14 @@ function createConsoleCapture(options = {}) {
       return;
     const { exceptionDetails: details, timestamp } = parsed.data;
     const source = sourceOf(details.url, details.lineNumber, details.columnNumber);
+    const stack = framesOf(details.stackTrace);
     return {
       ts: timestamp ?? now(),
       level: "error",
       kind: "exception",
       text: describeException(details),
-      ...source ? { source } : {}
+      ...source ? { source } : {},
+      ...stack ? { stack } : {}
     };
   };
   return {
@@ -3033,7 +3098,8 @@ async function connectDevtools(o) {
   const cdpHandlers = new Map;
   const eventHandlers = {
     reconnected: new Set,
-    lost: new Set
+    lost: new Set,
+    yielded: new Set
   };
   let unsubscribeCdp = [];
   let connection = 0;
@@ -3083,9 +3149,17 @@ async function connectDevtools(o) {
       for (const handler of handlers)
         unsubscribeCdp.push(attached.cdp.on(method, handler));
     }
-    attached.cdp.onClose(() => {
-      if (state.kind === "up" && state.attached.cdp === attached.cdp)
-        reconnect("socket closed");
+    attached.cdp.onClose((info) => {
+      if (state.kind !== "up" || state.attached.cdp !== attached.cdp)
+        return;
+      if (o.yieldOnClose?.(info)) {
+        state = { kind: "closed" };
+        log(`devtools: yielded (${info.code} ${info.reason})`);
+        for (const handler of [...eventHandlers.yielded])
+          handler(info);
+        return;
+      }
+      reconnect("socket closed");
     });
     attached.cdp.on("Runtime.executionContextsCleared", () => {
       if (state.kind === "up" && state.attached.cdp === attached.cdp)
@@ -3937,6 +4011,25 @@ function spawnFailure(cmd, cwd, error) {
     return `cannot run \`${cmd.join(" ")}\`: no such directory ${cwd}`;
   return `cannot run \`${cmd.join(" ")}\`: ${error instanceof Error ? error.message : String(error)}`;
 }
+async function readLines(stream, onLine) {
+  const decoder = new TextDecoder;
+  let text = "";
+  let pending = "";
+  for await (const chunk of stream) {
+    const piece = decoder.decode(chunk, { stream: true });
+    text += piece;
+    const lines = (pending + piece).split(/\r?\n/);
+    pending = lines.pop() ?? "";
+    for (const line of lines)
+      onLine(line);
+  }
+  const rest = decoder.decode();
+  text += rest;
+  pending += rest;
+  if (pending !== "")
+    onLine(pending);
+  return text;
+}
 var bunExec = async (cmd, opts = {}) => {
   try {
     const proc = Bun.spawn([...cmd], {
@@ -3948,11 +4041,9 @@ var bunExec = async (cmd, opts = {}) => {
       timeout: opts.timeoutMs,
       ...opts.signal !== undefined ? { signal: opts.signal } : {}
     });
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited
-    ]);
+    const { onLine } = opts;
+    const read = (stream) => onLine ? readLines(stream, onLine) : new Response(stream).text();
+    const [stdout, stderr, exitCode] = await Promise.all([read(proc.stdout), read(proc.stderr), proc.exited]);
     return { exitCode, stdout, stderr };
   } catch (error) {
     return { exitCode: 127, stdout: "", stderr: spawnFailure(cmd, opts.cwd, error) };
@@ -4186,6 +4277,8 @@ var frontmostDataSchema = z6.looseObject({
   pid: z6.number().optional(),
   frontmostPid: z6.number().optional()
 });
+var launchDataSchema = z6.looseObject({ pid: z6.number() });
+var terminateDataSchema = z6.looseObject({ terminated: z6.boolean() });
 var orientationDataSchema = z6.object({
   orientation: z6.enum([
     "portrait",
@@ -4207,7 +4300,9 @@ var opSchemas = {
   rebind: rebindDataSchema,
   alertButtons: alertButtonsDataSchema,
   frontmost: frontmostDataSchema,
-  orientation: orientationDataSchema
+  orientation: orientationDataSchema,
+  launch: launchDataSchema,
+  terminate: terminateDataSchema
 };
 function hasOpSchema(op) {
   return Object.hasOwn(opSchemas, op);
@@ -5855,6 +5950,6 @@ function onlyWasSeen() {
 
 // ../../packages/e2e/src/version.ts
 var WORKSPACE_VERSION = "0.0.0-workspace";
-var WARDEN_E2E_VERSION2 = "0.3.1";
+var WARDEN_E2E_VERSION2 = "0.4.0";
 
 export { E2eError2, noteSpanDetail, addSpanDetail, canObserve, canDetectAlerts, settleDetailOf, DEFAULT_SETTLE_QUIET_MS, DEFAULT_SETTLE_TIMEOUT_MS, settleByHash, snapshotHash, ok, err, swipeVector, screenRect, fieldValue, PINCH_MS, ROTATE_MS, PATH_MS, centreOf, pinchRadius, rotateRadius, requireGesture, assertScale, assertDegrees, isInteractiveRole, resolveRole, normalizeText, matchesText, indexSnapshot, testIdQuery, textQuery, roleQuery, selectorExpression, renderSnapshot, renderHeader, resolve, locateByTestIdViaReact, isLocator, Locator, pickOne, textOf, scrollUntilVisible, bunExec, execError, driverError, driverErr, logEventSchema, fatalEventSchema, responseSchema, mapWireError, encodeRequest, bunSpawn, stdioTransport, spawnSimd, connectSimd, isHidLost, ENV_NAMES, DEFAULT_ASSERTION_TIMEOUT_MS, readEnv, runStep, setDefaultHidRecovery, setDefaultNativeLog, setDefaultDriverFactory, hasDefaultDriverFactory, setDefaultFixtureFactory, hasDefaultFixtureFactory, attemptSession, getSession, parseBudgets, createDevicePerf, perfStartFor, spawnWarden, hash6, attemptDir, screenshotPath, specIdOf, realNativeLogDeps, captureNativeLog, callerFile, BUN_TIMEOUT_MARGIN_MS2, ownHook, currentScope, createScope, runInScope, hooksFor, resolveUse, registrationDefaults, markOnly, onlyWasSeen, WORKSPACE_VERSION, WARDEN_E2E_VERSION2 };

package/index.mjs

@@ -31,7 +31,7 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-8em9kgsk.mjs";
+} from "./chunk-3874jt2j.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.3.1",
+  "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.3.1"
+    "@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-8em9kgsk.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,
@@ -3348,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;
@@ -3359,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,
@@ -3426,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)
@@ -3463,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 {
@@ -3631,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,
@@ -3647,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))
@@ -3656,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),
@@ -4773,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));
@@ -4796,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>;

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

@@ -1,6 +1,7 @@
 import type { KeyName, Modifier, Point, Rect } from "../driver/driver.types";
 import { type Momentum, type SwipeDirection } from "./actions";
 import type { Observed, Runtime } from "./context";
+import { type FillVia } from "./field";
 import type { NodeEntry } from "./nodes";
 import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
 import { type LocatorExpression } from "./query";
@@ -39,6 +40,10 @@ export type TapOptions = ActionOptions & {
     /** gap between checks of `until`. Default 250 ms. Needs `until`. */
     pollMs?: number;
 };
+/** `fill` puts the text in by paste where the driver can (iOS) or types it: see `FillVia`. A retry always types. */
+export type FillOptions = ActionOptions & {
+    via?: FillVia;
+};
 export type LongPressOptions = ActionOptions & {
     durationMs?: number;
 };
@@ -137,12 +142,21 @@ export declare class Locator {
      * driver with a cheap hit-test first tries `aimFromKept`, which checks the kept snapshot with a hit-test instead.)
      * A fresh snapshot can also be of a screen still moving, so a match is taken only once its frame held still across
      * two looks with no input between them (Playwright's "stable"): the look a read or an `expect` kept, when there is
-     * one, costs nothing; with none, a look less than `STABLE_INPUT_GAP_MS` after an input is checked by one more. An
-     * element that never stops moving is taken after `MAX_STABILITY_LOOKS` extra looks.
+     * one, costs nothing; with none, a look less than `STABLE_INPUT_GAP_MS` after an input is checked by one more: a
+     * hit-test at the element where that is cheap (`stillByHitTest`), else a snapshot. An element that never stops
+     * moving is taken after `MAX_STABILITY_LOOKS` extra looks.
      */
     private actionable;
     /** One look of `actionable`: done, not yet, or `moving` (the match has not held still yet; look again at once). */
     private actionableLook;
+    /**
+     * The second look of the stable-frame rule as a hit-test, where that is cheap (`capabilities.cheapHitTest`, iOS:
+     * one element back instead of the whole tree): the element held still when the hit at its tap point is that element
+     * (`sameElement`, as in `aimFromKept`). Only for a look with nothing to compare against (the one that followed an
+     * input): a look that differs from the one before it is known to be moving. Never with system alerts answered: the
+     * app-scoped hit-test may not see an alert that came up since the look, the full second look does.
+     */
+    private stillByHitTest;
     /**
      * Whether `entry`'s frame, to 1 pt, is where the look before this one had this locator's one match. Without that look:
      * still unless an input ended less than `STABLE_INPUT_GAP_MS` before this one. No observation cache = still (no history).
@@ -173,7 +187,10 @@ export declare class Locator {
      */
     private tapOnce;
     /**
-     * Polls `plan.until` for `plan.windowMs`, one look at the screen per check. A locator is checked on the snapshot of
+     * Polls `plan.until` for `plan.windowMs`, one look at the screen per check, the first one right after the press
+     * (`driver.tap` returns once the HID press is over, ~85 ms, and an AX read queues behind the app's main thread, so
+     * that look usually already shows the screen the press made; measured: holding it back to `pollMs` saved no read
+     * and cost 250 ms a press). A locator is checked on the snapshot of
      * the poll itself, which is also compared with `pressedOn` (the hash of the screen the press aimed from): once the
      * screen changed the press landed, so it is never sent again (`landed`, even when `until` is late); a screen still
      * unchanged on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
@@ -188,10 +205,12 @@ export declare class Locator {
      * Replaces the content of a text field: focus with the caret at the end, empty it (select all and type over the selection when
      * the driver can, nothing for a field that is empty or shows a placeholder), type, then poll until the field holds
      * the text on consecutive reads (the accessibility value lags the keys). A mismatch is retried once with one Backspace
-     * per character and a retype (a field that refuses select-all). Secure fields cannot be read back, so they are not
+     * per character and a retype (a field that refuses select-all). `via` (default `"paste"`) is how the text goes in on
+     * the first attempt: a paste on iOS, typing where the driver cannot paste or when the pasteboard write fails; the
+     * retry always types, so a field that mangles a paste (a mask, a maxLength) still ends up right. Secure fields cannot be read back, so they are not
      * verified.
      */
-    fill(text: string, options?: ActionOptions): Promise<void>;
+    fill(text: string, options?: FillOptions): Promise<void>;
     /** Empties a text field (select all and one Backspace when the driver can), then checks it is empty (one more pass of counted Backspaces when it is not). */
     clear(options?: ActionOptions): Promise<void>;
     /** Types at the caret; the field is tapped (caret to the end) first unless it already has focus. */