Whether the browser is launched and connected
Current viewport dimensions
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.
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.
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.
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: ScreencastOptionsStop 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.
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.
Current URL of the browser page