browserscale-ts 1.7.1 → 1.9.0

package/dist/client.js

@@ -2,20 +2,17 @@ import { createClient } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Browser, 
 // request / response schemas
-SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, GetAuthSessionRequestSchema, SetAuthSessionRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, StartNetworkCaptureRequestSchema, StopNetworkCaptureRequestSchema, StartDomMirrorRequestSchema, StopDomMirrorRequestSchema, GetDomChildrenRequestSchema, ReleaseDomSubtreeRequestSchema, RevealDomNodeRequestSchema, GetDomRevisionRequestSchema, StreamDomEventsRequestSchema, StreamNetworkExchangesRequestSchema, RunScriptRequestSchema, StartScriptRequestSchema, StopScriptsRequestSchema, ListScriptRunsRequestSchema, StreamScriptEventsRequestSchema, } from "./gen/wrc_pb.js";
-import { DefaultWaitTimeoutMs } from "./defaults.js";
-import { BrowserScaleError } from "./errors.js";
+SetProxyRequestSchema, GetPagesRequestSchema, GetUsageRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, GetAuthSessionRequestSchema, SetAuthSessionRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, StartNetworkCaptureRequestSchema, StopNetworkCaptureRequestSchema, StartDomMirrorRequestSchema, StopDomMirrorRequestSchema, GetDomChildrenRequestSchema, ReleaseDomSubtreeRequestSchema, RevealDomNodeRequestSchema, GetDomRevisionRequestSchema, StreamDomEventsRequestSchema, StreamNetworkExchangesRequestSchema, RunScriptRequestSchema, StartScriptRequestSchema, StopScriptsRequestSchema, ListScriptRunsRequestSchema, StreamScriptEventsRequestSchema, } from "./gen/wrc_pb.js";
+import { BrowserScaleError, CommandError, throwCommandError } from "./errors.js";
 import { NetworkCapture } from "./network-capture.js";
 import { ScriptFollow, ScriptRun, scriptLogEntryFromProto, } from "./scripts.js";
 import { DomMirror, } from "./dom-mirror.js";
