---
title: JavaScript API Reference
description: Every method in the Vibium JavaScript client with its typed signature, and the matching CLI command and MCP tool.
tableOfContents:
  maxHeadingLevel: 2
---

<!-- Generated by scripts/gen_api_reference.py from docs/reference/api.md and the nightly packages in VibiumDev/vibium. Do not edit. -->

All 186 entries of the JavaScript client API, grouped by object. Each
entry shows the signature from the client's own source, then the
matching CLI command and MCP tool where one exists.

Entries marked **(nightly)** are not in the latest release (26.11.16);
**(changed in nightly)** means the documented signature differs from that release.
Signatures come from the latest nightly build. See
[What's in Nightly](../../nightly.md). The same data for every surface
is in the [API matrix](../../reference/api-matrix.md) and in
[`/api.json`](/api.json).

Examples assume `bro` is a started browser and `vibe` is its page, as in the
[quickstart](index.md).

## Browser

**`browser.start(opts?)`**

Launch browser and connect

`start(urlOrOptions?: string | StartOptions, options?: StartOptions): Promise<Browser>;`

Example: `const bro = await browser.start({ headless: true })`

CLI `vibium start` · MCP `browser_start`

**`browser.page()`**

Get the default page

`page(): Promise<Page>;`

Get the default page (first browsing context).

Example: `const vibe = await bro.page()`

**`browser.newPage()`**

Create a new page

`newPage(): Promise<Page>;`

Create a new page (tab) in the default context.

Example: `const second = await bro.newPage()`

CLI `vibium page new` · MCP `browser_new_page`

**`browser.newContext()`**

Create a new browser context

`newContext(): Promise<BrowserContext>;`

Create a new browser context (isolated, incognito-like).

**`browser.pages()`**

List all pages

`pages(): Promise<Page[]>;`

Get all open pages.

CLI `vibium pages` · MCP `browser_list_pages`

**`browser.stop()`**

Stop the browser

`stop(): Promise<void>;`

Stop the browser and clean up.

Example: `await bro.stop()`

CLI `vibium stop` · MCP `browser_stop`

**`browser.onPage(cb)`**

Listen for new page events

`onPage(callback: (page: Page) => void): void;`

Register a callback for when a new page is created (e.g. new tab).

**`browser.onPopup(cb)`**

Listen for popup events

`onPopup(callback: (page: Page) => void): void;`

Register a callback for when a popup is opened (window.open or target=_blank).

**`browser.removeAllListeners(ev?)`**

Remove all event listeners

`removeAllListeners(event?: 'page' | 'popup'): void;`

Remove all listeners for a given event, or all events if no event specified. Supported events: 'page', 'popup'.

## Page

**`page.go(url)`**

Navigate to a URL

`go(url: string): Promise<void>;`

Example: `await vibe.go('https://example.com')`

CLI `vibium go <url>` · MCP `browser_navigate`

**`page.back()`**

Go back

`back(): Promise<void>;`

Navigate back in history.

Example: `await vibe.back()`

CLI `vibium back` · MCP `browser_back`

**`page.forward()`**

Go forward

`forward(): Promise<void>;`

Navigate forward in history.

CLI `vibium forward` · MCP `browser_forward`

**`page.reload()`**

Reload page

`reload(): Promise<void>;`

Reload the page.

Example: `await vibe.reload()`

CLI `vibium reload` · MCP `browser_reload`

**`page.url()`**

Get current URL

`url(): Promise<string>;`

Get the current page URL.

Example: `const url = await vibe.url()`

CLI `vibium url` · MCP `browser_get_url`

**`page.title()`**

Get page title

`title(): Promise<string>;`

Get the current page title.

Example: `const title = await vibe.title()`

CLI `vibium title` · MCP `browser_get_title`

**`page.content()`**

Get page HTML

`content(): Promise<string>;`

Get the full HTML content of the page.

Example: `const html = await vibe.content()`

**`page.find(locator, opts?)`**

Find a single element by description (a bare string), css, tag, semantic locator, or reference image; strategy auto, cv, vlm, or tree

`find(selector: string | SelectorOptions, options?: FindOptions): FluentElement;`

Find an element. A string is a natural-language description; an options object gives an exact locator (css, tag, role, text, ...) or a reference image. Waits for the element to exist.

Example: `const button = await vibe.find({ role: 'button', text: 'Submit' })`

CLI `vibium find <description>` · MCP `browser_find`

**`page.findAll(locator, opts?)`**

Find all matching elements, same locator forms

`findAll(selector: string | SelectorOptions, options?: FindOptions): Promise<Element[]>;`

Find all elements matching a description, image, css, or semantic options. Waits up to the timeout for at least one match, then returns an empty array if there is none. A timeout of 0 checks once without waiting. Each element carries a snapshot of its tag, text, and box taken at findAll time, readable via `el.info` with no further round trips: els.map(el =\> el.info.text). Live reads like el.text() re-resolve the element and fail if the page has changed since findAll.

Example: `const links = await vibe.findAll({ role: 'link' })`

CLI `vibium find --all <description>` · MCP `browser_find_all`

**`page.screenshot(opts?)`**

Take a page screenshot

`screenshot(options?: ScreenshotOptions): Promise<Buffer>;`

Take a screenshot of the page. Returns a PNG buffer.

Example: `fs.writeFileSync('page.png', await vibe.screenshot())`

CLI `vibium screenshot` · MCP `browser_screenshot`

**`page.pdf(opts?)`**

Generate PDF

`pdf(options?: PdfOptions): Promise<Buffer>;`

Print the page to PDF. Returns a PDF buffer. Only works in headless mode.

CLI `vibium pdf` · MCP `browser_pdf`

**`page.evaluate(expr)`**

Evaluate JavaScript

`evaluate<T = unknown>(expression: string | (() => T | Promise<T>)): Promise<T>;`

Evaluate a JS expression string or argless function and return the deserialized value.

Example: `const count = await vibe.evaluate('document.links.length')`

CLI `vibium eval <expr>` · MCP `browser_evaluate`

**`page.addScript(src)`**

Add a script tag

`addScript(source: string): Promise<void>;`

Inject a script into the page. Pass a URL or inline JavaScript.

**`page.addStyle(src)`**

Add a style tag

`addStyle(source: string): Promise<void>;`

Inject a stylesheet into the page. Pass a URL or inline CSS.

**`page.expose(name, fn)`**

Expose a function to the page

`expose(name: string, fn: string | ((...args: unknown[]) => unknown)): Promise<void>;`

Expose a function on window. Pass a function to expose a host callback: the page calls window\[name\](...args), this function runs here, and its return value resolves the page's promise. Arguments and results cross as JSON. Pass a string to inject it as JS source instead, defining window\[name\] inside the page. Either form survives navigation, and re-exposing a name replaces it.

**`page.wait(ms)`**

Wait for a duration

`wait(ms: number): Promise<void>;`

Wait for a fixed amount of time (milliseconds). Discouraged but useful for debugging.

CLI `vibium sleep <ms>` · MCP `browser_sleep`

**`page.waitForFunction(fn, opts?)`**

Wait for JS function to return truthy

```text
waitForFunction(fn: string, options?: {
    timeout?: number;
}): Promise<unknown>;
```

Wait until a function returns a truthy value.

Example: `await vibe.waitForFunction('document.readyState === "complete"')`

CLI `vibium wait fn <expr>` · MCP `browser_wait_for_fn`

**`page.waitForURL(url, opts?)`**

Wait for URL to match

```text
waitForURL(pattern: string, options?: {
    timeout?: number;
}): Promise<void>;
```

Wait until the page URL matches a pattern.

Example: `await vibe.waitForURL('**/next')`

CLI `vibium wait url <pat>` · MCP `browser_wait_for_url`

**`page.waitForLoad(opts?)`**

Wait for page load

```text
waitForLoad(state?: string, options?: {
    timeout?: number;
}): Promise<void>;
```

Wait until the page reaches a load state.

Example: `await vibe.waitForLoad()`

CLI `vibium wait load` · MCP `browser_wait_for_load`

**`page.scroll(dir?, amt?, sel?)`**

Scroll the page

`scroll(direction?: string, amount?: number, selector?: string): Promise<void>;`

Scroll the page in a direction.

CLI `vibium scroll <dir> <amt>` · MCP `browser_scroll`

**`page.setViewport(size)`**

Set viewport size

```text
setViewport(size: {
    width: number;
    height: number;
}): Promise<void>;
```

Set the viewport size.

Example: `await vibe.setViewport({ width: 375, height: 812 })`

CLI `vibium viewport <w> <h>` · MCP `browser_set_viewport`

**`page.viewport()`**

Get viewport size

```text
viewport(): Promise<{
    width: number;
    height: number;
}>;
```

Get the current viewport size.

CLI `vibium viewport` · MCP `browser_get_viewport`

**`page.emulateMedia(opts)`**

Override CSS media features

```text
emulateMedia(opts: {
    media?: 'screen' | 'print' | null;
    colorScheme?: 'light' | 'dark' | 'no-preference' | null;
    reducedMotion?: 'reduce' | 'no-preference' | null;
    forcedColors?: 'active' | 'none' | null;
    contrast?: 'more' | 'no-preference' | null;
}): Promise<void>;
```

Override CSS media features (colorScheme, reducedMotion, forcedColors, contrast, media type).

CLI `vibium media <scheme>` · MCP `browser_emulate_media`

**`page.setContent(html)`**

Set page HTML

`setContent(html: string): Promise<void>;`

Replace the page HTML content.

Example: `await vibe.setContent('<h1>Hello</h1>')`

CLI `vibium content <html>` · MCP `browser_set_content`

**`page.setGeolocation(coords)`**

Override geolocation

```text
setGeolocation(coords: {
    latitude: number;
    longitude: number;
    accuracy?: number;
}): Promise<void>;
```

Override the browser's geolocation.

CLI `vibium geolocation <lat> <lon>` · MCP `browser_set_geolocation`

**`page.setWindow(opts)`**

Set window size/position

```text
setWindow(options: {
    width?: number;
    height?: number;
    x?: number;
    y?: number;
    state?: 'normal' | 'maximized' | 'minimized' | 'fullscreen';
}): Promise<void>;
```

Set the OS browser window size, position, or state.

CLI `vibium window <opts>` · MCP `browser_set_window`

**`page.window()`**

Get window info

```text
window(): Promise<{
    state: string;
    width: number;
    height: number;
    x: number;
    y: number;
}>;
```

Get the current OS browser window state and dimensions.

CLI `vibium window` · MCP `browser_get_window`

**`page.a11yTree(opts?)`**

Get accessibility tree

```text
a11yTree(options?: {
    everything?: boolean;
    root?: string;
}): Promise<A11yNode>;
```

Get the accessibility tree for the page.

Example: `const tree = await vibe.a11yTree()`

CLI `vibium a11y-tree` · MCP `browser_a11y_tree`

**`page.frames()`**

List all frames

`frames(): Promise<Page[]>;`

Get all child frames of this page (recursive, flattened).

CLI `vibium frames` · MCP `browser_frames`

**`page.frame(nameOrUrl)`**

Get a frame by name/URL

`frame(nameOrUrl: string): Promise<Page | null>;`

Find a frame by name attribute or URL substring. Returns null if not found.

CLI `vibium frame <ref>` · MCP `browser_frame`

**`page.mainFrame()`**

Get the main frame

`mainFrame(): Page;`

Returns this page — the page IS its own main frame.

**`page.bringToFront()`**

Bring page to front

`bringToFront(): Promise<void>;`

Bring this page/tab to the foreground.

CLI `vibium page switch <idx>` · MCP `browser_switch_page`

**`page.close()`**

Close the page

`close(): Promise<void>;`

Close this page/tab.

CLI `vibium page close` · MCP `browser_close_page`

**`page.route(pattern, handler)`**

Register a route handler

`route(pattern: string, handler: (route: Route) => void): Promise<void>;`

Intercept network requests matching a URL pattern. The handler receives a Route object that can fulfill, continue, or abort the request.

**`page.unroute(pattern)`**

Remove a route handler

`unroute(pattern: string): Promise<void>;`

Remove a previously registered route. If no handler given, removes all routes for the pattern.

**`page.setHeaders(headers)`**

Set extra HTTP headers

`setHeaders(headers: Record<string, string>): Promise<void>;`

Set extra HTTP headers for all requests in this page.

**`page.onRequest(fn)`**

Listen for requests

`onRequest(fn: (request: Request) => void): void;`

Register a callback for every outgoing request.

Example: `vibe.onRequest((req) => console.log(req.method(), req.url()))`

**`page.onResponse(fn)`**

Listen for responses

`onResponse(fn: (response: Response) => void): void;`

Register a callback for every completed response.

Example: `vibe.onResponse((resp) => console.log(resp.status(), resp.url()))`

**`page.onDialog(fn)`**

Listen for dialogs

`onDialog(handler: (dialog: Dialog) => void): void;`

Register a handler for browser dialogs (alert, confirm, prompt). If no handler is registered, dialogs are automatically dismissed.

**`page.onConsole(fn)`**

Listen for console messages

`onConsole(handler: ((message: ConsoleMessage) => void) | 'collect'): void;`

Register a handler for console messages, or pass 'collect' to buffer them for consoleMessages().

Example: `vibe.onConsole((msg) => console.log(msg.type(), msg.text()))`

**`page.onError(fn)`**

Listen for page errors

`onError(handler: ((error: Error) => void) | 'collect'): void;`

Register a handler for uncaught page errors, or pass 'collect' to buffer them for errors().

**`page.onDownload(fn)`**

Listen for downloads

`onDownload(handler: (download: Download) => void): void;`

Register a handler for file downloads.

**`page.onWebSocket(fn)`**

Subscribe to WebSocket events

`onWebSocket(fn: (ws: WebSocketInfo) => void): void;`

Listen for WebSocket connections opened by the page. Monitoring is installed in the engine before the next command on this connection is sent, so a socket opened by the very next call cannot be missed (#351).

**`page.removeAllListeners(ev?)`**

Remove all event listeners

`removeAllListeners(event?: 'request' | 'response' | 'dialog' | 'console' | 'error' | 'download' | 'navigation' | 'websocket'): void;`

Remove all listeners for a given event, or all events if no event specified. Supported events: 'request', 'response', 'dialog', 'console', 'error', 'download', 'websocket'.

**`page.capture.response(pat, fn?)`**

Capture response (before action)

```text
response(pattern: string, fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<Response>;
```

Capture a response matching a URL pattern. Optionally pass fn to trigger the action.

Example: `const resp = await vibe.capture.response('**/api/users', () => vibe.find({ role: 'button', text: 'Users' }).click())`

**`page.capture.request(pat, fn?)`**

Capture request (before action)

```text
request(pattern: string, fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<Request>;
```

Capture a request matching a URL pattern. Optionally pass fn to trigger the action.

**`page.capture.navigation(fn?)`**

Capture navigation (before action)

```text
navigation(fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<string>;
```

Capture a navigation event. Optionally pass fn to trigger the action. Resolves with URL.

**`page.capture.event(name, fn?)`**

Capture event (before action)

```text
event(name: string, fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<unknown>;
```

Capture a named event. Optionally pass fn to trigger the action.

**`page.capture.download(fn?)`**

Capture download (before action)

```text
download(fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<Download>;
```

Capture a download. Optionally pass fn to trigger the action.

Example: `const download = await vibe.capture.download(() => vibe.find({ role: 'link', text: 'Download' }).click())`

**`page.capture.dialog(fn?)`**

Capture dialog (before action)

```text
dialog(fn?: () => Promise<void>, options?: {
    timeout?: number;
}): Promise<Dialog>;
```

Capture a dialog. Optionally pass fn to trigger the action.

**`page.consoleMessages()`**

Get buffered console messages

```text
consoleMessages(): {
    type: string;
    text: string;
}[];
```

Return collected console messages and clear the buffer. Returns \[\] if not collecting.

**`page.errors()`**

Get buffered page errors

```text
errors(): {
    message: string;
}[];
```

Return collected errors and clear the buffer. Returns \[\] if not collecting.

**`page.context`**

Owning browser context

`get context(): BrowserContext;`

The parent BrowserContext that owns this page.

**`page.id`**

Browsing context id

`get id(): string;`

The browsing context ID for this page.

**`page.capture`**

One-shot capture namespace

```text
readonly capture: {
    /** Capture a response matching a URL pattern. Optionally pass fn to trigger the action. */
    response(pattern: string, fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<Response>;
    /** Capture a request matching a URL pattern. Optionally pass fn to trigger the action. */
    request(pattern: string, fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<Request>;
    /** Capture a navigation event. Optionally pass fn to trigger the action. Resolves with URL. */
    navigation(fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<string>;
    /** Capture a download. Optionally pass fn to trigger the action. */
    download(fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<Download>;
    /** Capture a dialog. Optionally pass fn to trigger the action. */
    dialog(fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<Dialog>;
    /** Capture a named event. Optionally pass fn to trigger the action. */
    event(name: string, fn?: () => Promise<void>, options?: {
        timeout?: number;
    }): Promise<unknown>;
};
```

Capture namespace — set up a listener before performing an action.

**`page.keyboard`**

Keyboard input for the page

`readonly keyboard: Keyboard;`

Page-level keyboard input.

**`page.mouse`**

Mouse input for the page

`readonly mouse: Mouse;`

Page-level mouse input.

**`page.touch`**

Touch input for the page

`readonly touch: Touch;`

Page-level touch input.

**`page.clock`**

Clock control for the page

`readonly clock: Clock;`

Page-level clock control for faking timers and Date.

**`page.waitUntil(fn, opts?)`**

Deprecated alias for the wait helpers

```text
readonly waitUntil: ((fn: string, options?: {
    timeout?: number;
}) => Promise<unknown>) & {
    /** @deprecated Use waitForURL(). */
    url(pattern: string, options?: {
        timeout?: number;
    }): Promise<void>;
    /** @deprecated Use waitForLoad(). */
    loaded(state?: string, options?: {
        timeout?: number;
    }): Promise<void>;
};
```

Wait until a condition is met. Callable with a function, or use .url() / .loaded() sub-methods. @deprecated Use waitForFunction(), waitForURL(), or waitForLoad().

***mode of onConsole('collect')***

Enable console collect mode

***mode of onError('collect')***

Enable error collect mode

**`page.routeWebSocket(pattern, fn)`**

Intercept WebSockets (unsupported: throws)

`routeWebSocket(_pattern: string, _handler: unknown): never;`

Intercept WebSocket connections. Not supported by BiDi.

## Element

**`el.click(opts?)`**

Click an element

`click(options?: ActionOptions): Promise<void>;`

Click the element. Waits for element to be visible, stable, receive events, and enabled.

Example: `await vibe.find({ role: 'button', text: 'Submit' }).click()`

CLI `vibium click <sel>` · MCP `browser_click`

**`el.dblclick(opts?)`**

Double-click an element

`dblclick(options?: ActionOptions): Promise<void>;`

Double-click the element.

CLI `vibium dblclick <sel>` · MCP `browser_dblclick`

**`el.fill(value, opts?)`**

Fill an input field

`fill(value: string, options?: ActionOptions): Promise<void>;`

Fill the element with text (clears existing content first). For inputs and textareas.

Example: `await vibe.find({ label: 'Email' }).fill('user@example.com')`

CLI `vibium fill <sel> <val>` · MCP `browser_fill`

**`el.type(text, opts?)`**

Type text character by character

`type(text: string, options?: ActionOptions): Promise<void>;`

Type text into the element (appends to existing content). Waits for element to be visible, stable, receive events, enabled, and editable.

Example: `await vibe.find({ label: 'Email' }).type('user@example.com')`

CLI `vibium type <text>` · MCP `browser_type`

**`el.press(key, opts?)`**

Press a key on focused element

`press(key: string, options?: ActionOptions): Promise<void>;`

Press a key while the element is focused. Supports key names ("Enter", "Tab") and combos ("Control+a").

Example: `await vibe.find({ label: 'Email' }).press('Enter')`

CLI `vibium press <key>` · MCP `browser_press`

**`el.clear(opts?)`**

Clear an input field

`clear(options?: ActionOptions): Promise<void>;`

Clear the element's content (select all + delete).

**`el.set(value?, opts?)`**

Check a checkbox

`set(value?: boolean, options?: ActionOptions): Promise<void>;`

Check a checkbox (no-op if already checked).

Example: `await vibe.find({ css: 'input[type="checkbox"]' }).set()`

CLI `vibium set <sel>` · MCP `browser_set`

**`el.unset(opts?)`**

Uncheck a checkbox

`unset(options?: ActionOptions): Promise<void>;`

Uncheck a checkbox (no-op if already unchecked).

CLI `vibium unset <sel>` · MCP `browser_unset`

**`el.selectOption(val, opts?)`**

Select a dropdown option

`selectOption(value: string, options?: ActionOptions): Promise<void>;`

Select an option in a \<select\> element by value.

Example: `await vibe.find({ label: 'Country' }).selectOption('de')`

CLI `vibium select <sel> <val>` · MCP `browser_select`

**`el.hover(opts?)`**

Hover over an element

`hover(options?: ActionOptions): Promise<void>;`

Hover over the element (move mouse to center, no click).

Example: `await vibe.find({ role: 'button', text: 'Menu' }).hover()`

CLI `vibium hover <sel>` · MCP `browser_hover`

**`el.focus(opts?)`**

Focus an element

`focus(options?: ActionOptions): Promise<void>;`

Focus the element.

CLI `vibium focus <sel>` · MCP `browser_focus`

**`el.dragTo(target, opts?)`**

Drag an element to a target

`dragTo(target: Element, options?: ActionOptions): Promise<void>;`

Drag this element to a target element.

CLI `vibium drag <sel> <x> <y>` · MCP `browser_drag`

**`el.tap(opts?)`**

Tap an element (touch)

`tap(options?: ActionOptions): Promise<void>;`

Tap the element (touch action).

**`el.scrollIntoView(opts?)`**

Scroll element into view

`scrollIntoView(options?: ActionOptions): Promise<void>;`

Scroll the element into view.

CLI `vibium scroll into-view <sel>` · MCP `browser_scroll_into_view`

**`el.dispatchEvent(type, init?)`**

Dispatch a DOM event

`dispatchEvent(eventType: string, eventInit?: Record<string, unknown>, options?: ActionOptions): Promise<void>;`

Dispatch a DOM event on the element.

**`el.setFiles(files, opts?)`**

Set files on a file input

`setFiles(files: string[], options?: ActionOptions): Promise<void>;`

Set files on an \<input type="file"\> element.

CLI `vibium upload <sel> <paths>` · MCP `browser_upload`

**`el.highlight()`**

Highlight an element

`highlight(options?: ActionOptions): Promise<void>;`

Highlight the element with a brief outline, for visual debugging.

CLI `vibium highlight <sel>` · MCP `browser_highlight`

**`el.text()`**

Get element text content

`text(): Promise<string>;`

Get the element's textContent (trimmed).

Example: `const heading = await vibe.find({ css: 'h1' }).text()`

CLI `vibium text <sel>` · MCP `browser_get_text`

**`el.innerText()`**

Get element inner text

`innerText(): Promise<string>;`

Get the element's innerText (rendered text only).

CLI `vibium text <sel>` · MCP `browser_get_text`

**`el.html()`**

Get element outer HTML

`html(): Promise<string>;`

Get the element's innerHTML.

CLI `vibium html <sel>` · MCP `browser_get_html`

**`el.value()`**

Get input element value

`value(): Promise<string>;`

Get the element's value (for inputs, textareas, selects).

Example: `const email = await vibe.find({ label: 'Email' }).value()`

CLI `vibium value <sel>` · MCP `browser_get_value`

**`el.attr(name)`**

Get element attribute

`attr(name: string): Promise<string | null>;`

Get an attribute value. Short name for getAttribute.

Example: `const href = await vibe.find({ role: 'link', text: 'Next' }).attr('href')`

CLI `vibium attr <sel> <name>` · MCP `browser_get_attribute`

**`el.bounds()`**

Get element bounding box

`bounds(): Promise<BoundingBox>;`

Get the element's bounding box. Short name for boundingBox.

**`el.boundingBox()`**

Bounding box (Playwright-compat alias for bounds)

`boundingBox(): Promise<BoundingBox>;`

Get the element's bounding box. Alias for bounds().

**`el.getAttribute(name)`**

Get attribute (alias for attr)

`getAttribute(name: string): Promise<string | null>;`

Get an attribute value. Alias for attr().

**`el.info`**

Find-time snapshot of tag, text, and box

`readonly info: ElementInfo;`

**`el.isVisible()`**

Check if element is visible

`isVisible(): Promise<boolean>;`

Check if the element is visible (has dimensions, not display:none/visibility:hidden/opacity:0).

Example: `const visible = await vibe.find({ role: 'button', text: 'Submit' }).isVisible()`

CLI `vibium is visible <sel>` · MCP `browser_is_visible`

**`el.isHidden()`**

Check if element is hidden

`isHidden(): Promise<boolean>;`

Check if the element is hidden (inverse of isVisible).

**`el.isEnabled()`**

Check if element is enabled

`isEnabled(): Promise<boolean>;`

Check if the element is enabled (not disabled).

CLI `vibium is enabled <sel>` · MCP `browser_is_enabled`

**`el.isSet()`**

Check if element is checked

`isSet(): Promise<boolean>;`

Check if the element is checked (for checkboxes/radios).

CLI `vibium is set <sel>` · MCP `browser_is_set`

**`el.isEditable()`**

Check if element is editable

`isEditable(): Promise<boolean>;`

Check if the element is editable (not disabled and not readonly).

**`el.role()`**

Get element ARIA role

`role(): Promise<string>;`

Get the element's computed ARIA role.

**`el.label()`**

Get element accessible label

`label(): Promise<string>;`

Get the element's accessible name (label).

**`el.screenshot()`**

Screenshot an element

`screenshot(): Promise<Buffer>;`

Take a screenshot of just this element. Returns a PNG buffer.

**`el.waitUntil(state?, opts?)`**

Wait for element state

```text
waitUntil(state?: string, options?: {
    timeout?: number;
}): Promise<void>;
```

Wait until the element reaches a state: "visible", "hidden", "attached", or "detached".

CLI `vibium wait <sel> --state <st>` · MCP `browser_wait`

**`el.find(sel, opts?)`**

Find a child element (scoped)

```text
find(selector: string | SelectorOptions, options?: {
    timeout?: number;
}): FluentElement;
```

Find a child element by CSS selector or semantic options. Scoped to this element.

Example: `const home = await (await vibe.find({ css: 'nav' })).find({ role: 'link', text: 'Home' })`

**`el.findAll(sel, opts?)`**

Find all child elements (scoped)

```text
findAll(selector: string | SelectorOptions, options?: {
    timeout?: number;
}): Promise<Element[]>;
```

Find all child elements by description, image, css, or semantic options. Scoped to this element.

## BrowserContext

**`context.newPage()`**

Create a page in a context

`newPage(): Promise<Page>;`

Create a new page (tab) in this context.

**`context.close()`**

Close the context

`close(): Promise<void>;`

Close this context and all its pages.

**`context.cookies(urls?)`**

Get cookies

`cookies(urls?: string[]): Promise<Cookie[]>;`

Get cookies for this context. Optionally filter by URLs.

CLI `vibium cookies` · MCP `browser_get_cookies`

**`context.setCookies(cookies)`**

Set cookies

`setCookies(cookies: SetCookieParam[]): Promise<void>;`

Set cookies in this context.

CLI `vibium cookies <n> <v>` · MCP `browser_set_cookie`

**`context.clearCookies()`**

Clear cookies

`clearCookies(): Promise<void>;`

Clear all cookies in this context.

CLI `vibium cookies clear` · MCP `browser_delete_cookies`

**`context.storage()`**

Get storage state

`storage(): Promise<StorageState>;`

Get the storage state (cookies + localStorage + sessionStorage).

CLI `vibium storage` · MCP `browser_storage_state`

**`context.setStorage(state)`**

Set storage state

`setStorage(state: StorageState): Promise<void>;`

Set the storage state (cookies + localStorage + sessionStorage).

MCP `browser_restore_storage`

**`context.clearStorage()`**

Clear all storage

`clearStorage(): Promise<void>;`

Clear all storage (cookies + localStorage + sessionStorage).

**`context.addInitScript(script)`**

Add an init script

`addInitScript(script: string): Promise<string>;`

Add an init script that runs before page scripts in this context.

**`context.id`**

User context id

`get id(): string;`

The user context ID for this browser context.

**`context.recording`**

Recording controls for the context

`readonly recording: Recording;`

## Keyboard

**`keyboard.press(key)`**

Press a key

`press(key: string): Promise<void>;`

Press and release a key. Supports combos like "Control+a".

Example: `await vibe.keyboard.press('Enter')`

CLI `vibium keys <keys>` · MCP `browser_keys`

**`keyboard.down(key)`**

Key down

`down(key: string): Promise<void>;`

Press a key down (without releasing).

**`keyboard.up(key)`**

Key up

`up(key: string): Promise<void>;`

Release a key.

**`keyboard.type(text)`**

Type text

`type(text: string): Promise<void>;`

Type a string of text character by character.

## Mouse

**`mouse.click(x, y, opts?)`**

Click at coordinates

`click(x: number, y: number): Promise<void>;`

Click at (x, y) coordinates.

CLI `vibium mouse click <x> <y>` · MCP `browser_mouse_click`

**`mouse.move(x, y, opts?)`**

Move mouse

`move(x: number, y: number): Promise<void>;`

Move mouse to (x, y) coordinates.

CLI `vibium mouse move <x> <y>` · MCP `browser_mouse_move`

**`mouse.down(opts?)`**

Mouse button down

`down(): Promise<void>;`

Press mouse button down.

CLI `vibium mouse down` · MCP `browser_mouse_down`

**`mouse.up(opts?)`**

Mouse button up

`up(): Promise<void>;`

Release mouse button.

CLI `vibium mouse up` · MCP `browser_mouse_up`

**`mouse.wheel(dx, dy)`**

Scroll mouse wheel

`wheel(deltaX: number, deltaY: number): Promise<void>;`

Scroll the mouse wheel at the current pointer position.

## Touch

**`touch.tap(x, y)`**

Tap at coordinates

`tap(x: number, y: number): Promise<void>;`

Tap at (x, y) coordinates.

CLI `vibium tap <x> <y>` · MCP `browser_tap`

**`touch.swipe(direction, opts?)`**

Swipe in a direction (up, down, left, right; from an edge or point; speed, hold) or between coordinates

- `swipe(direction: SwipeDirection, options?: SwipeOptions): Promise<void>;`
- `swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;`

Swipe in a direction, or from (x1, y1) to (x2, y2). The finger stays down for the move, so the gesture reads as a swipe/fling rather than two taps. swipe('up') // from the center, half the viewport swipe('up', { from: 'bottom', speed: 'fast' }) // phone home gesture via Roadie swipe(40, 100, 240, 100, 200) // coordinates, 200ms

CLI `vibium swipe <direction>` · MCP `browser_swipe`

**`touch.longPress(x, y, durationMs?)`**

Long-press at coordinates

`longPress(x: number, y: number, durationMs?: number): Promise<void>;`

Press and hold at (x, y) for durationMs before releasing (default 500).

CLI `vibium long-press <x> <y>` · MCP `browser_long_press`

## Clock

**`clock.install(opts?)`**

Install fake timers

`install(options?: ClockInstallOptions): Promise<void>;`

Install fake clock, overriding Date, setTimeout, setInterval, etc.

MCP `page_clock_install`

**`clock.fastForward(ticks)`**

Fast-forward time

`fastForward(ticks: number): Promise<void>;`

Jump forward by ticks ms, fire each due timer at most once.

MCP `page_clock_fast_forward`

**`clock.runFor(ticks)`**

Run timers for a duration

`runFor(ticks: number): Promise<void>;`

Advance ticks ms, firing all callbacks systematically (including interval reschedules).

MCP `page_clock_run_for`

**`clock.pauseAt(time)`**

Pause clock at a time

`pauseAt(time: number | string | Date): Promise<void>;`

Jump to a specific time and pause — no timers fire until resumed/advanced.

MCP `page_clock_pause_at`

**`clock.resume()`**

Resume clock

`resume(): Promise<void>;`

Resume real-time progression from current fake time.

MCP `page_clock_resume`

**`clock.setFixedTime(time)`**

Set fixed fake time

`setFixedTime(time: number | string | Date): Promise<void>;`

Freeze Date.now() at a value permanently. Timers still run.

MCP `page_clock_set_fixed_time`

**`clock.setSystemTime(time)`**

Set system time

`setSystemTime(time: number | string | Date): Promise<void>;`

Set Date.now() without triggering timers.

MCP `page_clock_set_system_time`

**`clock.setTimezone(tz)`**

Set timezone

`setTimezone(timezone: string): Promise<void>;`

Override the browser timezone. Pass an IANA timezone ID, or empty string to reset to system default.

MCP `page_clock_set_timezone`

## Recording

**`recording.start(opts?)`**

Start recording

`start(options?: RecordingStartOptions): Promise<void>;`

CLI `vibium record start` · MCP `browser_record_start`

**`recording.stop(opts?)`**

Stop recording, return trace

`stop(options?: RecordingStopOptions): Promise<RecordingResult>;`

Stop recording and deliver the zip to the declared path. The result carries where it landed and what it holds; the zip bytes are included only for bytes-only recordings (start path: null).

CLI `vibium record stop` · MCP `browser_record_stop`

**`recording.startChunk(opts?)`**

Start a recording chunk

```text
startChunk(options?: {
    name?: string;
    title?: string;
}): Promise<void>;
```

Start a new recording chunk (resets event buffer, keeps resources).

CLI `vibium record chunk start` · MCP `browser_record_start_chunk`

**`recording.stopChunk(opts?)`**

Stop a recording chunk

`stopChunk(options?: RecordingStopOptions): Promise<RecordingResult>;`

Stop the current chunk. The result carries the path it was written to, or the chunk's bytes when no path was given.

CLI `vibium record chunk stop` · MCP `browser_record_stop_chunk`

**`recording.startGroup(name, opts?)`**

Start a logical group

```text
startGroup(name: string, options?: {
    location?: {
        file: string;
        line?: number;
        column?: number;
    };
}): Promise<void>;
```

Start a named group of actions in the recording.

CLI `vibium record group start <name>` · MCP `browser_record_start_group`

**`recording.stopGroup()`**

Stop a logical group

`stopGroup(): Promise<void>;`

End the current group.

CLI `vibium record group stop` · MCP `browser_record_stop_group`

## Route

**`route.request` (property)**

Access intercepted request

`readonly request: Request;`

**`route.fulfill(resp?)`**

Fulfill an intercepted request

```text
fulfill(response?: {
    status?: number;
    headers?: Record<string, string>;
    contentType?: string;
    body?: string;
}): Promise<void>;
```

Fulfill the request with a custom response (mock response).

**`route.continue(overrides?)`**

Continue an intercepted request

```text
continue(overrides?: {
    url?: string;
    method?: string;
    headers?: Record<string, string>;
    postData?: string;
}): Promise<void>;
```

Continue the request with optional overrides.

**`route.abort()`**

Abort an intercepted request

`abort(): Promise<void>;`

Abort the request.

## Dialog

**`dialog.message()`**

Get dialog message

`message(): string;`

The dialog message text.

**`dialog.type()`**

Get dialog type

`type(): string;`

The dialog type: 'alert', 'confirm', 'prompt', or 'beforeunload'.

**`dialog.defaultValue()`**

Get dialog default value

`defaultValue(): string;`

The default value for prompt dialogs.

**`dialog.accept(promptText?)`**

Accept the dialog

`accept(promptText?: string): Promise<void>;`

Accept the dialog. For prompt dialogs, optionally provide text.

CLI `vibium dialog accept` · MCP `browser_dialog_accept`

**`dialog.dismiss()`**

Dismiss the dialog

`dismiss(): Promise<void>;`

Dismiss the dialog (cancel/close).

CLI `vibium dialog dismiss` · MCP `browser_dialog_dismiss`

## Download

**`download.saveAs(path)`**

Save a download to path

`saveAs(path: string): Promise<void>;`

Wait for the download to complete, then save to the specified path.

**`download.url()`**

Get download URL

`url(): string;`

The URL of the download.

**`download.suggestedFilename()`**

Get download filename

`suggestedFilename(): string;`

The filename suggested by the server (from Content-Disposition).

**`download.path()`**

Get download path

`path(): Promise<string | null>;`

Wait for the download to complete and return the temp file path, or null if failed.

## Request

**`request.url()`**

Get request URL

`url(): string;`

The request URL.

**`request.method()`**

Get HTTP method

`method(): string;`

The HTTP method (GET, POST, etc.).

**`request.headers()`**

Get request headers

`headers(): Record<string, string>;`

Request headers as a simple key-value object.

**`request.requestId()`**

Get BiDi request ID

`requestId(): string;`

The request ID (BiDi network request identifier).

**`request.postData()`**

Get request body

`postData(): Promise<string | null>;`

Request body / post data. Uses BiDi network.getData when a data collector is active.

## Response

**`response.url()`**

Get response URL

`url(): string;`

The response URL.

**`response.status()`**

Get HTTP status

`status(): number;`

The HTTP status code.

**`response.headers()`**

Get response headers

`headers(): Record<string, string>;`

Response headers as a simple key-value object.

**`response.requestId()`**

Get associated request ID

`requestId(): string;`

The request ID associated with this response.

**`response.body()`**

Get response body

`body(): Promise<string | null>;`

Response body as a string. Requires a data collector (set up by onResponse/expect.response).

**`response.json()`**

Parse response body as JSON

`json(): Promise<unknown>;`

Response body parsed as JSON. Requires a data collector (set up by onResponse/expect.response).

## ConsoleMessage

**`message.type()`**

Get console message type

`type(): string;`

The console method: 'log', 'warn', 'error', 'debug', 'info', etc.

**`message.text()`**

Get formatted message text

`text(): string;`

The message text.

**`message.args()`**

Get console arguments

`args(): unknown[];`

The serialized arguments passed to the console call.

**`message.location()`**

Get source location

```text
location(): {
    url: string;
    lineNumber: number;
    columnNumber: number;
} | null;
```

The source location of the console call, if available.

## WebSocketInfo

**`socket.url()`**

Get WebSocket URL

`url(): string;`

**`socket.onMessage(fn)`**

Listen for messages

`onMessage(fn: MessageHandler): void;`

**`socket.onClose(fn)`**

Listen for close

`onClose(fn: CloseHandler): void;`

**`socket.isClosed()`**

Check whether socket is closed

`isClosed(): boolean;`

## Run and Check

**`browser.check(claim, opts?)`**

Independently verify the active session or a saved archive

`check(claim: string, options?: CheckOptions): Promise<CheckResult>;`

Independently verify this session, or inspect a saved archive.

CLI `vibium check <claim>` · MCP `vibium_check`

**`page.check(claim, opts?)`**

Independently verify a pinned page or a saved archive

`check(claim: string, options?: CheckOptions): Promise<CheckResult>;`

Verify this exact page, or inspect a read-only archive.

**`browser.run(goal, opts?)`**

Accomplish a goal in the active browser session

`run(goal: string, options?: RunOptions): Promise<RunResult>;`

Accomplish a live browser goal; provider settings are read in the runtime.

CLI `vibium run <goal>` · MCP `vibium_run`

**`page.run(goal, opts?)`**

Accomplish a goal on a pinned page

`run(goal: string, options?: RunOptions): Promise<RunResult>;`

Accomplish a live browser goal; provider settings are read in the runtime.

## Say and Listen

**`browser.say(text, opts?)`**

Speak text into the session, this machine's speakers, or a WAV file

`say(text: string, options?: SayOptions): Promise<SayResult>;`

Speak text into the current page's microphone, or into the device.

CLI `vibium say <text>` · MCP `vibium_say`

**`page.say(text, opts?)`**

Speak text into a pinned page

`say(text: string, options?: SayOptions): Promise<SayResult>;`

Speak text into this page's microphone, or into the device.

**`browser.listen(opts?)`**

Hear the session, this machine's microphone, or a WAV file, and return a transcript

`listen(options?: ListenOptions): Promise<ListenResult>;`

Hear what the current page, or the device, plays, and return its words.

CLI `vibium listen` · MCP `vibium_listen`

**`page.listen(opts?)`**

Hear a pinned page and return a transcript

`listen(options?: ListenOptions): Promise<ListenResult>;`

Hear what this page, or the device, plays, and return its words.

## Types

Option and result types named in the signatures above.

### `A11yNode`

```ts
interface A11yNode {
    role: string;
    name?: string;
    value?: string | number;
    description?: string;
    disabled?: boolean;
    expanded?: boolean;
    focused?: boolean;
    checked?: boolean | 'mixed';
    pressed?: boolean | 'mixed';
    selected?: boolean;
    required?: boolean;
    readonly?: boolean;
    level?: number;
    valuemin?: number;
    valuemax?: number;
    children?: A11yNode[];
}
```

### `ActionOptions`

```ts
interface ActionOptions {
    /** Timeout in milliseconds for actionability checks. Default: 30000 */
    timeout?: number;
}
```

### `BoundingBox`

```ts
interface BoundingBox {
    x: number;
    y: number;
    width: number;
    height: number;
}
```

### `Browser`

```ts
interface Browser {
    (goal: string, options?: RunOptions): Promise<RunResult>;
}
```

### `CheckOptions`

```ts
interface CheckOptions extends ModelOptions {
    /** Read-only archive on the runtime host. */
    record?: string;
    /** Site under test: opened first unless the current page already shares its
     * origin; relative navigation paths resolve against it. Not the AI provider
     * endpoint; that is aiBaseURL. */
    baseURL?: string;
}
```

### `CheckResult`

```ts
interface CheckResult {
    status: 'passed' | 'failed' | 'inconclusive';
    claim: string;
    summary: string;
    /** Machine-readable cause of an inconclusive verdict. */
    reason?: 'action_limit' | 'insufficient_evidence' | 'safety_stop' | 'archive_missing_evidence';
    evidence: {
        type: 'observation';
        summary: string;
    }[];
}
```

### `ClockInstallOptions`

```ts
interface ClockInstallOptions {
    time?: number | string | Date;
    timezone?: string;
}
```

### `CloseHandler`

```ts
type CloseHandler = (code?: number, reason?: string) => void;
```

### `Cookie`

```ts
interface Cookie {
    name: string;
    value: string;
    domain: string;
    path: string;
    size: number;
    httpOnly: boolean;
    secure: boolean;
    sameSite: string;
    expiry?: number;
}
```

### `ElementInfo`

```ts
interface ElementInfo {
    tag: string;
    text: string;
    box: BoundingBox;
    /** The @eN ref find registered; the CLI and MCP address the same element by it. */
    ref?: string;
    role?: string;
    /** Accessible name. */
    name?: string;
    /** What backs the match: dom, tree, image, or vlm. */
    source?: string;
    /** The DOM selector of a DOM-backed match. Absent for a visual region. */
    selector?: string;
    /** Diagnostics, when the find asked for details. */
    details?: Record<string, unknown>;
}
```

### `FindOptions`

```ts
interface FindOptions {
    /** Timeout in milliseconds to wait for element. Default: 30000 */
    timeout?: number;
}
```

### `FindStrategy`

```ts
type FindStrategy = 'auto' | 'cv' | 'vlm' | 'tree';
```

### `FluentElement`

```ts
type FluentElement = Promise<Element> & {
    click(options?: ActionOptions): Promise<void>;
```

### `ListenOptions`

```ts
interface ListenOptions extends SpeechOptions {
    /** Trailing silence that ends the reply, in ms. 0 turns endpointing off. Default 1000. */
    silence?: number;
    /** How long to wait for speech to start, from the call, in ms. Default 10000. */
    timeout?: number;
    /** Maximum capture length from the call, in ms. Default 30000. */
    duration?: number;
    /** Return an empty transcript instead of throwing when nothing is heard. */
    allowSilence?: boolean;
    /** Also save the captured audio as a WAV file. */
    path?: string;
    /** false captures without a transcript. Default true. */
    transcribe?: boolean;
}
```

### `ListenResult`

```ts
interface ListenResult {
    text: string;
    /** False when the capture was not sent to a provider. */
    transcribed: boolean;
    /** False when no speech was detected (only with allowSilence). */
    speech: boolean;
    /** Times are ms from the start of the capture. */
    segments: {
        startMs: number;
        endMs: number;
        text: string;
    }[];
    /** Present when the provider returns word timings. */
    words?: {
        startMs: number;
        endMs: number;
        word: string;
    }[];
    /** When speech started and ended in the capture. */
    onsetMs?: number;
    speechEndMs?: number;
    /** Speech onset minus the end of the preceding say. */
    latencyMs?: number;
    stoppedBy: 'silence' | 'duration' | 'eof' | 'timeout';
    /** Length of the captured audio. */
    durationMs: number;
    target: string;
    provider: string;
    model: string;
    path?: string;
    /** Audio the target dropped on its way here, in ms. The transcript may miss words. */
    lostMs?: number;
}
```

### `MessageHandler`

```ts
type MessageHandler = (data: string, info: {
    direction: 'sent' | 'received';
```

### `ModelOptions`

```ts
interface ModelOptions {
    provider?: 'openai' | 'xai' | 'anthropic' | 'google' | 'openai-compatible' | 'local';
    model?: string;
    /** The AI provider's API base URL (the model endpoint, not the site under
     * test). Empty string resets the endpoint to the provider default. */
    aiBaseURL?: string;
    /** Empty string clears an inherited effort. */
    reasoningEffort?: string;
}
```

### `OriginState`

```ts
interface OriginState {
    origin: string;
    localStorage: {
        name: string;
        value: string;
    }[];
    sessionStorage: {
        name: string;
        value: string;
    }[];
}
```

### `Page`

```ts
interface Page {
    (goal: string, options?: RunOptions): Promise<RunResult>;
}
```

### `PdfOptions`

```ts
interface PdfOptions {
    /** Landscape orientation (default: portrait). */
    landscape?: boolean;
    /** Print scale, 0.1-2 (default: 1). */
    scale?: number;
    /** Print background graphics (default: false). */
    background?: boolean;
    /** Top margin in cm (default: 1). */
    marginTop?: number;
    /** Bottom margin in cm (default: 1). */
    marginBottom?: number;
    /** Left margin in cm (default: 1). */
    marginLeft?: number;
    /** Right margin in cm (default: 1). */
    marginRight?: number;
    /** Page width in cm (default: 21.59). */
    pageWidth?: number;
    /** Page height in cm (default: 27.94). */
    pageHeight?: number;
    /** Pages to print, e.g. [1, '3-5'] (default: all). */
    pageRanges?: Array<number | string>;
    /** Shrink content to fit the page width (default: true). */
    shrinkToFit?: boolean;
}
```

### `RecordingResult`

```ts
interface RecordingResult {
    /** Where the zip landed. Absent for bytes-only recordings. */
    path?: string;
    /** The zip itself. Present only for bytes-only recordings (start path: null). */
    bytes?: Buffer;
    steps?: number;
    durationMs?: number;
    videos?: RecordingVideoSummary[];
    /** Why no video was recorded (video omitted on an engine without support). */
    videoUnavailable?: string;
    /** Where the zip was uploaded, when stop() asked for it. */
    upload?: RecordingUpload;
}
```

### `RecordingStartOptions`

```ts
interface RecordingStartOptions {
    name?: string;
    screenshots?: boolean;
    snapshots?: boolean;
    sources?: boolean;
    title?: string;
    bidi?: boolean;
    /** Screenshot format: 'jpeg' (default, faster/smaller) or 'png' (lossless). */
    format?: 'jpeg' | 'png';
    /** JPEG quality 0.0-1.0 (default 0.5). Ignored for PNG. */
    quality?: number;
    /**
     * Video track (Firefox 154+, local browsers). Omitted: record video if the
     * engine supports it; the stop result reports videoUnavailable otherwise.
     * `true` (or explicit dimensions): start fails if the engine can't deliver.
     * `false`: off.
     */
    video?: boolean | RecordingVideoOptions;
    /**
     * Where the recording zip lands at stop. Defaults to a timestamped
     * record-YYYYMMDD-HHMMSS.zip in the working directory, so a rerun never
     * clobbers the previous one. `null` selects bytes-only capture: no file
     * is written and the recording is lost if the session closes before
     * stop().
     */
    path?: string | null;
}
```

### `RecordingStopOptions`

```ts
interface RecordingStopOptions {
    /** Overrides the path declared at start. */
    path?: string;
    /**
     * Also upload the zip to a station's Record Store: `true` for the station
     * the browser is connected through, or a station URL. Needs the API key
     * the connection was made with; the zip still lands at its path either
     * way, and the result's `upload` says where it went.
     */
    upload?: boolean | string;
}
```

### `RecordingUpload`

```ts
interface RecordingUpload {
    /** Where the station serves the file. */
    url: string;
    sha256: string;
    size: number;
    /** The hold the recording was filed under, when the station knows one. */
    hold?: string;
    device?: string;
    /** The id of the file event the station signed for it. */
    event?: string;
}
```

### `RecordingVideoOptions`

```ts
interface RecordingVideoOptions {
    /** Video width in pixels (defaults to the viewport). */
    width?: number;
    /** Video height in pixels (defaults to the viewport). */
    height?: number;
    /** Video frame rate (engine default if omitted). */
    frameRate?: number;
    /**
     * On a remote browser connection, 'keep' records anyway and leaves the
     * video on the remote host: the stop result and zip manifest carry its
     * remotePath, and retrieval and cleanup are yours. Ignored on local
     * connections.
     */
    remote?: 'keep';
}
```

### `RecordingVideoSummary`

```ts
interface RecordingVideoSummary {
    context: string;
    durationMs: number;
    width: number;
    height: number;
    /** Where a remote-keep video lives on the remote host. */
    remotePath?: string;
    /** Set when the video pipeline died; the zip delivered without or with a partial video. */
    error?: string;
    /** True when the video file also holds what the recording said and heard. */
    audio?: boolean;
}
```

### `RunOptions`

```ts
interface RunOptions extends ModelOptions {
    /** Site under test: opened first unless the current page already shares its
     * origin; relative navigation paths resolve against it. Not the AI provider
     * endpoint; that is aiBaseURL. */
    baseURL?: string;
}
```

### `RunResult`

```ts
interface RunResult {
    status: 'completed' | 'not_completed';
    goal: string;
    summary: string;
    /** Machine-readable cause of a not_completed result. */
    reason?: 'action_limit' | 'missing_information' | 'safety_stop';
    evidence: {
        type: 'observation';
        summary: string;
    }[];
}
```

### `SayOptions`

```ts
interface SayOptions extends SpeechOptions {
    /** A WAV file to play as it is. Pass an empty text with it. */
    file?: string;
    voice?: string;
    speed?: number;
    /** false renders again and replaces the cached audio. Default true. */
    cache?: boolean;
    cacheDir?: string;
}
```

### `SayResult`

```ts
interface SayResult {
    text: string;
    target: string;
    provider: string;
    model: string;
    voice: string;
    durationMs: number;
    cached: boolean;
    /** SHA-256 of the audio that was played. */
    sha256: string;
    /** Present for file targets. */
    path?: string;
    /** Present when a file was played in place of text. */
    file?: string;
}
```

### `ScreenshotOptions`

```ts
interface ScreenshotOptions {
    /** Capture full scrollable page instead of just the viewport. */
    fullPage?: boolean;
    /** Capture a specific region of the page. */
    clip?: {
        x: number;
        y: number;
        width: number;
        height: number;
    };
}
```

### `SelectorOptions`

```ts
interface SelectorOptions {
    /** Natural-language description, e.g. 'the Add to Cart button'. Stands alone. */
    description?: string;
    /** Reference image to locate on screen: a file path, a data: URL, or PNG/JPEG bytes. Stands alone. */
    image?: string | Uint8Array;
    /** CSS selector. Exact; never sent to a model. */
    css?: string;
    /** Same as css. */
    selector?: string;
    /** HTML tag name. */
    tag?: string;
    /** Accessible-name filter: the text, label, alt, or aria-label a person reads the element by. */
    name?: string;
    /**
     * auto (default): page evidence first, a vision model only when needed
     * and configured. cv: local image matching only. vlm: vision model only.
     * tree: the page's DOM/accessibility tree only.
     */
    strategy?: FindStrategy;
    /** Include diagnostics in info.details. */
    details?: boolean;
    /** Per-call AI overrides, as for check and run. */
    provider?: string;
    model?: string;
    aiBaseURL?: string;
    reasoningEffort?: string;
    role?: string;
    text?: string;
    label?: string;
    placeholder?: string;
    alt?: string;
    title?: string;
    testid?: string;
    xpath?: string;
    near?: string;
    timeout?: number;
}
```

### `SetCookieParam`

```ts
interface SetCookieParam {
    name: string;
    value: string;
    domain?: string;
    url?: string;
    path?: string;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: string;
    expiry?: number;
}
```

### `SpeechOptions`

```ts
interface SpeechOptions {
    /** 'session', 'local', or a path ending in .wav. */
    target?: string;
    provider?: string;
    model?: string;
    language?: string;
}
```

### `StartOptions`

```ts
interface StartOptions {
    /** Browser engine to launch: 'chrome' (default) or 'firefox'. */
    engine?: 'chrome' | 'firefox';
    /**
     * Release channel of the engine to install and run, e.g. 'beta'.
     * Currently honored by Firefox only.
     */
    channel?: string;
    headless?: boolean;
    headers?: Record<string, string>;
    /** Extra alwaysMatch capabilities for classic WebDriver endpoints
     *  (cloud grids take their config this way, via vendor-prefixed capability keys). */
    caps?: Record<string, unknown>;
    executablePath?: string;
    /**
     * Extra command-line flags for the launched browser, e.g.
     * ['--use-fake-device-for-media-stream', '--lang=fr']. Each is passed to the
     * engine as-is and wins over Vibium's defaults. Ignored in connect mode,
     * where the browser is already running elsewhere.
     */
    args?: string[];
    /**
     * Persistent browser profile directory, created if missing and reused
     * across sessions (cookies, logins survive). Omit for the default: a
     * temporary profile wiped on close. Ignored in connect mode.
     */
    userDataDir?: string;
}
```

### `StorageState`

```ts
interface StorageState {
    cookies: Cookie[];
    origins: OriginState[];
}
```

### `SwipeDirection`

```ts
type SwipeDirection = 'up' | 'down' | 'left' | 'right';
```

### `SwipeOptions`

```ts
interface SwipeOptions {
    /** Start at an edge or corner of the viewport, its center (default), or a point. */
    from?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | {
        x: number;
        y: number;
    };
    /** Pixels to move (default: half the viewport). */
    distance?: number;
    /** 'slow', 'normal', 'fast', or pixels per second. Instead of duration. */
    speed?: 'slow' | 'normal' | 'fast' | number;
    /** Milliseconds the move takes (default 300). */
    duration?: number;
    /** Milliseconds to rest at the end before lifting. */
    hold?: number;
}
```
