Struct AgentPage 

pub struct AgentPage<'a> { /* private fields */ }

Wraps a Page with agent-friendly observation and interaction methods.

The core loop is: observe() → read element_list() → click(i) / fill(i, text).

Implementations

impl<'a> AgentPage<'a>

pub fn new(page: &'a Page) -> Self

Create an AgentPage wrapping an existing eoka Page.

pub fn with_config(page: &'a Page, config: ObserveConfig) -> Self

Create with custom observation config.

pub fn page(&self) -> &Page

Get a reference to the underlying Page.

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

Snapshot the page: enumerate all interactive elements.

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(&mut self) -> Result<Vec<u8>>

Take an annotated screenshot with numbered boxes on each element. Calls observe() first if no elements have been enumerated yet.

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

Take a plain screenshot without annotations.

pub fn element_list(&self) -> String

Compact text list for LLM consumption. Each line: [index] <tag type="x"> "text" placeholder="y"

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). Returns the element index, or None.

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 click(&self, index: usize) -> Result<()>

Click an element by its index.

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

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

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

Human-like click by index.

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

Clear and type into an element by index.

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

Human-like fill by index.

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

Focus an element by index.

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

Select a dropdown option by index. value matches the option’s value or visible text.

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

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

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

Scroll element at index into view.

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

Navigate to a URL. Clears element list (call observe() after navigation).

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

Go back in history. Clears element list (call observe() after navigation).

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

Go forward in history. Clears element list (call observe() after navigation).

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

Reload the page. Clears element list (call observe() after navigation).

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 the top of the page.

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

Scroll to the bottom of the page.

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 wait(&self, ms: u64)

Fixed delay in milliseconds.

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 press_key(&self, key: &str) -> Result<()>

Press a key (e.g. “Enter”, “Tab”, “Escape”, “ArrowDown”, “Backspace”).

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

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

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

Hover over element by index (triggers hover states, tooltips, menus).

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> = agent.extract(
    "Array.from(document.querySelectorAll('h2')).map(h => h.textContent.trim())"
).await?;

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 click_and_wait(&mut self, index: usize) -> Result<()>

Click an element and wait for page to stabilize.

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

Fill an element and wait for page to stabilize.

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

Select an option and wait for page to stabilize.

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 list 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 list since the DOM will change.