-import { authSessionFromProto, authSessionToProto, cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
+import { authSessionFromProto, authSessionToProto, cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, sessionUsageFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
 /**
  * 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.
@@ -52,15 +49,25 @@ export 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`);
+     * }
      */
     async stopBrowser() {
         if (this._stopFn) {
-            await this._stopFn();
+            return await this._stopFn();
         }
+        return undefined;
     }
     // ──────────────────────────────────────────────────────────────────
     // Context-level
@@ -77,7 +84,9 @@ export 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");
@@ -95,7 +104,8 @@ export class CloudBrowser {
             if (proxyPassword)
                 req.proxyPassword = proxyPassword;
         }
-        await this.client.setProxy(req);
+        const res = await this.client.setProxy(req);
+        throwCommandError("setProxy", res.error);
     }
     /**
      * Returns all open pages (tabs and popups) for this session's browser
@@ -107,7 +117,9 @@ export 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();
@@ -118,8 +130,40 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("getPages", resp.error);
         return resp.pages.map(pageInfoFromProto);
     }
+    /**
+     * 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`);
+     */
+    async getUsage() {
+        const resp = await this.client.getUsage(create(GetUsageRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        throwCommandError("getUsage", resp.error);
+        if (!resp.usage) {
+            throw new BrowserScaleError("getUsage: the server sent no usage");
+        }
+        return sessionUsageFromProto(resp.usage);
+    }
     // ──────────────────────────────────────────────────────────────────
     // Page navigation / content
     // ──────────────────────────────────────────────────────────────────
@@ -136,7 +180,16 @@ export 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");
@@ -150,6 +203,7 @@ export class CloudBrowser {
         if (opts?.timeoutMs)
             req.timeout = opts.timeoutMs;
         const resp = await this.client.navigate(req);
+        throwCommandError("navigate", resp.error);
         return { frameId: resp.frameId, url: resp.url };
     }
     /**
@@ -164,7 +218,11 @@ export 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>");
@@ -180,7 +238,8 @@ export class CloudBrowser {
         });
         if (opts?.statusCode)
             req.statusCode = opts.statusCode;
-        await this.client.loadHTML(req);
+        const res = await this.client.loadHTML(req);
+        throwCommandError("loadHTML", res.error);
     }
     // ──────────────────────────────────────────────────────────────────
     // Evaluation
@@ -197,16 +256,34 @@ export 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;
+     * }
      */
     async evaluate(expression) {
         return this._evaluate("", expression);
@@ -239,6 +316,15 @@ export class CloudBrowser {
         if (frameId)
             req.frameId = frameId;
         const resp = await this.client.evaluate(req);
+        // An expression that threw arrives as success=false in the payload, not as a
+        // transport error, so it is raised here rather than by the call above.
+        if (resp.error) {
+            throw new CommandError({
+                command: "evaluate",
+                code: resp.error.code,
+                message: resp.error.message,
+            });
+        }
         let value = null;
         if (resp.result !== "") {
             try {
@@ -249,6 +335,7 @@ export class CloudBrowser {
             }
         }
         return {
+            success: resp.success,
             value: value,
             backendNodeId: resp.backendNodeId,
             isVisible: resp.isVisible,
@@ -340,7 +427,8 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             conditions: pbConds,
-            timeout: opts?.timeoutMs ?? DefaultWaitTimeoutMs,
+            // Left unset unless the caller passed one, so the API applies its default.
+            timeout: opts?.timeoutMs,
         });
         if (frameId)
             req.frameId = frameId;
@@ -660,7 +748,9 @@ export 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();
@@ -675,6 +765,7 @@ export class CloudBrowser {
         if (opts?.depth !== undefined)
             req.depth = opts.depth;
         const resp = await this.client.getDOM(req);
+        throwCommandError("getDOM", resp.error);
         return { hash: "", dom: resp.dom };
     }
     /**
@@ -689,7 +780,9 @@ export 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();
@@ -738,7 +831,11 @@ export 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();
@@ -771,6 +868,7 @@ export class CloudBrowser {
         if (opts?.frameId !== undefined)
             req.frameId = opts.frameId;
         const resp = await this.client.getObservation(req);
+        throwCommandError("getObservation", resp.error);
         return resp.observation;
     }
     /**
@@ -787,7 +885,11 @@ export 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" });
@@ -803,6 +905,7 @@ export class CloudBrowser {
         if (opts?.quality !== undefined)
             req.quality = opts.quality;
         const resp = await this.client.screenshot(req);
+        throwCommandError("screenshot", resp.error);
         return {
             dataBase64: resp.dataBase64,
             width: resp.width,
@@ -826,11 +929,15 @@ export 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"));
@@ -862,6 +969,7 @@ export class CloudBrowser {
             req.sh = opts.sh;
         }
         const resp = await this.client.readCanvas(req);
+        throwCommandError("readCanvas", resp.error);
         return {
             success: resp.success,
             frameId: resp.frameId,
@@ -885,7 +993,9 @@ export 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([
@@ -894,11 +1004,12 @@ export class CloudBrowser {
      * ]);
      */
     async setBlockList(patterns) {
-        await this.client.setBlockList(create(SetBlockListRequestSchema, {
+        const res = await this.client.setBlockList(create(SetBlockListRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             patterns,
         }));
+        throwCommandError("setBlockList", res.error);
     }
     /**
      * Configures the session to serve cached static responses for requests
@@ -912,18 +1023,21 @@ export 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/*"]);
      */
     async setStaticPaths(blobName, patterns) {
-        await this.client.setStaticPaths(create(SetStaticPathsRequestSchema, {
+        const res = await this.client.setStaticPaths(create(SetStaticPathsRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             blobName,
             patterns,
         }));
+        throwCommandError("setStaticPaths", res.error);
     }
     /**
      * Blocks until the next request whose URL matches one of the supplied
@@ -940,7 +1054,12 @@ export 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(
@@ -963,6 +1082,7 @@ export class CloudBrowser {
         if (opts?.timeoutMs)
             req.timeout = opts.timeoutMs;
         const resp = await this.client.waitForAnyRequest(req);
+        throwCommandError("waitForAnyRequest", resp.error);
         return {
             index: resp.index,
             request: interceptedRequestFromProto(resp.request),
@@ -981,6 +1101,13 @@ export 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" }],
@@ -1002,6 +1129,7 @@ export class CloudBrowser {
         if (opts?.timeoutMs)
             req.timeout = opts.timeoutMs;
         const resp = await this.client.waitForAnyResponse(req);
+        throwCommandError("waitForAnyResponse", resp.error);
         return {
             index: resp.index,
             response: interceptedResponseFromProto(resp.response),
@@ -1023,7 +1151,10 @@ export 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", {
@@ -1047,6 +1178,7 @@ export class CloudBrowser {
         if (opts?.timeoutMs)
             req.timeout = opts.timeoutMs;
         const resp = await this.client.modifyRequest(req);
+        throwCommandError("modifyRequest", resp.error);
         return interceptedRequestFromProto(resp.request);
     }
     // ──────────────────────────────────────────────────────────────────
@@ -1076,7 +1208,9 @@ export 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(
@@ -1112,29 +1246,34 @@ export 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.
      */
     async startNetworkCapture(opts) {
-        await this.client.startNetworkCapture(create(StartNetworkCaptureRequestSchema, {
+        const res = await this.client.startNetworkCapture(create(StartNetworkCaptureRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             patterns: opts.patterns ?? [],
             bodies: opts.bodies ?? "none",
             bodyPatterns: opts.bodyPatterns ?? [],
         }));
+        throwCommandError("startNetworkCapture", res.error);
     }
     /**
      * Disarms the session's capture.
      *
      * @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.
      */
     async stopNetworkCapture() {
         const resp = await this.client.stopNetworkCapture(create(StopNetworkCaptureRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("stopNetworkCapture", resp.error);
         return resp.stopped;
     }
     /**
@@ -1151,7 +1290,8 @@ export 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.
      */
     async streamNetworkExchanges(onExchange) {
         return this.subscribeNetworkExchanges(onExchange);
@@ -1233,7 +1373,10 @@ export 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
      */
     async mirrorDom(opts, onChange, onResync) {
         const abort = new AbortController();
@@ -1282,6 +1425,11 @@ export class CloudBrowser {
      * 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
      */
     async startDomMirror(opts = {}) {
         const req = create(StartDomMirrorRequestSchema, {
@@ -1293,6 +1441,7 @@ export class CloudBrowser {
         if (opts.pierce !== undefined)
             req.pierce = opts.pierce;
         const resp = await this.client.startDomMirror(req);
+        throwCommandError("startDomMirror", resp.error);
         return {
             root: resp.root,
             frameId: resp.frameId,
@@ -1301,10 +1450,11 @@ export class CloudBrowser {
     }
     /** Stops the page's mirror, every frame of it. Idempotent. */
     async stopDomMirror() {
-        await this.client.stopDomMirror(create(StopDomMirrorRequestSchema, {
+        const res = await this.client.stopDomMirror(create(StopDomMirrorRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("stopDomMirror", res.error);
     }
     /**
      * Fetches a node's children and starts reporting changes inside them.
@@ -1312,6 +1462,17 @@ export 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
      */
     async getDomChildren(backendNodeId, frameId = "", depth) {
         const req = create(GetDomChildrenRequestSchema, {
@@ -1324,11 +1485,19 @@ export class CloudBrowser {
         if (depth !== undefined)
             req.depth = depth;
         const resp = await this.client.getDomChildren(req);
+        throwCommandError("getDomChildren", resp.error);
         return { children: resp.children, seq: Number(resp.seq) };
     }
     /**
      * 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
      */
     async releaseDomSubtree(backendNodeId, frameId = "") {
         const req = create(ReleaseDomSubtreeRequestSchema, {
@@ -1338,13 +1507,24 @@ export class CloudBrowser {
         });
         if (frameId)
             req.frameId = frameId;
-        await this.client.releaseDomSubtree(req);
+        const res = await this.client.releaseDomSubtree(req);
+        throwCommandError("releaseDomSubtree", res.error);
     }
     /**
      * Returns the chain from the main document down to a node, each ancestor
      * 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
      */
     async revealDomNode(backendNodeId, frameId = "") {
         const req = create(RevealDomNodeRequestSchema, {
@@ -1355,6 +1535,7 @@ export class CloudBrowser {
         if (frameId)
             req.frameId = frameId;
         const resp = await this.client.revealDomNode(req);
+        throwCommandError("revealDomNode", resp.error);
         return { path: resp.path, seq: Number(resp.seq) };
     }
     /**
@@ -1366,6 +1547,10 @@ export 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.
      */
     async getDomRevision(frameId = "") {
         const req = create(GetDomRevisionRequestSchema, {
@@ -1375,6 +1560,7 @@ export class CloudBrowser {
         if (frameId)
             req.frameId = frameId;
         const resp = await this.client.getDomRevision(req);
+        throwCommandError("getDomRevision", resp.error);
         return Number(resp.revision);
     }
     // ──────────────────────────────────────────────────────────────────
@@ -1385,7 +1571,9 @@ export 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();
@@ -1396,6 +1584,7 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("getCookies", resp.error);
         return resp.cookies.map(cookieParamFromProto);
     }
     /**
@@ -1406,7 +1595,9 @@ export 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([
@@ -1414,25 +1605,29 @@ export class CloudBrowser {
      * ]);
      */
     async setCookies(cookies) {
-        await this.client.setCookies(create(SetCookiesRequestSchema, {
+        const res = await this.client.setCookies(create(SetCookiesRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             cookies: cookieParamsToProto(cookies),
         }));
+        throwCommandError("setCookies", res.error);
     }
     /**
      * 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();
      */
     async clearCookies() {
-        await this.client.clearCookies(create(ClearCookiesRequestSchema, {
+        const res = await this.client.clearCookies(create(ClearCookiesRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("clearCookies", res.error);
     }
     // ──────────────────────────────────────────────────────────────────
     // Storage (localStorage)
@@ -1450,7 +1645,9 @@ export 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();
@@ -1466,6 +1663,7 @@ export class CloudBrowser {
         if (origin)
             req.origin = origin;
         const resp = await this.client.getStorage(req);
+        throwCommandError("getStorage", resp.error);
         return resp.storage.map(storageEntryFromProto);
     }
     /**
@@ -1479,7 +1677,9 @@ export 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([
@@ -1493,11 +1693,12 @@ export class CloudBrowser {
      * ]);
      */
     async setStorage(storage) {
-        await this.client.setStorage(create(SetStorageRequestSchema, {
+        const res = await this.client.setStorage(create(SetStorageRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             storage: storageEntriesToProto(storage),
         }));
+        throwCommandError("setStorage", res.error);
     }
     /**
      * Deletes localStorage in the browser context.
@@ -1505,7 +1706,9 @@ export 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.
@@ -1521,7 +1724,8 @@ export class CloudBrowser {
         });
         if (origin)
             req.origin = origin;
-        await this.client.clearStorage(req);
+        const res = await this.client.clearStorage(req);
+        throwCommandError("clearStorage", res.error);
     }
     // ──────────────────────────────────────────────────────────────────
     // Auth / DBSC (portable signed-in persona)
@@ -1536,7 +1740,9 @@ export 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();
@@ -1547,6 +1753,7 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("getAuthSession", resp.error);
         return resp.session ? authSessionFromProto(resp.session) : undefined;
     }
     /**
@@ -1558,18 +1765,21 @@ export 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);
      * await browser.navigate("https://mail.google.com");
      */
     async setAuthSession(session) {
-        await this.client.setAuthSession(create(SetAuthSessionRequestSchema, {
+        const res = await this.client.setAuthSession(create(SetAuthSessionRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             session: authSessionToProto(session),
         }));
+        throwCommandError("setAuthSession", res.error);
     }
     // ──────────────────────────────────────────────────────────────────
     // Devtools / live-UI helpers
@@ -1589,7 +1799,9 @@ export 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);
@@ -1602,6 +1814,7 @@ export class CloudBrowser {
             x,
             y,
         }));
+        throwCommandError("inspectAtPosition", resp.error);
         return {
             backendNodeId: resp.backendNodeId,
             frameId: resp.frameId,
@@ -1621,7 +1834,9 @@ export 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);
@@ -1634,7 +1849,8 @@ export class CloudBrowser {
         });
         if (frameId)
             req.frameId = frameId;
-        await this.client.highlightNode(req);
+        const res = await this.client.highlightNode(req);
+        throwCommandError("highlight", res.error);
     }
     /**
      * Pastes text at the current caret using IME-style input.
@@ -1646,17 +1862,22 @@ export 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");
      */
     async insertText(text) {
-        await this.client.insertText(create(InsertTextRequestSchema, {
+        const res = await this.client.insertText(create(InsertTextRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
             text,
         }));
+        throwCommandError("insertText", res.error);
     }
     /**
      * Types `text` into the currently focused element as a per-key stream of real
@@ -1678,7 +1899,10 @@ export 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.
@@ -1693,7 +1917,7 @@ export class CloudBrowser {
         });
         if (opts?.clearFirst)
             req.clearFirst = true;
-        await this.client.type(req);
+        throwCommandError("type", (await this.client.type(req)).error);
     }
     /**
      * Fires a single key-down event.
@@ -1708,7 +1932,11 @@ export 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
@@ -1727,7 +1955,8 @@ export class CloudBrowser {
             req.modifiers = opts.modifiers;
         if (opts?.location !== undefined)
             req.location = opts.location;
-        await this.client.pressKey(req);
+        const res = await this.client.pressKey(req);
+        throwCommandError("pressKey", res.error);
     }
     /**
      * Fires a single key-up event.
@@ -1753,7 +1982,8 @@ export class CloudBrowser {
             req.modifiers = opts.modifiers;
         if (opts?.location !== undefined)
             req.location = opts.location;
-        await this.client.releaseKey(req);
+        const res = await this.client.releaseKey(req);
+        throwCommandError("releaseKey", res.error);
     }
     /**
      * Returns the current text selection.
@@ -1764,7 +1994,9 @@ export 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();
@@ -1775,6 +2007,7 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("getSelection", resp.error);
         return resp.text;
     }
     // ──────────────────────────────────────────────────────────────────
@@ -1795,8 +2028,10 @@ export 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 });
@@ -1824,7 +2059,8 @@ export 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();
@@ -1851,8 +2087,16 @@ export 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);
@@ -1864,6 +2108,7 @@ export class CloudBrowser {
             apiKey: this.apiKey,
             offerSdp,
         }));
+        throwCommandError("startStream", resp.error);
         return {
             answerSdp: resp.answerSdp,
             viewport: resp.viewport
@@ -1875,25 +2120,27 @@ export 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();
      */
     async stopStream() {
-        await this.client.stopStream(create(StopStreamRequestSchema, {
+        const res = await this.client.stopStream(create(StopStreamRequestSchema, {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("stopStream", res.error);
     }
     // ──────────────────────────────────────────────────────────────────
     // Reactions
     // ──────────────────────────────────────────────────────────────────
     /**
-     * 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
@@ -1951,6 +2198,7 @@ export class CloudBrowser {
         if (opts?.intervalMs)
             req.interval = opts.intervalMs;
         const resp = await this.client.addReaction(req);
+        throwCommandError("addReaction", resp.error);
         return resp.reactionId;
     }
     /**
@@ -1961,6 +2209,10 @@ export 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);
      */
@@ -1970,6 +2222,7 @@ export class CloudBrowser {
             apiKey: this.apiKey,
             reactionId,
         }));
+        throwCommandError("removeReaction", resp.error);
         return resp.removed;
     }
     /**
@@ -1978,6 +2231,10 @@ export 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);
@@ -1987,6 +2244,7 @@ export class CloudBrowser {
             sessionId: this.sessionId,
             apiKey: this.apiKey,
         }));
+        throwCommandError("listReactions", resp.error);
         return resp.reactions.map((r) => ({
             reactionId: r.reactionId,
             matchSelector: r.matchSelector ?? "",
@@ -2023,7 +2281,10 @@ export 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(`
@@ -2071,7 +2332,8 @@ export 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) => {
@@ -2156,7 +2418,8 @@ export 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) => {
@@ -2189,7 +2452,9 @@ export 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
@@ -2212,7 +2477,9 @@ export 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()) {