## API Reference
Use this as the supported `agent.browsers.*` surface.

```ts
// Installed by setupBrowserRuntime({ globals: globalThis }).
const browser = await agent.browsers.get("iab");
interface Agent {
  browsers: Browsers; // API for finding and selecting browsers.
  documentation: Documentation; // API for reading packaged browser-use documentation by name.
}

interface Browsers {
  get(id: string): Promise<Browser>; // Get a browser by id or client type.
  list(): Promise<Array<BrowserInfo>>; // List available browsers.
}

interface Browser {
  browserId: string; // Browser id selected by `agent.browsers.get()`.
  capabilities: BrowserCapabilityCollection; // Browser-scoped optional capabilities advertised by the connected backend; discover IDs with `await browser.capabilities.list()`, then call `await (await browser.capabilities.get(id)).documentation()` for method details.
  tabs: Tabs; // API for interacting with browser tabs.
  user: BrowserUser; // Readonly context about tabs in the user's browser windows.
  documentation(): Promise<string>; // Read browser guidance and the core API reference.
  nameSession(name: string): Promise<void>; // Name the current browser automation session.
}

interface BrowserUser {

  openTabs(): Promise<Array<BrowserUserTabInfo>>; // List open top-level tabs across the user's browser windows ordered by `lastOpened` descending.
}

interface Tabs {

  get(id: string): Promise<Tab>; // Get a tab by id.
  list(): Promise<Array<TabInfo>>; // List open tabs in the browser.
  new(): Promise<Tab>; // Create and return a new tab in the browser.
  selected(): Promise<undefined | Tab>; // Return the currently selected tab, if any.
}

interface Tab {
  capabilities: TabCapabilityCollection; // Tab-scoped optional capabilities advertised by the connected backend; discover IDs with `await tab.capabilities.list()`, then call `await (await tab.capabilities.get(id)).documentation()` for method details.
  clipboard: TabClipboardAPI; // API for interacting with clipboard content in this tab.

  cua: CUAAPI; // API for interacting with the tab via the cua api
  dev: TabDevAPI; // API for developer-oriented tab inspection.
  dom_cua: DomCUAAPI; // API for interacting with the tab via the dom based cua api
  id: string; // A tab's unique identifier
  playwright: PlaywrightAPI; // API for interacting with the tab via the playwright api
  back(): Promise<void>; // Navigate this tab back in history.
  close(): Promise<void>; // Close this tab.
  forward(): Promise<void>; // Navigate this tab forward in history.
  goto(url: string): Promise<void>; // Open a URL in this tab.
  reload(): Promise<void>; // Reload this tab.
  screenshot(options: ScreenshotOptions): Promise<Uint8Array>; // Capture a screenshot of this tab.
  title(): Promise<undefined | string>; // Get the current title for this tab.
  url(): Promise<undefined | string>; // Get the current URL for this tab.
}

interface CUAAPI {
  click(options: ClickOptions): Promise<void>; // Click at a coordinate in the current viewport.
  double_click(options: DoubleClickOptions): Promise<void>; // Double click at a coordinate in the current viewport.
  
  drag(options: DragOptions): Promise<void>; // Drag from a point to a point by the provided path.
  keypress(options: KeypressOptions): Promise<void>; // Press control characters at the current focused element (focus it first via click/dblclick).
  move(options: MoveOptions): Promise<void>; // Move the mouse to a point by the provided x and y coordinates.
  scroll(options: ScrollOptions): Promise<void>; // Scroll by a delta from a specific viewport coordinate.
  type(options: TypeOptions): Promise<void>; // Type text at the current focus.
}

interface DomCUAAPI {
  click(options: DomClickOptions): Promise<void>; // Click a DOM node by its id from the visible DOM snapshot.
  double_click(options: DomClickOptions): Promise<void>; // Double-click a DOM node by its id.
  
  get_visible_dom(): Promise<unknown>; // Return a filtered DOM with node ids for interactable elements.
  keypress(options: DomKeypressOptions): Promise<void>; // Press control characters at the currently focused element (focus it first via click/dblclick).
  scroll(options: DomScrollOptions): Promise<void>; // Scroll either the page or a specific node (if node_id provided) by deltas.
  type(options: DomTypeOptions): Promise<void>; // Type text into the currently focused element (focus via click first).
}

interface PlaywrightAPI {
  domSnapshot(): Promise<string>; // Return a snapshot of the current DOM as a string, including expanded iframe body content when available.

  evaluate<TResult, TArg>(pageFunction: PlaywrightEvaluateFunction<TArg, TResult>, arg?: TArg, options?: PlaywrightEvaluateOptions): Promise<TResult>; // Evaluate JavaScript in a read-only page scope.
  expectNavigation<T>(action: () => Promise<T>, options: { timeoutMs?: number; url?: string; waitUntil?: LoadState }): Promise<T>; // Expect a navigation triggered by an action.
  frameLocator(frameSelector: string): PlaywrightFrameLocator; // Create a frame-scoped locator builder.
  getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label text within the page.
  getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder text within the page.
  getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role within the page.
  getByTestId(testId: string): PlaywrightLocator; // Find elements by test id within the page.
  getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text within the page.
  locator(selector: string): PlaywrightLocator; // Create a locator scoped to this tab.
  waitForEvent(event: "download", options?: WaitForEventOptions): Promise<PlaywrightDownload>; // Wait for the next event on the page.

  waitForLoadState(options: PageWaitForLoadStateOptions): Promise<void>; // Wait for the page to reach a specific load state.
  waitForTimeout(timeoutMs: number): Promise<void>; // Wait for a fixed duration.
  waitForURL(url: string, options: PageWaitForURLOptions): Promise<void>; // Wait for the page URL to match the provided value.
}

interface PlaywrightFrameLocator {
  frameLocator(frameSelector: string): PlaywrightFrameLocator; // Create a locator scoped to a nested frame.
  getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label within this frame.
  getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder within this frame.
  getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role within this frame.
  getByTestId(testId: string): PlaywrightLocator; // Find elements by test id within this frame.
  getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text within this frame.
  locator(selector: string): PlaywrightLocator; // Create a locator scoped to this frame.
}

interface PlaywrightLocator {
  all(): Promise<Array<PlaywrightLocator>>; // Resolve to a list of locators for each matched element.
  allTextContents(options: { timeoutMs?: number }): Promise<Array<string>>; // Return `textContent` for *all* elements matched by this locator.
  and(locator: PlaywrightLocator): PlaywrightLocator; // Return a locator matching elements that satisfy both this locator and `locator`.
  check(options: LocatorCheckOptions): Promise<void>; // Check a checkbox or switch-like control.
  click(options: LocatorClickOptions): Promise<void>; // Click the element matched by this locator.
  count(): Promise<number>; // Number of elements matching this locator.
  dblclick(options: LocatorClickOptions): Promise<void>; // Double-click the element matched by this locator.

  fill(value: string, options: { timeoutMs?: number }): Promise<void>; // Replace the element's value with the provided text.
  filter(options: LocatorFilterOptions): PlaywrightLocator; // Narrow this locator by additional constraints.
  first(): PlaywrightLocator; // Return a locator pointing at the first matched element.
  getAttribute(name: string, options: { timeoutMs?: number }): Promise<null | string>; // Return an attribute value from the first matched element.
  getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label text, scoped to this locator.
  getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder text, scoped to this locator.
  getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role, scoped to this locator.
  getByTestId(testId: string): PlaywrightLocator; // Find elements by test id, scoped to this locator.
  getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text content, scoped to this locator.
  innerText(options: { timeoutMs?: number }): Promise<string>; // Return the rendered (visible) text of the first matched element.
  isEnabled(): Promise<boolean>; // Whether the first matched element is currently enabled.
  isVisible(): Promise<boolean>; // Whether the first matched element is currently visible.
  last(): PlaywrightLocator; // Return a locator pointing at the last matched element.
  locator(selector: string, options: LocatorLocatorOptions): PlaywrightLocator; // Create a descendant locator scoped to this locator.
  nth(index: number): PlaywrightLocator; // Return a locator pointing at the Nth matched element.
  or(locator: PlaywrightLocator): PlaywrightLocator; // Return a locator matching elements that satisfy either this locator or `locator`.
  press(value: string, options: { timeoutMs?: number }): Promise<void>; // Press a keyboard key while this locator is focused.
  selectOption(value: SelectOptionInput | Array<SelectOptionInput>, options: { timeoutMs?: number }): Promise<void>; // Select one or more options on a native `<select>` element.
  setChecked(checked: boolean, options: LocatorCheckOptions): Promise<void>; // Set a checkbox or switch-like control to a checked/unchecked state.
  textContent(options: { timeoutMs?: number }): Promise<null | string>; // Return the raw textContent of the first matched element (or null if missing).
  type(value: string, options: { timeoutMs?: number }): Promise<void>; // Type text into the element without clearing existing content.
  uncheck(options: LocatorCheckOptions): Promise<void>; // Uncheck a checkbox or switch-like control.
  waitFor(options: LocatorWaitForOptions): Promise<void>; // Wait for the element to reach a specific state.
}

interface PlaywrightDownload {

}

interface TabClipboardAPI {
  read(): Promise<Array<TabClipboardItem>>; // Read clipboard items, including text and binary payloads.
  readText(): Promise<string>; // Read plain text from the browser clipboard.
  write(items: Array<TabClipboardItem>): Promise<void>; // Write clipboard items.
  writeText(text: string): Promise<void>; // Write plain text to the browser clipboard.
}

interface TabDevAPI {
  logs(options: TabDevLogsOptions): Promise<Array<TabDevLogEntry>>; // Read console log messages captured for this tab.
}

interface Documentation {
  get(name: string): Promise<string>; // Read packaged documentation by its extensionless relative path.
}

interface BrowserInfo {
  capabilities: ClientCapabilities;
  id: string;
  metadata?: Record<string, string>;
  name: string;
  type: ClientType;
}

type BrowserCapabilityCollection = {
  get(id: string): Promise<unknown>;
  list(): Promise<Array<{ id: string; description: string }>>;
};

interface BrowserUserTabInfo {
  id: string; // Opaque identifier for this browser tab.
  lastOpened?: string; // ISO 8601 timestamp for the last time the tab was opened or focused.
  tabGroup?: string; // User-visible tab group name when the tab belongs to one.
  title?: string; // User-visible tab title.
  url?: string; // Current tab URL.
}

interface TabsContentOptions {

  timeoutMs?: number; // Maximum time to wait for each page load, in milliseconds.
  urls: Array<string>; // URLs to load in temporary background tabs.
}

interface TabsContentResult {

  title: null | string; // The resolved page title when available.
  url: string; // The resolved page URL when available, otherwise the requested URL.
}

interface FinalizeTabsOptions {
  keep?: Array<FinalizeTabsKeep>; // Explicit tab dispositions to preserve after cleanup.
}

interface TabInfo {
  id: string; // Metadata describing an open tab.
  title?: string;
  url?: string;
}

type TabCapabilityCollection = {
  get(id: string): Promise<unknown>;
  list(): Promise<Array<{ id: string; description: string }>>;
};

type ScreenshotOptions = {
  clip?: ClipRect; // Crop to a specific rectangle instead of the full viewport.
  fullPage?: boolean; // Capture the full page instead of the viewport.
};

type ClickOptions = {
  button?: number; // Mouse button (1-left, 2-middle/wheel, 3-right, 4-back, 5-forward).
  keypress?: Array<string>; // Modifier keys held during the click.
  x: number;
  y: number;
};

type DoubleClickOptions = {
  keypress?: Array<string>; // Modifier keys held during the double click.
  x: number;
  y: number;
};

type DragOptions = {
  keys?: Array<string>; // Optional modifier keys held during the drag.
  path: Array<{ x: number; y: number }>; // Drag path as a list of points.
};

type KeypressOptions = {
  keys: Array<string>; // Key combination to press.
};

type MoveOptions = {
  keys?: Array<string>; // Optional modifier keys held while moving.
  x: number;
  y: number;
};

type ScrollOptions = {
  keypress?: Array<string>; // Modifier keys held during scroll.
  scrollX: number;
  scrollY: number;
  x: number;
  y: number;
};

type TypeOptions = {
  text: string;
};

type DomClickOptions = {
  node_id: string; // Node id from `get_visible_dom()`.
};

type DomKeypressOptions = {
  keys: Array<string>; // Key combination to press.
};

type DomScrollOptions = {
  node_id?: string; // Optional node id to scroll within.
  x: number; // Horizontal scroll delta.
  y: number; // Vertical scroll delta.
};

type DomTypeOptions = {
  text: string; // Text to type into the currently focused element.
};

type ElementInfoOptions = {
  includeNonInteractable?: boolean; // When true, include non-interactable elements in addition to interactable targets.
  x: number;
  y: number;
};

type ElementInfo = {
  ariaName?: string | null; // Accessible name if available.
  boundingBox?: ElementInfoRect | null; // Element bounds in screenshot coordinates.
  nodeId?: number | null; // Backend node id that can be passed to DOM-inspection APIs when available.
  preview: string; // Compact human-readable node preview.
  role?: string | null; // Computed ARIA role if available.
  selector: ElementInfoSelector; // Suggested selector data for this element.
  tagName: string; // Lowercased HTML tag name.
  testId?: string | null; // Configured test id attribute if present.
  visibleText?: string | null; // Rendered visible text, selected option text, or visible form value when available.
};

type ElementScreenshotOptions = {
  includeNonInteractable?: boolean; // When true, highlight non-interactable elements in addition to interactable targets.
  x: number;
  y: number;
};

type PlaywrightEvaluateFunction<TArg, TResult> = string | (arg: TArg) => TResult | Promise<TResult>;

type PlaywrightEvaluateOptions = {
  timeoutMs?: number; // Maximum time to spend setting up the read-only DOM scope and running the script.
};

type LoadState = "load" | "domcontentloaded" | "networkidle";

type TextMatcher = string | RegExp;

type WaitForEventOptions = {
  timeoutMs?: number;
};

type PageWaitForLoadStateOptions = {
  state?: LoadState;
  timeoutMs?: number;
};

type PageWaitForURLOptions = {
  timeoutMs?: number;
  waitUntil?: WaitUntil;
};

type LocatorCheckOptions = {
  force?: boolean;
  timeoutMs?: number;
};

type LocatorClickOptions = {
  button?: MouseButton;
  force?: boolean;
  modifiers?: Array<KeyboardModifier>;
  timeoutMs?: number;
};

type LocatorFilterOptions = {
  has?: PlaywrightLocator;
  hasNot?: PlaywrightLocator;
  hasNotText?: TextMatcher;
  hasText?: TextMatcher;
  visible?: boolean;
};

type LocatorLocatorOptions = {
  has?: PlaywrightLocator;
  hasNot?: PlaywrightLocator;
  hasNotText?: TextMatcher;
  hasText?: TextMatcher;
};

type SelectOptionInput = string | SelectOptionDescriptor;

type LocatorWaitForOptions = {
  state: WaitForState;
  timeoutMs?: number;
};

type TabClipboardItem = {
  entries: Array<TabClipboardEntry>;
  presentationStyle?: "unspecified" | "inline" | "attachment";
};

interface TabDevLogsOptions {
  filter?: string; // Optional substring filter applied to the rendered log message.
  levels?: Array<"debug" | "info" | "log" | "warn" | "error" | "warning">; // Optional levels to include.
  limit?: number; // Maximum number of logs to return.
}

interface TabDevLogEntry {
  level: "debug" | "info" | "log" | "warn" | "error"; // Console log level.
  message: string; // Rendered log message text.
  timestamp: string; // ISO 8601 timestamp for when the runtime captured the log.
  url?: string; // Source URL reported by the browser runtime, when available.
}

interface ClientCapabilities {
  browser?: Array<CapabilityInfo>;
  tab?: Array<CapabilityInfo>;
}

type ClientType = "iab" | "extension" | "cdp";

type TabsContentType = "html" | "text" | "domSnapshot";

interface FinalizeTabsKeep {
  status: FinalizeTabStatus; // Where the kept tab belongs after cleanup.
  tab: string | Tab | TabInfo; // Tab object to keep open after browser cleanup.
}

type ClipRect = {
  height: number;
  width: number;
  x: number;
  y: number;
};

type ElementInfoRect = {
  height: number;
  width: number;
  x: number;
  y: number;
};

type ElementInfoSelector = {
  candidates: Array<string>; // Ranked selector candidates for the element.
  frameSelectors?: Array<string>; // Frame selectors to enter before using the element selector.
  primary?: string | null; // The preferred selector for the element when available.
};

type WaitUntil = LoadState | "commit";

type MouseButton = "left" | "right" | "middle";

type KeyboardModifier = "Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift";

type SelectOptionDescriptor = {
  index?: number;
  label?: string;
  value?: string;
};

type WaitForState = "attached" | "detached" | "visible" | "hidden";

type TabClipboardEntry = {
  base64?: string;
  mimeType: string;
  text?: string;
};

interface CapabilityInfo {
  description: string;
  id: string;
}

type FinalizeTabStatus = "handoff" | "deliverable";
```