TypeScript SDK Reference

match must be a css() or js() Locator — node()/at() are rejected. Use .inAllFrames() to watch every frame and .visible(false) to opt out of the default visibility gate. Pass a ReactionOpts to click a different target (on), change the button/click count, or the poll cadence.

Every request matching opts.patterns is reported once it completes, and "every request" is literal: capture sits in the browser process rather than in a page, so cross-process iframes, workers and service workers are included, the headers are the ones actually put on the wire (Cookie and Sec-* included), and each hop of a redirect chain arrives as its own exchange. Requests are never paused, so the page loads at full speed.

This resolves as soon as the capture is running; onExchange then fires in the background while you drive the browser. The capture is armed only after the subscription exists, so nothing that happens after this resolves is missed. Call NetworkCapture.stop when done — it disarms the capture server-side, which an aborted transport alone does not.

Rejects only on a transport failure - a dead session, a page that is gone, a broken connection. This call has no semantic failure of its own, so there are no error codes to branch on.

The browser scrolls the element into view if needed, moves the cursor along a human-like path, then dispatches a full mouseDown+mouseUp at a randomized point inside the element's bounding rect.

For right-click, double-click, press/release-only, or to override the target frame, pass a ClickOpts object as the second argument.

The browser presses the left mouse button at a pickup point inside the element, drags along a human-like path to (pickupX+offsetX, pickupY+offsetY), then releases. at is not a valid target — drag needs a real element.

Same gesture as dragBy, but the drop destination is in page coordinates rather than relative to the pickup point.

The expression's return value is JSON-serialized server-side and parsed eagerly into .value. When the expression returns a DOM element the .value is null and the element metadata (backendNodeId, isVisible, bounds) is populated instead — use node in subsequent calls to act on it.

The generic T is a TypeScript hint only — there is no runtime validation that the JS expression actually returned that type.

A falsy answer and a broken expression are different outcomes. Returning null, false or undefined is a successful evaluation and resolves normally; an expression that throws or will not compile rejects with a CommandError, so a typo can never read as "the page says null".

Same semantics as evaluate but targets a specific frame instead of the main frame. Useful for evaluating inside OOPIFs (out- of-process iframes) found via getPages. ALL_FRAMES is not supported here.

The browser scrolls the element into view, moves the cursor along a human-like path, clicks to focus, then types the text character- by-character with QWERTZ keyboard simulation and human-like timing.

To overwrite the field instead of appending, pass { clearFirst: true }.

at is not a valid target — fill requires an actual element.

For the case CloudBrowser.startScript cannot cover: a run somebody else launched, or one this page started before it reloaded. Several readers can watch the same session, each with its own buffer.

Only output produced from now on arrives — lines printed before the subscription existed are not kept. A run that has already finished is therefore invisible here; CloudBrowser.listScriptRuns is how you tell that apart from a run that is merely quiet.

State is read in the browser process, so no page needs to be open. Returns undefined when the context has neither a signed-in account nor DBSC sessions.

The shape matches Chrome DevTools' Protocol DOM.Node — useful for piping into agent loops or visualizers that already speak CDP. For a much smaller agent-oriented payload, prefer getObservation instead. The cheap polling endpoint is getDOMHash.

On an <iframe> the one child is the document it hosts, and this call is what starts mirroring that frame.

An id that is simply unknown is not a failure: the call resolves with an empty result.

Computing a hash is much cheaper than transferring the full tree — pair this with getDOM only when the hash differs from your last snapshot.

Prefer this over CloudBrowser.getDOMHash, which serializes the whole tree just to hash it. The two answer different questions: a hash compares content, a revision only says whether this document moved since you last asked.

Rejects only on a transport failure - a dead session, a page that is gone, a broken connection. This call has no semantic failure of its own, so there are no error codes to branch on.

Each frame opens with header lines carrying the URL, the title and the scroll position, then one line per visible element:

`` input#email47 type="email" name="loginId" value="a@b.com" required click "E-Mail" ``

It spans every frame, pierces open and closed shadow roots, enumerates <select> options, and reports live form state: value= is what is typed in right now (passwords as a length), checked= for boxes. The trailing quoted string is always the label or text, never the value, so an empty and a prefilled field stay distinguishable. Because the headers already carry URL, title and scroll offset, this replaces the usual handful of evaluate probes after each step.

