@delacour/warden-e2e 0.0.0-stage → 0.1.0

package/types/core/src/types.d.ts

@@ -0,0 +1,126 @@
+export type Platform = "ios" | "android";
+export type DeviceResource = {
+    kind: "device";
+    platform: Platform;
+    id: string;
+    name: string;
+};
+export type PortResource = {
+    kind: "port";
+    port: number;
+};
+export type BuildResource = {
+    kind: "build";
+    key: string;
+};
+export type Resource = DeviceResource | PortResource | BuildResource;
+export type AgentOwner = {
+    kind: "agent";
+    sessionId: string;
+    cwd: string;
+    repo?: string;
+    worktree?: string;
+};
+export type UserOwner = {
+    kind: "user";
+    pid: number;
+    tty?: string;
+    cwd: string;
+    repo?: string;
+    worktree?: string;
+};
+export type CiOwner = {
+    kind: "ci";
+    runId: string;
+};
+export type Owner = AgentOwner | UserOwner | CiOwner;
+export type Lease = {
+    id: string;
+    resource: Resource;
+    owner: Owner;
+    label?: string;
+    acquiredAt: number;
+    heartbeatAt: number;
+    ttlMs: number;
+    pid?: number;
+    /** the owner booted this device (it was off when leased) — so it's theirs to shut down on release */
+    bootedByOwner?: boolean;
+    /**
+     * Heartbeat period of the process that holds this lease (`run` / `dev` / `batch` / `e2e`, which also
+     * record their own `pid`). With a pid, a dead pid makes the lease stale after `LOST_HEARTBEATS` periods.
+     */
+    heartbeatMs?: number;
+    /**
+     * The holding process (`warden dev`) lets its owner's other processes drive the device beside it: `warden ui`
+     * attaches to it instead of refusing with `device_busy`, and never releases it. Other owners still see it as foreign.
+     */
+    shared?: boolean;
+};
+export type DeviceState = "booted" | "shutdown" | "booting";
+/** A device as seen by a provider, enriched with warden's own bookkeeping. */
+export type InventoryDevice = {
+    platform: Platform;
+    id: string;
+    name: string;
+    state: DeviceState;
+    /** true when warden created this device (sim) or launched it (emulator) */
+    wardenCreated: boolean;
+    /** warden profile slug, e.g. `iphone-17` */
+    profile?: string;
+    /** runtime identifier or version, e.g. `iOS-26-5` */
+    runtime?: string;
+    /** a golden image (`warden-golden-*`): clone source only — never allocated, adopted, booted by gc or counted in a pool */
+    golden?: boolean;
+    /** reported bad: never allocated until `warden sim unquarantine` */
+    quarantined?: boolean;
+};
+export type DeviceRequest = {
+    platform: Platform;
+    profile: string;
+    runtime?: string;
+    count: number;
+    /** max warden-created devices for this platform+profile */
+    max: number;
+    /** allow allocating foreign (non-warden) devices that match the profile */
+    adopt?: boolean;
+};
+export type AllocationStep = {
+    action: "reuse";
+    device: InventoryDevice;
+} | {
+    action: "boot";
+    device: InventoryDevice;
+} | {
+    action: "create";
+    name: string;
+};
+export type AllocationPlan = {
+    kind: "assign";
+    steps: AllocationStep[];
+    stale: string[];
+} | {
+    kind: "wait";
+    available: number;
+    needed: number;
+    stale: string[];
+};
+export declare function resourceKey(resource: Resource): string;
+export declare function describeOwner(owner: Owner): string;
+/** Owner location for messages: `repo/worktree` when known. */
+export declare function ownerLocation(owner: Owner): string | undefined;
+export declare function sameOwner(a: Owner, b: Owner): boolean;
+/** A claim waiting for host capacity to boot devices (`boot_queue` row). */
+export type QueueEntry = {
+    id: string;
+    platform: Platform;
+    profile: string;
+    /** capacity units the boots need */
+    units: number;
+    /** numeric base priority (see `PRIORITY` in queue.ts); aging adds to it */
+    priority: number;
+    enqueuedAt: number;
+    heartbeatAt: number;
+    owner: Owner;
+    label?: string;
+    pid?: number;
+};

package/types/e2e/src/alert-buttons.d.ts

