Struct Session 

pub struct Session { /* private fields */ }

A browser session that owns its browser and page. This is the primary API for library usage. The MCP server uses raw Page directly.

Implementations

impl Session

pub async fn launch() -> Result<Self>

Launch a new browser and create an owned agent page.

pub async fn launch_with_config(stealth: StealthConfig) -> Result<Self>

Launch with custom stealth config.

pub fn set_observe_config(&mut self, config: ObserveConfig)

Set observation config.

pub fn page(&self) -> &Page

Get reference to underlying page.

pub fn browser(&self) -> &Browser

Get reference to browser.

pub async fn observe(&mut self) -> Result<&[InteractiveElement]>

Snapshot the page: enumerate all interactive elements.

pub async fn screenshot(&mut self) -> Result<Vec<u8>>

Take an annotated screenshot with numbered boxes on each element.

pub fn element_list(&self) -> String

Compact text list for LLM consumption.

pub fn get(&self, index: usize) -> Option<&InteractiveElement>

Get element info by index.

pub fn elements(&self) -> &[InteractiveElement]

Get all observed elements.

pub fn len(&self) -> usize

Number of observed elements.

pub fn is_empty(&self) -> bool

Whether the element list is empty.

pub fn find_by_text(&self, needle: &str) -> Option<usize>

Find first element whose text contains the given substring (case-insensitive).

pub fn find_all_by_text(&self, needle: &str) -> Vec<usize>

Find all elements whose text contains the given substring (case-insensitive).

pub async fn observe_diff(&mut self) -> Result<ObserveDiff>

Observe and return a diff against the previous observation. Use this in multi-step sessions to minimize tokens — only send added_element_list() to the LLM instead of the full list.

pub fn added_element_list(&self, diff: &ObserveDiff) -> String

Compact text list of only the added elements from the last observe_diff().

pub async fn screenshot_plain(&self) -> Result<Vec<u8>>

Take a plain screenshot without annotations.

pub async fn click(&mut self, index: usize) -> Result<()>

Click an element, auto-recovering if stale. Clears element cache since clicks often trigger navigation/DOM changes.

pub async fn fill(&mut self, index: usize, text: &str) -> Result<()>

Fill an element, auto-recovering if stale. Does NOT clear element cache (typing rarely changes DOM structure).

pub async fn select(&mut self, index: usize, value: &str) -> Result<()>

Select a dropdown option, auto-recovering if stale. Clears element cache since onChange handlers may modify DOM.

pub async fn hover(&mut self, index: usize) -> Result<()>

Hover over element.

pub async fn scroll_to(&mut self, index: usize) -> Result<()>

Scroll element into view.

pub async fn try_click(&mut self, index: usize) -> Result<bool>

Try to click — returns Ok(false) if element is missing or not visible.

pub async fn human_click(&mut self, index: usize) -> Result<()>

Human-like click by index.

pub async fn human_fill(&mut self, index: usize, text: &str) -> Result<()>

Human-like fill by index.

pub async fn focus(&mut self, index: usize) -> Result<()>

Focus an element by index.

pub async fn submit(&mut self, index: usize) -> Result<()>

Focus element by index and press Enter (common for form submission).

pub async fn options(&mut self, index: usize) -> Result<Vec<(String, String)>>

Get dropdown options for a select element. Returns vec of (value, text) pairs.

pub async fn goto(&mut self, url: &str) -> Result<()>

Navigate to a URL.

pub async fn back(&mut self) -> Result<()>

Go back in history.

pub async fn forward(&mut self) -> Result<()>

Go forward in history.

pub async fn reload(&mut self) -> Result<()>

Reload the page.

pub async fn url(&self) -> Result<String>

Get the current URL.

pub async fn title(&self) -> Result<String>

Get the page title.

pub async fn text(&self) -> Result<String>

Get visible text content of the page.

pub async fn scroll_down(&self) -> Result<()>

Scroll down by approximately one viewport height.

pub async fn scroll_up(&self) -> Result<()>

Scroll up by approximately one viewport height.

pub async fn scroll_to_top(&self) -> Result<()>

Scroll to top.

pub async fn scroll_to_bottom(&self) -> Result<()>

Scroll to bottom.

pub async fn wait_for_stable(&self) -> Result<()>

Wait for the page to stabilize after an action. Waits up to 2s for network idle, then 50ms for DOM settle. Intentionally succeeds even if network doesn’t fully idle (some sites never stop polling).

pub async fn wait(&self, ms: u64)

Fixed delay in milliseconds.

pub async fn wait_for_text(&self, text: &str, timeout_ms: u64) -> Result<()>

Wait for text to appear on the page.

pub async fn wait_for_url(&self, pattern: &str, timeout_ms: u64) -> Result<()>

Wait for a URL pattern (substring match).

pub async fn wait_for_idle(&self, timeout_ms: u64) -> Result<()>

Wait for network activity to settle.

pub async fn press_key(&self, key: &str) -> Result<()>

Press a key.

pub async fn eval<T: DeserializeOwned>(&self, js: &str) -> Result<T>

Evaluate JavaScript and return the result.

pub async fn exec(&self, js: &str) -> Result<()>

Execute JavaScript (no return value).

pub async fn extract<T: DeserializeOwned>( &self, js_expression: &str, ) -> Result<T>

Extract structured data from the page using a JS expression that returns JSON.

Example:

let titles: Vec<String> = session.extract(
    "Array.from(document.querySelectorAll('h2')).map(h => h.textContent.trim())"
).await?;

pub async fn spa_info(&self) -> Result<SpaRouterInfo>

Detect the SPA router type and current route state.

pub async fn spa_navigate(&mut self, path: &str) -> Result<String>

Navigate the SPA to a new path without page reload. Automatically detects the router type and uses the appropriate navigation method. Clears element cache since the DOM will change.

pub async fn history_go(&mut self, delta: i32) -> Result<()>

Navigate browser history by delta steps. delta = -1 goes back, delta = 1 goes forward. Clears element cache since the DOM will change.

pub async fn close(self) -> Result<()>

Close the browser.