On what to do with the result: backendNodeId (the 47 above) is a handle for this session and can be passed straight to click/fill via node. It does not survive a new document, so for anything you write into a script, target with css or js instead — those calls return the backendNodeId they resolved to, which lets you confirm the durable anchor hits the element you saw.

Each PageInfo carries the page's URL, title, viewport and a full nested frame tree (out-of-process iframes are children of the page's main frame).

Walks every frame and returns the first non-empty selection found — useful for "copy what the user highlighted" flows. Returns an empty string when nothing is selected anywhere.

The storage database is read directly in the browser process, so no page needs to be open. Only first-party localStorage is included — sessionStorage is per-tab and not covered.

Live streaming is a two-step, client-offerer handshake: call getStreamConfig, build your peer with the returned servers, create an offer, then pass its SDP to startStream and apply the answer.

Everything but minMemory and averageMemory only ever grows, so polling and diffing two readings gives the cost of what ran in between. The final figures need no call of their own: CloudBrowser.stopBrowser resolves with them.

Useful for visual debugging of agent flows — the overlay stays until the next call. Pass backendNodeId <= 0 to clear any current highlights.

No individual key events are dispatched; the entire string is committed at once via Input.insertText. Whatever element currently has focus receives the text. Use click or fill first if you need a specific element to be focused.

Mirrors what the live-UI overlay does on hover. Elements with pointer-events:none are skipped — the result is the actual click target, not the visually-topmost node. A backendNodeId === 0 in the result means nothing was found.

Only runs in flight — a finished run is reported once on the event stream and then forgotten, so this is not a history. Its use is finding work this caller did not start: a script a previous page left behind, which CloudBrowser.stopScripts needs an id to name.

Registers a one-shot interceptor that intercepts the next request to url and replies with the supplied html and headers instead of going to the network. Useful for snapshotted pages, test fixtures, and offline replays. Pair with navigate to trigger the load.

The browser sends the top of the tree once, then reports only what changed in the part you expanded. Everything else costs a child count per batch, no matter how much churns inside it — which is what makes this usable on a page that rewrites a list sixty times a second, where re-fetching the document on a timer is not.

Expand and collapse as the user opens and closes nodes; that is what moves the boundary of what gets reported. The returned DomMirror holds the tree and exposes expand, collapse and reveal.

The handler runs after each applied batch. mirror.root is a new object whenever anything under it changed and the untouched parts keep their identity, so rendering straight from it with memoized components is cheap.

One mirror covers the whole page as ONE tree. An <iframe> is an ordinary element whose single child is the document it hosts; expanding it fetches that document and starts mirroring the frame, however deeply nested and whether or not it is cross-origin. Unlike the inlining CloudBrowser.getDOM does, these regions stay live — and frames nobody opened cost nothing.

``ts const mirror = await browser.mirrorDom({ pierce: true }, () => { render(mirror.root); }); await mirror.expand(bodyNode); // ... await mirror.stop(); ``

One-shot: consumes the first matching request. Each modification is a plain HeaderModification object literal.

The browser scrolls the target into view first if necessary, then animates the cursor along a human-like path to the element's center (or to the viewport coordinate when target is at).

Returns once the primary main-frame navigation commits (the response is received and a new document is selected), before DOMContentLoaded or load fire. Cross-origin redirects are followed.

Only the keydown half is dispatched — pair with releaseKey for a full press cycle. The event targets whichever element currently has focus.

at is not a valid target — a real <canvas> element is required.

Bodies are stored by the browser, not sent with the exchange, so reading one is a separate call. They stay readable after the capture stops, until the session ends.

The body is fetched in ranges and assembled in memory. For very large bodies, use CloudBrowser.readNetworkBodyRange to process them piece by piece.

A single call returns at most 2 MiB; omit length to read that much. Loop on offset + data.length until it reaches totalSize to stream a large body.

Mirror of pressKey. Same parameter semantics; use this to close a press cycle that was started with pressKey.

An id that is simply unknown is not a failure: the call resolves with an empty result.