@@ -0,0 +1,41 @@
+import type { Element, Point } from "./driver/driver.types";
+/**
+ * Button names `device.alert("accept")` / `("dismiss")` look for, in order. The Android permission prompt's own
+ * labels ("While using the app", "Only this time", "Don't allow") are here too; on Android `accept` and `dismiss` go
+ * by the permission prompt's button ids first (`ANDROID_PERMISSION_ALLOW_IDS`, `ANDROID_PERMISSION_DENY_IDS`), which also
+ * holds in other locales, then by these names, then by `AlertDialog`'s `button1` / `button2`. "Don't allow" is matched by
+ * "Don't Allow" (names compare ignoring case).
+ */
+export declare const ACCEPT_BUTTONS: string[];
+export declare const DISMISS_BUTTONS: string[];
+export declare function nameOf(button: Element): string | undefined;
+/** The button called `wanted`, ignoring case and curly apostrophes. */
+export declare function findButton(buttons: readonly Element[], wanted: string): Element | undefined;
+export declare function firstOf(buttons: readonly Element[], names: readonly string[]): Element | undefined;
+/** Where to tap an element: its own tap point, else the middle of its frame. */
+export declare function centre(element: Element): Point;
+/**
+ * The permission prompt's allow buttons, in the order `device.alert("accept")` tries them, the most lasting grant
+ * first (API 30+ camera, mic and location prompts show "While using the app", "Only this time" and "Don't allow",
+ * deny last, so the last button is the wrong guess). Going by id holds in other locales.
+ */
+export declare const ANDROID_PERMISSION_ALLOW_IDS: readonly string[];
+/** The permission prompt's deny buttons: the plain one before "don't ask again", which a later prompt could not undo. */
+export declare const ANDROID_PERMISSION_DENY_IDS: readonly string[];
+/**
+ * `AlertDialog`'s positive (`button1`) and negative (`button2`) ids. Only a fallback after the names: React Native's
+ * `Alert.alert` fills them by position, not by style (positive = last button, negative = second to last), so
+ * `[OK, Cancel]` puts OK on `button2` and `[Cancel, Delete, Keep]` puts Delete there.
+ */
+export declare const ANDROID_POSITIVE_ID = "button1";
+export declare const ANDROID_NEGATIVE_ID = "button2";
+/**
+ * Every id `device.alert("accept")` goes by on Android: the permission allow ids (before the names), then
+ * `AlertDialog`'s positive `button1` (after the names).
+ */
+export declare const ANDROID_ALLOW_IDS: readonly string[];
+/**
+ * Every id `device.alert("dismiss")` goes by on Android: the permission deny ids (before the names), then
+ * `AlertDialog`'s negative `button2` (after the names).
+ */
+export declare const ANDROID_DENY_IDS: readonly string[];

package/types/e2e/src/alert-reader.d.ts

@@ -0,0 +1,25 @@
+import { type AlertBackend } from "./driver/alerts";
+import type { AlertInfo, Driver } from "./driver/driver.types";
+import type { Clock } from "./fixture-session";
+/** A modal is up but its buttons are not readable yet: look again this many times, this far apart. */
+export declare const ALERT_MODAL_LOOKS = 3;
+export type AlertReaderDeps = {
+    driver: Driver;
+    clock: Clock;
+    /** the running attempt's deadline, read per call */
+    signal: () => AbortSignal | undefined;
+};
+/** `readAlert(backend?, modalLooks?)`: see {@link createAlertReader}. */
+export type AlertReader = (backend?: AlertBackend, modalLooks?: number) => Promise<AlertInfo | null>;
+/**
+ * Reads the system alert on top for `device.alert` and `device.openLink`.
+ *
+ * With `backend`, and a driver that can read one reader (`driver/alerts.ts`), that reader is read ONCE: a screen without
+ * an alert costs one tree read where `driver.alert()` reads both readers, and nothing sleeps. A modal that is up but
+ * shows no buttons yet (`buttons: []`) is looked at again `modalLooks` times, `ALERT_MODAL_RETRY_MS` apart, then reported
+ * as it is. If the bridge read fails (it answers nothing for ~0.2 s after a launch, while its quiescence stream is not
+ * bound to the new process), the host reader is read once: what `driver.alert()` would answer when one of its two readers
+ * fails, for one read instead of two. If that fails too, or there is no `backend`, the two-reader `driver.alert()`
+ * answers instead, retrying a transient failure after a short sleep.
+ */
+export declare function createAlertReader({ driver, clock, signal }: AlertReaderDeps): AlertReader;

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

