Current URL of the browser page
Whether the browser is launched and connected
Current viewport dimensions
Capture a snapshot of the given origin's client-side storage (localStorage
Default returns null (nothing to capture) so adapters without a live
page don't break — additive and non-throwing. Adapters backed by a real
page (e.g. Playwright) override this.
Origin (protocol + host + port) to snapshot.
Capture one frame on demand and push it through the active screencast's callback.
Lets callers force an immediate live-view refresh (e.g. the first paint, or right after a navigation settles) on adapters whose screencast only emits frames on a viewport repaint.
Default implementation is a no-op resolve — safe to call when no screencast is running or the adapter has no screencast support. Adapters with a live screencast (e.g. PlaywrightBrowserAdapter) override this to emit a real frame.
Capture a screenshot of the current viewport.
Base64-encoded PNG string (no data URI prefix)
Close the browser and release all resources. Safe to call multiple times — subsequent calls are no-ops.
Execute a single browser action.
The action is a discriminated union — implementations should
switch on action.Type for exhaustive handling.
ProtectedExtractExtract the domain (hostname) from a URL string. Shared utility available to all adapter implementations.
Extract the page's interactive elements (buttons/links/inputs/ARIA roles/
click affordances) as a stable indexed list for element-grounded
perception. The returned indices are what a subsequent
ClickElement/TypeIntoElement action resolves against, so an adapter
that implements this MUST cache the result to resolve those actions.
Default returns an empty list so adapters without a live DOM don't break — element grounding then simply has nothing to offer and the engine falls back to coordinate actions. Adapters backed by a real page override this.
Capture the page's accessibility tree for token-efficient, structured perception (a lighter-weight alternative to a screenshot).
Default implementation returns null so adapters that cannot produce an
accessibility tree don't break — additive and non-throwing. Adapters
backed by a real page (e.g. Playwright) override this.
The root AccessibilityNode, or null when unavailable.
Retrieve and flush all buffered diagnostic events (console errors, network failures, page crashes) captured since the last call.
Read the page's CURRENT text selection (window.getSelection().toString()).
Used by the remote-browser human "copy-out" path — the viewer reads what the human selected on the remote page and writes it to the local clipboard. Default implementation returns an empty string so adapters without a live page don't break — it's a non-throwing, additive default. Adapters backed by a real page (e.g. Playwright) override this to return the live selection.
The selected text, or '' when nothing is selected / unavailable.
Capture the current page's title for cheap perception / sync.
Default implementation returns an empty string so adapters without a live page don't break — it's a non-throwing, additive default. Adapters backed by a real page (e.g. Playwright) override this to return the page title.
The page title, or '' when unavailable.
Read the visible text of the current page for agent perception.
Returns the rendered (visible) text content of the page body — useful for an LLM controller that needs the page's textual state without a screenshot. Adapters backed by a live page (e.g. Playwright) override this to return the real page text.
Default implementation returns an empty string so adapters that cannot read page text don't break — it's a non-throwing, additive default.
The page's visible text, or '' if unavailable.
Launch the browser with the given configuration. Must be called before any other method.
Navigate to the given URL and wait for the page to load. Respects the NavigationTimeoutMs from BrowserConfig.
Introspect a single element matched by a CSS selector — its existence, visibility, text, and bounding box — without ever throwing on a miss.
Default implementation reports the element as absent so adapters that cannot query the DOM don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.
CSS selector identifying the target element.
An ElementInfo; { Exists:false, Visible:false, Text:'' } when missing.
Reset per-session state for the given origin while preserving auth tokens. Called between tests in shared-context mode so that the next test starts with a clean app state but doesn't have to re-login.
Cleans (for the given origin):
sessionStorage (entirely)localStorage EXCEPT entries matching auth-token patternsPreserves: cookies (handled at context level by Playwright — they survive naturally), auth-token localStorage entries (Auth0, MSAL, generic OAuth).
Best-effort: never throws.
Restore a previously-captured ContextSeed into the current context BEFORE the app boots. Best-effort and cold-boot-safe by contract: any failure must leave the context to refetch from the server, never a half-populated (corrupt) cache.
Default is a no-op resolve so adapters that can't seed don't break — additive and non-throwing. Adapters backed by a real page override this.
Add cookies to the browser context. Used by AuthHandler for CookieInjection auth.
Set extra HTTP headers for all requests to a specific domain. Used by AuthHandler for Bearer, APIKey, and Basic auth.
Headers are additive — calling this multiple times for the same domain merges headers. Calling with a different domain adds a new set of domain-scoped headers.
Implementation note: Playwright uses page.route() interception; other adapters may use their own request interception mechanism.
Set localStorage entries for a specific domain. The browser must have already navigated to the domain (or a page on that domain) for this to work.
Used by AuthHandler for LocalStorage auth.
Start capturing the audio playing inside the browser tab, invoking
onChunk for each encoded AudioCaptureChunk until
StopAudioCapture is called.
Default implementation is a no-op resolve: it starts no capture and emits no chunks. This is the safer additive default — a consumer that opportunistically requests tab audio on an adapter that can't provide one simply receives nothing rather than an exception. Adapters that can tap the page's media elements (e.g. PlaywrightBrowserAdapter) override this to emit real chunks.
Callback invoked with each captured audio chunk.
Start a live screencast of the browser viewport, invoking onFrame for
each captured frame until StopScreencast is called.
Default implementation is a no-op resolve: it starts no feed and emits no frames. This is the safer additive default — a consumer that opportunistically requests a live feed on an adapter that can't provide one (e.g. a non-CDP backend) simply receives nothing rather than an exception that would break an otherwise-working automation loop. Adapters that can drive CDP (e.g. PlaywrightBrowserAdapter) override this to emit real ScreencastFrames.
Optional_opts: ScreencastOptionsBegin recording a forensic trace of the session (DOM snapshots + screenshots + network + console) for later offline inspection.
Default implementation is a no-op resolve so adapters that can't produce a
trace (or non-CDP backends) don't break — additive and non-throwing.
Adapters backed by a real browser context (e.g. Playwright) override this
to call context.tracing.start(...). The caller decides whether to
capture (and whether to keep the result); the adapter only knows how.
Stop an audio capture previously started via StartAudioCapture and
release any associated in-page resources (the MediaRecorder, observers).
Default implementation is a no-op — safe to call even when no capture is active or the adapter never supported one.
Stop a screencast previously started via StartScreencast and release any associated resources (e.g. the CDP session).
Default implementation is a no-op — safe to call even when no screencast is active or the adapter never supported one.
Stop a trace started via StartTracing, writing it to path.
Returns true iff a trace file was actually written (so the caller can
decide whether there's an artifact to retain or discard). Default
implementation returns false — nothing was traced. Never throws.
Filesystem path to write the trace to (e.g. a .zip).
Wait until the page reaches a given load state.
Useful after a navigation/action to let the page settle before the next perception step. Default implementation is a no-op resolve so adapters that cannot observe load state don't break — additive and non-throwing. Adapters backed by a real page (e.g. Playwright) override this.
'load', 'domcontentloaded', or 'networkidle'.
Hard cap on buffered diagnostic events between drains.
A misbehaving page can emit console errors far faster than the step loop drains them. One Explorer defect (
TabContainer.updateTabDisplayNamethrowing NG0201 on every tab add/reload) produced 50,153 console errors in run-20260730T200139Z; the unbounded buffer plus Playwright's retained argument handles for each message cost 6.5 GB of runner heap and OOM-killed the suite. Past the cap we count and discard — the digest only ever surfaces a handful of representative events, so the overflow has no diagnostic value.