JavaScript API Reference
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. The same data for every surface
is in the API matrix and in
/api.json.
Examples assume bro is a started browser and vibe is its page, as in the
quickstart.
Browser
Section titled “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.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
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
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
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
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
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
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
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
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
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
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)
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)
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)
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)
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)
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)
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
consoleMessages(): { type: string; text: string;}[];Return collected console messages and clear the buffer. Returns [] if not collecting.
page.errors()
Get buffered page errors
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
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
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
Section titled “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
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)
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)
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
Section titled “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
Section titled “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.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.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.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
Section titled “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
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
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.request (property)
Access intercepted request
readonly request: Request;
route.fulfill(resp?)
Fulfill an intercepted request
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
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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
location(): { url: string; lineNumber: number; columnNumber: number;} | null;The source location of the console call, if available.
WebSocketInfo
Section titled “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
Section titled “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
Section titled “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.
Option and result types named in the signatures above.
A11yNode
Section titled “A11yNode”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
Section titled “ActionOptions”interface ActionOptions { /** Timeout in milliseconds for actionability checks. Default: 30000 */ timeout?: number;}BoundingBox
Section titled “BoundingBox”interface BoundingBox { x: number; y: number; width: number; height: number;}Browser
Section titled “Browser”interface Browser { (goal: string, options?: RunOptions): Promise<RunResult>;}CheckOptions
Section titled “CheckOptions”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
Section titled “CheckResult”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
Section titled “ClockInstallOptions”interface ClockInstallOptions { time?: number | string | Date; timezone?: string;}CloseHandler
Section titled “CloseHandler”type CloseHandler = (code?: number, reason?: string) => void;Cookie
Section titled “Cookie”interface Cookie { name: string; value: string; domain: string; path: string; size: number; httpOnly: boolean; secure: boolean; sameSite: string; expiry?: number;}ElementInfo
Section titled “ElementInfo”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
Section titled “FindOptions”interface FindOptions { /** Timeout in milliseconds to wait for element. Default: 30000 */ timeout?: number;}FindStrategy
Section titled “FindStrategy”type FindStrategy = 'auto' | 'cv' | 'vlm' | 'tree';FluentElement
Section titled “FluentElement”type FluentElement = Promise<Element> & { click(options?: ActionOptions): Promise<void>;ListenOptions
Section titled “ListenOptions”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
Section titled “ListenResult”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
Section titled “MessageHandler”type MessageHandler = (data: string, info: { direction: 'sent' | 'received';ModelOptions
Section titled “ModelOptions”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
Section titled “OriginState”interface OriginState { origin: string; localStorage: { name: string; value: string; }[]; sessionStorage: { name: string; value: string; }[];}interface Page { (goal: string, options?: RunOptions): Promise<RunResult>;}PdfOptions
Section titled “PdfOptions”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
Section titled “RecordingResult”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
Section titled “RecordingStartOptions”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
Section titled “RecordingStopOptions”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
Section titled “RecordingUpload”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
Section titled “RecordingVideoOptions”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
Section titled “RecordingVideoSummary”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
Section titled “RunOptions”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
Section titled “RunResult”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
Section titled “SayOptions”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
Section titled “SayResult”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
Section titled “ScreenshotOptions”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
Section titled “SelectorOptions”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
Section titled “SetCookieParam”interface SetCookieParam { name: string; value: string; domain?: string; url?: string; path?: string; httpOnly?: boolean; secure?: boolean; sameSite?: string; expiry?: number;}SpeechOptions
Section titled “SpeechOptions”interface SpeechOptions { /** 'session', 'local', or a path ending in .wav. */ target?: string; provider?: string; model?: string; language?: string;}StartOptions
Section titled “StartOptions”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
Section titled “StorageState”interface StorageState { cookies: Cookie[]; origins: OriginState[];}SwipeDirection
Section titled “SwipeDirection”type SwipeDirection = 'up' | 'down' | 'left' | 'right';SwipeOptions
Section titled “SwipeOptions”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;}