Class PlaywrightBrowserAdapter

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

• IndexedDB) for later restore into a fresh context — the warm-seed that kills the per-test cold-boot metadata refetch. The caller (driver) captures once post-login and reuses the seed across contexts.

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.

Capture ONE frame on demand and push it through the active screencast's frame callback.

CDP's Page.screencastFrame only fires on a viewport REPAINT, so the very first navigation (and navigations to pages that paint identically) can leave the live view blank until some later change. This grabs the current viewport via a screenshot (encoded to match the screencast format) and emits it as the next sequence-numbered frame, so callers can force an immediate refresh right after starting the stream and after a navigation settles.

No-op (resolves) when no screencast is running or no page is open — safe to call opportunistically.

Capture a screenshot of the current viewport.

Close the browser and release all resources. Safe to call multiple times — subsequent calls are no-ops.

Run a self-contained function (no closure state; it is serialized into the page) against the live DOM and return its result. Default returns null so adapters without a live DOM don't break; adapters backed by a real page override this. null also means the call timed out.

Execute a single browser action. The action is a discriminated union — implementations should switch on action.Type for exhaustive handling.

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.

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.

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.

Read the visible text of the current page (the rendered text of ). Used by consumers that need page text for agent perception without a screenshot. Returns '' when no page is open (guarded, never throws on a closed adapter).

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.

Restricts where this browser may go, for a browser an agent drives (a test harness leaves it unrestricted). Navigation then opens only http(s) pages and about:blank. With allowedPrivateHosts, a request to a loopback, link-local or private-network host (listed ones, as host or host:port, excepted) is aborted, and a main-frame navigation that lands on one (a redirect) is sent back to about:blank. Can be called again to replace the list.

ponytail: best effort, by hostname, for the main frame (see NavigationGuard.IsPrivateNetworkHost). Gets through: names that resolve to private addresses, WebSockets, service-worker fetches, an iframe whose source redirects to a private host, redirects of the page's own requests, and the redirect request itself (only where it lands is refused). Real isolation is network egress rules on the machine the browser runs on.

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. Maps our CookieEntry to Playwright's cookie format.

Set extra HTTP headers for all requests to a specific domain.

Uses Playwright's page.route() to intercept requests and inject headers for matching domains. The interceptor is set up once on the first call; subsequent calls just update the headers map.

Headers are additive — calling this multiple times for the same domain merges headers (later calls override conflicting keys).

Set localStorage entries for a specific domain.

If the page is already on the target domain, entries are set directly via page.evaluate(). If not (e.g. on about:blank before first navigation), entries are deferred via page.addInitScript() so they run before page scripts on the next navigation — this avoids the origin mismatch that would occur from navigating to https://{domain} when the actual target is a different origin (e.g. http://localhost:4201).

Start capturing the audio playing inside the browser tab and invoke onChunk for each encoded slice.

Mechanism (in-page, headless-safe, no OS audio device, no extension): a capture agent is injected via Playwright page.exposeBinding('__mjAudioChunk', …)

• page.addInitScript(…). The agent watches the DOM for <video> / <audio> elements (a MutationObserver plus an initial scan), taps the FIRST one that is actively playing with element.captureStream(), and feeds its audio tracks to an in-page MediaRecorder({ mimeType: 'audio/webm;codecs=opus' }) with a ~250ms timeslice. Each dataavailable blob is base64-encoded and sent back through the binding, which lands here and is mapped to an AudioCaptureChunk. The agent restarts the recorder when the active element swaps / plays / pauses.

Calling start while a capture is already running is a no-op (the existing capture keeps feeding chunks).

Limitation: only audio routed through a media ELEMENT is captured (covers YouTube and most video/audio sites). Pure Web-Audio-API sound and DRM/EME media (where captureStream() is blocked) are NOT captured — a server-side virtual audio sink is the documented future path for full-fidelity / DRM audio.

Start a CDP-backed live screencast of the viewport.

Obtains a CDP session via context.newCDPSession(page), subscribes to Page.screencastFrame, and for each frame decodes the payload into a ScreencastFrame (with a monotonic SequenceNumber), invokes onFrame, then acks the frame via Page.screencastFrameAck so Chromium continues streaming. Calling start while a screencast is already running is a no-op (the existing session keeps streaming).

Begin 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 the active audio capture (if any): ask the in-page agent to tear down its MediaRecorder + observers, and clear local capture state. Safe to call when no capture is running. Best-effort — teardown errors are swallowed.

Stop the active screencast (if any): tell Chromium to stop streaming, detach the CDP session, and clear screencast state. Safe to call when no screencast is running. Best-effort — teardown errors are swallowed.

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.

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.