browserscale-ts 1.7.1 → 1.9.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { Transport } from "@connectrpc/connect";
 import type { Locator } from "./locator.ts";
-import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, NetworkCaptureOptions, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult, IceServer, StreamAnswer, ReactionInfo } from "./types.ts";
+import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, NetworkCaptureOptions, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, SessionUsage, WaitResult, IceServer, StreamAnswer, ReactionInfo } from "./types.ts";
 import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ReactionOpts, ScreenshotOpts, ReadCanvasOpts, SelectOpts, WaitOpts } from "./options.ts";
 import type { HeaderModification, RequestPattern } from "./network.ts";
 import { NetworkCapture, type NetworkExchangeHandler } from "./network-capture.ts";
@@ -13,9 +13,7 @@ import type { AuthSession } from "./auth-session.ts";
  * CloudBrowser is the SDK-side handle for an active browserscale browser session.
  *
  * One CloudBrowser corresponds to exactly one browser context, which
- * always has at least one page. The session is implicitly bound to its
- * primary page server-side — the proto's page_id field is currently
- * ignored server-side, so the SDK never sets it.
+ * always has at least one page; its commands act on the primary page.
  *
  * Construct via rentBrowser() / createWebSocketBrowser() — never
  * directly.
@@ -27,7 +25,7 @@ export declare class CloudBrowser {
     private readonly _transport;
     private readonly _fingerprint;
     private readonly _stopFn?;
-    constructor(transport: Transport, sessionId: string, apiKey: string, fingerprint: string, stopFn?: () => Promise<void>);
+    constructor(transport: Transport, sessionId: string, apiKey: string, fingerprint: string, stopFn?: () => Promise<SessionUsage | undefined>);
     /** Returns the unique server-assigned id for this browser session. */
     getSessionId(): string;
     /** Returns the API key used to rent this session. */
@@ -42,12 +40,21 @@ export declare class CloudBrowser {
      * {@link createWebSocketBrowser} the rental stays untouched; only the
      * transport is closed.
      *
-     * @throws UNKNOWN_ERROR - the stop API or the transport close failed
+     * @returns SessionUsage what the session consumed over its whole life, read
+     *   as it was torn down - no {@link CloudBrowser.getUsage} call is needed
+     *   before stopping. Undefined when the server could not report it, and for
+     *   a handle that owns no rental.
+     *
+     * Rejects only when the stop API or the transport close fails. The session is
+     * released either way; retrying a stop is safe.
      *
      * @example
-     * await browser.stopBrowser();
+     * const usage = await browser.stopBrowser();
+     * if (usage) {
+     *   console.log(`ran ${usage.wallTime}s, ${usage.cpuTime}s CPU, peak ${usage.peakMemory} bytes`);
+     * }
      */
-    stopBrowser(): Promise<void>;
+    stopBrowser(): Promise<SessionUsage | undefined>;
     /**
      * Changes the runtime proxy for this session.
      *
@@ -60,7 +67,9 @@ export declare class CloudBrowser {
      * @param proxyUsername - proxy auth user; empty for unauthenticated proxies
      * @param proxyPassword - proxy auth password; empty for unauthenticated proxies
      *
-     * @throws UNKNOWN_ERROR - the proxy could not be applied
+     * 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.
      *
      * @example
      * await browser.setProxy("proxy.example.com", 8080, "user", "pass");
@@ -76,13 +85,36 @@ export declare class CloudBrowser {
      *
      * @returns PageInfo[] for every page currently open in the context
      *
-     * @throws UNKNOWN_ERROR - the pages could not be enumerated
+     * 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.
      *
      * @example
      * const pages = await browser.getPages();
      * for (const p of pages) console.log(p.url, p.title);
      */
     getPages(): Promise<PageInfo[]>;
+    /**
+     * Reports what this session's browser has consumed so far.
+     *
+     * 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: {@link CloudBrowser.stopBrowser} resolves
+     * with them.
+     *
+     * @returns SessionUsage as of now
+     *
+     * Rejects only on a transport failure - a dead session, a broken connection.
+     * This call has no semantic failure of its own, so there are no error codes to
+     * branch on.
+     *
+     * @example
+     * const before = await browser.getUsage();
+     * await browser.navigate("https://example.com");
+     * const after = await browser.getUsage();
+     * console.log(`navigation cost ${after.cpuTime - before.cpuTime}s of CPU`);
+     */
+    getUsage(): Promise<SessionUsage>;
     /**
      * Navigates the page to url.
      *
@@ -96,7 +128,16 @@ export declare class CloudBrowser {
      * @returns NavigateResult with the final resolved URL and the frameId
      *   of the main frame after navigation
      *
-     * @throws UNKNOWN_ERROR - the navigation failed or timed out
+     * @throws timeout - nothing committed before the deadline; the page may still
+     *   be loading, so a longer timeout can be the whole fix
+     * @throws net_error - the URL never loaded: DNS, TLS, a refused connection, or
+     *   a proxy that could not reach it. The message carries the underlying net
+     *   error name, which is what separates a bad proxy from a bad host - worth
+     *   logging, since the two need different fixes
+     * @throws crashed - the renderer died mid-navigation; the page is unusable and
+     *   has to be navigated again
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * await browser.navigate("https://example.com");
@@ -114,7 +155,11 @@ export declare class CloudBrowser {
      * @param html - response body to serve
      * @param opts - optional headers and statusCode (default 200)
      *
-     * @throws UNKNOWN_ERROR - the interceptor could not be installed
+     * @throws timeout - the page never requested the URL, so the prepared
+     *   response had nobody to hand it to; usually the navigation was cancelled
+     *   or redirected away before reaching it
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * await browser.loadHTML("https://example.com", "<h1>hi</h1>");
@@ -133,16 +178,34 @@ export declare class CloudBrowser {
      * 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
+     * {@link CommandError}, so a typo can never read as "the page says null".
+     *
      * @param expression - JavaScript expression evaluated in the main frame
      *
      * @returns EvaluateResult with either value (non-Element) or element
      *   metadata (Element)
      *
-     * @throws UNKNOWN_ERROR - the expression threw or could not be compiled
+     * @throws {@link CommandError} - code `"threw"` (the expression raised; the
+     *   message carries the exception text), `"not_run"` (it could not be
+     *   compiled, or execution never started), `"aborted"` (the browser stopped
+     *   execution) or `"no_context"` (the frame had no live script context)
      *
      * @example
      * const res = await browser.evaluate<string>("document.title");
      * console.log(res.value);
+     *
+     * @example
+     * // Telling a false answer from a broken expression.
+     * try {
+     *   const res = await browser.evaluate<boolean>("window.__ready === true");
+     *   if (!res.value) { /* legitimately not ready yet *\/ }
+     * } catch (e) {
+     *   if (e instanceof CommandError) throw new Error(`expression broken: ${e.message}`);
+     *   throw e;
+     * }
      */
     evaluate<T = unknown>(expression: string): Promise<EvaluateResult<T>>;
     /**
@@ -438,7 +501,9 @@ export declare class CloudBrowser {
      * @returns DOMResult with the JSON string in `.dom` (the `.hash` field
      *   is populated by {@link getDOMHash}, not by this call)
      *
-     * @throws UNKNOWN_ERROR - the DOM could not be retrieved
+     * 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.
      *
      * @example
      * const { dom } = await browser.getDOM();
@@ -456,7 +521,9 @@ export declare class CloudBrowser {
      *
      * @returns 16-char hex string (the first 8 bytes of sha256 of the DOM JSON)
      *
-     * @throws UNKNOWN_ERROR - the hash could not be computed
+     * Rejects only on a transport failure. The hash is computed from a serialized
+     * tree, so there is no semantic failure of its own and no error codes to branch
+     * on.
      *
      * @example
      * const hash = await browser.getDOMHash();
@@ -496,7 +563,11 @@ export declare class CloudBrowser {
      *
      * @returns the observation in the requested format, ready to hand to a model
      *
-     * @throws UNKNOWN_ERROR - the observation could not be produced
+     * @throws not_found - the requested scope root is not on the page, so there
+     *   was nothing to observe. Distinct from an observation that comes back
+     *   empty, which means the scope exists and holds nothing worth reporting
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const obs = await browser.getObservation();
@@ -517,7 +588,11 @@ export declare class CloudBrowser {
      * @returns ScreenshotResult with the base64 image in `dataBase64` and the
      *   physical pixel `width`/`height`
      *
-     * @throws UNKNOWN_ERROR - the screenshot could not be captured
+     * @throws capture_failed - the page had no frame to copy. A page that has not
+     *   produced one yet, or is not being composited at the moment, has nothing to
+     *   hand over; retrying after it renders usually works
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const shot = await browser.screenshot({ format: "png" });
@@ -541,11 +616,15 @@ export declare class CloudBrowser {
      *   canvas `width`/`height`, resolved `frameId`/`backendNodeId` and the
      *   `originClean` flag
      *
-     * @throws INVALID_LOCATOR - target is empty, uses at(x,y), or has multiple targets
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws not_found - no element matched the locator
+     * @throws not_element - the expression was truthy but did not yield an element
+     * @throws not_readable - the target was found but is not a readable canvas
+     *
+     * A target that is empty, uses `at(x, y)` or names several things at once is
+     * rejected before anything is sent. A closed page or a frame that is gone is a
+     * transport failure rather than a code.
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const res = await browser.readCanvas(css("#game canvas"));
@@ -568,7 +647,9 @@ export declare class CloudBrowser {
      *
      * @param patterns - URL wildcards to block; empty array clears the list
      *
-     * @throws UNKNOWN_ERROR - the blocklist could not be applied
+     * 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.
      *
      * @example
      * await browser.setBlockList([
@@ -589,7 +670,9 @@ export declare class CloudBrowser {
      * @param blobName - server-side identifier of the snapshot to serve from
      * @param patterns - URL wildcards to redirect to the cache; empty disables
      *
-     * @throws UNKNOWN_ERROR - the static paths could not be configured
+     * 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.
      *
      * @example
      * await browser.setStaticPaths("snap-2026-05", ["*.example.com/*"]);
@@ -610,7 +693,12 @@ export declare class CloudBrowser {
      *   (the captured method/URL/headers/body; null if intercepted with
      *   no body)
      *
-     * @throws UNKNOWN_ERROR - the wait timed out or no patterns were supplied
+     * @throws timeout - no request matched any pattern before the deadline.
+     *   Nothing occurring is an answer, and it stays distinguishable from a
+     *   connection that died on the way. Supplying no patterns is a caller mistake
+     *   rather than an outcome, and rejects separately
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const { index, request } = await browser.waitForAnyRequest(
@@ -638,6 +726,13 @@ export declare class CloudBrowser {
      * @returns object with `index` (matched pattern index) and `response`
      *   (the captured status/headers/body; null if no body was returned)
      *
+     * @throws timeout - no response matched any pattern before the deadline.
+     *   Nothing occurring is an answer, and it stays distinguishable from a
+     *   connection that died on the way. Supplying no patterns is a caller mistake
+     *   rather than an outcome, and rejects separately
+     *
+     * @see {@link CommandError} for reading the code off the rejection
+     *
      * @example
      * const { index, response } = await browser.waitForAnyResponse(
      *   [{ url: "*\/api/login" }],
@@ -667,7 +762,10 @@ export declare class CloudBrowser {
      *   were actually sent on the wire after modifications were applied;
      *   null when no request payload was reported
      *
-     * @throws UNKNOWN_ERROR - no matching request appeared within the timeout
+     * @throws timeout - no matching request appeared before the deadline, so
+     *   nothing was modified
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const req = await browser.modifyRequest("*\/api/me", {
@@ -708,7 +806,9 @@ export declare class CloudBrowser {
      * @returns NetworkCapture handle for stopping the capture and inspecting how
      *   it ended
      *
-     * @throws UNKNOWN_ERROR - the capture could not be started
+     * 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.
      *
      * @example
      * const capture = await browser.captureNetwork(
@@ -732,7 +832,9 @@ export declare class CloudBrowser {
      *
      * @param opts - which requests to capture and whether to keep bodies
      *
-     * @throws UNKNOWN_ERROR - the capture could not be started
+     * 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.
      */
     startNetworkCapture(opts: NetworkCaptureOptions): Promise<void>;
     /**
@@ -740,7 +842,8 @@ export declare class CloudBrowser {
      *
      * @returns whether a capture was running
      *
-     * @throws UNKNOWN_ERROR - the capture could not be stopped
+     * Rejects only on a transport failure. Stopping a capture that is not running
+     * is a no-op rather than a failure, so there are no error codes to branch on.
      */
     stopNetworkCapture(): Promise<boolean>;
     /**
@@ -757,7 +860,8 @@ export declare class CloudBrowser {
      * @returns NetworkCapture attached to whatever capture is running; onExchange
      *   simply never fires when none is
      *
-     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     * Rejects only on a transport failure: opening the subscription has no semantic
+     * failure of its own.
      */
     streamNetworkExchanges(onExchange: NetworkExchangeHandler): Promise<NetworkCapture>;
     /**
@@ -810,13 +914,21 @@ export declare class CloudBrowser {
      * @param onResync called when the copy had to be rebuilt, after the new tree
      *   is in place. Rebuilding is automatic; this is for telling the user why
      *   their expanded nodes collapsed.
-     * @throws UNKNOWN_ERROR - the mirror could not be started
+     * @throws mirror_failed - the page could not be serialized, usually a document
+     *   that went away while the tree was being built. No mirror is left running
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     mirrorDom(opts: DomMirrorOptions, onChange: DomChangeHandler, onResync?: DomResyncHandler): Promise<DomMirror>;
     /**
      * Starts (or restarts) the page's mirror and returns the main document,
      * without subscribing to changes. {@link CloudBrowser.mirrorDom} is what you
      * normally want; this is the raw command.
+     *
+     * @throws mirror_failed - the page could not be serialized, usually a document
+     *   that went away while the tree was being built. No mirror is left running
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     startDomMirror(opts?: DomMirrorOptions): Promise<DomSnapshot>;
     /** Stops the page's mirror, every frame of it. Idempotent. */
@@ -827,6 +939,17 @@ export declare class CloudBrowser {
      *
      * 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.
+     *
+     * @throws not_mirrored - the page has no mirror, or frameId is not part of the
+     *   one it has; start a mirror first, and after a resync fetch the current tree
+     *   before addressing nodes again
+     * @throws mirror_failed - the subtree could not be serialized, usually a
+     *   document that went away mid-read
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     getDomChildren(backendNodeId: number, frameId?: string, depth?: number): Promise<{
         children: string;
@@ -835,6 +958,13 @@ export declare class CloudBrowser {
     /**
      * Stops reporting changes inside a node, and inside any frame below it.
      * {@link DomMirror.collapse} calls this.
+     *
+     * @throws not_mirrored - the page has no mirror, or frameId is not part of
+     *   the one it has; this is what replaying ids from a tree that has since
+     *   been resynced looks like, so fetch the current tree and address the node
+     *   again
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     releaseDomSubtree(backendNodeId: number, frameId?: string): Promise<void>;
     /**
@@ -842,6 +972,16 @@ export declare class CloudBrowser {
      * with its own children, crossing into frames where it has to and starting
      * the ones it passes through. {@link DomMirror.reveal} calls this and
      * splices it in.
+     *
+     * An id that is simply unknown is not a failure: the call resolves with an
+     * empty result.
+     *
+     * @throws not_mirrored - the page has no mirror, or frameId is not part of the
+     *   one it has
+     * @throws mirror_failed - the path could not be serialized, usually a document
+     *   that went away mid-read
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     revealDomNode(backendNodeId: number, frameId?: string): Promise<{
         path: string;
@@ -856,6 +996,10 @@ export declare class CloudBrowser {
      * 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.
      */
     getDomRevision(frameId?: string): Promise<number>;
     /**
@@ -863,7 +1007,9 @@ export declare class CloudBrowser {
      *
      * @returns CookieParam[], one per cookie in the context
      *
-     * @throws UNKNOWN_ERROR - the cookies could not be read
+     * 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.
      *
      * @example
      * const cookies = await browser.getCookies();
@@ -878,7 +1024,9 @@ export declare class CloudBrowser {
      *
      * @param cookies - cookies to write; empty array is a no-op
      *
-     * @throws UNKNOWN_ERROR - the cookies could not be written
+     * 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.
      *
      * @example
      * await browser.setCookies([
@@ -889,7 +1037,9 @@ export declare class CloudBrowser {
     /**
      * Deletes every cookie in the browser context.
      *
-     * @throws UNKNOWN_ERROR - the cookies could not be cleared
+     * 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.
      *
      * @example
      * await browser.clearCookies();
@@ -908,7 +1058,9 @@ export declare class CloudBrowser {
      *
      * @returns StorageOriginEntry[], one per origin with localStorage data
      *
-     * @throws UNKNOWN_ERROR - the storage could not be read
+     * 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.
      *
      * @example
      * const storage = await browser.getStorage();
@@ -928,7 +1080,9 @@ export declare class CloudBrowser {
      *
      * @param storage - entries to write, grouped by origin
      *
-     * @throws UNKNOWN_ERROR - the storage could not be written
+     * 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.
      *
      * @example
      * await browser.setStorage([
@@ -948,7 +1102,9 @@ export declare class CloudBrowser {
      * @param origin - if set, only this origin's storage is deleted
      *   (e.g. "https://example.com"); omit to delete all origins
      *
-     * @throws UNKNOWN_ERROR - the storage could not be cleared
+     * 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.
      *
      * @example
      * // Wipe one origin.
@@ -968,7 +1124,9 @@ export declare class CloudBrowser {
      *
      * @returns AuthSession, or undefined when there is nothing to export
      *
-     * @throws UNKNOWN_ERROR - the auth session could not be read
+     * 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.
      *
      * @example
      * const auth = await browser.getAuthSession();
@@ -984,7 +1142,9 @@ export declare class CloudBrowser {
      *
      * @param session - session as returned by getAuthSession()
      *
-     * @throws UNKNOWN_ERROR - the auth session could not be written
+     * 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.
      *
      * @example
      * await browser.setAuthSession(saved);
@@ -1006,7 +1166,9 @@ export declare class CloudBrowser {
      * @returns InspectResult with the resolved backendNodeId, frameId, tag
      *   name, trimmed textContent, visibility and bounds
      *
-     * @throws UNKNOWN_ERROR - the hit-test failed
+     * 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.
      *
      * @example
      * const r = await browser.inspectAtPosition(200, 300);
@@ -1023,7 +1185,9 @@ export declare class CloudBrowser {
      * @param frameId - id of the frame the node lives in; empty string
      *   targets the main frame
      *
-     * @throws UNKNOWN_ERROR - the highlight could not be applied
+     * 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.
      *
      * @example
      * await browser.highlightNode(res.backendNodeId, res.frameId);
@@ -1039,7 +1203,11 @@ export declare class CloudBrowser {
      *
      * @param text - the text to insert at the caret
      *
-     * @throws UNKNOWN_ERROR - the text could not be inserted
+     * @throws no_focus - nothing in the page holds focus, so there is no caret to
+     *   insert at; click the field first
+     * @throws busy - another action is already running on this page
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * await browser.insertText("hello world");
@@ -1065,7 +1233,10 @@ export declare class CloudBrowser {
      * @param opts - optional: `clearFirst` clears the focused field (Ctrl+A,
      *   Delete) before typing
      *
-     * @throws UNKNOWN_ERROR - the page/context was torn down mid-stream
+     * `type` has no semantic failure of its own: the keys land wherever focus
+     * happens to be, so there is no target it can miss. Only the page or context
+     * being torn down mid-stream surfaces, and that is a transport failure rather
+     * than a code.
      *
      * @example
      * // OTP field that auto-advances across boxes.
@@ -1088,7 +1259,11 @@ export declare class CloudBrowser {
      *   `modifiers` (bit-flag: Alt=1, Ctrl=2, Meta=4, Shift=8),
      *   `location` (0=standard, 1=left, 2=right, 3=numpad)
      *
-     * @throws UNKNOWN_ERROR - the event could not be dispatched
+     * @throws no_focus - nothing in the page holds focus, so the key has nowhere
+     *   to go; click the field first
+     * @throws busy - another action is already running on this page
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * // Ctrl+A
@@ -1126,7 +1301,9 @@ export declare class CloudBrowser {
      *
      * @returns the selected text, or `""` when nothing is selected
      *
-     * @throws UNKNOWN_ERROR - the selection could not be read
+     * 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.
      *
      * @example
      * const sel = await browser.getSelection();
@@ -1148,8 +1325,10 @@ export declare class CloudBrowser {
      *
      * @returns empty string on success — the solution is applied server-side
      *
-     * @throws UNKNOWN_ERROR - no captcha appeared within timeoutMs, or the
-     *   detected captcha could not be solved within retryAmount attempts
+     * Rejects when no captcha appeared within 	imeoutMs, or when the one that did
+     * could not be solved within
+  etryAmount attempts. Neither carries a code:
+     * solving runs outside the page, so there is no per-command code set here.
      *
      * @example
      * await browser.solveCaptcha({ retryAmount: 2 });
@@ -1169,7 +1348,8 @@ export declare class CloudBrowser {
      *
      * @returns the ICE servers for the client `RTCPeerConnection`
      *
-     * @throws UNKNOWN_ERROR - TURN is not configured on the server
+     * Rejects when TURN is not configured on the server. That is a deployment
+     * condition rather than a per-call outcome, so it carries no code.
      *
      * @example
      * const ice = await browser.getStreamConfig();
@@ -1186,8 +1366,16 @@ export declare class CloudBrowser {
      * @returns the SDP answer to apply as the remote description, plus the
      *   viewport to map input coordinates into
      *
-     * @throws UNKNOWN_ERROR - the offer was empty, TURN is unconfigured, or the
-     *   browser could not negotiate the stream
+     * @throws already_active - a stream is already running on this session; stop it
+     *   before starting another
+     * @throws negotiation_failed - the browser could not agree on a connection. The
+     *   message carries the negotiator's own diagnostic, which is usually where the
+     *   actual cause is
+     *
+     * An empty offer or an unconfigured TURN setup is a caller mistake rather than
+     * an outcome, and rejects separately.
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      *
      * @example
      * const { answerSdp, viewport } = await browser.startStream(offer.sdp);
@@ -1198,17 +1386,18 @@ export declare class CloudBrowser {
      * Tears down the live video stream for the session's page. Safe to call even
      * if no stream is running.
      *
-     * @throws UNKNOWN_ERROR - the stream could not be stopped
+     * 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.
      *
      * @example
      * await browser.stopStream();
      */
     stopStream(): Promise<void>;
     /**
-     * Registers a one-shot "reaction": a background poller (one shared loop per
-     * page) watches for the `match` locator and, as soon as it matches, clicks it
-     * with the full smart-click machinery (scroll, human path, occlusion gate,
-     * evade) — then removes itself. The poller yields to any in-flight input
+     * Registers a one-shot "reaction": the browser watches for the `match`
+     * locator in the background and, as soon as it matches, clicks it the same
+     * way {@link CloudBrowser.click} does (scroll, human path, occlusion check) —
+     * then removes itself. The reaction yields to any in-flight input
      * action and only fires while the pointer is idle, so a reaction naturally
      * slots into the gaps of a retrying foreground action (e.g. it dismisses a
      * newsletter modal blocking a {@link CloudBrowser.click}, after which the
@@ -1247,6 +1436,10 @@ export declare class CloudBrowser {
      *
      * @returns true if a pending reaction with this id existed and was removed
      *
+     * Removing an id that is not registered is a no-op rather than an error, so the
+     * returned boolean - not a rejection - is what tells you whether anything was
+     * there. Rejects only on a transport failure.
+     *
      * @example
      * const removed = await browser.removeReaction(id);
      */
@@ -1257,6 +1450,10 @@ export declare class CloudBrowser {
      *
      * @returns the pending reactions for the page
      *
+     * 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.
+     *
      * @example
      * const pending = await browser.listReactions();
      * for (const r of pending) console.log(r.reactionId, r.matchSelector);
@@ -1285,7 +1482,10 @@ export declare class CloudBrowser {
      * @returns the return value and the script's whole console output. A script
      *   that threw is reported as `success: false`, not as a rejection
      *
-     * @throws UNKNOWN_ERROR - the script could not be delivered to the browser
+     * Rejects only on a transport failure. A script that fails to compile or throws
+     * is not a rejection: the returned result has success: false and
+  esult holds
+     * the message, so a broken script stays distinguishable from a broken connection.
      *
      * @example
      * const result = await browser.runScript(`
@@ -1320,7 +1520,8 @@ export declare class CloudBrowser {
      *
      * @returns ScriptRun handle for awaiting or cancelling the run
      *
-     * @throws UNKNOWN_ERROR - the run could not be started
+     * Rejects only on a transport failure: a script that fails to compile or throws
+     * surfaces on the run itself rather than here.
      *
      * @example
      * const run = await browser.startScript(source, (ev) => {
@@ -1347,7 +1548,8 @@ export declare class CloudBrowser {
      *
      * @returns ScriptFollow handle for stopping the subscription
      *
-     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     * Rejects only on a transport failure: opening the subscription has no semantic
+     * failure of its own.
      *
      * @example
      * const follow = await browser.followScript(runId, (ev) => {
@@ -1372,7 +1574,9 @@ export declare class CloudBrowser {
      * @returns how many runs were cancelled; 0 when the id named nothing in
      *   flight
      *
-     * @throws UNKNOWN_ERROR - the cancel could not be delivered
+     * Rejects only on a transport failure. Cancelling runs that have already
+     * finished, or none at all, is a no-op - read the returned count to learn how
+     * many were actually stopped.
      *
      * @example
      * await browser.stopScripts(""); // abandon everything running
@@ -1388,7 +1592,9 @@ export declare class CloudBrowser {
      *
      * @returns one entry per run still executing
      *
-     * @throws UNKNOWN_ERROR - the session could not be queried
+     * Rejects only on a transport failure - a dead session, a broken connection.
+     * This call has no semantic failure of its own, so there are no error codes to
+     * branch on.
      *
      * @example
      * for (const run of await browser.listScriptRuns()) {