browserscale-ts 1.1.0 → 1.2.0

package/dist/client.d.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);

package/dist/client.js

@@ -5,7 +5,7 @@ import { Browser,
 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

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;
+    });
+}

package/dist/errors.js

@@ -1,15 +1,22 @@
 /**
- * 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 class BrowserScaleError extends Error {
@@ -19,3 +26,112 @@ export class BrowserScaleError extends Error {
         this.name = "BrowserScaleError";
     }
 }
+/**
+ * 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 class ClickError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("click", init.code, init.message));
+        this.name = "ClickError";
+        this.code = init.code;
+        this.occluder = init.occluder;
+        this.evadeAttempted = init.evadeAttempted ?? false;
+        this.result = init.result;
+    }
+}
+/**
+ * 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 class FillError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("fill", init.code, init.message));
+        this.name = "FillError";
+        this.code = init.code;
+        this.clickError = init.clickError;
+        this.result = init.result;
+    }
+}
+/**
+ * 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 class DragError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("drag", init.code, init.message));
+        this.name = "DragError";
+        this.code = init.code;
+        this.clickError = init.clickError;
+        this.result = init.result;
+    }
+}
+/**
+ * ScrollError is thrown by {@link CloudBrowser.scrollTo} when the target could
+ * not be located/scrolled.
+ */
+export class ScrollError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("scrollTo", init.code, init.message));
+        this.name = "ScrollError";
+        this.code = init.code;
+        this.result = init.result;
+    }
+}
+/**
+ * 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 class MoveError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("moveTo", init.code, init.message));
+        this.name = "MoveError";
+        this.code = init.code;
+        this.result = init.result;
+    }
+}
+/**
+ * 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 class SelectOptionError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("selectOption", init.code, init.message));
+        this.name = "SelectOptionError";
+        this.code = init.code;
+        this.result = init.result;
+    }
+}
+/**
+ * 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 class WaitError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage("wait", init.code, init.message));
+        this.name = "WaitError";
+        this.code = init.code;
+        this.conditions = init.conditions;
+        this.result = init.result;
+    }
+}
+function formatMessage(action, code, message) {
+    const base = `${action} failed: ${code}`;
+    return message ? `${base}: ${message}` : base;
+}