browserscale-ts 1.7.0 → 1.8.0

package/dist/defaults.d.ts

@@ -1,19 +1,21 @@
 /**
- * Default timeout (ms) used by wait() / waitAny() when no opts.timeoutMs
+ * Timeout (ms) the API applies to wait() / waitAny() when no opts.timeoutMs
  * is passed.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export declare const DefaultWaitTimeoutMs = 30000;
 /**
- * Default visibility flag baked into css(...) and js(...). For JS
- * expressions returning a non-Element value (boolean, string, number,
- * plain object) this flag is a no-op. Use .visible(false) on the returned
- * Locator to opt out.
+ * Visibility requirement the API applies to a wait condition that does not set
+ * one. Use .visible(false) on a Locator to wait for DOM presence alone.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export declare const DefaultVisible = true;
 /**
- * Default steady-time (ms) baked into css(...) and js(...). For JS
- * expressions returning a non-Element value this is a no-op. Use
- * .steady(ms) (or .steady(0) to disable) on the returned Locator to
- * override.
+ * Steady-time (ms) the API applies to a wait condition that does not set one.
+ * Use .steady(0) on a Locator to match the instant the element is found.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export declare const DefaultSteadyMs = 500;

package/dist/defaults.js

@@ -1,22 +1,25 @@
-// Defaults the SDK applies automatically before sending a request. Any
-// field not listed here is left unset on the wire and follows the browserscale API's
-// server-side default.
+// The SDK no longer applies its own defaults: every optional field is left
+// unset on the wire and the browserscale API supplies the default, so there is
+// one place that defines them. The constants below record the current
+// server-side values for reference and are kept only for compatibility.
 /**
- * Default timeout (ms) used by wait() / waitAny() when no opts.timeoutMs
+ * Timeout (ms) the API applies to wait() / waitAny() when no opts.timeoutMs
  * is passed.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export const DefaultWaitTimeoutMs = 30000;
 /**
- * Default visibility flag baked into css(...) and js(...). For JS
- * expressions returning a non-Element value (boolean, string, number,
- * plain object) this flag is a no-op. Use .visible(false) on the returned
- * Locator to opt out.
+ * Visibility requirement the API applies to a wait condition that does not set
+ * one. Use .visible(false) on a Locator to wait for DOM presence alone.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export const DefaultVisible = true;
 /**
- * Default steady-time (ms) baked into css(...) and js(...). For JS
- * expressions returning a non-Element value this is a no-op. Use
- * .steady(ms) (or .steady(0) to disable) on the returned Locator to
- * override.
+ * Steady-time (ms) the API applies to a wait condition that does not set one.
+ * Use .steady(0) on a Locator to match the instant the element is found.
+ *
+ * @deprecated The API owns this value; the SDK no longer sends it.
  */
 export const DefaultSteadyMs = 500;

package/dist/dom-mirror.d.ts