@@ -0,0 +1,62 @@
+import type { Driver } from "./driver/driver.types";
+import type { E2eEnv } from "./env";
+import { type Clock, type FixtureSession } from "./fixture-session";
+import { type Locator } from "./screen/locator";
+/** `app.open({ wait: { until } })`: the first screen, named by a locator. */
+export type OpenWaitUntil = {
+    /** a locator made by `screen` that is visible once the app's first screen is up */
+    until: Locator;
+    /** how long `until` gets to show; default the assertion timeout (`WARDEN_E2E_ASSERTION_TIMEOUT`) */
+    timeout?: number;
+};
+export type OpenOptions = {
+    /** opened with `driver.app.openUrl` once the app is launched */
+    url?: string;
+    /** appended after `WARDEN_LAUNCH_ARGS` (on Android, which cannot take launch args, these still fail the launch) */
+    args?: readonly string[];
+    env?: Record<string, string>;
+    /**
+     * `"none"` (default): return when the launch call returns, which is before the app is on screen.
+     *
+     * `"quiet"`: then wait for the first screen and for it to stop moving. A launch screen (a storyboard, an Android
+     * splash) is idle while the app loads, so "quiet" alone would end on it: the screen is read after 100, 200, then
+     * every 400 ms until it shows content (a visible control, or any element with a testID), for at most 3 s, then
+     * settled (what `device.settle()` waits for: 250 ms of quiet, at most 3 s). That is a best-effort wait, never an
+     * error: a first screen with no control and no testID waits out the 3 s, and an app that is not quiet in time is
+     * returned as it is, so assert on what the test needs.
+     *
+     * `{ until }`: wait for that locator to be visible (an error after `timeout`, like `toBeVisible()`), then settle
+     * once, so the next tap lands on a mounted screen. Use it in place of `open()` followed by `toBeVisible()`.
+     */
+    wait?: "quiet" | "none" | OpenWaitUntil;
+};
+/** The app under test (`WARDEN_BUNDLE_ID`). */
+export type App = {
+    /**
+     * Launches the app (terminating a running instance first) with `WARDEN_LAUNCH_ARGS` + `args`, then
+     * opens `url` if given, then waits as `wait` says (`"quiet"`: first content then still; `{ until }`). The runner calls this (with no options) for the per-test
+     * `launch: "fresh"` default.
+     */
+    open(options?: OpenOptions): Promise<void>;
+    close(): Promise<void>;
+    /** terminate, then launch again with `WARDEN_LAUNCH_ARGS` (the launch itself terminates a running instance, so there is one stop, not two) */
+    restart(): Promise<void>;
+    /** uninstall (when installed) and install again from `WARDEN_APP_PATH` */
+    reinstall(): Promise<void>;
+    /**
+     * Wipes app data but keeps the build. Always asks for the keychain to be reset as well: the iOS
+     * driver maps this to core `resetAppData` with `resetKeychain`, Android to `pm clear`.
+     */
+    clearData(): Promise<void>;
+    isRunning(): Promise<boolean>;
+};
+export type AppDeps = {
+    session: FixtureSession;
+    driver: Driver;
+    env: E2eEnv;
+    /** where the one "dropped WARDEN_LAUNCH_ARGS on Android" line goes; default stderr */
+    log?: (line: string) => void;
+    /** time for the `wait: "quiet"` content poll; default the system clock */
+    clock?: Clock;
+};
+export declare function createApp({ session, driver, env, log, clock }: AppDeps): App;

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

@@ -0,0 +1,26 @@
+import type { ConsoleLine, DevtoolsFacet, DevtoolsResult } from "./devtools/devtools.types";
+/** Where the facet comes from: the session attaches it on the first `devtools()` and keeps it. */
+export type DevtoolsSource = {
+    devtools(): Promise<DevtoolsResult<DevtoolsFacet>>;
+    peekDevtools(): DevtoolsFacet | undefined;
+};
+/**
+ * `device.devtools`: the app's JS runtime over Metro. Every call attaches on first use (the session shares one
+ * connection), so the members that are synchronous on a bare facet (`console`) are async here. `connect()` hands out
+ * the whole facet (`target`, `on`, `attachArtifacts`).
+ */
+export type DeviceDevtools = {
+    evaluate: DevtoolsFacet["evaluate"];
+    reloadJs: DevtoolsFacet["reloadJs"];
+    /** the app's React components with rects, `devtools_unavailable` when the app has no DevTools hook */
+    tree: DevtoolsFacet["tree"];
+    network: DevtoolsFacet["network"];
+    console: {
+        lines(): Promise<ConsoleLine[]>;
+        clear(): Promise<void>;
+        mark(label: string): Promise<void>;
+    };
+    /** the attached facet; throws `SESSION` when the app cannot be reached */
+    connect(): Promise<DevtoolsFacet>;
+};
+export declare function createDeviceDevtools(source: DevtoolsSource): DeviceDevtools;

