@delacour/warden-e2e 0.13.0 → 0.15.0

package/preload.mjs

@@ -11,6 +11,7 @@ import {
   settleDetailOf,
   DEFAULT_SETTLE_QUIET_MS,
   DEFAULT_SETTLE_TIMEOUT_MS,
+  hashFallbackQuietMs,
   settleByHash,
   snapshotHash,
   ok,
@@ -29,13 +30,14 @@ import {
   isInteractiveRole,
   resolveRole,
   indexSnapshot,
+  keyboardVisible,
   testIdQuery,
   textQuery,
   roleQuery,
   selectorExpression,
   renderSnapshot,
   renderHeader,
-  locateByTestIdViaReact,
+  lookUpTestIdViaReact,
   isLocator,
   Locator,
   scrollUntilVisible,
@@ -44,6 +46,10 @@ import {
   execError,
   driverError,
   driverErr,
+  bridgeStallSchema,
+  toBridgeStall,
+  noteBridgeStall,
+  formatBridgeStall,
   logEventSchema,
   fatalEventSchema,
   responseSchema,
@@ -56,6 +62,10 @@ import {
   createSimdClient,
   spawnSimd,
   connectSimd,
+  KEYBOARD_MODES,
+  DEFAULT_KEYBOARD_MODE,
+  IME_STASH_ENABLED,
+  IME_STASH_DEFAULT,
   CAMERA_FACINGS,
   CONDITION_AREAS,
   resolveNetwork,
@@ -109,7 +119,7 @@ import {
   onlyWasSeen,
   WORKSPACE_VERSION,
   WARDEN_E2E_VERSION2
-} from "./chunk-tnr47n9c.mjs";
+} from "./chunk-e3cry5br.mjs";
 
 // ../../packages/e2e/src/preload.ts
 import { afterAll, setDefaultTimeout } from "bun:test";
@@ -1371,6 +1381,8 @@ function physicalConditionOps(device) {
     locale: () => refuse("locale"),
     a11y: () => refuse("a11y"),
     battery: () => refuse("battery"),
+    keyboard: () => refuse("keyboard"),
+    keyboardState: () => refuse("keyboardState"),
     memoryWarning: () => refuse("memoryWarning"),
     push: () => refuse("push"),
     camera: () => refuse("camera")
@@ -4074,6 +4086,75 @@ function batteryOp(c) {
     };
   };
 }
+var nullable = (value) => value.trim() === "null" ? "" : value.trim();
+async function readIme(c) {
+  const enabled = await c.shell(settingGetArgv("secure", "enabled_input_methods"));
+  const current = await c.shell(settingGetArgv("secure", "default_input_method"));
+  return { enabled: nullable(enabled.stdout), default: nullable(current.stdout) };
+}
+async function readImeStash(c) {
+  const enabled = await c.shell(settingGetArgv("global", IME_STASH_ENABLED));
+  const current = await c.shell(settingGetArgv("global", IME_STASH_DEFAULT));
+  const state = { enabled: nullable(enabled.stdout), default: nullable(current.stdout) };
+  return state.enabled === "" ? undefined : state;
+}
+async function readKeyboardMode(c) {
+  return (await readIme(c)).enabled === "" ? "hardware" : "software";
+}
+function imeVisibleIn(dump) {
+  return /\bisVisible=true\b/.test(dump);
+}
+async function readKeyboardVisible(c) {
+  const read = await c.shell(["dumpsys", "window", "InputMethod"]);
+  return read.ok && imeVisibleIn(read.stdout);
+}
+async function restoreImes(c) {
+  const stash = await readImeStash(c);
+  if (stash !== undefined) {
+    const steps = [
+      ["settings", "put", "secure", "enabled_input_methods", stash.enabled],
+      ...stash.default === "" ? [] : [["settings", "put", "secure", "default_input_method", stash.default]],
+      ["settings", "delete", "global", IME_STASH_ENABLED],
+      ["settings", "delete", "global", IME_STASH_DEFAULT]
+    ];
+    for (const argv of steps) {
+      const done = await c.must(argv);
+      if (!done.success)
+        return done;
+    }
+  }
+  return { success: true, data: { mode: "software" } };
+}
+async function hideImes(c, current) {
+  const listed = await c.shell(["ime", "list", "-s"]);
+  const ids = listed.stdout.split(`
+`).map((line) => line.trim()).filter((line) => line.includes("/"));
+  const steps = [
+    ["settings", "put", "global", IME_STASH_ENABLED, current.enabled],
+    ...current.default === "" ? [] : [["settings", "put", "global", IME_STASH_DEFAULT, current.default]],
+    ...ids.map((id) => ["ime", "disable", id])
+  ];
+  for (const argv of steps) {
+    const done = await c.must(argv);
+    if (!done.success)
+      return done;
+  }
+  if ((await readIme(c)).enabled !== "") {
+    return driverErr("E_IO", "an input method is still enabled after ime disable", { detail: { serial: c.serial } });
+  }
+  return { success: true, data: { mode: "hardware", previousIme: current } };
+}
+function keyboardOp(c) {
+  return async (mode) => {
+    if (mode === "software")
+      return restoreImes(c);
+    const current = await readIme(c);
+    if (current.enabled !== "")
+      return hideImes(c, current);
+    const previous = await readImeStash(c);
+    return { success: true, data: { mode, ...previous === undefined ? {} : { previousIme: previous } } };
+  };
+}
 function memoryWarningOp(c) {
   return async (opts) => {
     const app = c.packageOf(opts?.bundleId, "memoryWarning");
@@ -4148,6 +4229,12 @@ function createAndroidSettings(deps) {
     locale: localeOp(ctx),
     a11y: a11yOp(ctx),
     battery: batteryOp(ctx),
+    keyboard: keyboardOp(ctx),
+    keyboardMode: () => readKeyboardMode(ctx),
+    keyboardVisible: () => readKeyboardVisible(ctx),
+    async keyboardState() {
+      return { success: true, data: { mode: await readKeyboardMode(ctx), visible: await readKeyboardVisible(ctx) } };
+    },
     memoryWarning: memoryWarningOp(ctx),
     async push() {
       return driverErr("E_UNSUPPORTED", "push notifications through the shell are iOS only (`simctl push`); Android needs FCM");
@@ -5835,7 +5922,12 @@ function buildDriver(options, session, baseScreen, clock, execBinary, facts) {
     });
     return { success: true, data: { ...applied.data, condition: op } };
   };
-  const { talkback, ...settings } = createAndroidSettings({
+  const {
+    talkback,
+    keyboardMode: _mode,
+    keyboardVisible: _visible,
+    ...settings
+  } = createAndroidSettings({
     session,
     serial,
     ...options.appPackage ? { appPackage: options.appPackage } : {},
@@ -5953,6 +6045,11 @@ function buildDriver(options, session, baseScreen, clock, execBinary, facts) {
       ...options.cameraHost ?? createAndroidCameraHost({ serial, exec })
     }),
     ...facts.physical ? physicalConditionOps(`physical Android device ${serial}`) : {},
+    keyboardState: settings.keyboardState,
+    async dismissKeyboard() {
+      const pressed = await pressButton("back");
+      return pressed.success ? { success: true, data: { via: "back" } } : pressed;
+    },
     biometrics,
     app: createAppCommands({
       session,
@@ -6031,6 +6128,17 @@ function writeLaunchSettings(path, settings) {
   }
 }
 
+// ../../packages/e2e/src/driver/read-deadline.ts
+import { AsyncLocalStorage } from "async_hooks";
+var deadlines = new AsyncLocalStorage;
+function withReadDeadline(remaining, fn) {
+  return deadlines.run({ remaining }, fn);
+}
+function readDeadlineRemaining() {
+  const deadline = deadlines.getStore();
+  return deadline === undefined ? undefined : Math.max(0, deadline.remaining());
+}
+
 // ../../packages/e2e/src/driver/ios/inject.ts
 import { mkdirSync as mkdirSync7, readFileSync as readFileSync5, renameSync as renameSync6, rmSync as rmSync6, writeFileSync as writeFileSync6 } from "fs";
 import { dirname as dirname3, join as join10, resolve } from "path";
@@ -6051,12 +6159,17 @@ function encodeInjectState(state) {
     clockOffsetMs: Math.trunc(state.clockOffsetMs ?? 0),
     ...state.clockFrozenMs === undefined ? {} : { clockFrozenMs: Math.trunc(state.clockFrozenMs) },
     ...state.a11yRead ? { a11yRead: true } : {},
-    ...state.camera === undefined ? {} : { camera: state.camera }
+    ...state.camera === undefined ? {} : { camera: state.camera },
+    ...state.keyboard === undefined ? {} : { keyboard: state.keyboard },
+    ...state.dismissKeyboard ? { dismissKeyboard: true } : {}
   });
 }
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function parseKeyboard(value) {
+  return KEYBOARD_MODES.find((mode) => mode === value);
+}
 function parseFeed(value) {
   if (!isRecord3(value) || typeof value.path !== "string")
     return;
@@ -6084,7 +6197,8 @@ function parseInjectState(text) {
       clockOffsetMs: typeof data.clockOffsetMs === "number" ? data.clockOffsetMs : 0,
       ...typeof data.clockFrozenMs === "number" ? { clockFrozenMs: data.clockFrozenMs } : {},
       ...data.a11yRead === true ? { a11yRead: true } : {},
-      ..."camera" in data ? { camera: parseCamera(data.camera) } : {}
+      ..."camera" in data ? { camera: parseCamera(data.camera) } : {},
+      ...parseKeyboard(data.keyboard) ? { keyboard: parseKeyboard(data.keyboard) } : {}
     };
   } catch {
     return;
@@ -6118,11 +6232,12 @@ function injectLaunchEnv(input) {
     ...input.clockOffsetMs ? { WARDEN_CLOCK_OFFSET_MS: String(Math.trunc(input.clockOffsetMs)) } : {},
     ...input.clockFrozenMs === undefined ? {} : { WARDEN_CLOCK_FROZEN_MS: String(Math.trunc(input.clockFrozenMs)) },
     ...input.camera ? { WARDEN_CAMERA: "1" } : {},
+    ...input.keyboard ? { WARDEN_KEYBOARD: input.keyboard } : {},
     ...input.debug ? { WARDEN_INJECT_DEBUG: "1" } : {}
   };
 }
 function shouldInject(input) {
-  return input.networkActive || input.clockActive || input.cameraActive === true || input.requested;
+  return input.networkActive || input.clockActive || input.cameraActive === true || input.keyboardActive === true || input.requested;
 }
 function locateInjectDylib(input) {
   const tried = [];
@@ -6207,7 +6322,13 @@ function createInjectChannel(input) {
     current: readState,
     write(next) {
       fs.mkdir(dirname3(statePath));
-      const state = { ...next, seq: Math.max(readState().seq + 1, Math.trunc(now())) };
+      const previous = readState();
+      const keyboard = next.keyboard ?? previous.keyboard;
+      const state = {
+        ...next,
+        ...keyboard === undefined ? {} : { keyboard },
+        seq: Math.max(previous.seq + 1, Math.trunc(now()))
+      };
       fs.writeAtomic(statePath, encodeInjectState(state));
       return state;
     },
@@ -6224,9 +6345,14 @@ function createInjectChannel(input) {
       }
     },
     reset() {
+      const keyboard = readState().keyboard;
       fs.remove(ackPath);
       fs.remove(statePath);
       fs.remove(injectEventsPath(statePath));
+      if (keyboard !== undefined) {
+        fs.mkdir(dirname3(statePath));
+        fs.writeAtomic(statePath, encodeInjectState({ seq: 0, keyboard }));
+      }
     }
   };
 }
@@ -6787,8 +6913,14 @@ function defaultBuildCommand(platform, configuration, framework = "expo") {
   if (platform === "ios") {
     return `${IOS_NATIVE_PREPARE} && bunx expo run:ios ${configuration === "Release" ? "--configuration Release " : ""}${flags}`;
   }
-  return `bunx expo run:android ${configuration === "Release" ? "--variant release " : ""}${flags}`;
+  return androidGradleCommand(configuration, framework);
+}
+function androidGradleCommand(configuration, framework = "expo") {
+  const gradle = `cd android && ./gradlew app:assemble${configuration} -PreactNativeArchitectures=${ANDROID_HOST_ABI}`;
+  return framework === "react-native" ? gradle : `${ANDROID_NATIVE_PREPARE} && ${gradle}`;
 }
+var ANDROID_NATIVE_PREPARE = "{ [ -f android/gradlew ] || bunx expo prebuild --platform android --no-install; }";
+var ANDROID_HOST_ABI = '"$([ "$(uname -m)" = arm64 ] && echo arm64-v8a || echo x86_64)"';
 var DEFAULT_BUILD_COMMAND = {
   ios: defaultBuildCommand("ios", "Debug"),
   android: defaultBuildCommand("android", "Debug")
@@ -7365,6 +7497,63 @@ function createIosNativeAudit(o) {
   };
 }
 
+// ../../packages/e2e/src/driver/ios/ios-keyboard.ts
+var okVoid2 = { success: true, data: undefined };
+function createIosKeyboard(deps) {
+  const { channel } = deps;
+  let expectLoad = false;
+  const mode = () => channel.current().keyboard ?? DEFAULT_KEYBOARD_MODE;
+  return {
+    mode,
+    launchEnv() {
+      const dylib = deps.dylib();
+      if (!dylib.success)
+        return;
+      channel.reset();
+      channel.write({});
+      expectLoad = true;
+      return injectLaunchEnv({
+        dylib: dylib.data,
+        statePath: channel.statePath,
+        keyboard: mode(),
+        ...deps.debug ? { debug: true } : {}
+      });
+    },
+    launchMode: () => ({ WARDEN_KEYBOARD: mode() }),
+    async confirmLoaded() {
+      if (!expectLoad)
+        return okVoid2;
+      expectLoad = false;
+      if (await channel.acked(channel.current().seq, INJECT_LOAD_MS))
+        return okVoid2;
+      const error = driverError("E_INTERNAL", `the app did not load libwarden-inject.dylib within ${INJECT_LOAD_MS} ms: the keyboard mode would not reach it. Check the app is a simulator build, and run with WARDEN_E2E_DEBUG=1`, { detail: { statePath: channel.statePath } });
+      return { success: false, error };
+    },
+    async dismiss() {
+      if (!channel.attached())
+        return { success: true, data: { attached: false } };
+      const { seq: _seq, a11yRead: _read, ...rest } = channel.current();
+      const state = channel.write({ ...rest, dismissKeyboard: true });
+      if (await channel.acked(state.seq, INJECT_ACK_MS))
+        return { success: true, data: { attached: true } };
+      return driverErr("E_TIMEOUT", `the app did not acknowledge the keyboard dismissal within ${INJECT_ACK_MS} ms`, {
+        detail: { statePath: channel.statePath }
+      });
+    },
+    async keyboard(next) {
+      const { seq: _seq, a11yRead: _read, ...rest } = channel.current();
+      const state = channel.write({ ...rest, keyboard: next });
+      if (!channel.attached())
+        return { success: true, data: { mode: next, appliesOnLaunch: true } };
+      if (await channel.acked(state.seq, INJECT_ACK_MS))
+        return { success: true, data: { mode: next } };
+      return driverErr("E_TIMEOUT", `the app did not acknowledge the keyboard mode within ${INJECT_ACK_MS} ms`, {
+        detail: { statePath: channel.statePath }
+      });
+    }
+  };
+}
+
 // ../../packages/e2e/src/driver/ios/ios-session.ts
 var SHUTDOWN_TIMEOUT_MS = 500;
 function swappableClient(initial, o) {
@@ -7774,6 +7963,9 @@ function optionalFields(node) {
     fields.pid = node.pid;
   return fields;
 }
+function roleOf(node) {
+  return node.role === "other" && node.identifier === "inputView" ? "keyboard" : node.role;
+}
 function normalizeElements(wire, screen, prefix = "", depth = 0) {
   const flat = [];
   const elements = wire.map((node, index) => {
@@ -7781,7 +7973,7 @@ function normalizeElements(wire, screen, prefix = "", depth = 0) {
     const element = {
       ...optionalFields(node),
       id: node.id ?? path,
-      role: node.role,
+      role: roleOf(node),
       rawType: node.rawType,
       frame: node.frame,
       depth: node.depth ?? depth,
@@ -7819,6 +8011,8 @@ function toSnapshot(data, takenAt) {
     snapshot.modal = data.modal;
   if (data.fallback?.from === "axbridge")
     snapshot.fellBackFrom = "axbridge";
+  if (data.fallback?.stall)
+    snapshot.bridgeStall = toBridgeStall(data.fallback.stall);
   return snapshot;
 }
 
@@ -8407,6 +8601,14 @@ var REBIND_TIMEOUT_MS = 1e4;
 var COLD_BRIDGE_BUDGET_MS = 60000;
 var COLD_BRIDGE_FIRST_WAIT_MS = 2000;
 var COLD_BRIDGE_WAIT_MS = 5000;
+var BRIDGE_COLD_DEADLINE_MS = 12000;
+var AX_FALLBACK_MARGIN_MS = 8000;
+var COLD_READ_TIMEOUT_MS = BRIDGE_COLD_DEADLINE_MS + AX_FALLBACK_MARGIN_MS;
+function coldReadTimeoutMs(env = process.env) {
+  const raw = Number(env.WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS);
+  const deadline = Number.isFinite(raw) && raw > BRIDGE_COLD_DEADLINE_MS ? raw : BRIDGE_COLD_DEADLINE_MS;
+  return deadline + AX_FALLBACK_MARGIN_MS;
+}
 var GESTURE_MARGIN_MS = 5000;
 var FRONTMOST_TIMEOUT_MS = 3000;
 var LAUNCH_TIMEOUT_MS = 30000;
@@ -8444,7 +8646,7 @@ var SOCKET_RETRY_MS = 500;
 function params(values) {
   return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
-var okVoid2 = { success: true, data: undefined };
+var okVoid3 = { success: true, data: undefined };
 function fail2(error) {
   return { success: false, error };
 }
@@ -8480,6 +8682,23 @@ function noteSnapshotError(detail) {
     if (typeof value === "string")
       noteSpanDetail(to, value);
   }
+  const stall = bridgeStallSchema.safeParse(detail.stall);
+  if (stall.success)
+    noteBridgeStall(toBridgeStall(stall.data));
+}
+function noteFallback(fallback, log) {
+  const stall = fallback.stall && toBridgeStall(fallback.stall);
+  const why = stall ? ` (${formatBridgeStall(stall)})` : "";
+  log?.(`[ios] snapshot fell back ${fallback.from} -> ${fallback.to}: ${fallback.reason}${why}`);
+  noteSpanDetail("fallback", fallback.reason);
+  if (stall)
+    noteBridgeStall(stall);
+}
+function noteSnapshotTarget(target) {
+  if (!target)
+    return;
+  noteSpanDetail("targetPid", target.pid);
+  noteSpanDetail("targetSource", target.source);
 }
 function noteHelperHealth(health) {
   noteSpanDetail("bridge", health.ax.bridge);
@@ -8495,6 +8714,10 @@ function noteHelperHealth(health) {
     noteSpanDetail("coreSimulator", health.coreSimulatorVersion);
   if (health.frontmost)
     noteSpanDetail("frontmostUnresolvedAgoMs", health.frontmost.unresolvedAgoMs);
+  if (health.bridgeRecycles) {
+    noteSpanDetail("bridgeRecycles", health.bridgeRecycles.count);
+    noteSpanDetail("bridgeRecyclesExhausted", health.bridgeRecycles.exhausted);
+  }
 }
 function coldBridgeWait(error, attempt, spentMs, budgetMs) {
   if (!bridgeNotReady(error))
@@ -8538,8 +8761,26 @@ function healthDetail(d) {
     ...d.ax.error !== undefined ? { axError: d.ax.error } : {},
     ...d.socket ? { socket: d.socket } : {},
     ...d.xcode ? { xcode: d.xcode } : {},
-    ...d.state ? { state: d.state } : {}
-  };
+    ...d.state ? { state: d.state } : {},
+    ...d.axWedge ? { axWedge: toAxWedgeState(d.axWedge) } : {}
+  };
+}
+var AX_WEDGE_RECOVER_MS = 75000;
+function toAxWedgeState(d) {
+  const state = {
+    restarts: d.restarts,
+    maxRestarts: d.maxRestarts,
+    recovering: d.recovering,
+    ...d.checked !== undefined ? { checked: d.checked } : {}
+  };
+  const last = d.last;
+  if (last?.outcome === "restarted")
+    state.last = { outcome: "restarted", agoMs: last.agoMs, ...last.ms !== undefined ? { ms: last.ms } : {} };
+  else if (last?.outcome === "not-wedged")
+    state.last = { outcome: "not-wedged", agoMs: last.agoMs };
+  else if (last?.outcome === "failed")
+    state.last = { outcome: "failed", agoMs: last.agoMs, error: last.error };
+  return state;
 }
 
 class DriverFailure extends Error {
@@ -8562,14 +8803,15 @@ function decodeBase64(png) {
 function predatesOp(error) {
   return error.code === "E_UNSUPPORTED" || error.code === "E_BAD_REQUEST" && /unknown (input )?op/.test(error.message);
 }
-async function launchWithInjection(net, a11y, requested) {
+async function launchWithInjection(net, a11y, keyboard, requested) {
   const injected = net ? await net.launchEnv(requested ?? {}) : undefined;
   if (injected && !injected.success)
     return injected;
   const forA11y = injected?.data || !a11y ? undefined : await a11y.launchEnv(requested ?? {});
   if (forA11y && !forA11y.success)
     return forA11y;
-  const env = injected?.data ?? forA11y?.data;
+  const carried = injected?.data ?? forA11y?.data;
+  const env = keyboard ? carried ? { ...carried, ...keyboard.launchMode() } : keyboard.launchEnv() : carried;
   return { success: true, data: env ? { ...requested, env: { ...requested?.env, ...env } } : requested };
 }
 function createIosDriver(swap, simctl, opts) {
@@ -8584,6 +8826,7 @@ function createIosDriver(swap, simctl, opts) {
     relaunch: (bundleId) => driverRef ? driverRef.app.launch(bundleId, { relaunch: true, inject: true }) : noLeaseProxy()
   });
   const a11y = opts.a11y?.();
+  const kbd = opts.keyboard?.();
   const nativeAudit = opts.nativeAudit?.({ lastBundle: () => lastLaunched });
   const { client } = swap;
   let axFailures = 0;
@@ -8595,6 +8838,9 @@ function createIosDriver(swap, simctl, opts) {
   let settleAxFailures = 0;
   let rebindUnsupported = false;
   let bridgeProven = false;
+  let warmGeneration;
+  const coldTimeoutMs = coldReadTimeoutMs();
+  const readOpts = () => warmGeneration === swap.generation() ? {} : { minTimeoutMs: coldTimeoutMs };
   let gestureUnsupported = false;
   let appOpsOutdated = false;
   const capabilities = {
@@ -8647,7 +8893,7 @@ function createIosDriver(swap, simctl, opts) {
   const send = (op, p = {}, timeoutMs) => request(op, p, timeoutMs === undefined ? {} : { timeoutMs });
   const sendVoid = async (op, p = {}, timeoutMs) => {
     const result = await send(op, p, timeoutMs);
-    return result.success ? okVoid2 : result;
+    return result.success ? okVoid3 : result;
   };
   const gestureTimeout = (durationMs, base = 0) => (durationMs ?? 0) + base + GESTURE_MARGIN_MS;
   const helperOutdated = () => fail2(driverError("E_UNSUPPORTED", `this warden-simd predates the gesture op: restart the helper (warden ui close --udid ${udid}) or rebuild it (bun run --cwd packages/e2e native:build)`, { detail: { reason: "helper_outdated" } }));
@@ -8686,11 +8932,12 @@ function createIosDriver(swap, simctl, opts) {
     if (!viaHelper.success)
       return viaHelper;
     note(viaHelper.data);
-    return okVoid2;
+    return okVoid3;
   }
   let failureDiagnosed = false;
   const fetchSnapshot = async (o) => {
-    const result = await request("snapshot", params({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }));
+    const generation = swap.generation();
+    const result = await request("snapshot", params({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }), readOpts());
     if (!result.success) {
       noteSnapshotError(result.error.detail);
       if (!failureDiagnosed) {
@@ -8703,15 +8950,12 @@ function createIosDriver(swap, simctl, opts) {
     }
     failureDiagnosed = false;
     const { fallback, target } = result.data;
+    if (result.data.backend === "axbridge" && !fallback)
+      warmGeneration = generation;
     noteSpanDetail("backend", result.data.backend);
-    if (fallback) {
-      opts.log?.(`[ios] snapshot fell back ${fallback.from} -> ${fallback.to}: ${fallback.reason}`);
-      noteSpanDetail("fallback", fallback.reason);
-    }
-    if (target) {
-      noteSpanDetail("targetPid", target.pid);
-      noteSpanDetail("targetSource", target.source);
-    }
+    if (fallback)
+      noteFallback(fallback, opts.log);
+    noteSnapshotTarget(target);
     return { success: true, data: toSnapshot(result.data, now()) };
   };
   async function snapshotOnce(o) {
@@ -8738,10 +8982,11 @@ function createIosDriver(swap, simctl, opts) {
   async function snapshot(o) {
     if (bridgeProven)
       return snapshotOnce(o);
+    const budgetMs = opts.coldBridgeBudgetMs ?? COLD_BRIDGE_BUDGET_MS;
     const result = await retryColdSnapshot(() => snapshotOnce(o), {
       now,
       sleep,
-      budgetMs: opts.coldBridgeBudgetMs ?? COLD_BRIDGE_BUDGET_MS,
+      budgetMs: Math.min(budgetMs, readDeadlineRemaining() ?? budgetMs),
       ...opts.log ? { log: opts.log } : {}
     });
     if (result.success)
@@ -8774,7 +9019,7 @@ function createIosDriver(swap, simctl, opts) {
         if (!snap.success)
           throw new DriverFailure(snap.error);
         return snapshotHash(snap.data);
-      }, { quietMs: o.quietMs, timeoutMs: o.timeoutMs, now, sleep });
+      }, { quietMs: hashFallbackQuietMs(o.quietMs), timeoutMs: o.timeoutMs, now, sleep });
       noteSpanDetail("via", "hash");
       return { success: true, data: { ...outcome, via: "hash" } };
     } catch (error) {
@@ -8785,6 +9030,7 @@ function createIosDriver(swap, simctl, opts) {
   }
   async function settleAfterLaunch(bundleId) {
     lastLaunched = bundleId;
+    warmGeneration = undefined;
     launchedBundle = bundleId;
     if (await rebind(bundleId))
       launchedBundle = undefined;
@@ -8794,6 +9040,9 @@ function createIosDriver(swap, simctl, opts) {
     const a11yLoaded = await a11y?.confirmLoaded();
     if (a11yLoaded && !a11yLoaded.success)
       return a11yLoaded.error;
+    const kbdLoaded = await kbd?.confirmLoaded();
+    if (kbdLoaded && !kbdLoaded.success)
+      return kbdLoaded.error;
     return;
   }
   async function rebind(bundleId) {
@@ -8808,8 +9057,6 @@ function createIosDriver(swap, simctl, opts) {
       return false;
     }
     noteRebind(reply.data);
-    if (reply.data.bound)
-      bridgeProven = true;
     return reply.data.bound;
   }
   function noteSettleAxFailure(message) {
@@ -8882,7 +9129,7 @@ function createIosDriver(swap, simctl, opts) {
     return info;
   }
   async function readAlert(backend) {
-    const result = await request("alertButtons", params({ backend }));
+    const result = await request("alertButtons", params({ backend }), readOpts());
     if (!result.success)
       return result;
     return { success: true, data: result.data === null ? null : toAlertInfo(result.data) };
@@ -8895,6 +9142,18 @@ function createIosDriver(swap, simctl, opts) {
     const result = await request("frontmost", { bundleId }, { timeoutMs: FRONTMOST_TIMEOUT_MS });
     return result.success ? { success: true, data: result.data.frontmost } : result;
   }
+  async function axWedge(o) {
+    const recover = o?.recover === true;
+    const result = await request("axWedge", { recover }, { timeoutMs: recover ? AX_WEDGE_RECOVER_MS : 5000 });
+    if (result.success)
+      return { success: true, data: toAxWedgeState(result.data) };
+    if (predatesOp(result.error)) {
+      return driverErr("E_UNSUPPORTED", "this warden-simd predates the axWedge op", {
+        detail: { reason: "helper_outdated" }
+      });
+    }
+    return result;
+  }
   async function health() {
     const result = await request("health");
     if (!result.success)
@@ -8938,7 +9197,7 @@ function createIosDriver(swap, simctl, opts) {
     health,
     snapshot,
     async elementAtPoint(point, o) {
-      const result = await request("elementAtPoint", params({ x: point.x, y: point.y, reachability: o?.reachability }));
+      const result = await request("elementAtPoint", params({ x: point.x, y: point.y, reachability: o?.reachability }), readOpts());
       if (!result.success)
         return result;
       return {
@@ -8964,6 +9223,7 @@ function createIosDriver(swap, simctl, opts) {
     alert,
     alertOn,
     isFrontmost,
+    axWedge,
     readA11y: async (snapshot) => a11y ? a11y.read(snapshot) : driverErr("E_UNSUPPORTED", "this iOS driver was opened without the injected library channel"),
     a11yEvents: async (since) => a11y ? a11y.events(since) : driverErr("E_UNSUPPORTED", "this iOS driver was opened without the injected library channel"),
     auditNatively: async (options) => nativeAudit ? nativeAudit.audit(options ?? {}) : { issues: [], skipped: { source: "xcuitest", reason: "this iOS driver was opened without the runner" } },
@@ -8976,6 +9236,26 @@ function createIosDriver(swap, simctl, opts) {
     locale: (tag, o) => settings ? settings.locale(tag, o) : noSettings(),
     a11y: (op) => settings ? settings.a11y(op) : noSettings(),
     battery: (op) => settings ? settings.battery(op) : noSettings(),
+    keyboard: async (mode) => kbd ? kbd.keyboard(mode) : driverErr("E_UNSUPPORTED", "this iOS driver was opened without the injected library channel"),
+    async dismissKeyboard() {
+      const resigned = kbd ? await kbd.dismiss() : undefined;
+      if (resigned !== undefined && !resigned.success)
+        return resigned;
+      if (resigned?.data.attached)
+        return { success: true, data: { via: "resign" } };
+      opts.log?.("[ios] keyboard dismissed with Enter: the app was launched without libwarden-inject.dylib, so Return may submit the focused field");
+      const pressed = await sendVoid("key", params({ usage: KEY_USAGE.Enter }));
+      return pressed.success ? { success: true, data: { via: "key" } } : pressed;
+    },
+    async keyboardState() {
+      const taken = await snapshot();
+      if (!taken.success)
+        return taken;
+      return {
+        success: true,
+        data: { mode: kbd?.mode() ?? DEFAULT_KEYBOARD_MODE, visible: keyboardVisible(taken.data) }
+      };
+    },
     camera: async (op) => net ? net.camera(op) : driverErr("E_UNSUPPORTED", "the simulated camera on iOS needs a device lease for the injected dylib: run the spec with `warden e2e`, or `warden ui`; a bare `bun test` has no lease"),
     memoryWarning: (o) => settings ? settings.memoryWarning(o) : noSettings(),
     push: (payload, o) => settings ? settings.push(payload, o) : noSettings(),
@@ -8997,7 +9277,7 @@ function createIosDriver(swap, simctl, opts) {
     app: {
       launch: async (bundleId, plain) => {
         const requested = settings ? withStagedSettings(plain, settings.launchSettings()) : plain;
-        const withEnv = await launchWithInjection(net, a11y, requested);
+        const withEnv = await launchWithInjection(net, a11y, kbd, requested);
         if (!withEnv.success)
           return withEnv;
         const o = withEnv.data;
@@ -9133,6 +9413,7 @@ async function openIosDriver(o) {
       ...o.coldBridgeBudgetMs !== undefined ? { coldBridgeBudgetMs: o.coldBridgeBudgetMs } : {},
       ...network ? { network } : {},
       a11y: () => iosA11yFor(o, now, sleep),
+      keyboard: () => iosKeyboardFor(o, now, sleep),
       nativeAudit: (ctx) => nativeAuditFor(o, exec, log, ctx),
       settings: (ctx) => settingsFor(o, exec, ctx),
       ...o.clockRecorder ? { clockRecorder: o.clockRecorder } : {}
@@ -9172,6 +9453,28 @@ function iosNetworkFactory(o, simctl, now, sleep) {
     ...o.debug ? { debug: true } : {}
   });
 }
+function iosKeyboardFor(o, now, sleep) {
+  const wardenHome2 = o.wardenHome ?? wardenHome();
+  return createIosKeyboard({
+    channel: createInjectChannel({
+      statePath: injectStatePath2(wardenHome2, o.udid),
+      now,
+      sleep,
+      ...o.bundleId ? { bundleId: () => o.bundleId } : {},
+      ...o.injectFs ? { fs: o.injectFs } : {}
+    }),
+    dylib: () => locateInjectDylib({
+      env: { [INJECT_DYLIB_ENV]: process.env[INJECT_DYLIB_ENV], WARDEN_HELPER_DIR: o.env?.helperDir },
+      execPath: o.execPath ?? process.execPath,
+      importDir: o.importDir ?? import.meta.dir,
+      wardenHome: wardenHome2,
+      exists: o.exists ?? existsSync8,
+      realpath: o.realpath ?? realpathSync2,
+      ...o.version ? { version: o.version } : {}
+    }),
+    ...o.debug ? { debug: true } : {}
+  });
+}
 function iosA11yFor(o, now, sleep) {
   const wardenHome2 = o.wardenHome ?? wardenHome();
   return createIosA11y({
@@ -9415,7 +9718,7 @@ var SCREENSHOT_FALLBACK2 = new Set(["E_UNSUPPORTED", "E_IO", "E_INTERNAL"]);
 function params2(values) {
   return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
-var okVoid3 = { success: true, data: undefined };
+var okVoid4 = { success: true, data: undefined };
 function fail3(error) {
   return { success: false, error };
 }
@@ -9448,7 +9751,7 @@ function createIosDeviceDriver(client, devicectl, opts) {
   }
   const sendVoid = async (op, p = {}, timeoutMs) => {
     const result = await request(op, p, timeoutMs === undefined ? {} : { timeoutMs });
-    return result.success ? okVoid3 : result;
+    return result.success ? okVoid4 : result;
   };
   async function snapshot(o) {
     const result = await request("snapshot", params2({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }));
@@ -9466,7 +9769,12 @@ function createIosDeviceDriver(client, devicectl, opts) {
         if (!snap.success)
           throw new DriverFailure2(snap.error);
         return snapshotHash(snap.data);
-      }, { quietMs: o.quietMs ?? DEFAULT_QUIET_MS2, timeoutMs: o.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS3, now, sleep });
+      }, {
+        quietMs: hashFallbackQuietMs(o.quietMs ?? DEFAULT_QUIET_MS2),
+        timeoutMs: o.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS3,
+        now,
+        sleep
+      });
       noteSpanDetail("via", "hash");
       return { success: true, data: { ...outcome, via: "hash" } };
     } catch (error) {
@@ -9578,7 +9886,7 @@ function createIosDeviceDriver(client, devicectl, opts) {
       return installed;
     for (const bundleId of installed.data.bundleIds)
       owned.add(bundleId);
-    return okVoid3;
+    return okVoid4;
   }
   async function uninstall(bundleId) {
     const refused = guard(bundleId, "uninstall");
@@ -9617,6 +9925,11 @@ function createIosDeviceDriver(client, devicectl, opts) {
     gesture: async () => unsupported2("gesture", "the XCUITest runner takes taps, swipes and drags only"),
     biometrics: async () => unsupported2("biometrics", "Face ID / Touch ID cannot be simulated on a real sensor; use a simulator"),
     ...physicalConditionOps(`physical iPhone ${udid}`),
+    dismissKeyboard: async () => {
+      const pressed = await sendVoid("key", params2({ usage: KEY_USAGE.Enter }));
+      return pressed.success ? { success: true, data: { via: "key" } } : pressed;
+    },
+    keyboardState: async () => unsupported2("the keyboard mode", "the injected library runs in simulator apps only"),
     typeText: (text) => sendVoid("typeText", { text }, deviceTypeTextBudgetMs(text)),
     key: (key, modifiers) => sendVoid("key", params2({ usage: KEY_USAGE[key], modifiers: modifiers && [...modifiers] })),
     pressButton,
@@ -10339,6 +10652,10 @@ function createDevice({
     locale: conditions.locale,
     a11y: conditions.a11y,
     battery: conditions.battery,
+    keyboard: conditions.keyboard,
+    async keyboardVisible() {
+      return (await unwrap(() => driver.keyboardState(), "read the keyboard", signal())).visible;
+    },
     camera: conditions.camera,
     memoryWarning: conditions.memoryWarning,
     push: conditions.push,
@@ -10408,13 +10725,9 @@ function createDevice({
       await unwrap(() => driver.clipboard(text), "set clipboard", signal());
     },
     async hideKeyboard() {
-      const snapshot = await readSnapshot();
-      if (!snapshot.flat.some((element) => element.role === "keyboard"))
+      if (!await device.keyboardVisible())
         return;
-      if (driver.platform === "ios")
-        await unwrap(() => driver.key("Enter"), "hide keyboard", signal());
-      else
-        await unwrap(() => driver.pressButton("back"), "hide keyboard", signal());
+      await unwrap(() => driver.dismissKeyboard(), "hide keyboard", signal());
     },
     async screenshot(name) {
       const dir = session.attemptDir ?? join22(session.out, "adhoc");
@@ -10455,7 +10768,7 @@ function createDevice({
       if (native.error.code !== "E_UNSUPPORTED")
         throw toE2eError(native.error, "settle");
       const polled = await settleByHash(async () => snapshotHash(await readSnapshot()), {
-        quietMs,
+        quietMs: hashFallbackQuietMs(quietMs),
         timeoutMs,
         now: clock.now,
         sleep: clock.sleep
@@ -10534,13 +10847,11 @@ var EXCERPT_LINES = 40;
 var MAX_ALERT_ANSWERS = 3;
 var REACT_THROTTLE_MS = 450;
 var REACT_TIMEOUT_MS = 2000;
-var FIRST_READER_RETRY_MS = 5000;
 
 class Runtime {
   host;
   reactCache;
   indexed = new WeakMap;
-  firstReaderRetryAt = 0;
   constructor(host) {
     this.host = host;
   }
@@ -10580,7 +10891,7 @@ class Runtime {
       const result = canObserve(driver) ? await driver.observe({ reuse }) : await driver.snapshot();
       if (!result.success)
         return { ok: false, error: result.error };
-      const snapshot = await this.restoreDegraded(driver, result.data);
+      const snapshot = result.data;
       const observation = {
         ok: true,
         observed: { driver, snapshot, index: this.indexOf(snapshot) }
@@ -10594,16 +10905,6 @@ class Runtime {
       reuse = false;
     }
   }
-  async restoreDegraded(driver, snapshot) {
-    const first = snapshot.fellBackFrom;
-    if (first === undefined || this.clock.now() < this.firstReaderRetryAt)
-      return snapshot;
-    const again = await driver.snapshot({ backend: first });
-    if (again.success && again.data.backend === first)
-      return again.data;
-    this.firstReaderRetryAt = this.clock.now() + FIRST_READER_RETRY_MS;
-    return snapshot;
-  }
   earlierThan(driver, before, look) {
     const after = canObserve(driver) ? driver.previous?.() : undefined;
     const same = after !== undefined && after.generation === before.generation && after.snapshot === look;
@@ -10640,18 +10941,25 @@ class Runtime {
     throw driverFailure("snapshot", result.last ?? { code: "E_TIMEOUT", message: "no snapshot", retryable: true });
   }
   async reactMatches(testId, observed) {
+    const lookup = await this.reactLookup(testId, observed);
+    return lookup.answered ? lookup.matches : [];
+  }
+  hasReactTree() {
+    return this.host.devtools?.() !== undefined;
+  }
+  async reactLookup(testId, observed) {
     const facet = this.host.devtools?.();
     if (facet === undefined)
-      return [];
+      return { answered: false };
     const key = typeof testId === "string" ? `s:${testId}` : `r:${testId.toString()}`;
     const cached = this.reactCache;
     if (cached !== undefined && cached.key === key && this.clock.now() - cached.at < REACT_THROTTLE_MS) {
-      return cached.matches;
+      return cached.lookup;
     }
     const view = { platform: observed.snapshot.platform, screen: observed.snapshot.screen };
-    const matches = await locateByTestIdViaReact(facet, testId, view, { timeoutMs: REACT_TIMEOUT_MS });
-    this.reactCache = { key, at: this.clock.now(), matches };
-    return matches;
+    const lookup = await lookUpTestIdViaReact(facet, testId, view, { timeoutMs: REACT_TIMEOUT_MS });
+    this.reactCache = { key, at: this.clock.now(), lookup };
+    return lookup;
   }
   excerpt(snapshot) {
     const rendered = renderSnapshot(snapshot, { interactiveOnly: true, refs: new Map, maxLines: EXCERPT_LINES });
@@ -10660,13 +10968,15 @@ class Runtime {
   }
   async poll(step, timeoutMs, options = {}) {
     const signal = this.host.signal;
-    const result = await poll(step, {
+    const outer = readDeadlineRemaining();
+    const deadline = this.clock.now() + (outer === undefined ? timeoutMs : Math.min(timeoutMs, outer));
+    const result = await withReadDeadline(() => deadline - this.clock.now(), () => poll(step, {
       timeoutMs,
       ...options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs },
       ...signal === undefined ? {} : { signal },
       now: this.clock.now,
       sleep: this.clock.sleep
-    });
+    }));
     if (result.status === "aborted")
       throw abortError(signal);
     return result;
@@ -10839,6 +11149,8 @@ function traceDevice(device, span) {
     locale: (tag, options) => span("device.locale", () => device.locale(tag, options)),
     a11y: (op) => span("device.a11y", () => device.a11y(op)),
     battery: (op) => span("device.battery", () => device.battery(op)),
+    keyboard: (mode) => span("device.keyboard", () => device.keyboard(mode)),
+    keyboardVisible: () => span("device.keyboardVisible", () => device.keyboardVisible()),
     camera: {
       set: (path, options) => span("device.camera.set", () => camera.set(path, options)),
       clear: (facing) => span("device.camera.clear", () => camera.clear(facing)),