@@ -195,6 +195,14 @@ export declare class DomMirror {
      * boundary was crossed; it is a child list like any other.
      *
      * @param depth levels below the node, default 1
+     *
+     * @throws not_mirrored - the page has no mirror, or the node's frame is not
+     *   part of the one it has; 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
      */
     expand(node: DomNode, depth?: number): Promise<void>;
     /**
@@ -204,6 +212,13 @@ export declare class DomMirror {
      *
      * Skipping this is not an error, it is a slow leak: the browser's revealed
      * set only grows, and eventually it is no longer filtering anything.
+     *
+     * @throws not_mirrored - the page has no mirror, or the node's frame is not
+     *   part of the one it has; this is what collapsing a node 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
      */
     collapse(node: DomNode): Promise<void>;
     /**
@@ -220,12 +235,24 @@ export declare class DomMirror {
      *
      * @returns the ancestor chain, the main document first, or an empty array if
      *   the node is not on the page
+     *
+     * @throws not_mirrored - the page has no mirror, or the given frame 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
      */
     reveal(backendNodeId: number, frameId?: string): Promise<DomNode[]>;
     /**
      * Throws away the local copy of the whole page and fetches a fresh one.
      * Happens automatically whenever the browser says the copy is void, so you
      * rarely need to call it.
+     *
+     * @throws mirror_failed - the page could not be serialized, usually a document
+     *   that went away while the tree was being rebuilt. The mirror then ends
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     resync(reason?: DomResyncReason): Promise<void>;
     /** Resolves once the mirror ends — stop(), a dead session, a transport failure. */

package/dist/dom-mirror.js

@@ -130,6 +130,14 @@ export class DomMirror {
      * boundary was crossed; it is a child list like any other.
      *
      * @param depth levels below the node, default 1
+     *
+     * @throws not_mirrored - the page has no mirror, or the node's frame is not
+     *   part of the one it has; 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 expand(node, depth) {
         if (this.stopped)
@@ -157,6 +165,13 @@ export class DomMirror {
      *
      * Skipping this is not an error, it is a slow leak: the browser's revealed
      * set only grows, and eventually it is no longer filtering anything.
+     *
+     * @throws not_mirrored - the page has no mirror, or the node's frame is not
+     *   part of the one it has; this is what collapsing a node 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 collapse(node) {
         if (this.stopped)
@@ -185,6 +200,13 @@ export class DomMirror {
      *
      * @returns the ancestor chain, the main document first, or an empty array if
      *   the node is not on the page
+     *
+     * @throws not_mirrored - the page has no mirror, or the given frame 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 reveal(backendNodeId, frameId) {
         if (this.stopped)
@@ -236,6 +258,11 @@ export class DomMirror {
      * Throws away the local copy of the whole page and fetches a fresh one.
      * Happens automatically whenever the browser says the copy is void, so you
      * rarely need to call it.
+     *
+     * @throws mirror_failed - the page could not be serialized, usually a document
+     *   that went away while the tree was being rebuilt. The mirror then ends
+     *
+     * @see {@link CommandError} for reading the code off the rejection
      */
     async resync(reason = "manual") {
         if (this.stopped)

package/dist/errors.d.ts

@@ -24,6 +24,49 @@ export declare class BrowserScaleError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/**
+ * CommandError is thrown when the browser carried out a command correctly but
+ * the page would not go along with it. It is the error for the commands that
+ * have nothing to report beyond what went wrong; the richer failures have their
+ * own class ({@link ClickError}, {@link FillError}, {@link DragError}) carrying
+ * the same `code` plus their own detail.
+ *
+ * It never reports an outage. A dead session, a closed page or a malformed call
+ * arrive as a plain {@link BrowserScaleError} instead, so narrowing to this
+ * class tells you the fault is in the page or in what you asked of it — which is
+ * the difference between retrying and fixing your code.
+ *
+ *   try {
+ *     await browser.evaluate("window.__ready === true");
+ *   } catch (e) {
+ *     if (e instanceof CommandError && e.code === "threw") {
+ *       // the expression itself is broken; e.message has the exception text
+ *     }
+ *   }
+ */
+/**
+ * Raises the optional error of a uniform result, and does nothing when the
+ * command succeeded — so a call site stays one line instead of an if.
+ */
+export declare function throwCommandError(command: string, error?: {
+    code: string;
+    message: string;
+}): void;
+export declare class CommandError extends BrowserScaleError {
+    /** The call that failed, e.g. `"evaluate"`. */
+    readonly command: string;
+    /**
+     * Machine-stable and lowercase, and scoped to `command`: the same string can
+     * mean different things for different commands, so narrow on it together with
+     * the call you made.
+     */
+    readonly code: string;
+    constructor(init: {
+        command: string;
+        code: string;
+        message: string;
+    });
+}
 /**
  * ClickError is thrown by {@link CloudBrowser.click} when the click did not
  * land — the target was found but another element covered the intended point.

package/dist/errors.js

@@ -26,6 +26,43 @@ export class BrowserScaleError extends Error {
         this.name = "BrowserScaleError";
     }
 }
+/**
+ * CommandError is thrown when the browser carried out a command correctly but
+ * the page would not go along with it. It is the error for the commands that
+ * have nothing to report beyond what went wrong; the richer failures have their
+ * own class ({@link ClickError}, {@link FillError}, {@link DragError}) carrying
+ * the same `code` plus their own detail.
+ *
+ * It never reports an outage. A dead session, a closed page or a malformed call
+ * arrive as a plain {@link BrowserScaleError} instead, so narrowing to this
+ * class tells you the fault is in the page or in what you asked of it — which is
+ * the difference between retrying and fixing your code.
+ *
+ *   try {
+ *     await browser.evaluate("window.__ready === true");
+ *   } catch (e) {
+ *     if (e instanceof CommandError && e.code === "threw") {
+ *       // the expression itself is broken; e.message has the exception text
+ *     }
+ *   }
+ */
+/**
+ * Raises the optional error of a uniform result, and does nothing when the
+ * command succeeded — so a call site stays one line instead of an if.
+ */
+export function throwCommandError(command, error) {
+    if (error) {
+        throw new CommandError({ command, code: error.code, message: error.message });
+    }
+}
+export class CommandError extends BrowserScaleError {
+    constructor(init) {
+        super(formatMessage(init.command, init.code, init.message));
+        this.name = "CommandError";
+        this.command = init.command;
+        this.code = init.code;
+    }
+}
 /**
  * ClickError is thrown by {@link CloudBrowser.click} when the click did not
  * land — the target was found but another element covered the intended point.