@delacour/warden-e2e 0.13.0 → 0.14.0

package/index.mjs

@@ -3,17 +3,19 @@ import {
   E2eError2,
   a11yTargetOf,
   canObserve,
+  isOnScreen,
   fieldValue,
   normalizeText,
   matchesText,
   renderSnapshot,
   renderHeader,
-  resolve,
   isLocator,
   pickOne,
   textOf,
   formatNativeTail,
   captureNativeLog,
+  bridgeStallFromSpan,
+  formatBridgeStall,
   isRecoverableLoss,
   parseDuration,
   runStep,
@@ -44,7 +46,7 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-tnr47n9c.mjs";
+} from "./chunk-zk3wxa70.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
@@ -148,6 +150,15 @@ ${screen}`, screen);
 var NEGATION_GRACE_MS = 1000;
 var NEGATION_QUIET_MS = 250;
 var NOT_FOUND = "element not found";
+var UNKNOWN = "unknown (degraded read)";
+function reactShown(matches, screen) {
+  const [only] = matches;
+  return only !== undefined && only.frame.width > 0 && only.frame.height > 0 && isOnScreen(only.tapPoint, screen);
+}
+function reactText(matches) {
+  const [only] = matches;
+  return only?.text === undefined ? undefined : normalizeText(only.text);
+}
 function missing() {
   return { kind: "missing" };
 }
@@ -205,7 +216,11 @@ class LocatorAssertions {
       call: "toBeVisible()",
       expected: "visible",
       strict: true,
-      judge: (entry) => entry === undefined ? judged(false, "not found") : judged(entry.visible, entry.visible ? "visible" : "hidden")
+      judge: (entry) => entry === undefined ? judged(false, "not found") : judged(entry.visible, entry.visible ? "visible" : "hidden"),
+      judgeReact: (matches, screen) => {
+        const shown = reactShown(matches, screen);
+        return judged(shown, shown ? "visible (React tree)" : "hidden (React tree)");
+      }
     }, options);
   }
   async toBeHidden(options = {}) {
@@ -214,7 +229,11 @@ class LocatorAssertions {
       call: "toBeHidden()",
       expected: "hidden",
       strict: true,
-      judge: (entry) => entry === undefined ? judged(true, "not found") : judged(!entry.visible, entry.visible ? "visible" : "hidden")
+      judge: (entry) => entry === undefined ? judged(true, "not found") : judged(!entry.visible, entry.visible ? "visible" : "hidden"),
+      judgeReact: (matches, screen) => {
+        const shown = reactShown(matches, screen);
+        return judged(!shown, shown ? "visible (React tree)" : "hidden (React tree)");
+      }
     }, options);
   }
   async toHaveText(expected, options = {}) {
@@ -229,6 +248,12 @@ class LocatorAssertions {
           return missing();
         const value = textOf(entry);
         return judged(matchesText(value, expected, { exact }), JSON.stringify(value));
+      },
+      judgeReact: (matches) => {
+        const value = reactText(matches);
+        if (value === undefined)
+          return;
+        return judged(matchesText(value, expected, { exact }), `${JSON.stringify(value)} (React tree)`);
       }
     }, options);
   }
@@ -244,6 +269,12 @@ class LocatorAssertions {
           return missing();
         const value = textOf(entry);
         return judged(containsText(value, expected, ignoreCase), JSON.stringify(value));
+      },
+      judgeReact: (matches) => {
+        const value = reactText(matches);
+        if (value === undefined)
+          return;
+        return judged(containsText(value, expected, ignoreCase), `${JSON.stringify(value)} (React tree)`);
       }
     }, options);
   }
@@ -379,7 +410,8 @@ class LocatorAssertions {
       call: `toHaveCount(${expected})`,
       expected: String(expected),
       strict: false,
-      judge: (_entry, count) => judged(count === expected, String(count))
+      judge: (_entry, count) => judged(count === expected, String(count)),
+      judgeReact: (matches) => judged(matches.length === expected, `${matches.length} (React tree)`)
     }, options);
   }
   async assert(spec, options) {
@@ -407,11 +439,12 @@ class LocatorAssertions {
         return { done: false, state: { received: "(screen unreadable)" } };
       }
       const { observed } = observation;
-      const entries = resolve(this.locator.expr, observed.index);
-      if (spec.strict && entries.length > 1)
-        pickOne(rt, this.locator.expr, entries, observed);
-      const { seen, context } = await judgementContext(spec, observed);
-      const judgement = spec.judge(entries[0], entries.length, context);
+      const look = await this.judgeLook(spec, observed);
+      if (look.kind === "unsettled") {
+        hold.broken();
+        return { done: false, state: look.last };
+      }
+      const { judgement, seen } = look;
       const verdict = await hold.next(judgement.kind === "judged" && judgement.matches !== negate, observed.driver);
       if (verdict === "pass")
         return { done: true, value: true };
@@ -426,8 +459,35 @@ class LocatorAssertions {
     }, timeoutMs);
     if (result.status === "done")
       return;
+    const degraded = result.last?.degraded;
+    if (degraded !== undefined)
+      throw this.locator.degradedFailure(degraded, timeoutMs, result.last?.snapshot);
     throw this.failure(spec, result.last);
   }
+  async judgeLook(spec, observed) {
+    const rt = this.locator.runtime;
+    const resolved = await this.locator.resolveIn(observed);
+    if (resolved.kind === "unknown") {
+      return { kind: "unsettled", last: { received: UNKNOWN, snapshot: observed.snapshot, degraded: resolved.read } };
+    }
+    if (resolved.kind === "react") {
+      const { matches } = resolved;
+      if (spec.strict && matches.length > 1 && spec.judgeReact !== undefined) {
+        const message = `${this.locator} matched ${matches.length} components in the React tree`;
+        throw new E2eError2("LOCATOR_AMBIGUOUS", message, rt.excerpt(observed.snapshot), matches.length);
+      }
+      const judgement = spec.judgeReact?.(matches, observed.snapshot.screen);
+      if (judgement === undefined) {
+        return { kind: "unsettled", last: { received: "only in the React tree", snapshot: observed.snapshot } };
+      }
+      return { kind: "judged", judgement, seen: observed.snapshot };
+    }
+    const { entries } = resolved;
+    if (spec.strict && entries.length > 1)
+      pickOne(rt, this.locator.expr, entries, observed);
+    const { seen, context } = await judgementContext(spec, observed);
+    return { kind: "judged", judgement: spec.judge(entries[0], entries.length, context), seen };
+  }
   failure(spec, last) {
     const { negate } = this.context;
     const lines = [
@@ -710,6 +770,36 @@ function missingRequirements(target, requires) {
 import { readdirSync } from "fs";
 import { join as join2 } from "path";
 
+// ../../packages/e2e/src/runner/bridge-evidence.ts
+function bridgeEvidence() {
+  let fallbacks = 0;
+  let first;
+  let last;
+  return {
+    observe(event) {
+      if (event.type !== "span" || event.detail === undefined)
+        return;
+      const detail = event.detail;
+      const stall = bridgeStallFromSpan(detail);
+      const reason = typeof detail.fallback === "string" ? detail.fallback : undefined;
+      const fellBack = reason !== undefined && detail.backend !== "axbridge";
+      if (stall === undefined && !fellBack)
+        return;
+      const read = {
+        ...fellBack ? { reason } : {},
+        ...event.ok || event.code === undefined ? {} : { code: event.code },
+        ...stall
+      };
+      fallbacks += 1;
+      first ??= read;
+      last = read;
+    },
+    summary() {
+      return first === undefined || last === undefined ? undefined : { fallbacks, first, last };
+    }
+  };
+}
+
 // ../../packages/e2e/src/runner/failure.ts
 import { mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
@@ -782,7 +872,9 @@ async function captureSnapshot(driver, dir, ms, capture) {
     }
     const rendered = renderSnapshot(result.data, { interactiveOnly: false, refs: new Map });
     const header = renderHeader({ snapshot: result.data, rendered, interactiveOnly: false });
-    writeFileSync(join(dir, SCREEN_AT_FAILURE), `${[header, ...rendered.lines].join(`
+    const fellBack = fallbackLine(result.data);
+    const lines = fellBack === undefined ? [header, ...rendered.lines] : [header, fellBack, ...rendered.lines];
+    writeFileSync(join(dir, SCREEN_AT_FAILURE), `${lines.join(`
 `)}
 `);
     capture.files.push(SCREEN_AT_FAILURE);
@@ -790,6 +882,12 @@ async function captureSnapshot(driver, dir, ms, capture) {
     capture.problems.push(`snapshot: ${message(cause)}`);
   }
 }
+function fallbackLine(snapshot) {
+  if (snapshot.fellBackFrom === undefined)
+    return;
+  const head = `# read on ${snapshot.backend}: ${snapshot.fellBackFrom}`;
+  return snapshot.bridgeStall === undefined ? `${head} did not answer` : `${head} stalled (${formatBridgeStall(snapshot.bridgeStall)})`;
+}
 async function captureDevtoolsArtifacts(facet, dir, timeoutMs = CAPTURE_TIMEOUT_MS, budget = unlimited) {
   const capture = { files: [], problems: [] };
   const ms = Math.min(timeoutMs, budget());
@@ -1059,8 +1157,10 @@ async function runAttemptOnce(session, spec) {
   };
   const files = new Set;
   let binding;
+  const bridge = bridgeEvidence();
   const trace = openTrace(join2(dir, "trace.jsonl"), (event) => {
     files.add("trace.jsonl");
+    bridge.observe(event);
     print(formatConsoleLine(event, { clock, short, depth: binding?.context.depth ?? 0 }));
   });
   const controller = new AbortController;
@@ -1093,7 +1193,7 @@ async function runAttemptOnce(session, spec) {
   session.leaveAttempt(ctx);
   trace.flush();
   outcome = failIf(outcome, cleanupErrors.length > 0, () => cleanupErrors[0]);
-  return concludeAttempt(session, spec, ctx, { startedAt, device }, outcome, print, clock);
+  return concludeAttempt(session, spec, ctx, { startedAt, device, bridge: bridge.summary() }, outcome, print, clock);
 }
 async function raceDeadline(controller, timeoutMs, run) {
   let deadlineHit = false;
@@ -1154,6 +1254,7 @@ function buildResult(spec, ctx, run, outcome) {
     ...spec.only ? { only: true } : {},
     ...outcome.failed ? { error: errorInfo(outcome.error) } : {},
     ...ctx.files.size > 0 ? { artifacts: { dir: ctx.dir, files: [...ctx.files].sort() } } : {},
+    ...run.bridge === undefined ? {} : { bridge: run.bridge },
     device: run.device
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "TypeScript e2e testing for React Native and Expo on iOS simulators and Android emulators, run by `warden e2e`: test, expect, screen, device, app",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@delacour/warden": "0.13.0"
+    "@delacour/warden": "0.14.0"
   },
   "dependencies": {
     "zod": "^4.4.3"

package/preload.mjs

@@ -11,6 +11,7 @@ import {
   settleDetailOf,
   DEFAULT_SETTLE_QUIET_MS,
   DEFAULT_SETTLE_TIMEOUT_MS,
+  hashFallbackQuietMs,
   settleByHash,
   snapshotHash,
   ok,
@@ -35,7 +36,7 @@ import {
   selectorExpression,
   renderSnapshot,
   renderHeader,
-  locateByTestIdViaReact,
+  lookUpTestIdViaReact,
   isLocator,
   Locator,
   scrollUntilVisible,
@@ -44,6 +45,10 @@ import {
   execError,
   driverError,
   driverErr,
+  bridgeStallSchema,
+  toBridgeStall,
+  noteBridgeStall,
+  formatBridgeStall,
   logEventSchema,
   fatalEventSchema,
   responseSchema,
@@ -109,7 +114,7 @@ import {
   onlyWasSeen,
   WORKSPACE_VERSION,
   WARDEN_E2E_VERSION2
-} from "./chunk-tnr47n9c.mjs";
+} from "./chunk-zk3wxa70.mjs";
 
 // ../../packages/e2e/src/preload.ts
 import { afterAll, setDefaultTimeout } from "bun:test";
@@ -7819,6 +7824,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 +8414,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;
@@ -8480,6 +8495,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 +8527,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))
@@ -8595,6 +8631,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 = {
@@ -8690,7 +8729,8 @@ function createIosDriver(swap, simctl, opts) {
   }
   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 +8743,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) {
@@ -8774,7 +8811,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 +8822,7 @@ function createIosDriver(swap, simctl, opts) {
   }
   async function settleAfterLaunch(bundleId) {
     lastLaunched = bundleId;
+    warmGeneration = undefined;
     launchedBundle = bundleId;
     if (await rebind(bundleId))
       launchedBundle = undefined;
@@ -8882,7 +8920,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) };
@@ -8938,7 +8976,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 {
@@ -9466,7 +9504,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) {
@@ -10455,7 +10498,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 +10577,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 +10621,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 +10635,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 +10671,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 });

package/types/e2e/src/driver/bridge-stall.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type SpanDetail } from "./span-detail";
+/**
+ * What one iOS `axbridge` fallback or stall looked like, as `warden-simd` reports it (`fallback.stall` on a snapshot,
+ * `detail.stall` on a failed read). Recorded in `trace.jsonl` (the `stall*` span fields), `results.jsonl` (`bridge`)
+ * and under the header of `screen-at-failure.txt`.
+ */
+export declare const bridgeStallSchema: z.ZodObject<{
+    stage: z.ZodString;
+    readMs: z.ZodOptional<z.ZodNumber>;
+    deadlineMs: z.ZodOptional<z.ZodNumber>;
+    guestAgeMs: z.ZodOptional<z.ZodNumber>;
+    cold: z.ZodBoolean;
+    cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+    probes: z.ZodNumber;
+    recycles: z.ZodOptional<z.ZodNumber>;
+    recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type BridgeStall = {
+    stage: string;
+    readMs?: number;
+    deadlineMs?: number;
+    guestAgeMs?: number;
+    cold: boolean;
+    cooldownRemainingMs?: number;
+    probes: number;
+    recycles?: number;
+    recyclesExhausted?: boolean;
+};
+/** Only the fields of the schema, so a newer helper's extra keys stay off the span and out of the results. */
+export declare function toBridgeStall(wire: z.infer<typeof bridgeStallSchema>): BridgeStall;
+/** Leaves the stall on the span timing the read (`stallStage`, `stallReadMs`, …). */
+export declare function noteBridgeStall(stall: BridgeStall): void;
+/** The stall a span recorded, or undefined when it has none. */
+export declare function bridgeStallFromSpan(detail: SpanDetail | undefined): BridgeStall | undefined;
+/** One line for a log or a report: `stage read · read 4012 ms of a 4000 ms deadline · warm · …`. */
+export declare function formatBridgeStall(stall: BridgeStall): string;

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

@@ -1,6 +1,7 @@
 import type { CameraCondition, ClockCondition, HostFault, LocationCondition, NetworkCondition, PermissionName, PermissionState, TextSize } from "../../../core/src/conditions/conditions.types";
 import type { AsyncResult } from "../../../types/src/result";
 import type { ScreenReaderState } from "../a11y/a11y.types";
+import type { BridgeStall } from "./bridge-stall";
 /**
  * The device driver contract every layer of warden-e2e builds on: the spec API (`screen`, `device`,
  * `app`), `warden ui`, specs and the devtools facet all talk to a `Driver`. Implementations:
@@ -136,9 +137,12 @@ export type Snapshot = {
     modal?: ModalInfo;
     /**
      * Set when `backend` answered because this reader failed or was skipped first (iOS: `axbridge` stalled, `ax` read in
-     * its place). The fallback reader can lack what the first one has, so a missing node on such a snapshot is not final.
+     * its place). The fallback reader can lack what the first one has, so a missing node on such a snapshot is not final:
+     * the iOS helper probes the first reader in the background, and a later read is back on it once it answers.
      */
     fellBackFrom?: SnapshotBackend;
+    /** iOS: what the bridge failure behind `fellBackFrom` looked like, when the helper reported it */
+    bridgeStall?: BridgeStall;
 };
 export type Orientation = "portrait" | "portraitUpsideDown" | "landscapeLeft" | "landscapeRight";
 export type HardwareButton = "home" | "back" | "lock" | "volumeUp" | "volumeDown" | "shake";

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

@@ -91,6 +91,16 @@ export type OpenIosDriverOptions = {
  * Once a read or a rebind has succeeded the normal per-call budgets apply.
  */
 export declare const COLD_BRIDGE_BUDGET_MS = 60000;
+/**
+ * warden-simd's deadline for the first `axbridge` read of a cold guest (helper start, a recycled guest, an app just
+ * launched): `BridgeDeadline.defaultColdReadMs`, or `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS`. On a 3-vCPU runner that
+ * first read takes 4-11 s; warm reads keep the 4 s deadline.
+ */
+export declare const BRIDGE_COLD_DEADLINE_MS = 12000;
+/** The request timeout of a read while the bridge is cold, so the client never gives up before the helper's deadline. */
+export declare const COLD_READ_TIMEOUT_MS: number;
+/** {@link COLD_READ_TIMEOUT_MS}, following a `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS` the helper also reads. */
+export declare function coldReadTimeoutMs(env?: Readonly<Record<string, string | undefined>>): number;
 /** USB HID keyboard-page usage ids for the keys `Driver.key` offers. */
 export declare const KEY_USAGE: Readonly<Record<KeyName, number>>;
 /** The fields of a failed snapshot's `detail` the helper sets (which reader, why, both readers' errors), on its span. */

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

@@ -21,6 +21,8 @@ export type SimdEventMap = {
 };
 export type RequestOptions = {
     timeoutMs?: number;
+    /** a floor for this request's timeout (a cold bridge read): raises the default or `timeoutMs`, never lowers it */
+    minTimeoutMs?: number;
 };
 export type SimdClient = {
     /** the handshake of the current helper process (refreshed after a respawn) */

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

@@ -192,6 +192,10 @@ export declare const healthDataSchema: z.ZodObject<{
         unresolvedAgoMs: z.ZodNumber;
         method: z.ZodString;
     }, z.core.$strip>>;
+    bridgeRecycles: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+        exhausted: z.ZodBoolean;
+    }, z.core.$strip>>;
     state: z.ZodOptional<z.ZodString>;
     uptimeMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
@@ -214,6 +218,17 @@ export declare const snapshotDataSchema: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         reason: z.ZodString;
+        stall: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodString;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodBoolean;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodNumber;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
     }, z.core.$strip>>;
     target: z.ZodOptional<z.ZodObject<{
         pid: z.ZodNumber;
@@ -362,6 +377,10 @@ export declare const opSchemas: {
             unresolvedAgoMs: z.ZodNumber;
             method: z.ZodString;
         }, z.core.$strip>>;
+        bridgeRecycles: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+            exhausted: z.ZodBoolean;
+        }, z.core.$strip>>;
         state: z.ZodOptional<z.ZodString>;
         uptimeMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>;
@@ -383,6 +402,17 @@ export declare const opSchemas: {
             from: z.ZodString;
             to: z.ZodString;
             reason: z.ZodString;
+            stall: z.ZodOptional<z.ZodObject<{
+                stage: z.ZodString;
+                readMs: z.ZodOptional<z.ZodNumber>;
+                deadlineMs: z.ZodOptional<z.ZodNumber>;
+                guestAgeMs: z.ZodOptional<z.ZodNumber>;
+                cold: z.ZodBoolean;
+                cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+                probes: z.ZodNumber;
+                recycles: z.ZodOptional<z.ZodNumber>;
+                recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>;
         }, z.core.$strip>>;
         target: z.ZodOptional<z.ZodObject<{
             pid: z.ZodNumber;