package/types/e2e/src/device-link.d.ts

@@ -0,0 +1,43 @@
+import type { AlertBackend } from "./driver/alerts";
+import type { AlertInfo, Element } from "./driver/driver.types";
+import type { Clock } from "./fixture-session";
+import type { Locator } from "./screen/locator";
+/** A loaded machine can show the sheet several seconds after `openUrl` returns. */
+export declare const OPEN_LINK_WAIT_MS = 8000;
+export declare function sheetlessFor(session: object): Set<string>;
+/**
+ * Whether `openLink` is waiting on a link in `session`. Reads that answer system alerts (`test.use({ systemAlerts })`)
+ * leave alerts alone meanwhile: a read that cancelled (or pressed) the sheet first would lose the link, or hide the
+ * sheet from `openLink`, which then remembers the scheme as having none.
+ */
+export declare function linkInFlight(session: object): boolean;
+/** Runs `fn` with a link in flight in `session` (see {@link linkInFlight}). */
+export declare function whileLinkInFlight<T>(session: object, fn: () => Promise<T>): Promise<T>;
+/** iOS's "Open in “App”?" sheet, which only a link the test opened raises. */
+export declare function isOpenInSheet(info: Pick<AlertInfo, "title">): boolean;
+/** `myapp` for `myapp://x/y`; `https://example.com` for web links, which are handled per host. */
+export declare function linkKey(url: string): string;
+export type LinkDeps = {
+    clock: Clock;
+    /** `readAlert`: with a backend, one reader; without, both */
+    readAlert(backend?: AlertBackend, modalLooks?: number): Promise<AlertInfo | null>;
+    press(button: Element): Promise<void>;
+    /** is the app under test in front; undefined = cannot tell */
+    appInFront(): Promise<boolean | undefined>;
+    isVisible(locator: Locator): Promise<boolean>;
+    /** `sheetlessFor(session)` */
+    sheetless: Set<string>;
+};
+export type LinkPlan = {
+    key: string;
+    /** iOS, `accept` not false: there may be an "Open in …?" sheet to answer */
+    answersSheet: boolean;
+    until?: Locator;
+    waitMs: number;
+};
+/**
+ * Waits for a link `openUrl` just opened to be handled (see `Device.openLink`): the sheet answered, or the app in front
+ * with no sheet for 1.2 s, or `until` visible, or `waitMs` over. Reads alerts every 100 ms for the first second, every
+ * 250 ms after. While another app (SpringBoard, Safari) is in front no sheet-free verdict is reached, so it waits on.
+ */
+export declare function waitForLink(deps: LinkDeps, plan: LinkPlan): Promise<void>;

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

