@delacour/warden-e2e 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,169 @@
+import type { Result } from "../../../types/src/result";
+import type { SelectedTarget } from "./inspector";
+import type { DevtoolsSession } from "./session";
+/** Why a devtools call failed. `devtools_unavailable` = no dev client to talk to (release build, no Metro, no target). */
+export type DevtoolsErrorCode = "devtools_unavailable" | "device_mismatch" | "cdp_closed" | "cdp_timeout" | "cdp_protocol" | "binding_unavailable" | "eval_failed" | "reload_failed" | "io_failed";
+export type DevtoolsError = {
+    code: DevtoolsErrorCode;
+    message: string;
+};
+export type DevtoolsResult<T> = Result<T, DevtoolsError>;
+/** The `Runtime.exceptionDetails` object of a failed `Runtime.evaluate`. */
+export type ExceptionDetails = {
+    text?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    url?: string;
+    exception?: {
+        type?: string;
+        subtype?: string;
+        className?: string;
+        description?: string;
+        value?: unknown;
+    };
+};
+/** Failure of `DevtoolsSession.evaluate`: a thrown JS exception carries `exceptionDetails`. */
+export type EvaluateError = {
+    message: string;
+    code?: DevtoolsErrorCode;
+    exceptionDetails?: ExceptionDetails;
+};
+/** The slice of `Response` the devtools code reads; the global `fetch` satisfies it. */
+export type FetchResponse = {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+};
+/** Injectable `fetch` (the global one is assignable). */
+export type Fetch = (input: string, init?: {
+    method?: string;
+    signal?: AbortSignal;
+}) => Promise<FetchResponse>;
+export type Sleep = (ms: number) => Promise<void>;
+export declare function devtoolsErr(code: DevtoolsErrorCode, message: string): {
+    success: false;
+    error: DevtoolsError;
+};
+/** One CDP event as the session saw it. `replay` = it arrived while the connect handshake was still running. */
+export type CdpTapEvent = {
+    method: string;
+    params: unknown;
+    /** 1 for the first socket, +1 for every reconnect */
+    connection: number;
+    replay: boolean;
+};
+export type CdpTap = (event: CdpTapEvent) => void;
+export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+/** 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) */
+    ts: number;
+    level: ConsoleLevel;
+    kind: "console" | "exception" | "note";
+    text: string;
+    /** top stack frame; `line`/`col` are 1-based */
+    source?: {
+        url: string;
+        line: number;
+        col: number;
+    };
+    /** each console argument rendered on its own (console messages only) */
+    args?: string[];
+};
+/** One finished `fetch` of the app (Metro's own traffic excluded). */
+export type NetworkEntry = {
+    /** host-assigned, increasing */
+    id: number;
+    /** request start, epoch ms */
+    ts: number;
+    method: string;
+    url: string;
+    /** 0 when the request failed before a response */
+    status: number;
+    durationMs: number;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody?: string;
+    responseBody?: string;
+    /** the body was cut at 64 KB */
+    responseBodyTruncated?: boolean;
+    error?: string;
+};
+export type NetworkQuery = {
+    last?: number;
+    id?: number;
+};
+export type TreeOptions = {
+    /** components returned, at most 5000 (default 5000) */
+    max?: number;
+    /** only this screen's subtree (a react-navigation / expo-router route name), whether or not it is the focused one */
+    screen?: string;
+    /** keep inactive screens and hidden subtrees, flagged `inactive` */
+    all?: boolean;
+    /** multiply measured rects by this: Android reports dp, the driver speaks px (iOS points are dp already) */
+    pixelRatio?: number;
+    /** give up after this long (default 5 s) */
+    timeoutMs?: number;
+};
+/** One React component of the app that carries a testID, a label, text or a screen. */
+export type TreeComponent = {
+    /** index in `components` (preorder) */
+    id: number;
+    name: string;
+    testID?: string;
+    /** accessibilityLabel / aria-label */
+    label?: string;
+    /** the strings rendered inside it, concatenated */
+    text?: string;
+    /** `id` of the enclosing component, null for a top-level one */
+    parent: number | null;
+    /** window coordinates; absent when the view could not be measured */
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** inside an inactive screen or hidden subtree (only with `all`) */
+    inactive?: true;
+};
+export type ReactTree = {
+    /** route name of the focused screen, when the app uses react-navigation or expo-router */
+    screen?: string;
+    components: TreeComponent[];
+    /** more components existed than `max` */
+    truncated: boolean;
+};
+/** Everything `device.devtools` (T6) and the failure capture (T3) use. */
+export type DevtoolsFacet = {
+    evaluate: (expression: string, options?: {
+        await?: boolean;
+        timeoutMs?: number;
+    }) => Promise<Result<unknown, EvaluateError>>;
+    reloadJs: () => Promise<DevtoolsResult<{
+        method: "expo" | "devsettings" | "http";
+    }>>;
+    console: {
+        lines: () => ConsoleLine[];
+        clear: () => void;
+        mark: (label: string) => void;
+    };
+    network: {
+        /** drains the page first, so it is current */
+        entries: (query?: NetworkQuery) => Promise<NetworkEntry[]>;
+        /** also discards what the page still holds, so it is a clean cut */
+        clear: () => Promise<void>;
+    };
+    /** The app's React components with rects (see `tree.script.ts`); `devtools_unavailable` when the app has no DevTools hook. */
+    tree: (options?: TreeOptions) => Promise<DevtoolsResult<ReactTree>>;
+    /** the page currently attached (changes after a reconnect) */
+    readonly target: SelectedTarget;
+    /** `reconnected` (new target attached) and `lost` (gave up reconnecting) */
+    on: DevtoolsSession["on"];
+    /** Writes `console.jsonl` and `network.jsonl` into `dir` (created); resolves with the two paths. */
+    attachArtifacts: (dir: string) => Promise<DevtoolsResult<{
+        console: string;
+        network: string;
+    }>>;
+    close: () => void;
+};

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