The script runs beside the browser, in a V8 isolate of its own rather than in the page, and reaches the document through the engine: a cross-origin <iframe> is read as plain contentDocument with no frame ids anywhere, values come back as live objects it can assign to rather than snapshots, an element can be handed straight to browser.click, and the page sees nothing injected. Steps cost microseconds rather than network round trips, so work that is chatty by nature — polling for a selector, walking a list, following pagination — is affordable there. A guide for it is still to come.

This waits for as long as the script runs, and cannot be bounded: the run id needed to cancel only arrives with the reply. Use CloudBrowser.startScript when the script may outlive the caller's patience, or CloudBrowser.stopScripts to abandon what this session is running.

The capture uses a one-shot surface copy (the same mechanism as CDP Page.captureScreenshot), so it is independent of any active live stream and works with both GPU (hardware) and software compositing.

Whatever scroll container is closest to the element does the scrolling — nested scroll containers and out-of-process iframe chains are walked automatically. at is not a valid target here; scrolling needs a real element.

Sets the option as selected on the targeted <select>, then fires the standard input + change events (unless suppressed via opts.fireEvents = false).

at is not a valid target — select requires an actual <select> element.

Sets the option as selected on the targeted <select>, then fires the standard input + change events (unless suppressed via opts.fireEvents = false).

at is not a valid target — select requires an actual <select> element.

Sets the option as selected on the targeted <select>, then fires the standard input + change events (unless suppressed via opts.fireEvents = false).

at is not a valid target — select requires an actual <select> element.

Call it before navigating. Pair with setCookies() / setStorage() to restore a full persona.

Any request whose URL matches one of the supplied patterns is blocked before it leaves the browser. Patterns are simple URL wildcards (* matches any character span). Pass an empty array to clear the blocklist and let everything through.

Existing cookies with the same (name, domain, path) tuple are overwritten. Pass an empty array for a no-op.

Takes effect for new requests immediately; in-flight requests keep their original routing. Pass an empty proxyHost to clear the proxy and route directly.

Useful for replaying frozen page assets (HTML/JS/CSS/images) without hitting the origin every time. The cache backend itself is configured server-side. Pass an empty patterns array to disable caching for this session.

Accepts the same structure getStorage() returns, so a dump can be fed back verbatim. Existing keys are overwritten. Works without any open page; pages that are already open will not observe the writes until they reload.

Detection covers the common challenge types you run into in the wild. The challenge is completed in-page server-side (the resulting token / bypass cookies are wired into the page automatically), so callers can ignore the returned string.

Use it when the reader lives somewhere else — another tab, or a later createWebSocketBrowser against the same session. Most callers want CloudBrowser.captureNetwork instead, which arms and subscribes together. Calling this again replaces the running capture.

The counterpart to CloudBrowser.runScript, for scripts that are not worth waiting on: a watcher that runs for the life of the session, work that should survive this page. Output arrives at onEvent while the caller gets on with something else, and ScriptRun.wait collects the outcome if it is wanted.

Subscribing has to happen before the launch, because a detached run's output is not kept anywhere — the browser rejects a start with nobody listening rather than discard the script's log and result. This call does both in that order, so nothing the script prints is missed.

An empty runId cancels every run in the session, which is the only form available to a caller that never learned an id — notably one abandoning a CloudBrowser.runScript.

Rejects only on a transport failure. Stopping a stream that is not running is a no-op rather than a failure, so there are no error codes to branch on.

Stopping the returned view detaches this reader and leaves the capture running, since other readers may still be attached.

type is intentionally UNtargeted and loose: it does not locate or focus any element and does NOT pin focus, so the page is free to route keys and move focus between fields mid-stream — ideal for one-time-code / OTP inputs that auto-advance to the next box on each digit. To type one specific field that must stay focused for the whole value, use fill instead (strict, target-bound, per-key focus-verified).

Nothing is focused for you: click (or fill) the field first, or otherwise ensure focus, before calling type.

Shortcut for waitAny(condition, opts). See waitAny for timeout handling, per-locator visible/steady defaults and the list of locators that are not valid wait conditions.

When several conditions are supplied, the first one to match wins; the others are abandoned. The returned WaitResult's .index points to the entry in conditions that matched.

Defaults applied automatically: - timeout: 30000 ms — override via opts.timeoutMs - per-locator visible/steady: true / 500 for css() and js() locators. For js() expressions returning a non-Element value both flags are no-ops. Override with .visible(false) / .steady(ms) on individual locators.

