@delacour/warden-e2e 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,433 @@
+import { z } from "zod";
+import type { DriverError, Rect, Role, ScreenInfo } from "../driver.types";
+/**
+ * Wire format of `warden-simd` (plan WDN-E2E, "warden-simd protocol (v1)"): newline-delimited JSON,
+ * one object per line. Requests `{id, op, …params, timeoutMs?}`; responses `{id, ok:true, data}` /
+ * `{id, ok:false, error}` (possibly out of order); events `{event:"ready"|"log"|"fatal", …}`.
+ */
+export declare const protocolVersion = 1;
+export declare const screenInfoSchema: z.ZodType<ScreenInfo>;
+/**
+ * One AX node as the helper sends it. `id`, `normFrame`, `depth`, `traits`, `enabled` and `children`
+ * may be omitted (the TS driver fills them in `normalize.ts`) and any optional field may arrive as
+ * `null` (unknown); everything else is the `Element` shape.
+ */
+export type WireElement = {
+    id?: string | null;
+    role: Role;
+    rawType: string;
+    label?: string | null;
+    identifier?: string | null;
+    value?: string | null;
+    text?: string | null;
+    placeholder?: string | null;
+    frame: Rect;
+    normFrame?: Rect | null;
+    traits?: string[] | null;
+    enabled?: boolean | null;
+    focused?: boolean | null;
+    hidden?: boolean | null;
+    selected?: boolean | null;
+    checked?: boolean | null;
+    hittable?: boolean | null;
+    tapPoint?: {
+        x: number;
+        y: number;
+    } | null;
+    pid?: number | null;
+    depth?: number | null;
+    children?: WireElement[] | null;
+};
+export declare const wireElementSchema: z.ZodType<WireElement>;
+/**
+ * Structural check of one wire node and its subtree, equivalent to {@link wireElementSchema} (a test compares
+ * them) but cheaper: about 0.05 ms warm for a 35-node tree against 0.25 ms, and about 0.7 ms on the first call of
+ * a process against 2 ms (measured after the ready event had warmed zod). Unknown keys are accepted (a newer
+ * helper may add fields); `normalize.ts` reads only the known ones.
+ */
+export declare function isWireElement(value: unknown): value is WireElement;
+export declare const wireErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+    detail: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type WireError = z.infer<typeof wireErrorSchema>;
+export declare const readyEventSchema: z.ZodObject<{
+    event: z.ZodLiteral<"ready">;
+    protocol: z.ZodNumber;
+    version: z.ZodString;
+    udid: z.ZodString;
+    hid: z.ZodObject<{
+        transport: z.ZodString;
+    }, z.core.$strip>;
+    ax: z.ZodObject<{
+        default: z.ZodString;
+        bridge: z.ZodString;
+    }, z.core.$strip>;
+    screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+}, z.core.$strip>;
+export type ReadyEvent = z.infer<typeof readyEventSchema>;
+export declare const logEventSchema: z.ZodObject<{
+    event: z.ZodLiteral<"log">;
+    level: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+        debug: "debug";
+    }>;
+    message: z.ZodString;
+    op: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LogEvent = z.infer<typeof logEventSchema>;
+export declare const fatalEventSchema: z.ZodObject<{
+    event: z.ZodLiteral<"fatal">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+        detail: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type FatalEvent = z.infer<typeof fatalEventSchema>;
+export declare const eventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event: z.ZodLiteral<"ready">;
+    protocol: z.ZodNumber;
+    version: z.ZodString;
+    udid: z.ZodString;
+    hid: z.ZodObject<{
+        transport: z.ZodString;
+    }, z.core.$strip>;
+    ax: z.ZodObject<{
+        default: z.ZodString;
+        bridge: z.ZodString;
+    }, z.core.$strip>;
+    screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"log">;
+    level: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+        debug: "debug";
+    }>;
+    message: z.ZodString;
+    op: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    event: z.ZodLiteral<"fatal">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+        detail: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "event">;
+export type SimdEvent = z.infer<typeof eventSchema>;
+export declare const responseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+        detail: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "ok">;
+export type SimdResponse = z.infer<typeof responseSchema>;
+/** Any line the helper may send. Events carry `event`, responses carry `ok`. */
+export type SimdMessage = {
+    kind: "event";
+    event: SimdEvent;
+} | {
+    kind: "response";
+    response: SimdResponse;
+};
+export type ParsedLine = {
+    success: true;
+    message: SimdMessage;
+} | {
+    success: false;
+    reason: string;
+};
+export declare function parseLine(line: string): ParsedLine;
+export declare const healthDataSchema: z.ZodObject<{
+    version: z.ZodString;
+    udid: z.ZodString;
+    hid: z.ZodObject<{
+        transport: z.ZodString;
+    }, z.core.$strip>;
+    ax: z.ZodObject<{
+        default: z.ZodString;
+        bridge: z.ZodEnum<{
+            available: "available";
+            missing: "missing";
+            failed: "failed";
+            degraded: "degraded";
+        }>;
+        error: z.ZodOptional<z.ZodString>;
+        lastError: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            agoMs: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+    socket: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        clients: z.ZodNumber;
+    }, z.core.$strip>>;
+    idb: z.ZodOptional<z.ZodString>;
+    xcode: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    uptimeMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type HealthData = z.infer<typeof healthDataSchema>;
+export declare const snapshotDataSchema: z.ZodObject<{
+    backend: z.ZodEnum<{
+        axbridge: "axbridge";
+        ax: "ax";
+        uiautomator: "uiautomator";
+    }>;
+    screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+    modal: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        pid: z.ZodOptional<z.ZodNumber>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    truncated: z.ZodBoolean;
+    elements: z.ZodArray<z.ZodCustom<WireElement, WireElement>>;
+    ms: z.ZodNumber;
+    fallback: z.ZodOptional<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    readMs: z.ZodOptional<z.ZodNumber>;
+    nodes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type SnapshotData = z.infer<typeof snapshotDataSchema>;
+export declare const elementAtPointDataSchema: z.ZodNullable<z.ZodType<WireElement, unknown, z.core.$ZodTypeInternals<WireElement, unknown>>>;
+/** `path` when the helper wrote the PNG itself, else `png` as base64. */
+export declare const screenshotDataSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    png: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type ScreenshotData = z.infer<typeof screenshotDataSchema>;
+/**
+ * `via`: `stream` (the guest reported run-loop idle) or `snapshot` (the stream was stuck: two identical reads); a
+ * value this client does not know reads as absent. `reason: "frontmost_mismatch"`: `bundleId` was asked for and never
+ * became the frontmost app before the deadline, and `frontmostPid` is what was frontmost instead.
+ */
+export declare const settleDataSchema: z.ZodObject<{
+    quiet: z.ZodBoolean;
+    waitedMs: z.ZodNumber;
+    via: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        snapshot: "snapshot";
+        stream: "stream";
+    }>>>;
+    reason: z.ZodOptional<z.ZodString>;
+    frontmostPid: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type SettleData = z.infer<typeof settleDataSchema>;
+/**
+ * `rebind` params: the helper (not the launch) waits until the quiescence stream reports on `bundleId`'s own process.
+ * `bound: false` is an answer, not an error: `reason` is `no_process` (the app never appeared), `timeout` (the stream
+ * stayed on another process) or `cancelled`. `restarts` is how many times the helper had to restart the stream.
+ */
+export declare const rebindDataSchema: z.ZodObject<{
+    bound: z.ZodBoolean;
+    waitedMs: z.ZodNumber;
+    pid: z.ZodOptional<z.ZodNumber>;
+    restarts: z.ZodOptional<z.ZodNumber>;
+    recycled: z.ZodOptional<z.ZodBoolean>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type RebindData = z.infer<typeof rebindDataSchema>;
+/**
+ * `alertButtons` params. No `backend` reads both readers (`ax` first, then `axbridge`); `ax` or `axbridge` reads only
+ * that one: one tree read instead of two, errors propagate (nothing else answered), and an `axbridge` read that sees a
+ * modal without readable buttons answers `{ buttons: [] }` instead of `null`.
+ */
+export type AlertButtonsParams = {
+    backend?: "ax" | "axbridge";
+};
+/** `alertButtons`: the system alert / sheet on top, `null` when there is none. */
+export declare const alertButtonsDataSchema: z.ZodNullable<z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    buttons: z.ZodArray<z.ZodType<WireElement, unknown, z.core.$ZodTypeInternals<WireElement, unknown>>>;
+}, z.core.$strip>>;
+export type AlertButtonsData = z.infer<typeof alertButtonsDataSchema>;
+/**
+ * `frontmost{bundleId}`: whether that app's process is the one the quiescence stream reports as frontmost. A read of the
+ * helper's state (one launchd lookup), no tree read and no waiting. `pid` is the bundle's process (absent when it is not
+ * running), `frontmostPid` the stream's (absent while no stream has reported).
+ */
+export declare const frontmostDataSchema: z.ZodObject<{
+    frontmost: z.ZodBoolean;
+    pid: z.ZodOptional<z.ZodNumber>;
+    frontmostPid: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type FrontmostData = z.infer<typeof frontmostDataSchema>;
+/**
+ * `orientation`: a real read may also say `faceUp` / `faceDown` / `unknown` (flat device); `source` tells
+ * whether the value was read from the device, is the last one this helper wrote, or is an assumed portrait.
+ */
+export declare const orientationDataSchema: z.ZodObject<{
+    orientation: z.ZodEnum<{
+        portrait: "portrait";
+        portraitUpsideDown: "portraitUpsideDown";
+        landscapeLeft: "landscapeLeft";
+        landscapeRight: "landscapeRight";
+        unknown: "unknown";
+        faceUp: "faceUp";
+        faceDown: "faceDown";
+    }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        device: "device";
+        written: "written";
+        assumed: "assumed";
+    }>>;
+}, z.core.$strip>;
+export type OrientationData = z.infer<typeof orientationDataSchema>;
+/** Ops whose `data` the client validates and types; every other op's data stays `unknown`. */
+export declare const opSchemas: {
+    readonly health: z.ZodObject<{
+        version: z.ZodString;
+        udid: z.ZodString;
+        hid: z.ZodObject<{
+            transport: z.ZodString;
+        }, z.core.$strip>;
+        ax: z.ZodObject<{
+            default: z.ZodString;
+            bridge: z.ZodEnum<{
+                available: "available";
+                missing: "missing";
+                failed: "failed";
+                degraded: "degraded";
+            }>;
+            error: z.ZodOptional<z.ZodString>;
+            lastError: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                agoMs: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+        socket: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            clients: z.ZodNumber;
+        }, z.core.$strip>>;
+        idb: z.ZodOptional<z.ZodString>;
+        xcode: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        uptimeMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    readonly snapshot: z.ZodObject<{
+        backend: z.ZodEnum<{
+            axbridge: "axbridge";
+            ax: "ax";
+            uiautomator: "uiautomator";
+        }>;
+        screen: z.ZodType<ScreenInfo, unknown, z.core.$ZodTypeInternals<ScreenInfo, unknown>>;
+        modal: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            pid: z.ZodOptional<z.ZodNumber>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        truncated: z.ZodBoolean;
+        elements: z.ZodArray<z.ZodCustom<WireElement, WireElement>>;
+        ms: z.ZodNumber;
+        fallback: z.ZodOptional<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        readMs: z.ZodOptional<z.ZodNumber>;
+        nodes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    readonly elementAtPoint: z.ZodNullable<z.ZodType<WireElement, unknown, z.core.$ZodTypeInternals<WireElement, unknown>>>;
+    readonly screenshot: z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        png: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    readonly settle: z.ZodObject<{
+        quiet: z.ZodBoolean;
+        waitedMs: z.ZodNumber;
+        via: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            snapshot: "snapshot";
+            stream: "stream";
+        }>>>;
+        reason: z.ZodOptional<z.ZodString>;
+        frontmostPid: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    readonly rebind: z.ZodObject<{
+        bound: z.ZodBoolean;
+        waitedMs: z.ZodNumber;
+        pid: z.ZodOptional<z.ZodNumber>;
+        restarts: z.ZodOptional<z.ZodNumber>;
+        recycled: z.ZodOptional<z.ZodBoolean>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    readonly alertButtons: z.ZodNullable<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        buttons: z.ZodArray<z.ZodType<WireElement, unknown, z.core.$ZodTypeInternals<WireElement, unknown>>>;
+    }, z.core.$strip>>;
+    readonly frontmost: z.ZodObject<{
+        frontmost: z.ZodBoolean;
+        pid: z.ZodOptional<z.ZodNumber>;
+        frontmostPid: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    readonly orientation: z.ZodObject<{
+        orientation: z.ZodEnum<{
+            portrait: "portrait";
+            portraitUpsideDown: "portraitUpsideDown";
+            landscapeLeft: "landscapeLeft";
+            landscapeRight: "landscapeRight";
+            unknown: "unknown";
+            faceUp: "faceUp";
+            faceDown: "faceDown";
+        }>;
+        source: z.ZodOptional<z.ZodEnum<{
+            device: "device";
+            written: "written";
+            assumed: "assumed";
+        }>>;
+    }, z.core.$strip>;
+};
+export type OpDataMap = {
+    health: HealthData;
+    snapshot: SnapshotData;
+    elementAtPoint: WireElement | null;
+    screenshot: ScreenshotData;
+    settle: SettleData;
+    rebind: RebindData;
+    alertButtons: AlertButtonsData;
+    frontmost: FrontmostData;
+    orientation: OrientationData;
+};
+export type OpData<Op extends string> = Op extends keyof OpDataMap ? OpDataMap[Op] : unknown;
+export declare function hasOpSchema(op: string): op is keyof typeof opSchemas;
+/** Wire code → `DriverErrorCode`: `E_UNKNOWN_UDID` is `E_UNKNOWN_DEVICE`, unknown codes are `E_INTERNAL` (code kept in `detail`). */
+export declare function mapWireError(wire: WireError): DriverError;
+export type LineSplitter = {
+    /** feed raw bytes; returns the complete lines (without `\n` / `\r\n`, blanks dropped) */
+    push(chunk: Uint8Array): string[];
+    /** the unterminated tail (a crashed helper may leave one) */
+    rest(): string;
+};
+/** Newline framing that is safe against chunk boundaries inside a line or a UTF-8 sequence. */
+export declare function createLineSplitter(): LineSplitter;
+export type SimdRequest = {
+    id: string;
+    op: string;
+    timeoutMs?: number;
+} & Record<string, unknown>;
+export declare function encodeRequest(request: SimdRequest): string;

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

@@ -0,0 +1,43 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError } from "../driver.types";
+/**
+ * The byte pipe under `simd-client`: a spawned helper's stdio or a unix socket. A transport only
+ * frames lines and reports closure; ids, timeouts and respawn live in the client.
+ */
+export type TransportClose = {
+    exitCode: number | null;
+    stderrTail: string[];
+};
+export type TransportHandlers = {
+    onLine(line: string): void;
+    /** helper stderr (stdio mode) */
+    onDiagnostic(line: string): void;
+    onClose(info: TransportClose): void;
+};
+export type Transport = {
+    send(data: string): void;
+    /** graceful: stop input, wait for exit up to the grace period, then kill */
+    close(): Promise<void>;
+};
+export type TransportFactory = (handlers: TransportHandlers) => Promise<Result<Transport, DriverError>>;
+/** The slice of a child process the stdio transport needs; tests and `bunSpawn` provide it. */
+export type SimdProcess = {
+    write(data: string): void;
+    /** close stdin */
+    end(): void;
+    kill(): void;
+    stdout: ReadableStream<Uint8Array>;
+    stderr?: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+};
+export type SimdSpawn = (cmd: readonly string[]) => SimdProcess;
+export declare const bunSpawn: SimdSpawn;
+export declare function stdioTransport(opts: {
+    cmd: readonly string[];
+    spawn?: SimdSpawn;
+    /** how long `close()` waits for the helper to exit after closing stdin before killing it */
+    graceMs?: number;
+}): TransportFactory;
+export declare function socketTransport(opts: {
+    socketPath: string;
+}): TransportFactory;

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

@@ -0,0 +1,6 @@
+/** Per-request budget for the helper's `typeText`: it holds, paces and (for a repeated key) waits per character. */
+export declare const TYPE_BASE_MS = 10000;
+export declare const TYPE_PER_CHAR_MS = 70;
+export declare const TYPE_PER_REPEAT_MS = 300;
+/** Base + ~70 ms per character + 300 ms per character equal to the one before it. */
+export declare function typeTextBudgetMs(text: string): number;

package/types/e2e/src/driver/observation-cache.d.ts

@@ -0,0 +1,66 @@
+import type { AlertInfo, Driver, DriverResult, Platform, Snapshot } from "./driver.types";
+/**
+ * A short-lived memory of the last whole-screen snapshot, so a read that follows another with no input in between
+ * does not walk the screen again (`isVisible()` then `text()` was two snapshots; on Android each one is a ~1.9 s
+ * `uiautomator dump`).
+ *
+ * It is a `Driver` wrapper, because every layer that can change the screen (`screen`, `app`, `device`, specs) shares
+ * the one driver: whatever calls it, an input moves the *generation* on and the kept snapshot dies with the old one.
+ * A snapshot is also dropped once it is older than the platform's max age, input or not (the app can change by itself).
+ * Which reads may reuse one is the caller's call (`observe({ reuse })`): only the first look of a wait does, so a
+ * poll never spins on a tree that stopped being true.
+ */
+/** How old a kept snapshot may be and still answer a read. iOS reads cost ~100-300 ms; an Android dump takes ~1.9 s. */
+export declare const OBSERVATION_MAX_AGE_MS: Record<Platform, number>;
+/** Optional capability of the cached driver, next to the frozen `Driver` (pattern: `SelectsAll` in `typing.ts`). */
+export type Observes = {
+    /** the whole screen: the kept snapshot when `reuse` and it is still good, else a new one (which is then kept) */
+    observe(options: {
+        reuse: boolean;
+    }): DriverResult<Snapshot>;
+    /** forgets the kept snapshot: the next `observe` reads the device */
+    invalidateObservations(): void;
+    /**
+     * The look before the next one, for an action's stability rule (a frame that held still across two looks). Never
+     * used to answer a read: the kept snapshot is returned whatever its age.
+     */
+    previous?(): PreviousLook;
+    /**
+     * The kept snapshot and its age, when no input came since it was taken (whatever its age; the caller judges). Never
+     * reads the device. For a tap that checks a young kept snapshot with a hit-test instead of taking a new one.
+     */
+    peek?(): KeptLook | undefined;
+};
+export type KeptLook = {
+    snapshot: Snapshot;
+    ageMs: number;
+};
+export type PreviousLook = {
+    /** the kept snapshot, when no input came since it was taken (whatever its age) */
+    snapshot: Snapshot | undefined;
+    /** the input generation now: two answers with the same number had no input between them */
+    generation: number;
+    /** ms since the last input ended; undefined before any input */
+    sinceInputMs: number | undefined;
+};
+export declare function canObserve(driver: Driver): driver is Driver & Observes;
+/**
+ * Optional capability: the system alert, worked out from a snapshot already taken (Android: alerts are windows in the
+ * dump). With it the cache answers `alert()` from the kept snapshot instead of dumping the screen again.
+ */
+export type DetectsAlerts = {
+    alertIn(snapshot: Snapshot): AlertInfo | null;
+};
+export declare function canDetectAlerts(driver: Driver): driver is Driver & DetectsAlerts;
+export type ObservationCacheOptions = {
+    /** time source (ms); default `Date.now` */
+    now?: () => number;
+    /** default `OBSERVATION_MAX_AGE_MS` for the driver's platform */
+    maxAgeMs?: number;
+};
+/**
+ * Wraps `driver` (a `Proxy`: every member, optional capabilities included, reads through unchanged) with the
+ * observation cache and the {@link Observes} capability. Put it outside the tracing wrapper, so a snapshot that was
+ * served from memory leaves no `driver.snapshot` span.
+ */
+export declare function cacheObservations<D extends Driver>(driver: D, options?: ObservationCacheOptions): D & Observes;

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

@@ -0,0 +1,29 @@
+import { type Exec } from "../../../core/src/exec";
+import type { E2eEnv } from "../env";
+import type { DriverFactory } from "../session";
+import { type AndroidDriverOptions } from "./android/android-driver";
+import type { Driver, DriverResult } from "./driver.types";
+import { type OpenIosDriverOptions } from "./ios/ios-driver";
+/**
+ * Test seams for {@link openDriver}: everything the platform openers inject except what the env supplies.
+ * `android` carries the Android-only seams (`adb` path, resident-shell spawn, binary runner, clock).
+ */
+export type OpenDriverDeps = Omit<OpenIosDriverOptions, "udid" | "env" | "exec"> & {
+    exec?: Exec;
+    android?: Omit<AndroidDriverOptions, "serial" | "exec" | "log" | "adb"> & {
+        adb?: string;
+    };
+};
+/** `WARDEN_E2E_DEBUG=1` logs every helper op and simctl call with its duration to stderr. */
+export declare const DEBUG_ENV = "WARDEN_E2E_DEBUG";
+/**
+ * The Android opener's options: the env's serial and app package, the `state` store under `<wardenHome>/android`
+ * (a caller's own `android.state` wins) that remembers the dump route that worked and the animation scales to put
+ * back, the resident `warden-uiad` server (unless `WARDEN_ANDROID_UIAD=0`, a caller's own `android.uiad`, or an injected
+ * shell `spawn`, which is a test that must never reach a real `adb`), and the injected seams.
+ */
+export declare function androidOptions(env: E2eEnv, deps: OpenDriverDeps, debug: boolean): AndroidDriverOptions;
+/** Open the `Driver` for the device in `env`, by platform. Android deep links go to `env.bundleId` only. */
+export declare function openDriver(env: E2eEnv, deps?: OpenDriverDeps): DriverResult<Driver>;
+/** What the session uses when no factory is passed; `preload.ts` registers it with `setDefaultDriverFactory`. */
+export declare const defaultDriverFactory: DriverFactory;

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

@@ -0,0 +1,43 @@
+import type { Snapshot } from "./driver.types";
+export type SettleDeps = {
+    quietMs: number;
+    timeoutMs: number;
+    /** monotonic-ish clock in ms */
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    /** gap between polls, default 50 */
+    pollMs?: number;
+};
+export type SettleOutcome = {
+    quiet: boolean;
+    waitedMs: number;
+};
+/** How a settle decided: the helper's quiescence `stream` (iOS `warden-simd`, Android `warden-uiad`: the accessibility events stopped), the `snapshot` stability fallback, or client-side snapshot `hash` polling. */
+export type SettleVia = "stream" | "snapshot" | "hash";
+/**
+ * What a driver's `settle` may report beyond the frozen `{ quiet, waitedMs }` of `Driver["settle"]` (a driver
+ * returns this wider object; the contract in `driver.types.ts` is unchanged). iOS passes the helper's reply through:
+ * `via`, `reason` (`frontmost_mismatch` when the launched app never came to the front, `helper_timeout` when the
+ * helper answered after the client's padded timer) and `frontmostPid`. Android says `stream` when `warden-uiad` waited
+ * for the events to stop, else `snapshot` when one `uiautomator dump` covered the whole quiet window and `hash` when it
+ * compared successive snapshots; the iOS hash fallback says `hash`.
+ */
+export type SettleDetail = SettleOutcome & {
+    via?: SettleVia;
+    reason?: string;
+    frontmostPid?: number;
+};
+/** The extra fields of a settle reply, kept when they have the right type. `Driver["settle"]` is typed narrower than it answers. */
+export declare function settleDetailOf(outcome: SettleOutcome): SettleDetail;
+/** A screen counts as settled once its hash stayed equal this long (`device.settle`, `warden ui --settle`). */
+export declare const DEFAULT_SETTLE_QUIET_MS = 250;
+/** How long a settle waits for quiet before it gives up. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+/**
+ * Snapshot-hash settle: poll a UI fingerprint until it stays unchanged for `quietMs`
+ * (two consecutive equal hashes and ≥ quietMs since the last change), or give up at `timeoutMs`.
+ * Side effects are injected so tests drive a fake clock.
+ */
+export declare function settleByHash(poll: () => Promise<string>, deps: SettleDeps): Promise<SettleOutcome>;
+/** Stable fingerprint over `(role, identifier, label, value, frame)` of every node in preorder. */
+export declare function snapshotHash(snapshot: Pick<Snapshot, "flat">): string;

package/types/e2e/src/driver/span-detail.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Where code deep inside a driver call (an adb command, the dump route, a settle verdict) leaves a note for the
+ * `span` that is timing that call, without the driver knowing about tracing: a note outside a span goes nowhere.
+ * Values are scalars so a span stays one short JSON line.
+ */
+export type SpanDetail = Record<string, string | number | boolean>;
+/** Runs `fn` with `notes` as the sink for every {@link noteSpanDetail} / {@link addSpanDetail} made inside it, awaits included. */
+export declare function collectSpanDetail<T>(notes: SpanDetail, fn: () => T): T;
+/** Sets `key` on the innermost span being timed. */
+export declare function noteSpanDetail(key: string, value: string | number | boolean): void;
+/** Adds `amount` to a numeric `key` of the innermost span (a counter or a sum of durations). */
+export declare function addSpanDetail(key: string, amount: number): void;

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

@@ -0,0 +1,14 @@
+import { type SpanSink } from "../runner/span";
+import type { Driver } from "./driver.types";
+export type TracedDriverOptions = {
+    /** where spans go right now: the running attempt's trace, `undefined` between attempts. Read per call. */
+    trace: () => SpanSink | undefined;
+    now?: () => number;
+};
+/**
+ * Wraps `driver` so every call it answers with a promise (`snapshot`, `tap`, `settle`, `app.launch`, and whatever
+ * optional capability it offers, such as `pressKeyRepeat`) writes a `driver.<call>` span to the running attempt's
+ * trace. It is a `Proxy`, so every other member (`platform`, `capabilities`, a synchronous method) reads through
+ * unchanged, and nothing is recorded outside an attempt. Arguments are never recorded: `typeText` carries passwords.
+ */
+export declare function traceDriver<D extends Driver>(driver: D, options: TracedDriverOptions): D;