@@ -0,0 +1,28 @@
+import { type ConsoleLine, type DevtoolsFacet, type DevtoolsResult, type Fetch, type NetworkEntry, type Sleep } from "./devtools.types";
+import { type DevtoolsDevice } from "./session";
+export type OpenDevtoolsFacetOptions = {
+    /** the spec env: `metroUrl` is `WARDEN_METRO_URL`; absent = a release build, so `devtools_unavailable` */
+    env: {
+        metroUrl?: string;
+    };
+    device: DevtoolsDevice;
+    fetch: Fetch;
+    WebSocket?: typeof WebSocket;
+    log?: (line: string) => void;
+    sleep?: Sleep;
+    timeoutMs?: number;
+    /** keep request/response text in network entries (default false) */
+    includeBodies?: boolean;
+    pollMs?: number;
+    consoleRing?: number;
+    networkRing?: number;
+    /** called with each console line / network entry as it is recorded (the collector's files) */
+    consoleSink?: (line: ConsoleLine) => void;
+    networkSink?: (entry: NetworkEntry) => void;
+};
+/**
+ * Attach to the running dev client and start capturing its console and `fetch` traffic. This is what
+ * `device.devtools` and the failure capture use. Console capture starts before the socket opens so the
+ * runtime's replay of buffered messages is seen (and de-duplicated on later reconnects).
+ */
+export declare function openDevtoolsFacet(o: OpenDevtoolsFacetOptions): Promise<DevtoolsResult<DevtoolsFacet>>;

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { type DevtoolsResult, type Fetch } from "./devtools.types";
+/** One entry of Metro's `/json/list` (`/json`). */
+export declare const inspectorTargetSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    vm: z.ZodOptional<z.ZodString>;
+    deviceName: z.ZodOptional<z.ZodString>;
+    appId: z.ZodOptional<z.ZodString>;
+    webSocketDebuggerUrl: z.ZodString;
+    reactNative: z.ZodOptional<z.ZodObject<{
+        logicalDeviceId: z.ZodOptional<z.ZodString>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            prefersFuseboxFrontend: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type InspectorTarget = z.infer<typeof inspectorTargetSchema>;
+/** Which target a caller wants; every field narrows, none is required. */
+export type TargetQuery = {
+    deviceName?: string;
+    logicalDeviceId?: string;
+    appId?: string;
+};
+export type SelectedTarget = {
+    /** Metro's inspector socket, host and port rewritten to the Metro URL */
+    wsUrl: string;
+    deviceName: string;
+    appId: string | undefined;
+    /** persist this to re-pin the same device after an app restart */
+    logicalDeviceId: string | undefined;
+    /** the C++ (Fusebox) connection, as opposed to the legacy bridge */
+    fusebox: boolean;
+    id: string;
+    title: string | undefined;
+};
+/**
+ * Metro's debuggable pages. `/status` must say `packager-status:running` (something else on the port is
+ * not Metro), then `/json/list` (`/json` on older Metro). Decoy `vm` entries are dropped.
+ */
+export declare function listTargets(metroUrl: string, fetch: Fetch): Promise<DevtoolsResult<InspectorTarget[]>>;
+/**
+ * Pick the page to debug: the pinned `logicalDeviceId`, else `deviceName`; then `appId`; then Fusebox over the
+ * legacy `React Native Bridge` page over anything, newest page id first. A pin or name that matches nothing is
+ * `device_mismatch` when Metro serves several devices (never attach to the wrong one), and ignored when it serves one.
+ */
+export declare function selectTarget(targets: readonly InspectorTarget[], query: TargetQuery, metroUrl: string): DevtoolsResult<SelectedTarget>;

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

@@ -0,0 +1,4 @@
+/** Replace `path` with one JSON object per line (parent directories created). */
+export declare function writeJsonl(path: string, rows: readonly unknown[]): Promise<void>;
+/** Append rows to `path`, creating it (and its directories) when missing. */
+export declare function appendJsonl(path: string, rows: readonly unknown[]): Promise<void>;

package/types/e2e/src/devtools/native-log.d.ts

@@ -0,0 +1,50 @@
+import type { Exec } from "../../../core/src/exec";
+export declare const NATIVE_LOG = "native.log";
+/** The app a failing attempt ran: `native.log` and crash reports are read for it only. */
+export type NativeTarget = {
+    platform: "ios";
+    udid: string;
+    bundleId: string;
+} | {
+    platform: "android";
+    serial: string;
+    pkg: string;
+};
+export type CrashReport = {
+    name: string;
+    mtimeMs: number;
+};
+/** Filesystem seam: where crash reports are read from and `native.log` goes. */
+export type NativeFs = {
+    listReports(dir: string): CrashReport[];
+    copy(from: string, to: string): void;
+    write(path: string, text: string): void;
+};
+export type NativeLogDeps = {
+    exec: Exec;
+    /** path of the `adb` binary */
+    adb: string;
+    fs: NativeFs;
+    /** `~/Library/Logs/DiagnosticReports` */
+    reportsDir: string;
+};
+export type NativeLogWindow = {
+    /** the attempt's directory; files are written into it */
+    dir: string;
+    /** when the attempt started (ms since epoch) */
+    sinceMs: number;
+    nowMs: number;
+    timeoutMs?: number;
+};
+export type NativeCapture = {
+    files: string[];
+    problems: string[];
+};
+export declare function realNativeFs(): NativeFs;
+export declare function realNativeLogDeps(exec: Exec, adb: string): NativeLogDeps;
+/**
+ * `native.log` (and iOS `.ips` crash reports) for a failed attempt, read after the fact: iOS
+ * `simctl spawn log show` for the app's process over the attempt's window, Android `logcat -d` for its pid
+ * plus the crash buffer. Reading afterwards needs no stream to start, stop or leak. Never throws.
+ */
+export declare function captureNativeLog(target: NativeTarget, deps: NativeLogDeps, win: NativeLogWindow): Promise<NativeCapture>;

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

@@ -0,0 +1,33 @@
+import type { DevtoolsResult, NetworkEntry, NetworkQuery, Sleep } from "./devtools.types";
+import type { DevtoolsSession } from "./session";
+export type NetworkOptions = {
+    /** entries kept, in the page and on the host (default 2000) */
+    ring?: number;
+    /** Metro's URL: requests to it (and its loopback aliases on the same port) are not recorded */
+    metroUrl?: string;
+    /** record request text and response text up to 64 KB (default false) */
+    includeBodies?: boolean;
+    /** how often the page is drained (default 500 ms) */
+    pollMs?: number;
+    /** injectable for tests; defaults to a timer */
+    sleep?: Sleep;
+    /** called with each new entry once */
+    sink?: (entry: NetworkEntry) => void;
+};
+export type NetworkCapture = {
+    /** Drains the page, then answers from the buffer: all, the `last` n, or the one with `id`. */
+    entries: (query?: NetworkQuery) => Promise<NetworkEntry[]>;
+    /** Drops the buffer and whatever the page still holds. Ids keep counting. */
+    clear: () => Promise<void>;
+    writeJsonl: (path: string) => Promise<void>;
+    /** stops polling (the page wrapper stays; it is harmless) */
+    stop: () => void;
+};
+/** Every URL prefix that is the same Metro: its origin plus the loopback aliases of a simulator and an emulator. */
+export declare function metroSkipPrefixes(metroUrl: string): string[];
+/**
+ * Record the app's `fetch` calls: patch `fetch` inside the page once, then drain its ring on a timer and
+ * whenever a caller asks. A new JS context (reload) loses the wrapper, so it is re-installed on reconnect and
+ * whenever a drain finds it missing; requests made before that are lost.
+ */
+export declare function attachNetwork(session: DevtoolsSession, options?: NetworkOptions): Promise<DevtoolsResult<NetworkCapture>>;

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

@@ -0,0 +1,24 @@
+/**
+ * The page side of network capture: a `fetch` wrapper that records finished requests into an in-page ring,
+ * drained by `__warden_net_drain()`.
+ *
+ * This is source text evaluated inside Hermes by `Runtime.evaluate`, which does not transpile it, so it stays
+ * plain ES2015 on purpose: `function`, `var`, promises, no `async`/`await`, arrows, `?.` or `??`.
+ * `XMLHttpRequest` is not patched: RN's `fetch` is built on it, so patching both would count every request twice.
+ *
+ * Use as `(NETWORK_SCRIPT)(config, globalObject)`; see {@link networkInstallExpression}.
+ */
+export declare const NETWORK_SCRIPT = "function (cfg, g) {\n  if (g.__warden_net_patched) return \"already\";\n  if (typeof g.fetch !== \"function\") return \"no fetch\";\n  g.__warden_net_patched = true;\n  var original = g.fetch;\n  var log = [];\n  var maxBody = cfg.maxBody || 65536;\n  var textual = /json|text|xml|javascript|x-www-form-urlencoded|graphql/i;\n\n  function skipped(url) {\n    for (var i = 0; i < cfg.skipPrefixes.length; i++) {\n      var prefix = cfg.skipPrefixes[i];\n      if (url.indexOf(prefix) === 0 && \"/?#\".indexOf(url.charAt(prefix.length) || \"/\") !== -1) return true;\n    }\n    return false;\n  }\n\n  function headersToObject(h) {\n    var out = {};\n    if (!h) return out;\n    if (Array.isArray(h)) {\n      for (var i = 0; i < h.length; i++) out[String(h[i][0]).toLowerCase()] = String(h[i][1]);\n    } else if (typeof h.forEach === \"function\") {\n      h.forEach(function (value, key) { out[String(key).toLowerCase()] = String(value); });\n    } else {\n      for (var k in h) if (Object.prototype.hasOwnProperty.call(h, k)) out[k.toLowerCase()] = String(h[k]);\n    }\n    return out;\n  }\n\n  function requestBodyText(body) {\n    if (typeof body === \"string\") return body.length > maxBody ? body.slice(0, maxBody) : body;\n    if (body && typeof body.toString === \"function\" && body.constructor && body.constructor.name === \"URLSearchParams\") {\n      return body.toString();\n    }\n    return undefined;\n  }\n\n  function push(entry) {\n    log.push(entry);\n    if (log.length > cfg.ring) log.shift();\n  }\n\n  g.__warden_net_drain = function () {\n    var out = log;\n    log = [];\n    return JSON.stringify(out);\n  };\n\n  g.fetch = function (input, init) {\n    var self = this;\n    var args = arguments;\n    var url = typeof input === \"string\" ? input : (input && input.url) || String(input);\n    if (skipped(url)) return original.apply(self, args);\n\n    var started = Date.now();\n    var entry = {\n      ts: started,\n      method: String((init && init.method) || (input && input.method) || \"GET\").toUpperCase(),\n      url: url,\n      status: 0,\n      durationMs: 0,\n      requestHeaders: headersToObject((init && init.headers) || (input && input.headers)),\n      responseHeaders: {}\n    };\n    if (cfg.includeBodies && init && init.body !== undefined && init.body !== null) {\n      var sent = requestBodyText(init.body);\n      if (sent !== undefined) entry.requestBody = sent;\n    }\n\n    return original.apply(self, args).then(function (res) {\n      entry.status = res.status;\n      entry.durationMs = Date.now() - started;\n      entry.responseHeaders = headersToObject(res.headers);\n      var type = entry.responseHeaders[\"content-type\"] || \"\";\n      if (!cfg.includeBodies || !textual.test(type)) {\n        push(entry);\n        return res;\n      }\n      try {\n        res.clone().text().then(function (text) {\n          if (text.length > maxBody) {\n            entry.responseBody = text.slice(0, maxBody);\n            entry.responseBodyTruncated = true;\n          } else {\n            entry.responseBody = text;\n          }\n          push(entry);\n        }, function () { push(entry); });\n      } catch (e) {\n        push(entry);\n      }\n      return res;\n    }, function (error) {\n      entry.durationMs = Date.now() - started;\n      entry.error = error && error.message ? error.message : String(error);\n      push(entry);\n      throw error;\n    });\n  };\n  return \"patched\";\n}";
+export type NetworkScriptConfig = {
+    /** page-side ring size */
+    ring: number;
+    includeBodies: boolean;
+    /** URLs starting with any of these are not recorded (Metro) */
+    skipPrefixes: string[];
+    /** body text cap in characters (default 64 KB) */
+    maxBody?: number;
+};
+/** The expression to `Runtime.evaluate`: installs the wrapper once and answers `patched` / `already` / `no fetch`. */
+export declare function networkInstallExpression(config: NetworkScriptConfig): string;
+/** Reads the page's ring and empties it; `null` when the wrapper is not installed (fresh JS context). */
+export declare const NETWORK_DRAIN_EXPRESSION = "typeof __warden_net_drain === \"function\" ? __warden_net_drain() : null";

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

@@ -0,0 +1,82 @@
+import { type Result } from "../../../types/src/result";
+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, … }))`. */
+export declare const WARDEN_BINDING = "__warden_cb";
+export type DevtoolsDevice = {
+    /** the simulator's name as the app reports it */
+    deviceName?: string;
+    /** pin this device on a Metro shared by several (persist `session.target.logicalDeviceId`) */
+    logicalDeviceId?: string;
+    appId?: string;
+};
+export type ConnectDevtoolsOptions = {
+    /** `undefined` = no Metro: a release build, so `devtools_unavailable` */
+    metroUrl: string | undefined;
+    device: DevtoolsDevice;
+    fetch: Fetch;
+    WebSocket?: typeof WebSocket;
+    log?: (line: string) => void;
+    /** injectable for tests; defaults to a timer */
+    sleep?: Sleep;
+    /** per-request and connect timeout (default 10 s) */
+    timeoutMs?: number;
+    /** first pause between reconnect attempts (default 200 ms; grows to `maxReconnectBackoffMs` after 10 attempts) */
+    reconnectBackoffMs?: number;
+    /** longest pause between reconnect attempts (default 1 s) */
+    maxReconnectBackoffMs?: number;
+    /** reconnect attempts before giving up (default: no cap, `reconnectBudgetMs` decides) */
+    maxReconnectAttempts?: number;
+    /** how long one reconnect keeps trying before it emits `lost` (default 30 s) */
+    reconnectBudgetMs?: number;
+    /** injectable for tests; defaults to `Date.now` (with the time slept, measures `reconnectBudgetMs`) */
+    now?: () => number;
+    /** Called for every CDP event from the moment each socket opens, handshake included (so replays are seen). */
+    taps?: readonly CdpTap[];
+    /** how long `reloadJs` waits for the app to start tearing its JS context down (default 5 s) */
+    reloadWaitMs?: number;
+};
+export type DevtoolsSession = {
+    /** `Runtime.evaluate` by value. A thrown JS error fails with `exceptionDetails`. Waits out a reconnect. */
+    evaluate: (expression: string, options?: {
+        await?: boolean;
+        timeoutMs?: number;
+    }) => Promise<Result<unknown, EvaluateError>>;
+    /**
+     * Reloads this device's JS: `expo.reloadAppAsync()` evaluated in the app, else `DevSettings.reload()`, else (only
+     * when the app has neither) `POST <metro>/reload`, which reloads every device on that Metro. Never `Page.reload`:
+     * RN handles it inside the inspector dispatch on the main thread and a bridgeless host freezes. Fails with
+     * `reload_failed` when the JS context did not restart in time; resolves once the app has reconnected.
+     */
+    reloadJs: () => Promise<DevtoolsResult<{
+        method: ReloadMethod;
+    }>>;
+    /** the page currently attached (changes after a reconnect) */
+    readonly target: SelectedTarget;
+    /** false on legacy Hermes: `evaluateWithBinding` is refused */
+    readonly bindingAvailable: boolean;
+    /** raw CDP call on the current socket (waits out a reconnect) */
+    send: (method: string, params?: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+    }) => Promise<DevtoolsResult<unknown>>;
+    /** CDP event subscription that survives reconnects */
+    onCdp: (method: string, handler: (params: unknown) => void) => () => void;
+    /** 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) */
+    on: <E extends keyof SessionEvents>(event: E, handler: (arg: SessionEvents[E]) => void) => () => void;
+    close: () => void;
+};
+export type ReloadMethod = "expo" | "devsettings" | "http";
+export type SessionEvents = {
+    reconnected: SelectedTarget;
+    lost: DevtoolsError;
+};
+/**
+ * Attach to the app's Hermes runtime through Metro's inspector proxy. Connect sequence (same as Chrome's Fusebox
+ * frontend): `FuseboxClient.setClientMetadata`, `ReactNativeApplication.enable`, `Runtime.enable`,
+ * `Runtime.runIfWaitingForDebugger`, `Runtime.addBinding`. The session re-attaches on socket close and on
+ * `Runtime.executionContextsCleared` (JS reload), re-selecting the target because a reload gets a new page id.
+ */
+export declare function connectDevtools(o: ConnectDevtoolsOptions): Promise<DevtoolsResult<DevtoolsSession>>;

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

@@ -0,0 +1,23 @@
+import { type DevtoolsResult, type ReactTree, type Sleep, type TreeOptions } from "./devtools.types";
+import { type DevtoolsSession } from "./session";
+/** What `fetchTree` needs of a session. */
+export type TreeSession = Pick<DevtoolsSession, "evaluate" | "evaluateWithBinding" | "bindingAvailable">;
+export type FetchTreeDeps = {
+    /** injectable for tests; defaults to a timer */
+    sleep?: Sleep;
+    now?: () => number;
+};
+/**
+ * The app's React components (testID, label, text, screen) with window rects, read through the DevTools hook.
+ * The page script answers through the CDP binding when the runtime has one, else the host polls a page global.
+ * `pixelRatio` multiplies rects (Android reports dp, the driver speaks px).
+ */
+export declare function fetchTree(session: TreeSession, options?: TreeOptions, deps?: FetchTreeDeps): Promise<DevtoolsResult<ReactTree>>;
+export type FormatTreeOptions = {
+    /** include unmeasured and inactive components (inactive ones are marked) */
+    all?: boolean;
+    /** lines at most; the rest is summarised in a last line */
+    max?: number;
+};
+/** One line per component, indented by nesting: `View testID=save "Save changes" (20,700 350×48)`. */
+export declare function formatTree(tree: ReactTree, options?: FormatTreeOptions): string[];

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

@@ -0,0 +1,33 @@
+/**
+ * Page-side script that reads the app's React component tree through the React DevTools global hook and reports
+ * the components a test can address (testID, accessibility label, text, screens) together with their window rects.
+ *
+ * Runs inside Hermes untranspiled, so it is plain ES2015: no arrow functions, optional chaining, nullish
+ * coalescing or async functions, and no backticks or interpolation (it lives in a template literal here).
+ * Used as `(TREE_SCRIPT)(config, globalObject)`; it answers "started" at once and delivers the result later:
+ * through the CDP binding `config.binding` when the page has one, else as a JSON string in
+ * `globalObject.__warden_tree_results[requestId]` for the host to poll and delete.
+ *
+ * Inactive-screen heuristic (a subtree is skipped unless `all`, then it is kept and flagged `inactive`):
+ * - props `activityState === 0` (react-native-screens), `isPageFocused === false` (pager views), `freeze === true`
+ *   (react-freeze, Suspense-style freezing), `aria-hidden === true`, `accessibilityElementsHidden === true`,
+ *   `importantForAccessibility === "no-hide-descendants"`, or a style whose last `display` is `"none"`;
+ * - a fiber with both `route` and `navigation` props (a react-navigation / expo-router screen) whose
+ *   `navigation.isFocused()` is false. `isFocused` accounts for parent navigators, so a focused tab inside an
+ *   unfocused stack screen is unfocused too. When it throws the screen is treated as unknown, not as unfocused.
+ * The reported `screen` is `route.name` of the deepest focused screen. `activityState === 1` (transitioning)
+ * is kept. With `config.screen` pruning is off and only the subtree of the screen with that route name is reported.
+ */
+export declare const TREE_SCRIPT = "function (cfg, g) {\n  var rid = cfg.requestId;\n  var MAX = typeof cfg.max === \"number\" && cfg.max > 0 ? Math.min(Math.floor(cfg.max), 5000) : 5000;\n  var GUARD = typeof cfg.guardMs === \"number\" && cfg.guardMs > 0 ? cfg.guardMs : 1200;\n  var ALL = cfg.all === true;\n  var ONLY = typeof cfg.screen === \"string\" && cfg.screen !== \"\" ? cfg.screen : null;\n  var BUDGET = 300000;\n  var MAX_DEPTH = 1500;\n  var MEASURE_CAP = 8000;\n  var TEXT_CAP = 200;\n  var HOST_NAMES = {\n    RCTView: \"View\",\n    RCTText: \"Text\",\n    RCTVirtualText: \"Text\",\n    RCTScrollView: \"ScrollView\",\n    RCTImageView: \"Image\",\n    RCTSinglelineTextInputView: \"TextInput\",\n    RCTMultilineTextInputView: \"TextInput\",\n    AndroidTextInput: \"TextInput\"\n  };\n  var EMPTY = {};\n  var visits = 0;\n  var budgetHit = false;\n  var delivered = false;\n  var finished = false;\n  var timer = null;\n  var bestScreen = null;\n  var bestDepth = -1;\n  var onlyFound = false;\n  var hostMap = new Map();\n  var hostList = [];\n  var rects = [];\n  var forest = [];\n  var pending = 0;\n\n  function isObj(v) {\n    return v !== null && typeof v === \"object\";\n  }\n\n  function str(v) {\n    return typeof v === \"string\" && v !== \"\" ? v : undefined;\n  }\n\n  function message(e) {\n    return String(e && e.message ? e.message : e);\n  }\n\n  function deliver(result) {\n    if (delivered) return;\n    delivered = true;\n    var cb = g[cfg.binding];\n    if (typeof cb === \"function\") {\n      cb(JSON.stringify({ requestId: rid, result: result }));\n      return;\n    }\n    var store = g.__warden_tree_results;\n    if (!isObj(store)) {\n      store = {};\n      g.__warden_tree_results = store;\n    }\n    store[rid] = JSON.stringify(result);\n  }\n\n  function lastDisplay(style, depth) {\n    if (!style || depth > 6) return undefined;\n    if (Array.isArray(style)) {\n      var found;\n      for (var i = 0; i < style.length; i++) {\n        var d = lastDisplay(style[i], depth + 1);\n        if (d !== undefined) found = d;\n      }\n      return found;\n    }\n    return typeof style === \"object\" ? style.display : undefined;\n  }\n\n  function isHidden(props) {\n    return props.activityState === 0 ||\n      props.isPageFocused === false ||\n      props.freeze === true ||\n      props[\"aria-hidden\"] === true ||\n      props.accessibilityElementsHidden === true ||\n      props.importantForAccessibility === \"no-hide-descendants\" ||\n      lastDisplay(props.style, 0) === \"none\";\n  }\n\n  function typeName(t, depth) {\n    if (typeof t === \"function\") return t.displayName || t.name || \"\";\n    if (typeof t === \"string\") return t;\n    if (isObj(t) && depth < 4) {\n      return t.displayName || typeName(t.render, depth + 1) || typeName(t.type, depth + 1) || \"\";\n    }\n    return \"\";\n  }\n\n  function nameOf(f) {\n    var t = f.type;\n    if (f.tag === 5 && typeof t === \"string\") {\n      return Object.prototype.hasOwnProperty.call(HOST_NAMES, t) ? HOST_NAMES[t] : t;\n    }\n    return typeName(t, 0) || \"Component\";\n  }\n\n  function rectHostOf(f) {\n    if (f.tag === 5) return f;\n    var cur = f.child;\n    var n = 0;\n    while (cur && n < 30) {\n      if (cur.sibling) return null;\n      if (cur.tag === 5) return cur;\n      if (cur.tag === 6) return null;\n      cur = cur.child;\n      n++;\n    }\n    return null;\n  }\n\n  function registerHost(h) {\n    if (!h) return -1;\n    var i = hostMap.get(h);\n    if (i === undefined) {\n      if (hostList.length >= MEASURE_CAP) return -1;\n      i = hostList.length;\n      hostList.push(h);\n      hostMap.set(h, i);\n    }\n    return i;\n  }\n\n  function clip(t) {\n    return t.length > TEXT_CAP ? t.slice(0, TEXT_CAP) : t;\n  }\n\n  function buildChildren(f, ctx, depth) {\n    var nodes = [];\n    var strings = [];\n    if (depth >= MAX_DEPTH) {\n      budgetHit = true;\n      return { nodes: nodes, strings: strings };\n    }\n    var c = f.child;\n    while (c) {\n      var r = buildFiber(c, ctx, depth + 1);\n      for (var i = 0; i < r.nodes.length; i++) nodes.push(r.nodes[i]);\n      for (var j = 0; j < r.strings.length; j++) strings.push(r.strings[j]);\n      c = c.sibling;\n    }\n    return { nodes: nodes, strings: strings };\n  }\n\n  function buildFiber(f, ctx, depth) {\n    visits++;\n    if (visits > BUDGET) {\n      budgetHit = true;\n      return { nodes: [], strings: [] };\n    }\n    if (f.tag === 6) {\n      var s = f.memoizedProps;\n      if (typeof s === \"string\" || typeof s === \"number\") return { nodes: [], strings: [String(s)] };\n      return { nodes: [], strings: [] };\n    }\n    var props = isObj(f.memoizedProps) ? f.memoizedProps : EMPTY;\n    var route = props.route;\n    var nav = props.navigation;\n    var screenRoot = isObj(route) && typeof route.name === \"string\" && isObj(nav);\n    var focused;\n    if (screenRoot && typeof nav.isFocused === \"function\") {\n      try {\n        focused = nav.isFocused() === true;\n      } catch (e) {\n        focused = undefined;\n      }\n    }\n    var hidden = isHidden(props) || focused === false;\n    if (ONLY === null && hidden && !ALL) return { nodes: [], strings: [] };\n    var inactive = ctx.inactive || (ONLY === null && hidden);\n    var inScreen = ctx.inScreen;\n    if (ONLY !== null && screenRoot && route.name === ONLY) {\n      inScreen = true;\n      onlyFound = true;\n    }\n    if (ONLY === null && screenRoot && focused === true && !inactive && depth > bestDepth) {\n      bestDepth = depth;\n      bestScreen = route.name;\n    }\n    var childCtx = ctx;\n    if (inactive !== ctx.inactive || inScreen !== ctx.inScreen) childCtx = { inactive: inactive, inScreen: inScreen };\n    var kids = buildChildren(f, childCtx, depth);\n\n    var type = f.type;\n    var isHost = f.tag === 5 && typeof type === \"string\";\n    var isText = isHost && (type === \"RCTText\" || type === \"Text\");\n    var isVirtual = isHost && type === \"RCTVirtualText\";\n    var testID = str(props.testID);\n    var label = str(props.accessibilityLabel) || str(props[\"aria-label\"]);\n    var strings = kids.strings;\n    var text;\n    var outStrings = strings;\n    if (isText) {\n      var joined = clip(strings.join(\"\"));\n      text = joined === \"\" ? undefined : joined;\n      outStrings = [];\n    }\n    var emit = (ONLY === null || inScreen) &&\n      (testID !== undefined || label !== undefined || screenRoot || (isText && text !== undefined));\n    if (!emit) return { nodes: kids.nodes, strings: outStrings };\n    if (!isText && strings.length > 0) {\n      text = clip(strings.join(isVirtual ? \"\" : \" \"));\n      if (!isVirtual) outStrings = [];\n    }\n    var node = {\n      name: nameOf(f),\n      testID: testID,\n      label: label,\n      text: text,\n      hostIdx: registerHost(rectHostOf(f)),\n      kids: kids.nodes,\n      inactive: inactive,\n      screenRoot: screenRoot,\n      rect: undefined\n    };\n    return { nodes: [node], strings: outStrings };\n  }\n\n  function r1(v) {\n    return Math.round(v * 10) / 10;\n  }\n\n  function accept(i, x, y, w, h) {\n    if (finished) return;\n    if (typeof x !== \"number\" || typeof y !== \"number\" || typeof w !== \"number\" || typeof h !== \"number\") return;\n    if (!isFinite(x) || !isFinite(y) || !isFinite(w) || !isFinite(h) || w <= 0 || h <= 0) return;\n    rects[i] = { x: r1(x), y: r1(y), w: r1(w), h: r1(h) };\n  }\n\n  function done() {\n    pending--;\n    if (pending === 0) finish();\n  }\n\n  function measure(i) {\n    var sn = hostList[i].stateNode;\n    var settled = false;\n    function viaWindow(x, y, w, h) {\n      if (settled) return;\n      settled = true;\n      accept(i, x, y, w, h);\n      done();\n    }\n    function viaShadow(x, y, w, h, px, py) {\n      if (settled) return;\n      settled = true;\n      accept(i, px, py, w, h);\n      done();\n    }\n    try {\n      if (isObj(sn)) {\n        var pub = isObj(sn.canonical) ? sn.canonical.publicInstance : null;\n        if (isObj(pub) && typeof pub.measureInWindow === \"function\") {\n          pub.measureInWindow(viaWindow);\n          return;\n        }\n        if (typeof sn.measureInWindow === \"function\") {\n          sn.measureInWindow(viaWindow);\n          return;\n        }\n        var fab = g.nativeFabricUIManager;\n        if (sn.node && isObj(fab) && typeof fab.measure === \"function\") {\n          fab.measure(sn.node, viaShadow);\n          return;\n        }\n        var tag = typeof sn._nativeTag === \"number\"\n          ? sn._nativeTag\n          : (isObj(sn.canonical) && typeof sn.canonical.nativeTag === \"number\" ? sn.canonical.nativeTag : undefined);\n        var proxy = g.nativeModuleProxy;\n        var ui = isObj(proxy) ? proxy.UIManager : null;\n        if (tag !== undefined && isObj(ui) && typeof ui.measureInWindow === \"function\") {\n          ui.measureInWindow(tag, viaWindow);\n          return;\n        }\n      }\n    } catch (e) {\n    }\n    if (!settled) {\n      settled = true;\n      done();\n    }\n  }\n\n  function sameRect(a, b) {\n    if (a === undefined || b === undefined) return a === b;\n    return Math.abs(a.x - b.x) <= 1 && Math.abs(a.y - b.y) <= 1 && Math.abs(a.w - b.w) <= 1 && Math.abs(a.h - b.h) <= 1;\n  }\n\n  function canAbsorb(p, c) {\n    return !p.screenRoot &&\n      !!p.inactive === !!c.inactive &&\n      sameRect(p.rect, c.rect) &&\n      (c.testID === undefined || c.testID === p.testID) &&\n      (c.label === undefined || c.label === p.label);\n  }\n\n  function finalize(nodes) {\n    var out = [];\n    for (var i = 0; i < nodes.length; i++) {\n      var n = nodes[i];\n      n.rect = n.hostIdx >= 0 ? rects[n.hostIdx] : undefined;\n      n.kids = finalize(n.kids);\n      if (n.rect === undefined && n.testID === undefined) {\n        for (var k = 0; k < n.kids.length; k++) out.push(n.kids[k]);\n        continue;\n      }\n      while (n.kids.length === 1 && canAbsorb(n, n.kids[0])) {\n        var c = n.kids[0];\n        if (n.testID === undefined) n.testID = c.testID;\n        if (n.label === undefined) n.label = c.label;\n        if (n.text === undefined) n.text = c.text;\n        n.screenRoot = n.screenRoot || c.screenRoot;\n        n.kids = c.kids;\n      }\n      out.push(n);\n    }\n    return out;\n  }\n\n  var comps = [];\n  var more = false;\n\n  function flatten(nodes, parentId) {\n    for (var i = 0; i < nodes.length; i++) {\n      if (comps.length >= MAX) {\n        more = true;\n        return;\n      }\n      var n = nodes[i];\n      var id = comps.length;\n      var c = { id: id, name: n.name, parent: parentId };\n      if (n.testID !== undefined) c.testID = n.testID;\n      if (n.label !== undefined) c.label = n.label;\n      if (n.text !== undefined) c.text = n.text;\n      if (n.rect !== undefined) c.rect = n.rect;\n      if (n.inactive) c.inactive = true;\n      comps.push(c);\n      flatten(n.kids, id);\n    }\n  }\n\n  function finish() {\n    if (finished) return;\n    finished = true;\n    if (timer !== null && typeof g.clearTimeout === \"function\") g.clearTimeout(timer);\n    try {\n      flatten(finalize(forest), null);\n      var result = { components: comps, truncated: more || budgetHit };\n      var screen = ONLY !== null ? (onlyFound ? ONLY : null) : bestScreen;\n      if (screen !== null) result.screen = screen;\n      deliver(result);\n    } catch (e) {\n      deliver({ error: message(e) });\n    }\n  }\n\n  function countFibers(start) {\n    var n = 0;\n    var cur = start;\n    while (cur && n < 20000) {\n      n++;\n      if (cur.child) {\n        cur = cur.child;\n        continue;\n      }\n      while (cur && cur !== start && !cur.sibling) cur = cur.return;\n      if (!cur || cur === start) break;\n      cur = cur.sibling;\n    }\n    return n;\n  }\n\n  try {\n    var hook = g.__REACT_DEVTOOLS_GLOBAL_HOOK__;\n    if (!isObj(hook)) {\n      deliver({ error: \"no-hook\" });\n      return \"started\";\n    }\n    var best = null;\n    var bestCount = -1;\n    var consider = function (set) {\n      if (!set || typeof set.forEach !== \"function\") return;\n      set.forEach(function (root) {\n        var cur = root && root.current;\n        if (!cur) return;\n        var n = countFibers(cur);\n        if (n > bestCount) {\n          bestCount = n;\n          best = cur;\n        }\n      });\n    };\n    if (typeof hook.getFiberRoots === \"function\") {\n      if (isObj(hook.renderers) && typeof hook.renderers.forEach === \"function\") {\n        hook.renderers.forEach(function (renderer, id) {\n          consider(hook.getFiberRoots(id));\n        });\n      }\n      if (best === null) consider(hook.getFiberRoots(1));\n    }\n    if (best === null) {\n      deliver({ error: \"no-roots\" });\n      return \"started\";\n    }\n    forest = buildChildren(best, { inactive: false, inScreen: false }, 0).nodes;\n    if (hostList.length === 0) {\n      finish();\n      return \"started\";\n    }\n    pending = hostList.length + 1;\n    for (var i = 0; i < hostList.length; i++) measure(i);\n    done();\n    if (!finished) {\n      if (typeof g.setTimeout === \"function\") timer = g.setTimeout(finish, GUARD);\n      else finish();\n    }\n  } catch (e) {\n    deliver({ error: message(e) });\n  }\n  return \"started\";\n}";
+export type TreeScriptConfig = {
+    requestId: string;
+    /** name of the CDP binding to report through (when the page has it) */
+    binding: string;
+    max?: number;
+    screen?: string;
+    all?: boolean;
+    /** how long to wait for native measurements before reporting what arrived (default 1200 ms) */
+    guardMs?: number;
+};
+/** Expression that runs `TREE_SCRIPT` against the page's global object; evaluates to "started". */
+export declare function treeInstallExpression(config: TreeScriptConfig): string;

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

@@ -0,0 +1,29 @@
+import type { AlertInfo, Driver, DriverResult } from "./driver.types";
+/**
+ * Optional capabilities a driver can offer next to the frozen `Driver` interface, for `device.alert` and
+ * `device.openLink` (pattern: `RepeatingKeys` in `typing.ts`). A driver without them is still fully usable: the
+ * device layer falls back to `Driver.alert()` and to waiting out `openLink`'s window.
+ */
+/**
+ * The iOS accessibility readers a system alert can be read through. `ax` is the host reader: it sees
+ * SpringBoard-hosted sheets ("Open in …?", permission prompts) and never touches the in-simulator bridge, so a
+ * stuck stream or a relaunched app cannot slow it. `axbridge` is the in-simulator bridge: it also sees prompts the
+ * app owns (the Keychain "Save Password?" sheet, app alerts), which `ax` reports as one empty root.
+ */
+export type AlertBackend = "ax" | "axbridge";
+/**
+ * `alert()` through ONE reader, so a screen without an alert costs one tree read where `Driver.alert()` reads both.
+ * `null` = this reader shows none. `{ buttons: [] }` = a modal is up whose buttons are not readable yet.
+ */
+export type ReadsAlertOn = {
+    alertOn(backend: AlertBackend): DriverResult<AlertInfo | null>;
+};
+export declare function canReadAlertOn(driver: Driver): driver is Driver & ReadsAlertOn;
+/**
+ * Whether the app with `bundleId` owns the foreground right now: a read of the helper's own state, no tree read and no
+ * waiting. `false` while SpringBoard (a system sheet), Safari or another app is in front.
+ */
+export type ProbesFrontmost = {
+    isFrontmost(bundleId: string): DriverResult<boolean>;
+};
+export declare function canProbeFrontmost(driver: Driver): driver is Driver & ProbesFrontmost;

package/types/e2e/src/driver/android/adb-session.d.ts

@@ -0,0 +1,52 @@
+import type { DriverResult, Logger } from "../driver.types";
+/**
+ * One long-lived `adb -s <serial> shell` per driver. Spawning `adb shell <cmd>` per call costs ~50-150 ms
+ * of adb round trip; writing to a resident shell costs the command itself. Text commands only: binary
+ * output (screenshots) must NEVER go through this session, the pty-less shell is not binary clean, so
+ * screenshots use a separate `adb exec-out screencap -p` process (`android-argv.ts: screencapArgv`).
+ *
+ * Wire format, one line per command:
+ *   `(<cmd>) 2>&1 </dev/null; echo "__WDN_<id>_$?__"`
+ * stdout is accumulated until the sentinel for that id shows up; the text before it is the output and the
+ * number inside it the exit code. `</dev/null` keeps a stdin-reading command from eating the next line.
+ *
+ * Commands run strictly FIFO, one in flight. A timed-out command's shell state is unknowable, so the
+ * process is killed and the next `run` starts a fresh one. A process that dies mid-command fails that
+ * command with `E_HELPER_CRASHED` and is respawned on the next `run`; one respawn is allowed in a row
+ * (a respawned process that also dies before completing any command makes the session give up, every
+ * later `run` fails with `E_HELPER_CRASHED` until a new session is opened). A completed command resets
+ * the budget.
+ */
+/** The slice of a child process the session needs (real: `spawnAdb`; tests may inject their own). */
+export type AdbProcess = {
+    /** write text to the shell's stdin; throws when the pipe is closed */
+    write(data: string): void;
+    stdout: ReadableStream<Uint8Array>;
+    kill(): void;
+    /** resolves with the exit code once the process is gone */
+    exited: Promise<number>;
+};
+export type SpawnAdb = (argv: string[]) => AdbProcess;
+/** `Bun.spawn` with stdin/stdout piped and stderr dropped (`2>&1` is inside every command line). */
+export declare function spawnAdb(argv: string[], env?: Record<string, string>): AdbProcess;
+export type AdbRunResult = {
+    stdout: string;
+    exitCode: number;
+};
+export type AdbSessionOptions = {
+    /** path of the `adb` binary (`androidTools(env).adb`) */
+    adb: string;
+    serial: string;
+    spawn?: SpawnAdb;
+    log?: Logger;
+};
+export type AdbSession = {
+    /** run one shell command line; `timeoutMs` defaults to 10 s */
+    run(cmd: string, opts?: {
+        timeoutMs?: number;
+    }): DriverResult<AdbRunResult>;
+    /** kill the shell; later `run`s fail. Safe to call twice. */
+    close(): Promise<void>;
+};
+export declare const DEFAULT_ADB_TIMEOUT_MS = 10000;
+export declare function openAdbSession(options: AdbSessionOptions): AdbSession;

package/types/e2e/src/driver/android/android-alert.d.ts

@@ -0,0 +1,4 @@
+import type { AlertInfo, Element } from "../driver.types";
+export { ANDROID_ALLOW_IDS, ANDROID_DENY_IDS } from "../../alert-buttons";
+/** The alert on screen, or null. Title/message are best effort; at least one known button is required. */
+export declare function detectAlert(flat: readonly Element[]): AlertInfo | null;