node and at are not valid wait conditions — they only make sense as action targets — and throw at send time.

Returns the matched pattern's index and the captured request. When patternsi.abort is true the request is dropped with an empty 200 response instead of being sent to the network.

Same shape as waitForAnyRequest but on the response phase. When patternsi.abort is true the page receives an empty 200 instead of the real response.

Equivalent to .inFrame(AllFrames). Use this when an element might appear inside any of several frames and you do not want to enumerate them.

Use the frameId from a previous result or CloudBrowser.getPages to target elements inside a known iframe.

Settling defaults to 500ms, so pass 0 to match the instant the element is found. Has no effect for js() expressions that return a non-Element value, nor when used as an action target.

Visibility is required by default, so pass false to wait for DOM presence alone. Has no effect when used as an action target — actions never check visibility before dispatching.

Drives both the assigned exit-IP region and the locale defaults (Accept-Language, timezone fallback) when those are not overridden separately.

When omitted the server picks a fingerprint based on the country code. Pass a known id (e.g. one returned by a previous rental) to keep fingerprints stable across sessions.

Skipping this is not an error, it is a slow leak: the browser's revealed set only grows, and eventually it is no longer filtering anything.

On an <iframe> the one child is the document it hosts, and this call is what starts mirroring that frame. Nothing about the result says a process boundary was crossed; it is a child list like any other.

Use it to focus a node you do not hold — an inspectAtPosition hit, say. You cannot walk up to it yourself: it is not in your tree, so there is nothing to walk from.

The node may be in a frame nobody opened, and that works: the chain comes back crossing the frame boundaries it has to, and those frames start being mirrored, exactly as if you had expanded your way there by hand.

Once it resolves the handler is no longer running, so data it collected is complete. Views from CloudBrowser.streamNetworkExchanges only detach — they never disarm a capture other readers may share.

To stop from inside the handler, call CloudBrowser.stopNetworkCapture instead: stop awaits the reader, which cannot finish while the handler it called is still running.

Rejects only on a transport failure, and the local reader is shut down regardless. Disarming a capture that is not running is a no-op rather than a failure, so there are no error codes to branch on.

Use it to capture for as long as the session lives. It is not needed when you drive the browser yourself and call stop when done.

A script that is executing is interrupted; one parked on an await unwinds at its next operation in the page. Either way the handler sees a finished with stopped set, unless the local reader is torn down first.

Rejects only on a transport failure, and the local reader is detached regardless. Cancelling a run that has already finished is a no-op.

A script that threw is an outcome, not an error: it resolves with success: false. It rejects when the run's fate is unknown — the stream broke or the session died before the script finished.

Resolving means the server confirmed the subscription, so a caller may act on it — arm a network capture, say — without racing the first message.

Useful for clicking inside a canvas, hovering decorative regions, or dispatching events at synthetic positions. Action-only — using it in wait() throws at send time. Note that only click and moveTo accept at; scrollTo, drag, fill and select all require a real element.

Useful when a session id (and its gRPC URL) was persisted across processes and you want to drive it again without renting a new one. Mirrors browserscale-go's ConnectSession. Closing the returned handle via CloudBrowser.stopBrowser releases the rental (calls the stop endpoint) and closes the transport.

Use this from a browser context: the WebSocket transport framing is defined by WebSocketTransport and is served directly by the browserscale session host. The session must already exist server-side; unlike rentBrowser this does not call the rent API. Closing the returned handle (via CloudBrowser.stopBrowser) only closes the transport — the rental stays alive.

When used in CloudBrowser.wait/CloudBrowser.waitAny, the condition requires the element to be visible and to hold still for 500ms before it matches — the API's defaults for a condition that does not set them. Override per call with .visible(false) / .steady(ms) (use .steady(0) to disable the steady check).

When used as an action target (click, fill, …) the visible/steady fields are ignored — there are no corresponding fields on the action requests.

Same wait defaults as css (visible, 500ms steady); these only apply when the expression returns a DOM Element. For non-Element truthy values (boolean, string, number, plain object) both fields are no-ops and the condition matches as soon as the value is truthy. Use .visible(false) / .steady(0) to opt out.