browserscale-ts 1.0.1 → 1.2.0

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { Transport } from "@connectrpc/connect";
 import type { Locator } from "./locator.ts";
-import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, ObservationResult, PageInfo, ScreenshotResult, SelectOptionResult, WaitResult } from "./types.ts";
-import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ScreenshotOpts, SelectOpts, WaitOpts } from "./options.ts";
+import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, ObservationResult, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult } from "./types.ts";
+import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ScreenshotOpts, ReadCanvasOpts, SelectOpts, WaitOpts } from "./options.ts";
 import type { HeaderModification, RequestPattern } from "./network.ts";
 import type { CookieParam } from "./cookies.ts";
 import type { StorageOriginEntry } from "./storage.ts";
@@ -195,7 +195,10 @@ export declare class CloudBrowser {
      *
      * @returns WaitResult for the first matching condition
      *
-     * @throws UNKNOWN_ERROR - the wait timed out or a condition was invalid
+     * @throws {@link WaitError} - no condition matched before the deadline;
+     *   `.conditions` holds the per-condition breakdown of why each never matched
+     * @throws {@link BrowserScaleError} - a condition was invalid, or a
+     *   server/transport error occurred
      *
      * @example
      * const r = await browser.waitAny(
@@ -223,15 +226,18 @@ export declare class CloudBrowser {
      *   post-scroll isVisible, element bounds, and the root-viewport
      *   (rootX, rootY) where the click landed
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws CLICK_FAILED - the click could not be dispatched
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link ClickError} - the target was found but the click could not
+     *   land because another element covered it; `.code`, `.occluder` and
+     *   `.result` describe the blocker and the resolved coordinates
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (element not found, frame not found, timeout, page closed)
      *
      * @example
-     * await browser.click(css("button.submit"));
+     * try {
+     *   await browser.click(css("button.submit"));
+     * } catch (e) {
+     *   if (e instanceof ClickError) console.log(e.code, e.occluder?.tagName);
+     * }
      *
      * @example
      * // Right double-click on a context menu trigger.
@@ -257,12 +263,10 @@ export declare class CloudBrowser {
      * @returns ElementResult with success, resolved frameId, backendNodeId
      *   and the root-viewport (rootX, rootY) where the element was clicked
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws FILL_FAILED - the input could not be filled
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link FillError} - the field could not be focused/typed; `.code`
+     *   and `.clickError` (the underlying click-core failure) describe why
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (element not found, frame not found, timeout, page closed)
      *
      * @example
      * await browser.fill(css("input[name=email]"), "user@example.com");
@@ -285,7 +289,9 @@ export declare class CloudBrowser {
      *   post-scroll isVisible, element bounds and the root-viewport
      *   (rootX, rootY) where the cursor ended up
      *
-     * @throws UNKNOWN_ERROR - the move could not be completed
+     * @throws {@link MoveError} - the target could not be located (`.code` is
+     *   `"not_found"`); `.result` carries the resolved payload
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.moveTo(css("nav .menu"));
@@ -305,7 +311,9 @@ export declare class CloudBrowser {
      * @returns ElementResult with the resolved frameId, backendNodeId,
      *   post-scroll isVisible and the element's bounds after the scroll
      *
-     * @throws UNKNOWN_ERROR - the element could not be scrolled into view
+     * @throws {@link ScrollError} - the target could not be located/scrolled
+     *   (`.code` is `"not_found"`); `.result` carries the resolved payload
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.scrollTo(css("#footer"));
@@ -327,7 +335,9 @@ export declare class CloudBrowser {
      * @returns DragResult with the resolved frameId, backendNodeId and the
      *   final cursor position (rootX, rootY) where the drop happened
      *
-     * @throws UNKNOWN_ERROR - the drag could not be performed
+     * @throws {@link DragError} - the source could not be acquired/pressed;
+     *   `.code` and `.clickError` describe the underlying click-core failure
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.dragBy(css(".slider .handle"), 120, 0);
@@ -346,7 +356,9 @@ export declare class CloudBrowser {
      * @returns DragResult with the resolved frameId, backendNodeId and the
      *   final cursor position (rootX, rootY) where the drop happened
      *
-     * @throws UNKNOWN_ERROR - the drag could not be performed
+     * @throws {@link DragError} - the source could not be acquired/pressed;
+     *   `.code` and `.clickError` describe the underlying click-core failure
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.dragTo(css(".card"), 800, 400);
@@ -371,13 +383,10 @@ export declare class CloudBrowser {
      * @returns SelectOptionResult with the resolved selectedIndex,
      *   selectedValue and selectedText after the change
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws SELECT_FAILED - the option could not be selected
-     *   (out of range, or element is not a `<select>`)
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link SelectOptionError} - the option could not be selected;
+     *   `.code` is `"not_found"` (no `<select>`) or `"option_not_found"`
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (frame not found, timeout, page closed)
      *
      * @example
      * await browser.selectByIndex(css("select#country"), 2);
@@ -495,6 +504,40 @@ export declare class CloudBrowser {
      * await fs.writeFile("page.png", Buffer.from(shot.dataBase64, "base64"));
      */
     screenshot(opts?: ScreenshotOpts): Promise<ScreenshotResult>;
+    /**
+     * Reads the pixels of a <canvas> element directly in the renderer,
+     * bypassing the origin-clean (tainted) security check and without executing
+     * any page JavaScript — so cross-origin/tainted canvases (common in
+     * captchas) read fine where a normal `toDataURL` / `getImageData` would
+     * throw a SecurityError.
+     *
+     * {@link at} is not a valid target — a real <canvas> element is required.
+     *
+     * @param target - locator for the <canvas>; {@link css}, {@link js} or {@link node}
+     * @param opts - optional `format`, `quality`, sub-rectangle and frame
+     *   override; see {@link ReadCanvasOpts}
+     *
+     * @returns ReadCanvasResult with the base64 image in `dataBase64`, the
+     *   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
+     *
+     * @example
+     * const res = await browser.readCanvas(css("#game canvas"));
+     * await fs.writeFile("canvas.png", Buffer.from(res.dataBase64, "base64"));
+     *
+     * @example
+     * // Read the left half as JPEG at quality 80.
+     * const res = await browser.readCanvas(css("canvas"), {
+     *   format: "jpeg", quality: 80, sw: 150, sh: 300,
+     * });
+     */
+    readCanvas(target: Locator, opts?: ReadCanvasOpts): Promise<ReadCanvasResult>;
     /**
      * Replaces the session's URL blocklist.
      *

package/dist/client.js

@@ -2,10 +2,10 @@ 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, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, } from "./gen/wrc_pb.js";
+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, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, } from "./gen/wrc_pb.js";
 import { DefaultWaitTimeoutMs } from "./defaults.js";
 import { BrowserScaleError } from "./errors.js";
-import { cookieParamFromProto, cookieParamsToProto, dragResultFromProto, elementFields, elementResultFromProto, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, waitResultFromProto, } from "./internal/convert.js";
+import { cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, 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.
  *
@@ -293,7 +293,10 @@ export class CloudBrowser {
      *
      * @returns WaitResult for the first matching condition
      *
-     * @throws UNKNOWN_ERROR - the wait timed out or a condition was invalid
+     * @throws {@link WaitError} - no condition matched before the deadline;
+     *   `.conditions` holds the per-condition breakdown of why each never matched
+     * @throws {@link BrowserScaleError} - a condition was invalid, or a
+     *   server/transport error occurred
      *
      * @example
      * const r = await browser.waitAny(
@@ -338,8 +341,7 @@ export class CloudBrowser {
         });
         if (frameId)
             req.frameId = frameId;
-        const resp = await this.client.waitForAny(req);
-        return waitResultFromProto(resp);
+        return unwrapWait(await this.client.waitForAny(req));
     }
     // ──────────────────────────────────────────────────────────────────
     // Element actions
@@ -362,15 +364,18 @@ export class CloudBrowser {
      *   post-scroll isVisible, element bounds, and the root-viewport
      *   (rootX, rootY) where the click landed
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws CLICK_FAILED - the click could not be dispatched
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link ClickError} - the target was found but the click could not
+     *   land because another element covered it; `.code`, `.occluder` and
+     *   `.result` describe the blocker and the resolved coordinates
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (element not found, frame not found, timeout, page closed)
      *
      * @example
-     * await browser.click(css("button.submit"));
+     * try {
+     *   await browser.click(css("button.submit"));
+     * } catch (e) {
+     *   if (e instanceof ClickError) console.log(e.code, e.occluder?.tagName);
+     * }
      *
      * @example
      * // Right double-click on a context menu trigger.
@@ -389,8 +394,7 @@ export class CloudBrowser {
             req.clickCount = opts.clickCount;
         if (opts?.action)
             req.action = opts.action;
-        const resp = await this.client.click(req);
-        return elementResultFromProto(resp);
+        return unwrapClick(await this.client.click(req));
     }
     /**
      * Clicks the target and types text into it, appending to any existing
@@ -411,12 +415,10 @@ export class CloudBrowser {
      * @returns ElementResult with success, resolved frameId, backendNodeId
      *   and the root-viewport (rootX, rootY) where the element was clicked
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws FILL_FAILED - the input could not be filled
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link FillError} - the field could not be focused/typed; `.code`
+     *   and `.clickError` (the underlying click-core failure) describe why
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (element not found, frame not found, timeout, page closed)
      *
      * @example
      * await browser.fill(css("input[name=email]"), "user@example.com");
@@ -435,8 +437,7 @@ export class CloudBrowser {
         });
         if (opts?.clearFirst)
             req.clearFirst = true;
-        const resp = await this.client.fill(req);
-        return elementResultFromProto(resp);
+        return unwrapFill(await this.client.fill(req));
     }
     /**
      * Moves the mouse cursor over the given target.
@@ -451,7 +452,9 @@ export class CloudBrowser {
      *   post-scroll isVisible, element bounds and the root-viewport
      *   (rootX, rootY) where the cursor ended up
      *
-     * @throws UNKNOWN_ERROR - the move could not be completed
+     * @throws {@link MoveError} - the target could not be located (`.code` is
+     *   `"not_found"`); `.result` carries the resolved payload
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.moveTo(css("nav .menu"));
@@ -463,8 +466,7 @@ export class CloudBrowser {
             apiKey: this.apiKey,
             ...elementFields(target),
         });
-        const resp = await this.client.moveTo(req);
-        return elementResultFromProto(resp);
+        return unwrapMove(await this.client.moveTo(req));
     }
     /**
      * Scrolls the given element into view.
@@ -480,7 +482,9 @@ export class CloudBrowser {
      * @returns ElementResult with the resolved frameId, backendNodeId,
      *   post-scroll isVisible and the element's bounds after the scroll
      *
-     * @throws UNKNOWN_ERROR - the element could not be scrolled into view
+     * @throws {@link ScrollError} - the target could not be located/scrolled
+     *   (`.code` is `"not_found"`); `.result` carries the resolved payload
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.scrollTo(css("#footer"));
@@ -492,8 +496,7 @@ export class CloudBrowser {
             apiKey: this.apiKey,
             ...elementFields(target),
         });
-        const resp = await this.client.scrollTo(req);
-        return elementResultFromProto(resp);
+        return unwrapScroll(await this.client.scrollTo(req));
     }
     /**
      * Picks up the target and drops it at an offset relative to the pickup
@@ -511,7 +514,9 @@ export class CloudBrowser {
      * @returns DragResult with the resolved frameId, backendNodeId and the
      *   final cursor position (rootX, rootY) where the drop happened
      *
-     * @throws UNKNOWN_ERROR - the drag could not be performed
+     * @throws {@link DragError} - the source could not be acquired/pressed;
+     *   `.code` and `.clickError` describe the underlying click-core failure
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.dragBy(css(".slider .handle"), 120, 0);
@@ -532,7 +537,9 @@ export class CloudBrowser {
      * @returns DragResult with the resolved frameId, backendNodeId and the
      *   final cursor position (rootX, rootY) where the drop happened
      *
-     * @throws UNKNOWN_ERROR - the drag could not be performed
+     * @throws {@link DragError} - the source could not be acquired/pressed;
+     *   `.code` and `.clickError` describe the underlying click-core failure
+     * @throws {@link BrowserScaleError} - invalid locator or a server/transport error
      *
      * @example
      * await browser.dragTo(css(".card"), 800, 400);
@@ -555,8 +562,7 @@ export class CloudBrowser {
             req.absoluteX = spec.absoluteX;
         if (spec.absoluteY !== undefined)
             req.absoluteY = spec.absoluteY;
-        const resp = await this.client.drag(req);
-        return dragResultFromProto(resp);
+        return unwrapDrag(await this.client.drag(req));
     }
     /**
      * Picks the `<option>` at the zero-based index inside the targeted
@@ -576,13 +582,10 @@ export class CloudBrowser {
      * @returns SelectOptionResult with the resolved selectedIndex,
      *   selectedValue and selectedText after the change
      *
-     * @throws INVALID_LOCATOR - target is empty or has multiple targets set
-     * @throws ELEMENT_NOT_FOUND - no element matched the locator
-     * @throws FRAME_NOT_FOUND - the requested frame does not exist
-     * @throws SELECT_FAILED - the option could not be selected
-     *   (out of range, or element is not a `<select>`)
-     * @throws TIMEOUT - the operation exceeded the server-side timeout
-     * @throws PAGE_NOT_ALIVE - the page has been closed
+     * @throws {@link SelectOptionError} - the option could not be selected;
+     *   `.code` is `"not_found"` (no `<select>`) or `"option_not_found"`
+     * @throws {@link BrowserScaleError} - invalid locator, or a server/transport
+     *   error (frame not found, timeout, page closed)
      *
      * @example
      * await browser.selectByIndex(css("select#country"), 2);
@@ -630,12 +633,7 @@ export class CloudBrowser {
         withKey(req);
         if (opts?.fireEvents === false)
             req.fireEvents = false;
-        const resp = await this.client.selectOption(req);
-        return {
-            selectedIndex: resp.selectedIndex,
-            selectedValue: resp.selectedValue,
-            selectedText: resp.selectedText,
-        };
+        return unwrapSelect(await this.client.selectOption(req));
     }
     // ──────────────────────────────────────────────────────────────────
     // DOM / observation
@@ -772,6 +770,69 @@ export class CloudBrowser {
             height: resp.height,
         };
     }
+    /**
+     * Reads the pixels of a <canvas> element directly in the renderer,
+     * bypassing the origin-clean (tainted) security check and without executing
+     * any page JavaScript — so cross-origin/tainted canvases (common in
+     * captchas) read fine where a normal `toDataURL` / `getImageData` would
+     * throw a SecurityError.
+     *
+     * {@link at} is not a valid target — a real <canvas> element is required.
+     *
+     * @param target - locator for the <canvas>; {@link css}, {@link js} or {@link node}
+     * @param opts - optional `format`, `quality`, sub-rectangle and frame
+     *   override; see {@link ReadCanvasOpts}
+     *
+     * @returns ReadCanvasResult with the base64 image in `dataBase64`, the
+     *   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
+     *
+     * @example
+     * const res = await browser.readCanvas(css("#game canvas"));
+     * await fs.writeFile("canvas.png", Buffer.from(res.dataBase64, "base64"));
+     *
+     * @example
+     * // Read the left half as JPEG at quality 80.
+     * const res = await browser.readCanvas(css("canvas"), {
+     *   format: "jpeg", quality: 80, sw: 150, sh: 300,
+     * });
+     */
+    async readCanvas(target, opts) {
+        // A real <canvas> is required — at(x,y) coordinates are not valid here.
+        target.validateTarget("readCanvas", false);
+        const req = create(ReadCanvasRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            ...elementFields(target, opts?.inFrame),
+        });
+        if (opts?.format !== undefined)
+            req.format = opts.format;
+        if (opts?.quality !== undefined)
+            req.quality = opts.quality;
+        if (opts?.sw !== undefined && opts?.sh !== undefined &&
+            opts.sw > 0 && opts.sh > 0) {
+            req.sx = opts.sx ?? 0;
+            req.sy = opts.sy ?? 0;
+            req.sw = opts.sw;
+            req.sh = opts.sh;
+        }
+        const resp = await this.client.readCanvas(req);
+        return {
+            success: resp.success,
+            frameId: resp.frameId,
+            backendNodeId: resp.backendNodeId,
+            dataBase64: resp.dataBase64,
+            width: resp.width,
+            height: resp.height,
+            originClean: resp.originClean,
+        };
+    }
     // ──────────────────────────────────────────────────────────────────
     // Network interception
     // ──────────────────────────────────────────────────────────────────

package/dist/errors.d.ts

@@ -1,18 +1,167 @@
+import type { DragResult, ElementResult, OccluderInfo, SelectOptionResult, WaitConditionStatus, WaitResult } from "./types.ts";
 /**
- * BrowserScaleError is the single error type thrown by all SDK methods. It wraps
- * either:
+ * BrowserScaleError is the base class for every error thrown by the SDK. It
+ * wraps either:
  *   - a client-side validation failure (bad locator, missing patterns, …)
  *   - a server-side gRPC error (Connect's ConnectError, available as `cause`)
  *
- * Catch it with `instanceof BrowserScaleError`:
+ * Semantic action failures (an occluded click, a wait timeout, an option that
+ * did not exist, …) are thrown as the typed subclasses below, each carrying the
+ * same structured detail the Go SDK exposes via `errors.As` — plus the partial
+ * result of the attempted action on `.result`, so a single `catch` gives you
+ * both the diagnostics and the resolved coordinates.
+ *
+ * Catch the base for anything, or narrow to a subclass for the detail:
  *
  *   try {
  *     await browser.click(css("#btn"));
  *   } catch (e) {
- *     if (e instanceof BrowserScaleError) { ... }
+ *     if (e instanceof ClickError) console.log(e.code, e.occluder?.tagName);
+ *     else if (e instanceof BrowserScaleError) { ... }
  *   }
  */
 export declare class BrowserScaleError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/**
+ * ClickError is thrown by {@link CloudBrowser.click} when the click did not
+ * land — the target was found but another element covered the intended point.
+ * `occluder` describes the blocker; `result` carries the resolved element and
+ * coordinates (success is false).
+ *
+ * It is also nested under {@link FillError} / {@link DragError} as the
+ * underlying click-core failure; in that nested form `result` is undefined
+ * (the partial result lives on the outer error).
+ */
+export declare class ClickError extends BrowserScaleError {
+    /**
+     * Machine-stable failure code, e.g. `"occluded_no_reachable_point"` (target
+     * fully covered, no exposed part reachable), `"occluded_after_evade"` (a
+     * reposition was tried but the target was still covered) or `"not_found"`.
+     */
+    readonly code: string;
+    /** The intercepting element (present for occlusion codes). */
+    readonly occluder?: OccluderInfo;
+    /** Whether a pointer reposition was tried before giving up. */
+    readonly evadeAttempted: boolean;
+    /**
+     * Resolved element + coordinates at the failed action. Present when this is
+     * the thrown top-level error; undefined when nested inside another error.
+     */
+    readonly result?: ElementResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        occluder?: OccluderInfo;
+        evadeAttempted?: boolean;
+        result?: ElementResult;
+    });
+}
+/**
+ * FillError is thrown by {@link CloudBrowser.fill} when the field could not be
+ * focused/typed. Fill focuses with the exact same smart click as
+ * {@link CloudBrowser.click}, so a pre-typing failure is a click failure:
+ * `code` mirrors it and the full click diagnostics live under `clickError`.
+ */
+export declare class FillError extends BrowserScaleError {
+    /** Mirrored from the underlying click failure. */
+    readonly code: string;
+    /** The underlying click-core failure that prevented focusing/typing. */
+    readonly clickError?: ClickError;
+    /** Resolved element + coordinates at the failed action (success is false). */
+    readonly result: ElementResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        clickError?: ClickError;
+        result: ElementResult;
+    });
+}
+/**
+ * DragError is thrown by {@link CloudBrowser.dragBy} / {@link CloudBrowser.dragTo}
+ * when the source element could not be acquired/pressed. Drag picks up the
+ * source with the same smart click as {@link CloudBrowser.click}, so a pre-drag
+ * failure is a click failure: `code` mirrors it and the full click diagnostics
+ * live under `clickError`.
+ */
+export declare class DragError extends BrowserScaleError {
+    readonly code: string;
+    readonly clickError?: ClickError;
+    /** Resolved source + coordinates at the failed drag (success is false). */
+    readonly result: DragResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        clickError?: ClickError;
+        result: DragResult;
+    });
+}
+/**
+ * ScrollError is thrown by {@link CloudBrowser.scrollTo} when the target could
+ * not be located/scrolled.
+ */
+export declare class ScrollError extends BrowserScaleError {
+    /** Currently always `"not_found"`. */
+    readonly code: string;
+    readonly result: ElementResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        result: ElementResult;
+    });
+}
+/**
+ * MoveError is thrown by {@link CloudBrowser.moveTo} when the target could not
+ * be located. A move has no occlusion notion, so this is the only semantic
+ * failure.
+ */
+export declare class MoveError extends BrowserScaleError {
+    /** Currently always `"not_found"`. */
+    readonly code: string;
+    readonly result: ElementResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        result: ElementResult;
+    });
+}
+/**
+ * SelectOptionError is thrown by the {@link CloudBrowser.selectByIndex} /
+ * `selectByValue` / `selectByText` calls when the option could not be selected.
+ * selectOption is programmatic (no pointer gate), so it only reports semantic
+ * failures.
+ */
+export declare class SelectOptionError extends BrowserScaleError {
+    /**
+     * `"not_found"` (the `<select>` was not located) or `"option_not_found"` (no
+     * option matched the requested index/value/text).
+     */
+    readonly code: string;
+    readonly result: SelectOptionResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        result: SelectOptionResult;
+    });
+}
+/**
+ * WaitError is thrown by {@link CloudBrowser.wait} / {@link CloudBrowser.waitAny}
+ * when no condition matched before the deadline. `conditions` holds the
+ * per-condition breakdown (same order/length as the conditions passed in)
+ * explaining why each one never matched.
+ */
+export declare class WaitError extends BrowserScaleError {
+    /** Machine-stable failure code, currently always `"timeout"`. */
+    readonly code: string;
+    /** Per-condition status, same order/length as the conditions passed to wait. */
+    readonly conditions: WaitConditionStatus[];
+    /** The partial wait result (index is -1 on timeout). */
+    readonly result: WaitResult;
+    constructor(init: {
+        code: string;
+        message: string;
+        conditions: WaitConditionStatus[];
+        result: WaitResult;
+    });
+}