@@ -0,0 +1,90 @@
+import { type DeviceDevtools } from "./device-devtools";
+import type { Driver, Orientation } from "./driver/driver.types";
+import { type SettleDetail } from "./driver/settle";
+import type { E2eEnv } from "./env";
+import { type Clock, type FixtureSession } from "./fixture-session";
+import { type DevicePerf, type PerfExec } from "./perf/device-perf";
+import type { Locator } from "./screen/locator";
+export type AlertAction = "accept" | "dismiss" | {
+    button: string;
+};
+export type OpenLinkOptions = {
+    /** answer iOS's "Open in …?" sheet with "Open". Default true. */
+    accept?: boolean;
+    /**
+     * Return as soon as this locator is visible and no sheet is up, instead of when the link is known to be handled.
+     * Use it when the link leads to a screen the app is not already showing; the wait still ends at `waitMs`
+     * (without an error: the next assertion reports the missing screen).
+     */
+    until?: Locator;
+    /** The longest `openLink` waits, in ms. Default 8000. */
+    waitMs?: number;
+};
+export type SnapshotTextOptions = {
+    interactiveOnly?: boolean;
+};
+export type SettleOptions = {
+    /** how long the UI must stay unchanged. Default 250 ms. */
+    quietMs?: number;
+    /** give up after this long. Default 3000 ms. */
+    timeout?: number;
+};
+export type Device = {
+    /**
+     * Answers the system alert / sheet on top. `accept` presses the first present of OK, Allow, Open,
+     * Continue, Yes, Done, Allow While Using App, Allow Once (else the last button); `dismiss` the first
+     * of Cancel, Don't Allow, Not Now, Dismiss, No, Close (else the first button); `{button}` the button
+     * with that name (`ACTION_FAILED` when absent). Resolves false when no alert is showing.
+     */
+    alert(action: AlertAction): Promise<boolean>;
+    /**
+     * Opens a URL from outside the app. On iOS it accepts the "Open in …?" sheet when one shows (pressing again if it
+     * stays up) and returns once the link is handled: the sheet was answered, or none showed for 1.2 s while the app is
+     * in front (so a link without a sheet costs about 1.3 s, and later links with the same scheme in this session return
+     * as soon as the app is in front). While another app (SpringBoard, Safari) is in front it keeps looking for the sheet
+     * for up to `waitMs` (8 s). Pass `until` to return when the target screen is visible.
+     */
+    openLink(url: string, options?: OpenLinkOptions): Promise<void>;
+    home(): Promise<void>;
+    /** Android back key; `INVALID_ARGUMENT` on iOS (there is none). */
+    back(): Promise<void>;
+    orientation(set?: Orientation): Promise<Orientation>;
+    appearance(set?: "light" | "dark"): Promise<"light" | "dark">;
+    clipboard(): Promise<string>;
+    setClipboard(text: string): Promise<void>;
+    /**
+     * Dismisses the soft keyboard when the snapshot shows one, else does nothing. iOS presses Enter
+     * (which may submit the focused field); Android presses back.
+     */
+    hideKeyboard(): Promise<void>;
+    /** Saves `<attemptDir>/screenshots/NNN-<name>.png` and returns the path. */
+    screenshot(name: string): Promise<string>;
+    /** The accessibility tree as text (`warden ui snapshot` format). */
+    snapshot(options?: SnapshotTextOptions): Promise<string>;
+    /**
+     * Waits for a quiet UI: the driver's own settle, else snapshot-hash polling. Resolves `{ quiet, waitedMs }` and,
+     * when known, how it decided: `via` (`stream`: the app's run loop went idle; `snapshot`: the helper fell back to
+     * comparing screens; `hash`: warden polled snapshot hashes, always on Android), a `reason` for a not-quiet end
+     * (`frontmost_mismatch`: the launched app never came to the front) and the `frontmostPid` the helper saw.
+     */
+    settle(options?: SettleOptions): Promise<SettleDetail>;
+    /**
+     * The app's JS runtime over Metro (evaluate, React tree, console, network, reload); `undefined` without
+     * `WARDEN_METRO_URL` (a release build). The first access starts attaching, so console capture begins there.
+     */
+    readonly devtools: DeviceDevtools | undefined;
+    /**
+     * Perf profiling of the app (`warden perf` over the CLI that started the run): `start`, `mark`, then `stop` for the
+     * typed report. The report is copied under the attempt's `perf/`; budgets from `warden.config.ts` fail `stop`.
+     */
+    readonly perf: DevicePerf;
+};
+export type DeviceDeps = {
+    session: FixtureSession;
+    driver: Driver;
+    env: E2eEnv;
+    clock?: Clock;
+    /** runs `warden …` for `device.perf`; default spawns `WARDEN_BIN` */
+    perfExec?: PerfExec;
+};
+export declare function createDevice({ session, driver, env, clock, perfExec }: DeviceDeps): Device;

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { type DevtoolsResult, type ExceptionDetails } from "./devtools.types";
+export type CdpOptions = {
+    /** injectable for tests; defaults to the global one */
+    WebSocket?: typeof WebSocket;
+    /** connect timeout and the default per-request timeout */
+    timeoutMs?: number;
+};
+export type CdpClient = {
+    /** `Runtime.evaluate`-style JSON-RPC call; resolves with the reply's `result`. */
+    send: (method: string, params?: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+    }) => Promise<DevtoolsResult<unknown>>;
+    /** Subscribe to a CDP event by method name; returns the unsubscribe function. */
+    on: (event: string, handler: (params: unknown) => void) => () => void;
+    /** Called when the socket closes on its own (not after `close()`). */
+    onClose: (handler: () => void) => () => void;
+    /** Every event of every method, in arrival order (a wildcard `on`). */
+    onAny: (handler: (method: string, params: unknown) => void) => () => void;
+    /**
+     * `Runtime.addBinding`, then probe `typeof <name>`: legacy Hermes (RN <= 0.72) acknowledges the call but never
+     * installs the function, so `available` is false and `evaluateWithBinding` is refused.
+     */
+    addBinding: (name: string) => Promise<DevtoolsResult<{
+        available: boolean;
+    }>>;
+    /**
+     * Run `script` (which must call the binding with JSON carrying `requestId`) and resolve with the parsed payload of
+     * the matching `Runtime.bindingCalled`.
+     */
+    evaluateWithBinding: (script: string, requestId: string, timeoutMs?: number) => Promise<DevtoolsResult<unknown>>;
+    /** `undefined` until `addBinding` ran */
+    readonly bindingAvailable: boolean | undefined;
+    close: () => void;
+};
+export declare const exceptionDetailsSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    lineNumber: z.ZodOptional<z.ZodNumber>;
+    columnNumber: z.ZodOptional<z.ZodNumber>;
+    url: z.ZodOptional<z.ZodString>;
+    exception: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        subtype: z.ZodOptional<z.ZodString>;
+        className: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Parse the `exceptionDetails` of a `Runtime.evaluate` reply, if it has one. */
+export declare function readEvaluateReply(reply: unknown): {
+    value: unknown;
+    type: string | undefined;
+    exceptionDetails: ExceptionDetails | undefined;
+};
+/** One line for a JS exception: the error's `description` (`Name: message` + stack), else the CDP text. */
+export declare function describeException(details: ExceptionDetails): string;
+/**
+ * The `Origin` Metro's inspector proxy requires: it rejects a debugger upgrade with no Origin (the 401 a bare
+ * `new WebSocket(url)` gets) and accepts its own base URL or a local hostname. Always the 127.0.0.1 origin of the
+ * socket's port: verified live against Expo's Metro, where `http://localhost:<port>` is accepted by the handshake
+ * but the socket is then dropped (1006), while `http://127.0.0.1:<port>` works whatever host the socket dials.
+ */
+export declare function inspectorOrigin(wsUrl: string): string | undefined;
+/** Open a CDP JSON-RPC session over a WebSocket (Metro's `/inspector/debug`). */
+export declare function openCdp(wsUrl: string, options?: CdpOptions): Promise<DevtoolsResult<CdpClient>>;

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

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { CdpTap, ConsoleLine } from "./devtools.types";
+import type { DevtoolsSession } from "./session";
+declare const remoteObjectSchema: z.ZodObject<{
+    type: z.ZodString;
+    subtype: z.ZodOptional<z.ZodString>;
+    className: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodUnknown>;
+    unserializableValue: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodObject<{
+        subtype: z.ZodOptional<z.ZodString>;
+        overflow: z.ZodOptional<z.ZodBoolean>;
+        properties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            subtype: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type RemoteObject = z.infer<typeof remoteObjectSchema>;
+/** The text of a console call and each argument rendered separately. */
+export declare function formatConsoleArgs(args: readonly RemoteObject[]): {
+    text: string;
+    args: string[];
+};
+export type ConsoleOptions = {
+    /** lines kept (default 500) */
+    ring?: number;
+    /** called with every line as it is recorded, including marks */
+    sink?: (line: ConsoleLine) => void;
+    now?: () => number;
+};
+export type ConsoleCapture = {
+    /** feed it CDP events (a session tap) */
+    handle: CdpTap;
+    lines: () => ConsoleLine[];
+    /** empties the buffer; replayed old lines are still recognised afterwards */
+    clear: () => void;
+    /** inserts a `note` line, to find a point in time in the log */
+    mark: (label: string) => void;
+    writeJsonl: (path: string) => Promise<void>;
+};
+/**
+ * Collect `Runtime.consoleAPICalled` / `Runtime.exceptionThrown` into a ring.
+ *
+ * Replay: Hermes keeps a buffer of recent console messages and sends it again on every `Runtime.enable`, so
+ * each (re)connect re-delivers old lines. Events flagged `replay` (they arrived during the connect handshake)
+ * are matched against what was recorded earlier by `(timestamp, text)` with counts, so a burst of identical
+ * lines is kept once per real occurrence. Live events are never de-duplicated: a loop may log the same text
+ * within one millisecond.
+ */
+export declare function createConsoleCapture(options?: ConsoleOptions): ConsoleCapture;
+/** Capture a connected session's console from now on. `detach()` stops it. */
+export declare function attachConsole(session: DevtoolsSession, options?: ConsoleOptions): ConsoleCapture & {
+    detach: () => void;
+};
+export {};